@layerzerolabs/common-canton 1.2.38 → 1.2.39

package/src/address.ts

@@ -1,7 +1,7 @@
 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';
+import { CANTON_DEFERRED_VALUE_SUFFIX, isCantonDeferredSentinel } from './deferredValue';
 
 const CANTON_PARTY_ID_REGEX = /^(.+)::([0-9a-fA-F]+)$/;
 const CANTON_CONTRACT_ID_HEX_LENGTH = 138; // 69 bytes
@@ -25,10 +25,7 @@ export const cantonDeferredAddress = (sentinel: string): CantonAddress => sentin
 
 /** 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)
-    ) {
+    if (isCantonDeferredSentinel(raw)) {
         return cantonDeferredAddress(raw);
     }
     const partyMatch = CANTON_PARTY_ID_REGEX.exec(raw);
@@ -47,4 +44,4 @@ export const toCantonAddress = (raw: string): CantonAddress => {
 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);
+    isCantonDeferredSentinel(value);

package/src/deferredValue.ts

@@ -1,29 +1,55 @@
 import { z } from 'zod';
 
+import { NonRetryableError } from '@layerzerolabs/common-error-utils';
+
+/** Filter / authority token resolved to the ACS query (funding) party at refresh. */
+export const CANTON_DEFERRED_SENDER = 'sender' as const;
+export type CantonDeferredSender = typeof CANTON_DEFERRED_SENDER;
+
+export const cantonDeferredSenderSchema = z.literal(CANTON_DEFERRED_SENDER);
+
+export const isCantonDeferredSender = (value: unknown): value is CantonDeferredSender =>
+    value === CANTON_DEFERRED_SENDER;
+
 export const cantonRefreshPartyFilterSchema = z.union([
-    z.literal('sender'),
+    cantonDeferredSenderSchema,
     z.object({ party: z.string() }),
 ]);
 
+/** Non-empty list of parties that must all appear in created-event signatories. */
+export const cantonExpectedSignatoriesSchema = z
+    .array(z.union([cantonDeferredSenderSchema, z.string().min(1)]))
+    .nonempty();
+
+const cantonActiveContractRefFields = {
+    partyToFilter: cantonRefreshPartyFilterSchema,
+    /**
+     * Authority parties that must all be ledger signatories (authenticate-then-count).
+     * Use {@link CANTON_DEFERRED_SENDER} for the resolved funding/query party.
+     * Omitted on pre-existing persisted refs; refresh then defaults to the query
+     * party, except CIP-56 Amulet holdings (owner is not a signatory).
+     */
+    expectedSignatories: cantonExpectedSignatoriesSchema.optional(),
+    templateId: z.string(),
+    contractStateFilter: z.partialRecord(z.string(), z.any()).optional(),
+};
+
 export const cantonDeferredValueSchema = z.discriminatedUnion('type', [
     z.object({ type: z.literal('senderParty') }),
     z.object({
         type: z.literal('activeContractId'),
-        partyToFilter: cantonRefreshPartyFilterSchema,
-        templateId: z.string(),
-        contractStateFilter: z.partialRecord(z.string(), z.any()).optional(),
+        ...cantonActiveContractRefFields,
     }),
     z.object({
         type: z.literal('activeContractIds'),
-        partyToFilter: cantonRefreshPartyFilterSchema,
-        templateId: z.string(),
-        contractStateFilter: z.partialRecord(z.string(), z.any()).optional(),
+        ...cantonActiveContractRefFields,
     }),
     z.object({ type: z.literal('amuletRulesCid') }),
     z.object({ type: z.literal('amuletContext') }),
 ]);
 
 export type CantonRefreshPartyFilter = z.infer<typeof cantonRefreshPartyFilterSchema>;
+export type CantonExpectedSignatories = z.infer<typeof cantonExpectedSignatoriesSchema>;
 export type CantonDeferredValue = z.infer<typeof cantonDeferredValueSchema>;
 type CantonActiveContractIdRef = Omit<
     Extract<CantonDeferredValue, { type: 'activeContractId' }>,
