@forestrie/forestrie-cli 0.8.0

package/src/main/decode-receipt.ts

@@ -0,0 +1,72 @@
+import { readFileSync } from "node:fs";
+
+import type { Out } from "@forestrie/cli-kit/reporting";
+import type { DecodeReceiptOptions } from "../options/decode-receipt.js";
+import {
+  DecodeReceiptError,
+  decodeReceipt,
+  type DecodedReceipt,
+} from "../lib/decode-receipt-decode.js";
+import { renderReceipt } from "../lib/decode-receipt-render.js";
+
+/** `--json` decode failure shape (stage names the parse step that failed). */
+export type DecodeReceiptFailure = {
+  error: "decode_failed";
+  command: "decode-receipt";
+  stage: string;
+  message: string;
+};
+
+function readReceiptBytes(options: DecodeReceiptOptions): Uint8Array {
+  const source = options.receipt ?? "-";
+  try {
+    // fd 0: read stdin when the positional is omitted or `-`.
+    const buffer = source === "-" ? readFileSync(0) : readFileSync(source);
+    return new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new DecodeReceiptError(
+      "input",
+      source === "-"
+        ? `cannot read receipt from stdin: ${detail}`
+        : `cannot read receipt file ${source}: ${detail}`,
+    );
+  }
+}
+
+/**
+ * FOR-346: decode a COSE receipt so the audience sees it is just COSE
+ * (Sign1 + MMR inclusion). Display only — no signature verification
+ * (that is `forestrie verify`, FOR-347).
+ */
+export async function runDecodeReceipt(
+  out: Out,
+  options: DecodeReceiptOptions,
+): Promise<void> {
+  let decoded: DecodedReceipt;
+  try {
+    decoded = decodeReceipt(readReceiptBytes(options));
+  } catch (error) {
+    const stage = error instanceof DecodeReceiptError ? error.stage : "decode";
+    const message = error instanceof Error ? error.message : String(error);
+    if (options.json) {
+      const failure: DecodeReceiptFailure = {
+        error: "decode_failed",
+        command: "decode-receipt",
+        stage,
+        message,
+      };
+      out.out(JSON.stringify(failure, null, 2));
+    } else {
+      out.warn("forestrie decode-receipt: %s: %s", stage, message);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  if (options.json) {
+    out.out(JSON.stringify(decoded, null, 2));
+    return;
+  }
+  out.out(renderReceipt(decoded));
+}

package/src/main/delegate.ts

@@ -0,0 +1,141 @@
+import type { Out } from "@forestrie/cli-kit/reporting";
+import { readTextFile, writeOutputFile } from "../lib/fsio.js";
+import type { DelegateOptions } from "../options/delegate.js";
+import {
+  DelegateFlowError,
+  runDelegateFlow,
+  type DelegateFlowDeps,
+  type DelegateFlowResult,
+} from "../lib/delegate-flow.js";
+
+/**
+ * FOR-390 / ADR-0052: authorize a custodian-vouched sealer to publish
+ * checkpoints for a log the caller owns (K(L)). Reads the ES256 root PEM, runs
+ * the public delegation flow (`delegate-flow.ts`) — which verifies the
+ * registrar voucher against the caller-known registrar key before binding —
+ * and reports the bound lease. Public coordinator endpoints only.
+ */
+
+/** `--json` success shape. */
+export type DelegateReport = {
+  command: "delegate";
+  status: "submitted";
+  logId: string;
+  sealerId: string;
+  epoch: number | string;
+  mmrStart: number;
+  mmrEnd: number;
+  expiresAt: number;
+  /** Present when `--out-b64` was given. */
+  outB64?: string;
+};
+
+/** `--json` failure shape. */
+export type DelegateErrorReport = {
+  command: "delegate";
+  error: "key_read_failed" | "delegation_failed";
+  message: string;
+  httpStatus?: number;
+};
+
+/** Test seam: effects injected by the delegate tests (real by default). */
+export type DelegateRunDeps = DelegateFlowDeps;
+
+async function readPemFile(path: string, flag: string): Promise<string> {
+  return readTextFile(path, `${flag} key file not found: ${path}`);
+}
+
+function reportError(
+  out: Out,
+  options: DelegateOptions,
+  report: DelegateErrorReport,
+): void {
+  if (options.json) {
+    out.out(JSON.stringify(report, null, 2));
+  } else {
+    out.warn("forestrie delegate: %s", report.message);
+  }
+  process.exitCode = 1;
+}
+
+async function reportResult(
+  out: Out,
+  options: DelegateOptions,
+  result: DelegateFlowResult,
+): Promise<void> {
+  if (options.outB64 !== undefined) {
+    await writeOutputFile(
+      options.outB64,
+      Buffer.from(result.certificate).toString("base64"),
+    );
+  }
+  if (options.json) {
+    const report: DelegateReport = {
+      command: "delegate",
+      status: "submitted",
+      logId: options.logId,
+      sealerId: result.sealerId,
+      epoch: result.epoch,
+      mmrStart: result.mmrStart,
+      mmrEnd: result.mmrEnd,
+      expiresAt: result.expiresAt,
+    };
+    if (options.outB64 !== undefined) report.outB64 = options.outB64;
+    out.out(JSON.stringify(report, null, 2));
+    return;
+  }
+  out.print("standing: sealerId %s epoch %s", result.sealerId, String(result.epoch));
+  out.print("voucher: ok — verifies against the known sealer-voucher key");
+  out.print("horizon: mmr %d..%d", result.mmrStart, result.mmrEnd);
+  out.print("submit: ok");
+  if (options.outB64 !== undefined) {
+    out.print("wrote certificate (base64) to %s", options.outB64);
+  }
+}
+
+export async function runDelegate(
+  out: Out,
+  options: DelegateOptions,
+  deps: DelegateRunDeps = {},
+): Promise<void> {
+  // 1. Root key material (K(L)).
+  let rootPem: string;
+  try {
+    rootPem = await readPemFile(options.signWith, "--sign-with");
+  } catch (err) {
+    reportError(out, options, {
+      command: "delegate",
+      error: "key_read_failed",
+      message: err instanceof Error ? err.message : String(err),
+    });
+    return;
+  }
+
+  // 2. Run the public delegation flow (voucher verify is mandatory inside).
+  try {
+    const result = await runDelegateFlow(
+      {
+        coordinatorUrl: options.coordinatorUrl,
+        logId: options.logId,
+        rootPem,
+        knownSealerKey: options.knownSealerKey,
+        horizonMmrEnd: options.horizonMmrEnd,
+        ttlSeconds: options.ttlSeconds,
+      },
+      deps,
+    );
+    await reportResult(out, options, result);
+  } catch (err) {
+    if (err instanceof DelegateFlowError) {
+      const report: DelegateErrorReport = {
+        command: "delegate",
+        error: err.code ?? "delegation_failed",
+        message: err.message,
+      };
+      if (err.httpStatus !== undefined) report.httpStatus = err.httpStatus;
+      reportError(out, options, report);
+      return;
+    }
+    throw err;
+  }
+}

package/src/main/deploy.ts

@@ -0,0 +1,273 @@
+import type { Out } from "@forestrie/cli-kit/reporting";
+import { writeOutputFile } from "../lib/fsio.js";
+import { getAddress, type Hex } from "viem";
+import type { BootstrapAlg, DeployOptions } from "../options/deploy.js";
+import {
+  loadImutableArtifact,
+  type ImutableDeployArtifact,
+} from "../lib/deploy-artifact.js";
+import {
+  resolveDeployBootstrapKey,
+  type ResolvedDeployBootstrap,
+} from "../lib/deploy-bootstrap.js";
+import {
+  DeployFlowError,
+  runDeployFlow,
+  type DeployFlowResult,
+  type DeployRpc,
+} from "../lib/deploy-flow.js";
+import { createDeployRpc } from "../lib/deploy-rpc.js";
+import { errorMessage } from "../lib/sign-statement-key.js";
+
+/**
+ * FOR-341..347 sibling — FOR-340: deploy a univocity instance.
+ *
+ * ES256 paved path (forestrie-demo-01.md §R1): resolve/generate the
+ * ES256 bootstrap key, fetch + verify the univocity release manifest,
+ * build the ImutableUnivocity creation tx via `@forestrie/deploy-core`,
+ * submit it directly from the funded deployer EOA, and write the
+ * deployment record. KS256 (Safe / ERC-1271) is a pre-provisioned aside
+ * — no live Safe flow is implemented here.
+ */
+
+/**
+ * Deployment record (`--out` / stdout). The demo contract is the first
+ * four fields — `jq -r .imutableUnivocity` / `.genesisLogId` must keep
+ * working; the rest is provenance.
+ */
+export type DeploymentRecord = {
+  kind: "imutable-deployment";
+  version: 1;
+  imutableUnivocity: string;
+  genesisLogId: string;
+  bootstrapAlg: BootstrapAlg;
+  chainId: number;
+  from: string;
+  txHash: string;
+  releaseId: string;
+};
+
+/** `--json` success shape. */
+export type DeployReport = DeploymentRecord & {
+  command: "deploy";
+  status: "deployed";
+  /** Present when the bootstrap key was generated. */
+  bootstrapPemOut?: string;
+  /** Present when `--out` was given. */
+  out?: string;
+};
+
+/** `--json` failure shape. */
+export type DeployErrorReport = {
+  error:
+    | "bootstrap_alg_unsupported"
+    | "bootstrap_key_failed"
+    | "manifest_failed"
+    | "owner_mismatch"
+    | "network_failed"
+    | "deploy_failed";
+  command: "deploy";
+  message: string;
+  detail?: string;
+  txHash?: string;
+};
+
+/** Test seam: effects injected by the deploy tests (real by default). */
+export type DeployRunDeps = {
+  resolveBootstrap?: typeof resolveDeployBootstrapKey;
+  loadArtifact?: typeof loadImutableArtifact;
+  createRpc?: (rpcUrl: string, deployerKey: Hex) => DeployRpc;
+};
+
+const FLOW_ERROR_CODES = {
+  network: "network_failed",
+  deploy: "deploy_failed",
+} as const;
+
+function reportError(
+  out: Out,
+  options: DeployOptions,
+  report: DeployErrorReport,
+): void {
+  if (options.json) {
+    out.out(JSON.stringify(report, null, 2));
+  } else {
+    out.warn("forestrie deploy: %s", report.message);
+    if (report.detail !== undefined && !report.message.includes(report.detail)) {
+      out.warn("  detail: %s", report.detail);
+    }
+    if (report.txHash !== undefined) {
+      out.warn("  txHash: %s", report.txHash);
+    }
+  }
+  process.exitCode = 1;
+}
+
+function deploymentRecord(
+  options: DeployOptions,
+  artifact: ImutableDeployArtifact,
+  result: DeployFlowResult,
+): DeploymentRecord {
+  return {
+    kind: "imutable-deployment",
+    version: 1,
+    imutableUnivocity: result.imutableUnivocity,
+    genesisLogId: result.genesisLogId,
+    bootstrapAlg: options.bootstrapAlg,
+    chainId: result.chainId,
+    from: result.from,
+    txHash: result.txHash,
+    releaseId: artifact.releaseId,
+  };
+}
+
+async function reportDeployed(
+  out: Out,
+  options: DeployOptions,
+  bootstrap: ResolvedDeployBootstrap,
+  record: DeploymentRecord,
+): Promise<void> {
+  const json = JSON.stringify(record, null, 2);
+  if (options.out !== undefined) {
+    await writeOutputFile(options.out, `${json}\n`);
+  }
+  if (options.json) {
+    const report: DeployReport = {
+      command: "deploy",
+      status: "deployed",
+      ...record,
+    };
+    if (bootstrap.pemOut !== undefined) report.bootstrapPemOut = bootstrap.pemOut;
+    if (options.out !== undefined) report.out = options.out;
+    out.out(JSON.stringify(report, null, 2));
+    return;
+  }
+  if (bootstrap.pemOut !== undefined) {
+    out.print("wrote ES256 bootstrap PEM to %s", bootstrap.pemOut);
+  }
+  if (options.out !== undefined) {
+    // Record went to --out; keep stdout clean, summarize on stderr.
+    out.print("ImutableUnivocity deployed at: %s", record.imutableUnivocity);
+    out.print("genesisLogId: %s", record.genesisLogId);
+    out.print("chainId: %d  txHash: %s", record.chainId, record.txHash);
+    out.print("wrote deployment record to %s", options.out);
+  } else {
+    // No --out: the record itself is the pipeable product (demo jq's it).
+    out.out("%s", json);
+  }
+}
+
+export async function runDeploy(
+  out: Out,
+  options: DeployOptions,
+  deps: DeployRunDeps = {},
+): Promise<void> {
+  if (options.bootstrapAlg !== "es256") {
+    reportError(out, options, {
+      error: "bootstrap_alg_unsupported",
+      command: "deploy",
+      message:
+        "ks256 (Safe / ERC-1271) is the pre-provisioned aside — forestrie deploy implements the ES256 paved path only; use the univocity-tools deployer Safe flow",
+    });
+    return;
+  }
+
+  const resolveBootstrap = deps.resolveBootstrap ?? resolveDeployBootstrapKey;
+  const loadArtifact = deps.loadArtifact ?? loadImutableArtifact;
+  const createRpc = deps.createRpc ?? createDeployRpc;
+
+  let bootstrap: ResolvedDeployBootstrap;
+  try {
+    bootstrap = await resolveBootstrap({
+      generate: options.bootstrapEs256Generate,
+      pemOut: options.bootstrapEs256PemOut,
+      pemPath: options.bootstrapEs256Pem,
+    });
+  } catch (err) {
+    reportError(out, options, {
+      error: "bootstrap_key_failed",
+      command: "deploy",
+      message: errorMessage(err),
+    });
+    return;
+  }
+
+  let artifact: ImutableDeployArtifact;
+  try {
+    artifact = await loadArtifact({
+      manifestPath: options.releaseManifest,
+      releaseTag: options.releaseTag,
+    });
+  } catch (err) {
+    reportError(out, options, {
+      error: "manifest_failed",
+      command: "deploy",
+      message: `cannot load a verified deploy manifest: ${errorMessage(err)}`,
+    });
+    return;
+  }
+
+  const rpc = createRpc(options.rpcUrl, options.deployerKey);
+
+  if (options.ownerAddress !== undefined) {
+    let owner: string;
+    try {
+      owner = getAddress(options.ownerAddress);
+    } catch {
+      reportError(out, options, {
+        error: "owner_mismatch",
+        command: "deploy",
+        message: `--owner-address is not a valid address: ${options.ownerAddress}`,
+      });
+      return;
+    }
+    if (owner !== rpc.from) {
+      reportError(out, options, {
+        error: "owner_mismatch",
+        command: "deploy",
+        message: `--owner-address ${owner} does not match the --deployer-key account ${rpc.from}`,
+      });
+      return;
+    }
+  }
+
+  out.log(
+    "deploying ImutableUnivocity (release %s) from %s via %s",
+    artifact.releaseId,
+    rpc.from,
+    options.rpcUrl,
+  );
+
+  let result: DeployFlowResult;
+  try {
+    result = await runDeployFlow(rpc, {
+      creationBytecode: artifact.creationBytecode,
+      bootstrap: bootstrap.bootstrap,
+    });
+  } catch (err) {
+    if (err instanceof DeployFlowError) {
+      const report: DeployErrorReport = {
+        error: FLOW_ERROR_CODES[err.stage],
+        command: "deploy",
+        message: err.message,
+      };
+      if (err.detail !== undefined) report.detail = err.detail;
+      if (err.txHash !== undefined) report.txHash = err.txHash;
+      reportError(out, options, report);
+      return;
+    }
+    reportError(out, options, {
+      error: "deploy_failed",
+      command: "deploy",
+      message: errorMessage(err),
+    });
+    return;
+  }
+
+  await reportDeployed(
+    out,
+    options,
+    bootstrap,
+    deploymentRecord(options, artifact, result),
+  );
+}

package/src/main/fetch-accumulator.ts

@@ -0,0 +1,181 @@
+import { writeFileSync } from "node:fs";
+import type { Out } from "@forestrie/cli-kit/reporting";
+import { ethRpc, hexAddressToBytes, normalizeHexAddress } from "@forestrie/chain-rpc";
+import type { FetchAccumulatorOptions } from "../options/fetch-accumulator.js";
+import { decodeLogStateResult, toContractLogId } from "../lib/verify-anchored.js";
+import {
+  encodeKnownAccumulator,
+  type KnownAccumulator,
+} from "../lib/verify-known-accumulator.js";
+import {
+  fetchPublishedCheckpoints,
+  selectPublishedAtBlock,
+} from "../lib/verify-eventscan.js";
+
+/** Selector for `logState(bytes32)` (mirrors verify-anchored). */
+const LOG_STATE_SELECTOR = "0xeecac1b7";
+
+/** `--json` success shape on stdout — stable for demo scripting. */
+export type FetchAccumulatorReport = {
+  command: "fetch-accumulator";
+  chainId: string;
+  univocity: string;
+  logId: string;
+  anchoredSize: string;
+  peakCount: number;
+  blockNumber: string;
+  blockHash: string;
+  out: string;
+};
+
+export type FetchAccumulatorErrorReport = {
+  error: "fetch_accumulator_failed";
+  command: "fetch-accumulator";
+  message: string;
+};
+
+function hexToBigint(v: unknown, what: string): bigint {
+  if (typeof v !== "string" || !/^0x[0-9a-fA-F]+$/.test(v)) {
+    throw new Error(`${what}: expected a hex quantity, got ${String(v)}`);
+  }
+  return BigInt(v);
+}
+
+function hexToBytes32(v: unknown, what: string): Uint8Array {
+  if (typeof v !== "string" || !/^0x[0-9a-fA-F]{64}$/.test(v)) {
+    throw new Error(`${what}: expected a 32-byte hex value, got ${String(v)}`);
+  }
+  const hex = v.slice(2);
+  const out = new Uint8Array(32);
+  for (let i = 0; i < 32; i++) {
+    out[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}
+
+/**
+ * Read `logState(logId)` pinned to a specific block: fetch the latest block
+ * header first, then `eth_call` AT that block number, so the snapshot's
+ * `(blockNumber, blockHash)` binding is exact — the falsifiability handle
+ * that lets anyone re-run the read and confirm or disprove the snapshot.
+ */
+export async function runFetchAccumulator(
+  out: Out,
+  options: FetchAccumulatorOptions,
+): Promise<void> {
+  try {
+    const address = normalizeHexAddress(options.univocity);
+    if (address === null) {
+      throw new Error(
+        `--univocity is not a valid address: '${options.univocity}'`,
+      );
+    }
+    const contractLogId = toContractLogId(options.logId);
+
+    const chainId = hexToBigint(
+      await ethRpc(options.rpcUrl, "eth_chainId", []),
+      "eth_chainId",
+    );
+
+    let state: { size: bigint; accumulator: Uint8Array[] };
+    let blockNumber: bigint;
+    let blockHash: Uint8Array;
+    if (options.atBlock !== undefined) {
+      // FOR-368: historical snapshot from the CheckpointPublished record —
+      // events survive where contract state does not, so no archive node
+      // is needed. The snapshot binds to the block the anchor landed in.
+      const published = await fetchPublishedCheckpoints({
+        univocity: options.univocity,
+        logId: options.logId,
+        rpcUrl: options.rpcUrl,
+        fromBlock: options.fromBlock,
+      });
+      const chosen = selectPublishedAtBlock(published, options.atBlock);
+      if (chosen === null) {
+        throw new Error(
+          `no CheckpointPublished at or before block ${options.atBlock} for log ${options.logId}` +
+            (published.length > 0
+              ? ` (earliest anchor is block ${published[0]!.blockNumber})`
+              : " (no anchors found in the scanned range)"),
+        );
+      }
+      state = { size: chosen.size, accumulator: chosen.accumulator };
+      blockNumber = chosen.blockNumber;
+      blockHash = hexToBytes32(chosen.blockHash, "event block hash");
+    } else {
+      const block = (await ethRpc(options.rpcUrl, "eth_getBlockByNumber", [
+        "latest",
+        false,
+      ])) as { number?: unknown; hash?: unknown } | null;
+      if (block === null || typeof block !== "object") {
+        throw new Error("eth_getBlockByNumber returned no block");
+      }
+      blockNumber = hexToBigint(block.number, "block number");
+      blockHash = hexToBytes32(block.hash, "block hash");
+
+      const data = LOG_STATE_SELECTOR + contractLogId.slice(2);
+      const result = await ethRpc(options.rpcUrl, "eth_call", [
+        { to: `0x${address}`, data },
+        `0x${blockNumber.toString(16)}`,
+      ]);
+      if (typeof result !== "string" || result === "0x") {
+        throw new Error(
+          `logState eth_call returned no data for log ${options.logId} at ${options.univocity}`,
+        );
+      }
+      state = decodeLogStateResult(result);
+    }
+
+    const snapshot: KnownAccumulator = {
+      version: 1,
+      chainId,
+      univocity: hexAddressToBytes(`0x${address}`),
+      logId: hexToBytes32(contractLogId, "log id"),
+      size: state.size,
+      accumulator: state.accumulator,
+      blockNumber,
+      blockHash,
+    };
+    writeFileSync(options.out, encodeKnownAccumulator(snapshot));
+
+    if (options.json) {
+      const report: FetchAccumulatorReport = {
+        command: "fetch-accumulator",
+        chainId: chainId.toString(),
+        univocity: `0x${address}`,
+        logId: contractLogId,
+        anchoredSize: state.size.toString(),
+        peakCount: state.accumulator.length,
+        blockNumber: blockNumber.toString(),
+        blockHash: `0x${Array.from(blockHash, (b) =>
+          b.toString(16).padStart(2, "0"),
+        ).join("")}`,
+        out: options.out,
+      };
+      out.out(JSON.stringify(report, null, 2));
+    } else {
+      out.print(
+        "fetch-accumulator: read logState at block %s (chain %s)",
+        blockNumber.toString(),
+        chainId.toString(),
+      );
+      out.out(
+        `wrote known accumulator: ${options.out} (anchored size ${state.size}, ${state.accumulator.length} peaks, block ${blockNumber})`,
+      );
+    }
+    process.exitCode = 0;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (options.json) {
+      const report: FetchAccumulatorErrorReport = {
+        error: "fetch_accumulator_failed",
+        command: "fetch-accumulator",
+        message,
+      };
+      out.out(JSON.stringify(report, null, 2));
+    } else {
+      out.warn("forestrie fetch-accumulator: %s", message);
+    }
+    process.exitCode = 1;
+  }
+}

package/src/main/not-implemented.ts

@@ -0,0 +1,43 @@
+import type { Out } from "@forestrie/cli-kit/reporting";
+import type { ForestrieCommonOptions } from "../options/common.js";
+
+/** Structured not-implemented report — the `--json` shape is a contract. */
+export type NotImplementedReport = {
+  error: "not_implemented";
+  command: string;
+  issue: string;
+  message: string;
+  options: Record<string, unknown>;
+};
+
+/**
+ * Every subcommand stub terminates here: parsing succeeded (the arg
+ * surface is real), the behaviour ships under the referenced FOR-34x
+ * issue. Exits non-zero via `process.exitCode` so citty does not wrap
+ * the message in its own error formatting.
+ *
+ * Human mode: one line on stderr. `--json`: the report on stdout.
+ */
+export function reportNotImplemented(
+  out: Out,
+  common: ForestrieCommonOptions,
+  command: string,
+  issue: string,
+  options: Record<string, unknown>,
+): void {
+  const message = `forestrie ${command}: not implemented yet — ${issue}`;
+  if (common.json) {
+    const report: NotImplementedReport = {
+      error: "not_implemented",
+      command,
+      issue,
+      message,
+      options,
+    };
+    out.out(JSON.stringify(report, null, 2));
+  } else {
+    out.warn(message);
+    out.log("parsed options: %s", JSON.stringify(options));
+  }
+  process.exitCode = 1;
+}