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

package/dist/commands/ledger.js

@@ -1,397 +1,574 @@
-import { ethers } from "ethers";
-import Joi from "joi";
-import { buildParam } from "../buildParam/index.js";
-import { green, httpCall, jsonrpcBody, red, yellow } from "../utils/index.js";
-import { compute, getProperties, toPlainAbiValue } from "./compute.js";
-import { readPtrContract } from "./ptr.js";
-import { readTcrContract } from "./tcr.js";
-import { readTsrContract } from "./tsr.js";
-import { view } from "./view.js";
-export const smartContractApiList = [
-    "timestamp",
-    "did",
-    "tcr",
-    "ptr",
-    "tir",
-    "tsr",
-    "tpr",
-    "tnt",
-];
-const onlyApiMethods = [
-    {
-        contract: "did",
-        method: "addService",
-    },
-    {
-        contract: "did",
-        method: "revokeService",
-    },
-];
-export async function ledger(method, inputs, useProxy, context) {
-    if (useProxy) {
-        try {
-            new URL(context.config.besuProvider);
-        }
-        catch {
-            throw new Error(`Invalid URL for besu provider: ${context.config.besuProvider}`);
-        }
+import { readFileSync } from "node:fs";
+import { getClient, unwrap } from "../api/fetch.js";
+import { validateScope } from "../auth/presentation.js";
+import { getAccessToken } from "../auth/token.js";
+import { readFromRegistry } from "../ledger/read.js";
+import { defaultScopeFor, deriveScopeForRegistries, REGISTRIES, REGISTRY_NAMES, } from "../ledger/registries.js";
+import { signWriteBatch, writeToRegistry } from "../ledger/write.js";
+import { requiredArg } from "./shared/args.js";
+import { resolveWallet, WALLET_KEY_OPTIONS } from "./shared/wallet-opts.js";
+function normalizeBatchEntry(entry, index) {
+    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"}).`);
     }
-    if (smartContractApiList.includes(method)) {
-        return ledgerCallSmartContract(method, inputs, useProxy, context);
+    const { id, method, params } = entry;
+    if (typeof method !== "string" || method === "") {
+        throw new Error(`${position} is missing a "method" string.`);
     }
-    switch (method) {
-        case "get": {
-            return ledgerGet(inputs, useProxy, context);
-        }
-        case "getBlock": {
-            return ledgerGetBlock(inputs, useProxy, context);
-        }
-        case "getChainId": {
-            return ledgerGetChainId(inputs, useProxy, context);
-        }
-        case "getGasPrice": {
-            return ledgerGetGasPrice(useProxy, context);
-        }
-        case "getTransaction": {
-            return ledgerGetTransaction(inputs, useProxy, context);
-        }
-        case "getTransactionCount": {
-            return ledgerGetTransactionCount(inputs, useProxy, context);
-        }
-        case "getTransactionReceipt": {
-            return ledgerGetTransactionReceipt(inputs, useProxy, context);
-        }
-        case "send": {
-            return ledgerSendCustomContract(inputs, useProxy, context);
-        }
-        case "sendEth": {
-            return ledgerSendEth(inputs[0], inputs[1], useProxy, context);
-        }
-        case "sendTransaction": {
-            return ledgerSendTransaction(inputs, useProxy, context);
-        }
-        default: {
-            throw new Error(`Invalid method '${method}'`);
-        }
+    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 }),
+    };
 }
