@did-btcr2/cli 0.22.0 → 0.23.0

package/src/commands/write.ts

@@ -8,10 +8,13 @@ import {
   resolveSigningKeyRef,
   type ApiFactory,
 } from '../config.js';
+import { Identifier } from '@did-btcr2/api';
 import { CLIError } from '../error.js';
+import { GENESIS_DOCUMENT_HELP } from '../genesis-document-file.js';
 import { resolveKeyRef } from '../keystore/resolve-key-ref.js';
-import { MIN_CONF_HELP, parseMinConf, readResolutionOptions, type ResolutionOptionFlags } from '../resolution-options.js';
+import { hasResolutionFlags, MIN_CONF_HELP, parseMinConf, readResolutionOptions, type ResolutionOptionFlags } from '../resolution-options.js';
 import type { GlobalOptions, NetworkOption, UpdateCommandOptions } from '../types.js';
+import { assertGenesisDocumentApplies } from './resolve.js';
 
 /** The parsed flags that `update` and `deactivate` share. */
 export type WriteFlags = ResolutionOptionFlags & {
@@ -62,6 +65,7 @@ export function registerWriteOptions(command: Command): Command {
       'Path to a JSON file with resolution options, for the resolution of the source document',
     )
     .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. '
@@ -93,7 +97,8 @@ export function registerWriteOptions(command: Command): Command {
  * 3. The resolution flags come only without the source pair. The api ignores
  *    `resolutionOptions` when the pair is supplied (ADR 098). A silent ignore
  *    of `--min-conf` would mislead.
- * 4. A mainnet write is refused with an unencrypted dev keystore (ADR 080).
+ * 4. `--genesis-document` comes only with an external (x) identifier.
+ * 5. A mainnet write is refused with an unencrypted dev keystore (ADR 080).
  */
 export async function prepareWrite(
   options : WriteFlags,
@@ -112,17 +117,15 @@ export async function prepareWrite(
       { did },
     );
   }
-  const hasResolutionFlags = options.resolutionOptions !== undefined
-    || options.resolutionOptionsPath !== undefined
-    || options.minConf !== undefined;
-  if (hasDocument && hasResolutionFlags) {
+  if (hasDocument && hasResolutionFlags(options)) {
     throw new CLIError(
-      '--resolution-options, --resolution-options-path, and --min-conf apply only when '
+      '--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, Identifier.decode(did).hrp);
   assertKeystoreAllowedForNetwork(network, g);
   const resolutionOptions = await readResolutionOptions(options);
   const api = factory(network, g);

package/src/genesis-document-file.ts

@@ -0,0 +1,35 @@
+import { readFile } from 'node:fs/promises';
+import { CLIError } from './error.js';
+
+/** The help text of `--genesis-document`. `resolve`, `update`, and `deactivate` share it. */
+export const GENESIS_DOCUMENT_HELP =
+  'Path to the JSON genesis document of an external identifier (x). '
+  + 'Fills sidecar.genesisDocument of the resolution options';
+
+/**
+ * Reads and parses a genesis document file. The content must be a JSON
+ * object. The shape of the document is checked by the api, not here.
+ * @param path The path of the JSON file.
+ * @returns The parsed object.
+ * @throws {CLIError} If the file is unreadable, not JSON, or not an object.
+ */
+export async function readGenesisDocumentFile(path: string): Promise<object> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(await 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;
+}

package/src/genesis-spec.ts

@@ -0,0 +1,149 @@
+import type {
+  BeaconAddressType,
+  BeaconType,
+  GenesisBeaconSpec,
+  GenesisDocumentSpec,
+  GenesisVerificationMethodSpec,
+  VerificationRelationship
+} from '@did-btcr2/api';
+import { hexToBytes } from '@noble/hashes/utils.js';
+import type { DidService } from '@web5/dids';
+import { CLIError } from './error.js';
+import type { NetworkOption } from './types.js';
+
+/**
+ * One verification method of a genesis spec file. `key` is a keystore
+ * reference (URN, name, or fingerprint prefix); `publicKey` is a 33-byte
+ * compressed public key as hex. Exactly one of the two.
+ */
+export interface GenesisSpecVerificationMethod {
+  key?           : string;
+  publicKey?     : string;
+  relationships? : string[];
+  fragment?      : string;
+}
+
+/**
+ * One beacon of a genesis spec file. `key` or `publicKey` derives the beacon
+ * address from a key; `address` uses a Bitcoin address as given. At most one
+ * of the three; the api requires one.
+ */
+export interface GenesisSpecBeacon {
+  type          : string;
+  key?          : string;
+  publicKey?    : string;
+  addressType?  : string;
+  address?      : string;
+  fragment?     : string;
+}
+
+/** One other service of a genesis spec file. */
+export interface GenesisSpecService {
+  id?             : string;
+  type            : string;
+  serviceEndpoint : unknown;
+}
+
+/**
+ * The genesis spec file that `btcr2 genesis build --spec <path>` reads, and
+ * that the wizard collects. The network comes from `-n` or the configuration,
+ * not from the file.
+ */
+export interface GenesisSpecFile {
+  verificationMethods : GenesisSpecVerificationMethod[];
+  beacons?            : GenesisSpecBeacon[];
+  services?           : GenesisSpecService[];
+}
+
+/** Resolves a keystore key reference to the 33-byte public key. */
+export type ResolvePublicKey = (ref: string) => Uint8Array;
+
+/**
+ * Checks the shape of a parsed genesis spec file. The values (relationship
+ * names, beacon types, addresses) are checked by the api when it builds the
+ * document; this function checks only what the api cannot see: that each
+ * verification method names exactly one key source, and that each beacon
+ * names at most one.
+ * @param value The parsed JSON value.
+ * @param source The file path, for the error data.
+ * @returns The spec.
+ * @throws {CLIError} If the shape is not valid.
+ */
+export function parseGenesisSpec(value: unknown, source: string): GenesisSpecFile {
+  const fail = (message: string): never => {
+    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 as Record<string, unknown>;
+  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 !== undefined) {
+    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] !== undefined);
+      if (sources.length > 1) {
+        return fail(`beacons[${index}] names ${sources.join(' and ')}. Give only one of "key", "publicKey", or "address".`);
+      }
+    });
+  }
+  if (spec.services !== undefined && !Array.isArray(spec.services)) {
+    return fail('"services" must be an array.');
+  }
+  return spec as unknown as GenesisSpecFile;
+}
+
+/**
+ * Converts a genesis spec file to the api spec: resolves each keystore
+ * reference to its public key, parses each hex public key, and passes the
+ * other values through for the api to check.
+ * @param spec The spec file.
+ * @param network The network of the beacon addresses.
+ * @param resolvePublicKey Resolves a keystore reference to the public key.
+ * @returns The api spec.
+ * @throws {CLIError} If a hex public key is not hex.
+ */
+export function toApiSpec(spec: GenesisSpecFile, network: NetworkOption, resolvePublicKey: ResolvePublicKey): GenesisDocumentSpec {
+  const keyBytes = (entry: { key?: string; publicKey?: string }, label: string): Uint8Array =>
+    entry.key !== undefined ? resolvePublicKey(entry.key) : parseHexPublicKey(entry.publicKey as string, label);
+  const verificationMethods: GenesisVerificationMethodSpec[] = spec.verificationMethods.map((vm, index) => ({
+    publicKey     : keyBytes(vm, `verificationMethods[${index}].publicKey`),
+    relationships : vm.relationships as VerificationRelationship[] | undefined,
+    fragment      : vm.fragment,
+  }));
+  const beacons: GenesisBeaconSpec[] | undefined = spec.beacons?.map((beacon, index) => ({
+    type        : beacon.type as BeaconType,
+    publicKey   : beacon.key !== undefined || beacon.publicKey !== undefined
+      ? keyBytes(beacon, `beacons[${index}].publicKey`)
+      : undefined,
+    addressType : beacon.addressType as BeaconAddressType | undefined,
+    address     : beacon.address,
+    fragment    : beacon.fragment,
+  }));
+  return {
+    network,
+    verificationMethods,
+    beacons,
+    services : spec.services as DidService[] | undefined,
+  };
+}
+
+/** Parses a hex public key. The length and the curve check belong to the api. */
+export function parseHexPublicKey(hex: string, label: string): Uint8Array {
+  try {
+    return hexToBytes(hex.trim());
+  } catch {
+    throw new CLIError(`Invalid ${label}: not valid hex.`, 'INVALID_ARGUMENT_ERROR', { publicKey: hex });
+  }
+}

package/src/genesis-wizard.ts

@@ -0,0 +1,163 @@
+import { BEACON_ADDRESS_TYPES, BEACON_TYPES, DEFAULT_BEACON_ADDRESS_TYPE, VERIFICATION_RELATIONSHIPS } from '@did-btcr2/api';
+import type { GenesisSpecBeacon, GenesisSpecFile, GenesisSpecService, GenesisSpecVerificationMethod } from './genesis-spec.js';
+
+/** Asks one question and returns the answer line. */
+export type Ask = (question: string) => Promise<string>;
+
+/** One keystore key as the wizard lists it. */
+export interface WizardKey {
+  keyId       : string;
+  fingerprint : string;
+  name?       : string;
+  active      : boolean;
+}
+
+/** What the wizard needs from the command: output, the key list, and key resolution. */
+export interface WizardContext {
+  /** Prints one line to the operator. */
+  say: (line: string) => void;
+  /** The keys of the keystore, for the list and the default. */
+  keys: WizardKey[];
+  /** Resolves a key reference to its id, or throws with a message. */
+  resolveKey: (ref: string) => string;
+}
+
+/** A 33-byte compressed public key as hex. */
+const PUBLIC_KEY_HEX = /^0[23][0-9a-fA-F]{64}$/;
+
+/**
+ * Collects a genesis spec through questions: the verification methods with
+ * their relationships, the beacons, and the other services. The answers are
+ * not checked against the network here; the api checks them when it builds
+ * the document, and the command reports the failure.
+ * @param ask Asks one question.
+ * @param ctx The output, the key list, and the key resolver.
+ * @returns The spec.
+ */
+export async function collectGenesisSpec(ask: Ask, ctx: WizardContext): Promise<GenesisSpecFile> {
+  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 }) };
+}
+
+/** Asks for the verification methods. The first one defaults to the active key. */
+async function collectVerificationMethods(ask: Ask, ctx: WizardContext): Promise<GenesisSpecVerificationMethod[]> {
+  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: GenesisSpecVerificationMethod[] = [];
+  for (let n = 1; ; n++) {
+    const defaultRef = n === 1 && active ? (active.name ?? active.fingerprint) : undefined;
+    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;
+}
+
+/** Asks for the beacons. The first one defaults to a Singleton beacon on the first key. */
+async function collectBeacons(ask: Ask, ctx: WizardContext, firstMethod: GenesisSpecVerificationMethod): Promise<GenesisSpecBeacon[]> {
+  const beacons: GenesisSpecBeacon[] = [];
+  for (let n = 1; ; n++) {
+    const type = await askChoice(ask, ctx, `Beacon ${n} type`, 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`, BEACON_ADDRESS_TYPES, DEFAULT_BEACON_ADDRESS_TYPE);
+      const keySource = firstMethod.key !== undefined ? { 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;
+}
+
+/** Asks for the other services, if any. */
+async function collectServices(ask: Ask, ctx: WizardContext): Promise<GenesisSpecService[]> {
+  const services: GenesisSpecService[] = [];
+  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;
+}
+
+/** Asks for a key reference or a public key hex, until the answer resolves. */
+async function askKeySource(
+  ask        : Ask,
+  ctx        : WizardContext,
+  question   : string,
+  defaultRef : string | undefined,
+): Promise<{ key: string } | { publicKey: string }> {
+  for (;;) {
+    const raw = (await ask(`${question}${defaultRef ? ` [${defaultRef}]` : ''}: `)).trim();
+    const answer = raw.length > 0 ? raw : defaultRef;
+    if (answer === undefined) {
+      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 as Error).message);
+    }
+  }
+}
+
+/** Asks for the relationships of a method. Blank means all four (the api default). */
+async function askRelationships(ask: Ask, ctx: WizardContext, n: number): Promise<string[] | undefined> {
+  const names = VERIFICATION_RELATIONSHIPS.join(', ');
+  for (;;) {
+    const raw = (await ask(`Relationships of method ${n} (comma-separated: ${names}) [all]: `)).trim();
+    if (raw.length === 0) return undefined;
+    const chosen = raw.split(',').map(s => s.trim()).filter(s => s.length > 0);
+    const unknown = chosen.filter(name => !(VERIFICATION_RELATIONSHIPS as readonly string[]).includes(name));
+    if (unknown.length === 0) return chosen;
+    ctx.say(`Unknown relationship: ${unknown.join(', ')}. Expected one of ${names}.`);
+  }
+}
+
+/** Asks for one value of a list, with a default. */
+async function askChoice<T extends string>(
+  ask          : Ask,
+  ctx          : WizardContext,
+  question     : string,
+  choices      : readonly T[],
+  defaultValue : T,
+): Promise<T> {
+  for (;;) {
+    const raw = (await ask(`${question} (${choices.join(', ')}) [${defaultValue}]: `)).trim();
+    if (raw.length === 0) return defaultValue;
+    if ((choices as readonly string[]).includes(raw)) return raw as T;
+    ctx.say(`Unknown value "${raw}". Expected one of ${choices.join(', ')}.`);
+  }
+}
+
+/** Asks for a non-empty value. */
+async function askRequired(ask: Ask, ctx: WizardContext, question: string): Promise<string> {
+  for (;;) {
+    const raw = (await ask(`${question}: `)).trim();
+    if (raw.length > 0) return raw;
+    ctx.say('A value is required.');
+  }
+}
+
+/** Asks a yes/no question. Blank means no. */
+async function askYesNo(ask: Ask, question: string): Promise<boolean> {
+  const raw = (await ask(`${question} [y/N]: `)).trim();
+  return /^y(es)?$/i.test(raw);
+}

package/src/hints.ts

@@ -20,8 +20,6 @@ import type { GlobalOptions, NetworkOption } from './types.js';
  */
 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');
@@ -29,6 +27,19 @@ export function printCreateFundingHint(g: GlobalOptions, network: NetworkOption,
   } catch {
     return;
   }
+  printBeaconFundingHint(g, network, beaconAddress);
+}
+
+/**
+ * Prints a funding hint for a beacon address on a network with a public
+ * faucet: the address next to the faucet and explorer links. A no-op on a
+ * network without a faucet (regtest/mainnet). `create -t x --document` and
+ * `genesis build` use it for the first beacon of the genesis document.
+ */
+export function printBeaconFundingHint(g: GlobalOptions, network: NetworkOption, beaconAddress: string): void {
+  if (g.quiet || g.output === 'json') return;
+  const faucet = faucetUrl(network);
+  if (!faucet) return;
   const explorer = explorerAddressUrl(network, beaconAddress);
   const lines = [
     'Fund the initial beacon to anchor updates:',

package/src/network-option.ts

@@ -0,0 +1,50 @@
+import type { ConnectionOverrides } from './config.js';
+import { profileNetworkMismatch, resolveDefaultNetwork } from './config.js';
+import { CLIError } from './error.js';
+import type { GlobalOptions, NetworkOption } from './types.js';
+import { SUPPORTED_NETWORKS } from './types.js';
+
+/** The help text of `-n, --network` on the offline creation commands. */
+export const NETWORK_OPTION_HELP =
+  'Identifier bitcoin network <bitcoin|testnet3|testnet4|signet|mutinynet|regtest> '
+  + '(default: config defaults.network, else regtest)';
+
+/** Builds the keystore- and config-resolution overrides from the global flags. */
+export function overridesFromGlobals(g: GlobalOptions): ConnectionOverrides {
+  return {
+    home           : g.home,
+    config         : g.config,
+    profile        : g.profile,
+    keystore       : g.keystore,
+    passphraseFile : g.passphraseFile,
+  };
+}
+
+/** Validates an explicit `--network`, or resolves the default from configuration. */
+export function resolveNetworkOption(explicit: string | undefined, overrides: ConnectionOverrides): NetworkOption {
+  if (!explicit) return resolveDefaultNetwork(overrides);
+  if (!SUPPORTED_NETWORKS.includes(explicit as NetworkOption)) {
+    throw new CLIError(
+      'Invalid network. Must be one of "bitcoin", "testnet3", "testnet4", "signet", "mutinynet", or "regtest".',
+      'INVALID_ARGUMENT_ERROR',
+      { network: explicit },
+    );
+  }
+  return explicit as NetworkOption;
+}
+
+/**
+ * Warns on stderr, and never blocks, when the network of a new identifier
+ * disagrees with the network that the active profile declares. A `production`
+ * profile that holds mainnet endpoints must not mint a regtest DID in silence.
+ */
+export function warnProfileNetworkMismatch(g: GlobalOptions, network: NetworkOption, overrides: ConnectionOverrides): void {
+  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.\n'
+    );
+  }
+}

package/src/resolution-options.ts

@@ -2,14 +2,24 @@ import { DEFAULT_MIN_CONF } from '@did-btcr2/api';
 import type { ResolutionOptions } from '@did-btcr2/method';
 import { readFile } from 'node:fs/promises';
 import { CLIError } from './error.js';
+import { readGenesisDocumentFile } from './genesis-document-file.js';
 
 /** The flags that select the resolution options of a command. */
 export type ResolutionOptionFlags = {
   resolutionOptions?     : string;
   resolutionOptionsPath? : string;
   minConf?               : number;
+  genesisDocument?       : string;
 };
 
+/** Whether any resolution flag is set. */
+export function hasResolutionFlags(flags: ResolutionOptionFlags): boolean {
+  return flags.resolutionOptions !== undefined
+    || flags.resolutionOptionsPath !== undefined
+    || flags.minConf !== undefined
+    || flags.genesisDocument !== undefined;
+}
+
 /** The help text of `--min-conf`. `resolve`, `update`, and `deactivate` share it. */
 export const MIN_CONF_HELP =
   'Minimum block confirmations a beacon signal needs before resolution applies it '
@@ -17,8 +27,9 @@ export const MIN_CONF_HELP =
 
 /**
  * Builds the resolution options from the flags. The inline JSON wins over
- * the file. The `--min-conf` flag wins over a `minConf` inside the JSON.
- * Returns `undefined` if no flag is set.
+ * the file. The `--min-conf` flag wins over a `minConf` inside the JSON. The
+ * `--genesis-document` file wins over a `sidecar.genesisDocument` inside the
+ * JSON. Returns `undefined` if no flag is set.
  */
 export async function readResolutionOptions(flags: ResolutionOptionFlags): Promise<ResolutionOptions | undefined> {
   let resolutionOptions: ResolutionOptions | undefined;
@@ -48,6 +59,14 @@ export async function readResolutionOptions(flags: ResolutionOptionFlags): Promi
   if (flags.minConf !== undefined) {
     resolutionOptions = { ...(resolutionOptions ?? {}), minConf: flags.minConf };
   }
+  // The file wins over a sidecar.genesisDocument inside the JSON options.
+  if (flags.genesisDocument !== undefined) {
+    const genesisDocument = await readGenesisDocumentFile(flags.genesisDocument);
+    resolutionOptions = {
+      ...(resolutionOptions ?? {}),
+      sidecar : { ...(resolutionOptions?.sidecar ?? {}), genesisDocument },
+    };
+  }
   return resolutionOptions;
 }
 

package/src/types.ts

@@ -1,4 +1,4 @@
-import type { BroadcastOptions, DidUpdateResult, IdentifierReport, PublishToCasMode, Signer } from '@did-btcr2/api';
+import type { BeaconInfo, BroadcastOptions, DidUpdateResult, IdentifierReport, PublishToCasMode, Signer } from '@did-btcr2/api';
 import type { Btcr2DidDocument, ResolutionOptions } from '@did-btcr2/method';
 import type { DidResolutionResult } from '@web5/dids';
 import type { DoctorReport, EffectiveConfig } from './config.js';
@@ -69,13 +69,28 @@ export interface IdentifierDecodeData {
   initialDocument? : Btcr2DidDocument;
 }
 
+/**
+ * The data that `genesis build` prints: the external identifier, its
+ * network, its genesis bytes as hex, the path of the written genesis
+ * document, and the beacons of the initial DID document with their
+ * addresses to fund.
+ */
+export interface GenesisBuildData {
+  did          : string;
+  network      : NetworkOption;
+  genesisBytes : string;
+  path         : string;
+  beacons      : BeaconInfo[];
+}
+
 export type CommandResult =
-  | { action: 'create'; data: string; keyId?: string; publicKey?: string }
+  | { action: 'create'; data: string; keyId?: string; publicKey?: string; genesisBytes?: string }
   | { action: 'resolve'; data: DidResolutionResult }
   | { action: 'update'; data: DidUpdateResult }
   | { action: 'deactivate'; data: DidUpdateResult }
   | { action: 'identifier-decode'; data: IdentifierDecodeData }
   | { action: 'identifier-validate'; data: IdentifierReport }
+  | { action: 'genesis-build'; data: GenesisBuildData }
   | { action: 'key-generate'; data: { keyId: string; publicKey: string; active: boolean } }
   | { action: 'key-list'; data: Array<{ keyId: string; fingerprint: string; name?: string; active: boolean }> }
   | { action: 'key-show'; data: { keyId: string; publicKey: string; tags?: Record<string, string> } }