From 4681c2b320c201ae8c5c1c0b531880819fcdf088 Mon Sep 17 00:00:00 2001 From: William Robertson Date: Fri, 20 Jun 2025 10:53:03 -0400 Subject: [PATCH 1/4] work --- sui/README.md | 42 +++++++++++++++++++ sui/caip2.md | 114 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 156 insertions(+) create mode 100644 sui/README.md create mode 100644 sui/caip2.md diff --git a/sui/README.md b/sui/README.md new file mode 100644 index 0000000..563bb7c --- /dev/null +++ b/sui/README.md @@ -0,0 +1,42 @@ +--- +namespace-identifier: sui +title: Sui Ecosystem +author: William Robertson (@williamrobertson13) +discussions-to: https://github.com/ChainAgnostic/namespaces/pull/146 +status: Draft +type: Informational +created: 2025-06-18 +updated: 2025-06-18 +--- + +# Namespace for Sui Chains + +Sui is a smart contract platform that uses a Move-based, object-centric data model and is optimized for parallel execution. Transactions in Sui operate on objects rather than accounts, allowing independent operations to be executed in parallel without coordination. This enables high throughput while preserving safety and determinism. + +A Sui network is maintained by a validator committee responsible for processing transactions, reaching consensus, and producing checkpoint digests — cryptographic summaries of network state at fixed intervals. These checkpoints serve as the canonical state and ensure consistency across nodes. + +Each network is uniquely identified by its genesis checkpoint digest — the cryptographic hash of the very first checkpoint, signed by the original validator set. This digest anchors the network’s identity in verifiable history and validator consensus. + +## Rationale + +Because chain identity and state in Sui revolve around checkpoints and objects rather than blocks and accounts, standard CAIP identifiers (e.g., for chains, accounts, and assets) must be adapted accordingly. + +This namespace defines how Sui’s architecture maps to cross-chain standards to support consistent and interoperable multi-chain tooling. + +## Governance + +Sui protocol upgrades and standards are coordinated by the Sui Foundation in collaboration with core contributors and the broader developer community. Changes are proposed through SIPs (Sui Improvement Proposals), with open discussion and reference implementations maintained on GitHub. + +## References + +- [Sui Docs] — Developer documentation and concept overviews for building on Sui. +- [Sui GitHub] — Official GitHub repository for the Sui smart contract platform. +- [Sui SIPs] — Official GitHub repository for Sui Improvement Proposals. + +[Sui Docs]: https://docs.sui.io/ +[Sui GitHub]: https://github.com/MystenLabs/sui +[Sui SIPs]: https://github.com/sui-foundation/sips + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). diff --git a/sui/caip2.md b/sui/caip2.md new file mode 100644 index 0000000..a350016 --- /dev/null +++ b/sui/caip2.md @@ -0,0 +1,114 @@ +--- +namespace-identifier: sui-caip2 +title: Sui Namespace - Chains +author: William Robertson (@williamrobertson13) +discussions-to: https://github.com/ChainAgnostic/namespaces/pull/146 +status: Draft +type: Informational +created: 2025-06-18 +updated: 2025-06-18 +--- + +# CAIP-2 + +_For context, see the [CAIP-2][] specification._ + +## Introduction + +The Sui namespace in CAIP-2 defines chain identifiers based on the **genesis checkpoint digest**, a cryptographically unique and immutable value derived from the first checkpoint of a Sui network. This ensures that identifiers are stable, verifiable, and unambiguous. + +## Specification + +### Semantics + +A valid CAIP-2 identifier in the Sui namespace takes the form: + +``` +sui: +``` + +Where `` is the first 4 bytes (8 hex characters) of the network’s genesis checkpoint digest. + +### Syntax + +#### Regular Expression + +``` +^sui:[0-9a-fA-F]{8}$ +``` + +#### Example + +``` +sui:35834a8a +``` + +### Resolution Mechanics + +To resolve a CAIP-2 chain identifier, clients query a trusted full node associated with the specified network. While the `suix_getChainIdentifier` JSON-RPC method is commonly used for this purpose, resolution is not limited to JSON-RPC. Other interfaces, such as GraphQL, may also support retrieving the corresponding genesis checkpoint digest. + +**Sample request:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "suix_getChainIdentifier", + "params": [] +} +``` + +**Sample response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "35834a8a" +} +``` + +## Rationale + +This approach advocates for the exclusive use of unambiguous chain identifiers for identifying Sui chains in CAIP-2 format. + +While human-readable identifiers like `sui:mainnet` or `sui:testnet` are intuitive, they are not stable over time. Networks like testnet and devnet may be reset by Sui maintainers, resulting in a new genesis state. When this happens, the associated digest changes, meaning the underlying chain is no longer the same, even if the CAIP-2 identifier remains unchanged. + +Using the digest-based identifier directly avoids this ambiguity by ensuring all references point to a specific, verifiable chain instance. This eliminates reliance on potentially outdated or re-used labels and simplifies validation logic. + +By relying solely on unambiguous identifiers, we prioritize long-term compatibility, security, and correctness. This ensures that clients consistently interact with the intended chain, even as network environments evolve. + +### Backwards Compatibility + +There are no legacy identifiers or alternate forms for Sui chains. + +## Test Cases + +Below are manually composed examples: + +``` +# CAIP-2 Chain ID for Mainnet** +sui:35834a8a + +# CAIP-2 Chain ID for Testnet** +sui:4c78adac + +# CAIP-2 Chain ID for Devnet** +sui:aba3e445 +``` + +## References + +- [Sui Docs] - Developer documentation and concept overviews for building on Sui. +- [Sui RPC] - Reference documentation for interacting with Sui networks via RPC. +- [Sui GitHub] - Official GitHub repository for the Sui smart contract platform. +- [CAIP-2] - Chain ID Specification. + +[Sui Docs]: https://docs.sui.io/ +[Sui RPC]: https://docs.sui.io/references/sui-api +[Sui GitHub]: https://github.com/MystenLabs/sui +[CAIP-2]: https://chainagnostic.org/CAIPs/caip-2 + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). From 20790d100139df88f3837eb7ac99b941110b67a8 Mon Sep 17 00:00:00 2001 From: William Robertson Date: Fri, 20 Jun 2025 11:19:54 -0400 Subject: [PATCH 2/4] add --- sui/caip2-alt-draft.md | 127 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 127 insertions(+) create mode 100644 sui/caip2-alt-draft.md diff --git a/sui/caip2-alt-draft.md b/sui/caip2-alt-draft.md new file mode 100644 index 0000000..fb666a9 --- /dev/null +++ b/sui/caip2-alt-draft.md @@ -0,0 +1,127 @@ +--- +namespace-identifier: sui-caip2 +title: Sui Namespace - Chains +author: William Robertson (@williamrobertson13) +discussions-to: https://github.com/ChainAgnostic/namespaces/pull/146 +status: Draft +type: Informational +created: 2025-06-18 +updated: 2025-06-18 +--- + +# CAIP-2 + +_For context, see the [CAIP-2][] specification._ + +## Introduction + +The Sui namespace in CAIP-2 uses human-readable chain identifiers — such as `mainnet`, `testnet`, and `devnet` — to identify specific Sui networks. These identifiers are **stable**, **concise**, and **easy to communicate**, and can be resolved to a unique genesis checkpoint digest through a supported Sui RPC interface. + +This design provides both developer ergonomics and cryptographic assurance, allowing developers to work with simple names while still supporting verifiable chain identification. + +## Specification + +### Semantics + +A valid CAIP-2 identifier in the Sui namespace takes the form: + +`sui:` + +Where `` is one of the following reserved, stable identifiers: + +- `mainnet` +- `testnet` +- `devnet` + +### Syntax + +#### Regular Expression + +`^sui:(mainnet|testnet|devnet)$` + +Only these exact network identifiers are currently supported. + +#### Example + +`sui:mainnet` + +### Resolution Mechanics + +To resolve a CAIP-2 `sui:` identifier into a unique chain identitier, clients typically query a trusted full node associated with the specified network. While the `suix_getChainIdentifier` JSON-RPC method is commonly used for this purpose, resolution is not limited to JSON-RPC. Other interfaces, such as GraphQL, may also support retrieving the corresponding genesis checkpoint digest. + +**Sample request** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "suix_getChainIdentifier", + "params": [] +} +``` + +**Sample response (for mainnet):** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "35834a8a" +} +``` + +The response returns the first four bytes of the genesis checkpoint digest for the network. + +## Rationale + +This approach allows developers to use intuitive, readable CAIP-2 identifiers (e.g., `sui:mainnet`) while still achieving unambiguous and verifiable identification of the underlying chain through the genesis checkpoint digest. + +The separation of **stable identifiers** (e.g., `sui:testnet`) from the **unambiguous chain identifier** (e.g., the identifier returned by `suix_getChainIdentifier`) is particularly important because: + +- **`testnet` and `devnet` may be reset** by Sui maintainers, resulting in a new genesis state. +- When this happens, the **genesis checkpoint digest changes**, meaning the underlying chain identifier is no longer the same. +- If clients depended directly on the digest as the CAIP-2 identifier, each reset would break compatibility or require external coordination. +- By resolving the digest dynamically via RPC, clients can ensure they’re talking to the correct chain, without needing to change the CAIP-2 identifier they rely on. + +This pattern balances human readability, forward compatibility, and security. + +### Backwards Compatibility + +There are no legacy identifiers or alternate forms for Sui chains. + +## Test Cases + +Below are manually composed examples: + +#### Sui Mainnet + +- **CAIP-2 Chain ID:** `sui:mainnet` +- **Resolved Chain Identifier:** `35834a8a` + +#### Sui Testnet + +- **CAIP-2 Chain ID:** `sui:testnet` +- **Resolved Chain Identifier:** `4c78adac` _(value depends on the current testnet)_ + +#### Sui Devnet + +- **CAIP-2 Chain ID:** `sui:devnet` +- **Resolved Chain Identifier:** `aba3e445` _(value depends on the current devnet)_ + +## References + +- [Sui Docs] - Developer documentation and concept overviews for building on Sui. +- [Sui RPC] - Reference documentation for interacting with Sui networks via RPC. +- [Sui GitHub] - Official GitHub repository for the Sui smart contract platform. +- [Sui Network Info] - Information regarding Sui networks and their release schedules. +- [CAIP-2] - Chain ID Specification. + +[Sui Docs]: https://docs.sui.io/ +[Sui RPC]: https://docs.sui.io/references/sui-api +[Sui GitHub]: https://github.com/MystenLabs/sui +[Sui Network Info]: https://sui.io/networkinfo +[CAIP-2]: https://chainagnostic.org/CAIPs/caip-2 + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). From fe4627761af1d6b192994791ea0bba45049f02d5 Mon Sep 17 00:00:00 2001 From: William Robertson Date: Fri, 20 Jun 2025 14:49:20 -0400 Subject: [PATCH 3/4] go with 2 --- sui/caip2-alt-draft.md | 127 ----------------------------------------- sui/caip2.md | 65 ++++++++++++--------- 2 files changed, 39 insertions(+), 153 deletions(-) delete mode 100644 sui/caip2-alt-draft.md diff --git a/sui/caip2-alt-draft.md b/sui/caip2-alt-draft.md deleted file mode 100644 index fb666a9..0000000 --- a/sui/caip2-alt-draft.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -namespace-identifier: sui-caip2 -title: Sui Namespace - Chains -author: William Robertson (@williamrobertson13) -discussions-to: https://github.com/ChainAgnostic/namespaces/pull/146 -status: Draft -type: Informational -created: 2025-06-18 -updated: 2025-06-18 ---- - -# CAIP-2 - -_For context, see the [CAIP-2][] specification._ - -## Introduction - -The Sui namespace in CAIP-2 uses human-readable chain identifiers — such as `mainnet`, `testnet`, and `devnet` — to identify specific Sui networks. These identifiers are **stable**, **concise**, and **easy to communicate**, and can be resolved to a unique genesis checkpoint digest through a supported Sui RPC interface. - -This design provides both developer ergonomics and cryptographic assurance, allowing developers to work with simple names while still supporting verifiable chain identification. - -## Specification - -### Semantics - -A valid CAIP-2 identifier in the Sui namespace takes the form: - -`sui:` - -Where `` is one of the following reserved, stable identifiers: - -- `mainnet` -- `testnet` -- `devnet` - -### Syntax - -#### Regular Expression - -`^sui:(mainnet|testnet|devnet)$` - -Only these exact network identifiers are currently supported. - -#### Example - -`sui:mainnet` - -### Resolution Mechanics - -To resolve a CAIP-2 `sui:` identifier into a unique chain identitier, clients typically query a trusted full node associated with the specified network. While the `suix_getChainIdentifier` JSON-RPC method is commonly used for this purpose, resolution is not limited to JSON-RPC. Other interfaces, such as GraphQL, may also support retrieving the corresponding genesis checkpoint digest. - -**Sample request** - -```json -{ - "jsonrpc": "2.0", - "id": 1, - "method": "suix_getChainIdentifier", - "params": [] -} -``` - -**Sample response (for mainnet):** - -```json -{ - "jsonrpc": "2.0", - "id": 1, - "result": "35834a8a" -} -``` - -The response returns the first four bytes of the genesis checkpoint digest for the network. - -## Rationale - -This approach allows developers to use intuitive, readable CAIP-2 identifiers (e.g., `sui:mainnet`) while still achieving unambiguous and verifiable identification of the underlying chain through the genesis checkpoint digest. - -The separation of **stable identifiers** (e.g., `sui:testnet`) from the **unambiguous chain identifier** (e.g., the identifier returned by `suix_getChainIdentifier`) is particularly important because: - -- **`testnet` and `devnet` may be reset** by Sui maintainers, resulting in a new genesis state. -- When this happens, the **genesis checkpoint digest changes**, meaning the underlying chain identifier is no longer the same. -- If clients depended directly on the digest as the CAIP-2 identifier, each reset would break compatibility or require external coordination. -- By resolving the digest dynamically via RPC, clients can ensure they’re talking to the correct chain, without needing to change the CAIP-2 identifier they rely on. - -This pattern balances human readability, forward compatibility, and security. - -### Backwards Compatibility - -There are no legacy identifiers or alternate forms for Sui chains. - -## Test Cases - -Below are manually composed examples: - -#### Sui Mainnet - -- **CAIP-2 Chain ID:** `sui:mainnet` -- **Resolved Chain Identifier:** `35834a8a` - -#### Sui Testnet - -- **CAIP-2 Chain ID:** `sui:testnet` -- **Resolved Chain Identifier:** `4c78adac` _(value depends on the current testnet)_ - -#### Sui Devnet - -- **CAIP-2 Chain ID:** `sui:devnet` -- **Resolved Chain Identifier:** `aba3e445` _(value depends on the current devnet)_ - -## References - -- [Sui Docs] - Developer documentation and concept overviews for building on Sui. -- [Sui RPC] - Reference documentation for interacting with Sui networks via RPC. -- [Sui GitHub] - Official GitHub repository for the Sui smart contract platform. -- [Sui Network Info] - Information regarding Sui networks and their release schedules. -- [CAIP-2] - Chain ID Specification. - -[Sui Docs]: https://docs.sui.io/ -[Sui RPC]: https://docs.sui.io/references/sui-api -[Sui GitHub]: https://github.com/MystenLabs/sui -[Sui Network Info]: https://sui.io/networkinfo -[CAIP-2]: https://chainagnostic.org/CAIPs/caip-2 - -## Copyright - -Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). diff --git a/sui/caip2.md b/sui/caip2.md index a350016..fb666a9 100644 --- a/sui/caip2.md +++ b/sui/caip2.md @@ -15,7 +15,9 @@ _For context, see the [CAIP-2][] specification._ ## Introduction -The Sui namespace in CAIP-2 defines chain identifiers based on the **genesis checkpoint digest**, a cryptographically unique and immutable value derived from the first checkpoint of a Sui network. This ensures that identifiers are stable, verifiable, and unambiguous. +The Sui namespace in CAIP-2 uses human-readable chain identifiers — such as `mainnet`, `testnet`, and `devnet` — to identify specific Sui networks. These identifiers are **stable**, **concise**, and **easy to communicate**, and can be resolved to a unique genesis checkpoint digest through a supported Sui RPC interface. + +This design provides both developer ergonomics and cryptographic assurance, allowing developers to work with simple names while still supporting verifiable chain identification. ## Specification @@ -23,31 +25,31 @@ The Sui namespace in CAIP-2 defines chain identifiers based on the **genesis che A valid CAIP-2 identifier in the Sui namespace takes the form: -``` -sui: -``` +`sui:` + +Where `` is one of the following reserved, stable identifiers: -Where `` is the first 4 bytes (8 hex characters) of the network’s genesis checkpoint digest. +- `mainnet` +- `testnet` +- `devnet` ### Syntax #### Regular Expression -``` -^sui:[0-9a-fA-F]{8}$ -``` +`^sui:(mainnet|testnet|devnet)$` + +Only these exact network identifiers are currently supported. #### Example -``` -sui:35834a8a -``` +`sui:mainnet` ### Resolution Mechanics -To resolve a CAIP-2 chain identifier, clients query a trusted full node associated with the specified network. While the `suix_getChainIdentifier` JSON-RPC method is commonly used for this purpose, resolution is not limited to JSON-RPC. Other interfaces, such as GraphQL, may also support retrieving the corresponding genesis checkpoint digest. +To resolve a CAIP-2 `sui:` identifier into a unique chain identitier, clients typically query a trusted full node associated with the specified network. While the `suix_getChainIdentifier` JSON-RPC method is commonly used for this purpose, resolution is not limited to JSON-RPC. Other interfaces, such as GraphQL, may also support retrieving the corresponding genesis checkpoint digest. -**Sample request:** +**Sample request** ```json { @@ -58,7 +60,7 @@ To resolve a CAIP-2 chain identifier, clients query a trusted full node associat } ``` -**Sample response:** +**Sample response (for mainnet):** ```json { @@ -68,15 +70,20 @@ To resolve a CAIP-2 chain identifier, clients query a trusted full node associat } ``` +The response returns the first four bytes of the genesis checkpoint digest for the network. + ## Rationale -This approach advocates for the exclusive use of unambiguous chain identifiers for identifying Sui chains in CAIP-2 format. +This approach allows developers to use intuitive, readable CAIP-2 identifiers (e.g., `sui:mainnet`) while still achieving unambiguous and verifiable identification of the underlying chain through the genesis checkpoint digest. -While human-readable identifiers like `sui:mainnet` or `sui:testnet` are intuitive, they are not stable over time. Networks like testnet and devnet may be reset by Sui maintainers, resulting in a new genesis state. When this happens, the associated digest changes, meaning the underlying chain is no longer the same, even if the CAIP-2 identifier remains unchanged. +The separation of **stable identifiers** (e.g., `sui:testnet`) from the **unambiguous chain identifier** (e.g., the identifier returned by `suix_getChainIdentifier`) is particularly important because: -Using the digest-based identifier directly avoids this ambiguity by ensuring all references point to a specific, verifiable chain instance. This eliminates reliance on potentially outdated or re-used labels and simplifies validation logic. +- **`testnet` and `devnet` may be reset** by Sui maintainers, resulting in a new genesis state. +- When this happens, the **genesis checkpoint digest changes**, meaning the underlying chain identifier is no longer the same. +- If clients depended directly on the digest as the CAIP-2 identifier, each reset would break compatibility or require external coordination. +- By resolving the digest dynamically via RPC, clients can ensure they’re talking to the correct chain, without needing to change the CAIP-2 identifier they rely on. -By relying solely on unambiguous identifiers, we prioritize long-term compatibility, security, and correctness. This ensures that clients consistently interact with the intended chain, even as network environments evolve. +This pattern balances human readability, forward compatibility, and security. ### Backwards Compatibility @@ -86,27 +93,33 @@ There are no legacy identifiers or alternate forms for Sui chains. Below are manually composed examples: -``` -# CAIP-2 Chain ID for Mainnet** -sui:35834a8a +#### Sui Mainnet -# CAIP-2 Chain ID for Testnet** -sui:4c78adac +- **CAIP-2 Chain ID:** `sui:mainnet` +- **Resolved Chain Identifier:** `35834a8a` -# CAIP-2 Chain ID for Devnet** -sui:aba3e445 -``` +#### Sui Testnet + +- **CAIP-2 Chain ID:** `sui:testnet` +- **Resolved Chain Identifier:** `4c78adac` _(value depends on the current testnet)_ + +#### Sui Devnet + +- **CAIP-2 Chain ID:** `sui:devnet` +- **Resolved Chain Identifier:** `aba3e445` _(value depends on the current devnet)_ ## References - [Sui Docs] - Developer documentation and concept overviews for building on Sui. - [Sui RPC] - Reference documentation for interacting with Sui networks via RPC. - [Sui GitHub] - Official GitHub repository for the Sui smart contract platform. +- [Sui Network Info] - Information regarding Sui networks and their release schedules. - [CAIP-2] - Chain ID Specification. [Sui Docs]: https://docs.sui.io/ [Sui RPC]: https://docs.sui.io/references/sui-api [Sui GitHub]: https://github.com/MystenLabs/sui +[Sui Network Info]: https://sui.io/networkinfo [CAIP-2]: https://chainagnostic.org/CAIPs/caip-2 ## Copyright From d430a98861e62366f6cbdbdf9be1fbe6a05faa1b Mon Sep 17 00:00:00 2001 From: Bumblefudge Date: Wed, 2 Jul 2025 09:12:25 +0200 Subject: [PATCH 4/4] Update sui/caip2.md --- sui/caip2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sui/caip2.md b/sui/caip2.md index fb666a9..cd586ee 100644 --- a/sui/caip2.md +++ b/sui/caip2.md @@ -47,7 +47,7 @@ Only these exact network identifiers are currently supported. ### Resolution Mechanics -To resolve a CAIP-2 `sui:` identifier into a unique chain identitier, clients typically query a trusted full node associated with the specified network. While the `suix_getChainIdentifier` JSON-RPC method is commonly used for this purpose, resolution is not limited to JSON-RPC. Other interfaces, such as GraphQL, may also support retrieving the corresponding genesis checkpoint digest. +To resolve a CAIP-2 `sui:` identifier into a unique chain identitier, clients typically query a trusted full node associated with the specified network. While the `suix_getChainIdentifier` JSON-RPC method is commonly used for this purpose, resolution is not limited to JSON-RPC. Other node interfaces, such as GraphQL, may also support retrieving identifiers pertinent to locating records, such as a genesis checkpoint digest unique to each chain. **Sample request**