# Implement Saga Pattern for Swap Operations with Recovery Mechanism
## Overview
This PR refactors the swap operation implementation to use the saga pattern - a distributed transaction pattern that provides reliable transaction management through explicit state tracking and compensation-based error handling. The implementation includes a robust recovery mechanism that automatically handles swap operations interrupted by crashes, power loss, or network failures.
## What Changed
**Saga Pattern Implementation:**
- Introduced a strict linear state machine for swaps: `Initial` → `SetupComplete` → `Signed` → `Completed`
- New modular `swap_saga` module with state validation, compensation logic, and saga orchestration
- Automatic rollback of database changes on failure, ensuring atomic swap operations
- Replaced previous swap implementation (`swap.rs`, `blinded_message_writer.rs`) with saga-based approach
**Recovery Mechanism:**
- Added `operation_id` and `operation_kind` columns to database schema for tracking which operation proofs belong to
- New `recover_from_bad_swaps()` method that runs on mint startup to handle incomplete swaps
- For proofs left in `PENDING` state from swap operations:
- If blind signatures exist: marks proofs as `SPENT` (swap completed but not finalized)
- If no blind signatures exist: removes proofs from database (swap failed partway through)
- Database migrations included for both PostgreSQL and SQLite
* feat(cdk): add WebSocket authentication support with comprehensive configuration
- Add WebSocket auth token injection for client connections
- Implement server-side WebSocket authentication verification
- Add configuration options for per-endpoint WebSocket auth types
- Include comprehensive documentation and example configuration
- Support clear, blind, and no-auth modes for WebSocket endpoin
* feat(docker): add LDK Node mint service with dedicated Docker setup
- Add Dockerfile.ldk-node and Dockerfile.ldk-node.arm for LDK Node builds
- Add GitHub Actions workflows for publishing LDK Node Docker images
- Add docker-compose.ldk-node.yaml for standalone LDK Node deployment
- Integrate LDK Node service into main docker-compose.yaml with profile
- Update cdk-mintd README with LDK Node Docker configuration
* feat: use docker tags
* feat(cdk): add generic key-value store functionality for mint databases
Implements a comprehensive KV store system with transaction support,
namespace-based organization, and validation for mint databases.
- Add KVStoreDatabase and KVStoreTransaction traits for generic storage
- Include namespace and key validation with ASCII character restrictions
- Add database migrations for kv_store table in SQLite and PostgreSQL
- Implement comprehensive test suite for KV store functionality
- Integrate KV store traits into existing Database and Transaction bounds
* feat: add LDK Node Lightning backend with comprehensive integration
- Add new cdk-ldk-node crate implementing Lightning backend using LDK Node
- Extend MintPayment trait with start/stop methods for processor lifecycle management
- Add LDK Node configuration support to cdk-mintd with chain source and gossip options
- Enhance mint startup/shutdown to properly manage payment processor lifecycle
---------
Co-authored-by: Erik <78821053+swedishfrenchpress@users.noreply.github.com>
* refactor(cdk-lnbits): migrate to LNbits v1 websocket API and remove webhook support
- Remove webhook-based payment notifications in favor of v1 websocket API
- Add explicit documentation that only LNbits v1 API is supported
- Remove webhook_url parameter and related router setup code
- Simplify payment status handling by removing pending status logic
- Switch to local lnbits-rs dependency for development
- Remove unused axum dependency and clean up imports
- Update configuration documentation and examples
* refactor(cdk-lnbits): extract payment processing logic into helper methods
Improve code readability by separating message processing, payment response
creation, and payment hash decoding into dedicated methods. This reduces
complexity in the main payment waiting loop while maintaining identical
functionality
* chore: bump lnbits-rs
* Add PostgreSQL support for mint and wallet
* Fixed bug to avoid empty calls `get_proofs_states`
* Fixed SQL bug
* Avoid redudant clone()
* Add more tests for the storage layer
* Minor enhacements
* Add a generic function to execute db operations
This function would log slow operations and log errors
* Provision a postgres db for tests
* Update deps for msrv
* Add postgres to pipeline
* feat: add psgl to example and docker
* feat: db url fmt
---------
Co-authored-by: thesimplekid <tsk@thesimplekid.com>
* feat(cdk-integration-tests): refactor regtest setup and mintd integration
- Replace shell-based regtest setup with Rust binary (start_regtest_mints)
- Add cdk-mintd crate to workspace and integration tests
- Improve environment variable handling for test configurations
- Update integration tests to use proper temp directory management
- Remove deprecated start_regtest.rs binary
- Enhance CLN client connection with retry logic
- Simplify regtest shell script (itests.sh) to use new binary
- Fix tracing filters and improve error handling in setup
- Update dependencies and configurations for integration tests
fix: killing
chore: comment tests for ci debugging
chore: compile
Revert "chore: comment tests for ci debugging"
This reverts commit bfc594c11cf37caeaa6445cb854ae5567d2da6bd.
* chore: sql cipher
* fix: removal of sqlite cipher
* fix: auth password
* refactor(cdk-mintd): improve database password handling and function signatures
- Pass database password as parameter instead of parsing CLI args in setup_database
- Update function signatures for run_mintd and run_mintd_with_shutdown to accept db_password
- Remove direct CLI parsing from database setup logic
- Fix auth database initialization to use correct type when sqlcipher feature enabled
The primary purpose of this new crate is to have a common and shared codebase
for all SQL storage systems. It would force us to write standard SQL using best
practices for all databases.
This crate has been extracted from #878
- Add background service management with graceful shutdown handling
- Refactor invoice payment monitoring to use centralized task supervision
- Update cdk-mintd and integration tests to use new lifecycle methods
- Add comprehensive documentation and lifecycle tests
* Split the database trait into read and transactions.
The transaction traits will encapsulate all database changes and also expect
READ-and-lock operations to read and lock records from the database for
exclusive access, thereby avoiding race conditions.
The Transaction trait expects a `rollback` operation on Drop unless the
transaction has been committed.
* fix: melt quote duplicate error
This change stops a second melt quote from being created
if there is an existing valid melt quote for an invoice already.
If the first melt quote has expired then we allow for a new melt quote to be created.
---------
Co-authored-by: thesimplekid <tsk@thesimplekid.com>
* Migrate from `sqlx` to rusqlite
1. Add rusqlite with rusqlite with a working thread
2. Add wallet without a thread (synchronous)
3. Add custom migration
Co-authored-by: thesimplekid <tsk@thesimplekid.com>
* WIP: Introduce a SignatoryManager service.
The SignatoryManager manager provides an API to interact with keysets, private
keys, and all key-related operations, offering segregation between the mint and
the most sensible part of the mind: the private keys.
Although the default signatory runs in memory, it is completely isolated from
the rest of the system and can only be communicated through the interface
offered by the signatory manager. Only messages can be sent from the mintd to
the Signatory trait through the Signatory Manager.
This pull request sets the foundation for eventually being able to run the
Signatory and all the key-related operations in a separate service, possibly in
a foreign service, to offload risks, as described in #476.
The Signatory manager is concurrent and deferred any mechanism needed to handle
concurrency to the Signatory trait.
* Fixed missing default feature for signatory
* Do not read keys from the DB
* Removed KeysDatabase Trait from MintDatabase
All Keys operations should be done through the signatory
* Make sure signatory has all the keys in memory
Drop also foreign constraints on sqlite
* Fix race condition
* Adding debug info to failing test
* Add `sleep` in test
* Fixed issue with active auth keyset
* Fixed dependency
* Move all keys and keysets to an ArcSwap.
Since the keys and keysets exist in RAM, most wrapping functions are infallible
and synchronous, improving performance and adding breaking API changes.
The signatory will provide this information on the boot and update when the
`rotate_keyset` is executed.
Todo: Implement a subscription key to reload the keys when the GRPC server
changes the keys. For the embedded mode, that makes no sense since there is a
single way to rotate keys, and that bit is already covered.
* Implementing https://github.com/cashubtc/nuts/pull/250
* Add CLI for cdk-signatory to spawn an external signatory
Add to the pipeline the external signatory
* Update tests
* Apply suggestions from code review
Co-authored-by: ok300 <106775972+ok300@users.noreply.github.com>
Co-authored-by: thesimplekid <tsk@thesimplekid.com>
* Minor change
* Update proto buf to use the newest format
* Rename binary
* Add instrumentations
* Add more comments
* Use a single database for the signatory
Store all keys, even auth keys, in a single database. Leave the MintAuthDatabse
trait implementation for the CDK but not the signagtory
This commit also moves the cli mod to its own file
* Update dep
* Add `test_mint_keyset_gen` test
---------
Co-authored-by: ok300 <106775972+ok300@users.noreply.github.com>
Co-authored-by: thesimplekid <tsk@thesimplekid.com>
