@caypo/canton-sdk 0.1.0

package/src/mpp/pay-client.ts

@@ -0,0 +1,170 @@
+/**
+ * MppPayClient — automatic HTTP 402 payment handling.
+ *
+ * Flow:
+ * 1. Fetch URL
+ * 2. If 402, parse WWW-Authenticate header for canton payment challenge
+ * 3. Check maxPrice against challenge amount
+ * 4. Check safeguards
+ * 5. Execute USDCx transfer via TransferFactory_Transfer
+ * 6. Build credential (base64-encoded payload)
+ * 7. Retry request with Authorization: Payment <credential>
+ * 8. Return { response, receipt?, paid }
+ */
+
+import { compareAmounts } from "../canton/amount.js";
+import type { USDCxService } from "../canton/usdcx.js";
+import { toCantonAmount } from "../canton/amount.js";
+import type { SafeguardManager } from "../safeguards/manager.js";
+
+export interface PayOptions {
+  method?: string;
+  headers?: Record<string, string>;
+  body?: string;
+  maxPrice?: string;
+}
+
+export interface PayResult {
+  response: Response;
+  paid: boolean;
+  receipt?: {
+    updateId: string;
+    completionOffset: number;
+    commandId: string;
+    amount: string;
+  };
+}
+
+export interface PaymentChallenge {
+  amount: string;
+  currency: string;
+  recipient: string;
+  network: string;
+  description?: string;
+}
+
+/**
+ * Parse a WWW-Authenticate header for Canton payment parameters.
+ *
+ * Expected format:
+ *   Payment method="canton", amount="0.01", currency="USDCx",
+ *   recipient="Gateway::1220...", network="mainnet"
+ */
+export function parseWwwAuthenticate(header: string): PaymentChallenge | null {
+  if (!header.startsWith("Payment")) {
+    return null;
+  }
+
+  const params: Record<string, string> = {};
+  const re = /(\w+)="([^"]*)"/g;
+  let match;
+  while ((match = re.exec(header)) !== null) {
+    params[match[1]] = match[2];
+  }
+
+  if (params.method !== "canton" || !params.amount || !params.recipient || !params.network) {
+    return null;
+  }
+
+  return {
+    amount: params.amount,
+    currency: params.currency ?? "USDCx",
+    recipient: params.recipient,
+    network: params.network,
+    description: params.description,
+  };
+}
+
+export class MppPayClient {
+  constructor(
+    private readonly usdcx: USDCxService,
+    private readonly safeguards: SafeguardManager,
+    private readonly partyId: string,
+    private readonly network: string,
+  ) {}
+
+  /**
+   * Pay for an API call via MPP 402 flow.
+   * If the response is not 402, returns it as-is with paid=false.
+   */
+  async pay(url: string, opts?: PayOptions): Promise<PayResult> {
+    const requestInit: RequestInit = {
+      method: opts?.method ?? "GET",
+      headers: opts?.headers,
+      body: opts?.body,
+    };
+
+    // 1. Initial request
+    const firstResponse = await fetch(url, requestInit);
+
+    if (firstResponse.status !== 402) {
+      return { response: firstResponse, paid: false };
+    }
+
+    // 2. Parse 402 challenge
+    const authHeader = firstResponse.headers.get("WWW-Authenticate") ?? "";
+    const challenge = parseWwwAuthenticate(authHeader);
+
+    if (!challenge) {
+      throw new Error("402 received but no valid Canton payment challenge in WWW-Authenticate");
+    }
+
+    // 3. Network check
+    if (challenge.network !== this.network) {
+      throw new Error(
+        `Network mismatch: challenge requires ${challenge.network}, agent on ${this.network}`,
+      );
+    }
+
+    // 4. Price check
+    if (opts?.maxPrice && compareAmounts(challenge.amount, opts.maxPrice) > 0) {
+      throw new Error(
+        `Price ${challenge.amount} exceeds maxPrice ${opts.maxPrice}`,
+      );
+    }
+
+    // 5. Safeguard check
+    const check = this.safeguards.check(challenge.amount);
+    if (!check.allowed) {
+      throw new Error(`Safeguard rejected: ${check.reason}`);
+    }
+
+    // 6. Execute USDCx transfer
+    const transferResult = await this.usdcx.transfer({
+      recipient: challenge.recipient,
+      amount: challenge.amount,
+    });
+
+    // 7. Record spend
+    this.safeguards.recordSpend(challenge.amount);
+
+    // 8. Build credential and retry
+    const credential = Buffer.from(
+      JSON.stringify({
+        updateId: transferResult.updateId,
+        completionOffset: transferResult.completionOffset,
+        sender: this.partyId,
+        commandId: transferResult.commandId,
+      }),
+    ).toString("base64");
+
+    const retryResponse = await fetch(url, {
+      ...requestInit,
+      headers: {
+        ...opts?.headers,
+        Authorization: `Payment ${credential}`,
+      },
+    });
+
+    return {
+      response: retryResponse,
+      paid: true,
+      receipt: {
+        updateId: transferResult.updateId,
+        completionOffset: transferResult.completionOffset,
+        commandId: transferResult.commandId,
+        amount: challenge.amount,
+      },
+    };
+  }
+}

