@layerzerolabs/common-canton 1.2.8 → 1.2.9

package/src/client/canton-client.ts

@@ -2,7 +2,12 @@ import type { ContractId } from '@daml/types';
 import { once } from 'es-toolkit';
 import { randomUUID } from 'node:crypto';
 
-import { CantonProtocolError, CantonTransportError } from '../errors';
+import {
+    CantonApiError,
+    cantonApiErrorFromResponse,
+    CantonProtocolError,
+    CantonTransportError,
+} from '../errors';
 import {
     DefaultApi,
     type PostV2CommandsAsyncSubmitRequest,
@@ -25,7 +30,7 @@ import {
     type JsActiveContract,
     JsActiveContractFromJSON,
 } from '../open-api/models';
-import type { Configuration } from '../open-api/runtime';
+import { type Configuration, ResponseError } from '../open-api/runtime';
 import type {
     ExternalSignature,
     PreparedTransaction,
@@ -121,33 +126,18 @@ export class CantonClient implements ICantonClient {
     }
 
     /**
-     * Try to extract error body from API response.
-     * Returns the parsed body or null if extraction fails.
+     * Run an API call, normalizing a thrown `ResponseError` into a `CantonApiError`
+     * that carries `errorCategory` (for retry classification). Other errors pass through.
      */
-    async #extractErrorBody(err: unknown): Promise<Record<string, unknown> | null> {
-        if (err && typeof err === 'object' && 'response' in err) {
-            const resp = (err as { response: Response }).response;
-            if (resp && typeof resp.json === 'function') {
-                return (await resp.json().catch(() => null)) as Record<string, unknown> | null;
+    async #invoke<T>(call: () => Promise<T>): Promise<T> {
+        try {
+            return await call();
+        } catch (err) {
+            if (err instanceof ResponseError) {
+                throw await cantonApiErrorFromResponse(err.response);
             }
+            throw err;
         }
-        return null;
-    }
-
-    /**
-     * Throw a CantonProtocolError with extracted error details from API response.
-     * Handles the common pattern of extracting JSON error details from failed requests.
-     *
-     * @param err - The caught error
-     * @param context - Description of the operation (e.g., "DAR upload", "Party allocation")
-     * @throws CantonProtocolError with extracted error details, or re-throws original error
-     */
-    async #throwApiError(err: unknown, context: string): Promise<never> {
-        const body = await this.#extractErrorBody(err);
-        if (body) {
-            throw new CantonProtocolError(`${context} failed: ${JSON.stringify(body)}`);
-        }
-        throw err;
     }
 
     /**
@@ -235,7 +225,7 @@ export class CantonClient implements ICantonClient {
      * Returns all connected synchronizer IDs.
      */
     async connectedSynchronizers(): Promise<string[]> {
-        const response = await this.#api.getV2StateConnectedSynchronizers();
+        const response = await this.#invoke(() => this.#api.getV2StateConnectedSynchronizers());
         const synchronizers = response.connectedSynchronizers ?? [];
         return synchronizers.map((s) => s.synchronizerId).filter((id): id is string => !!id);
     }
@@ -283,19 +273,17 @@ export class CantonClient implements ICantonClient {
         };
 
         try {
-            return await this.#api.postV2Dars(request);
+            return await this.#invoke(() => this.#api.postV2Dars(request));
         } catch (err: unknown) {
             // If skipIfVetted, treat KNOWN_PACKAGE_VERSION as a no-op success
-            if (opts.skipIfVetted) {
-                const body = await this.#extractErrorBody(err);
-                if (body) {
-                    if (body.code === 'KNOWN_PACKAGE_VERSION') {
-                        return { skipped: true, reason: 'already_vetted', details: body };
-                    }
-                    throw new CantonProtocolError(`DAR upload failed: ${JSON.stringify(body)}`);
-                }
+            if (
+                opts.skipIfVetted &&
+                err instanceof CantonApiError &&
+                err.code === 'KNOWN_PACKAGE_VERSION'
+            ) {
+                return { skipped: true, reason: 'already_vetted', details: err.body };
             }
-            throw await this.#throwApiError(err, 'DAR upload');
+            throw err;
         }
     }
 
@@ -321,11 +309,11 @@ export class CantonClient implements ICantonClient {
 
         if (!request.synchronizerId) {
             return this.#ensureSynchronizerId().then((synchronizerId) =>
-                this.#api.postV2DarsValidate({ ...request, synchronizerId }),
+                this.#invoke(() => this.#api.postV2DarsValidate({ ...request, synchronizerId })),
             );
         }
 
-        return this.#api.postV2DarsValidate(request);
+        return this.#invoke(() => this.#api.postV2DarsValidate(request));
     }
 
     // ─────────────────────────────────────────────────────────────────────────
@@ -342,10 +330,12 @@ export class CantonClient implements ICantonClient {
     async listParties(
         opts: { pageSize?: number; pageToken?: string } = {},
     ): Promise<{ parties: string[]; nextPageToken: string }> {
-        const response = await this.#api.getV2Parties({
-            pageSize: opts.pageSize,
-            pageToken: opts.pageToken,
-        });
+        const response = await this.#invoke(() =>
+            this.#api.getV2Parties({
+                pageSize: opts.pageSize,
+                pageToken: opts.pageToken,
+            }),
+        );
 
         return {
             parties: response.partyDetails?.map((p) => p.party) ?? [],
@@ -363,9 +353,11 @@ export class CantonClient implements ICantonClient {
      * ourselves to preserve the actual variant payload.
      */
     async listUserRights(): Promise<UserRight[]> {
-        const apiResponse = await this.#api.getV2UsersUserIdRightsRaw({
-            userId: this.#userId,
-        });
+        const apiResponse = await this.#invoke(() =>
+            this.#api.getV2UsersUserIdRightsRaw({
+                userId: this.#userId,
+            }),
+        );
         const raw = (await apiResponse.raw.json()) as { rights?: UserRight[] };
         return raw.rights ?? [];
     }
