@layerzerolabs/common-canton 1.2.69 → 1.2.70

package/src/errors.ts

@@ -1,84 +0,0 @@
-import { z } from 'zod';
-
-/**
- * Base error class for Canton SDK errors.
- */
-export class CantonError extends Error {
-    constructor(message: string) {
-        super(message);
-        this.name = this.constructor.name;
-    }
-}
-
-/**
- * Network/transport layer errors (timeouts, 5xx, connection issues).
- */
-export class CantonTransportError extends CantonError {
-    constructor(
-        message: string,
-        public readonly status?: number,
-    ) {
-        super(message);
-    }
-}
-
-/**
- * Protocol errors (unexpected response shapes, missing required fields).
- */
-export class CantonProtocolError extends CantonError {
-    constructor(
-        message: string,
-        public readonly details?: unknown,
-    ) {
-        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)
-    );
-}

package/src/events.ts

@@ -1,113 +0,0 @@
-import { NonEmittableError } from '@layerzerolabs/common-error-utils';
-
-import type { CantonTransaction, ICantonClient } from './client';
-import type { CreatedEvent, ExercisedEvent } from './open-api/models';
-import { templateIdMatches } from './refresh/deployment-address';
-import { cantonTransactionWithResultSchema } from './transaction';
-
-/**
- * Finds a CreatedEvent matching the expected templateId whose signatories
- * are a subset of the provided actAs parties (ledger signatories ⊆ expected).
- * Opposite of `areExpectedSignatories` on the refresh path.
- */
-export const findMatchingCreatedEvent = (
-    createdEvents: CreatedEvent[],
-    expectedTemplateId: string,
-    expectedSignatories: string[],
-): CreatedEvent | undefined => {
-    const expectedSet = new Set(expectedSignatories);
-    return createdEvents.find((event) => {
-        if (!templateIdMatches(event.templateId, expectedTemplateId)) return false;
-        const signatories = event.signatories ?? [];
-        return signatories.length > 0 && signatories.every((s) => expectedSet.has(s));
-    });
-};
-
-/**
- * Fetches a transaction by updateId and returns all CreatedEvents.
- */
-export const fetchCreatedEvents = async (
-    client: ICantonClient,
-    updateId: string,
-    parties: string[],
-): Promise<CreatedEvent[]> => {
-    const cantonTx = await client.fetchTransactionByUpdateId(updateId, parties);
-    return (
-        cantonTx.events
-            ?.filter((event): event is { CreatedEvent: CreatedEvent } => 'CreatedEvent' in event)
-            .map((event) => event.CreatedEvent) ?? []
-    );
-};
-
-/**
- * Parses a Canton transaction-with-result, fetches the created events from the ledger,
- * and returns the first CreatedEvent matching the submitted command's templateId and actAs
- * signatories. Returns null if the transaction is falsy, not successful, or has no match.
- */
-export const findMatchingCreatedEventFromTx = async (
-    client: ICantonClient,
-    tx: unknown,
-): Promise<CreatedEvent | null> => {
-    const parsed = cantonTransactionWithResultSchema.safeParse(tx);
-    if (!parsed.success) return null;
-
-    if (parsed.data.result.type !== 'success') return null;
-
-    const {
-        populatedTransaction: { actAs, unresolvedCommands },
-    } = parsed.data;
-    const updateId = parsed.data.result.minedTxHash;
-
-    if (!updateId || !actAs.length) return null;
-
-    const createCommand = unresolvedCommands.find((cmd) => 'createCommand' in cmd);
-    if (!createCommand || !('createCommand' in createCommand)) return null;
-
-    const createdEvents = await fetchCreatedEvents(client, updateId, actAs);
-    return (
-        findMatchingCreatedEvent(createdEvents, createCommand.createCommand.templateId, actAs) ??
-        null
-    );
-};
-
-/**
- * Checks that a Canton deploy transaction resulted in a CreatedEvent
- * matching the submitted command's templateId and actAs signatories.
- */
-export const cantonDeploymentSucceeded = async (
-    client: ICantonClient,
-    txWithResult: unknown,
-): Promise<boolean> => {
-    return (await findMatchingCreatedEventFromTx(client, txWithResult)) != null;
-};
-
-/**
- * Waits for a contract to be archived and returns the transaction that archived it.
- * Throws NonEmittableError if the contract is not yet archived.
- */
-export const waitForArchival = async (
-    client: ICantonClient,
-    contractId: string,
-    parties: string[],
-): Promise<CantonTransaction> => {
-    const { archived } = await client.fetchEventsByContractId(contractId, parties);
-    if (archived) {
-        return client.fetchTransactionByOffset(archived.offset, parties);
-    }
-    throw new NonEmittableError(`Contract ${contractId} is not archived yet`);
-};
-
-/** Returns the first exercised event on `contractId` in a transaction tree, if any. */
-export const getExercisedEvent = (
-    transaction: CantonTransaction,
-    contractId: string,
-): ExercisedEvent | undefined => {
-    for (const event of transaction.events ?? []) {
-        if (!('ExercisedEvent' in event)) continue;
-        const { ExercisedEvent: exercised } = event;
-        if (exercised.contractId === contractId) {
-            return exercised;
-        }
-    }
-    return undefined;
-};

