@ftptech/canton-agent-wallet 1.1.0 → 1.3.0

package/dist/registry-parties.js

@@ -36,14 +36,82 @@ export const REGISTRY_TRUSTED_PARTIES_ENV = "CANTON_AGENT_REGISTRY_TRUSTED_PARTI
  * the xReserve Bridge-Operator, both confirmed on a live MainNet USDCx
  * `TransferFactory_Transfer`.
  */
+/** DA Registry Utility operator, shared by EVERY instrument the utility hosts
+ *  (verified live at /api/utilities/v0/operator — identical for USDCx, CBTC,
+ *  USDXLR, cETH). It appears on every DA-Utility `TransferFactory_Transfer`. */
+const DA_UTILITY_OPERATOR = "auth0_007c6643538f2eadd3e573dd05b9::12205bcc106efa0eaa7f18dc491e5c6f5fb9b0cc68dc110ae66f4ed6467475d7c78e";
 export const KNOWN_REGISTRY_TRUSTED_PARTIES = {
     "decentralized-usdc-interchain-rep::12208115f1e168dd7e792320be9c4ca720c751a02a3053c7606e1c1cd3dad9bf60ef": [
         // DA Registry Utility operator (from /api/utilities/v0/operator).
-        "auth0_007c6643538f2eadd3e573dd05b9::12205bcc106efa0eaa7f18dc491e5c6f5fb9b0cc68dc110ae66f4ed6467475d7c78e",
+        DA_UTILITY_OPERATOR,
         // xReserve Bridge-Operator (mints/burns USDCx; signatory on the holding).
         "Bridge-Operator::1220c8448890a70e65f6906bd48d797ee6551f094e9e6a53e329fd5b2b549334f13f",
     ],
+    // CBTC (BitSafe), USDXLR (Excellar), cETH (onRails) — all DA Registry Utility
+    // instruments, so each carries the shared operator above. A token-specific infra
+    // party is added when its transfers reference one: CBTC declares a fee/config
+    // "cbtc-beneficiary" party in its registrar-authored InstrumentConfiguration
+    // (verified: it appears only in the authenticated InstrumentConfiguration input
+    // contract — never as a value owner or recipient — so a relay cannot forge it).
+    // cETH instead uses per-user parties minted UNDER ITS OWN NAMESPACE, which are
+    // trusted generically by the same-namespace rule in @ftptech/x402-canton-core's
+    // foreign-party backstop, so none need listing here.
+    "cbtc-network::12205af3b949a04776fc48cdcc05a060f6bda2e470632935f375d1049a8546a3b262": [
+        DA_UTILITY_OPERATOR,
+        // CBTC beneficiary declared in the registrar's InstrumentConfiguration.
+        "cbtc-beneficiary::1220409a9fcc5ff6422e29ab978c22c004dde33202546b4bcbde24b25b85353366c2",
+    ],
+    "excellar-issuer::12203d1e36930ee0e3fbb898add7e222a47ae9d2a5f0f6187e3a446ea32f871ce2ca": [DA_UTILITY_OPERATOR],
+    "rails-cethMain-1::12200350ba6e96e3b701c3048b5aa013a8c1c08833e8ebf54339cff581055c29003a": [DA_UTILITY_OPERATOR],
+    "ember-silver::1220ad9c097ae75192b4716854fa413aa8582c86a62b16714663cdab55e025cc79c4": [DA_UTILITY_OPERATOR],
+    "ember-gold::1220ad9c097ae75192b4716854fa413aa8582c86a62b16714663cdab55e025cc79c4": [DA_UTILITY_OPERATOR],
+};
+/** MainNet symbol → {admin, id} for the DA Registry Utility instruments this
+ *  wallet knows out of the box (all `decimals: 10`). Canton Coin is NOT here —
+ *  it is the native Amulet, named by omitting an instrument. Used by `swap` to
+ *  resolve `--in USDCx` locally; the fee-ticket path (facilitator /swap) carries
+ *  its own resolved instruments, which take precedence on DevNet/other networks. */
+export const KNOWN_INSTRUMENTS = {
+    USDCx: {
+        admin: "decentralized-usdc-interchain-rep::12208115f1e168dd7e792320be9c4ca720c751a02a3053c7606e1c1cd3dad9bf60ef",
+        id: "USDCx",
+    },
+    CBTC: {
+        admin: "cbtc-network::12205af3b949a04776fc48cdcc05a060f6bda2e470632935f375d1049a8546a3b262",
+        id: "CBTC",
+    },
+    USDXLR: {
+        admin: "excellar-issuer::12203d1e36930ee0e3fbb898add7e222a47ae9d2a5f0f6187e3a446ea32f871ce2ca",
+        id: "USDXLR",
+    },
+    cETH: {
+        admin: "rails-cethMain-1::12200350ba6e96e3b701c3048b5aa013a8c1c08833e8ebf54339cff581055c29003a",
+        id: "cETH",
+    },
+    // Ember tokenized metals (eXAG = silver, eXAU = gold), both DA Registry Utility
+    // instruments (live metadata resolves, decimals 10) — same shared packages, no new
+    // DARs to receive; ids verified from Tradecraft's /v1/tokenB and the DA Utility.
+    eXAG: {
+        admin: "ember-silver::1220ad9c097ae75192b4716854fa413aa8582c86a62b16714663cdab55e025cc79c4",
+        id: "eXAG",
+    },
+    eXAU: {
+        admin: "ember-gold::1220ad9c097ae75192b4716854fa413aa8582c86a62b16714663cdab55e025cc79c4",
+        id: "eXAU",
+    },
 };
