FFiber Offers
Documentation / Reference

Production and security

The included resolver is deliberately local-first so teams can build against a small, inspectable surface. A public payment deployment needs durable data, authenticated operations, secure key handling, monitoring, and real Fiber-node validation.

Deployment baseline

RESOLVER_API_KEY=change-me \
RESOLVER_PUBLIC_URL=https://resolver.example \
FIBER_RPC_URL=http://127.0.0.1:8227 \
npm run dev
  • Terminate TLS at a trusted reverse proxy and expose the resolver only through HTTPS.
  • Set RESOLVER_PUBLIC_URL to the externally reachable origin so links and webhooks use the correct address.
  • Protect operator inventory, webhook configuration and history, and merchant write endpoints with RESOLVER_API_KEY. The browser exchanges it for a signed HttpOnly session cookie.
  • Store API keys and Fiber RPC credentials in a secret manager, not source files or browser code.
  • Run the PostgreSQL migration service before accepting live payments and use Redis/BullMQ for distributed maintenance work.

Each resolver deployment currently maps to one merchant node configured through FIBER_RPC_URL. The endpoint may use a custom port or hosted private URL. Do not configure customer payer nodes in the resolver and do not accept RPC URLs from public requests.

Settlement and webhook workers

The Docker deployment runs BullMQ workers against Redis. The interval-based worker remains a single-process development fallback.

RESOLVER_WORKERS_ENABLED=true
RESOLVER_WORKERS_RUN_ON_START=true
RESOLVER_SETTLEMENT_SYNC_INTERVAL_MS=3000
RESOLVER_WEBHOOK_RETRY_INTERVAL_MS=30000
RESOLVER_WEBHOOK_MAX_ATTEMPTS=8
RESOLVER_WEBHOOK_RETRY_MIN_AGE_MS=30000
RESOLVER_WEBHOOK_TIMEOUT_MS=10000

Monitor the worker state reported by GET /diagnostics. The delivery timeout defaults to 10 seconds, and failed webhook events retain their delivery history so operators can inspect and retry them without losing context.

Security boundaries

BoundaryRequired controlReason
Offer lifecycle keyMerchant-owned encrypted key storage and rotation plan.The signature protects offer content and revocation; the resolver separately verifies the Fiber node identity.
Resolver API keyScoped per merchant or service, rotated, and never exposed to wallets.Protects registration, status updates, syncs, and webhook operations.
Webhook secretEncrypted storage, HMAC verification, event ID deduplication, timestamp tolerance.Protects fulfillment from forged or replayed delivery requests.
Fiber RPCPrivate network access or authenticated RPC access.Prevents an untrusted party from controlling invoice or node diagnostics calls.
Offer and request dataRate limits, request-size limits, structured validation, and observability.Protects the public resolver surface from abuse and makes failures diagnosable.

Operational checklist

  1. Run npm run verify and review the resolver smoke flow on every release candidate.
  2. Probe the live node with npm run fiber:check before deploying a live invoice source.
  3. Probe the merchant node from the resolver. Run route dry-runs in the payer application against its own node; use pair topology only when both endpoints are controlled test fixtures.
  4. Alert on resolver reachability, worker failures, high webhook failure rates, and failed invoice syncs.
  5. Back up durable resolution and webhook event data. Reconciliation records are business records, not transient UI state.
  6. Log offer ID, resolution ID, webhook event ID, and delivery ID together so an operator can trace a payment attempt end to end.
Independent merchant deploymentRun npm run cli -- init before the first Docker startup, then use npm run cli -- doctor to prove that the resolver and merchant CLI are connected to the same FNN. PostgreSQL is authoritative in Docker; the JSON adapter remains a local single-process fallback.

Troubleshooting guide

The Fiber RPC endpoint is unavailable

Run npm run fiber:check and inspect GET /diagnostics. The resolver reports the node failure and does not silently replace live invoices with simulated ones.

Readiness is blocked

Read summary, blockers, and next_actions. Merchant readiness checks node reachability and offer validity. The payer wallet should inspect its own outbound liquidity and route dry-run result.

The same checkout received an unexpected response

Retry the invoice request with the original idempotency key and identical amount and asset. A changed request with the same key is rejected with IDEMPOTENCY_KEY_REUSED by design.

A webhook is pending or failed

Inspect the event outbox and delivery response. Verify the receiver returns a 2xx status quickly, validates the HMAC against the raw body, and deduplicates event IDs. Retry explicitly or enable the worker after the receiver is healthy.

A live payment does not route

Run a dry-run from the payer's own node. Use the optional pair topology report only in a controlled environment where the operator owns both endpoints. Keep the raw Fiber error for debugging, but communicate the normalized failure summary and next action to the user.

Release readiness

Before a testnet merchant pilot

Use HTTPS, real Fiber RPC endpoints, a persistent data store, scoped API credentials, a verified webhook receiver, background worker monitoring, and live topology and route checks.

Fiber Offers is built to be useful infrastructure in the wider Fiber stack. Treat the documented interfaces as integration contracts and keep deployment hardening in step with the value being moved through them.

PreviousSDKBack to startDocumentation overview