Fiber Network Node

https://github.com/nervosnetwork/fiber
Admin
Fiber Network Node (FNN) is a reference node implementation of the Fiber Network Protocol (FNP), a...
Tokens:64,303
Snippets:635
Trust Score:7.9
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install Nginx

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/fiber-node-wss.md

Compiles and installs the configured Nginx binary. This step should be run after the configure script completes successfully.

```bash
sudo make
sudo make install
```

--------------------------------

### Start Nodes for Testing

Source: https://github.com/nervosnetwork/fiber/blob/develop/tests/bruno/e2e/open-use-close-a-channel/README.md

Execute this command to start the necessary nodes for running the fiber network tests. This is a prerequisite for the subsequent test execution.

```bash
./tests/nodes/start.sh

```

--------------------------------

### Start Fiber Service and List Peers

Source: https://github.com/nervosnetwork/fiber/blob/develop/fiber-js/README.md

This JavaScript code snippet demonstrates how to start the Fiber service with a given configuration and then invoke the 'list_peers' command. Ensure that `randomSecretKey()` and `undefined` are appropriately handled or replaced based on your application's needs.

```javascript
await fiber.start(testnetConfig, randomSecretKey(), randomSecretKey(), undefined, "info", "/wasm");
console.log(await fiber.invokeCommand("list_peers", []));
```

--------------------------------

### Install Nginx Dependencies

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/fiber-node-wss.md

Installs necessary packages for building and configuring Nginx with stream support. Ensure your system is up-to-date before running.

```bash
sudo apt update
sudo apt install -y build-essential libpcre3 libpcre3-dev zlib1g zlib1g-dev libssl-dev jq
```

--------------------------------

### Start 3 Nodes with Default Balances

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/dev/README.md

This command starts three Fiber network nodes (FNN) and one CKB node. It automatically initializes the CKB dev chain if it hasn't been set up yet. Use this for standard development node startup.

```bash
./tests/nodes/start.sh
```

--------------------------------

### Start the Node with Environment Variables

Source: https://github.com/nervosnetwork/fiber/blob/develop/README.md

Launch the FNN node, setting the password for the private key encryption and configuring logging verbosity.

```bash
FIBER_SECRET_KEY_PASSWORD='YOUR_PASSWORD' RUST_LOG='info' ./fnn -c config.yml -d .
```

--------------------------------

### Build Fiber JS

Source: https://github.com/nervosnetwork/fiber/blob/develop/fiber-js/README.md

Install dependencies and build the project from the fiber root directory.

```bash
npm install
npm build -ws
```

--------------------------------

### Start Fiber Node with Password

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/notes/backup-guide.md

Start the Fiber node by providing the secret key password as an environment variable. Ensure the password is correct to avoid startup errors.

```bash
FIBER_SECRET_KEY_PASSWORD='YOUR_PASSWORD' ./fnn -c ./fiber-dir/config.yml -d ./fiber-dir
```

--------------------------------

### Start Nodes for Funding Tx Verification Test

Source: https://github.com/nervosnetwork/fiber/blob/develop/tests/bruno/e2e/funding-tx-verification/README.md

Use these commands to set up logging, select a test case, and start nodes with a clean environment for the funding transaction verification E2E test. The `FUNDING_TX_VERIFICATION_CASE` environment variable determines the specific test scenario.

```shell
# Set a logging file for the shell builder for debugging
export FUNDING_TX_SHELL_BUILDER_LOG_FILE=/tmp/funding.log
# Choose test case via the environment variable
export EXTRA_BRU_ARGS="--env-var FUNDING_TX_VERIFICATION_CASE=fund_from_peer"
# Start with a clean environment
export REMOVE_OLD_STATE=y

./tests/nodes/start.sh e2e/funding-tx-verification
```

--------------------------------

### Install Biscuit CLI

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/biscuit-auth.md

Installs the `biscuit-cli` tool, which is necessary for generating cryptographic key pairs for Biscuit authentication. Ensure you use version 0.6.0-beta.2.

```bash
# make sure you use 0.6.0 version
cargo install biscuit-cli --vers 0.6.0-beta.2
```

--------------------------------

### Start Development Nodes

Source: https://github.com/nervosnetwork/fiber/blob/develop/tests/bruno/e2e/external-funding-open/README.md

Starts the development nodes for the e2e external funding open test environment. Ensure this script is running before executing Bruno collections or restart regression tests.

```bash
REMOVE_OLD_STATE=y ./tests/nodes/start.sh e2e/external-funding-open
```

--------------------------------

### RPC Call After Migration (v0.8.0)

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/notes/v0.8.0-migration-guide.md

Example of an RPC call to open_channel using 'pubkey' in v0.8.0 and later.

```json
{"method": "open_channel", "params": [{"pubkey": "02abc..."}]}
```

--------------------------------

### Start Fiber Node after Migration

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/notes/v0.8.0-migration-guide.md

Launch the Fiber node using the updated binary after the migration process is complete. Specify configuration and data directories.

```bash
./fnn -c /path/to/fiber-dir/config.yml -d /path/to/fiber-dir
```

--------------------------------

### Start Nodes in a Clean State

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/dev/README.md

To start nodes with a completely clean state, including removing all old data, set the environment variable REMOVE_OLD_STATE to 'y' before running the start script. This is useful when database schemas have changed.

```bash
REMOVE_OLD_STATE=y ./tests/nodes/start.sh
```

--------------------------------

### Install fnn-cli

Source: https://github.com/nervosnetwork/fiber/blob/develop/crates/fiber-cli/README.md

