Skip to content

feat(wallet): add efficient recovery#1081

Draft
a1denvalu3 wants to merge 2 commits into
mainfrom
feat/efficient-recovery
Draft

feat(wallet): add efficient recovery#1081
a1denvalu3 wants to merge 2 commits into
mainfrom
feat/efficient-recovery

Conversation

@a1denvalu3

Copy link
Copy Markdown
Collaborator

Summary

  • implement efficient wallet recovery proposed in cashubtc/nuts#342
  • add encrypted d_gap metadata to blinded messages and signatures
  • persist and restore d_gap at the mint and advertise NUT-342 support
  • calculate recovery gaps from unspent and pending proofs within the same keyset
  • recover using windowed binary-search probes with NUT-13 fallback

Implementation notes

Binary-search probes use the legacy recovery batch size as their window size. This tolerates isolated derivation gaps while keeping the strategy wallet-defined and wire-compatible.

The wallet reuses the derivation counter already stored in each proof's derivation_path; no wallet schema migration is needed. The mint adds a nullable d_gap column to promises.

Testing

  • poetry run ruff check .
  • poetry run mypy cashu --check-untyped-defs
  • focused efficient-recovery, wallet restore, mint database, and auth tests

Review considerations

  • draft specification is still under discussion
  • includes a mint database migration
  • includes AES-128-GCM recovery metadata keyed from the deterministic blinding factor
  • windowed binary search tolerates gaps within a probe window; wallets fall back to NUT-13 when the search assumptions cannot be established

@codecov

codecov Bot commented Jul 14, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 83.33333% with 21 lines in your changes missing coverage. Please review.
✅ Project coverage is 74.65%. Comparing base (a935eb9) to head (230596b).
✅ All tests successful. No failed tests found.

Files with missing lines Patch % Lines
cashu/wallet/wallet.py 75.60% 20 Missing ⚠️
cashu/core/nuts/nut342.py 95.45% 1 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main    #1081      +/-   ##
==========================================
+ Coverage   74.54%   74.65%   +0.11%     
==========================================
  Files         115      116       +1     
  Lines       13195    13310     +115     
==========================================
+ Hits         9836     9937     +101     
- Misses       3359     3373      +14     

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

@a1denvalu3

Copy link
Copy Markdown
Collaborator Author
image

robwoodgate added a commit to cashubtc/cashu-ts that referenced this pull request Jul 14, 2026
Self-contained demo of the draft recovery scheme against a mint built
from the Nutshell reference branch (cashubtc/nutshell#1081). The
Makefile builds and runs the mint (up/demo/down); the script exercises
two mints, several swaps, a Lightning melt with NUT-08 change and an
unclaimed sent token, then recovers everything from seed alone via
restoreEfficient(), with a batchRestore() comparison.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Backlog

Development

Successfully merging this pull request may close these issues.

1 participant