@@ -44,15 +70,17 @@ export type CantonDeferredRef = string & { readonly __cantonDeferredRef: unique
 export const CANTON_DEFERRED_VALUE_PREFIX = '<<CANTON_DEFERRED:';
 export const CANTON_DEFERRED_VALUE_SUFFIX = '>>';
 
+/** True when `value` has deferred-ref framing, whether or not the payload parses. */
+export const isCantonDeferredSentinel = (value: unknown): value is string =>
+    typeof value === 'string' &&
+    value.startsWith(CANTON_DEFERRED_VALUE_PREFIX) &&
+    value.endsWith(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 (
-        typeof value !== 'string' ||
-        !value.startsWith(CANTON_DEFERRED_VALUE_PREFIX) ||
-        !value.endsWith(CANTON_DEFERRED_VALUE_SUFFIX)
-    ) {
+    if (!isCantonDeferredSentinel(value)) {
         return undefined;
     }
 
@@ -66,6 +94,22 @@ export const parseCantonDeferredValue = (value: unknown): CantonDeferredValue |
     }
 };
 
+/**
+ * Parse a deferred ref. Non-sentinels return `undefined`. A framed sentinel
+ * that fails schema validation throws — callers must not treat corrupt refs
+ * as plain strings.
+ */
+export const parseCantonDeferredValueOrThrow = (
+    value: unknown,
+): CantonDeferredValue | undefined => {
+    const ref = parseCantonDeferredValue(value);
+    if (ref) return ref;
+    if (isCantonDeferredSentinel(value)) {
+        throw new NonRetryableError(`Invalid Canton deferred ref: ${value}`);
+    }
+    return undefined;
+};
+
 export const cantonSenderPartyRef = (): CantonDeferredRef =>
     encodeCantonDeferredValue({ type: 'senderParty' });
 
@@ -81,6 +125,6 @@ export const cantonAmuletRulesCidRef = (): CantonDeferredRef =>
 export const cantonAmuletContextRef = (): CantonDeferredRef =>
     encodeCantonDeferredValue({ type: 'amuletContext' });
 
-/** Returns true if `value` is a Canton deferred-value sentinel. */
+/** Returns true if `value` is a valid Canton deferred-value sentinel. */
 export const isCantonPlaceholder = (value: string): boolean =>
     parseCantonDeferredValue(value) !== undefined;

package/src/events.ts

@@ -6,7 +6,8 @@ import { cantonTransactionWithResultSchema } from './transaction';
 
 /**
  * Finds a CreatedEvent matching the expected templateId whose signatories
- * are a subset of the provided actAs parties.
+ * are a subset of the provided actAs parties (ledger signatories ⊆ expected).
+ * Opposite of `areExpectedSignatories` on the refresh path.
  */
 export const findMatchingCreatedEvent = (
     createdEvents: CreatedEvent[],

package/src/index.ts

@@ -12,6 +12,7 @@ export * from './provider';
 export * from './refresh';
 export * from './sdk/index';
 export * from './transaction';
+export * from './trusted-origin';
 export * from './types';
 
 // Re-export only the types needed for SDK usage

package/src/refresh/address-resolver.ts

@@ -3,16 +3,25 @@ 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 {
+    CANTON_DEFERRED_SENDER,
+    type CantonDeferredValue,
+    isCantonDeferredSender,
+} from '../deferredValue';
 import type { JsActiveContract } from '../open-api/models';
 import type { CantonDisclosedContracts } from '../transaction';
+import { areExpectedSignatories, getCreateArgumentField } from '../trusted-origin';
+
+/** CIP-56 Amulet holding — DSO is the sole signatory; owner is payload/observer. */
+const isAmuletHoldingTemplateId = (templateId: string): boolean =>
+    templateId.endsWith(':Splice.Amulet:Amulet');
 
 export type ActiveContractRef = Extract<
     CantonDeferredValue,
     { type: 'activeContractId' | 'activeContractIds' }
 >;
 
-/** Active-contract ref whose handler party is concrete (not the `'sender'` sentinel). */
+/** Active-contract ref whose handler party is concrete (not the sender sentinel). */
 export type ConcreteActiveContractRef = ActiveContractRef & {
     partyToFilter: { party: string };
 };
@@ -21,7 +30,7 @@ export const isConcreteActiveContractRef = (
     ref: CantonDeferredValue,
 ): ref is ConcreteActiveContractRef =>
     (ref.type === 'activeContractId' || ref.type === 'activeContractIds') &&
-    ref.partyToFilter !== 'sender';
+    ref.partyToFilter !== CANTON_DEFERRED_SENDER;
 
 export interface ContractAddressResolverDeps {
     client: ICantonClient;
@@ -31,14 +40,55 @@ export interface ContractAddressResolverDeps {
     appendDisclosures: (disclosures: CantonDisclosedContracts) => void;
 }
 
+/**
+ * Match create-argument fields, including dotted paths (`instrumentId.admin`).
+ */
 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),
+    const createArgument = contract.createdEvent.createArgument;
+    return Object.entries(contractStateFilter).every(([key, value]) => {
+        const actual = getCreateArgumentField(createArgument, key);
+        // Missing / unresolvable paths must not match (fail closed).
+        if (actual === undefined) return false;
+        return JSON.stringify(actual) === JSON.stringify(value);
+    });
+};
+
+/**
+ * Resolve {@link CANTON_DEFERRED_SENDER} entries to the ACS query party.
+ * Missing lists default to `[queryParty]` except CIP-56 Amulet holdings, where
+ * the owner is not a signatory — omit the filter so pre-PR refs still resolve.
+ */
+export const resolveExpectedSignatories = (
+    expectedSignatories: readonly string[] | undefined,
+    queryParty: string,
+    templateId: string,
+): string[] | undefined => {
+    if (expectedSignatories?.length) {
+        return expectedSignatories.map((party) =>
+            isCantonDeferredSender(party) ? queryParty : party,
+        );
+    }
+    if (isAmuletHoldingTemplateId(templateId)) {
+        return undefined;
+    }
+    return [queryParty];
+};
+
+/** Resolve {@link CANTON_DEFERRED_SENDER} values in `contractStateFilter` to the ACS query party. */
+export const resolveContractStateFilter = (
+    contractStateFilter: ActiveContractRef['contractStateFilter'],
+    queryParty: string,
+): ActiveContractRef['contractStateFilter'] => {
+    if (!contractStateFilter) return contractStateFilter;
+    return Object.fromEntries(
+        Object.entries(contractStateFilter).map(([key, value]) => [
+            key,
+            isCantonDeferredSender(value) ? queryParty : value,
+        ]),
     );
 };
 
@@ -51,21 +101,40 @@ export const isRefAlive = async (
     return ref.type === 'activeContractId' ? contracts.length === 1 : contracts.length > 0;
 };
 
-/** partyToFilter: 'sender' is resolved per-caller — this function takes an already-resolved party string. */
+/**
+ * Query ACS for `party` + template, apply state filter, then
+ * authenticate-then-count: keep only contracts where every resolved
+ * `expectedSignatories` entry is a ledger signatory.
+ *
+ * `partyToFilter` is visibility (may be an observer). `expectedSignatories` is
+ * authority (defaults to the query party when omitted, except Amulet holdings).
+ * Optional `contractStateFilter` disambiguates / binds payload roles (supports
+ * dotted paths; {@link CANTON_DEFERRED_SENDER} values resolve).
+ */
 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));
