@caypo/canton-sdk 0.1.0

package/src/accounts/checking.ts

@@ -0,0 +1,118 @@
+/**
+ * CheckingAccount — high-level USDCx checking account.
+ *
+ * Wraps USDCxService with safeguard checks and transaction history.
+ */
+
+import type { CantonClient } from "../canton/client.js";
+import type { USDCxService } from "../canton/usdcx.js";
+import type { TransferResult } from "../canton/usdcx.js";
+import type { SafeguardManager } from "../safeguards/manager.js";
+
+export interface SendOptions {
+  memo?: string;
+  commandId?: string;
+}
+
+export interface TransactionRecord {
+  updateId: string;
+  commandId: string;
+  effectiveAt: string;
+  offset: number;
+  type: "send" | "receive" | "unknown";
+  amount?: string;
+  counterparty?: string;
+}
+
+export class CheckingAccount {
+  constructor(
+    private readonly usdcx: USDCxService,
+    private readonly safeguards: SafeguardManager,
+    private readonly client: CantonClient,
+    private readonly partyId: string,
+  ) {}
+
+  /** Get USDCx balance: total available and number of UTXO holdings. */
+  async balance(): Promise<{ available: string; holdingCount: number }> {
+    const holdings = await this.usdcx.getHoldings();
+    let available = "0";
+
+    // Use addAmounts from the holdings themselves
+    const { addAmounts } = await import("../canton/amount.js");
+    for (const h of holdings) {
+      available = addAmounts(available, h.amount);
+    }
+
+    return { available, holdingCount: holdings.length };
+  }
+
+  /**
+   * Send USDCx to a recipient.
+   * Checks safeguards before executing the transfer.
+   */
+  async send(
+    recipient: string,
+    amount: string,
+    opts?: SendOptions,
+  ): Promise<TransferResult> {
+    // 1. Check safeguards
+    const check = this.safeguards.check(amount);
+    if (!check.allowed) {
+      throw new Error(`Safeguard rejected: ${check.reason}`);
+    }
+
+    // 2. Execute transfer
+    const result = await this.usdcx.transfer({
+      recipient,
+      amount,
+      commandId: opts?.commandId,
+    });
+
+    // 3. Record spend
+    this.safeguards.recordSpend(amount);
+
+    return result;
+  }
+
+  /** Party ID for receiving payments. */
+  address(): string {
+    return this.partyId;
+  }
+
+  /**
+   * Query transaction history via /v2/updates/flats.
+   * Returns recent flat transactions involving this party.
+   */
+  async history(opts?: { limit?: number }): Promise<TransactionRecord[]> {
+    const limit = opts?.limit ?? 20;
+    const offset = await this.client.getLedgerEnd();
+
+    // Query recent transactions using active contracts approach
+    // Note: full streaming history requires WebSocket /v2/updates/flats
+    // For now, return what we can derive from recent contract state
+    const contracts = await this.client.queryActiveContracts({
+      filtersByParty: {
+        [this.partyId]: {
+          cumulative: [
+            {
+              identifierFilter: {
+                WildcardFilter: { value: { includeCreatedEventBlob: false } },
+              },
+            },
+          ],
+        },
+      },
+      activeAtOffset: offset,
+    });
+
+    // Map contracts to transaction records (limited view — full history needs WebSocket streaming)
+    return contracts.slice(0, limit).map((c) => ({
+      updateId: "",
+      commandId: "",
+      effectiveAt: c.createdAt,
+      offset: 0,
+      type: "unknown" as const,
+      amount: typeof c.createArgument.amount === "string" ? c.createArgument.amount : undefined,
+    }));
+  }
+}

package/src/agent.ts

