@layerzerolabs/common-canton 0.2.116 → 0.2.118

package/dist/transaction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../src/transaction.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../src/transaction.ts"],"names":[],"mappings":"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"}

package/dist/transaction.js

@@ -1,4 +1,4 @@
-export { buildCantonTransaction, cantonAssignedTransactionSchema, cantonCommandSchema, cantonDisclosedContractSchema, cantonMinedTransactionSchema, cantonSignedTransactionSchema, cantonTransactionSchema, cantonTransactionWithResultSchema } from './EYLCZMM4.js';
+export { buildCantonTransaction, cantonAssignedTransactionSchema, cantonCommandSchema, cantonDisclosedContractSchema, cantonMinedTransactionSchema, cantonSignedTransactionSchema, cantonTransactionSchema, cantonTransactionWithResultSchema } from './WHTAP4A3.js';
 import './VUOMXK5T.js';
 //# sourceMappingURL=transaction.js.map
 //# sourceMappingURL=transaction.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@layerzerolabs/common-canton",
-  "version": "0.2.116",
+  "version": "0.2.118",
   "private": false,
   "description": "Canton VM client and utilities",
   "license": "MIT",
@@ -30,10 +30,10 @@
     "@protobuf-ts/grpc-transport": "^2.9.4",
     "es-toolkit": "^1.39.10",
     "zod": "4.3.5",
