Repository navigation
Support genesis-hash network identifiers in DIDs and chain IDs - #711
andynelson wants to merge 1 commit into
Conversation
c233494 to
324c972
Compare
476c536 to
cb10333
Compare
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).
cb10333 to
d6101ef
Compare
| 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 }; |
There was a problem hiding this comment.
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.
| /** | ||
| * 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 { |
There was a problem hiding this comment.
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.
| /** | ||
| * 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 }>; | ||
| } |
There was a problem hiding this comment.
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"
| * | ||
| * Key derivation only distinguishes mainnet from every other network; see {@linkcode getKeyDerivationNetwork}. |
There was a problem hiding this comment.
| * | |
| * Key derivation only distinguishes mainnet from every other network; see {@linkcode getKeyDerivationNetwork}. |
probably fine to just leave this at the function in question instead
| - `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. |
There was a problem hiding this comment.
| - `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`. |
| - 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://`. |
There was a problem hiding this comment.
would reference the wallets by "concordium wallet" instead of "cryptox"
| - 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. |
There was a problem hiding this comment.
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.
| 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}`); | ||
| } |
There was a problem hiding this comment.
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?
| | { 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 }; |
There was a problem hiding this comment.
I think it would make sense to use the dedicated types to represent these, i.e.
| | { 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
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 asdid:ccd:<32-hex genesis prefix>:….Builds on Concordium/concordium-base#986 (merged);
deps/concordium-basenow points at that commit onmain.Compatibility
testnet/mainnet, and parsingdid:ccd:testnet:…still givesnetwork === 'Testnet'.DIDNetwork.sameChain, matching the Rust equality in base).did:ccd:<prefix>:…, so adopt per integration.Changes
sdk
Network(intypes.ts) is now'Testnet' | 'Mainnet' | GenesisHashPrefix.Type.GenesisHashPrefixmodule insrc/types/(Type,TESTNET,MAINNET,instanceOf,fromHexString,fromGenesisHash,toHexString), following theBlockHash-style modules.networkHelpers.ts:networkToString,networkFromString,isSameNetwork,getNetworkGenesisHashPrefix,networkFromChainId,networkToChainId,getKeyDerivationNetwork.getKeyDerivationNetworkmaps mainnet (by name or genesis prefix) toMainnet(coin type 919) and every other network toTestnet(coin type 1). Applied inConcordiumHdWalletandgetIdProof, the only places the network reaches WASM key derivation.ConcordiumDIDclass inweb3-id/types.ts, next toDIDString,IdentityProviderDIDandContractInstanceDID:fromJSON,toJSONandidentifierOf, with aDIDIdentifierunion for every DID type (acc,cred,sci,pkc,idp,encidcred). It is now the only code that builds or parsesdid:ccd:strings.IdentityProviderDID,ContractInstanceDID, thecreate*DIDhelpers and credential metadata parsing use it. NewIdentityProviderDID.fromChainId,createAccountAddressDID,createPublicKeyDID.isSameNetwork) instead of by regex.Effect on code that checks
NetworkexhaustivelyExisting calls compile and behave as before. The only TypeScript that stops compiling is code assuming
Networkhas exactly two values, e.g.or passing a
Networkinto 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-sdkunchanged,>= 12.0.2)chainIdFormat: 'genesis'onNetworkand awithGenesisChainId(network)helper, producingccd:<genesis prefix>. The default staysccd:<name>(soSTAGENETremainsccd:stagenet).getChainIdis exported.verification-web-ui
networkconfig accepts a custom network:{ chainId: 'ccd:<prefix>', walletDeepLinks?: { ios?, android? } }.utils/network.ts) instead of four inconsistent sources; legacy'testnet'/'mainnet'values in localStorage still resolve.cryptox-iosInfo.plists /AppDelegate.swiftand thecryptox-androidmanifest): mainnetcryptoxmainnet:///cryptox-wc-mainnet://→cryptox:///cryptox-wc://, and Android testnetcryptox-wc-testnet://→cryptox-wc://(both Android builds register onlycryptox-wc).testscript (node:test via tsx).Testing
test/cipasses (695 tests), including newdid.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-endVerifiablePresentationV1prove → verify with the testnet genesis prefix and a custom prefix through WASM.build:libOK.