Build the fnn-cli binary using Cargo. The executable will be located in the target/release directory.

```bash
cargo build -p fnn-cli --release
# binary is at target/release/fnn-cli
```

--------------------------------

### Start Local Fiber Nodes

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/public-nodes.md

Launch the Fiber nodes (nodeA and nodeB) by setting the FIBER_SECRET_KEY_PASSWORD environment variable and specifying configuration and data directories.

```bash
FIBER_SECRET_KEY_PASSWORD='your_password' RUST_LOG=info ./fnn -c $FNNDIR/nodeA/config.yml -d $FNNDIR/nodeA > $FNNDIR/nodeA/a.log 2>&1 &
FIBER_SECRET_KEY_PASSWORD='your_password' RUST_LOG=info ./fnn -c $FNNDIR/nodeB/config.yml -d $FNNDIR/nodeB > $FNNDIR/nodeB/b.log 2>&1 &
```

--------------------------------

### Build Project with Cargo

Source: https://github.com/nervosnetwork/fiber/blob/develop/AGENTS.md

Use these commands to build the project for debugging or release. Ensure you have the correct Rust toolchain installed.

```bash
cargo build                    # Debug build
```

```bash
cargo build --release          # Release build
```

```bash
cargo check --locked           # Quick check with Cargo.lock
```

```bash
make check                     # Full check (debug, release, no-default-features)
```

--------------------------------

### Start Interactive fnn-cli Session in Docker

Source: https://github.com/nervosnetwork/fiber/blob/develop/docker/README.md

Starts an interactive `fnn-cli` session within the running Fiber Docker container. This allows for real-time command execution.

```bash
docker exec -it fiber-node fnn-cli
```

--------------------------------

### RPC Call Before Migration (v0.7.x)

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/notes/v0.8.0-migration-guide.md

Example of an RPC call to open_channel using 'peer_id' in older versions.

```json
{"method": "open_channel", "params": [{"peer_id": "QmXxx..."}]}
```

--------------------------------

### Start fnn-cli in Interactive Mode

Source: https://github.com/nervosnetwork/fiber/blob/develop/crates/fiber-cli/README.md

Launch the fnn-cli in interactive mode to connect to a local node by default. Supports tab completion.

```bash
fnn-cli
```

--------------------------------

### Configure Public Key via Command-Line Argument

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/biscuit-auth.md

Passes the Biscuit public key as a command-line argument when starting the `fiber-bin` executable. This is useful for temporary or script-based configurations.

```bash
fiber-bin --rpc-biscuit-public-key "ed25519/17b172749be74276f0ed35a5d0685752684a3c5722114bba447a2f301136db79"
```

--------------------------------

### Example Signed Biscuit Token

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/biscuit-auth.md

An example of a Base64-encoded Biscuit bearer token generated after defining permissions and using a private key.

```text
ErsBClEKBXBlZXJzCghwYXltZW50cxgDIgkKBwgAEgMYgAgiCQoHCAESAxiBCDImCiQKAggbEgYIBRICCAUaFgoECgIIBQoICgYggIvSuwYKBBoCCAISJAgAEiDAjoKKNTZpA61ImgoD5Q2sSbBjA3ixK1R2M65a2TOxbRpA4SF04LS5zD6OempqQObA2TTlTCANI7bZkDpl7JIecjR59GFoNtyKYak-_jXq2gDUHadj2I8SbJ0N-vN1RPslDSIiCiBR7VZ7ZJaPE4nhxUUpgpd5MXr3hqi0RfNERy3NE4KjaQ==
```

--------------------------------

### Get Help with Fiber CLI Commands

Source: https://github.com/nervosnetwork/fiber/blob/develop/crates/fiber-cli/README.md

Use the --help flag with any command or subcommand to understand its usage and options. This applies to both direct commands and interactive mode.

```bash
fnn-cli --help
fnn-cli channel --help
fnn-cli channel open_channel --help
```

```bash
FNN> channel open_channel --help
```

--------------------------------

### Initialize or Re-initialize Dev Chain

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/dev/README.md

This script can be used to initialize or re-initialize the development chain, transferring balances and deploying contracts. The `-f` flag can be used to forcefully clean all old state and reinitialize. This is usually handled automatically by the start script.

```bash
./tests/deploy/init-dev-chain.sh [-f]
```

--------------------------------

### Configure Public Key via Environment Variable

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/biscuit-auth.md

Sets the Biscuit public key using an environment variable `RPC_BISCUIT_PUBLIC_KEY` before starting the `fiber-bin` executable. This is a common method for containerized or automated deployments.

```bash
export RPC_BISCUIT_PUBLIC_KEY="ed25519/17b172749be74276f0ed35a5d0685752684a3c5722114bba447a2f301136db79"
fiber-bin
```

--------------------------------

### Custom Records Example

Source: https://github.com/nervosnetwork/fiber/blob/develop/crates/fiber-lib/src/rpc/README.md

Illustrates how to specify custom records for a payment, which are key-value pairs where the key is a record type (hexadecimal) and the value is serialized data (hexadecimal).

```json
{
  "custom_records": {
    "0x1": "0x01020304",
    "0x2": "0x05060708",
    "0x3": "0x090a0b0c",
    "0x4": "0x0d0e0f10010d090a0b0c"
  }
}
```

--------------------------------

### Run Bruno Collection for External Funding

Source: https://github.com/nervosnetwork/fiber/blob/develop/tests/bruno/e2e/external-funding-open/README.md

Executes the Bruno collection for the e2e external funding open test. This command assumes the development nodes have already been started.

