Core Lightning (CLN)

What Is Core Lightning?

Core Lightning (CLN) is one of the major implementations of the Lightning Network protocol, alongside LND (Lightning Labs) and Eclair (ACINQ). It enables fast, low-cost Bitcoin payments by operating Lightning channels between nodes, routing payments across a network of these channels without requiring on-chain transactions for every transfer.

CLN's defining characteristic is its modular design philosophy, inspired by the UNIX principle of doing one thing well. The core daemon (lightningd) handles the Lightning protocol, channel management, and peer connections, while everything else: from automatic channel management to REST APIs to advanced routing: is handled by plugins. This approach keeps the core lightweight and auditable while allowing operators to customize their node with only the features they need.

Blockstream originally released the project in August 2015 as c-lightning, making it the first Lightning Network implementation. Rusty Russell, a former Linux kernel developer known for creating iptables, led development from the start. The project entered production on Bitcoin mainnet in early 2018 when the Blockstream Store launched as one of the first real-world Lightning merchants.

How It Works

CLN uses a multi-process architecture where the master daemon orchestrates specialized subdaemons, each responsible for a specific function. This process isolation provides defense-in-depth security: a vulnerability in one subdaemon does not automatically compromise the entire system.

Subdaemon Architecture

When lightningd starts, it spawns several subdaemons that handle distinct responsibilities:

• hsmd: manages all cryptographic secrets and performs commitment signing, completely isolated from network-facing code
• gossipd: maintains the network routing graph and broadcasts gossip messages to peers
• connectd: handles peer connections and incoming connection requests
• channeld: operates a single channel during normal operation, handling HTLC forwarding and state updates
• openingd: manages the channel opening negotiation for a single peer
• closingd: handles mutual close negotiation when both parties cooperate
• onchaind: monitors and resolves channels whose funding transaction has been spent on-chain

The master daemon passes peer file descriptors to the appropriate subdaemon rather than proxying data. Each channel gets its own channeld process, so a crash in one channel does not affect others. For a deeper look at how Lightning implementations compare, see the node implementation comparison.

The Plugin System

Plugins are standalone processes that communicate with lightningd via JSON-RPC over stdin/stdout. When CLN starts, it initializes each plugin through a two-step handshake:

1. CLN sends a getmanifest request, and the plugin responds with its capabilities: custom RPC methods, event subscriptions, hooks, CLI options, and feature bits
2. CLN sends an init message containing configuration values, signaling that the node is ready

Because the interface is language-agnostic (just JSON over stdio), plugins can be written in any programming language. Official libraries exist for the most common choices:

# Python: pyln-client provides a plugin framework
from pyln.client import Plugin

plugin = Plugin()

@plugin.method("mymethod")
def my_custom_rpc(plugin, name):
    return {"greeting": f"Hello {name} from CLN!"}

plugin.run()

# Rust: cln-plugin provides async/await support
# Go: glightning community bindings
# JavaScript/TypeScript: community frameworks available

Plugins can be either static (loaded at startup via --plugin=) or dynamic (started and stopped at runtime through the plugin RPC command). This means operators can add or remove functionality without restarting their node.

APIs and Remote Access

CLN exposes three API layers, each built on the one below it:

• JSON-RPC over Unix socket: the primary interface used by all other APIs and the lightning-cli command-line tool
• gRPC (via cln-grpc): auto-generated from the JSON-RPC schema, secured with mutual TLS authentication, efficient binary encoding via protobuf
• REST (via CLNRest): transforms RPC calls into HTTP endpoints with JSON responses, includes a WebSocket server for real-time notifications

The built-in Commando plugin enables remote RPC access over Lightning's own encrypted peer connections, eliminating the need for separate networking. Authentication uses runes: base64-encoded permission tokens with fine-grained restrictions on which methods can be called, how often, and for how long.

Notable Plugins

The CLN ecosystem includes dozens of community-maintained plugins. A few stand out for the functionality they provide:

CLBOSS: Automated Node Management

CLBOSS is an autopilot plugin that automates most of the operational decisions involved in running a Lightning node:

• Opens channels to well-connected nodes based on network topology analysis
• Acquires inbound liquidity via on-chain to off-chain swaps during low-fee periods
• Rebalances channels automatically, including just-in-time rebalancing on forwards
• Adjusts routing fees dynamically based on channel balance and forwarding performance
• Monitors on-chain funds and moves them into channels when fees are low

