@layerzerolabs/common-canton 0.2.102 → 0.2.104

package/dist/types.js

@@ -1,4 +1,4 @@
-export { CommandStatus, buildTemplateId } from './75QKYROD.js';
+export { CommandStatus, buildTemplateId } from './CXNQT7WY.js';
 import './VUOMXK5T.js';
 //# sourceMappingURL=types.js.map
 //# sourceMappingURL=types.js.map

package/eslint.config.js

@@ -5,6 +5,8 @@ export default [
     ...baseConfig,
     {
         // TODO Cover source code in `scripts` and `tests` directories.
-        ignores: ['dist', 'node_modules', 'scripts', 'test'],
+        // src/open-api is generated by openapi-generator at build time (gitignored); its emitted
+        // eslint-disable directives trip --max-warnings 0, so exclude it from linting.
+        ignores: ['dist', 'node_modules', 'scripts', 'test', 'src/open-api'],
     },
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@layerzerolabs/common-canton",
-  "version": "0.2.102",
+  "version": "0.2.104",
   "private": false,
   "description": "Canton VM client and utilities",
   "license": "MIT",
@@ -21,8 +21,8 @@
     "@protobuf-ts/grpc-transport": "^2.9.4",
     "es-toolkit": "^1.39.10",
     "zod": "4.3.5",
-    "@layerzerolabs/common-chain-model": "0.2.102",
-    "@layerzerolabs/typescript-utils": "0.2.102"
+    "@layerzerolabs/common-chain-model": "0.2.104",
+    "@layerzerolabs/typescript-utils": "0.2.104"
   },
   "devDependencies": {
     "@types/node": "^22.18.6",
@@ -31,12 +31,12 @@
     "tsup": "^8.4.0",
     "typescript": "^5.8.2",
     "vitest": "^3.2.3",
-    "@layerzerolabs/typescript-configuration": "0.2.102",
-    "@layerzerolabs/tsup-configuration": "0.2.102",
-    "@layerzerolabs/eslint-configuration": "^0.2.102",
-    "@layerzerolabs/ver-signer-adapter": "0.2.102",
-    "@layerzerolabs/vm-tooling-canton": "0.2.102",
-    "@layerzerolabs/vitest-configuration": "0.2.102"
+    "@layerzerolabs/eslint-configuration": "^0.2.104",
+    "@layerzerolabs/tsup-configuration": "0.2.104",
+    "@layerzerolabs/typescript-configuration": "0.2.104",
+    "@layerzerolabs/ver-signer-adapter": "0.2.104",
+    "@layerzerolabs/vitest-configuration": "0.2.104",
+    "@layerzerolabs/vm-tooling-canton": "0.2.104"
   },
   "publishConfig": {
     "access": "restricted",

package/src/client/canton-client.ts

@@ -29,6 +29,7 @@ import type {
     PreparedTransaction,
     SubmitActors,
     SubmitResult,
+    UserRight,
     WaitOptions,
     WaitResult,
 } from '../types';
@@ -304,6 +305,49 @@ export class CantonClient implements ICantonClient {
         };
     }
 