```bash
cd tests/bruno
npm exec -- @usebruno/cli@1.20.0 run e2e/external-funding-open -r --env test
```

--------------------------------

### Check for Running Node Processes

Source: https://github.com/nervosnetwork/fiber/wiki/Fiber-Breaking-Change-Migration-Guide

Use this command to identify any running Fiber node processes before stopping them. Replace the example process ID with your actual ID.

```bash
# Check for running node processes
ps aux | grep fnn
```

--------------------------------

### Define Biscuit Permissions

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/biscuit-auth.md

Define the permissions for a Biscuit token using Datalog facts and checks. This example grants read access to peers and write access to payments, with an expiration date.

```datalog
// Grant permissions for specific modules
read("peers");
write("payments");

// You can also add checks, like an expiration date.
// This check ensures the token is only valid before the specified UTC timestamp.
check if time($time), $time <= 2025-01-01T00:00:00Z;
```

--------------------------------

### Create Node Data Folder and Copy Files

Source: https://github.com/nervosnetwork/fiber/blob/develop/README.md

Set up the directory for the node's data and copy the compiled binary and configuration file.

```bash
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
```

--------------------------------

### Build the Project

Source: https://github.com/nervosnetwork/fiber/blob/develop/README.md

Compile the Fiber project using Cargo. Skip this if using a released binary.

```bash
cargo build --release
```

--------------------------------

### Download and Configure Nginx Source

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/fiber-node-wss.md

Downloads Nginx version 1.24.0 and configures it with essential modules including stream, SSL, and HTTP/2. This prepares Nginx for custom stream proxying.

```bash
cd /opt/
sudo wget https://nginx.org/download/nginx-1.24.0.tar.gz
sudo tar -zxvf nginx-1.24.0.tar.gz
cd nginx-1.24.0

sudo ./configure \
  --prefix=/usr/local/nginx \
  --with-stream \
  --with-stream_ssl_module \
  --with-stream_ssl_preread_module \
  --with-http_ssl_module \
  --with-http_v2_module \
  --with-http_gzip_static_module \
  --with-http_stub_status_module \
  --with-http_realip_module \
  --with-pcre
```

--------------------------------

### Build Fiber v0.8.0 from Source

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/notes/v0.8.0-migration-guide.md

Compile the Fiber node and migration tool from the v0.8.0 tag in the source repository.

```bash
git checkout v0.8.0
cargo build --release -p fnn
cargo build --release --manifest-path migrate/Cargo.toml
```

--------------------------------

### Connect nodeA to node1

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/public-nodes.md

Establishes a connection between nodeA and node1. This is the first step in setting up a UDT channel.

```bash
curl -s --location 'http://127.0.0.1:8227' --header 'Content-Type: application/json' --data '{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "connect_peer",
    "params": [
        {
            "pubkey": "02b6d4e3ab86a2ca2fad6fae0ecb2e1e559e0b911939872a90abdda6d20302be71"
        }
    ]
}'
```

--------------------------------

### Initialize Fiber Client with Testnet Configuration

Source: https://github.com/nervosnetwork/fiber/blob/develop/fiber-js/README.md

Instantiate the Fiber client using a detailed testnet configuration object. This configuration includes network settings, script definitions for funding and commitment locks, and CKB node connection details.

```javascript
import { Fiber, randomSecretKey } from "@nervosnetwork/fiber-js";

const fiber = new Fiber();

const testnetConfig = `
# This configuration file only contains the necessary configurations for the testnet deployment.
# All options' descriptions can be found via fnn --help and be overridden by command line arguments or environment variables.
fiber:
  # standalone_watchtower_rpc_url: http://127.0.0.1:23456
  # disable_built_in_watchtower: true
  listening_addr: "/ip4/127.0.0.1/tcp/8228"
  bootnode_addrs:
    - "/dns4/thrall.fiber.channel/tcp/443/wss/p2p/Qmes1EBD4yNo9Ywkfe6eRw9tG1nVNGLDmMud1xJMsoYFKy"
    - "/dns4/onyxia.fiber.channel/tcp/443/wss/p2p/QmdyQWjPtbK4NWWsvy8s69NGJaQULwgeQDT5ZpNDrTNaeV"
  announce_listening_addr: false
  announced_addrs:
    # If you want to announce your fiber node public address to the network, you need to add the address here, please change the ip to your public ip accordingly.
    # - "/ip4/YOUR-FIBER-NODE-PUBLIC-IP/tcp/8228"
  chain: testnet
  # lock script configurations related to fiber network
  # https://github.com/nervosnetwork/fiber-scripts/blob/main/deployment/testnet/migrations/2025-02-28-111246.json
  scripts:
    - name: FundingLock
      script:
        code_hash: 0x6c67887fe201ee0c7853f1682c0b77c0e6214044c156c7558269390a8afa6d7c
        hash_type: type
        args: 0x
      cell_deps:
        - type_id:
            code_hash: 0x00000000000000000000000000000000000000000000000000545950455f4944
            hash_type: type
            args: 0x3cb7c0304fe53f75bb5727e2484d0beae4bd99d979813c6fc97c3cca569f10f6
        - cell_dep:
            out_point:
              tx_hash: 0x12c569a258dd9c5bd99f632bb8314b1263b90921ba31496467580d6b79dd14a7 # ckb_auth
              index: 0x0
            dep_type: code
    - name: CommitmentLock
      script:
        code_hash: 0x740dee83f87c6f309824d8fd3fbdd3c8380ee6fc9acc90b1a748438afcdf81d8
        hash_type: type
        args: 0x
      cell_deps:
        - type_id:
            code_hash: 0x00000000000000000000000000000000000000000000000000545950455f4944
            hash_type: type
            args: 0xf7e458887495cf70dd30d1543cad47dc1dfe9d874177bf19291e4db478d5751b
        - cell_dep:
            out_point:
              tx_hash: 0x12c569a258dd9c5bd99f632bb8314b1263b90921ba31496467580d6b79dd14a7 #ckb_auth
              index: 0x0
            dep_type: code