@@ -411,19 +403,16 @@ export class CantonClient implements ICantonClient {
     ): Promise<string> {
         const synchronizerId = opts.synchronizerId ?? (await this.#ensureSynchronizerId());
 
-        let response;
-        try {
-            response = await this.#api.postV2Parties({
+        const response = await this.#invoke(() =>
+            this.#api.postV2Parties({
                 allocatePartyRequest: {
                     partyIdHint,
                     synchronizerId,
                     userId: opts.userId ?? '',
                     identityProviderId: opts.identityProviderId ?? '',
                 },
-            });
-        } catch (err: unknown) {
-            throw await this.#throwApiError(err, 'Party allocation');
-        }
+            }),
+        );
 
         const party = response.partyDetails?.party;
         if (!party) {
@@ -460,12 +449,9 @@ export class CantonClient implements ICantonClient {
             },
         };
 
-        let response;
-        try {
-            response = await this.#api.postV2PartiesExternalGenerateTopology(request);
-        } catch (err: unknown) {
-            throw await this.#throwApiError(err, 'External party topology generation');
-        }
+        const response = await this.#invoke(() =>
+            this.#api.postV2PartiesExternalGenerateTopology(request),
+        );
 
         if (!response.partyId || !response.multiHash) {
             throw new CantonProtocolError(
@@ -513,12 +499,7 @@ export class CantonClient implements ICantonClient {
             },
         };
 
-        let response;
-        try {
-            response = await this.#api.postV2PartiesExternalAllocate(request);
-        } catch (err: unknown) {
-            throw await this.#throwApiError(err, 'External party allocation');
-        }
+        const response = await this.#invoke(() => this.#api.postV2PartiesExternalAllocate(request));
 
         if (!response.partyId) {
             throw new CantonProtocolError('allocateExternalParty response missing partyId');
@@ -534,18 +515,16 @@ export class CantonClient implements ICantonClient {
      * POST /v2/users/{userId}/rights
      */
     async grantCanActAs(partyId: string): Promise<void> {
-        try {
-            await this.#api.postV2UsersUserIdRights({
+        await this.#invoke(() =>
+            this.#api.postV2UsersUserIdRights({
                 userId: this.#userId,
                 grantUserRightsRequest: {
                     userId: this.#userId,
                     rights: [{ kind: { canActAs: { value: { party: partyId } } } }],
                     identityProviderId: '',
                 },
-            });
-        } catch (err: unknown) {
-            throw await this.#throwApiError(err, `Grant canActAs for party ${partyId}`);
-        }
+            }),
+        );
     }
 
     /**
@@ -575,12 +554,9 @@ export class CantonClient implements ICantonClient {
             },
         };
 
-        let response;
-        try {
-            response = await this.#api.postV2InteractiveSubmissionPreferredPackages(request);
-        } catch (err: unknown) {
-            throw await this.#throwApiError(err, 'Package lookup');
-        }
+        const response = await this.#invoke(() =>
+            this.#api.postV2InteractiveSubmissionPreferredPackages(request),
+        );
 
         const packageRef = response.packageReferences?.find(
             (ref) => ref.packageName === packageName,
@@ -612,7 +588,7 @@ export class CantonClient implements ICantonClient {
         const commandId = opts.commandId ?? randomUUID();
 
         // Snapshot ledger end before submission so waitForCommand knows where to start polling
-        const ledgerEndResponse = await this.#api.getV2StateLedgerEnd();
+        const ledgerEndResponse = await this.#invoke(() => this.#api.getV2StateLedgerEnd());
         const completionOffset = ledgerEndResponse.offset;
 
         const request: PostV2CommandsAsyncSubmitRequest = {
@@ -627,11 +603,7 @@ export class CantonClient implements ICantonClient {
             },
         };
 
-        try {
-            await this.#api.postV2CommandsAsyncSubmit(request);
-        } catch (err: unknown) {
-            throw await this.#throwApiError(err, 'Command submission');
-        }
+        await this.#invoke(() => this.#api.postV2CommandsAsyncSubmit(request));
 
         return { commandId, completionOffset };
     }
@@ -669,7 +641,9 @@ export class CantonClient implements ICantonClient {
                 streamIdleTimeoutMs,
             };
 
-            const rawResponse = await this.#api.postV2CommandsCompletionsRaw(request);
+            const rawResponse = await this.#invoke(() =>
+                this.#api.postV2CommandsCompletionsRaw(request),
+            );
             const responseText = await rawResponse.raw.text();
             const completions = JSON.parse(responseText) as unknown[];
 
@@ -782,7 +756,9 @@ export class CantonClient implements ICantonClient {
             },
         };
 
-        const response = await this.#api.postV2EventsEventsByContractId(request);
+        const response = await this.#invoke(() =>
+            this.#api.postV2EventsEventsByContractId(request),
+        );
 
         // If archived, contract is not active
         if (response.archived) return undefined;
@@ -849,7 +825,9 @@ export class CantonClient implements ICantonClient {
             },
         };
 
-        const response = await this.#api.postV2EventsEventsByContractId(request);
+        const response = await this.#invoke(() =>
+            this.#api.postV2EventsEventsByContractId(request),
+        );
 
         return {
             created: response.created?.createdEvent,
@@ -867,12 +845,14 @@ export class CantonClient implements ICantonClient {
         updateId: string,
         parties: string[],
     ): Promise<CantonTransaction> {
-        const response = await this.#api.postV2UpdatesUpdateByIdRaw({
-            getUpdateByIdRequest: {
-                updateId,
-                updateFormat: this.#buildUpdateFormat(parties),
-            },
-        });
+        const response = await this.#invoke(() =>
+            this.#api.postV2UpdatesUpdateByIdRaw({
+                getUpdateByIdRequest: {
+                    updateId,
+                    updateFormat: this.#buildUpdateFormat(parties),
+                },
+            }),
+        );
 
         const updateResponse: CantonUpdateResponse = await response.raw.json();
         return this.#parseTransactionFromUpdate(
@@ -888,12 +868,14 @@ export class CantonClient implements ICantonClient {
      * @returns The full transaction including recordTime
      */
     async fetchTransactionByOffset(offset: number, parties: string[]): Promise<CantonTransaction> {
-        const response = await this.#api.postV2UpdatesUpdateByOffsetRaw({
-            getUpdateByOffsetRequest: {
-                offset,
-                updateFormat: this.#buildUpdateFormat(parties),
-            },
-        });
+        const response = await this.#invoke(() =>
+            this.#api.postV2UpdatesUpdateByOffsetRaw({
+                getUpdateByOffsetRequest: {
+                    offset,
+                    updateFormat: this.#buildUpdateFormat(parties),
+                },
+            }),
+        );
 
         const updateResponse: CantonUpdateResponse = await response.raw.json();
         return this.#parseTransactionFromUpdate(
