Skip to content

feat: add economically optimized Loop Out CLI tool with real route probing and SOT accounting - #52

Merged
TrezorHannes merged 5 commits into
mainfrom
feat/loop-out-economic-cli
Sep 20, 2026
Merged

TrezorHannes merged 5 commits into
mainfrom
feat/loop-out-economic-cli

Conversation

@TrezorHannes

Copy link
Copy Markdown
Owner

Summary of Changes

  1. Economic Loop Out CLI Optimizer (Other/swap_out-loop.py):

    • Discovers channel candidates with high local liquidity and low outbound fees via LNDg API.
    • Dynamic per-channel equilibrium sizing (targeting 50% balance) or explicit --amt <sats>.
    • Two-stage route validation:
      • Stage 1: lncli queryroutes Dijkstra pathfinding to Loop node (021c97a9...).
      • Stage 2: Mandatory live prepay probe with random 32-byte fake hashes via lncli sendpayment to detect ghost liquidity and verify real downstream routing paths.
      • Direct 2-Hop Probing Fallback: Checks if peer maintains a direct channel to Loop, building route via lncli buildroute and probing via lncli sendtoroute to accurately determine real routing fees.
    • Comprehensive total economic cost calculation:
      29383\text{Total Cost} = \text{Loop Service Fee} + \text{On-chain Sweep Fee} + \text{LN Routing Fee} + \text{Opportunity Cost (PPM)}29383
    • Ranking candidates by lowest Net Effective PPM.
    • Interactive terminal menu navigation (↑/↓/Enter/q) using native termios/tty, with clean PrettyTable fallback for non-TTY pipelines and --auto-approve.
    • Concurrent worker probing via --workers <N> (using ThreadPoolExecutor with thread-safe output) while preserving 15s probe timeout.
    • Economical on-chain sweeping: enforces minimum 6-block confirmation target (default 9) and omits --fast for fee-saving swap batching.
  2. Native Source of Truth (SOT) Accounting via Loop's loop.db:

    • Directly connects in read-only mode to Loop daemon's SQLite database (~/.loop/mainnet/loop_sqlite.db), eliminating redundant custom databases and state divergence.
    • Configurable via loop_db_path in config.ini, with seamless RPC fallback to litloop listswaps.
    • Automatically tags initiated swaps with --label "Loop-Out: <alias> (<chan_id>)" to preserve channel metadata natively in loop.db.
    • Historical querying CLI: python Other/swap_out-loop.py --history [--limit N] displaying actual settled costs and realized PPM.
    • On-demand CSV export: --history --csv [path].
  3. Documentation & Config:

    • Comprehensive documentation in Other/swap_out-loop.md.
    • Documented [loop] section in config.ini.example and live Debian NUC config.ini.
    • Updated README.md tool index.
  4. Testing & Live Verification:

    • 17 unit tests in tests/Other/test_swap_out_loop.py covering candidate filtering, dynamic sizing, quote parsing, economic scoring, route probing, direct route fallback, SOT SQLite querying, and CSV export.
    • Entire test suite passing: 91/91 tests pass.
    • Verified live on debian-nuc.lan with live --dry-run, --workers 2, --history, and real on-chain execution.

Verification

  • Automated Tests: pytest passed 91/91 tests in 15.6s.
  • Debian NUC Live Testing: Verified live on debian-nuc.lan with dry-run, workers, history, and real swap execution.

…ounting

- Refactor Other/swap_out-loop.py to identify high-local-liquidity, low-fee channels via LNDg API.
- Implement hybrid sizing: explicit --amt or dynamic per-channel equilibrium sizing.
- Add two-stage route validation: lncli queryroutes fee calculation followed by live prepay probing via lncli sendpayment with fake hashes.
- Calculate full economic cost: Loop service fee, on-chain sweep fee, LN routing fee, and local opportunity cost (foregone PPM).
- Provide interactive arrow-key terminal menu navigation (termios/tty) with graceful non-interactive fallback.
- Enforce economical sweep settings with minimum 6-block conf_target (default 9) and batched publication.
- Stream litloop monitor in foreground with instructions for safe background detachment.
- Persist operations in SQLite database (data/loop_out_history.db) with auto-synced CSV export.
- Add comprehensive documentation in Other/swap_out-loop.md.
- Add test suite in tests/Other/test_swap_out_loop.py (11 tests, 81/81 total passing).
@TrezorHannes TrezorHannes added documentation Improvements or additions to documentation enhancement New feature or request python Pull requests that update python code labels Sep 20, 2026
@TrezorHannes TrezorHannes self-assigned this Sep 20, 2026
@TrezorHannes
TrezorHannes merged commit 946c740 into main Sep 20, 2026
7 checks passed
@TrezorHannes
TrezorHannes deleted the feat/loop-out-economic-cli branch September 20, 2026 15:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation enhancement New feature or request python Pull requests that update python code

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant