@caypo/canton-sdk 0.1.0

package/src/canton/holdings.ts

@@ -0,0 +1,90 @@
+/**
+ * Holding selection algorithm for USDCx transfers.
+ *
+ * Canton uses a UTXO-like model: a party can have multiple Holding contracts.
+ * When transferring, we need to select holdings that cover the required amount.
+ */
+
+import { addAmounts, compareAmounts } from "./amount.js";
+
+export interface USDCxHolding {
+  contractId: string;
+  owner: string;
+  amount: string;
+  templateId: string;
+}
+
+export interface HoldingSelection {
+  type: "single" | "merge-then-transfer";
+  contractIds: string[];
+}
+
+export class InsufficientBalanceError extends Error {
+  readonly available: string;
+  readonly required: string;
+
+  constructor(available: string, required: string) {
+    super(`Insufficient balance: have ${available}, need ${required}`);
+    this.name = "InsufficientBalanceError";
+    this.available = available;
+    this.required = required;
+  }
+}
+
+/**
+ * Select holdings that cover the required amount.
+ *
+ * Strategy:
+ * 1. Sort holdings by amount descending.
+ * 2. Look for a single holding >= required (prefer smallest sufficient one).
+ * 3. If none, accumulate multiple holdings until we cover the amount.
+ * 4. Throw InsufficientBalanceError if total < required.
+ */
+export function selectHoldings(
+  holdings: USDCxHolding[],
+  requiredAmount: string,
+): HoldingSelection {
+  if (holdings.length === 0) {
+    throw new InsufficientBalanceError("0", requiredAmount);
+  }
+
+  // Sort descending by amount
+  const sorted = [...holdings].sort((a, b) => compareAmounts(b.amount, a.amount));
+
+  // 1. Try to find a single holding that covers the amount.
+  //    Among all sufficient holdings, pick the smallest (best fit).
+  let bestSingle: USDCxHolding | null = null;
+  for (const h of sorted) {
+    if (compareAmounts(h.amount, requiredAmount) >= 0) {
+      // This one is sufficient — it might be the best fit
+      // since we iterate descending, each subsequent one is smaller but still sufficient
+      bestSingle = h;
+    }
+  }
+
+  if (bestSingle) {
+    return {
+      type: "single",
+      contractIds: [bestSingle.contractId],
+    };
+  }
+
+  // 2. Accumulate multiple holdings (greedy — take largest first)
+  let accumulated = "0";
+  const selected: string[] = [];
+
+  for (const h of sorted) {
+    selected.push(h.contractId);
+    accumulated = addAmounts(accumulated, h.amount);
+
+    if (compareAmounts(accumulated, requiredAmount) >= 0) {
+      return {
+        type: "merge-then-transfer",
+        contractIds: selected,
+      };
+    }
+  }
+
+  // 3. Not enough
+  throw new InsufficientBalanceError(accumulated, requiredAmount);
+}

package/src/canton/index.ts

@@ -0,0 +1,51 @@
+export { CantonClient } from "./client.js";
+export { CantonApiError, CantonAuthError, CantonTimeoutError } from "./errors.js";
+export type {
+  ActiveContract,
+  ActiveContractsRequest,
+  AnyPartyFilter,
+  ArchivedEvent,
+  CantonClientConfig,
+  CantonErrorCode,
+  Command,
+  CreateCommand,
+  CreatedEvent,
+  EventFormat,
+  ExerciseCommand,
+  ExercisedEvent,
+  FlatTransaction,
+  IdentifierFilter,
+  LedgerEndResponse,
+  LedgerError,
+  PartyDetails,
+  PartyFilter,
+  PartyLocalMetadata,
+  QueryActiveContractsParams,
+  SubmitAndWaitRequest,
+  SubmitAndWaitResponse,
+  SubmitParams,
+  TransactionResponse,
+  TransactionTree,
+  TransactionTreeEvent,
+} from "./types.js";
+export {
+  addAmounts,
+  compareAmounts,
+  isValidAmount,
+  subtractAmounts,
+  toCantonAmount,
+} from "./amount.js";
+export {
+  InsufficientBalanceError,
+  selectHoldings,
+  type HoldingSelection,
+  type USDCxHolding,
+} from "./holdings.js";
+export {
+  USDCxService,
+  USDCX_HOLDING_TEMPLATE_ID,
+  USDCX_INSTRUMENT_ID,
+  TRANSFER_FACTORY_TEMPLATE_ID,
+  type TransferParams,
+  type TransferResult,
+} from "./usdcx.js";

package/src/canton/types.ts

@@ -0,0 +1,214 @@
+/**
+ * Canton JSON Ledger API v2 — Type Definitions
+ *
+ * Verified against: docs.digitalasset.com/build/3.5, Canton OpenAPI spec v3.3.0
+ * Default port: 7575
+ */
+
+// ---------------------------------------------------------------------------
+// Party
+// ---------------------------------------------------------------------------
+
+export interface PartyLocalMetadata {
+  resourceVersion: string;
+  annotations: Record<string, string>;
+}
+
+export interface PartyDetails {
+  party: string; // e.g., "Alice::122084768362d0ce21f1ffec870e55e365a292cdf8f54c5c38ad7775b9bdd462e141"
+  isLocal: boolean;
+  localMetadata: PartyLocalMetadata;
+  identityProviderId: string;
+}
+
+// ---------------------------------------------------------------------------
+// Commands
+// ---------------------------------------------------------------------------
+
+export interface CreateCommand {
+  CreateCommand: {
+    templateId: string; // "#package-name:Module:Template" or "packagehash:Module:Template"
+    createArguments: Record<string, unknown>;
+  };
+}
+
+export interface ExerciseCommand {
+  ExerciseCommand: {
+    templateId: string;
+    contractId: string;
+    choice: string;
+    choiceArgument: Record<string, unknown>;
+  };
+}
+
+export type Command = CreateCommand | ExerciseCommand;
+
+// ---------------------------------------------------------------------------
+// Submit and Wait
+// ---------------------------------------------------------------------------
+
+export interface SubmitAndWaitRequest {
+  commands: Command[];
+  userId: string;
+  commandId: string;
+  actAs: string[];
+  readAs?: string[];
+}
+
+export interface SubmitAndWaitResponse {
+  updateId: string;
+  completionOffset: number;
+}
+
+// ---------------------------------------------------------------------------
+// Events
+// ---------------------------------------------------------------------------
+
+export interface CreatedEvent {
+  contractId: string;
+  templateId: string;
+  createArgument: Record<string, unknown>;
+  witnessParties: string[];
+  signatories: string[];
+  observers: string[];
+}
+
+export interface ArchivedEvent {
+  contractId: string;
+  templateId: string;
+  witnessParties: string[];
+}
+
+export interface ExercisedEvent {
+  contractId: string;
+  templateId: string;
+  choice: string;
+  choiceArgument: Record<string, unknown>;
+  exerciseResult: unknown;
+  actingParties: string[];
+  childEvents: TransactionTreeEvent[];
+}
+
+export type TransactionTreeEvent =
+  | { createdEvent: CreatedEvent }
+  | { exercisedEvent: ExercisedEvent };
+
+// ---------------------------------------------------------------------------
+// Transactions
+// ---------------------------------------------------------------------------
+
+export interface TransactionTree {
+  updateId: string;
+  commandId: string;
+  effectiveAt: string;
+  offset: number;
+  eventsById: Record<string, TransactionTreeEvent>;
+  rootEventIds: string[];
+}
+
+export interface FlatTransaction {
+  updateId: string;
+  commandId: string;
+  effectiveAt: string;
+  offset: number;
+  events: Array<{ createdEvent?: CreatedEvent; archivedEvent?: ArchivedEvent }>;
+}
+
+export interface TransactionResponse {
+  transaction: FlatTransaction;
+}
+
+// ---------------------------------------------------------------------------
+// Active Contracts
+// ---------------------------------------------------------------------------
+
+export interface IdentifierFilter {
+  identifierFilter:
+    | { TemplateFilter: { value: { templateId: string } } }
+    | { WildcardFilter: { value: { includeCreatedEventBlob?: boolean } } };
+}
+
+export interface PartyFilter {
+  cumulative: IdentifierFilter[];
+}
+
+export interface AnyPartyFilter {
+  cumulative: IdentifierFilter[];
+}
+
+export interface EventFormat {
+  filtersByParty?: Record<string, PartyFilter>;
+  filtersForAnyParty?: AnyPartyFilter;
+  verbose?: boolean;
+}
+
+export interface ActiveContractsRequest {
+  eventFormat: EventFormat;
+  activeAtOffset: number;
+}
+
+export interface ActiveContract {
+  contractId: string;
+  templateId: string;
+  createArgument: Record<string, unknown>;
+  createdAt: string;
+  signatories: string[];
+  observers: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Ledger State
+// ---------------------------------------------------------------------------
+
+export interface LedgerEndResponse {
+  offset: number;
+}
+
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+
+export type CantonErrorCode =
+  | "INVALID_ARGUMENT"
+  | "NOT_FOUND"
+  | "PERMISSION_DENIED"
+  | "ALREADY_EXISTS"
+  | "FAILED_PRECONDITION"
+  | "UNAVAILABLE"
+  | string;
+
+export interface LedgerError {
+  cause: string;
+  code: CantonErrorCode;
+  context: Record<string, string>;
+  errorCategory: number;
+  grpcCodeValue: number;
+}
+
+// ---------------------------------------------------------------------------
+// Client Config
+// ---------------------------------------------------------------------------
+
+export interface CantonClientConfig {
+  ledgerUrl: string; // e.g., "http://localhost:7575"
+  token: string; // JWT bearer token
+  userId: string; // Ledger API user ID
+  timeout?: number; // Request timeout in ms (default: 30000)
+}
+
+// ---------------------------------------------------------------------------
+// Client Method Params (excluding userId, which comes from config)
+// ---------------------------------------------------------------------------
+
+export interface SubmitParams {
+  commands: Command[];
+  commandId: string;
+  actAs: string[];
+  readAs?: string[];
+}
+
+export interface QueryActiveContractsParams {
+  filtersByParty?: Record<string, PartyFilter>;
+  filtersForAnyParty?: AnyPartyFilter;
+  activeAtOffset: number;
+}

package/src/canton/usdcx.ts

@@ -0,0 +1,166 @@
+/**
+ * USDCx Operations — Query holdings, transfer, merge.
+ *
+ * Uses CIP-56 token standard:
+ * - Splice.Api.Token.HoldingV1:Holding for balance queries
+ * - TransferFactory_Transfer for 1-step transfers (requires TransferPreapproval)
+ */
+
+import { addAmounts, toCantonAmount } from "./amount.js";
+import type { CantonClient } from "./client.js";
+import { selectHoldings, type HoldingSelection, type USDCxHolding } from "./holdings.js";
+import type { SubmitAndWaitResponse } from "./types.js";
+
+/** CIP-56 Holding template ID — used for active contract queries */
+export const USDCX_HOLDING_TEMPLATE_ID = "Splice.Api.Token.HoldingV1:Holding";
+
+/** TransferFactory template ID for 1-step transfers */
+export const TRANSFER_FACTORY_TEMPLATE_ID = "Splice.Api.Token.TransferFactoryV1:TransferFactory";
+
+/** USDCx instrument identifier */
+export const USDCX_INSTRUMENT_ID = "USDCx";
+
+export interface TransferResult {
+  updateId: string;
+  completionOffset: number;
+  commandId: string;
+}
+
+export interface TransferParams {
+  recipient: string;
+  amount: string;
+  commandId?: string;
+}
+
+export class USDCxService {
+  constructor(
+    private readonly client: CantonClient,
+    private readonly partyId: string,
+  ) {}
+
+  /**
+   * Query all USDCx Holding contracts for this party.
+   */
+  async getHoldings(): Promise<USDCxHolding[]> {
+    const offset = await this.client.getLedgerEnd();
+
+    const contracts = await this.client.queryActiveContracts({
+      filtersByParty: {
+        [this.partyId]: {
+          cumulative: [
+            {
+              identifierFilter: {
+                TemplateFilter: {
+                  value: { templateId: USDCX_HOLDING_TEMPLATE_ID },
+                },
+              },
+            },
+          ],
+        },
+      },
+      activeAtOffset: offset,
+    });
+
+    return contracts.map((c) => ({
+      contractId: c.contractId,
+      owner: (c.createArgument.owner as string) ?? this.partyId,
+      amount: c.createArgument.amount as string,
+      templateId: c.templateId,
+    }));
+  }
+
+  /**
+   * Calculate total USDCx balance by summing all holding amounts.
+   * Returns a string with up to 10 decimal places.
+   */
+  async getBalance(): Promise<string> {
+    const holdings = await this.getHoldings();
+
+    if (holdings.length === 0) {
+      return "0";
+    }
+
+    let total = "0";
+    for (const h of holdings) {
+      total = addAmounts(total, h.amount);
+    }
+
+    return total;
+  }
+
+  /**
+   * Transfer USDCx using TransferFactory_Transfer (1-step).
+   * Requires the recipient to have an active TransferPreapproval.
+   */
+  async transfer(params: TransferParams): Promise<TransferResult> {
+    const commandId = params.commandId ?? crypto.randomUUID();
+    const amount = toCantonAmount(params.amount);
+
+    // 1. Query holdings
+    const holdings = await this.getHoldings();
+
+    // 2. Select holdings covering the amount (throws InsufficientBalanceError if not enough)
+    const selection: HoldingSelection = selectHoldings(holdings, params.amount);
+
+    // 3. Build and submit ExerciseCommand for TransferFactory_Transfer
+    const result: SubmitAndWaitResponse = await this.client.submitAndWait({
+      commands: [
+        {
+          ExerciseCommand: {
+            templateId: TRANSFER_FACTORY_TEMPLATE_ID,
+            contractId: selection.contractIds[0],
+            choice: "TransferFactory_Transfer",
+            choiceArgument: {
+              sender: this.partyId,
+              receiver: params.recipient,
+              amount,
+              instrumentId: USDCX_INSTRUMENT_ID,
+              inputHoldingCids: selection.contractIds,
+              meta: {},
+            },
+          },
+        },
+      ],
+      commandId,
+      actAs: [this.partyId],
+      readAs: [this.partyId],
+    });
+
+    return {
+      updateId: result.updateId,
+      completionOffset: result.completionOffset,
+      commandId,
+    };
+  }
+
+  /**
+   * Merge multiple holdings into fewer UTXOs.
+   * Returns the commandId of the merge transaction.
+   */
+  async mergeHoldings(holdingCids: string[]): Promise<string> {
+    if (holdingCids.length < 2) {
+      throw new Error("Need at least 2 holdings to merge");
+    }
+
+    const commandId = crypto.randomUUID();
+
+    await this.client.submitAndWait({
+      commands: [
+        {
+          ExerciseCommand: {
+            templateId: USDCX_HOLDING_TEMPLATE_ID,
+            contractId: holdingCids[0],
+            choice: "Merge",
+            choiceArgument: {
+              holdingCids: holdingCids.slice(1),
+            },
+          },
+        },
+      ],
+      commandId,
+      actAs: [this.partyId],
+    });
+
+    return commandId;
+  }
+}

package/src/index.ts

@@ -0,0 +1,97 @@
+/**
+ * @caypo/canton-sdk — Core SDK for Canton Network.
+ * JSON Ledger API v2 client, USDCx operations, agent accounts.
+ */
+
+export { MPP_CANTON_VERSION } from "@caypo/mpp-canton";
+
+export const CANTON_SDK_VERSION = "0.1.0";
+
+export const DEFAULT_LEDGER_PORT = 7575;
+
+// Canton JSON Ledger API v2 client
+export { CantonClient } from "./canton/client.js";
+export { CantonApiError, CantonAuthError, CantonTimeoutError } from "./canton/errors.js";
+export type {
+  ActiveContract,
+  ActiveContractsRequest,
+  AnyPartyFilter,
+  ArchivedEvent,
+  CantonClientConfig,
+  CantonErrorCode,
+  Command,
+  CreateCommand,
+  CreatedEvent,
+  EventFormat,
+  ExerciseCommand,
+  ExercisedEvent,
+  FlatTransaction,
+  IdentifierFilter,
+  LedgerEndResponse,
+  LedgerError,
+  PartyDetails,
+  PartyFilter,
+  PartyLocalMetadata,
+  QueryActiveContractsParams,
+  SubmitAndWaitRequest,
+  SubmitAndWaitResponse,
+  SubmitParams,
+  TransactionResponse,
+  TransactionTree,
+  TransactionTreeEvent,
+} from "./canton/types.js";
+
+// USDCx operations
+export {
+  USDCxService,
+  USDCX_HOLDING_TEMPLATE_ID,
+  USDCX_INSTRUMENT_ID,
+  TRANSFER_FACTORY_TEMPLATE_ID,
+} from "./canton/usdcx.js";
+export type { TransferParams, TransferResult } from "./canton/usdcx.js";
+
+// Amount utilities (string-based decimal arithmetic)
+export {
+  addAmounts,
+  compareAmounts,
+  isValidAmount,
+  subtractAmounts,
+  toCantonAmount,
+} from "./canton/amount.js";
+
+// Holding selection
+export { InsufficientBalanceError, selectHoldings } from "./canton/holdings.js";
+export type { HoldingSelection, USDCxHolding } from "./canton/holdings.js";
+
+// Wallet keystore
+export { Keystore } from "./wallet/keystore.js";
+export type { WalletData } from "./wallet/keystore.js";
+
+// Agent configuration
+export { loadConfig, saveConfig, DEFAULT_CONFIG } from "./wallet/config.js";
+export type {
+  AgentConfig,
+  TrafficConfig,
+  SafeguardsConfig,
+  MppConfig,
+} from "./wallet/config.js";
+
+// Safeguards
+export { SafeguardManager } from "./safeguards/manager.js";
+export type { SafeguardConfig, CheckResult } from "./safeguards/manager.js";
+
+// High-level agent
+export { CantonAgent } from "./agent.js";
+export type { CantonAgentConfig, WalletInfo } from "./agent.js";
+
+// Checking account
+export { CheckingAccount } from "./accounts/checking.js";
+export type { SendOptions, TransactionRecord } from "./accounts/checking.js";
+
+// Traffic manager
+export { TrafficManager } from "./traffic/manager.js";
+export type { TrafficBalance, AutoPurchaseConfig } from "./traffic/manager.js";
+
+// MPP pay client
+export { MppPayClient, parseWwwAuthenticate } from "./mpp/pay-client.js";
+export type { PayOptions, PayResult, PaymentChallenge } from "./mpp/pay-client.js";