rpc:
  # By default RPC only binds to localhost, thus it only allows accessing from the same machine.
  # Allowing arbitrary machines to access the JSON-RPC port is dangerous and strongly discouraged.
  # Please strictly limit the access to only trusted machines.
  listening_addr: "127.0.0.1:8227"

ckb:
  rpc_url: "https://testnet.ckbapp.dev/"
  udt_whitelist:
    - name: RUSD
      script:
        code_hash: 0x1142755a044bf2ee358cba9f2da187ce928c91cd4dc8692ded0337efa677d21a
        hash_type: type
        args: 0x878fcc6f1f08d48e87bb1c3b3d5083f23f8a39c5d5c764f253b55b998526439b
      cell_deps:
        - type_id:
            code_hash: 0x00000000000000000000000000000000000000000000000000545950455f4944
            hash_type: type
            args: 0x97d30b723c0b2c66e9cb8d4d0df4ab5d7222cbb00d4a9a2055ce2e5d7f0d8b0f
      auto_accept_amount: 1000000000

`;

// The Fiber client is initialized with the provided configuration.
// Further operations would use this 'fiber' instance.

```

--------------------------------

### Run Fiber Migration Tool

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/notes/v0.8.0-migration-guide.md

Execute the fnn-migrate tool to update the existing Fiber database. Use the -d flag to specify the data directory.

```bash
./fnn-migrate -d /path/to/fiber-dir
```

--------------------------------

### Create Local Node Directories

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/public-nodes.md

Create the necessary directory structure for two local nodes (nodeA and nodeB) to store their CKB data.

```bash
# Create local node directories
mkdir -p $FNNDIR/nodeA/ckb $FNNDIR/nodeB/ckb
```

--------------------------------

### Connect Node to Peer

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/public-nodes.md

Establishes a connection to a specified peer using their public key. This is the first step in setting up a CKB channel.

```bash
curl -s --location 'http://127.0.0.1:8227' --header 'Content-Type: application/json' --data '{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "connect_peer",
    "params": [
        {
            "pubkey": "'$NODE1_PUBKEY'"
        }
    ]
}'
```

```json
{"jsonrpc":"2.0","result":null,"id":1}
```

--------------------------------

### Query Channels and Wait for ChannelReady

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/public-nodes.md

Lists existing channels with a specific peer and monitors their state. Wait until the state changes to 'ChannelReady' before attempting to send payments.

```bash
curl -s --location 'http://127.0.0.1:8227' --header 'Content-Type: application/json' --data '{
    "id": 3,
    "jsonrpc": "2.0",
    "method": "list_channels",
    "params": [
        {
            "pubkey": "'$NODE1_PUBKEY'"
        }
    ]
}'
```

```json
{"jsonrpc":"2.0","id":3,"result":{"channels":[{"channel_id":"0x8cfd1718dace307c1c7eee756773fee9ded3bae8a3808fc207e078ac5f190413","is_public":true,"is_acceptor":false,"is_one_way":false,"channel_outpoint":"0x31b242023b98f2b460fc83cd0b9c3165c446bc129571dbc269d6e3f22d67b38600000000","pubkey":"02b6d4e3ab86a2ca2fad6fae0ecb2e1e559e0b911939872a90abdda6d20302be71","funding_udt_type_script":null,"state":{"state_name":"ChannelReady"},"local_balance":"0x9502f9000","offered_tlc_balance":"0x0","remote_balance":"0x38407b700","received_tlc_balance":"0x0","pending_tlcs":[],"latest_commitment_transaction_hash":"0x586a486509015da605d403f184885c69c0a16e5e651e93d7e03a7f1a5378710a","created_at":"0x19d72fe29f6","enabled":true,"tlc_expiry_delta":"0xdbba00","tlc_fee_proportional_millionths":"0x3e8","shutdown_transaction_hash":null,"failure_detail":null}]}}
```

--------------------------------

### Terminate Fiber Node Process

Source: https://github.com/nervosnetwork/fiber/wiki/Fiber-Breaking-Change-Migration-Guide

Stop the Fiber node by terminating its process. Ensure you replace the example process ID (3585187) with the correct ID found in the previous step.

```bash
# Terminate it (replace 3585187 with your process ID)
kill 3585187
```

--------------------------------

### Connect to a Peer

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/public-nodes.md

Establishes a connection with another node using its public key. Ensure the target node is running and accessible.

```bash
curl -s --location 'http://127.0.0.1:8237' --header 'Content-Type: application/json' --data '{ 
    "id": 1, 
    "jsonrpc": "2.0", 
    "method": "connect_peer", 
    "params": [ 
        { 
            "pubkey": "'$NODE2_PUBKEY'" 
        } 
    ] 
}'
```

--------------------------------

### TxUpdate Message Structure

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/specs/p2p-message.md

The TxUpdate message is used by the channel initiator to start the transaction construction protocol. Both parties must save and compare the funding tx field of the previous message.

```protobuf
table TxUpdate {
    channel_id: Byte32,
    tx:         Transaction,
}
```

