@did-btcr2/cli 0.17.0 → 0.18.1

package/dist/cjs/index.js

@@ -29,6 +29,7 @@ __export(index_exports, {
   SUPPORTED_NETWORKS: () => SUPPORTED_NETWORKS,
   VERSION: () => VERSION,
   assertKeystoreAllowedForNetwork: () => assertKeystoreAllowedForNetwork,
+  assertSupportedNetwork: () => assertSupportedNetwork,
   blankToUndef: () => blankToUndef,
   defaultApiFactory: () => defaultApiFactory,
   defaultConfigPath: () => defaultConfigPath,
@@ -39,9 +40,11 @@ __export(index_exports, {
   keystoreApiFactory: () => keystoreApiFactory,
   parseConfigFileRaw: () => parseConfigFileRaw,
   parseHeaderList: () => parseHeaderList,
+  persistDefaultNetwork: () => persistDefaultNetwork,
   profileNetworkMismatch: () => profileNetworkMismatch,
   profileToOverrides: () => profileToOverrides,
   readConfigFile: () => readConfigFile,
+  readConfiguredDefaultNetwork: () => readConfiguredDefaultNetwork,
   readEnvOverrides: () => readEnvOverrides,
   redactSecrets: () => redactSecrets,
   registerCompletionCommand: () => registerCompletionCommand,
@@ -52,6 +55,7 @@ __export(index_exports, {
   registerKeyCommand: () => registerKeyCommand,
   registerKeystoreCommand: () => registerKeystoreCommand,
   registerProfileCommand: () => registerProfileCommand,
+  registerQuickstartCommand: () => registerQuickstartCommand,
   registerResolveCommand: () => registerResolveCommand,
   registerUpdateCommand: () => registerUpdateCommand,
   resolveActiveProfile: () => resolveActiveProfile,
@@ -1310,6 +1314,45 @@ function resolveDefaultNetwork(overrides) {
   if (network) return network;
   return "regtest";
 }
+function readConfiguredDefaultNetwork(overrides) {
+  const configPath = overrides?.config ?? defaultConfigPath(overrides);
+  let raw;
+  try {
+    raw = parseConfigFileRaw(configPath);
+  } catch {
+    return void 0;
+  }
+  const value = raw ? getConfigPath(raw, "defaults.network") : void 0;
+  return typeof value === "string" && SUPPORTED_NETWORKS.includes(value) ? value : void 0;
+}
+function persistDefaultNetwork(configPath, opts) {
+  const raw = parseConfigFileRaw(configPath);
+  const rawValue = raw ? getConfigPath(raw, "defaults.network") : void 0;
+  const rawNetwork = typeof rawValue === "string" && SUPPORTED_NETWORKS.includes(rawValue) ? rawValue : void 0;
+  if (opts.explicit) {
+    if (opts.explicit !== rawNetwork) {
+      writeConfigFile(configPath, (r) => setConfigPath(r, "defaults.network", opts.explicit));
+      return { network: opts.explicit, wrote: true };
+    }
+    return { network: opts.explicit, wrote: false };
+  }
+  if (rawNetwork) return { network: rawNetwork, wrote: false };
+  if (opts.fallback) {
+    writeConfigFile(configPath, (r) => setConfigPath(r, "defaults.network", opts.fallback));
+    return { network: opts.fallback, wrote: true };
+  }
+  return { network: resolveDefaultNetwork(opts.overrides), wrote: false };
+}
+function assertSupportedNetwork(value) {
+  if (!SUPPORTED_NETWORKS.includes(value)) {
+    throw new CLIError(
+      `Invalid network "${value}". Must be one of ${SUPPORTED_NETWORKS.join(", ")}.`,
+      "INVALID_ARGUMENT_ERROR",
+      { network: value }
+    );
+  }
+  return value;
+}
 function profileNetworkMismatch(network, overrides) {
   let file;
   try {
@@ -1682,51 +1725,384 @@ function formatResult(result, options) {
 }
 
 // src/commands/init.ts
+function runInit(g, options = {}) {
+  const home = resolveHome(g);
+  const configPath = g.config ?? defaultConfigPath(g);
+  const keystorePath = resolveKeystorePath(g);
+  ensureDir(home, 448);
+  const created = [];
+  if (!(0, import_node_fs7.existsSync)(configPath) || options.force) {
+    writeDefaultConfigFile(configPath);
+    created.push("config");
+  }
+  const keystoreExists = (0, import_node_fs7.existsSync)(keystorePath);
+  if (keystoreExists && options.force && !g.quiet) {
+    process.stderr.write(
+      `note: a keystore already exists at ${keystorePath} and was left intact. To re-establish it (discarding its keys), run "btcr2 keystore init --force".
+`
+    );
+  }
+  let establishedPassphrase;
+  if (!keystoreExists) {
+    if (options.dev && !g.quiet) {
+      process.stderr.write(
+        "warning: establishing an UNENCRYPTED dev keystore. Keys are stored in plaintext. Use it only for disposable testnet material; mainnet operations will be refused.\n"
+      );
+    }
+    initKeystore(keystorePath, {
+      protection: options.dev ? "none" : "passphrase",
+      getPassphrase: (opts) => {
+        const passphrase = acquirePassphrase({
+          passphraseFile: g.passphraseFile,
+          confirm: opts?.confirm,
+          prompt: "New keystore passphrase: "
+        });
+        if (options.captureEstablishedPassphrase && !options.dev) establishedPassphrase = passphrase;
+        return passphrase;
+      }
+    });
+    clearSession(defaultSessionPath(g));
+    created.push("keystore");
+  }
+  const { network } = persistDefaultNetwork(configPath, {
+    explicit: options.network,
+    fallback: options.fallbackNetwork,
+    overrides: g
+  });
+  const protection = keystoreSummary(keystorePath).protection;
+  return { home, config: configPath, keystore: keystorePath, network, created, protection, establishedPassphrase };
+}
 function registerInitCommand(program, globals) {
   const print = (result) => console.log(formatResult(result, globals()));
-  program.command("init").description("Set up the btcr2 home: create the directory, a default config, and establish the keystore.").option("--dev", "Establish an UNENCRYPTED dev keystore: plaintext keys, no passphrase. Testnet only.", false).option("--force", "Re-create the config and keystore even if they already exist.", false).action((options) => {
+  program.command("init").description("Set up the btcr2 home: create the directory, a default config, and establish the keystore.").option(
+    "-n, --network <network>",
+    "Bitcoin network to record as defaults.network <bitcoin|testnet3|testnet4|signet|mutinynet|regtest>"
+  ).option("--dev", "Establish an UNENCRYPTED dev keystore: plaintext keys, no passphrase. Testnet only.", false).option("--force", "Re-create the config even if it already exists (never the keystore).", false).action((options) => {
     const g = globals();
-    const home = resolveHome(g);
-    const configPath = g.config ?? defaultConfigPath(g);
-    const keystorePath = resolveKeystorePath(g);
-    ensureDir(home, 448);
-    const created = [];
-    if (!(0, import_node_fs7.existsSync)(configPath) || options.force) {
-      writeDefaultConfigFile(configPath);
-      created.push("config");
-    }
-    const keystoreExists = (0, import_node_fs7.existsSync)(keystorePath);
-    if (keystoreExists && options.force && !g.quiet) {
-      process.stderr.write(
-        `note: a keystore already exists at ${keystorePath} and was left intact. To re-establish it (discarding its keys), run "btcr2 keystore init --force".
-`
+    const network = options.network ? assertSupportedNetwork(options.network) : void 0;
+    const result = runInit(g, { dev: options.dev, force: options.force, network });
+    print({
+      action: "init",
+      data: {
+        home: result.home,
+        config: result.config,
+        keystore: result.keystore,
+        network: result.network,
+        created: result.created,
+        protection: result.protection
+      }
+    });
+    if (!g.quiet && g.output !== "json") {
+      process.stderr.write(`btcr2 home ready at ${result.home} on ${result.network}. Next: btcr2 key generate --set-active
+`);
+    }
+  });
+}
+
+// src/commands/quickstart.ts
+var import_api2 = require("@did-btcr2/api");
+
+// src/commands/keystore.ts
+var import_node_fs8 = require("fs");
+function registerKeystoreCommand(program, globals) {
+  const keystore = program.command("keystore").description("Establish, inspect, re-key, and unlock the keystore.");
+  const print = (result) => console.log(formatResult(result, globals()));
+  keystore.command("init").description("Establish the keystore (encrypted by default). Prompts for a passphrase and confirms it.").option("--dev", "Create an UNENCRYPTED dev keystore: plaintext keys, no passphrase. Testnet only; mainnet operations are refused.", false).option("--force", "Re-establish even if a keystore already exists (discards its keys).", false).action((options) => {
+    const g = globals();
+    const path = resolveKeystorePath(g);
+    if ((0, import_node_fs8.existsSync)(path) && !options.force) {
+      throw new CLIError(
+        `A keystore already exists at ${path}. Use --force to re-establish it (this discards its keys).`,
+        "INVALID_ARGUMENT_ERROR",
+        { path }
       );
     }
-    if (!keystoreExists) {
-      if (options.dev && !g.quiet) {
+    if ((0, import_node_fs8.existsSync)(path) && options.force && !g.quiet) {
+      const { keyCount } = keystoreSummary(path);
+      if (keyCount > 0) {
         process.stderr.write(
-          "warning: establishing an UNENCRYPTED dev keystore. Keys are stored in plaintext. Use it only for disposable testnet material; mainnet operations will be refused.\n"
+          `warning: re-establishing the keystore at ${path} permanently discards its ${keyCount} existing key(s).
+`
         );
       }
-      initKeystore(keystorePath, {
-        protection: options.dev ? "none" : "passphrase",
-        getPassphrase: (opts) => acquirePassphrase({ passphraseFile: g.passphraseFile, confirm: opts?.confirm, prompt: "New keystore passphrase: " })
-      });
-      clearSession(defaultSessionPath(g));
-      created.push("keystore");
     }
-    const protection = keystoreSummary(keystorePath).protection;
-    print({ action: "init", data: { home, config: configPath, keystore: keystorePath, created, protection } });
+    if (options.dev && !g.quiet) {
+      process.stderr.write(
+        "warning: creating an UNENCRYPTED dev keystore. Keys are stored in plaintext. Use it only for disposable testnet material; mainnet operations will be refused.\n"
+      );
+    }
+    initKeystore(path, {
+      protection: options.dev ? "none" : "passphrase",
+      getPassphrase: (opts) => acquirePassphrase({ passphraseFile: g.passphraseFile, confirm: opts?.confirm, prompt: "New keystore passphrase: " })
+    });
+    clearSession(defaultSessionPath(g));
+    print({ action: "keystore-init", data: { path, protection: options.dev ? "dev" : "encrypted" } });
+  });
+  keystore.command("status").description("Show the keystore path, protection mode, key count, and session state. Never decrypts or prompts.").action(() => {
+    const g = globals();
+    const path = resolveKeystorePath(g, { lenient: true });
+    const summary = keystoreSummary(path);
+    const session = readSessionStatus(defaultSessionPath(g), path, keystoreVerifierId(path));
+    if (summary.protection === "dev" && !g.quiet && g.output !== "json") {
+      process.stderr.write("warning: this is an UNENCRYPTED dev keystore; keys are stored in plaintext.\n");
+    }
+    print({ action: "keystore-status", data: { path, ...summary, session } });
+  });
+  keystore.command("change-passphrase").alias("passwd").description("Change the keystore passphrase, re-sealing every key under the new one. Encrypted keystores only.").action(() => {
+    const g = globals();
+    const path = resolveKeystorePath(g);
+    const summary = keystoreSummary(path);
+    if (summary.protection === "absent") {
+      throw new CLIError(`No keystore at ${path}. Run "btcr2 keystore init" first.`, "INVALID_ARGUMENT_ERROR", { path });
+    }
+    if (summary.protection === "dev") {
+      throw new CLIError(
+        `The keystore at ${path} is an unencrypted dev keystore; there is no passphrase to change.`,
+        "INVALID_ARGUMENT_ERROR",
+        { path }
+      );
+    }
+    const oldPassphrase = acquirePassphrase({ passphraseFile: g.passphraseFile, prompt: "Current keystore passphrase: " });
+    const newPassphrase = acquirePassphrase({ forcePrompt: true, confirm: true, prompt: "New keystore passphrase: " });
+    const rekeyed = changeKeystorePassphrase(path, oldPassphrase, newPassphrase);
+    clearSession(defaultSessionPath(g));
+    print({ action: "keystore-change-passphrase", data: { path, rekeyed } });
+  });
+  keystore.command("unlock").description("Cache the keystore passphrase for a session so later commands do not re-prompt (ADR 081).").option("--ttl <duration>", `Session lifetime: bare seconds or an s/m/h suffix (default 1h, max 24h). Also $${ENV_KEYSTORE_TTL}.`).option("--allow-mainnet", "Permit unlocking when the active network is mainnet (bitcoin); this suspends per-use passphrase auth for the session.", false).action((options) => {
+    const g = globals();
+    const path = resolveKeystorePath(g);
+    const ttlMs = resolveSessionTtl(options.ttl);
+    const session = unlockSession({
+      g,
+      keystorePath: path,
+      network: resolveDefaultNetwork(g),
+      allowMainnet: !!options.allowMainnet,
+      ttlMs
+    });
+    print({ action: "keystore-unlock", data: { keystore: path, expiresAt: session.expiresAt, ttlSeconds: session.ttlSeconds } });
+  });
+  keystore.command("lock").description("Revoke the cached session so later commands prompt for the passphrase again (ADR 081).").action(() => {
+    const g = globals();
+    const sessionPath = defaultSessionPath(g);
+    const cleared = clearSession(sessionPath);
+    print({ action: "keystore-lock", data: { path: sessionPath, cleared } });
+  });
+}
+function unlockSession(input) {
+  const { g, keystorePath: path, network, allowMainnet, ttlMs } = input;
+  const summary = keystoreSummary(path);
+  if (summary.protection === "absent") {
+    throw new CLIError(`No keystore at ${path}. Run "btcr2 init" or "btcr2 keystore init" first.`, "INVALID_ARGUMENT_ERROR", { path });
+  }
+  if (summary.protection === "dev") {
+    throw new CLIError(
+      `The keystore at ${path} is an unencrypted dev keystore; it has no passphrase to cache, so no unlock is needed.`,
+      "INVALID_ARGUMENT_ERROR",
+      { path }
+    );
+  }
+  if (!summary.established) {
+    throw new CLIError(
+      `The keystore at ${path} has no passphrase established yet. Establish one with "btcr2 keystore init" or the first "btcr2 key generate".`,
+      "INVALID_ARGUMENT_ERROR",
+      { path }
+    );
+  }
+  if (!allowMainnet && network === "bitcoin") {
+    throw new CLIError(
+      "Refusing to unlock for a mainnet (bitcoin) context: caching the passphrase suspends per-use authentication for the session. Pass --allow-mainnet to override, or keep signing mainnet updates with a per-use passphrase prompt.",
+      "MAINNET_UNLOCK_REFUSED_ERROR",
+      { path }
+    );
+  }
+  const passphrase = input.passphrase ?? acquirePassphrase({ passphraseFile: g.passphraseFile, prompt: "Keystore passphrase: " });
+  if (!verifyKeystorePassphrase(path, passphrase)) {
+    throw new CLIError(`Incorrect passphrase for the keystore at ${path}; no session was created.`, "DECRYPT_ERROR", { path });
+  }
+  const verifierId = keystoreVerifierId(path);
+  if (!verifierId) {
+    throw new CLIError(`The keystore at ${path} has no verifier to bind a session to.`, "INVALID_ARGUMENT_ERROR", { path });
+  }
+  return writeSession(defaultSessionPath(g), {
+    keystorePath: path,
+    verifierId,
+    passphrase,
+    ttlMs,
+    allowMainnet
+  });
+}
+function resolveSessionTtl(flag) {
+  const fromFlag = blankToUndef(flag);
+  const raw = fromFlag ?? blankToUndef(process.env[ENV_KEYSTORE_TTL]);
+  if (raw === void 0) return DEFAULT_SESSION_TTL_MS;
+  const source = fromFlag !== void 0 ? "--ttl" : `$${ENV_KEYSTORE_TTL}`;
+  const ms = parseTtlToMs(raw);
+  if (ms === void 0 || ms <= 0) {
+    throw new CLIError(
+      `Invalid ${source} "${raw}": expected seconds or a value with an s/m/h suffix, e.g. 3600, 45m, or 2h.`,
+      "INVALID_ARGUMENT_ERROR",
+      { value: raw, source }
+    );
+  }
+  if (ms > MAX_SESSION_TTL_MS) {
+    throw new CLIError(
+      `${source} "${raw}" exceeds the 24h maximum for a cached passphrase.`,
+      "INVALID_ARGUMENT_ERROR",
+      { value: raw, source }
+    );
+  }
+  return ms;
+}
+
+// src/commands/quickstart.ts
+var QUICKSTART_DEFAULT_NETWORK = "mutinynet";
+function registerQuickstartCommand(program, globals) {
+  const print = (result) => console.log(formatResult(result, globals()));
+  program.command("quickstart").description("One-command onboarding: create the home + config + keystore, record the network, and (optionally) cache the session and probe endpoints.").option(
+    "-n, --network <network>",
+    "Bitcoin network to set up <bitcoin|testnet3|testnet4|signet|mutinynet|regtest> (default: mutinynet)"
+  ).option("--dev", "Establish an UNENCRYPTED dev keystore: plaintext keys, no passphrase. Testnet only.", false).option("--unlock", "Cache the passphrase for the session so later commands do not re-prompt (ADR 081).", false).option("--ttl <duration>", `Session lifetime with --unlock: bare seconds or an s/m/h suffix (default 1h, max 24h). Also $${ENV_KEYSTORE_TTL}.`).option("--no-doctor", "Skip the endpoint reachability probe.").option("--allow-mainnet", "Permit -n bitcoin (records mainnet as the default; dev keystores are still refused).", false).option("--force", "Re-create the config even if it already exists (never the keystore).", false).action(async (options) => {
+    const g = globals();
+    const explicit = options.network ? assertSupportedNetwork(options.network) : void 0;
+    const network = explicit ?? readConfiguredDefaultNetwork(g) ?? QUICKSTART_DEFAULT_NETWORK;
+    if (network === "bitcoin") {
+      if (options.dev) {
+        throw new CLIError(
+          "Refusing to quickstart a mainnet (bitcoin) dev keystore: dev keystores store keys in plaintext and never operate on mainnet. Drop --dev, or choose a testnet with -n.",
+          "MAINNET_QUICKSTART_REFUSED_ERROR",
+          { network }
+        );
+      }
+      if (!options.allowMainnet) {
+        throw new CLIError(
+          "Refusing to quickstart on mainnet (bitcoin) without --allow-mainnet. Pass --allow-mainnet to record mainnet as the default, or choose a testnet with -n (the default is mutinynet).",
+          "MAINNET_QUICKSTART_REFUSED_ERROR",
+          { network }
+        );
+      }
+    }
+    const init = runInit(g, {
+      dev: options.dev,
+      force: options.force,
+      network: explicit,
+      fallbackNetwork: explicit ? void 0 : QUICKSTART_DEFAULT_NETWORK,
+      captureEstablishedPassphrase: !!options.unlock && !options.dev
+    });
+    let unlocked = false;
+    let session;
+    if (options.unlock && !options.dev) {
+      const outcome = cacheSession(g, init, options.ttl, !!options.allowMainnet);
+      unlocked = outcome.unlocked;
+      session = outcome.session;
+    }
+    let doctor;
+    if (options.doctor) {
+      doctor = await runDoctor(init.network, g);
+    }
+    print({
+      action: "quickstart",
+      data: {
+        home: init.home,
+        config: init.config,
+        keystore: init.keystore,
+        network: init.network,
+        created: init.created,
+        protection: init.protection,
+        unlocked,
+        ...session ? { session } : {},
+        ...doctor ? { doctor } : {}
+      }
+    });
     if (!g.quiet && g.output !== "json") {
-      process.stderr.write(`btcr2 home ready at ${home}. Next: btcr2 key generate --set-active
-`);
+      printNextSteps(init, unlocked, session, doctor);
     }
   });
 }
+function cacheSession(g, init, ttlFlag, allowMainnet) {
+  const ttlMs = resolveSessionTtl(ttlFlag);
+  const freshlyEstablished = init.created.includes("keystore");
+  if (!freshlyEstablished) {
+    const status = readSessionStatus(defaultSessionPath(g), init.keystore, keystoreVerifierId(init.keystore));
+    if (status.active && status.expiresAt !== void 0) {
+      return { unlocked: true, session: { expiresAt: status.expiresAt, ttlSeconds: status.secondsRemaining ?? 0 } };
+    }
+  }
+  try {
+    const written = unlockSession({
+      g,
+      keystorePath: init.keystore,
+      network: init.network,
+      allowMainnet,
+      ttlMs,
+      // Reuse the establish-time passphrase on a fresh keystore: no second prompt.
+      passphrase: freshlyEstablished ? init.establishedPassphrase : void 0
+    });
+    return { unlocked: true, session: { expiresAt: written.expiresAt, ttlSeconds: written.ttlSeconds } };
+  } catch (error) {
+    const type = error.type;
+    if (!freshlyEstablished && !process.stdin.isTTY && type === "PASSPHRASE_REQUIRED_ERROR") {
+      if (!g.quiet) {
+        process.stderr.write(
+          'note: no passphrase source and no terminal; skipped caching the session. Run "btcr2 keystore unlock" later to cache it.\n'
+        );
+      }
+      return { unlocked: false };
+    }
+    throw error;
+  }
+}
+function printNextSteps(init, unlocked, session, doctor) {
+  const lines = [`btcr2 home ready at ${init.home} on ${init.network}.`];
+  if (unlocked && session) {
+    lines.push(`Session cached until ${new Date(session.expiresAt).toISOString()}; signing will not re-prompt until it expires.`);
+  }
+  if (init.protection === "dev") {
+    lines.push("Dev keystore: keys are stored in plaintext; mainnet operations are refused.");
+  }
+  if (doctor && doctor.checks.some((c) => !c.ok)) {
+    lines.push('Warning: one or more endpoints were unreachable (see the doctor report). Re-run "btcr2 config doctor" for detail.');
+  }
+  lines.push("Next: btcr2 key generate --name demo --set-active");
+  const faucet = (0, import_api2.faucetUrl)(init.network);
+  if (faucet) lines.push(`Faucet (fund your beacon after "btcr2 create"): ${faucet}`);
+  process.stderr.write(`${lines.join("\n")}
+`);
+}
 
 // src/commands/create.ts
 var import_utils4 = require("@noble/hashes/utils.js");
 
+// src/hints.ts
+var import_api3 = require("@did-btcr2/api");
+var import_method2 = require("@did-btcr2/method");
+function printCreateFundingHint(g, network, did) {
+  if (g.quiet || g.output === "json") return;
+  const faucet = (0, import_api3.faucetUrl)(network);
+  if (!faucet) return;
+  let beaconAddress;
+  try {
+    const { serviceEndpoint } = import_method2.BeaconUtils.createBeaconService(did, "p2wpkh", "SingletonBeacon");
+    beaconAddress = serviceEndpoint.replace(/^bitcoin:/, "");
+  } catch {
+    return;
+  }
+  const explorer = (0, import_api3.explorerAddressUrl)(network, beaconAddress);
+  const lines = [
+    "Fund the initial beacon to anchor updates:",
+    `  Beacon:   ${beaconAddress}`,
+    `  Faucet:   ${faucet}`
+  ];
+  if (explorer) lines.push(`  Explorer: ${explorer}`);
+  process.stderr.write(`${lines.join("\n")}
+`);
+}
+function printWatchHint(g, network, txid) {
+  if (g.quiet || g.output === "json") return;
+  const url = (0, import_api3.explorerTxUrl)(network, txid);
+  if (url) process.stderr.write(`Watch: ${url}
+`);
+}
+
 // src/keystore/resolve-key-ref.ts
 function fingerprintOf(id) {
   return /^urn:kms:secp256k1:([0-9a-f]{32})$/.exec(id)?.[1];
@@ -1825,6 +2201,7 @@ function registerCreateCommand(program, factory, keystoreFactory, globals) {
       const genesisBytes = parseGenesisBytes(options.bytes, "k");
       const did2 = factory().createDid("deterministic", genesisBytes, { network });
       print({ action: "create", data: did2 });
+      printCreateFundingHint(g, network, did2);
       return;
     }
     if (signingKey) {
@@ -1836,6 +2213,7 @@ function registerCreateCommand(program, factory, keystoreFactory, globals) {
         { action: "create", data: did2, keyId: keyId2, publicKey: (0, import_utils4.bytesToHex)(publicKey2) },
         `Using stored key ${keyId2}.`
       );
+      printCreateFundingHint(g, network, did2);
       return;
     }
     assertKeystoreAllowedForNetwork(network, overrides);
@@ -1846,6 +2224,7 @@ function registerCreateCommand(program, factory, keystoreFactory, globals) {
       { action: "create", data: did, keyId, publicKey },
       `Generated and stored key ${keyId} (now the active key).`
     );
+    printCreateFundingHint(g, network, did);
   });
 }
 function overridesFromGlobals(g) {
@@ -1891,7 +2270,7 @@ function parseGenesisBytes(hex, type) {
 }
 
 // src/commands/resolve.ts
-var import_api2 = require("@did-btcr2/api");
+var import_api4 = require("@did-btcr2/api");
 var import_promises = require("fs/promises");
 function registerResolveCommand(program, factory, globals) {
   program.command("resolve").alias("read").description("Resolve the DID document of the identifier.").requiredOption("-i, --identifier <identifier>", "did:btcr2 identifier").option("-r, --resolution-options <json>", "JSON string containing resolution options").option("-p, --resolution-options-path <path>", "Path to a JSON file containing resolution options").action(async (options) => {
@@ -1904,7 +2283,7 @@ function registerResolveCommand(program, factory, globals) {
   });
 }
 async function validateResolveOptions(options) {
-  import_api2.Identifier.decode(options.identifier);
+  import_api4.Identifier.decode(options.identifier);
   let resolutionOptions = void 0;
   if (options.resolutionOptions) {
     try {
@@ -2006,6 +2385,7 @@ function registerUpdateCommand(program, factory, globals) {
       ...broadcastOptions ? { broadcastOptions } : {}
     });
     console.log(formatResult({ action: "update", data }, globals()));
+    printWatchHint(globals(), network, data.txid);
   });
 }
 function parsePublishToCasMode(value) {
@@ -2104,6 +2484,7 @@ function registerDeactivateCommand(program, factory, globals) {
       ...broadcastOptions ? { broadcastOptions } : {}
     });
     console.log(formatResult({ action: "deactivate", data }, globals()));
+    printWatchHint(globals(), network, data.txid);
   });
 }
 function parsePublishToCasMode2(value) {
@@ -2133,7 +2514,7 @@ function parseJsonArg2(flagName) {
 // src/commands/key.ts
 var import_keypair = require("@did-btcr2/keypair");
 var import_utils5 = require("@noble/hashes/utils.js");
-var import_node_fs8 = require("fs");
+var import_node_fs9 = require("fs");
 function registerKeyCommand(program, factory, globals) {
   const key = program.command("key").description("Manage keypairs in the encrypted keystore.");
   const print = (result) => console.log(formatResult(result, globals()));
@@ -2231,7 +2612,7 @@ function parseHex(hex, expectedBytes, label) {
 function readHexFile(path, expectedBytes, label) {
   let content;
   try {
-    content = (0, import_node_fs8.readFileSync)(path, "utf-8");
+    content = (0, import_node_fs9.readFileSync)(path, "utf-8");
   } catch {
     throw new CLIError(`Cannot read ${label} at ${path}.`, "INVALID_ARGUMENT_ERROR", { label, path });
   }
@@ -2240,7 +2621,7 @@ function readHexFile(path, expectedBytes, label) {
 function writeSecretFile(path, contents) {
   let fd;
   try {
-    fd = (0, import_node_fs8.openSync)(path, "wx", 384);
+    fd = (0, import_node_fs9.openSync)(path, "wx", 384);
   } catch (error) {
     if (error.code === "EEXIST") {
       throw new CLIError(`Refusing to overwrite existing file ${path}. Choose a new --out path.`, "INVALID_ARGUMENT_ERROR", { path });
@@ -2248,152 +2629,10 @@ function writeSecretFile(path, contents) {
     throw error;
   }
   try {
-    (0, import_node_fs8.writeFileSync)(fd, contents);
+    (0, import_node_fs9.writeFileSync)(fd, contents);
   } finally {
-    (0, import_node_fs8.closeSync)(fd);
-  }
-}
-
-// src/commands/keystore.ts
-var import_node_fs9 = require("fs");
-function registerKeystoreCommand(program, globals) {
-  const keystore = program.command("keystore").description("Establish, inspect, re-key, and unlock the keystore.");
-  const print = (result) => console.log(formatResult(result, globals()));
-  keystore.command("init").description("Establish the keystore (encrypted by default). Prompts for a passphrase and confirms it.").option("--dev", "Create an UNENCRYPTED dev keystore: plaintext keys, no passphrase. Testnet only; mainnet operations are refused.", false).option("--force", "Re-establish even if a keystore already exists (discards its keys).", false).action((options) => {
-    const g = globals();
-    const path = resolveKeystorePath(g);
-    if ((0, import_node_fs9.existsSync)(path) && !options.force) {
-      throw new CLIError(
-        `A keystore already exists at ${path}. Use --force to re-establish it (this discards its keys).`,
-        "INVALID_ARGUMENT_ERROR",
-        { path }
-      );
-    }
-    if ((0, import_node_fs9.existsSync)(path) && options.force && !g.quiet) {
-      const { keyCount } = keystoreSummary(path);
-      if (keyCount > 0) {
-        process.stderr.write(
-          `warning: re-establishing the keystore at ${path} permanently discards its ${keyCount} existing key(s).
-`
-        );
-      }
-    }
-    if (options.dev && !g.quiet) {
-      process.stderr.write(
-        "warning: creating an UNENCRYPTED dev keystore. Keys are stored in plaintext. Use it only for disposable testnet material; mainnet operations will be refused.\n"
-      );
-    }
-    initKeystore(path, {
-      protection: options.dev ? "none" : "passphrase",
-      getPassphrase: (opts) => acquirePassphrase({ passphraseFile: g.passphraseFile, confirm: opts?.confirm, prompt: "New keystore passphrase: " })
-    });
-    clearSession(defaultSessionPath(g));
-    print({ action: "keystore-init", data: { path, protection: options.dev ? "dev" : "encrypted" } });
-  });
-  keystore.command("status").description("Show the keystore path, protection mode, key count, and session state. Never decrypts or prompts.").action(() => {
-    const g = globals();
-    const path = resolveKeystorePath(g, { lenient: true });
-    const summary = keystoreSummary(path);
-    const session = readSessionStatus(defaultSessionPath(g), path, keystoreVerifierId(path));
-    if (summary.protection === "dev" && !g.quiet && g.output !== "json") {
-      process.stderr.write("warning: this is an UNENCRYPTED dev keystore; keys are stored in plaintext.\n");
-    }
-    print({ action: "keystore-status", data: { path, ...summary, session } });
-  });
-  keystore.command("change-passphrase").alias("passwd").description("Change the keystore passphrase, re-sealing every key under the new one. Encrypted keystores only.").action(() => {
-    const g = globals();
-    const path = resolveKeystorePath(g);
-    const summary = keystoreSummary(path);
-    if (summary.protection === "absent") {
-      throw new CLIError(`No keystore at ${path}. Run "btcr2 keystore init" first.`, "INVALID_ARGUMENT_ERROR", { path });
-    }
-    if (summary.protection === "dev") {
-      throw new CLIError(
-        `The keystore at ${path} is an unencrypted dev keystore; there is no passphrase to change.`,
-        "INVALID_ARGUMENT_ERROR",
-        { path }
-      );
-    }
-    const oldPassphrase = acquirePassphrase({ passphraseFile: g.passphraseFile, prompt: "Current keystore passphrase: " });
-    const newPassphrase = acquirePassphrase({ forcePrompt: true, confirm: true, prompt: "New keystore passphrase: " });
-    const rekeyed = changeKeystorePassphrase(path, oldPassphrase, newPassphrase);
-    clearSession(defaultSessionPath(g));
-    print({ action: "keystore-change-passphrase", data: { path, rekeyed } });
-  });
-  keystore.command("unlock").description("Cache the keystore passphrase for a session so later commands do not re-prompt (ADR 081).").option("--ttl <duration>", `Session lifetime: bare seconds or an s/m/h suffix (default 1h, max 24h). Also $${ENV_KEYSTORE_TTL}.`).option("--allow-mainnet", "Permit unlocking when the active network is mainnet (bitcoin); this suspends per-use passphrase auth for the session.", false).action((options) => {
-    const g = globals();
-    const path = resolveKeystorePath(g);
-    const summary = keystoreSummary(path);
-    if (summary.protection === "absent") {
-      throw new CLIError(`No keystore at ${path}. Run "btcr2 init" or "btcr2 keystore init" first.`, "INVALID_ARGUMENT_ERROR", { path });
-    }
-    if (summary.protection === "dev") {
-      throw new CLIError(
-        `The keystore at ${path} is an unencrypted dev keystore; it has no passphrase to cache, so no unlock is needed.`,
-        "INVALID_ARGUMENT_ERROR",
-        { path }
-      );
-    }
-    if (!summary.established) {
-      throw new CLIError(
-        `The keystore at ${path} has no passphrase established yet. Establish one with "btcr2 keystore init" or the first "btcr2 key generate".`,
-        "INVALID_ARGUMENT_ERROR",
-        { path }
-      );
-    }
-    if (!options.allowMainnet && resolveDefaultNetwork(g) === "bitcoin") {
-      throw new CLIError(
-        `Refusing to unlock for a mainnet (bitcoin) context: caching the passphrase suspends per-use authentication for the session. Pass --allow-mainnet to override, or keep signing mainnet updates with a per-use passphrase prompt.`,
-        "MAINNET_UNLOCK_REFUSED_ERROR",
-        { path }
-      );
-    }
-    const ttlMs = resolveSessionTtl(options.ttl);
-    const passphrase = acquirePassphrase({ passphraseFile: g.passphraseFile, prompt: "Keystore passphrase: " });
-    if (!verifyKeystorePassphrase(path, passphrase)) {
-      throw new CLIError(`Incorrect passphrase for the keystore at ${path}; no session was created.`, "DECRYPT_ERROR", { path });
-    }
-    const verifierId = keystoreVerifierId(path);
-    if (!verifierId) {
-      throw new CLIError(`The keystore at ${path} has no verifier to bind a session to.`, "INVALID_ARGUMENT_ERROR", { path });
-    }
-    const session = writeSession(defaultSessionPath(g), {
-      keystorePath: path,
-      verifierId,
-      passphrase,
-      ttlMs,
-      allowMainnet: !!options.allowMainnet
-    });
-    print({ action: "keystore-unlock", data: { keystore: path, expiresAt: session.expiresAt, ttlSeconds: session.ttlSeconds } });
-  });
-  keystore.command("lock").description("Revoke the cached session so later commands prompt for the passphrase again (ADR 081).").action(() => {
-    const g = globals();
-    const sessionPath = defaultSessionPath(g);
-    const cleared = clearSession(sessionPath);
-    print({ action: "keystore-lock", data: { path: sessionPath, cleared } });
-  });
-}
-function resolveSessionTtl(flag) {
-  const fromFlag = blankToUndef(flag);
-  const raw = fromFlag ?? blankToUndef(process.env[ENV_KEYSTORE_TTL]);
-  if (raw === void 0) return DEFAULT_SESSION_TTL_MS;
-  const source = fromFlag !== void 0 ? "--ttl" : `$${ENV_KEYSTORE_TTL}`;
-  const ms = parseTtlToMs(raw);
-  if (ms === void 0 || ms <= 0) {
-    throw new CLIError(
-      `Invalid ${source} "${raw}": expected seconds or a value with an s/m/h suffix, e.g. 3600, 45m, or 2h.`,
-      "INVALID_ARGUMENT_ERROR",
-      { value: raw, source }
-    );
-  }
-  if (ms > MAX_SESSION_TTL_MS) {
-    throw new CLIError(
-      `${source} "${raw}" exceeds the 24h maximum for a cached passphrase.`,
-      "INVALID_ARGUMENT_ERROR",
-      { value: raw, source }
-    );
+    (0, import_node_fs9.closeSync)(fd);
   }
-  return ms;
 }
 
 // src/commands/config.ts
@@ -2749,6 +2988,7 @@ var DidBtcr2Cli = class {
       opts.output = resolveOutputFormat({ output: opts.output, config: opts.config, home: opts.home });
     });
     registerInitCommand(this.program, globals);
+    registerQuickstartCommand(this.program, globals);
     registerCreateCommand(this.program, factory, keystoreFactory, globals);
     registerResolveCommand(this.program, factory, globals);
     registerUpdateCommand(this.program, keystoreFactory, globals);
@@ -2805,6 +3045,7 @@ function handleError(error, verbose) {
   SUPPORTED_NETWORKS,
   VERSION,
   assertKeystoreAllowedForNetwork,
+  assertSupportedNetwork,
   blankToUndef,
   defaultApiFactory,
   defaultConfigPath,
@@ -2815,9 +3056,11 @@ function handleError(error, verbose) {
   keystoreApiFactory,
   parseConfigFileRaw,
   parseHeaderList,
+  persistDefaultNetwork,
   profileNetworkMismatch,
   profileToOverrides,
   readConfigFile,
+  readConfiguredDefaultNetwork,
   readEnvOverrides,
   redactSecrets,
   registerCompletionCommand,
@@ -2828,6 +3071,7 @@ function handleError(error, verbose) {
   registerKeyCommand,
   registerKeystoreCommand,
   registerProfileCommand,
+  registerQuickstartCommand,
   registerResolveCommand,
   registerUpdateCommand,
   resolveActiveProfile,