For operators who want hands-off node management, CLBOSS handles the tasks described in the Lightning channel management guide. Individual channels can be excluded from automation using the clboss-unmanage command.

Other Key Plugins

• Summary: displays an at-a-glance node overview including on-chain balance, fiat equivalent, peer count, and ASCII channel balance graphs
• Rebalance and Sling: move liquidity between channels to maintain healthy channel capacity distribution
• Feeadjuster: sets dynamic fee structures to keep channels balanced
• Hold: enables hodl invoices for conditional payment flows
• Reckless: a plugin manager that installs and uninstalls plugins with a single command

Key Features

BOLT12 Offers

CLN was the first major implementation to support BOLT12 offers natively. As of late 2024, BOLT12 send and receive are enabled by default on all CLN nodes. Offers provide reusable payment requests, payer-initiated payments, and refund flows without requiring a web server: a significant upgrade over traditional BOLT11 invoices.

Splicing

Splicing allows adding or removing funds from an existing channel without closing it. CLN moved splicing out of experimental status in its April 2025 release (v26.04), supporting splice-in, splice-out, and cross-splicing between channels. This feature is interoperable with Eclair. For technical details, see the splicing deep dive.

HSM Key Management

The hsmd subdaemon provides hardware-security-module-style key isolation. All signing operations happen in this dedicated process, separated from network-facing code. As of late 2024, new CLN nodes generate a BIP-39 12-word mnemonic phrase as their root secret, replacing the previous binary format. CLN also supports remote signing via external hardware, where the hsmd process delegates to a signing proxy.

xpay Payment Engine

Introduced in late 2024, xpay is CLN's next-generation payment engine. It uses a minimum-cost-flow solver to compute optimal multi-path payment routes, learns from previous payment attempts to improve future routing decisions, and supports both BOLT11 and BOLT12 invoices. xpay can also pay BIP-353 human-readable addresses (for example, user@domain.com style Lightning addresses).

Use Cases

CLN's modular architecture makes it well-suited for specific deployment scenarios:

• Resource-constrained environments: CLN runs comfortably on ~512 MB of RAM, making it a natural fit for Raspberry Pi and other single-board computers. LND typically requires 2 GB or more for comparable channel counts.
• Custom Lightning applications: the plugin system allows developers to add business logic directly to the node without forking the codebase. Payment processing, automated channel management, and custom routing policies all run as plugins.
• Lightning service providers: operators running infrastructure for others benefit from CLN's process isolation, gRPC API, and Commando-based remote access. See the Lightning service provider guide for how providers build on implementations like CLN.
• Specification development and testing: as a reference implementation, CLN is often the first to implement new BOLT features, making it a testing ground for protocol researchers.

CLN vs. LND

The two most widely deployed Lightning implementations take fundamentally different design approaches:

Neither approach is universally better. LND's integrated feature set means less configuration for common use cases, while CLN's modularity provides more flexibility for operators with specific requirements. Both implement the same BOLT protocol and interoperate on the same Lightning Network.

Risks and Considerations

Smaller Ecosystem

LND has a larger share of the Lightning Network by node count, which means more third-party tooling, wallet integrations, and community support are built for LND first. CLN operators may encounter fewer ready-made solutions and need to rely more on the plugin ecosystem or custom development.

Plugin Dependency

CLN's strength is also a potential risk: critical functionality lives in plugins that may be maintained by individual developers rather than the core team. If a key plugin like CLBOSS loses its maintainer, operators relying on it must find alternatives or maintain forks. Community plugins vary in quality and update frequency.

C Language Considerations

Writing in C delivers performance and low resource usage, but C programs are more susceptible to memory safety issues (buffer overflows, use-after-free) than memory-safe alternatives. The CLN team mitigates this with extensive testing and the subdaemon isolation model, but it remains an inherent tradeoff of the language choice.

Operational Complexity

The modular design means operators must understand which plugins to install and configure for their use case. A new operator running CLN without plugins like CLBOSS may find the out-of-the-box experience more hands-on than LND's integrated defaults. Tools like Reckless (the plugin manager) help, but the learning curve is steeper for non-technical users.

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.