+    const expectedSignatories = resolveExpectedSignatories(
+        ref.expectedSignatories,
+        party,
+        ref.templateId,
+    );
+    const contractStateFilter = resolveContractStateFilter(ref.contractStateFilter, party);
+    return (await client.queryActiveContracts(party, offset, { templateIds: [ref.templateId] }))
+        .filter((contract) => matchesContractStateFilter(contract, contractStateFilter))
+        .filter(
+            (contract) =>
+                expectedSignatories === undefined ||
+                areExpectedSignatories(contract.createdEvent, expectedSignatories),
+        );
 };
 
 /**
  * Returns the contractIds of all live contracts matching ref.
- * Resolves 'sender' to senderParty when provided; returns [] if unresolvable.
+ * Resolves {@link CANTON_DEFERRED_SENDER} to senderParty when provided; returns [] if unresolvable.
  */
 export const queryLiveContractIdsForRef = async (
     client: ICantonClient,
@@ -73,7 +142,8 @@ export const queryLiveContractIdsForRef = async (
     senderParty?: string,
 ): Promise<string[]> => {
     if (ref.type !== 'activeContractId' && ref.type !== 'activeContractIds') return [];
-    const party = ref.partyToFilter === 'sender' ? senderParty : ref.partyToFilter.party;
+    const party =
+        ref.partyToFilter === CANTON_DEFERRED_SENDER ? senderParty : ref.partyToFilter.party;
     if (!party) return [];
     const contracts = await queryLiveContractsForRef(client, party, ref);
     return contracts.map((c) => c.createdEvent.contractId);
@@ -92,7 +162,7 @@ export const createContractAddressResolver = (deps: ContractAddressResolverDeps)
     };
 
     const resolveQueryParty = ({ partyToFilter, templateId }: ActiveContractRef): string =>
-        partyToFilter === 'sender' ? requireSender(templateId) : partyToFilter.party;
+        partyToFilter === CANTON_DEFERRED_SENDER ? requireSender(templateId) : partyToFilter.party;
 
     const queryCache = new Map<string, Promise<JsActiveContract[]>>();
     const queryAsParty = async (ref: ActiveContractRef): Promise<JsActiveContract[]> => {

package/src/refresh/deployment-address.ts

@@ -39,6 +39,8 @@ export const buildCantonDeployedContractAddressRef = (
 
     return cantonActiveContractIdRef({
         partyToFilter: { party: ownerParty },
+        // LZ deploy templates: ownerField is a create-argument signatory.
+        expectedSignatories: [ownerParty],
         templateId: `#${spec.packageName}:${qualifiedName}`,
         ...(contractStateFilter ? { contractStateFilter } : {}),
     });

package/src/refresh/reverse-substitute.ts

@@ -1,6 +1,6 @@
 import { NonRetryableError } from '@layerzerolabs/common-error-utils';
 
-import { type CantonDeferredValue, parseCantonDeferredValue } from '../deferredValue';
+import { type CantonDeferredValue, parseCantonDeferredValueOrThrow } from '../deferredValue';
 
 // Opaque base64 — swapping a cid here would corrupt it.
 const BLOB_KEY = 'createdEventBlob';
@@ -30,7 +30,7 @@ export const substituteRefsToCids = async <T>(value: T, resolve: ResolveRef): Pr
     if (Array.isArray(value)) {
         const items = await Promise.all(
             value.map(async (item) => {
-                const ref = parseCantonDeferredValue(item);
+                const ref = parseCantonDeferredValueOrThrow(item);
                 return ref?.type === 'activeContractIds'
                     ? ((await resolve(ref)) as unknown[])
                     : [await substituteRefsToCids(item, resolve)];
@@ -39,7 +39,7 @@ export const substituteRefsToCids = async <T>(value: T, resolve: ResolveRef): Pr
         return items.flat() as T;
     }
 
-    const ref = parseCantonDeferredValue(value);
+    const ref = parseCantonDeferredValueOrThrow(value);
     if (ref) {
         if (ref.type === 'activeContractIds') {
             throw new NonRetryableError(

package/src/refresh/wrapped-lz-sdk.ts

@@ -1,3 +1,4 @@
+import { NonRetryableError } from '@layerzerolabs/common-error-utils';
 import { isPromise } from '@layerzerolabs/typescript-utils';
 
 import { cantonActiveContractIdRef, type CantonDeferredRef } from '../deferredValue';
@@ -22,16 +23,25 @@ const applyRefs = <R>(result: R): WithRefsInjected<R> => {
     if (!refs?.length) return result as WithRefsInjected<R>;
 
     const contractIdToRef = new Map<string, CantonDeferredRef>(
-        refs.map((ref) => [
-            ref.cid,
-            cantonActiveContractIdRef({
-                partyToFilter: { party: ref.party },
-                templateId: ref.templateId,
-                ...(ref.contractStateFilter
-                    ? { contractStateFilter: ref.contractStateFilter }
-                    : {}),
-            }),
-        ]),
+        refs.map((ref) => {
+            const expectedSignatories = ref.expectedSignatories;
+            if (!expectedSignatories[0]) {
+                throw new NonRetryableError(
+                    `ContractDataIdentifier for ${ref.cid} missing expectedSignatories`,
+                );
+            }
+            return [
+                ref.cid,
+                cantonActiveContractIdRef({
+                    partyToFilter: { party: ref.party },
+                    expectedSignatories,
+                    templateId: ref.templateId,
+                    ...(ref.contractStateFilter
+                        ? { contractStateFilter: ref.contractStateFilter }
+                        : {}),
+                }),
+            ];
+        }),
     );
 
     const { referencedContracts: _dropped, ...rest } = result as Record<string, unknown>;

package/src/transaction.ts

@@ -9,7 +9,7 @@ import {
 } from '@layerzerolabs/common-chain-model';
 import type { PartialBy } from '@layerzerolabs/typescript-utils';
 
-import type { CantonDeferredRef } from './deferredValue';
+import type { CantonDeferredRef, CantonExpectedSignatories } from './deferredValue';
 
 // === Component schemas ===
 
@@ -167,7 +167,16 @@ export const cantonMinedTransactionSchema = minedTransactionSchema.extend({
 export interface ContractDataIdentifier {
     cid: string;
     templateId: string;
+    /** ACS query / visibility party (`partyToFilter`). */
     party: string;
+    /**
+     * Authority parties that must all be ledger signatories at refresh time.
+     * Typically `[party]`; use a different list when querying as an observer
+     * (e.g. gateway) while authenticating the admin signatory.
+     *
+     * Non-empty; same type as the deferred-ref wire field.
+     */
+    expectedSignatories: CantonExpectedSignatories;
     contractStateFilter?: Record<string, unknown>;
 }
 

package/src/trusted-origin.ts

@@ -0,0 +1,59 @@
+/**
+ * Read a create-argument field, supporting dotted paths (`instrumentId.admin`).
+ */
+export const getCreateArgumentField = (createArgument: unknown, fieldPath: string): unknown => {
+    let current: unknown = createArgument;
+    for (const part of fieldPath.split('.')) {
+        if (current == null || typeof current !== 'object') {
+            return undefined;
+        }
+        current = (current as Record<string, unknown>)[part];
+    }
+    return current;
+};
+
+/**
+ * True when every party in `expectedSignatories` is among the created-event signatories
+ * (expected ⊆ ledger signatories). Opposite of `findMatchingCreatedEvent`, which
+ * requires every ledger signatory to be in the expected/actAs set.
+ *
+ * Drops observer-only foreign contracts that would otherwise poison ACS cardinality.
+ */
+export const areExpectedSignatories = (
+    created: { signatories?: readonly string[] },
+    expectedSignatories: readonly string[],
+): boolean => {
+    if (expectedSignatories.length === 0) return false;
+    const signatories = created.signatories ?? [];
+    return expectedSignatories.every((party) => signatories.includes(party));
+};
+
+/**
+ * True when `expectedParty` is among the created-event signatories.
+ */
+export const isSignatoryOrigin = (
+    created: { signatories?: readonly string[] },
+    expectedParty: string,
+): boolean => areExpectedSignatories(created, [expectedParty]);
+
+/**
+ * True when a created event originated under `expectedParty`: that party is among
+ * the created-event signatories, and `createArgument[createArgumentField]` equals it.
+ *
+ * Use when the template has multiple signatories and the party must bind a
+ * specific payload role (e.g. Request `handler` amid sender / oappAdmin).
+ * Prefer `contractStateFilter` + `expectedSignatories` on deferred refs instead.
+ *
+ * @param createArgumentField - Payload identity field (`owner`, `handler`,
+ *   `admin`, or a dotted path such as `instrumentId.admin`).
+ */
+export const isTrustedOrigin = (
+    created: { createArgument?: unknown; signatories?: readonly string[] },
+    expectedParty: string,
+    createArgumentField: string,
+): boolean => {
+    if (getCreateArgumentField(created.createArgument, createArgumentField) !== expectedParty) {
+        return false;
+    }
+    return isSignatoryOrigin(created, expectedParty);
+};

package/test/deferredValue.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+
+import { NonRetryableError } from '@layerzerolabs/common-error-utils';
+
+import {
+    CANTON_DEFERRED_SENDER,
+    isCantonDeferredSender,
+    isCantonDeferredSentinel,
+    isCantonPlaceholder,
+    parseCantonDeferredValue,
+    parseCantonDeferredValueOrThrow,
+} from '../src/deferredValue';
+
+describe('CANTON_DEFERRED_SENDER', () => {
+    it('is the typed sender token', () => {
+        expect(isCantonDeferredSender(CANTON_DEFERRED_SENDER)).toBe(true);
+        expect(isCantonDeferredSender('alice::1220ab')).toBe(false);
+    });
+});
+
+describe('parseCantonDeferredValueOrThrow', () => {
+    it('returns undefined for non-sentinels', () => {
+        expect(parseCantonDeferredValueOrThrow('00abc')).toBeUndefined();
+        expect(parseCantonDeferredValueOrThrow({ type: 'senderParty' })).toBeUndefined();
+    });
+
+    it('parses a valid sentinel', () => {
+        expect(
+            parseCantonDeferredValueOrThrow('<<CANTON_DEFERRED:{"type":"senderParty"}>>'),
+        ).toEqual({ type: 'senderParty' });
+    });
+
+    it('throws NonRetryableError for a framed but invalid sentinel', () => {
+        const malformed = '<<CANTON_DEFERRED:{"type":"activeContractId","templateId":"#pkg:T"}>>';
+        expect(isCantonDeferredSentinel(malformed)).toBe(true);
+        expect(parseCantonDeferredValue(malformed)).toBeUndefined();
+        expect(isCantonPlaceholder(malformed)).toBe(false);
+        expect(() => parseCantonDeferredValueOrThrow(malformed)).toThrow(NonRetryableError);
+    });
+});

package/test/refresh/deployment-artifacts.test.ts

@@ -0,0 +1,53 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { describe, expect, it } from 'vitest';
+
+import { parseCantonDeferredValue } from '../../src/deferredValue';
+
+const PREFIX = '<<CANTON_DEFERRED:';
+const SUFFIX = '>>';
+
+const encodeAddress = (nativeAddress: string): string => {
+    const inner = nativeAddress.slice(PREFIX.length, -SUFFIX.length);
+    return `0x${Buffer.from(inner, 'utf8').toString('hex')}02`.toLowerCase();
+};
+
+const deploymentRoots = [
+    join(process.cwd(), '../../../../deployments/layerzero/mainnet/canton/deploymentInfo'),
+    join(process.cwd(), '../../../../deployments/layerzero/testnet/canton/deploymentInfo'),
+];
+
+describe('Canton deploymentInfo deferred-ref artifacts', () => {
+    const artifacts = deploymentRoots.flatMap((root) =>
+        readdirSync(root)
+            .filter((file) => file.endsWith('.json'))
+            .map((file) => {
+                const path = join(root, file);
+                return {
+                    path,
+                    json: JSON.parse(readFileSync(path, 'utf8')) as Record<string, unknown>,
+                };
+            })
+            .filter(
+                ({ json }) =>
+                    typeof json.nativeAddress === 'string' &&
+                    (json.nativeAddress as string).startsWith(PREFIX),
+            ),
+    );
+
+    it('has deferred-ref deploy artifacts to check', () => {
+        expect(artifacts.length).toBeGreaterThan(0);
+    });
+
+    it('hex address matches nativeAddress and parses as a deferred ref', () => {
+        for (const { path, json } of artifacts) {
+            const nativeAddress = json.nativeAddress as string;
+            expect(json.address, path).toBe(encodeAddress(nativeAddress));
+            expect(parseCantonDeferredValue(nativeAddress), path).toMatchObject({
+                type: 'activeContractId',
+                templateId: expect.any(String),
+            });
+        }
+    });
+});