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.58084% with 103 lines in your changes missing coverage. Please review.
✅ Project coverage is 75.61%. Comparing base (19e86e6) to head (caf9a23).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
cashu/mint/ledger/melt.py	81.56%	47 Missing ⚠️
cashu/mint/ledger/mint.py	82.58%	31 Missing ⚠️
cashu/mint/ledger/ledger.py	90.90%	11 Missing ⚠️
cashu/mint/ledger/swap.py	80.48%	8 Missing ⚠️
cashu/mint/ledger/blind_signatures.py	91.42%	6 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1032      +/-   ##
==========================================
+ Coverage   75.41%   75.61%   +0.19%     
==========================================
  Files         111      116       +5     
  Lines       12546    12590      +44     
==========================================
+ Hits         9462     9520      +58     
+ Misses       3084     3070      -14     

☔ 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.

[KvngMikey]

• Every non-move change has been removed, protocols.py and crud.py are now identical to upstream.
• the swap annotation and the bol11 text are reverted (will be fixed in follow up PR) and Ledger.module is pinned back to cashu.mint.ledger.
• The one genuine cross-class dependency the split introduces (LedgerMint needing get_unit_balance_and_fees) is now satisfied by inheriting the real LedgerWatchdog mixin rather than a Protocol stub, so there is no runtime stub and no shadowing. The PR is a clean move plus that single structural inheritance edge.