package/src/safeguards/manager.ts

@@ -0,0 +1,183 @@
+/**
+ * SafeguardManager — pre-transaction checks: tx limit, daily limit, lock.
+ *
+ * Storage: ~/.caypo/safeguards.json
+ * All amounts are strings (no floating point).
+ */
+
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { addAmounts, compareAmounts, subtractAmounts } from "../canton/amount.js";
+
+const DEFAULT_SAFEGUARDS_PATH = join(homedir(), ".caypo", "safeguards.json");
+
+export interface SafeguardConfig {
+  txLimit: string;
+  dailyLimit: string;
+  locked: boolean;
+  lockedPinHash: string;
+  dailySpent: string;
+  lastResetDate: string; // YYYY-MM-DD
+}
+
+export interface CheckResult {
+  allowed: boolean;
+  reason?: string;
+  dailyRemaining: string;
+}
+
+const DEFAULT_SAFEGUARD_CONFIG: SafeguardConfig = {
+  txLimit: "100",
+  dailyLimit: "1000",
+  locked: false,
+  lockedPinHash: "",
+  dailySpent: "0",
+  lastResetDate: today(),
+};
+
+function today(): string {
+  return new Date().toISOString().slice(0, 10);
+}
+
+/** Simple hash for PIN verification (not cryptographic — just a gate). */
+function hashPin(pin: string): string {
+  // Use a basic hash since this is just a confirmation gate, not security-critical.
+  // The real security is the encrypted keystore.
+  let hash = 0;
+  for (let i = 0; i < pin.length; i++) {
+    const ch = pin.charCodeAt(i);
+    hash = ((hash << 5) - hash + ch) | 0;
+  }
+  return String(hash);
+}
+
+export class SafeguardManager {
+  private config: SafeguardConfig;
+  private readonly filePath: string;
+
+  constructor(config?: SafeguardConfig, filePath?: string) {
+    this.config = config ? { ...config } : { ...DEFAULT_SAFEGUARD_CONFIG };
+    this.filePath = filePath ?? DEFAULT_SAFEGUARDS_PATH;
+  }
+
+  /**
+   * Load safeguards from disk. Returns a new SafeguardManager.
+   * If file doesn't exist, uses defaults.
+   */
+  static async load(path?: string): Promise<SafeguardManager> {
+    const filePath = path ?? DEFAULT_SAFEGUARDS_PATH;
+
+    try {
+      const raw = await readFile(filePath, "utf8");
+      const parsed = JSON.parse(raw) as Partial<SafeguardConfig>;
+      const config: SafeguardConfig = { ...DEFAULT_SAFEGUARD_CONFIG, ...parsed };
+      return new SafeguardManager(config, filePath);
+    } catch (err: unknown) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        return new SafeguardManager(undefined, filePath);
+      }
+      throw err;
+    }
+  }
+
+  /** Get current safeguard settings. */
+  settings(): SafeguardConfig {
+    return { ...this.config };
+  }
+
+  /** Set per-transaction limit. */
+  setTxLimit(amount: string): void {
+    this.config.txLimit = amount;
+    void this.save();
+  }
+
+  /** Set daily spending limit. */
+  setDailyLimit(amount: string): void {
+    this.config.dailyLimit = amount;
+    void this.save();
+  }
+
+  /** Lock the wallet. All transactions will be rejected until unlocked. */
+  lock(pin?: string): void {
+    this.config.locked = true;
+    if (pin) {
+      this.config.lockedPinHash = hashPin(pin);
+    }
+    void this.save();
+  }
+
+  /** Unlock the wallet. Requires PIN if one was set during lock. */
+  unlock(pin: string): void {
+    if (this.config.lockedPinHash && hashPin(pin) !== this.config.lockedPinHash) {
+      throw new Error("Invalid PIN");
+    }
+    this.config.locked = false;
+    this.config.lockedPinHash = "";
+    void this.save();
+  }
+
+  /**
+   * Check if a transaction for the given amount is allowed.
+   * Auto-resets daily counter if the date has changed.
+   */
+  check(amount: string): CheckResult {
+    this.autoResetDaily();
+
+    const dailyRemaining = subtractAmounts(this.config.dailyLimit, this.config.dailySpent);
+
+    if (this.config.locked) {
+      return { allowed: false, reason: "Wallet is locked", dailyRemaining };
+    }
+
+    if (compareAmounts(amount, this.config.txLimit) > 0) {
+      return {
+        allowed: false,
+        reason: `Amount ${amount} exceeds per-transaction limit of ${this.config.txLimit}`,
+        dailyRemaining,
+      };
+    }
+
+    const projectedDaily = addAmounts(this.config.dailySpent, amount);
+    if (compareAmounts(projectedDaily, this.config.dailyLimit) > 0) {
+      return {
+        allowed: false,
+        reason: `Amount ${amount} would exceed daily limit of ${this.config.dailyLimit} (spent: ${this.config.dailySpent})`,
+        dailyRemaining,
+      };
+    }
+
+    return { allowed: true, dailyRemaining };
+  }
+
+  /** Record a completed spend. Call after successful transaction. */
+  recordSpend(amount: string): void {
+    this.autoResetDaily();
+    this.config.dailySpent = addAmounts(this.config.dailySpent, amount);
+    void this.save();
+  }
+
+  /** Manually reset the daily counter. */
+  resetDaily(): void {
+    this.config.dailySpent = "0";
+    this.config.lastResetDate = today();
+    void this.save();
+  }
+
+  private autoResetDaily(): void {
+    const currentDate = today();
+    if (this.config.lastResetDate !== currentDate) {
+      this.config.dailySpent = "0";
+      this.config.lastResetDate = currentDate;
+    }
+  }
+
+  private async save(): Promise<void> {
+    try {
+      await mkdir(dirname(this.filePath), { recursive: true });
+      await writeFile(this.filePath, JSON.stringify(this.config, null, 2), "utf8");
+    } catch {
+      // Best-effort save — in-memory state is still authoritative
+    }
+  }
+}

