npm package: @lumiapassport/uo-debug
Description: ERC-4337 user operation debugger for Lumia Passport with CLI and library exports.
Author: Lumia Passport
Latest version: 0.3.0

# @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

```bash
npm install @lumiapassport/uo-debug
```

You can run the CLI bundled with the package:

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

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

```bash
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` |

```bash
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:

```js
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:

```js
// 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.