How nodes discover each other, build the channel graph, and propagate routing information across the network — a deep dive into BOLT #7. Covers message types, gossip propagation dynamics, privacy implications of on-chain linkability, and the road to Gossip v2.
When Alice wants to pay Carol, she must find a path through the channel graph. But Lightning Network has thousands of nodes and channels — Alice can't know the full topology without learning it somehow. The design choice of how to learn topology has major security, privacy, and scalability consequences.
Alice needs to know:
Each node tells its peers what it knows. Peers tell their peers. Information propagates organically:
Censorship risk. Privacy-leaking. Offline = no routing.
No single point of failure. Censorship-resistant. Anyone can participate.
"I exist! Here's my public key, IP address, display name, and what features I support."
AuthenticatedIdentity
"This channel exists! Here's the on-chain UTXO that proves it, and the two node pubkeys."
On-chain verifiedPrivacy risk
"This channel's current fee policy: base 1000 msat, rate 100 ppm, CLTV delta 40 blocks."
High frequencyRouting critical
Click each message type to expand. Click individual fields to see detailed explanations and examples.
node_announcementBroadcast by a node to announce its existence and metadata to the network
The node signs the entire announcement message with its node private key. This authenticates that the node actually controls this public key — prevents impersonation. Signature covers all other fields.
Verifiers check: verify(sig, sha256d(msg), node_id)
A bit vector declaring what protocol features this node supports. Common bits:
• Bit 4/5: option_upfront_shutdown_script
• Bit 8/9: var_onion_optin (TLV onion)
• Bit 18/19: option_anchor_outputs
• Bit 44/45: option_channel_type
Even bits = optional, Odd bits = required.
Unix timestamp (seconds) when this announcement was created. Nodes reject announcements older than 2 weeks — this prevents old stale announcements from clogging the network.
If a node broadcasts a new announcement with a higher timestamp, peers replace the old one. This is how nodes "refresh" their presence.
The node's persistent public key. This is the primary identifier for a node on the Lightning Network. It is used to:
• Address payments (BOLT #11 invoices)
• Verify gossip signatures
• Establish peer connections (noise handshake)
Example: 02abcdef1234... (33 bytes, 66 hex chars)
A self-chosen RGB color for display in network explorers (e.g., amboss.space, 1ml.com). Completely cosmetic — has no protocol effect. Nodes like ACINQ choose blue, others choose their brand colors.
Format: R G B each 1 byte (0–255). Example: 0x0D1117 = almost black.
A human-readable name chosen by the node operator. Examples: "ACINQ", "Bitfinex", "WalletOfSatoshi". Zero-padded to 32 bytes.
⚠️ Not unique or verified — anyone can claim any alias. Always identify nodes by their node_id, not alias.
Where to connect to this node. Each address is type-prefixed:
• type=1: IPv4 — 4 bytes IP + 2 bytes port = 6 bytes
• type=2: IPv6 — 16 bytes IP + 2 bytes port = 18 bytes
• type=4: Tor v3 — 35 bytes .onion + 2 bytes port = 37 bytes
A node can list multiple addresses for redundancy. Tor-only nodes have no IPv4/IPv6 addresses, preserving network-level anonymity.
channel_announcementAnnounces a new channel exists, proven by on-chain UTXO reference. Signed by both nodes AND both Bitcoin keys.
Both nodes sign the announcement with their Lightning node keys. Node 1 is defined as the node with the lexicographically lower pubkey. This proves both parties agree this channel should be publicly announced.
Both nodes also sign with their Bitcoin funding keys (the keys in the 2-of-2 multisig). This proves they actually control the on-chain funds — you can't fake a channel announcement without controlling the UTXO.
Verifiers check: bitcoin_key_1 signed the announcement hash.
The genesis block hash of the Bitcoin network. For mainnet: 000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f. Prevents testnet channels leaking onto mainnet gossip.
A compact on-chain identifier encoding three pieces of information:
• Bits 63–40: Block height (3 bytes = 24 bits, supports ~16M blocks)
• Bits 39–16: Transaction index within that block (3 bytes)
• Bits 15–0: Output index (2 bytes)
Format: BLOCK x TX_INDEX x OUTPUT e.g. 820000x100x0
This uniquely identifies the funding UTXO, which nodes use to verify the channel on-chain.
The two endpoint node pubkeys. Node 1 has the lexicographically lower pubkey. These are the identities used in routing — channel_updates reference which direction by a flag bit rather than repeating pubkeys.
The actual keys used in the 2-of-2 on-chain multisig output. These are different from the node_ids — each channel uses unique derived keys for the funding output.
⚠️ Privacy leak: These keys definitively link the on-chain UTXO to the Lightning node identity.
⚠️ Cross-layer deanonymization vector (Romiti et al. 2021): channel_announcement explicitly links an on-chain UTXO (via SCID) to two Lightning node pubkeys (via bitcoin_key_1/2 signatures). This is a fundamental privacy leak — see §6.
channel_updateThe most frequently sent message. Each direction of a channel has its own update announcing fee policy. Sent when fees change, or to refresh channel liveness.
Bit 0 (direction): 0 = this update is from node1 (lower pubkey) forwarding to node2; 1 = from node2 to node1. Each channel has two independent channel_update messages, one per direction.
Bit 1 (disabled): If set, this channel direction is temporarily disabled. Routers should not use it. Commonly set when a node is going offline or the channel is unbalanced.
How many additional blocks this node adds to the CLTV (CheckLockTimeVerify) expiry when forwarding an HTLC. This is the node's safety buffer for claiming funds if something goes wrong.
Typical values: 40–144 blocks. Higher = safer but payments take longer to expire if stuck. Example: if Alice sends to Carol via Bob, and Bob's delta is 40, Carol's CLTV must expire at least 40 blocks before Bob's.
A flat fee charged for every HTLC routed through this channel direction, regardless of payment amount. Denominated in millisatoshis (1/1000 of a satoshi).
Example: fee_base_msat = 1000 means 1 satoshi base fee per payment. Common range: 0–2000 msat.
A proportional fee expressed in parts per million (PPM). The fee is amount_msat × ppm / 1,000,000.
Example: ppm = 100 means 100 ppm = 0.01% = 100 sat per 1M sat = 1 sat per 10,000 sat routed.
Total fee = fee_base_msat + floor(amount × ppm / 1_000_000)
Common range: 1–500 PPM. Competitive nodes often set 1–20 PPM.
minimum: Smallest HTLC this channel will accept. Typically 1 msat. Setting higher rejects micropayments.
maximum: Largest single HTLC. Operators set this to limit exposure to a single payment. Typically 80–100% of channel capacity. Senders probe by trying and failing if over limit.
channel_update messages — one per direction:Watch how a new channel_update received by Alice propagates across the network. Each time step, nodes forward to their neighbors (excluding the sender). Controls: step through manually or run automatically.
Without controls, gossip could flood the network. BOLT #7 defines several rate-limiting mechanisms:
Each peer connection has a maximum gossip rate (e.g., max N messages/second). Exceeding this causes the peer to be temporarily throttled or disconnected.
Nodes reject any gossip message with a timestamp older than 2 weeks. This prevents replay attacks of old channel_updates and limits storage requirements.
Every channel_update must be signed by the node that controls that channel direction. You cannot forge updates for channels you don't own.
Nodes track which messages they've seen (by signature hash). They never re-forward a message to the peer it came from, and skip duplicates. Prevents echo storms.
channel_announcements reference a real UTXO. Nodes with a Bitcoin node verify the UTXO exists with the correct amount — fake channels without real on-chain funds are rejected.
Implementations typically enforce a minimum interval between channel_updates for the same channel (e.g., once per minute). Rapid oscillation triggers rate limiting.
After receiving gossip, Alice maintains an in-memory channel graph. This is the data structure used for pathfinding.
// Alice's local channel graph data structure graph = { nodes: { "02abc...": { alias: "Bob", ip: "1.2.3.4:9735", features: ["var_onion", "anchor_outputs"], last_seen: 1746000000 }, "03def...": { alias: "Carol", ip: "5.6.7.8:9735" }, }, channels: { "820000x100x0": { node1: "02abc...", node2: "03def...", capacity: 1_000_000, // sats — from on-chain lookup update_node1: { // Node1→Node2 direction fee_base: 1000, // msat fee_rate: 100, // PPM cltv_delta: 40, htlc_min: 1, htlc_max: 900_000_000, // msat enabled: true, timestamp: 1746000000 }, update_node2: { // Node2→Node1 direction fee_base: 500, fee_rate: 50, cltv_delta: 40, htlc_min: 1, htlc_max: 850_000_000, // msat enabled: true, timestamp: 1745999500 } } } }
Alice knows channel capacity but not balance split. Under a uniform distribution assumption, probability of routing a payment of size X through a channel of capacity C is: P = (C - X) / C for each channel.
When a brand new Lightning node starts up, it has an empty channel graph. It needs to download the entire network topology to find payment paths. This bootstrapping process is slow, bandwidth-heavy, and has privacy implications.
gossip_timestamp_filter (past 2 weeks)gossip_timestamp_filter to each peerchannel_announcement you missedchannel_update (2 per channel!)Problems: slow, high bandwidth, reveals bootstrapping to peers, many duplicate messages
Benefits: bandwidth proportional to diff, reveals less about node state, much faster resync
Nodes send this to peers to request gossip from a specific time range. Format: (chain_hash, first_timestamp, timestamp_range). A new node sends: first=0, range=now (get everything). A node that was briefly offline sends a shorter range.
A node can request specific channels by SCID. The peer responds with reply_short_channel_ids_end and the requested channel data. Used for targeted updates rather than full resync.
A node can ask: "Tell me all channels opened between block X and block Y." Peer responds with compressed list of SCIDs in that range. More efficient than timestamp-based sync for initial graph building.
The gossip protocol was designed for routing efficiency, not privacy. The result: Lightning Network channel announcements create a rich deanonymization surface that links on-chain identities to Lightning node identities. Romiti et al. (2021) quantified this at ~80% of early channels being linkable.
node_announcement contains the node's IP. Combined with funding UTXO trail: Lightning pubkey → on-chain identity → real-world IP → potentially real person.
Result: ~80% of channels in early LN dataset were fully linkable to on-chain identities (Romiti et al. CCS 2021)
With Taproot (P2TR), the funding output is a MuSig2 aggregate key that looks like any other Taproot key-path spend. No 2-of-2 multisig "tell" on-chain. Much harder to identify as a Lightning channel from blockchain data alone.
Receivers can hide their channels from the graph. Instead of advertising "pay to node X channel Y", they advertise a blinded path. Gossip for these channels is not broadcasted to the full network.
Channels that are never gossiped. Both parties must know each other directly (e.g., through a private introduction). No SCID in gossip means no on-chain linkage via gossip — though the UTXO still exists on-chain.
Nodes can announce only Tor v3 .onion addresses, hiding their IP from the gossip layer. Many privacy-conscious nodes operate Tor-only. This breaks the "IP → real person" part of the deanon chain.
OP_2 <key1> <key2> OP_2 OP_CHECKMULTISIGOP_1 <aggregated_key>channel_update messagesThe current gossip protocol has known scaling problems. As the Lightning Network grows, these become more acute — especially for mobile/light clients that can't store the full graph. Several proposals address different aspects of the problem.
Click each proposal to expand implementation details:
Instead of computing a full path, a light client says: "Route this to Trampoline Node T, who will figure out the next hops." This means the light client only needs to know how to reach a few large trampoline nodes, not the full graph.
Privacy trade-off: the trampoline node sees the payment destination (though BOLT #12 blinded paths can mitigate this). The light client doesn't need to download thousands of channel updates daily.
Specified in BOLT #12 (Offers) ecosystem. ACINQ's Phoenix wallet uses this approach.
Minisketch (Erlay-style) allows two peers to sync their sets of known channel IDs using only O(d) messages, where d = set difference size. Instead of "send me everything from the last 2 weeks", two nodes compute a compact sketch of what they know and exchange only differences.
Benefits: A node that's been offline 5 minutes downloads only 5 minutes of changes, not 2 weeks. Reduces bandwidth by ~10x for common cases. Also reveals less about the timing of when you were offline.
Proposed by t-bast and others in LN spec discussions. Requires protocol upgrade across all implementations.
Proposal: channels expire after a shorter TTL (e.g., 1 week instead of 2). Nodes must periodically re-announce channels to keep them active. Dead channels get pruned faster, resulting in a more accurate graph.
Trade-off: more gossip traffic (every node must re-announce every week). Benefits routing reliability — stale channels cause payment failures. LND has experimented with aggressive pruning of un-refreshed channels.
Instead of advertising "I have a channel with Bob at SCID 820000x100x0", a node advertises a blinded path: "Route to this introduction node using this blinded onion." Senders can reach the node without knowing its exact channel topology.
Combined with BOLT #12 Offers, this allows a receiver to fully hide which channels they control. The gossip of these blinded paths contains less identifying information than traditional channel announcements.
Particularly valuable for merchants who don't want to reveal their node identity or liquidity position via gossip.
The fundamental tension in LN gossip: routing requires knowing the graph, but sharing the graph leaks topology and on-chain linkages. Current research explores zero-knowledge proof approaches where nodes can prove "I have a valid funded channel" without revealing which UTXO it is — analogous to ZK-proofs used in privacy coins. This remains an open research problem as of 2025.
P2P Node and Channel Discovery. The canonical specification for all gossip message types, propagation rules, and sync mechanisms. lightning/bolts repository.
"Cross-Layer Deanonymization Methods in the Lightning Protocol." CCS 2021. Quantified linkage of 80% of LN channels to on-chain identities via channel_announcement analysis.
Efficient set reconciliation for transaction relay (Bitcoin Core). The same technique is proposed for LN gossip v2. Reduces bandwidth from O(n) to O(diff size).
Introduces blinded paths and route blinding, which change how nodes can be reached without full gossip exposure. Directly impacts gossip privacy design.