Skip to content
← Open Cap Table Protocol Canton Node SDK

Reference

ledger.subscribeToCompletions

WebSocket stream over /v2/commands/completions with structured completion frames.

subscribeToCompletions opens ws(s)://…/v2/commands/completions using CompletionStreamRequest payloads derived from CompletionsWsParams.

Unlike subscribeToUpdates, this operation returns a Promise<WebSocketSubscription> so you close the socket explicitly—waitForCompletion wraps this internally.

Receiver: await canton.ledger.subscribeToCompletions(params, handlers)

Setup

import { Canton } from '@fairmint/canton-node-sdk';

const canton = new Canton({
  network: 'devnet',
  provider: '5n',
  partyId: 'OWN_PARTY_ID',
});

Minimal example

const sub = await canton.ledger.subscribeToCompletions(
  {
    userId: canton.getUserId()!,
    parties: [canton.getPartyId()],
    beginExclusive: checkpoint,
  },
  {
    onMessage: (msg) => {
      console.log(msg);
    },
    onError: (err) => console.error(err),
  }
);

setTimeout(() => sub.close(), 60_000);

If userId is omitted, the SDK calls client.getUserId()—configure userId on Canton or pass it explicitly or subscribeToCompletions throws early.

If parties is empty, buildPartyList() supplies acting + managed parties.

Parameters — first argument CompletionsWsParams

  • userId (optional, string) — Ledger stream user; required implicitly via client configuration if omitted.
  • parties (required array, may be empty) — Filter scope; empty ⇒ SDK fills buildPartyList().
  • beginExclusive (optional, number) — Exclusive resume offset (forward from checkpoint bookkeeping).

Parameters — second argument WebSocketHandlers<CompletionsWsMessage>

  • onMessage (required) — Every inbound JSON payload (CompletionStreamResponse, Canton error frames, web-socket errors modeled per schema unions).
  • onOpen (optional) — Socket accepted (daml.ws.auth subprotocol).
  • onError (optional) — Transport-layer Error objects.
  • onClose (optional) — (code, reason) after shutdown.

Token lifecycle hooks reuse WebSocketOptions from WebSocketClient when wired through the factory—call subscription.close() when finished.

Returns — Promise<WebSocketSubscription>

  • close() — Idempotent shutdown.
  • isConnected() — Status probe.
  • getConnectionState() — Raw WebSocket readyState.

Promise rejects when negotiation/auth fails before handlers attach.

Message shapes (CompletionsWsMessage)

Union of parsed CompletionStreamResponse (nested completionResponse with Completion, Empty, OffsetCheckpoint variants), JsCantonError, WsCantonError—mirror Canton diagnostics similar to updates streaming.

Errors and pitfalls

  • Missing userId configuration ⇒ synchronous Error before subscribe.
  • Parser errors bubble via onError / rejected Promise depending on failure phase.

Auth and party

Uses bearer tokens identical to REST calls; parties must align with read/act grants relevant to streamed completions.

See also

Source

operations/v2/commands/subscribe-to-completions.ts