Fiber node integration

The resolver uses live Fiber RPC by default for invoice creation, automatic settlement polling, topology diagnostics, and payer-side route confidence.

Live runtime and test mode

Mode	Use it for	What the resolver does
Live Fiber RPC	Standard local, testnet, and production payment flows.	Probes the node, requests real invoices, polls invoice state, retries webhooks, and exposes node diagnostics.
Explicit mock	Automated tests or isolated UI work when no node can be used.	Runs only through `npm run dev:mock`; it is never selected as a silent fallback.

Inspect the active mode with GET /health. The console and GET /diagnostics expose node reachability and worker status rather than silently replacing an unavailable node with simulated invoices.

Configure a live invoice source

FIBER_RPC_URL=http://127.0.0.1:8227 \
FIBER_RPC_INVOICE_METHOD=new_invoice \
FIBER_RPC_GET_INVOICE_METHOD=get_invoice \
FIBER_RPC_PROBE_METHOD=node_info \
npm run dev

If the Fiber RPC endpoint requires basic authentication, also set FIBER_RPC_USERNAME and FIBER_RPC_PASSWORD. Method names are configurable so the adapter can match the Fiber node version you run.

FIBER_RPC_URL=http://127.0.0.1:8227 npm run fiber:check
FIBER_RPC_URL=http://127.0.0.1:8227 npm run fiber:invoice-check

The adapter uses node_info, list_peers, list_channels, new_invoice, and get_invoice to build diagnostics and invoice lifecycle data.

Merchant and payer node ownership

The resolver connects only to the merchant node. Its address can be local, use a custom port, or be hosted behind HTTPS and authentication. Keep this endpoint in server environment configuration; never place RPC credentials in an offer or payment link.

FIBER_RPC_URL=https://fiber-rpc.merchant.example \
FIBER_RPC_USERNAME=resolver \
FIBER_RPC_PASSWORD=secret \
npm run dev

The payer opens the stable offer link, requests a fresh invoice from the resolver, and pays that invoice using their own Fiber wallet or node. Fiber routing uses the invoice and network graph; the merchant does not need to know the payer RPC URL.

Multi-tenant boundaryOne resolver deployment currently maps to one merchant node. A hosted multi-merchant service needs a server-side tenant connection registry with encrypted credentials and ownership checks. Never accept an arbitrary node URL from a browser request because that creates credential and SSRF risks.

Topology and payment readiness

For a controlled integration test, an operator may configure a known payer fixture alongside the merchant node. This is optional diagnostic tooling, not a requirement for serving offers or receiving payments from real users.

MERCHANT_FIBER_RPC_URL=http://127.0.0.1:8227 \
PAYER_FIBER_RPC_URL=http://127.0.0.1:8229 \
npm run fiber:topology-check

GET /topology and the SDK topology client inspect direct channels, shared counterparties, channel state, asset visibility, pending TLCs, and usable payer outbound capacity. The returned report includes blockers, warnings, next actions, and a fixture recommendation.

Scenario: direct channel has insufficient outbound liquidity

Readiness stays false before an invoice is paid. The response points to the topology and capacity blocker instead of returning a vague payment failure. A wallet can surface the next action without pretending the merchant has rejected the offer.

Route dry-runs

After an invoice exists, the payer application uses its own node through the SDK to perform a send_payment dry-run. This gives the payer a stronger confidence signal without disclosing its node to the merchant resolver.

FIBER_INVOICE=fibt1... \
PAYER_FIBER_RPC_URL=http://127.0.0.1:8229 \
npm run fiber:route-check

Route failures are normalized into a stable code, summary, likely causes, and next actions while the raw Fiber node error remains attached for diagnostics. This lets applications show actionable wording without discarding the source failure.

const route = await payer.checkPaymentRoute(invoice, {
  timeoutSeconds: 60,
  maxFeeAmount: 100000,
  maxParts: 3
});

if (!route.ok) {
  console.log(route.failure.summary);
  console.log(route.failure.next_actions);
}

Guarded direct-channel fixture

The fixture command is report-only until an explicit opt-in flag is set. It compares the current topology against the desired direct channel and proposes either opening or merchant acceptance steps.

MERCHANT_FIBER_RPC_URL=http://127.0.0.1:8227 \
PAYER_FIBER_RPC_URL=http://127.0.0.1:8229 \
FIBER_DIRECT_CHANNEL_FUNDING_AMOUNT=10000000000 \
FIBER_MERCHANT_PEER_ADDRESS=/ip4/127.0.0.1/tcp/8228/p2p/... \
npm run fiber:direct-channel-fixture

# Only after reviewing the plan:
FIBER_FIXTURE_OPEN_DIRECT_CHANNEL=true npm run fiber:direct-channel-fixture

Keep fixtures out of merchant flowsChannel opening is an operator action. A wallet or checkout should display readiness diagnostics and next actions, not silently mutate channel topology.

Live end-to-end checks

RESOLVER_URL=http://127.0.0.1:8787 \
MERCHANT_FIBER_RPC_URL=http://127.0.0.1:8227 \
PAYER_FIBER_RPC_URL=http://127.0.0.1:8229 \
npm run fiber:e2e-check

# Use a dry-run-only path while diagnosing routes:
FIBER_E2E_DRY_RUN_ONLY=true \
FIBER_E2E_TRAMPOLINE_HOPS=<pubkey> \
npm run fiber:e2e-check

Run the unit and resolver smoke suite before live checks. The live commands are integration tools and require actual endpoints, channel state, and suitable testnet funds.

PreviousMerchant operations NextSDK