+    /**
+     * Return the rights granted to the current user (this.#userId).
+     *
+     * Bypasses the OpenAPI generator's typed `Kind` converter, which is
+     * broken: `instanceOfKindOneOf` checks lowercase `canActAs in value`, but
+     * `KindOneOfFromJSONTyped` reads uppercase `json['CanActAs']`, so the
+     * typed client returns every `kind` as `{}`. We parse the raw JSON
+     * ourselves to preserve the actual variant payload.
+     */
+    async listUserRights(): Promise<UserRight[]> {
+        const apiResponse = await this.#api.getV2UsersUserIdRightsRaw({
+            userId: this.#userId,
+        });
+        const raw = (await apiResponse.raw.json()) as { rights?: UserRight[] };
+        return raw.rights ?? [];
+    }
+
+    /**
+     * Return the parties the current user has CanActAs or CanReadAs rights
+     * for. Convenience wrapper over `listUserRights()` for the common case
+     * where the caller just needs party-scoped access (e.g. to query events
+     * or fetch transactions).
+     *
+     * Use this instead of `listParties()` when the caller only has scoped
+     * rights — `listParties()` returns *all* parties on the participant
+     * (including DSO, splice parties), and Canton returns 403 if you query
+     * as a party you can't read.
+     */
+    async listUserParties(): Promise<string[]> {
+        const rights = await this.listUserRights();
+        const parties = new Set<string>();
+        for (const right of rights) {
+            // Only `CanActAs` / `CanReadAs` carry a party; the other four
+            // variants (ParticipantAdmin, IdentityProviderAdmin,
+            // CanReadAsAnyParty, CanExecuteAsAnyParty) have empty payloads.
+            const party = right.kind.CanActAs?.value.party ?? right.kind.CanReadAs?.value.party;
+            if (party !== undefined) {
+                parties.add(party);
+            }
+        }
+        return [...parties];
+    }
+
     /**
      * Allocate a new party on the participant node.
      *
@@ -736,7 +780,12 @@ export class CantonClient implements ICantonClient {
             },
         };
 
-        const response = await this.#api.postV2InteractiveSubmissionPrepare(request);
+        let response;
+        try {
+            response = await this.#api.postV2InteractiveSubmissionPrepare(request);
+        } catch (error: unknown) {
+            throw await this.#throwApiError(error, 'Interactive submission prepare');
+        }
         const validated = this.#validatePrepareResponse(response);
 
         return {
@@ -788,7 +837,11 @@ export class CantonClient implements ICantonClient {
             },
         };
 
-        await this.#api.postV2InteractiveSubmissionExecute(request);
+        try {
+            await this.#api.postV2InteractiveSubmissionExecute(request);
+        } catch (error: unknown) {
+            throw await this.#throwApiError(error, 'Interactive submission execute');
+        }
 
         return { commandId: prepared.commandId, completionOffset };
     }
@@ -868,6 +921,12 @@ export class CantonClient implements ICantonClient {
     /**
      * Stream transactions from a given offset.
      *
+     * Uses `updateFormat` with `TRANSACTION_SHAPE_LEDGER_EFFECTS` so consumers
+     * receive `ExercisedEvent`s (e.g. the request-poller depends on
+     * `Request_Create` exercise results). The deprecated legacy `filter`
+     * shape would default to `ACS_DELTA`, which only emits Created/Archived
+     * events and silently drops every exercise on the wire.
+     *
      * @param party - Party to query as
      * @param beginExclusive - Start offset (exclusive)
      * @param endInclusive - End offset (inclusive)
@@ -880,16 +939,23 @@ export class CantonClient implements ICantonClient {
         endInclusive: number,
         opts?: { templateIds?: string[]; limit?: number },
     ): Promise<CantonUpdate[]> {
+        const eventFormat = {
+            filtersByParty: {
+                [party]: { cumulative: this.#buildCumulativeFilters(opts?.templateIds) },
+            },
+            verbose: false,
+        };
         const rawResponse = await this.#api.postV2UpdatesRaw({
             getUpdatesRequest: {
                 beginExclusive,
                 endInclusive,
-                filter: {
-                    filtersByParty: {
-                        [party]: { cumulative: this.#buildCumulativeFilters(opts?.templateIds) },
+                verbose: false,
+                updateFormat: {
+                    includeTransactions: {
+                        eventFormat,
+                        transactionShape: 'TRANSACTION_SHAPE_LEDGER_EFFECTS' as const,
                     },
                 },
-                verbose: true,
             },
             limit: opts?.limit,
         });

package/src/client/interface.ts

@@ -17,6 +17,7 @@ import type {
     PreparedTransaction,
     SubmitActors,
     SubmitResult,
+    UserRight,
     WaitOptions,
     WaitResult,
 } from '../types';
@@ -178,6 +179,22 @@ export interface ICantonClient {
         pageToken?: string;
     }): Promise<{ parties: string[]; nextPageToken: string }>;
 
+    /**
+     * Return the rights granted to the current user (this user's userId in
+     * the underlying token).
+     *
+     * GET /v2/users/{userId}/rights
+     */
+    listUserRights(): Promise<UserRight[]>;
+
+    /**
+     * Convenience wrapper over `listUserRights()` returning just the parties
+     * the current user has CanActAs / CanReadAs rights for. Use instead of
+     * `listParties()` when the call requires scoped read access (Canton
+     * returns 403 if you query as a party you can't read).
+     */
+    listUserParties(): Promise<string[]>;
+
     /**
      * Allocate a new party on the participant node.
      *

package/src/index.ts

@@ -1,6 +1,7 @@
 export * from './auth';
 export * from './events';
 export * from './provider';
+export * from './senderPlaceholder';
 export * from './transaction';
 
 // Core types
@@ -13,6 +14,8 @@ export {
     type SubmitActors,
     type SubmitResult,
     type TemplateId,
+    type UserRight,
+    type UserRightKind,
     type WaitOptions,
     type WaitResult,
 } from './types';

package/src/provider.ts

@@ -24,6 +24,9 @@ export type CantonProvider = {
     client: ICantonClient;
     grpcClient: CantonGrpcClient;
     tokenProvider: TokenProvider;
+    /** Validator wallet URL for scan-proxy CIP-56 endpoints. Required — amulet fee
+     *  payment needs it on every Canton transaction; enforced in {@link parseCantonUri}. */
+    walletUrl: string;
 };
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -37,6 +40,8 @@ export type CantonUriParams = {
     adminApiHost: string;
     /** Ledger API user ID (default: "participant_admin") */
     userId: string;
+    /** Validator wallet URL for scan-proxy CIP-56 endpoints (e.g. "http://localhost:7201") */
+    walletUrl: string;
     /** OAuth2 client credentials config — present only for non-local environments */
     oauth2?: ClientCredentialsTokenProviderConfig;
 };
