@distrohelena/canton-typescript-sdk 0.1.33 → 0.1.36

package/README.md

@@ -92,6 +92,178 @@ topology shape: a serial-1 decentralized namespace definition, one self-root
 namespace certificate per owner, and a PartyToParticipant containing the party
 signing key. No deprecated PartyToKeyMapping is created.
 
+The SDK preserves `identityProviderId`, `userId`, and `waitForAllocation`
+through decentralized prepare/finalize. Canton ignores `waitForAllocation` for
+decentralized parties, so the example explicitly calls
+`topologyAggregationService.waitForPartyHostingAsync(...)` to prove that the
+expected participant is hosting the party on the expected synchronizer. That
+aggregate topology check is the same on Participant 3.5.7 and 3.5.8.
+
+## Standalone TypeScript examples
+
+The repository includes runnable TypeScript examples for a local Canton
+participant. Check them before running a lifecycle:
+
+```bash
+npm run examples:check
+```
+
+The setup and party examples are available individually:
+
+```bash
+npm run example:init
+npm run example:tls
+npm run example:jwt
+npm run example:party:hosted
+npm run example:party:external
+npm run example:party:decentralized
+```
+
+For the application lifecycle, run these in order:
+
+```bash
+npm run example:dar:upload
+npm run example:contract:create-exercise
+npm run example:contract:query
+npm run example:updates:stream
+npm run example:user:rights
+npm run example:topology:party-hosting
+```
+
+### Workflow examples
+
+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
+```
+
+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
+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
+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.
+
+- `example:workflow:atomic` first proves that an invalid choice is rejected,
+  then proves an atomic create-and-exercise by reading the created replacement
+  and its exact text.
+- `example:workflow:retry` submits a caller-controlled command ID with a
+  deduplication duration, retries the exact same request, classifies the
+  duplicate outcome, and proves that exactly one matching contract is active.
+- `example:workflow:resume` saves the ledger end before its post-offset create,
+  proves the intentionally idle stream timeout, then resumes exclusively after
+  that saved offset and rejects a pre-offset contract if it appears.
+- `example:workflow:stale-contract` proves archive/replacement state and then
+  proves that exercising the archived contract is rejected.
+
+Expected failures are accepted only through structured error classification:
+gRPC status code, decoded status, operation, and the selected compatibility
+path—not prose matching. The retry example uses one explicit command ID and
+deduplication period for the exact same request; changing either value is a new
+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 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`.
+
+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
+isolated 3.5.8 sidecar, use the SDK sidecar launcher's protected documented
+credential refresh flow in a local child shell and refresh before expiry. Never
+log its output or expose refreshed credentials beyond that child. Use the
+documented `SDK_EXAMPLE_*` environment variables when running the workflow
+commands.
+
+By default, Ledger and Ledger Admin use `localhost:3901`; Participant Admin
+uses `localhost:3902`. Override them with
+`SDK_EXAMPLE_LEDGER_ENDPOINT`, `SDK_EXAMPLE_LEDGER_ADMIN_ENDPOINT`, and
+`SDK_EXAMPLE_PARTICIPANT_ADMIN_ENDPOINT`. Use `SDK_EXAMPLE_BEARER_TOKEN` for a
+shared bearer token, or set `SDK_EXAMPLE_LEDGER_BEARER_TOKEN`,
+`SDK_EXAMPLE_LEDGER_ADMIN_BEARER_TOKEN`, and
+`SDK_EXAMPLE_PARTICIPANT_ADMIN_BEARER_TOKEN` per surface. The examples also
+accept `SDK_EXAMPLE_PARTY`, `SDK_EXAMPLE_USER_ID`, `SDK_EXAMPLE_SYNCHRONIZER`,
+and `SDK_EXAMPLE_TIMEOUT_MS`; generated fallback party names use
+`SDK_EXAMPLE_PARTY_PREFIX` when supplied. For TLS, set
+`SDK_EXAMPLE_TLS_ROOT_CERTIFICATE` to a custom CA certificate path.
+
+Some commands intentionally create durable localnet state: DAR upload installs
+a package; create/exercise, query, and stream may allocate a fallback party and
+create contracts; topology inspection may allocate a fallback party. User-rights
+is read-only. These examples do not clean up durable state.
+
+The uploaded asset is
+`canton-explorer-debug-playground-0.1.0.dar`, the normal (not debug) Canton
+Explorer Debug Playground DAR from
+`/home/helena/dev/daml/canton-explorer/debug-playground/.daml/dist/canton-explorer-debug-playground-0.1.0.dar`.
+Its Canton Explorer checkout commit is `750b28dd0ce4674e4368c12a6da1b5b5cbb00f88`,
+its package-introduction commit is `abde077`, it is Apache-2.0 licensed, and
+its SHA-256 is
+`307cf7c52ac2770d1d1a2c5e1ec56a78ab7c70e7809c0cfb419abadb93cc6e29`.
+
+The examples and their DAR are repository-only and excluded from the npm
+tarball. The existing setup and decentralized-party examples were developed
+and live-tested against Participant 3.5.7, then live-tested unchanged against
+the isolated [Participant 3.5.8 sidecar](#optional-canton-358-participant-sidecar).
+The workflow examples have completed 3.5.7 and 3.5.8 workflow matrices with
+authenticated status evidence, the same unchanged implementation, and the
+common compatibility path.
+
 ## Localnet launchers
 
 The published package includes launchers for an existing CN Quickstart checkout.
@@ -133,13 +305,21 @@ Compose project, its Postgres container, and host ports `8901` (Ledger), `8902`
 registered synchronizer via its Admin API, stores the exported connection
 configuration in the sidecar runtime directory, and connects the sidecar with
 its own Admin API. It generates a five-minute 3.5.8-compatible development JWT
-at `.generated/participant-358/ledger-api-user.token` and prints both live-test
-and example endpoint/token exports when the connection is healthy.
+at `.generated/participant-358/ledger-api-user.token`. When the connection is
+healthy, use the protected child-shell credential flow below to make the
+live-test and example endpoint/token variables available without logging them.
+Canton 3.5.8 enforces this short lifetime for the unsafe development JWT.
 `cn-quickstart` is strictly read-only: this launcher never writes to, starts,
 or stops the normal Quickstart stack.
 
-After copying the printed `SDK_EXAMPLE_*` exports into the current shell, run
-the standalone decentralized-party comparison example with:
+Refresh short-lived credentials before expiry without restarting or otherwise
+touching the running containers. Use the launcher's protected documented
+credential refresh flow only in a local child shell; do not log its output or
+expose refreshed credentials beyond that child. The runtime credential file
+remains protected with mode `0600`.
+
+After the protected credential flow completes, run the example inside that same
+short-lived credential-scoped child shell:
 
 ```bash
 npm run example:party:decentralized
@@ -151,11 +331,14 @@ localnet differs:
 
 ```bash
 PARTICIPANT_358_SOURCE_ADMIN_ENDPOINT=localhost:3902 \
-PARTICIPANT_358_SOURCE_ADMIN_BEARER_TOKEN="$TOKEN" \
 PARTICIPANT_358_NETWORK=quickstart \
 canton-localnet-participant-358-start
 ```
 
+Provide any required source-admin credential only through the protected
+child-scoped credential mechanism described above; do not place credentials in
+command lines or logs.
+
 Use `PARTICIPANT_358_CANTON_IMAGE`, `PARTICIPANT_358_PROJECT_NAME`,
 `PARTICIPANT_358_RUNTIME_DIR`, `PARTICIPANT_358_LEDGER_PORT`,
 `PARTICIPANT_358_ADMIN_PORT`, and `PARTICIPANT_358_JSON_PORT` to make an
@@ -179,11 +362,12 @@ a self-signed certificate in `.generated/localnet-es256` at the package root. Se
 use your own matching PEM private key and certificate.
 
 The launcher writes a short-lived (ten-minute) token for `ledger-api-user` to
-`ledger-api-user.token` in that runtime directory and prints its path. Use it
-with the live SDK suite:
+`ledger-api-user.token` in that runtime directory and prints its path. In a
+short-lived child shell, use a protected local credential mechanism to make the
+token available without placing its value or a token-file read in a command
+line or log. From within that same child shell, run the live SDK suite:
 
 ```bash
-SDK_TEST_LEDGER_BEARER_TOKEN="$(cat .generated/localnet-es256/ledger-api-user.token)" \
 npm run test:live
 ```
 
@@ -356,11 +540,11 @@ import {
     BearerTokenAuthProvider,
     CantonClient,
     CantonClientOptions,
-    GetActiveContractsPageRequest,
     HealthCheckRequest,
     GetLedgerApiVersionRequest,
     TransportKind,
 } from "@distrohelena/canton-typescript-sdk";
+import { ledgerApiV2 } from "@distrohelena/canton-typescript-sdk/protobuf";
 
 const client = new CantonClient(
     new CantonClientOptions({
@@ -393,14 +577,22 @@ const party = await client.partyManagementService.allocatePartyAsync(
     }),
 );
 const contracts = await client.stateService.getActiveContractsPageAsync(
-    new GetActiveContractsPageRequest({
-        party: "Alice",
-        templateId: "Main:Iou",
+    ledgerApiV2.GetActiveContractsPageRequest.create({
+        eventFormat: {
+            filtersByParty: {
+                Alice: { cumulative: [] },
+            },
+            verbose: true,
+        },
     }),
 );
 ```
 
-`stateService.getActiveContractsPageAsync(...)` keeps `templateId` as the simple helper path, and on gRPC also supports interface-based ACS reads with `interfaceId`, `includeInterfaceView`, `includeCreatedEventBlob`, `activeAtOffset`, `maxPageSize`, and `pageToken`. JSON remains template-query only.
+`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.
 
@@ -547,12 +739,13 @@ unsupported query features reject with `QueryCapabilityError`.
 - `packageService.listVettedPackagesAsync(...)`: `grpc` only
 - `commandService.submitAndWaitAsync(...)`: `json`, `grpc`
 - `commandSubmissionService.submitAsync(...)`: reserved, currently unsupported
-- `stateService.getActiveContractsPageAsync(...)`: `json`, `grpc`
-- `stateService.getActiveContractsAsync(...)`: `json` only
+- `stateService.getActiveContractsPageAsync(...)`: `grpc` 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/client/external-party-activation-client.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ExternalPartyActivationClient = void 0;
+const list_party_to_participant_request_js_1 = require("../core/types/requests/list-party-to-participant-request.js");
+const topology_base_query_js_1 = require("../core/types/topology/topology-base-query.js");
 const topology_store_id_js_1 = require("../core/types/topology/topology-store-id.js");
 const topology_js_1 = require("../transports/grpc/generated/canton/com/digitalasset/canton/protocol/v30/topology.js");
 const external_party_activation_response_js_1 = require("./external-party-activation-response.js");
@@ -66,27 +68,35 @@ class ExternalPartyActivationClient {
     }
     async readStateAsync(request, options) {
         const [activeResponse, proposalResponse] = await Promise.all([
-            this.sourceClient.topologyManagerReadService.listPartyToParticipantAsync({
-                baseQuery: createSynchronizerQuery(request.synchronizerId, false),
+            this.sourceClient.topologyManagerReadService.listPartyToParticipantAsync(new list_party_to_participant_request_js_1.ListPartyToParticipantRequest({
+                baseQuery: new topology_base_query_js_1.TopologyBaseQuery({
+                    storeId: createSynchronizerStoreId(request.synchronizerId),
+                    headState: true,
+                    includeProposals: false,
+                }),
                 filterParty: request.partyId,
                 filterParticipant: "",
-            }, options),
-            this.sourceClient.topologyManagerReadService.listPartyToParticipantAsync({
-                baseQuery: createSynchronizerQuery(request.synchronizerId, true),
+            }), options),
+            this.sourceClient.topologyManagerReadService.listPartyToParticipantAsync(new list_party_to_participant_request_js_1.ListPartyToParticipantRequest({
+                baseQuery: new topology_base_query_js_1.TopologyBaseQuery({
+                    storeId: createSynchronizerStoreId(request.synchronizerId),
+                    headState: true,
+                    includeProposals: true,
+                }),
                 filterParty: request.partyId,
                 filterParticipant: "",
-            }, options),
+            }), options),
         ]);
-        const active = activeResponse.results.find((item) => item.item?.party === request.partyId);
-        const proposal = proposalResponse.results.find((item) => item.item?.party === request.partyId);
+        const active = activeResponse.results.find((item) => item.item.party === request.partyId);
+        const proposal = proposalResponse.results.find((item) => item.item.party === request.partyId);
         return {
-            active: active === undefined || active.context === undefined || active.item === undefined
+            active: active === undefined || active.context === undefined
                 ? undefined
                 : {
                     context: active.context,
                     mapping: active.item,
                 },
-            proposal: proposal === undefined || proposal.context === undefined || proposal.item === undefined
+            proposal: proposal === undefined || proposal.context === undefined
                 ? undefined
                 : {
                     context: proposal.context,

package/dist/cjs/core/errors/active-contracts-traversal-error.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActiveContractsTraversalError = void 0;
+const canton_error_js_1 = require("./canton-error.js");
+class ActiveContractsTraversalError extends canton_error_js_1.CantonError {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+exports.ActiveContractsTraversalError = ActiveContractsTraversalError;

package/dist/cjs/core/polling/poll-until-async.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pollUntilAsync = pollUntilAsync;
+async function pollUntilAsync(init) {
+    const now = init.now ?? Date.now;
+    const sleepAsync = init.sleepAsync ?? defaultSleepAsync;
+    const deadline = now() + init.timeoutMs;
+    let lastObserved;
+    let firstRead = true;
+    while (firstRead || now() < deadline) {
+        firstRead = false;
+        lastObserved = await init.readAsync();
+        if (init.match(lastObserved)) {
+            return lastObserved;
+        }
+        const remainingMs = deadline - now();
+        if (remainingMs <= 0) {
+            throw init.createTimeoutError(lastObserved);
+        }
+        await sleepAsync(Math.min(init.pollIntervalMs, remainingMs));
+    }
+    throw init.createTimeoutError(lastObserved);
+}
+async function defaultSleepAsync(milliseconds) {
+    await new Promise(resolve => setTimeout(resolve, milliseconds));
+}

package/dist/cjs/core/types/active-contracts-traversal-options.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActiveContractsTraversalOptions = void 0;
+const validation_error_js_1 = require("../errors/validation-error.js");
+const operation_deadline_js_1 = require("./operation-deadline.js");
+class ActiveContractsTraversalOptions {
+    deadline;
+    maxPages;
+    maxContracts;
+    constructor(init) {
+        if (!(init.deadline instanceof operation_deadline_js_1.OperationDeadline)) {
+            throw new validation_error_js_1.ValidationError("active contracts traversal deadline must be an OperationDeadline");
+        }
+        else if (!Number.isSafeInteger(init.maxPages) || init.maxPages <= 0) {
+            throw new validation_error_js_1.ValidationError("active contracts traversal maxPages must be a positive safe integer");
+        }
+        else if (!Number.isSafeInteger(init.maxContracts) || init.maxContracts <= 0) {
+            throw new validation_error_js_1.ValidationError("active contracts traversal maxContracts must be a positive safe integer");
+        }
+        this.deadline = init.deadline;
+        this.maxPages = init.maxPages;
+        this.maxContracts = init.maxContracts;
+        Object.freeze(this);
+    }
+}
+exports.ActiveContractsTraversalOptions = ActiveContractsTraversalOptions;

package/dist/cjs/core/types/command-deduplication-period.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/core/types/operation-deadline.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OperationDeadline = void 0;
+const timeout_error_js_1 = require("../errors/timeout-error.js");
+const validation_error_js_1 = require("../errors/validation-error.js");
+const request_options_js_1 = require("./request-options.js");
+class OperationDeadline {
+    endsAtMs;
+    now;
+    remainingMs;
+    constructor(init) {
+        if (!Number.isSafeInteger(init.timeoutMs) || init.timeoutMs <= 0) {
+            throw new validation_error_js_1.ValidationError("operation deadline timeout must be a positive safe integer");
+        }
+        this.now = init.now ?? Date.now;
+        const startedAtMs = this.safeNow();
+        this.endsAtMs = startedAtMs + init.timeoutMs;
+        if (!Number.isSafeInteger(this.endsAtMs)) {
+            throw new validation_error_js_1.ValidationError("operation deadline end time must be a safe integer");
+        }
+        this.remainingMs = init.timeoutMs;
+    }
+    remainingTimeoutMs() {
+        const computedRemainingMs = Math.max(0, this.endsAtMs - this.safeNow());
+        this.remainingMs = Math.min(this.remainingMs, computedRemainingMs);
+        if (this.remainingMs === 0) {
+            throw new timeout_error_js_1.TimeoutError("operation deadline has expired");
+        }
+        return this.remainingMs;
+    }
+    createRequestOptions() {
+        return new request_options_js_1.RequestOptions({ timeoutMs: this.remainingTimeoutMs() });
+    }
+    safeNow() {
+        const now = this.now();
+        if (!Number.isSafeInteger(now)) {
+            throw new validation_error_js_1.ValidationError("operation deadline clock must return a safe integer");
+        }
+        return now;
+    }
+}
+exports.OperationDeadline = OperationDeadline;

package/dist/cjs/core/types/requests/allocate-party-request.js

@@ -4,9 +4,11 @@ exports.AllocatePartyRequest = void 0;
 class AllocatePartyRequest {
     partyIdHint;
     displayName;
+    userId;
     constructor(init = {}) {
         this.partyIdHint = init.partyIdHint;
         this.displayName = init.displayName;
+        this.userId = init.userId;
     }
 }
 exports.AllocatePartyRequest = AllocatePartyRequest;

package/dist/cjs/core/types/requests/finalize-decentralized-party-request.js

@@ -8,6 +8,9 @@ class PreparedDecentralizedParty {
     decentralizedNamespace;
     ownerThreshold;
     partySigningThreshold;
+    identityProviderId;
+    waitForAllocation;
+    userId;
     transactions;
     signingRequests;
     constructor(init) {
@@ -16,6 +19,9 @@ class PreparedDecentralizedParty {
         this.decentralizedNamespace = init.decentralizedNamespace;
         this.ownerThreshold = init.ownerThreshold;
         this.partySigningThreshold = init.partySigningThreshold;
+        this.identityProviderId = init.identityProviderId;
+        this.waitForAllocation = init.waitForAllocation;
+        this.userId = init.userId;
         this.transactions = [...(init.transactions ?? [])].map((transaction) => new prepared_topology_transaction_js_1.PreparedTopologyTransaction({
             serializedTransaction: transaction.serializedTransaction,
             transactionHash: transaction.transactionHash,

package/dist/cjs/core/types/requests/submit-command-request.js

@@ -2,25 +2,68 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SubmitCommandRequest = void 0;
 const validation_error_js_1 = require("../../errors/validation-error.js");
+const ledgerStringPattern = /^[A-Za-z0-9#:\-_/ ]+$/;
+const canonicalOffsetPattern = /^(0|[1-9][0-9]*)$/;
+const maximumInt64Offset = "9223372036854775807";
 class SubmitCommandRequest {
     applicationId;
     userId;
     actAs;
     readAs;
     command;
+    commandId;
+    deduplicationPeriod;
     disclosedContracts;
     synchronizerId;
     constructor(init) {
         if (init.actAs.length === 0) {
             throw new validation_error_js_1.ValidationError("submit requests require at least one actAs party");
         }
+        else if (init.commandId !== undefined &&
+            (typeof init.commandId !== "string" ||
+                init.commandId.length > 255 ||
+                !ledgerStringPattern.test(init.commandId))) {
+            throw new validation_error_js_1.ValidationError("submit request command ID must be a LedgerString");
+        }
+        const deduplicationPeriod = freezeDeduplicationPeriod(init.deduplicationPeriod);
         this.applicationId = init.applicationId;
         this.userId = init.userId;
         this.actAs = init.actAs;
         this.readAs = init.readAs ?? [];
         this.command = init.command;
+        this.commandId = init.commandId;
+        this.deduplicationPeriod = deduplicationPeriod;
         this.disclosedContracts = init.disclosedContracts ?? [];
         this.synchronizerId = init.synchronizerId;
     }
 }
 exports.SubmitCommandRequest = SubmitCommandRequest;
+function freezeDeduplicationPeriod(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    else if (typeof value !== "object" ||
+        value === null ||
+        Array.isArray(value)) {
+        throw new validation_error_js_1.ValidationError("submit request deduplication period is invalid");
+    }
+    else if (value.kind === "duration") {
+        if (typeof value.seconds !== "number" ||
+            !Number.isSafeInteger(value.seconds) ||
+            value.seconds <= 0) {
+            throw new validation_error_js_1.ValidationError("submit request duration deduplication seconds must be a positive safe integer");
+        }
+        return Object.freeze({ kind: "duration", seconds: value.seconds });
+    }
+    else if (value.kind !== "offset") {
+        throw new validation_error_js_1.ValidationError("submit request deduplication period is invalid");
+    }
+    if (typeof value.offset !== "string" ||
+        !canonicalOffsetPattern.test(value.offset) ||
+        value.offset.length > maximumInt64Offset.length ||
+        (value.offset.length === maximumInt64Offset.length &&
+            value.offset > maximumInt64Offset)) {
+        throw new validation_error_js_1.ValidationError("submit request offset deduplication period must be a canonical unsigned int64");
+    }
+    return Object.freeze({ kind: "offset", offset: value.offset });
+}

package/dist/cjs/core/types/requests/wait-for-party-hosting-request.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WaitForPartyHostingRequest = void 0;
+const validation_error_js_1 = require("../../errors/validation-error.js");
+class WaitForPartyHostingRequest {
+    partyId;
+    participantId;
+    synchronizerId;
+    pollIntervalMs;
+    timeoutMs;
+    constructor(init) {
+        const partyId = init.partyId.trim();
+        const participantId = init.participantId.trim();
+        const synchronizerId = init.synchronizerId.trim();
+        const pollIntervalMs = init.pollIntervalMs ?? 500;
+        const timeoutMs = init.timeoutMs ?? 30_000;
+        if (!partyId) {
+            throw new validation_error_js_1.ValidationError("party hosting wait requires a party ID");
+        }
+        else if (!participantId) {
+            throw new validation_error_js_1.ValidationError("party hosting wait requires a participant ID");
+        }
+        else if (!synchronizerId) {
+            throw new validation_error_js_1.ValidationError("party hosting wait requires a synchronizer ID");
+        }
+        else if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
+            throw new validation_error_js_1.ValidationError("party hosting wait timeout must be a positive safe integer");
+        }
+        else if (!Number.isSafeInteger(pollIntervalMs) ||
+            pollIntervalMs < 0) {
+            throw new validation_error_js_1.ValidationError("party hosting wait poll interval must be a non-negative safe integer");
+        }
+        this.partyId = partyId;
+        this.participantId = participantId;
+        this.synchronizerId = synchronizerId;
+        this.pollIntervalMs = pollIntervalMs;
+        this.timeoutMs = timeoutMs;
+    }
+}
+exports.WaitForPartyHostingRequest = WaitForPartyHostingRequest;