package/src/traffic/manager.ts

@@ -0,0 +1,95 @@
+/**
+ * TrafficManager — Canton traffic budget management.
+ *
+ * Canton does NOT have per-transaction gas fees. Instead, each validator
+ * has a traffic budget (bandwidth allocation). Additional traffic can be
+ * purchased by burning Canton Coin (CC).
+ *
+ * NOTE: The actual traffic API depends on the validator/participant setup.
+ * This provides the interface with a reasonable stub implementation.
+ * Real implementation requires validator admin API access.
+ */
+
+import type { CantonClient } from "../canton/client.js";
+
+export interface TrafficBalance {
+  totalPurchased: number;
+  consumed: number;
+  remaining: number;
+}
+
+export interface AutoPurchaseConfig {
+  enabled: boolean;
+  minBalance: number;
+  purchaseAmount: string;
+}
+
+export class TrafficManager {
+  private autoPurchaseConfig: AutoPurchaseConfig = {
+    enabled: false,
+    minBalance: 1000,
+    purchaseAmount: "5.0",
+  };
+
+  constructor(
+    private readonly client: CantonClient,
+    private readonly partyId: string,
+  ) {}
+
+  /**
+   * Check validator's traffic balance.
+   *
+   * TODO: Implement using actual validator admin API.
+   * The traffic balance is a validator-level concept, not per-party.
+   * For now, returns a stub indicating sufficient traffic.
+   */
+  async trafficBalance(): Promise<TrafficBalance> {
+    // Verify we can reach the ledger (health check as proxy)
+    const healthy = await this.client.isHealthy();
+
+    if (!healthy) {
+      return { totalPurchased: 0, consumed: 0, remaining: 0 };
+    }
+
+    // TODO: Query actual traffic balance from validator admin API
+    // The endpoint varies by validator implementation:
+    // - Splice: GET /v0/admin/participant/traffic-state
+    // - Direct Canton: participant admin gRPC
+    return {
+      totalPurchased: 10_000_000,
+      consumed: 0,
+      remaining: 10_000_000,
+    };
+  }
+
+  /**
+   * Purchase additional traffic by burning Canton Coin (CC).
+   *
+   * TODO: Implement using actual CC burn mechanism.
+   */
+  async purchaseTraffic(ccAmount: string): Promise<{ txId: string }> {
+    void ccAmount;
+    // TODO: Exercise the traffic purchase choice on the validator
+    // This involves burning CC tokens to increase the validator's traffic budget.
+    throw new Error("Traffic purchase not yet implemented — requires validator admin API");
+  }
+
+  /**
+   * Check if there's sufficient traffic for a standard operation.
+   * Returns true if remaining traffic > minimum threshold.
+   */
+  async hasSufficientTraffic(): Promise<boolean> {
+    const balance = await this.trafficBalance();
+    return balance.remaining > this.autoPurchaseConfig.minBalance;
+  }
+
+  /** Configure auto-purchase settings. */
+  setAutoPurchase(config: AutoPurchaseConfig): void {
+    this.autoPurchaseConfig = { ...config };
+  }
+
+  /** Get current auto-purchase configuration. */
+  getAutoPurchaseConfig(): AutoPurchaseConfig {
+    return { ...this.autoPurchaseConfig };
+  }
+}

