@layerzerolabs/common-canton 1.2.68 → 1.2.69

package/test/refresh/resolve-plan.test.ts

@@ -0,0 +1,723 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { NonRetryableError } from '@layerzerolabs/common-error-utils';
+
+import type { ICantonClient } from '../../src/client/interface';
+import { cantonActiveContractIdRef } from '../../src/deferredValue';
+import type { JsActiveContract } from '../../src/open-api/models';
+import { resolveCantonRefreshPlan, selectContractsByGte } from '../../src/refresh';
+import { type CantonRefreshPlan, cantonRefreshPlanSchema } from '../../src/refresh/plan';
+import { cantonTransactionSchema, type CantonUnresolvedCommands } from '../../src/transaction';
+
+const RICH = 'rich::namespace';
+const DSO = 'dso::namespace';
+const INFORMEE = 'informee::namespace';
+
+const activeContract = (args: {
+    contractId: string;
+    templateId: string;
+    createArgument: Record<string, unknown>;
+    signatories: string[];
+    observers?: string[];
+    blob?: string;
+}): JsActiveContract =>
+    ({
+        createdEvent: {
+            offset: 1,
+            nodeId: 0,
+            contractId: args.contractId,
+            templateId: args.templateId,
+            createArgument: args.createArgument,
+            signatories: args.signatories,
+            observers: args.observers ?? [],
+            createdEventBlob: args.blob ?? `blob-${args.contractId}`,
+            createdAt: '2026-01-01T00:00:00.000Z',
+            packageName: 'package',
+            representativePackageId: 'package-id',
+            acsDelta: true,
+        },
+        synchronizerId: 'sync',
+        reassignmentCounter: 0,
+    }) as JsActiveContract;
+
+const amulet = (contractId: string, amount: string): JsActiveContract =>
+    activeContract({
+        contractId,
+        templateId: 'pkg:Splice.Amulet:Amulet',
+        createArgument: { owner: RICH, amount: { initialAmount: amount } },
+        signatories: [DSO],
+        observers: [RICH],
+    });
+
+type ExerciseCommand = Extract<CantonUnresolvedCommands[number], { exerciseCommand: unknown }>;
+type CreateCommand = Extract<CantonUnresolvedCommands[number], { createCommand: unknown }>;
+
+const delegateCommand = (): ExerciseCommand => ({
+    exerciseCommand: {
+        templateId: 'pkg:Executor:Executor',
+        contractId: 'stale-executor',
+        choice: 'DelegateLzReceive',
+        choiceArgument: {
+            amuletCids: ['stale-amulet'],
+            amuletContext: { values: { stale: true } },
+            timestamp: '2020-01-01T00:00:00.000Z',
+            callArgs: [['timestamp', { tag: 'AV_Time', value: '2020-01-01T00:00:00.000Z' }]],
+        },
+    },
+});
+
+const timedCreateCommand = (): CreateCommand => ({
+    createCommand: {
+        templateId: 'pkg:Timed:Timed',
+        createArguments: {
+            executeBefore: '2020-01-01T00:00:00.000Z',
+        },
+    },
+});
+
+const getExercise = (command: CantonUnresolvedCommands[number]) => {
+    if (!('exerciseCommand' in command)) throw new Error('Expected exercise command');
+    return command.exerciseCommand;
+};
+
+const plan = (): CantonRefreshPlan => ({
+    commands: [
+        {
+            resolver: {
+                type: 'activeContract',
+                selector: {
+                    queryAs: { party: RICH },
+                    templateId: '#layerzero-executor:Executor:Executor',
+                    expectedSignatories: [RICH],
+                },
+                selection: { kind: 'exactlyOne' },
+            },
+            targets: [
+                {
+                    commandIndex: 0,
+                    command: 'exercise',
+                    field: 'contractId',
+                },
+            ],
+        },
+        {
+            resolver: {
+                type: 'activeContract',
+                selector: {
+                    queryAs: { party: RICH },
+                    templateId: '#splice-amulet:Splice.Amulet:Amulet',
+                    expectedSignatories: [DSO],
+                    stateFilter: { owner: RICH },
+                },
+                selection: { kind: 'gte', field: 'amount', value: '5.0' },
+            },
+            targets: [
+                {
+                    commandIndex: 0,
+                    command: 'exercise',
+                    choice: 'DelegateLzReceive',
+                    arguments: [{ path: [{ field: 'amuletCids' }] }],
+                },
+            ],
+        },
+        {
+            resolver: {
+                type: 'amuletContext',
+                dsoParty: DSO,
+            },
+            targets: [
+                {
+                    commandIndex: 0,
+                    command: 'exercise',
+                    choice: 'DelegateLzReceive',
+                    arguments: [{ path: [{ field: 'amuletContext' }] }],
+                },
+            ],
+        },
+        {
+            resolver: {
+                type: 'timestamp',
+            },
+            targets: [
+                {
+                    commandIndex: 0,
+                    command: 'exercise',
+                    choice: 'DelegateLzReceive',
+                    arguments: [
+                        { path: [{ field: 'timestamp' }] },
+                        {
+                            path: [{ field: 'callArgs' }, { damlMapKey: 'timestamp' }],
+                        },
+                    ],
+                },
+            ],
+        },
+    ],
+    disclosures: {
+        excludeBaselineCids: ['stale-rules'],
+    },
+});
+
+describe('Canton refresh plan', () => {
+    it('round-trips through the populated transaction schema', () => {
+        const refreshPlan = plan();
+        const parsed = cantonTransactionSchema.parse({
+            chainName: 'canton',
+            timestamps: { created: 1 },
+            populatedTransaction: {
+                unresolvedCommands: [delegateCommand()],
+                unresolvedDisclosedContracts: [],
+                actAs: [RICH],
+                refreshPlan,
+            },
+        });
+        expect(JSON.parse(JSON.stringify(parsed.populatedTransaction.refreshPlan))).toEqual(
+            refreshPlan,
+        );
+    });
+
+    it('requires choice for choice-argument targets', () => {
+        expect(
+            cantonRefreshPlanSchema.safeParse({
+                commands: [
+                    {
+                        resolver: { type: 'timestamp' },
+                        targets: [
+                            {
+                                commandIndex: 0,
+                                command: 'exercise',
+                                arguments: [{ path: [{ field: 'timestamp' }] }],
+                            },
+                        ],
+                    },
+                ],
+            }).success,
+        ).toBe(false);
+    });
+
+    it('restricts command resolvers to compatible targets', () => {
+        const contractIdTarget = {
+            commandIndex: 0,
+            command: 'exercise',
+            field: 'contractId',
+        };
+
+        expect(
+            cantonRefreshPlanSchema.safeParse({
+                commands: [
+                    {
+                        resolver: { type: 'timestamp' },
+                        targets: [contractIdTarget],
+                    },
+                ],
+            }).success,
+        ).toBe(false);
+        expect(
+            cantonRefreshPlanSchema.safeParse({
+                commands: [
+                    {
+                        resolver: { type: 'amuletContext', dsoParty: DSO },
+                        targets: [contractIdTarget],
+                    },
+                ],
+            }).success,
+        ).toBe(false);
+        expect(
+            cantonRefreshPlanSchema.safeParse({
+                commands: [
+                    {
+                        resolver: {
+                            type: 'activeContract',
+                            selector: {
+                                queryAs: { party: RICH },
+                                templateId: '#splice-amulet:Splice.Amulet:Amulet',
+                                expectedSignatories: [DSO],
+                            },
+                            selection: { kind: 'gte', field: 'amount', value: '5.0' },
+                        },
+                        targets: [contractIdTarget],
+                    },
+                ],
+            }).success,
+        ).toBe(false);
+    });
+
+    it('requires timestamp targets to have a nested path', () => {
+        expect(
+            cantonRefreshPlanSchema.safeParse({
+                commands: [
+                    {
+                        resolver: { type: 'timestamp' },
+                        targets: [
+                            {
+                                commandIndex: 0,
+                                command: 'exercise',
+                                choice: 'DelegateLzReceive',
+                                arguments: [{ path: [] }],
+                            },
+                        ],
+                    },
+                ],
+            }).success,
+        ).toBe(false);
+    });
+
+    it('requires baseline disclosure exclusions to be non-empty and unique', () => {
+        const refreshPlan = plan();
+        expect(
+            cantonRefreshPlanSchema.safeParse({
+                ...refreshPlan,
+                disclosures: { excludeBaselineCids: [] },
+            }).success,
+        ).toBe(false);
+        expect(
+            cantonRefreshPlanSchema.safeParse({
+                ...refreshPlan,
+                disclosures: { excludeBaselineCids: ['stale-rules', 'stale-rules'] },
+            }).success,
+        ).toBe(false);
+    });
+
+    it('rejects excluding a disclosure that is not in the persisted baseline', async () => {
+        await expect(
+            resolveCantonRefreshPlan({
+                unresolvedCommands: [delegateCommand()],
+                unresolvedDisclosedContracts: [],
+                refreshPlan: plan(),
+                signingParties: [RICH],
+                client: {} as ICantonClient,
+            }),
+        ).rejects.toThrow(/not present in unresolvedDisclosedContracts/);
+    });
+
+    it('applies timestamps after external refreshes regardless of declaration order', async () => {
+        vi.useFakeTimers();
+        try {
+            vi.setSystemTime(new Date('2026-01-01T00:00:00.000Z'));
+            const client = {
+                getAmuletContextWithExternalRules: vi.fn(async () => {
+                    vi.setSystemTime(new Date('2026-01-01T00:01:00.000Z'));
+                    return {
+                        amuletContext: { values: { fresh: true } },
+                        externalPartyAmuletRulesCid: 'rules',
+                        disclosedContracts: [],
+                    };
+                }),
+            } as unknown as ICantonClient;
+
+            const result = await resolveCantonRefreshPlan({
+                unresolvedCommands: [delegateCommand()],
+                unresolvedDisclosedContracts: [],
+                refreshPlan: {
+                    commands: [
+                        {
+                            resolver: { type: 'timestamp' },
+                            targets: [
+                                {
+                                    commandIndex: 0,
+                                    command: 'exercise',
+                                    choice: 'DelegateLzReceive',
+                                    arguments: [{ path: [{ field: 'timestamp' }] }],
+                                },
+                            ],
+                        },
+                        {
+                            resolver: { type: 'amuletContext', dsoParty: DSO },
+                            targets: [
+                                {
+                                    commandIndex: 0,
+                                    command: 'exercise',
+                                    choice: 'DelegateLzReceive',
+                                    arguments: [{ path: [{ field: 'amuletContext' }] }],
+                                },
+                            ],
+                        },
+                    ],
+                },
+                signingParties: [RICH],
+                client,
+            });
+
+            const exercise = getExercise(result.commands[0]!);
+            expect(exercise.choiceArgument).toMatchObject({
+                timestamp: '2026-01-01T00:01:00.000Z',
+                amuletContext: { values: { fresh: true } },
+            });
+        } finally {
+            vi.useRealTimers();
+        }
+    });
+
+    it('rejects timestamp targets whose current value is not a Canton Time', async () => {
+        const command = delegateCommand();
+        (command.exerciseCommand.choiceArgument as Record<string, unknown>).guid = 'not-a-time';
+
+        await expect(
+            resolveCantonRefreshPlan({
+                unresolvedCommands: [command],
+                unresolvedDisclosedContracts: [],
+                refreshPlan: {
+                    commands: [
+                        {
+                            resolver: { type: 'timestamp' },
+                            targets: [
+                                {
+                                    commandIndex: 0,
+                                    command: 'exercise',
+                                    choice: 'DelegateLzReceive',
+                                    arguments: [{ path: [{ field: 'guid' }] }],
+                                },
+                            ],
+                        },
+                    ],
+                },
+                signingParties: [RICH],
+                client: {} as ICantonClient,
+            }),
+        ).rejects.toThrow(/must contain a Canton Time/);
+    });
+
+    it('patches a timestamp inside nested DAML maps', async () => {
+        vi.useFakeTimers();
+        try {
+            vi.setSystemTime(new Date('2026-02-03T04:05:06.000Z'));
+            const command = delegateCommand();
+            (command.exerciseCommand.choiceArgument as Record<string, unknown>).nestedMaps = [
+                ['outer', [['inner', { tag: 'AV_Time', value: '2020-01-01T00:00:00.000Z' }]]],
+            ];
+
+            const result = await resolveCantonRefreshPlan({
+                unresolvedCommands: [command],
+                unresolvedDisclosedContracts: [],
+                refreshPlan: {
+                    commands: [
+                        {
+                            resolver: { type: 'timestamp' },
+                            targets: [
+                                {
+                                    commandIndex: 0,
+                                    command: 'exercise',
+                                    choice: 'DelegateLzReceive',
+                                    arguments: [
+                                        {
+                                            path: [
+                                                { field: 'nestedMaps' },
+                                                { damlMapKey: 'outer' },
+                                                { damlMapKey: 'inner' },
+                                            ],
+                                        },
+                                    ],
+                                },
+                            ],
+                        },
+                    ],
+                },
+                signingParties: [RICH],
+                client: {} as ICantonClient,
+            });
+
+            expect(getExercise(result.commands[0]!).choiceArgument).toMatchObject({
+                nestedMaps: [
+                    ['outer', [['inner', { tag: 'AV_Time', value: '2026-02-03T04:05:06.000Z' }]]],
+                ],
+            });
+        } finally {
+            vi.useRealTimers();
+        }
+    });
+
+    it('patches guarded create arguments with a per-patch offset', async () => {
+        vi.useFakeTimers();
+        try {
+            vi.setSystemTime(new Date('2026-02-03T04:05:06.000Z'));
+            const result = await resolveCantonRefreshPlan({
+                unresolvedCommands: [timedCreateCommand()],
+                unresolvedDisclosedContracts: [],
+                refreshPlan: {
+                    commands: [
+                        {
+                            resolver: { type: 'timestamp' },
+                            targets: [
+                                {
+                                    commandIndex: 0,
+                                    command: 'create',
+                                    template: 'pkg:Timed:Timed',
+                                    arguments: [
+                                        {
+                                            path: [{ field: 'executeBefore' }],
+                                            offsetMs: 60_000,
+                                        },
+                                    ],
+                                },
+                            ],
+                        },
+                    ],
+                },
+                signingParties: [RICH],
+                client: {} as ICantonClient,
+            });
+
+            expect(result.commands[0]).toMatchObject({
+                createCommand: {
+                    createArguments: {
+                        executeBefore: '2026-02-03T04:06:06.000Z',
+                    },
+                },
+            });
+        } finally {
+            vi.useRealTimers();
+        }
+    });
+
+    it('uses latest ACS reads and one instant while replacing commands and disclosures', async () => {
+        const executor = activeContract({
+            contractId: 'fresh-executor',
+            templateId: 'pkg:Executor:Executor',
+            createArgument: {},
+            signatories: [RICH],
+        });
+        const queryActiveContracts = vi.fn(
+            async (_party: string, offset: number, opts?: { templateIds?: string[] }) => {
+                expect(offset).toBe(42);
+                if (opts?.templateIds?.[0]?.includes('Executor')) return [executor];
+                return [amulet('amulet-3', '3.0'), amulet('amulet-4', '4.0')];
+            },
+        );
+        const client = {
+            getLedgerEndOffset: vi.fn(async () => 42),
+            queryActiveContracts,
+            getAmuletContextWithExternalRules: vi.fn(async () => ({
+                amuletContext: { values: { fresh: true } },
+                externalPartyAmuletRulesCid: 'fresh-rules',
+                disclosedContracts: [
+                    {
+                        contractId: 'fresh-rules',
+                        templateId: 'pkg:ExternalPartyAmuletRules',
+                        createdEventBlob: 'fresh-rules-blob',
+                        synchronizerId: 'sync',
+                    },
+                ],
+            })),
+        } as unknown as ICantonClient;
+        const unresolvedCommands = [delegateCommand()];
+
+        const result = await resolveCantonRefreshPlan({
+            unresolvedCommands,
+            unresolvedDisclosedContracts: [
+                {
+                    contractId: 'static',
+                    templateId: 'pkg:Static',
+                    createdEventBlob: 'static-blob',
+                    synchronizerId: 'sync',
+                },
+                {
+                    contractId: 'stale-rules',
+                    templateId: 'pkg:ExternalPartyAmuletRules',
+                    createdEventBlob: 'stale-rules-blob',
+                    synchronizerId: 'sync',
+                },
+            ],
+            refreshPlan: plan(),
+            signingParties: [RICH],
+            client,
+        });
+
+        const exercise = getExercise(result.commands[0]!);
+        expect(exercise.contractId).toBe('fresh-executor');
+        expect(exercise.choiceArgument).toMatchObject({
+            amuletCids: ['amulet-4', 'amulet-3'],
+            amuletContext: { values: { fresh: true } },
+        });
+        const args = exercise.choiceArgument as {
+            timestamp: string;
+            callArgs: Array<[string, { tag: string; value: string }]>;
+        };
+        expect(args.callArgs[0]![1]).toEqual({
+            tag: 'AV_Time',
+            value: args.timestamp,
+        });
+        expect(result.disclosedContracts.map(({ contractId }) => contractId)).toEqual([
+            'static',
+            'fresh-rules',
+        ]);
+        expect(client.getLedgerEndOffset).toHaveBeenCalledTimes(2);
+        expect(queryActiveContracts).toHaveBeenCalledTimes(2);
+        expect(queryActiveContracts).toHaveBeenCalledWith(
+            RICH,
+            42,
+            expect.objectContaining({ includeCreatedEventBlob: true }),
+        );
+        expect(getExercise(unresolvedCommands[0]!).contractId).toBe('stale-executor');
+    });
+
+    it('replaces a stale disclosure with the coherent ACS disclosure', async () => {
+        const fresh = activeContract({
+            contractId: 'fresh-config',
+            templateId: 'pkg:Config:Config',
+            createArgument: { owner: RICH },
+            signatories: [RICH],
+            observers: [INFORMEE],
+            blob: 'fresh-blob',
+        });
+        const client = {
+            getLedgerEndOffset: vi.fn(async () => 9),
+            queryActiveContracts: vi.fn(async () => [fresh]),
+        } as unknown as ICantonClient;
+        const command = delegateCommand();
+        (command.exerciseCommand.choiceArgument as Record<string, unknown>).configCid =
+            'stale-config';
+
+        const result = await resolveCantonRefreshPlan({
+            unresolvedCommands: [command],
+            unresolvedDisclosedContracts: [
+                {
+                    contractId: 'stale-config',
+                    templateId: 'pkg:Config:Config',
+                    createdEventBlob: 'stale-blob',
+                    synchronizerId: 'sync',
+                },
+            ],
+            refreshPlan: {
+                commands: [
+                    {
+                        resolver: {
+                            type: 'activeContract',
+                            selector: {
+                                queryAs: { party: INFORMEE },
+                                templateId: '#package:Config:Config',
+                                expectedSignatories: [RICH],
+                            },
+                            selection: { kind: 'exactlyOne' },
+                        },
+                        targets: [
+                            {
+                                commandIndex: 0,
+                                command: 'exercise',
+                                choice: 'DelegateLzReceive',
+                                arguments: [{ path: [{ field: 'configCid' }] }],
+                            },
+                        ],
+                    },
+                ],
+                disclosures: {
+                    excludeBaselineCids: ['stale-config'],
+                },
+            },
+            signingParties: ['different-signer'],
+            client,
+        });
+
+        expect(result.disclosedContracts).toEqual([
+            {
+                contractId: 'fresh-config',
+                templateId: 'pkg:Config:Config',
+                createdEventBlob: 'fresh-blob',
+                synchronizerId: 'sync',
+            },
+        ]);
+    });
+
+    it('does not mutate unresolved commands when a later target is invalid', async () => {
+        const command = delegateCommand();
+        const client = {
+            getLedgerEndOffset: vi.fn(async () => 1),
+            getAmuletContextWithExternalRules: vi.fn(async () => ({
+                amuletContext: { values: { fresh: true } },
+                externalPartyAmuletRulesCid: 'rules',
+                disclosedContracts: [],
+            })),
+        } as unknown as ICantonClient;
+
+        await expect(
+            resolveCantonRefreshPlan({
+                unresolvedCommands: [command],
+                unresolvedDisclosedContracts: [],
+                refreshPlan: {
+                    commands: [
+                        {
+                            resolver: { type: 'timestamp' },
+                            targets: [
+                                {
+                                    commandIndex: 0,
+                                    command: 'exercise',
+                                    choice: 'DelegateLzReceive',
+                                    arguments: [{ path: [{ field: 'timestamp' }] }],
+                                },
+                            ],
+                        },
+                        {
+                            resolver: { type: 'amuletContext', dsoParty: DSO },
+                            targets: [
+                                {
+                                    commandIndex: 0,
+                                    command: 'exercise',
+                                    choice: 'WrongChoice',
+                                    arguments: [{ path: [{ field: 'amuletContext' }] }],
+                                },
+                            ],
+                        },
+                    ],
+                },
+                signingParties: [RICH],
+                client,
+            }),
+        ).rejects.toBeInstanceOf(NonRetryableError);
+        expect(command.exerciseCommand.choiceArgument).toMatchObject({
+            timestamp: '2020-01-01T00:00:00.000Z',
+            amuletContext: { values: { stale: true } },
+        });
+    });
+
+    it('rejects mixing a refresh plan with legacy sentinels', async () => {
+        const command = delegateCommand();
+        command.exerciseCommand.contractId = cantonActiveContractIdRef({
+            partyToFilter: { party: RICH },
+            expectedSignatories: [RICH],
+            templateId: '#package:Executor:Executor',
+        });
+
+        await expect(
+            resolveCantonRefreshPlan({
+                unresolvedCommands: [command],
+                unresolvedDisclosedContracts: [],
+                refreshPlan: plan(),
+                signingParties: [RICH],
+                client: {
+                    getLedgerEndOffset: vi.fn(async () => 1),
+                } as unknown as ICantonClient,
+            }),
+        ).rejects.toThrow(/cannot be combined/);
+    });
+});
+
+describe('selectContractsByGte', () => {
+    it('selects deterministically until the requested field value is covered', () => {
+        expect(
+            selectContractsByGte(
+                [amulet('cid-b', '2.0'), amulet('cid-a', '2.0'), amulet('cid-c', '4.0')],
+                'amount',
+                '5.0',
+            ).map(({ createdEvent }) => createdEvent.contractId),
+        ).toEqual(['cid-c', 'cid-a']);
+    });
+
+    it('fails when the combined balance is insufficient', () => {
+        expect(() => selectContractsByGte([amulet('cid-a', '1.0')], 'amount', '2.0')).toThrow(
+            /Insufficient contract value/,
+        );
+    });
+
+    it('supports a different numeric create-argument field', () => {
+        const credit = activeContract({
+            contractId: 'credit-cid',
+            templateId: 'pkg:Asset:Credit',
+            createArgument: { availableCredit: '3.0' },
+            signatories: [RICH],
+        });
+        expect(
+            selectContractsByGte([credit], 'availableCredit', '2.0').map(
+                ({ createdEvent }) => createdEvent.contractId,
+            ),
+        ).toEqual(['credit-cid']);
+    });
+});