Hello Nervos Community,
While contributing to the Fiber core repository recently on diagnostic clarity for funding failures), our team at ILE Labs has been researching node operational ergonomics, specifically regarding channel liquidity balance and routing efficiency.
We wanted to share our findings, our adversarial threat model, and an early open-source prototype to get feedback from active node operators and maintainers.
The Problem: One-Sided Channel Depletion
Payment channels are fixed-capacity pipes. In practice, routing payments cause channel balances to skew over time:
- Outbound-heavy channels hold nearly all funds locally and cannot receive incoming payments.
- Inbound-heavy channels have their local balance drained and cannot route outgoing payments, returning:
"max outbound liquidity {max} is insufficient, required amount: {amount}"(fromcrates/fiber-lib/src/fiber/graph.rs).
The Fiber core team acknowledged this challenge in docs/channel-rebalancing.md, noting the limitations of manual intervention:
- Blind routing (
send_paymentwithallow_self_payment): The operator cannot choose which specific channels are drained or refilled. - Manual routing (
build_router+send_payment_with_router): Operators must manually inspect gossip topology, hand-calculate intermediate hops across raw JSON, verify fees, and dispatch manual RPCs.
In networks like Bitcoin Lightning, automated circular rebalancing tools (rebalance-lnd, lndmanage, balance-of-satoshis) are among the most essential operator utilities.
Adversarial Threat Model: Why Naive Rebalancing Fails
Before writing any automation code, we conducted an adversarial security and economic threat model on circular rebalancing in Fiber. We identified 5 critical failure modes that any production tool must mitigate:
-
Capital Jamming via 4-Hour TLC Deltas: In Fiber,
DEFAULT_TLC_EXPIRY_DELTA = 4 hours. If a node rebalances across 3 hops and an intermediate node stalls or deliberately holds the TLC, the operator’s funds are frozen in both channels for up to 8–12 hours.
Mitigation: Boundingtlc_expiry_limitto \le 15 minutes and dispatching payments in micro-chunks (\le 15\% of channel capacity). -
The Negative Fee Arbitrage Trap (Economic Bleed): If an operator pays 400 PPM in routing fees across intermediate hops to rebalance a channel whose outgoing fee policy is only 100 PPM, the operator loses 300 PPM on every turnover.
Mitigation: Enforcing an economic invariant:\text{Rebalance Fee (PPM)} \le 0.50 \times \text{Channel Forwarding Fee Rate (PPM)}Any route exceeding 50% of projected channel revenue is rejected.
-
Topology Sparsity (No Cycles): Circular rebalancing requires a directed simple cycle in the gossip graph. If the network topology resembles a tree or star graph, no circular route exists.
Mitigation: Fast-fail cycle pre-flight check without spamming speculative RPCs. Circular rebalancing is strictly complementary to the core team’s on-chain Loop In/Out (liquidity-management-m0), which handles star topologies. -
TLC Slot Exhaustion & Customer DoS: Flooding a channel with rebalancing TLCs risks hitting
MAX_TLC_NUMBER_IN_FLIGHT, causing organic customer payments and cross-chain swaps (CCH) to fail.
Mitigation: Concurrency is locked to strictly 1 active rebalance TLC per channel, with an automatic pause if channel slot utilization exceeds 70%. -
Surveillance Probing: Repeated network probing leaks channel balances to intermediate nodes.
Mitigation: Localdry_run: truepre-flight verification before any network broadcast.
Empirical Test & Working Prototype
We verified Fiber’s internal circular payment mechanism on our local test nodes (test_send_payment_for_pay_self_with_invoice), which executes and settles in 4.63s.
We then built a prototype CLI tool (rebalance.py) with a self-contained test harness verifying all threat model invariants:
=================================================================
RUNNING `fiber-rebalance` THREAT MODEL & INVARIANT TEST SUITE
=================================================================
Test 1 (Timelock Safe): PASSED: Timelock within anti-jamming budget.
Test 2 (Timelock Excess Rejection): Correctly blocked 4h delta.
Test 3 (Economic Arbitrage Positive): PASSED: Rebalance is profitable (100 PPM <= 250 PPM ceiling).
Test 4 (Negative Fee Bleed Rejection): Correctly blocked unprofitable route.
Test 5 (Slots Available): PASSED: Channel concurrency slots clear.
Test 6 (Duplicate TLC Concurrency Blocked): Correctly blocked concurrent rebalance.
Test 7 (Commercial Slot Buffer Preservation): Correctly blocked rebalance to protect customer traffic.
RESULTS: All 7/7 Security & Economic Invariant Tests PASSED!
=================================================================
The prototype repository below:
Repository: github.com/ILE-Labs/fiber-rebalance
Questions & Feedback from Node Operators.
We are sharing this research and our working PoC repository to open a discussion with the Fiber developer community:
- For Node Operators: When running Fiber nodes, how often do you observe one-sided channel depletion? Have you attempted manual circular rebalancing via
build_router? - For Core Maintainers: Are there plans to expose additional liquidity routing hints or graph cycle queries in future RPC milestones?
- Economic Parameters: What margin discount (e.g. 50% vs 75%) and chunk sizing do operators feel is optimal for automated liquidity maintenance?