@layerzerolabs/common-canton 0.2.120 → 0.2.122

package/src/client/topology/mappings.ts

@@ -0,0 +1,152 @@
+import {
+    CryptoKeyFormat,
+    DecentralizedNamespaceDefinition,
+    Enums_ParticipantPermission,
+    NamespaceDelegation,
+    PartyToKeyMapping,
+    PartyToParticipant,
+    PartyToParticipant_HostingParticipant,
+    SigningKeySpec,
+    SigningKeyUsage,
+    SigningPublicKey,
+    TopologyMapping,
+} from '@canton-network/core-ledger-proto';
+
+import { computePublicKeyFingerprint } from '../utils';
+
+/**
+ * Builds a Canton protocol `SigningPublicKey` from a DER-encoded secp256k1 public key.
+ *
+ * Keys use X.509 SubjectPublicKeyInfo encoding with `NAMESPACE` and `PROTOCOL` usage,
+ * as required by Canton topology mappings.
+ *
+ * @param publicKeyDer - DER-encoded secp256k1 public key (X.509 SubjectPublicKeyInfo).
+ * @returns A `SigningPublicKey` for use in topology mapping protobuf fields.
+ */
+function buildSigningPublicKey(publicKeyDer: Uint8Array): SigningPublicKey {
+    return SigningPublicKey.create({
+        format: CryptoKeyFormat.DER_X509_SUBJECT_PUBLIC_KEY_INFO,
+        publicKey: publicKeyDer,
+        usage: [SigningKeyUsage.NAMESPACE, SigningKeyUsage.PROTOCOL],
+        keySpec: SigningKeySpec.EC_SECP256K1,
+    });
+}
+
+/**
+ * Builds a Namespace Delegation (NSD) topology mapping for a root owner key.
+ *
+ * Registers a self-rooted namespace: the namespace identifier is the public key
+ * fingerprint, and the same key is the root delegation target. The unsigned
+ * transaction produced from this mapping must be signed by that key alone.
+ *
+ * @param publicKeyDer - DER-encoded secp256k1 public key for the namespace owner.
+ * @returns A `TopologyMapping` containing a root `NamespaceDelegation`.
+ */
+export function buildNamespaceDelegationMapping(publicKeyDer: Uint8Array): TopologyMapping {
+    const namespace = computePublicKeyFingerprint(publicKeyDer);
+    return TopologyMapping.create({
+        mapping: {
+            oneofKind: 'namespaceDelegation',
+            namespaceDelegation: NamespaceDelegation.create({
+                namespace,
+                targetKey: buildSigningPublicKey(publicKeyDer),
+                isRootDelegation: true,
+            }),
+        },
+    });
+}
+
+/**
+ * Builds a Decentralized Namespace Definition (DND) topology mapping.
+ *
+ * Defines a multi-owner namespace identified by `decentralizedNamespace`, with a
+ * signing threshold over the listed owner key fingerprints. Every owner must
+ * authorize the transaction.
+ *
+ * @param decentralizedNamespace - Decentralized namespace fingerprint (e.g. `1220…`).
+ * @param threshold - Minimum number of owner signatures required (≤ `owners.length`).
+ * @param owners - Owner namespace fingerprints (multihash hex strings).
+ * @returns A `TopologyMapping` containing a `DecentralizedNamespaceDefinition`.
+ */
+export function buildDecentralizedNamespaceDefinitionMapping(
+    decentralizedNamespace: string,
+    threshold: number,
+    owners: string[],
+): TopologyMapping {
+    return TopologyMapping.create({
+        mapping: {
+            oneofKind: 'decentralizedNamespaceDefinition',
+            decentralizedNamespaceDefinition: DecentralizedNamespaceDefinition.create({
+                decentralizedNamespace,
+                threshold,
+                owners,
+            }),
+        },
+    });
+}
+
+/**
+ * Builds a Party-to-Key (PTK) topology mapping.
+ *
+ * Binds signing keys to a party and sets the threshold required to authorize
+ * party-level topology changes. Decentralized namespace owners must co-sign
+ * the transaction.
+ *
+ * @param partyId - Full party identifier (e.g. `hint::1220…`).
+ * @param signingPublicKeyDers - DER-encoded signing public keys assigned to the party.
+ * @param threshold - Minimum number of party signing keys required (≤ number of keys).
+ * @returns A `TopologyMapping` containing a `PartyToKeyMapping`.
+ */
+export function buildPartyToKeyMapping(
+    partyId: string,
+    signingPublicKeyDers: Uint8Array[],
+    threshold: number,
+): TopologyMapping {
+    return TopologyMapping.create({
+        mapping: {
+            oneofKind: 'partyToKeyMapping',
+            partyToKeyMapping: PartyToKeyMapping.create({
+                party: partyId,
+                threshold,
+                signingKeys: signingPublicKeyDers.map((publicKeyDer) =>
+                    buildSigningPublicKey(publicKeyDer),
+                ),
+            }),
+        },
+    });
+}
+
+/**
+ * Builds a Party-to-Participant (PTP) topology mapping.
+ *
+ * Declares which participant nodes host the party. Each participant is granted
+ * `CONFIRMATION` permission. On initial hosting, submit the signed transaction
+ * with `proposal: true` so the participant can complete authorization via the
+ * topology `Authorize` RPC.
+ *
+ * @param partyId - Full party identifier (e.g. `hint::1220…`).
+ * @param participantIds - Participant UIDs that should host the party.
+ * @param threshold - Hosting threshold (≤ `participantIds.length`).
+ * @returns A `TopologyMapping` containing a `PartyToParticipant` mapping.
+ */
+export function buildPartyToParticipantMapping(
+    partyId: string,
+    participantIds: string[],
+    threshold: number,
+): TopologyMapping {
+    return TopologyMapping.create({
+        mapping: {
+            oneofKind: 'partyToParticipant',
+            partyToParticipant: PartyToParticipant.create({
+                party: partyId,
+                threshold,
+                participants: participantIds.map((participantId) =>
+                    PartyToParticipant_HostingParticipant.create({
+                        participantUid: participantId,
+                        permission: Enums_ParticipantPermission.CONFIRMATION,
+                    }),
+                ),
+            }),
+        },
+    });
+}