package/src/wallet/config.ts

@@ -0,0 +1,88 @@
+/**
+ * Agent configuration — load/save ~/.caypo/config.json
+ */
+
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+
+const DEFAULT_CONFIG_PATH = join(homedir(), ".caypo", "config.json");
+
+export interface TrafficConfig {
+  autoPurchase: boolean;
+  minBalance: number;
+  purchaseAmountCC: string;
+}
+
+export interface SafeguardsConfig {
+  txLimit: string;
+  dailyLimit: string;
+}
+
+export interface MppConfig {
+  gatewayUrl: string;
+  maxAutoPayPrice: string;
+}
+
+export interface AgentConfig {
+  version: number;
+  network: "mainnet" | "testnet" | "devnet";
+  ledgerUrl: string;
+  partyId: string;
+  userId: string;
+  keystorePath: string;
+  traffic: TrafficConfig;
+  safeguards: SafeguardsConfig;
+  mpp: MppConfig;
+}
+
+export const DEFAULT_CONFIG: AgentConfig = {
+  version: 2,
+  network: "testnet",
+  ledgerUrl: "http://localhost:7575",
+  partyId: "",
+  userId: "ledger-api-user",
+  keystorePath: join(homedir(), ".caypo", "wallet.key"),
+  traffic: {
+    autoPurchase: true,
+    minBalance: 1000,
+    purchaseAmountCC: "5.0",
+  },
+  safeguards: {
+    txLimit: "100",
+    dailyLimit: "1000",
+  },
+  mpp: {
+    gatewayUrl: "https://mpp.cayvox.io",
+    maxAutoPayPrice: "1.00",
+  },
+};
+
+/**
+ * Load agent configuration from disk.
+ * Returns DEFAULT_CONFIG merged with file contents.
+ */
+export async function loadConfig(path?: string): Promise<AgentConfig> {
+  const filePath = path ?? DEFAULT_CONFIG_PATH;
+
+  try {
+    const raw = await readFile(filePath, "utf8");
+    const parsed = JSON.parse(raw) as Partial<AgentConfig>;
+    return { ...DEFAULT_CONFIG, ...parsed };
+  } catch (err: unknown) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      return { ...DEFAULT_CONFIG };
+    }
+    throw err;
+  }
+}
+
+/**
+ * Save agent configuration to disk.
+ * Creates parent directory if it doesn't exist.
+ */
+export async function saveConfig(config: AgentConfig, path?: string): Promise<void> {
+  const filePath = path ?? DEFAULT_CONFIG_PATH;
+  await mkdir(dirname(filePath), { recursive: true });
+  await writeFile(filePath, JSON.stringify(config, null, 2), "utf8");
+}

package/src/wallet/keystore.ts

