Join Our Community
Tech Explanation
A source code-level exploration of Fiber's architecture and key modules.
Fiber is a Lightning-compatible peer-to-peer payment and swap network built on CKB, the base layer of Nervos Network. Fiber is designed to enable fast, secure, and efficient off-chain payment solutions, particularly for micropayments and high-frequency transactions.
Inspired by Bitcoin’s Lightning Network, Fiber leverages CKB’s unique architecture and offers the following key features:
This article presents a source code-level exploration of Fiber’s architecture, key modules, as well as an overview of its future development plans.
At a high level, a Fiber node consists of several key modules:
Key Modules Overview
ckb-auth library to implement a 2-of-2 multi-signature scheme for channel funding.The Lightning Network is essentially a peer-to-peer (P2P) system, where nodes communicate via network messages, updating internal states accordingly. The Actor Model aligns well with this setup:
obsolete image
One potential concern with the Actor Model is its memory footprint and runtime efficiency. We conducted a performance test, showing that 0.9 GB of memory can support 100,000 actors (each with a 1 KB state), processing 100 messages per actor within 10 seconds—demonstrating acceptable performance.
Unlike rust-lightning, which relies on complex locking mechanisms to maintain data consistency, Fiber’s Actor Model simplifies implementation by eliminating the need for locks to protect data updates. Messages are processed sequentially in an actor’s message queue. When a message handler completes its tasks, the updated channel state is written to the database, streamlining the persistence process.
Almost all modules in Fiber use the Actor Model. The Network Actor handles communication both within and across nodes. For example, if Node A wants to send an “Open Channel” message to Node B, the process follows these steps:
The Channel Actor in Node A (Actor 0 in this case) sends the message to the Network Actor in Node B.
The Network Actor transmits the message using Tentacle, a lower-level networking layer.
The Network Actor in Node B receives the message and forwards it to the corresponding Channel Actor(Actor 0/1/…/n).
obsolete image
For each new channel, Fiber creates a corresponding ChannelActor, where the ChannelActorState maintains all the necessary data for the channel.
Another major advantage of the Actor Model is its ability to map HTLC (Hash Time-Locked Contracts)-related operations directly to specific functions. For example, in the process of forwarding an HTLC across multiple nodes:
Actor 0 handles the AddTlc operation via handle_add_tlc_command.Actor 1 handles the corresponding peer message via handle_add_tlc_peer_message.
obsolete image
The HTLC management within channels is one of the most complex aspects of the Lightning Network, primarily due to the dependency of channel state changes on peer interactions. Both sides of a channel can have simultaneous HTLC operations.
Fiber adopts rust-lightning’s approach of using a state machine to track HTLC states, where state transitions occur based on commitment_sign and revoke_and_ack messages. The AddTlc operation and state transitions for both peers are as follows:
obsolete image
Each Fiber node maintains a representation of the network through a Network Graph, essentially a bidirectional directed graph, where:
For privacy reasons, the actual balance partition of a channel is not broadcasted across the network. Instead, the edge weight represents the channel capacity.
Before initiating a payment, the sender performs pathfinding to discover a route to the recipient. If multiple paths available, the sender must determine the optimal one by considering various factors. Finding the best path in a graph with incomplete information is a complex engineering challenge. A detailed discussion of this issue can be found in Mastering Lightning Network.
obsolete image
In Fiber, users initiate payments via RPC requests. When a node receives a payment request, it creates a corresponding PaymentSession to track the payment lifecycle.
The quality of pathfinding directly impacts network efficiency and payment success rates. Currently, Fiber uses a variant of Dijkstra’s algorithm. The implementation can be found here.
However, unlike the standard Dijkstra algorithm, Fiber’s routing expands backward from the target toward the source. During the search, the algorithm considers multiple factors:
Routes are ranked by computing a distance metric. Probability estimation is derived from past payment results and analysis, implemented in the eval_probability module.
Once the path is determined, the next step is to construct an Onion Packet. Then the source node sends an AddTlcCommand to start the payment. The payment status will be updated asynchronously. Whether the HTLC succeeds or fails, the network actor processes the result via event notifications.
Payments in Fiber may require multiple retries due to various factors, with a common failure scenario being:
When a payment fails due to liquidity constraints:
This dynamic retry mechanism ensures that payments have a higher chance of success despite fluctuating network conditions.
Fiber nodes exchange information about new nodes and channels by broadcasting messages. The Gossip module implements the routing gossip protocol defined in BOLTs 7. The key technical decisions were documented in the PR: Refactor gossip protocol.
When a node starts for the first time, it connects to its initial peers using addresses specified in the configuration file under bootnode_addrs.
Fiber supports three types of broadcast messages:
NodeAnnouncementChannelAnnouncementChannelUpdateThe raw broadcast data received is stored in the storage module, allowing messages to be efficiently indexed using a combination of timestamp + message_id. This enables quicker responses to query requests from peer nodes.
When a node starts, the Graph module loads all stored messages using load_from_store to rebuild its network graph.
Fiber propagates gossip messages using a subscription-based model.
BroadcastMessagesFilter) to a peer.This subscription model allows nodes to efficiently receive newly stored gossip messages after a specific cursor, enabling them to dynamically update their network graph, because the network graph also subscribes to gossip messages. The logic for retrieving these messages is implemented in this section.
For privacy and security consideration, payments’ TLC is propagated across multiple nodes using Onion encryption. Each node only accesses the minimal necessary details, such as:
This approach ensures that a node cannot access other sensitive details, including the total length of the payment route. The payment sender encrypts the payment details using onion encryption, and each hop must obfuscate the information before forwarding the TLC to the next node.
In case of an error occurs at any hop during payment forwarding, the affected node sends back an error message along the reverse route to the sender. This error message is also onion-encrypted, ensuring that intermediate nodes cannot decipher its content—only the sender can decrypt it.
We examined the onion packet implementation in rust-lightning and found it to be tightly coupled with rust-lightning’s internal data structures, limiting its generalization. Therefore, we built fiber-sphinx from scratch. For more details, refer to the project spec and the developer’s presentation slides.
The key Onion Encryption & Decryption steps in Fiber include:
Creating the Onion Packet for Sending Payments
Before sending a payment, the sender creates an onion packet, included in the AddTlcCommand sent to the first node in the payment route.
Onion Decryption at Each Hop
Generating an Onion Packet for Error Messages
If an error occurs during TLC forwarding, the node creates a new onion packet containing the error message and sends it back to the previous node.
Decrypting Error Messages at the Payment Sender
When the sender receives a TLC fail event, it decrypts the onion packet containing the error. Based on the error details, the sender can decide whether to resend and update the network graph accordingly.
obsolete image
Watchtower is an important security mechanism in the Lightning Network, primarily used to protect offline users from potential fund theft. It maintains fairness and security by real-time monitoring on-chain transactions and executing penalty transactions when violations are detected.
Fiber’s watchtower implementation is in the WatchtowerActor. This actor listens for key events in the Fiber node. For example：
RemoteTxComplete event, while the watchtower inserts a corresponding record into the database to start monitoring this channel.ChannelClosed event, while the watchtower removes the corresponding record from the database.During TLC interactions in the channel, the watchtower receives RemoteCommitmentSigned and RevokeAndAckReceived events, updating the revocation_data and settlement_data stored in the database respectively. These fields will be used later to create revocation and settlement transactions.
Watchtower’s penalty mechanism ensures that old commitment transactions are not used in a on-chain transaction by comparing the commitment_number. If a violation is detected, the watchtower constructs a revocation transaction and submits it on-chain to penalize the offender. Otherwise, it constructs and sends a settlement transaction.
serde. Data migration remains a challenge, which we address by this standalone program.Fiber is still in the early stages of active development. Looking ahead, we plan to make further improvements in the following areas: