Circuit Breaker (Lightning)

What Is a Circuit Breaker?

A circuit breaker in the Lightning Network context is software that acts as a firewall for a routing node, intercepting incoming HTLCs and enforcing rate limits before they are forwarded. Just as an electrical circuit breaker trips to prevent overload, a Lightning circuit breaker rejects or queues excess HTLCs to protect the node's channel capacity from being exhausted by malicious or excessive traffic.

The concept was introduced by Joost Jager, a former Lightning Labs engineer, through the open-source circuitbreaker project. It connects to LND via gRPC and uses the HTLC interceptor API to inspect and control every forwarded payment before it reaches the outgoing channel.

Without a circuit breaker, the Lightning protocol allows up to 483 concurrent HTLCs per channel direction. A single malicious peer can consume all of these slots at near-zero cost, blocking legitimate payments from routing through the node. Circuit breakers cap this exposure by enforcing configurable limits per peer.

How It Works

A circuit breaker sits between a node's incoming and outgoing HTLC processing. When a peer forwards an HTLC, the circuit breaker evaluates it against the configured limits before deciding whether to pass it through, reject it, or queue it for later processing.

1. An incoming HTLC arrives from a connected peer requesting the node to forward a payment
2. The circuit breaker intercepts the HTLC via the node's interceptor API before it is committed to the outgoing channel
3. It checks the current count of pending HTLCs for that peer against the configured maximum
4. It checks whether the rate limit (minimum interval between forwards) allows another HTLC
5. Based on the operating mode, the HTLC is either forwarded, failed back, or placed in a queue

Operating Modes

Circuit breakers support three distinct modes, each offering a different balance between protection and routing availability:

The fail mode is the safest default: it prevents liquidity from being locked on the incoming side but may cause the node to appear unreliable to pathfinding algorithms. The queue modes are more aggressive, holding misbehaving peers' HTLCs hostage to create back-pressure, but carry the risk of triggering a force-close if HTLCs are held past their timeout. LND v0.16 and above includes auto-fail protection that mitigates this risk.

Configurable Parameters