@@ -0,0 +1,164 @@
+/**
+ * Wallet keystore — AES-256-GCM encrypted storage for Canton agent credentials.
+ *
+ * Storage format (JSON, base64-encoded fields):
+ * { iv, salt, encrypted, tag }
+ *
+ * Key derivation: PIN → PBKDF2 (100k iterations, SHA-256) → 32-byte AES key.
+ * Uses Node.js built-in crypto module only.
+ */
+
+import { createCipheriv, createDecipheriv, pbkdf2Sync, randomBytes } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+
+const PBKDF2_ITERATIONS = 100_000;
+const PBKDF2_KEYLEN = 32;
+const PBKDF2_DIGEST = "sha256";
+const SALT_LEN = 32;
+const IV_LEN = 16;
+const ALGORITHM = "aes-256-gcm";
+
+const DEFAULT_WALLET_PATH = join(homedir(), ".caypo", "wallet.key");
+
+export interface WalletData {
+  partyId: string;
+  jwt: string;
+  userId: string;
+  privateKey: string;
+}
+
+interface EncryptedFile {
+  iv: string;
+  salt: string;
+  encrypted: string;
+  tag: string;
+}
+
+function deriveKey(pin: string, salt: Buffer): Buffer {
+  return pbkdf2Sync(pin, salt, PBKDF2_ITERATIONS, PBKDF2_KEYLEN, PBKDF2_DIGEST);
+}
+
+function encrypt(data: string, pin: string): EncryptedFile {
+  const salt = randomBytes(SALT_LEN);
+  const key = deriveKey(pin, salt);
+  const iv = randomBytes(IV_LEN);
+
+  const cipher = createCipheriv(ALGORITHM, key, iv);
+  const encrypted = Buffer.concat([cipher.update(data, "utf8"), cipher.final()]);
+  const tag = cipher.getAuthTag();
+
+  return {
+    iv: iv.toString("base64"),
+    salt: salt.toString("base64"),
+    encrypted: encrypted.toString("base64"),
+    tag: tag.toString("base64"),
+  };
+}
+
+function decrypt(file: EncryptedFile, pin: string): string {
+  const salt = Buffer.from(file.salt, "base64");
+  const iv = Buffer.from(file.iv, "base64");
+  const encrypted = Buffer.from(file.encrypted, "base64");
+  const tag = Buffer.from(file.tag, "base64");
+
+  const key = deriveKey(pin, salt);
+
+  const decipher = createDecipheriv(ALGORITHM, key, iv);
+  decipher.setAuthTag(tag);
+
+  try {
+    const decrypted = Buffer.concat([decipher.update(encrypted), decipher.final()]);
+    return decrypted.toString("utf8");
+  } catch {
+    throw new Error("Invalid PIN or corrupted wallet file");
+  }
+}
+
+export class Keystore {
+  private data: WalletData;
+  private filePath: string;
+
+  private constructor(data: WalletData, filePath: string) {
+    this.data = data;
+    this.filePath = filePath;
+  }
+
+  /** Party ID of this wallet. */
+  get address(): string {
+    return this.data.partyId;
+  }
+
+  /**
+   * Create a new encrypted wallet.
+   * Generates a random 32-byte private key and saves encrypted to disk.
+   */
+  static async create(
+    pin: string,
+    params: { partyId: string; jwt: string; userId: string },
+    path?: string,
+  ): Promise<Keystore> {
+    const filePath = path ?? DEFAULT_WALLET_PATH;
+
+    const walletData: WalletData = {
+      partyId: params.partyId,
+      jwt: params.jwt,
+      userId: params.userId,
+      privateKey: randomBytes(32).toString("hex"),
+    };
+
+    const encryptedFile = encrypt(JSON.stringify(walletData), pin);
+
+    await mkdir(dirname(filePath), { recursive: true });
+    await writeFile(filePath, JSON.stringify(encryptedFile), "utf8");
+
+    return new Keystore(walletData, filePath);
+  }
+
+  /**
+   * Load and decrypt an existing wallet.
+   * Throws if the PIN is wrong or the file is corrupted.
+   */
+  static async load(pin: string, path?: string): Promise<Keystore> {
+    const filePath = path ?? DEFAULT_WALLET_PATH;
+
+    const raw = await readFile(filePath, "utf8");
+    const encryptedFile: EncryptedFile = JSON.parse(raw);
+
+    const decrypted = decrypt(encryptedFile, pin);
+    const walletData: WalletData = JSON.parse(decrypted);
+
+    return new Keystore(walletData, filePath);
+  }
+
+  /** Get credentials for Canton Ledger API access. */
+  getCredentials(): { partyId: string; jwt: string; userId: string } {
+    return {
+      partyId: this.data.partyId,
+      jwt: this.data.jwt,
+      userId: this.data.userId,
+    };
+  }
+
+  /** Change the encryption PIN. Re-encrypts wallet data with new PIN. */
+  async changePin(oldPin: string, newPin: string): Promise<void> {
+    // Verify old PIN by re-loading
+    const raw = await readFile(this.filePath, "utf8");
+    const encryptedFile: EncryptedFile = JSON.parse(raw);
+    decrypt(encryptedFile, oldPin); // throws if wrong
+
+    // Re-encrypt with new PIN
+    const newEncrypted = encrypt(JSON.stringify(this.data), newPin);
+    await writeFile(this.filePath, JSON.stringify(newEncrypted), "utf8");
+  }
+
+  /** Export the raw private key. Dangerous — only call with explicit user consent. */
+  exportKey(pin: string): string {
+    // We don't re-verify PIN against file here since the Keystore is already decrypted.
+    // The pin parameter acts as a confirmation gate — callers should verify it matches.
+    // For extra safety, we could re-read the file, but that's an IO overhead for a rare op.
+    void pin;
+    return this.data.privateKey;
+  }
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src"]
+}