[](https://github.com/astral-sh/ruff)
[](https://github.com/psf/black)
[](http://mypy-lang.org/)
[](http://commitizen.github.io/cz-cli/)
# ⚡ 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](https://github.com/lightning/bolts/blob/master/07-routing-gossip.md)
This python package is part of the [ln-history project](https://github.com/ln-history)
---
## 📦 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
```bash
pip install lnhistoryclient
```
## 🧬 Usage
To parse a raw Lightning Network gossip message, first extract the message type,
then use the type to select the appropriate parser. This ensures correctness
and avoids interpreting invalid data.
The library accepts both bytes and io.BytesIO objects as input for maximum flexibility.
```python
from lnhistoryclient.parser.common import get_message_type
from lnhistoryclient.parser.parser_factory import get_parser_by_message_type
raw_hex = bytes.fromhex("0101...") # Replace with actual raw hex (includes 2-byte type prefix)
msg_type = get_message_type_by_raw_hex(raw_hex)
if msg_type is not None:
parser = get_parser_by_message_type(msg_type)
result = parser(raw_hex[2:]) # Strip the type prefix if your parser expects it
print(result)
else:
print("Unknown or unsupported message type.")
```
For convenience (and if you're confident the input is valid), a shortcut is also available:
```python
from lnhistoryclient.parser.parser_factory import get_parser_from_raw_hex
raw_hex = bytes.fromhex("0101...") # Replace with actual raw hex
parser = get_parser_from_raw_hex(raw_hex)
if parser:
result = parser(raw_hex[2:])
print(result)
else:
print("Could not determine parser.")
```
You can also directly use individual parsers if you know the message type:
```python
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](https://docs.python.org/3/library/typing.html) for every gossip message.
See in the project structure section below for details.
## 📁 Project Structure
```bash
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](https://github.com/astral-sh/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
Raw data
{
"_id": null,
"home_page": null,
"name": "lnhistoryclient",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.7",
"maintainer_email": null,
"keywords": "lightning, network, bitcoin, parser, gossip, ln",
"author": null,
"author_email": "Fabian Kraus <fabian.felix.kraus@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/6d/e8/ff6f6ab7c3e2639cff0fd63f0a4f5a03416b995e2406eb76e308220ba40a/lnhistoryclient-3.3.1.tar.gz",
"platform": null,
"description": "[](https://github.com/astral-sh/ruff)\n[](https://github.com/psf/black)\n[](http://mypy-lang.org/)\n\n\n\n[](http://commitizen.github.io/cz-cli/)\n\n# \u26a1 lnhistoryclient\n\nA 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.\nFor details about the gossip messages see the Lightning Network specifications [BOLT #7](https://github.com/lightning/bolts/blob/master/07-routing-gossip.md)\nThis python package is part of the [ln-history project](https://github.com/ln-history)\n\n---\n\n## \ud83d\udce6 Features\n\n- \ud83d\udd0d Parses raw gossip messages: `ChannelAnnouncement`, `NodeAnnouncement`, `ChannelUpdate`, and more\n- \ud83e\uddf1 Clean and extensible object model (e.g., `ChannelAnnouncement`, `NodeAnnouncement`, `ChannelUpdate`)\n- \ud83e\uddea Tested on real-world data\n- \ud83e\uddf0 Built with reusability in mind for microservice architectures\n\n---\n\n## \ud83d\udee0\ufe0f Installation\n\n```bash\npip install lnhistoryclient\n```\n\n## \ud83e\uddec Usage\n\nTo parse a raw Lightning Network gossip message, first extract the message type,\nthen use the type to select the appropriate parser. This ensures correctness\nand avoids interpreting invalid data.\nThe library accepts both bytes and io.BytesIO objects as input for maximum flexibility.\n\n```python\nfrom lnhistoryclient.parser.common import get_message_type\nfrom lnhistoryclient.parser.parser_factory import get_parser_by_message_type\n\n\nraw_hex = bytes.fromhex(\"0101...\") # Replace with actual raw hex (includes 2-byte type prefix)\n\nmsg_type = get_message_type_by_raw_hex(raw_hex)\nif msg_type is not None:\n parser = get_parser_by_message_type(msg_type)\n result = parser(raw_hex[2:]) # Strip the type prefix if your parser expects it\n print(result)\nelse:\n print(\"Unknown or unsupported message type.\")\n```\n\nFor convenience (and if you're confident the input is valid), a shortcut is also available:\n\n```python\nfrom lnhistoryclient.parser.parser_factory import get_parser_from_raw_hex\n\nraw_hex = bytes.fromhex(\"0101...\") # Replace with actual raw hex\n\nparser = get_parser_from_raw_hex(raw_hex)\nif parser:\n result = parser(raw_hex[2:])\n print(result)\nelse:\n print(\"Could not determine parser.\")\n```\n\nYou can also directly use individual parsers if you know the message type:\n\n```python\nfrom lnhistoryclient.parser.channel_announcement_parser import parse_channel_announcement\n\nresult = parse_channel_announcement(raw_hex)\nprint(result.channel_id, result.node1_id, result.node2_id)\n```\n\n## \ud83c\udfa8 Model\nThe library provides [python typing models](https://docs.python.org/3/library/typing.html) for every gossip message.\nSee in the project structure section below for details.\n\n## \ud83d\udcc1 Project Structure\n```bash\nlnhistoryclient\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 lnhistoryclient\n\u2502 \u251c\u2500\u2500 constants.py\n\u2502 \u251c\u2500\u2500 model\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u251c\u2500\u2500 Address.py\n\u2502 \u2502 \u251c\u2500\u2500 AddressType.py\n\u2502 \u2502 \u251c\u2500\u2500 cache\n\u2502 \u2502 \u2502 \u2514\u2500\u2500 GossipCache.py\n\u2502 \u2502 \u251c\u2500\u2500 ChannelAnnouncement.py\n\u2502 \u2502 \u251c\u2500\u2500 ChannelUpdate.py\n\u2502 \u2502 \u251c\u2500\u2500 core_lightning_internal\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 ChannelAmount.py\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 ChannelDying.py\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 DeleteChannel.py\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 GossipStoreEnded.py\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 PrivateChannelAnnouncement.py\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 PrivateChannelUpdate.py\n\u2502 \u2502 \u2502 \u2514\u2500\u2500 types.py\n\u2502 \u2502 \u251c\u2500\u2500 gossip_event_kafka\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u2502 \u2514\u2500\u2500 GossipEvent.py\n\u2502 \u2502 \u251c\u2500\u2500 gossip_event_zmq\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 ChannelAnnouncementEvent.py\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 ChannelUpdateEvent.py\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 core_lightning_internal\n\u2502 \u2502 \u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u2502 \u2502 \u251c\u2500\u2500 ChannelAmountEvent.py\n\u2502 \u2502 \u2502 \u2502 \u251c\u2500\u2500 ChannelDyingEvent.py\n\u2502 \u2502 \u2502 \u2502 \u251c\u2500\u2500 DeleteChannelEvent.py\n\u2502 \u2502 \u2502 \u2502 \u251c\u2500\u2500 GossipStoreEndedEvent.py\n\u2502 \u2502 \u2502 \u2502 \u251c\u2500\u2500 PrivateChannelAnnouncementEvent.py\n\u2502 \u2502 \u2502 \u2502 \u2514\u2500\u2500 PrivateChannelUpdateEvent.py\n\u2502 \u2502 \u2502 \u2514\u2500\u2500 NodeAnnouncementEvent.py\n\u2502 \u2502 \u251c\u2500\u2500 MessageMetadata.py\n\u2502 \u2502 \u251c\u2500\u2500 NodeAnnouncement.py\n\u2502 \u2502 \u2514\u2500\u2500 types.py\n\u2502 \u2514\u2500\u2500 parser\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 channel_announcement_parser.py\n\u2502 \u251c\u2500\u2500 channel_update_parser.py\n\u2502 \u251c\u2500\u2500 common.py\n\u2502 \u251c\u2500\u2500 core_lightning_internal\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u251c\u2500\u2500 channel_amount_parser.py\n\u2502 \u2502 \u251c\u2500\u2500 channel_dying_parser.py\n\u2502 \u2502 \u251c\u2500\u2500 delete_channel_parser.py\n\u2502 \u2502 \u251c\u2500\u2500 gossip_store_ended_parser.py\n\u2502 \u2502 \u251c\u2500\u2500 private_channel_announcement_parser.py\n\u2502 \u2502 \u2514\u2500\u2500 private_channel_update_parser.py\n\u2502 \u251c\u2500\u2500 node_announcement_parser.py\n\u2502 \u2514\u2500\u2500 parser_factory.py\n\u251c\u2500\u2500 pyproject.toml\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 requirements-dev.txt\n\u2514\u2500\u2500 tests\n```\n\n## \ud83e\uddea Testing\nUnit tests coming soon.\n\n## \ud83e\udde0 Requirements\nPython >=3.7, <4.0\nPure Python, no external dependencies\n\n## Code Style, Linting etc.\nThe code has been formatted using [ruff](https://github.com/astral-sh/ruff), [black]() and [mypy]()\n\n## \ud83e\udd1d Contributing\nPull requests, issues, and feature ideas are always welcome!\nFork the repo\nCreate a new branch\nSubmit a PR with a clear description\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "A reusable parser for Lightning Network gossip messages format.",
"version": "3.3.1",
"project_urls": {
"Homepage": "https://ln-history.info",
"Repository": "https://github.com/ln-history/ln-history-python-client"
},
"split_keywords": [
"lightning",
" network",
" bitcoin",
" parser",
" gossip",
" ln"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0f07bc4f31e69592ed04426c87c7313f26f02b2f114ddf469d6a513e0506043f",
"md5": "d9aa6ff9c61b22fb73036df86a39f4e3",
"sha256": "fa60c7a8c847802889324e7bfb00a6daf80c65c20c8b442065105e4495c940d0"
},
"downloads": -1,
"filename": "lnhistoryclient-3.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d9aa6ff9c61b22fb73036df86a39f4e3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.7",
"size": 28294,
"upload_time": "2025-07-10T10:38:45",
"upload_time_iso_8601": "2025-07-10T10:38:45.000511Z",
"url": "https://files.pythonhosted.org/packages/0f/07/bc4f31e69592ed04426c87c7313f26f02b2f114ddf469d6a513e0506043f/lnhistoryclient-3.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6de8ff6f6ab7c3e2639cff0fd63f0a4f5a03416b995e2406eb76e308220ba40a",
"md5": "c4e425003a62f51bca8f022d1a60f7ee",
"sha256": "8dac4d1486db50933d6edc356f895d000272acd914a29268e3979b5d585c1995"
},
"downloads": -1,
"filename": "lnhistoryclient-3.3.1.tar.gz",
"has_sig": false,
"md5_digest": "c4e425003a62f51bca8f022d1a60f7ee",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.7",
"size": 21220,
"upload_time": "2025-07-10T10:38:46",
"upload_time_iso_8601": "2025-07-10T10:38:46.396073Z",
"url": "https://files.pythonhosted.org/packages/6d/e8/ff6f6ab7c3e2639cff0fd63f0a4f5a03416b995e2406eb76e308220ba40a/lnhistoryclient-3.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-10 10:38:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ln-history",
"github_project": "ln-history-python-client",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "lnhistoryclient"
}
JSON