package/src/client/topology/signing.ts

@@ -0,0 +1,56 @@
+import {
+    MultiTransactionSignatures,
+    Signature,
+    SignatureFormat,
+    SignedTopologyTransaction,
+    SigningAlgorithmSpec,
+} from '@canton-network/core-ledger-proto';
+
+/** A single namespace-key signature over the multi-transaction hash. */
+export type TopologySignature = {
+    /** Fingerprint of the signing key (Canton `signedBy`). */
+    signerFingerprint: string;
+    /** Raw DER ECDSA-SHA256 signature bytes over the multi-transaction hash. */
+    signatureBytes: Uint8Array;
+};
+
+/**
+ * Wraps namespace-key signatures over one or more topology transaction hashes.
+ *
+ * Use with {@link computeMultiTransactionHash}: sign the multi-hash once per key,
+ * then pass the raw signatures here to cover every hash in the batch.
+ */
+export function buildMultiTransactionSignatures(
+    transactionHashes: Uint8Array[],
+    signatures: readonly TopologySignature[],
+): MultiTransactionSignatures {
+    return MultiTransactionSignatures.create({
+        transactionHashes,
+        signatures: signatures.map((entry) =>
+            Signature.create({
+                format: SignatureFormat.DER,
+                signature: entry.signatureBytes,
+                signedBy: entry.signerFingerprint,
+                signingAlgorithmSpec: SigningAlgorithmSpec.EC_DSA_SHA_256,
+            }),
+        ),
+    });
+}
+
+/**
+ * Builds a {@link SignedTopologyTransaction} ready for
+ * {@link CantonGrpcClient.submitTopologyTransactions}.
+ *
+ * Set `proposal: true` when the hosting participant must authorize the mapping.
+ */
+export function buildSignedTransaction(
+    transaction: Uint8Array,
+    multiTransactionSignatures: MultiTransactionSignatures[],
+    proposal = false,
+): SignedTopologyTransaction {
+    return SignedTopologyTransaction.create({
+        transaction,
+        multiTransactionSignatures,
+        proposal,
+    });
+}