--------------------------------

### Create Fiber Database Backup

Source: https://github.com/nervosnetwork/fiber/wiki/Fiber-Breaking-Change-Migration-Guide

Create a compressed tar archive of the Fiber directory to back up your database. This is a crucial step before proceeding with the migration.

```bash
tar -zcvf backup-fiber-dir.tar.gz fiber-dir
```

--------------------------------

### Get Fiber Node Public Key

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/fiber-node-wss.md

Retrieve your Fiber node's public key by sending a JSON-RPC request to the node's API. This is required for connecting to peers by pubkey.

```sh
curl -s -X POST http://127.0.0.1:8227 \
  -H "Content-Type: application/json" \
  -d '{"id": 42, "jsonrpc": "2.0", "method": "node_info", "params": []}' \
  | jq -r '.result.pubkey'
```

--------------------------------

### Run Published Fiber Docker Image

Source: https://github.com/nervosnetwork/fiber/blob/develop/docker/README.md

Runs a published Fiber Docker image. Ensure you create the necessary directory and place your CKB private key before execution. Replace `<release-tag>` with the desired version.

```bash
mkdir -p ./fiber-node/ckb
# Put your CKB private key in ./fiber-node/ckb/key before starting the node.

docker run --rm -it \
  --name fiber-node \
  -e FIBER_SECRET_KEY_PASSWORD='YOUR_PASSWORD' \
  -e RUST_LOG='info' \
  -v "$(pwd)/fiber-node:/fiber" \
  -p 8228:8228 \
  nervos/fiber:<release-tag>
```

--------------------------------

### Copy Mainnet Configuration

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/public-nodes.md

Copy the mainnet configuration file to the respective directories for nodeA and nodeB.

```bash
cp config/mainnet/config.yml $FNNDIR/nodeA
cp config/mainnet/config.yml $FNNDIR/nodeB
```

--------------------------------

### Reset Fiber Node Password

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/notes/backup-guide.md

If the password is forgotten, you can reset it by removing the encrypted key, adding a plaintext key, and starting the node with a new password. This process re-encrypts the key with the new password.

```bash
rm -rf fiber-dir/ckb
mkdir fiber-dir/ckb
echo "YOUR_PLAINTEXT_KEY" > fiber-dir/ckb/key
FIBER_SECRET_KEY_PASSWORD='NEW_PASSWORD' ./fnn -c ./fiber-dir/config.yml -d ./fiber-dir
```

--------------------------------

### Open a CKB Channel

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/public-nodes.md

Opens a new channel with a specified public key and funding amount. The `funding_amount` must be sufficient, especially if `open_channel_auto_accept_min_ckb_funding_amount` is set on the peer.

```bash
curl -s --location 'http://127.0.0.1:8237' --header 'Content-Type: application/json' --data '{ 
    "id": 2, 
    "jsonrpc": "2.0", 
    "method": "open_channel", 
    "params": [ 
        { 
            "pubkey": "'$NODE2_PUBKEY'", 
            "funding_amount": "0xb9e459300", 
            "public": true 
        } 
    ] 
}'
```

--------------------------------

### Other Project Checks and Generation

Source: https://github.com/nervosnetwork/fiber/blob/develop/AGENTS.md

Perform various checks like unused dependencies, generate RPC documentation, and verify or update migration schemas.

```bash
# Check for unused dependencies
cargo shear
```

```bash
# Generate RPC documentation
make gen-rpc-doc
```

```bash
# Verify data migration schemas
make check-migrate
```

```bash
# Update migration schemas
make update-migrate-check
```

--------------------------------

### Collect CPU Profile

Source: https://github.com/nervosnetwork/fiber/blob/develop/crates/fiber-cli/README.md

Use the `pprof` command to collect a CPU profile and generate a flamegraph SVG for performance analysis.

```bash
fnn-cli prof pprof --duration-secs 30
```

--------------------------------

### Create and Export Node Accounts

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/public-nodes.md

Generate new accounts for nodeA and nodeB using ckb-cli, export their private keys, and store them securely in the node's ckb directory.

```bash
# Create accounts for nodeA and nodeB (replace <lock_arg_a/b> with the lock_arg from each output)
./ckb-cli account new  # -> nodeA account
./ckb-cli account export --lock-arg <lock_arg_a> --extended-privkey-path exported-key-a
head -n 1 ./exported-key-a > $FNNDIR/nodeA/ckb/key && chmod 600 $FNNDIR/nodeA/ckb/key

./ckb-cli account new  # -> nodeB account
./ckb-cli account export --lock-arg <lock_arg_b> --extended-privkey-path exported-key-b
head -n 1 ./exported-key-b > $FNNDIR/nodeB/ckb/key && chmod 600 $FNNDIR/nodeB/ckb/key
```

--------------------------------

### Channel Establishment Sequence Diagram

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/specs/p2p-message.md

Illustrates the message flow for establishing a payment channel between two nodes, A and B. Node A is the initiator, and Node B is the accepter.

