@layerzerolabs/common-canton 1.2.69 → 1.2.71

package/src/refresh/resolve-plan.ts

@@ -1,502 +0,0 @@
-import { NonRetryableError } from '@layerzerolabs/common-error-utils';
-
-import type { ICantonClient } from '../client/interface';
-import {
-    type CantonRefreshPartyFilter,
-    isCantonDeferredSender,
-    isCantonDeferredSentinel,
-} from '../deferredValue';
-import type { JsActiveContract } from '../open-api/models';
-import type {
-    CantonCommands,
-    CantonDisclosedContracts,
-    CantonUnresolvedCommands,
-} from '../transaction';
-import { getCreateArgumentField } from '../trusted-origin';
-import { type ActiveContractRef, createContractAddressResolver } from './address-resolver';
-import type {
-    CantonActiveContractRefresh,
-    CantonActiveContractSelection,
-    CantonAmuletContextRefresh,
-    CantonArgumentRefreshTarget,
-    CantonContractSelector,
-    CantonRefresh,
-    CantonRefreshPath,
-    CantonRefreshPlan,
-    CantonRefreshTarget,
-    CantonTimestampRefresh,
-} from './plan';
-
-const DAML_DECIMAL_SCALE = 10n ** 10n;
-const MAX_SELECTED_CONTRACTS = 100;
-const CANTON_TIME_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?Z$/;
-
-const nonRetryable = (message: string): never => {
-    throw new NonRetryableError(message);
-};
-
-const resolveParty = (
-    partyRef: CantonRefreshPartyFilter,
-    senderParty: string | undefined,
-    label: string,
-): string => {
-    if (!isCantonDeferredSender(partyRef)) return partyRef.party;
-    if (!senderParty) {
-        return nonRetryable(`${label} requires a resolved sender party`);
-    }
-    return senderParty;
-};
-
-const parseDamlDecimal = (value: unknown, label: string): bigint => {
-    if (typeof value !== 'string') {
-        return nonRetryable(`${label} must be a DAML Decimal string`);
-    }
-    const match = /^([+-]?)(\d+)(?:\.(\d{0,10}))?$/.exec(value);
-    if (!match) {
-        return nonRetryable(`${label} is not a valid DAML Decimal: ${value}`);
-    }
-    const sign = match[1] === '-' ? -1n : 1n;
-    const whole = BigInt(match[2]!);
-    const fraction = BigInt((match[3] ?? '').padEnd(10, '0'));
-    return sign * (whole * DAML_DECIMAL_SCALE + fraction);
-};
-
-const getContractNumericField = (contract: JsActiveContract, field: string): bigint => {
-    const raw = getCreateArgumentField(contract.createdEvent.createArgument, field);
-    const value =
-        raw !== null && typeof raw === 'object' && 'initialAmount' in raw
-            ? (raw as { initialAmount?: unknown }).initialAmount
-            : raw;
-    return parseDamlDecimal(
-        value,
-        `Contract ${contract.createdEvent.contractId} numeric field ${field}`,
-    );
-};
-
-export const selectContractsByGte = (
-    contracts: JsActiveContract[],
-    field: string,
-    requestedValue: string,
-): JsActiveContract[] => {
-    const requested = parseDamlDecimal(requestedValue, 'Requested contract value');
-    if (requested <= 0n) {
-        return nonRetryable('Requested contract value must be positive');
-    }
-
-    const candidates = contracts
-        .map((contract) => ({
-            contract,
-            amount: getContractNumericField(contract, field),
-        }))
-        .filter(({ amount }) => amount > 0n)
-        .sort((left, right) =>
-            left.amount === right.amount
-                ? left.contract.createdEvent.contractId.localeCompare(
-                      right.contract.createdEvent.contractId,
-                  )
-                : left.amount > right.amount
-                  ? -1
-                  : 1,
-        );
-
-    const selected: JsActiveContract[] = [];
-    let total = 0n;
-    for (const candidate of candidates) {
-        selected.push(candidate.contract);
-        total += candidate.amount;
-        if (total >= requested) break;
-    }
-
-    if (total < requested) {
-        return nonRetryable(
-            `Insufficient contract value in field ${field}: requested ${requestedValue}, found ${total.toString()} base units`,
-        );
-    }
-    if (selected.length > MAX_SELECTED_CONTRACTS) {
-        return nonRetryable(
-            `Selection needs ${selected.length} contracts, exceeding the ${MAX_SELECTED_CONTRACTS} input limit`,
-        );
-    }
-    return selected;
-};
-
-const makeActiveContractRef = (selector: CantonContractSelector): ActiveContractRef => ({
-    type: 'activeContractIds',
-    partyToFilter: selector.queryAs,
-    expectedSignatories: selector.expectedSignatories,
-    templateId: selector.templateId,
-    contractStateFilter: selector.stateFilter,
-});
-
-const selectActiveContracts = (
-    contracts: JsActiveContract[],
-    selection: CantonActiveContractSelection,
-): JsActiveContract[] => {
-    switch (selection.kind) {
-        case 'exactlyOne':
-            if (contracts.length !== 1) {
-                return nonRetryable(
-                    `Active contract selection matched ${contracts.length} contracts, expected exactly one`,
-                );
-            }
-            return contracts;
-        case 'all':
-            return contracts;
-        case 'gte':
-            return selectContractsByGte(contracts, selection.field, selection.value);
-    }
-};
-
-export const resolveCantonActiveContracts = async (args: {
-    client: ICantonClient;
-    selector: CantonContractSelector;
-    selection: CantonActiveContractSelection;
-    senderParty?: string;
-}): Promise<{ contractIds: string[] }> => {
-    const queryParty = resolveParty(
-        args.selector.queryAs,
-        args.senderParty,
-        'Active contract selection',
-    );
-    const ref = makeActiveContractRef(args.selector);
-    const resolver = createContractAddressResolver({
-        client: args.client,
-        senderParty: args.senderParty,
-        signingParties: [queryParty],
-        appendDisclosures: () => undefined,
-    });
-    const selected = selectActiveContracts(
-        await resolver.resolveActiveContracts(ref),
-        args.selection,
-    );
-    return {
-        contractIds: selected.map(({ createdEvent }) => createdEvent.contractId),
-    };
-};
-
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-    value !== null && typeof value === 'object' && !Array.isArray(value);
-
-const isCantonTime = (value: unknown): value is string =>
-    typeof value === 'string' &&
-    CANTON_TIME_PATTERN.test(value) &&
-    Number.isFinite(Date.parse(value));
-
-const isActiveContractRefresh = (refresh: CantonRefresh): refresh is CantonActiveContractRefresh =>
-    refresh.resolver.type === 'activeContract';
-
-const isAmuletContextRefresh = (refresh: CantonRefresh): refresh is CantonAmuletContextRefresh =>
-    refresh.resolver.type === 'amuletContext';
-
-const isTimestampRefresh = (refresh: CantonRefresh): refresh is CantonTimestampRefresh =>
-    refresh.resolver.type === 'timestamp';
-
-const replaceAtPath = (root: unknown, path: CantonRefreshPath, value: unknown): unknown => {
-    if (path.length === 0) return value;
-
-    let current = root;
-    for (const [position, segment] of path.entries()) {
-        const isLast = position === path.length - 1;
-        if ('field' in segment) {
-            if (!isRecord(current) || !(segment.field in current)) {
-                return nonRetryable(`Refresh target field "${segment.field}" does not exist`);
-            }
-            if (isLast) {
-                current[segment.field] = value;
-                return root;
-            }
-            current = current[segment.field];
-            continue;
-        }
-        if ('index' in segment) {
-            if (!Array.isArray(current) || segment.index >= current.length) {
-                return nonRetryable(`Refresh target array index ${segment.index} does not exist`);
-            }
-            if (isLast) {
-                current[segment.index] = value;
-                return root;
-            }
-            current = current[segment.index];
-            continue;
-        }
-
-        if (!Array.isArray(current)) {
-            return nonRetryable(`Refresh target DAML map "${segment.damlMapKey}" is not an array`);
-        }
-        const matches = current.filter(
-            (entry): entry is [string, unknown] =>
-                Array.isArray(entry) && entry.length === 2 && entry[0] === segment.damlMapKey,
-        );
-        if (matches.length !== 1) {
-            return nonRetryable(
-                `Refresh target DAML map key "${segment.damlMapKey}" matched ${matches.length} entries`,
-            );
-        }
-        if (isLast) {
-            matches[0]![1] = value;
-            return root;
-        }
-        current = matches[0]![1];
-    }
-    return root;
-};
-
-const readAtPath = (root: unknown, path: CantonRefreshPath): unknown => {
-    let current = root;
-    for (const segment of path) {
-        if ('field' in segment) {
-            if (!isRecord(current) || !(segment.field in current)) {
-                return nonRetryable(`Refresh target field "${segment.field}" does not exist`);
-            }
-            current = current[segment.field];
-            continue;
-        }
-        if ('index' in segment) {
-            if (!Array.isArray(current) || segment.index >= current.length) {
-                return nonRetryable(`Refresh target array index ${segment.index} does not exist`);
-            }
-            current = current[segment.index];
-            continue;
-        }
-
-        if (!Array.isArray(current)) {
-            return nonRetryable(`Refresh target DAML map "${segment.damlMapKey}" is not an array`);
-        }
-        const matches = current.filter(
-            (entry): entry is [string, unknown] =>
-                Array.isArray(entry) && entry.length === 2 && entry[0] === segment.damlMapKey,
-        );
-        if (matches.length !== 1) {
-            return nonRetryable(
-                `Refresh target DAML map key "${segment.damlMapKey}" matched ${matches.length} entries`,
-            );
-        }
-        current = matches[0]![1];
-    }
-    return current;
-};
-
-const readTarget = (
-    commands: CantonUnresolvedCommands,
-    target: CantonArgumentRefreshTarget,
-    path: CantonRefreshPath,
-): unknown => {
-    const command = commands[target.commandIndex];
-    if (!command) {
-        return nonRetryable(`Refresh command index ${target.commandIndex} does not exist`);
-    }
-
-    if (target.command === 'exercise') {
-        if (!('exerciseCommand' in command)) {
-            return nonRetryable(`Refresh command index ${target.commandIndex} is not an exercise`);
-        }
-        if (command.exerciseCommand.choice !== target.choice) {
-            return nonRetryable(
-                `Refresh command index ${target.commandIndex} expected choice ${target.choice}, found ${command.exerciseCommand.choice}`,
-            );
-        }
-        return readAtPath(command.exerciseCommand.choiceArgument, path);
-    }
-
-    if (!('createCommand' in command)) {
-        return nonRetryable(`Refresh command index ${target.commandIndex} is not a create`);
-    }
-    if (command.createCommand.templateId !== target.template) {
-        return nonRetryable(
-            `Refresh command index ${target.commandIndex} expected template ${target.template}, found ${command.createCommand.templateId}`,
-        );
-    }
-    return readAtPath(command.createCommand.createArguments, path);
-};
-
-const applyPatch = (
-    commands: CantonUnresolvedCommands,
-    target: CantonArgumentRefreshTarget,
-    path: CantonRefreshPath,
-    value: unknown,
-): void => {
-    const command = commands[target.commandIndex];
-    if (!command) {
-        return nonRetryable(`Refresh command index ${target.commandIndex} does not exist`);
-    }
-
-    if (target.command === 'exercise') {
-        if (!('exerciseCommand' in command)) {
-            return nonRetryable(`Refresh command index ${target.commandIndex} is not an exercise`);
-        }
-        if (command.exerciseCommand.choice !== target.choice) {
-            return nonRetryable(
-                `Refresh command index ${target.commandIndex} expected choice ${target.choice}, found ${command.exerciseCommand.choice}`,
-            );
-        }
-        command.exerciseCommand.choiceArgument = replaceAtPath(
-            command.exerciseCommand.choiceArgument,
-            path,
-            value,
-        );
-        return;
-    }
-
-    if (!('createCommand' in command)) {
-        return nonRetryable(`Refresh command index ${target.commandIndex} is not a create`);
-    }
-    if (command.createCommand.templateId !== target.template) {
-        return nonRetryable(
-            `Refresh command index ${target.commandIndex} expected template ${target.template}, found ${command.createCommand.templateId}`,
-        );
-    }
-    command.createCommand.createArguments = replaceAtPath(
-        command.createCommand.createArguments,
-        path,
-        value,
-    );
-};
-
-const applyTarget = (
-    commands: CantonUnresolvedCommands,
-    target: CantonRefreshTarget,
-    value: unknown,
-): void => {
-    if ('field' in target) {
-        const command = commands[target.commandIndex];
-        if (!command) {
-            return nonRetryable(`Refresh command index ${target.commandIndex} does not exist`);
-        }
-        if (!('exerciseCommand' in command)) {
-            return nonRetryable(`Refresh command index ${target.commandIndex} is not an exercise`);
-        }
-        if (typeof value !== 'string') {
-            return nonRetryable('Exercise contract ID refresh must resolve to a string');
-        }
-        command.exerciseCommand.contractId = value;
-        return;
-    }
-
-    for (const argument of target.arguments) {
-        applyPatch(commands, target, argument.path, value);
-    }
-};
-
-const containsDeferredSentinel = (value: unknown, key?: string): boolean => {
-    if (key === 'createdEventBlob') return false;
-    if (isCantonDeferredSentinel(value)) return true;
-    if (Array.isArray(value)) return value.some((item) => containsDeferredSentinel(item));
-    if (!isRecord(value)) return false;
-    return Object.entries(value).some(([childKey, child]) =>
-        containsDeferredSentinel(child, childKey),
-    );
-};
-
-const disclosuresEqual = (
-    left: CantonDisclosedContracts[number],
-    right: CantonDisclosedContracts[number],
-): boolean =>
-    left.contractId === right.contractId &&
-    left.templateId === right.templateId &&
-    left.createdEventBlob === right.createdEventBlob &&
-    left.synchronizerId === right.synchronizerId;
-
-export const resolveCantonRefreshPlan = async (args: {
-    unresolvedCommands: CantonUnresolvedCommands;
-    unresolvedDisclosedContracts: CantonDisclosedContracts;
-    refreshPlan: CantonRefreshPlan;
-    senderParty?: string;
-    signingParties: string[];
-    client: ICantonClient;
-}): Promise<{ commands: CantonCommands; disclosedContracts: CantonDisclosedContracts }> => {
-    if (
-        containsDeferredSentinel(args.unresolvedCommands) ||
-        containsDeferredSentinel(args.unresolvedDisclosedContracts)
-    ) {
-        return nonRetryable('Canton refreshPlan cannot be combined with deferred sentinels');
-    }
-
-    const commands = structuredClone(args.unresolvedCommands);
-    const baselineDisclosureCids = new Set(
-        args.unresolvedDisclosedContracts.map(({ contractId }) => contractId),
-    );
-    const excludedBaselineCids = new Set(args.refreshPlan.disclosures?.excludeBaselineCids ?? []);
-    for (const contractId of excludedBaselineCids) {
-        if (!baselineDisclosureCids.has(contractId)) {
-            return nonRetryable(
-                `Cannot exclude baseline disclosure ${contractId}: it is not present in unresolvedDisclosedContracts`,
-            );
-        }
-    }
-    const disclosureMap = new Map<string, CantonDisclosedContracts[number]>();
-    const appendDisclosures = (disclosures: CantonDisclosedContracts): void => {
-        for (const disclosure of disclosures) {
-            const existing = disclosureMap.get(disclosure.contractId);
-            if (existing && !disclosuresEqual(existing, disclosure)) {
-                return nonRetryable(
-                    `Conflicting disclosures for contract ${disclosure.contractId}`,
-                );
-            }
-            disclosureMap.set(disclosure.contractId, disclosure);
-        }
-    };
-    appendDisclosures(
-        args.unresolvedDisclosedContracts.filter(
-            ({ contractId }) => !excludedBaselineCids.has(contractId),
-        ),
-    );
-
-    const resolver = createContractAddressResolver({
-        client: args.client,
-        senderParty: args.senderParty,
-        signingParties: args.signingParties,
-        appendDisclosures,
-    });
-
-    for (const refresh of args.refreshPlan.commands) {
-        if (isActiveContractRefresh(refresh)) {
-            const ref = makeActiveContractRef(refresh.resolver.selector);
-            const selected = selectActiveContracts(
-                await resolver.resolveActiveContracts(ref),
-                refresh.resolver.selection,
-            );
-            await resolver.discloseActiveContracts(ref, selected);
-            const contractIds = selected.map(({ createdEvent }) => createdEvent.contractId);
-            const resolved =
-                refresh.resolver.selection.kind === 'exactlyOne' ? contractIds[0]! : contractIds;
-            for (const target of refresh.targets) applyTarget(commands, target, resolved);
-            continue;
-        }
-
-        if (isAmuletContextRefresh(refresh)) {
-            const bundle = await args.client.getAmuletContextWithExternalRules({
-                admin: refresh.resolver.dsoParty,
-                id: 'Amulet',
-            });
-            appendDisclosures(bundle.disclosedContracts);
-            for (const target of refresh.targets) {
-                applyTarget(commands, target, bundle.amuletContext);
-            }
-        }
-    }
-
-    // Timestamp refreshes run after all external reads so their shared instant is
-    // as close as possible to prepareForSigning, regardless of declaration order.
-    const now = new Date();
-    for (const refresh of args.refreshPlan.commands) {
-        if (!isTimestampRefresh(refresh)) continue;
-
-        for (const target of refresh.targets) {
-            for (const { path, offsetMs = 0 } of target.arguments) {
-                const iso = new Date(now.getTime() + offsetMs).toISOString();
-                const current = readTarget(commands, target, path);
-                const value = isCantonTime(current)
-                    ? iso
-                    : isRecord(current) && current.tag === 'AV_Time' && isCantonTime(current.value)
-                      ? { ...current, value: iso }
-                      : nonRetryable('Timestamp refresh target must contain a Canton Time value');
-                applyPatch(commands, target, path, value);
-            }
-        }
-    }
-
-    return {
-        commands: commands as CantonCommands,
-        disclosedContracts: [...disclosureMap.values()],
-    };
-};