package/src/minFee.ts

@@ -1,12 +0,0 @@
-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);

package/src/provider.ts

@@ -1,195 +0,0 @@
-import {
-    ClientCredentialsTokenProvider,
-    type ClientCredentialsTokenProviderConfig,
-} from './auth/client-credentials-token-provider';
-import { LocalTokenProvider } from './auth/local-token-provider';
-import type { TokenProvider } from './auth/token-provider';
-import { CantonClient } from './client/canton-client';
-import { CantonGrpcClient } from './client/grpc';
-import type { ICantonClient } from './client/interface';
-import { Configuration } from './open-api/runtime';
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Provider Type
-// ─────────────────────────────────────────────────────────────────────────────
-
-/**
- * - {@link client} — JSON Ledger API (commands, queries, updates)
- * - {@link grpcClient} — gRPC Admin API (topology transactions, namespace queries)
- * - {@link tokenProvider} — Shared Bearer-token source used by both transports
- * - {@link walletUrl} — Canton Network validator wallet (scan-proxy CIP-56 endpoints)
- */
-export type CantonChainProvider = {
-    client: ICantonClient;
-    grpcClient: CantonGrpcClient;
-    tokenProvider: TokenProvider;
-    /** Validator wallet URL for scan-proxy CIP-56 endpoints. Required. */
-    walletUrl: string;
-};
-
-// ─────────────────────────────────────────────────────────────────────────────
-// URI Parsing
-// ─────────────────────────────────────────────────────────────────────────────
-
-export type CantonChainUriParams = {
-    /** Base URL of the JSON Ledger API (e.g. "http://localhost:5975") */
-    jsonApiUrl: string;
-    /** Host:port of the gRPC Admin API (e.g. "localhost:5076") */
-    adminApiHost: string;
-    /** Ledger API user ID (default: "participant_admin") */
-    userId: string;
-    /** Parties granted `actAs` on localnet tokens (comma-separated in the URI). */
-    actAs: string[];
-    /** Validator wallet URL for scan-proxy CIP-56 endpoints (e.g. "http://localhost:7201"). Required. */
-    walletUrl: string;
-    /** OAuth2 client credentials config — present only for non-local environments */
-    oauth2?: ClientCredentialsTokenProviderConfig;
-};
-
-/**
- * Parse a Canton chain provider URI into its constituent parts.
- *
- * URI format:
- *   `<json-api-base>?admin-api=<host:port>&user-id=<id>&wallet-url=<url>[&token-url=...&client-id=...&client-secret=...&scope=...&audience=...]`
- *
- * The base URL (everything before the query string) is the JSON Ledger API endpoint.
- * Canton-specific params are extracted and removed; any remaining query params are
- * preserved on the JSON API URL.
- *
- * When `client-secret` is omitted from the URI, `CANTON_CLIENT_SECRET` is read from the
- * environment.
- */
-export function parseCantonChainUri(uri: string): CantonChainUriParams {
-    const url = new URL(uri);
-
-    const adminApiHost = url.searchParams.get('admin-api');
-    if (!adminApiHost) {
-        throw new Error('Canton provider URI missing required "admin-api" query parameter');
-    }
-
-    const userId = url.searchParams.get('user-id') ?? 'participant_admin';
-    const actAsParam = url.searchParams.get('act-as');
-    const actAs =
-        actAsParam
-            ?.split(',')
-            .map((party) => party.trim())
-            .filter((party) => party.length > 0) ?? [];
-    const walletUrl = url.searchParams.get('wallet-url');
-    if (!walletUrl) {
-        throw new Error('Canton provider URI missing required "wallet-url" query parameter');
-    }
-    const tokenUrl = url.searchParams.get('token-url') ?? undefined;
-    const clientId = url.searchParams.get('client-id') ?? undefined;
-    // Prefer URI param; fall back to env so secrets are not committed in provider configs.
-    const clientSecret =
-        url.searchParams.get('client-secret') ??
-        // eslint-disable-next-line turbo/no-undeclared-env-vars -- runtime OAuth secret, not a turbo task input
-        process.env.CANTON_CLIENT_SECRET ??
-        undefined;
-    const scope = url.searchParams.get('scope') ?? undefined;
-    const audience = url.searchParams.get('audience') ?? undefined;
-
-    for (const key of [
-        'admin-api',
-        'user-id',
-        'act-as',
-        'wallet-url',
-        'sequencer-url',
-        'sequencer-validators',
-        'sequencer-quorum',
-        'token-url',
-        'client-id',
-        'client-secret',
-        'scope',
-        'audience',
-    ]) {
-        url.searchParams.delete(key);
-    }
-
-    const jsonApiUrl = url.toString().replace(/\/$/, '');
-
-    const oauth2 =
-        tokenUrl && clientId && clientSecret
-            ? { tokenUrl, clientId, clientSecret, scope, audience }
-            : undefined;
-
-    return {
-        jsonApiUrl,
-        adminApiHost,
-        userId,
-        actAs,
-        walletUrl,
-        oauth2,
-    };
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Provider Factory
-// ─────────────────────────────────────────────────────────────────────────────
-
-export type CreateCantonChainProviderOptions = {
-    /** Raw provider URI (from provider config) */
-    uri: string;
-    /** When true, uses LocalTokenProvider (self-signed JWTs) instead of OAuth2 */
-    isLocal: boolean;
-};
-
-/**
- * Create a {@link CantonChainProvider} from a provider URI.
- *
- * - **isLocal=true**: Uses {@link LocalTokenProvider} with admin-level access (self-signed JWTs)
- *   over an unencrypted admin channel, allowed for a loopback admin host only.
- * - **isLocal=false**: Uses {@link ClientCredentialsTokenProvider} with OAuth2 client
- *   credentials extracted from the URI query parameters, over a TLS admin channel.
- */
-export function createCantonChainProvider({
-    uri,
-    isLocal,
-}: CreateCantonChainProviderOptions): CantonChainProvider {
-    const params = parseCantonChainUri(uri);
-
-    const tokenProvider = createTokenProvider(params, isLocal);
-
-    // ── JSON Ledger API Client ──────────────────────────────────────────
-    const configuration = new Configuration({
-        basePath: params.jsonApiUrl,
-        accessToken: () => tokenProvider.getToken(),
-    });
-    const client = new CantonClient(configuration, params.userId, {
-        walletUrl: params.walletUrl,
-        tokenProvider,
-    });
-
-    // ── gRPC Admin API Client ───────────────────────────────────────────
-    const grpcClient = new CantonGrpcClient({
-        host: params.adminApiHost,
-        tokenProvider,
-        insecureTransport: isLocal,
-    });
-
-    return {
-        client,
-        grpcClient,
-        tokenProvider,
-        walletUrl: params.walletUrl,
-    };
-}
-
-function createTokenProvider(params: CantonChainUriParams, isLocal: boolean): TokenProvider {
-    if (isLocal) {
-        return new LocalTokenProvider({
-            userId: params.userId,
-            actAs: params.actAs,
-            admin: true,
-        });
-    }
-
-    // TODO(canton): add other prod auth methods (direct JWT passthrough, etc.).
-    if (!params.oauth2) {
-        throw new Error(
-            'Canton provider requires OAuth2 credentials (token-url, client-id, client-secret in URI or CANTON_CLIENT_SECRET)',
-        );
-    }
-
-    return new ClientCredentialsTokenProvider(params.oauth2);
-}

package/src/refresh/README.md

@@ -1,119 +0,0 @@
----
-owner: Protocol team
-reviewed: 2026-10-01
----
-
-# Canton refresh plans
-
-A transaction producer or activity can attach a `refreshPlan` to
-`CantonPopulatedTransaction` when command inputs may become stale before signing. Protocol SDKs
-should still build ordinary Canton commands with current values; they should not emit deferred
-sentinels or define refresh policy.
-
-At sign time, the common Canton transaction layer:
-
-1. clones `unresolvedCommands`;
-2. resolves each refresh against current ledger, wallet, or clock state;
-3. applies replacements only to the declared command targets;
-4. replaces refresh-owned disclosures and deduplicates the result; and
-5. passes the resulting `commands` and `disclosedContracts` to `prepareForSigning`.
-
-The persisted unresolved values remain the immutable baseline. Do not combine a `refreshPlan` with
-legacy `CANTON_DEFERRED` sentinels.
-
-## Defining a plan
-
-```ts
-const populatedTransaction: CantonPopulatedTransaction = {
-    unresolvedCommands: prepared.commands,
-    unresolvedDisclosedContracts: prepared.disclosedContracts,
-    actAs: prepared.actAs,
-    refreshPlan: {
-        commands: [
-            {
-                resolver: {
-                    type: 'activeContract',
-                    selector: {
-                        queryAs: { party: executorParty },
-                        templateId: '#layerzero-executor:Executor:Executor',
-                        expectedSignatories: [executorParty],
-                    },
-                    selection: { kind: 'exactlyOne' },
-                },
-                targets: [
-                    {
-                        commandIndex: 0,
-                        command: 'exercise',
-                        field: 'contractId',
-                    },
-                ],
-            },
-            {
-                resolver: {
-                    type: 'timestamp',
-                },
-                targets: [
-                    {
-                        commandIndex: 0,
-                        command: 'exercise',
-                        choice: 'DelegateLzReceive',
-                        arguments: [{ path: [{ field: 'timestamp' }] }],
-                    },
-                ],
-            },
-        ],
-    },
-};
-```
-
-`refreshPlan.commands` contains the instructions that resolve and patch volatile Canton command
-values. Each instruction groups one `resolver` with every command target that consumes its output,
-so external reads and correlated timestamps are shared. Some resolvers also emit the fresh
-disclosures required by their values.
-
-`commandIndex` selects an entry in `unresolvedCommands`. `command` validates that the entry has the
-required create or exercise shape. Each target groups its nested `arguments` under one guarded
-command: exercise targets require `choice`, while create targets require `template`.
-An exercise `contractId` target remains a separate variant and does not have a choice guard.
-
-Nested paths support:
-
-- `{ field: 'name' }` for object fields;
-- `{ index: 0 }` for array entries; and
-- `{ damlMapKey: 'timestamp' }` for entries in Daml maps represented as key-value tuples.
-
-Path segments can be mixed and repeated, so nested Daml maps use consecutive `damlMapKey` segments.
-Timestamp `offsetMs` is configured per argument.
-
-Only an `activeContract` refresh with `selection.kind: 'exactlyOne'` can target an exercise
-`contractId`. Collection-valued `activeContract` selections and `amuletContext` refreshes target
-choice or create arguments. Timestamp refreshes also require a non-empty nested argument path.
-
-## Command resolvers
-
-- `activeContract`: queries authenticated active contracts, then selects `exactlyOne`, `all`, or
-  enough contracts for a numeric field to be greater than or equal to a requested value:
-  `{ kind: 'gte', field: 'amount', value: feeAmount }`.
-- `amuletContext`: refreshes the wallet-provided context, ExternalPartyAmuletRules CID, and
-  disclosures.
-- `timestamp`: refreshes one or more Canton Time values from the same current instant; `offsetMs`
-  can derive an expiry from that instant. Timestamp refreshes run after all ledger and wallet
-  refreshes regardless of declaration order.
-
-`gte.field` may be a dotted create-argument path. Its value may be a Daml Decimal string or an
-Amulet-style record containing `initialAmount`.
-
-When the persisted baseline contains disclosures owned by a command refresh, list their contract
-IDs under `refreshPlan.disclosures.excludeBaselineCids`. The IDs must be unique and must exist in
-`unresolvedDisclosedContracts`. Those baseline records are excluded before fresh resolver
-disclosures are added; the IDs identify old records, not their replacements.
-
-Active-contract queries always request `createdEventBlob`, and conflicting disclosures for the
-same CID fail.
-
-Keep `queryAs` (ledger visibility) separate from `expectedSignatories` (authority), and use
-`stateFilter` for semantic payload identity such as an owner. Missing filter paths fail closed.
-
-See
-[`createExecuteTransaction()`](../../../../../../migrated/offchain-monorepo/packages/sdks/executor-sdk/src/canton/index.ts)
-for the first complete activity-side example.