@caypo/canton-sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,673 @@
+export { MPP_CANTON_VERSION } from '@caypo/mpp-canton';
+
+/**
+ * Canton JSON Ledger API v2 — Type Definitions
+ *
+ * Verified against: docs.digitalasset.com/build/3.5, Canton OpenAPI spec v3.3.0
+ * Default port: 7575
+ */
+interface PartyLocalMetadata {
+    resourceVersion: string;
+    annotations: Record<string, string>;
+}
+interface PartyDetails {
+    party: string;
+    isLocal: boolean;
+    localMetadata: PartyLocalMetadata;
+    identityProviderId: string;
+}
+interface CreateCommand {
+    CreateCommand: {
+        templateId: string;
+        createArguments: Record<string, unknown>;
+    };
+}
+interface ExerciseCommand {
+    ExerciseCommand: {
+        templateId: string;
+        contractId: string;
+        choice: string;
+        choiceArgument: Record<string, unknown>;
+    };
+}
+type Command = CreateCommand | ExerciseCommand;
+interface SubmitAndWaitRequest {
+    commands: Command[];
+    userId: string;
+    commandId: string;
+    actAs: string[];
+    readAs?: string[];
+}
+interface SubmitAndWaitResponse {
+    updateId: string;
+    completionOffset: number;
+}
+interface CreatedEvent {
+    contractId: string;
+    templateId: string;
+    createArgument: Record<string, unknown>;
+    witnessParties: string[];
+    signatories: string[];
+    observers: string[];
+}
+interface ArchivedEvent {
+    contractId: string;
+    templateId: string;
+    witnessParties: string[];
+}
+interface ExercisedEvent {
+    contractId: string;
+    templateId: string;
+    choice: string;
+    choiceArgument: Record<string, unknown>;
+    exerciseResult: unknown;
+    actingParties: string[];
+    childEvents: TransactionTreeEvent[];
+}
+type TransactionTreeEvent = {
+    createdEvent: CreatedEvent;
+} | {
+    exercisedEvent: ExercisedEvent;
+};
+interface TransactionTree {
+    updateId: string;
+    commandId: string;
+    effectiveAt: string;
+    offset: number;
+    eventsById: Record<string, TransactionTreeEvent>;
+    rootEventIds: string[];
+}
+interface FlatTransaction {
+    updateId: string;
+    commandId: string;
+    effectiveAt: string;
+    offset: number;
+    events: Array<{
+        createdEvent?: CreatedEvent;
+        archivedEvent?: ArchivedEvent;
+    }>;
+}
+interface TransactionResponse {
+    transaction: FlatTransaction;
+}
+interface IdentifierFilter {
+    identifierFilter: {
+        TemplateFilter: {
+            value: {
+                templateId: string;
+            };
+        };
+    } | {
+        WildcardFilter: {
+            value: {
+                includeCreatedEventBlob?: boolean;
+            };
+        };
+    };
+}
+interface PartyFilter {
+    cumulative: IdentifierFilter[];
+}
+interface AnyPartyFilter {
+    cumulative: IdentifierFilter[];
+}
+interface EventFormat {
+    filtersByParty?: Record<string, PartyFilter>;
+    filtersForAnyParty?: AnyPartyFilter;
+    verbose?: boolean;
+}
+interface ActiveContractsRequest {
+    eventFormat: EventFormat;
+    activeAtOffset: number;
+}
+interface ActiveContract {
+    contractId: string;
+    templateId: string;
+    createArgument: Record<string, unknown>;
+    createdAt: string;
+    signatories: string[];
+    observers: string[];
+}
+interface LedgerEndResponse {
+    offset: number;
+}
+type CantonErrorCode = "INVALID_ARGUMENT" | "NOT_FOUND" | "PERMISSION_DENIED" | "ALREADY_EXISTS" | "FAILED_PRECONDITION" | "UNAVAILABLE" | string;
+interface LedgerError {
+    cause: string;
+    code: CantonErrorCode;
+    context: Record<string, string>;
+    errorCategory: number;
+    grpcCodeValue: number;
+}
+interface CantonClientConfig {
+    ledgerUrl: string;
+    token: string;
+    userId: string;
+    timeout?: number;
+}
+interface SubmitParams {
+    commands: Command[];
+    commandId: string;
+    actAs: string[];
+    readAs?: string[];
+}
+interface QueryActiveContractsParams {
+    filtersByParty?: Record<string, PartyFilter>;
+    filtersForAnyParty?: AnyPartyFilter;
+    activeAtOffset: number;
+}
+
+/**
+ * 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.
+ */
+
+declare class CantonClient {
+    private readonly ledgerUrl;
+    private readonly token;
+    private readonly userId;
+    private readonly timeout;
+    constructor(config: CantonClientConfig);
+    submitAndWait(params: SubmitParams): Promise<SubmitAndWaitResponse>;
+    submitAndWaitForTransaction(params: SubmitParams): Promise<TransactionResponse>;
+    queryActiveContracts(params: QueryActiveContractsParams): Promise<ActiveContract[]>;
+    getTransactionById(updateId: string): Promise<TransactionTree | null>;
+    getLedgerEnd(): Promise<number>;
+    allocateParty(hint: string): Promise<PartyDetails>;
+    listParties(): Promise<PartyDetails[]>;
+    isHealthy(): Promise<boolean>;
+    private request;
+}
+
+/**
+ * Canton SDK — Custom Error Classes
+ */
+
+declare class CantonApiError extends Error {
+    readonly code: CantonErrorCode;
+    readonly ledgerCause: string;
+    readonly grpcCodeValue: number;
+    readonly errorCategory: number;
+    readonly context: Record<string, string>;
+    constructor(ledgerError: LedgerError);
+}
+declare class CantonTimeoutError extends Error {
+    readonly timeoutMs: number;
+    readonly path: string;
+    constructor(path: string, timeoutMs: number);
+}
+declare class CantonAuthError extends Error {
+    readonly statusCode: number;
+    constructor(statusCode: number, message?: string);
+}
+
+/**
+ * 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.
+ */
+interface USDCxHolding {
+    contractId: string;
+    owner: string;
+    amount: string;
+    templateId: string;
+}
+interface HoldingSelection {
+    type: "single" | "merge-then-transfer";
+    contractIds: string[];
+}
+declare class InsufficientBalanceError extends Error {
+    readonly available: string;
+    readonly required: string;
+    constructor(available: string, required: string);
+}
+/**
+ * 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.
+ */
+declare function selectHoldings(holdings: USDCxHolding[], requiredAmount: string): HoldingSelection;
+
+/**
+ * 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)
+ */
+
+/** CIP-56 Holding template ID — used for active contract queries */
+declare const USDCX_HOLDING_TEMPLATE_ID = "Splice.Api.Token.HoldingV1:Holding";
+/** TransferFactory template ID for 1-step transfers */
+declare const TRANSFER_FACTORY_TEMPLATE_ID = "Splice.Api.Token.TransferFactoryV1:TransferFactory";
+/** USDCx instrument identifier */
+declare const USDCX_INSTRUMENT_ID = "USDCx";
+interface TransferResult {
+    updateId: string;
+    completionOffset: number;
+    commandId: string;
+}
+interface TransferParams {
+    recipient: string;
+    amount: string;
+    commandId?: string;
+}
+declare class USDCxService {
+    private readonly client;
+    private readonly partyId;
+    constructor(client: CantonClient, partyId: string);
+    /**
+     * Query all USDCx Holding contracts for this party.
+     */
+    getHoldings(): Promise<USDCxHolding[]>;
+    /**
+     * Calculate total USDCx balance by summing all holding amounts.
+     * Returns a string with up to 10 decimal places.
+     */
+    getBalance(): Promise<string>;
+    /**
+     * Transfer USDCx using TransferFactory_Transfer (1-step).
+     * Requires the recipient to have an active TransferPreapproval.
+     */
+    transfer(params: TransferParams): Promise<TransferResult>;
+    /**
+     * Merge multiple holdings into fewer UTXOs.
+     * Returns the commandId of the merge transaction.
+     */
+    mergeHoldings(holdingCids: string[]): Promise<string>;
+}
+
+/**
+ * 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.
+ */
+/**
+ * Validate that a string is a valid non-negative decimal amount.
+ */
+declare function isValidAmount(s: string): boolean;
+/**
+ * Compare two decimal amount strings.
+ * Returns -1 if a < b, 0 if a === b, 1 if a > b.
+ */
+declare function compareAmounts(a: string, b: string): -1 | 0 | 1;
+/**
+ * Add two decimal amount strings. Returns the sum as a string.
+ */
+declare function addAmounts(a: string, b: string): string;
+/**
+ * Subtract b from a. Both must be valid amounts and a >= b.
+ * Throws if a < b.
+ */
+declare function subtractAmounts(a: string, b: string): string;
+/**
+ * Pad (or truncate) a decimal string to exactly N decimal places.
+ * Default: 10 (Canton Numeric 10).
+ */
+declare function toCantonAmount(s: string, decimals?: number): string;
+
+/**
+ * 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.
+ */
+interface WalletData {
+    partyId: string;
+    jwt: string;
+    userId: string;
+    privateKey: string;
+}
+declare class Keystore {
+    private data;
+    private filePath;
+    private constructor();
+    /** Party ID of this wallet. */
+    get address(): string;
+    /**
+     * Create a new encrypted wallet.
+     * Generates a random 32-byte private key and saves encrypted to disk.
+     */
+    static create(pin: string, params: {
+        partyId: string;
+        jwt: string;
+        userId: string;
+    }, path?: string): Promise<Keystore>;
+    /**
+     * Load and decrypt an existing wallet.
+     * Throws if the PIN is wrong or the file is corrupted.
+     */
+    static load(pin: string, path?: string): Promise<Keystore>;
+    /** Get credentials for Canton Ledger API access. */
+    getCredentials(): {
+        partyId: string;
+        jwt: string;
+        userId: string;
+    };
+    /** Change the encryption PIN. Re-encrypts wallet data with new PIN. */
+    changePin(oldPin: string, newPin: string): Promise<void>;
+    /** Export the raw private key. Dangerous — only call with explicit user consent. */
+    exportKey(pin: string): string;
+}
+
+/**
+ * Agent configuration — load/save ~/.caypo/config.json
+ */
+interface TrafficConfig {
+    autoPurchase: boolean;
+    minBalance: number;
+    purchaseAmountCC: string;
+}
+interface SafeguardsConfig {
+    txLimit: string;
+    dailyLimit: string;
+}
+interface MppConfig {
+    gatewayUrl: string;
+    maxAutoPayPrice: string;
+}
+interface AgentConfig {
+    version: number;
+    network: "mainnet" | "testnet" | "devnet";
+    ledgerUrl: string;
+    partyId: string;
+    userId: string;
+    keystorePath: string;
+    traffic: TrafficConfig;
+    safeguards: SafeguardsConfig;
+    mpp: MppConfig;
+}
+declare const DEFAULT_CONFIG: AgentConfig;
+/**
+ * Load agent configuration from disk.
+ * Returns DEFAULT_CONFIG merged with file contents.
+ */
+declare function loadConfig(path?: string): Promise<AgentConfig>;
+/**
+ * Save agent configuration to disk.
+ * Creates parent directory if it doesn't exist.
+ */
+declare function saveConfig(config: AgentConfig, path?: string): Promise<void>;
+
+/**
+ * SafeguardManager — pre-transaction checks: tx limit, daily limit, lock.
+ *
+ * Storage: ~/.caypo/safeguards.json
+ * All amounts are strings (no floating point).
+ */
+interface SafeguardConfig {
+    txLimit: string;
+    dailyLimit: string;
+    locked: boolean;
+    lockedPinHash: string;
+    dailySpent: string;
+    lastResetDate: string;
+}
+interface CheckResult {
+    allowed: boolean;
+    reason?: string;
+    dailyRemaining: string;
+}
+declare class SafeguardManager {
+    private config;
+    private readonly filePath;
+    constructor(config?: SafeguardConfig, filePath?: string);
+    /**
+     * Load safeguards from disk. Returns a new SafeguardManager.
+     * If file doesn't exist, uses defaults.
+     */
+    static load(path?: string): Promise<SafeguardManager>;
+    /** Get current safeguard settings. */
+    settings(): SafeguardConfig;
+    /** Set per-transaction limit. */
+    setTxLimit(amount: string): void;
+    /** Set daily spending limit. */
+    setDailyLimit(amount: string): void;
+    /** Lock the wallet. All transactions will be rejected until unlocked. */
+    lock(pin?: string): void;
+    /** Unlock the wallet. Requires PIN if one was set during lock. */
+    unlock(pin: string): void;
+    /**
+     * Check if a transaction for the given amount is allowed.
+     * Auto-resets daily counter if the date has changed.
+     */
+    check(amount: string): CheckResult;
+    /** Record a completed spend. Call after successful transaction. */
+    recordSpend(amount: string): void;
+    /** Manually reset the daily counter. */
+    resetDaily(): void;
+    private autoResetDaily;
+    private save;
+}
+
+/**
+ * CheckingAccount — high-level USDCx checking account.
+ *
+ * Wraps USDCxService with safeguard checks and transaction history.
+ */
+
+interface SendOptions {
+    memo?: string;
+    commandId?: string;
+}
+interface TransactionRecord {
+    updateId: string;
+    commandId: string;
+    effectiveAt: string;
+    offset: number;
+    type: "send" | "receive" | "unknown";
+    amount?: string;
+    counterparty?: string;
+}
+declare class CheckingAccount {
+    private readonly usdcx;
+    private readonly safeguards;
+    private readonly client;
+    private readonly partyId;
+    constructor(usdcx: USDCxService, safeguards: SafeguardManager, client: CantonClient, partyId: string);
+    /** Get USDCx balance: total available and number of UTXO holdings. */
+    balance(): Promise<{
+        available: string;
+        holdingCount: number;
+    }>;
+    /**
+     * Send USDCx to a recipient.
+     * Checks safeguards before executing the transfer.
+     */
+    send(recipient: string, amount: string, opts?: SendOptions): Promise<TransferResult>;
+    /** Party ID for receiving payments. */
+    address(): string;
+    /**
+     * Query transaction history via /v2/updates/flats.
+     * Returns recent flat transactions involving this party.
+     */
+    history(opts?: {
+        limit?: number;
+    }): Promise<TransactionRecord[]>;
+}
+
+/**
+ * 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 }
+ */
+
+interface PayOptions {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    maxPrice?: string;
+}
+interface PayResult {
+    response: Response;
+    paid: boolean;
+    receipt?: {
+        updateId: string;
+        completionOffset: number;
+        commandId: string;
+        amount: string;
+    };
+}
+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"
+ */
+declare function parseWwwAuthenticate(header: string): PaymentChallenge | null;
+declare class MppPayClient {
+    private readonly usdcx;
+    private readonly safeguards;
+    private readonly partyId;
+    private readonly network;
+    constructor(usdcx: USDCxService, safeguards: SafeguardManager, partyId: string, network: string);
+    /**
+     * Pay for an API call via MPP 402 flow.
+     * If the response is not 402, returns it as-is with paid=false.
+     */
+    pay(url: string, opts?: PayOptions): Promise<PayResult>;
+}
+
+/**
+ * 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.
+ */
+
+interface TrafficBalance {
+    totalPurchased: number;
+    consumed: number;
+    remaining: number;
+}
+interface AutoPurchaseConfig {
+    enabled: boolean;
+    minBalance: number;
+    purchaseAmount: string;
+}
+declare class TrafficManager {
+    private readonly client;
+    private readonly partyId;
+    private autoPurchaseConfig;
+    constructor(client: CantonClient, 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.
+     */
+    trafficBalance(): Promise<TrafficBalance>;
+    /**
+     * Purchase additional traffic by burning Canton Coin (CC).
+     *
+     * TODO: Implement using actual CC burn mechanism.
+     */
+    purchaseTraffic(ccAmount: string): Promise<{
+        txId: string;
+    }>;
+    /**
+     * Check if there's sufficient traffic for a standard operation.
+     * Returns true if remaining traffic > minimum threshold.
+     */
+    hasSufficientTraffic(): Promise<boolean>;
+    /** Configure auto-purchase settings. */
+    setAutoPurchase(config: AutoPurchaseConfig): void;
+    /** Get current auto-purchase configuration. */
+    getAutoPurchaseConfig(): AutoPurchaseConfig;
+}
+
+/**
+ * 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)
+ */
+
+interface WalletInfo {
+    address: string;
+    partyId: string;
+    network: string;
+}
+interface CantonAgentConfig {
+    ledgerUrl?: string;
+    token?: string;
+    userId?: string;
+    partyId?: string;
+    network?: "mainnet" | "testnet" | "devnet";
+    configPath?: string;
+    safeguardsPath?: string;
+}
+declare class CantonAgent {
+    readonly checking: CheckingAccount;
+    readonly safeguards: SafeguardManager;
+    readonly traffic: TrafficManager;
+    readonly mpp: MppPayClient;
+    readonly wallet: WalletInfo;
+    private readonly client;
+    private readonly usdcx;
+    private constructor();
+    /**
+     * Create a new CantonAgent from config.
+     *
+     * Loads configuration from ~/.caypo/config.json (or overrides),
+     * initializes all sub-services, and wires them together.
+     */
+    static create(config?: CantonAgentConfig): Promise<CantonAgent>;
+    /**
+     * 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;
+}
+
+/**
+ * @caypo/canton-sdk — Core SDK for Canton Network.
+ * JSON Ledger API v2 client, USDCx operations, agent accounts.
+ */
+
+declare const CANTON_SDK_VERSION = "0.1.0";
+declare const DEFAULT_LEDGER_PORT = 7575;
+
+export { type ActiveContract, type ActiveContractsRequest, type AgentConfig, type AnyPartyFilter, type ArchivedEvent, type AutoPurchaseConfig, CANTON_SDK_VERSION, CantonAgent, type CantonAgentConfig, CantonApiError, CantonAuthError, CantonClient, type CantonClientConfig, type CantonErrorCode, CantonTimeoutError, type CheckResult, CheckingAccount, type Command, type CreateCommand, type CreatedEvent, DEFAULT_CONFIG, DEFAULT_LEDGER_PORT, type EventFormat, type ExerciseCommand, type ExercisedEvent, type FlatTransaction, type HoldingSelection, type IdentifierFilter, InsufficientBalanceError, Keystore, type LedgerEndResponse, type LedgerError, type MppConfig, MppPayClient, type PartyDetails, type PartyFilter, type PartyLocalMetadata, type PayOptions, type PayResult, type PaymentChallenge, type QueryActiveContractsParams, type SafeguardConfig, SafeguardManager, type SafeguardsConfig, type SendOptions, type SubmitAndWaitRequest, type SubmitAndWaitResponse, type SubmitParams, TRANSFER_FACTORY_TEMPLATE_ID, type TrafficBalance, type TrafficConfig, TrafficManager, type TransactionRecord, type TransactionResponse, type TransactionTree, type TransactionTreeEvent, type TransferParams, type TransferResult, USDCX_HOLDING_TEMPLATE_ID, USDCX_INSTRUMENT_ID, type USDCxHolding, USDCxService, type WalletData, type WalletInfo, addAmounts, compareAmounts, isValidAmount, loadConfig, parseWwwAuthenticate, saveConfig, selectHoldings, subtractAmounts, toCantonAmount };