-    "@layerzerolabs/common-encoding-utils": "0.2.116",
-    "@layerzerolabs/common-chain-model": "0.2.116",
-    "@layerzerolabs/common-error-utils": "0.2.116",
-    "@layerzerolabs/typescript-utils": "0.2.116"
+    "@layerzerolabs/common-encoding-utils": "0.2.118",
+    "@layerzerolabs/common-chain-model": "0.2.118",
+    "@layerzerolabs/common-error-utils": "0.2.118",
+    "@layerzerolabs/typescript-utils": "0.2.118"
   },
   "devDependencies": {
     "@types/node": "^22.18.6",
@@ -42,11 +42,11 @@
     "tsup": "^8.4.0",
     "typescript": "^5.8.2",
     "vitest": "^3.2.6",
-    "@layerzerolabs/eslint-configuration": "^0.2.116",
-    "@layerzerolabs/tsup-configuration": "0.2.116",
-    "@layerzerolabs/typescript-configuration": "0.2.116",
-    "@layerzerolabs/vm-tooling-canton": "0.2.116",
-    "@layerzerolabs/vitest-configuration": "0.2.116"
+    "@layerzerolabs/eslint-configuration": "^0.2.118",
+    "@layerzerolabs/tsup-configuration": "0.2.118",
+    "@layerzerolabs/vitest-configuration": "0.2.118",
+    "@layerzerolabs/typescript-configuration": "0.2.118",
+    "@layerzerolabs/vm-tooling-canton": "0.2.118"
   },
   "publishConfig": {
     "access": "public",

package/src/address.ts

@@ -0,0 +1,50 @@
+import { trim0x } from '@layerzerolabs/common-encoding-utils';
+import type { Branded } from '@layerzerolabs/typescript-utils';
+
+import { CANTON_DEFERRED_VALUE_PREFIX, CANTON_DEFERRED_VALUE_SUFFIX } from './deferredValue';
+
+const CANTON_PARTY_ID_REGEX = /^(.+)::([0-9a-fA-F]+)$/;
+const CANTON_CONTRACT_ID_HEX_LENGTH = 138; // 69 bytes
+
+export const CANTON_PARTY_ADDRESS_PREFIX = '<<CANTON_PARTY::';
+export const CANTON_CID_ADDRESS_PREFIX = '<<CANTON_CID::';
+
+/** A Canton native address — a branded string with one of three sentinel-prefix forms. */
+export type CantonAddress = Branded<string, 'CantonAddress'>;
+
+/** Construct a party `CantonAddress` from hint and fingerprint. */
+export const cantonPartyAddress = (hint: string, fingerprint: string): CantonAddress =>
+    `${CANTON_PARTY_ADDRESS_PREFIX}${hint}::${fingerprint}${CANTON_DEFERRED_VALUE_SUFFIX}` as CantonAddress;
+
+/** Construct a contract-ID `CantonAddress` from the raw 69-byte hex contract id. */
+export const cantonCidAddress = (contractId: string): CantonAddress =>
+    `${CANTON_CID_ADDRESS_PREFIX}${contractId}${CANTON_DEFERRED_VALUE_SUFFIX}` as CantonAddress;
+
+/** Wrap a deferred-ref sentinel (`<<CANTON_DEFERRED:{json}>>`) as a `CantonAddress`. */
+export const cantonDeferredAddress = (sentinel: string): CantonAddress => sentinel as CantonAddress;
+
+/** Wrap a raw Canton ledger value (party id, contract id, or deferred sentinel) as `CantonAddress`. */
+export const toCantonAddress = (raw: string): CantonAddress => {
+    if (
+        raw.startsWith(CANTON_DEFERRED_VALUE_PREFIX) &&
+        raw.endsWith(CANTON_DEFERRED_VALUE_SUFFIX)
+    ) {
+        return cantonDeferredAddress(raw);
+    }
+    const partyMatch = CANTON_PARTY_ID_REGEX.exec(raw);
+    if (partyMatch) {
+        const [, hint, fingerprint] = partyMatch;
+        return cantonPartyAddress(hint!, fingerprint!);
+    }
+    const bare = trim0x(raw);
+    if (bare.length === CANTON_CONTRACT_ID_HEX_LENGTH && bare.startsWith('00')) {
+        return cantonCidAddress(bare);
+    }
+    throw new Error(`Not a Canton-native address: ${raw}`);
+};
+
+/** Returns true if `value` is a valid `CantonAddress` sentinel string. */
+export const isCantonAddress = (value: string): value is CantonAddress =>
+    value.startsWith(CANTON_PARTY_ADDRESS_PREFIX) ||
+    value.startsWith(CANTON_CID_ADDRESS_PREFIX) ||
+    value.startsWith(CANTON_DEFERRED_VALUE_PREFIX);

package/src/client/amulet.ts

@@ -0,0 +1,126 @@
+import { NonRetryableError } from '@layerzerolabs/common-error-utils';
+
+import type { TokenProvider } from '../auth/token-provider';
+import { CantonProtocolError } from '../errors';
+import type { DisclosedContract } from '../open-api/models';
+
+/** Validator-wallet access a {@link CantonClient} needs to serve amulet endpoints. */
+export type CantonClientWalletConfig = {
+    /** Validator wallet URL for scan-proxy CIP-56 endpoints. */
+    walletUrl: string;
+    /** Bearer-token source for wallet requests. */
+    tokenProvider: TokenProvider;
+};
+
+/** The single Amulet instrument id used across Canton Network fee flows. */
+export const AMULET_INSTRUMENT_ID = 'Amulet';
+
+/** Instrument identifier for an amulet context probe. */
+export type InstrumentId = { admin: string; id: string };
+
+/** DAML ChoiceContext — a bag of named AnyValues passed to fee-bearing choices. */
+export type ChoiceContext = { values: Record<string, unknown> };
+
+export type AmuletContextResult = {
+    amuletContext: ChoiceContext;
+    disclosedContracts: DisclosedContract[];
+    externalPartyAmuletRulesCid: string;
+};
+
+// The probe (amount 0, sender = receiver = admin) never executes — it only fetches context; 1-hour window is ample.
+const CONTEXT_PROBE_EXECUTE_BEFORE_WINDOW_MS = 60 * 60 * 1000;
+
+type AmuletContextResponse = {
+    choiceContext: {
+        disclosedContracts: DisclosedContract[];
+        choiceContextData: ChoiceContext;
+    };
+};
+
+/** Amulet ChoiceContext from the validator scan-proxy — same call for all fee-bearing choices. */
+export const fetchAmuletContext = async (
+    walletUrl: string,
+    token: string,
+    instrumentId: InstrumentId,
+): Promise<{ amuletContext: ChoiceContext; disclosedContracts: DisclosedContract[] }> => {
+    const now = new Date();
+    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`,
+        {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${token}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                choiceArguments: {
+                    expectedAdmin: instrumentId.admin,
+                    transfer: {
+                        sender: instrumentId.admin,
+                        receiver: instrumentId.admin,
+                        amount: '0',
+                        instrumentId,
+                        requestedAt: now.toISOString(),
+                        executeBefore: later.toISOString(),
+                        inputHoldingCids: [],
+                        meta: { values: {} },
+                    },
+                    extraArgs: { context: { values: {} }, meta: { values: {} } },
+                },
+            }),
+        },
+    );
+
+    if (!response.ok) {
+        const text = await response.text();
+        throw new CantonProtocolError(`Failed to get amulet context: ${response.status} ${text}`);
+    }
+
+    const data = (await response.json()) as AmuletContextResponse;
+    const { disclosedContracts, choiceContextData: amuletContext } = data.choiceContext;
+
+    return { amuletContext, disclosedContracts };
+};
+
+/** Injects ExternalPartyAmuletRules cid into the ChoiceContext — required by every flow hitting FeeUtils.validateContext. */
+export const injectExternalPartyAmuletRules = (
+    amuletContext: ChoiceContext,
+    disclosedContracts: DisclosedContract[],
+): { amuletContext: ChoiceContext; externalPartyAmuletRulesCid: string } => {
+    const externalRulesContract = disclosedContracts.find((contract) =>
+        contract.templateId?.includes('ExternalPartyAmuletRules'),
+    );
+
+    if (!externalRulesContract) {
+        throw new NonRetryableError(
+            'ExternalPartyAmuletRules not found in disclosed contracts from amulet context',
+        );
+    }
+
+    return {
+        amuletContext: {
+            values: {
+                ...amuletContext.values,
+                'external-party-amulet-rules': {
+                    tag: 'AV_ContractId',
+                    value: externalRulesContract.contractId,
+                },
+            },
+        },
+        externalPartyAmuletRulesCid: externalRulesContract.contractId,
+    };
+};
+
+/** 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`, {
+        headers: { Authorization: `Bearer ${token}` },
+    });
+    if (!response.ok) {
+        throw new CantonProtocolError(`Failed to get DSO party: ${response.status}`);
+    }
+    const data = (await response.json()) as { dso_party_id: string };
+    return data.dso_party_id;
+};

