Design: Fiber liquidity management milestones

This was generated by AI during triage.

Summary

Track the approved milestone design for adding lnd Loop-inspired liquidity management to Fiber.

Product Direction

Fiber should support Loop In and Loop Out style liquidity movement between Fiber channels and CKB on-chain assets.

Key decisions:

• Support CKB and whitelisted UDT assets from the first version.
• Use an asset registry / whitelist instead of arbitrary user-supplied UDT type scripts.
• Add an independent liquidity module rather than merging this into cch.
• Support dual-role FNN nodes: client capability always available, provider mode optional and disabled by default.
• Do not change Fiber p2p messages in the first product milestones.
• Use RPC for swap negotiation, while Fiber p2p continues to carry normal payments/TLCs.
• Defer provider discovery, quote gossip, and liquidity-specific p2p messages until a later market-mode milestone.

Proposed Milestones

M0: Protocol And Product Spec

Define Loop In / Loop Out semantics, dual-role model, CKB + UDT whitelist asset model, quote schema, swap order state machine, fee model, timeout/refund/recovery rules, and initial RPC draft.

M1: Asset Registry And On-Chain Swap Primitive

Implement Asset::Ckb / Asset::Udt, provider whitelist configuration, per-asset limits, CKB + UDT swap cell support, claim/refund transaction builders, and chain-level tests.

M2: Swap Store And Recovery Framework

Persist swap orders and state transitions, validate transitions, recover non-terminal orders on startup, and expose swap history queries.

M3: Manual Loop Out

Ship the first end-to-end product: Fiber channel balance to on-chain CKB/UDT, with quote/execution RPCs, payment integration, payout integration, and recovery handling.

M4: Manual Loop In

Implement on-chain CKB/UDT to Fiber channel balance, including lock watching, provider Fiber payment, claim/refund, and restart-safe recovery.

M5: Integrated Provider Mode

Add optional provider mode with per-asset capacity, quote/fee policy, concurrent order limits, risk budgets, order recovery, and metrics.

M6: Client-Side Liquidity Planner

Add dry-run recommendations based on channel liquidity, rebalance-first planning, Loop In/Out cost estimation, and human-readable decision reasons.

M7: Automated Liquidity Management

Add policy-driven execution with channel target ratios, max fee budgets, cooldowns, spend limits, automatic rebalance/Loop In/Loop Out, and audit logs.

M8: Productization

Add CLI support, RPC docs, Biscuit auth rules, swap history, fee breakdowns, operator metrics, and clear errors.

M9: Multi-Provider Network Mode

Explore provider discovery, quote comparison, reputation, capacity advertisement, anti-spam, privacy review, and possible p2p/gossip extensions.

Recommended First Phase

Implement M0 -> M1 -> M2 -> M3 first. Manual Loop Out should validate the shared asset model, on-chain primitive, Fiber payment integration, provider flow, and restart recovery before Loop In and automation are added.

M0 Decisions Still Required

• Exact CKB and UDT swap cell script design.
• Exact preimage ownership and reveal sequence for Loop In and Loop Out.
• Confirmation policy by asset/network.
• Whether quote negotiation uses existing JSON-RPC only or also an HTTP API.
• How much CCH tracker/state-machine code should be reused.
• Storage key layout and migration requirements.