```text
    +-------+                              +-------+ 
    |       |--(1)--- OpenChannel     ---->|       | 
    |       |<-(2)--- AcceptChannel   -----|       | 
    |       |                              |       | 
--->|       |      <tx collaboration>      |       | 
|   |       |                              |       | 
|   |       |--(3)--  commitment_signed -->|       | 
|   |       |<-(4)--  commitment_signed ---|       | 
|   |   A   |                              |   B   | 
|   |       |<-(5)--  tx_signatures -------|       | 
|   |       |--(6)--  tx_signatures ------>|       | 
|   |       |                              |       | 
|   |       |--(a)--- tx_init_rbf -------->|       | 
----|       |<-(b)--- tx_ack_rbf ----------|       | 
    |       |                              |       | 
    |       |    <tx rbf collaboration>    |       | 
    |       |                              |       | 
    |       |--(c)--  commitment_signed -->|       | 
    |       |<-(d)--  commitment_signed ---|       | 
    |       |                              |       | 
    |       |<-(e)--  tx_signatures -------|       | 
    |       |--(f)--  tx_signatures ------>|       | 
    |       |                              |       | 
    |       |--(7)--- channel_ready  ----->|       | 
    |       |<-(8)--- channel_ready  ------|       | 
    +-------+                              +-------+
```

--------------------------------

### Run End-to-End Tests with Bruno CLI

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/dev/README.md

Navigate to the 'tests/bruno' directory and use the Bruno CLI to run end-to-end tests. This command executes the 'open-use-close-a-channel' test suite in the 'test' environment.

```bash
cd tests/bruno
npm exec -- @usebruno/cli run e2e/open-use-close-a-channel -r --env test
```

--------------------------------

### Copy Testnet Configuration

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/public-nodes.md

Copy the testnet configuration file to the respective directories for nodeA and nodeB.

```bash
cp config/testnet/config.yml $FNNDIR/nodeA
cp config/testnet/config.yml $FNNDIR/nodeB
```

--------------------------------

### Turmoil for Network Simulation

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/notes/fuzz-testing.md

Demonstrates setting up a deterministic simulation of networked actors using Turmoil. This requires replacing real TCP with Turmoil's simulated TCP and may involve significant integration work with Ractor.

```rust
use turmoil::Builder;

#[test]
fn test_channel_open_under_partition() {
    let mut sim = Builder::new()
        .simulation_duration(Duration::from_secs(60))
        .build();

    sim.host("alice", || async {
        let node = start_fiber_node(config_alice()).await;
        node.open_channel("bob", 1000).await?;
        Ok(())
    });

    sim.host("bob", || async {
        let node = start_fiber_node(config_bob()).await;
        // Accept channel
        Ok(())
    });

    // Partition network after channel open
    sim.partition("alice", "bob");
    sim.run().unwrap();
}
```

--------------------------------

### Create Fiber Node Backup Archive

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/notes/backup-guide.md

Create a compressed tar archive of the entire Fiber node directory to back up all essential data, including keys, database, and configuration.

```bash
tar -zcvf fiber-dir.tar.gz fiber-dir
```

--------------------------------

### Send Payment from NodeA

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/public-nodes.md

Initiate a payment from NodeA using the invoice address obtained in the previous step. This command sends the payment through the established channel.

```bash
curl -s --location 'http://127.0.0.1:8227' --header 'Content-Type: application/json' --data '{
    "id": 3,
    "jsonrpc": "2.0",
    "method": "send_payment",
    "params": [
        {
            "invoice": "<invoice_address from step 2>"
        }
    ]
}'
```

--------------------------------

### Manage Payment Channels

Source: https://github.com/nervosnetwork/fiber/blob/develop/crates/fiber-cli/README.md

Commands for managing payment channels, including opening, accepting, listing, updating, shutting down, and abandoning channels.

```bash
fnn-cli channel open_channel --pubkey 02abc... --funding-amount 1000000
```

```bash
fnn-cli channel list_channels
```

```bash
fnn-cli channel shutdown_channel --channel-id 0xabc...
```

--------------------------------

### Run E2E Channel Test with Bruno CLI

Source: https://github.com/nervosnetwork/fiber/blob/develop/tests/bruno/e2e/open-use-close-a-channel/README.md

Use the Bruno CLI to run the end-to-end test suite for opening, using, and closing a fiber channel. This command specifies the test collection and environment.

```bash
cd tests/bruno
npm exec -- @usebruno/cli run e2e/open-use-close-a-channel -r --env test

```

--------------------------------

### Module Watchtower RPC Methods

Source: https://github.com/nervosnetwork/fiber/blob/develop/crates/fiber-lib/src/rpc/README.md

Methods for interacting with the watchtower service.

```APIDOC
## Watchtower RPC Methods

### `create_watch_channel`

Creates a watchtower entry for a channel.

### `remove_watch_channel`

Removes a watchtower entry for a channel.

### `update_revocation`

Updates revocation information for a watched channel.

### `update_pending_remote_settlement`

Updates pending remote settlement information.

### `update_local_settlement`

Updates local settlement information.

### `create_preimage`

Creates a preimage for watchtower.

### `remove_preimage`

Removes a preimage from watchtower.
```

--------------------------------

### Manage Private Key for Wallet

Source: https://github.com/nervosnetwork/fiber/blob/develop/README.md

Create or import a private key for the node's wallet functionality. The key is stored in `ckb/key`.

```bash
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
```

--------------------------------

### Payment Session and Attempt State Machine

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/payment-lifecycle.md

Visualizes the state transitions for Payment Sessions (Created, Inflight, Success, Failed) and Payment Attempts (Created, Inflight, Settled, Retrying, Failed), including aggregation and MPP logic.