@@ -54,25 +59,33 @@ export type CantonUriParams = {
 export function parseCantonUri(uri: string): CantonUriParams {
     const url = new URL(uri);
 
-    // Extract Canton-specific params
+    // `admin-api` is a gRPC `host:port` (no scheme), so it carries no TLS signal.
+    // TODO(CANTON): convey TLS for non-localhost (e.g. `&admin-api-tls=1` or `admin-api=grpcs://host:port`).
     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';
+
+    // Required: amulet fee payment hits the validator wallet scan-proxy on every
+    // Canton transaction, so a provider without it can't transact. Fail at parse
+    // time rather than guarding each downstream use.
+    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;
     const clientSecret = url.searchParams.get('client-secret') ?? undefined;
     const scope = url.searchParams.get('scope') ?? undefined;
     const audience = url.searchParams.get('audience') ?? undefined;
 
-    // Remove Canton params to get clean JSON API URL
     for (const key of [
         'admin-api',
         'user-id',
+        'wallet-url',
         'token-url',
-        // TODO: check if these are acceptable in our providers config, we do the same with api-keys currently.
         'client-id',
         'client-secret',
         'scope',
@@ -81,7 +94,6 @@ export function parseCantonUri(uri: string): CantonUriParams {
         url.searchParams.delete(key);
     }
 
-    // Reconstruct clean base URL (origin + pathname, plus any remaining query params)
     const jsonApiUrl = url.toString().replace(/\/$/, '');
 
     const oauth2 =
@@ -89,7 +101,7 @@ export function parseCantonUri(uri: string): CantonUriParams {
             ? { tokenUrl, clientId, clientSecret, scope, audience }
             : undefined;
 
-    return { jsonApiUrl, adminApiHost, userId, oauth2 };
+    return { jsonApiUrl, adminApiHost, userId, walletUrl, oauth2 };
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -131,7 +143,12 @@ export function createCantonProvider({
         tokenProvider,
     });
 
-    return { client, grpcClient, tokenProvider };
+    return {
+        client,
+        grpcClient,
+        tokenProvider,
+        walletUrl: params.walletUrl,
+    };
 }
 
 function createTokenProvider(params: CantonUriParams, isLocal: boolean): TokenProvider {
@@ -143,8 +160,7 @@ function createTokenProvider(params: CantonUriParams, isLocal: boolean): TokenPr
         });
     }
 
-    // TODO: add other authentication methods for prod: such as direct jwt passthrough, oauth2 client credentials, etc.
-    // Non-local: require OAuth2 client credentials
+    // 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 the provider URI',

package/src/senderPlaceholder.ts

@@ -0,0 +1,119 @@
+import { mapValues } from 'es-toolkit';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Generic JSON-tree visitors
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Result of a leaf check: either the leaf has been replaced (with `value`),
+ * or `undefined` to leave it alone and recurse into its children.
+ */
+type LeafResult = { value: unknown } | undefined;
+
+/** Walk a JSON value and rewrite leaves matched by `replace`; recursion stops at a swapped leaf. */
+const visit = <T>(value: T, replace: (leaf: unknown) => LeafResult): T => {
+    const result = replace(value);
+    if (result) return result.value as T;
+    if (Array.isArray(value)) {
+        return value.map((item) => visit(item, replace)) as T;
+    }
+    if (value !== null && typeof value === 'object') {
+        return mapValues(value as Record<string, unknown>, (item) => visit(item, replace)) as T;
+    }
+    return value;
+};
+
+/** True if `predicate` matches any leaf or sub-value in the tree. */
+const containsLeaf = (value: unknown, predicate: (leaf: unknown) => boolean): boolean => {
+    if (predicate(value)) return true;
+    if (Array.isArray(value)) return value.some((item) => containsLeaf(item, predicate));
+    return (
+        value !== null &&
+        typeof value === 'object' &&
+        Object.values(value).some((item) => containsLeaf(item, predicate))
+    );
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Sender placeholder
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Sentinel emitted in place of the sender `Party` when the sender is unknown at
+ * create time; substituted for the real party at sign time.
+ */
+export const CANTON_SENDER_PLACEHOLDER = '<<CANTON_SENDER_PLACEHOLDER>>';
+
+/**
+ * Returns true if `value` is the Canton sender placeholder.
+ */
+export const isCantonSenderPlaceholder = (value: string): boolean =>
+    value === CANTON_SENDER_PLACEHOLDER;
+
+/** Replace every {@link CANTON_SENDER_PLACEHOLDER} in a command tree with the actual sender party ID. */
+export const replaceCantonSenderPlaceholders = <T>(value: T, senderParty: string): T =>
+    visit(value, (leaf) =>
+        leaf === CANTON_SENDER_PLACEHOLDER ? { value: senderParty } : undefined,
+    );
+
+/** Returns true if the command tree contains the sender placeholder anywhere. */
+export const containsCantonSenderPlaceholder = (value: unknown): boolean =>
+    containsLeaf(value, (leaf) => leaf === CANTON_SENDER_PLACEHOLDER);
+
+// ─────────────────────────────────────────────────────────────────────────────
+// AmuletCids placeholder
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Sentinel emitted as the sole element of the `amuletCids` array
+ * (`amuletCids: [CANTON_AMULET_CIDS_PLACEHOLDER]`); substituted for the resolved
+ * sender's Amulet contract IDs at sign time.
+ */
+export const CANTON_AMULET_CIDS_PLACEHOLDER = '<<CANTON_AMULET_CIDS_PLACEHOLDER>>';
+
+const isAmuletCidsPlaceholderArray = (value: unknown): value is [string] =>
+    Array.isArray(value) && value.length === 1 && value[0] === CANTON_AMULET_CIDS_PLACEHOLDER;
+
+/**
+ * Returns true if the command tree contains an amulet-cids placeholder array
+ * anywhere — i.e. an array `[CANTON_AMULET_CIDS_PLACEHOLDER]`.
+ */
+export const containsCantonAmuletCidsPlaceholder = (value: unknown): boolean =>
+    containsLeaf(value, isAmuletCidsPlaceholderArray);
+
+/**
+ * Recursively walks a JSON-serializable value and replaces every
+ * `[CANTON_AMULET_CIDS_PLACEHOLDER]` array with the supplied list of resolved
+ * Amulet contract IDs.
+ */
+export const replaceCantonAmuletCidsPlaceholder = <T>(value: T, amuletCids: string[]): T =>
+    visit(value, (leaf) =>
+        isAmuletCidsPlaceholderArray(leaf) ? { value: amuletCids } : undefined,
+    );
+
+/** Sentinel for a choice's `extraArgs.context`, replaced with the freshly-fetched
+ *  amulet choice context at sign time. */
+export const CANTON_AMULET_CONTEXT_PLACEHOLDER = '<<CANTON_AMULET_CONTEXT_PLACEHOLDER>>';
+
+/** Sentinel for the exercised ExternalPartyAmuletRules contract id, re-pinned to the
+ *  freshly-fetched amulet fee bundle at sign time. */
+export const CANTON_AMULET_RULES_CID_PLACEHOLDER = '<<CANTON_AMULET_RULES_CID_PLACEHOLDER>>';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Generic placeholder helpers (sentinel-agnostic)
+//
+// Used by the sign-time refresh executor, which receives the sentinel to match as
+// data (from the transaction's refreshSpec, or a known amulet sentinel) instead of
+// hardcoding it here — keeping these helpers free of any contract knowledge.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Returns true if any scalar leaf in the tree equals `placeholder`. */
+export const containsPlaceholderValue = (value: unknown, placeholder: string): boolean =>
+    containsLeaf(value, (leaf) => leaf === placeholder);
+
+/** Replace every scalar sentinel leaf equal to `placeholder` with `replacement`. */
+export const replacePlaceholderValue = <T>(
+    value: T,
+    placeholder: string,
+    replacement: unknown,
+): T => visit(value, (leaf) => (leaf === placeholder ? { value: replacement } : undefined));

package/src/transaction.ts

@@ -10,9 +10,8 @@ import type { PartialBy } from '@layerzerolabs/typescript-utils';
 
 // === Component schemas ===
 
-// Daml command schemas mirror the OpenAPI-generated Command union (Command = CommandOneOf | ... | CommandOneOf3).
-// Payload fields (createArguments, choiceArgument, contractKey) are z.any() because
-// they carry arbitrary Daml values whose shape depends on the template.
+// Payload fields (createArguments, choiceArgument, contractKey) are z.any() —
+// arbitrary Daml values whose shape depends on the template.
 
 const createCommandSchema = z.object({
     templateId: z.string(),
@@ -54,8 +53,43 @@ export const cantonDisclosedContractSchema = z.object({
     synchronizerId: z.string(),
 });
 
+/** A contract located by an Active Contract Set query, run as a party that can see
+ *  it (the sender for holdings; a config admin for OFT/RequestFactory/… later). */
+const ledgerRefreshEntrySchema = z.object({
+    /** Party whose Active Contract Set to query; resolved at sign time. */
+    partyToFilter: z.literal('sender'),
+    /** Template id to query. */
+    templateId: z.string(),
+});
+
+/**
+ * Declarative description of ledger contracts the building factory deferred to sign
+ * time, resolved by a generic ledger-query refresh executor. (The amulet fee context is
+ * refreshed automatically when a command carries its placeholder, so it isn't declared
+ * here.)
+ */
+export const cantonRefreshSpecSchema = z.object({
+    /** Command-tree placeholders, each replaced with the contract id(s) from a ledger query. */
+    commands: z
+        .array(
+            ledgerRefreshEntrySchema.extend({
+                /** Sentinel to replace in the command tree. */
+                placeholder: z.string(),
+                /** When true, the placeholder is replaced with the full array of resolved
+                 *  contract ids (e.g. amulet holdings); otherwise with the single id. */
+                multiple: z.boolean().optional(),
+            }),
+        )
+        .optional(),
+    /** Contracts fetched via a ledger query (run as the sender) and appended to
+     *  disclosedContracts. */
+    disclosedContracts: z.array(ledgerRefreshEntrySchema).optional(),
+});
+
+export type CantonRefreshSpec = z.infer<typeof cantonRefreshSpecSchema>;
+
 /** Output of prepareForSigning — needed by submitSigned to execute the transaction. */
-const _cantonInflightTransactionSchema = z.object({
+const cantonInflightTransactionSchema = z.object({
     /** The prepared transaction blob */
     preparedTransaction: z.string(),
     /** Hash of the prepared transaction (what was signed) */
@@ -67,6 +101,10 @@ const _cantonInflightTransactionSchema = z.object({
     ]),
     /** Command ID for tracking */
     commandId: z.string(),
+    /** Ledger offset at which the submission landed — used as `beginExclusive`
+     *  for waitForCommand to avoid polling from the start of the ledger.
+     *  Optional: only present after send(); absent for old/retry scenarios. */
+    completionOffset: z.number().optional(),
 });
 
 // === Lifecycle schemas ===
@@ -85,8 +123,16 @@ export const cantonTransactionSchema = transactionSchema.extend({
         commands: z.array(cantonCommandSchema),
         /** Disclosed contracts for contract/key lookups */
         disclosedContracts: z.array(cantonDisclosedContractSchema),
-        /** Maps each actAs party ID → senderEntityName that controls its signing key */
-        partyToSenderEntity: z.record(z.string(), z.string()),
+        /** Maps each actAs party → the senderEntityName(s) controlling its signing
+         *  key(s), always as an array. `.optional()` only so deferred-sender create-time
+         *  payloads parse; by sign time every actAs party must map, or signing throws.
+         *  Multiple entries = a multisig party (decentralized namespace) whose keys must
+         *  all sign. */
+        partyToSenderEntity: z.record(z.string(), z.array(z.string())).optional(),
+        /** Sign-time refresh spec for placeholders the building factory deferred
+         *  (e.g. amulet input holdings, disclosures, time-sensitive choice context).
+         *  Resolved by the generic refresh executor before prepareForSigning. */
+        refreshSpec: cantonRefreshSpecSchema.optional(),
     }),
 });
 
@@ -95,7 +141,7 @@ export const cantonTransactionSchema = transactionSchema.extend({
  */
 export const cantonAssignedTransactionSchema = assignedTransactionSchema.extend({
     ...cantonTransactionSchema.shape,
-    inflightTransaction: _cantonInflightTransactionSchema.optional(),
+    inflightTransaction: cantonInflightTransactionSchema.optional(),
 });
 
 /**
@@ -126,7 +172,7 @@ export const cantonSignedTransactionSchema = signedTransactionSchema.extend({
  */
 export const cantonMinedTransactionSchema = minedTransactionSchema.extend({
     ...cantonSignedTransactionSchema.shape,
-    inflightTransaction: _cantonInflightTransactionSchema,
+    inflightTransaction: cantonInflightTransactionSchema,
 });
 
 // === Types ===

package/src/types.ts

@@ -106,6 +106,39 @@ export type ExternalSignature = {
     signingAlgorithmSpec: string;
 };
 
+/**
+ * A right granted to a Canton user, as returned by `/v2/users/{userId}/rights`.
+ *
+ * The `kind` is a discriminated union — only one variant is set per right:
+ *  - `CanActAs.value.party`: user can submit transactions as that party
+ *  - `CanReadAs.value.party`: user can read events visible to that party
+ *  - `ParticipantAdmin`: user has admin rights on the participant
+ *  - `IdentityProviderAdmin`: user can administer its identity provider
+ *  - `CanReadAsAnyParty`: user can read as any party
+ *  - `CanExecuteAsAnyParty`: user can submit as any party
+ *
+ * Hand-rolled because the OpenAPI generator's `Kind` converter is broken
+ * (`instanceOfKindOneOf` checks lowercase `canActAs`, but `KindOneOfFromJSON`
+ * reads uppercase `CanActAs`), so the typed client strips all party data.
+ *
+ * The four nullary variants carry `value: unknown` because Canton's wire
+ * format for them is literally `{ "value": {} }` (see
+ * https://docs.digitalasset.com/build/3.4/explanations/json-api/) and we
+ * never read into that payload — only the presence of the variant matters.
+ */
+export type UserRightKind = {
+    CanActAs?: { value: { party: string } };
+    CanReadAs?: { value: { party: string } };
+    ParticipantAdmin?: { value: unknown };
+    IdentityProviderAdmin?: { value: unknown };
+    CanReadAsAnyParty?: { value: unknown };
+    CanExecuteAsAnyParty?: { value: unknown };
+};
+
+export type UserRight = {
+    kind: UserRightKind;
+};
+
 /** Normalized active contract (flat shape derived from JsActiveContract). */
 export type NormalizedActiveContract = {
     contractId: string;

package/dist/CJEDJ6BA.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/transaction.ts"],"names":["createCommandSchema","z","object","templateId","string","createArguments","any","exerciseCommandSchema","contractId","choice","choiceArgument","createAndExerciseCommandSchema","exerciseByKeyCommandSchema","contractKey","cantonCommandSchema","union","createCommand","exerciseCommand","createAndExerciseCommand","exerciseByKeyCommand","cantonDisclosedContractSchema","optional","createdEventBlob","synchronizerId","_cantonInflightTransactionSchema","preparedTransaction","preparedTransactionHash","hashingSchemeVersion","enum","commandId","cantonTransactionSchema","transactionSchema","extend","populatedTransaction","actAs","array","commands","disclosedContracts","partyToSenderEntity","record","cantonAssignedTransactionSchema","assignedTransactionSchema","shape","inflightTransaction","cantonSignedTransactionSchema","signedTransactionSchema","signedTransaction","signatures","party","format","signature","signedBy","signingAlgorithmSpec","cantonMinedTransactionSchema","minedTransactionSchema","buildCantonTransaction","chainName","tx","timestamps","created","Date","now"],"mappings":"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","file":"CJEDJ6BA.js","sourcesContent":["import { z } from 'zod';\n\nimport {\n    assignedTransactionSchema,\n    minedTransactionSchema,\n    signedTransactionSchema,\n    transactionSchema,\n} from '@layerzerolabs/common-chain-model';\nimport type { PartialBy } from '@layerzerolabs/typescript-utils';\n\n// === Component schemas ===\n\n// Daml command schemas mirror the OpenAPI-generated Command union (Command = CommandOneOf | ... | CommandOneOf3).\n// Payload fields (createArguments, choiceArgument, contractKey) are z.any() because\n// they carry arbitrary Daml values whose shape depends on the template.\n\nconst createCommandSchema = z.object({\n    templateId: z.string(),\n    createArguments: z.any(),\n});\n\nconst exerciseCommandSchema = z.object({\n    templateId: z.string(),\n    contractId: z.string(),\n    choice: z.string(),\n    choiceArgument: z.any(),\n});\n\nconst createAndExerciseCommandSchema = z.object({\n    templateId: z.string(),\n    createArguments: z.any(),\n    choice: z.string(),\n    choiceArgument: z.any(),\n});\n\nconst exerciseByKeyCommandSchema = z.object({\n    templateId: z.string(),\n    contractKey: z.any(),\n    choice: z.string(),\n    choiceArgument: z.any(),\n});\n\nexport const cantonCommandSchema = z.union([\n    z.object({ createCommand: createCommandSchema }),\n    z.object({ exerciseCommand: exerciseCommandSchema }),\n    z.object({ createAndExerciseCommand: createAndExerciseCommandSchema }),\n    z.object({ exerciseByKeyCommand: exerciseByKeyCommandSchema }),\n]);\n\nexport const cantonDisclosedContractSchema = z.object({\n    templateId: z.string().optional(),\n    contractId: z.string(),\n    createdEventBlob: z.string(),\n    synchronizerId: z.string(),\n});\n\n/** Output of prepareForSigning — needed by submitSigned to execute the transaction. */\nconst _cantonInflightTransactionSchema = z.object({\n    /** The prepared transaction blob */\n    preparedTransaction: z.string(),\n    /** Hash of the prepared transaction (what was signed) */\n    preparedTransactionHash: z.string(),\n    /** Hashing scheme version used */\n    hashingSchemeVersion: z.enum([\n        'HASHING_SCHEME_VERSION_UNSPECIFIED',\n        'HASHING_SCHEME_VERSION_V2',\n    ]),\n    /** Command ID for tracking */\n    commandId: z.string(),\n});\n\n// === Lifecycle schemas ===\n\n/**\n * Canton transaction schema for Daml Ledger API commands.\n *\n * Canton uses an interactive submission (prepare-sign-submit) flow for external party signing.\n * The populatedTransaction contains the commands to send to prepareForSigning.\n */\nexport const cantonTransactionSchema = transactionSchema.extend({\n    populatedTransaction: z.object({\n        /** Parties submitting the command (actAs) */\n        actAs: z.array(z.string()),\n        /** Daml commands to send to prepareForSigning */\n        commands: z.array(cantonCommandSchema),\n        /** Disclosed contracts for contract/key lookups */\n        disclosedContracts: z.array(cantonDisclosedContractSchema),\n        /** Maps each actAs party ID → senderEntityName that controls its signing key */\n        partyToSenderEntity: z.record(z.string(), z.string()),\n    }),\n});\n\n/**\n * Assigned transaction includes the inflight transaction data.\n */\nexport const cantonAssignedTransactionSchema = assignedTransactionSchema.extend({\n    ...cantonTransactionSchema.shape,\n    inflightTransaction: _cantonInflightTransactionSchema.optional(),\n});\n\n/**\n * Signed transaction includes the DER-encoded ECDSA signature.\n */\nexport const cantonSignedTransactionSchema = signedTransactionSchema.extend({\n    ...cantonAssignedTransactionSchema.shape,\n    signedTransaction: z.object({\n        /** Per-party signatures in the format expected by Canton's submitSigned */\n        signatures: z.array(\n            z.object({\n                party: z.string(),\n                signatures: z.array(\n                    z.object({\n                        format: z.string(),\n                        signature: z.string(),\n                        signedBy: z.string(),\n                        signingAlgorithmSpec: z.string(),\n                    }),\n                ),\n            }),\n        ),\n    }),\n});\n\n/**\n * Mined transaction with confirmation result.\n */\nexport const cantonMinedTransactionSchema = minedTransactionSchema.extend({\n    ...cantonSignedTransactionSchema.shape,\n    inflightTransaction: _cantonInflightTransactionSchema,\n});\n\n// === Types ===\n\nexport type CantonTx = z.infer<typeof cantonTransactionSchema>;\nexport type CantonAssignedTx = z.infer<typeof cantonAssignedTransactionSchema>;\nexport type CantonSignedTx = z.infer<typeof cantonSignedTransactionSchema>;\nexport type CantonMinedTx = z.infer<typeof cantonMinedTransactionSchema>;\n\n// === Builder ===\n\nexport type BuildCantonTransactionInput = PartialBy<CantonTx, 'chainName' | 'timestamps'>;\n\nexport const buildCantonTransaction = async (\n    chainName: string,\n    tx: BuildCantonTransactionInput,\n): Promise<CantonTx> => {\n    return {\n        ...tx,\n        chainName,\n        timestamps: {\n            created: tx.timestamps?.created ?? Date.now(),\n        },\n    };\n};\n"]}

package/dist/CTDZ456O.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/provider.ts"],"names":["parseCantonUri","uri","url","URL","adminApiHost","searchParams","get","Error","userId","tokenUrl","undefined","clientId","clientSecret","scope","audience","key","delete","jsonApiUrl","toString","replace","oauth2","createCantonProvider","isLocal","params","tokenProvider","createTokenProvider","configuration","Configuration","basePath","accessToken","getToken","client","CantonClient","grpcClient","CantonGrpcClient","host","LocalTokenProvider","actAs","admin","ClientCredentialsTokenProvider"],"mappings":"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","file":"CTDZ456O.js","sourcesContent":["import {\n    ClientCredentialsTokenProvider,\n    type ClientCredentialsTokenProviderConfig,\n} from './auth/client-credentials-token-provider';\nimport { LocalTokenProvider } from './auth/local-token-provider';\nimport type { TokenProvider } from './auth/token-provider';\nimport { CantonClient } from './client/canton-client';\nimport { CantonGrpcClient } from './client/grpc';\nimport type { ICantonClient } from './client/interface';\nimport { Configuration } from './open-api/runtime';\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Provider Type\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Composite provider for Canton — bundles both transport layers and shared auth.\n *\n * - {@link client} — JSON Ledger API (commands, queries, updates)\n * - {@link grpcClient} — gRPC Admin API (topology transactions, namespace queries)\n * - {@link tokenProvider} — Shared Bearer-token source used by both transports\n */\nexport type CantonProvider = {\n    client: ICantonClient;\n    grpcClient: CantonGrpcClient;\n    tokenProvider: TokenProvider;\n};\n\n// ─────────────────────────────────────────────────────────────────────────────\n// URI Parsing\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport type CantonUriParams = {\n    /** Base URL of the JSON Ledger API (e.g. \"http://localhost:5975\") */\n    jsonApiUrl: string;\n    /** Host:port of the gRPC Admin API (e.g. \"localhost:5076\") */\n    adminApiHost: string;\n    /** Ledger API user ID (default: \"participant_admin\") */\n    userId: string;\n    /** OAuth2 client credentials config — present only for non-local environments */\n    oauth2?: ClientCredentialsTokenProviderConfig;\n};\n\n/**\n * Parse a Canton provider URI into its constituent parts.\n *\n * URI format:\n *   `<json-api-base>?admin-api=<host:port>&user-id=<id>[&token-url=...&client-id=...&client-secret=...&scope=...&audience=...]`\n *\n * The base URL (everything before the query string) is the JSON Ledger API endpoint.\n * Canton-specific params are extracted and removed; any remaining query params are\n * preserved on the JSON API URL.\n */\nexport function parseCantonUri(uri: string): CantonUriParams {\n    const url = new URL(uri);\n\n    // Extract Canton-specific params\n    const adminApiHost = url.searchParams.get('admin-api');\n    if (!adminApiHost) {\n        throw new Error('Canton provider URI missing required \"admin-api\" query parameter');\n    }\n\n    const userId = url.searchParams.get('user-id') ?? 'participant_admin';\n    const tokenUrl = url.searchParams.get('token-url') ?? undefined;\n    const clientId = url.searchParams.get('client-id') ?? undefined;\n    const clientSecret = url.searchParams.get('client-secret') ?? undefined;\n    const scope = url.searchParams.get('scope') ?? undefined;\n    const audience = url.searchParams.get('audience') ?? undefined;\n\n    // Remove Canton params to get clean JSON API URL\n    for (const key of [\n        'admin-api',\n        'user-id',\n        'token-url',\n        // TODO: check if these are acceptable in our providers config, we do the same with api-keys currently.\n        'client-id',\n        'client-secret',\n        'scope',\n        'audience',\n    ]) {\n        url.searchParams.delete(key);\n    }\n\n    // Reconstruct clean base URL (origin + pathname, plus any remaining query params)\n    const jsonApiUrl = url.toString().replace(/\\/$/, '');\n\n    const oauth2 =\n        tokenUrl && clientId && clientSecret\n            ? { tokenUrl, clientId, clientSecret, scope, audience }\n            : undefined;\n\n    return { jsonApiUrl, adminApiHost, userId, oauth2 };\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Provider Factory\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport type CreateCantonProviderOptions = {\n    /** Raw provider URI (from provider config) */\n    uri: string;\n    /** When true, uses LocalTokenProvider (self-signed JWTs) instead of OAuth2 */\n    isLocal: boolean;\n};\n\n/**\n * Create a {@link CantonProvider} from a provider URI.\n *\n * - **isLocal=true**: Uses {@link LocalTokenProvider} with admin-level access (self-signed JWTs).\n * - **isLocal=false**: Uses {@link ClientCredentialsTokenProvider} with OAuth2 client\n *   credentials extracted from the URI query parameters.\n */\nexport function createCantonProvider({\n    uri,\n    isLocal,\n}: CreateCantonProviderOptions): CantonProvider {\n    const params = parseCantonUri(uri);\n\n    const tokenProvider = createTokenProvider(params, isLocal);\n\n    // ── JSON Ledger API Client ──────────────────────────────────────────\n    const configuration = new Configuration({\n        basePath: params.jsonApiUrl,\n        accessToken: () => tokenProvider.getToken(),\n    });\n    const client = new CantonClient(configuration, params.userId);\n\n    // ── gRPC Admin API Client ───────────────────────────────────────────\n    const grpcClient = new CantonGrpcClient({\n        host: params.adminApiHost,\n        tokenProvider,\n    });\n\n    return { client, grpcClient, tokenProvider };\n}\n\nfunction createTokenProvider(params: CantonUriParams, isLocal: boolean): TokenProvider {\n    if (isLocal) {\n        return new LocalTokenProvider({\n            userId: params.userId,\n            actAs: [],\n            admin: true,\n        });\n    }\n\n    // TODO: add other authentication methods for prod: such as direct jwt passthrough, oauth2 client credentials, etc.\n    // Non-local: require OAuth2 client credentials\n    if (!params.oauth2) {\n        throw new Error(\n            'Canton provider requires OAuth2 credentials (token-url, client-id, client-secret) in the provider URI',\n        );\n    }\n\n    return new ClientCredentialsTokenProvider(params.oauth2);\n}\n"]}