Skip to content

Support genesis-hash network identifiers in DIDs and chain IDs - #711

Open
andynelson wants to merge 1 commit into
mainfrom
feature/did-genesis-network
Open

andynelson wants to merge 1 commit into
mainfrom
feature/did-genesis-network

Conversation

@andynelson

@andynelson andynelson commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Purpose

Chain IDs can already name a network either by name (ccd:testnet) or by genesis hash prefix (ccd:4221332d34e1694168c2a0c0b3fd0f27), but DIDs only accepted the named form (did:ccd:testnet:…). This brings DIDs in line, so any network, including a custom one, can be addressed as did:ccd:<32-hex genesis prefix>:….

Builds on Concordium/concordium-base#986 (merged); deps/concordium-base now points at that commit on main.

Compatibility

  • Existing DIDs, chain IDs and stored settings are unchanged. Named networks are still written as testnet/mainnet, and parsing did:ccd:testnet:… still gives network === 'Testnet'.
  • The genesis form is opt-in everywhere.
  • A named network and its genesis prefix count as the same chain (DIDNetwork.sameChain, matching the Rust equality in base).
  • Counterparties (wallets, verifiers) need the updated concordium-base before they accept did:ccd:<prefix>:…, so adopt per integration.

Changes

sdk

  • Network (in types.ts) is now 'Testnet' | 'Mainnet' | GenesisHashPrefix.Type.
  • New GenesisHashPrefix module in src/types/ (Type, TESTNET, MAINNET, instanceOf, fromHexString, fromGenesisHash, toHexString), following the BlockHash-style modules.
  • New networkHelpers.ts: networkToString, networkFromString, isSameNetwork, getNetworkGenesisHashPrefix, networkFromChainId, networkToChainId, getKeyDerivationNetwork.
  • Key derivation is unchanged in meaning: getKeyDerivationNetwork maps mainnet (by name or genesis prefix) to Mainnet (coin type 919) and every other network to Testnet (coin type 1). Applied in ConcordiumHdWallet and getIdProof, the only places the network reaches WASM key derivation.
  • New ConcordiumDID class in web3-id/types.ts, next to DIDString, IdentityProviderDID and ContractInstanceDID: fromJSON, toJSON and identifierOf, with a DIDIdentifier union for every DID type (acc, cred, sci, pkc, idp, encidcred). It is now the only code that builds or parses did:ccd: strings.
  • IdentityProviderDID, ContractInstanceDID, the create*DID helpers and credential metadata parsing use it. New IdentityProviderDID.fromChainId, createAccountAddressDID, createPublicKeyDID.
  • Network checks when verifying credentials compare by chain (isSameNetwork) instead of by regex.

Effect on code that checks Network exhaustively

Existing calls compile and behave as before. The only TypeScript that stops compiling is code assuming Network has exactly two values, e.g.

switch (network) {
    case 'Testnet': ...
    case 'Mainnet': ...
    default: { const _: never = network; } // now errors: GenesisHashPrefix is possible
}

or passing a Network into something typed 'Testnet' | 'Mainnet'. As with #[non_exhaustive] in Concordium/concordium-base#986, I don't expect this in practice, so the CHANGELOG lists it under Changed rather than as a breaking change.

wallet-connectors (peer dependency on @concordium/web-sdk unchanged, >= 12.0.2)

  • Opt-in chainIdFormat: 'genesis' on Network and a withGenesisChainId(network) helper, producing ccd:<genesis prefix>. The default stays ccd:<name> (so STAGENET remains ccd:stagenet). getChainId is exported.

verification-web-ui

  • network config accepts a custom network: { chainId: 'ccd:<prefix>', walletDeepLinks?: { ios?, android? } }.
  • The network is resolved in one place (utils/network.ts) instead of four inconsistent sources; legacy 'testnet'/'mainnet' values in localStorage still resolve.
  • Custom networks without deep links fall back to QR / the WalletConnect URI.
  • Fixes CryptoX deep links to use the schemes the apps actually register (checked against cryptox-ios Info.plists / AppDelegate.swift and the cryptox-android manifest): mainnet cryptoxmainnet:// / cryptox-wc-mainnet:// → cryptox:// / cryptox-wc://, and Android testnet cryptox-wc-testnet:// → cryptox-wc:// (both Android builds register only cryptox-wc).
  • Adds a test script (node:test via tsx).

