@ftptech/canton-agent-wallet 2.2.0 → 2.3.1

package/README.md

@@ -24,22 +24,31 @@ Bin: `canton-agent-wallet`.
 ```
 canton-agent-wallet create --relay-url <url>        # generate + onboard a self-custody wallet (idempotent)
 canton-agent-wallet address                         # print the party id (fund this)
-canton-agent-wallet balance                         # print the balance of every instrument the wallet holds (CC + any CIP-56 registry token, e.g. USDCx)
+canton-agent-wallet balance                         # print the balance of every instrument the wallet holds (CC + any CIP-56 registry token, e.g. USDCx; "≥" when the wallet is too large to list in one read)
 canton-agent-wallet claim                           # accept incoming transfers — CC and registry tokens (expired offers are skipped; one bad offer never blocks the rest)
-canton-agent-wallet merge [--target <n>] [--batch <n>] [--max-rounds <n>] [--dry-run] [--admin <registrar> --id <instrument>]   # consolidate dust (CC, or a registry token) so a busy wallet can be enumerated + spent again
-canton-agent-wallet preapproval [--status] [--admin <DSO>] [--days <n>]   # MERCHANT: self-provision this wallet's own TransferPreapproval so transfer-factory payments settle in one round-trip (--status just checks)
-canton-agent-wallet pay --relay-url <url> <url>      # fetch a URL, auto-paying any x402 402 challenge
-canton-agent-wallet swap --in <SYM> --out <SYM> --amount <n> [--venue cantex|tradecraft|auto] [--slippage <pct>] [--direct] [--no-wait] [--max-fee <cc>] [--swap-merchant <party>] [--no-preapprove]   # swap CC <-> a CIP-56 registry token via Tradecraft; waits for the output to land (see below)
+canton-agent-wallet merge [--target <n>] [--batch <n>] [--max-rounds <n>] [--dry-run] [--yes] [--admin <registrar> --id <instrument> | --all-tokens]   # consolidate dust (CC, one registry token, or every trusted token) so a busy wallet can be enumerated + spent again
+canton-agent-wallet preapproval [--status] [--admin <DSO|registrar>] [--id <instrument>] [--days <n>]   # MERCHANT: self-provision this wallet's own TransferPreapproval so transfer-factory payments settle in one round-trip (--status just checks)
+canton-agent-wallet pay [--relay-url <url>] [--asset <symbol>] [--max <amount>] [--pay-to <party>] <url>   # fetch a URL, auto-paying any x402 402 challenge (--max caps one payment, --pay-to pins the payee)
+canton-agent-wallet swap --in <SYM> --out <SYM> --amount <n> [--venue cantex|tradecraft|auto] [--slippage <pct>] [--direct] [--no-wait] [--max-fee <cc>] [--swap-merchant <party>] [--no-preapprove]   # swap CC <-> a CIP-56 registry token on Cantex (default) or Tradecraft; waits for the output to land (see below)
 canton-agent-wallet withdraw --to <party> [--amount <n>] [--admin <registrar> --id <instrument>]   # send CC (default: full balance) or a registry token back out
 canton-agent-wallet export                           # print the private key (backup; guard it)
+canton-agent-wallet set-relay <url>                  # switch the relay saved in wallet.json (refuses one on another network)
 ```
 
 `create` and `pay` **require** a relay (facilitator) URL: pass `--relay-url
 <url>` or set `CANTON_AGENT_RELAY_URL`. There is no default: a stale built-in
 default would silently send payments to a dead host, so the CLI fails fast when
-none is given. `address`, `balance`, `claim`, `withdraw` and `export` reuse the
-relay stored in the wallet at `create` time. The current FTP facilitator is
-`https://facilitator.ftptech.xyz`.
+none is given. Every other command uses the relay stored in the wallet at
+`create` time, unless `--relay-url` / `CANTON_AGENT_RELAY_URL` names another for
+that run (said on stderr; the saved one is not changed). `set-relay <url>`
+changes the saved relay, after checking it settles on the wallet's network. The
+current FTP facilitator is `https://facilitator.ftptech.xyz`.
+
+`pay --max <amount>` caps what one payment may cost, in the unit of what is
+paid: with `--asset <token>` that token's own amount, otherwise Canton Coin (and
+a 402 asking for a token is then refused — add `--asset`). `--pay-to <party>`
+pins the only payee the wallet will sign for. Both refuse before anything is
+signed; without them `pay` pays whatever the 402 asks, as before.
 
 ### Merchant onboarding: self-provision a `TransferPreapproval`
 
@@ -77,7 +86,7 @@ batch collapses ~`--batch` amulets into ~2, restoring a spendable wallet:
 
 ```bash
 canton-agent-wallet merge --dry-run   # show the plan (counts + batches), change nothing
-canton-agent-wallet merge             # consolidate (defaults: --batch 90, --target 2, --max-rounds 30)
+canton-agent-wallet merge             # consolidate (defaults: --batch 70, --target 2, --max-rounds 30)
 canton-agent-wallet merge --yes       # required for a LARGE whale pass (>20 batches; see cost note)
 ```
 
