@distrohelena/canton-typescript-sdk 0.1.35 → 0.1.36

package/README.md

@@ -132,30 +132,63 @@ npm run example:topology:party-hosting
 
 ### Workflow examples
 
-The four workflow examples are standalone proofs, not a sequence: each uploads
-or verifies the fixture DAR, resolves a party, reads the participant status,
-and creates its own run-scoped data. First make a Canton participant available
-and verify the source with `npm run examples:check`; the default endpoints and
-authentication environment variables are documented below. Run any example
-independently:
+The seven workflow examples are standalone proofs, not a sequence:
+each uploads or verifies the fixture DAR, resolves a party, reads the
+participant status, and creates its own run-scoped data. First make a Canton
+participant available and verify the source with `npm run examples:check`; the
+default endpoints and authentication environment variables are documented below.
+The pruning preflight is a separate read-only operator check and does none of
+those setup or mutation steps. Run any example independently:
 
 ```bash
 npm run example:workflow:atomic
 npm run example:workflow:retry
 npm run example:workflow:resume
 npm run example:workflow:stale-contract
+npm run example:workflow:command-completion
+npm run example:workflow:contract-lifecycle-audit
+npm run example:workflow:update-lookup-reconciliation
+npm run example:workflow:pruning-preflight
 ```
 
-They intentionally leave durable state behind. A missing `SDK_EXAMPLE_PARTY`
+Those seven established stateful workflows intentionally leave durable state behind. A missing `SDK_EXAMPLE_PARTY`
 causes fallback party allocation, which creates durable topology state; every
