@layerzerolabs/common-canton 0.2.121 → 0.2.122

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@layerzerolabs/common-canton",
-  "version": "0.2.121",
+  "version": "0.2.122",
   "private": false,
   "description": "Canton VM client and utilities",
   "license": "MIT",
@@ -28,12 +28,14 @@
     "@noble/hashes": "^1.8.0",
     "@noble/secp256k1": "1.7.1",
     "@protobuf-ts/grpc-transport": "^2.9.4",
+    "@protobuf-ts/runtime": "^2.11.1",
+    "@protobuf-ts/runtime-rpc": "^2.11.1",
     "es-toolkit": "^1.39.10",
     "zod": "4.3.5",
-    "@layerzerolabs/common-encoding-utils": "0.2.121",
-    "@layerzerolabs/common-error-utils": "0.2.121",
-    "@layerzerolabs/common-chain-model": "0.2.121",
-    "@layerzerolabs/typescript-utils": "0.2.121"
+    "@layerzerolabs/common-encoding-utils": "0.2.122",
+    "@layerzerolabs/common-chain-model": "0.2.122",
+    "@layerzerolabs/common-error-utils": "0.2.122",
+    "@layerzerolabs/typescript-utils": "0.2.122"
   },
   "devDependencies": {
     "@types/node": "^22.18.6",
@@ -42,11 +44,11 @@
     "tsup": "^8.4.0",
     "typescript": "^5.8.2",
     "vitest": "^3.2.6",
-    "@layerzerolabs/eslint-configuration": "^0.2.121",
-    "@layerzerolabs/tsup-configuration": "0.2.121",
-    "@layerzerolabs/typescript-configuration": "0.2.121",
-    "@layerzerolabs/vitest-configuration": "0.2.121",
-    "@layerzerolabs/vm-tooling-canton": "0.2.121"
+    "@layerzerolabs/eslint-configuration": "^0.2.122",
+    "@layerzerolabs/tsup-configuration": "0.2.122",
+    "@layerzerolabs/vm-tooling-canton": "0.2.122",
+    "@layerzerolabs/vitest-configuration": "0.2.122",
+    "@layerzerolabs/typescript-configuration": "0.2.122"
   },
   "publishConfig": {
     "access": "public",

package/src/client/amulet.ts

@@ -47,7 +47,10 @@ export const fetchAmuletContext = async (
     const later = new Date(now.getTime() + CONTEXT_PROBE_EXECUTE_BEFORE_WINDOW_MS);
 
     const response = await fetch(
-        `${walletUrl}/api/validator/v0/scan-proxy/registry/transfer-instruction/v1/transfer-factory`,
+        new URL(
+            '/api/validator/v0/scan-proxy/registry/transfer-instruction/v1/transfer-factory',
+            walletUrl,
+        ),
         {
             method: 'POST',
             headers: {
@@ -115,7 +118,7 @@ export const injectExternalPartyAmuletRules = (
 
 /** Fetch the DSO party id from the validator scan-proxy API. */
 export const fetchDsoParty = async (walletUrl: string, token: string): Promise<string> => {
-    const response = await fetch(`${walletUrl}/api/validator/v0/scan-proxy/dso-party-id`, {
+    const response = await fetch(new URL('/api/validator/v0/scan-proxy/dso-party-id', walletUrl), {
         headers: { Authorization: `Bearer ${token}` },
     });
     if (!response.ok) {

package/src/client/grpc.ts

@@ -1,81 +1,438 @@
 import {
-    BaseQuery,
-    type DecentralizedNamespaceDefinition,
-    Empty,
+    AddTransactionsRequest,
+    Enums_TopologyChangeOp,
+    GenerateTransactionsRequest,
+    GenerateTransactionsRequest_Proposal,
     ListDecentralizedNamespaceDefinitionRequest,
-    StoreId,
+    ListNamespaceDelegationRequest,
+    ListPartyToKeyMappingRequest,
+    ListPartyToParticipantRequest,
+    type SignedTopologyTransaction,
     TopologyManagerReadServiceClient,
+    TopologyManagerWriteServiceClient,
+    type TopologyMapping,
 } from '@canton-network/core-ledger-proto';
-import { ChannelCredentials } from '@grpc/grpc-js';
 import { GrpcTransport } from '@protobuf-ts/grpc-transport';
 
 import type { TokenProvider } from '../auth/token-provider';
+import { CantonError, CantonProtocolError } from '../errors';
+import {
+    buildDecentralizedNamespaceDefinitionMapping,
+    buildNamespaceDelegationMapping,
+    buildPartyToKeyMapping,
+    buildPartyToParticipantMapping,
+} from './topology/mappings';
+import { SynchronizerConnectivityServiceClient } from './topology/synchronizer-connectivity';
+import type {
+    CantonGrpcClientOptions,
+    CreateDecentralizedNamespaceDefinitionTxParams,
+    CreateNamespaceDelegationTxParams,
+    CreatePartyToKeyMappingTxParams,
+    CreatePartyToParticipantMappingTxParams,
+    DecentralizedNamespaceDefinitionState,
+    GeneratedTopologyTransaction,
+    NamespaceDelegationState,
+    PartyToKeyMappingState,
+    PartyToParticipantMappingState,
+    UpdateDecentralizedNamespaceDefinitionTxParams,
+} from './topology/types';
+import {
+    buildChannelCredentials,
+    computeDecentralizedNamespace,
+    headStateBaseQuery,
+    synchronizerStore,
+} from './topology/utils';
+import { computePublicKeyFingerprint } from './utils';
 
-export type TlsOptions = {
-    rootCert?: Buffer;
-    clientKey?: Buffer;
-    clientCert?: Buffer;
-};
-
-export type CantonGrpcClientOptions = {
-    host: string;
-    tokenProvider?: TokenProvider;
-    tls?: TlsOptions;
-};
-
-function buildChannelCredentials(tls?: TlsOptions): ChannelCredentials {
-    if (!tls) return ChannelCredentials.createInsecure();
-    return ChannelCredentials.createSsl(tls.rootCert, tls.clientKey, tls.clientCert);
-}
+/** Default gRPC client options: 128 MiB message-size limits for large admin responses. */
+const DEFAULT_GRPC_CLIENT_OPTIONS = {
+    'grpc.max_receive_message_length': 128 * 1024 * 1024,
+    'grpc.max_send_message_length': 128 * 1024 * 1024,
+} as const;
 
 /**
- * gRPC client for the Canton Admin API.
+ * gRPC client for the Canton participant admin Topology Manager API.
  *
- * Wraps the Topology Manager Read Service for querying topology state
- * (decentralized namespace definitions, etc.) via the participant's admin endpoint.
+ * Exposes read queries for topology mappings and write helpers that call
+ * `GenerateTransactions` to produce unsigned topology transactions and
+ * `AddTransactions` to submit signed ones.
  *
- * If a {@link TokenProvider} is supplied, a fresh Bearer token is acquired
- * before each RPC call via per-call metadata.
+ * A fresh Bearer token is attached to each RPC via {@link TokenProvider}.
  */
 export class CantonGrpcClient {
     readonly #transport: GrpcTransport;
     readonly #topologyRead: TopologyManagerReadServiceClient;
-    readonly #tokenProvider?: TokenProvider;
+    readonly #topologyWrite: TopologyManagerWriteServiceClient;
+    readonly #connectivity: SynchronizerConnectivityServiceClient;
+    readonly #tokenProvider: TokenProvider;
+    #synchronizerId?: string;
 
+    /**
+     * @param opts - Admin API host, auth, optional synchronizer id, and optional TLS.
+     */
     constructor(opts: CantonGrpcClientOptions) {
+        this.#tokenProvider = opts.tokenProvider;
+        this.#synchronizerId = opts.synchronizerId;
         this.#transport = new GrpcTransport({
             host: opts.host,
-            channelCredentials: buildChannelCredentials(opts.tls),
+            channelCredentials: buildChannelCredentials(opts.host, opts.tls),
+            clientOptions: opts.grpcClientOptions ?? DEFAULT_GRPC_CLIENT_OPTIONS,
         });
         this.#topologyRead = new TopologyManagerReadServiceClient(this.#transport);
-        this.#tokenProvider = opts.tokenProvider;
+        this.#topologyWrite = new TopologyManagerWriteServiceClient(this.#transport);
+        this.#connectivity = new SynchronizerConnectivityServiceClient(this.#transport);
     }
 
+    /** Returns per-RPC gRPC metadata with a fresh Bearer token. */
     async #getMeta(): Promise<Record<string, string>> {
-        if (!this.#tokenProvider) return {};
         const token = await this.#tokenProvider.getToken();
         return { Authorization: `Bearer ${token}` };
     }
 
-    async getLatestDecentralizedNamespaceDefinition(
+    /**
+     * Returns the client synchronizer id, discovering it on first use when omitted at construction.
+     *
+     * @throws {CantonProtocolError} If the participant exposes no synchronizer store.
+     */
+    async #getSynchronizerId(): Promise<string> {
+        if (this.#synchronizerId) {
+            return this.#synchronizerId;
+        }
+        this.#synchronizerId = await this.#discoverSynchronizerId();
+        return this.#synchronizerId;
+    }
+
+    /**
+     * Resolves the logical id of the first synchronizer the participant is connected to.
+     *
+     * @throws {CantonProtocolError} If the participant is not connected to any synchronizer.
+     */
+    async #discoverSynchronizerId(): Promise<string> {
+        const { response } = await this.#connectivity.listConnectedSynchronizers(
+            {},
+            { meta: await this.#getMeta() },
+        );
+        for (const synchronizer of response.connectedSynchronizers) {
+            if (synchronizer.synchronizerId) {
+                return synchronizer.synchronizerId;
+            }
+        }
+        throw new CantonProtocolError('Participant is not connected to any synchronizer');
+    }
+
+    /**
+     * Calls `GenerateTransactions` for a single ADD_REPLACE mapping.
+     *
+     * @param synchronizerId - Synchronizer store to target.
+     * @param mapping - Topology mapping to encode into the transaction.
+     * @param serial - Topology serial (`0` lets Canton auto-determine).
+     * @returns Unsigned topology transaction (`serializedTransaction`, `transactionHash`).
+     * @throws {CantonProtocolError} If the RPC returns no generated transaction.
+     */
+    async #generateTopologyTransaction(
         synchronizerId: string,
+        mapping: TopologyMapping,
+        serial: number,
+    ): Promise<GeneratedTopologyTransaction> {
+        const { response } = await this.#topologyWrite.generateTransactions(
+            GenerateTransactionsRequest.create({
+                proposals: [
+                    GenerateTransactionsRequest_Proposal.create({
+                        operation: Enums_TopologyChangeOp.ADD_REPLACE,
+                        serial,
+                        mapping,
+                        store: synchronizerStore(synchronizerId),
+                    }),
+                ],
+            }),
+            { meta: await this.#getMeta() },
+        );
+
+        const generated = response.generatedTransactions[0];
+        if (!generated) {
+            throw new CantonProtocolError('GenerateTransactions returned no topology transaction');
+        }
+        return generated;
+    }
+
+    /**
+     * Lists Namespace Delegation (NSD) mappings for a namespace.
+     *
+     * Queries topology head state on the synchronizer. Returns every result from
+     * the list RPC.
+     *
+     * @param namespaceFingerprint - Namespace to filter on (for root NSD, the owner key fingerprint).
+     * @returns All matching NSD mappings, or an empty array if none exist.
+     */
+    async getNamespaceDelegation(
+        namespaceFingerprint: string,
+    ): Promise<NamespaceDelegationState[]> {
+        const synchronizerId = await this.#getSynchronizerId();
+        const { response } = await this.#topologyRead.listNamespaceDelegation(
+            ListNamespaceDelegationRequest.create({
+                baseQuery: headStateBaseQuery(synchronizerId),
+                filterNamespace: namespaceFingerprint,
+                // Empty string = no target-key filter; return all delegations for this namespace.
+                filterTargetKeyFingerprint: '',
+            }),
+            { meta: await this.#getMeta() },
+        );
+
+        return response.results.flatMap((result) => {
+            const item = result.item;
+            const publicKey = item?.targetKey?.publicKey;
+            if (!item || !publicKey) {
+                return [];
+            }
+            return [
+                {
+                    namespace: item.namespace,
+                    targetKeyFingerprint: computePublicKeyFingerprint(publicKey),
+                    isRootDelegation: item.isRootDelegation,
+                    serial: result.context?.serial ?? 0,
+                },
+            ];
+        });
+    }
+
+    /**
+     * Lists Decentralized Namespace Definition (DND) mappings for a namespace.
+     *
+     * Queries topology head state on the synchronizer. For a party id `hint::1220…`,
+     * pass the `1220…` suffix as `namespaceFingerprint`.
+     *
+     * @param namespaceFingerprint - Decentralized namespace fingerprint to filter on.
+     * @returns All matching DND mappings, or an empty array if none exist.
+     */
+    async getDecentralizedNamespaceDefinition(
         namespaceFingerprint: string,
-    ): Promise<DecentralizedNamespaceDefinition | undefined> {
+    ): Promise<DecentralizedNamespaceDefinitionState[]> {
+        const synchronizerId = await this.#getSynchronizerId();
         const { response } = await this.#topologyRead.listDecentralizedNamespaceDefinition(
             ListDecentralizedNamespaceDefinitionRequest.create({
-                baseQuery: BaseQuery.create({
-                    store: StoreId.create({
-                        store: { oneofKind: 'synchronizer', synchronizer: { id: synchronizerId } },
-                    }),
-                    timeQuery: { oneofKind: 'headState', headState: Empty.create({}) },
-                }),
+                baseQuery: headStateBaseQuery(synchronizerId),
                 filterNamespace: namespaceFingerprint,
             }),
             { meta: await this.#getMeta() },
         );
-        return response.results[0]?.item;
+
+        return response.results.flatMap((result) => {
+            const item = result.item;
+            if (!item) {
+                return [];
+            }
+            return [
+                {
+                    namespace: item.decentralizedNamespace,
+                    threshold: item.threshold,
+                    owners: [...item.owners],
+                    serial: result.context?.serial ?? 0,
+                },
+            ];
+        });
+    }
+
+    /**
+     * Lists Party-to-Key (PTK) mappings for a party.
+     *
+     * Queries topology head state on the synchronizer.
+     *
+     * @param partyId - Full party identifier (e.g. `hint::1220…`).
+     * @returns All matching PTK mappings, or an empty array if none exist.
+     */
+    async getPartyToKeyMapping(partyId: string): Promise<PartyToKeyMappingState[]> {
+        const synchronizerId = await this.#getSynchronizerId();
+        const { response } = await this.#topologyRead.listPartyToKeyMapping(
+            ListPartyToKeyMappingRequest.create({
+                baseQuery: headStateBaseQuery(synchronizerId),
+                filterParty: partyId,
+            }),
+            { meta: await this.#getMeta() },
+        );
+
+        return response.results.flatMap((result) => {
+            const item = result.item;
+            if (!item) {
+                return [];
+            }
+            return [
+                {
+                    party: item.party,
+                    threshold: item.threshold,
+                    signingKeyFingerprints: item.signingKeys.map((key) =>
+                        computePublicKeyFingerprint(key.publicKey),
+                    ),
+                    serial: result.context?.serial ?? 0,
+                },
+            ];
+        });
+    }
+
+    /**
+     * Lists Party-to-Participant (PTP) mappings for a party.
+     *
+     * Queries topology head state on the synchronizer.
+     *
+     * @param partyId - Full party identifier (e.g. `hint::1220…`).
+     * @param proposals - If `true`, query pending proposals instead of authorized mappings.
+     * @returns All matching PTP mappings, or an empty array if none exist.
+     */
+    async getPartyToParticipantMapping(
+        partyId: string,
+        proposals = false,
+    ): Promise<PartyToParticipantMappingState[]> {
+        const synchronizerId = await this.#getSynchronizerId();
+        const { response } = await this.#topologyRead.listPartyToParticipant(
+            ListPartyToParticipantRequest.create({
+                baseQuery: headStateBaseQuery(synchronizerId, proposals),
+                filterParty: partyId,
+                // Empty string = no participant filter; return all hosting mappings for this party.
+                filterParticipant: '',
+            }),
+            { meta: await this.#getMeta() },
+        );
+
+        return response.results.flatMap((result) => {
+            const item = result.item;
+            if (!item) {
+                return [];
+            }
+            return [
+                {
+                    party: item.party,
+                    threshold: item.threshold,
+                    participants: item.participants.map((participant) => ({
+                        participantUid: participant.participantUid,
+                        permission: participant.permission,
+                    })),
+                    serial: result.context?.serial ?? 0,
+                },
+            ];
+        });
+    }
+
+    /**
+     * Builds an unsigned Namespace Delegation (NSD) topology transaction.
+     *
+     * Calls `GenerateTransactions` with an ADD_REPLACE mapping. The returned
+     * `transactionHash` must be signed by the namespace key.
+     *
+     * @param params - Owner public key and optional serial.
+     * @returns Unsigned topology transaction (`serializedTransaction`, `transactionHash`).
+     */
+    async createNamespaceDelegationTx(
+        params: CreateNamespaceDelegationTxParams,
+    ): Promise<GeneratedTopologyTransaction> {
+        const synchronizerId = await this.#getSynchronizerId();
+        const mapping = buildNamespaceDelegationMapping(params.publicKeyDer);
+        return this.#generateTopologyTransaction(synchronizerId, mapping, params.serial ?? 0);
+    }
+
+    /**
+     * Builds an unsigned Decentralized Namespace Definition (DND) topology transaction.
+     *
+     * The decentralized namespace id is derived from `params.owners`. All owners
+     * must sign the transaction hash.
+     *
+     * @param params - Owner fingerprints, threshold, and optional serial.
+     * @returns Unsigned topology transaction (`serializedTransaction`, `transactionHash`).
+     */
+    async createDecentralizedNamespaceDefinitionTx(
+        params: CreateDecentralizedNamespaceDefinitionTxParams,
+    ): Promise<GeneratedTopologyTransaction> {
+        const synchronizerId = await this.#getSynchronizerId();
+        const decentralizedNamespace = computeDecentralizedNamespace(params.owners);
+        const mapping = buildDecentralizedNamespaceDefinitionMapping(
+            decentralizedNamespace,
+            params.threshold,
+            params.owners,
+        );
+        return this.#generateTopologyTransaction(synchronizerId, mapping, params.serial ?? 0);
+    }
+
+    async updateDecentralizedNamespaceDefinitionTx(
+        params: UpdateDecentralizedNamespaceDefinitionTxParams,
+    ): Promise<GeneratedTopologyTransaction> {
+        const synchronizerId = await this.#getSynchronizerId();
+        const mapping = buildDecentralizedNamespaceDefinitionMapping(
+            params.namespace,
+            params.threshold,
+            params.owners,
+        );
+        return this.#generateTopologyTransaction(synchronizerId, mapping, params.serial ?? 0);
+    }
+
+    /**
+     * Builds an unsigned Party-to-Key (PTK) topology transaction.
+     *
+     * Decentralized namespace owners must sign the transaction hash.
+     *
+     * @param params - Party id, signing keys, threshold, and optional serial.
+     * @returns Unsigned topology transaction (`serializedTransaction`, `transactionHash`).
+     */
+    async createPartyToKeyTx(
+        params: CreatePartyToKeyMappingTxParams,
+    ): Promise<GeneratedTopologyTransaction> {
+        const synchronizerId = await this.#getSynchronizerId();
+        const mapping = buildPartyToKeyMapping(
+            params.partyId,
+            params.signingPublicKeyDers,
+            params.threshold,
+        );
+        return this.#generateTopologyTransaction(synchronizerId, mapping, params.serial ?? 0);
+    }
+
+    /**
+     * Builds an unsigned Party-to-Participant (PTP) topology transaction.
+     *
+     * Party owners sign the transaction hash. On submit, set `proposal: true` on the
+     * signed transaction so the hosting participant can authorize via `Authorize`.
+     *
+     * @param params - Party id, participant ids, threshold, and optional serial.
+     * @returns Unsigned topology transaction (`serializedTransaction`, `transactionHash`).
+     */
+    async createPartyToParticipantTx(
+        params: CreatePartyToParticipantMappingTxParams,
+    ): Promise<GeneratedTopologyTransaction> {
+        const synchronizerId = await this.#getSynchronizerId();
+        const mapping = buildPartyToParticipantMapping(
+            params.partyId,
+            params.participantIds,
+            params.threshold,
+        );
+        return this.#generateTopologyTransaction(synchronizerId, mapping, params.serial ?? 0);
+    }
+
+    /**
+     * Submits signed topology transactions to the synchronizer store.
+     *
+     * Multiple transactions are submitted atomically in one `AddTransactions` call.
+     * When batching, sign `computeMultiTransactionHash` over all transaction hashes
+     * and attach the same `MultiTransactionSignatures` to each entry.
+     *
+     * Set `proposal: true` on a transaction when the hosting participant must
+     * authorize that mapping afterward.
+     *
+     * @param transactions - One or more signed topology transactions.
+     * @throws {CantonError} If `transactions` is empty.
+     */
+    async submitTopologyTransactions(
+        transactions: readonly SignedTopologyTransaction[],
+    ): Promise<void> {
+        if (transactions.length === 0) {
+            throw new CantonError('AddTransactions requires at least one transaction');
+        }
+        const synchronizerId = await this.#getSynchronizerId();
+        await this.#topologyWrite.addTransactions(
+            AddTransactionsRequest.create({
+                transactions: [...transactions],
+                store: synchronizerStore(synchronizerId),
+            }),
+            { meta: await this.#getMeta() },
+        );
     }
 
+    /** Closes the underlying gRPC transport. */
     close(): void {
         this.#transport.close();
     }

package/src/client/index.ts

@@ -3,3 +3,23 @@ export { CantonClient } from './canton-client';
 export * from './grpc';
 export * from './interface';
 export * from './utils';
+
+// Topology Manager API
+export type { TopologySignature } from './topology/signing';
+export { buildMultiTransactionSignatures, buildSignedTransaction } from './topology/signing';
+export type {
+    CantonGrpcClientOptions,
+    CreateDecentralizedNamespaceDefinitionTxParams,
+    CreateNamespaceDelegationTxParams,
+    CreatePartyToKeyMappingTxParams,
+    CreatePartyToParticipantMappingTxParams,
+    DecentralizedNamespaceDefinitionState,
+    GeneratedTopologyTransaction,
+    NamespaceDelegationState,
+    PartyToKeyMappingState,
+    PartyToParticipantMappingState,
+    TlsOptions,
+    UpdateDecentralizedNamespaceDefinitionTxParams,
+} from './topology/types';
+export { computeDecentralizedNamespace, computeMultiTransactionHash } from './topology/utils';
+export type { SignedTopologyTransaction } from '@canton-network/core-ledger-proto';