@@ -943,12 +925,9 @@ export class CantonClient implements ICantonClient {
             },
         };
 
-        let response;
-        try {
-            response = await this.#api.postV2InteractiveSubmissionPrepare(request);
-        } catch (error: unknown) {
-            throw await this.#throwApiError(error, 'Interactive submission prepare');
-        }
+        const response = await this.#invoke(() =>
+            this.#api.postV2InteractiveSubmissionPrepare(request),
+        );
         const validated = this.#validatePrepareResponse(response);
 
         return {
@@ -969,7 +948,7 @@ export class CantonClient implements ICantonClient {
         signatures: ExternalSignature[],
     ): Promise<SubmitResult> {
         // Snapshot ledger end so the caller can poll for completion from this point
-        const ledgerEndResponse = await this.#api.getV2StateLedgerEnd();
+        const ledgerEndResponse = await this.#invoke(() => this.#api.getV2StateLedgerEnd());
         const completionOffset = ledgerEndResponse.offset;
 
         const request: PostV2InteractiveSubmissionExecuteRequest = {
@@ -1000,11 +979,7 @@ export class CantonClient implements ICantonClient {
             },
         };
 
-        try {
-            await this.#api.postV2InteractiveSubmissionExecute(request);
-        } catch (error: unknown) {
-            throw await this.#throwApiError(error, 'Interactive submission execute');
-        }
+        await this.#invoke(() => this.#api.postV2InteractiveSubmissionExecute(request));
 
         return { commandId: prepared.commandId, completionOffset };
     }
@@ -1017,7 +992,7 @@ export class CantonClient implements ICantonClient {
      * Get the current ledger end offset.
      */
     async getLedgerEndOffset(): Promise<number> {
-        const response = await this.#api.getV2StateLedgerEnd();
+        const response = await this.#invoke(() => this.#api.getV2StateLedgerEnd());
         return response.offset;
     }
 
@@ -1096,14 +1071,16 @@ export class CantonClient implements ICantonClient {
             parties.map((party) => [party, { cumulative: cumulativeFilter }]),
         );
 
-        const rawResponse = await this.#api.postV2StateActiveContractsRaw({
-            getActiveContractsRequest: {
-                filter: { filtersByParty },
-                verbose: true,
-                activeAtOffset: offset,
-            },
-            limit: opts?.limit,
-        });
+        const rawResponse = await this.#invoke(() =>
+            this.#api.postV2StateActiveContractsRaw({
+                getActiveContractsRequest: {
+                    filter: { filtersByParty },
+                    verbose: true,
+                    activeAtOffset: offset,
+                },
+                limit: opts?.limit,
+            }),
+        );
 
         // Raw response is an array of streamed entries; extract and deserialize contracts
         type RawActiveContractsResponse = Array<{
@@ -1144,20 +1121,22 @@ export class CantonClient implements ICantonClient {
             },
             verbose: false,
         };
