lnhistoryclient 2.1.2

A reusable parser for Lightning Network gossip messages format.

⚡ lnhistoryclient

A Python client library to parse and handle raw Lightning Network gossip messages from the gossip store. Centralized, reusable, and production-tested on real-world data. Perfect for microservices that consume Lightning Network data in raw_hex format. For details about the gossip messages see the Lightning Network specifications BOLT #7 This python package is part of the ln-history project

---

📦 Features

• 🔍 Parses raw gossip messages: ChannelAnnouncement, NodeAnnouncement, ChannelUpdate, and more
• 🧱 Clean and extensible object model (e.g., ChannelAnnouncement, NodeAnnouncement, ChannelUpdate)
• 🧪 Tested on real-world data
• 🧰 Built with reusability in mind for microservice architectures

---

🛠️ Installation

pip install lnhistoryclient

🧬 Usage

from lnhistoryclient.parser import parser_factory

raw_hex = "0101..."  # Replace with actual raw gossip hex string (including the 2-Byte type field)
parsed = parser_factory.get_parser_by_raw_hex(raw_hex)

print(parsed)

You can also directly use individual parsers if you know the message type:

from lnhistoryclient.parser.channel_announcement_parser import parse_channel_announcement

result = parse_channel_announcement(raw_hex)
print(result.channel_id, result.node1_id, result.node2_id)

🎨 Model

The library provides python typing models for every gossip message. See in the project structure section below for details.

📁 Project Structure

lnhistoryclient
├── LICENSE
├── lnhistoryclient
│   ├── constants.py
│   ├── model
│   │   ├── __init__.py
│   │   ├── Address.py
│   │   ├── AddressType.py
│   │   ├── cache
│   │   │   └── GossipCache.py
│   │   ├── ChannelAnnouncement.py
│   │   ├── ChannelUpdate.py
│   │   ├── core_lightning_internal
│   │   │   ├── __init__.py
│   │   │   ├── ChannelAmount.py
│   │   │   ├── ChannelDying.py
│   │   │   ├── DeleteChannel.py
│   │   │   ├── GossipStoreEnded.py
│   │   │   ├── PrivateChannelAnnouncement.py
│   │   │   ├── PrivateChannelUpdate.py
│   │   │   └── types.py
│   │   ├── gossip_event_kafka
│   │   │   ├── __init__.py
│   │   │   └── GossipEvent.py
│   │   ├── gossip_event_zmq
│   │   │   ├── __init__.py
│   │   │   ├── ChannelAnnouncementEvent.py
│   │   │   ├── ChannelUpdateEvent.py
│   │   │   ├── core_lightning_internal
│   │   │   │   ├── __init__.py
│   │   │   │   ├── ChannelAmountEvent.py
│   │   │   │   ├── ChannelDyingEvent.py
│   │   │   │   ├── DeleteChannelEvent.py
│   │   │   │   ├── GossipStoreEndedEvent.py
│   │   │   │   ├── PrivateChannelAnnouncementEvent.py
│   │   │   │   └── PrivateChannelUpdateEvent.py
│   │   │   └── NodeAnnouncementEvent.py
│   │   ├── MessageMetadata.py
│   │   ├── NodeAnnouncement.py
│   │   └── types.py
│   └── parser
│       ├── __init__.py
│       ├── channel_announcement_parser.py
│       ├── channel_update_parser.py
│       ├── common.py
│       ├── core_lightning_internal
│       │   ├── __init__.py
│       │   ├── channel_amount_parser.py
│       │   ├── channel_dying_parser.py
│       │   ├── delete_channel_parser.py
│       │   ├── gossip_store_ended_parser.py
│       │   ├── private_channel_announcement_parser.py
│       │   └── private_channel_update_parser.py
│       ├── node_announcement_parser.py
│       └── parser_factory.py
├── pyproject.toml
├── README.md
├── requirements-dev.txt
└── tests

🧪 Testing

Unit tests coming soon.

🧠 Requirements

Python >=3.7, <4.0 Pure Python, no external dependencies

Code Style, Linting etc.

The code has been formatted using ruff, black and mypy

🤝 Contributing

Pull requests, issues, and feature ideas are always welcome! Fork the repo Create a new branch Submit a PR with a clear description