DOCSEARCHbyAlgolia
Submit Docs

Rust-Lightning

repository·main·Indexed 23 days ago

https://github.com/lightningdevkit/rust-lightning

A performant, flexible, and runtime-agnostic implementation of the Lightning Network protocol. Designed as a library, it provides core protocol logic and channel state machines while allowing developers to implement their own networking, storage, and key management. The project includes specialized crates such as lightning-invoice for BOLT 11, lightning-rapid-gossip-sync for optimized network graph synchronization, and lightning-liquidity for liquidity management.

Tokens
35.2K
Snippets
64
Records
164
Agent score
80%

What's inside rust-lightning

  2. Understand the Rapid Gossip Sync (RGS) serialization format

    main

    The RGS protocol uses a compressed, compact serialization format designed to omit signatures and use incremental updates. The structure is as follows:

    1. Prefix: 76, 68, 75 (ASCII for LDK).
    2. Version: Currently supports 1 and 2.
    3. Chain Hash: 32 bytes.
    4. Latest Seen Timestamp: u32.
    5. Version 2 Node Features: A byte indicating the count, followed by an array of node features.
    6. Node IDs: An unsigned int count, followed by an array of compressed 33-byte pubkeys (Version 2 may include supplemental feature/address info).
    7. Channel Announcements: An unsigned int count, followed by stripped-down announcement messages.
    8. Channel Updates: An unsigned int count, followed by a series of default values and customized updates.

    Default Values for Updates:

    • default_cltv_expiry_delta
    • default_htlc_minimum_msat
    • default_fee_base_msat
    • default_fee_proportional_millionths
    • default_htlc_maximum_msat (u64, or u64::MAX if no maximum)

    Note: NodeAnnouncement messages are omitted because node IDs are implicitly extracted from channel data.

  3. Configure Monitoring: Watchtowers and Monitor Replicas

    main

    The monitoring (ChainMonitor) subsystem can be deployed using the following configurations:

    • Watchtower: An external, untrusted service used to publish justice transactions. To ensure security, you should subscribe to N watchtowers; the security model assumes you are safe if at least one watchtower behaves correctly.
    • Monitor Replicas: An instance of a highly available, distributed channel-monitor.

    Warning: Monitor Replicas require a correctly functioning Hardware Security Module (HSM) because they manage sensitive keys that, if compromised, could lead to the loss of all funds in the channel.

  4. Understand the core architecture of Rust-Lightning

    main

    Rust-Lightning is a runtime-agnostic implementation of the Lightning Network protocol. The core lightning crate handles the Lightning protocol, channel state machines, and on-chain logic, but it does not manage networking, data persistence, or blockchain interactions itself.

    Instead, it provides a clean API that allows you to plug in your own implementations for:

    • Data Persistence: Store channel state as binary blobs in any format (local disk, database, cloud storage, etc.).
    • Blockchain Data: Provide block headers and transaction information via a block_connected/block_disconnected API.
    • UTXO Management: The library notifies you when outputs are claimable or when a funding transaction needs to be created, allowing you to integrate with existing on-chain wallets.
    • Networking: You can implement your own transport layer (e.g., TCP, USB, serial) to connect to other nodes.
    • Private Keys: You can provide signing logic via a generic API, enabling use cases like hardware wallets where private keys never enter memory.

  5. Understand Channel Roles: Initiator and Counterparty

    main

    In the context of Lightning channel management, roles are defined by who is driving the operation and whose interests the implementation serves:

    • Channel Initiator: The entity that decides to open a channel. The initiator is responsible for paying the on-chain fees for channel opening. Finalization of the opening depends on the counterparty's acceptance policy.
    • Holder: The entity operating the current node. The implementation's primary goal is to serve the interests of the Holder.
    • Counterparty: The peer participating in the channel operation. The implementation treats the counterparty as an external entity whose specific interests are not the focus of the local implementation.

    These terms are used throughout the Channel data structure in the channel-management subsystem.

  6. Understand Transaction Roles: Broadcaster and Countersignatory

    main

    Because Lightning states are symmetric but punishment is asymmetric, parties must maintain different commitment transactions. The roles in transaction construction are:

    • Broadcaster: The entity that has the unilateral capability to broadcast the transaction to the network.
    • Countersignatory: The entity that provides signatures for the broadcastable transaction, thereby verifying that it correctly encodes the off-chain states.

    At any given time, there should be two 'latest' commitment transactions processed by the implementation:

    1. The Holder is the Broadcaster and the Counterparty is the Countersignatory.
    2. The Holder is the Countersignatory and the Counterparty is the Broadcaster.

    These roles are used across the channel-utils library (chan_utils.rs).

  7. Integrate lightning-liquidity with an LDK node

    main

    To integrate lightning-liquidity with an LDK-based node, you must set up a LiquidityManager and configure it as the CustomMessageHandler of your LDK node.

    Once configured, you can access specific protocol handlers depending on whether you are building a client or a service:

    • Client-side handlers: LiquidityManager::lsps1_client_handler and LiquidityManager::lsps2_client_handler.
    • Service-side handlers: LiquidityManager::lsps2_service_handler and LiquidityManager::lsps5_service_handler.
    • Client-side (Webhooks): LiquidityManager::lsps5_client_handler.

    LiquidityManager uses an eventing system to notify you about protocol updates. You must handle these events by calling the provided event handling methods, such as LiquidityManager::next_event.

  8. Choose between Rust-Lightning, LDK, and LDK-node

    main

    Depending on your integration needs, you should choose one of the following paths:

    • rust-lightning (the lightning crate): Use this if you want maximum control and want to implement your own custom logic for storage, networking, and key management.
    • LDK (Lightning Development Kit): This encompasses the rust-lightning core plus its sample modules (like lightning-persister), language bindings, and sample node implementations. Use this for a more complete set of building blocks.
    • LDK-sample: Use this if you want an out-of-the-box Lightning node implementation.
    • LDK-node: Use this if you want to easily integrate Lightning into an existing application without handling all the boilerplate code.

  9. Use RapidGossipSync to synchronize the network graph

    main

    To perform a rapid gossip sync, use the RapidGossipSync instance to apply snapshots retrieved from an RGS (Rapid Gossip Sync) server.

    Initial Sync

    To start from the beginning, request a snapshot from the RGS server using an initial timestamp of 0.

    Incremental Sync

    When applying a snapshot, the sync methods return a Result<u32, GraphSyncError>. The successful u32 value is the timestamp that must be used for the subsequent server request to ensure continuous synchronization.

    Managing Timestamps

    You do not need to implement additional caching for the timestamp. The RapidGossipSync methods automatically update the timestamp stored within the NetworkGraph object. You can retrieve the current sync timestamp by calling get_last_rapid_gossip_sync_timestamp on the NetworkGraph.

  11. What is the BackgroundProcessor and when to use it

    main

    The BackgroundProcessor is a utility designed to handle tasks that must run periodically to maintain the proper operation of Rust-Lightning. These tasks are suitable for background execution to avoid blocking the main application logic.

    Key Responsibilities:

    • Event Processing: Processes [Event]s using a user-provided [EventHandler].
    • ChannelManager Persistence: Monitors if the [ChannelManager] needs re-persisting to disk and performs the write operation in the background.
    • Periodic Ticks: Automatically calls the following methods at appropriate intervals:
      • [ChannelManager::timer_tick_occurred]
      • [ChainMonitor::rebroadcast_pending_claims]
      • [PeerManager::timer_tick_occurred]
    • Network Graph Maintenance: If a [GossipSync] with a [NetworkGraph] is provided during startup, it calls [NetworkGraph::remove_stale_channels_and_tracking].
    • Peer Event Processing: Periodically calls [PeerManager::process_events] (note: this may result in higher latency).

    Important Safety Note: If [ChannelManager] persistence fails and the persisted state becomes outdated, there is a risk of channels being force-closed on startup. However, as long as [ChannelMonitor] backups are valid, funds are generally safe except for those used for unilateral chain closure fees.

    Lifecycle Note: BackgroundProcessor will immediately stop when it is dropped. It should be stored in a long-lived location until application shutdown.

  12. How marker sequences work in BOLT 12

    main

    In BOLT 12 selective disclosure, markers are used to identify omitted TLVs. A marker is typically one greater than the previous value (either the previous included TLV or the previous marker).

    Crucially, there is a gap between the standard invoice TLV range and the experimental/signature range. The next_marker function ensures that if a marker would land in this signature range (e.g., landing on 240), it instead jumps to the start of the experimental range (e.g., 1_000_000_000). This ensures producers and consumers stay in agreement regarding the marker sequence.