-workflow also creates durable contracts. Set `SDK_EXAMPLE_PARTY` to an existing
-party to rerun all four against that party and avoid fallback allocation. The
-fixture DAR remains installed after a run.
-
-Each program prints its actor plus the full participant version returned by the
+one also creates durable contracts. Set `SDK_EXAMPLE_PARTY` to an existing
+party to rerun the established workflows against that party and avoid fallback
+allocation. The fixture DAR remains installed after a run.
+
+The completion-correlation workflow (`npm run example:workflow:command-completion`)
+is a standalone successful proof that creates durable Message state. It uses the
+same normal `SDK_EXAMPLE_*` configuration: `SDK_EXAMPLE_LEDGER_ENDPOINT`,
+`SDK_EXAMPLE_LEDGER_ADMIN_ENDPOINT`, `SDK_EXAMPLE_PARTICIPANT_ADMIN_ENDPOINT`,
+`SDK_EXAMPLE_BEARER_TOKEN`, `SDK_EXAMPLE_LEDGER_BEARER_TOKEN`,
+`SDK_EXAMPLE_LEDGER_ADMIN_BEARER_TOKEN`,
+`SDK_EXAMPLE_PARTICIPANT_ADMIN_BEARER_TOKEN`,
+`SDK_EXAMPLE_TLS_ROOT_CERTIFICATE`, `SDK_EXAMPLE_PARTY`,
+`SDK_EXAMPLE_PARTY_PREFIX`, and `SDK_EXAMPLE_TIMEOUT_MS`.
+`SDK_EXAMPLE_USER_ID` is mandatory: absent or blank input is rejected, while
+every nonblank value is preserved untrimmed and exactly submitted and exactly
+matched in the completion. With bearer authentication, the configured declared
+user must equal the token's Ledger API user/subject; the example does not inspect
+the token. It keeps the ledger end as its saved exclusive offset and begins the
+first stream read before submission.
+No public wait-for-command-completion helper or API is introduced; the
+correlation helper remains example-only.
+The completion-correlation example asserts successful correlation only; it does
+not assert rejected-command correlation. On both participant observations, the
+stream-first rejected-command probes observed no exact completion before their
+bounded stream transport errors.
+
+The contract-lifecycle audit workflow (`npm run example:workflow:contract-lifecycle-audit`) is a standalone gRPC-only proof. It uses the normal `SDK_EXAMPLE_*` endpoint, authentication, party, and timeout configuration: `SDK_EXAMPLE_LEDGER_ENDPOINT`, `SDK_EXAMPLE_LEDGER_ADMIN_ENDPOINT`, `SDK_EXAMPLE_PARTICIPANT_ADMIN_ENDPOINT`, `SDK_EXAMPLE_BEARER_TOKEN`, `SDK_EXAMPLE_LEDGER_BEARER_TOKEN`, `SDK_EXAMPLE_LEDGER_ADMIN_BEARER_TOKEN`, `SDK_EXAMPLE_PARTICIPANT_ADMIN_BEARER_TOKEN`, `SDK_EXAMPLE_PARTY`, `SDK_EXAMPLE_PARTY_PREFIX`, and `SDK_EXAMPLE_TIMEOUT_MS`. An explicit `SDK_EXAMPLE_PARTY` is reused; otherwise fallback allocation creates durable topology. The fixture upload leaves a durable DAR, and the workflow leaves durable contracts. It uses the alpha ContractService to prove the original active Message before replacement and the replacement active Message afterward, then uses EventQuery for the original contract's create/archive history. It makes no post-archive ContractService claim for the original.
+
+The update-lookup reconciliation workflow (`npm run example:workflow:update-lookup-reconciliation`) is a standalone gRPC-only proof that observes one exact self-party Message transaction from `UpdateService.GetUpdates`, then immediately reconciles it through `getUpdateById` and `getUpdateByOffset`. It uses the normal `SDK_EXAMPLE_*` endpoint, authentication, party, and timeout configuration, including `SDK_EXAMPLE_PARTY` and `SDK_EXAMPLE_TIMEOUT_MS`; first run `npm run examples:check` and make an authenticated participant available. An explicit party is reused, while fallback allocation creates durable topology; the fixture upload leaves a durable DAR and the workflow leaves durable contracts. The same unchanged implementation is tested against authenticated Participant 3.5.7 and the isolated Participant 3.5.8 sidecar, in default-party and explicit-party modes.
+
+The pruning-preflight workflow (`npm run example:workflow:pruning-preflight`) is a standalone gRPC-only, read-only operator check. It requires `SDK_EXAMPLE_OFFSET` to be a canonical positive decimal integer and uses the normal endpoint, authentication, and timeout variables: `SDK_EXAMPLE_LEDGER_ENDPOINT`, `SDK_EXAMPLE_LEDGER_ADMIN_ENDPOINT`, `SDK_EXAMPLE_PARTICIPANT_ADMIN_ENDPOINT`, `SDK_EXAMPLE_BEARER_TOKEN`, `SDK_EXAMPLE_LEDGER_BEARER_TOKEN`, `SDK_EXAMPLE_LEDGER_ADMIN_BEARER_TOKEN`, `SDK_EXAMPLE_PARTICIPANT_ADMIN_BEARER_TOKEN`, and `SDK_EXAMPLE_TIMEOUT_MS`. The participant-admin credential is required for the schedule and safe-pruning context reads. Its safe-pruning context request sends the saved ledger end and a validated current timestamp encoded in `beforeOrAt`; it leaves commitment-state absent. It does not mutate the participant or create durable state: no party, DAR, command, update query, schedule change, or pruning request is made. The later participant watermark classifies the supplied offset as `alreadyPruned`, `beyondLedgerEnd`, or `notObservedPruned`; all-divulged watermarks and schedule/safe-pruning context are reported separately and do not alter that result. `notObservedPruned` is not proven queryable, because pruning can race after the later observation and other query preconditions can still fail. The unchanged implementation is supported on Participant 3.5.7 and the isolated Participant 3.5.8 sidecar.
+
+Each of the seven established stateful workflows prints its actor plus the full participant version returned by the
 authenticated status API, its parsed release core, and its selected path:
 `Participant version:`, `Release core:`, and `Compatibility path:`. The current
-implementation uses one common-code path for release cores 3.5.7 and 3.5.8. It
+stateful-workflow implementation uses one common-code path for release cores 3.5.7 and 3.5.8. It
 adds a version-specific behavioral difference only after live evidence proves
 one; it does not infer compatibility from a container tag or endpoint.
 
@@ -179,15 +212,15 @@ request and is not a retry proof. The resume example treats the saved offset as
 exclusive, so its resumed stream must observe only updates after the saved
 ledger end.
 
-The workflow source and unit contracts were developed and live-tested against
-authenticated Participant 3.5.7 and the isolated Participant 3.5.8. Both
-final-tree matrices selected the same unchanged implementation and common
+The seven established stateful workflow sources and unit contracts were developed
+and live-tested against authenticated Participant 3.5.7 and the isolated
+Participant 3.5.8. Both final-tree matrices selected the same unchanged implementation and common
 compatibility path. The normalized outcome comparison is identical: atomic
 reports `invalidChoice` before its replacement proof, retry reports
 `duplicateCommand` with one active contract, resume reports `idle-timeout` and
 a post-offset update, and stale-contract reports `staleContract`.
 
-The best multi-version path reads the authenticated full version, parses its
+For those seven established stateful workflows, the best multi-version path reads the authenticated full version, parses its
 release core, and uses data-only structured compatibility for observed
 outcomes. A behavioral difference is introduced only after live proof; it is
 never inferred from a container tag, endpoint, or prose error message. For the
