genlayer 0.22.1 → 0.23.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.23.0 (2025-07-15)
+
+### Features
+
+* fetch transaction receipt command ([#234](https://github.com/yeagerai/genlayer-cli/issues/234)) ([5cf868c](https://github.com/yeagerai/genlayer-cli/commit/5cf868c28ce036e41b7b40ed6cdde222cdc5dcf0))
+
 ## 0.22.1 (2025-07-14)
 
 ## 0.22.0 (2025-07-14)

package/dist/index.js

@@ -17856,7 +17856,7 @@ var require_semver2 = __commonJS({
 import { program } from "commander";
 
 // package.json
-var version = "0.22.1";
+var version = "0.23.0";
 var package_default = {
   name: "genlayer",
   version,
@@ -42909,6 +42909,51 @@ function initializeNetworkCommands(program2) {
   return program2;
 }
 
+// src/commands/transactions/receipt.ts
+var ReceiptAction = class extends BaseAction {
+  constructor() {
+    super();
+  }
+  validateTransactionStatus(status) {
+    const upperStatus = status.toUpperCase();
+    if (!(upperStatus in TransactionStatus)) {
+      const validStatuses = Object.values(TransactionStatus);
+      this.failSpinner(
+        "Invalid transaction status",
+        `Invalid status: ${status}. Valid values are: ${validStatuses.join(", ")}`
+      );
+      return;
+    }
+    return TransactionStatus[upperStatus];
+  }
+  async receipt({
+    txId,
+    status = TransactionStatus.FINALIZED,
+    retries,
+    interval,
+    rpc
+  }) {
+    const client = await this.getClient(rpc);
+    await client.initializeConsensusSmartContract();
+    this.startSpinner(`Waiting for transaction receipt ${txId} (status: ${status})...`);
+    try {
+      let validatedStatus = this.validateTransactionStatus(status);
+      if (!validatedStatus) {
+        return;
+      }
+      const result = await client.waitForTransactionReceipt({
+        hash: txId,
+        status: validatedStatus,
+        retries,
+        interval
+      });
+      this.succeedSpinner("Transaction receipt retrieved successfully", result);
+    } catch (error) {
+      this.failSpinner("Error retrieving transaction receipt", error);
+    }
+  }
+};
+
 // src/commands/transactions/appeal.ts
 var AppealAction = class extends BaseAction {
   constructor() {
@@ -42938,7 +42983,16 @@ var AppealAction = class extends BaseAction {
 };
 
 // src/commands/transactions/index.ts
+function parseIntOption(value, fallback2) {
+  const parsed = parseInt(value, 10);
+  return isNaN(parsed) ? fallback2 : parsed;
+}
 function initializeTransactionsCommands(program2) {
+  const validStatuses = Object.values(TransactionStatus).join(", ");
+  program2.command("receipt <txId>").description("Get transaction receipt by hash").option("--status <status>", `Transaction status to wait for (${validStatuses})`, TransactionStatus.FINALIZED).option("--retries <retries>", "Number of retries", (value) => parseIntOption(value, 100), 100).option("--interval <interval>", "Interval between retries in milliseconds", (value) => parseIntOption(value, 5e3), 5e3).option("--rpc <rpcUrl>", "RPC URL for the network").action(async (txId, options) => {
+    const receiptAction = new ReceiptAction();
+    await receiptAction.receipt({ txId, ...options });
+  });
   program2.command("appeal <txId>").description("Appeal a transaction by its hash").option("--rpc <rpcUrl>", "RPC URL for the network").action(async (txId, options) => {
     const appealAction = new AppealAction();
     await appealAction.appeal({ txId, ...options });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genlayer",
-  "version": "0.22.1",
+  "version": "0.23.0",
   "description": "GenLayer Command Line Tool",
   "main": "src/index.ts",
   "type": "module",

package/src/commands/transactions/index.ts

@@ -1,8 +1,29 @@
 import {Command} from "commander";
-import {TransactionHash} from "genlayer-js/types";
+import {TransactionStatus, TransactionHash} from "genlayer-js/types";
+import {ReceiptAction, ReceiptOptions} from "./receipt";
 import {AppealAction, AppealOptions} from "./appeal";
 
+function parseIntOption(value: string, fallback: number): number {
+  const parsed = parseInt(value, 10);
+  return isNaN(parsed) ? fallback : parsed;
+}
+
 export function initializeTransactionsCommands(program: Command) {
+  const validStatuses = Object.values(TransactionStatus).join(", ");
+  
+  program
+    .command("receipt <txId>")
+    .description("Get transaction receipt by hash")
+    .option("--status <status>", `Transaction status to wait for (${validStatuses})`, TransactionStatus.FINALIZED)
+    .option("--retries <retries>", "Number of retries", (value) => parseIntOption(value, 100), 100)
+    .option("--interval <interval>", "Interval between retries in milliseconds", (value) => parseIntOption(value, 5000), 5000)
+    .option("--rpc <rpcUrl>", "RPC URL for the network")
+    .action(async (txId: TransactionHash, options: ReceiptOptions) => {
+      const receiptAction = new ReceiptAction();
+      
+      await receiptAction.receipt({txId, ...options});
+    })      
+
   program
     .command("appeal <txId>")
     .description("Appeal a transaction by its hash")

package/src/commands/transactions/receipt.ts

@@ -0,0 +1,64 @@
+import {BaseAction} from "../../lib/actions/BaseAction";
+import {TransactionHash, TransactionStatus} from "genlayer-js/types";
+
+export interface ReceiptParams {
+  txId: TransactionHash;
+  status?: string | TransactionStatus;
+  retries?: number;
+  interval?: number;
+  rpc?: string;
+}
+
+export interface ReceiptOptions extends Omit<ReceiptParams, 'txId'> {}
+
+export class ReceiptAction extends BaseAction {
+  constructor() {
+    super();
+  }
+
+  private validateTransactionStatus(status: string): TransactionStatus | undefined {
+    const upperStatus = status.toUpperCase() as keyof typeof TransactionStatus;
+    
+    if (!(upperStatus in TransactionStatus)) {
+      const validStatuses = Object.values(TransactionStatus);
+      this.failSpinner(
+        "Invalid transaction status", 
+        `Invalid status: ${status}. Valid values are: ${validStatuses.join(", ")}`
+      );
+      return
+    }
+    
+    return TransactionStatus[upperStatus];
+  }
+
+  async receipt({
+    txId,
+    status = TransactionStatus.FINALIZED,
+    retries,
+    interval,
+    rpc,
+  }: ReceiptParams): Promise<void> {
+    const client = await this.getClient(rpc);
+    await client.initializeConsensusSmartContract();
+    this.startSpinner(`Waiting for transaction receipt ${txId} (status: ${status})...`);
+
+    try {
+      let validatedStatus = this.validateTransactionStatus(status);
+
+      if (!validatedStatus) {
+        return;
+      }
+        
+      const result = await client.waitForTransactionReceipt({
+        hash: txId,
+        status: validatedStatus,
+        retries,
+        interval,
+      });
+      
+      this.succeedSpinner("Transaction receipt retrieved successfully", result);
+    } catch (error) {
+      this.failSpinner("Error retrieving transaction receipt", error);
+    }
+  }
+} 

package/tests/actions/receipt.test.ts

@@ -0,0 +1,173 @@
+import {describe, test, vi, beforeEach, afterEach, expect} from "vitest";
+import {createClient, createAccount} from "genlayer-js";
+import type {TransactionHash} from "genlayer-js/types";
+import {TransactionStatus} from "genlayer-js/types";
+import {ReceiptAction, type ReceiptParams} from "../../src/commands/transactions/receipt";
+
+vi.mock("genlayer-js");
+
+describe("ReceiptAction", () => {
+  let receiptAction: ReceiptAction;
+  const mockClient = {
+    waitForTransactionReceipt: vi.fn(),
+    initializeConsensusSmartContract: vi.fn(),
+  };
+
+  const mockPrivateKey = "mocked_private_key";
+  const mockTxId = "0x1234567890123456789012345678901234567890123456789012345678901234" as TransactionHash;
+  const defaultRetries = 100;
+  const defaultInterval = 5000;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(createClient).mockReturnValue(mockClient as any);
+    vi.mocked(createAccount).mockReturnValue({privateKey: mockPrivateKey} as any);
+    receiptAction = new ReceiptAction();
+    vi.spyOn(receiptAction as any, "getPrivateKey").mockResolvedValue(mockPrivateKey);
+
+    vi.spyOn(receiptAction as any, "startSpinner").mockImplementation(() => {});
+    vi.spyOn(receiptAction as any, "succeedSpinner").mockImplementation(() => {});
+    vi.spyOn(receiptAction as any, "failSpinner").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  test("retrieves transaction receipt successfully with default options", async () => {
+    const mockReceipt = {status: "FINALIZED", data: {hash: mockTxId}};
+
+    vi.mocked(mockClient.waitForTransactionReceipt).mockResolvedValue(mockReceipt);
+
+    await receiptAction.receipt({
+      txId: mockTxId,
+      retries: defaultRetries,
+      interval: defaultInterval,
+    });
+
+    expect(mockClient.waitForTransactionReceipt).toHaveBeenCalledWith({
+      hash: mockTxId,
+      status: TransactionStatus.FINALIZED,
+      retries: defaultRetries,
+      interval: defaultInterval,
+    });
+    expect(receiptAction["succeedSpinner"]).toHaveBeenCalledWith(
+      "Transaction receipt retrieved successfully",
+      mockReceipt,
+    );
+  });
+
+  test("retrieves transaction receipt with custom options", async () => {
+    const mockReceipt = {status: "ACCEPTED", data: {hash: mockTxId}};
+
+    vi.mocked(mockClient.waitForTransactionReceipt).mockResolvedValue(mockReceipt);
+
+    await receiptAction.receipt({
+      txId: mockTxId,
+      status: "ACCEPTED",
+      retries: 50,
+      interval: 3000,
+    });
+
+    expect(mockClient.waitForTransactionReceipt).toHaveBeenCalledWith({
+      hash: mockTxId,
+      status: TransactionStatus.ACCEPTED,
+      retries: 50,
+      interval: 3000,
+    });
+    expect(receiptAction["succeedSpinner"]).toHaveBeenCalledWith(
+      "Transaction receipt retrieved successfully",
+      mockReceipt,
+    );
+  });
+
+  test("handles waitForTransactionReceipt errors", async () => {
+    vi.mocked(mockClient.waitForTransactionReceipt).mockRejectedValue(new Error("Mocked receipt error"));
+
+    await receiptAction.receipt({
+      txId: mockTxId,
+      retries: defaultRetries,
+      interval: defaultInterval,
+    });
+
+    expect(receiptAction["failSpinner"]).toHaveBeenCalledWith(
+      "Error retrieving transaction receipt",
+      expect.any(Error),
+    );
+  });
+
+  test("uses custom RPC URL for receipt operations", async () => {
+    const rpcUrl = "https://custom-rpc-url.com";
+    const mockReceipt = {status: "FINALIZED", data: {hash: mockTxId}};
+
+    vi.mocked(mockClient.waitForTransactionReceipt).mockResolvedValue(mockReceipt);
+
+    await receiptAction.receipt({
+      txId: mockTxId,
+      retries: defaultRetries,
+      interval: defaultInterval,
+      rpc: rpcUrl,
+    });
+
+    expect(createClient).toHaveBeenCalledWith(
+      expect.objectContaining({
+        endpoint: rpcUrl,
+      }),
+    );
+    expect(mockClient.waitForTransactionReceipt).toHaveBeenCalledWith({
+      hash: mockTxId,
+      status: TransactionStatus.FINALIZED,
+      retries: defaultRetries,
+      interval: defaultInterval,
+    });
+    expect(receiptAction["succeedSpinner"]).toHaveBeenCalledWith(
+      "Transaction receipt retrieved successfully",
+      mockReceipt,
+    );
+  });
+
+  test("validates transaction status and shows error for invalid status", async () => {
+    await receiptAction.receipt({
+      txId: mockTxId,
+      status: "INVALID_STATUS",
+      retries: defaultRetries,
+      interval: defaultInterval,
+    });
+
+    expect(receiptAction["failSpinner"]).toHaveBeenCalledWith(
+      "Invalid transaction status",
+      expect.stringContaining("Invalid status: INVALID_STATUS")
+    );
+    
+    expect(mockClient.waitForTransactionReceipt).not.toHaveBeenCalled();
+  });
+
+  test("accepts valid transaction statuses", async () => {
+    const mockReceipt = {status: "PENDING", data: {hash: mockTxId}};
+    vi.mocked(mockClient.waitForTransactionReceipt).mockResolvedValue(mockReceipt);
+
+    const testStatuses = [
+      {input: "accepted", expected: TransactionStatus.ACCEPTED},
+      {input: "FINALIZED", expected: TransactionStatus.FINALIZED},
+      {input: "pending", expected: TransactionStatus.PENDING},
+      {input: "COMMITTING", expected: TransactionStatus.COMMITTING},
+    ];
+
+    for (const {input, expected} of testStatuses) {
+      await receiptAction.receipt({
+        txId: mockTxId,
+        status: input,
+        retries: defaultRetries,
+        interval: defaultInterval,
+      });
+
+      expect(mockClient.waitForTransactionReceipt).toHaveBeenCalledWith({
+        hash: mockTxId,
+        status: expected,
+        retries: defaultRetries,
+        interval: defaultInterval,
+      });
+    }
+  });
+
+}); 

package/tests/commands/receipt.test.ts

@@ -0,0 +1,108 @@
+import {Command} from "commander";
+import {ReceiptAction} from "../../src/commands/transactions/receipt";
+import {vi, describe, beforeEach, afterEach, test, expect} from "vitest";
+import {initializeTransactionsCommands} from "../../src/commands/transactions";
+
+vi.mock("../../src/commands/transactions/receipt");
+
+describe("receipt command", () => {
+  let program: Command;
+  const mockTxId = "0x1234567890123456789012345678901234567890123456789012345678901234";
+
+  beforeEach(() => {
+    program = new Command();
+    initializeTransactionsCommands(program);
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  test("ReceiptAction.receipt is called with default options", async () => {
+    program.parse(["node", "test", "receipt", mockTxId]);
+    expect(ReceiptAction).toHaveBeenCalledTimes(1);
+    expect(ReceiptAction.prototype.receipt).toHaveBeenCalledWith({
+      txId: mockTxId,
+      status: "FINALIZED",
+      retries: 100,
+      interval: 5000,
+    });
+  });
+
+  test("ReceiptAction.receipt is called with custom options", async () => {
+    program.parse([
+      "node",
+      "test",
+      "receipt",
+      mockTxId,
+      "--status",
+      "ACCEPTED",
+      "--retries",
+      "50",
+      "--interval",
+      "3000",
+      "--rpc",
+      "https://custom-rpc-url-for-receipt.com",
+    ]);
+    expect(ReceiptAction).toHaveBeenCalledTimes(1);
+    expect(ReceiptAction.prototype.receipt).toHaveBeenCalledWith({
+      txId: mockTxId,
+      status: "ACCEPTED",
+      retries: 50,
+      interval: 3000,
+      rpc: "https://custom-rpc-url-for-receipt.com",
+    });
+  });
+
+  test("ReceiptAction is instantiated when the receipt command is executed", async () => {
+    program.parse(["node", "test", "receipt", mockTxId]);
+    expect(ReceiptAction).toHaveBeenCalledTimes(1);
+  });
+
+  test("throws error for unrecognized options", async () => {
+    const receiptCommand = program.commands.find(cmd => cmd.name() === "receipt");
+    receiptCommand?.exitOverride();
+    expect(() =>
+      program.parse(["node", "test", "receipt", mockTxId, "--invalid-option"]),
+    ).toThrowError("error: unknown option '--invalid-option'");
+  });
+
+  test("parses numeric options correctly", async () => {
+    program.parse([
+      "node",
+      "test",
+      "receipt",
+      mockTxId,
+      "--retries",
+      "25",
+      "--interval",
+      "1000",
+    ]);
+    expect(ReceiptAction.prototype.receipt).toHaveBeenCalledWith({
+      txId: mockTxId,
+      status: "FINALIZED",
+      retries: 25,
+      interval: 1000,
+    });
+  });
+
+  test("uses fallback value for invalid numeric options", async () => {
+    program.parse([
+      "node",
+      "test",
+      "receipt", 
+      mockTxId,
+      "--retries",
+      "invalid",
+      "--interval", 
+      "notanumber",
+    ]);
+    expect(ReceiptAction.prototype.receipt).toHaveBeenCalledWith({
+      txId: mockTxId,
+      status: "FINALIZED",
+      retries: 100,
+      interval: 5000,
+    });
+  });
+});