FiberTraceboxFailure replay infrastructure

Docs/API

FiberTracebox integration surface

The app runs fully in sandbox mode for deterministic demos and can also connect to a Fiber Network Node JSON-RPC endpoint for live payment dry-runs or explicitly enabled live sends.

API Examples

Health

curl http://localhost:3000/api/health

Run scenario

curl -X POST http://localhost:3000/api/scenarios/run -H 'content-type: application/json' -H "x-api-key: $FIBERTRACEBOX_API_KEY" -d '{"scenario":"route-capacity"}'

Live dry-run

curl -X POST http://localhost:3000/api/traces -H 'content-type: application/json' -H "x-api-key: $FIBERTRACEBOX_API_KEY" -d '{"invoice":"<fiber-invoice>","dryRun":true}'

Replay trace

curl -X POST http://localhost:3000/api/traces/<traceId>/replay -H "x-api-key: $FIBERTRACEBOX_API_KEY"

Markdown report

curl http://localhost:3000/api/traces/<traceId>/report?format=markdown

CLI Examples

Use these from the project folder while developing locally.

npm run cli -- health
npm run demo:judge
npm run cli -- scenario run route-capacity
npm run cli -- live <fiber-invoice>
npm run cli -- trace list
npm run cli -- replay <traceId>
npm run cli -- report <traceId> --format markdown

Optional linked binary

Run npm run build:cli, then npm link once if you want the global fibertracebox command.

npm run build:cli
npm link
fibertracebox health
fibertracebox scenario run route-capacity
fibertracebox live <fiber-invoice>
fibertracebox trace list

CLI Setup

The local CLI reads FIBERTRACEBOX_API_URL and FIBERTRACEBOX_API_KEY from your shell environment. If write protection is enabled, export the same API key used by the server before running write commands.

export FIBERTRACEBOX_API_URL=http://localhost:3000
export FIBERTRACEBOX_API_KEY=<your-api-key>

Sandbox Mode

Sandbox mode simulates Fiber payment lifecycle events with deterministic topology, capacity, peer, channel, fee, timeout, retry, and liquidity failures. It is designed for repeatable hackathon demos and CI tests without requiring a live Fiber node.

Optional Fiber RPC Mode

Set FIBER_RPC_URL, FIBER_RPC_ENABLED=true, and FIBER_RPC_LIVE_ENABLED=true to connect to FNN. The app probes node_info and list_channels, then uses send_payment for invoice checks. Live sends require FIBER_RPC_ALLOW_LIVE_PAYMENTS=true; otherwise requests are dry-runs.

Live Node Boundaries

  • Run FNN separately and keep its JSON-RPC port private.
  • Use a valid Fiber invoice, connected peers, open channels, and sufficient liquidity.
  • Replay-to-Fix remains analytical for live traces because replay changes can move funds or mutate channels.
  • Sandbox scenario cards are synthetic demos; use the Live Fiber RPC panel for FNN-backed checks.

Evidence Bundles

Successful live-payment proof is stored in payment-testing/. Raw failed FNN captures and fingerprint reports are stored in failed-transactions/.

  • payment-testing/trace_49a88732-e613-44c1-b65d-60e78c7c1de2-fibertracebox-report.md
  • failed-transactions/route-capacity/send-payment-error.json
  • failed-transactions/peer-offline/send-payment-route-unavailable.json

What Works Today

  • Working sandbox adapter and deterministic scenario runner.
  • Fiber RPC health probing and invoice dry-run/live-send adapter.
  • Failure fingerprint catalog with diagnosis, likely causes, and fixes.
  • Replay-to-Fix engine with recommended smallest fix.
  • Markdown and JSON report generation.
  • Dashboard, API routes, CLI, SDK, Supabase schema, and tests.