@ldgr/cli 0.5.0 → 0.5.2

package/README.md

@@ -1,6 +1,15 @@
 # @ldgr/cli
 
-LDGR's self-custody terminal wallet. Version 0.5.0 creates or imports local wallets, lets you select between them, shows addresses and balances, sends native Ledra or a token, and persistently switches the selected wallet between mainnet and testnet. It also reviews prepared MCP requests for transfers, token creation and escrow creation in a separate interactive terminal.
+LDGR's self-custody terminal wallet. Version 0.5.2 creates or imports local wallets, lets you select between them, shows addresses and balances, sends native Ledra or a token, and persistently switches the selected wallet between mainnet and testnet. It also reviews prepared MCP requests for transfers, swaps, token creation and escrow creation in a separate interactive terminal.
+
+The MCP launcher uses `ldgr mcp --stdin` with a UTF-8 JSON envelope for
+`wallet-info` and `save-request`. Envelopes are limited to 128 KiB. Public wallet
+metadata or the saved request path and approval arguments are returned as JSON;
+failures return a redacted error code and exit status 1. These machine operations
+do not migrate or unlock wallets. `ldgr mcp <base64url-envelope>` also supports an
+allowlisted `command` envelope for interactive wallet setup and approval in the
+user's terminal. Recovery-key values and passphrases must never be included in
+an envelope; interactive secrets remain local terminal prompts.
 
 ```bash
 npm install -g @ldgr/cli
@@ -23,7 +32,9 @@ The public `@ldgr/cli/mcp` module exposes `getMcpWalletInfo`, `validateMcpReques
 
 Run `ldgr approve <request-file>` yourself in an interactive terminal. Approval accepts the saved request envelope or a portable request JSON produced by hosted MCP. It checks the selected wallet's network, shows the destination, exact decimal amount and asset code, current balances and fee, or the complete token/escrow terms. Confirmation defaults to **No**. A protected wallet then prompts privately for its passphrase. Request expiry and signing-draft freshness are checked again after confirmation and unlock. A draft older than four minutes requires a new review, leaving submission headroom within the ledger's five-minute signature window; the CLI never silently changes the reviewed timestamp or derived token code. Terminal controls in live asset labels are escaped, and request text rejects terminal and Unicode formatting controls. API hosts are fixed to the official network endpoints; custom URLs and secret-bearing request fields are rejected.
 
-Supported requests use `{version:1, requestId:<lowercase UUID v4>, network:"mainnet"|"testnet", expiresAt:<ISO timestamp>, action, params}`. Actions are `transfer` (`asset`, `to`, `amount`, optional `memo`), `create_token` (`displayName`, `ticker`, `decimals`, `supplyMode`, `initialSupply`, optional `initialRecipient` and mintable `maxSupply`), and `open_escrow` (`asset`, `to`, `amount`, `expiresAt` as Unix milliseconds string, optional `reference`). Amounts and supplies are decimal strings. Token icons, arbitrary code and additional contract templates are not part of this request format.
+Supported requests use `{version:1, requestId:<lowercase UUID v4>, network:"mainnet"|"testnet", expiresAt:<ISO timestamp>, action, params}`. Actions are `transfer` (`asset`, `to`, `amount`, optional `memo`), `swap` (`assetIn`, `assetOut`, `amountIn`, `amountOutMin`, optional `maxHops` of 1, 2 or 3, default 3), `create_token` (`displayName`, `ticker`, `decimals`, `supplyMode`, `initialSupply`, optional `initialRecipient` and mintable `maxSupply`), and `open_escrow` (`asset`, `to`, `amount`, `expiresAt` as Unix milliseconds string, optional `reference`). Amounts and supplies are decimal strings. Token icons, arbitrary code and additional contract templates are not part of this request format.
+
+Swap approval fetches a fresh route quote, validates its assets, amounts and connected pools, and displays the exact input, required minimum output, live quoted output, route, per-pool LP fees and current network fee. Input and minimum output must both be positive and fit their assets' precision. The minimum is never reduced to match a quote. Quotes can change before settlement; the signed minimum remains enforced. Swaps use one to three pools, return output to the selected wallet, and charge one native Ledra network fee for the whole route. A request cannot supply a recipient or route. The CLI signs the existing `amm_route_swap` action with the native `dng` nonce lane after explicit approval; preparation never signs or submits.
 
 Prepared requests default to `~/.ldgr/requests`. Approval records live in `approvals` beside the selected wallet store. Before submission, the CLI durably saves the exact signed envelope and consumes the request ID. The same request cannot be approved again by copying or renaming its file. An interrupted or uncertain submission also blocks further approvals for that wallet. Inspect the retained envelope and ledger history to reconcile the result before manually removing the wallet's pending record or creating a replacement. Do not delete records merely to retry: a request may already have settled. There is no automatic re-signing or retry. Successful receipts contain the transaction hash. On Windows, these files rely on native directory ACLs, as the wallet store does.
 

