Node Announcement (Lightning Gossip)

What Is a Node Announcement?

A node announcement (formally node_announcement) is one of the three core gossip messages defined in BOLT 7, the Lightning Network specification for routing gossip. While channel_announcement proves a channel exists on-chain and channel_update advertises routing fees and policies, the node_announcement message tells the network who a node is and how to reach it.

Every Lightning node that operates at least one public channel can broadcast a node_announcement containing its public key, IP addresses or Tor onion addresses, a human-readable alias (up to 32 bytes), an RGB color for visual identification, and a set of feature flags describing which protocol extensions it supports. Other nodes relay valid announcements to their own peers, flooding the message across the network so every participant can maintain an up-to-date view of the topology.

How It Works

The node_announcement message is type 257 in the Lightning wire protocol. When a node wants to advertise or update its information, it constructs and signs a node_announcement, then sends it to all connected peers. Those peers validate the message and, if it is newer than any previous announcement from the same node, forward it onward.

Message Fields

The message contains the following fields, serialized in order:

node_announcement (type 257)
+------------+--------+------------------------------------------+
| Field      | Size   | Description                              |
+------------+--------+------------------------------------------+
| signature  | 64 B   | Schnorr/ECDSA sig over the message body  |
| flen       | 2 B    | Length of feature bit field               |
| features   | flen B | Supported protocol features (BOLT 9)     |
| timestamp  | 4 B    | UNIX timestamp for ordering updates      |
| node_id    | 33 B   | Compressed public key of the node        |
| rgb_color  | 3 B    | Display color (red, green, blue)         |
| alias      | 32 B   | UTF-8 node name, zero-padded             |
| addrlen    | 2 B    | Length of address descriptors            |
| addresses  | var    | Network address descriptors              |
+------------+--------+------------------------------------------+

The signature field covers the double-SHA256 hash of everything after itself: features, timestamp, node_id, color, alias, and addresses. This proves that the announcement was created by the holder of the corresponding private key.

Address Descriptors

The addresses field contains one or more address descriptors, each prefixed by a single-byte type identifier:

• Type 1: IPv4 address (4 bytes) plus port (2 bytes), 6 bytes total
• Type 2: IPv6 address (16 bytes) plus port (2 bytes), 18 bytes total
• Type 4: Tor v3 onion address (35 bytes: 32-byte ed25519 public key, 2-byte checksum, 1-byte version) plus port (2 bytes), 37 bytes total

Type 3 was formerly used for Tor v2 onion services but is now deprecated and ignored by conforming implementations. Addresses must be listed in ascending order by type, and ports of zero are ignored by receivers.

Validation Rules

When a node receives a node_announcement, it applies several checks before accepting and relaying the message:

1. The node_id must have appeared in a prior channel_announcement. Without at least one confirmed public channel, the announcement is ignored. This is the key anti-spam mechanism: creating a channel requires locking real bitcoin in an on-chain funding transaction.
2. The signature must be valid for the given node_id. Invalid signatures cause the message to be dropped immediately.
3. The timestamp must be strictly greater than any previously accepted node_announcement from the same node. Older or equal timestamps are ignored, which prevents replay of stale information.
4. If the features field contains unknown even (compulsory) bits, the receiving node must not route payments through the announcing node and should avoid connecting to it.

Timestamp and Updates

The timestamp field serves as a version number. A node that changes its IP address, adds Tor support, enables a new protocol feature, or simply wants to refresh its presence broadcasts a new node_announcement with a higher timestamp. Receivers compare timestamps and keep only the latest version. The specification recommends using a UNIX timestamp for this field, though any monotonically increasing value is valid.

Nodes typically rebroadcast their announcement periodically (often every few days) even if nothing has changed, to ensure their information propagates to newly joined peers. Stale announcements from nodes whose channels have all closed are eventually pruned from the network graph.

Node Alias and Color

Two fields give nodes a human-friendly identity. The rgb_color field is three bytes representing red, green, and blue values, used by explorers and visualization tools to render nodes on network graphs. The alias field is a fixed 32-byte UTF-8 string, zero-padded at the end, that serves as the node's human-readable name.

