Core Lightning (CLN) Documentation

Core Lightning (CLN) provides several entry points depending on whether you are operating a node or developing software. The documentation portal offers specific paths for:

• Installation: Instructions for installing Core Lightning on various platforms and environments.
• Configuration: Guidance on choosing and applying configuration options to suit your node's needs.
• Upgrading: Procedures for upgrading to the latest stable releases without service interruption.
• Beginner's Guide: A foundational guide covering the basics required to get a node up and running immediately.

pyln-proto is a pure Python implementation of the Lightning Network protocol.

Security Warning: This package is intended strictly for protocol testing and minor tooling. It is not considered secure enough to handle real funds.

MsgGen is a collection of tools designed to parse schemas and protocol wire CSVs into an intermediate in-memory representation. It is used to generate language-specific bindings and documentation from these schemas.

The toolchain follows this dependency flow:

1. JSON-RPC Schemas are parsed into the msggen model.
2. The msggen model is used to generate:
   • grpc proto files (which lead to Rust grpc bindings and ultimately cln-grpc).
   • Rust From<JsonRpc> Converters (used by cln-grpc).
   • Rust JSON-RPC structs (used by cln-rpc).
3. Patches are applied to the model to enrich it before generation.

Core Lightning provides several resources specifically for node operators to manage, extend, and troubleshoot their deployments:

• Analytics: Tools to analyze node data for effective management.
• Plugins: A wide range of available plugins to extend Core Lightning functionality.
• Troubleshooting & FAQ: Guidance on common issues and frequently asked questions regarding CLN node operation.

In addition to the built-in SQL plugin, you can use several third-party Graphical User Interface (GUI) tools to monitor and analyze your Lightning node. Popular options include:

• Ride-the-Lightning: A comprehensive management tool.
• Umbrel: A complete node operating system.
• bolt.observer: An analytics platform.
• LN Node Insights: Specialized node insights.
• Munin: A monitoring tool (available via https://github.com/lduchosal/munin-clightning).

Core Lightning is a modular system that allows you to extend its functionality using plugins. Plugins operate as subprocesses started by the lightningd daemon. They can interact with the daemon through several mechanisms:

• Command line option passthrough: Register custom command line options that are exposed through lightningd.
• JSON-RPC command passthrough: Add custom commands to the JSON-RPC interface.
• Event stream subscriptions: Receive push-based notifications about events occurring within lightningd.
• Hooks: Intercept internal lightningd events to alter or inject custom behaviors.
• Dynamic REST paths: Register RPC commands with custom REST paths for use with clnrest.

Core Lightning exposes a JSON-RPC 2.0 interface over a Unix Domain socket. You can interact with it using:

• lightning-cli: The standard command-line tool.
• pyln-client: A Python client library located in contrib/pyln-client.

Use lightning-cli help to list available RPC methods, or lightning-cli help <command> for specific command details.

Core Lightning (CLN) uses abstract schemas to generate its various interfaces. This ensures consistency across different communication protocols:

• Peer-to-peer (P2P) Wire Format: Generated from LN specification CSV files using generate-wire.py. This produces C source code for encoding, decoding, and printing messages.
• Inter-daemon Communication: Uses a modified LN spec format (supporting FD passing and u32 length prefixes) generated via generate-wire.py for communication between CLN daemons.
• JSON-RPC: Defined using JSON Schema in the doc/schemas directory. Each method has a corresponding lightning-*.json file for requests and responses.
• Man pages: Generated from JSON schemas using the fromschema.py tool.

Depending on your application's architecture and deployment, you can connect to a Core Lightning (CLN) node using several different interfaces:

• JSON-RPC commands: Best for applications running on the same system as the CLN node.
• REST APIs: Best for remote clients connecting over a secure network.
• gRPC APIs: Best for remote clients requiring high-performance communication over a secure network.
• Commando Plugin: Connects over the Lightning Network to issue commands.
• WSS Proxy: Connects via a Web Secure Socket proxy.
• Third-party libraries: Options include JSON over HTTPS or GraphQL (note: GraphQL is deprecated).