@@ -0,0 +1,132 @@
+/**
+ * CantonAgent — high-level entry point for the Canton SDK.
+ *
+ * Creates and wires together all sub-services:
+ * - CheckingAccount (USDCx balance, send, history)
+ * - SafeguardManager (tx limits, daily limits, lock)
+ * - TrafficManager (validator traffic budgets)
+ * - MppPayClient (HTTP 402 auto-pay)
+ */
+
+import { CheckingAccount } from "./accounts/checking.js";
+import { CantonClient } from "./canton/client.js";
+import { USDCxService } from "./canton/usdcx.js";
+import { MppPayClient } from "./mpp/pay-client.js";
+import { SafeguardManager } from "./safeguards/manager.js";
+import { TrafficManager } from "./traffic/manager.js";
+import {
+  loadConfig,
+  type AgentConfig,
+} from "./wallet/config.js";
+
+export interface WalletInfo {
+  address: string;
+  partyId: string;
+  network: string;
+}
+
+export interface CantonAgentConfig {
+  ledgerUrl?: string;
+  token?: string;
+  userId?: string;
+  partyId?: string;
+  network?: "mainnet" | "testnet" | "devnet";
+  configPath?: string;
+  safeguardsPath?: string;
+}
+
+export class CantonAgent {
+  readonly checking: CheckingAccount;
+  readonly safeguards: SafeguardManager;
+  readonly traffic: TrafficManager;
+  readonly mpp: MppPayClient;
+  readonly wallet: WalletInfo;
+
+  private readonly client: CantonClient;
+  private readonly usdcx: USDCxService;
+
+  private constructor(
+    client: CantonClient,
+    usdcx: USDCxService,
+    checking: CheckingAccount,
+    safeguards: SafeguardManager,
+    traffic: TrafficManager,
+    mpp: MppPayClient,
+    wallet: WalletInfo,
+  ) {
+    this.client = client;
+    this.usdcx = usdcx;
+    this.checking = checking;
+    this.safeguards = safeguards;
+    this.traffic = traffic;
+    this.mpp = mpp;
+    this.wallet = wallet;
+  }
+
+  /**
+   * Create a new CantonAgent from config.
+   *
+   * Loads configuration from ~/.caypo/config.json (or overrides),
+   * initializes all sub-services, and wires them together.
+   */
+  static async create(config?: CantonAgentConfig): Promise<CantonAgent> {
+    // 1. Load config (file + overrides)
+    const fileConfig = await loadConfig(config?.configPath);
+    const merged: AgentConfig = {
+      ...fileConfig,
+      ...(config?.ledgerUrl && { ledgerUrl: config.ledgerUrl }),
+      ...(config?.partyId && { partyId: config.partyId }),
+      ...(config?.userId && { userId: config.userId }),
+      ...(config?.network && { network: config.network }),
+    };
+
+    const token = config?.token ?? "";
+
+    // 2. Create low-level client
+    const client = new CantonClient({
+      ledgerUrl: merged.ledgerUrl,
+      token,
+      userId: merged.userId,
+    });
+
+    // 3. Create services
+    const usdcx = new USDCxService(client, merged.partyId);
+    const safeguards = await SafeguardManager.load(config?.safeguardsPath);
+    const traffic = new TrafficManager(client, merged.partyId);
+    const checking = new CheckingAccount(usdcx, safeguards, client, merged.partyId);
+    const mpp = new MppPayClient(usdcx, safeguards, merged.partyId, merged.network);
+
+    const wallet: WalletInfo = {
+      address: merged.partyId,
+      partyId: merged.partyId,
+      network: merged.network,
+    };
+
+    return new CantonAgent(client, usdcx, checking, safeguards, traffic, mpp, wallet);
+  }
+
+  /**
+   * Create a CantonAgent from explicit parameters (no file I/O).
+   * Useful for testing and programmatic setup.
+   */
+  static fromParams(params: {
+    client: CantonClient;
+    partyId: string;
+    network: string;
+    safeguards?: SafeguardManager;
+  }): CantonAgent {
+    const safeguards = params.safeguards ?? new SafeguardManager();
+    const usdcx = new USDCxService(params.client, params.partyId);
+    const traffic = new TrafficManager(params.client, params.partyId);
+    const checking = new CheckingAccount(usdcx, safeguards, params.client, params.partyId);
+    const mpp = new MppPayClient(usdcx, safeguards, params.partyId, params.network);
+
+    const wallet: WalletInfo = {
+      address: params.partyId,
+      partyId: params.partyId,
+      network: params.network,
+    };
+
+    return new CantonAgent(params.client, usdcx, checking, safeguards, traffic, mpp, wallet);
+  }
+}

package/src/canton/amount.ts