@@ -555,7 +588,11 @@ const contracts = await client.stateService.getActiveContractsPageAsync(
 );
 ```
 
-`stateService.getActiveContractsPageAsync(...)` accepts the generated Ledger API request on gRPC, including its `eventFormat`, `activeAtOffset`, `maxPageSize`, and `pageToken` fields. Build party, template, and interface filters in `eventFormat`. JSON does not implement this paginated RPC; use `getActiveContractsAsync(...)` for JSON streaming reads.
+`stateService.getActiveContractsPageAsync(...)` is gRPC-only and accepts the generated Ledger API request, including its `eventFormat`, `activeAtOffset`, `maxPageSize`, and `pageToken` fields. Build party, template, and interface filters in `eventFormat`.
+
+`stateService.getActiveContractsPagesAsync(...)` is the gRPC-only lazy, raw, bounded traversal API. It starts from the same generated request and yields raw `GetActiveContractsPageResponse` values one page at a time. The caller selects the shared `OperationDeadline`, maximum pages, and maximum contracts with `ActiveContractsTraversalOptions`; there is no collect-all wrapper. Transport errors from dispatched RPCs propagate unchanged. Traversal safety, invariant, and bound failures use `ActiveContractsTraversalError` codes, such as an inconsistent offset, repeated page token, or exceeded bound.
+
+JSON does not implement either paginated gRPC API. Its existing `stateService.getActiveContractsAsync(...)` behavior remains the distinct JSON streaming read.
 
 For interface views, do not use `contractService.getContractAsync(...)`. That contract lookup surface cannot return interface views; use `stateService` or `updateService` instead.
 
@@ -703,11 +740,12 @@ unsupported query features reject with `QueryCapabilityError`.
 - `commandService.submitAndWaitAsync(...)`: `json`, `grpc`
 - `commandSubmissionService.submitAsync(...)`: reserved, currently unsupported
 - `stateService.getActiveContractsPageAsync(...)`: `grpc` only
-- `stateService.getActiveContractsAsync(...)`: `json` only
+- `stateService.getActiveContractsPagesAsync(...)`: `grpc` only, lazy raw bounded traversal
+- `stateService.getActiveContractsAsync(...)`: `json` only, existing distinct streaming read
 - `updateService.getUpdatesAsync(...)`: `grpc` only
-- `commandCompletionService`: placeholder, no methods yet
-- `eventQueryService`: placeholder, no methods yet
-- `contractService`: placeholder, no methods yet
+- `commandCompletionService.getCompletionsAsync(...)`: `grpc` only, existing streaming API
+- `eventQueryService.getEventsByContractIdAsync(...)`: `grpc` only; JSON rejects this request
+- `contractService.getContractAsync(...)`: `grpc` only; JSON rejects this request
 
 - Ledger Admin endpoint:
 - `partyManagementService.allocatePartyAsync(...)`: `json`, `grpc`

package/dist/cjs/services/state/state-service-client.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StateServiceClient = void 0;
+const active_contracts_traversal_error_js_1 = require("../../core/errors/active-contracts-traversal-error.js");
+const validation_error_js_1 = require("../../core/errors/validation-error.js");
 class StateServiceClient {
     transport;
     constructor(transport) {
@@ -11,6 +13,10 @@ class StateServiceClient {
     getActiveContractsPageAsync(request, options) {
         return this.transport.getActiveContractsPageAsync(request, options);
     }
+    /** Reads active-contract pages lazily. Supported on gRPC; JSON rejects it. */
+    getActiveContractsPagesAsync(request, options) {
+        return this.getActiveContractsPagesLazy(request, options);
+    }
     /** Reads active contracts as a stream. JSON-backed; gRPC currently rejects it. */
     getActiveContractsAsync(request, observer, options) {
         return this.transport.getActiveContractsAsync(request, observer, options);
@@ -27,5 +33,55 @@ class StateServiceClient {
     getLatestPrunedOffsetsAsync(request, options) {
         return this.transport.getLatestPrunedOffsetsAsync(request, options);
     }
+    async *getActiveContractsPagesLazy(request, options) {
+        if (request.pageToken && request.pageToken.length > 0) {
+            throw new validation_error_js_1.ValidationError("active contracts traversal must not start with a page token");
+        }
+        let pageRequest = request;
+        let pagesRead = 0;
+        let contractsRead = 0;
+        let activeAtOffset;
+        const observedPageTokens = new Set();
+        while (true) {
+            if (pagesRead >= options.maxPages) {
+                throw new active_contracts_traversal_error_js_1.ActiveContractsTraversalError("max-pages-exceeded", "active contracts traversal exceeded maxPages");
+            }
+            const response = await this.transport.getActiveContractsPageAsync(pageRequest, options.deadline.createRequestOptions());
+            pagesRead += 1;
+            if (typeof response.activeAtOffset !== "string" ||
+                response.activeAtOffset.trim().length === 0) {
+                throw new active_contracts_traversal_error_js_1.ActiveContractsTraversalError("missing-active-at-offset", "active contracts response is missing activeAtOffset");
+            }
+            else if (activeAtOffset === undefined) {
+                if (request.activeAtOffset !== undefined &&
+                    request.activeAtOffset !== response.activeAtOffset) {
+                    throw new active_contracts_traversal_error_js_1.ActiveContractsTraversalError("active-at-offset-mismatch", "active contracts response activeAtOffset does not match the request");
+                }
+                activeAtOffset = response.activeAtOffset;
+            }
+            else if (activeAtOffset !== response.activeAtOffset) {
+                throw new active_contracts_traversal_error_js_1.ActiveContractsTraversalError("active-at-offset-mismatch", "active contracts response activeAtOffset changed during traversal");
+            }
+            contractsRead += response.activeContracts.length;
+            if (contractsRead > options.maxContracts) {
+                throw new active_contracts_traversal_error_js_1.ActiveContractsTraversalError("max-contracts-exceeded", "active contracts traversal exceeded maxContracts");
+            }
+            yield response;
+            if (!response.nextPageToken || response.nextPageToken.length === 0) {
+                return;
+            }
+            const pageTokenKey = Array.from(response.nextPageToken).join(",");
+            if (observedPageTokens.has(pageTokenKey)) {
+                throw new active_contracts_traversal_error_js_1.ActiveContractsTraversalError("repeated-page-token", "active contracts traversal received a repeated page token");
+            }
+            observedPageTokens.add(pageTokenKey);
+            pageRequest = {
+                activeAtOffset,
+                eventFormat: request.eventFormat,
+                maxPageSize: request.maxPageSize,
+                pageToken: response.nextPageToken,
+            };
+        }
+    }
 }
 exports.StateServiceClient = StateServiceClient;

package/dist/services/state/state-service-client.d.ts

@@ -1,4 +1,5 @@
 import { ITransport } from "../../core/transports/transport.interface.js";
+import { ActiveContractsTraversalOptions } from "../../core/types/active-contracts-traversal-options.js";
 import { RequestOptions } from "../../core/types/request-options.js";
 import { GetActiveContractsRequest } from "../../core/types/requests/get-active-contracts-request.js";
 import type { GetActiveContractsPageRequest, GetActiveContractsPageResponse, GetConnectedSynchronizersRequest, GetConnectedSynchronizersResponse, GetLedgerEndRequest, GetLedgerEndResponse, GetLatestPrunedOffsetsRequest, GetLatestPrunedOffsetsResponse } from "../../transports/grpc/generated/canton/com/daml/ledger/api/v2/state_service.js";
@@ -8,6 +9,8 @@ export declare class StateServiceClient {
     constructor(transport: ITransport);
     /** Reads a page of active contracts. Supported on gRPC; JSON rejects it. */
     getActiveContractsPageAsync(request: GetActiveContractsPageRequest, options?: RequestOptions): Promise<GetActiveContractsPageResponse>;
+    /** Reads active-contract pages lazily. Supported on gRPC; JSON rejects it. */
+    getActiveContractsPagesAsync(request: GetActiveContractsPageRequest, options: ActiveContractsTraversalOptions): AsyncIterable<GetActiveContractsPageResponse>;
     /** Reads active contracts as a stream. JSON-backed; gRPC currently rejects it. */
     getActiveContractsAsync(request: GetActiveContractsRequest, observer: ContractObserver, options?: RequestOptions): Promise<void>;
     /** Reads connected synchronizers. Supported on gRPC; JSON rejects it. */
@@ -16,4 +19,5 @@ export declare class StateServiceClient {
     getLedgerEndAsync(request: GetLedgerEndRequest, options?: RequestOptions): Promise<GetLedgerEndResponse>;
     /** Reads the latest participant pruning offsets. Supported on gRPC; JSON rejects it. */
     getLatestPrunedOffsetsAsync(request: GetLatestPrunedOffsetsRequest, options?: RequestOptions): Promise<GetLatestPrunedOffsetsResponse>;
+    private getActiveContractsPagesLazy;
 }

package/dist/services/state/state-service-client.js

@@ -1,3 +1,5 @@
+import { ActiveContractsTraversalError } from "../../core/errors/active-contracts-traversal-error.js";
+import { ValidationError } from "../../core/errors/validation-error.js";
 export class StateServiceClient {
     transport;
     constructor(transport) {
@@ -8,6 +10,10 @@ export class StateServiceClient {
     getActiveContractsPageAsync(request, options) {
         return this.transport.getActiveContractsPageAsync(request, options);
     }
+    /** Reads active-contract pages lazily. Supported on gRPC; JSON rejects it. */
+    getActiveContractsPagesAsync(request, options) {
+        return this.getActiveContractsPagesLazy(request, options);
+    }
     /** Reads active contracts as a stream. JSON-backed; gRPC currently rejects it. */
     getActiveContractsAsync(request, observer, options) {
         return this.transport.getActiveContractsAsync(request, observer, options);
@@ -24,4 +30,54 @@ export class StateServiceClient {
     getLatestPrunedOffsetsAsync(request, options) {
         return this.transport.getLatestPrunedOffsetsAsync(request, options);
     }
+    async *getActiveContractsPagesLazy(request, options) {
+        if (request.pageToken && request.pageToken.length > 0) {
+            throw new ValidationError("active contracts traversal must not start with a page token");
+        }
+        let pageRequest = request;
+        let pagesRead = 0;
+        let contractsRead = 0;
+        let activeAtOffset;
+        const observedPageTokens = new Set();
+        while (true) {
+            if (pagesRead >= options.maxPages) {
+                throw new ActiveContractsTraversalError("max-pages-exceeded", "active contracts traversal exceeded maxPages");
+            }
+            const response = await this.transport.getActiveContractsPageAsync(pageRequest, options.deadline.createRequestOptions());
+            pagesRead += 1;
+            if (typeof response.activeAtOffset !== "string" ||
+                response.activeAtOffset.trim().length === 0) {
+                throw new ActiveContractsTraversalError("missing-active-at-offset", "active contracts response is missing activeAtOffset");
+            }
+            else if (activeAtOffset === undefined) {
+                if (request.activeAtOffset !== undefined &&
+                    request.activeAtOffset !== response.activeAtOffset) {
+                    throw new ActiveContractsTraversalError("active-at-offset-mismatch", "active contracts response activeAtOffset does not match the request");
+                }
+                activeAtOffset = response.activeAtOffset;
+            }
+            else if (activeAtOffset !== response.activeAtOffset) {
+                throw new ActiveContractsTraversalError("active-at-offset-mismatch", "active contracts response activeAtOffset changed during traversal");
+            }
+            contractsRead += response.activeContracts.length;
+            if (contractsRead > options.maxContracts) {
+                throw new ActiveContractsTraversalError("max-contracts-exceeded", "active contracts traversal exceeded maxContracts");
+            }
+            yield response;
+            if (!response.nextPageToken || response.nextPageToken.length === 0) {
+                return;
+            }
+            const pageTokenKey = Array.from(response.nextPageToken).join(",");
+            if (observedPageTokens.has(pageTokenKey)) {
+                throw new ActiveContractsTraversalError("repeated-page-token", "active contracts traversal received a repeated page token");
+            }
+            observedPageTokens.add(pageTokenKey);
+            pageRequest = {
+                activeAtOffset,
+                eventFormat: request.eventFormat,
+                maxPageSize: request.maxPageSize,
+                pageToken: response.nextPageToken,
+            };
+        }
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@distrohelena/canton-typescript-sdk",
-    "version": "0.1.35",
+    "version": "0.1.36",
     "license": "Apache-2.0",
     "type": "module",
     "main": "./dist/index.js",
@@ -98,6 +98,10 @@
         "example:workflow:retry": "npm run build && node --loader ts-node/esm examples/91-idempotent-command-retry.ts",
         "example:workflow:resume": "npm run build && node --loader ts-node/esm examples/92-resume-update-stream.ts",
         "example:workflow:stale-contract": "npm run build && node --loader ts-node/esm examples/93-archive-and-stale-contract.ts",
+        "example:workflow:command-completion": "npm run build && node --loader ts-node/esm examples/94-command-completion-correlation.ts",
+        "example:workflow:contract-lifecycle-audit": "npm run build && node --loader ts-node/esm examples/95-contract-lifecycle-audit.ts",
+        "example:workflow:update-lookup-reconciliation": "npm run build && node --loader ts-node/esm examples/96-update-lookup-reconciliation.ts",
+        "example:workflow:pruning-preflight": "npm run build && node --loader ts-node/esm examples/97-pruning-preflight.ts",
         "lint": "eslint . --max-warnings=0",
         "lint:fix": "eslint . --fix --max-warnings=0",
         "start:local-ledger": "bash node/start-local.sh",