@ldgr/cli 0.1.0

package/README.md

@@ -0,0 +1,18 @@
+# @ldgr/cli
+
+LDGR's self-custody terminal wallet. Version 0.1.0 creates or imports encrypted local wallets, lets you select between them, shows addresses and balances, sends native LDGR or a token, and persistently switches the selected wallet between mainnet and testnet.
+
+```bash
+npm install -g @ldgr/cli
+ldgr wallet create
+ldgr wallet import
+ldgr wallet list
+ldgr wallet select 2
+ldgr address
+ldgr balance
+ldgr send ldgr1… 2.5
+ldgr send-token t1abcdef01234567 ldgr1… 10
+ldgr network set testnet
+```
+
+The default owner-only wallet store lives at `~/.config/ldgr/wallet.json`. Each added wallet is encrypted separately using a passphrase requested on the terminal. `wallet list` shows one-based indexes and marks the active wallet; `wallet select <index>` changes it without exposing a secret. Record the recovery key shown at creation offline. `wallet import --testnet` imports a recovery key as a testnet wallet. Testnet prints a warning on every wallet command and only uses `https://tst.ldgr.ltd`.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,594 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import * as p from "@clack/prompts";
+import { createLdgrClient, LdgrClientError } from "@ldgr/client";
+import {
+  isBurnerWalletAddress,
+  nativeAssetDefinitionForLedger,
+  resolvePublicAssetCode
+} from "@ldgr/protocol";
+
+// src/transfer.ts
+import {
+  canonicalizeLedgerAddress,
+  formatAtomicAmount,
+  parseDecimalAmount
+} from "@ldgr/protocol";
+async function buildTransferSubmission(input) {
+  const recipient = canonicalizeLedgerAddress(input.to, input.wallet.ledgerId);
+  const amount = parseDecimalAmount(input.amount.trim(), input.assetDefinition);
+  if (amount <= 0n)
+    throw new RangeError("Amount must be greater than zero");
+  if (!/^(0|[1-9][0-9]*)$/.test(input.nextNonce))
+    throw new TypeError("Ledger returned an invalid next nonce");
+  const payload = {
+    version: 1,
+    action: "transfer",
+    chain: "ldgr-v1",
+    ledgerId: input.wallet.ledgerId,
+    asset: input.asset,
+    from: input.wallet.address,
+    to: recipient,
+    amount,
+    nonce: BigInt(input.nextNonce),
+    timestamp: BigInt((input.now ?? Date.now)()),
+    publicKey: input.wallet.publicKey
+  };
+  const signature = await input.wallet.sign(payload);
+  return {
+    payload: {
+      ...payload,
+      amount: formatAtomicAmount(amount, input.assetDefinition),
+      nonce: payload.nonce.toString(),
+      timestamp: payload.timestamp.toString()
+    },
+    signature
+  };
+}
+
+// src/wallet-file.ts
+import { generateLocalWallet, loadLocalWallet } from "@ldgr/client";
+import { canonicalizeLedgerAddress as canonicalizeLedgerAddress2 } from "@ldgr/protocol";
+import { lstat, mkdir, open, readFile, rename, unlink } from "node:fs/promises";
+import { dirname, join } from "node:path";
+var KDF_ITERATIONS = 310000;
+var AES_GCM = "AES-GCM";
+function arrayBuffer(bytes) {
+  return bytes.slice().buffer;
+}
+function encodeBase64Url(bytes) {
+  let binary = "";
+  for (const byte of bytes)
+    binary += String.fromCharCode(byte);
+  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+function decodeBase64Url(value) {
+  if (!/^[A-Za-z0-9_-]+$/.test(value))
+    throw new TypeError("Wallet file contains invalid base64url data");
+  const padded = value.replaceAll("-", "+").replaceAll("_", "/").padEnd(Math.ceil(value.length / 4) * 4, "=");
+  return Uint8Array.from(atob(padded), (character) => character.charCodeAt(0));
+}
+function networkForLedger(ledgerId) {
+  return ledgerId === 0 ? "testnet" : "mainnet";
+}
+async function deriveEncryptionKey(passphrase, salt) {
+  if (passphrase.length < 12)
+    throw new RangeError("Passphrase must be at least 12 characters");
+  const material = await crypto.subtle.importKey("raw", new TextEncoder().encode(passphrase), "PBKDF2", false, ["deriveKey"]);
+  return crypto.subtle.deriveKey({ name: "PBKDF2", hash: "SHA-256", salt: arrayBuffer(salt), iterations: KDF_ITERATIONS }, material, { name: AES_GCM, length: 256 }, false, ["encrypt", "decrypt"]);
+}
+function parseWalletEntry(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new TypeError("Wallet file is not a JSON object");
+  const file = value;
+  if (file.format !== "ldgr-cli-wallet" || file.version !== 1 || file.network !== "mainnet" && file.network !== "testnet" || file.ledgerId !== 0 && file.ledgerId !== 1 || typeof file.address !== "string" || typeof file.publicKey !== "string" || typeof file.ciphertext !== "string" || typeof file.iv !== "string" || !file.kdf || file.kdf.name !== "PBKDF2" || file.kdf.hash !== "SHA-256" || file.kdf.iterations !== KDF_ITERATIONS || typeof file.kdf.salt !== "string")
+    throw new TypeError("Unsupported wallet file format");
+  if (file.network !== networkForLedger(file.ledgerId))
+    throw new TypeError("Wallet file network does not match ledgerId");
+  canonicalizeLedgerAddress2(file.address, file.ledgerId);
+  return file;
+}
+function parseWalletStore(value) {
+  if (value && typeof value === "object" && !Array.isArray(value) && value.format === "ldgr-cli-wallet") {
+    return { format: "ldgr-cli-wallet-store", version: 1, activeWalletIndex: 0, wallets: [parseWalletEntry(value)] };
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new TypeError("Wallet file is not a JSON object");
+  const store = value;
+  const activeWalletIndex = store.activeWalletIndex;
+  const wallets = store.wallets;
+  if (store.format !== "ldgr-cli-wallet-store" || store.version !== 1 || typeof activeWalletIndex !== "number" || !Number.isInteger(activeWalletIndex) || !Array.isArray(wallets) || wallets.length === 0 || activeWalletIndex < 0 || activeWalletIndex >= wallets.length)
+    throw new TypeError("Unsupported wallet file format");
+  return {
+    format: "ldgr-cli-wallet-store",
+    version: 1,
+    activeWalletIndex,
+    wallets: wallets.map(parseWalletEntry)
+  };
+}
+function newWalletStore(file) {
+  return { format: "ldgr-cli-wallet-store", version: 1, activeWalletIndex: 0, wallets: [file] };
+}
+function serializeWalletStore(store) {
+  return `${JSON.stringify(store, null, 2)}
+`;
+}
+function defaultWalletPath(input = {}) {
+  const home = input.home ?? process.env.HOME;
+  if (!home)
+    throw new Error("Could not determine your home directory; use --wallet <path>");
+  const configHome = process.env.XDG_CONFIG_HOME?.trim() || join(home, ".config");
+  return join(configHome, "ldgr", "wallet.json");
+}
+async function createEncryptedWalletFile(input) {
+  const wallet = await generateLocalWallet({ ledgerId: input.ledgerId });
+  return encryptWallet({ wallet, recoveryKey: wallet.recoveryKey, passphrase: input.passphrase });
+}
+async function encryptWallet(input) {
+  const salt = crypto.getRandomValues(new Uint8Array(16));
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const key = await deriveEncryptionKey(input.passphrase, salt);
+  const plaintext = new TextEncoder().encode(JSON.stringify({ recoveryKey: input.recoveryKey }));
+  const ciphertext = new Uint8Array(await crypto.subtle.encrypt({ name: AES_GCM, iv: arrayBuffer(iv) }, key, plaintext));
+  plaintext.fill(0);
+  const file = {
+    format: "ldgr-cli-wallet",
+    version: 1,
+    network: networkForLedger(input.wallet.ledgerId),
+    ledgerId: input.wallet.ledgerId,
+    address: input.wallet.address,
+    publicKey: input.wallet.publicKey,
+    ciphertext: encodeBase64Url(ciphertext),
+    iv: encodeBase64Url(iv),
+    kdf: { name: "PBKDF2", hash: "SHA-256", iterations: KDF_ITERATIONS, salt: encodeBase64Url(salt) }
+  };
+  return { file, serialized: `${JSON.stringify(file, null, 2)}
+`, recoveryKey: input.recoveryKey };
+}
+async function writeNewWalletFile(path, file) {
+  await mkdir(dirname(path), { recursive: true, mode: 448 });
+  const handle = await open(path, "wx", 384).catch((error) => {
+    if (error.code === "EEXIST")
+      throw new Error(`Wallet file already exists: ${path}`);
+    throw error;
+  });
+  try {
+    await handle.writeFile(serializeWalletStore(newWalletStore(file)), "utf8");
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+async function readWalletStore(path) {
+  const details = await lstat(path).catch((error) => {
+    if (error.code === "ENOENT")
+      throw new Error(`Wallet file not found: ${path}`);
+    throw error;
+  });
+  if (!details.isFile() || details.isSymbolicLink() || details.nlink !== 1)
+    throw new Error("Wallet file must be a regular file with no links");
+  if ((details.mode & 63) !== 0)
+    throw new Error("Wallet file must be owner-only (chmod 600)");
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile(path, "utf8"));
+  } catch {
+    throw new TypeError("Wallet file is not valid JSON");
+  }
+  return parseWalletStore(parsed);
+}
+async function unlockWalletFile(file, passphrase) {
+  try {
+    const key = await deriveEncryptionKey(passphrase, decodeBase64Url(file.kdf.salt));
+    const plaintext = new Uint8Array(await crypto.subtle.decrypt({ name: AES_GCM, iv: arrayBuffer(decodeBase64Url(file.iv)) }, key, arrayBuffer(decodeBase64Url(file.ciphertext))));
+    const value = JSON.parse(new TextDecoder(undefined, { fatal: true }).decode(plaintext));
+    plaintext.fill(0);
+    if (typeof value.recoveryKey !== "string")
+      throw new Error("missing recovery key");
+    const wallet = await loadLocalWallet({ recoveryKey: value.recoveryKey, ledgerId: file.ledgerId });
+    if (wallet.address !== file.address || wallet.publicKey !== file.publicKey)
+      throw new Error("wallet identity mismatch");
+    return { wallet, recoveryKey: value.recoveryKey };
+  } catch {
+    throw new Error("Could not unlock wallet: check your passphrase or wallet file");
+  }
+}
+async function readEncryptedWalletFile(path, passphrase) {
+  const store = await readWalletStore(path);
+  const file = store.wallets[store.activeWalletIndex];
+  return (await unlockWalletFile(file, passphrase)).wallet;
+}
+async function replaceWalletStore(path, store) {
+  await readWalletStore(path);
+  const temporaryPath = join(dirname(path), `.${crypto.randomUUID()}.wallet.tmp`);
+  const handle = await open(temporaryPath, "wx", 384);
+  try {
+    await handle.writeFile(serializeWalletStore(store), "utf8");
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  try {
+    await rename(temporaryPath, path);
+  } catch (error) {
+    await unlink(temporaryPath).catch(() => {
+      return;
+    });
+    throw error;
+  }
+}
+async function addWalletFile(path, file) {
+  let store;
+  try {
+    store = await readWalletStore(path);
+  } catch (error) {
+    if (error instanceof Error && error.message === `Wallet file not found: ${path}`) {
+      await writeNewWalletFile(path, file);
+      return 0;
+    }
+    throw error;
+  }
+  if (store.wallets.some((entry) => entry.ledgerId === file.ledgerId && entry.publicKey === file.publicKey)) {
+    throw new Error("This wallet is already in the local wallet store for this network");
+  }
+  const index = store.wallets.length;
+  await replaceWalletStore(path, { ...store, activeWalletIndex: index, wallets: [...store.wallets, file] });
+  return index;
+}
+async function importEncryptedWalletFile(input) {
+  const wallet = await loadLocalWallet({ recoveryKey: input.recoveryKey, ledgerId: input.ledgerId });
+  const encrypted = await encryptWallet({ wallet, recoveryKey: input.recoveryKey, passphrase: input.passphrase });
+  return { file: encrypted.file, index: await addWalletFile(input.path, encrypted.file) };
+}
+async function listWalletFileMetadata(path) {
+  const store = await readWalletStore(path);
+  return store.wallets.map((wallet, index) => ({ ...wallet, index, selected: index === store.activeWalletIndex }));
+}
+async function selectWalletFile(path, index) {
+  const store = await readWalletStore(path);
+  if (!Number.isInteger(index) || index < 0 || index >= store.wallets.length) {
+    throw new RangeError(`Wallet index must be between 1 and ${store.wallets.length}`);
+  }
+  if (index !== store.activeWalletIndex)
+    await replaceWalletStore(path, { ...store, activeWalletIndex: index });
+  return store.wallets[index];
+}
+async function switchWalletNetwork(path, passphrase, ledgerId) {
+  const store = await readWalletStore(path);
+  const existing = store.wallets[store.activeWalletIndex];
+  if (existing.ledgerId === ledgerId)
+    return existing;
+  const unlocked = await unlockWalletFile(existing, passphrase);
+  const wallet = await loadLocalWallet({ recoveryKey: unlocked.recoveryKey, ledgerId });
+  const encrypted = await encryptWallet({ wallet, recoveryKey: unlocked.recoveryKey, passphrase });
+  if (store.wallets.some((entry, index) => index !== store.activeWalletIndex && entry.ledgerId === ledgerId && entry.publicKey === wallet.publicKey)) {
+    throw new Error("This recovery key already has a wallet in the selected network; select that wallet instead");
+  }
+  const wallets = [...store.wallets];
+  wallets[store.activeWalletIndex] = encrypted.file;
+  await replaceWalletStore(path, { ...store, wallets });
+  return encrypted.file;
+}
+async function walletFileMetadata(path) {
+  const store = await readWalletStore(path);
+  return store.wallets[store.activeWalletIndex];
+}
+
+// src/cli.ts
+var HELP = `
+LDGR CLI 0.1.0 — self-custody wallet
+
+Usage:
+  ldgr wallet create [--testnet] [--wallet <path>]
+  ldgr wallet import [--testnet] [--wallet <path>]
+  ldgr wallet list [--wallet <path>]
+  ldgr wallet select <index> [--wallet <path>]
+  ldgr address [--wallet <path>]
+  ldgr balance [--wallet <path>]
+  ldgr send <recipient> <amount> [--wallet <path>]
+  ldgr send-token <asset> <recipient> <amount> [--wallet <path>]
+  ldgr network show [--wallet <path>]
+  ldgr network set <mainnet|testnet> [--wallet <path>]
+
+The default wallet store is ~/.config/ldgr/wallet.json. Each wallet inside it
+is independently encrypted with a passphrase you enter through the terminal;
+the CLI never accepts recovery keys or passphrases as arguments or environment
+variables. Use \`ldgr wallet select <index>\` to change the active wallet, or
+\`ldgr network set testnet\` to switch its network persistently. Testnet mode
+prints a warning on every wallet command.
+`;
+function parseArguments(argv) {
+  const command = [];
+  let walletPath = defaultWalletPath();
+  let walletOnTestnet = false;
+  for (let index = 0;index < argv.length; index += 1) {
+    const value = argv[index];
+    if (value === "--wallet") {
+      const path = argv[index + 1];
+      if (!path || path.startsWith("-"))
+        throw new TypeError("--wallet requires a file path");
+      walletPath = path;
+      index += 1;
+    } else if (value === "--testnet") {
+      walletOnTestnet = true;
+    } else if (value === "--help" || value === "-h") {
+      command.push("help");
+    } else {
+      command.push(value);
+    }
+  }
+  if (walletOnTestnet && !(command[0] === "wallet" && (command[1] === "create" || command[1] === "import"))) {
+    throw new TypeError("--testnet is only used with wallet create or wallet import; use `ldgr network set testnet` to switch an existing wallet");
+  }
+  return { command, walletPath, walletOnTestnet };
+}
+function networkLabel(file) {
+  return file.ledgerId === 0 ? "testnet" : "mainnet";
+}
+function showNetworkWarning(file) {
+  if (file.ledgerId === 0) {
+    p.log.warn("TESTNET — this wallet and every transaction here use test tokens with no real-world value.");
+  }
+}
+async function askPassphrase(message) {
+  const answer = await p.password({
+    message,
+    validate(value) {
+      return value.length >= 12 ? undefined : "Use at least 12 characters";
+    }
+  });
+  if (p.isCancel(answer))
+    throw new Error("Cancelled");
+  return answer;
+}
+async function confirm2(message) {
+  const answer = await p.confirm({ message, initialValue: false });
+  if (p.isCancel(answer) || !answer)
+    throw new Error("Cancelled");
+}
+async function selectedClient(file) {
+  const client = createLdgrClient({ network: file.ledgerId });
+  const ledger = await client.ledger.get();
+  if (ledger.ledgerId !== file.ledgerId)
+    throw new Error("The selected LDGR endpoint returned a different ledger network");
+  return client;
+}
+function nativeDefinition(ledgerId) {
+  return nativeAssetDefinitionForLedger(ledgerId);
+}
+function assetDefinition(record) {
+  if (!Number.isSafeInteger(record.decimals) || record.decimals < 0)
+    throw new TypeError("Asset metadata contains invalid decimals");
+  if (!record.displayName.trim())
+    throw new TypeError("Asset metadata is missing its display name");
+  const ticker = record.ticker?.trim() || record.code;
+  return { ...record, ticker, displayName: record.displayName.trim() };
+}
+async function definitionForAsset(client, asset, ledgerId) {
+  if (asset === "dng")
+    return nativeDefinition(ledgerId);
+  return assetDefinition(await client.assets.get(asset));
+}
+async function runCreate(path, testnet) {
+  const ledgerId = testnet ? 0 : 1;
+  if (ledgerId === 0)
+    showNetworkWarning({ ledgerId });
+  const passphrase = await askPassphrase("Choose a wallet passphrase");
+  const confirmation = await askPassphrase("Repeat the wallet passphrase");
+  if (passphrase !== confirmation)
+    throw new Error("Passphrases did not match");
+  const spinner2 = p.spinner();
+  spinner2.start("Generating and encrypting your wallet");
+  const created = await createEncryptedWalletFile({ ledgerId, passphrase });
+  const index = await addWalletFile(path, created.file);
+  spinner2.stop("Encrypted wallet added");
+  p.note(`Address
+${created.file.address}
+
+Recovery key — save this offline now; it will not be shown again
+${created.recoveryKey}`, "Your self-custody backup");
+  p.log.warn("This recovery key alone can restore and control this wallet. Your passphrase protects only this local file; never share either secret.");
+  p.outro(`Wallet #${index + 1} selected in ${path}`);
+}
+async function runImport(path, testnet) {
+  const ledgerId = testnet ? 0 : 1;
+  if (ledgerId === 0)
+    showNetworkWarning({ ledgerId });
+  const recoveryKey = await p.password({
+    message: "Enter the recovery key to import",
+    validate(value) {
+      return value.trim() ? undefined : "Enter a recovery key";
+    }
+  });
+  if (p.isCancel(recoveryKey))
+    throw new Error("Cancelled");
+  const passphrase = await askPassphrase("Choose a passphrase for this imported wallet");
+  const confirmation = await askPassphrase("Repeat the wallet passphrase");
+  if (passphrase !== confirmation)
+    throw new Error("Passphrases did not match");
+  const spinner2 = p.spinner();
+  spinner2.start("Validating and encrypting imported wallet");
+  const imported = await importEncryptedWalletFile({ path, recoveryKey, ledgerId, passphrase });
+  spinner2.stop("Imported wallet added");
+  p.note(`Address
+${imported.file.address}
+
+Network
+${networkLabel(imported.file)}`, `Wallet #${imported.index + 1} selected`);
+  if (ledgerId === 0)
+    showNetworkWarning(imported.file);
+  p.outro(`Wallet #${imported.index + 1} added to ${path}`);
+}
+async function runWalletList(path) {
+  const wallets = await listWalletFileMetadata(path);
+  const selected = wallets.find((wallet) => wallet.selected);
+  showNetworkWarning(selected);
+  const rows = wallets.map((wallet) => [
+    `${wallet.selected ? "● Selected" : "○"}  #${wallet.index + 1} · ${networkLabel(wallet)}`,
+    wallet.address
+  ].join(`
+`));
+  p.note(rows.join(`
+
+`), `${wallets.length} local wallet${wallets.length === 1 ? "" : "s"}`);
+  p.outro("Wallet list ready");
+}
+async function runWalletSelect(path, rawIndex) {
+  if (!/^[1-9][0-9]*$/.test(rawIndex))
+    throw new TypeError("Wallet index must be a positive number");
+  const selected = await selectWalletFile(path, Number(rawIndex) - 1);
+  showNetworkWarning(selected);
+  p.note(`${selected.address}
+
+Network: ${networkLabel(selected)}`, `Wallet #${rawIndex} selected`);
+  p.outro("Wallet selected");
+}
+async function runAddress(path) {
+  const file = await walletFileMetadata(path);
+  showNetworkWarning(file);
+  p.note(`${file.address}
+
+Network: ${networkLabel(file)}
+Wallet: ${path}`, "LDGR wallet address");
+  p.outro("Address ready");
+}
+async function runBalance(path) {
+  const file = await walletFileMetadata(path);
+  showNetworkWarning(file);
+  const spinner2 = p.spinner();
+  spinner2.start("Loading balances");
+  const client = await selectedClient(file);
+  const result = await client.accounts.listBalances(file.address);
+  const rows = await Promise.all(result.balances.map(async (balance) => {
+    const definition = await definitionForAsset(client, balance.asset, file.ledgerId);
+    return `${balance.amount} ${definition.ticker}  ${definition.displayName}
+${balance.asset === "dng" ? `t${file.ledgerId}` : balance.asset}`;
+  }));
+  spinner2.stop("Balances loaded");
+  p.note(rows.length === 0 ? "No positive balances yet." : rows.join(`
+
+`), `${file.address} · ${networkLabel(file)}`);
+  p.outro("Balance ready");
+}
+async function runSend(path, rawAsset, recipient, amount) {
+  const file = await walletFileMetadata(path);
+  showNetworkWarning(file);
+  const client = await selectedClient(file);
+  const asset = resolvePublicAssetCode(rawAsset, file.ledgerId);
+  const definition = await definitionForAsset(client, asset, file.ledgerId);
+  const passphrase = await askPassphrase("Enter your wallet passphrase to sign");
+  const wallet = await readEncryptedWalletFile(path, passphrase);
+  const makeSubmission = async () => buildTransferSubmission({
+    wallet,
+    asset,
+    assetDefinition: definition,
+    amount,
+    to: recipient,
+    nextNonce: (await client.accounts.getNextNonce(wallet.address, asset)).nextNonce
+  });
+  let submission = await makeSubmission();
+  p.note(`${definition.displayName} (${definition.ticker})
+${submission.payload.amount}
+
+To
+${submission.payload.to}
+
+Network
+${networkLabel(file)}`, "Review transfer");
+  if (isBurnerWalletAddress(String(submission.payload.to))) {
+    p.log.warn("This recipient is the irreversible burn address. The transferred amount cannot be recovered.");
+  }
+  await confirm2("Sign and submit this transfer?");
+  const spinner2 = p.spinner();
+  spinner2.start("Submitting signed transfer");
+  let transaction;
+  try {
+    transaction = await client.submitSigned("/api/v1/transfers", submission);
+  } catch (error) {
+    if (!(error instanceof LdgrClientError) || error.code !== "NONCE_MISMATCH")
+      throw error;
+    submission = await makeSubmission();
+    transaction = await client.submitSigned("/api/v1/transfers", submission);
+  }
+  spinner2.stop("Transfer settled");
+  const hash = typeof transaction.transactionHash === "string" ? transaction.transactionHash : "(transaction hash unavailable)";
+  p.outro(`Sent ${String(submission.payload.amount)} ${definition.ticker}
+Transaction: ${hash}`);
+}
+async function runNetwork(path, target) {
+  const file = await walletFileMetadata(path);
+  showNetworkWarning(file);
+  if (target === undefined) {
+    p.note(`${networkLabel(file)}
+${file.address}`, "Selected network");
+    p.outro("Network ready");
+    return;
+  }
+  if (target !== "mainnet" && target !== "testnet")
+    throw new TypeError("Choose mainnet or testnet");
+  const ledgerId = target === "testnet" ? 0 : 1;
+  if (file.ledgerId === ledgerId) {
+    p.outro(`Already using ${target}`);
+    return;
+  }
+  if (ledgerId === 0)
+    showNetworkWarning({ ledgerId });
+  p.log.info("Switching networks derives a different address from the same self-custody key.");
+  const passphrase = await askPassphrase("Enter your wallet passphrase to switch networks");
+  await confirm2(`Switch this wallet to ${target}?`);
+  const spinner2 = p.spinner();
+  spinner2.start("Re-encrypting wallet for the selected network");
+  const switched = await switchWalletNetwork(path, passphrase, ledgerId);
+  spinner2.stop("Network switched");
+  showNetworkWarning(switched);
+  p.outro(`${target} address: ${switched.address}`);
+}
+async function main() {
+  let parsed;
+  try {
+    parsed = parseArguments(process.argv.slice(2));
+  } catch (error) {
+    process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
+`);
+    process.exitCode = 1;
+    return;
+  }
+  const [first, second, third, fourth] = parsed.command;
+  if (first === undefined || first === "help") {
+    process.stdout.write(HELP);
+    return;
+  }
+  p.intro("LDGR CLI");
+  try {
+    if (first === "wallet" && second === "create" && third === undefined)
+      await runCreate(parsed.walletPath, parsed.walletOnTestnet);
+    else if (first === "wallet" && second === "import" && third === undefined)
+      await runImport(parsed.walletPath, parsed.walletOnTestnet);
+    else if (first === "wallet" && second === "list" && third === undefined)
+      await runWalletList(parsed.walletPath);
+    else if (first === "wallet" && second === "select" && third && fourth === undefined)
+      await runWalletSelect(parsed.walletPath, third);
+    else if (first === "address" && second === undefined)
+      await runAddress(parsed.walletPath);
+    else if (first === "balance" && second === undefined)
+      await runBalance(parsed.walletPath);
+    else if (first === "send" && second && third && fourth === undefined)
+      await runSend(parsed.walletPath, "dng", second, third);
+    else if (first === "send-token" && second && third && fourth)
+      await runSend(parsed.walletPath, second, third, fourth);
+    else if (first === "network" && second === "show" && third === undefined)
+      await runNetwork(parsed.walletPath);
+    else if (first === "network" && second === "set" && third && fourth === undefined)
+      await runNetwork(parsed.walletPath, third);
+    else
+      throw new TypeError("Unknown command. Run `ldgr --help` for available commands.");
+  } catch (error) {
+    if (error instanceof Error && error.message === "Cancelled")
+      p.cancel("Cancelled");
+    else
+      p.cancel(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  }
+}
+await main();

package/dist/transfer.d.ts

@@ -0,0 +1,14 @@
+import type { LdgrSigner } from "@ldgr/client";
+import { type AssetDefinition } from "@ldgr/protocol";
+export declare function buildTransferSubmission(input: {
+    readonly wallet: LdgrSigner;
+    readonly asset: string;
+    readonly assetDefinition: AssetDefinition;
+    readonly amount: string;
+    readonly to: string;
+    readonly nextNonce: string;
+    readonly now?: () => number;
+}): Promise<{
+    readonly payload: Record<string, unknown>;
+    readonly signature: string;
+}>;

package/dist/wallet-file.d.ts

@@ -0,0 +1,61 @@
+import { type LdgrSigner } from "@ldgr/client";
+import { type LedgerId } from "@ldgr/protocol";
+export type WalletNetwork = "mainnet" | "testnet";
+export type EncryptedWalletFile = {
+    readonly format: "ldgr-cli-wallet";
+    readonly version: 1;
+    readonly network: WalletNetwork;
+    readonly ledgerId: LedgerId;
+    readonly address: string;
+    readonly publicKey: string;
+    readonly ciphertext: string;
+    readonly iv: string;
+    readonly kdf: {
+        readonly name: "PBKDF2";
+        readonly hash: "SHA-256";
+        readonly iterations: number;
+        readonly salt: string;
+    };
+};
+export type EncryptedWalletStore = {
+    readonly format: "ldgr-cli-wallet-store";
+    readonly version: 1;
+    readonly activeWalletIndex: number;
+    readonly wallets: readonly EncryptedWalletFile[];
+};
+export type WalletFileMetadata = EncryptedWalletFile & {
+    readonly index: number;
+    readonly selected: boolean;
+};
+export type CreatedEncryptedWallet = {
+    readonly file: EncryptedWalletFile;
+    readonly serialized: string;
+    /** Display once during creation; never persist or log this value. */
+    readonly recoveryKey: string;
+};
+export declare function defaultWalletPath(input?: {
+    readonly home?: string | undefined;
+}): string;
+export declare function createEncryptedWalletFile(input: {
+    readonly ledgerId: LedgerId;
+    readonly passphrase: string;
+}): Promise<CreatedEncryptedWallet>;
+export declare function writeNewWalletFile(path: string, file: EncryptedWalletFile): Promise<void>;
+export declare function readEncryptedWalletFile(path: string, passphrase: string): Promise<LdgrSigner>;
+/** Adds a separately encrypted wallet and selects it. */
+export declare function addWalletFile(path: string, file: EncryptedWalletFile): Promise<number>;
+/** Encrypts canonical recovery material, adds it to the store, and selects it. */
+export declare function importEncryptedWalletFile(input: {
+    readonly path: string;
+    readonly recoveryKey: string;
+    readonly ledgerId: LedgerId;
+    readonly passphrase: string;
+}): Promise<{
+    readonly file: EncryptedWalletFile;
+    readonly index: number;
+}>;
+export declare function listWalletFileMetadata(path: string): Promise<readonly WalletFileMetadata[]>;
+export declare function selectWalletFile(path: string, index: number): Promise<EncryptedWalletFile>;
+/** Re-encrypts the same self-custody key for a different LDGR ledger. */
+export declare function switchWalletNetwork(path: string, passphrase: string, ledgerId: LedgerId): Promise<EncryptedWalletFile>;
+export declare function walletFileMetadata(path: string): Promise<EncryptedWalletFile>;

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@ldgr/cli",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "ldgr": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "dependencies": {
+    "@ldgr/client": "^0.2.1",
+    "@ldgr/protocol": "^0.2.0",
+    "@clack/prompts": "^0.11.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && bun build src/cli.ts --outdir dist --target node --format esm --packages external && tsc -p tsconfig.build.json",
+    "prepack": "bun run build",
+    "start": "bun src/cli.ts",
+    "test": "bun test",
+    "typecheck": "tsc -p tsconfig.json"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "typescript": "^5.9.3"
+  }
+}