package/dist/cli.js

@@ -5,8 +5,8 @@ import * as p2 from "@clack/prompts";
 import { createLdgrClient as createLdgrClient2, LdgrClientError } from "@ldgr/client";
 import {
   isBurnerWalletAddress as isBurnerWalletAddress2,
-  nativeAssetDefinitionForLedger as nativeAssetDefinitionForLedger3,
-  resolvePublicAssetCode as resolvePublicAssetCode3
+  nativeAssetDefinitionForLedger as nativeAssetDefinitionForLedger4,
+  resolvePublicAssetCode as resolvePublicAssetCode4
 } from "@ldgr/protocol";
 import { readFile as readFile3 } from "node:fs/promises";
 
@@ -16,7 +16,7 @@ import { buildTransferSubmission } from "@ldgr/wallet-core";
 // src/mcp-approval.ts
 import * as p from "@clack/prompts";
 import { createLdgrClient } from "@ldgr/client";
-import { canonicalizeLedgerAddress as canonicalizeLedgerAddress3, deriveUserAssetCode, formatAtomicAmount, isBurnerWalletAddress, nativeAssetDefinitionForLedger as nativeAssetDefinitionForLedger2, parseDecimalAmount as parseDecimalAmount2, resolvePublicAssetCode as resolvePublicAssetCode2 } from "@ldgr/protocol";
+import { canonicalizeLedgerAddress as canonicalizeLedgerAddress3, deriveUserAssetCode, formatAtomicAmount as formatAtomicAmount2, isBurnerWalletAddress, nativeAssetDefinitionForLedger as nativeAssetDefinitionForLedger3, parseDecimalAmount as parseDecimalAmount3, resolvePublicAssetCode as resolvePublicAssetCode3 } from "@ldgr/protocol";
 import { lstat as lstat2, mkdir as mkdir3, open as open3, readFile as readFile2, unlink as unlink2 } from "node:fs/promises";
 import { dirname as dirname3, join as join3, resolve as resolve2 } from "node:path";
 
@@ -395,6 +395,16 @@ function validateMcpRequest(input) {
       if (typeof params.expiresAt !== "string" || !/^[1-9][0-9]{0,15}$/.test(params.expiresAt) || BigInt(params.expiresAt) <= BigInt(Date.now()) || BigInt(params.expiresAt) > BigInt(Number.MAX_SAFE_INTEGER))
         throw new TypeError("Escrow expiry must be future Unix milliseconds as a string");
     }
