@did-btcr2/cli 0.17.0 → 0.18.0

package/src/commands/keystore.ts

@@ -17,11 +17,12 @@ import {
   MAX_SESSION_TTL_MS,
   parseTtlToMs,
   readSessionStatus,
+  type SessionFile,
   writeSession,
 } from '../keystore/session.js';
 import { formatResult } from '../output.js';
 import { defaultSessionPath } from '../paths.js';
-import { blankToUndef, type CommandResult, type GlobalOptions } from '../types.js';
+import { blankToUndef, type CommandResult, type GlobalOptions, type NetworkOption } from '../types.js';
 
 /**
  * Registers the `keystore` command group: establish, inspect, and re-key the
@@ -129,62 +130,17 @@ export function registerKeystoreCommand(program: Command, globals: () => GlobalO
     .action((options: { ttl?: string; allowMainnet?: boolean }) => {
       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 },
-        );
-      }
-      // An unlocked encrypted keystore signs prompt-free for the whole TTL,
-      // silently removing per-use passphrase auth. Two guards, both keyed to
-      // --allow-mainnet (ADR 081): this early refusal when the *configured* default
-      // network is mainnet (a clear signal before caching anything), plus the
-      // authoritative one at consumption, where the session records `allowMainnet`
-      // (below) and a `bitcoin` operation, whose network is derived from the DID
-      // rather than the config, is withheld from a session that lacks it. The
-      // active network defaults to a testnet, so this early refusal never fires
-      // for the demo.
-      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);
-      // Acquire the passphrase directly (env / file / prompt) with NO session
-      // consultation and NO confirm, verify it against the keystore verifier, and
-      // only then cache it. A wrong passphrase writes no session file.
-      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) {
-        // An established keystore always carries a verifier; defensive guard.
-        throw new CLIError(`The keystore at ${path} has no verifier to bind a session to.`, 'INVALID_ARGUMENT_ERROR', { path });
-      }
-      const session = writeSession(defaultSessionPath(g), {
+      // The op network for the mainnet gate is the configured default here; the
+      // session records `allowMainnet` and the authoritative check happens at
+      // consumption, where a `bitcoin` operation (network derived from the DID) is
+      // withheld from a session that lacks it.
+      const session = unlockSession({
+        g,
         keystorePath : path,
-        verifierId,
-        passphrase,
-        ttlMs,
+        network      : resolveDefaultNetwork(g),
         allowMainnet : !!options.allowMainnet,
+        ttlMs,
       });
       print({ action: 'keystore-unlock', data: { keystore: path, expiresAt: session.expiresAt, ttlSeconds: session.ttlSeconds } });
     });
@@ -202,13 +158,97 @@ export function registerKeystoreCommand(program: Command, globals: () => GlobalO
     });
 }
 
+/** Input for the shared {@link unlockSession} step. */
+export interface UnlockSessionInput {
+  g            : GlobalOptions;
+  /** The resolved keystore path to unlock. */
+  keystorePath : string;
+  /** The operation network for the mainnet gate, passed explicitly (never re-derived). */
+  network      : NetworkOption;
+  /** Whether a mainnet (bitcoin) unlock is permitted (`--allow-mainnet`). */
+  allowMainnet : boolean;
+  /** Session lifetime in milliseconds (already resolved via {@link resolveSessionTtl}). */
+  ttlMs        : number;
+  /**
+   * A pre-acquired passphrase to reuse instead of prompting (the establish-time
+   * passphrase from `quickstart --unlock` on a fresh keystore). Still verified
+   * against the keystore verifier before caching.
+   */
+  passphrase?  : string;
+}
+
+/**
+ * The shared unlock step behind `keystore unlock` and `quickstart --unlock` (ADR
+ * 081/083): validate the keystore, enforce the mainnet gate against the passed
+ * `network`, acquire (or reuse) and verify the passphrase, and write the session.
+ * Refuses an absent, dev, or unestablished keystore. A wrong passphrase writes no
+ * session file. Returns the written {@link SessionFile}. The op network is passed
+ * in rather than re-derived so the mainnet gate is order-independent even when a
+ * caller has just written `defaults.network`.
+ */
+export function unlockSession(input: UnlockSessionInput): SessionFile {
+  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 },
+    );
+  }
+  // An unlocked encrypted keystore signs prompt-free for the whole TTL, silently
+  // removing per-use passphrase auth. Refuse a bitcoin context unless allowed; the
+  // authoritative per-use check still happens at consumption from the session's
+  // recorded `allowMainnet` (ADR 081).
+  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 },
+    );
+  }
+  // Acquire the passphrase directly (env / file / prompt) with NO session
+  // consultation and NO confirm, or reuse a caller-provided one, then verify it
+  // against the keystore verifier before caching. A wrong passphrase writes no
+  // session file.
+  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) {
+    // An established keystore always carries a verifier; defensive guard.
+    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,
+  });
+}
+
 /**
  * Resolves the session TTL in milliseconds from the `--ttl` flag, then
  * `$BTCR2_KEYSTORE_TTL`, then the one-hour default. Rejects a non-positive,
  * malformed, or over-24h value with a {@link CLIError} that names the actual
  * source (the flag or the env var) so the operator fixes the right input.
  */
