@europeum-ebsi/cli 0.0.0 → 1.0.0-rc.0

package/src/commands/ledger.ts

@@ -0,0 +1,777 @@
+import type { components } from "@europeum-ebsi/api-contract/types";
+
+import { readFileSync } from "node:fs";
+
+import type { CliConfig } from "../config/config.ts";
+import type { WalletDetails } from "../crypto/wallet.ts";
+import type { GasOverrides } from "../ledger/write.ts";
+import type { CommandDescriptor } from "./registry.ts";
+
+import { getClient, unwrap } from "../api/fetch.ts";
+import { validateScope } from "../auth/presentation.ts";
+import { getAccessToken } from "../auth/token.ts";
+import { readFromRegistry } from "../ledger/read.ts";
+import {
+  defaultScopeFor,
+  deriveScopeForRegistries,
+  REGISTRIES,
+  REGISTRY_NAMES,
+} from "../ledger/registries.ts";
+import { signWriteBatch, writeToRegistry } from "../ledger/write.ts";
+import { requiredArg } from "./shared/args.ts";
+import { resolveWallet, WALLET_KEY_OPTIONS } from "./shared/wallet-opts.ts";
+
+/**
+ * One entry of a generic `ledger batch` JSON-RPC request, before the
+ * `jsonrpc` field is stamped on. `id` is intentionally optional — an entry
+ * without one is a JSON-RPC notification and gets no response entry, matching
+ * the generated `components["schemas"]["JsonRpcPayload"]["id"]` type, which
+ * is likewise optional.
+ */
+interface JsonRpcBatchEntry {
+  id?: number | string;
+  jsonrpc: "2.0";
+  method: string;
+  params?: JsonRpcParams;
+}
+
+type JsonRpcBatchPayload = components["schemas"]["JsonRpcBatchPayload"];
+type JsonRpcParams = components["schemas"]["JsonRpcPayload"]["params"];
+
+/**
+ * One entry of a `ledger write-batch` file: a registry function call, the
+ * same shape `ledger write` takes as separate positional args.
+ */
+interface WriteBatchFileEntry {
+  args: unknown[];
+  function: string;
+  registry: string;
+  to?: string;
+}
+
+/**
+ * Validates and normalises one raw JSON value from a `ledger batch` source
+ * file into a well-formed JSON-RPC request, stamping `jsonrpc: "2.0"`.
+ */
+function normalizeBatchEntry(entry: unknown, index: number): JsonRpcBatchEntry {
+  const position = `Batch entry #${(index + 1).toString()}`;
+  if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+    throw new Error(
+      `${position} must be a JSON object with a "method" field (e.g. {"method": "eth_blockNumber"}).`,
+    );
+  }
+  const { id, method, params } = entry as Record<string, unknown>;
+  if (typeof method !== "string" || method === "") {
+    throw new Error(`${position} is missing a "method" string.`);
+  }
+  if (params !== undefined && !Array.isArray(params)) {
+    throw new Error(`${position}: "params" must be a JSON array when present.`);
+  }
+  if (id !== undefined && typeof id !== "number" && typeof id !== "string") {
+    throw new Error(
+      `${position}: "id" must be a number or string when present.`,
+    );
+  }
+
+  return {
+    ...(id !== undefined && { id: id }),
+    jsonrpc: "2.0",
+    method,
+    ...(params !== undefined && { params: params as JsonRpcParams }),
+  };
+}
+
+/**
+ * Parses one `--gas-limit`/`--gas-price` value (decimal or `0x`-prefixed
+ * hex, both accepted by `BigInt()`), throwing a CLI-style error — naming the
+ * flag — instead of a raw `SyntaxError`/`RangeError` on a bad value.
+ */
+function parseGasBigInt(raw: string, flag: string): bigint {
+  try {
+    return BigInt(raw);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Invalid ${flag} value "${raw}": ${message}`, {
+      cause: error,
+    });
+  }
+}
+
+/**
+ * Parses the shared `--gas-limit <value>` / `--gas-price <value>` options
+ * (decimal or `0x`-prefixed hex, both accepted by `BigInt()`) into a
+ * `GasOverrides`. Both are advanced escape hatches — by default `ledger
+ * write`/`ledger write-batch` derive gas dynamically from the node (see
+ * `../ledger/write.ts`). Returns `undefined` when neither is set, so callers
+ * can pass the result straight through as `gas`.
+ */
+function parseGasOverrides(
+  opts: Record<string, string>,
+): GasOverrides | undefined {
+  const gasLimitRaw = opts["gasLimit"];
+  const gasPriceRaw = opts["gasPrice"];
+  if (gasLimitRaw === undefined && gasPriceRaw === undefined) {
+    return undefined;
+  }
+
+  return {
+    ...(gasLimitRaw !== undefined && {
+      gasLimit: parseGasBigInt(gasLimitRaw, "--gas-limit"),
+    }),
+    ...(gasPriceRaw !== undefined && {
+      gasPrice: parseGasBigInt(gasPriceRaw, "--gas-price"),
+    }),
+  };
+}
+
+/**
+ * Parses a JSON-array CLI argument (a registry function's args, or a raw
+ * JSON-RPC params list), throwing a CLI-style error — naming the argument —
+ * rather than a raw SyntaxError, when it isn't valid JSON or isn't an array.
+ */
+function parseJsonArray(raw: string, argName: string): unknown[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    /* v8 ignore next -- JSON.parse only ever throws a real Error/SyntaxError */
+    const message = error instanceof Error ? error.message : "parse error";
+    throw new Error(`Invalid ${argName} JSON: ${message}`, { cause: error });
+  }
+  if (!Array.isArray(parsed)) {
+    throw new TypeError(`${argName} must be a JSON array`);
+  }
+  return parsed;
+}
+
+/**
+ * Parses and validates a `ledger write-batch` file's JSON contents.
+ */
+function parseWriteBatchFile(raw: string): WriteBatchFileEntry[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    /* v8 ignore next -- JSON.parse only ever throws a real Error/SyntaxError */
+    const message = error instanceof Error ? error.message : "parse error";
+    throw new Error(`Invalid JSON: ${message}`, { cause: error });
+  }
+  if (!Array.isArray(parsed) || parsed.length === 0) {
+    throw new Error(
+      "Batch file must contain a non-empty JSON array of write entries " +
+        '(each: {"registry", "function", "args", "to"?}).',
+    );
+  }
+
+  return parsed.map((entry, index) => {
+    const position = `Entry #${(index + 1).toString()}`;
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+      throw new Error(
+        `${position} must be a JSON object with "registry", "function", and "args".`,
+      );
+    }
+    const {
+      args,
+      function: fn,
+      registry,
+      to,
+    } = entry as Record<string, unknown>;
+    if (typeof registry !== "string" || registry === "") {
+      throw new Error(`${position} is missing a "registry" string.`);
+    }
+    if (typeof fn !== "string" || fn === "") {
+      throw new Error(`${position} is missing a "function" string.`);
+    }
+    if (!Array.isArray(args)) {
+      throw new TypeError(`${position}: "args" must be a JSON array.`);
+    }
+    if (to !== undefined && typeof to !== "string") {
+      throw new Error(`${position}: "to" must be a string when present.`);
+    }
+    return { args, function: fn, registry, ...(to !== undefined && { to }) };
+  });
+}
+
+/**
+ * Reads all of stdin and returns it as a UTF-8 string.
+ */
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk as Buffer);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+/**
+ * Resolves the Bearer token for `ledger write`/`ledger write-batch`: either
+ * mints a fresh one via `--auto-token` (validating `--scope` up front so an
+ * illegal combination fails locally with a clear message instead of a
+ * generic API error) or reads a pre-obtained one from `--token`/config.
+ */
+async function resolveWriteToken(
+  opts: Record<string, string>,
+  config: CliConfig,
+  wallet: WalletDetails,
+  defaultScope: string,
+): Promise<string> {
+  if (opts["autoToken"]) {
+    const scope = opts["scope"] ?? defaultScope;
+    validateScope(scope);
+    const vcFile = opts["vc"];
+    const vcJwt = vcFile ? readFileSync(vcFile, "utf8").trim() : undefined;
+    return getAccessToken({
+      config,
+      scope,
+      wallet,
+      ...(vcJwt !== undefined && { vcJwt }),
+    });
+  }
+
+  const resolvedToken = opts["token"] ?? config.token;
+  if (!resolvedToken) {
+    throw new Error(
+      "No access token found. " +
+        "Use --auto-token to mint one via the VP flow, " +
+        "or provide --token <jwt> / EBSI_ACCESS_TOKEN / `ebsi config set token <jwt>`.",
+    );
+  }
+  return resolvedToken;
+}
+
+export const ledgerCommands: CommandDescriptor[] = [
+  {
+    args: [
+      {
+        description:
+          "JSON-RPC method to invoke (e.g. eth_getBlockByNumber, eth_sendRawTransaction)",
+        example: "eth_getBlockByNumber",
+        name: "method",
+        required: true,
+      },
+      {
+        description:
+          "JSON array of parameters encoded as a string (e.g. '[\"latest\", false]'). Omit or pass '[]' for methods with no params.",
+        example: '["latest", false]',
+        name: "params",
+        required: false,
+      },
+    ],
+    group: "Ledger",
+    async handler(args, opts, config) {
+      const method = requiredArg(args, "method");
+      const rawParams = args["params"];
+
+      let params: NonNullable<JsonRpcParams> = [];
+      if (rawParams !== undefined && rawParams !== "") {
+        try {
+          const parsed: unknown = JSON.parse(rawParams);
+          if (!Array.isArray(parsed)) {
+            throw new TypeError("params must be a JSON array");
+          }
+          params = parsed as NonNullable<JsonRpcParams>;
+        } catch (error) {
+          /* v8 ignore next -- JSON.parse only ever throws a real Error/SyntaxError */
+          const message =
+            error instanceof Error ? error.message : "parse error";
+          throw new Error(`Invalid params JSON: ${message}`, { cause: error });
+        }
+      }
+
+      const id = Number(opts["id"] ?? 1);
+      const client = getClient(config);
+      const result = await client.POST("/ledger", {
+        body: { id, jsonrpc: "2.0", method, params },
+      });
+      return unwrap(result);
+    },
+    id: "ledger.call",
+    options: [
+      {
+        defaultValue: "1",
+        description: "JSON-RPC request id (default: 1)",
+        flags: "--id <n>",
+      },
+    ],
+    segments: ["ledger", "call"],
+    summary:
+      "Send a JSON-RPC request to the Besu node via POST /ledger. " +
+      "Read methods (eth_getBlock*, eth_getTransaction*, ...) are forwarded anonymously. " +
+      "Write methods (eth_sendRawTransaction) require a Bearer token via --token, " +
+      "EBSI_ACCESS_TOKEN env var, or `ebsi config set token <jwt>`. " +
+      "The caller is responsible for building and signing the raw transaction.",
+  },
+
+  {
+    args: [
+      {
+        description:
+          "Block number (hex, e.g. 0x1e240) or tag (latest, earliest, pending)",
+        example: "latest",
+        name: "blockNumberOrTag",
+        required: true,
+      },
+    ],
+    group: "Ledger",
+    async handler(args, _opts, config) {
+      const tag = requiredArg(args, "blockNumberOrTag", "latest");
+      const client = getClient(config);
+      const result = await client.POST("/ledger", {
+        body: {
+          id: 1,
+          jsonrpc: "2.0",
+          method: "eth_getBlockByNumber",
+          params: [tag, false],
+        },
+      });
+      return unwrap(result);
+    },
+    id: "ledger.block",
+    options: [],
+    segments: ["ledger", "block"],
+    summary:
+      "Get a block by number or tag (eth_getBlockByNumber). Shorthand for `ledger call eth_getBlockByNumber`.",
+  },
+
+  {
+    args: [
+      {
+        description: "Transaction hash (0x-prefixed hex)",
+        example:
+          "0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b",
+        name: "hash",
+        required: true,
+      },
+    ],
+    group: "Ledger",
+    async handler(args, _opts, config) {
+      const hash = requiredArg(args, "hash");
+      const client = getClient(config);
+      const result = await client.POST("/ledger", {
+        body: {
+          id: 1,
+          jsonrpc: "2.0",
+          method: "eth_getTransactionByHash",
+          params: [hash],
+        },
+      });
+      return unwrap(result);
+    },
+    id: "ledger.tx",
+    options: [],
+    segments: ["ledger", "tx"],
+    summary:
+      "Get a transaction by hash (eth_getTransactionByHash). Shorthand for `ledger call eth_getTransactionByHash`.",
+  },
+
+  {
+    args: [
+      {
+        description: "Registry name: " + REGISTRY_NAMES.join(", "),
+        example: "did-registry",
+        name: "registry",
+        required: true,
+      },
+      {
+        description:
+          "Smart-contract function to call (e.g. insertDidDocument, addIssuer)",
+        example: "insertDidDocument",
+        name: "function",
+        required: true,
+      },
+      {
+        description:
+          'Function arguments as a JSON array string (e.g. \'["did:ebsi:z123", "..."]\'). ' +
+          "Types must match the contract ABI exactly.",
+        example:
+          '["did:ebsi:z123", "{}", "thumbprint", "0xpubkey", true, 0, 9999999999]',
+        name: "args",
+        required: true,
+      },
+    ],
+    group: "Ledger",
+    async handler(args, opts, config) {
+      const registryName = requiredArg(args, "registry");
+      const functionName = requiredArg(args, "function");
+      const argsRaw = requiredArg(args, "args");
+
+      const registry = REGISTRIES[registryName];
+      if (!registry) {
+        throw new Error(
+          `Unknown registry "${registryName}". Known registries: ${REGISTRY_NAMES.join(", ")}`,
+        );
+      }
+
+      const functionArgs = parseJsonArray(argsRaw, "args");
+
+      // Resolve contract address: --to → env var → error
+      const toOpt = opts["to"];
+      const contractAddress = toOpt ?? process.env[registry.addressEnvKey];
+      if (!contractAddress) {
+        throw new Error(
+          `No contract address for "${registryName}". ` +
+            `Provide --to <address> or set ${registry.addressEnvKey}.`,
+        );
+      }
+
+      const wallet = await resolveWallet(opts, config);
+
+      // Resolve access token. With --auto-token and no explicit --scope, the
+      // default scope targets the same instance being written to
+      // (`contractAddress`), so the minted token is authorised against
+      // exactly that beacon-proxy instance.
+      const token = await resolveWriteToken(
+        opts,
+        config,
+        wallet,
+        `${defaultScopeFor(registryName, functionName, registry)}:${contractAddress}`,
+      );
+
+      const gas = parseGasOverrides(opts);
+      const receipt = await writeToRegistry({
+        config,
+        contractAddress,
+        functionArgs,
+        functionName,
+        ...(gas !== undefined && { gas }),
+        registry,
+        token,
+        wallet,
+      });
+
+      return receipt;
+    },
+    id: "ledger.write",
+    options: [
+      {
+        description:
+          "Contract address (0x-prefixed). If omitted, read from the corresponding env var " +
+          "(e.g. DID_REGISTRY_CONTRACT_ADDRESS for did-registry).",
+        flags: "--to <address>",
+      },
+      {
+        description:
+          "Obtain a fresh access token automatically using the VP flow " +
+          "before submitting the transaction. Uses the registry/function's default scope " +
+          '(e.g. "did-registry:invite" for did-registry insertDidDocument, "track-and-trace:authorise" for ' +
+          'track-and-trace authoriseDid, "track-and-trace:create" for track-and-trace createDocument/' +
+          "commitCreateDocument, and each registry's plain write scope for every other " +
+          "function), targeted at the resolved --to contract instance, unless --scope " +
+          "overrides it.",
+        flags: "--auto-token",
+      },
+      {
+        description:
+          "EBSI scope to use when requesting a token with --auto-token " +
+          '(e.g. "did-registry:write", "issuers-registry:invite", or "track-and-trace:write:0x61c3..." to target a specific ' +
+          "instance). Defaults to the registry/function's default scope targeted at --to.",
+        flags: "--scope <scope>",
+      },
+      {
+        description:
+          "Path to a VC JWT file. Required for VC-required scopes " +
+          "(did-registry:invite, ledger:invoke, issuers-registry:invite, track-and-trace:authorise) when using --auto-token.",
+        flags: "--vc <file>",
+      },
+      ...WALLET_KEY_OPTIONS,
+      {
+        description: "EBSI DID to use. Overrides config/env.",
+        flags: "--did <did>",
+      },
+      {
+        description:
+          "Advanced: manual gas limit (decimal or 0x-prefixed hex), overriding the " +
+          "eth_estimateGas result. By default the gas limit is estimated dynamically from the node.",
+        flags: "--gas-limit <value>",
+      },
+      {
+        description:
+          "Advanced: manual gas price (decimal or 0x-prefixed hex), forcing a legacy " +
+          "transaction. By default fees are derived dynamically from the node (EIP-1559 when supported).",
+        flags: "--gas-price <value>",
+      },
+    ],
+    segments: ["ledger", "write"],
+    summary:
+      "ABI-encode a registry function call, sign an Ethereum transaction, and submit it " +
+      "via POST /ledger. " +
+      "Requires a private key and an access token (or --auto-token to mint one inline). " +
+      "Contract address comes from --to or the corresponding env var " +
+      "(e.g. DID_REGISTRY_CONTRACT_ADDRESS). " +
+      "Known registries: " +
+      REGISTRY_NAMES.join(", ") +
+      ".",
+  },
+
+  {
+    args: [
+      {
+        description: "Registry name: " + REGISTRY_NAMES.join(", "),
+        example: "timestamp",
+        name: "registry",
+        required: true,
+      },
+      {
+        description:
+          "Smart-contract view/pure function to call (e.g. getTimestamp, computeTimestampCommitment)",
+        example: "computeTimestampCommitment",
+        name: "function",
+        required: true,
+      },
+      {
+        description:
+          "Function arguments as a JSON array string (e.g. '[\"0x1234\"]'). " +
+          "Types must match the contract ABI exactly.",
+        example: '["0xCommitter", [1], ["0xhash"], [], "0xsalt"]',
+        name: "args",
+        required: true,
+      },
+    ],
+    group: "Ledger",
+    async handler(args, opts, config) {
+      const registryName = requiredArg(args, "registry");
+      const functionName = requiredArg(args, "function");
+      const functionArgs = parseJsonArray(requiredArg(args, "args"), "args");
+
+      const registry = REGISTRIES[registryName];
+      if (!registry) {
+        throw new Error(
+          `Unknown registry "${registryName}". Known registries: ${REGISTRY_NAMES.join(", ")}`,
+        );
+      }
+
+      // Resolve contract address: --to → env var → error
+      const toOpt = opts["to"];
+      const contractAddress = toOpt ?? process.env[registry.addressEnvKey];
+      if (!contractAddress) {
+        throw new Error(
+          `No contract address for "${registryName}". ` +
+            `Provide --to <address> or set ${registry.addressEnvKey}.`,
+        );
+      }
+
+      return readFromRegistry({
+        config,
+        contractAddress,
+        functionArgs,
+        functionName,
+        registry,
+      });
+    },
+    id: "ledger.read",
+    options: [
+      {
+        description:
+          "Contract address (0x-prefixed). If omitted, read from the corresponding env var " +
+          "(e.g. TIMESTAMP_CONTRACT_ADDRESS for timestamp).",
+        flags: "--to <address>",
+      },
+    ],
+    segments: ["ledger", "read"],
+    summary:
+      "ABI-encode a registry view/pure function call and resolve it via eth_call — " +
+      "the read-only counterpart to `ledger write`. No wallet or token needed, since " +
+      "eth_call is served anonymously. Returns the function's outputs as an array, " +
+      "in declaration order. Contract address comes from --to or the corresponding " +
+      "env var. Known registries: " +
+      REGISTRY_NAMES.join(", ") +
+      ".",
+  },
+
+  {
+    args: [
+      {
+        description:
+          "Path to a JSON file containing a JSON array of JSON-RPC requests, or '-' to read from stdin. " +
+          'Each entry needs a "method" field; "params" defaults to [] and "id" may be omitted to send ' +
+          "a notification (no response entry for that request).",
+        example: "./batch.json",
+        name: "source",
+        required: true,
+      },
+    ],
+    group: "Ledger",
+    async handler(args, _opts, config) {
+      const source = requiredArg(args, "source");
+      const raw =
+        source === "-" ? await readStdin() : readFileSync(source, "utf8");
+
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(raw);
+      } catch (error) {
+        /* v8 ignore next -- JSON.parse only ever throws a real Error/SyntaxError */
+        const message = error instanceof Error ? error.message : "parse error";
+        throw new Error(`Invalid JSON in "${source}": ${message}`, {
+          cause: error,
+        });
+      }
+      if (!Array.isArray(parsed) || parsed.length === 0) {
+        throw new Error(
+          "Batch source must contain a non-empty JSON array of JSON-RPC requests.",
+        );
+      }
+
+      const batch = parsed.map((entry, index) =>
+        normalizeBatchEntry(entry, index),
+      );
+
+      const client = getClient(config);
+      const result = await client.POST("/ledger", {
+        body: batch as unknown as JsonRpcBatchPayload,
+      });
+      return unwrap(result);
+    },
+    id: "ledger.batch",
+    options: [],
+    segments: ["ledger", "batch"],
+    summary:
+      "Send a JSON-RPC batch request to the Besu node via POST /ledger — an array of independent " +
+      "requests processed in order under a single Authorization header (--token, EBSI_ACCESS_TOKEN, " +
+      "or `ebsi config set token`). Besu accepts at most 1024 requests per batch. Useful for grouping " +
+      "reads, or submitting several pre-signed raw transactions (eth_sendRawTransaction) together. " +
+      "For signing and submitting several registry writes in one batch, use `ledger write-batch`.",
+  },
+
+  {
+    args: [
+      {
+        description:
+          'Path to a JSON file containing a JSON array of write entries: {"registry", "function", ' +
+          '"args", "to"?} — same shape as the `ledger write` positional args. "to" falls back to the ' +
+          "registry's env var, per entry, if omitted.",
+        example: "./writes.json",
+        name: "file",
+        required: true,
+      },
+    ],
+    group: "Ledger",
+    async handler(args, opts, config) {
+      const file = requiredArg(args, "file");
+      const fileEntries = parseWriteBatchFile(readFileSync(file, "utf8"));
+
+      // Resolve each entry's registry + contract address up front, so a bad
+      // entry fails before any signing/network activity happens.
+      const resolvedEntries = fileEntries.map((entry, index) => {
+        const position = `Entry #${(index + 1).toString()}`;
+        const registry = REGISTRIES[entry.registry];
+        if (!registry) {
+          throw new Error(
+            `${position}: unknown registry "${entry.registry}". Known registries: ${REGISTRY_NAMES.join(", ")}`,
+          );
+        }
+        const to = entry.to ?? process.env[registry.addressEnvKey];
+        if (!to) {
+          throw new Error(
+            `${position}: no contract address for "${entry.registry}". ` +
+              `Set "to" in the batch file or the ${registry.addressEnvKey} env var.`,
+          );
+        }
+        return {
+          functionArgs: entry.args,
+          functionName: entry.function,
+          registry,
+          registryName: entry.registry,
+          to,
+        };
+      });
+
+      const wallet = await resolveWallet(opts, config);
+
+      // Resolve access token — with --auto-token and no explicit --scope, derive
+      // the minimal multi-scope token covering every distinct registry in the
+      // batch, each instance-targeted at the address it's being written to.
+      const defaultScope = deriveScopeForRegistries(
+        resolvedEntries.map(({ functionName, registryName, to }) => ({
+          functionName,
+          registryName,
+          to,
+        })),
+      );
+      const token = await resolveWriteToken(opts, config, wallet, defaultScope);
+
+      // Sign every write against one nonce sequence, then submit as one batch
+      const gas = parseGasOverrides(opts);
+      const rawTxs = await signWriteBatch({
+        config,
+        entries: resolvedEntries.map(
+          ({ functionArgs, functionName, registry, to }) => ({
+            functionArgs,
+            functionName,
+            registry,
+            to,
+          }),
+        ),
+        ...(gas !== undefined && { gas }),
+        token,
+        wallet,
+      });
+
+      const batchBody = rawTxs.map((rawTx, index) => ({
+        id: index + 1,
+        jsonrpc: "2.0" as const,
+        method: "eth_sendRawTransaction",
+        params: [rawTx],
+      }));
+
+      const client = getClient(config);
+      const result = await client.POST("/ledger", {
+        body: batchBody,
+      });
+      return unwrap(result);
+    },
+    id: "ledger.write-batch",
+    options: [
+      {
+        description:
+          "Obtain a fresh access token automatically using the VP flow before submitting the batch. " +
+          "Uses the minimal multi-scope token covering every distinct registry in the batch, each " +
+          "targeted at the instance it's being written to, unless --scope overrides it.",
+        flags: "--auto-token",
+      },
+      {
+        description:
+          'EBSI scope to use when requesting a token with --auto-token (e.g. "did-registry:write issuers-registry:write"). ' +
+          "Defaults to the minimal multi-scope combination derived from the batch's registries, " +
+          "each instance-targeted at its resolved contract address.",
+        flags: "--scope <scope>",
+      },
+      {
+        description:
+          "Path to a VC JWT file. Only relevant if --scope is overridden to a VC-required scope " +
+          "(uncommon for a multi-write batch).",
+        flags: "--vc <file>",
+      },
+      ...WALLET_KEY_OPTIONS,
+      {
+        description: "EBSI DID to use. Overrides config/env.",
+        flags: "--did <did>",
+      },
+      {
+        description:
+          "Advanced: manual gas limit (decimal or 0x-prefixed hex), shared by every entry, " +
+          "overriding the eth_estimateGas result. By default the gas limit is estimated dynamically, " +
+          "per entry, from the node.",
+        flags: "--gas-limit <value>",
+      },
+      {
+        description:
+          "Advanced: manual gas price (decimal or 0x-prefixed hex), shared by every entry, " +
+          "forcing legacy transactions. By default fees are derived dynamically from the node " +
+          "(EIP-1559 when supported).",
+        flags: "--gas-price <value>",
+      },
+    ],
+    segments: ["ledger", "write-batch"],
+    summary:
+      "Sign several registry writes from one wallet, under one access token, and submit them as a " +
+      "single JSON-RPC batch request via POST /ledger — one round-trip instead of one per write. " +
+      "Each write gets a sequential nonce so they don't collide. With --auto-token, one multi-scope " +
+      "token is minted covering every distinct registry referenced in the batch file " +
+      "(combinable scopes only: did-registry:write, issuers-registry:write, timestamp:write, track-and-trace:create, track-and-trace:write, " +
+      "policies-registry:write, schemas-registry:write). Returns transaction hashes, not receipts — use `ledger tx <hash>` " +
+      "to check status afterwards. Known registries: " +
+      REGISTRY_NAMES.join(", ") +
+      ".",
+  },
+];