@@ -94,7 +103,40 @@ holdings), so each batch is self-transferred for its exact total, holdings are
 read through the token-standard `HoldingV1` view, locked holdings are never used
 as inputs, and the default target is 1 holding. The registrar must be a known or
 trusted registry admin (`CANTON_AGENT_REGISTRY_TRUSTED_PARTIES` for one the
-wallet does not ship with).
+wallet does not ship with). The default batch is 90 for a registry token and 70
+for Canton Coin (a transaction is capped at 256 nodes: a registry input costs
+~1, an Amulet input ~3).
+
+**A wallet with more holdings than the participant lists in one read** (a
+merchant paid thousands of times in a token: the participant refuses an
+unbounded list past its element cap, 200 by default). The relay then answers a
+bounded read of the wallet's **oldest** holdings instead of an error, and
+`merge` works through it: merge a batch, read again — the merged holdings drop
+out and the ones behind them come into view. Because the size is unknown up
+front, such a run needs `--yes`, and `--max-rounds` (default 30) bounds it.
+A per-token merge can only work on its own token; when the oldest holdings are
+mostly another token's dust it says so and points at `--all-tokens`, which
+merges every token of a trusted registrar, the largest group in view first,
+until each is down to one holding:
+
+```bash
+canton-agent-wallet merge --all-tokens --dry-run
+canton-agent-wallet merge --all-tokens --yes
+```
+
+A current relay narrows each read to what was asked for: Canton Coin by its own
+templates, a token by its registry's holding template. So thousands of Canton
+Coin dust holdings no longer hide a token, or make its total a lower bound —
+only more holdings of that token's own registry than one read lists do (tokens
+of one registry share a template), and on an older relay any mix does.
+
+On such a wallet `balance` shows token totals as lower bounds ("≥"), `withdraw`
+spends the fewest holdings that cover the amount (and refuses a full-balance
+withdraw, whose amount it cannot know), and a swap into that token says it
+cannot confirm delivery instead of reporting a false timeout (it still claims a
+returned input during its window; `claim` picks up one that comes back later).
+Paying from it works while the amount is coverable from the visible holdings;
+otherwise the relay answers `holdings_merge_required` with the merge to run.
 
 For a wallet already too large to enumerate on-ledger, `merge` reads the holdings
 from the public SV Scan ACS snapshot (paginated, no node cap), sweeps over them
@@ -266,6 +308,9 @@ const r = await executeSwap({ amount: "60", ticket });      // sends, waits for
   settable via `--network <net>`.
 - `CANTON_AGENT_API_KEY`: only if the relay requires one (sent as the
   `X-Agent-Key` header).
+- `CANTON_AGENT_RELAY_TIMEOUT_MS`: per-request relay timeout (default 120000). A
+  timed-out read fails the command; a timed-out SUBMISSION is reported as
+  "outcome unknown" — check `balance` before retrying, it may have committed.
 - `HTTPS_PROXY` / `HTTP_PROXY` (or `ALL_PROXY`): if set, the CLI routes all
   relay calls through that proxy. Node's `fetch` does NOT honor these on its
   own, so behind a corporate/regional proxy you must set one of them or every

package/dist/cli-args.d.ts

@@ -100,4 +100,31 @@ export declare function preapprovalMode(args: readonly string[], env: Record<str
     mode: "legacy";
     operatorToken: string;
 };
+/**
+ * `pay --max <amount> [--pay-to <party>]` → the signer's spend limits.
+ *
+ * `--max` caps the payment in the unit of what is paid. With `--asset` naming a
+ * registry token that is that token's own ceiling; otherwise it is the Canton
+ * Coin ceiling, and a 402 that asks for a token is then refused by the signer
+ * (a CC number cannot cap a token whose unit is worth something else) with the
+ * hint to add `--asset`. An asset we cannot resolve cannot be capped, so it is
+ * refused rather than paid uncapped. Present-but-invalid values fail fast.
+ */
+export declare function payLimits(args: readonly string[], env?: NodeJS.ProcessEnv): {
+    kind: "ok";
+    maxPaymentValue?: string;
+    maxPaymentValueByInstrument?: Record<string, string>;
+    expectedPayTo?: string;
+} | {
+    kind: "error";
+    message: string;
+};
+/**
+ * The registry instrument id `preapproval` provisions for registrar `admin`:
+ * `--id` when given, else the one instrument this wallet knows for that
+ * registrar. Undefined when it cannot be decided — the caller must then
+ * require `--id` rather than guess (it used to default to USDCx for EVERY
+ * registrar, provisioning the wrong instrument for CBTC, USDXLR, …).
+ */
+export declare function preapprovalInstrumentId(args: readonly string[], admin: string): string | undefined;
 //# sourceMappingURL=cli-args.d.ts.map