Because aliases are self-assigned and not unique, any software displaying them must treat the data as untrusted. The BOLT 7 specification explicitly warns that aliases should be sanitized before rendering in HTML or JavaScript contexts and escaped before database storage, to prevent cross-site scripting and injection attacks.

Feature Flags

The features field advertises which protocol extensions a node supports, encoded as a variable-length bit vector following the conventions defined in BOLT 9. Even-numbered bits indicate compulsory features (the sender requires peers to understand them), while odd-numbered bits indicate optional features.

Examples of features commonly advertised in node_announcements include support for anchor outputs, onion messaging, blinded paths, simple taproot channels, and multi-path payments. Routing nodes use these flags to determine whether a peer supports the protocol features required for a given payment path.

Use Cases

Payment Routing

The most critical use of node_announcement data is payment routing. When a wallet or routing node builds a path from sender to receiver, it consults the network graph constructed from gossip messages. The node_announcement tells the pathfinding algorithm which nodes are reachable, what addresses they listen on, and whether their feature set is compatible with the payment being sent.

Network Explorers

Block explorers and network visualization tools such as Amboss, mempool.space, and 1ML aggregate node_announcement data to display network statistics: node count, geographic distribution (inferred from IP addresses), capacity, alias, and color. The alias and rgb_color fields make these visualizations human-readable.

Peer Connection

When a wallet or node needs to open a new channel, it uses the address descriptors from node_announcements to discover how to reach potential peers. This is a core part of peer discovery: without node_announcements, a node would need out-of-band information (like a manual connection string) to find and connect to every peer.

Mobile and Lightweight Clients

Mobile Lightning wallets often cannot process the full gossip stream due to bandwidth and battery constraints. Protocols like rapid gossip sync compress node_announcement and channel_update data into compact snapshots, allowing mobile clients to bootstrap a routing graph without downloading every individual gossip message. The timestamp field makes this efficient: clients can request only announcements newer than their last sync.

Relationship to Other Gossip Messages

BOLT 7 defines three gossip messages that work together to describe the Lightning Network topology:

The channel_announcement is the anchor: it ties two node_ids to a specific UTXO on the Bitcoin blockchain. Only after a valid channel_announcement has been accepted will receivers process node_announcements from those node_ids. This dependency chain prevents attackers from flooding the network with fake node identities.

Risks and Considerations

Privacy Tradeoffs

Broadcasting a node_announcement reveals the node's IP addresses and Tor onion addresses to the entire network. Operators who prioritize privacy may use Tor-only addresses or operate private channels that do not generate gossip messages at all. The Noise protocol secures the connection between peers, but the node_announcement itself is public by design.

Gossip Bandwidth

As the Lightning Network grows, the volume of gossip messages increases. Each node_announcement is relatively small, but the aggregate bandwidth required to receive, validate, and relay thousands of announcements can strain resource-constrained devices. The timestamp-based deduplication helps, but large networks still generate significant gossip traffic. Proposals for gossip v2 aim to reduce this overhead by using inventory-based message exchange rather than unconditional flooding.

Alias Spoofing

Because aliases are self-assigned and not enforced to be unique, any node can set its alias to mimic well-known nodes. Users and software should always verify a node by its node_id (public key), not its alias. Displaying both the alias and a truncated node_id is standard practice in wallets and explorers to mitigate impersonation.

Stale Announcements

If a node goes offline without closing its channels, its last node_announcement remains in the network graph. Routing attempts through the node will fail, wasting time and fee budget in the pathfinding process. Implementations typically prune announcements from nodes that have not refreshed within a configurable window (often two weeks).

Why It Matters

The node_announcement message is the foundation of the Lightning Network's decentralized directory service. Without it, every node connection and payment route would require out-of-band coordination. By combining node_announcements with channel_announcements and channel_updates, the gossip protocol gives every participant a shared, self-updating map of the network: who is online, where they can be reached, and what capabilities they support.

For Layer 2 systems like the Lightning Network and beyond, efficient peer discovery and metadata distribution are essential to scaling payments. As protocols evolve with features like blinded paths and onion messaging, the feature flags in node_announcements ensure that the network can coordinate upgrades without breaking backward compatibility.

This glossary entry is for informational purposes only and does not constitute financial or investment advice. Always do your own research before using any protocol or technology.