@did-btcr2/cli 0.22.0 → 0.23.1

package/dist/cjs/index.js

@@ -51,6 +51,7 @@ __export(index_exports, {
   registerConfigCommand: () => registerConfigCommand,
   registerCreateCommand: () => registerCreateCommand,
   registerDeactivateCommand: () => registerDeactivateCommand,
+  registerGenesisCommand: () => registerGenesisCommand,
   registerIdentifierCommand: () => registerIdentifierCommand,
   registerInitCommand: () => registerInitCommand,
   registerKeyCommand: () => registerKeyCommand,
@@ -2097,13 +2098,35 @@ function printNextSteps(init, unlocked, session, doctor) {
 // src/commands/create.ts
 var import_utils4 = require("@noble/hashes/utils.js");
 
+// src/genesis-document-file.ts
+var import_promises = require("fs/promises");
+var GENESIS_DOCUMENT_HELP = "Path to the JSON genesis document of an external identifier (x). Fills sidecar.genesisDocument of the resolution options";
+async function readGenesisDocumentFile(path) {
+  let parsed;
+  try {
+    parsed = JSON.parse(await (0, import_promises.readFile)(path, "utf-8"));
+  } catch {
+    throw new CLIError(
+      "Invalid genesis document path. Must be a valid path to a JSON file.",
+      "INVALID_ARGUMENT_ERROR",
+      { genesisDocument: path }
+    );
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new CLIError(
+      "Invalid genesis document. The file must contain a JSON object.",
+      "INVALID_ARGUMENT_ERROR",
+      { genesisDocument: path }
+    );
+  }
+  return parsed;
+}
+
 // 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");
@@ -2111,6 +2134,12 @@ function printCreateFundingHint(g, network, did) {
   } catch {
     return;
   }
+  printBeaconFundingHint(g, network, beaconAddress);
+}
+function printBeaconFundingHint(g, network, beaconAddress) {
+  if (g.quiet || g.output === "json") return;
+  const faucet = (0, import_api3.faucetUrl)(network);
+  if (!faucet) return;
   const explorer = (0, import_api3.explorerAddressUrl)(network, beaconAddress);
   const lines = [
     "Fund the initial beacon to anchor updates:",
@@ -2166,33 +2195,59 @@ function resolveKeyRef(kms, ref) {
   throw new CLIError(`No key matches reference "${ref}".`, "KEY_NOT_FOUND_ERROR", { ref });
 }
 
+// src/network-option.ts
+var NETWORK_OPTION_HELP = "Identifier bitcoin network <bitcoin|testnet3|testnet4|signet|mutinynet|regtest> (default: config defaults.network, else regtest)";
+function overridesFromGlobals(g) {
+  return {
+    home: g.home,
+    config: g.config,
+    profile: g.profile,
+    keystore: g.keystore,
+    passphraseFile: g.passphraseFile
+  };
+}
+function resolveNetworkOption(explicit, overrides) {
+  if (!explicit) return resolveDefaultNetwork(overrides);
+  if (!SUPPORTED_NETWORKS.includes(explicit)) {
+    throw new CLIError(
+      'Invalid network. Must be one of "bitcoin", "testnet3", "testnet4", "signet", "mutinynet", or "regtest".',
+      "INVALID_ARGUMENT_ERROR",
+      { network: explicit }
+    );
+  }
+  return explicit;
+}
+function warnProfileNetworkMismatch(g, network, overrides) {
+  const mismatch = profileNetworkMismatch(network, overrides);
+  if (mismatch && !g.quiet) {
+    process.stderr.write(
+      `Warning: creating a "${network}" identifier while the active profile "${mismatch.profile}" declares network "${mismatch.declared}". The identifier's network and the profile's endpoints may not match.
+`
+    );
+  }
+}
+
 // src/commands/create.ts
 var EXPECTED_BYTES = {
   k: { length: 33, label: "secp256k1 compressed public key (33 bytes)" },
   x: { length: 32, label: "SHA-256 hash (32 bytes)" }
 };
 function registerCreateCommand(program, factory, keystoreFactory, globals) {
-  program.command("create").description("Create an identifier and initial DID document").option("-t, --type <type>", "Identifier type <k|x>", "k").option(
-    "-n, --network <network>",
-    "Identifier bitcoin network <bitcoin|testnet3|testnet4|signet|mutinynet|regtest> (default: config defaults.network, else regtest)"
-  ).option(
+  program.command("create").description("Create an identifier and initial DID document").option("-t, --type <type>", "Identifier type <k|x>", "k").option("-n, --network <network>", NETWORK_OPTION_HELP).option(
     "-b, --bytes <bytes>",
     "Genesis bytes as a hex string. For type=k, a 33-byte secp256k1 public key (omit to generate a key). For type=x, the 32-byte SHA-256 hash of a genesis document."
+  ).option(
+    "--document <path>",
+    'For type=x, the path of the JSON genesis document to hash (see "btcr2 genesis build"). Exclusive with --bytes.'
   ).action(async (options) => {
     const g = globals();
     if (options.type !== "k" && options.type !== "x") {
       throw new CLIError('Invalid type. Must be "k" or "x".', "INVALID_ARGUMENT_ERROR", options);
     }
     const overrides = overridesFromGlobals(g);
-    const network = resolveNetwork(options.network, overrides);
+    const network = resolveNetworkOption(options.network, overrides);
     const signingKey = g.signingKey;
-    const mismatch = profileNetworkMismatch(network, overrides);
-    if (mismatch && !g.quiet) {
-      process.stderr.write(
-        `Warning: creating a "${network}" identifier while the active profile "${mismatch.profile}" declares network "${mismatch.declared}". The identifier's network and the profile's endpoints may not match.
-`
-      );
-    }
+    warnProfileNetworkMismatch(g, network, overrides);
     const print = (result, note) => {
       console.log(formatResult(result, g));
       if (note && g.output !== "json") process.stderr.write(`${note}
@@ -2205,9 +2260,21 @@ function registerCreateCommand(program, factory, keystoreFactory, globals) {
           "INVALID_ARGUMENT_ERROR"
         );
       }
+      if (options.bytes !== void 0 && options.document !== void 0) {
+        throw new CLIError("Provide at most one of --bytes or --document.", "INVALID_ARGUMENT_ERROR");
+      }
+      if (options.document !== void 0) {
+        const genesisDocument = await readGenesisDocumentFile(options.document);
+        const api2 = factory();
+        const { did: did3, genesisBytes: genesisBytes2, didDocument } = api2.btcr2.createExternalFromDocument(genesisDocument, { network });
+        print({ action: "create", data: did3, genesisBytes: (0, import_utils4.bytesToHex)(genesisBytes2) });
+        const beacons = api2.btcr2.getBeacons(didDocument);
+        if (beacons.length > 0) printBeaconFundingHint(g, network, beacons[0].address);
+        return;
+      }
       if (options.bytes === void 0) {
         throw new CLIError(
-          "External identifiers (-t x) require --bytes <hex>, the 32-byte genesis document hash. Key generation is only available for -t k.",
+          "External identifiers (-t x) require --document <path>, the genesis document, or --bytes <hex>, its 32-byte hash. Key generation is only available for -t k.",
           "INVALID_ARGUMENT_ERROR"
         );
       }
@@ -2216,6 +2283,9 @@ function registerCreateCommand(program, factory, keystoreFactory, globals) {
       print({ action: "create", data: did2 });
       return;
     }
+    if (options.document !== void 0) {
+      throw new CLIError("--document applies only to external identifiers (-t x).", "INVALID_ARGUMENT_ERROR");
+    }
     if (options.bytes !== void 0 && signingKey) {
       throw new CLIError(
         "Provide at most one of --bytes or --signing-key.",
@@ -2252,26 +2322,6 @@ function registerCreateCommand(program, factory, keystoreFactory, globals) {
     printCreateFundingHint(g, network, did);
   });
 }
-function overridesFromGlobals(g) {
-  return {
-    home: g.home,
-    config: g.config,
-    profile: g.profile,
-    keystore: g.keystore,
-    passphraseFile: g.passphraseFile
-  };
-}
-function resolveNetwork(explicit, overrides) {
-  if (!explicit) return resolveDefaultNetwork(overrides);
-  if (!SUPPORTED_NETWORKS.includes(explicit)) {
-    throw new CLIError(
-      'Invalid network. Must be one of "bitcoin", "testnet3", "testnet4", "signet", "mutinynet", or "regtest".',
-      "INVALID_ARGUMENT_ERROR",
-      { network: explicit }
-    );
-  }
-  return explicit;
-}
 function parseGenesisBytes(hex, type) {
   const expected = EXPECTED_BYTES[type];
   let bytes;
@@ -2299,7 +2349,10 @@ var import_api5 = require("@did-btcr2/api");
 
 // src/resolution-options.ts
 var import_api4 = require("@did-btcr2/api");
-var import_promises = require("fs/promises");
+var import_promises2 = require("fs/promises");
+function hasResolutionFlags(flags) {
+  return flags.resolutionOptions !== void 0 || flags.resolutionOptionsPath !== void 0 || flags.minConf !== void 0 || flags.genesisDocument !== void 0;
+}
 var MIN_CONF_HELP = `Minimum block confirmations a beacon signal needs before resolution applies it (positive integer, default: ${import_api4.DEFAULT_MIN_CONF}). Overrides a minConf inside the JSON resolution options`;
 async function readResolutionOptions(flags) {
   let resolutionOptions;
@@ -2315,7 +2368,7 @@ async function readResolutionOptions(flags) {
     }
   } else if (flags.resolutionOptionsPath) {
     try {
-      const content = await (0, import_promises.readFile)(flags.resolutionOptionsPath, "utf-8");
+      const content = await (0, import_promises2.readFile)(flags.resolutionOptionsPath, "utf-8");
       resolutionOptions = JSON.parse(content);
     } catch {
       throw new CLIError(
@@ -2328,6 +2381,13 @@ async function readResolutionOptions(flags) {
   if (flags.minConf !== void 0) {
     resolutionOptions = { ...resolutionOptions ?? {}, minConf: flags.minConf };
   }
+  if (flags.genesisDocument !== void 0) {
+    const genesisDocument = await readGenesisDocumentFile(flags.genesisDocument);
+    resolutionOptions = {
+      ...resolutionOptions ?? {},
+      sidecar: { ...resolutionOptions?.sidecar ?? {}, genesisDocument }
+    };
+  }
   return resolutionOptions;
 }
 function parseMinConf(value) {
@@ -2343,7 +2403,7 @@ function parseMinConf(value) {
 
 // src/commands/resolve.ts
 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").option("--min-conf <n>", MIN_CONF_HELP, parseMinConf).action(async (options) => {
+  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").option("--min-conf <n>", MIN_CONF_HELP, parseMinConf).option("--genesis-document <path>", GENESIS_DOCUMENT_HELP).action(async (options) => {
     const parsed = await validateResolveOptions(options);
     const network = deriveNetwork(parsed.identifier);
     const api = factory(network, globals());
@@ -2353,13 +2413,24 @@ function registerResolveCommand(program, factory, globals) {
   });
 }
 async function validateResolveOptions(options) {
-  import_api5.Identifier.decode(options.identifier);
+  const components = import_api5.Identifier.decode(options.identifier);
+  assertGenesisDocumentApplies(options, components.hrp);
   const resolutionOptions = await readResolutionOptions(options);
   return { identifier: options.identifier, options: resolutionOptions };
 }
+function assertGenesisDocumentApplies(flags, hrp) {
+  if (flags.genesisDocument !== void 0 && hrp === "k") {
+    throw new CLIError(
+      "--genesis-document applies only to external identifiers (x).",
+      "INVALID_ARGUMENT_ERROR",
+      { genesisDocument: flags.genesisDocument }
+    );
+  }
+}
 
 // src/commands/write.ts
 var import_key_manager2 = require("@did-btcr2/key-manager");
+var import_api6 = require("@did-btcr2/api");
 function registerWriteOptions(command) {
   return command.option(
     "-s, --source-document <json>",
@@ -2381,7 +2452,7 @@ function registerWriteOptions(command) {
   ).option(
     "--resolution-options-path <path>",
     "Path to a JSON file with resolution options, for the resolution of the source document"
-  ).option("--min-conf <n>", MIN_CONF_HELP, parseMinConf).option(
+  ).option("--min-conf <n>", MIN_CONF_HELP, parseMinConf).option("--genesis-document <path>", `${GENESIS_DOCUMENT_HELP}, for the resolution of the source document`).option(
     "--publish-to-cas <mode>",
     "Publish update artifacts to a writable CAS before broadcast: auto|always|never. CAS publication is optional; the default distributes the returned artifacts via sidecar.",
     parsePublishToCasMode,
@@ -2406,14 +2477,14 @@ async function prepareWrite(options, factory, g) {
       { did }
     );
   }
-  const hasResolutionFlags = options.resolutionOptions !== void 0 || options.resolutionOptionsPath !== void 0 || options.minConf !== void 0;
-  if (hasDocument && hasResolutionFlags) {
+  if (hasDocument && hasResolutionFlags(options)) {
     throw new CLIError(
-      "--resolution-options, --resolution-options-path, and --min-conf apply only when --source-document and --source-version-id are omitted. A supplied source pair skips resolution.",
+      "--resolution-options, --resolution-options-path, --min-conf, and --genesis-document apply only when --source-document and --source-version-id are omitted. A supplied source pair skips resolution.",
       "INVALID_ARGUMENT_ERROR",
       { did }
     );
   }
+  assertGenesisDocumentApplies(options, import_api6.Identifier.decode(did).hrp);
   assertKeystoreAllowedForNetwork(network, g);
   const resolutionOptions = await readResolutionOptions(options);
   const api = factory(network, g);
@@ -2502,9 +2573,8 @@ function registerDeactivateCommand(program, factory, globals) {
 }
 
 // src/commands/identifier.ts
-var import_api6 = require("@did-btcr2/api");
+var import_api7 = require("@did-btcr2/api");
 var import_utils5 = require("@noble/hashes/utils.js");
-var import_promises2 = require("fs/promises");
 function registerIdentifierCommand(program, factory, globals) {
   const identifier = program.command("identifier").description("Decode and validate did:btcr2 identifiers (offline).");
   const print = (result) => console.log(formatResult(result, globals()));
@@ -2545,7 +2615,7 @@ function registerIdentifierCommand(program, factory, globals) {
           { did }
         );
       }
-      const genesisDocument = options.genesisDocument === void 0 ? void 0 : await readGenesisDocument(options.genesisDocument);
+      const genesisDocument = options.genesisDocument === void 0 ? void 0 : await readGenesisDocumentFile(options.genesisDocument);
       data.initialDocument = api.btcr2.getInitialDocument(did, genesisDocument);
     }
     print({ action: "identifier-decode", data });
@@ -2560,14 +2630,14 @@ function registerIdentifierCommand(program, factory, globals) {
     const genesisBytes = options.bytes === void 0 ? void 0 : parseHexBytes(options.bytes);
     let genesisDocument;
     if (options.genesisDocument !== void 0) {
-      if (import_api6.Identifier.isValid(did) && import_api6.Identifier.decode(did).hrp === "k") {
+      if (import_api7.Identifier.isValid(did) && import_api7.Identifier.decode(did).hrp === "k") {
         throw new CLIError(
           "--genesis-document applies only to external identifiers (x).",
           "INVALID_ARGUMENT_ERROR",
           { did }
         );
       }
-      genesisDocument = await readGenesisDocument(options.genesisDocument);
+      genesisDocument = await readGenesisDocumentFile(options.genesisDocument);
     }
     const report = factory().did.validate(did, { genesisBytes, genesisDocument });
     print({ action: "identifier-validate", data: report });
@@ -2575,7 +2645,7 @@ function registerIdentifierCommand(program, factory, globals) {
   });
 }
 function assertValidIdentifier(did) {
-  const report = import_api6.Identifier.validate(did);
+  const report = import_api7.Identifier.validate(did);
   if (report.valid) return;
   const failed = report.checks[report.checks.length - 1];
   throw new CLIError(
@@ -2591,31 +2661,275 @@ function parseHexBytes(value) {
     throw new CLIError("Invalid bytes: not valid hex.", "INVALID_ARGUMENT_ERROR", { bytes: value });
   }
 }
-async function readGenesisDocument(path) {
+
+// src/commands/genesis.ts
+var import_utils7 = require("@noble/hashes/utils.js");
+var import_node_fs9 = require("fs");
+var import_promises3 = require("fs/promises");
+var import_node_path6 = require("path");
+var import_promises4 = require("readline/promises");
+
+// src/genesis-spec.ts
+var import_utils6 = require("@noble/hashes/utils.js");
+function parseGenesisSpec(value, source) {
+  const fail = (message) => {
+    throw new CLIError(`Invalid genesis spec: ${message}`, "INVALID_ARGUMENT_ERROR", { spec: source });
+  };
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return fail("the file must contain a JSON object.");
+  }
+  const spec = value;
+  if (!Array.isArray(spec.verificationMethods) || spec.verificationMethods.length === 0) {
+    return fail('"verificationMethods" must be a non-empty array.');
+  }
+  spec.verificationMethods.forEach((vm, index) => {
+    if (vm === null || typeof vm !== "object") return fail(`verificationMethods[${index}] must be an object.`);
+    const hasKey = typeof vm.key === "string" && vm.key.length > 0;
+    const hasPublicKey = typeof vm.publicKey === "string" && vm.publicKey.length > 0;
+    if (hasKey === hasPublicKey) {
+      return fail(`verificationMethods[${index}] needs exactly one of "key" (a keystore reference) or "publicKey" (hex).`);
+    }
+  });
+  if (spec.beacons !== void 0) {
+    if (!Array.isArray(spec.beacons)) return fail('"beacons" must be an array.');
+    spec.beacons.forEach((beacon, index) => {
+      if (beacon === null || typeof beacon !== "object") return fail(`beacons[${index}] must be an object.`);
+      const sources = ["key", "publicKey", "address"].filter((name) => beacon[name] !== void 0);
+      if (sources.length > 1) {
+        return fail(`beacons[${index}] names ${sources.join(" and ")}. Give only one of "key", "publicKey", or "address".`);
+      }
+    });
+  }
+  if (spec.services !== void 0 && !Array.isArray(spec.services)) {
+    return fail('"services" must be an array.');
+  }
+  return spec;
+}
+function toApiSpec(spec, network, resolvePublicKey) {
+  const keyBytes = (entry, label) => entry.key !== void 0 ? resolvePublicKey(entry.key) : parseHexPublicKey(entry.publicKey, label);
+  const verificationMethods = spec.verificationMethods.map((vm, index) => ({
+    publicKey: keyBytes(vm, `verificationMethods[${index}].publicKey`),
+    relationships: vm.relationships,
+    fragment: vm.fragment
+  }));
+  const beacons = spec.beacons?.map((beacon, index) => ({
+    type: beacon.type,
+    publicKey: beacon.key !== void 0 || beacon.publicKey !== void 0 ? keyBytes(beacon, `beacons[${index}].publicKey`) : void 0,
+    addressType: beacon.addressType,
+    address: beacon.address,
+    fragment: beacon.fragment
+  }));
+  return {
+    network,
+    verificationMethods,
+    beacons,
+    services: spec.services
+  };
+}
+function parseHexPublicKey(hex, label) {
+  try {
+    return (0, import_utils6.hexToBytes)(hex.trim());
+  } catch {
+    throw new CLIError(`Invalid ${label}: not valid hex.`, "INVALID_ARGUMENT_ERROR", { publicKey: hex });
+  }
+}
+
+// src/genesis-wizard.ts
+var import_api8 = require("@did-btcr2/api");
+var PUBLIC_KEY_HEX = /^0[23][0-9a-fA-F]{64}$/;
+async function collectGenesisSpec(ask, ctx) {
+  const verificationMethods = await collectVerificationMethods(ask, ctx);
+  const beacons = await collectBeacons(ask, ctx, verificationMethods[0]);
+  const services = await collectServices(ask, ctx);
+  return { verificationMethods, beacons, ...services.length > 0 && { services } };
+}
+async function collectVerificationMethods(ask, ctx) {
+  if (ctx.keys.length === 0) {
+    ctx.say("The keystore has no keys. Enter each key as a 33-byte compressed public key in hex.");
+  } else {
+    ctx.say("Keys in the keystore:");
+    for (const key of ctx.keys) {
+      ctx.say(`  ${key.fingerprint}${key.name ? `  ${key.name}` : ""}${key.active ? "  (active)" : ""}`);
+    }
+  }
+  const active = ctx.keys.find((key) => key.active);
+  const methods = [];
+  for (let n = 1; ; n++) {
+    const defaultRef = n === 1 && active ? active.name ?? active.fingerprint : void 0;
+    const source = await askKeySource(ask, ctx, `Verification method ${n}: key reference or public key hex`, defaultRef);
+    const relationships = await askRelationships(ask, ctx, n);
+    methods.push({ ...source, ...relationships && { relationships } });
+    if (!await askYesNo(ask, "Add another verification method?")) break;
+  }
+  return methods;
+}
+async function collectBeacons(ask, ctx, firstMethod) {
+  const beacons = [];
+  for (let n = 1; ; n++) {
+    const type = await askChoice(ask, ctx, `Beacon ${n} type`, import_api8.BEACON_TYPES, "SingletonBeacon");
+    const address = (await ask(`Beacon ${n} address (blank: derive the address from the key of method 1): `)).trim();
+    if (address.length === 0) {
+      const addressType = await askChoice(ask, ctx, `Beacon ${n} address type`, import_api8.BEACON_ADDRESS_TYPES, import_api8.DEFAULT_BEACON_ADDRESS_TYPE);
+      const keySource = firstMethod.key !== void 0 ? { key: firstMethod.key } : { publicKey: firstMethod.publicKey };
+      beacons.push({ type, ...keySource, addressType });
+    } else {
+      beacons.push({ type, address });
+    }
+    if (!await askYesNo(ask, "Add another beacon?")) break;
+  }
+  return beacons;
+}
+async function collectServices(ask, ctx) {
+  const services = [];
+  while (await askYesNo(ask, "Add a service?")) {
+    const n = services.length + 1;
+    const fragment = (await ask(`Service ${n} id fragment (blank: service-<position>): `)).trim();
+    const type = await askRequired(ask, ctx, `Service ${n} type`);
+    const serviceEndpoint = await askRequired(ask, ctx, `Service ${n} endpoint`);
+    services.push({ ...fragment.length > 0 && { id: `#${fragment.replace(/^#/, "")}` }, type, serviceEndpoint });
+  }
+  return services;
+}
+async function askKeySource(ask, ctx, question, defaultRef) {
+  for (; ; ) {
+    const raw = (await ask(`${question}${defaultRef ? ` [${defaultRef}]` : ""}: `)).trim();
+    const answer = raw.length > 0 ? raw : defaultRef;
+    if (answer === void 0) {
+      ctx.say("A key is required.");
+      continue;
+    }
+    if (PUBLIC_KEY_HEX.test(answer)) return { publicKey: answer.toLowerCase() };
+    try {
+      ctx.resolveKey(answer);
+      return { key: answer };
+    } catch (error) {
+      ctx.say(error.message);
+    }
+  }
+}
+async function askRelationships(ask, ctx, n) {
+  const names = import_api8.VERIFICATION_RELATIONSHIPS.join(", ");
+  for (; ; ) {
+    const raw = (await ask(`Relationships of method ${n} (comma-separated: ${names}) [all]: `)).trim();
+    if (raw.length === 0) return void 0;
+    const chosen = raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+    const unknown = chosen.filter((name) => !import_api8.VERIFICATION_RELATIONSHIPS.includes(name));
+    if (unknown.length === 0) return chosen;
+    ctx.say(`Unknown relationship: ${unknown.join(", ")}. Expected one of ${names}.`);
+  }
+}
+async function askChoice(ask, ctx, question, choices, defaultValue) {
+  for (; ; ) {
+    const raw = (await ask(`${question} (${choices.join(", ")}) [${defaultValue}]: `)).trim();
+    if (raw.length === 0) return defaultValue;
+    if (choices.includes(raw)) return raw;
+    ctx.say(`Unknown value "${raw}". Expected one of ${choices.join(", ")}.`);
+  }
+}
+async function askRequired(ask, ctx, question) {
+  for (; ; ) {
+    const raw = (await ask(`${question}: `)).trim();
+    if (raw.length > 0) return raw;
+    ctx.say("A value is required.");
+  }
+}
+async function askYesNo(ask, question) {
+  const raw = (await ask(`${question} [y/N]: `)).trim();
+  return /^y(es)?$/i.test(raw);
+}
+
+// src/commands/genesis.ts
+var DEFAULT_GENESIS_PATH = "genesis.json";
+function registerGenesisCommand(program, factory, keystoreFactory, globals) {
+  const genesis = program.command("genesis").description("Build the genesis document of an external identifier (offline).");
+  const print = (result) => console.log(formatResult(result, globals()));
+  genesis.command("build").description("Build a genesis document, write it to a file, and print the external identifier.").option("-n, --network <network>", NETWORK_OPTION_HELP).option("--spec <path>", "Path to a JSON spec file with the keys, beacons, and services. Runs without prompts.").option("--out <path>", "Path of the genesis document to write.", DEFAULT_GENESIS_PATH).option("--force", "Overwrite an existing --out file.", false).action(async (options) => {
+    const g = globals();
+    const overrides = overridesFromGlobals(g);
+    const network = resolveNetworkOption(options.network, overrides);
+    warnProfileNetworkMismatch(g, network, overrides);
+    const outPath = (0, import_node_path6.resolve)(options.out);
+    if (!options.force && (0, import_node_fs9.existsSync)(outPath)) {
+      throw new CLIError(
+        `The file ${outPath} exists. Pass --force to overwrite it, or --out <path> for another file.`,
+        "INVALID_ARGUMENT_ERROR",
+        { out: outPath }
+      );
+    }
+    let keystoreApi;
+    const kms = () => (keystoreApi ??= keystoreFactory(void 0, overrides)).kms.kms;
+    const resolvePublicKey = (ref) => kms().getPublicKey(resolveKeyRef(kms(), ref));
+    const spec = options.spec !== void 0 ? await readSpecFile(options.spec) : await runWizard(kms);
+    const api = factory();
+    const document2 = api.btcr2.buildGenesisDocument(toApiSpec(spec, network, resolvePublicKey));
+    const json = `${JSON.stringify(document2, null, 2)}
+`;
+    const { did, genesisBytes, didDocument } = api.btcr2.createExternalFromDocument(JSON.parse(json), { network });
+    await (0, import_promises3.writeFile)(outPath, json, { encoding: "utf-8", flag: options.force ? "w" : "wx" });
+    const beacons = api.btcr2.getBeacons(didDocument);
+    print({
+      action: "genesis-build",
+      data: { did, network, genesisBytes: (0, import_utils7.bytesToHex)(genesisBytes), path: outPath, beacons }
+    });
+    if (!g.quiet && g.output !== "json") {
+      process.stderr.write(
+        `Wrote the genesis document to ${outPath}. Keep it: the identifier resolves only with it. Pass --genesis-document <path> to resolve, update, and deactivate, or publish it to a CAS.
+`
+      );
+      if (beacons.length > 0) printBeaconFundingHint(g, network, beacons[0].address);
+    }
+  });
+}
+async function readSpecFile(path) {
   let parsed;
   try {
-    parsed = JSON.parse(await (0, import_promises2.readFile)(path, "utf-8"));
+    parsed = JSON.parse(await (0, import_promises3.readFile)(path, "utf-8"));
   } catch {
     throw new CLIError(
-      "Invalid genesis document path. Must be a valid path to a JSON file.",
+      "Invalid genesis spec path. Must be a valid path to a JSON file.",
       "INVALID_ARGUMENT_ERROR",
-      { genesisDocument: path }
+      { spec: path }
     );
   }
-  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+  return parseGenesisSpec(parsed, path);
+}
+async function runWizard(kms) {
+  if (!process.stdin.isTTY) {
     throw new CLIError(
-      "Invalid genesis document. The file must contain a JSON object.",
-      "INVALID_ARGUMENT_ERROR",
-      { genesisDocument: path }
+      "No terminal is attached. Pass --spec <path> to build the genesis document without prompts.",
+      "INVALID_ARGUMENT_ERROR"
     );
   }
-  return parsed;
+  const store = kms();
+  const rl = (0, import_promises4.createInterface)({ input: process.stdin, output: process.stderr });
+  try {
+    return await collectGenesisSpec((question) => rl.question(question), {
+      say: (line) => process.stderr.write(`${line}
+`),
+      keys: listKeys(store),
+      resolveKey: (ref) => resolveKeyRef(store, ref)
+    });
+  } finally {
+    rl.close();
+  }
+}
+function listKeys(kms) {
+  const active = kms.activeKeyId;
+  return kms.listKeys().map((id) => {
+    const entry = kms.getEntry(id);
+    return {
+      keyId: id,
+      fingerprint: id.split(":").pop() ?? id,
+      ...entry.tags?.name && { name: entry.tags.name },
+      active: id === active
+    };
+  });
 }
 
 // src/commands/key.ts
 var import_keypair = require("@did-btcr2/keypair");
-var import_utils6 = require("@noble/hashes/utils.js");
-var import_node_fs9 = require("fs");
+var import_utils8 = require("@noble/hashes/utils.js");
+var import_node_fs10 = 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()));
@@ -2624,7 +2938,7 @@ function registerKeyCommand(program, factory, globals) {
     assertNameAvailable(api.kms.kms, options.name);
     const setActive = options.setActive ?? false;
     const id = api.kms.generateKey({ ...options.name && { tags: { name: options.name } }, setActive });
-    print({ action: "key-generate", data: { keyId: id, publicKey: (0, import_utils6.bytesToHex)(api.kms.getPublicKey(id)), active: setActive } });
+    print({ action: "key-generate", data: { keyId: id, publicKey: (0, import_utils8.bytesToHex)(api.kms.getPublicKey(id)), active: setActive } });
   });
   key.command("list").alias("ls").description("List stored keys.").action(() => {
     const kms = factory(void 0, globals()).kms.kms;
@@ -2644,7 +2958,7 @@ function registerKeyCommand(program, factory, globals) {
     const kms = factory(void 0, globals()).kms.kms;
     const id = resolveKeyRef(kms, ref);
     const entry = kms.getEntry(id);
-    print({ action: "key-show", data: { keyId: id, publicKey: (0, import_utils6.bytesToHex)(entry.publicKey), ...entry.tags && { tags: entry.tags } } });
+    print({ action: "key-show", data: { keyId: id, publicKey: (0, import_utils8.bytesToHex)(entry.publicKey), ...entry.tags && { tags: entry.tags } } });
   });
   key.command("import").description("Import a key: a secret from a hex file, or a public key as watch-only.").option("--secret-file <path>", "Path to a file containing a 32-byte secret key as hex.").option("--public <hex>", "A 33-byte compressed public key as hex (imported watch-only).").option("--name <name>", "A human-friendly name, stored as a tag.").option("--set-active", "Make this the active key.", false).action((options) => {
     if (Boolean(options.secretFile) === Boolean(options.public)) {
@@ -2655,13 +2969,13 @@ function registerKeyCommand(program, factory, globals) {
     const keyPair = options.secretFile ? new import_keypair.SchnorrKeyPair({ secretKey: readHexFile(options.secretFile, 32, "--secret-file") }) : new import_keypair.SchnorrKeyPair({ publicKey: parseHex(options.public ?? "", 33, "--public") });
     const setActive = options.setActive ?? false;
     const id = api.kms.import(keyPair, { ...options.name && { tags: { name: options.name } }, setActive });
-    print({ action: "key-import", data: { keyId: id, publicKey: (0, import_utils6.bytesToHex)(api.kms.getPublicKey(id)), watchOnly: !options.secretFile, active: setActive } });
+    print({ action: "key-import", data: { keyId: id, publicKey: (0, import_utils8.bytesToHex)(api.kms.getPublicKey(id)), watchOnly: !options.secretFile, active: setActive } });
   });
   key.command("export <ref>").description("Export a key. Public material by default; --secret writes the secret to a file.").option("--secret", "Export the secret key. Requires --out.", false).option("--out <path>", "Write the exported secret to this file (created 0600).").action((ref, options) => {
     const api = factory(void 0, globals());
     const id = resolveKeyRef(api.kms.kms, ref);
     if (!options.secret) {
-      print({ action: "key-export", data: { keyId: id, publicKey: (0, import_utils6.bytesToHex)(api.kms.getPublicKey(id)) } });
+      print({ action: "key-export", data: { keyId: id, publicKey: (0, import_utils8.bytesToHex)(api.kms.getPublicKey(id)) } });
       return;
     }
     if (!options.out) {
@@ -2672,7 +2986,7 @@ function registerKeyCommand(program, factory, globals) {
       throw new CLIError(`Key ${id} is watch-only and has no secret to export.`, "INVALID_ARGUMENT_ERROR", { keyId: id });
     }
     process.stderr.write("warning: writing an unencrypted secret key to disk. Protect this file and delete it when done.\n");
-    writeSecretFile(options.out, (0, import_utils6.bytesToHex)(keyPair.secretKey.bytes));
+    writeSecretFile(options.out, (0, import_utils8.bytesToHex)(keyPair.secretKey.bytes));
     print({ action: "key-export", data: { keyId: id, secretWrittenTo: options.out } });
   });
   key.command("delete <ref>").alias("rm").description("Delete a key from the keystore.").option("--force", "Delete even if it is the active key.", false).action((ref, options) => {
@@ -2697,7 +3011,7 @@ function assertNameAvailable(kms, name) {
 function parseHex(hex, expectedBytes, label) {
   let bytes;
   try {
-    bytes = (0, import_utils6.hexToBytes)(hex.trim());
+    bytes = (0, import_utils8.hexToBytes)(hex.trim());
   } catch {
     throw new CLIError(`Invalid hex for ${label}.`, "INVALID_ARGUMENT_ERROR", { label });
   }
@@ -2713,7 +3027,7 @@ function parseHex(hex, expectedBytes, label) {
 function readHexFile(path, expectedBytes, label) {
   let content;
   try {
-    content = (0, import_node_fs9.readFileSync)(path, "utf-8");
+    content = (0, import_node_fs10.readFileSync)(path, "utf-8");
   } catch {
     throw new CLIError(`Cannot read ${label} at ${path}.`, "INVALID_ARGUMENT_ERROR", { label, path });
   }
@@ -2722,7 +3036,7 @@ function readHexFile(path, expectedBytes, label) {
 function writeSecretFile(path, contents) {
   let fd;
   try {
-    fd = (0, import_node_fs9.openSync)(path, "wx", 384);
+    fd = (0, import_node_fs10.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 });
@@ -2730,14 +3044,14 @@ function writeSecretFile(path, contents) {
     throw error;
   }
   try {
-    (0, import_node_fs9.writeFileSync)(fd, contents);
+    (0, import_node_fs10.writeFileSync)(fd, contents);
   } finally {
-    (0, import_node_fs9.closeSync)(fd);
+    (0, import_node_fs10.closeSync)(fd);
   }
 }
 
 // src/commands/config.ts
-var import_node_fs10 = require("fs");
+var import_node_fs11 = require("fs");
 
 // src/config-schema.ts
 var CONFIG_SCHEMA = {
@@ -2874,7 +3188,7 @@ function registerConfigCommand(program, globals) {
   const print = (result) => console.log(formatResult(result, globals()));
   config.command("init").description("Create a default config file with one profile per network.").option("--force", "Overwrite an existing config file.", false).action((options) => {
     const p = path();
-    if ((0, import_node_fs10.existsSync)(p) && !options.force) {
+    if ((0, import_node_fs11.existsSync)(p) && !options.force) {
       throw new CLIError(`Config already exists at ${p}. Use --force to overwrite.`, "INVALID_ARGUMENT_ERROR", { path: p });
     }
     writeDefaultConfigFile(p);
@@ -3024,30 +3338,35 @@ function registerProfileCommand(program, globals) {
 }
 
 // src/commands/completion.ts
-var COMMANDS = "create resolve read update deactivate delete identifier key config profile completion";
+var HELP_COMMAND = "help";
 function registerCompletionCommand(program, _globals) {
   program.command("completion [shell]").description("Print a shell completion script (bash, zsh, or fish) to stdout.").action((shell = "bash") => {
-    console.log(completionScript(shell));
+    console.log(completionScript(shell, completionWords(program)));
   });
 }
-function completionScript(shell) {
+function completionWords(program) {
+  const words = program.commands.flatMap((command) => [command.name(), ...command.aliases()]);
+  return [...words, HELP_COMMAND];
+}
+function completionScript(shell, words) {
+  const list = words.join(" ");
   switch (shell) {
     case "bash":
       return [
         '# btcr2 bash completion. Install with: eval "$(btcr2 completion bash)"',
-        '_btcr2() { COMPREPLY=( $(compgen -W "' + COMMANDS + '" -- "${COMP_WORDS[COMP_CWORD]}") ); }',
+        '_btcr2() { COMPREPLY=( $(compgen -W "' + list + '" -- "${COMP_WORDS[COMP_CWORD]}") ); }',
         "complete -F _btcr2 btcr2"
       ].join("\n");
     case "zsh":
       return [
         '# btcr2 zsh completion. Install with: eval "$(btcr2 completion zsh)"',
-        "_btcr2() { compadd " + COMMANDS + " }",
+        "_btcr2() { compadd " + list + " }",
         "compdef _btcr2 btcr2"
       ].join("\n");
     case "fish":
       return [
         "# btcr2 fish completion. Save to ~/.config/fish/completions/btcr2.fish",
-        'complete -c btcr2 -f -a "' + COMMANDS + '"'
+        'complete -c btcr2 -f -a "' + list + '"'
       ].join("\n");
     default:
       throw new CLIError(`Unsupported shell "${shell}". Use bash, zsh, or fish.`, "INVALID_ARGUMENT_ERROR", { shell });
@@ -3055,18 +3374,18 @@ function completionScript(shell) {
 }
 
 // src/version.ts
-var import_node_fs11 = require("fs");
-var import_node_path6 = require("path");
+var import_node_fs12 = require("fs");
+var import_node_path7 = require("path");
 var import_node_url = require("url");
 function readVersion() {
-  let dir = (0, import_node_path6.dirname)((0, import_node_url.fileURLToPath)(importMetaUrl));
+  let dir = (0, import_node_path7.dirname)((0, import_node_url.fileURLToPath)(importMetaUrl));
   for (let i = 0; i < 5; i++) {
     try {
-      const pkg = JSON.parse((0, import_node_fs11.readFileSync)((0, import_node_path6.join)(dir, "package.json"), "utf-8"));
+      const pkg = JSON.parse((0, import_node_fs12.readFileSync)((0, import_node_path7.join)(dir, "package.json"), "utf-8"));
       if (pkg.name === "@did-btcr2/cli") return pkg.version;
     } catch {
     }
-    dir = (0, import_node_path6.dirname)(dir);
+    dir = (0, import_node_path7.dirname)(dir);
   }
   return "0.0.0";
 }
@@ -3103,6 +3422,7 @@ var DidBtcr2Cli = class {
     registerUpdateCommand(this.program, keystoreFactory, globals);
     registerDeactivateCommand(this.program, keystoreFactory, globals);
     registerIdentifierCommand(this.program, factory, globals);
+    registerGenesisCommand(this.program, factory, keystoreFactory, globals);
     registerKeyCommand(this.program, keystoreFactory, globals);
     registerKeystoreCommand(this.program, globals);
     registerConfigCommand(this.program, globals);
@@ -3177,6 +3497,7 @@ function handleError(error, verbose) {
   registerConfigCommand,
   registerCreateCommand,
   registerDeactivateCommand,
+  registerGenesisCommand,
   registerIdentifierCommand,
   registerInitCommand,
   registerKeyCommand,