@@ -0,0 +1,167 @@
+/**
+ * String-based decimal arithmetic for Canton amounts.
+ *
+ * Canton uses Numeric 10 (up to 10 decimal places). USDCx has 6 meaningful decimals.
+ * ALL arithmetic is pure string manipulation — NO floating point.
+ */
+
+const AMOUNT_RE = /^\d+(\.\d+)?$/;
+
+/**
+ * Validate that a string is a valid non-negative decimal amount.
+ */
+export function isValidAmount(s: string): boolean {
+  return AMOUNT_RE.test(s);
+}
+
+/**
+ * Parse an amount string into integer and fractional digit arrays.
+ * Returns [intDigits, fracDigits] where each is a number[].
+ */
+function parse(s: string): [number[], number[]] {
+  const dot = s.indexOf(".");
+  const intPart = dot === -1 ? s : s.slice(0, dot);
+  const fracPart = dot === -1 ? "" : s.slice(dot + 1);
+  return [
+    intPart.split("").map(Number),
+    fracPart.split("").map(Number),
+  ];
+}
+
+/**
+ * Normalise two amount strings so their fractional parts have equal length.
+ * Returns [aParts, bParts, fracLen].
+ */
+function align(a: string, b: string): [number[], number[], number[], number[], number] {
+  const [aInt, aFrac] = parse(a);
+  const [bInt, bFrac] = parse(b);
+  const fracLen = Math.max(aFrac.length, bFrac.length);
+  while (aFrac.length < fracLen) aFrac.push(0);
+  while (bFrac.length < fracLen) bFrac.push(0);
+  // Also align integer parts to equal length by prepending zeros
+  const intLen = Math.max(aInt.length, bInt.length);
+  while (aInt.length < intLen) aInt.unshift(0);
+  while (bInt.length < intLen) bInt.unshift(0);
+  return [aInt, aFrac, bInt, bFrac, fracLen];
+}
+
+/**
+ * Strip trailing zeros from fractional part and leading zeros from integer part.
+ */
+function formatResult(intDigits: number[], fracDigits: number[]): string {
+  // Remove trailing zeros from fraction
+  while (fracDigits.length > 0 && fracDigits[fracDigits.length - 1] === 0) {
+    fracDigits.pop();
+  }
+  // Remove leading zeros from integer (keep at least one)
+  while (intDigits.length > 1 && intDigits[0] === 0) {
+    intDigits.shift();
+  }
+  const intStr = intDigits.join("");
+  return fracDigits.length > 0 ? `${intStr}.${fracDigits.join("")}` : intStr;
+}
+
+/**
+ * Compare two decimal amount strings.
+ * Returns -1 if a < b, 0 if a === b, 1 if a > b.
+ */
+export function compareAmounts(a: string, b: string): -1 | 0 | 1 {
+  const [aInt, aFrac, bInt, bFrac] = align(a, b);
+
+  // Compare integer parts digit by digit
+  for (let i = 0; i < aInt.length; i++) {
+    if (aInt[i] < bInt[i]) return -1;
+    if (aInt[i] > bInt[i]) return 1;
+  }
+
+  // Compare fractional parts digit by digit
+  for (let i = 0; i < aFrac.length; i++) {
+    if (aFrac[i] < bFrac[i]) return -1;
+    if (aFrac[i] > bFrac[i]) return 1;
+  }
+
+  return 0;
+}
+
+/**
+ * Add two decimal amount strings. Returns the sum as a string.
+ */
+export function addAmounts(a: string, b: string): string {
+  const [aInt, aFrac, bInt, bFrac, fracLen] = align(a, b);
+
+  // Combine into single digit arrays (integer + fractional)
+  const aAll = [...aInt, ...aFrac];
+  const bAll = [...bInt, ...bFrac];
+
+  const result: number[] = new Array(aAll.length).fill(0);
+  let carry = 0;
+
+  for (let i = aAll.length - 1; i >= 0; i--) {
+    const sum = aAll[i] + bAll[i] + carry;
+    result[i] = sum % 10;
+    carry = Math.floor(sum / 10);
+  }
+
+  if (carry > 0) {
+    result.unshift(carry);
+  }
+
+  // Split back into integer and fractional parts
+  const intDigits = result.slice(0, result.length - fracLen);
+  const fracDigits = result.slice(result.length - fracLen);
+
+  return formatResult(
+    intDigits.length === 0 ? [0] : intDigits,
+    fracDigits,
+  );
+}
+
+/**
+ * Subtract b from a. Both must be valid amounts and a >= b.
+ * Throws if a < b.
+ */
+export function subtractAmounts(a: string, b: string): string {
+  if (compareAmounts(a, b) < 0) {
+    throw new Error(`Cannot subtract: ${a} < ${b}`);
+  }
+
+  const [aInt, aFrac, bInt, bFrac, fracLen] = align(a, b);
+
+  const aAll = [...aInt, ...aFrac];
+  const bAll = [...bInt, ...bFrac];
+
+  const result: number[] = new Array(aAll.length).fill(0);
+  let borrow = 0;
+
+  for (let i = aAll.length - 1; i >= 0; i--) {
+    let diff = aAll[i] - bAll[i] - borrow;
+    if (diff < 0) {
+      diff += 10;
+      borrow = 1;
+    } else {
+      borrow = 0;
+    }
+    result[i] = diff;
+  }
+
+  const intDigits = result.slice(0, result.length - fracLen);
+  const fracDigits = result.slice(result.length - fracLen);
+
+  return formatResult(
+    intDigits.length === 0 ? [0] : intDigits,
+    fracDigits,
+  );
+}
+
+/**
+ * Pad (or truncate) a decimal string to exactly N decimal places.
+ * Default: 10 (Canton Numeric 10).
+ */
+export function toCantonAmount(s: string, decimals = 10): string {
+  const dot = s.indexOf(".");
+  const intPart = dot === -1 ? s : s.slice(0, dot);
+  const fracPart = dot === -1 ? "" : s.slice(dot + 1);
+
+  const padded = fracPart.padEnd(decimals, "0").slice(0, decimals);
+  return `${intPart}.${padded}`;
+}

