From e27ad300a10fd4557751f2c1bf741ec7f919849c Mon Sep 17 00:00:00 2001 From: Marc Juchli Date: Sun, 23 Aug 2026 13:40:17 +0200 Subject: [PATCH 1/5] Add Canton Namespace --- canton/caip10.md | 53 ++++++++++++++++++++++++++++++++++++ canton/caip19.md | 68 ++++++++++++++++++++++++++++++++++++++++++++++ canton/caip2.md | 71 ++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 192 insertions(+) create mode 100644 canton/caip10.md create mode 100644 canton/caip19.md create mode 100644 canton/caip2.md diff --git a/canton/caip10.md b/canton/caip10.md new file mode 100644 index 0000000..f0a811b --- /dev/null +++ b/canton/caip10.md @@ -0,0 +1,53 @@ +--- +namespace-identifier: canton-caip10 +title: Canton Namespace - Addresses +author: Marc Juchli (@mjuchli-da) +discussions-to: https://github.com/ChainAgnostic/namespaces/pulls +status: Draft +type: Standard +created: 2026-08-21 +requires: ["CAIP-2", "CAIP-10"] +--- + +# CAIP-10 + +For context, see the [CAIP-10](https://chainagnostic.org/CAIPs/caip-10) specification. + +## Syntax + +CAIP‑10 defines `account_id` as `{chain_id}:{account_address}` +- `chain_id` the [CAIP2 Canton ID](./caip2.md) +- `account_address` the user or entity address on that chain (`[-.%a-zA-Z0-9]{1,128}`). + +The `account_address` is derived from the canonical textual representation of a Canton Party ID. A Canton Party ID has the following canonical form: +``` +{partyHint}::{partyNamespace} +``` + +As the `:` character is not permitted in the CAIP-10 account_address, the canonical Party ID is percent-encoded before being embedded in the CAIP-10 identifier. The resulting format is: +``` +canton:{networkIdentifier}:{partyHint}%3A%3A{partyNamespace} +``` + +Examples: +``` +canton:mainnet:alice%3A%3A123abc... +canton:testnet:bob%3A%3A1220def... +``` + +The percent-encoded value preserves the canonical Party ID and can be decoded by implementations using standard percent-decoding. This approach ensures compliance with the CAIP-10 grammar while preserving Canton's existing Party ID semantics and avoiding the introduction of a new account address format. + +## Limitations + +The `account_address` lenght **MUST** be <= 128 characters. The party namespace takes 64 characters, the url encoded colons 4 characters, the `canton:` prefix 7 characters, and thus leaving 53 characters for the `{networkIdentifier}:{partyHint}`. + +In the case of `networkIdentifier` being `da-mainnet`, the party hint must be <= 43 characters. + + +## References + +- [Canton Core Concepts](https://docs.canton.network/overview/understand/core-concepts#party-identifier-format): Party identifier format + +## Rights + +Copyright and related rights waived via CC0. diff --git a/canton/caip19.md b/canton/caip19.md new file mode 100644 index 0000000..9c9aa0e --- /dev/null +++ b/canton/caip19.md @@ -0,0 +1,68 @@ +--- +namespace-identifier: canton-caip19 +title: Canton Namespace - Assets +author: Marc Juchli (@mjuchli-da) +discussions-to: https://github.com/ChainAgnostic/namespaces/pulls +status: Draft +type: Standard +created: 2026-08-21 +requires: ["CAIP-2", "CAIP-19"] +--- + +# CAIP-19 + +For context, see the [CAIP-19](https://chainagnostic.org/CAIPs/caip-19) specification. + + +## Syntax + +The Canton ecosystem defines a standardized token representation through CIP-0056. To enable interoperability with chain-agnostic tooling, Canton assets are identified using the CAIP-19 asset identification format. + +The `asset type` follows `chain_id + "/" + asset_namespace + ":" + asset_reference`, whereas: +- `chain_id` is the Canton CAIP-2 +- `asset_namespace` identifies the asset identification scheme (`[-a-z0-9]{3,8}`) +- `asset_reference` identifies the asset within that scheme (`[-.%a-zA-Z0-9]{1,128}`) +- `token_id`: Optional asset identifer (`[-.%a-zA-Z0-9]{1,78}`) + +### Assets with SLIP-44 + +For assets with a SLIP-44 registered coin type, such as `CC` with `6767`, the format is: +``` +chain_id = canton:{networkIdentifier} // CAIP-2 +asset_namespace = slip44 +asset_reference = 6767 // CC +asset_type = canton:{networkIdentifier}/slip44:6767 +``` + +Hence, for `CC` on `mainnet`, the `asset_type` is `canton:mainnet/slip44:6767`. + + +### Assets without SLIP-44 + +For CIP-0056 assets without a SLIP-44 coin type leveraging optional Asset ID (identified by `token_id` for fungibles): +``` +chain_id = canton:{synchronizer} // see CAIP-2 +asset_namespace = cip-0056 +asset_reference = percentEncode({instrumentId.admin}) +token_id = percentEncode({instrumentId.id}) + +asset_type = canton:mainnet/cip-0056:{instrumentId.admin}/{token_id} +``` + +For Example: +``` +canton:mainnet/cip-0056:decentralized-usdc-interchain-rep%3A%3A12208115f1e168dd7e792320be9c4ca720c751a02a3053c7606e1c1cd3dad9bf60ef/USDCx +``` + +**Note:** CAIP-19 defines a maximum length of 78 characters for the optional `token_id` component. The compatibility of this mapping depends on the serialized length of the corresponding Canton `instrumentId.id` value after any required encoding. Implementations **MUST** ensure that the resulting token_id complies with the CAIP-19 length constraint. + + +## References + +- [Canton CAIP-2](./caip2.md): Canton chain identifier profile +- [CIP-0056](https://github.com/canton-foundation/cips/blob/main/cip-0056/cip-0056): Canton token standard +- [SLIP-44](https://github.com/satoshilabs/slips/blob/master/slip-0044.md): Registered coin types + +## Rights + +Copyright and related rights waived via CC0. diff --git a/canton/caip2.md b/canton/caip2.md new file mode 100644 index 0000000..7ebedaf --- /dev/null +++ b/canton/caip2.md @@ -0,0 +1,71 @@ +--- +namespace-identifier: canton-caip2 +title: Canton Namespace - Chains +author: Marc Juchli (@mjuchli-da) +discussions-to: https://github.com/ChainAgnostic/namespaces/pulls +status: Draft +type: Standard +created: 2026-08-21 +requires: CAIP-2 +--- + +# CAIP-2 + +For context, see the [CAIP-2](https://chainagnostic.org/CAIPs/caip-2) specification. + + +## Syntax + +CAIP‑2 identifiers follow: + +``` +chain_id: namespace + ":" + reference +namespace: [-a-z0-9]{3,8} +reference: [-_a-zA-Z0-9]{1,32} +``` + +CAIP-2 constrains the blockchain reference component to a maximum length of 32 characters and restricts the set of permitted characters. As Canton Synchronizer identifiers do not conform to these constraints, they cannot be used directly as CAIP-2 blockchain identifiers. + +### Namespace + +The namespace is set to `canton`. + +### Reference + +To provide a compliant and stable `reference`, Canton Synchronizer IDs **MUST** define a unique network identifier (alias) that satisfies the CAIP-2 reference requirements. This identifier serves as the blockchain reference in the CAIP-2 chain identifier and **MUST** uniquely resolve to the corresponding Synchronizer. + +The mapping between a network identifier and its Synchronizer identifier **MUST** be deterministic and authoritative, ensuring that all implementations resolve the same CAIP-2 identifier to the same Canton network. + +### Global synchronizers + +The `chain_id` for the well known global synchronizers are: + +``` +canton:mainnet # Global Synchronizer MainNet +canton:testnet # Global Synchronizer TestNet +canton:devnet # Global Synchronizer DevNet +``` + +See reference below for exact `domainId` values. + +### Other synchronizers + +Additional aliases **MAY** be proposed and **MUST** use one of the following formats: + +``` +canton:private-name # Private domainId, eg. sync::1220f5d7... + +// Prefix to indicate a network extension +canton:{mainnet|testnet|devnet}/private-name +``` + +This approach provides human-readable, interoperable identifiers while decoupling the CAIP representation from Canton's internal identifier format and remaining compatible with future network evolution. + +## References + +- [The Global Synchronizer](https://docs.canton.network/overview/understand/global-synchronizer#network-environments): DevNet, TestNet, and MainNet environments +- [Scan Global Synchronizer Connectivity API](https://docs.canton.network/sdks-tools/api-reference/splice-scan-gs-connectivity-api): Current synchronizer IDs (`domainId`) for each network + +## Rights + +Copyright and related rights waived via CC0. From fce8318fe97f65b4b572f216b479cd030ff32cf6 Mon Sep 17 00:00:00 2001 From: Marc Juchli Date: Sun, 23 Aug 2026 13:43:38 +0200 Subject: [PATCH 2/5] update PR links --- canton/caip10.md | 2 +- canton/caip19.md | 2 +- canton/caip2.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/canton/caip10.md b/canton/caip10.md index f0a811b..00e59d5 100644 --- a/canton/caip10.md +++ b/canton/caip10.md @@ -2,7 +2,7 @@ namespace-identifier: canton-caip10 title: Canton Namespace - Addresses author: Marc Juchli (@mjuchli-da) -discussions-to: https://github.com/ChainAgnostic/namespaces/pulls +discussions-to: https://github.com/ChainAgnostic/namespaces/pull/201 status: Draft type: Standard created: 2026-08-21 diff --git a/canton/caip19.md b/canton/caip19.md index 9c9aa0e..aff0969 100644 --- a/canton/caip19.md +++ b/canton/caip19.md @@ -2,7 +2,7 @@ namespace-identifier: canton-caip19 title: Canton Namespace - Assets author: Marc Juchli (@mjuchli-da) -discussions-to: https://github.com/ChainAgnostic/namespaces/pulls +discussions-to: https://github.com/ChainAgnostic/namespaces/pull/201 status: Draft type: Standard created: 2026-08-21 diff --git a/canton/caip2.md b/canton/caip2.md index 7ebedaf..af023e1 100644 --- a/canton/caip2.md +++ b/canton/caip2.md @@ -2,7 +2,7 @@ namespace-identifier: canton-caip2 title: Canton Namespace - Chains author: Marc Juchli (@mjuchli-da) -discussions-to: https://github.com/ChainAgnostic/namespaces/pulls +discussions-to: https://github.com/ChainAgnostic/namespaces/pull/201 status: Draft type: Standard created: 2026-08-21 From 520b755305d00eb4a35420c9f119a673d82b03cd Mon Sep 17 00:00:00 2001 From: Marc Juchli Date: Mon, 24 Aug 2026 09:57:57 +0200 Subject: [PATCH 3/5] add readme; co-author; and some minor tweaks --- canton/README.md | 22 ++++++++++++++++++++++ canton/caip10.md | 6 +++++- canton/caip19.md | 2 +- canton/caip2.md | 7 ++----- 4 files changed, 30 insertions(+), 7 deletions(-) create mode 100644 canton/README.md diff --git a/canton/README.md b/canton/README.md new file mode 100644 index 0000000..3b65583 --- /dev/null +++ b/canton/README.md @@ -0,0 +1,22 @@ +--- +namespace-identifier: canton +title: Canton Namespace +author: Marc Juchli (@mjuchli-da) +status: Draft +type: Informational +created: 2026-08-21 +--- + +# Namespace for Canton Network + +The prefix `canton` designates the CAIP-conformant schemata of the Canton namespace. + +## References + +- [CAIP-2](./caip-2) +- [CAIP-10](./caip-10) +- [CAIP-19](./caip-19) + +## Copyright + +Copyright and related rights waived via CC0. diff --git a/canton/caip10.md b/canton/caip10.md index 00e59d5..929bfbc 100644 --- a/canton/caip10.md +++ b/canton/caip10.md @@ -19,7 +19,9 @@ CAIP‑10 defines `account_id` as `{chain_id}:{account_address}` - `chain_id` the [CAIP2 Canton ID](./caip2.md) - `account_address` the user or entity address on that chain (`[-.%a-zA-Z0-9]{1,128}`). -The `account_address` is derived from the canonical textual representation of a Canton Party ID. A Canton Party ID has the following canonical form: +The `account_address` is derived from the canonical textual representation of a Canton Party ID. A given Party ID (e.g. `account_address`) is shared across multiple synchronizers (e.g. `chain_id`). + +A Canton Party ID has the following canonical form: ``` {partyHint}::{partyNamespace} ``` @@ -37,6 +39,8 @@ canton:testnet:bob%3A%3A1220def... The percent-encoded value preserves the canonical Party ID and can be decoded by implementations using standard percent-decoding. This approach ensures compliance with the CAIP-10 grammar while preserving Canton's existing Party ID semantics and avoiding the introduction of a new account address format. +**Note:** the same PartyId (e.g. account_address) is shared across multiple synchronizers (e.g. chain_id). + ## Limitations The `account_address` lenght **MUST** be <= 128 characters. The party namespace takes 64 characters, the url encoded colons 4 characters, the `canton:` prefix 7 characters, and thus leaving 53 characters for the `{networkIdentifier}:{partyHint}`. diff --git a/canton/caip19.md b/canton/caip19.md index aff0969..276c048 100644 --- a/canton/caip19.md +++ b/canton/caip19.md @@ -1,7 +1,7 @@ --- namespace-identifier: canton-caip19 title: Canton Namespace - Assets -author: Marc Juchli (@mjuchli-da) +author: Marc Juchli (@mjuchli-da) , Greg May (@mnrgreg) discussions-to: https://github.com/ChainAgnostic/namespaces/pull/201 status: Draft type: Standard diff --git a/canton/caip2.md b/canton/caip2.md index af023e1..e39e67e 100644 --- a/canton/caip2.md +++ b/canton/caip2.md @@ -50,13 +50,10 @@ See reference below for exact `domainId` values. ### Other synchronizers -Additional aliases **MAY** be proposed and **MUST** use one of the following formats: +Aliases for dedicated synchronizers **MAY** be proposed and **SHOULD** be prefixed with the corresponding network: ``` -canton:private-name # Private domainId, eg. sync::1220f5d7... - -// Prefix to indicate a network extension -canton:{mainnet|testnet|devnet}/private-name +canton:{mainnet|testnet|devnet}/dedicated-name ``` This approach provides human-readable, interoperable identifiers while decoupling the CAIP representation from Canton's internal identifier format and remaining compatible with future network evolution. From d0c32f5576e018277fd315034f6ef3b1d785b421 Mon Sep 17 00:00:00 2001 From: Marc Juchli Date: Mon, 24 Aug 2026 10:18:27 +0200 Subject: [PATCH 4/5] character saving --- canton/caip19.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/canton/caip19.md b/canton/caip19.md index 276c048..f30f634 100644 --- a/canton/caip19.md +++ b/canton/caip19.md @@ -42,16 +42,16 @@ Hence, for `CC` on `mainnet`, the `asset_type` is `canton:mainnet/slip44:6767`. For CIP-0056 assets without a SLIP-44 coin type leveraging optional Asset ID (identified by `token_id` for fungibles): ``` chain_id = canton:{synchronizer} // see CAIP-2 -asset_namespace = cip-0056 +asset_namespace = cip-56 asset_reference = percentEncode({instrumentId.admin}) token_id = percentEncode({instrumentId.id}) -asset_type = canton:mainnet/cip-0056:{instrumentId.admin}/{token_id} +asset_type = canton:mainnet/cip-56:{instrumentId.admin}/{token_id} ``` For Example: ``` -canton:mainnet/cip-0056:decentralized-usdc-interchain-rep%3A%3A12208115f1e168dd7e792320be9c4ca720c751a02a3053c7606e1c1cd3dad9bf60ef/USDCx +canton:mainnet/cip-56:decentralized-usdc-interchain-rep%3A%3A12208115f1e168dd7e792320be9c4ca720c751a02a3053c7606e1c1cd3dad9bf60ef/USDCx ``` **Note:** CAIP-19 defines a maximum length of 78 characters for the optional `token_id` component. The compatibility of this mapping depends on the serialized length of the corresponding Canton `instrumentId.id` value after any required encoding. Implementations **MUST** ensure that the resulting token_id complies with the CAIP-19 length constraint. From cb9010b99f40c1e85ef2ae6764408a23148b6176 Mon Sep 17 00:00:00 2001 From: Marc Juchli Date: Wed, 26 Aug 2026 15:33:26 +0200 Subject: [PATCH 5/5] address review comments --- canton/caip10.md | 6 +++--- canton/caip19.md | 25 ++++++++++++++----------- canton/caip2.md | 10 ++++++---- 3 files changed, 23 insertions(+), 18 deletions(-) diff --git a/canton/caip10.md b/canton/caip10.md index 929bfbc..4c8ecb1 100644 --- a/canton/caip10.md +++ b/canton/caip10.md @@ -33,8 +33,8 @@ canton:{networkIdentifier}:{partyHint}%3A%3A{partyNamespace} Examples: ``` -canton:mainnet:alice%3A%3A123abc... -canton:testnet:bob%3A%3A1220def... +canton:mainnet-global:alice%3A%3A123abc... +canton:testnet-global:bob%3A%3A1220def... ``` The percent-encoded value preserves the canonical Party ID and can be decoded by implementations using standard percent-decoding. This approach ensures compliance with the CAIP-10 grammar while preserving Canton's existing Party ID semantics and avoiding the introduction of a new account address format. @@ -45,7 +45,7 @@ The percent-encoded value preserves the canonical Party ID and can be decoded by The `account_address` lenght **MUST** be <= 128 characters. The party namespace takes 64 characters, the url encoded colons 4 characters, the `canton:` prefix 7 characters, and thus leaving 53 characters for the `{networkIdentifier}:{partyHint}`. -In the case of `networkIdentifier` being `da-mainnet`, the party hint must be <= 43 characters. +In the case of `networkIdentifier` being `mainnet-global`, the party hint must be <= 32 characters. ## References diff --git a/canton/caip19.md b/canton/caip19.md index f30f634..98c4cdd 100644 --- a/canton/caip19.md +++ b/canton/caip19.md @@ -22,40 +22,43 @@ The `asset type` follows `chain_id + "/" + asset_namespace + ":" + asset_referen - `chain_id` is the Canton CAIP-2 - `asset_namespace` identifies the asset identification scheme (`[-a-z0-9]{3,8}`) - `asset_reference` identifies the asset within that scheme (`[-.%a-zA-Z0-9]{1,128}`) -- `token_id`: Optional asset identifer (`[-.%a-zA-Z0-9]{1,78}`) ### Assets with SLIP-44 For assets with a SLIP-44 registered coin type, such as `CC` with `6767`, the format is: ``` -chain_id = canton:{networkIdentifier} // CAIP-2 asset_namespace = slip44 asset_reference = 6767 // CC -asset_type = canton:{networkIdentifier}/slip44:6767 +asset_type = {chain_id}/slip44:6767 ``` -Hence, for `CC` on `mainnet`, the `asset_type` is `canton:mainnet/slip44:6767`. +Hence, for `CC` on `canton:mainnet-global`, the `asset_type` is `canton:mainnet/slip44:6767`. ### Assets without SLIP-44 -For CIP-0056 assets without a SLIP-44 coin type leveraging optional Asset ID (identified by `token_id` for fungibles): +For CIP-0056 assets without a SLIP-44 coin type, we leverage CIP-0056 that identifies an instrument by an `InstrumentId`, comprising an administrating party (`admin`) and an instrument identifier (`id`). +Both components are required to identify the instrument: a single administrator **MAY** administer multiple instruments, so `admin` alone does not identify an asset. +The `asset_reference` therefore combines the two. + ``` -chain_id = canton:{synchronizer} // see CAIP-2 asset_namespace = cip-56 -asset_reference = percentEncode({instrumentId.admin}) -token_id = percentEncode({instrumentId.id}) +asset_reference = percentEncode({instrumentId.admin}) + "." + percentEncode({instrumentId.id}) -asset_type = canton:mainnet/cip-56:{instrumentId.admin}/{token_id} +asset_type = {chain_id}/cip-56:{asset_reference} ``` For Example: ``` -canton:mainnet/cip-56:decentralized-usdc-interchain-rep%3A%3A12208115f1e168dd7e792320be9c4ca720c751a02a3053c7606e1c1cd3dad9bf60ef/USDCx +canton:mainnet-global/cip-56:decentralized-usdc-interchain-rep%3A%3A12208115f1e168dd7e792320be9c4ca720c751a02a3053c7606e1c1cd3dad9bf60ef/USDCx ``` -**Note:** CAIP-19 defines a maximum length of 78 characters for the optional `token_id` component. The compatibility of this mapping depends on the serialized length of the corresponding Canton `instrumentId.id` value after any required encoding. Implementations **MUST** ensure that the resulting token_id complies with the CAIP-19 length constraint. +**Note:** CAIP-19 defines a maximum length of 128 characters for the `asset_reference` component. + A Canton party identifier of the form `{hint}::{fingerprint}` consumes 68 characters for the fingerprint, 6 for the percent-encoded `::`, and the delimiter consumes 1, leaving 53 characters to be shared between the administrator's party hint and the percent-encoded instrument identifier. + Implementations **MUST** ensure that the resulting `asset_reference` complies with the CAIP-19 length constraint. +The optional `token_id` component is not used by CIP-0056, as both InstrumentId components identify an instrument rather than an individual unit of it. +Should a per-unit identifier become necessary, `token_id` remains available for that purpose, in which case an `asset_id` follows `asset_type + "/" + token_id` ## References diff --git a/canton/caip2.md b/canton/caip2.md index e39e67e..71ea628 100644 --- a/canton/caip2.md +++ b/canton/caip2.md @@ -41,9 +41,9 @@ The mapping between a network identifier and its Synchronizer identifier **MUST* The `chain_id` for the well known global synchronizers are: ``` -canton:mainnet # Global Synchronizer MainNet -canton:testnet # Global Synchronizer TestNet -canton:devnet # Global Synchronizer DevNet +canton:mainnet-global # Global Synchronizer MainNet +canton:testnet-global # Global Synchronizer TestNet +canton:devnet-global # Global Synchronizer DevNet ``` See reference below for exact `domainId` values. @@ -53,9 +53,11 @@ See reference below for exact `domainId` values. Aliases for dedicated synchronizers **MAY** be proposed and **SHOULD** be prefixed with the corresponding network: ``` -canton:{mainnet|testnet|devnet}/dedicated-name +canton:{mainnet|testnet|devnet}-dedicated-name ``` +The complete network identifier, prefix and dedicated name together, **MUST** satisfy the CAIP-2 reference production `[-_a-zA-Z0-9]{1,32}`, leaving at most 24 characters for `{dedicated-name}`. + This approach provides human-readable, interoperable identifiers while decoupling the CAIP representation from Canton's internal identifier format and remaining compatible with future network evolution. ## References