cantonjs 0.0.1

package/src/clients/createLedgerClient.ts

@@ -0,0 +1,383 @@
+/**
+ * Factory for creating a party-scoped Ledger API client.
+ *
+ * The LedgerClient provides contract operations: create, exercise, query.
+ * Each client is scoped to a party via its JWT token.
+ *
+ * Request/response shapes match the Canton JSON Ledger API V2 OpenAPI spec (3.4+).
+ */
+
+import type { Transport, TransportRequest } from '../transport/types.js'
+import type { Party } from '../types/party.js'
+import type {
+  CreatedEvent,
+  TaggedEvent,
+  ActiveContract,
+  ContractEntry,
+} from '../types/contract.js'
+import type { JsTransaction } from '../types/transaction.js'
+import type { Reassignment, ReassignmentCommand } from '../types/reassignment.js'
+import type {
+  PrepareSubmissionResponse,
+  PartySignatures,
+} from '../types/interactive.js'
+import type { LedgerOffset, EventFormat, TransactionFormat } from '../types/command.js'
+
+export type LedgerClientConfig = {
+  /** Transport to communicate with the Canton node. */
+  readonly transport: Transport
+  /** The party this client acts as. */
+  readonly actAs: Party
+  /** Additional parties this client can read as. */
+  readonly readAs?: readonly Party[]
+}
+
+export type LedgerClient = {
+  /** The party this client acts as. */
+  readonly actAs: Party
+  /** Additional parties this client can read as. */
+  readonly readAs: readonly Party[]
+
+  /** Create a new contract on the ledger. */
+  createContract: (
+    templateId: string,
+    createArguments: Record<string, unknown>,
+    options?: CommandOptions,
+  ) => Promise<CreatedEvent>
+
+  /** Exercise a choice on an existing contract. */
+  exerciseChoice: (
+    templateId: string,
+    contractId: string,
+    choice: string,
+    choiceArgument: Record<string, unknown>,
+    options?: CommandOptions,
+  ) => Promise<JsTransaction>
+
+  /** Query active contracts matching a template. */
+  queryContracts: (
+    templateId: string,
+    options?: QueryOptions,
+  ) => Promise<readonly ActiveContract[]>
+
+  /** Get a transaction by its update ID. */
+  getTransactionById: (updateId: string) => Promise<JsTransaction>
+
+  /** Get the current ledger end offset. */
+  getLedgerEnd: () => Promise<LedgerOffset>
+
+  /** Get events for a specific contract. */
+  getEventsByContractId: (contractId: string) => Promise<unknown>
+
+  /** Get connected synchronizer IDs. */
+  getConnectedSynchronizers: () => Promise<readonly ConnectedSynchronizer[]>
+
+  /** Get the latest pruned offsets. */
+  getLatestPrunedOffsets: () => Promise<PrunedOffsets>
+
+  /** Submit a reassignment command and wait for completion. */
+  submitReassignment: (
+    command: ReassignmentCommand,
+    options?: CommandOptions,
+  ) => Promise<Reassignment>
+
+  /**
+   * Prepare a transaction for external signing.
+   * Returns the prepared transaction and hash to sign.
+   */
+  prepareSubmission: (
+    templateId: string,
+    createArguments: Record<string, unknown>,
+    options?: CommandOptions,
+  ) => Promise<PrepareSubmissionResponse>
+
+  /**
+   * Execute a previously prepared and externally signed transaction.
+   */
+  executeSubmission: (
+    preparedTransaction: string,
+    partySignatures: readonly PartySignatures[],
+    options?: { readonly submissionId?: string; readonly signal?: AbortSignal },
+  ) => Promise<JsTransaction>
+}
+
+/** A connected synchronizer (domain). */
+export type ConnectedSynchronizer = {
+  readonly synchronizerId: string
+  readonly permission: 'SUBMISSION' | 'OBSERVATION' | 'UNSPECIFIED'
+}
+
+/** Pruned offset information. */
+export type PrunedOffsets = {
+  readonly participantPrunedUpToInclusive?: number
+  readonly allDivulgedContractsPrunedUpToInclusive?: number
+}
+
+export type CommandOptions = {
+  readonly commandId?: string
+  readonly workflowId?: string
+  readonly signal?: AbortSignal
+}
+
+export type QueryOptions = {
+  readonly signal?: AbortSignal
+  /** Event format for filtering. Defaults to verbose wildcard filter for actAs party. */
+  readonly eventFormat?: EventFormat
+  /** Offset to snapshot at. 0 = empty ledger. Defaults to 0. */
+  readonly activeAtOffset?: LedgerOffset
+}
+
+/** Generate a random UUID, compatible with Node.js 18+ and browsers. */
+function generateUUID(): string {
+  if (typeof globalThis.crypto?.randomUUID === 'function') {
+    return globalThis.crypto.randomUUID()
+  }
+  // Fallback for Node.js 18 where globalThis.crypto.randomUUID may not exist
+  const bytes = new Uint8Array(16)
+  if (typeof globalThis.crypto?.getRandomValues === 'function') {
+    globalThis.crypto.getRandomValues(bytes)
+  } else {
+    for (let i = 0; i < 16; i++) bytes[i] = Math.floor(Math.random() * 256)
+  }
+  bytes[6] = (bytes[6]! & 0x0f) | 0x40
+  bytes[8] = (bytes[8]! & 0x3f) | 0x80
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('')
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`
+}
+
+export function createLedgerClient(config: LedgerClientConfig): LedgerClient {
+  const { transport, actAs, readAs = [] } = config
+
+  function defaultEventFormat(): EventFormat {
+    return {
+      filtersByParty: {
+        [actAs]: {
+          cumulative: [
+            {
+              identifierFilter: {
+                WildcardFilter: { value: { includeCreatedEventBlob: false } },
+              },
+            },
+          ],
+        },
+      },
+      verbose: true,
+    }
+  }
+
+  function templateEventFormat(templateId: string): EventFormat {
+    return {
+      filtersByParty: {
+        [actAs]: {
+          cumulative: [
+            {
+              identifierFilter: {
+                TemplateFilter: {
+                  value: { templateId, includeCreatedEventBlob: false },
+                },
+              },
+            },
+          ],
+        },
+      },
+      verbose: true,
+    }
+  }
+
+  function defaultTransactionFormat(): TransactionFormat {
+    return {
+      transactionShape: 'TRANSACTION_SHAPE_ACS_DELTA',
+      eventFormat: defaultEventFormat(),
+    }
+  }
+
+  return {
+    actAs,
+    readAs,
+
+    async createContract(templateId, createArguments, options) {
+      const request: TransportRequest = {
+        method: 'POST',
+        path: '/v2/commands/submit-and-wait-for-transaction',
+        body: {
+          commands: {
+            commands: [{ CreateCommand: { templateId, createArguments } }],
+            commandId: options?.commandId ?? generateUUID(),
+            actAs: [actAs],
+            readAs: readAs.length > 0 ? readAs : undefined,
+            workflowId: options?.workflowId,
+          },
+          transactionFormat: defaultTransactionFormat(),
+        },
+      }
+      if (options?.signal) request.signal = options.signal
+
+      const response = await transport.request<{
+        transaction: JsTransaction
+      }>(request)
+
+      const created = extractCreatedEvent(response.transaction.events)
+      if (created === undefined) {
+        throw new Error('No created event in transaction response')
+      }
+      return created
+    },
+
+    async exerciseChoice(templateId, contractId, choice, choiceArgument, options) {
+      const request: TransportRequest = {
+        method: 'POST',
+        path: '/v2/commands/submit-and-wait-for-transaction',
+        body: {
+          commands: {
+            commands: [
+              { ExerciseCommand: { templateId, contractId, choice, choiceArgument } },
+            ],
+            commandId: options?.commandId ?? generateUUID(),
+            actAs: [actAs],
+            readAs: readAs.length > 0 ? readAs : undefined,
+            workflowId: options?.workflowId,
+          },
+          transactionFormat: defaultTransactionFormat(),
+        },
+      }
+      if (options?.signal) request.signal = options.signal
+
+      const response = await transport.request<{
+        transaction: JsTransaction
+      }>(request)
+
+      return response.transaction
+    },
+
+    async queryContracts(templateId, options) {
+      const request: TransportRequest = {
+        method: 'POST',
+        path: '/v2/state/active-contracts',
+        body: {
+          activeAtOffset: options?.activeAtOffset ?? 0,
+          eventFormat: options?.eventFormat ?? templateEventFormat(templateId),
+        },
+      }
+      if (options?.signal) request.signal = options.signal
+
+      const response = await transport.request<
+        readonly { contractEntry: ContractEntry }[]
+      >(request)
+
+      return response
+        .map((entry) => {
+          if ('JsActiveContract' in entry.contractEntry) {
+            return entry.contractEntry.JsActiveContract
+          }
+          return undefined
+        })
+        .filter((c): c is ActiveContract => c !== undefined)
+    },
+
+    async getTransactionById(updateId) {
+      const response = await transport.request<{ transaction: JsTransaction }>({
+        method: 'POST',
+        path: '/v2/updates/transaction-by-id',
+        body: {
+          updateId,
+          requestingParties: [actAs, ...readAs],
+        },
+      })
+      return response.transaction
+    },
+
+    async getLedgerEnd() {
+      const response = await transport.request<{ offset: number }>({
+        method: 'GET',
+        path: '/v2/state/ledger-end',
+      })
+      return response.offset
+    },
+
+    async getEventsByContractId(contractId) {
+      return transport.request({
+        method: 'POST',
+        path: '/v2/events/events-by-contract-id',
+        body: { contractId, requestingParties: [actAs, ...readAs] },
+      })
+    },
+
+    async getConnectedSynchronizers() {
+      const response = await transport.request<{
+        connectedSynchronizers: readonly ConnectedSynchronizer[]
+      }>({
+        method: 'GET',
+        path: '/v2/state/connected-synchronizers',
+      })
+      return response.connectedSynchronizers ?? []
+    },
+
+    async getLatestPrunedOffsets() {
+      const response = await transport.request<PrunedOffsets>({
+        method: 'GET',
+        path: '/v2/state/latest-pruned-offsets',
+      })
+      return response
+    },
+
+    async submitReassignment(command, options) {
+      const request: TransportRequest = {
+        method: 'POST',
+        path: '/v2/commands/submit-and-wait-for-reassignment',
+        body: {
+          reassignmentCommand: command,
+          commandId: options?.commandId ?? generateUUID(),
+          submitter: actAs,
+          workflowId: options?.workflowId,
+        },
+      }
+      if (options?.signal) request.signal = options.signal
+
+      const response = await transport.request<{ reassignment: Reassignment }>(request)
+      return response.reassignment
+    },
+
+    async prepareSubmission(templateId, createArguments, options) {
+      const request: TransportRequest = {
+        method: 'POST',
+        path: '/v2/interactive-submission/prepare',
+        body: {
+          commands: [{ CreateCommand: { templateId, createArguments } }],
+          commandId: options?.commandId ?? generateUUID(),
+          actAs: [actAs],
+          readAs: readAs.length > 0 ? readAs : undefined,
+          workflowId: options?.workflowId,
+        },
+      }
+      if (options?.signal) request.signal = options.signal
+
+      return transport.request<PrepareSubmissionResponse>(request)
+    },
+
+    async executeSubmission(preparedTransaction, partySignatures, options) {
+      const request: TransportRequest = {
+        method: 'POST',
+        path: '/v2/interactive-submission/execute',
+        body: {
+          preparedTransaction,
+          partySignatures,
+          submissionId: options?.submissionId,
+        },
+      }
+      if (options?.signal) request.signal = options.signal
+
+      const response = await transport.request<{ transaction: JsTransaction }>(request)
+      return response.transaction
+    },
+  }
+}
+
+/** Extract the first CreatedEvent from a list of tagged events. */
+function extractCreatedEvent(events: readonly TaggedEvent[]): CreatedEvent | undefined {
+  for (const event of events) {
+    if ('CreatedEvent' in event) {
+      return event.CreatedEvent
+    }
+  }
+  return undefined
+}

package/src/clients/createTestClient.ts

@@ -0,0 +1,77 @@
+/**
+ * Factory for creating a test client for Canton sandbox.
+ *
+ * The TestClient provides sandbox lifecycle management, party allocation,
+ * and time manipulation for testing. Extends LedgerClient + AdminClient.
+ */
+
+import type { Transport } from '../transport/types.js'
+import type { Party, PartyDetails } from '../types/party.js'
+import { createLedgerClient, type LedgerClient } from './createLedgerClient.js'
+import { createAdminClient, type AdminClient } from './createAdminClient.js'
+
+export type TestClientConfig = {
+  readonly transport: Transport
+  /** Default party for ledger operations. If not provided, one will be allocated. */
+  readonly party?: Party
+}
+
+export type TestClient = LedgerClient &
+  AdminClient & {
+    /** Get the current ledger time (static-time sandbox only). */
+    getTime: () => Promise<Date>
+
+    /** Set the ledger time (static-time sandbox only). */
+    setTime: (currentTime: Date, newTime: Date) => Promise<void>
+
+    /** Advance ledger time by a duration in seconds (static-time sandbox only). */
+    advanceTime: (seconds: number) => Promise<void>
+
+    /** Allocate multiple parties at once. */
+    allocateParties: (hints: readonly string[]) => Promise<readonly PartyDetails[]>
+  }
+
+export function createTestClient(config: TestClientConfig): TestClient {
+  const { transport, party = 'test-party' as Party } = config
+
+  const ledger = createLedgerClient({ transport, actAs: party })
+  const admin = createAdminClient({ transport })
+
+  return {
+    ...ledger,
+    ...admin,
+
+    async getTime() {
+      const response = await transport.request<{ currentTime: string }>({
+        method: 'GET',
+        path: '/v2/time',
+      })
+      return new Date(response.currentTime)
+    },
+
+    async setTime(currentTime, newTime) {
+      await transport.request({
+        method: 'POST',
+        path: '/v2/time',
+        body: {
+          currentTime: currentTime.toISOString(),
+          newTime: newTime.toISOString(),
+        },
+      })
+    },
+
+    async advanceTime(seconds) {
+      const current = await this.getTime()
+      const newTime = new Date(current.getTime() + seconds * 1000)
+      await this.setTime(current, newTime)
+    },
+
+    async allocateParties(hints) {
+      return Promise.all(
+        hints.map((hint) =>
+          admin.allocateParty({ partyIdHint: hint }),
+        ),
+      )
+    },
+  }
+}

package/src/clients/index.ts

@@ -0,0 +1,19 @@
+export {
+  createLedgerClient,
+  type LedgerClient,
+  type LedgerClientConfig,
+  type CommandOptions,
+  type QueryOptions,
+} from './createLedgerClient.js'
+
+export {
+  createAdminClient,
+  type AdminClient,
+  type AdminClientConfig,
+} from './createAdminClient.js'
+
+export {
+  createTestClient,
+  type TestClient,
+  type TestClientConfig,
+} from './createTestClient.js'

package/src/codegen/index.ts

@@ -0,0 +1,6 @@
+export type {
+  ChoiceDescriptor,
+  TemplateDescriptor,
+  InferPayload,
+  InferChoiceArgs,
+} from './types.js'

package/src/codegen/types.ts

@@ -0,0 +1,51 @@
+/**
+ * Runtime types for cantonjs codegen output.
+ *
+ * Generated code imports these types to describe templates and choices.
+ * The core library uses them for type-safe contract operations.
+ */
+
+/** Describes a choice on a template. */
+export type ChoiceDescriptor<
+  TArgs extends Record<string, unknown> = Record<string, unknown>,
+  _TResult = unknown,
+> = {
+  readonly name: string
+  readonly _args?: TArgs
+}
+
+/** Describes a template with its payload type and available choices. */
+export type TemplateDescriptor<
+  TPayload extends Record<string, unknown> = Record<string, unknown>,
+  TChoices extends Record<string, ChoiceDescriptor> = Record<string, ChoiceDescriptor>,
+> = {
+  readonly templateId: string
+  readonly choices: TChoices
+  readonly _payload?: TPayload
+}
+
+/**
+ * Extract the payload type from a TemplateDescriptor.
+ *
+ * @example
+ * ```typescript
+ * type AssetPayload = InferPayload<typeof Asset>
+ * // { readonly owner: string; readonly value: string }
+ * ```
+ */
+export type InferPayload<T extends TemplateDescriptor> =
+  T extends TemplateDescriptor<infer P, Record<string, ChoiceDescriptor>> ? P : never
+
+/**
+ * Extract the choice argument type for a specific choice.
+ *
+ * @example
+ * ```typescript
+ * type TransferArgs = InferChoiceArgs<typeof Asset, 'Transfer'>
+ * // { readonly newOwner: string }
+ * ```
+ */
+export type InferChoiceArgs<
+  T extends TemplateDescriptor,
+  C extends keyof T['choices'],
+> = T['choices'][C] extends ChoiceDescriptor<infer A> ? A : never

package/src/errors/auth.ts

@@ -0,0 +1,33 @@
+import { CantonjsError, type ErrorCode } from './base.js'
+
+/** JWT token has expired. */
+export class TokenExpiredError extends CantonjsError {
+  readonly expiredAt: Date
+
+  constructor(expiredAt: Date) {
+    super('JWT token has expired', {
+      code: 'CJ2001' as ErrorCode,
+      metaMessages: [
+        `Token expired at: ${expiredAt.toISOString()}`,
+        'Generate a new token using cantonctl auth or your identity provider.',
+      ],
+    })
+    this.name = 'TokenExpiredError'
+    this.expiredAt = expiredAt
+  }
+}
+
+/** JWT token is invalid or malformed. */
+export class InvalidTokenError extends CantonjsError {
+  constructor(reason: string, options?: { cause?: Error }) {
+    super(`Invalid JWT token: ${reason}`, {
+      code: 'CJ2002' as ErrorCode,
+      cause: options?.cause,
+      metaMessages: [
+        'Ensure the token is a valid JWT with the required Canton claims.',
+        'Required scope: daml_ledger_api',
+      ],
+    })
+    this.name = 'InvalidTokenError'
+  }
+}

package/src/errors/base.ts

@@ -0,0 +1,83 @@
+/**
+ * Structured error hierarchy for cantonjs.
+ *
+ * Follows viem's BaseError pattern with walk(), docsPath, and metaMessages.
+ * Error code ranges are complementary to cantonctl's E1xxx-E8xxx system.
+ *
+ * cantonjs error ranges:
+ *   CJ1xxx — Transport errors (connection, HTTP, gRPC)
+ *   CJ2xxx — Authentication errors (JWT, token lifecycle)
+ *   CJ3xxx — Ledger errors (command rejection, contract not found)
+ *   CJ4xxx — Admin errors (party, user, package management)
+ *   CJ5xxx — Streaming errors (subscription, reconnection)
+ *   CJ6xxx — Codegen errors (type mismatch, generation failures)
+ */
+
+export type ErrorCode = `CJ${number}`
+
+export class CantonjsError extends Error {
+  readonly code: ErrorCode
+  readonly shortMessage: string
+  readonly docsPath?: string
+  readonly metaMessages?: readonly string[]
+  override readonly cause?: Error
+
+  constructor(shortMessage: string, options: CantonjsErrorOptions) {
+    const message = buildMessage(shortMessage, options)
+    super(message)
+    this.name = 'CantonjsError'
+    this.code = options.code
+    this.shortMessage = shortMessage
+    this.docsPath = options.docsPath
+    this.metaMessages = options.metaMessages
+    this.cause = options.cause
+  }
+
+  /**
+   * Walk the error cause chain, returning the first error matching the predicate.
+   * Useful for finding specific error types in nested cause chains.
+   */
+  walk(fn?: (error: Error) => boolean): Error | undefined {
+    if (fn === undefined) {
+      return this.cause
+    }
+    if (fn(this)) {
+      return this
+    }
+    if (this.cause instanceof CantonjsError) {
+      return this.cause.walk(fn)
+    }
+    if (this.cause !== undefined && fn(this.cause)) {
+      return this.cause
+    }
+    return undefined
+  }
+}
+
+export type CantonjsErrorOptions = {
+  readonly code: ErrorCode
+  readonly cause?: Error
+  readonly docsPath?: string
+  readonly metaMessages?: readonly string[]
+}
+
+function buildMessage(shortMessage: string, options: CantonjsErrorOptions): string {
+  const parts: string[] = [shortMessage]
+
+  if (options.metaMessages !== undefined && options.metaMessages.length > 0) {
+    parts.push('')
+    for (const meta of options.metaMessages) {
+      parts.push(`  ${meta}`)
+    }
+  }
+
+  if (options.docsPath !== undefined) {
+    parts.push('')
+    parts.push(`  Docs: ${options.docsPath}`)
+  }
+
+  parts.push('')
+  parts.push(`  Error code: ${options.code}`)
+
+  return parts.join('\n')
+}

package/src/errors/index.ts

@@ -0,0 +1,5 @@
+export { CantonjsError, type ErrorCode, type CantonjsErrorOptions } from './base.js'
+export { ConnectionError, HttpError, GrpcError, TimeoutError } from './transport.js'
+export { CommandRejectedError, ContractNotFoundError, AuthorizationError } from './ledger.js'
+export { TokenExpiredError, InvalidTokenError } from './auth.js'
+export { WebSocketError, StreamClosedError, ReconnectFailedError } from './streaming.js'