package/src/canton/client.ts

@@ -0,0 +1,218 @@
+/**
+ * Canton JSON Ledger API v2 — Client
+ *
+ * All requests target config.ledgerUrl + path.
+ * All requests include Authorization: Bearer <token>.
+ * Errors are parsed into typed CantonApiError / CantonAuthError / CantonTimeoutError.
+ */
+
+import { CantonApiError, CantonAuthError, CantonTimeoutError } from "./errors.js";
+import type {
+  ActiveContract,
+  CantonClientConfig,
+  CreatedEvent,
+  LedgerError,
+  PartyDetails,
+  QueryActiveContractsParams,
+  SubmitAndWaitResponse,
+  SubmitParams,
+  TransactionResponse,
+  TransactionTree,
+} from "./types.js";
+
+const DEFAULT_TIMEOUT = 30_000;
+
+export class CantonClient {
+  private readonly ledgerUrl: string;
+  private readonly token: string;
+  private readonly userId: string;
+  private readonly timeout: number;
+
+  constructor(config: CantonClientConfig) {
+    this.ledgerUrl = config.ledgerUrl.replace(/\/+$/, "");
+    this.token = config.token;
+    this.userId = config.userId;
+    this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Command Submission
+  // ---------------------------------------------------------------------------
+
+  async submitAndWait(params: SubmitParams): Promise<SubmitAndWaitResponse> {
+    return this.request<SubmitAndWaitResponse>("POST", "/v2/commands/submit-and-wait", {
+      commands: params.commands,
+      userId: this.userId,
+      commandId: params.commandId,
+      actAs: params.actAs,
+      readAs: params.readAs,
+    });
+  }
+
+  async submitAndWaitForTransaction(params: SubmitParams): Promise<TransactionResponse> {
+    return this.request<TransactionResponse>(
+      "POST",
+      "/v2/commands/submit-and-wait-for-transaction",
+      {
+        commands: params.commands,
+        userId: this.userId,
+        commandId: params.commandId,
+        actAs: params.actAs,
+        readAs: params.readAs,
+      },
+    );
+  }
+
+  // ---------------------------------------------------------------------------
+  // Active Contract Queries
+  // ---------------------------------------------------------------------------
+
+  async queryActiveContracts(params: QueryActiveContractsParams): Promise<ActiveContract[]> {
+    const body = {
+      eventFormat: {
+        filtersByParty: params.filtersByParty,
+        filtersForAnyParty: params.filtersForAnyParty,
+        verbose: true,
+      },
+      activeAtOffset: params.activeAtOffset,
+    };
+
+    const response = await this.request<{
+      contractEntry?: Array<{ createdEvent?: CreatedEvent }>;
+    }>("POST", "/v2/state/active-contracts", body);
+
+    if (!response.contractEntry) {
+      return [];
+    }
+
+    return response.contractEntry
+      .filter((entry) => entry.createdEvent != null)
+      .map((entry) => {
+        const evt = entry.createdEvent!;
+        return {
+          contractId: evt.contractId,
+          templateId: evt.templateId,
+          createArgument: evt.createArgument,
+          createdAt: "",
+          signatories: evt.signatories,
+          observers: evt.observers,
+        };
+      });
+  }
+
+  // ---------------------------------------------------------------------------
+  // Transaction Lookup
+  // ---------------------------------------------------------------------------
+
+  async getTransactionById(updateId: string): Promise<TransactionTree | null> {
+    try {
+      return await this.request<TransactionTree>(
+        "GET",
+        `/v2/updates/transaction-by-id/${encodeURIComponent(updateId)}`,
+      );
+    } catch (err) {
+      if (err instanceof CantonApiError && err.code === "NOT_FOUND") {
+        return null;
+      }
+      throw err;
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Ledger State
+  // ---------------------------------------------------------------------------
+
+  async getLedgerEnd(): Promise<number> {
+    const response = await this.request<{ offset: number }>("GET", "/v2/state/ledger-end");
+    return response.offset;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Party Management
+  // ---------------------------------------------------------------------------
+
+  async allocateParty(hint: string): Promise<PartyDetails> {
+    const response = await this.request<{ partyDetails: PartyDetails }>("POST", "/v2/parties", {
+      partyIdHint: hint,
+      identityProviderId: "",
+    });
+    return response.partyDetails;
+  }
+
+  async listParties(): Promise<PartyDetails[]> {
+    const response = await this.request<{ partyDetails: PartyDetails[] }>("GET", "/v2/parties");
+    return response.partyDetails;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Health Check
+  // ---------------------------------------------------------------------------
+
+  async isHealthy(): Promise<boolean> {
+    try {
+      const response = await fetch(`${this.ledgerUrl}/livez`, {
+        method: "GET",
+        headers: { Authorization: `Bearer ${this.token}` },
+        signal: AbortSignal.timeout(this.timeout),
+      });
+      return response.ok;
+    } catch {
+      return false;
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal
+  // ---------------------------------------------------------------------------
+
+  private async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+    const url = `${this.ledgerUrl}${path}`;
+
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${this.token}`,
+    };
+
+    if (body !== undefined) {
+      headers["Content-Type"] = "application/json";
+    }
+
+    let response: Response;
+    try {
+      response = await fetch(url, {
+        method,
+        headers,
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+        signal: AbortSignal.timeout(this.timeout),
+      });
+    } catch (err: unknown) {
+      if (err instanceof DOMException && err.name === "TimeoutError") {
+        throw new CantonTimeoutError(path, this.timeout);
+      }
+      if (err instanceof DOMException && err.name === "AbortError") {
+        throw new CantonTimeoutError(path, this.timeout);
+      }
+      throw err;
+    }
+
+    if (response.status === 401 || response.status === 403) {
+      const text = await response.text().catch(() => "");
+      throw new CantonAuthError(response.status, text || undefined);
+    }
+
+    if (!response.ok) {
+      const errorBody = await response.json().catch(() => null);
+      if (errorBody && typeof errorBody === "object" && "code" in errorBody) {
+        throw new CantonApiError(errorBody as LedgerError);
+      }
+      throw new Error(`Canton API error: HTTP ${response.status} on ${method} ${path}`);
+    }
+
+    // Some endpoints (like livez) may return empty body
+    const text = await response.text();
+    if (!text) {
+      return {} as T;
+    }
+
+    return JSON.parse(text) as T;
+  }
+}

package/src/canton/errors.ts

@@ -0,0 +1,45 @@
+/**
+ * Canton SDK — Custom Error Classes
+ */
+
+import type { CantonErrorCode, LedgerError } from "./types.js";
+
+export class CantonApiError extends Error {
+  readonly code: CantonErrorCode;
+  readonly ledgerCause: string;
+  readonly grpcCodeValue: number;
+  readonly errorCategory: number;
+  readonly context: Record<string, string>;
+
+  constructor(ledgerError: LedgerError) {
+    super(`Canton API error [${ledgerError.code}]: ${ledgerError.cause}`);
+    this.name = "CantonApiError";
+    this.code = ledgerError.code;
+    this.ledgerCause = ledgerError.cause;
+    this.grpcCodeValue = ledgerError.grpcCodeValue;
+    this.errorCategory = ledgerError.errorCategory;
+    this.context = ledgerError.context;
+  }
+}
+
+export class CantonTimeoutError extends Error {
+  readonly timeoutMs: number;
+  readonly path: string;
+
+  constructor(path: string, timeoutMs: number) {
+    super(`Canton request to ${path} timed out after ${timeoutMs}ms`);
+    this.name = "CantonTimeoutError";
+    this.timeoutMs = timeoutMs;
+    this.path = path;
+  }
+}
+
+export class CantonAuthError extends Error {
+  readonly statusCode: number;
+
+  constructor(statusCode: number, message?: string) {
+    super(message ?? `Canton authentication failed (HTTP ${statusCode})`);
+    this.name = "CantonAuthError";
+    this.statusCode = statusCode;
+  }
+}