package/src/client/canton-client.ts

@@ -33,6 +33,14 @@ import type {
     WaitOptions,
     WaitResult,
 } from '../types';
+import {
+    type AmuletContextResult,
+    type CantonClientWalletConfig,
+    fetchAmuletContext,
+    fetchDsoParty,
+    injectExternalPartyAmuletRules,
+    type InstrumentId,
+} from './amulet';
 import type {
     CantonTransaction,
     CantonUpdate,
@@ -55,10 +63,48 @@ import type {
 export class CantonClient implements ICantonClient {
     readonly #api: DefaultApi;
     readonly #userId: string;
-
-    constructor(config: Configuration, userId: string = 'participant_admin') {
+    readonly #wallet?: CantonClientWalletConfig;
+    #dsoParty?: string;
+
+    constructor(
+        config: Configuration,
+        userId: string = 'participant_admin',
+        wallet?: CantonClientWalletConfig,
+    ) {
         this.#api = new DefaultApi(config);
         this.#userId = userId;
+        this.#wallet = wallet;
+    }
+
+    #requireWallet(): CantonClientWalletConfig {
+        if (!this.#wallet) {
+            throw new CantonProtocolError(
+                'CantonClient has no wallet config (walletUrl + tokenProvider); amulet endpoints are unavailable',
+            );
+        }
+        return this.#wallet;
+    }
+
+    async getDsoParty(): Promise<string> {
+        const { walletUrl, tokenProvider } = this.#requireWallet();
+        if (this.#dsoParty) return this.#dsoParty;
+        this.#dsoParty = await fetchDsoParty(walletUrl, await tokenProvider.getToken());
+        return this.#dsoParty;
+    }
+
+    /** Amulet ChoiceContext with ExternalPartyAmuletRules injected — required by every flow hitting FeeUtils.validateContext. */
+    async getAmuletContextWithExternalRules(
+        instrumentId: InstrumentId,
+    ): Promise<AmuletContextResult> {
+        const { walletUrl, tokenProvider } = this.#requireWallet();
+        const { amuletContext, disclosedContracts } = await fetchAmuletContext(
+            walletUrl,
+            await tokenProvider.getToken(),
+            instrumentId,
+        );
+        const { amuletContext: contextWithRules, externalPartyAmuletRulesCid } =
+            injectExternalPartyAmuletRules(amuletContext, disclosedContracts);
+        return { amuletContext: contextWithRules, disclosedContracts, externalPartyAmuletRulesCid };
     }
 
     /**

package/src/client/index.ts

@@ -1,3 +1,4 @@
+export * from './amulet';
 export { CantonClient } from './canton-client';
 export * from './grpc';
 export * from './interface';

package/src/client/interface.ts

@@ -21,6 +21,7 @@ import type {
     WaitOptions,
     WaitResult,
 } from '../types';
+import type { AmuletContextResult, InstrumentId } from './amulet';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Corrected Update Types
@@ -71,6 +72,11 @@ export interface ICantonClient {
      */
     connectedSynchronizers(): Promise<string[]>;
 
+    getDsoParty(): Promise<string>;
+
+    /** Amulet ChoiceContext with ExternalPartyAmuletRules injected — requires wallet config. */
+    getAmuletContextWithExternalRules(instrumentId: InstrumentId): Promise<AmuletContextResult>;
+
     /**
      * Submit a batch of commands atomically.
      */

package/src/deferredValue.ts

@@ -12,14 +12,12 @@ export const cantonDeferredValueSchema = z.discriminatedUnion('type', [
         partyToFilter: cantonRefreshPartyFilterSchema,
         templateId: z.string(),
         contractStateFilter: z.partialRecord(z.string(), z.any()).optional(),
-        disclose: z.boolean().optional(),
     }),
     z.object({
         type: z.literal('activeContractIds'),
         partyToFilter: cantonRefreshPartyFilterSchema,
         templateId: z.string(),
         contractStateFilter: z.partialRecord(z.string(), z.any()).optional(),
-        disclose: z.boolean().optional(),
     }),
     z.object({ type: z.literal('amuletRulesCid') }),
     z.object({ type: z.literal('amuletContext') }),
@@ -36,11 +34,18 @@ type CantonActiveContractIdsRef = Omit<
     'type'
 >;
 
-const CANTON_DEFERRED_VALUE_PREFIX = '<<CANTON_DEFERRED:';
-const CANTON_DEFERRED_VALUE_SUFFIX = '>>';
+/**
+ * Branded encoded form of a {@link CantonDeferredValue}: a sign-time reference
+ * string that a resolver turns into a live contract id / party. Branding keeps it
+ * distinct from a plain `string` so the ref-substitution stays type-checked.
+ */
+export type CantonDeferredRef = string & { readonly __cantonDeferredRef: unique symbol };
 
-export const encodeCantonDeferredValue = (value: CantonDeferredValue): string =>
-    `${CANTON_DEFERRED_VALUE_PREFIX}${JSON.stringify(value)}${CANTON_DEFERRED_VALUE_SUFFIX}`;
+export const CANTON_DEFERRED_VALUE_PREFIX = '<<CANTON_DEFERRED:';
+export const CANTON_DEFERRED_VALUE_SUFFIX = '>>';
+
+export const encodeCantonDeferredValue = (value: CantonDeferredValue): CantonDeferredRef =>
+    `${CANTON_DEFERRED_VALUE_PREFIX}${JSON.stringify(value)}${CANTON_DEFERRED_VALUE_SUFFIX}` as CantonDeferredRef;
 
 export const parseCantonDeferredValue = (value: unknown): CantonDeferredValue | undefined => {
     if (
@@ -61,19 +66,19 @@ export const parseCantonDeferredValue = (value: unknown): CantonDeferredValue |
     }
 };
 
-export const cantonSenderPartyRef = (): string =>
+export const cantonSenderPartyRef = (): CantonDeferredRef =>
     encodeCantonDeferredValue({ type: 'senderParty' });
 
-export const cantonActiveContractIdRef = (value: CantonActiveContractIdRef): string =>
+export const cantonActiveContractIdRef = (value: CantonActiveContractIdRef): CantonDeferredRef =>
     encodeCantonDeferredValue({ type: 'activeContractId', ...value });
 
-export const cantonActiveContractIdsRef = (value: CantonActiveContractIdsRef): string =>
+export const cantonActiveContractIdsRef = (value: CantonActiveContractIdsRef): CantonDeferredRef =>
     encodeCantonDeferredValue({ type: 'activeContractIds', ...value });
 
-export const cantonAmuletRulesCidRef = (): string =>
+export const cantonAmuletRulesCidRef = (): CantonDeferredRef =>
     encodeCantonDeferredValue({ type: 'amuletRulesCid' });
 
-export const cantonAmuletContextRef = (): string =>
+export const cantonAmuletContextRef = (): CantonDeferredRef =>
     encodeCantonDeferredValue({ type: 'amuletContext' });
 
 /** Returns true if `value` is a Canton deferred-value sentinel. */

package/src/events.ts

@@ -58,7 +58,7 @@ export const findMatchingCreatedEventFromTx = async (
 
     if (!updateId || !actAs.length) return null;
 
-    const createCommand = unresolvedCommands[0];
+    const createCommand = unresolvedCommands.find((cmd) => 'createCommand' in cmd);
     if (!createCommand || !('createCommand' in createCommand)) return null;
 
     const createdEvents = await fetchCreatedEvents(client, updateId, actAs);

package/src/index.ts

@@ -1,3 +1,4 @@
+export * from './address';
 export * from './amulet';
 export * from './auth';
 export * from './crypto';
@@ -5,6 +6,7 @@ export * from './daml-serde';
 export * from './deferredValue';
 export * from './events';
 export * from './provider';
+export * from './refresh';
 export * from './transaction';
 
 // Core types
@@ -31,19 +33,7 @@ export {
 export { CantonError, CantonProtocolError, CantonTransportError } from './errors';
 
 // Canton Client (low-level transport)
-export {
-    CantonClient,
-    type CantonEvent,
-    CantonGrpcClient,
-    type CantonGrpcClientOptions,
-    type CantonTransaction,
-    type CantonUpdate,
-    type CantonUpdateResponse,
-    computeCantonFingerprint,
-    extractTransactions,
-    type ICantonClient,
-    type TlsOptions,
-} from './client';
+export * from './client';
 
 // Canton SDK (high-level API)
 export { CantonSdk, type NormalizedActiveContract } from './sdk/index';

package/src/provider.ts

@@ -146,7 +146,10 @@ export function createCantonChainProvider({
         basePath: params.jsonApiUrl,
         accessToken: () => tokenProvider.getToken(),
     });
-    const client = new CantonClient(configuration, params.userId);
+    const client = new CantonClient(configuration, params.userId, {
+        walletUrl: params.walletUrl,
+        tokenProvider,
+    });
 
     // ── gRPC Admin API Client ───────────────────────────────────────────
     const grpcClient = new CantonGrpcClient({

package/src/refresh/address-resolver.ts

@@ -0,0 +1,161 @@
+import type { ContractId } from '@daml/types';
+
+import { NonRetryableError } from '@layerzerolabs/common-error-utils';
+
+import type { ICantonClient } from '../client/interface';
+import type { CantonDeferredValue } from '../deferredValue';
+import type { JsActiveContract } from '../open-api/models';
+import type { CantonDisclosedContracts } from '../transaction';
+
+export type ActiveContractRef = Extract<
+    CantonDeferredValue,
+    { type: 'activeContractId' | 'activeContractIds' }
+>;
+
+export interface ContractAddressResolverDeps {
+    client: ICantonClient;
+    senderParty?: string;
+    /** A contract is only disclosed when none of these parties is already a stakeholder on it. */
+    signingParties: string[];
+    appendDisclosures: (disclosures: CantonDisclosedContracts) => void;
+}
+
+export const matchesContractStateFilter = (
+    contract: JsActiveContract,
+    contractStateFilter: ActiveContractRef['contractStateFilter'],
+): boolean => {
+    if (!contractStateFilter) return true;
+    const createArgument = contract.createdEvent.createArgument as Record<string, unknown>;
+    return Object.entries(contractStateFilter).every(
+        ([key, value]) => JSON.stringify(createArgument[key]) === JSON.stringify(value),
+    );
+};
+
+export const isRefAlive = async (
+    client: ICantonClient,
+    ref: CantonDeferredValue,
+): Promise<boolean> => {
+    if (ref.type !== 'activeContractId' && ref.type !== 'activeContractIds') return false;
+    if (ref.partyToFilter === 'sender') return false;
+    const contracts = await queryLiveContractsForRef(client, ref.partyToFilter.party, ref);
+    return ref.type === 'activeContractId' ? contracts.length === 1 : contracts.length > 0;
+};
+
+/** partyToFilter: 'sender' is resolved per-caller — this function takes an already-resolved party string. */
+export const queryLiveContractsForRef = async (
+    client: ICantonClient,
+    party: string,
+    ref: ActiveContractRef,
+): Promise<JsActiveContract[]> => {
+    const offset = await client.getLedgerEndOffset();
+    return (
+        await client.queryActiveContracts(party, offset, { templateIds: [ref.templateId] })
+    ).filter((contract) => matchesContractStateFilter(contract, ref.contractStateFilter));
+};
+
+/**
+ * Returns the contractIds of all live contracts matching ref.
+ * Resolves 'sender' to senderParty when provided; returns [] if unresolvable.
+ */
+export const queryLiveContractIdsForRef = async (
+    client: ICantonClient,
+    ref: CantonDeferredValue,
+    senderParty?: string,
+): Promise<string[]> => {
+    if (ref.type !== 'activeContractId' && ref.type !== 'activeContractIds') return [];
+    const party = ref.partyToFilter === 'sender' ? senderParty : ref.partyToFilter.party;
+    if (!party) return [];
+    const contracts = await queryLiveContractsForRef(client, party, ref);
+    return contracts.map((c) => c.createdEvent.contractId);
+};
+
+export const createContractAddressResolver = (deps: ContractAddressResolverDeps) => {
+    const { client, senderParty, signingParties, appendDisclosures } = deps;
+
+    const requireSender = (templateId: string): string => {
+        if (!senderParty) {
+            throw new NonRetryableError(
+                `Refresh entry for ${templateId} needs a resolved sender party, but none was provided`,
+            );
+        }
+        return senderParty;
+    };
+
+    const resolveQueryParty = ({ partyToFilter, templateId }: ActiveContractRef): string =>
+        partyToFilter === 'sender' ? requireSender(templateId) : partyToFilter.party;
+
+    const queryCache = new Map<string, Promise<JsActiveContract[]>>();
+    const queryAsParty = async (ref: ActiveContractRef): Promise<JsActiveContract[]> => {
+        const party = resolveQueryParty(ref);
+        const cacheKey = JSON.stringify({ ...ref, party });
+        const cached = queryCache.get(cacheKey);
+        if (cached) return cached;
+
+        const query = (async () => {
+            const contracts = await queryLiveContractsForRef(client, party, ref);
+            if (contracts.length === 0) {
+                throw new NonRetryableError(
+                    `Party ${party} has no matching active contracts of ${ref.templateId}`,
+                );
+            }
+            return contracts;
+        })();
+        queryCache.set(cacheKey, query);
+        return query;
+    };
+
+    // A signing party that is already a stakeholder can see the contract on its
+    // own stream, so only disclose to parties that aren't signatories/observers.
+    const needsDisclosure = (contract: JsActiveContract): boolean => {
+        const stakeholders = new Set([
+            ...(contract.createdEvent.signatories ?? []),
+            ...(contract.createdEvent.observers ?? []),
+        ]);
+        return !signingParties.some((party) => stakeholders.has(party));
+    };
+
+    const discloseContracts = async (
+        ref: ActiveContractRef,
+        contracts: JsActiveContract[],
+    ): Promise<void> => {
+        const toDisclose = contracts.filter(needsDisclosure);
+        if (toDisclose.length === 0) return;
+
+        const party = resolveQueryParty(ref);
+        const disclosures = await Promise.all(
+            toDisclose.map(async (contract) => {
+                const contractId = contract.createdEvent.contractId;
+                const disclosure = await client.createDisclosure(
+                    contractId as ContractId<unknown>,
+                    [party],
+                );
+                if (!disclosure) {
+                    throw new NonRetryableError(
+                        `Could not disclose ${contractId} (template ${ref.templateId}) — no longer active`,
+                    );
+                }
+                return disclosure;
+            }),
+        );
+        appendDisclosures(disclosures);
+    };
+
+    const resolveActiveContractId = async (ref: ActiveContractRef): Promise<string> => {
+        const contracts = await queryAsParty(ref);
+        if (contracts.length !== 1) {
+            throw new NonRetryableError(
+                `Refresh for ${ref.templateId} matched ${contracts.length} contracts, but a scalar ref expects exactly one`,
+            );
+        }
+        await discloseContracts(ref, contracts);
+        return contracts[0]!.createdEvent.contractId;
+    };
+
+    const resolveActiveContractIds = async (ref: ActiveContractRef): Promise<string[]> => {
+        const contracts = await queryAsParty(ref);
+        await discloseContracts(ref, contracts);
+        return contracts.map((contract) => contract.createdEvent.contractId);
+    };
+
+    return { resolveActiveContractId, resolveActiveContractIds, requireSenderParty: requireSender };
+};

package/src/refresh/deployment-address.ts

@@ -0,0 +1,45 @@
+import { NonRetryableError } from '@layerzerolabs/common-error-utils';
+
+import { cantonActiveContractIdRef, type CantonDeferredRef } from '../deferredValue';
+
+export interface CantonDeployedTemplateSpec {
+    packageName: string;
+    ownerField: string;
+    // Immutable disambiguating fields only — mutable fields break recreate-survival.
+    identityKeys: string[];
+}
+
+// Canton returns `<packageId>:Module:Entity`; the package id has no colon.
+export const qualifiedTemplateName = (templateId: string): string => {
+    const firstColon = templateId.indexOf(':');
+    return firstColon === -1 ? templateId : templateId.slice(firstColon + 1);
+};
+
+interface DeployedCreatedEvent {
+    templateId: string;
+    createArgument?: unknown;
+}
+
+export const buildCantonDeployedContractAddressRef = (
+    createdEvent: DeployedCreatedEvent,
+    spec: CantonDeployedTemplateSpec,
+): CantonDeferredRef => {
+    const qualifiedName = qualifiedTemplateName(createdEvent.templateId);
+    const createArgument = (createdEvent.createArgument ?? {}) as Record<string, unknown>;
+    const ownerParty = createArgument[spec.ownerField];
+    if (typeof ownerParty !== 'string') {
+        throw new NonRetryableError(
+            `Template '${qualifiedName}' create argument is missing string owner field '${spec.ownerField}'`,
+        );
+    }
+
+    const contractStateFilter = spec.identityKeys.length
+        ? Object.fromEntries(spec.identityKeys.map((key) => [key, createArgument[key]]))
+        : undefined;
+
+    return cantonActiveContractIdRef({
+        partyToFilter: { party: ownerParty },
+        templateId: `#${spec.packageName}:${qualifiedName}`,
+        ...(contractStateFilter ? { contractStateFilter } : {}),
+    });
+};