-        const rawResponse = await this.#api.postV2UpdatesRaw({
-            getUpdatesRequest: {
-                beginExclusive,
-                endInclusive,
-                verbose: false,
-                updateFormat: {
-                    includeTransactions: {
-                        eventFormat,
-                        transactionShape: 'TRANSACTION_SHAPE_LEDGER_EFFECTS' as const,
+        const rawResponse = await this.#invoke(() =>
+            this.#api.postV2UpdatesRaw({
+                getUpdatesRequest: {
+                    beginExclusive,
+                    endInclusive,
+                    verbose: false,
+                    updateFormat: {
+                        includeTransactions: {
+                            eventFormat,
+                            transactionShape: 'TRANSACTION_SHAPE_LEDGER_EFFECTS' as const,
+                        },
                     },
                 },
-            },
-            limit: opts?.limit,
-        });
+                limit: opts?.limit,
+            }),
+        );
 
         const updateResponses: CantonUpdateResponse[] = await rawResponse.raw.json();
 

package/src/errors.ts

@@ -1,3 +1,5 @@
+import { z } from 'zod';
+
 /**
  * Base error class for Canton SDK errors.
  */
@@ -31,3 +33,52 @@ export class CantonProtocolError extends CantonError {
         super(message);
     }
 }
+
+/** A JSON Ledger API error, normalized from a non-2xx response's `JsCantonError` body. */
+export class CantonApiError extends CantonError {
+    constructor(
+        message: string,
+        /** Canton error category (1–14). See {@link isRetryableCantonError}. */
+        public readonly errorCategory: number | undefined,
+        /** Canton error code id, e.g. `CONTRACT_NOT_FOUND`. */
+        public readonly code: string | undefined,
+        public readonly status: number,
+        public readonly body: unknown,
+    ) {
+        super(message);
+    }
+}
+
+const cantonApiErrorBodySchema = z.object({
+    errorCategory: z.number(),
+    code: z.string(),
+    cause: z.string(),
+});
+
+/** Build a {@link CantonApiError} from a non-2xx `Response`, reading a clone of the body. */
+export async function cantonApiErrorFromResponse(response: Response): Promise<CantonApiError> {
+    const body = await response.json().catch(() => undefined);
+    const fields = cantonApiErrorBodySchema.safeParse(body).data;
+    const message = `Canton API error ${response.status}${fields?.code ? ` [${fields.code}]` : ''}${
+        fields?.cause ? `: ${fields.cause}` : ''
+    }`;
+    return new CantonApiError(message, fields?.errorCategory, fields?.code, response.status, body);
+}
+
+// Canton's `errorCategory` (1–14) is the retry signal, not the HTTP status.
+// See https://docs.canton.network/appdev/reference/error-codes
+const NON_RETRYABLE_CANTON_ERROR_CATEGORIES: ReadonlySet<number> = new Set([
+    5, 9, 10, 11, 12, 13, 14,
+]);
+
+/**
+ * Non-retryable Categories: 5, 9, 10, 11, 12, 13, 14.  Everything else is retryable.
+ * Errors with no category (transport/connection failures) are treated as retryable.
+ */
+export function isRetryableCantonError(error: unknown): boolean {
+    return (
+        !(error instanceof CantonApiError) ||
+        error.errorCategory === undefined ||
+        !NON_RETRYABLE_CANTON_ERROR_CATEGORIES.has(error.errorCategory)
+    );
+}