⚡️ Motivation
Since the beginning of Bitcoin on Janurary 3rd 2009, it has kept many of its promises and is establishing itself as a store-of-value solution. Nonetheless Satoshi Nakamoto titled in the Bitcoin Whitepaper "Bitcoin: A Peer-to-Peer Electronic Cash System", emphesising on its use case as digital cash for peer to peer transactions. The Bitcoin blockchain, the leger that keeps track of every transaction, is limited in its scaleability. To keep the Bitcoin blockchain as decentralized as possible, any idea of directly scaling it by e. g. increasing the storage size per block, failed.
With a constant rate of adoption, storing information on the Bitcoin blockchain is scarce. In 2024 transaction costs reached record highs, making it unaffordable for daily use.
The Lightning Network - a second layer solution on top of Bitcoin - deployed in 2018, promises lightning fast and cheap payments, ultimatly scaling the transaction volume of Bitcoin. The technology of the Bitcoin Lightning Network is defined in BOLTS. Although more than seven years passed, there are open questions for research about the Bitcoin Lightning Network.
🏁 Goal
The aim of this open source project is to build a platform for researchers as well as node runners to help understand the (changing) topology of the Bitcoin Lightning Network, making it more accessible.
Precisly we want the following requirements to be met
- Get a snapshot (raw gossip messages) of the network at a given timestamp (How did the network look?)
- Get the difference between two snapshots for two given timestamps (How did the network change?)
- Get all gossip messages by a given node_id (How much did a node contribute to the network change?)
- Get all gossip messages by a given scid (How much did a channel change ?)
We also build a backend that exposes an API that can be accessed to get those analysis results. See here for the code behind the analysis.
📊 Data
The analyzed gossip messages come from Christian Deckers lnresearch repository. Additionally we spin up our one nodes in July 2025 to record gossip messages.
We currently have a total number of around 100 million recorded gossip messages.
We can see that the number of channel update messages has been changing a lot.
As the number of nodes in the Bitcoin Lightning Network rose, the number of node anouncement messages also rose.
⊰⊱ Schema
To meet the requirements we use a postgresql database with the btree_gist extension.
You can build the database yourself by creating the following tables:
-- Enable necessary extensions
CREATE EXTENSION IF NOT EXISTS btree_gist;
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
-- TABLE: Nodes
CREATE TABLE Nodes (
node_id CHAR(66) PRIMARY KEY NOT NULL,
validity TSTZRANGE,
from_timestamp TIMESTAMPTZ GENERATED ALWAYS AS (lower(validity)) STORED,
last_seen TIMESTAMPTZ GENERATED ALWAYS AS (upper(validity)) STORED
);
-- TABLE: NodesRawGossip
CREATE TABLE NodesRawGossip (
gossip_id CHAR(64) PRIMARY KEY NOT NULL,
node_id CHAR(66) NOT NULL REFERENCES Nodes(node_id),
timestamp TIMESTAMPTZ NOT NULL,
raw_gossip BYTEA NOT NULL
);
-- TABLE: Channels
CREATE TABLE Channels (
gossip_id CHAR(64),
scid VARCHAR(23) PRIMARY KEY,
source_node_id CHAR(66) NOT NULL REFERENCES Nodes(node_id),
target_node_id CHAR(66) NOT NULL REFERENCES Nodes(node_id),
validity TSTZRANGE NOT NULL,
from_timestamp TIMESTAMPTZ GENERATED ALWAYS AS (lower(validity)) STORED,
to_timestamp TIMESTAMPTZ GENERATED ALWAYS AS (upper(validity)) STORED,
amount_sat INT,
raw_gossip BYTEA
);
-- TABLE: ChannelUpdates
CREATE TABLE ChannelUpdates (
gossip_id CHAR(64) PRIMARY KEY,
scid VARCHAR(23) NOT NULL REFERENCES Channels(scid),
direction BIT NOT NULL,
validity TSTZRANGE NOT NULL,
from_update_timestamp TIMESTAMPTZ GENERATED ALWAYS AS (lower(validity)) STORED,
to_update_timestamp TIMESTAMPTZ GENERATED ALWAYS AS (upper(validity)) STORED,
raw_gossip BYTEA
);
💻 Api
See here for the swagger documentation of our API. The backend code can be found on GitHub or mirrored on my univerisities GitLab