Allow caller-provided wallets for untrusted-mint settlement attempts #3

New issue

Closed

opened 2026-10-09 11:19:44 +00:00 by thesimplekid · 0 comments

thesimplekid commented

2026-10-09 11:19:44 +00:00

Owner

Problem

Direct settlement currently creates an isolated CDK source wallet per Cashu token/attempt, with a persistent seed and SQLite database under the Engine data directory. These wallets track original proofs, melt recovery, and change without mixing source proofs into trusted balances or payouts.

Once applications can supply their trusted wallet, the library still needs a way to handle previously unknown source mints without taking control of their wallet storage.

Proposed improvement

Introduce a caller-provided wallet provider/factory that opens or creates an isolated source wallet using a stable attempt identity, source mint, and unit. Retries and restarts must resolve to the same wallet state. Provide the existing persistent per-attempt implementation as the default.

Preserve the current direct-melt behavior: no preliminary swap, no automatic reuse of original source proofs for payouts, and no remelting after a durable rejection. Define how source network restrictions remain enforced when a caller supplies the wallet or connector; injection must not silently bypass the existing public-address, redirect, and transport restrictions.

Persistence and in-memory storage

Do not replace the default with an in-memory database. A crash during a held or uncertain melt can lose wallet recovery and change-output state. An in-memory implementation is only safe if an external durable journal can fully reconstruct all required state; evaluating that is optional and must not weaken recovery guarantees.

Acceptance criteria

The caller can control source-wallet construction and persistence without changing settlement logic.
Stable attempt lookup, exclusive use, and lifecycle requirements are documented.
Source proofs remain isolated from trusted receiving wallets and payouts.
Tests cover pending melts across restart, lost responses, claim/reject recovery, original-proof release, and change recovery.
Storage is not discarded while an operation or change recovery remains unresolved.

This complements caller-managed trusted wallets and is a post-first-release improvement.

## Problem Direct settlement currently creates an isolated CDK source wallet per Cashu token/attempt, with a persistent seed and SQLite database under the Engine data directory. These wallets track original proofs, melt recovery, and change without mixing source proofs into trusted balances or payouts. Once applications can supply their trusted wallet, the library still needs a way to handle previously unknown source mints without taking control of their wallet storage. ## Proposed improvement Introduce a caller-provided wallet provider/factory that opens or creates an isolated source wallet using a stable attempt identity, source mint, and unit. Retries and restarts must resolve to the same wallet state. Provide the existing persistent per-attempt implementation as the default. Preserve the current direct-melt behavior: no preliminary swap, no automatic reuse of original source proofs for payouts, and no remelting after a durable rejection. Define how source network restrictions remain enforced when a caller supplies the wallet or connector; injection must not silently bypass the existing public-address, redirect, and transport restrictions. ## Persistence and in-memory storage Do not replace the default with an in-memory database. A crash during a held or uncertain melt can lose wallet recovery and change-output state. An in-memory implementation is only safe if an external durable journal can fully reconstruct all required state; evaluating that is optional and must not weaken recovery guarantees. ## Acceptance criteria - The caller can control source-wallet construction and persistence without changing settlement logic. - Stable attempt lookup, exclusive use, and lifecycle requirements are documented. - Source proofs remain isolated from trusted receiving wallets and payouts. - Tests cover pending melts across restart, lost responses, claim/reject recovery, original-proof release, and change recovery. - Storage is not discarded while an operation or change recovery remains unresolved. This complements caller-managed trusted wallets and is a post-first-release improvement.

~~thesimplekid referenced this issue 2026-10-09 11:20:34 +00:00~~

Embedding compatibility: CDK version pin and MSRV #9

thesimplekid referenced this issue

2026-10-09 11:20:55 +00:00

Embedding compatibility: CDK version pin and MSRV #9

thesimplekid referenced this issue

2026-10-09 12:51:51 +00:00

feat: accept caller-managed trusted Cashu wallets #15

thesimplekid referenced this issue from a commit

2026-10-09 13:02:53 +00:00

feat: allow persistent source-wallet providers

thesimplekid referenced this issue from a pull request that will close it,