Configuration Reference

Fiber Node is mainly configured by config.yml. Many fields in this file can also be set from command-line flags or environment variables when starting fnn.

Configuration Loading

Native fnn loads configuration file in this order:

1. -c, --config <path> if provided.
2. $BASE_DIR/config.yml when -d, --dir <BASE_DIR> is provided.
3. $HOME/.fiber-node/config.yml.

Values from command-line flags and supported environment variables override config.yml; values not provided by either source fall back to built-in defaults. If both a command-line flag and its environment variable are provided, use the command-line value as the effective override.

services decides which services start. Set it in config.yml, or pass one or more service names with -s, --services when starting fnn, for example --services fiber,rpc,ckb. When the command line includes at least one service name, that list replaces the services list in config.yml; when no service name is provided, fnn uses the list from config.yml. Valid service names are fiber, rpc, ckb, and cch.

Data directories are derived from BASE_DIR, which defaults to $HOME/.fiber-node and can be changed with global -d, --dir. Native startup sets service directories to $BASE_DIR/fiber, $BASE_DIR/ckb, and $BASE_DIR/cch; do not rely on per-service base_dir entries in config.yml. The generated help may list per-service base directory flags and environment variables, but native startup rewrites those service directories from BASE_DIR.

Tip: Run fnn --help to list the available configuration flags and environment variables. Most service-scoped options are generated from the same config structs that parse config.yml, so the corresponding YAML fields work too. For example, --fiber-listening-addr maps to fiber.listening_addr, and --rpc-listening-addr maps to rpc.listening_addr.

Global Startup Options

These options affect native fnn startup. They are not config.yml fields.

Top-Level Fields

fiber:
  # P2P network and channel configuration
rpc:
  # JSON-RPC server configuration
ckb:
  # CKB blockchain integration
cch:
  # Cross-Chain Hub configuration (optional)
services:
  - fiber
  - rpc
  - ckb

Service dependencies:

• fiber requires ckb.
• cch requires either the in-process fiber service or cch.fiber_rpc_url.
• Standalone cch mode, where fiber is not running in the same process, also requires cch.wrapped_btc_type_script.

Fiber Section (fiber)

Network

Contract Scripts

fiber:
  scripts:
    - name: FundingLock
      script:
        code_hash: 0x...
        hash_type: type
        args: 0x
      cell_deps:
        - type_id:
            code_hash: 0x...
            hash_type: type
            args: 0x...
        - cell_dep:
            out_point:
              tx_hash: 0x...
              index: 0x0
            dep_type: code

name must be one of the contract names used by Fiber, such as FundingLock or CommitmentLock. Each cell_deps entry must contain exactly one of type_id or cell_dep.

Channel

TLC

final_tlc_expiry_delta is not a node-level config field. It is a payment/invoice-level value with separate defaults in the payment code.

Node Announcements, Peers, and Gossip

Watchtower

If disable_built_in_watchtower is true, standalone_watchtower_rpc_url must be set.

Proxy & Tor

proxy and onion are config-file-only fields. They are not exposed as direct CLI flags or environment variables.

Feature-Gated Fields

RPC Section (rpc)

Default modules are cch, channel, graph, payment, info, invoice, and peer. Builds with the watchtower feature also enable watchtower by default.

Available module names include cch, channel, graph, payment, info, invoice, peer, pubsub, watchtower, dev in debug builds, and prof when built with the pprof feature.

If listening_addr is public, biscuit_public_key is required. Without auth, the RPC server refuses to bind public addresses such as 0.0.0.0:8227.

CKB Section (ckb)

UDT Configuration

ckb:
  udt_whitelist:
    - name: "USDI"
      script:
        code_hash: "0x..."
        hash_type: type
        args: "0x..."
      auto_accept_amount: 10000000  # Optional: auto-accept amount
      cell_deps:
        - type_id:
            code_hash: "0x..."
            hash_type: type
            args: "0x..."

script.args is compiled as a regular expression and matched against the UDT type script args rendered as a 0x-prefixed hex string. Use an exact regex if you only want to match one token.

Each UDT cell_deps entry must contain exactly one of:

• type_id, a script used to resolve the current cell dep through the CKB indexer.
• cell_dep, a direct out_point plus dep_type.

funding_tx_shell_builder is configured under ckb, but its environment variable is FIBER_FUNDING_TX_SHELL_BUILDER. The command receives a funding request JSON object on stdin and must print a CKB transaction JSON object to stdout on success.

CCH Section (cch) — Cross-Chain Hub

Relative lnd_cert_path and lnd_macaroon_path values are resolved under the effective CCH data directory, normally $BASE_DIR/cch.

Environment Variables

Only fields wired to clap can be overridden by environment variables. List values use comma-separated strings. Complex values such as FIBER_SCRIPTS and CKB_UDT_WHITELIST are easier and less error-prone in YAML.

Fiber

FIBER_TO_BE_ACCEPTED_CHANNELS_BYTESS_LIMIT keeps the current source spelling of the environment variable. The YAML field and CLI flag use bytes.

RPC

CKB

CCH

Special variable: FIBER_SECRET_KEY_PASSWORD — Required to decrypt the CKB private key at startup.

No supported direct environment variable exists for native service directories, fiber.proxy, fiber.onion, fiber.gossip_policy, or cch.ignore_startup_failure.

Example: Minimal Testnet Config

fiber:
  listening_addr: "/ip4/0.0.0.0/tcp/8228"
  bootnode_addrs:
    - "/ip4/54.179.226.154/tcp/8228/p2p/Qmes1EBD4yNo9Ywkfe6eRw9tG1nVNGLDmMud1xJMsoYFKy"
    - "/ip4/16.163.7.105/tcp/8228/p2p/QmdyQWjPtbK4NWWsvy8s69NGJaQULwgeQDT5ZpNDrTNaeV"
  announce_listening_addr: true
  chain: testnet
  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
              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
              index: 0x0
            dep_type: code

rpc:
  listening_addr: "127.0.0.1:8227"

ckb:
  rpc_url: "https://testnet.ckbapp.dev/"

services:
  - fiber
  - rpc
  - ckb

Tip: Use the config files from the Fiber repository as starting points. They include current script hashes, cell deps, UDT whitelist entries, and bootnode addresses for each network.