Nutshell 0.22.1

We forgot to bump the version in the last release. Here are the release notes of 0.22.0 again.

Nutshell 0.22.0 brings BIP-39 mint seeds, updated payment requests, response caching without Redis, improved Lightning payment handling, and security fixes.

Compatibility Notes

• Mint seeds: MINT_PRIVATE_KEY is deprecated but remains supported. Existing mints can set MINT_MNEMONIC and transition each unit through an explicit next-keyset rotation. Setting the mnemonic does not rotate existing keysets automatically. Back up the mnemonic securely and keep it configured once mnemonic-derived keysets exist.
• Seed encryption: operators using legacy keysets with MINT_SEED_DECRYPTION_KEY should re-run poetry run python -m cashu.mint.encrypt migrate --no-dry-run after upgrading.
• Python installation: Python 3.12 is recommended for pip and pipx installations to avoid current Coincurve build issues on Python 3.13/3.14.

Notable Changes

Mint

• BIP-39 mint seeds: support for MINT_MNEMONIC, with CDK-compatible key derivation and validation at startup.
• NUT-19 response caching: successful mint, batch mint, swap, and melt responses are cached in memory by default. Redis remains available for shared caching across workers and instances.
• LND routing fees: REST and gRPC backends now probe route fees when creating full-invoice melt quotes, with a fallback to the configured fee reserve.
• Payment handling: improved melt execution, recovery across workers, and management tooling, plus graceful shutdown of background tasks and backend connections.
• Invoice validation: earlier rejection of expired LND invoices and improved handling of backend-normalized quote amounts, including Spark’s fractional-satoshi rounding.
• Keyset rotation: requests with already-accepted outputs continue correctly through a rotation.
• Spark: updated SDK integration and payment lifecycle handling.
• Security: fixes and hardening across mint accounting, authentication, seed handling, logging, and request validation.

Wallet

• NUT-18/26 payment requests: updated support for preferred mints, supported payment methods, and method fees.
• cashu request: create payment requests from the CLI, including optional NUT-26 bech32m encoding.
• Payment selection and fees: select a funded, compatible mint and account for input fees so the recipient receives the requested value.
• Multi-mint tokens: preserve mixed-mint V3 tokens during decoding.
• Mint compatibility: accept older melt quote responses that omit method, and use the returned quote amount when minting and transferring between mints.

Other

• Added clean-install validation before package publishing and updated dependencies.
• Expanded wallet compatibility, multi-mint, payment lifecycle, and mutation test coverage.
• Added configurable per-invoice payment outcomes to FakeWallet.

New Contributors

• @btcforplebs in #1169
• @ifuensan in #1191

Full Changelog