@lumiapassport/uo-debug

Lightweight debugger for Lumia Beam ERC-4337 user operations. Ship with a terminal CLI (with colorful tracing) and library exports so other tools or UIs can reuse the same logic.

Installation

npm install @lumiapassport/uo-debug

You can run the CLI bundled with the package:

npx @lumiapassport/uo-debug --tx 0x...

Or install it globally to expose uo-debug system-wide:

npm install -g @lumiapassport/uo-debug
uo-debug --uo <userOpHash>

CLI Usage

Environment variables mirror the legacy debugWallet.js script but now require the UO_DEBUG_ prefix (legacy names still work for backward compatibility):

| Variable | Purpose | Default | | --- | --- | --- | | UO_DEBUG_RPC_URL (legacy RPC_URL) | Lumia Beam RPC endpoint | https://beam-rpc.lumia.org | | UO_DEBUG_TRACE_TIMEOUT (legacy DEBUG_TRACE_TIMEOUT) | debug_traceTransaction timeout string | 20s | | UO_DEBUG_NATIVE_TOKEN_SYMBOL (legacy NATIVE_TOKEN_SYMBOL) | Display label for the native token | LUMIA | | UO_DEBUG_NATIVE_TOKEN_SUBUNIT (legacy NATIVE_TOKEN_SUBUNIT) | Subunit label for value summaries | attoLUMIA | | UO_DEBUG_EXPLORER_TX_BASE_URL (legacy EXPLORER_TX_BASE_URL) | Prefix for explorer hyperlinks in failure summaries | https://beam-explorer.lumia.org/tx/ | | UO_DEBUG_ALIAS_FILE (legacy ALIAS_FILE) | Path to aliases.json when not using the bundled file | aliases.json | | UO_DEBUG_SIGNATURES_FILE (legacy SIGNATURES_FILE) | Path to signatures.json when not using the bundled file | signatures.json | | UO_DEBUG_DISABLE_4BYTE_LOOKUP (legacy DISABLE_4BYTE_LOOKUP) | Disable online 4byte.xyz selector lookups | false |

uo-debug --tx <txHash>
uo-debug --uo <userOpHash> --rpc https://beam-rpc.lumia.org

Use --timeout to override the trace timeout and --rpc to specify another endpoint.

Library Usage

Import the entry point in your Node (or bundler) project to reuse the debugging logic programmatically:

import { runDebug, traceTransaction } from "@lumiapassport/uo-debug";

await runDebug({ txHash: "...", rpc: process.env.RPC_URL });

runDebug returns when tracing finishes and reuses the same alias/signature files shipped in the package root. If you need to resolve selectors without running the CLI, import traceTransaction or inspectUserOperation directly.

Sharing Configuration

aliases.json and signatures.json live next to the CLI and are included in the package. Drop in custom files by setting UO_DEBUG_ALIAS_FILE / UO_DEBUG_SIGNATURES_FILE (absolute paths or relative to your working directory); the legacy ALIASES_FILE / SIGNATURES_FILE environment names still work.

Set UO_DEBUG_DISABLE_4BYTE_LOOKUP=true (or DISABLE_4BYTE_LOOKUP=true) to skip live 4byte.xyz selector resolution when offline.

Browser or UI Integration

Because the same renderer is used for both CLI and library consumers, you can capture the terminal output (ANSI colors from picocolors) and pipe it into browser-friendly widgets that respect ANSI escape sequences. For richer integrations, re-use the exported helpers (inspectUserOperation, traceTransaction, selector resolvers, etc.) to build structured JSON and render your own markup.

React integration pattern

Run the debugger inside a trusted Node/Edge handler and expose an API to your React app:

// server/debug.js
import express from "express";
import { runDebug } from "@lumiapassport/uo-debug";

const app = express();

app.get("/api/uo-debug", async (req, res) => {
  try {
    await runDebug({ uoHash: req.query.uo, rpc: process.env.RPC_URL });
    res.send("Trace completed"); // or capture structured data instead of relying on console
  } catch (err) {
    res.status(500).send(err.message);
  }
});

The React client can then fetch the endpoint and render the returned ANSI-friendly text inside <pre> (use ansi-to-react, ansi-html, etc. to keep the colors). For richer views, alter runDebug / traceTransaction to return the annotated call tree and gas summaries, and render them directly as JSON-driven components.

Keep the RPC settings in .env (or pass custom values to runDebug) so the server controls provider access while the browser only renders prepared output.

Running Locally

Use npm run debug -- --tx <txHash> from the workspace root (after installing dependencies) to mimic the CLI shipped inside the package.