package/dist/cli-args.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-args.d.ts","sourceRoot":"","sources":["../src/cli-args.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,eAAe,mBAAmB,CAAC;AAEhD,8EAA8E;AAC9E,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,MAAM,CAyB1C,CAAC;AAEH,gEAAgE;AAChE,wBAAgB,IAAI,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAU9E;AAED;;0EAE0E;AAC1E,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAE1E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAUvE;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CACrB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,SAAS,CAQpB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAW7D;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,GAAG,SAAS,CAEpB;AAED,+EAA+E;AAC/E,wBAAgB,cAAc,CAC5B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CAER;AAED,iEAAiE;AACjE,eAAO,MAAM,kBAAkB,QAEkD,CAAC;AAElF;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAY5F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACtC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CASvF"}
+{"version":3,"file":"cli-args.d.ts","sourceRoot":"","sources":["../src/cli-args.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,eAAO,MAAM,eAAe,mBAAmB,CAAC;AAEhD,8EAA8E;AAC9E,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,MAAM,CA8B1C,CAAC;AAEH,gEAAgE;AAChE,wBAAgB,IAAI,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAU9E;AAED;;0EAE0E;AAC1E,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAE1E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAUvE;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CACrB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,SAAS,CAQpB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAW7D;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,GAAG,SAAS,CAEpB;AAED,+EAA+E;AAC/E,wBAAgB,cAAc,CAC5B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CAER;AAED,iEAAiE;AACjE,eAAO,MAAM,kBAAkB,QAEkD,CAAC;AAElF;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAY5F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACtC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CASvF;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,GAAG,GAAE,MAAM,CAAC,UAAwB,GAElC;IACE,IAAI,EAAE,IAAI,CAAC;IACX,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,2BAA2B,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrD,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GACD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CA+CrC;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,KAAK,EAAE,MAAM,GACZ,MAAM,GAAG,SAAS,CAKpB"}

package/dist/cli-args.js

@@ -5,6 +5,7 @@
  * `cli.ts` (which auto-runs `main()` on import and would call
  * `process.exit`). `cli.ts` composes these with its env + `fail()`.
  */
+import { envTrustedRegistryAdmins, instrumentKey, KNOWN_INSTRUMENTS, resolveSwapSymbol, } from "./registry-parties.js";
 export const DEFAULT_NETWORK = "canton:testnet";
 /** Known `--flag <value>` options; used to strip flags out of positionals. */
 export const VALUE_FLAGS = new Set([
@@ -32,6 +33,11 @@ export const VALUE_FLAGS = new Set([
     "--expires-at",
     "--days",
     "--operator-token",
+    "--id",
+    "--venue",
+    // pay: spend ceiling and payee pin.
+    "--max",
+    "--pay-to",
 ]);
 /** First value following `--<name>` in `args`, or undefined. */
 export function flag(args, name) {
@@ -178,4 +184,72 @@ export function preapprovalMode(args, env) {
         ambientIgnored: Boolean(env["CANTON_X402_OPERATOR_TOKEN"]),
     };
 }
+/**
+ * `pay --max <amount> [--pay-to <party>]` → the signer's spend limits.
+ *
+ * `--max` caps the payment in the unit of what is paid. With `--asset` naming a
+ * registry token that is that token's own ceiling; otherwise it is the Canton
+ * Coin ceiling, and a 402 that asks for a token is then refused by the signer
+ * (a CC number cannot cap a token whose unit is worth something else) with the
+ * hint to add `--asset`. An asset we cannot resolve cannot be capped, so it is
+ * refused rather than paid uncapped. Present-but-invalid values fail fast.
+ */
+export function payLimits(args, env = process.env) {
+    const out = { kind: "ok" };
+    if (flagPresent(args, "--pay-to")) {
+        const to = flag(args, "--pay-to")?.trim();
+        if (!to)
+            return { kind: "error", message: "pay --pay-to was given with no party — refusing." };
+        out.expectedPayTo = to;
+    }
+    if (!flagPresent(args, "--max"))
+        return out;
+    const raw = flag(args, "--max")?.trim() ?? "";
+    if (!/^\d+(\.\d+)?$/.test(raw) || Number(raw) <= 0) {
+        return {
+            kind: "error",
+            message: `pay --max must be a positive amount (got ${JSON.stringify(raw)}) — refusing to pay uncapped.`,
+        };
+    }
+    const asset = flag(args, "--asset");
+    if (asset === undefined) {
+        out.maxPaymentValue = raw;
+        return out;
+    }
+    const sym = resolveSwapSymbol(asset);
+    if (sym.kind === "cc") {
+        out.maxPaymentValue = raw;
+    }
+    else if (sym.kind === "registry") {
+        // Keyed on the MainNet registrar AND every registrar trusted through
+        // CANTON_AGENT_REGISTRY_TRUSTED_PARTIES: on testnet/devnet the same symbol
+        // comes from such a registrar, and a cap keyed only on the MainNet one would
+        // never apply there. The signer looks the cap up by the instrument actually
+        // paid, so a key for a registrar that does not issue this id is inert.
+        const admins = new Set([sym.instrument.admin, ...envTrustedRegistryAdmins(env)]);
+        out.maxPaymentValueByInstrument = Object.fromEntries([...admins].map((admin) => [instrumentKey(admin, sym.instrument.id), raw]));
+    }
+    else {
+        return {
+            kind: "error",
+            message: `pay --max with --asset ${asset}: that asset is not one this wallet knows, so the cap ` +
+                `cannot be applied to it — refusing to pay uncapped.`,
+        };
+    }
+    return out;
+}
+/**
+ * The registry instrument id `preapproval` provisions for registrar `admin`:
+ * `--id` when given, else the one instrument this wallet knows for that
+ * registrar. Undefined when it cannot be decided — the caller must then
+ * require `--id` rather than guess (it used to default to USDCx for EVERY
+ * registrar, provisioning the wrong instrument for CBTC, USDXLR, …).
+ */
+export function preapprovalInstrumentId(args, admin) {
+    const explicit = flag(args, "--id")?.trim();
+    if (explicit)
+        return explicit;
+    const known = Object.values(KNOWN_INSTRUMENTS).filter((i) => i.admin === admin);
+    return known.length === 1 ? known[0].id : undefined;
+}
 //# sourceMappingURL=cli-args.js.map

package/dist/cli-args.js.map

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

package/dist/cli.js

@@ -6,7 +6,7 @@
  *   address                      print the party id (fund this)
  *   balance                      print every instrument the wallet holds (CC + registry tokens)
  *   claim                        accept incoming transfers (e.g. the initial funding)
- *   merge [--target <n>] [--batch <n>] [--max-rounds <n>] [--dry-run] [--yes] [--admin <registrar> --id <instrument>]
+ *   merge [--target <n>] [--batch <n>] [--max-rounds <n>] [--dry-run] [--yes] [--admin <registrar> --id <instrument> | --all-tokens]
  *                                consolidate dust amulets (self-transfer in batches)
  *                                so a wallet with thousands of holdings can be
  *                                enumerated + spent again. --dry-run prints the plan;
@@ -18,13 +18,13 @@
  *                                transfer-factory path — SELF-provisions the
  *                                merchant's own preapproval so x402 CC payments
  *                                settle in one round-trip. --status just checks.
- *   pay [--relay-url <url>] [--asset <symbol>] <url>  fetch a URL, auto-paying any
+ *   pay [--relay-url <url>] [--asset <symbol>] [--max <amount>] [--pay-to <party>] <url>  fetch a URL, auto-paying any
  *                                x402 402 challenge; --asset prefers that
  *                                instrument (e.g. USDCx) when the 402 offers
  *                                several, else the first compatible entry
  *   withdraw --to <p>            send CC back out (--amount <cc> for a partial amount)
- *   swap --in <SYM> --out <SYM> --amount <n> [--slippage <pct>] [--direct] [--no-wait]
- *                                swap on Tradecraft: pre-approve the output, send
+ *   swap --in <SYM> --out <SYM> --amount <n> [--venue cantex|tradecraft|auto] [--slippage <pct>] [--direct] [--no-wait]
+ *                                swap on Cantex (default) or Tradecraft: pre-approve the output, send
  *                                the input to the pool, and WAIT until the output
  *                                lands (no manual claim). By DEFAULT the ticket (pool,
  *                                minimum, amm_cid) comes from our x402 swap endpoint (a
@@ -36,14 +36,17 @@
  *   export                       print the private key (backup; guard it)
  *   import [--relay-url <url>] [--key-file <p>]  restore a wallet from a backed-up
  *                                key (stdin or --key-file); inverse of export
+ *   set-relay <url>              switch the relay saved in wallet.json (checks it
+ *                                settles on this wallet's network first)
  *
  * The relay (facilitator) URL is REQUIRED for the commands that talk to a
  * relay (`create`, `pay`, `import`). There is intentionally no built-in default — a
  * wrong/stale default would silently send an agent's payments to a dead host.
  * Supply it via `--relay-url <url>` or the `CANTON_AGENT_RELAY_URL` env var.
- * The current FTP facilitator is `https://facilitator.ftptech.xyz`. `address`,
- * `balance`, `claim`, `withdraw` and `export` reuse the relay stored in the
- * wallet at `create` time and do not need the flag.
+ * The current FTP facilitator is `https://facilitator.ftptech.xyz`. Every other
+ * command uses the relay saved in the wallet at `create` time, unless
+ * `--relay-url` / CANTON_AGENT_RELAY_URL names another one for that run;
+ * `set-relay` changes the saved one.
  *
  * Behind a proxy? Node's fetch ignores HTTP(S)_PROXY by default; this CLI wires
  * an undici ProxyAgent when HTTPS_PROXY/HTTP_PROXY/ALL_PROXY is set (see proxy.ts).
@@ -54,18 +57,18 @@
 /* eslint-disable no-console -- CLI entrypoint: stdout is its result channel */
 import { readFileSync } from "node:fs";
 import { ensureWallet } from "./onboard.js";
-import { loadWallet } from "./store.js";
+import { loadWallet, saveWallet, walletPath } from "./store.js";
 import { agentKeyFromPrivatePem } from "./keys.js";
 import { makePayingFetch } from "./pay.js";
 import { RelayClient, isHoldingsExceedNodeLimitError } from "./relay-client.js";
 import { claimAll, selfProvisionPreapproval, selfProvisionRegistryPreapproval, } from "./tx.js";
 import { isTrustedRegistryAdmin } from "./registry-parties.js";
-import { mergeHoldings } from "./merge.js";
+import { mergeHoldings, mergeAllRegistryHoldings } from "./merge.js";
 import { withdraw } from "./withdraw.js";
 import { executeSwap } from "./swap.js";
 import { resolveSwapIntent, resolveSwapTicket, swapFloorNotes, parseSwapVenue, parseSlippagePct, SWAP_MAX_FEE_CC, } from "./swap-route.js";
 import { installProxyFromEnv } from "./proxy.js";
-import { flag, boolFlag, intFlag, positionals, resolveNetwork, resolveRelayUrl, MISSING_RELAY_HELP, withdrawAmount, preapprovalMode, } from "./cli-args.js";
+import { flag, boolFlag, intFlag, positionals, resolveNetwork, resolveRelayUrl, MISSING_RELAY_HELP, withdrawAmount, preapprovalMode, payLimits, preapprovalInstrumentId, } from "./cli-args.js";
 import { resolveTrustedDsoParty } from "./trusted-dso.js";
 const API_KEY = process.env.CANTON_AGENT_API_KEY;
 function fail(msg) {
@@ -94,11 +97,34 @@ async function main() {
     if (proxy)
         console.error(`(using proxy ${proxy})`);
     const [cmd, ...args] = process.argv.slice(2);
+    /** The relay this run talks to: `--relay-url` / CANTON_AGENT_RELAY_URL when
+     *  given, else the one saved at `create`. A flag that was silently ignored
+     *  pointed commands at the old relay after a cut-over; now it wins, and is
+     *  never written back (`set-relay` does that on purpose). */
+    const relayFor = (w) => {
+        const url = resolveRelayUrl(args);
+        if (!url || url === w.relayUrl)
+            return w;
+        console.error(`(using relay ${url}; this wallet's saved relay is ${w.relayUrl} — ` +
+            `\`canton-agent-wallet set-relay <url>\` changes it)`);
+        return { ...w, relayUrl: url };
+    };
+    const requireWallet = () => {
+        const w = loadWallet();
+        if (!w)
+            return fail("no wallet yet — run: canton-agent-wallet create");
+        return relayFor(w);
+    };
     switch (cmd) {
         case "create": {
             const relayUrl = requireRelay(args);
-            if (!loadWallet())
+            const existing = loadWallet();
+            if (!existing)
                 console.error("creating the wallet (takes about half a minute)…");
+            else if (existing.relayUrl !== relayUrl) {
+                console.error(`a wallet already exists; it keeps its saved relay ${existing.relayUrl}. ` +
+                    `To switch it to ${relayUrl}: canton-agent-wallet set-relay ${relayUrl}`);
+            }
             // A relay that funds new wallets sends a starter grant; ensureWallet
             // waits for it and accepts it before returning.
             const grant = {};
@@ -122,7 +148,7 @@ async function main() {
                 `  party:   ${w.party}\n` +
                 starterLine +
                 `  fund me: send CC to that party id, then run: canton-agent-wallet claim\n` +
-                `  keyfile: ~/.canton-agent/wallet.json  <- this IS your wallet; back it up\n` +
+                `  keyfile: ${walletPath()}  <- this IS your wallet; back it up\n` +
                 `  By creating a wallet you accept the Terms of Service: https://ftp-tech.mintlify.site/terms`);
             break;
         }
@@ -134,9 +160,7 @@ async function main() {
             break;
         }
         case "balance": {
-            const w = loadWallet();
-            if (!w)
-                return fail("no wallet yet — run: canton-agent-wallet create");
+            const w = requireWallet();
             try {
                 const relay = new RelayClient({ relayUrl: w.relayUrl, apiKey: API_KEY });
                 const b = await relay.balance(w.party);
@@ -145,19 +169,39 @@ async function main() {
                 // and printed after CC on purpose: a relay that predates /holdings makes
                 // this line throw, and a wallet must keep showing its Canton Coin on an
                 // older relay rather than fail the whole command over a token listing.
+                //
+                // Read BOUNDED: a wallet with more holdings than the participant lists in
+                // one read gets part of them (complete:false). The totals are then
+                // lower bounds, shown as "≥", with the command that makes them exact —
+                // this line used to swallow that 413 and print nothing at all, so a
+                // wallet full of USDCx looked like it held only Canton Coin. Only the
+                // tokens are asked for (`registryOnly`): on a current relay Canton Coin
+                // dust then no longer turns every token total into a lower bound.
                 try {
-                    const h = await relay.holdings(w.party);
+                    const h = await relay.holdings(w.party, undefined, { slice: true, registryOnly: true });
+                    const ge = h.complete ? "" : "≥ ";
                     for (const ins of h.instruments) {
                         if (ins.id === "Amulet")
                             continue; // already printed as CC above
                         const locked = ins.holdings.filter((x) => x.locked).length;
-                        console.log(`${ins.total} ${ins.id}  (${ins.holdings.length} holding${ins.holdings.length === 1 ? "" : "s"}` +
+                        console.log(`${ge}${ins.total} ${ins.id}  (${ge}${ins.holdings.length} holding${ins.holdings.length === 1 ? "" : "s"}` +
                             (locked ? `, ${locked} locked` : "") +
                             `)  @ ${ins.admin}`);
                     }
+                    if (!h.complete) {
+                        console.log("  (this wallet holds more than the participant lists in one read — token totals above " +
+                            "are lower bounds; consolidate with: canton-agent-wallet merge --all-tokens, " +
+                            "and plain `canton-agent-wallet merge` for Canton Coin dust)");
+                    }
                 }
-                catch {
-                    /* older relay without /holdings — CC line above already shown */
+                catch (err) {
+                    // An older relay without /holdings answers Fastify's route-not-found;
+                    // that stays quiet (the CC line above is the whole answer there). Any
+                    // other failure is said, not swallowed.
+                    const notServed = err instanceof Error && /-> 404 .*Route GET:/.test(err.message);
+                    if (!notServed) {
+                        console.error(`tokens: could not list (${err instanceof Error ? err.message.split("\n")[0] : String(err)})`);
+                    }
                 }
             }
             catch (err) {
@@ -177,9 +221,7 @@ async function main() {
             // Consolidate dust amulets by self-transferring them in batches (receiver ==
             // this wallet, enforced by verify-before-sign). Restores `balance`/`pay` for
             // a wallet whose amulet count outgrew the participant's ACS element cap.
-            const w = loadWallet();
-            if (!w)
-                return fail("no wallet yet — run: canton-agent-wallet create");
+            const w = requireWallet();
             const target = intFlag(args, "--target");
             const batch = intFlag(args, "--batch");
             const maxRounds = intFlag(args, "--max-rounds");
@@ -195,6 +237,24 @@ async function main() {
             if ((mAdmin && !mId) || (!mAdmin && mId)) {
                 return fail("merge: --admin <registrar> and --id <instrument> must be given together");
             }
+            // --all-tokens: every token of a trusted registrar, whatever the mix — the
+            // way through a wallet whose oldest holdings are another token's dust.
+            if (boolFlag(args, "--all-tokens")) {
+                if (mAdmin)
+                    return fail("merge: --all-tokens merges every trusted token — drop --admin/--id");
+                const res = await mergeAllRegistryHoldings(new RelayClient({ relayUrl: w.relayUrl, apiKey: API_KEY }), w, {
+                    ...(batch !== undefined ? { batch } : {}),
+                    ...(maxRounds !== undefined ? { maxRounds } : {}),
+                    dryRun,
+                    yes,
+                    onProgress: (line) => console.log(line),
+                });
+                if (!dryRun) {
+                    console.log(`merge complete: ${res.rounds} batch transfer(s), ${res.merged.length} token holding(s) consumed` +
+                        (res.skippedStale > 0 ? ` (${res.skippedStale} stale batch(es) skipped)` : ""));
+                }
+                break;
+            }
             if (mAdmin && !isTrustedRegistryAdmin(mAdmin, process.env)) {
                 return fail(`merge: ${mAdmin} is not a known registry admin — add it via ` +
                     `CANTON_AGENT_REGISTRY_TRUSTED_PARTIES before merging its token`);
@@ -218,16 +278,16 @@ async function main() {
                     `${res.merged.length} ${mId ? `${mId} holding(s)` : "amulet(s)"} consumed` +
                     (extras.length ? ` (${extras.join(", ")})` : "") +
                     (res.finalHoldings === null
-                        ? " — remaining holdings predate this run; re-run `merge` after the next " +
-                            "Scan snapshot (~12:00 UTC daily) to continue"
+                        ? mId
+                            ? " — more remain than one read lists; see above"
+                            : " — remaining holdings predate this run; re-run `merge` after the next " +
+                                "Scan snapshot (~12:00 UTC daily) to continue"
                         : ` → ${res.finalHoldings} holding(s) remain`));
             }
             break;
         }
         case "claim": {
-            const w = loadWallet();
-            if (!w)
-                return fail("no wallet yet — run: canton-agent-wallet create");
+            const w = requireWallet();
             const r = await claimAll(new RelayClient({ relayUrl: w.relayUrl, apiKey: API_KEY }), w);
             // Say what happened to EVERY pending row, not just the claimed ones. An
             // expired offer is skipped (the ledger would refuse its accept); a failed
@@ -269,9 +329,7 @@ async function main() {
             //                      pays the fee) — ONLY works if the merchant delegated
             //                      CanActAs to the facilitator user; NOT for
             //                      self-custody merchants. Prefer the self default.
-            const w = loadWallet();
-            if (!w)
-                return fail("no wallet yet — run: canton-agent-wallet create");
+            const w = requireWallet();
             const admin = flag(args, "--admin") ||
                 resolveTrustedDsoParty(process.env, w.network) ||
                 "";
@@ -355,7 +413,11 @@ async function main() {
             // client's trusted-registry table/env, so an arbitrary --admin cannot be
             // blind-trusted.
             if (isTrustedRegistryAdmin(admin, process.env)) {
-                const id = flag(args, "--id") || "USDCx";
+                const id = preapprovalInstrumentId(args, admin);
+                if (id === undefined) {
+                    return fail(`preapproval: pass --id <instrument> — this wallet does not know which instrument ` +
+                        `${admin} issues, and provisioning the wrong one is not harmless`);
+                }
                 // ABSENCE MUST BE PROVEN BEFORE CREATING, because this create is not
                 // idempotent: run it twice and the merchant ends up with two live
                 // Utility.Registry TransferPreapproval contracts for the same
@@ -393,7 +455,7 @@ async function main() {
             // DEFAULT: SELF-provision with the merchant's OWN key — no token, no
             // delegation. The merchant prepays the fee from its own CC.
             try {
-                const res = await selfProvisionPreapproval(relay, w, { expiresAt });
+                const res = await selfProvisionPreapproval(relay, w, { expiresAt, dso: admin });
                 console.log(`TransferPreapproval self-provisioned for ${w.party} (ready for transfer-factory payments)\n` +
                     `  provider:  ${w.party} (self)\n` +
                     `  expiresAt: ${expiresAt}\n` +
@@ -414,7 +476,7 @@ async function main() {
         case "pay": {
             const url = positionals(args)[0];
             if (!url)
-                return fail("usage: canton-agent-wallet pay [--relay-url <url>] [--asset <symbol>] <url>");
+                return fail("usage: canton-agent-wallet pay [--relay-url <url>] [--asset <symbol>] [--max <amount>] [--pay-to <party>] <url>");
             // Reuse the wallet's stored relay (like claim/balance) when neither
             // --relay-url nor CANTON_AGENT_RELAY_URL is given, so an already-created
             // agent can pay without re-specifying the relay each time.
@@ -426,11 +488,22 @@ async function main() {
             // Selection only; spending a registry token still needs
             // CANTON_AGENT_PAYABLE_INSTRUMENTS.
             const preferAsset = flag(args, "--asset");
+            // --max caps what one payment may cost (in the paid asset's own unit);
+            // --pay-to pins the only payee the wallet will sign for. Both refuse
+            // BEFORE anything is signed; see payLimits.
+            const limits = payLimits(args);
+            if (limits.kind === "error")
+                return fail(limits.message);
             const f = await makePayingFetch({
                 relayUrl,
                 network: existing?.network ?? resolveNetwork(args),
                 apiKey: API_KEY,
                 ...(preferAsset ? { preferAsset } : {}),
+                ...(limits.maxPaymentValue !== undefined ? { maxPaymentValue: limits.maxPaymentValue } : {}),
+                ...(limits.maxPaymentValueByInstrument !== undefined
+                    ? { maxPaymentValueByInstrument: limits.maxPaymentValueByInstrument }
+                    : {}),
+                ...(limits.expectedPayTo !== undefined ? { expectedPayTo: limits.expectedPayTo } : {}),
             });
             const res = await f(url);
             console.log(`${res.status} ${res.statusText}`);
@@ -470,6 +543,7 @@ async function main() {
             }
             const r = await withdraw({
                 to,
+                wallet: requireWallet(),
                 ...(amt.kind === "amount" ? { amount: amt.amount } : {}),
                 ...(wAdmin && wId ? { instrumentAdmin: wAdmin, instrumentId: wId } : {}),
                 apiKey: API_KEY,
@@ -550,6 +624,7 @@ async function main() {
             const sr = await executeSwap({
                 amount,
                 ticket,
+                ...(existing ? { wallet: relayFor(existing) } : {}),
                 apiKey: API_KEY,
                 preapproveOutput: !boolFlag(args, "--no-preapprove"),
                 waitForOutput: wait,
@@ -568,6 +643,29 @@ async function main() {
                 console.log(`${head}\n  ! input RETURNED — nothing was swapped: the CC balance is back at its ` +
                     `pre-send level (the venue hands back a trade it will not fill, e.g. below its minimum)`);
             }
+            else if (sr.deliveryUnobservable) {
+                // Reached only after the input was sent (sentUpdateId above), so "do not
+                // resend" is true here. The wait claimed offers and watched for a
+                // returned input; only the delivery itself could not be seen.
+                console.log(`${head}\n  ! cannot confirm delivery: the relay cannot list every ${outCanon} holding of ` +
+                    `this wallet (more of that registry's holdings than the participant lists in one ` +
+                    `read), so the new one is out of view. The input WAS sent: do NOT resend. A trade ` +
+                    `the venue will not fill comes back as an offer — run \`canton-agent-wallet claim\` ` +
+                    `in a minute to pick it up. Run \`canton-agent-wallet merge --all-tokens\` (plain ` +
+                    `\`canton-agent-wallet merge\` first if Canton Coin dust fills the wallet), then ` +
+                    `check \`balance\`.` +
+                    (sr.partialRise !== undefined
+                        ? `\n  note: before that, the ${outCanon} balance rose ${sr.partialRise}, below the ` +
+                            `ticket minimum ${ticket.minOutput} — possibly an unrelated inbound, not this swap's fill`
+                        : "") +
+                    (sr.claimed > 0
+                        ? `\n  claimed ${sr.claimed} incoming transfer(s): ${sr.claimedUpdateIds.join(", ")}`
+                        : "") +
+                    (sr.pollErrors > 0
+                        ? `\n  ! ${sr.pollErrors} poll error(s) while waiting — the relay was flaky, but ` +
+                            "the input WAS sent (updateId above); do NOT resend, check `balance` first"
+                        : ""));
+            }
             else {
                 // Waited, no arrival: still settling, or a below-minimum trade whose input
                 // was returned (the per-tick claim picks that return up — `claimed` shows
@@ -626,8 +724,35 @@ async function main() {
                 `  run: canton-agent-wallet balance`);
             break;
         }
+        case "set-relay": {
+            // Change the relay SAVED in wallet.json — the one every command uses when
+            // no --relay-url is given. Refuses a relay that settles on a different
+            // network: the wallet's DSO pin and parties are network-specific.
+            const url = positionals(args)[0];
+            if (!url)
+                return fail("usage: canton-agent-wallet set-relay <url>");
+            const w = loadWallet();
+            if (!w)
+                return fail("no wallet yet — run: canton-agent-wallet create");
+            let net;
+            try {
+                const sup = await new RelayClient({ relayUrl: url, apiKey: API_KEY }).supported();
+                net = sup?.kinds?.find((k) => typeof k?.network === "string" && k.network.length > 0)?.network;
+            }
+            catch (err) {
+                return fail(`set-relay: could not reach ${url} (${err instanceof Error ? err.message : String(err)})`);
+            }
+            if (!net)
+                return fail(`set-relay: ${url} does not say which network it settles on — not switching`);
+            if (net !== w.network) {
+                return fail(`set-relay: ${url} settles on ${net}, but this wallet is on ${w.network} — not switching`);
+            }
+            saveWallet({ ...w, relayUrl: url });
+            console.log(`relay set: ${w.relayUrl} → ${url} (${net})`);
+            break;
+        }
         default:
-            console.error("canton-agent-wallet: create | address | balance | claim | merge [--target <n>] [--batch <n>] [--max-rounds <n>] [--dry-run] [--yes] [--admin <registrar> --id <instrument>] | preapproval [--status] [--admin <DSO>] [--operator-token <t>] [--days <n>] [--expires-at <iso>] | pay [--asset <symbol>] <url> | swap --in <SYM> --out <SYM> --amount <n> [--venue cantex|tradecraft|auto] [--slippage <pct>] [--direct] [--no-wait] [--max-fee <cc>] [--swap-merchant <party>] [--no-preapprove] | withdraw --to <party> [--amount <n>] [--admin <registrar> --id <instrument>] | export | import\n" +
+            console.error("canton-agent-wallet: create | address | balance | claim | merge [--target <n>] [--batch <n>] [--max-rounds <n>] [--dry-run] [--yes] [--admin <registrar> --id <instrument> | --all-tokens] | preapproval [--status] [--admin <DSO|registrar>] [--id <instrument>] [--operator-token <t>] [--days <n>] [--expires-at <iso>] | pay [--asset <symbol>] [--max <amount>] [--pay-to <party>] <url> | swap --in <SYM> --out <SYM> --amount <n> [--venue cantex|tradecraft|auto] [--slippage <pct>] [--direct] [--no-wait] [--max-fee <cc>] [--swap-merchant <party>] [--no-preapprove] | withdraw --to <party> [--amount <n>] [--admin <registrar> --id <instrument>] | export | import | set-relay <url>\n" +
                 "  relay required for create/pay/import: --relay-url <url> or CANTON_AGENT_RELAY_URL\n" +
                 "  preapproval = merchant TransferPreapproval setup for the transfer-factory (V3, 1-tx) path (--status to just check).");
             process.exit(cmd ? 1 : 0);