refactor(mint): split monolithic ledger.py into ledger/ package

[KvngMikey]

Fixes #865

Summary

Extracts the monolithic 1413-line cashu/mint/ledger.py into a package with focused mixin classes, making the code easier to navigate and understand. Each mixin inherits from the mixin that provides the methods it calls, this way all existing imports continue to work unchanged.

Changes

• cashu/mint/ledger.py has been replaced with a cashu/mint/ledger/ package containing focused submodules.
• ledger/__init__.py barrel exports from .ledger import Ledger.
• No logic was changed. Existing test suite passes without modification.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Refactors the mint ledger implementation from a single large module into a structured package, separating mint/melt/swap and blind-signature logic while adding protocol typing for watchdog functionality.

Changes:

• Split cashu/mint/ledger.py into multiple modules under cashu/mint/ledger/ (mint, melt, swap, blind_signatures, ledger).
• Introduced SupportsWatchdog protocol to type the watchdog balance/fee API used during mint quoting.
• Added cashu.mint.ledger package export via __init__.py.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
cashu/mint/protocols.py	Adds SupportsWatchdog protocol and supporting imports for typed watchdog integration.
cashu/mint/ledger/ledger.py	New composed Ledger class wiring together split ledger mixins and startup/shutdown routines.
cashu/mint/ledger/blind_signatures.py	Extracts blind signature storage/signing + fee-change promise generation.
cashu/mint/ledger/mint.py	Extracts mint quote, mint, and batch mint flows into a dedicated mixin.
cashu/mint/ledger/melt.py	Extracts melt quoting and payment execution logic into a dedicated mixin.
cashu/mint/ledger/swap.py	Extracts swap + restore logic into a dedicated mixin.
cashu/mint/ledger/init.py	Exposes the new package-level Ledger import.
cashu/mint/ledger.py	Removes the previous monolithic ledger module.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov]

Codecov Report

❌ Patch coverage is 84.00598% with 107 lines in your changes missing coverage. Please review.
✅ Project coverage is 75.41%. Comparing base (10ccf1b) to head (aebe07a).
⚠️ Report is 2 commits behind head on main.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
cashu/mint/ledger/melt.py	82.28%	45 Missing ⚠️
cashu/mint/ledger/mint.py	79.88%	35 Missing ⚠️
cashu/mint/ledger/ledger.py	90.08%	12 Missing ⚠️
cashu/mint/ledger/swap.py	80.48%	8 Missing ⚠️
cashu/mint/ledger/blind_signatures.py	90.00%	7 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1032      +/-   ##
==========================================
+ Coverage   75.28%   75.41%   +0.12%     
==========================================
  Files         111      116       +5     
  Lines       12419    12473      +54     
==========================================
+ Hits         9350     9406      +56     
+ Misses       3069     3067       -2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

[callebtc]

I reviewed this specifically as a move-only refactor, and I found several changes that are not clean code movement:

1. LedgerMint now inherits SupportsWatchdog, and SupportsWatchdog defines an async get_unit_balance_and_fees stub. In the new Ledger MRO, LedgerMint appears before LedgerWatchdog, so self.get_unit_balance_and_fees(...) can resolve to the Protocol stub instead of the real watchdog implementation. The call in cashu/mint/ledger/mint.py when settings.mint_max_balance is enabled can therefore await the stub and fail instead of using LedgerWatchdog.get_unit_balance_and_fees. This is a runtime behavior change, not a pure move.

2. Ledger is now defined in cashu.mint.ledger.ledger and re-exported from cashu.mint.ledger. Existing imports like from cashu.mint.ledger import Ledger still work, but Ledger.__module__ changes from cashu.mint.ledger to cashu.mint.ledger.ledger. That is observable for introspection, pickling, and FQN-based integrations, so it is not a zero-change refactor.

3. cashu/mint/crud.py adds try_update_mint_quote_last_checked to the abstract LedgerCrud interface. The concrete implementation already existed, but this changes the contract for custom LedgerCrud subclasses and can make previously instantiable subclasses abstract. That is not moved code.

4. There are smaller non-move edits too: the disabled-melt error text changes from Melting with bol11 is disabled. to Melting with bolt11 is disabled., and swap gains a runtime-visible return annotation. These are minor individually, but they still violate the stated goal of zero changes other than moving code.

Given the stated scope, I would not consider this PR a completely clean refactor until these are reverted or handled in separate behavior/typing cleanup commits.