package/src/refresh/resolve.ts

@@ -1,120 +0,0 @@
-import { AMULET_INSTRUMENT_ID, type ChoiceContext } from '../client/amulet';
-import type { ICantonClient } from '../client/interface';
-import type { CantonDeferredValue } from '../deferredValue';
-import type {
-    CantonCommands,
-    CantonDisclosedContracts,
-    CantonUnresolvedCommands,
-} from '../transaction';
-import { createContractAddressResolver } from './address-resolver';
-import type { CantonRefreshPlan } from './plan';
-import { resolveCantonRefreshPlan } from './resolve-plan';
-import { substituteRefsToCids } from './reverse-substitute';
-
-export interface ResolveCantonAddressParams {
-    unresolvedCommands: CantonUnresolvedCommands;
-    unresolvedDisclosedContracts: CantonDisclosedContracts;
-    refreshPlan?: CantonRefreshPlan;
-    senderParty?: string;
-    /** A contract is only disclosed when none of these parties is already a stakeholder on it. */
-    signingParties: string[];
-    client: ICantonClient;
-}
-
-export const resolveCantonTransaction = async ({
-    unresolvedCommands,
-    unresolvedDisclosedContracts,
-    refreshPlan,
-    senderParty,
-    signingParties,
-    client,
-}: ResolveCantonAddressParams): Promise<{
-    commands: CantonCommands;
-    disclosedContracts: CantonDisclosedContracts;
-}> => {
-    if (refreshPlan) {
-        return resolveCantonRefreshPlan({
-            unresolvedCommands,
-            unresolvedDisclosedContracts,
-            refreshPlan,
-            senderParty,
-            signingParties,
-            client,
-        });
-    }
-
-    const nextDisclosed = [...unresolvedDisclosedContracts];
-    const disclosedContractIds = new Set(
-        unresolvedDisclosedContracts.map(({ contractId }) => contractId),
-    );
-    const appendDisclosures = (disclosures: CantonDisclosedContracts): void => {
-        for (const disclosure of disclosures) {
-            if (!disclosedContractIds.has(disclosure.contractId)) {
-                disclosedContractIds.add(disclosure.contractId);
-                nextDisclosed.push(disclosure);
-            }
-        }
-    };
-
-    const { resolveActiveContractId, resolveActiveContractIds, requireSenderParty } =
-        createContractAddressResolver({
-            client,
-            senderParty,
-            signingParties,
-            appendDisclosures,
-        });
-
-    let amuletBundlePromise:
-        | Promise<{
-              amuletContext: ChoiceContext;
-              externalPartyAmuletRulesCid: string;
-          }>
-        | undefined;
-
-    const getAmuletBundle = async () => {
-        if (!amuletBundlePromise) {
-            amuletBundlePromise = (async () => {
-                const dsoParty = await client.getDsoParty();
-                const {
-                    amuletContext,
-                    disclosedContracts: bundle,
-                    externalPartyAmuletRulesCid,
-                } = await client.getAmuletContextWithExternalRules({
-                    admin: dsoParty,
-                    id: AMULET_INSTRUMENT_ID,
-                });
-                appendDisclosures(bundle);
-                return { amuletContext, externalPartyAmuletRulesCid };
-            })();
-        }
-        return amuletBundlePromise;
-    };
-
-    const resolveRef = async (ref: CantonDeferredValue): Promise<unknown> => {
-        switch (ref.type) {
-            case 'senderParty':
-                return requireSenderParty(ref.type);
-            case 'activeContractId':
-                return resolveActiveContractId(ref);
-            case 'activeContractIds':
-                return resolveActiveContractIds(ref);
-            case 'amuletRulesCid':
-                return (await getAmuletBundle()).externalPartyAmuletRulesCid;
-            case 'amuletContext':
-                return (await getAmuletBundle()).amuletContext;
-        }
-    };
-
-    const resolvedCommands = await substituteRefsToCids(unresolvedCommands, resolveRef);
-    const resolvedDisclosedContracts: CantonDisclosedContracts = [];
-    for (let index = 0; index < nextDisclosed.length; index++) {
-        resolvedDisclosedContracts.push(
-            await substituteRefsToCids(nextDisclosed[index]!, resolveRef),
-        );
-    }
-
-    return {
-        commands: resolvedCommands,
-        disclosedContracts: resolvedDisclosedContracts,
-    };
-};