Testing

  • sdk: test/ci passes (695 tests), including new did.test.ts (parse/format round trips for every DID type and network form, compatibility snapshots for named networks, and key derivation for genesis-prefix networks) and an end-to-end VerifiablePresentationV1 prove → verify with the testnet genesis prefix and a custom prefix through WASM.
  • wallet-connectors: 32 tests pass, including chain IDs for TESTNET, MAINNET, STAGENET and a custom network.
  • verification-web-ui: 15 tests pass; build:lib OK.
  • Lint and prettier clean.

@andynelson
andynelson force-pushed the feature/did-genesis-network branch from c233494 to 324c972 Compare November 12, 2026 14:18
@andynelson
andynelson marked this pull request as draft November 12, 2026 14:25
@andynelson
andynelson force-pushed the feature/did-genesis-network branch 5 times, most recently from 476c536 to cb10333 Compare November 12, 2026 16:25
@andynelson
andynelson marked this pull request as ready for review November 12, 2026 16:29
@andynelson
andynelson requested a review from limemloh November 12, 2026 16:30
Bump concordium-base to main (Concordium/concordium-base#986), which
accepts did:ccd:<genesis hash prefix>:..., and adopt it across the SDK
packages. Existing DIDs, chain IDs and stored settings are
unchanged; the genesis form is opt-in.

- sdk: widen Network to 'Testnet' | 'Mainnet' | GenesisHashPrefix.Type;
  add the GenesisHashPrefix module and network helpers (chain IDs,
  chain equality, key derivation: mainnet derives as Mainnet, every other
  network as Testnet); add a ConcordiumDID class covering every
  Concordium DID type and route the DID classes, create*DID helpers and
  credential metadata parsing through it; compare networks by chain
  when verifying.
- wallet-connectors: opt-in chainIdFormat: 'genesis' / withGenesisChainId
  for ccd:<genesis hash prefix> chain IDs.
- verification-web-ui: accept a custom network ({ chainId,
  walletDeepLinks }), resolve the network in one place, and fix the
  CryptoX deep-link schemes (mainnet, and Android testnet).
@andynelson
andynelson force-pushed the feature/did-genesis-network branch from cb10333 to d6101ef Compare November 12, 2026 16:33
Comment on lines +9 to +16
declare const genesisHashPrefixBrand: unique symbol;

/**
* The first 32 lowercase hex characters (16 bytes) of the hash of a chain's genesis block.
* Identifies a Concordium network without relying on a name, and matches the reference part of
* `ccd:<prefix>` chain IDs and the network segment of `did:ccd:<prefix>:...` DIDs.
*/
export type Type = HexString & { readonly [genesisHashPrefixBrand]: true };

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just pointing out that this form of type safety with type brands is different from what we use elsewhere (see BlockHash and AccountAddress). I personally don't mind; there's pros and cons to both, and for this type I think it makes sense to do type branding.

Comment on lines +129 to +135
/**
* A Concordium DID: `did:ccd:<network>:<identifier>`, mirroring `web3id::did::Method` in concordium-base.
*
* This is the general form covering every DID type; {@linkcode IdentityProviderDID} and
* {@linkcode ContractInstanceDID} are specific to identity providers and contract instances.
*/
export class ConcordiumDID {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I feel like it would make more sense to have specific types representing each DID (extending the approach for ipd/contract instance) and then do a union of these to represent the general form? I think structuring it like that would make the code easier to read as parsing/formatting would be coupled to the individual type.

Comment on lines +171 to +183
/**
* Gets the identifier, checking that it is of the given type.
*
* @param type - The expected identifier type
* @returns The identifier
* @throws Error if the identifier is of another type
*/
public identifierOf<T extends DIDIdentifier['type']>(type: T): Extract<DIDIdentifier, { type: T }> {
if (this.identifier.type !== type) {
throw new Error(`Expected a DID of type '${type}', got: ${this.toJSON()}`);
}
return this.identifier as Extract<DIDIdentifier, { type: T }>;
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

also then you would not need to rely on this slightly awkward function which seems to be mostly used as "construct this generalised form of a known variant, and then extract this parsed property assuming this type"

Comment thread packages/sdk/src/types.ts
Comment on lines +1863 to +1864
*
* Key derivation only distinguishes mainnet from every other network; see {@linkcode getKeyDerivationNetwork}.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
*
* Key derivation only distinguishes mainnet from every other network; see {@linkcode getKeyDerivationNetwork}.

probably fine to just leave this at the function in question instead

Comment thread packages/sdk/CHANGELOG.md
Comment on lines +7 to +10
- `Network` can now also be a `GenesisHashPrefix.Type`: the first 32 lowercase hex characters of a chain's genesis block
hash. This identifies any chain, including ones without a well-known name, and is written into DIDs as
`did:ccd:<prefix>:…` (e.g. `did:ccd:4221332d34e1694168c2a0c0b3fd0f27:idp:0`), matching `ccd:<prefix>` chain IDs.
It requires counterparties (wallets, verifiers) that support it.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- `Network` can now also be a `GenesisHashPrefix.Type`: the first 32 lowercase hex characters of a chain's genesis block
hash. This identifies any chain, including ones without a well-known name, and is written into DIDs as
`did:ccd:<prefix>:…` (e.g. `did:ccd:4221332d34e1694168c2a0c0b3fd0f27:idp:0`), matching `ccd:<prefix>` chain IDs.
It requires counterparties (wallets, verifiers) that support it.
- `GenesisHashPrefix.Type`: the first 32 lowercase hex characters of a chain's genesis block
hash. This identifies any chain, including ones without a well-known name, and is written into DIDs as
`did:ccd:<prefix>:…` (e.g. `did:ccd:4221332d34e1694168c2a0c0b3fd0f27:idp:0`), matching `ccd:<prefix>` chain IDs.

changed already describes the Network change, and I think the last part removed is not a concern for the sdk to describe

export type NamedNetwork = 'mainnet' | 'testnet';

/**
* URL schemes used to deep link into a mobile wallet, without `://`, e.g. `cryptox`.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

also here

Comment on lines +19 to +21
- Mobile app detection and deep links used schemes the CryptoX apps don't register: `cryptoxmainnet://` /
`cryptox-wc-mainnet://` on mainnet instead of `cryptox://` / `cryptox-wc://`, and `cryptox-wc-testnet://` on
Android testnet instead of `cryptox-wc://`.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

would reference the wallets by "concordium wallet" instead of "cryptox"

Comment on lines +16 to +18
- All components now read the network from one place. Before, some used the `VITE_NETWORK` env var while others used
the configured network, and the chain ID sent from the session-approval path could be `undefined` when the
`VITE_CHAIN_ID_*` env vars were not set.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sounds like an internal implementation detail? the important bit seems to be communicating which environment variable is relevant to specify and which are not relevant anymore.

Comment on lines +570 to +573
const prefix = genesisHash.toLowerCase().slice(0, GENESIS_HASH_PREFIX_HEX_LEN);
if (!/^[0-9a-f]{32}$/.test(prefix)) {
throw new Error(`Invalid genesis hash for network '${name}': ${genesisHash}`);
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Error message seems misleading as it does not have anything to do with the specific network name. Also, we could use the new GenesisHashPrefix.fromGenesisHash from the SDK, as long as the peer dependency entry is updated?

Comment on lines +32 to +45
| { type: 'acc'; address: string }
/** An account credential, by credential registration ID: `cred:<96 hex chars>`. */
| { type: 'cred'; credId: string }
/**
* A smart contract instance: `sci:<index>[:<subindex>][/<entrypoint>[/<hex parameter>]]`.
* `entrypoint` and `parameter` are omitted from the string when `undefined`.
*/
| { type: 'sci'; index: bigint; subindex: bigint; entrypoint?: string; parameter?: string }
/** An Ed25519 public key: `pkc:<64 hex chars>`. */
| { type: 'pkc'; key: string }
/** An identity provider, by its on-chain index: `idp:<index>`. */
| { type: 'idp'; index: number }
/** An encrypted, ephemeral identity credential ID: `encidcred:<hex>`. */
| { type: 'encidcred'; credId: string };

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it would make sense to use the dedicated types to represent these, i.e.

Suggested change
| { type: 'acc'; address: string }
/** An account credential, by credential registration ID: `cred:<96 hex chars>`. */
| { type: 'cred'; credId: string }
/**
* A smart contract instance: `sci:<index>[:<subindex>][/<entrypoint>[/<hex parameter>]]`.
* `entrypoint` and `parameter` are omitted from the string when `undefined`.
*/
| { type: 'sci'; index: bigint; subindex: bigint; entrypoint?: string; parameter?: string }
/** An Ed25519 public key: `pkc:<64 hex chars>`. */
| { type: 'pkc'; key: string }
/** An identity provider, by its on-chain index: `idp:<index>`. */
| { type: 'idp'; index: number }
/** An encrypted, ephemeral identity credential ID: `encidcred:<hex>`. */
| { type: 'encidcred'; credId: string };
| { type: 'acc'; address: AccountAddress.Type }
/** An account credential, by credential registration ID: `cred:<96 hex chars>`. */
| { type: 'cred'; credId: CredentialRegistrationId.Type }
...

as that would enforce the constraints of the domain types as intended.

But I would still rather have each DID identifier in a dedicated DID type for each variant

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants