genlayer 0.38.13 → 0.38.15

package/.github/workflows/publish.yml

@@ -37,11 +37,9 @@ jobs:
 
       - uses: actions/setup-node@v4
         with:
-          node-version: "22"
+          node-version: "24"
           registry-url: "https://registry.npmjs.org"
 
-      - run: npm install -g npm@latest
-
       - run: npm ci
 
       - name: Release

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.38.15 (2026-04-14)
+
+### Bug Fixes
+
+* preserve platform-specific optional deps in lockfile ([af7436b](https://github.com/genlayerlabs/genlayer-cli/commit/af7436b8d4f8f56582c38dd8006efa4946ea8964))
+
+## [0.38.14](https://github.com/genlayerlabs/genlayer-cli/compare/v0.38.13...v0.38.14) (2026-04-02)
+
 ## 0.38.13 (2026-04-01)
 
 ## 0.38.12 (2026-04-01)

package/dist/index.js

@@ -20078,7 +20078,7 @@ var require_cli_table3 = __commonJS({
 import { program } from "commander";
 
 // package.json
-var version = "0.38.13";
+var version = "0.38.15";
 var package_default = {
   name: "genlayer",
   version,
@@ -20148,7 +20148,7 @@ var package_default = {
     dotenv: "^17.0.0",
     ethers: "^6.13.4",
     "fs-extra": "^11.3.0",
-    "genlayer-js": "^0.27.9",
+    "genlayer-js": "^0.28.5",
     inquirer: "^12.0.0",
     keytar: "^7.9.0",
     "node-fetch": "^3.0.0",
@@ -33738,7 +33738,7 @@ init_toHex();
 init_keccak256();
 init_formatEther();
 
-// node_modules/genlayer-js/dist/chunk-C4Z24PT6.js
+// node_modules/genlayer-js/dist/chunk-SGAVFNGA.js
 var chains_exports = {};
 __export2(chains_exports, {
   localnet: () => localnet,
@@ -37755,6 +37755,7 @@ var localnet = defineChain({
   stakingContract: null,
   feeManagerContract: null,
   roundsStorageContract: null,
+  appealsContract: null,
   defaultNumberOfInitialValidators: 5,
   defaultConsensusMaxRotations: 3
 });
@@ -41768,6 +41769,7 @@ var studionet = defineChain({
   stakingContract: null,
   feeManagerContract: null,
   roundsStorageContract: null,
+  appealsContract: null,
   defaultNumberOfInitialValidators: 5,
   defaultConsensusMaxRotations: 3
 });
@@ -47261,6 +47263,7 @@ var testnetAsimov = defineChain({
   stakingContract: STAKING_CONTRACT,
   feeManagerContract: null,
   roundsStorageContract: null,
+  appealsContract: null,
   defaultNumberOfInitialValidators: 5,
   defaultConsensusMaxRotations: 3
 });
@@ -47294,6 +47297,70 @@ var ROUNDS_STORAGE_CONTRACT = {
       stateMutability: "view",
       inputs: [{ name: "_txId", type: "bytes32" }],
       outputs: [{ name: "", type: "uint256" }]
+    },
+    {
+      type: "function",
+      name: "getRoundData",
+      stateMutability: "view",
+      inputs: [
+        { name: "_txId", type: "bytes32" },
+        { name: "_round", type: "uint256" }
+      ],
+      outputs: [{
+        name: "",
+        type: "tuple",
+        components: [
+          { name: "round", type: "uint256" },
+          { name: "leaderIndex", type: "uint256" },
+          { name: "votesCommitted", type: "uint256" },
+          { name: "votesRevealed", type: "uint256" },
+          { name: "appealBond", type: "uint256" },
+          { name: "rotationsLeft", type: "uint256" },
+          { name: "result", type: "uint8" },
+          { name: "roundValidators", type: "address[]" },
+          { name: "validatorVotes", type: "uint8[]" },
+          { name: "validatorVotesHash", type: "bytes32[]" },
+          { name: "validatorResultHash", type: "bytes32[]" }
+        ]
+      }]
+    },
+    {
+      type: "function",
+      name: "getLastRoundData",
+      stateMutability: "view",
+      inputs: [{ name: "_txId", type: "bytes32" }],
+      outputs: [
+        { name: "", type: "uint256" },
+        {
+          name: "",
+          type: "tuple",
+          components: [
+            { name: "round", type: "uint256" },
+            { name: "leaderIndex", type: "uint256" },
+            { name: "votesCommitted", type: "uint256" },
+            { name: "votesRevealed", type: "uint256" },
+            { name: "appealBond", type: "uint256" },
+            { name: "rotationsLeft", type: "uint256" },
+            { name: "result", type: "uint8" },
+            { name: "roundValidators", type: "address[]" },
+            { name: "validatorVotes", type: "uint8[]" },
+            { name: "validatorVotesHash", type: "bytes32[]" },
+            { name: "validatorResultHash", type: "bytes32[]" }
+          ]
+        }
+      ]
+    }
+  ]
+};
+var APPEALS_CONTRACT = {
+  address: "0xbb8C35AA878D09b9830aFF9e5aAC6492BFbd5471",
+  abi: [
+    {
+      type: "function",
+      name: "canAppeal",
+      stateMutability: "view",
+      inputs: [{ name: "_txId", type: "bytes32" }],
+      outputs: [{ name: "", type: "bool" }]
     }
   ]
 };
@@ -50640,6 +50707,7 @@ var testnetBradbury = defineChain({
   stakingContract: STAKING_CONTRACT2,
   feeManagerContract: FEE_MANAGER_CONTRACT,
   roundsStorageContract: ROUNDS_STORAGE_CONTRACT,
+  appealsContract: APPEALS_CONTRACT,
   defaultNumberOfInitialValidators: 5,
   defaultConsensusMaxRotations: 3
 });
@@ -51410,10 +51478,10 @@ function extractGenCallResult(result) {
 }
 var contractActions = (client, publicClient) => {
   return {
-    /** Retrieves the source code of a deployed contract. Localnet only. */
+    /** Retrieves the source code of a deployed contract. Studio only. */
     getContractCode: async (address) => {
-      if (client.chain.id !== localnet.id) {
-        throw new Error(`getContractCode is only available on localnet (current chain: ${client.chain.name})`);
+      if (!client.chain.isStudio) {
+        throw new Error(`getContractCode is only available on Studio networks (current chain: ${client.chain.name})`);
       }
       const result = await client.request({
         method: "gen_getContractCode",
@@ -51422,10 +51490,10 @@ var contractActions = (client, publicClient) => {
       const codeBytes = b64ToArray(result);
       return new TextDecoder().decode(codeBytes);
     },
-    /** Gets the schema (methods and constructor) of a deployed contract. Localnet only. */
+    /** Gets the schema (methods and constructor) of a deployed contract. Studio only. */
     getContractSchema: async (address) => {
-      if (client.chain.id !== localnet.id) {
-        throw new Error(`getContractSchema is only available on localnet (current chain: ${client.chain.name})`);
+      if (!client.chain.isStudio) {
+        throw new Error(`getContractSchema is only available on Studio networks (current chain: ${client.chain.name})`);
       }
       const schema = await client.request({
         method: "gen_getContractSchema",
@@ -51433,10 +51501,10 @@ var contractActions = (client, publicClient) => {
       });
       return schema;
     },
-    /** Generates a schema for contract code without deploying it. Localnet only. */
+    /** Generates a schema for contract code without deploying it. Studio only. */
     getContractSchemaForCode: async (contractCode) => {
-      if (client.chain.id !== localnet.id) {
-        throw new Error(`getContractSchema is only available on localnet (current chain: ${client.chain.name})`);
+      if (!client.chain.isStudio) {
+        throw new Error(`getContractSchemaForCode is only available on Studio networks (current chain: ${client.chain.name})`);
       }
       const schema = await client.request({
         method: "gen_getContractSchemaForCode",
@@ -51600,6 +51668,54 @@ var contractActions = (client, publicClient) => {
       });
       return minBond;
     },
+    /** Returns the current consensus round number for a transaction. */
+    getRoundNumber: async (args) => {
+      if (!client.chain.roundsStorageContract?.address) {
+        throw new Error("getRoundNumber not supported on this chain (missing roundsStorageContract)");
+      }
+      return publicClient.readContract({
+        address: client.chain.roundsStorageContract.address,
+        abi: client.chain.roundsStorageContract.abi,
+        functionName: "getRoundNumber",
+        args: [args.txId]
+      });
+    },
+    /** Returns detailed data for a specific consensus round. */
+    getRoundData: async (args) => {
+      if (!client.chain.roundsStorageContract?.address) {
+        throw new Error("getRoundData not supported on this chain (missing roundsStorageContract)");
+      }
+      return publicClient.readContract({
+        address: client.chain.roundsStorageContract.address,
+        abi: client.chain.roundsStorageContract.abi,
+        functionName: "getRoundData",
+        args: [args.txId, args.round]
+      });
+    },
+    /** Returns the current round number and its data for a transaction. */
+    getLastRoundData: async (args) => {
+      if (!client.chain.roundsStorageContract?.address) {
+        throw new Error("getLastRoundData not supported on this chain (missing roundsStorageContract)");
+      }
+      return publicClient.readContract({
+        address: client.chain.roundsStorageContract.address,
+        abi: client.chain.roundsStorageContract.abi,
+        functionName: "getLastRoundData",
+        args: [args.txId]
+      });
+    },
+    /** Checks if a transaction can be appealed. */
+    canAppeal: async (args) => {
+      if (!client.chain.appealsContract?.address) {
+        throw new Error("canAppeal not supported on this chain (missing appealsContract)");
+      }
+      return publicClient.readContract({
+        address: client.chain.appealsContract.address,
+        abi: client.chain.appealsContract.abi,
+        functionName: "canAppeal",
+        args: [args.txId]
+      });
+    },
     /** Appeals a consensus transaction to trigger a new round of validation. */
     appealTransaction: async (args) => {
       const { account, txId } = args;
@@ -51626,12 +51742,51 @@ var contractActions = (client, publicClient) => {
       }
       const senderAccount = account || client.account;
       const encodedData = _encodeSubmitAppealData({ client, txId });
-      return _sendTransaction({
+      await _sendConsensusCall({
         client,
         publicClient,
         encodedData,
         senderAccount,
-        value
+        value,
+        operationName: "Appeal"
+      });
+      return txId;
+    },
+    /** Finalizes a single GenLayer transaction that is ready to be finalized. Returns the EVM transaction hash. */
+    finalizeTransaction: async (args) => {
+      const { account, txId } = args;
+      const senderAccount = account || client.account;
+      const encodedData = encodeFunctionData({
+        abi: client.chain.consensusMainContract?.abi,
+        functionName: "finalizeTransaction",
+        args: [txId]
+      });
+      return _sendConsensusCall({
+        client,
+        publicClient,
+        encodedData,
+        senderAccount,
+        operationName: "Finalize"
+      });
+    },
+    /** Batch-finalizes idle GenLayer transactions (those stuck without progressing). Returns the EVM transaction hash. */
+    finalizeIdlenessTxs: async (args) => {
+      const { account, txIds } = args;
+      if (txIds.length === 0) {
+        throw new Error("finalizeIdlenessTxs requires at least one txId.");
+      }
+      const senderAccount = account || client.account;
+      const encodedData = encodeFunctionData({
+        abi: client.chain.consensusMainContract?.abi,
+        functionName: "finalizeIdlenessTxs",
+        args: [txIds]
+      });
+      return _sendConsensusCall({
+        client,
+        publicClient,
+        encodedData,
+        senderAccount,
+        operationName: "Finalize idleness"
       });
     }
   };
@@ -51745,6 +51900,69 @@ var _encodeSubmitAppealData = ({
     args: [txId]
   });
 };
+var _sendConsensusCall = async ({
+  client,
+  publicClient,
+  encodedData,
+  senderAccount,
+  value = 0n,
+  operationName = "Consensus call"
+}) => {
+  if (!client.chain.consensusMainContract?.address) {
+    throw new Error("Consensus main contract not initialized.");
+  }
+  const validatedAccount = validateAccount(senderAccount);
+  const nonce = await client.getCurrentNonce({ address: validatedAccount.address });
+  let estimatedGas;
+  try {
+    estimatedGas = await client.estimateTransactionGas({
+      to: client.chain.consensusMainContract.address,
+      data: encodedData,
+      value
+    });
+  } catch (err) {
+    console.error("Gas estimation failed, using default 200_000:", err);
+    estimatedGas = 200000n;
+  }
+  const gasPriceHex = await client.request({ method: "eth_gasPrice" });
+  if (validatedAccount.type === "local") {
+    if (!validatedAccount.signTransaction) {
+      throw new Error("Local account does not support signTransaction.");
+    }
+    const txRequest = {
+      account: validatedAccount,
+      to: client.chain.consensusMainContract.address,
+      data: encodedData,
+      value,
+      gas: estimatedGas,
+      gasPrice: BigInt(gasPriceHex),
+      nonce,
+      chainId: client.chain.id
+    };
+    const serializedTransaction = await validatedAccount.signTransaction(txRequest);
+    const evmHash2 = await client.sendRawTransaction({ serializedTransaction });
+    const receipt2 = await publicClient.waitForTransactionReceipt({ hash: evmHash2 });
+    if (receipt2.status === "reverted") {
+      throw new Error(`${operationName} reverted: EVM tx ${evmHash2}`);
+    }
+    return evmHash2;
+  }
+  const evmHash = await client.request({
+    method: "eth_sendTransaction",
+    params: [{
+      from: validatedAccount.address,
+      to: client.chain.consensusMainContract.address,
+      data: encodedData,
+      value: value ? `0x${value.toString(16)}` : void 0,
+      gas: `0x${estimatedGas.toString(16)}`
+    }]
+  });
+  const receipt = await publicClient.waitForTransactionReceipt({ hash: evmHash });
+  if (receipt.status === "reverted") {
+    throw new Error(`${operationName} reverted: EVM tx ${evmHash}`);
+  }
+  return evmHash;
+};
 var isAddTransactionAbiMismatchError = (error) => {
   const seen = /* @__PURE__ */ new WeakSet();
   const serializedError = typeof error === "object" && error !== null ? JSON.stringify(error, (_key, value) => {
@@ -51874,6 +52092,9 @@ var _sendTransaction = async ({
       method: "eth_sendTransaction",
       params: [formattedRequest]
     });
+    if (client.chain.isStudio) {
+      return evmTxHash;
+    }
     const externalReceipt = await publicClient.waitForTransactionReceipt({ hash: evmTxHash });
     if (externalReceipt.status === "reverted") {
       throw new Error(`Transaction reverted: EVM tx ${evmTxHash} to consensus contract ${client.chain.consensusMainContract?.address} was reverted.`);
@@ -52158,7 +52379,7 @@ var receiptActions = (client, publicClient) => ({
     const requestedStatus = transactionsStatusNameToNumber[status];
     if (transactionStatusString === requestedStatus || status === "ACCEPTED" && isDecidedState(transactionStatusString)) {
       let finalTransaction = transaction;
-      if (client.chain.id === localnet.id) {
+      if (client.chain.isStudio) {
         finalTransaction = decodeLocalnetTransaction(transaction);
       }
       if (!fullTransaction) {
@@ -53017,6 +53238,21 @@ var PROVIDER_METHODS = /* @__PURE__ */ new Set([
   "personal_sign",
   "eth_signTypedData_v4"
 ]);
+var assertChainMatch = async (provider, chainConfig) => {
+  if (chainConfig.isStudio) return;
+  const expectedChainIdHex = `0x${chainConfig.id.toString(16)}`;
+  try {
+    const currentChainId = await provider.request({ method: "eth_chainId" });
+    if (currentChainId !== expectedChainIdHex) {
+      const currentId = parseInt(currentChainId, 16);
+      throw new Error(
+        `Wallet is on chain ${currentId} but client is configured for chain ${chainConfig.id} (${chainConfig.name}). Call client.connect("${chainConfig.name}") or switch your wallet to the correct network before sending transactions.`
+      );
+    }
+  } catch (err) {
+    if (err instanceof Error && err.message.startsWith("Wallet is on chain")) throw err;
+  }
+};
 var getCustomTransportConfig = (config, chainConfig) => {
   const isAddress2 = typeof config.account !== "object";
   return {
@@ -53025,6 +53261,9 @@ var getCustomTransportConfig = (config, chainConfig) => {
         const provider = config.provider || (typeof window !== "undefined" ? window.ethereum : void 0);
         if (provider) {
           try {
+            if (method === "eth_sendTransaction" || method === "eth_signTransaction") {
+              await assertChainMatch(provider, chainConfig);
+            }
             return await provider.request({ method, params });
           } catch (err) {
             console.warn(`Error using provider for method ${method}:`, err);
@@ -56011,6 +56250,41 @@ var TraceAction = class extends BaseAction {
   }
 };
 
+// src/commands/transactions/finalize.ts
+var FinalizeAction = class extends BaseAction {
+  constructor() {
+    super();
+  }
+  async finalize({ txId, rpc }) {
+    const client = await this.getClient(rpc);
+    this.startSpinner(`Finalizing transaction ${txId}...`);
+    try {
+      const evmHash = await client.finalizeTransaction({ txId });
+      this.succeedSpinner("Transaction finalized", { txId, evmTransactionHash: evmHash });
+    } catch (error) {
+      this.failSpinner("Error finalizing transaction", error);
+    }
+  }
+  async finalizeBatch({ txIds, rpc }) {
+    if (txIds.length === 0) {
+      this.failSpinner("At least one txId is required.");
+      return;
+    }
+    const client = await this.getClient(rpc);
+    this.startSpinner(`Finalizing ${txIds.length} idle transaction(s)...`);
+    try {
+      const evmHash = await client.finalizeIdlenessTxs({ txIds });
+      this.succeedSpinner("Idle transactions finalized", {
+        count: txIds.length,
+        txIds,
+        evmTransactionHash: evmHash
+      });
+    } catch (error) {
+      this.failSpinner("Error finalizing idle transactions", error);
+    }
+  }
+};
+
 // src/commands/transactions/index.ts
 function parseIntOption(value, fallback2) {
   const parsed = parseInt(value, 10);
@@ -56034,6 +56308,14 @@ function initializeTransactionsCommands(program2) {
     const traceAction = new TraceAction();
     await traceAction.trace({ txId, ...options });
   });
+  program2.command("finalize <txId>").description("Finalize a transaction that is ready to be finalized (public call)").option("--rpc <rpcUrl>", "RPC URL for the network").action(async (txId, options) => {
+    const finalizeAction = new FinalizeAction();
+    await finalizeAction.finalize({ txId, ...options });
+  });
+  program2.command("finalize-batch <txIds...>").description("Finalize a batch of idle transactions in a single call (public call)").option("--rpc <rpcUrl>", "RPC URL for the network").action(async (txIds, options) => {
+    const finalizeAction = new FinalizeAction();
+    await finalizeAction.finalizeBatch({ txIds, ...options });
+  });
   return program2;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genlayer",
-  "version": "0.38.13",
+  "version": "0.38.15",
   "description": "GenLayer Command Line Tool",
   "main": "src/index.ts",
   "type": "module",
@@ -67,7 +67,7 @@
     "dotenv": "^17.0.0",
     "ethers": "^6.13.4",
     "fs-extra": "^11.3.0",
-    "genlayer-js": "^0.27.9",
+    "genlayer-js": "^0.28.5",
     "inquirer": "^12.0.0",
     "keytar": "^7.9.0",
     "node-fetch": "^3.0.0",

package/src/commands/transactions/finalize.ts

@@ -0,0 +1,45 @@
+import {TransactionHash} from "genlayer-js/types";
+import {BaseAction} from "../../lib/actions/BaseAction";
+
+export interface FinalizeOptions {
+  rpc?: string;
+}
+
+export class FinalizeAction extends BaseAction {
+  constructor() {
+    super();
+  }
+
+  async finalize({txId, rpc}: {txId: TransactionHash; rpc?: string}): Promise<void> {
+    const client = await this.getClient(rpc);
+
+    this.startSpinner(`Finalizing transaction ${txId}...`);
+    try {
+      const evmHash = await client.finalizeTransaction({txId});
+      this.succeedSpinner("Transaction finalized", {txId, evmTransactionHash: evmHash});
+    } catch (error) {
+      this.failSpinner("Error finalizing transaction", error);
+    }
+  }
+
+  async finalizeBatch({txIds, rpc}: {txIds: TransactionHash[]; rpc?: string}): Promise<void> {
+    if (txIds.length === 0) {
+      this.failSpinner("At least one txId is required.");
+      return;
+    }
+
+    const client = await this.getClient(rpc);
+
+    this.startSpinner(`Finalizing ${txIds.length} idle transaction(s)...`);
+    try {
+      const evmHash = await client.finalizeIdlenessTxs({txIds});
+      this.succeedSpinner("Idle transactions finalized", {
+        count: txIds.length,
+        txIds,
+        evmTransactionHash: evmHash,
+      });
+    } catch (error) {
+      this.failSpinner("Error finalizing idle transactions", error);
+    }
+  }
+}

package/src/commands/transactions/index.ts

@@ -3,6 +3,7 @@ import {TransactionStatus, TransactionHash} from "genlayer-js/types";
 import {ReceiptAction, ReceiptOptions} from "./receipt";
 import {AppealAction, AppealOptions, AppealBondOptions} from "./appeal";
 import {TraceAction, TraceOptions} from "./trace";
+import {FinalizeAction, FinalizeOptions} from "./finalize";
 
 function parseIntOption(value: string, fallback: number): number {
   const parsed = parseInt(value, 10);
@@ -56,5 +57,23 @@ export function initializeTransactionsCommands(program: Command) {
       await traceAction.trace({txId, ...options});
     });
 
+  program
+    .command("finalize <txId>")
+    .description("Finalize a transaction that is ready to be finalized (public call)")
+    .option("--rpc <rpcUrl>", "RPC URL for the network")
+    .action(async (txId: TransactionHash, options: FinalizeOptions) => {
+      const finalizeAction = new FinalizeAction();
+      await finalizeAction.finalize({txId, ...options});
+    });
+
+  program
+    .command("finalize-batch <txIds...>")
+    .description("Finalize a batch of idle transactions in a single call (public call)")
+    .option("--rpc <rpcUrl>", "RPC URL for the network")
+    .action(async (txIds: TransactionHash[], options: FinalizeOptions) => {
+      const finalizeAction = new FinalizeAction();
+      await finalizeAction.finalizeBatch({txIds, ...options});
+    });
+
   return program;
 }

package/tests/actions/finalize.test.ts

@@ -0,0 +1,109 @@
+import {describe, test, vi, beforeEach, afterEach, expect} from "vitest";
+import {createClient, createAccount} from "genlayer-js";
+import type {TransactionHash} from "genlayer-js/types";
+import {FinalizeAction} from "../../src/commands/transactions/finalize";
+
+vi.mock("genlayer-js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("genlayer-js")>();
+  return {
+    ...actual,
+    createClient: vi.fn(),
+    createAccount: vi.fn(),
+  };
+});
+
+describe("FinalizeAction", () => {
+  let finalizeAction: FinalizeAction;
+  const mockClient = {
+    finalizeTransaction: vi.fn(),
+    finalizeIdlenessTxs: vi.fn(),
+  };
+
+  const mockPrivateKey = "mocked_private_key";
+  const mockTxId = "0x1234567890123456789012345678901234567890123456789012345678901234" as TransactionHash;
+  const mockTxId2 = "0xabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcd" as TransactionHash;
+  const mockEvmHash = "0xdeadbeef" as `0x${string}`;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(createClient).mockReturnValue(mockClient as any);
+    vi.mocked(createAccount).mockReturnValue({privateKey: mockPrivateKey} as any);
+    finalizeAction = new FinalizeAction();
+    vi.spyOn(finalizeAction as any, "getAccount").mockResolvedValue({privateKey: mockPrivateKey});
+
+    vi.spyOn(finalizeAction as any, "startSpinner").mockImplementation(() => {});
+    vi.spyOn(finalizeAction as any, "succeedSpinner").mockImplementation(() => {});
+    vi.spyOn(finalizeAction as any, "failSpinner").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  test("finalize calls client.finalizeTransaction and reports the EVM hash", async () => {
+    vi.mocked(mockClient.finalizeTransaction).mockResolvedValue(mockEvmHash);
+
+    await finalizeAction.finalize({txId: mockTxId});
+
+    expect(mockClient.finalizeTransaction).toHaveBeenCalledWith({txId: mockTxId});
+    expect(finalizeAction["succeedSpinner"]).toHaveBeenCalledWith(
+      "Transaction finalized",
+      {txId: mockTxId, evmTransactionHash: mockEvmHash},
+    );
+  });
+
+  test("finalize surfaces underlying errors via failSpinner", async () => {
+    vi.mocked(mockClient.finalizeTransaction).mockRejectedValue(new Error("boom"));
+
+    await finalizeAction.finalize({txId: mockTxId});
+
+    expect(finalizeAction["failSpinner"]).toHaveBeenCalledWith(
+      "Error finalizing transaction",
+      expect.any(Error),
+    );
+  });
+
+  test("finalize uses custom RPC URL when provided", async () => {
+    vi.mocked(mockClient.finalizeTransaction).mockResolvedValue(mockEvmHash);
+
+    await finalizeAction.finalize({txId: mockTxId, rpc: "https://custom.com"});
+
+    expect(createClient).toHaveBeenCalledWith(
+      expect.objectContaining({endpoint: "https://custom.com"}),
+    );
+  });
+
+  test("finalizeBatch calls client.finalizeIdlenessTxs with all ids", async () => {
+    vi.mocked(mockClient.finalizeIdlenessTxs).mockResolvedValue(mockEvmHash);
+
+    await finalizeAction.finalizeBatch({txIds: [mockTxId, mockTxId2]});
+
+    expect(mockClient.finalizeIdlenessTxs).toHaveBeenCalledWith({
+      txIds: [mockTxId, mockTxId2],
+    });
+    expect(finalizeAction["succeedSpinner"]).toHaveBeenCalledWith(
+      "Idle transactions finalized",
+      {count: 2, txIds: [mockTxId, mockTxId2], evmTransactionHash: mockEvmHash},
+    );
+  });
+
+  test("finalizeBatch rejects an empty list without calling the client", async () => {
+    await finalizeAction.finalizeBatch({txIds: []});
+
+    expect(mockClient.finalizeIdlenessTxs).not.toHaveBeenCalled();
+    expect(finalizeAction["failSpinner"]).toHaveBeenCalledWith(
+      "At least one txId is required.",
+    );
+  });
+
+  test("finalizeBatch surfaces underlying errors via failSpinner", async () => {
+    vi.mocked(mockClient.finalizeIdlenessTxs).mockRejectedValue(new Error("revert"));
+
+    await finalizeAction.finalizeBatch({txIds: [mockTxId]});
+
+    expect(finalizeAction["failSpinner"]).toHaveBeenCalledWith(
+      "Error finalizing idle transactions",
+      expect.any(Error),
+    );
+  });
+});

package/tests/commands/finalize.test.ts

@@ -0,0 +1,83 @@
+import {Command} from "commander";
+import {FinalizeAction} from "../../src/commands/transactions/finalize";
+import {vi, describe, beforeEach, afterEach, test, expect} from "vitest";
+import {initializeTransactionsCommands} from "../../src/commands/transactions";
+
+vi.mock("../../src/commands/transactions/finalize");
+
+describe("finalize command", () => {
+  let program: Command;
+  const mockTxId = "0x1234567890123456789012345678901234567890123456789012345678901234";
+
+  beforeEach(() => {
+    program = new Command();
+    initializeTransactionsCommands(program);
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  test("FinalizeAction.finalize is called with txId", async () => {
+    program.parse(["node", "test", "finalize", mockTxId]);
+    expect(FinalizeAction).toHaveBeenCalledTimes(1);
+    expect(FinalizeAction.prototype.finalize).toHaveBeenCalledWith({txId: mockTxId});
+  });
+
+  test("FinalizeAction.finalize is called with custom RPC URL", async () => {
+    program.parse(["node", "test", "finalize", mockTxId, "--rpc", "https://custom.com"]);
+    expect(FinalizeAction.prototype.finalize).toHaveBeenCalledWith({
+      txId: mockTxId,
+      rpc: "https://custom.com",
+    });
+  });
+
+  test("throws error for unrecognized options", async () => {
+    const finalizeCommand = program.commands.find(cmd => cmd.name() === "finalize");
+    finalizeCommand?.exitOverride();
+    expect(() =>
+      program.parse(["node", "test", "finalize", mockTxId, "--invalid-option"]),
+    ).toThrowError("error: unknown option '--invalid-option'");
+  });
+});
+
+describe("finalize-batch command", () => {
+  let program: Command;
+  const mockTxId1 = "0x1111111111111111111111111111111111111111111111111111111111111111";
+  const mockTxId2 = "0x2222222222222222222222222222222222222222222222222222222222222222";
+
+  beforeEach(() => {
+    program = new Command();
+    initializeTransactionsCommands(program);
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  test("FinalizeAction.finalizeBatch is called with a single txId", async () => {
+    program.parse(["node", "test", "finalize-batch", mockTxId1]);
+    expect(FinalizeAction.prototype.finalizeBatch).toHaveBeenCalledWith({
+      txIds: [mockTxId1],
+    });
+  });
+
+  test("FinalizeAction.finalizeBatch is called with multiple txIds", async () => {
+    program.parse(["node", "test", "finalize-batch", mockTxId1, mockTxId2]);
+    expect(FinalizeAction.prototype.finalizeBatch).toHaveBeenCalledWith({
+      txIds: [mockTxId1, mockTxId2],
+    });
+  });
+
+  test("FinalizeAction.finalizeBatch is called with custom RPC", async () => {
+    program.parse([
+      "node", "test", "finalize-batch", mockTxId1, mockTxId2, "--rpc", "https://custom.com",
+    ]);
+    expect(FinalizeAction.prototype.finalizeBatch).toHaveBeenCalledWith({
+      txIds: [mockTxId1, mockTxId2],
+      rpc: "https://custom.com",
+    });
+  });
+});