cantonjs 0.0.1

package/src/transport/grpc.ts

@@ -0,0 +1,130 @@
+/**
+ * gRPC transport factory for Canton Ledger API V2.
+ *
+ * Uses a custom fetch-based adapter to translate Transport requests into
+ * gRPC-Web calls via ConnectRPC's HTTP/2 or HTTP/1.1 protocol. This keeps
+ * cantonjs zero-dependency — users bring their own `@connectrpc/connect-web`
+ * or `@connectrpc/connect-node` transport.
+ *
+ * Since Canton's JSON API V2 and gRPC API share the same semantics, this
+ * transport maps JSON API paths to gRPC service methods and re-encodes
+ * request/response bodies.
+ *
+ * Usage:
+ *   import { grpc } from 'cantonjs'
+ *   import { createGrpcWebTransport } from '@connectrpc/connect-web'
+ *
+ *   const transport = grpc({
+ *     url: 'http://localhost:7575',
+ *     grpcTransport: createGrpcWebTransport({ baseUrl: 'http://localhost:7575' }),
+ *   })
+ */
+
+import type { Transport, TransportRequest } from './types.js'
+
+/** Configuration for the gRPC transport. */
+export type GrpcTransportConfig = {
+  /** Base URL of the Canton node. */
+  readonly url: string
+  /** JWT Bearer token for authentication. */
+  readonly token?: string
+  /**
+   * A ConnectRPC transport instance (from @connectrpc/connect-web or connect-node).
+   * Injected to keep cantonjs zero-dependency.
+   */
+  readonly grpcTransport: GrpcTransportLike
+}
+
+/**
+ * Minimal interface for a ConnectRPC transport.
+ * Compatible with @connectrpc/connect's Transport type.
+ */
+export type GrpcTransportLike = {
+  readonly unary: (
+    service: unknown,
+    method: unknown,
+    signal: AbortSignal | undefined,
+    timeoutMs: number | undefined,
+    header: unknown,
+    message: unknown,
+  ) => Promise<{ readonly message: unknown }>
+}
+
+/**
+ * Create a gRPC transport for the Canton Ledger API.
+ *
+ * Requires @connectrpc/connect as a peer dependency (not bundled).
+ * Maps Transport requests to gRPC unary calls.
+ */
+export function grpc(config: GrpcTransportConfig): Transport {
+  const { url, token, grpcTransport } = config
+  const baseUrl = url.replace(/\/+$/, '')
+
+  return {
+    type: 'grpc',
+    url: baseUrl,
+
+    async request<TResponse = unknown>(args: TransportRequest): Promise<TResponse> {
+      const headers: Record<string, string> = {}
+      if (token !== undefined) {
+        headers['Authorization'] = `Bearer ${token}`
+      }
+
+      const result = await grpcTransport.unary(
+        pathToService(args.path),
+        pathToMethod(args.path),
+        args.signal,
+        args.timeout,
+        headers,
+        args.body ?? {},
+      )
+
+      return result.message as TResponse
+    },
+  }
+}
+
+/**
+ * Map a JSON API path to a gRPC service descriptor.
+ * In a full implementation, this would use generated service descriptors
+ * from Canton's protobuf definitions.
+ */
+function pathToService(path: string): { typeName: string } {
+  const segments = path.replace(/^\/v2\//, '').split('/')
+  const serviceMap: Record<string, string> = {
+    'commands': 'com.daml.ledger.api.v2.CommandService',
+    'interactive-submission': 'com.daml.ledger.api.v2.InteractiveSubmissionService',
+    'state': 'com.daml.ledger.api.v2.StateService',
+    'updates': 'com.daml.ledger.api.v2.UpdateService',
+    'events': 'com.daml.ledger.api.v2.EventQueryService',
+    'parties': 'com.daml.ledger.api.v2.PartyManagementService',
+    'users': 'com.daml.ledger.api.v2.UserManagementService',
+    'packages': 'com.daml.ledger.api.v2.PackageService',
+    'dars': 'com.daml.ledger.api.v2.PackageManagementService',
+    'version': 'com.daml.ledger.api.v2.VersionService',
+  }
+  const serviceName = serviceMap[segments[0] ?? ''] ?? 'unknown'
+  return { typeName: serviceName }
+}
+
+/**
+ * Map a JSON API path to a gRPC method descriptor.
+ */
+function pathToMethod(path: string): { name: string } {
+  const methodMap: Record<string, string> = {
+    '/v2/commands/submit-and-wait': 'SubmitAndWait',
+    '/v2/commands/submit-and-wait-for-transaction': 'SubmitAndWaitForTransaction',
+    '/v2/commands/submit-and-wait-for-reassignment': 'SubmitAndWaitForReassignment',
+    '/v2/interactive-submission/prepare': 'PrepareSubmission',
+    '/v2/interactive-submission/execute': 'ExecuteSubmission',
+    '/v2/state/active-contracts': 'GetActiveContracts',
+    '/v2/state/connected-synchronizers': 'GetConnectedSynchronizers',
+    '/v2/state/ledger-end': 'GetLedgerEnd',
+    '/v2/state/latest-pruned-offsets': 'GetLatestPrunedOffsets',
+    '/v2/updates/transaction-by-id': 'GetTransactionById',
+    '/v2/events/events-by-contract-id': 'GetEventsByContractId',
+    '/v2/version': 'GetLedgerApiVersion',
+  }
+  const methodName = methodMap[path] ?? path.split('/').pop() ?? 'unknown'
+  return { name: methodName }
+}

package/src/transport/index.ts

@@ -0,0 +1,2 @@
+export { jsonApi } from './json-api.js'
+export type { Transport, TransportConfig, TransportRequest, TransportFactory } from './types.js'

package/src/transport/json-api.ts

@@ -0,0 +1,83 @@
+/**
+ * JSON Ledger API V2 transport (HTTP).
+ *
+ * Primary transport for cantonjs. Communicates with Canton's JSON Ledger API
+ * via HTTP requests to /v2/* endpoints.
+ */
+
+import { ConnectionError, HttpError, TimeoutError } from '../errors/transport.js'
+import type { Transport, TransportConfig, TransportRequest } from './types.js'
+
+const DEFAULT_TIMEOUT = 30_000
+
+export function jsonApi(config: TransportConfig): Transport {
+  const { url, token, timeout = DEFAULT_TIMEOUT, fetchFn = globalThis.fetch } = config
+
+  const baseUrl = url.replace(/\/+$/, '')
+
+  return {
+    type: 'json-api',
+    url: baseUrl,
+
+    async request<TResponse = unknown>(args: TransportRequest): Promise<TResponse> {
+      const requestUrl = `${baseUrl}${args.path}`
+      const headers: Record<string, string> = {
+        'Content-Type': 'application/json',
+        ...args.headers,
+      }
+
+      if (token !== undefined) {
+        headers['Authorization'] = `Bearer ${token}`
+      }
+
+      const controller = new AbortController()
+      const timeoutMs = args.timeout ?? timeout
+
+      const timeoutId = setTimeout(() => controller.abort(), timeoutMs)
+
+      if (args.signal !== undefined) {
+        args.signal.addEventListener('abort', () => controller.abort(), { once: true })
+      }
+
+      try {
+        const response = await fetchFn(requestUrl, {
+          method: args.method,
+          headers,
+          body: args.body !== undefined ? JSON.stringify(args.body) : undefined,
+          signal: controller.signal,
+        })
+
+        clearTimeout(timeoutId)
+
+        if (!response.ok) {
+          const body = await response.text().catch(() => undefined)
+          throw new HttpError(response.status, response.statusText, { body })
+        }
+
+        const contentType = response.headers.get('content-type')
+        if (contentType?.includes('application/json')) {
+          return (await response.json()) as TResponse
+        }
+
+        return (await response.text()) as TResponse
+      } catch (error) {
+        clearTimeout(timeoutId)
+
+        if (error instanceof HttpError) {
+          throw error
+        }
+
+        if (error instanceof DOMException && error.name === 'AbortError') {
+          if (args.signal?.aborted) {
+            throw error
+          }
+          throw new TimeoutError(timeoutMs)
+        }
+
+        throw new ConnectionError(baseUrl, {
+          cause: error instanceof Error ? error : new Error(String(error)),
+        })
+      }
+    },
+  }
+}

package/src/transport/types.ts

@@ -0,0 +1,39 @@
+/**
+ * Transport abstraction for Canton API communication.
+ *
+ * Inspired by viem's transport pattern: clients are instantiated with a
+ * transport that handles the actual request execution. This separates
+ * client logic from communication concerns.
+ */
+
+/** A transport handles sending requests to a Canton node. */
+export type Transport = {
+  readonly type: string
+  readonly url: string
+  request: <TResponse = unknown>(args: TransportRequest) => Promise<TResponse>
+}
+
+/** A request to be sent via transport. */
+export type TransportRequest = {
+  method: 'GET' | 'POST' | 'PATCH' | 'DELETE'
+  path: string
+  body?: unknown
+  headers?: Record<string, string>
+  signal?: AbortSignal
+  timeout?: number
+}
+
+/** Configuration shared by all transport types. */
+export type TransportConfig = {
+  /** Base URL of the Canton node. */
+  readonly url: string
+  /** JWT Bearer token for authentication. */
+  readonly token?: string
+  /** Request timeout in milliseconds. Default: 30000. */
+  readonly timeout?: number
+  /** Custom fetch implementation (for testing or environments without global fetch). */
+  readonly fetchFn?: typeof fetch
+}
+
+/** Factory function type for creating transports. */
+export type TransportFactory = (config: TransportConfig) => Transport

package/src/types/command.ts

@@ -0,0 +1,123 @@
+/**
+ * Canton command types.
+ *
+ * Commands are the units of submission to the ledger. Each command atomically
+ * creates contracts or exercises choices on existing contracts.
+ *
+ * Commands on the wire use tagged discriminated unions:
+ *   { "CreateCommand": {...} } | { "ExerciseCommand": {...} } | ...
+ */
+
+/**
+ * Ledger offset. int64 in Canton 3.4+.
+ * 0 = empty ledger, positive = absolute offset.
+ */
+export type LedgerOffset = number
+
+/** Wire format for a create command. */
+export type CreateCommand = {
+  readonly templateId: string
+  readonly createArguments: Record<string, unknown>
+}
+
+/** Wire format for an exercise command. */
+export type ExerciseCommand = {
+  readonly templateId: string
+  readonly contractId: string
+  readonly choice: string
+  readonly choiceArgument: Record<string, unknown>
+}
+
+/** Wire format for an exercise-by-key command. */
+export type ExerciseByKeyCommand = {
+  readonly templateId: string
+  readonly contractKey: unknown
+  readonly choice: string
+  readonly choiceArgument: Record<string, unknown>
+}
+
+/** Wire format for a create-and-exercise command. */
+export type CreateAndExerciseCommand = {
+  readonly templateId: string
+  readonly createArguments: Record<string, unknown>
+  readonly choice: string
+  readonly choiceArgument: Record<string, unknown>
+}
+
+/** Tagged command union as it appears on the wire. */
+export type TaggedCommand =
+  | { readonly CreateCommand: CreateCommand }
+  | { readonly ExerciseCommand: ExerciseCommand }
+  | { readonly ExerciseByKeyCommand: ExerciseByKeyCommand }
+  | { readonly CreateAndExerciseCommand: CreateAndExerciseCommand }
+
+/** Full JsCommands request body. */
+export type JsCommands = {
+  readonly commands: readonly TaggedCommand[]
+  readonly commandId: string
+  readonly actAs: readonly string[]
+  readonly userId?: string
+  readonly readAs?: readonly string[]
+  readonly workflowId?: string
+  readonly deduplicationPeriod?: DeduplicationPeriod
+  readonly submissionId?: string
+  readonly synchronizerId?: string
+}
+
+/** Deduplication period (tagged union). */
+export type DeduplicationPeriod =
+  | { readonly DeduplicationDuration: { readonly seconds: number; readonly nanos?: number } }
+  | { readonly DeduplicationOffset: { readonly value: number } }
+  | { readonly Empty: Record<string, never> }
+
+/** Submit-and-wait response. */
+export type SubmitAndWaitResponse = {
+  readonly updateId: string
+  readonly completionOffset: number
+}
+
+/** Transaction shape for queries. */
+export type TransactionShape =
+  | 'TRANSACTION_SHAPE_ACS_DELTA'
+  | 'TRANSACTION_SHAPE_LEDGER_EFFECTS'
+  | 'TRANSACTION_SHAPE_UNSPECIFIED'
+
+/** Event format for filtering. */
+export type EventFormat = {
+  readonly filtersByParty?: Record<string, { readonly cumulative: readonly CumulativeFilter[] }>
+  readonly filtersForAnyParty?: { readonly cumulative: readonly CumulativeFilter[] }
+  readonly verbose?: boolean
+}
+
+/** Cumulative filter entry. */
+export type CumulativeFilter = {
+  readonly identifierFilter: IdentifierFilter
+}
+
+/** Identifier filter (tagged union). */
+export type IdentifierFilter =
+  | {
+      readonly TemplateFilter: {
+        readonly value: {
+          readonly templateId: string
+          readonly includeCreatedEventBlob?: boolean
+        }
+      }
+    }
+  | {
+      readonly InterfaceFilter: {
+        readonly value: {
+          readonly interfaceId: string
+          readonly includeInterfaceView?: boolean
+          readonly includeCreatedEventBlob?: boolean
+        }
+      }
+    }
+  | { readonly WildcardFilter: { readonly value: { readonly includeCreatedEventBlob?: boolean } } }
+  | { readonly Empty: Record<string, never> }
+
+/** Transaction format for queries. */
+export type TransactionFormat = {
+  readonly transactionShape: TransactionShape
+  readonly eventFormat: EventFormat
+}

package/src/types/contract.ts

@@ -0,0 +1,101 @@
+/**
+ * Core Canton contract types.
+ *
+ * Canton uses a UTXO model: contracts are created and archived, never mutated.
+ * Each contract is identified by a unique ContractId and belongs to a template.
+ *
+ * Events on the wire use tagged discriminated unions:
+ *   { "CreatedEvent": {...} } | { "ArchivedEvent": {...} } | { "ExercisedEvent": {...} }
+ */
+
+/** Unique identifier for a contract instance on the ledger. */
+export type ContractId<T = unknown> = string & { readonly __contractId: T }
+
+/**
+ * Template identifier string.
+ * Supports two formats:
+ *   - `#package-name:Module:Entity` (preferred, package-name reference)
+ *   - `packageId:Module:Entity` (deprecated package-id reference)
+ */
+export type TemplateId = string & { readonly __templateId: true }
+
+/** A created event from the ledger (wire format). */
+export type CreatedEvent = {
+  readonly offset: number
+  readonly nodeId: number
+  readonly contractId: string
+  readonly templateId: string
+  readonly packageName: string
+  readonly representativePackageId: string
+  readonly createArgument: Record<string, unknown>
+  readonly signatories: readonly string[]
+  readonly witnessParties: readonly string[]
+  readonly acsDelta: boolean
+  readonly createdAt: string
+  readonly contractKey?: Record<string, unknown>
+  readonly createdEventBlob?: string
+  readonly interfaceViews?: readonly InterfaceView[]
+  readonly observers?: readonly string[]
+}
+
+/** An archived event from the ledger (wire format). */
+export type ArchivedEvent = {
+  readonly offset: number
+  readonly nodeId: number
+  readonly contractId: string
+  readonly templateId: string
+  readonly packageName: string
+  readonly witnessParties: readonly string[]
+  readonly implementedInterfaces?: readonly string[]
+}
+
+/** An exercised event from a transaction tree (wire format). */
+export type ExercisedEvent = {
+  readonly offset: number
+  readonly nodeId: number
+  readonly contractId: string
+  readonly templateId: string
+  readonly choice: string
+  readonly choiceArgument: Record<string, unknown>
+  readonly consuming: boolean
+  readonly lastDescendantNodeId: number
+  readonly packageName: string
+  readonly acsDelta: boolean
+  readonly actingParties: readonly string[]
+  readonly witnessParties: readonly string[]
+  readonly interfaceId?: string
+  readonly exerciseResult?: unknown
+  readonly implementedInterfaces?: readonly string[]
+}
+
+/** Interface view attached to a created event. */
+export type InterfaceView = {
+  readonly interfaceId: string
+  readonly viewValue: Record<string, unknown>
+}
+
+/**
+ * Tagged event union as it appears on the wire.
+ * Canton uses { "CreatedEvent": {...} } | { "ArchivedEvent": {...} } | ...
+ */
+export type TaggedEvent =
+  | { readonly CreatedEvent: CreatedEvent }
+  | { readonly ArchivedEvent: ArchivedEvent }
+  | { readonly ExercisedEvent: ExercisedEvent }
+
+/** A contract from the active contract set. */
+export type ActiveContract = {
+  readonly createdEvent: CreatedEvent
+  readonly synchronizerId: string
+  readonly reassignmentCounter: number
+}
+
+/**
+ * Tagged contract entry from active contracts query.
+ * { "JsActiveContract": ... } | { "JsEmpty": {} } | ...
+ */
+export type ContractEntry =
+  | { readonly JsActiveContract: ActiveContract }
+  | { readonly JsEmpty: Record<string, never> }
+  | { readonly JsIncompleteAssigned: unknown }
+  | { readonly JsIncompleteUnassigned: unknown }

package/src/types/idp.ts

@@ -0,0 +1,31 @@
+/**
+ * Canton Identity Provider (IDP) configuration types.
+ *
+ * Identity providers allow delegating user authentication to external
+ * OpenID Connect providers (e.g., Auth0, Okta, Keycloak).
+ */
+
+import type { ObjectMeta } from './party.js'
+
+/** An identity provider configuration (wire format). */
+export type IdentityProviderConfig = {
+  readonly identityProviderId: string
+  readonly isDeactivated?: boolean
+  readonly issuer: string
+  readonly jwksUrl: string
+  readonly audience?: string
+  readonly metadata?: ObjectMeta
+}
+
+/** Request to create an identity provider. */
+export type CreateIdentityProviderRequest = {
+  readonly identityProviderConfig: IdentityProviderConfig
+}
+
+/** Request to update an identity provider. */
+export type UpdateIdentityProviderRequest = {
+  readonly identityProviderConfig: IdentityProviderConfig
+  readonly updateMask?: {
+    readonly paths: readonly string[]
+  }
+}

package/src/types/index.ts

@@ -0,0 +1,66 @@
+export type {
+  ContractId,
+  TemplateId,
+  CreatedEvent,
+  ArchivedEvent,
+  ExercisedEvent,
+  InterfaceView,
+  TaggedEvent,
+  ActiveContract,
+  ContractEntry,
+} from './contract.js'
+
+export type { Party, ObjectMeta, PartyDetails, AllocatePartyRequest } from './party.js'
+
+export type {
+  LedgerOffset,
+  CreateCommand,
+  ExerciseCommand,
+  ExerciseByKeyCommand,
+  CreateAndExerciseCommand,
+  TaggedCommand,
+  JsCommands,
+  DeduplicationPeriod,
+  SubmitAndWaitResponse,
+  TransactionShape,
+  EventFormat,
+  CumulativeFilter,
+  IdentifierFilter,
+  TransactionFormat,
+} from './command.js'
+
+export type {
+  JsTransaction,
+  OffsetCheckpoint,
+  TaggedUpdate,
+  UpdateFormat,
+} from './transaction.js'
+
+export type { User, Right, RightKind, CreateUserRequest } from './user.js'
+
+export type { PackageStatus, PackageDetails } from './package.js'
+
+export type {
+  IdentityProviderConfig,
+  CreateIdentityProviderRequest,
+  UpdateIdentityProviderRequest,
+} from './idp.js'
+
+export type {
+  PrepareSubmissionRequest,
+  PrepareSubmissionResponse,
+  ExecuteSubmissionRequest,
+  PartySignatures,
+  Signature,
+  SignatureFormat,
+} from './interactive.js'
+
+export type {
+  Reassignment,
+  ReassignmentEvent,
+  AssignedEvent,
+  UnassignedEvent,
+  ReassignmentCommand,
+  UnassignCommand,
+  AssignCommand,
+} from './reassignment.js'

package/src/types/interactive.ts

@@ -0,0 +1,53 @@
+/**
+ * Interactive submission types for external signing workflows.
+ *
+ * The interactive submission flow allows external signing of transactions:
+ * 1. Prepare — submit commands, get back a prepared transaction with hash
+ * 2. Sign — sign the hash externally (HSM, hardware wallet, etc.)
+ * 3. Execute — submit the signed transaction
+ *
+ * Canton 3.3+ uses hashing algorithm V2.
+ */
+
+import type { TaggedCommand } from './command.js'
+
+/** Request to prepare a transaction for external signing. */
+export type PrepareSubmissionRequest = {
+  readonly commands: readonly TaggedCommand[]
+  readonly commandId: string
+  readonly actAs: readonly string[]
+  readonly readAs?: readonly string[]
+  readonly workflowId?: string
+  readonly synchronizerId?: string
+  readonly submissionId?: string
+}
+
+/** Response from preparing a transaction — contains the hash to sign. */
+export type PrepareSubmissionResponse = {
+  readonly preparedTransaction: string
+  readonly preparedTransactionHash: string
+  readonly hashingSchemeVersion: string
+}
+
+/** Request to execute a previously prepared and signed transaction. */
+export type ExecuteSubmissionRequest = {
+  readonly preparedTransaction: string
+  readonly partySignatures: readonly PartySignatures[]
+  readonly submissionId?: string
+}
+
+/** Signatures from a party for a prepared transaction. */
+export type PartySignatures = {
+  readonly party: string
+  readonly signatures: readonly Signature[]
+}
+
+/** A cryptographic signature. */
+export type Signature = {
+  readonly format: SignatureFormat
+  readonly signature: string
+  readonly signedBy: string
+}
+
+/** Supported signature formats. */
+export type SignatureFormat = 'RAW'

package/src/types/package.ts

@@ -0,0 +1,16 @@
+/**
+ * Canton package management types.
+ *
+ * Packages (DARs/DALFs) contain Daml code compiled for the ledger.
+ */
+
+/** Status of a package on the ledger. */
+export type PackageStatus = 'REGISTERED' | 'UNKNOWN'
+
+/** Details about a known package. */
+export type PackageDetails = {
+  readonly packageId: string
+  readonly packageSize: number
+  readonly sourceDescription: string
+  readonly knownSince: string
+}

package/src/types/party.ts

@@ -0,0 +1,33 @@
+/**
+ * Canton party types.
+ *
+ * In Canton, the fundamental identity unit is the party — not an account or address.
+ * A party's permissions are encoded in their JWT token.
+ * Party IDs follow the format: `Name::fingerprint`
+ */
+
+/** A party identifier on the Canton ledger. */
+export type Party = string & { readonly __party: true }
+
+/** Object metadata for Canton resources. */
+export type ObjectMeta = {
+  readonly resourceVersion?: string
+  readonly annotations?: Record<string, string>
+}
+
+/** Details about a known party (wire format). */
+export type PartyDetails = {
+  readonly party: string
+  readonly isLocal?: boolean
+  readonly localMetadata?: ObjectMeta
+  readonly identityProviderId?: string
+}
+
+/** Request to allocate a new party. */
+export type AllocatePartyRequest = {
+  readonly partyIdHint?: string
+  readonly localMetadata?: ObjectMeta
+  readonly identityProviderId?: string
+  readonly synchronizerId?: string
+  readonly userId?: string
+}