+  } else if (value.action === "swap") {
+    const params = object(value.params, ["assetIn", "assetOut", "amountIn", "amountOutMin", "maxHops"]);
+    const assetIn = resolvePublicAssetCode(text(params.assetIn, "input asset"), ledgerId);
+    const assetOut = resolvePublicAssetCode(text(params.assetOut, "output asset"), ledgerId);
+    if (assetIn === assetOut)
+      throw new TypeError("Swap assets must be distinct");
+    if (!/[1-9]/.test(amount(params.amountIn)) || !/[1-9]/.test(amount(params.amountOutMin)))
+      throw new TypeError("Swap input and minimum output must be positive");
+    if (params.maxHops !== undefined && ![1, 2, 3].includes(params.maxHops))
+      throw new TypeError("maxHops must be 1, 2 or 3");
   } else if (value.action === "create_token") {
     const params = object(value.params, ["displayName", "ticker", "decimals", "supplyMode", "initialSupply", "initialRecipient", "maxSupply"]);
     assertAssetDisplayName(text(params.displayName, "display name", 64));
@@ -446,6 +456,140 @@ async function saveMcpRequest(input, options = {}) {
   return { requestPath, approvalArgs: ["approve", requestPath, "--wallet", walletPath] };
 }
 
+// src/mcp-swap.ts
+import { AMM_POOL_ID_PATTERN, assertAssetDecimals as assertAssetDecimals2, formatAtomicAmount, nativeAssetDefinitionForLedger as nativeAssetDefinitionForLedger2, parseDecimalAmount as parseDecimalAmount2, resolvePublicAssetCode as resolvePublicAssetCode2 } from "@ldgr/protocol";
+
+// src/mcp-review.ts
+function reviewText(value) {
+  if (typeof value !== "string")
+    throw new TypeError("Invalid asset display metadata");
+  return value.replace(/[\x00-\x1f\x7f-\x9f\p{Cf}\u2028\u2029]/gu, (character) => `\\u{${character.codePointAt(0).toString(16).padStart(4, "0")}}`);
+}
+
+// src/mcp-swap.ts
+function record(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new TypeError("Invalid live swap quote");
+  return value;
+}
+function atomic(value) {
+  if (typeof value !== "string" || !/^(0|[1-9][0-9]*)$/.test(value))
+    throw new TypeError("Invalid live atomic amount");
+  return BigInt(value);
+}
+function decimal(value, definition) {
+  if (typeof value !== "string" || !/^(0|[1-9][0-9]*)(\.[0-9]{1,18})?$/.test(value))
+    throw new TypeError("Invalid live decimal amount");
+  return parseDecimalAmount2(value, definition);
+}
+function quoteAmount(value, key, definition) {
+  const result = decimal(value[key], definition);
+  if (result <= 0n || result !== atomic(value[`${key}Atomic`]))
+    throw new TypeError("Inconsistent live swap quote amount");
+  return result;
+}
+async function draftMcpSwap(request, wallet, client) {
+  const params = request.params;
+  const assetIn = resolvePublicAssetCode2(params.assetIn, wallet.ledgerId);
+  const assetOut = resolvePublicAssetCode2(params.assetOut, wallet.ledgerId);
+  const maxHops = params.maxHops ?? 3;
+  const native = nativeAssetDefinitionForLedger2(wallet.ledgerId);
+  const definitions = new Map([["dng", native]]);
+  const label = (metadata) => `${reviewText(metadata.ticker ?? metadata.code)} (${reviewText(metadata.displayName)}; ${reviewText(metadata.code)})`;
+  async function definition(code) {
+    const cached = definitions.get(code);
+    if (cached)
+      return cached;
+    const metadata = await client.assets.get(code);
+    if (metadata.code !== code || metadata.active !== true)
+      throw new TypeError("Asset metadata does not match the active requested asset");
+    assertAssetDecimals2(metadata.decimals);
+    reviewText(metadata.displayName);
+    reviewText(metadata.ticker ?? code);
+    definitions.set(code, metadata);
+    return metadata;
+  }
+  function code(value) {
+    if (typeof value !== "string" || resolvePublicAssetCode2(value, wallet.ledgerId) !== value)
+      throw new TypeError("Invalid live route asset code");
+    return value;
+  }
+  const input = await definition(assetIn);
+  const output = await definition(assetOut);
+  const amountIn = decimal(params.amountIn, input);
+  const amountOutMin = decimal(params.amountOutMin, output);
+  if (amountIn <= 0n || amountOutMin <= 0n)
+    throw new TypeError("Swap input and minimum output must be positive");
+  const quote = record(await client.amm.quoteRoute(assetIn, assetOut, params.amountIn, maxHops));
+  if (quote.assetIn !== assetIn || quote.assetOut !== assetOut || quoteAmount(quote, "amountIn", input) !== amountIn)
+    throw new TypeError("Live swap quote does not match the requested input and assets");
+  const quotedOutput = quoteAmount(quote, "amountOut", output);
+  if (quotedOutput < amountOutMin)
+    throw new Error("Live quoted output is below the requested minimum; nothing was signed or submitted");
+  if (typeof quote.routeSearchTruncated !== "boolean" || !Array.isArray(quote.hops) || quote.hops.length < 1 || quote.hops.length > maxHops)
+    throw new TypeError("Invalid live swap route length or search result");
+  const pools = new Set;
+  const assets = new Set([assetIn]);
+  const hops = [];
+  const routeReview = [];
+  let previousAsset = assetIn;
+  let previousAmount = amountIn;
+  for (const value of quote.hops) {
+    const hop = record(value);
+    const poolId = hop.poolId;
+    const hopIn = code(hop.assetIn);
+    const hopOut = code(hop.assetOut);
+    if (typeof poolId !== "string" || !AMM_POOL_ID_PATTERN.test(poolId) || pools.has(poolId) || assets.has(hopOut) || hopIn !== previousAsset)
+      throw new TypeError("Invalid, disconnected or cyclic live swap route");
+    if (typeof hop.feeBps !== "number" || !Number.isInteger(hop.feeBps) || hop.feeBps < 0 || hop.feeBps >= 1e4)
+      throw new TypeError("Invalid live swap LP fee");
+    const hopInput = await definition(hopIn);
+    const hopOutput = await definition(hopOut);
+    if (quoteAmount(hop, "amountIn", hopInput) !== previousAmount)
+      throw new TypeError("Disconnected live swap quote amounts");
+    previousAmount = quoteAmount(hop, "amountOut", hopOutput);
+    previousAsset = hopOut;
+    pools.add(poolId);
+    assets.add(hopOut);
+    hops.push({ poolId, assetIn: hopIn, assetOut: hopOut });
+    routeReview.push(`${reviewText(poolId)}: ${label(hopInput)} -> ${label(hopOutput)}; LP fee: ${hop.feeBps} bps (included in quote)`);
+  }
+  if (previousAsset !== assetOut || previousAmount !== quotedOutput)
+    throw new TypeError("Live swap route does not match the quoted output");
+  const nonce = atomic((await client.accounts.getNextNonce(wallet.address, "dng")).nextNonce);
+  const config = await client.ledger.getProtocolConfig();
+  const fee = atomic(config.transferFeeAtomic);
+  const balances = await client.accounts.listBalances(wallet.address);
+  const balance = (asset, metadata) => decimal(balances.balances.find((row) => row.asset === asset)?.amount ?? "0", metadata);
+  const nativeBalance = balance("dng", native);
+  const inputBalance = balance(assetIn, input);
+  if (nativeBalance < fee + (assetIn === "dng" ? amountIn : 0n))
+    throw new Error("Insufficient Ledra balance for amount and network fee");
+  if (inputBalance < amountIn)
+    throw new Error("Insufficient token balance");
+  const timestamp = BigInt(Date.now());
+  const payload = { version: 1, chain: "ldgr-v1", ledgerId: wallet.ledgerId, action: "amm_route_swap", template: "amm_v1", asset: "dng", from: wallet.address, to: wallet.address, publicKey: wallet.publicKey, nonce, timestamp, hops, amountIn, amountOutMin };
+  const review = `Network: ${wallet.network}${wallet.ledgerId === 0 ? " (test tokens, no real-world value)" : ""}
+From: ${wallet.address}
+To: ${wallet.address} (selected wallet)
+Request: ${request.requestId}
+Approval expires: ${request.expiresAt}
+Balance: ${formatAtomicAmount(inputBalance, input)} ${label(input)}
+Fee balance: ${formatAtomicAmount(nativeBalance, native)} ${native.ticker} (dng)
+Current network fee: ${formatAtomicAmount(fee, native)} ${native.ticker} (dng)
+One network fee for the entire route. The network applies its current fee at settlement.
+
+Swap exact input: ${formatAtomicAmount(amountIn, input)} ${label(input)}
+Minimum output: ${formatAtomicAmount(amountOutMin, output)} ${label(output)}
+Live quoted output: ${formatAtomicAmount(quotedOutput, output)} ${label(output)}
+The quote can change before settlement; the signed minimum output is enforced.
+Route:
+${routeReview.join(`
+`)}${quote.routeSearchTruncated ? `
+Route search was truncated; this quote may not be the best available route.` : ""}`;
+  return { path: "/api/v1/amm/routes/swap", payload: { ...payload }, wire: { ...payload, nonce: nonce.toString(), timestamp: timestamp.toString(), amountIn: formatAtomicAmount(amountIn, input), amountOutMin: formatAtomicAmount(amountOutMin, output) }, review };
+}
+
 // src/mcp-approval.ts
 var MAX_REVIEWED_DRAFT_AGE_MS = 4n * 60n * 1000n;
 function assertFreshDraft(draft) {
@@ -455,11 +599,6 @@ function assertFreshDraft(draft) {
     throw new Error("The reviewed signing draft is stale. Run the approval command and review again; nothing was signed or submitted.");
   }
 }
-function reviewText(value) {
-  if (typeof value !== "string")
-    throw new TypeError("Invalid asset display metadata");
-  return value.replace(/[\x00-\x1f\x7f-\x9f\p{Cf}\u2028\u2029]/gu, (character) => `\\u{${character.codePointAt(0).toString(16).padStart(4, "0")}}`);
-}
 async function writeExclusive(path, value) {
   const handle = await open3(path, "wx", 384);
   try {
@@ -482,8 +621,10 @@ async function readRequest(path) {
   return { request: validateMcpRequest(envelope.request), wallet: envelope.wallet };
 }
 async function draftRequest(request, wallet, client) {
-  const asset = request.action === "create_token" ? "dng" : resolvePublicAssetCode2(request.params.asset, wallet.ledgerId);
-  const native = nativeAssetDefinitionForLedger2(wallet.ledgerId);
+  if (request.action === "swap")
+    return draftMcpSwap(request, wallet, client);
+  const asset = request.action === "create_token" ? "dng" : resolvePublicAssetCode3(request.params.asset, wallet.ledgerId);
+  const native = nativeAssetDefinitionForLedger3(wallet.ledgerId);
   const definition = asset === "dng" ? native : await client.assets.get(asset);
   if (definition.code !== asset || !definition.active)
     throw new TypeError("Asset metadata does not match the active requested asset");
@@ -500,9 +641,9 @@ async function draftRequest(request, wallet, client) {
   if (typeof fee !== "string" || !/^(0|[1-9][0-9]*)$/.test(fee))
     throw new TypeError("Live network fee unavailable");
   const balances = await client.accounts.listBalances(wallet.address);
-  const balance = (code, metadata) => parseDecimalAmount2(balances.balances.find((row) => row.asset === code)?.amount ?? "0", metadata);
+  const balance = (code, metadata) => parseDecimalAmount3(balances.balances.find((row) => row.asset === code)?.amount ?? "0", metadata);
   const nativeBalance = balance("dng", native);
-  const spend = request.action === "create_token" ? 0n : parseDecimalAmount2(request.params.amount, definition);
+  const spend = request.action === "create_token" ? 0n : parseDecimalAmount3(request.params.amount, definition);
   if (nativeBalance < BigInt(fee) + (asset === "dng" ? spend : 0n))
     throw new Error("Insufficient Ledra balance for amount and network fee");
   if (asset !== "dng" && balance(asset, definition) < spend)
@@ -511,9 +652,9 @@ async function draftRequest(request, wallet, client) {
 From: ${wallet.address}
 Request: ${request.requestId}
 Approval expires: ${request.expiresAt}
-Balance: ${formatAtomicAmount(balance(asset, definition), definition)} ${ticker} (${asset})
-Fee balance: ${formatAtomicAmount(nativeBalance, native)} ${native.ticker} (dng)
-Current network fee: ${formatAtomicAmount(BigInt(fee), native)} ${native.ticker} (dng)
+Balance: ${formatAtomicAmount2(balance(asset, definition), definition)} ${ticker} (${asset})
+Fee balance: ${formatAtomicAmount2(nativeBalance, native)} ${native.ticker} (dng)
+Current network fee: ${formatAtomicAmount2(BigInt(fee), native)} ${native.ticker} (dng)
 The network applies its current fee at settlement.`;
   let payload;
   let wire;
@@ -522,9 +663,9 @@ The network applies its current fee at settlement.`;
   if (request.action === "create_token") {
     const params = request.params;
     const token = { ...native, decimals: params.decimals };
-    const identity = { ...base, action: "asset_create", displayName: params.displayName, ticker: params.ticker, decimals: params.decimals, supplyMode: params.supplyMode, initialSupply: parseDecimalAmount2(params.initialSupply, token), initialRecipient: params.initialRecipient ?? wallet.address, ...params.maxSupply === undefined ? {} : { maxSupply: parseDecimalAmount2(params.maxSupply, token) } };
+    const identity = { ...base, action: "asset_create", displayName: params.displayName, ticker: params.ticker, decimals: params.decimals, supplyMode: params.supplyMode, initialSupply: parseDecimalAmount3(params.initialSupply, token), initialRecipient: params.initialRecipient ?? wallet.address, ...params.maxSupply === undefined ? {} : { maxSupply: parseDecimalAmount3(params.maxSupply, token) } };
     payload = { ...identity };
-    wire = { ...identity, initialSupply: formatAtomicAmount(identity.initialSupply, token), ...identity.maxSupply === undefined ? {} : { maxSupply: formatAtomicAmount(identity.maxSupply, token) } };
+    wire = { ...identity, initialSupply: formatAtomicAmount2(identity.initialSupply, token), ...identity.maxSupply === undefined ? {} : { maxSupply: formatAtomicAmount2(identity.maxSupply, token) } };
     review = `${heading}
 
 Create token: ${params.displayName} (${params.ticker})
@@ -537,18 +678,18 @@ Maximum supply: ${params.maxSupply ?? (params.supplyMode === "fixed" ? params.in
     path = "/api/v1/assets";
   } else {
     const params = request.params;
-    const atomic = parseDecimalAmount2(params.amount, definition);
+    const atomic = parseDecimalAmount3(params.amount, definition);
     if (atomic <= 0n)
       throw new TypeError("Amount must be positive");
     const to = canonicalizeLedgerAddress3(params.to, wallet.ledgerId);
     const common = { ...base, to, amount: atomic };
     if (request.action === "transfer") {
       payload = { ...common, action: "transfer", ...request.params.memo === undefined ? {} : { memo: request.params.memo } };
-      wire = { ...payload, amount: formatAtomicAmount(atomic, definition) };
+      wire = { ...payload, amount: formatAtomicAmount2(atomic, definition) };
       path = "/api/v1/transfers";
     } else {
       payload = { ...common, action: "payment_open", template: "escrow_v1", contractId: request.requestId, expiresAt: BigInt(request.params.expiresAt), ...request.params.reference === undefined ? {} : { reference: request.params.reference } };
-      wire = { ...payload, amount: formatAtomicAmount(atomic, definition), expiresAt: request.params.expiresAt };
+      wire = { ...payload, amount: formatAtomicAmount2(atomic, definition), expiresAt: request.params.expiresAt };
       path = "/api/v1/payment-contracts";
     }
     review = `${heading}
@@ -644,9 +785,97 @@ async function approveMcpRequest(requestPath, walletPath, options = {}) {
   }
 }
 
+// src/mcp-bridge.ts
+var MAX_BYTES = 128 * 1024;
+function commandArgs(input) {
+  if (!Array.isArray(input) || input.some((value) => typeof value !== "string" || !value || /[\x00-\x1f\x7f-\x9f\p{Cf}\u2028\u2029]/u.test(value)))
+    throw new TypeError("Invalid arguments");
+  const positional = [];
+  let testnet = false, wallet = false;
+  for (let index = 0;index < input.length; index++) {
+    const value = input[index];
+    if (value === "--wallet") {
+      if (wallet || !input[index + 1] || input[index + 1].startsWith("-"))
+        throw new TypeError("Invalid wallet path");
+      wallet = true;
+      index++;
+    } else if (value === "--testnet") {
+      if (testnet)
+        throw new TypeError("Repeated network flag");
+      testnet = true;
+    } else if (value.startsWith("-"))
+      throw new TypeError("Unsupported option");
+    else
+      positional.push(value);
+  }
+  const [first, second, third] = positional;
+  const creation = first === "wallet" && (second === "create" || second === "import");
+  if (testnet && !creation)
+    throw new TypeError("Invalid network flag");
+  const valid = first === "wallet" && second === "create" && positional.length === 2 || first === "wallet" && second === "import" && (positional.length === 2 || positional.length === 3) || first === "wallet" && second === "list" && positional.length === 2 || first === "wallet" && second === "select" && positional.length === 3 && /^[0-9]+$/.test(third) || first === "approve" && positional.length === 2 || first === "address" && positional.length === 1 || first === "network" && second === "show" && positional.length === 2 || first === "network" && second === "set" && positional.length === 3 && (third === "mainnet" || third === "testnet");
+  if (!valid)
+    throw new TypeError("Unsupported command");
+  return [...input];
+}
+function envelope(bytes, machineOnly) {
+  if (bytes.length > MAX_BYTES)
+    throw new TypeError("Envelope too large");
+  const value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new TypeError("Invalid envelope");
+  const keys = value.operation === "wallet-info" ? ["operation", "walletPath"] : value.operation === "save-request" ? ["operation", "walletPath", "directory", "request"] : value.operation === "command" && !machineOnly ? ["operation", "args"] : [];
+  if (!keys.length || Object.keys(value).some((key) => !keys.includes(key)))
+    throw new TypeError("Unsupported envelope");
+  for (const key of ["walletPath", "directory"]) {
+    if (key in value && (typeof value[key] !== "string" || !value[key].trim() || /[\x00-\x1f\x7f-\x9f\p{Cf}\u2028\u2029]/u.test(value[key])))
+      throw new TypeError("Invalid path");
+  }
+  if (value.operation === "command")
+    value.args = commandArgs(value.args);
+  return value;
+}
+async function readEnvelope(argument) {
+  if (argument === "--stdin") {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of process.stdin) {
+      const bytes = Buffer.from(chunk);
+      size += bytes.length;
+      if (size > MAX_BYTES)
+        throw new TypeError("Envelope too large");
+      chunks.push(bytes);
+    }
+    return envelope(Buffer.concat(chunks), true);
+  }
+  if (argument.length > Math.ceil(MAX_BYTES * 4 / 3) || !/^[A-Za-z0-9_-]+$/.test(argument))
+    throw new TypeError("Invalid encoding");
+  const bytes = Buffer.from(argument, "base64url");
+  if (bytes.toString("base64url") !== argument)
+    throw new TypeError("Invalid encoding");
+  return envelope(bytes, false);
+}
+async function runMcpBridge(args) {
+  try {
+    if (args.length !== 1)
+      throw new TypeError("Expected one envelope");
+    const request = await readEnvelope(args[0]);
+    if (request.operation === "command")
+      return request.args;
+    const result = request.operation === "wallet-info" ? await getMcpWalletInfo(request.walletPath) : await saveMcpRequest(validateMcpRequest(request.request), { walletPath: request.walletPath, directory: request.directory });
+    process.stdout.write(JSON.stringify(result) + `
+`);
+  } catch (error) {
+    const code = error instanceof TypeError && error.message === "Request network does not match the selected CLI wallet" ? "WALLET_NETWORK_MISMATCH" : error instanceof Error && error.message.startsWith("Wallet file not found: ") ? "WALLET_NOT_FOUND" : "OPERATION_FAILED";
+    process.stdout.write(JSON.stringify({ error: { code } }) + `
+`);
+    process.exitCode = 1;
+  }
+  return;
+}
+
 // src/cli.ts
 var HELP = `
-LDGR CLI 0.5.0 — self-custody wallet
+LDGR CLI 0.5.2 — self-custody wallet
 
 Usage:
   ldgr wallet create [--testnet] [--wallet <path>]
@@ -744,7 +973,7 @@ async function selectedClient(file) {
   return client;
 }
 function nativeDefinition(ledgerId) {
-  return nativeAssetDefinitionForLedger3(ledgerId);
+  return nativeAssetDefinitionForLedger4(ledgerId);
 }
 function assetDefinition(record) {
   if (!Number.isSafeInteger(record.decimals) || record.decimals < 0)
@@ -867,7 +1096,7 @@ async function runSend(path, rawAsset, recipient, amount) {
   const file = await walletFileMetadata(path);
   showNetworkWarning(file);
   const client = await selectedClient(file);
-  const asset = resolvePublicAssetCode3(rawAsset, file.ledgerId);
+  const asset = resolvePublicAssetCode4(rawAsset, file.ledgerId);
   const definition = await definitionForAsset(client, asset, file.ledgerId);
   const passphrase = await signingPassphrase(file, "Enter your wallet passphrase to sign");
   const wallet = await readEncryptedWalletFile(path, passphrase);
@@ -937,9 +1166,16 @@ ${file.address}`, "Selected network");
   p2.outro(`${target} address: ${switched.address}`);
 }
 async function main() {
+  let argv = process.argv.slice(2);
+  if (argv[0] === "mcp") {
+    const command = await runMcpBridge(argv.slice(1));
+    if (!command)
+      return;
+    argv = command;
+  }
   let parsed;
   try {
-    parsed = parseArguments(process.argv.slice(2));
+    parsed = parseArguments(argv);
   } catch (error) {
     process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
 `);

package/dist/mcp-bridge.d.ts

@@ -0,0 +1,2 @@
+/** Machine operations do not migrate, unlock, sign, or emit terminal UI. */
+export declare function runMcpBridge(args: readonly string[]): Promise<readonly string[] | undefined>;

package/dist/mcp-review.d.ts

@@ -0,0 +1,2 @@
+/** Escape ledger-provided display text before placing it in terminal review. */
+export declare function reviewText(value: string): string;

package/dist/mcp-swap.d.ts

@@ -0,0 +1,47 @@
+import type { createLdgrClient } from "@ldgr/client";
+import { type AmmRouteSwapHop } from "@ldgr/protocol";
+import type { McpRequest, McpWalletInfo } from "./mcp";
+type SwapRequest = Extract<McpRequest, {
+    action: "swap";
+}>;
+type Client = ReturnType<typeof createLdgrClient>;
+/** Build a fresh, reviewed route; callers retain sole ownership of approval and signing. */
+export declare function draftMcpSwap(request: SwapRequest, wallet: McpWalletInfo, client: Client): Promise<{
+    path: string;
+    payload: {
+        version: 1;
+        chain: import("@ldgr/protocol").ChainId;
+        ledgerId: import("@ldgr/protocol").LedgerId;
+        from: import("@ldgr/protocol").Address;
+        nonce: bigint;
+        timestamp: bigint;
+        memo?: string;
+        action: "amm_route_swap";
+        asset: "dng";
+        template: "amm_v1";
+        hops: readonly AmmRouteSwapHop[];
+        amountIn: import("@ldgr/protocol").AtomicAmount;
+        amountOutMin: import("@ldgr/protocol").AtomicAmount;
+        to?: import("@ldgr/protocol").Address;
+        publicKey?: string;
+    };
+    wire: {
+        version: 1;
+        chain: import("@ldgr/protocol").ChainId;
+        ledgerId: import("@ldgr/protocol").LedgerId;
+        from: import("@ldgr/protocol").Address;
+        memo?: string;
+        action: "amm_route_swap";
+        asset: "dng";
+        template: "amm_v1";
+        hops: readonly AmmRouteSwapHop[];
+        to?: import("@ldgr/protocol").Address;
+        publicKey?: string;
+        nonce: string;
+        timestamp: string;
+        amountIn: string;
+        amountOutMin: string;
+    };
+    review: string;
+}>;
+export {};

package/dist/mcp.d.ts

@@ -32,6 +32,15 @@ export type McpRequest = RequestBase & ({
         readonly expiresAt: string;
         readonly reference?: string;
     };
+} | {
+    readonly action: "swap";
+    readonly params: {
+        readonly assetIn: string;
+        readonly assetOut: string;
+        readonly amountIn: string;
+        readonly amountOutMin: string;
+        readonly maxHops?: 1 | 2 | 3;
+    };
 });
 export type McpWalletInfo = {
     readonly address: string;

package/dist/mcp.js

@@ -373,6 +373,16 @@ function validateMcpRequest(input) {
       if (typeof params.expiresAt !== "string" || !/^[1-9][0-9]{0,15}$/.test(params.expiresAt) || BigInt(params.expiresAt) <= BigInt(Date.now()) || BigInt(params.expiresAt) > BigInt(Number.MAX_SAFE_INTEGER))
         throw new TypeError("Escrow expiry must be future Unix milliseconds as a string");
     }
+  } else if (value.action === "swap") {
+    const params = object(value.params, ["assetIn", "assetOut", "amountIn", "amountOutMin", "maxHops"]);
+    const assetIn = resolvePublicAssetCode(text(params.assetIn, "input asset"), ledgerId);
+    const assetOut = resolvePublicAssetCode(text(params.assetOut, "output asset"), ledgerId);
+    if (assetIn === assetOut)
+      throw new TypeError("Swap assets must be distinct");
+    if (!/[1-9]/.test(amount(params.amountIn)) || !/[1-9]/.test(amount(params.amountOutMin)))
+      throw new TypeError("Swap input and minimum output must be positive");
+    if (params.maxHops !== undefined && ![1, 2, 3].includes(params.maxHops))
+      throw new TypeError("maxHops must be 1, 2 or 3");
   } else if (value.action === "create_token") {
     const params = object(value.params, ["displayName", "ticker", "decimals", "supplyMode", "initialSupply", "initialRecipient", "maxSupply"]);
     assertAssetDisplayName(text(params.displayName, "display name", 64));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ldgr/cli",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "type": "module",
   "bin": {
     "ldgr": "dist/cli.js"