Skip to content

Add local swap history with SQLite persistence#22

Open
eureka0928 wants to merge 1 commit intoentrius:testfrom
eureka0928:feat/swap-history
Open

Add local swap history with SQLite persistence#22
eureka0928 wants to merge 1 commit intoentrius:testfrom
eureka0928:feat/swap-history

Conversation

@eureka0928
Copy link
Copy Markdown
Contributor

Summary

When a swap completes or times out, the smart contract deletes it from on-chain storage. Running alw view swap 42 after resolution returns:

Swap 42 has been resolved (completed or timed out).
Resolved swaps are removed from on-chain storage.

No record of what was swapped, the rate applied, amounts, tx hashes, or when it happened. This PR adds local swap history so completed swaps are never lost.

What Changed

  • allways/cli/swap_commands/history.py (new) — SQLite persistence layer (~/.allways/swap_history.db). Stores all swap fields at terminal state. WAL mode, INSERT OR REPLACE for safe dedup.
  • allways/cli/swap_commands/view.py — Three additions:
    • alw view swap <id> auto-falls back to local history when swap is resolved on-chain
    • alw view history command with --swap, --status, --limit, --stats flags
    • save_to_history() / save_initiated_swap_to_history() helpers
  • allways/cli/swap_commands/swap.py — Save to history in agent mode (--yes) where watch is skipped
  • allways/cli/swap_commands/post_tx.py — Save to history after swap initiated
  • allways/cli/swap_commands/resume.py — Save to history in non-interactive mode

How It Works

Transparent fallback — alw view swap 42 just works

Before (swap resolved on-chain):

Swap 42 has been resolved (completed or timed out).
Resolved swaps are removed from on-chain storage.

After:

Swap 42 resolved on-chain. Showing local history:

  Swap ID          42
  Status           Completed
  Direction        BTC -> TAO

  Source Amount     0.10000000 BTC
  Dest Amount       34.50000000 TAO
  Rate Applied      0.00289855 BTC/TAO

  Source TX         abc123def456...
  Dest TX           789ghi012jkl...

  User Source Addr  bc1q...
  User Dest Addr    5C...
  Miner Hotkey      5Cxyz...

  Initiated Block   1,234,500
  Fulfilled Block   1,234,512
  Completed Block   1,234,518
  Timestamp         2026-04-07 14:23:45 UTC

Browse all past swaps — alw view history

$ alw view history

           Swap History
 ID  Direction    Sent              Received           Status   Date
 42  BTC -> TAO   0.10000000 BTC    34.15500000 TAO    Done     2026-04-07 14:23
 38  TAO -> BTC   50.00000000 TAO   0.14500000 BTC     Done     2026-04-05 09:11
 35  BTC -> TAO   0.05000000 BTC    17.00000000 TAO    Timeout  2026-04-04 21:45
 31  BTC -> TAO   0.25000000 BTC    85.00000000 TAO    Done     2026-04-03 11:02

Filter — alw view history --status completed

$ alw view history --status completed

 ID  Direction    Sent              Received           Status   Date
 42  BTC -> TAO   0.10000000 BTC    34.15500000 TAO    Done     2026-04-07 14:23
 38  TAO -> BTC   50.00000000 TAO   0.14500000 BTC     Done     2026-04-05 09:11
 31  BTC -> TAO   0.25000000 BTC    85.00000000 TAO    Done     2026-04-03 11:02

Aggregate stats — alw view history --stats

$ alw view history --stats

           Swap History
 ID  Direction    Sent              Received           Status   Date
 42  BTC -> TAO   0.10000000 BTC    34.15500000 TAO    Done     2026-04-07 14:23
 38  TAO -> BTC   50.00000000 TAO   0.14500000 BTC     Done     2026-04-05 09:11
 35  BTC -> TAO   0.05000000 BTC    17.00000000 TAO    Timeout  2026-04-04 21:45
 31  BTC -> TAO   0.25000000 BTC    85.00000000 TAO    Done     2026-04-03 11:02

Summary
  Total Swaps           4
  Completed             3 (75%)
  Timed Out             1
  Total Sent BTC        0.40000000 BTC
  Total Sent TAO        50.00000000 TAO
  Total Received BTC    0.14500000 BTC
  Total Received TAO    119.15500000 TAO

All flags

Flag Description Example
--swap <id> Full detail view of a single past swap alw view history --swap 42
--status <s> Filter by completed or timed_out alw view history --status completed
--limit <n> Show only the last N swaps (default 50) alw view history --limit 5
--stats Show aggregate summary after table alw view history --stats

Design Decisions

  • SQLite — matches PR Persist pending confirms in SQLite #11's pattern for pending confirms. WAL mode, same ~/.allways/ location.
  • All touchpoints captured — history saved from swap now (agent mode), swap resume, post-tx, and view swap --watch. Non-interactive flows save at initiation; watched flows update at terminal state. INSERT OR REPLACE handles dedup.
  • Transparent fallbackalw view swap <id> checks local history before showing "resolved" message. Users don't need to learn a new command for the common case.
  • Rate display — rates shown as BTC/TAO (priced in TAO) per owner preference. Stored as canonical, inverted for display.
  • Best-effort savessave_to_history() never raises. If SQLite write fails, the swap flow is unaffected.

Limitation

History is per-machine (local SQLite). Same limitation as pending_swap.json — right tradeoff for simplicity.

Test Plan

  • alw view history shows table of past swaps
  • alw view history --swap 42 shows full detail with all fields
  • alw view history --status completed filters correctly
  • alw view history --stats shows aggregate summary
  • alw view swap <id> falls back to local history when resolved on-chain
  • alw swap now --yes saves initiated swap to history (agent mode)
  • alw swap post-tx <hash> saves to history
  • Duplicate saves (same swap ID) handled gracefully via INSERT OR REPLACE
  • Existing tests pass
  • ruff check and ruff format pass

- Save swap receipts to ~/.allways/swap_history.db when swaps reach
  terminal state (completed/timed_out) or are initiated in non-interactive mode
- alw view swap <id> auto-falls back to local history when swap is
  resolved on-chain, instead of showing "Swap resolved" with no details
- alw view history shows all past swaps with --status, --limit, --swap filters
- alw view history --stats shows aggregate summary (volume, success rate)
- History captured from all touchpoints: swap now, swap resume, post-tx,
  and view swap --watch
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.

1 participant