Toolchain Overview

The Fiber ecosystem includes several tools and libraries that serve different roles. This page provides a complete map to help you understand what's available and choose the right tool for your use case.

Ecosystem Map

┌────────────────────────────────────────────────────────────────────────────────────┐
│ Application Layer                                                                  │
│  ┌──────────────────────┐  ┌──────────────────────┐  ┌──────────────────────────┐  │
│  │ Operators / backends │  │ Wallets / dApps      │  │ Native mobile / desktop  │  │
│  │ Services any lang    │  │ Browser UI (JS/TS)   │  │ Android / iOS / C/C++    │  │
│  └──────────┬───────────┘  └──────────┬───────────┘  └────────────┬─────────────┘  │
│             │                         │                           │                │
│             ▼                         ▼                           ▼                │
├────────────────────────────────────────────────────────────────────────────────────┤
│ Access / API Layer                                                                 │
│  ┌──────────────────────┐  ┌──────────────────────┐  ┌──────────────────────────┐  │
│  │ HTTP RPC / fnn-cli   │  │ fiber-js API         │  │ fiber-ffi C ABI wrappers │  │
│  │ Native node control  │  │ JS/TS API + workers  │  │ JNI / Swift / C binding  │  │
│  └──────────┬───────────┘  └──────────┬───────────┘  └────────────┬─────────────┘  │
│             │                         │                           │                │
│             ▼                         ▼                           ▼                │
├────────────────────────────────────────────────────────────────────────────────────┤
│ Runtime Layer                                                                      │
│  ┌──────────────────────┐  ┌──────────────────────┐  ┌──────────────────────────┐  │
│  │ fnn native binary    │  │ fiber-wasm           │  │ fiber-ffi dynamic lib    │  │
│  │ crates/fiber-bin     │  │ crates/fiber-wasm    │  │ exploratory C ABI        │  │
│  └──────────┬───────────┘  └──────────┬───────────┘  └────────────┬─────────────┘  │
│             │                         │                           │                │
│             └─────────────────────────┼───────────────────────────┘                │
│                                         ▼                                          │
├────────────────────────────────────────────────────────────────────────────────────┤
│ Shared Core Layer                                                                  │
│  ┌──────────────────────────────────────────────────────────────────────────────┐  │
│  │ fiber-lib (package name: fnn)                                                │  │
│  │ Actors, RPC handlers, channels, graph, invoices, payments                    │  │
│  └──────────────────────────────────────┬───────────────────────────────────────┘  │
│                                         ▼                                          │
├────────────────────────────────────────────────────────────────────────────────────┤
│ Shared Supporting Crates / Assets                                                  │
│  fiber-store · fiber-types · fiber-json-types · fiber-sphinx · fiber-scripts       │
└────────────────────────────────────────────────────────────────────────────────────┘

Runtime Stacks

fnn — Rust Native Node

fnn is the reference implementation of the Fiber Network Node, written in Rust. It runs as a native binary on Linux, macOS, and Windows. In the Fiber source tree, the fnn binary is built from crates/fiber-bin, which depends on the shared crates/fiber-lib crate.

Choose fnn if:

• You want to run a production node on a server
• You need the best performance and full feature set
• You want to be a relay node or liquidity provider on the network

fiber-js — Browser WASM Node

fiber-js is the JavaScript/TypeScript API layer above Fiber WASM. It is bundled for browser runtime environments, starts Web Workers for the Fiber node and IndexedDB storage, and exposes common Fiber node operations through a JS API. It also targets modern mobile browsers that support WebAssembly, Web Workers, and IndexedDB, so browser wallets and dApps can offer Fiber functionality on mobile devices without a native app.

The browser stack has one more layer than the native stack: application code calls @nervosnetwork/fiber-js, fiber-js loads crates/fiber-wasm through a worker, and fiber-wasm wraps the same shared fiber-lib node core with wasm-bindgen.