```mermaid
flowchart TB
    subgraph PaymentSession [Payment Session]
        direction TB
        PS_Created[Created] --> PS_Inflight[Inflight]
        PS_Inflight -- "Σ(Settled Amount) == Total" --> PS_Success[Success / Finished]
        PS_Inflight -- "Exhausted / Terminal Error" --> PS_Failed[Failed]
        
        style PS_Success fill:#e1f5fe,stroke:#01579b
        style PS_Failed fill:#ffebee,stroke:#b71c1c
    end

    subgraph Attempts [Payment Attempts]
        direction TB
        A_Created[Attempt 1..N] --> A_Inflight[Inflight]
        A_Inflight --> A_Result{Result?}
        A_Result -- "Fulfill" --> A_Settled[Settled]
        A_Result -- "Fail (Retryable)" --> A_Retrying[Retrying]
        A_Result -- "Fail (Final)" --> A_Failed[Failed]
        
        A_Retrying --> A_Inflight
    end

    %% Aggregation & MPP Logic
    PS_Created -- "Splits Amount" --> A_Created
    A_Settled -- "Partial Amount Collected" --> PS_Inflight
    A_Settled -- "Full Amount Reached" --> PS_Success
    A_Failed -- "Cannot fulfill Total Amount" --> PS_Failed
```

--------------------------------

### Build Fiber Docker Image Locally

Source: https://github.com/nervosnetwork/fiber/blob/develop/docker/README.md

Builds the Docker image for Fiber using the provided Dockerfile. Use this command to create a local image for development or testing.

```bash
docker build -f docker/Dockerfile -t fiber:local .
```

--------------------------------

### Download and Extract fnn Binary

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/public-nodes.md

Download the latest fnn binary from the releases page and extract it to a temporary directory.

```bash
mkdir tmp && cd tmp
tar xzvf fnn-latest.tar.gz
```

--------------------------------

### Manage Peer Connections

Source: https://github.com/nervosnetwork/fiber/blob/develop/crates/fiber-cli/README.md

Commands for managing peer connections, including connecting, disconnecting, and listing peers.

```bash
fnn-cli peer connect_peer --address /ip4/1.2.3.4/tcp/8119/p2p/QmNode...
```

```bash
fnn-cli peer disconnect_peer --pubkey 02abc...
```

```bash
fnn-cli peer list_peers
```

--------------------------------

### build_router

Source: https://github.com/nervosnetwork/fiber/blob/develop/crates/fiber-lib/src/rpc/README.md

Constructs a payment route based on specified hops and channel requirements.

```APIDOC
## Method build_router

### Description
Builds a router with a list of pubkeys and required channels.

### Params
#### Path Parameters
* `amount` (Option<u128>) - the amount of the payment, the unit is Shannons for non UDT payment. If not set, the minimum routable amount `1` is used
* `udt_type_script` (Option<Script>) - udt type script for the payment router
* `hops_info` (Vec<HopRequire>) - A list of hops that defines the route. This does not include the source hop pubkey. A hop info is a tuple of pubkey and the channel (specified by channel funding tx) will be used. This is a strong restriction given on payment router, which means these specified hops and channels must be adapted in the router. This is different from hop hints, which maybe ignored by find path. If channel is not specified, find path algorithm will pick a channel within these two peers.
 An error will be returned if there is no router could be build from given hops and channels
* `final_tlc_expiry_delta` (Option<u64>) - the TLC expiry delta should be used to set the timelock for the final hop, in milliseconds

### Returns
* `router_hops` (Vec<RouterHop>) - The hops information for router
```

--------------------------------

### Verify Node Private Keys

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/public-nodes.md

Use ckb-cli to confirm that the private keys for nodeA and nodeB have been correctly exported and stored.

```bash
# Verify keys
./ckb-cli util key-info --privkey-path $FNNDIR/nodeA/ckb/key
./ckb-cli util key-info --privkey-path $FNNDIR/nodeB/ckb/key
```

--------------------------------

### Run Tests with Nextest

Source: https://github.com/nervosnetwork/fiber/blob/develop/AGENTS.md

Execute all tests using nextest for faster feedback. Configure `RUST_TEST_THREADS: 2` in CI for heavy tests. Specific packages or tests can be targeted.

```bash
# Run all tests with nextest (PREFERRED)
cargo nextest run --no-fail-fast
```

```bash
# Run specific package tests
cargo nextest run -p fnn -p fiber-bin
```

```bash
# Run single test by name
cargo nextest run test_name
```

```bash
# Run tests matching pattern
cargo nextest run 'test_pattern'
```

```bash
# Standard cargo test (if nextest unavailable)
RUST_LOG=off cargo test -p fnn -p fiber-bin
```

```bash
# Run benchmarks
cargo criterion --features bench
make benchmark-test
```

--------------------------------

### Enter Interactive REPL Mode

Source: https://github.com/nervosnetwork/fiber/blob/develop/crates/fiber-cli/README.md

Run `fnn-cli` without a subcommand to enter the interactive REPL. This mode offers tab completion, command history, and colored output.

```bash
$ fnn-cli -u http://54.178.252.1:8227

  ______ ___ ___  ______ _____
 |  ____|_ _| _ \|  ____|  __ \
 | |__   | ||___/| |__  | |__) |
 |  __|  | || _ \|  __| |  _  /
 | |    _| || |_\| |____| | \ \
 |_|   |___|____/|______|_|  \_\

[  fnn-cli version ]: 0.9.0-rc4
[              url ]: http://54.178.252.1:8227
[    output format ]: yaml
[           status ]: Connected

FNN> info
FNN> channel list_channels
FNN> exit
```

--------------------------------

### Module Info RPC Methods

Source: https://github.com/nervosnetwork/fiber/blob/develop/crates/fiber-lib/src/rpc/README.md

Methods for retrieving node information.

```APIDOC
## Info RPC Methods

### `node_info`

Retrieves information about the current node.
```

