@c7-digital/ledger 0.0.2

package/lib/src/ledger.js

@@ -0,0 +1,849 @@
+/**
+ * High-level Daml Ledger abstraction for Canton's OpenAPI v2 JSON API
+ *
+ * This class provides convenient, Template and Choice-aware methods for common
+ * Daml operations. It applies business logic to filter and transform raw API
+ * responses into the expected Daml types, ensuring results match the requested
+ * Template or Choice specifications.
+ *
+ * Key features:
+ * - Template-typed contract queries and creation
+ * - Choice-typed exercise operations
+ * - Automatic filtering of irrelevant data (non-active contracts, wrong templates)
+ * - Type safety with branded value.proto string types
+ * - Compatibility with @daml/types interfaces
+ *
+ * Use this for most Daml application needs. Use TypedHttpClient directly when
+ * you need access to Canton-specific endpoints or full control over API calls.
+ */
+import { lookupTemplate, } from "@daml/types";
+import { decodeJwt } from "jose";
+import { EventEmitter } from "eventemitter3";
+import { logger } from "./logger.js";
+import { TypedHttpClient } from "./client.js";
+import { WebSocketClient, isTransaction, } from "./websocket.js";
+import { MultiStreamAdapter } from "./multistream.js";
+import { matchesPartiallyQualified } from "./util.js";
+import * as translate from "./translate.js";
+import { createLedgerString, createPartyIdString, createNameString, createUserIdString, } from "./valueTypes.js";
+// Type guard to check if an event is a CreatedEvent
+function isCreateEvent(event) {
+    return "CreatedEvent" in event;
+}
+// This term is so overloaded, lets add a '_' to help differentiate
+function createEvent_(cantonEvent, versionedRegistry) {
+    let t;
+    let packageVersion;
+    // Use custom registry if provided, otherwise fall back to default lookupTemplate
+    if (versionedRegistry) {
+        const result = versionedRegistry(cantonEvent.templateId);
+        if (!result) {
+            throw new Error(`Template not found in registry: ${cantonEvent.templateId}`);
+        }
+        // Check if result is a tuple [Template, version] or just Template
+        if (result.type === "template") {
+            const { template, version } = result;
+            t = template;
+            packageVersion = version;
+        }
+        else {
+            throw new Error(`Expected template in registry not: ${JSON.stringify(result)}`);
+        }
+    }
+    else {
+        t = lookupTemplate(cantonEvent.templateId);
+    }
+    return {
+        type: "create",
+        templateId: cantonEvent.templateId,
+        contractId: cantonEvent.contractId,
+        payload: t.decoder.runWithException(cantonEvent.createArgument),
+        signatories: (cantonEvent.signatories || []),
+        observers: (cantonEvent.observers || []),
+        key: cantonEvent.contractKey
+            ? t.keyDecoder?.runWithException(cantonEvent.contractKey)
+            : undefined,
+        createdEventBlob: cantonEvent.createdEventBlob || "",
+        packageVersion,
+    };
+}
+function archiveEvent_(cantonEvent) {
+    return {
+        type: "archive",
+        templateId: cantonEvent.templateId,
+        contractId: cantonEvent.contractId,
+        witnessParties: (cantonEvent.witnessParties || []),
+        offset: cantonEvent.offset,
+    };
+}
+// It is possible that we query for a given interview that we are interested in,
+// but the underlying contract has multiple interview implementations that we are NOT
+// interested in, and consequently not registered in our versionedRegistry.
+// In this case we return null.
+function interfaceEvent_(cantonEvent, interfaceView, versionedRegistry) {
+    const result = versionedRegistry(interfaceView.interfaceId);
+    if (!result) {
+        logger.warn(`Interface not found in registry: ${interfaceView.interfaceId}`);
+        return null;
+    }
+    if (result.type === "template") {
+        throw new Error(`Expected template in registry not: ${JSON.stringify(result)}`);
+    }
+    const { interface_, version } = result;
+    const i = interface_;
+    const decodedInterfaceView = i.decoder.runWithException(interfaceView.viewValue);
+    const packageVersion = version;
+    return {
+        type: "interface",
+        templateId: cantonEvent.templateId,
+        contractId: cantonEvent.contractId,
+        payload: cantonEvent.createArgument,
+        signatories: (cantonEvent.signatories || []),
+        observers: (cantonEvent.observers || []),
+        key: cantonEvent.contractKey,
+        createdEventBlob: cantonEvent.createdEventBlob || "",
+        interfaceView: decodedInterfaceView,
+        packageVersion,
+    };
+}
+function templateFilter(templateId, includeCreatedEventBlob) {
+    return {
+        TemplateFilter: {
+            value: {
+                templateId: templateId,
+                includeCreatedEventBlob,
+            },
+        },
+    };
+}
+function interfaceFilter(interfaceId, includeCreatedEventBlob) {
+    return {
+        InterfaceFilter: {
+            value: {
+                interfaceId: interfaceId,
+                includeInterfaceView: true,
+                includeCreatedEventBlob,
+            },
+        },
+    };
+}
+// Convenience constructors for commands
+export function createCmd(template, payload) {
+    return {
+        type: 'create',
+        template,
+        payload,
+    };
+}
+export function createAndExerciseCmd(template, payload, choice, argument) {
+    return {
+        type: 'createAndExercise',
+        template,
+        payload,
+        choice,
+        argument,
+    };
+}
+export function exerciseCmd(contractId, choice, argument) {
+    return {
+        type: 'exercise',
+        contractId,
+        choice,
+        argument,
+    };
+}
+function convertCommand(command) {
+    switch (command.type) {
+        case 'create':
+            return {
+                CreateCommand: {
+                    templateId: command.template.templateId,
+                    createArguments: command.payload,
+                }
+            };
+        case 'createAndExercise':
+            return {
+                CreateAndExerciseCommand: {
+                    templateId: command.template.templateId,
+                    createArguments: command.payload,
+                    choice: createNameString(command.choice.choiceName),
+                    choiceArgument: command.argument,
+                }
+            };
+        case 'exercise':
+            return {
+                ExerciseCommand: {
+                    templateId: command.choice.template().templateId,
+                    contractId: createLedgerString(command.contractId),
+                    choice: createNameString(command.choice.choiceName),
+                    choiceArgument: command.argument,
+                }
+            };
+        default:
+            // TypeScript exhaustiveness check
+            const _exhaustive = command;
+            throw new Error(`Unknown command type: ${JSON.stringify(_exhaustive)}`);
+    }
+}
+/**
+ * Internal stream implementation for active contracts
+ */
+class LedgerStream {
+    /**
+     * Creates a new stream for active contracts
+     *
+     * @param template The template to stream contracts for
+     * @param parties The parties to stream contracts for
+     * @param wsClient The WebSocket client to use
+     * @param activeAtOffset Optional offset to start streaming from
+     */
+    constructor(templateIds, parties, wsClient, startOffset, skipAcs = false, includeCreatedEventBlob = true, versionedRegistry) {
+        this.eventEmitter = new EventEmitter();
+        this.state_ = "start";
+        this.parties = parties;
+        this.wsClient = wsClient;
+        this.offset = startOffset;
+        this.skipAcs = skipAcs;
+        this.versionedRegistry = versionedRegistry;
+        let cumulative = templateIds.map(templateId => {
+            return {
+                identifierFilter: templateFilter(templateId, includeCreatedEventBlob),
+            };
+        });
+        this.filtersByParty = this.parties.reduce((acc, party) => {
+            acc[party] = { cumulative };
+            return acc;
+        }, {});
+    }
+    /**
+     * Start the active contracts stream to get existing contracts
+     */
+    startActiveContractsStream() {
+        // Create the request for active contracts
+        const request = {
+            verbose: false,
+            activeAtOffset: this.offset,
+            eventFormat: {
+                filtersByParty: this.filtersByParty,
+                verbose: true,
+            },
+        };
+        logger.debug(`Starting active contracts stream from offset ${this.offset}`);
+        // Start streaming and store the stop function
+        this.stopClient = this.wsClient.streamActiveContracts(request, response => this.handleActiveContractsResponse(response), error => this.handleError(error), (code, reason) => this.handleActiveContractsClose(code, reason));
+    }
+    /**
+     * Handle responses from the active contracts stream
+     */
+    handleActiveContractsResponse(response) {
+        if (response.status === "error") {
+            this.eventEmitter.emit("error", response.error);
+            return;
+        }
+        // Process the successful response
+        const contractEntry = response.data.contractEntry;
+        // Track the offset for continuing with updates stream later
+        // Extract offset from the active contract if available
+        if (contractEntry && "JsActiveContract" in contractEntry) {
+            const activeContract = contractEntry.JsActiveContract;
+            // TODO, do we have to do this?
+            if (activeContract.createdEvent.offset > this.offset) {
+                logger.warn(`While receiving ACS, updating offset from ${this.offset} to ${activeContract.createdEvent.offset}`);
+                this.offset = activeContract.createdEvent.offset;
+            }
+            this.eventEmitter.emit("create", createEvent_(activeContract.createdEvent, this.versionedRegistry));
+        }
+    }
+    /**
+     * Handle close event from active contracts stream
+     * This is the signal to transition to the updates stream
+     */
+    handleActiveContractsClose(code, reason) {
+        logger.debug(`Active contracts stream closed: ${code} ${reason}`);
+        this.stopClient?.();
+        this.stopClient = undefined;
+        if (this.state_ === "init") {
+            this.state_ = "live";
+            this.eventEmitter.emit("state", "live");
+            this.startUpdatesStream();
+        }
+        else {
+            const closeEvent = { code, reason };
+            this.eventEmitter.emit("close", closeEvent);
+        }
+    }
+    /**
+     * Start streaming updates after active contracts have been loaded
+     */
+    startUpdatesStream() {
+        // Create the request for updates stream
+        const request = {
+            beginExclusive: this.offset,
+            verbose: false,
+            updateFormat: {
+                includeTransactions: {
+                    eventFormat: {
+                        filtersByParty: this.filtersByParty,
+                        verbose: true,
+                    },
+                    transactionShape: "TRANSACTION_SHAPE_ACS_DELTA",
+                },
+            },
+        };
+        logger.debug(`Starting updates stream from offset ${this.offset}`);
+        // Start streaming updates and store the stop function
+        this.stopClient = this.wsClient.streamUpdates(request, response => this.handleUpdatesResponse(response), error => this.handleError(error), (code, reason) => this.handleUpdatesClose(code, reason));
+    }
+    /**
+     * Handle responses from the updates stream
+     */
+    handleUpdatesResponse(response) {
+        if (response.status === "error") {
+            this.eventEmitter.emit("error", response.error);
+            return;
+        }
+        const update = response.data.update;
+        if (isTransaction(update)) {
+            const jsTransaction = update.Transaction.value;
+            for (const event of jsTransaction.events || []) {
+                if ("CreatedEvent" in event) {
+                    this.offset = Math.max(this.offset, event.CreatedEvent.offset);
+                    this.eventEmitter.emit("create", createEvent_(event.CreatedEvent, this.versionedRegistry));
+                }
+                else if ("ArchivedEvent" in event) {
+                    this.offset = Math.max(this.offset, event.ArchivedEvent.offset);
+                    this.eventEmitter.emit("archive", archiveEvent_(event.ArchivedEvent));
+                }
+                else {
+                    logger.warn(`Unexpected event type in transaction stream: ${JSON.stringify(event)}`);
+                }
+            }
+        }
+        else {
+            logger.debug(`Ignoring update of type ${JSON.stringify(update)}`);
+        }
+    }
+    /**
+     * Handle close event from updates stream
+     */
+    handleUpdatesClose(code, reason) {
+        logger.debug(`Updates stream closed: ${code} ${reason}`);
+        this.stopClient?.();
+        this.stopClient = undefined;
+        // Emit close event
+        const closeEvent = { code, reason };
+        this.eventEmitter.emit("close", closeEvent);
+        // Auto-reconnect on abnormal close (1006) if stream is still active
+        if (code === 1006 && this.state_ === "live") {
+            logger.log(`WebSocket closed abnormally (1006), reconnecting in 3 seconds...`);
+            setTimeout(() => {
+                if (this.state_ === "live") {
+                    // Double-check we're still active
+                    logger.log(`Attempting to reconnect stream...`);
+                    this.startUpdatesStream();
+                }
+            }, 3000);
+        }
+    }
+    // This is a websocket error, not a Canton error
+    handleError(error) {
+        logger.error("Stream error:", error);
+        this.eventEmitter.emit("error", {
+            code: "STREAM_ERROR",
+            cause: error.message,
+            context: {},
+            errorCategory: 0,
+        });
+    }
+    // Implementation
+    on(type, listener) {
+        this.eventEmitter.on(type, listener);
+    }
+    // Implementation
+    off(type, listener) {
+        this.eventEmitter.off(type, listener);
+    }
+    /**
+     * Start streaming contracts
+     * First loads active contracts, then transitions to streaming updates
+     */
+    start() {
+        if (this.state_ !== "start") {
+            logger.warn(`Cannot start stream in state: ${this.state_}`);
+            return;
+        }
+        if (this.skipAcs) {
+            this.state_ = "live";
+            this.eventEmitter.emit("state", "live");
+            this.startUpdatesStream();
+        }
+        else {
+            this.state_ = "init";
+            this.eventEmitter.emit("state", "init");
+            this.startActiveContractsStream();
+        }
+    }
+    state() {
+        return this.state_;
+    }
+    /**
+     * Close the stream and clean up resources
+     */
+    close() {
+        // Set state to stop to prevent transitions
+        this.state_ = "stop";
+        this.eventEmitter.emit("state", "stop");
+        if (this.stopClient) {
+            this.stopClient();
+            this.stopClient = undefined;
+        }
+        // Clean up event listeners
+        this.eventEmitter.removeAllListeners();
+    }
+}
+/**
+ * Meant to be a simple replacement for Ledger from @daml/ledger
+ */
+export class Ledger {
+    constructor(options) {
+        this.tokenUserInfo = null;
+        this.httpBaseUrl = options.httpBaseUrl;
+        const payload = decodeJwt(options.token);
+        logger.debug(`Token payload: ${JSON.stringify(payload)}`);
+        if (payload.sub === undefined) {
+            throw new Error(`Token payload missing 'sub' field`);
+        }
+        this.tokenUserId = payload.sub;
+        this.client = new TypedHttpClient({
+            token: options.token,
+            baseUrl: this.httpBaseUrl,
+            validation: options.validation,
+            openApiSchemaPath: options.openApiSchemaPath,
+        });
+        this.options = options;
+    }
+    generateCommandId() {
+        return createLedgerString(`cmd-${Date.now()}-${Math.random().toString(36).substring(2, 13)}`);
+    }
+    async resolveOffset(offset) {
+        logger.log(`Resolving offset: ${offset}`);
+        if (typeof offset === "number") {
+            return offset;
+        }
+        if (offset === "start") {
+            return 0; // Ledger begin
+        }
+        if (offset === "end") {
+            const result = await this.getLedgerEnd();
+            return result;
+        }
+        throw new Error(`Invalid offset: ${offset}`);
+    }
+    async getLedgerEnd() {
+        // If there's already a request in flight, return that promise
+        if (this.ledgerEndPromise) {
+            return this.ledgerEndPromise;
+        }
+        // Check cache (valid for 1 second to avoid excessive API calls)
+        const now = Date.now();
+        if (this.ledgerEndCache && now - this.ledgerEndCache.timestamp < 1000) {
+            return this.ledgerEndCache.offset;
+        }
+        // Create new promise for ledger end request
+        this.ledgerEndPromise = this.client.getLedgerEnd().then(endResponse => endResponse.offset);
+        try {
+            const offset = await this.ledgerEndPromise;
+            // Cache the result
+            this.ledgerEndCache = { offset, timestamp: now };
+            return offset;
+        }
+        finally {
+            // Clear the promise so next request can make a new one if needed
+            this.ledgerEndPromise = undefined;
+        }
+    }
+    getTokenUserId() {
+        return this.tokenUserId;
+    }
+    async getTokenUserInfo() {
+        if (this.tokenUserInfo) {
+            return this.tokenUserInfo;
+        }
+        else {
+            this.tokenUserInfo = await this.getUserInfo(this.tokenUserId);
+            return this.tokenUserInfo;
+        }
+    }
+    async getTokenActAsParties() {
+        const userInfo = await this.getTokenUserInfo();
+        return (userInfo?.rights.filter(right => right.type === "canActAs").map(right => right.party) || []);
+    }
+    /**
+     * Query for the Active Contract Set of a specific template.
+     * @param template a Template instance as generated by the codegen
+     * @param atOffset Whether we want to get historical or just the current
+     *  state, default.
+     * @param includeCreatedEventBlob
+     * @param verbose
+     * @param readAsParties
+     * @returns
+     */
+    async query(template, atOffset = "end", includeCreatedEventBlob = false, verbose = false, readAsParties) {
+        const activeAtOffset = await this.resolveOffset(atOffset);
+        const readAsParties_ = readAsParties || (await this.getTokenActAsParties());
+        let filtersByParty = readAsParties_.reduce((acc, key) => {
+            acc[key] = {
+                cumulative: [
+                    {
+                        identifierFilter: templateFilter(template.templateId, includeCreatedEventBlob),
+                    },
+                ],
+            };
+            return acc;
+        }, {});
+        const queryRequest = {
+            verbose: false, // To be deprecated do not rely
+            activeAtOffset,
+            eventFormat: {
+                filtersByParty,
+                verbose,
+            },
+        };
+        const response = await this.client.queryActiveContracts(queryRequest);
+        // Convert the response to our CreateEvent format
+        return response.reduce((acc, item) => {
+            // Skip non-active contract entries
+            if (!("JsActiveContract" in item.contractEntry)) {
+                logger.debug(`Skipping non-active contract entry: ${JSON.stringify(item.contractEntry)}`);
+                return acc;
+            }
+            const contractEntry = item.contractEntry;
+            const createEvent = contractEntry.JsActiveContract.createdEvent;
+            // Verify we got the correct template
+            if (!matchesPartiallyQualified(createEvent.templateId, template.templateId)) {
+                logger.warn(`Template ID mismatch: expected ${template.templateId}, got ${createEvent.templateId}`);
+                return acc; // Skip contracts with mismatched template IDs
+            }
+            acc.push(createEvent_(createEvent, this.options.versionedRegistry));
+            return acc;
+        }, []);
+    }
+    /**
+     * Query for instances of a given interface.
+     * @param interface_
+     * @param atOffset
+     * @param includeCreatedEventBlob
+     * @param verbose
+     * @param readAsParties
+     * @returns
+     */
+    async queryInterface(interface_, atOffset = "end", includeCreatedEventBlob = false, verbose = false, readAsParties) {
+        if (this.options.versionedRegistry === undefined) {
+            throw new Error("Versioned registry is required for interface queries.");
+        }
+        const versionedRegistry = this.options.versionedRegistry;
+        const activeAtOffset = await this.resolveOffset(atOffset);
+        const readAsParties_ = readAsParties || (await this.getTokenActAsParties());
+        let filtersByParty = readAsParties_.reduce((acc, key) => {
+            acc[key] = {
+                cumulative: [
+                    {
+                        identifierFilter: interfaceFilter(interface_.templateId, includeCreatedEventBlob),
+                    },
+                ],
+            };
+            return acc;
+        }, {});
+        const queryRequest = {
+            verbose: false, // To be deprecated do not rely
+            activeAtOffset,
+            eventFormat: {
+                filtersByParty,
+                verbose,
+            },
+        };
+        const response = await this.client.queryActiveContracts(queryRequest);
+        // Convert the response to our CreateEvent format
+        return response.reduce((acc, item) => {
+            // Skip non-active contract entries
+            if (!("JsActiveContract" in item.contractEntry)) {
+                logger.debug(`Skipping non-active contract entry: ${JSON.stringify(item.contractEntry)}`);
+                return acc;
+            }
+            const contractEntry = item.contractEntry;
+            const createEvent = contractEntry.JsActiveContract.createdEvent;
+            for (const interfaceView of createEvent.interfaceViews ?? []) {
+                if (matchesPartiallyQualified(interfaceView.interfaceId, interface_.templateId)) {
+                    const interfaceEvent = interfaceEvent_(createEvent, interfaceView, versionedRegistry);
+                    if (interfaceEvent !== null) {
+                        acc.push(interfaceEvent);
+                    }
+                }
+                else {
+                    logger.debug(`Ignoring interface ${interfaceView.interfaceId} as it does not match ${interface_.templateId}.`);
+                }
+            }
+            return acc;
+        }, []);
+    }
+    /**
+     * Create a template
+     * @param template
+     * @param payload
+     * @param actAs
+     * @returns
+     */
+    async create(template, payload, actAs) {
+        const createCommand = {
+            templateId: template.templateId,
+            createArguments: payload,
+        };
+        const actAs_ = actAs || (await this.getTokenActAsParties());
+        const commands = {
+            commands: [{ CreateCommand: createCommand }],
+            commandId: this.generateCommandId(),
+            actAs: actAs_.map(party => createPartyIdString(party)),
+            userId: createUserIdString(this.tokenUserId),
+        };
+        const request = { commands };
+        const response = await this.client.submitAndWaitForTransaction(request);
+        const transaction = response.transaction;
+        logger.log(`Create Transaction: ${JSON.stringify(transaction)}`);
+        const createdEvents = (transaction.events || []).reduce((acc, event) => {
+            logger.debug(`Checking event: ${JSON.stringify(event)}`);
+            if (isCreateEvent(event)) {
+                const matchesTemplate = matchesPartiallyQualified(event.CreatedEvent.templateId, template.templateId);
+                if (matchesTemplate) {
+                    logger.debug(`Event matches template, adding to results`);
+                    acc.push(createEvent_(event.CreatedEvent, this.options.versionedRegistry));
+                }
+                else {
+                    logger.debug(`Event templateId: ${event.CreatedEvent.templateId}, ` +
+                        `does not match requested templateId: ${template.templateId}`);
+                }
+            }
+            else {
+                logger.debug(`Ignoring non create event in transaction: ${JSON.stringify(event)}`);
+            }
+            return acc;
+        }, []);
+        if (createdEvents.length === 0) {
+            throw new Error(`No created event found for template ${template.templateId}`);
+        }
+        else if (createdEvents.length > 1) {
+            throw new Error(`Multiple create ${JSON.stringify(createdEvents)} ` +
+                `events found for template ${template.templateId}`);
+        }
+        // We've already checked that createdEvents.length > 0, so this is safe
+        // Use non-null assertion to tell TypeScript this can't be undefined
+        return createdEvents[0];
+    }
+    /**
+     * Exercise a choice of a given contract
+     * @param choice
+     * @param contractId
+     * @param argument
+     * @param actAs
+     * @returns
+     */
+    async exercise(choice, contractId, argument, actAs) {
+        // Extract actAs from meta or use a default
+        const exerciseCommand = {
+            templateId: choice.template().templateId,
+            contractId: createLedgerString(contractId.toString()),
+            choice: createNameString(choice.choiceName),
+            choiceArgument: argument,
+        };
+        const actAs_ = actAs || (await this.getTokenActAsParties());
+        const commands = {
+            commands: [{ ExerciseCommand: exerciseCommand }],
+            commandId: this.generateCommandId(),
+            actAs: actAs_.map(party => createPartyIdString(party)),
+            // Ends up being not optional
+            userId: createUserIdString(this.tokenUserId),
+        };
+        const request = { commands };
+        const response = await this.client.submitAndWaitForTransaction(request);
+        const transaction = response.transaction;
+        const events = [];
+        // TODO: Convert this to the other transaction format to capture the
+        // exercise result and the resulting events.
+        for (const event of transaction.events || []) {
+            logger.log(`Processing exercise resulting event: ${JSON.stringify(event)}`);
+            if ("CreatedEvent" in event) {
+                // Convert to our Event format
+                events.push(createEvent_(event.CreatedEvent, this.options.versionedRegistry));
+            }
+            else if ("ArchivedEvent" in event) {
+                // Convert to our Event format
+                events.push(archiveEvent_(event.ArchivedEvent));
+            }
+            else {
+                // Since we are using ACS_DELTA we can ignore ExercisedEvent
+                throw new Error(`Unexpected event type: ${JSON.stringify(event)}`);
+            }
+        }
+        return events;
+    }
+    /**
+     * `submit` allows combining multiple commands into a single Canton
+     * transaction. Similar to `create` and `exercise` one can use `createCmd`
+     * and `exerciseCmd` to create commands, that are then passed to `submit`.
+     *
+     * @param commands
+     * @param actAs Defaults to the actAs parties of the user in the token.
+     * @returns Stream of events resulting from the submitted commands.
+     */
+    async submit(commands, actAs) {
+        const jsCommands = commands.map((command) => convertCommand(command));
+        // Extract actAs from meta or use a default
+        const actAs_ = actAs || (await this.getTokenActAsParties());
+        const requestCommands = {
+            commands: jsCommands,
+            commandId: this.generateCommandId(),
+            actAs: actAs_.map(party => createPartyIdString(party)),
+            // Ends up being not optional
+            userId: createUserIdString(this.tokenUserId),
+        };
+        const request = { commands: requestCommands };
+        const response = await this.client.submitAndWaitForTransaction(request);
+        const transaction = response.transaction;
+        const events = [];
+        for (const event of transaction.events || []) {
+            logger.log(`Processing exercise resulting event: ${JSON.stringify(event)}`);
+            if ("CreatedEvent" in event) {
+                // Convert to our Event format
+                events.push(createEvent_(event.CreatedEvent, this.options.versionedRegistry));
+            }
+            else if ("ArchivedEvent" in event) {
+                // Convert to our Event format
+                events.push(archiveEvent_(event.ArchivedEvent));
+            }
+            else {
+                // Since we are using ACS_DELTA we can ignore ExercisedEvent
+                throw new Error(`Unexpected event type: ${JSON.stringify(event)}`);
+            }
+        }
+        return events;
+    }
+    initClient() {
+        const wsBaseUrl = this.options.wsBaseUrl ||
+            this.httpBaseUrl.replace(/^https?:/, this.httpBaseUrl.startsWith("https:") ? "wss:" : "ws:");
+        return new WebSocketClient({
+            token: this.options.token,
+            wsBaseUrl: wsBaseUrl,
+            validation: this.options.validation,
+            asyncApiSchemaPath: this.options.asyncApiSchemaPath,
+        });
+    }
+    /**
+     * Stream functionality using WebSockets
+     *
+     * @param template The template to stream
+     * @param readAsParties Array of parties to stream for, if not specified default to
+     *          the actAs parties of the user in the token.
+     * @param offset Optional offset to start streaming from
+     * @param skipAcs Whether to skip archived contracts
+     * @param includeCreatedEventBlob Whether to include created event blobs
+     * @returns A stream of events for the specified template
+     */
+    async streamQuery(template, offset = "end", skipAcs = false, includeCreatedEventBlob = false, readAsParties) {
+        const activeAtOffset = await this.resolveOffset(offset);
+        const parties_ = readAsParties || (await this.getTokenActAsParties());
+        return new LedgerStream([template.templateId], parties_, this.initClient(), activeAtOffset, skipAcs, includeCreatedEventBlob, this.options.versionedRegistry);
+    }
+    /**
+     * Create a type-safe MultiStream for working with multiple templates
+     *
+     * @example
+     * ```typescript
+     * // Define your template mapping
+     * type MyTemplates = {
+     *   [UserTemplate.templateId]: { contractType: UserContract, keyType: UserKey },
+     *   [AccountTemplate.templateId]: { contractType: AccountContract, keyType: AccountKey }
+     * };
+     *
+     * // Create a type-safe multi-stream
+     * const stream = await ledger.createMultiStream<MyTemplates>(
+     *   [UserTemplate, AccountTemplate],
+     *   [party]
+     * );
+     *
+     * // Use template-specific handlers with proper typing
+     * stream.onCreate(UserTemplate.templateId, (event) => {
+     *   // event.payload is typed as UserContract
+     *   logger.log("User created:", event.payload.username);
+     * });
+     *
+     * stream.onCreate(AccountTemplate.templateId, (event) => {
+     *   // event.payload is typed as AccountContract
+     *   logger.log("Account created:", event.payload.accountNumber);
+     * });
+     *
+     * stream.start();
+     * ```
+     *
+     * @param templates Array of templates to stream
+     * @param offset Optional offset to start streaming from
+     * @param includeCreatedEventBlob Whether to include created event blobs
+     * @param readAsParties Array of parties to stream for, if not specified default to
+     *          the actAs parties of the user in the token.
+     * @returns A type-safe MultiStream for working with multiple templates
+     */
+    async createMultiStream(tm, offset = "end", skipAcs = false, includeCreatedEventBlob = false, readAsParties) {
+        const activeAtOffset = await this.resolveOffset(offset);
+        const templateIds = Object.keys(tm);
+        const parties_ = readAsParties || (await this.getTokenActAsParties());
+        const stream = new LedgerStream(templateIds, parties_, this.initClient(), activeAtOffset, skipAcs, includeCreatedEventBlob, this.options.versionedRegistry);
+        return new MultiStreamAdapter(stream);
+    }
+    // User information
+    async getUserInfo(userId) {
+        const response = await this.client.getUserInfo(userId);
+        if (!response.user) {
+            logger.warn(`User '${userId}' not found in v2/users/${userId}.`);
+            return null;
+        }
+        else {
+            let userRights = await this.client.getUserRights(userId);
+            return {
+                userId: createUserIdString(response.user.id),
+                primaryParty: response.user.primaryParty,
+                rights: userRights.rights?.map(translate.userRights) || [],
+            };
+        }
+    }
+    // Party management
+    async getParties() {
+        const response = await this.client.getParties();
+        return (response.partyDetails || []).map((party) => ({
+            party: party.party, // Keep as Party type for compatibility
+            displayName: party.localMetadata?.annotations?.displayName,
+            isLocal: party.isLocal || false,
+        }));
+    }
+    async allocateParty(request) {
+        const allocateRequest = {
+            partyIdHint: request.partyIdHint
+                ? createPartyIdString(request.partyIdHint)
+                : createPartyIdString(""),
+            identityProviderId: "default", // Use default identity provider
+            synchronizerId: "",
+            userId: "", // Do not assign to user.
+            ...(request.displayName && {
+                localMetadata: {
+                    resourceVersion: "",
+                    annotations: { displayName: request.displayName },
+                },
+            }),
+        };
+        const response = await this.client.allocateParty(allocateRequest);
+        return {
+            partyDetails: {
+                party: (response.partyDetails?.party || ""),
+                displayName: response.partyDetails?.localMetadata?.annotations?.displayName,
+                isLocal: response.partyDetails?.isLocal || false,
+            },
+        };
+    }
+}