chainlesschain 0.160.1 → 0.161.2

package/src/commands/crosschain.js

@@ -2,8 +2,30 @@
  * `cc crosschain` — CLI surface for Phase 89 Cross-Chain Interoperability.
  */
 
+import fs from "node:fs";
+
 import { Command } from "commander";
 
+import { bootstrap } from "../runtime/bootstrap.js";
+import { getHomeDir } from "../lib/paths.js";
+import {
+  getCrossChainMtcDir,
+  getBridgeMtcStatus,
+  loadCrossChainMtcConfig,
+  addTrustAnchor,
+  listTrustAnchors,
+  removeTrustAnchor,
+  verifyBridgeEnvelope,
+  assembleBridgeBatch,
+  stageBridgeOp,
+  closeBatch,
+  buildMultiHopBridgeEnvelope,
+  verifyMultiHopBridgeEnvelope,
+  shouldCloseBatchGasAware,
+  getBridgeMtcSlaMetrics,
+} from "../lib/cross-chain-mtc.js";
+import mtcLib from "@chainlesschain/core-mtc";
+
 import {
   SUPPORTED_CHAINS,
   BRIDGE_STATUS,
@@ -48,16 +70,64 @@ import {
 } from "../lib/cross-chain.js";
 
 function _dbFromCtx(cmd) {
-  const root = cmd?.parent?.parent ?? cmd?.parent;
-  return root?._db;
+  // cmd is typically the action subcommand (e.g. `bridge`).
+  // _db may be wired onto cmd itself, the parent (`cc crosschain` group),
+  // or the root program — return the first one we find.
+  return cmd?._db ?? cmd?.parent?._db ?? cmd?.parent?.parent?._db ?? null;
+}
+
+/**
+ * Bootstrap a real DB when the crosschain command is invoked headless
+ * (e.g. via spawnSync in integration tests). Falls back to whatever the
+ * REPL/runtime already wired into _dbFromCtx if present.
+ */
+async function _ensureDb(thisCmd) {
+  const existing = _dbFromCtx(thisCmd);
+  if (existing) {
+    ensureCrossChainTables(existing);
+    return existing;
+  }
+  const ctx = await bootstrap({ verbose: false });
+  if (!ctx.db) return null;
+  const db = ctx.db.getDatabase();
+  ensureCrossChainTables(db);
+  thisCmd._db = db;
+  return db;
+}
+
+/**
+ * --mtc opt-in hook: when caller passes --mtc and the action succeeded,
+ * stage one bridge op for the next batch close. Silent best-effort —
+ * an MTC failure must not break the existing crosschain flow.
+ */
+function _maybeStageMtc(opts, opBuilder) {
+  if (!opts || !opts.mtc) return null;
+  try {
+    const home = opts.mtcConfigDir || getHomeDir();
+    const dir = getCrossChainMtcDir(home);
+    return stageBridgeOp(dir, opBuilder(), { requireEnabled: false });
+  } catch (err) {
+    return { staged: false, path: null, reason: `STAGE_ERROR: ${err.message}` };
+  }
 }
 
 export function registerCrossChainCommand(program) {
   const cc = new Command("crosschain")
     .description("Cross-chain interoperability (Phase 89)")
-    .hook("preAction", (thisCmd) => {
-      const db = _dbFromCtx(thisCmd);
-      if (db) ensureCrossChainTables(db);
+    .hook("preAction", async (thisCmd, actionCommand) => {
+      // Skip db bootstrap for MTC-only subcommands that don't touch the
+      // crosschain DB — keeps `cc crosschain mtc-status` etc. usable on
+      // a fresh box where the SQLite store hasn't been initialized.
+      const name = actionCommand?.name?.() || "";
+      if (
+        name.startsWith("mtc-") ||
+        name === "chains" ||
+        name === "bridge-statuses" ||
+        name === "swap-statuses"
+      ) {
+        return;
+      }
+      await _ensureDb(thisCmd);
     });
 
   /* ── Catalogs ────────────────────────────────────── */
@@ -99,6 +169,11 @@ export function registerCrossChainCommand(program) {
     .option("-a, --asset <asset>", "Asset name", "native")
     .option("-s, --sender <address>", "Sender address")
     .option("-r, --recipient <address>", "Recipient address")
+    .option(
+      "--mtc",
+      "On success, stage an MTC bridge envelope (requires cc crosschain mtc-batch to close)",
+    )
+    .option("--mtc-config-dir <dir>", "Override MTC config root")
     .option("--json", "JSON output")
     .action((fromChain, toChain, amount, opts) => {
       const db = _dbFromCtx(cc);
@@ -110,10 +185,27 @@ export function registerCrossChainCommand(program) {
         senderAddress: opts.sender,
         recipientAddress: opts.recipient,
       });
-      if (opts.json) return console.log(JSON.stringify(result, null, 2));
+      const mtc =
+        result.bridgeId &&
+        _maybeStageMtc(opts, () => ({
+          bridge_op: "lock",
+          src_chain: fromChain,
+          dst_chain: toChain,
+          src_tx_hash: result.bridgeId,
+          amount: String(amount),
+          asset: opts.asset || "native",
+          src_did: opts.sender || null,
+          dst_did: opts.recipient || null,
+          issued_at: new Date().toISOString(),
+        }));
+      if (opts.json)
+        return console.log(JSON.stringify({ ...result, mtc }, null, 2));
       if (result.bridgeId)
         console.log(`Bridge created: ${result.bridgeId} (fee: ${result.fee})`);
       else console.log(`Failed: ${result.reason}`);
+      if (mtc?.staged) console.log(`MTC envelope staged: ${mtc.path}`);
+      else if (mtc && !mtc.staged)
+        console.log(`MTC stage skipped: ${mtc.reason}`);
     });
 
   cc.command("bridge-status <bridge-id> <status>")
@@ -184,6 +276,8 @@ export function registerCrossChainCommand(program) {
     .option("-b, --to-asset <asset>", "Target asset", "native")
     .option("-c, --counterparty <address>", "Counterparty address")
     .option("-t, --timeout <ms>", "Timeout in ms", parseInt)
+    .option("--mtc", "On success, stage an MTC swap-init envelope")
+    .option("--mtc-config-dir <dir>", "Override MTC config root")
     .option("--json", "JSON output")
     .action((fromChain, toChain, amount, opts) => {
       const db = _dbFromCtx(cc);
@@ -196,12 +290,27 @@ export function registerCrossChainCommand(program) {
         counterpartyAddress: opts.counterparty,
         timeoutMs: opts.timeout,
       });
-      if (opts.json) return console.log(JSON.stringify(result, null, 2));
+      const mtc =
+        result.swapId &&
+        _maybeStageMtc(opts, () => ({
+          bridge_op: "swap-init",
+          src_chain: fromChain,
+          dst_chain: toChain,
+          swap_id: result.swapId,
+          amount: String(amount),
+          asset: opts.fromAsset || "native",
+          issued_at: new Date().toISOString(),
+        }));
+      if (opts.json)
+        return console.log(JSON.stringify({ ...result, mtc }, null, 2));
       if (result.swapId) {
         console.log(`Swap initiated: ${result.swapId}`);
         console.log(`Hash lock: ${result.hashLock}`);
         console.log(`Expires:   ${new Date(result.expiresAt).toISOString()}`);
       } else console.log(`Failed: ${result.reason}`);
+      if (mtc?.staged) console.log(`MTC envelope staged: ${mtc.path}`);
+      else if (mtc && !mtc.staged)
+        console.log(`MTC stage skipped: ${mtc.reason}`);
     });
 
   cc.command("swap-claim <swap-id>")
@@ -292,6 +401,8 @@ export function registerCrossChainCommand(program) {
     .description("Send cross-chain message")
     .option("-p, --payload <text>", "Message payload")
     .option("-c, --contract <address>", "Target contract address")
+    .option("--mtc", "On success, stage an MTC msg-send envelope")
+    .option("--mtc-config-dir <dir>", "Override MTC config root")
     .option("--json", "JSON output")
     .action((fromChain, toChain, opts) => {
       const db = _dbFromCtx(cc);
@@ -301,9 +412,25 @@ export function registerCrossChainCommand(program) {
         payload: opts.payload,
         targetContract: opts.contract,
       });
-      if (opts.json) return console.log(JSON.stringify(result, null, 2));
+      const mtc =
+        result.messageId &&
+        _maybeStageMtc(opts, () => ({
+          bridge_op: "msg-send",
+          src_chain: fromChain,
+          dst_chain: toChain,
+          src_tx_hash: result.messageId,
+          msg_payload: opts.payload
+            ? Buffer.from(opts.payload, "utf-8").toString("base64url")
+            : null,
+          issued_at: new Date().toISOString(),
+        }));
+      if (opts.json)
+        return console.log(JSON.stringify({ ...result, mtc }, null, 2));
       if (result.messageId) console.log(`Message sent: ${result.messageId}`);
       else console.log(`Failed: ${result.reason}`);
+      if (mtc?.staged) console.log(`MTC envelope staged: ${mtc.path}`);
+      else if (mtc && !mtc.staged)
+        console.log(`MTC stage skipped: ${mtc.reason}`);
     });
 
   cc.command("msg-status <message-id> <status>")
@@ -396,6 +523,15 @@ export function registerCrossChainCommand(program) {
       console.log(`Messages:  ${stats.messages.total}`);
     });
 
+  /* ══════════════════════════════════════════════════
+   * Cross-chain bridge MTC integration (跨链桥设计 v0.1)
+   * Design: docs/design/MTC_跨链桥_v1.md
+   * Status: opt-in. Default config.enabled = false. Read commands work
+   * regardless; envelope generation requires enabled=true.
+   * ══════════════════════════════════════════════════ */
+
+  registerCrossChainMtcSubcommands(cc);
+
   /* ══════════════════════════════════════════════════
    * Phase 89 — Cross-Chain V2 subcommands
    * ══════════════════════════════════════════════════ */
@@ -600,6 +736,426 @@ export function registerCrossChainCommand(program) {
   registerCrossChainV2Command(cc);
 }
 
+function _resolveBridgeMtcDir(opts) {
+  const home = (opts && opts.configDir) || getHomeDir();
+  return getCrossChainMtcDir(home);
+}
+
+function registerCrossChainMtcSubcommands(cc) {
+  cc.command("mtc-status")
+    .description("Show cross-chain bridge MTC config + trust anchors + batches")
+    .option(
+      "--config-dir <dir>",
+      "Override config root (default: ~/.chainlesschain)",
+    )
+    .option("--json", "JSON output")
+    .action((opts) => {
+      const dir = _resolveBridgeMtcDir(opts);
+      const s = getBridgeMtcStatus(dir);
+      if (opts.json) return console.log(JSON.stringify(s, null, 2));
+      console.log(
+        `Enabled:        ${s.enabled ? "yes" : "no (opt-in via config.enabled=true)"}`,
+      );
+      console.log(`Mode:           ${s.mode}`);
+      console.log(`Algorithm:      ${s.alg}`);
+      console.log(`Batch interval: ${s.batch_interval_seconds}s`);
+      console.log(`Issuer:         ${s.issuer}`);
+      console.log(
+        `Trust anchors:  ${s.trust_anchors.total} across ${s.trust_anchors.chain_count} chain(s)`,
+      );
+      for (const [chain, count] of Object.entries(s.trust_anchors.by_chain)) {
+        console.log(`                ${chain}: ${count}`);
+      }
+      console.log(
+        `Batches:        ${s.batches.total}${s.batches.latest ? ` (latest: ${s.batches.latest})` : ""}`,
+      );
+    });
+
+  cc.command("mtc-serve")
+    .description(
+      "Run a daemon that periodically closes staged bridge ops into batches",
+    )
+    .option("--config-dir <dir>", "Override config root")
+    .option(
+      "--interval <seconds>",
+      "Batch close interval (default: config.batch_interval_seconds)",
+      parseInt,
+    )
+    .option("--once", "Close once and exit (no daemon loop)")
+    .option("--alg <alg>", "Override config alg")
+    .option("--issuer <issuer>", "Override config issuer")
+    .option("--json", "Emit per-tick JSON results to stdout")
+    .action(async (opts) => {
+      const dir = _resolveBridgeMtcDir(opts);
+      const cfg = loadCrossChainMtcConfig(dir);
+      const intervalSec = opts.interval || cfg.batch_interval_seconds;
+      const tick = () => {
+        try {
+          const result = closeBatch(dir, {
+            alg: opts.alg,
+            issuer: opts.issuer,
+          });
+          const stamp = new Date().toISOString();
+          if (opts.json) {
+            console.log(JSON.stringify({ tick_at: stamp, ...result }, null, 2));
+          } else if (!result.skipped) {
+            console.log(
+              `[${stamp}] closed ${result.batches.length} batch(es): ${result.batches
+                .map((b) => `${b.pair}#${b.seq}(${b.count})`)
+                .join(", ")}`,
+            );
+          } else {
+            console.log(`[${stamp}] (idle: ${result.skipped.reason})`);
+          }
+        } catch (err) {
+          console.error(
+            `[${new Date().toISOString()}] tick error: ${err.message}`,
+          );
+        }
+      };
+
+      tick();
+      if (opts.once) return;
+
+      console.log(
+        `mtc-serve: closing every ${intervalSec}s (config-dir: ${dir}). Ctrl-C to stop.`,
+      );
+      const handle = setInterval(tick, intervalSec * 1000);
+      // Graceful shutdown
+      const stop = () => {
+        clearInterval(handle);
+        console.log("mtc-serve: stopped.");
+        process.exit(0);
+      };
+      process.on("SIGINT", stop);
+      process.on("SIGTERM", stop);
+      // Keep the event loop alive forever (until signal)
+      await new Promise(() => {});
+    });
+
+  cc.command("mtc-batch")
+    .description(
+      "Close currently-staged bridge ops into batches (one per chain-pair)",
+    )
+    .option("--config-dir <dir>", "Override config root")
+    .option("--alg <alg>", "Override config alg (ed25519 | slh-dsa-128f)")
+    .option("--issuer <issuer>", "Override config issuer")
+    .option("--json", "JSON output")
+    .action((opts) => {
+      const dir = _resolveBridgeMtcDir(opts);
+      const result = closeBatch(dir, {
+        alg: opts.alg,
+        issuer: opts.issuer,
+      });
+      if (opts.json) return console.log(JSON.stringify(result, null, 2));
+      if (result.skipped) {
+        console.log(`(no batch closed: ${result.skipped.reason})`);
+        return;
+      }
+      for (const b of result.batches) {
+        console.log(
+          `✓ Closed ${b.pair}#${b.seq}  ${b.count} op(s)  treeHead=${b.treeHeadId}`,
+        );
+        console.log(`  → ${b.dir}`);
+      }
+    });
+
+  cc.command("mtc-envelope")
+    .description("Build a bridge MTC envelope from a JSON file of bridge ops")
+    .requiredOption("-i, --input <path>", "JSON file: array of bridge ops")
+    .requiredOption("--src-chain <chain>", "Source chain")
+    .requiredOption("--dst-chain <chain>", "Destination chain")
+    .requiredOption("--batch-seq <n>", "Batch sequence number", parseInt)
+    .option("--issuer <issuer>", "MTCA issuer (default from config)")
+    .option("--alg <alg>", "ed25519 | slh-dsa-128f")
+    .option("--config-dir <dir>", "Override config root")
+    .option("--json", "JSON output (full landmark + envelopes)")
+    .action((opts) => {
+      const dir = _resolveBridgeMtcDir(opts);
+      const cfg = loadCrossChainMtcConfig(dir);
+      const ops = JSON.parse(fs.readFileSync(opts.input, "utf-8"));
+      if (!Array.isArray(ops)) {
+        console.error("Input file must contain a JSON array of bridge ops.");
+        process.exit(2);
+      }
+      const alg = opts.alg || cfg.alg;
+      const signer = alg === "slh-dsa-128f" ? mtcLib.slhDsa : mtcLib.ed25519;
+      const keys = signer.generateKeyPair();
+      const result = assembleBridgeBatch(ops, keys, {
+        src_chain: opts.srcChain,
+        dst_chain: opts.dstChain,
+        batch_seq: opts.batchSeq,
+        issuer: opts.issuer || cfg.issuer,
+        signer,
+      });
+      if (opts.json) return console.log(JSON.stringify(result, null, 2));
+      console.log(`Namespace:    ${result.namespace}`);
+      console.log(`Tree head id: ${result.treeHeadId}`);
+      console.log(`Tree size:    ${result.envelopes.length}`);
+      console.log(`Algorithm:    ${alg}`);
+      console.log(`(JSON envelope + landmark omitted; pass --json to emit)`);
+    });
+
+  cc.command("mtc-verify <envelope-path> <landmark-path>")
+    .description("Verify a bridge MTC envelope against a landmark file")
+    .option("--json", "JSON output")
+    .action((envPath, lmPath, opts) => {
+      const envelope = JSON.parse(fs.readFileSync(envPath, "utf-8"));
+      const landmark = JSON.parse(fs.readFileSync(lmPath, "utf-8"));
+      const cache = new mtcLib.LandmarkCache({
+        signatureVerifier: mtcLib.alwaysAcceptSignatureVerifier,
+      });
+      try {
+        cache.ingest(landmark);
+      } catch (err) {
+        const out = {
+          ok: false,
+          code: err.code || "LANDMARK_REJECT",
+          error: err.message,
+        };
+        if (opts.json) return console.log(JSON.stringify(out, null, 2));
+        console.log(`✗ Landmark ingest failed: ${err.message}`);
+        process.exit(2);
+      }
+      const result = verifyBridgeEnvelope(envelope, cache);
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        if (!result.ok) process.exit(2);
+        return;
+      }
+      if (result.ok) {
+        console.log(`✓ Envelope verified.`);
+        console.log(`  Bridge op: ${result.bridge_op}`);
+        console.log(`  Tree size: ${result.treeHead?.tree_size}`);
+        console.log(`  Issuer:    ${result.treeHead?.issuer}`);
+      } else {
+        console.log(`✗ Verification failed: ${result.code}`);
+        process.exit(2);
+      }
+    });
+
+  // v0.2 — Multi-hop bridge envelope (envelope-of-envelope)
+  cc.command("mtc-multihop-build")
+    .description(
+      "Build a multi-hop bridge envelope from a JSON file of leg envelopes",
+    )
+    .requiredOption(
+      "-i, --input <path>",
+      "JSON file: array of single-hop bridge envelopes (≥ 2)",
+    )
+    .option("--route-id <id>", "Optional route id (default: auto-generated)")
+    .option("--total-amount <amount>", "Optional cumulative amount string")
+    .option("--asset <asset>", "Optional asset symbol")
+    .option("--out <path>", "Write multi-hop envelope to file")
+    .option("--json", "JSON output (default unless --out given)")
+    .action((opts) => {
+      try {
+        const legs = JSON.parse(fs.readFileSync(opts.input, "utf-8"));
+        const wrapper = buildMultiHopBridgeEnvelope(legs, {
+          route_id: opts.routeId,
+          total_amount: opts.totalAmount,
+          asset: opts.asset,
+        });
+        const json = JSON.stringify(wrapper, null, 2);
+        if (opts.out) {
+          fs.writeFileSync(opts.out, json, "utf-8");
+          if (opts.json) console.log(json);
+          else
+            console.log(
+              `✓ Multi-hop envelope written: ${opts.out} (${wrapper.leg_count} legs, route: ${wrapper.chain_path.join(" → ")})`,
+            );
+        } else {
+          console.log(json);
+        }
+      } catch (err) {
+        console.error(`mtc-multihop-build failed: ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  cc.command("mtc-multihop-verify <wrapper-path>")
+    .description(
+      "Verify a multi-hop bridge envelope against per-leg landmark files",
+    )
+    .requiredOption(
+      "--landmarks <path>",
+      "JSON file: array of {landmark} entries, one per leg in order",
+    )
+    .option("--json", "JSON output")
+    .action((wrapperPath, opts) => {
+      try {
+        const wrapper = JSON.parse(fs.readFileSync(wrapperPath, "utf-8"));
+        const lmEntries = JSON.parse(fs.readFileSync(opts.landmarks, "utf-8"));
+        const result = verifyMultiHopBridgeEnvelope(wrapper, lmEntries);
+        if (opts.json) {
+          console.log(JSON.stringify(result, null, 2));
+          if (!result.ok) process.exit(2);
+          return;
+        }
+        if (result.ok) {
+          console.log(
+            `✓ Multi-hop verified (${wrapper.leg_count} legs, route: ${wrapper.chain_path.join(" → ")})`,
+          );
+        } else {
+          console.log(
+            `✗ Multi-hop verification failed: ${result.code || "LEG_FAIL"}`,
+          );
+          process.exit(2);
+        }
+      } catch (err) {
+        console.error(`mtc-multihop-verify failed: ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  // v0.2 — Gas-aware batch trigger advisor
+  cc.command("mtc-gas-check <target-chain>")
+    .description(
+      "Heuristic: should the bridge MTCA close its batch now given current gas + staged ops?",
+    )
+    .requiredOption("--staged-count <n>", "Currently staged ops", parseInt)
+    .option(
+      "--current-gas-usd <usd>",
+      "Observed gas cost in USD (default: chain baseline)",
+      parseFloat,
+    )
+    .option(
+      "--hard-close-floor <n>",
+      "Always close at or above this staged count (default: 50)",
+      parseInt,
+    )
+    .option(
+      "--defer-multiplier <m>",
+      "Defer when current_gas > baseline * this (default: 1.5)",
+      parseFloat,
+    )
+    .option("--json", "JSON output")
+    .action((targetChain, opts) => {
+      try {
+        const r = shouldCloseBatchGasAware({
+          target_chain: targetChain,
+          staged_count: opts.stagedCount,
+          current_gas_usd: opts.currentGasUsd,
+          hard_close_floor: opts.hardCloseFloor,
+          defer_multiplier: opts.deferMultiplier,
+        });
+        if (opts.json) return console.log(JSON.stringify(r, null, 2));
+        console.log(
+          `${r.close ? "✓ CLOSE" : "✗ DEFER"}  reason=${r.reason}  baseline=$${r.baseline_usd}  current=$${r.current_usd}  staged=${r.staged_count}`,
+        );
+      } catch (err) {
+        console.error(`mtc-gas-check failed: ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  // v0.2 — SLA Manager integration: emit SLA-shaped metrics
+  cc.command("mtc-sla")
+    .description(
+      "Emit cc sla-compatible operational metrics for the bridge MTCA",
+    )
+    .option("--config-dir <dir>", "Override config root")
+    .option("--json", "JSON output")
+    .action((opts) => {
+      const dir = _resolveBridgeMtcDir(opts);
+      const m = getBridgeMtcSlaMetrics(dir);
+      if (opts.json) return console.log(JSON.stringify(m, null, 2));
+      console.log(`SLA Status:        ${m.sla_status}`);
+      console.log(`Enabled:           ${m.enabled}`);
+      console.log(`Mode:              ${m.mode}`);
+      console.log(`Staged pending:    ${m.staged_pending_count}`);
+      console.log(`Batches total:     ${m.batches_total}`);
+      console.log(`Batches last hour: ${m.batches_last_hour}`);
+      console.log(
+        `Last batch:        ${m.seconds_since_last_batch !== null ? `${m.seconds_since_last_batch}s ago` : "—"}`,
+      );
+    });
+
+  const taParent = cc
+    .command("mtc-trust-anchor")
+    .description("Manage Independent-mode trust anchors (per source chain)");
+
+  taParent
+    .command("add <chain> <pubkey-id>")
+    .description("Add a trust anchor for a source chain")
+    .requiredOption("--alg <alg>", "ed25519 | slh-dsa-128f")
+    .requiredOption("--issuer <issuer>", "MTCA issuer string for this anchor")
+    .option("--jwk <path>", "Optional JWK file for the public key")
+    .option("--config-dir <dir>", "Override config root")
+    .option("--json", "JSON output")
+    .action((chain, pubkeyId, opts) => {
+      const dir = _resolveBridgeMtcDir(opts);
+      let pubkeyJwk = null;
+      if (opts.jwk) {
+        pubkeyJwk = JSON.parse(fs.readFileSync(opts.jwk, "utf-8"));
+      }
+      const r = addTrustAnchor(dir, chain, {
+        pubkey_id: pubkeyId,
+        alg: opts.alg,
+        issuer: opts.issuer,
+        pubkey_jwk: pubkeyJwk,
+      });
+      if (opts.json) return console.log(JSON.stringify(r, null, 2));
+      if (r.added) {
+        console.log(`✓ Added trust anchor for ${chain}: ${pubkeyId}`);
+      } else {
+        console.log(`(already exists for ${chain}: ${pubkeyId})`);
+      }
+      console.log(`Total anchors for ${chain}: ${r.total_for_chain}`);
+    });
+
+  taParent
+    .command("list [chain]")
+    .description("List trust anchors (optionally filter by chain)")
+    .option("--config-dir <dir>", "Override config root")
+    .option("--json", "JSON output")
+    .action((chain, opts) => {
+      const dir = _resolveBridgeMtcDir(opts);
+      const result = listTrustAnchors(dir, chain);
+      if (opts.json) return console.log(JSON.stringify(result, null, 2));
+      if (chain) {
+        if (!result || result.length === 0) {
+          console.log(`(no trust anchors for ${chain})`);
+          return;
+        }
+        for (const a of result) {
+          console.log(
+            `  ${a.pubkey_id}  alg=${a.alg}  issuer=${a.issuer}  added=${a.added_at}`,
+          );
+        }
+      } else {
+        const chains = Object.keys(result);
+        if (chains.length === 0) {
+          console.log("(no trust anchors)");
+          return;
+        }
+        for (const c of chains) {
+          console.log(`${c}:`);
+          for (const a of result[c]) {
+            console.log(`  ${a.pubkey_id}  alg=${a.alg}  issuer=${a.issuer}`);
+          }
+        }
+      }
+    });
+
+  taParent
+    .command("remove <chain> <pubkey-id>")
+    .description("Remove a trust anchor by pubkey-id")
+    .option("--config-dir <dir>", "Override config root")
+    .option("--json", "JSON output")
+    .action((chain, pubkeyId, opts) => {
+      const dir = _resolveBridgeMtcDir(opts);
+      const r = removeTrustAnchor(dir, chain, pubkeyId);
+      if (opts.json) return console.log(JSON.stringify(r, null, 2));
+      if (r.removed) {
+        console.log(`✓ Removed trust anchor for ${chain}: ${pubkeyId}`);
+      } else {
+        console.log(`(no matching trust anchor for ${chain}: ${pubkeyId})`);
+      }
+      console.log(`Remaining anchors for ${chain}: ${r.total_for_chain}`);
+    });
+}
+
 import {
   XCHAIN_CHANNEL_MATURITY_V2,
   XCHAIN_TRANSFER_LIFECYCLE_V2,