Skip to content

Add swap quote and swap resume CLI commands#13

Merged
LandynDev merged 1 commit intoentrius:testfrom
eureka0928:feat/swap-quote-resume
Apr 8, 2026
Merged

Add swap quote and swap resume CLI commands#13
LandynDev merged 1 commit intoentrius:testfrom
eureka0928:feat/swap-quote-resume

Conversation

@eureka0928
Copy link
Copy Markdown
Contributor

Closes #12

Summary

Two new CLI commands under alw swap to improve user experience:

  • alw swap quote — Preview rates and estimated receive amounts before committing to a swap. Shows all available miners with calculated receive amounts after fees for a given input amount.
  • alw swap resume — Recover an interrupted swap flow. Reads saved pending state and handles all failure scenarios: expired reservations, offline miners, already-on-chain swaps.

What Changed

  • allways/cli/swap_commands/quote.py — New command (~130 lines)
  • allways/cli/swap_commands/resume.py — New command (~330 lines)
  • allways/cli/swap_commands/__init__.py — Register both commands under alw swap
  • .gitignore — Add .venv/

Design

Both commands follow the existing CLI patterns and reuse existing infrastructure:

Quote uses read_miner_commitments() + calculate_dest_amount() + apply_fee_deduction() — purely read-only, no wallet needed.

Resume follows the same two philosophies as alw swap now:

  1. Wizard mode — walks user through recovery step by step, auto re-reserves if expired, finds alternative miners if original went offline
  2. Agent mode — fully scriptable via --source-tx-hash and --yes flags

Resume handles these recovery paths:

Scenario Behavior
Swap already on-chain Skip to watch mode
Reservation still active Proceed to tx submission
Reservation expired, miner available Auto re-reserve same miner
Reservation expired, miner unavailable Find alternative at same-or-better rate
No pending swap Clear message, suggest alw swap now

Usage

# Quote
alw swap quote --from btc --to tao --amount 0.1
alw swap quote --from tao --to btc --amount 50

# Resume (interactive)
alw swap resume

# Resume (non-interactive / agent)
alw swap resume --source-tx-hash abc123... --yes

Test Plan

  • alw swap quote --from btc --to tao --amount 0.1 shows rates table with receive amounts
  • alw swap quote with invalid chain shows error
  • alw swap resume with no pending swap shows clear message
  • alw swap resume with active reservation proceeds to tx prompt
  • alw swap resume --source-tx-hash <hash> --yes works non-interactively
  • Existing tests pass (pytest tests/test_rate.py tests/test_chains.py)
  • ruff check and ruff format pass

@eureka0928 eureka0928 force-pushed the feat/swap-quote-resume branch from 78e91f9 to cac207a Compare April 7, 2026 02:17
@eureka0928
Copy link
Copy Markdown
Contributor Author

Hi @LandynDev would you review this PR?
Thank you for your time

@eureka0928 eureka0928 force-pushed the feat/swap-quote-resume branch 3 times, most recently from 4af01df to 4583f1c Compare April 7, 2026 22:46
Copy link
Copy Markdown
Collaborator

@LandynDev LandynDev left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A few things we'd want to tighten up before merging

Resume: on-chain swap scan performance

get_miner_active_swaps() calls get_active_swaps() which iterates through all swap IDs. On mainnet with lots of historical swaps this could be really slow for what should be a quick recovery command.

We might wanna add a more targeted lookup — we already know the miner_hotkey from pending state, so we could:

  • Cap the scan window, or
  • Check get_miner_has_active_swap first and only do the full scan if that returns true (this is probably better bc if the miner doesn't have an active/pending swap then there's nothing to resume)

Resume: expired reservation = nothing to resume

Like the above comment, if the reservation expired and the user already sent funds, there's not really a resumable state — the miner could have been taken by someone else, rate could have changed, etc.

We should make it clear in this case that there's nothing to resume and guide them to start fresh with:

alw swap now

Right now it silently tries to re-reserve which could lead to confusing outcomes.
If the reservation expired, there's nothing to resume - they should do alw swap now


Resume: validator discovery ordering

Right now validators are discovered after the user enters their tx hash.
If no validators are found, they've already committed info but hit a dead end.
In swap now, validator discovery happens during reservation so failures surface before the user takes any irreversible action.

We'd want to match that pattern here — discover validators before prompting for the tx hash.


Resume: empty dest_address on re-reservation

When building the MinerPair for re-reservation (line 178), dest_address is set to ''.

It works today since broadcast_reserve_with_retry doesn't use it, but it's a footgun if anything downstream ever reads it.

We might wanna just pass the actual dest_address through.


Overall solid contribution — the swap now command is the reference point for how these should feel, both for interactive users and agents.

Once these are addressed this should be good to go.

@eureka0928 eureka0928 force-pushed the feat/swap-quote-resume branch from 4583f1c to 3221737 Compare April 8, 2026 00:13
Copy link
Copy Markdown
Contributor Author

@eureka0928 eureka0928 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All four items addressed:

1. On-chain scan performance — Now gates with get_miner_has_active_swap() (cheap bool) before doing the full get_miner_active_swaps() scan.

2. Expired reservation = nothing to resume — Removed the re-reserve logic entirely. If the reservation expired, we clear the pending state and direct them to alw swap now. Much cleaner — no confusing silent re-reservation.

3. Validator discovery ordering — Moved discover_validators() before the tx hash prompt. If no validators are found, we fail before the user enters anything irreversible.

4. Empty dest_address — Removed the MinerPair reconstruction entirely since re-reservation is no longer part of resume. The dest_address='' footgun is gone.

The command is now much simpler: show summary → check if already on-chain → verify reservation is active → discover validators → prompt for tx hash → confirm. ~200 lines down from ~330.

@eureka0928 eureka0928 requested a review from LandynDev April 8, 2026 00:16
@eureka0928
Copy link
Copy Markdown
Contributor Author

@LandynDev would you take another look on this? I addressed all
Thank you

@LandynDev LandynDev merged commit eaa7c25 into entrius:test Apr 8, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add swap quote and swap resume CLI commands

2 participants