@layerzerolabs/common-canton 0.2.78

package/src/client/canton-client.ts

@@ -0,0 +1,949 @@
+import type { ContractId } from '@daml/types';
+import { once } from 'es-toolkit';
+import { randomUUID } from 'node:crypto';
+
+import { CantonProtocolError, CantonTransportError } from '../errors';
+import {
+    DefaultApi,
+    type PostV2CommandsAsyncSubmitRequest,
+    type PostV2CommandsCompletionsRequest,
+    type PostV2DarsRequest,
+    type PostV2DarsValidateRequest,
+    type PostV2EventsEventsByContractIdRequest,
+    type PostV2InteractiveSubmissionExecuteRequest,
+    type PostV2InteractiveSubmissionPreferredPackagesRequest,
+    type PostV2InteractiveSubmissionPrepareRequest,
+} from '../open-api/apis/DefaultApi';
+import {
+    type ArchivedEvent,
+    type Command,
+    type CreatedEvent,
+    type CumulativeFilter,
+    type DisclosedContract,
+    type JsActiveContract,
+    JsActiveContractFromJSON,
+} from '../open-api/models';
+import type { Configuration } from '../open-api/runtime';
+import type {
+    ExternalSignature,
+    PreparedTransaction,
+    SubmitActors,
+    SubmitResult,
+    WaitOptions,
+    WaitResult,
+} from '../types';
+import type {
+    CantonTransaction,
+    CantonUpdate,
+    CantonUpdateResponse,
+    ICantonClient,
+} from './interface';
+
+/**
+ * CantonClient - The engine layer for Canton ledger operations.
+ *
+ * Responsibilities:
+ * - Synchronizer discovery and caching
+ * - Command submission and completion waiting
+ * - Disclosed contract building
+ * - JSON normalization (temporary workaround)
+ *
+ * This class uses composition (not inheritance) to wrap the generated API,
+ * exposing only the minimal surface needed for ledger app operations.
+ */
+export class CantonClient implements ICantonClient {
+    readonly #api: DefaultApi;
+    readonly #userId: string;
+
+    constructor(config: Configuration, userId: string = 'participant_admin') {
+        this.#api = new DefaultApi(config);
+        this.#userId = userId;
+    }
+
+    /**
+     * Get a property from an object, trying PascalCase first then camelCase.
+     * Canton API returns PascalCase but OpenAPI expects camelCase.
+     */
+    #getField<T>(obj: Record<string, unknown> | undefined, key: string): T | undefined {
+        if (!obj) return undefined;
+        const pascal = key.charAt(0).toUpperCase() + key.slice(1);
+        const camel = key.charAt(0).toLowerCase() + key.slice(1);
+        return (obj[pascal] ?? obj[camel]) as T | undefined;
+    }
+
+    /**
+     * Try to extract error body from API response.
+     * Returns the parsed body or null if extraction fails.
+     */
+    async #extractErrorBody(err: unknown): Promise<Record<string, unknown> | null> {
+        if (err && typeof err === 'object' && 'response' in err) {
+            const resp = (err as { response: Response }).response;
+            if (resp && typeof resp.json === 'function') {
+                return (await resp.json().catch(() => null)) as Record<string, unknown> | null;
+            }
+        }
+        return null;
+    }
+
+    /**
+     * Throw a CantonProtocolError with extracted error details from API response.
+     * Handles the common pattern of extracting JSON error details from failed requests.
+     *
+     * @param err - The caught error
+     * @param context - Description of the operation (e.g., "DAR upload", "Party allocation")
+     * @throws CantonProtocolError with extracted error details, or re-throws original error
+     */
+    async #throwApiError(err: unknown, context: string): Promise<never> {
+        const body = await this.#extractErrorBody(err);
+        if (body) {
+            throw new CantonProtocolError(`${context} failed: ${JSON.stringify(body)}`);
+        }
+        throw err;
+    }
+
+    /**
+     * Build party-based filter object for event queries.
+     */
+    #buildPartyFilters(parties: string[], includeCreatedEventBlob: boolean) {
+        return Object.fromEntries(
+            parties.map((p) => [
+                p,
+                {
+                    cumulative: [
+                        {
+                            identifierFilter: {
+                                wildcardFilter: { value: { includeCreatedEventBlob } },
+                            },
+                        },
+                    ],
+                },
+            ]),
+        );
+    }
+
+    /**
+     * Validate and extract disclosure fields from a CreatedEvent.
+     */
+    #validateDisclosureEvent(
+        event: { templateId?: string; contractId?: string; createdEventBlob?: string },
+        contractId: ContractId<unknown>,
+    ): { templateId: string; contractId: string; createdEventBlob: string } {
+        if (!event.templateId) {
+            throw new CantonProtocolError('Disclosure response missing templateId', {
+                contractId,
+            });
+        }
+        if (!event.contractId) {
+            throw new CantonProtocolError('Disclosure response missing contractId', {
+                contractId,
+            });
+        }
+        if (!event.createdEventBlob) {
+            throw new CantonProtocolError('Disclosure response missing createdEventBlob', {
+                contractId,
+            });
+        }
+        return {
+            templateId: event.templateId,
+            contractId: event.contractId,
+            createdEventBlob: event.createdEventBlob,
+        };
+    }
+
+    /**
+     * Validate and extract prepared transaction fields from a prepare response.
+     */
+    #validatePrepareResponse(response: {
+        preparedTransaction?: string;
+        preparedTransactionHash?: string;
+        hashingSchemeVersion?: string;
+    }): {
+        preparedTransaction: string;
+        preparedTransactionHash: string;
+        hashingSchemeVersion: string;
+    } {
+        if (!response.preparedTransaction) {
+            throw new CantonProtocolError('Prepare response missing preparedTransaction');
+        }
+        if (!response.preparedTransactionHash) {
+            throw new CantonProtocolError('Prepare response missing preparedTransactionHash');
+        }
+        if (!response.hashingSchemeVersion) {
+            throw new CantonProtocolError('Prepare response missing hashingSchemeVersion');
+        }
+        return {
+            preparedTransaction: response.preparedTransaction,
+            preparedTransactionHash: response.preparedTransactionHash,
+            hashingSchemeVersion: response.hashingSchemeVersion,
+        };
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Synchronizer Discovery
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Returns all connected synchronizer IDs.
+     */
+    async connectedSynchronizers(): Promise<string[]> {
+        const response = await this.#api.getV2StateConnectedSynchronizers();
+        const synchronizers = response.connectedSynchronizers ?? [];
+        return synchronizers.map((s) => s.synchronizerId).filter((id): id is string => !!id);
+    }
+
+    /**
+     * Internal: ensures we have a cached synchronizer ID, fetching if needed.
+     */
+    #ensureSynchronizerId = once(async (): Promise<string> => {
+        const [id] = await this.connectedSynchronizers();
+
+        if (!id) {
+            throw new CantonTransportError('No connected synchronizers found');
+        }
+
+        return id;
+    });
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // DAR Upload / Validation
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Upload a DAR (Daml Archive) to the participant node.
+     *
+     * @param dar - Raw DAR bytes.
+     * @param opts.vetAllPackages - Whether to vet all packages in the DAR.
+     * @param opts.synchronizerId - Synchronizer to upload to (auto-detected if omitted).
+     * @param opts.skipIfVetted - If true, silently succeeds when the DAR is already vetted.
+     */
+    async uploadDar(
+        dar: Uint8Array<ArrayBuffer>,
+        opts: { vetAllPackages?: boolean; synchronizerId?: string; skipIfVetted?: boolean } = {},
+    ): Promise<object> {
+        // Extract the underlying ArrayBuffer, handling views that don't start at offset 0
+        const bytes =
+            dar.byteOffset === 0 && dar.byteLength === dar.buffer.byteLength
+                ? dar.buffer
+                : dar.buffer.slice(dar.byteOffset, dar.byteOffset + dar.byteLength);
+        const body = new Blob([bytes], { type: 'application/octet-stream' });
+        const synchronizerId = opts.synchronizerId ?? (await this.#ensureSynchronizerId());
+        const request: PostV2DarsRequest = {
+            body,
+            vetAllPackages: opts.vetAllPackages,
+            synchronizerId,
+        };
+
+        try {
+            return await this.#api.postV2Dars(request);
+        } catch (err: unknown) {
+            // If skipIfVetted, treat KNOWN_PACKAGE_VERSION as a no-op success
+            if (opts.skipIfVetted) {
+                const body = await this.#extractErrorBody(err);
+                if (body) {
+                    if (body.code === 'KNOWN_PACKAGE_VERSION') {
+                        return { skipped: true, reason: 'already_vetted', details: body };
+                    }
+                    throw new CantonProtocolError(`DAR upload failed: ${JSON.stringify(body)}`);
+                }
+            }
+            throw await this.#throwApiError(err, 'DAR upload');
+        }
+    }
+
+    /**
+     * Validate a DAR against the participant without uploading it.
+     *
+     * @param dar - Raw DAR bytes.
+     * @param opts.synchronizerId - Synchronizer to validate against (auto-detected if omitted).
+     */
+    async validateDar(
+        dar: Uint8Array<ArrayBuffer>,
+        opts: { synchronizerId?: string } = {},
+    ): Promise<void> {
+        const bytes =
+            dar.byteOffset === 0 && dar.byteLength === dar.buffer.byteLength
+                ? dar.buffer
+                : dar.buffer.slice(dar.byteOffset, dar.byteOffset + dar.byteLength);
+        const body = new Blob([bytes], { type: 'application/octet-stream' });
+        const request: PostV2DarsValidateRequest = {
+            body,
+            synchronizerId: opts.synchronizerId,
+        };
+
+        if (!request.synchronizerId) {
+            return this.#ensureSynchronizerId().then((synchronizerId) =>
+                this.#api.postV2DarsValidate({ ...request, synchronizerId }),
+            );
+        }
+
+        return this.#api.postV2DarsValidate(request);
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Party Management
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * List all known parties on the participant node.
+     *
+     * @param opts.pageSize - Maximum number of results per page
+     * @param opts.pageToken - Pagination token from previous response
+     * @returns Array of party IDs and pagination token
+     */
+    async listParties(
+        opts: { pageSize?: number; pageToken?: string } = {},
+    ): Promise<{ parties: string[]; nextPageToken: string }> {
+        const response = await this.#api.getV2Parties({
+            pageSize: opts.pageSize,
+            pageToken: opts.pageToken,
+        });
+
+        return {
+            parties: response.partyDetails?.map((p) => p.party) ?? [],
+            nextPageToken: response.nextPageToken,
+        };
+    }
+
+    /**
+     * Allocate a new party on the participant node.
+     *
+     * @param partyIdHint - A hint for the party ID (e.g., "alice", "bob")
+     * @param opts.userId - User who gets actAs rights (empty string = no user)
+     * @param opts.synchronizerId - Synchronizer to allocate on (auto-detected if omitted)
+     * @param opts.identityProviderId - Identity provider ID (empty string = default)
+     * @returns The allocated party ID
+     */
+    async allocateParty(
+        partyIdHint: string,
+        opts: { userId?: string; synchronizerId?: string; identityProviderId?: string } = {},
+    ): Promise<string> {
+        const synchronizerId = opts.synchronizerId ?? (await this.#ensureSynchronizerId());
+
+        let response;
+        try {
+            response = await this.#api.postV2Parties({
+                allocatePartyRequest: {
+                    partyIdHint,
+                    synchronizerId,
+                    userId: opts.userId ?? '',
+                    identityProviderId: opts.identityProviderId ?? '',
+                },
+            });
+        } catch (err: unknown) {
+            throw await this.#throwApiError(err, 'Party allocation');
+        }
+
+        const party = response.partyDetails?.party;
+        if (!party) {
+            throw new CantonProtocolError('Party allocation response missing party ID');
+        }
+
+        return party;
+    }
+
+    /**
+     * Get the package ID for a package by name.
+     *
+     * @param packageName - The package name (e.g., "layerzero-oft")
+     * @param parties - Parties whose vetting state should be considered
+     * @param opts.synchronizerId - Synchronizer to query (auto-detected if omitted)
+     * @returns The package ID (hash)
+     */
+    async getPackageId(
+        packageName: string,
+        parties: string[],
+        opts: { synchronizerId?: string } = {},
+    ): Promise<string> {
+        const synchronizerId = opts.synchronizerId ?? (await this.#ensureSynchronizerId());
+
+        const request: PostV2InteractiveSubmissionPreferredPackagesRequest = {
+            getPreferredPackagesRequest: {
+                packageVettingRequirements: [
+                    {
+                        packageName,
+                        parties,
+                    },
+                ],
+                synchronizerId,
+            },
+        };
+
+        let response;
+        try {
+            response = await this.#api.postV2InteractiveSubmissionPreferredPackages(request);
+        } catch (err: unknown) {
+            throw await this.#throwApiError(err, 'Package lookup');
+        }
+
+        const packageRef = response.packageReferences?.find(
+            (ref) => ref.packageName === packageName,
+        );
+        if (!packageRef?.packageId) {
+            throw new CantonProtocolError(
+                `Package "${packageName}" not found or not vetted for parties`,
+            );
+        }
+
+        return packageRef.packageId;
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Command Submission
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Submit a batch of commands atomically.
+     *
+     * @returns commandId and completionOffset for use with waitForCommand()
+     */
+    async submit(
+        actors: SubmitActors,
+        commands: Command[],
+        opts: { disclosedContracts?: DisclosedContract[]; commandId?: string } = {},
+    ): Promise<SubmitResult> {
+        const synchronizerId = await this.#ensureSynchronizerId();
+        const commandId = opts.commandId ?? randomUUID();
+
+        // Snapshot ledger end before submission so waitForCommand knows where to start polling
+        const ledgerEndResponse = await this.#api.getV2StateLedgerEnd();
+        const completionOffset = ledgerEndResponse.offset;
+
+        const request: PostV2CommandsAsyncSubmitRequest = {
+            jsCommands: {
+                commandId,
+                actAs: actors.actAs,
+                readAs: actors.readAs ?? actors.actAs,
+                userId: this.#userId,
+                synchronizerId,
+                commands,
+                disclosedContracts: opts.disclosedContracts,
+            },
+        };
+
+        try {
+            await this.#api.postV2CommandsAsyncSubmit(request);
+        } catch (err: unknown) {
+            throw await this.#throwApiError(err, 'Command submission');
+        }
+
+        return { commandId, completionOffset };
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Completion Waiting / Reconciliation
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Wait for a command to be accepted or rejected.
+     *
+     * Uses bounded exponential backoff to avoid hammering the participant.
+     */
+    async waitForCommand(commandId: string, opts: WaitOptions): Promise<WaitResult> {
+        const { parties, timeoutMs = 30_000, poll = {} } = opts;
+
+        const limit = poll.limit ?? 50;
+        const streamIdleTimeoutMs = poll.streamIdleTimeoutMs ?? 1000;
+        const initialBackoffMs = poll.backoffMs?.initial ?? 100;
+        const maxBackoffMs = poll.backoffMs?.max ?? 5000;
+
+        let beginExclusive = opts.beginExclusive ?? 0;
+        let currentBackoff = initialBackoffMs;
+        const deadline = Date.now() + timeoutMs;
+
+        // Poll the completions stream until we find our commandId or timeout
+        while (Date.now() < deadline) {
+            const request: PostV2CommandsCompletionsRequest = {
+                completionStreamRequest: {
+                    beginExclusive,
+                    parties,
+                    userId: this.#userId,
+                },
+                limit,
+                streamIdleTimeoutMs,
+            };
+
+            const rawResponse = await this.#api.postV2CommandsCompletionsRaw(request);
+            const responseText = await rawResponse.raw.text();
+            const completions = JSON.parse(responseText) as unknown[];
+
+            // Scan each completion for our commandId
+            for (const item of completions) {
+                const normalized = item as Record<string, unknown>;
+                const completionResponse = this.#getField<Record<string, unknown>>(
+                    normalized,
+                    'completionResponse',
+                );
+                if (!completionResponse) continue;
+
+                // Handle offsetCheckpoint responses (no commandId)
+                const offsetCheckpoint = this.#getField<Record<string, unknown>>(
+                    completionResponse,
+                    'offsetCheckpoint',
+                );
+                if (offsetCheckpoint) {
+                    const checkpoint =
+                        this.#getField<Record<string, unknown>>(offsetCheckpoint, 'value') ??
+                        offsetCheckpoint;
+                    const checkpointOffset = this.#getField<number>(checkpoint, 'offset');
+                    if (checkpointOffset !== undefined) {
+                        beginExclusive = Math.max(beginExclusive, checkpointOffset);
+                    }
+                    continue;
+                }
+
+                // Navigate: completionResponse.completion.value
+                const completionWrapper = this.#getField<Record<string, unknown>>(
+                    completionResponse,
+                    'completion',
+                );
+                const completion =
+                    this.#getField<Record<string, unknown>>(completionWrapper, 'value') ??
+                    completionWrapper;
+                if (!completion) continue;
+
+                const offset = this.#getField<number>(completion, 'offset');
+                const completionCommandId = this.#getField<string>(completion, 'commandId');
+
+                // Found our command — check gRPC status to determine accept/reject
+                if (completionCommandId === commandId) {
+                    const status = this.#getField<{
+                        code?: number;
+                        message?: string;
+                        details?: unknown;
+                    }>(completion, 'status');
+
+                    // code === 0 or status undefined means success (gRPC OK)
+                    if (!status || status.code === 0) {
+                        return {
+                            status: 'accepted',
+                            commandId,
+                            updateId: this.#getField<string>(completion, 'updateId') ?? '',
+                            offset: offset ?? 0,
+                        };
+                    } else {
+                        return {
+                            status: 'rejected',
+                            commandId,
+                            offset: offset ?? 0,
+                            error: {
+                                code: status.code,
+                                message: status.message ?? 'Unknown rejection',
+                                details: status.details,
+                            },
+                        };
+                    }
+                }
+
+                // Not our command — advance offset cursor past it
+                if (offset !== undefined) {
+                    beginExclusive = Math.max(beginExclusive, offset);
+                }
+            }
+
+            // Bounded exponential backoff
+            const remainingTime = deadline - Date.now();
+            const sleepTime = Math.min(currentBackoff, remainingTime, maxBackoffMs);
+            if (sleepTime > 0) {
+                await new Promise((resolve) => setTimeout(resolve, sleepTime));
+            }
+            currentBackoff = Math.min(currentBackoff * 2, maxBackoffMs);
+        }
+
+        return { status: 'timeout', commandId, lastCheckedOffset: beginExclusive };
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Disclosed Contracts
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Fetch active contract's created event by ID.
+     * Returns undefined if contract doesn't exist or is archived.
+     */
+    async #fetchActiveContractEvent(
+        contractId: ContractId<unknown>,
+        parties: string[],
+        includeCreatedEventBlob: boolean,
+    ): Promise<CreatedEvent | undefined> {
+        const request: PostV2EventsEventsByContractIdRequest = {
+            getEventsByContractIdRequest: {
+                contractId,
+                eventFormat: {
+                    filtersByParty: this.#buildPartyFilters(parties, includeCreatedEventBlob),
+                    verbose: false,
+                },
+            },
+        };
+
+        const response = await this.#api.postV2EventsEventsByContractId(request);
+
+        // If archived, contract is not active
+        if (response.archived) return undefined;
+
+        return response.created?.createdEvent;
+    }
+
+    /**
+     * Build a disclosure for a contract.
+     *
+     * @param contractId - The contract ID to create disclosure for
+     * @param parties - Parties that have visibility to the contract
+     * @returns DisclosedContract if visible, undefined if not found
+     * @throws CantonProtocolError if contract visible but blob missing (server/config mismatch)
+     */
+    async createDisclosure(
+        contractId: ContractId<unknown>,
+        parties: string[],
+    ): Promise<DisclosedContract | undefined> {
+        const synchronizerId = await this.#ensureSynchronizerId();
+        const created = await this.#fetchActiveContractEvent(contractId, parties, true);
+
+        if (!created) return undefined;
+
+        const validated = this.#validateDisclosureEvent(created, contractId);
+        return {
+            ...validated,
+            synchronizerId,
+        };
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Internal: Active Contract Queries (used by CantonSdk)
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Fetch a single contract by ID.
+     *
+     * @param contractId The contract ID to fetch
+     * @param parties Parties to use for filtering (required for non-admin tokens)
+     */
+    async fetchContractById(
+        contractId: ContractId<unknown>,
+        parties: string[],
+    ): Promise<CreatedEvent | undefined> {
+        return this.#fetchActiveContractEvent(contractId, parties, false);
+    }
+
+    /**
+     * Fetch both the created and archived events for a contract by ID.
+     * Unlike fetchContractById, this preserves archival information.
+     */
+    async fetchEventsByContractId(
+        contractId: string,
+        parties: string[],
+    ): Promise<{ created: CreatedEvent | undefined; archived: ArchivedEvent | undefined }> {
+        const request: PostV2EventsEventsByContractIdRequest = {
+            getEventsByContractIdRequest: {
+                contractId,
+                eventFormat: {
+                    filtersByParty: this.#buildPartyFilters(parties, false),
+                    verbose: false,
+                },
+            },
+        };
+
+        const response = await this.#api.postV2EventsEventsByContractId(request);
+
+        return {
+            created: response.created?.createdEvent,
+            archived: response.archived?.archivedEvent,
+        };
+    }
+
+    /**
+     * Fetch an update (transaction) by its ID.
+     * @param updateId The update ID from a completion
+     * @param parties Parties to use for the query filter
+     * @returns The full update response
+     */
+    async fetchTransactionByUpdateId(
+        updateId: string,
+        parties: string[],
+    ): Promise<CantonTransaction> {
+        const response = await this.#api.postV2UpdatesUpdateByIdRaw({
+            getUpdateByIdRequest: {
+                updateId,
+                updateFormat: this.#buildUpdateFormat(parties),
+            },
+        });
+
+        const updateResponse: CantonUpdateResponse = await response.raw.json();
+        return this.#parseTransactionFromUpdate(
+            updateResponse,
+            `Update ${updateId} is not a transaction`,
+        );
+    }
+
+    /**
+     * Fetch a transaction by its offset.
+     * @param offset - The ledger offset
+     * @param parties - Parties to use for the query filter
+     * @returns The full transaction including recordTime
+     */
+    async fetchTransactionByOffset(offset: number, parties: string[]): Promise<CantonTransaction> {
+        const response = await this.#api.postV2UpdatesUpdateByOffsetRaw({
+            getUpdateByOffsetRequest: {
+                offset,
+                updateFormat: this.#buildUpdateFormat(parties),
+            },
+        });
+
+        const updateResponse: CantonUpdateResponse = await response.raw.json();
+        return this.#parseTransactionFromUpdate(
+            updateResponse,
+            `Update at offset ${offset} is not a transaction`,
+        );
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // External Party / Interactive Submission
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Prepare commands for external party signing.
+     *
+     * Returns a typed PreparedTransaction that preserves the contract type
+     * through the signing flow. After signing, use submitSigned() to submit.
+     *
+     * @typeparam T The contract payload type (phantom type for type safety)
+     *
+     * @example
+     * ```ts
+     * const prepared = await client.prepareForSigning<Oft>({ actAs: [party] }, [cmd]);
+     * const signature = await sign(prepared.preparedTransactionHash);
+     * await client.submitSigned(prepared, [signature]);
+     * ```
+     */
+    async prepareForSigning(
+        actors: SubmitActors,
+        commands: Command[],
+        opts: { disclosedContracts?: DisclosedContract[]; commandId?: string } = {},
+    ): Promise<PreparedTransaction> {
+        const synchronizerId = await this.#ensureSynchronizerId();
+        const commandId = opts.commandId ?? randomUUID();
+
+        const request: PostV2InteractiveSubmissionPrepareRequest = {
+            jsPrepareSubmissionRequest: {
+                userId: this.#userId,
+                commandId,
+                commands,
+                actAs: actors.actAs,
+                readAs: actors.readAs ?? actors.actAs,
+                disclosedContracts: opts.disclosedContracts,
+                synchronizerId,
+                verboseHashing: false,
+                packageIdSelectionPreference: [],
+            },
+        };
+
+        const response = await this.#api.postV2InteractiveSubmissionPrepare(request);
+        const validated = this.#validatePrepareResponse(response);
+
+        return {
+            ...validated,
+            hashingSchemeVersion:
+                validated.hashingSchemeVersion as PreparedTransaction['hashingSchemeVersion'],
+            commandId,
+        };
+    }
+
+    /**
+     * Submit a pre-signed transaction.
+     *
+     * The generic type T flows from prepareForSigning() for type documentation.
+     */
+    async submitSigned(
+        prepared: PreparedTransaction,
+        signatures: ExternalSignature[],
+    ): Promise<SubmitResult> {
+        // Snapshot ledger end so the caller can poll for completion from this point
+        const ledgerEndResponse = await this.#api.getV2StateLedgerEnd();
+        const completionOffset = ledgerEndResponse.offset;
+
+        const request: PostV2InteractiveSubmissionExecuteRequest = {
+            jsExecuteSubmissionRequest: {
+                preparedTransaction: prepared.preparedTransaction,
+                // Map each ExternalSignature into the Canton per-party signature format
+                partySignatures: {
+                    signatures: signatures.map((sig) => ({
+                        party: sig.party,
+                        signatures: [
+                            {
+                                format: sig.format,
+                                signature: sig.signature,
+                                signedBy: sig.signedBy,
+                                signingAlgorithmSpec: sig.signingAlgorithmSpec,
+                            },
+                        ],
+                    })),
+                },
+                deduplicationPeriod: {
+                    deduplicationDuration: {
+                        value: { seconds: 3600, nanos: 0 }, // 1 hour default
+                    },
+                },
+                submissionId: randomUUID(),
+                userId: this.#userId,
+                hashingSchemeVersion: prepared.hashingSchemeVersion,
+            },
+        };
+
+        await this.#api.postV2InteractiveSubmissionExecute(request);
+
+        return { commandId: prepared.commandId, completionOffset };
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Active Contracts Query
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Get the current ledger end offset.
+     */
+    async getLedgerEndOffset(): Promise<number> {
+        const response = await this.#api.getV2StateLedgerEnd();
+        return response.offset;
+    }
+
+    /**
+     * Query active contracts at a given offset with optional template filtering.
+     *
+     * @param party - Party to query as
+     * @param offset - Ledger offset for the snapshot
+     * @param opts.templateIds - Optional template IDs to filter by
+     * @param opts.limit - Maximum number of contracts to return
+     */
+    async queryActiveContracts(
+        party: string,
+        offset: number,
+        opts?: { templateIds?: string[]; limit?: number },
+    ): Promise<JsActiveContract[]> {
+        return this.queryActiveContractsByParties([party], offset, opts?.templateIds ?? [], {
+            limit: opts?.limit,
+        });
+    }
+
+    /**
+     * Query active contracts visible to any of the given parties.
+     *
+     * Single API call with all parties in filtersByParty.
+     *
+     * @param parties - Parties to query as (for visibility)
+     * @param offset - Ledger offset for the snapshot
+     * @param templateIds - Template IDs to filter by
+     * @param opts.limit - Maximum number of contracts to return
+     */
+    async queryActiveContractsByParties(
+        parties: string[],
+        offset: number,
+        templateIds: string[],
+        opts?: { limit?: number },
+    ): Promise<JsActiveContract[]> {
+        const cumulativeFilter = this.#buildCumulativeFilters(templateIds);
+        const filtersByParty = Object.fromEntries(
+            parties.map((party) => [party, { cumulative: cumulativeFilter }]),
+        );
+
+        const rawResponse = await this.#api.postV2StateActiveContractsRaw({
+            getActiveContractsRequest: {
+                filter: { filtersByParty },
+                verbose: true,
+                activeAtOffset: offset,
+            },
+            limit: opts?.limit,
+        });
+
+        // Raw response is an array of streamed entries; extract and deserialize contracts
+        type RawActiveContractsResponse = Array<{
+            contractEntry?: { JsActiveContract?: Record<string, unknown> };
+        }>;
+        const rawJson: RawActiveContractsResponse = await rawResponse.raw.json();
+
+        return rawJson
+            .map((item) => item.contractEntry?.JsActiveContract)
+            .filter((contract): contract is Record<string, unknown> => contract != null)
+            .map((contract) => JsActiveContractFromJSON(contract));
+    }
+
+    /**
+     * Stream transactions from a given offset.
+     *
+     * @param party - Party to query as
+     * @param beginExclusive - Start offset (exclusive)
+     * @param endInclusive - End offset (inclusive)
+     * @param opts.templateIds - Optional template IDs to filter by
+     * @param opts.limit - Maximum number of transactions to return
+     */
+    async getUpdates(
+        party: string,
+        beginExclusive: number,
+        endInclusive: number,
+        opts?: { templateIds?: string[]; limit?: number },
+    ): Promise<CantonUpdate[]> {
+        const rawResponse = await this.#api.postV2UpdatesRaw({
+            getUpdatesRequest: {
+                beginExclusive,
+                endInclusive,
+                filter: {
+                    filtersByParty: {
+                        [party]: { cumulative: this.#buildCumulativeFilters(opts?.templateIds) },
+                    },
+                },
+                verbose: true,
+            },
+            limit: opts?.limit,
+        });
+
+        const updateResponses: CantonUpdateResponse[] = await rawResponse.raw.json();
+
+        return updateResponses.map((response) => response.update);
+    }
+
+    /**
+     * Build cumulative filters for party-based queries.
+     * If templateIds provided, filters by those templates; otherwise uses wildcard.
+     */
+    #buildCumulativeFilters(templateIds?: string[]): CumulativeFilter[] {
+        if (templateIds?.length) {
+            return templateIds.map((templateId) => ({
+                identifierFilter: {
+                    templateFilter: { value: { templateId, includeCreatedEventBlob: false } },
+                },
+            }));
+        }
+        return [
+            { identifierFilter: { wildcardFilter: { value: { includeCreatedEventBlob: false } } } },
+        ];
+    }
+
+    /**
+     * Build the standard update format for fetching transactions.
+     */
+    #buildUpdateFormat(parties: string[]) {
+        return {
+            includeTransactions: {
+                eventFormat: {
+                    filtersByParty: this.#buildPartyFilters(parties, false),
+                    verbose: false,
+                },
+                transactionShape: 'TRANSACTION_SHAPE_LEDGER_EFFECTS' as const,
+            },
+        };
+    }
+
+    /**
+     * Parse an update response and extract the transaction.
+     * The response structure is: { update: { Transaction: { value: CantonTransaction } } }
+     */
+    #parseTransactionFromUpdate(
+        json: CantonUpdateResponse,
+        notFoundMessage: string,
+    ): CantonTransaction {
+        // Update can be a Transaction, Reassignment, TopologyTransaction, or OffsetCheckpoint
+        if (!('Transaction' in json.update)) {
+            throw new CantonProtocolError(notFoundMessage);
+        }
+
+        return json.update.Transaction.value;
+    }
+}