Operators tune their circuit breaker through a web-based dashboard (by default at http://127.0.0.1:9235). The primary parameters include:

• Maximum pending HTLCs: a per-peer cap on the number of concurrent in-flight HTLCs the node will forward. Trusted peers with high legitimate traffic can be assigned higher limits, while unknown peers might be restricted to just a few
• Rate limiting: implemented using a token bucket algorithm, this sets a minimum interval between forwarded HTLCs. It protects against spam attacks that cycle through many fast-resolving HTLCs, which the pending-count limit alone would not catch
• Per-peer overrides: both the operating mode and numerical limits can be customized for individual peers, allowing differentiated treatment based on trust and traffic history
• Global defaults: a fallback configuration that applies to all peers without specific overrides

Example Configuration

The circuitbreaker tool connects to an LND node and provides both a CLI and web interface for management. A typical setup:

# Install circuitbreaker
go install github.com/lightningequipment/circuitbreaker@latest

# Run with default LND connection
circuitbreaker

# Run with custom LND settings
circuitbreaker \
  --rpcserver=localhost:10009 \
  --tlscertpath=~/.lnd/tls.cert \
  --macaroonpath=~/.lnd/data/chain/bitcoin/mainnet/admin.macaroon

# The web UI is accessible at http://127.0.0.1:9235
# Configuration is stored in ~/.circuitbreaker/circuitbreaker.db

From the web UI, operators can view per-peer statistics (settled, failed, and rejected HTLC counts on hourly and daily intervals), set limits for individual peers, and choose the operating mode. Configuration changes take effect immediately without restarting the node.

The Problem: Channel Jamming

Circuit breakers exist because of a fundamental vulnerability in Lightning's design: channel jamming. Because forwarding HTLCs costs nothing until they settle, an attacker can lock up a node's entire routing capacity without paying fees. This attack comes in two forms:

• Slot jamming: the attacker sends many small HTLCs (up to 483 per channel) and delays their resolution. With just two channels to the target, they can occupy all available HTLC slots, blocking every legitimate payment
• Amount jamming: the attacker routes a large payment through the target and delays settlement, locking up the channel's balance. A single HTLC can consume nearly all of a channel's capacity

Both attacks are cheap: the attacker ties up their own liquidity for the duration but pays no routing fees since the HTLCs never complete. The damage is asymmetric because a single attacker can jam capacity across every hop in a 20-hop route, amplifying the effect by up to 20x their own locked funds.

A circuit breaker directly counters slot jamming by capping the number of pending HTLCs per peer. If the attacker is limited to 10 pending HTLCs instead of 483, they need to open roughly 48x more channels (at real on-chain cost) to achieve the same jamming effect. Rate limiting adds a second layer of defense against rapid-fire spam patterns.

Use Cases

Protecting Routing Nodes

High-volume routing nodes are the primary users of circuit breakers. These nodes earn routing fees by forwarding payments, making them attractive targets for jamming. A jammed routing node loses fee income and degrades the network for all users. Circuit breakers let operators protect their capital while continuing to serve legitimate traffic.

Defending Against Competitive Attacks

In a competitive routing market, a malicious node operator could jam a rival's channels to divert traffic toward their own routes. Circuit breakers make this attack significantly more expensive by limiting the attacker's leverage on each channel.

Traffic Shaping

Beyond security, circuit breakers let operators shape their forwarding traffic. A node operator might set lower limits on peers with poor payment-completion rates and higher limits on peers that consistently forward successful payments, optimizing for overall routing revenue and reliability.

Lightning Service Providers

LSPs that manage channels on behalf of many users face heightened jamming risk because of their central role in payment routing. Circuit breakers provide a practical, immediately deployable defense layer while longer-term protocol solutions are still being developed.

Protection vs. Revenue Tradeoff

The core tension in running a circuit breaker is that any limit strict enough to stop an attacker will also affect some legitimate traffic. This tradeoff manifests differently depending on the operating mode:

• In fail mode, rejected HTLCs cause payment failures. Pathfinding algorithms in sender wallets may deprioritize nodes that frequently fail forwards, reducing future routing volume even after the attack ends
• In queue mode, delayed HTLCs may time out before they can be forwarded, causing the same payment failures from the sender's perspective but with the added risk of force-closures if hold times are excessive
• Strict per-peer limits on a high-traffic peer with occasional spikes will drop legitimate payments during peak periods

Operators mitigate this by using the monitoring dashboard to tune limits based on observed traffic patterns. The hourly and daily HTLC counters help identify which peers send legitimate traffic versus suspicious patterns, allowing targeted adjustments over time.

Broader Jamming Mitigation Landscape

Circuit breakers are a local, unilateral defense: they require no cooperation from other nodes and no protocol changes. They sit within a broader ecosystem of proposed solutions to channel jamming, several of which are progressing toward deployment:

HTLC Endorsement and Reputation

The most advanced protocol-level proposal is HTLC endorsement (evolving into "accountable signals" under bLIP-4). In this system, nodes track per-peer payment behavior and flag HTLCs from well-behaved, profitable peers as "endorsed." Endorsed HTLCs get preferential access to channel slots and liquidity, while unendorsed HTLCs are restricted to a smaller resource pool. Research by Carla Kirk-Cohen and Clara Shikhelman at Chaincode Labs has shown through simulations that this approach can handle 10x current network traffic without increasing payment failures. Experimental support has been added to LND, Eclair, and LDK.

Upfront Fees

Proposed in the "Unjamming Lightning" paper (Chaincode Labs Research, November 2022), unconditional fees would charge a small amount on all payment attempts, whether they succeed or fail. This makes rapid-fire jamming economically costly. Simulations suggested a modest 2% fee increase would fully compensate routing nodes for the disruption.

How Circuit Breakers Fit In

Circuit breakers complement these protocol-level proposals rather than competing with them. A node running a circuit breaker today gains immediate protection. As HTLC endorsement and upfront fees are deployed across implementations, circuit breakers can be relaxed or retired. For a deeper analysis of routing infrastructure, see the Lightning Network routing deep dive.

Limitations and Risks

LND-Only Availability

The circuitbreaker tool is currently LND-specific, relying on LND's HTLC interceptor API. Node operators running Core Lightning or Eclair do not have an equivalent standalone tool, though both implementations are adding protocol-level jamming mitigations directly.

Alpha-Quality Software

The circuitbreaker project explicitly warns that it is alpha-quality software. Running it on mainnet nodes with significant capital requires careful monitoring and conservative initial settings. Bugs in the HTLC interceptor path could cause forwarding failures or, in extreme cases, stuck channels.

Incomplete Protection Against Amount Jamming

While circuit breakers effectively counter slot jamming (limiting HTLC count), they offer less protection against amount jamming. A single large HTLC within the per-peer limit can still lock up most of a channel's balance. Addressing amount jamming requires protocol-level solutions like upfront fees that make holding large HTLCs costly.

False Positives

Legitimate payment spikes (such as a merchant receiving a burst of orders) can trigger circuit breaker limits, causing real payments to fail. Operators must balance security against the risk of degrading service for honest users, especially on channels with variable traffic patterns.

No Network-Wide Coordination

Circuit breakers protect only the node running them. An attacker can still jam downstream hops that lack protection. True network-wide resilience requires protocol-level solutions adopted by a critical mass of nodes, which is why the Lightning development community continues pursuing HTLC endorsement and fee-based mitigations alongside local tools like circuit breakers. For more on Lightning Network scaling challenges, see the Lightning Network scalability limits analysis.

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.