package/src/client/topology/synchronizer-connectivity.ts

@@ -0,0 +1,110 @@
+// `@protobuf-ts/runtime` and `@protobuf-ts/runtime-rpc` are already in the tree as
+// transitive deps of `@canton-network/core-ledger-proto` (and `@protobuf-ts/grpc-transport`),
+// so declaring them here adds no new dependency — pnpm's isolation just requires this
+// package to list them before it can import them directly.
+import { MessageType, RepeatType, ScalarType } from '@protobuf-ts/runtime';
+import {
+    type MethodInfo,
+    type RpcOptions,
+    type RpcTransport,
+    ServiceType,
+    stackIntercept,
+    type UnaryCall,
+} from '@protobuf-ts/runtime-rpc';
+
+/**
+ * Minimal hand-written client for the Canton participant admin
+ * `SynchronizerConnectivityService.ListConnectedSynchronizers` RPC.
+ *
+ * The published `@canton-network/core-ledger-proto` package does not ship the
+ * `com.digitalasset.canton.admin.participant.v30` namespace, so the message and
+ * service descriptors required for synchronizer discovery are declared here
+ * against the same `@protobuf-ts` runtime the generated topology clients use.
+ *
+ * Field numbers mirror the `SynchronizerConnectivityService` definition in the
+ * Canton `com.digitalasset.canton.admin.participant.v30` proto package; re-verify
+ * them when bumping `@canton-network/core-ledger-proto` (pinned at ^0.22.0).
+ *
+ * TODO: the synchronizer id is also resolvable via the JSON Ledger API
+ * (`/v2/state/connected-synchronizers`), in which case this hand-written gRPC
+ * client can be removed — but consumers would then need to pass a JSON API URL too.
+ */
+
+const SERVICE_NAME =
+    'com.digitalasset.canton.admin.participant.v30.SynchronizerConnectivityService';
+
+/** Empty request for `ListConnectedSynchronizers`. */
+export type ListConnectedSynchronizersRequest = Record<string, never>;
+
+/** A single connected-synchronizer entry. */
+export type ConnectedSynchronizer = {
+    /** Human-readable synchronizer alias (e.g. `global`). */
+    synchronizerAlias: string;
+    /** Logical synchronizer id — the value accepted by topology `BaseQuery.store`. */
+    synchronizerId: string;
+    /** Physical synchronizer id (logical id plus a `::<protocol>-<serial>` suffix). */
+    physicalSynchronizerId: string;
+    /** Whether the participant's connection to the synchronizer is healthy. */
+    healthy: boolean;
+};
+
+/** Response for `ListConnectedSynchronizers`. */
+export type ListConnectedSynchronizersResponse = {
+    connectedSynchronizers: ConnectedSynchronizer[];
+};
+
+const connectedSynchronizerMessage = new MessageType<ConnectedSynchronizer>(
+    `${SERVICE_NAME}.ListConnectedSynchronizersResponse.Result`,
+    [
+        { no: 1, name: 'synchronizer_alias', kind: 'scalar', T: ScalarType.STRING },
+        { no: 2, name: 'synchronizer_id', kind: 'scalar', T: ScalarType.STRING },
+        { no: 3, name: 'physical_synchronizer_id', kind: 'scalar', T: ScalarType.STRING },
+        { no: 4, name: 'healthy', kind: 'scalar', T: ScalarType.BOOL },
+    ],
+);
+
+const requestMessage = new MessageType<ListConnectedSynchronizersRequest>(
+    `${SERVICE_NAME}.ListConnectedSynchronizersRequest`,
+    [],
+);
+
+const responseMessage = new MessageType<ListConnectedSynchronizersResponse>(
+    `${SERVICE_NAME}.ListConnectedSynchronizersResponse`,
+    [
+        {
+            no: 1,
+            name: 'connected_synchronizers',
+            kind: 'message',
+            repeat: RepeatType.UNPACKED,
+            T: () => connectedSynchronizerMessage,
+        },
+    ],
+);
+
+const service = new ServiceType(SERVICE_NAME, [
+    { name: 'ListConnectedSynchronizers', options: {}, I: requestMessage, O: responseMessage },
+]);
+
+/** Client for the participant admin `SynchronizerConnectivityService`. */
+export class SynchronizerConnectivityServiceClient {
+    readonly #transport: RpcTransport;
+
+    constructor(transport: RpcTransport) {
+        this.#transport = transport;
+    }
+
+    /** Lists synchronizers the participant is currently connected to. */
+    listConnectedSynchronizers(
+        input: ListConnectedSynchronizersRequest,
+        options?: RpcOptions,
+    ): UnaryCall<ListConnectedSynchronizersRequest, ListConnectedSynchronizersResponse> {
+        const method = service.methods[0] as MethodInfo<
+            ListConnectedSynchronizersRequest,
+            ListConnectedSynchronizersResponse
+        >;
+        return stackIntercept<
+            ListConnectedSynchronizersRequest,
+            ListConnectedSynchronizersResponse
+        >('unary', this.#transport, method, this.#transport.mergeOptions(options), input);
+    }
+}

package/src/client/topology/types.ts

@@ -0,0 +1,133 @@
+import {
+    type Enums_ParticipantPermission,
+    type GenerateTransactionsResponse_GeneratedTransaction,
+} from '@canton-network/core-ledger-proto';
+import type { ClientOptions } from '@grpc/grpc-js';
+
+import type { TokenProvider } from '../../auth/token-provider';
+
+/** Unsigned topology transaction from `GenerateTransactions` (`serializedTransaction`, `transactionHash`). */
+export type GeneratedTopologyTransaction = GenerateTransactionsResponse_GeneratedTransaction;
+
+/** Inputs for building an unsigned Namespace Delegation topology transaction. */
+export type CreateNamespaceDelegationTxParams = {
+    /** DER-encoded secp256k1 public key (X.509 SubjectPublicKeyInfo). Namespace is derived from its fingerprint. */
+    publicKeyDer: Uint8Array;
+    /** Topology serial (default: 0 = auto-determined by Canton). */
+    serial?: number;
+};
+
+/** Inputs for building an unsigned Decentralized Namespace Definition topology transaction. */
+export type CreateDecentralizedNamespaceDefinitionTxParams = {
+    /** Owner key fingerprints (multihash hex). Namespace id is derived from these. */
+    owners: string[];
+    /** Signing threshold (≤ number of owners). */
+    threshold: number;
+    /** Topology serial (default: 0 = auto-determined by Canton). */
+    serial?: number;
+};
+
+export type UpdateDecentralizedNamespaceDefinitionTxParams =
+    CreateDecentralizedNamespaceDefinitionTxParams & {
+        namespace: string;
+    };
+
+/** Inputs for building an unsigned Party-to-Key mapping topology transaction. */
+export type CreatePartyToKeyMappingTxParams = {
+    /** Full party id (e.g. `hint::1220…`). */
+    partyId: string;
+    /** DER-encoded signing public keys. */
+    signingPublicKeyDers: Uint8Array[];
+    /** Signing threshold (≤ number of keys). */
+    threshold: number;
+    /** Topology serial (default: 0 = auto-determined by Canton). */
+    serial?: number;
+};
+
+/** Inputs for building an unsigned Party-to-Participant topology transaction. */
+export type CreatePartyToParticipantMappingTxParams = {
+    /** Full party id (e.g. `hint::1220…`). */
+    partyId: string;
+    /** Hosting participant id(s). */
+    participantIds: string[];
+    /** Hosting threshold (≤ number of participants). */
+    threshold: number;
+    /** Topology serial (default: 0 = auto-determined by Canton). */
+    serial?: number;
+};
+
+/** Namespace Delegation (NSD) as returned by topology list queries. */
+export type NamespaceDelegationState = {
+    /** Namespace fingerprint this delegation applies to. */
+    namespace: string;
+    /** Fingerprint of the key receiving delegation authority. */
+    targetKeyFingerprint: string;
+    /** Whether this is a root (self) namespace delegation. */
+    isRootDelegation: boolean;
+    /** Topology serial of this mapping revision. */
+    serial: number;
+};
+
+/** Decentralized Namespace Definition (DND) as returned by topology list queries. */
+export type DecentralizedNamespaceDefinitionState = {
+    /** Decentralized namespace fingerprint. */
+    namespace: string;
+    /** Minimum number of owner signatures required. */
+    threshold: number;
+    /** Owner namespace fingerprints (multihash hex). */
+    owners: string[];
+    /** Topology serial of this mapping revision. */
+    serial: number;
+};
+
+/** Party-to-Key (PTK) mapping as returned by topology list queries. */
+export type PartyToKeyMappingState = {
+    /** Full party identifier. */
+    party: string;
+    /** Minimum number of signing keys required. */
+    threshold: number;
+    /** Fingerprints of keys authorized to sign for the party. */
+    signingKeyFingerprints: string[];
+    /** Topology serial of this mapping revision. */
+    serial: number;
+};
+
+/** Party-to-Participant (PTP) mapping as returned by topology list queries. */
+export type PartyToParticipantMappingState = {
+    /** Full party identifier. */
+    party: string;
+    /** Hosting threshold (≤ number of participants). */
+    threshold: number;
+    /** Participant nodes hosting the party and their permission. */
+    participants: { participantUid: string; permission: Enums_ParticipantPermission }[];
+    /** Topology serial of this mapping revision. */
+    serial: number;
+};
+
+/** TLS credentials for Canton admin gRPC connections. */
+export type TlsOptions = {
+    /** CA root certificate for server verification. */
+    rootCert?: Buffer;
+    /** Client private key for mutual TLS. */
+    clientKey?: Buffer;
+    /** Client certificate for mutual TLS. */
+    clientCert?: Buffer;
+};
+
+/** Options for constructing a {@link CantonGrpcClient}. */
+export type CantonGrpcClientOptions = {
+    /** Participant admin API host (e.g. `participant.example.com:443`). */
+    host: string;
+    /** Supplies a fresh Bearer token before each RPC call. */
+    tokenProvider: TokenProvider;
+    /**
+     * Logical synchronizer id used as the topology store. When omitted, the first
+     * synchronizer the participant is connected to (via `ListConnectedSynchronizers`)
+     * is resolved on the first RPC.
+     */
+    synchronizerId?: string;
+    /** TLS options; omitted for insecure (non-:443) or default SSL on :443. */
+    tls?: TlsOptions;
+    /** Overrides the default gRPC channel options. */
+    grpcClientOptions?: ClientOptions;
+};

package/src/client/topology/utils.ts

@@ -0,0 +1,93 @@
+import { BaseQuery, Empty, StoreId } from '@canton-network/core-ledger-proto';
+import { ChannelCredentials } from '@grpc/grpc-js';
+
+import { bytesToHex } from '@layerzerolabs/common-encoding-utils';
+
+import { cantonMultihash } from '../utils';
+import type { TlsOptions } from './types';
+
+/** Canton hash purpose for decentralized namespace derivation. */
+const HASH_PURPOSE_DECENTRALIZED_NAMESPACE = 37;
+
+/** Canton hash purpose for multi-transaction topology signing. */
+const HASH_PURPOSE_MULTI_TRANSACTION = 55;
+
+/**
+ * Computes the decentralized namespace fingerprint from owner key fingerprints.
+ *
+ * Owners are sorted lexicographically, then hashed as
+ * `1220` + SHA256(purpose=37 || for each owner: len(utf8) || utf8).
+ */
+export function computeDecentralizedNamespace(owners: string[]): string {
+    const sorted = [...owners].sort();
+    const parts: Buffer[] = [];
+    for (const owner of sorted) {
+        const ownerBytes = Buffer.from(owner, 'utf-8');
+        const lengthPrefix = Buffer.alloc(4);
+        lengthPrefix.writeUInt32BE(ownerBytes.length);
+        parts.push(lengthPrefix, ownerBytes);
+    }
+    return bytesToHex(cantonMultihash(HASH_PURPOSE_DECENTRALIZED_NAMESPACE, Buffer.concat(parts)));
+}
+
+/**
+ * Combines topology transaction hashes into the digest Canton expects signed.
+ *
+ * Hashes are sorted lexicographically, count-prefixed, each length-prefixed, then
+ * hashed with purpose 55. Pass a single hash when signing one transaction —
+ * Canton always uses this multi-transaction format for `AddTransactions`.
+ */
+export function computeMultiTransactionHash(hashes: Uint8Array[]): Uint8Array {
+    const sorted = [...hashes].sort((left, right) =>
+        Buffer.compare(Buffer.from(left), Buffer.from(right)),
+    );
+    const parts: Buffer[] = [];
+    const countBuffer = Buffer.alloc(4);
+    countBuffer.writeUInt32BE(sorted.length);
+    parts.push(countBuffer);
+    for (const hash of sorted) {
+        const lengthBuffer = Buffer.alloc(4);
+        lengthBuffer.writeUInt32BE(hash.length);
+        parts.push(lengthBuffer, Buffer.from(hash));
+    }
+    return cantonMultihash(HASH_PURPOSE_MULTI_TRANSACTION, Buffer.concat(parts));
+}
+
+/**
+ * Builds a topology `StoreId` scoped to a synchronizer.
+ *
+ * Used as the `store` field on topology read/write RPC requests.
+ */
+export function synchronizerStore(synchronizerId: string): StoreId {
+    return StoreId.create({
+        store: { oneofKind: 'synchronizer', synchronizer: { id: synchronizerId } },
+    });
+}
+
+/**
+ * Builds a topology `BaseQuery` at synchronizer head state.
+ *
+ * Used as the `baseQuery` field on topology list RPC requests.
+ */
+export function headStateBaseQuery(synchronizerId: string, proposals = false): BaseQuery {
+    return BaseQuery.create({
+        store: synchronizerStore(synchronizerId),
+        timeQuery: { oneofKind: 'headState', headState: Empty.create({}) },
+        proposals,
+    });
+}
+
+/**
+ * Builds gRPC channel credentials for the Canton admin API.
+ *
+ * Uses explicit TLS when `tls` is set, default SSL for hosts ending in `:443`,
+ * and insecure credentials otherwise.
+ */
+export function buildChannelCredentials(host: string, tls?: TlsOptions): ChannelCredentials {
+    if (tls) {
+        return ChannelCredentials.createSsl(tls.rootCert, tls.clientKey, tls.clientCert);
+    }
+    return host.endsWith(':443')
+        ? ChannelCredentials.createSsl()
+        : ChannelCredentials.createInsecure();
+}

package/src/client/utils.ts

@@ -14,8 +14,32 @@ export function extractTransactions(updates: CantonUpdate[]): CantonTransaction[
 }
 
 const HASH_PURPOSE_PUBLIC_KEY_FINGERPRINT = 12;
+const HASH_PURPOSE_DECENTRALIZED_NAMESPACE = 37;
 const MULTIHASH_SHA256_PREFIX = new Uint8Array([0x12, 0x20]);
 
+/**
+ * Canton multihash: `0x1220 || SHA-256(BE32(purpose) || data)`.
+ */
+export function cantonMultihash(purpose: number, data: Uint8Array): Uint8Array {
+    const purposePrefix = new Uint8Array(4);
+    new DataView(purposePrefix.buffer).setUint32(0, purpose);
+
+    const hash = createHash('sha256').update(purposePrefix).update(data).digest();
+
+    const result = new Uint8Array(MULTIHASH_SHA256_PREFIX.length + hash.length);
+    result.set(MULTIHASH_SHA256_PREFIX);
+    result.set(hash, MULTIHASH_SHA256_PREFIX.length);
+    return result;
+}
+
+/**
+ * Canton fingerprint for a DER-encoded public key (purpose 12).
+ * For root NSD, this is also the namespace id.
+ */
+export function computePublicKeyFingerprint(publicKeyDer: Uint8Array): string {
+    return bytesToHex(cantonMultihash(HASH_PURPOSE_PUBLIC_KEY_FINGERPRINT, publicKeyDer));
+}
+
 /**
  * Computes the Canton fingerprint for an uncompressed secp256k1 public key.
  * DER-encodes the key, then computes hex(SHA-256 multihash of purpose=12 || publicKeyDer).
@@ -27,14 +51,28 @@ export function computeCantonFingerprint(uncompressedPublicKey: Uint8Array): str
     publicKeyDer.set(SECP256K1_SPKI_DER_HEADER);
     publicKeyDer.set(uncompressedPublicKey, SECP256K1_SPKI_DER_HEADER.length);
 
-    const purposePrefix = new Uint8Array(4);
-    new DataView(purposePrefix.buffer).setUint32(0, HASH_PURPOSE_PUBLIC_KEY_FINGERPRINT);
-
-    const hash = createHash('sha256').update(purposePrefix).update(publicKeyDer).digest();
-
-    const result = new Uint8Array(MULTIHASH_SHA256_PREFIX.length + hash.length);
-    result.set(MULTIHASH_SHA256_PREFIX);
-    result.set(hash, MULTIHASH_SHA256_PREFIX.length);
+    return computePublicKeyFingerprint(publicKeyDer);
+}
 
-    return bytesToHex(result);
+/**
+ * Deterministic decentralized-namespace fingerprint from owner key fingerprints.
+ * `"1220" + SHA256(purpose=37 || for each sorted owner: len(utf8) || utf8)`.
+ *
+ * For threshold-1 / single-owner namespaces this is `computeDecentralizedNamespace([keyFp])`,
+ * which is the party id suffix — not the raw key fingerprint.
+ */
+export function computeDecentralizedNamespace(owners: string[]): string {
+    const sorted = [...owners].map((owner) => owner.replace(/^0x/i, '')).sort();
+    const hash = createHash('sha256');
+    const purposeBuf = Buffer.alloc(4);
+    purposeBuf.writeUInt32BE(HASH_PURPOSE_DECENTRALIZED_NAMESPACE);
+    hash.update(purposeBuf);
+    for (const owner of sorted) {
+        const ownerBuf = Buffer.from(owner, 'utf-8');
+        const lenBuf = Buffer.alloc(4);
+        lenBuf.writeUInt32BE(ownerBuf.length);
+        hash.update(lenBuf);
+        hash.update(ownerBuf);
+    }
+    return `1220${hash.digest('hex')}`;
 }

package/src/index.ts

@@ -1,42 +1,18 @@
 export * from './address';
 export * from './amulet';
 export * from './auth';
+export * from './client';
 export * from './crypto';
 export * from './daml-serde';
 export * from './deferredValue';
+export * from './errors';
 export * from './events';
+export * from './minFee';
 export * from './provider';
 export * from './refresh';
+export * from './sdk/index';
 export * from './transaction';
-
-// Core types
-export {
-    buildTemplateId,
-    CommandStatus,
-    type Contract,
-    type ExternalSignature,
-    type IntLike,
-    IntLikeSchema,
-    type PreparedTransaction,
-    type SubmitActors,
-    type SubmitResult,
-    type TemplateId,
-    type UserRight,
-    type UserRightKind,
-    type WaitAccepted,
-    type WaitOptions,
-    type WaitRejected,
-    type WaitResult,
-} from './types';
-
-// Errors
-export { CantonError, CantonProtocolError, CantonTransportError } from './errors';
-
-// Canton Client (low-level transport)
-export * from './client';
-
-// Canton SDK (high-level API)
-export { CantonSdk, type NormalizedActiveContract } from './sdk/index';
+export * from './types';
 
 // Re-export only the types needed for SDK usage
 export type {

package/src/minFee.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+
+import { canonicalizeDamlDecimal } from './types';
+
+const minFeeArgSchema = z.object({ minFee: z.string() });
+
+/**
+ * Extract and canonicalize the `minFee` Daml Decimal from an IMinFee contract's
+ * `createArgument`. Throws a ZodError if the shape doesn't match.
+ */
+export const parseMinFeeValue = (createArgument: unknown): string =>
+    canonicalizeDamlDecimal(minFeeArgSchema.parse(createArgument).minFee);