+export function resolveSwapSymbol(symbol) {
+    const s = symbol.trim().toLowerCase();
+    if (s === "cc" || s === "canton-coin" || s === "amulet") {
+        return { kind: "cc", symbol: "CC" };
+    }
+    for (const [sym, instrument] of Object.entries(KNOWN_INSTRUMENTS)) {
+        if (sym.toLowerCase() === s) {
+            return { kind: "registry", symbol: sym, instrument };
+        }
+    }
+    return { kind: "unknown" };
+}
 /** Parse the env JSON (admin → party[]) fail-closed to `{}` on any malformation. */
 function parseEnvTrustedParties(raw) {
     if (!raw || raw.trim().length === 0)

package/dist/registry-parties.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry-parties.js","sourceRoot":"","sources":["../src/registry-parties.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"registry-parties.js","sourceRoot":"","sources":["../src/registry-parties.ts"],"names":[],"mappings":"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"}

package/dist/swap.d.ts

@@ -0,0 +1,204 @@
+/**
+ * swap — a self-custody swap primitive over Tradecraft (an AMM DEX on Canton).
+ * A Tradecraft swap is just an on-ledger transfer of the input token to a
+ * per-pair pool party (`tc-swp_{IN}-{OUT}::<amm_cid>`); the pool sends the
+ * counter-asset back within a minute or two, as a transfer OFFER when the output
+ * is not pre-approved (which `claimAll` accepts) or DIRECTLY when it is.
+ *
+ * SAFETY MODEL (what actually holds):
+ *  - The recipient is ALWAYS a pool party derived from a trusted `amm_cid`
+ *    (config/constant), never a client- or 402-supplied address. This is the one
+ *    unconditional guarantee.
+ *  - Slippage protection is OPTIONAL: Tradecraft reads the minimum from the
+ *    transfer's memo field, so it is attached only when a memo key is configured
+ *    (`ticket.memoKey`, from CANTON_AGENT_TRADECRAFT_MEMO_KEY). With NO key the
+ *    swap fills at MARKET price — the proven bare flow — and `swap` warns.
+ *  - Output preapproval is OPT-IN (`preapproveOutput`, `--preapprove`): default is
+ *    the offer/claim path. Tradecraft's docs note the hazard that on a DIRECT
+ *    settlement an un-preapproved output can be "consumed on fill with no funds
+ *    returned"; the default path avoids direct settlement by not pre-approving, so
+ *    the return arrives as a claimable offer instead. An unfilled trade returns
+ *    the input either way.
+ */
+import { RelayClient } from "./relay-client.js";
+import { type AgentWallet } from "./store.js";
+import type { HashBindingOptions } from "./verify-prepared.js";
+/** A registry instrument, or `null` for native Canton Coin. */
+export type SwapInstrument = {
+    admin: string;
+    id: string;
+} | null;
+/** Everything needed to execute one swap, resolved up front (locally, or by the
+ *  facilitator /swap fee-ticket which knows the network's registrars). */
+export interface SwapTicket {
+    /** The pool party to send the input to: `tc-swp_{IN}-{OUT}::<amm_cid>`. */
+    poolParty: string;
+    /** Slippage-protected minimum output, as a ledger decimal string. Always
+     *  computed for display; only ENFORCED when `memoKey` is set (see below). */
+    minOutput: string;
+    /** The transfer-meta key Tradecraft reads the minimum from ("the memo field").
+     *  When set, the minimum is attached to the input transfer and the pool honors
+     *  it (below-minimum → the trade fails and the input returns). When UNDEFINED,
+     *  the swap executes at market price with no slippage protection — exactly the
+     *  bare "send to the pool" flow, which works. Tradecraft's docs: the minimum is
+     *  the first text in the memo field, a decimal with ≤10 places. */
+    memoKey?: string;
+    /** The raw quote (estimated output) that produced `minOutput`. */
+    quote: string;
+    /** The instrument being sent in (null = CC). */
+    inInstrument: SwapInstrument;
+    /** The instrument expected back (null = CC). */
+    outInstrument: SwapInstrument;
+}
+/** Per-input-token advisory minimums, mirrored from the Tradecraft web app (there
+ *  is NO API endpoint for these — they are a hardcoded frontend constant). A trade
+ *  below the minimum is ADVISORY only: the pool safely returns the funds if it will
+ *  not fill (no loss), and amounts slightly under still often fill. `swap` warns
+ *  when the amount is under the listed minimum but does not block. Symbols not
+ *  listed have no advertised minimum. */
+export declare const TRADECRAFT_MIN_INPUT: Readonly<Record<string, number>>;
+/** The advisory minimum input for `symbol` (canonical), or undefined if none is
+ *  advertised. Case-sensitive on the canonical symbol. */
+export declare function tradecraftMinInput(symbol: string): number | undefined;
+/** Derive the Tradecraft pool party for a pair: `tc-swp_{TOKEN1}-{TOKEN2}::<ammCid>`.
+ *  `token1`/`token2` MUST be in the pool's CANONICAL order (as listed by /pools),
+ *  NOT the swap direction: Tradecraft has one pool party per pair that accepts
+ *  either token and returns the other, so `tc-swp_CC-USDCx` serves both CC→USDCx
+ *  and USDCx→CC. Deriving from the swap direction (`{in}-{out}`) yields a
+ *  non-existent party for one of the two directions. The amm_cid is a single
+ *  AMM-rules contract shared by every pair. Pure. */
+export declare function derivePoolParty(token1: string, token2: string, ammCid: string): string;
+/** One pool row from Tradecraft `/v1/pools`, reduced to what a swap needs: the
+ *  pair in the pool party's CANONICAL order. That order is the one in
+ *  `lp_token_name` ("TC {TOKEN1}-{TOKEN2} LP"), which is what the on-ledger pool
+ *  party `tc-swp_{TOKEN1}-{TOKEN2}::<ammCid>` uses — NOT the row's `token1`/`token2`
+ *  fields, which are ordered differently for 9 of 34 live pools (e.g. the CBTC/CC
+ *  pool lists token1=CC,token2=CBTC but its party and LP name are CBTC-CC). */
+export interface TradecraftPool {
+    /** First symbol of the pool party, from lp_token_name. */
+    token1: string;
+    /** Second symbol of the pool party, from lp_token_name. */
+    token2: string;
+}
+/** Parse `/v1/pools` into rows carrying each pool's CANONICAL pair order (from
+ *  `lp_token_name`, falling back to `token1`/`token2`). Tolerates a bare array or
+ *  `{pools:[…]}`. Exported for unit testing. */
+export declare function parseTradecraftPools(body: unknown): TradecraftPool[];
+/** Find the pool whose pair equals {a, b} (case-insensitive, unordered) and
+ *  return its CANONICAL token order (the pool party's order). Throws when no such
+ *  pool exists — exactly the "send to a non-existent pool party" mistake we must
+ *  not make. Exported for unit testing. */
+export declare function resolvePoolPair(pools: TradecraftPool[], a: string, b: string): {
+    token1: string;
+    token2: string;
+};
+/** Slippage-protected minimum output: `quote * (1 - slippagePct/100)`, floored to
+ *  10 decimals (every DA-Utility instrument and Canton Coin use 10). Floored, not
+ *  rounded — the minimum must never sit ABOVE the true floor, or an honest fill
+ *  could be rejected. `slippagePct` must be in [0, 100). Pure. */
+export declare function computeMinOutput(quote: number, slippagePct: number): string;
+/** Parse Tradecraft's `/v1/quoteForFixedInput/{IN}/{OUT}?givingAmount=N` →
+ *  `{ user_gets: number }`. Exported for unit testing the shape. */
+export declare function parseTradecraftQuote(body: unknown): number;
+/** Fetch a live quote from Tradecraft's public REST and build a ticket locally
+ *  (the `--no-fee` / test path). The fee path gets its ticket from the
+ *  facilitator /swap endpoint instead. */
+export declare function buildLocalTicket(opts: {
+    tradecraftApi: string;
+    ammCid: string;
+    /** The memo key that enforces the minimum; omit to swap at market. */
+    memoKey?: string;
+    inSymbol: string;
+    outSymbol: string;
+    amount: string;
+    slippagePct: number;
+    inInstrument: SwapInstrument;
+    outInstrument: SwapInstrument;
+    fetchImpl?: typeof globalThis.fetch;
+}): Promise<SwapTicket>;
+/** Parse a swap-endpoint ticket response into a SwapTicket, validating the fields
+ *  the local execute path relies on. Extra fields (e.g. ammCid) are ignored. */
+export declare function parseEndpointTicket(body: unknown): SwapTicket;
+/**
+ * Validate an endpoint-returned ticket against LOCALLY-TRUSTED values before it is
+ * ever executed. The swap endpoint is UNTRUSTED for money safety: the ticket's
+ * `poolParty` becomes the transfer receiver and its instruments become the assets
+ * moved, and verify-before-sign only pins those to caller INTENT — so if intent
+ * came from the endpoint unchecked, a malicious/compromised endpoint could name an
+ * attacker party and drain the swap amount. We therefore pin, client-side:
+ *   - `poolParty` MUST be `tc-swp_{A}-{B}::<trustedAmmCid>` for the two canonical
+ *     symbols the caller chose (either pair order) — its namespace equals our own
+ *     trusted amm_cid, which a hostile endpoint cannot forge, and its localpart is
+ *     the Tradecraft pool naming for exactly this pair;
+ *   - the in/out instruments MUST equal the ones the caller resolved locally from
+ *     KNOWN_INSTRUMENTS.
+ * The endpoint is then trusted ONLY for the price/minimum (a bad one loses at most
+ * a bad fill, which returns the input) — never for where the funds go.
+ */
+export declare function assertTicketMatchesIntent(ticket: SwapTicket, expect: {
+    inCanon: string;
+    outCanon: string;
+    inInstrument: SwapInstrument;
+    outInstrument: SwapInstrument;
+    trustedAmmCid: string;
+}): void;
+/** Fetch a swap ticket from OUR x402-gated `/swap` endpoint (the default path): the
+ *  managed router that stays current with Tradecraft's pools/amm_cid/minimums and
+ *  charges a small fee. `payingFetch` is a `makePayingFetch` result, so the 402 is
+ *  paid automatically from the agent's wallet. The endpoint is UNTRUSTED for money
+ *  safety — the returned ticket is validated against the caller's locally-trusted
+ *  amm_cid + instruments (see assertTicketMatchesIntent) before it is returned, so
+ *  a hostile endpoint can only give a bad price, never redirect funds. */
+export declare function fetchTicketFromEndpoint(opts: {
+    swapUrl: string;
+    inSymbol: string;
+    outSymbol: string;
+    amount: string;
+    slippagePct: number;
+    payingFetch: typeof globalThis.fetch;
+    /** Locally-resolved input instrument (null = CC) the ticket MUST match. */
+    inInstrument: SwapInstrument;
+    /** Locally-resolved output instrument (null = CC) the ticket MUST match. */
+    outInstrument: SwapInstrument;
+    /** The caller's OWN trusted amm_cid the pool party MUST derive from. */
+    trustedAmmCid: string;
+}): Promise<SwapTicket>;
+export interface ExecuteSwapOpts {
+    amount: string;
+    ticket: SwapTicket;
+    apiKey?: string | undefined;
+    hashBinding?: HashBindingOptions;
+    wallet?: AgentWallet;
+    relay?: RelayClient;
+    /**
+     * Self-provision a TransferPreapproval for the OUTPUT instrument before sending
+     * the input, so the pool can deliver the counter-asset DIRECTLY. This is
+     * REQUIRED for a registry output: a Tradecraft pool holds no preapproval for the
+     * payer and does not create a return offer, so without our preapproval the pool
+     * keeps the swapped-out asset (the trade does not complete on our side). Defaults
+     * to ON for a registry output (`outInstrument` set) and is a no-op for a CC
+     * output (Amulet needs none). Set false only to skip it deliberately (e.g. the
+     * preapproval already exists, or a test).
+     */
+    preapproveOutput?: boolean;
+    /** Injectable sleep + poll bounds for the return-claim (tests). */
+    sleep?: (ms: number) => Promise<void>;
+    claimAttempts?: number;
+    claimIntervalMs?: number;
+}
+export interface SwapResult {
+    /** updateId of the input transfer we sent to the pool. */
+    sentUpdateId: string;
+    /** How many returning transfers we claimed (0 if the pool settled directly to
+     *  our preapproval, or if it has not arrived within the poll window). */
+    claimed: number;
+    claimedUpdateIds: string[];
+}
+/**
+ * Execute a swap from a resolved ticket: (1) pre-approve the output instrument so
+ * the pool's return can never be a consumed-input-no-return loss, (2) send the
+ * input to the pool with the minimum in meta, (3) claim the returning transfer if
+ * it arrives as an offer rather than settling directly.
+ */
+export declare function executeSwap(opts: ExecuteSwapOpts): Promise<SwapResult>;
+//# sourceMappingURL=swap.d.ts.map

package/dist/swap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"swap.d.ts","sourceRoot":"","sources":["../src/swap.ts"],"names":[],"mappings":"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"}