fiber-js is close to the Fiber RPC shape for common channel, peer, invoice, payment, graph, and info workflows, but it is not a full replacement for fnn. The native fnn binary remains the more complete choice for long-running nodes, production operations, CCH, watchtower, profiling, and other advanced node scenarios.

Choose fiber-js if:

• You want to build a browser-based wallet or dApp
• You need the same Fiber integration to work in desktop and mobile browsers
• You don't want to run a separate server
• You are building a web game with micro-payments

fiber-ffi — Native Mobile / C ABI Node

fiber-ffi wraps the shared Fiber node core as a C ABI exposed through a dynamic library and fiber_ffi.h. It lets Android apps, iOS apps, C/C++ programs, desktop apps, and other native host runtimes embed a Fiber node in-process while keeping platform-specific work in JNI bridges, Swift bridging headers, or host-language wrappers.

The FFI path is different from fiber-js: it targets native app runtimes rather than browser runtimes, and the host app is responsible for dynamic library packaging, platform lifecycle, threading, string ownership, private-key handling, and app sandbox paths.

Choose fiber-ffi if:

• You are exploring a native Android or iOS app integration
• You need a C ABI boundary for a non-JavaScript runtime
• You want to prototype language bindings or SDK shape above the Fiber node core

Access Layer

HTTP RPC

The HTTP JSON-RPC interface is the standard way to interact with a running native fnn node. Any language with an HTTP client can use it.

Choose HTTP RPC if:

• You have a running fnn node and want to control it programmatically
• You are building a backend service that integrates with Fiber
• You prefer to use a language other than JavaScript/TypeScript

See the API Reference for details.

fiber-js API

The @nervosnetwork/fiber-js API is the browser-facing integration layer. It does not talk to a local HTTP server. Instead, it sends commands to its Fiber Web Worker, and that worker invokes the functions exported by fiber-wasm.

fiber-ffi C ABI

The fiber-ffi C ABI is the native embedding boundary. Host applications call functions declared in fiber_ffi.h, receive status codes, returned data, and event callbacks, and wrap those C-level details in a platform runtime such as an Android JNI bridge, an iOS Swift runtime, or a C/C++ integration layer.

Runtime-Specific Operations

The native, WASM, and FFI runtimes have different operational surfaces. Native fnn exposes HTTP RPC and CLI-based node-maintenance tooling. fiber-js embeds the WASM node in browser workers, uses IndexedDB-backed storage through the WASM database worker, and presents a JS/TS API to application code. fiber-ffi exposes a C ABI through a dynamic library and leaves platform lifecycle, packaging, and host-language wrappers to the app. These paths share fiber-lib underneath, including the store version check used when each runtime opens its store.

fnn-cli

fnn-cli is the official command-line tool for managing a Fiber node. It supports both one-shot commands and an interactive REPL with tab completion.

Storage Migration

Storage version checking is part of the shared Fiber node startup path. Native fnn, fiber-wasm, and fiber-ffi all call the store opening path from crates/fiber-lib, which initializes the version for a new store and refuses to open an incompatible or older store that needs migration.

Starting from v0.9.0, migration is built into the fnn binary and runs automatically on startup when needed (with user confirmation). The standalone fnn-migrate binary, previously built from the migrate directory, was deprecated and removed in v0.9.0. For databases created before v0.8.x (database version older than 20260302100001), you must first upgrade using the v0.8.x fnn-migrate tool before starting the current fnn binary. See the backup guide for details.

Cryptography & On-Chain Scripts

fiber-sphinx

fiber-sphinx is the cryptography library implementing Sphinx-based onion routing for Fiber's payment privacy. It handles the construction and peeling of onion packets used in multi-hop payments.

fiber-scripts

fiber-scripts contains the CKB on-chain scripts that secure Fiber payment channels:

• Funding Lock: Secures the multi-sig output that funds a channel
• Commitment Lock: Enforces the revocation mechanism and dispute resolution

Decision Guide