package/src/refresh/reverse-substitute.ts

@@ -1,63 +0,0 @@
-import { NonRetryableError } from '@layerzerolabs/common-error-utils';
-
-import { type CantonDeferredValue, parseCantonDeferredValueOrThrow } from '../deferredValue';
-
-// Opaque base64 — swapping a cid here would corrupt it.
-const BLOB_KEY = 'createdEventBlob';
-
-export const substituteCidsToRefs = <T>(value: T, cidToRef: Map<string, string>): T => {
-    if (typeof value === 'string') {
-        const ref = cidToRef.get(value);
-        return (ref ?? value) as T;
-    }
-    if (Array.isArray(value)) {
-        return value.map((item) => substituteCidsToRefs(item, cidToRef)) as T;
-    }
-    if (value !== null && typeof value === 'object') {
-        const out: Record<string, unknown> = {};
-        for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
-            out[key] = key === BLOB_KEY ? item : substituteCidsToRefs(item, cidToRef);
-        }
-        return out as T;
-    }
-    return value;
-};
-
-export type ResolveRef = (ref: CantonDeferredValue) => Promise<unknown>;
-
-/** A plural activeContractIds ref expands in place — must be inside an array; a scalar slot throws. */
-export const substituteRefsToCids = async <T>(value: T, resolve: ResolveRef): Promise<T> => {
-    if (Array.isArray(value)) {
-        const items = await Promise.all(
-            value.map(async (item) => {
-                const ref = parseCantonDeferredValueOrThrow(item);
-                return ref?.type === 'activeContractIds'
-                    ? ((await resolve(ref)) as unknown[])
-                    : [await substituteRefsToCids(item, resolve)];
-            }),
-        );
-        return items.flat() as T;
-    }
-
-    const ref = parseCantonDeferredValueOrThrow(value);
-    if (ref) {
-        if (ref.type === 'activeContractIds') {
-            throw new NonRetryableError(
-                `Refresh for ${ref.templateId} resolves to multiple contract ids, but the ref was not inside an array`,
-            );
-        }
-        return (await resolve(ref)) as T;
-    }
-
-    if (value !== null && typeof value === 'object') {
-        const entries = await Promise.all(
-            Object.entries(value as Record<string, unknown>).map(async ([key, item]) => [
-                key,
-                await substituteRefsToCids(item, resolve),
-            ]),
-        );
-        return Object.fromEntries(entries) as T;
-    }
-
-    return value;
-};