Skip to content
nervosnetworkPublic

About

A scalable, privacy-by-default payment & swap network

Topics

Resources

Stars

60 stars

Watchers

7 watching

Forks

Repository files navigation

Fiber Network Node

Fiber Network Node (FNN) is a reference node implementation of Fiber Network Protocol (FNP). Fiber network is a peer-to-peer payment/swap network (like Lightning Network). We believe payment and swap are the two foundational primitives of finance.

Features

  • Multiple assets support, e.g. stable coins, RGB++ assets issued on Bitcoin ledger, and UDT assets issued on CKB ledger;
  • Extremely low-cost micropayments, e.g. 0.0001 cent payment with 0.00000001 cent fee;
  • Instant swap between any asset pairs, as long as there's available channel paths;
  • Cross-network asset payment/swap, e.g. from Lightning network to Fiber network, and vice versa;
  • Watchtower support, make it easier for node operators;
  • Multi-hop payment, anyone can facilitate payments and earn payment fees by running a fiber node and becoming a hop on payment paths;
  • Low latency, e.g. 0.0001 cent payment in your p2p connection latency, e.g. 20ms;
  • High throughput, because transactions are only processed by involved peers, no network consensus required;
  • High privacy, your transactions are only seen by involved peers;
  • Based on more advanced cryptographic techniques to ensure security and privacy, e.g. hash-based HTLC payment contracts today, with PTLC planned as a future direction;
  • Composable with other contracts/scripts on CKB;

!!! The implementation is still a work-in-progress and will have iterations even after mainnet, please use it with caution and report any issues/limitations in the issue tracker.

TODO

  • Establishing connections with other fiber nodes
  • Creating and closing fiber channel
  • Payments over fiber channel (via fiber-scripts)
  • Basic Multi-Path Payment (MPP)
  • Cross-network asset transfer
  • Web-browser friendly runtime (WASM/fiber-js, productization in progress)
  • Programmable conditional payment — official roadmap item covering PTLC, hold-invoice application protocols, on-chain contract conditions, and agent fair exchange
  • Advanced channel liquidity management — under active development (Loop In/Out and provider mode), not yet released
  • Atomic multi-path payment — long-term research direction (Basic MPP already released)

Quick Install (One-liner)

# Install to default location (~/.fiber)
curl -sSfL https://raw.githubusercontent.com/nervosnetwork/fiber/main/tools/install/install.sh | bash

# Install mainnet non-interactively with a trusted CKB RPC endpoint
curl -sSfL https://raw.githubusercontent.com/nervosnetwork/fiber/main/tools/install/install.sh | INSTALL_DIR=/opt/fiber FNN_VERSION=0.9.0 NETWORK=mainnet CKB_RPC_URL=https://your-trusted-mainnet-ckb-rpc.example bash

Mainnet installations do not select a public CKB RPC endpoint automatically. The guided installer prompts for one; bootstrap or non-interactive installations require CKB_RPC_URL to be set explicitly.

Build from source and run a testnet node

  1. Build the project, if you are using the released binary, you can skip this step:
cargo build --release
  1. Create a data folder for the node, then copy the built binary and testnet config file to it:
mkdir /folder-to/my-fnn
// if you are using the released binary, replace target/release/fnn with the path of released binary
cp target/release/fnn /folder-to/my-fnn
cp config/testnet/config.yml /folder-to/my-fnn
cd /folder-to/my-fnn
  1. FNN has the built-in wallet functionality to sign funding transactions, let's create or import a private key first. The private key is stored in the data folder and named ckb/key. You may use the ckb-cli to generate a new key or export an existing key:
mkdir ckb
ckb-cli account export --lock-arg <lock_arg> --extended-privkey-path ./ckb/exported-key
// ckb-cli exports master private key and chain code, FNN only needs the private key part
head -n 1 ./ckb/exported-key > ./ckb/key
// the exported key file can be deleted after the private key is extracted
rm ./ckb/exported-key
  1. Start the node, by default it will output logs to the console, you may redirect it to a file. Before starting, you must set the FIBER_SECRET_KEY_PASSWORD environment variable to encrypt the wallet private key file (which was stored in plain text during the previous step). Additionally, you can configure logging verbosity with the RUST_LOG environment variable—use predefined levels like info, debug, or trace, or specify granular logging with patterns such as info,fnn=debug to enable debug logs only for the FNN module.
FIBER_SECRET_KEY_PASSWORD='YOUR_PASSWORD' RUST_LOG='info' ./fnn -c config.yml -d .

Run with Docker

Fiber release tags publish official container images to Docker Hub at nervos/fiber and mirror the same tags to GHCR at ghcr.io/nervosnetwork/fiber. Detailed Docker usage, including startup, local builds, fnn-cli, and migration, is documented in docker/README.md.

Upgrading to the V2-only release

This release only supports V2 peers and channels. Peers without the CHANNEL_V2 feature are rejected during the Fiber Init handshake.

Existing databases at epoch 20260925120000 can be upgraded in place when all unfinished channels have valid, persisted V2 signing sessions. V2 channels do not need to be closed. The new storage epoch is 20261113000001.

  1. Stop the node and back up its complete data directory before upgrading.
  2. Start the new binary with the existing database and confirm the migration. Preflight lists unfinished V1 channels and refuses the upgrade without changing records or the database version. If refused, use the old binary to close those V1 channels and finish pending payments, delivery and on-chain settlement, then retry.
  3. The migration retains V2 signing intents, nonce seeds, signatures and replay history unchanged. Fully completed V1 records and their indexes are retained byte-for-byte in a read-only archive, outside the V2 runtime's channel tables.

Legacy watchtower history is archived only for this node's safely closed channels, with matching funding keys. Local entries without a trustworthy final channel state are refused. Legacy third-party watchtower entries are outside this migration's supported scope: keep their original service and database protecting them; they are never silently discarded. No chain queries or replacement sessions are used to guess whether a legacy channel has finished.

Orphan inbound/outbound WaitingForPeer opening records are archived only when no actor or persisted funding/watch evidence exists. The requested funding amount is not evidence that funds were locked. Later opening stages still require the old binary to finish recovery. Unsupported, corrupt and nonempty unversioned stores are not cleared or silently initialized. Older layouts must first be upgraded with their matching old release's migration tools.

Watchtower RPC clients must explicitly send channel_features: "0x1" when creating a watched channel. Missing features, the old field name alone, and explicit legacy features are rejected rather than silently registered as V2.

Do not run the old binary on the migrated database, or restore a stale backup as a live channel after the upgraded node has signed new commitments.

Documentation

We are in an actively developing stage, don't hesitate to report issues or ask for help in the channel of the Nervos dev community.

Network node documentation

License

This project is licensed under the MIT License.

About

A scalable, privacy-by-default payment & swap network

Topics

Resources

Stars

60 stars

Watchers

7 watching

Forks

Releases

Packages

Used by

Contributors

Languages