--------------------------------

### Configure NodeB Testnet Ports

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/public-nodes.md

Adjust the listening ports for nodeB in the testnet configuration to avoid conflicts with nodeA.

```bash
sed -i.bak 's|/ip4/0.0.0.0/tcp/8228|/ip4/0.0.0.0/tcp/8238|' $FNNDIR/nodeB/config.yml
sed -i.bak 's|127.0.0.1:8227|127.0.0.1:8237|' $FNNDIR/nodeB/config.yml
grep -wE 'rpc_url|listening_addr' $FNNDIR/nodeB/config.yml
```

--------------------------------

### Configure Mainnet RPC URL

Source: https://github.com/nervosnetwork/fiber/blob/develop/docs/public-nodes.md

Update the 'rpc_url' in the configuration file for nodeA to point to a trusted CKB RPC endpoint.

```bash
sed -i.bak 's|rpc_url:.*|rpc_url: "https://mainnet.ckbapp.dev/"|
' $FNNDIR/nodeA/config.yml
grep rpc_url $FNNDIR/nodeA/config.yml
```

--------------------------------

### Authenticate fnn-cli with Token File

Source: https://github.com/nervosnetwork/fiber/blob/develop/crates/fiber-cli/README.md

Read the authentication token from a file. This is recommended for long tokens to avoid shell quoting issues.

```bash
echo -n 'EsQCCtkBCghjaGFu...' > ~/.fnn-token
fnn-cli --auth-token-file ~/.fnn-token info
```

--------------------------------

### Watchtower Module RPC Methods

Source: https://github.com/nervosnetwork/fiber/blob/develop/crates/fiber-lib/src/rpc/README.md

Methods for managing watched channels and related data.

```APIDOC
## Method `create_watch_channel`

### Description
Create a new watched channel.

### Method
create_watch_channel

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* `channel_id` ([Hash256](#type-hash256)) - Channel ID
* `funding_udt_type_script` (Option<Script>) - Funding UDT type script
* `local_settlement_key` ([Privkey](#type-privkey)) - The local party's private key used to settle the commitment transaction (hex without 0x prefix)
* `remote_settlement_key` ([Pubkey](#type-pubkey)) - The remote party's public key used to settle the commitment transaction (hex without 0x prefix)
* `local_funding_pubkey` ([Pubkey](#type-pubkey)) - The local party's funding public key (hex without 0x prefix)
* `remote_funding_pubkey` ([Pubkey](#type-pubkey)) - The remote party's funding public key (hex without 0x prefix)
* `settlement_data` ([SettlementData](#type-settlementdata)) - Settlement data

### Request Example
```json
{
  "channel_id": "0x...",
  "local_settlement_key": "0x...",
  "remote_settlement_key": "0x...",
  "local_funding_pubkey": "0x...",
  "remote_funding_pubkey": "0x...",
  "settlement_data": {}
}
```

### Response
#### Success Response (None)
None
```

```APIDOC
## Method `remove_watch_channel`

### Description
Remove a watched channel.

### Method
remove_watch_channel

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* `channel_id` ([Hash256](#type-hash256)) - Channel ID

### Request Example
```json
{
  "channel_id": "0x..."
}
```

### Response
#### Success Response (None)
None
```

```APIDOC
## Method `update_revocation`

### Description
Update revocation.

### Method
update_revocation

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* `channel_id` ([Hash256](#type-hash256)) - Channel ID
* `revocation_data` ([RevocationData](#type-revocationdata)) - Revocation data
* `settlement_data` ([SettlementData](#type-settlementdata)) - Settlement data

### Request Example
```json
{
  "channel_id": "0x...",
  "revocation_data": {},
  "settlement_data": {}
}
```

### Response
#### Success Response (None)
None
```

```APIDOC
## Method `update_pending_remote_settlement`

### Description
Update pending remote settlement.

### Method
update_pending_remote_settlement

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* `channel_id` ([Hash256](#type-hash256)) - Channel ID
* `settlement_data` ([SettlementData](#type-settlementdata)) - Settlement data

### Request Example
```json
{
  "channel_id": "0x...",
  "settlement_data": {}
}
```

### Response
#### Success Response (None)
None
```

```APIDOC
## Method `update_local_settlement`

### Description
Update settlement.

### Method
update_local_settlement

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* `channel_id` ([Hash256](#type-hash256)) - Channel ID
* `settlement_data` ([SettlementData](#type-settlementdata)) - Settlement data

### Request Example
```json
{
  "channel_id": "0x...",
  "settlement_data": {}
}
```

### Response
#### Success Response (None)
None
```

```APIDOC
## Method `create_preimage`

### Description
Create preimage.

### Method
create_preimage

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* `payment_hash` ([Hash256](#type-hash256)) - Payment hash
* `preimage` ([Hash256](#type-hash256)) - Preimage

### Request Example
```json
{
  "payment_hash": "0x...",
  "preimage": "0x..."
}
```

### Response
#### Success Response (None)
None
```

```APIDOC
## Method `remove_preimage`

### Description
Remove preimage.

### Method
remove_preimage

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* `payment_hash` ([Hash256](#type-hash256)) - Payment hash

### Request Example
```json
{
  "payment_hash": "0x..."
}
```

### Response
#### Success Response (None)
None
```

--------------------------------

### Execute fnn-cli Command

Source: https://github.com/nervosnetwork/fiber/blob/develop/crates/fiber-cli/README.md

Run a one-shot command with fnn-cli, such as 'info'.

```bash
fnn-cli info
```
Tokens:
Raw