-function resolveSessionTtl(flag?: string): number {
+export function resolveSessionTtl(flag?: string): number {
   const fromFlag = blankToUndef(flag);
   const raw = fromFlag ?? blankToUndef(process.env[ENV_KEYSTORE_TTL]);
   if (raw === undefined) return DEFAULT_SESSION_TTL_MS;

package/src/commands/quickstart.ts

@@ -0,0 +1,209 @@
+import { faucetUrl } from '@did-btcr2/api';
+import type { Command } from 'commander';
+import {
+  assertSupportedNetwork,
+  readConfiguredDefaultNetwork,
+  runDoctor,
+  type DoctorReport,
+} from '../config.js';
+import { CLIError } from '../error.js';
+import { keystoreVerifierId } from '../keystore/file-key-store.js';
+import { ENV_KEYSTORE_TTL, readSessionStatus } from '../keystore/session.js';
+import { formatResult } from '../output.js';
+import { defaultSessionPath } from '../paths.js';
+import type { CommandResult, GlobalOptions, NetworkOption } from '../types.js';
+import { runInit, type RunInitResult } from './init.js';
+import { resolveSessionTtl, unlockSession } from './keystore.js';
+
+/** The opinionated default network for `quickstart`: zero local infra, a free faucet, 30s blocks. */
+const QUICKSTART_DEFAULT_NETWORK: NetworkOption = 'mutinynet';
+
+/** The session sub-object reported in the quickstart envelope. */
+type SessionReport = { expiresAt: number; ttlSeconds: number };
+
+/**
+ * Registers the top-level `btcr2 quickstart` (ADR 083): a one-command onboarding
+ * that COMPOSES the existing primitives - the {@link runInit} scaffold, the
+ * network record, the optional {@link unlockSession} cache, and the advisory
+ * {@link runDoctor} probe - into a single step for a workshop follow-along.
+ * Reimplements nothing; the ADR 080/081 keystore and session guarantees hold by
+ * construction.
+ */
+export function registerQuickstartCommand(program: Command, globals: () => GlobalOptions): void {
+  const print = (result: CommandResult): void => 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: {
+      network?      : string;
+      dev?          : boolean;
+      unlock?       : boolean;
+      ttl?          : string;
+      doctor        : boolean; // commander sets false for --no-doctor, true otherwise
+      allowMainnet? : boolean;
+      force?        : boolean;
+    }) => {
+      const g = globals();
+      const explicit = options.network ? assertSupportedNetwork(options.network) : undefined;
+      // The network quickstart will operate on, computed BEFORE any write so the
+      // mainnet guard sees the real target: explicit -n, else an existing
+      // defaults.network, else the mutinynet default. runInit resolves to the
+      // same value.
+      const network = explicit ?? readConfiguredDefaultNetwork(g) ?? QUICKSTART_DEFAULT_NETWORK;
+
+      // Mainnet is guarded before any files are written (ADR 083). A dev keystore
+      // never operates on mainnet; an encrypted mainnet setup needs the explicit
+      // opt-in that also gates the session-unlock mainnet suspension.
+      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 },
+          );
+        }
+      }
+
+      // 1-2. Scaffold and record the network. An explicit -n always writes; a
+      // merely-defaulted mutinynet writes only when defaults.network is unset.
+      const init = runInit(g, {
+        dev                          : options.dev,
+        force                        : options.force,
+        network                      : explicit,
+        fallbackNetwork              : explicit ? undefined : QUICKSTART_DEFAULT_NETWORK,
+        captureEstablishedPassphrase : !!options.unlock && !options.dev,
+      });
+
+      // 3. Optionally cache the session (ADR 081 opt-in; never on a dev keystore).
+      let unlocked = false;
+      let session: SessionReport | undefined;
+      if (options.unlock && !options.dev) {
+        const outcome = cacheSession(g, init, options.ttl, !!options.allowMainnet);
+        unlocked = outcome.unlocked;
+        session = outcome.session;
+      }
+
+      // 4. Advisory endpoint probe (on by default; a failed probe warns, exit 0).
+      let doctor: DoctorReport | undefined;
+      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') {
+        printNextSteps(init, unlocked, session, doctor);
+      }
+    });
+}
+
+/**
+ * Caches the session for `quickstart --unlock`. On a fresh keystore, reuses the
+ * establish-time confirmed passphrase (no second prompt). On an existing keystore
+ * with a live matching session, skips (idempotent re-run). Otherwise acquires and
+ * verifies the passphrase. In a non-interactive context with no passphrase source
+ * on an existing keystore, the step is a non-fatal skip (warn, `unlocked: false`),
+ * so `quickstart` still exits 0 (ADR 083).
+ */
+function cacheSession(
+  g            : GlobalOptions,
+  init         : RunInitResult,
+  ttlFlag      : string | undefined,
+  allowMainnet : boolean,
+): { unlocked: boolean; session?: SessionReport } {
+  const ttlMs = resolveSessionTtl(ttlFlag);
+  const freshlyEstablished = init.created.includes('keystore');
+
+  // Existing encrypted keystore already unlocked: report it and skip re-writing.
+  if (!freshlyEstablished) {
+    const status = readSessionStatus(defaultSessionPath(g), init.keystore, keystoreVerifierId(init.keystore));
+    if (status.active && status.expiresAt !== undefined) {
+      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 : undefined,
+    });
+    return { unlocked: true, session: { expiresAt: written.expiresAt, ttlSeconds: written.ttlSeconds } };
+  } catch (error) {
+    // On an EXISTING keystore with no passphrase source and no terminal, caching
+    // is a non-fatal skip: the scaffold already succeeded (ADR 083). A fresh
+    // keystore cannot reach here (its passphrase was just captured), and an
+    // interactive wrong passphrase still propagates.
+    const type = (error as { type?: string }).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;
+  }
+}
+
+/** Prints the text-mode next-step hints after quickstart (ADR 082/083). */
+function printNextSteps(
+  init     : RunInitResult,
+  unlocked : boolean,
+  session  : SessionReport | undefined,
+  doctor   : DoctorReport | undefined,
+): void {
+  const lines: string[] = [`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 = faucetUrl(init.network);
+  if (faucet) lines.push(`Faucet (fund your beacon after "btcr2 create"): ${faucet}`);
+  process.stderr.write(`${lines.join('\n')}\n`);
+}

package/src/commands/update.ts

@@ -3,6 +3,7 @@ import { KeyManagerSigner } from '@did-btcr2/key-manager';
 import type { Command } from 'commander';
 import { assertKeystoreAllowedForNetwork, deriveNetwork, resolveBroadcastOptions, resolveSigningKeyRef, type ApiFactory } from '../config.js';
 import { CLIError } from '../error.js';
+import { printWatchHint } from '../hints.js';
 import { resolveKeyRef } from '../keystore/resolve-key-ref.js';
 import { formatResult } from '../output.js';
 import type { GlobalOptions, UpdateCommandOptions } from '../types.js';
@@ -117,6 +118,7 @@ export function registerUpdateCommand(
         ...(broadcastOptions ? { broadcastOptions } : {}),
       });
       console.log(formatResult({ action: 'update', data }, globals()));
+      printWatchHint(globals(), network, data.txid);
     });
 }
 

package/src/config.ts

@@ -398,6 +398,81 @@ export function resolveDefaultNetwork(overrides?: ConnectionOverrides): NetworkO
   return 'regtest';
 }
 
+/**
+ * The network recorded at `defaults.network` in the config file, validated, or
+ * `undefined` when the file is absent, malformed, or the value is unset/unknown.
+ * Unlike {@link resolveDefaultNetwork} this consults ONLY the raw
+ * `defaults.network` (no profile fallback, no regtest default), so `quickstart`
+ * can distinguish "the operator set a default" from "there is none yet" before
+ * it writes (ADR 083). Never throws: a malformed config is surfaced loudly by
+ * the write path, so this pre-write read stays quiet.
+ */
+export function readConfiguredDefaultNetwork(overrides?: ConnectionOverrides): NetworkOption | undefined {
+  const configPath = overrides?.config ?? defaultConfigPath(overrides);
+  let raw: Record<string, unknown> | undefined;
+  try {
+    raw = parseConfigFileRaw(configPath);
+  } catch {
+    return undefined;
+  }
+  const value = raw ? getConfigPath(raw, 'defaults.network') : undefined;
+  return typeof value === 'string' && SUPPORTED_NETWORKS.includes(value as NetworkOption)
+    ? value as NetworkOption
+    : undefined;
+}
+
+/**
+ * Persists `defaults.network` idempotently and returns the resolved network,
+ * the shared network-recording step behind `btcr2 init -n` and `btcr2 quickstart`
+ * (ADR 083). Writes when `explicit` (an explicit `-n`) is given, or when a
+ * `fallback` is given and the raw config has no `defaults.network` yet. Keyed on
+ * the **raw** file value (not {@link resolveDefaultNetwork}, which never returns
+ * undefined), so a defaulted re-run never clobbers a network the operator set
+ * earlier. When neither condition writes, the existing default is returned
+ * unchanged. Assumes `configPath` names a parseable config (the caller has just
+ * scaffolded one, or an existing one that a malformed-JSON read surfaces loudly).
+ */
+export function persistDefaultNetwork(
+  configPath : string,
+  opts       : { explicit?: NetworkOption; fallback?: NetworkOption; overrides?: ConnectionOverrides },
+): { network: NetworkOption; wrote: boolean } {
+  const raw = parseConfigFileRaw(configPath);
+  const rawValue = raw ? getConfigPath(raw, 'defaults.network') : undefined;
+  const rawNetwork = typeof rawValue === 'string' && SUPPORTED_NETWORKS.includes(rawValue as NetworkOption)
+    ? rawValue as NetworkOption
+    : undefined;
+
+  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 };
+}
+
+/**
+ * Validates an explicit network string against {@link SUPPORTED_NETWORKS},
+ * returning it typed as a {@link NetworkOption} or throwing a {@link CLIError}.
+ * Shared by the `-n/--network` flags on `init` and `quickstart` (ADR 083).
+ */
+export function assertSupportedNetwork(value: string): NetworkOption {
+  if (!SUPPORTED_NETWORKS.includes(value as NetworkOption)) {
+    throw new CLIError(
+      `Invalid network "${value}". Must be one of ${SUPPORTED_NETWORKS.join(', ')}.`,
+      'INVALID_ARGUMENT_ERROR',
+      { network: value },
+    );
+  }
+  return value as NetworkOption;
+}
+
 /**
  * Reports a coherence conflict between the network a `create` run is about to
  * encode and the network the active profile declares, so the CLI can warn

package/src/hints.ts

@@ -0,0 +1,51 @@
+import { explorerAddressUrl, explorerTxUrl, faucetUrl } from '@did-btcr2/api';
+import { BeaconUtils } from '@did-btcr2/method';
+import type { GlobalOptions, NetworkOption } from './types.js';
+
+/**
+ * Text-mode stderr hints derived from the per-network presets (ADR 082). All of
+ * these are suppressed under `--quiet` and `--output json` so machine output is
+ * never touched, and they never throw: a presentation hint must never break the
+ * command that produced the real result.
+ */
+
+/**
+ * Prints a funding hint after a KEY `create` on a network with a public faucet:
+ * the derived initial P2WPKH beacon address next to the faucet and explorer
+ * links the operator would otherwise hand-copy. A no-op on a network without a
+ * faucet (regtest/mainnet), which also keeps mainnet from showing a fund-me
+ * affordance. The beacon address is derived from the DID string alone via
+ * {@link BeaconUtils.createBeaconService}, so it matches the resolver's
+ * `#initialP2WPKH` service rather than a divergent re-derivation.
+ */
+export function printCreateFundingHint(g: GlobalOptions, network: NetworkOption, did: string): void {
+  if (g.quiet || g.output === 'json') return;
+  const faucet = faucetUrl(network);
+  if (!faucet) return;
+  let beaconAddress: string;
+  try {
+    const { serviceEndpoint } = BeaconUtils.createBeaconService(did, 'p2wpkh', 'SingletonBeacon');
+    beaconAddress = serviceEndpoint.replace(/^bitcoin:/, '');
+  } catch {
+    return;
+  }
+  const explorer = 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')}\n`);
+}
+
+/**
+ * Prints a watch link after an `update`/`deactivate` broadcast: the
+ * block-explorer URL for the signal txid. A no-op on a network without an
+ * explorer (regtest).
+ */
+export function printWatchHint(g: GlobalOptions, network: NetworkOption, txid: string): void {
+  if (g.quiet || g.output === 'json') return;
+  const url = explorerTxUrl(network, txid);
+  if (url) process.stderr.write(`Watch: ${url}\n`);
+}

package/src/types.ts

@@ -56,7 +56,18 @@ export type CommandResult =
   | { action: 'key-export'; data: { keyId: string; publicKey?: string; secretWrittenTo?: string } }
   | { action: 'key-delete'; data: { keyId: string; deleted: true } }
   | { action: 'key-use'; data: { keyId: string; active: true } }
-  | { action: 'init'; data: { home: string; config: string; keystore: string; created: string[]; protection: KeystoreProtectionLabel } }
+  | { action: 'init'; data: { home: string; config: string; keystore: string; network: NetworkOption; created: string[]; protection: KeystoreProtectionLabel } }
+  | { action: 'quickstart'; data: {
+      home       : string;
+      config     : string;
+      keystore   : string;
+      network    : NetworkOption;
+      created    : string[];
+      protection : KeystoreProtectionLabel;
+      unlocked   : boolean;
+      session?   : { expiresAt: number; ttlSeconds: number };
+      doctor?    : DoctorReport;
+    } }
   | { action: 'config-init'; data: { path: string } }
   | { action: 'config-get'; data: unknown }
   | { action: 'config-set'; data: { path: string } }