-export async function ledgerCallSmartContract(contractName, inputs, useProxy, context) {
-    if (!(contractName in context.config.api)) {
-        throw new Error(`contract ${contractName} not supported`);
+function parseGasBigInt(raw, flag) {
+    try {
+        return BigInt(raw);
     }
-    const { contract } = context.config.api[contractName];
-    if (!contract) {
-        throw new Error(`contract ${contractName} not supported`);
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Invalid ${flag} value "${raw}": ${message}`, {
+            cause: error,
+        });
     }
-    const [m, ...args] = inputs;
-    let method = m;
-    Joi.assert(method, Joi.string());
-    // check if the user wants to read data from the contract
-    if (method === "get") {
-        const path = args[0];
-        switch (contractName) {
-            case "ptr": {
-                return readPtrContract(path, useProxy, context);
-            }
-            case "tcr": {
-                return readTcrContract(path, useProxy, context);
-            }
-            case "tsr": {
-                return readTsrContract(path, useProxy, context);
-            }
-            default: {
-                throw new Error(`contract ${contractName} not supported`);
-            }
-        }
+}
+function parseGasOverrides(opts) {
+    const gasLimitRaw = opts["gasLimit"];
+    const gasPriceRaw = opts["gasPrice"];
+    if (gasLimitRaw === undefined && gasPriceRaw === undefined) {
+        return undefined;
     }
-    // check if the method is just to build the unsigned transaction
-    if (method.startsWith("build-")) {
-        method = method.replace("build-", "");
-        if (onlyApiMethods.some((im) => im.contract === contractName && im.method === method)) {
-            throw new Error(`The method '${method}' can only be used through the ${contractName} api`);
-        }
-        const build = await buildParam(contractName, method, context.client, args, context.config.versionApis);
-        const params = build.paramOrder.map((key) => build.param[key]);
-        if (build.method)
-            method = build.method;
-        const data = contract.interface.encodeFunctionData(method, params);
-        yellow(build.info.title);
-        yellow(build.info.data);
-        context.transactionInfo = {
-            build,
-            contract: contractName,
-            method,
-        };
-        return {
-            chainId: `0x${Number(await ledgerGetChainId([], useProxy, context)).toString(16)}`,
-            data,
-            from: context.client.ethWallet.address,
-            gasLimit: `0x${context.rtVars["gasLimit"].toString(16)}`,
-            gasPrice: `0x${context.rtVars["gasPrice"].toString(16)}`,
-            nonce: await ledgerGetTransactionCount([context.client.ethWallet.address], useProxy, context),
-            to: await contract.getAddress(),
-            value: "0x0",
-        };
+    return {
+        ...(gasLimitRaw !== undefined && {
+            gasLimit: parseGasBigInt(gasLimitRaw, "--gas-limit"),
+        }),
+        ...(gasPriceRaw !== undefined && {
+            gasPrice: parseGasBigInt(gasPriceRaw, "--gas-price"),
+        }),
+    };
+}
+function parseJsonArray(raw, argName) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        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;
+}
+function parseWriteBatchFile(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "parse error";
+        throw new Error(`Invalid JSON: ${message}`, { cause: error });
     }
-    // build, sign and send
-    const cmd = useProxy ? "proxyledger" : "ledger";
-    console.log(`==> ${cmd} built-${method} ${args
-        .map((arg) => {
-        let param;
-        if (typeof arg === "number") {
-            param = `${arg}`;
+    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;
+        if (typeof registry !== "string" || registry === "") {
+            throw new Error(`${position} is missing a "registry" string.`);
         }
-        else if (typeof arg === "string") {
-            param = `"${arg}"`;
+        if (typeof fn !== "string" || fn === "") {
+            throw new Error(`${position} is missing a "function" string.`);
         }
-        else {
-            param = JSON.stringify(arg);
+        if (!Array.isArray(args)) {
+            throw new TypeError(`${position}: "args" must be a JSON array.`);
         }
-        return param;
-    })
-        .join(" ")}`);
-    const uTx = (await ledgerCallSmartContract(contractName, [`build-${method}`, ...args], useProxy, context));
-    console.log(`==> compute signTransaction ${JSON.stringify(uTx)}`);
-    const sgnTx = (await compute("signTransaction", [uTx], context));
-    console.log(`==> ${cmd} sendTransaction ${sgnTx}`);
-    const receipt = await ledgerSendTransaction([sgnTx], useProxy, context);
-    await view(["transactionInfo"], context);
-    return receipt;
+        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 }) };
+    });
 }
-export async function ledgerGet(inputs, useProxy, context) {
-    // check if the first input is an address
-    if (/^0x[0-9a-fA-F]+$/.test(inputs[0])) {
-        return ledgerGetCustomContract(inputs, useProxy, context);
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
     }
-    const apiUrl = context.config.api.ledger.url;
-    const urlPath = inputs.join("");
-    const url = urlPath.startsWith("http") ? urlPath : `${apiUrl}${urlPath}`;
-    const response = await httpCall.get(url, context.httpOpts);
-    return response.data;
-}
-export async function ledgerGetBlock(inputs, useProxy, context) {
-    const apiUrl = useProxy
-        ? context.config.besuProvider
-        : `${context.config.api.ledger.url}/blockchains/besu`;
-    const body = jsonrpcBody("eth_getBlockByNumber", [inputs[0], true]);
-    const response = await httpCall.post(apiUrl, body, context.httpOpts);
-    return response.data.result;
+    return Buffer.concat(chunks).toString("utf8");
 }
-export async function ledgerGetChainId(_inputs, useProxy, context) {
-    const apiUrl = useProxy
-        ? context.config.besuProvider
-        : `${context.config.api.ledger.url}/blockchains/besu`;
-    const body = jsonrpcBody("net_version", []);
-    const response = await httpCall.post(apiUrl, body, context.httpOpts);
-    return response.data.result;
-}
-export async function ledgerGetCustomContract(inputs, useProxy, context) {
-    const [address, abi, method, ...args] = inputs;
-    const provider = new ethers.JsonRpcProvider(useProxy
-        ? context.config.besuProvider
-        : `${context.config.api.ledger.url}/blockchains/besu`);
-    const contract = new ethers.Contract(address, abi, provider);
-    const result = (await contract[method](...args));
-    const fragment = contract.interface.getFunction(method);
-    if (!fragment) {
-        throw new Error(`Can't get function fragment for ${method}`);
+async function resolveWriteToken(opts, config, wallet, defaultScope) {
+    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 outputs = fragment.outputs;
-    const outputsDecoded = outputs.length === 0
-        ? undefined
-        : outputs.length === 1
-            ? toPlainAbiValue(result, outputs[0])
-            : getProperties(result, outputs);
-    const dataDecoded = {
-        name: fragment.name,
-        outputs: outputsDecoded,
-    };
-    green({ dataDecoded, result });
-    return { dataDecoded, result };
-}
-export async function ledgerGetGasPrice(useProxy, context) {
-    const apiUrl = useProxy
-        ? context.config.besuProvider
-        : `${context.config.api.ledger.url}/blockchains/besu`;
-    const body = jsonrpcBody("eth_gasPrice", []);
-    const response = await httpCall.post(apiUrl, body, context.httpOpts);
-    return response.data.result;
-}
-export async function ledgerGetTransaction(inputs, useProxy, context) {
-    const apiUrl = useProxy
-        ? context.config.besuProvider
-        : `${context.config.api.ledger.url}/blockchains/besu`;
-    const body = jsonrpcBody("eth_getTransactionByHash", [inputs[0]]);
-    const response = await httpCall.post(apiUrl, body, context.httpOpts);
-    return response.data.result;
-}
-export async function ledgerGetTransactionCount(inputs, useProxy, context) {
-    const apiUrl = useProxy
-        ? context.config.besuProvider
-        : `${context.config.api.ledger.url}/blockchains/besu`;
-    const body = jsonrpcBody("eth_getTransactionCount", [inputs[0], "latest"]);
-    const response = await httpCall.post(apiUrl, body, context.httpOpts);
-    return response.data.result;
-}
-export async function ledgerGetTransactionReceipt(inputs, useProxy, context) {
-    const apiUrl = useProxy
-        ? context.config.besuProvider
-        : `${context.config.api.ledger.url}/blockchains/besu`;
-    const body = jsonrpcBody("eth_getTransactionReceipt", [inputs[0]]);
-    const response = await httpCall.post(apiUrl, body, context.httpOpts);
-    const receipt = response.data.result;
-    if (receipt && Number(receipt.status) !== 1) {
-        const message = `Transaction failed: Status ${receipt.status}. Revert reason: ${parseRevertReason(receipt, context)}`;
-        red(message);
-        throw new Error(message);
+    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 receipt;
+    return resolvedToken;
 }
-export async function ledgerSendCustomContract(inputs, useProxy, context) {
-    const [address, abi, method, ...params] = inputs;
-    const provider = new ethers.JsonRpcProvider(useProxy
-        ? context.config.besuProvider
-        : `${context.config.api.ledger.url}/blockchains/besu`);
-    const contract = new ethers.Contract(address, abi, provider);
-    const data = contract.interface.encodeFunctionData(method, params);
-    const uTx = {
-        chainId: `0x${Number(await ledgerGetChainId([], useProxy, context)).toString(16)}`,
-        data,
-        from: context.client.ethWallet.address,
-        gasLimit: `0x${context.rtVars["gasLimit"].toString(16)}`,
-        gasPrice: `0x${context.rtVars["gasPrice"].toString(16)}`,
-        nonce: await ledgerGetTransactionCount([context.client.ethWallet.address], useProxy, context),
-        to: address,
-        value: "0x0",
-    };
-    context.transactionInfo = {
-        build: {
-            info: {
-                data: params,
-                title: `call ${method} on ${address}`,
+export const ledgerCommands = [
+    {
+        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,
             },
-            param: {},
-            paramOrder: [],
+        ],
+        group: "Ledger",
+        async handler(args, opts, config) {
+            const method = requiredArg(args, "method");
+            const rawParams = args["params"];
+            let params = [];
+            if (rawParams !== undefined && rawParams !== "") {
+                try {
+                    const parsed = JSON.parse(rawParams);
+                    if (!Array.isArray(parsed)) {
+                        throw new TypeError("params must be a JSON array");
+                    }
+                    params = parsed;
+                }
+                catch (error) {
+                    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);
         },
-        contract: address,
-        method,
-    };
-    console.log(`==> compute signTransaction ${JSON.stringify(uTx)}`);
-    const sgnTx = (await compute("signTransaction", [uTx], context));
-    const cmd = useProxy ? "proxyledger" : "ledger";
-    console.log(`==> ${cmd} sendTransaction ${sgnTx}`);
-    const receipt = await ledgerSendTransaction([sgnTx], useProxy, context);
-    return receipt;
-}
-export async function ledgerSendEth(amount, to, useProxy, context) {
-    const value = `0x${(BigInt(Number(amount) * 1e6) * BigInt(Number(1e12))).toString(16)}`;
-    const uTx = {
-        chainId: `0x${Number(await ledgerGetChainId([], useProxy, context)).toString(16)}`,
-        data: "0x",
-        from: context.client.ethWallet.address,
-        gasLimit: `0x${context.rtVars["gasLimit"].toString(16)}`,
-        gasPrice: "0x01",
-        nonce: await ledgerGetTransactionCount([context.client.ethWallet.address], useProxy, context),
-        to,
-        value,
-    };
-    context.transactionInfo = {
-        build: {
-            info: {
-                data: { amount, to },
-                title: `send ETH: ${amount} to ${to}`,
+        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,
             },
-            param: {},
-            paramOrder: [],
+        ],
+        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);
         },
-        contract: to,
-        method: "sendEth",
-    };
-    console.log(`==> compute signTransaction ${JSON.stringify(uTx)}`);
-    const sgnTx = (await compute("signTransaction", [uTx], context));
-    const cmd = useProxy ? "proxyledger" : "ledger";
-    console.log(`==> ${cmd} sendTransaction ${sgnTx}`);
-    const receipt = await ledgerSendTransaction([sgnTx], useProxy, context);
-    return receipt;
-}
-export async function ledgerSendTransaction(inputs, useProxy, context) {
-    const apiUrl = useProxy
-        ? context.config.besuProvider
-        : `${context.config.api.ledger.url}/blockchains/besu`;
-    const [sgnTx] = inputs;
-    Joi.assert(sgnTx, Joi.string());
-    const body = jsonrpcBody("eth_sendRawTransaction", [sgnTx]);
-    const response = await httpCall.post(apiUrl, body, context.httpOpts);
-    if (!response.data.result) {
-        if (response.data.error)
-            throw new Error(JSON.stringify(response.data.error));
-        throw new Error(JSON.stringify(response.data));
-    }
-    context.transactionInfo.txId = response.data.result;
-    context.transactionInfo.receipt = await waitToBeMined(response.data.result, useProxy, context);
-    return context.transactionInfo.receipt;
-}
-export function parseRevertReason(receipt, context) {
-    if (!receipt.revertReason) {
-        // no revert reason
-        return "";
-    }
-    if (receipt.revertReason.length >= 138) {
-        // revert reason with a message
-        return Buffer.from(receipt.revertReason.slice(138), "hex")
-            .toString()
-            .replaceAll(/[^a-z0-9:\-' ]/gi, "");
-    }
-    // get the contract linked to the "to" value in the receipt
-    const contractName = Object.keys(context.config.contractAddresses).find((a) => context.config.contractAddresses[a].toLowerCase() ===
-        receipt.to.toLowerCase());
-    if (!contractName)
-        return receipt.revertReason;
-    const { contract } = context.config.api[contractName];
-    // get the error name associated to the revert reason
-    // In ethers v6, errors are accessed through fragments
-    const errorSelector = receipt.revertReason.slice(0, 10);
-    let errorName;
-    // Try to find error by iterating through interface error fragments
-    try {
-        const interfaceErrors = contract?.interface.fragments.filter((f) => f.type === "error");
-        for (const fragment of interfaceErrors) {
+        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");
+            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);
+            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(", ")}`);
+            }
+            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;
             try {
-                const selector = ethers.id(fragment.format("sighash")).slice(0, 10);
-                if (selector === errorSelector) {
-                    errorName = fragment.name;
-                    break;
-                }
+                parsed = JSON.parse(raw);
             }
-            catch {
-                // Continue searching
+            catch (error) {
+                const message = error instanceof Error ? error.message : "parse error";
+                throw new Error(`Invalid JSON in "${source}": ${message}`, {
+                    cause: error,
+                });
             }
-        }
-    }
-    catch {
-        // If we can't parse errors, return the revert reason
-        errorName = undefined;
-    }
-    return errorName ?? receipt.revertReason;
-}
-export async function waitToBeMined(txId, useProxy, context) {
-    let mined = false;
-    let receipt = null;
-    yellow("Waiting to be mined...");
-    const iniTime = Date.now();
-    let diffTime = 0;
-    while (!mined && diffTime <= context.config.timeoutMining) {
-        await new Promise((resolve) => {
-            setTimeout(resolve, 5000);
-        });
-        console.log(`==> ${useProxy ? "proxyledger" : "ledger"} getTransactionReceipt ${txId}`);
-        receipt = await ledgerGetTransactionReceipt([txId], useProxy, context);
-        mined = !!receipt;
-        diffTime = Date.now() - iniTime;
-    }
-    if (!mined && diffTime > context.config.timeoutMining) {
-        throw new Error(`${context.config.timeoutMining} milliseconds timeout. Transaction ${txId} is still waiting to be mined`);
-    }
-    return receipt;
-}
+            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,
+            });
+            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"));
+            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);
+            const defaultScope = deriveScopeForRegistries(resolvedEntries.map(({ functionName, registryName, to }) => ({
+                functionName,
+                registryName,
+                to,
+            })));
+            const token = await resolveWriteToken(opts, config, wallet, defaultScope);
+            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",
+                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(", ") +
+            ".",
+    },
+];
 //# sourceMappingURL=ledger.js.map