Run a Fiber Node

Overview

This guide walks you through the process of setting up and running a Fiber Network Node (FNN) on the Testnet. You'll learn how to build the node from source or use a pre-built binary, configure it properly, and start it up.

Prerequisites

• Git (if building from source)
• Rust and Cargo (if building from source)
• Basic understanding of command line operations
• ckb-cli tool for key management

Building and Setting Up Your Node

1. Obtain the FNN Binary

You can either download a pre-built binary from the Fiber GitHub Releases page or build it from source:

git clone https://github.com/nervosnetwork/fiber.git
cd fiber
cargo build --release

This document used the v0.8.0 binary throughout the guide.

xattr -d com.apple.quarantine fnn fnn-migrate fnn-cli

2. Create Node Directory

Create a dedicated directory for your node and copy the necessary files:

mkdir /folder-to/my-fnn
# If using released binary, replace target/release/fnn with the path to your downloaded binary
cp target/release/fnn /folder-to/my-fnn
# Copy additional tools (v0.8.0+)
cp target/release/fnn-migrate /folder-to/my-fnn
cp target/release/fnn-cli /folder-to/my-fnn
cp config/testnet/config.yml /folder-to/my-fnn
cd /folder-to/my-fnn

3. Set Up Node Keys

FNN includes built-in wallet functionality for signing funding transactions. You'll need to create or import a private key:

create a new ckb account and get the lock_arg of the new account

ckb-cli account new

# example output
# address
#   mainnet: ckb1qzda0cr08m85hc8jlnfp3zer7xulejywt49kt2rr0vthywaa50xwsqtp83cu4pk8nysm9dngxezw546dyr5w8esx7rlyt
#   testnet: ckt1qzda0cr08m85hc8jlnfp3zer7xulejywt49kt2rr0vthywaa50xwsqtp83cu4pk8nysm9dngxezw546dyr5w8esgvgswn
# address(deprecated):
#   mainnet: ckb1qyqxz0r3e2rv0xfpk2mxsdjyaft56g8gu0nq8cjjeq
#   testnet: ckt1qyqxz0r3e2rv0xfpk2mxsdjyaft56g8gu0nq6avd4u
# lock_arg: 0x613c71ca86c79921b2b6683644ea574d20e8e3e6
# lock_hash: 0x1c506178212949e961f5949c916f70f5ba0f3b89b14ce2608f02201a41eb3ef7

Then export the existing key

mkdir ckb
# Export an existing key using ckb-cli
ckb-cli account export --lock-arg <lock_arg> --extended-privkey-path ./ckb/exported-key
# Extract just the private key (FNN only needs this part)
head -n 1 ./ckb/exported-key > ./ckb/key

4. Start the Node

Launch your node with logging enabled:

(You need to set a FIBER_SECRET_KEY_PASSWORD environment variable in the startup command to encrypt your wallet private key file. I used 123 here for demo purposes, but I recommend using a strong password.)

FIBER_SECRET_KEY_PASSWORD='123' RUST_LOG=info ./fnn -c config.yml -d .

The node will start syncing with the Testnet and output logs to the console. You can redirect the output to a file if needed.

Interacting with Your Node

Once your node is running, you can interact with it using the RPC interface or the CLI tool.

Using the CLI Tool (v0.8.0+)

v0.8.0 introduces fnn-cli, a command-line interface that provides a convenient way to manage your node without writing raw JSON-RPC requests:

# View node information
./fnn-cli info

# List connected peers
./fnn-cli peer list_peers

# List open channels
./fnn-cli channel list_channels

# List available commands
./fnn-cli --help

The CLI connects to the node's RPC endpoint (default: http://127.0.0.1:8227).

export NO_PROXY=127.0.0.1,localhost
./fnn-cli info

Using JSON-RPC Directly

You can also interact with the node using any HTTP client:

curl -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"node_info"}' \
  http://127.0.0.1:8227/

Version Compatibility and Upgrades

FNN is under active development, and protocol/storage format changes may occur between versions. Here's how to handle upgrades:

Safe Upgrade Process

1. Close all active channels before upgrading:

   • Use RPC to list all channels
   • Close them properly

2. Stop the node and clean the storage:

rm -rf /folder-to/my-fnn/fiber/store

3. Update the node:
   • Replace the FNN binary with the new version
   • Start the node again

Storage Migration (Optional)

If you want to preserve channel states during an upgrade:

1. Stop your node
2. Back up your data:

cp -r /folder-to/my-fnn/fiber/store /folder-to/my-fnn/fiber/store.backup

3. Run the migration tool:

./fnn-migrate -d /folder-to/my-fnn

4. Update and restart:
   • Replace the FNN binary
   • Start your node

Next Steps

Once your node is running, you can:

• Send and receive payments
• Explore more RPC methods