From 56ff5c3f19361916a3aa094d6485d5aa70da0826 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Sun, 29 Jun 2025 13:55:59 +0100 Subject: [PATCH 001/321] chore: bump v0.11 --- CHANGELOG.md | 31 +++++++++++++++++++++++++++++-- Cargo.toml | 28 ++++++++++++++-------------- 2 files changed, 43 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d454f1148..bcf918f20 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,9 +4,35 @@ -[Unreleased] +## [0.11.0](https://github.com/cashubtc/cdk/releases/tag/v0.11.0) + +### Added +- cdk-lnbits: Support lnbits v1 and pre-v1 [PR](https://github.com/cashubtc/cdk/pull/802) ([thesimplekid]). +- Support for Keyset v2 [PR](https://github.com/cashubtc/cdk/pull/702) ([lollerfirst]). +- Add option to limit the token size of a send [PR](https://github.com/cashubtc/cdk/pull/855) ([davidcaseria]). +- Database transaction support [PR](https://github.com/cashubtc/cdk/pull/826) ([crodas]). +- Support for multsig refund [PR](https://github.com/cashubtc/cdk/pull/860) ([thesimplekid]). +- Convert unit helper fn [PR](https://github.com/cashubtc/cdk/pull/856) ([davidcaseria]). + +### Changed +- cdk-sqlite: remove sqlx in favor of rusqlite ([crodas]). +- cdk-lnd: use custom tonic gRPC instead of fedimint-tonic-grpc [PR](https://github.com/cashubtc/cdk/pull/831) ([thesimplekid]). +- cdk-cln: remove the us of mutex on cln client [PR](https://github.com/cashubtc/cdk/pull/832) ([thesimplekid]). + ### Fixed -- Mintd version updated when grpc is enabled [PR](https://github.com/cashubtc/cdk/pull/803) ([thesimplekid]). +- mint start up check was not checking unpaid quotes [PR](https://github.com/cashubtc/cdk/pull/844) ([gudnuf]). +- Naming of blinded_message column on blind_signatures was y [PR](https://github.com/cashubtc/cdk/pull/845) ([thesimplekid]). +- cdk-cli: Create wallets for non sat units if supported [PR](https://github.com/cashubtc/cdk/pull/841) ([thesimplekid]). + +### Removed +- cdk-redb support for the mint [PR](https://github.com/cashubtc/cdk/pull/787) ([thesimplekid]). +- cdk-sqlite remove unused melt_request table [PR](https://github.com/cashubtc/cdk/pull/819) ([crodas]) + + +## [0.10.1](https://github.com/cashubtc/cdk/releases/tag/v0.10.1) +### Fix +- Set mint version when mint rpc is enabled [PR](https://github.com/cashubtc/cdk/pull/803) ([thesimplekid]). +- `cdk-signatory` is optional for wallet [PR](https://github.com/cashubtc/cdk/pull/815) ([thesimplekid]). ## [0.10.0](https://github.com/cashubtc/cdk/releases/tag/v0.10.0) ### Added @@ -379,3 +405,4 @@ Additionally, this release introduces a Mint binary cdk-mintd that uses the cdk- [benthecarman]: https://github.com/benthecarman [Darrell]: https://github.com/Darrellbor [asmo]: https://github.com/asmogo +[gudnuf]: https://github.com/gudnuf diff --git a/Cargo.toml b/Cargo.toml index 3c30044a1..3aaab2b85 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -33,7 +33,7 @@ rust-version = "1.75.0" license = "MIT" homepage = "https://github.com/cashubtc/cdk" repository = "https://github.com/cashubtc/cdk.git" -version = "0.10.0" +version = "0.11.0" readme = "README.md" [workspace.dependencies] @@ -43,19 +43,19 @@ axum = { version = "0.8.1", features = ["ws"] } bitcoin = { version = "0.32.2", features = ["base64", "serde", "rand", "rand-std"] } bip39 = { version = "2.0", features = ["rand"] } jsonwebtoken = "9.2.0" -cashu = { path = "./crates/cashu", version = "=0.10.0" } -cdk = { path = "./crates/cdk", default-features = false, version = "=0.10.0" } -cdk-common = { path = "./crates/cdk-common", default-features = false, version = "=0.10.0" } -cdk-axum = { path = "./crates/cdk-axum", default-features = false, version = "=0.10.0" } -cdk-cln = { path = "./crates/cdk-cln", version = "=0.10.0" } -cdk-lnbits = { path = "./crates/cdk-lnbits", version = "=0.10.0" } -cdk-lnd = { path = "./crates/cdk-lnd", version = "=0.10.0" } -cdk-fake-wallet = { path = "./crates/cdk-fake-wallet", version = "=0.10.0" } -cdk-payment-processor = { path = "./crates/cdk-payment-processor", default-features = true, version = "=0.10.0" } -cdk-mint-rpc = { path = "./crates/cdk-mint-rpc", version = "=0.10.0" } -cdk-redb = { path = "./crates/cdk-redb", default-features = true, version = "=0.10.0" } -cdk-sqlite = { path = "./crates/cdk-sqlite", default-features = true, version = "=0.10.0" } -cdk-signatory = { path = "./crates/cdk-signatory", version = "=0.10.0", default-features = false } +cashu = { path = "./crates/cashu", version = "=0.11.0" } +cdk = { path = "./crates/cdk", default-features = false, version = "=0.11.0" } +cdk-common = { path = "./crates/cdk-common", default-features = false, version = "=0.11.0" } +cdk-axum = { path = "./crates/cdk-axum", default-features = false, version = "=0.11.0" } +cdk-cln = { path = "./crates/cdk-cln", version = "=0.11.0" } +cdk-lnbits = { path = "./crates/cdk-lnbits", version = "=0.11.0" } +cdk-lnd = { path = "./crates/cdk-lnd", version = "=0.11.0" } +cdk-fake-wallet = { path = "./crates/cdk-fake-wallet", version = "=0.11.0" } +cdk-payment-processor = { path = "./crates/cdk-payment-processor", default-features = true, version = "=0.11.0" } +cdk-mint-rpc = { path = "./crates/cdk-mint-rpc", version = "=0.11.0" } +cdk-redb = { path = "./crates/cdk-redb", default-features = true, version = "=0.11.0" } +cdk-sqlite = { path = "./crates/cdk-sqlite", default-features = true, version = "=0.11.0" } +cdk-signatory = { path = "./crates/cdk-signatory", version = "=0.11.0", default-features = false } clap = { version = "4.5.31", features = ["derive"] } ciborium = { version = "0.2.2", default-features = false, features = ["std"] } cbor-diag = "0.1.12" From 4b82fa82a76a07944a32f74dfd2e4e668af62150 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Sun, 29 Jun 2025 17:15:38 +0100 Subject: [PATCH 002/321] chore: release summary --- CHANGELOG.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index bcf918f20..8f6db7ad5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,8 +4,30 @@ + + ## [0.11.0](https://github.com/cashubtc/cdk/releases/tag/v0.11.0) +### Summary + +Version 0.11.0 brings significant architectural changes to enhance database reliability and performance. The major changes include: + +1. **Database Engine Change**: Replaced `sqlx` with `rusqlite` as the SQLite database driver and removed support for `redb`. This change provides better performance and reliability for database operations. + +2. **Transaction Management**: Introduced robust database transaction support that encapsulates all database changes. The new Transaction trait implements a rollback operation on Drop unless explicitly committed, ensuring data integrity. + +3. **Race Condition Prevention**: Added READ-and-lock operations to securely read and lock records from the database for exclusive access, preventing race conditions in concurrent operations. + +### ⚠️ Important Migration Note for redb Users +If you are currently running a mint with redb, you must migrate to SQLite before upgrading to v0.11. Follow these steps: + +1. Stop your current mint +2. Back up your database +3. Use the migration script available at: https://github.com/cashubtc/cdk/blob/main/misc/convert_redb_to_sqlite.sh +4. Update your config file to target the SQLite database engine +5. Start your mint with v0.11 + + ### Added - cdk-lnbits: Support lnbits v1 and pre-v1 [PR](https://github.com/cashubtc/cdk/pull/802) ([thesimplekid]). - Support for Keyset v2 [PR](https://github.com/cashubtc/cdk/pull/702) ([lollerfirst]). From c7dfb4307110dc10fa5c4c84f303b581c06cfe38 Mon Sep 17 00:00:00 2001 From: Darrell Date: Mon, 30 Jun 2025 08:17:55 +0900 Subject: [PATCH 003/321] fix GLIBC compatibility issue --- Dockerfile | 2 +- Dockerfile.arm | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Dockerfile b/Dockerfile index 711d172da..85bc2e03c 100644 --- a/Dockerfile +++ b/Dockerfile @@ -13,7 +13,7 @@ COPY crates ./crates RUN nix develop --extra-experimental-features nix-command --extra-experimental-features flakes --command cargo build --release --bin cdk-mintd --features redis # Create a runtime stage -FROM debian:bookworm-slim +FROM debian:sid-slim # Set the working directory WORKDIR /usr/src/app diff --git a/Dockerfile.arm b/Dockerfile.arm index cdb19fd5f..7f4333844 100644 --- a/Dockerfile.arm +++ b/Dockerfile.arm @@ -16,7 +16,7 @@ RUN echo 'filter-syscalls = false' > /etc/nix/nix.conf RUN nix develop --extra-platforms aarch64-linux --extra-experimental-features nix-command --extra-experimental-features flakes --command cargo build --release --bin cdk-mintd --features redis # Create a runtime stage -FROM debian:bookworm-slim +FROM debian:sid-slim # Set the working directory WORKDIR /usr/src/app From 0e3b23534ae0131164b9390b93c1788d52353c03 Mon Sep 17 00:00:00 2001 From: mountdisk Date: Mon, 30 Jun 2025 19:33:20 +0800 Subject: [PATCH 004/321] chore: fix some minor issues in the comments Signed-off-by: mountdisk --- crates/cdk-common/src/pub_sub/mod.rs | 2 +- crates/cdk-signatory/src/signatory.rs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/cdk-common/src/pub_sub/mod.rs b/crates/cdk-common/src/pub_sub/mod.rs index 61123ca04..aef062b5b 100644 --- a/crates/cdk-common/src/pub_sub/mod.rs +++ b/crates/cdk-common/src/pub_sub/mod.rs @@ -1,7 +1,7 @@ //! Publish–subscribe pattern. //! //! This is a generic implementation for -//! [NUT-17() with a type +//! [NUT-17]() with a type //! agnostic Publish-subscribe manager. //! //! The manager has a method for subscribers to subscribe to events with a diff --git a/crates/cdk-signatory/src/signatory.rs b/crates/cdk-signatory/src/signatory.rs index 73a661659..31ea99c3c 100644 --- a/crates/cdk-signatory/src/signatory.rs +++ b/crates/cdk-signatory/src/signatory.rs @@ -132,7 +132,7 @@ impl From<&(MintKeySetInfo, MintKeySet)> for SignatoryKeySet { #[async_trait::async_trait] /// Signatory trait pub trait Signatory { - /// The Signatory implementation name. This may be exposed, so being as discreet as possible is + /// The Signatory implementation name. This may be exposed, so being as discrete as possible is /// advised. fn name(&self) -> String; From 48c42e6260f7ca3e65f021b525a3c236c11a198f Mon Sep 17 00:00:00 2001 From: gudnuf Date: Mon, 30 Jun 2025 14:22:28 -0700 Subject: [PATCH 005/321] fix: add cors headers to auth routes --- crates/cdk-axum/src/lib.rs | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/crates/cdk-axum/src/lib.rs b/crates/cdk-axum/src/lib.rs index ec108e36c..230ba7ae1 100644 --- a/crates/cdk-axum/src/lib.rs +++ b/crates/cdk-axum/src/lib.rs @@ -142,6 +142,11 @@ async fn cors_middleware( req: axum::http::Request, next: axum::middleware::Next, ) -> Response { + #[cfg(feature = "auth")] + let allowed_headers = "Content-Type, Clear-auth, Blind-auth"; + #[cfg(not(feature = "auth"))] + let allowed_headers = "Content-Type"; + // Handle preflight requests if req.method() == axum::http::Method::OPTIONS { let mut response = Response::new("".into()); @@ -154,7 +159,7 @@ async fn cors_middleware( ); response.headers_mut().insert( "Access-Control-Allow-Headers", - "Content-Type".parse().unwrap(), + allowed_headers.parse().unwrap(), ); return response; } @@ -171,7 +176,7 @@ async fn cors_middleware( ); response.headers_mut().insert( "Access-Control-Allow-Headers", - "Content-Type".parse().unwrap(), + allowed_headers.parse().unwrap(), ); response @@ -210,9 +215,7 @@ pub async fn create_mint_router_with_custom_cache( .route("/info", get(get_mint_info)) .route("/restore", post(post_restore)); - let mint_router = Router::new() - .nest("/v1", v1_router) - .layer(from_fn(cors_middleware)); + let mint_router = Router::new().nest("/v1", v1_router); #[cfg(feature = "auth")] let mint_router = { @@ -220,6 +223,8 @@ pub async fn create_mint_router_with_custom_cache( mint_router.nest("/v1", auth_router) }; + let mint_router = mint_router.layer(from_fn(cors_middleware)); + let mint_router = mint_router.with_state(state); Ok(mint_router) From 074279214bd5cb4e06275c4dd7dce67eab80e15d Mon Sep 17 00:00:00 2001 From: gudnuf Date: Tue, 1 Jul 2025 09:43:05 -0700 Subject: [PATCH 006/321] chore: add \`enabled_check_proof_state\` to example.config.toml --- crates/cdk-mintd/example.config.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/crates/cdk-mintd/example.config.toml b/crates/cdk-mintd/example.config.toml index bd373df5e..8828a65a4 100644 --- a/crates/cdk-mintd/example.config.toml +++ b/crates/cdk-mintd/example.config.toml @@ -92,3 +92,4 @@ reserve_fee_min = 4 # enabled_check_mint_quote=true # enabled_check_melt_quote=true # enabled_restore=true +# enabled_check_proof_state=true From 49c0e4f0e532a53d50dbc14b16cfff6ef913e097 Mon Sep 17 00:00:00 2001 From: gudnuf Date: Wed, 2 Jul 2025 18:31:37 -0700 Subject: [PATCH 007/321] fix: install CryptoProvider when starting RPC server --- crates/cdk-mint-rpc/src/proto/server.rs | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/crates/cdk-mint-rpc/src/proto/server.rs b/crates/cdk-mint-rpc/src/proto/server.rs index dbba9479e..f2c03eb5b 100644 --- a/crates/cdk-mint-rpc/src/proto/server.rs +++ b/crates/cdk-mint-rpc/src/proto/server.rs @@ -76,6 +76,11 @@ impl MintRPCServer { pub async fn start(&mut self, tls_dir: Option) -> Result<(), Error> { tracing::info!("Starting RPC server {}", self.socket_addr); + #[cfg(not(target_arch = "wasm32"))] + if rustls::crypto::CryptoProvider::get_default().is_none() { + let _ = rustls::crypto::ring::default_provider().install_default(); + } + let server = match tls_dir { Some(tls_dir) => { tracing::info!("TLS configuration found, starting secure server"); From abb43c39b1adfac14c2327c1c5bd253fad412a65 Mon Sep 17 00:00:00 2001 From: David Caseria Date: Thu, 3 Jul 2025 16:07:14 -0400 Subject: [PATCH 008/321] Wallet: Get active mint quotes --- crates/cdk/src/wallet/mint.rs | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/crates/cdk/src/wallet/mint.rs b/crates/cdk/src/wallet/mint.rs index 11def1e70..0ef94f29d 100644 --- a/crates/cdk/src/wallet/mint.rs +++ b/crates/cdk/src/wallet/mint.rs @@ -141,6 +141,16 @@ impl Wallet { Ok(total_amount) } + /// Get active mint quotes + /// Mint quotes that are not expired and not paid will be returned (including those that are paid but not yet issued). + #[instrument(skip(self))] + pub async fn get_active_mint_quotes(&self) -> Result, Error> { + let mut mint_quotes = self.localstore.get_mint_quotes().await?; + let unix_time = unix_time(); + mint_quotes.retain(|quote| quote.state != MintQuoteState::Paid && quote.expiry > unix_time); + Ok(mint_quotes) + } + /// Mint /// # Synopsis /// ```rust,no_run From 54f53eb8775762161d1444fa15e42e28d13a6601 Mon Sep 17 00:00:00 2001 From: David Caseria Date: Thu, 3 Jul 2025 16:39:12 -0400 Subject: [PATCH 009/321] Fix get_active_mint_quotes logic --- crates/cdk/src/wallet/mint.rs | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/crates/cdk/src/wallet/mint.rs b/crates/cdk/src/wallet/mint.rs index 0ef94f29d..033e8a02b 100644 --- a/crates/cdk/src/wallet/mint.rs +++ b/crates/cdk/src/wallet/mint.rs @@ -142,12 +142,13 @@ impl Wallet { } /// Get active mint quotes - /// Mint quotes that are not expired and not paid will be returned (including those that are paid but not yet issued). + /// Returns mint quotes that are not expired and not yet issued. #[instrument(skip(self))] pub async fn get_active_mint_quotes(&self) -> Result, Error> { let mut mint_quotes = self.localstore.get_mint_quotes().await?; let unix_time = unix_time(); - mint_quotes.retain(|quote| quote.state != MintQuoteState::Paid && quote.expiry > unix_time); + mint_quotes + .retain(|quote| quote.state != MintQuoteState::Issued && quote.expiry > unix_time); Ok(mint_quotes) } From 4e3af789f34dded5d508e024248dc972a97d535f Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Sun, 6 Jul 2025 10:56:29 +0100 Subject: [PATCH 010/321] chore: remove start up pending mint check --- crates/cdk-mintd/src/main.rs | 6 ------ crates/cdk/src/mint/issue/issue_nut04.rs | 22 -------------------- crates/cdk/src/mint/start_up_check.rs | 26 ------------------------ 3 files changed, 54 deletions(-) diff --git a/crates/cdk-mintd/src/main.rs b/crates/cdk-mintd/src/main.rs index 5f9966668..0936b69d0 100644 --- a/crates/cdk-mintd/src/main.rs +++ b/crates/cdk-mintd/src/main.rs @@ -539,12 +539,6 @@ async fn main() -> anyhow::Result<()> { let mint = Arc::new(mint); - // Check the status of any mint quotes that are pending - // In the event that the mint server is down but the ln node is not - // it is possible that a mint quote was paid but the mint has not been updated - // this will check and update the mint state of those quotes - mint.check_pending_mint_quotes().await?; - // Checks the status of all pending melt quotes // Pending melt quotes where the payment has gone through inputs are burnt // Pending melt quotes where the payment has **failed** inputs are reset to unspent diff --git a/crates/cdk/src/mint/issue/issue_nut04.rs b/crates/cdk/src/mint/issue/issue_nut04.rs index 5b01aeb71..4b159b8dd 100644 --- a/crates/cdk/src/mint/issue/issue_nut04.rs +++ b/crates/cdk/src/mint/issue/issue_nut04.rs @@ -157,28 +157,6 @@ impl Mint { Ok(quotes) } - /// Get pending mint quotes - #[instrument(skip_all)] - pub async fn get_pending_mint_quotes(&self) -> Result, Error> { - let mint_quotes = self - .localstore - .get_mint_quotes_with_state(MintQuoteState::Pending) - .await?; - - Ok(mint_quotes) - } - - /// Get pending mint quotes - #[instrument(skip_all)] - pub async fn get_unpaid_mint_quotes(&self) -> Result, Error> { - let mint_quotes = self - .localstore - .get_mint_quotes_with_state(MintQuoteState::Unpaid) - .await?; - - Ok(mint_quotes) - } - /// Remove mint quote #[instrument(skip_all)] pub async fn remove_mint_quote(&self, quote_id: &Uuid) -> Result<(), Error> { diff --git a/crates/cdk/src/mint/start_up_check.rs b/crates/cdk/src/mint/start_up_check.rs index 4fe08bc0f..95f09467a 100644 --- a/crates/cdk/src/mint/start_up_check.rs +++ b/crates/cdk/src/mint/start_up_check.rs @@ -8,32 +8,6 @@ use crate::mint::{MeltQuote, MeltQuoteState, PaymentMethod}; use crate::types::PaymentProcessorKey; impl Mint { - /// Check the status of all pending and unpaid mint quotes in the mint db - /// with all the lighting backends. This check that any payments - /// received while the mint was offline are accounted for, and the wallet can mint associated ecash - pub async fn check_pending_mint_quotes(&self) -> Result<(), Error> { - let pending_quotes = self.get_pending_mint_quotes().await?; - let unpaid_quotes = self.get_unpaid_mint_quotes().await?; - - let all_quotes = [pending_quotes, unpaid_quotes].concat(); - - tracing::info!( - "There are {} pending and unpaid mint quotes.", - all_quotes.len() - ); - for mut quote in all_quotes.into_iter() { - tracing::debug!("Checking status of mint quote: {}", quote.id); - match self - .check_mint_quote_paid(self.localstore.begin_transaction().await?, &mut quote) - .await - { - Ok(tx) => tx.commit().await?, - Err(err) => tracing::error!("Could not check status of {}, {}", quote.id, err), - } - } - Ok(()) - } - /// Checks the states of melt quotes that are **PENDING** or **UNKNOWN** to the mint with the ln node pub async fn check_pending_melt_quotes(&self) -> Result<(), Error> { let melt_quotes = self.localstore.get_melt_quotes().await?; From d99f228acf20767878302eff38aa40ff5fbfb4a1 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Sun, 6 Jul 2025 10:53:23 +0100 Subject: [PATCH 011/321] chore: remove unused redb --- crates/cdk-mintd/Cargo.toml | 2 +- misc/itests.sh | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/crates/cdk-mintd/Cargo.toml b/crates/cdk-mintd/Cargo.toml index 384481907..47b9ee07a 100644 --- a/crates/cdk-mintd/Cargo.toml +++ b/crates/cdk-mintd/Cargo.toml @@ -20,7 +20,7 @@ lnbits = ["dep:cdk-lnbits"] fakewallet = ["dep:cdk-fake-wallet"] grpc-processor = ["dep:cdk-payment-processor", "cdk-signatory/grpc"] sqlcipher = ["cdk-sqlite/sqlcipher"] -# MSRV is not committed to with redb enabled +# MSRV is not committed to with swagger enabled swagger = ["cdk-axum/swagger", "dep:utoipa", "dep:utoipa-swagger-ui"] redis = ["cdk-axum/redis"] auth = ["cdk/auth", "cdk-sqlite/auth"] diff --git a/misc/itests.sh b/misc/itests.sh index cb8de230e..6465ca78d 100755 --- a/misc/itests.sh +++ b/misc/itests.sh @@ -109,7 +109,7 @@ export CDK_MINTD_MNEMONIC="eye survey guilt napkin crystal cup whisper salt lugg export RUST_BACKTRACE=1 echo "Starting cln mintd" -cargo run --bin cdk-mintd --features "redb" & +cargo run --bin cdk-mintd & export CDK_MINTD_PID=$! @@ -160,7 +160,7 @@ export CDK_MINTD_LN_BACKEND="lnd" export CDK_MINTD_MNEMONIC="cattle gold bind busy sound reduce tone addict baby spend february strategy" echo "Starting lnd mintd" -cargo run --bin cdk-mintd --features "redb" & +cargo run --bin cdk-mintd & export CDK_MINTD_LND_PID=$! URL="http://$CDK_ITESTS_MINT_ADDR:$CDK_ITESTS_MINT_PORT_1/v1/info" From 44ca7e48dc6148b104c3c2d635bd5d08af53447d Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Mon, 7 Jul 2025 13:53:05 +0100 Subject: [PATCH 012/321] feat: remove rexie --- README.md | 1 - crates/cdk-rexie/Cargo.toml | 27 -- crates/cdk-rexie/README.md | 35 -- crates/cdk-rexie/src/lib.rs | 10 - crates/cdk-rexie/src/wallet.rs | 751 --------------------------------- justfile | 3 - misc/justfile.custom.just | 2 - 7 files changed, 829 deletions(-) delete mode 100644 crates/cdk-rexie/Cargo.toml delete mode 100644 crates/cdk-rexie/README.md delete mode 100644 crates/cdk-rexie/src/lib.rs delete mode 100644 crates/cdk-rexie/src/wallet.rs diff --git a/README.md b/README.md index cffa1295b..f7ebae6d2 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,6 @@ The project is split up into several crates in the `crates/` directory: * [**cdk**](./crates/cdk/): Rust implementation of Cashu protocol. * [**cdk-sqlite**](./crates/cdk-sqlite/): SQLite Storage backend. * [**cdk-redb**](./crates/cdk-redb/): Redb Storage backend. - * [**cdk-rexie**](./crates/cdk-rexie/): Rexie Storage backend for browsers. * [**cdk-axum**](./crates/cdk-axum/): Axum webserver for mint. * [**cdk-cln**](./crates/cdk-cln/): CLN Lightning backend for mint. * [**cdk-lnd**](./crates/cdk-lnd/): Lnd Lightning backend for mint. diff --git a/crates/cdk-rexie/Cargo.toml b/crates/cdk-rexie/Cargo.toml deleted file mode 100644 index b3298de51..000000000 --- a/crates/cdk-rexie/Cargo.toml +++ /dev/null @@ -1,27 +0,0 @@ -[package] -name = "cdk-rexie" -version.workspace = true -edition.workspace = true -authors = ["CDK Developers"] -description = "Indexdb storage backend for CDK in the browser" -license.workspace = true -homepage = "https://github.com/cashubtc/cdk" -repository = "https://github.com/cashubtc/cdk.git" -rust-version.workspace = true # MSRV -readme = "README.md" - -# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html -[features] -default = ["wallet"] -wallet = ["cdk/wallet"] - -[dependencies] -rexie = "0.6.0" -cdk.workspace = true -async-trait.workspace = true -tokio.workspace = true -serde.workspace = true -serde_json.workspace = true -thiserror.workspace = true -serde-wasm-bindgen = "0.6.5" -web-sys = { version = "0.3.69", default-features = false, features = ["console"] } diff --git a/crates/cdk-rexie/README.md b/crates/cdk-rexie/README.md deleted file mode 100644 index 11920ba96..000000000 --- a/crates/cdk-rexie/README.md +++ /dev/null @@ -1,35 +0,0 @@ -# CDK Rexie - -[![crates.io](https://img.shields.io/crates/v/cdk-rexie.svg)](https://crates.io/crates/cdk-rexie) -[![Documentation](https://docs.rs/cdk-rexie/badge.svg)](https://docs.rs/cdk-rexie) -[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/cashubtc/cdk/blob/main/LICENSE) - -**ALPHA** This library is in early development, the API will change and should be used with caution. - -[Rexie](https://github.com/SaltyAom/rexie) (IndexedDB) storage backend implementation for the Cashu Development Kit (CDK). This provides browser-based storage for web applications. - -## Features - -This crate provides a Rexie-based storage implementation for browser environments: -- Wallet storage -- Transaction history -- Proof tracking -- IndexedDB persistence - -## Installation - -Add this to your `Cargo.toml`: - -```toml -[dependencies] -cdk-rexie = "*" -``` - - -## WASM Support - -This crate is specifically designed for use in WebAssembly environments and requires the `wasm32-unknown-unknown` target. - -## License - -This project is licensed under the [MIT License](../../LICENSE). \ No newline at end of file diff --git a/crates/cdk-rexie/src/lib.rs b/crates/cdk-rexie/src/lib.rs deleted file mode 100644 index fca5caad1..000000000 --- a/crates/cdk-rexie/src/lib.rs +++ /dev/null @@ -1,10 +0,0 @@ -//! Rexie Indexdb database - -#![warn(missing_docs)] -#![warn(rustdoc::bare_urls)] - -#[cfg(all(feature = "wallet", target_arch = "wasm32"))] -pub mod wallet; - -#[cfg(all(feature = "wallet", target_arch = "wasm32"))] -pub use wallet::WalletRexieDatabase; diff --git a/crates/cdk-rexie/src/wallet.rs b/crates/cdk-rexie/src/wallet.rs deleted file mode 100644 index 20b01895e..000000000 --- a/crates/cdk-rexie/src/wallet.rs +++ /dev/null @@ -1,751 +0,0 @@ -//! Rexie Browser Database - -use std::collections::{HashMap, HashSet}; -use std::rc::Rc; -use std::result::Result; - -use async_trait::async_trait; -use cdk::cdk_database::{self, WalletDatabase}; -use cdk::mint_url::MintUrl; -use cdk::nuts::{ - CurrencyUnit, Id, KeySetInfo, Keys, MintInfo, PublicKey, SpendingConditions, State, -}; -use cdk::types::ProofInfo; -use cdk::util::unix_time; -use cdk::wallet::{MeltQuote, MintQuote}; -use rexie::*; -use thiserror::Error; -use tokio::sync::Mutex; - -// Tables -const MINTS: &str = "mints"; -const MINT_KEYSETS: &str = "keysets_by_mint"; -const KEYSETS: &str = "keysets"; -const MINT_KEYS: &str = "mint_keys"; -const MINT_QUOTES: &str = "mint_quotes"; -const MELT_QUOTES: &str = "melt_quotes"; -const PROOFS: &str = "proofs"; -const CONFIG: &str = "config"; -const KEYSET_COUNTER: &str = "keyset_counter"; - -const DATABASE_VERSION: u32 = 4; - -/// Rexie Database Error -#[derive(Debug, Error)] -pub enum Error { - /// CDK Database Error - #[error(transparent)] - CDKDatabase(#[from] cdk::cdk_database::Error), - /// Rexie Error - #[error(transparent)] - Rexie(#[from] rexie::Error), - /// Serde Wasm Error - #[error(transparent)] - SerdeBindgen(#[from] serde_wasm_bindgen::Error), - /// NUT00 Error - #[error(transparent)] - NUT00(cdk::nuts::nut00::Error), - #[error("Not found")] - /// Not Found - NotFound, -} -impl From for cdk::cdk_database::Error { - fn from(e: Error) -> Self { - Self::Database(Box::new(e)) - } -} - -// These are okay because we never actually send across threads in the browser -unsafe impl Send for Error {} -unsafe impl Sync for Error {} - -/// Wallet Rexie Database -#[derive(Debug, Clone)] -pub struct WalletRexieDatabase { - db: Rc>, -} - -// These are okay because we never actually send across threads in the browser -unsafe impl Send for WalletRexieDatabase {} -unsafe impl Sync for WalletRexieDatabase {} - -impl WalletRexieDatabase { - /// Create new [`WalletRexieDatabase`] - pub async fn new() -> Result { - let rexie = Rexie::builder("cdk") - .version(DATABASE_VERSION) - .add_object_store( - ObjectStore::new(PROOFS) - .add_index(Index::new("y", "y").unique(true)) - .add_index(Index::new("mint_url", "mint_url")) - .add_index(Index::new("state", "state")) - .add_index(Index::new("unit", "unit")), - ) - .add_object_store( - ObjectStore::new(MINTS).add_index(Index::new("mint_url", "mint_url").unique(true)), - ) - .add_object_store(ObjectStore::new(MINT_KEYSETS)) - .add_object_store( - ObjectStore::new(KEYSETS) - .add_index(Index::new("keyset_id", "keyset_id").unique(true)), - ) - .add_object_store( - ObjectStore::new(MINT_KEYS) - .add_index(Index::new("keyset_id", "keyset_id").unique(true)), - ) - .add_object_store(ObjectStore::new(MINT_QUOTES)) - .add_object_store(ObjectStore::new(MELT_QUOTES)) - .add_object_store(ObjectStore::new(CONFIG)) - .add_object_store(ObjectStore::new(KEYSET_COUNTER)) - // Build the database - .build() - .await - .unwrap(); - - Ok(Self { - db: Rc::new(Mutex::new(rexie)), - }) - } - - async fn set_proof_states( - &self, - ys: Vec, - state: State, - ) -> Result<(), cdk_database::Error> { - let rexie = self.db.lock().await; - - let transaction = rexie - .transaction(&[PROOFS], TransactionMode::ReadWrite) - .map_err(Error::from)?; - - let proofs_store = transaction.store(PROOFS).map_err(Error::from)?; - - for y in ys { - let y = serde_wasm_bindgen::to_value(&y).map_err(Error::from)?; - - let mut proof: ProofInfo = proofs_store - .get(y.clone()) - .await - .map_err(Error::from)? - .and_then(|p| serde_wasm_bindgen::from_value(p).ok()) - .ok_or(Error::NotFound)?; - - proof.state = state; - - let proof = serde_wasm_bindgen::to_value(&proof).map_err(Error::from)?; - - proofs_store - .put(&proof, Some(&y)) - .await - .map_err(Error::from)?; - } - - transaction.done().await.map_err(Error::from)?; - - Ok(()) - } -} - -#[cfg_attr(target_arch = "wasm32", async_trait(?Send))] -#[cfg_attr(not(target_arch = "wasm32"), async_trait)] -impl WalletDatabase for WalletRexieDatabase { - type Err = cdk::cdk_database::Error; - - async fn add_mint( - &self, - mint_url: MintUrl, - mint_info: Option, - ) -> Result<(), Self::Err> { - let rexie = self.db.lock().await; - - let transaction = rexie - .transaction(&[MINTS], TransactionMode::ReadWrite) - .map_err(Error::from)?; - - let mints_store = transaction.store(MINTS).map_err(Error::from)?; - - let mint_url = serde_wasm_bindgen::to_value(&mint_url).map_err(Error::from)?; - let mint_info = serde_wasm_bindgen::to_value(&mint_info).map_err(Error::from)?; - - mints_store - .put(&mint_info, Some(&mint_url)) - .await - .map_err(Error::from)?; - - transaction.done().await.map_err(Error::from)?; - - Ok(()) - } - - async fn remove_mint(&self, mint_url: MintUrl) -> Result<(), Self::Err> { - let rexie = self.db.lock().await; - - let transaction = rexie - .transaction(&[MINTS], TransactionMode::ReadWrite) - .map_err(Error::from)?; - - let mints_store = transaction.store(MINTS).map_err(Error::from)?; - - let mint_url = serde_wasm_bindgen::to_value(&mint_url).map_err(Error::from)?; - - mints_store.delete(mint_url).await.map_err(Error::from)?; - - transaction.done().await.map_err(Error::from)?; - - Ok(()) - } - - async fn get_mint(&self, mint_url: MintUrl) -> Result, Self::Err> { - let rexie = self.db.lock().await; - - let transaction = rexie - .transaction(&[MINTS], TransactionMode::ReadOnly) - .map_err(Error::from)?; - - let mints_store = transaction.store(MINTS).map_err(Error::from)?; - - let mint_url = serde_wasm_bindgen::to_value(&mint_url).map_err(Error::from)?; - let mint_info = mints_store - .get(mint_url) - .await - .map_err(Error::from)? - .and_then(|m| serde_wasm_bindgen::from_value(m).ok()); - - Ok(mint_info) - } - - async fn get_mints(&self) -> Result>, Self::Err> { - let rexie = self.db.lock().await; - - let transaction = rexie - .transaction(&[MINTS], TransactionMode::ReadOnly) - .map_err(Error::from)?; - - let mints_store = transaction.store(MINTS).map_err(Error::from)?; - - let mints = mints_store - .scan(None, None, None, None) - .await - .map_err(Error::from)?; - - let mints: HashMap> = mints - .into_iter() - .map(|(url, info)| { - ( - serde_wasm_bindgen::from_value(url).unwrap(), - serde_wasm_bindgen::from_value(info).unwrap(), - ) - }) - .collect(); - - Ok(mints) - } - - async fn update_mint_url( - &self, - old_mint_url: MintUrl, - new_mint_url: MintUrl, - ) -> Result<(), Self::Err> { - let proofs = self - .get_proofs(Some(old_mint_url), None, None, None) - .await - .map_err(Error::from)?; - - let updated_proofs: Vec = proofs - .into_iter() - .map(|mut p| { - p.mint_url = new_mint_url.clone(); - p - }) - .collect(); - - if !updated_proofs.is_empty() { - self.update_proofs(updated_proofs, vec![]).await?; - } - - // Update mint quotes - { - let quotes = self.get_mint_quotes().await?; - - let unix_time = unix_time(); - - let quotes: Vec = quotes - .into_iter() - .filter_map(|mut q| { - if q.expiry < unix_time { - q.mint_url = new_mint_url.clone(); - Some(q) - } else { - None - } - }) - .collect(); - - for quote in quotes { - self.add_mint_quote(quote).await?; - } - } - - Ok(()) - } - - async fn add_mint_keysets( - &self, - mint_url: MintUrl, - keysets: Vec, - ) -> Result<(), Self::Err> { - let rexie = self.db.lock().await; - - let transaction = rexie - .transaction(&[MINT_KEYSETS, KEYSETS], TransactionMode::ReadWrite) - .map_err(Error::from)?; - - let mint_keysets_store = transaction.store(MINT_KEYSETS).map_err(Error::from)?; - let keysets_store = transaction.store(KEYSETS).map_err(Error::from)?; - - let mint_url = serde_wasm_bindgen::to_value(&mint_url).map_err(Error::from)?; - - let mut mint_keysets = mint_keysets_store - .get(mint_url.clone()) - .await - .map_err(Error::from)? - .and_then(|m| serde_wasm_bindgen::from_value(m).ok()); - - let new_keyset_ids: Vec = keysets.iter().map(|k| k.id).collect(); - - mint_keysets - .as_mut() - .unwrap_or(&mut HashSet::new()) - .extend(new_keyset_ids); - - let mint_keysets = serde_wasm_bindgen::to_value(&mint_keysets).map_err(Error::from)?; - - mint_keysets_store - .put(&mint_keysets, Some(&mint_url)) - .await - .map_err(Error::from)?; - - for keyset in keysets { - let id = serde_wasm_bindgen::to_value(&keyset.id).map_err(Error::from)?; - let keyset = serde_wasm_bindgen::to_value(&keyset).map_err(Error::from)?; - - keysets_store - .put(&keyset, Some(&id)) - .await - .map_err(Error::from)?; - } - - transaction.done().await.map_err(Error::from)?; - - Ok(()) - } - - async fn get_mint_keysets( - &self, - mint_url: MintUrl, - ) -> Result>, Self::Err> { - let rexie = self.db.lock().await; - - let transaction = rexie - .transaction(&[MINT_KEYSETS, KEYSETS], TransactionMode::ReadOnly) - .map_err(Error::from)?; - - let mints_store = transaction.store(MINT_KEYSETS).map_err(Error::from)?; - - let mint_url = serde_wasm_bindgen::to_value(&mint_url).map_err(Error::from)?; - let mint_keysets: Option> = mints_store - .get(mint_url) - .await - .map_err(Error::from)? - .and_then(|m| serde_wasm_bindgen::from_value(m).ok()); - - let keysets_store = transaction.store(KEYSETS).map_err(Error::from)?; - - let keysets = match mint_keysets { - Some(mint_keysets) => { - let mut keysets = vec![]; - - for mint_keyset in mint_keysets { - let id = serde_wasm_bindgen::to_value(&mint_keyset).map_err(Error::from)?; - - let keyset = keysets_store - .get(id) - .await - .map_err(Error::from)? - .and_then(|k| serde_wasm_bindgen::from_value(k).ok()); - - keysets.push(keyset); - } - - let keysets = keysets.iter().flatten().cloned().collect(); - - Some(keysets) - } - None => None, - }; - - transaction.done().await.map_err(Error::from)?; - - Ok(keysets) - } - - async fn get_keyset_by_id(&self, keyset_id: &Id) -> Result, Self::Err> { - let rexie = self.db.lock().await; - - let transaction = rexie - .transaction(&[KEYSETS], TransactionMode::ReadOnly) - .map_err(Error::from)?; - let keysets_store = transaction.store(KEYSETS).map_err(Error::from)?; - - let keyset_id = serde_wasm_bindgen::to_value(keyset_id).map_err(Error::from)?; - - let keyset = keysets_store - .get(keyset_id) - .await - .map_err(Error::from)? - .and_then(|k| serde_wasm_bindgen::from_value(k).ok()); - - Ok(keyset) - } - - async fn add_mint_quote(&self, quote: MintQuote) -> Result<(), Self::Err> { - let rexie = self.db.lock().await; - - let transaction = rexie - .transaction(&[MINT_QUOTES], TransactionMode::ReadWrite) - .map_err(Error::from)?; - - let quotes_store = transaction.store(MINT_QUOTES).map_err(Error::from)?; - - let quote_id = serde_wasm_bindgen::to_value("e.id).map_err(Error::from)?; - let quote = serde_wasm_bindgen::to_value("e).map_err(Error::from)?; - - quotes_store - .put("e, Some("e_id)) - .await - .map_err(Error::from)?; - - transaction.done().await.map_err(Error::from)?; - - Ok(()) - } - - async fn get_mint_quote(&self, quote_id: &str) -> Result, Self::Err> { - let rexie = self.db.lock().await; - - let transaction = rexie - .transaction(&[MINT_QUOTES], TransactionMode::ReadOnly) - .map_err(Error::from)?; - - let quotes_store = transaction.store(MINT_QUOTES).map_err(Error::from)?; - - let quote_id = serde_wasm_bindgen::to_value("e_id).map_err(Error::from)?; - let quote = quotes_store - .get(quote_id) - .await - .map_err(Error::from)? - .and_then(|q| serde_wasm_bindgen::from_value(q).ok()); - - Ok(quote) - } - - async fn get_mint_quotes(&self) -> Result, Self::Err> { - let rexie = self.db.lock().await; - - let transaction = rexie - .transaction(&[MINT_QUOTES], TransactionMode::ReadOnly) - .map_err(Error::from)?; - - let quotes_store = transaction.store(MINT_QUOTES).map_err(Error::from)?; - - let quotes = quotes_store - .scan(None, None, None, None) - .await - .map_err(Error::from)?; - - Ok(quotes - .into_iter() - .map(|(_id, q)| serde_wasm_bindgen::from_value(q)) - .collect::, serde_wasm_bindgen::Error>>() - .map_err(>::into)?) - } - - async fn remove_mint_quote(&self, quote_id: &str) -> Result<(), Self::Err> { - let rexie = self.db.lock().await; - - let transaction = rexie - .transaction(&[MINT_QUOTES], TransactionMode::ReadWrite) - .map_err(Error::from)?; - - let quotes_store = transaction.store(MINT_QUOTES).map_err(Error::from)?; - - let quote_id = serde_wasm_bindgen::to_value("e_id).map_err(Error::from)?; - - quotes_store.delete(quote_id).await.map_err(Error::from)?; - - transaction.done().await.map_err(Error::from)?; - - Ok(()) - } - - async fn add_melt_quote(&self, quote: MeltQuote) -> Result<(), Self::Err> { - let rexie = self.db.lock().await; - - let transaction = rexie - .transaction(&[MELT_QUOTES], TransactionMode::ReadWrite) - .map_err(Error::from)?; - - let quotes_store = transaction.store(MELT_QUOTES).map_err(Error::from)?; - - let quote_id = serde_wasm_bindgen::to_value("e.id).map_err(Error::from)?; - let quote = serde_wasm_bindgen::to_value("e).map_err(Error::from)?; - - quotes_store - .put("e, Some("e_id)) - .await - .map_err(Error::from)?; - - transaction.done().await.map_err(Error::from)?; - - Ok(()) - } - - async fn get_melt_quote(&self, quote_id: &str) -> Result, Self::Err> { - let rexie = self.db.lock().await; - - let transaction = rexie - .transaction(&[MELT_QUOTES], TransactionMode::ReadOnly) - .map_err(Error::from)?; - - let quotes_store = transaction.store(MELT_QUOTES).map_err(Error::from)?; - - let quote_id = serde_wasm_bindgen::to_value("e_id).map_err(Error::from)?; - let quote = quotes_store - .get(quote_id) - .await - .map_err(Error::from)? - .and_then(|q| serde_wasm_bindgen::from_value(q).ok()); - - Ok(quote) - } - - async fn remove_melt_quote(&self, quote_id: &str) -> Result<(), Self::Err> { - let rexie = self.db.lock().await; - - let transaction = rexie - .transaction(&[MELT_QUOTES], TransactionMode::ReadWrite) - .map_err(Error::from)?; - - let quotes_store = transaction.store(MELT_QUOTES).map_err(Error::from)?; - - let quote_id = serde_wasm_bindgen::to_value("e_id).map_err(Error::from)?; - - quotes_store.delete(quote_id).await.map_err(Error::from)?; - - transaction.done().await.map_err(Error::from)?; - - Ok(()) - } - - async fn add_keys(&self, keyset: KeySet) -> Result<(), Self::Err> { - // Verify ID by recomputing id - keyset.verify_id()?; - - let rexie = self.db.lock().await; - - let transaction = rexie - .transaction(&[MINT_KEYS], TransactionMode::ReadWrite) - .map_err(Error::from)?; - - let keys_store = transaction.store(MINT_KEYS).map_err(Error::from)?; - - let keyset_id = serde_wasm_bindgen::to_value(&keyset.id).map_err(Error::from)?; - let keys = serde_wasm_bindgen::to_value(&keys).map_err(Error::from)?; - - keys_store - .put(&keys, Some(&keyset_id)) - .await - .map_err(Error::from)?; - - transaction.done().await.map_err(Error::from)?; - - Ok(()) - } - - async fn get_keys(&self, id: &Id) -> Result, Self::Err> { - let rexie = self.db.lock().await; - - let transaction = rexie - .transaction(&[MINT_KEYS], TransactionMode::ReadOnly) - .map_err(Error::from)?; - - let keys_store = transaction.store(MINT_KEYS).map_err(Error::from)?; - - let keyset_id = serde_wasm_bindgen::to_value(id).map_err(Error::from)?; - let keys = keys_store - .get(keyset_id) - .await - .map_err(Error::from)? - .and_then(|k| serde_wasm_bindgen::from_value(k).ok()); - - Ok(keys) - } - - async fn remove_keys(&self, id: &Id) -> Result<(), Self::Err> { - let rexie = self.db.lock().await; - - let transaction = rexie - .transaction(&[MINT_KEYS], TransactionMode::ReadWrite) - .map_err(Error::from)?; - - let keys_store = transaction.store(MINT_KEYS).map_err(Error::from)?; - - let keyset_id = serde_wasm_bindgen::to_value(id).map_err(Error::from)?; - keys_store.delete(keyset_id).await.map_err(Error::from)?; - - Ok(()) - } - - async fn update_proofs( - &self, - added: Vec, - removed_ys: Vec, - ) -> Result<(), Self::Err> { - let rexie = self.db.lock().await; - - let transaction = rexie - .transaction(&[PROOFS], TransactionMode::ReadWrite) - .map_err(Error::from)?; - - let proofs_store = transaction.store(PROOFS).map_err(Error::from)?; - - for proof in added { - let y = serde_wasm_bindgen::to_value(&proof.y).map_err(Error::from)?; - let proof = serde_wasm_bindgen::to_value(&proof).map_err(Error::from)?; - - proofs_store - .put(&proof, Some(&y)) - .await - .map_err(Error::from)?; - } - - for y in removed_ys { - let y = serde_wasm_bindgen::to_value(&y).map_err(Error::from)?; - - proofs_store.delete(y).await.map_err(Error::from)?; - } - - transaction.done().await.map_err(Error::from)?; - - Ok(()) - } - - async fn set_pending_proofs(&self, ys: Vec) -> Result<(), Self::Err> { - self.set_proof_states(ys, State::Pending).await - } - - async fn reserve_proofs(&self, ys: Vec) -> Result<(), Self::Err> { - self.set_proof_states(ys, State::Reserved).await - } - - async fn set_unspent_proofs(&self, ys: Vec) -> Result<(), Self::Err> { - self.set_proof_states(ys, State::Unspent).await - } - - async fn get_proofs( - &self, - mint_url: Option, - unit: Option, - state: Option>, - spending_conditions: Option>, - ) -> Result, Self::Err> { - let rexie = self.db.lock().await; - - let transaction = rexie - .transaction(&[PROOFS], TransactionMode::ReadOnly) - .map_err(Error::from)?; - - let proofs_store = transaction.store(PROOFS).map_err(Error::from)?; - - let proofs = proofs_store - .scan(None, None, None, None) - .await - .map_err(Error::from)?; - - let proofs: Vec = proofs - .into_iter() - .filter_map(|(_k, v)| { - let mut proof = None; - - if let Ok(proof_info) = serde_wasm_bindgen::from_value::(v) { - proof = match proof_info.matches_conditions( - &mint_url, - &unit, - &state, - &spending_conditions, - ) { - true => Some(proof_info), - false => None, - }; - } - - proof - }) - .collect(); - - transaction.done().await.map_err(Error::from)?; - - Ok(proofs) - } - - async fn increment_keyset_counter(&self, keyset_id: &Id, count: u32) -> Result<(), Self::Err> { - let rexie = self.db.lock().await; - - let transaction = rexie - .transaction(&[KEYSET_COUNTER], TransactionMode::ReadWrite) - .map_err(Error::from)?; - - let counter_store = transaction.store(KEYSET_COUNTER).map_err(Error::from)?; - - let keyset_id = serde_wasm_bindgen::to_value(keyset_id).map_err(Error::from)?; - - let current_count: Option = counter_store - .get(keyset_id.clone()) - .await - .map_err(Error::from)? - .and_then(|c| serde_wasm_bindgen::from_value(c).ok()); - - let new_count = current_count.unwrap_or_default() + count; - - let new_count = serde_wasm_bindgen::to_value(&new_count).map_err(Error::from)?; - - counter_store - .put(&new_count, Some(&keyset_id)) - .await - .map_err(Error::from)?; - - transaction.done().await.map_err(Error::from)?; - - Ok(()) - } - - async fn get_keyset_counter(&self, keyset_id: &Id) -> Result, Self::Err> { - let rexie = self.db.lock().await; - - let transaction = rexie - .transaction(&[KEYSET_COUNTER], TransactionMode::ReadWrite) - .map_err(Error::from)?; - - let counter_store = transaction.store(KEYSET_COUNTER).map_err(Error::from)?; - - let keyset_id = serde_wasm_bindgen::to_value(keyset_id).map_err(Error::from)?; - - let current_count = counter_store - .get(keyset_id) - .await - .map_err(Error::from)? - .and_then(|c| serde_wasm_bindgen::from_value(c).ok()); - - Ok(current_count) - } -} diff --git a/justfile b/justfile index fbf3b9c13..7e0cdf1c1 100644 --- a/justfile +++ b/justfile @@ -192,7 +192,6 @@ release m="": "-p cdk-redb" "-p cdk-signatory" "-p cdk" - "-p cdk-rexie" "-p cdk-axum" "-p cdk-mint-rpc" "-p cdk-cln" @@ -221,7 +220,6 @@ check-docs: "-p cdk-redb" "-p cdk-sqlite" "-p cdk-axum" - "-p cdk-rexie" "-p cdk-cln" "-p cdk-lnd" "-p cdk-lnbits" @@ -249,7 +247,6 @@ docs-strict: "-p cdk-redb" "-p cdk-sqlite" "-p cdk-axum" - "-p cdk-rexie" "-p cdk-cln" "-p cdk-lnd" "-p cdk-lnbits" diff --git a/misc/justfile.custom.just b/misc/justfile.custom.just index f86eb180e..c085c1ea6 100644 --- a/misc/justfile.custom.just +++ b/misc/justfile.custom.just @@ -72,7 +72,6 @@ release m="": "-p cdk" "-p cdk-redb" "-p cdk-sqlite" - "-p cdk-rexie" "-p cdk-axum" "-p cdk-mint-rpc" "-p cdk-cln" @@ -100,7 +99,6 @@ check-docs: "-p cdk-redb" "-p cdk-sqlite" "-p cdk-axum" - "-p cdk-rexie" "-p cdk-cln" "-p cdk-lnd" "-p cdk-lnbits" From 4028824b1ac3d2f163a20e24004796438243d082 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Tue, 8 Jul 2025 10:48:22 +0100 Subject: [PATCH 013/321] feat: mprocs regtest --- MINT_RESTART_FEATURE.md | 86 ++++++ MPROCS_INTEGRATION.md | 147 ++++++++++ MPROCS_MODES.md | 132 +++++++++ REGTEST_QUICKSTART.md | 125 +++++++++ flake.nix | 3 +- justfile | 67 +++++ misc/README.md | 218 +++++++++++++++ misc/interactive_regtest.sh | 330 ++++++++++++++++++++++ misc/interactive_regtest_mprocs.sh | 320 ++++++++++++++++++++++ misc/regtest_helper.sh | 421 +++++++++++++++++++++++++++++ 10 files changed, 1848 insertions(+), 1 deletion(-) create mode 100644 MINT_RESTART_FEATURE.md create mode 100644 MPROCS_INTEGRATION.md create mode 100644 MPROCS_MODES.md create mode 100644 REGTEST_QUICKSTART.md create mode 100644 misc/README.md create mode 100755 misc/interactive_regtest.sh create mode 100755 misc/interactive_regtest_mprocs.sh create mode 100755 misc/regtest_helper.sh diff --git a/MINT_RESTART_FEATURE.md b/MINT_RESTART_FEATURE.md new file mode 100644 index 000000000..0a6180a35 --- /dev/null +++ b/MINT_RESTART_FEATURE.md @@ -0,0 +1,86 @@ +# Mint Restart Feature + +A new command has been added to restart the CDK mints after recompiling, perfect for development workflows when you're making changes to the mint code. + +## Command + +```bash +just restart-mints +``` + +or + +```bash +./misc/regtest_helper.sh restart-mints +``` + +## What It Does + +1. **Stops** both running mints (CLN and LND mints) +2. **Recompiles** the `cdk-mintd` binary with your latest changes +3. **Restarts** both mints with the same configuration +4. **Waits** for both mints to be ready and responding +5. **Updates** the state file with new process IDs + +## Development Workflow + +### Before this feature: +```bash +# Terminal 1: Start environment +just regtest + +# Terminal 2: Make code changes, then manually restart everything +# Ctrl+C in Terminal 1 (stops entire environment including Lightning network) +just regtest # Start everything again (slow) +``` + +### With this feature: +```bash +# Terminal 1: Start environment (once) +just regtest + +# Terminal 2: Make code changes, then quickly restart just the mints +just restart-mints # Fast! Keeps Lightning network running +just mint-test # Test your changes +``` + +## Benefits + +1. **Faster Development Cycle** - No need to restart the entire Lightning network +2. **Preserves Network State** - Bitcoin blockchain, Lightning channels, and node states remain intact +3. **Automatic Recompilation** - No need to manually run `cargo build` +4. **Status Validation** - Ensures mints are responding before completing +5. **State Management** - Updates process IDs for other commands to work correctly + +## Example Output + +``` +=============================== +Restarting CDK Mints +=============================== +Stopping existing mints... + Stopping CLN Mint (PID: 12345) + Stopping LND Mint (PID: 12346) +Recompiling cdk-mintd... +✓ Compilation successful +Starting CLN Mint... +Waiting for CLN mint to start... +✓ CLN Mint ready +Starting LND Mint... +Waiting for LND mint to start... +✓ LND Mint ready + +✅ Mints restarted successfully! + CLN Mint: http://127.0.0.1:8085 (PID: 54321) + LND Mint: http://127.0.0.1:8087 (PID: 54322) +=============================== +``` + +## Use Cases + +- **Testing mint code changes** without restarting the entire regtest environment +- **Debugging mint behavior** with fresh mint instances +- **Performance testing** with clean mint state but preserved Lightning network +- **Integration testing** after mint code modifications + +This feature makes the development experience much smoother when working on CDK mint functionality! diff --git a/MPROCS_INTEGRATION.md b/MPROCS_INTEGRATION.md new file mode 100644 index 000000000..79aee0fe7 --- /dev/null +++ b/MPROCS_INTEGRATION.md @@ -0,0 +1,147 @@ +# mprocs Integration for CDK Regtest + +The CDK regtest environment now integrates with `mprocs` to provide a beautiful TUI (Terminal User Interface) for monitoring all component logs in real-time. + +## What is mprocs? + +`mprocs` is a TUI for running multiple processes and monitoring their output. Perfect for development environments where you need to watch logs from multiple services simultaneously. + +## Features + +### Automatic Setup +- The regtest script checks for `mprocs` and offers to install it if missing +- Creates a dynamic mprocs configuration with all relevant log files +- Handles missing log files gracefully (waits for them to be created) + +### Components Monitored +- **cln-mint**: CDK mint connected to CLN +- **lnd-mint**: CDK mint connected to LND +- **bitcoind**: Bitcoin regtest node +- **cln-one**: Core Lightning node #1 +- **cln-two**: Core Lightning node #2 +- **lnd-one**: LND node #1 +- **lnd-two**: LND node #2 + +### Key Benefits +- **Real-time log monitoring** for all components +- **Side-by-side view** of related services +- **Easy navigation** between different logs +- **Scrollback** to review history +- **Search functionality** within logs +- **Process management** (start/stop/restart individual processes) + +## Usage + +### Automatic (Recommended) - Log Tailing Mode +```bash +just regtest +# After setup completes, mprocs launches automatically +# Mints start and log to files, mprocs shows log contents +``` + +### Direct Process Management Mode +```bash +just regtest-mprocs +# After setup, mprocs starts with mint processes stopped +# Use 's' key to start individual mints +# Full process control from within mprocs +``` + +### Manual Launch +```bash +# Start environment without mprocs +just regtest + +# In another terminal, launch mprocs +just regtest-logs +``` + +### Commands Available +```bash +just regtest # Starts environment and mprocs (log tailing mode) +just regtest-mprocs # Starts environment with direct process management +just regtest-logs # Manual mprocs launch (adapts to current mode) +``` + +## mprocs Controls + +### Direct Process Management Mode: +- **Arrow keys**: Navigate between processes +- **s**: Start the selected process +- **k**: Kill the selected process +- **r**: Restart the selected process +- **Enter**: Focus on selected process +- **Tab**: Switch between process list and log view +- **?**: Show help +- **q**: Quit mprocs (stops all managed processes) + +### Log Tailing Mode: +- **Arrow keys**: Navigate between processes +- **Enter**: Focus on selected process +- **Tab**: Switch between process list and log view +- **PageUp/PageDown**: Scroll through logs +- **Ctrl+C**: Interrupt current process +- **q**: Quit mprocs (processes continue running) + +## Installation + +If `mprocs` is not installed: +```bash +# Automatic installation prompt when running regtest +just regtest + +# Manual installation +cargo install mprocs + +# Or via package manager (varies by OS) +# Ubuntu/Debian: apt install mprocs +# macOS: brew install mprocs +``` + +## Configuration + +The mprocs configuration is automatically generated at `$CDK_ITESTS_DIR/mprocs.yaml`. It includes: + +- Proper log file paths for all components +- Graceful handling of missing files +- Optimized UI settings for development +- Auto-start for all monitoring processes + +## Development Workflow + +### Before mprocs: +- Start regtest environment +- Open multiple terminals to `tail -f` different log files +- Manually manage multiple windows/panes +- Switch between terminals to see different components + +### With mprocs: +- Start regtest environment → automatic log monitoring +- Single TUI shows all component logs +- Easy navigation between components +- Professional development experience + +## Example View + +``` +┌─Processes─────────┬─Output───────────────────────────────────────┐ +│ ● cln-mint │ 2024-07-08T08:30:12 INFO cdk_mintd: Starting │ +│ ● lnd-mint │ mint server on 127.0.0.1:8085 │ +│ ● bitcoind │ 2024-07-08T08:30:13 INFO: New invoice │ +│ ● cln-one │ received for 1000 sats │ +│ ● cln-two │ 2024-07-08T08:30:14 INFO: Payment │ +│ ● lnd-one │ successful │ +│ ● lnd-two │ │ +│ │ │ +└───────────────────┴──────────────────────────────────────────────┘ +``` + +## Fallback + +If mprocs is not available or fails: +- Environment continues to work normally +- Falls back to simple wait loop +- All `just` commands work as expected +- Logs still accessible via `just regtest-logs` + +This integration makes CDK development much more pleasant by providing professional-grade log monitoring out of the box! 🎉 diff --git a/MPROCS_MODES.md b/MPROCS_MODES.md new file mode 100644 index 000000000..06faea0ef --- /dev/null +++ b/MPROCS_MODES.md @@ -0,0 +1,132 @@ +# mprocs Process Management Modes + +The CDK regtest environment now supports two different modes for managing processes with mprocs: + +## Mode 1: Log Tailing (Default) +**Command**: `just regtest` + +### How it works: +- Mints are started by the bash script and run in the background +- Mints write their output to log files (`mintd.log`) +- mprocs uses `tail -f` to follow these log files +- Log files persist even after mprocs exits + +### Pros: +- ✅ Log files are preserved for later analysis +- ✅ Simple setup +- ✅ Works even if mprocs crashes + +### Cons: +- ❌ Cannot restart mints from within mprocs +- ❌ Must use external commands to control mints +- ❌ mprocs shows file contents, not live processes + +## Mode 2: Direct Process Management +**Command**: `just regtest-mprocs` + +### How it works: +- mprocs directly manages the mint processes +- Mints are started/stopped by mprocs itself +- Output goes directly to mprocs (no log files by default) +- Full process control from within mprocs + +### Pros: +- ✅ Start/stop/restart mints directly from mprocs +- ✅ Live process output +- ✅ Better development workflow +- ✅ Process status indicators + +### Cons: +- ❌ Output not saved to files (unless configured) +- ❌ If mprocs crashes, you lose the processes + +## mprocs Controls + +### Direct Process Management Mode: +- **Arrow keys**: Navigate between processes +- **s**: Start the selected process +- **k**: Kill the selected process +- **r**: Restart the selected process +- **Enter**: Focus on a process (see its output) +- **Tab**: Switch between process list and output +- **?**: Show help +- **q**: Quit mprocs (stops all managed processes) + +### Log Tailing Mode: +- **Arrow keys**: Navigate between log sources +- **Enter**: Focus on a log source +- **Tab**: Switch between process list and log view +- **PageUp/PageDown**: Scroll through logs +- **q**: Quit mprocs (processes continue running) + +## Usage Examples + +### Start with Log Tailing (Original Mode) +```bash +just regtest +# Mints start automatically and log to files +# mprocs shows log contents +# Use Ctrl+C or 'q' to exit mprocs +# Processes continue running in background +``` + +### Start with Direct Process Management +```bash +just regtest-mprocs +# Only Lightning network starts automatically +# In mprocs, navigate to "cln-mint" and press 's' to start it +# Navigate to "lnd-mint" and press 's' to start it +# Use 'r' to restart mints after code changes +# Use 'q' to exit and stop all processes +``` + +### Switch Between Modes + +If you started with log tailing mode, you can access the direct management: +```bash +# In another terminal +source /tmp/cdk_regtest_env +just regtest-logs # This will detect the mode and adapt +``` + +## Development Workflow Comparison + +### Traditional (Log Tailing): +1. `just regtest` +2. Make code changes +3. In another terminal: `just restart-mints` +4. Check logs in mprocs + +### Direct Management: +1. `just regtest-mprocs` +2. Press 's' to start mints +3. Make code changes +4. In mprocs: press 'r' on each mint to restart +5. Watch live output directly + +## Technical Details + +### Project Root Handling +The direct process management mode ensures that: +- Startup scripts change to the correct project root directory +- Cargo commands run from where the `Cargo.toml` file is located +- Environment variables are properly set before starting processes + +### File Structure +``` +$CDK_ITESTS_DIR/ +├── start_cln_mint.sh # Sets PROJECT_ROOT and runs cargo from there +├── start_lnd_mint.sh # Sets PROJECT_ROOT and runs cargo from there +└── mprocs.yaml # Points to the startup scripts +``` + +Each startup script: +1. Changes to the project root directory (`cd "$PROJECT_ROOT"`) +2. Sets all required environment variables +3. Executes `cargo run --bin cdk-mintd` from the correct location + +The environment variables and helper commands work the same in both modes: +- `just ln-cln1 getinfo` +- `just btc-mine 5` +- `just mint-info` +- etc. diff --git a/REGTEST_QUICKSTART.md b/REGTEST_QUICKSTART.md new file mode 100644 index 000000000..f02bedf67 --- /dev/null +++ b/REGTEST_QUICKSTART.md @@ -0,0 +1,125 @@ +# CDK Interactive Regtest - Quick Start + +A simple guide to get up and running with the interactive regtest environment. + +## Start Environment + +```bash +# Terminal 1: Start regtest with default sqlite database +just regtest + +# Or with redb database +just regtest redb +``` + +The script will: +1. Check for `mprocs` and offer to install it if missing +2. Set up the regtest environment (Bitcoin + Lightning nodes + CDK mints) +3. Launch `mprocs` showing logs from all components +4. Press 'q' in mprocs to quit and stop the environment + +## Use Lightning Nodes (in any other terminal) + +The `just` commands work from any terminal - they automatically find the running environment. + +### Get Node Information +```bash +just ln-cln1 getinfo # CLN node 1 +just ln-cln2 getinfo # CLN node 2 +just ln-lnd1 getinfo # LND node 1 +just ln-lnd2 getinfo # LND node 2 +``` + +### Create and Pay Invoices +```bash +# Create 1000 sat invoice on CLN +just ln-cln1 invoice 1000 test_label "Test payment" + +# Pay invoice with LND (use the bolt11 from above) +just ln-lnd1 payinvoice lnbcrt10u1... + +# Check balances +just ln-cln1 listfunds +just ln-lnd1 listchannels +``` + +## Bitcoin Operations + +```bash +just btc getblockchaininfo # Blockchain status +just btc getbalance # Wallet balance +just btc-mine 5 # Mine 5 blocks +``` + +## CDK Mint Operations + +```bash +just mint-info # Show both mints' info +just mint-test # Run integration tests +just restart-mints # Stop, recompile, and restart mints +just regtest-status # Check all components +just regtest-logs # Show recent logs +just regtest-mprocs # Start mprocs TUI (if not already running) +``` + +## Stop Environment + +Press `Ctrl+C` in the terminal running `just regtest`. Everything will be cleaned up automatically. + +## Available Endpoints + +- **CLN Mint**: http://127.0.0.1:8085 +- **LND Mint**: http://127.0.0.1:8087 +- **Bitcoin RPC**: 127.0.0.1:18443 (testuser/testpass) + +## Common Workflows + +### Test Lightning Payment Flow +```bash +# Terminal 1 +just regtest + +# Terminal 2 +just ln-cln1 invoice 1000 test "Test payment" +# Copy the bolt11 invoice + +just ln-lnd1 payinvoice +just ln-cln1 listinvoices +just ln-lnd1 listpayments +``` + +### Test CDK Integration +```bash +# Terminal 1 +just regtest + +# Terminal 2 +just mint-test # Run all tests +cargo test -p cdk-integration-tests # Or specific tests +``` + +### Development with CDK CLI +```bash +# Terminal 1 +just regtest + +# Terminal 2 - use environment variables +echo $CDK_TEST_MINT_URL # CLN mint URL +echo $CDK_TEST_MINT_URL_2 # LND mint URL + +# Use with CDK CLI +cargo run --bin cdk-cli -- --mint-url $CDK_TEST_MINT_URL mint-info +``` + +### Development Workflow (Mint Code Changes) +```bash +# Terminal 1: Keep regtest running +just regtest + +# Terminal 2: Make changes to mint code, then +just restart-mints # Recompiles and restarts both mints +just mint-info # Test the changes +just mint-test # Run integration tests +``` + +That's it! The environment provides a full Lightning Network with CDK mints for testing and development. diff --git a/flake.nix b/flake.nix index 311f5307e..20def6318 100644 --- a/flake.nix +++ b/flake.nix @@ -81,6 +81,7 @@ bitcoind sqlx-cli cargo-outdated + mprocs # Needed for github ci libz @@ -274,7 +275,7 @@ echo "Docker is available at $(which docker)" echo "Docker version: $(docker --version)" ''; - buildInputs = buildInputs ++ [ + buildInputs = buildInputs ++ [ stable_toolchain pkgs.docker-client ]; diff --git a/justfile b/justfile index fbf3b9c13..7c403f97f 100644 --- a/justfile +++ b/justfile @@ -153,6 +153,73 @@ nutshell-wallet-itest: #!/usr/bin/env bash ./misc/nutshell_wallet_itest.sh +# Start interactive regtest environment (Bitcoin + 4 LN nodes + 2 CDK mints) +regtest db="sqlite": + #!/usr/bin/env bash + ./misc/interactive_regtest.sh {{db}} + +# Start regtest with direct process management via mprocs (lets you start/stop mints) +regtest-mprocs db="sqlite": + #!/usr/bin/env bash + ./misc/interactive_regtest_mprocs.sh {{db}} + +# Lightning Network Commands (require regtest environment to be running) + +# Get CLN node 1 info +ln-cln1 *ARGS: + #!/usr/bin/env bash + ./misc/regtest_helper.sh ln-cln1 {{ARGS}} + +# Get CLN node 2 info +ln-cln2 *ARGS: + #!/usr/bin/env bash + ./misc/regtest_helper.sh ln-cln2 {{ARGS}} + +# Get LND node 1 info +ln-lnd1 *ARGS: + #!/usr/bin/env bash + ./misc/regtest_helper.sh ln-lnd1 {{ARGS}} + +# Get LND node 2 info +ln-lnd2 *ARGS: + #!/usr/bin/env bash + ./misc/regtest_helper.sh ln-lnd2 {{ARGS}} + +# Bitcoin regtest commands +btc *ARGS: + #!/usr/bin/env bash + ./misc/regtest_helper.sh btc {{ARGS}} + +# Mine blocks in regtest +btc-mine blocks="10": + #!/usr/bin/env bash + ./misc/regtest_helper.sh btc-mine {{blocks}} + +# Show mint information +mint-info: + #!/usr/bin/env bash + ./misc/regtest_helper.sh mint-info + +# Run integration tests against regtest environment +mint-test: + #!/usr/bin/env bash + ./misc/regtest_helper.sh mint-test + +# Restart mints after recompiling (useful for development) +restart-mints: + #!/usr/bin/env bash + ./misc/regtest_helper.sh restart-mints + +# Show regtest environment status +regtest-status: + #!/usr/bin/env bash + ./misc/regtest_helper.sh show-status + +# Show regtest environment logs +regtest-logs: + #!/usr/bin/env bash + ./misc/regtest_helper.sh show-logs + run-examples: cargo r --example p2pk cargo r --example mint-token diff --git a/misc/README.md b/misc/README.md new file mode 100644 index 000000000..51b19c358 --- /dev/null +++ b/misc/README.md @@ -0,0 +1,218 @@ +# CDK Interactive Regtest Environment + +This directory contains scripts for setting up and interacting with a CDK regtest environment for development and testing. + +## Scripts + +### 1. `interactive_regtest.sh` +Sets up a complete regtest environment with: +- Bitcoin regtest node +- 2 CLN (Core Lightning) nodes with channels +- 2 LND nodes with channels +- 2 CDK mint instances (one connected to CLN, one to LND) + +Unlike `itests.sh`, this script keeps the environment running for interactive use and creates a state file (`/tmp/cdk_regtest_env`) that allows other terminal sessions to find and interact with the environment. + +### 2. `regtest_helper.sh` +Helper script providing convenient commands to interact with the running regtest environment. Automatically detects the environment using the state file. + +## Quick Start + +### Using `just` (Recommended) + +1. **Start the regtest environment:** + ```bash + just regtest [database_type] + ``` + - `database_type`: Optional, defaults to "sqlite". Can be "sqlite" or "redb" + - The script will check for `mprocs` and offer to install it if missing + - After setup, it will launch `mprocs` showing logs from all nodes and mints + - Press 'q' in mprocs to quit and stop the environment + +2. **In another terminal, interact with Lightning nodes:** + ```bash + # Get node information + just ln-cln1 getinfo + just ln-lnd1 getinfo + + # Mine some blocks + just btc-mine 5 + + # Check mint status + just mint-info + + # Start mprocs log viewer in another terminal + just regtest-mprocs + + # See all available commands + just --list + ``` + +### Using Scripts Directly + +1. **Start the regtest environment:** + ```bash + ./misc/interactive_regtest.sh [database_type] + ``` + - `database_type`: Optional, defaults to "sqlite". Can be "sqlite" or "redb" + - The script will build necessary binaries and set up the full environment + - Keep this terminal open - the environment runs until you press Ctrl+C + +2. **In another terminal, use the helper script:** + ```bash + ./misc/regtest_helper.sh help + ``` + +## How It Works + +The interactive regtest environment uses a state file (`/tmp/cdk_regtest_env`) to share environment information between terminal sessions: + +1. When you run `just regtest` or `./misc/interactive_regtest.sh`, it creates the state file with all necessary environment variables +2. When you run Lightning node commands in other terminals (e.g., `just ln-cln1 getinfo`), the helper script automatically sources the state file +3. When the environment shuts down (Ctrl+C), it cleans up the state file automatically + +This allows you to use `just` commands from any terminal without needing to export environment variables manually. + +## Environment Details + +When running, the environment provides: + +### Network Endpoints +- **Bitcoin RPC**: `127.0.0.1:18443` (user: `testuser`, pass: `testpass`) +- **CLN Node 1**: Unix socket at `$CDK_ITESTS_DIR/cln/one/regtest/lightning-rpc` +- **CLN Node 2**: Unix socket at `$CDK_ITESTS_DIR/cln/two/regtest/lightning-rpc` +- **LND Node 1**: HTTPS on `localhost:10009` +- **LND Node 2**: HTTPS on `localhost:10010` + +### CDK Mints +- **CLN Mint**: `http://127.0.0.1:8085` (connected to CLN node 1) +- **LND Mint**: `http://127.0.0.1:8087` (connected to LND node 2) + +### Environment Variables +The following variables are exported for easy access: +- `CDK_TEST_MINT_URL`: CLN mint URL +- `CDK_TEST_MINT_URL_2`: LND mint URL +- `CDK_ITESTS_DIR`: Temporary directory with all data + +## Usage Examples + +### Using `just` Commands (Recommended) + +```bash +# Start the environment +just regtest + +# In another terminal: +# Get Lightning node info +just ln-cln1 getinfo +just ln-cln2 getinfo +just ln-lnd1 getinfo +just ln-lnd2 getinfo + +# Create and pay invoices +just ln-cln1 invoice 1000 label description +just ln-lnd1 payinvoice + +# Bitcoin operations +just btc getblockchaininfo +just btc-mine 10 +just btc getbalance + +# CDK operations +just mint-info +just mint-test +just restart-mints # Stop, recompile, and restart mints +just regtest-status +just regtest-logs # Show recent logs +just regtest-mprocs # Start mprocs TUI log viewer +``` + +### Using Helper Script Directly + +```bash +# Lightning Node Operations +./misc/regtest_helper.sh ln-cln1 getinfo +./misc/regtest_helper.sh ln-lnd1 getinfo +./misc/regtest_helper.sh ln-cln1 invoice 1000 label description +./misc/regtest_helper.sh ln-lnd1 payinvoice + +# Bitcoin Operations +./misc/regtest_helper.sh btc getblockchaininfo +./misc/regtest_helper.sh btc-mine 10 +./misc/regtest_helper.sh btc getbalance + +# CDK Mint Operations +./misc/regtest_helper.sh mint-info +./misc/regtest_helper.sh mint-test +./misc/regtest_helper.sh restart-mints +./misc/regtest_helper.sh show-status +``` + +### Legacy Examples (for reference) + +### Direct API Access +```bash +# Query mint info directly +curl http://127.0.0.1:8085/v1/info | jq + +# Get mint keysets +curl http://127.0.0.1:8085/v1/keysets | jq +``` + +### Development Workflow +```bash +# Terminal 1: Start environment +just regtest + +# Terminal 2: Development and testing +just ln-cln1 getinfo # Check CLN status +just mint-info # Check mint status +just mint-test # Run integration tests + +# Or use CDK CLI tools directly with the mint URLs +# The environment sets CDK_TEST_MINT_URL and CDK_TEST_MINT_URL_2 +cargo run --bin cdk-cli -- --mint-url $CDK_TEST_MINT_URL mint-info +``` + +## File Locations + +All files are stored in a temporary directory (`$CDK_ITESTS_DIR`): +``` +$CDK_ITESTS_DIR/ +├── bitcoin/ # Bitcoin regtest data +├── cln/ +│ ├── one/ # CLN node 1 data +│ └── two/ # CLN node 2 data +├── lnd/ +│ ├── one/ # LND node 1 data +│ │ ├── tls.cert +│ │ └── data/chain/bitcoin/regtest/admin.macaroon +│ └── two/ # LND node 2 data +│ ├── tls.cert +│ └── data/chain/bitcoin/regtest/admin.macaroon +├── cln_mint/ # CLN mint working directory +│ └── mintd.log +└── lnd_mint/ # LND mint working directory + └── mintd.log +``` + +## Cleanup + +- Press `Ctrl+C` in the terminal running `interactive_regtest.sh` +- All processes will be terminated and the temporary directory will be cleaned up automatically +- No manual cleanup is required + +## Troubleshooting + +### Environment not starting +- Check that ports 8085, 8087, 18443, 19846, 19847, 10009, 10010 are available +- Ensure you have the necessary dependencies (Bitcoin Core, CLN, LND) available +- Check the logs in `$CDK_ITESTS_DIR/cln_mint/mintd.log` and `$CDK_ITESTS_DIR/lnd_mint/mintd.log` + +### Helper script not working +- Ensure the regtest environment is running first +- The `CDK_ITESTS_DIR` environment variable must be set (done automatically by `interactive_regtest.sh`) + +### Connection issues +- Use `./misc/regtest_helper.sh show-status` to check component health +- Check mint logs with `./misc/regtest_helper.sh show-logs` diff --git a/misc/interactive_regtest.sh b/misc/interactive_regtest.sh new file mode 100755 index 000000000..e38b8fb41 --- /dev/null +++ b/misc/interactive_regtest.sh @@ -0,0 +1,330 @@ +#!/usr/bin/env bash + +# Interactive Regtest Environment for CDK +# This script sets up the regtest environment and keeps it running for interaction + +set -e + +# Function to wait for HTTP endpoint +wait_for_endpoint() { + local url=$1 + local timeout=${2:-60} + local start_time=$(date +%s) + + while true; do + local current_time=$(date +%s) + local elapsed_time=$((current_time - start_time)) + + if [ $elapsed_time -ge $timeout ]; then + echo "❌ Timeout waiting for $url" + return 1 + fi + + local http_status=$(curl -o /dev/null -s -w "%{http_code}" "$url" 2>/dev/null || echo "000") + + if [ "$http_status" -eq 200 ]; then + echo "✓ $url is ready" + return 0 + fi + + sleep 2 + done +} + +# Function to perform cleanup +cleanup() { + echo "Cleaning up..." + + # Remove state file for other sessions + rm -f "/tmp/cdk_regtest_env" + + if [ ! -z "$CDK_MINTD_PID" ] && kill -0 $CDK_MINTD_PID 2>/dev/null; then + echo "Killing the cdk mintd (CLN)" + kill -2 $CDK_MINTD_PID + wait $CDK_MINTD_PID + fi + + if [ ! -z "$CDK_MINTD_LND_PID" ] && kill -0 $CDK_MINTD_LND_PID 2>/dev/null; then + echo "Killing the cdk mintd (LND)" + kill -2 $CDK_MINTD_LND_PID + wait $CDK_MINTD_LND_PID + fi + + if [ ! -z "$CDK_REGTEST_PID" ] && kill -0 $CDK_REGTEST_PID 2>/dev/null; then + echo "Killing the cdk regtest" + kill -2 $CDK_REGTEST_PID + wait $CDK_REGTEST_PID + fi + + echo "Environment terminated" + + # Remove the temporary directory + if [ ! -z "$CDK_ITESTS_DIR" ]; then + rm -rf "$CDK_ITESTS_DIR" + echo "Temp directory removed: $CDK_ITESTS_DIR" + fi + + # Unset all environment variables + unset CDK_ITESTS_DIR + unset CDK_ITESTS_MINT_ADDR + unset CDK_ITESTS_MINT_PORT_0 + unset CDK_ITESTS_MINT_PORT_1 + unset CDK_MINTD_DATABASE + unset CDK_TEST_MINT_URL + unset CDK_TEST_MINT_URL_2 + unset CDK_MINTD_URL + unset CDK_MINTD_WORK_DIR + unset CDK_MINTD_LISTEN_HOST + unset CDK_MINTD_LISTEN_PORT + unset CDK_MINTD_LN_BACKEND + unset CDK_MINTD_MNEMONIC + unset CDK_MINTD_CLN_RPC_PATH + unset CDK_MINTD_LND_ADDRESS + unset CDK_MINTD_LND_CERT_FILE + unset CDK_MINTD_LND_MACAROON_FILE + unset CDK_MINTD_PID + unset CDK_MINTD_LND_PID + unset CDK_REGTEST_PID + unset RUST_BACKTRACE + unset CDK_TEST_REGTEST +} + +# Set up trap to call cleanup on script exit +trap cleanup EXIT + +export CDK_TEST_REGTEST=1 + +# Check for mprocs and offer to install if missing +if ! command -v mprocs >/dev/null 2>&1; then + echo "⚠️ mprocs not found - this tool provides a nice TUI for monitoring logs" + echo "Install it with: cargo install mprocs" + echo + read -p "Would you like to install mprocs now? (y/n): " -n 1 -r + echo + if [[ $REPLY =~ ^[Yy]$ ]]; then + echo "Installing mprocs..." + cargo install mprocs + if [ $? -eq 0 ]; then + echo "✓ mprocs installed successfully" + else + echo "❌ Failed to install mprocs. You can install it later with: cargo install mprocs" + fi + else + echo "Skipping mprocs installation. The environment will work without it." + fi + echo +fi + +# Parse command line arguments +CDK_MINTD_DATABASE=${1:-"sqlite"} # Default to sqlite if not specified + +# Create a temporary directory +export CDK_ITESTS_DIR=$(mktemp -d) +export CDK_ITESTS_MINT_ADDR="127.0.0.1" +export CDK_ITESTS_MINT_PORT_0=8085 +export CDK_ITESTS_MINT_PORT_1=8087 + +# Check if the temporary directory was created successfully +if [[ ! -d "$CDK_ITESTS_DIR" ]]; then + echo "Failed to create temp directory" + exit 1 +fi + +echo "==============================================" +echo "Starting Interactive CDK Regtest Environment" +echo "==============================================" +echo "Temp directory: $CDK_ITESTS_DIR" +echo "Database type: $CDK_MINTD_DATABASE" +echo + +export CDK_MINTD_DATABASE="$CDK_MINTD_DATABASE" + +# Build the necessary binaries +echo "Building binaries..." +cargo build -p cdk-integration-tests --bin start_regtest + +echo "Starting regtest network (Bitcoin + Lightning nodes)..." +cargo run --bin start_regtest & +export CDK_REGTEST_PID=$! + +# Create named pipe for progress tracking +mkfifo "$CDK_ITESTS_DIR/progress_pipe" +rm -f "$CDK_ITESTS_DIR/signal_received" + +# Start reading from pipe in background +(while read line; do + case "$line" in + "checkpoint1") + echo "✓ Regtest network is ready" + touch "$CDK_ITESTS_DIR/signal_received" + exit 0 + ;; + esac +done < "$CDK_ITESTS_DIR/progress_pipe") & + +# Wait for regtest setup (up to 120 seconds) +echo "Waiting for regtest network to be ready..." +for ((i=0; i<120; i++)); do + if [ -f "$CDK_ITESTS_DIR/signal_received" ]; then + break + fi + sleep 1 +done + +if [ ! -f "$CDK_ITESTS_DIR/signal_received" ]; then + echo "❌ Timeout waiting for regtest network" + exit 1 +fi + +echo +echo "Starting CDK Mint #1 (CLN backend)..." +export CDK_MINTD_CLN_RPC_PATH="$CDK_ITESTS_DIR/cln/one/regtest/lightning-rpc" +export CDK_MINTD_URL="http://$CDK_ITESTS_MINT_ADDR:$CDK_ITESTS_MINT_PORT_0" +export CDK_MINTD_WORK_DIR="$CDK_ITESTS_DIR/cln_mint" +export CDK_MINTD_LISTEN_HOST=$CDK_ITESTS_MINT_ADDR +export CDK_MINTD_LISTEN_PORT=$CDK_ITESTS_MINT_PORT_0 +export CDK_MINTD_LN_BACKEND="cln" +export CDK_MINTD_MNEMONIC="eye survey guilt napkin crystal cup whisper salt luggage manage unveil loyal" +export RUST_BACKTRACE=1 + +mkdir -p "$CDK_MINTD_WORK_DIR" +cargo run --bin cdk-mintd > "$CDK_MINTD_WORK_DIR/mintd.log" 2>&1 & +export CDK_MINTD_PID=$! + +# Wait for CLN mint to be ready +echo "Waiting for CLN mint to be ready..." +URL="http://$CDK_ITESTS_MINT_ADDR:$CDK_ITESTS_MINT_PORT_0/v1/info" +wait_for_endpoint "$URL" 60 + +echo +echo "Starting CDK Mint #2 (LND backend)..." +export CDK_MINTD_LND_ADDRESS="https://localhost:10010" +export CDK_MINTD_LND_CERT_FILE="$CDK_ITESTS_DIR/lnd/two/tls.cert" +export CDK_MINTD_LND_MACAROON_FILE="$CDK_ITESTS_DIR/lnd/two/data/chain/bitcoin/regtest/admin.macaroon" + +export CDK_MINTD_URL="http://$CDK_ITESTS_MINT_ADDR:$CDK_ITESTS_MINT_PORT_1" +mkdir -p "$CDK_ITESTS_DIR/lnd_mint" +export CDK_MINTD_WORK_DIR="$CDK_ITESTS_DIR/lnd_mint" +export CDK_MINTD_LISTEN_HOST=$CDK_ITESTS_MINT_ADDR +export CDK_MINTD_LISTEN_PORT=$CDK_ITESTS_MINT_PORT_1 +export CDK_MINTD_LN_BACKEND="lnd" +export CDK_MINTD_MNEMONIC="cattle gold bind busy sound reduce tone addict baby spend february strategy" + +cargo run --bin cdk-mintd > "$CDK_MINTD_WORK_DIR/mintd.log" 2>&1 & +export CDK_MINTD_LND_PID=$! + +# Wait for LND mint to be ready +echo "Waiting for LND mint to be ready..." +URL="http://$CDK_ITESTS_MINT_ADDR:$CDK_ITESTS_MINT_PORT_1/v1/info" +wait_for_endpoint "$URL" 60 + +# Set environment variables for easy access +export CDK_TEST_MINT_URL="http://$CDK_ITESTS_MINT_ADDR:$CDK_ITESTS_MINT_PORT_0" +export CDK_TEST_MINT_URL_2="http://$CDK_ITESTS_MINT_ADDR:$CDK_ITESTS_MINT_PORT_1" + +# Create state file for other terminal sessions +ENV_FILE="/tmp/cdk_regtest_env" +echo "export CDK_ITESTS_DIR=\"$CDK_ITESTS_DIR\"" > "$ENV_FILE" +echo "export CDK_TEST_MINT_URL=\"$CDK_TEST_MINT_URL\"" >> "$ENV_FILE" +echo "export CDK_TEST_MINT_URL_2=\"$CDK_TEST_MINT_URL_2\"" >> "$ENV_FILE" +echo "export CDK_MINTD_PID=\"$CDK_MINTD_PID\"" >> "$ENV_FILE" +echo "export CDK_MINTD_LND_PID=\"$CDK_MINTD_LND_PID\"" >> "$ENV_FILE" +echo "export CDK_REGTEST_PID=\"$CDK_REGTEST_PID\"" >> "$ENV_FILE" + +echo +echo "==============================================" +echo "🎉 CDK Regtest Environment is Ready!" +echo "==============================================" +echo +echo "Network Information:" +echo " • Bitcoin RPC: 127.0.0.1:18443 (user: testuser, pass: testpass)" +echo " • CLN Node 1: $CDK_ITESTS_DIR/cln/one/regtest/lightning-rpc" +echo " • CLN Node 2: $CDK_ITESTS_DIR/cln/two/regtest/lightning-rpc" +echo " • LND Node 1: https://localhost:10009" +echo " • LND Node 2: https://localhost:10010" +echo +echo "CDK Mints:" +echo " • CLN Mint: $CDK_TEST_MINT_URL" +echo " • LND Mint: $CDK_TEST_MINT_URL_2" +echo +echo "Files and Directories:" +echo " • Working Directory: $CDK_ITESTS_DIR" +echo " • CLN Mint Logs: $CDK_ITESTS_DIR/cln_mint/mintd.log" +echo " • LND Mint Logs: $CDK_ITESTS_DIR/lnd_mint/mintd.log" +echo " • LND 1 TLS Cert: $CDK_ITESTS_DIR/lnd/one/tls.cert" +echo " • LND 1 Macaroon: $CDK_ITESTS_DIR/lnd/one/data/chain/bitcoin/regtest/admin.macaroon" +echo " • LND 2 TLS Cert: $CDK_ITESTS_DIR/lnd/two/tls.cert" +echo " • LND 2 Macaroon: $CDK_ITESTS_DIR/lnd/two/data/chain/bitcoin/regtest/admin.macaroon" +echo +echo "Environment Variables (available in other terminals):" +echo " • CDK_TEST_MINT_URL=\"$CDK_TEST_MINT_URL\"" +echo " • CDK_TEST_MINT_URL_2=\"$CDK_TEST_MINT_URL_2\"" +echo " • CDK_ITESTS_DIR=\"$CDK_ITESTS_DIR\"" +echo +echo "You can now:" +echo " • Use 'just' commands in other terminals: 'just ln-cln1 getinfo'" +echo " • Run integration tests: 'just mint-test' or 'cargo test -p cdk-integration-tests'" +echo " • Use CDK CLI tools with the mint URLs above" +echo " • Interact with Lightning nodes directly" +echo " • Access Bitcoin regtest node" +echo +echo "State File: /tmp/cdk_regtest_env (allows other terminals to find this environment)" +echo +echo "Starting mprocs to monitor logs..." +echo "Press 'q' to quit mprocs and stop the environment" +echo "==============================================" + +# Create mprocs configuration +MPROCS_CONFIG="$CDK_ITESTS_DIR/mprocs.yaml" +cat > "$MPROCS_CONFIG" << EOF +procs: + cln-mint: + shell: "touch $CDK_ITESTS_DIR/cln_mint/mintd.log && tail -f $CDK_ITESTS_DIR/cln_mint/mintd.log" + autostart: true + + lnd-mint: + shell: "touch $CDK_ITESTS_DIR/lnd_mint/mintd.log && tail -f $CDK_ITESTS_DIR/lnd_mint/mintd.log" + autostart: true + + bitcoind: + shell: "touch $CDK_ITESTS_DIR/bitcoin/regtest/debug.log && tail -f $CDK_ITESTS_DIR/bitcoin/regtest/debug.log" + autostart: true + + cln-one: + shell: "while [ ! -f $CDK_ITESTS_DIR/cln/one/regtest/log ]; do sleep 1; done && tail -f $CDK_ITESTS_DIR/cln/one/regtest/log" + autostart: true + + cln-two: + shell: "while [ ! -f $CDK_ITESTS_DIR/cln/two/regtest/log ]; do sleep 1; done && tail -f $CDK_ITESTS_DIR/cln/two/regtest/log" + autostart: true + + lnd-one: + shell: "while [ ! -f $CDK_ITESTS_DIR/lnd/one/logs/bitcoin/regtest/lnd.log ]; do sleep 1; done && tail -f $CDK_ITESTS_DIR/lnd/one/logs/bitcoin/regtest/lnd.log" + autostart: true + + lnd-two: + shell: "while [ ! -f $CDK_ITESTS_DIR/lnd/two/logs/bitcoin/regtest/lnd.log ]; do sleep 1; done && tail -f $CDK_ITESTS_DIR/lnd/two/logs/bitcoin/regtest/lnd.log" + autostart: true + +settings: + mouse_scroll_speed: 3 + proc_list_width: 20 + hide_keymap_window: false +EOF + +# Wait a bit for log files to be created +sleep 2 + +# Start mprocs to show all logs +if command -v mprocs >/dev/null 2>&1; then + cd "$CDK_ITESTS_DIR" + mprocs --config "$MPROCS_CONFIG" +else + echo "⚠️ mprocs not found. Install it with: cargo install mprocs" + echo "Falling back to simple wait loop..." + echo "Press Ctrl+C to stop the environment" + # Keep the script running + while true; do + sleep 1 + done +fi diff --git a/misc/interactive_regtest_mprocs.sh b/misc/interactive_regtest_mprocs.sh new file mode 100755 index 000000000..8f486fb63 --- /dev/null +++ b/misc/interactive_regtest_mprocs.sh @@ -0,0 +1,320 @@ +#!/usr/bin/env bash + +# Interactive Regtest Environment for CDK with Direct Process Management +# This script sets up mprocs to manage the mint processes directly + +set -e + +# Function to wait for HTTP endpoint +wait_for_endpoint() { + local url=$1 + local timeout=${2:-60} + local start_time=$(date +%s) + + while true; do + local current_time=$(date +%s) + local elapsed_time=$((current_time - start_time)) + + if [ $elapsed_time -ge $timeout ]; then + echo "❌ Timeout waiting for $url" + return 1 + fi + + local http_status=$(curl -o /dev/null -s -w "%{http_code}" "$url" 2>/dev/null || echo "000") + + if [ "$http_status" -eq 200 ]; then + echo "✓ $url is ready" + return 0 + fi + + sleep 2 + done +} + +# Function to perform cleanup +cleanup() { + echo "Cleaning up..." + + # Remove state file for other sessions + rm -f "/tmp/cdk_regtest_env" + + if [ ! -z "$CDK_REGTEST_PID" ] && kill -0 $CDK_REGTEST_PID 2>/dev/null; then + echo "Killing the cdk regtest" + kill -2 $CDK_REGTEST_PID + wait $CDK_REGTEST_PID + fi + + echo "Environment terminated" + + # Remove the temporary directory + if [ ! -z "$CDK_ITESTS_DIR" ]; then + rm -rf "$CDK_ITESTS_DIR" + echo "Temp directory removed: $CDK_ITESTS_DIR" + fi + + # Unset all environment variables + unset CDK_ITESTS_DIR + unset CDK_ITESTS_MINT_ADDR + unset CDK_ITESTS_MINT_PORT_0 + unset CDK_ITESTS_MINT_PORT_1 + unset CDK_MINTD_DATABASE + unset CDK_TEST_MINT_URL + unset CDK_TEST_MINT_URL_2 + unset CDK_REGTEST_PID + unset RUST_BACKTRACE + unset CDK_TEST_REGTEST +} + +# Set up trap to call cleanup on script exit +trap cleanup EXIT + +export CDK_TEST_REGTEST=1 + +# Check for mprocs and offer to install if missing +if ! command -v mprocs >/dev/null 2>&1; then + echo "⚠️ mprocs not found - this tool is required for direct process management" + echo "Install it with: cargo install mprocs" + echo + read -p "Would you like to install mprocs now? (y/n): " -n 1 -r + echo + if [[ $REPLY =~ ^[Yy]$ ]]; then + echo "Installing mprocs..." + cargo install mprocs + if [ $? -eq 0 ]; then + echo "✓ mprocs installed successfully" + else + echo "❌ Failed to install mprocs." + exit 1 + fi + else + echo "❌ mprocs is required for this mode. Exiting." + exit 1 + fi + echo +fi + +# Parse command line arguments +CDK_MINTD_DATABASE=${1:-"sqlite"} # Default to sqlite if not specified + +# Create a temporary directory +export CDK_ITESTS_DIR=$(mktemp -d) +export CDK_ITESTS_MINT_ADDR="127.0.0.1" +export CDK_ITESTS_MINT_PORT_0=8085 +export CDK_ITESTS_MINT_PORT_1=8087 + +# Check if the temporary directory was created successfully +if [[ ! -d "$CDK_ITESTS_DIR" ]]; then + echo "Failed to create temp directory" + exit 1 +fi + +echo "==============================================" +echo "Starting CDK Regtest with Direct Process Management" +echo "==============================================" +echo "Temp directory: $CDK_ITESTS_DIR" +echo "Database type: $CDK_MINTD_DATABASE" +echo + +export CDK_MINTD_DATABASE="$CDK_MINTD_DATABASE" + +# Build the necessary binaries +echo "Building binaries..." +cargo build -p cdk-integration-tests --bin start_regtest +cargo build --bin cdk-mintd + +echo "Starting regtest network (Bitcoin + Lightning nodes)..." +cargo run --bin start_regtest & +export CDK_REGTEST_PID=$! + +# Create named pipe for progress tracking +mkfifo "$CDK_ITESTS_DIR/progress_pipe" +rm -f "$CDK_ITESTS_DIR/signal_received" + +# Start reading from pipe in background +(while read line; do + case "$line" in + "checkpoint1") + echo "✓ Regtest network is ready" + touch "$CDK_ITESTS_DIR/signal_received" + exit 0 + ;; + esac +done < "$CDK_ITESTS_DIR/progress_pipe") & + +# Wait for regtest setup (up to 120 seconds) +echo "Waiting for regtest network to be ready..." +for ((i=0; i<120; i++)); do + if [ -f "$CDK_ITESTS_DIR/signal_received" ]; then + break + fi + sleep 1 +done + +if [ ! -f "$CDK_ITESTS_DIR/signal_received" ]; then + echo "❌ Timeout waiting for regtest network" + exit 1 +fi + +# Create work directories for mints +mkdir -p "$CDK_ITESTS_DIR/cln_mint" +mkdir -p "$CDK_ITESTS_DIR/lnd_mint" + +# Set environment variables for easy access +export CDK_TEST_MINT_URL="http://$CDK_ITESTS_MINT_ADDR:$CDK_ITESTS_MINT_PORT_0" +export CDK_TEST_MINT_URL_2="http://$CDK_ITESTS_MINT_ADDR:$CDK_ITESTS_MINT_PORT_1" + +# Create state file for other terminal sessions +ENV_FILE="/tmp/cdk_regtest_env" +echo "export CDK_ITESTS_DIR=\"$CDK_ITESTS_DIR\"" > "$ENV_FILE" +echo "export CDK_TEST_MINT_URL=\"$CDK_TEST_MINT_URL\"" >> "$ENV_FILE" +echo "export CDK_TEST_MINT_URL_2=\"$CDK_TEST_MINT_URL_2\"" >> "$ENV_FILE" +echo "export CDK_REGTEST_PID=\"$CDK_REGTEST_PID\"" >> "$ENV_FILE" + +# Get the project root directory (where justfile is located) +PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" + +# Create environment setup scripts for mprocs to use +cat > "$CDK_ITESTS_DIR/start_cln_mint.sh" << EOF +#!/usr/bin/env bash +cd "$PROJECT_ROOT" +export CDK_MINTD_CLN_RPC_PATH="$CDK_ITESTS_DIR/cln/one/regtest/lightning-rpc" +export CDK_MINTD_URL="http://127.0.0.1:8085" +export CDK_MINTD_WORK_DIR="$CDK_ITESTS_DIR/cln_mint" +export CDK_MINTD_LISTEN_HOST="127.0.0.1" +export CDK_MINTD_LISTEN_PORT=8085 +export CDK_MINTD_LN_BACKEND="cln" +export CDK_MINTD_MNEMONIC="eye survey guilt napkin crystal cup whisper salt luggage manage unveil loyal" +export RUST_BACKTRACE=1 +export CDK_MINTD_DATABASE="$CDK_MINTD_DATABASE" + +echo "Starting CLN Mint on port 8085..." +echo "Project root: $PROJECT_ROOT" +echo "Working directory: \$CDK_MINTD_WORK_DIR" +echo "CLN RPC path: \$CDK_MINTD_CLN_RPC_PATH" +echo "Database type: \$CDK_MINTD_DATABASE" +echo "---" + +exec cargo run --bin cdk-mintd +EOF + +cat > "$CDK_ITESTS_DIR/start_lnd_mint.sh" << EOF +#!/usr/bin/env bash +cd "$PROJECT_ROOT" +export CDK_MINTD_LND_ADDRESS="https://localhost:10010" +export CDK_MINTD_LND_CERT_FILE="$CDK_ITESTS_DIR/lnd/two/tls.cert" +export CDK_MINTD_LND_MACAROON_FILE="$CDK_ITESTS_DIR/lnd/two/data/chain/bitcoin/regtest/admin.macaroon" +export CDK_MINTD_URL="http://127.0.0.1:8087" +export CDK_MINTD_WORK_DIR="$CDK_ITESTS_DIR/lnd_mint" +export CDK_MINTD_LISTEN_HOST="127.0.0.1" +export CDK_MINTD_LISTEN_PORT=8087 +export CDK_MINTD_LN_BACKEND="lnd" +export CDK_MINTD_MNEMONIC="cattle gold bind busy sound reduce tone addict baby spend february strategy" +export RUST_BACKTRACE=1 +export CDK_MINTD_DATABASE="$CDK_MINTD_DATABASE" + +echo "Starting LND Mint on port 8087..." +echo "Project root: $PROJECT_ROOT" +echo "Working directory: \$CDK_MINTD_WORK_DIR" +echo "LND address: \$CDK_MINTD_LND_ADDRESS" +echo "Database type: \$CDK_MINTD_DATABASE" +echo "---" + +exec cargo run --bin cdk-mintd +EOF + +# Make scripts executable +chmod +x "$CDK_ITESTS_DIR/start_cln_mint.sh" +chmod +x "$CDK_ITESTS_DIR/start_lnd_mint.sh" + +echo +echo "==============================================" +echo "🎉 CDK Regtest Environment is Ready!" +echo "==============================================" +echo +echo "Network Information:" +echo " • Bitcoin RPC: 127.0.0.1:18443 (user: testuser, pass: testpass)" +echo " • CLN Node 1: $CDK_ITESTS_DIR/cln/one/regtest/lightning-rpc" +echo " • CLN Node 2: $CDK_ITESTS_DIR/cln/two/regtest/lightning-rpc" +echo " • LND Node 1: https://localhost:10009" +echo " • LND Node 2: https://localhost:10010" +echo +echo "CDK Mints (will be managed by mprocs):" +echo " • CLN Mint: $CDK_TEST_MINT_URL" +echo " • LND Mint: $CDK_TEST_MINT_URL_2" +echo +echo "Files and Directories:" +echo " • Working Directory: $CDK_ITESTS_DIR" +echo " • Start Scripts: $CDK_ITESTS_DIR/start_{cln,lnd}_mint.sh" +echo +echo "Environment Variables (available in other terminals):" +echo " • CDK_TEST_MINT_URL=\"$CDK_TEST_MINT_URL\"" +echo " • CDK_TEST_MINT_URL_2=\"$CDK_TEST_MINT_URL_2\"" +echo " • CDK_ITESTS_DIR=\"$CDK_ITESTS_DIR\"" +echo +echo "Starting mprocs with direct process management..." +echo +echo "In mprocs you can:" +echo " • 's' to start a process" +echo " • 'k' to kill a process" +echo " • 'r' to restart a process" +echo " • 'Enter' to focus on a process" +echo " • 'q' to quit and stop the environment" +echo "==============================================" + +# Wait a moment for everything to settle +sleep 2 + +# Create mprocs configuration with direct process management +MPROCS_CONFIG="$CDK_ITESTS_DIR/mprocs.yaml" +cat > "$MPROCS_CONFIG" << EOF +procs: + cln-mint: + shell: "$CDK_ITESTS_DIR/start_cln_mint.sh" + autostart: false + env: + CDK_ITESTS_DIR: "$CDK_ITESTS_DIR" + CDK_MINTD_DATABASE: "$CDK_MINTD_DATABASE" + + lnd-mint: + shell: "$CDK_ITESTS_DIR/start_lnd_mint.sh" + autostart: false + env: + CDK_ITESTS_DIR: "$CDK_ITESTS_DIR" + CDK_MINTD_DATABASE: "$CDK_MINTD_DATABASE" + + bitcoind: + shell: "while [ ! -f $CDK_ITESTS_DIR/bitcoin/regtest/debug.log ]; do sleep 1; done && tail -f $CDK_ITESTS_DIR/bitcoin/regtest/debug.log" + autostart: true + + cln-one: + shell: "while [ ! -f $CDK_ITESTS_DIR/cln/one/regtest/log ]; do sleep 1; done && tail -f $CDK_ITESTS_DIR/cln/one/regtest/log" + autostart: true + + cln-two: + shell: "while [ ! -f $CDK_ITESTS_DIR/cln/two/regtest/log ]; do sleep 1; done && tail -f $CDK_ITESTS_DIR/cln/two/regtest/log" + autostart: true + + lnd-one: + shell: "while [ ! -f $CDK_ITESTS_DIR/lnd/one/logs/bitcoin/regtest/lnd.log ]; do sleep 1; done && tail -f $CDK_ITESTS_DIR/lnd/one/logs/bitcoin/regtest/lnd.log" + autostart: true + + lnd-two: + shell: "while [ ! -f $CDK_ITESTS_DIR/lnd/two/logs/bitcoin/regtest/lnd.log ]; do sleep 1; done && tail -f $CDK_ITESTS_DIR/lnd/two/logs/bitcoin/regtest/lnd.log" + autostart: true + +settings: + mouse_scroll_speed: 3 + proc_list_width: 20 + hide_keymap_window: false + keymap_procs: + toggle_process: 's' + kill_process: 'k' + restart_process: 'r' + focus_process: 'Enter' + show_keymap: '?' +EOF + +# Start mprocs with direct process management +echo "Starting mprocs..." +cd "$CDK_ITESTS_DIR" +mprocs --config "$MPROCS_CONFIG" diff --git a/misc/regtest_helper.sh b/misc/regtest_helper.sh new file mode 100755 index 000000000..c0442c41b --- /dev/null +++ b/misc/regtest_helper.sh @@ -0,0 +1,421 @@ +#!/usr/bin/env bash + +# Helper script for interacting with CDK regtest environment +# Run this after starting interactive_regtest.sh + +# Check for environment state file first, then environment variable +ENV_FILE="/tmp/cdk_regtest_env" +if [ -f "$ENV_FILE" ]; then + source "$ENV_FILE" +elif [ ! -z "$CDK_ITESTS_DIR" ]; then + # Environment variable is set, create state file for other sessions + echo "export CDK_ITESTS_DIR=\"$CDK_ITESTS_DIR\"" > "$ENV_FILE" + echo "export CDK_TEST_MINT_URL=\"$CDK_TEST_MINT_URL\"" >> "$ENV_FILE" + echo "export CDK_TEST_MINT_URL_2=\"$CDK_TEST_MINT_URL_2\"" >> "$ENV_FILE" + echo "export CDK_MINTD_PID=\"$CDK_MINTD_PID\"" >> "$ENV_FILE" + echo "export CDK_MINTD_LND_PID=\"$CDK_MINTD_LND_PID\"" >> "$ENV_FILE" + echo "export CDK_REGTEST_PID=\"$CDK_REGTEST_PID\"" >> "$ENV_FILE" +else + echo "❌ CDK regtest environment not found!" + echo "Please run './misc/interactive_regtest.sh' or 'just regtest' first" + exit 1 +fi + +# Validate that the environment is actually running +if [ -z "$CDK_ITESTS_DIR" ] || [ ! -d "$CDK_ITESTS_DIR" ]; then + echo "❌ CDK regtest environment not found or directory missing!" + echo "Please run './misc/interactive_regtest.sh' or 'just regtest' first" + [ -f "$ENV_FILE" ] && rm "$ENV_FILE" # Clean up stale state file + exit 1 +fi + +show_help() { + echo "CDK Regtest Environment Helper" + echo "=============================" + echo + echo "Lightning Node Commands:" + echo " ln-cln1 - Execute command on CLN node 1" + echo " ln-cln2 - Execute command on CLN node 2" + echo " ln-lnd1 - Execute command on LND node 1" + echo " ln-lnd2 - Execute command on LND node 2" + echo + echo "Bitcoin Commands:" + echo " btc - Execute bitcoin-cli command" + echo " btc-mine [blocks] - Mine blocks (default: 10)" + echo + echo "CDK Mint Commands:" + echo " mint-info - Show mint information" + echo " mint-test - Run integration tests" + echo " restart-mints - Stop, recompile, and restart both mints (log mode)" + echo + echo "Environment Commands:" + echo " show-env - Show environment variables" + echo " show-logs - Show recent mint logs" + echo " show-status - Show status of all components" + echo " logs - Start mprocs TUI (adapts to current mode)" + echo + echo "Environment Modes:" + echo " just regtest - Log tailing mode (mints auto-start, logs to files)" + echo " just regtest-mprocs - Direct management (mprocs controls mint processes)" + echo + echo "Examples:" + echo " $0 ln-cln1 getinfo" + echo " $0 ln-lnd1 getinfo" + echo " $0 btc getblockcount" + echo " $0 btc-mine 5" + echo " $0 mint-info" + echo " $0 restart-mints # Only works in log tailing mode" + echo " $0 logs # Start mprocs viewer" +} + +# Bitcoin commands +btc_command() { + bitcoin-cli -regtest -rpcuser=testuser -rpcpassword=testpass -rpcport=18443 "$@" +} + +btc_mine() { + local blocks=${1:-10} + local address=$(btc_command getnewaddress) + btc_command generatetoaddress "$blocks" "$address" + echo "Mined $blocks blocks" +} + +# CLN commands +cln_command() { + local node=$1 + shift + lightning-cli --rpc-file="$CDK_ITESTS_DIR/cln/$node/regtest/lightning-rpc" "$@" +} + +# LND commands +lnd_command() { + local node=$1 + shift + local port + case $node in + "one") port=10009 ;; + "two") port=10010 ;; + *) echo "Unknown LND node: $node"; return 1 ;; + esac + + lncli --rpcserver=localhost:$port \ + --tlscertpath="$CDK_ITESTS_DIR/lnd/$node/tls.cert" \ + --macaroonpath="$CDK_ITESTS_DIR/lnd/$node/data/chain/bitcoin/regtest/admin.macaroon" \ + "$@" +} + +# Mint commands +mint_info() { + echo "CLN Mint (Port 8085):" + curl -s "$CDK_TEST_MINT_URL/v1/info" | jq . 2>/dev/null || curl -s "$CDK_TEST_MINT_URL/v1/info" + echo + echo "LND Mint (Port 8087):" + curl -s "$CDK_TEST_MINT_URL_2/v1/info" | jq . 2>/dev/null || curl -s "$CDK_TEST_MINT_URL_2/v1/info" +} + +mint_test() { + echo "Running integration tests..." + cargo test -p cdk-integration-tests +} + +# Environment info +show_env() { + echo "CDK Regtest Environment Variables:" + echo "=================================" + echo "CDK_ITESTS_DIR=$CDK_ITESTS_DIR" + echo "CDK_TEST_MINT_URL=$CDK_TEST_MINT_URL" + echo "CDK_TEST_MINT_URL_2=$CDK_TEST_MINT_URL_2" + echo "CDK_MINTD_PID=$CDK_MINTD_PID" + echo "CDK_MINTD_LND_PID=$CDK_MINTD_LND_PID" + echo "CDK_REGTEST_PID=$CDK_REGTEST_PID" +} + +show_logs() { + echo "=== Recent CLN Mint Logs ===" + if [ -f "$CDK_ITESTS_DIR/cln_mint/mintd.log" ]; then + tail -10 "$CDK_ITESTS_DIR/cln_mint/mintd.log" + else + echo "Log file not found" + fi + echo + echo "=== Recent LND Mint Logs ===" + if [ -f "$CDK_ITESTS_DIR/lnd_mint/mintd.log" ]; then + tail -10 "$CDK_ITESTS_DIR/lnd_mint/mintd.log" + else + echo "Log file not found" + fi +} + +start_mprocs() { + echo "Starting mprocs log viewer..." + + if ! command -v mprocs >/dev/null 2>&1; then + echo "❌ mprocs not found! Please install it with:" + echo " cargo install mprocs" + echo " or your package manager" + return 1 + fi + + # Check if we have the direct process management config + DIRECT_MPROCS_CONFIG="$CDK_ITESTS_DIR/mprocs.yaml" + FALLBACK_MPROCS_CONFIG="$CDK_ITESTS_DIR/mprocs_fallback.yaml" + + if [ -f "$DIRECT_MPROCS_CONFIG" ]; then + echo "Using direct process management mode..." + echo "In mprocs: 's' to start, 'k' to kill, 'r' to restart processes" + cd "$CDK_ITESTS_DIR" + mprocs --config "$DIRECT_MPROCS_CONFIG" + return + fi + + # Create fallback mprocs configuration for log tailing + cat > "$FALLBACK_MPROCS_CONFIG" << EOF +procs: + cln-mint: + shell: "touch $CDK_ITESTS_DIR/cln_mint/mintd.log && tail -f $CDK_ITESTS_DIR/cln_mint/mintd.log" + autostart: true + + lnd-mint: + shell: "touch $CDK_ITESTS_DIR/lnd_mint/mintd.log && tail -f $CDK_ITESTS_DIR/lnd_mint/mintd.log" + autostart: true + + bitcoind: + shell: "touch $CDK_ITESTS_DIR/bitcoin/regtest/debug.log && tail -f $CDK_ITESTS_DIR/bitcoin/regtest/debug.log" + autostart: true + + cln-one: + shell: "while [ ! -f $CDK_ITESTS_DIR/cln/one/regtest/log ]; do sleep 1; done && tail -f $CDK_ITESTS_DIR/cln/one/regtest/log" + autostart: true + + cln-two: + shell: "while [ ! -f $CDK_ITESTS_DIR/cln/two/regtest/log ]; do sleep 1; done && tail -f $CDK_ITESTS_DIR/cln/two/regtest/log" + autostart: true + + lnd-one: + shell: "while [ ! -f $CDK_ITESTS_DIR/lnd/one/logs/bitcoin/regtest/lnd.log ]; do sleep 1; done && tail -f $CDK_ITESTS_DIR/lnd/one/logs/bitcoin/regtest/lnd.log" + autostart: true + + lnd-two: + shell: "while [ ! -f $CDK_ITESTS_DIR/lnd/two/logs/bitcoin/regtest/lnd.log ]; do sleep 1; done && tail -f $CDK_ITESTS_DIR/lnd/two/logs/bitcoin/regtest/lnd.log" + autostart: true + +settings: + mouse_scroll_speed: 3 + proc_list_width: 20 + hide_keymap_window: false +EOF + + echo "Using log tailing mode..." + echo "Use 'q' to quit the log viewer" + cd "$CDK_ITESTS_DIR" + mprocs --config "$FALLBACK_MPROCS_CONFIG" +} + +show_status() { + echo "CDK Regtest Environment Status:" + echo "===============================" + + # Check processes + echo "Processes:" + if [ ! -z "$CDK_REGTEST_PID" ] && kill -0 $CDK_REGTEST_PID 2>/dev/null; then + echo " ✓ Regtest network (PID: $CDK_REGTEST_PID)" + else + echo " ❌ Regtest network" + fi + + if [ ! -z "$CDK_MINTD_PID" ] && kill -0 $CDK_MINTD_PID 2>/dev/null; then + echo " ✓ CLN Mint (PID: $CDK_MINTD_PID)" + else + echo " ❌ CLN Mint" + fi + + if [ ! -z "$CDK_MINTD_LND_PID" ] && kill -0 $CDK_MINTD_LND_PID 2>/dev/null; then + echo " ✓ LND Mint (PID: $CDK_MINTD_LND_PID)" + else + echo " ❌ LND Mint" + fi + + echo + echo "Network connectivity:" + if curl -s "$CDK_TEST_MINT_URL/v1/info" >/dev/null 2>&1; then + echo " ✓ CLN Mint responding" + else + echo " ❌ CLN Mint not responding" + fi + + if curl -s "$CDK_TEST_MINT_URL_2/v1/info" >/dev/null 2>&1; then + echo " ✓ LND Mint responding" + else + echo " ❌ LND Mint not responding" + fi +} + +restart_mints() { + echo "===============================" + echo "Restarting CDK Mints" + echo "===============================" + + # Stop existing mints + echo "Stopping existing mints..." + if [ ! -z "$CDK_MINTD_PID" ] && kill -0 $CDK_MINTD_PID 2>/dev/null; then + echo " Stopping CLN Mint (PID: $CDK_MINTD_PID)" + kill -2 $CDK_MINTD_PID + wait $CDK_MINTD_PID 2>/dev/null || true + fi + + if [ ! -z "$CDK_MINTD_LND_PID" ] && kill -0 $CDK_MINTD_LND_PID 2>/dev/null; then + echo " Stopping LND Mint (PID: $CDK_MINTD_LND_PID)" + kill -2 $CDK_MINTD_LND_PID + wait $CDK_MINTD_LND_PID 2>/dev/null || true + fi + + # Recompile + echo "Recompiling cdk-mintd..." + if ! cargo build --bin cdk-mintd; then + echo "❌ Compilation failed" + return 1 + fi + echo "✓ Compilation successful" + + # Restart CLN mint + echo "Starting CLN Mint..." + export CDK_MINTD_CLN_RPC_PATH="$CDK_ITESTS_DIR/cln/one/regtest/lightning-rpc" + export CDK_MINTD_URL="http://127.0.0.1:8085" + export CDK_MINTD_WORK_DIR="$CDK_ITESTS_DIR/cln_mint" + export CDK_MINTD_LISTEN_HOST="127.0.0.1" + export CDK_MINTD_LISTEN_PORT=8085 + export CDK_MINTD_LN_BACKEND="cln" + export CDK_MINTD_MNEMONIC="eye survey guilt napkin crystal cup whisper salt luggage manage unveil loyal" + export RUST_BACKTRACE=1 + + cargo run --bin cdk-mintd > "$CDK_MINTD_WORK_DIR/mintd.log" 2>&1 & + NEW_CLN_PID=$! + + # Wait for CLN mint to be ready + echo "Waiting for CLN mint to start..." + local start_time=$(date +%s) + while true; do + local current_time=$(date +%s) + local elapsed_time=$((current_time - start_time)) + + if [ $elapsed_time -ge 30 ]; then + echo "❌ Timeout waiting for CLN mint" + return 1 + fi + + if curl -s "http://127.0.0.1:8085/v1/info" >/dev/null 2>&1; then + echo "✓ CLN Mint ready" + break + fi + sleep 1 + done + + # Restart LND mint + echo "Starting LND Mint..." + export CDK_MINTD_LND_ADDRESS="https://localhost:10010" + export CDK_MINTD_LND_CERT_FILE="$CDK_ITESTS_DIR/lnd/two/tls.cert" + export CDK_MINTD_LND_MACAROON_FILE="$CDK_ITESTS_DIR/lnd/two/data/chain/bitcoin/regtest/admin.macaroon" + export CDK_MINTD_URL="http://127.0.0.1:8087" + export CDK_MINTD_WORK_DIR="$CDK_ITESTS_DIR/lnd_mint" + export CDK_MINTD_LISTEN_HOST="127.0.0.1" + export CDK_MINTD_LISTEN_PORT=8087 + export CDK_MINTD_LN_BACKEND="lnd" + export CDK_MINTD_MNEMONIC="cattle gold bind busy sound reduce tone addict baby spend february strategy" + + cargo run --bin cdk-mintd > "$CDK_MINTD_WORK_DIR/mintd.log" 2>&1 & + NEW_LND_PID=$! + + # Wait for LND mint to be ready + echo "Waiting for LND mint to start..." + start_time=$(date +%s) + while true; do + current_time=$(date +%s) + elapsed_time=$((current_time - start_time)) + + if [ $elapsed_time -ge 30 ]; then + echo "❌ Timeout waiting for LND mint" + return 1 + fi + + if curl -s "http://127.0.0.1:8087/v1/info" >/dev/null 2>&1; then + echo "✓ LND Mint ready" + break + fi + sleep 1 + done + + # Update PIDs in state file + CDK_MINTD_PID=$NEW_CLN_PID + CDK_MINTD_LND_PID=$NEW_LND_PID + + # Update state file + echo "export CDK_ITESTS_DIR=\"$CDK_ITESTS_DIR\"" > "$ENV_FILE" + echo "export CDK_TEST_MINT_URL=\"$CDK_TEST_MINT_URL\"" >> "$ENV_FILE" + echo "export CDK_TEST_MINT_URL_2=\"$CDK_TEST_MINT_URL_2\"" >> "$ENV_FILE" + echo "export CDK_MINTD_PID=\"$CDK_MINTD_PID\"" >> "$ENV_FILE" + echo "export CDK_MINTD_LND_PID=\"$CDK_MINTD_LND_PID\"" >> "$ENV_FILE" + echo "export CDK_REGTEST_PID=\"$CDK_REGTEST_PID\"" >> "$ENV_FILE" + + echo + echo "✅ Mints restarted successfully!" + echo " CLN Mint: http://127.0.0.1:8085 (PID: $CDK_MINTD_PID)" + echo " LND Mint: http://127.0.0.1:8087 (PID: $CDK_MINTD_LND_PID)" + echo "===============================" +} + +# Main command dispatcher +case "$1" in + "ln-cln1") + shift + cln_command "one" "$@" + ;; + "ln-cln2") + shift + cln_command "two" "$@" + ;; + "ln-lnd1") + shift + lnd_command "one" "$@" + ;; + "ln-lnd2") + shift + lnd_command "two" "$@" + ;; + "btc") + shift + btc_command "$@" + ;; + "btc-mine") + shift + btc_mine "$@" + ;; + "mint-info") + mint_info + ;; + "mint-test") + mint_test + ;; + "restart-mints") + restart_mints + ;; + "show-env") + show_env + ;; + "show-logs") + show_logs + ;; + "show-status") + show_status + ;; + "logs") + start_mprocs + ;; + "help"|"-h"|"--help"|"") + show_help + ;; + *) + echo "Unknown command: $1" + echo "Run '$0 help' for available commands" + exit 1 + ;; +esac From e76b53a6372ea7ece9535e1365e15bfcdc5ef95e Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Tue, 8 Jul 2025 11:03:40 +0100 Subject: [PATCH 014/321] feat: mprocs inter only regtest --- MINT_RESTART_FEATURE.md | 86 -------- justfile | 5 - misc/README.md | 10 +- misc/interactive_regtest.sh | 330 ----------------------------- misc/interactive_regtest_mprocs.sh | 4 +- misc/regtest_helper.sh | 6 +- 6 files changed, 10 insertions(+), 431 deletions(-) delete mode 100644 MINT_RESTART_FEATURE.md delete mode 100755 misc/interactive_regtest.sh diff --git a/MINT_RESTART_FEATURE.md b/MINT_RESTART_FEATURE.md deleted file mode 100644 index 0a6180a35..000000000 --- a/MINT_RESTART_FEATURE.md +++ /dev/null @@ -1,86 +0,0 @@ -# Mint Restart Feature - -A new command has been added to restart the CDK mints after recompiling, perfect for development workflows when you're making changes to the mint code. - -## Command - -```bash -just restart-mints -``` - -or - -```bash -./misc/regtest_helper.sh restart-mints -``` - -## What It Does - -1. **Stops** both running mints (CLN and LND mints) -2. **Recompiles** the `cdk-mintd` binary with your latest changes -3. **Restarts** both mints with the same configuration -4. **Waits** for both mints to be ready and responding -5. **Updates** the state file with new process IDs - -## Development Workflow - -### Before this feature: -```bash -# Terminal 1: Start environment -just regtest - -# Terminal 2: Make code changes, then manually restart everything -# Ctrl+C in Terminal 1 (stops entire environment including Lightning network) -just regtest # Start everything again (slow) -``` - -### With this feature: -```bash -# Terminal 1: Start environment (once) -just regtest - -# Terminal 2: Make code changes, then quickly restart just the mints -just restart-mints # Fast! Keeps Lightning network running -just mint-test # Test your changes -``` - -## Benefits - -1. **Faster Development Cycle** - No need to restart the entire Lightning network -2. **Preserves Network State** - Bitcoin blockchain, Lightning channels, and node states remain intact -3. **Automatic Recompilation** - No need to manually run `cargo build` -4. **Status Validation** - Ensures mints are responding before completing -5. **State Management** - Updates process IDs for other commands to work correctly - -## Example Output - -``` -=============================== -Restarting CDK Mints -=============================== -Stopping existing mints... - Stopping CLN Mint (PID: 12345) - Stopping LND Mint (PID: 12346) -Recompiling cdk-mintd... -✓ Compilation successful -Starting CLN Mint... -Waiting for CLN mint to start... -✓ CLN Mint ready -Starting LND Mint... -Waiting for LND mint to start... -✓ LND Mint ready - -✅ Mints restarted successfully! - CLN Mint: http://127.0.0.1:8085 (PID: 54321) - LND Mint: http://127.0.0.1:8087 (PID: 54322) -=============================== -``` - -## Use Cases - -- **Testing mint code changes** without restarting the entire regtest environment -- **Debugging mint behavior** with fresh mint instances -- **Performance testing** with clean mint state but preserved Lightning network -- **Integration testing** after mint code modifications - -This feature makes the development experience much smoother when working on CDK mint functionality! diff --git a/justfile b/justfile index 7c403f97f..fe4b0f311 100644 --- a/justfile +++ b/justfile @@ -155,11 +155,6 @@ nutshell-wallet-itest: # Start interactive regtest environment (Bitcoin + 4 LN nodes + 2 CDK mints) regtest db="sqlite": - #!/usr/bin/env bash - ./misc/interactive_regtest.sh {{db}} - -# Start regtest with direct process management via mprocs (lets you start/stop mints) -regtest-mprocs db="sqlite": #!/usr/bin/env bash ./misc/interactive_regtest_mprocs.sh {{db}} diff --git a/misc/README.md b/misc/README.md index 51b19c358..a61e3242b 100644 --- a/misc/README.md +++ b/misc/README.md @@ -4,7 +4,7 @@ This directory contains scripts for setting up and interacting with a CDK regtes ## Scripts -### 1. `interactive_regtest.sh` +### 1. `interactive_regtest_mprocs.sh` Sets up a complete regtest environment with: - Bitcoin regtest node - 2 CLN (Core Lightning) nodes with channels @@ -52,7 +52,7 @@ Helper script providing convenient commands to interact with the running regtest 1. **Start the regtest environment:** ```bash - ./misc/interactive_regtest.sh [database_type] + ./misc/interactive_regtest_mprocs.sh [database_type] ``` - `database_type`: Optional, defaults to "sqlite". Can be "sqlite" or "redb" - The script will build necessary binaries and set up the full environment @@ -67,7 +67,7 @@ Helper script providing convenient commands to interact with the running regtest The interactive regtest environment uses a state file (`/tmp/cdk_regtest_env`) to share environment information between terminal sessions: -1. When you run `just regtest` or `./misc/interactive_regtest.sh`, it creates the state file with all necessary environment variables +1. When you run `just regtest` or `./misc/interactive_regtest_mprocs.sh`, it creates the state file with all necessary environment variables 2. When you run Lightning node commands in other terminals (e.g., `just ln-cln1 getinfo`), the helper script automatically sources the state file 3. When the environment shuts down (Ctrl+C), it cleans up the state file automatically @@ -198,7 +198,7 @@ $CDK_ITESTS_DIR/ ## Cleanup -- Press `Ctrl+C` in the terminal running `interactive_regtest.sh` +- Press `Ctrl+C` in the terminal running `interactive_regtest_mprocs.sh` - All processes will be terminated and the temporary directory will be cleaned up automatically - No manual cleanup is required @@ -211,7 +211,7 @@ $CDK_ITESTS_DIR/ ### Helper script not working - Ensure the regtest environment is running first -- The `CDK_ITESTS_DIR` environment variable must be set (done automatically by `interactive_regtest.sh`) +- The `CDK_ITESTS_DIR` environment variable must be set (done automatically by `interactive_regtest_mprocs.sh`) ### Connection issues - Use `./misc/regtest_helper.sh show-status` to check component health diff --git a/misc/interactive_regtest.sh b/misc/interactive_regtest.sh deleted file mode 100755 index e38b8fb41..000000000 --- a/misc/interactive_regtest.sh +++ /dev/null @@ -1,330 +0,0 @@ -#!/usr/bin/env bash - -# Interactive Regtest Environment for CDK -# This script sets up the regtest environment and keeps it running for interaction - -set -e - -# Function to wait for HTTP endpoint -wait_for_endpoint() { - local url=$1 - local timeout=${2:-60} - local start_time=$(date +%s) - - while true; do - local current_time=$(date +%s) - local elapsed_time=$((current_time - start_time)) - - if [ $elapsed_time -ge $timeout ]; then - echo "❌ Timeout waiting for $url" - return 1 - fi - - local http_status=$(curl -o /dev/null -s -w "%{http_code}" "$url" 2>/dev/null || echo "000") - - if [ "$http_status" -eq 200 ]; then - echo "✓ $url is ready" - return 0 - fi - - sleep 2 - done -} - -# Function to perform cleanup -cleanup() { - echo "Cleaning up..." - - # Remove state file for other sessions - rm -f "/tmp/cdk_regtest_env" - - if [ ! -z "$CDK_MINTD_PID" ] && kill -0 $CDK_MINTD_PID 2>/dev/null; then - echo "Killing the cdk mintd (CLN)" - kill -2 $CDK_MINTD_PID - wait $CDK_MINTD_PID - fi - - if [ ! -z "$CDK_MINTD_LND_PID" ] && kill -0 $CDK_MINTD_LND_PID 2>/dev/null; then - echo "Killing the cdk mintd (LND)" - kill -2 $CDK_MINTD_LND_PID - wait $CDK_MINTD_LND_PID - fi - - if [ ! -z "$CDK_REGTEST_PID" ] && kill -0 $CDK_REGTEST_PID 2>/dev/null; then - echo "Killing the cdk regtest" - kill -2 $CDK_REGTEST_PID - wait $CDK_REGTEST_PID - fi - - echo "Environment terminated" - - # Remove the temporary directory - if [ ! -z "$CDK_ITESTS_DIR" ]; then - rm -rf "$CDK_ITESTS_DIR" - echo "Temp directory removed: $CDK_ITESTS_DIR" - fi - - # Unset all environment variables - unset CDK_ITESTS_DIR - unset CDK_ITESTS_MINT_ADDR - unset CDK_ITESTS_MINT_PORT_0 - unset CDK_ITESTS_MINT_PORT_1 - unset CDK_MINTD_DATABASE - unset CDK_TEST_MINT_URL - unset CDK_TEST_MINT_URL_2 - unset CDK_MINTD_URL - unset CDK_MINTD_WORK_DIR - unset CDK_MINTD_LISTEN_HOST - unset CDK_MINTD_LISTEN_PORT - unset CDK_MINTD_LN_BACKEND - unset CDK_MINTD_MNEMONIC - unset CDK_MINTD_CLN_RPC_PATH - unset CDK_MINTD_LND_ADDRESS - unset CDK_MINTD_LND_CERT_FILE - unset CDK_MINTD_LND_MACAROON_FILE - unset CDK_MINTD_PID - unset CDK_MINTD_LND_PID - unset CDK_REGTEST_PID - unset RUST_BACKTRACE - unset CDK_TEST_REGTEST -} - -# Set up trap to call cleanup on script exit -trap cleanup EXIT - -export CDK_TEST_REGTEST=1 - -# Check for mprocs and offer to install if missing -if ! command -v mprocs >/dev/null 2>&1; then - echo "⚠️ mprocs not found - this tool provides a nice TUI for monitoring logs" - echo "Install it with: cargo install mprocs" - echo - read -p "Would you like to install mprocs now? (y/n): " -n 1 -r - echo - if [[ $REPLY =~ ^[Yy]$ ]]; then - echo "Installing mprocs..." - cargo install mprocs - if [ $? -eq 0 ]; then - echo "✓ mprocs installed successfully" - else - echo "❌ Failed to install mprocs. You can install it later with: cargo install mprocs" - fi - else - echo "Skipping mprocs installation. The environment will work without it." - fi - echo -fi - -# Parse command line arguments -CDK_MINTD_DATABASE=${1:-"sqlite"} # Default to sqlite if not specified - -# Create a temporary directory -export CDK_ITESTS_DIR=$(mktemp -d) -export CDK_ITESTS_MINT_ADDR="127.0.0.1" -export CDK_ITESTS_MINT_PORT_0=8085 -export CDK_ITESTS_MINT_PORT_1=8087 - -# Check if the temporary directory was created successfully -if [[ ! -d "$CDK_ITESTS_DIR" ]]; then - echo "Failed to create temp directory" - exit 1 -fi - -echo "==============================================" -echo "Starting Interactive CDK Regtest Environment" -echo "==============================================" -echo "Temp directory: $CDK_ITESTS_DIR" -echo "Database type: $CDK_MINTD_DATABASE" -echo - -export CDK_MINTD_DATABASE="$CDK_MINTD_DATABASE" - -# Build the necessary binaries -echo "Building binaries..." -cargo build -p cdk-integration-tests --bin start_regtest - -echo "Starting regtest network (Bitcoin + Lightning nodes)..." -cargo run --bin start_regtest & -export CDK_REGTEST_PID=$! - -# Create named pipe for progress tracking -mkfifo "$CDK_ITESTS_DIR/progress_pipe" -rm -f "$CDK_ITESTS_DIR/signal_received" - -# Start reading from pipe in background -(while read line; do - case "$line" in - "checkpoint1") - echo "✓ Regtest network is ready" - touch "$CDK_ITESTS_DIR/signal_received" - exit 0 - ;; - esac -done < "$CDK_ITESTS_DIR/progress_pipe") & - -# Wait for regtest setup (up to 120 seconds) -echo "Waiting for regtest network to be ready..." -for ((i=0; i<120; i++)); do - if [ -f "$CDK_ITESTS_DIR/signal_received" ]; then - break - fi - sleep 1 -done - -if [ ! -f "$CDK_ITESTS_DIR/signal_received" ]; then - echo "❌ Timeout waiting for regtest network" - exit 1 -fi - -echo -echo "Starting CDK Mint #1 (CLN backend)..." -export CDK_MINTD_CLN_RPC_PATH="$CDK_ITESTS_DIR/cln/one/regtest/lightning-rpc" -export CDK_MINTD_URL="http://$CDK_ITESTS_MINT_ADDR:$CDK_ITESTS_MINT_PORT_0" -export CDK_MINTD_WORK_DIR="$CDK_ITESTS_DIR/cln_mint" -export CDK_MINTD_LISTEN_HOST=$CDK_ITESTS_MINT_ADDR -export CDK_MINTD_LISTEN_PORT=$CDK_ITESTS_MINT_PORT_0 -export CDK_MINTD_LN_BACKEND="cln" -export CDK_MINTD_MNEMONIC="eye survey guilt napkin crystal cup whisper salt luggage manage unveil loyal" -export RUST_BACKTRACE=1 - -mkdir -p "$CDK_MINTD_WORK_DIR" -cargo run --bin cdk-mintd > "$CDK_MINTD_WORK_DIR/mintd.log" 2>&1 & -export CDK_MINTD_PID=$! - -# Wait for CLN mint to be ready -echo "Waiting for CLN mint to be ready..." -URL="http://$CDK_ITESTS_MINT_ADDR:$CDK_ITESTS_MINT_PORT_0/v1/info" -wait_for_endpoint "$URL" 60 - -echo -echo "Starting CDK Mint #2 (LND backend)..." -export CDK_MINTD_LND_ADDRESS="https://localhost:10010" -export CDK_MINTD_LND_CERT_FILE="$CDK_ITESTS_DIR/lnd/two/tls.cert" -export CDK_MINTD_LND_MACAROON_FILE="$CDK_ITESTS_DIR/lnd/two/data/chain/bitcoin/regtest/admin.macaroon" - -export CDK_MINTD_URL="http://$CDK_ITESTS_MINT_ADDR:$CDK_ITESTS_MINT_PORT_1" -mkdir -p "$CDK_ITESTS_DIR/lnd_mint" -export CDK_MINTD_WORK_DIR="$CDK_ITESTS_DIR/lnd_mint" -export CDK_MINTD_LISTEN_HOST=$CDK_ITESTS_MINT_ADDR -export CDK_MINTD_LISTEN_PORT=$CDK_ITESTS_MINT_PORT_1 -export CDK_MINTD_LN_BACKEND="lnd" -export CDK_MINTD_MNEMONIC="cattle gold bind busy sound reduce tone addict baby spend february strategy" - -cargo run --bin cdk-mintd > "$CDK_MINTD_WORK_DIR/mintd.log" 2>&1 & -export CDK_MINTD_LND_PID=$! - -# Wait for LND mint to be ready -echo "Waiting for LND mint to be ready..." -URL="http://$CDK_ITESTS_MINT_ADDR:$CDK_ITESTS_MINT_PORT_1/v1/info" -wait_for_endpoint "$URL" 60 - -# Set environment variables for easy access -export CDK_TEST_MINT_URL="http://$CDK_ITESTS_MINT_ADDR:$CDK_ITESTS_MINT_PORT_0" -export CDK_TEST_MINT_URL_2="http://$CDK_ITESTS_MINT_ADDR:$CDK_ITESTS_MINT_PORT_1" - -# Create state file for other terminal sessions -ENV_FILE="/tmp/cdk_regtest_env" -echo "export CDK_ITESTS_DIR=\"$CDK_ITESTS_DIR\"" > "$ENV_FILE" -echo "export CDK_TEST_MINT_URL=\"$CDK_TEST_MINT_URL\"" >> "$ENV_FILE" -echo "export CDK_TEST_MINT_URL_2=\"$CDK_TEST_MINT_URL_2\"" >> "$ENV_FILE" -echo "export CDK_MINTD_PID=\"$CDK_MINTD_PID\"" >> "$ENV_FILE" -echo "export CDK_MINTD_LND_PID=\"$CDK_MINTD_LND_PID\"" >> "$ENV_FILE" -echo "export CDK_REGTEST_PID=\"$CDK_REGTEST_PID\"" >> "$ENV_FILE" - -echo -echo "==============================================" -echo "🎉 CDK Regtest Environment is Ready!" -echo "==============================================" -echo -echo "Network Information:" -echo " • Bitcoin RPC: 127.0.0.1:18443 (user: testuser, pass: testpass)" -echo " • CLN Node 1: $CDK_ITESTS_DIR/cln/one/regtest/lightning-rpc" -echo " • CLN Node 2: $CDK_ITESTS_DIR/cln/two/regtest/lightning-rpc" -echo " • LND Node 1: https://localhost:10009" -echo " • LND Node 2: https://localhost:10010" -echo -echo "CDK Mints:" -echo " • CLN Mint: $CDK_TEST_MINT_URL" -echo " • LND Mint: $CDK_TEST_MINT_URL_2" -echo -echo "Files and Directories:" -echo " • Working Directory: $CDK_ITESTS_DIR" -echo " • CLN Mint Logs: $CDK_ITESTS_DIR/cln_mint/mintd.log" -echo " • LND Mint Logs: $CDK_ITESTS_DIR/lnd_mint/mintd.log" -echo " • LND 1 TLS Cert: $CDK_ITESTS_DIR/lnd/one/tls.cert" -echo " • LND 1 Macaroon: $CDK_ITESTS_DIR/lnd/one/data/chain/bitcoin/regtest/admin.macaroon" -echo " • LND 2 TLS Cert: $CDK_ITESTS_DIR/lnd/two/tls.cert" -echo " • LND 2 Macaroon: $CDK_ITESTS_DIR/lnd/two/data/chain/bitcoin/regtest/admin.macaroon" -echo -echo "Environment Variables (available in other terminals):" -echo " • CDK_TEST_MINT_URL=\"$CDK_TEST_MINT_URL\"" -echo " • CDK_TEST_MINT_URL_2=\"$CDK_TEST_MINT_URL_2\"" -echo " • CDK_ITESTS_DIR=\"$CDK_ITESTS_DIR\"" -echo -echo "You can now:" -echo " • Use 'just' commands in other terminals: 'just ln-cln1 getinfo'" -echo " • Run integration tests: 'just mint-test' or 'cargo test -p cdk-integration-tests'" -echo " • Use CDK CLI tools with the mint URLs above" -echo " • Interact with Lightning nodes directly" -echo " • Access Bitcoin regtest node" -echo -echo "State File: /tmp/cdk_regtest_env (allows other terminals to find this environment)" -echo -echo "Starting mprocs to monitor logs..." -echo "Press 'q' to quit mprocs and stop the environment" -echo "==============================================" - -# Create mprocs configuration -MPROCS_CONFIG="$CDK_ITESTS_DIR/mprocs.yaml" -cat > "$MPROCS_CONFIG" << EOF -procs: - cln-mint: - shell: "touch $CDK_ITESTS_DIR/cln_mint/mintd.log && tail -f $CDK_ITESTS_DIR/cln_mint/mintd.log" - autostart: true - - lnd-mint: - shell: "touch $CDK_ITESTS_DIR/lnd_mint/mintd.log && tail -f $CDK_ITESTS_DIR/lnd_mint/mintd.log" - autostart: true - - bitcoind: - shell: "touch $CDK_ITESTS_DIR/bitcoin/regtest/debug.log && tail -f $CDK_ITESTS_DIR/bitcoin/regtest/debug.log" - autostart: true - - cln-one: - shell: "while [ ! -f $CDK_ITESTS_DIR/cln/one/regtest/log ]; do sleep 1; done && tail -f $CDK_ITESTS_DIR/cln/one/regtest/log" - autostart: true - - cln-two: - shell: "while [ ! -f $CDK_ITESTS_DIR/cln/two/regtest/log ]; do sleep 1; done && tail -f $CDK_ITESTS_DIR/cln/two/regtest/log" - autostart: true - - lnd-one: - shell: "while [ ! -f $CDK_ITESTS_DIR/lnd/one/logs/bitcoin/regtest/lnd.log ]; do sleep 1; done && tail -f $CDK_ITESTS_DIR/lnd/one/logs/bitcoin/regtest/lnd.log" - autostart: true - - lnd-two: - shell: "while [ ! -f $CDK_ITESTS_DIR/lnd/two/logs/bitcoin/regtest/lnd.log ]; do sleep 1; done && tail -f $CDK_ITESTS_DIR/lnd/two/logs/bitcoin/regtest/lnd.log" - autostart: true - -settings: - mouse_scroll_speed: 3 - proc_list_width: 20 - hide_keymap_window: false -EOF - -# Wait a bit for log files to be created -sleep 2 - -# Start mprocs to show all logs -if command -v mprocs >/dev/null 2>&1; then - cd "$CDK_ITESTS_DIR" - mprocs --config "$MPROCS_CONFIG" -else - echo "⚠️ mprocs not found. Install it with: cargo install mprocs" - echo "Falling back to simple wait loop..." - echo "Press Ctrl+C to stop the environment" - # Keep the script running - while true; do - sleep 1 - done -fi diff --git a/misc/interactive_regtest_mprocs.sh b/misc/interactive_regtest_mprocs.sh index 8f486fb63..a81a7c31d 100755 --- a/misc/interactive_regtest_mprocs.sh +++ b/misc/interactive_regtest_mprocs.sh @@ -270,14 +270,14 @@ cat > "$MPROCS_CONFIG" << EOF procs: cln-mint: shell: "$CDK_ITESTS_DIR/start_cln_mint.sh" - autostart: false + autostart: true env: CDK_ITESTS_DIR: "$CDK_ITESTS_DIR" CDK_MINTD_DATABASE: "$CDK_MINTD_DATABASE" lnd-mint: shell: "$CDK_ITESTS_DIR/start_lnd_mint.sh" - autostart: false + autostart: true env: CDK_ITESTS_DIR: "$CDK_ITESTS_DIR" CDK_MINTD_DATABASE: "$CDK_MINTD_DATABASE" diff --git a/misc/regtest_helper.sh b/misc/regtest_helper.sh index c0442c41b..5e366825d 100755 --- a/misc/regtest_helper.sh +++ b/misc/regtest_helper.sh @@ -1,7 +1,7 @@ #!/usr/bin/env bash # Helper script for interacting with CDK regtest environment -# Run this after starting interactive_regtest.sh +# Run this after starting interactive_regtest_mprocs.sh # Check for environment state file first, then environment variable ENV_FILE="/tmp/cdk_regtest_env" @@ -17,14 +17,14 @@ elif [ ! -z "$CDK_ITESTS_DIR" ]; then echo "export CDK_REGTEST_PID=\"$CDK_REGTEST_PID\"" >> "$ENV_FILE" else echo "❌ CDK regtest environment not found!" - echo "Please run './misc/interactive_regtest.sh' or 'just regtest' first" + echo "Please run './misc/interactive_regtest_mprocs.sh' or 'just regtest' first" exit 1 fi # Validate that the environment is actually running if [ -z "$CDK_ITESTS_DIR" ] || [ ! -d "$CDK_ITESTS_DIR" ]; then echo "❌ CDK regtest environment not found or directory missing!" - echo "Please run './misc/interactive_regtest.sh' or 'just regtest' first" + echo "Please run './misc/interactive_regtest_mprocs.sh' or 'just regtest' first" [ -f "$ENV_FILE" ] && rm "$ENV_FILE" # Clean up stale state file exit 1 fi From a97eb84db6b79fee3657e47e36a0471cb491ab85 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Tue, 8 Jul 2025 11:09:20 +0100 Subject: [PATCH 015/321] chore: update docs --- DEVELOPMENT.md | 23 ++++ MPROCS_INTEGRATION.md | 147 ----------------------- MPROCS_MODES.md | 132 --------------------- REGTEST_GUIDE.md | 267 ++++++++++++++++++++++++++++++++++++++++++ REGTEST_QUICKSTART.md | 125 -------------------- misc/README.md | 218 ---------------------------------- 6 files changed, 290 insertions(+), 622 deletions(-) delete mode 100644 MPROCS_INTEGRATION.md delete mode 100644 MPROCS_MODES.md create mode 100644 REGTEST_GUIDE.md delete mode 100644 REGTEST_QUICKSTART.md delete mode 100644 misc/README.md diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 1306fbc91..0d24c69d4 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -69,6 +69,29 @@ If the Nix installation is in multi-user mode, don’t forget to restart the nix nix develop -c $SHELL ``` +## Regtest Environment + +For testing and development, CDK provides a complete regtest environment with Bitcoin, Lightning Network nodes, and CDK mints. + +### Quick Start +```bash +just regtest # Starts full environment with mprocs TUI +``` + +This provides: +- Bitcoin regtest node +- 4 Lightning Network nodes (2 CLN + 2 LND) +- 2 CDK mints (one connected to CLN, one to LND) +- Real-time log monitoring via mprocs +- Helper commands for testing Lightning payments and CDK operations + +### Comprehensive Guide +See [REGTEST_GUIDE.md](REGTEST_GUIDE.md) for complete documentation including: +- Detailed setup and usage instructions +- Development workflows and testing scenarios +- mprocs TUI interface guide +- Troubleshooting and advanced usage + ## Common Development Tasks ### Building the Project diff --git a/MPROCS_INTEGRATION.md b/MPROCS_INTEGRATION.md deleted file mode 100644 index 79aee0fe7..000000000 --- a/MPROCS_INTEGRATION.md +++ /dev/null @@ -1,147 +0,0 @@ -# mprocs Integration for CDK Regtest - -The CDK regtest environment now integrates with `mprocs` to provide a beautiful TUI (Terminal User Interface) for monitoring all component logs in real-time. - -## What is mprocs? - -`mprocs` is a TUI for running multiple processes and monitoring their output. Perfect for development environments where you need to watch logs from multiple services simultaneously. - -## Features - -### Automatic Setup -- The regtest script checks for `mprocs` and offers to install it if missing -- Creates a dynamic mprocs configuration with all relevant log files -- Handles missing log files gracefully (waits for them to be created) - -### Components Monitored -- **cln-mint**: CDK mint connected to CLN -- **lnd-mint**: CDK mint connected to LND -- **bitcoind**: Bitcoin regtest node -- **cln-one**: Core Lightning node #1 -- **cln-two**: Core Lightning node #2 -- **lnd-one**: LND node #1 -- **lnd-two**: LND node #2 - -### Key Benefits -- **Real-time log monitoring** for all components -- **Side-by-side view** of related services -- **Easy navigation** between different logs -- **Scrollback** to review history -- **Search functionality** within logs -- **Process management** (start/stop/restart individual processes) - -## Usage - -### Automatic (Recommended) - Log Tailing Mode -```bash -just regtest -# After setup completes, mprocs launches automatically -# Mints start and log to files, mprocs shows log contents -``` - -### Direct Process Management Mode -```bash -just regtest-mprocs -# After setup, mprocs starts with mint processes stopped -# Use 's' key to start individual mints -# Full process control from within mprocs -``` - -### Manual Launch -```bash -# Start environment without mprocs -just regtest - -# In another terminal, launch mprocs -just regtest-logs -``` - -### Commands Available -```bash -just regtest # Starts environment and mprocs (log tailing mode) -just regtest-mprocs # Starts environment with direct process management -just regtest-logs # Manual mprocs launch (adapts to current mode) -``` - -## mprocs Controls - -### Direct Process Management Mode: -- **Arrow keys**: Navigate between processes -- **s**: Start the selected process -- **k**: Kill the selected process -- **r**: Restart the selected process -- **Enter**: Focus on selected process -- **Tab**: Switch between process list and log view -- **?**: Show help -- **q**: Quit mprocs (stops all managed processes) - -### Log Tailing Mode: -- **Arrow keys**: Navigate between processes -- **Enter**: Focus on selected process -- **Tab**: Switch between process list and log view -- **PageUp/PageDown**: Scroll through logs -- **Ctrl+C**: Interrupt current process -- **q**: Quit mprocs (processes continue running) - -## Installation - -If `mprocs` is not installed: -```bash -# Automatic installation prompt when running regtest -just regtest - -# Manual installation -cargo install mprocs - -# Or via package manager (varies by OS) -# Ubuntu/Debian: apt install mprocs -# macOS: brew install mprocs -``` - -## Configuration - -The mprocs configuration is automatically generated at `$CDK_ITESTS_DIR/mprocs.yaml`. It includes: - -- Proper log file paths for all components -- Graceful handling of missing files -- Optimized UI settings for development -- Auto-start for all monitoring processes - -## Development Workflow - -### Before mprocs: -- Start regtest environment -- Open multiple terminals to `tail -f` different log files -- Manually manage multiple windows/panes -- Switch between terminals to see different components - -### With mprocs: -- Start regtest environment → automatic log monitoring -- Single TUI shows all component logs -- Easy navigation between components -- Professional development experience - -## Example View - -``` -┌─Processes─────────┬─Output───────────────────────────────────────┐ -│ ● cln-mint │ 2024-07-08T08:30:12 INFO cdk_mintd: Starting │ -│ ● lnd-mint │ mint server on 127.0.0.1:8085 │ -│ ● bitcoind │ 2024-07-08T08:30:13 INFO: New invoice │ -│ ● cln-one │ received for 1000 sats │ -│ ● cln-two │ 2024-07-08T08:30:14 INFO: Payment │ -│ ● lnd-one │ successful │ -│ ● lnd-two │ │ -│ │ │ -└───────────────────┴──────────────────────────────────────────────┘ -``` - -## Fallback - -If mprocs is not available or fails: -- Environment continues to work normally -- Falls back to simple wait loop -- All `just` commands work as expected -- Logs still accessible via `just regtest-logs` - -This integration makes CDK development much more pleasant by providing professional-grade log monitoring out of the box! 🎉 diff --git a/MPROCS_MODES.md b/MPROCS_MODES.md deleted file mode 100644 index 06faea0ef..000000000 --- a/MPROCS_MODES.md +++ /dev/null @@ -1,132 +0,0 @@ -# mprocs Process Management Modes - -The CDK regtest environment now supports two different modes for managing processes with mprocs: - -## Mode 1: Log Tailing (Default) -**Command**: `just regtest` - -### How it works: -- Mints are started by the bash script and run in the background -- Mints write their output to log files (`mintd.log`) -- mprocs uses `tail -f` to follow these log files -- Log files persist even after mprocs exits - -### Pros: -- ✅ Log files are preserved for later analysis -- ✅ Simple setup -- ✅ Works even if mprocs crashes - -### Cons: -- ❌ Cannot restart mints from within mprocs -- ❌ Must use external commands to control mints -- ❌ mprocs shows file contents, not live processes - -## Mode 2: Direct Process Management -**Command**: `just regtest-mprocs` - -### How it works: -- mprocs directly manages the mint processes -- Mints are started/stopped by mprocs itself -- Output goes directly to mprocs (no log files by default) -- Full process control from within mprocs - -### Pros: -- ✅ Start/stop/restart mints directly from mprocs -- ✅ Live process output -- ✅ Better development workflow -- ✅ Process status indicators - -### Cons: -- ❌ Output not saved to files (unless configured) -- ❌ If mprocs crashes, you lose the processes - -## mprocs Controls - -### Direct Process Management Mode: -- **Arrow keys**: Navigate between processes -- **s**: Start the selected process -- **k**: Kill the selected process -- **r**: Restart the selected process -- **Enter**: Focus on a process (see its output) -- **Tab**: Switch between process list and output -- **?**: Show help -- **q**: Quit mprocs (stops all managed processes) - -### Log Tailing Mode: -- **Arrow keys**: Navigate between log sources -- **Enter**: Focus on a log source -- **Tab**: Switch between process list and log view -- **PageUp/PageDown**: Scroll through logs -- **q**: Quit mprocs (processes continue running) - -## Usage Examples - -### Start with Log Tailing (Original Mode) -```bash -just regtest -# Mints start automatically and log to files -# mprocs shows log contents -# Use Ctrl+C or 'q' to exit mprocs -# Processes continue running in background -``` - -### Start with Direct Process Management -```bash -just regtest-mprocs -# Only Lightning network starts automatically -# In mprocs, navigate to "cln-mint" and press 's' to start it -# Navigate to "lnd-mint" and press 's' to start it -# Use 'r' to restart mints after code changes -# Use 'q' to exit and stop all processes -``` - -### Switch Between Modes - -If you started with log tailing mode, you can access the direct management: -```bash -# In another terminal -source /tmp/cdk_regtest_env -just regtest-logs # This will detect the mode and adapt -``` - -## Development Workflow Comparison - -### Traditional (Log Tailing): -1. `just regtest` -2. Make code changes -3. In another terminal: `just restart-mints` -4. Check logs in mprocs - -### Direct Management: -1. `just regtest-mprocs` -2. Press 's' to start mints -3. Make code changes -4. In mprocs: press 'r' on each mint to restart -5. Watch live output directly - -## Technical Details - -### Project Root Handling -The direct process management mode ensures that: -- Startup scripts change to the correct project root directory -- Cargo commands run from where the `Cargo.toml` file is located -- Environment variables are properly set before starting processes - -### File Structure -``` -$CDK_ITESTS_DIR/ -├── start_cln_mint.sh # Sets PROJECT_ROOT and runs cargo from there -├── start_lnd_mint.sh # Sets PROJECT_ROOT and runs cargo from there -└── mprocs.yaml # Points to the startup scripts -``` - -Each startup script: -1. Changes to the project root directory (`cd "$PROJECT_ROOT"`) -2. Sets all required environment variables -3. Executes `cargo run --bin cdk-mintd` from the correct location - -The environment variables and helper commands work the same in both modes: -- `just ln-cln1 getinfo` -- `just btc-mine 5` -- `just mint-info` -- etc. diff --git a/REGTEST_GUIDE.md b/REGTEST_GUIDE.md new file mode 100644 index 000000000..91958648e --- /dev/null +++ b/REGTEST_GUIDE.md @@ -0,0 +1,267 @@ +# CDK Regtest Environment Guide + +A comprehensive guide for setting up and using the CDK regtest environment for development and testing. + +## Quick Start + +### Start the Environment +```bash +# Start regtest with SQLite database (default) +just regtest + +# Or with REDB database +just regtest redb +``` + +The script will: +1. Check for `mprocs` and offer to install it if missing +2. Build necessary binaries +3. Set up Bitcoin regtest + 4 Lightning nodes + 2 CDK mints +4. Launch `mprocs` TUI showing all component logs +5. Both mints start automatically + +### Stop the Environment +Press `q` in mprocs or `Ctrl+C` in the terminal. Everything cleans up automatically. + +## Network Components + +When running, you get a complete Lightning Network environment: + +### Bitcoin Network +- **Bitcoin RPC**: `127.0.0.1:18443` (user: `testuser`, pass: `testpass`) + +### Lightning Nodes +- **CLN Node 1**: `$CDK_ITESTS_DIR/cln/one/regtest/lightning-rpc` +- **CLN Node 2**: `$CDK_ITESTS_DIR/cln/two/regtest/lightning-rpc` +- **LND Node 1**: `https://localhost:10009` +- **LND Node 2**: `https://localhost:10010` + +### CDK Mints +- **CLN Mint**: `http://127.0.0.1:8085` (connected to CLN node 1) +- **LND Mint**: `http://127.0.0.1:8087` (connected to LND node 2) + +### Environment Variables +Available in all terminals automatically: +- `CDK_TEST_MINT_URL`: CLN mint URL +- `CDK_TEST_MINT_URL_2`: LND mint URL +- `CDK_ITESTS_DIR`: Temporary directory with all data + +## Using the Environment + +All commands work from any terminal - they automatically find the running environment. + +### Lightning Node Operations +```bash +# Get node information +just ln-cln1 getinfo +just ln-cln2 getinfo +just ln-lnd1 getinfo +just ln-lnd2 getinfo + +# Create and pay invoices +just ln-cln1 invoice 1000 label "Test payment" +just ln-lnd1 payinvoice + +# Check balances and channels +just ln-cln1 listfunds +just ln-lnd1 listchannels +``` + +### Bitcoin Operations +```bash +just btc getblockchaininfo # Blockchain status +just btc getbalance # Wallet balance +just btc-mine 5 # Mine 5 blocks +``` + +### CDK Mint Operations +```bash +just mint-info # Show both mints' info +just mint-test # Run integration tests +just restart-mints # Recompile and restart mints +just regtest-status # Check all components +just regtest-logs # Show recent logs +``` + +## mprocs TUI Interface + +The `mprocs` interface shows all component logs in real-time: + +### Controls +- **Arrow keys**: Navigate between processes +- **Enter**: Focus on a process to see its output +- **Tab**: Switch between process list and output view +- **s**: Start a process (if stopped) +- **k**: Kill a process +- **r**: Restart a process +- **PageUp/PageDown**: Scroll through logs +- **?**: Show help +- **q**: Quit and stop environment + +### Process List +- `cln-mint`: CDK mint connected to CLN (auto-started) +- `lnd-mint`: CDK mint connected to LND (auto-started) +- `bitcoind`: Bitcoin regtest node logs +- `cln-one`: CLN node 1 logs +- `cln-two`: CLN node 2 logs +- `lnd-one`: LND node 1 logs +- `lnd-two`: LND node 2 logs + +## Development Workflows + +### Testing Lightning Payment Flow +```bash +# Terminal 1: Start environment +just regtest + +# Terminal 2: Create invoice and pay +just ln-cln1 invoice 1000 test "Test payment" +just ln-lnd1 payinvoice +just ln-cln1 listinvoices +just ln-lnd1 listpayments +``` + +### Developing Mint Code +```bash +# Terminal 1: Keep regtest running +just regtest + +# Terminal 2: After making code changes +just restart-mints # Recompiles and restarts both mints +just mint-info # Test the changes +just mint-test # Run integration tests +``` + +### Using CDK CLI Tools +```bash +# Terminal 1: Start environment +just regtest + +# Terminal 2: Use environment variables +cargo run --bin cdk-cli -- --mint-url $CDK_TEST_MINT_URL mint-info +cargo run --bin cdk-cli -- --mint-url $CDK_TEST_MINT_URL_2 mint-info +``` + +### Direct API Testing +```bash +# Query mint info directly +curl $CDK_TEST_MINT_URL/v1/info | jq +curl $CDK_TEST_MINT_URL/v1/keysets | jq + +# Test both mints +curl http://127.0.0.1:8085/v1/info | jq +curl http://127.0.0.1:8087/v1/info | jq +``` + +## File Structure + +All components run in a temporary directory: + +``` +$CDK_ITESTS_DIR/ +├── bitcoin/ # Bitcoin regtest data +├── cln/ +│ ├── one/ # CLN node 1 data +│ └── two/ # CLN node 2 data +├── lnd/ +│ ├── one/ # LND node 1 data +│ │ ├── tls.cert +│ │ └── data/chain/bitcoin/regtest/admin.macaroon +│ └── two/ # LND node 2 data +├── cln_mint/ # CLN mint working directory +├── lnd_mint/ # LND mint working directory +├── start_cln_mint.sh # Mint startup scripts +├── start_lnd_mint.sh +└── mprocs.yaml # mprocs configuration +``` + +## Installation Requirements + +### mprocs (TUI Interface) +If not installed, the script will offer to install it: +```bash +# Automatic installation during regtest setup +just regtest + +# Manual installation +cargo install mprocs + +# Or via package manager +# Ubuntu/Debian: apt install mprocs +# macOS: brew install mprocs +``` + +### System Dependencies +Managed automatically via Nix development shell: +- Bitcoin Core +- Core Lightning (CLN) +- LND (Lightning Network Daemon) +- Rust toolchain + +## Advanced Usage + +### Manual mprocs Launch +```bash +# If you need to restart just the mprocs interface +source /tmp/cdk_regtest_env +just regtest-logs +``` + +### Environment State +The environment creates a state file at `/tmp/cdk_regtest_env` that: +- Shares environment variables between terminals +- Allows `just` commands to work from anywhere +- Automatically cleaned up when environment stops + +### Process Management +From within mprocs: +- Restart individual mints after code changes +- Monitor specific component logs +- Start/stop services for testing scenarios + +## Troubleshooting + +### Environment Not Starting +- Check that ports are available: 8085, 8087, 18443, 19846, 19847, 10009, 10010 +- Ensure the Nix development shell is active: `nix develop` +- Check individual component logs in mprocs + +### Helper Commands Not Working +- Ensure the regtest environment is running +- Check that `/tmp/cdk_regtest_env` file exists +- Verify environment variables are set: `echo $CDK_TEST_MINT_URL` + +### Connection Issues +- Use `just regtest-status` to check component health +- Check mint logs with `just regtest-logs` +- Verify Lightning node status with `just ln-cln1 getinfo` + +### mprocs Issues +- If mprocs crashes, processes continue running +- Use `Ctrl+C` in the original terminal to clean up +- Restart with `just regtest-logs` + +## Common Error Solutions + +### "Port already in use" +```bash +# Find and kill processes using ports +sudo lsof -ti:8085 | xargs kill -9 +sudo lsof -ti:8087 | xargs kill -9 +``` + +### "Environment not found" +```bash +# Clean up and restart +rm -f /tmp/cdk_regtest_env +just regtest +``` + +### "Binary not found" +```bash +# Rebuild binaries +just build +just regtest +``` + +This environment provides everything needed for CDK development and testing in a single, easy-to-use interface! 🎉 diff --git a/REGTEST_QUICKSTART.md b/REGTEST_QUICKSTART.md deleted file mode 100644 index f02bedf67..000000000 --- a/REGTEST_QUICKSTART.md +++ /dev/null @@ -1,125 +0,0 @@ -# CDK Interactive Regtest - Quick Start - -A simple guide to get up and running with the interactive regtest environment. - -## Start Environment - -```bash -# Terminal 1: Start regtest with default sqlite database -just regtest - -# Or with redb database -just regtest redb -``` - -The script will: -1. Check for `mprocs` and offer to install it if missing -2. Set up the regtest environment (Bitcoin + Lightning nodes + CDK mints) -3. Launch `mprocs` showing logs from all components -4. Press 'q' in mprocs to quit and stop the environment - -## Use Lightning Nodes (in any other terminal) - -The `just` commands work from any terminal - they automatically find the running environment. - -### Get Node Information -```bash -just ln-cln1 getinfo # CLN node 1 -just ln-cln2 getinfo # CLN node 2 -just ln-lnd1 getinfo # LND node 1 -just ln-lnd2 getinfo # LND node 2 -``` - -### Create and Pay Invoices -```bash -# Create 1000 sat invoice on CLN -just ln-cln1 invoice 1000 test_label "Test payment" - -# Pay invoice with LND (use the bolt11 from above) -just ln-lnd1 payinvoice lnbcrt10u1... - -# Check balances -just ln-cln1 listfunds -just ln-lnd1 listchannels -``` - -## Bitcoin Operations - -```bash -just btc getblockchaininfo # Blockchain status -just btc getbalance # Wallet balance -just btc-mine 5 # Mine 5 blocks -``` - -## CDK Mint Operations - -```bash -just mint-info # Show both mints' info -just mint-test # Run integration tests -just restart-mints # Stop, recompile, and restart mints -just regtest-status # Check all components -just regtest-logs # Show recent logs -just regtest-mprocs # Start mprocs TUI (if not already running) -``` - -## Stop Environment - -Press `Ctrl+C` in the terminal running `just regtest`. Everything will be cleaned up automatically. - -## Available Endpoints - -- **CLN Mint**: http://127.0.0.1:8085 -- **LND Mint**: http://127.0.0.1:8087 -- **Bitcoin RPC**: 127.0.0.1:18443 (testuser/testpass) - -## Common Workflows - -### Test Lightning Payment Flow -```bash -# Terminal 1 -just regtest - -# Terminal 2 -just ln-cln1 invoice 1000 test "Test payment" -# Copy the bolt11 invoice - -just ln-lnd1 payinvoice -just ln-cln1 listinvoices -just ln-lnd1 listpayments -``` - -### Test CDK Integration -```bash -# Terminal 1 -just regtest - -# Terminal 2 -just mint-test # Run all tests -cargo test -p cdk-integration-tests # Or specific tests -``` - -### Development with CDK CLI -```bash -# Terminal 1 -just regtest - -# Terminal 2 - use environment variables -echo $CDK_TEST_MINT_URL # CLN mint URL -echo $CDK_TEST_MINT_URL_2 # LND mint URL - -# Use with CDK CLI -cargo run --bin cdk-cli -- --mint-url $CDK_TEST_MINT_URL mint-info -``` - -### Development Workflow (Mint Code Changes) -```bash -# Terminal 1: Keep regtest running -just regtest - -# Terminal 2: Make changes to mint code, then -just restart-mints # Recompiles and restarts both mints -just mint-info # Test the changes -just mint-test # Run integration tests -``` - -That's it! The environment provides a full Lightning Network with CDK mints for testing and development. diff --git a/misc/README.md b/misc/README.md deleted file mode 100644 index a61e3242b..000000000 --- a/misc/README.md +++ /dev/null @@ -1,218 +0,0 @@ -# CDK Interactive Regtest Environment - -This directory contains scripts for setting up and interacting with a CDK regtest environment for development and testing. - -## Scripts - -### 1. `interactive_regtest_mprocs.sh` -Sets up a complete regtest environment with: -- Bitcoin regtest node -- 2 CLN (Core Lightning) nodes with channels -- 2 LND nodes with channels -- 2 CDK mint instances (one connected to CLN, one to LND) - -Unlike `itests.sh`, this script keeps the environment running for interactive use and creates a state file (`/tmp/cdk_regtest_env`) that allows other terminal sessions to find and interact with the environment. - -### 2. `regtest_helper.sh` -Helper script providing convenient commands to interact with the running regtest environment. Automatically detects the environment using the state file. - -## Quick Start - -### Using `just` (Recommended) - -1. **Start the regtest environment:** - ```bash - just regtest [database_type] - ``` - - `database_type`: Optional, defaults to "sqlite". Can be "sqlite" or "redb" - - The script will check for `mprocs` and offer to install it if missing - - After setup, it will launch `mprocs` showing logs from all nodes and mints - - Press 'q' in mprocs to quit and stop the environment - -2. **In another terminal, interact with Lightning nodes:** - ```bash - # Get node information - just ln-cln1 getinfo - just ln-lnd1 getinfo - - # Mine some blocks - just btc-mine 5 - - # Check mint status - just mint-info - - # Start mprocs log viewer in another terminal - just regtest-mprocs - - # See all available commands - just --list - ``` - -### Using Scripts Directly - -1. **Start the regtest environment:** - ```bash - ./misc/interactive_regtest_mprocs.sh [database_type] - ``` - - `database_type`: Optional, defaults to "sqlite". Can be "sqlite" or "redb" - - The script will build necessary binaries and set up the full environment - - Keep this terminal open - the environment runs until you press Ctrl+C - -2. **In another terminal, use the helper script:** - ```bash - ./misc/regtest_helper.sh help - ``` - -## How It Works - -The interactive regtest environment uses a state file (`/tmp/cdk_regtest_env`) to share environment information between terminal sessions: - -1. When you run `just regtest` or `./misc/interactive_regtest_mprocs.sh`, it creates the state file with all necessary environment variables -2. When you run Lightning node commands in other terminals (e.g., `just ln-cln1 getinfo`), the helper script automatically sources the state file -3. When the environment shuts down (Ctrl+C), it cleans up the state file automatically - -This allows you to use `just` commands from any terminal without needing to export environment variables manually. - -## Environment Details - -When running, the environment provides: - -### Network Endpoints -- **Bitcoin RPC**: `127.0.0.1:18443` (user: `testuser`, pass: `testpass`) -- **CLN Node 1**: Unix socket at `$CDK_ITESTS_DIR/cln/one/regtest/lightning-rpc` -- **CLN Node 2**: Unix socket at `$CDK_ITESTS_DIR/cln/two/regtest/lightning-rpc` -- **LND Node 1**: HTTPS on `localhost:10009` -- **LND Node 2**: HTTPS on `localhost:10010` - -### CDK Mints -- **CLN Mint**: `http://127.0.0.1:8085` (connected to CLN node 1) -- **LND Mint**: `http://127.0.0.1:8087` (connected to LND node 2) - -### Environment Variables -The following variables are exported for easy access: -- `CDK_TEST_MINT_URL`: CLN mint URL -- `CDK_TEST_MINT_URL_2`: LND mint URL -- `CDK_ITESTS_DIR`: Temporary directory with all data - -## Usage Examples - -### Using `just` Commands (Recommended) - -```bash -# Start the environment -just regtest - -# In another terminal: -# Get Lightning node info -just ln-cln1 getinfo -just ln-cln2 getinfo -just ln-lnd1 getinfo -just ln-lnd2 getinfo - -# Create and pay invoices -just ln-cln1 invoice 1000 label description -just ln-lnd1 payinvoice - -# Bitcoin operations -just btc getblockchaininfo -just btc-mine 10 -just btc getbalance - -# CDK operations -just mint-info -just mint-test -just restart-mints # Stop, recompile, and restart mints -just regtest-status -just regtest-logs # Show recent logs -just regtest-mprocs # Start mprocs TUI log viewer -``` - -### Using Helper Script Directly - -```bash -# Lightning Node Operations -./misc/regtest_helper.sh ln-cln1 getinfo -./misc/regtest_helper.sh ln-lnd1 getinfo -./misc/regtest_helper.sh ln-cln1 invoice 1000 label description -./misc/regtest_helper.sh ln-lnd1 payinvoice - -# Bitcoin Operations -./misc/regtest_helper.sh btc getblockchaininfo -./misc/regtest_helper.sh btc-mine 10 -./misc/regtest_helper.sh btc getbalance - -# CDK Mint Operations -./misc/regtest_helper.sh mint-info -./misc/regtest_helper.sh mint-test -./misc/regtest_helper.sh restart-mints -./misc/regtest_helper.sh show-status -``` - -### Legacy Examples (for reference) - -### Direct API Access -```bash -# Query mint info directly -curl http://127.0.0.1:8085/v1/info | jq - -# Get mint keysets -curl http://127.0.0.1:8085/v1/keysets | jq -``` - -### Development Workflow -```bash -# Terminal 1: Start environment -just regtest - -# Terminal 2: Development and testing -just ln-cln1 getinfo # Check CLN status -just mint-info # Check mint status -just mint-test # Run integration tests - -# Or use CDK CLI tools directly with the mint URLs -# The environment sets CDK_TEST_MINT_URL and CDK_TEST_MINT_URL_2 -cargo run --bin cdk-cli -- --mint-url $CDK_TEST_MINT_URL mint-info -``` - -## File Locations - -All files are stored in a temporary directory (`$CDK_ITESTS_DIR`): -``` -$CDK_ITESTS_DIR/ -├── bitcoin/ # Bitcoin regtest data -├── cln/ -│ ├── one/ # CLN node 1 data -│ └── two/ # CLN node 2 data -├── lnd/ -│ ├── one/ # LND node 1 data -│ │ ├── tls.cert -│ │ └── data/chain/bitcoin/regtest/admin.macaroon -│ └── two/ # LND node 2 data -│ ├── tls.cert -│ └── data/chain/bitcoin/regtest/admin.macaroon -├── cln_mint/ # CLN mint working directory -│ └── mintd.log -└── lnd_mint/ # LND mint working directory - └── mintd.log -``` - -## Cleanup - -- Press `Ctrl+C` in the terminal running `interactive_regtest_mprocs.sh` -- All processes will be terminated and the temporary directory will be cleaned up automatically -- No manual cleanup is required - -## Troubleshooting - -### Environment not starting -- Check that ports 8085, 8087, 18443, 19846, 19847, 10009, 10010 are available -- Ensure you have the necessary dependencies (Bitcoin Core, CLN, LND) available -- Check the logs in `$CDK_ITESTS_DIR/cln_mint/mintd.log` and `$CDK_ITESTS_DIR/lnd_mint/mintd.log` - -### Helper script not working -- Ensure the regtest environment is running first -- The `CDK_ITESTS_DIR` environment variable must be set (done automatically by `interactive_regtest_mprocs.sh`) - -### Connection issues -- Use `./misc/regtest_helper.sh show-status` to check component health -- Check mint logs with `./misc/regtest_helper.sh show-logs` From ea0b696db9eeac0ddf6e31ad8c53b6d34562c19b Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Tue, 8 Jul 2025 11:33:21 +0100 Subject: [PATCH 016/321] fix: cln mprocs logging --- crates/cdk-integration-tests/Cargo.toml | 2 +- misc/interactive_regtest_mprocs.sh | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/crates/cdk-integration-tests/Cargo.toml b/crates/cdk-integration-tests/Cargo.toml index a824321a3..26a9da986 100644 --- a/crates/cdk-integration-tests/Cargo.toml +++ b/crates/cdk-integration-tests/Cargo.toml @@ -35,7 +35,7 @@ uuid.workspace = true serde.workspace = true serde_json.workspace = true # ln-regtest-rs = { path = "../../../../ln-regtest-rs" } -ln-regtest-rs = { git = "https://github.com/thesimplekid/ln-regtest-rs", rev = "ed24716" } +ln-regtest-rs = { git = "https://github.com/thesimplekid/ln-regtest-rs", rev = "df81424" } lightning-invoice.workspace = true tracing.workspace = true tracing-subscriber.workspace = true diff --git a/misc/interactive_regtest_mprocs.sh b/misc/interactive_regtest_mprocs.sh index a81a7c31d..72aceef72 100755 --- a/misc/interactive_regtest_mprocs.sh +++ b/misc/interactive_regtest_mprocs.sh @@ -287,11 +287,11 @@ procs: autostart: true cln-one: - shell: "while [ ! -f $CDK_ITESTS_DIR/cln/one/regtest/log ]; do sleep 1; done && tail -f $CDK_ITESTS_DIR/cln/one/regtest/log" + shell: "while [ ! -f $CDK_ITESTS_DIR/cln/one/debug.log ]; do sleep 1; done && tail -f $CDK_ITESTS_DIR/cln/one/debug.log" autostart: true cln-two: - shell: "while [ ! -f $CDK_ITESTS_DIR/cln/two/regtest/log ]; do sleep 1; done && tail -f $CDK_ITESTS_DIR/cln/two/regtest/log" + shell: "while [ ! -f $CDK_ITESTS_DIR/cln/two/debug.log ]; do sleep 1; done && tail -f $CDK_ITESTS_DIR/cln/two/debug.log" autostart: true lnd-one: From a3087023764768eb287a7cce0eded9448b1cf616 Mon Sep 17 00:00:00 2001 From: David Caseria Date: Thu, 10 Jul 2025 14:58:00 -0400 Subject: [PATCH 017/321] Filter active mint quotes for wallet --- crates/cdk/src/wallet/mint.rs | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/crates/cdk/src/wallet/mint.rs b/crates/cdk/src/wallet/mint.rs index 033e8a02b..58ae07ce9 100644 --- a/crates/cdk/src/wallet/mint.rs +++ b/crates/cdk/src/wallet/mint.rs @@ -147,8 +147,11 @@ impl Wallet { pub async fn get_active_mint_quotes(&self) -> Result, Error> { let mut mint_quotes = self.localstore.get_mint_quotes().await?; let unix_time = unix_time(); - mint_quotes - .retain(|quote| quote.state != MintQuoteState::Issued && quote.expiry > unix_time); + mint_quotes.retain(|quote| { + quote.mint_url == self.mint_url + && quote.state != MintQuoteState::Issued + && quote.expiry > unix_time + }); Ok(mint_quotes) } From 526cadf53924d6487f03cd5c702d8a693ef02cf3 Mon Sep 17 00:00:00 2001 From: asmo Date: Fri, 11 Jul 2025 11:32:11 +0200 Subject: [PATCH 018/321] refactor mintd main function (#778) --- crates/cdk-mintd/src/main.rs | 570 +++++++++++++++++++++-------------- 1 file changed, 340 insertions(+), 230 deletions(-) diff --git a/crates/cdk-mintd/src/main.rs b/crates/cdk-mintd/src/main.rs index 0936b69d0..36425f1b8 100644 --- a/crates/cdk-mintd/src/main.rs +++ b/crates/cdk-mintd/src/main.rs @@ -2,19 +2,24 @@ #![warn(missing_docs)] #![warn(rustdoc::bare_urls)] +// std +#[cfg(feature = "auth")] use std::collections::HashMap; use std::env; use std::net::SocketAddr; -use std::path::PathBuf; +use std::path::{Path, PathBuf}; use std::str::FromStr; use std::sync::Arc; +// external crates use anyhow::{anyhow, bail, Result}; use axum::Router; use bip39::Mnemonic; -use cdk::cdk_database::{self, MintAuthDatabase}; +// internal crate modules +use cdk::cdk_database::{self, MintDatabase, MintKeysDatabase}; +use cdk::cdk_payment; +use cdk::cdk_payment::MintPayment; use cdk::mint::{MintBuilder, MintMeltLimits}; -// Feature-gated imports #[cfg(any( feature = "cln", feature = "lnbits", @@ -31,17 +36,16 @@ use cdk::nuts::nut19::{CachedEndpoint, Method as NUT19Method, Path as NUT19Path} feature = "fakewallet" ))] use cdk::nuts::CurrencyUnit; -use cdk::nuts::{ - AuthRequired, ContactInfo, MintVersion, PaymentMethod, ProtectedEndpoint, RoutePath, -}; +#[cfg(feature = "auth")] +use cdk::nuts::{AuthRequired, Method, ProtectedEndpoint, RoutePath}; +use cdk::nuts::{ContactInfo, MintVersion, PaymentMethod}; use cdk::types::QuoteTTL; use cdk_axum::cache::HttpCache; -#[cfg(feature = "management-rpc")] -use cdk_mint_rpc::MintRPCServer; use cdk_mintd::cli::CLIArgs; use cdk_mintd::config::{self, DatabaseEngine, LnBackend}; use cdk_mintd::env_vars::ENV_WORK_DIR; use cdk_mintd::setup::LnBackendSetup; +#[cfg(feature = "auth")] use cdk_sqlite::mint::MintSqliteAuthDatabase; use cdk_sqlite::MintSqliteDatabase; use clap::Parser; @@ -68,10 +72,71 @@ compile_error!( "At least one lightning backend feature must be enabled: cln, lnbits, lnd, fakewallet, or grpc-processor" ); +/// The main entry point for the application. +/// +/// This asynchronous function performs the following steps: +/// 1. Executes the initial setup, including loading configurations and initializing the database. +/// 2. Configures a `MintBuilder` instance with the local store and keystore based on the database. +/// 3. Applies additional custom configurations and authentication setup for the `MintBuilder`. +/// 4. Constructs a `Mint` instance from the configured `MintBuilder`. +/// 5. Checks and resolves the status of any pending mint and melt quotes. #[tokio::main] -async fn main() -> anyhow::Result<()> { - let default_filter = "debug"; +async fn main() -> Result<()> { + let (work_dir, settings, localstore, keystore) = initial_setup().await?; + + let mint_builder = MintBuilder::new() + .with_localstore(localstore) + .with_keystore(keystore); + + let (mint_builder, ln_routers) = configure_mint_builder(&settings, mint_builder).await?; + #[cfg(feature = "auth")] + let mint_builder = setup_authentication(&settings, &work_dir, mint_builder).await?; + let mint_builder_info = mint_builder.mint_info.clone(); + + let mint = mint_builder.build().await?; + + tracing::debug!("Mint built from builder."); + + let mint = Arc::new(mint); + + // Checks the status of all pending melt quotes + // Pending melt quotes where the payment has gone through inputs are burnt + // Pending melt quotes where the payment has **failed** inputs are reset to unspent + mint.check_pending_melt_quotes().await?; + + start_services( + mint.clone(), + &settings, + ln_routers, + &work_dir, + mint_builder_info, + ) + .await?; + + Ok(()) +} +/// Performs the initial setup for the application, including configuring tracing, +/// parsing CLI arguments, setting up the working directory, loading settings, +/// and initializing the database connection. +async fn initial_setup() -> Result<( + PathBuf, + config::Settings, + Arc + Send + Sync>, + Arc + Send + Sync>, +)> { + setup_tracing(); + let args = CLIArgs::parse(); + let work_dir = get_work_directory(&args).await?; + + let settings = load_settings(&work_dir, args.config)?; + let (localstore, keystore) = setup_database(&settings, &work_dir).await?; + Ok((work_dir, settings, localstore, keystore)) +} + +/// Sets up and initializes a tracing subscriber with custom log filtering. +fn setup_tracing() { + let default_filter = "debug"; let sqlx_filter = "sqlx=warn"; let hyper_filter = "hyper=warn"; let h2_filter = "h2=warn"; @@ -82,23 +147,27 @@ async fn main() -> anyhow::Result<()> { )); tracing_subscriber::fmt().with_env_filter(env_filter).init(); +} - let args = CLIArgs::parse(); - - let work_dir = if let Some(work_dir) = args.work_dir { +/// Retrieves the work directory based on command-line arguments, environment variables, or system defaults. +async fn get_work_directory(args: &CLIArgs) -> Result { + let work_dir = if let Some(work_dir) = &args.work_dir { tracing::info!("Using work dir from cmd arg"); - work_dir + work_dir.clone() } else if let Ok(env_work_dir) = env::var(ENV_WORK_DIR) { tracing::info!("Using work dir from env var"); env_work_dir.into() } else { work_dir()? }; - tracing::info!("Using work dir: {}", work_dir.display()); + Ok(work_dir) +} +/// Loads the application settings based on a configuration file and environment variables. +fn load_settings(work_dir: &Path, config_path: Option) -> Result { // get config file name from args - let config_file_arg = match args.config { + let config_file_arg = match config_path { Some(c) => c, None => work_dir.join("config.toml"), }; @@ -112,56 +181,126 @@ async fn main() -> anyhow::Result<()> { // This check for any settings defined in ENV VARs // ENV VARS will take **priority** over those in the config - let settings = settings.from_env()?; + settings.from_env() +} - let mut mint_builder = match settings.database.engine { +async fn setup_database( + settings: &config::Settings, + work_dir: &Path, +) -> Result<( + Arc + Send + Sync>, + Arc + Send + Sync>, +)> { + match settings.database.engine { DatabaseEngine::Sqlite => { - let sql_db_path = work_dir.join("cdk-mintd.sqlite"); - #[cfg(not(feature = "sqlcipher"))] - let sqlite_db = MintSqliteDatabase::new(&sql_db_path).await?; #[cfg(feature = "sqlcipher")] - let sqlite_db = MintSqliteDatabase::new(&sql_db_path, args.password.clone()).await?; - - let db = Arc::new(sqlite_db); - MintBuilder::new() - .with_localstore(db.clone()) - .with_keystore(db) + let password = CLIArgs::parse().password; + #[cfg(not(feature = "sqlcipher"))] + let password = String::new(); + let db = setup_sqlite_database(work_dir, Some(password)).await?; + let localstore: Arc + Send + Sync> = db.clone(); + let keystore: Arc + Send + Sync> = db; + Ok((localstore, keystore)) } + } +} + +async fn setup_sqlite_database( + work_dir: &Path, + _password: Option, +) -> Result> { + let sql_db_path = work_dir.join("cdk-mintd.sqlite"); + #[cfg(not(feature = "sqlcipher"))] + let db = MintSqliteDatabase::new(&sql_db_path).await?; + #[cfg(feature = "sqlcipher")] + let db = { + // Get password from command line arguments for sqlcipher + MintSqliteDatabase::new(&sql_db_path, _password.unwrap()).await? }; + Ok(Arc::new(db)) +} - let mut contact_info: Option> = None; +/** + * Configures a `MintBuilder` instance with provided settings and initializes + * routers for Lightning Network backends. + */ +async fn configure_mint_builder( + settings: &config::Settings, + mint_builder: MintBuilder, +) -> Result<(MintBuilder, Vec)> { + let mut ln_routers = vec![]; - if let Some(nostr_contact) = &settings.mint_info.contact_nostr_public_key { - let nostr_contact = ContactInfo::new("nostr".to_string(), nostr_contact.to_string()); + // Configure basic mint information + let mint_builder = configure_basic_info(settings, mint_builder); - contact_info = match contact_info { - Some(mut vec) => { - vec.push(nostr_contact); - Some(vec) - } - None => Some(vec![nostr_contact]), - }; - } + // Configure lightning backend + let mint_builder = configure_lightning_backend(settings, mint_builder, &mut ln_routers).await?; - if let Some(email_contact) = &settings.mint_info.contact_email { - let email_contact = ContactInfo::new("email".to_string(), email_contact.to_string()); + // Configure signatory or seed + let mint_builder = configure_signing_method(settings, mint_builder).await?; - contact_info = match contact_info { - Some(mut vec) => { - vec.push(email_contact); - Some(vec) - } - None => Some(vec![email_contact]), - }; + // Configure caching + let mint_builder = configure_cache(settings, mint_builder); + + Ok((mint_builder, ln_routers)) +} + +/// Configures basic mint information (name, contact info, descriptions, etc.) +fn configure_basic_info(settings: &config::Settings, mint_builder: MintBuilder) -> MintBuilder { + // Add contact information + let mut contacts = Vec::new(); + if let Some(nostr_key) = &settings.mint_info.contact_nostr_public_key { + contacts.push(ContactInfo::new("nostr".to_string(), nostr_key.to_string())); + } + if let Some(email) = &settings.mint_info.contact_email { + contacts.push(ContactInfo::new("email".to_string(), email.to_string())); } + // Add version information let mint_version = MintVersion::new( "cdk-mintd".to_string(), CARGO_PKG_VERSION.unwrap_or("Unknown").to_string(), ); - let mut ln_routers = vec![]; + // Configure mint builder with basic info + let mut builder = mint_builder + .with_name(settings.mint_info.name.clone()) + .with_version(mint_version) + .with_description(settings.mint_info.description.clone()); + + // Add optional information + if let Some(long_description) = &settings.mint_info.description_long { + builder = builder.with_long_description(long_description.to_string()); + } + for contact in contacts { + builder = builder.add_contact_info(contact); + } + + if let Some(pubkey) = settings.mint_info.pubkey { + builder = builder.with_pubkey(pubkey); + } + + if let Some(icon_url) = &settings.mint_info.icon_url { + builder = builder.with_icon_url(icon_url.to_string()); + } + + if let Some(motd) = &settings.mint_info.motd { + builder = builder.with_motd(motd.to_string()); + } + + if let Some(tos_url) = &settings.mint_info.tos_url { + builder = builder.with_tos_url(tos_url.to_string()); + } + + builder +} +/// Configures Lightning Network backend based on the specified backend type +async fn configure_lightning_backend( + settings: &config::Settings, + mut mint_builder: MintBuilder, + ln_routers: &mut Vec, +) -> Result { let mint_melt_limits = MintMeltLimits { mint_min: settings.ln.min_mint, mint_max: settings.ln.max_mint, @@ -178,74 +317,50 @@ async fn main() -> anyhow::Result<()> { .cln .clone() .expect("Config checked at load that cln is some"); - let cln = cln_settings - .setup(&mut ln_routers, &settings, CurrencyUnit::Msat) - .await?; - let cln = Arc::new(cln); - - mint_builder = mint_builder - .add_ln_backend( - CurrencyUnit::Sat, - PaymentMethod::Bolt11, - mint_melt_limits, - cln.clone(), - ) + .setup(ln_routers, settings, CurrencyUnit::Msat) .await?; - if let Some(input_fee) = settings.info.input_fee_ppk { - mint_builder = mint_builder.set_unit_fee(&CurrencyUnit::Sat, input_fee)?; - } - - let nut17_supported = SupportedMethods::default_bolt11(CurrencyUnit::Sat); - - mint_builder = mint_builder.add_supported_websockets(nut17_supported); + mint_builder = configure_backend_for_unit( + settings, + mint_builder, + CurrencyUnit::Sat, + mint_melt_limits, + Arc::new(cln), + ) + .await?; } #[cfg(feature = "lnbits")] LnBackend::LNbits => { let lnbits_settings = settings.clone().lnbits.expect("Checked on config load"); let lnbits = lnbits_settings - .setup(&mut ln_routers, &settings, CurrencyUnit::Sat) + .setup(ln_routers, settings, CurrencyUnit::Sat) .await?; - mint_builder = mint_builder - .add_ln_backend( - CurrencyUnit::Sat, - PaymentMethod::Bolt11, - mint_melt_limits, - Arc::new(lnbits), - ) - .await?; - if let Some(input_fee) = settings.info.input_fee_ppk { - mint_builder = mint_builder.set_unit_fee(&CurrencyUnit::Sat, input_fee)?; - } - - let nut17_supported = SupportedMethods::default_bolt11(CurrencyUnit::Sat); - - mint_builder = mint_builder.add_supported_websockets(nut17_supported); + mint_builder = configure_backend_for_unit( + settings, + mint_builder, + CurrencyUnit::Sat, + mint_melt_limits, + Arc::new(lnbits), + ) + .await?; } #[cfg(feature = "lnd")] LnBackend::Lnd => { let lnd_settings = settings.clone().lnd.expect("Checked at config load"); let lnd = lnd_settings - .setup(&mut ln_routers, &settings, CurrencyUnit::Msat) - .await?; - - mint_builder = mint_builder - .add_ln_backend( - CurrencyUnit::Sat, - PaymentMethod::Bolt11, - mint_melt_limits, - Arc::new(lnd), - ) + .setup(ln_routers, settings, CurrencyUnit::Msat) .await?; - if let Some(input_fee) = settings.info.input_fee_ppk { - mint_builder = mint_builder.set_unit_fee(&CurrencyUnit::Sat, input_fee)?; - } - let nut17_supported = SupportedMethods::default_bolt11(CurrencyUnit::Sat); - - mint_builder = mint_builder.add_supported_websockets(nut17_supported); + mint_builder = configure_backend_for_unit( + settings, + mint_builder, + CurrencyUnit::Sat, + mint_melt_limits, + Arc::new(lnd), + ) + .await?; } #[cfg(feature = "fakewallet")] LnBackend::FakeWallet => { @@ -254,27 +369,17 @@ async fn main() -> anyhow::Result<()> { for unit in fake_wallet.clone().supported_units { let fake = fake_wallet - .setup(&mut ln_routers, &settings, CurrencyUnit::Sat) - .await - .expect("hhh"); - - let fake = Arc::new(fake); - - mint_builder = mint_builder - .add_ln_backend( - unit.clone(), - PaymentMethod::Bolt11, - mint_melt_limits, - fake.clone(), - ) + .setup(ln_routers, settings, CurrencyUnit::Sat) .await?; - if let Some(input_fee) = settings.info.input_fee_ppk { - mint_builder = mint_builder.set_unit_fee(&unit, input_fee)?; - } - let nut17_supported = SupportedMethods::default_bolt11(unit); - - mint_builder = mint_builder.add_supported_websockets(nut17_supported); + mint_builder = configure_backend_for_unit( + settings, + mint_builder, + unit.clone(), + mint_melt_limits, + Arc::new(fake), + ) + .await?; } } #[cfg(feature = "grpc-processor")] @@ -290,123 +395,132 @@ async fn main() -> anyhow::Result<()> { grpc_processor.port ); - tracing::info!("{:?}", grpc_processor); - for unit in grpc_processor.clone().supported_units { tracing::debug!("Adding unit: {:?}", unit); - let processor = grpc_processor - .setup(&mut ln_routers, &settings, unit.clone()) + .setup(ln_routers, settings, unit.clone()) .await?; - mint_builder = mint_builder - .add_ln_backend( - unit.clone(), - PaymentMethod::Bolt11, - mint_melt_limits, - Arc::new(processor), - ) - .await?; - if let Some(input_fee) = settings.info.input_fee_ppk { - mint_builder = mint_builder.set_unit_fee(&unit, input_fee)?; - } - - let nut17_supported = SupportedMethods::default_bolt11(unit); - mint_builder = mint_builder.add_supported_websockets(nut17_supported); + mint_builder = configure_backend_for_unit( + settings, + mint_builder, + unit.clone(), + mint_melt_limits, + Arc::new(processor), + ) + .await?; } } LnBackend::None => { tracing::error!( - "Pyament backend was not set or feature disabled. {:?}", + "Payment backend was not set or feature disabled. {:?}", settings.ln.ln_backend ); - bail!("Ln backend must be") + bail!("Lightning backend must be configured"); } }; - if let Some(long_description) = &settings.mint_info.description_long { - mint_builder = mint_builder.with_long_description(long_description.to_string()); - } - - if let Some(contact_info) = contact_info { - for info in contact_info { - mint_builder = mint_builder.add_contact_info(info); - } - } - - if let Some(pubkey) = settings.mint_info.pubkey { - mint_builder = mint_builder.with_pubkey(pubkey); - } + Ok(mint_builder) +} - if let Some(icon_url) = &settings.mint_info.icon_url { - mint_builder = mint_builder.with_icon_url(icon_url.to_string()); - } +/// Helper function to configure a mint builder with a lightning backend for a specific currency unit +async fn configure_backend_for_unit( + settings: &config::Settings, + mut mint_builder: MintBuilder, + unit: cdk::nuts::CurrencyUnit, + mint_melt_limits: MintMeltLimits, + backend: Arc + Send + Sync>, +) -> Result { + mint_builder = mint_builder + .add_ln_backend( + unit.clone(), + PaymentMethod::Bolt11, + mint_melt_limits, + backend, + ) + .await?; - if let Some(motd) = settings.mint_info.motd { - mint_builder = mint_builder.with_motd(motd); + if let Some(input_fee) = settings.info.input_fee_ppk { + mint_builder = mint_builder.set_unit_fee(&unit, input_fee)?; } - if let Some(tos_url) = &settings.mint_info.tos_url { - mint_builder = mint_builder.with_tos_url(tos_url.to_string()); - } + let nut17_supported = SupportedMethods::default_bolt11(unit); + mint_builder = mint_builder.add_supported_websockets(nut17_supported); - mint_builder = mint_builder - .with_name(settings.mint_info.name) - .with_version(mint_version.clone()) - .with_description(settings.mint_info.description); + Ok(mint_builder) +} - mint_builder = if let Some(signatory_url) = settings.info.signatory_url { +/// Configures the signing method (remote signatory or local seed) +async fn configure_signing_method( + settings: &config::Settings, + mint_builder: MintBuilder, +) -> Result { + if let Some(signatory_url) = settings.info.signatory_url.clone() { tracing::info!( "Connecting to remote signatory to {} with certs {:?}", signatory_url, - settings.info.signatory_certs + settings.info.signatory_certs.clone() ); - mint_builder.with_signatory(Arc::new( - cdk_signatory::SignatoryRpcClient::new(signatory_url, settings.info.signatory_certs) - .await?, - )) + + Ok(mint_builder.with_signatory(Arc::new( + cdk_signatory::SignatoryRpcClient::new( + signatory_url, + settings.info.signatory_certs.clone(), + ) + .await?, + ))) } else if let Some(mnemonic) = settings .info .mnemonic + .clone() .map(|s| Mnemonic::from_str(&s)) .transpose()? { - mint_builder.with_seed(mnemonic.to_seed_normalized("").to_vec()) + Ok(mint_builder.with_seed(mnemonic.to_seed_normalized("").to_vec())) } else { bail!("No seed nor remote signatory set"); - }; + } +} +/// Configures cache settings +fn configure_cache(settings: &config::Settings, mint_builder: MintBuilder) -> MintBuilder { let cached_endpoints = vec![ CachedEndpoint::new(NUT19Method::Post, NUT19Path::MintBolt11), CachedEndpoint::new(NUT19Method::Post, NUT19Path::MeltBolt11), CachedEndpoint::new(NUT19Method::Post, NUT19Path::Swap), ]; - let cache: HttpCache = settings.info.http_cache.into(); - - mint_builder = mint_builder.add_cache(Some(cache.ttl.as_secs()), cached_endpoints); + let cache: HttpCache = settings.info.http_cache.clone().into(); + mint_builder.add_cache(Some(cache.ttl.as_secs()), cached_endpoints) +} - // Add auth to mint - if let Some(auth_settings) = settings.auth { +#[cfg(feature = "auth")] +async fn setup_authentication( + settings: &config::Settings, + work_dir: &Path, + mut mint_builder: MintBuilder, +) -> Result { + if let Some(auth_settings) = settings.auth.clone() { tracing::info!("Auth settings are defined. {:?}", auth_settings); - let auth_localstore: Arc + Send + Sync> = - match settings.database.engine { - DatabaseEngine::Sqlite => { - let sql_db_path = work_dir.join("cdk-mintd-auth.sqlite"); - #[cfg(not(feature = "sqlcipher"))] - let sqlite_db = MintSqliteAuthDatabase::new(&sql_db_path).await?; - #[cfg(feature = "sqlcipher")] - let sqlite_db = - MintSqliteAuthDatabase::new(&sql_db_path, args.password).await?; - - Arc::new(sqlite_db) - } - }; + let auth_localstore: Arc< + dyn cdk_database::MintAuthDatabase + Send + Sync, + > = match settings.database.engine { + DatabaseEngine::Sqlite => { + let sql_db_path = work_dir.join("cdk-mintd-auth.sqlite"); + #[cfg(feature = "sqlcipher")] + let password = CLIArgs::parse().password; + #[cfg(feature = "sqlcipher")] + let sqlite_db = MintSqliteAuthDatabase::new(&sql_db_path, password).await?; + #[cfg(not(feature = "sqlcipher"))] + let sqlite_db = MintSqliteAuthDatabase::new(&sql_db_path).await?; + Arc::new(sqlite_db) + } + }; mint_builder = mint_builder.with_auth_localstore(auth_localstore.clone()); let mint_blind_auth_endpoint = - ProtectedEndpoint::new(cdk::nuts::Method::Post, RoutePath::MintBlindAuth); + ProtectedEndpoint::new(Method::Post, RoutePath::MintBlindAuth); mint_builder = mint_builder.set_clear_auth_settings( auth_settings.openid_discovery, @@ -421,12 +535,10 @@ async fn main() -> anyhow::Result<()> { let mut unprotected_endpoints = vec![]; { - let mint_quote_protected_endpoint = ProtectedEndpoint::new( - cdk::nuts::Method::Post, - cdk::nuts::RoutePath::MintQuoteBolt11, - ); + let mint_quote_protected_endpoint = + ProtectedEndpoint::new(Method::Post, RoutePath::MintQuoteBolt11); let mint_protected_endpoint = - ProtectedEndpoint::new(cdk::nuts::Method::Post, cdk::nuts::RoutePath::MintBolt11); + ProtectedEndpoint::new(Method::Post, RoutePath::MintBolt11); if auth_settings.enabled_mint { protected_endpoints.insert(mint_quote_protected_endpoint, AuthRequired::Blind); @@ -441,12 +553,10 @@ async fn main() -> anyhow::Result<()> { } { - let melt_quote_protected_endpoint = ProtectedEndpoint::new( - cdk::nuts::Method::Post, - cdk::nuts::RoutePath::MeltQuoteBolt11, - ); + let melt_quote_protected_endpoint = + ProtectedEndpoint::new(Method::Post, RoutePath::MeltQuoteBolt11); let melt_protected_endpoint = - ProtectedEndpoint::new(cdk::nuts::Method::Post, cdk::nuts::RoutePath::MeltBolt11); + ProtectedEndpoint::new(Method::Post, RoutePath::MeltBolt11); if auth_settings.enabled_melt { protected_endpoints.insert(melt_quote_protected_endpoint, AuthRequired::Blind); @@ -461,8 +571,7 @@ async fn main() -> anyhow::Result<()> { } { - let swap_protected_endpoint = - ProtectedEndpoint::new(cdk::nuts::Method::Post, cdk::nuts::RoutePath::Swap); + let swap_protected_endpoint = ProtectedEndpoint::new(Method::Post, RoutePath::Swap); if auth_settings.enabled_swap { protected_endpoints.insert(swap_protected_endpoint, AuthRequired::Blind); @@ -473,10 +582,8 @@ async fn main() -> anyhow::Result<()> { } { - let check_mint_protected_endpoint = ProtectedEndpoint::new( - cdk::nuts::Method::Get, - cdk::nuts::RoutePath::MintQuoteBolt11, - ); + let check_mint_protected_endpoint = + ProtectedEndpoint::new(Method::Get, RoutePath::MintQuoteBolt11); if auth_settings.enabled_check_mint_quote { protected_endpoints.insert(check_mint_protected_endpoint, AuthRequired::Blind); @@ -487,10 +594,8 @@ async fn main() -> anyhow::Result<()> { } { - let check_melt_protected_endpoint = ProtectedEndpoint::new( - cdk::nuts::Method::Get, - cdk::nuts::RoutePath::MeltQuoteBolt11, - ); + let check_melt_protected_endpoint = + ProtectedEndpoint::new(Method::Get, RoutePath::MeltQuoteBolt11); if auth_settings.enabled_check_melt_quote { protected_endpoints.insert(check_melt_protected_endpoint, AuthRequired::Blind); @@ -502,7 +607,7 @@ async fn main() -> anyhow::Result<()> { { let restore_protected_endpoint = - ProtectedEndpoint::new(cdk::nuts::Method::Post, cdk::nuts::RoutePath::Restore); + ProtectedEndpoint::new(Method::Post, RoutePath::Restore); if auth_settings.enabled_restore { protected_endpoints.insert(restore_protected_endpoint, AuthRequired::Blind); @@ -514,7 +619,7 @@ async fn main() -> anyhow::Result<()> { { let state_protected_endpoint = - ProtectedEndpoint::new(cdk::nuts::Method::Post, cdk::nuts::RoutePath::Checkstate); + ProtectedEndpoint::new(Method::Post, RoutePath::Checkstate); if auth_settings.enabled_check_proof_state { protected_endpoints.insert(state_protected_endpoint, AuthRequired::Blind); @@ -532,20 +637,19 @@ async fn main() -> anyhow::Result<()> { tx.add_protected_endpoints(protected_endpoints).await?; tx.commit().await?; } + Ok(mint_builder) +} - let mint = mint_builder.build().await?; - - tracing::debug!("Mint built from builder."); - - let mint = Arc::new(mint); - - // Checks the status of all pending melt quotes - // Pending melt quotes where the payment has gone through inputs are burnt - // Pending melt quotes where the payment has **failed** inputs are reset to unspent - mint.check_pending_melt_quotes().await?; - - let listen_addr = settings.info.listen_host; +async fn start_services( + mint: Arc, + settings: &config::Settings, + ln_routers: Vec, + _work_dir: &Path, + mint_builder_info: cdk::nuts::MintInfo, +) -> Result<()> { + let listen_addr = settings.info.listen_host.clone(); let listen_port = settings.info.listen_port; + let cache: HttpCache = settings.info.http_cache.clone().into(); let v1_service = cdk_axum::create_mint_router_with_custom_cache(Arc::clone(&mint), cache).await?; @@ -590,13 +694,13 @@ async fn main() -> anyhow::Result<()> { #[cfg(feature = "management-rpc")] { - if let Some(rpc_settings) = settings.mint_management_rpc { + if let Some(rpc_settings) = settings.mint_management_rpc.clone() { if rpc_settings.enabled { let addr = rpc_settings.address.unwrap_or("127.0.0.1".to_string()); let port = rpc_settings.port.unwrap_or(8086); - let mut mint_rpc = MintRPCServer::new(&addr, port, mint.clone())?; + let mut mint_rpc = cdk_mint_rpc::MintRPCServer::new(&addr, port, mint.clone())?; - let tls_dir = rpc_settings.tls_dir_path.unwrap_or(work_dir.join("tls")); + let tls_dir = rpc_settings.tls_dir_path.unwrap_or(_work_dir.join("tls")); if !tls_dir.exists() { tracing::error!("TLS directory does not exist: {}", tls_dir.display()); @@ -615,13 +719,17 @@ async fn main() -> anyhow::Result<()> { if rpc_enabled { if mint.mint_info().await.is_err() { tracing::info!("Mint info not set on mint, setting."); - mint.set_mint_info(mint_builder.mint_info).await?; + mint.set_mint_info(mint_builder_info).await?; mint.set_quote_ttl(QuoteTTL::new(10_000, 10_000)).await?; } else { if mint.localstore.get_quote_ttl().await.is_err() { mint.set_quote_ttl(QuoteTTL::new(10_000, 10_000)).await?; } - + // Add version information + let mint_version = MintVersion::new( + "cdk-mintd".to_string(), + CARGO_PKG_VERSION.unwrap_or("Unknown").to_string(), + ); let mut stored_mint_info = mint.mint_info().await?; stored_mint_info.version = Some(mint_version); mint.set_mint_info(stored_mint_info).await?; @@ -630,7 +738,7 @@ async fn main() -> anyhow::Result<()> { } } else { tracing::warn!("RPC not enabled, using mint info from config."); - mint.set_mint_info(mint_builder.mint_info).await?; + mint.set_mint_info(mint_builder_info).await?; mint.set_quote_ttl(QuoteTTL::new(10_000, 10_000)).await?; } @@ -640,6 +748,7 @@ async fn main() -> anyhow::Result<()> { tracing::debug!("listening on {}", listener.local_addr().unwrap()); + // Wait for axum server to complete let axum_result = axum::serve(listener, mint_service).with_graceful_shutdown(shutdown_signal()); match axum_result.await { @@ -653,6 +762,7 @@ async fn main() -> anyhow::Result<()> { } } + // Notify all waiting tasks to shutdown shutdown.notify_waiters(); #[cfg(feature = "management-rpc")] From 180a7c41b754f3b37d90e2cc92a5ba5f76b0b15e Mon Sep 17 00:00:00 2001 From: vnprc Date: Fri, 11 Jul 2025 19:35:49 -0400 Subject: [PATCH 019/321] fix: return the correct error when fetching config values do not always return UnknownQuoteTTL return UnknownMintInfo when appropriate add a new UnknownConfigKey for unknown key values unit tests to cover this functionality --- crates/cdk-sqlite/src/mint/error.rs | 3 + crates/cdk-sqlite/src/mint/mod.rs | 98 ++++++++++++++++++++++++++++- 2 files changed, 100 insertions(+), 1 deletion(-) diff --git a/crates/cdk-sqlite/src/mint/error.rs b/crates/cdk-sqlite/src/mint/error.rs index eea510a5f..ad5210632 100644 --- a/crates/cdk-sqlite/src/mint/error.rs +++ b/crates/cdk-sqlite/src/mint/error.rs @@ -92,6 +92,9 @@ pub enum Error { /// Unknown quote TTL #[error("Unknown quote TTL")] UnknownQuoteTTL, + /// Unknown config key + #[error("Unknown config key: {0}")] + UnknownConfigKey(String), /// Proof not found #[error("Proof not found")] ProofNotFound, diff --git a/crates/cdk-sqlite/src/mint/mod.rs b/crates/cdk-sqlite/src/mint/mod.rs index f4cf3e926..6f6cd03c6 100644 --- a/crates/cdk-sqlite/src/mint/mod.rs +++ b/crates/cdk-sqlite/src/mint/mod.rs @@ -130,7 +130,11 @@ impl MintSqliteDatabase { .bind(":id", id.to_owned()) .pluck(&self.pool) .await? - .ok_or::(Error::UnknownQuoteTTL)?); + .ok_or_else(|| match id { + "mint_info" => Error::UnknownMintInfo, + "quote_ttl" => Error::UnknownQuoteTTL, + unknown => Error::UnknownConfigKey(unknown.to_string()), + })?); Ok(serde_json::from_str(&value)?) } @@ -1651,4 +1655,96 @@ mod tests { let _ = remove_file(&file); } + + #[tokio::test] + async fn test_fetch_from_config_error_handling() { + use cdk_common::common::QuoteTTL; + use cdk_common::MintInfo; + + let db = memory::empty().await.unwrap(); + + // Test 1: Unknown mint_info should return UnknownMintInfo error + let result: Result = db.fetch_from_config("mint_info").await; + assert!(result.is_err()); + assert!(matches!(result.unwrap_err(), Error::UnknownMintInfo)); + + // Test 2: Unknown quote_ttl should return UnknownQuoteTTL error + let result: Result = db.fetch_from_config("quote_ttl").await; + assert!(result.is_err()); + assert!(matches!(result.unwrap_err(), Error::UnknownQuoteTTL)); + + // Test 3: Unknown config key should return UnknownConfigKey error + let result: Result = db.fetch_from_config("unknown_config_key").await; + assert!(result.is_err()); + match result.unwrap_err() { + Error::UnknownConfigKey(key) => { + assert_eq!(key, "unknown_config_key"); + } + other => panic!("Expected UnknownConfigKey error, got: {:?}", other), + } + + // Test 4: Another unknown config key with different name + let result: Result = db.fetch_from_config("some_other_key").await; + assert!(result.is_err()); + match result.unwrap_err() { + Error::UnknownConfigKey(key) => { + assert_eq!(key, "some_other_key"); + } + other => panic!("Expected UnknownConfigKey error, got: {:?}", other), + } + } + + #[tokio::test] + async fn test_config_round_trip() { + use cdk_common::common::QuoteTTL; + use cdk_common::{MintInfo, Nuts}; + + let db = memory::empty().await.unwrap(); + + // Test mint_info round trip + let mint_info = MintInfo { + name: Some("Test Mint".to_string()), + description: Some("A test mint".to_string()), + pubkey: None, + version: None, + description_long: None, + contact: None, + nuts: Nuts::default(), + icon_url: None, + urls: None, + motd: None, + time: None, + tos_url: None, + }; + + // Store mint_info + let mut tx = cdk_common::database::MintDatabase::begin_transaction(&db) + .await + .unwrap(); + tx.set_mint_info(mint_info.clone()).await.unwrap(); + tx.commit().await.unwrap(); + + // Retrieve mint_info + let retrieved_mint_info: MintInfo = db.fetch_from_config("mint_info").await.unwrap(); + assert_eq!(mint_info.name, retrieved_mint_info.name); + assert_eq!(mint_info.description, retrieved_mint_info.description); + + // Test quote_ttl round trip + let quote_ttl = QuoteTTL { + mint_ttl: 3600, + melt_ttl: 1800, + }; + + // Store quote_ttl + let mut tx = cdk_common::database::MintDatabase::begin_transaction(&db) + .await + .unwrap(); + tx.set_quote_ttl(quote_ttl.clone()).await.unwrap(); + tx.commit().await.unwrap(); + + // Retrieve quote_ttl + let retrieved_quote_ttl: QuoteTTL = db.fetch_from_config("quote_ttl").await.unwrap(); + assert_eq!(quote_ttl.mint_ttl, retrieved_quote_ttl.mint_ttl); + assert_eq!(quote_ttl.melt_ttl, retrieved_quote_ttl.melt_ttl); + } } From ae6c10780931dcecc3d9546d9ab16f2bea4782b4 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Sun, 6 Jul 2025 21:20:25 +0100 Subject: [PATCH 020/321] feat: bolt12 --- Cargo.toml | 1 + crates/cashu/Cargo.toml | 1 + crates/cashu/src/amount.rs | 46 ++ crates/cashu/src/nuts/auth/nut21.rs | 28 +- crates/cashu/src/nuts/auth/nut22.rs | 4 +- crates/cashu/src/nuts/mod.rs | 2 + crates/cashu/src/nuts/nut00/mod.rs | 5 +- crates/cashu/src/nuts/nut04.rs | 10 + crates/cashu/src/nuts/nut05.rs | 19 +- crates/cashu/src/nuts/nut17/mod.rs | 34 + crates/cashu/src/nuts/nut19.rs | 6 + crates/cashu/src/nuts/nut23.rs | 6 - crates/cashu/src/nuts/nut24.rs | 104 +++ crates/cdk-axum/src/bolt12_router.rs | 213 +++++ crates/cdk-axum/src/lib.rs | 40 +- crates/cdk-axum/src/router_handlers.rs | 16 +- crates/cdk-cli/Cargo.toml | 4 + crates/cdk-cli/src/bip353.rs | 132 +++ crates/cdk-cli/src/main.rs | 2 + crates/cdk-cli/src/sub_commands/melt.rs | 418 ++++++---- crates/cdk-cli/src/sub_commands/mint.rs | 125 ++- crates/cdk-cln/src/error.rs | 6 + crates/cdk-cln/src/lib.rs | 755 ++++++++++++----- crates/cdk-common/Cargo.toml | 1 + crates/cdk-common/src/database/mint/mod.rs | 39 +- crates/cdk-common/src/database/mod.rs | 3 + crates/cdk-common/src/error.rs | 18 + crates/cdk-common/src/lib.rs | 2 + crates/cdk-common/src/melt.rs | 26 + crates/cdk-common/src/mint.rs | 311 ++++++- crates/cdk-common/src/payment.rs | 243 +++++- crates/cdk-common/src/subscription.rs | 3 + crates/cdk-common/src/wallet.rs | 69 +- crates/cdk-common/src/ws.rs | 3 + crates/cdk-fake-wallet/Cargo.toml | 3 +- crates/cdk-fake-wallet/src/error.rs | 2 +- crates/cdk-fake-wallet/src/lib.rs | 372 ++++++--- .../src/init_pure_tests.rs | 60 +- crates/cdk-integration-tests/src/lib.rs | 45 +- crates/cdk-integration-tests/tests/bolt12.rs | 332 ++++++++ .../cdk-integration-tests/tests/fake_auth.rs | 6 +- .../tests/happy_path_mint_wallet.rs | 12 +- .../tests/integration_tests_pure.rs | 6 +- crates/cdk-integration-tests/tests/regtest.rs | 4 +- .../cdk-integration-tests/tests/test_fees.rs | 4 + crates/cdk-lnbits/src/error.rs | 3 + crates/cdk-lnbits/src/lib.rs | 341 ++++---- crates/cdk-lnd/src/lib.rs | 528 ++++++------ crates/cdk-mint-rpc/Cargo.toml | 1 + crates/cdk-mint-rpc/src/proto/server.rs | 49 +- crates/cdk-mintd/src/main.rs | 89 +- crates/cdk-payment-processor/Cargo.toml | 5 +- crates/cdk-payment-processor/src/error.rs | 67 +- crates/cdk-payment-processor/src/lib.rs | 1 + .../cdk-payment-processor/src/proto/client.rs | 162 ++-- crates/cdk-payment-processor/src/proto/mod.rs | 282 ++++--- .../src/proto/payment_processor.proto | 133 ++- .../cdk-payment-processor/src/proto/server.rs | 216 +++-- crates/cdk-sqlite/src/mint/error.rs | 3 + crates/cdk-sqlite/src/mint/memory.rs | 2 +- crates/cdk-sqlite/src/mint/migrations.rs | 1 + .../mint/migrations/20250706101057_bolt12.sql | 81 ++ crates/cdk-sqlite/src/mint/mod.rs | 760 ++++++++++++------ crates/cdk-sqlite/src/wallet/migrations.rs | 1 + .../migrations/20250707093445_bolt12.sql | 58 ++ crates/cdk-sqlite/src/wallet/mod.rs | 40 +- crates/cdk/Cargo.toml | 1 + crates/cdk/src/mint/builder.rs | 48 +- crates/cdk/src/mint/issue/issue_nut04.rs | 301 ------- crates/cdk/src/mint/issue/mod.rs | 600 +++++++++++++- crates/cdk/src/mint/ln.rs | 49 +- crates/cdk/src/mint/melt.rs | 270 +++++-- crates/cdk/src/mint/mod.rs | 59 +- crates/cdk/src/mint/start_up_check.rs | 8 +- .../src/mint/subscription/on_subscription.rs | 6 + .../wallet/{mint.rs => issue/issue_bolt11.rs} | 35 +- crates/cdk/src/wallet/issue/issue_bolt12.rs | 258 ++++++ crates/cdk/src/wallet/issue/mod.rs | 2 + .../wallet/{melt.rs => melt/melt_bolt11.rs} | 2 +- crates/cdk/src/wallet/melt/melt_bolt12.rs | 89 ++ crates/cdk/src/wallet/melt/mod.rs | 2 + .../src/wallet/mint_connector/http_client.rs | 102 ++- crates/cdk/src/wallet/mint_connector/mod.rs | 26 + crates/cdk/src/wallet/mod.rs | 2 +- misc/itests.sh | 7 + misc/mintd_payment_processor.sh | 14 + 86 files changed, 6304 insertions(+), 1941 deletions(-) create mode 100644 crates/cashu/src/nuts/nut24.rs create mode 100644 crates/cdk-axum/src/bolt12_router.rs create mode 100644 crates/cdk-cli/src/bip353.rs create mode 100644 crates/cdk-common/src/melt.rs create mode 100644 crates/cdk-integration-tests/tests/bolt12.rs create mode 100644 crates/cdk-sqlite/src/mint/migrations/20250706101057_bolt12.sql create mode 100644 crates/cdk-sqlite/src/wallet/migrations/20250707093445_bolt12.sql delete mode 100644 crates/cdk/src/mint/issue/issue_nut04.rs rename crates/cdk/src/wallet/{mint.rs => issue/issue_bolt11.rs} (92%) create mode 100644 crates/cdk/src/wallet/issue/issue_bolt12.rs create mode 100644 crates/cdk/src/wallet/issue/mod.rs rename crates/cdk/src/wallet/{melt.rs => melt/melt_bolt11.rs} (99%) create mode 100644 crates/cdk/src/wallet/melt/melt_bolt12.rs create mode 100644 crates/cdk/src/wallet/melt/mod.rs diff --git a/Cargo.toml b/Cargo.toml index 3aaab2b85..02418387d 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -61,6 +61,7 @@ ciborium = { version = "0.2.2", default-features = false, features = ["std"] } cbor-diag = "0.1.12" futures = { version = "0.3.28", default-features = false, features = ["async-await"] } lightning-invoice = { version = "0.33.0", features = ["serde", "std"] } +lightning = { version = "0.1.2", default-features = false, features = ["std"]} serde = { version = "1", features = ["derive"] } serde_json = "1" thiserror = { version = "2" } diff --git a/crates/cashu/Cargo.toml b/crates/cashu/Cargo.toml index afc4e9f12..efbc975ea 100644 --- a/crates/cashu/Cargo.toml +++ b/crates/cashu/Cargo.toml @@ -26,6 +26,7 @@ ciborium.workspace = true once_cell.workspace = true serde.workspace = true lightning-invoice.workspace = true +lightning.workspace = true thiserror.workspace = true tracing.workspace = true url.workspace = true diff --git a/crates/cashu/src/amount.rs b/crates/cashu/src/amount.rs index 9cf893a02..33bf82bf6 100644 --- a/crates/cashu/src/amount.rs +++ b/crates/cashu/src/amount.rs @@ -6,6 +6,7 @@ use std::cmp::Ordering; use std::fmt; use std::str::FromStr; +use lightning::offers::offer::Offer; use serde::{Deserialize, Serialize}; use thiserror::Error; @@ -26,6 +27,12 @@ pub enum Error { /// Invalid amount #[error("Invalid Amount: {0}")] InvalidAmount(String), + /// Amount undefined + #[error("Amount undefined")] + AmountUndefined, + /// Utf8 parse error + #[error(transparent)] + Utf8ParseError(#[from] std::string::FromUtf8Error), } /// Amount can be any unit @@ -181,6 +188,24 @@ impl Amount { ) -> Result { to_unit(self.0, current_unit, target_unit) } + + /// Convert to i64 + pub fn to_i64(self) -> Option { + if self.0 <= i64::MAX as u64 { + Some(self.0 as i64) + } else { + None + } + } + + /// Create from i64, returning None if negative + pub fn from_i64(value: i64) -> Option { + if value >= 0 { + Some(Amount(value as u64)) + } else { + None + } + } } impl Default for Amount { @@ -273,6 +298,27 @@ impl std::ops::Div for Amount { } } +/// Convert offer to amount in unit +pub fn amount_for_offer(offer: &Offer, unit: &CurrencyUnit) -> Result { + let offer_amount = offer.amount().ok_or(Error::AmountUndefined)?; + + let (amount, currency) = match offer_amount { + lightning::offers::offer::Amount::Bitcoin { amount_msats } => { + (amount_msats, CurrencyUnit::Msat) + } + lightning::offers::offer::Amount::Currency { + iso4217_code, + amount, + } => ( + amount, + CurrencyUnit::from_str(&String::from_utf8(iso4217_code.to_vec())?) + .map_err(|_| Error::CannotConvertUnits)?, + ), + }; + + to_unit(amount, ¤cy, unit).map_err(|_err| Error::CannotConvertUnits) +} + /// Kinds of targeting that are supported #[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Default, Serialize, Deserialize)] pub enum SplitTarget { diff --git a/crates/cashu/src/nuts/auth/nut21.rs b/crates/cashu/src/nuts/auth/nut21.rs index f99a02fcd..6392bd4ae 100644 --- a/crates/cashu/src/nuts/auth/nut21.rs +++ b/crates/cashu/src/nuts/auth/nut21.rs @@ -149,6 +149,18 @@ pub enum RoutePath { /// Mint Blind Auth #[serde(rename = "/v1/auth/blind/mint")] MintBlindAuth, + /// Bolt12 Mint Quote + #[serde(rename = "/v1/mint/quote/bolt12")] + MintQuoteBolt12, + /// Bolt12 Mint + #[serde(rename = "/v1/mint/bolt12")] + MintBolt12, + /// Bolt12 Melt Quote + #[serde(rename = "/v1/melt/quote/bolt12")] + MeltQuoteBolt12, + /// Bolt12 Quote + #[serde(rename = "/v1/melt/bolt12")] + MeltBolt12, } /// Returns [`RoutePath`]s that match regex @@ -195,6 +207,8 @@ mod tests { assert!(paths.contains(&RoutePath::Checkstate)); assert!(paths.contains(&RoutePath::Restore)); assert!(paths.contains(&RoutePath::MintBlindAuth)); + assert!(paths.contains(&RoutePath::MintQuoteBolt12)); + assert!(paths.contains(&RoutePath::MintBolt12)); } #[test] @@ -203,13 +217,17 @@ mod tests { let paths = matching_route_paths("^/v1/mint/.*").unwrap(); // Should match only mint paths - assert_eq!(paths.len(), 2); + assert_eq!(paths.len(), 4); assert!(paths.contains(&RoutePath::MintQuoteBolt11)); assert!(paths.contains(&RoutePath::MintBolt11)); + assert!(paths.contains(&RoutePath::MintQuoteBolt12)); + assert!(paths.contains(&RoutePath::MintBolt12)); // Should not match other paths assert!(!paths.contains(&RoutePath::MeltQuoteBolt11)); assert!(!paths.contains(&RoutePath::MeltBolt11)); + assert!(!paths.contains(&RoutePath::MeltQuoteBolt12)); + assert!(!paths.contains(&RoutePath::MeltBolt12)); assert!(!paths.contains(&RoutePath::Swap)); } @@ -219,9 +237,11 @@ mod tests { let paths = matching_route_paths(".*/quote/.*").unwrap(); // Should match only quote paths - assert_eq!(paths.len(), 2); + assert_eq!(paths.len(), 4); assert!(paths.contains(&RoutePath::MintQuoteBolt11)); assert!(paths.contains(&RoutePath::MeltQuoteBolt11)); + assert!(paths.contains(&RoutePath::MintQuoteBolt12)); + assert!(paths.contains(&RoutePath::MeltQuoteBolt12)); // Should not match non-quote paths assert!(!paths.contains(&RoutePath::MintBolt11)); @@ -336,12 +356,14 @@ mod tests { "https://example.com/.well-known/openid-configuration" ); assert_eq!(settings.client_id, "client123"); - assert_eq!(settings.protected_endpoints.len(), 3); // 2 mint paths + 1 swap path + assert_eq!(settings.protected_endpoints.len(), 5); // 3 mint paths + 1 swap path let expected_protected: HashSet = HashSet::from_iter(vec![ ProtectedEndpoint::new(Method::Post, RoutePath::Swap), ProtectedEndpoint::new(Method::Get, RoutePath::MintBolt11), ProtectedEndpoint::new(Method::Get, RoutePath::MintQuoteBolt11), + ProtectedEndpoint::new(Method::Get, RoutePath::MintQuoteBolt12), + ProtectedEndpoint::new(Method::Get, RoutePath::MintBolt12), ]); let deserlized_protected = settings.protected_endpoints.into_iter().collect(); diff --git a/crates/cashu/src/nuts/auth/nut22.rs b/crates/cashu/src/nuts/auth/nut22.rs index b92cb8737..81990ea31 100644 --- a/crates/cashu/src/nuts/auth/nut22.rs +++ b/crates/cashu/src/nuts/auth/nut22.rs @@ -330,12 +330,14 @@ mod tests { let settings: Settings = serde_json::from_str(json).unwrap(); assert_eq!(settings.bat_max_mint, 5); - assert_eq!(settings.protected_endpoints.len(), 3); // 2 mint paths + 1 swap path + assert_eq!(settings.protected_endpoints.len(), 5); // 4 mint paths + 1 swap path let expected_protected: HashSet = HashSet::from_iter(vec![ ProtectedEndpoint::new(Method::Post, RoutePath::Swap), ProtectedEndpoint::new(Method::Get, RoutePath::MintBolt11), ProtectedEndpoint::new(Method::Get, RoutePath::MintQuoteBolt11), + ProtectedEndpoint::new(Method::Get, RoutePath::MintQuoteBolt12), + ProtectedEndpoint::new(Method::Get, RoutePath::MintBolt12), ]); let deserialized_protected = settings.protected_endpoints.into_iter().collect(); diff --git a/crates/cashu/src/nuts/mod.rs b/crates/cashu/src/nuts/mod.rs index d9e31218a..8e8331f93 100644 --- a/crates/cashu/src/nuts/mod.rs +++ b/crates/cashu/src/nuts/mod.rs @@ -24,6 +24,7 @@ pub mod nut18; pub mod nut19; pub mod nut20; pub mod nut23; +pub mod nut24; #[cfg(feature = "auth")] mod auth; @@ -67,3 +68,4 @@ pub use nut23::{ MeltOptions, MeltQuoteBolt11Request, MeltQuoteBolt11Response, MintQuoteBolt11Request, MintQuoteBolt11Response, QuoteState as MintQuoteState, }; +pub use nut24::{MeltQuoteBolt12Request, MintQuoteBolt12Request, MintQuoteBolt12Response}; diff --git a/crates/cashu/src/nuts/nut00/mod.rs b/crates/cashu/src/nuts/nut00/mod.rs index 85f33a97b..3996800f5 100644 --- a/crates/cashu/src/nuts/nut00/mod.rs +++ b/crates/cashu/src/nuts/nut00/mod.rs @@ -641,13 +641,14 @@ impl<'de> Deserialize<'de> for CurrencyUnit { } /// Payment Method -#[non_exhaustive] #[derive(Debug, Clone, Default, PartialEq, Eq, Hash)] #[cfg_attr(feature = "swagger", derive(utoipa::ToSchema))] pub enum PaymentMethod { /// Bolt11 payment type #[default] Bolt11, + /// Bolt12 + Bolt12, /// Custom Custom(String), } @@ -657,6 +658,7 @@ impl FromStr for PaymentMethod { fn from_str(value: &str) -> Result { match value.to_lowercase().as_str() { "bolt11" => Ok(Self::Bolt11), + "bolt12" => Ok(Self::Bolt12), c => Ok(Self::Custom(c.to_string())), } } @@ -666,6 +668,7 @@ impl fmt::Display for PaymentMethod { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { match self { PaymentMethod::Bolt11 => write!(f, "bolt11"), + PaymentMethod::Bolt12 => write!(f, "bolt12"), PaymentMethod::Custom(p) => write!(f, "{p}"), } } diff --git a/crates/cashu/src/nuts/nut04.rs b/crates/cashu/src/nuts/nut04.rs index 68fbcc979..475c590cc 100644 --- a/crates/cashu/src/nuts/nut04.rs +++ b/crates/cashu/src/nuts/nut04.rs @@ -291,6 +291,16 @@ impl Settings { .position(|settings| &settings.method == method && &settings.unit == unit) .map(|index| self.methods.remove(index)) } + + /// Supported nut04 methods + pub fn supported_methods(&self) -> Vec<&PaymentMethod> { + self.methods.iter().map(|a| &a.method).collect() + } + + /// Supported nut04 units + pub fn supported_units(&self) -> Vec<&CurrencyUnit> { + self.methods.iter().map(|s| &s.unit).collect() + } } #[cfg(test)] diff --git a/crates/cashu/src/nuts/nut05.rs b/crates/cashu/src/nuts/nut05.rs index cd9652749..ac7992336 100644 --- a/crates/cashu/src/nuts/nut05.rs +++ b/crates/cashu/src/nuts/nut05.rs @@ -105,6 +105,11 @@ impl TryFrom> for MeltRequest { // Basic implementation without trait bounds impl MeltRequest { + /// Quote Id + pub fn quote_id(&self) -> &Q { + &self.quote + } + /// Get inputs (proofs) pub fn inputs(&self) -> &Proofs { &self.inputs @@ -132,7 +137,7 @@ impl MeltRequest { } /// Total [`Amount`] of [`Proofs`] - pub fn proofs_amount(&self) -> Result { + pub fn inputs_amount(&self) -> Result { Amount::try_sum(self.inputs.iter().map(|proof| proof.amount)) .map_err(|_| Error::AmountOverflow) } @@ -355,6 +360,18 @@ pub struct Settings { pub disabled: bool, } +impl Settings { + /// Supported nut05 methods + pub fn supported_methods(&self) -> Vec<&PaymentMethod> { + self.methods.iter().map(|a| &a.method).collect() + } + + /// Supported nut05 units + pub fn supported_units(&self) -> Vec<&CurrencyUnit> { + self.methods.iter().map(|s| &s.unit).collect() + } +} + #[cfg(test)] mod tests { use serde_json::{from_str, json, to_string}; diff --git a/crates/cashu/src/nuts/nut17/mod.rs b/crates/cashu/src/nuts/nut17/mod.rs index 10bde715c..da3be3c8f 100644 --- a/crates/cashu/src/nuts/nut17/mod.rs +++ b/crates/cashu/src/nuts/nut17/mod.rs @@ -9,6 +9,7 @@ use super::PublicKey; use crate::nuts::{ CurrencyUnit, MeltQuoteBolt11Response, MintQuoteBolt11Response, PaymentMethod, ProofState, }; +use crate::MintQuoteBolt12Response; pub mod ws; @@ -69,6 +70,21 @@ impl SupportedMethods { commands, } } + + /// Create [`SupportedMethods`] for Bolt12 with all supported commands + pub fn default_bolt12(unit: CurrencyUnit) -> Self { + let commands = vec![ + WsCommand::Bolt12MintQuote, + WsCommand::Bolt12MeltQuote, + WsCommand::ProofState, + ]; + + Self { + method: PaymentMethod::Bolt12, + unit, + commands, + } + } } /// WebSocket commands supported by the Cashu mint @@ -82,11 +98,23 @@ pub enum WsCommand { /// Command to request a Lightning payment for melting tokens #[serde(rename = "bolt11_melt_quote")] Bolt11MeltQuote, + /// Websocket support for Bolt12 Mint Quote + #[serde(rename = "bolt12_mint_quote")] + Bolt12MintQuote, + /// Websocket support for Bolt12 Melt Quote + #[serde(rename = "bolt12_melt_quote")] + Bolt12MeltQuote, /// Command to check the state of a proof #[serde(rename = "proof_state")] ProofState, } +impl From> for NotificationPayload { + fn from(mint_quote: MintQuoteBolt12Response) -> NotificationPayload { + NotificationPayload::MintQuoteBolt12Response(mint_quote) + } +} + #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] #[serde(bound = "T: Serialize + DeserializeOwned")] #[serde(untagged)] @@ -98,6 +126,8 @@ pub enum NotificationPayload { MeltQuoteBolt11Response(MeltQuoteBolt11Response), /// Mint Quote Bolt11 Response MintQuoteBolt11Response(MintQuoteBolt11Response), + /// Mint Quote Bolt12 Response + MintQuoteBolt12Response(MintQuoteBolt12Response), } impl From for NotificationPayload { @@ -128,6 +158,10 @@ pub enum Notification { MeltQuoteBolt11(Uuid), /// MintQuote id is an Uuid MintQuoteBolt11(Uuid), + /// MintQuote id is an Uuid + MintQuoteBolt12(Uuid), + /// MintQuote id is an Uuid + MeltQuoteBolt12(Uuid), } /// Kind diff --git a/crates/cashu/src/nuts/nut19.rs b/crates/cashu/src/nuts/nut19.rs index 6434fdf96..bef6ded1d 100644 --- a/crates/cashu/src/nuts/nut19.rs +++ b/crates/cashu/src/nuts/nut19.rs @@ -55,4 +55,10 @@ pub enum Path { /// Swap #[serde(rename = "/v1/swap")] Swap, + /// Bolt12 Mint + #[serde(rename = "/v1/mint/bolt12")] + MintBolt12, + /// Bolt12 Melt + #[serde(rename = "/v1/melt/bolt12")] + MeltBolt12, } diff --git a/crates/cashu/src/nuts/nut23.rs b/crates/cashu/src/nuts/nut23.rs index e80f480d5..9d67fcda8 100644 --- a/crates/cashu/src/nuts/nut23.rs +++ b/crates/cashu/src/nuts/nut23.rs @@ -54,10 +54,6 @@ pub enum QuoteState { Unpaid, /// Quote has been paid and wallet can mint Paid, - /// Minting is in progress - /// **Note:** This state is to be used internally but is not part of the - /// nut. - Pending, /// ecash issued for quote Issued, } @@ -67,7 +63,6 @@ impl fmt::Display for QuoteState { match self { Self::Unpaid => write!(f, "UNPAID"), Self::Paid => write!(f, "PAID"), - Self::Pending => write!(f, "PENDING"), Self::Issued => write!(f, "ISSUED"), } } @@ -78,7 +73,6 @@ impl FromStr for QuoteState { fn from_str(state: &str) -> Result { match state { - "PENDING" => Ok(Self::Pending), "PAID" => Ok(Self::Paid), "UNPAID" => Ok(Self::Unpaid), "ISSUED" => Ok(Self::Issued), diff --git a/crates/cashu/src/nuts/nut24.rs b/crates/cashu/src/nuts/nut24.rs new file mode 100644 index 000000000..574dec9fd --- /dev/null +++ b/crates/cashu/src/nuts/nut24.rs @@ -0,0 +1,104 @@ +//! Bolt12 +use serde::{Deserialize, Serialize}; +use thiserror::Error; +#[cfg(feature = "mint")] +use uuid::Uuid; + +use super::{CurrencyUnit, MeltOptions, PublicKey}; +use crate::Amount; + +/// NUT18 Error +#[derive(Debug, Error)] +pub enum Error { + /// Unknown Quote State + #[error("Unknown quote state")] + UnknownState, + /// Amount overflow + #[error("Amount Overflow")] + AmountOverflow, + /// Publickey not defined + #[error("Publickey not defined")] + PublickeyUndefined, +} + +/// Mint quote request [NUT-24] +#[derive(Debug, Clone, Hash, PartialEq, Eq, Serialize, Deserialize)] +#[cfg_attr(feature = "swagger", derive(utoipa::ToSchema))] +pub struct MintQuoteBolt12Request { + /// Amount + pub amount: Option, + /// Unit wallet would like to pay with + pub unit: CurrencyUnit, + /// Memo to create the invoice with + pub description: Option, + /// Pubkey + pub pubkey: PublicKey, +} + +/// Mint quote response [NUT-24] +#[derive(Debug, Clone, Hash, PartialEq, Eq, Serialize, Deserialize)] +#[cfg_attr(feature = "swagger", derive(utoipa::ToSchema))] +#[serde(bound = "Q: Serialize + for<'a> Deserialize<'a>")] +pub struct MintQuoteBolt12Response { + /// Quote Id + pub quote: Q, + /// Payment request to fulfil + pub request: String, + /// Amount + pub amount: Option, + /// Unit wallet would like to pay with + pub unit: CurrencyUnit, + /// Unix timestamp until the quote is valid + pub expiry: Option, + /// Pubkey + pub pubkey: PublicKey, + /// Amount that has been paid + pub amount_paid: Amount, + /// Amount that has been issued + pub amount_issued: Amount, +} + +#[cfg(feature = "mint")] +impl MintQuoteBolt12Response { + /// Convert the MintQuote with a quote type Q to a String + pub fn to_string_id(&self) -> MintQuoteBolt12Response { + MintQuoteBolt12Response { + quote: self.quote.to_string(), + request: self.request.clone(), + amount: self.amount, + unit: self.unit.clone(), + expiry: self.expiry, + pubkey: self.pubkey, + amount_paid: self.amount_paid, + amount_issued: self.amount_issued, + } + } +} + +#[cfg(feature = "mint")] +impl From> for MintQuoteBolt12Response { + fn from(value: MintQuoteBolt12Response) -> Self { + Self { + quote: value.quote.to_string(), + request: value.request, + expiry: value.expiry, + amount_paid: value.amount_paid, + amount_issued: value.amount_issued, + pubkey: value.pubkey, + amount: value.amount, + unit: value.unit, + } + } +} + +/// Melt quote request [NUT-18] +#[derive(Debug, Clone, Hash, PartialEq, Eq, Serialize, Deserialize)] +#[cfg_attr(feature = "swagger", derive(utoipa::ToSchema))] +pub struct MeltQuoteBolt12Request { + /// Bolt12 invoice to be paid + pub request: String, + /// Unit wallet would like to pay with + pub unit: CurrencyUnit, + /// Payment Options + pub options: Option, +} diff --git a/crates/cdk-axum/src/bolt12_router.rs b/crates/cdk-axum/src/bolt12_router.rs new file mode 100644 index 000000000..4ee363d83 --- /dev/null +++ b/crates/cdk-axum/src/bolt12_router.rs @@ -0,0 +1,213 @@ +use anyhow::Result; +use axum::extract::{Json, Path, State}; +use axum::response::Response; +#[cfg(feature = "swagger")] +use cdk::error::ErrorResponse; +#[cfg(feature = "auth")] +use cdk::nuts::nut21::{Method, ProtectedEndpoint, RoutePath}; +use cdk::nuts::{ + MeltQuoteBolt11Response, MeltQuoteBolt12Request, MeltRequest, MintQuoteBolt12Request, + MintQuoteBolt12Response, MintRequest, MintResponse, +}; +use paste::paste; +use tracing::instrument; +use uuid::Uuid; + +#[cfg(feature = "auth")] +use crate::auth::AuthHeader; +use crate::{into_response, post_cache_wrapper, MintState}; + +post_cache_wrapper!(post_mint_bolt12, MintRequest, MintResponse); +post_cache_wrapper!( + post_melt_bolt12, + MeltRequest, + MeltQuoteBolt11Response +); + +#[cfg_attr(feature = "swagger", utoipa::path( + get, + context_path = "/v1", + path = "/mint/quote/bolt12", + responses( + (status = 200, description = "Successful response", body = MintQuoteBolt12Response, content_type = "application/json") + ) +))] +/// Get mint bolt12 quote +#[instrument(skip_all, fields(amount = ?payload.amount))] +pub async fn post_mint_bolt12_quote( + #[cfg(feature = "auth")] auth: AuthHeader, + State(state): State, + Json(payload): Json, +) -> Result>, Response> { + #[cfg(feature = "auth")] + { + state + .mint + .verify_auth( + auth.into(), + &ProtectedEndpoint::new(Method::Post, RoutePath::MintQuoteBolt12), + ) + .await + .map_err(into_response)?; + } + + let quote = state + .mint + .get_mint_quote(payload.into()) + .await + .map_err(into_response)?; + + Ok(Json(quote.try_into().map_err(into_response)?)) +} + +#[cfg_attr(feature = "swagger", utoipa::path( + get, + context_path = "/v1", + path = "/mint/quote/bolt12/{quote_id}", + params( + ("quote_id" = String, description = "The quote ID"), + ), + responses( + (status = 200, description = "Successful response", body = MintQuoteBolt12Response, content_type = "application/json"), + (status = 500, description = "Server error", body = ErrorResponse, content_type = "application/json") + ) +))] +/// Get mint bolt12 quote +#[instrument(skip_all, fields(quote_id = ?quote_id))] +pub async fn get_check_mint_bolt12_quote( + #[cfg(feature = "auth")] auth: AuthHeader, + State(state): State, + Path(quote_id): Path, +) -> Result>, Response> { + #[cfg(feature = "auth")] + { + state + .mint + .verify_auth( + auth.into(), + &ProtectedEndpoint::new(Method::Get, RoutePath::MintQuoteBolt12), + ) + .await + .map_err(into_response)?; + } + + let quote = state + .mint + .check_mint_quote("e_id) + .await + .map_err(into_response)?; + + Ok(Json(quote.try_into().map_err(into_response)?)) +} + +#[cfg_attr(feature = "swagger", utoipa::path( + post, + context_path = "/v1", + path = "/mint/bolt12", + request_body(content = MintRequest, description = "Request params", content_type = "application/json"), + responses( + (status = 200, description = "Successful response", body = MintResponse, content_type = "application/json"), + (status = 500, description = "Server error", body = ErrorResponse, content_type = "application/json") + ) +))] +/// Request a quote for melting tokens +#[instrument(skip_all, fields(quote_id = ?payload.quote))] +pub async fn post_mint_bolt12( + #[cfg(feature = "auth")] auth: AuthHeader, + State(state): State, + Json(payload): Json>, +) -> Result, Response> { + #[cfg(feature = "auth")] + { + state + .mint + .verify_auth( + auth.into(), + &ProtectedEndpoint::new(Method::Post, RoutePath::MintBolt12), + ) + .await + .map_err(into_response)?; + } + + let res = state + .mint + .process_mint_request(payload) + .await + .map_err(|err| { + tracing::error!("Could not process mint: {}", err); + into_response(err) + })?; + + Ok(Json(res)) +} + +#[cfg_attr(feature = "swagger", utoipa::path( + post, + context_path = "/v1", + path = "/melt/quote/bolt12", + request_body(content = MeltQuoteBolt12Request, description = "Quote params", content_type = "application/json"), + responses( + (status = 200, description = "Successful response", body = MeltQuoteBolt11Response, content_type = "application/json"), + (status = 500, description = "Server error", body = ErrorResponse, content_type = "application/json") + ) +))] +pub async fn post_melt_bolt12_quote( + #[cfg(feature = "auth")] auth: AuthHeader, + State(state): State, + Json(payload): Json, +) -> Result>, Response> { + #[cfg(feature = "auth")] + { + state + .mint + .verify_auth( + auth.into(), + &ProtectedEndpoint::new(Method::Post, RoutePath::MeltQuoteBolt12), + ) + .await + .map_err(into_response)?; + } + + let quote = state + .mint + .get_melt_quote(payload.into()) + .await + .map_err(into_response)?; + + Ok(Json(quote)) +} + +#[cfg_attr(feature = "swagger", utoipa::path( + post, + context_path = "/v1", + path = "/melt/bolt12", + request_body(content = MeltRequest, description = "Melt params", content_type = "application/json"), + responses( + (status = 200, description = "Successful response", body = MeltQuoteBolt11Response, content_type = "application/json"), + (status = 500, description = "Server error", body = ErrorResponse, content_type = "application/json") + ) +))] +/// Melt tokens for a Bitcoin payment that the mint will make for the user in exchange +/// +/// Requests tokens to be destroyed and sent out via Lightning. +pub async fn post_melt_bolt12( + #[cfg(feature = "auth")] auth: AuthHeader, + State(state): State, + Json(payload): Json>, +) -> Result>, Response> { + #[cfg(feature = "auth")] + { + state + .mint + .verify_auth( + auth.into(), + &ProtectedEndpoint::new(Method::Post, RoutePath::MeltBolt12), + ) + .await + .map_err(into_response)?; + } + + let res = state.mint.melt(&payload).await.map_err(into_response)?; + + Ok(Json(res)) +} diff --git a/crates/cdk-axum/src/lib.rs b/crates/cdk-axum/src/lib.rs index 230ba7ae1..9863c98d2 100644 --- a/crates/cdk-axum/src/lib.rs +++ b/crates/cdk-axum/src/lib.rs @@ -19,6 +19,7 @@ use router_handlers::*; #[cfg(feature = "auth")] mod auth; +mod bolt12_router; pub mod cache; mod router_handlers; mod ws; @@ -52,6 +53,11 @@ mod swagger_imports { #[cfg(feature = "swagger")] use swagger_imports::*; +use crate::bolt12_router::{ + cache_post_melt_bolt12, cache_post_mint_bolt12, get_check_mint_bolt12_quote, + post_melt_bolt12_quote, post_mint_bolt12_quote, +}; + /// CDK Mint State #[derive(Clone)] pub struct MintState { @@ -134,8 +140,8 @@ pub struct MintState { pub struct ApiDocV1; /// Create mint [`Router`] with required endpoints for cashu mint with the default cache -pub async fn create_mint_router(mint: Arc) -> Result { - create_mint_router_with_custom_cache(mint, Default::default()).await +pub async fn create_mint_router(mint: Arc, include_bolt12: bool) -> Result { + create_mint_router_with_custom_cache(mint, Default::default(), include_bolt12).await } async fn cors_middleware( @@ -187,6 +193,7 @@ async fn cors_middleware( pub async fn create_mint_router_with_custom_cache( mint: Arc, cache: HttpCache, + include_bolt12: bool, ) -> Result { let state = MintState { mint, @@ -223,9 +230,34 @@ pub async fn create_mint_router_with_custom_cache( mint_router.nest("/v1", auth_router) }; - let mint_router = mint_router.layer(from_fn(cors_middleware)); + // Conditionally create and merge bolt12_router + let mint_router = if include_bolt12 { + let bolt12_router = create_bolt12_router(state.clone()); + mint_router.nest("/v1", bolt12_router) + } else { + mint_router + }; - let mint_router = mint_router.with_state(state); + let mint_router = mint_router + .layer(from_fn(cors_middleware)) + .with_state(state); Ok(mint_router) } + +fn create_bolt12_router(state: MintState) -> Router { + Router::new() + .route("/melt/quote/bolt12", post(post_melt_bolt12_quote)) + .route( + "/melt/quote/bolt12/{quote_id}", + get(get_check_melt_bolt11_quote), + ) + .route("/melt/bolt12", post(cache_post_melt_bolt12)) + .route("/mint/quote/bolt12", post(post_mint_bolt12_quote)) + .route( + "/mint/quote/bolt12/{quote_id}", + get(get_check_mint_bolt12_quote), + ) + .route("/mint/bolt12", post(cache_post_mint_bolt12)) + .with_state(state) +} diff --git a/crates/cdk-axum/src/router_handlers.rs b/crates/cdk-axum/src/router_handlers.rs index 0fb937edc..1deee5670 100644 --- a/crates/cdk-axum/src/router_handlers.rs +++ b/crates/cdk-axum/src/router_handlers.rs @@ -22,6 +22,8 @@ use crate::auth::AuthHeader; use crate::ws::main_websocket; use crate::MintState; +/// Macro to add cache to endpoint +#[macro_export] macro_rules! post_cache_wrapper { ($handler:ident, $request_type:ty, $response_type:ty) => { paste! { @@ -163,11 +165,11 @@ pub(crate) async fn post_mint_bolt11_quote( let quote = state .mint - .get_mint_bolt11_quote(payload) + .get_mint_quote(payload.into()) .await .map_err(into_response)?; - Ok(Json(quote)) + Ok(Json(quote.try_into().map_err(into_response)?)) } #[cfg_attr(feature = "swagger", utoipa::path( @@ -212,7 +214,7 @@ pub(crate) async fn get_check_mint_bolt11_quote( into_response(err) })?; - Ok(Json(quote)) + Ok(Json(quote.try_into().map_err(into_response)?)) } #[instrument(skip_all)] @@ -299,7 +301,7 @@ pub(crate) async fn post_melt_bolt11_quote( let quote = state .mint - .get_melt_bolt11_quote(&payload) + .get_melt_quote(payload.into()) .await .map_err(into_response)?; @@ -382,11 +384,7 @@ pub(crate) async fn post_melt_bolt11( .map_err(into_response)?; } - let res = state - .mint - .melt_bolt11(&payload) - .await - .map_err(into_response)?; + let res = state.mint.melt(&payload).await.map_err(into_response)?; Ok(Json(res)) } diff --git a/crates/cdk-cli/Cargo.toml b/crates/cdk-cli/Cargo.toml index 6ec4c8b2b..e6e83a282 100644 --- a/crates/cdk-cli/Cargo.toml +++ b/crates/cdk-cli/Cargo.toml @@ -11,6 +11,8 @@ rust-version.workspace = true readme = "README.md" [features] +default = ["bip353"] +bip353 = ["dep:trust-dns-resolver"] sqlcipher = ["cdk-sqlite/sqlcipher"] # MSRV is not tracked with redb enabled redb = ["dep:cdk-redb"] @@ -37,3 +39,5 @@ nostr-sdk = { version = "0.41.0", default-features = false, features = [ reqwest.workspace = true url.workspace = true serde_with.workspace = true +lightning.workspace = true +trust-dns-resolver = { version = "0.23.2", optional = true } diff --git a/crates/cdk-cli/src/bip353.rs b/crates/cdk-cli/src/bip353.rs new file mode 100644 index 000000000..1d424be44 --- /dev/null +++ b/crates/cdk-cli/src/bip353.rs @@ -0,0 +1,132 @@ +use std::collections::HashMap; +use std::str::FromStr; + +use anyhow::{bail, Result}; +use trust_dns_resolver::config::{ResolverConfig, ResolverOpts}; +use trust_dns_resolver::TokioAsyncResolver; + +#[derive(Debug, Clone, PartialEq, Eq, Hash)] +pub struct Bip353Address { + pub user: String, + pub domain: String, +} + +impl Bip353Address { + /// Resolve a human-readable Bitcoin address + pub async fn resolve(self) -> Result { + // Construct DNS name + let dns_name = format!("{}.user._bitcoin-payment.{}", self.user, self.domain); + + // Create a new resolver with DNSSEC validation + let mut opts = ResolverOpts::default(); + opts.validate = true; // Enable DNSSEC validation + + let resolver = TokioAsyncResolver::tokio(ResolverConfig::default(), opts); + + // Query TXT records - with opts.validate=true, this will fail if DNSSEC validation fails + let response = resolver.txt_lookup(&dns_name).await?; + + // Extract and concatenate TXT record strings + let mut bitcoin_uris = Vec::new(); + + for txt in response.iter() { + let txt_data: Vec = txt + .txt_data() + .iter() + .map(|bytes| String::from_utf8_lossy(bytes).into_owned()) + .collect(); + + let concatenated = txt_data.join(""); + + if concatenated.to_lowercase().starts_with("bitcoin:") { + bitcoin_uris.push(concatenated); + } + } + + // BIP-353 requires exactly one Bitcoin URI + match bitcoin_uris.len() { + 0 => bail!("No Bitcoin URI found"), + 1 => PaymentInstruction::from_uri(&bitcoin_uris[0]), + _ => bail!("Multiple Bitcoin URIs found"), + } + } +} + +impl FromStr for Bip353Address { + type Err = anyhow::Error; + + /// Parse a human-readable Bitcoin address + fn from_str(address: &str) -> Result { + let addr = address.trim(); + + // Remove Bitcoin prefix if present + let addr = addr.strip_prefix("₿").unwrap_or(addr); + + // Split by @ + let parts: Vec<&str> = addr.split('@').collect(); + if parts.len() != 2 { + bail!("Address is not formatted correctly") + } + + let user = parts[0].trim(); + let domain = parts[1].trim(); + + if user.is_empty() || domain.is_empty() { + bail!("User name and domain must not be empty") + } + + Ok(Self { + user: user.to_string(), + domain: domain.to_string(), + }) + } +} + +/// Payment instruction type +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +pub enum PaymentType { + OnChain, + LightningOffer, +} + +/// BIP-353 payment instruction +#[derive(Debug, Clone)] +pub struct PaymentInstruction { + pub parameters: HashMap, +} + +impl PaymentInstruction { + /// Parse a payment instruction from a Bitcoin URI + pub fn from_uri(uri: &str) -> Result { + if !uri.to_lowercase().starts_with("bitcoin:") { + bail!("URI must start with 'bitcoin:'") + } + + let mut parameters = HashMap::new(); + + // Parse URI parameters + if let Some(query_start) = uri.find('?') { + let query = &uri[query_start + 1..]; + for pair in query.split('&') { + if let Some(eq_pos) = pair.find('=') { + let key = pair[..eq_pos].to_string(); + let value = pair[eq_pos + 1..].to_string(); + let payment_type; + // Determine payment type + if key.contains("lno") { + payment_type = PaymentType::LightningOffer; + } else if !uri[8..].contains('?') && uri.len() > 8 { + // Simple on-chain address + payment_type = PaymentType::OnChain; + } else { + continue; + } + + parameters.insert(payment_type, value); + } + } + } + + Ok(PaymentInstruction { parameters }) + } +} diff --git a/crates/cdk-cli/src/main.rs b/crates/cdk-cli/src/main.rs index 252be05b3..7eb554b5a 100644 --- a/crates/cdk-cli/src/main.rs +++ b/crates/cdk-cli/src/main.rs @@ -18,6 +18,8 @@ use tracing::Level; use tracing_subscriber::EnvFilter; use url::Url; +#[cfg(feature = "bip353")] +mod bip353; mod nostr_storage; mod sub_commands; mod token_storage; diff --git a/crates/cdk-cli/src/sub_commands/melt.rs b/crates/cdk-cli/src/sub_commands/melt.rs index bd92dde9c..ea2bd676f 100644 --- a/crates/cdk-cli/src/sub_commands/melt.rs +++ b/crates/cdk-cli/src/sub_commands/melt.rs @@ -1,20 +1,34 @@ use std::str::FromStr; -use anyhow::{bail, Result}; -use cdk::amount::MSAT_IN_SAT; +use anyhow::{anyhow, bail, Result}; +use cdk::amount::{amount_for_offer, Amount, MSAT_IN_SAT}; +use cdk::mint_url::MintUrl; use cdk::nuts::{CurrencyUnit, MeltOptions}; use cdk::wallet::multi_mint_wallet::MultiMintWallet; use cdk::wallet::types::WalletKey; +use cdk::wallet::{MeltQuote, Wallet}; use cdk::Bolt11Invoice; -use clap::Args; +use clap::{Args, ValueEnum}; +use lightning::offers::offer::Offer; use tokio::task::JoinSet; +use crate::bip353::{Bip353Address, PaymentType as Bip353PaymentType}; use crate::sub_commands::balance::mint_balances; use crate::utils::{ get_number_input, get_user_input, get_wallet_by_index, get_wallet_by_mint_url, validate_mint_number, }; +#[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, ValueEnum)] +pub enum PaymentType { + /// BOLT11 invoice + Bolt11, + /// BOLT12 offer + Bolt12, + /// Bip353 + Bip353, +} + #[derive(Args)] pub struct MeltSubCommand { /// Currency unit e.g. sat @@ -26,132 +40,90 @@ pub struct MeltSubCommand { /// Mint URL to use for melting #[arg(long, conflicts_with = "mpp")] mint_url: Option, + /// Payment method (bolt11 or bolt12) + #[arg(long, default_value = "bolt11")] + method: PaymentType, } -pub async fn pay( - multi_mint_wallet: &MultiMintWallet, - sub_command_args: &MeltSubCommand, -) -> Result<()> { - let unit = CurrencyUnit::from_str(&sub_command_args.unit)?; - let mints_amounts = mint_balances(multi_mint_wallet, &unit).await?; +/// Helper function to process a melt quote and execute the payment +async fn process_payment(wallet: &Wallet, quote: MeltQuote) -> Result<()> { + // Display quote information + println!("Quote ID: {}", quote.id); + println!("Amount: {}", quote.amount); + println!("Fee Reserve: {}", quote.fee_reserve); + println!("State: {}", quote.state); + println!("Expiry: {}", quote.expiry); + + // Execute the payment + let melt = wallet.melt("e.id).await?; + println!("Paid: {}", melt.state); + + if let Some(preimage) = melt.preimage { + println!("Payment preimage: {preimage}"); + } - let mut mints = vec![]; - let mut mint_amounts = vec![]; - if sub_command_args.mpp { - // MPP functionality expects multiple mints, so mint_url flag doesn't fully apply here, - // but we can offer to use the specified mint as the first one if provided - if let Some(mint_url) = &sub_command_args.mint_url { - println!("Using mint URL {mint_url} as the first mint for MPP payment."); - - // Check if the mint exists - if let Ok(_wallet) = - get_wallet_by_mint_url(multi_mint_wallet, mint_url, unit.clone()).await - { - // Find the index of this mint in the mints_amounts list - if let Some(mint_index) = mints_amounts - .iter() - .position(|(url, _)| url.to_string() == *mint_url) - { - mints.push(mint_index); - let melt_amount: u64 = - get_number_input("Enter amount to mint from this mint in sats.")?; - mint_amounts.push(melt_amount); - } else { - println!("Warning: Mint URL exists but no balance found. Continuing with manual selection."); - } - } else { - println!("Warning: Could not find wallet for the specified mint URL. Continuing with manual selection."); - } - } - loop { - let mint_number: String = - get_user_input("Enter mint number to melt from and -1 when done.")?; + Ok(()) +} - if mint_number == "-1" || mint_number.is_empty() { - break; +/// Helper function to check if there are enough funds and create appropriate MeltOptions +fn create_melt_options( + available_funds: u64, + payment_amount: Option, + prompt: &str, +) -> Result> { + match payment_amount { + Some(amount) => { + // Payment has a specified amount + if amount > available_funds { + bail!("Not enough funds; payment requires {} msats", amount); } - - let mint_number: usize = mint_number.parse()?; - validate_mint_number(mint_number, mints_amounts.len())?; - - mints.push(mint_number); - let melt_amount: u64 = - get_number_input("Enter amount to mint from this mint in sats.")?; - mint_amounts.push(melt_amount); + Ok(None) // Use default options } + None => { + // Payment doesn't have an amount, ask user for it + let user_amount = get_number_input::(prompt)? * MSAT_IN_SAT; - let bolt11 = Bolt11Invoice::from_str(&get_user_input("Enter bolt11 invoice request")?)?; - - let mut quotes = JoinSet::new(); - - for (mint, amount) in mints.iter().zip(mint_amounts) { - let wallet = mints_amounts[*mint].0.clone(); - - let wallet = multi_mint_wallet - .get_wallet(&WalletKey::new(wallet, unit.clone())) - .await - .expect("Known wallet"); - let options = MeltOptions::new_mpp(amount * 1000); - - let bolt11_clone = bolt11.clone(); - - quotes.spawn(async move { - let quote = wallet - .melt_quote(bolt11_clone.to_string(), Some(options)) - .await; + if user_amount > available_funds { + bail!("Not enough funds"); + } - (wallet, quote) - }); + Ok(Some(MeltOptions::new_amountless(user_amount))) } + } +} - let quotes = quotes.join_all().await; +pub async fn pay( + multi_mint_wallet: &MultiMintWallet, + sub_command_args: &MeltSubCommand, +) -> Result<()> { + let unit = CurrencyUnit::from_str(&sub_command_args.unit)?; + let mints_amounts = mint_balances(multi_mint_wallet, &unit).await?; - for (wallet, quote) in quotes.iter() { - if let Err(quote) = quote { - tracing::error!("Could not get quote for {}: {:?}", wallet.mint_url, quote); - bail!("Could not get melt quote for {}", wallet.mint_url); - } else { - let quote = quote.as_ref().unwrap(); - println!( - "Melt quote {} for mint {} of amount {} with fee {}.", - quote.id, wallet.mint_url, quote.amount, quote.fee_reserve - ); - } + if sub_command_args.mpp { + // MPP logic only works with BOLT11 currently + if !matches!(sub_command_args.method, PaymentType::Bolt11) { + bail!("MPP is only supported for BOLT11 invoices"); } - let mut melts = JoinSet::new(); + // Collect mint numbers and amounts for MPP + let (mints, mint_amounts) = collect_mpp_inputs(&mints_amounts, &sub_command_args.mint_url)?; - for (wallet, quote) in quotes { - let quote = quote.expect("Errors checked above"); - - melts.spawn(async move { - let melt = wallet.melt("e.id).await; - (wallet, melt) - }); - } - - let melts = melts.join_all().await; - - let mut error = false; - - for (wallet, melt) in melts { - match melt { - Ok(melt) => { - println!( - "Melt for {} paid {} with fee of {} ", - wallet.mint_url, melt.amount, melt.fee_paid - ); - } - Err(err) => { - println!("Melt for {} failed with {}", wallet.mint_url, err); - error = true; - } - } - } + // Process BOLT11 MPP payment + let bolt11 = Bolt11Invoice::from_str(&get_user_input("Enter bolt11 invoice request")?)?; - if error { - bail!("Could not complete all melts"); - } + // Get quotes from all mints + let quotes = get_mpp_quotes( + multi_mint_wallet, + &mints_amounts, + &mints, + &mint_amounts, + &unit, + &bolt11, + ) + .await?; + + // Execute all melts + execute_mpp_melts(quotes).await?; } else { // Get wallet either by mint URL or by index let wallet = if let Some(mint_url) = &sub_command_args.mint_url { @@ -174,47 +146,207 @@ pub async fn pay( let available_funds = >::into(mint_amount) * MSAT_IN_SAT; - let bolt11 = Bolt11Invoice::from_str(&get_user_input("Enter bolt11 invoice request")?)?; + // Process payment based on payment method + match sub_command_args.method { + PaymentType::Bolt11 => { + // Process BOLT11 payment + let bolt11 = Bolt11Invoice::from_str(&get_user_input("Enter bolt11 invoice")?)?; + + // Determine payment amount and options + let prompt = + "Enter the amount you would like to pay in sats for this amountless invoice."; + let options = + create_melt_options(available_funds, bolt11.amount_milli_satoshis(), prompt)?; + + // Process payment + let quote = wallet.melt_quote(bolt11.to_string(), options).await?; + process_payment(&wallet, quote).await?; + } + PaymentType::Bolt12 => { + // Process BOLT12 payment (offer) + let offer_str = get_user_input("Enter BOLT12 offer")?; + let offer = Offer::from_str(&offer_str) + .map_err(|e| anyhow::anyhow!("Invalid BOLT12 offer: {:?}", e))?; + + // Determine if offer has an amount + let prompt = + "Enter the amount you would like to pay in sats for this amountless offer:"; + let amount_msat = match amount_for_offer(&offer, &CurrencyUnit::Msat) { + Ok(amount) => Some(u64::from(amount)), + Err(_) => None, + }; + + let options = create_melt_options(available_funds, amount_msat, prompt)?; + + // Get melt quote for BOLT12 + let quote = wallet.melt_bolt12_quote(offer_str, options).await?; + process_payment(&wallet, quote).await?; + } + PaymentType::Bip353 => { + let bip353_addr = get_user_input("Enter Bip353 address.")?; + let bip353_addr = Bip353Address::from_str(&bip353_addr)?; - // Determine payment amount and options - let options = if bolt11.amount_milli_satoshis().is_none() { - // Get user input for amount - let prompt = format!( - "Enter the amount you would like to pay in sats for a {} payment.", - if sub_command_args.mpp { - "MPP" - } else { - "amountless invoice" - } - ); + let payment_instructions = bip353_addr.resolve().await?; - let user_amount = get_number_input::(&prompt)? * MSAT_IN_SAT; + let offer = payment_instructions + .parameters + .get(&Bip353PaymentType::LightningOffer) + .ok_or(anyhow!("Offer not defined"))?; - if user_amount > available_funds { - bail!("Not enough funds"); + let prompt = + "Enter the amount you would like to pay in sats for this amountless offer:"; + // BIP353 payments are always amountless for now + let options = create_melt_options(available_funds, None, prompt)?; + + // Get melt quote for BOLT12 + let quote = wallet.melt_bolt12_quote(offer.to_string(), options).await?; + process_payment(&wallet, quote).await?; } + } + } + + Ok(()) +} + +/// Collect mint numbers and amounts for MPP payments +fn collect_mpp_inputs( + mints_amounts: &[(MintUrl, Amount)], + mint_url_opt: &Option, +) -> Result<(Vec, Vec)> { + let mut mints = Vec::new(); + let mut mint_amounts = Vec::new(); - Some(MeltOptions::new_amountless(user_amount)) + // If a specific mint URL was provided, try to use it as the first mint + if let Some(mint_url) = mint_url_opt { + println!("Using mint URL {mint_url} as the first mint for MPP payment."); + + // Find the index of this mint in the mints_amounts list + if let Some(mint_index) = mints_amounts + .iter() + .position(|(url, _)| url.to_string() == *mint_url) + { + mints.push(mint_index); + let melt_amount: u64 = + get_number_input("Enter amount to mint from this mint in sats.")?; + mint_amounts.push(melt_amount); } else { - // Check if invoice amount exceeds available funds - let invoice_amount = bolt11.amount_milli_satoshis().unwrap(); - if invoice_amount > available_funds { - bail!("Not enough funds"); + println!( + "Warning: Mint URL not found or no balance. Continuing with manual selection." + ); + } + } + + // Continue with regular mint selection + loop { + let mint_number: String = + get_user_input("Enter mint number to melt from and -1 when done.")?; + + if mint_number == "-1" || mint_number.is_empty() { + break; + } + + let mint_number: usize = mint_number.parse()?; + validate_mint_number(mint_number, mints_amounts.len())?; + + mints.push(mint_number); + let melt_amount: u64 = get_number_input("Enter amount to mint from this mint in sats.")?; + mint_amounts.push(melt_amount); + } + + if mints.is_empty() { + bail!("No mints selected for MPP payment"); + } + + Ok((mints, mint_amounts)) +} + +/// Get quotes from all mints for MPP payment +async fn get_mpp_quotes( + multi_mint_wallet: &MultiMintWallet, + mints_amounts: &[(MintUrl, Amount)], + mints: &[usize], + mint_amounts: &[u64], + unit: &CurrencyUnit, + bolt11: &Bolt11Invoice, +) -> Result> { + let mut quotes = JoinSet::new(); + + for (mint, amount) in mints.iter().zip(mint_amounts) { + let wallet = mints_amounts[*mint].0.clone(); + + let wallet = multi_mint_wallet + .get_wallet(&WalletKey::new(wallet, unit.clone())) + .await + .expect("Known wallet"); + let options = MeltOptions::new_mpp(*amount * 1000); + + let bolt11_clone = bolt11.clone(); + + quotes.spawn(async move { + let quote = wallet + .melt_quote(bolt11_clone.to_string(), Some(options)) + .await; + + (wallet, quote) + }); + } + + let quotes_results = quotes.join_all().await; + + // Validate all quotes succeeded + let mut valid_quotes = Vec::new(); + for (wallet, quote_result) in quotes_results { + match quote_result { + Ok(quote) => { + println!( + "Melt quote {} for mint {} of amount {} with fee {}.", + quote.id, wallet.mint_url, quote.amount, quote.fee_reserve + ); + valid_quotes.push((wallet, quote)); } - None - }; + Err(err) => { + tracing::error!("Could not get quote for {}: {:?}", wallet.mint_url, err); + bail!("Could not get melt quote for {}", wallet.mint_url); + } + } + } + + Ok(valid_quotes) +} + +/// Execute all melts for MPP payment +async fn execute_mpp_melts(quotes: Vec<(Wallet, MeltQuote)>) -> Result<()> { + let mut melts = JoinSet::new(); + + for (wallet, quote) in quotes { + melts.spawn(async move { + let melt = wallet.melt("e.id).await; + (wallet, melt) + }); + } - // Process payment - let quote = wallet.melt_quote(bolt11.to_string(), options).await?; - println!("{quote:?}"); + let melts = melts.join_all().await; - let melt = wallet.melt("e.id).await?; - println!("Paid invoice: {}", melt.state); + let mut error = false; - if let Some(preimage) = melt.preimage { - println!("Payment preimage: {preimage}"); + for (wallet, melt) in melts { + match melt { + Ok(melt) => { + println!( + "Melt for {} paid {} with fee of {} ", + wallet.mint_url, melt.amount, melt.fee_paid + ); + } + Err(err) => { + println!("Melt for {} failed with {}", wallet.mint_url, err); + error = true; + } } } + if error { + bail!("Could not complete all melts"); + } + Ok(()) } diff --git a/crates/cdk-cli/src/sub_commands/mint.rs b/crates/cdk-cli/src/sub_commands/mint.rs index 9372bd589..71b2a987e 100644 --- a/crates/cdk-cli/src/sub_commands/mint.rs +++ b/crates/cdk-cli/src/sub_commands/mint.rs @@ -4,7 +4,7 @@ use anyhow::{anyhow, Result}; use cdk::amount::SplitTarget; use cdk::mint_url::MintUrl; use cdk::nuts::nut00::ProofsMethods; -use cdk::nuts::{CurrencyUnit, MintQuoteState, NotificationPayload}; +use cdk::nuts::{CurrencyUnit, MintQuoteState, NotificationPayload, PaymentMethod}; use cdk::wallet::{MultiMintWallet, WalletSubscription}; use cdk::Amount; use clap::Args; @@ -27,6 +27,15 @@ pub struct MintSubCommand { /// Quote Id #[arg(short, long)] quote_id: Option, + /// Payment method + #[arg(long, default_value = "bolt11")] + method: String, + /// Expiry + #[arg(short, long)] + expiry: Option, + /// Expiry + #[arg(short, long)] + single_use: Option, } pub async fn mint( @@ -39,36 +48,104 @@ pub async fn mint( let wallet = get_or_create_wallet(multi_mint_wallet, &mint_url, unit).await?; + let mut payment_method = PaymentMethod::from_str(&sub_command_args.method)?; + let quote_id = match &sub_command_args.quote_id { - None => { - let amount = sub_command_args - .amount - .ok_or(anyhow!("Amount must be defined"))?; - let quote = wallet.mint_quote(Amount::from(amount), description).await?; - - println!("Quote: {quote:#?}"); - - println!("Please pay: {}", quote.request); - - let mut subscription = wallet - .subscribe(WalletSubscription::Bolt11MintQuoteState(vec![quote - .id - .clone()])) - .await; - - while let Some(msg) = subscription.recv().await { - if let NotificationPayload::MintQuoteBolt11Response(response) = msg { - if response.state == MintQuoteState::Paid { - break; + None => match payment_method { + PaymentMethod::Bolt11 => { + let amount = sub_command_args + .amount + .ok_or(anyhow!("Amount must be defined"))?; + let quote = wallet.mint_quote(Amount::from(amount), description).await?; + + println!("Quote: {quote:#?}"); + + println!("Please pay: {}", quote.request); + + let mut subscription = wallet + .subscribe(WalletSubscription::Bolt11MintQuoteState(vec![quote + .id + .clone()])) + .await; + + while let Some(msg) = subscription.recv().await { + if let NotificationPayload::MintQuoteBolt11Response(response) = msg { + if response.state == MintQuoteState::Paid { + break; + } + } + } + quote.id + } + PaymentMethod::Bolt12 => { + let amount = sub_command_args.amount; + println!("{:?}", sub_command_args.single_use); + let quote = wallet + .mint_bolt12_quote(amount.map(|a| a.into()), description) + .await?; + + println!("Quote: {quote:#?}"); + + println!("Please pay: {}", quote.request); + + let mut subscription = wallet + .subscribe(WalletSubscription::Bolt11MintQuoteState(vec![quote + .id + .clone()])) + .await; + + while let Some(msg) = subscription.recv().await { + if let NotificationPayload::MintQuoteBolt11Response(response) = msg { + if response.state == MintQuoteState::Paid { + break; + } } } + quote.id + } + _ => { + todo!() } - quote.id + }, + Some(quote_id) => { + let quote = wallet + .localstore + .get_mint_quote(quote_id) + .await? + .ok_or(anyhow!("Unknown quote"))?; + + payment_method = quote.payment_method; + quote_id.to_string() } - Some(quote_id) => quote_id.to_string(), }; - let proofs = wallet.mint("e_id, SplitTarget::default(), None).await?; + tracing::debug!("Attempting mint for: {}", payment_method); + + let proofs = match payment_method { + PaymentMethod::Bolt11 => wallet.mint("e_id, SplitTarget::default(), None).await?, + PaymentMethod::Bolt12 => { + let response = wallet.mint_bolt12_quote_state("e_id).await?; + + let amount_mintable = response.amount_paid - response.amount_issued; + + if amount_mintable == Amount::ZERO { + println!("Mint quote does not have amount that can be minted."); + return Ok(()); + } + + wallet + .mint_bolt12( + "e_id, + Some(amount_mintable), + SplitTarget::default(), + None, + ) + .await? + } + _ => { + todo!() + } + }; let receive_amount = proofs.total_amount()?; diff --git a/crates/cdk-cln/src/error.rs b/crates/cdk-cln/src/error.rs index 7fd489ff1..2f9d8e0e9 100644 --- a/crates/cdk-cln/src/error.rs +++ b/crates/cdk-cln/src/error.rs @@ -26,6 +26,12 @@ pub enum Error { /// Amount Error #[error(transparent)] Amount(#[from] cdk_common::amount::Error), + /// UTF-8 Error + #[error(transparent)] + Utf8(#[from] std::string::FromUtf8Error), + /// Bolt12 Error + #[error("Bolt12 error: {0}")] + Bolt12(String), } impl From for cdk_common::payment::Error { diff --git a/crates/cdk-cln/src/lib.rs b/crates/cdk-cln/src/lib.rs index 916e30e3b..a52dae615 100644 --- a/crates/cdk-cln/src/lib.rs +++ b/crates/cdk-cln/src/lib.rs @@ -10,29 +10,35 @@ use std::pin::Pin; use std::str::FromStr; use std::sync::atomic::{AtomicBool, Ordering}; use std::sync::Arc; +use std::time::Duration; use async_trait::async_trait; +use bitcoin::hashes::sha256::Hash; use cdk_common::amount::{to_unit, Amount}; use cdk_common::common::FeeReserve; -use cdk_common::nuts::{CurrencyUnit, MeltOptions, MeltQuoteState, MintQuoteState}; +use cdk_common::nuts::{CurrencyUnit, MeltOptions, MeltQuoteState}; use cdk_common::payment::{ - self, Bolt11Settings, CreateIncomingPaymentResponse, MakePaymentResponse, MintPayment, - PaymentQuoteResponse, + self, Bolt11IncomingPaymentOptions, Bolt11Settings, Bolt12IncomingPaymentOptions, + CreateIncomingPaymentResponse, IncomingPaymentOptions, MakePaymentResponse, MintPayment, + OutgoingPaymentOptions, PaymentIdentifier, PaymentQuoteResponse, WaitPaymentResponse, }; use cdk_common::util::{hex, unix_time}; -use cdk_common::{mint, Bolt11Invoice}; +use cdk_common::Bolt11Invoice; use cln_rpc::model::requests::{ - InvoiceRequest, ListinvoicesRequest, ListpaysRequest, PayRequest, WaitanyinvoiceRequest, + DecodeRequest, FetchinvoiceRequest, InvoiceRequest, ListinvoicesRequest, ListpaysRequest, + OfferRequest, PayRequest, WaitanyinvoiceRequest, }; use cln_rpc::model::responses::{ - ListinvoicesInvoices, ListinvoicesInvoicesStatus, ListpaysPaysStatus, PayStatus, - WaitanyinvoiceStatus, + DecodeResponse, ListinvoicesInvoices, ListinvoicesInvoicesStatus, ListpaysPaysStatus, + PayStatus, WaitanyinvoiceResponse, WaitanyinvoiceStatus, }; -use cln_rpc::primitives::{Amount as CLN_Amount, AmountOrAny}; +use cln_rpc::primitives::{Amount as CLN_Amount, AmountOrAny, Sha256}; +use cln_rpc::ClnRpc; use error::Error; use futures::{Stream, StreamExt}; use serde_json::Value; use tokio_util::sync::CancellationToken; +use tracing::instrument; use uuid::Uuid; pub mod error; @@ -68,6 +74,7 @@ impl MintPayment for Cln { unit: CurrencyUnit::Msat, invoice_description: true, amountless: true, + bolt12: true, })?) } @@ -81,12 +88,33 @@ impl MintPayment for Cln { self.wait_invoice_cancel_token.cancel() } + #[instrument(skip_all)] async fn wait_any_incoming_payment( &self, - ) -> Result + Send>>, Self::Err> { - let last_pay_index = self.get_last_pay_index().await?; - let cln_client = cln_rpc::ClnRpc::new(&self.rpc_socket).await?; + ) -> Result + Send>>, Self::Err> { + tracing::info!( + "CLN: Starting wait_any_incoming_payment with socket: {:?}", + self.rpc_socket + ); + + let last_pay_index = self.get_last_pay_index().await?.map(|idx| { + tracing::info!("CLN: Found last payment index: {}", idx); + idx + }); + + tracing::debug!("CLN: Connecting to CLN node..."); + let cln_client = match cln_rpc::ClnRpc::new(&self.rpc_socket).await { + Ok(client) => { + tracing::debug!("CLN: Successfully connected to CLN node"); + client + } + Err(err) => { + tracing::error!("CLN: Failed to connect to CLN node: {}", err); + return Err(Error::from(err).into()); + } + }; + tracing::debug!("CLN: Creating stream processing pipeline"); let stream = futures::stream::unfold( ( cln_client, @@ -97,70 +125,133 @@ impl MintPayment for Cln { |(mut cln_client, mut last_pay_idx, cancel_token, is_active)| async move { // Set the stream as active is_active.store(true, Ordering::SeqCst); + tracing::debug!("CLN: Stream is now active, waiting for invoice events with lastpay_index: {:?}", last_pay_idx); loop { - let request = WaitanyinvoiceRequest { - timeout: None, - lastpay_index: last_pay_idx, - }; tokio::select! { _ = cancel_token.cancelled() => { // Set the stream as inactive is_active.store(false, Ordering::SeqCst); + tracing::info!("CLN: Invoice stream cancelled"); // End the stream return None; } - result = cln_client.call_typed(&request) => { + result = cln_client.call(cln_rpc::Request::WaitAnyInvoice(WaitanyinvoiceRequest { + timeout: None, + lastpay_index: last_pay_idx, + })) => { + tracing::debug!("CLN: Received response from WaitAnyInvoice call"); match result { Ok(invoice) => { + tracing::debug!("CLN: Successfully received invoice data"); + // Try to convert the invoice to WaitanyinvoiceResponse + let wait_any_response_result: Result = + invoice.try_into(); + + let wait_any_response = match wait_any_response_result { + Ok(response) => { + tracing::debug!("CLN: Parsed WaitAnyInvoice response successfully"); + response + } + Err(e) => { + tracing::warn!( + "CLN: Failed to parse WaitAnyInvoice response: {:?}", + e + ); + // Continue to the next iteration without panicking + continue; + } + }; // Check the status of the invoice // We only want to yield invoices that have been paid - match invoice.status { - WaitanyinvoiceStatus::PAID => (), - WaitanyinvoiceStatus::EXPIRED => continue, + match wait_any_response.status { + WaitanyinvoiceStatus::PAID => { + tracing::info!("CLN: Invoice with payment index {} is PAID", + wait_any_response.pay_index.unwrap_or_default()); + } + WaitanyinvoiceStatus::EXPIRED => { + tracing::debug!("CLN: Invoice with payment index {} is EXPIRED, skipping", + wait_any_response.pay_index.unwrap_or_default()); + continue; + } } - last_pay_idx = invoice.pay_index; + last_pay_idx = wait_any_response.pay_index; + tracing::debug!("CLN: Updated last_pay_idx to {:?}", last_pay_idx); + + let payment_hash = wait_any_response.payment_hash; + tracing::debug!("CLN: Payment hash: {}", payment_hash); + + let amount_msats = match wait_any_response.amount_received_msat { + Some(amt) => { + tracing::info!("CLN: Received payment of {} msats for {}", + amt.msat(), payment_hash); + amt + } + None => { + tracing::error!("CLN: No amount in paid invoice, this should not happen"); + continue; + } + }; + let amount_sats = amount_msats.msat() / 1000; - let payment_hash = invoice.payment_hash.to_string(); + let payment_hash = Hash::from_bytes_ref(payment_hash.as_ref()); - let request_look_up = match invoice.bolt12 { + let request_lookup_id = match wait_any_response.bolt12 { // If it is a bolt12 payment we need to get the offer_id as this is what we use as the request look up. // Since this is not returned in the wait any response, // we need to do a second query for it. - Some(_) => { + Some(bolt12) => { + tracing::info!("CLN: Processing BOLT12 payment, bolt12 value: {}", bolt12); match fetch_invoice_by_payment_hash( &mut cln_client, - &payment_hash, + payment_hash, ) .await { Ok(Some(invoice)) => { if let Some(local_offer_id) = invoice.local_offer_id { - local_offer_id.to_string() + tracing::info!("CLN: Received bolt12 payment of {} sats for offer {}", + amount_sats, local_offer_id); + PaymentIdentifier::OfferId(local_offer_id.to_string()) } else { + tracing::warn!("CLN: BOLT12 invoice has no local_offer_id, skipping"); continue; } } - Ok(None) => continue, + Ok(None) => { + tracing::warn!("CLN: Failed to find invoice by payment hash, skipping"); + continue; + } Err(e) => { tracing::warn!( - "Error fetching invoice by payment hash: {e}" + "CLN: Error fetching invoice by payment hash: {e}" ); continue; } } } - None => payment_hash, + None => { + tracing::info!("CLN: Processing BOLT11 payment with hash {}", payment_hash); + PaymentIdentifier::PaymentHash(*payment_hash.as_ref()) + }, + }; + + let response = WaitPaymentResponse { + payment_identifier: request_lookup_id, + payment_amount: amount_sats.into(), + unit: CurrencyUnit::Sat, + payment_id: payment_hash.to_string() }; + tracing::info!("CLN: Created WaitPaymentResponse with amount {} sats", amount_sats); - return Some((request_look_up, (cln_client, last_pay_idx, cancel_token, is_active))); + break Some((response, (cln_client, last_pay_idx, cancel_token, is_active))); } Err(e) => { - tracing::warn!("Error fetching invoice: {e}"); - is_active.store(false, Ordering::SeqCst); - return None; + tracing::warn!("CLN: Error fetching invoice: {e}"); + tokio::time::sleep(Duration::from_secs(1)).await; + continue; } } } @@ -170,80 +261,199 @@ impl MintPayment for Cln { ) .boxed(); + tracing::info!("CLN: Successfully initialized invoice stream"); Ok(stream) } + #[instrument(skip_all)] async fn get_payment_quote( &self, - request: &str, unit: &CurrencyUnit, - options: Option, + options: OutgoingPaymentOptions, ) -> Result { - let bolt11 = Bolt11Invoice::from_str(request)?; - - let amount_msat = match options { - Some(amount) => amount.amount_msat(), - None => bolt11 - .amount_milli_satoshis() - .ok_or(Error::UnknownInvoiceAmount)? - .into(), - }; - - let amount = to_unit(amount_msat, &CurrencyUnit::Msat, unit)?; + match options { + OutgoingPaymentOptions::Bolt11(bolt11_options) => { + // If we have specific amount options, use those + let amount_msat: Amount = if let Some(melt_options) = bolt11_options.melt_options { + match melt_options { + MeltOptions::Amountless { amountless } => { + let amount_msat = amountless.amount_msat; + + if let Some(invoice_amount) = + bolt11_options.bolt11.amount_milli_satoshis() + { + if !invoice_amount == u64::from(amount_msat) { + return Err(payment::Error::AmountMismatch); + } + } + amount_msat + } + MeltOptions::Mpp { mpp } => mpp.amount, + } + } else { + // Fall back to invoice amount + bolt11_options + .bolt11 + .amount_milli_satoshis() + .ok_or(Error::UnknownInvoiceAmount)? + .into() + }; + // Convert to target unit + let amount = to_unit(amount_msat, &CurrencyUnit::Msat, unit)?; + + // Calculate fee + let relative_fee_reserve = + (self.fee_reserve.percent_fee_reserve * u64::from(amount) as f32) as u64; + let absolute_fee_reserve: u64 = self.fee_reserve.min_fee_reserve.into(); + let fee = max(relative_fee_reserve, absolute_fee_reserve); + + Ok(PaymentQuoteResponse { + request_lookup_id: PaymentIdentifier::PaymentHash( + *bolt11_options.bolt11.payment_hash().as_ref(), + ), + amount, + fee: fee.into(), + state: MeltQuoteState::Unpaid, + options: None, + unit: unit.clone(), + }) + } + OutgoingPaymentOptions::Bolt12(bolt12_options) => { + let offer = bolt12_options.offer; + + let amount_msat: u64 = if let Some(amount) = bolt12_options.melt_options { + amount.amount_msat().into() + } else { + // Fall back to offer amount + let decode_response = self.decode_string(offer.to_string()).await?; + + decode_response + .offer_amount_msat + .ok_or(Error::UnknownInvoiceAmount)? + .msat() + }; - let relative_fee_reserve = - (self.fee_reserve.percent_fee_reserve * u64::from(amount) as f32) as u64; + // Convert to target unit + let amount = to_unit(amount_msat, &CurrencyUnit::Msat, unit)?; + + // Calculate fee + let relative_fee_reserve = + (self.fee_reserve.percent_fee_reserve * u64::from(amount) as f32) as u64; + let absolute_fee_reserve: u64 = self.fee_reserve.min_fee_reserve.into(); + let fee = max(relative_fee_reserve, absolute_fee_reserve); + + let cln_response; + { + // Fetch invoice from offer + let mut cln_client = self.cln_client().await?; + + cln_response = cln_client + .call_typed(&FetchinvoiceRequest { + amount_msat: Some(CLN_Amount::from_msat(amount_msat)), + payer_metadata: None, + payer_note: None, + quantity: None, + recurrence_counter: None, + recurrence_label: None, + recurrence_start: None, + timeout: None, + offer: offer.to_string(), + bip353: None, + }) + .await + .map_err(|err| { + tracing::error!("Could not fetch invoice for offer: {:?}", err); + Error::ClnRpc(err) + })?; + } - let absolute_fee_reserve: u64 = self.fee_reserve.min_fee_reserve.into(); + let decode_response = self.decode_string(cln_response.invoice.clone()).await?; - let fee = max(relative_fee_reserve, absolute_fee_reserve); + let options = payment::PaymentQuoteOptions::Bolt12 { + invoice: Some(cln_response.invoice.into()), + }; - Ok(PaymentQuoteResponse { - request_lookup_id: bolt11.payment_hash().to_string(), - amount, - unit: unit.clone(), - fee: fee.into(), - state: MeltQuoteState::Unpaid, - }) + Ok(PaymentQuoteResponse { + request_lookup_id: PaymentIdentifier::Bolt12PaymentHash( + hex::decode( + decode_response + .invoice_payment_hash + .ok_or(Error::UnknownInvoice)?, + ) + .unwrap() + .try_into() + .map_err(|_| Error::InvalidHash)?, + ), + amount, + fee: fee.into(), + state: MeltQuoteState::Unpaid, + options: Some(options), + unit: unit.clone(), + }) + } + } } + #[instrument(skip_all)] async fn make_payment( &self, - melt_quote: mint::MeltQuote, - partial_amount: Option, - max_fee: Option, + unit: &CurrencyUnit, + options: OutgoingPaymentOptions, ) -> Result { - let bolt11 = Bolt11Invoice::from_str(&melt_quote.request)?; - let pay_state = self - .check_outgoing_payment(&bolt11.payment_hash().to_string()) - .await?; + let max_fee_msat: Option; + let mut partial_amount: Option = None; + let mut amount_msat: Option = None; + + let invoice = match options { + OutgoingPaymentOptions::Bolt11(bolt11_options) => { + let payment_identifier = + PaymentIdentifier::PaymentHash(*bolt11_options.bolt11.payment_hash().as_ref()); + + self.check_outgoing_unpaided(&payment_identifier).await?; + + if let Some(melt_options) = bolt11_options.melt_options { + match melt_options { + MeltOptions::Mpp { mpp } => partial_amount = Some(mpp.amount.into()), + MeltOptions::Amountless { amountless } => { + amount_msat = Some(amountless.amount_msat.into()); + } + } + } - match pay_state.status { - MeltQuoteState::Unpaid | MeltQuoteState::Unknown | MeltQuoteState::Failed => (), - MeltQuoteState::Paid => { - tracing::debug!("Melt attempted on invoice already paid"); - return Err(Self::Err::InvoiceAlreadyPaid); + max_fee_msat = bolt11_options.max_fee_amount.map(|a| a.into()); + + bolt11_options.bolt11.to_string() } - MeltQuoteState::Pending => { - tracing::debug!("Melt attempted on invoice already pending"); - return Err(Self::Err::InvoicePaymentPending); + OutgoingPaymentOptions::Bolt12(bolt12_options) => { + let bolt12_invoice = bolt12_options.invoice.ok_or(Error::UnknownInvoice)?; + let decode_response = self + .decode_string(String::from_utf8(bolt12_invoice.clone()).map_err(Error::Utf8)?) + .await?; + + let payment_identifier = PaymentIdentifier::Bolt12PaymentHash( + hex::decode( + decode_response + .invoice_payment_hash + .ok_or(Error::UnknownInvoice)?, + ) + .map_err(|e| Error::Bolt12(e.to_string()))? + .try_into() + .map_err(|_| Error::InvalidHash)?, + ); + + self.check_outgoing_unpaided(&payment_identifier).await?; + + max_fee_msat = bolt12_options.max_fee_amount.map(|a| a.into()); + String::from_utf8(bolt12_invoice).map_err(Error::Utf8)? } - } + }; - let amount_msat = partial_amount - .is_none() - .then(|| { - melt_quote - .msat_to_pay - .map(|a| CLN_Amount::from_msat(a.into())) - }) - .flatten(); + let mut cln_client = self.cln_client().await?; - let mut cln_client = cln_rpc::ClnRpc::new(&self.rpc_socket).await?; let cln_response = cln_client .call_typed(&PayRequest { - bolt11: melt_quote.request.to_string(), - amount_msat, + bolt11: invoice, + amount_msat: amount_msat.map(CLN_Amount::from_msat), label: None, riskfactor: None, maxfeepercent: None, @@ -252,22 +462,9 @@ impl MintPayment for Cln { exemptfee: None, localinvreqid: None, exclude: None, - maxfee: max_fee - .map(|a| { - let msat = to_unit(a, &melt_quote.unit, &CurrencyUnit::Msat)?; - Ok::(CLN_Amount::from_msat(msat.into())) - }) - .transpose()?, + maxfee: max_fee_msat.map(CLN_Amount::from_msat), description: None, - partial_msat: partial_amount - .map(|a| { - let msat = to_unit(a, &melt_quote.unit, &CurrencyUnit::Msat)?; - - Ok::(CLN_Amount::from_msat( - msat.into(), - )) - }) - .transpose()?, + partial_msat: partial_amount.map(CLN_Amount::from_msat), }) .await; @@ -279,16 +476,19 @@ impl MintPayment for Cln { PayStatus::FAILED => MeltQuoteState::Failed, }; + let payment_identifier = + PaymentIdentifier::PaymentHash(*pay_response.payment_hash.as_ref()); + MakePaymentResponse { payment_proof: Some(hex::encode(pay_response.payment_preimage.to_vec())), - payment_lookup_id: pay_response.payment_hash.to_string(), + payment_lookup_id: payment_identifier, status, total_spent: to_unit( pay_response.amount_sent_msat.msat(), &CurrencyUnit::Msat, - &melt_quote.unit, + unit, )?, - unit: melt_quote.unit, + unit: unit.clone(), } } Err(err) => { @@ -300,90 +500,206 @@ impl MintPayment for Cln { Ok(response) } + #[instrument(skip_all)] async fn create_incoming_payment_request( &self, - amount: Amount, unit: &CurrencyUnit, - description: String, - unix_expiry: Option, + options: IncomingPaymentOptions, ) -> Result { - let time_now = unix_time(); - - let mut cln_client = cln_rpc::ClnRpc::new(&self.rpc_socket).await?; - - let label = Uuid::new_v4().to_string(); - - let amount = to_unit(amount, unit, &CurrencyUnit::Msat)?; - let amount_msat = AmountOrAny::Amount(CLN_Amount::from_msat(amount.into())); - - let invoice_response = cln_client - .call_typed(&InvoiceRequest { - amount_msat, + match options { + IncomingPaymentOptions::Bolt11(Bolt11IncomingPaymentOptions { description, - label: label.clone(), - expiry: unix_expiry.map(|t| t - time_now), - fallbacks: None, - preimage: None, - cltv: None, - deschashonly: None, - exposeprivatechannels: None, - }) - .await - .map_err(Error::from)?; + amount, + unix_expiry, + }) => { + let time_now = unix_time(); + + let mut cln_client = self.cln_client().await?; + + let label = Uuid::new_v4().to_string(); + + let amount = to_unit(amount, unit, &CurrencyUnit::Msat)?; + let amount_msat = AmountOrAny::Amount(CLN_Amount::from_msat(amount.into())); + + let invoice_response = cln_client + .call_typed(&InvoiceRequest { + amount_msat, + description: description.unwrap_or_default(), + label: label.clone(), + expiry: unix_expiry.map(|t| t - time_now), + fallbacks: None, + preimage: None, + cltv: None, + deschashonly: None, + exposeprivatechannels: None, + }) + .await + .map_err(Error::from)?; - let request = Bolt11Invoice::from_str(&invoice_response.bolt11)?; - let expiry = request.expires_at().map(|t| t.as_secs()); - let payment_hash = request.payment_hash(); + let request = Bolt11Invoice::from_str(&invoice_response.bolt11)?; + let expiry = request.expires_at().map(|t| t.as_secs()); + let payment_hash = request.payment_hash(); - Ok(CreateIncomingPaymentResponse { - request_lookup_id: payment_hash.to_string(), - request: request.to_string(), - expiry, - }) + Ok(CreateIncomingPaymentResponse { + request_lookup_id: PaymentIdentifier::PaymentHash(*payment_hash.as_ref()), + request: request.to_string(), + expiry, + }) + } + IncomingPaymentOptions::Bolt12(bolt12_options) => { + let Bolt12IncomingPaymentOptions { + description, + amount, + unix_expiry, + } = *bolt12_options; + let mut cln_client = self.cln_client().await?; + + let label = Uuid::new_v4().to_string(); + + // Match like this until we change to option + let amount = match amount { + Some(amount) => { + let amount = to_unit(amount, unit, &CurrencyUnit::Msat)?; + + amount.to_string() + } + None => "any".to_string(), + }; + + // It seems that the only way to force cln to create a unique offer + // is to encode some random data in the offer + let issuer = Uuid::new_v4().to_string(); + + let offer_response = cln_client + .call_typed(&OfferRequest { + amount, + absolute_expiry: unix_expiry, + description: Some(description.unwrap_or_default()), + issuer: Some(issuer.to_string()), + label: Some(label.to_string()), + single_use: None, + quantity_max: None, + recurrence: None, + recurrence_base: None, + recurrence_limit: None, + recurrence_paywindow: None, + recurrence_start_any_period: None, + }) + .await + .map_err(Error::from)?; + + Ok(CreateIncomingPaymentResponse { + request_lookup_id: PaymentIdentifier::OfferId( + offer_response.offer_id.to_string(), + ), + request: offer_response.bolt12, + expiry: unix_expiry, + }) + } + } } + #[instrument(skip(self))] async fn check_incoming_payment_status( &self, - payment_hash: &str, - ) -> Result { - let mut cln_client = cln_rpc::ClnRpc::new(&self.rpc_socket).await?; - - let listinvoices_response = cln_client - .call_typed(&ListinvoicesRequest { - payment_hash: Some(payment_hash.to_string()), - label: None, - invstring: None, - offer_id: None, - index: None, - limit: None, - start: None, - }) - .await - .map_err(Error::from)?; - - let status = match listinvoices_response.invoices.first() { - Some(invoice_response) => cln_invoice_status_to_mint_state(invoice_response.status), - None => { - tracing::info!( - "Check invoice called on unknown look up id: {}", - payment_hash - ); - return Err(Error::WrongClnResponse.into()); + payment_identifier: &PaymentIdentifier, + ) -> Result, Self::Err> { + let mut cln_client = self.cln_client().await?; + + let listinvoices_response = match payment_identifier { + PaymentIdentifier::Label(label) => { + // Query by label + cln_client + .call_typed(&ListinvoicesRequest { + payment_hash: None, + label: Some(label.to_string()), + invstring: None, + offer_id: None, + index: None, + limit: None, + start: None, + }) + .await + .map_err(Error::from)? + } + PaymentIdentifier::OfferId(offer_id) => { + // Query by offer_id + cln_client + .call_typed(&ListinvoicesRequest { + payment_hash: None, + label: None, + invstring: None, + offer_id: Some(offer_id.to_string()), + index: None, + limit: None, + start: None, + }) + .await + .map_err(Error::from)? + } + PaymentIdentifier::PaymentHash(payment_hash) => { + // Query by payment_hash + cln_client + .call_typed(&ListinvoicesRequest { + payment_hash: Some(hex::encode(payment_hash)), + label: None, + invstring: None, + offer_id: None, + index: None, + limit: None, + start: None, + }) + .await + .map_err(Error::from)? + } + PaymentIdentifier::CustomId(_) => { + tracing::error!("Unsupported payment id for CLN"); + return Err(payment::Error::UnknownPaymentState); + } + PaymentIdentifier::Bolt12PaymentHash(_) => { + tracing::error!("Unsupported payment id for CLN"); + return Err(payment::Error::UnknownPaymentState); } }; - Ok(status) + Ok(listinvoices_response + .invoices + .iter() + .filter(|p| p.status == ListinvoicesInvoicesStatus::PAID) + .filter(|p| p.amount_msat.is_some()) // Filter out invoices without an amount + .map(|p| WaitPaymentResponse { + payment_identifier: payment_identifier.clone(), + payment_amount: p + .amount_msat + // Safe to expect since we filtered for Some + .expect("We have filter out those without amounts") + .msat() + .into(), + unit: CurrencyUnit::Msat, + payment_id: p.payment_hash.to_string(), + }) + .collect()) } + #[instrument(skip(self))] async fn check_outgoing_payment( &self, - payment_hash: &str, + payment_identifier: &PaymentIdentifier, ) -> Result { - let mut cln_client = cln_rpc::ClnRpc::new(&self.rpc_socket).await?; + let mut cln_client = self.cln_client().await?; + + let payment_hash = match payment_identifier { + PaymentIdentifier::PaymentHash(hash) => hash, + PaymentIdentifier::Bolt12PaymentHash(hash) => hash, + _ => { + tracing::error!("Unsupported identifier to check outgoing payment for cln."); + return Err(payment::Error::UnknownPaymentState); + } + }; let listpays_response = cln_client .call_typed(&ListpaysRequest { - payment_hash: Some(payment_hash.parse().map_err(|_| Error::InvalidHash)?), + payment_hash: Some(*Sha256::from_bytes_ref(payment_hash)), bolt11: None, status: None, start: None, @@ -398,7 +714,7 @@ impl MintPayment for Cln { let status = cln_pays_status_to_mint_state(pays_response.status); Ok(MakePaymentResponse { - payment_lookup_id: pays_response.payment_hash.to_string(), + payment_lookup_id: payment_identifier.clone(), payment_proof: pays_response.preimage.map(|p| hex::encode(p.to_vec())), status, total_spent: pays_response @@ -408,7 +724,7 @@ impl MintPayment for Cln { }) } None => Ok(MakePaymentResponse { - payment_lookup_id: payment_hash.to_string(), + payment_lookup_id: payment_identifier.clone(), payment_proof: None, status: MeltQuoteState::Unknown, total_spent: Amount::ZERO, @@ -419,9 +735,13 @@ impl MintPayment for Cln { } impl Cln { + async fn cln_client(&self) -> Result { + Ok(cln_rpc::ClnRpc::new(&self.rpc_socket).await?) + } + /// Get last pay index for cln async fn get_last_pay_index(&self) -> Result, Error> { - let mut cln_client = cln_rpc::ClnRpc::new(&self.rpc_socket).await?; + let mut cln_client = self.cln_client().await?; let listinvoices_response = cln_client .call_typed(&ListinvoicesRequest { index: None, @@ -440,13 +760,40 @@ impl Cln { None => Ok(None), } } -} -fn cln_invoice_status_to_mint_state(status: ListinvoicesInvoicesStatus) -> MintQuoteState { - match status { - ListinvoicesInvoicesStatus::UNPAID => MintQuoteState::Unpaid, - ListinvoicesInvoicesStatus::PAID => MintQuoteState::Paid, - ListinvoicesInvoicesStatus::EXPIRED => MintQuoteState::Unpaid, + /// Decode string + #[instrument(skip(self))] + async fn decode_string(&self, string: String) -> Result { + let mut cln_client = self.cln_client().await?; + + cln_client + .call_typed(&DecodeRequest { string }) + .await + .map_err(|err| { + tracing::error!("Could not fetch invoice for offer: {:?}", err); + Error::ClnRpc(err) + }) + } + + /// Checks that outgoing payment is not already paid + #[instrument(skip(self))] + async fn check_outgoing_unpaided( + &self, + payment_identifier: &PaymentIdentifier, + ) -> Result<(), payment::Error> { + let pay_state = self.check_outgoing_payment(payment_identifier).await?; + + match pay_state.status { + MeltQuoteState::Unpaid | MeltQuoteState::Unknown | MeltQuoteState::Failed => Ok(()), + MeltQuoteState::Paid => { + tracing::debug!("Melt attempted on invoice already paid"); + Err(payment::Error::InvoiceAlreadyPaid) + } + MeltQuoteState::Pending => { + tracing::debug!("Melt attempted on invoice already pending"); + Err(payment::Error::InvoicePaymentPending) + } + } } } @@ -460,23 +807,57 @@ fn cln_pays_status_to_mint_state(status: ListpaysPaysStatus) -> MeltQuoteState { async fn fetch_invoice_by_payment_hash( cln_client: &mut cln_rpc::ClnRpc, - payment_hash: &str, + payment_hash: &Hash, ) -> Result, Error> { - match cln_client - .call_typed(&ListinvoicesRequest { - payment_hash: Some(payment_hash.to_string()), - index: None, - invstring: None, - label: None, - limit: None, - offer_id: None, - start: None, - }) - .await - { - Ok(invoice_response) => Ok(invoice_response.invoices.first().cloned()), + tracing::debug!("Fetching invoice by payment hash: {}", payment_hash); + + let payment_hash_str = payment_hash.to_string(); + tracing::debug!("Payment hash string: {}", payment_hash_str); + + let request = ListinvoicesRequest { + payment_hash: Some(payment_hash_str), + index: None, + invstring: None, + label: None, + limit: None, + offer_id: None, + start: None, + }; + tracing::debug!("Created ListinvoicesRequest"); + + match cln_client.call_typed(&request).await { + Ok(invoice_response) => { + let invoice_count = invoice_response.invoices.len(); + tracing::debug!( + "Received {} invoices for payment hash {}", + invoice_count, + payment_hash + ); + + if invoice_count > 0 { + let first_invoice = invoice_response.invoices.first().cloned(); + if let Some(invoice) = &first_invoice { + tracing::debug!("Found invoice with payment hash {}", payment_hash); + tracing::debug!( + "Invoice details - local_offer_id: {:?}, status: {:?}", + invoice.local_offer_id, + invoice.status + ); + } else { + tracing::warn!("No invoice found with payment hash {}", payment_hash); + } + Ok(first_invoice) + } else { + tracing::warn!("No invoices returned for payment hash {}", payment_hash); + Ok(None) + } + } Err(e) => { - tracing::warn!("Error fetching invoice: {e}"); + tracing::error!( + "Error fetching invoice by payment hash {}: {}", + payment_hash, + e + ); Err(Error::from(e)) } } diff --git a/crates/cdk-common/Cargo.toml b/crates/cdk-common/Cargo.toml index 2c9ce3912..a6c1466a7 100644 --- a/crates/cdk-common/Cargo.toml +++ b/crates/cdk-common/Cargo.toml @@ -27,6 +27,7 @@ cbor-diag.workspace = true ciborium.workspace = true serde.workspace = true lightning-invoice.workspace = true +lightning.workspace = true thiserror.workspace = true tracing.workspace = true url.workspace = true diff --git a/crates/cdk-common/src/database/mint/mod.rs b/crates/cdk-common/src/database/mint/mod.rs index 95eb3db09..7ba65304b 100644 --- a/crates/cdk-common/src/database/mint/mod.rs +++ b/crates/cdk-common/src/database/mint/mod.rs @@ -3,16 +3,16 @@ use std::collections::HashMap; use async_trait::async_trait; -use cashu::MintInfo; +use cashu::{Amount, MintInfo}; use uuid::Uuid; use super::Error; use crate::common::QuoteTTL; use crate::mint::{self, MintKeySetInfo, MintQuote as MintMintQuote}; use crate::nuts::{ - BlindSignature, CurrencyUnit, Id, MeltQuoteState, MintQuoteState, Proof, Proofs, PublicKey, - State, + BlindSignature, CurrencyUnit, Id, MeltQuoteState, Proof, Proofs, PublicKey, State, }; +use crate::payment::PaymentIdentifier; #[cfg(feature = "auth")] mod auth; @@ -67,13 +67,20 @@ pub trait QuotesTransaction<'a> { async fn get_mint_quote(&mut self, quote_id: &Uuid) -> Result, Self::Err>; /// Add [`MintMintQuote`] - async fn add_or_replace_mint_quote(&mut self, quote: MintMintQuote) -> Result<(), Self::Err>; - /// Update state of [`MintMintQuote`] - async fn update_mint_quote_state( + async fn add_mint_quote(&mut self, quote: MintMintQuote) -> Result<(), Self::Err>; + /// Increment amount paid [`MintMintQuote`] + async fn increment_mint_quote_amount_paid( &mut self, quote_id: &Uuid, - state: MintQuoteState, - ) -> Result; + amount_paid: Amount, + payment_id: String, + ) -> Result; + /// Increment amount paid [`MintMintQuote`] + async fn increment_mint_quote_amount_issued( + &mut self, + quote_id: &Uuid, + amount_issued: Amount, + ) -> Result; /// Remove [`MintMintQuote`] async fn remove_mint_quote(&mut self, quote_id: &Uuid) -> Result<(), Self::Err>; /// Get [`mint::MeltQuote`] and lock it for update in this transaction @@ -88,7 +95,7 @@ pub trait QuotesTransaction<'a> { async fn update_melt_quote_request_lookup_id( &mut self, quote_id: &Uuid, - new_request_lookup_id: &str, + new_request_lookup_id: &PaymentIdentifier, ) -> Result<(), Self::Err>; /// Update [`mint::MeltQuote`] state @@ -98,6 +105,7 @@ pub trait QuotesTransaction<'a> { &mut self, quote_id: &Uuid, new_state: MeltQuoteState, + payment_proof: Option, ) -> Result<(MeltQuoteState, mint::MeltQuote), Self::Err>; /// Remove [`mint::MeltQuote`] async fn remove_melt_quote(&mut self, quote_id: &Uuid) -> Result<(), Self::Err>; @@ -106,6 +114,12 @@ pub trait QuotesTransaction<'a> { &mut self, request: &str, ) -> Result, Self::Err>; + + /// Get all [`MintMintQuote`]s + async fn get_mint_quote_by_request_lookup_id( + &mut self, + request_lookup_id: &PaymentIdentifier, + ) -> Result, Self::Err>; } /// Mint Quote Database trait @@ -125,15 +139,10 @@ pub trait QuotesDatabase { /// Get all [`MintMintQuote`]s async fn get_mint_quote_by_request_lookup_id( &self, - request_lookup_id: &str, + request_lookup_id: &PaymentIdentifier, ) -> Result, Self::Err>; /// Get Mint Quotes async fn get_mint_quotes(&self) -> Result, Self::Err>; - /// Get Mint Quotes with state - async fn get_mint_quotes_with_state( - &self, - state: MintQuoteState, - ) -> Result, Self::Err>; /// Get [`mint::MeltQuote`] async fn get_melt_quote(&self, quote_id: &Uuid) -> Result, Self::Err>; /// Get all [`mint::MeltQuote`]s diff --git a/crates/cdk-common/src/database/mod.rs b/crates/cdk-common/src/database/mod.rs index 8fad4132d..195e210ba 100644 --- a/crates/cdk-common/src/database/mod.rs +++ b/crates/cdk-common/src/database/mod.rs @@ -29,6 +29,9 @@ pub enum Error { /// Duplicate entry #[error("Duplicate entry")] Duplicate, + /// Amount overflow + #[error("Amount overflow")] + AmountOverflow, /// DHKE error #[error(transparent)] diff --git a/crates/cdk-common/src/error.rs b/crates/cdk-common/src/error.rs index d0264401c..842751188 100644 --- a/crates/cdk-common/src/error.rs +++ b/crates/cdk-common/src/error.rs @@ -91,6 +91,24 @@ pub enum Error { /// Multi-Part Payment not supported for unit and method #[error("Amountless invoices are not supported for unit `{0}` and method `{1}`")] AmountlessInvoiceNotSupported(CurrencyUnit, PaymentMethod), + /// Duplicate Payment id + #[error("Payment id seen for mint")] + DuplicatePaymentId, + /// Pubkey required + #[error("Pubkey required")] + PubkeyRequired, + /// Invalid payment method + #[error("Invalid payment method")] + InvalidPaymentMethod, + /// Amount undefined + #[error("Amount undefined")] + AmountUndefined, + /// Unsupported payment method + #[error("Payment method unsupported")] + UnsupportedPaymentMethod, + /// Could not parse bolt12 + #[error("Could not parse bolt12")] + Bolt12parse, /// Internal Error - Send error #[error("Internal send error: {0}")] diff --git a/crates/cdk-common/src/lib.rs b/crates/cdk-common/src/lib.rs index 3dec0a8dc..fcd7bfc95 100644 --- a/crates/cdk-common/src/lib.rs +++ b/crates/cdk-common/src/lib.rs @@ -12,6 +12,8 @@ pub mod common; pub mod database; pub mod error; #[cfg(feature = "mint")] +pub mod melt; +#[cfg(feature = "mint")] pub mod mint; #[cfg(feature = "mint")] pub mod payment; diff --git a/crates/cdk-common/src/melt.rs b/crates/cdk-common/src/melt.rs new file mode 100644 index 000000000..d744b3882 --- /dev/null +++ b/crates/cdk-common/src/melt.rs @@ -0,0 +1,26 @@ +//! Melt types +use cashu::{MeltQuoteBolt11Request, MeltQuoteBolt12Request}; + +/// Melt quote request enum for different types of quotes +/// +/// This enum represents the different types of melt quote requests +/// that can be made, either BOLT11 or BOLT12. +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum MeltQuoteRequest { + /// Lightning Network BOLT11 invoice request + Bolt11(MeltQuoteBolt11Request), + /// Lightning Network BOLT12 offer request + Bolt12(MeltQuoteBolt12Request), +} + +impl From for MeltQuoteRequest { + fn from(request: MeltQuoteBolt11Request) -> Self { + MeltQuoteRequest::Bolt11(request) + } +} + +impl From for MeltQuoteRequest { + fn from(request: MeltQuoteBolt12Request) -> Self { + MeltQuoteRequest::Bolt12(request) + } +} diff --git a/crates/cdk-common/src/mint.rs b/crates/cdk-common/src/mint.rs index 089c36549..49b94d5bc 100644 --- a/crates/cdk-common/src/mint.rs +++ b/crates/cdk-common/src/mint.rs @@ -2,11 +2,17 @@ use bitcoin::bip32::DerivationPath; use cashu::util::unix_time; -use cashu::{MeltQuoteBolt11Response, MintQuoteBolt11Response}; +use cashu::{ + Bolt11Invoice, MeltOptions, MeltQuoteBolt11Response, MintQuoteBolt11Response, + MintQuoteBolt12Response, PaymentMethod, +}; +use lightning::offers::offer::Offer; use serde::{Deserialize, Serialize}; +use tracing::instrument; use uuid::Uuid; use crate::nuts::{MeltQuoteState, MintQuoteState}; +use crate::payment::PaymentIdentifier; use crate::{Amount, CurrencyUnit, Id, KeySetInfo, PublicKey}; /// Mint Quote Info @@ -15,56 +21,211 @@ pub struct MintQuote { /// Quote id pub id: Uuid, /// Amount of quote - pub amount: Amount, + pub amount: Option, /// Unit of quote pub unit: CurrencyUnit, /// Quote payment request e.g. bolt11 pub request: String, - /// Quote state - pub state: MintQuoteState, /// Expiration time of quote pub expiry: u64, /// Value used by ln backend to look up state of request - pub request_lookup_id: String, + pub request_lookup_id: PaymentIdentifier, /// Pubkey pub pubkey: Option, /// Unix time quote was created #[serde(default)] pub created_time: u64, - /// Unix time quote was paid - pub paid_time: Option, - /// Unix time quote was issued - pub issued_time: Option, + /// Amount paid + #[serde(default)] + amount_paid: Amount, + /// Amount issued + #[serde(default)] + amount_issued: Amount, + /// Payment of payment(s) that filled quote + #[serde(default)] + pub payments: Vec, + /// Payment Method + #[serde(default)] + pub payment_method: PaymentMethod, + /// Payment of payment(s) that filled quote + #[serde(default)] + pub issuance: Vec, } impl MintQuote { /// Create new [`MintQuote`] + #[allow(clippy::too_many_arguments)] pub fn new( + id: Option, request: String, unit: CurrencyUnit, - amount: Amount, + amount: Option, expiry: u64, - request_lookup_id: String, + request_lookup_id: PaymentIdentifier, pubkey: Option, + amount_paid: Amount, + amount_issued: Amount, + payment_method: PaymentMethod, + created_time: u64, + payments: Vec, + issuance: Vec, ) -> Self { - let id = Uuid::new_v4(); + let id = id.unwrap_or(Uuid::new_v4()); Self { id, amount, unit, request, - state: MintQuoteState::Unpaid, expiry, request_lookup_id, pubkey, - created_time: unix_time(), - paid_time: None, - issued_time: None, + created_time, + amount_paid, + amount_issued, + payment_method, + payments, + issuance, + } + } + + /// Increment the amount paid on the mint quote by a given amount + #[instrument(skip(self))] + pub fn increment_amount_paid( + &mut self, + additional_amount: Amount, + ) -> Result { + self.amount_paid = self + .amount_paid + .checked_add(additional_amount) + .ok_or(crate::Error::AmountOverflow)?; + Ok(self.amount_paid) + } + + /// Amount paid + #[instrument(skip(self))] + pub fn amount_paid(&self) -> Amount { + self.amount_paid + } + + /// Increment the amount issued on the mint quote by a given amount + #[instrument(skip(self))] + pub fn increment_amount_issued( + &mut self, + additional_amount: Amount, + ) -> Result { + self.amount_issued = self + .amount_issued + .checked_add(additional_amount) + .ok_or(crate::Error::AmountOverflow)?; + Ok(self.amount_issued) + } + + /// Amount issued + #[instrument(skip(self))] + pub fn amount_issued(&self) -> Amount { + self.amount_issued + } + + /// Get state of mint quote + #[instrument(skip(self))] + pub fn state(&self) -> MintQuoteState { + self.compute_quote_state() + } + + /// Existing payment ids of a mint quote + pub fn payment_ids(&self) -> Vec<&String> { + self.payments.iter().map(|a| &a.payment_id).collect() + } + + /// Add a payment ID to the list of payment IDs + /// + /// Returns an error if the payment ID is already in the list + #[instrument(skip(self))] + pub fn add_payment( + &mut self, + amount: Amount, + payment_id: String, + time: u64, + ) -> Result<(), crate::Error> { + let payment_ids = self.payment_ids(); + if payment_ids.contains(&&payment_id) { + return Err(crate::Error::DuplicatePaymentId); + } + + let payment = IncomingPayment::new(amount, payment_id, time); + + self.payments.push(payment); + Ok(()) + } + + /// Compute quote state + #[instrument(skip(self))] + fn compute_quote_state(&self) -> MintQuoteState { + if self.amount_paid == Amount::ZERO && self.amount_issued == Amount::ZERO { + return MintQuoteState::Unpaid; + } + + match self.amount_paid.cmp(&self.amount_issued) { + std::cmp::Ordering::Less => { + // self.amount_paid is less than other (amount issued) + // Handle case where paid amount is insufficient + tracing::error!("We should not have issued more then has been paid"); + MintQuoteState::Issued + } + std::cmp::Ordering::Equal => { + // We do this extra check for backwards compatibility for quotes where amount paid/issed was not tracked + // self.amount_paid equals other (amount issued) + // Handle case where paid amount exactly matches + MintQuoteState::Issued + } + std::cmp::Ordering::Greater => { + // self.amount_paid is greater than other (amount issued) + // Handle case where paid amount exceeds required amount + MintQuoteState::Paid + } + } + } +} + +/// Mint Payments +#[derive(Debug, Clone, Hash, PartialEq, Eq, Serialize, Deserialize)] +pub struct IncomingPayment { + /// Amount + pub amount: Amount, + /// Pyament unix time + pub time: u64, + /// Payment id + pub payment_id: String, +} + +impl IncomingPayment { + /// New [`IncomingPayment`] + pub fn new(amount: Amount, payment_id: String, time: u64) -> Self { + Self { + payment_id, + time, + amount, } } } +/// Informattion about issued quote +#[derive(Debug, Clone, Hash, PartialEq, Eq, Serialize, Deserialize)] +pub struct Issuance { + /// Amount + pub amount: Amount, + /// Time + pub time: u64, +} + +impl Issuance { + /// Create new [`Issuance`] + pub fn new(amount: Amount, time: u64) -> Self { + Self { amount, time } + } +} + /// Melt Quote Info #[derive(Debug, Clone, Hash, PartialEq, Eq, Serialize, Deserialize)] pub struct MeltQuote { @@ -75,7 +236,7 @@ pub struct MeltQuote { /// Quote amount pub amount: Amount, /// Quote Payment request e.g. bolt11 - pub request: String, + pub request: MeltPaymentRequest, /// Quote fee reserve pub fee_reserve: Amount, /// Quote state @@ -85,28 +246,33 @@ pub struct MeltQuote { /// Payment preimage pub payment_preimage: Option, /// Value used by ln backend to look up state of request - pub request_lookup_id: String, - /// Msat to pay + pub request_lookup_id: PaymentIdentifier, + /// Payment options /// - /// Used for an amountless invoice - pub msat_to_pay: Option, + /// Used for amountless invoices and MPP payments + pub options: Option, /// Unix time quote was created #[serde(default)] pub created_time: u64, /// Unix time quote was paid pub paid_time: Option, + /// Payment method + #[serde(default)] + pub payment_method: PaymentMethod, } impl MeltQuote { /// Create new [`MeltQuote`] + #[allow(clippy::too_many_arguments)] pub fn new( - request: String, + request: MeltPaymentRequest, unit: CurrencyUnit, amount: Amount, fee_reserve: Amount, expiry: u64, - request_lookup_id: String, - msat_to_pay: Option, + request_lookup_id: PaymentIdentifier, + options: Option, + payment_method: PaymentMethod, ) -> Self { let id = Uuid::new_v4(); @@ -120,9 +286,10 @@ impl MeltQuote { expiry, payment_preimage: None, request_lookup_id, - msat_to_pay, + options, created_time: unix_time(), paid_time: None, + payment_method, } } } @@ -173,16 +340,51 @@ impl From for MintQuoteBolt11Response { fn from(mint_quote: crate::mint::MintQuote) -> MintQuoteBolt11Response { MintQuoteBolt11Response { quote: mint_quote.id, + state: mint_quote.state(), request: mint_quote.request, - state: mint_quote.state, expiry: Some(mint_quote.expiry), pubkey: mint_quote.pubkey, - amount: Some(mint_quote.amount), + amount: mint_quote.amount, unit: Some(mint_quote.unit.clone()), } } } +impl From for MintQuoteBolt11Response { + fn from(quote: MintQuote) -> Self { + let quote: MintQuoteBolt11Response = quote.into(); + + quote.into() + } +} + +impl TryFrom for MintQuoteBolt12Response { + type Error = crate::Error; + + fn try_from(mint_quote: crate::mint::MintQuote) -> Result { + Ok(MintQuoteBolt12Response { + quote: mint_quote.id, + request: mint_quote.request, + expiry: Some(mint_quote.expiry), + amount_paid: mint_quote.amount_paid, + amount_issued: mint_quote.amount_issued, + pubkey: mint_quote.pubkey.ok_or(crate::Error::PubkeyRequired)?, + amount: mint_quote.amount, + unit: mint_quote.unit, + }) + } +} + +impl TryFrom for MintQuoteBolt12Response { + type Error = crate::Error; + + fn try_from(quote: MintQuote) -> Result { + let quote: MintQuoteBolt12Response = quote.try_into()?; + + Ok(quote.into()) + } +} + impl From<&MeltQuote> for MeltQuoteBolt11Response { fn from(melt_quote: &MeltQuote) -> MeltQuoteBolt11Response { MeltQuoteBolt11Response { @@ -212,8 +414,61 @@ impl From for MeltQuoteBolt11Response { expiry: melt_quote.expiry, payment_preimage: melt_quote.payment_preimage, change: None, - request: Some(melt_quote.request.clone()), + request: Some(melt_quote.request.to_string()), unit: Some(melt_quote.unit.clone()), } } } + +/// Payment request +#[derive(Debug, Clone, Hash, PartialEq, Eq, Serialize, Deserialize)] +pub enum MeltPaymentRequest { + /// Bolt11 Payment + Bolt11 { + /// Bolt11 invoice + bolt11: Bolt11Invoice, + }, + /// Bolt12 Payment + Bolt12 { + /// Offer + #[serde(with = "offer_serde")] + offer: Box, + /// Invoice + invoice: Option>, + }, +} + +impl std::fmt::Display for MeltPaymentRequest { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + MeltPaymentRequest::Bolt11 { bolt11 } => write!(f, "{bolt11}"), + MeltPaymentRequest::Bolt12 { offer, invoice: _ } => write!(f, "{offer}"), + } + } +} + +mod offer_serde { + use std::str::FromStr; + + use serde::{self, Deserialize, Deserializer, Serializer}; + + use super::Offer; + + pub fn serialize(offer: &Offer, serializer: S) -> Result + where + S: Serializer, + { + let s = offer.to_string(); + serializer.serialize_str(&s) + } + + pub fn deserialize<'de, D>(deserializer: D) -> Result, D::Error> + where + D: Deserializer<'de>, + { + let s = String::deserialize(deserializer)?; + Ok(Box::new(Offer::from_str(&s).map_err(|_| { + serde::de::Error::custom("Invalid Bolt12 Offer") + })?)) + } +} diff --git a/crates/cdk-common/src/payment.rs b/crates/cdk-common/src/payment.rs index fabbabaca..923c0f059 100644 --- a/crates/cdk-common/src/payment.rs +++ b/crates/cdk-common/src/payment.rs @@ -1,17 +1,21 @@ //! CDK Mint Lightning +use std::convert::Infallible; use std::pin::Pin; use async_trait::async_trait; -use cashu::MeltOptions; +use cashu::util::hex; +use cashu::{Bolt11Invoice, MeltOptions}; use futures::Stream; +use lightning::offers::offer::Offer; use lightning_invoice::ParseOrSemanticError; use serde::{Deserialize, Serialize}; use serde_json::Value; use thiserror::Error; -use crate::nuts::{CurrencyUnit, MeltQuoteState, MintQuoteState}; -use crate::{mint, Amount}; +use crate::mint::MeltPaymentRequest; +use crate::nuts::{CurrencyUnit, MeltQuoteState}; +use crate::Amount; /// CDK Lightning Error #[derive(Debug, Error)] @@ -31,6 +35,9 @@ pub enum Error { /// Payment state is unknown #[error("Payment state is unknown")] UnknownPaymentState, + /// Amount mismatch + #[error("Amount is not what is expected")] + AmountMismatch, /// Lightning Error #[error(transparent)] Lightning(Box), @@ -55,11 +62,186 @@ pub enum Error { /// NUT23 Error #[error(transparent)] NUT23(#[from] crate::nuts::nut23::Error), + /// Hex error + #[error("Hex error")] + Hex(#[from] hex::Error), + /// Invalid hash + #[error("Invalid hash")] + InvalidHash, /// Custom #[error("`{0}`")] Custom(String), } +impl From for Error { + fn from(_: Infallible) -> Self { + unreachable!("Infallible cannot be constructed") + } +} + +/// Payment identifier types +#[derive(Debug, Clone, Hash, PartialEq, Eq, Deserialize, Serialize)] +#[serde(tag = "type", content = "value")] +pub enum PaymentIdentifier { + /// Label identifier + Label(String), + /// Offer ID identifier + OfferId(String), + /// Payment hash identifier + PaymentHash([u8; 32]), + /// Bolt12 payment hash + Bolt12PaymentHash([u8; 32]), + /// Custom Payment ID + CustomId(String), +} + +impl PaymentIdentifier { + /// Create new [`PaymentIdentifier`] + pub fn new(kind: &str, identifier: &str) -> Result { + match kind.to_lowercase().as_str() { + "label" => Ok(Self::Label(identifier.to_string())), + "offer_id" => Ok(Self::OfferId(identifier.to_string())), + "payment_hash" => Ok(Self::PaymentHash( + hex::decode(identifier)? + .try_into() + .map_err(|_| Error::InvalidHash)?, + )), + "bolt12_payment_hash" => Ok(Self::Bolt12PaymentHash( + hex::decode(identifier)? + .try_into() + .map_err(|_| Error::InvalidHash)?, + )), + "custom" => Ok(Self::CustomId(identifier.to_string())), + _ => Err(Error::UnsupportedPaymentOption), + } + } + + /// Payment id kind + pub fn kind(&self) -> String { + match self { + Self::Label(_) => "label".to_string(), + Self::OfferId(_) => "offer_id".to_string(), + Self::PaymentHash(_) => "payment_hash".to_string(), + Self::Bolt12PaymentHash(_) => "bolt12_payment_hash".to_string(), + Self::CustomId(_) => "custom".to_string(), + } + } +} + +impl std::fmt::Display for PaymentIdentifier { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + Self::Label(l) => write!(f, "{l}"), + Self::OfferId(o) => write!(f, "{o}"), + Self::PaymentHash(h) => write!(f, "{}", hex::encode(h)), + Self::Bolt12PaymentHash(h) => write!(f, "{}", hex::encode(h)), + Self::CustomId(c) => write!(f, "{c}"), + } + } +} + +/// Options for creating a BOLT11 incoming payment request +#[derive(Debug, Clone, Default, PartialEq, Eq, Hash)] +pub struct Bolt11IncomingPaymentOptions { + /// Optional description for the payment request + pub description: Option, + /// Amount for the payment request in sats + pub amount: Amount, + /// Optional expiry time as Unix timestamp in seconds + pub unix_expiry: Option, +} + +/// Options for creating a BOLT12 incoming payment request +#[derive(Debug, Clone, Default, PartialEq, Eq, Hash)] +pub struct Bolt12IncomingPaymentOptions { + /// Optional description for the payment request + pub description: Option, + /// Optional amount for the payment request in sats + pub amount: Option, + /// Optional expiry time as Unix timestamp in seconds + pub unix_expiry: Option, +} + +/// Options for creating an incoming payment request +#[derive(Debug, Clone, PartialEq, Eq, Hash)] +pub enum IncomingPaymentOptions { + /// BOLT11 payment request options + Bolt11(Bolt11IncomingPaymentOptions), + /// BOLT12 payment request options + Bolt12(Box), +} + +/// Options for BOLT11 outgoing payments +#[derive(Debug, Clone, PartialEq, Eq, Hash)] +pub struct Bolt11OutgoingPaymentOptions { + /// Bolt11 + pub bolt11: Bolt11Invoice, + /// Maximum fee amount allowed for the payment + pub max_fee_amount: Option, + /// Optional timeout in seconds + pub timeout_secs: Option, + /// Melt options + pub melt_options: Option, +} + +/// Options for BOLT12 outgoing payments +#[derive(Debug, Clone, PartialEq, Eq, Hash)] +pub struct Bolt12OutgoingPaymentOptions { + /// Offer + pub offer: Offer, + /// Maximum fee amount allowed for the payment + pub max_fee_amount: Option, + /// Optional timeout in seconds + pub timeout_secs: Option, + /// Bolt12 Invoice + pub invoice: Option>, + /// Melt options + pub melt_options: Option, +} + +/// Options for creating an outgoing payment +#[derive(Debug, Clone, PartialEq, Eq, Hash)] +pub enum OutgoingPaymentOptions { + /// BOLT11 payment options + Bolt11(Box), + /// BOLT12 payment options + Bolt12(Box), +} + +impl TryFrom for OutgoingPaymentOptions { + type Error = Error; + + fn try_from(melt_quote: crate::mint::MeltQuote) -> Result { + match melt_quote.request { + MeltPaymentRequest::Bolt11 { bolt11 } => Ok(OutgoingPaymentOptions::Bolt11(Box::new( + Bolt11OutgoingPaymentOptions { + max_fee_amount: Some(melt_quote.fee_reserve), + timeout_secs: None, + bolt11, + melt_options: melt_quote.options, + }, + ))), + MeltPaymentRequest::Bolt12 { offer, invoice } => { + let melt_options = match melt_quote.options { + None => None, + Some(MeltOptions::Mpp { mpp: _ }) => return Err(Error::UnsupportedUnit), + Some(options) => Some(options), + }; + + Ok(OutgoingPaymentOptions::Bolt12(Box::new( + Bolt12OutgoingPaymentOptions { + max_fee_amount: Some(melt_quote.fee_reserve), + timeout_secs: None, + offer: *offer, + invoice, + melt_options, + }, + ))) + } + } + } +} + /// Mint payment trait #[async_trait] pub trait MintPayment { @@ -72,34 +254,30 @@ pub trait MintPayment { /// Create a new invoice async fn create_incoming_payment_request( &self, - amount: Amount, unit: &CurrencyUnit, - description: String, - unix_expiry: Option, + options: IncomingPaymentOptions, ) -> Result; /// Get payment quote /// Used to get fee and amount required for a payment request async fn get_payment_quote( &self, - request: &str, unit: &CurrencyUnit, - options: Option, + options: OutgoingPaymentOptions, ) -> Result; /// Pay request async fn make_payment( &self, - melt_quote: mint::MeltQuote, - partial_amount: Option, - max_fee_amount: Option, + unit: &CurrencyUnit, + options: OutgoingPaymentOptions, ) -> Result; /// Listen for invoices to be paid to the mint /// Returns a stream of request_lookup_id once invoices are paid async fn wait_any_incoming_payment( &self, - ) -> Result + Send>>, Self::Err>; + ) -> Result + Send>>, Self::Err>; /// Is wait invoice active fn is_wait_invoice_active(&self) -> bool; @@ -110,21 +288,36 @@ pub trait MintPayment { /// Check the status of an incoming payment async fn check_incoming_payment_status( &self, - request_lookup_id: &str, - ) -> Result; + payment_identifier: &PaymentIdentifier, + ) -> Result, Self::Err>; /// Check the status of an outgoing payment async fn check_outgoing_payment( &self, - request_lookup_id: &str, + payment_identifier: &PaymentIdentifier, ) -> Result; } +/// Wait any invoice response +#[derive(Debug, Clone, Hash, Serialize, Deserialize)] +pub struct WaitPaymentResponse { + /// Request look up id + /// Id that relates the quote and payment request + pub payment_identifier: PaymentIdentifier, + /// Payment amount + pub payment_amount: Amount, + /// Unit + pub unit: CurrencyUnit, + /// Unique id of payment + // Payment hash + pub payment_id: String, +} + /// Create incoming payment response #[derive(Debug, Clone, Hash, PartialEq, Eq, Serialize, Deserialize)] pub struct CreateIncomingPaymentResponse { /// Id that is used to look up the payment from the ln backend - pub request_lookup_id: String, + pub request_lookup_id: PaymentIdentifier, /// Payment request pub request: String, /// Unix Expiry of Invoice @@ -135,7 +328,7 @@ pub struct CreateIncomingPaymentResponse { #[derive(Debug, Clone, Hash, PartialEq, Eq, Serialize, Deserialize)] pub struct MakePaymentResponse { /// Payment hash - pub payment_lookup_id: String, + pub payment_lookup_id: PaymentIdentifier, /// Payment proof pub payment_proof: Option, /// Status @@ -150,7 +343,7 @@ pub struct MakePaymentResponse { #[derive(Debug, Clone, Hash, PartialEq, Eq, Serialize, Deserialize)] pub struct PaymentQuoteResponse { /// Request look up id - pub request_lookup_id: String, + pub request_lookup_id: PaymentIdentifier, /// Amount pub amount: Amount, /// Fee required for melt @@ -159,6 +352,18 @@ pub struct PaymentQuoteResponse { pub unit: CurrencyUnit, /// Status pub state: MeltQuoteState, + /// Payment Quote Options + pub options: Option, +} + +/// Payment quote options +#[derive(Debug, Clone, Hash, PartialEq, Eq, Serialize, Deserialize)] +pub enum PaymentQuoteOptions { + /// Bolt12 payment options + Bolt12 { + /// Bolt12 invoice + invoice: Option>, + }, } /// Ln backend settings @@ -172,6 +377,8 @@ pub struct Bolt11Settings { pub invoice_description: bool, /// Paying amountless invoices supported pub amountless: bool, + /// Bolt12 supported + pub bolt12: bool, } impl TryFrom for Value { diff --git a/crates/cdk-common/src/subscription.rs b/crates/cdk-common/src/subscription.rs index ba14de1b0..50c6cbe7f 100644 --- a/crates/cdk-common/src/subscription.rs +++ b/crates/cdk-common/src/subscription.rs @@ -81,6 +81,9 @@ impl Indexable for NotificationPayload { NotificationPayload::MintQuoteBolt11Response(mint_quote) => { vec![Index::from(Notification::MintQuoteBolt11(mint_quote.quote))] } + NotificationPayload::MintQuoteBolt12Response(mint_quote) => { + vec![Index::from(Notification::MintQuoteBolt12(mint_quote.quote))] + } } } } diff --git a/crates/cdk-common/src/wallet.rs b/crates/cdk-common/src/wallet.rs index 5634d6de2..d9aca538b 100644 --- a/crates/cdk-common/src/wallet.rs +++ b/crates/cdk-common/src/wallet.rs @@ -6,7 +6,7 @@ use std::str::FromStr; use bitcoin::hashes::{sha256, Hash, HashEngine}; use cashu::util::hex; -use cashu::{nut00, Proofs, PublicKey}; +use cashu::{nut00, PaymentMethod, Proofs, PublicKey}; use serde::{Deserialize, Serialize}; use crate::mint_url::MintUrl; @@ -42,8 +42,11 @@ pub struct MintQuote { pub id: String, /// Mint Url pub mint_url: MintUrl, + /// Payment method + #[serde(default)] + pub payment_method: PaymentMethod, /// Amount of quote - pub amount: Amount, + pub amount: Option, /// Unit of quote pub unit: CurrencyUnit, /// Quote payment request e.g. bolt11 @@ -54,6 +57,12 @@ pub struct MintQuote { pub expiry: u64, /// Secretkey for signing mint quotes [NUT-20] pub secret_key: Option, + /// Amount minted + #[serde(default)] + pub amount_issued: Amount, + /// Amount paid to the mint for the quote + #[serde(default)] + pub amount_paid: Amount, } /// Melt Quote Info @@ -77,6 +86,62 @@ pub struct MeltQuote { pub payment_preimage: Option, } +impl MintQuote { + /// Create a new MintQuote + #[allow(clippy::too_many_arguments)] + pub fn new( + id: String, + mint_url: MintUrl, + payment_method: PaymentMethod, + amount: Option, + unit: CurrencyUnit, + request: String, + expiry: u64, + secret_key: Option, + ) -> Self { + Self { + id, + mint_url, + payment_method, + amount, + unit, + request, + state: MintQuoteState::Unpaid, + expiry, + secret_key, + amount_issued: Amount::ZERO, + amount_paid: Amount::ZERO, + } + } + + /// Calculate the total amount including any fees + pub fn total_amount(&self) -> Amount { + self.amount_paid + } + + /// Check if the quote has expired + pub fn is_expired(&self, current_time: u64) -> bool { + current_time > self.expiry + } + + /// Amount that can be minted + pub fn amount_mintable(&self) -> Amount { + if self.amount_issued > self.amount_paid { + return Amount::ZERO; + } + + let difference = self.amount_paid - self.amount_issued; + + if difference == Amount::ZERO && self.state != MintQuoteState::Issued { + if let Some(amount) = self.amount { + return amount; + } + } + + difference + } +} + /// Send Kind #[derive(Debug, Clone, Copy, Hash, PartialEq, Eq, Default, Serialize, Deserialize)] pub enum SendKind { diff --git a/crates/cdk-common/src/ws.rs b/crates/cdk-common/src/ws.rs index 91ca5d228..1f2e5246e 100644 --- a/crates/cdk-common/src/ws.rs +++ b/crates/cdk-common/src/ws.rs @@ -60,6 +60,9 @@ pub fn notification_uuid_to_notification_string( NotificationPayload::MintQuoteBolt11Response(quote) => { NotificationPayload::MintQuoteBolt11Response(quote.to_string_id()) } + NotificationPayload::MintQuoteBolt12Response(quote) => { + NotificationPayload::MintQuoteBolt12Response(quote.to_string_id()) + } }, } } diff --git a/crates/cdk-fake-wallet/Cargo.toml b/crates/cdk-fake-wallet/Cargo.toml index 5f89a6770..0b98f5039 100644 --- a/crates/cdk-fake-wallet/Cargo.toml +++ b/crates/cdk-fake-wallet/Cargo.toml @@ -13,7 +13,7 @@ readme = "README.md" [dependencies] async-trait.workspace = true bitcoin.workspace = true -cdk = { workspace = true, features = ["mint"] } +cdk-common = { workspace = true, features = ["mint"] } futures.workspace = true tokio.workspace = true tokio-util.workspace = true @@ -22,5 +22,6 @@ thiserror.workspace = true serde.workspace = true serde_json.workspace = true lightning-invoice.workspace = true +lightning.workspace = true tokio-stream.workspace = true reqwest.workspace = true diff --git a/crates/cdk-fake-wallet/src/error.rs b/crates/cdk-fake-wallet/src/error.rs index 69ee03219..f52dbc6e5 100644 --- a/crates/cdk-fake-wallet/src/error.rs +++ b/crates/cdk-fake-wallet/src/error.rs @@ -16,7 +16,7 @@ pub enum Error { NoReceiver, } -impl From for cdk::cdk_payment::Error { +impl From for cdk_common::payment::Error { fn from(e: Error) -> Self { Self::Lightning(Box::new(e)) } diff --git a/crates/cdk-fake-wallet/src/lib.rs b/crates/cdk-fake-wallet/src/lib.rs index fa9ef562f..38d241b73 100644 --- a/crates/cdk-fake-wallet/src/lib.rs +++ b/crates/cdk-fake-wallet/src/lib.rs @@ -9,7 +9,6 @@ use std::cmp::max; use std::collections::{HashMap, HashSet}; use std::pin::Pin; -use std::str::FromStr; use std::sync::atomic::{AtomicBool, Ordering}; use std::sync::Arc; @@ -17,22 +16,23 @@ use async_trait::async_trait; use bitcoin::hashes::{sha256, Hash}; use bitcoin::secp256k1::rand::{thread_rng, Rng}; use bitcoin::secp256k1::{Secp256k1, SecretKey}; -use cdk::amount::{to_unit, Amount}; -use cdk::cdk_payment::{ - self, Bolt11Settings, CreateIncomingPaymentResponse, MakePaymentResponse, MintPayment, - PaymentQuoteResponse, +use cdk_common::amount::{to_unit, Amount}; +use cdk_common::common::FeeReserve; +use cdk_common::ensure_cdk; +use cdk_common::nuts::{CurrencyUnit, MeltOptions, MeltQuoteState}; +use cdk_common::payment::{ + self, Bolt11Settings, CreateIncomingPaymentResponse, IncomingPaymentOptions, + MakePaymentResponse, MintPayment, OutgoingPaymentOptions, PaymentIdentifier, + PaymentQuoteResponse, WaitPaymentResponse, }; -use cdk::nuts::{CurrencyUnit, MeltOptions, MeltQuoteState, MintQuoteState}; -use cdk::types::FeeReserve; -use cdk::{ensure_cdk, mint}; use error::Error; use futures::stream::StreamExt; use futures::Stream; +use lightning::offers::offer::OfferBuilder; use lightning_invoice::{Bolt11Invoice, Currency, InvoiceBuilder, PaymentSecret}; -use reqwest::Client; use serde::{Deserialize, Serialize}; use serde_json::Value; -use tokio::sync::Mutex; +use tokio::sync::{Mutex, RwLock}; use tokio::time; use tokio_stream::wrappers::ReceiverStream; use tokio_util::sync::CancellationToken; @@ -44,13 +44,16 @@ pub mod error; #[derive(Clone)] pub struct FakeWallet { fee_reserve: FeeReserve, - sender: tokio::sync::mpsc::Sender, - receiver: Arc>>>, + #[allow(clippy::type_complexity)] + sender: tokio::sync::mpsc::Sender<(PaymentIdentifier, Amount)>, + #[allow(clippy::type_complexity)] + receiver: Arc>>>, payment_states: Arc>>, failed_payment_check: Arc>>, payment_delay: u64, wait_invoice_cancel_token: CancellationToken, wait_invoice_is_active: Arc, + incoming_payments: Arc>>>, } impl FakeWallet { @@ -72,6 +75,7 @@ impl FakeWallet { payment_delay, wait_invoice_cancel_token: CancellationToken::new(), wait_invoice_is_active: Arc::new(AtomicBool::new(false)), + incoming_payments: Arc::new(RwLock::new(HashMap::new())), } } } @@ -102,7 +106,7 @@ impl Default for FakeInvoiceDescription { #[async_trait] impl MintPayment for FakeWallet { - type Err = cdk_payment::Error; + type Err = payment::Error; #[instrument(skip_all)] async fn get_settings(&self) -> Result { @@ -111,6 +115,7 @@ impl MintPayment for FakeWallet { unit: CurrencyUnit::Msat, invoice_description: true, amountless: false, + bolt12: false, })?) } @@ -127,51 +132,86 @@ impl MintPayment for FakeWallet { #[instrument(skip_all)] async fn wait_any_incoming_payment( &self, - ) -> Result + Send>>, Self::Err> { + ) -> Result + Send>>, Self::Err> { tracing::info!("Starting stream for fake invoices"); - let receiver = self.receiver.lock().await.take().ok_or(Error::NoReceiver)?; + let receiver = self + .receiver + .lock() + .await + .take() + .ok_or(Error::NoReceiver) + .unwrap(); let receiver_stream = ReceiverStream::new(receiver); - Ok(Box::pin(receiver_stream.map(|label| label))) + Ok(Box::pin(receiver_stream.map( + |(request_lookup_id, payment_amount)| WaitPaymentResponse { + payment_identifier: request_lookup_id.clone(), + payment_amount, + unit: CurrencyUnit::Sat, + payment_id: request_lookup_id.to_string(), + }, + ))) } #[instrument(skip_all)] async fn get_payment_quote( &self, - request: &str, unit: &CurrencyUnit, - options: Option, + options: OutgoingPaymentOptions, ) -> Result { - let bolt11 = Bolt11Invoice::from_str(request)?; - - let amount_msat = match options { - Some(amount) => amount.amount_msat(), - None => bolt11 - .amount_milli_satoshis() - .ok_or(Error::UnknownInvoiceAmount)? - .into(), + let (amount_msat, request_lookup_id) = match options { + OutgoingPaymentOptions::Bolt11(bolt11_options) => { + // If we have specific amount options, use those + let amount_msat: u64 = if let Some(melt_options) = bolt11_options.melt_options { + let msats = match melt_options { + MeltOptions::Amountless { amountless } => { + let amount_msat = amountless.amount_msat; + + if let Some(invoice_amount) = + bolt11_options.bolt11.amount_milli_satoshis() + { + ensure_cdk!( + invoice_amount == u64::from(amount_msat), + Error::UnknownInvoiceAmount.into() + ); + } + amount_msat + } + MeltOptions::Mpp { mpp } => mpp.amount, + }; + + u64::from(msats) + } else { + // Fall back to invoice amount + bolt11_options + .bolt11 + .amount_milli_satoshis() + .ok_or(Error::UnknownInvoiceAmount)? + }; + let payment_id = + PaymentIdentifier::PaymentHash(*bolt11_options.bolt11.payment_hash().as_ref()); + (amount_msat, payment_id) + } + OutgoingPaymentOptions::Bolt12(bolt12_options) => { + let offer = bolt12_options.offer; + + let amount_msat: u64 = if let Some(amount) = bolt12_options.melt_options { + amount.amount_msat().into() + } else { + // Fall back to offer amount + let amount = offer.amount().ok_or(Error::UnknownInvoiceAmount)?; + match amount { + lightning::offers::offer::Amount::Bitcoin { amount_msats } => amount_msats, + _ => return Err(Error::UnknownInvoiceAmount.into()), + } + }; + ( + amount_msat, + PaymentIdentifier::OfferId(offer.id().to_string()), + ) + } }; - let amount = if unit != &CurrencyUnit::Sat && unit != &CurrencyUnit::Msat { - let client = Client::new(); - - let response: Value = client - .get("https://mempool.space/api/v1/prices") - .send() - .await - .map_err(|_| Error::UnknownInvoice)? - .json() - .await - .unwrap(); - - let price = response.get(unit.to_string().to_uppercase()).unwrap(); - - let bitcoin_amount = u64::from(amount_msat) as f64 / 100_000_000_000.0; - let total_price = price.as_f64().unwrap() * bitcoin_amount; - - Amount::from((total_price * 100.0).ceil() as u64) - } else { - to_unit(amount_msat, &CurrencyUnit::Msat, unit)? - }; + let amount = to_unit(amount_msat, &CurrencyUnit::Msat, unit)?; let relative_fee_reserve = (self.fee_reserve.percent_fee_reserve * u64::from(amount) as f32) as u64; @@ -181,96 +221,198 @@ impl MintPayment for FakeWallet { let fee = max(relative_fee_reserve, absolute_fee_reserve); Ok(PaymentQuoteResponse { - request_lookup_id: bolt11.payment_hash().to_string(), + request_lookup_id, amount, fee: fee.into(), - unit: unit.clone(), state: MeltQuoteState::Unpaid, + options: None, + unit: unit.clone(), }) } #[instrument(skip_all)] async fn make_payment( &self, - melt_quote: mint::MeltQuote, - _partial_msats: Option, - _max_fee_msats: Option, + unit: &CurrencyUnit, + options: OutgoingPaymentOptions, ) -> Result { - let bolt11 = Bolt11Invoice::from_str(&melt_quote.request)?; - - let payment_hash = bolt11.payment_hash().to_string(); - - let description = bolt11.description().to_string(); - - let status: Option = serde_json::from_str(&description).ok(); - - let mut payment_states = self.payment_states.lock().await; - let payment_status = status - .clone() - .map(|s| s.pay_invoice_state) - .unwrap_or(MeltQuoteState::Paid); - - let checkout_going_status = status - .clone() - .map(|s| s.check_payment_state) - .unwrap_or(MeltQuoteState::Paid); - - payment_states.insert(payment_hash.clone(), checkout_going_status); - - if let Some(description) = status { - if description.check_err { - let mut fail = self.failed_payment_check.lock().await; - fail.insert(payment_hash.clone()); + match options { + OutgoingPaymentOptions::Bolt11(bolt11_options) => { + let bolt11 = bolt11_options.bolt11; + let payment_hash = bolt11.payment_hash().to_string(); + + let description = bolt11.description().to_string(); + + let status: Option = + serde_json::from_str(&description).ok(); + + let mut payment_states = self.payment_states.lock().await; + let payment_status = status + .clone() + .map(|s| s.pay_invoice_state) + .unwrap_or(MeltQuoteState::Paid); + + let checkout_going_status = status + .clone() + .map(|s| s.check_payment_state) + .unwrap_or(MeltQuoteState::Paid); + + payment_states.insert(payment_hash.clone(), checkout_going_status); + + if let Some(description) = status { + if description.check_err { + let mut fail = self.failed_payment_check.lock().await; + fail.insert(payment_hash.clone()); + } + + ensure_cdk!(!description.pay_err, Error::UnknownInvoice.into()); + } + + let amount_msat: u64 = if let Some(melt_options) = bolt11_options.melt_options { + melt_options.amount_msat().into() + } else { + // Fall back to invoice amount + bolt11 + .amount_milli_satoshis() + .ok_or(Error::UnknownInvoiceAmount)? + }; + + let total_spent = to_unit(amount_msat, &CurrencyUnit::Msat, unit)?; + + Ok(MakePaymentResponse { + payment_proof: Some("".to_string()), + payment_lookup_id: PaymentIdentifier::PaymentHash( + *bolt11.payment_hash().as_ref(), + ), + status: payment_status, + total_spent: total_spent + 1.into(), + unit: unit.clone(), + }) + } + OutgoingPaymentOptions::Bolt12(bolt12_options) => { + let bolt12 = bolt12_options.offer; + let amount_msat: u64 = if let Some(amount) = bolt12_options.melt_options { + amount.amount_msat().into() + } else { + // Fall back to offer amount + let amount = bolt12.amount().ok_or(Error::UnknownInvoiceAmount)?; + match amount { + lightning::offers::offer::Amount::Bitcoin { amount_msats } => amount_msats, + _ => return Err(Error::UnknownInvoiceAmount.into()), + } + }; + + let total_spent = to_unit(amount_msat, &CurrencyUnit::Msat, unit)?; + + Ok(MakePaymentResponse { + payment_proof: Some("".to_string()), + payment_lookup_id: PaymentIdentifier::OfferId(bolt12.id().to_string()), + status: MeltQuoteState::Paid, + total_spent: total_spent + 1.into(), + unit: unit.clone(), + }) } - - ensure_cdk!(!description.pay_err, Error::UnknownInvoice.into()); } - - Ok(MakePaymentResponse { - payment_proof: Some("".to_string()), - payment_lookup_id: payment_hash, - status: payment_status, - total_spent: melt_quote.amount + 1.into(), - unit: melt_quote.unit, - }) } #[instrument(skip_all)] async fn create_incoming_payment_request( &self, - amount: Amount, - _unit: &CurrencyUnit, - description: String, - _unix_expiry: Option, + unit: &CurrencyUnit, + options: IncomingPaymentOptions, ) -> Result { - // Since this is fake we just use the amount no matter the unit to create an invoice - let amount_msat = amount; - - let invoice = create_fake_invoice(amount_msat.into(), description); + let (payment_hash, request, amount, expiry) = match options { + IncomingPaymentOptions::Bolt12(bolt12_options) => { + let description = bolt12_options.description.unwrap_or_default(); + let amount = bolt12_options.amount; + let expiry = bolt12_options.unix_expiry; + + let secret_key = SecretKey::new(&mut thread_rng()); + let secp_ctx = Secp256k1::new(); + + let offer_builder = OfferBuilder::new(secret_key.public_key(&secp_ctx)) + .description(description.clone()); + + let offer_builder = match amount { + Some(amount) => { + let amount_msat = to_unit(amount, unit, &CurrencyUnit::Msat)?; + offer_builder.amount_msats(amount_msat.into()) + } + None => offer_builder, + }; + + let offer = offer_builder.build().unwrap(); + + ( + PaymentIdentifier::OfferId(offer.id().to_string()), + offer.to_string(), + amount.unwrap_or(Amount::ZERO), + expiry, + ) + } + IncomingPaymentOptions::Bolt11(bolt11_options) => { + let description = bolt11_options.description.unwrap_or_default(); + let amount = bolt11_options.amount; + let expiry = bolt11_options.unix_expiry; + + // Since this is fake we just use the amount no matter the unit to create an invoice + let invoice = create_fake_invoice(amount.into(), description.clone()); + let payment_hash = invoice.payment_hash(); + + ( + PaymentIdentifier::PaymentHash(*payment_hash.as_ref()), + invoice.to_string(), + amount, + expiry, + ) + } + }; let sender = self.sender.clone(); + let duration = time::Duration::from_secs(self.payment_delay); - let payment_hash = invoice.payment_hash(); + let final_amount = if amount == Amount::ZERO { + let mut rng = thread_rng(); + // Generate a random number between 1 and 1000 (inclusive) + let random_number: u64 = rng.gen_range(1..=1000); + random_number.into() + } else { + amount + }; - let payment_hash_clone = payment_hash.to_string(); + let payment_hash_clone = payment_hash.clone(); - let duration = time::Duration::from_secs(self.payment_delay); + let incoming_payment = self.incoming_payments.clone(); tokio::spawn(async move { // Wait for the random delay to elapse time::sleep(duration).await; + let response = WaitPaymentResponse { + payment_identifier: payment_hash_clone.clone(), + payment_amount: final_amount, + unit: CurrencyUnit::Sat, + payment_id: payment_hash_clone.to_string(), + }; + let mut incoming = incoming_payment.write().await; + incoming + .entry(payment_hash_clone.clone()) + .or_insert_with(Vec::new) + .push(response.clone()); + // Send the message after waiting for the specified duration - if sender.send(payment_hash_clone.clone()).await.is_err() { - tracing::error!("Failed to send label: {}", payment_hash_clone); + if sender + .send((payment_hash_clone.clone(), final_amount)) + .await + .is_err() + { + tracing::error!("Failed to send label: {:?}", payment_hash_clone); } }); - let expiry = invoice.expires_at().map(|t| t.as_secs()); - Ok(CreateIncomingPaymentResponse { - request_lookup_id: payment_hash.to_string(), - request: invoice.to_string(), + request_lookup_id: payment_hash, + request, expiry, }) } @@ -278,31 +420,37 @@ impl MintPayment for FakeWallet { #[instrument(skip_all)] async fn check_incoming_payment_status( &self, - _request_lookup_id: &str, - ) -> Result { - Ok(MintQuoteState::Paid) + request_lookup_id: &PaymentIdentifier, + ) -> Result, Self::Err> { + Ok(self + .incoming_payments + .read() + .await + .get(request_lookup_id) + .cloned() + .unwrap_or(vec![])) } #[instrument(skip_all)] async fn check_outgoing_payment( &self, - request_lookup_id: &str, + request_lookup_id: &PaymentIdentifier, ) -> Result { // For fake wallet if the state is not explicitly set default to paid let states = self.payment_states.lock().await; - let status = states.get(request_lookup_id).cloned(); + let status = states.get(&request_lookup_id.to_string()).cloned(); let status = status.unwrap_or(MeltQuoteState::Paid); let fail_payments = self.failed_payment_check.lock().await; - if fail_payments.contains(request_lookup_id) { - return Err(cdk_payment::Error::InvoicePaymentPending); + if fail_payments.contains(&request_lookup_id.to_string()) { + return Err(payment::Error::InvoicePaymentPending); } Ok(MakePaymentResponse { payment_proof: Some("".to_string()), - payment_lookup_id: request_lookup_id.to_string(), + payment_lookup_id: request_lookup_id.clone(), status, total_spent: Amount::ZERO, unit: CurrencyUnit::Msat, diff --git a/crates/cdk-integration-tests/src/init_pure_tests.rs b/crates/cdk-integration-tests/src/init_pure_tests.rs index 155f03e34..aafe5c60d 100644 --- a/crates/cdk-integration-tests/src/init_pure_tests.rs +++ b/crates/cdk-integration-tests/src/init_pure_tests.rs @@ -8,6 +8,7 @@ use std::{env, fs}; use anyhow::{anyhow, bail, Result}; use async_trait::async_trait; use bip39::Mnemonic; +use cashu::{MeltQuoteBolt12Request, MintQuoteBolt12Request, MintQuoteBolt12Response}; use cdk::amount::SplitTarget; use cdk::cdk_database::{self, WalletDatabase}; use cdk::mint::{MintBuilder, MintMeltLimits}; @@ -72,7 +73,7 @@ impl MintConnector for DirectMintConnection { request: MintQuoteBolt11Request, ) -> Result, Error> { self.mint - .get_mint_bolt11_quote(request) + .get_mint_quote(request.into()) .await .map(Into::into) } @@ -98,7 +99,7 @@ impl MintConnector for DirectMintConnection { request: MeltQuoteBolt11Request, ) -> Result, Error> { self.mint - .get_melt_bolt11_quote(&request) + .get_melt_quote(request.into()) .await .map(Into::into) } @@ -119,7 +120,7 @@ impl MintConnector for DirectMintConnection { request: MeltRequest, ) -> Result, Error> { let request_uuid = request.try_into().unwrap(); - self.mint.melt_bolt11(&request_uuid).await.map(Into::into) + self.mint.melt(&request_uuid).await.map(Into::into) } async fn post_swap(&self, swap_request: SwapRequest) -> Result { @@ -152,6 +153,59 @@ impl MintConnector for DirectMintConnection { *auth_wallet = wallet; } + + async fn post_mint_bolt12_quote( + &self, + request: MintQuoteBolt12Request, + ) -> Result, Error> { + let res: MintQuoteBolt12Response = + self.mint.get_mint_quote(request.into()).await?.try_into()?; + Ok(res.into()) + } + + async fn get_mint_quote_bolt12_status( + &self, + quote_id: &str, + ) -> Result, Error> { + let quote_id_uuid = Uuid::from_str(quote_id).unwrap(); + let quote: MintQuoteBolt12Response = self + .mint + .check_mint_quote("e_id_uuid) + .await? + .try_into()?; + + Ok(quote.into()) + } + + /// Melt Quote [NUT-23] + async fn post_melt_bolt12_quote( + &self, + request: MeltQuoteBolt12Request, + ) -> Result, Error> { + self.mint + .get_melt_quote(request.into()) + .await + .map(Into::into) + } + /// Melt Quote Status [NUT-23] + async fn get_melt_bolt12_quote_status( + &self, + quote_id: &str, + ) -> Result, Error> { + let quote_id_uuid = Uuid::from_str(quote_id).unwrap(); + self.mint + .check_melt_quote("e_id_uuid) + .await + .map(Into::into) + } + /// Melt [NUT-23] + async fn post_melt_bolt12( + &self, + _request: MeltRequest, + ) -> Result, Error> { + // Implementation to be added later + Err(Error::UnsupportedPaymentMethod) + } } pub fn setup_tracing() { diff --git a/crates/cdk-integration-tests/src/lib.rs b/crates/cdk-integration-tests/src/lib.rs index 304757111..2fb7d0623 100644 --- a/crates/cdk-integration-tests/src/lib.rs +++ b/crates/cdk-integration-tests/src/lib.rs @@ -2,7 +2,7 @@ use std::env; use std::sync::Arc; use anyhow::{anyhow, bail, Result}; -use cashu::Bolt11Invoice; +use cashu::{Bolt11Invoice, PaymentMethod}; use cdk::amount::{Amount, SplitTarget}; use cdk::nuts::{MintQuoteState, NotificationPayload, State}; use cdk::wallet::WalletSubscription; @@ -86,6 +86,10 @@ pub async fn wait_for_mint_to_be_paid( if response.state == MintQuoteState::Paid { return Ok(()); } + } else if let NotificationPayload::MintQuoteBolt12Response(response) = msg { + if response.amount_paid > Amount::ZERO { + return Ok(()); + } } } Err(anyhow!("Subscription ended without quote being paid")) @@ -95,18 +99,40 @@ pub async fn wait_for_mint_to_be_paid( let check_interval = Duration::from_secs(5); + let method = wallet + .localstore + .get_mint_quote(mint_quote_id) + .await? + .map(|q| q.payment_method) + .unwrap_or_default(); + let periodic_task = async { loop { - match wallet.mint_quote_state(mint_quote_id).await { - Ok(result) => { - if result.state == MintQuoteState::Paid { - tracing::info!("mint quote paid via poll"); - return Ok(()); + match method { + PaymentMethod::Bolt11 => match wallet.mint_quote_state(mint_quote_id).await { + Ok(result) => { + if result.state == MintQuoteState::Paid { + tracing::info!("mint quote paid via poll"); + return Ok(()); + } + } + Err(e) => { + tracing::error!("Could not check mint quote status: {:?}", e); + } + }, + PaymentMethod::Bolt12 => { + match wallet.mint_bolt12_quote_state(mint_quote_id).await { + Ok(result) => { + if result.amount_paid > Amount::ZERO { + return Ok(()); + } + } + Err(e) => { + tracing::error!("Could not check mint quote status: {:?}", e); + } } } - Err(e) => { - tracing::error!("Could not check mint quote status: {:?}", e); - } + PaymentMethod::Custom(_) => (), } sleep(check_interval).await; } @@ -166,7 +192,6 @@ pub async fn init_lnd_client() -> LndClient { pub async fn pay_if_regtest(invoice: &Bolt11Invoice) -> Result<()> { // Check if the invoice is for the regtest network if invoice.network() == bitcoin::Network::Regtest { - println!("Regtest invoice"); let lnd_client = init_lnd_client().await; lnd_client.pay_invoice(invoice.to_string()).await?; Ok(()) diff --git a/crates/cdk-integration-tests/tests/bolt12.rs b/crates/cdk-integration-tests/tests/bolt12.rs new file mode 100644 index 000000000..5a265c899 --- /dev/null +++ b/crates/cdk-integration-tests/tests/bolt12.rs @@ -0,0 +1,332 @@ +use std::sync::Arc; + +use anyhow::{bail, Result}; +use bip39::Mnemonic; +use cashu::amount::SplitTarget; +use cashu::nut23::Amountless; +use cashu::{Amount, CurrencyUnit, MintRequest, PreMintSecrets, ProofsMethods}; +use cdk::wallet::{HttpClient, MintConnector, Wallet}; +use cdk_integration_tests::init_regtest::get_cln_dir; +use cdk_integration_tests::{get_mint_url_from_env, wait_for_mint_to_be_paid}; +use cdk_sqlite::wallet::memory; +use ln_regtest_rs::ln_client::ClnClient; + +/// Tests basic BOLT12 minting functionality: +/// - Creates a wallet +/// - Gets a BOLT12 quote for a specific amount (100 sats) +/// - Pays the quote using Core Lightning +/// - Mints tokens and verifies the correct amount is received +#[tokio::test(flavor = "multi_thread", worker_threads = 1)] +async fn test_regtest_bolt12_mint() { + let wallet = Wallet::new( + &get_mint_url_from_env(), + CurrencyUnit::Sat, + Arc::new(memory::empty().await.unwrap()), + &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + None, + ) + .unwrap(); + + let mint_amount = Amount::from(100); + + let mint_quote = wallet + .mint_bolt12_quote(Some(mint_amount), None) + .await + .unwrap(); + + assert_eq!(mint_quote.amount, Some(mint_amount)); + + let cln_one_dir = get_cln_dir("one"); + let cln_client = ClnClient::new(cln_one_dir.clone(), None).await.unwrap(); + cln_client + .pay_bolt12_offer(None, mint_quote.request) + .await + .unwrap(); + + let proofs = wallet + .mint_bolt12(&mint_quote.id, None, SplitTarget::default(), None) + .await + .unwrap(); + + assert_eq!(proofs.total_amount().unwrap(), 100.into()); +} + +/// Tests multiple payments to a single BOLT12 quote: +/// - Creates a wallet and gets a BOLT12 quote without specifying amount +/// - Makes two separate payments (10,000 sats and 11,000 sats) to the same quote +/// - Verifies that each payment can be minted separately and correctly +/// - Tests the functionality of reusing a quote for multiple payments +#[tokio::test(flavor = "multi_thread", worker_threads = 1)] +async fn test_regtest_bolt12_mint_multiple() -> Result<()> { + let wallet = Wallet::new( + &get_mint_url_from_env(), + CurrencyUnit::Sat, + Arc::new(memory::empty().await?), + &Mnemonic::generate(12)?.to_seed_normalized(""), + None, + )?; + + let mint_quote = wallet.mint_bolt12_quote(None, None).await?; + + let cln_one_dir = get_cln_dir("one"); + let cln_client = ClnClient::new(cln_one_dir.clone(), None).await?; + cln_client + .pay_bolt12_offer(Some(10000), mint_quote.request.clone()) + .await + .unwrap(); + + wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60).await?; + + wallet.mint_bolt12_quote_state(&mint_quote.id).await?; + + let proofs = wallet + .mint_bolt12(&mint_quote.id, None, SplitTarget::default(), None) + .await + .unwrap(); + + assert_eq!(proofs.total_amount().unwrap(), 10.into()); + + cln_client + .pay_bolt12_offer(Some(11_000), mint_quote.request) + .await + .unwrap(); + + wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60).await?; + + wallet.mint_bolt12_quote_state(&mint_quote.id).await?; + + let proofs = wallet + .mint_bolt12(&mint_quote.id, None, SplitTarget::default(), None) + .await + .unwrap(); + + assert_eq!(proofs.total_amount().unwrap(), 11.into()); + + Ok(()) +} + +/// Tests that multiple wallets can pay the same BOLT12 offer: +/// - Creates a BOLT12 offer through CLN that both wallets will pay +/// - Creates two separate wallets with different minting amounts +/// - Has each wallet get their own quote and make payments +/// - Verifies both wallets can successfully mint their tokens +#[tokio::test(flavor = "multi_thread", worker_threads = 1)] +async fn test_regtest_bolt12_multiple_wallets() -> Result<()> { + // Create first wallet + let wallet_one = Wallet::new( + &get_mint_url_from_env(), + CurrencyUnit::Sat, + Arc::new(memory::empty().await?), + &Mnemonic::generate(12)?.to_seed_normalized(""), + None, + )?; + + // Create second wallet + let wallet_two = Wallet::new( + &get_mint_url_from_env(), + CurrencyUnit::Sat, + Arc::new(memory::empty().await?), + &Mnemonic::generate(12)?.to_seed_normalized(""), + None, + )?; + + // Create a BOLT12 offer that both wallets will use + let cln_one_dir = get_cln_dir("one"); + let cln_client = ClnClient::new(cln_one_dir.clone(), None).await?; + // First wallet payment + let quote_one = wallet_one + .mint_bolt12_quote(Some(10_000.into()), None) + .await?; + cln_client + .pay_bolt12_offer(None, quote_one.request.clone()) + .await?; + wait_for_mint_to_be_paid(&wallet_one, "e_one.id, 60).await?; + let proofs_one = wallet_one + .mint_bolt12("e_one.id, None, SplitTarget::default(), None) + .await?; + + assert_eq!(proofs_one.total_amount()?, 10_000.into()); + + // Second wallet payment + let quote_two = wallet_two + .mint_bolt12_quote(Some(15_000.into()), None) + .await?; + cln_client + .pay_bolt12_offer(None, quote_two.request.clone()) + .await?; + wait_for_mint_to_be_paid(&wallet_two, "e_two.id, 60).await?; + + let proofs_two = wallet_two + .mint_bolt12("e_two.id, None, SplitTarget::default(), None) + .await?; + assert_eq!(proofs_two.total_amount()?, 15_000.into()); + + let offer = cln_client + .get_bolt12_offer(None, false, "test_multiple_wallets".to_string()) + .await?; + + let wallet_one_melt_quote = wallet_one + .melt_bolt12_quote( + offer.to_string(), + Some(cashu::MeltOptions::Amountless { + amountless: Amountless { + amount_msat: 1500.into(), + }, + }), + ) + .await?; + + let wallet_two_melt_quote = wallet_two + .melt_bolt12_quote( + offer.to_string(), + Some(cashu::MeltOptions::Amountless { + amountless: Amountless { + amount_msat: 1000.into(), + }, + }), + ) + .await?; + + let melted = wallet_one.melt(&wallet_one_melt_quote.id).await?; + + assert!(melted.preimage.is_some()); + + let melted_two = wallet_two.melt(&wallet_two_melt_quote.id).await?; + + assert!(melted_two.preimage.is_some()); + + Ok(()) +} + +/// Tests the BOLT12 melting (spending) functionality: +/// - Creates a wallet and mints 20,000 sats using BOLT12 +/// - Creates a BOLT12 offer for 10,000 sats +/// - Tests melting (spending) tokens using the BOLT12 offer +/// - Verifies the correct amount is melted +#[tokio::test(flavor = "multi_thread", worker_threads = 1)] +async fn test_regtest_bolt12_melt() -> Result<()> { + let wallet = Wallet::new( + &get_mint_url_from_env(), + CurrencyUnit::Sat, + Arc::new(memory::empty().await?), + &Mnemonic::generate(12)?.to_seed_normalized(""), + None, + )?; + + wallet.get_mint_info().await?; + + let mint_amount = Amount::from(20_000); + + // Create a single-use BOLT12 quote + let mint_quote = wallet.mint_bolt12_quote(Some(mint_amount), None).await?; + + assert_eq!(mint_quote.amount, Some(mint_amount)); + // Pay the quote + let cln_one_dir = get_cln_dir("one"); + let cln_client = ClnClient::new(cln_one_dir.clone(), None).await?; + cln_client + .pay_bolt12_offer(None, mint_quote.request.clone()) + .await?; + + // Wait for payment to be processed + wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60).await?; + + let offer = cln_client + .get_bolt12_offer(Some(10_000), true, "hhhhhhhh".to_string()) + .await?; + + let _proofs = wallet + .mint_bolt12(&mint_quote.id, None, SplitTarget::default(), None) + .await + .unwrap(); + + let quote = wallet.melt_bolt12_quote(offer.to_string(), None).await?; + + let melt = wallet.melt("e.id).await?; + + assert_eq!(melt.amount, 10.into()); + + Ok(()) +} + +/// Tests security validation for BOLT12 minting to prevent overspending: +/// - Creates a wallet and gets an open-ended BOLT12 quote +/// - Makes a payment of 10,000 millisats +/// - Attempts to mint more tokens (500 sats) than were actually paid for +/// - Verifies that the mint correctly rejects the oversized mint request +/// - Ensures proper error handling with TransactionUnbalanced error +/// This test is crucial for ensuring the economic security of the minting process +/// by preventing users from minting more tokens than they have paid for. +#[tokio::test(flavor = "multi_thread", worker_threads = 1)] +async fn test_regtest_bolt12_mint_extra() -> Result<()> { + let wallet = Wallet::new( + &get_mint_url_from_env(), + CurrencyUnit::Sat, + Arc::new(memory::empty().await?), + &Mnemonic::generate(12)?.to_seed_normalized(""), + None, + )?; + + wallet.get_mint_info().await?; + + // Create a single-use BOLT12 quote + let mint_quote = wallet.mint_bolt12_quote(None, None).await?; + + let state = wallet.mint_bolt12_quote_state(&mint_quote.id).await?; + + assert_eq!(state.amount_paid, Amount::ZERO); + assert_eq!(state.amount_issued, Amount::ZERO); + + let active_keyset_id = wallet.get_active_mint_keyset().await?.id; + + let pay_amount_msats = 10_000; + + let cln_one_dir = get_cln_dir("one"); + let cln_client = ClnClient::new(cln_one_dir.clone(), None).await?; + cln_client + .pay_bolt12_offer(Some(pay_amount_msats), mint_quote.request.clone()) + .await?; + + wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 10).await?; + + let state = wallet.mint_bolt12_quote_state(&mint_quote.id).await?; + + assert_eq!(state.amount_paid, (pay_amount_msats / 1_000).into()); + assert_eq!(state.amount_issued, Amount::ZERO); + + let pre_mint = PreMintSecrets::random(active_keyset_id, 500.into(), &SplitTarget::None)?; + + let quote_info = wallet + .localstore + .get_mint_quote(&mint_quote.id) + .await? + .expect("there is a quote"); + + let mut mint_request = MintRequest { + quote: mint_quote.id, + outputs: pre_mint.blinded_messages(), + signature: None, + }; + + if let Some(secret_key) = quote_info.secret_key { + mint_request.sign(secret_key)?; + } + + let http_client = HttpClient::new(get_mint_url_from_env().parse().unwrap(), None); + + let response = http_client.post_mint(mint_request.clone()).await; + + match response { + Err(err) => match err { + cdk::Error::TransactionUnbalanced(_, _, _) => (), + err => { + bail!("Wrong mint error returned: {}", err.to_string()); + } + }, + Ok(_) => { + bail!("Should not have allowed second payment"); + } + } + + Ok(()) +} diff --git a/crates/cdk-integration-tests/tests/fake_auth.rs b/crates/cdk-integration-tests/tests/fake_auth.rs index d9c97514b..bf2134bdd 100644 --- a/crates/cdk-integration-tests/tests/fake_auth.rs +++ b/crates/cdk-integration-tests/tests/fake_auth.rs @@ -514,7 +514,7 @@ async fn test_reuse_auth_proof() { .await .expect("Quote should be allowed"); - assert!(quote.amount == 10.into()); + assert!(quote.amount == Some(10.into())); } wallet @@ -645,7 +645,7 @@ async fn test_refresh_access_token() { .await .expect("failed to get mint quote with refreshed token"); - assert_eq!(mint_quote.amount, mint_amount); + assert_eq!(mint_quote.amount, Some(mint_amount)); // Verify the total number of auth tokens let total_auth_proofs = wallet.get_unspent_auth_proofs().await.unwrap(); @@ -731,7 +731,7 @@ async fn test_auth_token_spending_order() { .await .expect("failed to get mint quote"); - assert_eq!(mint_quote.amount, 10.into()); + assert_eq!(mint_quote.amount, Some(10.into())); // Check remaining tokens after each operation let remaining = wallet.get_unspent_auth_proofs().await.unwrap(); diff --git a/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs b/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs index 2f596388c..e93111965 100644 --- a/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs +++ b/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs @@ -100,6 +100,10 @@ async fn test_happy_mint_melt_round_trip() { let invoice = Bolt11Invoice::from_str(&mint_quote.request).unwrap(); pay_if_regtest(&invoice).await.unwrap(); + wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 10) + .await + .unwrap(); + let proofs = wallet .mint(&mint_quote.id, SplitTarget::default(), None) .await @@ -210,7 +214,7 @@ async fn test_happy_mint() { let mint_quote = wallet.mint_quote(mint_amount, None).await.unwrap(); - assert_eq!(mint_quote.amount, mint_amount); + assert_eq!(mint_quote.amount, Some(mint_amount)); let invoice = Bolt11Invoice::from_str(&mint_quote.request).unwrap(); pay_if_regtest(&invoice).await.unwrap(); @@ -285,6 +289,8 @@ async fn test_restore() { let restored = wallet_2.restore().await.unwrap(); let proofs = wallet_2.get_unspent_proofs().await.unwrap(); + assert!(!proofs.is_empty()); + let expected_fee = wallet.get_proofs_fee(&proofs).await.unwrap(); wallet_2 .swap(None, SplitTarget::default(), proofs, None, false) @@ -431,7 +437,9 @@ async fn test_pay_invoice_twice() { Err(err) => match err { cdk::Error::RequestAlreadyPaid => (), err => { - panic!("Wrong invoice already paid: {}", err.to_string()); + if !err.to_string().contains("Duplicate entry") { + panic!("Wrong invoice already paid: {}", err.to_string()); + } } }, Ok(_) => { diff --git a/crates/cdk-integration-tests/tests/integration_tests_pure.rs b/crates/cdk-integration-tests/tests/integration_tests_pure.rs index fc60de484..4eb9dd72e 100644 --- a/crates/cdk-integration-tests/tests/integration_tests_pure.rs +++ b/crates/cdk-integration-tests/tests/integration_tests_pure.rs @@ -832,11 +832,11 @@ async fn test_concurrent_double_spend_melt() { let melt_request3 = melt_request.clone(); // Spawn 3 concurrent tasks to process the melt requests - let task1 = tokio::spawn(async move { mint_clone1.melt_bolt11(&melt_request).await }); + let task1 = tokio::spawn(async move { mint_clone1.melt(&melt_request).await }); - let task2 = tokio::spawn(async move { mint_clone2.melt_bolt11(&melt_request2).await }); + let task2 = tokio::spawn(async move { mint_clone2.melt(&melt_request2).await }); - let task3 = tokio::spawn(async move { mint_clone3.melt_bolt11(&melt_request3).await }); + let task3 = tokio::spawn(async move { mint_clone3.melt(&melt_request3).await }); // Wait for all tasks to complete let results = tokio::try_join!(task1, task2, task3).expect("Tasks failed to complete"); diff --git a/crates/cdk-integration-tests/tests/regtest.rs b/crates/cdk-integration-tests/tests/regtest.rs index e50aef785..f73d432b6 100644 --- a/crates/cdk-integration-tests/tests/regtest.rs +++ b/crates/cdk-integration-tests/tests/regtest.rs @@ -89,7 +89,7 @@ async fn test_internal_payment() { let _melted = wallet.melt(&melt.id).await.unwrap(); - wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60) + wait_for_mint_to_be_paid(&wallet_2, &mint_quote.id, 60) .await .unwrap(); @@ -348,7 +348,7 @@ async fn test_regtest_melt_amountless() { let mint_quote = wallet.mint_quote(mint_amount, None).await.unwrap(); - assert_eq!(mint_quote.amount, mint_amount); + assert_eq!(mint_quote.amount, Some(mint_amount)); lnd_client .pay_invoice(mint_quote.request) diff --git a/crates/cdk-integration-tests/tests/test_fees.rs b/crates/cdk-integration-tests/tests/test_fees.rs index da7c24f49..0893ab41c 100644 --- a/crates/cdk-integration-tests/tests/test_fees.rs +++ b/crates/cdk-integration-tests/tests/test_fees.rs @@ -28,6 +28,10 @@ async fn test_swap() { let invoice = Bolt11Invoice::from_str(&mint_quote.request).unwrap(); pay_if_regtest(&invoice).await.unwrap(); + wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 10) + .await + .unwrap(); + let _mint_amount = wallet .mint(&mint_quote.id, SplitTarget::default(), None) .await diff --git a/crates/cdk-lnbits/src/error.rs b/crates/cdk-lnbits/src/error.rs index d22d69dcd..83cc6336b 100644 --- a/crates/cdk-lnbits/src/error.rs +++ b/crates/cdk-lnbits/src/error.rs @@ -14,6 +14,9 @@ pub enum Error { /// Amount overflow #[error("Amount overflow")] AmountOverflow, + /// Invalid payment hash + #[error("Invalid payment hash")] + InvalidPaymentHash, /// Anyhow error #[error(transparent)] Anyhow(#[from] anyhow::Error), diff --git a/crates/cdk-lnbits/src/lib.rs b/crates/cdk-lnbits/src/lib.rs index 6a14395f9..3703a47e7 100644 --- a/crates/cdk-lnbits/src/lib.rs +++ b/crates/cdk-lnbits/src/lib.rs @@ -6,7 +6,6 @@ use std::cmp::max; use std::pin::Pin; -use std::str::FromStr; use std::sync::atomic::{AtomicBool, Ordering}; use std::sync::Arc; @@ -15,13 +14,14 @@ use async_trait::async_trait; use axum::Router; use cdk_common::amount::{to_unit, Amount, MSAT_IN_SAT}; use cdk_common::common::FeeReserve; -use cdk_common::nuts::{CurrencyUnit, MeltOptions, MeltQuoteState, MintQuoteState}; +use cdk_common::nuts::{CurrencyUnit, MeltOptions, MeltQuoteState}; use cdk_common::payment::{ - self, Bolt11Settings, CreateIncomingPaymentResponse, MakePaymentResponse, MintPayment, - PaymentQuoteResponse, + self, Bolt11Settings, CreateIncomingPaymentResponse, IncomingPaymentOptions, + MakePaymentResponse, MintPayment, OutgoingPaymentOptions, PaymentIdentifier, + PaymentQuoteResponse, WaitPaymentResponse, }; -use cdk_common::util::unix_time; -use cdk_common::{mint, Bolt11Invoice}; +use cdk_common::util::{hex, unix_time}; +use cdk_common::Bolt11Invoice; use error::Error; use futures::Stream; use lnbits_rs::api::invoice::CreateInvoiceRequest; @@ -65,6 +65,7 @@ impl LNbits { unit: CurrencyUnit::Sat, invoice_description: true, amountless: false, + bolt12: false, }, }) } @@ -99,7 +100,7 @@ impl MintPayment for LNbits { async fn wait_any_incoming_payment( &self, - ) -> Result + Send>>, Self::Err> { + ) -> Result + Send>>, Self::Err> { let api = self.lnbits_api.clone(); let cancel_token = self.wait_invoice_cancel_token.clone(); let is_active = Arc::clone(&self.wait_invoice_is_active); @@ -122,23 +123,45 @@ impl MintPayment for LNbits { msg_option = receiver.recv() => { match msg_option { Some(msg) => { - let check = api.is_invoice_paid(&msg).await; - + let check = api.get_payment_info(&msg).await; match check { - Ok(state) => { - if state { - Some((msg, (api, cancel_token, is_active))) + Ok(payment) => { + if payment.paid { + match hex::decode(msg.clone()) { + Ok(decoded) => { + match decoded.try_into() { + Ok(hash) => { + let response = WaitPaymentResponse { + payment_identifier: PaymentIdentifier::PaymentHash(hash), + payment_amount: Amount::from(payment.details.amount as u64), + unit: CurrencyUnit::Sat, + payment_id: msg.clone() + }; + Some((response, (api, cancel_token, is_active))) + }, + Err(e) => { + tracing::error!("Failed to convert payment hash bytes to array: {:?}", e); + None + } + } + }, + Err(e) => { + tracing::error!("Failed to decode payment hash hex string: {}", e); + None + } + } } else { - Some(("".to_string(), (api, cancel_token, is_active))) + tracing::warn!("Received payment notification but could not check payment for {}", msg); + None } - } - _ => Some(("".to_string(), (api, cancel_token, is_active))), + }, + Err(_) => None } - } + }, None => { is_active.store(false, Ordering::SeqCst); None - }, + } } } } @@ -148,151 +171,181 @@ impl MintPayment for LNbits { async fn get_payment_quote( &self, - request: &str, unit: &CurrencyUnit, - options: Option, + options: OutgoingPaymentOptions, ) -> Result { if unit != &CurrencyUnit::Sat { return Err(Self::Err::Anyhow(anyhow!("Unsupported unit"))); } - let bolt11 = Bolt11Invoice::from_str(request)?; - - let amount_msat = match options { - Some(amount) => { - if matches!(amount, MeltOptions::Mpp { mpp: _ }) { - return Err(payment::Error::UnsupportedPaymentOption); - } - amount.amount_msat() + match options { + OutgoingPaymentOptions::Bolt11(bolt11_options) => { + let amount_msat = match bolt11_options.melt_options { + Some(amount) => { + if matches!(amount, MeltOptions::Mpp { mpp: _ }) { + return Err(payment::Error::UnsupportedPaymentOption); + } + amount.amount_msat() + } + None => bolt11_options + .bolt11 + .amount_milli_satoshis() + .ok_or(Error::UnknownInvoiceAmount)? + .into(), + }; + + let amount = amount_msat / MSAT_IN_SAT.into(); + + let relative_fee_reserve = + (self.fee_reserve.percent_fee_reserve * u64::from(amount) as f32) as u64; + + let absolute_fee_reserve: u64 = self.fee_reserve.min_fee_reserve.into(); + + let fee = max(relative_fee_reserve, absolute_fee_reserve); + + Ok(PaymentQuoteResponse { + request_lookup_id: PaymentIdentifier::PaymentHash( + *bolt11_options.bolt11.payment_hash().as_ref(), + ), + amount, + fee: fee.into(), + state: MeltQuoteState::Unpaid, + options: None, + unit: unit.clone(), + }) } - None => bolt11 - .amount_milli_satoshis() - .ok_or(Error::UnknownInvoiceAmount)? - .into(), - }; - - let amount = amount_msat / MSAT_IN_SAT.into(); - - let relative_fee_reserve = - (self.fee_reserve.percent_fee_reserve * u64::from(amount) as f32) as u64; - - let absolute_fee_reserve: u64 = self.fee_reserve.min_fee_reserve.into(); - - let fee = max(relative_fee_reserve, absolute_fee_reserve); - - Ok(PaymentQuoteResponse { - request_lookup_id: bolt11.payment_hash().to_string(), - amount, - unit: unit.clone(), - fee: fee.into(), - state: MeltQuoteState::Unpaid, - }) + OutgoingPaymentOptions::Bolt12(_bolt12_options) => { + Err(Self::Err::Anyhow(anyhow!("BOLT12 not supported by LNbits"))) + } + } } async fn make_payment( &self, - melt_quote: mint::MeltQuote, - _partial_msats: Option, - _max_fee_msats: Option, + _unit: &CurrencyUnit, + options: OutgoingPaymentOptions, ) -> Result { - let pay_response = self - .lnbits_api - .pay_invoice(&melt_quote.request, None) - .await - .map_err(|err| { - tracing::error!("Could not pay invoice"); - tracing::error!("{}", err.to_string()); - Self::Err::Anyhow(anyhow!("Could not pay invoice")) - })?; - - let invoice_info = self - .lnbits_api - .get_payment_info(&pay_response.payment_hash) - .await - .map_err(|err| { - tracing::error!("Could not find invoice"); - tracing::error!("{}", err.to_string()); - Self::Err::Anyhow(anyhow!("Could not find invoice")) - })?; - - let status = match invoice_info.paid { - true => MeltQuoteState::Paid, - false => MeltQuoteState::Unpaid, - }; - - let total_spent = Amount::from( - (invoice_info - .details - .amount - .checked_add(invoice_info.details.fee) - .ok_or(Error::AmountOverflow)?) - .unsigned_abs(), - ); - - Ok(MakePaymentResponse { - payment_lookup_id: pay_response.payment_hash, - payment_proof: invoice_info.details.preimage, - status, - total_spent, - unit: CurrencyUnit::Sat, - }) + match options { + OutgoingPaymentOptions::Bolt11(bolt11_options) => { + let pay_response = self + .lnbits_api + .pay_invoice(&bolt11_options.bolt11.to_string(), None) + .await + .map_err(|err| { + tracing::error!("Could not pay invoice"); + tracing::error!("{}", err.to_string()); + Self::Err::Anyhow(anyhow!("Could not pay invoice")) + })?; + + let invoice_info = self + .lnbits_api + .get_payment_info(&pay_response.payment_hash) + .await + .map_err(|err| { + tracing::error!("Could not find invoice"); + tracing::error!("{}", err.to_string()); + Self::Err::Anyhow(anyhow!("Could not find invoice")) + })?; + + let status = if invoice_info.paid { + MeltQuoteState::Unpaid + } else { + MeltQuoteState::Paid + }; + + let total_spent = Amount::from( + (invoice_info + .details + .amount + .checked_add(invoice_info.details.fee) + .ok_or(Error::AmountOverflow)?) + .unsigned_abs(), + ); + + Ok(MakePaymentResponse { + payment_lookup_id: PaymentIdentifier::PaymentHash( + hex::decode(pay_response.payment_hash) + .map_err(|_| Error::InvalidPaymentHash)? + .try_into() + .map_err(|_| Error::InvalidPaymentHash)?, + ), + payment_proof: Some(invoice_info.details.payment_hash), + status, + total_spent, + unit: CurrencyUnit::Sat, + }) + } + OutgoingPaymentOptions::Bolt12(_) => { + Err(Self::Err::Anyhow(anyhow!("BOLT12 not supported by LNbits"))) + } + } } async fn create_incoming_payment_request( &self, - amount: Amount, unit: &CurrencyUnit, - description: String, - unix_expiry: Option, + options: IncomingPaymentOptions, ) -> Result { if unit != &CurrencyUnit::Sat { return Err(Self::Err::Anyhow(anyhow!("Unsupported unit"))); } - let time_now = unix_time(); - - let expiry = unix_expiry.map(|t| t - time_now); - - let invoice_request = CreateInvoiceRequest { - amount: to_unit(amount, unit, &CurrencyUnit::Sat)?.into(), - memo: Some(description), - unit: unit.to_string(), - expiry, - webhook: self.webhook_url.clone(), - internal: None, - out: false, - }; - - let create_invoice_response = self - .lnbits_api - .create_invoice(&invoice_request) - .await - .map_err(|err| { - tracing::error!("Could not create invoice"); - tracing::error!("{}", err.to_string()); - Self::Err::Anyhow(anyhow!("Could not create invoice")) - })?; - - let request: Bolt11Invoice = create_invoice_response - .bolt11() - .ok_or_else(|| Self::Err::Anyhow(anyhow!("Missing bolt11 invoice")))? - .parse()?; - let expiry = request.expires_at().map(|t| t.as_secs()); - - Ok(CreateIncomingPaymentResponse { - request_lookup_id: create_invoice_response.payment_hash().to_string(), - request: request.to_string(), - expiry, - }) + match options { + IncomingPaymentOptions::Bolt11(bolt11_options) => { + let description = bolt11_options.description.unwrap_or_default(); + let amount = bolt11_options.amount; + let unix_expiry = bolt11_options.unix_expiry; + + let time_now = unix_time(); + let expiry = unix_expiry.map(|t| t - time_now); + + let invoice_request = CreateInvoiceRequest { + amount: to_unit(amount, unit, &CurrencyUnit::Sat)?.into(), + memo: Some(description), + unit: unit.to_string(), + expiry, + webhook: self.webhook_url.clone(), + internal: None, + out: false, + }; + + let create_invoice_response = self + .lnbits_api + .create_invoice(&invoice_request) + .await + .map_err(|err| { + tracing::error!("Could not create invoice"); + tracing::error!("{}", err.to_string()); + Self::Err::Anyhow(anyhow!("Could not create invoice")) + })?; + + let request: Bolt11Invoice = create_invoice_response + .bolt11() + .ok_or_else(|| Self::Err::Anyhow(anyhow!("Missing bolt11 invoice")))? + .parse()?; + let expiry = request.expires_at().map(|t| t.as_secs()); + + Ok(CreateIncomingPaymentResponse { + request_lookup_id: PaymentIdentifier::PaymentHash( + *request.payment_hash().as_ref(), + ), + request: request.to_string(), + expiry, + }) + } + IncomingPaymentOptions::Bolt12(_) => { + Err(Self::Err::Anyhow(anyhow!("BOLT12 not supported by LNbits"))) + } + } } async fn check_incoming_payment_status( &self, - payment_hash: &str, - ) -> Result { - let paid = self + payment_identifier: &PaymentIdentifier, + ) -> Result, Self::Err> { + let payment = self .lnbits_api - .is_invoice_paid(payment_hash) + .get_payment_info(&payment_identifier.to_string()) .await .map_err(|err| { tracing::error!("Could not check invoice status"); @@ -300,21 +353,21 @@ impl MintPayment for LNbits { Self::Err::Anyhow(anyhow!("Could not check invoice status")) })?; - let state = match paid { - true => MintQuoteState::Paid, - false => MintQuoteState::Unpaid, - }; - - Ok(state) + Ok(vec![WaitPaymentResponse { + payment_identifier: payment_identifier.clone(), + payment_amount: Amount::from(payment.details.amount as u64), + unit: CurrencyUnit::Sat, + payment_id: payment.details.payment_hash, + }]) } async fn check_outgoing_payment( &self, - payment_hash: &str, + payment_identifier: &PaymentIdentifier, ) -> Result { let payment = self .lnbits_api - .get_payment_info(payment_hash) + .get_payment_info(&payment_identifier.to_string()) .await .map_err(|err| { tracing::error!("Could not check invoice status"); @@ -323,7 +376,7 @@ impl MintPayment for LNbits { })?; let pay_response = MakePaymentResponse { - payment_lookup_id: payment.details.payment_hash, + payment_lookup_id: payment_identifier.clone(), payment_proof: payment.preimage, status: lnbits_to_melt_status(&payment.details.status, payment.details.pending), total_spent: Amount::from( diff --git a/crates/cdk-lnd/src/lib.rs b/crates/cdk-lnd/src/lib.rs index c923d5543..98296e945 100644 --- a/crates/cdk-lnd/src/lib.rs +++ b/crates/cdk-lnd/src/lib.rs @@ -18,13 +18,14 @@ use async_trait::async_trait; use cdk_common::amount::{to_unit, Amount, MSAT_IN_SAT}; use cdk_common::bitcoin::hashes::Hash; use cdk_common::common::FeeReserve; -use cdk_common::nuts::{CurrencyUnit, MeltOptions, MeltQuoteState, MintQuoteState}; +use cdk_common::nuts::{CurrencyUnit, MeltOptions, MeltQuoteState}; use cdk_common::payment::{ - self, Bolt11Settings, CreateIncomingPaymentResponse, MakePaymentResponse, MintPayment, - PaymentQuoteResponse, + self, Bolt11Settings, CreateIncomingPaymentResponse, IncomingPaymentOptions, + MakePaymentResponse, MintPayment, OutgoingPaymentOptions, PaymentIdentifier, + PaymentQuoteResponse, WaitPaymentResponse, }; use cdk_common::util::hex; -use cdk_common::{mint, Bolt11Invoice}; +use cdk_common::Bolt11Invoice; use error::Error; use futures::{Stream, StreamExt}; use lnrpc::fee_limit::Limit; @@ -39,6 +40,8 @@ pub mod error; mod proto; pub(crate) use proto::{lnrpc, routerrpc}; +use crate::lnrpc::invoice::InvoiceState; + /// Lnd mint backend #[derive(Clone)] pub struct Lnd { @@ -108,6 +111,7 @@ impl Lnd { unit: CurrencyUnit::Msat, invoice_description: true, amountless: true, + bolt12: false, }, }) } @@ -135,7 +139,7 @@ impl MintPayment for Lnd { #[instrument(skip_all)] async fn wait_any_incoming_payment( &self, - ) -> Result + Send>>, Self::Err> { + ) -> Result + Send>>, Self::Err> { let mut lnd_client = self.lnd_client.clone(); let stream_req = lnrpc::InvoiceSubscription { @@ -176,8 +180,23 @@ impl MintPayment for Lnd { match msg { Ok(Some(msg)) => { - if msg.state == 1 { - Some((hex::encode(msg.r_hash), (stream, cancel_token, is_active))) + if msg.state() == InvoiceState::Settled { + + let hash_slice: Result<[u8;32], _> = msg.r_hash.try_into(); + + if let Ok(hash_slice) = hash_slice { + let hash = hex::encode(hash_slice); + + tracing::info!("LND: Processing payment with hash: {}", hash); + let wait_response = WaitPaymentResponse { + payment_identifier: PaymentIdentifier::PaymentHash(hash_slice), payment_amount: Amount::from(msg.amt_paid_msat as u64), + unit: CurrencyUnit::Msat, + payment_id: hash, + }; + tracing::info!("LND: Created WaitPaymentResponse with amount {} msat", + msg.amt_paid_msat); + Some((wait_response, (stream, cancel_token, is_active))) + } else { None } } else { None } @@ -205,261 +224,299 @@ impl MintPayment for Lnd { #[instrument(skip_all)] async fn get_payment_quote( &self, - request: &str, unit: &CurrencyUnit, - options: Option, + options: OutgoingPaymentOptions, ) -> Result { - let bolt11 = Bolt11Invoice::from_str(request)?; - - let amount_msat = match options { - Some(amount) => amount.amount_msat(), - None => bolt11 - .amount_milli_satoshis() - .ok_or(Error::UnknownInvoiceAmount)? - .into(), - }; + match options { + OutgoingPaymentOptions::Bolt11(bolt11_options) => { + let amount_msat = match bolt11_options.melt_options { + Some(amount) => amount.amount_msat(), + None => bolt11_options + .bolt11 + .amount_milli_satoshis() + .ok_or(Error::UnknownInvoiceAmount)? + .into(), + }; - let amount = to_unit(amount_msat, &CurrencyUnit::Msat, unit)?; + let amount = to_unit(amount_msat, &CurrencyUnit::Msat, unit)?; - let relative_fee_reserve = - (self.fee_reserve.percent_fee_reserve * u64::from(amount) as f32) as u64; + let relative_fee_reserve = + (self.fee_reserve.percent_fee_reserve * u64::from(amount) as f32) as u64; - let absolute_fee_reserve: u64 = self.fee_reserve.min_fee_reserve.into(); + let absolute_fee_reserve: u64 = self.fee_reserve.min_fee_reserve.into(); - let fee = max(relative_fee_reserve, absolute_fee_reserve); + let fee = max(relative_fee_reserve, absolute_fee_reserve); - Ok(PaymentQuoteResponse { - request_lookup_id: bolt11.payment_hash().to_string(), - amount, - unit: unit.clone(), - fee: fee.into(), - state: MeltQuoteState::Unpaid, - }) + Ok(PaymentQuoteResponse { + request_lookup_id: PaymentIdentifier::PaymentHash( + *bolt11_options.bolt11.payment_hash().as_ref(), + ), + amount, + fee: fee.into(), + state: MeltQuoteState::Unpaid, + options: None, + unit: unit.clone(), + }) + } + OutgoingPaymentOptions::Bolt12(_) => { + Err(Self::Err::Anyhow(anyhow!("BOLT12 not supported by LND"))) + } + } } #[instrument(skip_all)] async fn make_payment( &self, - melt_quote: mint::MeltQuote, - partial_amount: Option, - max_fee: Option, + _unit: &CurrencyUnit, + options: OutgoingPaymentOptions, ) -> Result { - let payment_request = melt_quote.request; - let bolt11 = Bolt11Invoice::from_str(&payment_request)?; - - let pay_state = self - .check_outgoing_payment(&bolt11.payment_hash().to_string()) - .await?; - - match pay_state.status { - MeltQuoteState::Unpaid | MeltQuoteState::Unknown | MeltQuoteState::Failed => (), - MeltQuoteState::Paid => { - tracing::debug!("Melt attempted on invoice already paid"); - return Err(Self::Err::InvoiceAlreadyPaid); - } - MeltQuoteState::Pending => { - tracing::debug!("Melt attempted on invoice already pending"); - return Err(Self::Err::InvoicePaymentPending); - } - } - - let bolt11 = Bolt11Invoice::from_str(&payment_request)?; - let amount_msat: u64 = match bolt11.amount_milli_satoshis() { - Some(amount_msat) => amount_msat, - None => melt_quote - .msat_to_pay - .ok_or(Error::UnknownInvoiceAmount)? - .into(), - }; - - // Detect partial payments - match partial_amount { - Some(part_amt) => { - let partial_amount_msat = to_unit(part_amt, &melt_quote.unit, &CurrencyUnit::Msat)?; - let invoice = Bolt11Invoice::from_str(&payment_request)?; - - // Extract information from invoice - let pub_key = invoice.get_payee_pub_key(); - let payer_addr = invoice.payment_secret().0.to_vec(); - let payment_hash = invoice.payment_hash(); - - let mut lnd_client = self.lnd_client.clone(); - - for attempt in 0..Self::MAX_ROUTE_RETRIES { - // Create a request for the routes - let route_req = lnrpc::QueryRoutesRequest { - pub_key: hex::encode(pub_key.serialize()), - amt_msat: u64::from(partial_amount_msat) as i64, - fee_limit: max_fee.map(|f| { - let limit = Limit::Fixed(u64::from(f) as i64); - FeeLimit { limit: Some(limit) } - }), - use_mission_control: true, - ..Default::default() - }; - - // Query the routes - let mut routes_response = lnd_client - .lightning() - .query_routes(route_req) - .await - .map_err(Error::LndError)? - .into_inner(); - - // update its MPP record, - // attempt it and check the result - let last_hop: &mut Hop = routes_response.routes[0] - .hops - .last_mut() - .ok_or(Error::MissingLastHop)?; - let mpp_record = MppRecord { - payment_addr: payer_addr.clone(), - total_amt_msat: amount_msat as i64, - }; - last_hop.mpp_record = Some(mpp_record); + match options { + OutgoingPaymentOptions::Bolt11(bolt11_options) => { + let bolt11 = bolt11_options.bolt11; + + let pay_state = self + .check_outgoing_payment(&PaymentIdentifier::PaymentHash( + *bolt11.payment_hash().as_ref(), + )) + .await?; + + match pay_state.status { + MeltQuoteState::Unpaid | MeltQuoteState::Unknown | MeltQuoteState::Failed => (), + MeltQuoteState::Paid => { + tracing::debug!("Melt attempted on invoice already paid"); + return Err(Self::Err::InvoiceAlreadyPaid); + } + MeltQuoteState::Pending => { + tracing::debug!("Melt attempted on invoice already pending"); + return Err(Self::Err::InvoicePaymentPending); + } + } - let payment_response = lnd_client - .router() - .send_to_route_v2(routerrpc::SendToRouteRequest { - payment_hash: payment_hash.to_byte_array().to_vec(), - route: Some(routes_response.routes[0].clone()), - ..Default::default() - }) - .await - .map_err(Error::LndError)? - .into_inner(); - - if let Some(failure) = payment_response.failure { - if failure.code == 15 { - tracing::debug!( - "Attempt number {}: route has failed. Re-querying...", - attempt + 1 - ); - continue; + // Detect partial payments + match bolt11_options.melt_options { + Some(MeltOptions::Mpp { mpp }) => { + let amount_msat: u64 = bolt11 + .amount_milli_satoshis() + .ok_or(Error::UnknownInvoiceAmount)?; + { + let partial_amount_msat = mpp.amount; + let invoice = bolt11; + let max_fee: Option = bolt11_options.max_fee_amount; + + // Extract information from invoice + let pub_key = invoice.get_payee_pub_key(); + let payer_addr = invoice.payment_secret().0.to_vec(); + let payment_hash = invoice.payment_hash(); + + let mut lnd_client = self.lnd_client.clone(); + + for attempt in 0..Self::MAX_ROUTE_RETRIES { + // Create a request for the routes + let route_req = lnrpc::QueryRoutesRequest { + pub_key: hex::encode(pub_key.serialize()), + amt_msat: u64::from(partial_amount_msat) as i64, + fee_limit: max_fee.map(|f| { + let limit = Limit::Fixed(u64::from(f) as i64); + FeeLimit { limit: Some(limit) } + }), + use_mission_control: true, + ..Default::default() + }; + + // Query the routes + let mut routes_response = lnd_client + .lightning() + .query_routes(route_req) + .await + .map_err(Error::LndError)? + .into_inner(); + + // update its MPP record, + // attempt it and check the result + let last_hop: &mut Hop = routes_response.routes[0] + .hops + .last_mut() + .ok_or(Error::MissingLastHop)?; + let mpp_record = MppRecord { + payment_addr: payer_addr.clone(), + total_amt_msat: amount_msat as i64, + }; + last_hop.mpp_record = Some(mpp_record); + + let payment_response = lnd_client + .router() + .send_to_route_v2(routerrpc::SendToRouteRequest { + payment_hash: payment_hash.to_byte_array().to_vec(), + route: Some(routes_response.routes[0].clone()), + ..Default::default() + }) + .await + .map_err(Error::LndError)? + .into_inner(); + + if let Some(failure) = payment_response.failure { + if failure.code == 15 { + tracing::debug!( + "Attempt number {}: route has failed. Re-querying...", + attempt + 1 + ); + continue; + } + } + + // Get status and maybe the preimage + let (status, payment_preimage) = match payment_response.status { + 0 => (MeltQuoteState::Pending, None), + 1 => ( + MeltQuoteState::Paid, + Some(hex::encode(payment_response.preimage)), + ), + 2 => (MeltQuoteState::Unpaid, None), + _ => (MeltQuoteState::Unknown, None), + }; + + // Get the actual amount paid in sats + let mut total_amt: u64 = 0; + if let Some(route) = payment_response.route { + total_amt = (route.total_amt_msat / 1000) as u64; + } + + return Ok(MakePaymentResponse { + payment_lookup_id: PaymentIdentifier::PaymentHash( + payment_hash.to_byte_array(), + ), + payment_proof: payment_preimage, + status, + total_spent: total_amt.into(), + unit: CurrencyUnit::Sat, + }); + } + + // "We have exhausted all tactical options" -- STEM, Upgrade (2018) + // The payment was not possible within 50 retries. + tracing::error!("Limit of retries reached, payment couldn't succeed."); + Err(Error::PaymentFailed.into()) } } + _ => { + let mut lnd_client = self.lnd_client.clone(); + + let max_fee: Option = bolt11_options.max_fee_amount; + + let amount_msat = u64::from( + bolt11_options + .melt_options + .map(|a| a.amount_msat()) + .unwrap_or_default(), + ); + + let pay_req = lnrpc::SendRequest { + payment_request: bolt11.to_string(), + fee_limit: max_fee.map(|f| { + let limit = Limit::Fixed(u64::from(f) as i64); + FeeLimit { limit: Some(limit) } + }), + amt_msat: amount_msat as i64, + ..Default::default() + }; + + let payment_response = lnd_client + .lightning() + .send_payment_sync(tonic::Request::new(pay_req)) + .await + .map_err(|err| { + tracing::warn!("Lightning payment failed: {}", err); + Error::PaymentFailed + })? + .into_inner(); + + let total_amount = payment_response + .payment_route + .map_or(0, |route| route.total_amt_msat / MSAT_IN_SAT as i64) + as u64; + + let (status, payment_preimage) = match total_amount == 0 { + true => (MeltQuoteState::Unpaid, None), + false => ( + MeltQuoteState::Paid, + Some(hex::encode(payment_response.payment_preimage)), + ), + }; - // Get status and maybe the preimage - let (status, payment_preimage) = match payment_response.status { - 0 => (MeltQuoteState::Pending, None), - 1 => ( - MeltQuoteState::Paid, - Some(hex::encode(payment_response.preimage)), - ), - 2 => (MeltQuoteState::Unpaid, None), - _ => (MeltQuoteState::Unknown, None), - }; + let payment_identifier = + PaymentIdentifier::PaymentHash(*bolt11.payment_hash().as_ref()); - // Get the actual amount paid in sats - let mut total_amt: u64 = 0; - if let Some(route) = payment_response.route { - total_amt = (route.total_amt_msat / 1000) as u64; + Ok(MakePaymentResponse { + payment_lookup_id: payment_identifier, + payment_proof: payment_preimage, + status, + total_spent: total_amount.into(), + unit: CurrencyUnit::Sat, + }) } - - return Ok(MakePaymentResponse { - payment_lookup_id: hex::encode(payment_hash), - payment_proof: payment_preimage, - status, - total_spent: total_amt.into(), - unit: CurrencyUnit::Sat, - }); } - - // "We have exhausted all tactical options" -- STEM, Upgrade (2018) - // The payment was not possible within 50 retries. - tracing::error!("Limit of retries reached, payment couldn't succeed."); - Err(Error::PaymentFailed.into()) } - None => { - let mut lnd_client = self.lnd_client.clone(); - - let pay_req = lnrpc::SendRequest { - payment_request, - fee_limit: max_fee.map(|f| { - let limit = Limit::Fixed(u64::from(f) as i64); - FeeLimit { limit: Some(limit) } - }), - amt_msat: amount_msat as i64, - ..Default::default() - }; - - let payment_response = lnd_client - .lightning() - .send_payment_sync(tonic::Request::new(pay_req)) - .await - .map_err(|err| { - tracing::warn!("Lightning payment failed: {}", err); - Error::PaymentFailed - })? - .into_inner(); - - let total_amount = payment_response - .payment_route - .map_or(0, |route| route.total_amt_msat / MSAT_IN_SAT as i64) - as u64; - - let (status, payment_preimage) = match total_amount == 0 { - true => (MeltQuoteState::Unpaid, None), - false => ( - MeltQuoteState::Paid, - Some(hex::encode(payment_response.payment_preimage)), - ), - }; - - Ok(MakePaymentResponse { - payment_lookup_id: hex::encode(payment_response.payment_hash), - payment_proof: payment_preimage, - status, - total_spent: total_amount.into(), - unit: CurrencyUnit::Sat, - }) + OutgoingPaymentOptions::Bolt12(_) => { + Err(Self::Err::Anyhow(anyhow!("BOLT12 not supported by LND"))) } } } - #[instrument(skip(self, description))] + #[instrument(skip(self, options))] async fn create_incoming_payment_request( &self, - amount: Amount, unit: &CurrencyUnit, - description: String, - unix_expiry: Option, + options: IncomingPaymentOptions, ) -> Result { - let amount = to_unit(amount, unit, &CurrencyUnit::Msat)?; + match options { + IncomingPaymentOptions::Bolt11(bolt11_options) => { + let description = bolt11_options.description.unwrap_or_default(); + let amount = bolt11_options.amount; + let unix_expiry = bolt11_options.unix_expiry; - let invoice_request = lnrpc::Invoice { - value_msat: u64::from(amount) as i64, - memo: description, - ..Default::default() - }; + let amount_msat = to_unit(amount, unit, &CurrencyUnit::Msat)?; - let mut lnd_client = self.lnd_client.clone(); + let invoice_request = lnrpc::Invoice { + value_msat: u64::from(amount_msat) as i64, + memo: description, + ..Default::default() + }; - let invoice = lnd_client - .lightning() - .add_invoice(tonic::Request::new(invoice_request)) - .await - .map_err(|e| payment::Error::Anyhow(anyhow!(e)))? - .into_inner(); + let mut lnd_client = self.lnd_client.clone(); + + let invoice = lnd_client + .lightning() + .add_invoice(tonic::Request::new(invoice_request)) + .await + .map_err(|e| payment::Error::Anyhow(anyhow!(e)))? + .into_inner(); - let bolt11 = Bolt11Invoice::from_str(&invoice.payment_request)?; + let bolt11 = Bolt11Invoice::from_str(&invoice.payment_request)?; - Ok(CreateIncomingPaymentResponse { - request_lookup_id: bolt11.payment_hash().to_string(), - request: bolt11.to_string(), - expiry: unix_expiry, - }) + let payment_identifier = + PaymentIdentifier::PaymentHash(*bolt11.payment_hash().as_ref()); + + Ok(CreateIncomingPaymentResponse { + request_lookup_id: payment_identifier, + request: bolt11.to_string(), + expiry: unix_expiry, + }) + } + IncomingPaymentOptions::Bolt12(_) => { + Err(Self::Err::Anyhow(anyhow!("BOLT12 not supported by LND"))) + } + } } #[instrument(skip(self))] async fn check_incoming_payment_status( &self, - request_lookup_id: &str, - ) -> Result { + payment_identifier: &PaymentIdentifier, + ) -> Result, Self::Err> { let mut lnd_client = self.lnd_client.clone(); let invoice_request = lnrpc::PaymentHash { - r_hash: hex::decode(request_lookup_id).unwrap(), + r_hash: hex::decode(payment_identifier.to_string()).unwrap(), ..Default::default() }; @@ -470,26 +527,27 @@ impl MintPayment for Lnd { .map_err(|e| payment::Error::Anyhow(anyhow!(e)))? .into_inner(); - match invoice.state { - // Open - 0 => Ok(MintQuoteState::Unpaid), - // Settled - 1 => Ok(MintQuoteState::Paid), - // Canceled - 2 => Ok(MintQuoteState::Unpaid), - // Accepted - 3 => Ok(MintQuoteState::Unpaid), - _ => Err(Self::Err::Anyhow(anyhow!("Invalid status"))), + if invoice.state() == InvoiceState::Settled { + Ok(vec![WaitPaymentResponse { + payment_identifier: payment_identifier.clone(), + payment_amount: Amount::from(invoice.amt_paid_msat as u64), + unit: CurrencyUnit::Msat, + payment_id: hex::encode(invoice.r_hash), + }]) + } else { + Ok(vec![]) } } #[instrument(skip(self))] async fn check_outgoing_payment( &self, - payment_hash: &str, + payment_identifier: &PaymentIdentifier, ) -> Result { let mut lnd_client = self.lnd_client.clone(); + let payment_hash = &payment_identifier.to_string(); + let track_request = routerrpc::TrackPaymentRequest { payment_hash: hex::decode(payment_hash).map_err(|_| Error::InvalidHash)?, no_inflight_updates: true, @@ -503,7 +561,7 @@ impl MintPayment for Lnd { let err_code = err.code(); if err_code == tonic::Code::NotFound { return Ok(MakePaymentResponse { - payment_lookup_id: payment_hash.to_string(), + payment_lookup_id: payment_identifier.clone(), payment_proof: None, status: MeltQuoteState::Unknown, total_spent: Amount::ZERO, @@ -522,7 +580,7 @@ impl MintPayment for Lnd { let response = match status { PaymentStatus::Unknown => MakePaymentResponse { - payment_lookup_id: payment_hash.to_string(), + payment_lookup_id: payment_identifier.clone(), payment_proof: Some(update.payment_preimage), status: MeltQuoteState::Unknown, total_spent: Amount::ZERO, @@ -533,7 +591,7 @@ impl MintPayment for Lnd { continue; } PaymentStatus::Succeeded => MakePaymentResponse { - payment_lookup_id: payment_hash.to_string(), + payment_lookup_id: payment_identifier.clone(), payment_proof: Some(update.payment_preimage), status: MeltQuoteState::Paid, total_spent: Amount::from( @@ -546,7 +604,7 @@ impl MintPayment for Lnd { unit: CurrencyUnit::Sat, }, PaymentStatus::Failed => MakePaymentResponse { - payment_lookup_id: payment_hash.to_string(), + payment_lookup_id: payment_identifier.clone(), payment_proof: Some(update.payment_preimage), status: MeltQuoteState::Failed, total_spent: Amount::ZERO, diff --git a/crates/cdk-mint-rpc/Cargo.toml b/crates/cdk-mint-rpc/Cargo.toml index 5b86d9f91..810ac0c0b 100644 --- a/crates/cdk-mint-rpc/Cargo.toml +++ b/crates/cdk-mint-rpc/Cargo.toml @@ -23,6 +23,7 @@ anyhow.workspace = true cdk = { workspace = true, features = [ "mint", ] } +cdk-common = { workspace = true } clap.workspace = true tonic = { workspace = true, features = ["transport"] } tracing.workspace = true diff --git a/crates/cdk-mint-rpc/src/proto/server.rs b/crates/cdk-mint-rpc/src/proto/server.rs index f2c03eb5b..55fe8f2b4 100644 --- a/crates/cdk-mint-rpc/src/proto/server.rs +++ b/crates/cdk-mint-rpc/src/proto/server.rs @@ -3,12 +3,13 @@ use std::path::PathBuf; use std::str::FromStr; use std::sync::Arc; -use cdk::mint::Mint; +use cdk::mint::{Mint, MintQuote}; use cdk::nuts::nut04::MintMethodSettings; use cdk::nuts::nut05::MeltMethodSettings; use cdk::nuts::{CurrencyUnit, MintQuoteState, PaymentMethod}; use cdk::types::QuoteTTL; use cdk::Amount; +use cdk_common::payment::WaitPaymentResponse; use thiserror::Error; use tokio::sync::Notify; use tokio::task::JoinHandle; @@ -650,15 +651,47 @@ impl CdkMint for MintRPCServer { match state { MintQuoteState::Paid => { + // Create a dummy payment response + let response = WaitPaymentResponse { + payment_id: String::new(), + payment_amount: mint_quote.amount_paid(), + unit: mint_quote.unit.clone(), + payment_identifier: mint_quote.request_lookup_id.clone(), + }; + + let mut tx = self + .mint + .localstore + .begin_transaction() + .await + .map_err(|_| Status::internal("Could not start db transaction".to_string()))?; + self.mint - .pay_mint_quote(&mint_quote) + .pay_mint_quote(&mut tx, &mint_quote, response) .await - .map_err(|_| Status::internal("Could not find quote".to_string()))?; + .map_err(|_| Status::internal("Could not process payment".to_string()))?; + + tx.commit() + .await + .map_err(|_| Status::internal("Could not commit db transaction".to_string()))?; } _ => { - let mut mint_quote = mint_quote; - - mint_quote.state = state; + // Create a new quote with the same values + let quote = MintQuote::new( + Some(mint_quote.id), // id + mint_quote.request.clone(), // request + mint_quote.unit.clone(), // unit + mint_quote.amount, // amount + mint_quote.expiry, // expiry + mint_quote.request_lookup_id.clone(), // request_lookup_id + mint_quote.pubkey, // pubkey + mint_quote.amount_issued(), // amount_issued + mint_quote.amount_paid(), // amount_paid + mint_quote.payment_method.clone(), // method + 0, // created_at + vec![], // blinded_messages + vec![], // payment_ids + ); let mut tx = self .mint @@ -666,7 +699,7 @@ impl CdkMint for MintRPCServer { .begin_transaction() .await .map_err(|_| Status::internal("Could not update quote".to_string()))?; - tx.add_or_replace_mint_quote(mint_quote) + tx.add_mint_quote(quote.clone()) .await .map_err(|_| Status::internal("Could not update quote".to_string()))?; tx.commit() @@ -684,7 +717,7 @@ impl CdkMint for MintRPCServer { .ok_or(Status::invalid_argument("Could not find quote".to_string()))?; Ok(Response::new(UpdateNut04QuoteRequest { - state: mint_quote.state.to_string(), + state: mint_quote.state().to_string(), quote_id: mint_quote.id.to_string(), })) } diff --git a/crates/cdk-mintd/src/main.rs b/crates/cdk-mintd/src/main.rs index 36425f1b8..85befcf00 100644 --- a/crates/cdk-mintd/src/main.rs +++ b/crates/cdk-mintd/src/main.rs @@ -431,6 +431,21 @@ async fn configure_backend_for_unit( mint_melt_limits: MintMeltLimits, backend: Arc + Send + Sync>, ) -> Result { + let payment_settings = backend.get_settings().await?; + + if let Some(bolt12) = payment_settings.get("bolt12") { + if bolt12.as_bool().unwrap_or_default() { + mint_builder = mint_builder + .add_ln_backend( + unit.clone(), + PaymentMethod::Bolt12, + mint_melt_limits, + Arc::clone(&backend), + ) + .await?; + } + } + mint_builder = mint_builder .add_ln_backend( unit.clone(), @@ -651,39 +666,6 @@ async fn start_services( let listen_port = settings.info.listen_port; let cache: HttpCache = settings.info.http_cache.clone().into(); - let v1_service = - cdk_axum::create_mint_router_with_custom_cache(Arc::clone(&mint), cache).await?; - - let mut mint_service = Router::new() - .merge(v1_service) - .layer( - ServiceBuilder::new() - .layer(RequestDecompressionLayer::new()) - .layer(CompressionLayer::new()), - ) - .layer(TraceLayer::new_for_http()); - - #[cfg(feature = "swagger")] - { - if settings.info.enable_swagger_ui.unwrap_or(false) { - mint_service = mint_service.merge( - utoipa_swagger_ui::SwaggerUi::new("/swagger-ui") - .url("/api-docs/openapi.json", cdk_axum::ApiDocV1::openapi()), - ); - } - } - - for router in ln_routers { - mint_service = mint_service.merge(router); - } - - let shutdown = Arc::new(Notify::new()); - let mint_clone = Arc::clone(&mint); - tokio::spawn({ - let shutdown = Arc::clone(&shutdown); - async move { mint_clone.wait_for_paid_invoices(shutdown).await } - }); - #[cfg(feature = "management-rpc")] let mut rpc_enabled = false; #[cfg(not(feature = "management-rpc"))] @@ -742,6 +724,47 @@ async fn start_services( mint.set_quote_ttl(QuoteTTL::new(10_000, 10_000)).await?; } + let mint_info = mint.mint_info().await?; + let nut04_methods = mint_info.nuts.nut04.supported_methods(); + let nut05_methods = mint_info.nuts.nut05.supported_methods(); + + let bolt12_supported = nut04_methods.contains(&&PaymentMethod::Bolt12) + || nut05_methods.contains(&&PaymentMethod::Bolt12); + + let v1_service = + cdk_axum::create_mint_router_with_custom_cache(Arc::clone(&mint), cache, bolt12_supported) + .await?; + + let mut mint_service = Router::new() + .merge(v1_service) + .layer( + ServiceBuilder::new() + .layer(RequestDecompressionLayer::new()) + .layer(CompressionLayer::new()), + ) + .layer(TraceLayer::new_for_http()); + + #[cfg(feature = "swagger")] + { + if settings.info.enable_swagger_ui.unwrap_or(false) { + mint_service = mint_service.merge( + utoipa_swagger_ui::SwaggerUi::new("/swagger-ui") + .url("/api-docs/openapi.json", cdk_axum::ApiDocV1::openapi()), + ); + } + } + + for router in ln_routers { + mint_service = mint_service.merge(router); + } + + let shutdown = Arc::new(Notify::new()); + let mint_clone = Arc::clone(&mint); + tokio::spawn({ + let shutdown = Arc::clone(&shutdown); + async move { mint_clone.wait_for_paid_invoices(shutdown).await } + }); + let socket_addr = SocketAddr::from_str(&format!("{listen_addr}:{listen_port}"))?; let listener = tokio::net::TcpListener::bind(socket_addr).await?; diff --git a/crates/cdk-payment-processor/Cargo.toml b/crates/cdk-payment-processor/Cargo.toml index ee3bc4979..605ff211b 100644 --- a/crates/cdk-payment-processor/Cargo.toml +++ b/crates/cdk-payment-processor/Cargo.toml @@ -25,6 +25,7 @@ lnd = ["dep:cdk-lnd"] anyhow.workspace = true async-trait.workspace = true bitcoin.workspace = true +cashu.workspace = true cdk-common = { workspace = true, features = ["mint"] } cdk-cln = { workspace = true, optional = true } cdk-lnd = { workspace = true, optional = true } @@ -34,7 +35,7 @@ thiserror.workspace = true tracing.workspace = true tracing-subscriber.workspace = true lightning-invoice.workspace = true -uuid = { workspace = true, optional = true } +uuid = { workspace = true } utoipa = { workspace = true, optional = true } futures.workspace = true serde_json.workspace = true @@ -43,6 +44,8 @@ tonic = { workspace = true, features = ["router"] } prost.workspace = true tokio-stream.workspace = true tokio-util = { workspace = true, default-features = false } +hex = "0.4" +lightning = { workspace = true } [target.'cfg(not(target_arch = "wasm32"))'.dependencies] diff --git a/crates/cdk-payment-processor/src/error.rs b/crates/cdk-payment-processor/src/error.rs index a4c27251b..6aa90ba03 100644 --- a/crates/cdk-payment-processor/src/error.rs +++ b/crates/cdk-payment-processor/src/error.rs @@ -1,6 +1,7 @@ -//! Errors +//! Error for payment processor use thiserror::Error; +use tonic::Status; /// CDK Payment processor error #[derive(Debug, Error)] @@ -8,13 +9,73 @@ pub enum Error { /// Invalid ID #[error("Invalid id")] InvalidId, + /// Invalid payment identifier + #[error("Invalid payment identifier")] + InvalidPaymentIdentifier, + /// Invalid hash + #[error("Invalid hash")] + InvalidHash, + /// Invalid currency unit + #[error("Invalid currency unit: {0}")] + InvalidCurrencyUnit(String), + /// Parse invoice error + #[error(transparent)] + Invoice(#[from] lightning_invoice::ParseOrSemanticError), + /// Hex decode error + #[error(transparent)] + Hex(#[from] hex::FromHexError), + /// BOLT12 parse error + #[error("BOLT12 parse error")] + Bolt12Parse, /// NUT00 Error #[error(transparent)] NUT00(#[from] cdk_common::nuts::nut00::Error), /// NUT05 error #[error(transparent)] NUT05(#[from] cdk_common::nuts::nut05::Error), - /// Parse invoice error + /// Payment error #[error(transparent)] - Invoice(#[from] lightning_invoice::ParseOrSemanticError), + Payment(#[from] cdk_common::payment::Error), +} + +impl From for Status { + fn from(error: Error) -> Self { + match error { + Error::InvalidId => Status::invalid_argument("Invalid ID"), + Error::InvalidPaymentIdentifier => { + Status::invalid_argument("Invalid payment identifier") + } + Error::InvalidHash => Status::invalid_argument("Invalid hash"), + Error::InvalidCurrencyUnit(unit) => { + Status::invalid_argument(format!("Invalid currency unit: {unit}")) + } + Error::Invoice(err) => Status::invalid_argument(format!("Invoice error: {err}")), + Error::Hex(err) => Status::invalid_argument(format!("Hex decode error: {err}")), + Error::Bolt12Parse => Status::invalid_argument("BOLT12 parse error"), + Error::NUT00(err) => Status::internal(format!("NUT00 error: {err}")), + Error::NUT05(err) => Status::internal(format!("NUT05 error: {err}")), + Error::Payment(err) => Status::internal(format!("Payment error: {err}")), + } + } +} + +impl From for cdk_common::payment::Error { + fn from(error: Error) -> Self { + match error { + Error::InvalidId => Self::Custom("Invalid ID".to_string()), + Error::InvalidPaymentIdentifier => { + Self::Custom("Invalid payment identifier".to_string()) + } + Error::InvalidHash => Self::Custom("Invalid hash".to_string()), + Error::InvalidCurrencyUnit(unit) => { + Self::Custom(format!("Invalid currency unit: {unit}")) + } + Error::Invoice(err) => Self::Custom(format!("Invoice error: {err}")), + Error::Hex(err) => Self::Custom(format!("Hex decode error: {err}")), + Error::Bolt12Parse => Self::Custom("BOLT12 parse error".to_string()), + Error::NUT00(err) => Self::Custom(format!("NUT00 error: {err}")), + Error::NUT05(err) => err.into(), + Error::Payment(err) => err, + } + } } diff --git a/crates/cdk-payment-processor/src/lib.rs b/crates/cdk-payment-processor/src/lib.rs index 89ff00cad..31b39a002 100644 --- a/crates/cdk-payment-processor/src/lib.rs +++ b/crates/cdk-payment-processor/src/lib.rs @@ -3,6 +3,7 @@ #![warn(rustdoc::bare_urls)] pub mod error; +/// Protocol types and functionality for the CDK payment processor pub mod proto; pub use proto::cdk_payment_processor_client::CdkPaymentProcessorClient; diff --git a/crates/cdk-payment-processor/src/proto/client.rs b/crates/cdk-payment-processor/src/proto/client.rs index ab9292aac..58b477ee1 100644 --- a/crates/cdk-payment-processor/src/proto/client.rs +++ b/crates/cdk-payment-processor/src/proto/client.rs @@ -1,15 +1,14 @@ use std::path::PathBuf; use std::pin::Pin; -use std::str::FromStr; use std::sync::atomic::{AtomicBool, Ordering}; use std::sync::Arc; use anyhow::anyhow; use cdk_common::payment::{ - CreateIncomingPaymentResponse, MakePaymentResponse as CdkMakePaymentResponse, MintPayment, - PaymentQuoteResponse, + CreateIncomingPaymentResponse, IncomingPaymentOptions as CdkIncomingPaymentOptions, + MakePaymentResponse as CdkMakePaymentResponse, MintPayment, + PaymentQuoteResponse as CdkPaymentQuoteResponse, WaitPaymentResponse, }; -use cdk_common::{mint, Amount, CurrencyUnit, MeltOptions, MintQuoteState}; use futures::{Stream, StreamExt}; use serde_json::Value; use tokio_util::sync::CancellationToken; @@ -17,10 +16,10 @@ use tonic::transport::{Certificate, Channel, ClientTlsConfig, Identity}; use tonic::{async_trait, Request}; use tracing::instrument; -use super::cdk_payment_processor_client::CdkPaymentProcessorClient; -use super::{ - CheckIncomingPaymentRequest, CheckOutgoingPaymentRequest, CreatePaymentRequest, - MakePaymentRequest, SettingsRequest, WaitIncomingPaymentRequest, +use crate::proto::cdk_payment_processor_client::CdkPaymentProcessorClient; +use crate::proto::{ + CheckIncomingPaymentRequest, CheckOutgoingPaymentRequest, CreatePaymentRequest, EmptyRequest, + IncomingPaymentOptions, MakePaymentRequest, OutgoingPaymentRequestType, PaymentQuoteRequest, }; /// Payment Processor @@ -100,7 +99,7 @@ impl MintPayment for PaymentProcessorClient { async fn get_settings(&self) -> Result { let mut inner = self.inner.clone(); let response = inner - .get_settings(Request::new(SettingsRequest {})) + .get_settings(Request::new(EmptyRequest {})) .await .map_err(|err| { tracing::error!("Could not get settings: {}", err); @@ -115,18 +114,36 @@ impl MintPayment for PaymentProcessorClient { /// Create a new invoice async fn create_incoming_payment_request( &self, - amount: Amount, - unit: &CurrencyUnit, - description: String, - unix_expiry: Option, + unit: &cdk_common::CurrencyUnit, + options: CdkIncomingPaymentOptions, ) -> Result { let mut inner = self.inner.clone(); + + let proto_options = match options { + CdkIncomingPaymentOptions::Bolt11(opts) => IncomingPaymentOptions { + options: Some(super::incoming_payment_options::Options::Bolt11( + super::Bolt11IncomingPaymentOptions { + description: opts.description, + amount: opts.amount.into(), + unix_expiry: opts.unix_expiry, + }, + )), + }, + CdkIncomingPaymentOptions::Bolt12(opts) => IncomingPaymentOptions { + options: Some(super::incoming_payment_options::Options::Bolt12( + super::Bolt12IncomingPaymentOptions { + description: opts.description, + amount: opts.amount.map(Into::into), + unix_expiry: opts.unix_expiry, + }, + )), + }, + }; + let response = inner .create_payment(Request::new(CreatePaymentRequest { - amount: amount.into(), unit: unit.to_string(), - description, - unix_expiry, + options: Some(proto_options), })) .await .map_err(|err| { @@ -143,16 +160,36 @@ impl MintPayment for PaymentProcessorClient { async fn get_payment_quote( &self, - request: &str, - unit: &CurrencyUnit, - options: Option, - ) -> Result { + unit: &cdk_common::CurrencyUnit, + options: cdk_common::payment::OutgoingPaymentOptions, + ) -> Result { let mut inner = self.inner.clone(); + + let request_type = match &options { + cdk_common::payment::OutgoingPaymentOptions::Bolt11(_) => { + OutgoingPaymentRequestType::Bolt11Invoice + } + cdk_common::payment::OutgoingPaymentOptions::Bolt12(_) => { + OutgoingPaymentRequestType::Bolt12Offer + } + }; + + let proto_request = match &options { + cdk_common::payment::OutgoingPaymentOptions::Bolt11(opts) => opts.bolt11.to_string(), + cdk_common::payment::OutgoingPaymentOptions::Bolt12(opts) => opts.offer.to_string(), + }; + + let proto_options = match &options { + cdk_common::payment::OutgoingPaymentOptions::Bolt11(opts) => opts.melt_options, + cdk_common::payment::OutgoingPaymentOptions::Bolt12(opts) => opts.melt_options, + }; + let response = inner - .get_payment_quote(Request::new(super::PaymentQuoteRequest { - request: request.to_string(), + .get_payment_quote(Request::new(PaymentQuoteRequest { + request: proto_request, unit: unit.to_string(), - options: options.map(|o| o.into()), + options: proto_options.map(Into::into), + request_type: request_type.into(), })) .await .map_err(|err| { @@ -167,16 +204,44 @@ impl MintPayment for PaymentProcessorClient { async fn make_payment( &self, - melt_quote: mint::MeltQuote, - partial_amount: Option, - max_fee_amount: Option, + _unit: &cdk_common::CurrencyUnit, + options: cdk_common::payment::OutgoingPaymentOptions, ) -> Result { let mut inner = self.inner.clone(); + + let payment_options = match options { + cdk_common::payment::OutgoingPaymentOptions::Bolt11(opts) => { + super::OutgoingPaymentVariant { + options: Some(super::outgoing_payment_variant::Options::Bolt11( + super::Bolt11OutgoingPaymentOptions { + bolt11: opts.bolt11.to_string(), + max_fee_amount: opts.max_fee_amount.map(Into::into), + timeout_secs: opts.timeout_secs, + melt_options: opts.melt_options.map(Into::into), + }, + )), + } + } + cdk_common::payment::OutgoingPaymentOptions::Bolt12(opts) => { + super::OutgoingPaymentVariant { + options: Some(super::outgoing_payment_variant::Options::Bolt12( + super::Bolt12OutgoingPaymentOptions { + offer: opts.offer.to_string(), + max_fee_amount: opts.max_fee_amount.map(Into::into), + timeout_secs: opts.timeout_secs, + invoice: opts.invoice, + melt_options: opts.melt_options.map(Into::into), + }, + )), + } + } + }; + let response = inner .make_payment(Request::new(MakePaymentRequest { - melt_quote: Some(melt_quote.into()), - partial_amount: partial_amount.map(|a| a.into()), - max_fee_amount: max_fee_amount.map(|a| a.into()), + payment_options: Some(payment_options), + partial_amount: None, + max_fee_amount: None, })) .await .map_err(|err| { @@ -198,17 +263,16 @@ impl MintPayment for PaymentProcessorClient { })?) } - /// Listen for invoices to be paid to the mint #[instrument(skip_all)] async fn wait_any_incoming_payment( &self, - ) -> Result + Send>>, Self::Err> { + ) -> Result + Send>>, Self::Err> { self.wait_incoming_payment_stream_is_active .store(true, Ordering::SeqCst); tracing::debug!("Client waiting for payment"); let mut inner = self.inner.clone(); let stream = inner - .wait_incoming_payment(WaitIncomingPaymentRequest {}) + .wait_incoming_payment(EmptyRequest {}) .await .map_err(|err| { tracing::error!("Could not check incoming payment stream: {}", err); @@ -222,15 +286,18 @@ impl MintPayment for PaymentProcessorClient { let transformed_stream = stream .take_until(cancel_fut) - .filter_map(|item| async move { + .filter_map(|item| async { match item { - Ok(value) => { - tracing::warn!("{}", value.lookup_id); - Some(value.lookup_id) - } + Ok(value) => match value.try_into() { + Ok(payment_response) => Some(payment_response), + Err(e) => { + tracing::error!("Error converting payment response: {}", e); + None + } + }, Err(e) => { tracing::error!("Error in payment stream: {}", e); - None // Skip this item and continue with the stream + None } } }) @@ -255,12 +322,12 @@ impl MintPayment for PaymentProcessorClient { async fn check_incoming_payment_status( &self, - request_lookup_id: &str, - ) -> Result { + payment_identifier: &cdk_common::payment::PaymentIdentifier, + ) -> Result, Self::Err> { let mut inner = self.inner.clone(); let response = inner .check_incoming_payment(Request::new(CheckIncomingPaymentRequest { - request_lookup_id: request_lookup_id.to_string(), + request_identifier: Some(payment_identifier.clone().into()), })) .await .map_err(|err| { @@ -269,20 +336,21 @@ impl MintPayment for PaymentProcessorClient { })?; let check_incoming = response.into_inner(); - - let status = check_incoming.status().as_str_name(); - - Ok(MintQuoteState::from_str(status)?) + check_incoming + .payments + .into_iter() + .map(|resp| resp.try_into().map_err(Self::Err::from)) + .collect() } async fn check_outgoing_payment( &self, - request_lookup_id: &str, + payment_identifier: &cdk_common::payment::PaymentIdentifier, ) -> Result { let mut inner = self.inner.clone(); let response = inner .check_outgoing_payment(Request::new(CheckOutgoingPaymentRequest { - request_lookup_id: request_lookup_id.to_string(), + request_identifier: Some(payment_identifier.clone().into()), })) .await .map_err(|err| { diff --git a/crates/cdk-payment-processor/src/proto/mod.rs b/crates/cdk-payment-processor/src/proto/mod.rs index 95c6e8199..d7788a144 100644 --- a/crates/cdk-payment-processor/src/proto/mod.rs +++ b/crates/cdk-payment-processor/src/proto/mod.rs @@ -1,12 +1,11 @@ -//! Proto types for payment processor - use std::str::FromStr; use cdk_common::payment::{ CreateIncomingPaymentResponse, MakePaymentResponse as CdkMakePaymentResponse, + PaymentIdentifier as CdkPaymentIdentifier, WaitPaymentResponse, }; -use cdk_common::{Bolt11Invoice, CurrencyUnit, MeltQuoteBolt11Request}; -use melt_options::Options; +use cdk_common::{CurrencyUnit, MeltOptions as CdkMeltOptions}; + mod client; mod server; @@ -15,15 +14,85 @@ pub use server::PaymentProcessorServer; tonic::include_proto!("cdk_payment_processor"); +impl From for PaymentIdentifier { + fn from(value: CdkPaymentIdentifier) -> Self { + match value { + CdkPaymentIdentifier::Label(id) => Self { + r#type: PaymentIdentifierType::Label.into(), + value: Some(payment_identifier::Value::Id(id)), + }, + CdkPaymentIdentifier::OfferId(id) => Self { + r#type: PaymentIdentifierType::OfferId.into(), + value: Some(payment_identifier::Value::Id(id)), + }, + CdkPaymentIdentifier::PaymentHash(hash) => Self { + r#type: PaymentIdentifierType::PaymentHash.into(), + value: Some(payment_identifier::Value::Hash(hex::encode(hash))), + }, + CdkPaymentIdentifier::Bolt12PaymentHash(hash) => Self { + r#type: PaymentIdentifierType::Bolt12PaymentHash.into(), + value: Some(payment_identifier::Value::Hash(hex::encode(hash))), + }, + CdkPaymentIdentifier::CustomId(id) => Self { + r#type: PaymentIdentifierType::CustomId.into(), + value: Some(payment_identifier::Value::Id(id)), + }, + } + } +} + +impl TryFrom for CdkPaymentIdentifier { + type Error = crate::error::Error; + + fn try_from(value: PaymentIdentifier) -> Result { + match (value.r#type(), value.value) { + (PaymentIdentifierType::Label, Some(payment_identifier::Value::Id(id))) => { + Ok(CdkPaymentIdentifier::Label(id)) + } + (PaymentIdentifierType::OfferId, Some(payment_identifier::Value::Id(id))) => { + Ok(CdkPaymentIdentifier::OfferId(id)) + } + (PaymentIdentifierType::PaymentHash, Some(payment_identifier::Value::Hash(hash))) => { + let decoded = hex::decode(hash)?; + let hash_array: [u8; 32] = decoded + .try_into() + .map_err(|_| crate::error::Error::InvalidHash)?; + Ok(CdkPaymentIdentifier::PaymentHash(hash_array)) + } + ( + PaymentIdentifierType::Bolt12PaymentHash, + Some(payment_identifier::Value::Hash(hash)), + ) => { + let decoded = hex::decode(hash)?; + let hash_array: [u8; 32] = decoded + .try_into() + .map_err(|_| crate::error::Error::InvalidHash)?; + Ok(CdkPaymentIdentifier::Bolt12PaymentHash(hash_array)) + } + (PaymentIdentifierType::CustomId, Some(payment_identifier::Value::Id(id))) => { + Ok(CdkPaymentIdentifier::CustomId(id)) + } + _ => Err(crate::error::Error::InvalidPaymentIdentifier), + } + } +} + impl TryFrom for CdkMakePaymentResponse { type Error = crate::error::Error; fn try_from(value: MakePaymentResponse) -> Result { + let status = value.status().as_str_name().parse()?; + let payment_proof = value.payment_proof; + let total_spent = value.total_spent.into(); + let unit = CurrencyUnit::from_str(&value.unit)?; + let payment_identifier = value + .payment_identifier + .ok_or(crate::error::Error::InvalidPaymentIdentifier)?; Ok(Self { - payment_lookup_id: value.payment_lookup_id.clone(), - payment_proof: value.payment_proof.clone(), - status: value.status().as_str_name().parse()?, - total_spent: value.total_spent.into(), - unit: value.unit.parse()?, + payment_lookup_id: payment_identifier.try_into()?, + payment_proof, + status, + total_spent, + unit, }) } } @@ -31,8 +100,8 @@ impl TryFrom for CdkMakePaymentResponse { impl From for MakePaymentResponse { fn from(value: CdkMakePaymentResponse) -> Self { Self { - payment_lookup_id: value.payment_lookup_id.clone(), - payment_proof: value.payment_proof.clone(), + payment_identifier: Some(value.payment_lookup_id.into()), + payment_proof: value.payment_proof, status: QuoteState::from(value.status).into(), total_spent: value.total_spent.into(), unit: value.unit.to_string(), @@ -43,8 +112,8 @@ impl From for MakePaymentResponse { impl From for CreatePaymentResponse { fn from(value: CreateIncomingPaymentResponse) -> Self { Self { - request_lookup_id: value.request_lookup_id, - request: value.request.to_string(), + request_identifier: Some(value.request_lookup_id.into()), + request: value.request, expiry: value.expiry, } } @@ -54,82 +123,102 @@ impl TryFrom for CreateIncomingPaymentResponse { type Error = crate::error::Error; fn try_from(value: CreatePaymentResponse) -> Result { + let request_identifier = value + .request_identifier + .ok_or(crate::error::Error::InvalidPaymentIdentifier)?; Ok(Self { - request_lookup_id: value.request_lookup_id, + request_lookup_id: request_identifier.try_into()?, request: value.request, expiry: value.expiry, }) } } -impl From<&MeltQuoteBolt11Request> for PaymentQuoteRequest { - fn from(value: &MeltQuoteBolt11Request) -> Self { - Self { - request: value.request.to_string(), - unit: value.unit.to_string(), - options: value.options.map(|o| o.into()), - } - } -} - impl From for PaymentQuoteResponse { fn from(value: cdk_common::payment::PaymentQuoteResponse) -> Self { Self { - request_lookup_id: value.request_lookup_id, + request_identifier: Some(value.request_lookup_id.into()), amount: value.amount.into(), fee: value.fee.into(), - state: QuoteState::from(value.state).into(), unit: value.unit.to_string(), + state: QuoteState::from(value.state).into(), + melt_options: value.options.map(|opt| match opt { + cdk_common::payment::PaymentQuoteOptions::Bolt12 { invoice } => { + PaymentQuoteOptions { + melt_options: Some(payment_quote_options::MeltOptions::Bolt12( + Bolt12Options { + invoice: invoice.map(String::from_utf8).and_then(|r| r.ok()), + }, + )), + } + } + }), } } } -impl From for MeltOptions { - fn from(value: cdk_common::nut23::MeltOptions) -> Self { - Self { - options: Some(value.into()), - } - } -} +impl From for cdk_common::payment::PaymentQuoteResponse { + fn from(value: PaymentQuoteResponse) -> Self { + let state_val = value.state(); + let request_identifier = value + .request_identifier + .expect("request identifier required"); -impl From for Options { - fn from(value: cdk_common::nut23::MeltOptions) -> Self { - match value { - cdk_common::MeltOptions::Mpp { mpp } => Self::Mpp(Mpp { - amount: mpp.amount.into(), - }), - cdk_common::MeltOptions::Amountless { amountless } => Self::Amountless(Amountless { - amount_msat: amountless.amount_msat.into(), + Self { + request_lookup_id: request_identifier + .try_into() + .expect("valid request identifier"), + amount: value.amount.into(), + fee: value.fee.into(), + unit: CurrencyUnit::from_str(&value.unit).unwrap_or_default(), + state: state_val.into(), + options: value.melt_options.map(|opt| match opt.melt_options { + Some(payment_quote_options::MeltOptions::Bolt12(bolt12)) => { + cdk_common::payment::PaymentQuoteOptions::Bolt12 { + invoice: bolt12.invoice.as_deref().map(str::as_bytes).map(Vec::from), + } + } + None => unreachable!(), }), } } } -impl From for cdk_common::nut23::MeltOptions { +impl From for CdkMeltOptions { fn from(value: MeltOptions) -> Self { - let options = value.options.expect("option defined"); - match options { - Options::Mpp(mpp) => cdk_common::MeltOptions::new_mpp(mpp.amount), - Options::Amountless(amountless) => { - cdk_common::MeltOptions::new_amountless(amountless.amount_msat) - } + match value.options.expect("option defined") { + melt_options::Options::Mpp(mpp) => Self::Mpp { + mpp: cashu::nuts::nut15::Mpp { + amount: mpp.amount.into(), + }, + }, + melt_options::Options::Amountless(amountless) => Self::Amountless { + amountless: cashu::nuts::nut23::Amountless { + amount_msat: amountless.amount_msat.into(), + }, + }, } } } -impl From for cdk_common::payment::PaymentQuoteResponse { - fn from(value: PaymentQuoteResponse) -> Self { - Self { - request_lookup_id: value.request_lookup_id.clone(), - amount: value.amount.into(), - unit: CurrencyUnit::from_str(&value.unit).unwrap_or_default(), - fee: value.fee.into(), - state: value.state().into(), +impl From for MeltOptions { + fn from(value: CdkMeltOptions) -> Self { + match value { + CdkMeltOptions::Mpp { mpp } => Self { + options: Some(melt_options::Options::Mpp(Mpp { + amount: mpp.amount.into(), + })), + }, + CdkMeltOptions::Amountless { amountless } => Self { + options: Some(melt_options::Options::Amountless(Amountless { + amount_msat: amountless.amount_msat.into(), + })), + }, } } } -impl From for cdk_common::nut05::QuoteState { +impl From for cdk_common::nuts::MeltQuoteState { fn from(value: QuoteState) -> Self { match value { QuoteState::Unpaid => Self::Unpaid, @@ -142,80 +231,53 @@ impl From for cdk_common::nut05::QuoteState { } } -impl From for QuoteState { - fn from(value: cdk_common::nut05::QuoteState) -> Self { +impl From for QuoteState { + fn from(value: cdk_common::nuts::MeltQuoteState) -> Self { match value { - cdk_common::MeltQuoteState::Unpaid => Self::Unpaid, - cdk_common::MeltQuoteState::Paid => Self::Paid, - cdk_common::MeltQuoteState::Pending => Self::Pending, - cdk_common::MeltQuoteState::Unknown => Self::Unknown, - cdk_common::MeltQuoteState::Failed => Self::Failed, + cdk_common::nuts::MeltQuoteState::Unpaid => Self::Unpaid, + cdk_common::nuts::MeltQuoteState::Paid => Self::Paid, + cdk_common::nuts::MeltQuoteState::Pending => Self::Pending, + cdk_common::nuts::MeltQuoteState::Unknown => Self::Unknown, + cdk_common::nuts::MeltQuoteState::Failed => Self::Failed, } } } -impl From for QuoteState { - fn from(value: cdk_common::nut23::QuoteState) -> Self { +impl From for QuoteState { + fn from(value: cdk_common::nuts::MintQuoteState) -> Self { match value { - cdk_common::MintQuoteState::Unpaid => Self::Unpaid, - cdk_common::MintQuoteState::Paid => Self::Paid, - cdk_common::MintQuoteState::Pending => Self::Pending, - cdk_common::MintQuoteState::Issued => Self::Issued, + cdk_common::nuts::MintQuoteState::Unpaid => Self::Unpaid, + cdk_common::nuts::MintQuoteState::Paid => Self::Paid, + cdk_common::nuts::MintQuoteState::Issued => Self::Issued, } } } -impl From for MeltQuote { - fn from(value: cdk_common::mint::MeltQuote) -> Self { +impl From for WaitIncomingPaymentResponse { + fn from(value: WaitPaymentResponse) -> Self { Self { - id: value.id.to_string(), + payment_identifier: Some(value.payment_identifier.into()), + payment_amount: value.payment_amount.into(), unit: value.unit.to_string(), - amount: value.amount.into(), - request: value.request, - fee_reserve: value.fee_reserve.into(), - state: QuoteState::from(value.state).into(), - expiry: value.expiry, - payment_preimage: value.payment_preimage, - request_lookup_id: value.request_lookup_id, - msat_to_pay: value.msat_to_pay.map(|a| a.into()), - created_time: value.created_time, - paid_time: value.paid_time, + payment_id: value.payment_id, } } } -impl TryFrom for cdk_common::mint::MeltQuote { +impl TryFrom for WaitPaymentResponse { type Error = crate::error::Error; - fn try_from(value: MeltQuote) -> Result { - Ok(Self { - id: value - .id - .parse() - .map_err(|_| crate::error::Error::InvalidId)?, - unit: value.unit.parse()?, - amount: value.amount.into(), - request: value.request.clone(), - fee_reserve: value.fee_reserve.into(), - state: cdk_common::nut05::QuoteState::from(value.state()), - expiry: value.expiry, - payment_preimage: value.payment_preimage, - request_lookup_id: value.request_lookup_id, - msat_to_pay: value.msat_to_pay.map(|a| a.into()), - created_time: value.created_time, - paid_time: value.paid_time, - }) - } -} - -impl TryFrom for MeltQuoteBolt11Request { - type Error = crate::error::Error; + fn try_from(value: WaitIncomingPaymentResponse) -> Result { + let payment_identifier = value + .payment_identifier + .ok_or(crate::error::Error::InvalidPaymentIdentifier)? + .try_into()?; - fn try_from(value: PaymentQuoteRequest) -> Result { Ok(Self { - request: Bolt11Invoice::from_str(&value.request)?, + payment_identifier, + payment_amount: value.payment_amount.into(), unit: CurrencyUnit::from_str(&value.unit)?, - options: value.options.map(|o| o.into()), + payment_id: value.payment_id, }) } } diff --git a/crates/cdk-payment-processor/src/proto/payment_processor.proto b/crates/cdk-payment-processor/src/proto/payment_processor.proto index 94a6021c5..7a32187de 100644 --- a/crates/cdk-payment-processor/src/proto/payment_processor.proto +++ b/crates/cdk-payment-processor/src/proto/payment_processor.proto @@ -3,30 +3,73 @@ syntax = "proto3"; package cdk_payment_processor; service CdkPaymentProcessor { - rpc GetSettings(SettingsRequest) returns (SettingsResponse) {} + rpc GetSettings(EmptyRequest) returns (SettingsResponse) {} rpc CreatePayment(CreatePaymentRequest) returns (CreatePaymentResponse) {} rpc GetPaymentQuote(PaymentQuoteRequest) returns (PaymentQuoteResponse) {} rpc MakePayment(MakePaymentRequest) returns (MakePaymentResponse) {} rpc CheckIncomingPayment(CheckIncomingPaymentRequest) returns (CheckIncomingPaymentResponse) {} rpc CheckOutgoingPayment(CheckOutgoingPaymentRequest) returns (MakePaymentResponse) {} - rpc WaitIncomingPayment(WaitIncomingPaymentRequest) returns (stream WaitIncomingPaymentResponse) {} + rpc WaitIncomingPayment(EmptyRequest) returns (stream WaitIncomingPaymentResponse) {} } -message SettingsRequest {} +message EmptyRequest {} message SettingsResponse { string inner = 1; } +message Bolt11IncomingPaymentOptions { + optional string description = 1; + uint64 amount = 2; + optional uint64 unix_expiry = 3; +} + +message Bolt12IncomingPaymentOptions { + optional string description = 1; + optional uint64 amount = 2; + optional uint64 unix_expiry = 3; +} + +enum PaymentMethodType { + BOLT11 = 0; + BOLT12 = 1; +} + +enum OutgoingPaymentRequestType { + BOLT11_INVOICE = 0; + BOLT12_OFFER = 1; +} + +enum PaymentIdentifierType { + PAYMENT_HASH = 0; + OFFER_ID = 1; + LABEL = 2; + BOLT12_PAYMENT_HASH = 3; + CUSTOM_ID = 4; +} + +message PaymentIdentifier { + PaymentIdentifierType type = 1; + oneof value { + string hash = 2; // Used for PAYMENT_HASH and BOLT12_PAYMENT_HASH + string id = 3; // Used for OFFER_ID, LABEL, and CUSTOM_ID + } +} + +message IncomingPaymentOptions { + oneof options { + Bolt11IncomingPaymentOptions bolt11 = 1; + Bolt12IncomingPaymentOptions bolt12 = 2; + } +} + message CreatePaymentRequest { - uint64 amount = 1; - string unit = 2; - string description = 3; - optional uint64 unix_expiry = 4; + string unit = 1; + IncomingPaymentOptions options = 2; } message CreatePaymentResponse { - string request_lookup_id = 1; + PaymentIdentifier request_identifier = 1; string request = 2; optional uint64 expiry = 3; } @@ -35,7 +78,6 @@ message Mpp { uint64 amount = 1; } - message Amountless { uint64 amount_msat = 1; } @@ -51,6 +93,7 @@ message PaymentQuoteRequest { string request = 1; string unit = 2; optional MeltOptions options = 3; + OutgoingPaymentRequestType request_type = 4; } enum QuoteState { @@ -62,38 +105,60 @@ enum QuoteState { ISSUED = 5; } +message Bolt12Options { + optional string invoice = 1; +} + +message PaymentQuoteOptions { + oneof melt_options { + Bolt12Options bolt12 = 1; + } +} message PaymentQuoteResponse { - string request_lookup_id = 1; + PaymentIdentifier request_identifier = 1; uint64 amount = 2; uint64 fee = 3; QuoteState state = 4; - string unit = 5; + optional PaymentQuoteOptions melt_options = 5; + string unit = 6; +} + +message Bolt11OutgoingPaymentOptions { + string bolt11 = 1; + optional uint64 max_fee_amount = 2; + optional uint64 timeout_secs = 3; + optional MeltOptions melt_options = 4; } -message MeltQuote { - string id = 1; - string unit = 2; - uint64 amount = 3; - string request = 4; - uint64 fee_reserve = 5; - QuoteState state = 6; - uint64 expiry = 7; - optional string payment_preimage = 8; - string request_lookup_id = 9; - optional uint64 msat_to_pay = 10; - uint64 created_time = 11; - optional uint64 paid_time = 12; +message Bolt12OutgoingPaymentOptions { + string offer = 1; + optional uint64 max_fee_amount = 2; + optional uint64 timeout_secs = 3; + optional bytes invoice = 4; + optional MeltOptions melt_options = 5; +} + +enum OutgoingPaymentOptionsType { + OUTGOING_BOLT11 = 0; + OUTGOING_BOLT12 = 1; +} + +message OutgoingPaymentVariant { + oneof options { + Bolt11OutgoingPaymentOptions bolt11 = 1; + Bolt12OutgoingPaymentOptions bolt12 = 2; + } } message MakePaymentRequest { - MeltQuote melt_quote = 1; + OutgoingPaymentVariant payment_options = 1; optional uint64 partial_amount = 2; optional uint64 max_fee_amount = 3; } message MakePaymentResponse { - string payment_lookup_id = 1; + PaymentIdentifier payment_identifier = 1; optional string payment_proof = 2; QuoteState status = 3; uint64 total_spent = 4; @@ -101,22 +166,20 @@ message MakePaymentResponse { } message CheckIncomingPaymentRequest { - string request_lookup_id = 1; + PaymentIdentifier request_identifier = 1; } message CheckIncomingPaymentResponse { - QuoteState status = 1; + repeated WaitIncomingPaymentResponse payments = 1; } message CheckOutgoingPaymentRequest { - string request_lookup_id = 1; + PaymentIdentifier request_identifier = 1; } - -message WaitIncomingPaymentRequest { -} - - message WaitIncomingPaymentResponse { - string lookup_id = 1; + PaymentIdentifier payment_identifier = 1; + uint64 payment_amount = 2; + string unit = 3; + string payment_id = 4; } diff --git a/crates/cdk-payment-processor/src/proto/server.rs b/crates/cdk-payment-processor/src/proto/server.rs index 823b73c3a..d983cf447 100644 --- a/crates/cdk-payment-processor/src/proto/server.rs +++ b/crates/cdk-payment-processor/src/proto/server.rs @@ -5,8 +5,10 @@ use std::str::FromStr; use std::sync::Arc; use std::time::Duration; -use cdk_common::payment::MintPayment; +use cdk_common::payment::{IncomingPaymentOptions, MintPayment}; +use cdk_common::CurrencyUnit; use futures::{Stream, StreamExt}; +use lightning::offers::offer::Offer; use serde_json::Value; use tokio::sync::{mpsc, Notify}; use tokio::task::JoinHandle; @@ -17,6 +19,7 @@ use tonic::{async_trait, Request, Response, Status}; use tracing::instrument; use super::cdk_payment_processor_server::{CdkPaymentProcessor, CdkPaymentProcessorServer}; +use crate::error::Error; use crate::proto::*; type ResponseStream = @@ -162,7 +165,7 @@ impl Drop for PaymentProcessorServer { impl CdkPaymentProcessor for PaymentProcessorServer { async fn get_settings( &self, - _request: Request, + _request: Request, ) -> Result, Status> { let settings: Value = self .inner @@ -179,18 +182,36 @@ impl CdkPaymentProcessor for PaymentProcessorServer { &self, request: Request, ) -> Result, Status> { - let CreatePaymentRequest { - amount, - unit, - description, - unix_expiry, - } = request.into_inner(); - - let unit = - CurrencyUnit::from_str(&unit).map_err(|_| Status::invalid_argument("Invalid unit"))?; + let CreatePaymentRequest { unit, options } = request.into_inner(); + + let unit = CurrencyUnit::from_str(&unit) + .map_err(|_| Status::invalid_argument("Invalid currency unit"))?; + + let options = options.ok_or_else(|| Status::invalid_argument("Missing payment options"))?; + + let proto_options = match options + .options + .ok_or_else(|| Status::invalid_argument("Missing options"))? + { + incoming_payment_options::Options::Bolt11(opts) => { + IncomingPaymentOptions::Bolt11(cdk_common::payment::Bolt11IncomingPaymentOptions { + description: opts.description, + amount: opts.amount.into(), + unix_expiry: opts.unix_expiry, + }) + } + incoming_payment_options::Options::Bolt12(opts) => IncomingPaymentOptions::Bolt12( + Box::new(cdk_common::payment::Bolt12IncomingPaymentOptions { + description: opts.description, + amount: opts.amount.map(Into::into), + unix_expiry: opts.unix_expiry, + }), + ), + }; + let invoice_response = self .inner - .create_incoming_payment_request(amount.into(), &unit, description, unix_expiry) + .create_incoming_payment_request(&unit, proto_options) .await .map_err(|_| Status::internal("Could not create invoice"))?; @@ -203,21 +224,46 @@ impl CdkPaymentProcessor for PaymentProcessorServer { ) -> Result, Status> { let request = request.into_inner(); - let options: Option = - request.options.as_ref().map(|options| (*options).into()); + let unit = CurrencyUnit::from_str(&request.unit) + .map_err(|_| Status::invalid_argument("Invalid currency unit"))?; + + let options = match request.request_type() { + OutgoingPaymentRequestType::Bolt11Invoice => { + let bolt11: cdk_common::Bolt11Invoice = + request.request.parse().map_err(Error::Invoice)?; + + cdk_common::payment::OutgoingPaymentOptions::Bolt11(Box::new( + cdk_common::payment::Bolt11OutgoingPaymentOptions { + bolt11, + max_fee_amount: None, + timeout_secs: None, + melt_options: request.options.map(Into::into), + }, + )) + } + OutgoingPaymentRequestType::Bolt12Offer => { + // Parse offer to verify it's valid, but store as string + let _: Offer = request.request.parse().map_err(|_| Error::Bolt12Parse)?; + + cdk_common::payment::OutgoingPaymentOptions::Bolt12(Box::new( + cdk_common::payment::Bolt12OutgoingPaymentOptions { + offer: Offer::from_str(&request.request).unwrap(), + max_fee_amount: None, + timeout_secs: None, + invoice: None, + melt_options: request.options.map(Into::into), + }, + )) + } + }; let payment_quote = self .inner - .get_payment_quote( - &request.request, - &CurrencyUnit::from_str(&request.unit) - .map_err(|_| Status::invalid_argument("Invalid currency unit"))?, - options, - ) + .get_payment_quote(&unit, options) .await .map_err(|err| { - tracing::error!("Could not get bolt11 melt quote: {}", err); - Status::internal("Could not get melt quote") + tracing::error!("Could not get payment quote: {}", err); + Status::internal("Could not get quote") })?; Ok(Response::new(payment_quote.into())) @@ -229,17 +275,51 @@ impl CdkPaymentProcessor for PaymentProcessorServer { ) -> Result, Status> { let request = request.into_inner(); - let pay_invoice = self + let options = request + .payment_options + .ok_or_else(|| Status::invalid_argument("Missing payment options"))?; + + let (unit, payment_options) = match options + .options + .ok_or_else(|| Status::invalid_argument("Missing options"))? + { + outgoing_payment_variant::Options::Bolt11(opts) => { + let bolt11: cdk_common::Bolt11Invoice = + opts.bolt11.parse().map_err(Error::Invoice)?; + + let payment_options = cdk_common::payment::OutgoingPaymentOptions::Bolt11( + Box::new(cdk_common::payment::Bolt11OutgoingPaymentOptions { + bolt11, + max_fee_amount: opts.max_fee_amount.map(Into::into), + timeout_secs: opts.timeout_secs, + melt_options: opts.melt_options.map(Into::into), + }), + ); + + (CurrencyUnit::Msat, payment_options) + } + outgoing_payment_variant::Options::Bolt12(opts) => { + let offer = Offer::from_str(&opts.offer) + .map_err(|_| Error::Bolt12Parse) + .unwrap(); + + let payment_options = cdk_common::payment::OutgoingPaymentOptions::Bolt12( + Box::new(cdk_common::payment::Bolt12OutgoingPaymentOptions { + offer, + max_fee_amount: opts.max_fee_amount.map(Into::into), + timeout_secs: opts.timeout_secs, + invoice: opts.invoice, + melt_options: opts.melt_options.map(Into::into), + }), + ); + + (CurrencyUnit::Msat, payment_options) + } + }; + + let pay_response = self .inner - .make_payment( - request - .melt_quote - .ok_or(Status::invalid_argument("Meltquote is required"))? - .try_into() - .map_err(|_err| Status::invalid_argument("Invalid melt quote"))?, - request.partial_amount.map(|a| a.into()), - request.max_fee_amount.map(|a| a.into()), - ) + .make_payment(&unit, payment_options) .await .map_err(|err| { tracing::error!("Could not make payment: {}", err); @@ -255,7 +335,7 @@ impl CdkPaymentProcessor for PaymentProcessorServer { } })?; - Ok(Response::new(pay_invoice.into())) + Ok(Response::new(pay_response.into())) } async fn check_incoming_payment( @@ -264,14 +344,20 @@ impl CdkPaymentProcessor for PaymentProcessorServer { ) -> Result, Status> { let request = request.into_inner(); - let check_response = self + let payment_identifier = request + .request_identifier + .ok_or_else(|| Status::invalid_argument("Missing request identifier"))? + .try_into() + .map_err(|_| Status::invalid_argument("Invalid request identifier"))?; + + let check_responses = self .inner - .check_incoming_payment_status(&request.request_lookup_id) + .check_incoming_payment_status(&payment_identifier) .await .map_err(|_| Status::internal("Could not check incoming payment status"))?; Ok(Response::new(CheckIncomingPaymentResponse { - status: QuoteState::from(check_response).into(), + payments: check_responses.into_iter().map(|r| r.into()).collect(), })) } @@ -281,23 +367,28 @@ impl CdkPaymentProcessor for PaymentProcessorServer { ) -> Result, Status> { let request = request.into_inner(); + let payment_identifier = request + .request_identifier + .ok_or_else(|| Status::invalid_argument("Missing request identifier"))? + .try_into() + .map_err(|_| Status::invalid_argument("Invalid request identifier"))?; + let check_response = self .inner - .check_outgoing_payment(&request.request_lookup_id) + .check_outgoing_payment(&payment_identifier) .await - .map_err(|_| Status::internal("Could not check incoming payment status"))?; + .map_err(|_| Status::internal("Could not check outgoing payment status"))?; Ok(Response::new(check_response.into())) } type WaitIncomingPaymentStream = ResponseStream; - // Clippy thinks select is not stable but it compiles fine on MSRV (1.63.0) #[allow(clippy::incompatible_msrv)] #[instrument(skip_all)] async fn wait_incoming_payment( &self, - _request: Request, + _request: Request, ) -> Result, Status> { tracing::debug!("Server waiting for payment stream"); let (tx, rx) = mpsc::channel(128); @@ -307,34 +398,35 @@ impl CdkPaymentProcessor for PaymentProcessorServer { tokio::spawn(async move { loop { tokio::select! { - _ = shutdown_clone.notified() => { - tracing::info!("Shutdown signal received, stopping task for "); - ln.cancel_wait_invoice(); - break; - } - result = ln.wait_any_incoming_payment() => { - match result { - Ok(mut stream) => { - while let Some(request_lookup_id) = stream.next().await { - match tx.send(Result::<_, Status>::Ok(WaitIncomingPaymentResponse{lookup_id: request_lookup_id} )).await { - Ok(_) => { - // item (server response) was queued to be send to client - } - Err(item) => { - tracing::error!("Error adding incoming payment to stream: {}", item); + _ = shutdown_clone.notified() => { + tracing::info!("Shutdown signal received, stopping task"); + ln.cancel_wait_invoice(); break; } - } + result = ln.wait_any_incoming_payment() => { + match result { + Ok(mut stream) => { + while let Some(payment_response) = stream.next().await { + match tx.send(Result::<_, Status>::Ok(payment_response.into())) + .await + { + Ok(_) => { + // Response was queued to be sent to client + } + Err(item) => { + tracing::error!("Error adding incoming payment to stream: {}", item); + break; + } + } + } + } + Err(err) => { + tracing::warn!("Could not get invoice stream: {}", err); + tokio::time::sleep(std::time::Duration::from_secs(5)).await; } - } - Err(err) => { - tracing::warn!("Could not get invoice stream for {}", err); - - tokio::time::sleep(std::time::Duration::from_secs(5)).await; } } } - } } }); diff --git a/crates/cdk-sqlite/src/mint/error.rs b/crates/cdk-sqlite/src/mint/error.rs index ad5210632..cbc104485 100644 --- a/crates/cdk-sqlite/src/mint/error.rs +++ b/crates/cdk-sqlite/src/mint/error.rs @@ -101,6 +101,9 @@ pub enum Error { /// Invalid keyset ID #[error("Invalid keyset ID")] InvalidKeysetId, + /// Invalid melt payment request + #[error("Invalid melt payment request")] + InvalidMeltPaymentRequest, } impl From for cdk_common::database::Error { diff --git a/crates/cdk-sqlite/src/mint/memory.rs b/crates/cdk-sqlite/src/mint/memory.rs index 735f7670a..548644431 100644 --- a/crates/cdk-sqlite/src/mint/memory.rs +++ b/crates/cdk-sqlite/src/mint/memory.rs @@ -44,7 +44,7 @@ pub async fn new_with_state( let mut tx = MintDatabase::begin_transaction(&db).await?; for quote in mint_quotes { - tx.add_or_replace_mint_quote(quote).await?; + tx.add_mint_quote(quote).await?; } for quote in melt_quotes { diff --git a/crates/cdk-sqlite/src/mint/migrations.rs b/crates/cdk-sqlite/src/mint/migrations.rs index 9384c4966..d8e93c90f 100644 --- a/crates/cdk-sqlite/src/mint/migrations.rs +++ b/crates/cdk-sqlite/src/mint/migrations.rs @@ -21,4 +21,5 @@ pub static MIGRATIONS: &[(&str, &str)] = &[ ("20250406093755_mint_created_time_signature.sql", include_str!(r#"./migrations/20250406093755_mint_created_time_signature.sql"#)), ("20250415093121_drop_keystore_foreign.sql", include_str!(r#"./migrations/20250415093121_drop_keystore_foreign.sql"#)), ("20250626120251_rename_blind_message_y_to_b.sql", include_str!(r#"./migrations/20250626120251_rename_blind_message_y_to_b.sql"#)), + ("20250706101057_bolt12.sql", include_str!(r#"./migrations/20250706101057_bolt12.sql"#)), ]; diff --git a/crates/cdk-sqlite/src/mint/migrations/20250706101057_bolt12.sql b/crates/cdk-sqlite/src/mint/migrations/20250706101057_bolt12.sql new file mode 100644 index 000000000..94d690a65 --- /dev/null +++ b/crates/cdk-sqlite/src/mint/migrations/20250706101057_bolt12.sql @@ -0,0 +1,81 @@ +-- Add new columns to mint_quote table +ALTER TABLE mint_quote ADD COLUMN amount_paid INTEGER NOT NULL DEFAULT 0; +ALTER TABLE mint_quote ADD COLUMN amount_issued INTEGER NOT NULL DEFAULT 0; +ALTER TABLE mint_quote ADD COLUMN payment_method TEXT NOT NULL DEFAULT 'BOLT11'; +ALTER TABLE mint_quote DROP COLUMN issued_time; +ALTER TABLE mint_quote DROP COLUMN paid_time; + +-- Set amount_paid equal to amount for quotes with PAID or ISSUED state +UPDATE mint_quote SET amount_paid = amount WHERE state = 'PAID' OR state = 'ISSUED'; + +-- Set amount_issued equal to amount for quotes with ISSUED state +UPDATE mint_quote SET amount_issued = amount WHERE state = 'ISSUED'; + +DROP INDEX IF EXISTS mint_quote_state_index; + +-- Remove the state column from mint_quote table +ALTER TABLE mint_quote DROP COLUMN state; + +-- Remove NOT NULL constraint from amount column +CREATE TABLE mint_quote_temp ( + id TEXT PRIMARY KEY, + amount INTEGER, + unit TEXT NOT NULL, + request TEXT NOT NULL, + expiry INTEGER NOT NULL, + request_lookup_id TEXT UNIQUE, + pubkey TEXT, + created_time INTEGER NOT NULL DEFAULT 0, + amount_paid INTEGER NOT NULL DEFAULT 0, + amount_issued INTEGER NOT NULL DEFAULT 0, + payment_method TEXT NOT NULL DEFAULT 'BOLT11' +); + +INSERT INTO mint_quote_temp (id, amount, unit, request, expiry, request_lookup_id, pubkey, created_time, amount_paid, amount_issued, payment_method) +SELECT id, amount, unit, request, expiry, request_lookup_id, pubkey, created_time, amount_paid, amount_issued, payment_method +FROM mint_quote; + +DROP TABLE mint_quote; +ALTER TABLE mint_quote_temp RENAME TO mint_quote; + +ALTER TABLE mint_quote ADD COLUMN request_lookup_id_kind TEXT NOT NULL DEFAULT 'payment_hash'; + +CREATE INDEX IF NOT EXISTS idx_mint_quote_created_time ON mint_quote(created_time); +CREATE INDEX IF NOT EXISTS idx_mint_quote_expiry ON mint_quote(expiry); +CREATE INDEX IF NOT EXISTS idx_mint_quote_request_lookup_id ON mint_quote(request_lookup_id); +CREATE INDEX IF NOT EXISTS idx_mint_quote_request_lookup_id_and_kind ON mint_quote(request_lookup_id, request_lookup_id_kind); + +-- Create mint_quote_payments table +CREATE TABLE mint_quote_payments ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + quote_id TEXT NOT NULL, + payment_id TEXT NOT NULL UNIQUE, + timestamp INTEGER NOT NULL, + amount INTEGER NOT NULL, + FOREIGN KEY (quote_id) REFERENCES mint_quote(id) +); + +-- Create index on payment_id for faster lookups +CREATE INDEX idx_mint_quote_payments_payment_id ON mint_quote_payments(payment_id); +CREATE INDEX idx_mint_quote_payments_quote_id ON mint_quote_payments(quote_id); + +-- Create mint_quote_issued table +CREATE TABLE mint_quote_issued ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + quote_id TEXT NOT NULL, + amount INTEGER NOT NULL, + timestamp INTEGER NOT NULL, + FOREIGN KEY (quote_id) REFERENCES mint_quote(id) +); + +-- Create index on quote_id for faster lookups +CREATE INDEX idx_mint_quote_issued_quote_id ON mint_quote_issued(quote_id); + +-- Add new columns to melt_quote table +ALTER TABLE melt_quote ADD COLUMN payment_method TEXT NOT NULL DEFAULT 'bolt11'; +ALTER TABLE melt_quote ADD COLUMN options TEXT; +ALTER TABLE melt_quote ADD COLUMN request_lookup_id_kind TEXT NOT NULL DEFAULT 'payment_hash'; + +CREATE INDEX IF NOT EXISTS idx_melt_quote_request_lookup_id_and_kind ON mint_quote(request_lookup_id, request_lookup_id_kind); + +ALTER TABLE melt_quote DROP COLUMN msat_to_pay; diff --git a/crates/cdk-sqlite/src/mint/mod.rs b/crates/cdk-sqlite/src/mint/mod.rs index 6f6cd03c6..c2cf5796f 100644 --- a/crates/cdk-sqlite/src/mint/mod.rs +++ b/crates/cdk-sqlite/src/mint/mod.rs @@ -14,18 +14,21 @@ use cdk_common::database::{ MintProofsDatabase, MintProofsTransaction, MintQuotesDatabase, MintQuotesTransaction, MintSignatureTransaction, MintSignaturesDatabase, }; -use cdk_common::mint::{self, MintKeySetInfo, MintQuote}; +use cdk_common::mint::{ + self, IncomingPayment, Issuance, MeltPaymentRequest, MeltQuote, MintKeySetInfo, MintQuote, +}; use cdk_common::nut00::ProofsMethods; -use cdk_common::nut05::QuoteState; +use cdk_common::payment::PaymentIdentifier; use cdk_common::secret::Secret; use cdk_common::state::check_state_transition; use cdk_common::util::unix_time; use cdk_common::{ Amount, BlindSignature, BlindSignatureDleq, CurrencyUnit, Id, MeltQuoteState, MintInfo, - MintQuoteState, Proof, Proofs, PublicKey, SecretKey, State, + PaymentMethod, Proof, Proofs, PublicKey, SecretKey, State, }; use error::Error; use lightning_invoice::Bolt11Invoice; +use tracing::instrument; use uuid::Uuid; use crate::common::{create_sqlite_pool, migrate}; @@ -95,6 +98,66 @@ where Ok(()) } +#[inline(always)] +async fn get_mint_quote_payments( + conn: &C, + quote_id: &Uuid, +) -> Result, Error> +where + C: DatabaseExecutor + Send + Sync, +{ + // Get payment IDs and timestamps from the mint_quote_payments table + query( + r#" +SELECT payment_id, timestamp, amount +FROM mint_quote_payments +WHERE quote_id=:quote_id; + "#, + ) + .bind(":quote_id", quote_id.as_hyphenated().to_string()) + .fetch_all(conn) + .await? + .into_iter() + .map(|row| { + let amount: u64 = column_as_number!(row[2].clone()); + let time: u64 = column_as_number!(row[1].clone()); + Ok(IncomingPayment::new( + amount.into(), + column_as_string!(&row[0]), + time, + )) + }) + .collect() +} + +#[inline(always)] +async fn get_mint_quote_issuance(conn: &C, quote_id: &Uuid) -> Result, Error> +where + C: DatabaseExecutor + Send + Sync, +{ + // Get payment IDs and timestamps from the mint_quote_payments table + query( + r#" +SELECT amount, timestamp +FROM mint_quote_issued +WHERE quote_id=:quote_id; + "#, + ) + .bind(":quote_id", quote_id.as_hyphenated().to_string()) + .fetch_all(conn) + .await? + .into_iter() + .map(|row| { + let time: u64 = column_as_number!(row[1].clone()); + Ok(Issuance::new( + Amount::from_i64(column_as_number!(row[0].clone())) + .expect("Is amount when put into db"), + time, + )) + }) + .collect() +} + impl MintSqliteDatabase { /// Create new [`MintSqliteDatabase`] #[cfg(not(feature = "sqlcipher"))] @@ -324,30 +387,193 @@ impl MintKeysDatabase for MintSqliteDatabase { impl<'a> MintQuotesTransaction<'a> for SqliteTransaction<'a> { type Err = database::Error; - async fn add_or_replace_mint_quote(&mut self, quote: MintQuote) -> Result<(), Self::Err> { + #[instrument(skip(self))] + async fn increment_mint_quote_amount_paid( + &mut self, + quote_id: &Uuid, + amount_paid: Amount, + payment_id: String, + ) -> Result { + // Check if payment_id already exists in mint_quote_payments + let exists = query( + r#" + SELECT payment_id + FROM mint_quote_payments + WHERE payment_id = :payment_id + "#, + ) + .bind(":payment_id", payment_id.clone()) + .fetch_one(&self.inner) + .await?; + + if exists.is_some() { + tracing::error!("Payment ID already exists: {}", payment_id); + return Err(database::Error::Duplicate); + } + + // Get current amount_paid from quote + let current_amount = query( + r#" + SELECT amount_paid + FROM mint_quote + WHERE id = :quote_id + "#, + ) + .bind(":quote_id", quote_id.as_hyphenated().to_string()) + .fetch_one(&self.inner) + .await + .map_err(|err| { + tracing::error!("SQLite could not get mint quote amount_paid"); + err + })?; + + let current_amount_paid = if let Some(current_amount) = current_amount { + let amount: u64 = column_as_number!(current_amount[0].clone()); + Amount::from(amount) + } else { + Amount::ZERO + }; + + // Calculate new amount_paid with overflow check + let new_amount_paid = current_amount_paid + .checked_add(amount_paid) + .ok_or_else(|| database::Error::AmountOverflow)?; + + // Update the amount_paid + query( + r#" + UPDATE mint_quote + SET amount_paid = :amount_paid + WHERE id = :quote_id + "#, + ) + .bind(":amount_paid", new_amount_paid.to_i64()) + .bind(":quote_id", quote_id.as_hyphenated().to_string()) + .execute(&self.inner) + .await + .map_err(|err| { + tracing::error!("SQLite could not update mint quote amount_paid"); + err + })?; + + // Add payment_id to mint_quote_payments table + query( + r#" + INSERT INTO mint_quote_payments + (quote_id, payment_id, amount, timestamp) + VALUES (:quote_id, :payment_id, :amount, :timestamp) + "#, + ) + .bind(":quote_id", quote_id.as_hyphenated().to_string()) + .bind(":payment_id", payment_id) + .bind(":amount", amount_paid.to_i64()) + .bind(":timestamp", unix_time() as i64) + .execute(&self.inner) + .await + .map_err(|err| { + tracing::error!("SQLite could not insert payment ID: {}", err); + err + })?; + + Ok(new_amount_paid) + } + + #[instrument(skip_all)] + async fn increment_mint_quote_amount_issued( + &mut self, + quote_id: &Uuid, + amount_issued: Amount, + ) -> Result { + // Get current amount_issued from quote + let current_amount = query( + r#" + SELECT amount_issued + FROM mint_quote + WHERE id = :quote_id + "#, + ) + .bind(":quote_id", quote_id.as_hyphenated().to_string()) + .fetch_one(&self.inner) + .await + .map_err(|err| { + tracing::error!("SQLite could not get mint quote amount_issued"); + err + })?; + + let current_amount_issued = if let Some(current_amount) = current_amount { + let amount: u64 = column_as_number!(current_amount[0].clone()); + Amount::from(amount) + } else { + Amount::ZERO + }; + + // Calculate new amount_issued with overflow check + let new_amount_issued = current_amount_issued + .checked_add(amount_issued) + .ok_or_else(|| database::Error::AmountOverflow)?; + + // Update the amount_issued query( r#" - INSERT OR REPLACE INTO mint_quote ( - id, amount, unit, request, state, expiry, request_lookup_id, - pubkey, created_time, paid_time, issued_time + UPDATE mint_quote + SET amount_issued = :amount_issued + WHERE id = :quote_id + "#, + ) + .bind(":amount_issued", new_amount_issued.to_i64()) + .bind(":quote_id", quote_id.as_hyphenated().to_string()) + .execute(&self.inner) + .await + .map_err(|err| { + tracing::error!("SQLite could not update mint quote amount_issued"); + err + })?; + + let current_time = unix_time(); + + query( + r#" +INSERT INTO mint_quote_issued +(quote_id, amount, timestamp) +VALUES (:quote_id, :amount, :timestamp); + "#, + ) + .bind(":quote_id", quote_id.as_hyphenated().to_string()) + .bind(":amount", amount_issued.to_i64()) + .bind(":timestamp", current_time as i64) + .execute(&self.inner) + .await?; + + Ok(new_amount_issued) + } + + #[instrument(skip_all)] + async fn add_mint_quote(&mut self, quote: MintQuote) -> Result<(), Self::Err> { + tracing::debug!("Adding quote with: {}", quote.payment_method.to_string()); + println!("Adding quote with: {}", quote.payment_method.to_string()); + query( + r#" + INSERT INTO mint_quote ( + id, amount, unit, request, expiry, request_lookup_id, pubkey, created_time, payment_method, request_lookup_id_kind ) VALUES ( - :id, :amount, :unit, :request, :state, :expiry, :request_lookup_id, - :pubkey, :created_time, :paid_time, :issued_time + :id, :amount, :unit, :request, :expiry, :request_lookup_id, :pubkey, :created_time, :payment_method, :request_lookup_id_kind ) "#, ) .bind(":id", quote.id.to_string()) - .bind(":amount", u64::from(quote.amount) as i64) + .bind(":amount", quote.amount.map(|a| a.to_i64())) .bind(":unit", quote.unit.to_string()) .bind(":request", quote.request) - .bind(":state", quote.state.to_string()) .bind(":expiry", quote.expiry as i64) - .bind(":request_lookup_id", quote.request_lookup_id) + .bind( + ":request_lookup_id", + quote.request_lookup_id.to_string(), + ) .bind(":pubkey", quote.pubkey.map(|p| p.to_string())) .bind(":created_time", quote.created_time as i64) - .bind(":paid_time", quote.paid_time.map(|t| t as i64)) - .bind(":issued_time", quote.issued_time.map(|t| t as i64)) + .bind(":payment_method", quote.payment_method.to_string()) + .bind(":request_lookup_id_kind", quote.request_lookup_id.kind()) .execute(&self.inner) .await?; @@ -389,32 +615,33 @@ impl<'a> MintQuotesTransaction<'a> for SqliteTransaction<'a> { INSERT INTO melt_quote ( id, unit, amount, request, fee_reserve, state, - expiry, payment_preimage, request_lookup_id, msat_to_pay, - created_time, paid_time + expiry, payment_preimage, request_lookup_id, + created_time, paid_time, options, request_lookup_id_kind ) VALUES ( :id, :unit, :amount, :request, :fee_reserve, :state, - :expiry, :payment_preimage, :request_lookup_id, :msat_to_pay, - :created_time, :paid_time + :expiry, :payment_preimage, :request_lookup_id, + :created_time, :paid_time, :options, :request_lookup_id_kind ) "#, ) .bind(":id", quote.id.to_string()) .bind(":unit", quote.unit.to_string()) - .bind(":amount", u64::from(quote.amount) as i64) - .bind(":request", quote.request) - .bind(":fee_reserve", u64::from(quote.fee_reserve) as i64) + .bind(":amount", quote.amount.to_i64()) + .bind(":request", serde_json::to_string("e.request)?) + .bind(":fee_reserve", quote.fee_reserve.to_i64()) .bind(":state", quote.state.to_string()) .bind(":expiry", quote.expiry as i64) .bind(":payment_preimage", quote.payment_preimage) - .bind(":request_lookup_id", quote.request_lookup_id) - .bind( - ":msat_to_pay", - quote.msat_to_pay.map(|a| u64::from(a) as i64), - ) + .bind(":request_lookup_id", quote.request_lookup_id.to_string()) .bind(":created_time", quote.created_time as i64) .bind(":paid_time", quote.paid_time.map(|t| t as i64)) + .bind( + ":options", + quote.options.map(|o| serde_json::to_string(&o).ok()), + ) + .bind(":request_lookup_id_kind", quote.request_lookup_id.kind()) .execute(&self.inner) .await?; @@ -424,10 +651,11 @@ impl<'a> MintQuotesTransaction<'a> for SqliteTransaction<'a> { async fn update_melt_quote_request_lookup_id( &mut self, quote_id: &Uuid, - new_request_lookup_id: &str, + new_request_lookup_id: &PaymentIdentifier, ) -> Result<(), Self::Err> { - query(r#"UPDATE melt_quote SET request_lookup_id = :new_req_id WHERE id = :id"#) - .bind(":new_req_id", new_request_lookup_id.to_owned()) + query(r#"UPDATE melt_quote SET request_lookup_id = :new_req_id, request_lookup_id_kind = :new_kind WHERE id = :id"#) + .bind(":new_req_id", new_request_lookup_id.to_string()) + .bind(":new_kind",new_request_lookup_id.kind() ) .bind(":id", quote_id.as_hyphenated().to_string()) .execute(&self.inner) .await?; @@ -438,6 +666,7 @@ impl<'a> MintQuotesTransaction<'a> for SqliteTransaction<'a> { &mut self, quote_id: &Uuid, state: MeltQuoteState, + payment_proof: Option, ) -> Result<(MeltQuoteState, mint::MeltQuote), Self::Err> { let mut quote = query( r#" @@ -447,13 +676,15 @@ impl<'a> MintQuotesTransaction<'a> for SqliteTransaction<'a> { amount, request, fee_reserve, - state, expiry, + state, payment_preimage, request_lookup_id, - msat_to_pay, created_time, - paid_time + paid_time, + payment_method, + options, + request_lookup_id_kind FROM melt_quote WHERE @@ -471,9 +702,10 @@ impl<'a> MintQuotesTransaction<'a> for SqliteTransaction<'a> { let rec = if state == MeltQuoteState::Paid { let current_time = unix_time(); - query(r#"UPDATE melt_quote SET state = :state, paid_time = :paid_time WHERE id = :id"#) + query(r#"UPDATE melt_quote SET state = :state, paid_time = :paid_time, payment_preimage = :payment_preimage WHERE id = :id"#) .bind(":state", state.to_string()) .bind(":paid_time", current_time as i64) + .bind(":payment_preimage", payment_proof) .bind(":id", quote_id.as_hyphenated().to_string()) .execute(&self.inner) .await @@ -513,72 +745,10 @@ impl<'a> MintQuotesTransaction<'a> for SqliteTransaction<'a> { Ok(()) } - async fn update_mint_quote_state( - &mut self, - quote_id: &Uuid, - state: MintQuoteState, - ) -> Result { - let quote = query( - r#" - SELECT - id, - amount, - unit, - request, - state, - expiry, - request_lookup_id, - pubkey, - created_time, - paid_time, - issued_time - FROM - mint_quote - WHERE id = :id"#, - ) - .bind(":id", quote_id.as_hyphenated().to_string()) - .fetch_one(&self.inner) - .await? - .map(sqlite_row_to_mint_quote) - .ok_or(Error::QuoteNotFound)??; - - let update_query = match state { - MintQuoteState::Paid => { - r#"UPDATE mint_quote SET state = :state, paid_time = :current_time WHERE id = :quote_id"# - } - MintQuoteState::Issued => { - r#"UPDATE mint_quote SET state = :state, issued_time = :current_time WHERE id = :quote_id"# - } - _ => r#"UPDATE mint_quote SET state = :state WHERE id = :quote_id"#, - }; - - let current_time = unix_time(); - - let update = match state { - MintQuoteState::Paid => query(update_query) - .bind(":state", state.to_string()) - .bind(":current_time", current_time as i64) - .bind(":quote_id", quote_id.as_hyphenated().to_string()), - MintQuoteState::Issued => query(update_query) - .bind(":state", state.to_string()) - .bind(":current_time", current_time as i64) - .bind(":quote_id", quote_id.as_hyphenated().to_string()), - _ => query(update_query) - .bind(":state", state.to_string()) - .bind(":quote_id", quote_id.as_hyphenated().to_string()), - }; - - match update.execute(&self.inner).await { - Ok(_) => Ok(quote.state), - Err(err) => { - tracing::error!("SQLite Could not update keyset: {:?}", err); - - return Err(err.into()); - } - } - } - async fn get_mint_quote(&mut self, quote_id: &Uuid) -> Result, Self::Err> { + let payments = get_mint_quote_payments(&self.inner, quote_id).await?; + let issuance = get_mint_quote_issuance(&self.inner, quote_id).await?; + Ok(query( r#" SELECT @@ -586,13 +756,14 @@ impl<'a> MintQuotesTransaction<'a> for SqliteTransaction<'a> { amount, unit, request, - state, expiry, request_lookup_id, pubkey, created_time, - paid_time, - issued_time + amount_paid, + amount_issued, + payment_method, + request_lookup_id_kind FROM mint_quote WHERE id = :id"#, @@ -600,7 +771,7 @@ impl<'a> MintQuotesTransaction<'a> for SqliteTransaction<'a> { .bind(":id", quote_id.as_hyphenated().to_string()) .fetch_one(&self.inner) .await? - .map(sqlite_row_to_mint_quote) + .map(|row| sqlite_row_to_mint_quote(row, payments, issuance)) .transpose()?) } @@ -610,19 +781,21 @@ impl<'a> MintQuotesTransaction<'a> for SqliteTransaction<'a> { ) -> Result, Self::Err> { Ok(query( r#" - SELECT + SELECT id, unit, amount, request, fee_reserve, - state, expiry, + state, payment_preimage, request_lookup_id, - msat_to_pay, created_time, - paid_time + paid_time, + payment_method, + options, + request_lookup_id FROM melt_quote WHERE @@ -640,29 +813,81 @@ impl<'a> MintQuotesTransaction<'a> for SqliteTransaction<'a> { &mut self, request: &str, ) -> Result, Self::Err> { - Ok(query( + let mut mint_quote = query( r#" SELECT id, amount, unit, request, - state, expiry, request_lookup_id, pubkey, created_time, - paid_time, - issued_time + amount_paid, + amount_issued, + payment_method, + request_lookup_id_kind FROM mint_quote WHERE request = :request"#, ) - .bind(":request", request.to_owned()) + .bind(":request", request.to_string()) .fetch_one(&self.inner) .await? - .map(sqlite_row_to_mint_quote) - .transpose()?) + .map(|row| sqlite_row_to_mint_quote(row, vec![], vec![])) + .transpose()?; + + if let Some(quote) = mint_quote.as_mut() { + let payments = get_mint_quote_payments(&self.inner, "e.id).await?; + let issuance = get_mint_quote_issuance(&self.inner, "e.id).await?; + quote.issuance = issuance; + quote.payments = payments; + } + + Ok(mint_quote) + } + + async fn get_mint_quote_by_request_lookup_id( + &mut self, + request_lookup_id: &PaymentIdentifier, + ) -> Result, Self::Err> { + let mut mint_quote = query( + r#" + SELECT + id, + amount, + unit, + request, + expiry, + request_lookup_id, + pubkey, + created_time, + amount_paid, + amount_issued, + payment_method, + request_lookup_id_kind + FROM + mint_quote + WHERE request_lookup_id = :request_lookup_id + AND request_lookup_id_kind = :request_lookup_id_kind + "#, + ) + .bind(":request_lookup_id", request_lookup_id.to_string()) + .bind(":request_lookup_id_kind", request_lookup_id.kind()) + .fetch_one(&self.inner) + .await? + .map(|row| sqlite_row_to_mint_quote(row, vec![], vec![])) + .transpose()?; + + if let Some(quote) = mint_quote.as_mut() { + let payments = get_mint_quote_payments(&self.inner, "e.id).await?; + let issuance = get_mint_quote_issuance(&self.inner, "e.id).await?; + quote.issuance = issuance; + quote.payments = payments; + } + + Ok(mint_quote) } } @@ -671,6 +896,9 @@ impl MintQuotesDatabase for MintSqliteDatabase { type Err = database::Error; async fn get_mint_quote(&self, quote_id: &Uuid) -> Result, Self::Err> { + let payments = get_mint_quote_payments(&self.pool, quote_id).await?; + let issuance = get_mint_quote_issuance(&self.pool, quote_id).await?; + Ok(query( r#" SELECT @@ -678,13 +906,14 @@ impl MintQuotesDatabase for MintSqliteDatabase { amount, unit, request, - state, expiry, request_lookup_id, pubkey, created_time, - paid_time, - issued_time + amount_paid, + amount_issued, + payment_method, + request_lookup_id_kind FROM mint_quote WHERE id = :id"#, @@ -692,7 +921,7 @@ impl MintQuotesDatabase for MintSqliteDatabase { .bind(":id", quote_id.as_hyphenated().to_string()) .fetch_one(&self.pool) .await? - .map(sqlite_row_to_mint_quote) + .map(|row| sqlite_row_to_mint_quote(row, payments, issuance)) .transpose()?) } @@ -700,20 +929,21 @@ impl MintQuotesDatabase for MintSqliteDatabase { &self, request: &str, ) -> Result, Self::Err> { - Ok(query( + let mut mint_quote = query( r#" SELECT id, amount, unit, request, - state, expiry, request_lookup_id, pubkey, created_time, - paid_time, - issued_time + amount_paid, + amount_issued, + payment_method, + request_lookup_id_kind FROM mint_quote WHERE request = :request"#, @@ -721,95 +951,96 @@ impl MintQuotesDatabase for MintSqliteDatabase { .bind(":request", request.to_owned()) .fetch_one(&self.pool) .await? - .map(sqlite_row_to_mint_quote) - .transpose()?) + .map(|row| sqlite_row_to_mint_quote(row, vec![], vec![])) + .transpose()?; + + if let Some(quote) = mint_quote.as_mut() { + let payments = get_mint_quote_payments(&self.pool, "e.id).await?; + let issuance = get_mint_quote_issuance(&self.pool, "e.id).await?; + quote.issuance = issuance; + quote.payments = payments; + } + + Ok(mint_quote) } async fn get_mint_quote_by_request_lookup_id( &self, - request_lookup_id: &str, + request_lookup_id: &PaymentIdentifier, ) -> Result, Self::Err> { - Ok(query( + let mut mint_quote = query( r#" SELECT id, amount, unit, request, - state, expiry, request_lookup_id, pubkey, created_time, - paid_time, - issued_time + amount_paid, + amount_issued, + payment_method, + request_lookup_id_kind FROM mint_quote WHERE request_lookup_id = :request_lookup_id"#, ) - .bind(":request_lookup_id", request_lookup_id.to_owned()) + .bind( + ":request_lookup_id", + serde_json::to_string(request_lookup_id)?, + ) .fetch_one(&self.pool) .await? - .map(sqlite_row_to_mint_quote) - .transpose()?) + .map(|row| sqlite_row_to_mint_quote(row, vec![], vec![])) + .transpose()?; + + // TODO: these should use an sql join so they can be done in one query + if let Some(quote) = mint_quote.as_mut() { + let payments = get_mint_quote_payments(&self.pool, "e.id).await?; + let issuance = get_mint_quote_issuance(&self.pool, "e.id).await?; + quote.issuance = issuance; + quote.payments = payments; + } + + Ok(mint_quote) } async fn get_mint_quotes(&self) -> Result, Self::Err> { - Ok(query( + let mut mint_quotes = query( r#" - SELECT - id, - amount, - unit, - request, - state, - expiry, - request_lookup_id, - pubkey, - created_time, - paid_time, - issued_time - FROM - mint_quote - "#, + SELECT + id, + amount, + unit, + request, + expiry, + request_lookup_id, + pubkey, + created_time, + amount_paid, + amount_issued, + payment_method, + request_lookup_id_kind + FROM + mint_quote + "#, ) .fetch_all(&self.pool) .await? .into_iter() - .map(sqlite_row_to_mint_quote) - .collect::, _>>()?) - } + .map(|row| sqlite_row_to_mint_quote(row, vec![], vec![])) + .collect::, _>>()?; + + for quote in mint_quotes.as_mut_slice() { + let payments = get_mint_quote_payments(&self.pool, "e.id).await?; + let issuance = get_mint_quote_issuance(&self.pool, "e.id).await?; + quote.issuance = issuance; + quote.payments = payments; + } - async fn get_mint_quotes_with_state( - &self, - state: MintQuoteState, - ) -> Result, Self::Err> { - Ok(query( - r#" - SELECT - id, - amount, - unit, - request, - state, - expiry, - request_lookup_id, - pubkey, - created_time, - paid_time, - issued_time - FROM - mint_quote - WHERE - state = :state - "#, - ) - .bind(":state", state.to_string()) - .fetch_all(&self.pool) - .await? - .into_iter() - .map(sqlite_row_to_mint_quote) - .collect::, _>>()?) + Ok(mint_quotes) } async fn get_melt_quote(&self, quote_id: &Uuid) -> Result, Self::Err> { @@ -821,13 +1052,15 @@ impl MintQuotesDatabase for MintSqliteDatabase { amount, request, fee_reserve, - state, expiry, + state, payment_preimage, request_lookup_id, - msat_to_pay, created_time, - paid_time + paid_time, + payment_method, + options, + request_lookup_id_kind FROM melt_quote WHERE @@ -844,19 +1077,21 @@ impl MintQuotesDatabase for MintSqliteDatabase { async fn get_melt_quotes(&self) -> Result, Self::Err> { Ok(query( r#" - SELECT + SELECT id, unit, amount, request, fee_reserve, - state, expiry, + state, payment_preimage, request_lookup_id, - msat_to_pay, created_time, - paid_time + paid_time, + payment_method, + options, + request_lookup_id_kind FROM melt_quote "#, @@ -910,7 +1145,7 @@ impl<'a> MintProofsTransaction<'a> for SqliteTransaction<'a> { "#, ) .bind(":y", proof.y()?.to_bytes().to_vec()) - .bind(":amount", u64::from(proof.amount) as i64) + .bind(":amount", proof.amount.to_i64()) .bind(":keyset_id", proof.keyset_id.to_string()) .bind(":secret", proof.secret.to_string()) .bind(":c", proof.c.to_bytes().to_vec()) @@ -984,6 +1219,7 @@ impl<'a> MintProofsTransaction<'a> for SqliteTransaction<'a> { impl MintProofsDatabase for MintSqliteDatabase { type Err = database::Error; + #[instrument(skip_all)] async fn get_proofs_by_ys(&self, ys: &[PublicKey]) -> Result>, Self::Err> { let mut proofs = query( r#" @@ -1019,6 +1255,7 @@ impl MintProofsDatabase for MintSqliteDatabase { Ok(ys.iter().map(|y| proofs.remove(y)).collect()) } + #[instrument(skip(self))] async fn get_proof_ys_by_quote_id(&self, quote_id: &Uuid) -> Result, Self::Err> { Ok(query( r#" @@ -1043,12 +1280,14 @@ impl MintProofsDatabase for MintSqliteDatabase { .ys()?) } + #[instrument(skip_all)] async fn get_proofs_states(&self, ys: &[PublicKey]) -> Result>, Self::Err> { let mut current_states = get_current_states(&self.pool, ys).await?; Ok(ys.iter().map(|y| current_states.remove(y)).collect()) } + #[instrument(skip_all)] async fn get_proofs_by_keyset_id( &self, keyset_id: &Id, @@ -1083,6 +1322,7 @@ impl MintProofsDatabase for MintSqliteDatabase { impl<'a> MintSignatureTransaction<'a> for SqliteTransaction<'a> { type Err = database::Error; + #[instrument(skip_all)] async fn add_blind_signatures( &mut self, blinded_messages: &[PublicKey], @@ -1101,9 +1341,9 @@ impl<'a> MintSignatureTransaction<'a> for SqliteTransaction<'a> { "#, ) .bind(":blinded_message", message.to_bytes().to_vec()) - .bind(":amount", u64::from(signature.amount) as i64) + .bind(":amount", signature.amount.to_i64()) .bind(":keyset_id", signature.keyset_id.to_string()) - .bind(":c", signature.c.to_bytes().to_vec()) + .bind(":c", signature.c.to_hex()) .bind(":quote_id", quote_id.map(|q| q.hyphenated().to_string())) .bind( ":dleq_e", @@ -1121,6 +1361,7 @@ impl<'a> MintSignatureTransaction<'a> for SqliteTransaction<'a> { Ok(()) } + #[instrument(skip_all)] async fn get_blind_signatures( &mut self, blinded_messages: &[PublicKey], @@ -1135,11 +1376,11 @@ impl<'a> MintSignatureTransaction<'a> for SqliteTransaction<'a> { blinded_message FROM blind_signature - WHERE blinded_message IN (:y) + WHERE blinded_message IN (:blinded_message) "#, ) .bind_vec( - ":y", + ":blinded_message", blinded_messages .iter() .map(|y| y.to_bytes().to_vec()) @@ -1159,6 +1400,7 @@ impl<'a> MintSignatureTransaction<'a> for SqliteTransaction<'a> { )) }) .collect::, Error>>()?; + Ok(blinded_messages .iter() .map(|y| blinded_signatures.remove(y)) @@ -1318,58 +1560,72 @@ fn sqlite_row_to_keyset_info(row: Vec) -> Result }) } -fn sqlite_row_to_mint_quote(row: Vec) -> Result { +#[instrument(skip_all)] +fn sqlite_row_to_mint_quote( + row: Vec, + payments: Vec, + issueances: Vec, +) -> Result { unpack_into!( let ( - id, amount, unit, request, state, expiry, request_lookup_id, - pubkey, created_time, paid_time, issued_time + id, amount, unit, request, expiry, request_lookup_id, + pubkey, created_time, amount_paid, amount_issued, payment_method, request_lookup_id_kind ) = row ); - let request = column_as_string!(&request); + let request_str = column_as_string!(&request); let request_lookup_id = column_as_nullable_string!(&request_lookup_id).unwrap_or_else(|| { - Bolt11Invoice::from_str(&request) + Bolt11Invoice::from_str(&request_str) .map(|invoice| invoice.payment_hash().to_string()) - .unwrap_or_else(|_| request.clone()) + .unwrap_or_else(|_| request_str.clone()) }); + let request_lookup_id_kind = column_as_string!(request_lookup_id_kind); let pubkey = column_as_nullable_string!(&pubkey) .map(|pk| PublicKey::from_hex(&pk)) .transpose()?; let id = column_as_string!(id); - let amount: u64 = column_as_number!(amount); - - Ok(MintQuote { - id: Uuid::parse_str(&id).map_err(|_| Error::InvalidUuid(id))?, - amount: Amount::from(amount), - unit: column_as_string!(unit, CurrencyUnit::from_str), - request, - state: column_as_string!(state, MintQuoteState::from_str), - expiry: column_as_number!(expiry), - request_lookup_id, + let amount: Option = column_as_nullable_number!(amount); + let amount_paid: u64 = column_as_number!(amount_paid); + let amount_issued: u64 = column_as_number!(amount_issued); + let payment_method = column_as_string!(payment_method, PaymentMethod::from_str); + + Ok(MintQuote::new( + Some(Uuid::parse_str(&id).map_err(|_| Error::InvalidUuid(id))?), + request_str, + column_as_string!(unit, CurrencyUnit::from_str), + amount.map(Amount::from), + column_as_number!(expiry), + PaymentIdentifier::new(&request_lookup_id_kind, &request_lookup_id) + .map_err(|_| Error::MissingParameter("Payment id".to_string()))?, pubkey, - created_time: column_as_number!(created_time), - paid_time: column_as_nullable_number!(paid_time).map(|p| p), - issued_time: column_as_nullable_number!(issued_time).map(|p| p), - }) + amount_paid.into(), + amount_issued.into(), + payment_method, + column_as_number!(created_time), + payments, + issueances, + )) } fn sqlite_row_to_melt_quote(row: Vec) -> Result { unpack_into!( let ( - id, - unit, - amount, - request, - fee_reserve, - state, - expiry, - payment_preimage, - request_lookup_id, - msat_to_pay, - created_time, - paid_time + id, + unit, + amount, + request, + fee_reserve, + expiry, + state, + payment_preimage, + request_lookup_id, + created_time, + paid_time, + payment_method, + options, + request_lookup_id_kind ) = row ); @@ -1377,27 +1633,59 @@ fn sqlite_row_to_melt_quote(row: Vec) -> Result let amount: u64 = column_as_number!(amount); let fee_reserve: u64 = column_as_number!(fee_reserve); - let request = column_as_string!(&request); + let expiry = column_as_number!(expiry); + let payment_preimage = column_as_nullable_string!(payment_preimage); + let options = column_as_nullable_string!(options); + let options = options.and_then(|o| serde_json::from_str(&o).ok()); + let created_time: i64 = column_as_number!(created_time); + let paid_time = column_as_nullable_number!(paid_time); + let payment_method = PaymentMethod::from_str(&column_as_string!(payment_method))?; + + let state = MeltQuoteState::from_str(&column_as_string!(&state))?; + + let unit = column_as_string!(unit); + let request = column_as_string!(request); + + let mut request_lookup_id_kind = column_as_string!(request_lookup_id_kind); + let request_lookup_id = column_as_nullable_string!(&request_lookup_id).unwrap_or_else(|| { Bolt11Invoice::from_str(&request) .map(|invoice| invoice.payment_hash().to_string()) - .unwrap_or_else(|_| request.clone()) + .unwrap_or_else(|_| { + request_lookup_id_kind = "custom".to_string(); + request.clone() + }) }); - let msat_to_pay: Option = column_as_nullable_number!(msat_to_pay); - Ok(mint::MeltQuote { + let request_lookup_id = PaymentIdentifier::new(&request_lookup_id_kind, &request_lookup_id) + .map_err(|_| Error::MissingParameter("Payment id".to_string()))?; + + let request = match serde_json::from_str(&request) { + Ok(req) => req, + Err(err) => { + tracing::debug!( + "Melt quote from pre migrations defaulting to bolt11 {}.", + err + ); + let bolt11 = Bolt11Invoice::from_str(&request).unwrap(); + MeltPaymentRequest::Bolt11 { bolt11 } + } + }; + + Ok(MeltQuote { id: Uuid::parse_str(&id).map_err(|_| Error::InvalidUuid(id))?, + unit: CurrencyUnit::from_str(&unit)?, amount: Amount::from(amount), - fee_reserve: Amount::from(fee_reserve), - unit: column_as_string!(unit, CurrencyUnit::from_str), request, - payment_preimage: column_as_nullable_string!(payment_preimage), - msat_to_pay: msat_to_pay.map(Amount::from), - state: column_as_string!(state, QuoteState::from_str), - expiry: column_as_number!(expiry), + fee_reserve: Amount::from(fee_reserve), + state, + expiry, + payment_preimage, request_lookup_id, - created_time: column_as_number!(created_time), - paid_time: column_as_nullable_number!(paid_time).map(|p| p), + options, + created_time: created_time as u64, + paid_time, + payment_method, }) } diff --git a/crates/cdk-sqlite/src/wallet/migrations.rs b/crates/cdk-sqlite/src/wallet/migrations.rs index dce9e2c95..0c41bad78 100644 --- a/crates/cdk-sqlite/src/wallet/migrations.rs +++ b/crates/cdk-sqlite/src/wallet/migrations.rs @@ -17,4 +17,5 @@ pub static MIGRATIONS: &[(&str, &str)] = &[ ("20250323152040_wallet_dleq_proofs.sql", include_str!(r#"./migrations/20250323152040_wallet_dleq_proofs.sql"#)), ("20250401120000_add_transactions_table.sql", include_str!(r#"./migrations/20250401120000_add_transactions_table.sql"#)), ("20250616144830_add_keyset_expiry.sql", include_str!(r#"./migrations/20250616144830_add_keyset_expiry.sql"#)), + ("20250707093445_bolt12.sql", include_str!(r#"./migrations/20250707093445_bolt12.sql"#)), ]; diff --git a/crates/cdk-sqlite/src/wallet/migrations/20250707093445_bolt12.sql b/crates/cdk-sqlite/src/wallet/migrations/20250707093445_bolt12.sql new file mode 100644 index 000000000..c191ee593 --- /dev/null +++ b/crates/cdk-sqlite/src/wallet/migrations/20250707093445_bolt12.sql @@ -0,0 +1,58 @@ +ALTER TABLE mint_quote ADD COLUMN amount_paid INTEGER NOT NULL DEFAULT 0; +ALTER TABLE mint_quote ADD COLUMN amount_minted INTEGER NOT NULL DEFAULT 0; +ALTER TABLE mint_quote ADD COLUMN payment_method TEXT NOT NULL DEFAULT 'BOLT11'; + +-- Remove NOT NULL constraint from amount column +PRAGMA foreign_keys=off; +CREATE TABLE mint_quote_new ( + id TEXT PRIMARY KEY, + mint_url TEXT NOT NULL, + payment_method TEXT NOT NULL DEFAULT 'bolt11', + amount INTEGER, + unit TEXT NOT NULL, + request TEXT NOT NULL, + state TEXT NOT NULL, + expiry INTEGER NOT NULL, + amount_paid INTEGER NOT NULL DEFAULT 0, + amount_issued INTEGER NOT NULL DEFAULT 0, + secret_key TEXT +); + +-- Explicitly specify columns for proper mapping +INSERT INTO mint_quote_new ( + id, + mint_url, + payment_method, + amount, + unit, + request, + state, + expiry, + amount_paid, + amount_issued, + secret_key +) +SELECT + id, + mint_url, + 'bolt11', -- Default value for the new payment_method column + amount, + unit, + request, + state, + expiry, + 0, -- Default value for amount_paid + 0, -- Default value for amount_minted + secret_key +FROM mint_quote; + +DROP TABLE mint_quote; +ALTER TABLE mint_quote_new RENAME TO mint_quote; +PRAGMA foreign_keys=on; + + +-- Set amount_paid equal to amount for quotes with PAID or ISSUED state +UPDATE mint_quote SET amount_paid = amount WHERE state = 'PAID' OR state = 'ISSUED'; + +-- Set amount_issued equal to amount for quotes with ISSUED state +UPDATE mint_quote SET amount_issued = amount WHERE state = 'ISSUED'; diff --git a/crates/cdk-sqlite/src/wallet/mod.rs b/crates/cdk-sqlite/src/wallet/mod.rs index 74c57b362..5e16e7fcb 100644 --- a/crates/cdk-sqlite/src/wallet/mod.rs +++ b/crates/cdk-sqlite/src/wallet/mod.rs @@ -14,8 +14,8 @@ use cdk_common::nuts::{MeltQuoteState, MintQuoteState}; use cdk_common::secret::Secret; use cdk_common::wallet::{self, MintQuote, Transaction, TransactionDirection, TransactionId}; use cdk_common::{ - database, Amount, CurrencyUnit, Id, KeySet, KeySetInfo, Keys, MintInfo, Proof, ProofDleq, - PublicKey, SecretKey, SpendingConditions, State, + database, Amount, CurrencyUnit, Id, KeySet, KeySetInfo, Keys, MintInfo, PaymentMethod, Proof, + ProofDleq, PublicKey, SecretKey, SpendingConditions, State, }; use error::Error; use tracing::instrument; @@ -376,9 +376,9 @@ ON CONFLICT(mint_url) DO UPDATE SET Statement::new( r#" INSERT INTO mint_quote -(id, mint_url, amount, unit, request, state, expiry, secret_key) +(id, mint_url, amount, unit, request, state, expiry, secret_key, payment_method, amount_issued, amount_paid) VALUES -(:id, :mint_url, :amount, :unit, :request, :state, :expiry, :secret_key) +(:id, :mint_url, :amount, :unit, :request, :state, :expiry, :secret_key, :payment_method, :amount_issued, :amount_paid) ON CONFLICT(id) DO UPDATE SET mint_url = excluded.mint_url, amount = excluded.amount, @@ -386,18 +386,24 @@ ON CONFLICT(id) DO UPDATE SET request = excluded.request, state = excluded.state, expiry = excluded.expiry, - secret_key = excluded.secret_key + secret_key = excluded.secret_key, + payment_method = excluded.payment_method, + amount_issued = excluded.amount_issued, + amount_paid = excluded.amount_paid ; "#, ) .bind(":id", quote.id.to_string()) .bind(":mint_url", quote.mint_url.to_string()) - .bind(":amount", u64::from(quote.amount) as i64) + .bind(":amount", quote.amount.map(|a| a.to_i64())) .bind(":unit", quote.unit.to_string()) .bind(":request", quote.request) .bind(":state", quote.state.to_string()) .bind(":expiry", quote.expiry as i64) .bind(":secret_key", quote.secret_key.map(|p| p.to_string())) + .bind(":payment_method", quote.payment_method.to_string()) + .bind(":amount_issued", quote.amount_issued.to_i64()) + .bind(":amount_paid", quote.amount_paid.to_i64()) .execute(&self.pool.get().map_err(Error::Pool)?) .map_err(Error::Sqlite)?; @@ -416,7 +422,10 @@ ON CONFLICT(id) DO UPDATE SET request, state, expiry, - secret_key + secret_key, + payment_method, + amount_issued, + amount_paid FROM mint_quote WHERE @@ -950,16 +959,24 @@ fn sqlite_row_to_mint_quote(row: Vec) -> Result { request, state, expiry, - secret_key + secret_key, + row_method, + row_amount_minted, + row_amount_paid ) = row ); - let amount: u64 = column_as_number!(amount); + let amount: Option = column_as_nullable_number!(amount); + + let amount_paid: u64 = column_as_number!(row_amount_paid); + let amount_minted: u64 = column_as_number!(row_amount_minted); + let payment_method = + PaymentMethod::from_str(&column_as_string!(row_method)).map_err(Error::from)?; Ok(MintQuote { id: column_as_string!(id), mint_url: column_as_string!(mint_url, MintUrl::from_str), - amount: Amount::from(amount), + amount: amount.and_then(Amount::from_i64), unit: column_as_string!(unit, CurrencyUnit::from_str), request: column_as_string!(request), state: column_as_string!(state, MintQuoteState::from_str), @@ -967,6 +984,9 @@ fn sqlite_row_to_mint_quote(row: Vec) -> Result { secret_key: column_as_nullable_string!(secret_key) .map(|v| SecretKey::from_str(&v)) .transpose()?, + payment_method, + amount_issued: amount_minted.into(), + amount_paid: amount_paid.into(), }) } diff --git a/crates/cdk/Cargo.toml b/crates/cdk/Cargo.toml index 8b9625f81..73d3a1e7f 100644 --- a/crates/cdk/Cargo.toml +++ b/crates/cdk/Cargo.toml @@ -28,6 +28,7 @@ async-trait.workspace = true anyhow.workspace = true bitcoin.workspace = true ciborium.workspace = true +lightning.workspace = true lightning-invoice.workspace = true regex.workspace = true reqwest = { workspace = true, optional = true } diff --git a/crates/cdk/src/mint/builder.rs b/crates/cdk/src/mint/builder.rs index 4f85e0575..fbdc96413 100644 --- a/crates/cdk/src/mint/builder.rs +++ b/crates/cdk/src/mint/builder.rs @@ -210,32 +210,30 @@ impl MintBuilder { self.mint_info.nuts.nut15 = mpp; } - if method == PaymentMethod::Bolt11 { - let mint_method_settings = MintMethodSettings { - method: method.clone(), - unit: unit.clone(), - min_amount: Some(limits.mint_min), - max_amount: Some(limits.mint_max), - options: Some(MintMethodOptions::Bolt11 { - description: settings.invoice_description, - }), - }; + let mint_method_settings = MintMethodSettings { + method: method.clone(), + unit: unit.clone(), + min_amount: Some(limits.mint_min), + max_amount: Some(limits.mint_max), + options: Some(MintMethodOptions::Bolt11 { + description: settings.invoice_description, + }), + }; - self.mint_info.nuts.nut04.methods.push(mint_method_settings); - self.mint_info.nuts.nut04.disabled = false; - - let melt_method_settings = MeltMethodSettings { - method, - unit, - min_amount: Some(limits.melt_min), - max_amount: Some(limits.melt_max), - options: Some(MeltMethodOptions::Bolt11 { - amountless: settings.amountless, - }), - }; - self.mint_info.nuts.nut05.methods.push(melt_method_settings); - self.mint_info.nuts.nut05.disabled = false; - } + self.mint_info.nuts.nut04.methods.push(mint_method_settings); + self.mint_info.nuts.nut04.disabled = false; + + let melt_method_settings = MeltMethodSettings { + method, + unit, + min_amount: Some(limits.melt_min), + max_amount: Some(limits.melt_max), + options: Some(MeltMethodOptions::Bolt11 { + amountless: settings.amountless, + }), + }; + self.mint_info.nuts.nut05.methods.push(melt_method_settings); + self.mint_info.nuts.nut05.disabled = false; ln.insert(ln_key.clone(), ln_backend); diff --git a/crates/cdk/src/mint/issue/issue_nut04.rs b/crates/cdk/src/mint/issue/issue_nut04.rs deleted file mode 100644 index 4b159b8dd..000000000 --- a/crates/cdk/src/mint/issue/issue_nut04.rs +++ /dev/null @@ -1,301 +0,0 @@ -use cdk_common::payment::Bolt11Settings; -use tracing::instrument; -use uuid::Uuid; - -use crate::mint::{ - CurrencyUnit, MintQuote, MintQuoteBolt11Request, MintQuoteBolt11Response, MintQuoteState, - MintRequest, MintResponse, NotificationPayload, PublicKey, Verification, -}; -use crate::nuts::PaymentMethod; -use crate::util::unix_time; -use crate::{ensure_cdk, Amount, Error, Mint}; - -impl Mint { - /// Checks that minting is enabled, request is supported unit and within range - async fn check_mint_request_acceptable( - &self, - amount: Amount, - unit: &CurrencyUnit, - ) -> Result<(), Error> { - let mint_info = self.localstore.get_mint_info().await?; - let nut04 = &mint_info.nuts.nut04; - - ensure_cdk!(!nut04.disabled, Error::MintingDisabled); - - let settings = nut04 - .get_settings(unit, &PaymentMethod::Bolt11) - .ok_or(Error::UnsupportedUnit)?; - - let is_above_max = settings - .max_amount - .is_some_and(|max_amount| amount > max_amount); - let is_below_min = settings - .min_amount - .is_some_and(|min_amount| amount < min_amount); - let is_out_of_range = is_above_max || is_below_min; - - ensure_cdk!( - !is_out_of_range, - Error::AmountOutofLimitRange( - settings.min_amount.unwrap_or_default(), - settings.max_amount.unwrap_or_default(), - amount, - ) - ); - - Ok(()) - } - - /// Create new mint bolt11 quote - #[instrument(skip_all)] - pub async fn get_mint_bolt11_quote( - &self, - mint_quote_request: MintQuoteBolt11Request, - ) -> Result, Error> { - let MintQuoteBolt11Request { - amount, - unit, - description, - pubkey, - } = mint_quote_request; - - self.check_mint_request_acceptable(amount, &unit).await?; - - let ln = self.get_payment_processor(unit.clone(), PaymentMethod::Bolt11)?; - - let mint_ttl = self.localstore.get_quote_ttl().await?.mint_ttl; - - let quote_expiry = unix_time() + mint_ttl; - - let settings = ln.get_settings().await?; - let settings: Bolt11Settings = serde_json::from_value(settings)?; - - if description.is_some() && !settings.invoice_description { - tracing::error!("Backend does not support invoice description"); - return Err(Error::InvoiceDescriptionUnsupported); - } - - let create_invoice_response = ln - .create_incoming_payment_request( - amount, - &unit, - description.unwrap_or("".to_string()), - Some(quote_expiry), - ) - .await - .map_err(|err| { - tracing::error!("Could not create invoice: {}", err); - Error::InvalidPaymentRequest - })?; - - let quote = MintQuote::new( - create_invoice_response.request.to_string(), - unit.clone(), - amount, - create_invoice_response.expiry.unwrap_or(0), - create_invoice_response.request_lookup_id.clone(), - pubkey, - ); - - tracing::debug!( - "New mint quote {} for {} {} with request id {}", - quote.id, - amount, - unit, - create_invoice_response.request_lookup_id, - ); - - let mut tx = self.localstore.begin_transaction().await?; - tx.add_or_replace_mint_quote(quote.clone()).await?; - tx.commit().await?; - - let quote: MintQuoteBolt11Response = quote.into(); - - self.pubsub_manager - .broadcast(NotificationPayload::MintQuoteBolt11Response(quote.clone())); - - Ok(quote) - } - - /// Check mint quote - #[instrument(skip(self))] - pub async fn check_mint_quote( - &self, - quote_id: &Uuid, - ) -> Result, Error> { - let mut tx = self.localstore.begin_transaction().await?; - let mut mint_quote = tx - .get_mint_quote(quote_id) - .await? - .ok_or(Error::UnknownQuote)?; - - // Since the pending state is not part of the NUT it should not be part of the - // response. In practice the wallet should not be checking the state of - // a quote while waiting for the mint response. - if mint_quote.state == MintQuoteState::Unpaid { - self.check_mint_quote_paid(tx, &mut mint_quote) - .await? - .commit() - .await?; - } - - Ok(MintQuoteBolt11Response { - quote: mint_quote.id, - request: mint_quote.request, - state: mint_quote.state, - expiry: Some(mint_quote.expiry), - pubkey: mint_quote.pubkey, - amount: Some(mint_quote.amount), - unit: Some(mint_quote.unit.clone()), - }) - } - - /// Get mint quotes - #[instrument(skip_all)] - pub async fn mint_quotes(&self) -> Result, Error> { - let quotes = self.localstore.get_mint_quotes().await?; - Ok(quotes) - } - - /// Remove mint quote - #[instrument(skip_all)] - pub async fn remove_mint_quote(&self, quote_id: &Uuid) -> Result<(), Error> { - let mut tx = self.localstore.begin_transaction().await?; - tx.remove_mint_quote(quote_id).await?; - tx.commit().await?; - - Ok(()) - } - - /// Flag mint quote as paid - #[instrument(skip_all)] - pub async fn pay_mint_quote_for_request_id( - &self, - request_lookup_id: &str, - ) -> Result<(), Error> { - if let Ok(Some(mint_quote)) = self - .localstore - .get_mint_quote_by_request_lookup_id(request_lookup_id) - .await - { - self.pay_mint_quote(&mint_quote).await?; - } - Ok(()) - } - - /// Mark mint quote as paid - #[instrument(skip_all)] - pub async fn pay_mint_quote(&self, mint_quote: &MintQuote) -> Result<(), Error> { - tracing::debug!( - "Received payment notification for mint quote {}", - mint_quote.id - ); - if mint_quote.state != MintQuoteState::Issued && mint_quote.state != MintQuoteState::Paid { - let mut tx = self.localstore.begin_transaction().await?; - tx.update_mint_quote_state(&mint_quote.id, MintQuoteState::Paid) - .await?; - tx.commit().await?; - } else { - tracing::debug!( - "{} Quote already {} continuing", - mint_quote.id, - mint_quote.state - ); - } - - self.pubsub_manager - .mint_quote_bolt11_status(mint_quote.clone(), MintQuoteState::Paid); - - Ok(()) - } - - /// Process mint request - #[instrument(skip_all)] - pub async fn process_mint_request( - &self, - mint_request: MintRequest, - ) -> Result { - let mut tx = self.localstore.begin_transaction().await?; - - let mut mint_quote = tx - .get_mint_quote(&mint_request.quote) - .await? - .ok_or(Error::UnknownQuote)?; - - let mut tx = if mint_quote.state == MintQuoteState::Unpaid { - self.check_mint_quote_paid(tx, &mut mint_quote).await? - } else { - tx - }; - - match mint_quote.state { - MintQuoteState::Unpaid => { - return Err(Error::UnpaidQuote); - } - MintQuoteState::Pending => { - return Err(Error::PendingQuote); - } - MintQuoteState::Issued => { - return Err(Error::IssuedQuote); - } - MintQuoteState::Paid => (), - } - - // If the there is a public key provoided in mint quote request - // verify the signature is provided for the mint request - if let Some(pubkey) = mint_quote.pubkey { - mint_request.verify_signature(pubkey)?; - } - - let Verification { amount, unit } = - match self.verify_outputs(&mut tx, &mint_request.outputs).await { - Ok(verification) => verification, - Err(err) => { - tracing::debug!("Could not verify mint outputs"); - return Err(err); - } - }; - - // We check the total value of blinded messages == mint quote - if amount != mint_quote.amount { - return Err(Error::TransactionUnbalanced( - mint_quote.amount.into(), - mint_request.total_amount()?.into(), - 0, - )); - } - - let unit = unit.ok_or(Error::UnsupportedUnit)?; - ensure_cdk!(unit == mint_quote.unit, Error::UnsupportedUnit); - - let mut blind_signatures = Vec::with_capacity(mint_request.outputs.len()); - - for blinded_message in mint_request.outputs.iter() { - let blind_signature = self.blind_sign(blinded_message.clone()).await?; - blind_signatures.push(blind_signature); - } - - tx.add_blind_signatures( - &mint_request - .outputs - .iter() - .map(|p| p.blinded_secret) - .collect::>(), - &blind_signatures, - Some(mint_request.quote), - ) - .await?; - - tx.update_mint_quote_state(&mint_request.quote, MintQuoteState::Issued) - .await?; - - tx.commit().await?; - - self.pubsub_manager - .mint_quote_bolt11_status(mint_quote, MintQuoteState::Issued); - - Ok(MintResponse { - signatures: blind_signatures, - }) - } -} diff --git a/crates/cdk/src/mint/issue/mod.rs b/crates/cdk/src/mint/issue/mod.rs index 9c3f84439..0cf772f0e 100644 --- a/crates/cdk/src/mint/issue/mod.rs +++ b/crates/cdk/src/mint/issue/mod.rs @@ -1,3 +1,601 @@ +use cdk_common::mint::MintQuote; +use cdk_common::payment::{ + Bolt11IncomingPaymentOptions, Bolt11Settings, Bolt12IncomingPaymentOptions, + IncomingPaymentOptions, WaitPaymentResponse, +}; +use cdk_common::util::unix_time; +use cdk_common::{ + database, ensure_cdk, Amount, CurrencyUnit, Error, MintQuoteBolt11Request, + MintQuoteBolt11Response, MintQuoteBolt12Request, MintQuoteBolt12Response, MintQuoteState, + MintRequest, MintResponse, NotificationPayload, PaymentMethod, PublicKey, +}; +use tracing::instrument; +use uuid::Uuid; + +use crate::mint::Verification; +use crate::Mint; + #[cfg(feature = "auth")] mod auth; -mod issue_nut04; + +/// Request for creating a mint quote +/// +/// This enum represents the different types of payment requests that can be used +/// to create a mint quote. +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum MintQuoteRequest { + /// Lightning Network BOLT11 invoice request + Bolt11(MintQuoteBolt11Request), + /// Lightning Network BOLT12 offer request + Bolt12(MintQuoteBolt12Request), +} + +impl From for MintQuoteRequest { + fn from(request: MintQuoteBolt11Request) -> Self { + MintQuoteRequest::Bolt11(request) + } +} + +impl From for MintQuoteRequest { + fn from(request: MintQuoteBolt12Request) -> Self { + MintQuoteRequest::Bolt12(request) + } +} + +/// Response for a mint quote request +/// +/// This enum represents the different types of payment responses that can be returned +/// when creating a mint quote. +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum MintQuoteResponse { + /// Lightning Network BOLT11 invoice response + Bolt11(MintQuoteBolt11Response), + /// Lightning Network BOLT12 offer response + Bolt12(MintQuoteBolt12Response), +} + +impl TryFrom for MintQuoteBolt11Response { + type Error = Error; + + fn try_from(response: MintQuoteResponse) -> Result { + match response { + MintQuoteResponse::Bolt11(bolt11_response) => Ok(bolt11_response), + _ => Err(Error::InvalidPaymentMethod), + } + } +} + +impl TryFrom for MintQuoteBolt12Response { + type Error = Error; + + fn try_from(response: MintQuoteResponse) -> Result { + match response { + MintQuoteResponse::Bolt12(bolt12_response) => Ok(bolt12_response), + _ => Err(Error::InvalidPaymentMethod), + } + } +} + +impl TryFrom for MintQuoteResponse { + type Error = Error; + + fn try_from(quote: MintQuote) -> Result { + match quote.payment_method { + PaymentMethod::Bolt11 => { + let bolt11_response: MintQuoteBolt11Response = quote.into(); + Ok(MintQuoteResponse::Bolt11(bolt11_response)) + } + PaymentMethod::Bolt12 => { + let bolt12_response = MintQuoteBolt12Response::try_from(quote)?; + Ok(MintQuoteResponse::Bolt12(bolt12_response)) + } + PaymentMethod::Custom(_) => Err(Error::InvalidPaymentMethod), + } + } +} + +impl From for MintQuoteBolt11Response { + fn from(response: MintQuoteResponse) -> Self { + match response { + MintQuoteResponse::Bolt11(bolt11_response) => MintQuoteBolt11Response { + quote: bolt11_response.quote.to_string(), + state: bolt11_response.state, + request: bolt11_response.request, + expiry: bolt11_response.expiry, + pubkey: bolt11_response.pubkey, + amount: bolt11_response.amount, + unit: bolt11_response.unit, + }, + _ => panic!("Expected Bolt11 response"), + } + } +} + +impl Mint { + /// Validates that a mint request meets all requirements + /// + /// Checks that: + /// - Minting is enabled for the requested payment method + /// - The currency unit is supported + /// - The amount (if provided) is within the allowed range for the payment method + /// + /// # Arguments + /// * `amount` - Optional amount to validate + /// * `unit` - Currency unit for the request + /// * `payment_method` - Payment method (Bolt11, Bolt12, etc.) + /// + /// # Returns + /// * `Ok(())` if the request is acceptable + /// * `Error` if any validation fails + pub async fn check_mint_request_acceptable( + &self, + amount: Option, + unit: &CurrencyUnit, + payment_method: &PaymentMethod, + ) -> Result<(), Error> { + let mint_info = self.localstore.get_mint_info().await?; + + let nut04 = &mint_info.nuts.nut04; + ensure_cdk!(!nut04.disabled, Error::MintingDisabled); + + let disabled = nut04.disabled; + + ensure_cdk!(!disabled, Error::MintingDisabled); + + let settings = nut04 + .get_settings(unit, payment_method) + .ok_or(Error::UnsupportedUnit)?; + + let min_amount = settings.min_amount; + let max_amount = settings.max_amount; + + // Check amount limits if an amount is provided + if let Some(amount) = amount { + let is_above_max = max_amount.is_some_and(|max_amount| amount > max_amount); + let is_below_min = min_amount.is_some_and(|min_amount| amount < min_amount); + let is_out_of_range = is_above_max || is_below_min; + + ensure_cdk!( + !is_out_of_range, + Error::AmountOutofLimitRange( + min_amount.unwrap_or_default(), + max_amount.unwrap_or_default(), + amount, + ) + ); + } + + Ok(()) + } + + /// Creates a new mint quote for the specified payment request + /// + /// Handles both Bolt11 and Bolt12 payment requests by: + /// 1. Validating the request parameters + /// 2. Creating an appropriate payment request via the payment processor + /// 3. Storing the quote in the database + /// 4. Broadcasting a notification about the new quote + /// + /// # Arguments + /// * `mint_quote_request` - The request containing payment details + /// + /// # Returns + /// * `MintQuoteResponse` - Response with payment details if successful + /// * `Error` - If the request is invalid or payment creation fails + #[instrument(skip_all)] + pub async fn get_mint_quote( + &self, + mint_quote_request: MintQuoteRequest, + ) -> Result { + let unit: CurrencyUnit; + let amount; + let pubkey; + let payment_method; + + let create_invoice_response = match mint_quote_request { + MintQuoteRequest::Bolt11(bolt11_request) => { + unit = bolt11_request.unit; + amount = Some(bolt11_request.amount); + pubkey = bolt11_request.pubkey; + payment_method = PaymentMethod::Bolt11; + + self.check_mint_request_acceptable( + Some(bolt11_request.amount), + &unit, + &payment_method, + ) + .await?; + + let ln = self.get_payment_processor(unit.clone(), PaymentMethod::Bolt11)?; + + let mint_ttl = self.localstore.get_quote_ttl().await?.mint_ttl; + + let quote_expiry = unix_time() + mint_ttl; + + let settings = ln.get_settings().await?; + let settings: Bolt11Settings = serde_json::from_value(settings)?; + + let description = bolt11_request.description; + + if description.is_some() && !settings.invoice_description { + tracing::error!("Backend does not support invoice description"); + return Err(Error::InvoiceDescriptionUnsupported); + } + + let bolt11_options = Bolt11IncomingPaymentOptions { + description, + amount: bolt11_request.amount, + unix_expiry: Some(quote_expiry), + }; + + let incoming_options = IncomingPaymentOptions::Bolt11(bolt11_options); + + ln.create_incoming_payment_request(&unit, incoming_options) + .await + .map_err(|err| { + tracing::error!("Could not create invoice: {}", err); + Error::InvalidPaymentRequest + })? + } + MintQuoteRequest::Bolt12(bolt12_request) => { + unit = bolt12_request.unit; + amount = bolt12_request.amount; + pubkey = Some(bolt12_request.pubkey); + payment_method = PaymentMethod::Bolt12; + + self.check_mint_request_acceptable(amount, &unit, &payment_method) + .await?; + + let ln = self.get_payment_processor(unit.clone(), payment_method.clone())?; + + let description = bolt12_request.description; + + let mint_ttl = self.localstore.get_quote_ttl().await?.mint_ttl; + + let expiry = unix_time() + mint_ttl; + + let bolt12_options = Bolt12IncomingPaymentOptions { + description, + amount, + unix_expiry: Some(expiry), + }; + + let incoming_options = IncomingPaymentOptions::Bolt12(Box::new(bolt12_options)); + + ln.create_incoming_payment_request(&unit, incoming_options) + .await + .map_err(|err| { + tracing::error!("Could not create invoice: {}", err); + Error::InvalidPaymentRequest + })? + } + }; + + let quote = MintQuote::new( + None, + create_invoice_response.request.to_string(), + unit.clone(), + amount, + create_invoice_response.expiry.unwrap_or(0), + create_invoice_response.request_lookup_id.clone(), + pubkey, + Amount::ZERO, + Amount::ZERO, + payment_method.clone(), + unix_time(), + vec![], + vec![], + ); + + tracing::debug!( + "New {} mint quote {} for {:?} {} with request id {:?}", + payment_method, + quote.id, + amount, + unit, + create_invoice_response.request_lookup_id, + ); + + let mut tx = self.localstore.begin_transaction().await?; + tx.add_mint_quote(quote.clone()).await?; + tx.commit().await?; + + match payment_method { + PaymentMethod::Bolt11 => { + let res: MintQuoteBolt11Response = quote.clone().into(); + self.pubsub_manager + .broadcast(NotificationPayload::MintQuoteBolt11Response(res)); + } + PaymentMethod::Bolt12 => { + let res: MintQuoteBolt12Response = quote.clone().try_into()?; + self.pubsub_manager + .broadcast(NotificationPayload::MintQuoteBolt12Response(res)); + } + PaymentMethod::Custom(_) => {} + } + + quote.try_into() + } + + /// Retrieves all mint quotes from the database + /// + /// # Returns + /// * `Vec` - List of all mint quotes + /// * `Error` if database access fails + #[instrument(skip_all)] + pub async fn mint_quotes(&self) -> Result, Error> { + let quotes = self.localstore.get_mint_quotes().await?; + Ok(quotes) + } + + /// Removes a mint quote from the database + /// + /// # Arguments + /// * `quote_id` - The UUID of the quote to remove + /// + /// # Returns + /// * `Ok(())` if removal was successful + /// * `Error` if the quote doesn't exist or removal fails + #[instrument(skip_all)] + pub async fn remove_mint_quote(&self, quote_id: &Uuid) -> Result<(), Error> { + let mut tx = self.localstore.begin_transaction().await?; + tx.remove_mint_quote(quote_id).await?; + tx.commit().await?; + + Ok(()) + } + + /// Marks a mint quote as paid based on the payment request ID + /// + /// Looks up the mint quote by the payment request ID and marks it as paid + /// if found. + /// + /// # Arguments + /// * `wait_payment_response` - Payment response containing payment details + /// + /// # Returns + /// * `Ok(())` if the quote was found and updated + /// * `Error` if the update fails + #[instrument(skip_all)] + pub async fn pay_mint_quote_for_request_id( + &self, + wait_payment_response: WaitPaymentResponse, + ) -> Result<(), Error> { + if wait_payment_response.payment_amount == Amount::ZERO { + tracing::warn!( + "Received payment response with 0 amount with payment id {}.", + wait_payment_response.payment_id + ); + + return Err(Error::AmountUndefined); + } + + let mut tx = self.localstore.begin_transaction().await?; + + if let Ok(Some(mint_quote)) = tx + .get_mint_quote_by_request_lookup_id(&wait_payment_response.payment_identifier) + .await + { + self.pay_mint_quote(&mut tx, &mint_quote, wait_payment_response) + .await?; + } else { + tracing::warn!( + "Could not get request for request lookup id {:?}.", + wait_payment_response.payment_identifier + ); + } + + tx.commit().await?; + + Ok(()) + } + + /// Marks a specific mint quote as paid + /// + /// Updates the mint quote with payment information and broadcasts + /// a notification about the payment status change. + /// + /// # Arguments + /// * `mint_quote` - The mint quote to mark as paid + /// * `wait_payment_response` - Payment response containing payment details + /// + /// # Returns + /// * `Ok(())` if the update was successful + /// * `Error` if the update fails + #[instrument(skip_all)] + pub async fn pay_mint_quote( + &self, + tx: &mut Box + Send + Sync + '_>, + mint_quote: &MintQuote, + wait_payment_response: WaitPaymentResponse, + ) -> Result<(), Error> { + tracing::debug!( + "Received payment notification of {} for mint quote {} with payment id {}", + wait_payment_response.payment_amount, + mint_quote.id, + wait_payment_response.payment_id + ); + + let quote_state = mint_quote.state(); + if !mint_quote + .payment_ids() + .contains(&&wait_payment_response.payment_id) + { + if mint_quote.payment_method == PaymentMethod::Bolt11 + && (quote_state == MintQuoteState::Issued || quote_state == MintQuoteState::Paid) + { + tracing::info!("Received payment notification for already seen payment."); + } else { + tx.increment_mint_quote_amount_paid( + &mint_quote.id, + wait_payment_response.payment_amount, + wait_payment_response.payment_id, + ) + .await?; + + self.pubsub_manager + .mint_quote_bolt11_status(mint_quote.clone(), MintQuoteState::Paid); + } + } else { + tracing::info!("Received payment notification for already seen payment."); + } + + Ok(()) + } + + /// Checks the status of a mint quote and updates it if necessary + /// + /// If the quote is unpaid, this will check if payment has been received. + /// Returns the current state of the quote. + /// + /// # Arguments + /// * `quote_id` - The UUID of the quote to check + /// + /// # Returns + /// * `MintQuoteResponse` - The current state of the quote + /// * `Error` if the quote doesn't exist or checking fails + #[instrument(skip(self))] + pub async fn check_mint_quote(&self, quote_id: &Uuid) -> Result { + let mut quote = self + .localstore + .get_mint_quote(quote_id) + .await? + .ok_or(Error::UnknownQuote)?; + + self.check_mint_quote_paid(&mut quote).await?; + + quote.try_into() + } + + /// Processes a mint request to issue new tokens + /// + /// This function: + /// 1. Verifies the mint quote exists and is paid + /// 2. Validates the request signature if a pubkey was provided + /// 3. Verifies the outputs match the expected amount + /// 4. Signs the blinded messages + /// 5. Updates the quote status + /// 6. Broadcasts a notification about the status change + /// + /// # Arguments + /// * `mint_request` - The mint request containing blinded outputs to sign + /// + /// # Returns + /// * `MintBolt11Response` - Response containing blind signatures + /// * `Error` if validation fails or signing fails + #[instrument(skip_all)] + pub async fn process_mint_request( + &self, + mint_request: MintRequest, + ) -> Result { + let mut mint_quote = self + .localstore + .get_mint_quote(&mint_request.quote) + .await? + .ok_or(Error::UnknownQuote)?; + + self.check_mint_quote_paid(&mut mint_quote).await?; + + let mut tx = self.localstore.begin_transaction().await?; + + let mint_quote = tx + .get_mint_quote(&mint_request.quote) + .await? + .ok_or(Error::UnknownQuote)?; + + match mint_quote.state() { + MintQuoteState::Unpaid => { + return Err(Error::UnpaidQuote); + } + MintQuoteState::Issued => { + if mint_quote.payment_method == PaymentMethod::Bolt12 + && mint_quote.amount_paid() > mint_quote.amount_issued() + { + tracing::warn!("Mint quote should state should have been set to issued upon new payment. Something isn't right. Stopping mint"); + } + + return Err(Error::IssuedQuote); + } + MintQuoteState::Paid => (), + } + + if mint_quote.payment_method == PaymentMethod::Bolt12 && mint_quote.pubkey.is_none() { + tracing::warn!("Bolt12 mint quote created without pubkey"); + return Err(Error::SignatureMissingOrInvalid); + } + + let mint_amount = match mint_quote.payment_method { + PaymentMethod::Bolt11 => mint_quote.amount.ok_or(Error::AmountUndefined)?, + PaymentMethod::Bolt12 => { + if mint_quote.amount_issued() > mint_quote.amount_paid() { + tracing::error!( + "Quote state should not be issued if issued {} is > paid {}.", + mint_quote.amount_issued(), + mint_quote.amount_paid() + ); + return Err(Error::UnpaidQuote); + } + mint_quote.amount_paid() - mint_quote.amount_issued() + } + _ => return Err(Error::UnsupportedPaymentMethod), + }; + + // If the there is a public key provoided in mint quote request + // verify the signature is provided for the mint request + if let Some(pubkey) = mint_quote.pubkey { + mint_request.verify_signature(pubkey)?; + } + + let Verification { amount, unit } = + match self.verify_outputs(&mut tx, &mint_request.outputs).await { + Ok(verification) => verification, + Err(err) => { + tracing::debug!("Could not verify mint outputs"); + + return Err(err); + } + }; + + // We check the total value of blinded messages == mint quote + if amount != mint_amount { + return Err(Error::TransactionUnbalanced( + mint_amount.into(), + mint_request.total_amount()?.into(), + 0, + )); + } + + let unit = unit.ok_or(Error::UnsupportedUnit).unwrap(); + ensure_cdk!(unit == mint_quote.unit, Error::UnsupportedUnit); + + let mut blind_signatures = Vec::with_capacity(mint_request.outputs.len()); + + for blinded_message in mint_request.outputs.iter() { + let blind_signature = self.blind_sign(blinded_message.clone()).await?; + blind_signatures.push(blind_signature); + } + + tx.add_blind_signatures( + &mint_request + .outputs + .iter() + .map(|p| p.blinded_secret) + .collect::>(), + &blind_signatures, + Some(mint_request.quote), + ) + .await?; + + tx.increment_mint_quote_amount_issued(&mint_request.quote, mint_request.total_amount()?) + .await?; + + tx.commit().await?; + + self.pubsub_manager + .mint_quote_bolt11_status(mint_quote, MintQuoteState::Issued); + + Ok(MintResponse { + signatures: blind_signatures, + }) + } +} diff --git a/crates/cdk/src/mint/ln.rs b/crates/cdk/src/mint/ln.rs index d23122a0f..5ffb3e4aa 100644 --- a/crates/cdk/src/mint/ln.rs +++ b/crates/cdk/src/mint/ln.rs @@ -1,21 +1,31 @@ +use cdk_common::amount::to_unit; use cdk_common::common::PaymentProcessorKey; -use cdk_common::database::{self, MintTransaction}; use cdk_common::mint::MintQuote; -use cdk_common::MintQuoteState; +use cdk_common::util::unix_time; +use cdk_common::{MintQuoteState, PaymentMethod}; +use tracing::instrument; use super::Mint; use crate::Error; impl Mint { /// Check the status of an ln payment for a quote - pub async fn check_mint_quote_paid( - &self, - tx: Box + Send + Sync + '_>, - quote: &mut MintQuote, - ) -> Result + Send + Sync + '_>, Error> { + #[instrument(skip_all)] + pub async fn check_mint_quote_paid(&self, quote: &mut MintQuote) -> Result<(), Error> { + let state = quote.state(); + + // We can just return here and do not need to check with ln node. + // If quote is issued it is already in a final state, + // If it is paid ln node will only tell us what we already know + if quote.payment_method == PaymentMethod::Bolt11 + && (state == MintQuoteState::Issued || state == MintQuoteState::Paid) + { + return Ok(()); + } + let ln = match self.ln.get(&PaymentProcessorKey::new( quote.unit.clone(), - cdk_common::PaymentMethod::Bolt11, + quote.payment_method.clone(), )) { Some(ln) => ln, None => { @@ -25,23 +35,30 @@ impl Mint { } }; - tx.commit().await?; - let ln_status = ln .check_incoming_payment_status("e.request_lookup_id) .await?; let mut tx = self.localstore.begin_transaction().await?; - if ln_status != quote.state && quote.state != MintQuoteState::Issued { - tx.update_mint_quote_state("e.id, ln_status).await?; + for payment in ln_status { + if !quote.payment_ids().contains(&&payment.payment_id) { + tracing::debug!("Found payment for quote {} when checking.", quote.id); + let amount_paid = to_unit(payment.payment_amount, &payment.unit, "e.unit)?; - quote.state = ln_status; + quote.increment_amount_paid(amount_paid)?; + quote.add_payment(amount_paid, payment.payment_id.clone(), unix_time())?; - self.pubsub_manager - .mint_quote_bolt11_status(quote.clone(), ln_status); + tx.increment_mint_quote_amount_paid("e.id, amount_paid, payment.payment_id) + .await?; + + self.pubsub_manager + .mint_quote_bolt11_status(quote.clone(), MintQuoteState::Paid); + } } - Ok(tx) + tx.commit().await?; + + Ok(()) } } diff --git a/crates/cdk/src/mint/melt.rs b/crates/cdk/src/mint/melt.rs index 544bab97f..d0792ca0c 100644 --- a/crates/cdk/src/mint/melt.rs +++ b/crates/cdk/src/mint/melt.rs @@ -1,11 +1,18 @@ use std::str::FromStr; use anyhow::bail; +use cdk_common::amount::amount_for_offer; use cdk_common::database::{self, MintTransaction}; +use cdk_common::melt::MeltQuoteRequest; +use cdk_common::mint::MeltPaymentRequest; use cdk_common::nut00::ProofsMethods; use cdk_common::nut05::MeltMethodOptions; -use cdk_common::MeltOptions; -use lightning_invoice::Bolt11Invoice; +use cdk_common::payment::{ + Bolt11OutgoingPaymentOptions, Bolt12OutgoingPaymentOptions, OutgoingPaymentOptions, + PaymentQuoteOptions, +}; +use cdk_common::{MeltOptions, MeltQuoteBolt12Request}; +use lightning::offers::offer::Offer; use tracing::instrument; use uuid::Uuid; @@ -65,10 +72,12 @@ impl Mint { amount } Some(MeltOptions::Amountless { amountless: _ }) => { - if !matches!( - settings.options, - Some(MeltMethodOptions::Bolt11 { amountless: true }) - ) { + if method == PaymentMethod::Bolt11 + && !matches!( + settings.options, + Some(MeltMethodOptions::Bolt11 { amountless: true }) + ) + { return Err(Error::AmountlessInvoiceNotSupported(unit, method)); } @@ -97,9 +106,28 @@ impl Mint { } } - /// Get melt bolt11 quote + /// Get melt quote for either BOLT11 or BOLT12 + /// + /// This function accepts a `MeltQuoteRequest` enum and delegates to the + /// appropriate handler based on the request type. + #[instrument(skip_all)] + pub async fn get_melt_quote( + &self, + melt_quote_request: MeltQuoteRequest, + ) -> Result, Error> { + match melt_quote_request { + MeltQuoteRequest::Bolt11(bolt11_request) => { + self.get_melt_bolt11_quote_impl(&bolt11_request).await + } + MeltQuoteRequest::Bolt12(bolt12_request) => { + self.get_melt_bolt12_quote_impl(&bolt12_request).await + } + } + } + + /// Implementation of get_melt_bolt11_quote #[instrument(skip_all)] - pub async fn get_melt_bolt11_quote( + async fn get_melt_bolt11_quote_impl( &self, melt_request: &MeltQuoteBolt11Request, ) -> Result, Error> { @@ -110,6 +138,19 @@ impl Mint { .. } = melt_request; + let amount_msats = melt_request.amount_msat()?; + + let amount_quote_unit = to_unit(amount_msats, &CurrencyUnit::Msat, unit)?; + + self.check_melt_request_acceptable( + amount_quote_unit, + unit.clone(), + PaymentMethod::Bolt11, + request.to_string(), + *options, + ) + .await?; + let ln = self .ln .get(&PaymentProcessorKey::new( @@ -122,11 +163,17 @@ impl Mint { Error::UnsupportedUnit })?; + let bolt11 = Bolt11OutgoingPaymentOptions { + bolt11: melt_request.request.clone(), + max_fee_amount: None, + timeout_secs: None, + melt_options: melt_request.options, + }; + let payment_quote = ln .get_payment_quote( - &melt_request.request.to_string(), &melt_request.unit, - melt_request.options, + OutgoingPaymentOptions::Bolt11(Box::new(bolt11)), ) .await .map_err(|err| { @@ -139,62 +186,137 @@ impl Mint { Error::UnsupportedUnit })?; - self.check_melt_request_acceptable( - payment_quote.amount, + let melt_ttl = self.localstore.get_quote_ttl().await?.melt_ttl; + + let quote = MeltQuote::new( + MeltPaymentRequest::Bolt11 { + bolt11: request.clone(), + }, unit.clone(), + payment_quote.amount, + payment_quote.fee, + unix_time() + melt_ttl, + payment_quote.request_lookup_id.clone(), + *options, PaymentMethod::Bolt11, - request.to_string(), + ); + + tracing::debug!( + "New melt quote {} for {} {} with request id {}", + quote.id, + amount_quote_unit, + unit, + payment_quote.request_lookup_id + ); + + let mut tx = self.localstore.begin_transaction().await?; + tx.add_melt_quote(quote.clone()).await?; + tx.commit().await?; + + Ok(quote.into()) + } + + /// Implementation of get_melt_bolt12_quote + #[instrument(skip_all)] + async fn get_melt_bolt12_quote_impl( + &self, + melt_request: &MeltQuoteBolt12Request, + ) -> Result, Error> { + let MeltQuoteBolt12Request { + request, + unit, + options, + } = melt_request; + + let offer = Offer::from_str(request).map_err(|_| Error::InvalidPaymentRequest)?; + + let amount = match options { + Some(options) => match options { + MeltOptions::Amountless { amountless } => { + to_unit(amountless.amount_msat, &CurrencyUnit::Msat, unit)? + } + _ => return Err(Error::UnsupportedUnit), + }, + None => amount_for_offer(&offer, unit).map_err(|_| Error::UnsupportedUnit)?, + }; + + self.check_melt_request_acceptable( + amount, + unit.clone(), + PaymentMethod::Bolt12, + request.clone(), *options, ) .await?; - // We only want to set the msats_to_pay of the melt quote if the invoice is amountless - // or we want to ignore the amount and do an mpp payment - let msats_to_pay = options.map(|opt| opt.amount_msat()); + let ln = self + .ln + .get(&PaymentProcessorKey::new( + unit.clone(), + PaymentMethod::Bolt12, + )) + .ok_or_else(|| { + tracing::info!("Could not get ln backend for {}, bolt12 ", unit); + + Error::UnsupportedUnit + })?; - let melt_ttl = self.localstore.get_quote_ttl().await?.melt_ttl; + let offer = Offer::from_str(&melt_request.request).map_err(|_| Error::Bolt12parse)?; + + let outgoing_payment_options = Bolt12OutgoingPaymentOptions { + offer: offer.clone(), + max_fee_amount: None, + timeout_secs: None, + melt_options: *options, + invoice: None, + }; + + let payment_quote = ln + .get_payment_quote( + &melt_request.unit, + OutgoingPaymentOptions::Bolt12(Box::new(outgoing_payment_options)), + ) + .await + .map_err(|err| { + tracing::error!( + "Could not get payment quote for mint quote, {} bolt12, {}", + unit, + err + ); + + Error::UnsupportedUnit + })?; + + let invoice = payment_quote.options.and_then(|options| match options { + PaymentQuoteOptions::Bolt12 { invoice } => invoice, + }); + + let payment_request = MeltPaymentRequest::Bolt12 { + offer: Box::new(offer), + invoice, + }; let quote = MeltQuote::new( - request.to_string(), + payment_request, unit.clone(), payment_quote.amount, payment_quote.fee, - unix_time() + melt_ttl, + unix_time() + self.quote_ttl().await?.melt_ttl, payment_quote.request_lookup_id.clone(), - msats_to_pay, + *options, + PaymentMethod::Bolt12, ); tracing::debug!( "New melt quote {} for {} {} with request id {}", quote.id, - payment_quote.amount, + amount, unit, payment_quote.request_lookup_id ); let mut tx = self.localstore.begin_transaction().await?; - if let Some(mut from_db_quote) = tx.get_melt_quote("e.id).await? { - if from_db_quote.state != quote.state { - tx.update_melt_quote_state("e.id, from_db_quote.state) - .await?; - from_db_quote.state = quote.state; - } - if from_db_quote.request_lookup_id != quote.request_lookup_id { - tx.update_melt_quote_request_lookup_id("e.id, "e.request_lookup_id) - .await?; - from_db_quote.request_lookup_id = quote.request_lookup_id.clone(); - } - if from_db_quote != quote { - return Err(Error::Internal); - } - } else if let Err(err) = tx.add_melt_quote(quote.clone()).await { - match err { - database::Error::Duplicate => { - return Err(Error::RequestAlreadyPaid); - } - _ => return Err(Error::from(err)), - } - } + tx.add_melt_quote(quote.clone()).await?; tx.commit().await?; Ok(quote.into()) @@ -228,7 +350,7 @@ impl Mint { fee_reserve: quote.fee_reserve, payment_preimage: quote.payment_preimage, change, - request: Some(quote.request.clone()), + request: Some(quote.request.to_string()), unit: Some(quote.unit.clone()), }) } @@ -247,16 +369,40 @@ impl Mint { melt_quote: &MeltQuote, melt_request: &MeltRequest, ) -> Result, Error> { - let invoice = Bolt11Invoice::from_str(&melt_quote.request)?; - let quote_msats = to_unit(melt_quote.amount, &melt_quote.unit, &CurrencyUnit::Msat) .expect("Quote unit is checked above that it can convert to msat"); - let invoice_amount_msats: Amount = match invoice.amount_milli_satoshis() { - Some(amt) => amt.into(), - None => melt_quote - .msat_to_pay - .ok_or(Error::InvoiceAmountUndefined)?, + let invoice_amount_msats = match &melt_quote.request { + MeltPaymentRequest::Bolt11 { bolt11 } => match bolt11.amount_milli_satoshis() { + Some(amount) => amount.into(), + None => melt_quote + .options + .ok_or(Error::InvoiceAmountUndefined)? + .amount_msat(), + }, + MeltPaymentRequest::Bolt12 { offer, invoice: _ } => match offer.amount() { + Some(amount) => { + let (amount, currency) = match amount { + lightning::offers::offer::Amount::Bitcoin { amount_msats } => { + (amount_msats, CurrencyUnit::Msat) + } + lightning::offers::offer::Amount::Currency { + iso4217_code, + amount, + } => ( + amount, + CurrencyUnit::from_str(&String::from_utf8(iso4217_code.to_vec())?)?, + ), + }; + + to_unit(amount, ¤cy, &CurrencyUnit::Msat) + .map_err(|_err| Error::UnsupportedUnit)? + } + None => melt_quote + .options + .ok_or(Error::InvoiceAmountUndefined)? + .amount_msat(), + }, }; let partial_amount = match invoice_amount_msats > quote_msats { @@ -273,7 +419,7 @@ impl Mint { .map_err(|_| Error::UnsupportedUnit)?, }; - let inputs_amount_quote_unit = melt_request.proofs_amount().map_err(|_| { + let inputs_amount_quote_unit = melt_request.inputs_amount().map_err(|_| { tracing::error!("Proof inputs in melt quote overflowed"); Error::AmountOverflow })?; @@ -305,7 +451,7 @@ impl Mint { melt_request: &MeltRequest, ) -> Result<(ProofWriter, MeltQuote), Error> { let (state, quote) = tx - .update_melt_quote_state(melt_request.quote(), MeltQuoteState::Pending) + .update_melt_quote_state(melt_request.quote(), MeltQuoteState::Pending, None) .await?; match state { @@ -371,7 +517,7 @@ impl Mint { /// Melt Bolt11 #[instrument(skip_all)] - pub async fn melt_bolt11( + pub async fn melt( &self, melt_request: &MeltRequest, ) -> Result, Error> { @@ -455,7 +601,7 @@ impl Mint { tx.commit().await?; let pre = match ln - .make_payment(quote.clone(), partial_amount, Some(quote.fee_reserve)) + .make_payment("e.unit, quote.clone().try_into()?) .await { Ok(pay) @@ -602,8 +748,12 @@ impl Mint { .update_proofs_states(&mut tx, &input_ys, State::Spent) .await?; - tx.update_melt_quote_state(melt_request.quote(), MeltQuoteState::Paid) - .await?; + tx.update_melt_quote_state( + melt_request.quote(), + MeltQuoteState::Paid, + payment_preimage.clone(), + ) + .await?; self.pubsub_manager.melt_quote_status( "e, @@ -615,7 +765,7 @@ impl Mint { let mut change = None; // Check if there is change to return - if melt_request.proofs_amount()? > total_spent { + if melt_request.inputs_amount()? > total_spent { // Check if wallet provided change outputs if let Some(outputs) = melt_request.outputs().clone() { let blinded_messages: Vec = @@ -636,7 +786,7 @@ impl Mint { let fee = self.get_proofs_fee(melt_request.inputs()).await?; - let change_target = melt_request.proofs_amount()? - total_spent - fee; + let change_target = melt_request.inputs_amount()? - total_spent - fee; let mut amounts = change_target.split(); let mut change_sigs = Vec::with_capacity(amounts.len()); @@ -689,7 +839,7 @@ impl Mint { fee_reserve: quote.fee_reserve, state: MeltQuoteState::Paid, expiry: quote.expiry, - request: Some(quote.request.clone()), + request: Some(quote.request.to_string()), unit: Some(quote.unit.clone()), }) } diff --git a/crates/cdk/src/mint/mod.rs b/crates/cdk/src/mint/mod.rs index d9285a01d..bd89527a0 100644 --- a/crates/cdk/src/mint/mod.rs +++ b/crates/cdk/src/mint/mod.rs @@ -254,11 +254,32 @@ impl Mint { let mut join_set = JoinSet::new(); + let mut processor_groups: Vec<( + Arc + Send + Sync>, + Vec, + )> = Vec::new(); + for (key, ln) in self.ln.iter() { + // Check if we already have this processor + let found = processor_groups.iter_mut().find(|(proc_ref, _)| { + // Compare Arc pointer equality using ptr_eq + Arc::ptr_eq(proc_ref, ln) + }); + + if let Some((_, keys)) = found { + // We found this processor, add the key to its group + keys.push(key.clone()); + } else { + // New processor, create a new group + processor_groups.push((Arc::clone(ln), vec![key.clone()])); + } + } + + for (ln, key) in processor_groups { if !ln.is_wait_invoice_active() { tracing::info!("Wait payment for {:?} inactive starting.", key); let mint = Arc::clone(&mint_arc); - let ln = Arc::clone(ln); + let ln = Arc::clone(&ln); let shutdown = Arc::clone(&shutdown); let key = key.clone(); join_set.spawn(async move { @@ -274,7 +295,7 @@ impl Mint { match result { Ok(mut stream) => { while let Some(request_lookup_id) = stream.next().await { - if let Err(err) = mint.pay_mint_quote_for_request_id(&request_lookup_id).await { + if let Err(err) = mint.pay_mint_quote_for_request_id(request_lookup_id).await { tracing::warn!("{:?}", err); } } @@ -416,7 +437,10 @@ impl Mint { melt_quote: &MeltQuote, melt_request: &MeltRequest, ) -> Result, Error> { - let mint_quote = match tx.get_mint_quote_by_request(&melt_quote.request).await { + let mint_quote = match tx + .get_mint_quote_by_request(&melt_quote.request.to_string()) + .await + { Ok(Some(mint_quote)) => mint_quote, // Not an internal melt -> mint Ok(None) => return Ok(None), @@ -428,31 +452,32 @@ impl Mint { tracing::error!("internal stuff"); // Mint quote has already been settled, proofs should not be burned or held. - if mint_quote.state == MintQuoteState::Issued || mint_quote.state == MintQuoteState::Paid { + if mint_quote.state() == MintQuoteState::Issued + || mint_quote.state() == MintQuoteState::Paid + { return Err(Error::RequestAlreadyPaid); } - let inputs_amount_quote_unit = melt_request.proofs_amount().map_err(|_| { + let inputs_amount_quote_unit = melt_request.inputs_amount().map_err(|_| { tracing::error!("Proof inputs in melt quote overflowed"); Error::AmountOverflow })?; - let mut mint_quote = mint_quote; - - if mint_quote.amount > inputs_amount_quote_unit { - tracing::debug!( - "Not enough inuts provided: {} needed {}", - inputs_amount_quote_unit, - mint_quote.amount - ); - return Err(Error::InsufficientFunds); + if let Some(amount) = mint_quote.amount { + if amount > inputs_amount_quote_unit { + tracing::debug!( + "Not enough inuts provided: {} needed {}", + inputs_amount_quote_unit, + amount + ); + return Err(Error::InsufficientFunds); + } } - mint_quote.state = MintQuoteState::Paid; - let amount = melt_quote.amount; - tx.add_or_replace_mint_quote(mint_quote).await?; + tx.increment_mint_quote_amount_paid(&mint_quote.id, amount, melt_quote.id.to_string()) + .await?; Ok(Some(amount)) } diff --git a/crates/cdk/src/mint/start_up_check.rs b/crates/cdk/src/mint/start_up_check.rs index 95f09467a..fa265a085 100644 --- a/crates/cdk/src/mint/start_up_check.rs +++ b/crates/cdk/src/mint/start_up_check.rs @@ -10,7 +10,7 @@ use crate::types::PaymentProcessorKey; impl Mint { /// Checks the states of melt quotes that are **PENDING** or **UNKNOWN** to the mint with the ln node pub async fn check_pending_melt_quotes(&self) -> Result<(), Error> { - let melt_quotes = self.localstore.get_melt_quotes().await?; + let melt_quotes = self.localstore.get_melt_quotes().await.unwrap(); let pending_quotes: Vec = melt_quotes .into_iter() .filter(|q| q.state == MeltQuoteState::Pending || q.state == MeltQuoteState::Unknown) @@ -53,7 +53,11 @@ impl Mint { }; if let Err(err) = tx - .update_melt_quote_state(&pending_quote.id, melt_quote_state) + .update_melt_quote_state( + &pending_quote.id, + melt_quote_state, + pay_invoice_response.payment_proof, + ) .await { tracing::error!( diff --git a/crates/cdk/src/mint/subscription/on_subscription.rs b/crates/cdk/src/mint/subscription/on_subscription.rs index 829cc6e15..efb3598e5 100644 --- a/crates/cdk/src/mint/subscription/on_subscription.rs +++ b/crates/cdk/src/mint/subscription/on_subscription.rs @@ -48,6 +48,12 @@ impl OnNewSubscription for OnSubscription { Notification::MintQuoteBolt11(uuid) => { mint_queries.push(datastore.get_mint_quote(uuid)) } + Notification::MintQuoteBolt12(uuid) => { + mint_queries.push(datastore.get_mint_quote(uuid)) + } + Notification::MeltQuoteBolt12(uuid) => { + melt_queries.push(datastore.get_melt_quote(uuid)) + } } } diff --git a/crates/cdk/src/wallet/mint.rs b/crates/cdk/src/wallet/issue/issue_bolt11.rs similarity index 92% rename from crates/cdk/src/wallet/mint.rs rename to crates/cdk/src/wallet/issue/issue_bolt11.rs index 11def1e70..45cddfb98 100644 --- a/crates/cdk/src/wallet/mint.rs +++ b/crates/cdk/src/wallet/issue/issue_bolt11.rs @@ -1,10 +1,10 @@ use std::collections::HashMap; use cdk_common::nut04::MintMethodOptions; -use cdk_common::wallet::{Transaction, TransactionDirection}; +use cdk_common::wallet::{MintQuote, Transaction, TransactionDirection}; +use cdk_common::PaymentMethod; use tracing::instrument; -use super::MintQuote; use crate::amount::SplitTarget; use crate::dhke::construct_proofs; use crate::nuts::nut00::ProofsMethods; @@ -81,16 +81,16 @@ impl Wallet { let quote_res = self.client.post_mint_quote(request).await?; - let quote = MintQuote { + let quote = MintQuote::new( + quote_res.quote, mint_url, - id: quote_res.quote, - amount, + PaymentMethod::Bolt11, + Some(amount), unit, - request: quote_res.request, - state: quote_res.state, - expiry: quote_res.expiry.unwrap_or(0), - secret_key: Some(secret_key), - }; + quote_res.request, + quote_res.expiry.unwrap_or(0), + Some(secret_key), + ); self.localstore.add_mint_quote(quote.clone()).await?; @@ -196,6 +196,17 @@ impl Wallet { .await? .ok_or(Error::UnknownQuote)?; + if quote_info.payment_method != PaymentMethod::Bolt11 { + return Err(Error::UnsupportedPaymentMethod); + } + + let amount_mintable = quote_info.amount_mintable(); + + if amount_mintable == Amount::ZERO { + tracing::debug!("Amount mintable 0."); + return Err(Error::AmountUndefined); + } + let unix_time = unix_time(); if quote_info.expiry > unix_time { @@ -214,7 +225,7 @@ impl Wallet { let premint_secrets = match &spending_conditions { Some(spending_conditions) => PreMintSecrets::with_conditions( active_keyset_id, - quote_info.amount, + amount_mintable, &amount_split_target, spending_conditions, )?, @@ -222,7 +233,7 @@ impl Wallet { active_keyset_id, count, self.xpriv, - quote_info.amount, + amount_mintable, &amount_split_target, )?, }; diff --git a/crates/cdk/src/wallet/issue/issue_bolt12.rs b/crates/cdk/src/wallet/issue/issue_bolt12.rs new file mode 100644 index 000000000..9fb591a85 --- /dev/null +++ b/crates/cdk/src/wallet/issue/issue_bolt12.rs @@ -0,0 +1,258 @@ +use std::collections::HashMap; + +use cdk_common::nut04::MintMethodOptions; +use cdk_common::nut24::MintQuoteBolt12Request; +use cdk_common::wallet::{Transaction, TransactionDirection}; +use cdk_common::{Proofs, SecretKey}; +use tracing::instrument; + +use crate::amount::SplitTarget; +use crate::dhke::construct_proofs; +use crate::nuts::nut00::ProofsMethods; +use crate::nuts::{ + nut12, MintQuoteBolt12Response, MintRequest, PaymentMethod, PreMintSecrets, SpendingConditions, + State, +}; +use crate::types::ProofInfo; +use crate::util::unix_time; +use crate::wallet::MintQuote; +use crate::{Amount, Error, Wallet}; + +impl Wallet { + /// Mint Bolt12 + #[instrument(skip(self))] + pub async fn mint_bolt12_quote( + &self, + amount: Option, + description: Option, + ) -> Result { + let mint_url = self.mint_url.clone(); + let unit = &self.unit; + + // If we have a description, we check that the mint supports it. + if description.is_some() { + let mint_method_settings = self + .localstore + .get_mint(mint_url.clone()) + .await? + .ok_or(Error::IncorrectMint)? + .nuts + .nut04 + .get_settings(unit, &crate::nuts::PaymentMethod::Bolt12) + .ok_or(Error::UnsupportedUnit)?; + + match mint_method_settings.options { + Some(MintMethodOptions::Bolt11 { description }) if description => (), + _ => return Err(Error::InvoiceDescriptionUnsupported), + } + } + + let secret_key = SecretKey::generate(); + + let mint_request = MintQuoteBolt12Request { + amount, + unit: self.unit.clone(), + description, + pubkey: secret_key.public_key(), + }; + + let quote_res = self.client.post_mint_bolt12_quote(mint_request).await?; + + let quote = MintQuote::new( + quote_res.quote, + mint_url, + PaymentMethod::Bolt12, + amount, + unit.clone(), + quote_res.request, + quote_res.expiry.unwrap_or(0), + Some(secret_key), + ); + + self.localstore.add_mint_quote(quote.clone()).await?; + + Ok(quote) + } + + /// Mint bolt12 + #[instrument(skip(self))] + pub async fn mint_bolt12( + &self, + quote_id: &str, + amount: Option, + amount_split_target: SplitTarget, + spending_conditions: Option, + ) -> Result { + // Check that mint is in store of mints + if self + .localstore + .get_mint(self.mint_url.clone()) + .await? + .is_none() + { + self.get_mint_info().await?; + } + + let quote_info = self.localstore.get_mint_quote(quote_id).await?; + + let quote_info = if let Some(quote) = quote_info { + if quote.expiry.le(&unix_time()) && quote.expiry.ne(&0) { + return Err(Error::ExpiredQuote(quote.expiry, unix_time())); + } + + quote.clone() + } else { + return Err(Error::UnknownQuote); + }; + + let active_keyset_id = self.get_active_mint_keyset().await?.id; + + let count = self + .localstore + .get_keyset_counter(&active_keyset_id) + .await?; + + let count = count.map_or(0, |c| c + 1); + + let amount = match amount { + Some(amount) => amount, + None => { + // If an amount it not supplied with check the status of the quote + // The mint will tell us how much can be minted + let state = self.mint_bolt12_quote_state(quote_id).await?; + + state.amount_paid - state.amount_issued + } + }; + + if amount == Amount::ZERO { + tracing::error!("Cannot mint zero amount."); + return Err(Error::InvoiceAmountUndefined); + } + + let premint_secrets = match &spending_conditions { + Some(spending_conditions) => PreMintSecrets::with_conditions( + active_keyset_id, + amount, + &amount_split_target, + spending_conditions, + )?, + None => PreMintSecrets::from_xpriv( + active_keyset_id, + count, + self.xpriv, + amount, + &amount_split_target, + )?, + }; + + let mut request = MintRequest { + quote: quote_id.to_string(), + outputs: premint_secrets.blinded_messages(), + signature: None, + }; + + if let Some(secret_key) = quote_info.secret_key.clone() { + request.sign(secret_key)?; + } else { + tracing::error!("Signature is required for bolt12."); + return Err(Error::SignatureMissingOrInvalid); + } + + let mint_res = self.client.post_mint(request).await?; + + let keys = self.get_keyset_keys(active_keyset_id).await?; + + // Verify the signature DLEQ is valid + { + for (sig, premint) in mint_res.signatures.iter().zip(&premint_secrets.secrets) { + let keys = self.get_keyset_keys(sig.keyset_id).await?; + let key = keys.amount_key(sig.amount).ok_or(Error::AmountKey)?; + match sig.verify_dleq(key, premint.blinded_message.blinded_secret) { + Ok(_) | Err(nut12::Error::MissingDleqProof) => (), + Err(_) => return Err(Error::CouldNotVerifyDleq), + } + } + } + + let proofs = construct_proofs( + mint_res.signatures, + premint_secrets.rs(), + premint_secrets.secrets(), + &keys, + )?; + + // Remove filled quote from store + let mut quote_info = self + .localstore + .get_mint_quote(quote_id) + .await? + .ok_or(Error::UnpaidQuote)?; + quote_info.amount_issued += proofs.total_amount()?; + + self.localstore.add_mint_quote(quote_info.clone()).await?; + + if spending_conditions.is_none() { + // Update counter for keyset + self.localstore + .increment_keyset_counter(&active_keyset_id, proofs.len() as u32) + .await?; + } + + let proof_infos = proofs + .iter() + .map(|proof| { + ProofInfo::new( + proof.clone(), + self.mint_url.clone(), + State::Unspent, + quote_info.unit.clone(), + ) + }) + .collect::, _>>()?; + + // Add new proofs to store + self.localstore.update_proofs(proof_infos, vec![]).await?; + + // Add transaction to store + self.localstore + .add_transaction(Transaction { + mint_url: self.mint_url.clone(), + direction: TransactionDirection::Incoming, + amount: proofs.total_amount()?, + fee: Amount::ZERO, + unit: self.unit.clone(), + ys: proofs.ys()?, + timestamp: unix_time(), + memo: None, + metadata: HashMap::new(), + }) + .await?; + + Ok(proofs) + } + + /// Check mint quote status + #[instrument(skip(self, quote_id))] + pub async fn mint_bolt12_quote_state( + &self, + quote_id: &str, + ) -> Result, Error> { + let response = self.client.get_mint_quote_bolt12_status(quote_id).await?; + + match self.localstore.get_mint_quote(quote_id).await? { + Some(quote) => { + let mut quote = quote; + quote.amount_issued = response.amount_issued; + quote.amount_paid = response.amount_paid; + + self.localstore.add_mint_quote(quote).await?; + } + None => { + tracing::info!("Quote mint {} unknown", quote_id); + } + } + + Ok(response) + } +} diff --git a/crates/cdk/src/wallet/issue/mod.rs b/crates/cdk/src/wallet/issue/mod.rs new file mode 100644 index 000000000..8d74d484f --- /dev/null +++ b/crates/cdk/src/wallet/issue/mod.rs @@ -0,0 +1,2 @@ +mod issue_bolt11; +mod issue_bolt12; diff --git a/crates/cdk/src/wallet/melt.rs b/crates/cdk/src/wallet/melt/melt_bolt11.rs similarity index 99% rename from crates/cdk/src/wallet/melt.rs rename to crates/cdk/src/wallet/melt/melt_bolt11.rs index abccaae4e..6dad683d7 100644 --- a/crates/cdk/src/wallet/melt.rs +++ b/crates/cdk/src/wallet/melt/melt_bolt11.rs @@ -6,7 +6,6 @@ use cdk_common::wallet::{Transaction, TransactionDirection}; use lightning_invoice::Bolt11Invoice; use tracing::instrument; -use super::MeltQuote; use crate::amount::to_unit; use crate::dhke::construct_proofs; use crate::nuts::{ @@ -15,6 +14,7 @@ use crate::nuts::{ }; use crate::types::{Melted, ProofInfo}; use crate::util::unix_time; +use crate::wallet::MeltQuote; use crate::{ensure_cdk, Error, Wallet}; impl Wallet { diff --git a/crates/cdk/src/wallet/melt/melt_bolt12.rs b/crates/cdk/src/wallet/melt/melt_bolt12.rs new file mode 100644 index 000000000..93b487909 --- /dev/null +++ b/crates/cdk/src/wallet/melt/melt_bolt12.rs @@ -0,0 +1,89 @@ +//! Melt BOLT12 +//! +//! Implementation of melt functionality for BOLT12 offers + +use std::str::FromStr; + +use cdk_common::amount::amount_for_offer; +use cdk_common::wallet::MeltQuote; +use lightning::offers::offer::Offer; +use tracing::instrument; + +use crate::amount::to_unit; +use crate::nuts::{CurrencyUnit, MeltOptions, MeltQuoteBolt11Response, MeltQuoteBolt12Request}; +use crate::{Error, Wallet}; + +impl Wallet { + /// Melt Quote for BOLT12 offer + #[instrument(skip(self, request))] + pub async fn melt_bolt12_quote( + &self, + request: String, + options: Option, + ) -> Result { + let quote_request = MeltQuoteBolt12Request { + request: request.clone(), + unit: self.unit.clone(), + options, + }; + + let quote_res = self.client.post_melt_bolt12_quote(quote_request).await?; + + if self.unit == CurrencyUnit::Sat || self.unit == CurrencyUnit::Msat { + let offer = Offer::from_str(&request).map_err(|_| Error::Bolt12parse)?; + // Get amount from offer or options + let amount_msat = options + .map(|opt| opt.amount_msat()) + .or_else(|| amount_for_offer(&offer, &CurrencyUnit::Msat).ok()) + .ok_or(Error::AmountUndefined)?; + let amount_quote_unit = to_unit(amount_msat, &CurrencyUnit::Msat, &self.unit).unwrap(); + + if quote_res.amount != amount_quote_unit { + tracing::warn!( + "Mint returned incorrect quote amount. Expected {}, got {}", + amount_quote_unit, + quote_res.amount + ); + return Err(Error::IncorrectQuoteAmount); + } + } + + let quote = MeltQuote { + id: quote_res.quote, + amount: quote_res.amount, + request, + unit: self.unit.clone(), + fee_reserve: quote_res.fee_reserve, + state: quote_res.state, + expiry: quote_res.expiry, + payment_preimage: quote_res.payment_preimage, + }; + + self.localstore.add_melt_quote(quote.clone()).await?; + + Ok(quote) + } + + /// BOLT12 melt quote status + #[instrument(skip(self, quote_id))] + pub async fn melt_bolt12_quote_status( + &self, + quote_id: &str, + ) -> Result, Error> { + let response = self.client.get_melt_bolt12_quote_status(quote_id).await?; + + match self.localstore.get_melt_quote(quote_id).await? { + Some(quote) => { + let mut quote = quote; + + quote.state = response.state; + self.localstore.add_melt_quote(quote).await?; + } + None => { + tracing::info!("Quote melt {} unknown", quote_id); + } + } + + Ok(response) + } +} diff --git a/crates/cdk/src/wallet/melt/mod.rs b/crates/cdk/src/wallet/melt/mod.rs new file mode 100644 index 000000000..98f889a83 --- /dev/null +++ b/crates/cdk/src/wallet/melt/mod.rs @@ -0,0 +1,2 @@ +mod melt_bolt11; +mod melt_bolt12; diff --git a/crates/cdk/src/wallet/mint_connector/http_client.rs b/crates/cdk/src/wallet/mint_connector/http_client.rs index d15989bcf..96720f5a1 100644 --- a/crates/cdk/src/wallet/mint_connector/http_client.rs +++ b/crates/cdk/src/wallet/mint_connector/http_client.rs @@ -2,6 +2,7 @@ use std::sync::Arc; use async_trait::async_trait; +use cdk_common::{MeltQuoteBolt12Request, MintQuoteBolt12Request, MintQuoteBolt12Response}; #[cfg(feature = "auth")] use cdk_common::{Method, ProtectedEndpoint, RoutePath}; use reqwest::{Client, IntoUrl}; @@ -91,7 +92,9 @@ impl HttpClientCore { let response = request .send() .await - .map_err(|e| Error::HttpError(e.to_string()))? + .map_err(|e| Error::HttpError(e.to_string()))?; + + let response = response .text() .await .map_err(|e| Error::HttpError(e.to_string()))?; @@ -395,6 +398,103 @@ impl MintConnector for HttpClient { let auth_token = None; self.core.http_post(url, auth_token, &request).await } + + /// Mint Quote Bolt12 [NUT-23] + #[instrument(skip(self), fields(mint_url = %self.mint_url))] + async fn post_mint_bolt12_quote( + &self, + request: MintQuoteBolt12Request, + ) -> Result, Error> { + let url = self + .mint_url + .join_paths(&["v1", "mint", "quote", "bolt12"])?; + + #[cfg(feature = "auth")] + let auth_token = self + .get_auth_token(Method::Post, RoutePath::MintQuoteBolt12) + .await?; + + #[cfg(not(feature = "auth"))] + let auth_token = None; + + self.core.http_post(url, auth_token, &request).await + } + + /// Mint Quote Bolt12 status + #[instrument(skip(self), fields(mint_url = %self.mint_url))] + async fn get_mint_quote_bolt12_status( + &self, + quote_id: &str, + ) -> Result, Error> { + let url = self + .mint_url + .join_paths(&["v1", "mint", "quote", "bolt12", quote_id])?; + + #[cfg(feature = "auth")] + let auth_token = self + .get_auth_token(Method::Get, RoutePath::MintQuoteBolt12) + .await?; + + #[cfg(not(feature = "auth"))] + let auth_token = None; + self.core.http_get(url, auth_token).await + } + + /// Melt Quote Bolt12 [NUT-23] + #[instrument(skip(self, request), fields(mint_url = %self.mint_url))] + async fn post_melt_bolt12_quote( + &self, + request: MeltQuoteBolt12Request, + ) -> Result, Error> { + let url = self + .mint_url + .join_paths(&["v1", "melt", "quote", "bolt12"])?; + #[cfg(feature = "auth")] + let auth_token = self + .get_auth_token(Method::Post, RoutePath::MeltQuoteBolt12) + .await?; + + #[cfg(not(feature = "auth"))] + let auth_token = None; + self.core.http_post(url, auth_token, &request).await + } + + /// Melt Quote Bolt12 Status [NUT-23] + #[instrument(skip(self), fields(mint_url = %self.mint_url))] + async fn get_melt_bolt12_quote_status( + &self, + quote_id: &str, + ) -> Result, Error> { + let url = self + .mint_url + .join_paths(&["v1", "melt", "quote", "bolt12", quote_id])?; + + #[cfg(feature = "auth")] + let auth_token = self + .get_auth_token(Method::Get, RoutePath::MeltQuoteBolt12) + .await?; + + #[cfg(not(feature = "auth"))] + let auth_token = None; + self.core.http_get(url, auth_token).await + } + + /// Melt Bolt12 [NUT-23] + #[instrument(skip(self, request), fields(mint_url = %self.mint_url))] + async fn post_melt_bolt12( + &self, + request: MeltRequest, + ) -> Result, Error> { + let url = self.mint_url.join_paths(&["v1", "melt", "bolt12"])?; + #[cfg(feature = "auth")] + let auth_token = self + .get_auth_token(Method::Post, RoutePath::MeltBolt12) + .await?; + + #[cfg(not(feature = "auth"))] + let auth_token = None; + self.core.http_post(url, auth_token, &request).await + } } /// Http Client diff --git a/crates/cdk/src/wallet/mint_connector/mod.rs b/crates/cdk/src/wallet/mint_connector/mod.rs index 712ba8e9d..eb88944a4 100644 --- a/crates/cdk/src/wallet/mint_connector/mod.rs +++ b/crates/cdk/src/wallet/mint_connector/mod.rs @@ -3,6 +3,7 @@ use std::fmt::Debug; use async_trait::async_trait; +use cdk_common::{MeltQuoteBolt12Request, MintQuoteBolt12Request, MintQuoteBolt12Response}; use super::Error; use crate::nuts::{ @@ -77,4 +78,29 @@ pub trait MintConnector: Debug { /// Set auth wallet on client #[cfg(feature = "auth")] async fn set_auth_wallet(&self, wallet: Option); + /// Mint Quote [NUT-04] + async fn post_mint_bolt12_quote( + &self, + request: MintQuoteBolt12Request, + ) -> Result, Error>; + /// Mint Quote status + async fn get_mint_quote_bolt12_status( + &self, + quote_id: &str, + ) -> Result, Error>; + /// Melt Quote [NUT-23] + async fn post_melt_bolt12_quote( + &self, + request: MeltQuoteBolt12Request, + ) -> Result, Error>; + /// Melt Quote Status [NUT-23] + async fn get_melt_bolt12_quote_status( + &self, + quote_id: &str, + ) -> Result, Error>; + /// Melt [NUT-23] + async fn post_melt_bolt12( + &self, + request: MeltRequest, + ) -> Result, Error>; } diff --git a/crates/cdk/src/wallet/mod.rs b/crates/cdk/src/wallet/mod.rs index a0f499ee1..1aa4db9a4 100644 --- a/crates/cdk/src/wallet/mod.rs +++ b/crates/cdk/src/wallet/mod.rs @@ -34,9 +34,9 @@ use crate::OidcClient; mod auth; mod balance; mod builder; +mod issue; mod keysets; mod melt; -mod mint; mod mint_connector; pub mod multi_mint_wallet; mod proofs; diff --git a/misc/itests.sh b/misc/itests.sh index 6465ca78d..dd2755c15 100755 --- a/misc/itests.sh +++ b/misc/itests.sh @@ -224,6 +224,13 @@ if [ $? -ne 0 ]; then exit 1 fi +echo "Running regtest test with cln mint for bolt12" +cargo test -p cdk-integration-tests --test bolt12 +if [ $? -ne 0 ]; then + echo "regtest test failed, exiting" + exit 1 +fi + # Switch Mints: Run tests with LND mint echo "Switching to LND mint for tests" export CDK_ITESTS_MINT_PORT_0=8087 diff --git a/misc/mintd_payment_processor.sh b/misc/mintd_payment_processor.sh index 376978da8..d00dc7401 100755 --- a/misc/mintd_payment_processor.sh +++ b/misc/mintd_payment_processor.sh @@ -50,6 +50,7 @@ cleanup() { unset CDK_MINTD_GRPC_PAYMENT_PROCESSOR_SUPPORTED_UNITS unset CDK_MINTD_MNEMONIC unset CDK_MINTD_PID + unset CDK_PAYMENT_PROCESSOR_CLN_BOLT12 } # Set up trap to call cleanup on script exit @@ -102,6 +103,7 @@ if [ "$LN_BACKEND" != "FAKEWALLET" ]; then sleep 1 done echo "Regtest set up continuing" + export CDK_PAYMENT_PROCESSOR_CLN_BOLT12=true fi # Start payment processor @@ -177,5 +179,17 @@ cargo test -p cdk-integration-tests --test happy_path_mint_wallet # Capture the exit status of cargo test test_status=$? +if [ "$LN_BACKEND" = "CLN" ]; then + echo "Running bolt12 tests for CLN backend" + cargo test -p cdk-integration-tests --test bolt12 + bolt12_test_status=$? + + # Exit with non-zero status if either test failed + if [ $test_status -ne 0 ] || [ $bolt12_test_status -ne 0 ]; then + echo "Tests failed - happy_path_mint_wallet: $test_status, bolt12: $bolt12_test_status" + exit 1 + fi +fi + # Exit with the status of the tests exit $test_status From 21a32b6b0fb64ca047ecfe9e3871bdc74ccb797c Mon Sep 17 00:00:00 2001 From: gudnuf Date: Mon, 14 Jul 2025 06:56:40 -0700 Subject: [PATCH 021/321] fix: include change in melt quote state updates --- crates/cdk/src/mint/melt.rs | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/crates/cdk/src/mint/melt.rs b/crates/cdk/src/mint/melt.rs index d0792ca0c..e50a23966 100644 --- a/crates/cdk/src/mint/melt.rs +++ b/crates/cdk/src/mint/melt.rs @@ -755,13 +755,6 @@ impl Mint { ) .await?; - self.pubsub_manager.melt_quote_status( - "e, - payment_preimage.clone(), - None, - MeltQuoteState::Paid, - ); - let mut change = None; // Check if there is change to return @@ -827,6 +820,13 @@ impl Mint { } } + self.pubsub_manager.melt_quote_status( + "e, + payment_preimage.clone(), + change.clone(), + MeltQuoteState::Paid, + ); + proof_writer.commit(); tx.commit().await?; From bd2fbb13f91427958b5123ceb7a1b6640c5a1d48 Mon Sep 17 00:00:00 2001 From: David Caseria Date: Thu, 17 Jul 2025 03:37:38 -0400 Subject: [PATCH 022/321] Wallet: Check Pending Melt Quotes (#895) * Add transaction for pending melt * Check pending melt quotes * Fix imports --- crates/cdk-common/src/database/wallet.rs | 2 + crates/cdk-redb/src/wallet/mod.rs | 15 +++++ crates/cdk-sqlite/src/wallet/mod.rs | 24 +++++++ crates/cdk/src/wallet/melt/melt_bolt11.rs | 7 ++ crates/cdk/src/wallet/melt/melt_bolt12.rs | 7 ++ crates/cdk/src/wallet/melt/mod.rs | 79 +++++++++++++++++++++++ 6 files changed, 134 insertions(+) diff --git a/crates/cdk-common/src/database/wallet.rs b/crates/cdk-common/src/database/wallet.rs index 1195a858d..074f07086 100644 --- a/crates/cdk-common/src/database/wallet.rs +++ b/crates/cdk-common/src/database/wallet.rs @@ -69,6 +69,8 @@ pub trait Database: Debug { async fn add_melt_quote(&self, quote: wallet::MeltQuote) -> Result<(), Self::Err>; /// Get melt quote from storage async fn get_melt_quote(&self, quote_id: &str) -> Result, Self::Err>; + /// Get melt quotes from storage + async fn get_melt_quotes(&self) -> Result, Self::Err>; /// Remove melt quote from storage async fn remove_melt_quote(&self, quote_id: &str) -> Result<(), Self::Err>; diff --git a/crates/cdk-redb/src/wallet/mod.rs b/crates/cdk-redb/src/wallet/mod.rs index cdeac6f8e..f08b2ab36 100644 --- a/crates/cdk-redb/src/wallet/mod.rs +++ b/crates/cdk-redb/src/wallet/mod.rs @@ -477,6 +477,21 @@ impl WalletDatabase for WalletRedbDatabase { Ok(None) } + #[instrument(skip_all)] + async fn get_melt_quotes(&self) -> Result, Self::Err> { + let read_txn = self.db.begin_read().map_err(Error::from)?; + let table = read_txn + .open_table(MELT_QUOTES_TABLE) + .map_err(Error::from)?; + + Ok(table + .iter() + .map_err(Error::from)? + .flatten() + .flat_map(|(_id, quote)| serde_json::from_str(quote.value())) + .collect()) + } + #[instrument(skip_all)] async fn remove_melt_quote(&self, quote_id: &str) -> Result<(), Self::Err> { let write_txn = self.db.begin_write().map_err(Error::from)?; diff --git a/crates/cdk-sqlite/src/wallet/mod.rs b/crates/cdk-sqlite/src/wallet/mod.rs index 5e16e7fcb..95259ed26 100644 --- a/crates/cdk-sqlite/src/wallet/mod.rs +++ b/crates/cdk-sqlite/src/wallet/mod.rs @@ -530,6 +530,30 @@ ON CONFLICT(id) DO UPDATE SET .transpose()?) } + #[instrument(skip(self))] + async fn get_melt_quotes(&self) -> Result, Self::Err> { + Ok(Statement::new( + r#" + SELECT + id, + unit, + amount, + request, + fee_reserve, + state, + expiry, + payment_preimage + FROM + melt_quote + "#, + ) + .fetch_all(&self.pool.get().map_err(Error::Pool)?) + .map_err(Error::Sqlite)? + .into_iter() + .map(sqlite_row_to_melt_quote) + .collect::>()?) + } + #[instrument(skip(self))] async fn remove_melt_quote(&self, quote_id: &str) -> Result<(), Self::Err> { Statement::new(r#"DELETE FROM melt_quote WHERE id=:id"#) diff --git a/crates/cdk/src/wallet/melt/melt_bolt11.rs b/crates/cdk/src/wallet/melt/melt_bolt11.rs index 6dad683d7..afe3b4386 100644 --- a/crates/cdk/src/wallet/melt/melt_bolt11.rs +++ b/crates/cdk/src/wallet/melt/melt_bolt11.rs @@ -104,6 +104,13 @@ impl Wallet { Some(quote) => { let mut quote = quote; + if let Err(e) = self + .add_transaction_for_pending_melt("e, &response) + .await + { + tracing::error!("Failed to add transaction for pending melt: {}", e); + } + quote.state = response.state; self.localstore.add_melt_quote(quote).await?; } diff --git a/crates/cdk/src/wallet/melt/melt_bolt12.rs b/crates/cdk/src/wallet/melt/melt_bolt12.rs index 93b487909..95707b80f 100644 --- a/crates/cdk/src/wallet/melt/melt_bolt12.rs +++ b/crates/cdk/src/wallet/melt/melt_bolt12.rs @@ -76,6 +76,13 @@ impl Wallet { Some(quote) => { let mut quote = quote; + if let Err(e) = self + .add_transaction_for_pending_melt("e, &response) + .await + { + tracing::error!("Failed to add transaction for pending melt: {}", e); + } + quote.state = response.state; self.localstore.add_melt_quote(quote).await?; } diff --git a/crates/cdk/src/wallet/melt/mod.rs b/crates/cdk/src/wallet/melt/mod.rs index 98f889a83..3dc4262af 100644 --- a/crates/cdk/src/wallet/melt/mod.rs +++ b/crates/cdk/src/wallet/melt/mod.rs @@ -1,2 +1,81 @@ +use std::collections::HashMap; + +use cdk_common::util::unix_time; +use cdk_common::wallet::{MeltQuote, Transaction, TransactionDirection}; +use cdk_common::{Error, MeltQuoteBolt11Response, MeltQuoteState, ProofsMethods}; +use tracing::instrument; + +use crate::Wallet; + mod melt_bolt11; mod melt_bolt12; + +impl Wallet { + /// Check pending melt quotes + #[instrument(skip_all)] + pub async fn check_pending_melt_quotes(&self) -> Result<(), Error> { + let quotes = self.get_pending_melt_quotes().await?; + for quote in quotes { + self.melt_quote_status("e.id).await?; + } + Ok(()) + } + + /// Get all active melt quotes from the wallet + pub async fn get_active_melt_quotes(&self) -> Result, Error> { + let quotes = self.localstore.get_melt_quotes().await?; + Ok(quotes + .into_iter() + .filter(|q| { + q.state == MeltQuoteState::Pending + || (q.state == MeltQuoteState::Unpaid && q.expiry > unix_time()) + }) + .collect()) + } + + /// Get pending melt quotes + pub async fn get_pending_melt_quotes(&self) -> Result, Error> { + let quotes = self.localstore.get_melt_quotes().await?; + Ok(quotes + .into_iter() + .filter(|q| q.state == MeltQuoteState::Pending) + .collect()) + } + + pub(crate) async fn add_transaction_for_pending_melt( + &self, + quote: &MeltQuote, + response: &MeltQuoteBolt11Response, + ) -> Result<(), Error> { + if quote.state != response.state { + tracing::info!( + "Quote melt {} state changed from {} to {}", + quote.id, + quote.state, + response.state + ); + if response.state == MeltQuoteState::Paid { + let pending_proofs = self.get_pending_proofs().await?; + let proofs_total = pending_proofs.total_amount().unwrap_or_default(); + let change_total = response.change_amount().unwrap_or_default(); + self.localstore + .add_transaction(Transaction { + mint_url: self.mint_url.clone(), + direction: TransactionDirection::Outgoing, + amount: response.amount, + fee: proofs_total + .checked_sub(response.amount) + .and_then(|amt| amt.checked_sub(change_total)) + .unwrap_or_default(), + unit: quote.unit.clone(), + ys: pending_proofs.ys()?, + timestamp: unix_time(), + memo: None, + metadata: HashMap::new(), + }) + .await?; + } + } + Ok(()) + } +} From 7f0e261a255d9732b43e3ad56a426fa5bbceba24 Mon Sep 17 00:00:00 2001 From: findingsov <113792100+findingsov@users.noreply.github.com> Date: Thu, 17 Jul 2025 09:38:32 +0200 Subject: [PATCH 023/321] Update README.md-small typo (#893) could not find cdk-mint-cli in crates.io. Found cdk-mint-rpc. --- crates/cdk-mint-rpc/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/cdk-mint-rpc/README.md b/crates/cdk-mint-rpc/README.md index be20d9cf2..54dbac5db 100644 --- a/crates/cdk-mint-rpc/README.md +++ b/crates/cdk-mint-rpc/README.md @@ -19,7 +19,7 @@ This crate includes: From crates.io: ```bash -cargo install cdk-mint-cli +cargo install cdk-mint-rpc ``` As a library: @@ -48,4 +48,4 @@ cdk-mint-cli keysets list ## License -This project is licensed under the [MIT License](../../LICENSE). \ No newline at end of file +This project is licensed under the [MIT License](../../LICENSE). From f018465aa663258e8a081596b7c99dfabf114c72 Mon Sep 17 00:00:00 2001 From: David Caseria Date: Sat, 19 Jul 2025 12:13:11 -0400 Subject: [PATCH 024/321] Refactor MintBuilder (#887) * Refactor MintBuilder * Validate azp instead of aud for client id --- crates/cdk-axum/src/ws/subscribe.rs | 2 +- .../src/sub_commands/cat_device_login.rs | 2 +- crates/cdk-cli/src/sub_commands/cat_login.rs | 2 +- .../src/sub_commands/mint_blind_auth.rs | 2 +- crates/cdk-common/src/common.rs | 13 +- .../src/init_auth_mint.rs | 32 +- .../src/init_pure_tests.rs | 38 +- .../cdk-integration-tests/tests/fake_auth.rs | 4 +- .../tests/integration_tests_pure.rs | 6 +- crates/cdk-integration-tests/tests/mint.rs | 26 +- crates/cdk-mint-rpc/src/proto/server.rs | 14 +- crates/cdk-mintd/src/main.rs | 117 +++--- crates/cdk/examples/auth_wallet.rs | 2 +- crates/cdk/src/mint/builder.rs | 348 ++++++++---------- crates/cdk/src/mint/ln.rs | 2 +- crates/cdk/src/mint/melt.rs | 6 +- crates/cdk/src/mint/mod.rs | 99 ++--- crates/cdk/src/mint/start_up_check.rs | 2 +- crates/cdk/src/oidc_client.rs | 49 ++- crates/cdk/src/wallet/mod.rs | 9 +- 20 files changed, 383 insertions(+), 392 deletions(-) diff --git a/crates/cdk-axum/src/ws/subscribe.rs b/crates/cdk-axum/src/ws/subscribe.rs index e675bf40d..fb8c9201e 100644 --- a/crates/cdk-axum/src/ws/subscribe.rs +++ b/crates/cdk-axum/src/ws/subscribe.rs @@ -20,7 +20,7 @@ pub(crate) async fn handle( let mut subscription = context .state .mint - .pubsub_manager + .pubsub_manager() .try_subscribe(params) .await .map_err(|_| WsError::ParseError)?; diff --git a/crates/cdk-cli/src/sub_commands/cat_device_login.rs b/crates/cdk-cli/src/sub_commands/cat_device_login.rs index 29727c7d8..8c958f5cc 100644 --- a/crates/cdk-cli/src/sub_commands/cat_device_login.rs +++ b/crates/cdk-cli/src/sub_commands/cat_device_login.rs @@ -82,7 +82,7 @@ async fn get_device_code_token(mint_info: &MintInfo, client_id: &str) -> (String .expect("Nut21 defined") .openid_discovery; - let oidc_client = OidcClient::new(openid_discovery); + let oidc_client = OidcClient::new(openid_discovery, None); // Get the OIDC configuration let oidc_config = oidc_client diff --git a/crates/cdk-cli/src/sub_commands/cat_login.rs b/crates/cdk-cli/src/sub_commands/cat_login.rs index 61a296b91..dcfc57ebf 100644 --- a/crates/cdk-cli/src/sub_commands/cat_login.rs +++ b/crates/cdk-cli/src/sub_commands/cat_login.rs @@ -93,7 +93,7 @@ async fn get_access_token( .expect("Nut21 defined") .openid_discovery; - let oidc_client = OidcClient::new(openid_discovery); + let oidc_client = OidcClient::new(openid_discovery, None); // Get the token endpoint from the OIDC configuration let token_url = oidc_client diff --git a/crates/cdk-cli/src/sub_commands/mint_blind_auth.rs b/crates/cdk-cli/src/sub_commands/mint_blind_auth.rs index 2e1f06529..ec894343b 100644 --- a/crates/cdk-cli/src/sub_commands/mint_blind_auth.rs +++ b/crates/cdk-cli/src/sub_commands/mint_blind_auth.rs @@ -164,7 +164,7 @@ async fn refresh_access_token( .ok_or_else(|| anyhow::anyhow!("OIDC discovery information not available"))? .openid_discovery; - let oidc_client = OidcClient::new(openid_discovery); + let oidc_client = OidcClient::new(openid_discovery, None); // Get the token endpoint from the OIDC configuration let token_url = oidc_client.get_oidc_config().await?.token_endpoint; diff --git a/crates/cdk-common/src/common.rs b/crates/cdk-common/src/common.rs index b2920bb39..d86d5ce0f 100644 --- a/crates/cdk-common/src/common.rs +++ b/crates/cdk-common/src/common.rs @@ -162,8 +162,8 @@ impl PaymentProcessorKey { } } -/// Secs wuotes are valid -#[derive(Debug, Clone, Copy, Hash, PartialEq, Eq, Serialize, Deserialize, Default)] +/// Seconds quotes are valid +#[derive(Debug, Clone, Copy, Hash, PartialEq, Eq, Serialize, Deserialize)] pub struct QuoteTTL { /// Seconds mint quote is valid pub mint_ttl: u64, @@ -178,6 +178,15 @@ impl QuoteTTL { } } +impl Default for QuoteTTL { + fn default() -> Self { + Self { + mint_ttl: 60 * 60, // 1 hour + melt_ttl: 60, // 1 minute + } + } +} + #[cfg(test)] mod tests { use std::str::FromStr; diff --git a/crates/cdk-integration-tests/src/init_auth_mint.rs b/crates/cdk-integration-tests/src/init_auth_mint.rs index 822334dae..dc6c50719 100644 --- a/crates/cdk-integration-tests/src/init_auth_mint.rs +++ b/crates/cdk-integration-tests/src/init_auth_mint.rs @@ -31,14 +31,10 @@ where let fake_wallet = FakeWallet::new(fee_reserve, HashMap::default(), HashSet::default(), 0); - let mut mint_builder = MintBuilder::new(); + let mut mint_builder = MintBuilder::new(Arc::new(database)); - mint_builder = mint_builder - .with_localstore(Arc::new(database)) - .with_keystore(Arc::new(key_store)); - - mint_builder = mint_builder - .add_ln_backend( + mint_builder + .add_payment_processor( CurrencyUnit::Sat, PaymentMethod::Bolt11, MintMeltLimits::new(1, 300), @@ -46,10 +42,14 @@ where ) .await?; - mint_builder = - mint_builder.set_clear_auth_settings(openid_discovery, "cashu-client".to_string()); + let auth_database = Arc::new(auth_database); - mint_builder = mint_builder.set_blind_auth_settings(50); + mint_builder = mint_builder.with_auth( + auth_database.clone(), + openid_discovery, + "cashu-client".to_string(), + vec![], + ); let blind_auth_endpoints = vec![ ProtectedEndpoint::new(Method::Post, RoutePath::MintQuoteBolt11), @@ -71,6 +71,8 @@ where acc }); + mint_builder = mint_builder.with_blind_auth(50, blind_auth_endpoints.keys().cloned().collect()); + let mut tx = auth_database.begin_transaction().await?; tx.add_protected_endpoints(blind_auth_endpoints).await?; @@ -85,15 +87,13 @@ where tx.commit().await?; - mint_builder = mint_builder.with_auth_localstore(Arc::new(auth_database)); - let mnemonic = Mnemonic::generate(12)?; - mint_builder = mint_builder - .with_description("fake test mint".to_string()) - .with_seed(mnemonic.to_seed_normalized("").to_vec()); + mint_builder = mint_builder.with_description("fake test mint".to_string()); - let _mint = mint_builder.build().await?; + let _mint = mint_builder + .build_with_seed(Arc::new(key_store), &mnemonic.to_seed_normalized("")) + .await?; todo!("Need to start this a cdk mintd keeping as ref for now"); } diff --git a/crates/cdk-integration-tests/src/init_pure_tests.rs b/crates/cdk-integration-tests/src/init_pure_tests.rs index aafe5c60d..9d64035f4 100644 --- a/crates/cdk-integration-tests/src/init_pure_tests.rs +++ b/crates/cdk-integration-tests/src/init_pure_tests.rs @@ -10,7 +10,7 @@ use async_trait::async_trait; use bip39::Mnemonic; use cashu::{MeltQuoteBolt12Request, MintQuoteBolt12Request, MintQuoteBolt12Response}; use cdk::amount::SplitTarget; -use cdk::cdk_database::{self, WalletDatabase}; +use cdk::cdk_database::{self, MintDatabase, WalletDatabase}; use cdk::mint::{MintBuilder, MintMeltLimits}; use cdk::nuts::nut00::ProofsMethods; use cdk::nuts::{ @@ -227,25 +227,22 @@ pub async fn create_and_start_test_mint() -> Result { // Read environment variable to determine database type let db_type = env::var("CDK_TEST_DB_TYPE").expect("Database type set"); - let mut mint_builder = match db_type.to_lowercase().as_str() { - "memory" => MintBuilder::new() - .with_localstore(Arc::new(cdk_sqlite::mint::memory::empty().await?)) - .with_keystore(Arc::new(cdk_sqlite::mint::memory::empty().await?)), + let localstore = match db_type.to_lowercase().as_str() { + "memory" => Arc::new(cdk_sqlite::mint::memory::empty().await?), _ => { // Create a temporary directory for SQLite database let temp_dir = create_temp_dir("cdk-test-sqlite-mint")?; let path = temp_dir.join("mint.db").to_str().unwrap().to_string(); - let database = Arc::new( + Arc::new( cdk_sqlite::MintSqliteDatabase::new(&path) .await .expect("Could not create sqlite db"), - ); - MintBuilder::new() - .with_localstore(database.clone()) - .with_keystore(database) + ) } }; + let mut mint_builder = MintBuilder::new(localstore.clone()); + let fee_reserve = FeeReserve { min_fee_reserve: 1.into(), percent_fee_reserve: 1.0, @@ -258,8 +255,8 @@ pub async fn create_and_start_test_mint() -> Result { 0, ); - mint_builder = mint_builder - .add_ln_backend( + mint_builder + .add_payment_processor( CurrencyUnit::Sat, PaymentMethod::Bolt11, MintMeltLimits::new(1, 10_000), @@ -272,23 +269,18 @@ pub async fn create_and_start_test_mint() -> Result { mint_builder = mint_builder .with_name("pure test mint".to_string()) .with_description("pure test mint".to_string()) - .with_urls(vec!["https://aaa".to_string()]) - .with_seed(mnemonic.to_seed_normalized("").to_vec()); + .with_urls(vec!["https://aaa".to_string()]); - let localstore = mint_builder - .localstore - .as_ref() - .map(|x| x.clone()) - .expect("localstore"); - - let mut tx = localstore.begin_transaction().await?; - tx.set_mint_info(mint_builder.mint_info.clone()).await?; + let tx_localstore = localstore.clone(); + let mut tx = tx_localstore.begin_transaction().await?; let quote_ttl = QuoteTTL::new(10000, 10000); tx.set_quote_ttl(quote_ttl).await?; tx.commit().await?; - let mint = mint_builder.build().await?; + let mint = mint_builder + .build_with_seed(localstore.clone(), &mnemonic.to_seed_normalized("")) + .await?; let mint_clone = mint.clone(); let shutdown = Arc::new(Notify::new()); diff --git a/crates/cdk-integration-tests/tests/fake_auth.rs b/crates/cdk-integration-tests/tests/fake_auth.rs index bf2134bdd..9ea4b1f05 100644 --- a/crates/cdk-integration-tests/tests/fake_auth.rs +++ b/crates/cdk-integration-tests/tests/fake_auth.rs @@ -753,7 +753,7 @@ async fn get_access_token(mint_info: &MintInfo) -> (String, String) { .expect("Nutxx defined") .openid_discovery; - let oidc_client = OidcClient::new(openid_discovery); + let oidc_client = OidcClient::new(openid_discovery, None); // Get the token endpoint from the OIDC configuration let token_url = oidc_client @@ -811,7 +811,7 @@ async fn get_custom_access_token( .expect("Nutxx defined") .openid_discovery; - let oidc_client = OidcClient::new(openid_discovery); + let oidc_client = OidcClient::new(openid_discovery, None); // Get the token endpoint from the OIDC configuration let token_url = oidc_client diff --git a/crates/cdk-integration-tests/tests/integration_tests_pure.rs b/crates/cdk-integration-tests/tests/integration_tests_pure.rs index 4eb9dd72e..d49bd2a8b 100644 --- a/crates/cdk-integration-tests/tests/integration_tests_pure.rs +++ b/crates/cdk-integration-tests/tests/integration_tests_pure.rs @@ -443,7 +443,7 @@ pub async fn test_p2pk_swap() { .collect(); let mut listener = mint_bob - .pubsub_manager + .pubsub_manager() .try_subscribe::( Params { kind: cdk::nuts::nut17::Kind::ProofState, @@ -773,7 +773,7 @@ async fn test_concurrent_double_spend_swap() { // Verify that all proofs are marked as spent in the mint let states = mint_bob - .localstore + .localstore() .get_proofs_states(&proofs.iter().map(|p| p.y().unwrap()).collect::>()) .await .expect("Failed to get proof state"); @@ -870,7 +870,7 @@ async fn test_concurrent_double_spend_melt() { // Verify that all proofs are marked as spent in the mint let states = mint_bob - .localstore + .localstore() .get_proofs_states(&proofs.iter().map(|p| p.y().unwrap()).collect::>()) .await .expect("Failed to get proof state"); diff --git a/crates/cdk-integration-tests/tests/mint.rs b/crates/cdk-integration-tests/tests/mint.rs index 33c4dd479..da6fa8c88 100644 --- a/crates/cdk-integration-tests/tests/mint.rs +++ b/crates/cdk-integration-tests/tests/mint.rs @@ -29,14 +29,15 @@ async fn test_correct_keyset() { let fake_wallet = FakeWallet::new(fee_reserve, HashMap::default(), HashSet::default(), 0); - let mut mint_builder = MintBuilder::new(); let localstore = Arc::new(database); - mint_builder = mint_builder - .with_localstore(localstore.clone()) - .with_keystore(localstore.clone()); + let mut mint_builder = MintBuilder::new(localstore.clone()); mint_builder = mint_builder - .add_ln_backend( + .with_name("regtest mint".to_string()) + .with_description("regtest mint".to_string()); + + mint_builder + .add_payment_processor( CurrencyUnit::Sat, PaymentMethod::Bolt11, MintMeltLimits::new(1, 5_000), @@ -44,18 +45,14 @@ async fn test_correct_keyset() { ) .await .unwrap(); + // .with_seed(mnemonic.to_seed_normalized("").to_vec()); - mint_builder = mint_builder - .with_name("regtest mint".to_string()) - .with_description("regtest mint".to_string()) - .with_seed(mnemonic.to_seed_normalized("").to_vec()); - - let mint = mint_builder.build().await.unwrap(); - let mut tx = localstore.begin_transaction().await.unwrap(); - - tx.set_mint_info(mint_builder.mint_info.clone()) + let mint = mint_builder + .build_with_seed(localstore.clone(), &mnemonic.to_seed_normalized("")) .await .unwrap(); + let mut tx = localstore.begin_transaction().await.unwrap(); + let quote_ttl = QuoteTTL::new(10000, 10000); tx.set_quote_ttl(quote_ttl).await.unwrap(); @@ -81,7 +78,6 @@ async fn test_correct_keyset() { assert_ne!(keyset_info.id, old_keyset_info.id); mint.rotate_keyset(CurrencyUnit::Sat, 32, 0).await.unwrap(); - let mint = mint_builder.build().await.unwrap(); let active = mint.get_active_keysets(); diff --git a/crates/cdk-mint-rpc/src/proto/server.rs b/crates/cdk-mint-rpc/src/proto/server.rs index 55fe8f2b4..7b8508e50 100644 --- a/crates/cdk-mint-rpc/src/proto/server.rs +++ b/crates/cdk-mint-rpc/src/proto/server.rs @@ -643,7 +643,7 @@ impl CdkMint for MintRPCServer { let mint_quote = self .mint - .localstore + .localstore() .get_mint_quote("e_id) .await .map_err(|_| Status::invalid_argument("Could not find quote".to_string()))? @@ -659,9 +659,8 @@ impl CdkMint for MintRPCServer { payment_identifier: mint_quote.request_lookup_id.clone(), }; - let mut tx = self - .mint - .localstore + let localstore = self.mint.localstore(); + let mut tx = localstore .begin_transaction() .await .map_err(|_| Status::internal("Could not start db transaction".to_string()))?; @@ -693,9 +692,8 @@ impl CdkMint for MintRPCServer { vec![], // payment_ids ); - let mut tx = self - .mint - .localstore + let mint_store = self.mint.localstore(); + let mut tx = mint_store .begin_transaction() .await .map_err(|_| Status::internal("Could not update quote".to_string()))?; @@ -710,7 +708,7 @@ impl CdkMint for MintRPCServer { let mint_quote = self .mint - .localstore + .localstore() .get_mint_quote("e_id) .await .map_err(|_| Status::invalid_argument("Could not find quote".to_string()))? diff --git a/crates/cdk-mintd/src/main.rs b/crates/cdk-mintd/src/main.rs index 85befcf00..6296325c5 100644 --- a/crates/cdk-mintd/src/main.rs +++ b/crates/cdk-mintd/src/main.rs @@ -19,7 +19,7 @@ use bip39::Mnemonic; use cdk::cdk_database::{self, MintDatabase, MintKeysDatabase}; use cdk::cdk_payment; use cdk::cdk_payment::MintPayment; -use cdk::mint::{MintBuilder, MintMeltLimits}; +use cdk::mint::{Mint, MintBuilder, MintMeltLimits}; #[cfg(any( feature = "cln", feature = "lnbits", @@ -84,16 +84,13 @@ compile_error!( async fn main() -> Result<()> { let (work_dir, settings, localstore, keystore) = initial_setup().await?; - let mint_builder = MintBuilder::new() - .with_localstore(localstore) - .with_keystore(keystore); + let mint_builder = MintBuilder::new(localstore); let (mint_builder, ln_routers) = configure_mint_builder(&settings, mint_builder).await?; #[cfg(feature = "auth")] let mint_builder = setup_authentication(&settings, &work_dir, mint_builder).await?; - let mint_builder_info = mint_builder.mint_info.clone(); - let mint = mint_builder.build().await?; + let mint = build_mint(&settings, keystore, mint_builder).await?; tracing::debug!("Mint built from builder."); @@ -109,7 +106,7 @@ async fn main() -> Result<()> { &settings, ln_routers, &work_dir, - mint_builder_info, + mint.mint_info().await?, ) .await?; @@ -236,9 +233,6 @@ async fn configure_mint_builder( // Configure lightning backend let mint_builder = configure_lightning_backend(settings, mint_builder, &mut ln_routers).await?; - // Configure signatory or seed - let mint_builder = configure_signing_method(settings, mint_builder).await?; - // Configure caching let mint_builder = configure_cache(settings, mint_builder); @@ -274,7 +268,7 @@ fn configure_basic_info(settings: &config::Settings, mint_builder: MintBuilder) } for contact in contacts { - builder = builder.add_contact_info(contact); + builder = builder.with_contact_info(contact); } if let Some(pubkey) = settings.mint_info.pubkey { @@ -435,8 +429,8 @@ async fn configure_backend_for_unit( if let Some(bolt12) = payment_settings.get("bolt12") { if bolt12.as_bool().unwrap_or_default() { - mint_builder = mint_builder - .add_ln_backend( + mint_builder + .add_payment_processor( unit.clone(), PaymentMethod::Bolt12, mint_melt_limits, @@ -446,8 +440,8 @@ async fn configure_backend_for_unit( } } - mint_builder = mint_builder - .add_ln_backend( + mint_builder + .add_payment_processor( unit.clone(), PaymentMethod::Bolt11, mint_melt_limits, @@ -456,47 +450,15 @@ async fn configure_backend_for_unit( .await?; if let Some(input_fee) = settings.info.input_fee_ppk { - mint_builder = mint_builder.set_unit_fee(&unit, input_fee)?; + mint_builder.set_unit_fee(&unit, input_fee)?; } let nut17_supported = SupportedMethods::default_bolt11(unit); - mint_builder = mint_builder.add_supported_websockets(nut17_supported); + mint_builder = mint_builder.with_supported_websockets(nut17_supported); Ok(mint_builder) } -/// Configures the signing method (remote signatory or local seed) -async fn configure_signing_method( - settings: &config::Settings, - mint_builder: MintBuilder, -) -> Result { - if let Some(signatory_url) = settings.info.signatory_url.clone() { - tracing::info!( - "Connecting to remote signatory to {} with certs {:?}", - signatory_url, - settings.info.signatory_certs.clone() - ); - - Ok(mint_builder.with_signatory(Arc::new( - cdk_signatory::SignatoryRpcClient::new( - signatory_url, - settings.info.signatory_certs.clone(), - ) - .await?, - ))) - } else if let Some(mnemonic) = settings - .info - .mnemonic - .clone() - .map(|s| Mnemonic::from_str(&s)) - .transpose()? - { - Ok(mint_builder.with_seed(mnemonic.to_seed_normalized("").to_vec())) - } else { - bail!("No seed nor remote signatory set"); - } -} - /// Configures cache settings fn configure_cache(settings: &config::Settings, mint_builder: MintBuilder) -> MintBuilder { let cached_endpoints = vec![ @@ -506,7 +468,7 @@ fn configure_cache(settings: &config::Settings, mint_builder: MintBuilder) -> Mi ]; let cache: HttpCache = settings.info.http_cache.clone().into(); - mint_builder.add_cache(Some(cache.ttl.as_secs()), cached_endpoints) + mint_builder.with_cache(Some(cache.ttl.as_secs()), cached_endpoints) } #[cfg(feature = "auth")] @@ -532,16 +494,9 @@ async fn setup_authentication( } }; - mint_builder = mint_builder.with_auth_localstore(auth_localstore.clone()); - let mint_blind_auth_endpoint = ProtectedEndpoint::new(Method::Post, RoutePath::MintBlindAuth); - mint_builder = mint_builder.set_clear_auth_settings( - auth_settings.openid_discovery, - auth_settings.openid_client_id, - ); - let mut protected_endpoints = HashMap::new(); protected_endpoints.insert(mint_blind_auth_endpoint, AuthRequired::Clear); @@ -644,7 +599,14 @@ async fn setup_authentication( } } - mint_builder = mint_builder.set_blind_auth_settings(auth_settings.mint_max_bat); + mint_builder = mint_builder.with_auth( + auth_localstore.clone(), + auth_settings.openid_discovery, + auth_settings.openid_client_id, + vec![mint_blind_auth_endpoint], + ); + mint_builder = + mint_builder.with_blind_auth(auth_settings.mint_max_bat, blind_auth_endpoints); let mut tx = auth_localstore.begin_transaction().await?; @@ -655,6 +617,43 @@ async fn setup_authentication( Ok(mint_builder) } +/// Build mints with the configured the signing method (remote signatory or local seed) +async fn build_mint( + settings: &config::Settings, + keystore: Arc + Send + Sync>, + mint_builder: MintBuilder, +) -> Result { + if let Some(signatory_url) = settings.info.signatory_url.clone() { + tracing::info!( + "Connecting to remote signatory to {} with certs {:?}", + signatory_url, + settings.info.signatory_certs.clone() + ); + + Ok(mint_builder + .build_with_signatory(Arc::new( + cdk_signatory::SignatoryRpcClient::new( + signatory_url, + settings.info.signatory_certs.clone(), + ) + .await?, + )) + .await?) + } else if let Some(mnemonic) = settings + .info + .mnemonic + .clone() + .map(|s| Mnemonic::from_str(&s)) + .transpose()? + { + Ok(mint_builder + .build_with_seed(keystore, &mnemonic.to_seed_normalized("")) + .await?) + } else { + bail!("No seed nor remote signatory set"); + } +} + async fn start_services( mint: Arc, settings: &config::Settings, @@ -704,7 +703,7 @@ async fn start_services( mint.set_mint_info(mint_builder_info).await?; mint.set_quote_ttl(QuoteTTL::new(10_000, 10_000)).await?; } else { - if mint.localstore.get_quote_ttl().await.is_err() { + if mint.localstore().get_quote_ttl().await.is_err() { mint.set_quote_ttl(QuoteTTL::new(10_000, 10_000)).await?; } // Add version information diff --git a/crates/cdk/examples/auth_wallet.rs b/crates/cdk/examples/auth_wallet.rs index afb58b377..4eff20ac6 100644 --- a/crates/cdk/examples/auth_wallet.rs +++ b/crates/cdk/examples/auth_wallet.rs @@ -112,7 +112,7 @@ async fn get_access_token(mint_info: &MintInfo) -> String { .expect("Nut21 defined") .openid_discovery; - let oidc_client = OidcClient::new(openid_discovery); + let oidc_client = OidcClient::new(openid_discovery, None); // Get the token endpoint from the OIDC configuration let token_url = oidc_client diff --git a/crates/cdk/src/mint/builder.rs b/crates/cdk/src/mint/builder.rs index fbdc96413..f028a5874 100644 --- a/crates/cdk/src/mint/builder.rs +++ b/crates/cdk/src/mint/builder.rs @@ -3,13 +3,13 @@ use std::collections::HashMap; use std::sync::Arc; -use anyhow::anyhow; use bitcoin::bip32::DerivationPath; use cdk_common::database::{self, MintDatabase, MintKeysDatabase}; use cdk_common::error::Error; use cdk_common::nut04::MintMethodOptions; use cdk_common::nut05::MeltMethodOptions; use cdk_common::payment::Bolt11Settings; +#[cfg(feature = "auth")] use cdk_common::{nut21, nut22}; use cdk_signatory::signatory::Signatory; @@ -19,103 +19,91 @@ use super::nut19::{self, CachedEndpoint}; use super::MintAuthDatabase; use super::Nuts; use crate::amount::Amount; -#[cfg(feature = "auth")] use crate::cdk_database; use crate::cdk_payment::{self, MintPayment}; use crate::mint::Mint; +#[cfg(feature = "auth")] +use crate::nuts::ProtectedEndpoint; use crate::nuts::{ ContactInfo, CurrencyUnit, MeltMethodSettings, MintInfo, MintMethodSettings, MintVersion, MppMethodSettings, PaymentMethod, }; use crate::types::PaymentProcessorKey; -/// Cashu Mint -#[derive(Default)] +/// Cashu Mint Builder pub struct MintBuilder { - /// Mint Info - pub mint_info: MintInfo, - /// Mint Storage backend - pub localstore: Option + Send + Sync>>, - /// Database for the Signatory - keystore: Option + Send + Sync>>, - /// Mint Storage backend + mint_info: MintInfo, + localstore: Arc + Send + Sync>, #[cfg(feature = "auth")] auth_localstore: Option + Send + Sync>>, - /// Ln backends for mint - ln: Option< + payment_processors: HashMap + Send + Sync>>, - >, - seed: Option>, supported_units: HashMap, custom_paths: HashMap, - // protected_endpoints: HashMap, - openid_discovery: Option, - signatory: Option>, } impl MintBuilder { - /// New mint builder - pub fn new() -> MintBuilder { - let mut builder = MintBuilder::default(); - - let nuts = Nuts::new() - .nut07(true) - .nut08(true) - .nut09(true) - .nut10(true) - .nut11(true) - .nut12(true) - .nut14(true) - .nut20(true); - - builder.mint_info.nuts = nuts; - - builder - } - - /// Set signatory service - pub fn with_signatory(mut self, signatory: Arc) -> Self { - self.signatory = Some(signatory); - self - } - - /// Set seed - pub fn with_seed(mut self, seed: Vec) -> Self { - self.seed = Some(seed); - self - } + /// New [`MintBuilder`] + pub fn new(localstore: Arc + Send + Sync>) -> MintBuilder { + let mint_info = MintInfo { + nuts: Nuts::new() + .nut07(true) + .nut08(true) + .nut09(true) + .nut10(true) + .nut11(true) + .nut12(true), + ..Default::default() + }; - /// Set localstore - pub fn with_localstore( - mut self, - localstore: Arc + Send + Sync>, - ) -> MintBuilder { - self.localstore = Some(localstore); - self + MintBuilder { + mint_info, + localstore, + #[cfg(feature = "auth")] + auth_localstore: None, + payment_processors: HashMap::new(), + supported_units: HashMap::new(), + custom_paths: HashMap::new(), + } } - /// Set keystore database - pub fn with_keystore( + /// Set clear auth settings + #[cfg(feature = "auth")] + pub fn with_auth( mut self, - keystore: Arc + Send + Sync>, - ) -> MintBuilder { - self.keystore = Some(keystore); + auth_localstore: Arc + Send + Sync>, + openid_discovery: String, + client_id: String, + protected_endpoints: Vec, + ) -> Self { + self.auth_localstore = Some(auth_localstore); + self.mint_info.nuts.nut21 = Some(nut21::Settings::new( + openid_discovery, + client_id, + protected_endpoints, + )); self } - /// Set auth localstore + /// Set blind auth settings #[cfg(feature = "auth")] - pub fn with_auth_localstore( + pub fn with_blind_auth( mut self, - localstore: Arc + Send + Sync>, - ) -> MintBuilder { - self.auth_localstore = Some(localstore); + bat_max_mint: u64, + protected_endpoints: Vec, + ) -> Self { + let mut nuts = self.mint_info.nuts; + + nuts.nut22 = Some(nut22::Settings::new(bat_max_mint, protected_endpoints)); + + self.mint_info.nuts = nuts; + self } - /// Set Openid discovery url - pub fn with_openid_discovery(mut self, openid_discovery: String) -> Self { - self.openid_discovery = Some(openid_discovery); + /// Set mint info + pub fn with_mint_info(mut self, mint_info: MintInfo) -> Self { + self.mint_info = mint_info; self } @@ -168,32 +156,68 @@ impl MintBuilder { } /// Set contact info - pub fn add_contact_info(mut self, contact_info: ContactInfo) -> Self { + pub fn with_contact_info(mut self, contact_info: ContactInfo) -> Self { let mut contacts = self.mint_info.contact.clone().unwrap_or_default(); contacts.push(contact_info); self.mint_info.contact = Some(contacts); self } - /// Add ln backend - pub async fn add_ln_backend( + /// Set pubkey + pub fn with_pubkey(mut self, pubkey: crate::nuts::PublicKey) -> Self { + self.mint_info.pubkey = Some(pubkey); + + self + } + + /// Support websockets + pub fn with_supported_websockets(mut self, supported_method: SupportedMethods) -> Self { + let mut supported_settings = self.mint_info.nuts.nut17.supported.clone(); + + if !supported_settings.contains(&supported_method) { + supported_settings.push(supported_method); + + self.mint_info.nuts = self.mint_info.nuts.nut17(supported_settings); + } + + self + } + + /// Add support for NUT19 + pub fn with_cache(mut self, ttl: Option, cached_endpoints: Vec) -> Self { + let nut19_settings = nut19::Settings { + ttl, + cached_endpoints, + }; + + self.mint_info.nuts.nut19 = nut19_settings; + + self + } + + /// Set custom derivation paths for mint units + pub fn with_custom_derivation_paths( mut self, + custom_paths: HashMap, + ) -> Self { + self.custom_paths = custom_paths; + self + } + + /// Add payment processor + pub async fn add_payment_processor( + &mut self, unit: CurrencyUnit, method: PaymentMethod, limits: MintMeltLimits, - ln_backend: Arc + Send + Sync>, - ) -> Result { - let ln_key = PaymentProcessorKey { + payment_processor: Arc + Send + Sync>, + ) -> Result<(), Error> { + let key = PaymentProcessorKey { unit: unit.clone(), method: method.clone(), }; - tracing::debug!("Adding ln backed for {}, {}", unit, method); - tracing::debug!("with limits {:?}", limits); - - let mut ln = self.ln.unwrap_or_default(); - - let settings = ln_backend.get_settings().await?; + let settings = payment_processor.get_settings().await?; let settings: Bolt11Settings = settings.try_into()?; @@ -235,91 +259,19 @@ impl MintBuilder { self.mint_info.nuts.nut05.methods.push(melt_method_settings); self.mint_info.nuts.nut05.disabled = false; - ln.insert(ln_key.clone(), ln_backend); - let mut supported_units = self.supported_units.clone(); - supported_units.insert(ln_key.unit, (0, 32)); + supported_units.insert(key.unit.clone(), (0, 32)); self.supported_units = supported_units; - self.ln = Some(ln); - - Ok(self) - } - - /// Set pubkey - pub fn with_pubkey(mut self, pubkey: crate::nuts::PublicKey) -> Self { - self.mint_info.pubkey = Some(pubkey); - - self - } - - /// Support websockets - pub fn add_supported_websockets(mut self, supported_method: SupportedMethods) -> Self { - let mut supported_settings = self.mint_info.nuts.nut17.supported.clone(); - - if !supported_settings.contains(&supported_method) { - supported_settings.push(supported_method); - - self.mint_info.nuts = self.mint_info.nuts.nut17(supported_settings); - } - - self - } - - /// Add support for NUT19 - pub fn add_cache(mut self, ttl: Option, cached_endpoints: Vec) -> Self { - let nut19_settings = nut19::Settings { - ttl, - cached_endpoints, - }; - - self.mint_info.nuts.nut19 = nut19_settings; - - self - } - - /// Set custom derivation paths for mint units - pub fn add_custom_derivation_paths( - mut self, - custom_paths: HashMap, - ) -> Self { - self.custom_paths = custom_paths; - self - } - - /// Set clear auth settings - pub fn set_clear_auth_settings(mut self, openid_discovery: String, client_id: String) -> Self { - let mut nuts = self.mint_info.nuts; - - nuts.nut21 = Some(nut21::Settings::new( - openid_discovery.clone(), - client_id, - vec![], - )); - - self.openid_discovery = Some(openid_discovery); - - self.mint_info.nuts = nuts; - - self - } - - /// Set blind auth settings - pub fn set_blind_auth_settings(mut self, bat_max_mint: u64) -> Self { - let mut nuts = self.mint_info.nuts; - - nuts.nut22 = Some(nut22::Settings::new(bat_max_mint, vec![])); - - self.mint_info.nuts = nuts; - - self + self.payment_processors.insert(key, payment_processor); + Ok(()) } /// Sets the input fee ppk for a given unit /// /// The unit **MUST** already have been added with a ln backend - pub fn set_unit_fee(mut self, unit: &CurrencyUnit, input_fee_ppk: u64) -> Result { + pub fn set_unit_fee(&mut self, unit: &CurrencyUnit, input_fee_ppk: u64) -> Result<(), Error> { let (input_fee, _max_order) = self .supported_units .get_mut(unit) @@ -327,59 +279,53 @@ impl MintBuilder { *input_fee = input_fee_ppk; - Ok(self) + Ok(()) } - /// Build mint - pub async fn build(&self) -> anyhow::Result { - let localstore = self - .localstore - .clone() - .ok_or(anyhow!("Localstore not set"))?; - let ln = self.ln.clone().ok_or(anyhow!("Ln backends not set"))?; - - let signatory = if let Some(signatory) = self.signatory.as_ref() { - signatory.clone() - } else { - let seed = self.seed.as_ref().ok_or(anyhow!("Mint seed not set"))?; - let in_memory_signatory = cdk_signatory::db_signatory::DbSignatory::new( - self.keystore.clone().ok_or(anyhow!("keystore not set"))?, - seed, - self.supported_units.clone(), - HashMap::new(), - ) - .await?; - - Arc::new(cdk_signatory::embedded::Service::new(Arc::new( - in_memory_signatory, - ))) - }; - + /// Build the mint with the provided signatory + pub async fn build_with_signatory( + self, + signatory: Arc, + ) -> Result { #[cfg(feature = "auth")] - if let Some(openid_discovery) = &self.openid_discovery { - let auth_localstore = self - .auth_localstore - .clone() - .ok_or(anyhow!("Auth localstore not set"))?; - - return Ok(Mint::new_with_auth( + if let Some(auth_localstore) = self.auth_localstore { + return Mint::new_with_auth( + self.mint_info, signatory, - localstore, + self.localstore, auth_localstore, - ln, - openid_discovery.clone(), + self.payment_processors, ) - .await?); - } - - #[cfg(not(feature = "auth"))] - if self.openid_discovery.is_some() { - return Err(anyhow!( - "OpenID discovery URL provided but auth feature is not enabled" - )); + .await; } + Mint::new( + self.mint_info, + signatory, + self.localstore, + self.payment_processors, + ) + .await + } - Ok(Mint::new(signatory, localstore, ln).await?) + /// Build the mint with the provided keystore and seed + pub async fn build_with_seed( + self, + keystore: Arc + Send + Sync>, + seed: &[u8], + ) -> Result { + let in_memory_signatory = cdk_signatory::db_signatory::DbSignatory::new( + keystore, + seed, + self.supported_units.clone(), + HashMap::new(), + ) + .await?; + + let signatory = Arc::new(cdk_signatory::embedded::Service::new(Arc::new( + in_memory_signatory, + ))); + + self.build_with_signatory(signatory).await } } diff --git a/crates/cdk/src/mint/ln.rs b/crates/cdk/src/mint/ln.rs index 5ffb3e4aa..281638d1a 100644 --- a/crates/cdk/src/mint/ln.rs +++ b/crates/cdk/src/mint/ln.rs @@ -23,7 +23,7 @@ impl Mint { return Ok(()); } - let ln = match self.ln.get(&PaymentProcessorKey::new( + let ln = match self.payment_processors.get(&PaymentProcessorKey::new( quote.unit.clone(), quote.payment_method.clone(), )) { diff --git a/crates/cdk/src/mint/melt.rs b/crates/cdk/src/mint/melt.rs index d0792ca0c..fecb1540b 100644 --- a/crates/cdk/src/mint/melt.rs +++ b/crates/cdk/src/mint/melt.rs @@ -152,7 +152,7 @@ impl Mint { .await?; let ln = self - .ln + .payment_processors .get(&PaymentProcessorKey::new( unit.clone(), PaymentMethod::Bolt11, @@ -250,7 +250,7 @@ impl Mint { .await?; let ln = self - .ln + .payment_processors .get(&PaymentProcessorKey::new( unit.clone(), PaymentMethod::Bolt12, @@ -586,7 +586,7 @@ impl Mint { _ => None, }; tracing::debug!("partial_amount: {:?}", partial_amount); - let ln = match self.ln.get(&PaymentProcessorKey::new( + let ln = match self.payment_processors.get(&PaymentProcessorKey::new( quote.unit.clone(), PaymentMethod::Bolt11, )) { diff --git a/crates/cdk/src/mint/mod.rs b/crates/cdk/src/mint/mod.rs index bd89527a0..522076d4d 100644 --- a/crates/cdk/src/mint/mod.rs +++ b/crates/cdk/src/mint/mod.rs @@ -53,17 +53,17 @@ pub struct Mint { /// /// It is implemented in the cdk-signatory crate, and it can be embedded in the mint or it can /// be a gRPC client to a remote signatory server. - pub signatory: Arc, + signatory: Arc, /// Mint Storage backend - pub localstore: Arc + Send + Sync>, + localstore: Arc + Send + Sync>, /// Auth Storage backend (only available with auth feature) #[cfg(feature = "auth")] - pub auth_localstore: Option + Send + Sync>>, - /// Ln backends for mint - pub ln: + auth_localstore: Option + Send + Sync>>, + /// Payment processors for mint + payment_processors: HashMap + Send + Sync>>, /// Subscription manager - pub pubsub_manager: Arc, + pubsub_manager: Arc, #[cfg(feature = "auth")] oidc_client: Option, /// In-memory keyset @@ -71,40 +71,23 @@ pub struct Mint { } impl Mint { - /// Get the payment processor for the given unit and payment method - pub fn get_payment_processor( - &self, - unit: CurrencyUnit, - payment_method: PaymentMethod, - ) -> Result + Send + Sync>, Error> { - let key = PaymentProcessorKey::new(unit.clone(), payment_method.clone()); - self.ln.get(&key).cloned().ok_or_else(|| { - tracing::info!( - "No payment processor set for pair {}, {}", - unit, - payment_method - ); - Error::UnsupportedUnit - }) - } - /// Create new [`Mint`] without authentication pub async fn new( + mint_info: MintInfo, signatory: Arc, localstore: Arc + Send + Sync>, - ln: HashMap< + payment_processors: HashMap< PaymentProcessorKey, Arc + Send + Sync>, >, ) -> Result { Self::new_internal( + mint_info, signatory, localstore, #[cfg(feature = "auth")] None, - ln, - #[cfg(feature = "auth")] - None, + payment_processors, ) .await } @@ -112,21 +95,21 @@ impl Mint { /// Create new [`Mint`] with authentication support #[cfg(feature = "auth")] pub async fn new_with_auth( + mint_info: MintInfo, signatory: Arc, localstore: Arc + Send + Sync>, auth_localstore: Arc + Send + Sync>, - ln: HashMap< + payment_processors: HashMap< PaymentProcessorKey, Arc + Send + Sync>, >, - open_id_discovery: String, ) -> Result { Self::new_internal( + mint_info, signatory, localstore, Some(auth_localstore), - ln, - Some(open_id_discovery), + payment_processors, ) .await } @@ -134,21 +117,17 @@ impl Mint { /// Internal function to create a new [`Mint`] with shared logic #[inline] async fn new_internal( + mint_info: MintInfo, signatory: Arc, localstore: Arc + Send + Sync>, #[cfg(feature = "auth")] auth_localstore: Option< Arc + Send + Sync>, >, - ln: HashMap< + payment_processors: HashMap< PaymentProcessorKey, Arc + Send + Sync>, >, - #[cfg(feature = "auth")] open_id_discovery: Option, ) -> Result { - #[cfg(feature = "auth")] - let oidc_client = - open_id_discovery.map(|openid_discovery| OidcClient::new(openid_discovery.clone())); - let keysets = signatory.keysets().await?; if !keysets .keysets @@ -168,19 +147,57 @@ impl Mint { .count() ); + let mint_store = localstore.clone(); + let mut tx = mint_store.begin_transaction().await?; + tx.set_mint_info(mint_info.clone()).await?; + tx.set_quote_ttl(QuoteTTL::default()).await?; + tx.commit().await?; + Ok(Self { signatory, pubsub_manager: Arc::new(localstore.clone().into()), localstore, #[cfg(feature = "auth")] - oidc_client, - ln, + oidc_client: mint_info.nuts.nut21.as_ref().map(|nut21| { + OidcClient::new( + nut21.openid_discovery.clone(), + Some(nut21.client_id.clone()), + ) + }), + payment_processors, #[cfg(feature = "auth")] auth_localstore, keysets: Arc::new(ArcSwap::new(keysets.keysets.into())), }) } + /// Get the payment processor for the given unit and payment method + pub fn get_payment_processor( + &self, + unit: CurrencyUnit, + payment_method: PaymentMethod, + ) -> Result + Send + Sync>, Error> { + let key = PaymentProcessorKey::new(unit.clone(), payment_method.clone()); + self.payment_processors.get(&key).cloned().ok_or_else(|| { + tracing::info!( + "No payment processor set for pair {}, {}", + unit, + payment_method + ); + Error::UnsupportedUnit + }) + } + + /// Localstore + pub fn localstore(&self) -> Arc + Send + Sync> { + Arc::clone(&self.localstore) + } + + /// Pub Sub manager + pub fn pubsub_manager(&self) -> Arc { + Arc::clone(&self.pubsub_manager) + } + /// Get mint info #[instrument(skip_all)] pub async fn mint_info(&self) -> Result { @@ -259,7 +276,7 @@ impl Mint { Vec, )> = Vec::new(); - for (key, ln) in self.ln.iter() { + for (key, ln) in self.payment_processors.iter() { // Check if we already have this processor let found = processor_groups.iter_mut().find(|(proc_ref, _)| { // Compare Arc pointer equality using ptr_eq @@ -609,7 +626,7 @@ mod tests { .expect("Failed to create signatory"), ); - Mint::new(signatory, localstore, HashMap::new()) + Mint::new(MintInfo::default(), signatory, localstore, HashMap::new()) .await .unwrap() } diff --git a/crates/cdk/src/mint/start_up_check.rs b/crates/cdk/src/mint/start_up_check.rs index fa265a085..44a106369 100644 --- a/crates/cdk/src/mint/start_up_check.rs +++ b/crates/cdk/src/mint/start_up_check.rs @@ -27,7 +27,7 @@ impl Mint { method: PaymentMethod::Bolt11, }; - let ln_backend = match self.ln.get(&ln_key) { + let ln_backend = match self.payment_processors.get(&ln_key) { Some(ln_backend) => ln_backend, None => { tracing::warn!("No backend for ln key: {:?}", ln_key); diff --git a/crates/cdk/src/oidc_client.rs b/crates/cdk/src/oidc_client.rs index a01f2368e..59d10ffc7 100644 --- a/crates/cdk/src/oidc_client.rs +++ b/crates/cdk/src/oidc_client.rs @@ -32,9 +32,9 @@ pub enum Error { /// Unsupported Algo #[error("Unsupported signing algo")] UnsupportedSigningAlgo, - /// Access token not returned - #[error("Error getting access token")] - AccessTokenMissing, + /// Invalid Client ID + #[error("Invalid Client ID")] + InvalidClientId, } impl From for cdk_common::error::Error { @@ -58,6 +58,7 @@ pub struct OidcConfig { pub struct OidcClient { client: Client, openid_discovery: String, + client_id: Option, oidc_config: Arc>>, jwks_set: Arc>>, } @@ -88,10 +89,11 @@ pub struct TokenResponse { impl OidcClient { /// Create new [`OidcClient`] - pub fn new(openid_discovery: String) -> Self { + pub fn new(openid_discovery: String, client_id: Option) -> Self { Self { client: Client::new(), openid_discovery, + client_id, oidc_config: Arc::new(RwLock::new(None)), jwks_set: Arc::new(RwLock::new(None)), } @@ -192,11 +194,40 @@ impl OidcClient { validation }; - if let Err(err) = - decode::>(cat_jwt, &decoding_key, &validation) - { - tracing::debug!("Could not verify cat: {}", err); - return Err(err.into()); + match decode::>(cat_jwt, &decoding_key, &validation) { + Ok(claims) => { + tracing::debug!("Successfully verified cat"); + tracing::debug!("Claims: {:?}", claims.claims); + if let Some(client_id) = &self.client_id { + if let Some(token_client_id) = claims.claims.get("client_id") { + if let Some(token_client_id_value) = token_client_id.as_str() { + if token_client_id_value != client_id { + tracing::warn!( + "Client ID mismatch: expected {}, got {}", + client_id, + token_client_id_value + ); + return Err(Error::InvalidClientId); + } + } + } else if let Some(azp) = claims.claims.get("azp") { + if let Some(azp_value) = azp.as_str() { + if azp_value != client_id { + tracing::warn!( + "Client ID (azp) mismatch: expected {}, got {}", + client_id, + azp_value + ); + return Err(Error::InvalidClientId); + } + } + } + } + } + Err(err) => { + tracing::debug!("Could not verify cat: {}", err); + return Err(err.into()); + } } Ok(()) diff --git a/crates/cdk/src/wallet/mod.rs b/crates/cdk/src/wallet/mod.rs index 1aa4db9a4..bfec189f8 100644 --- a/crates/cdk/src/wallet/mod.rs +++ b/crates/cdk/src/wallet/mod.rs @@ -268,8 +268,9 @@ impl Wallet { auth_wallet.protected_endpoints.write().await; *protected_endpoints = mint_info.protected_endpoints(); - if let Some(oidc_client) = - mint_info.openid_discovery().map(OidcClient::new) + if let Some(oidc_client) = mint_info + .openid_discovery() + .map(|url| OidcClient::new(url, None)) { auth_wallet.set_oidc_client(Some(oidc_client)).await; } @@ -277,7 +278,9 @@ impl Wallet { None => { tracing::info!("Mint has auth enabled creating auth wallet"); - let oidc_client = mint_info.openid_discovery().map(OidcClient::new); + let oidc_client = mint_info + .openid_discovery() + .map(|url| OidcClient::new(url, None)); let new_auth_wallet = AuthWallet::new( self.mint_url.clone(), None, From e639bd4021868e0ea2888f1d101804468e67b758 Mon Sep 17 00:00:00 2001 From: asmo Date: Tue, 22 Jul 2025 15:27:18 +0200 Subject: [PATCH 025/321] fakewallet: convert sat to msat (#899) --- crates/cdk-fake-wallet/src/lib.rs | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/crates/cdk-fake-wallet/src/lib.rs b/crates/cdk-fake-wallet/src/lib.rs index 38d241b73..eeebfa55a 100644 --- a/crates/cdk-fake-wallet/src/lib.rs +++ b/crates/cdk-fake-wallet/src/lib.rs @@ -352,7 +352,12 @@ impl MintPayment for FakeWallet { } IncomingPaymentOptions::Bolt11(bolt11_options) => { let description = bolt11_options.description.unwrap_or_default(); - let amount = bolt11_options.amount; + let amount = if unit == &CurrencyUnit::Sat { + to_unit(bolt11_options.amount, unit, &CurrencyUnit::Msat) + .unwrap_or(bolt11_options.amount * Amount::from(1000)) + } else { + bolt11_options.amount + }; let expiry = bolt11_options.unix_expiry; // Since this is fake we just use the amount no matter the unit to create an invoice From 7ee0fe03850fe9fa9aff1d6ebb4e6ed133fde1d6 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Tue, 22 Jul 2025 23:31:17 +0100 Subject: [PATCH 026/321] feat(misc): add Goose AI recipes for automated changelog and git message generation - Add changelog-update.yaml recipe for analyzing staged changes and updating CHANGELOG.md - Add git-commit-message.yaml recipe for creating conventional commit messages - Add justfile commands (goose-changelog-update, goose-git-msg) for running recipes - Update CHANGELOG.md with new recipe functionality entries --- CHANGELOG.md | 14 +++++ justfile | 12 ++++ misc/recipes/changelog-update.yaml | 73 ++++++++++++++++++++++++ misc/recipes/git-commit-message.yaml | 83 ++++++++++++++++++++++++++++ 4 files changed, 182 insertions(+) create mode 100644 misc/recipes/changelog-update.yaml create mode 100644 misc/recipes/git-commit-message.yaml diff --git a/CHANGELOG.md b/CHANGELOG.md index 8f6db7ad5..1fc77a772 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,20 @@ +## [Unreleased] + +### Added +- cashu: `KeySetInfos` type alias and `KeySetInfosMethods` trait for filtering keysets ([thesimplekid]). + +### Changed +- cdk: Refactored wallet keyset management methods for better clarity and separation of concerns ([thesimplekid]). +- cdk: Renamed `get_keyset_keys` to `fetch_keyset_keys` to indicate network operation ([thesimplekid]). +- cdk: Renamed `get_active_mint_keyset` to `fetch_active_keyset` for consistency ([thesimplekid]). +- cdk: Updated `get_active_mint_keysets` to `refresh_keysets` with improved keyset refresh logic ([thesimplekid]). +- cdk: Improved `load_mint_keysets` method to be the primary method for getting keysets for token operations ([thesimplekid]). +- cdk: Enhanced keyset management with better offline/online operation separation ([thesimplekid]). +- cdk: Updated method documentation to clarify storage vs network operations ([thesimplekid]). + ## [0.11.0](https://github.com/cashubtc/cdk/releases/tag/v0.11.0) diff --git a/justfile b/justfile index 21b085faf..19c4a66c7 100644 --- a/justfile +++ b/justfile @@ -129,6 +129,18 @@ typos: typos-fix: just typos -w +# Goose AI Recipe Commands + +# Create git message from staged changes using Goose AI +goose-changelog-update: + #!/usr/bin/env bash + goose run --recipe ./misc/recipes/changelog-update.yaml --interactive + +# Update changelog from staged changes using Goose AI +goose-git-msg: + #!/usr/bin/env bash + goose run --recipe ./misc/recipes/git-commit-message.yaml --interactive + itest db: #!/usr/bin/env bash ./misc/itests.sh "{{db}}" diff --git a/misc/recipes/changelog-update.yaml b/misc/recipes/changelog-update.yaml new file mode 100644 index 000000000..75afcd9ff --- /dev/null +++ b/misc/recipes/changelog-update.yaml @@ -0,0 +1,73 @@ +version: 1.0.0 +title: Update Changelog from staged +description: a custom recipe instance from this chat session +instructions: Analyze staged Git changes and automatically update project changelogs following Keep a Changelog format. Read staged files using git diff, understand the nature of code changes (API refactoring, new features, bug fixes, etc.), and add appropriately categorized entries to the Unreleased section. Use the git author's username for attribution and follow established changelog patterns including proper formatting with contributor links. Requires git command line tools and file editing capabilities. +prompt: | + You are tasked with updating the CHANGELOG.md file based on staged Git changes. Follow these instructions: + + ## Analysis Process: + 1. **Read staged changes**: Use `git diff --staged` to analyze what files and code changes are currently staged for commit + 2. **Get git author**: Use `git config --get user.name` to get the author name for attribution + 3. **Analyze change types**: Categorize changes into: + - **Added**: New features, new functions, new files, new functionality + - **Changed**: Modifications to existing functionality, refactoring, API changes, dependency updates + - **Fixed**: Bug fixes, error handling improvements, corrections + - **Removed**: Deleted files, deprecated functions, removed dependencies + + ## CHANGELOG.md Update Requirements: + 1. **Preserve existing format**: Keep the exact formatting style of the existing CHANGELOG.md + 2. **Update Unreleased section**: Add new entries to the "## [Unreleased]" section only + 3. **Use proper categories**: Add entries under the appropriate subsections (Added, Changed, Fixed, Removed) + 4. **Follow format pattern**: Each entry should follow this exact format: + ``` + - component: Description of change ([author]). + ``` + 5. **Author attribution**: Use the git author name in square brackets at the end of each entry + 6. **Component identification**: Identify the relevant component (e.g., "cdk", "cashu", "cdk-cli", etc.) from file paths + 7. **Maintain formatting**: + - Use proper bullet points with hyphens + - Maintain consistent spacing + - Keep entries concise but descriptive + - End each entry with period before author attribution + + ## Example Entry Format: + ```markdown + ### Added + - cdk: New keyset refresh functionality with improved error handling ([thesimplekid]). + + ### Changed + - cdk: Refactored wallet keyset management for better performance ([thesimplekid]). + + ### Fixed + - cdk-cli: Fixed token parsing error for malformed inputs ([thesimplekid]). + ``` + + ## Important Guidelines: + - **DO NOT** modify any existing changelog entries + - **DO NOT** change the structure or format of the changelog + - **ONLY** add new entries to the Unreleased section + - **DO NOT** add duplicate entries + - **BE SPECIFIC** about what changed, not just which files + - **FOCUS** on user-facing changes and important internal improvements + - **IGNORE** trivial changes like whitespace, comments, or formatting unless they're significant + + ## Steps to Execute: + 1. Read current CHANGELOG.md file to understand format + 2. Get git author name + 3. Analyze staged changes with `git diff --staged` + 4. Categorize and write appropriate changelog entries + 5. Update the CHANGELOG.md file preserving all existing content +extensions: +- type: builtin + name: developer + display_name: Developer + timeout: 300 + bundled: true +activities: +- Update changelog from staged changes +- Analyze API refactoring commits +- Add new feature entries +- Categorize bug fix changes +- Format contributor attributions +author: + contact: thesimplekid diff --git a/misc/recipes/git-commit-message.yaml b/misc/recipes/git-commit-message.yaml new file mode 100644 index 000000000..c0ceea316 --- /dev/null +++ b/misc/recipes/git-commit-message.yaml @@ -0,0 +1,83 @@ +version: 1.0.0 +title: Create git commit message from staged changes +description: Generate meaningful git commit messages by analyzing staged changes +prompt: | + You are tasked with creating a clear and descriptive git commit message based on staged Git changes. Follow these instructions: + + ## Analysis Process: + 1. **Read staged changes**: Use `git diff --staged` to analyze what files and code changes are currently staged for commit + 2. **Analyze change scope**: Identify which components/modules are affected (e.g., cdk, cashu, cdk-cli, etc.) + 3. **Determine change type**: Categorize the primary change as: + - **feat**: New features or functionality + - **fix**: Bug fixes + - **refactor**: Code refactoring without functional changes + - **docs**: Documentation changes + - **style**: Code style/formatting changes + - **test**: Adding or updating tests + - **chore**: Maintenance tasks, dependency updates, build changes + + ## Commit Message Format: + Follow conventional commit format: + ``` + type(scope): description + + Optional body with more details if needed + ``` + + ### Examples: + ``` + feat(cdk): add keyset refresh functionality with improved error handling + + refactor(wallet): improve keyset management for better performance + + fix(cdk-cli): resolve token parsing error for malformed inputs + + docs(README): update installation instructions + + chore(deps): update rust dependencies to latest versions + ``` + + ## Commit Message Guidelines: + 1. **Subject line (first line)**: + - Start with conventional commit type and scope + - Use imperative mood ("add", "fix", "update", not "added", "fixed", "updated") + - Keep under 72 characters + - Don't end with a period + - Be specific and descriptive + + 2. **Body (optional)**: + - Add if the change needs more explanation + - Wrap at 72 characters + - Explain **what** and **why**, not **how** + - Separate from subject with blank line + + 3. **Scope identification**: + - Use component names from file paths (cdk, cashu, cdk-cli, etc.) + - Use general scopes like "deps", "ci", "docs" for broad changes + - Omit scope if change affects multiple unrelated areas + + ## Analysis Priority: + 1. **Focus on the main change**: If multiple types of changes, pick the most significant one + 2. **Combine related changes**: Group similar modifications into one cohesive message + 3. **Ignore trivial changes**: Don't mention minor formatting, whitespace, or comment changes unless that's the primary purpose + 4. **Be user/developer focused**: Describe impact rather than implementation details + + ## Steps to Execute: + 1. Analyze staged changes with `git diff --staged` + 2. Identify primary change type and affected components + 3. Write a clear, descriptive commit message following conventional format + 4. Output ONLY the commit message (no additional explanation unless asked) +extensions: +- type: builtin + name: developer + display_name: Developer + timeout: 300 + bundled: true +activities: +- Analyze staged git changes +- Generate conventional commit messages +- Identify change types and scopes +- Create clear and descriptive commit subjects +- Format commit messages properly +author: + contact: thesimplekid From 6e0c3a3f7f051f8fe89361b2cee67c6cd088ed0d Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Wed, 23 Jul 2025 13:08:20 +0100 Subject: [PATCH 027/321] feat(cdk): add mint lifecycle management with start/stop methods - 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 --- CHANGELOG.md | 5 + .../src/init_pure_tests.rs | 9 +- crates/cdk-mintd/src/main.rs | 11 +- crates/cdk/src/mint/mod.rs | 368 +++++++++++++++--- 4 files changed, 319 insertions(+), 74 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1fc77a772..4d2b663d0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,8 @@ ### Added - cashu: `KeySetInfos` type alias and `KeySetInfosMethods` trait for filtering keysets ([thesimplekid]). +- cdk: Mint lifecycle management with `start()` and `stop()` methods for graceful background service control ([thesimplekid]). +- cdk: Background task management for invoice payment monitoring with proper shutdown handling ([thesimplekid]). ### Changed - cdk: Refactored wallet keyset management methods for better clarity and separation of concerns ([thesimplekid]). @@ -17,6 +19,9 @@ - cdk: Improved `load_mint_keysets` method to be the primary method for getting keysets for token operations ([thesimplekid]). - cdk: Enhanced keyset management with better offline/online operation separation ([thesimplekid]). - cdk: Updated method documentation to clarify storage vs network operations ([thesimplekid]). +- cdk: Refactored invoice payment monitoring to use centralized lifecycle management instead of manual task spawning ([thesimplekid]). +- cdk-mintd: Updated to use new mint lifecycle methods for improved service management ([thesimplekid]). +- cdk-integration-tests: Updated test utilities to use new mint lifecycle management ([thesimplekid]). diff --git a/crates/cdk-integration-tests/src/init_pure_tests.rs b/crates/cdk-integration-tests/src/init_pure_tests.rs index 9d64035f4..f55e1d1d4 100644 --- a/crates/cdk-integration-tests/src/init_pure_tests.rs +++ b/crates/cdk-integration-tests/src/init_pure_tests.rs @@ -24,7 +24,7 @@ use cdk::util::unix_time; use cdk::wallet::{AuthWallet, MintConnector, Wallet, WalletBuilder}; use cdk::{Amount, Error, Mint}; use cdk_fake_wallet::FakeWallet; -use tokio::sync::{Notify, RwLock}; +use tokio::sync::RwLock; use tracing_subscriber::EnvFilter; use uuid::Uuid; @@ -282,12 +282,7 @@ pub async fn create_and_start_test_mint() -> Result { .build_with_seed(localstore.clone(), &mnemonic.to_seed_normalized("")) .await?; - let mint_clone = mint.clone(); - let shutdown = Arc::new(Notify::new()); - tokio::spawn({ - let shutdown = Arc::clone(&shutdown); - async move { mint_clone.wait_for_paid_invoices(shutdown).await } - }); + mint.start().await?; Ok(mint) } diff --git a/crates/cdk-mintd/src/main.rs b/crates/cdk-mintd/src/main.rs index 6296325c5..59cbe46b8 100644 --- a/crates/cdk-mintd/src/main.rs +++ b/crates/cdk-mintd/src/main.rs @@ -49,7 +49,6 @@ use cdk_mintd::setup::LnBackendSetup; use cdk_sqlite::mint::MintSqliteAuthDatabase; use cdk_sqlite::MintSqliteDatabase; use clap::Parser; -use tokio::sync::Notify; use tower::ServiceBuilder; use tower_http::compression::CompressionLayer; use tower_http::decompression::RequestDecompressionLayer; @@ -757,12 +756,7 @@ async fn start_services( mint_service = mint_service.merge(router); } - let shutdown = Arc::new(Notify::new()); - let mint_clone = Arc::clone(&mint); - tokio::spawn({ - let shutdown = Arc::clone(&shutdown); - async move { mint_clone.wait_for_paid_invoices(shutdown).await } - }); + mint.start().await?; let socket_addr = SocketAddr::from_str(&format!("{listen_addr}:{listen_port}"))?; @@ -784,8 +778,7 @@ async fn start_services( } } - // Notify all waiting tasks to shutdown - shutdown.notify_waiters(); + mint.stop().await?; #[cfg(feature = "management-rpc")] { diff --git a/crates/cdk/src/mint/mod.rs b/crates/cdk/src/mint/mod.rs index 522076d4d..b29d220b9 100644 --- a/crates/cdk/src/mint/mod.rs +++ b/crates/cdk/src/mint/mod.rs @@ -2,6 +2,7 @@ use std::collections::HashMap; use std::sync::Arc; +use std::time::Duration; use arc_swap::ArcSwap; use cdk_common::common::{PaymentProcessorKey, QuoteTTL}; @@ -9,14 +10,15 @@ use cdk_common::common::{PaymentProcessorKey, QuoteTTL}; use cdk_common::database::MintAuthDatabase; use cdk_common::database::{self, MintDatabase, MintTransaction}; use cdk_common::nuts::{self, BlindSignature, BlindedMessage, CurrencyUnit, Id, Kind}; +use cdk_common::payment::WaitPaymentResponse; use cdk_common::secret; use cdk_signatory::signatory::{Signatory, SignatoryKeySet}; use futures::StreamExt; #[cfg(feature = "auth")] use nut21::ProtectedEndpoint; use subscription::PubSubManager; -use tokio::sync::Notify; -use tokio::task::JoinSet; +use tokio::sync::{Mutex, Notify}; +use tokio::task::{JoinHandle, JoinSet}; use tracing::instrument; use uuid::Uuid; @@ -68,6 +70,17 @@ pub struct Mint { oidc_client: Option, /// In-memory keyset keysets: Arc>>, + /// Background task management + task_state: Arc>, +} + +/// State for managing background tasks +#[derive(Default)] +struct TaskState { + /// Shutdown signal for all background tasks + shutdown_notify: Option>, + /// Handle to the main supervisor task + supervisor_handle: Option>>, } impl Mint { @@ -168,9 +181,112 @@ impl Mint { #[cfg(feature = "auth")] auth_localstore, keysets: Arc::new(ArcSwap::new(keysets.keysets.into())), + task_state: Arc::new(Mutex::new(TaskState::default())), }) } + /// Start the mint's background services and operations + /// + /// This function immediately starts background services and returns. The background + /// tasks will continue running until `stop()` is called. + /// + /// # Returns + /// + /// Returns `Ok(())` if background services started successfully, or an `Error` + /// if startup failed. + /// + /// # Background Services + /// + /// Currently manages: + /// - Invoice payment monitoring across all configured payment processors + /// + /// Future services may include: + /// - Quote cleanup and expiration management + /// - Periodic database maintenance + /// - Health check monitoring + /// - Metrics collection + pub async fn start(&self) -> Result<(), Error> { + let mut task_state = self.task_state.lock().await; + + // Prevent starting if already running + if task_state.shutdown_notify.is_some() { + return Err(Error::Internal); // Already started + } + + // Create shutdown signal + let shutdown_notify = Arc::new(Notify::new()); + + // Clone required components for the background task + let payment_processors = self.payment_processors.clone(); + let localstore = Arc::clone(&self.localstore); + let pubsub_manager = Arc::clone(&self.pubsub_manager); + let shutdown_clone = shutdown_notify.clone(); + + // Spawn the supervisor task + let supervisor_handle = tokio::spawn(async move { + Self::wait_for_paid_invoices( + &payment_processors, + localstore, + pubsub_manager, + shutdown_clone, + ) + .await + }); + + // Store the handles + task_state.shutdown_notify = Some(shutdown_notify); + task_state.supervisor_handle = Some(supervisor_handle); + + tracing::info!("Mint background services started"); + Ok(()) + } + + /// Stop all background services and wait for graceful shutdown + /// + /// This function signals all background tasks to shut down and waits for them + /// to complete gracefully. It's safe to call multiple times. + /// + /// # Returns + /// + /// Returns `Ok(())` when all background services have shut down cleanly, or an + /// `Error` if there was an issue during shutdown. + pub async fn stop(&self) -> Result<(), Error> { + let mut task_state = self.task_state.lock().await; + + // Take the handles out of the state + let shutdown_notify = task_state.shutdown_notify.take(); + let supervisor_handle = task_state.supervisor_handle.take(); + + // If nothing to stop, return early + let (shutdown_notify, supervisor_handle) = match (shutdown_notify, supervisor_handle) { + (Some(notify), Some(handle)) => (notify, handle), + _ => { + tracing::debug!("Stop called but no background services were running"); + return Ok(()); // Nothing to stop + } + }; + + // Drop the lock before waiting + drop(task_state); + + tracing::info!("Stopping mint background services..."); + + // Signal shutdown + shutdown_notify.notify_waiters(); + + // Wait for supervisor to complete + match supervisor_handle.await { + Ok(result) => { + tracing::info!("Mint background services stopped"); + result + } + Err(join_error) => { + tracing::error!("Background service task panicked: {:?}", join_error); + Err(Error::Internal) + } + } + } + /// Get the payment processor for the given unit and payment method pub fn get_payment_processor( &self, @@ -262,80 +378,189 @@ impl Mint { Ok(tx.commit().await?) } - /// Wait for any invoice to be paid /// For each backend starts a task that waits for any invoice to be paid /// Once invoice is paid mint quote status is updated #[instrument(skip_all)] - pub async fn wait_for_paid_invoices(&self, shutdown: Arc) -> Result<(), Error> { - let mint_arc = Arc::new(self.clone()); - + async fn wait_for_paid_invoices( + payment_processors: &HashMap< + PaymentProcessorKey, + Arc + Send + Sync>, + >, + localstore: Arc + Send + Sync>, + pubsub_manager: Arc, + shutdown: Arc, + ) -> Result<(), Error> { let mut join_set = JoinSet::new(); - let mut processor_groups: Vec<( - Arc + Send + Sync>, - Vec, - )> = Vec::new(); - - for (key, ln) in self.payment_processors.iter() { - // Check if we already have this processor - let found = processor_groups.iter_mut().find(|(proc_ref, _)| { - // Compare Arc pointer equality using ptr_eq - Arc::ptr_eq(proc_ref, ln) - }); + // Group processors by unique instance (using Arc pointer equality) + let mut seen_processors = Vec::new(); + for (key, processor) in payment_processors { + // Skip if processor is already active + if processor.is_wait_invoice_active() { + continue; + } - if let Some((_, keys)) = found { - // We found this processor, add the key to its group - keys.push(key.clone()); - } else { - // New processor, create a new group - processor_groups.push((Arc::clone(ln), vec![key.clone()])); + // Skip if we've already spawned a task for this processor instance + if seen_processors.iter().any(|p| Arc::ptr_eq(p, processor)) { + continue; } + + seen_processors.push(Arc::clone(processor)); + + tracing::info!("Starting payment wait task for {:?}", key); + + // Clone for the spawned task + let processor = Arc::clone(processor); + let localstore = Arc::clone(&localstore); + let pubsub_manager = Arc::clone(&pubsub_manager); + let shutdown = Arc::clone(&shutdown); + + join_set.spawn(async move { + let result = Self::wait_for_processor_payments( + processor, + localstore, + pubsub_manager, + shutdown, + ) + .await; + + if let Err(e) = result { + tracing::error!("Payment processor task failed: {:?}", e); + } + }); } - for (ln, key) in processor_groups { - if !ln.is_wait_invoice_active() { - tracing::info!("Wait payment for {:?} inactive starting.", key); - let mint = Arc::clone(&mint_arc); - let ln = Arc::clone(&ln); - let shutdown = Arc::clone(&shutdown); - let key = key.clone(); - join_set.spawn(async move { - loop { - tracing::info!("Restarting wait for: {:?}", key); - tokio::select! { - _ = shutdown.notified() => { - tracing::info!("Shutdown signal received, stopping task for {:?}", key); - ln.cancel_wait_invoice(); - break; + // Wait for shutdown or all tasks to complete + loop { + tokio::select! { + _ = shutdown.notified() => { + tracing::info!("Shutting down payment processors"); + break; + } + Some(result) = join_set.join_next() => { + if let Err(e) = result { + tracing::warn!("Task panicked: {:?}", e); } - result = ln.wait_any_incoming_payment() => { - match result { - Ok(mut stream) => { - while let Some(request_lookup_id) = stream.next().await { - if let Err(err) = mint.pay_mint_quote_for_request_id(request_lookup_id).await { - tracing::warn!("{:?}", err); - } - } - } - Err(err) => { - tracing::warn!("Could not get incoming payment stream for {:?}: {}",key, err); + } + else => break, // All tasks completed + } + } + + join_set.shutdown().await; + Ok(()) + } - tokio::time::sleep(std::time::Duration::from_secs(5)).await; + /// Handles payment waiting for a single processor + async fn wait_for_processor_payments( + processor: Arc + Send + Sync>, + localstore: Arc + Send + Sync>, + pubsub_manager: Arc, + shutdown: Arc, + ) -> Result<(), Error> { + loop { + tokio::select! { + _ = shutdown.notified() => { + processor.cancel_wait_invoice(); + break; + } + result = processor.wait_any_incoming_payment() => { + match result { + Ok(mut stream) => { + while let Some(request_lookup_id) = stream.next().await { + if let Err(e) = Self::handle_payment_notification( + &localstore, + &pubsub_manager, + request_lookup_id, + ).await { + tracing::warn!("Payment notification error: {:?}", e); + } } } + Err(e) => { + tracing::warn!("Failed to get payment stream: {}", e); + tokio::time::sleep(Duration::from_secs(5)).await; + } } - } - } - }); + } } } + Ok(()) + } + + /// Handle payment notification without needing full Mint instance + /// This is a helper function that can be called with just the required components + async fn handle_payment_notification( + localstore: &Arc + Send + Sync>, + pubsub_manager: &Arc, + wait_payment_response: WaitPaymentResponse, + ) -> Result<(), Error> { + if wait_payment_response.payment_amount == Amount::ZERO { + tracing::warn!( + "Received payment response with 0 amount with payment id {}.", + wait_payment_response.payment_id + ); + return Err(Error::AmountUndefined); + } + + let mut tx = localstore.begin_transaction().await?; + + if let Ok(Some(mint_quote)) = tx + .get_mint_quote_by_request_lookup_id(&wait_payment_response.payment_identifier) + .await + { + Self::handle_mint_quote_payment( + &mut tx, + &mint_quote, + wait_payment_response, + pubsub_manager, + ) + .await?; + } else { + tracing::warn!( + "Could not get request for request lookup id {:?}.", + wait_payment_response.payment_identifier + ); + } + + tx.commit().await?; + Ok(()) + } + + /// Handle payment for a specific mint quote (extracted from pay_mint_quote) + async fn handle_mint_quote_payment( + tx: &mut Box + Send + Sync + '_>, + mint_quote: &MintQuote, + wait_payment_response: WaitPaymentResponse, + pubsub_manager: &Arc, + ) -> Result<(), Error> { + tracing::debug!( + "Received payment notification of {} for mint quote {} with payment id {}", + wait_payment_response.payment_amount, + mint_quote.id, + wait_payment_response.payment_id + ); + + let quote_state = mint_quote.state(); + if !mint_quote + .payment_ids() + .contains(&&wait_payment_response.payment_id) + { + if mint_quote.payment_method == PaymentMethod::Bolt11 + && (quote_state == MintQuoteState::Issued || quote_state == MintQuoteState::Paid) + { + tracing::info!("Received payment notification for already issued quote."); + } else { + tx.increment_mint_quote_amount_paid( + &mint_quote.id, + wait_payment_response.payment_amount, + wait_payment_response.payment_id, + ) + .await?; - // Spawn a task to manage the JoinSet - while let Some(result) = join_set.join_next().await { - match result { - Ok(_) => tracing::info!("A task completed successfully."), - Err(err) => tracing::warn!("A task failed: {:?}", err), + pubsub_manager.mint_quote_bolt11_status(mint_quote.clone(), MintQuoteState::Paid); } + } else { + tracing::info!("Received payment notification for already seen payment."); } Ok(()) @@ -713,4 +938,31 @@ mod tests { assert_eq!(expected_keys, serde_json::to_string(&keys.clone()).unwrap()); } + + #[tokio::test] + async fn test_start_stop_lifecycle() { + let mut supported_units = HashMap::new(); + supported_units.insert(CurrencyUnit::default(), (0, 32)); + let config = MintConfig::<'_> { + supported_units, + ..Default::default() + }; + let mint = create_mint(config).await; + + // Start should succeed (async) + mint.start().await.expect("Failed to start mint"); + + // Starting again should fail (already running) + assert!(mint.start().await.is_err()); + + // Stop should succeed (still async) + mint.stop().await.expect("Failed to stop mint"); + + // Stopping again should succeed (idempotent) + mint.stop().await.expect("Second stop should be fine"); + + // Should be able to start again after stopping + mint.start().await.expect("Should be able to restart"); + mint.stop().await.expect("Final stop should work"); + } } From d07388d1ce62bba84a6e7c280388c95ebbe84d84 Mon Sep 17 00:00:00 2001 From: lollerfirst <43107113+lollerfirst@users.noreply.github.com> Date: Wed, 23 Jul 2025 15:55:27 +0200 Subject: [PATCH 028/321] refactor Nut10SecretRequest and add tests with provided test vectors (#900) * refactor Nut10SecretRequest and add tests with provided test vectors --- crates/cashu/src/nuts/nut18/mod.rs | 2 +- .../cashu/src/nuts/nut18/payment_request.rs | 235 +++++++++++++++++- crates/cashu/src/nuts/nut18/secret.rs | 139 +++++------ 3 files changed, 292 insertions(+), 84 deletions(-) diff --git a/crates/cashu/src/nuts/nut18/mod.rs b/crates/cashu/src/nuts/nut18/mod.rs index a3e22db37..2e07a8e48 100644 --- a/crates/cashu/src/nuts/nut18/mod.rs +++ b/crates/cashu/src/nuts/nut18/mod.rs @@ -7,5 +7,5 @@ pub mod transport; pub use error::Error; pub use payment_request::{PaymentRequest, PaymentRequestBuilder, PaymentRequestPayload}; -pub use secret::{Nut10SecretRequest, SecretDataRequest}; +pub use secret::Nut10SecretRequest; pub use transport::{Transport, TransportBuilder, TransportType}; diff --git a/crates/cashu/src/nuts/nut18/payment_request.rs b/crates/cashu/src/nuts/nut18/payment_request.rs index 8c690efe8..8408a9527 100644 --- a/crates/cashu/src/nuts/nut18/payment_request.rs +++ b/crates/cashu/src/nuts/nut18/payment_request.rs @@ -43,6 +43,7 @@ pub struct PaymentRequest { #[serde(skip_serializing_if = "Option::is_none")] pub transports: Option>, /// Nut10 + #[serde(skip_serializing_if = "Option::is_none")] pub nut10: Option, } @@ -358,14 +359,8 @@ mod tests { // Check round-trip conversion assert_eq!(converted_back.kind, secret_request.kind); - assert_eq!( - converted_back.secret_data.data, - secret_request.secret_data.data - ); - assert_eq!( - converted_back.secret_data.tags, - secret_request.secret_data.tags - ); + assert_eq!(converted_back.data, secret_request.data); + assert_eq!(converted_back.tags, secret_request.tags); // Test in PaymentRequest builder let payment_request = PaymentRequest::builder() @@ -458,9 +453,231 @@ mod tests { // Verify the P2PK data was preserved correctly if let Some(nut10_secret) = decoded_request.nut10 { assert_eq!(nut10_secret.kind, Kind::P2PK); - assert_eq!(nut10_secret.secret_data.data, pubkey_hex); + assert_eq!(nut10_secret.data, pubkey_hex); } else { panic!("NUT10 secret data missing in decoded payment request"); } } + + /// Test vectors from NUT-18 specification + /// https://github.com/cashubtc/nuts/blob/main/tests/18-tests.md + + #[test] + fn test_basic_payment_request() { + // Basic payment request with required fields + let json = r#"{ + "i": "b7a90176", + "a": 10, + "u": "sat", + "m": ["https://8333.space:3338"], + "t": [ + { + "t": "nostr", + "a": "nprofile1qy28wumn8ghj7un9d3shjtnyv9kh2uewd9hsz9mhwden5te0wfjkccte9curxven9eehqctrv5hszrthwden5te0dehhxtnvdakqqgydaqy7curk439ykptkysv7udhdhu68sucm295akqefdehkf0d495cwunl5", + "g": [["n", "17"]] + } + ] + }"#; + + let expected_encoded = "creqApWF0gaNhdGVub3N0cmFheKlucHJvZmlsZTFxeTI4d3VtbjhnaGo3dW45ZDNzaGp0bnl2OWtoMnVld2Q5aHN6OW1od2RlbjV0ZTB3ZmprY2N0ZTljdXJ4dmVuOWVlaHFjdHJ2NWhzenJ0aHdkZW41dGUwZGVoaHh0bnZkYWtxcWd5ZGFxeTdjdXJrNDM5eWtwdGt5c3Y3dWRoZGh1NjhzdWNtMjk1YWtxZWZkZWhrZjBkNDk1Y3d1bmw1YWeBgmFuYjE3YWloYjdhOTAxNzZhYQphdWNzYXRhbYF3aHR0cHM6Ly84MzMzLnNwYWNlOjMzMzg="; + + // Parse the JSON into a PaymentRequest + let payment_request: PaymentRequest = serde_json::from_str(json).unwrap(); + let payment_request_cloned = payment_request.clone(); + + // Verify the payment request fields + assert_eq!( + payment_request_cloned.payment_id.as_ref().unwrap(), + "b7a90176" + ); + assert_eq!(payment_request_cloned.amount.unwrap(), Amount::from(10)); + assert_eq!(payment_request_cloned.unit.unwrap(), CurrencyUnit::Sat); + assert_eq!( + payment_request_cloned.mints.unwrap(), + vec![MintUrl::from_str("https://8333.space:3338").unwrap()] + ); + + let transport = payment_request.transports.as_ref().unwrap(); + let transport = transport.first().unwrap(); + assert_eq!(transport._type, TransportType::Nostr); + assert_eq!(transport.target, "nprofile1qy28wumn8ghj7un9d3shjtnyv9kh2uewd9hsz9mhwden5te0wfjkccte9curxven9eehqctrv5hszrthwden5te0dehhxtnvdakqqgydaqy7curk439ykptkysv7udhdhu68sucm295akqefdehkf0d495cwunl5"); + assert_eq!( + transport.tags, + Some(vec![vec!["n".to_string(), "17".to_string()]]) + ); + + // Test encoding - the encoded form should match the expected output + let encoded = payment_request.to_string(); + + // For now, let's verify it can be decoded back correctly + let decoded = PaymentRequest::from_str(&encoded).unwrap(); + assert_eq!(payment_request, decoded); + + // Test decoding the expected encoded string + let decoded_from_spec = PaymentRequest::from_str(expected_encoded).unwrap(); + assert_eq!(decoded_from_spec.payment_id.as_ref().unwrap(), "b7a90176"); + assert_eq!(decoded_from_spec.amount.unwrap(), Amount::from(10)); + assert_eq!(decoded_from_spec.unit.unwrap(), CurrencyUnit::Sat); + assert_eq!( + decoded_from_spec.mints.unwrap(), + vec![MintUrl::from_str("https://8333.space:3338").unwrap()] + ); + } + + #[test] + fn test_nostr_transport_payment_request() { + // Nostr transport payment request with multiple mints + let json = r#"{ + "i": "f92a51b8", + "a": 100, + "u": "sat", + "m": ["https://mint1.example.com", "https://mint2.example.com"], + "t": [ + { + "t": "nostr", + "a": "npub1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq28spj3", + "g": [["n", "17"], ["n", "9735"]] + } + ] + }"#; + + let expected_encoded = "creqApWF0gaNhdGVub3N0cmFheD9ucHViMXFxcXFxcXFxcXFxcXFxcXFxcXFxcXFxcXFxcXFxcXFxcXFxcXFxcXFxcXFxcXFxcXFxcXEyOHNwajNhZ4KCYW5iMTeCYW5kOTczNWFpaGY5MmE1MWI4YWEYZGF1Y3NhdGFtgngZaHR0cHM6Ly9taW50MS5leGFtcGxlLmNvbXgZaHR0cHM6Ly9taW50Mi5leGFtcGxlLmNvbQ=="; + + // Parse the JSON into a PaymentRequest + let payment_request: PaymentRequest = serde_json::from_str(json).unwrap(); + let payment_request_cloned = payment_request.clone(); + + // Verify the payment request fields + assert_eq!( + payment_request_cloned.payment_id.as_ref().unwrap(), + "f92a51b8" + ); + assert_eq!(payment_request_cloned.amount.unwrap(), Amount::from(100)); + assert_eq!(payment_request_cloned.unit.unwrap(), CurrencyUnit::Sat); + assert_eq!( + payment_request_cloned.mints.unwrap(), + vec![ + MintUrl::from_str("https://mint1.example.com").unwrap(), + MintUrl::from_str("https://mint2.example.com").unwrap() + ] + ); + + let transport = payment_request_cloned.transports.unwrap(); + let transport = transport.first().unwrap(); + assert_eq!(transport._type, TransportType::Nostr); + assert_eq!( + transport.target, + "npub1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq28spj3" + ); + assert_eq!( + transport.tags, + Some(vec![ + vec!["n".to_string(), "17".to_string()], + vec!["n".to_string(), "9735".to_string()] + ]) + ); + + // Test round-trip serialization + let encoded = payment_request.to_string(); + let decoded = PaymentRequest::from_str(&encoded).unwrap(); + assert_eq!(payment_request, decoded); + + // Test decoding the expected encoded string + let decoded_from_spec = PaymentRequest::from_str(expected_encoded).unwrap(); + assert_eq!(decoded_from_spec.payment_id.as_ref().unwrap(), "f92a51b8"); + } + + #[test] + fn test_minimal_payment_request() { + // Minimal payment request with only required fields + let json = r#"{ + "i": "7f4a2b39", + "u": "sat", + "m": ["https://mint.example.com"] + }"#; + + let expected_encoded = + "creqAo2FpaDdmNGEyYjM5YXVjc2F0YW2BeBhodHRwczovL21pbnQuZXhhbXBsZS5jb20="; + + // Parse the JSON into a PaymentRequest + let payment_request: PaymentRequest = serde_json::from_str(json).unwrap(); + let payment_request_cloned = payment_request.clone(); + + // Verify the payment request fields + assert_eq!( + payment_request_cloned.payment_id.as_ref().unwrap(), + "7f4a2b39" + ); + assert_eq!(payment_request_cloned.amount, None); + assert_eq!(payment_request_cloned.unit.unwrap(), CurrencyUnit::Sat); + assert_eq!( + payment_request_cloned.mints.unwrap(), + vec![MintUrl::from_str("https://mint.example.com").unwrap()] + ); + assert_eq!(payment_request_cloned.transports, None); + + // Test round-trip serialization + let encoded = payment_request.to_string(); + let decoded = PaymentRequest::from_str(&encoded).unwrap(); + assert_eq!(payment_request, decoded); + + // Test decoding the expected encoded string + let decoded_from_spec = PaymentRequest::from_str(expected_encoded).unwrap(); + assert_eq!(decoded_from_spec.payment_id.as_ref().unwrap(), "7f4a2b39"); + } + + #[test] + fn test_nut10_locking_payment_request() { + // Payment request with NUT-10 P2PK locking + let json = r#"{ + "i": "c9e45d2a", + "a": 500, + "u": "sat", + "m": ["https://mint.example.com"], + "nut10": { + "k": "P2PK", + "d": "02c3b5bb27e361457c92d93d78dd73d3d53732110b2cfe8b50fbc0abc615e9c331", + "t": [["timeout", "3600"]] + } + }"#; + + let expected_encoded = "creqApWFpaGM5ZTQ1ZDJhYWEZAfRhdWNzYXRhbYF4GGh0dHBzOi8vbWludC5leGFtcGxlLmNvbWVudXQxMKNha2RQMlBLYWR4QjAyYzNiNWJiMjdlMzYxNDU3YzkyZDkzZDc4ZGQ3M2QzZDUzNzMyMTEwYjJjZmU4YjUwZmJjMGFiYzYxNWU5YzMzMWF0gYJndGltZW91dGQzNjAw"; + + // Parse the JSON into a PaymentRequest + let payment_request: PaymentRequest = serde_json::from_str(json).unwrap(); + let payment_request_cloned = payment_request.clone(); + + // Verify the payment request fields + assert_eq!( + payment_request_cloned.payment_id.as_ref().unwrap(), + "c9e45d2a" + ); + assert_eq!(payment_request_cloned.amount.unwrap(), Amount::from(500)); + assert_eq!(payment_request_cloned.unit.unwrap(), CurrencyUnit::Sat); + assert_eq!( + payment_request_cloned.mints.unwrap(), + vec![MintUrl::from_str("https://mint.example.com").unwrap()] + ); + + // Test NUT-10 locking + let nut10 = payment_request_cloned.nut10.unwrap(); + assert_eq!(nut10.kind, Kind::P2PK); + assert_eq!( + nut10.data, + "02c3b5bb27e361457c92d93d78dd73d3d53732110b2cfe8b50fbc0abc615e9c331" + ); + assert_eq!( + nut10.tags, + Some(vec![vec!["timeout".to_string(), "3600".to_string()]]) + ); + + // Test round-trip serialization + let encoded = payment_request.to_string(); + let decoded = PaymentRequest::from_str(&encoded).unwrap(); + assert_eq!(payment_request, decoded); + + // Test decoding the expected encoded string + let decoded_from_spec = PaymentRequest::from_str(expected_encoded).unwrap(); + assert_eq!(decoded_from_spec.payment_id.as_ref().unwrap(), "c9e45d2a"); + } } diff --git a/crates/cashu/src/nuts/nut18/secret.rs b/crates/cashu/src/nuts/nut18/secret.rs index 24b16f161..c3fc1c2f5 100644 --- a/crates/cashu/src/nuts/nut18/secret.rs +++ b/crates/cashu/src/nuts/nut18/secret.rs @@ -1,31 +1,21 @@ //! Secret types for NUT-18: Payment Requests - -use std::fmt; - -use serde::de::{self, Deserializer, SeqAccess, Visitor}; -use serde::ser::{SerializeTuple, Serializer}; use serde::{Deserialize, Serialize}; use crate::nuts::nut10::Kind; use crate::nuts::{Nut10Secret, SpendingConditions}; -/// Secret Data without nonce for payment requests -#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)] -pub struct SecretDataRequest { - /// Expresses the spending condition specific to each kind - pub data: String, - /// Additional data committed to and can be used for feature extensions - #[serde(skip_serializing_if = "Option::is_none")] - pub tags: Option>>, -} - /// Nut10Secret without nonce for payment requests -#[derive(Debug, Clone, Hash, PartialEq, Eq)] +#[derive(Debug, Clone, Hash, PartialEq, Eq, Serialize, Deserialize)] pub struct Nut10SecretRequest { /// Kind of the spending condition + #[serde(rename = "k")] pub kind: Kind, - /// Secret Data without nonce - pub secret_data: SecretDataRequest, + /// Secret data + #[serde(rename = "d")] + pub data: String, + /// Additional data committed to and can be used for feature extensions + #[serde(rename = "t", skip_serializing_if = "Option::is_none")] + pub tags: Option>>, } impl Nut10SecretRequest { @@ -35,32 +25,27 @@ impl Nut10SecretRequest { S: Into, V: Into>>, { - let secret_data = SecretDataRequest { + Self { + kind, data: data.into(), tags: tags.map(|v| v.into()), - }; - - Self { kind, secret_data } + } } } impl From for Nut10SecretRequest { fn from(secret: Nut10Secret) -> Self { - let secret_data = SecretDataRequest { - data: secret.secret_data().data().to_string(), - tags: secret.secret_data().tags().cloned(), - }; - Self { kind: secret.kind(), - secret_data, + data: secret.secret_data().data().to_string(), + tags: secret.secret_data().tags().cloned(), } } } impl From for Nut10Secret { fn from(value: Nut10SecretRequest) -> Self { - Self::new(value.kind, value.secret_data.data, value.secret_data.tags) + Self::new(value.kind, value.data, value.tags) } } @@ -77,61 +62,67 @@ impl From for Nut10SecretRequest { } } -impl Serialize for Nut10SecretRequest { - fn serialize(&self, serializer: S) -> Result - where - S: Serializer, - { - // Create a tuple representing the struct fields - let secret_tuple = (&self.kind, &self.secret_data); +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn test_nut10_secret_request_serialization() { + let request = Nut10SecretRequest::new( + Kind::P2PK, + "026562efcfadc8e86d44da6a8adf80633d974302e62c850774db1fb36ff4cc7198", + Some(vec![vec!["key".to_string(), "value".to_string()]]), + ); - // Serialize the tuple as a JSON array - let mut s = serializer.serialize_tuple(2)?; + let json = serde_json::to_string(&request).unwrap(); - s.serialize_element(&secret_tuple.0)?; - s.serialize_element(&secret_tuple.1)?; - s.end() + // Verify json has abbreviated field names + assert!(json.contains(r#""k":"P2PK""#)); + assert!(json.contains(r#""d":"026562"#)); + assert!(json.contains(r#""t":[["key","#)); } -} -// Custom visitor for deserializing Secret -struct SecretVisitor; + #[test] + fn test_roundtrip_serialization() { + let original = Nut10SecretRequest { + kind: Kind::P2PK, + data: "test_data".into(), + tags: Some(vec![vec!["key".to_string(), "value".to_string()]]), + }; -impl<'de> Visitor<'de> for SecretVisitor { - type Value = Nut10SecretRequest; + let json = serde_json::to_string(&original).unwrap(); + let decoded: Nut10SecretRequest = serde_json::from_str(&json).unwrap(); - fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result { - formatter.write_str("a tuple with two elements: [Kind, SecretData]") + assert_eq!(original, decoded); } - fn visit_seq(self, mut seq: A) -> Result - where - A: SeqAccess<'de>, - { - // Deserialize the kind (first element) - let kind = seq - .next_element()? - .ok_or_else(|| de::Error::invalid_length(0, &self))?; - - // Deserialize the secret_data (second element) - let secret_data = seq - .next_element()? - .ok_or_else(|| de::Error::invalid_length(1, &self))?; - - // Make sure there are no additional elements - if seq.next_element::()?.is_some() { - return Err(de::Error::invalid_length(3, &self)); - } + #[test] + fn test_from_nut10_secret() { + let secret = Nut10Secret::new( + Kind::P2PK, + "test_data", + Some(vec![vec!["key".to_string(), "value".to_string()]]), + ); + + let request: Nut10SecretRequest = secret.clone().into(); - Ok(Nut10SecretRequest { kind, secret_data }) + assert_eq!(request.kind, secret.kind()); + assert_eq!(request.data, secret.secret_data().data()); + assert_eq!(request.tags, secret.secret_data().tags().cloned()); } -} -impl<'de> Deserialize<'de> for Nut10SecretRequest { - fn deserialize(deserializer: D) -> Result - where - D: Deserializer<'de>, - { - deserializer.deserialize_seq(SecretVisitor) + #[test] + fn test_into_nut10_secret() { + let request = Nut10SecretRequest { + kind: Kind::HTLC, + data: "test_hash".into(), + tags: None, + }; + + let secret: Nut10Secret = request.clone().into(); + + assert_eq!(secret.kind(), request.kind); + assert_eq!(secret.secret_data().data(), request.data); + assert_eq!(secret.secret_data().tags(), request.tags.as_ref()); } } From af2762e5eff6f929d224c7aa13dc23578f34518a Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Wed, 23 Jul 2025 15:58:47 +0100 Subject: [PATCH 029/321] fix: waiting start stop tests --- crates/cdk/src/mint/mod.rs | 35 ++++++++++++++++++++++------------- 1 file changed, 22 insertions(+), 13 deletions(-) diff --git a/crates/cdk/src/mint/mod.rs b/crates/cdk/src/mint/mod.rs index b29d220b9..0221ba82f 100644 --- a/crates/cdk/src/mint/mod.rs +++ b/crates/cdk/src/mint/mod.rs @@ -237,6 +237,9 @@ impl Mint { task_state.shutdown_notify = Some(shutdown_notify); task_state.supervisor_handle = Some(supervisor_handle); + // Give the background task a tiny bit of time to start waiting + tokio::time::sleep(std::time::Duration::from_millis(10)).await; + tracing::info!("Mint background services started"); Ok(()) } @@ -430,19 +433,24 @@ impl Mint { }); } - // Wait for shutdown or all tasks to complete - loop { - tokio::select! { - _ = shutdown.notified() => { - tracing::info!("Shutting down payment processors"); - break; - } - Some(result) = join_set.join_next() => { - if let Err(e) = result { - tracing::warn!("Task panicked: {:?}", e); + // If no payment processors, just wait for shutdown + if join_set.is_empty() { + shutdown.notified().await; + } else { + // Wait for shutdown or all tasks to complete + loop { + tokio::select! { + _ = shutdown.notified() => { + println!("Shutting down payment processors"); + break; + } + Some(result) = join_set.join_next() => { + if let Err(e) = result { + tracing::warn!("Task panicked: {:?}", e); + } } + else => break, // All tasks completed } - else => break, // All tasks completed } } @@ -782,11 +790,11 @@ impl Mint { /// Total redeemed for keyset #[instrument(skip_all)] pub async fn total_redeemed(&self) -> Result, Error> { - let keysets = self.keysets().keysets; + let keysets = self.signatory.keysets().await?; let mut total_redeemed = HashMap::new(); - for keyset in keysets { + for keyset in keysets.keysets { let (proofs, state) = self.localstore.get_proofs_by_keyset_id(&keyset.id).await?; let total_spent = @@ -806,6 +814,7 @@ impl Mint { #[cfg(test)] mod tests { + use std::str::FromStr; use cdk_sqlite::mint::memory::new_with_state; From d2e9f1a626b15e74e6b57562885161eb561f0da0 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Wed, 23 Jul 2025 20:49:42 +0100 Subject: [PATCH 030/321] Merge pull request #901 from thesimplekid/refresh_keys feat: refactor wallet keyset management for better clarity --- crates/cashu/src/nuts/nut02.rs | 22 +++ .../cdk-cli/src/sub_commands/pay_request.rs | 2 +- crates/cdk-integration-tests/tests/bolt12.rs | 2 +- .../tests/fake_wallet.rs | 30 ++-- .../tests/happy_path_mint_wallet.rs | 2 +- crates/cdk-integration-tests/tests/regtest.rs | 2 +- crates/cdk/examples/proof-selection.rs | 5 +- crates/cdk/src/wallet/auth/auth_wallet.rs | 114 +++++++------ crates/cdk/src/wallet/issue/issue_bolt11.rs | 6 +- crates/cdk/src/wallet/issue/issue_bolt12.rs | 6 +- crates/cdk/src/wallet/keysets.rs | 152 ++++++++++-------- crates/cdk/src/wallet/melt/melt_bolt11.rs | 4 +- crates/cdk/src/wallet/mod.rs | 6 +- crates/cdk/src/wallet/multi_mint_wallet.rs | 2 +- crates/cdk/src/wallet/receive.rs | 8 +- crates/cdk/src/wallet/send.rs | 17 +- crates/cdk/src/wallet/swap.rs | 8 +- 17 files changed, 231 insertions(+), 157 deletions(-) diff --git a/crates/cashu/src/nuts/nut02.rs b/crates/cashu/src/nuts/nut02.rs index bfb3f07e2..84e0859a6 100644 --- a/crates/cashu/src/nuts/nut02.rs +++ b/crates/cashu/src/nuts/nut02.rs @@ -497,6 +497,28 @@ pub struct KeySetInfo { pub final_expiry: Option, } +/// List of [KeySetInfo] +pub type KeySetInfos = Vec; + +/// Utility methods for [KeySetInfos] +pub trait KeySetInfosMethods { + /// Filter for active keysets + fn active(&self) -> impl Iterator + '_; + + /// Filter keysets for specific unit + fn unit(&self, unit: CurrencyUnit) -> impl Iterator + '_; +} + +impl KeySetInfosMethods for KeySetInfos { + fn active(&self) -> impl Iterator + '_ { + self.iter().filter(|k| k.active) + } + + fn unit(&self, unit: CurrencyUnit) -> impl Iterator + '_ { + self.iter().filter(move |k| k.unit == unit) + } +} + fn deserialize_input_fee_ppk<'de, D>(deserializer: D) -> Result where D: Deserializer<'de>, diff --git a/crates/cdk-cli/src/sub_commands/pay_request.rs b/crates/cdk-cli/src/sub_commands/pay_request.rs index 0da976094..dc4bddec4 100644 --- a/crates/cdk-cli/src/sub_commands/pay_request.rs +++ b/crates/cdk-cli/src/sub_commands/pay_request.rs @@ -101,7 +101,7 @@ pub async fn pay_request( .await? { Some(keysets_info) => keysets_info, - None => matching_wallet.get_mint_keysets().await?, // Hit the keysets endpoint if we don't have the keysets for this Mint + None => matching_wallet.load_mint_keysets().await?, // Hit the keysets endpoint if we don't have the keysets for this Mint }; let proofs = token.proofs(&keysets_info)?; diff --git a/crates/cdk-integration-tests/tests/bolt12.rs b/crates/cdk-integration-tests/tests/bolt12.rs index 5a265c899..fc2798854 100644 --- a/crates/cdk-integration-tests/tests/bolt12.rs +++ b/crates/cdk-integration-tests/tests/bolt12.rs @@ -277,7 +277,7 @@ async fn test_regtest_bolt12_mint_extra() -> Result<()> { assert_eq!(state.amount_paid, Amount::ZERO); assert_eq!(state.amount_issued, Amount::ZERO); - let active_keyset_id = wallet.get_active_mint_keyset().await?.id; + let active_keyset_id = wallet.fetch_active_keyset().await?.id; let pay_amount_msats = 10_000; diff --git a/crates/cdk-integration-tests/tests/fake_wallet.rs b/crates/cdk-integration-tests/tests/fake_wallet.rs index e2de57c41..a48434630 100644 --- a/crates/cdk-integration-tests/tests/fake_wallet.rs +++ b/crates/cdk-integration-tests/tests/fake_wallet.rs @@ -381,7 +381,7 @@ async fn test_fake_melt_change_in_quote() { let melt_quote = wallet.melt_quote(invoice.to_string(), None).await.unwrap(); - let keyset = wallet.get_active_mint_keyset().await.unwrap(); + let keyset = wallet.fetch_active_keyset().await.unwrap(); let premint_secrets = PreMintSecrets::random(keyset.id, 100.into(), &SplitTarget::default()).unwrap(); @@ -489,7 +489,7 @@ async fn test_fake_mint_without_witness() { let http_client = HttpClient::new(MINT_URL.parse().unwrap(), None); - let active_keyset_id = wallet.get_active_mint_keyset().await.unwrap().id; + let active_keyset_id = wallet.fetch_active_keyset().await.unwrap().id; let premint_secrets = PreMintSecrets::random(active_keyset_id, 100.into(), &SplitTarget::default()).unwrap(); @@ -529,7 +529,7 @@ async fn test_fake_mint_with_wrong_witness() { let http_client = HttpClient::new(MINT_URL.parse().unwrap(), None); - let active_keyset_id = wallet.get_active_mint_keyset().await.unwrap().id; + let active_keyset_id = wallet.fetch_active_keyset().await.unwrap().id; let premint_secrets = PreMintSecrets::random(active_keyset_id, 100.into(), &SplitTarget::default()).unwrap(); @@ -573,7 +573,7 @@ async fn test_fake_mint_inflated() { .await .unwrap(); - let active_keyset_id = wallet.get_active_mint_keyset().await.unwrap().id; + let active_keyset_id = wallet.fetch_active_keyset().await.unwrap().id; let pre_mint = PreMintSecrets::random(active_keyset_id, 500.into(), &SplitTarget::None).unwrap(); @@ -631,7 +631,7 @@ async fn test_fake_mint_multiple_units() { .await .unwrap(); - let active_keyset_id = wallet.get_active_mint_keyset().await.unwrap().id; + let active_keyset_id = wallet.fetch_active_keyset().await.unwrap().id; let pre_mint = PreMintSecrets::random(active_keyset_id, 50.into(), &SplitTarget::None).unwrap(); @@ -644,7 +644,7 @@ async fn test_fake_mint_multiple_units() { ) .expect("failed to create new wallet"); - let active_keyset_id = wallet_usd.get_active_mint_keyset().await.unwrap().id; + let active_keyset_id = wallet_usd.fetch_active_keyset().await.unwrap().id; let usd_pre_mint = PreMintSecrets::random(active_keyset_id, 50.into(), &SplitTarget::None).unwrap(); @@ -733,7 +733,7 @@ async fn test_fake_mint_multiple_unit_swap() { .await .unwrap(); - let active_keyset_id = wallet.get_active_mint_keyset().await.unwrap().id; + let active_keyset_id = wallet.fetch_active_keyset().await.unwrap().id; { let inputs: Proofs = vec![ @@ -767,7 +767,7 @@ async fn test_fake_mint_multiple_unit_swap() { } { - let usd_active_keyset_id = wallet_usd.get_active_mint_keyset().await.unwrap().id; + let usd_active_keyset_id = wallet_usd.fetch_active_keyset().await.unwrap().id; let inputs: Proofs = proofs.into_iter().take(2).collect(); let total_inputs = inputs.total_amount().unwrap(); @@ -883,8 +883,8 @@ async fn test_fake_mint_multiple_unit_melt() { let input_amount: u64 = inputs.total_amount().unwrap().into(); let invoice = create_fake_invoice((input_amount - 1) * 1000, "".to_string()); - let active_keyset_id = wallet.get_active_mint_keyset().await.unwrap().id; - let usd_active_keyset_id = wallet_usd.get_active_mint_keyset().await.unwrap().id; + let active_keyset_id = wallet.fetch_active_keyset().await.unwrap().id; + let usd_active_keyset_id = wallet_usd.fetch_active_keyset().await.unwrap().id; let usd_pre_mint = PreMintSecrets::random( usd_active_keyset_id, @@ -952,7 +952,7 @@ async fn test_fake_mint_input_output_mismatch() { None, ) .expect("failed to create new usd wallet"); - let usd_active_keyset_id = wallet_usd.get_active_mint_keyset().await.unwrap().id; + let usd_active_keyset_id = wallet_usd.fetch_active_keyset().await.unwrap().id; let inputs = proofs; @@ -1001,7 +1001,7 @@ async fn test_fake_mint_swap_inflated() { .mint(&mint_quote.id, SplitTarget::None, None) .await .unwrap(); - let active_keyset_id = wallet.get_active_mint_keyset().await.unwrap().id; + let active_keyset_id = wallet.fetch_active_keyset().await.unwrap().id; let pre_mint = PreMintSecrets::random(active_keyset_id, 101.into(), &SplitTarget::None).unwrap(); @@ -1045,7 +1045,7 @@ async fn test_fake_mint_swap_spend_after_fail() { .mint(&mint_quote.id, SplitTarget::None, None) .await .unwrap(); - let active_keyset_id = wallet.get_active_mint_keyset().await.unwrap().id; + let active_keyset_id = wallet.fetch_active_keyset().await.unwrap().id; let pre_mint = PreMintSecrets::random(active_keyset_id, 100.into(), &SplitTarget::None).unwrap(); @@ -1116,7 +1116,7 @@ async fn test_fake_mint_melt_spend_after_fail() { .mint(&mint_quote.id, SplitTarget::None, None) .await .unwrap(); - let active_keyset_id = wallet.get_active_mint_keyset().await.unwrap().id; + let active_keyset_id = wallet.fetch_active_keyset().await.unwrap().id; let pre_mint = PreMintSecrets::random(active_keyset_id, 100.into(), &SplitTarget::None).unwrap(); @@ -1189,7 +1189,7 @@ async fn test_fake_mint_duplicate_proofs_swap() { .await .unwrap(); - let active_keyset_id = wallet.get_active_mint_keyset().await.unwrap().id; + let active_keyset_id = wallet.fetch_active_keyset().await.unwrap().id; let inputs = vec![proofs[0].clone(), proofs[0].clone()]; diff --git a/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs b/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs index e93111965..5d42aff7b 100644 --- a/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs +++ b/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs @@ -358,7 +358,7 @@ async fn test_fake_melt_change_in_quote() { let melt_quote = wallet.melt_quote(invoice.to_string(), None).await.unwrap(); - let keyset = wallet.get_active_mint_keyset().await.unwrap(); + let keyset = wallet.fetch_active_keyset().await.unwrap(); let premint_secrets = PreMintSecrets::random(keyset.id, 100.into(), &SplitTarget::default()).unwrap(); diff --git a/crates/cdk-integration-tests/tests/regtest.rs b/crates/cdk-integration-tests/tests/regtest.rs index f73d432b6..df80f1559 100644 --- a/crates/cdk-integration-tests/tests/regtest.rs +++ b/crates/cdk-integration-tests/tests/regtest.rs @@ -308,7 +308,7 @@ async fn test_cached_mint() { .await .unwrap(); - let active_keyset_id = wallet.get_active_mint_keyset().await.unwrap().id; + let active_keyset_id = wallet.fetch_active_keyset().await.unwrap().id; let http_client = HttpClient::new(get_mint_url_from_env().parse().unwrap(), None); let premint_secrets = PreMintSecrets::random(active_keyset_id, 100.into(), &SplitTarget::default()).unwrap(); diff --git a/crates/cdk/examples/proof-selection.rs b/crates/cdk/examples/proof-selection.rs index 1532de613..d7060cf14 100644 --- a/crates/cdk/examples/proof-selection.rs +++ b/crates/cdk/examples/proof-selection.rs @@ -8,6 +8,7 @@ use cdk::nuts::nut00::ProofsMethods; use cdk::nuts::{CurrencyUnit, MintQuoteState, NotificationPayload}; use cdk::wallet::{Wallet, WalletSubscription}; use cdk::Amount; +use cdk_common::nut02::KeySetInfosMethods; use cdk_sqlite::wallet::memory; use rand::random; @@ -62,9 +63,9 @@ async fn main() -> Result<(), Box> { // Select proofs to send let amount = Amount::from(64); let active_keyset_ids = wallet - .get_active_mint_keysets() + .refresh_keysets() .await? - .into_iter() + .active() .map(|keyset| keyset.id) .collect(); let selected = diff --git a/crates/cdk/src/wallet/auth/auth_wallet.rs b/crates/cdk/src/wallet/auth/auth_wallet.rs index fa6718eaa..5be0df2ec 100644 --- a/crates/cdk/src/wallet/auth/auth_wallet.rs +++ b/crates/cdk/src/wallet/auth/auth_wallet.rs @@ -3,6 +3,7 @@ use std::sync::Arc; use cdk_common::database::{self, WalletDatabase}; use cdk_common::mint_url::MintUrl; +use cdk_common::nut02::KeySetInfosMethods; use cdk_common::{AuthProof, Id, Keys, MintInfo}; use serde::{Deserialize, Serialize}; use tokio::sync::RwLock; @@ -167,12 +168,12 @@ impl AuthWallet { self.client.get_mint_info().await.map(Some).or(Ok(None)) } - /// Get keys for mint keyset + /// Fetch keys for mint keyset /// - /// Selected keys from localstore if they are already known - /// If they are not known queries mint for keyset id and stores the [`Keys`] + /// Returns keys from local database if they are already stored. + /// If keys are not found locally, goes online to query the mint for the keyset and stores the [`Keys`] in local database. #[instrument(skip(self))] - pub async fn get_keyset_keys(&self, keyset_id: Id) -> Result { + pub async fn load_keyset_keys(&self, keyset_id: Id) -> Result { let keys = if let Some(keys) = self.localstore.get_keys(&keyset_id).await? { keys } else { @@ -188,62 +189,88 @@ impl AuthWallet { Ok(keys) } - /// Get active keyset for mint + /// Get blind auth keysets from local database or go online if missing /// - /// Queries mint for current keysets then gets [`Keys`] for any unknown - /// keysets + /// First checks the local database for cached blind auth keysets. If keysets are not found locally, + /// goes online to refresh keysets from the mint and updates the local database. + /// This is the main method for getting auth keysets in operations that can work offline + /// but will fall back to online if needed. #[instrument(skip(self))] - pub async fn get_active_mint_blind_auth_keysets(&self) -> Result, Error> { - let keysets = self.client.get_mint_blind_auth_keysets().await?; - let keysets = keysets.keysets; + pub async fn load_mint_keysets(&self) -> Result, Error> { + match self + .localstore + .get_mint_keysets(self.mint_url.clone()) + .await? + { + Some(keysets_info) => { + let auth_keysets: Vec = + keysets_info.unit(CurrencyUnit::Sat).cloned().collect(); + if auth_keysets.is_empty() { + // If we don't have any auth keysets, fetch them from the mint + let keysets = self.refresh_keysets().await?; + Ok(keysets) + } else { + Ok(auth_keysets) + } + } + None => { + // If we don't have any keysets, fetch them from the mint + let keysets = self.refresh_keysets().await?; + Ok(keysets) + } + } + } + + /// Refresh blind auth keysets by fetching the latest from mint - always goes online + /// + /// This method always goes online to fetch the latest blind auth keyset information from the mint. + /// It updates the local database with the fetched keysets and ensures we have keys for all keysets. + /// Returns only the keysets with Auth currency unit. This is used when operations need the most + /// up-to-date keyset information and are willing to go online. + #[instrument(skip(self))] + pub async fn refresh_keysets(&self) -> Result, Error> { + let keysets_response = self.client.get_mint_blind_auth_keysets().await?; + let keysets = keysets_response.keysets; + // Update local store with keysets self.localstore .add_mint_keysets(self.mint_url.clone(), keysets.clone()) .await?; - let active_keysets = keysets + // Filter for auth keysets + let auth_keysets = keysets .clone() .into_iter() .filter(|k| k.unit == CurrencyUnit::Auth) .collect::>(); - match self - .localstore - .get_mint_keysets(self.mint_url.clone()) - .await? - { - Some(known_keysets) => { - let unknown_keysets: Vec<&KeySetInfo> = keysets - .iter() - .filter(|k| known_keysets.contains(k)) - .collect(); - - for keyset in unknown_keysets { - self.get_keyset_keys(keyset.id).await?; - } - } - None => { - for keyset in keysets { - self.get_keyset_keys(keyset.id).await?; - } + // Ensure we have keys for all auth keysets + for keyset in &auth_keysets { + if self.localstore.get_keys(&keyset.id).await?.is_none() { + tracing::debug!("Fetching missing keys for auth keyset {}", keyset.id); + self.load_keyset_keys(keyset.id).await?; } } - Ok(active_keysets) + + Ok(auth_keysets) } - /// Get active keyset for mint + /// Get the first active blind auth keyset - always goes online /// - /// Queries mint for current keysets then gets [`Keys`] for any unknown - /// keysets + /// This method always goes online to refresh keysets from the mint and then returns + /// the first active keyset found. Use this when you need the most up-to-date + /// keyset information for blind auth operations. #[instrument(skip(self))] - pub async fn get_active_mint_blind_auth_keyset(&self) -> Result { - let active_keysets = self.get_active_mint_blind_auth_keysets().await?; - - let keyset = active_keysets.first().ok_or(Error::NoActiveKeyset)?; + pub async fn fetch_active_keyset(&self) -> Result { + let auth_keysets = self.refresh_keysets().await?; + let keyset = auth_keysets.first().ok_or(Error::NoActiveKeyset)?; Ok(keyset.clone()) } - /// Get unspent proofs for mint + /// Get unspent auth proofs from local database only - offline operation + /// + /// Returns auth proofs from the local database that are in the Unspent state. + /// This is an offline operation that does not contact the mint. #[instrument(skip(self))] pub async fn get_unspent_auth_proofs(&self) -> Result, Error> { Ok(self @@ -334,9 +361,6 @@ impl AuthWallet { let auth_token = self.client.get_auth_token().await?; - let active_keyset_id = self.get_active_mint_blind_auth_keysets().await?; - tracing::debug!("Active ketset: {:?}", active_keyset_id); - match &auth_token { AuthToken::ClearAuth(cat) => { if cat.is_empty() { @@ -369,7 +393,7 @@ impl AuthWallet { } } - let active_keyset_id = self.get_active_mint_blind_auth_keyset().await?.id; + let active_keyset_id = self.fetch_active_keyset().await?.id; let premint_secrets = PreMintSecrets::random(active_keyset_id, amount, &SplitTarget::Value(1.into()))?; @@ -380,13 +404,13 @@ impl AuthWallet { let mint_res = self.client.post_mint_blind_auth(request).await?; - let keys = self.get_keyset_keys(active_keyset_id).await?; + let keys = self.load_keyset_keys(active_keyset_id).await?; // Verify the signature DLEQ is valid { assert!(mint_res.signatures.len() == premint_secrets.secrets.len()); for (sig, premint) in mint_res.signatures.iter().zip(&premint_secrets.secrets) { - let keys = self.get_keyset_keys(sig.keyset_id).await?; + let keys = self.load_keyset_keys(sig.keyset_id).await?; let key = keys.amount_key(sig.amount).ok_or(Error::AmountKey)?; match sig.verify_dleq(key, premint.blinded_message.blinded_secret) { Ok(_) => (), diff --git a/crates/cdk/src/wallet/issue/issue_bolt11.rs b/crates/cdk/src/wallet/issue/issue_bolt11.rs index c63168044..f33b03907 100644 --- a/crates/cdk/src/wallet/issue/issue_bolt11.rs +++ b/crates/cdk/src/wallet/issue/issue_bolt11.rs @@ -227,7 +227,7 @@ impl Wallet { tracing::warn!("Attempting to mint with expired quote."); } - let active_keyset_id = self.get_active_mint_keyset().await?.id; + let active_keyset_id = self.fetch_active_keyset().await?.id; let count = self .localstore @@ -264,12 +264,12 @@ impl Wallet { let mint_res = self.client.post_mint(request).await?; - let keys = self.get_keyset_keys(active_keyset_id).await?; + let keys = self.fetch_keyset_keys(active_keyset_id).await?; // Verify the signature DLEQ is valid { for (sig, premint) in mint_res.signatures.iter().zip(&premint_secrets.secrets) { - let keys = self.get_keyset_keys(sig.keyset_id).await?; + let keys = self.fetch_keyset_keys(sig.keyset_id).await?; let key = keys.amount_key(sig.amount).ok_or(Error::AmountKey)?; match sig.verify_dleq(key, premint.blinded_message.blinded_secret) { Ok(_) | Err(nut12::Error::MissingDleqProof) => (), diff --git a/crates/cdk/src/wallet/issue/issue_bolt12.rs b/crates/cdk/src/wallet/issue/issue_bolt12.rs index 9fb591a85..7d5c5c3ac 100644 --- a/crates/cdk/src/wallet/issue/issue_bolt12.rs +++ b/crates/cdk/src/wallet/issue/issue_bolt12.rs @@ -105,7 +105,7 @@ impl Wallet { return Err(Error::UnknownQuote); }; - let active_keyset_id = self.get_active_mint_keyset().await?.id; + let active_keyset_id = self.fetch_active_keyset().await?.id; let count = self .localstore @@ -161,12 +161,12 @@ impl Wallet { let mint_res = self.client.post_mint(request).await?; - let keys = self.get_keyset_keys(active_keyset_id).await?; + let keys = self.fetch_keyset_keys(active_keyset_id).await?; // Verify the signature DLEQ is valid { for (sig, premint) in mint_res.signatures.iter().zip(&premint_secrets.secrets) { - let keys = self.get_keyset_keys(sig.keyset_id).await?; + let keys = self.fetch_keyset_keys(sig.keyset_id).await?; let key = keys.amount_key(sig.amount).ok_or(Error::AmountKey)?; match sig.verify_dleq(key, premint.blinded_message.blinded_secret) { Ok(_) | Err(nut12::Error::MissingDleqProof) => (), diff --git a/crates/cdk/src/wallet/keysets.rs b/crates/cdk/src/wallet/keysets.rs index 095201944..0d40818ba 100644 --- a/crates/cdk/src/wallet/keysets.rs +++ b/crates/cdk/src/wallet/keysets.rs @@ -1,17 +1,18 @@ use std::collections::HashMap; +use cdk_common::nut02::{KeySetInfos, KeySetInfosMethods}; use tracing::instrument; use crate::nuts::{Id, KeySetInfo, Keys}; use crate::{Error, Wallet}; impl Wallet { - /// Get keys for mint keyset + /// Fetch keys for mint keyset /// - /// Selected keys from localstore if they are already known - /// If they are not known queries mint for keyset id and stores the [`Keys`] + /// Returns keys from local database if they are already stored. + /// If keys are not found locally, goes online to query the mint for the keyset and stores the [`Keys`] in local database. #[instrument(skip(self))] - pub async fn get_keyset_keys(&self, keyset_id: Id) -> Result { + pub async fn fetch_keyset_keys(&self, keyset_id: Id) -> Result { let keys = if let Some(keys) = self.localstore.get_keys(&keyset_id).await? { keys } else { @@ -27,10 +28,12 @@ impl Wallet { Ok(keys) } - /// Get keysets from DB or fetch them + /// Get keysets from local database or go online if missing /// - /// Checks the database for keysets and queries the Mint if - /// it can't find any. + /// First checks the local database for cached keysets. If keysets are not found locally, + /// goes online to refresh keysets from the mint and updates the local database. + /// This is the main method for getting keysets in token operations that can work offline + /// but will fall back to online if needed. #[instrument(skip(self))] pub async fn load_mint_keysets(&self) -> Result, Error> { match self @@ -39,86 +42,105 @@ impl Wallet { .await? { Some(keysets_info) => Ok(keysets_info), - None => self.get_mint_keysets().await, // Hit the keysets endpoint if we don't have the keysets for this Mint + None => { + // If we don't have any keysets, fetch them from the mint + let keysets = self.refresh_keysets().await?; + Ok(keysets) + } } } - /// Get keysets for wallet's mint + /// Get keysets from local database only - pure offline operation /// - /// Queries mint for all keysets + /// Only checks the local database for cached keysets. If keysets are not found locally, + /// returns an error without going online. This is used for operations that must remain + /// offline and rely on previously cached keyset data. #[instrument(skip(self))] pub async fn get_mint_keysets(&self) -> Result, Error> { - let keysets = self.client.get_mint_keysets().await?; - - self.localstore - .add_mint_keysets(self.mint_url.clone(), keysets.keysets.clone()) - .await?; - - Ok(keysets.keysets) + match self + .localstore + .get_mint_keysets(self.mint_url.clone()) + .await? + { + Some(keysets_info) => Ok(keysets_info), + None => Err(Error::UnknownKeySet), + } } - /// Get active keyset for mint + /// Refresh keysets by fetching the latest from mint - always goes online /// - /// Queries mint for current keysets then gets [`Keys`] for any unknown - /// keysets + /// This method always goes online to fetch the latest keyset information from the mint. + /// It updates the local database with the fetched keysets and ensures we have keys + /// for all active keysets. This is used when operations need the most up-to-date + /// keyset information and are willing to go online. #[instrument(skip(self))] - pub async fn get_active_mint_keysets(&self) -> Result, Error> { - let keysets = self.client.get_mint_keysets().await?; - let keysets = keysets.keysets; + pub async fn refresh_keysets(&self) -> Result { + tracing::debug!("Refreshing keysets and ensuring we have keys"); + let _ = self.get_mint_info().await?; + // Fetch all current keysets from mint + let keysets_response = self.client.get_mint_keysets().await?; + let all_keysets = keysets_response.keysets; + + // Update local storage with keyset info self.localstore - .add_mint_keysets(self.mint_url.clone(), keysets.clone()) + .add_mint_keysets(self.mint_url.clone(), all_keysets.clone()) .await?; - let active_keysets = keysets - .clone() - .into_iter() - .filter(|k| k.active && k.unit == self.unit) - .collect::>(); + // Filter for active keysets matching our unit + let keysets: KeySetInfos = all_keysets.unit(self.unit.clone()).cloned().collect(); - match self - .localstore - .get_mint_keysets(self.mint_url.clone()) - .await? - { - Some(known_keysets) => { - let unknown_keysets: Vec<&KeySetInfo> = keysets - .iter() - .filter(|k| known_keysets.contains(k)) - .collect(); - - for keyset in unknown_keysets { - self.get_keyset_keys(keyset.id).await?; - } - } - None => { - for keyset in keysets { - self.get_keyset_keys(keyset.id).await?; - } + // Ensure we have keys for all active keysets + for keyset in &keysets { + if self.localstore.get_keys(&keyset.id).await?.is_none() { + tracing::debug!("Fetching missing keys for keyset {}", keyset.id); + self.fetch_keyset_keys(keyset.id).await?; } } - Ok(active_keysets) + Ok(keysets) } - /// Get active keyset for mint with the lowest fees + /// Get the active keyset with the lowest fees - always goes online /// - /// Queries mint for current keysets then gets [`Keys`] for any unknown - /// keysets + /// This method always goes online to refresh keysets from the mint and then returns + /// the active keyset with the minimum input fees. Use this when you need the most + /// up-to-date keyset information for operations. #[instrument(skip(self))] - pub async fn get_active_mint_keyset(&self) -> Result { - // Important - let _ = self.get_mint_info().await?; - let active_keysets = self.get_active_mint_keysets().await?; + pub async fn fetch_active_keyset(&self) -> Result { + self.refresh_keysets() + .await? + .active() + .min_by_key(|k| k.input_fee_ppk) + .cloned() + .ok_or(Error::NoActiveKeyset) + } - let keyset_with_lowest_fee = active_keysets - .into_iter() - .min_by_key(|key| key.input_fee_ppk) - .ok_or(Error::NoActiveKeyset)?; - Ok(keyset_with_lowest_fee) + /// Get the active keyset with the lowest fees from local database only - offline operation + /// + /// Returns the active keyset with minimum input fees from cached keysets in the local database. + /// This is an offline operation that does not contact the mint. If no keysets are found locally, + /// returns an error. Use this for offline operations or when you want to avoid network calls. + #[instrument(skip(self))] + pub async fn get_active_keyset(&self) -> Result { + match self + .localstore + .get_mint_keysets(self.mint_url.clone()) + .await? + { + Some(keysets_info) => keysets_info + .into_iter() + .min_by_key(|k| k.input_fee_ppk) + .ok_or(Error::NoActiveKeyset), + None => Err(Error::UnknownKeySet), + } } - /// Get keyset fees for mint + /// Get keyset fees for mint from local database only - offline operation + /// + /// Returns a HashMap of keyset IDs to their input fee rates (per-proof-per-thousand) + /// from cached keysets in the local database. This is an offline operation that does + /// not contact the mint. If no keysets are found locally, returns an error. pub async fn get_keyset_fees(&self) -> Result, Error> { let keysets = self .localstore @@ -134,7 +156,11 @@ impl Wallet { Ok(fees) } - /// Get keyset fees for mint by keyset id + /// Get keyset fees for mint by keyset id from local database only - offline operation + /// + /// Returns the input fee rate (per-proof-per-thousand) for a specific keyset ID from + /// cached keysets in the local database. This is an offline operation that does not + /// contact the mint. If the keyset is not found locally, returns an error. pub async fn get_keyset_fees_by_id(&self, keyset_id: Id) -> Result { self.get_keyset_fees() .await? diff --git a/crates/cdk/src/wallet/melt/melt_bolt11.rs b/crates/cdk/src/wallet/melt/melt_bolt11.rs index afe3b4386..014443316 100644 --- a/crates/cdk/src/wallet/melt/melt_bolt11.rs +++ b/crates/cdk/src/wallet/melt/melt_bolt11.rs @@ -146,7 +146,7 @@ impl Wallet { .update_proofs_state(ys, State::Pending) .await?; - let active_keyset_id = self.get_active_mint_keyset().await?.id; + let active_keyset_id = self.fetch_active_keyset().await?.id; let count = self .localstore @@ -317,7 +317,7 @@ impl Wallet { let available_proofs = self.get_unspent_proofs().await?; let active_keyset_ids = self - .get_active_mint_keysets() + .refresh_keysets() .await? .into_iter() .map(|k| k.id) diff --git a/crates/cdk/src/wallet/mod.rs b/crates/cdk/src/wallet/mod.rs index bfec189f8..a0bf863ca 100644 --- a/crates/cdk/src/wallet/mod.rs +++ b/crates/cdk/src/wallet/mod.rs @@ -378,12 +378,12 @@ impl Wallet { self.get_mint_info().await?; } - let keysets = self.get_mint_keysets().await?; + let keysets = self.load_mint_keysets().await?; let mut restored_value = Amount::ZERO; for keyset in keysets { - let keys = self.get_keyset_keys(keyset.id).await?; + let keys = self.fetch_keyset_keys(keyset.id).await?; let mut empty_batch = 0; let mut start_counter = 0; @@ -632,7 +632,7 @@ impl Wallet { let mint_pubkey = match keys_cache.get(&proof.keyset_id) { Some(keys) => keys.amount_key(proof.amount), None => { - let keys = self.get_keyset_keys(proof.keyset_id).await?; + let keys = self.fetch_keyset_keys(proof.keyset_id).await?; let key = keys.amount_key(proof.amount); keys_cache.insert(proof.keyset_id, keys); diff --git a/crates/cdk/src/wallet/multi_mint_wallet.rs b/crates/cdk/src/wallet/multi_mint_wallet.rs index bea3ab3bd..cfac4e1b7 100644 --- a/crates/cdk/src/wallet/multi_mint_wallet.rs +++ b/crates/cdk/src/wallet/multi_mint_wallet.rs @@ -293,7 +293,7 @@ impl MultiMintWallet { { Some(keysets_info) => keysets_info, // Hit the keysets endpoint if we don't have the keysets for this Mint - None => wallet.get_mint_keysets().await?, + None => wallet.load_mint_keysets().await?, }; let proofs = token_data.proofs(&keysets_info)?; diff --git a/crates/cdk/src/wallet/receive.rs b/crates/cdk/src/wallet/receive.rs index 04afa7283..84b3aff3e 100644 --- a/crates/cdk/src/wallet/receive.rs +++ b/crates/cdk/src/wallet/receive.rs @@ -38,11 +38,11 @@ impl Wallet { self.get_mint_info().await?; } - let _ = self.get_active_mint_keyset().await?; + let _ = self.fetch_active_keyset().await?; - let active_keyset_id = self.get_active_mint_keyset().await?.id; + let active_keyset_id = self.fetch_active_keyset().await?.id; - let keys = self.get_keyset_keys(active_keyset_id).await?; + let keys = self.fetch_keyset_keys(active_keyset_id).await?; let mut proofs = proofs; @@ -70,7 +70,7 @@ impl Wallet { for proof in &mut proofs { // Verify that proof DLEQ is valid if proof.dleq.is_some() { - let keys = self.get_keyset_keys(proof.keyset_id).await?; + let keys = self.fetch_keyset_keys(proof.keyset_id).await?; let key = keys.amount_key(proof.amount).ok_or(Error::AmountKey)?; proof.verify_dleq(key)?; } diff --git a/crates/cdk/src/wallet/send.rs b/crates/cdk/src/wallet/send.rs index a98547b44..9d6b47648 100644 --- a/crates/cdk/src/wallet/send.rs +++ b/crates/cdk/src/wallet/send.rs @@ -1,6 +1,7 @@ use std::collections::HashMap; use std::fmt::Debug; +use cdk_common::nut02::KeySetInfosMethods; use cdk_common::util::unix_time; use cdk_common::wallet::{Transaction, TransactionDirection}; use tracing::instrument; @@ -32,11 +33,8 @@ impl Wallet { // If online send check mint for current keysets fees if opts.send_kind.is_online() { - if let Err(e) = self.get_active_mint_keyset().await { - tracing::error!( - "Error fetching active mint keyset: {:?}. Using stored keysets", - e - ); + if let Err(e) = self.refresh_keysets().await { + tracing::error!("Error refreshing keysets: {:?}. Using stored keysets", e); } } @@ -78,11 +76,12 @@ impl Wallet { // Select proofs let active_keyset_ids = self - .get_active_mint_keysets() + .get_mint_keysets() .await? - .into_iter() + .active() .map(|k| k.id) .collect(); + let selected_proofs = Wallet::select_proofs( amount, available_proofs, @@ -131,7 +130,7 @@ impl Wallet { ) -> Result { // Split amount with fee if necessary let (send_amounts, send_fee) = if opts.include_fee { - let active_keyset_id = self.get_active_mint_keyset().await?.id; + let active_keyset_id = self.get_active_keyset().await?.id; let keyset_fee_ppk = self.get_keyset_fees_by_id(active_keyset_id).await?; tracing::debug!("Keyset fee per proof: {:?}", keyset_fee_ppk); let send_split = amount.split_with_fee(keyset_fee_ppk)?; @@ -209,7 +208,7 @@ impl Wallet { let mut proofs_to_send = send.proofs_to_send; // Get active keyset ID - let active_keyset_id = self.get_active_mint_keyset().await?.id; + let active_keyset_id = self.fetch_active_keyset().await?.id; tracing::debug!("Active keyset ID: {:?}", active_keyset_id); // Get keyset fees diff --git a/crates/cdk/src/wallet/swap.rs b/crates/cdk/src/wallet/swap.rs index 5e9f15aad..85c82bbfe 100644 --- a/crates/cdk/src/wallet/swap.rs +++ b/crates/cdk/src/wallet/swap.rs @@ -1,3 +1,4 @@ +use cdk_common::nut02::KeySetInfosMethods; use tracing::instrument; use crate::amount::SplitTarget; @@ -167,11 +168,12 @@ impl Wallet { ensure_cdk!(proofs_sum >= amount, Error::InsufficientFunds); let active_keyset_ids = self - .get_active_mint_keysets() + .refresh_keysets() .await? - .into_iter() + .active() .map(|k| k.id) .collect(); + let keyset_fees = self.get_keyset_fees().await?; let proofs = Wallet::select_proofs( amount, @@ -203,7 +205,7 @@ impl Wallet { include_fees: bool, ) -> Result { tracing::info!("Creating swap"); - let active_keyset_id = self.get_active_mint_keyset().await?.id; + let active_keyset_id = self.fetch_active_keyset().await?.id; // Desired amount is either amount passed or value of all proof let proofs_total = proofs.total_amount()?; From 9df904648e87a9b7c41c322cf14c42482e34e710 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Thu, 24 Jul 2025 09:00:06 +0100 Subject: [PATCH 031/321] fix(cashu): preserve original case for custom CurrencyUnit values Custom currency units were incorrectly being converted to uppercase during deserialization. This change ensures custom units maintain their original case while still allowing case-insensitive matching for standard units. --- CHANGELOG.md | 2 ++ crates/cashu/src/nuts/nut00/mod.rs | 14 +++++++++++--- 2 files changed, 13 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4d2b663d0..f4c11e577 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,6 +23,8 @@ - cdk-mintd: Updated to use new mint lifecycle methods for improved service management ([thesimplekid]). - cdk-integration-tests: Updated test utilities to use new mint lifecycle management ([thesimplekid]). +### Fixed +- cashu: Fixed CurrencyUnit custom units preserving original case instead of being converted to uppercase ([thesimplekid]). ## [0.11.0](https://github.com/cashubtc/cdk/releases/tag/v0.11.0) diff --git a/crates/cashu/src/nuts/nut00/mod.rs b/crates/cashu/src/nuts/nut00/mod.rs index 3996800f5..cbcbf0617 100644 --- a/crates/cashu/src/nuts/nut00/mod.rs +++ b/crates/cashu/src/nuts/nut00/mod.rs @@ -591,14 +591,14 @@ impl CurrencyUnit { impl FromStr for CurrencyUnit { type Err = Error; fn from_str(value: &str) -> Result { - let value = &value.to_uppercase(); - match value.as_str() { + let upper_value = value.to_uppercase(); + match upper_value.as_str() { "SAT" => Ok(Self::Sat), "MSAT" => Ok(Self::Msat), "USD" => Ok(Self::Usd), "EUR" => Ok(Self::Eur), "AUTH" => Ok(Self::Auth), - c => Ok(Self::Custom(c.to_string())), + _ => Ok(Self::Custom(value.to_string())), } } } @@ -977,4 +977,12 @@ mod tests { .unwrap(); assert_eq!(b.len(), 1); } + + #[test] + fn custom_unit_ser_der() { + let unit = CurrencyUnit::Custom(String::from("test")); + let serialized = serde_json::to_string(&unit).unwrap(); + let deserialized: CurrencyUnit = serde_json::from_str(&serialized).unwrap(); + assert_eq!(unit, deserialized) + } } From 4997af879a55c3fcb84a5f0fe7cb72be24b98d21 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Thu, 24 Jul 2025 09:14:43 +0100 Subject: [PATCH 032/321] refactor(ci): move flake check from CI to separate daily workflow Move Nix flake input checking from the main CI pipeline to a dedicated daily scheduled workflow to reduce CI build time while maintaining regular dependency monitoring. --- .github/workflows/ci.yml | 11 ----------- .github/workflows/daily-flake-check.yml | 20 ++++++++++++++++++++ 2 files changed, 20 insertions(+), 11 deletions(-) create mode 100644 .github/workflows/daily-flake-check.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6a43fae51..fec7cec30 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -12,17 +12,6 @@ env: CARGO_TERM_COLOR: always jobs: - self-care: - name: Flake self-check - runs-on: ubuntu-latest - timeout-minutes: 30 - steps: - - uses: actions/checkout@v4 - - name: Check Nix flake inputs - uses: DeterminateSystems/flake-checker-action@v9 - with: - fail-mode: true - pre-commit-checks: name: "Cargo fmt, typos" runs-on: ubuntu-latest diff --git a/.github/workflows/daily-flake-check.yml b/.github/workflows/daily-flake-check.yml new file mode 100644 index 000000000..659ca6c46 --- /dev/null +++ b/.github/workflows/daily-flake-check.yml @@ -0,0 +1,20 @@ +name: Daily Flake Check + +on: + schedule: + # Run daily at 6 AM UTC + - cron: '0 6 * * *' + # Allow manual trigger + workflow_dispatch: + +jobs: + flake-check: + name: Daily Nix Flake Check + runs-on: ubuntu-latest + timeout-minutes: 30 + steps: + - uses: actions/checkout@v4 + - name: Check Nix flake inputs + uses: DeterminateSystems/flake-checker-action@v9 + with: + fail-mode: true From fef1cda009e1f9567982ddae62d48bba77a821c4 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Wed, 23 Jul 2025 22:16:42 +0100 Subject: [PATCH 033/321] refactor(flake): remove crane build system and simplify flake dependencies Remove crane and fenix dependencies along with their associated build infrastructure. This simplifies the flake to focus on development environments while removing package builds and applications. --- flake.lock | 24 +++++++------- flake.nix | 95 +++--------------------------------------------------- 2 files changed, 16 insertions(+), 103 deletions(-) diff --git a/flake.lock b/flake.lock index 6de883378..8589eaed4 100644 --- a/flake.lock +++ b/flake.lock @@ -2,11 +2,11 @@ "nodes": { "crane": { "locked": { - "lastModified": 1750266157, - "narHash": "sha256-tL42YoNg9y30u7zAqtoGDNdTyXTi8EALDeCB13FtbQA=", + "lastModified": 1753316655, + "narHash": "sha256-tzWa2kmTEN69OEMhxFy+J2oWSvZP5QhEgXp3TROOzl0=", "owner": "ipetkov", "repo": "crane", - "rev": "e37c943371b73ed87faf33f7583860f81f1d5a48", + "rev": "f35a3372d070c9e9ccb63ba7ce347f0634ddf3d2", "type": "github" }, "original": { @@ -23,11 +23,11 @@ "rust-analyzer-src": [] }, "locked": { - "lastModified": 1750833544, - "narHash": "sha256-e5W27mfPGiM35qr0DjTUzLHP4ET2MbvRc4HJHScw/ko=", + "lastModified": 1753511988, + "narHash": "sha256-wC9PR+rPjmcpnPdOIDwyNwQiRhNsuDs3oZY3t42f4uA=", "owner": "nix-community", "repo": "fenix", - "rev": "c3940d9ff4d37e965e5841149367234c2aad1ab6", + "rev": "25db7a6f4de7dea678620785e03fbc4560c00672", "type": "github" }, "original": { @@ -93,11 +93,11 @@ }, "nixpkgs": { "locked": { - "lastModified": 1750622754, - "narHash": "sha256-kMhs+YzV4vPGfuTpD3mwzibWUE6jotw5Al2wczI0Pv8=", + "lastModified": 1753345091, + "narHash": "sha256-CdX2Rtvp5I8HGu9swBmYuq+ILwRxpXdJwlpg8jvN4tU=", "owner": "NixOS", "repo": "nixpkgs", - "rev": "c7ab75210cb8cb16ddd8f290755d9558edde7ee1", + "rev": "3ff0e34b1383648053bba8ed03f201d3466f90c9", "type": "github" }, "original": { @@ -160,11 +160,11 @@ ] }, "locked": { - "lastModified": 1750819193, - "narHash": "sha256-XvkupGPZqD54HuKhN/2WhbKjAHeTl1UEnWspzUzRFfA=", + "lastModified": 1753497720, + "narHash": "sha256-yzZkDMVfPpNyTciQOfriWpRXrgGNT/cvrFAEQZ//SZs=", "owner": "oxalica", "repo": "rust-overlay", - "rev": "1ba3b9c59b68a4b00156827ad46393127b51b808", + "rev": "c8b8b812010515b7d9bd7e538f06a9f4edb373ff", "type": "github" }, "original": { diff --git a/flake.nix b/flake.nix index 20def6318..5790c106b 100644 --- a/flake.nix +++ b/flake.nix @@ -27,7 +27,7 @@ pre-commit-hooks.url = "github:cachix/pre-commit-hooks.nix"; }; - outputs = { self, nixpkgs, rust-overlay, flake-utils, pre-commit-hooks, crane, fenix, ... }: + outputs = { self, nixpkgs, rust-overlay, flake-utils, pre-commit-hooks, ... }: flake-utils.lib.eachDefaultSystem (system: let overlays = [ (import rust-overlay) ]; @@ -87,80 +87,9 @@ libz ] ++ libsDarwin; - # WASM deps - WASMInputs = with pkgs; [ - ]; - - - - craneLib = crane.mkLib pkgs; - src = craneLib.cleanCargoSource ./.; # Common arguments can be set here to avoid repeating them later - commonArgs = { - inherit src; - strictDeps = true; - - buildInputs = [ - # Add additional build inputs here - pkgs.protobuf - pkgs.pkg-config - ] ++ lib.optionals pkgs.stdenv.isDarwin [ - # Additional darwin specific inputs can be set here - pkgs.libiconv - ]; - - # Additional environment variables can be set directly - # MY_CUSTOM_VAR = "some value"; - PROTOC = "${pkgs.protobuf}/bin/protoc"; - PROTOC_INCLUDE = "${pkgs.protobuf}/include"; - }; - - - craneLibLLvmTools = craneLib.overrideToolchain - (fenix.packages.${system}.complete.withComponents [ - "cargo" - "llvm-tools" - "rustc" - ]); - - cargoArtifacts = craneLib.buildDepsOnly commonArgs; - - individualCrateArgs = commonArgs // { - inherit cargoArtifacts; - inherit (craneLib.crateNameFromCargoToml { inherit src; }) version; - # NB: we disable tests since we'll run them all via cargo-nextest - doCheck = false; - }; - - fileSetForCrate = crate: lib.fileset.toSource { - root = ./.; - fileset = lib.fileset.unions [ - ./Cargo.toml - ./Cargo.lock - (craneLib.fileset.commonCargoSources ./crates/cdk) - (craneLib.fileset.commonCargoSources ./crates/cdk-axum) - (craneLib.fileset.commonCargoSources ./crates/cdk-cln) - (craneLib.fileset.commonCargoSources ./crates/cdk-lnd) - (craneLib.fileset.commonCargoSources ./crates/cdk-fake-wallet) - (craneLib.fileset.commonCargoSources ./crates/cdk-lnbits) - (craneLib.fileset.commonCargoSources ./crates/cdk-redb) - (craneLib.fileset.commonCargoSources ./crates/cdk-sqlite) - ./crates/cdk-sqlite/src/mint/migrations - ./crates/cdk-sqlite/src/wallet/migrations - (craneLib.fileset.commonCargoSources crate) - ]; - }; - - cdk-mintd = craneLib.buildPackage (individualCrateArgs // { - pname = "cdk-mintd"; - name = "cdk-mintd-${individualCrateArgs.version}"; - cargoExtraArgs = "-p cdk-mintd"; - src = fileSetForCrate ./crates/cdk-mintd; - }); - - - nativeBuildInputs = with pkgs; [ + nativeBuildInputs = [ #Add additional build inputs here ] ++ lib.optionals isDarwin [ # Additional darwin specific native inputs can be set here @@ -201,22 +130,6 @@ }; }; - - packages = { - inherit cdk-mintd; - default = cdk-mintd; - } // lib.optionalAttrs (!pkgs.stdenv.isDarwin) { - my-workspace-llvm-coverage = craneLibLLvmTools.cargoLlvmCov (commonArgs // { - inherit cargoArtifacts; - }); - }; - - apps = { - cdk-mintd = flake-utils.lib.mkApp { - drv = cdk-mintd; - }; - }; - devShells = let # pre-commit-checks @@ -238,13 +151,13 @@ cargo update -p pest_meta --precise 2.8.0 cargo update -p pest --precise 2.8.0 "; - buildInputs = buildInputs ++ WASMInputs ++ [ msrv_toolchain ]; + buildInputs = buildInputs ++ [ msrv_toolchain ]; inherit nativeBuildInputs; } // envVars); stable = pkgs.mkShell ({ shellHook = ''${_shellHook}''; - buildInputs = buildInputs ++ WASMInputs ++ [ stable_toolchain ]; + buildInputs = buildInputs ++ [ stable_toolchain ]; inherit nativeBuildInputs; } // envVars); From 735de3216199324f412a30b7dcc0c7f208375aa3 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Sat, 26 Jul 2025 14:51:28 +0100 Subject: [PATCH 034/321] feat: sig all (#862) * feat: swap sig all * feat: melt sig all * feat: swap and melt sig flag verify for mint * feat: msg to sign tests --- .goosehints | 5 + crates/cashu/src/nuts/nut03.rs | 5 + crates/cashu/src/nuts/nut05.rs | 5 + crates/cashu/src/nuts/nut11/mod.rs | 977 ++++++++++++++++++++++++++++- crates/cdk/src/mint/melt.rs | 4 +- crates/cdk/src/mint/swap.rs | 16 +- 6 files changed, 987 insertions(+), 25 deletions(-) create mode 100644 .goosehints diff --git a/.goosehints b/.goosehints new file mode 100644 index 000000000..46e2f875a --- /dev/null +++ b/.goosehints @@ -0,0 +1,5 @@ +This is a rust project with crates in crate dir. + +tips: +- can look at unstaged changes for what is being worked on if starting +- Do not make code comments that explain *what* is happening. Only explain *why* something is being done. diff --git a/crates/cashu/src/nuts/nut03.rs b/crates/cashu/src/nuts/nut03.rs index 50b18e983..5dfa974ae 100644 --- a/crates/cashu/src/nuts/nut03.rs +++ b/crates/cashu/src/nuts/nut03.rs @@ -61,6 +61,11 @@ impl SwapRequest { &self.inputs } + /// Get mutable inputs (proofs) + pub fn inputs_mut(&mut self) -> &mut Proofs { + &mut self.inputs + } + /// Get outputs (blinded messages) pub fn outputs(&self) -> &Vec { &self.outputs diff --git a/crates/cashu/src/nuts/nut05.rs b/crates/cashu/src/nuts/nut05.rs index ac7992336..34ec338ea 100644 --- a/crates/cashu/src/nuts/nut05.rs +++ b/crates/cashu/src/nuts/nut05.rs @@ -115,6 +115,11 @@ impl MeltRequest { &self.inputs } + /// Get mutable inputs (proofs) + pub fn inputs_mut(&mut self) -> &mut Proofs { + &mut self.inputs + } + /// Get outputs (blinded messages for change) pub fn outputs(&self) -> &Option> { &self.outputs diff --git a/crates/cashu/src/nuts/nut11/mod.rs b/crates/cashu/src/nuts/nut11/mod.rs index 076aac030..675cba790 100644 --- a/crates/cashu/src/nuts/nut11/mod.rs +++ b/crates/cashu/src/nuts/nut11/mod.rs @@ -9,18 +9,19 @@ use std::{fmt, vec}; use bitcoin::hashes::sha256::Hash as Sha256Hash; use bitcoin::hashes::Hash; use bitcoin::secp256k1::schnorr::Signature; -use serde::de::Error as DeserializerError; +use serde::de::{DeserializeOwned, Error as DeserializerError}; use serde::ser::SerializeSeq; use serde::{Deserialize, Deserializer, Serialize, Serializer}; use thiserror::Error; use super::nut00::Witness; use super::nut01::PublicKey; +use super::nut05::MeltRequest; use super::{Kind, Nut10Secret, Proof, Proofs, SecretKey}; -use crate::ensure_cdk; use crate::nuts::nut00::BlindedMessage; use crate::secret::Secret; use crate::util::{hex, unix_time}; +use crate::{ensure_cdk, SwapRequest}; pub mod serde_p2pk_witness; @@ -367,8 +368,9 @@ impl SpendingConditions { if let Some(conditions) = conditions { pubkeys.extend(conditions.pubkeys.clone().unwrap_or_default()); } - - Some(pubkeys) + // Remove duplicates + let unique_pubkeys: HashSet<_> = pubkeys.into_iter().collect(); + Some(unique_pubkeys.into_iter().collect()) } Self::HTLCConditions { conditions, .. } => conditions.clone().and_then(|c| c.pubkeys), } @@ -820,6 +822,368 @@ impl From for Vec { } } +impl SwapRequest { + /// Generate the message to sign for SIG_ALL validation + /// Concatenates all input secrets and output blinded messages in order + fn sig_all_msg_to_sign(&self) -> String { + let mut msg_to_sign = String::new(); + + // Add all input secrets in order + for proof in self.inputs() { + let secret = proof.secret.to_string(); + msg_to_sign.push_str(&secret); + } + + // Add all output blinded messages in order + for output in self.outputs() { + let message = output.blinded_secret.to_string(); + msg_to_sign.push_str(&message); + } + + msg_to_sign + } + + /// Get required signature count from first input's spending conditions + fn get_sig_all_required_sigs(&self) -> Result<(u64, SpendingConditions), Error> { + let first_input = self.inputs().first().ok_or(Error::SpendConditionsNotMet)?; + let first_conditions: SpendingConditions = + SpendingConditions::try_from(&first_input.secret)?; + + let required_sigs = match first_conditions.clone() { + SpendingConditions::P2PKConditions { conditions, .. } => { + let conditions = conditions.ok_or(Error::IncorrectSecretKind)?; + + if SigFlag::SigAll != conditions.sig_flag { + return Err(Error::IncorrectSecretKind); + } + + conditions.num_sigs.unwrap_or(1) + } + _ => return Err(Error::IncorrectSecretKind), + }; + + Ok((required_sigs, first_conditions)) + } + + /// Verify all inputs have matching secrets and tags + fn verify_matching_conditions(&self) -> Result<(), Error> { + let first_input = self.inputs().first().ok_or(Error::SpendConditionsNotMet)?; + let first_nut10: Nut10Secret = (&first_input.secret).try_into()?; + + for proof in self.inputs().iter().skip(1) { + let current_secret: Nut10Secret = proof.secret.clone().try_into()?; + + // Check data matches + if current_secret.secret_data().data() != first_nut10.secret_data().data() { + return Err(Error::SpendConditionsNotMet); + } + + // Check tags match + if current_secret.secret_data().tags() != first_nut10.secret_data().tags() { + return Err(Error::SpendConditionsNotMet); + } + } + Ok(()) + } + + /// Get validated signatures from first input's witness + fn get_valid_witness_signatures(&self) -> Result, Error> { + let first_input = self.inputs().first().ok_or(Error::SpendConditionsNotMet)?; + let first_witness = first_input + .witness + .as_ref() + .ok_or(Error::SignaturesNotProvided)?; + + let witness_sigs = first_witness + .signatures() + .ok_or(Error::SignaturesNotProvided)?; + + // Convert witness strings to signatures + witness_sigs + .iter() + .map(|s| Signature::from_str(s)) + .collect::, _>>() + .map_err(Error::from) + } + + /// Check if swap request can be signed with the given secret key + fn can_sign_sig_all( + &self, + secret_key: &SecretKey, + ) -> Result<(SpendingConditions, PublicKey), Error> { + // Get the first input since all must match for SIG_ALL + let first_input = self.inputs().first().ok_or(Error::SpendConditionsNotMet)?; + let first_conditions: SpendingConditions = + SpendingConditions::try_from(&first_input.secret)?; + + // Verify this is a P2PK condition with SIG_ALL + match first_conditions.clone() { + SpendingConditions::P2PKConditions { conditions, .. } => { + let conditions = conditions.ok_or(Error::IncorrectSecretKind)?; + if conditions.sig_flag != SigFlag::SigAll { + return Err(Error::IncorrectSecretKind); + } + conditions + } + _ => return Err(Error::IncorrectSecretKind), + }; + + // Get authorized keys and verify secret_key matches one + let pubkey = secret_key.public_key(); + let authorized_keys = first_conditions + .pubkeys() + .ok_or(Error::P2PKPubkeyRequired)?; + + if !authorized_keys.contains(&pubkey) { + return Err(Error::SpendConditionsNotMet); + } + + Ok((first_conditions, pubkey)) + } + + /// Sign swap request with SIG_ALL if conditions are met + pub fn sign_sig_all(&mut self, secret_key: SecretKey) -> Result<(), Error> { + // Verify we can sign and get conditions + let (_first_conditions, _) = self.can_sign_sig_all(&secret_key)?; + + // Verify all inputs have matching conditions + self.verify_matching_conditions()?; + + // Get message to sign + let msg = self.sig_all_msg_to_sign(); + let signature = secret_key.sign(msg.as_bytes())?; + + // Add signature to first input witness + let first_input = self + .inputs_mut() + .first_mut() + .ok_or(Error::IncorrectSecretKind)?; + + match first_input.witness.as_mut() { + Some(witness) => { + witness.add_signatures(vec![signature.to_string()]); + } + None => { + let mut p2pk_witness = Witness::P2PKWitness(P2PKWitness::default()); + p2pk_witness.add_signatures(vec![signature.to_string()]); + first_input.witness = Some(p2pk_witness); + } + }; + + Ok(()) + } + + /// Validate SIG_ALL conditions and signatures for the swap request + pub fn verify_sig_all(&self) -> Result<(), Error> { + // Get required signatures and conditions from first input + let (required_sigs, first_conditions) = self.get_sig_all_required_sigs()?; + + // Verify all inputs have matching secrets + self.verify_matching_conditions()?; + + // Get and validate witness signatures + let signatures = self.get_valid_witness_signatures()?; + + // Get signing pubkeys + let verifying_pubkeys = first_conditions + .pubkeys() + .ok_or(Error::P2PKPubkeyRequired)?; + + // Get aggregated message and validate signatures + let msg = self.sig_all_msg_to_sign(); + let valid_sigs = valid_signatures(msg.as_bytes(), &verifying_pubkeys, &signatures)?; + + if valid_sigs >= required_sigs { + Ok(()) + } else { + Err(Error::SpendConditionsNotMet) + } + } +} + +impl MeltRequest { + /// Generate the message to sign for SIG_ALL validation + /// Concatenates all input secrets, blank outputs, and quote ID in order + fn sig_all_msg_to_sign(&self) -> String { + let mut msg_to_sign = String::new(); + + // Add all input secrets in order + for proof in self.inputs() { + let secret = proof.secret.to_string(); + msg_to_sign.push_str(&secret); + } + + // Add all blank outputs in order if they exist + if let Some(outputs) = self.outputs() { + for output in outputs { + msg_to_sign.push_str(&output.blinded_secret.to_hex()); + } + } + + // Add quote ID + msg_to_sign.push_str(&self.quote().to_string()); + + msg_to_sign + } + + /// Get required signature count from first input's spending conditions + fn get_sig_all_required_sigs(&self) -> Result<(u64, SpendingConditions), Error> { + let first_input = self.inputs().first().ok_or(Error::SpendConditionsNotMet)?; + let first_conditions: SpendingConditions = + SpendingConditions::try_from(&first_input.secret)?; + + let required_sigs = match first_conditions.clone() { + SpendingConditions::P2PKConditions { conditions, .. } => { + let conditions = conditions.ok_or(Error::IncorrectSecretKind)?; + + if SigFlag::SigAll != conditions.sig_flag { + return Err(Error::IncorrectSecretKind); + } + + conditions.num_sigs.unwrap_or(1) + } + _ => return Err(Error::IncorrectSecretKind), + }; + + Ok((required_sigs, first_conditions)) + } + + /// Verify all inputs have matching secrets and tags + fn verify_matching_conditions(&self) -> Result<(), Error> { + let first_input = self.inputs().first().ok_or(Error::SpendConditionsNotMet)?; + let first_nut10: Nut10Secret = (&first_input.secret).try_into()?; + + for proof in self.inputs().iter().skip(1) { + let current_secret: Nut10Secret = proof.secret.clone().try_into()?; + + // Check data matches + if current_secret.secret_data().data() != first_nut10.secret_data().data() { + return Err(Error::SpendConditionsNotMet); + } + + // Check tags match + if current_secret.secret_data().tags() != first_nut10.secret_data().tags() { + return Err(Error::SpendConditionsNotMet); + } + } + Ok(()) + } + + /// Get validated signatures from first input's witness + fn get_valid_witness_signatures(&self) -> Result, Error> { + let first_input = self.inputs().first().ok_or(Error::SpendConditionsNotMet)?; + let first_witness = first_input + .witness + .as_ref() + .ok_or(Error::SignaturesNotProvided)?; + + let witness_sigs = first_witness + .signatures() + .ok_or(Error::SignaturesNotProvided)?; + + // Convert witness strings to signatures + witness_sigs + .iter() + .map(|s| Signature::from_str(s)) + .collect::, _>>() + .map_err(Error::from) + } + + /// Check if melt request can be signed with the given secret key + fn can_sign_sig_all( + &self, + secret_key: &SecretKey, + ) -> Result<(SpendingConditions, PublicKey), Error> { + // Get the first input since all must match for SIG_ALL + let first_input = self.inputs().first().ok_or(Error::SpendConditionsNotMet)?; + let first_conditions: SpendingConditions = + SpendingConditions::try_from(&first_input.secret)?; + + // Verify this is a P2PK condition with SIG_ALL + match first_conditions.clone() { + SpendingConditions::P2PKConditions { conditions, .. } => { + let conditions = conditions.ok_or(Error::IncorrectSecretKind)?; + if conditions.sig_flag != SigFlag::SigAll { + return Err(Error::IncorrectSecretKind); + } + conditions + } + _ => return Err(Error::IncorrectSecretKind), + }; + + // Get authorized keys and verify secret_key matches one + let pubkey = secret_key.public_key(); + let authorized_keys = first_conditions + .pubkeys() + .ok_or(Error::P2PKPubkeyRequired)?; + + if !authorized_keys.contains(&pubkey) { + return Err(Error::SpendConditionsNotMet); + } + + Ok((first_conditions, pubkey)) + } + + /// Sign melt request with SIG_ALL if conditions are met + pub fn sign_sig_all(&mut self, secret_key: SecretKey) -> Result<(), Error> { + // Verify we can sign and get conditions + let (_first_conditions, _) = self.can_sign_sig_all(&secret_key)?; + + // Verify all inputs have matching conditions + self.verify_matching_conditions()?; + + // Get message to sign + let msg = self.sig_all_msg_to_sign(); + let signature = secret_key.sign(msg.as_bytes())?; + + // Add signature to first input witness + let first_input = self + .inputs_mut() + .first_mut() + .ok_or(Error::SpendConditionsNotMet)?; + + match first_input.witness.as_mut() { + Some(witness) => { + witness.add_signatures(vec![signature.to_string()]); + } + None => { + let mut p2pk_witness = Witness::P2PKWitness(P2PKWitness::default()); + p2pk_witness.add_signatures(vec![signature.to_string()]); + first_input.witness = Some(p2pk_witness); + } + }; + + Ok(()) + } + + /// Validate SIG_ALL conditions and signatures for the melt request + pub fn verify_sig_all(&self) -> Result<(), Error> { + // Get required signatures and conditions from first input + let (required_sigs, first_conditions) = self.get_sig_all_required_sigs()?; + + // Verify all inputs have matching secrets + self.verify_matching_conditions()?; + + // Get and validate witness signatures + let signatures = self.get_valid_witness_signatures()?; + + // Get signing pubkeys + let verifying_pubkeys = first_conditions + .pubkeys() + .ok_or(Error::P2PKPubkeyRequired)?; + + // Get aggregated message and validate signatures + let msg = self.sig_all_msg_to_sign(); + let valid_sigs = valid_signatures(msg.as_bytes(), &verifying_pubkeys, &signatures)?; + + if valid_sigs >= required_sigs { + Ok(()) + } else { + Err(Error::SpendConditionsNotMet) + } + } +} + impl Serialize for Tag { fn serialize(&self, serializer: S) -> Result where @@ -849,10 +1213,12 @@ impl<'de> Deserialize<'de> for Tag { mod tests { use std::str::FromStr; + use uuid::Uuid; + use super::*; use crate::nuts::Id; use crate::secret::Secret; - use crate::Amount; + use crate::{Amount, BlindedMessage}; #[test] fn test_secret_ser() { @@ -994,12 +1360,601 @@ mod tests { assert!(invalid_proof.verify_p2pk().is_err()); } + // Helper functions for melt request tests + fn create_test_proof(secret: Secret, pubkey: PublicKey, id: &str) -> Proof { + Proof { + keyset_id: Id::from_str(id).unwrap(), + amount: Amount::ZERO, + secret, + c: pubkey, + witness: None, + dleq: None, + } + } + + fn create_test_secret(pubkey: PublicKey, conditions: Conditions) -> Secret { + Nut10Secret::new(Kind::P2PK, pubkey.to_string(), Some(conditions)) + .try_into() + .unwrap() + } + + fn create_test_blinded_msg(pubkey: PublicKey) -> BlindedMessage { + BlindedMessage { + amount: Amount::ZERO, + blinded_secret: pubkey, + keyset_id: Id::from_str("009a1f293253e41e").unwrap(), + witness: None, + } + } + #[test] - fn test_duplicate_signatures_counting() { - let proof: Proof = serde_json::from_str( - r#"{"amount":1,"id":"009a1f293253e41e","secret":"[\"P2PK\",{\"nonce\":\"e434a9efbc5f65d144a620e368c9a6dc12c719d0ebc57e0c74f7341864dc449a\",\"data\":\"02a60c27104cf6023581e790970fc33994a320abe36e7ceed16771b0f8d76f0666\",\"tags\":[[\"pubkeys\",\"039c6a20a6ba354b7bb92eb9750716c1098063006362a1fa2afca7421f262d45c5\",\"0203eb2f7cd72a4f725d3327216365d2df18bb4bbc810522fd973c9af987e9b05b\"],[\"locktime\",\"1744876528\"],[\"n_sigs\",\"2\"],[\"sigflag\",\"SIG_INPUTS\"]]}]","C":"02698c4e2b5f9534cd0687d87513c759790cf829aa5739184a3e3735471fbda904","witness":"{\"signatures\":[\"3e9ff9e55c9eccb9e5aa0b6c62d54500b40d0eebadb06efcc8e76f3ce38e0923f956ec1bccb9080db96a17c1e98a1b857abfd1a56bb25670037cea3db1f73d81\",\"c5e29c38e60c4db720cf3f78e590358cf1291a06b9eadf77c1108ae84d533520c2707ffda224eb6a63fddaee9abd5ecf8f2cd263d2556950550e3061a5511f65\"]}"}"#, - ).unwrap(); + fn test_melt_sig_all_basic_signing() { + let secret_key = + SecretKey::from_str("99590802251e78ee1051648439eedb003dc539093a48a44e7b8f2642c909ea37") + .unwrap(); + let pubkey = secret_key.public_key(); + + // Create conditions with SIG_ALL + let conditions = Conditions { + sig_flag: SigFlag::SigAll, + pubkeys: Some(vec![pubkey]), + ..Default::default() + }; - assert!(proof.verify_p2pk().is_err()); + let secret = create_test_secret(pubkey, conditions); + let proof = create_test_proof(secret, pubkey, "009a1f293253e41e"); + let blinded_msg = create_test_blinded_msg(pubkey); + + // Create melt request + let mut melt = MeltRequest::new(Uuid::new_v4(), vec![proof], Some(vec![blinded_msg])); + + // Before signing, should fail verification + assert!( + melt.verify_sig_all().is_err(), + "Unsigned melt request should fail verification" + ); + + // Sign the request + assert!( + melt.sign_sig_all(secret_key).is_ok(), + "Signing should succeed" + ); + + // After signing, should pass verification + assert!( + melt.verify_sig_all().is_ok(), + "Signed melt request should pass verification" + ); } -} + + #[test] + fn test_melt_sig_all_unauthorized_key() { + let secret_key = + SecretKey::from_str("99590802251e78ee1051648439eedb003dc539093a48a44e7b8f2642c909ea37") + .unwrap(); + let pubkey = secret_key.public_key(); + + // Create conditions with explicit authorized pubkey + let conditions = Conditions { + sig_flag: SigFlag::SigAll, + pubkeys: Some(vec![pubkey]), + ..Default::default() + }; + + let secret = create_test_secret(pubkey, conditions); + let proof = create_test_proof(secret, pubkey, "009a1f293253e41e"); + + let mut melt = MeltRequest::new(Uuid::new_v4(), vec![proof], None); + + // Try to sign with unauthorized key + let unauthorized_key = + SecretKey::from_str("0000000000000000000000000000000000000000000000000000000000000001") + .unwrap(); + + assert!( + melt.sign_sig_all(unauthorized_key).is_err(), + "Signing with unauthorized key should fail" + ); + } + + #[test] + fn test_melt_sig_all_wrong_flag() { + let secret_key = + SecretKey::from_str("99590802251e78ee1051648439eedb003dc539093a48a44e7b8f2642c909ea37") + .unwrap(); + let pubkey = secret_key.public_key(); + + // Create conditions with SIG_INPUTS instead of SIG_ALL + let conditions = Conditions { + sig_flag: SigFlag::SigInputs, + pubkeys: Some(vec![pubkey]), + ..Default::default() + }; + + let secret = create_test_secret(pubkey, conditions); + let proof = create_test_proof(secret, pubkey, "009a1f293253e41e"); + + let mut melt = MeltRequest::new(Uuid::new_v4(), vec![proof], None); + + assert!( + melt.sign_sig_all(secret_key).is_err(), + "Signing with SIG_INPUTS flag should fail" + ); + } + + #[test] + fn test_melt_sig_all_multiple_inputs() { + let secret_key = + SecretKey::from_str("99590802251e78ee1051648439eedb003dc539093a48a44e7b8f2642c909ea37") + .unwrap(); + let pubkey = secret_key.public_key(); + + // Create conditions + let conditions = Conditions { + sig_flag: SigFlag::SigAll, + pubkeys: Some(vec![pubkey]), + ..Default::default() + }; + + let secret = create_test_secret(pubkey, conditions); + + // Create two proofs with same secret + let proof1 = create_test_proof(secret.clone(), pubkey, "009a1f293253e41e"); + let proof2 = create_test_proof(secret, pubkey, "009a1f293253e41f"); + + let mut melt = MeltRequest::new(Uuid::new_v4(), vec![proof1, proof2], None); + + // Signing should work with multiple matching inputs + assert!( + melt.sign_sig_all(secret_key).is_ok(), + "Signing with multiple matching inputs should succeed" + ); + assert!( + melt.verify_sig_all().is_ok(), + "Verification should succeed with multiple matching inputs" + ); + } + + #[test] + fn test_melt_sig_all_mismatched_inputs() { + let secret_key = + SecretKey::from_str("99590802251e78ee1051648439eedb003dc539093a48a44e7b8f2642c909ea37") + .unwrap(); + let pubkey = secret_key.public_key(); + + // Create first secret and proof + let conditions1 = Conditions { + sig_flag: SigFlag::SigAll, + ..Default::default() + }; + let secret1 = create_test_secret(pubkey, conditions1.clone()); + let proof1 = create_test_proof(secret1, pubkey, "009a1f293253e41e"); + + // Create second secret with different data + let conditions2 = conditions1.clone(); + let secret2 = Nut10Secret::new( + Kind::P2PK, + "02698c4e2b5f9534cd0687d87513c759790cf829aa5739184a3e3735471fbda904", + Some(conditions2), + ) + .try_into() + .unwrap(); + let proof2 = create_test_proof(secret2, pubkey, "009a1f293253e41f"); + + let mut melt = MeltRequest::new(Uuid::new_v4(), vec![proof1, proof2], None); + + assert!( + melt.sign_sig_all(secret_key).is_err(), + "Signing with mismatched input secrets should fail" + ); + } + + #[test] + fn test_melt_sig_all_multiple_signatures() { + let secret_key1 = + SecretKey::from_str("99590802251e78ee1051648439eedb003dc539093a48a44e7b8f2642c909ea37") + .unwrap(); + let pubkey1 = secret_key1.public_key(); + + let secret_key2 = + SecretKey::from_str("7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f") + .unwrap(); + let pubkey2 = secret_key2.public_key(); + + // Create conditions requiring 2 signatures + let conditions = Conditions { + sig_flag: SigFlag::SigAll, + num_sigs: Some(2), + pubkeys: Some(vec![pubkey1, pubkey2]), + ..Default::default() + }; + + let secret = create_test_secret(pubkey1, conditions); + let proof = create_test_proof(secret, pubkey1, "009a1f293253e41e"); + + let mut melt = MeltRequest::new( + Uuid::new_v4(), + vec![proof], + Some(vec![create_test_blinded_msg( + SecretKey::generate().public_key(), + )]), + ); + + // First signature + assert!( + melt.sign_sig_all(secret_key1).is_ok(), + "First signature should succeed" + ); + assert!( + melt.verify_sig_all().is_err(), + "Single signature should not verify when two required" + ); + + // Second signature + assert!( + melt.sign_sig_all(secret_key2).is_ok(), + "Second signature should succeed" + ); + + assert!( + melt.verify_sig_all().is_ok(), + "Both signatures should verify successfully" + ); + } + + #[test] + fn test_melt_sig_all_message_components() { + let secret_key = + SecretKey::from_str("99590802251e78ee1051648439eedb003dc539093a48a44e7b8f2642c909ea37") + .unwrap(); + let pubkey = secret_key.public_key(); + + let conditions = Conditions { + sig_flag: SigFlag::SigAll, + pubkeys: Some(vec![pubkey]), + ..Default::default() + }; + + let secret = create_test_secret(pubkey, conditions); + let proof = create_test_proof(secret.clone(), pubkey, "009a1f293253e41e"); + let blinded_msg = create_test_blinded_msg(pubkey); + let quote_id = Uuid::new_v4(); + + let melt = MeltRequest::new(quote_id, vec![proof], Some(vec![blinded_msg.clone()])); + + // Get message to sign + let msg = melt.sig_all_msg_to_sign(); + + // Verify all components are present in the message + assert!( + msg.contains(&secret.to_string()), + "Message should contain secret" + ); + assert!( + msg.contains(&blinded_msg.blinded_secret.to_hex()), + "Message should contain blinded message in hex format" + ); + assert!( + msg.contains("e_id.to_string()), + "Message should contain quote ID" + ); + } + + #[test] + fn test_sig_all_swap_single_sig() { + // Valid SwapRequest with SIG_ALL signature + let valid_swap = r#"{"inputs":[{"amount":0,"id":"009a1f293253e41e","secret":"[\"P2PK\",{\"nonce\":\"fc14ca312b7442d05231239d0e3cdcb6b2335250defcb8bec7d2efe9e26c90a6\",\"data\":\"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a\",\"tags\":[[\"sigflag\",\"SIG_ALL\"]]}]","C":"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a","witness":"{\"signatures\":[\"aa6f3b3f112ec3e834aded446ea67a90cdb26b43e08cfed259e0bbd953395c4af11117c58ec0ec3de404f31076692426cde40d2c1602d9dd067a872cb11ac3c0\"]}"},{"amount":0,"id":"009a1f293253e41f","secret":"[\"P2PK\",{\"nonce\":\"fc14ca312b7442d05231239d0e3cdcb6b2335250defcb8bec7d2efe9e26c90a6\",\"data\":\"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a\",\"tags\":[[\"sigflag\",\"SIG_ALL\"]]}]","C":"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a"}],"outputs":[{"amount":0,"id":"009a1f293253e41e","B_":"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a"}]}"#; + + let valid_swap: SwapRequest = serde_json::from_str(valid_swap).unwrap(); + assert!( + valid_swap.verify_sig_all().is_ok(), + "Valid SIG_ALL swap request should verify" + ); + } + + #[test] + fn test_sig_all_swap_mismatched_inputs() { + // Invalid SwapRequest - mismatched inputs with SIG_ALL + let invalid_swap = r#"{ + "inputs": [{ + "amount": 1, + "secret": "[\"P2PK\",{\"nonce\":\"859d4935c4907062a6297cf4e663e2835d90d97ecdd510745d32f6816323a41f\",\"data\":\"0249098aa8b9d2fbec49ff8598feb17b592b986e62319a4fa488a3dc36387157a7\",\"tags\":[[\"sigflag\",\"SIG_ALL\"]]}]", + "C": "02698c4e2b5f9534cd0687d87513c759790cf829aa5739184a3e3735471fbda904", + "id": "009a1f293253e41e", + "witness": "{\"signatures\":[\"60f3c9b766770b46caac1d27e1ae6b77c8866ebaeba0b9489fe6a15a837eaa6fcd6eaa825499c72ac342983983fd3ba3a8a41f56677cc99ffd73da68b59e1383\"]}" + }, { + "amount": 1, + "secret": "[\"P2PK\",{\"nonce\":\"859d4935c4907062a6297cf4e663e2835d90d97ecdd510745d32f6816323a41f\",\"data\":\"02a60c27104cf6023581e790970fc33994a320abe36e7ceed16771b0f8d76f0666\",\"tags\":[[\"sigflag\",\"SIG_ALL\"]]}]", + "C": "02698c4e2b5f9534cd0687d87513c759790cf829aa5739184a3e3735471fbda904", + "id": "009a1f293253e41f", + "witness": "{\"signatures\":[\"60f3c9b766770b46caac1d27e1ae6b77c8866ebaeba0b9489fe6a15a837eaa6fcd6eaa825499c72ac342983983fd3ba3a8a41f56677cc99ffd73da68b59e1383\"]}" + }], + "outputs": [{ + "amount": 2, + "B_": "02698c4e2b5f9534cd0687d87513c759790cf829aa5739184a3e3735471fbda904", + "id": "009a1f293253e41e" + }] + }"#; + + let invalid_swap: SwapRequest = serde_json::from_str(invalid_swap).unwrap(); + assert!( + invalid_swap.verify_sig_all().is_err(), + "Invalid SIG_ALL swap request should fail verification" + ); + } + + #[test] + fn test_sig_all_swap_multi_sig() { + // SwapRequest with multi-sig SIG_ALL requiring 2 signatures + let multisig_swap = r#"{"inputs":[{"amount":0,"id":"009a1f293253e41e","secret":"[\"P2PK\",{\"nonce\":\"c537ea76c1ac9cfa44d15dac91a63315903a3b4afa8e4e20f868f87f65ff2d16\",\"data\":\"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a\",\"tags\":[[\"pubkeys\",\"03142715675faf8da1ecc4d51e0b9e539fa0d52fdd96ed60dbe99adb15d6b05ad9\"],[\"n_sigs\",\"2\"],[\"sigflag\",\"SIG_ALL\"]]}]","C":"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a","witness":"{\"signatures\":[\"c38cf7943f59206dc22734d39c17e342674a4025e6d3b424eb79d445a57257d57b45dd94fcd1b8dd8013e9240a4133bdef6523f64cd7288d890f3bbb8e3c6453\",\"f766dbb80e5c27de9a4770486e11e1bac0b1c4f782bf807a5189ea9c3e294559a3de4e217d3dfceafd4d9e8dcbfe4e9a188052d6dab9df07df7844224292de36\"]}"}],"outputs":[{"amount":0,"id":"009a1f293253e41e","B_":"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a"}]}"#; + + let multisig_swap: SwapRequest = serde_json::from_str(multisig_swap).unwrap(); + assert!( + multisig_swap.verify_sig_all().is_ok(), + "Multi-sig SIG_ALL swap request should verify with both signatures" + ); + } + + #[test] + fn test_sig_all_swap_msg_to_sign() { + // SwapRequest with multi-sig SIG_ALL requiring 2 signatures + let multisig_swap = r#"{"inputs":[{"amount":0,"id":"009a1f293253e41e","secret":"[\"P2PK\",{\"nonce\":\"c537ea76c1ac9cfa44d15dac91a63315903a3b4afa8e4e20f868f87f65ff2d16\",\"data\":\"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a\",\"tags\":[[\"pubkeys\",\"03142715675faf8da1ecc4d51e0b9e539fa0d52fdd96ed60dbe99adb15d6b05ad9\"],[\"n_sigs\",\"2\"],[\"sigflag\",\"SIG_ALL\"]]}]","C":"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a","witness":"{\"signatures\":[\"c38cf7943f59206dc22734d39c17e342674a4025e6d3b424eb79d445a57257d57b45dd94fcd1b8dd8013e9240a4133bdef6523f64cd7288d890f3bbb8e3c6453\",\"f766dbb80e5c27de9a4770486e11e1bac0b1c4f782bf807a5189ea9c3e294559a3de4e217d3dfceafd4d9e8dcbfe4e9a188052d6dab9df07df7844224292de36\"]}"}],"outputs":[{"amount":0,"id":"009a1f293253e41e","B_":"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a"}]}"#; + + let multisig_swap: SwapRequest = serde_json::from_str(multisig_swap).unwrap(); + + let msg_to_sign = multisig_swap.sig_all_msg_to_sign(); + + println!("{}", msg_to_sign); + + assert_eq!( + msg_to_sign, + r#"["P2PK",{"nonce":"c537ea76c1ac9cfa44d15dac91a63315903a3b4afa8e4e20f868f87f65ff2d16","data":"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a","tags":[["pubkeys","03142715675faf8da1ecc4d51e0b9e539fa0d52fdd96ed60dbe99adb15d6b05ad9"],["n_sigs","2"],["sigflag","SIG_ALL"]]}]026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a"# + ) + } + + #[test] + fn test_sig_all_melt() { + // MeltRequest with valid SIG_ALL signature + let valid_melt = r#"{"quote":"0f983814-de91-46b8-8875-1b358a35298a","inputs":[{"amount":0,"id":"009a1f293253e41e","secret":"[\"P2PK\",{\"nonce\":\"600050bd36cccdc71dec82e97679fa3e7712c22ea33cf4fe69d4d78223757e57\",\"data\":\"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a\",\"tags\":[[\"pubkeys\",\"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a\"],[\"sigflag\",\"SIG_ALL\"]]}]","C":"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a","witness":"{\"signatures\":[\"b66c342654ccc95a62100f8f4a76afe1aea612c9c63383be3c7feb5110bb8eabe7ccaa9f117abd524be8c9a2e331e7d70248aeae337b9ce405625b3c49fc627d\"]}"}],"outputs":[{"amount":0,"id":"009a1f293253e41e","B_":"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a"}]}"#; + + let valid_melt: MeltRequest = serde_json::from_str(valid_melt).unwrap(); + assert!( + valid_melt.verify_sig_all().is_ok(), + "Valid SIG_ALL melt request should verify" + ); + } + + #[test] + fn test_sig_all_melt_wrong_sig() { + // Invalid MeltRequest - wrong signature for SIG_ALL + let invalid_melt = r#"{ + "inputs": [{ + "amount": 1, + "secret": "[\"P2PK\",{\"nonce\":\"859d4935c4907062a6297cf4e663e2835d90d97ecdd510745d32f6816323a41f\",\"data\":\"0249098aa8b9d2fbec49ff8598feb17b592b986e62319a4fa488a3dc36387157a7\",\"tags\":[[\"sigflag\",\"SIG_ALL\"]]}]", + "C": "02698c4e2b5f9534cd0687d87513c759790cf829aa5739184a3e3735471fbda904", + "id": "009a1f293253e41e", + "witness": "{\"signatures\":[\"3426df9730d365a9d18d79bed2f3e78e9172d7107c55306ac5ddd1b2d065893366cfa24ff3c874ebf1fc22360ba5888ddf6ff5dbcb9e5f2f5a1368f7afc64f15\"]}" + }], + "quote": "test_quote_123", + "outputs": null + }"#; + + let invalid_melt: MeltRequest = serde_json::from_str(invalid_melt).unwrap(); + assert!( + invalid_melt.verify_sig_all().is_err(), + "Invalid SIG_ALL melt request should fail verification" + ); + } + + #[test] + fn test_sig_all_melt_msg_to_sign() { + let multisig_melt = r#"{"quote":"2fc40ad3-2f6a-4a7e-91fb-b8c2b5dc2bf7","inputs":[{"amount":0,"id":"009a1f293253e41e","secret":"[\"P2PK\",{\"nonce\":\"1d0db9cbd2aa7370a3d6e0e3ce5714758ed7a085e2f8da9814924100e1fc622e\",\"data\":\"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a\",\"tags\":[[\"pubkeys\",\"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a\",\"03142715675faf8da1ecc4d51e0b9e539fa0d52fdd96ed60dbe99adb15d6b05ad9\"],[\"n_sigs\",\"2\"],[\"sigflag\",\"SIG_ALL\"]]}]","C":"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a","witness":"{\"signatures\":[\"b2077717cfe43086582679ce3fbe1802f9b8652f93828c2e1a75b9e553c0ab66cd14b9c5f6c45a098375fe6583e106c7ccdb1421636daf893576e15815f3483f\",\"179f687c2236c3d0767f3b2af88478cad312e7f76183fb5781754494709334c578c7232dc57017d06b9130a406f8e3ece18245064cda4ef66808ed3ff68c933e\"]}"}],"outputs":[{"amount":0,"id":"009a1f293253e41e","B_":"028b708cfd03b38bdc0a561008119594106f0c563061ae3fbfc8981b5595fd4e2b"}]}"#; + + let multisig_melt: MeltRequest = serde_json::from_str(multisig_melt).unwrap(); + + let msg_to_sign = multisig_melt.sig_all_msg_to_sign(); + + assert_eq!( + msg_to_sign, + r#"["P2PK",{"nonce":"1d0db9cbd2aa7370a3d6e0e3ce5714758ed7a085e2f8da9814924100e1fc622e","data":"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a","tags":[["pubkeys","026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a","03142715675faf8da1ecc4d51e0b9e539fa0d52fdd96ed60dbe99adb15d6b05ad9"],["n_sigs","2"],["sigflag","SIG_ALL"]]}]028b708cfd03b38bdc0a561008119594106f0c563061ae3fbfc8981b5595fd4e2b2fc40ad3-2f6a-4a7e-91fb-b8c2b5dc2bf7"# + ); + } + + #[test] + fn test_sig_all_melt_multi_sig() { + // MeltRequest with multi-sig SIG_ALL requiring 2 signatures + let multisig_melt = r#"{"quote":"2fc40ad3-2f6a-4a7e-91fb-b8c2b5dc2bf7","inputs":[{"amount":0,"id":"009a1f293253e41e","secret":"[\"P2PK\",{\"nonce\":\"1d0db9cbd2aa7370a3d6e0e3ce5714758ed7a085e2f8da9814924100e1fc622e\",\"data\":\"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a\",\"tags\":[[\"pubkeys\",\"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a\",\"03142715675faf8da1ecc4d51e0b9e539fa0d52fdd96ed60dbe99adb15d6b05ad9\"],[\"n_sigs\",\"2\"],[\"sigflag\",\"SIG_ALL\"]]}]","C":"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a","witness":"{\"signatures\":[\"b2077717cfe43086582679ce3fbe1802f9b8652f93828c2e1a75b9e553c0ab66cd14b9c5f6c45a098375fe6583e106c7ccdb1421636daf893576e15815f3483f\",\"179f687c2236c3d0767f3b2af88478cad312e7f76183fb5781754494709334c578c7232dc57017d06b9130a406f8e3ece18245064cda4ef66808ed3ff68c933e\"]}"}],"outputs":[{"amount":0,"id":"009a1f293253e41e","B_":"028b708cfd03b38bdc0a561008119594106f0c563061ae3fbfc8981b5595fd4e2b"}]}"#; + + let multisig_melt: MeltRequest = serde_json::from_str(multisig_melt).unwrap(); + assert!( + multisig_melt.verify_sig_all().is_ok(), + "Multi-sig SIG_ALL melt request should verify with both signatures" + ); + + // MeltRequest with insufficient signatures for multi-sig SIG_ALL + let insufficient_sigs_melt = r#"{ + "inputs": [{ + "amount": 1, + "secret": "[\"P2PK\",{\"nonce\":\"859d4935c4907062a6297cf4e663e2835d90d97ecdd510745d32f6816323a41f\",\"data\":\"0249098aa8b9d2fbec49ff8598feb17b592b986e62319a4fa488a3dc36387157a7\",\"tags\":[[\"sigflag\",\"SIG_ALL\"],[\"pubkeys\",\"0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798\",\"02142715675faf8da1ecc4d51e0b9e539fa0d52fdd96ed60dbe99adb15d6b05ad9\"],[\"n_sigs\",\"2\"]]}]", + "C": "02698c4e2b5f9534cd0687d87513c759790cf829aa5739184a3e3735471fbda904", + "id": "009a1f293253e41e", + "witness": "{\"signatures\":[\"83564aca48c668f50d022a426ce0ed19d3a9bdcffeeaee0dc1e7ea7e98e9eff1840fcc821724f623468c94f72a8b0a7280fa9ef5a54a1b130ef3055217f467b3\"]}" + }], + "quote": "test_quote_123", + "outputs": null + }"#; + + let insufficient_sigs_melt: MeltRequest = + serde_json::from_str(insufficient_sigs_melt).unwrap(); + assert!( + insufficient_sigs_melt.verify_sig_all().is_err(), + "Multi-sig SIG_ALL melt request should fail with insufficient signatures" + ); + } + + // Helper functions for tests + fn create_test_keys() -> (SecretKey, PublicKey) { + let secret_key = + SecretKey::from_str("99590802251e78ee1051648439eedb003dc539093a48a44e7b8f2642c909ea37") + .unwrap(); + let pubkey = secret_key.public_key(); + (secret_key, pubkey) + } + + #[test] + fn test_sig_all_basic_signing_verification() { + let (secret_key, pubkey) = create_test_keys(); + + // Create basic SIG_ALL conditions + let conditions = Conditions { + sig_flag: SigFlag::SigAll, + ..Default::default() + }; + + let secret = create_test_secret(pubkey, conditions); + let proof1 = create_test_proof(secret.clone(), pubkey, "009a1f293253e41e"); + let proof2 = create_test_proof(secret, pubkey, "009a1f293253e41f"); + let blinded_msg = create_test_blinded_msg(pubkey); + + // Test basic signing flow + let mut swap = SwapRequest::new(vec![proof1, proof2], vec![blinded_msg]); + assert!( + swap.verify_sig_all().is_err(), + "Unsigned swap should fail verification" + ); + + assert!( + swap.sign_sig_all(secret_key).is_ok(), + "Signing should succeed" + ); + + println!("{}", serde_json::to_string(&swap).unwrap()); + + assert!( + swap.verify_sig_all().is_ok(), + "Signed swap should pass verification" + ); + } + + #[test] + fn test_sig_all_unauthorized_key() { + let (_secret_key, pubkey) = create_test_keys(); + + let conditions = Conditions { + sig_flag: SigFlag::SigAll, + ..Default::default() + }; + + let secret = create_test_secret(pubkey, conditions); + let proof = create_test_proof(secret, pubkey, "009a1f293253e41e"); + let blinded_msg = create_test_blinded_msg(pubkey); + + // Create unauthorized key + let unauthorized_key = + SecretKey::from_str("0000000000000000000000000000000000000000000000000000000000000001") + .unwrap(); + + let mut swap = SwapRequest::new(vec![proof], vec![blinded_msg]); + assert!( + swap.sign_sig_all(unauthorized_key).is_err(), + "Signing with unauthorized key should fail" + ); + } + + #[test] + fn test_sig_all_mismatched_secrets() { + let (secret_key, pubkey) = create_test_keys(); + + let conditions = Conditions { + sig_flag: SigFlag::SigAll, + ..Default::default() + }; + + // Create first proof with original secret + let secret1 = create_test_secret(pubkey, conditions.clone()); + + // Create second proof with different secret data + let different_secret = Nut10Secret::new( + Kind::P2PK, + "02698c4e2b5f9534cd0687d87513c759790cf829aa5739184a3e3735471fbda904", + Some(conditions), + ) + .try_into() + .unwrap(); + + let proof1 = create_test_proof(secret1, pubkey, "009a1f293253e41e"); + let proof2 = create_test_proof(different_secret, pubkey, "009a1f293253e41f"); + let blinded_msg = create_test_blinded_msg(pubkey); + + let mut swap = SwapRequest::new(vec![proof1, proof2], vec![blinded_msg]); + assert!( + swap.sign_sig_all(secret_key).is_err(), + "Signing with mismatched secrets should fail" + ); + } + + #[test] + fn test_sig_all_wrong_flag() { + let (secret_key, pubkey) = create_test_keys(); + + // Create conditions with SIG_INPUTS instead of SIG_ALL + let sig_inputs_conditions = Conditions { + sig_flag: SigFlag::SigInputs, + ..Default::default() + }; + + let secret = create_test_secret(pubkey, sig_inputs_conditions); + let proof = create_test_proof(secret, pubkey, "009a1f293253e41e"); + let blinded_msg = create_test_blinded_msg(pubkey); + + let mut swap = SwapRequest::new(vec![proof], vec![blinded_msg]); + assert!( + swap.sign_sig_all(secret_key).is_err(), + "Signing with SIG_INPUTS flag should fail" + ); + } + + #[test] + fn test_sig_all_multiple_signatures() { + let (secret_key1, pubkey1) = create_test_keys(); + let secret_key2 = + SecretKey::from_str("7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f") + .unwrap(); + let pubkey2 = secret_key2.public_key(); + + // Create conditions requiring 2 signatures + let conditions = Conditions { + num_sigs: Some(2), + sig_flag: SigFlag::SigAll, + pubkeys: Some(vec![pubkey2]), + ..Default::default() + }; + + let secret = create_test_secret(pubkey1, conditions); + let proof = create_test_proof(secret, pubkey1, "009a1f293253e41e"); + let blinded_msg = create_test_blinded_msg(pubkey1); + + let mut swap = SwapRequest::new(vec![proof], vec![blinded_msg]); + + // Sign with first key + assert!( + swap.sign_sig_all(secret_key1).is_ok(), + "First signature should succeed" + ); + assert!( + swap.verify_sig_all().is_err(), + "Single signature should not verify when two required" + ); + + // Sign with second key + assert!( + swap.sign_sig_all(secret_key2).is_ok(), + "Second signature should succeed" + ); + + assert!( + swap.verify_sig_all().is_ok(), + "Both signatures should verify" + ); + } +} // End of tests module diff --git a/crates/cdk/src/mint/melt.rs b/crates/cdk/src/mint/melt.rs index f01fa5b7e..2f6c2c5e2 100644 --- a/crates/cdk/src/mint/melt.rs +++ b/crates/cdk/src/mint/melt.rs @@ -498,7 +498,9 @@ impl Mint { let EnforceSigFlag { sig_flag, .. } = enforce_sig_flag(melt_request.inputs().clone()); - ensure_cdk!(sig_flag.ne(&SigFlag::SigAll), Error::SigAllUsedInMelt); + if sig_flag == SigFlag::SigAll { + melt_request.verify_sig_all()?; + } if let Some(outputs) = &melt_request.outputs() { if !outputs.is_empty() { diff --git a/crates/cdk/src/mint/swap.rs b/crates/cdk/src/mint/swap.rs index ab2648288..0701fbbae 100644 --- a/crates/cdk/src/mint/swap.rs +++ b/crates/cdk/src/mint/swap.rs @@ -59,20 +59,10 @@ impl Mint { } async fn validate_sig_flag(&self, swap_request: &SwapRequest) -> Result<(), Error> { - let EnforceSigFlag { - sig_flag, - pubkeys, - sigs_required, - } = enforce_sig_flag(swap_request.inputs().clone()); + let EnforceSigFlag { sig_flag, .. } = enforce_sig_flag(swap_request.inputs().clone()); - if sig_flag.eq(&SigFlag::SigAll) { - let pubkeys = pubkeys.into_iter().collect(); - for blinded_message in swap_request.outputs() { - if let Err(err) = blinded_message.verify_p2pk(&pubkeys, sigs_required) { - tracing::info!("Could not verify p2pk in swap request"); - return Err(err.into()); - } - } + if sig_flag == SigFlag::SigAll { + swap_request.verify_sig_all()?; } Ok(()) From 29a2866326df47b3eb9c472c2c5eb815205a7af4 Mon Sep 17 00:00:00 2001 From: codingpeanut157 Date: Mon, 28 Jul 2025 12:16:47 +0200 Subject: [PATCH 035/321] TransactionId::from_hex check bytes len before copy_from_slice avoid panicking when the input does not convert to an [u8;32] byte array --- crates/cdk-common/src/wallet.rs | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/crates/cdk-common/src/wallet.rs b/crates/cdk-common/src/wallet.rs index d9aca538b..7359d730f 100644 --- a/crates/cdk-common/src/wallet.rs +++ b/crates/cdk-common/src/wallet.rs @@ -310,6 +310,9 @@ impl TransactionId { /// From hex string pub fn from_hex(value: &str) -> Result { let bytes = hex::decode(value)?; + if bytes.len() != 32 { + return Err(Error::InvalidTransactionId); + } let mut array = [0u8; 32]; array.copy_from_slice(&bytes); Ok(Self(array)) @@ -357,3 +360,29 @@ impl TryFrom for TransactionId { Self::from_proofs(proofs) } } + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn test_transaction_id_from_hex() { + let hex_str = "a1b2c3d4e5f60718293a0b1c2d3e4f506172839a0b1c2d3e4f506172839a0b1c"; + let transaction_id = TransactionId::from_hex(hex_str).unwrap(); + assert_eq!(transaction_id.to_string(), hex_str); + } + + #[test] + fn test_transaction_id_from_hex_empty_string() { + let hex_str = ""; + let res = TransactionId::from_hex(hex_str); + assert!(matches!(res, Err(Error::InvalidTransactionId))); + } + + #[test] + fn test_transaction_id_from_hex_longer_string() { + let hex_str = "a1b2c3d4e5f60718293a0b1c2d3e4f506172839a0b1c2d3e4f506172839a0b1ca1b2"; + let res = TransactionId::from_hex(hex_str); + assert!(matches!(res, Err(Error::InvalidTransactionId))); + } +} From d14cfff8b84384e4b8568f68c73a8aa13d23bf9d Mon Sep 17 00:00:00 2001 From: Cesar Rodas Date: Mon, 28 Jul 2025 22:25:36 -0300 Subject: [PATCH 036/321] Fix `get_mint_quote_by_request_lookup_id` Fixes #916 The two functions (read and transaction) got out of sync --- crates/cdk-sqlite/src/mint/mod.rs | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/crates/cdk-sqlite/src/mint/mod.rs b/crates/cdk-sqlite/src/mint/mod.rs index c2cf5796f..b0251b04b 100644 --- a/crates/cdk-sqlite/src/mint/mod.rs +++ b/crates/cdk-sqlite/src/mint/mod.rs @@ -414,7 +414,7 @@ impl<'a> MintQuotesTransaction<'a> for SqliteTransaction<'a> { // Get current amount_paid from quote let current_amount = query( r#" - SELECT amount_paid + SELECT amount_paid FROM mint_quote WHERE id = :quote_id "#, @@ -442,8 +442,8 @@ impl<'a> MintQuotesTransaction<'a> for SqliteTransaction<'a> { // Update the amount_paid query( r#" - UPDATE mint_quote - SET amount_paid = :amount_paid + UPDATE mint_quote + SET amount_paid = :amount_paid WHERE id = :quote_id "#, ) @@ -487,7 +487,7 @@ impl<'a> MintQuotesTransaction<'a> for SqliteTransaction<'a> { // Get current amount_issued from quote let current_amount = query( r#" - SELECT amount_issued + SELECT amount_issued FROM mint_quote WHERE id = :quote_id "#, @@ -515,8 +515,8 @@ impl<'a> MintQuotesTransaction<'a> for SqliteTransaction<'a> { // Update the amount_issued query( r#" - UPDATE mint_quote - SET amount_issued = :amount_issued + UPDATE mint_quote + SET amount_issued = :amount_issued WHERE id = :quote_id "#, ) @@ -593,8 +593,8 @@ VALUES (:quote_id, :amount, :timestamp); let current_time = unix_time(); let row_affected = query( r#" - DELETE FROM melt_quote - WHERE request_lookup_id = :request_lookup_id + DELETE FROM melt_quote + WHERE request_lookup_id = :request_lookup_id AND state = :state AND expiry < :current_time "#, @@ -781,7 +781,7 @@ VALUES (:quote_id, :amount, :timestamp); ) -> Result, Self::Err> { Ok(query( r#" - SELECT + SELECT id, unit, amount, @@ -985,12 +985,12 @@ impl MintQuotesDatabase for MintSqliteDatabase { request_lookup_id_kind FROM mint_quote - WHERE request_lookup_id = :request_lookup_id"#, - ) - .bind( - ":request_lookup_id", - serde_json::to_string(request_lookup_id)?, + WHERE request_lookup_id = :request_lookup_id + AND request_lookup_id_kind = :request_lookup_id_kind + "#, ) + .bind(":request_lookup_id", request_lookup_id.to_string()) + .bind(":request_lookup_id_kind", request_lookup_id.kind()) .fetch_one(&self.pool) .await? .map(|row| sqlite_row_to_mint_quote(row, vec![], vec![])) @@ -1077,7 +1077,7 @@ impl MintQuotesDatabase for MintSqliteDatabase { async fn get_melt_quotes(&self) -> Result, Self::Err> { Ok(query( r#" - SELECT + SELECT id, unit, amount, From 349c773406ce758ebc7df428ac1781ac4777d156 Mon Sep 17 00:00:00 2001 From: Cesar Rodas Date: Tue, 15 Jul 2025 12:17:25 +0200 Subject: [PATCH 037/321] Introduce `cdk-sql-common` 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 --- Cargo.toml | 1 + crates/cdk-cli/src/main.rs | 2 +- crates/cdk-common/src/database/mod.rs | 109 + .../src/init_pure_tests.rs | 4 +- crates/cdk-mintd/src/main.rs | 4 +- crates/cdk-signatory/src/bin/cli/mod.rs | 2 +- crates/cdk-sql-common/Cargo.toml | 30 + crates/cdk-sql-common/README.md | 24 + .../{cdk-sqlite => cdk-sql-common}/build.rs | 11 +- crates/cdk-sql-common/src/common.rs | 46 + crates/cdk-sql-common/src/database.rs | 53 + crates/cdk-sql-common/src/lib.rs | 23 + .../src/macros.rs | 86 +- .../src/mint/auth/migrations.rs | 5 + .../sqlite}/20250109143347_init.sql | 0 .../src/mint/auth/mod.rs | 193 +- crates/cdk-sql-common/src/mint/migrations.rs | 26 + .../sqlite/1_fix_sqlx_migration.sql | 20 + .../sqlite}/20240612124932_init.sql | 0 .../sqlite}/20240618195700_quote_state.sql | 0 .../sqlite}/20240626092101_nut04_state.sql | 0 .../20240703122347_request_lookup_id.sql | 0 .../sqlite}/20240710145043_input_fee.sql | 0 .../20240711183109_derivation_path_index.sql | 0 .../sqlite}/20240718203721_allow_unspent.sql | 0 .../20240811031111_update_mint_url.sql | 0 .../20240919103407_proofs_quote_id.sql | 0 .../sqlite}/20240923153640_melt_requests.sql | 0 .../sqlite}/20240930101140_dleq_for_sigs.sql | 0 .../20241108093102_mint_mint_quote_pubkey.sql | 0 .../20250103201327_amount_to_pay_msats.sql | 0 .../20250129200912_remove_mint_url.sql | 0 .../20250129230326_add_config_table.sql | 0 ...0250307213652_keyset_id_as_foreign_key.sql | 2 +- .../20250406091754_mint_time_of_quotes.sql | 0 ...0406093755_mint_created_time_signature.sql | 0 .../20250415093121_drop_keystore_foreign.sql | 0 ...0626120251_rename_blind_message_y_to_b.sql | 0 .../sqlite}/20250706101057_bolt12.sql | 0 crates/cdk-sql-common/src/mint/mod.rs | 1796 +++++++++++++++ .../src/pool.rs | 42 +- crates/cdk-sql-common/src/stmt.rs | 292 +++ crates/cdk-sql-common/src/value.rs | 82 + .../src/wallet/error.rs | 2 +- .../cdk-sql-common/src/wallet/migrations.rs | 21 + .../sqlite}/20240612132920_init.sql | 0 .../sqlite}/20240618200350_quote_state.sql | 0 .../sqlite}/20240626091921_nut04_state.sql | 0 .../sqlite}/20240710144711_input_fee.sql | 0 .../sqlite}/20240810214105_mint_icon_url.sql | 0 .../20240810233905_update_mint_url.sql | 0 .../sqlite}/20240902151515_icon_url.sql | 0 .../sqlite}/20240902210905_mint_time.sql | 0 .../sqlite}/20241011125207_mint_urls.sql | 0 ...1108092756_wallet_mint_quote_secretkey.sql | 0 .../sqlite}/20250214135017_mint_tos.sql | 0 ...20250310111513_drop_nostr_last_checked.sql | 0 .../20250314082116_allow_pending_spent.sql | 0 .../20250323152040_wallet_dleq_proofs.sql | 0 .../20250401120000_add_transactions_table.sql | 0 .../20250616144830_add_keyset_expiry.sql | 0 .../sqlite}/20250707093445_bolt12.sql | 0 crates/cdk-sql-common/src/wallet/mod.rs | 1122 +++++++++ crates/cdk-sql-common/tests/legacy-sqlx.sql | 97 + crates/cdk-sqlite/Cargo.toml | 9 +- crates/cdk-sqlite/src/common.rs | 85 +- crates/cdk-sqlite/src/lib.rs | 3 - crates/cdk-sqlite/src/mint/async_rusqlite.rs | 500 ++-- crates/cdk-sqlite/src/mint/auth/migrations.rs | 5 - crates/cdk-sqlite/src/mint/error.rs | 116 - crates/cdk-sqlite/src/mint/memory.rs | 7 +- crates/cdk-sqlite/src/mint/migrations.rs | 25 - crates/cdk-sqlite/src/mint/mod.rs | 2014 +---------------- crates/cdk-sqlite/src/stmt.rs | 184 -- crates/cdk-sqlite/src/wallet/memory.rs | 8 +- crates/cdk-sqlite/src/wallet/migrations.rs | 21 - crates/cdk-sqlite/src/wallet/mod.rs | 1229 ++-------- crates/cdk-sqlite/tests/legacy-sqlx.sql | 2 +- 78 files changed, 4470 insertions(+), 3833 deletions(-) create mode 100644 crates/cdk-sql-common/Cargo.toml create mode 100644 crates/cdk-sql-common/README.md rename crates/{cdk-sqlite => cdk-sql-common}/build.rs (82%) create mode 100644 crates/cdk-sql-common/src/common.rs create mode 100644 crates/cdk-sql-common/src/database.rs create mode 100644 crates/cdk-sql-common/src/lib.rs rename crates/{cdk-sqlite => cdk-sql-common}/src/macros.rs (62%) create mode 100644 crates/cdk-sql-common/src/mint/auth/migrations.rs rename crates/{cdk-sqlite/src/mint/auth/migrations => cdk-sql-common/src/mint/auth/migrations/sqlite}/20250109143347_init.sql (100%) rename crates/{cdk-sqlite => cdk-sql-common}/src/mint/auth/mod.rs (72%) create mode 100644 crates/cdk-sql-common/src/mint/migrations.rs create mode 100644 crates/cdk-sql-common/src/mint/migrations/sqlite/1_fix_sqlx_migration.sql rename crates/{cdk-sqlite/src/mint/migrations => cdk-sql-common/src/mint/migrations/sqlite}/20240612124932_init.sql (100%) rename crates/{cdk-sqlite/src/mint/migrations => cdk-sql-common/src/mint/migrations/sqlite}/20240618195700_quote_state.sql (100%) rename crates/{cdk-sqlite/src/mint/migrations => cdk-sql-common/src/mint/migrations/sqlite}/20240626092101_nut04_state.sql (100%) rename crates/{cdk-sqlite/src/mint/migrations => cdk-sql-common/src/mint/migrations/sqlite}/20240703122347_request_lookup_id.sql (100%) rename crates/{cdk-sqlite/src/mint/migrations => cdk-sql-common/src/mint/migrations/sqlite}/20240710145043_input_fee.sql (100%) rename crates/{cdk-sqlite/src/mint/migrations => cdk-sql-common/src/mint/migrations/sqlite}/20240711183109_derivation_path_index.sql (100%) rename crates/{cdk-sqlite/src/mint/migrations => cdk-sql-common/src/mint/migrations/sqlite}/20240718203721_allow_unspent.sql (100%) rename crates/{cdk-sqlite/src/mint/migrations => cdk-sql-common/src/mint/migrations/sqlite}/20240811031111_update_mint_url.sql (100%) rename crates/{cdk-sqlite/src/mint/migrations => cdk-sql-common/src/mint/migrations/sqlite}/20240919103407_proofs_quote_id.sql (100%) rename crates/{cdk-sqlite/src/mint/migrations => cdk-sql-common/src/mint/migrations/sqlite}/20240923153640_melt_requests.sql (100%) rename crates/{cdk-sqlite/src/mint/migrations => cdk-sql-common/src/mint/migrations/sqlite}/20240930101140_dleq_for_sigs.sql (100%) rename crates/{cdk-sqlite/src/mint/migrations => cdk-sql-common/src/mint/migrations/sqlite}/20241108093102_mint_mint_quote_pubkey.sql (100%) rename crates/{cdk-sqlite/src/mint/migrations => cdk-sql-common/src/mint/migrations/sqlite}/20250103201327_amount_to_pay_msats.sql (100%) rename crates/{cdk-sqlite/src/mint/migrations => cdk-sql-common/src/mint/migrations/sqlite}/20250129200912_remove_mint_url.sql (100%) rename crates/{cdk-sqlite/src/mint/migrations => cdk-sql-common/src/mint/migrations/sqlite}/20250129230326_add_config_table.sql (100%) rename crates/{cdk-sqlite/src/mint/migrations => cdk-sql-common/src/mint/migrations/sqlite}/20250307213652_keyset_id_as_foreign_key.sql (96%) rename crates/{cdk-sqlite/src/mint/migrations => cdk-sql-common/src/mint/migrations/sqlite}/20250406091754_mint_time_of_quotes.sql (100%) rename crates/{cdk-sqlite/src/mint/migrations => cdk-sql-common/src/mint/migrations/sqlite}/20250406093755_mint_created_time_signature.sql (100%) rename crates/{cdk-sqlite/src/mint/migrations => cdk-sql-common/src/mint/migrations/sqlite}/20250415093121_drop_keystore_foreign.sql (100%) rename crates/{cdk-sqlite/src/mint/migrations => cdk-sql-common/src/mint/migrations/sqlite}/20250626120251_rename_blind_message_y_to_b.sql (100%) rename crates/{cdk-sqlite/src/mint/migrations => cdk-sql-common/src/mint/migrations/sqlite}/20250706101057_bolt12.sql (100%) create mode 100644 crates/cdk-sql-common/src/mint/mod.rs rename crates/{cdk-sqlite => cdk-sql-common}/src/pool.rs (79%) create mode 100644 crates/cdk-sql-common/src/stmt.rs create mode 100644 crates/cdk-sql-common/src/value.rs rename crates/{cdk-sqlite => cdk-sql-common}/src/wallet/error.rs (98%) create mode 100644 crates/cdk-sql-common/src/wallet/migrations.rs rename crates/{cdk-sqlite/src/wallet/migrations => cdk-sql-common/src/wallet/migrations/sqlite}/20240612132920_init.sql (100%) rename crates/{cdk-sqlite/src/wallet/migrations => cdk-sql-common/src/wallet/migrations/sqlite}/20240618200350_quote_state.sql (100%) rename crates/{cdk-sqlite/src/wallet/migrations => cdk-sql-common/src/wallet/migrations/sqlite}/20240626091921_nut04_state.sql (100%) rename crates/{cdk-sqlite/src/wallet/migrations => cdk-sql-common/src/wallet/migrations/sqlite}/20240710144711_input_fee.sql (100%) rename crates/{cdk-sqlite/src/wallet/migrations => cdk-sql-common/src/wallet/migrations/sqlite}/20240810214105_mint_icon_url.sql (100%) rename crates/{cdk-sqlite/src/wallet/migrations => cdk-sql-common/src/wallet/migrations/sqlite}/20240810233905_update_mint_url.sql (100%) rename crates/{cdk-sqlite/src/wallet/migrations => cdk-sql-common/src/wallet/migrations/sqlite}/20240902151515_icon_url.sql (100%) rename crates/{cdk-sqlite/src/wallet/migrations => cdk-sql-common/src/wallet/migrations/sqlite}/20240902210905_mint_time.sql (100%) rename crates/{cdk-sqlite/src/wallet/migrations => cdk-sql-common/src/wallet/migrations/sqlite}/20241011125207_mint_urls.sql (100%) rename crates/{cdk-sqlite/src/wallet/migrations => cdk-sql-common/src/wallet/migrations/sqlite}/20241108092756_wallet_mint_quote_secretkey.sql (100%) rename crates/{cdk-sqlite/src/wallet/migrations => cdk-sql-common/src/wallet/migrations/sqlite}/20250214135017_mint_tos.sql (100%) rename crates/{cdk-sqlite/src/wallet/migrations => cdk-sql-common/src/wallet/migrations/sqlite}/20250310111513_drop_nostr_last_checked.sql (100%) rename crates/{cdk-sqlite/src/wallet/migrations => cdk-sql-common/src/wallet/migrations/sqlite}/20250314082116_allow_pending_spent.sql (100%) rename crates/{cdk-sqlite/src/wallet/migrations => cdk-sql-common/src/wallet/migrations/sqlite}/20250323152040_wallet_dleq_proofs.sql (100%) rename crates/{cdk-sqlite/src/wallet/migrations => cdk-sql-common/src/wallet/migrations/sqlite}/20250401120000_add_transactions_table.sql (100%) rename crates/{cdk-sqlite/src/wallet/migrations => cdk-sql-common/src/wallet/migrations/sqlite}/20250616144830_add_keyset_expiry.sql (100%) rename crates/{cdk-sqlite/src/wallet/migrations => cdk-sql-common/src/wallet/migrations/sqlite}/20250707093445_bolt12.sql (100%) create mode 100644 crates/cdk-sql-common/src/wallet/mod.rs create mode 100644 crates/cdk-sql-common/tests/legacy-sqlx.sql delete mode 100644 crates/cdk-sqlite/src/mint/auth/migrations.rs delete mode 100644 crates/cdk-sqlite/src/mint/error.rs delete mode 100644 crates/cdk-sqlite/src/mint/migrations.rs delete mode 100644 crates/cdk-sqlite/src/stmt.rs delete mode 100644 crates/cdk-sqlite/src/wallet/migrations.rs diff --git a/Cargo.toml b/Cargo.toml index 02418387d..527ee25a1 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -54,6 +54,7 @@ cdk-fake-wallet = { path = "./crates/cdk-fake-wallet", version = "=0.11.0" } cdk-payment-processor = { path = "./crates/cdk-payment-processor", default-features = true, version = "=0.11.0" } cdk-mint-rpc = { path = "./crates/cdk-mint-rpc", version = "=0.11.0" } cdk-redb = { path = "./crates/cdk-redb", default-features = true, version = "=0.11.0" } +cdk-sql-common = { path = "./crates/cdk-sql-common", default-features = true, version = "=0.11.0" } cdk-sqlite = { path = "./crates/cdk-sqlite", default-features = true, version = "=0.11.0" } cdk-signatory = { path = "./crates/cdk-signatory", version = "=0.11.0", default-features = false } clap = { version = "4.5.31", features = ["derive"] } diff --git a/crates/cdk-cli/src/main.rs b/crates/cdk-cli/src/main.rs index 7eb554b5a..11b4297bb 100644 --- a/crates/cdk-cli/src/main.rs +++ b/crates/cdk-cli/src/main.rs @@ -128,7 +128,7 @@ async fn main() -> Result<()> { #[cfg(feature = "sqlcipher")] let sql = { match args.password { - Some(pass) => WalletSqliteDatabase::new(&sql_path, pass).await?, + Some(pass) => WalletSqliteDatabase::new((sql_path, pass)).await?, None => bail!("Missing database password"), } }; diff --git a/crates/cdk-common/src/database/mod.rs b/crates/cdk-common/src/database/mod.rs index 195e210ba..ccf13797e 100644 --- a/crates/cdk-common/src/database/mod.rs +++ b/crates/cdk-common/src/database/mod.rs @@ -19,6 +19,80 @@ pub use mint::{MintAuthDatabase, MintAuthTransaction}; #[cfg(feature = "wallet")] pub use wallet::Database as WalletDatabase; +/// Data conversion error +#[derive(thiserror::Error, Debug)] +pub enum ConversionError { + /// Missing columns + #[error("Not enough elements: expected {0}, got {1}")] + MissingColumn(usize, usize), + + /// Missing parameter + #[error("Missing parameter {0}")] + MissingParameter(String), + + /// Invalid db type + #[error("Invalid type from db, expected {0} got {1}")] + InvalidType(String, String), + + /// Invalid data conversion in column + #[error("Error converting {1}, expecting type {0}")] + InvalidConversion(String, String), + + /// Mint Url Error + #[error(transparent)] + MintUrl(#[from] crate::mint_url::Error), + + /// NUT00 Error + #[error(transparent)] + CDKNUT00(#[from] crate::nuts::nut00::Error), + + /// NUT01 Error + #[error(transparent)] + CDKNUT01(#[from] crate::nuts::nut01::Error), + + /// NUT02 Error + #[error(transparent)] + CDKNUT02(#[from] crate::nuts::nut02::Error), + + /// NUT04 Error + #[error(transparent)] + CDKNUT04(#[from] crate::nuts::nut04::Error), + + /// NUT05 Error + #[error(transparent)] + CDKNUT05(#[from] crate::nuts::nut05::Error), + + /// NUT07 Error + #[error(transparent)] + CDKNUT07(#[from] crate::nuts::nut07::Error), + + /// NUT23 Error + #[error(transparent)] + CDKNUT23(#[from] crate::nuts::nut23::Error), + + /// Secret Error + #[error(transparent)] + CDKSECRET(#[from] crate::secret::Error), + + /// Serde Error + #[error(transparent)] + Serde(#[from] serde_json::Error), + + /// BIP32 Error + #[error(transparent)] + BIP32(#[from] bitcoin::bip32::Error), + + /// Generic error + #[error(transparent)] + Generic(#[from] Box), +} + +impl From for ConversionError { + fn from(err: crate::Error) -> Self { + ConversionError::Generic(Box::new(err)) + } +} + /// CDK_database error #[derive(Debug, thiserror::Error)] pub enum Error { @@ -39,6 +113,9 @@ pub enum Error { /// NUT00 Error #[error(transparent)] NUT00(#[from] crate::nuts::nut00::Error), + /// NUT01 Error + #[error(transparent)] + NUT01(#[from] crate::nuts::nut01::Error), /// NUT02 Error #[error(transparent)] NUT02(#[from] crate::nuts::nut02::Error), @@ -68,6 +145,38 @@ pub enum Error { /// Invalid state transition #[error("Invalid state transition")] InvalidStateTransition(crate::state::Error), + + /// Invalid connection settings + #[error("Invalid credentials {0}")] + InvalidConnectionSettings(String), + + /// Unexpected database response + #[error("Invalid database response")] + InvalidDbResponse, + + /// Internal error + #[error("Internal {0}")] + Internal(String), + + /// Data conversion error + #[error(transparent)] + Conversion(#[from] ConversionError), + + /// Missing Placeholder value + #[error("Missing placeholder value {0}")] + MissingPlaceholder(String), + + /// Unknown quote ttl + #[error("Unknown quote ttl")] + UnknownQuoteTTL, + + /// Invalid UUID + #[error("Invalid UUID: {0}")] + InvalidUuid(String), + + /// QuoteNotFound + #[error("Quote not found")] + QuoteNotFound, } #[cfg(feature = "mint")] diff --git a/crates/cdk-integration-tests/src/init_pure_tests.rs b/crates/cdk-integration-tests/src/init_pure_tests.rs index f55e1d1d4..853dddb18 100644 --- a/crates/cdk-integration-tests/src/init_pure_tests.rs +++ b/crates/cdk-integration-tests/src/init_pure_tests.rs @@ -234,7 +234,7 @@ pub async fn create_and_start_test_mint() -> Result { let temp_dir = create_temp_dir("cdk-test-sqlite-mint")?; let path = temp_dir.join("mint.db").to_str().unwrap().to_string(); Arc::new( - cdk_sqlite::MintSqliteDatabase::new(&path) + cdk_sqlite::MintSqliteDatabase::new(path.as_str()) .await .expect("Could not create sqlite db"), ) @@ -310,7 +310,7 @@ pub async fn create_test_wallet_for_mint(mint: Mint) -> Result { // Create a temporary directory for SQLite database let temp_dir = create_temp_dir("cdk-test-sqlite-wallet")?; let path = temp_dir.join("wallet.db").to_str().unwrap().to_string(); - let database = cdk_sqlite::WalletSqliteDatabase::new(&path) + let database = cdk_sqlite::WalletSqliteDatabase::new(path.as_str()) .await .expect("Could not create sqlite db"); Arc::new(database) diff --git a/crates/cdk-mintd/src/main.rs b/crates/cdk-mintd/src/main.rs index 59cbe46b8..7c270043f 100644 --- a/crates/cdk-mintd/src/main.rs +++ b/crates/cdk-mintd/src/main.rs @@ -211,7 +211,7 @@ async fn setup_sqlite_database( #[cfg(feature = "sqlcipher")] let db = { // Get password from command line arguments for sqlcipher - MintSqliteDatabase::new(&sql_db_path, _password.unwrap()).await? + MintSqliteDatabase::new((sql_db_path, _password.unwrap())).await? }; Ok(Arc::new(db)) } @@ -486,7 +486,7 @@ async fn setup_authentication( #[cfg(feature = "sqlcipher")] let password = CLIArgs::parse().password; #[cfg(feature = "sqlcipher")] - let sqlite_db = MintSqliteAuthDatabase::new(&sql_db_path, password).await?; + let sqlite_db = MintSqliteAuthDatabase::new((sql_db_path, password)).await?; #[cfg(not(feature = "sqlcipher"))] let sqlite_db = MintSqliteAuthDatabase::new(&sql_db_path).await?; Arc::new(sqlite_db) diff --git a/crates/cdk-signatory/src/bin/cli/mod.rs b/crates/cdk-signatory/src/bin/cli/mod.rs index 1eed94265..b389b31c5 100644 --- a/crates/cdk-signatory/src/bin/cli/mod.rs +++ b/crates/cdk-signatory/src/bin/cli/mod.rs @@ -108,7 +108,7 @@ pub async fn cli_main() -> Result<()> { #[cfg(feature = "sqlcipher")] let db = { match args.password { - Some(pass) => MintSqliteDatabase::new(&sql_path, pass).await?, + Some(pass) => MintSqliteDatabase::new((&sql_path, pass)).await?, None => bail!("Missing database password"), } }; diff --git a/crates/cdk-sql-common/Cargo.toml b/crates/cdk-sql-common/Cargo.toml new file mode 100644 index 000000000..406e12fb4 --- /dev/null +++ b/crates/cdk-sql-common/Cargo.toml @@ -0,0 +1,30 @@ +[package] +name = "cdk-sql-common" +version.workspace = true +edition.workspace = true +authors = ["CDK Developers"] +description = "Generic SQL storage backend for CDK" +license.workspace = true +homepage = "https://github.com/cashubtc/cdk" +repository = "https://github.com/cashubtc/cdk.git" +rust-version.workspace = true # MSRV +readme = "README.md" + +# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html +[features] +default = ["mint", "wallet", "auth"] +mint = ["cdk-common/mint"] +wallet = ["cdk-common/wallet"] +auth = ["cdk-common/auth"] + +[dependencies] +async-trait.workspace = true +cdk-common = { workspace = true, features = ["test"] } +bitcoin.workspace = true +thiserror.workspace = true +tokio.workspace = true +tracing.workspace = true +serde.workspace = true +serde_json.workspace = true +lightning-invoice.workspace = true +uuid.workspace = true diff --git a/crates/cdk-sql-common/README.md b/crates/cdk-sql-common/README.md new file mode 100644 index 000000000..861923910 --- /dev/null +++ b/crates/cdk-sql-common/README.md @@ -0,0 +1,24 @@ +# CDK SQL Base + +This is a private crate offering a common framework to interact with SQL databases. + +This crate uses standard SQL, a generic migration framework a traits to implement blocking or +non-blocking clients. + + +**ALPHA** This library is in early development, the API will change and should be used with caution. + +## Features + +The following crate feature flags are available: + +| Feature | Default | Description | +|-------------|:-------:|------------------------------------| +| `wallet` | Yes | Enable cashu wallet features | +| `mint` | Yes | Enable cashu mint wallet features | +| `auth` | Yes | Enable cashu mint auth features | + + +## License + +This project is licensed under the [MIT License](../../LICENSE). diff --git a/crates/cdk-sqlite/build.rs b/crates/cdk-sql-common/build.rs similarity index 82% rename from crates/cdk-sqlite/build.rs rename to crates/cdk-sql-common/build.rs index 0891729a2..6b32a916b 100644 --- a/crates/cdk-sqlite/build.rs +++ b/crates/cdk-sql-common/build.rs @@ -18,18 +18,21 @@ fn main() { let dest_path = parent.join("migrations.rs"); let mut out_file = File::create(&dest_path).expect("Failed to create migrations.rs"); - writeln!(out_file, "// @generated").unwrap(); - writeln!(out_file, "// Auto-generated by build.rs").unwrap(); + let skip_name = migration_path.to_str().unwrap_or_default().len(); + + writeln!(out_file, "/// @generated").unwrap(); + writeln!(out_file, "/// Auto-generated by build.rs").unwrap(); writeln!(out_file, "pub static MIGRATIONS: &[(&str, &str)] = &[").unwrap(); for path in &files { - let name = path.file_name().unwrap().to_string_lossy(); + let rel_name = &path.to_str().unwrap().replace("\\", "/")[skip_name + 1..]; // for Windows let rel_path = &path.to_str().unwrap().replace("\\", "/")[skip_path..]; // for Windows writeln!( out_file, - " (\"{name}\", include_str!(r#\".{rel_path}\"#))," + " (\"{rel_name}\", include_str!(r#\".{rel_path}\"#))," ) .unwrap(); + println!("cargo:rerun-if-changed={}", path.display()); } writeln!(out_file, "];").unwrap(); diff --git a/crates/cdk-sql-common/src/common.rs b/crates/cdk-sql-common/src/common.rs new file mode 100644 index 000000000..b2962898a --- /dev/null +++ b/crates/cdk-sql-common/src/common.rs @@ -0,0 +1,46 @@ +use crate::database::DatabaseExecutor; +use crate::stmt::query; + +/// Migrates the migration generated by `build.rs` +#[inline(always)] +pub async fn migrate( + conn: &C, + db_prefix: &str, + migrations: &[(&str, &str)], +) -> Result<(), cdk_common::database::Error> { + query( + r#" + CREATE TABLE IF NOT EXISTS migrations ( + name TEXT PRIMARY KEY, + applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP + ) + "#, + )? + .execute(conn) + .await?; + + // Apply each migration if it hasn’t been applied yet + for (name, sql) in migrations { + if let Some((prefix, _)) = name.split_once(['/', '\\']) { + if prefix != db_prefix { + continue; + } + } + + let is_missing = query("SELECT name FROM migrations WHERE name = :name")? + .bind("name", name) + .pluck(conn) + .await? + .is_none(); + + if is_missing { + query(sql)?.batch(conn).await?; + query(r#"INSERT INTO migrations (name) VALUES (:name)"#)? + .bind("name", name) + .execute(conn) + .await?; + } + } + + Ok(()) +} diff --git a/crates/cdk-sql-common/src/database.rs b/crates/cdk-sql-common/src/database.rs new file mode 100644 index 000000000..06c63a34c --- /dev/null +++ b/crates/cdk-sql-common/src/database.rs @@ -0,0 +1,53 @@ +//! Database traits definition + +use std::fmt::Debug; + +use cdk_common::database::Error; + +use crate::stmt::{Column, Statement}; + +/// Database Executor +/// +/// This trait defines the expectations of a database execution +#[async_trait::async_trait] +pub trait DatabaseExecutor: Debug + Sync + Send { + /// Database driver name + fn name() -> &'static str; + + /// Executes a query and returns the affected rows + async fn execute(&self, statement: Statement) -> Result; + + /// Runs the query and returns the first row or None + async fn fetch_one(&self, statement: Statement) -> Result>, Error>; + + /// Runs the query and returns the first row or None + async fn fetch_all(&self, statement: Statement) -> Result>, Error>; + + /// Fetches the first row and column from a query + async fn pluck(&self, statement: Statement) -> Result, Error>; + + /// Batch execution + async fn batch(&self, statement: Statement) -> Result<(), Error>; +} + +/// Database transaction trait +#[async_trait::async_trait] +pub trait DatabaseTransaction<'a>: Debug + DatabaseExecutor + Send + Sync { + /// Consumes the current transaction committing the changes + async fn commit(self) -> Result<(), Error>; + + /// Consumes the transaction rolling back all changes + async fn rollback(self) -> Result<(), Error>; +} + +/// Database connector +#[async_trait::async_trait] +pub trait DatabaseConnector: Debug + DatabaseExecutor + Send + Sync { + /// Transaction type for this database connection + type Transaction<'a>: DatabaseTransaction<'a> + where + Self: 'a; + + /// Begin a new transaction + async fn begin(&self) -> Result, Error>; +} diff --git a/crates/cdk-sql-common/src/lib.rs b/crates/cdk-sql-common/src/lib.rs new file mode 100644 index 000000000..8c44b9a44 --- /dev/null +++ b/crates/cdk-sql-common/src/lib.rs @@ -0,0 +1,23 @@ +//! SQLite storage backend for cdk + +#![warn(missing_docs)] +#![warn(rustdoc::bare_urls)] + +mod common; +pub mod database; +mod macros; +pub mod pool; +pub mod stmt; +pub mod value; + +pub use cdk_common::database::ConversionError; + +#[cfg(feature = "mint")] +pub mod mint; +#[cfg(feature = "wallet")] +pub mod wallet; + +#[cfg(feature = "mint")] +pub use mint::SQLMintDatabase; +#[cfg(feature = "wallet")] +pub use wallet::SQLWalletDatabase; diff --git a/crates/cdk-sqlite/src/macros.rs b/crates/cdk-sql-common/src/macros.rs similarity index 62% rename from crates/cdk-sqlite/src/macros.rs rename to crates/cdk-sql-common/src/macros.rs index 7720d56be..094cb0980 100644 --- a/crates/cdk-sqlite/src/macros.rs +++ b/crates/cdk-sql-common/src/macros.rs @@ -1,4 +1,4 @@ -//! Collection of macros to generate code to digest data from SQLite +//! Collection of macros to generate code to digest data from a generic SQL databasex /// Unpacks a vector of Column, and consumes it, parsing into individual variables, checking the /// vector is big enough. @@ -10,9 +10,9 @@ macro_rules! unpack_into { vec.reverse(); let required = 0 $(+ {let _ = stringify!($var); 1})+; if vec.len() < required { - return Err(Error::MissingColumn(required, vec.len())); + Err($crate::ConversionError::MissingColumn(required, vec.len()))?; } - Ok::<_, Error>(( + Ok::<_, cdk_common::database::Error>(( $( vec.pop().expect(&format!("Checked length already for {}", stringify!($var))) ),+ @@ -21,7 +21,7 @@ macro_rules! unpack_into { }; } -/// Parses a SQLite column as a string or NULL +/// Parses a SQL column as a string or NULL #[macro_export] macro_rules! column_as_nullable_string { ($col:expr, $callback_str:expr, $callback_bytes:expr) => { @@ -29,9 +29,9 @@ macro_rules! column_as_nullable_string { $crate::stmt::Column::Text(text) => Ok(Some(text).and_then($callback_str)), $crate::stmt::Column::Blob(bytes) => Ok(Some(bytes).and_then($callback_bytes)), $crate::stmt::Column::Null => Ok(None), - other => Err(Error::InvalidType( + _ => Err($crate::ConversionError::InvalidType( "String".to_owned(), - other.data_type().to_string(), + stringify!($col).to_owned(), )), })? }; @@ -42,9 +42,9 @@ macro_rules! column_as_nullable_string { Ok(Some(String::from_utf8_lossy(&bytes)).and_then($callback_str)) } $crate::stmt::Column::Null => Ok(None), - other => Err(Error::InvalidType( + _ => Err($crate::ConversionError::InvalidType( "String".to_owned(), - other.data_type().to_string(), + stringify!($col).to_owned(), )), })? }; @@ -55,9 +55,9 @@ macro_rules! column_as_nullable_string { Ok(Some(String::from_utf8_lossy(&bytes).to_string())) } $crate::stmt::Column::Null => Ok(None), - other => Err(Error::InvalidType( + _ => Err($crate::ConversionError::InvalidType( "String".to_owned(), - other.data_type().to_string(), + stringify!($col).to_owned(), )), })? }; @@ -69,15 +69,21 @@ macro_rules! column_as_nullable_number { ($col:expr) => { (match $col { $crate::stmt::Column::Text(text) => Ok(Some(text.parse().map_err(|_| { - Error::InvalidConversion(stringify!($col).to_owned(), "Number".to_owned()) + $crate::ConversionError::InvalidConversion( + stringify!($col).to_owned(), + "Number".to_owned(), + ) })?)), $crate::stmt::Column::Integer(n) => Ok(Some(n.try_into().map_err(|_| { - Error::InvalidConversion(stringify!($col).to_owned(), "Number".to_owned()) + $crate::ConversionError::InvalidConversion( + stringify!($col).to_owned(), + "Number".to_owned(), + ) })?)), $crate::stmt::Column::Null => Ok(None), - other => Err(Error::InvalidType( + _ => Err($crate::ConversionError::InvalidType( "Number".to_owned(), - other.data_type().to_string(), + stringify!($col).to_owned(), )), })? }; @@ -89,14 +95,20 @@ macro_rules! column_as_number { ($col:expr) => { (match $col { $crate::stmt::Column::Text(text) => text.parse().map_err(|_| { - Error::InvalidConversion(stringify!($col).to_owned(), "Number".to_owned()) + $crate::ConversionError::InvalidConversion( + stringify!($col).to_owned(), + "Number".to_owned(), + ) }), $crate::stmt::Column::Integer(n) => n.try_into().map_err(|_| { - Error::InvalidConversion(stringify!($col).to_owned(), "Number".to_owned()) + $crate::ConversionError::InvalidConversion( + stringify!($col).to_owned(), + "Number".to_owned(), + ) }), - other => Err(Error::InvalidType( + _ => Err($crate::ConversionError::InvalidType( "Number".to_owned(), - other.data_type().to_string(), + stringify!($col).to_owned(), )), })? }; @@ -110,51 +122,57 @@ macro_rules! column_as_nullable_binary { $crate::stmt::Column::Text(text) => Ok(Some(text.as_bytes().to_vec())), $crate::stmt::Column::Blob(bytes) => Ok(Some(bytes.to_owned())), $crate::stmt::Column::Null => Ok(None), - other => Err(Error::InvalidType( + _ => Err($crate::ConversionError::InvalidType( "String".to_owned(), - other.data_type().to_string(), + stringify!($col).to_owned(), )), })? }; } -/// Parses a SQLite column as a binary +/// Parses a SQL column as a binary #[macro_export] macro_rules! column_as_binary { ($col:expr) => { (match $col { $crate::stmt::Column::Text(text) => Ok(text.as_bytes().to_vec()), $crate::stmt::Column::Blob(bytes) => Ok(bytes.to_owned()), - other => Err(Error::InvalidType( + _ => Err($crate::ConversionError::InvalidType( "String".to_owned(), - other.data_type().to_string(), + stringify!($col).to_owned(), )), })? }; } -/// Parses a SQLite column as a string +/// Parses a SQL column as a string #[macro_export] macro_rules! column_as_string { ($col:expr, $callback_str:expr, $callback_bytes:expr) => { (match $col { - $crate::stmt::Column::Text(text) => $callback_str(&text).map_err(Error::from), - $crate::stmt::Column::Blob(bytes) => $callback_bytes(&bytes).map_err(Error::from), - other => Err(Error::InvalidType( + $crate::stmt::Column::Text(text) => { + $callback_str(&text).map_err($crate::ConversionError::from) + } + $crate::stmt::Column::Blob(bytes) => { + $callback_bytes(&bytes).map_err($crate::ConversionError::from) + } + _ => Err($crate::ConversionError::InvalidType( "String".to_owned(), - other.data_type().to_string(), + stringify!($col).to_owned(), )), })? }; ($col:expr, $callback:expr) => { (match $col { - $crate::stmt::Column::Text(text) => $callback(&text).map_err(Error::from), + $crate::stmt::Column::Text(text) => { + $callback(&text).map_err($crate::ConversionError::from) + } $crate::stmt::Column::Blob(bytes) => { - $callback(&String::from_utf8_lossy(&bytes)).map_err(Error::from) + $callback(&String::from_utf8_lossy(&bytes)).map_err($crate::ConversionError::from) } - other => Err(Error::InvalidType( + _ => Err($crate::ConversionError::InvalidType( "String".to_owned(), - other.data_type().to_string(), + stringify!($col).to_owned(), )), })? }; @@ -162,9 +180,9 @@ macro_rules! column_as_string { (match $col { $crate::stmt::Column::Text(text) => Ok(text.to_owned()), $crate::stmt::Column::Blob(bytes) => Ok(String::from_utf8_lossy(&bytes).to_string()), - other => Err(Error::InvalidType( + _ => Err($crate::ConversionError::InvalidType( "String".to_owned(), - other.data_type().to_string(), + stringify!($col).to_owned(), )), })? }; diff --git a/crates/cdk-sql-common/src/mint/auth/migrations.rs b/crates/cdk-sql-common/src/mint/auth/migrations.rs new file mode 100644 index 000000000..75a1584f7 --- /dev/null +++ b/crates/cdk-sql-common/src/mint/auth/migrations.rs @@ -0,0 +1,5 @@ +/// @generated +/// Auto-generated by build.rs +pub static MIGRATIONS: &[(&str, &str)] = &[ + ("sqlite/20250109143347_init.sql", include_str!(r#"./migrations/sqlite/20250109143347_init.sql"#)), +]; diff --git a/crates/cdk-sqlite/src/mint/auth/migrations/20250109143347_init.sql b/crates/cdk-sql-common/src/mint/auth/migrations/sqlite/20250109143347_init.sql similarity index 100% rename from crates/cdk-sqlite/src/mint/auth/migrations/20250109143347_init.sql rename to crates/cdk-sql-common/src/mint/auth/migrations/sqlite/20250109143347_init.sql diff --git a/crates/cdk-sqlite/src/mint/auth/mod.rs b/crates/cdk-sql-common/src/mint/auth/mod.rs similarity index 72% rename from crates/cdk-sqlite/src/mint/auth/mod.rs rename to crates/cdk-sql-common/src/mint/auth/mod.rs index 4a002fa80..9d37c1d8e 100644 --- a/crates/cdk-sqlite/src/mint/auth/mod.rs +++ b/crates/cdk-sql-common/src/mint/auth/mod.rs @@ -1,8 +1,7 @@ -//! SQLite Mint Auth +//! SQL Mint Auth use std::collections::HashMap; -use std::ops::DerefMut; -use std::path::Path; +use std::marker::PhantomData; use std::str::FromStr; use async_trait::async_trait; @@ -10,53 +9,57 @@ use cdk_common::database::{self, MintAuthDatabase, MintAuthTransaction}; use cdk_common::mint::MintKeySetInfo; use cdk_common::nuts::{AuthProof, BlindSignature, Id, PublicKey, State}; use cdk_common::{AuthRequired, ProtectedEndpoint}; +use migrations::MIGRATIONS; use tracing::instrument; -use super::async_rusqlite::AsyncRusqlite; -use super::{sqlite_row_to_blind_signature, sqlite_row_to_keyset_info, SqliteTransaction}; +use super::{sql_row_to_blind_signature, sql_row_to_keyset_info, SQLTransaction}; use crate::column_as_string; -use crate::common::{create_sqlite_pool, migrate}; -use crate::mint::async_rusqlite::query; +use crate::common::migrate; +use crate::database::{DatabaseConnector, DatabaseTransaction}; use crate::mint::Error; +use crate::stmt::query; -/// Mint SQLite Database +/// Mint SQL Database #[derive(Debug, Clone)] -pub struct MintSqliteAuthDatabase { - pool: AsyncRusqlite, +pub struct SQLMintAuthDatabase +where + DB: DatabaseConnector, +{ + db: DB, } -#[rustfmt::skip] -mod migrations; - -impl MintSqliteAuthDatabase { - /// Create new [`MintSqliteAuthDatabase`] - #[cfg(not(feature = "sqlcipher"))] - pub async fn new>(path: P) -> Result { - let pool = create_sqlite_pool(path.as_ref().to_str().ok_or(Error::InvalidDbPath)?); - migrate(pool.get()?.deref_mut(), migrations::MIGRATIONS)?; - - Ok(Self { - pool: AsyncRusqlite::new(pool), - }) +impl SQLMintAuthDatabase +where + DB: DatabaseConnector, +{ + /// Creates a new instance + pub async fn new(db: X) -> Result + where + X: Into, + { + let db = db.into(); + Self::migrate(&db).await?; + Ok(Self { db }) } - /// Create new [`MintSqliteAuthDatabase`] - #[cfg(feature = "sqlcipher")] - pub async fn new>(path: P, password: String) -> Result { - let pool = create_sqlite_pool( - path.as_ref().to_str().ok_or(Error::InvalidDbPath)?, - password, - ); - migrate(pool.get()?.deref_mut(), migrations::MIGRATIONS)?; - - Ok(Self { - pool: AsyncRusqlite::new(pool), - }) + /// Migrate + async fn migrate(conn: &DB) -> Result<(), Error> { + let tx = conn.begin().await?; + migrate(&tx, DB::name(), MIGRATIONS).await?; + tx.commit().await?; + Ok(()) } } +#[rustfmt::skip] +mod migrations; + + #[async_trait] -impl MintAuthTransaction for SqliteTransaction<'_> { +impl<'a, T> MintAuthTransaction for SQLTransaction<'a, T> +where + T: DatabaseTransaction<'a>, +{ #[instrument(skip(self))] async fn set_active_keyset(&mut self, id: Id) -> Result<(), database::Error> { tracing::info!("Setting auth keyset {id} active"); @@ -68,8 +71,8 @@ impl MintAuthTransaction for SqliteTransaction<'_> { ELSE FALSE END; "#, - ) - .bind(":id", id.to_string()) + )? + .bind("id", id.to_string()) .execute(&self.inner) .await?; @@ -97,15 +100,15 @@ impl MintAuthTransaction for SqliteTransaction<'_> { max_order = excluded.max_order, derivation_path_index = excluded.derivation_path_index "#, - ) - .bind(":id", keyset.id.to_string()) - .bind(":unit", keyset.unit.to_string()) - .bind(":active", keyset.active) - .bind(":valid_from", keyset.valid_from as i64) - .bind(":valid_to", keyset.final_expiry.map(|v| v as i64)) - .bind(":derivation_path", keyset.derivation_path.to_string()) - .bind(":max_order", keyset.max_order) - .bind(":derivation_path_index", keyset.derivation_path_index) + )? + .bind("id", keyset.id.to_string()) + .bind("unit", keyset.unit.to_string()) + .bind("active", keyset.active) + .bind("valid_from", keyset.valid_from as i64) + .bind("valid_to", keyset.final_expiry.map(|v| v as i64)) + .bind("derivation_path", keyset.derivation_path.to_string()) + .bind("max_order", keyset.max_order) + .bind("derivation_path_index", keyset.derivation_path_index) .execute(&self.inner) .await?; @@ -120,12 +123,12 @@ impl MintAuthTransaction for SqliteTransaction<'_> { VALUES (:y, :keyset_id, :secret, :c, :state) "#, - ) - .bind(":y", proof.y()?.to_bytes().to_vec()) - .bind(":keyset_id", proof.keyset_id.to_string()) - .bind(":secret", proof.secret.to_string()) - .bind(":c", proof.c.to_bytes().to_vec()) - .bind(":state", "UNSPENT".to_string()) + )? + .bind("y", proof.y()?.to_bytes().to_vec()) + .bind("keyset_id", proof.keyset_id.to_string()) + .bind("secret", proof.secret.to_string()) + .bind("c", proof.c.to_bytes().to_vec()) + .bind("state", "UNSPENT".to_string()) .execute(&self.inner) .await { @@ -139,20 +142,20 @@ impl MintAuthTransaction for SqliteTransaction<'_> { y: &PublicKey, proofs_state: State, ) -> Result, Self::Err> { - let current_state = query(r#"SELECT state FROM proof WHERE y = :y"#) - .bind(":y", y.to_bytes().to_vec()) + let current_state = query(r#"SELECT state FROM proof WHERE y = :y"#)? + .bind("y", y.to_bytes().to_vec()) .pluck(&self.inner) .await? .map(|state| Ok::<_, Error>(column_as_string!(state, State::from_str))) .transpose()?; - query(r#"UPDATE proof SET state = :new_state WHERE state = :state AND y = :y"#) - .bind(":y", y.to_bytes().to_vec()) + query(r#"UPDATE proof SET state = :new_state WHERE state = :state AND y = :y"#)? + .bind("y", y.to_bytes().to_vec()) .bind( - ":state", + "state", current_state.as_ref().map(|state| state.to_string()), ) - .bind(":new_state", proofs_state.to_string()) + .bind("new_state", proofs_state.to_string()) .execute(&self.inner) .await?; @@ -173,11 +176,11 @@ impl MintAuthTransaction for SqliteTransaction<'_> { VALUES (:y, :amount, :keyset_id, :c) "#, - ) - .bind(":y", message.to_bytes().to_vec()) - .bind(":amount", u64::from(signature.amount) as i64) - .bind(":keyset_id", signature.keyset_id.to_string()) - .bind(":c", signature.c.to_bytes().to_vec()) + )? + .bind("y", message.to_bytes().to_vec()) + .bind("amount", u64::from(signature.amount) as i64) + .bind("keyset_id", signature.keyset_id.to_string()) + .bind("c", signature.c.to_bytes().to_vec()) .execute(&self.inner) .await?; } @@ -196,9 +199,9 @@ impl MintAuthTransaction for SqliteTransaction<'_> { (endpoint, auth) VALUES (:endpoint, :auth); "#, - ) - .bind(":endpoint", serde_json::to_string(endpoint)?) - .bind(":auth", serde_json::to_string(auth)?) + )? + .bind("endpoint", serde_json::to_string(endpoint)?) + .bind("auth", serde_json::to_string(auth)?) .execute(&self.inner) .await { @@ -215,9 +218,9 @@ impl MintAuthTransaction for SqliteTransaction<'_> { &mut self, protected_endpoints: Vec, ) -> Result<(), database::Error> { - query(r#"DELETE FROM protected_endpoints WHERE endpoint IN (:endpoints)"#) + query(r#"DELETE FROM protected_endpoints WHERE endpoint IN (:endpoints)"#)? .bind_vec( - ":endpoints", + "endpoints", protected_endpoints .iter() .map(serde_json::to_string) @@ -230,15 +233,19 @@ impl MintAuthTransaction for SqliteTransaction<'_> { } #[async_trait] -impl MintAuthDatabase for MintSqliteAuthDatabase { +impl MintAuthDatabase for SQLMintAuthDatabase +where + DB: DatabaseConnector, +{ type Err = database::Error; async fn begin_transaction<'a>( &'a self, ) -> Result + Send + Sync + 'a>, database::Error> { - Ok(Box::new(SqliteTransaction { - inner: self.pool.begin().await?, + Ok(Box::new(SQLTransaction { + inner: self.db.begin().await?, + _phantom: PhantomData, })) } @@ -252,8 +259,8 @@ impl MintAuthDatabase for MintSqliteAuthDatabase { WHERE active = 1; "#, - ) - .pluck(&self.pool) + )? + .pluck(&self.db) .await? .map(|id| Ok::<_, Error>(column_as_string!(id, Id::from_str, Id::from_bytes))) .transpose()?) @@ -274,11 +281,11 @@ impl MintAuthDatabase for MintSqliteAuthDatabase { FROM keyset WHERE id=:id"#, - ) - .bind(":id", id.to_string()) - .fetch_one(&self.pool) + )? + .bind("id", id.to_string()) + .fetch_one(&self.db) .await? - .map(sqlite_row_to_keyset_info) + .map(sql_row_to_keyset_info) .transpose()?) } @@ -297,18 +304,18 @@ impl MintAuthDatabase for MintSqliteAuthDatabase { FROM keyset WHERE id=:id"#, - ) - .fetch_all(&self.pool) + )? + .fetch_all(&self.db) .await? .into_iter() - .map(sqlite_row_to_keyset_info) + .map(sql_row_to_keyset_info) .collect::, _>>()?) } async fn get_proofs_states(&self, ys: &[PublicKey]) -> Result>, Self::Err> { - let mut current_states = query(r#"SELECT y, state FROM proof WHERE y IN (:ys)"#) - .bind_vec(":ys", ys.iter().map(|y| y.to_bytes().to_vec()).collect()) - .fetch_all(&self.pool) + let mut current_states = query(r#"SELECT y, state FROM proof WHERE y IN (:ys)"#)? + .bind_vec("ys", ys.iter().map(|y| y.to_bytes().to_vec()).collect()) + .fetch_all(&self.db) .await? .into_iter() .map(|row| { @@ -338,15 +345,15 @@ impl MintAuthDatabase for MintSqliteAuthDatabase { blind_signature WHERE y IN (:y) "#, - ) + )? .bind_vec( - ":y", + "y", blinded_messages .iter() .map(|y| y.to_bytes().to_vec()) .collect(), ) - .fetch_all(&self.pool) + .fetch_all(&self.db) .await? .into_iter() .map(|mut row| { @@ -356,7 +363,7 @@ impl MintAuthDatabase for MintSqliteAuthDatabase { PublicKey::from_hex, PublicKey::from_slice ), - sqlite_row_to_blind_signature(row)?, + sql_row_to_blind_signature(row)?, )) }) .collect::, Error>>()?; @@ -371,9 +378,9 @@ impl MintAuthDatabase for MintSqliteAuthDatabase { protected_endpoint: ProtectedEndpoint, ) -> Result, Self::Err> { Ok( - query(r#"SELECT auth FROM protected_endpoints WHERE endpoint = :endpoint"#) - .bind(":endpoint", serde_json::to_string(&protected_endpoint)?) - .pluck(&self.pool) + query(r#"SELECT auth FROM protected_endpoints WHERE endpoint = :endpoint"#)? + .bind("endpoint", serde_json::to_string(&protected_endpoint)?) + .pluck(&self.db) .await? .map(|auth| { Ok::<_, Error>(column_as_string!( @@ -389,8 +396,8 @@ impl MintAuthDatabase for MintSqliteAuthDatabase { async fn get_auth_for_endpoints( &self, ) -> Result>, Self::Err> { - Ok(query(r#"SELECT endpoint, auth FROM protected_endpoints"#) - .fetch_all(&self.pool) + Ok(query(r#"SELECT endpoint, auth FROM protected_endpoints"#)? + .fetch_all(&self.db) .await? .into_iter() .map(|row| { diff --git a/crates/cdk-sql-common/src/mint/migrations.rs b/crates/cdk-sql-common/src/mint/migrations.rs new file mode 100644 index 000000000..f67690a7a --- /dev/null +++ b/crates/cdk-sql-common/src/mint/migrations.rs @@ -0,0 +1,26 @@ +/// @generated +/// Auto-generated by build.rs +pub static MIGRATIONS: &[(&str, &str)] = &[ + ("sqlite/1_fix_sqlx_migration.sql", include_str!(r#"./migrations/sqlite/1_fix_sqlx_migration.sql"#)), + ("sqlite/20240612124932_init.sql", include_str!(r#"./migrations/sqlite/20240612124932_init.sql"#)), + ("sqlite/20240618195700_quote_state.sql", include_str!(r#"./migrations/sqlite/20240618195700_quote_state.sql"#)), + ("sqlite/20240626092101_nut04_state.sql", include_str!(r#"./migrations/sqlite/20240626092101_nut04_state.sql"#)), + ("sqlite/20240703122347_request_lookup_id.sql", include_str!(r#"./migrations/sqlite/20240703122347_request_lookup_id.sql"#)), + ("sqlite/20240710145043_input_fee.sql", include_str!(r#"./migrations/sqlite/20240710145043_input_fee.sql"#)), + ("sqlite/20240711183109_derivation_path_index.sql", include_str!(r#"./migrations/sqlite/20240711183109_derivation_path_index.sql"#)), + ("sqlite/20240718203721_allow_unspent.sql", include_str!(r#"./migrations/sqlite/20240718203721_allow_unspent.sql"#)), + ("sqlite/20240811031111_update_mint_url.sql", include_str!(r#"./migrations/sqlite/20240811031111_update_mint_url.sql"#)), + ("sqlite/20240919103407_proofs_quote_id.sql", include_str!(r#"./migrations/sqlite/20240919103407_proofs_quote_id.sql"#)), + ("sqlite/20240923153640_melt_requests.sql", include_str!(r#"./migrations/sqlite/20240923153640_melt_requests.sql"#)), + ("sqlite/20240930101140_dleq_for_sigs.sql", include_str!(r#"./migrations/sqlite/20240930101140_dleq_for_sigs.sql"#)), + ("sqlite/20241108093102_mint_mint_quote_pubkey.sql", include_str!(r#"./migrations/sqlite/20241108093102_mint_mint_quote_pubkey.sql"#)), + ("sqlite/20250103201327_amount_to_pay_msats.sql", include_str!(r#"./migrations/sqlite/20250103201327_amount_to_pay_msats.sql"#)), + ("sqlite/20250129200912_remove_mint_url.sql", include_str!(r#"./migrations/sqlite/20250129200912_remove_mint_url.sql"#)), + ("sqlite/20250129230326_add_config_table.sql", include_str!(r#"./migrations/sqlite/20250129230326_add_config_table.sql"#)), + ("sqlite/20250307213652_keyset_id_as_foreign_key.sql", include_str!(r#"./migrations/sqlite/20250307213652_keyset_id_as_foreign_key.sql"#)), + ("sqlite/20250406091754_mint_time_of_quotes.sql", include_str!(r#"./migrations/sqlite/20250406091754_mint_time_of_quotes.sql"#)), + ("sqlite/20250406093755_mint_created_time_signature.sql", include_str!(r#"./migrations/sqlite/20250406093755_mint_created_time_signature.sql"#)), + ("sqlite/20250415093121_drop_keystore_foreign.sql", include_str!(r#"./migrations/sqlite/20250415093121_drop_keystore_foreign.sql"#)), + ("sqlite/20250626120251_rename_blind_message_y_to_b.sql", include_str!(r#"./migrations/sqlite/20250626120251_rename_blind_message_y_to_b.sql"#)), + ("sqlite/20250706101057_bolt12.sql", include_str!(r#"./migrations/sqlite/20250706101057_bolt12.sql"#)), +]; diff --git a/crates/cdk-sql-common/src/mint/migrations/sqlite/1_fix_sqlx_migration.sql b/crates/cdk-sql-common/src/mint/migrations/sqlite/1_fix_sqlx_migration.sql new file mode 100644 index 000000000..9f7a0d828 --- /dev/null +++ b/crates/cdk-sql-common/src/mint/migrations/sqlite/1_fix_sqlx_migration.sql @@ -0,0 +1,20 @@ +-- Migrate `_sqlx_migrations` to our new migration system +CREATE TABLE IF NOT EXISTS _sqlx_migrations AS +SELECT + '' AS version, + '' AS description, + 0 AS execution_time +WHERE 0; + +INSERT INTO migrations +SELECT + version || '_' || REPLACE(description, ' ', '_') || '.sql', + execution_time +FROM _sqlx_migrations +WHERE EXISTS ( + SELECT 1 + FROM sqlite_master + WHERE type = 'table' AND name = '_sqlx_migrations' +); + +DROP TABLE _sqlx_migrations; diff --git a/crates/cdk-sqlite/src/mint/migrations/20240612124932_init.sql b/crates/cdk-sql-common/src/mint/migrations/sqlite/20240612124932_init.sql similarity index 100% rename from crates/cdk-sqlite/src/mint/migrations/20240612124932_init.sql rename to crates/cdk-sql-common/src/mint/migrations/sqlite/20240612124932_init.sql diff --git a/crates/cdk-sqlite/src/mint/migrations/20240618195700_quote_state.sql b/crates/cdk-sql-common/src/mint/migrations/sqlite/20240618195700_quote_state.sql similarity index 100% rename from crates/cdk-sqlite/src/mint/migrations/20240618195700_quote_state.sql rename to crates/cdk-sql-common/src/mint/migrations/sqlite/20240618195700_quote_state.sql diff --git a/crates/cdk-sqlite/src/mint/migrations/20240626092101_nut04_state.sql b/crates/cdk-sql-common/src/mint/migrations/sqlite/20240626092101_nut04_state.sql similarity index 100% rename from crates/cdk-sqlite/src/mint/migrations/20240626092101_nut04_state.sql rename to crates/cdk-sql-common/src/mint/migrations/sqlite/20240626092101_nut04_state.sql diff --git a/crates/cdk-sqlite/src/mint/migrations/20240703122347_request_lookup_id.sql b/crates/cdk-sql-common/src/mint/migrations/sqlite/20240703122347_request_lookup_id.sql similarity index 100% rename from crates/cdk-sqlite/src/mint/migrations/20240703122347_request_lookup_id.sql rename to crates/cdk-sql-common/src/mint/migrations/sqlite/20240703122347_request_lookup_id.sql diff --git a/crates/cdk-sqlite/src/mint/migrations/20240710145043_input_fee.sql b/crates/cdk-sql-common/src/mint/migrations/sqlite/20240710145043_input_fee.sql similarity index 100% rename from crates/cdk-sqlite/src/mint/migrations/20240710145043_input_fee.sql rename to crates/cdk-sql-common/src/mint/migrations/sqlite/20240710145043_input_fee.sql diff --git a/crates/cdk-sqlite/src/mint/migrations/20240711183109_derivation_path_index.sql b/crates/cdk-sql-common/src/mint/migrations/sqlite/20240711183109_derivation_path_index.sql similarity index 100% rename from crates/cdk-sqlite/src/mint/migrations/20240711183109_derivation_path_index.sql rename to crates/cdk-sql-common/src/mint/migrations/sqlite/20240711183109_derivation_path_index.sql diff --git a/crates/cdk-sqlite/src/mint/migrations/20240718203721_allow_unspent.sql b/crates/cdk-sql-common/src/mint/migrations/sqlite/20240718203721_allow_unspent.sql similarity index 100% rename from crates/cdk-sqlite/src/mint/migrations/20240718203721_allow_unspent.sql rename to crates/cdk-sql-common/src/mint/migrations/sqlite/20240718203721_allow_unspent.sql diff --git a/crates/cdk-sqlite/src/mint/migrations/20240811031111_update_mint_url.sql b/crates/cdk-sql-common/src/mint/migrations/sqlite/20240811031111_update_mint_url.sql similarity index 100% rename from crates/cdk-sqlite/src/mint/migrations/20240811031111_update_mint_url.sql rename to crates/cdk-sql-common/src/mint/migrations/sqlite/20240811031111_update_mint_url.sql diff --git a/crates/cdk-sqlite/src/mint/migrations/20240919103407_proofs_quote_id.sql b/crates/cdk-sql-common/src/mint/migrations/sqlite/20240919103407_proofs_quote_id.sql similarity index 100% rename from crates/cdk-sqlite/src/mint/migrations/20240919103407_proofs_quote_id.sql rename to crates/cdk-sql-common/src/mint/migrations/sqlite/20240919103407_proofs_quote_id.sql diff --git a/crates/cdk-sqlite/src/mint/migrations/20240923153640_melt_requests.sql b/crates/cdk-sql-common/src/mint/migrations/sqlite/20240923153640_melt_requests.sql similarity index 100% rename from crates/cdk-sqlite/src/mint/migrations/20240923153640_melt_requests.sql rename to crates/cdk-sql-common/src/mint/migrations/sqlite/20240923153640_melt_requests.sql diff --git a/crates/cdk-sqlite/src/mint/migrations/20240930101140_dleq_for_sigs.sql b/crates/cdk-sql-common/src/mint/migrations/sqlite/20240930101140_dleq_for_sigs.sql similarity index 100% rename from crates/cdk-sqlite/src/mint/migrations/20240930101140_dleq_for_sigs.sql rename to crates/cdk-sql-common/src/mint/migrations/sqlite/20240930101140_dleq_for_sigs.sql diff --git a/crates/cdk-sqlite/src/mint/migrations/20241108093102_mint_mint_quote_pubkey.sql b/crates/cdk-sql-common/src/mint/migrations/sqlite/20241108093102_mint_mint_quote_pubkey.sql similarity index 100% rename from crates/cdk-sqlite/src/mint/migrations/20241108093102_mint_mint_quote_pubkey.sql rename to crates/cdk-sql-common/src/mint/migrations/sqlite/20241108093102_mint_mint_quote_pubkey.sql diff --git a/crates/cdk-sqlite/src/mint/migrations/20250103201327_amount_to_pay_msats.sql b/crates/cdk-sql-common/src/mint/migrations/sqlite/20250103201327_amount_to_pay_msats.sql similarity index 100% rename from crates/cdk-sqlite/src/mint/migrations/20250103201327_amount_to_pay_msats.sql rename to crates/cdk-sql-common/src/mint/migrations/sqlite/20250103201327_amount_to_pay_msats.sql diff --git a/crates/cdk-sqlite/src/mint/migrations/20250129200912_remove_mint_url.sql b/crates/cdk-sql-common/src/mint/migrations/sqlite/20250129200912_remove_mint_url.sql similarity index 100% rename from crates/cdk-sqlite/src/mint/migrations/20250129200912_remove_mint_url.sql rename to crates/cdk-sql-common/src/mint/migrations/sqlite/20250129200912_remove_mint_url.sql diff --git a/crates/cdk-sqlite/src/mint/migrations/20250129230326_add_config_table.sql b/crates/cdk-sql-common/src/mint/migrations/sqlite/20250129230326_add_config_table.sql similarity index 100% rename from crates/cdk-sqlite/src/mint/migrations/20250129230326_add_config_table.sql rename to crates/cdk-sql-common/src/mint/migrations/sqlite/20250129230326_add_config_table.sql diff --git a/crates/cdk-sqlite/src/mint/migrations/20250307213652_keyset_id_as_foreign_key.sql b/crates/cdk-sql-common/src/mint/migrations/sqlite/20250307213652_keyset_id_as_foreign_key.sql similarity index 96% rename from crates/cdk-sqlite/src/mint/migrations/20250307213652_keyset_id_as_foreign_key.sql rename to crates/cdk-sql-common/src/mint/migrations/sqlite/20250307213652_keyset_id_as_foreign_key.sql index 1dfdc77fe..c18669742 100644 --- a/crates/cdk-sqlite/src/mint/migrations/20250307213652_keyset_id_as_foreign_key.sql +++ b/crates/cdk-sql-common/src/mint/migrations/sqlite/20250307213652_keyset_id_as_foreign_key.sql @@ -1,5 +1,5 @@ -- Add foreign key constraints for keyset_id in SQLite --- SQLite requires recreating tables to add foreign keys +-- SQL requires recreating tables to add foreign keys -- First, ensure we have the right schema information PRAGMA foreign_keys = OFF; diff --git a/crates/cdk-sqlite/src/mint/migrations/20250406091754_mint_time_of_quotes.sql b/crates/cdk-sql-common/src/mint/migrations/sqlite/20250406091754_mint_time_of_quotes.sql similarity index 100% rename from crates/cdk-sqlite/src/mint/migrations/20250406091754_mint_time_of_quotes.sql rename to crates/cdk-sql-common/src/mint/migrations/sqlite/20250406091754_mint_time_of_quotes.sql diff --git a/crates/cdk-sqlite/src/mint/migrations/20250406093755_mint_created_time_signature.sql b/crates/cdk-sql-common/src/mint/migrations/sqlite/20250406093755_mint_created_time_signature.sql similarity index 100% rename from crates/cdk-sqlite/src/mint/migrations/20250406093755_mint_created_time_signature.sql rename to crates/cdk-sql-common/src/mint/migrations/sqlite/20250406093755_mint_created_time_signature.sql diff --git a/crates/cdk-sqlite/src/mint/migrations/20250415093121_drop_keystore_foreign.sql b/crates/cdk-sql-common/src/mint/migrations/sqlite/20250415093121_drop_keystore_foreign.sql similarity index 100% rename from crates/cdk-sqlite/src/mint/migrations/20250415093121_drop_keystore_foreign.sql rename to crates/cdk-sql-common/src/mint/migrations/sqlite/20250415093121_drop_keystore_foreign.sql diff --git a/crates/cdk-sqlite/src/mint/migrations/20250626120251_rename_blind_message_y_to_b.sql b/crates/cdk-sql-common/src/mint/migrations/sqlite/20250626120251_rename_blind_message_y_to_b.sql similarity index 100% rename from crates/cdk-sqlite/src/mint/migrations/20250626120251_rename_blind_message_y_to_b.sql rename to crates/cdk-sql-common/src/mint/migrations/sqlite/20250626120251_rename_blind_message_y_to_b.sql diff --git a/crates/cdk-sqlite/src/mint/migrations/20250706101057_bolt12.sql b/crates/cdk-sql-common/src/mint/migrations/sqlite/20250706101057_bolt12.sql similarity index 100% rename from crates/cdk-sqlite/src/mint/migrations/20250706101057_bolt12.sql rename to crates/cdk-sql-common/src/mint/migrations/sqlite/20250706101057_bolt12.sql diff --git a/crates/cdk-sql-common/src/mint/mod.rs b/crates/cdk-sql-common/src/mint/mod.rs new file mode 100644 index 000000000..0f362b6dc --- /dev/null +++ b/crates/cdk-sql-common/src/mint/mod.rs @@ -0,0 +1,1796 @@ +//! SQL database implementation of the Mint +//! +//! This is a generic SQL implementation for the mint storage layer. Any database can be plugged in +//! as long as standard ANSI SQL is used, as Postgres and SQLite would understand it. +//! +//! This implementation also has a rudimentary but standard migration and versioning system. +//! +//! The trait expects an asynchronous interaction, but it also provides tools to spawn blocking +//! clients in a pool and expose them to an asynchronous environment, making them compatible with +//! Mint. +use std::collections::HashMap; +use std::marker::PhantomData; +use std::str::FromStr; + +use async_trait::async_trait; +use bitcoin::bip32::DerivationPath; +use cdk_common::common::QuoteTTL; +use cdk_common::database::{ + self, ConversionError, Error, MintDatabase, MintDbWriterFinalizer, MintKeyDatabaseTransaction, + MintKeysDatabase, MintProofsDatabase, MintQuotesDatabase, MintQuotesTransaction, + MintSignatureTransaction, MintSignaturesDatabase, +}; +use cdk_common::mint::{ + self, IncomingPayment, Issuance, MeltPaymentRequest, MeltQuote, MintKeySetInfo, MintQuote, +}; +use cdk_common::nut00::ProofsMethods; +use cdk_common::payment::PaymentIdentifier; +use cdk_common::secret::Secret; +use cdk_common::state::check_state_transition; +use cdk_common::util::unix_time; +use cdk_common::{ + Amount, BlindSignature, BlindSignatureDleq, CurrencyUnit, Id, MeltQuoteState, MintInfo, + PaymentMethod, Proof, Proofs, PublicKey, SecretKey, State, +}; +use lightning_invoice::Bolt11Invoice; +use migrations::MIGRATIONS; +use tracing::instrument; +use uuid::Uuid; + +use crate::common::migrate; +use crate::database::{DatabaseConnector, DatabaseExecutor, DatabaseTransaction}; +use crate::stmt::{query, Column}; +use crate::{ + column_as_nullable_number, column_as_nullable_string, column_as_number, column_as_string, + unpack_into, +}; + +#[cfg(feature = "auth")] +mod auth; + +#[rustfmt::skip] +mod migrations; + + +#[cfg(feature = "auth")] +pub use auth::SQLMintAuthDatabase; + +/// Mint SQL Database +#[derive(Debug, Clone)] +pub struct SQLMintDatabase +where + DB: DatabaseConnector, +{ + db: DB, +} + +/// SQL Transaction Writer +pub struct SQLTransaction<'a, T> +where + T: DatabaseTransaction<'a>, +{ + inner: T, + _phantom: PhantomData<&'a ()>, +} + +#[inline(always)] +async fn get_current_states( + conn: &C, + ys: &[PublicKey], +) -> Result, Error> +where + C: DatabaseExecutor + Send + Sync, +{ + query(r#"SELECT y, state FROM proof WHERE y IN (:ys)"#)? + .bind_vec("ys", ys.iter().map(|y| y.to_bytes().to_vec()).collect()) + .fetch_all(conn) + .await? + .into_iter() + .map(|row| { + Ok(( + column_as_string!(&row[0], PublicKey::from_hex, PublicKey::from_slice), + column_as_string!(&row[1], State::from_str), + )) + }) + .collect::, _>>() +} + +#[inline(always)] +async fn set_to_config(conn: &C, id: &str, value: &V) -> Result<(), Error> +where + C: DatabaseExecutor + Send + Sync, + V: ?Sized + serde::Serialize, +{ + query( + r#" + INSERT INTO config (id, value) VALUES (:id, :value) + ON CONFLICT(id) DO UPDATE SET value = excluded.value + "#, + )? + .bind("id", id.to_owned()) + .bind("value", serde_json::to_string(&value)?) + .execute(conn) + .await?; + + Ok(()) +} + +impl SQLMintDatabase +where + DB: DatabaseConnector, +{ + /// Creates a new instance + pub async fn new(db: X) -> Result + where + X: Into, + { + let db = db.into(); + Self::migrate(&db).await?; + Ok(Self { db }) + } + + /// Migrate + async fn migrate(conn: &DB) -> Result<(), Error> { + let tx = conn.begin().await?; + migrate(&tx, DB::name(), MIGRATIONS).await?; + tx.commit().await?; + Ok(()) + } + + #[inline(always)] + async fn fetch_from_config(&self, id: &str) -> Result + where + R: serde::de::DeserializeOwned, + { + let value = column_as_string!(query(r#"SELECT value FROM config WHERE id = :id LIMIT 1"#)? + .bind("id", id.to_owned()) + .pluck(&self.db) + .await? + .ok_or(Error::UnknownQuoteTTL)?); + + Ok(serde_json::from_str(&value)?) + } +} + +#[async_trait] +impl<'a, T> database::MintProofsTransaction<'a> for SQLTransaction<'a, T> +where + T: DatabaseTransaction<'a>, +{ + type Err = Error; + + async fn add_proofs( + &mut self, + proofs: Proofs, + quote_id: Option, + ) -> Result<(), Self::Err> { + let current_time = unix_time(); + + // Check any previous proof, this query should return None in order to proceed storing + // Any result here would error + match query(r#"SELECT state FROM proof WHERE y IN (:ys) LIMIT 1 FOR UPDATE"#)? + .bind_vec( + "ys", + proofs + .iter() + .map(|y| y.y().map(|y| y.to_bytes().to_vec())) + .collect::>()?, + ) + .pluck(&self.inner) + .await? + .map(|state| Ok::<_, Error>(column_as_string!(&state, State::from_str))) + .transpose()? + { + Some(State::Spent) => Err(database::Error::AttemptUpdateSpentProof), + Some(_) => Err(database::Error::Duplicate), + None => Ok(()), // no previous record + }?; + + for proof in proofs { + query( + r#" + INSERT INTO proof + (y, amount, keyset_id, secret, c, witness, state, quote_id, created_time) + VALUES + (:y, :amount, :keyset_id, :secret, :c, :witness, :state, :quote_id, :created_time) + "#, + )? + .bind("y", proof.y()?.to_bytes().to_vec()) + .bind("amount", proof.amount.to_i64()) + .bind("keyset_id", proof.keyset_id.to_string()) + .bind("secret", proof.secret.to_string()) + .bind("c", proof.c.to_bytes().to_vec()) + .bind( + "witness", + proof.witness.map(|w| serde_json::to_string(&w).unwrap()), + ) + .bind("state", "UNSPENT".to_string()) + .bind("quote_id", quote_id.map(|q| q.hyphenated().to_string())) + .bind("created_time", current_time as i64) + .execute(&self.inner) + .await?; + } + + Ok(()) + } + + async fn update_proofs_states( + &mut self, + ys: &[PublicKey], + new_state: State, + ) -> Result>, Self::Err> { + let mut current_states = get_current_states(&self.inner, ys).await?; + + if current_states.len() != ys.len() { + tracing::warn!( + "Attempted to update state of non-existent proof {} {}", + current_states.len(), + ys.len() + ); + return Err(database::Error::ProofNotFound); + } + + for state in current_states.values() { + check_state_transition(*state, new_state)?; + } + + query(r#"UPDATE proof SET state = :new_state WHERE y IN (:ys)"#)? + .bind("new_state", new_state.to_string()) + .bind_vec("ys", ys.iter().map(|y| y.to_bytes().to_vec()).collect()) + .execute(&self.inner) + .await?; + + Ok(ys.iter().map(|y| current_states.remove(y)).collect()) + } + + async fn remove_proofs( + &mut self, + ys: &[PublicKey], + _quote_id: Option, + ) -> Result<(), Self::Err> { + let total_deleted = query( + r#" + DELETE FROM proof WHERE y IN (:ys) AND state NOT IN (:exclude_state) + "#, + )? + .bind_vec("ys", ys.iter().map(|y| y.to_bytes().to_vec()).collect()) + .bind_vec("exclude_state", vec![State::Spent.to_string()]) + .execute(&self.inner) + .await?; + + if total_deleted != ys.len() { + return Err(Self::Err::AttemptRemoveSpentProof); + } + + Ok(()) + } +} + +#[async_trait] +impl<'a, T> database::MintTransaction<'a, Error> for SQLTransaction<'a, T> +where + T: DatabaseTransaction<'a>, +{ + async fn set_mint_info(&mut self, mint_info: MintInfo) -> Result<(), Error> { + Ok(set_to_config(&self.inner, "mint_info", &mint_info).await?) + } + + async fn set_quote_ttl(&mut self, quote_ttl: QuoteTTL) -> Result<(), Error> { + Ok(set_to_config(&self.inner, "quote_ttl", "e_ttl).await?) + } +} + +#[async_trait] +impl<'a, T> MintDbWriterFinalizer for SQLTransaction<'a, T> +where + T: DatabaseTransaction<'a>, +{ + type Err = Error; + + async fn commit(self: Box) -> Result<(), Error> { + Ok(self.inner.commit().await?) + } + + async fn rollback(self: Box) -> Result<(), Error> { + Ok(self.inner.rollback().await?) + } +} + +#[inline(always)] +async fn get_mint_quote_payments( + conn: &C, + quote_id: &Uuid, +) -> Result, Error> +where + C: DatabaseExecutor + Send + Sync, +{ + // Get payment IDs and timestamps from the mint_quote_payments table + query( + r#" +SELECT payment_id, timestamp, amount +FROM mint_quote_payments +WHERE quote_id=:quote_id; + "#, + )? + .bind("quote_id", quote_id.as_hyphenated().to_string()) + .fetch_all(conn) + .await? + .into_iter() + .map(|row| { + let amount: u64 = column_as_number!(row[2].clone()); + let time: u64 = column_as_number!(row[1].clone()); + Ok(IncomingPayment::new( + amount.into(), + column_as_string!(&row[0]), + time, + )) + }) + .collect() +} + +#[inline(always)] +async fn get_mint_quote_issuance(conn: &C, quote_id: &Uuid) -> Result, Error> +where + C: DatabaseExecutor + Send + Sync, +{ + // Get payment IDs and timestamps from the mint_quote_payments table + query( + r#" +SELECT amount, timestamp +FROM mint_quote_issued +WHERE quote_id=:quote_id + "#, + )? + .bind("quote_id", quote_id.as_hyphenated().to_string()) + .fetch_all(conn) + .await? + .into_iter() + .map(|row| { + let time: u64 = column_as_number!(row[1].clone()); + Ok(Issuance::new( + Amount::from_i64(column_as_number!(row[0].clone())) + .expect("Is amount when put into db"), + time, + )) + }) + .collect() +} + +#[async_trait] +impl<'a, T> MintKeyDatabaseTransaction<'a, Error> for SQLTransaction<'a, T> +where + T: DatabaseTransaction<'a>, +{ + async fn add_keyset_info(&mut self, keyset: MintKeySetInfo) -> Result<(), Error> { + query( + r#" + INSERT INTO + keyset ( + id, unit, active, valid_from, valid_to, derivation_path, + max_order, input_fee_ppk, derivation_path_index + ) + VALUES ( + :id, :unit, :active, :valid_from, :valid_to, :derivation_path, + :max_order, :input_fee_ppk, :derivation_path_index + ) + ON CONFLICT(id) DO UPDATE SET + unit = excluded.unit, + active = excluded.active, + valid_from = excluded.valid_from, + valid_to = excluded.valid_to, + derivation_path = excluded.derivation_path, + max_order = excluded.max_order, + input_fee_ppk = excluded.input_fee_ppk, + derivation_path_index = excluded.derivation_path_index + "#, + )? + .bind("id", keyset.id.to_string()) + .bind("unit", keyset.unit.to_string()) + .bind("active", keyset.active) + .bind("valid_from", keyset.valid_from as i64) + .bind("valid_to", keyset.final_expiry.map(|v| v as i64)) + .bind("derivation_path", keyset.derivation_path.to_string()) + .bind("max_order", keyset.max_order) + .bind("input_fee_ppk", keyset.input_fee_ppk as i64) + .bind("derivation_path_index", keyset.derivation_path_index) + .execute(&self.inner) + .await?; + + Ok(()) + } + + async fn set_active_keyset(&mut self, unit: CurrencyUnit, id: Id) -> Result<(), Error> { + query(r#"UPDATE keyset SET active=FALSE WHERE unit IS :unit"#)? + .bind("unit", unit.to_string()) + .execute(&self.inner) + .await?; + + query(r#"UPDATE keyset SET active=TRUE WHERE unit IS :unit AND id IS :id"#)? + .bind("unit", unit.to_string()) + .bind("id", id.to_string()) + .execute(&self.inner) + .await?; + + Ok(()) + } +} + +#[async_trait] +impl MintKeysDatabase for SQLMintDatabase +where + DB: DatabaseConnector, +{ + type Err = Error; + + async fn begin_transaction<'a>( + &'a self, + ) -> Result + Send + Sync + 'a>, Error> { + Ok(Box::new(SQLTransaction { + inner: self.db.begin().await?, + _phantom: PhantomData, + })) + } + + async fn get_active_keyset_id(&self, unit: &CurrencyUnit) -> Result, Self::Err> { + Ok( + query(r#" SELECT id FROM keyset WHERE active = 1 AND unit IS :unit"#)? + .bind("unit", unit.to_string()) + .pluck(&self.db) + .await? + .map(|id| match id { + Column::Text(text) => Ok(Id::from_str(&text)?), + Column::Blob(id) => Ok(Id::from_bytes(&id)?), + _ => Err(Error::InvalidKeysetId), + }) + .transpose()?, + ) + } + + async fn get_active_keysets(&self) -> Result, Self::Err> { + Ok(query(r#"SELECT id, unit FROM keyset WHERE active = 1"#)? + .fetch_all(&self.db) + .await? + .into_iter() + .map(|row| { + Ok(( + column_as_string!(&row[1], CurrencyUnit::from_str), + column_as_string!(&row[0], Id::from_str, Id::from_bytes), + )) + }) + .collect::, Error>>()?) + } + + async fn get_keyset_info(&self, id: &Id) -> Result, Self::Err> { + Ok(query( + r#"SELECT + id, + unit, + active, + valid_from, + valid_to, + derivation_path, + derivation_path_index, + max_order, + input_fee_ppk + FROM + keyset + WHERE id=:id"#, + )? + .bind("id", id.to_string()) + .fetch_one(&self.db) + .await? + .map(sql_row_to_keyset_info) + .transpose()?) + } + + async fn get_keyset_infos(&self) -> Result, Self::Err> { + Ok(query( + r#"SELECT + id, + unit, + active, + valid_from, + valid_to, + derivation_path, + derivation_path_index, + max_order, + input_fee_ppk + FROM + keyset + "#, + )? + .fetch_all(&self.db) + .await? + .into_iter() + .map(sql_row_to_keyset_info) + .collect::, _>>()?) + } +} + +#[async_trait] +impl<'a, T> MintQuotesTransaction<'a> for SQLTransaction<'a, T> +where + T: DatabaseTransaction<'a>, +{ + type Err = Error; + + #[instrument(skip(self))] + async fn increment_mint_quote_amount_paid( + &mut self, + quote_id: &Uuid, + amount_paid: Amount, + payment_id: String, + ) -> Result { + // Check if payment_id already exists in mint_quote_payments + let exists = query( + r#" + SELECT payment_id + FROM mint_quote_payments + WHERE payment_id = :payment_id + FOR UPDATE + "#, + )? + .bind("payment_id", payment_id.clone()) + .fetch_one(&self.inner) + .await?; + + if exists.is_some() { + tracing::error!("Payment ID already exists: {}", payment_id); + return Err(database::Error::Duplicate); + } + + // Get current amount_paid from quote + let current_amount = query( + r#" + SELECT amount_paid + FROM mint_quote + WHERE id = :quote_id + FOR UPDATE + "#, + )? + .bind("quote_id", quote_id.as_hyphenated().to_string()) + .fetch_one(&self.inner) + .await + .map_err(|err| { + tracing::error!("SQLite could not get mint quote amount_paid"); + err + })?; + + let current_amount_paid = if let Some(current_amount) = current_amount { + let amount: u64 = column_as_number!(current_amount[0].clone()); + Amount::from(amount) + } else { + Amount::ZERO + }; + + // Calculate new amount_paid with overflow check + let new_amount_paid = current_amount_paid + .checked_add(amount_paid) + .ok_or_else(|| database::Error::AmountOverflow)?; + + // Update the amount_paid + query( + r#" + UPDATE mint_quote + SET amount_paid = :amount_paid + WHERE id = :quote_id + "#, + )? + .bind("amount_paid", new_amount_paid.to_i64()) + .bind("quote_id", quote_id.as_hyphenated().to_string()) + .execute(&self.inner) + .await + .map_err(|err| { + tracing::error!("SQLite could not update mint quote amount_paid"); + err + })?; + + // Add payment_id to mint_quote_payments table + query( + r#" + INSERT INTO mint_quote_payments + (quote_id, payment_id, amount, timestamp) + VALUES (:quote_id, :payment_id, :amount, :timestamp) + "#, + )? + .bind("quote_id", quote_id.as_hyphenated().to_string()) + .bind("payment_id", payment_id) + .bind("amount", amount_paid.to_i64()) + .bind("timestamp", unix_time() as i64) + .execute(&self.inner) + .await + .map_err(|err| { + tracing::error!("SQLite could not insert payment ID: {}", err); + err + })?; + + Ok(new_amount_paid) + } + + #[instrument(skip_all)] + async fn increment_mint_quote_amount_issued( + &mut self, + quote_id: &Uuid, + amount_issued: Amount, + ) -> Result { + // Get current amount_issued from quote + let current_amount = query( + r#" + SELECT amount_issued + FROM mint_quote + WHERE id = :quote_id + FOR UPDATE + "#, + )? + .bind("quote_id", quote_id.as_hyphenated().to_string()) + .fetch_one(&self.inner) + .await + .map_err(|err| { + tracing::error!("SQLite could not get mint quote amount_issued"); + err + })?; + + let current_amount_issued = if let Some(current_amount) = current_amount { + let amount: u64 = column_as_number!(current_amount[0].clone()); + Amount::from(amount) + } else { + Amount::ZERO + }; + + // Calculate new amount_issued with overflow check + let new_amount_issued = current_amount_issued + .checked_add(amount_issued) + .ok_or_else(|| database::Error::AmountOverflow)?; + + // Update the amount_issued + query( + r#" + UPDATE mint_quote + SET amount_issued = :amount_issued + WHERE id = :quote_id + FOR UPDATE + "#, + )? + .bind("amount_issued", new_amount_issued.to_i64()) + .bind("quote_id", quote_id.as_hyphenated().to_string()) + .execute(&self.inner) + .await + .map_err(|err| { + tracing::error!("SQLite could not update mint quote amount_issued"); + err + })?; + + let current_time = unix_time(); + + query( + r#" +INSERT INTO mint_quote_issued +(quote_id, amount, timestamp) +VALUES (:quote_id, :amount, :timestamp); + "#, + )? + .bind("quote_id", quote_id.as_hyphenated().to_string()) + .bind("amount", amount_issued.to_i64()) + .bind("timestamp", current_time as i64) + .execute(&self.inner) + .await?; + + Ok(new_amount_issued) + } + + #[instrument(skip_all)] + async fn add_mint_quote(&mut self, quote: MintQuote) -> Result<(), Self::Err> { + tracing::debug!("Adding quote with: {}", quote.payment_method.to_string()); + println!("Adding quote with: {}", quote.payment_method.to_string()); + query( + r#" + INSERT INTO mint_quote ( + id, amount, unit, request, expiry, request_lookup_id, pubkey, created_time, payment_method, request_lookup_id_kind + ) + VALUES ( + :id, :amount, :unit, :request, :expiry, :request_lookup_id, :pubkey, :created_time, :payment_method, :request_lookup_id_kind + ) + "#, + )? + .bind("id", quote.id.to_string()) + .bind("amount", quote.amount.map(|a| a.to_i64())) + .bind("unit", quote.unit.to_string()) + .bind("request", quote.request) + .bind("expiry", quote.expiry as i64) + .bind( + "request_lookup_id", + quote.request_lookup_id.to_string(), + ) + .bind("pubkey", quote.pubkey.map(|p| p.to_string())) + .bind("created_time", quote.created_time as i64) + .bind("payment_method", quote.payment_method.to_string()) + .bind("request_lookup_id_kind", quote.request_lookup_id.kind()) + .execute(&self.inner) + .await?; + + Ok(()) + } + + async fn remove_mint_quote(&mut self, quote_id: &Uuid) -> Result<(), Self::Err> { + query(r#"DELETE FROM mint_quote WHERE id=:id"#)? + .bind("id", quote_id.as_hyphenated().to_string()) + .execute(&self.inner) + .await?; + Ok(()) + } + + async fn add_melt_quote(&mut self, quote: mint::MeltQuote) -> Result<(), Self::Err> { + // First try to find and replace any expired UNPAID quotes with the same request_lookup_id + let current_time = unix_time(); + let row_affected = query( + r#" + DELETE FROM melt_quote + WHERE request_lookup_id = :request_lookup_id + AND state = :state + AND expiry < :current_time + "#, + )? + .bind("request_lookup_id", quote.request_lookup_id.to_string()) + .bind("state", MeltQuoteState::Unpaid.to_string()) + .bind("current_time", current_time as i64) + .execute(&self.inner) + .await?; + + if row_affected > 0 { + tracing::info!("Received new melt quote for existing invoice with expired quote."); + } + + // Now insert the new quote + query( + r#" + INSERT INTO melt_quote + ( + id, unit, amount, request, fee_reserve, state, + expiry, payment_preimage, request_lookup_id, + created_time, paid_time, options, request_lookup_id_kind + ) + VALUES + ( + :id, :unit, :amount, :request, :fee_reserve, :state, + :expiry, :payment_preimage, :request_lookup_id, + :created_time, :paid_time, :options, :request_lookup_id_kind + ) + "#, + )? + .bind("id", quote.id.to_string()) + .bind("unit", quote.unit.to_string()) + .bind("amount", quote.amount.to_i64()) + .bind("request", serde_json::to_string("e.request)?) + .bind("fee_reserve", quote.fee_reserve.to_i64()) + .bind("state", quote.state.to_string()) + .bind("expiry", quote.expiry as i64) + .bind("payment_preimage", quote.payment_preimage) + .bind("request_lookup_id", quote.request_lookup_id.to_string()) + .bind("created_time", quote.created_time as i64) + .bind("paid_time", quote.paid_time.map(|t| t as i64)) + .bind( + "options", + quote.options.map(|o| serde_json::to_string(&o).ok()), + ) + .bind("request_lookup_id_kind", quote.request_lookup_id.kind()) + .execute(&self.inner) + .await?; + + Ok(()) + } + + async fn update_melt_quote_request_lookup_id( + &mut self, + quote_id: &Uuid, + new_request_lookup_id: &PaymentIdentifier, + ) -> Result<(), Self::Err> { + query(r#"UPDATE melt_quote SET request_lookup_id = :new_req_id, request_lookup_id_kind = :new_kind WHERE id = :id"#)? + .bind("new_req_id", new_request_lookup_id.to_string()) + .bind("new_kind",new_request_lookup_id.kind() ) + .bind("id", quote_id.as_hyphenated().to_string()) + .execute(&self.inner) + .await?; + Ok(()) + } + + async fn update_melt_quote_state( + &mut self, + quote_id: &Uuid, + state: MeltQuoteState, + payment_proof: Option, + ) -> Result<(MeltQuoteState, mint::MeltQuote), Self::Err> { + let mut quote = query( + r#" + SELECT + id, + unit, + amount, + request, + fee_reserve, + expiry, + state, + payment_preimage, + request_lookup_id, + created_time, + paid_time, + payment_method, + options, + request_lookup_id_kind + FROM + melt_quote + WHERE + id=:id + AND state != :state + "#, + )? + .bind("id", quote_id.as_hyphenated().to_string()) + .bind("state", state.to_string()) + .fetch_one(&self.inner) + .await? + .map(sql_row_to_melt_quote) + .transpose()? + .ok_or(Error::QuoteNotFound)?; + + let rec = if state == MeltQuoteState::Paid { + let current_time = unix_time(); + query(r#"UPDATE melt_quote SET state = :state, paid_time = :paid_time, payment_preimage = :payment_preimage WHERE id = :id"#)? + .bind("state", state.to_string()) + .bind("paid_time", current_time as i64) + .bind("payment_preimage", payment_proof) + .bind("id", quote_id.as_hyphenated().to_string()) + .execute(&self.inner) + .await + } else { + query(r#"UPDATE melt_quote SET state = :state WHERE id = :id"#)? + .bind("state", state.to_string()) + .bind("id", quote_id.as_hyphenated().to_string()) + .execute(&self.inner) + .await + }; + + match rec { + Ok(_) => {} + Err(err) => { + tracing::error!("SQLite Could not update melt quote"); + return Err(err); + } + }; + + let old_state = quote.state; + quote.state = state; + + Ok((old_state, quote)) + } + + async fn remove_melt_quote(&mut self, quote_id: &Uuid) -> Result<(), Self::Err> { + query( + r#" + DELETE FROM melt_quote + WHERE id=? + "#, + )? + .bind("id", quote_id.as_hyphenated().to_string()) + .execute(&self.inner) + .await?; + + Ok(()) + } + + async fn get_mint_quote(&mut self, quote_id: &Uuid) -> Result, Self::Err> { + let payments = get_mint_quote_payments(&self.inner, quote_id).await?; + let issuance = get_mint_quote_issuance(&self.inner, quote_id).await?; + + Ok(query( + r#" + SELECT + id, + amount, + unit, + request, + expiry, + request_lookup_id, + pubkey, + created_time, + amount_paid, + amount_issued, + payment_method, + request_lookup_id_kind + FROM + mint_quote + WHERE id = :id + FOR UPDATE + "#, + )? + .bind("id", quote_id.as_hyphenated().to_string()) + .fetch_one(&self.inner) + .await? + .map(|row| sql_row_to_mint_quote(row, payments, issuance)) + .transpose()?) + } + + async fn get_melt_quote( + &mut self, + quote_id: &Uuid, + ) -> Result, Self::Err> { + Ok(query( + r#" + SELECT + id, + unit, + amount, + request, + fee_reserve, + expiry, + state, + payment_preimage, + request_lookup_id, + created_time, + paid_time, + payment_method, + options, + request_lookup_id + FROM + melt_quote + WHERE + id=:id + "#, + )? + .bind("id", quote_id.as_hyphenated().to_string()) + .fetch_one(&self.inner) + .await? + .map(sql_row_to_melt_quote) + .transpose()?) + } + + async fn get_mint_quote_by_request( + &mut self, + request: &str, + ) -> Result, Self::Err> { + let mut mint_quote = query( + r#" + SELECT + id, + amount, + unit, + request, + expiry, + request_lookup_id, + pubkey, + created_time, + amount_paid, + amount_issued, + payment_method, + request_lookup_id_kind + FROM + mint_quote + WHERE request = :request + FOR UPDATE + "#, + )? + .bind("request", request.to_string()) + .fetch_one(&self.inner) + .await? + .map(|row| sql_row_to_mint_quote(row, vec![], vec![])) + .transpose()?; + + if let Some(quote) = mint_quote.as_mut() { + let payments = get_mint_quote_payments(&self.inner, "e.id).await?; + let issuance = get_mint_quote_issuance(&self.inner, "e.id).await?; + quote.issuance = issuance; + quote.payments = payments; + } + + Ok(mint_quote) + } + + async fn get_mint_quote_by_request_lookup_id( + &mut self, + request_lookup_id: &PaymentIdentifier, + ) -> Result, Self::Err> { + let mut mint_quote = query( + r#" + SELECT + id, + amount, + unit, + request, + expiry, + request_lookup_id, + pubkey, + created_time, + amount_paid, + amount_issued, + payment_method, + request_lookup_id_kind + FROM + mint_quote + WHERE request_lookup_id = :request_lookup_id + AND request_lookup_id_kind = :request_lookup_id_kind + FOR UPDATE + "#, + )? + .bind("request_lookup_id", request_lookup_id.to_string()) + .bind("request_lookup_id_kind", request_lookup_id.kind()) + .fetch_one(&self.inner) + .await? + .map(|row| sql_row_to_mint_quote(row, vec![], vec![])) + .transpose()?; + + if let Some(quote) = mint_quote.as_mut() { + let payments = get_mint_quote_payments(&self.inner, "e.id).await?; + let issuance = get_mint_quote_issuance(&self.inner, "e.id).await?; + quote.issuance = issuance; + quote.payments = payments; + } + + Ok(mint_quote) + } +} + +#[async_trait] +impl MintQuotesDatabase for SQLMintDatabase +where + DB: DatabaseConnector, +{ + type Err = Error; + + async fn get_mint_quote(&self, quote_id: &Uuid) -> Result, Self::Err> { + let payments = get_mint_quote_payments(&self.db, quote_id).await?; + let issuance = get_mint_quote_issuance(&self.db, quote_id).await?; + + Ok(query( + r#" + SELECT + id, + amount, + unit, + request, + expiry, + request_lookup_id, + pubkey, + created_time, + amount_paid, + amount_issued, + payment_method, + request_lookup_id_kind + FROM + mint_quote + WHERE id = :id"#, + )? + .bind("id", quote_id.as_hyphenated().to_string()) + .fetch_one(&self.db) + .await? + .map(|row| sql_row_to_mint_quote(row, payments, issuance)) + .transpose()?) + } + + async fn get_mint_quote_by_request( + &self, + request: &str, + ) -> Result, Self::Err> { + let mut mint_quote = query( + r#" + SELECT + id, + amount, + unit, + request, + expiry, + request_lookup_id, + pubkey, + created_time, + amount_paid, + amount_issued, + payment_method, + request_lookup_id_kind + FROM + mint_quote + WHERE request = :request"#, + )? + .bind("request", request.to_owned()) + .fetch_one(&self.db) + .await? + .map(|row| sql_row_to_mint_quote(row, vec![], vec![])) + .transpose()?; + + if let Some(quote) = mint_quote.as_mut() { + let payments = get_mint_quote_payments(&self.db, "e.id).await?; + let issuance = get_mint_quote_issuance(&self.db, "e.id).await?; + quote.issuance = issuance; + quote.payments = payments; + } + + Ok(mint_quote) + } + + async fn get_mint_quote_by_request_lookup_id( + &self, + request_lookup_id: &PaymentIdentifier, + ) -> Result, Self::Err> { + let mut mint_quote = query( + r#" + SELECT + id, + amount, + unit, + request, + expiry, + request_lookup_id, + pubkey, + created_time, + amount_paid, + amount_issued, + payment_method, + request_lookup_id_kind + FROM + mint_quote + WHERE request_lookup_id = :request_lookup_id"#, + )? + .bind( + "request_lookup_id", + serde_json::to_string(request_lookup_id)?, + ) + .fetch_one(&self.db) + .await? + .map(|row| sql_row_to_mint_quote(row, vec![], vec![])) + .transpose()?; + + // TODO: these should use an sql join so they can be done in one query + if let Some(quote) = mint_quote.as_mut() { + let payments = get_mint_quote_payments(&self.db, "e.id).await?; + let issuance = get_mint_quote_issuance(&self.db, "e.id).await?; + quote.issuance = issuance; + quote.payments = payments; + } + + Ok(mint_quote) + } + + async fn get_mint_quotes(&self) -> Result, Self::Err> { + let mut mint_quotes = query( + r#" + SELECT + id, + amount, + unit, + request, + expiry, + request_lookup_id, + pubkey, + created_time, + amount_paid, + amount_issued, + payment_method, + request_lookup_id_kind + FROM + mint_quote + "#, + )? + .fetch_all(&self.db) + .await? + .into_iter() + .map(|row| sql_row_to_mint_quote(row, vec![], vec![])) + .collect::, _>>()?; + + for quote in mint_quotes.as_mut_slice() { + let payments = get_mint_quote_payments(&self.db, "e.id).await?; + let issuance = get_mint_quote_issuance(&self.db, "e.id).await?; + quote.issuance = issuance; + quote.payments = payments; + } + + Ok(mint_quotes) + } + + async fn get_melt_quote(&self, quote_id: &Uuid) -> Result, Self::Err> { + Ok(query( + r#" + SELECT + id, + unit, + amount, + request, + fee_reserve, + expiry, + state, + payment_preimage, + request_lookup_id, + created_time, + paid_time, + payment_method, + options, + request_lookup_id_kind + FROM + melt_quote + WHERE + id=:id + "#, + )? + .bind("id", quote_id.as_hyphenated().to_string()) + .fetch_one(&self.db) + .await? + .map(sql_row_to_melt_quote) + .transpose()?) + } + + async fn get_melt_quotes(&self) -> Result, Self::Err> { + Ok(query( + r#" + SELECT + id, + unit, + amount, + request, + fee_reserve, + expiry, + state, + payment_preimage, + request_lookup_id, + created_time, + paid_time, + payment_method, + options, + request_lookup_id_kind + FROM + melt_quote + "#, + )? + .fetch_all(&self.db) + .await? + .into_iter() + .map(sql_row_to_melt_quote) + .collect::, _>>()?) + } +} + +#[async_trait] +impl MintProofsDatabase for SQLMintDatabase +where + DB: DatabaseConnector, +{ + type Err = Error; + + async fn get_proofs_by_ys(&self, ys: &[PublicKey]) -> Result>, Self::Err> { + let mut proofs = query( + r#" + SELECT + amount, + keyset_id, + secret, + c, + witness, + y + FROM + proof + WHERE + y IN (:ys) + "#, + )? + .bind_vec("ys", ys.iter().map(|y| y.to_bytes().to_vec()).collect()) + .fetch_all(&self.db) + .await? + .into_iter() + .map(|mut row| { + Ok(( + column_as_string!( + row.pop().ok_or(Error::InvalidDbResponse)?, + PublicKey::from_hex, + PublicKey::from_slice + ), + sql_row_to_proof(row)?, + )) + }) + .collect::, Error>>()?; + + Ok(ys.iter().map(|y| proofs.remove(y)).collect()) + } + + async fn get_proof_ys_by_quote_id(&self, quote_id: &Uuid) -> Result, Self::Err> { + Ok(query( + r#" + SELECT + amount, + keyset_id, + secret, + c, + witness + FROM + proof + WHERE + quote_id = :quote_id + "#, + )? + .bind("quote_id", quote_id.as_hyphenated().to_string()) + .fetch_all(&self.db) + .await? + .into_iter() + .map(sql_row_to_proof) + .collect::, _>>()? + .ys()?) + } + + async fn get_proofs_states(&self, ys: &[PublicKey]) -> Result>, Self::Err> { + let mut current_states = get_current_states(&self.db, ys).await?; + + Ok(ys.iter().map(|y| current_states.remove(y)).collect()) + } + + async fn get_proofs_by_keyset_id( + &self, + keyset_id: &Id, + ) -> Result<(Proofs, Vec>), Self::Err> { + Ok(query( + r#" + SELECT + keyset_id, + amount, + secret, + c, + witness, + state + FROM + proof + WHERE + keyset_id=? + "#, + )? + .bind("keyset_id", keyset_id.to_string()) + .fetch_all(&self.db) + .await? + .into_iter() + .map(sql_row_to_proof_with_state) + .collect::, _>>()? + .into_iter() + .unzip()) + } +} + +#[async_trait] +impl<'a, T> MintSignatureTransaction<'a> for SQLTransaction<'a, T> +where + T: DatabaseTransaction<'a>, +{ + type Err = Error; + + async fn add_blind_signatures( + &mut self, + blinded_messages: &[PublicKey], + blind_signatures: &[BlindSignature], + quote_id: Option, + ) -> Result<(), Self::Err> { + let current_time = unix_time(); + + for (message, signature) in blinded_messages.iter().zip(blind_signatures) { + query( + r#" + INSERT INTO blind_signature + (blinded_message, amount, keyset_id, c, quote_id, dleq_e, dleq_s, created_time) + VALUES + (:blinded_message, :amount, :keyset_id, :c, :quote_id, :dleq_e, :dleq_s, :created_time) + "#, + )? + .bind("blinded_message", message.to_bytes().to_vec()) + .bind("amount", u64::from(signature.amount) as i64) + .bind("keyset_id", signature.keyset_id.to_string()) + .bind("c", signature.c.to_bytes().to_vec()) + .bind("quote_id", quote_id.map(|q| q.hyphenated().to_string())) + .bind( + "dleq_e", + signature.dleq.as_ref().map(|dleq| dleq.e.to_secret_hex()), + ) + .bind( + "dleq_s", + signature.dleq.as_ref().map(|dleq| dleq.s.to_secret_hex()), + ) + .bind("created_time", current_time as i64) + .execute(&self.inner) + .await?; + } + + Ok(()) + } + + async fn get_blind_signatures( + &mut self, + blinded_messages: &[PublicKey], + ) -> Result>, Self::Err> { + let mut blinded_signatures = query( + r#"SELECT + keyset_id, + amount, + c, + dleq_e, + dleq_s, + blinded_message + FROM + blind_signature + WHERE blinded_message IN (:y) + "#, + )? + .bind_vec( + "y", + blinded_messages + .iter() + .map(|y| y.to_bytes().to_vec()) + .collect(), + ) + .fetch_all(&self.inner) + .await? + .into_iter() + .map(|mut row| { + Ok(( + column_as_string!( + &row.pop().ok_or(Error::InvalidDbResponse)?, + PublicKey::from_hex, + PublicKey::from_slice + ), + sql_row_to_blind_signature(row)?, + )) + }) + .collect::, Error>>()?; + Ok(blinded_messages + .iter() + .map(|y| blinded_signatures.remove(y)) + .collect()) + } +} + +#[async_trait] +impl MintSignaturesDatabase for SQLMintDatabase +where + DB: DatabaseConnector, +{ + type Err = Error; + + async fn get_blind_signatures( + &self, + blinded_messages: &[PublicKey], + ) -> Result>, Self::Err> { + let mut blinded_signatures = query( + r#"SELECT + keyset_id, + amount, + c, + dleq_e, + dleq_s, + blinded_message + FROM + blind_signature + WHERE blinded_message IN (:blinded_message) + "#, + )? + .bind_vec( + "blinded_message", + blinded_messages + .iter() + .map(|b_| b_.to_bytes().to_vec()) + .collect(), + ) + .fetch_all(&self.db) + .await? + .into_iter() + .map(|mut row| { + Ok(( + column_as_string!( + &row.pop().ok_or(Error::InvalidDbResponse)?, + PublicKey::from_hex, + PublicKey::from_slice + ), + sql_row_to_blind_signature(row)?, + )) + }) + .collect::, Error>>()?; + Ok(blinded_messages + .iter() + .map(|y| blinded_signatures.remove(y)) + .collect()) + } + + async fn get_blind_signatures_for_keyset( + &self, + keyset_id: &Id, + ) -> Result, Self::Err> { + Ok(query( + r#" + SELECT + keyset_id, + amount, + c, + dleq_e, + dleq_s + FROM + blind_signature + WHERE + keyset_id=:keyset_id + "#, + )? + .bind("keyset_id", keyset_id.to_string()) + .fetch_all(&self.db) + .await? + .into_iter() + .map(sql_row_to_blind_signature) + .collect::, _>>()?) + } + + /// Get [`BlindSignature`]s for quote + async fn get_blind_signatures_for_quote( + &self, + quote_id: &Uuid, + ) -> Result, Self::Err> { + Ok(query( + r#" + SELECT + keyset_id, + amount, + c, + dleq_e, + dleq_s + FROM + blind_signature + WHERE + quote_id=:quote_id + "#, + )? + .bind("quote_id", quote_id.to_string()) + .fetch_all(&self.db) + .await? + .into_iter() + .map(sql_row_to_blind_signature) + .collect::, _>>()?) + } +} + +#[async_trait] +impl MintDatabase for SQLMintDatabase +where + DB: DatabaseConnector, +{ + async fn begin_transaction<'a>( + &'a self, + ) -> Result + Send + Sync + 'a>, Error> { + Ok(Box::new(SQLTransaction { + inner: self.db.begin().await?, + _phantom: PhantomData, + })) + } + + async fn get_mint_info(&self) -> Result { + Ok(self.fetch_from_config("mint_info").await?) + } + + async fn get_quote_ttl(&self) -> Result { + Ok(self.fetch_from_config("quote_ttl").await?) + } +} + +fn sql_row_to_keyset_info(row: Vec) -> Result { + unpack_into!( + let ( + id, + unit, + active, + valid_from, + valid_to, + derivation_path, + derivation_path_index, + max_order, + row_keyset_ppk + ) = row + ); + + Ok(MintKeySetInfo { + id: column_as_string!(id, Id::from_str, Id::from_bytes), + unit: column_as_string!(unit, CurrencyUnit::from_str), + active: matches!(active, Column::Integer(1)), + valid_from: column_as_number!(valid_from), + derivation_path: column_as_string!(derivation_path, DerivationPath::from_str), + derivation_path_index: column_as_nullable_number!(derivation_path_index), + max_order: column_as_number!(max_order), + input_fee_ppk: column_as_number!(row_keyset_ppk), + final_expiry: column_as_nullable_number!(valid_to), + }) +} + +#[instrument(skip_all)] +fn sql_row_to_mint_quote( + row: Vec, + payments: Vec, + issueances: Vec, +) -> Result { + unpack_into!( + let ( + id, amount, unit, request, expiry, request_lookup_id, + pubkey, created_time, amount_paid, amount_issued, payment_method, request_lookup_id_kind + ) = row + ); + + let request_str = column_as_string!(&request); + let request_lookup_id = column_as_nullable_string!(&request_lookup_id).unwrap_or_else(|| { + Bolt11Invoice::from_str(&request_str) + .map(|invoice| invoice.payment_hash().to_string()) + .unwrap_or_else(|_| request_str.clone()) + }); + let request_lookup_id_kind = column_as_string!(request_lookup_id_kind); + + let pubkey = column_as_nullable_string!(&pubkey) + .map(|pk| PublicKey::from_hex(&pk)) + .transpose()?; + + let id = column_as_string!(id); + let amount: Option = column_as_nullable_number!(amount); + let amount_paid: u64 = column_as_number!(amount_paid); + let amount_issued: u64 = column_as_number!(amount_issued); + let payment_method = column_as_string!(payment_method, PaymentMethod::from_str); + + Ok(MintQuote::new( + Some(Uuid::parse_str(&id).map_err(|_| Error::InvalidUuid(id))?), + request_str, + column_as_string!(unit, CurrencyUnit::from_str), + amount.map(Amount::from), + column_as_number!(expiry), + PaymentIdentifier::new(&request_lookup_id_kind, &request_lookup_id) + .map_err(|_| ConversionError::MissingParameter("Payment id".to_string()))?, + pubkey, + amount_paid.into(), + amount_issued.into(), + payment_method, + column_as_number!(created_time), + payments, + issueances, + )) +} + +fn sql_row_to_melt_quote(row: Vec) -> Result { + unpack_into!( + let ( + id, + unit, + amount, + request, + fee_reserve, + expiry, + state, + payment_preimage, + request_lookup_id, + created_time, + paid_time, + payment_method, + options, + request_lookup_id_kind + ) = row + ); + + let id = column_as_string!(id); + let amount: u64 = column_as_number!(amount); + let fee_reserve: u64 = column_as_number!(fee_reserve); + + let expiry = column_as_number!(expiry); + let payment_preimage = column_as_nullable_string!(payment_preimage); + let options = column_as_nullable_string!(options); + let options = options.and_then(|o| serde_json::from_str(&o).ok()); + let created_time: i64 = column_as_number!(created_time); + let paid_time = column_as_nullable_number!(paid_time); + let payment_method = PaymentMethod::from_str(&column_as_string!(payment_method))?; + + let state = + MeltQuoteState::from_str(&column_as_string!(&state)).map_err(ConversionError::from)?; + + let unit = column_as_string!(unit); + let request = column_as_string!(request); + + let mut request_lookup_id_kind = column_as_string!(request_lookup_id_kind); + + let request_lookup_id = column_as_nullable_string!(&request_lookup_id).unwrap_or_else(|| { + Bolt11Invoice::from_str(&request) + .map(|invoice| invoice.payment_hash().to_string()) + .unwrap_or_else(|_| { + request_lookup_id_kind = "custom".to_string(); + request.clone() + }) + }); + + let request_lookup_id = PaymentIdentifier::new(&request_lookup_id_kind, &request_lookup_id) + .map_err(|_| ConversionError::MissingParameter("Payment id".to_string()))?; + + let request = match serde_json::from_str(&request) { + Ok(req) => req, + Err(err) => { + tracing::debug!( + "Melt quote from pre migrations defaulting to bolt11 {}.", + err + ); + let bolt11 = Bolt11Invoice::from_str(&request).unwrap(); + MeltPaymentRequest::Bolt11 { bolt11 } + } + }; + + Ok(MeltQuote { + id: Uuid::parse_str(&id).map_err(|_| Error::InvalidUuid(id))?, + unit: CurrencyUnit::from_str(&unit)?, + amount: Amount::from(amount), + request, + fee_reserve: Amount::from(fee_reserve), + state, + expiry, + payment_preimage, + request_lookup_id, + options, + created_time: created_time as u64, + paid_time, + payment_method, + }) +} + +fn sql_row_to_proof(row: Vec) -> Result { + unpack_into!( + let ( + amount, + keyset_id, + secret, + c, + witness + ) = row + ); + + let amount: u64 = column_as_number!(amount); + Ok(Proof { + amount: Amount::from(amount), + keyset_id: column_as_string!(keyset_id, Id::from_str), + secret: column_as_string!(secret, Secret::from_str), + c: column_as_string!(c, PublicKey::from_hex, PublicKey::from_slice), + witness: column_as_nullable_string!(witness).and_then(|w| serde_json::from_str(&w).ok()), + dleq: None, + }) +} + +fn sql_row_to_proof_with_state(row: Vec) -> Result<(Proof, Option), Error> { + unpack_into!( + let ( + keyset_id, amount, secret, c, witness, state + ) = row + ); + + let amount: u64 = column_as_number!(amount); + let state = column_as_nullable_string!(state).and_then(|s| State::from_str(&s).ok()); + + Ok(( + Proof { + amount: Amount::from(amount), + keyset_id: column_as_string!(keyset_id, Id::from_str, Id::from_bytes), + secret: column_as_string!(secret, Secret::from_str), + c: column_as_string!(c, PublicKey::from_hex, PublicKey::from_slice), + witness: column_as_nullable_string!(witness) + .and_then(|w| serde_json::from_str(&w).ok()), + dleq: None, + }, + state, + )) +} + +fn sql_row_to_blind_signature(row: Vec) -> Result { + unpack_into!( + let ( + keyset_id, amount, c, dleq_e, dleq_s + ) = row + ); + + let dleq = match ( + column_as_nullable_string!(dleq_e), + column_as_nullable_string!(dleq_s), + ) { + (Some(e), Some(s)) => Some(BlindSignatureDleq { + e: SecretKey::from_hex(e)?, + s: SecretKey::from_hex(s)?, + }), + _ => None, + }; + + let amount: u64 = column_as_number!(amount); + + Ok(BlindSignature { + amount: Amount::from(amount), + keyset_id: column_as_string!(keyset_id, Id::from_str, Id::from_bytes), + c: column_as_string!(c, PublicKey::from_hex, PublicKey::from_slice), + dleq, + }) +} diff --git a/crates/cdk-sqlite/src/pool.rs b/crates/cdk-sql-common/src/pool.rs similarity index 79% rename from crates/cdk-sqlite/src/pool.rs rename to crates/cdk-sql-common/src/pool.rs index c1b411aae..cbeadd7c3 100644 --- a/crates/cdk-sqlite/src/pool.rs +++ b/crates/cdk-sql-common/src/pool.rs @@ -4,7 +4,7 @@ use std::fmt::Debug; use std::ops::{Deref, DerefMut}; -use std::sync::atomic::{AtomicUsize, Ordering}; +use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering}; use std::sync::{Arc, Condvar, Mutex}; use std::time::Duration; @@ -30,13 +30,17 @@ pub trait ResourceManager: Debug { type Resource: Debug; /// The configuration that is needed in order to create the resource - type Config: Debug; + type Config: Clone + Debug; /// The error the resource may return when creating a new instance type Error: Debug; /// Creates a new resource with a given config - fn new_resource(config: &Self::Config) -> Result>; + fn new_resource( + config: &Self::Config, + still_valid: Arc, + timeout: Duration, + ) -> Result>; /// The object is dropped fn drop(_resource: Self::Resource) {} @@ -49,7 +53,7 @@ where RM: ResourceManager, { config: RM::Config, - queue: Mutex>, + queue: Mutex, RM::Resource)>>, in_use: AtomicUsize, max_size: usize, default_timeout: Duration, @@ -61,7 +65,7 @@ pub struct PooledResource where RM: ResourceManager, { - resource: Option, + resource: Option<(Arc, RM::Resource)>, pool: Arc>, } @@ -88,7 +92,7 @@ where type Target = RM::Resource; fn deref(&self) -> &Self::Target { - self.resource.as_ref().expect("resource already dropped") + &self.resource.as_ref().expect("resource already dropped").1 } } @@ -97,7 +101,7 @@ where RM: ResourceManager, { fn deref_mut(&mut self) -> &mut Self::Target { - self.resource.as_mut().expect("resource already dropped") + &mut self.resource.as_mut().expect("resource already dropped").1 } } @@ -136,21 +140,27 @@ where loop { if let Some(resource) = resources.pop() { - drop(resources); - self.in_use.fetch_add(1, Ordering::AcqRel); - - return Ok(PooledResource { - resource: Some(resource), - pool: self.clone(), - }); + if resource.0.load(Ordering::SeqCst) { + drop(resources); + self.in_use.fetch_add(1, Ordering::AcqRel); + + return Ok(PooledResource { + resource: Some(resource), + pool: self.clone(), + }); + } } if self.in_use.load(Ordering::Relaxed) < self.max_size { drop(resources); self.in_use.fetch_add(1, Ordering::AcqRel); + let still_valid: Arc = Arc::new(true.into()); return Ok(PooledResource { - resource: Some(RM::new_resource(&self.config)?), + resource: Some(( + still_valid.clone(), + RM::new_resource(&self.config, still_valid, timeout)?, + )), pool: self.clone(), }); } @@ -178,7 +188,7 @@ where if let Ok(mut resources) = self.queue.lock() { loop { while let Some(resource) = resources.pop() { - RM::drop(resource); + RM::drop(resource.1); } if self.in_use.load(Ordering::Relaxed) == 0 { diff --git a/crates/cdk-sql-common/src/stmt.rs b/crates/cdk-sql-common/src/stmt.rs new file mode 100644 index 000000000..631d2b3d4 --- /dev/null +++ b/crates/cdk-sql-common/src/stmt.rs @@ -0,0 +1,292 @@ +//! Stataments mod +use std::sync::Arc; + +use cdk_common::database::Error; + +use crate::database::DatabaseExecutor; +use crate::value::Value; + +/// The Column type +pub type Column = Value; + +/// Expected response type for a given SQL statement +#[derive(Debug, Clone, Copy, Default)] +pub enum ExpectedSqlResponse { + /// A single row + SingleRow, + /// All the rows that matches a query + #[default] + ManyRows, + /// How many rows were affected by the query + AffectedRows, + /// Return the first column of the first row + Pluck, + /// Batch + Batch, +} + +/// Part value +#[derive(Debug, Clone)] +pub enum PlaceholderValue { + /// Value + Value(Value), + /// Set + Set(Vec), +} + +impl From for PlaceholderValue { + fn from(value: Value) -> Self { + PlaceholderValue::Value(value) + } +} + +impl From> for PlaceholderValue { + fn from(value: Vec) -> Self { + PlaceholderValue::Set(value) + } +} + +/// SQL Part +#[derive(Debug, Clone)] +pub enum SqlPart { + /// Raw SQL statement + Raw(Arc), + /// Placeholder + Placeholder(Arc, Option), +} + +/// SQL parser error +#[derive(Debug, PartialEq, thiserror::Error)] +pub enum SqlParseError { + /// Invalid SQL + #[error("Unterminated String literal")] + UnterminatedStringLiteral, + /// Invalid placeholder name + #[error("Invalid placeholder name")] + InvalidPlaceholder, +} + +/// Rudimentary SQL parser. +/// +/// This function does not validate the SQL statement, it only extracts the placeholder to be +/// database agnostic. +pub fn split_sql_parts(input: &str) -> Result, SqlParseError> { + let mut parts = Vec::new(); + let mut current = String::new(); + let mut chars = input.chars().peekable(); + + while let Some(&c) = chars.peek() { + match c { + '\'' | '"' => { + // Start of string literal + let quote = c; + current.push(chars.next().unwrap()); + + let mut closed = false; + while let Some(&next) = chars.peek() { + current.push(chars.next().unwrap()); + + if next == quote { + if chars.peek() == Some("e) { + // Escaped quote (e.g. '' inside strings) + current.push(chars.next().unwrap()); + } else { + closed = true; + break; + } + } + } + + if !closed { + return Err(SqlParseError::UnterminatedStringLiteral); + } + } + + ':' => { + // Flush current raw SQL + if !current.is_empty() { + parts.push(SqlPart::Raw(current.clone().into())); + current.clear(); + } + + chars.next(); // consume ':' + let mut name = String::new(); + + while let Some(&next) = chars.peek() { + if next.is_alphanumeric() || next == '_' { + name.push(chars.next().unwrap()); + } else { + break; + } + } + + if name.is_empty() { + return Err(SqlParseError::InvalidPlaceholder); + } + + parts.push(SqlPart::Placeholder(name.into(), None)); + } + + _ => { + current.push(chars.next().unwrap()); + } + } + } + + if !current.is_empty() { + parts.push(SqlPart::Raw(current.into())); + } + + Ok(parts) +} + +/// Sql message +#[derive(Debug, Default)] +pub struct Statement { + /// The SQL statement + pub parts: Vec, + /// The expected response type + pub expected_response: ExpectedSqlResponse, +} + +impl Statement { + /// Creates a new statement + pub fn new(sql: &str) -> Result { + Ok(Self { + parts: split_sql_parts(sql)?, + ..Default::default() + }) + } + + /// Convert Statement into a SQL statement and the list of placeholders + /// + /// By default it converts the statement into placeholder using $1..$n placeholders which seems + /// to be more widely supported, although it can be reimplemented with other formats since part + /// is public + pub fn to_sql(self) -> Result<(String, Vec), Error> { + let mut placeholder_values = Vec::new(); + let sql = self + .parts + .into_iter() + .map(|x| match x { + SqlPart::Placeholder(name, value) => { + match value.ok_or(Error::MissingPlaceholder(name.to_string()))? { + PlaceholderValue::Value(value) => { + placeholder_values.push(value); + Ok::<_, Error>(format!("${}", placeholder_values.len())) + } + PlaceholderValue::Set(mut values) => { + let start_size = placeholder_values.len(); + placeholder_values.append(&mut values); + let placeholders = (start_size + 1..=placeholder_values.len()) + .map(|i| format!("${i}")) + .collect::>() + .join(", "); + Ok(placeholders) + } + } + } + SqlPart::Raw(raw) => Ok(raw.trim().to_string()), + }) + .collect::, _>>()? + .join(" "); + + Ok((sql, placeholder_values)) + } + + /// Binds a given placeholder to a value. + #[inline] + pub fn bind(mut self, name: C, value: V) -> Self + where + C: ToString, + V: Into, + { + let name = name.to_string(); + let value = value.into(); + let value: PlaceholderValue = value.into(); + + for part in self.parts.iter_mut() { + if let SqlPart::Placeholder(part_name, part_value) = part { + if **part_name == *name.as_str() { + *part_value = Some(value.clone()); + } + } + } + + self + } + + /// Binds a single variable with a vector. + /// + /// This will rewrite the function from `:foo` (where value is vec![1, 2, 3]) to `:foo0, :foo1, + /// :foo2` and binds each value from the value vector accordingly. + #[inline] + pub fn bind_vec(mut self, name: C, value: Vec) -> Self + where + C: ToString, + V: Into, + { + let name = name.to_string(); + let value: PlaceholderValue = value + .into_iter() + .map(|x| x.into()) + .collect::>() + .into(); + + for part in self.parts.iter_mut() { + if let SqlPart::Placeholder(part_name, part_value) = part { + if **part_name == *name.as_str() { + *part_value = Some(value.clone()); + } + } + } + + self + } + + /// Executes a query and returns the affected rows + pub async fn pluck(self, conn: &C) -> Result, Error> + where + C: DatabaseExecutor, + { + conn.pluck(self).await + } + + /// Executes a query and returns the affected rows + pub async fn batch(self, conn: &C) -> Result<(), Error> + where + C: DatabaseExecutor, + { + conn.batch(self).await + } + + /// Executes a query and returns the affected rows + pub async fn execute(self, conn: &C) -> Result + where + C: DatabaseExecutor, + { + conn.execute(self).await + } + + /// Runs the query and returns the first row or None + pub async fn fetch_one(self, conn: &C) -> Result>, Error> + where + C: DatabaseExecutor, + { + conn.fetch_one(self).await + } + + /// Runs the query and returns the first row or None + pub async fn fetch_all(self, conn: &C) -> Result>, Error> + where + C: DatabaseExecutor, + { + conn.fetch_all(self).await + } +} + +/// Creates a new query statement +#[inline(always)] +pub fn query(sql: &str) -> Result { + Statement::new(sql).map_err(|e| Error::Database(Box::new(e))) +} diff --git a/crates/cdk-sql-common/src/value.rs b/crates/cdk-sql-common/src/value.rs new file mode 100644 index 000000000..4fd0e77ee --- /dev/null +++ b/crates/cdk-sql-common/src/value.rs @@ -0,0 +1,82 @@ +//! Generic Rust value representation for data from the database + +/// Generic Value representation of data from the any database +#[derive(Clone, Debug, PartialEq)] +pub enum Value { + /// The value is a `NULL` value. + Null, + /// The value is a signed integer. + Integer(i64), + /// The value is a floating point number. + Real(f64), + /// The value is a text string. + Text(String), + /// The value is a blob of data + Blob(Vec), +} + +impl From for Value { + fn from(value: String) -> Self { + Self::Text(value) + } +} + +impl From<&str> for Value { + fn from(value: &str) -> Self { + Self::Text(value.to_owned()) + } +} + +impl From<&&str> for Value { + fn from(value: &&str) -> Self { + Self::Text(value.to_string()) + } +} + +impl From> for Value { + fn from(value: Vec) -> Self { + Self::Blob(value) + } +} + +impl From<&[u8]> for Value { + fn from(value: &[u8]) -> Self { + Self::Blob(value.to_owned()) + } +} + +impl From for Value { + fn from(value: u8) -> Self { + Self::Integer(value.into()) + } +} + +impl From for Value { + fn from(value: i64) -> Self { + Self::Integer(value) + } +} + +impl From for Value { + fn from(value: u32) -> Self { + Self::Integer(value.into()) + } +} + +impl From for Value { + fn from(value: bool) -> Self { + Self::Integer(if value { 1 } else { 0 }) + } +} + +impl From> for Value +where + T: Into, +{ + fn from(value: Option) -> Self { + match value { + Some(v) => v.into(), + None => Value::Null, + } + } +} diff --git a/crates/cdk-sqlite/src/wallet/error.rs b/crates/cdk-sql-common/src/wallet/error.rs similarity index 98% rename from crates/cdk-sqlite/src/wallet/error.rs rename to crates/cdk-sql-common/src/wallet/error.rs index e0886c27b..8c5ae4c55 100644 --- a/crates/cdk-sqlite/src/wallet/error.rs +++ b/crates/cdk-sql-common/src/wallet/error.rs @@ -2,7 +2,7 @@ use thiserror::Error; -/// SQLite Wallet Error +/// SQL Wallet Error #[derive(Debug, Error)] pub enum Error { /// SQLX Error diff --git a/crates/cdk-sql-common/src/wallet/migrations.rs b/crates/cdk-sql-common/src/wallet/migrations.rs new file mode 100644 index 000000000..4b6d3cf72 --- /dev/null +++ b/crates/cdk-sql-common/src/wallet/migrations.rs @@ -0,0 +1,21 @@ +/// @generated +/// Auto-generated by build.rs +pub static MIGRATIONS: &[(&str, &str)] = &[ + ("sqlite/20240612132920_init.sql", include_str!(r#"./migrations/sqlite/20240612132920_init.sql"#)), + ("sqlite/20240618200350_quote_state.sql", include_str!(r#"./migrations/sqlite/20240618200350_quote_state.sql"#)), + ("sqlite/20240626091921_nut04_state.sql", include_str!(r#"./migrations/sqlite/20240626091921_nut04_state.sql"#)), + ("sqlite/20240710144711_input_fee.sql", include_str!(r#"./migrations/sqlite/20240710144711_input_fee.sql"#)), + ("sqlite/20240810214105_mint_icon_url.sql", include_str!(r#"./migrations/sqlite/20240810214105_mint_icon_url.sql"#)), + ("sqlite/20240810233905_update_mint_url.sql", include_str!(r#"./migrations/sqlite/20240810233905_update_mint_url.sql"#)), + ("sqlite/20240902151515_icon_url.sql", include_str!(r#"./migrations/sqlite/20240902151515_icon_url.sql"#)), + ("sqlite/20240902210905_mint_time.sql", include_str!(r#"./migrations/sqlite/20240902210905_mint_time.sql"#)), + ("sqlite/20241011125207_mint_urls.sql", include_str!(r#"./migrations/sqlite/20241011125207_mint_urls.sql"#)), + ("sqlite/20241108092756_wallet_mint_quote_secretkey.sql", include_str!(r#"./migrations/sqlite/20241108092756_wallet_mint_quote_secretkey.sql"#)), + ("sqlite/20250214135017_mint_tos.sql", include_str!(r#"./migrations/sqlite/20250214135017_mint_tos.sql"#)), + ("sqlite/20250310111513_drop_nostr_last_checked.sql", include_str!(r#"./migrations/sqlite/20250310111513_drop_nostr_last_checked.sql"#)), + ("sqlite/20250314082116_allow_pending_spent.sql", include_str!(r#"./migrations/sqlite/20250314082116_allow_pending_spent.sql"#)), + ("sqlite/20250323152040_wallet_dleq_proofs.sql", include_str!(r#"./migrations/sqlite/20250323152040_wallet_dleq_proofs.sql"#)), + ("sqlite/20250401120000_add_transactions_table.sql", include_str!(r#"./migrations/sqlite/20250401120000_add_transactions_table.sql"#)), + ("sqlite/20250616144830_add_keyset_expiry.sql", include_str!(r#"./migrations/sqlite/20250616144830_add_keyset_expiry.sql"#)), + ("sqlite/20250707093445_bolt12.sql", include_str!(r#"./migrations/sqlite/20250707093445_bolt12.sql"#)), +]; diff --git a/crates/cdk-sqlite/src/wallet/migrations/20240612132920_init.sql b/crates/cdk-sql-common/src/wallet/migrations/sqlite/20240612132920_init.sql similarity index 100% rename from crates/cdk-sqlite/src/wallet/migrations/20240612132920_init.sql rename to crates/cdk-sql-common/src/wallet/migrations/sqlite/20240612132920_init.sql diff --git a/crates/cdk-sqlite/src/wallet/migrations/20240618200350_quote_state.sql b/crates/cdk-sql-common/src/wallet/migrations/sqlite/20240618200350_quote_state.sql similarity index 100% rename from crates/cdk-sqlite/src/wallet/migrations/20240618200350_quote_state.sql rename to crates/cdk-sql-common/src/wallet/migrations/sqlite/20240618200350_quote_state.sql diff --git a/crates/cdk-sqlite/src/wallet/migrations/20240626091921_nut04_state.sql b/crates/cdk-sql-common/src/wallet/migrations/sqlite/20240626091921_nut04_state.sql similarity index 100% rename from crates/cdk-sqlite/src/wallet/migrations/20240626091921_nut04_state.sql rename to crates/cdk-sql-common/src/wallet/migrations/sqlite/20240626091921_nut04_state.sql diff --git a/crates/cdk-sqlite/src/wallet/migrations/20240710144711_input_fee.sql b/crates/cdk-sql-common/src/wallet/migrations/sqlite/20240710144711_input_fee.sql similarity index 100% rename from crates/cdk-sqlite/src/wallet/migrations/20240710144711_input_fee.sql rename to crates/cdk-sql-common/src/wallet/migrations/sqlite/20240710144711_input_fee.sql diff --git a/crates/cdk-sqlite/src/wallet/migrations/20240810214105_mint_icon_url.sql b/crates/cdk-sql-common/src/wallet/migrations/sqlite/20240810214105_mint_icon_url.sql similarity index 100% rename from crates/cdk-sqlite/src/wallet/migrations/20240810214105_mint_icon_url.sql rename to crates/cdk-sql-common/src/wallet/migrations/sqlite/20240810214105_mint_icon_url.sql diff --git a/crates/cdk-sqlite/src/wallet/migrations/20240810233905_update_mint_url.sql b/crates/cdk-sql-common/src/wallet/migrations/sqlite/20240810233905_update_mint_url.sql similarity index 100% rename from crates/cdk-sqlite/src/wallet/migrations/20240810233905_update_mint_url.sql rename to crates/cdk-sql-common/src/wallet/migrations/sqlite/20240810233905_update_mint_url.sql diff --git a/crates/cdk-sqlite/src/wallet/migrations/20240902151515_icon_url.sql b/crates/cdk-sql-common/src/wallet/migrations/sqlite/20240902151515_icon_url.sql similarity index 100% rename from crates/cdk-sqlite/src/wallet/migrations/20240902151515_icon_url.sql rename to crates/cdk-sql-common/src/wallet/migrations/sqlite/20240902151515_icon_url.sql diff --git a/crates/cdk-sqlite/src/wallet/migrations/20240902210905_mint_time.sql b/crates/cdk-sql-common/src/wallet/migrations/sqlite/20240902210905_mint_time.sql similarity index 100% rename from crates/cdk-sqlite/src/wallet/migrations/20240902210905_mint_time.sql rename to crates/cdk-sql-common/src/wallet/migrations/sqlite/20240902210905_mint_time.sql diff --git a/crates/cdk-sqlite/src/wallet/migrations/20241011125207_mint_urls.sql b/crates/cdk-sql-common/src/wallet/migrations/sqlite/20241011125207_mint_urls.sql similarity index 100% rename from crates/cdk-sqlite/src/wallet/migrations/20241011125207_mint_urls.sql rename to crates/cdk-sql-common/src/wallet/migrations/sqlite/20241011125207_mint_urls.sql diff --git a/crates/cdk-sqlite/src/wallet/migrations/20241108092756_wallet_mint_quote_secretkey.sql b/crates/cdk-sql-common/src/wallet/migrations/sqlite/20241108092756_wallet_mint_quote_secretkey.sql similarity index 100% rename from crates/cdk-sqlite/src/wallet/migrations/20241108092756_wallet_mint_quote_secretkey.sql rename to crates/cdk-sql-common/src/wallet/migrations/sqlite/20241108092756_wallet_mint_quote_secretkey.sql diff --git a/crates/cdk-sqlite/src/wallet/migrations/20250214135017_mint_tos.sql b/crates/cdk-sql-common/src/wallet/migrations/sqlite/20250214135017_mint_tos.sql similarity index 100% rename from crates/cdk-sqlite/src/wallet/migrations/20250214135017_mint_tos.sql rename to crates/cdk-sql-common/src/wallet/migrations/sqlite/20250214135017_mint_tos.sql diff --git a/crates/cdk-sqlite/src/wallet/migrations/20250310111513_drop_nostr_last_checked.sql b/crates/cdk-sql-common/src/wallet/migrations/sqlite/20250310111513_drop_nostr_last_checked.sql similarity index 100% rename from crates/cdk-sqlite/src/wallet/migrations/20250310111513_drop_nostr_last_checked.sql rename to crates/cdk-sql-common/src/wallet/migrations/sqlite/20250310111513_drop_nostr_last_checked.sql diff --git a/crates/cdk-sqlite/src/wallet/migrations/20250314082116_allow_pending_spent.sql b/crates/cdk-sql-common/src/wallet/migrations/sqlite/20250314082116_allow_pending_spent.sql similarity index 100% rename from crates/cdk-sqlite/src/wallet/migrations/20250314082116_allow_pending_spent.sql rename to crates/cdk-sql-common/src/wallet/migrations/sqlite/20250314082116_allow_pending_spent.sql diff --git a/crates/cdk-sqlite/src/wallet/migrations/20250323152040_wallet_dleq_proofs.sql b/crates/cdk-sql-common/src/wallet/migrations/sqlite/20250323152040_wallet_dleq_proofs.sql similarity index 100% rename from crates/cdk-sqlite/src/wallet/migrations/20250323152040_wallet_dleq_proofs.sql rename to crates/cdk-sql-common/src/wallet/migrations/sqlite/20250323152040_wallet_dleq_proofs.sql diff --git a/crates/cdk-sqlite/src/wallet/migrations/20250401120000_add_transactions_table.sql b/crates/cdk-sql-common/src/wallet/migrations/sqlite/20250401120000_add_transactions_table.sql similarity index 100% rename from crates/cdk-sqlite/src/wallet/migrations/20250401120000_add_transactions_table.sql rename to crates/cdk-sql-common/src/wallet/migrations/sqlite/20250401120000_add_transactions_table.sql diff --git a/crates/cdk-sqlite/src/wallet/migrations/20250616144830_add_keyset_expiry.sql b/crates/cdk-sql-common/src/wallet/migrations/sqlite/20250616144830_add_keyset_expiry.sql similarity index 100% rename from crates/cdk-sqlite/src/wallet/migrations/20250616144830_add_keyset_expiry.sql rename to crates/cdk-sql-common/src/wallet/migrations/sqlite/20250616144830_add_keyset_expiry.sql diff --git a/crates/cdk-sqlite/src/wallet/migrations/20250707093445_bolt12.sql b/crates/cdk-sql-common/src/wallet/migrations/sqlite/20250707093445_bolt12.sql similarity index 100% rename from crates/cdk-sqlite/src/wallet/migrations/20250707093445_bolt12.sql rename to crates/cdk-sql-common/src/wallet/migrations/sqlite/20250707093445_bolt12.sql diff --git a/crates/cdk-sql-common/src/wallet/mod.rs b/crates/cdk-sql-common/src/wallet/mod.rs new file mode 100644 index 000000000..584aefa2b --- /dev/null +++ b/crates/cdk-sql-common/src/wallet/mod.rs @@ -0,0 +1,1122 @@ +//! SQLite Wallet Database + +use std::collections::HashMap; +use std::str::FromStr; + +use async_trait::async_trait; +use cdk_common::common::ProofInfo; +use cdk_common::database::{ConversionError, Error, WalletDatabase}; +use cdk_common::mint_url::MintUrl; +use cdk_common::nuts::{MeltQuoteState, MintQuoteState}; +use cdk_common::secret::Secret; +use cdk_common::wallet::{self, MintQuote, Transaction, TransactionDirection, TransactionId}; +use cdk_common::{ + database, Amount, CurrencyUnit, Id, KeySet, KeySetInfo, Keys, MintInfo, PaymentMethod, Proof, + ProofDleq, PublicKey, SecretKey, SpendingConditions, State, +}; +use tracing::instrument; + +use crate::common::migrate; +use crate::database::DatabaseExecutor; +use crate::stmt::{query, Column}; +use crate::{ + column_as_binary, column_as_nullable_binary, column_as_nullable_number, + column_as_nullable_string, column_as_number, column_as_string, unpack_into, +}; + +#[rustfmt::skip] +mod migrations; + +/// Wallet SQLite Database +#[derive(Debug, Clone)] +pub struct SQLWalletDatabase +where + T: DatabaseExecutor, +{ + db: T, +} + +impl SQLWalletDatabase +where + DB: DatabaseExecutor, +{ + /// Creates a new instance + pub async fn new(db: X) -> Result + where + X: Into, + { + let db = db.into(); + Self::migrate(&db).await?; + Ok(Self { db }) + } + + /// Migrate [`WalletSqliteDatabase`] + async fn migrate(conn: &DB) -> Result<(), Error> { + migrate(conn, DB::name(), migrations::MIGRATIONS).await?; + Ok(()) + } +} + +#[async_trait] +impl WalletDatabase for SQLWalletDatabase +where + T: DatabaseExecutor, +{ + type Err = database::Error; + + #[instrument(skip(self))] + async fn get_melt_quotes(&self) -> Result, Self::Err> { + Ok(query( + r#" + SELECT + id, + unit, + amount, + request, + fee_reserve, + state, + expiry, + payment_preimage + FROM + melt_quote + "#, + )? + .fetch_all(&self.db) + .await? + .into_iter() + .map(sql_row_to_melt_quote) + .collect::>()?) + } + + #[instrument(skip(self, mint_info))] + async fn add_mint( + &self, + mint_url: MintUrl, + mint_info: Option, + ) -> Result<(), Self::Err> { + let ( + name, + pubkey, + version, + description, + description_long, + contact, + nuts, + icon_url, + urls, + motd, + time, + tos_url, + ) = match mint_info { + Some(mint_info) => { + let MintInfo { + name, + pubkey, + version, + description, + description_long, + contact, + nuts, + icon_url, + urls, + motd, + time, + tos_url, + } = mint_info; + + ( + name, + pubkey.map(|p| p.to_bytes().to_vec()), + version.map(|v| serde_json::to_string(&v).ok()), + description, + description_long, + contact.map(|c| serde_json::to_string(&c).ok()), + serde_json::to_string(&nuts).ok(), + icon_url, + urls.map(|c| serde_json::to_string(&c).ok()), + motd, + time, + tos_url, + ) + } + None => ( + None, None, None, None, None, None, None, None, None, None, None, None, + ), + }; + + query( + r#" +INSERT INTO mint +( + mint_url, name, pubkey, version, description, description_long, + contact, nuts, icon_url, urls, motd, mint_time, tos_url +) +VALUES +( + :mint_url, :name, :pubkey, :version, :description, :description_long, + :contact, :nuts, :icon_url, :urls, :motd, :mint_time, :tos_url +) +ON CONFLICT(mint_url) DO UPDATE SET + name = excluded.name, + pubkey = excluded.pubkey, + version = excluded.version, + description = excluded.description, + description_long = excluded.description_long, + contact = excluded.contact, + nuts = excluded.nuts, + icon_url = excluded.icon_url, + urls = excluded.urls, + motd = excluded.motd, + mint_time = excluded.mint_time, + tos_url = excluded.tos_url +; + "#, + )? + .bind("mint_url", mint_url.to_string()) + .bind("name", name) + .bind("pubkey", pubkey) + .bind("version", version) + .bind("description", description) + .bind("description_long", description_long) + .bind("contact", contact) + .bind("nuts", nuts) + .bind("icon_url", icon_url) + .bind("urls", urls) + .bind("motd", motd) + .bind("mint_time", time.map(|v| v as i64)) + .bind("tos_url", tos_url) + .execute(&self.db) + .await?; + + Ok(()) + } + + #[instrument(skip(self))] + async fn remove_mint(&self, mint_url: MintUrl) -> Result<(), Self::Err> { + query(r#"DELETE FROM mint WHERE mint_url=:mint_url"#)? + .bind("mint_url", mint_url.to_string()) + .execute(&self.db) + .await?; + + Ok(()) + } + + #[instrument(skip(self))] + async fn get_mint(&self, mint_url: MintUrl) -> Result, Self::Err> { + Ok(query( + r#" + SELECT + name, + pubkey, + version, + description, + description_long, + contact, + nuts, + icon_url, + motd, + urls, + mint_time, + tos_url + FROM + mint + WHERE mint_url = :mint_url + "#, + )? + .bind("mint_url", mint_url.to_string()) + .fetch_one(&self.db) + .await? + .map(sql_row_to_mint_info) + .transpose()?) + } + + #[instrument(skip(self))] + async fn get_mints(&self) -> Result>, Self::Err> { + Ok(query( + r#" + SELECT + name, + pubkey, + version, + description, + description_long, + contact, + nuts, + icon_url, + motd, + urls, + mint_time, + tos_url, + mint_url + FROM + mint + "#, + )? + .fetch_all(&self.db) + .await? + .into_iter() + .map(|mut row| { + let url = column_as_string!( + row.pop().ok_or(ConversionError::MissingColumn(0, 1))?, + MintUrl::from_str + ); + + Ok((url, sql_row_to_mint_info(row).ok())) + }) + .collect::, Error>>()?) + } + + #[instrument(skip(self))] + async fn update_mint_url( + &self, + old_mint_url: MintUrl, + new_mint_url: MintUrl, + ) -> Result<(), Self::Err> { + let tables = ["mint_quote", "proof"]; + + for table in &tables { + query(&format!( + r#" + UPDATE {table} + SET mint_url = :new_mint_url + WHERE mint_url = :old_mint_url + "# + ))? + .bind("new_mint_url", new_mint_url.to_string()) + .bind("old_mint_url", old_mint_url.to_string()) + .execute(&self.db) + .await?; + } + + Ok(()) + } + + #[instrument(skip(self, keysets))] + async fn add_mint_keysets( + &self, + mint_url: MintUrl, + keysets: Vec, + ) -> Result<(), Self::Err> { + for keyset in keysets { + query( + r#" + INSERT INTO keyset + (mint_url, id, unit, active, input_fee_ppk, final_expiry) + VALUES + (:mint_url, :id, :unit, :active, :input_fee_ppk, :final_expiry) + ON CONFLICT(id) DO UPDATE SET + mint_url = excluded.mint_url, + unit = excluded.unit, + active = excluded.active, + input_fee_ppk = excluded.input_fee_ppk, + final_expiry = excluded.final_expiry; + "#, + )? + .bind("mint_url", mint_url.to_string()) + .bind("id", keyset.id.to_string()) + .bind("unit", keyset.unit.to_string()) + .bind("active", keyset.active) + .bind("input_fee_ppk", keyset.input_fee_ppk as i64) + .bind("final_expiry", keyset.final_expiry.map(|v| v as i64)) + .execute(&self.db) + .await?; + } + + Ok(()) + } + + #[instrument(skip(self))] + async fn get_mint_keysets( + &self, + mint_url: MintUrl, + ) -> Result>, Self::Err> { + let keysets = query( + r#" + SELECT + id, + unit, + active, + input_fee_ppk, + final_expiry + FROM + keyset + WHERE mint_url = :mint_url + "#, + )? + .bind("mint_url", mint_url.to_string()) + .fetch_all(&self.db) + .await? + .into_iter() + .map(sql_row_to_keyset) + .collect::, Error>>()?; + + match keysets.is_empty() { + false => Ok(Some(keysets)), + true => Ok(None), + } + } + + #[instrument(skip(self), fields(keyset_id = %keyset_id))] + async fn get_keyset_by_id(&self, keyset_id: &Id) -> Result, Self::Err> { + Ok(query( + r#" + SELECT + id, + unit, + active, + input_fee_ppk, + final_expiry + FROM + keyset + WHERE id = :id + "#, + )? + .bind("id", keyset_id.to_string()) + .fetch_one(&self.db) + .await? + .map(sql_row_to_keyset) + .transpose()?) + } + + #[instrument(skip_all)] + async fn add_mint_quote(&self, quote: MintQuote) -> Result<(), Self::Err> { + query( + r#" +INSERT INTO mint_quote +(id, mint_url, amount, unit, request, state, expiry, secret_key, payment_method, amount_issued, amount_paid) +VALUES +(:id, :mint_url, :amount, :unit, :request, :state, :expiry, :secret_key, :payment_method, :amount_issued, :amount_paid) +ON CONFLICT(id) DO UPDATE SET + mint_url = excluded.mint_url, + amount = excluded.amount, + unit = excluded.unit, + request = excluded.request, + state = excluded.state, + expiry = excluded.expiry, + secret_key = excluded.secret_key, + payment_method = excluded.payment_method, + amount_issued = excluded.amount_issued, + amount_paid = excluded.amount_paid +; + "#, + )? + .bind("id", quote.id.to_string()) + .bind("mint_url", quote.mint_url.to_string()) + .bind("amount", quote.amount.map(|a| a.to_i64())) + .bind("unit", quote.unit.to_string()) + .bind("request", quote.request) + .bind("state", quote.state.to_string()) + .bind("expiry", quote.expiry as i64) + .bind("secret_key", quote.secret_key.map(|p| p.to_string())) + .bind("payment_method", quote.payment_method.to_string()) + .bind("amount_issued", quote.amount_issued.to_i64()) + .bind("amount_paid", quote.amount_paid.to_i64()) + .execute(&self.db).await?; + + Ok(()) + } + + #[instrument(skip(self))] + async fn get_mint_quote(&self, quote_id: &str) -> Result, Self::Err> { + Ok(query( + r#" + SELECT + id, + mint_url, + amount, + unit, + request, + state, + expiry, + secret_key, + payment_method, + amount_issued, + amount_paid + FROM + mint_quote + WHERE + id = :id + "#, + )? + .bind("id", quote_id.to_string()) + .fetch_one(&self.db) + .await? + .map(sql_row_to_mint_quote) + .transpose()?) + } + + #[instrument(skip(self))] + async fn get_mint_quotes(&self) -> Result, Self::Err> { + Ok(query( + r#" + SELECT + id, + mint_url, + amount, + unit, + request, + state, + expiry, + secret_key + FROM + mint_quote + "#, + )? + .fetch_all(&self.db) + .await? + .into_iter() + .map(sql_row_to_mint_quote) + .collect::>()?) + } + + #[instrument(skip(self))] + async fn remove_mint_quote(&self, quote_id: &str) -> Result<(), Self::Err> { + query(r#"DELETE FROM mint_quote WHERE id=:id"#)? + .bind("id", quote_id.to_string()) + .execute(&self.db) + .await?; + + Ok(()) + } + + #[instrument(skip_all)] + async fn add_melt_quote(&self, quote: wallet::MeltQuote) -> Result<(), Self::Err> { + query( + r#" +INSERT INTO melt_quote +(id, unit, amount, request, fee_reserve, state, expiry) +VALUES +(:id, :unit, :amount, :request, :fee_reserve, :state, :expiry) +ON CONFLICT(id) DO UPDATE SET + unit = excluded.unit, + amount = excluded.amount, + request = excluded.request, + fee_reserve = excluded.fee_reserve, + state = excluded.state, + expiry = excluded.expiry +; + "#, + )? + .bind("id", quote.id.to_string()) + .bind("unit", quote.unit.to_string()) + .bind("amount", u64::from(quote.amount) as i64) + .bind("request", quote.request) + .bind("fee_reserve", u64::from(quote.fee_reserve) as i64) + .bind("state", quote.state.to_string()) + .bind("expiry", quote.expiry as i64) + .execute(&self.db) + .await?; + + Ok(()) + } + + #[instrument(skip(self))] + async fn get_melt_quote(&self, quote_id: &str) -> Result, Self::Err> { + Ok(query( + r#" + SELECT + id, + unit, + amount, + request, + fee_reserve, + state, + expiry, + payment_preimage + FROM + melt_quote + WHERE + id=:id + "#, + )? + .bind("id", quote_id.to_owned()) + .fetch_one(&self.db) + .await? + .map(sql_row_to_melt_quote) + .transpose()?) + } + + #[instrument(skip(self))] + async fn remove_melt_quote(&self, quote_id: &str) -> Result<(), Self::Err> { + query(r#"DELETE FROM melt_quote WHERE id=:id"#)? + .bind("id", quote_id.to_owned()) + .execute(&self.db) + .await?; + + Ok(()) + } + + #[instrument(skip_all)] + async fn add_keys(&self, keyset: KeySet) -> Result<(), Self::Err> { + // Recompute ID for verification + keyset.verify_id()?; + + query( + r#" + INSERT INTO key + (id, keys) + VALUES + (:id, :keys) + ON CONFLICT(id) DO UPDATE SET + keys = excluded.keys + "#, + )? + .bind("id", keyset.id.to_string()) + .bind( + "keys", + serde_json::to_string(&keyset.keys).map_err(Error::from)?, + ) + .execute(&self.db) + .await?; + + Ok(()) + } + + #[instrument(skip(self), fields(keyset_id = %keyset_id))] + async fn get_keys(&self, keyset_id: &Id) -> Result, Self::Err> { + Ok(query( + r#" + SELECT + keys + FROM key + WHERE id = :id + "#, + )? + .bind("id", keyset_id.to_string()) + .pluck(&self.db) + .await? + .map(|keys| { + let keys = column_as_string!(keys); + serde_json::from_str(&keys).map_err(Error::from) + }) + .transpose()?) + } + + #[instrument(skip(self))] + async fn remove_keys(&self, id: &Id) -> Result<(), Self::Err> { + query(r#"DELETE FROM key WHERE id = :id"#)? + .bind("id", id.to_string()) + .pluck(&self.db) + .await?; + + Ok(()) + } + + async fn update_proofs( + &self, + added: Vec, + removed_ys: Vec, + ) -> Result<(), Self::Err> { + // TODO: Use a transaction for all these operations + for proof in added { + query( + r#" + INSERT INTO proof + (y, mint_url, state, spending_condition, unit, amount, keyset_id, secret, c, witness, dleq_e, dleq_s, dleq_r) + VALUES + (:y, :mint_url, :state, :spending_condition, :unit, :amount, :keyset_id, :secret, :c, :witness, :dleq_e, :dleq_s, :dleq_r) + ON CONFLICT(y) DO UPDATE SET + mint_url = excluded.mint_url, + state = excluded.state, + spending_condition = excluded.spending_condition, + unit = excluded.unit, + amount = excluded.amount, + keyset_id = excluded.keyset_id, + secret = excluded.secret, + c = excluded.c, + witness = excluded.witness, + dleq_e = excluded.dleq_e, + dleq_s = excluded.dleq_s, + dleq_r = excluded.dleq_r + ; + "#, + )? + .bind("y", proof.y.to_bytes().to_vec()) + .bind("mint_url", proof.mint_url.to_string()) + .bind("state",proof.state.to_string()) + .bind( + "spending_condition", + proof + .spending_condition + .map(|s| serde_json::to_string(&s).ok()), + ) + .bind("unit", proof.unit.to_string()) + .bind("amount", u64::from(proof.proof.amount) as i64) + .bind("keyset_id", proof.proof.keyset_id.to_string()) + .bind("secret", proof.proof.secret.to_string()) + .bind("c", proof.proof.c.to_bytes().to_vec()) + .bind( + "witness", + proof + .proof + .witness + .map(|w| serde_json::to_string(&w).unwrap()), + ) + .bind( + "dleq_e", + proof.proof.dleq.as_ref().map(|dleq| dleq.e.to_secret_bytes().to_vec()), + ) + .bind( + "dleq_s", + proof.proof.dleq.as_ref().map(|dleq| dleq.s.to_secret_bytes().to_vec()), + ) + .bind( + "dleq_r", + proof.proof.dleq.as_ref().map(|dleq| dleq.r.to_secret_bytes().to_vec()), + ) + .execute(&self.db).await?; + } + + query(r#"DELETE FROM proof WHERE y IN (:ys)"#)? + .bind_vec( + "ys", + removed_ys.iter().map(|y| y.to_bytes().to_vec()).collect(), + ) + .execute(&self.db) + .await?; + + Ok(()) + } + + #[instrument(skip(self, state, spending_conditions))] + async fn get_proofs( + &self, + mint_url: Option, + unit: Option, + state: Option>, + spending_conditions: Option>, + ) -> Result, Self::Err> { + Ok(query( + r#" + SELECT + amount, + unit, + keyset_id, + secret, + c, + witness, + dleq_e, + dleq_s, + dleq_r, + y, + mint_url, + state, + spending_condition + FROM proof + "#, + )? + .fetch_all(&self.db) + .await? + .into_iter() + .filter_map(|row| { + let row = sql_row_to_proof_info(row).ok()?; + + if row.matches_conditions(&mint_url, &unit, &state, &spending_conditions) { + Some(row) + } else { + None + } + }) + .collect::>()) + } + + async fn update_proofs_state(&self, ys: Vec, state: State) -> Result<(), Self::Err> { + query("UPDATE proof SET state = :state WHERE y IN (:ys)")? + .bind_vec("ys", ys.iter().map(|y| y.to_bytes().to_vec()).collect()) + .bind("state", state.to_string()) + .execute(&self.db) + .await?; + + Ok(()) + } + + #[instrument(skip(self), fields(keyset_id = %keyset_id))] + async fn increment_keyset_counter(&self, keyset_id: &Id, count: u32) -> Result<(), Self::Err> { + query( + r#" + UPDATE keyset + SET counter=counter+:count + WHERE id=:id + "#, + )? + .bind("count", count) + .bind("id", keyset_id.to_string()) + .execute(&self.db) + .await?; + + Ok(()) + } + + #[instrument(skip(self), fields(keyset_id = %keyset_id))] + async fn get_keyset_counter(&self, keyset_id: &Id) -> Result, Self::Err> { + Ok(query( + r#" + SELECT + counter + FROM + keyset + WHERE + id=:id + "#, + )? + .bind("id", keyset_id.to_string()) + .pluck(&self.db) + .await? + .map(|n| Ok::<_, Error>(column_as_number!(n))) + .transpose()?) + } + + #[instrument(skip(self))] + async fn add_transaction(&self, transaction: Transaction) -> Result<(), Self::Err> { + let mint_url = transaction.mint_url.to_string(); + let direction = transaction.direction.to_string(); + let unit = transaction.unit.to_string(); + let amount = u64::from(transaction.amount) as i64; + let fee = u64::from(transaction.fee) as i64; + let ys = transaction + .ys + .iter() + .flat_map(|y| y.to_bytes().to_vec()) + .collect::>(); + + query( + r#" +INSERT INTO transactions +(id, mint_url, direction, unit, amount, fee, ys, timestamp, memo, metadata) +VALUES +(:id, :mint_url, :direction, :unit, :amount, :fee, :ys, :timestamp, :memo, :metadata) +ON CONFLICT(id) DO UPDATE SET + mint_url = excluded.mint_url, + direction = excluded.direction, + unit = excluded.unit, + amount = excluded.amount, + fee = excluded.fee, + ys = excluded.ys, + timestamp = excluded.timestamp, + memo = excluded.memo, + metadata = excluded.metadata +; + "#, + )? + .bind("id", transaction.id().as_slice().to_vec()) + .bind("mint_url", mint_url) + .bind("direction", direction) + .bind("unit", unit) + .bind("amount", amount) + .bind("fee", fee) + .bind("ys", ys) + .bind("timestamp", transaction.timestamp as i64) + .bind("memo", transaction.memo) + .bind( + "metadata", + serde_json::to_string(&transaction.metadata).map_err(Error::from)?, + ) + .execute(&self.db) + .await?; + + Ok(()) + } + + #[instrument(skip(self))] + async fn get_transaction( + &self, + transaction_id: TransactionId, + ) -> Result, Self::Err> { + Ok(query( + r#" + SELECT + mint_url, + direction, + unit, + amount, + fee, + ys, + timestamp, + memo, + metadata + FROM + transactions + WHERE + id = :id + "#, + )? + .bind("id", transaction_id.as_slice().to_vec()) + .fetch_one(&self.db) + .await? + .map(sql_row_to_transaction) + .transpose()?) + } + + #[instrument(skip(self))] + async fn list_transactions( + &self, + mint_url: Option, + direction: Option, + unit: Option, + ) -> Result, Self::Err> { + Ok(query( + r#" + SELECT + mint_url, + direction, + unit, + amount, + fee, + ys, + timestamp, + memo, + metadata + FROM + transactions + "#, + )? + .fetch_all(&self.db) + .await? + .into_iter() + .filter_map(|row| { + // TODO: Avoid a table scan by passing the heavy lifting of checking to the DB engine + let transaction = sql_row_to_transaction(row).ok()?; + if transaction.matches_conditions(&mint_url, &direction, &unit) { + Some(transaction) + } else { + None + } + }) + .collect::>()) + } + + #[instrument(skip(self))] + async fn remove_transaction(&self, transaction_id: TransactionId) -> Result<(), Self::Err> { + query(r#"DELETE FROM transactions WHERE id=:id"#)? + .bind("id", transaction_id.as_slice().to_vec()) + .execute(&self.db) + .await?; + + Ok(()) + } +} + +fn sql_row_to_mint_info(row: Vec) -> Result { + unpack_into!( + let ( + name, + pubkey, + version, + description, + description_long, + contact, + nuts, + icon_url, + motd, + urls, + mint_time, + tos_url + ) = row + ); + + Ok(MintInfo { + name: column_as_nullable_string!(&name), + pubkey: column_as_nullable_string!(&pubkey, |v| serde_json::from_str(v).ok(), |v| { + serde_json::from_slice(v).ok() + }), + version: column_as_nullable_string!(&version).and_then(|v| serde_json::from_str(&v).ok()), + description: column_as_nullable_string!(description), + description_long: column_as_nullable_string!(description_long), + contact: column_as_nullable_string!(contact, |v| serde_json::from_str(&v).ok()), + nuts: column_as_nullable_string!(nuts, |v| serde_json::from_str(&v).ok()) + .unwrap_or_default(), + urls: column_as_nullable_string!(urls, |v| serde_json::from_str(&v).ok()), + icon_url: column_as_nullable_string!(icon_url), + motd: column_as_nullable_string!(motd), + time: column_as_nullable_number!(mint_time).map(|t| t), + tos_url: column_as_nullable_string!(tos_url), + }) +} + +#[instrument(skip_all)] +fn sql_row_to_keyset(row: Vec) -> Result { + unpack_into!( + let ( + id, + unit, + active, + input_fee_ppk, + final_expiry + ) = row + ); + + Ok(KeySetInfo { + id: column_as_string!(id, Id::from_str, Id::from_bytes), + unit: column_as_string!(unit, CurrencyUnit::from_str), + active: matches!(active, Column::Integer(1)), + input_fee_ppk: column_as_nullable_number!(input_fee_ppk).unwrap_or_default(), + final_expiry: column_as_nullable_number!(final_expiry), + }) +} + +fn sql_row_to_mint_quote(row: Vec) -> Result { + unpack_into!( + let ( + id, + mint_url, + amount, + unit, + request, + state, + expiry, + secret_key, + row_method, + row_amount_minted, + row_amount_paid + ) = row + ); + + let amount: Option = column_as_nullable_number!(amount); + + let amount_paid: u64 = column_as_number!(row_amount_paid); + let amount_minted: u64 = column_as_number!(row_amount_minted); + let payment_method = + PaymentMethod::from_str(&column_as_string!(row_method)).map_err(Error::from)?; + + Ok(MintQuote { + id: column_as_string!(id), + mint_url: column_as_string!(mint_url, MintUrl::from_str), + amount: amount.and_then(Amount::from_i64), + unit: column_as_string!(unit, CurrencyUnit::from_str), + request: column_as_string!(request), + state: column_as_string!(state, MintQuoteState::from_str), + expiry: column_as_number!(expiry), + secret_key: column_as_nullable_string!(secret_key) + .map(|v| SecretKey::from_str(&v)) + .transpose()?, + payment_method, + amount_issued: amount_minted.into(), + amount_paid: amount_paid.into(), + }) +} + +fn sql_row_to_melt_quote(row: Vec) -> Result { + unpack_into!( + let ( + id, + unit, + amount, + request, + fee_reserve, + state, + expiry, + payment_preimage + ) = row + ); + + let amount: u64 = column_as_number!(amount); + let fee_reserve: u64 = column_as_number!(fee_reserve); + + Ok(wallet::MeltQuote { + id: column_as_string!(id), + amount: Amount::from(amount), + unit: column_as_string!(unit, CurrencyUnit::from_str), + request: column_as_string!(request), + fee_reserve: Amount::from(fee_reserve), + state: column_as_string!(state, MeltQuoteState::from_str), + expiry: column_as_number!(expiry), + payment_preimage: column_as_nullable_string!(payment_preimage), + }) +} + +fn sql_row_to_proof_info(row: Vec) -> Result { + unpack_into!( + let ( + amount, + unit, + keyset_id, + secret, + c, + witness, + dleq_e, + dleq_s, + dleq_r, + y, + mint_url, + state, + spending_condition + ) = row + ); + + let dleq = match ( + column_as_nullable_binary!(dleq_e), + column_as_nullable_binary!(dleq_s), + column_as_nullable_binary!(dleq_r), + ) { + (Some(e), Some(s), Some(r)) => { + let e_key = SecretKey::from_slice(&e)?; + let s_key = SecretKey::from_slice(&s)?; + let r_key = SecretKey::from_slice(&r)?; + + Some(ProofDleq::new(e_key, s_key, r_key)) + } + _ => None, + }; + + let amount: u64 = column_as_number!(amount); + let proof = Proof { + amount: Amount::from(amount), + keyset_id: column_as_string!(keyset_id, Id::from_str), + secret: column_as_string!(secret, Secret::from_str), + witness: column_as_nullable_string!(witness, |v| { serde_json::from_str(&v).ok() }, |v| { + serde_json::from_slice(&v).ok() + }), + c: column_as_string!(c, PublicKey::from_str, PublicKey::from_slice), + dleq, + }; + + Ok(ProofInfo { + proof, + y: column_as_string!(y, PublicKey::from_str, PublicKey::from_slice), + mint_url: column_as_string!(mint_url, MintUrl::from_str), + state: column_as_string!(state, State::from_str), + spending_condition: column_as_nullable_string!( + spending_condition, + |r| { serde_json::from_str(&r).ok() }, + |r| { serde_json::from_slice(&r).ok() } + ), + unit: column_as_string!(unit, CurrencyUnit::from_str), + }) +} + +fn sql_row_to_transaction(row: Vec) -> Result { + unpack_into!( + let ( + mint_url, + direction, + unit, + amount, + fee, + ys, + timestamp, + memo, + metadata + ) = row + ); + + let amount: u64 = column_as_number!(amount); + let fee: u64 = column_as_number!(fee); + + Ok(Transaction { + mint_url: column_as_string!(mint_url, MintUrl::from_str), + direction: column_as_string!(direction, TransactionDirection::from_str), + unit: column_as_string!(unit, CurrencyUnit::from_str), + amount: Amount::from(amount), + fee: Amount::from(fee), + ys: column_as_binary!(ys) + .chunks(33) + .map(PublicKey::from_slice) + .collect::, _>>()?, + timestamp: column_as_number!(timestamp), + memo: column_as_nullable_string!(memo), + metadata: column_as_nullable_string!(metadata, |v| serde_json::from_str(&v).ok(), |v| { + serde_json::from_slice(&v).ok() + }) + .unwrap_or_default(), + }) +} diff --git a/crates/cdk-sql-common/tests/legacy-sqlx.sql b/crates/cdk-sql-common/tests/legacy-sqlx.sql new file mode 100644 index 000000000..e1237f368 --- /dev/null +++ b/crates/cdk-sql-common/tests/legacy-sqlx.sql @@ -0,0 +1,97 @@ +PRAGMA foreign_keys=OFF; +BEGIN TRANSACTION; +CREATE TABLE _sqlx_migrations ( + version BIGINT PRIMARY KEY, + description TEXT NOT NULL, + installed_on TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, + success BOOLEAN NOT NULL, + checksum BYTEA NOT NULL, + execution_time BIGINT NOT NULL +); +INSERT INTO _sqlx_migrations VALUES(20240612124932,'init','2025-06-13 20:01:04',1,X'42664ceda25b07bca420c2f7480c90334cb8a720203c1b4b8971181d5d3afabda3171aa89c1c0c8a26421eded94b77fa',921834); +INSERT INTO _sqlx_migrations VALUES(20240618195700,'quote state','2025-06-13 20:01:04',1,X'4b3a5a7f91032320f32b2c60a4348f0e80cef98fcf58153c4c942aa5124ddadce7c5c4338f29d2cb672fc4c08dd894a6',1019333); +INSERT INTO _sqlx_migrations VALUES(20240626092101,'nut04 state','2025-06-13 20:01:04',1,X'3641316faa018b13892d2972010b26a68d48b499aa67f8c084587265d070b575f541f165a9e2c5653b9c81a8dc198843',814000); +INSERT INTO _sqlx_migrations VALUES(20240703122347,'request lookup id','2025-06-13 20:01:04',1,X'234851aa0990048e119d07e9844f064ee71731c4e21021934e733359d6c50bc95a40051673f0a06e82d151c34fff6e8a',430875); +INSERT INTO _sqlx_migrations VALUES(20240710145043,'input fee','2025-06-13 20:01:04',1,X'422d4ce6a1d94c2df4a7fd9400c3d45db35953e53ba46025df7d3ed4d373e04f948468dcbcd8155829a5441f8b46d7f3',302916); +INSERT INTO _sqlx_migrations VALUES(20240711183109,'derivation path index','2025-06-13 20:01:04',1,X'83651c857135516fd578c5ee9f179a04964dc9a366a5b698c1cb54f2b5aa139dc912d34e28c5ff4cc157e6991032952f',225125); +INSERT INTO _sqlx_migrations VALUES(20240718203721,'allow unspent','2025-06-13 20:01:04',1,X'9b900846657b9083cdeca3da6ca7d74487c400f715f7d455c6a662de6b60e2761c3d80ea67d820e9b1ec9fbfd596e267',776167); +INSERT INTO _sqlx_migrations VALUES(20240811031111,'update mint url','2025-06-13 20:01:04',1,X'b8d771e08d3bbe3fc1e8beb1674714f0306d7f9f7cc09990fc0215850179a64366c8c46305ea0c1fb5dbc73a5fe48207',79334); +INSERT INTO _sqlx_migrations VALUES(20240919103407,'proofs quote id','2025-06-13 20:01:04',1,X'e3df13daebbc7df1907c68963258ad3722a0f2398f5ee1e92ea1824ce1a22f5657411f9c08a1f72bfd250e40630fdca5',387875); +INSERT INTO _sqlx_migrations VALUES(20240923153640,'melt requests','2025-06-13 20:01:04',1,X'8c35d740fbb1c0c13dc4594da50cce3e066cba2ff3926a5527629207678afe3a4fa3b7c8f5fab7e08525c676a4098154',188958); +INSERT INTO _sqlx_migrations VALUES(20240930101140,'dleq for sigs','2025-06-13 20:01:04',1,X'23c61a60db9bb145c238bb305583ccc025cd17958e61a6ff97ef0e4385517fe87729f77de0c26ce9cfa3a0c70b273038',383542); +INSERT INTO _sqlx_migrations VALUES(20241108093102,'mint mint quote pubkey','2025-06-13 20:01:04',1,X'00c83af91dc109368fcdc9a1360e1c893afcac3a649c7dfd04e841f1f8fe3d0e99a2ade6891ab752e1b942a738ac6b44',246875); +INSERT INTO _sqlx_migrations VALUES(20250103201327,'amount to pay msats','2025-06-13 20:01:04',1,X'4cc8bd34aec65365271e2dc2a19735403c8551dbf738b541659399c900fb167577d3f02b1988679e6c7922fe018b9a32',235041); +INSERT INTO _sqlx_migrations VALUES(20250129200912,'remove mint url','2025-06-13 20:01:04',1,X'f86b07a6b816683d72bdad637502a47cdeb21f6535aa8e2c0647d4b29f4f58931683b72062b3e313a5936264876bb2c3',638084); +INSERT INTO _sqlx_migrations VALUES(20250129230326,'add config table','2025-06-13 20:01:04',1,X'c232f4cfa032105cdd48097197d7fb0eea290a593af0996434c3f1f5396efb41d1f225592b292367fd9d584672a347d8',163625); +INSERT INTO _sqlx_migrations VALUES(20250307213652,'keyset id as foreign key','2025-06-13 20:01:04',1,X'50a36140780074b2730d429d664c2a7593f2c2237c1a36ed2a11e22c40bfa40b24dc3a5c8089959fae955fdbe2f06533',1498459); +INSERT INTO _sqlx_migrations VALUES(20250406091754,'mint time of quotes','2025-06-13 20:01:04',1,X'ac0165a8371cf7ad424be08c0e6931e1dd1249354ea0e33b4a04ff48ab4188da105e1fd763c42f06aeb733eb33d85415',934250); +INSERT INTO _sqlx_migrations VALUES(20250406093755,'mint created time signature','2025-06-13 20:01:04',1,X'7f2ff8e30f66ab142753cc2e0faec89560726d96298e9ce0c9e871974300fcbe7c2f8a9b2d48ed4ca8daf1b9a5043e95',447000); +INSERT INTO _sqlx_migrations VALUES(20250415093121,'drop keystore foreign','2025-06-13 20:01:04',1,X'efa99131d37335d64c86680c9e5b1362c2bf4d03fbdb6f60c9160edc572add6422d871f76a245d6f55f7fb6f4491b825',1375084); +CREATE TABLE keyset ( + id TEXT PRIMARY KEY, + unit TEXT NOT NULL, + active BOOL NOT NULL, + valid_from INTEGER NOT NULL, + valid_to INTEGER, + derivation_path TEXT NOT NULL, + max_order INTEGER NOT NULL +, input_fee_ppk INTEGER, derivation_path_index INTEGER); +INSERT INTO keyset VALUES('0083a60439303340','sat',1,1749844864,NULL,'0''/0''/0''',32,0,0); +INSERT INTO keyset VALUES('00b13456b2934304','auth',1,1749844864,NULL,'0''/4''/0''',1,0,0); +INSERT INTO keyset VALUES('0002c733628bb92f','usd',1,1749844864,NULL,'0''/2''/0''',32,0,0); +CREATE TABLE mint_quote ( + id TEXT PRIMARY KEY, + amount INTEGER NOT NULL, + unit TEXT NOT NULL, + request TEXT NOT NULL, + expiry INTEGER NOT NULL +, state TEXT CHECK ( state IN ('UNPAID', 'PENDING', 'PAID', 'ISSUED' ) ) NOT NULL DEFAULT 'UNPAID', request_lookup_id TEXT, pubkey TEXT, created_time INTEGER NOT NULL DEFAULT 0, paid_time INTEGER, issued_time INTEGER); +CREATE TABLE melt_quote ( + id TEXT PRIMARY KEY, + unit TEXT NOT NULL, + amount INTEGER NOT NULL, + request TEXT NOT NULL, + fee_reserve INTEGER NOT NULL, + expiry INTEGER NOT NULL +, state TEXT CHECK ( state IN ('UNPAID', 'PENDING', 'PAID' ) ) NOT NULL DEFAULT 'UNPAID', payment_preimage TEXT, request_lookup_id TEXT, msat_to_pay INTEGER, created_time INTEGER NOT NULL DEFAULT 0, paid_time INTEGER); +CREATE TABLE melt_request ( +id TEXT PRIMARY KEY, +inputs TEXT NOT NULL, +outputs TEXT, +method TEXT NOT NULL, +unit TEXT NOT NULL +); +CREATE TABLE config ( + id TEXT PRIMARY KEY, + value TEXT NOT NULL +); +CREATE TABLE IF NOT EXISTS "proof" ( + y BYTEA PRIMARY KEY, + amount INTEGER NOT NULL, + keyset_id TEXT NOT NULL, -- no FK constraint here + secret TEXT NOT NULL, + c BYTEA NOT NULL, + witness TEXT, + state TEXT CHECK (state IN ('SPENT', 'PENDING', 'UNSPENT', 'RESERVED', 'UNKNOWN')) NOT NULL, + quote_id TEXT, + created_time INTEGER NOT NULL DEFAULT 0 +); +CREATE TABLE IF NOT EXISTS "blind_signature" ( + y BYTEA PRIMARY KEY, + amount INTEGER NOT NULL, + keyset_id TEXT NOT NULL, -- FK removed + c BYTEA NOT NULL, + dleq_e TEXT, + dleq_s TEXT, + quote_id TEXT, + created_time INTEGER NOT NULL DEFAULT 0 +); +CREATE INDEX unit_index ON keyset(unit); +CREATE INDEX active_index ON keyset(active); +CREATE INDEX request_index ON mint_quote(request); +CREATE INDEX expiry_index ON mint_quote(expiry); +CREATE INDEX melt_quote_state_index ON melt_quote(state); +CREATE INDEX mint_quote_state_index ON mint_quote(state); +CREATE UNIQUE INDEX unique_request_lookup_id_mint ON mint_quote(request_lookup_id); +CREATE UNIQUE INDEX unique_request_lookup_id_melt ON melt_quote(request_lookup_id); +COMMIT; diff --git a/crates/cdk-sqlite/Cargo.toml b/crates/cdk-sqlite/Cargo.toml index 6cfb99a58..264271dde 100644 --- a/crates/cdk-sqlite/Cargo.toml +++ b/crates/cdk-sqlite/Cargo.toml @@ -13,18 +13,19 @@ readme = "README.md" # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html [features] default = ["mint", "wallet", "auth"] -mint = ["cdk-common/mint"] -wallet = ["cdk-common/wallet"] -auth = ["cdk-common/auth"] +mint = ["cdk-common/mint", "cdk-sql-common/mint"] +wallet = ["cdk-common/wallet", "cdk-sql-common/wallet"] +auth = ["cdk-common/auth", "cdk-sql-common/auth"] sqlcipher = ["rusqlite/bundled-sqlcipher"] [dependencies] async-trait.workspace = true cdk-common = { workspace = true, features = ["test"] } bitcoin.workspace = true +cdk-sql-common = { workspace = true } rusqlite = { version = "0.31", features = ["bundled"]} thiserror.workspace = true -tokio.workspace = true +tokio = { workspace = true, features = ["rt-multi-thread"]} tracing.workspace = true serde.workspace = true serde_json.workspace = true diff --git a/crates/cdk-sqlite/src/common.rs b/crates/cdk-sqlite/src/common.rs index e04a00def..bdde9bf34 100644 --- a/crates/cdk-sqlite/src/common.rs +++ b/crates/cdk-sqlite/src/common.rs @@ -1,12 +1,13 @@ +use std::sync::atomic::AtomicBool; use std::sync::Arc; use std::time::Duration; -use rusqlite::{params, Connection}; - -use crate::pool::{Pool, ResourceManager}; +use cdk_sql_common::pool::{self, Pool, ResourceManager}; +use cdk_sql_common::value::Value; +use rusqlite::Connection; /// The config need to create a new SQLite connection -#[derive(Debug)] +#[derive(Clone, Debug)] pub struct Config { path: Option, password: Option, @@ -25,7 +26,9 @@ impl ResourceManager for SqliteConnectionManager { fn new_resource( config: &Self::Config, - ) -> Result> { + _still_valid: Arc, + _timeout: Duration, + ) -> Result> { let conn = if let Some(path) = config.path.as_ref() { Connection::open(path)? } else { @@ -57,14 +60,8 @@ impl ResourceManager for SqliteConnectionManager { /// For SQLCipher support, enable the "sqlcipher" feature and pass a password. pub fn create_sqlite_pool( path: &str, - #[cfg(feature = "sqlcipher")] password: String, + password: Option, ) -> Arc> { - #[cfg(feature = "sqlcipher")] - let password = Some(password); - - #[cfg(not(feature = "sqlcipher"))] - let password = None; - let (config, max_size) = if path.contains(":memory:") { ( Config { @@ -86,52 +83,26 @@ pub fn create_sqlite_pool( Pool::new(config, max_size, Duration::from_secs(10)) } -/// Migrates the migration generated by `build.rs` -pub fn migrate(conn: &mut Connection, migrations: &[(&str, &str)]) -> Result<(), rusqlite::Error> { - let tx = conn.transaction()?; - tx.execute( - r#" - CREATE TABLE IF NOT EXISTS migrations ( - name TEXT PRIMARY KEY, - applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP - ) - "#, - [], - )?; - - if tx.query_row( - r#"select count(*) from sqlite_master where name = '_sqlx_migrations'"#, - [], - |row| row.get::<_, i32>(0), - )? == 1 - { - tx.execute_batch( - r#" - INSERT INTO migrations - SELECT - version || '_' || REPLACE(description, ' ', '_') || '.sql', - execution_time - FROM _sqlx_migrations; - DROP TABLE _sqlx_migrations; - "#, - )?; +/// Convert cdk_sql_common::value::Value to rusqlite Value +#[inline(always)] +pub fn to_sqlite(v: Value) -> rusqlite::types::Value { + match v { + Value::Blob(blob) => rusqlite::types::Value::Blob(blob), + Value::Integer(i) => rusqlite::types::Value::Integer(i), + Value::Null => rusqlite::types::Value::Null, + Value::Text(t) => rusqlite::types::Value::Text(t), + Value::Real(r) => rusqlite::types::Value::Real(r), } +} - // Apply each migration if it hasn’t been applied yet - for (name, sql) in migrations { - let already_applied: bool = tx.query_row( - "SELECT EXISTS(SELECT 1 FROM migrations WHERE name = ?1)", - params![name], - |row| row.get(0), - )?; - - if !already_applied { - tx.execute_batch(sql)?; - tx.execute("INSERT INTO migrations (name) VALUES (?1)", params![name])?; - } +/// Convert from rusqlite Valute to cdk_sql_common::value::Value +#[inline(always)] +pub fn from_sqlite(v: rusqlite::types::Value) -> Value { + match v { + rusqlite::types::Value::Blob(blob) => Value::Blob(blob), + rusqlite::types::Value::Integer(i) => Value::Integer(i), + rusqlite::types::Value::Null => Value::Null, + rusqlite::types::Value::Text(t) => Value::Text(t), + rusqlite::types::Value::Real(r) => Value::Real(r), } - - tx.commit()?; - - Ok(()) } diff --git a/crates/cdk-sqlite/src/lib.rs b/crates/cdk-sqlite/src/lib.rs index 0a4c56730..4c50a5ff2 100644 --- a/crates/cdk-sqlite/src/lib.rs +++ b/crates/cdk-sqlite/src/lib.rs @@ -4,9 +4,6 @@ #![warn(rustdoc::bare_urls)] mod common; -mod macros; -mod pool; -mod stmt; #[cfg(feature = "mint")] pub mod mint; diff --git a/crates/cdk-sqlite/src/mint/async_rusqlite.rs b/crates/cdk-sqlite/src/mint/async_rusqlite.rs index 3cd3593af..920660f9d 100644 --- a/crates/cdk-sqlite/src/mint/async_rusqlite.rs +++ b/crates/cdk-sqlite/src/mint/async_rusqlite.rs @@ -1,16 +1,20 @@ +//! Async, pipelined rusqlite client use std::marker::PhantomData; +use std::path::PathBuf; use std::sync::atomic::{AtomicUsize, Ordering}; use std::sync::{mpsc as std_mpsc, Arc, Mutex}; use std::thread::spawn; use std::time::Instant; +use cdk_common::database::Error; +use cdk_sql_common::database::{DatabaseConnector, DatabaseExecutor, DatabaseTransaction}; +use cdk_sql_common::pool::{self, Pool, PooledResource}; +use cdk_sql_common::stmt::{Column, ExpectedSqlResponse, Statement as InnerStatement}; +use cdk_sql_common::ConversionError; use rusqlite::{ffi, Connection, ErrorCode, TransactionBehavior}; use tokio::sync::{mpsc, oneshot}; -use crate::common::SqliteConnectionManager; -use crate::mint::Error; -use crate::pool::{Pool, PooledResource}; -use crate::stmt::{Column, ExpectedSqlResponse, Statement as InnerStatement, Value}; +use crate::common::{create_sqlite_pool, from_sqlite, to_sqlite, SqliteConnectionManager}; /// The number of queued SQL statements before it start failing const SQL_QUEUE_SIZE: usize = 10_000; @@ -25,9 +29,57 @@ pub struct AsyncRusqlite { inflight_requests: Arc, } +impl From for AsyncRusqlite { + fn from(value: PathBuf) -> Self { + AsyncRusqlite::new(create_sqlite_pool(value.to_str().unwrap_or_default(), None)) + } +} + +impl From<&str> for AsyncRusqlite { + fn from(value: &str) -> Self { + AsyncRusqlite::new(create_sqlite_pool(value, None)) + } +} + +impl From<(&str, &str)> for AsyncRusqlite { + fn from((value, pass): (&str, &str)) -> Self { + AsyncRusqlite::new(create_sqlite_pool(value, Some(pass.to_owned()))) + } +} + +impl From<(PathBuf, &str)> for AsyncRusqlite { + fn from((value, pass): (PathBuf, &str)) -> Self { + AsyncRusqlite::new(create_sqlite_pool( + value.to_str().unwrap_or_default(), + Some(pass.to_owned()), + )) + } +} + +impl From<(&str, String)> for AsyncRusqlite { + fn from((value, pass): (&str, String)) -> Self { + AsyncRusqlite::new(create_sqlite_pool(value, Some(pass))) + } +} + +impl From<(PathBuf, String)> for AsyncRusqlite { + fn from((value, pass): (PathBuf, String)) -> Self { + AsyncRusqlite::new(create_sqlite_pool( + value.to_str().unwrap_or_default(), + Some(pass), + )) + } +} + +impl From<&PathBuf> for AsyncRusqlite { + fn from(value: &PathBuf) -> Self { + AsyncRusqlite::new(create_sqlite_pool(value.to_str().unwrap_or_default(), None)) + } +} + /// Internal request for the database thread #[derive(Debug)] -pub enum DbRequest { +enum DbRequest { Sql(InnerStatement, oneshot::Sender), Begin(oneshot::Sender), Commit(oneshot::Sender), @@ -35,97 +87,67 @@ pub enum DbRequest { } #[derive(Debug)] -pub enum DbResponse { +enum DbResponse { Transaction(mpsc::Sender), AffectedRows(usize), Pluck(Option), Row(Option>), Rows(Vec>), - Error(Error), + Error(SqliteError), Unexpected, Ok, } -/// Statement for the async_rusqlite wrapper -pub struct Statement(InnerStatement); - -impl Statement { - /// Bind a variable - pub fn bind(self, name: C, value: V) -> Self - where - C: ToString, - V: Into, - { - Self(self.0.bind(name, value)) - } +#[derive(thiserror::Error, Debug)] +enum SqliteError { + #[error(transparent)] + Sqlite(#[from] rusqlite::Error), - /// Bind vec - pub fn bind_vec(self, name: C, value: Vec) -> Self - where - C: ToString, - V: Into, - { - Self(self.0.bind_vec(name, value)) - } + #[error(transparent)] + Inner(#[from] Error), - /// Executes a query and return the number of affected rows - pub async fn execute(self, conn: &C) -> Result - where - C: DatabaseExecutor + Send + Sync, - { - conn.execute(self.0).await - } + #[error(transparent)] + Pool(#[from] pool::Error), - /// Returns the first column of the first row of the query result - pub async fn pluck(self, conn: &C) -> Result, Error> - where - C: DatabaseExecutor + Send + Sync, - { - conn.pluck(self.0).await - } + /// Duplicate entry + #[error("Duplicate")] + Duplicate, - /// Returns the first row of the query result - pub async fn fetch_one(self, conn: &C) -> Result>, Error> - where - C: DatabaseExecutor + Send + Sync, - { - conn.fetch_one(self.0).await - } + #[error(transparent)] + Conversion(#[from] ConversionError), +} - /// Returns all rows of the query result - pub async fn fetch_all(self, conn: &C) -> Result>, Error> - where - C: DatabaseExecutor + Send + Sync, - { - conn.fetch_all(self.0).await +impl From for Error { + fn from(val: SqliteError) -> Self { + match val { + SqliteError::Duplicate => Error::Duplicate, + SqliteError::Conversion(e) => e.into(), + o => Error::Internal(o.to_string()), + } } } /// Process a query #[inline(always)] -fn process_query(conn: &Connection, sql: InnerStatement) -> Result { +fn process_query(conn: &Connection, statement: InnerStatement) -> Result { let start = Instant::now(); - let mut args = sql.args; - let mut stmt = conn.prepare_cached(&sql.sql)?; - let total_parameters = stmt.parameter_count(); - - for index in 1..=total_parameters { - let value = if let Some(value) = stmt.parameter_name(index).map(|name| { - args.remove(name) - .ok_or(Error::MissingParameter(name.to_owned())) - }) { - value? - } else { - continue; - }; + let expected_response = statement.expected_response; + let (sql, placeholder_values) = statement.to_sql()?; + let sql = sql.trim_end_matches("FOR UPDATE"); - stmt.raw_bind_parameter(index, value)?; + let mut stmt = conn.prepare_cached(sql)?; + for (i, value) in placeholder_values.into_iter().enumerate() { + stmt.raw_bind_parameter(i + 1, to_sqlite(value))?; } let columns = stmt.column_count(); - let to_return = match sql.expected_response { + let to_return = match expected_response { ExpectedSqlResponse::AffectedRows => DbResponse::AffectedRows(stmt.raw_execute()?), + ExpectedSqlResponse::Batch => { + conn.execute_batch(sql)?; + DbResponse::Ok + } ExpectedSqlResponse::ManyRows => { let mut rows = stmt.raw_query(); let mut results = vec![]; @@ -133,7 +155,7 @@ fn process_query(conn: &Connection, sql: InnerStatement) -> Result, _>>()?, ) } @@ -142,7 +164,11 @@ fn process_query(conn: &Connection, sql: InnerStatement) -> Result { let mut rows = stmt.raw_query(); - DbResponse::Pluck(rows.next()?.map(|row| row.get(0usize)).transpose()?) + DbResponse::Pluck( + rows.next()? + .map(|row| row.get(0usize).map(from_sqlite)) + .transpose()?, + ) } ExpectedSqlResponse::SingleRow => { let mut rows = stmt.raw_query(); @@ -150,7 +176,7 @@ fn process_query(conn: &Connection, sql: InnerStatement) -> Result, _>>() }) .transpose()?; @@ -161,7 +187,7 @@ fn process_query(conn: &Connection, sql: InnerStatement) -> Result SLOW_QUERY_THRESHOLD_MS { - tracing::warn!("[SLOW QUERY] Took {} ms: {}", duration.as_millis(), sql.sql); + tracing::warn!("[SLOW QUERY] Took {} ms: {}", duration.as_millis(), sql); } Ok(to_return) @@ -196,13 +222,12 @@ fn rusqlite_spawn_worker_threads( let inflight_requests = inflight_requests.clone(); spawn(move || loop { while let Ok((conn, sql, reply_to)) = rx.lock().expect("failed to acquire").recv() { - tracing::trace!("Execute query: {}", sql.sql); let result = process_query(&conn, sql); let _ = match result { Ok(ok) => reply_to.send(ok), Err(err) => { tracing::error!("Failed query with error {:?}", err); - let err = if let Error::Sqlite(rusqlite::Error::SqliteFailure( + let err = if let SqliteError::Sqlite(rusqlite::Error::SqliteFailure( ffi::Error { code, extended_code, @@ -214,7 +239,7 @@ fn rusqlite_spawn_worker_threads( && (*extended_code == ffi::SQLITE_CONSTRAINT_PRIMARYKEY || *extended_code == ffi::SQLITE_CONSTRAINT_UNIQUE) { - Error::Duplicate + SqliteError::Duplicate } else { err } @@ -256,7 +281,7 @@ fn rusqlite_worker_manager( while let Some(request) = receiver.blocking_recv() { inflight_requests.fetch_add(1, Ordering::Relaxed); match request { - DbRequest::Sql(sql, reply_to) => { + DbRequest::Sql(statement, reply_to) => { let conn = match pool.get() { Ok(conn) => conn, Err(err) => { @@ -267,7 +292,7 @@ fn rusqlite_worker_manager( } }; - let _ = send_sql_to_thread.send((conn, sql, reply_to)); + let _ = send_sql_to_thread.send((conn, statement, reply_to)); continue; } DbRequest::Begin(reply_to) => { @@ -341,9 +366,9 @@ fn rusqlite_worker_manager( DbRequest::Begin(reply_to) => { let _ = reply_to.send(DbResponse::Unexpected); } - DbRequest::Sql(sql, reply_to) => { - tracing::trace!("Tx {}: SQL {}", tx_id, sql.sql); - let _ = match process_query(&tx, sql) { + DbRequest::Sql(statement, reply_to) => { + tracing::trace!("Tx {}: SQL {:?}", tx_id, statement); + let _ = match process_query(&tx, statement) { Ok(ok) => reply_to.send(ok), Err(err) => { tracing::error!( @@ -351,7 +376,7 @@ fn rusqlite_worker_manager( tx_id, err ); - let err = if let Error::Sqlite( + let err = if let SqliteError::Sqlite( rusqlite::Error::SqliteFailure( ffi::Error { code, @@ -365,7 +390,7 @@ fn rusqlite_worker_manager( && (*extended_code == ffi::SQLITE_CONSTRAINT_PRIMARYKEY || *extended_code == ffi::SQLITE_CONSTRAINT_UNIQUE) { - Error::Duplicate + SqliteError::Duplicate } else { err } @@ -395,138 +420,171 @@ fn rusqlite_worker_manager( } } +impl AsyncRusqlite { + /// Creates a new Async Rusqlite wrapper. + pub fn new(pool: Arc>) -> Self { + let (sender, receiver) = mpsc::channel(SQL_QUEUE_SIZE); + let inflight_requests = Arc::new(AtomicUsize::new(0)); + let inflight_requests_for_thread = inflight_requests.clone(); + spawn(move || { + rusqlite_worker_manager(receiver, pool, inflight_requests_for_thread); + }); + + Self { + sender, + inflight_requests, + } + } + + fn get_queue_sender(&self) -> &mpsc::Sender { + &self.sender + } + + /// Show how many inflight requests + #[allow(dead_code)] + pub fn inflight_requests(&self) -> usize { + self.inflight_requests.load(Ordering::Relaxed) + } +} + #[async_trait::async_trait] -pub trait DatabaseExecutor { - /// Returns the connection to the database thread (or the on-going transaction) - fn get_queue_sender(&self) -> mpsc::Sender; +impl DatabaseConnector for AsyncRusqlite { + type Transaction<'a> = Transaction<'a>; - /// Executes a query and returns the affected rows - async fn execute(&self, mut statement: InnerStatement) -> Result { + /// Begins a transaction + /// + /// If the transaction is Drop it will trigger a rollback operation + async fn begin(&self) -> Result, Error> { let (sender, receiver) = oneshot::channel(); - statement.expected_response = ExpectedSqlResponse::AffectedRows; - self.get_queue_sender() - .send(DbRequest::Sql(statement, sender)) + self.sender + .send(DbRequest::Begin(sender)) .await - .map_err(|_| Error::Communication)?; + .map_err(|_| Error::Internal("Communication".to_owned()))?; - match receiver.await.map_err(|_| Error::Communication)? { - DbResponse::AffectedRows(n) => Ok(n), - DbResponse::Error(err) => Err(err), + match receiver + .await + .map_err(|_| Error::Internal("Communication".to_owned()))? + { + DbResponse::Transaction(db_sender) => Ok(Transaction { + db_sender, + _marker: PhantomData, + }), + DbResponse::Error(err) => Err(err.into()), _ => Err(Error::InvalidDbResponse), } } +} + +#[async_trait::async_trait] +impl DatabaseExecutor for AsyncRusqlite { + fn name() -> &'static str { + "sqlite" + } - /// Runs the query and returns the first row or None async fn fetch_one(&self, mut statement: InnerStatement) -> Result>, Error> { let (sender, receiver) = oneshot::channel(); statement.expected_response = ExpectedSqlResponse::SingleRow; self.get_queue_sender() .send(DbRequest::Sql(statement, sender)) .await - .map_err(|_| Error::Communication)?; + .map_err(|_| Error::Internal("Communication".to_owned()))?; - match receiver.await.map_err(|_| Error::Communication)? { + match receiver + .await + .map_err(|_| Error::Internal("Communication".to_owned()))? + { DbResponse::Row(row) => Ok(row), - DbResponse::Error(err) => Err(err), + DbResponse::Error(err) => Err(err.into()), _ => Err(Error::InvalidDbResponse), } } - /// Runs the query and returns the first row or None - async fn fetch_all(&self, mut statement: InnerStatement) -> Result>, Error> { + async fn batch(&self, mut statement: InnerStatement) -> Result<(), Error> { let (sender, receiver) = oneshot::channel(); - statement.expected_response = ExpectedSqlResponse::ManyRows; + statement.expected_response = ExpectedSqlResponse::Batch; self.get_queue_sender() .send(DbRequest::Sql(statement, sender)) .await - .map_err(|_| Error::Communication)?; + .map_err(|_| Error::Internal("Communication".to_owned()))?; - match receiver.await.map_err(|_| Error::Communication)? { - DbResponse::Rows(rows) => Ok(rows), - DbResponse::Error(err) => Err(err), + match receiver + .await + .map_err(|_| Error::Internal("Communication".to_owned()))? + { + DbResponse::Ok => Ok(()), + DbResponse::Error(err) => Err(err.into()), _ => Err(Error::InvalidDbResponse), } } - async fn pluck(&self, mut statement: InnerStatement) -> Result, Error> { + async fn fetch_all(&self, mut statement: InnerStatement) -> Result>, Error> { let (sender, receiver) = oneshot::channel(); - statement.expected_response = ExpectedSqlResponse::Pluck; + statement.expected_response = ExpectedSqlResponse::ManyRows; self.get_queue_sender() .send(DbRequest::Sql(statement, sender)) .await - .map_err(|_| Error::Communication)?; + .map_err(|_| Error::Internal("Communication".to_owned()))?; - match receiver.await.map_err(|_| Error::Communication)? { - DbResponse::Pluck(value) => Ok(value), - DbResponse::Error(err) => Err(err), + match receiver + .await + .map_err(|_| Error::Internal("Communication".to_owned()))? + { + DbResponse::Rows(row) => Ok(row), + DbResponse::Error(err) => Err(err.into()), _ => Err(Error::InvalidDbResponse), } } -} - -#[inline(always)] -pub fn query(sql: T) -> Statement -where - T: ToString, -{ - Statement(crate::stmt::Statement::new(sql)) -} -impl AsyncRusqlite { - /// Creates a new Async Rusqlite wrapper. - pub fn new(pool: Arc>) -> Self { - let (sender, receiver) = mpsc::channel(SQL_QUEUE_SIZE); - let inflight_requests = Arc::new(AtomicUsize::new(0)); - let inflight_requests_for_thread = inflight_requests.clone(); - spawn(move || { - rusqlite_worker_manager(receiver, pool, inflight_requests_for_thread); - }); + async fn execute(&self, mut statement: InnerStatement) -> Result { + let (sender, receiver) = oneshot::channel(); + statement.expected_response = ExpectedSqlResponse::AffectedRows; + self.get_queue_sender() + .send(DbRequest::Sql(statement, sender)) + .await + .map_err(|_| Error::Internal("Communication".to_owned()))?; - Self { - sender, - inflight_requests, + match receiver + .await + .map_err(|_| Error::Internal("Communication".to_owned()))? + { + DbResponse::AffectedRows(total) => Ok(total), + DbResponse::Error(err) => Err(err.into()), + _ => Err(Error::InvalidDbResponse), } } - /// Show how many inflight requests - #[allow(dead_code)] - pub fn inflight_requests(&self) -> usize { - self.inflight_requests.load(Ordering::Relaxed) - } - - /// Begins a transaction - /// - /// If the transaction is Drop it will trigger a rollback operation - pub async fn begin(&self) -> Result, Error> { + async fn pluck(&self, mut statement: InnerStatement) -> Result, Error> { let (sender, receiver) = oneshot::channel(); - self.sender - .send(DbRequest::Begin(sender)) + statement.expected_response = ExpectedSqlResponse::Pluck; + self.get_queue_sender() + .send(DbRequest::Sql(statement, sender)) .await - .map_err(|_| Error::Communication)?; + .map_err(|_| Error::Internal("Communication".to_owned()))?; - match receiver.await.map_err(|_| Error::Communication)? { - DbResponse::Transaction(db_sender) => Ok(Transaction { - db_sender, - _marker: PhantomData, - }), - DbResponse::Error(err) => Err(err), + match receiver + .await + .map_err(|_| Error::Internal("Communication".to_owned()))? + { + DbResponse::Pluck(value) => Ok(value), + DbResponse::Error(err) => Err(err.into()), _ => Err(Error::InvalidDbResponse), } } } -impl DatabaseExecutor for AsyncRusqlite { - #[inline(always)] - fn get_queue_sender(&self) -> mpsc::Sender { - self.sender.clone() - } -} - +/// Database transaction +#[derive(Debug)] pub struct Transaction<'conn> { db_sender: mpsc::Sender, _marker: PhantomData<&'conn ()>, } +impl Transaction<'_> { + fn get_queue_sender(&self) -> &mpsc::Sender { + &self.db_sender + } +} + impl Drop for Transaction<'_> { fn drop(&mut self) { let (sender, _) = oneshot::channel(); @@ -534,40 +592,136 @@ impl Drop for Transaction<'_> { } } -impl Transaction<'_> { - pub async fn commit(self) -> Result<(), Error> { +#[async_trait::async_trait] +impl<'a> DatabaseTransaction<'a> for Transaction<'a> { + async fn commit(self) -> Result<(), Error> { let (sender, receiver) = oneshot::channel(); self.db_sender .send(DbRequest::Commit(sender)) .await - .map_err(|_| Error::Communication)?; + .map_err(|_| Error::Internal("Communication".to_owned()))?; - match receiver.await.map_err(|_| Error::Communication)? { + match receiver + .await + .map_err(|_| Error::Internal("Communication".to_owned()))? + { DbResponse::Ok => Ok(()), - DbResponse::Error(err) => Err(err), + DbResponse::Error(err) => Err(err.into()), _ => Err(Error::InvalidDbResponse), } } - pub async fn rollback(self) -> Result<(), Error> { + async fn rollback(self) -> Result<(), Error> { let (sender, receiver) = oneshot::channel(); self.db_sender .send(DbRequest::Rollback(sender)) .await - .map_err(|_| Error::Communication)?; + .map_err(|_| Error::Internal("Communication".to_owned()))?; - match receiver.await.map_err(|_| Error::Communication)? { + match receiver + .await + .map_err(|_| Error::Internal("Communication".to_owned()))? + { DbResponse::Ok => Ok(()), - DbResponse::Error(err) => Err(err), + DbResponse::Error(err) => Err(err.into()), _ => Err(Error::InvalidDbResponse), } } } +#[async_trait::async_trait] impl DatabaseExecutor for Transaction<'_> { - /// Get the internal sender to the SQL queue - #[inline(always)] - fn get_queue_sender(&self) -> mpsc::Sender { - self.db_sender.clone() + fn name() -> &'static str { + "sqlite" + } + + async fn fetch_one(&self, mut statement: InnerStatement) -> Result>, Error> { + let (sender, receiver) = oneshot::channel(); + statement.expected_response = ExpectedSqlResponse::SingleRow; + self.get_queue_sender() + .send(DbRequest::Sql(statement, sender)) + .await + .map_err(|_| Error::Internal("Communication".to_owned()))?; + + match receiver + .await + .map_err(|_| Error::Internal("Communication".to_owned()))? + { + DbResponse::Row(row) => Ok(row), + DbResponse::Error(err) => Err(err.into()), + _ => Err(Error::InvalidDbResponse), + } + } + + async fn batch(&self, mut statement: InnerStatement) -> Result<(), Error> { + let (sender, receiver) = oneshot::channel(); + statement.expected_response = ExpectedSqlResponse::Batch; + self.get_queue_sender() + .send(DbRequest::Sql(statement, sender)) + .await + .map_err(|_| Error::Internal("Communication".to_owned()))?; + + match receiver + .await + .map_err(|_| Error::Internal("Communication".to_owned()))? + { + DbResponse::Ok => Ok(()), + DbResponse::Error(err) => Err(err.into()), + _ => Err(Error::InvalidDbResponse), + } + } + + async fn fetch_all(&self, mut statement: InnerStatement) -> Result>, Error> { + let (sender, receiver) = oneshot::channel(); + statement.expected_response = ExpectedSqlResponse::ManyRows; + self.get_queue_sender() + .send(DbRequest::Sql(statement, sender)) + .await + .map_err(|_| Error::Internal("Communication".to_owned()))?; + + match receiver + .await + .map_err(|_| Error::Internal("Communication".to_owned()))? + { + DbResponse::Rows(row) => Ok(row), + DbResponse::Error(err) => Err(err.into()), + _ => Err(Error::InvalidDbResponse), + } + } + + async fn execute(&self, mut statement: InnerStatement) -> Result { + let (sender, receiver) = oneshot::channel(); + statement.expected_response = ExpectedSqlResponse::AffectedRows; + self.get_queue_sender() + .send(DbRequest::Sql(statement, sender)) + .await + .map_err(|_| Error::Internal("Communication".to_owned()))?; + + match receiver + .await + .map_err(|_| Error::Internal("Communication".to_owned()))? + { + DbResponse::AffectedRows(total) => Ok(total), + DbResponse::Error(err) => Err(err.into()), + _ => Err(Error::InvalidDbResponse), + } + } + + async fn pluck(&self, mut statement: InnerStatement) -> Result, Error> { + let (sender, receiver) = oneshot::channel(); + statement.expected_response = ExpectedSqlResponse::Pluck; + self.get_queue_sender() + .send(DbRequest::Sql(statement, sender)) + .await + .map_err(|_| Error::Internal("Communication".to_owned()))?; + + match receiver + .await + .map_err(|_| Error::Internal("Communication".to_owned()))? + { + DbResponse::Pluck(value) => Ok(value), + DbResponse::Error(err) => Err(err.into()), + _ => Err(Error::InvalidDbResponse), + } } } diff --git a/crates/cdk-sqlite/src/mint/auth/migrations.rs b/crates/cdk-sqlite/src/mint/auth/migrations.rs deleted file mode 100644 index 4edbb850c..000000000 --- a/crates/cdk-sqlite/src/mint/auth/migrations.rs +++ /dev/null @@ -1,5 +0,0 @@ -// @generated -// Auto-generated by build.rs -pub static MIGRATIONS: &[(&str, &str)] = &[ - ("20250109143347_init.sql", include_str!(r#"./migrations/20250109143347_init.sql"#)), -]; diff --git a/crates/cdk-sqlite/src/mint/error.rs b/crates/cdk-sqlite/src/mint/error.rs deleted file mode 100644 index cbc104485..000000000 --- a/crates/cdk-sqlite/src/mint/error.rs +++ /dev/null @@ -1,116 +0,0 @@ -//! SQLite Database Error - -use thiserror::Error; - -/// SQLite Database Error -#[derive(Debug, Error)] -pub enum Error { - /// SQLX Error - #[error(transparent)] - Sqlite(#[from] rusqlite::Error), - - /// Duplicate entry - #[error("Record already exists")] - Duplicate, - - /// Pool error - #[error(transparent)] - Pool(#[from] crate::pool::Error), - /// Invalid UUID - #[error("Invalid UUID: {0}")] - InvalidUuid(String), - /// QuoteNotFound - #[error("Quote not found")] - QuoteNotFound, - - /// Missing named parameter - #[error("Missing named parameter {0}")] - MissingParameter(String), - - /// Communication error with the database - #[error("Internal communication error")] - Communication, - - /// Invalid response from the database thread - #[error("Unexpected database response")] - InvalidDbResponse, - - /// Invalid db type - #[error("Invalid type from db, expected {0} got {1}")] - InvalidType(String, String), - - /// Missing columns - #[error("Not enough elements: expected {0}, got {1}")] - MissingColumn(usize, usize), - - /// Invalid data conversion in column - #[error("Error converting {0} to {1}")] - InvalidConversion(String, String), - - /// NUT00 Error - #[error(transparent)] - CDKNUT00(#[from] cdk_common::nuts::nut00::Error), - /// NUT01 Error - #[error(transparent)] - CDKNUT01(#[from] cdk_common::nuts::nut01::Error), - /// NUT02 Error - #[error(transparent)] - CDKNUT02(#[from] cdk_common::nuts::nut02::Error), - /// NUT04 Error - #[error(transparent)] - CDKNUT04(#[from] cdk_common::nuts::nut04::Error), - /// NUT05 Error - #[error(transparent)] - CDKNUT05(#[from] cdk_common::nuts::nut05::Error), - /// NUT07 Error - #[error(transparent)] - CDKNUT07(#[from] cdk_common::nuts::nut07::Error), - /// NUT23 Error - #[error(transparent)] - CDKNUT23(#[from] cdk_common::nuts::nut23::Error), - /// Secret Error - #[error(transparent)] - CDKSECRET(#[from] cdk_common::secret::Error), - /// BIP32 Error - #[error(transparent)] - BIP32(#[from] bitcoin::bip32::Error), - /// Mint Url Error - #[error(transparent)] - MintUrl(#[from] cdk_common::mint_url::Error), - /// Could Not Initialize Database - #[error("Could not initialize database")] - CouldNotInitialize, - /// Invalid Database Path - #[error("Invalid database path")] - InvalidDbPath, - /// Serde Error - #[error(transparent)] - Serde(#[from] serde_json::Error), - /// Unknown Mint Info - #[error("Unknown mint info")] - UnknownMintInfo, - /// Unknown quote TTL - #[error("Unknown quote TTL")] - UnknownQuoteTTL, - /// Unknown config key - #[error("Unknown config key: {0}")] - UnknownConfigKey(String), - /// Proof not found - #[error("Proof not found")] - ProofNotFound, - /// Invalid keyset ID - #[error("Invalid keyset ID")] - InvalidKeysetId, - /// Invalid melt payment request - #[error("Invalid melt payment request")] - InvalidMeltPaymentRequest, -} - -impl From for cdk_common::database::Error { - fn from(e: Error) -> Self { - match e { - Error::Duplicate => Self::Duplicate, - e => Self::Database(Box::new(e)), - } - } -} diff --git a/crates/cdk-sqlite/src/mint/memory.rs b/crates/cdk-sqlite/src/mint/memory.rs index 548644431..7bbb718b2 100644 --- a/crates/cdk-sqlite/src/mint/memory.rs +++ b/crates/cdk-sqlite/src/mint/memory.rs @@ -11,10 +11,11 @@ use super::MintSqliteDatabase; /// Creates a new in-memory [`MintSqliteDatabase`] instance pub async fn empty() -> Result { #[cfg(not(feature = "sqlcipher"))] - let db = MintSqliteDatabase::new(":memory:").await?; + let path = ":memory:"; #[cfg(feature = "sqlcipher")] - let db = MintSqliteDatabase::new(":memory:", "memory".to_string()).await?; - Ok(db) + let path = (":memory:", "memory"); + + MintSqliteDatabase::new(path).await } /// Creates a new in-memory [`MintSqliteDatabase`] instance with the given state diff --git a/crates/cdk-sqlite/src/mint/migrations.rs b/crates/cdk-sqlite/src/mint/migrations.rs deleted file mode 100644 index d8e93c90f..000000000 --- a/crates/cdk-sqlite/src/mint/migrations.rs +++ /dev/null @@ -1,25 +0,0 @@ -// @generated -// Auto-generated by build.rs -pub static MIGRATIONS: &[(&str, &str)] = &[ - ("20240612124932_init.sql", include_str!(r#"./migrations/20240612124932_init.sql"#)), - ("20240618195700_quote_state.sql", include_str!(r#"./migrations/20240618195700_quote_state.sql"#)), - ("20240626092101_nut04_state.sql", include_str!(r#"./migrations/20240626092101_nut04_state.sql"#)), - ("20240703122347_request_lookup_id.sql", include_str!(r#"./migrations/20240703122347_request_lookup_id.sql"#)), - ("20240710145043_input_fee.sql", include_str!(r#"./migrations/20240710145043_input_fee.sql"#)), - ("20240711183109_derivation_path_index.sql", include_str!(r#"./migrations/20240711183109_derivation_path_index.sql"#)), - ("20240718203721_allow_unspent.sql", include_str!(r#"./migrations/20240718203721_allow_unspent.sql"#)), - ("20240811031111_update_mint_url.sql", include_str!(r#"./migrations/20240811031111_update_mint_url.sql"#)), - ("20240919103407_proofs_quote_id.sql", include_str!(r#"./migrations/20240919103407_proofs_quote_id.sql"#)), - ("20240923153640_melt_requests.sql", include_str!(r#"./migrations/20240923153640_melt_requests.sql"#)), - ("20240930101140_dleq_for_sigs.sql", include_str!(r#"./migrations/20240930101140_dleq_for_sigs.sql"#)), - ("20241108093102_mint_mint_quote_pubkey.sql", include_str!(r#"./migrations/20241108093102_mint_mint_quote_pubkey.sql"#)), - ("20250103201327_amount_to_pay_msats.sql", include_str!(r#"./migrations/20250103201327_amount_to_pay_msats.sql"#)), - ("20250129200912_remove_mint_url.sql", include_str!(r#"./migrations/20250129200912_remove_mint_url.sql"#)), - ("20250129230326_add_config_table.sql", include_str!(r#"./migrations/20250129230326_add_config_table.sql"#)), - ("20250307213652_keyset_id_as_foreign_key.sql", include_str!(r#"./migrations/20250307213652_keyset_id_as_foreign_key.sql"#)), - ("20250406091754_mint_time_of_quotes.sql", include_str!(r#"./migrations/20250406091754_mint_time_of_quotes.sql"#)), - ("20250406093755_mint_created_time_signature.sql", include_str!(r#"./migrations/20250406093755_mint_created_time_signature.sql"#)), - ("20250415093121_drop_keystore_foreign.sql", include_str!(r#"./migrations/20250415093121_drop_keystore_foreign.sql"#)), - ("20250626120251_rename_blind_message_y_to_b.sql", include_str!(r#"./migrations/20250626120251_rename_blind_message_y_to_b.sql"#)), - ("20250706101057_bolt12.sql", include_str!(r#"./migrations/20250706101057_bolt12.sql"#)), -]; diff --git a/crates/cdk-sqlite/src/mint/mod.rs b/crates/cdk-sqlite/src/mint/mod.rs index b0251b04b..acfa09583 100644 --- a/crates/cdk-sqlite/src/mint/mod.rs +++ b/crates/cdk-sqlite/src/mint/mod.rs @@ -1,1913 +1,28 @@ //! SQLite Mint -use std::collections::HashMap; -use std::ops::DerefMut; -use std::path::Path; -use std::str::FromStr; - -use async_rusqlite::{query, DatabaseExecutor, Transaction}; -use async_trait::async_trait; -use bitcoin::bip32::DerivationPath; -use cdk_common::common::QuoteTTL; -use cdk_common::database::{ - self, MintDatabase, MintDbWriterFinalizer, MintKeyDatabaseTransaction, MintKeysDatabase, - MintProofsDatabase, MintProofsTransaction, MintQuotesDatabase, MintQuotesTransaction, - MintSignatureTransaction, MintSignaturesDatabase, -}; -use cdk_common::mint::{ - self, IncomingPayment, Issuance, MeltPaymentRequest, MeltQuote, MintKeySetInfo, MintQuote, -}; -use cdk_common::nut00::ProofsMethods; -use cdk_common::payment::PaymentIdentifier; -use cdk_common::secret::Secret; -use cdk_common::state::check_state_transition; -use cdk_common::util::unix_time; -use cdk_common::{ - Amount, BlindSignature, BlindSignatureDleq, CurrencyUnit, Id, MeltQuoteState, MintInfo, - PaymentMethod, Proof, Proofs, PublicKey, SecretKey, State, -}; -use error::Error; -use lightning_invoice::Bolt11Invoice; -use tracing::instrument; -use uuid::Uuid; - -use crate::common::{create_sqlite_pool, migrate}; -use crate::stmt::Column; -use crate::{ - column_as_nullable_number, column_as_nullable_string, column_as_number, column_as_string, - unpack_into, -}; +use cdk_sql_common::mint::SQLMintAuthDatabase; +use cdk_sql_common::SQLMintDatabase; mod async_rusqlite; -#[cfg(feature = "auth")] -mod auth; -pub mod error; + pub mod memory; -#[rustfmt::skip] -mod migrations; +/// Mint SQLite implementation with rusqlite +pub type MintSqliteDatabase = SQLMintDatabase; +/// Mint Auth database with rusqlite #[cfg(feature = "auth")] -pub use auth::MintSqliteAuthDatabase; - -/// Mint SQLite Database -#[derive(Debug, Clone)] -pub struct MintSqliteDatabase { - pool: async_rusqlite::AsyncRusqlite, -} - -#[inline(always)] -async fn get_current_states( - conn: &C, - ys: &[PublicKey], -) -> Result, Error> -where - C: DatabaseExecutor + Send + Sync, -{ - query(r#"SELECT y, state FROM proof WHERE y IN (:ys)"#) - .bind_vec(":ys", ys.iter().map(|y| y.to_bytes().to_vec()).collect()) - .fetch_all(conn) - .await? - .into_iter() - .map(|row| { - Ok(( - column_as_string!(&row[0], PublicKey::from_hex, PublicKey::from_slice), - column_as_string!(&row[1], State::from_str), - )) - }) - .collect::, _>>() -} - -#[inline(always)] -async fn set_to_config(conn: &C, id: &str, value: &T) -> Result<(), Error> -where - T: ?Sized + serde::Serialize, - C: DatabaseExecutor + Send + Sync, -{ - query( - r#" - INSERT INTO config (id, value) VALUES (:id, :value) - ON CONFLICT(id) DO UPDATE SET value = excluded.value - "#, - ) - .bind(":id", id.to_owned()) - .bind(":value", serde_json::to_string(&value)?) - .execute(conn) - .await?; - - Ok(()) -} - -#[inline(always)] -async fn get_mint_quote_payments( - conn: &C, - quote_id: &Uuid, -) -> Result, Error> -where - C: DatabaseExecutor + Send + Sync, -{ - // Get payment IDs and timestamps from the mint_quote_payments table - query( - r#" -SELECT payment_id, timestamp, amount -FROM mint_quote_payments -WHERE quote_id=:quote_id; - "#, - ) - .bind(":quote_id", quote_id.as_hyphenated().to_string()) - .fetch_all(conn) - .await? - .into_iter() - .map(|row| { - let amount: u64 = column_as_number!(row[2].clone()); - let time: u64 = column_as_number!(row[1].clone()); - Ok(IncomingPayment::new( - amount.into(), - column_as_string!(&row[0]), - time, - )) - }) - .collect() -} - -#[inline(always)] -async fn get_mint_quote_issuance(conn: &C, quote_id: &Uuid) -> Result, Error> -where - C: DatabaseExecutor + Send + Sync, -{ - // Get payment IDs and timestamps from the mint_quote_payments table - query( - r#" -SELECT amount, timestamp -FROM mint_quote_issued -WHERE quote_id=:quote_id; - "#, - ) - .bind(":quote_id", quote_id.as_hyphenated().to_string()) - .fetch_all(conn) - .await? - .into_iter() - .map(|row| { - let time: u64 = column_as_number!(row[1].clone()); - Ok(Issuance::new( - Amount::from_i64(column_as_number!(row[0].clone())) - .expect("Is amount when put into db"), - time, - )) - }) - .collect() -} - -impl MintSqliteDatabase { - /// Create new [`MintSqliteDatabase`] - #[cfg(not(feature = "sqlcipher"))] - pub async fn new>(path: P) -> Result { - let pool = create_sqlite_pool(path.as_ref().to_str().ok_or(Error::InvalidDbPath)?); - migrate(pool.get()?.deref_mut(), migrations::MIGRATIONS)?; - - Ok(Self { - pool: async_rusqlite::AsyncRusqlite::new(pool), - }) - } - - /// Create new [`MintSqliteDatabase`] - #[cfg(feature = "sqlcipher")] - pub async fn new>(path: P, password: String) -> Result { - let pool = create_sqlite_pool( - path.as_ref().to_str().ok_or(Error::InvalidDbPath)?, - password, - ); - migrate(pool.get()?.deref_mut(), migrations::MIGRATIONS)?; - - Ok(Self { - pool: async_rusqlite::AsyncRusqlite::new(pool), - }) - } - - #[inline(always)] - async fn fetch_from_config(&self, id: &str) -> Result - where - T: serde::de::DeserializeOwned, - { - let value = column_as_string!(query(r#"SELECT value FROM config WHERE id = :id LIMIT 1"#) - .bind(":id", id.to_owned()) - .pluck(&self.pool) - .await? - .ok_or_else(|| match id { - "mint_info" => Error::UnknownMintInfo, - "quote_ttl" => Error::UnknownQuoteTTL, - unknown => Error::UnknownConfigKey(unknown.to_string()), - })?); - - Ok(serde_json::from_str(&value)?) - } -} - -/// Sqlite Writer -pub struct SqliteTransaction<'a> { - inner: Transaction<'a>, -} - -#[async_trait] -impl<'a> database::MintTransaction<'a, database::Error> for SqliteTransaction<'a> { - async fn set_mint_info(&mut self, mint_info: MintInfo) -> Result<(), database::Error> { - Ok(set_to_config(&self.inner, "mint_info", &mint_info).await?) - } - - async fn set_quote_ttl(&mut self, quote_ttl: QuoteTTL) -> Result<(), database::Error> { - Ok(set_to_config(&self.inner, "quote_ttl", "e_ttl).await?) - } -} - -#[async_trait] -impl MintDbWriterFinalizer for SqliteTransaction<'_> { - type Err = database::Error; - - async fn commit(self: Box) -> Result<(), database::Error> { - Ok(self.inner.commit().await?) - } - - async fn rollback(self: Box) -> Result<(), database::Error> { - Ok(self.inner.rollback().await?) - } -} - -#[async_trait] -impl<'a> MintKeyDatabaseTransaction<'a, database::Error> for SqliteTransaction<'a> { - async fn add_keyset_info(&mut self, keyset: MintKeySetInfo) -> Result<(), database::Error> { - query( - r#" - INSERT INTO - keyset ( - id, unit, active, valid_from, valid_to, derivation_path, - max_order, input_fee_ppk, derivation_path_index - ) - VALUES ( - :id, :unit, :active, :valid_from, :valid_to, :derivation_path, - :max_order, :input_fee_ppk, :derivation_path_index - ) - ON CONFLICT(id) DO UPDATE SET - unit = excluded.unit, - active = excluded.active, - valid_from = excluded.valid_from, - valid_to = excluded.valid_to, - derivation_path = excluded.derivation_path, - max_order = excluded.max_order, - input_fee_ppk = excluded.input_fee_ppk, - derivation_path_index = excluded.derivation_path_index - "#, - ) - .bind(":id", keyset.id.to_string()) - .bind(":unit", keyset.unit.to_string()) - .bind(":active", keyset.active) - .bind(":valid_from", keyset.valid_from as i64) - .bind(":valid_to", keyset.final_expiry.map(|v| v as i64)) - .bind(":derivation_path", keyset.derivation_path.to_string()) - .bind(":max_order", keyset.max_order) - .bind(":input_fee_ppk", keyset.input_fee_ppk as i64) - .bind(":derivation_path_index", keyset.derivation_path_index) - .execute(&self.inner) - .await?; - - Ok(()) - } - - async fn set_active_keyset( - &mut self, - unit: CurrencyUnit, - id: Id, - ) -> Result<(), database::Error> { - query(r#"UPDATE keyset SET active=FALSE WHERE unit IS :unit"#) - .bind(":unit", unit.to_string()) - .execute(&self.inner) - .await?; - - query(r#"UPDATE keyset SET active=TRUE WHERE unit IS :unit AND id IS :id"#) - .bind(":unit", unit.to_string()) - .bind(":id", id.to_string()) - .execute(&self.inner) - .await?; - - Ok(()) - } -} - -#[async_trait] -impl MintKeysDatabase for MintSqliteDatabase { - type Err = database::Error; - - async fn begin_transaction<'a>( - &'a self, - ) -> Result< - Box + Send + Sync + 'a>, - database::Error, - > { - Ok(Box::new(SqliteTransaction { - inner: self.pool.begin().await?, - })) - } - - async fn get_active_keyset_id(&self, unit: &CurrencyUnit) -> Result, Self::Err> { - Ok( - query(r#" SELECT id FROM keyset WHERE active = 1 AND unit IS :unit"#) - .bind(":unit", unit.to_string()) - .pluck(&self.pool) - .await? - .map(|id| match id { - Column::Text(text) => Ok(Id::from_str(&text)?), - Column::Blob(id) => Ok(Id::from_bytes(&id)?), - _ => Err(Error::InvalidKeysetId), - }) - .transpose()?, - ) - } - - async fn get_active_keysets(&self) -> Result, Self::Err> { - Ok(query(r#"SELECT id, unit FROM keyset WHERE active = 1"#) - .fetch_all(&self.pool) - .await? - .into_iter() - .map(|row| { - Ok(( - column_as_string!(&row[1], CurrencyUnit::from_str), - column_as_string!(&row[0], Id::from_str, Id::from_bytes), - )) - }) - .collect::, Error>>()?) - } - - async fn get_keyset_info(&self, id: &Id) -> Result, Self::Err> { - Ok(query( - r#"SELECT - id, - unit, - active, - valid_from, - valid_to, - derivation_path, - derivation_path_index, - max_order, - input_fee_ppk - FROM - keyset - WHERE id=:id"#, - ) - .bind(":id", id.to_string()) - .fetch_one(&self.pool) - .await? - .map(sqlite_row_to_keyset_info) - .transpose()?) - } - - async fn get_keyset_infos(&self) -> Result, Self::Err> { - Ok(query( - r#"SELECT - id, - unit, - active, - valid_from, - valid_to, - derivation_path, - derivation_path_index, - max_order, - input_fee_ppk - FROM - keyset - "#, - ) - .fetch_all(&self.pool) - .await? - .into_iter() - .map(sqlite_row_to_keyset_info) - .collect::, _>>()?) - } -} - -#[async_trait] -impl<'a> MintQuotesTransaction<'a> for SqliteTransaction<'a> { - type Err = database::Error; - - #[instrument(skip(self))] - async fn increment_mint_quote_amount_paid( - &mut self, - quote_id: &Uuid, - amount_paid: Amount, - payment_id: String, - ) -> Result { - // Check if payment_id already exists in mint_quote_payments - let exists = query( - r#" - SELECT payment_id - FROM mint_quote_payments - WHERE payment_id = :payment_id - "#, - ) - .bind(":payment_id", payment_id.clone()) - .fetch_one(&self.inner) - .await?; - - if exists.is_some() { - tracing::error!("Payment ID already exists: {}", payment_id); - return Err(database::Error::Duplicate); - } - - // Get current amount_paid from quote - let current_amount = query( - r#" - SELECT amount_paid - FROM mint_quote - WHERE id = :quote_id - "#, - ) - .bind(":quote_id", quote_id.as_hyphenated().to_string()) - .fetch_one(&self.inner) - .await - .map_err(|err| { - tracing::error!("SQLite could not get mint quote amount_paid"); - err - })?; - - let current_amount_paid = if let Some(current_amount) = current_amount { - let amount: u64 = column_as_number!(current_amount[0].clone()); - Amount::from(amount) - } else { - Amount::ZERO - }; - - // Calculate new amount_paid with overflow check - let new_amount_paid = current_amount_paid - .checked_add(amount_paid) - .ok_or_else(|| database::Error::AmountOverflow)?; - - // Update the amount_paid - query( - r#" - UPDATE mint_quote - SET amount_paid = :amount_paid - WHERE id = :quote_id - "#, - ) - .bind(":amount_paid", new_amount_paid.to_i64()) - .bind(":quote_id", quote_id.as_hyphenated().to_string()) - .execute(&self.inner) - .await - .map_err(|err| { - tracing::error!("SQLite could not update mint quote amount_paid"); - err - })?; - - // Add payment_id to mint_quote_payments table - query( - r#" - INSERT INTO mint_quote_payments - (quote_id, payment_id, amount, timestamp) - VALUES (:quote_id, :payment_id, :amount, :timestamp) - "#, - ) - .bind(":quote_id", quote_id.as_hyphenated().to_string()) - .bind(":payment_id", payment_id) - .bind(":amount", amount_paid.to_i64()) - .bind(":timestamp", unix_time() as i64) - .execute(&self.inner) - .await - .map_err(|err| { - tracing::error!("SQLite could not insert payment ID: {}", err); - err - })?; - - Ok(new_amount_paid) - } - - #[instrument(skip_all)] - async fn increment_mint_quote_amount_issued( - &mut self, - quote_id: &Uuid, - amount_issued: Amount, - ) -> Result { - // Get current amount_issued from quote - let current_amount = query( - r#" - SELECT amount_issued - FROM mint_quote - WHERE id = :quote_id - "#, - ) - .bind(":quote_id", quote_id.as_hyphenated().to_string()) - .fetch_one(&self.inner) - .await - .map_err(|err| { - tracing::error!("SQLite could not get mint quote amount_issued"); - err - })?; - - let current_amount_issued = if let Some(current_amount) = current_amount { - let amount: u64 = column_as_number!(current_amount[0].clone()); - Amount::from(amount) - } else { - Amount::ZERO - }; - - // Calculate new amount_issued with overflow check - let new_amount_issued = current_amount_issued - .checked_add(amount_issued) - .ok_or_else(|| database::Error::AmountOverflow)?; - - // Update the amount_issued - query( - r#" - UPDATE mint_quote - SET amount_issued = :amount_issued - WHERE id = :quote_id - "#, - ) - .bind(":amount_issued", new_amount_issued.to_i64()) - .bind(":quote_id", quote_id.as_hyphenated().to_string()) - .execute(&self.inner) - .await - .map_err(|err| { - tracing::error!("SQLite could not update mint quote amount_issued"); - err - })?; - - let current_time = unix_time(); - - query( - r#" -INSERT INTO mint_quote_issued -(quote_id, amount, timestamp) -VALUES (:quote_id, :amount, :timestamp); - "#, - ) - .bind(":quote_id", quote_id.as_hyphenated().to_string()) - .bind(":amount", amount_issued.to_i64()) - .bind(":timestamp", current_time as i64) - .execute(&self.inner) - .await?; - - Ok(new_amount_issued) - } - - #[instrument(skip_all)] - async fn add_mint_quote(&mut self, quote: MintQuote) -> Result<(), Self::Err> { - tracing::debug!("Adding quote with: {}", quote.payment_method.to_string()); - println!("Adding quote with: {}", quote.payment_method.to_string()); - query( - r#" - INSERT INTO mint_quote ( - id, amount, unit, request, expiry, request_lookup_id, pubkey, created_time, payment_method, request_lookup_id_kind - ) - VALUES ( - :id, :amount, :unit, :request, :expiry, :request_lookup_id, :pubkey, :created_time, :payment_method, :request_lookup_id_kind - ) - "#, - ) - .bind(":id", quote.id.to_string()) - .bind(":amount", quote.amount.map(|a| a.to_i64())) - .bind(":unit", quote.unit.to_string()) - .bind(":request", quote.request) - .bind(":expiry", quote.expiry as i64) - .bind( - ":request_lookup_id", - quote.request_lookup_id.to_string(), - ) - .bind(":pubkey", quote.pubkey.map(|p| p.to_string())) - .bind(":created_time", quote.created_time as i64) - .bind(":payment_method", quote.payment_method.to_string()) - .bind(":request_lookup_id_kind", quote.request_lookup_id.kind()) - .execute(&self.inner) - .await?; - - Ok(()) - } - - async fn remove_mint_quote(&mut self, quote_id: &Uuid) -> Result<(), Self::Err> { - query(r#"DELETE FROM mint_quote WHERE id=:id"#) - .bind(":id", quote_id.as_hyphenated().to_string()) - .execute(&self.inner) - .await?; - Ok(()) - } - - async fn add_melt_quote(&mut self, quote: mint::MeltQuote) -> Result<(), Self::Err> { - // First try to find and replace any expired UNPAID quotes with the same request_lookup_id - let current_time = unix_time(); - let row_affected = query( - r#" - DELETE FROM melt_quote - WHERE request_lookup_id = :request_lookup_id - AND state = :state - AND expiry < :current_time - "#, - ) - .bind(":request_lookup_id", quote.request_lookup_id.to_string()) - .bind(":state", MeltQuoteState::Unpaid.to_string()) - .bind(":current_time", current_time as i64) - .execute(&self.inner) - .await?; - - if row_affected > 0 { - tracing::info!("Received new melt quote for existing invoice with expired quote."); - } - - // Now insert the new quote - query( - r#" - INSERT INTO melt_quote - ( - id, unit, amount, request, fee_reserve, state, - expiry, payment_preimage, request_lookup_id, - created_time, paid_time, options, request_lookup_id_kind - ) - VALUES - ( - :id, :unit, :amount, :request, :fee_reserve, :state, - :expiry, :payment_preimage, :request_lookup_id, - :created_time, :paid_time, :options, :request_lookup_id_kind - ) - "#, - ) - .bind(":id", quote.id.to_string()) - .bind(":unit", quote.unit.to_string()) - .bind(":amount", quote.amount.to_i64()) - .bind(":request", serde_json::to_string("e.request)?) - .bind(":fee_reserve", quote.fee_reserve.to_i64()) - .bind(":state", quote.state.to_string()) - .bind(":expiry", quote.expiry as i64) - .bind(":payment_preimage", quote.payment_preimage) - .bind(":request_lookup_id", quote.request_lookup_id.to_string()) - .bind(":created_time", quote.created_time as i64) - .bind(":paid_time", quote.paid_time.map(|t| t as i64)) - .bind( - ":options", - quote.options.map(|o| serde_json::to_string(&o).ok()), - ) - .bind(":request_lookup_id_kind", quote.request_lookup_id.kind()) - .execute(&self.inner) - .await?; - - Ok(()) - } - - async fn update_melt_quote_request_lookup_id( - &mut self, - quote_id: &Uuid, - new_request_lookup_id: &PaymentIdentifier, - ) -> Result<(), Self::Err> { - query(r#"UPDATE melt_quote SET request_lookup_id = :new_req_id, request_lookup_id_kind = :new_kind WHERE id = :id"#) - .bind(":new_req_id", new_request_lookup_id.to_string()) - .bind(":new_kind",new_request_lookup_id.kind() ) - .bind(":id", quote_id.as_hyphenated().to_string()) - .execute(&self.inner) - .await?; - Ok(()) - } - - async fn update_melt_quote_state( - &mut self, - quote_id: &Uuid, - state: MeltQuoteState, - payment_proof: Option, - ) -> Result<(MeltQuoteState, mint::MeltQuote), Self::Err> { - let mut quote = query( - r#" - SELECT - id, - unit, - amount, - request, - fee_reserve, - expiry, - state, - payment_preimage, - request_lookup_id, - created_time, - paid_time, - payment_method, - options, - request_lookup_id_kind - FROM - melt_quote - WHERE - id=:id - AND state != :state - "#, - ) - .bind(":id", quote_id.as_hyphenated().to_string()) - .bind(":state", state.to_string()) - .fetch_one(&self.inner) - .await? - .map(sqlite_row_to_melt_quote) - .transpose()? - .ok_or(Error::QuoteNotFound)?; - - let rec = if state == MeltQuoteState::Paid { - let current_time = unix_time(); - query(r#"UPDATE melt_quote SET state = :state, paid_time = :paid_time, payment_preimage = :payment_preimage WHERE id = :id"#) - .bind(":state", state.to_string()) - .bind(":paid_time", current_time as i64) - .bind(":payment_preimage", payment_proof) - .bind(":id", quote_id.as_hyphenated().to_string()) - .execute(&self.inner) - .await - } else { - query(r#"UPDATE melt_quote SET state = :state WHERE id = :id"#) - .bind(":state", state.to_string()) - .bind(":id", quote_id.as_hyphenated().to_string()) - .execute(&self.inner) - .await - }; - - match rec { - Ok(_) => {} - Err(err) => { - tracing::error!("SQLite Could not update melt quote"); - return Err(err.into()); - } - }; - - let old_state = quote.state; - quote.state = state; - - Ok((old_state, quote)) - } - - async fn remove_melt_quote(&mut self, quote_id: &Uuid) -> Result<(), Self::Err> { - query( - r#" - DELETE FROM melt_quote - WHERE id=? - "#, - ) - .bind(":id", quote_id.as_hyphenated().to_string()) - .execute(&self.inner) - .await?; - - Ok(()) - } - - async fn get_mint_quote(&mut self, quote_id: &Uuid) -> Result, Self::Err> { - let payments = get_mint_quote_payments(&self.inner, quote_id).await?; - let issuance = get_mint_quote_issuance(&self.inner, quote_id).await?; - - Ok(query( - r#" - SELECT - id, - amount, - unit, - request, - expiry, - request_lookup_id, - pubkey, - created_time, - amount_paid, - amount_issued, - payment_method, - request_lookup_id_kind - FROM - mint_quote - WHERE id = :id"#, - ) - .bind(":id", quote_id.as_hyphenated().to_string()) - .fetch_one(&self.inner) - .await? - .map(|row| sqlite_row_to_mint_quote(row, payments, issuance)) - .transpose()?) - } - - async fn get_melt_quote( - &mut self, - quote_id: &Uuid, - ) -> Result, Self::Err> { - Ok(query( - r#" - SELECT - id, - unit, - amount, - request, - fee_reserve, - expiry, - state, - payment_preimage, - request_lookup_id, - created_time, - paid_time, - payment_method, - options, - request_lookup_id - FROM - melt_quote - WHERE - id=:id - "#, - ) - .bind(":id", quote_id.as_hyphenated().to_string()) - .fetch_one(&self.inner) - .await? - .map(sqlite_row_to_melt_quote) - .transpose()?) - } - - async fn get_mint_quote_by_request( - &mut self, - request: &str, - ) -> Result, Self::Err> { - let mut mint_quote = query( - r#" - SELECT - id, - amount, - unit, - request, - expiry, - request_lookup_id, - pubkey, - created_time, - amount_paid, - amount_issued, - payment_method, - request_lookup_id_kind - FROM - mint_quote - WHERE request = :request"#, - ) - .bind(":request", request.to_string()) - .fetch_one(&self.inner) - .await? - .map(|row| sqlite_row_to_mint_quote(row, vec![], vec![])) - .transpose()?; - - if let Some(quote) = mint_quote.as_mut() { - let payments = get_mint_quote_payments(&self.inner, "e.id).await?; - let issuance = get_mint_quote_issuance(&self.inner, "e.id).await?; - quote.issuance = issuance; - quote.payments = payments; - } - - Ok(mint_quote) - } - - async fn get_mint_quote_by_request_lookup_id( - &mut self, - request_lookup_id: &PaymentIdentifier, - ) -> Result, Self::Err> { - let mut mint_quote = query( - r#" - SELECT - id, - amount, - unit, - request, - expiry, - request_lookup_id, - pubkey, - created_time, - amount_paid, - amount_issued, - payment_method, - request_lookup_id_kind - FROM - mint_quote - WHERE request_lookup_id = :request_lookup_id - AND request_lookup_id_kind = :request_lookup_id_kind - "#, - ) - .bind(":request_lookup_id", request_lookup_id.to_string()) - .bind(":request_lookup_id_kind", request_lookup_id.kind()) - .fetch_one(&self.inner) - .await? - .map(|row| sqlite_row_to_mint_quote(row, vec![], vec![])) - .transpose()?; - - if let Some(quote) = mint_quote.as_mut() { - let payments = get_mint_quote_payments(&self.inner, "e.id).await?; - let issuance = get_mint_quote_issuance(&self.inner, "e.id).await?; - quote.issuance = issuance; - quote.payments = payments; - } - - Ok(mint_quote) - } -} - -#[async_trait] -impl MintQuotesDatabase for MintSqliteDatabase { - type Err = database::Error; - - async fn get_mint_quote(&self, quote_id: &Uuid) -> Result, Self::Err> { - let payments = get_mint_quote_payments(&self.pool, quote_id).await?; - let issuance = get_mint_quote_issuance(&self.pool, quote_id).await?; - - Ok(query( - r#" - SELECT - id, - amount, - unit, - request, - expiry, - request_lookup_id, - pubkey, - created_time, - amount_paid, - amount_issued, - payment_method, - request_lookup_id_kind - FROM - mint_quote - WHERE id = :id"#, - ) - .bind(":id", quote_id.as_hyphenated().to_string()) - .fetch_one(&self.pool) - .await? - .map(|row| sqlite_row_to_mint_quote(row, payments, issuance)) - .transpose()?) - } - - async fn get_mint_quote_by_request( - &self, - request: &str, - ) -> Result, Self::Err> { - let mut mint_quote = query( - r#" - SELECT - id, - amount, - unit, - request, - expiry, - request_lookup_id, - pubkey, - created_time, - amount_paid, - amount_issued, - payment_method, - request_lookup_id_kind - FROM - mint_quote - WHERE request = :request"#, - ) - .bind(":request", request.to_owned()) - .fetch_one(&self.pool) - .await? - .map(|row| sqlite_row_to_mint_quote(row, vec![], vec![])) - .transpose()?; - - if let Some(quote) = mint_quote.as_mut() { - let payments = get_mint_quote_payments(&self.pool, "e.id).await?; - let issuance = get_mint_quote_issuance(&self.pool, "e.id).await?; - quote.issuance = issuance; - quote.payments = payments; - } - - Ok(mint_quote) - } - - async fn get_mint_quote_by_request_lookup_id( - &self, - request_lookup_id: &PaymentIdentifier, - ) -> Result, Self::Err> { - let mut mint_quote = query( - r#" - SELECT - id, - amount, - unit, - request, - expiry, - request_lookup_id, - pubkey, - created_time, - amount_paid, - amount_issued, - payment_method, - request_lookup_id_kind - FROM - mint_quote - WHERE request_lookup_id = :request_lookup_id - AND request_lookup_id_kind = :request_lookup_id_kind - "#, - ) - .bind(":request_lookup_id", request_lookup_id.to_string()) - .bind(":request_lookup_id_kind", request_lookup_id.kind()) - .fetch_one(&self.pool) - .await? - .map(|row| sqlite_row_to_mint_quote(row, vec![], vec![])) - .transpose()?; - - // TODO: these should use an sql join so they can be done in one query - if let Some(quote) = mint_quote.as_mut() { - let payments = get_mint_quote_payments(&self.pool, "e.id).await?; - let issuance = get_mint_quote_issuance(&self.pool, "e.id).await?; - quote.issuance = issuance; - quote.payments = payments; - } - - Ok(mint_quote) - } - - async fn get_mint_quotes(&self) -> Result, Self::Err> { - let mut mint_quotes = query( - r#" - SELECT - id, - amount, - unit, - request, - expiry, - request_lookup_id, - pubkey, - created_time, - amount_paid, - amount_issued, - payment_method, - request_lookup_id_kind - FROM - mint_quote - "#, - ) - .fetch_all(&self.pool) - .await? - .into_iter() - .map(|row| sqlite_row_to_mint_quote(row, vec![], vec![])) - .collect::, _>>()?; - - for quote in mint_quotes.as_mut_slice() { - let payments = get_mint_quote_payments(&self.pool, "e.id).await?; - let issuance = get_mint_quote_issuance(&self.pool, "e.id).await?; - quote.issuance = issuance; - quote.payments = payments; - } - - Ok(mint_quotes) - } - - async fn get_melt_quote(&self, quote_id: &Uuid) -> Result, Self::Err> { - Ok(query( - r#" - SELECT - id, - unit, - amount, - request, - fee_reserve, - expiry, - state, - payment_preimage, - request_lookup_id, - created_time, - paid_time, - payment_method, - options, - request_lookup_id_kind - FROM - melt_quote - WHERE - id=:id - "#, - ) - .bind(":id", quote_id.as_hyphenated().to_string()) - .fetch_one(&self.pool) - .await? - .map(sqlite_row_to_melt_quote) - .transpose()?) - } - - async fn get_melt_quotes(&self) -> Result, Self::Err> { - Ok(query( - r#" - SELECT - id, - unit, - amount, - request, - fee_reserve, - expiry, - state, - payment_preimage, - request_lookup_id, - created_time, - paid_time, - payment_method, - options, - request_lookup_id_kind - FROM - melt_quote - "#, - ) - .fetch_all(&self.pool) - .await? - .into_iter() - .map(sqlite_row_to_melt_quote) - .collect::, _>>()?) - } -} - -#[async_trait] -impl<'a> MintProofsTransaction<'a> for SqliteTransaction<'a> { - type Err = database::Error; - - async fn add_proofs( - &mut self, - proofs: Proofs, - quote_id: Option, - ) -> Result<(), Self::Err> { - let current_time = unix_time(); - - // Check any previous proof, this query should return None in order to proceed storing - // Any result here would error - match query(r#"SELECT state FROM proof WHERE y IN (:ys) LIMIT 1"#) - .bind_vec( - ":ys", - proofs - .iter() - .map(|y| y.y().map(|y| y.to_bytes().to_vec())) - .collect::>()?, - ) - .pluck(&self.inner) - .await? - .map(|state| Ok::<_, Error>(column_as_string!(&state, State::from_str))) - .transpose()? - { - Some(State::Spent) => Err(database::Error::AttemptUpdateSpentProof), - Some(_) => Err(database::Error::Duplicate), - None => Ok(()), // no previous record - }?; - - for proof in proofs { - query( - r#" - INSERT INTO proof - (y, amount, keyset_id, secret, c, witness, state, quote_id, created_time) - VALUES - (:y, :amount, :keyset_id, :secret, :c, :witness, :state, :quote_id, :created_time) - "#, - ) - .bind(":y", proof.y()?.to_bytes().to_vec()) - .bind(":amount", proof.amount.to_i64()) - .bind(":keyset_id", proof.keyset_id.to_string()) - .bind(":secret", proof.secret.to_string()) - .bind(":c", proof.c.to_bytes().to_vec()) - .bind( - ":witness", - proof.witness.map(|w| serde_json::to_string(&w).unwrap()), - ) - .bind(":state", "UNSPENT".to_string()) - .bind(":quote_id", quote_id.map(|q| q.hyphenated().to_string())) - .bind(":created_time", current_time as i64) - .execute(&self.inner) - .await?; - } - - Ok(()) - } - - async fn update_proofs_states( - &mut self, - ys: &[PublicKey], - new_state: State, - ) -> Result>, Self::Err> { - let mut current_states = get_current_states(&self.inner, ys).await?; - - if current_states.len() != ys.len() { - tracing::warn!( - "Attempted to update state of non-existent proof {} {}", - current_states.len(), - ys.len() - ); - return Err(database::Error::ProofNotFound); - } - - for state in current_states.values() { - check_state_transition(*state, new_state)?; - } - - query(r#"UPDATE proof SET state = :new_state WHERE y IN (:ys)"#) - .bind(":new_state", new_state.to_string()) - .bind_vec(":ys", ys.iter().map(|y| y.to_bytes().to_vec()).collect()) - .execute(&self.inner) - .await?; - - Ok(ys.iter().map(|y| current_states.remove(y)).collect()) - } - - async fn remove_proofs( - &mut self, - ys: &[PublicKey], - _quote_id: Option, - ) -> Result<(), Self::Err> { - let total_deleted = query( - r#" - DELETE FROM proof WHERE y IN (:ys) AND state NOT IN (:exclude_state) - "#, - ) - .bind_vec(":ys", ys.iter().map(|y| y.to_bytes().to_vec()).collect()) - .bind_vec(":exclude_state", vec![State::Spent.to_string()]) - .execute(&self.inner) - .await?; - - if total_deleted != ys.len() { - return Err(Self::Err::AttemptRemoveSpentProof); - } - - Ok(()) - } -} - -#[async_trait] -impl MintProofsDatabase for MintSqliteDatabase { - type Err = database::Error; - - #[instrument(skip_all)] - async fn get_proofs_by_ys(&self, ys: &[PublicKey]) -> Result>, Self::Err> { - let mut proofs = query( - r#" - SELECT - amount, - keyset_id, - secret, - c, - witness, - y - FROM - proof - WHERE - y IN (:ys) - "#, - ) - .bind_vec(":ys", ys.iter().map(|y| y.to_bytes().to_vec()).collect()) - .fetch_all(&self.pool) - .await? - .into_iter() - .map(|mut row| { - Ok(( - column_as_string!( - row.pop().ok_or(Error::InvalidDbPath)?, - PublicKey::from_hex, - PublicKey::from_slice - ), - sqlite_row_to_proof(row)?, - )) - }) - .collect::, Error>>()?; - - Ok(ys.iter().map(|y| proofs.remove(y)).collect()) - } - - #[instrument(skip(self))] - async fn get_proof_ys_by_quote_id(&self, quote_id: &Uuid) -> Result, Self::Err> { - Ok(query( - r#" - SELECT - amount, - keyset_id, - secret, - c, - witness - FROM - proof - WHERE - quote_id = :quote_id - "#, - ) - .bind(":quote_id", quote_id.as_hyphenated().to_string()) - .fetch_all(&self.pool) - .await? - .into_iter() - .map(sqlite_row_to_proof) - .collect::, _>>()? - .ys()?) - } - - #[instrument(skip_all)] - async fn get_proofs_states(&self, ys: &[PublicKey]) -> Result>, Self::Err> { - let mut current_states = get_current_states(&self.pool, ys).await?; - - Ok(ys.iter().map(|y| current_states.remove(y)).collect()) - } - - #[instrument(skip_all)] - async fn get_proofs_by_keyset_id( - &self, - keyset_id: &Id, - ) -> Result<(Proofs, Vec>), Self::Err> { - Ok(query( - r#" - SELECT - keyset_id, - amount, - secret, - c, - witness, - state - FROM - proof - WHERE - keyset_id=? - "#, - ) - .bind(":keyset_id", keyset_id.to_string()) - .fetch_all(&self.pool) - .await? - .into_iter() - .map(sqlite_row_to_proof_with_state) - .collect::, _>>()? - .into_iter() - .unzip()) - } -} - -#[async_trait] -impl<'a> MintSignatureTransaction<'a> for SqliteTransaction<'a> { - type Err = database::Error; - - #[instrument(skip_all)] - async fn add_blind_signatures( - &mut self, - blinded_messages: &[PublicKey], - blind_signatures: &[BlindSignature], - quote_id: Option, - ) -> Result<(), Self::Err> { - let current_time = unix_time(); - - for (message, signature) in blinded_messages.iter().zip(blind_signatures) { - query( - r#" - INSERT INTO blind_signature - (blinded_message, amount, keyset_id, c, quote_id, dleq_e, dleq_s, created_time) - VALUES - (:blinded_message, :amount, :keyset_id, :c, :quote_id, :dleq_e, :dleq_s, :created_time) - "#, - ) - .bind(":blinded_message", message.to_bytes().to_vec()) - .bind(":amount", signature.amount.to_i64()) - .bind(":keyset_id", signature.keyset_id.to_string()) - .bind(":c", signature.c.to_hex()) - .bind(":quote_id", quote_id.map(|q| q.hyphenated().to_string())) - .bind( - ":dleq_e", - signature.dleq.as_ref().map(|dleq| dleq.e.to_secret_hex()), - ) - .bind( - ":dleq_s", - signature.dleq.as_ref().map(|dleq| dleq.s.to_secret_hex()), - ) - .bind(":created_time", current_time as i64) - .execute(&self.inner) - .await?; - } - - Ok(()) - } - - #[instrument(skip_all)] - async fn get_blind_signatures( - &mut self, - blinded_messages: &[PublicKey], - ) -> Result>, Self::Err> { - let mut blinded_signatures = query( - r#"SELECT - keyset_id, - amount, - c, - dleq_e, - dleq_s, - blinded_message - FROM - blind_signature - WHERE blinded_message IN (:blinded_message) - "#, - ) - .bind_vec( - ":blinded_message", - blinded_messages - .iter() - .map(|y| y.to_bytes().to_vec()) - .collect(), - ) - .fetch_all(&self.inner) - .await? - .into_iter() - .map(|mut row| { - Ok(( - column_as_string!( - &row.pop().ok_or(Error::InvalidDbResponse)?, - PublicKey::from_hex, - PublicKey::from_slice - ), - sqlite_row_to_blind_signature(row)?, - )) - }) - .collect::, Error>>()?; - - Ok(blinded_messages - .iter() - .map(|y| blinded_signatures.remove(y)) - .collect()) - } -} - -#[async_trait] -impl MintSignaturesDatabase for MintSqliteDatabase { - type Err = database::Error; - - async fn get_blind_signatures( - &self, - blinded_messages: &[PublicKey], - ) -> Result>, Self::Err> { - let mut blinded_signatures = query( - r#"SELECT - keyset_id, - amount, - c, - dleq_e, - dleq_s, - blinded_message - FROM - blind_signature - WHERE blinded_message IN (:blinded_message) - "#, - ) - .bind_vec( - ":blinded_message", - blinded_messages - .iter() - .map(|b_| b_.to_bytes().to_vec()) - .collect(), - ) - .fetch_all(&self.pool) - .await? - .into_iter() - .map(|mut row| { - Ok(( - column_as_string!( - &row.pop().ok_or(Error::InvalidDbResponse)?, - PublicKey::from_hex, - PublicKey::from_slice - ), - sqlite_row_to_blind_signature(row)?, - )) - }) - .collect::, Error>>()?; - Ok(blinded_messages - .iter() - .map(|y| blinded_signatures.remove(y)) - .collect()) - } - - async fn get_blind_signatures_for_keyset( - &self, - keyset_id: &Id, - ) -> Result, Self::Err> { - Ok(query( - r#" - SELECT - keyset_id, - amount, - c, - dleq_e, - dleq_s - FROM - blind_signature - WHERE - keyset_id=:keyset_id - "#, - ) - .bind(":keyset_id", keyset_id.to_string()) - .fetch_all(&self.pool) - .await? - .into_iter() - .map(sqlite_row_to_blind_signature) - .collect::, _>>()?) - } - - /// Get [`BlindSignature`]s for quote - async fn get_blind_signatures_for_quote( - &self, - quote_id: &Uuid, - ) -> Result, Self::Err> { - Ok(query( - r#" - SELECT - keyset_id, - amount, - c, - dleq_e, - dleq_s - FROM - blind_signature - WHERE - quote_id=:quote_id - "#, - ) - .bind(":quote_id", quote_id.to_string()) - .fetch_all(&self.pool) - .await? - .into_iter() - .map(sqlite_row_to_blind_signature) - .collect::, _>>()?) - } -} - -#[async_trait] -impl MintDatabase for MintSqliteDatabase { - async fn begin_transaction<'a>( - &'a self, - ) -> Result< - Box + Send + Sync + 'a>, - database::Error, - > { - Ok(Box::new(SqliteTransaction { - inner: self.pool.begin().await?, - })) - } - - async fn get_mint_info(&self) -> Result { - Ok(self.fetch_from_config("mint_info").await?) - } - - async fn get_quote_ttl(&self) -> Result { - Ok(self.fetch_from_config("quote_ttl").await?) - } -} - -fn sqlite_row_to_keyset_info(row: Vec) -> Result { - unpack_into!( - let ( - id, - unit, - active, - valid_from, - valid_to, - derivation_path, - derivation_path_index, - max_order, - row_keyset_ppk - ) = row - ); - - Ok(MintKeySetInfo { - id: column_as_string!(id, Id::from_str, Id::from_bytes), - unit: column_as_string!(unit, CurrencyUnit::from_str), - active: matches!(active, Column::Integer(1)), - valid_from: column_as_number!(valid_from), - derivation_path: column_as_string!(derivation_path, DerivationPath::from_str), - derivation_path_index: column_as_nullable_number!(derivation_path_index), - max_order: column_as_number!(max_order), - input_fee_ppk: column_as_number!(row_keyset_ppk), - final_expiry: column_as_nullable_number!(valid_to), - }) -} - -#[instrument(skip_all)] -fn sqlite_row_to_mint_quote( - row: Vec, - payments: Vec, - issueances: Vec, -) -> Result { - unpack_into!( - let ( - id, amount, unit, request, expiry, request_lookup_id, - pubkey, created_time, amount_paid, amount_issued, payment_method, request_lookup_id_kind - ) = row - ); - - let request_str = column_as_string!(&request); - let request_lookup_id = column_as_nullable_string!(&request_lookup_id).unwrap_or_else(|| { - Bolt11Invoice::from_str(&request_str) - .map(|invoice| invoice.payment_hash().to_string()) - .unwrap_or_else(|_| request_str.clone()) - }); - let request_lookup_id_kind = column_as_string!(request_lookup_id_kind); - - let pubkey = column_as_nullable_string!(&pubkey) - .map(|pk| PublicKey::from_hex(&pk)) - .transpose()?; - - let id = column_as_string!(id); - let amount: Option = column_as_nullable_number!(amount); - let amount_paid: u64 = column_as_number!(amount_paid); - let amount_issued: u64 = column_as_number!(amount_issued); - let payment_method = column_as_string!(payment_method, PaymentMethod::from_str); - - Ok(MintQuote::new( - Some(Uuid::parse_str(&id).map_err(|_| Error::InvalidUuid(id))?), - request_str, - column_as_string!(unit, CurrencyUnit::from_str), - amount.map(Amount::from), - column_as_number!(expiry), - PaymentIdentifier::new(&request_lookup_id_kind, &request_lookup_id) - .map_err(|_| Error::MissingParameter("Payment id".to_string()))?, - pubkey, - amount_paid.into(), - amount_issued.into(), - payment_method, - column_as_number!(created_time), - payments, - issueances, - )) -} - -fn sqlite_row_to_melt_quote(row: Vec) -> Result { - unpack_into!( - let ( - id, - unit, - amount, - request, - fee_reserve, - expiry, - state, - payment_preimage, - request_lookup_id, - created_time, - paid_time, - payment_method, - options, - request_lookup_id_kind - ) = row - ); - - let id = column_as_string!(id); - let amount: u64 = column_as_number!(amount); - let fee_reserve: u64 = column_as_number!(fee_reserve); - - let expiry = column_as_number!(expiry); - let payment_preimage = column_as_nullable_string!(payment_preimage); - let options = column_as_nullable_string!(options); - let options = options.and_then(|o| serde_json::from_str(&o).ok()); - let created_time: i64 = column_as_number!(created_time); - let paid_time = column_as_nullable_number!(paid_time); - let payment_method = PaymentMethod::from_str(&column_as_string!(payment_method))?; - - let state = MeltQuoteState::from_str(&column_as_string!(&state))?; - - let unit = column_as_string!(unit); - let request = column_as_string!(request); - - let mut request_lookup_id_kind = column_as_string!(request_lookup_id_kind); - - let request_lookup_id = column_as_nullable_string!(&request_lookup_id).unwrap_or_else(|| { - Bolt11Invoice::from_str(&request) - .map(|invoice| invoice.payment_hash().to_string()) - .unwrap_or_else(|_| { - request_lookup_id_kind = "custom".to_string(); - request.clone() - }) - }); - - let request_lookup_id = PaymentIdentifier::new(&request_lookup_id_kind, &request_lookup_id) - .map_err(|_| Error::MissingParameter("Payment id".to_string()))?; - - let request = match serde_json::from_str(&request) { - Ok(req) => req, - Err(err) => { - tracing::debug!( - "Melt quote from pre migrations defaulting to bolt11 {}.", - err - ); - let bolt11 = Bolt11Invoice::from_str(&request).unwrap(); - MeltPaymentRequest::Bolt11 { bolt11 } - } - }; - - Ok(MeltQuote { - id: Uuid::parse_str(&id).map_err(|_| Error::InvalidUuid(id))?, - unit: CurrencyUnit::from_str(&unit)?, - amount: Amount::from(amount), - request, - fee_reserve: Amount::from(fee_reserve), - state, - expiry, - payment_preimage, - request_lookup_id, - options, - created_time: created_time as u64, - paid_time, - payment_method, - }) -} - -fn sqlite_row_to_proof(row: Vec) -> Result { - unpack_into!( - let ( - amount, - keyset_id, - secret, - c, - witness - ) = row - ); - - let amount: u64 = column_as_number!(amount); - Ok(Proof { - amount: Amount::from(amount), - keyset_id: column_as_string!(keyset_id, Id::from_str), - secret: column_as_string!(secret, Secret::from_str), - c: column_as_string!(c, PublicKey::from_hex, PublicKey::from_slice), - witness: column_as_nullable_string!(witness).and_then(|w| serde_json::from_str(&w).ok()), - dleq: None, - }) -} - -fn sqlite_row_to_proof_with_state(row: Vec) -> Result<(Proof, Option), Error> { - unpack_into!( - let ( - keyset_id, amount, secret, c, witness, state - ) = row - ); - - let amount: u64 = column_as_number!(amount); - let state = column_as_nullable_string!(state).and_then(|s| State::from_str(&s).ok()); - - Ok(( - Proof { - amount: Amount::from(amount), - keyset_id: column_as_string!(keyset_id, Id::from_str, Id::from_bytes), - secret: column_as_string!(secret, Secret::from_str), - c: column_as_string!(c, PublicKey::from_hex, PublicKey::from_slice), - witness: column_as_nullable_string!(witness) - .and_then(|w| serde_json::from_str(&w).ok()), - dleq: None, - }, - state, - )) -} - -fn sqlite_row_to_blind_signature(row: Vec) -> Result { - unpack_into!( - let ( - keyset_id, amount, c, dleq_e, dleq_s - ) = row - ); - - let dleq = match ( - column_as_nullable_string!(dleq_e), - column_as_nullable_string!(dleq_s), - ) { - (Some(e), Some(s)) => Some(BlindSignatureDleq { - e: SecretKey::from_hex(e)?, - s: SecretKey::from_hex(s)?, - }), - _ => None, - }; - - let amount: u64 = column_as_number!(amount); - - Ok(BlindSignature { - amount: Amount::from(amount), - keyset_id: column_as_string!(keyset_id, Id::from_str, Id::from_bytes), - c: column_as_string!(c, PublicKey::from_hex, PublicKey::from_slice), - dleq, - }) -} +pub type MintSqliteAuthDatabase = SQLMintAuthDatabase; #[cfg(test)] -mod tests { +mod test { use std::fs::remove_file; - use cdk_common::mint::MintKeySetInfo; - use cdk_common::{mint_db_test, Amount}; + use cdk_common::mint_db_test; + use cdk_sql_common::stmt::query; use super::*; - - #[tokio::test] - async fn test_remove_spent_proofs() { - let db = memory::empty().await.unwrap(); - - // Create a keyset and add it to the database - let keyset_id = Id::from_str("00916bbf7ef91a36").unwrap(); - let keyset_info = MintKeySetInfo { - id: keyset_id, - unit: CurrencyUnit::Sat, - active: true, - valid_from: 0, - derivation_path: bitcoin::bip32::DerivationPath::from_str("m/0'/0'/0'").unwrap(), - derivation_path_index: Some(0), - max_order: 32, - input_fee_ppk: 0, - final_expiry: None, - }; - let mut tx = MintKeysDatabase::begin_transaction(&db).await.unwrap(); - tx.add_keyset_info(keyset_info).await.unwrap(); - tx.commit().await.unwrap(); - - let proofs = vec![ - Proof { - amount: Amount::from(100), - keyset_id, - secret: Secret::generate(), - c: SecretKey::generate().public_key(), - witness: None, - dleq: None, - }, - Proof { - amount: Amount::from(200), - keyset_id, - secret: Secret::generate(), - c: SecretKey::generate().public_key(), - witness: None, - dleq: None, - }, - ]; - - // Add proofs to database - let mut tx = MintDatabase::begin_transaction(&db).await.unwrap(); - tx.add_proofs(proofs.clone(), None).await.unwrap(); - - // Mark one proof as spent - tx.update_proofs_states(&[proofs[0].y().unwrap()], State::Spent) - .await - .unwrap(); - - tx.commit().await.unwrap(); - - // Verify both proofs still exist - let states = db - .get_proofs_states(&[proofs[0].y().unwrap(), proofs[1].y().unwrap()]) - .await - .unwrap(); - - assert_eq!(states.len(), 2); - assert_eq!(states[0], Some(State::Spent)); - assert_eq!(states[1], Some(State::Unspent)); - } - - #[tokio::test] - async fn test_update_spent_proofs() { - let db = memory::empty().await.unwrap(); - - // Create a keyset and add it to the database - let keyset_id = Id::from_str("00916bbf7ef91a36").unwrap(); - let keyset_info = MintKeySetInfo { - id: keyset_id, - unit: CurrencyUnit::Sat, - active: true, - valid_from: 0, - derivation_path: bitcoin::bip32::DerivationPath::from_str("m/0'/0'/0'").unwrap(), - derivation_path_index: Some(0), - max_order: 32, - input_fee_ppk: 0, - final_expiry: None, - }; - let mut tx = MintKeysDatabase::begin_transaction(&db) - .await - .expect("begin"); - tx.add_keyset_info(keyset_info).await.unwrap(); - tx.commit().await.expect("commit"); - - let proofs = vec![ - Proof { - amount: Amount::from(100), - keyset_id, - secret: Secret::generate(), - c: SecretKey::generate().public_key(), - witness: None, - dleq: None, - }, - Proof { - amount: Amount::from(200), - keyset_id, - secret: Secret::generate(), - c: SecretKey::generate().public_key(), - witness: None, - dleq: None, - }, - ]; - - // Add proofs to database - let mut tx = MintDatabase::begin_transaction(&db).await.unwrap(); - tx.add_proofs(proofs.clone(), None).await.unwrap(); - - // Mark one proof as spent - tx.update_proofs_states(&[proofs[0].y().unwrap()], State::Spent) - .await - .unwrap(); - - // Try to update both proofs - should fail because one is spent - let result = tx - .update_proofs_states(&[proofs[0].y().unwrap()], State::Unspent) - .await; - - tx.commit().await.unwrap(); - - assert!(result.is_err()); - assert!(matches!( - result.unwrap_err(), - database::Error::AttemptUpdateSpentProof - )); - - // Verify states haven't changed - let states = db - .get_proofs_states(&[proofs[0].y().unwrap(), proofs[1].y().unwrap()]) - .await - .unwrap(); - - assert_eq!(states.len(), 2); - assert_eq!(states[0], Some(State::Spent)); - assert_eq!(states[1], Some(State::Unspent)); - } + use crate::mint::async_rusqlite::AsyncRusqlite; async fn provide_db() -> MintSqliteDatabase { memory::empty().await.unwrap() @@ -1925,114 +40,25 @@ mod tests { { let _ = remove_file(&file); #[cfg(not(feature = "sqlcipher"))] - let legacy = create_sqlite_pool(&file); + let conn: AsyncRusqlite = file.as_str().into(); #[cfg(feature = "sqlcipher")] - let legacy = create_sqlite_pool(&file, "test".to_owned()); - let y = legacy.get().expect("pool"); - y.execute_batch(include_str!("../../tests/legacy-sqlx.sql")) + let conn: AsyncRusqlite = (file.as_str(), "test".to_owned()).into(); + + query(include_str!("../../tests/legacy-sqlx.sql")) + .expect("query") + .execute(&conn) + .await .expect("create former db failed"); } #[cfg(not(feature = "sqlcipher"))] - let conn = MintSqliteDatabase::new(&file).await; + let conn = MintSqliteDatabase::new(file.as_str()).await; #[cfg(feature = "sqlcipher")] - let conn = MintSqliteDatabase::new(&file, "test".to_owned()).await; + let conn = MintSqliteDatabase::new((file.as_str(), "test".to_owned())).await; assert!(conn.is_ok(), "Failed with {:?}", conn.unwrap_err()); let _ = remove_file(&file); } - - #[tokio::test] - async fn test_fetch_from_config_error_handling() { - use cdk_common::common::QuoteTTL; - use cdk_common::MintInfo; - - let db = memory::empty().await.unwrap(); - - // Test 1: Unknown mint_info should return UnknownMintInfo error - let result: Result = db.fetch_from_config("mint_info").await; - assert!(result.is_err()); - assert!(matches!(result.unwrap_err(), Error::UnknownMintInfo)); - - // Test 2: Unknown quote_ttl should return UnknownQuoteTTL error - let result: Result = db.fetch_from_config("quote_ttl").await; - assert!(result.is_err()); - assert!(matches!(result.unwrap_err(), Error::UnknownQuoteTTL)); - - // Test 3: Unknown config key should return UnknownConfigKey error - let result: Result = db.fetch_from_config("unknown_config_key").await; - assert!(result.is_err()); - match result.unwrap_err() { - Error::UnknownConfigKey(key) => { - assert_eq!(key, "unknown_config_key"); - } - other => panic!("Expected UnknownConfigKey error, got: {:?}", other), - } - - // Test 4: Another unknown config key with different name - let result: Result = db.fetch_from_config("some_other_key").await; - assert!(result.is_err()); - match result.unwrap_err() { - Error::UnknownConfigKey(key) => { - assert_eq!(key, "some_other_key"); - } - other => panic!("Expected UnknownConfigKey error, got: {:?}", other), - } - } - - #[tokio::test] - async fn test_config_round_trip() { - use cdk_common::common::QuoteTTL; - use cdk_common::{MintInfo, Nuts}; - - let db = memory::empty().await.unwrap(); - - // Test mint_info round trip - let mint_info = MintInfo { - name: Some("Test Mint".to_string()), - description: Some("A test mint".to_string()), - pubkey: None, - version: None, - description_long: None, - contact: None, - nuts: Nuts::default(), - icon_url: None, - urls: None, - motd: None, - time: None, - tos_url: None, - }; - - // Store mint_info - let mut tx = cdk_common::database::MintDatabase::begin_transaction(&db) - .await - .unwrap(); - tx.set_mint_info(mint_info.clone()).await.unwrap(); - tx.commit().await.unwrap(); - - // Retrieve mint_info - let retrieved_mint_info: MintInfo = db.fetch_from_config("mint_info").await.unwrap(); - assert_eq!(mint_info.name, retrieved_mint_info.name); - assert_eq!(mint_info.description, retrieved_mint_info.description); - - // Test quote_ttl round trip - let quote_ttl = QuoteTTL { - mint_ttl: 3600, - melt_ttl: 1800, - }; - - // Store quote_ttl - let mut tx = cdk_common::database::MintDatabase::begin_transaction(&db) - .await - .unwrap(); - tx.set_quote_ttl(quote_ttl.clone()).await.unwrap(); - tx.commit().await.unwrap(); - - // Retrieve quote_ttl - let retrieved_quote_ttl: QuoteTTL = db.fetch_from_config("quote_ttl").await.unwrap(); - assert_eq!(quote_ttl.mint_ttl, retrieved_quote_ttl.mint_ttl); - assert_eq!(quote_ttl.melt_ttl, retrieved_quote_ttl.melt_ttl); - } } diff --git a/crates/cdk-sqlite/src/stmt.rs b/crates/cdk-sqlite/src/stmt.rs deleted file mode 100644 index d578ef2b7..000000000 --- a/crates/cdk-sqlite/src/stmt.rs +++ /dev/null @@ -1,184 +0,0 @@ -use std::collections::HashMap; - -use rusqlite::{self, CachedStatement}; - -use crate::common::SqliteConnectionManager; -use crate::pool::PooledResource; - -/// The Value coming from SQLite -pub type Value = rusqlite::types::Value; - -/// The Column type -pub type Column = Value; - -/// Expected response type for a given SQL statement -#[derive(Debug, Clone, Copy, Default)] -pub enum ExpectedSqlResponse { - /// A single row - SingleRow, - /// All the rows that matches a query - #[default] - ManyRows, - /// How many rows were affected by the query - AffectedRows, - /// Return the first column of the first row - Pluck, -} - -/// Sql message -#[derive(Default, Debug)] -pub struct Statement { - /// The SQL statement - pub sql: String, - /// The list of arguments for the placeholders. It only supports named arguments for simplicity - /// sake - pub args: HashMap, - /// The expected response type - pub expected_response: ExpectedSqlResponse, -} - -impl Statement { - /// Creates a new statement - pub fn new(sql: T) -> Self - where - T: ToString, - { - Self { - sql: sql.to_string(), - ..Default::default() - } - } - - /// Binds a given placeholder to a value. - #[inline] - pub fn bind(mut self, name: C, value: V) -> Self - where - C: ToString, - V: Into, - { - self.args.insert(name.to_string(), value.into()); - self - } - - /// Binds a single variable with a vector. - /// - /// This will rewrite the function from `:foo` (where value is vec![1, 2, 3]) to `:foo0, :foo1, - /// :foo2` and binds each value from the value vector accordingly. - #[inline] - pub fn bind_vec(mut self, name: C, value: Vec) -> Self - where - C: ToString, - V: Into, - { - let mut new_sql = String::with_capacity(self.sql.len()); - let target = name.to_string(); - let mut i = 0; - - let placeholders = value - .into_iter() - .enumerate() - .map(|(key, value)| { - let key = format!("{target}{key}"); - self.args.insert(key.clone(), value.into()); - key - }) - .collect::>() - .join(","); - - while let Some(pos) = self.sql[i..].find(&target) { - let abs_pos = i + pos; - let after = abs_pos + target.len(); - let is_word_boundary = self.sql[after..] - .chars() - .next() - .map_or(true, |c| !c.is_alphanumeric() && c != '_'); - - if is_word_boundary { - new_sql.push_str(&self.sql[i..abs_pos]); - new_sql.push_str(&placeholders); - i = after; - } else { - new_sql.push_str(&self.sql[i..=abs_pos]); - i = abs_pos + 1; - } - } - - new_sql.push_str(&self.sql[i..]); - - self.sql = new_sql; - self - } - - fn get_stmt( - self, - conn: &PooledResource, - ) -> rusqlite::Result> { - let mut stmt = conn.prepare_cached(&self.sql)?; - for (name, value) in self.args { - let index = stmt - .parameter_index(&name) - .map_err(|_| rusqlite::Error::InvalidColumnName(name.clone()))? - .ok_or(rusqlite::Error::InvalidColumnName(name))?; - - stmt.raw_bind_parameter(index, value)?; - } - - Ok(stmt) - } - - /// Executes a query and returns the affected rows - pub fn plunk( - self, - conn: &PooledResource, - ) -> rusqlite::Result> { - let mut stmt = self.get_stmt(conn)?; - let mut rows = stmt.raw_query(); - rows.next()?.map(|row| row.get(0)).transpose() - } - - /// Executes a query and returns the affected rows - pub fn execute( - self, - conn: &PooledResource, - ) -> rusqlite::Result { - self.get_stmt(conn)?.raw_execute() - } - - /// Runs the query and returns the first row or None - pub fn fetch_one( - self, - conn: &PooledResource, - ) -> rusqlite::Result>> { - let mut stmt = self.get_stmt(conn)?; - let columns = stmt.column_count(); - let mut rows = stmt.raw_query(); - rows.next()? - .map(|row| { - (0..columns) - .map(|i| row.get(i)) - .collect::, _>>() - }) - .transpose() - } - - /// Runs the query and returns the first row or None - pub fn fetch_all( - self, - conn: &PooledResource, - ) -> rusqlite::Result>> { - let mut stmt = self.get_stmt(conn)?; - let columns = stmt.column_count(); - let mut rows = stmt.raw_query(); - let mut results = vec![]; - - while let Some(row) = rows.next()? { - results.push( - (0..columns) - .map(|i| row.get(i)) - .collect::, _>>()?, - ); - } - - Ok(results) - } -} diff --git a/crates/cdk-sqlite/src/wallet/memory.rs b/crates/cdk-sqlite/src/wallet/memory.rs index e916461ed..d164abb9e 100644 --- a/crates/cdk-sqlite/src/wallet/memory.rs +++ b/crates/cdk-sqlite/src/wallet/memory.rs @@ -7,8 +7,10 @@ use super::WalletSqliteDatabase; /// Creates a new in-memory [`WalletSqliteDatabase`] instance pub async fn empty() -> Result { #[cfg(not(feature = "sqlcipher"))] - let db = WalletSqliteDatabase::new(":memory:").await?; + let path = ":memory:"; + #[cfg(feature = "sqlcipher")] - let db = WalletSqliteDatabase::new(":memory:", "memory".to_owned()).await?; - Ok(db) + let path = (":memory:", "memory"); + + WalletSqliteDatabase::new(path).await } diff --git a/crates/cdk-sqlite/src/wallet/migrations.rs b/crates/cdk-sqlite/src/wallet/migrations.rs deleted file mode 100644 index 0c41bad78..000000000 --- a/crates/cdk-sqlite/src/wallet/migrations.rs +++ /dev/null @@ -1,21 +0,0 @@ -// @generated -// Auto-generated by build.rs -pub static MIGRATIONS: &[(&str, &str)] = &[ - ("20240612132920_init.sql", include_str!(r#"./migrations/20240612132920_init.sql"#)), - ("20240618200350_quote_state.sql", include_str!(r#"./migrations/20240618200350_quote_state.sql"#)), - ("20240626091921_nut04_state.sql", include_str!(r#"./migrations/20240626091921_nut04_state.sql"#)), - ("20240710144711_input_fee.sql", include_str!(r#"./migrations/20240710144711_input_fee.sql"#)), - ("20240810214105_mint_icon_url.sql", include_str!(r#"./migrations/20240810214105_mint_icon_url.sql"#)), - ("20240810233905_update_mint_url.sql", include_str!(r#"./migrations/20240810233905_update_mint_url.sql"#)), - ("20240902151515_icon_url.sql", include_str!(r#"./migrations/20240902151515_icon_url.sql"#)), - ("20240902210905_mint_time.sql", include_str!(r#"./migrations/20240902210905_mint_time.sql"#)), - ("20241011125207_mint_urls.sql", include_str!(r#"./migrations/20241011125207_mint_urls.sql"#)), - ("20241108092756_wallet_mint_quote_secretkey.sql", include_str!(r#"./migrations/20241108092756_wallet_mint_quote_secretkey.sql"#)), - ("20250214135017_mint_tos.sql", include_str!(r#"./migrations/20250214135017_mint_tos.sql"#)), - ("20250310111513_drop_nostr_last_checked.sql", include_str!(r#"./migrations/20250310111513_drop_nostr_last_checked.sql"#)), - ("20250314082116_allow_pending_spent.sql", include_str!(r#"./migrations/20250314082116_allow_pending_spent.sql"#)), - ("20250323152040_wallet_dleq_proofs.sql", include_str!(r#"./migrations/20250323152040_wallet_dleq_proofs.sql"#)), - ("20250401120000_add_transactions_table.sql", include_str!(r#"./migrations/20250401120000_add_transactions_table.sql"#)), - ("20250616144830_add_keyset_expiry.sql", include_str!(r#"./migrations/20250616144830_add_keyset_expiry.sql"#)), - ("20250707093445_bolt12.sql", include_str!(r#"./migrations/20250707093445_bolt12.sql"#)), -]; diff --git a/crates/cdk-sqlite/src/wallet/mod.rs b/crates/cdk-sqlite/src/wallet/mod.rs index 95259ed26..28252a9e6 100644 --- a/crates/cdk-sqlite/src/wallet/mod.rs +++ b/crates/cdk-sqlite/src/wallet/mod.rs @@ -1,1147 +1,200 @@ //! SQLite Wallet Database -use std::collections::HashMap; -use std::ops::DerefMut; -use std::path::Path; -use std::str::FromStr; +use std::path::PathBuf; use std::sync::Arc; -use async_trait::async_trait; -use cdk_common::common::ProofInfo; -use cdk_common::database::WalletDatabase; -use cdk_common::mint_url::MintUrl; -use cdk_common::nuts::{MeltQuoteState, MintQuoteState}; -use cdk_common::secret::Secret; -use cdk_common::wallet::{self, MintQuote, Transaction, TransactionDirection, TransactionId}; -use cdk_common::{ - database, Amount, CurrencyUnit, Id, KeySet, KeySetInfo, Keys, MintInfo, PaymentMethod, Proof, - ProofDleq, PublicKey, SecretKey, SpendingConditions, State, -}; -use error::Error; -use tracing::instrument; +use cdk_common::database::Error; +use cdk_sql_common::database::DatabaseExecutor; +use cdk_sql_common::pool::{Pool, PooledResource}; +use cdk_sql_common::stmt::{Column, SqlPart, Statement}; +use cdk_sql_common::SQLWalletDatabase; +use rusqlite::CachedStatement; -use crate::common::{create_sqlite_pool, migrate, SqliteConnectionManager}; -use crate::pool::Pool; -use crate::stmt::{Column, Statement}; -use crate::{ - column_as_binary, column_as_nullable_binary, column_as_nullable_number, - column_as_nullable_string, column_as_number, column_as_string, unpack_into, -}; +use crate::common::{create_sqlite_pool, from_sqlite, to_sqlite, SqliteConnectionManager}; -pub mod error; pub mod memory; -#[rustfmt::skip] -mod migrations; +/// Simple Sqlite wapper, since the wallet may not need rusqlite with concurrency, a shared instance +/// may be enough +#[derive(Debug)] +pub struct SimpleAsyncRusqlite(Arc>); -/// Wallet SQLite Database -#[derive(Debug, Clone)] -pub struct WalletSqliteDatabase { - pool: Arc>, -} - -impl WalletSqliteDatabase { - /// Create new [`WalletSqliteDatabase`] - #[cfg(not(feature = "sqlcipher"))] - pub async fn new>(path: P) -> Result { - let db = Self { - pool: create_sqlite_pool(path.as_ref().to_str().ok_or(Error::InvalidDbPath)?), - }; - db.migrate()?; - Ok(db) - } - - /// Create new [`WalletSqliteDatabase`] - #[cfg(feature = "sqlcipher")] - pub async fn new>(path: P, password: String) -> Result { - let db = Self { - pool: create_sqlite_pool( - path.as_ref().to_str().ok_or(Error::InvalidDbPath)?, - password, - ), - }; - db.migrate()?; - Ok(db) - } +impl SimpleAsyncRusqlite { + fn get_stmt<'a>( + &self, + conn: &'a PooledResource, + statement: Statement, + ) -> Result, Error> { + let (sql, placeholder_values) = statement.to_sql()?; + let mut stmt = conn + .prepare_cached(&sql) + .map_err(|e| Error::Database(Box::new(e)))?; + + for (i, value) in placeholder_values.into_iter().enumerate() { + stmt.raw_bind_parameter(i + 1, to_sqlite(value)) + .map_err(|e| Error::Database(Box::new(e)))?; + } - /// Migrate [`WalletSqliteDatabase`] - fn migrate(&self) -> Result<(), Error> { - migrate(self.pool.get()?.deref_mut(), migrations::MIGRATIONS)?; - Ok(()) + Ok(stmt) } } -#[async_trait] -impl WalletDatabase for WalletSqliteDatabase { - type Err = database::Error; - - #[instrument(skip(self, mint_info))] - async fn add_mint( - &self, - mint_url: MintUrl, - mint_info: Option, - ) -> Result<(), Self::Err> { - let ( - name, - pubkey, - version, - description, - description_long, - contact, - nuts, - icon_url, - urls, - motd, - time, - tos_url, - ) = match mint_info { - Some(mint_info) => { - let MintInfo { - name, - pubkey, - version, - description, - description_long, - contact, - nuts, - icon_url, - urls, - motd, - time, - tos_url, - } = mint_info; - - ( - name, - pubkey.map(|p| p.to_bytes().to_vec()), - version.map(|v| serde_json::to_string(&v).ok()), - description, - description_long, - contact.map(|c| serde_json::to_string(&c).ok()), - serde_json::to_string(&nuts).ok(), - icon_url, - urls.map(|c| serde_json::to_string(&c).ok()), - motd, - time, - tos_url, - ) - } - None => ( - None, None, None, None, None, None, None, None, None, None, None, None, - ), - }; - - Statement::new( - r#" -INSERT INTO mint -( - mint_url, name, pubkey, version, description, description_long, - contact, nuts, icon_url, urls, motd, mint_time, tos_url -) -VALUES -( - :mint_url, :name, :pubkey, :version, :description, :description_long, - :contact, :nuts, :icon_url, :urls, :motd, :mint_time, :tos_url -) -ON CONFLICT(mint_url) DO UPDATE SET - name = excluded.name, - pubkey = excluded.pubkey, - version = excluded.version, - description = excluded.description, - description_long = excluded.description_long, - contact = excluded.contact, - nuts = excluded.nuts, - icon_url = excluded.icon_url, - urls = excluded.urls, - motd = excluded.motd, - mint_time = excluded.mint_time, - tos_url = excluded.tos_url -; - "#, - ) - .bind(":mint_url", mint_url.to_string()) - .bind(":name", name) - .bind(":pubkey", pubkey) - .bind(":version", version) - .bind(":description", description) - .bind(":description_long", description_long) - .bind(":contact", contact) - .bind(":nuts", nuts) - .bind(":icon_url", icon_url) - .bind(":urls", urls) - .bind(":motd", motd) - .bind(":mint_time", time.map(|v| v as i64)) - .bind(":tos_url", tos_url) - .execute(&self.pool.get().map_err(Error::Pool)?) - .map_err(Error::Sqlite)?; - - Ok(()) +#[async_trait::async_trait] +impl DatabaseExecutor for SimpleAsyncRusqlite { + fn name() -> &'static str { + "sqlite" } - #[instrument(skip(self))] - async fn remove_mint(&self, mint_url: MintUrl) -> Result<(), Self::Err> { - let conn = self.pool.get().map_err(Error::Pool)?; + async fn execute(&self, statement: Statement) -> Result { + let conn = self.0.get().map_err(|e| Error::Database(Box::new(e)))?; + let mut stmt = self + .get_stmt(&conn, statement) + .map_err(|e| Error::Database(Box::new(e)))?; - Statement::new(r#"DELETE FROM mint WHERE mint_url=:mint_url"#) - .bind(":mint_url", mint_url.to_string()) - .execute(&conn) - .map_err(Error::Sqlite)?; - - Ok(()) + Ok(stmt + .raw_execute() + .map_err(|e| Error::Database(Box::new(e)))?) } - #[instrument(skip(self))] - async fn get_mint(&self, mint_url: MintUrl) -> Result, Self::Err> { - Ok(Statement::new( - r#" - SELECT - name, - pubkey, - version, - description, - description_long, - contact, - nuts, - icon_url, - motd, - urls, - mint_time, - tos_url - FROM - mint - WHERE mint_url = :mint_url - "#, - ) - .bind(":mint_url", mint_url.to_string()) - .fetch_one(&self.pool.get().map_err(Error::Pool)?) - .map_err(Error::Sqlite)? - .map(sqlite_row_to_mint_info) - .transpose()?) - } + async fn fetch_one(&self, statement: Statement) -> Result>, Error> { + let conn = self.0.get().map_err(|e| Error::Database(Box::new(e)))?; + let mut stmt = self + .get_stmt(&conn, statement) + .map_err(|e| Error::Database(Box::new(e)))?; - #[instrument(skip(self))] - async fn get_mints(&self) -> Result>, Self::Err> { - Ok(Statement::new( - r#" - SELECT - name, - pubkey, - version, - description, - description_long, - contact, - nuts, - icon_url, - motd, - urls, - mint_time, - tos_url, - mint_url - FROM - mint - "#, - ) - .fetch_all(&self.pool.get().map_err(Error::Pool)?) - .map_err(Error::Sqlite)? - .into_iter() - .map(|mut row| { - let url = column_as_string!( - row.pop().ok_or(Error::MissingColumn(0, 1))?, - MintUrl::from_str - ); + let columns = stmt.column_count(); - Ok((url, sqlite_row_to_mint_info(row).ok())) - }) - .collect::, Error>>()?) + let mut rows = stmt.raw_query(); + rows.next() + .map_err(|e| Error::Database(Box::new(e)))? + .map(|row| { + (0..columns) + .map(|i| row.get(i).map(from_sqlite)) + .collect::, _>>() + }) + .transpose() + .map_err(|e| Error::Database(Box::new(e))) } - #[instrument(skip(self))] - async fn update_mint_url( - &self, - old_mint_url: MintUrl, - new_mint_url: MintUrl, - ) -> Result<(), Self::Err> { - let tables = ["mint_quote", "proof"]; - let conn = self.pool.get().map_err(Error::Pool)?; - - for table in &tables { - let query = format!( - r#" - UPDATE {table} - SET mint_url = :new_mint_url - WHERE mint_url = :old_mint_url - "# - ); + async fn fetch_all(&self, statement: Statement) -> Result>, Error> { + let conn = self.0.get().map_err(|e| Error::Database(Box::new(e)))?; + let mut stmt = self + .get_stmt(&conn, statement) + .map_err(|e| Error::Database(Box::new(e)))?; - Statement::new(query) - .bind(":new_mint_url", new_mint_url.to_string()) - .bind(":old_mint_url", old_mint_url.to_string()) - .execute(&conn) - .map_err(Error::Sqlite)?; - } + let columns = stmt.column_count(); - Ok(()) - } + let mut rows = stmt.raw_query(); + let mut results = vec![]; - #[instrument(skip(self, keysets))] - async fn add_mint_keysets( - &self, - mint_url: MintUrl, - keysets: Vec, - ) -> Result<(), Self::Err> { - let conn = self.pool.get().map_err(Error::Pool)?; - for keyset in keysets { - Statement::new( - r#" - INSERT INTO keyset - (mint_url, id, unit, active, input_fee_ppk, final_expiry) - VALUES - (:mint_url, :id, :unit, :active, :input_fee_ppk, :final_expiry) - ON CONFLICT(id) DO UPDATE SET - mint_url = excluded.mint_url, - unit = excluded.unit, - active = excluded.active, - input_fee_ppk = excluded.input_fee_ppk, - final_expiry = excluded.final_expiry; - "#, + while let Some(row) = rows.next().map_err(|e| Error::Database(Box::new(e)))? { + results.push( + (0..columns) + .map(|i| row.get(i).map(from_sqlite)) + .collect::, _>>() + .map_err(|e| Error::Database(Box::new(e)))?, ) - .bind(":mint_url", mint_url.to_string()) - .bind(":id", keyset.id.to_string()) - .bind(":unit", keyset.unit.to_string()) - .bind(":active", keyset.active) - .bind(":input_fee_ppk", keyset.input_fee_ppk as i64) - .bind(":final_expiry", keyset.final_expiry.map(|v| v as i64)) - .execute(&conn) - .map_err(Error::Sqlite)?; - } - - Ok(()) - } - - #[instrument(skip(self))] - async fn get_mint_keysets( - &self, - mint_url: MintUrl, - ) -> Result>, Self::Err> { - let keysets = Statement::new( - r#" - SELECT - id, - unit, - active, - input_fee_ppk, - final_expiry - FROM - keyset - WHERE mint_url = :mint_url - "#, - ) - .bind(":mint_url", mint_url.to_string()) - .fetch_all(&self.pool.get().map_err(Error::Pool)?) - .map_err(Error::Sqlite)? - .into_iter() - .map(sqlite_row_to_keyset) - .collect::, Error>>()?; - - match keysets.is_empty() { - false => Ok(Some(keysets)), - true => Ok(None), } - } - - #[instrument(skip(self), fields(keyset_id = %keyset_id))] - async fn get_keyset_by_id(&self, keyset_id: &Id) -> Result, Self::Err> { - Ok(Statement::new( - r#" - SELECT - id, - unit, - active, - input_fee_ppk, - final_expiry - FROM - keyset - WHERE id = :id - "#, - ) - .bind(":id", keyset_id.to_string()) - .fetch_one(&self.pool.get().map_err(Error::Pool)?) - .map_err(Error::Sqlite)? - .map(sqlite_row_to_keyset) - .transpose()?) - } - #[instrument(skip_all)] - async fn add_mint_quote(&self, quote: MintQuote) -> Result<(), Self::Err> { - Statement::new( - r#" -INSERT INTO mint_quote -(id, mint_url, amount, unit, request, state, expiry, secret_key, payment_method, amount_issued, amount_paid) -VALUES -(:id, :mint_url, :amount, :unit, :request, :state, :expiry, :secret_key, :payment_method, :amount_issued, :amount_paid) -ON CONFLICT(id) DO UPDATE SET - mint_url = excluded.mint_url, - amount = excluded.amount, - unit = excluded.unit, - request = excluded.request, - state = excluded.state, - expiry = excluded.expiry, - secret_key = excluded.secret_key, - payment_method = excluded.payment_method, - amount_issued = excluded.amount_issued, - amount_paid = excluded.amount_paid -; - "#, - ) - .bind(":id", quote.id.to_string()) - .bind(":mint_url", quote.mint_url.to_string()) - .bind(":amount", quote.amount.map(|a| a.to_i64())) - .bind(":unit", quote.unit.to_string()) - .bind(":request", quote.request) - .bind(":state", quote.state.to_string()) - .bind(":expiry", quote.expiry as i64) - .bind(":secret_key", quote.secret_key.map(|p| p.to_string())) - .bind(":payment_method", quote.payment_method.to_string()) - .bind(":amount_issued", quote.amount_issued.to_i64()) - .bind(":amount_paid", quote.amount_paid.to_i64()) - .execute(&self.pool.get().map_err(Error::Pool)?) - .map_err(Error::Sqlite)?; - - Ok(()) + Ok(results) } - #[instrument(skip(self))] - async fn get_mint_quote(&self, quote_id: &str) -> Result, Self::Err> { - Ok(Statement::new( - r#" - SELECT - id, - mint_url, - amount, - unit, - request, - state, - expiry, - secret_key, - payment_method, - amount_issued, - amount_paid - FROM - mint_quote - WHERE - id = :id - "#, - ) - .bind(":id", quote_id.to_string()) - .fetch_one(&self.pool.get().map_err(Error::Pool)?) - .map_err(Error::Sqlite)? - .map(sqlite_row_to_mint_quote) - .transpose()?) - } + async fn pluck(&self, statement: Statement) -> Result, Error> { + let conn = self.0.get().map_err(|e| Error::Database(Box::new(e)))?; + let mut stmt = self + .get_stmt(&conn, statement) + .map_err(|e| Error::Database(Box::new(e)))?; - #[instrument(skip(self))] - async fn get_mint_quotes(&self) -> Result, Self::Err> { - Ok(Statement::new( - r#" - SELECT - id, - mint_url, - amount, - unit, - request, - state, - expiry, - secret_key - FROM - mint_quote - "#, - ) - .fetch_all(&self.pool.get().map_err(Error::Pool)?) - .map_err(Error::Sqlite)? - .into_iter() - .map(sqlite_row_to_mint_quote) - .collect::>()?) + let mut rows = stmt.raw_query(); + rows.next() + .map_err(|e| Error::Database(Box::new(e)))? + .map(|row| row.get(0usize).map(from_sqlite)) + .transpose() + .map_err(|e| Error::Database(Box::new(e))) } - #[instrument(skip(self))] - async fn remove_mint_quote(&self, quote_id: &str) -> Result<(), Self::Err> { - Statement::new(r#"DELETE FROM mint_quote WHERE id=:id"#) - .bind(":id", quote_id.to_string()) - .execute(&self.pool.get().map_err(Error::Pool)?) - .map_err(Error::Sqlite)?; - - Ok(()) - } - - #[instrument(skip_all)] - async fn add_melt_quote(&self, quote: wallet::MeltQuote) -> Result<(), Self::Err> { - Statement::new( - r#" -INSERT INTO melt_quote -(id, unit, amount, request, fee_reserve, state, expiry) -VALUES -(:id, :unit, :amount, :request, :fee_reserve, :state, :expiry) -ON CONFLICT(id) DO UPDATE SET - unit = excluded.unit, - amount = excluded.amount, - request = excluded.request, - fee_reserve = excluded.fee_reserve, - state = excluded.state, - expiry = excluded.expiry -; - "#, - ) - .bind(":id", quote.id.to_string()) - .bind(":unit", quote.unit.to_string()) - .bind(":amount", u64::from(quote.amount) as i64) - .bind(":request", quote.request) - .bind(":fee_reserve", u64::from(quote.fee_reserve) as i64) - .bind(":state", quote.state.to_string()) - .bind(":expiry", quote.expiry as i64) - .execute(&self.pool.get().map_err(Error::Pool)?) - .map_err(Error::Sqlite)?; - - Ok(()) - } - - #[instrument(skip(self))] - async fn get_melt_quote(&self, quote_id: &str) -> Result, Self::Err> { - Ok(Statement::new( - r#" - SELECT - id, - unit, - amount, - request, - fee_reserve, - state, - expiry, - payment_preimage - FROM - melt_quote - WHERE - id=:id - "#, - ) - .bind(":id", quote_id.to_owned()) - .fetch_one(&self.pool.get().map_err(Error::Pool)?) - .map_err(Error::Sqlite)? - .map(sqlite_row_to_melt_quote) - .transpose()?) - } - - #[instrument(skip(self))] - async fn get_melt_quotes(&self) -> Result, Self::Err> { - Ok(Statement::new( - r#" - SELECT - id, - unit, - amount, - request, - fee_reserve, - state, - expiry, - payment_preimage - FROM - melt_quote - "#, - ) - .fetch_all(&self.pool.get().map_err(Error::Pool)?) - .map_err(Error::Sqlite)? - .into_iter() - .map(sqlite_row_to_melt_quote) - .collect::>()?) - } + async fn batch(&self, mut statement: Statement) -> Result<(), Error> { + let conn = self.0.get().map_err(|e| Error::Database(Box::new(e)))?; - #[instrument(skip(self))] - async fn remove_melt_quote(&self, quote_id: &str) -> Result<(), Self::Err> { - Statement::new(r#"DELETE FROM melt_quote WHERE id=:id"#) - .bind(":id", quote_id.to_owned()) - .execute(&self.pool.get().map_err(Error::Pool)?) - .map_err(Error::Sqlite)?; + let sql = { + let part = statement + .parts + .pop() + .ok_or(Error::Internal("Empty SQL".to_owned()))?; - Ok(()) - } - - #[instrument(skip_all)] - async fn add_keys(&self, keyset: KeySet) -> Result<(), Self::Err> { - // Recompute ID for verification - keyset.verify_id()?; - - Statement::new( - r#" - INSERT INTO key - (id, keys) - VALUES - (:id, :keys) - ON CONFLICT(id) DO UPDATE SET - keys = excluded.keys - "#, - ) - .bind(":id", keyset.id.to_string()) - .bind( - ":keys", - serde_json::to_string(&keyset.keys).map_err(Error::from)?, - ) - .execute(&self.pool.get().map_err(Error::Pool)?) - .map_err(Error::Sqlite)?; - - Ok(()) - } - - #[instrument(skip(self), fields(keyset_id = %keyset_id))] - async fn get_keys(&self, keyset_id: &Id) -> Result, Self::Err> { - Ok(Statement::new( - r#" - SELECT - keys - FROM key - WHERE id = :id - "#, - ) - .bind(":id", keyset_id.to_string()) - .plunk(&self.pool.get().map_err(Error::Pool)?) - .map_err(Error::Sqlite)? - .map(|keys| { - let keys = column_as_string!(keys); - serde_json::from_str(&keys).map_err(Error::from) - }) - .transpose()?) - } - - #[instrument(skip(self))] - async fn remove_keys(&self, id: &Id) -> Result<(), Self::Err> { - Statement::new(r#"DELETE FROM key WHERE id = :id"#) - .bind(":id", id.to_string()) - .plunk(&self.pool.get().map_err(Error::Pool)?) - .map_err(Error::Sqlite)?; - - Ok(()) - } - - async fn update_proofs( - &self, - added: Vec, - removed_ys: Vec, - ) -> Result<(), Self::Err> { - // TODO: Use a transaction for all these operations - for proof in added { - Statement::new( - r#" - INSERT INTO proof - (y, mint_url, state, spending_condition, unit, amount, keyset_id, secret, c, witness, dleq_e, dleq_s, dleq_r) - VALUES - (:y, :mint_url, :state, :spending_condition, :unit, :amount, :keyset_id, :secret, :c, :witness, :dleq_e, :dleq_s, :dleq_r) - ON CONFLICT(y) DO UPDATE SET - mint_url = excluded.mint_url, - state = excluded.state, - spending_condition = excluded.spending_condition, - unit = excluded.unit, - amount = excluded.amount, - keyset_id = excluded.keyset_id, - secret = excluded.secret, - c = excluded.c, - witness = excluded.witness, - dleq_e = excluded.dleq_e, - dleq_s = excluded.dleq_s, - dleq_r = excluded.dleq_r - ; - "#, - ) - .bind(":y", proof.y.to_bytes().to_vec()) - .bind(":mint_url", proof.mint_url.to_string()) - .bind(":state",proof.state.to_string()) - .bind( - ":spending_condition", - proof - .spending_condition - .map(|s| serde_json::to_string(&s).ok()), - ) - .bind(":unit", proof.unit.to_string()) - .bind(":amount", u64::from(proof.proof.amount) as i64) - .bind(":keyset_id", proof.proof.keyset_id.to_string()) - .bind(":secret", proof.proof.secret.to_string()) - .bind(":c", proof.proof.c.to_bytes().to_vec()) - .bind( - ":witness", - proof - .proof - .witness - .map(|w| serde_json::to_string(&w).unwrap()), - ) - .bind( - ":dleq_e", - proof.proof.dleq.as_ref().map(|dleq| dleq.e.to_secret_bytes().to_vec()), - ) - .bind( - ":dleq_s", - proof.proof.dleq.as_ref().map(|dleq| dleq.s.to_secret_bytes().to_vec()), - ) - .bind( - ":dleq_r", - proof.proof.dleq.as_ref().map(|dleq| dleq.r.to_secret_bytes().to_vec()), - ) - .execute(&self.pool.get().map_err(Error::Pool)?) - .map_err(Error::Sqlite)?; - } - - Statement::new(r#"DELETE FROM proof WHERE y IN (:ys)"#) - .bind_vec( - ":ys", - removed_ys.iter().map(|y| y.to_bytes().to_vec()).collect(), - ) - .execute(&self.pool.get().map_err(Error::Pool)?) - .map_err(Error::Sqlite)?; - - Ok(()) - } - - #[instrument(skip(self, state, spending_conditions))] - async fn get_proofs( - &self, - mint_url: Option, - unit: Option, - state: Option>, - spending_conditions: Option>, - ) -> Result, Self::Err> { - Ok(Statement::new( - r#" - SELECT - amount, - unit, - keyset_id, - secret, - c, - witness, - dleq_e, - dleq_s, - dleq_r, - y, - mint_url, - state, - spending_condition - FROM proof - "#, - ) - .fetch_all(&self.pool.get().map_err(Error::Pool)?) - .map_err(Error::Sqlite)? - .into_iter() - .filter_map(|row| { - let row = sqlite_row_to_proof_info(row).ok()?; + if !statement.parts.is_empty() || matches!(part, SqlPart::Placeholder(_, _)) { + return Err(Error::Internal( + "Invalid usage, batch does not support placeholders".to_owned(), + )); + } - if row.matches_conditions(&mint_url, &unit, &state, &spending_conditions) { - Some(row) + if let SqlPart::Raw(sql) = part { + sql } else { - None + unreachable!() } - }) - .collect::>()) - } - - async fn update_proofs_state(&self, ys: Vec, state: State) -> Result<(), Self::Err> { - Statement::new("UPDATE proof SET state = :state WHERE y IN (:ys)") - .bind_vec(":ys", ys.iter().map(|y| y.to_bytes().to_vec()).collect()) - .bind(":state", state.to_string()) - .execute(&self.pool.get().map_err(Error::Pool)?) - .map_err(Error::Sqlite)?; - - Ok(()) - } - - #[instrument(skip(self), fields(keyset_id = %keyset_id))] - async fn increment_keyset_counter(&self, keyset_id: &Id, count: u32) -> Result<(), Self::Err> { - Statement::new( - r#" - UPDATE keyset - SET counter=counter+:count - WHERE id=:id - "#, - ) - .bind(":count", count) - .bind(":id", keyset_id.to_string()) - .execute(&self.pool.get().map_err(Error::Pool)?) - .map_err(Error::Sqlite)?; - - Ok(()) - } - - #[instrument(skip(self), fields(keyset_id = %keyset_id))] - async fn get_keyset_counter(&self, keyset_id: &Id) -> Result, Self::Err> { - Ok(Statement::new( - r#" - SELECT - counter - FROM - keyset - WHERE - id=:id - "#, - ) - .bind(":id", keyset_id.to_string()) - .plunk(&self.pool.get().map_err(Error::Pool)?) - .map_err(Error::Sqlite)? - .map(|n| Ok::<_, Error>(column_as_number!(n))) - .transpose()?) - } - - #[instrument(skip(self))] - async fn add_transaction(&self, transaction: Transaction) -> Result<(), Self::Err> { - let mint_url = transaction.mint_url.to_string(); - let direction = transaction.direction.to_string(); - let unit = transaction.unit.to_string(); - let amount = u64::from(transaction.amount) as i64; - let fee = u64::from(transaction.fee) as i64; - let ys = transaction - .ys - .iter() - .flat_map(|y| y.to_bytes().to_vec()) - .collect::>(); - - Statement::new( - r#" -INSERT INTO transactions -(id, mint_url, direction, unit, amount, fee, ys, timestamp, memo, metadata) -VALUES -(:id, :mint_url, :direction, :unit, :amount, :fee, :ys, :timestamp, :memo, :metadata) -ON CONFLICT(id) DO UPDATE SET - mint_url = excluded.mint_url, - direction = excluded.direction, - unit = excluded.unit, - amount = excluded.amount, - fee = excluded.fee, - ys = excluded.ys, - timestamp = excluded.timestamp, - memo = excluded.memo, - metadata = excluded.metadata -; - "#, - ) - .bind(":id", transaction.id().as_slice().to_vec()) - .bind(":mint_url", mint_url) - .bind(":direction", direction) - .bind(":unit", unit) - .bind(":amount", amount) - .bind(":fee", fee) - .bind(":ys", ys) - .bind(":timestamp", transaction.timestamp as i64) - .bind(":memo", transaction.memo) - .bind( - ":metadata", - serde_json::to_string(&transaction.metadata).map_err(Error::from)?, - ) - .execute(&self.pool.get().map_err(Error::Pool)?) - .map_err(Error::Sqlite)?; + }; - Ok(()) + conn.execute_batch(&sql) + .map_err(|e| Error::Database(Box::new(e))) } +} - #[instrument(skip(self))] - async fn get_transaction( - &self, - transaction_id: TransactionId, - ) -> Result, Self::Err> { - Ok(Statement::new( - r#" - SELECT - mint_url, - direction, - unit, - amount, - fee, - ys, - timestamp, - memo, - metadata - FROM - transactions - WHERE - id = :id - "#, - ) - .bind(":id", transaction_id.as_slice().to_vec()) - .fetch_one(&self.pool.get().map_err(Error::Pool)?) - .map_err(Error::Sqlite)? - .map(sqlite_row_to_transaction) - .transpose()?) +impl From for SimpleAsyncRusqlite { + fn from(value: PathBuf) -> Self { + SimpleAsyncRusqlite(create_sqlite_pool(value.to_str().unwrap_or_default(), None)) } +} - #[instrument(skip(self))] - async fn list_transactions( - &self, - mint_url: Option, - direction: Option, - unit: Option, - ) -> Result, Self::Err> { - Ok(Statement::new( - r#" - SELECT - mint_url, - direction, - unit, - amount, - fee, - ys, - timestamp, - memo, - metadata - FROM - transactions - "#, - ) - .fetch_all(&self.pool.get().map_err(Error::Pool)?) - .map_err(Error::Sqlite)? - .into_iter() - .filter_map(|row| { - // TODO: Avoid a table scan by passing the heavy lifting of checking to the DB engine - let transaction = sqlite_row_to_transaction(row).ok()?; - if transaction.matches_conditions(&mint_url, &direction, &unit) { - Some(transaction) - } else { - None - } - }) - .collect::>()) - } - - #[instrument(skip(self))] - async fn remove_transaction(&self, transaction_id: TransactionId) -> Result<(), Self::Err> { - Statement::new(r#"DELETE FROM transactions WHERE id=:id"#) - .bind(":id", transaction_id.as_slice().to_vec()) - .execute(&self.pool.get().map_err(Error::Pool)?) - .map_err(Error::Sqlite)?; - - Ok(()) +impl From<&str> for SimpleAsyncRusqlite { + fn from(value: &str) -> Self { + SimpleAsyncRusqlite(create_sqlite_pool(value, None)) } } -fn sqlite_row_to_mint_info(row: Vec) -> Result { - unpack_into!( - let ( - name, - pubkey, - version, - description, - description_long, - contact, - nuts, - icon_url, - motd, - urls, - mint_time, - tos_url - ) = row - ); - - Ok(MintInfo { - name: column_as_nullable_string!(&name), - pubkey: column_as_nullable_string!(&pubkey, |v| serde_json::from_str(v).ok(), |v| { - serde_json::from_slice(v).ok() - }), - version: column_as_nullable_string!(&version).and_then(|v| serde_json::from_str(&v).ok()), - description: column_as_nullable_string!(description), - description_long: column_as_nullable_string!(description_long), - contact: column_as_nullable_string!(contact, |v| serde_json::from_str(&v).ok()), - nuts: column_as_nullable_string!(nuts, |v| serde_json::from_str(&v).ok()) - .unwrap_or_default(), - urls: column_as_nullable_string!(urls, |v| serde_json::from_str(&v).ok()), - icon_url: column_as_nullable_string!(icon_url), - motd: column_as_nullable_string!(motd), - time: column_as_nullable_number!(mint_time).map(|t| t), - tos_url: column_as_nullable_string!(tos_url), - }) +impl From<(&str, &str)> for SimpleAsyncRusqlite { + fn from((value, pass): (&str, &str)) -> Self { + SimpleAsyncRusqlite(create_sqlite_pool(value, Some(pass.to_owned()))) + } } -#[instrument(skip_all)] -fn sqlite_row_to_keyset(row: Vec) -> Result { - unpack_into!( - let ( - id, - unit, - active, - input_fee_ppk, - final_expiry - ) = row - ); - - Ok(KeySetInfo { - id: column_as_string!(id, Id::from_str, Id::from_bytes), - unit: column_as_string!(unit, CurrencyUnit::from_str), - active: matches!(active, Column::Integer(1)), - input_fee_ppk: column_as_nullable_number!(input_fee_ppk).unwrap_or_default(), - final_expiry: column_as_nullable_number!(final_expiry), - }) +impl From<(PathBuf, &str)> for SimpleAsyncRusqlite { + fn from((value, pass): (PathBuf, &str)) -> Self { + SimpleAsyncRusqlite(create_sqlite_pool( + value.to_str().unwrap_or_default(), + Some(pass.to_owned()), + )) + } } -fn sqlite_row_to_mint_quote(row: Vec) -> Result { - unpack_into!( - let ( - id, - mint_url, - amount, - unit, - request, - state, - expiry, - secret_key, - row_method, - row_amount_minted, - row_amount_paid - ) = row - ); - - let amount: Option = column_as_nullable_number!(amount); - - let amount_paid: u64 = column_as_number!(row_amount_paid); - let amount_minted: u64 = column_as_number!(row_amount_minted); - let payment_method = - PaymentMethod::from_str(&column_as_string!(row_method)).map_err(Error::from)?; - - Ok(MintQuote { - id: column_as_string!(id), - mint_url: column_as_string!(mint_url, MintUrl::from_str), - amount: amount.and_then(Amount::from_i64), - unit: column_as_string!(unit, CurrencyUnit::from_str), - request: column_as_string!(request), - state: column_as_string!(state, MintQuoteState::from_str), - expiry: column_as_number!(expiry), - secret_key: column_as_nullable_string!(secret_key) - .map(|v| SecretKey::from_str(&v)) - .transpose()?, - payment_method, - amount_issued: amount_minted.into(), - amount_paid: amount_paid.into(), - }) +impl From<(&str, String)> for SimpleAsyncRusqlite { + fn from((value, pass): (&str, String)) -> Self { + SimpleAsyncRusqlite(create_sqlite_pool(value, Some(pass))) + } } -fn sqlite_row_to_melt_quote(row: Vec) -> Result { - unpack_into!( - let ( - id, - unit, - amount, - request, - fee_reserve, - state, - expiry, - payment_preimage - ) = row - ); - - let amount: u64 = column_as_number!(amount); - let fee_reserve: u64 = column_as_number!(fee_reserve); - - Ok(wallet::MeltQuote { - id: column_as_string!(id), - amount: Amount::from(amount), - unit: column_as_string!(unit, CurrencyUnit::from_str), - request: column_as_string!(request), - fee_reserve: Amount::from(fee_reserve), - state: column_as_string!(state, MeltQuoteState::from_str), - expiry: column_as_number!(expiry), - payment_preimage: column_as_nullable_string!(payment_preimage), - }) +impl From<(PathBuf, String)> for SimpleAsyncRusqlite { + fn from((value, pass): (PathBuf, String)) -> Self { + SimpleAsyncRusqlite(create_sqlite_pool( + value.to_str().unwrap_or_default(), + Some(pass), + )) + } } -fn sqlite_row_to_proof_info(row: Vec) -> Result { - unpack_into!( - let ( - amount, - unit, - keyset_id, - secret, - c, - witness, - dleq_e, - dleq_s, - dleq_r, - y, - mint_url, - state, - spending_condition - ) = row - ); - - let dleq = match ( - column_as_nullable_binary!(dleq_e), - column_as_nullable_binary!(dleq_s), - column_as_nullable_binary!(dleq_r), - ) { - (Some(e), Some(s), Some(r)) => { - let e_key = SecretKey::from_slice(&e)?; - let s_key = SecretKey::from_slice(&s)?; - let r_key = SecretKey::from_slice(&r)?; - - Some(ProofDleq::new(e_key, s_key, r_key)) - } - _ => None, - }; - - let amount: u64 = column_as_number!(amount); - let proof = Proof { - amount: Amount::from(amount), - keyset_id: column_as_string!(keyset_id, Id::from_str), - secret: column_as_string!(secret, Secret::from_str), - witness: column_as_nullable_string!(witness, |v| { serde_json::from_str(&v).ok() }, |v| { - serde_json::from_slice(&v).ok() - }), - c: column_as_string!(c, PublicKey::from_str, PublicKey::from_slice), - dleq, - }; - - Ok(ProofInfo { - proof, - y: column_as_string!(y, PublicKey::from_str, PublicKey::from_slice), - mint_url: column_as_string!(mint_url, MintUrl::from_str), - state: column_as_string!(state, State::from_str), - spending_condition: column_as_nullable_string!( - spending_condition, - |r| { serde_json::from_str(&r).ok() }, - |r| { serde_json::from_slice(&r).ok() } - ), - unit: column_as_string!(unit, CurrencyUnit::from_str), - }) +impl From<&PathBuf> for SimpleAsyncRusqlite { + fn from(value: &PathBuf) -> Self { + SimpleAsyncRusqlite(create_sqlite_pool(value.to_str().unwrap_or_default(), None)) + } } -fn sqlite_row_to_transaction(row: Vec) -> Result { - unpack_into!( - let ( - mint_url, - direction, - unit, - amount, - fee, - ys, - timestamp, - memo, - metadata - ) = row - ); - - let amount: u64 = column_as_number!(amount); - let fee: u64 = column_as_number!(fee); - - Ok(Transaction { - mint_url: column_as_string!(mint_url, MintUrl::from_str), - direction: column_as_string!(direction, TransactionDirection::from_str), - unit: column_as_string!(unit, CurrencyUnit::from_str), - amount: Amount::from(amount), - fee: Amount::from(fee), - ys: column_as_binary!(ys) - .chunks(33) - .map(PublicKey::from_slice) - .collect::, _>>()?, - timestamp: column_as_number!(timestamp), - memo: column_as_nullable_string!(memo), - metadata: column_as_nullable_string!(metadata, |v| serde_json::from_str(&v).ok(), |v| { - serde_json::from_slice(&v).ok() - }) - .unwrap_or_default(), - }) -} +/// Mint SQLite implementation with rusqlite +pub type WalletSqliteDatabase = SQLWalletDatabase; #[cfg(test)] mod tests { + use std::str::FromStr; + use cdk_common::database::WalletDatabase; use cdk_common::nuts::{ProofDleq, State}; use cdk_common::secret::Secret; @@ -1158,7 +211,7 @@ mod tests { let path = std::env::temp_dir() .to_path_buf() .join(format!("cdk-test-{}.sqlite", uuid::Uuid::new_v4())); - let db = WalletSqliteDatabase::new(path, "password".to_string()) + let db = WalletSqliteDatabase::new((path, "password".to_string())) .await .unwrap(); @@ -1176,8 +229,6 @@ mod tests { #[tokio::test] async fn test_proof_with_dleq() { - use std::str::FromStr; - use cdk_common::common::ProofInfo; use cdk_common::mint_url::MintUrl; use cdk_common::nuts::{CurrencyUnit, Id, Proof, PublicKey, SecretKey}; @@ -1189,7 +240,7 @@ mod tests { .join(format!("cdk-test-dleq-{}.sqlite", uuid::Uuid::new_v4())); #[cfg(feature = "sqlcipher")] - let db = WalletSqliteDatabase::new(path, "password".to_string()) + let db = WalletSqliteDatabase::new((path, "password".to_string())) .await .unwrap(); diff --git a/crates/cdk-sqlite/tests/legacy-sqlx.sql b/crates/cdk-sqlite/tests/legacy-sqlx.sql index f28c566f2..dfe4d79d7 100644 --- a/crates/cdk-sqlite/tests/legacy-sqlx.sql +++ b/crates/cdk-sqlite/tests/legacy-sqlx.sql @@ -70,7 +70,7 @@ CREATE TABLE IF NOT EXISTS "proof" ( amount INTEGER NOT NULL, keyset_id TEXT NOT NULL, -- no FK constraint here secret TEXT NOT NULL, - c BLOB NOT NULL, + c BLOBNOT NULL, witness TEXT, state TEXT CHECK (state IN ('SPENT', 'PENDING', 'UNSPENT', 'RESERVED', 'UNKNOWN')) NOT NULL, quote_id TEXT, From 034af740139b82fdc198e83b31a4cf8b308a16ad Mon Sep 17 00:00:00 2001 From: Cesar Rodas Date: Thu, 24 Jul 2025 10:44:16 -0300 Subject: [PATCH 038/321] Add Cache to SQL stmt The cache will store the placeholders and if possible the RAW SQL with position placeholders, to avoid repetitive computations --- crates/cdk-sql-common/Cargo.toml | 1 + crates/cdk-sql-common/src/stmt.rs | 79 ++++++++++++++++++++++++++++--- 2 files changed, 73 insertions(+), 7 deletions(-) diff --git a/crates/cdk-sql-common/Cargo.toml b/crates/cdk-sql-common/Cargo.toml index 406e12fb4..ce2a62021 100644 --- a/crates/cdk-sql-common/Cargo.toml +++ b/crates/cdk-sql-common/Cargo.toml @@ -28,3 +28,4 @@ serde.workspace = true serde_json.workspace = true lightning-invoice.workspace = true uuid.workspace = true +once_cell.workspace = true diff --git a/crates/cdk-sql-common/src/stmt.rs b/crates/cdk-sql-common/src/stmt.rs index 631d2b3d4..f66767bac 100644 --- a/crates/cdk-sql-common/src/stmt.rs +++ b/crates/cdk-sql-common/src/stmt.rs @@ -1,7 +1,9 @@ //! Stataments mod -use std::sync::Arc; +use std::collections::HashMap; +use std::sync::{Arc, RwLock}; use cdk_common::database::Error; +use once_cell::sync::Lazy; use crate::database::DatabaseExecutor; use crate::value::Value; @@ -140,9 +142,14 @@ pub fn split_sql_parts(input: &str) -> Result, SqlParseError> { Ok(parts) } +type Cache = HashMap, Option>)>; + /// Sql message #[derive(Debug, Default)] pub struct Statement { + cache: Arc>, + cached_sql: Option>, + sql: Option, /// The SQL statement pub parts: Vec, /// The expected response type @@ -151,11 +158,35 @@ pub struct Statement { impl Statement { /// Creates a new statement - pub fn new(sql: &str) -> Result { - Ok(Self { - parts: split_sql_parts(sql)?, - ..Default::default() - }) + fn new(sql: &str, cache: Arc>) -> Result { + let parsed = cache + .read() + .map(|cache| cache.get(sql).cloned()) + .ok() + .flatten(); + + if let Some((parts, cached_sql)) = parsed { + Ok(Self { + parts, + cached_sql, + sql: None, + cache, + ..Default::default() + }) + } else { + let parts = split_sql_parts(sql)?; + + let _ = cache.write().map(|mut cache| { + cache.insert(sql.to_owned(), (parts.clone(), None)); + }); + + Ok(Self { + parts, + sql: Some(sql.to_owned()), + cache, + ..Default::default() + }) + } } /// Convert Statement into a SQL statement and the list of placeholders @@ -164,7 +195,29 @@ impl Statement { /// to be more widely supported, although it can be reimplemented with other formats since part /// is public pub fn to_sql(self) -> Result<(String, Vec), Error> { + if let Some(cached_sql) = self.cached_sql { + let sql = cached_sql.to_string(); + let values = self + .parts + .into_iter() + .map(|x| match x { + SqlPart::Placeholder(name, value) => { + match value.ok_or(Error::MissingPlaceholder(name.to_string()))? { + PlaceholderValue::Value(value) => Ok(vec![value]), + PlaceholderValue::Set(values) => Ok(values), + } + } + SqlPart::Raw(_) => Ok(vec![]), + }) + .collect::, Error>>()? + .into_iter() + .flatten() + .collect::>(); + return Ok((sql, values)); + } + let mut placeholder_values = Vec::new(); + let mut can_be_cached = true; let sql = self .parts .into_iter() @@ -176,6 +229,7 @@ impl Statement { Ok::<_, Error>(format!("${}", placeholder_values.len())) } PlaceholderValue::Set(mut values) => { + can_be_cached = false; let start_size = placeholder_values.len(); placeholder_values.append(&mut values); let placeholders = (start_size + 1..=placeholder_values.len()) @@ -191,6 +245,16 @@ impl Statement { .collect::, _>>()? .join(" "); + if can_be_cached { + if let Some(original_sql) = self.sql { + let _ = self.cache.write().map(|mut cache| { + if let Some((_, cached_sql)) = cache.get_mut(&original_sql) { + *cached_sql = Some(sql.clone().into()); + } + }); + } + } + Ok((sql, placeholder_values)) } @@ -288,5 +352,6 @@ impl Statement { /// Creates a new query statement #[inline(always)] pub fn query(sql: &str) -> Result { - Statement::new(sql).map_err(|e| Error::Database(Box::new(e))) + static CACHE: Lazy>> = Lazy::new(|| Arc::new(RwLock::new(HashMap::new()))); + Statement::new(sql, CACHE.clone()).map_err(|e| Error::Database(Box::new(e))) } From 1f85d0fd7a381a9e10b5ef9a579e0eb503b8f78d Mon Sep 17 00:00:00 2001 From: Cesar Rodas Date: Fri, 25 Jul 2025 11:18:31 -0300 Subject: [PATCH 039/321] Changes 1. Fix migration to avoid re-running migration twice 2. Remove tokio dependency --- crates/cdk-sql-common/Cargo.toml | 1 - crates/cdk-sql-common/src/common.rs | 9 ++++++--- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/crates/cdk-sql-common/Cargo.toml b/crates/cdk-sql-common/Cargo.toml index ce2a62021..4ceb09034 100644 --- a/crates/cdk-sql-common/Cargo.toml +++ b/crates/cdk-sql-common/Cargo.toml @@ -22,7 +22,6 @@ async-trait.workspace = true cdk-common = { workspace = true, features = ["test"] } bitcoin.workspace = true thiserror.workspace = true -tokio.workspace = true tracing.workspace = true serde.workspace = true serde_json.workspace = true diff --git a/crates/cdk-sql-common/src/common.rs b/crates/cdk-sql-common/src/common.rs index b2962898a..325b84433 100644 --- a/crates/cdk-sql-common/src/common.rs +++ b/crates/cdk-sql-common/src/common.rs @@ -21,14 +21,17 @@ pub async fn migrate( // Apply each migration if it hasn’t been applied yet for (name, sql) in migrations { - if let Some((prefix, _)) = name.split_once(['/', '\\']) { + let basename = if let Some((prefix, basename)) = name.split_once(['/', '\\']) { if prefix != db_prefix { continue; } - } + basename + } else { + name + }; let is_missing = query("SELECT name FROM migrations WHERE name = :name")? - .bind("name", name) + .bind("name", basename) .pluck(conn) .await? .is_none(); From fb4c470a9a151dfda950f03cdec470d008f3c86c Mon Sep 17 00:00:00 2001 From: Cesar Rodas Date: Fri, 25 Jul 2025 21:36:50 -0300 Subject: [PATCH 040/321] Rename `still_active` to `stale` --- crates/cdk-sql-common/src/pool.rs | 19 +++++++++++-------- crates/cdk-sqlite/src/common.rs | 2 +- 2 files changed, 12 insertions(+), 9 deletions(-) diff --git a/crates/cdk-sql-common/src/pool.rs b/crates/cdk-sql-common/src/pool.rs index cbeadd7c3..6f8561e66 100644 --- a/crates/cdk-sql-common/src/pool.rs +++ b/crates/cdk-sql-common/src/pool.rs @@ -35,10 +35,13 @@ pub trait ResourceManager: Debug { /// The error the resource may return when creating a new instance type Error: Debug; - /// Creates a new resource with a given config + /// Creates a new resource with a given config. + /// + /// If `stale` is every set to TRUE it is assumed the resource is no longer valid and it will be + /// dropped. fn new_resource( config: &Self::Config, - still_valid: Arc, + stale: Arc, timeout: Duration, ) -> Result>; @@ -139,13 +142,13 @@ where let mut resources = self.queue.lock().map_err(|_| Error::Poison)?; loop { - if let Some(resource) = resources.pop() { - if resource.0.load(Ordering::SeqCst) { + if let Some((stale, resource)) = resources.pop() { + if !stale.load(Ordering::SeqCst) { drop(resources); self.in_use.fetch_add(1, Ordering::AcqRel); return Ok(PooledResource { - resource: Some(resource), + resource: Some((stale, resource)), pool: self.clone(), }); } @@ -154,12 +157,12 @@ where if self.in_use.load(Ordering::Relaxed) < self.max_size { drop(resources); self.in_use.fetch_add(1, Ordering::AcqRel); - let still_valid: Arc = Arc::new(true.into()); + let stale: Arc = Arc::new(false.into()); return Ok(PooledResource { resource: Some(( - still_valid.clone(), - RM::new_resource(&self.config, still_valid, timeout)?, + stale.clone(), + RM::new_resource(&self.config, stale, timeout)?, )), pool: self.clone(), }); diff --git a/crates/cdk-sqlite/src/common.rs b/crates/cdk-sqlite/src/common.rs index bdde9bf34..e0ea6f9ed 100644 --- a/crates/cdk-sqlite/src/common.rs +++ b/crates/cdk-sqlite/src/common.rs @@ -26,7 +26,7 @@ impl ResourceManager for SqliteConnectionManager { fn new_resource( config: &Self::Config, - _still_valid: Arc, + _stale: Arc, _timeout: Duration, ) -> Result> { let conn = if let Some(path) = config.path.as_ref() { From 99ced01e67fe474e2aa1f12bf8b9ae98872540d6 Mon Sep 17 00:00:00 2001 From: C Date: Sat, 26 Jul 2025 17:34:55 -0300 Subject: [PATCH 041/321] Apply suggestions from code review Co-authored-by: thesimplekid --- crates/cdk-sql-common/src/common.rs | 13 +++++++------ crates/cdk-sql-common/src/pool.rs | 2 +- crates/cdk-sql-common/src/stmt.rs | 6 ++++-- crates/cdk-sqlite/tests/legacy-sqlx.sql | 2 +- 4 files changed, 13 insertions(+), 10 deletions(-) diff --git a/crates/cdk-sql-common/src/common.rs b/crates/cdk-sql-common/src/common.rs index 325b84433..ccdd4cad0 100644 --- a/crates/cdk-sql-common/src/common.rs +++ b/crates/cdk-sql-common/src/common.rs @@ -21,13 +21,14 @@ pub async fn migrate( // Apply each migration if it hasn’t been applied yet for (name, sql) in migrations { - let basename = if let Some((prefix, basename)) = name.split_once(['/', '\\']) { - if prefix != db_prefix { - continue; + let basename = match name.split_once(['/', '\\']) { + Some((prefix, basename)) => { + if prefix != db_prefix { + continue; + } + basename } - basename - } else { - name + None => name, }; let is_missing = query("SELECT name FROM migrations WHERE name = :name")? diff --git a/crates/cdk-sql-common/src/pool.rs b/crates/cdk-sql-common/src/pool.rs index 6f8561e66..3085a0eea 100644 --- a/crates/cdk-sql-common/src/pool.rs +++ b/crates/cdk-sql-common/src/pool.rs @@ -37,7 +37,7 @@ pub trait ResourceManager: Debug { /// Creates a new resource with a given config. /// - /// If `stale` is every set to TRUE it is assumed the resource is no longer valid and it will be + /// If `stale` is ever set to TRUE it is assumed the resource is no longer valid and it will be /// dropped. fn new_resource( config: &Self::Config, diff --git a/crates/cdk-sql-common/src/stmt.rs b/crates/cdk-sql-common/src/stmt.rs index f66767bac..9f686e542 100644 --- a/crates/cdk-sql-common/src/stmt.rs +++ b/crates/cdk-sql-common/src/stmt.rs @@ -176,9 +176,11 @@ impl Statement { } else { let parts = split_sql_parts(sql)?; - let _ = cache.write().map(|mut cache| { + if let Ok(mut cache) = cache.write() { cache.insert(sql.to_owned(), (parts.clone(), None)); - }); + } else { + tracing::warn!("Failed to acquire write lock for SQL statement cache"); + } Ok(Self { parts, diff --git a/crates/cdk-sqlite/tests/legacy-sqlx.sql b/crates/cdk-sqlite/tests/legacy-sqlx.sql index dfe4d79d7..f28c566f2 100644 --- a/crates/cdk-sqlite/tests/legacy-sqlx.sql +++ b/crates/cdk-sqlite/tests/legacy-sqlx.sql @@ -70,7 +70,7 @@ CREATE TABLE IF NOT EXISTS "proof" ( amount INTEGER NOT NULL, keyset_id TEXT NOT NULL, -- no FK constraint here secret TEXT NOT NULL, - c BLOBNOT NULL, + c BLOB NOT NULL, witness TEXT, state TEXT CHECK (state IN ('SPENT', 'PENDING', 'UNSPENT', 'RESERVED', 'UNKNOWN')) NOT NULL, quote_id TEXT, From 659518f24192fd9ee74b9fbeef7e9411b4228e15 Mon Sep 17 00:00:00 2001 From: Cesar Rodas Date: Mon, 28 Jul 2025 14:24:07 -0300 Subject: [PATCH 042/321] Improve migrations Add the namespaced migrations and global migrations --- crates/cdk-sql-common/build.rs | 21 +++++++-- crates/cdk-sql-common/src/common.rs | 18 +++----- .../src/mint/auth/migrations.rs | 4 +- crates/cdk-sql-common/src/mint/migrations.rs | 46 +++++++++---------- .../cdk-sql-common/src/wallet/migrations.rs | 36 +++++++-------- 5 files changed, 67 insertions(+), 58 deletions(-) diff --git a/crates/cdk-sql-common/build.rs b/crates/cdk-sql-common/build.rs index 6b32a916b..37d494fce 100644 --- a/crates/cdk-sql-common/build.rs +++ b/crates/cdk-sql-common/build.rs @@ -22,14 +22,29 @@ fn main() { writeln!(out_file, "/// @generated").unwrap(); writeln!(out_file, "/// Auto-generated by build.rs").unwrap(); - writeln!(out_file, "pub static MIGRATIONS: &[(&str, &str)] = &[").unwrap(); + writeln!( + out_file, + "pub static MIGRATIONS: &[(&str, &str, &str)] = &[" + ) + .unwrap(); for path in &files { - let rel_name = &path.to_str().unwrap().replace("\\", "/")[skip_name + 1..]; // for Windows + let parts = path.to_str().unwrap().replace("\\", "/")[skip_name + 1..] + .split("/") + .map(|x| x.to_owned()) + .collect::>(); + + let prefix = if parts.len() == 2 { + parts.first().map(|x| x.to_owned()).unwrap_or_default() + } else { + "".to_owned() + }; + + let rel_name = &path.file_name().unwrap().to_str().unwrap(); let rel_path = &path.to_str().unwrap().replace("\\", "/")[skip_path..]; // for Windows writeln!( out_file, - " (\"{rel_name}\", include_str!(r#\".{rel_path}\"#))," + " (\"{prefix}\", \"{rel_name}\", include_str!(r#\".{rel_path}\"#))," ) .unwrap(); println!("cargo:rerun-if-changed={}", path.display()); diff --git a/crates/cdk-sql-common/src/common.rs b/crates/cdk-sql-common/src/common.rs index ccdd4cad0..ce52f7df4 100644 --- a/crates/cdk-sql-common/src/common.rs +++ b/crates/cdk-sql-common/src/common.rs @@ -6,7 +6,7 @@ use crate::stmt::query; pub async fn migrate( conn: &C, db_prefix: &str, - migrations: &[(&str, &str)], + migrations: &[(&str, &str, &str)], ) -> Result<(), cdk_common::database::Error> { query( r#" @@ -20,19 +20,13 @@ pub async fn migrate( .await?; // Apply each migration if it hasn’t been applied yet - for (name, sql) in migrations { - let basename = match name.split_once(['/', '\\']) { - Some((prefix, basename)) => { - if prefix != db_prefix { - continue; - } - basename - } - None => name, - }; + for (prefix, name, sql) in migrations { + if !prefix.is_empty() && *prefix != db_prefix { + continue; + } let is_missing = query("SELECT name FROM migrations WHERE name = :name")? - .bind("name", basename) + .bind("name", name) .pluck(conn) .await? .is_none(); diff --git a/crates/cdk-sql-common/src/mint/auth/migrations.rs b/crates/cdk-sql-common/src/mint/auth/migrations.rs index 75a1584f7..06f5b0bb3 100644 --- a/crates/cdk-sql-common/src/mint/auth/migrations.rs +++ b/crates/cdk-sql-common/src/mint/auth/migrations.rs @@ -1,5 +1,5 @@ /// @generated /// Auto-generated by build.rs -pub static MIGRATIONS: &[(&str, &str)] = &[ - ("sqlite/20250109143347_init.sql", include_str!(r#"./migrations/sqlite/20250109143347_init.sql"#)), +pub static MIGRATIONS: &[(&str, &str, &str)] = &[ + ("sqlite", "20250109143347_init.sql", include_str!(r#"./migrations/sqlite/20250109143347_init.sql"#)), ]; diff --git a/crates/cdk-sql-common/src/mint/migrations.rs b/crates/cdk-sql-common/src/mint/migrations.rs index f67690a7a..d97ccb4ee 100644 --- a/crates/cdk-sql-common/src/mint/migrations.rs +++ b/crates/cdk-sql-common/src/mint/migrations.rs @@ -1,26 +1,26 @@ /// @generated /// Auto-generated by build.rs -pub static MIGRATIONS: &[(&str, &str)] = &[ - ("sqlite/1_fix_sqlx_migration.sql", include_str!(r#"./migrations/sqlite/1_fix_sqlx_migration.sql"#)), - ("sqlite/20240612124932_init.sql", include_str!(r#"./migrations/sqlite/20240612124932_init.sql"#)), - ("sqlite/20240618195700_quote_state.sql", include_str!(r#"./migrations/sqlite/20240618195700_quote_state.sql"#)), - ("sqlite/20240626092101_nut04_state.sql", include_str!(r#"./migrations/sqlite/20240626092101_nut04_state.sql"#)), - ("sqlite/20240703122347_request_lookup_id.sql", include_str!(r#"./migrations/sqlite/20240703122347_request_lookup_id.sql"#)), - ("sqlite/20240710145043_input_fee.sql", include_str!(r#"./migrations/sqlite/20240710145043_input_fee.sql"#)), - ("sqlite/20240711183109_derivation_path_index.sql", include_str!(r#"./migrations/sqlite/20240711183109_derivation_path_index.sql"#)), - ("sqlite/20240718203721_allow_unspent.sql", include_str!(r#"./migrations/sqlite/20240718203721_allow_unspent.sql"#)), - ("sqlite/20240811031111_update_mint_url.sql", include_str!(r#"./migrations/sqlite/20240811031111_update_mint_url.sql"#)), - ("sqlite/20240919103407_proofs_quote_id.sql", include_str!(r#"./migrations/sqlite/20240919103407_proofs_quote_id.sql"#)), - ("sqlite/20240923153640_melt_requests.sql", include_str!(r#"./migrations/sqlite/20240923153640_melt_requests.sql"#)), - ("sqlite/20240930101140_dleq_for_sigs.sql", include_str!(r#"./migrations/sqlite/20240930101140_dleq_for_sigs.sql"#)), - ("sqlite/20241108093102_mint_mint_quote_pubkey.sql", include_str!(r#"./migrations/sqlite/20241108093102_mint_mint_quote_pubkey.sql"#)), - ("sqlite/20250103201327_amount_to_pay_msats.sql", include_str!(r#"./migrations/sqlite/20250103201327_amount_to_pay_msats.sql"#)), - ("sqlite/20250129200912_remove_mint_url.sql", include_str!(r#"./migrations/sqlite/20250129200912_remove_mint_url.sql"#)), - ("sqlite/20250129230326_add_config_table.sql", include_str!(r#"./migrations/sqlite/20250129230326_add_config_table.sql"#)), - ("sqlite/20250307213652_keyset_id_as_foreign_key.sql", include_str!(r#"./migrations/sqlite/20250307213652_keyset_id_as_foreign_key.sql"#)), - ("sqlite/20250406091754_mint_time_of_quotes.sql", include_str!(r#"./migrations/sqlite/20250406091754_mint_time_of_quotes.sql"#)), - ("sqlite/20250406093755_mint_created_time_signature.sql", include_str!(r#"./migrations/sqlite/20250406093755_mint_created_time_signature.sql"#)), - ("sqlite/20250415093121_drop_keystore_foreign.sql", include_str!(r#"./migrations/sqlite/20250415093121_drop_keystore_foreign.sql"#)), - ("sqlite/20250626120251_rename_blind_message_y_to_b.sql", include_str!(r#"./migrations/sqlite/20250626120251_rename_blind_message_y_to_b.sql"#)), - ("sqlite/20250706101057_bolt12.sql", include_str!(r#"./migrations/sqlite/20250706101057_bolt12.sql"#)), +pub static MIGRATIONS: &[(&str, &str, &str)] = &[ + ("sqlite", "1_fix_sqlx_migration.sql", include_str!(r#"./migrations/sqlite/1_fix_sqlx_migration.sql"#)), + ("sqlite", "20240612124932_init.sql", include_str!(r#"./migrations/sqlite/20240612124932_init.sql"#)), + ("sqlite", "20240618195700_quote_state.sql", include_str!(r#"./migrations/sqlite/20240618195700_quote_state.sql"#)), + ("sqlite", "20240626092101_nut04_state.sql", include_str!(r#"./migrations/sqlite/20240626092101_nut04_state.sql"#)), + ("sqlite", "20240703122347_request_lookup_id.sql", include_str!(r#"./migrations/sqlite/20240703122347_request_lookup_id.sql"#)), + ("sqlite", "20240710145043_input_fee.sql", include_str!(r#"./migrations/sqlite/20240710145043_input_fee.sql"#)), + ("sqlite", "20240711183109_derivation_path_index.sql", include_str!(r#"./migrations/sqlite/20240711183109_derivation_path_index.sql"#)), + ("sqlite", "20240718203721_allow_unspent.sql", include_str!(r#"./migrations/sqlite/20240718203721_allow_unspent.sql"#)), + ("sqlite", "20240811031111_update_mint_url.sql", include_str!(r#"./migrations/sqlite/20240811031111_update_mint_url.sql"#)), + ("sqlite", "20240919103407_proofs_quote_id.sql", include_str!(r#"./migrations/sqlite/20240919103407_proofs_quote_id.sql"#)), + ("sqlite", "20240923153640_melt_requests.sql", include_str!(r#"./migrations/sqlite/20240923153640_melt_requests.sql"#)), + ("sqlite", "20240930101140_dleq_for_sigs.sql", include_str!(r#"./migrations/sqlite/20240930101140_dleq_for_sigs.sql"#)), + ("sqlite", "20241108093102_mint_mint_quote_pubkey.sql", include_str!(r#"./migrations/sqlite/20241108093102_mint_mint_quote_pubkey.sql"#)), + ("sqlite", "20250103201327_amount_to_pay_msats.sql", include_str!(r#"./migrations/sqlite/20250103201327_amount_to_pay_msats.sql"#)), + ("sqlite", "20250129200912_remove_mint_url.sql", include_str!(r#"./migrations/sqlite/20250129200912_remove_mint_url.sql"#)), + ("sqlite", "20250129230326_add_config_table.sql", include_str!(r#"./migrations/sqlite/20250129230326_add_config_table.sql"#)), + ("sqlite", "20250307213652_keyset_id_as_foreign_key.sql", include_str!(r#"./migrations/sqlite/20250307213652_keyset_id_as_foreign_key.sql"#)), + ("sqlite", "20250406091754_mint_time_of_quotes.sql", include_str!(r#"./migrations/sqlite/20250406091754_mint_time_of_quotes.sql"#)), + ("sqlite", "20250406093755_mint_created_time_signature.sql", include_str!(r#"./migrations/sqlite/20250406093755_mint_created_time_signature.sql"#)), + ("sqlite", "20250415093121_drop_keystore_foreign.sql", include_str!(r#"./migrations/sqlite/20250415093121_drop_keystore_foreign.sql"#)), + ("sqlite", "20250626120251_rename_blind_message_y_to_b.sql", include_str!(r#"./migrations/sqlite/20250626120251_rename_blind_message_y_to_b.sql"#)), + ("sqlite", "20250706101057_bolt12.sql", include_str!(r#"./migrations/sqlite/20250706101057_bolt12.sql"#)), ]; diff --git a/crates/cdk-sql-common/src/wallet/migrations.rs b/crates/cdk-sql-common/src/wallet/migrations.rs index 4b6d3cf72..f1011b5e3 100644 --- a/crates/cdk-sql-common/src/wallet/migrations.rs +++ b/crates/cdk-sql-common/src/wallet/migrations.rs @@ -1,21 +1,21 @@ /// @generated /// Auto-generated by build.rs -pub static MIGRATIONS: &[(&str, &str)] = &[ - ("sqlite/20240612132920_init.sql", include_str!(r#"./migrations/sqlite/20240612132920_init.sql"#)), - ("sqlite/20240618200350_quote_state.sql", include_str!(r#"./migrations/sqlite/20240618200350_quote_state.sql"#)), - ("sqlite/20240626091921_nut04_state.sql", include_str!(r#"./migrations/sqlite/20240626091921_nut04_state.sql"#)), - ("sqlite/20240710144711_input_fee.sql", include_str!(r#"./migrations/sqlite/20240710144711_input_fee.sql"#)), - ("sqlite/20240810214105_mint_icon_url.sql", include_str!(r#"./migrations/sqlite/20240810214105_mint_icon_url.sql"#)), - ("sqlite/20240810233905_update_mint_url.sql", include_str!(r#"./migrations/sqlite/20240810233905_update_mint_url.sql"#)), - ("sqlite/20240902151515_icon_url.sql", include_str!(r#"./migrations/sqlite/20240902151515_icon_url.sql"#)), - ("sqlite/20240902210905_mint_time.sql", include_str!(r#"./migrations/sqlite/20240902210905_mint_time.sql"#)), - ("sqlite/20241011125207_mint_urls.sql", include_str!(r#"./migrations/sqlite/20241011125207_mint_urls.sql"#)), - ("sqlite/20241108092756_wallet_mint_quote_secretkey.sql", include_str!(r#"./migrations/sqlite/20241108092756_wallet_mint_quote_secretkey.sql"#)), - ("sqlite/20250214135017_mint_tos.sql", include_str!(r#"./migrations/sqlite/20250214135017_mint_tos.sql"#)), - ("sqlite/20250310111513_drop_nostr_last_checked.sql", include_str!(r#"./migrations/sqlite/20250310111513_drop_nostr_last_checked.sql"#)), - ("sqlite/20250314082116_allow_pending_spent.sql", include_str!(r#"./migrations/sqlite/20250314082116_allow_pending_spent.sql"#)), - ("sqlite/20250323152040_wallet_dleq_proofs.sql", include_str!(r#"./migrations/sqlite/20250323152040_wallet_dleq_proofs.sql"#)), - ("sqlite/20250401120000_add_transactions_table.sql", include_str!(r#"./migrations/sqlite/20250401120000_add_transactions_table.sql"#)), - ("sqlite/20250616144830_add_keyset_expiry.sql", include_str!(r#"./migrations/sqlite/20250616144830_add_keyset_expiry.sql"#)), - ("sqlite/20250707093445_bolt12.sql", include_str!(r#"./migrations/sqlite/20250707093445_bolt12.sql"#)), +pub static MIGRATIONS: &[(&str, &str, &str)] = &[ + ("sqlite", "20240612132920_init.sql", include_str!(r#"./migrations/sqlite/20240612132920_init.sql"#)), + ("sqlite", "20240618200350_quote_state.sql", include_str!(r#"./migrations/sqlite/20240618200350_quote_state.sql"#)), + ("sqlite", "20240626091921_nut04_state.sql", include_str!(r#"./migrations/sqlite/20240626091921_nut04_state.sql"#)), + ("sqlite", "20240710144711_input_fee.sql", include_str!(r#"./migrations/sqlite/20240710144711_input_fee.sql"#)), + ("sqlite", "20240810214105_mint_icon_url.sql", include_str!(r#"./migrations/sqlite/20240810214105_mint_icon_url.sql"#)), + ("sqlite", "20240810233905_update_mint_url.sql", include_str!(r#"./migrations/sqlite/20240810233905_update_mint_url.sql"#)), + ("sqlite", "20240902151515_icon_url.sql", include_str!(r#"./migrations/sqlite/20240902151515_icon_url.sql"#)), + ("sqlite", "20240902210905_mint_time.sql", include_str!(r#"./migrations/sqlite/20240902210905_mint_time.sql"#)), + ("sqlite", "20241011125207_mint_urls.sql", include_str!(r#"./migrations/sqlite/20241011125207_mint_urls.sql"#)), + ("sqlite", "20241108092756_wallet_mint_quote_secretkey.sql", include_str!(r#"./migrations/sqlite/20241108092756_wallet_mint_quote_secretkey.sql"#)), + ("sqlite", "20250214135017_mint_tos.sql", include_str!(r#"./migrations/sqlite/20250214135017_mint_tos.sql"#)), + ("sqlite", "20250310111513_drop_nostr_last_checked.sql", include_str!(r#"./migrations/sqlite/20250310111513_drop_nostr_last_checked.sql"#)), + ("sqlite", "20250314082116_allow_pending_spent.sql", include_str!(r#"./migrations/sqlite/20250314082116_allow_pending_spent.sql"#)), + ("sqlite", "20250323152040_wallet_dleq_proofs.sql", include_str!(r#"./migrations/sqlite/20250323152040_wallet_dleq_proofs.sql"#)), + ("sqlite", "20250401120000_add_transactions_table.sql", include_str!(r#"./migrations/sqlite/20250401120000_add_transactions_table.sql"#)), + ("sqlite", "20250616144830_add_keyset_expiry.sql", include_str!(r#"./migrations/sqlite/20250616144830_add_keyset_expiry.sql"#)), + ("sqlite", "20250707093445_bolt12.sql", include_str!(r#"./migrations/sqlite/20250707093445_bolt12.sql"#)), ]; From 0041c135f7872cb9dda7e68c1adfad8d013672c8 Mon Sep 17 00:00:00 2001 From: Cesar Rodas Date: Mon, 28 Jul 2025 22:34:27 -0300 Subject: [PATCH 043/321] Fix `get_mint_quote_by_request_lookup_id` Fixes #916 The two functions (read and transaction) got out of sync --- crates/cdk-sql-common/src/mint/mod.rs | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/crates/cdk-sql-common/src/mint/mod.rs b/crates/cdk-sql-common/src/mint/mod.rs index 0f362b6dc..6a9370370 100644 --- a/crates/cdk-sql-common/src/mint/mod.rs +++ b/crates/cdk-sql-common/src/mint/mod.rs @@ -1124,12 +1124,12 @@ where request_lookup_id_kind FROM mint_quote - WHERE request_lookup_id = :request_lookup_id"#, + WHERE request_lookup_id = :request_lookup_id + AND request_lookup_id_kind = :request_lookup_id_kind + "#, )? - .bind( - "request_lookup_id", - serde_json::to_string(request_lookup_id)?, - ) + .bind("request_lookup_id", request_lookup_id.to_string()) + .bind("request_lookup_id_kind", request_lookup_id.kind()) .fetch_one(&self.db) .await? .map(|row| sql_row_to_mint_quote(row, vec![], vec![])) From ed7b64b71a8377d612b3d78bd06babd61d19653e Mon Sep 17 00:00:00 2001 From: Cesar Rodas Date: Tue, 29 Jul 2025 20:28:09 -0300 Subject: [PATCH 044/321] Add missing migrations for wallet and auth db --- .../src/mint/auth/migrations.rs | 1 + .../sqlite/1_fix_sqlx_migration.sql | 20 +++++++++++++++++++ .../cdk-sql-common/src/wallet/migrations.rs | 1 + .../sqlite/1_fix_sqlx_migration.sql | 20 +++++++++++++++++++ 4 files changed, 42 insertions(+) create mode 100644 crates/cdk-sql-common/src/mint/auth/migrations/sqlite/1_fix_sqlx_migration.sql create mode 100644 crates/cdk-sql-common/src/wallet/migrations/sqlite/1_fix_sqlx_migration.sql diff --git a/crates/cdk-sql-common/src/mint/auth/migrations.rs b/crates/cdk-sql-common/src/mint/auth/migrations.rs index 06f5b0bb3..d0f90c897 100644 --- a/crates/cdk-sql-common/src/mint/auth/migrations.rs +++ b/crates/cdk-sql-common/src/mint/auth/migrations.rs @@ -1,5 +1,6 @@ /// @generated /// Auto-generated by build.rs pub static MIGRATIONS: &[(&str, &str, &str)] = &[ + ("sqlite", "1_fix_sqlx_migration.sql", include_str!(r#"./migrations/sqlite/1_fix_sqlx_migration.sql"#)), ("sqlite", "20250109143347_init.sql", include_str!(r#"./migrations/sqlite/20250109143347_init.sql"#)), ]; diff --git a/crates/cdk-sql-common/src/mint/auth/migrations/sqlite/1_fix_sqlx_migration.sql b/crates/cdk-sql-common/src/mint/auth/migrations/sqlite/1_fix_sqlx_migration.sql new file mode 100644 index 000000000..9f7a0d828 --- /dev/null +++ b/crates/cdk-sql-common/src/mint/auth/migrations/sqlite/1_fix_sqlx_migration.sql @@ -0,0 +1,20 @@ +-- Migrate `_sqlx_migrations` to our new migration system +CREATE TABLE IF NOT EXISTS _sqlx_migrations AS +SELECT + '' AS version, + '' AS description, + 0 AS execution_time +WHERE 0; + +INSERT INTO migrations +SELECT + version || '_' || REPLACE(description, ' ', '_') || '.sql', + execution_time +FROM _sqlx_migrations +WHERE EXISTS ( + SELECT 1 + FROM sqlite_master + WHERE type = 'table' AND name = '_sqlx_migrations' +); + +DROP TABLE _sqlx_migrations; diff --git a/crates/cdk-sql-common/src/wallet/migrations.rs b/crates/cdk-sql-common/src/wallet/migrations.rs index f1011b5e3..c5e901c01 100644 --- a/crates/cdk-sql-common/src/wallet/migrations.rs +++ b/crates/cdk-sql-common/src/wallet/migrations.rs @@ -1,6 +1,7 @@ /// @generated /// Auto-generated by build.rs pub static MIGRATIONS: &[(&str, &str, &str)] = &[ + ("sqlite", "1_fix_sqlx_migration.sql", include_str!(r#"./migrations/sqlite/1_fix_sqlx_migration.sql"#)), ("sqlite", "20240612132920_init.sql", include_str!(r#"./migrations/sqlite/20240612132920_init.sql"#)), ("sqlite", "20240618200350_quote_state.sql", include_str!(r#"./migrations/sqlite/20240618200350_quote_state.sql"#)), ("sqlite", "20240626091921_nut04_state.sql", include_str!(r#"./migrations/sqlite/20240626091921_nut04_state.sql"#)), diff --git a/crates/cdk-sql-common/src/wallet/migrations/sqlite/1_fix_sqlx_migration.sql b/crates/cdk-sql-common/src/wallet/migrations/sqlite/1_fix_sqlx_migration.sql new file mode 100644 index 000000000..9f7a0d828 --- /dev/null +++ b/crates/cdk-sql-common/src/wallet/migrations/sqlite/1_fix_sqlx_migration.sql @@ -0,0 +1,20 @@ +-- Migrate `_sqlx_migrations` to our new migration system +CREATE TABLE IF NOT EXISTS _sqlx_migrations AS +SELECT + '' AS version, + '' AS description, + 0 AS execution_time +WHERE 0; + +INSERT INTO migrations +SELECT + version || '_' || REPLACE(description, ' ', '_') || '.sql', + execution_time +FROM _sqlx_migrations +WHERE EXISTS ( + SELECT 1 + FROM sqlite_master + WHERE type = 'table' AND name = '_sqlx_migrations' +); + +DROP TABLE _sqlx_migrations; From 714022fe140f3ed58bac9396ca6b7627dbbc59f9 Mon Sep 17 00:00:00 2001 From: vnprc Date: Tue, 29 Jul 2025 21:41:45 -0400 Subject: [PATCH 045/321] test: add PaymentMethod parsing and db read/write tests --- crates/cashu/src/nuts/nut00/mod.rs | 53 +++++++++++++++++++++++++++ crates/cdk-sqlite/src/wallet/mod.rs | 55 +++++++++++++++++++++++++++++ 2 files changed, 108 insertions(+) diff --git a/crates/cashu/src/nuts/nut00/mod.rs b/crates/cashu/src/nuts/nut00/mod.rs index cbcbf0617..485829347 100644 --- a/crates/cashu/src/nuts/nut00/mod.rs +++ b/crates/cashu/src/nuts/nut00/mod.rs @@ -985,4 +985,57 @@ mod tests { let deserialized: CurrencyUnit = serde_json::from_str(&serialized).unwrap(); assert_eq!(unit, deserialized) } + + #[test] + fn test_payment_method_parsing() { + // Test standard variants + assert_eq!( + PaymentMethod::from_str("bolt11").unwrap(), + PaymentMethod::Bolt11 + ); + assert_eq!( + PaymentMethod::from_str("BOLT11").unwrap(), + PaymentMethod::Bolt11 + ); + assert_eq!( + PaymentMethod::from_str("Bolt11").unwrap(), + PaymentMethod::Bolt11 + ); + + assert_eq!( + PaymentMethod::from_str("bolt12").unwrap(), + PaymentMethod::Bolt12 + ); + assert_eq!( + PaymentMethod::from_str("BOLT12").unwrap(), + PaymentMethod::Bolt12 + ); + assert_eq!( + PaymentMethod::from_str("Bolt12").unwrap(), + PaymentMethod::Bolt12 + ); + + // Test custom variants + assert_eq!( + PaymentMethod::from_str("custom").unwrap(), + PaymentMethod::Custom("custom".to_string()) + ); + assert_eq!( + PaymentMethod::from_str("CUSTOM").unwrap(), + PaymentMethod::Custom("custom".to_string()) + ); + + // Test serialization/deserialization consistency + let methods = vec![ + PaymentMethod::Bolt11, + PaymentMethod::Bolt12, + PaymentMethod::Custom("test".to_string()), + ]; + + for method in methods { + let serialized = serde_json::to_string(&method).unwrap(); + let deserialized: PaymentMethod = serde_json::from_str(&serialized).unwrap(); + assert_eq!(method, deserialized); + } + } } diff --git a/crates/cdk-sqlite/src/wallet/mod.rs b/crates/cdk-sqlite/src/wallet/mod.rs index 28252a9e6..5166baebc 100644 --- a/crates/cdk-sqlite/src/wallet/mod.rs +++ b/crates/cdk-sqlite/src/wallet/mod.rs @@ -306,4 +306,59 @@ mod tests { assert_eq!(retrieved_dleq.s.to_string(), s.to_string()); assert_eq!(retrieved_dleq.r.to_string(), r.to_string()); } + + #[tokio::test] + async fn test_mint_quote_payment_method_read_and_write() { + use cdk_common::mint_url::MintUrl; + use cdk_common::nuts::{CurrencyUnit, MintQuoteState, PaymentMethod}; + use cdk_common::wallet::MintQuote; + use cdk_common::Amount; + + // Create a temporary database + let path = std::env::temp_dir().to_path_buf().join(format!( + "cdk-test-migration-{}.sqlite", + uuid::Uuid::new_v4() + )); + + #[cfg(feature = "sqlcipher")] + let db = WalletSqliteDatabase::new((path, "password".to_string())) + .await + .unwrap(); + + #[cfg(not(feature = "sqlcipher"))] + let db = WalletSqliteDatabase::new(path).await.unwrap(); + + // Test PaymentMethod variants + let mint_url = MintUrl::from_str("https://example.com").unwrap(); + let payment_methods = vec![ + PaymentMethod::Bolt11, + PaymentMethod::Bolt12, + PaymentMethod::Custom("custom".to_string()), + ]; + + for (i, payment_method) in payment_methods.iter().enumerate() { + let quote = MintQuote { + id: format!("test_quote_{}", i), + mint_url: mint_url.clone(), + amount: Some(Amount::from(100)), + unit: CurrencyUnit::Sat, + request: "test_request".to_string(), + state: MintQuoteState::Unpaid, + expiry: 1000000000, + secret_key: None, + payment_method: payment_method.clone(), + amount_issued: Amount::from(0), + amount_paid: Amount::from(0), + }; + + // Store the quote + db.add_mint_quote(quote.clone()).await.unwrap(); + + // Retrieve and verify + let retrieved = db.get_mint_quote("e.id).await.unwrap().unwrap(); + assert_eq!(retrieved.payment_method, *payment_method); + assert_eq!(retrieved.amount_issued, Amount::from(0)); + assert_eq!(retrieved.amount_paid, Amount::from(0)); + } + } } From 8e0c44248be85400a382f8a2f151ab23b7202628 Mon Sep 17 00:00:00 2001 From: C Date: Tue, 29 Jul 2025 22:45:30 -0300 Subject: [PATCH 046/321] Add NUT-19 support in the wallet (#912) * Add NUT-19 support in the wallet --- crates/cashu/src/nuts/nut19.rs | 4 +- .../src/wallet/mint_connector/http_client.rs | 131 ++++++++++++++++-- 2 files changed, 121 insertions(+), 14 deletions(-) diff --git a/crates/cashu/src/nuts/nut19.rs b/crates/cashu/src/nuts/nut19.rs index bef6ded1d..7f34c41cb 100644 --- a/crates/cashu/src/nuts/nut19.rs +++ b/crates/cashu/src/nuts/nut19.rs @@ -32,7 +32,7 @@ impl CachedEndpoint { } /// HTTP method -#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)] +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)] #[serde(rename_all = "UPPERCASE")] #[cfg_attr(feature = "swagger", derive(utoipa::ToSchema))] pub enum Method { @@ -43,7 +43,7 @@ pub enum Method { } /// Route path -#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)] +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)] #[cfg_attr(feature = "swagger", derive(utoipa::ToSchema))] pub enum Path { /// Bolt11 Mint diff --git a/crates/cdk/src/wallet/mint_connector/http_client.rs b/crates/cdk/src/wallet/mint_connector/http_client.rs index 96720f5a1..25b0c8916 100644 --- a/crates/cdk/src/wallet/mint_connector/http_client.rs +++ b/crates/cdk/src/wallet/mint_connector/http_client.rs @@ -1,8 +1,9 @@ -#[cfg(feature = "auth")] -use std::sync::Arc; +use std::collections::HashSet; +use std::sync::{Arc, RwLock as StdRwLock}; +use std::time::{Duration, Instant}; use async_trait::async_trait; -use cdk_common::{MeltQuoteBolt12Request, MintQuoteBolt12Request, MintQuoteBolt12Response}; +use cdk_common::{nut19, MeltQuoteBolt12Request, MintQuoteBolt12Request, MintQuoteBolt12Response}; #[cfg(feature = "auth")] use cdk_common::{Method, ProtectedEndpoint, RoutePath}; use reqwest::{Client, IntoUrl}; @@ -109,11 +110,14 @@ impl HttpClientCore { } } +type Cache = (u64, HashSet<(nut19::Method, nut19::Path)>); + /// Http Client #[derive(Debug, Clone)] pub struct HttpClient { core: HttpClientCore, mint_url: MintUrl, + cache_support: Arc>, #[cfg(feature = "auth")] auth_wallet: Arc>>, } @@ -126,6 +130,7 @@ impl HttpClient { core: HttpClientCore::new(), mint_url, auth_wallet: Arc::new(RwLock::new(auth_wallet)), + cache_support: Default::default(), } } @@ -134,6 +139,7 @@ impl HttpClient { pub fn new(mint_url: MintUrl) -> Self { Self { core: HttpClientCore::new(), + cache_support: Default::default(), mint_url, } } @@ -190,8 +196,72 @@ impl HttpClient { mint_url, #[cfg(feature = "auth")] auth_wallet: Arc::new(RwLock::new(None)), + cache_support: Default::default(), }) } + + /// Generic implementation of a retriable http request + /// + /// The retry only happens if the mint supports replay through the Caching of NUT-19. + #[inline(always)] + async fn retriable_http_request( + &self, + method: nut19::Method, + path: nut19::Path, + auth_token: Option, + payload: &P, + ) -> Result + where + P: Serialize + ?Sized, + R: DeserializeOwned, + { + let started = Instant::now(); + + let retriable_window = self + .cache_support + .read() + .map(|cache_support| { + cache_support + .1 + .get(&(method, path)) + .map(|_| cache_support.0) + }) + .unwrap_or_default() + .map(Duration::from_secs) + .unwrap_or_default(); + + loop { + let url = self.mint_url.join_paths(&match path { + nut19::Path::MintBolt11 => vec!["v1", "mint", "bolt11"], + nut19::Path::MeltBolt11 => vec!["v1", "melt", "bolt11"], + nut19::Path::MintBolt12 => vec!["v1", "mint", "bolt12"], + nut19::Path::MeltBolt12 => vec!["v1", "melt", "bolt12"], + nut19::Path::Swap => vec!["v1", "swap"], + })?; + + let result = match method { + nut19::Method::Get => self.core.http_get(url, auth_token.clone()).await, + nut19::Method::Post => self.core.http_post(url, auth_token.clone(), payload).await, + }; + + if result.is_ok() { + return result; + } + + match result.as_ref() { + Err(Error::Database(_) | Error::HttpError(_) | Error::Custom(_)) => { + // retry request, if possible + tracing::error!("Failed http_request {:?}", result.as_ref().err()); + + if retriable_window < started.elapsed() { + return result; + } + } + Err(_) => return result, + _ => unreachable!(), + }; + } + } } #[cfg_attr(target_arch = "wasm32", async_trait(?Send))] @@ -272,7 +342,6 @@ impl MintConnector for HttpClient { /// Mint Tokens [NUT-04] #[instrument(skip(self, request), fields(mint_url = %self.mint_url))] async fn post_mint(&self, request: MintRequest) -> Result { - let url = self.mint_url.join_paths(&["v1", "mint", "bolt11"])?; #[cfg(feature = "auth")] let auth_token = self .get_auth_token(Method::Post, RoutePath::MintBolt11) @@ -280,7 +349,13 @@ impl MintConnector for HttpClient { #[cfg(not(feature = "auth"))] let auth_token = None; - self.core.http_post(url, auth_token, &request).await + self.retriable_http_request( + nut19::Method::Post, + nut19::Path::MintBolt11, + auth_token, + &request, + ) + .await } /// Melt Quote [NUT-05] @@ -329,7 +404,6 @@ impl MintConnector for HttpClient { &self, request: MeltRequest, ) -> Result, Error> { - let url = self.mint_url.join_paths(&["v1", "melt", "bolt11"])?; #[cfg(feature = "auth")] let auth_token = self .get_auth_token(Method::Post, RoutePath::MeltBolt11) @@ -337,25 +411,53 @@ impl MintConnector for HttpClient { #[cfg(not(feature = "auth"))] let auth_token = None; - self.core.http_post(url, auth_token, &request).await + + self.retriable_http_request( + nut19::Method::Post, + nut19::Path::MeltBolt11, + auth_token, + &request, + ) + .await } /// Swap Token [NUT-03] #[instrument(skip(self, swap_request), fields(mint_url = %self.mint_url))] async fn post_swap(&self, swap_request: SwapRequest) -> Result { - let url = self.mint_url.join_paths(&["v1", "swap"])?; #[cfg(feature = "auth")] let auth_token = self.get_auth_token(Method::Post, RoutePath::Swap).await?; #[cfg(not(feature = "auth"))] let auth_token = None; - self.core.http_post(url, auth_token, &swap_request).await + + self.retriable_http_request( + nut19::Method::Post, + nut19::Path::Swap, + auth_token, + &swap_request, + ) + .await } /// Helper to get mint info async fn get_mint_info(&self) -> Result { let url = self.mint_url.join_paths(&["v1", "info"])?; - self.core.http_get(url, None).await + let info: MintInfo = self.core.http_get(url, None).await?; + + if let Ok(mut cache_support) = self.cache_support.write() { + *cache_support = ( + info.nuts.nut19.ttl.unwrap_or(300), + info.nuts + .nut19 + .cached_endpoints + .clone() + .into_iter() + .map(|cached_endpoint| (cached_endpoint.method, cached_endpoint.path)) + .collect(), + ); + } + + Ok(info) } #[cfg(feature = "auth")] @@ -485,7 +587,6 @@ impl MintConnector for HttpClient { &self, request: MeltRequest, ) -> Result, Error> { - let url = self.mint_url.join_paths(&["v1", "melt", "bolt12"])?; #[cfg(feature = "auth")] let auth_token = self .get_auth_token(Method::Post, RoutePath::MeltBolt12) @@ -493,7 +594,13 @@ impl MintConnector for HttpClient { #[cfg(not(feature = "auth"))] let auth_token = None; - self.core.http_post(url, auth_token, &request).await + self.retriable_http_request( + nut19::Method::Post, + nut19::Path::MeltBolt12, + auth_token, + &request, + ) + .await } } From c6f6eea1aac2b666e17b1642508c008d0fd404c3 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Tue, 29 Jul 2025 21:59:29 -0400 Subject: [PATCH 047/321] chore: update change log --- CHANGELOG.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index f4c11e577..4f1618b3e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,9 @@ - cashu: `KeySetInfos` type alias and `KeySetInfosMethods` trait for filtering keysets ([thesimplekid]). - cdk: Mint lifecycle management with `start()` and `stop()` methods for graceful background service control ([thesimplekid]). - cdk: Background task management for invoice payment monitoring with proper shutdown handling ([thesimplekid]). +- cashu: NUT-19 support in the wallet ([crodas]). +- cdk: SIG_ALL support for swap and melt operations ([thesimplekid]). +- cdk-sql-common: Add cache to SQL statements for better performance ([crodas]). ### Changed - cdk: Refactored wallet keyset management methods for better clarity and separation of concerns ([thesimplekid]). @@ -22,9 +25,17 @@ - cdk: Refactored invoice payment monitoring to use centralized lifecycle management instead of manual task spawning ([thesimplekid]). - cdk-mintd: Updated to use new mint lifecycle methods for improved service management ([thesimplekid]). - cdk-integration-tests: Updated test utilities to use new mint lifecycle management ([thesimplekid]). +- cdk-sqlite: Introduce `cdk-sql-common` crate for shared SQL storage codebase ([crodas]). +- cdk-sqlite: Rename `still_active` to `stale` for better clarity ([crodas]). ### Fixed - cashu: Fixed CurrencyUnit custom units preserving original case instead of being converted to uppercase ([thesimplekid]). +- cdk-sqlite: Fix `get_mint_quote_by_request_lookup_id` function synchronization ([crodas]). +- cdk-common: Fix TransactionId::from_hex to check bytes length before copy to avoid panic ([codingpeanut157]). +- cdk: Include change in melt quote state updates ([thesimplekid]). + +### Migration +- cdk-sql-common: Improve migrations with namespaced and global migrations support ([crodas]). ## [0.11.0](https://github.com/cashubtc/cdk/releases/tag/v0.11.0) @@ -449,3 +460,4 @@ Additionally, this release introduces a Mint binary cdk-mintd that uses the cdk- [Darrell]: https://github.com/Darrellbor [asmo]: https://github.com/asmogo [gudnuf]: https://github.com/gudnuf +[codingpeanut157]: https://github.com/codingpeanut157 From 9a784fbacd0afb4f7e6c227853d17373343d4364 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Wed, 30 Jul 2025 09:21:01 -0400 Subject: [PATCH 048/321] feat(cdk): enable NUT-20 support in mint builder configuration --- crates/cdk/src/mint/builder.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/crates/cdk/src/mint/builder.rs b/crates/cdk/src/mint/builder.rs index f028a5874..b0cc19033 100644 --- a/crates/cdk/src/mint/builder.rs +++ b/crates/cdk/src/mint/builder.rs @@ -52,7 +52,8 @@ impl MintBuilder { .nut09(true) .nut10(true) .nut11(true) - .nut12(true), + .nut12(true) + .nut20(true), ..Default::default() }; From b5fc4a17c3906f9b076940ae50a5e6569ac83f04 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Wed, 30 Jul 2025 10:07:22 -0400 Subject: [PATCH 049/321] fix: include axum in swagger --- crates/cdk-axum/src/lib.rs | 130 ++++++++++++++++++++++++++++------- crates/cdk-mintd/src/main.rs | 2 +- 2 files changed, 108 insertions(+), 24 deletions(-) diff --git a/crates/cdk-axum/src/lib.rs b/crates/cdk-axum/src/lib.rs index 9863c98d2..182f4f785 100644 --- a/crates/cdk-axum/src/lib.rs +++ b/crates/cdk-axum/src/lib.rs @@ -47,6 +47,8 @@ mod swagger_imports { MeltQuoteBolt11Request, MeltQuoteBolt11Response, MintQuoteBolt11Request, MintQuoteBolt11Response, }; + #[cfg(feature = "auth")] + pub use cdk::nuts::MintAuthRequest; pub use cdk::nuts::{nut04, nut05, nut15, MeltQuoteState, MintQuoteState}; } @@ -66,9 +68,103 @@ pub struct MintState { } #[cfg(feature = "swagger")] -#[derive(utoipa::OpenApi)] -#[openapi( - components(schemas( +macro_rules! define_api_doc { + ( + schemas: [$($schema:ty),* $(,)?] + $(, auth_schemas: [$($auth_schema:ty),* $(,)?])? + $(, paths: [$($path:path),* $(,)?])? + $(, auth_paths: [$($auth_path:path),* $(,)?])? + ) => { + #[derive(utoipa::OpenApi)] + #[openapi( + components(schemas( + $($schema,)* + $($($auth_schema,)*)? + )), + info(description = "Cashu CDK mint APIs", title = "cdk-mintd"), + paths( + get_keys, + get_keyset_pubkeys, + get_keysets, + get_mint_info, + post_mint_bolt11_quote, + get_check_mint_bolt11_quote, + post_mint_bolt11, + post_melt_bolt11_quote, + get_check_melt_bolt11_quote, + post_melt_bolt11, + post_swap, + post_check, + post_restore + $(,$($path,)*)? + $(,$($auth_path,)*)? + ) + )] + /// Swagger api docs + pub struct ApiDoc; + }; +} + +// Configuration without auth feature +#[cfg(all(feature = "swagger", not(feature = "auth")))] +define_api_doc! { + schemas: [ + Amount, + BlindedMessage, + BlindSignature, + BlindSignatureDleq, + CheckStateRequest, + CheckStateResponse, + ContactInfo, + CurrencyUnit, + ErrorCode, + ErrorResponse, + HTLCWitness, + Keys, + KeysResponse, + KeysetResponse, + KeySet, + KeySetInfo, + MeltRequest, + MeltQuoteBolt11Request, + MeltQuoteBolt11Response, + MeltQuoteState, + MeltMethodSettings, + MintRequest, + MintResponse, + MintInfo, + MintQuoteBolt11Request, + MintQuoteBolt11Response, + MintQuoteState, + MintMethodSettings, + MintVersion, + Mpp, + MppMethodSettings, + Nuts, + P2PKWitness, + PaymentMethod, + Proof, + ProofDleq, + ProofState, + PublicKey, + RestoreRequest, + RestoreResponse, + SecretKey, + State, + SupportedSettings, + SwapRequest, + SwapResponse, + Witness, + nut04::Settings, + nut05::Settings, + nut15::Settings + ] +} + +// Configuration with auth feature +#[cfg(all(feature = "swagger", feature = "auth"))] +define_api_doc! { + schemas: [ Amount, BlindedMessage, BlindSignature, @@ -118,26 +214,14 @@ pub struct MintState { nut04::Settings, nut05::Settings, nut15::Settings - )), - info(description = "Cashu CDK mint APIs", title = "cdk-mintd",), - paths( - get_keys, - get_keyset_pubkeys, - get_keysets, - get_mint_info, - post_mint_bolt11_quote, - get_check_mint_bolt11_quote, - post_mint_bolt11, - post_melt_bolt11_quote, - get_check_melt_bolt11_quote, - post_melt_bolt11, - post_swap, - post_check, - post_restore - ) -)] -/// OpenAPI spec for the mint's v1 APIs -pub struct ApiDocV1; + ], + auth_schemas: [MintAuthRequest], + auth_paths: [ + crate::auth::get_auth_keysets, + crate::auth::get_blind_auth_keys, + crate::auth::post_mint_auth + ] +} /// Create mint [`Router`] with required endpoints for cashu mint with the default cache pub async fn create_mint_router(mint: Arc, include_bolt12: bool) -> Result { diff --git a/crates/cdk-mintd/src/main.rs b/crates/cdk-mintd/src/main.rs index 7c270043f..ab332c6ba 100644 --- a/crates/cdk-mintd/src/main.rs +++ b/crates/cdk-mintd/src/main.rs @@ -747,7 +747,7 @@ async fn start_services( if settings.info.enable_swagger_ui.unwrap_or(false) { mint_service = mint_service.merge( utoipa_swagger_ui::SwaggerUi::new("/swagger-ui") - .url("/api-docs/openapi.json", cdk_axum::ApiDocV1::openapi()), + .url("/api-docs/openapi.json", cdk_axum::ApiDoc::openapi()), ); } } From 6ebcbba0c4961a1a11d67ab1be031b712ca3ec1e Mon Sep 17 00:00:00 2001 From: David Caseria Date: Wed, 30 Jul 2025 23:37:41 -0400 Subject: [PATCH 050/321] refactor: update send functionality across wallet components (#925) * refactor: update send functionality across wallet components --------- Co-authored-by: thesimplekid --- .../cdk-cli/src/sub_commands/pay_request.rs | 2 +- crates/cdk-cli/src/sub_commands/send.rs | 2 +- .../tests/integration_tests_pure.rs | 7 +- .../cdk-integration-tests/tests/test_fees.rs | 2 +- crates/cdk/README.md | 2 +- crates/cdk/examples/auth_wallet.rs | 2 +- crates/cdk/examples/mint-token.rs | 2 +- crates/cdk/examples/p2pk.rs | 2 +- crates/cdk/examples/wallet.rs | 2 +- crates/cdk/src/wallet/multi_mint_wallet.rs | 18 +- crates/cdk/src/wallet/send.rs | 176 +++++++++--------- 11 files changed, 101 insertions(+), 116 deletions(-) diff --git a/crates/cdk-cli/src/sub_commands/pay_request.rs b/crates/cdk-cli/src/sub_commands/pay_request.rs index dc4bddec4..6ceeb258e 100644 --- a/crates/cdk-cli/src/sub_commands/pay_request.rs +++ b/crates/cdk-cli/src/sub_commands/pay_request.rs @@ -92,7 +92,7 @@ pub async fn pay_request( ) .await?; - let token = matching_wallet.send(prepared_send, None).await?; + let token = prepared_send.confirm(None).await?; // We need the keysets information to properly convert from token proof to proof let keysets_info = match matching_wallet diff --git a/crates/cdk-cli/src/sub_commands/send.rs b/crates/cdk-cli/src/sub_commands/send.rs index 5d1775476..e1b37bfff 100644 --- a/crates/cdk-cli/src/sub_commands/send.rs +++ b/crates/cdk-cli/src/sub_commands/send.rs @@ -221,7 +221,7 @@ pub async fn send( }, ) .await?; - let token = wallet.send(prepared_send, None).await?; + let token = prepared_send.confirm(None).await?; match sub_command_args.v3 { true => { diff --git a/crates/cdk-integration-tests/tests/integration_tests_pure.rs b/crates/cdk-integration-tests/tests/integration_tests_pure.rs index d49bd2a8b..7ed954b88 100644 --- a/crates/cdk-integration-tests/tests/integration_tests_pure.rs +++ b/crates/cdk-integration-tests/tests/integration_tests_pure.rs @@ -70,11 +70,8 @@ async fn test_swap_to_send() { .expect("Failed to get ys") ) ); - let token = wallet_alice - .send( - prepared_send, - Some(SendMemo::for_token("test_swapt_to_send")), - ) + let token = prepared_send + .confirm(Some(SendMemo::for_token("test_swapt_to_send"))) .await .expect("Failed to send token"); let keysets_info = wallet_alice.get_mint_keysets().await.unwrap(); diff --git a/crates/cdk-integration-tests/tests/test_fees.rs b/crates/cdk-integration-tests/tests/test_fees.rs index 0893ab41c..1433030a5 100644 --- a/crates/cdk-integration-tests/tests/test_fees.rs +++ b/crates/cdk-integration-tests/tests/test_fees.rs @@ -64,7 +64,7 @@ async fn test_swap() { assert_eq!(fee, 1.into()); - let send = wallet.send(send, None).await.unwrap(); + let send = send.confirm(None).await.unwrap(); let rec_amount = wallet .receive(&send.to_string(), ReceiveOptions::default()) diff --git a/crates/cdk/README.md b/crates/cdk/README.md index 670a90479..5ed3d02eb 100644 --- a/crates/cdk/README.md +++ b/crates/cdk/README.md @@ -101,7 +101,7 @@ async fn main() { // Send the token let prepared_send = wallet.prepare_send(Amount::ONE, SendOptions::default()).await.unwrap(); - let token = wallet.send(prepared_send, None).await.unwrap(); + let token = prepared_send.confirm(None).await.unwrap(); println!("{}", token); } diff --git a/crates/cdk/examples/auth_wallet.rs b/crates/cdk/examples/auth_wallet.rs index 4eff20ac6..6d4c55335 100644 --- a/crates/cdk/examples/auth_wallet.rs +++ b/crates/cdk/examples/auth_wallet.rs @@ -88,7 +88,7 @@ async fn main() -> Result<(), Error> { let prepared_send = wallet .prepare_send(10.into(), SendOptions::default()) .await?; - let token = wallet.send(prepared_send, None).await?; + let token = prepared_send.confirm(None).await?; println!("Created token: {}", token); diff --git a/crates/cdk/examples/mint-token.rs b/crates/cdk/examples/mint-token.rs index 0c9bf466e..9a5dd7aee 100644 --- a/crates/cdk/examples/mint-token.rs +++ b/crates/cdk/examples/mint-token.rs @@ -62,7 +62,7 @@ async fn main() -> Result<(), Error> { // Send a token with the specified amount let prepared_send = wallet.prepare_send(amount, SendOptions::default()).await?; - let token = wallet.send(prepared_send, None).await?; + let token = prepared_send.confirm(None).await?; println!("Token:"); println!("{}", token); diff --git a/crates/cdk/examples/p2pk.rs b/crates/cdk/examples/p2pk.rs index 2fb741e20..64cce6acf 100644 --- a/crates/cdk/examples/p2pk.rs +++ b/crates/cdk/examples/p2pk.rs @@ -87,7 +87,7 @@ async fn main() -> Result<(), Error> { ) .await?; println!("Fee: {}", prepared_send.fee()); - let token = wallet.send(prepared_send, None).await?; + let token = prepared_send.confirm(None).await?; println!("Created token locked to pubkey: {}", secret.public_key()); println!("{}", token); diff --git a/crates/cdk/examples/wallet.rs b/crates/cdk/examples/wallet.rs index 3bffe8efb..890cb4d61 100644 --- a/crates/cdk/examples/wallet.rs +++ b/crates/cdk/examples/wallet.rs @@ -59,7 +59,7 @@ async fn main() -> Result<(), Box> { // Send the token let prepared_send = wallet.prepare_send(amount, SendOptions::default()).await?; - let token = wallet.send(prepared_send, None).await?; + let token = prepared_send.confirm(None).await?; println!("{}", token); diff --git a/crates/cdk/src/wallet/multi_mint_wallet.rs b/crates/cdk/src/wallet/multi_mint_wallet.rs index cfac4e1b7..310cc2144 100644 --- a/crates/cdk/src/wallet/multi_mint_wallet.rs +++ b/crates/cdk/src/wallet/multi_mint_wallet.rs @@ -15,7 +15,7 @@ use tokio::sync::RwLock; use tracing::instrument; use super::receive::ReceiveOptions; -use super::send::{PreparedSend, SendMemo, SendOptions}; +use super::send::{PreparedSend, SendOptions}; use super::Error; use crate::amount::SplitTarget; use crate::mint_url::MintUrl; @@ -177,22 +177,6 @@ impl MultiMintWallet { wallet.prepare_send(amount, opts).await } - /// Create cashu token - #[instrument(skip(self))] - pub async fn send( - &self, - wallet_key: &WalletKey, - send: PreparedSend, - memo: Option, - ) -> Result { - let wallets = self.wallets.read().await; - let wallet = wallets - .get(wallet_key) - .ok_or(Error::UnknownWallet(wallet_key.clone()))?; - - wallet.send(send, memo).await - } - /// Mint quote for wallet #[instrument(skip(self))] pub async fn mint_quote( diff --git a/crates/cdk/src/wallet/send.rs b/crates/cdk/src/wallet/send.rs index 9d6b47648..190749ba8 100644 --- a/crates/cdk/src/wallet/send.rs +++ b/crates/cdk/src/wallet/send.rs @@ -21,7 +21,7 @@ impl Wallet { /// ```no_compile /// let send = wallet.prepare_send(Amount::from(10), SendOptions::default()).await?; /// assert!(send.fee() <= Amount::from(1)); - /// let token = wallet.send(send, None).await?; + /// let token = send.confirm(None).await?; /// ``` #[instrument(skip(self), err)] pub async fn prepare_send( @@ -188,6 +188,7 @@ impl Wallet { // Return prepared send Ok(PreparedSend { + wallet: self.clone(), amount, options: opts, proofs_to_swap, @@ -196,39 +197,92 @@ impl Wallet { send_fee, }) } +} - /// Finalize A Send Transaction - /// - /// This function finalizes a send transaction by constructing a token the [`PreparedSend`]. - /// See [`Wallet::prepare_send`] for more information. +/// Prepared send +pub struct PreparedSend { + wallet: Wallet, + amount: Amount, + options: SendOptions, + proofs_to_swap: Proofs, + swap_fee: Amount, + proofs_to_send: Proofs, + send_fee: Amount, +} + +impl PreparedSend { + /// Amount + pub fn amount(&self) -> Amount { + self.amount + } + + /// Send options + pub fn options(&self) -> &SendOptions { + &self.options + } + + /// Proofs to swap (i.e., proofs that need to be swapped before constructing the token) + pub fn proofs_to_swap(&self) -> &Proofs { + &self.proofs_to_swap + } + + /// Swap fee + pub fn swap_fee(&self) -> Amount { + self.swap_fee + } + + /// Proofs to send (i.e., proofs that will be included in the token) + pub fn proofs_to_send(&self) -> &Proofs { + &self.proofs_to_send + } + + /// Send fee + pub fn send_fee(&self) -> Amount { + self.send_fee + } + + /// All proofs + pub fn proofs(&self) -> Proofs { + let mut proofs = self.proofs_to_swap.clone(); + proofs.extend(self.proofs_to_send.clone()); + proofs + } + + /// Total fee + pub fn fee(&self) -> Amount { + self.swap_fee + self.send_fee + } + + /// Confirm the prepared send and create a token #[instrument(skip(self), err)] - pub async fn send(&self, send: PreparedSend, memo: Option) -> Result { - tracing::info!("Sending prepared send"); - let total_send_fee = send.fee(); - let mut proofs_to_send = send.proofs_to_send; + pub async fn confirm(self, memo: Option) -> Result { + tracing::info!("Confirming prepared send"); + let total_send_fee = self.fee(); + let mut proofs_to_send = self.proofs_to_send; // Get active keyset ID - let active_keyset_id = self.fetch_active_keyset().await?.id; + let active_keyset_id = self.wallet.fetch_active_keyset().await?.id; tracing::debug!("Active keyset ID: {:?}", active_keyset_id); // Get keyset fees - let keyset_fee_ppk = self.get_keyset_fees_by_id(active_keyset_id).await?; + let keyset_fee_ppk = self.wallet.get_keyset_fees_by_id(active_keyset_id).await?; tracing::debug!("Keyset fees: {:?}", keyset_fee_ppk); // Calculate total send amount - let total_send_amount = send.amount + send.send_fee; + let total_send_amount = self.amount + self.send_fee; tracing::debug!("Total send amount: {}", total_send_amount); // Swap proofs if necessary - if !send.proofs_to_swap.is_empty() { + if !self.proofs_to_swap.is_empty() { let swap_amount = total_send_amount - proofs_to_send.total_amount()?; tracing::debug!("Swapping proofs; swap_amount={:?}", swap_amount); if let Some(proofs) = self + .wallet .swap( Some(swap_amount), SplitTarget::None, - send.proofs_to_swap, - send.options.conditions.clone(), + self.proofs_to_swap, + self.options.conditions.clone(), false, // already included in swap_amount ) .await? @@ -242,15 +296,16 @@ impl Wallet { ); // Check if sufficient proofs are available - if send.amount > proofs_to_send.total_amount()? { + if self.amount > proofs_to_send.total_amount()? { return Err(Error::InsufficientFunds); } // Check if proofs are reserved or unspent let sendable_proof_ys = self + .wallet .get_proofs_with( Some(vec![State::Reserved, State::Unspent]), - send.options.conditions.clone().map(|c| vec![c]), + self.options.conditions.clone().map(|c| vec![c]), ) .await? .ys()?; @@ -268,45 +323,47 @@ impl Wallet { "Updating proofs state to pending spent: {:?}", proofs_to_send.ys()? ); - self.localstore + self.wallet + .localstore .update_proofs_state(proofs_to_send.ys()?, State::PendingSpent) .await?; // Include token memo - let send_memo = send.options.memo.or(memo); + let send_memo = self.options.memo.or(memo); let memo = send_memo.and_then(|m| if m.include_memo { Some(m.memo) } else { None }); // Add transaction to store - self.localstore + self.wallet + .localstore .add_transaction(Transaction { - mint_url: self.mint_url.clone(), + mint_url: self.wallet.mint_url.clone(), direction: TransactionDirection::Outgoing, - amount: send.amount, + amount: self.amount, fee: total_send_fee, - unit: self.unit.clone(), + unit: self.wallet.unit.clone(), ys: proofs_to_send.ys()?, timestamp: unix_time(), memo: memo.clone(), - metadata: send.options.metadata, + metadata: self.options.metadata, }) .await?; // Create and return token Ok(Token::new( - self.mint_url.clone(), + self.wallet.mint_url.clone(), proofs_to_send, memo, - self.unit.clone(), + self.wallet.unit.clone(), )) } - /// Cancel prepared send - pub async fn cancel_send(&self, send: PreparedSend) -> Result<(), Error> { + /// Cancel the prepared send + pub async fn cancel(self) -> Result<(), Error> { tracing::info!("Cancelling prepared send"); // Double-check proofs state - let reserved_proofs = self.get_reserved_proofs().await?.ys()?; - if !send + let reserved_proofs = self.wallet.get_reserved_proofs().await?.ys()?; + if !self .proofs() .ys()? .iter() @@ -315,68 +372,15 @@ impl Wallet { return Err(Error::UnexpectedProofState); } - self.localstore - .update_proofs_state(send.proofs().ys()?, State::Unspent) + self.wallet + .localstore + .update_proofs_state(self.proofs().ys()?, State::Unspent) .await?; Ok(()) } } -/// Prepared send -pub struct PreparedSend { - amount: Amount, - options: SendOptions, - proofs_to_swap: Proofs, - swap_fee: Amount, - proofs_to_send: Proofs, - send_fee: Amount, -} - -impl PreparedSend { - /// Amount - pub fn amount(&self) -> Amount { - self.amount - } - - /// Send options - pub fn options(&self) -> &SendOptions { - &self.options - } - - /// Proofs to swap (i.e., proofs that need to be swapped before constructing the token) - pub fn proofs_to_swap(&self) -> &Proofs { - &self.proofs_to_swap - } - - /// Swap fee - pub fn swap_fee(&self) -> Amount { - self.swap_fee - } - - /// Proofs to send (i.e., proofs that will be included in the token) - pub fn proofs_to_send(&self) -> &Proofs { - &self.proofs_to_send - } - - /// Send fee - pub fn send_fee(&self) -> Amount { - self.send_fee - } - - /// All proofs - pub fn proofs(&self) -> Proofs { - let mut proofs = self.proofs_to_swap.clone(); - proofs.extend(self.proofs_to_send.clone()); - proofs - } - - /// Total fee - pub fn fee(&self) -> Amount { - self.swap_fee + self.send_fee - } -} - impl Debug for PreparedSend { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { f.debug_struct("PreparedSend") From dc19798201e33d72d28dcf9f802767b6c782fd64 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Wed, 30 Jul 2025 23:45:53 -0400 Subject: [PATCH 051/321] feat(dev): add Goose recipes for changelog and commit message generation - Add new Goose recipes for generating conventional commit messages and updating changelogs - Include recipes for both staged changes and recent commits analysis - Add convenient Just commands for running the new recipes - Update README with usage instructions for the new recipes ([thesimplekid]). --- CHANGELOG.md | 1 + justfile | 16 +++-- misc/recipes/changelog-from-commits.yaml | 76 ++++++++++++++++++++++++ misc/recipes/changelog-update.yaml | 5 ++ 4 files changed, 93 insertions(+), 5 deletions(-) create mode 100644 misc/recipes/changelog-from-commits.yaml diff --git a/CHANGELOG.md b/CHANGELOG.md index 4f1618b3e..7726fd85f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,7 @@ ## [Unreleased] ### Added +- dev: Goose recipes for changelog and commit message generation with Just commands ([thesimplekid]). - cashu: `KeySetInfos` type alias and `KeySetInfosMethods` trait for filtering keysets ([thesimplekid]). - cdk: Mint lifecycle management with `start()` and `stop()` methods for graceful background service control ([thesimplekid]). - cdk: Background task management for invoice payment monitoring with proper shutdown handling ([thesimplekid]). diff --git a/justfile b/justfile index 19c4a66c7..9bd1444d6 100644 --- a/justfile +++ b/justfile @@ -131,16 +131,22 @@ typos-fix: # Goose AI Recipe Commands -# Create git message from staged changes using Goose AI -goose-changelog-update: - #!/usr/bin/env bash - goose run --recipe ./misc/recipes/changelog-update.yaml --interactive - # Update changelog from staged changes using Goose AI goose-git-msg: #!/usr/bin/env bash goose run --recipe ./misc/recipes/git-commit-message.yaml --interactive +# Create git message from staged changes using Goose AI +goose-changelog-staged: + #!/usr/bin/env bash + goose run --recipe ./misc/recipes/changelog-update.yaml --interactive + +# Update changelog from recent commits using Goose AI +# Usage: just goose-changelog-commits [number_of_commits] +goose-changelog-commits *COMMITS="5": + #!/usr/bin/env bash + COMMITS={{COMMITS}} goose run --recipe ./misc/recipes/changelog-from-commits.yaml --interactive + itest db: #!/usr/bin/env bash ./misc/itests.sh "{{db}}" diff --git a/misc/recipes/changelog-from-commits.yaml b/misc/recipes/changelog-from-commits.yaml new file mode 100644 index 000000000..a95889197 --- /dev/null +++ b/misc/recipes/changelog-from-commits.yaml @@ -0,0 +1,76 @@ +version: 1.0.0 +title: Update Changelog from last commits +description: A custom recipe to update changelog from the last X commits +instructions: Analyze recent Git commits and automatically update project changelogs following Keep a Changelog format. Read commit history using git log, understand the nature of code changes (API refactoring, new features, bug fixes, etc.), and add appropriately categorized entries to the Unreleased section. Use the git author's username for attribution and follow established changelog patterns including proper formatting with contributor links. Requires git command line tools and file editing capabilities. +prompt: | + You are tasked with updating the CHANGELOG.md file based on recent Git commits. Follow these instructions: + + ## Analysis Process: + 1. **Get commit count**: Check if a COMMITS environment variable was provided (default to 5 if not specified) + 2. **Read recent commits**: Use `git log -n X` to analyze the last X commits (where X is the number specified by user or default) + 3. **Get git author**: Use `git config --get user.name` to get the author name for attribution + 4. **Analyze change types**: Categorize changes into: + - **Added**: New features, new functions, new files, new functionality + - **Changed**: Modifications to existing functionality, refactoring, API changes, dependency updates + - **Fixed**: Bug fixes, error handling improvements, corrections + - **Removed**: Deleted files, deprecated functions, removed dependencies + + ## CHANGELOG.md Update Requirements: + 1. **Preserve existing format**: Keep the exact formatting style of the existing CHANGELOG.md + 2. **Update Unreleased section**: Add new entries to the "## [Unreleased]" section only + 3. **Use proper categories**: Add entries under the appropriate subsections (Added, Changed, Fixed, Removed) + 4. **Follow format pattern**: Each entry should follow this exact format: + ``` + - component: Description of change ([author]). + ``` + 5. **Author attribution**: Use the git author name in square brackets at the end of each entry + 6. **Component identification**: Identify the relevant component (e.g., "cdk", "cashu", "cdk-cli", etc.) from file paths + 7. **Maintain formatting**: + - Use proper bullet points with hyphens + - Maintain consistent spacing + - Keep entries concise but descriptive + - End each entry with period before author attribution + + ## Example Entry Format: + ```markdown + ### Added + - cdk: New keyset refresh functionality with improved error handling ([thesimplekid]). + + ### Changed + - cdk: Refactored wallet keyset management for better performance ([thesimplekid]). + + ### Fixed + - cdk-cli: Fixed token parsing error for malformed inputs ([thesimplekid]). + ``` + + ## Important Guidelines: + - **DO NOT** modify any existing changelog entries + - **DO NOT** change the structure or format of the changelog + - **ONLY** add new entries to the Unreleased section + - **DO NOT** add duplicate entries + - **BE SPECIFIC** about what changed, not just which files + - **FOCUS** on user-facing changes and important internal improvements + - **IGNORE** trivial changes like whitespace, comments, or formatting unless they're significant + + ## Steps to Execute: + 1. Check for COMMITS environment variable or ask user for the number of recent commits to analyze (default to 5) + 2. Read current CHANGELOG.md file to understand format + 3. Get git author name + 4. Analyze recent commits with `git log -n X --pretty=format:"%h %s"` + 5. For each commit, examine detailed changes with `git show COMMIT_HASH` + 6. Categorize and write appropriate changelog entries + 7. Update the CHANGELOG.md file preserving all existing content +extensions: +- type: builtin + name: developer + display_name: Developer + timeout: 300 + bundled: true +activities: +- Update changelog from recent commits +- Analyze API refactoring commits +- Add new feature entries +- Categorize bug fix changes +- Format contributor attributions +author: + contact: thesimplekid diff --git a/misc/recipes/changelog-update.yaml b/misc/recipes/changelog-update.yaml index 75afcd9ff..cf2b14de4 100644 --- a/misc/recipes/changelog-update.yaml +++ b/misc/recipes/changelog-update.yaml @@ -57,6 +57,11 @@ prompt: | 3. Analyze staged changes with `git diff --staged` 4. Categorize and write appropriate changelog entries 5. Update the CHANGELOG.md file preserving all existing content + + ## Alternative Recipe: + If you want to generate changelog entries from recent commits instead of staged changes, see the + `changelog-from-commits.yaml` recipe which analyzes the last X commits instead of staged changes. + extensions: - type: builtin name: developer From 3a3cd88ee94e1542787f7e733ca72b5b60a45d05 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Thu, 31 Jul 2025 00:43:43 -0400 Subject: [PATCH 052/321] Mintd lib (#914) * 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 --- CHANGELOG.md | 10 + Cargo.toml | 1 + crates/cdk-integration-tests/Cargo.toml | 5 +- .../src/bin/start_fake_auth_mint.rs | 163 ++++ .../src/bin/start_fake_mint.rs | 178 ++++ .../src/bin/start_regtest.rs | 62 +- .../src/bin/start_regtest_mints.rs | 305 +++++++ crates/cdk-integration-tests/src/cli.rs | 42 + .../src/init_pure_tests.rs | 4 +- .../cdk-integration-tests/src/init_regtest.rs | 98 ++- crates/cdk-integration-tests/src/lib.rs | 73 +- crates/cdk-integration-tests/src/shared.rs | 266 ++++++ crates/cdk-integration-tests/tests/bolt12.rs | 65 +- .../tests/fake_wallet.rs | 50 +- .../tests/happy_path_mint_wallet.rs | 37 +- .../tests/integration_tests_pure.rs | 5 + crates/cdk-integration-tests/tests/mint.rs | 9 +- crates/cdk-integration-tests/tests/regtest.rs | 124 ++- .../cdk-integration-tests/tests/test_fees.rs | 9 +- crates/cdk-mint-rpc/Cargo.toml | 2 +- crates/cdk-mint-rpc/src/bin/mint_rpc_cli.rs | 52 +- crates/cdk-mintd/src/cli.rs | 8 + crates/cdk-mintd/src/lib.rs | 805 +++++++++++++++++- crates/cdk-mintd/src/main.rs | 795 +---------------- crates/cdk-payment-processor/Cargo.toml | 1 + .../src/bin/payment_processor.rs | 58 +- crates/cdk-signatory/src/bin/cli/mod.rs | 54 +- misc/fake_auth_itests.sh | 107 +-- misc/fake_itests.sh | 126 ++- misc/interactive_regtest_mprocs.sh | 2 +- misc/itests.sh | 158 ++-- misc/mintd_payment_processor.sh | 2 +- misc/nutshell_wallet_itest.sh | 3 + 33 files changed, 2469 insertions(+), 1210 deletions(-) create mode 100644 crates/cdk-integration-tests/src/bin/start_fake_auth_mint.rs create mode 100644 crates/cdk-integration-tests/src/bin/start_fake_mint.rs create mode 100644 crates/cdk-integration-tests/src/bin/start_regtest_mints.rs create mode 100644 crates/cdk-integration-tests/src/cli.rs create mode 100644 crates/cdk-integration-tests/src/shared.rs diff --git a/CHANGELOG.md b/CHANGELOG.md index 7726fd85f..c03aa5bee 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,10 @@ - cashu: NUT-19 support in the wallet ([crodas]). - cdk: SIG_ALL support for swap and melt operations ([thesimplekid]). - cdk-sql-common: Add cache to SQL statements for better performance ([crodas]). +- cdk-integration-tests: New binary `start_fake_auth_mint` for testing fake mint with authentication ([thesimplekid]). +- cdk-integration-tests: New binary `start_fake_mint` for testing fake mint instances ([thesimplekid]). +- cdk-integration-tests: New binary `start_regtest_mints` for testing regtest mints ([thesimplekid]). +- cdk-integration-tests: Shared utilities module for common integration test functionality ([thesimplekid]). ### Changed - cdk: Refactored wallet keyset management methods for better clarity and separation of concerns ([thesimplekid]). @@ -28,6 +32,12 @@ - cdk-integration-tests: Updated test utilities to use new mint lifecycle management ([thesimplekid]). - cdk-sqlite: Introduce `cdk-sql-common` crate for shared SQL storage codebase ([crodas]). - cdk-sqlite: Rename `still_active` to `stale` for better clarity ([crodas]). +- cdk-integration-tests: Refactored regtest setup to use Rust binaries instead of shell scripts ([thesimplekid]). +- cdk-integration-tests: Improved environment variable handling for test configurations ([thesimplekid]). +- cdk-integration-tests: Enhanced CLN client connection with retry logic ([thesimplekid]). +- cdk-integration-tests: Updated integration tests to use proper temp directory management ([thesimplekid]). +- cdk-integration-tests: Simplified regtest shell scripts to use new binaries ([thesimplekid]). +- crates/cdk-mintd: Moved mintd library functions to separate module for better organization and testability ([thesimplekid]). ### Fixed - cashu: Fixed CurrencyUnit custom units preserving original case instead of being converted to uppercase ([thesimplekid]). diff --git a/Cargo.toml b/Cargo.toml index 527ee25a1..08fc3c4a0 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -57,6 +57,7 @@ cdk-redb = { path = "./crates/cdk-redb", default-features = true, version = "=0. cdk-sql-common = { path = "./crates/cdk-sql-common", default-features = true, version = "=0.11.0" } cdk-sqlite = { path = "./crates/cdk-sqlite", default-features = true, version = "=0.11.0" } cdk-signatory = { path = "./crates/cdk-signatory", version = "=0.11.0", default-features = false } +cdk-mintd = { path = "./crates/cdk-mintd", version = "=0.11.0", default-features = false } clap = { version = "4.5.31", features = ["derive"] } ciborium = { version = "0.2.2", default-features = false, features = ["std"] } cbor-diag = "0.1.12" diff --git a/crates/cdk-integration-tests/Cargo.toml b/crates/cdk-integration-tests/Cargo.toml index 26a9da986..ceaf68384 100644 --- a/crates/cdk-integration-tests/Cargo.toml +++ b/crates/cdk-integration-tests/Cargo.toml @@ -23,10 +23,12 @@ cashu = { workspace = true, features = ["mint", "wallet"] } cdk = { workspace = true, features = ["mint", "wallet", "auth"] } cdk-cln = { workspace = true } cdk-lnd = { workspace = true } -cdk-axum = { workspace = true } +cdk-axum = { workspace = true, features = ["auth"] } cdk-sqlite = { workspace = true } cdk-redb = { workspace = true } cdk-fake-wallet = { workspace = true } +cdk-common = { workspace = true, features = ["mint", "wallet", "auth"] } +cdk-mintd = { workspace = true, features = ["cln", "lnd", "fakewallet", "grpc-processor", "auth", "lnbits", "management-rpc"] } futures = { workspace = true, default-features = false, features = [ "executor", ] } @@ -44,6 +46,7 @@ tower-http = { workspace = true, features = ["cors"] } tower-service = "0.3.3" reqwest.workspace = true bitcoin = "0.32.0" +clap = { workspace = true, features = ["derive"] } [target.'cfg(not(target_arch = "wasm32"))'.dependencies] tokio.workspace = true diff --git a/crates/cdk-integration-tests/src/bin/start_fake_auth_mint.rs b/crates/cdk-integration-tests/src/bin/start_fake_auth_mint.rs new file mode 100644 index 000000000..4cb3ad9d3 --- /dev/null +++ b/crates/cdk-integration-tests/src/bin/start_fake_auth_mint.rs @@ -0,0 +1,163 @@ +//! Binary for starting a fake mint with authentication for testing +//! +//! This binary provides a programmatic way to start a fake mint instance with authentication for testing purposes: +//! 1. Sets up a fake mint instance with authentication using the cdk-mintd library +//! 2. Configures OpenID Connect authentication settings +//! 3. Waits for the mint to be ready and responsive +//! 4. Keeps it running until interrupted (Ctrl+C) +//! 5. Gracefully shuts down on receiving shutdown signal +//! +//! This approach offers better control and integration compared to external scripts, +//! making it easier to run authentication integration tests with consistent configuration. + +use std::path::Path; +use std::sync::Arc; + +use anyhow::Result; +use bip39::Mnemonic; +use cdk_integration_tests::cli::CommonArgs; +use cdk_integration_tests::shared; +use clap::Parser; +use tokio::sync::Notify; + +#[derive(Parser)] +#[command(name = "start-fake-auth-mint")] +#[command(about = "Start a fake mint with authentication for testing", long_about = None)] +struct Args { + #[command(flatten)] + common: CommonArgs, + + /// Database type (sqlite) + database_type: String, + + /// Working directory path + work_dir: String, + + /// OpenID discovery URL + openid_discovery: String, + + /// Port to listen on (default: 8087) + #[arg(default_value_t = 8087)] + port: u16, +} + +/// Start a fake mint with authentication using the library +async fn start_fake_auth_mint( + temp_dir: &Path, + port: u16, + openid_discovery: String, + shutdown: Arc, +) -> Result> { + println!("Starting fake auth mintd on port {port}"); + + // Create settings struct for fake mint with auth using shared function + let fake_wallet_config = cdk_mintd::config::FakeWallet { + supported_units: vec![cdk::nuts::CurrencyUnit::Sat, cdk::nuts::CurrencyUnit::Usd], + fee_percent: 0.0, + reserve_fee_min: cdk::Amount::from(1), + min_delay_time: 1, + max_delay_time: 3, + }; + + let mut settings = shared::create_fake_wallet_settings( + port, + Some(Mnemonic::generate(12)?.to_string()), + None, + Some(fake_wallet_config), + ); + + // Enable authentication + settings.auth = Some(cdk_mintd::config::Auth { + openid_discovery, + openid_client_id: "cashu-client".to_string(), + mint_max_bat: 50, + enabled_mint: true, + enabled_melt: true, + enabled_swap: true, + enabled_check_mint_quote: true, + enabled_check_melt_quote: true, + enabled_restore: true, + enabled_check_proof_state: true, + }); + + // Set description for the mint + settings.mint_info.description = "fake test mint with auth".to_string(); + + let temp_dir = temp_dir.to_path_buf(); + let shutdown_clone = shutdown.clone(); + + // Run the mint in a separate task + let handle = tokio::spawn(async move { + // Create a future that resolves when the shutdown signal is received + let shutdown_future = async move { + shutdown_clone.notified().await; + println!("Fake auth mint shutdown signal received"); + }; + + match cdk_mintd::run_mintd_with_shutdown(&temp_dir, &settings, shutdown_future, None).await + { + Ok(_) => println!("Fake auth mint exited normally"), + Err(e) => eprintln!("Fake auth mint exited with error: {e}"), + } + }); + + Ok(handle) +} + +#[tokio::main] +async fn main() -> Result<()> { + let args = Args::parse(); + + // Initialize logging based on CLI arguments + shared::setup_logging(&args.common); + + let temp_dir = shared::init_working_directory(&args.work_dir)?; + + // Start fake auth mint + let shutdown = shared::create_shutdown_handler(); + let shutdown_clone = shutdown.clone(); + + let handle = start_fake_auth_mint( + &temp_dir, + args.port, + args.openid_discovery.clone(), + shutdown_clone, + ) + .await?; + + // Wait for fake auth mint to be ready + if let Err(e) = shared::wait_for_mint_ready(args.port, 100).await { + eprintln!("Error waiting for fake auth mint: {e}"); + return Err(e); + } + + println!("Fake auth mint started successfully!"); + println!("Fake auth mint: http://127.0.0.1:{}", args.port); + println!("Temp directory: {temp_dir:?}"); + println!("Database type: {}", args.database_type); + println!("OpenID Discovery: {}", args.openid_discovery); + println!(); + println!("Environment variables needed for tests:"); + println!(" CDK_TEST_OIDC_USER="); + println!(" CDK_TEST_OIDC_PASSWORD="); + println!(); + println!("You can now run auth integration tests with:"); + println!(" cargo test -p cdk-integration-tests --test fake_auth"); + println!(); + + println!("Press Ctrl+C to stop the mint..."); + + // Wait for Ctrl+C signal + shared::wait_for_shutdown_signal(shutdown).await; + + println!("\nReceived Ctrl+C, shutting down mint..."); + + // Wait for mint to finish gracefully + if let Err(e) = handle.await { + eprintln!("Error waiting for mint to shut down: {e}"); + } + + println!("Mint shut down successfully"); + + Ok(()) +} diff --git a/crates/cdk-integration-tests/src/bin/start_fake_mint.rs b/crates/cdk-integration-tests/src/bin/start_fake_mint.rs new file mode 100644 index 000000000..2d1d490b7 --- /dev/null +++ b/crates/cdk-integration-tests/src/bin/start_fake_mint.rs @@ -0,0 +1,178 @@ +//! Binary for starting a fake mint for testing +//! +//! This binary provides a programmatic way to start a fake mint instance for testing purposes: +//! 1. Sets up a fake mint instance using the cdk-mintd library +//! 2. Configures the mint with fake wallet backend for testing Lightning Network interactions +//! 3. Waits for the mint to be ready and responsive +//! 4. Keeps it running until interrupted (Ctrl+C) +//! 5. Gracefully shuts down on receiving shutdown signal +//! +//! This approach offers better control and integration compared to external scripts, +//! making it easier to run integration tests with consistent configuration. + +use std::path::Path; +use std::sync::Arc; + +use anyhow::Result; +use cdk::nuts::CurrencyUnit; +use cdk_integration_tests::cli::CommonArgs; +use cdk_integration_tests::shared; +use clap::Parser; +use tokio::sync::Notify; + +#[derive(Parser)] +#[command(name = "start-fake-mint")] +#[command(about = "Start a fake mint for testing", long_about = None)] +struct Args { + #[command(flatten)] + common: CommonArgs, + + /// Database type (sqlite) + database_type: String, + + /// Working directory path + work_dir: String, + + /// Port to listen on (default: 8086) + #[arg(default_value_t = 8086)] + port: u16, + + /// Use external signatory + #[arg(long, default_value_t = false)] + external_signatory: bool, +} + +/// Start a fake mint using the library +async fn start_fake_mint( + temp_dir: &Path, + port: u16, + shutdown: Arc, + external_signatory: bool, +) -> Result> { + let signatory_config = if external_signatory { + println!("Configuring external signatory"); + Some(( + "https://127.0.0.1:15060".to_string(), // Default signatory URL + temp_dir.to_string_lossy().to_string(), // Certs directory as string + )) + } else { + None + }; + + let mnemonic = if external_signatory { + None + } else { + Some( + "eye survey guilt napkin crystal cup whisper salt luggage manage unveil loyal" + .to_string(), + ) + }; + + let fake_wallet_config = Some(cdk_mintd::config::FakeWallet { + supported_units: vec![CurrencyUnit::Sat, CurrencyUnit::Usd], + fee_percent: 0.0, + reserve_fee_min: 1.into(), + min_delay_time: 1, + max_delay_time: 3, + }); + + // Create settings struct for fake mint using shared function + let settings = + shared::create_fake_wallet_settings(port, mnemonic, signatory_config, fake_wallet_config); + + println!("Starting fake mintd on port {port}"); + + let temp_dir = temp_dir.to_path_buf(); + let shutdown_clone = shutdown.clone(); + + // Run the mint in a separate task + let handle = tokio::spawn(async move { + // Create a future that resolves when the shutdown signal is received + let shutdown_future = async move { + shutdown_clone.notified().await; + println!("Fake mint shutdown signal received"); + }; + + match cdk_mintd::run_mintd_with_shutdown(&temp_dir, &settings, shutdown_future, None).await + { + Ok(_) => println!("Fake mint exited normally"), + Err(e) => eprintln!("Fake mint exited with error: {e}"), + } + }); + + Ok(handle) +} + +#[tokio::main] +async fn main() -> Result<()> { + let args = Args::parse(); + + // Initialize logging based on CLI arguments + shared::setup_logging(&args.common); + + let temp_dir = shared::init_working_directory(&args.work_dir)?; + + // Write environment variables to a .env file in the temp_dir BEFORE starting the mint + let mint_url = format!("http://127.0.0.1:{}", args.port); + let itests_dir = temp_dir.display().to_string(); + let env_vars: Vec<(&str, &str)> = vec![ + ("CDK_TEST_MINT_URL", &mint_url), + ("CDK_ITESTS_DIR", &itests_dir), + ]; + + shared::write_env_file(&temp_dir, &env_vars)?; + + // Start fake mint + let shutdown = shared::create_shutdown_handler(); + let shutdown_clone = shutdown.clone(); + + let handle = start_fake_mint( + &temp_dir, + args.port, + shutdown_clone, + args.external_signatory, + ) + .await?; + + // Wait for fake mint to be ready + if let Err(e) = shared::wait_for_mint_ready(args.port, 100).await { + eprintln!("Error waiting for fake mint: {e}"); + return Err(e); + } + + shared::display_mint_info(args.port, &temp_dir, &args.database_type); + + println!(); + println!( + "Environment variables written to: {}/.env", + temp_dir.display() + ); + println!("You can source these variables with:"); + println!(" source {}/.env", temp_dir.display()); + println!(); + println!("Environment variables set:"); + println!(" CDK_TEST_MINT_URL=http://127.0.0.1:{}", args.port); + println!(" CDK_ITESTS_DIR={}", temp_dir.display()); + println!(); + println!("You can now run integration tests with:"); + println!(" cargo test -p cdk-integration-tests --test fake_wallet"); + println!(" cargo test -p cdk-integration-tests --test happy_path_mint_wallet"); + println!(" etc."); + println!(); + + println!("Press Ctrl+C to stop the mint..."); + + // Wait for Ctrl+C signal + shared::wait_for_shutdown_signal(shutdown).await; + + println!("\nReceived Ctrl+C, shutting down mint..."); + + // Wait for mint to finish gracefully + if let Err(e) = handle.await { + eprintln!("Error waiting for mint to shut down: {e}"); + } + + println!("Mint shut down successfully"); + + Ok(()) +} diff --git a/crates/cdk-integration-tests/src/bin/start_regtest.rs b/crates/cdk-integration-tests/src/bin/start_regtest.rs index e63a8cdc6..cec63d88a 100644 --- a/crates/cdk-integration-tests/src/bin/start_regtest.rs +++ b/crates/cdk-integration-tests/src/bin/start_regtest.rs @@ -1,20 +1,33 @@ use std::fs::OpenOptions; use std::io::Write; +use std::path::{Path, PathBuf}; +use std::str::FromStr; use std::sync::Arc; use std::time::Duration; -use anyhow::{bail, Result}; -use cdk_integration_tests::init_regtest::{get_temp_dir, start_regtest_end}; +use anyhow::Result; +use cdk_integration_tests::cli::{init_logging, CommonArgs}; +use cdk_integration_tests::init_regtest::start_regtest_end; +use clap::Parser; use tokio::signal; use tokio::sync::{oneshot, Notify}; use tokio::time::timeout; -use tracing_subscriber::EnvFilter; -fn signal_progress() { - let temp_dir = get_temp_dir(); +#[derive(Parser)] +#[command(name = "start-regtest")] +#[command(about = "Start regtest environment", long_about = None)] +struct Args { + #[command(flatten)] + common: CommonArgs, + + /// Working directory path + work_dir: String, +} + +fn signal_progress(work_dir: &Path) { let mut pipe = OpenOptions::new() .write(true) - .open(temp_dir.join("progress_pipe")) + .open(work_dir.join("progress_pipe")) .expect("Failed to open pipe"); pipe.write_all(b"checkpoint1\n") @@ -23,24 +36,21 @@ fn signal_progress() { #[tokio::main] async fn main() -> Result<()> { - let default_filter = "debug"; - - let sqlx_filter = "sqlx=warn"; - let hyper_filter = "hyper=warn"; - let h2_filter = "h2=warn"; - let rustls_filter = "rustls=warn"; + let args = Args::parse(); - let env_filter = EnvFilter::new(format!( - "{default_filter},{sqlx_filter},{hyper_filter},{h2_filter},{rustls_filter}" - )); + // Initialize logging based on CLI arguments + init_logging(args.common.enable_logging, args.common.log_level); - tracing_subscriber::fmt().with_env_filter(env_filter).init(); + let temp_dir = PathBuf::from_str(&args.work_dir)?; + let temp_dir_clone = temp_dir.clone(); let shutdown_regtest = Arc::new(Notify::new()); - let shutdown_clone = shutdown_regtest.clone(); + let shutdown_clone = Arc::clone(&shutdown_regtest); + let shutdown_clone_two = Arc::clone(&shutdown_regtest); + let (tx, rx) = oneshot::channel(); tokio::spawn(async move { - start_regtest_end(tx, shutdown_clone) + start_regtest_end(&temp_dir_clone, tx, shutdown_clone) .await .expect("Error starting regtest"); }); @@ -48,15 +58,25 @@ async fn main() -> Result<()> { match timeout(Duration::from_secs(300), rx).await { Ok(_) => { tracing::info!("Regtest set up"); - signal_progress(); + signal_progress(&temp_dir); } Err(_) => { tracing::error!("regtest setup timed out after 5 minutes"); - bail!("Could not set up regtest"); + anyhow::bail!("Could not set up regtest"); } } - signal::ctrl_c().await?; + let shutdown_future = async { + // Wait for Ctrl+C signal + signal::ctrl_c() + .await + .expect("failed to install CTRL+C handler"); + tracing::info!("Shutdown signal received"); + println!("\nReceived Ctrl+C, shutting down mints..."); + shutdown_clone_two.notify_waiters(); + }; + + shutdown_future.await; Ok(()) } diff --git a/crates/cdk-integration-tests/src/bin/start_regtest_mints.rs b/crates/cdk-integration-tests/src/bin/start_regtest_mints.rs new file mode 100644 index 000000000..ccef911b0 --- /dev/null +++ b/crates/cdk-integration-tests/src/bin/start_regtest_mints.rs @@ -0,0 +1,305 @@ +//! Binary for starting regtest mints +//! +//! This binary provides a programmatic way to start regtest mints for testing purposes: +//! 1. Sets up a regtest environment with CLN and LND nodes +//! 2. Starts CLN and LND mint instances using the cdk-mintd library +//! 3. Configures the mints to connect to the respective Lightning Network backends +//! 4. Waits for both mints to be ready and responsive +//! 5. Keeps them running until interrupted (Ctrl+C) +//! 6. Gracefully shuts down all services on receiving shutdown signal +//! +//! This approach offers better control and integration compared to external scripts, +//! making it easier to run integration tests with consistent configuration. + +use std::fs; +use std::path::Path; +use std::sync::Arc; +use std::time::Duration; + +use anyhow::Result; +use cdk_integration_tests::cli::CommonArgs; +use cdk_integration_tests::init_regtest::start_regtest_end; +use cdk_integration_tests::shared; +use clap::Parser; +use tokio::signal::unix::SignalKind; +use tokio::signal::{self}; +use tokio::sync::{oneshot, Notify}; +use tokio::time::timeout; + +#[derive(Parser)] +#[command(name = "start-regtest-mints")] +#[command(about = "Start regtest mints", long_about = None)] +struct Args { + #[command(flatten)] + common: CommonArgs, + + /// Database type (sqlite) + database_type: String, + + /// Working directory path + work_dir: String, + + /// Mint address (default: 127.0.0.1) + #[arg(default_value = "127.0.0.1")] + mint_addr: String, + + /// CLN port (default: 8085) + #[arg(default_value_t = 8085)] + cln_port: u16, + + /// LND port (default: 8087) + #[arg(default_value_t = 8087)] + lnd_port: u16, +} + +/// Start regtest CLN mint using the library +async fn start_cln_mint( + temp_dir: &Path, + port: u16, + shutdown: Arc, +) -> Result> { + let cln_rpc_path = temp_dir + .join("cln") + .join("one") + .join("regtest") + .join("lightning-rpc"); + + let cln_config = cdk_mintd::config::Cln { + rpc_path: cln_rpc_path, + bolt12: false, + fee_percent: 0.0, + reserve_fee_min: 0.into(), + }; + + // Create settings struct for CLN mint using shared function + let settings = shared::create_cln_settings( + port, + temp_dir + .join("cln") + .join("one") + .join("regtest") + .join("lightning-rpc"), + "eye survey guilt napkin crystal cup whisper salt luggage manage unveil loyal".to_string(), + cln_config, + ); + + println!("Starting CLN mintd on port {port}"); + + let temp_dir = temp_dir.to_path_buf(); + let shutdown_clone = shutdown.clone(); + + // Run the mint in a separate task + let handle = tokio::spawn(async move { + // Create a future that resolves when the shutdown signal is received + let shutdown_future = async move { + shutdown_clone.notified().await; + println!("CLN mint shutdown signal received"); + }; + + match cdk_mintd::run_mintd_with_shutdown(&temp_dir, &settings, shutdown_future, None).await + { + Ok(_) => println!("CLN mint exited normally"), + Err(e) => eprintln!("CLN mint exited with error: {e}"), + } + }); + + Ok(handle) +} + +/// Start regtest LND mint using the library +async fn start_lnd_mint( + temp_dir: &Path, + port: u16, + shutdown: Arc, +) -> Result> { + let lnd_cert_file = temp_dir.join("lnd").join("two").join("tls.cert"); + let lnd_macaroon_file = temp_dir + .join("lnd") + .join("two") + .join("data") + .join("chain") + .join("bitcoin") + .join("regtest") + .join("admin.macaroon"); + let lnd_work_dir = temp_dir.join("lnd_mint"); + + // Create work directory for LND mint + fs::create_dir_all(&lnd_work_dir)?; + + let lnd_config = cdk_mintd::config::Lnd { + address: "https://localhost:10010".to_string(), + cert_file: lnd_cert_file, + macaroon_file: lnd_macaroon_file, + fee_percent: 0.0, + reserve_fee_min: 0.into(), + }; + + // Create settings struct for LND mint using shared function + let settings = shared::create_lnd_settings( + port, + lnd_config, + "cattle gold bind busy sound reduce tone addict baby spend february strategy".to_string(), + ); + + println!("Starting LND mintd on port {port}"); + + let lnd_work_dir = lnd_work_dir.clone(); + let shutdown_clone = shutdown.clone(); + + // Run the mint in a separate task + let handle = tokio::spawn(async move { + // Create a future that resolves when the shutdown signal is received + let shutdown_future = async move { + shutdown_clone.notified().await; + println!("LND mint shutdown signal received"); + }; + + match cdk_mintd::run_mintd_with_shutdown(&lnd_work_dir, &settings, shutdown_future, None) + .await + { + Ok(_) => println!("LND mint exited normally"), + Err(e) => eprintln!("LND mint exited with error: {e}"), + } + }); + + Ok(handle) +} + +#[tokio::main] +async fn main() -> Result<()> { + let args = Args::parse(); + + // Initialize logging based on CLI arguments + shared::setup_logging(&args.common); + + let temp_dir = shared::init_working_directory(&args.work_dir)?; + + // Write environment variables to a .env file in the temp_dir + let mint_url_1 = format!("http://{}:{}", args.mint_addr, args.cln_port); + let mint_url_2 = format!("http://{}:{}", args.mint_addr, args.lnd_port); + let env_vars: Vec<(&str, &str)> = vec![ + ("CDK_TEST_MINT_URL", &mint_url_1), + ("CDK_TEST_MINT_URL_2", &mint_url_2), + ]; + + shared::write_env_file(&temp_dir, &env_vars)?; + + // Start regtest + println!("Starting regtest..."); + + let shutdown_regtest = shared::create_shutdown_handler(); + let shutdown_clone = shutdown_regtest.clone(); + let (tx, rx) = oneshot::channel(); + + let shutdown_clone_one = Arc::clone(&shutdown_clone); + + let temp_dir_clone = temp_dir.clone(); + tokio::spawn(async move { + start_regtest_end(&temp_dir_clone, tx, shutdown_clone_one) + .await + .expect("Error starting regtest"); + }); + + match timeout(Duration::from_secs(300), rx).await { + Ok(_) => { + tracing::info!("Regtest set up"); + } + Err(_) => { + tracing::error!("regtest setup timed out after 5 minutes"); + anyhow::bail!("Could not set up regtest"); + } + } + + // Start CLN mint + let cln_handle = start_cln_mint(&temp_dir, args.cln_port, shutdown_clone.clone()).await?; + + // Wait for CLN mint to be ready + if let Err(e) = shared::wait_for_mint_ready(args.cln_port, 100).await { + eprintln!("Error waiting for CLN mint: {e}"); + return Err(e); + } + + // Start LND mint + let lnd_handle = start_lnd_mint(&temp_dir, args.lnd_port, shutdown_clone.clone()).await?; + + // Wait for LND mint to be ready + if let Err(e) = shared::wait_for_mint_ready(args.lnd_port, 100).await { + eprintln!("Error waiting for LND mint: {e}"); + return Err(e); + } + + println!("All regtest mints started successfully!"); + println!("CLN mint: http://{}:{}", args.mint_addr, args.cln_port); + println!("LND mint: http://{}:{}", args.mint_addr, args.lnd_port); + shared::display_mint_info(args.cln_port, &temp_dir, &args.database_type); // Using CLN port for display + println!(); + println!("Environment variables set:"); + println!( + " CDK_TEST_MINT_URL=http://{}:{}", + args.mint_addr, args.cln_port + ); + println!( + " CDK_TEST_MINT_URL_2=http://{}:{}", + args.mint_addr, args.lnd_port + ); + println!(" CDK_ITESTS_DIR={}", temp_dir.display()); + println!(); + println!("You can now run integration tests with:"); + println!(" cargo test -p cdk-integration-tests --test regtest"); + println!(" cargo test -p cdk-integration-tests --test happy_path_mint_wallet"); + println!(" etc."); + println!(); + + println!("Press Ctrl+C to stop the mints..."); + + // Create a future to wait for either Ctrl+C signal or unexpected mint termination + let shutdown_future = async { + // Wait for either SIGINT (Ctrl+C) or SIGTERM + let mut sigterm = signal::unix::signal(SignalKind::terminate()) + .expect("Failed to create SIGTERM signal handler"); + tokio::select! { + _ = signal::ctrl_c() => { + tracing::info!("Received SIGINT (Ctrl+C), shutting down mints..."); + } + _ = sigterm.recv() => { + tracing::info!("Received SIGTERM, shutting down mints..."); + } + } + println!("\nShutdown signal received, shutting down mints..."); + shutdown_clone.notify_waiters(); + }; + + // Monitor mint handles for unexpected termination + let monitor_mints = async { + loop { + if cln_handle.is_finished() { + println!("CLN mint finished unexpectedly"); + return; + } + if lnd_handle.is_finished() { + println!("LND mint finished unexpectedly"); + return; + } + tokio::time::sleep(Duration::from_millis(100)).await; + } + }; + + // Wait for either shutdown signal or mint termination + tokio::select! { + _ = shutdown_future => { + println!("Shutdown signal received, waiting for mints to stop..."); + } + _ = monitor_mints => { + println!("One or more mints terminated unexpectedly"); + } + } + + // Wait for mints to finish gracefully + if let Err(e) = tokio::try_join!(cln_handle, lnd_handle) { + eprintln!("Error waiting for mints to shut down: {e}"); + } + + println!("All services shut down successfully"); + + Ok(()) +} diff --git a/crates/cdk-integration-tests/src/cli.rs b/crates/cdk-integration-tests/src/cli.rs new file mode 100644 index 000000000..f803da757 --- /dev/null +++ b/crates/cdk-integration-tests/src/cli.rs @@ -0,0 +1,42 @@ +//! Common CLI and logging utilities for CDK integration test binaries +//! +//! This module provides standardized CLI argument parsing and logging setup +//! for integration test binaries. + +use clap::Parser; +use tracing_subscriber::EnvFilter; + +/// Common CLI arguments for CDK integration test binaries +#[derive(Parser, Debug)] +pub struct CommonArgs { + /// Enable logging (default is false) + #[arg(long, default_value_t = false)] + pub enable_logging: bool, + + /// Logging level when enabled (default is debug) + #[arg(long, default_value = "debug")] + pub log_level: tracing::Level, +} + +/// Initialize logging based on CLI arguments +pub fn init_logging(enable_logging: bool, log_level: tracing::Level) { + if enable_logging { + let default_filter = log_level.to_string(); + + // Common filters to reduce noise + let sqlx_filter = "sqlx=warn"; + let hyper_filter = "hyper=warn"; + let h2_filter = "h2=warn"; + let rustls_filter = "rustls=warn"; + let reqwest_filter = "reqwest=warn"; + + let env_filter = EnvFilter::new(format!( + "{default_filter},{sqlx_filter},{hyper_filter},{h2_filter},{rustls_filter},{reqwest_filter}" + )); + + // Ok if successful, Err if already initialized + let _ = tracing_subscriber::fmt() + .with_env_filter(env_filter) + .try_init(); + } +} diff --git a/crates/cdk-integration-tests/src/init_pure_tests.rs b/crates/cdk-integration-tests/src/init_pure_tests.rs index 853dddb18..e3d86b830 100644 --- a/crates/cdk-integration-tests/src/init_pure_tests.rs +++ b/crates/cdk-integration-tests/src/init_pure_tests.rs @@ -211,10 +211,10 @@ impl MintConnector for DirectMintConnection { pub fn setup_tracing() { let default_filter = "debug"; - let sqlx_filter = "sqlx=warn"; + let h2_filter = "h2=warn"; let hyper_filter = "hyper=warn"; - let env_filter = EnvFilter::new(format!("{default_filter},{sqlx_filter},{hyper_filter}")); + let env_filter = EnvFilter::new(format!("{default_filter},{h2_filter},{hyper_filter}")); // Ok if successful, Err if already initialized // Allows us to setup tracing at the start of several parallel tests diff --git a/crates/cdk-integration-tests/src/init_regtest.rs b/crates/cdk-integration-tests/src/init_regtest.rs index fa021f8e6..538bd869a 100644 --- a/crates/cdk-integration-tests/src/init_regtest.rs +++ b/crates/cdk-integration-tests/src/init_regtest.rs @@ -31,21 +31,41 @@ pub const LND_TWO_RPC_ADDR: &str = "localhost:10010"; pub const CLN_ADDR: &str = "127.0.0.1:19846"; pub const CLN_TWO_ADDR: &str = "127.0.0.1:19847"; -pub fn get_mint_addr() -> String { - env::var("CDK_ITESTS_MINT_ADDR").expect("Mint address not set") +/// Configuration for regtest environment +pub struct RegtestConfig { + pub mint_addr: String, + pub cln_port: u16, + pub lnd_port: u16, + pub temp_dir: PathBuf, } -pub fn get_mint_port(which: &str) -> u16 { - let dir = env::var(format!("CDK_ITESTS_MINT_PORT_{which}")).expect("Mint port not set"); - dir.parse().unwrap() +impl Default for RegtestConfig { + fn default() -> Self { + Self { + mint_addr: "127.0.0.1".to_string(), + cln_port: 8085, + lnd_port: 8087, + temp_dir: std::env::temp_dir().join("cdk-itests-default"), + } + } } -pub fn get_mint_url(which: &str) -> String { - format!("http://{}:{}", get_mint_addr(), get_mint_port(which)) +pub fn get_mint_url_with_config(config: &RegtestConfig, which: &str) -> String { + let port = match which { + "0" => config.cln_port, + "1" => config.lnd_port, + _ => panic!("Unknown mint identifier: {which}"), + }; + format!("http://{}:{}", config.mint_addr, port) } -pub fn get_mint_ws_url(which: &str) -> String { - format!("ws://{}:{}/v1/ws", get_mint_addr(), get_mint_port(which)) +pub fn get_mint_ws_url_with_config(config: &RegtestConfig, which: &str) -> String { + let port = match which { + "0" => config.cln_port, + "1" => config.lnd_port, + _ => panic!("Unknown mint identifier: {which}"), + }; + format!("ws://{}:{}/v1/ws", config.mint_addr, port) } pub fn get_temp_dir() -> PathBuf { @@ -54,15 +74,19 @@ pub fn get_temp_dir() -> PathBuf { dir.parse().expect("Valid path buf") } -pub fn get_bitcoin_dir() -> PathBuf { - let dir = get_temp_dir().join(BITCOIN_DIR); +pub fn get_temp_dir_with_config(config: &RegtestConfig) -> &PathBuf { + &config.temp_dir +} + +pub fn get_bitcoin_dir(temp_dir: &Path) -> PathBuf { + let dir = temp_dir.join(BITCOIN_DIR); std::fs::create_dir_all(&dir).unwrap(); dir } -pub fn init_bitcoind() -> Bitcoind { +pub fn init_bitcoind(work_dir: &Path) -> Bitcoind { Bitcoind::new( - get_bitcoin_dir(), + get_bitcoin_dir(work_dir), BITCOIND_ADDR.parse().unwrap(), BITCOIN_RPC_USER.to_string(), BITCOIN_RPC_PASS.to_string(), @@ -81,14 +105,14 @@ pub fn init_bitcoin_client() -> Result { ) } -pub fn get_cln_dir(name: &str) -> PathBuf { - let dir = get_temp_dir().join("cln").join(name); +pub fn get_cln_dir(work_dir: &Path, name: &str) -> PathBuf { + let dir = work_dir.join("cln").join(name); std::fs::create_dir_all(&dir).unwrap(); dir } -pub fn get_lnd_dir(name: &str) -> PathBuf { - let dir = get_temp_dir().join("lnd").join(name); +pub fn get_lnd_dir(work_dir: &Path, name: &str) -> PathBuf { + let dir = work_dir.join("lnd").join(name); std::fs::create_dir_all(&dir).unwrap(); dir } @@ -101,9 +125,14 @@ pub fn get_lnd_macaroon_path(lnd_dir: &Path) -> PathBuf { lnd_dir.join("data/chain/bitcoin/regtest/admin.macaroon") } -pub async fn init_lnd(lnd_dir: PathBuf, lnd_addr: &str, lnd_rpc_addr: &str) -> Lnd { +pub async fn init_lnd( + work_dir: &Path, + lnd_dir: PathBuf, + lnd_addr: &str, + lnd_rpc_addr: &str, +) -> Lnd { Lnd::new( - get_bitcoin_dir(), + get_bitcoin_dir(work_dir), lnd_dir, lnd_addr.parse().unwrap(), lnd_rpc_addr.to_string(), @@ -192,8 +221,12 @@ where Ok(()) } -pub async fn start_regtest_end(sender: Sender<()>, notify: Arc) -> anyhow::Result<()> { - let mut bitcoind = init_bitcoind(); +pub async fn start_regtest_end( + work_dir: &Path, + sender: Sender<()>, + notify: Arc, +) -> anyhow::Result<()> { + let mut bitcoind = init_bitcoind(work_dir); bitcoind.start_bitcoind()?; let bitcoin_client = init_bitcoin_client()?; @@ -203,9 +236,9 @@ pub async fn start_regtest_end(sender: Sender<()>, notify: Arc) -> anyho let new_add = bitcoin_client.get_new_address()?; bitcoin_client.generate_blocks(&new_add, 200).unwrap(); - let cln_one_dir = get_cln_dir("one"); + let cln_one_dir = get_cln_dir(work_dir, "one"); let mut clnd = Clnd::new( - get_bitcoin_dir(), + get_bitcoin_dir(work_dir), cln_one_dir.clone(), CLN_ADDR.into(), BITCOIN_RPC_USER.to_string(), @@ -220,9 +253,9 @@ pub async fn start_regtest_end(sender: Sender<()>, notify: Arc) -> anyho fund_ln(&bitcoin_client, &cln_client).await.unwrap(); // Create second cln - let cln_two_dir = get_cln_dir("two"); + let cln_two_dir = get_cln_dir(work_dir, "two"); let mut clnd_two = Clnd::new( - get_bitcoin_dir(), + get_bitcoin_dir(work_dir), cln_two_dir.clone(), CLN_TWO_ADDR.into(), BITCOIN_RPC_USER.to_string(), @@ -236,10 +269,10 @@ pub async fn start_regtest_end(sender: Sender<()>, notify: Arc) -> anyho fund_ln(&bitcoin_client, &cln_two_client).await.unwrap(); - let lnd_dir = get_lnd_dir("one"); + let lnd_dir = get_lnd_dir(work_dir, "one"); println!("{}", lnd_dir.display()); - let mut lnd = init_lnd(lnd_dir.clone(), LND_ADDR, LND_RPC_ADDR).await; + let mut lnd = init_lnd(work_dir, lnd_dir.clone(), LND_ADDR, LND_RPC_ADDR).await; lnd.start_lnd().unwrap(); tracing::info!("Started lnd node"); @@ -255,8 +288,15 @@ pub async fn start_regtest_end(sender: Sender<()>, notify: Arc) -> anyho fund_ln(&bitcoin_client, &lnd_client).await.unwrap(); // create second lnd node - let lnd_two_dir = get_lnd_dir("two"); - let mut lnd_two = init_lnd(lnd_two_dir.clone(), LND_TWO_ADDR, LND_TWO_RPC_ADDR).await; + let work_dir = get_temp_dir(); + let lnd_two_dir = get_lnd_dir(&work_dir, "two"); + let mut lnd_two = init_lnd( + &work_dir, + lnd_two_dir.clone(), + LND_TWO_ADDR, + LND_TWO_RPC_ADDR, + ) + .await; lnd_two.start_lnd().unwrap(); tracing::info!("Started second lnd node"); diff --git a/crates/cdk-integration-tests/src/lib.rs b/crates/cdk-integration-tests/src/lib.rs index 2fb7d0623..41ccc0d75 100644 --- a/crates/cdk-integration-tests/src/lib.rs +++ b/crates/cdk-integration-tests/src/lib.rs @@ -1,4 +1,23 @@ +//! Integration Test Library +//! +//! This crate provides shared functionality for CDK integration tests. +//! It includes utilities for setting up test environments, funding wallets, +//! and common test operations across different test scenarios. +//! +//! Test Categories Supported: +//! - Pure in-memory tests (no external dependencies) +//! - Regtest environment tests (with actual Lightning nodes) +//! - Authenticated mint tests +//! - Multi-mint scenarios +//! +//! Key Components: +//! - Test environment initialization +//! - Wallet funding utilities +//! - Lightning Network client helpers +//! - Proof state management utilities + use std::env; +use std::path::Path; use std::sync::Arc; use anyhow::{anyhow, bail, Result}; @@ -8,13 +27,15 @@ use cdk::nuts::{MintQuoteState, NotificationPayload, State}; use cdk::wallet::WalletSubscription; use cdk::Wallet; use cdk_fake_wallet::create_fake_invoice; -use init_regtest::{get_lnd_dir, get_mint_url, LND_RPC_ADDR}; +use init_regtest::{get_lnd_dir, LND_RPC_ADDR}; use ln_regtest_rs::ln_client::{LightningClient, LndClient}; use tokio::time::{sleep, timeout, Duration}; +pub mod cli; pub mod init_auth_mint; pub mod init_pure_tests; pub mod init_regtest; +pub mod shared; pub async fn fund_wallet(wallet: Arc, amount: Amount) { let quote = wallet @@ -32,6 +53,20 @@ pub async fn fund_wallet(wallet: Arc, amount: Amount) { .expect("Could not mint"); } +pub fn get_mint_url_from_env() -> String { + match env::var("CDK_TEST_MINT_URL") { + Ok(url) => url, + Err(_) => panic!("Mint url not set"), + } +} + +pub fn get_second_mint_url_from_env() -> String { + match env::var("CDK_TEST_MINT_URL_2") { + Ok(url) => url, + Err(_) => panic!("Mint url not set"), + } +} + // Get all pending from wallet and attempt to swap // Will panic if there are no pending // Will return Ok if swap fails as expected @@ -151,33 +186,9 @@ pub async fn wait_for_mint_to_be_paid( } } -/// Gets the mint URL from environment variable or falls back to default -/// -/// Checks the CDK_TEST_MINT_URL environment variable: -/// - If set, returns that URL -/// - Otherwise falls back to the default URL from get_mint_url("0") -pub fn get_mint_url_from_env() -> String { - match env::var("CDK_TEST_MINT_URL") { - Ok(url) => url, - Err(_) => get_mint_url("0"), - } -} - -/// Gets the second mint URL from environment variable or falls back to default -/// -/// Checks the CDK_TEST_MINT_URL_2 environment variable: -/// - If set, returns that URL -/// - Otherwise falls back to the default URL from get_mint_url("1") -pub fn get_second_mint_url_from_env() -> String { - match env::var("CDK_TEST_MINT_URL_2") { - Ok(url) => url, - Err(_) => get_mint_url("1"), - } -} - // This is the ln wallet we use to send/receive ln payements as the wallet -pub async fn init_lnd_client() -> LndClient { - let lnd_dir = get_lnd_dir("one"); +pub async fn init_lnd_client(work_dir: &Path) -> LndClient { + let lnd_dir = get_lnd_dir(work_dir, "one"); let cert_file = lnd_dir.join("tls.cert"); let macaroon_file = lnd_dir.join("data/chain/bitcoin/regtest/admin.macaroon"); LndClient::new(format!("https://{LND_RPC_ADDR}"), cert_file, macaroon_file) @@ -189,10 +200,10 @@ pub async fn init_lnd_client() -> LndClient { /// /// This is useful for tests that need to pay invoices in regtest mode but /// should be skipped in other environments. -pub async fn pay_if_regtest(invoice: &Bolt11Invoice) -> Result<()> { +pub async fn pay_if_regtest(work_dir: &Path, invoice: &Bolt11Invoice) -> Result<()> { // Check if the invoice is for the regtest network if invoice.network() == bitcoin::Network::Regtest { - let lnd_client = init_lnd_client().await; + let lnd_client = init_lnd_client(work_dir).await; lnd_client.pay_invoice(invoice.to_string()).await?; Ok(()) } else { @@ -220,10 +231,10 @@ pub fn is_regtest_env() -> bool { /// /// Uses the is_regtest_env() function to determine whether to /// create a real regtest invoice or a fake one for testing. -pub async fn create_invoice_for_env(amount_sat: Option) -> Result { +pub async fn create_invoice_for_env(work_dir: &Path, amount_sat: Option) -> Result { if is_regtest_env() { // In regtest mode, create a real invoice - let lnd_client = init_lnd_client().await; + let lnd_client = init_lnd_client(work_dir).await; lnd_client .create_invoice(amount_sat) .await diff --git a/crates/cdk-integration-tests/src/shared.rs b/crates/cdk-integration-tests/src/shared.rs new file mode 100644 index 000000000..2657c1354 --- /dev/null +++ b/crates/cdk-integration-tests/src/shared.rs @@ -0,0 +1,266 @@ +//! Shared utilities for mint integration tests +//! +//! This module provides common functionality used across different +//! integration test binaries to reduce code duplication. + +use std::fs; +use std::path::{Path, PathBuf}; +use std::str::FromStr; +use std::sync::Arc; +use std::time::Duration; + +use anyhow::Result; +use cdk_axum::cache; +use tokio::signal; +use tokio::sync::Notify; + +use crate::cli::{init_logging, CommonArgs}; + +/// Default minimum mint amount for test mints +const DEFAULT_MIN_MINT: u64 = 1; +/// Default maximum mint amount for test mints +const DEFAULT_MAX_MINT: u64 = 500_000; +/// Default minimum melt amount for test mints +const DEFAULT_MIN_MELT: u64 = 1; +/// Default maximum melt amount for test mints +const DEFAULT_MAX_MELT: u64 = 500_000; + +/// Wait for mint to be ready by checking its info endpoint +pub async fn wait_for_mint_ready(port: u16, timeout_secs: u64) -> Result<()> { + let url = format!("http://127.0.0.1:{port}/v1/info"); + let start_time = std::time::Instant::now(); + + println!("Waiting for mint on port {port} to be ready..."); + + loop { + // Check if timeout has been reached + if start_time.elapsed().as_secs() > timeout_secs { + return Err(anyhow::anyhow!("Timeout waiting for mint on port {}", port)); + } + + // Try to make a request to the mint info endpoint + match reqwest::get(&url).await { + Ok(response) => { + if response.status().is_success() { + println!("Mint on port {port} is ready"); + return Ok(()); + } else { + println!( + "Mint on port {} returned status: {}", + port, + response.status() + ); + } + } + Err(e) => { + println!("Error connecting to mint on port {port}: {e}"); + } + } + + tokio::time::sleep(Duration::from_secs(2)).await; + } +} + +/// Initialize working directory +pub fn init_working_directory(work_dir: &str) -> Result { + let temp_dir = PathBuf::from_str(work_dir)?; + + // Create the temp directory if it doesn't exist + fs::create_dir_all(&temp_dir)?; + + Ok(temp_dir) +} + +/// Write environment variables to .env file +pub fn write_env_file(temp_dir: &Path, env_vars: &[(&str, &str)]) -> Result<()> { + let mut env_content = String::new(); + for (key, value) in env_vars { + env_content.push_str(&format!("{key}={value}\n")); + } + + let env_file_path = temp_dir.join(".env"); + + fs::write(&env_file_path, &env_content) + .map(|_| { + println!( + "Environment variables written to: {}", + env_file_path.display() + ); + }) + .map_err(|e| anyhow::anyhow!("Could not write .env file: {}", e)) +} + +/// Wait for .env file to be created +pub async fn wait_for_env_file(temp_dir: &Path, timeout_secs: u64) -> Result<()> { + let env_file_path = temp_dir.join(".env"); + let start_time = std::time::Instant::now(); + + println!( + "Waiting for .env file to be created at: {}", + env_file_path.display() + ); + + loop { + // Check if timeout has been reached + if start_time.elapsed().as_secs() > timeout_secs { + return Err(anyhow::anyhow!( + "Timeout waiting for .env file at {}", + env_file_path.display() + )); + } + + // Check if the file exists + if env_file_path.exists() { + println!(".env file found at: {}", env_file_path.display()); + return Ok(()); + } + + tokio::time::sleep(Duration::from_secs(1)).await; + } +} + +/// Setup common logging based on CLI arguments +pub fn setup_logging(common_args: &CommonArgs) { + init_logging(common_args.enable_logging, common_args.log_level); +} + +/// Create shutdown handler for graceful termination +pub fn create_shutdown_handler() -> Arc { + Arc::new(Notify::new()) +} + +/// Wait for Ctrl+C signal +pub async fn wait_for_shutdown_signal(shutdown: Arc) { + signal::ctrl_c() + .await + .expect("failed to install CTRL+C handler"); + + println!("\nReceived Ctrl+C, shutting down..."); + shutdown.notify_waiters(); +} + +/// Common mint information display +pub fn display_mint_info(port: u16, temp_dir: &Path, database_type: &str) { + println!("Mint started successfully!"); + println!("Mint URL: http://127.0.0.1:{port}"); + println!("Temp directory: {temp_dir:?}"); + println!("Database type: {database_type}"); +} + +/// Create settings for a fake wallet mint +pub fn create_fake_wallet_settings( + port: u16, + mnemonic: Option, + signatory_config: Option<(String, String)>, // (url, certs_dir) + fake_wallet_config: Option, +) -> cdk_mintd::config::Settings { + cdk_mintd::config::Settings { + info: cdk_mintd::config::Info { + url: format!("http://127.0.0.1:{port}"), + listen_host: "127.0.0.1".to_string(), + listen_port: port, + mnemonic, + signatory_url: signatory_config.as_ref().map(|(url, _)| url.clone()), + signatory_certs: signatory_config + .as_ref() + .map(|(_, certs_dir)| certs_dir.clone()), + input_fee_ppk: None, + http_cache: cache::Config::default(), + enable_swagger_ui: None, + }, + mint_info: cdk_mintd::config::MintInfo::default(), + ln: cdk_mintd::config::Ln { + ln_backend: cdk_mintd::config::LnBackend::FakeWallet, + invoice_description: None, + min_mint: DEFAULT_MIN_MINT.into(), + max_mint: DEFAULT_MAX_MINT.into(), + min_melt: DEFAULT_MIN_MELT.into(), + max_melt: DEFAULT_MAX_MELT.into(), + }, + cln: None, + lnbits: None, + lnd: None, + fake_wallet: fake_wallet_config, + grpc_processor: None, + database: cdk_mintd::config::Database::default(), + mint_management_rpc: None, + auth: None, + } +} + +/// Create settings for a CLN mint +pub fn create_cln_settings( + port: u16, + _cln_rpc_path: PathBuf, + mnemonic: String, + cln_config: cdk_mintd::config::Cln, +) -> cdk_mintd::config::Settings { + cdk_mintd::config::Settings { + info: cdk_mintd::config::Info { + url: format!("http://127.0.0.1:{port}"), + listen_host: "127.0.0.1".to_string(), + listen_port: port, + mnemonic: Some(mnemonic), + signatory_url: None, + signatory_certs: None, + input_fee_ppk: None, + http_cache: cache::Config::default(), + enable_swagger_ui: None, + }, + mint_info: cdk_mintd::config::MintInfo::default(), + ln: cdk_mintd::config::Ln { + ln_backend: cdk_mintd::config::LnBackend::Cln, + invoice_description: None, + min_mint: DEFAULT_MIN_MINT.into(), + max_mint: DEFAULT_MAX_MINT.into(), + min_melt: DEFAULT_MIN_MELT.into(), + max_melt: DEFAULT_MAX_MELT.into(), + }, + cln: Some(cln_config), + lnbits: None, + lnd: None, + fake_wallet: None, + grpc_processor: None, + database: cdk_mintd::config::Database::default(), + mint_management_rpc: None, + auth: None, + } +} + +/// Create settings for an LND mint +pub fn create_lnd_settings( + port: u16, + lnd_config: cdk_mintd::config::Lnd, + mnemonic: String, +) -> cdk_mintd::config::Settings { + cdk_mintd::config::Settings { + info: cdk_mintd::config::Info { + url: format!("http://127.0.0.1:{port}"), + listen_host: "127.0.0.1".to_string(), + listen_port: port, + mnemonic: Some(mnemonic), + signatory_url: None, + signatory_certs: None, + input_fee_ppk: None, + http_cache: cache::Config::default(), + enable_swagger_ui: None, + }, + mint_info: cdk_mintd::config::MintInfo::default(), + ln: cdk_mintd::config::Ln { + ln_backend: cdk_mintd::config::LnBackend::Lnd, + invoice_description: None, + min_mint: DEFAULT_MIN_MINT.into(), + max_mint: DEFAULT_MAX_MINT.into(), + min_melt: DEFAULT_MIN_MELT.into(), + max_melt: DEFAULT_MAX_MELT.into(), + }, + cln: None, + lnbits: None, + lnd: Some(lnd_config), + fake_wallet: None, + grpc_processor: None, + database: cdk_mintd::config::Database::default(), + mint_management_rpc: None, + auth: None, + } +} diff --git a/crates/cdk-integration-tests/tests/bolt12.rs b/crates/cdk-integration-tests/tests/bolt12.rs index fc2798854..2c6422569 100644 --- a/crates/cdk-integration-tests/tests/bolt12.rs +++ b/crates/cdk-integration-tests/tests/bolt12.rs @@ -1,3 +1,5 @@ +use std::env; +use std::path::PathBuf; use std::sync::Arc; use anyhow::{bail, Result}; @@ -6,11 +8,45 @@ use cashu::amount::SplitTarget; use cashu::nut23::Amountless; use cashu::{Amount, CurrencyUnit, MintRequest, PreMintSecrets, ProofsMethods}; use cdk::wallet::{HttpClient, MintConnector, Wallet}; -use cdk_integration_tests::init_regtest::get_cln_dir; +use cdk_integration_tests::init_regtest::{get_cln_dir, get_temp_dir}; use cdk_integration_tests::{get_mint_url_from_env, wait_for_mint_to_be_paid}; use cdk_sqlite::wallet::memory; use ln_regtest_rs::ln_client::ClnClient; +// Helper function to get temp directory from environment or fallback +fn get_test_temp_dir() -> PathBuf { + match env::var("CDK_ITESTS_DIR") { + Ok(dir) => PathBuf::from(dir), + Err(_) => get_temp_dir(), // fallback to default + } +} + +// Helper function to create CLN client with retries +async fn create_cln_client_with_retry(cln_dir: PathBuf) -> Result { + let mut retries = 0; + let max_retries = 10; + loop { + match ClnClient::new(cln_dir.clone(), None).await { + Ok(client) => return Ok(client), + Err(e) => { + retries += 1; + if retries >= max_retries { + bail!( + "Could not connect to CLN client after {} retries: {}", + max_retries, + e + ); + } + println!( + "Failed to connect to CLN (attempt {}/{}): {}. Retrying in 7 seconds...", + retries, max_retries, e + ); + tokio::time::sleep(tokio::time::Duration::from_secs(7)).await; + } + } + } +} + /// Tests basic BOLT12 minting functionality: /// - Creates a wallet /// - Gets a BOLT12 quote for a specific amount (100 sats) @@ -36,8 +72,11 @@ async fn test_regtest_bolt12_mint() { assert_eq!(mint_quote.amount, Some(mint_amount)); - let cln_one_dir = get_cln_dir("one"); - let cln_client = ClnClient::new(cln_one_dir.clone(), None).await.unwrap(); + let work_dir = get_test_temp_dir(); + let cln_one_dir = get_cln_dir(&work_dir, "one"); + let cln_client = create_cln_client_with_retry(cln_one_dir.clone()) + .await + .unwrap(); cln_client .pay_bolt12_offer(None, mint_quote.request) .await @@ -68,8 +107,9 @@ async fn test_regtest_bolt12_mint_multiple() -> Result<()> { let mint_quote = wallet.mint_bolt12_quote(None, None).await?; - let cln_one_dir = get_cln_dir("one"); - let cln_client = ClnClient::new(cln_one_dir.clone(), None).await?; + let work_dir = get_test_temp_dir(); + let cln_one_dir = get_cln_dir(&work_dir, "one"); + let cln_client = create_cln_client_with_retry(cln_one_dir.clone()).await?; cln_client .pay_bolt12_offer(Some(10000), mint_quote.request.clone()) .await @@ -131,8 +171,9 @@ async fn test_regtest_bolt12_multiple_wallets() -> Result<()> { )?; // Create a BOLT12 offer that both wallets will use - let cln_one_dir = get_cln_dir("one"); - let cln_client = ClnClient::new(cln_one_dir.clone(), None).await?; + let work_dir = get_test_temp_dir(); + let cln_one_dir = get_cln_dir(&work_dir, "one"); + let cln_client = create_cln_client_with_retry(cln_one_dir.clone()).await?; // First wallet payment let quote_one = wallet_one .mint_bolt12_quote(Some(10_000.into()), None) @@ -222,8 +263,9 @@ async fn test_regtest_bolt12_melt() -> Result<()> { assert_eq!(mint_quote.amount, Some(mint_amount)); // Pay the quote - let cln_one_dir = get_cln_dir("one"); - let cln_client = ClnClient::new(cln_one_dir.clone(), None).await?; + let work_dir = get_test_temp_dir(); + let cln_one_dir = get_cln_dir(&work_dir, "one"); + let cln_client = create_cln_client_with_retry(cln_one_dir.clone()).await?; cln_client .pay_bolt12_offer(None, mint_quote.request.clone()) .await?; @@ -281,8 +323,9 @@ async fn test_regtest_bolt12_mint_extra() -> Result<()> { let pay_amount_msats = 10_000; - let cln_one_dir = get_cln_dir("one"); - let cln_client = ClnClient::new(cln_one_dir.clone(), None).await?; + let work_dir = get_test_temp_dir(); + let cln_one_dir = get_cln_dir(&work_dir, "one"); + let cln_client = create_cln_client_with_retry(cln_one_dir.clone()).await?; cln_client .pay_bolt12_offer(Some(pay_amount_msats), mint_quote.request.clone()) .await?; diff --git a/crates/cdk-integration-tests/tests/fake_wallet.rs b/crates/cdk-integration-tests/tests/fake_wallet.rs index a48434630..1c185b72f 100644 --- a/crates/cdk-integration-tests/tests/fake_wallet.rs +++ b/crates/cdk-integration-tests/tests/fake_wallet.rs @@ -1,3 +1,19 @@ +//! Fake Wallet Integration Tests +//! +//! This file contains tests for the fake wallet backend functionality. +//! The fake wallet simulates Lightning Network behavior for testing purposes, +//! allowing verification of mint behavior in various payment scenarios without +//! requiring a real Lightning node. +//! +//! Test Scenarios: +//! - Pending payment states and proof handling +//! - Payment failure cases and proof state management +//! - Change output verification in melt operations +//! - Witness signature validation +//! - Cross-unit transaction validation +//! - Overflow and balance validation +//! - Duplicate proof detection + use std::sync::Arc; use bip39::Mnemonic; @@ -408,40 +424,6 @@ async fn test_fake_melt_change_in_quote() { assert_eq!(melt_change, check); } -/// Tests that the correct database type is used based on environment variables -#[tokio::test(flavor = "multi_thread", worker_threads = 1)] -async fn test_database_type() { - // Get the database type and work dir from environment - let db_type = std::env::var("CDK_MINTD_DATABASE").expect("MINT_DATABASE env var should be set"); - let work_dir = - std::env::var("CDK_MINTD_WORK_DIR").expect("CDK_MINTD_WORK_DIR env var should be set"); - - // Check that the correct database file exists - match db_type.as_str() { - "REDB" => { - let db_path = std::path::Path::new(&work_dir).join("cdk-mintd.redb"); - assert!( - db_path.exists(), - "Expected redb database file to exist at {:?}", - db_path - ); - } - "SQLITE" => { - let db_path = std::path::Path::new(&work_dir).join("cdk-mintd.sqlite"); - assert!( - db_path.exists(), - "Expected sqlite database file to exist at {:?}", - db_path - ); - } - "MEMORY" => { - // Memory database has no file to check - println!("Memory database in use - no file to check"); - } - _ => panic!("Unknown database type: {}", db_type), - } -} - /// Tests minting tokens with a valid witness signature #[tokio::test(flavor = "multi_thread", worker_threads = 1)] async fn test_fake_mint_with_witness() { diff --git a/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs b/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs index 5d42aff7b..96d79d82e 100644 --- a/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs +++ b/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs @@ -11,6 +11,7 @@ use core::panic; use std::env; use std::fmt::Debug; +use std::path::PathBuf; use std::str::FromStr; use std::sync::Arc; use std::time::Duration; @@ -32,6 +33,14 @@ use tokio::time::timeout; use tokio_tungstenite::connect_async; use tokio_tungstenite::tungstenite::protocol::Message; +// Helper function to get temp directory from environment or fallback +fn get_test_temp_dir() -> PathBuf { + match env::var("CDK_ITESTS_DIR") { + Ok(dir) => PathBuf::from(dir), + Err(_) => panic!("Unknown test dir"), + } +} + async fn get_notification> + Unpin, E: Debug>( reader: &mut T, timeout_to_wait: Duration, @@ -98,7 +107,9 @@ async fn test_happy_mint_melt_round_trip() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); let invoice = Bolt11Invoice::from_str(&mint_quote.request).unwrap(); - pay_if_regtest(&invoice).await.unwrap(); + pay_if_regtest(&get_test_temp_dir(), &invoice) + .await + .unwrap(); wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 10) .await @@ -113,7 +124,9 @@ async fn test_happy_mint_melt_round_trip() { assert!(mint_amount == 100.into()); - let invoice = create_invoice_for_env(Some(50)).await.unwrap(); + let invoice = create_invoice_for_env(&get_test_temp_dir(), Some(50)) + .await + .unwrap(); let melt = wallet.melt_quote(invoice, None).await.unwrap(); @@ -217,7 +230,9 @@ async fn test_happy_mint() { assert_eq!(mint_quote.amount, Some(mint_amount)); let invoice = Bolt11Invoice::from_str(&mint_quote.request).unwrap(); - pay_if_regtest(&invoice).await.unwrap(); + pay_if_regtest(&get_test_temp_dir(), &invoice) + .await + .unwrap(); wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60) .await @@ -262,7 +277,9 @@ async fn test_restore() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); let invoice = Bolt11Invoice::from_str(&mint_quote.request).unwrap(); - pay_if_regtest(&invoice).await.unwrap(); + pay_if_regtest(&get_test_temp_dir(), &invoice) + .await + .unwrap(); wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60) .await @@ -341,7 +358,7 @@ async fn test_fake_melt_change_in_quote() { let bolt11 = Bolt11Invoice::from_str(&mint_quote.request).unwrap(); - pay_if_regtest(&bolt11).await.unwrap(); + pay_if_regtest(&get_test_temp_dir(), &bolt11).await.unwrap(); wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60) .await @@ -352,7 +369,9 @@ async fn test_fake_melt_change_in_quote() { .await .unwrap(); - let invoice = create_invoice_for_env(Some(9)).await.unwrap(); + let invoice = create_invoice_for_env(&get_test_temp_dir(), Some(9)) + .await + .unwrap(); let proofs = wallet.get_unspent_proofs().await.unwrap(); @@ -408,7 +427,7 @@ async fn test_pay_invoice_twice() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - pay_if_regtest(&mint_quote.request.parse().unwrap()) + pay_if_regtest(&get_test_temp_dir(), &mint_quote.request.parse().unwrap()) .await .unwrap(); @@ -425,7 +444,9 @@ async fn test_pay_invoice_twice() { assert_eq!(mint_amount, 100.into()); - let invoice = create_invoice_for_env(Some(25)).await.unwrap(); + let invoice = create_invoice_for_env(&get_test_temp_dir(), Some(25)) + .await + .unwrap(); let melt_quote = wallet.melt_quote(invoice.clone(), None).await.unwrap(); diff --git a/crates/cdk-integration-tests/tests/integration_tests_pure.rs b/crates/cdk-integration-tests/tests/integration_tests_pure.rs index 7ed954b88..b98cd8a15 100644 --- a/crates/cdk-integration-tests/tests/integration_tests_pure.rs +++ b/crates/cdk-integration-tests/tests/integration_tests_pure.rs @@ -3,6 +3,11 @@ //! These tests verify the interaction between mint and wallet components, simulating real-world usage scenarios. //! They test the complete flow of operations including wallet funding, token swapping, sending tokens between wallets, //! and other operations that require client-mint interaction. +//! +//! Test Environment: +//! - Uses pure in-memory mint instances for fast execution +//! - Tests run concurrently with multi-threaded tokio runtime +//! - No external dependencies (Lightning nodes, databases) required use std::assert_eq; use std::collections::{HashMap, HashSet}; diff --git a/crates/cdk-integration-tests/tests/mint.rs b/crates/cdk-integration-tests/tests/mint.rs index da6fa8c88..3dd881ce8 100644 --- a/crates/cdk-integration-tests/tests/mint.rs +++ b/crates/cdk-integration-tests/tests/mint.rs @@ -1,8 +1,15 @@ -//! Mint tests +//! Mint Tests //! //! This file contains tests that focus on the mint's internal functionality without client interaction. //! These tests verify the mint's behavior in isolation, such as keyset management, database operations, //! and other mint-specific functionality that doesn't require wallet clients. +//! +//! Test Categories: +//! - Keyset rotation and management +//! - Database transaction handling +//! - Internal state transitions +//! - Fee calculation and enforcement +//! - Proof validation and state management use std::collections::{HashMap, HashSet}; use std::sync::Arc; diff --git a/crates/cdk-integration-tests/tests/regtest.rs b/crates/cdk-integration-tests/tests/regtest.rs index df80f1559..25fd33cbf 100644 --- a/crates/cdk-integration-tests/tests/regtest.rs +++ b/crates/cdk-integration-tests/tests/regtest.rs @@ -1,4 +1,20 @@ -use std::str::FromStr; +//! Regtest Integration Tests +//! +//! This file contains tests that run against actual Lightning Network nodes in regtest mode. +//! These tests require a local development environment with LND nodes configured for regtest. +//! +//! Test Environment Setup: +//! - Uses actual LND nodes connected to a regtest Bitcoin network +//! - Tests real Lightning payment flows including invoice creation and payment +//! - Verifies mint behavior with actual Lightning Network interactions +//! +//! Running Tests: +//! - Requires CDK_TEST_REGTEST=1 environment variable to be set +//! - Requires properly configured LND nodes with TLS certificates and macaroons +//! - Uses real Bitcoin transactions in regtest mode + +use std::env; +use std::path::PathBuf; use std::sync::Arc; use std::time::Duration; @@ -10,32 +26,46 @@ use cdk::nuts::{ NotificationPayload, PreMintSecrets, }; use cdk::wallet::{HttpClient, MintConnector, Wallet, WalletSubscription}; -use cdk_integration_tests::init_regtest::{ - get_cln_dir, get_lnd_cert_file_path, get_lnd_dir, get_lnd_macaroon_path, get_mint_port, - LND_RPC_ADDR, LND_TWO_RPC_ADDR, -}; +use cdk_integration_tests::init_regtest::{get_lnd_dir, LND_RPC_ADDR}; use cdk_integration_tests::{ get_mint_url_from_env, get_second_mint_url_from_env, wait_for_mint_to_be_paid, }; use cdk_sqlite::wallet::{self, memory}; use futures::join; -use lightning_invoice::Bolt11Invoice; -use ln_regtest_rs::ln_client::{ClnClient, LightningClient, LndClient}; -use ln_regtest_rs::InvoiceStatus; +use ln_regtest_rs::ln_client::{LightningClient, LndClient}; use tokio::time::timeout; // This is the ln wallet we use to send/receive ln payements as the wallet async fn init_lnd_client() -> LndClient { - let lnd_dir = get_lnd_dir("one"); + // Try to get the temp directory from environment variable first (from .env file) + let temp_dir = match env::var("CDK_ITESTS_DIR") { + Ok(dir) => { + let path = PathBuf::from(dir); + println!("Using temp directory from CDK_ITESTS_DIR: {:?}", path); + path + } + Err(_) => { + panic!("Unknown temp dir"); + } + }; + + // The LND mint uses the second LND node (LND_TWO_RPC_ADDR = localhost:10010) + let lnd_dir = get_lnd_dir(&temp_dir, "one"); let cert_file = lnd_dir.join("tls.cert"); let macaroon_file = lnd_dir.join("data/chain/bitcoin/regtest/admin.macaroon"); + + println!("Looking for LND cert file: {:?}", cert_file); + println!("Looking for LND macaroon file: {:?}", macaroon_file); + println!("Connecting to LND at: https://{}", LND_RPC_ADDR); + + // Connect to LND LndClient::new( format!("https://{}", LND_RPC_ADDR), - cert_file, - macaroon_file, + cert_file.clone(), + macaroon_file.clone(), ) .await - .unwrap() + .expect("Could not connect to lnd rpc") } #[tokio::test(flavor = "multi_thread", worker_threads = 1)] @@ -98,41 +128,41 @@ async fn test_internal_payment() { .await .unwrap(); - let check_paid = match get_mint_port("0") { - 8085 => { - let cln_one_dir = get_cln_dir("one"); - let cln_client = ClnClient::new(cln_one_dir.clone(), None).await.unwrap(); - - let payment_hash = Bolt11Invoice::from_str(&mint_quote.request).unwrap(); - cln_client - .check_incoming_payment_status(&payment_hash.payment_hash().to_string()) - .await - .expect("Could not check invoice") - } - 8087 => { - let lnd_two_dir = get_lnd_dir("two"); - let lnd_client = LndClient::new( - format!("https://{}", LND_TWO_RPC_ADDR), - get_lnd_cert_file_path(&lnd_two_dir), - get_lnd_macaroon_path(&lnd_two_dir), - ) - .await - .unwrap(); - let payment_hash = Bolt11Invoice::from_str(&mint_quote.request).unwrap(); - lnd_client - .check_incoming_payment_status(&payment_hash.payment_hash().to_string()) - .await - .expect("Could not check invoice") - } - _ => panic!("Unknown mint port"), - }; - - match check_paid { - InvoiceStatus::Unpaid => (), - _ => { - panic!("Invoice has incorrect status: {:?}", check_paid); - } - } + // let check_paid = match get_mint_port("0") { + // 8085 => { + // let cln_one_dir = get_cln_dir(&get_temp_dir(), "one"); + // let cln_client = ClnClient::new(cln_one_dir.clone(), None).await.unwrap(); + + // let payment_hash = Bolt11Invoice::from_str(&mint_quote.request).unwrap(); + // cln_client + // .check_incoming_payment_status(&payment_hash.payment_hash().to_string()) + // .await + // .expect("Could not check invoice") + // } + // 8087 => { + // let lnd_two_dir = get_lnd_dir(&get_temp_dir(), "two"); + // let lnd_client = LndClient::new( + // format!("https://{}", LND_TWO_RPC_ADDR), + // get_lnd_cert_file_path(&lnd_two_dir), + // get_lnd_macaroon_path(&lnd_two_dir), + // ) + // .await + // .unwrap(); + // let payment_hash = Bolt11Invoice::from_str(&mint_quote.request).unwrap(); + // lnd_client + // .check_incoming_payment_status(&payment_hash.payment_hash().to_string()) + // .await + // .expect("Could not check invoice") + // } + // _ => panic!("Unknown mint port"), + // }; + + // match check_paid { + // InvoiceStatus::Unpaid => (), + // _ => { + // panic!("Invoice has incorrect status: {:?}", check_paid); + // } + // } let wallet_2_balance = wallet_2.total_balance().await.unwrap(); diff --git a/crates/cdk-integration-tests/tests/test_fees.rs b/crates/cdk-integration-tests/tests/test_fees.rs index 1433030a5..f4d30ded0 100644 --- a/crates/cdk-integration-tests/tests/test_fees.rs +++ b/crates/cdk-integration-tests/tests/test_fees.rs @@ -6,6 +6,7 @@ use cashu::{Bolt11Invoice, ProofsMethods}; use cdk::amount::{Amount, SplitTarget}; use cdk::nuts::CurrencyUnit; use cdk::wallet::{ReceiveOptions, SendKind, SendOptions, Wallet}; +use cdk_integration_tests::init_regtest::get_temp_dir; use cdk_integration_tests::{ create_invoice_for_env, get_mint_url_from_env, pay_if_regtest, wait_for_mint_to_be_paid, }; @@ -26,7 +27,7 @@ async fn test_swap() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); let invoice = Bolt11Invoice::from_str(&mint_quote.request).unwrap(); - pay_if_regtest(&invoice).await.unwrap(); + pay_if_regtest(&get_temp_dir(), &invoice).await.unwrap(); wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 10) .await @@ -93,7 +94,7 @@ async fn test_fake_melt_change_in_quote() { let bolt11 = Bolt11Invoice::from_str(&mint_quote.request).unwrap(); - pay_if_regtest(&bolt11).await.unwrap(); + pay_if_regtest(&get_temp_dir(), &bolt11).await.unwrap(); wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60) .await @@ -106,7 +107,9 @@ async fn test_fake_melt_change_in_quote() { let invoice_amount = 9; - let invoice = create_invoice_for_env(Some(invoice_amount)).await.unwrap(); + let invoice = create_invoice_for_env(&get_temp_dir(), Some(invoice_amount)) + .await + .unwrap(); let melt_quote = wallet.melt_quote(invoice.to_string(), None).await.unwrap(); diff --git a/crates/cdk-mint-rpc/Cargo.toml b/crates/cdk-mint-rpc/Cargo.toml index 810ac0c0b..9f3ed0893 100644 --- a/crates/cdk-mint-rpc/Cargo.toml +++ b/crates/cdk-mint-rpc/Cargo.toml @@ -23,7 +23,7 @@ anyhow.workspace = true cdk = { workspace = true, features = [ "mint", ] } -cdk-common = { workspace = true } +cdk-common.workspace = true clap.workspace = true tonic = { workspace = true, features = ["transport"] } tracing.workspace = true diff --git a/crates/cdk-mint-rpc/src/bin/mint_rpc_cli.rs b/crates/cdk-mint-rpc/src/bin/mint_rpc_cli.rs index f7a619429..293ae6343 100644 --- a/crates/cdk-mint-rpc/src/bin/mint_rpc_cli.rs +++ b/crates/cdk-mint-rpc/src/bin/mint_rpc_cli.rs @@ -7,22 +7,55 @@ use cdk_mint_rpc::GetInfoRequest; use clap::{Parser, Subcommand}; use tonic::transport::{Certificate, Channel, ClientTlsConfig, Identity}; use tonic::Request; -use tracing::Level; use tracing_subscriber::EnvFilter; +/// Common CLI arguments for CDK binaries +#[derive(Parser, Debug)] +pub struct CommonArgs { + /// Enable logging (default is false) + #[arg(long, default_value_t = false)] + pub enable_logging: bool, + + /// Logging level when enabled (default is debug) + #[arg(long, default_value = "debug")] + pub log_level: tracing::Level, +} + +/// Initialize logging based on CLI arguments +pub fn init_logging(enable_logging: bool, log_level: tracing::Level) { + if enable_logging { + let default_filter = log_level.to_string(); + + // Common filters to reduce noise + let sqlx_filter = "sqlx=warn"; + let hyper_filter = "hyper=warn"; + let h2_filter = "h2=warn"; + let rustls_filter = "rustls=warn"; + let reqwest_filter = "reqwest=warn"; + + let env_filter = EnvFilter::new(format!( + "{default_filter},{sqlx_filter},{hyper_filter},{h2_filter},{rustls_filter},{reqwest_filter}" + )); + + // Ok if successful, Err if already initialized + let _ = tracing_subscriber::fmt() + .with_env_filter(env_filter) + .try_init(); + } +} + const DEFAULT_WORK_DIR: &str = ".cdk-mint-rpc-cli"; #[derive(Parser)] #[command(version, about, long_about = None)] struct Cli { + #[command(flatten)] + common: CommonArgs, + /// Address of RPC server #[arg(short, long, default_value = "https://127.0.0.1:8086")] addr: String, - /// Logging level - #[arg(short, long, default_value = "debug")] - log_level: Level, - /// Path to working dir #[arg(short, long)] work_dir: Option, @@ -70,14 +103,9 @@ enum Commands { #[tokio::main] async fn main() -> Result<()> { let args: Cli = Cli::parse(); - let default_filter = args.log_level; - - let sqlx_filter = "sqlx=warn,hyper_util=warn,reqwest=warn"; - - let env_filter = EnvFilter::new(format!("{default_filter},{sqlx_filter}")); - // Parse input - tracing_subscriber::fmt().with_env_filter(env_filter).init(); + // Initialize logging based on CLI arguments + init_logging(args.common.enable_logging, args.common.log_level); let cli = Cli::parse(); diff --git a/crates/cdk-mintd/src/cli.rs b/crates/cdk-mintd/src/cli.rs index 20d07086f..9da08831f 100644 --- a/crates/cdk-mintd/src/cli.rs +++ b/crates/cdk-mintd/src/cli.rs @@ -24,4 +24,12 @@ pub struct CLIArgs { pub config: Option, #[arg(short, long, help = "Recover Greenlight from seed", required = false)] pub recover: Option, + #[arg( + long, + help = "Enable logging output", + required = false, + action = clap::ArgAction::SetTrue, + default_value = "true" + )] + pub enable_logging: bool, } diff --git a/crates/cdk-mintd/src/lib.rs b/crates/cdk-mintd/src/lib.rs index a8268fd94..86adbf1b4 100644 --- a/crates/cdk-mintd/src/lib.rs +++ b/crates/cdk-mintd/src/lib.rs @@ -1,13 +1,66 @@ //! Cdk mintd lib -#[cfg(feature = "cln")] -use std::path::PathBuf; +// std +#[cfg(feature = "auth")] +use std::collections::HashMap; +use std::env; +use std::net::SocketAddr; +use std::path::{Path, PathBuf}; +use std::str::FromStr; +use std::sync::Arc; + +// external crates +use anyhow::{anyhow, bail, Result}; +use axum::Router; +use bip39::Mnemonic; +// internal crate modules +use cdk::cdk_database::{self, MintDatabase, MintKeysDatabase}; +use cdk::cdk_payment; +use cdk::cdk_payment::MintPayment; +use cdk::mint::{Mint, MintBuilder, MintMeltLimits}; +#[cfg(any( + feature = "cln", + feature = "lnbits", + feature = "lnd", + feature = "fakewallet", + feature = "grpc-processor" +))] +use cdk::nuts::nut17::SupportedMethods; +use cdk::nuts::nut19::{CachedEndpoint, Method as NUT19Method, Path as NUT19Path}; +#[cfg(any( + feature = "cln", + feature = "lnbits", + feature = "lnd", + feature = "fakewallet" +))] +use cdk::nuts::CurrencyUnit; +#[cfg(feature = "auth")] +use cdk::nuts::{AuthRequired, Method, ProtectedEndpoint, RoutePath}; +use cdk::nuts::{ContactInfo, MintVersion, PaymentMethod}; +use cdk::types::QuoteTTL; +use cdk_axum::cache::HttpCache; +#[cfg(feature = "auth")] +use cdk_sqlite::mint::MintSqliteAuthDatabase; +use cdk_sqlite::MintSqliteDatabase; +use cli::CLIArgs; +use config::{DatabaseEngine, LnBackend}; +use env_vars::ENV_WORK_DIR; +use setup::LnBackendSetup; +use tower::ServiceBuilder; +use tower_http::compression::CompressionLayer; +use tower_http::decompression::RequestDecompressionLayer; +use tower_http::trace::TraceLayer; +use tracing_subscriber::EnvFilter; +#[cfg(feature = "swagger")] +use utoipa::OpenApi; pub mod cli; pub mod config; pub mod env_vars; pub mod setup; +const CARGO_PKG_VERSION: Option<&'static str> = option_env!("CARGO_PKG_VERSION"); + #[cfg(feature = "cln")] fn expand_path(path: &str) -> Option { if path.starts_with('~') { @@ -23,3 +76,751 @@ fn expand_path(path: &str) -> Option { Some(PathBuf::from(path)) } } + +/// Performs the initial setup for the application, including configuring tracing, +/// parsing CLI arguments, setting up the working directory, loading settings, +/// and initializing the database connection. +async fn initial_setup( + work_dir: &Path, + settings: &config::Settings, + db_password: Option, +) -> Result<( + Arc + Send + Sync>, + Arc + Send + Sync>, +)> { + let (localstore, keystore) = setup_database(settings, work_dir, db_password).await?; + Ok((localstore, keystore)) +} + +/// Sets up and initializes a tracing subscriber with custom log filtering. +pub fn setup_tracing() { + let default_filter = "debug"; + let hyper_filter = "hyper=warn"; + let h2_filter = "h2=warn"; + let tower_http = "tower_http=warn"; + + let env_filter = EnvFilter::new(format!( + "{default_filter},{hyper_filter},{h2_filter},{tower_http}" + )); + + tracing_subscriber::fmt().with_env_filter(env_filter).init(); +} + +/// Retrieves the work directory based on command-line arguments, environment variables, or system defaults. +pub async fn get_work_directory(args: &CLIArgs) -> Result { + let work_dir = if let Some(work_dir) = &args.work_dir { + tracing::info!("Using work dir from cmd arg"); + work_dir.clone() + } else if let Ok(env_work_dir) = env::var(ENV_WORK_DIR) { + tracing::info!("Using work dir from env var"); + env_work_dir.into() + } else { + work_dir()? + }; + tracing::info!("Using work dir: {}", work_dir.display()); + Ok(work_dir) +} + +/// Loads the application settings based on a configuration file and environment variables. +pub fn load_settings(work_dir: &Path, config_path: Option) -> Result { + // get config file name from args + let config_file_arg = match config_path { + Some(c) => c, + None => work_dir.join("config.toml"), + }; + + let mut settings = if config_file_arg.exists() { + config::Settings::new(Some(config_file_arg)) + } else { + tracing::info!("Config file does not exist. Attempting to read env vars"); + config::Settings::default() + }; + + // This check for any settings defined in ENV VARs + // ENV VARS will take **priority** over those in the config + settings.from_env() +} + +async fn setup_database( + settings: &config::Settings, + work_dir: &Path, + db_password: Option, +) -> Result<( + Arc + Send + Sync>, + Arc + Send + Sync>, +)> { + match settings.database.engine { + DatabaseEngine::Sqlite => { + let db = setup_sqlite_database(work_dir, db_password).await?; + let localstore: Arc + Send + Sync> = db.clone(); + let keystore: Arc + Send + Sync> = db; + Ok((localstore, keystore)) + } + } +} + +async fn setup_sqlite_database( + work_dir: &Path, + _password: Option, +) -> Result> { + let sql_db_path = work_dir.join("cdk-mintd.sqlite"); + + #[cfg(not(feature = "sqlcipher"))] + let db = MintSqliteDatabase::new(&sql_db_path).await?; + #[cfg(feature = "sqlcipher")] + let db = { + // Get password from command line arguments for sqlcipher + MintSqliteDatabase::new((sql_db_path, _password.unwrap())).await? + }; + + Ok(Arc::new(db)) +} + +/** + * Configures a `MintBuilder` instance with provided settings and initializes + * routers for Lightning Network backends. + */ +async fn configure_mint_builder( + settings: &config::Settings, + mint_builder: MintBuilder, +) -> Result<(MintBuilder, Vec)> { + let mut ln_routers = vec![]; + + // Configure basic mint information + let mint_builder = configure_basic_info(settings, mint_builder); + + // Configure lightning backend + let mint_builder = configure_lightning_backend(settings, mint_builder, &mut ln_routers).await?; + + // Configure caching + let mint_builder = configure_cache(settings, mint_builder); + + Ok((mint_builder, ln_routers)) +} + +/// Configures basic mint information (name, contact info, descriptions, etc.) +fn configure_basic_info(settings: &config::Settings, mint_builder: MintBuilder) -> MintBuilder { + // Add contact information + let mut contacts = Vec::new(); + if let Some(nostr_key) = &settings.mint_info.contact_nostr_public_key { + contacts.push(ContactInfo::new("nostr".to_string(), nostr_key.to_string())); + } + if let Some(email) = &settings.mint_info.contact_email { + contacts.push(ContactInfo::new("email".to_string(), email.to_string())); + } + + // Add version information + let mint_version = MintVersion::new( + "cdk-mintd".to_string(), + CARGO_PKG_VERSION.unwrap_or("Unknown").to_string(), + ); + + // Configure mint builder with basic info + let mut builder = mint_builder + .with_name(settings.mint_info.name.clone()) + .with_version(mint_version) + .with_description(settings.mint_info.description.clone()); + + // Add optional information + if let Some(long_description) = &settings.mint_info.description_long { + builder = builder.with_long_description(long_description.to_string()); + } + + for contact in contacts { + builder = builder.with_contact_info(contact); + } + + if let Some(pubkey) = settings.mint_info.pubkey { + builder = builder.with_pubkey(pubkey); + } + + if let Some(icon_url) = &settings.mint_info.icon_url { + builder = builder.with_icon_url(icon_url.to_string()); + } + + if let Some(motd) = &settings.mint_info.motd { + builder = builder.with_motd(motd.to_string()); + } + + if let Some(tos_url) = &settings.mint_info.tos_url { + builder = builder.with_tos_url(tos_url.to_string()); + } + + builder +} +/// Configures Lightning Network backend based on the specified backend type +async fn configure_lightning_backend( + settings: &config::Settings, + mut mint_builder: MintBuilder, + ln_routers: &mut Vec, +) -> Result { + let mint_melt_limits = MintMeltLimits { + mint_min: settings.ln.min_mint, + mint_max: settings.ln.max_mint, + melt_min: settings.ln.min_melt, + melt_max: settings.ln.max_melt, + }; + + tracing::debug!("Ln backend: {:?}", settings.ln.ln_backend); + + match settings.ln.ln_backend { + #[cfg(feature = "cln")] + LnBackend::Cln => { + let cln_settings = settings + .cln + .clone() + .expect("Config checked at load that cln is some"); + let cln = cln_settings + .setup(ln_routers, settings, CurrencyUnit::Msat) + .await?; + + mint_builder = configure_backend_for_unit( + settings, + mint_builder, + CurrencyUnit::Sat, + mint_melt_limits, + Arc::new(cln), + ) + .await?; + } + #[cfg(feature = "lnbits")] + LnBackend::LNbits => { + let lnbits_settings = settings.clone().lnbits.expect("Checked on config load"); + let lnbits = lnbits_settings + .setup(ln_routers, settings, CurrencyUnit::Sat) + .await?; + + mint_builder = configure_backend_for_unit( + settings, + mint_builder, + CurrencyUnit::Sat, + mint_melt_limits, + Arc::new(lnbits), + ) + .await?; + } + #[cfg(feature = "lnd")] + LnBackend::Lnd => { + let lnd_settings = settings.clone().lnd.expect("Checked at config load"); + let lnd = lnd_settings + .setup(ln_routers, settings, CurrencyUnit::Msat) + .await?; + + mint_builder = configure_backend_for_unit( + settings, + mint_builder, + CurrencyUnit::Sat, + mint_melt_limits, + Arc::new(lnd), + ) + .await?; + } + #[cfg(feature = "fakewallet")] + LnBackend::FakeWallet => { + let fake_wallet = settings.clone().fake_wallet.expect("Fake wallet defined"); + tracing::info!("Using fake wallet: {:?}", fake_wallet); + + for unit in fake_wallet.clone().supported_units { + let fake = fake_wallet + .setup(ln_routers, settings, CurrencyUnit::Sat) + .await?; + + mint_builder = configure_backend_for_unit( + settings, + mint_builder, + unit.clone(), + mint_melt_limits, + Arc::new(fake), + ) + .await?; + } + } + #[cfg(feature = "grpc-processor")] + LnBackend::GrpcProcessor => { + let grpc_processor = settings + .clone() + .grpc_processor + .expect("grpc processor config defined"); + + tracing::info!( + "Attempting to start with gRPC payment processor at {}:{}.", + grpc_processor.addr, + grpc_processor.port + ); + + for unit in grpc_processor.clone().supported_units { + tracing::debug!("Adding unit: {:?}", unit); + let processor = grpc_processor + .setup(ln_routers, settings, unit.clone()) + .await?; + + mint_builder = configure_backend_for_unit( + settings, + mint_builder, + unit.clone(), + mint_melt_limits, + Arc::new(processor), + ) + .await?; + } + } + LnBackend::None => { + tracing::error!( + "Payment backend was not set or feature disabled. {:?}", + settings.ln.ln_backend + ); + bail!("Lightning backend must be configured"); + } + }; + + Ok(mint_builder) +} + +/// Helper function to configure a mint builder with a lightning backend for a specific currency unit +async fn configure_backend_for_unit( + settings: &config::Settings, + mut mint_builder: MintBuilder, + unit: cdk::nuts::CurrencyUnit, + mint_melt_limits: MintMeltLimits, + backend: Arc + Send + Sync>, +) -> Result { + let payment_settings = backend.get_settings().await?; + + if let Some(bolt12) = payment_settings.get("bolt12") { + if bolt12.as_bool().unwrap_or_default() { + mint_builder + .add_payment_processor( + unit.clone(), + PaymentMethod::Bolt12, + mint_melt_limits, + Arc::clone(&backend), + ) + .await?; + } + } + + mint_builder + .add_payment_processor( + unit.clone(), + PaymentMethod::Bolt11, + mint_melt_limits, + backend, + ) + .await?; + + if let Some(input_fee) = settings.info.input_fee_ppk { + mint_builder.set_unit_fee(&unit, input_fee)?; + } + + let nut17_supported = SupportedMethods::default_bolt11(unit); + mint_builder = mint_builder.with_supported_websockets(nut17_supported); + + Ok(mint_builder) +} + +/// Configures cache settings +fn configure_cache(settings: &config::Settings, mint_builder: MintBuilder) -> MintBuilder { + let cached_endpoints = vec![ + CachedEndpoint::new(NUT19Method::Post, NUT19Path::MintBolt11), + CachedEndpoint::new(NUT19Method::Post, NUT19Path::MeltBolt11), + CachedEndpoint::new(NUT19Method::Post, NUT19Path::Swap), + ]; + + let cache: HttpCache = settings.info.http_cache.clone().into(); + mint_builder.with_cache(Some(cache.ttl.as_secs()), cached_endpoints) +} + +#[cfg(feature = "auth")] +async fn setup_authentication( + settings: &config::Settings, + work_dir: &Path, + mut mint_builder: MintBuilder, + _password: Option, +) -> Result { + if let Some(auth_settings) = settings.auth.clone() { + tracing::info!("Auth settings are defined. {:?}", auth_settings); + let auth_localstore: Arc< + dyn cdk_database::MintAuthDatabase + Send + Sync, + > = match settings.database.engine { + DatabaseEngine::Sqlite => { + let sql_db_path = work_dir.join("cdk-mintd-auth.sqlite"); + #[cfg(not(feature = "sqlcipher"))] + let sqlite_db = MintSqliteAuthDatabase::new(&sql_db_path).await?; + #[cfg(feature = "sqlcipher")] + let sqlite_db = { + // Get password from command line arguments for sqlcipher + MintSqliteAuthDatabase::new((sql_db_path, _password.unwrap())).await? + }; + + Arc::new(sqlite_db) + } + }; + + let mint_blind_auth_endpoint = + ProtectedEndpoint::new(Method::Post, RoutePath::MintBlindAuth); + + let mut protected_endpoints = HashMap::new(); + + protected_endpoints.insert(mint_blind_auth_endpoint, AuthRequired::Clear); + + let mut blind_auth_endpoints = vec![]; + let mut unprotected_endpoints = vec![]; + + { + let mint_quote_protected_endpoint = + ProtectedEndpoint::new(Method::Post, RoutePath::MintQuoteBolt11); + let mint_protected_endpoint = + ProtectedEndpoint::new(Method::Post, RoutePath::MintBolt11); + if auth_settings.enabled_mint { + protected_endpoints.insert(mint_quote_protected_endpoint, AuthRequired::Blind); + + protected_endpoints.insert(mint_protected_endpoint, AuthRequired::Blind); + + blind_auth_endpoints.push(mint_quote_protected_endpoint); + blind_auth_endpoints.push(mint_protected_endpoint); + } else { + unprotected_endpoints.push(mint_protected_endpoint); + unprotected_endpoints.push(mint_quote_protected_endpoint); + } + } + + { + let melt_quote_protected_endpoint = + ProtectedEndpoint::new(Method::Post, RoutePath::MeltQuoteBolt11); + let melt_protected_endpoint = + ProtectedEndpoint::new(Method::Post, RoutePath::MeltBolt11); + + if auth_settings.enabled_melt { + protected_endpoints.insert(melt_quote_protected_endpoint, AuthRequired::Blind); + protected_endpoints.insert(melt_protected_endpoint, AuthRequired::Blind); + + blind_auth_endpoints.push(melt_quote_protected_endpoint); + blind_auth_endpoints.push(melt_protected_endpoint); + } else { + unprotected_endpoints.push(melt_quote_protected_endpoint); + unprotected_endpoints.push(melt_protected_endpoint); + } + } + + { + let swap_protected_endpoint = ProtectedEndpoint::new(Method::Post, RoutePath::Swap); + + if auth_settings.enabled_swap { + protected_endpoints.insert(swap_protected_endpoint, AuthRequired::Blind); + blind_auth_endpoints.push(swap_protected_endpoint); + } else { + unprotected_endpoints.push(swap_protected_endpoint); + } + } + + { + let check_mint_protected_endpoint = + ProtectedEndpoint::new(Method::Get, RoutePath::MintQuoteBolt11); + + if auth_settings.enabled_check_mint_quote { + protected_endpoints.insert(check_mint_protected_endpoint, AuthRequired::Blind); + blind_auth_endpoints.push(check_mint_protected_endpoint); + } else { + unprotected_endpoints.push(check_mint_protected_endpoint); + } + } + + { + let check_melt_protected_endpoint = + ProtectedEndpoint::new(Method::Get, RoutePath::MeltQuoteBolt11); + + if auth_settings.enabled_check_melt_quote { + protected_endpoints.insert(check_melt_protected_endpoint, AuthRequired::Blind); + blind_auth_endpoints.push(check_melt_protected_endpoint); + } else { + unprotected_endpoints.push(check_melt_protected_endpoint); + } + } + + { + let restore_protected_endpoint = + ProtectedEndpoint::new(Method::Post, RoutePath::Restore); + + if auth_settings.enabled_restore { + protected_endpoints.insert(restore_protected_endpoint, AuthRequired::Blind); + blind_auth_endpoints.push(restore_protected_endpoint); + } else { + unprotected_endpoints.push(restore_protected_endpoint); + } + } + + { + let state_protected_endpoint = + ProtectedEndpoint::new(Method::Post, RoutePath::Checkstate); + + if auth_settings.enabled_check_proof_state { + protected_endpoints.insert(state_protected_endpoint, AuthRequired::Blind); + blind_auth_endpoints.push(state_protected_endpoint); + } else { + unprotected_endpoints.push(state_protected_endpoint); + } + } + + mint_builder = mint_builder.with_auth( + auth_localstore.clone(), + auth_settings.openid_discovery, + auth_settings.openid_client_id, + vec![mint_blind_auth_endpoint], + ); + mint_builder = + mint_builder.with_blind_auth(auth_settings.mint_max_bat, blind_auth_endpoints); + + let mut tx = auth_localstore.begin_transaction().await?; + + tx.remove_protected_endpoints(unprotected_endpoints).await?; + tx.add_protected_endpoints(protected_endpoints).await?; + tx.commit().await?; + } + Ok(mint_builder) +} + +/// Build mints with the configured the signing method (remote signatory or local seed) +async fn build_mint( + settings: &config::Settings, + keystore: Arc + Send + Sync>, + mint_builder: MintBuilder, +) -> Result { + if let Some(signatory_url) = settings.info.signatory_url.clone() { + tracing::info!( + "Connecting to remote signatory to {} with certs {:?}", + signatory_url, + settings.info.signatory_certs.clone() + ); + + Ok(mint_builder + .build_with_signatory(Arc::new( + cdk_signatory::SignatoryRpcClient::new( + signatory_url, + settings.info.signatory_certs.clone(), + ) + .await?, + )) + .await?) + } else if let Some(mnemonic) = settings + .info + .mnemonic + .clone() + .map(|s| Mnemonic::from_str(&s)) + .transpose()? + { + Ok(mint_builder + .build_with_seed(keystore, &mnemonic.to_seed_normalized("")) + .await?) + } else { + bail!("No seed nor remote signatory set"); + } +} + +async fn start_services_with_shutdown( + mint: Arc, + settings: &config::Settings, + ln_routers: Vec, + work_dir: &Path, + mint_builder_info: cdk::nuts::MintInfo, + shutdown_signal: impl std::future::Future + Send + 'static, +) -> Result<()> { + let listen_addr = settings.info.listen_host.clone(); + let listen_port = settings.info.listen_port; + let cache: HttpCache = settings.info.http_cache.clone().into(); + + #[cfg(feature = "management-rpc")] + let mut rpc_enabled = false; + #[cfg(not(feature = "management-rpc"))] + let rpc_enabled = false; + + #[cfg(feature = "management-rpc")] + let mut rpc_server: Option = None; + + #[cfg(feature = "management-rpc")] + { + if let Some(rpc_settings) = settings.mint_management_rpc.clone() { + if rpc_settings.enabled { + let addr = rpc_settings.address.unwrap_or("127.0.0.1".to_string()); + let port = rpc_settings.port.unwrap_or(8086); + let mut mint_rpc = cdk_mint_rpc::MintRPCServer::new(&addr, port, mint.clone())?; + + let tls_dir = rpc_settings.tls_dir_path.unwrap_or(work_dir.join("tls")); + + if !tls_dir.exists() { + tracing::error!("TLS directory does not exist: {}", tls_dir.display()); + bail!("Cannot start RPC server: TLS directory does not exist"); + } + + mint_rpc.start(Some(tls_dir)).await?; + + rpc_server = Some(mint_rpc); + + rpc_enabled = true; + } + } + } + + if rpc_enabled { + if mint.mint_info().await.is_err() { + tracing::info!("Mint info not set on mint, setting."); + mint.set_mint_info(mint_builder_info).await?; + mint.set_quote_ttl(QuoteTTL::new(10_000, 10_000)).await?; + } else { + if mint.localstore().get_quote_ttl().await.is_err() { + mint.set_quote_ttl(QuoteTTL::new(10_000, 10_000)).await?; + } + // Add version information + let mint_version = MintVersion::new( + "cdk-mintd".to_string(), + CARGO_PKG_VERSION.unwrap_or("Unknown").to_string(), + ); + let mut stored_mint_info = mint.mint_info().await?; + stored_mint_info.version = Some(mint_version); + mint.set_mint_info(stored_mint_info).await?; + + tracing::info!("Mint info already set, not using config file settings."); + } + } else { + tracing::warn!("RPC not enabled, using mint info from config."); + mint.set_mint_info(mint_builder_info).await?; + mint.set_quote_ttl(QuoteTTL::new(10_000, 10_000)).await?; + } + + let mint_info = mint.mint_info().await?; + let nut04_methods = mint_info.nuts.nut04.supported_methods(); + let nut05_methods = mint_info.nuts.nut05.supported_methods(); + + let bolt12_supported = nut04_methods.contains(&&PaymentMethod::Bolt12) + || nut05_methods.contains(&&PaymentMethod::Bolt12); + + let v1_service = + cdk_axum::create_mint_router_with_custom_cache(Arc::clone(&mint), cache, bolt12_supported) + .await?; + + let mut mint_service = Router::new() + .merge(v1_service) + .layer( + ServiceBuilder::new() + .layer(RequestDecompressionLayer::new()) + .layer(CompressionLayer::new()), + ) + .layer(TraceLayer::new_for_http()); + + #[cfg(feature = "swagger")] + { + if settings.info.enable_swagger_ui.unwrap_or(false) { + mint_service = mint_service.merge( + utoipa_swagger_ui::SwaggerUi::new("/swagger-ui") + .url("/api-docs/openapi.json", cdk_axum::ApiDoc::openapi()), + ); + } + } + + for router in ln_routers { + mint_service = mint_service.merge(router); + } + + mint.start().await?; + + let socket_addr = SocketAddr::from_str(&format!("{listen_addr}:{listen_port}"))?; + + let listener = tokio::net::TcpListener::bind(socket_addr).await?; + + tracing::debug!("listening on {}", listener.local_addr().unwrap()); + + // Wait for axum server to complete with custom shutdown signal + let axum_result = axum::serve(listener, mint_service).with_graceful_shutdown(shutdown_signal); + + match axum_result.await { + Ok(_) => { + tracing::info!("Axum server stopped with okay status"); + } + Err(err) => { + tracing::warn!("Axum server stopped with error"); + tracing::error!("{}", err); + bail!("Axum exited with error") + } + } + + mint.stop().await?; + + #[cfg(feature = "management-rpc")] + { + if let Some(rpc_server) = rpc_server { + rpc_server.stop().await?; + } + } + + Ok(()) +} + +async fn shutdown_signal() { + tokio::signal::ctrl_c() + .await + .expect("failed to install CTRL+C handler"); + tracing::info!("Shutdown signal received"); +} + +fn work_dir() -> Result { + let home_dir = home::home_dir().ok_or(anyhow!("Unknown home dir"))?; + let dir = home_dir.join(".cdk-mintd"); + + std::fs::create_dir_all(&dir)?; + + Ok(dir) +} + +/// The main entry point for the application when used as a library. +/// +/// This asynchronous function performs the following steps: +/// 1. Executes the initial setup, including loading configurations and initializing the database. +/// 2. Configures a `MintBuilder` instance with the local store and keystore based on the database. +/// 3. Applies additional custom configurations and authentication setup for the `MintBuilder`. +/// 4. Constructs a `Mint` instance from the configured `MintBuilder`. +/// 5. Checks and resolves the status of any pending mint and melt quotes. +pub async fn run_mintd( + work_dir: &Path, + settings: &config::Settings, + db_password: Option, +) -> Result<()> { + run_mintd_with_shutdown(work_dir, settings, shutdown_signal(), db_password).await +} + +/// Run mintd with a custom shutdown signal +pub async fn run_mintd_with_shutdown( + work_dir: &Path, + settings: &config::Settings, + shutdown_signal: impl std::future::Future + Send + 'static, + db_password: Option, +) -> Result<()> { + let (localstore, keystore) = initial_setup(work_dir, settings, db_password.clone()).await?; + + let mint_builder = MintBuilder::new(localstore); + + let (mint_builder, ln_routers) = configure_mint_builder(settings, mint_builder).await?; + #[cfg(feature = "auth")] + let mint_builder = setup_authentication(settings, work_dir, mint_builder, db_password).await?; + + let mint = build_mint(settings, keystore, mint_builder).await?; + + tracing::debug!("Mint built from builder."); + + let mint = Arc::new(mint); + + // Checks the status of all pending melt quotes + // Pending melt quotes where the payment has gone through inputs are burnt + // Pending melt quotes where the payment has **failed** inputs are reset to unspent + mint.check_pending_melt_quotes().await?; + + start_services_with_shutdown( + mint.clone(), + settings, + ln_routers, + work_dir, + mint.mint_info().await?, + shutdown_signal, + ) + .await?; + + Ok(()) +} diff --git a/crates/cdk-mintd/src/main.rs b/crates/cdk-mintd/src/main.rs index ab332c6ba..8e8bdaeb8 100644 --- a/crates/cdk-mintd/src/main.rs +++ b/crates/cdk-mintd/src/main.rs @@ -2,63 +2,6 @@ #![warn(missing_docs)] #![warn(rustdoc::bare_urls)] -// std -#[cfg(feature = "auth")] -use std::collections::HashMap; -use std::env; -use std::net::SocketAddr; -use std::path::{Path, PathBuf}; -use std::str::FromStr; -use std::sync::Arc; - -// external crates -use anyhow::{anyhow, bail, Result}; -use axum::Router; -use bip39::Mnemonic; -// internal crate modules -use cdk::cdk_database::{self, MintDatabase, MintKeysDatabase}; -use cdk::cdk_payment; -use cdk::cdk_payment::MintPayment; -use cdk::mint::{Mint, MintBuilder, MintMeltLimits}; -#[cfg(any( - feature = "cln", - feature = "lnbits", - feature = "lnd", - feature = "fakewallet", - feature = "grpc-processor" -))] -use cdk::nuts::nut17::SupportedMethods; -use cdk::nuts::nut19::{CachedEndpoint, Method as NUT19Method, Path as NUT19Path}; -#[cfg(any( - feature = "cln", - feature = "lnbits", - feature = "lnd", - feature = "fakewallet" -))] -use cdk::nuts::CurrencyUnit; -#[cfg(feature = "auth")] -use cdk::nuts::{AuthRequired, Method, ProtectedEndpoint, RoutePath}; -use cdk::nuts::{ContactInfo, MintVersion, PaymentMethod}; -use cdk::types::QuoteTTL; -use cdk_axum::cache::HttpCache; -use cdk_mintd::cli::CLIArgs; -use cdk_mintd::config::{self, DatabaseEngine, LnBackend}; -use cdk_mintd::env_vars::ENV_WORK_DIR; -use cdk_mintd::setup::LnBackendSetup; -#[cfg(feature = "auth")] -use cdk_sqlite::mint::MintSqliteAuthDatabase; -use cdk_sqlite::MintSqliteDatabase; -use clap::Parser; -use tower::ServiceBuilder; -use tower_http::compression::CompressionLayer; -use tower_http::decompression::RequestDecompressionLayer; -use tower_http::trace::TraceLayer; -use tracing_subscriber::EnvFilter; -#[cfg(feature = "swagger")] -use utoipa::OpenApi; - -const CARGO_PKG_VERSION: Option<&'static str> = option_env!("CARGO_PKG_VERSION"); - // Ensure at least one lightning backend is enabled at compile time #[cfg(not(any( feature = "cln", @@ -71,737 +14,29 @@ compile_error!( "At least one lightning backend feature must be enabled: cln, lnbits, lnd, fakewallet, or grpc-processor" ); -/// The main entry point for the application. -/// -/// This asynchronous function performs the following steps: -/// 1. Executes the initial setup, including loading configurations and initializing the database. -/// 2. Configures a `MintBuilder` instance with the local store and keystore based on the database. -/// 3. Applies additional custom configurations and authentication setup for the `MintBuilder`. -/// 4. Constructs a `Mint` instance from the configured `MintBuilder`. -/// 5. Checks and resolves the status of any pending mint and melt quotes. -#[tokio::main] -async fn main() -> Result<()> { - let (work_dir, settings, localstore, keystore) = initial_setup().await?; - - let mint_builder = MintBuilder::new(localstore); - - let (mint_builder, ln_routers) = configure_mint_builder(&settings, mint_builder).await?; - #[cfg(feature = "auth")] - let mint_builder = setup_authentication(&settings, &work_dir, mint_builder).await?; - - let mint = build_mint(&settings, keystore, mint_builder).await?; - - tracing::debug!("Mint built from builder."); - - let mint = Arc::new(mint); - - // Checks the status of all pending melt quotes - // Pending melt quotes where the payment has gone through inputs are burnt - // Pending melt quotes where the payment has **failed** inputs are reset to unspent - mint.check_pending_melt_quotes().await?; +use anyhow::Result; +use cdk_mintd::cli::CLIArgs; +use cdk_mintd::{get_work_directory, load_settings, setup_tracing}; +use clap::Parser; +use tokio::main; - start_services( - mint.clone(), - &settings, - ln_routers, - &work_dir, - mint.mint_info().await?, - ) - .await?; +#[main] +async fn main() -> Result<()> { + let args = CLIArgs::parse(); - Ok(()) -} + if args.enable_logging { + setup_tracing(); + } -/// Performs the initial setup for the application, including configuring tracing, -/// parsing CLI arguments, setting up the working directory, loading settings, -/// and initializing the database connection. -async fn initial_setup() -> Result<( - PathBuf, - config::Settings, - Arc + Send + Sync>, - Arc + Send + Sync>, -)> { - setup_tracing(); - let args = CLIArgs::parse(); let work_dir = get_work_directory(&args).await?; let settings = load_settings(&work_dir, args.config)?; - let (localstore, keystore) = setup_database(&settings, &work_dir).await?; - Ok((work_dir, settings, localstore, keystore)) -} - -/// Sets up and initializes a tracing subscriber with custom log filtering. -fn setup_tracing() { - let default_filter = "debug"; - let sqlx_filter = "sqlx=warn"; - let hyper_filter = "hyper=warn"; - let h2_filter = "h2=warn"; - let tower_http = "tower_http=warn"; - - let env_filter = EnvFilter::new(format!( - "{default_filter},{sqlx_filter},{hyper_filter},{h2_filter},{tower_http}" - )); - - tracing_subscriber::fmt().with_env_filter(env_filter).init(); -} - -/// Retrieves the work directory based on command-line arguments, environment variables, or system defaults. -async fn get_work_directory(args: &CLIArgs) -> Result { - let work_dir = if let Some(work_dir) = &args.work_dir { - tracing::info!("Using work dir from cmd arg"); - work_dir.clone() - } else if let Ok(env_work_dir) = env::var(ENV_WORK_DIR) { - tracing::info!("Using work dir from env var"); - env_work_dir.into() - } else { - work_dir()? - }; - tracing::info!("Using work dir: {}", work_dir.display()); - Ok(work_dir) -} - -/// Loads the application settings based on a configuration file and environment variables. -fn load_settings(work_dir: &Path, config_path: Option) -> Result { - // get config file name from args - let config_file_arg = match config_path { - Some(c) => c, - None => work_dir.join("config.toml"), - }; - - let mut settings = if config_file_arg.exists() { - config::Settings::new(Some(config_file_arg)) - } else { - tracing::info!("Config file does not exist. Attempting to read env vars"); - config::Settings::default() - }; - - // This check for any settings defined in ENV VARs - // ENV VARS will take **priority** over those in the config - settings.from_env() -} - -async fn setup_database( - settings: &config::Settings, - work_dir: &Path, -) -> Result<( - Arc + Send + Sync>, - Arc + Send + Sync>, -)> { - match settings.database.engine { - DatabaseEngine::Sqlite => { - #[cfg(feature = "sqlcipher")] - let password = CLIArgs::parse().password; - #[cfg(not(feature = "sqlcipher"))] - let password = String::new(); - let db = setup_sqlite_database(work_dir, Some(password)).await?; - let localstore: Arc + Send + Sync> = db.clone(); - let keystore: Arc + Send + Sync> = db; - Ok((localstore, keystore)) - } - } -} -async fn setup_sqlite_database( - work_dir: &Path, - _password: Option, -) -> Result> { - let sql_db_path = work_dir.join("cdk-mintd.sqlite"); - #[cfg(not(feature = "sqlcipher"))] - let db = MintSqliteDatabase::new(&sql_db_path).await?; #[cfg(feature = "sqlcipher")] - let db = { - // Get password from command line arguments for sqlcipher - MintSqliteDatabase::new((sql_db_path, _password.unwrap())).await? - }; - Ok(Arc::new(db)) -} - -/** - * Configures a `MintBuilder` instance with provided settings and initializes - * routers for Lightning Network backends. - */ -async fn configure_mint_builder( - settings: &config::Settings, - mint_builder: MintBuilder, -) -> Result<(MintBuilder, Vec)> { - let mut ln_routers = vec![]; - - // Configure basic mint information - let mint_builder = configure_basic_info(settings, mint_builder); - - // Configure lightning backend - let mint_builder = configure_lightning_backend(settings, mint_builder, &mut ln_routers).await?; - - // Configure caching - let mint_builder = configure_cache(settings, mint_builder); - - Ok((mint_builder, ln_routers)) -} - -/// Configures basic mint information (name, contact info, descriptions, etc.) -fn configure_basic_info(settings: &config::Settings, mint_builder: MintBuilder) -> MintBuilder { - // Add contact information - let mut contacts = Vec::new(); - if let Some(nostr_key) = &settings.mint_info.contact_nostr_public_key { - contacts.push(ContactInfo::new("nostr".to_string(), nostr_key.to_string())); - } - if let Some(email) = &settings.mint_info.contact_email { - contacts.push(ContactInfo::new("email".to_string(), email.to_string())); - } - - // Add version information - let mint_version = MintVersion::new( - "cdk-mintd".to_string(), - CARGO_PKG_VERSION.unwrap_or("Unknown").to_string(), - ); - - // Configure mint builder with basic info - let mut builder = mint_builder - .with_name(settings.mint_info.name.clone()) - .with_version(mint_version) - .with_description(settings.mint_info.description.clone()); - - // Add optional information - if let Some(long_description) = &settings.mint_info.description_long { - builder = builder.with_long_description(long_description.to_string()); - } - - for contact in contacts { - builder = builder.with_contact_info(contact); - } - - if let Some(pubkey) = settings.mint_info.pubkey { - builder = builder.with_pubkey(pubkey); - } - - if let Some(icon_url) = &settings.mint_info.icon_url { - builder = builder.with_icon_url(icon_url.to_string()); - } - - if let Some(motd) = &settings.mint_info.motd { - builder = builder.with_motd(motd.to_string()); - } - - if let Some(tos_url) = &settings.mint_info.tos_url { - builder = builder.with_tos_url(tos_url.to_string()); - } - - builder -} -/// Configures Lightning Network backend based on the specified backend type -async fn configure_lightning_backend( - settings: &config::Settings, - mut mint_builder: MintBuilder, - ln_routers: &mut Vec, -) -> Result { - let mint_melt_limits = MintMeltLimits { - mint_min: settings.ln.min_mint, - mint_max: settings.ln.max_mint, - melt_min: settings.ln.min_melt, - melt_max: settings.ln.max_melt, - }; - - tracing::debug!("Ln backend: {:?}", settings.ln.ln_backend); - - match settings.ln.ln_backend { - #[cfg(feature = "cln")] - LnBackend::Cln => { - let cln_settings = settings - .cln - .clone() - .expect("Config checked at load that cln is some"); - let cln = cln_settings - .setup(ln_routers, settings, CurrencyUnit::Msat) - .await?; - - mint_builder = configure_backend_for_unit( - settings, - mint_builder, - CurrencyUnit::Sat, - mint_melt_limits, - Arc::new(cln), - ) - .await?; - } - #[cfg(feature = "lnbits")] - LnBackend::LNbits => { - let lnbits_settings = settings.clone().lnbits.expect("Checked on config load"); - let lnbits = lnbits_settings - .setup(ln_routers, settings, CurrencyUnit::Sat) - .await?; - - mint_builder = configure_backend_for_unit( - settings, - mint_builder, - CurrencyUnit::Sat, - mint_melt_limits, - Arc::new(lnbits), - ) - .await?; - } - #[cfg(feature = "lnd")] - LnBackend::Lnd => { - let lnd_settings = settings.clone().lnd.expect("Checked at config load"); - let lnd = lnd_settings - .setup(ln_routers, settings, CurrencyUnit::Msat) - .await?; - - mint_builder = configure_backend_for_unit( - settings, - mint_builder, - CurrencyUnit::Sat, - mint_melt_limits, - Arc::new(lnd), - ) - .await?; - } - #[cfg(feature = "fakewallet")] - LnBackend::FakeWallet => { - let fake_wallet = settings.clone().fake_wallet.expect("Fake wallet defined"); - tracing::info!("Using fake wallet: {:?}", fake_wallet); - - for unit in fake_wallet.clone().supported_units { - let fake = fake_wallet - .setup(ln_routers, settings, CurrencyUnit::Sat) - .await?; - - mint_builder = configure_backend_for_unit( - settings, - mint_builder, - unit.clone(), - mint_melt_limits, - Arc::new(fake), - ) - .await?; - } - } - #[cfg(feature = "grpc-processor")] - LnBackend::GrpcProcessor => { - let grpc_processor = settings - .clone() - .grpc_processor - .expect("grpc processor config defined"); - - tracing::info!( - "Attempting to start with gRPC payment processor at {}:{}.", - grpc_processor.addr, - grpc_processor.port - ); - - for unit in grpc_processor.clone().supported_units { - tracing::debug!("Adding unit: {:?}", unit); - let processor = grpc_processor - .setup(ln_routers, settings, unit.clone()) - .await?; - - mint_builder = configure_backend_for_unit( - settings, - mint_builder, - unit.clone(), - mint_melt_limits, - Arc::new(processor), - ) - .await?; - } - } - LnBackend::None => { - tracing::error!( - "Payment backend was not set or feature disabled. {:?}", - settings.ln.ln_backend - ); - bail!("Lightning backend must be configured"); - } - }; - - Ok(mint_builder) -} + let password = Some(CLIArgs::parse().password); -/// Helper function to configure a mint builder with a lightning backend for a specific currency unit -async fn configure_backend_for_unit( - settings: &config::Settings, - mut mint_builder: MintBuilder, - unit: cdk::nuts::CurrencyUnit, - mint_melt_limits: MintMeltLimits, - backend: Arc + Send + Sync>, -) -> Result { - let payment_settings = backend.get_settings().await?; - - if let Some(bolt12) = payment_settings.get("bolt12") { - if bolt12.as_bool().unwrap_or_default() { - mint_builder - .add_payment_processor( - unit.clone(), - PaymentMethod::Bolt12, - mint_melt_limits, - Arc::clone(&backend), - ) - .await?; - } - } - - mint_builder - .add_payment_processor( - unit.clone(), - PaymentMethod::Bolt11, - mint_melt_limits, - backend, - ) - .await?; - - if let Some(input_fee) = settings.info.input_fee_ppk { - mint_builder.set_unit_fee(&unit, input_fee)?; - } - - let nut17_supported = SupportedMethods::default_bolt11(unit); - mint_builder = mint_builder.with_supported_websockets(nut17_supported); - - Ok(mint_builder) -} - -/// Configures cache settings -fn configure_cache(settings: &config::Settings, mint_builder: MintBuilder) -> MintBuilder { - let cached_endpoints = vec![ - CachedEndpoint::new(NUT19Method::Post, NUT19Path::MintBolt11), - CachedEndpoint::new(NUT19Method::Post, NUT19Path::MeltBolt11), - CachedEndpoint::new(NUT19Method::Post, NUT19Path::Swap), - ]; - - let cache: HttpCache = settings.info.http_cache.clone().into(); - mint_builder.with_cache(Some(cache.ttl.as_secs()), cached_endpoints) -} - -#[cfg(feature = "auth")] -async fn setup_authentication( - settings: &config::Settings, - work_dir: &Path, - mut mint_builder: MintBuilder, -) -> Result { - if let Some(auth_settings) = settings.auth.clone() { - tracing::info!("Auth settings are defined. {:?}", auth_settings); - let auth_localstore: Arc< - dyn cdk_database::MintAuthDatabase + Send + Sync, - > = match settings.database.engine { - DatabaseEngine::Sqlite => { - let sql_db_path = work_dir.join("cdk-mintd-auth.sqlite"); - #[cfg(feature = "sqlcipher")] - let password = CLIArgs::parse().password; - #[cfg(feature = "sqlcipher")] - let sqlite_db = MintSqliteAuthDatabase::new((sql_db_path, password)).await?; - #[cfg(not(feature = "sqlcipher"))] - let sqlite_db = MintSqliteAuthDatabase::new(&sql_db_path).await?; - Arc::new(sqlite_db) - } - }; - - let mint_blind_auth_endpoint = - ProtectedEndpoint::new(Method::Post, RoutePath::MintBlindAuth); - - let mut protected_endpoints = HashMap::new(); - - protected_endpoints.insert(mint_blind_auth_endpoint, AuthRequired::Clear); - - let mut blind_auth_endpoints = vec![]; - let mut unprotected_endpoints = vec![]; - - { - let mint_quote_protected_endpoint = - ProtectedEndpoint::new(Method::Post, RoutePath::MintQuoteBolt11); - let mint_protected_endpoint = - ProtectedEndpoint::new(Method::Post, RoutePath::MintBolt11); - if auth_settings.enabled_mint { - protected_endpoints.insert(mint_quote_protected_endpoint, AuthRequired::Blind); - - protected_endpoints.insert(mint_protected_endpoint, AuthRequired::Blind); - - blind_auth_endpoints.push(mint_quote_protected_endpoint); - blind_auth_endpoints.push(mint_protected_endpoint); - } else { - unprotected_endpoints.push(mint_protected_endpoint); - unprotected_endpoints.push(mint_quote_protected_endpoint); - } - } - - { - let melt_quote_protected_endpoint = - ProtectedEndpoint::new(Method::Post, RoutePath::MeltQuoteBolt11); - let melt_protected_endpoint = - ProtectedEndpoint::new(Method::Post, RoutePath::MeltBolt11); - - if auth_settings.enabled_melt { - protected_endpoints.insert(melt_quote_protected_endpoint, AuthRequired::Blind); - protected_endpoints.insert(melt_protected_endpoint, AuthRequired::Blind); - - blind_auth_endpoints.push(melt_quote_protected_endpoint); - blind_auth_endpoints.push(melt_protected_endpoint); - } else { - unprotected_endpoints.push(melt_quote_protected_endpoint); - unprotected_endpoints.push(melt_protected_endpoint); - } - } - - { - let swap_protected_endpoint = ProtectedEndpoint::new(Method::Post, RoutePath::Swap); - - if auth_settings.enabled_swap { - protected_endpoints.insert(swap_protected_endpoint, AuthRequired::Blind); - blind_auth_endpoints.push(swap_protected_endpoint); - } else { - unprotected_endpoints.push(swap_protected_endpoint); - } - } - - { - let check_mint_protected_endpoint = - ProtectedEndpoint::new(Method::Get, RoutePath::MintQuoteBolt11); - - if auth_settings.enabled_check_mint_quote { - protected_endpoints.insert(check_mint_protected_endpoint, AuthRequired::Blind); - blind_auth_endpoints.push(check_mint_protected_endpoint); - } else { - unprotected_endpoints.push(check_mint_protected_endpoint); - } - } - - { - let check_melt_protected_endpoint = - ProtectedEndpoint::new(Method::Get, RoutePath::MeltQuoteBolt11); - - if auth_settings.enabled_check_melt_quote { - protected_endpoints.insert(check_melt_protected_endpoint, AuthRequired::Blind); - blind_auth_endpoints.push(check_melt_protected_endpoint); - } else { - unprotected_endpoints.push(check_melt_protected_endpoint); - } - } - - { - let restore_protected_endpoint = - ProtectedEndpoint::new(Method::Post, RoutePath::Restore); - - if auth_settings.enabled_restore { - protected_endpoints.insert(restore_protected_endpoint, AuthRequired::Blind); - blind_auth_endpoints.push(restore_protected_endpoint); - } else { - unprotected_endpoints.push(restore_protected_endpoint); - } - } - - { - let state_protected_endpoint = - ProtectedEndpoint::new(Method::Post, RoutePath::Checkstate); - - if auth_settings.enabled_check_proof_state { - protected_endpoints.insert(state_protected_endpoint, AuthRequired::Blind); - blind_auth_endpoints.push(state_protected_endpoint); - } else { - unprotected_endpoints.push(state_protected_endpoint); - } - } - - mint_builder = mint_builder.with_auth( - auth_localstore.clone(), - auth_settings.openid_discovery, - auth_settings.openid_client_id, - vec![mint_blind_auth_endpoint], - ); - mint_builder = - mint_builder.with_blind_auth(auth_settings.mint_max_bat, blind_auth_endpoints); - - let mut tx = auth_localstore.begin_transaction().await?; - - tx.remove_protected_endpoints(unprotected_endpoints).await?; - tx.add_protected_endpoints(protected_endpoints).await?; - tx.commit().await?; - } - Ok(mint_builder) -} - -/// Build mints with the configured the signing method (remote signatory or local seed) -async fn build_mint( - settings: &config::Settings, - keystore: Arc + Send + Sync>, - mint_builder: MintBuilder, -) -> Result { - if let Some(signatory_url) = settings.info.signatory_url.clone() { - tracing::info!( - "Connecting to remote signatory to {} with certs {:?}", - signatory_url, - settings.info.signatory_certs.clone() - ); - - Ok(mint_builder - .build_with_signatory(Arc::new( - cdk_signatory::SignatoryRpcClient::new( - signatory_url, - settings.info.signatory_certs.clone(), - ) - .await?, - )) - .await?) - } else if let Some(mnemonic) = settings - .info - .mnemonic - .clone() - .map(|s| Mnemonic::from_str(&s)) - .transpose()? - { - Ok(mint_builder - .build_with_seed(keystore, &mnemonic.to_seed_normalized("")) - .await?) - } else { - bail!("No seed nor remote signatory set"); - } -} - -async fn start_services( - mint: Arc, - settings: &config::Settings, - ln_routers: Vec, - _work_dir: &Path, - mint_builder_info: cdk::nuts::MintInfo, -) -> Result<()> { - let listen_addr = settings.info.listen_host.clone(); - let listen_port = settings.info.listen_port; - let cache: HttpCache = settings.info.http_cache.clone().into(); - - #[cfg(feature = "management-rpc")] - let mut rpc_enabled = false; - #[cfg(not(feature = "management-rpc"))] - let rpc_enabled = false; - - #[cfg(feature = "management-rpc")] - let mut rpc_server: Option = None; - - #[cfg(feature = "management-rpc")] - { - if let Some(rpc_settings) = settings.mint_management_rpc.clone() { - if rpc_settings.enabled { - let addr = rpc_settings.address.unwrap_or("127.0.0.1".to_string()); - let port = rpc_settings.port.unwrap_or(8086); - let mut mint_rpc = cdk_mint_rpc::MintRPCServer::new(&addr, port, mint.clone())?; - - let tls_dir = rpc_settings.tls_dir_path.unwrap_or(_work_dir.join("tls")); - - if !tls_dir.exists() { - tracing::error!("TLS directory does not exist: {}", tls_dir.display()); - bail!("Cannot start RPC server: TLS directory does not exist"); - } - - mint_rpc.start(Some(tls_dir)).await?; - - rpc_server = Some(mint_rpc); - - rpc_enabled = true; - } - } - } - - if rpc_enabled { - if mint.mint_info().await.is_err() { - tracing::info!("Mint info not set on mint, setting."); - mint.set_mint_info(mint_builder_info).await?; - mint.set_quote_ttl(QuoteTTL::new(10_000, 10_000)).await?; - } else { - if mint.localstore().get_quote_ttl().await.is_err() { - mint.set_quote_ttl(QuoteTTL::new(10_000, 10_000)).await?; - } - // Add version information - let mint_version = MintVersion::new( - "cdk-mintd".to_string(), - CARGO_PKG_VERSION.unwrap_or("Unknown").to_string(), - ); - let mut stored_mint_info = mint.mint_info().await?; - stored_mint_info.version = Some(mint_version); - mint.set_mint_info(stored_mint_info).await?; - - tracing::info!("Mint info already set, not using config file settings."); - } - } else { - tracing::warn!("RPC not enabled, using mint info from config."); - mint.set_mint_info(mint_builder_info).await?; - mint.set_quote_ttl(QuoteTTL::new(10_000, 10_000)).await?; - } - - let mint_info = mint.mint_info().await?; - let nut04_methods = mint_info.nuts.nut04.supported_methods(); - let nut05_methods = mint_info.nuts.nut05.supported_methods(); - - let bolt12_supported = nut04_methods.contains(&&PaymentMethod::Bolt12) - || nut05_methods.contains(&&PaymentMethod::Bolt12); - - let v1_service = - cdk_axum::create_mint_router_with_custom_cache(Arc::clone(&mint), cache, bolt12_supported) - .await?; - - let mut mint_service = Router::new() - .merge(v1_service) - .layer( - ServiceBuilder::new() - .layer(RequestDecompressionLayer::new()) - .layer(CompressionLayer::new()), - ) - .layer(TraceLayer::new_for_http()); - - #[cfg(feature = "swagger")] - { - if settings.info.enable_swagger_ui.unwrap_or(false) { - mint_service = mint_service.merge( - utoipa_swagger_ui::SwaggerUi::new("/swagger-ui") - .url("/api-docs/openapi.json", cdk_axum::ApiDoc::openapi()), - ); - } - } - - for router in ln_routers { - mint_service = mint_service.merge(router); - } - - mint.start().await?; - - let socket_addr = SocketAddr::from_str(&format!("{listen_addr}:{listen_port}"))?; - - let listener = tokio::net::TcpListener::bind(socket_addr).await?; - - tracing::debug!("listening on {}", listener.local_addr().unwrap()); - - // Wait for axum server to complete - let axum_result = axum::serve(listener, mint_service).with_graceful_shutdown(shutdown_signal()); - - match axum_result.await { - Ok(_) => { - tracing::info!("Axum server stopped with okay status"); - } - Err(err) => { - tracing::warn!("Axum server stopped with error"); - tracing::error!("{}", err); - bail!("Axum exited with error") - } - } - - mint.stop().await?; - - #[cfg(feature = "management-rpc")] - { - if let Some(rpc_server) = rpc_server { - rpc_server.stop().await?; - } - } - - Ok(()) -} - -async fn shutdown_signal() { - tokio::signal::ctrl_c() - .await - .expect("failed to install CTRL+C handler"); - tracing::info!("Shutdown signal received"); -} - -fn work_dir() -> Result { - let home_dir = home::home_dir().ok_or(anyhow!("Unknown home dir"))?; - let dir = home_dir.join(".cdk-mintd"); - - std::fs::create_dir_all(&dir)?; + #[cfg(not(feature = "sqlcipher"))] + let password = None; - Ok(dir) + cdk_mintd::run_mintd(&work_dir, &settings, password).await } diff --git a/crates/cdk-payment-processor/Cargo.toml b/crates/cdk-payment-processor/Cargo.toml index 605ff211b..db7983520 100644 --- a/crates/cdk-payment-processor/Cargo.toml +++ b/crates/cdk-payment-processor/Cargo.toml @@ -30,6 +30,7 @@ cdk-common = { workspace = true, features = ["mint"] } cdk-cln = { workspace = true, optional = true } cdk-lnd = { workspace = true, optional = true } cdk-fake-wallet = { workspace = true, optional = true } +clap = { workspace = true, features = ["derive"] } serde.workspace = true thiserror.workspace = true tracing.workspace = true diff --git a/crates/cdk-payment-processor/src/bin/payment_processor.rs b/crates/cdk-payment-processor/src/bin/payment_processor.rs index 46d11bef5..030ef0bb3 100644 --- a/crates/cdk-payment-processor/src/bin/payment_processor.rs +++ b/crates/cdk-payment-processor/src/bin/payment_processor.rs @@ -14,11 +14,47 @@ use cdk_common::payment::{self, MintPayment}; use cdk_common::Amount; #[cfg(feature = "fake")] use cdk_fake_wallet::FakeWallet; +use clap::Parser; use serde::{Deserialize, Serialize}; #[cfg(any(feature = "cln", feature = "lnd", feature = "fake"))] use tokio::signal; use tracing_subscriber::EnvFilter; +/// Common CLI arguments for CDK binaries +#[derive(Parser, Debug)] +pub struct CommonArgs { + /// Enable logging (default is false) + #[arg(long, default_value_t = false)] + pub enable_logging: bool, + + /// Logging level when enabled (default is debug) + #[arg(long, default_value = "debug")] + pub log_level: tracing::Level, +} + +/// Initialize logging based on CLI arguments +pub fn init_logging(enable_logging: bool, log_level: tracing::Level) { + if enable_logging { + let default_filter = log_level.to_string(); + + // Common filters to reduce noise + let sqlx_filter = "sqlx=warn"; + let hyper_filter = "hyper=warn"; + let h2_filter = "h2=warn"; + let rustls_filter = "rustls=warn"; + let reqwest_filter = "reqwest=warn"; + + let env_filter = EnvFilter::new(format!( + "{default_filter},{sqlx_filter},{hyper_filter},{h2_filter},{rustls_filter},{reqwest_filter}" + )); + + // Ok if successful, Err if already initialized + let _ = tracing_subscriber::fmt() + .with_env_filter(env_filter) + .try_init(); + } +} + pub const ENV_LN_BACKEND: &str = "CDK_PAYMENT_PROCESSOR_LN_BACKEND"; pub const ENV_LISTEN_HOST: &str = "CDK_PAYMENT_PROCESSOR_LISTEN_HOST"; pub const ENV_LISTEN_PORT: &str = "CDK_PAYMENT_PROCESSOR_LISTEN_PORT"; @@ -36,20 +72,20 @@ pub const ENV_LND_ADDRESS: &str = "CDK_PAYMENT_PROCESSOR_LND_ADDRESS"; pub const ENV_LND_CERT_FILE: &str = "CDK_PAYMENT_PROCESSOR_LND_CERT_FILE"; pub const ENV_LND_MACAROON_FILE: &str = "CDK_PAYMENT_PROCESSOR_LND_MACAROON_FILE"; +#[derive(Parser)] +#[command(name = "payment-processor")] +#[command(about = "CDK Payment Processor", long_about = None)] +struct Args { + #[command(flatten)] + common: CommonArgs, +} + #[tokio::main] async fn main() -> anyhow::Result<()> { - let default_filter = "debug"; - - let sqlx_filter = "sqlx=warn"; - let hyper_filter = "hyper=warn"; - let h2_filter = "h2=warn"; - let rustls_filter = "rustls=warn"; - - let env_filter = EnvFilter::new(format!( - "{default_filter},{sqlx_filter},{hyper_filter},{h2_filter},{rustls_filter}" - )); + let args = Args::parse(); - tracing_subscriber::fmt().with_env_filter(env_filter).init(); + // Initialize logging based on CLI arguments + init_logging(args.common.enable_logging, args.common.log_level); #[cfg(any(feature = "cln", feature = "lnd", feature = "fake"))] { diff --git a/crates/cdk-signatory/src/bin/cli/mod.rs b/crates/cdk-signatory/src/bin/cli/mod.rs index b389b31c5..6dc905792 100644 --- a/crates/cdk-signatory/src/bin/cli/mod.rs +++ b/crates/cdk-signatory/src/bin/cli/mod.rs @@ -17,9 +17,43 @@ use cdk_signatory::{db_signatory, start_grpc_server}; #[cfg(feature = "sqlite")] use cdk_sqlite::MintSqliteDatabase; use clap::Parser; -use tracing::Level; use tracing_subscriber::EnvFilter; +/// Common CLI arguments for CDK binaries +#[derive(Parser, Debug)] +pub struct CommonArgs { + /// Enable logging (default is false) + #[arg(long, default_value_t = false)] + pub enable_logging: bool, + + /// Logging level when enabled (default is debug) + #[arg(long, default_value = "debug")] + pub log_level: tracing::Level, +} + +/// Initialize logging based on CLI arguments +pub fn init_logging(enable_logging: bool, log_level: tracing::Level) { + if enable_logging { + let default_filter = log_level.to_string(); + + // Common filters to reduce noise + let sqlx_filter = "sqlx=warn"; + let hyper_filter = "hyper=warn"; + let h2_filter = "h2=warn"; + let rustls_filter = "rustls=warn"; + let reqwest_filter = "reqwest=warn"; + + let env_filter = EnvFilter::new(format!( + "{default_filter},{sqlx_filter},{hyper_filter},{h2_filter},{rustls_filter},{reqwest_filter}" + )); + + // Ok if successful, Err if already initialized + let _ = tracing_subscriber::fmt() + .with_env_filter(env_filter) + .try_init(); + } +} + const DEFAULT_WORK_DIR: &str = ".cdk-signatory"; const ENV_MNEMONIC: &str = "CDK_MINTD_MNEMONIC"; @@ -30,6 +64,9 @@ const ENV_MNEMONIC: &str = "CDK_MINTD_MNEMONIC"; #[command(version = "0.1.0")] #[command(author, version, about, long_about = None)] struct Cli { + #[command(flatten)] + common: CommonArgs, + /// Database engine to use (sqlite/redb) #[arg(short, long, default_value = "sqlite")] engine: String, @@ -39,9 +76,6 @@ struct Cli { /// Path to working dir #[arg(short, long)] work_dir: Option, - /// Logging level - #[arg(short, long, default_value = "debug")] - log_level: Level, #[arg(long, default_value = "127.0.0.1")] listen_addr: String, #[arg(long, default_value = "15060")] @@ -56,7 +90,10 @@ struct Cli { /// Main function for the signatory standalone binary pub async fn cli_main() -> Result<()> { let args: Cli = Cli::parse(); - let default_filter = args.log_level; + + // Initialize logging based on CLI arguments + init_logging(args.common.enable_logging, args.common.log_level); + let supported_units = args .units .into_iter() @@ -74,13 +111,6 @@ pub async fn cli_main() -> Result<()> { }) .collect::, _>>()?; - let sqlx_filter = "sqlx=warn,hyper_util=warn,reqwest=warn"; - - let env_filter = EnvFilter::new(format!("{default_filter},{sqlx_filter}")); - - // Parse input - tracing_subscriber::fmt().with_env_filter(env_filter).init(); - let work_dir = match &args.work_dir { Some(work_dir) => work_dir.clone(), None => { diff --git a/misc/fake_auth_itests.sh b/misc/fake_auth_itests.sh index cd70345bf..025311047 100755 --- a/misc/fake_auth_itests.sh +++ b/misc/fake_auth_itests.sh @@ -1,31 +1,37 @@ - #!/usr/bin/env bash # Function to perform cleanup cleanup() { echo "Cleaning up..." - echo "Killing the cdk mintd" - kill -2 $cdk_mintd_pid - wait $cdk_mintd_pid + if [ -n "$FAKE_AUTH_MINT_PID" ]; then + echo "Killing the fake auth mint process" + kill -2 $FAKE_AUTH_MINT_PID 2>/dev/null || true + wait $FAKE_AUTH_MINT_PID 2>/dev/null || true + fi echo "Mint binary terminated" # Remove the temporary directory - rm -rf "$CDK_ITESTS_DIR" - echo "Temp directory removed: $CDK_ITESTS_DIR" + if [ -n "$CDK_ITESTS_DIR" ] && [ -d "$CDK_ITESTS_DIR" ]; then + rm -rf "$CDK_ITESTS_DIR" + echo "Temp directory removed: $CDK_ITESTS_DIR" + fi + + # Unset all environment variables unset CDK_ITESTS_DIR unset CDK_ITESTS_MINT_ADDR unset CDK_ITESTS_MINT_PORT + unset FAKE_AUTH_MINT_PID } # Set up trap to call cleanup on script exit -trap cleanup EXIT +trap cleanup EXIT INT TERM # Create a temporary directory export CDK_ITESTS_DIR=$(mktemp -d) -export CDK_ITESTS_MINT_ADDR="127.0.0.1"; -export CDK_ITESTS_MINT_PORT=8087; +export CDK_ITESTS_MINT_ADDR="127.0.0.1" +export CDK_ITESTS_MINT_PORT=8087 # Check if the temporary directory was created successfully if [[ ! -d "$CDK_ITESTS_DIR" ]]; then @@ -34,72 +40,41 @@ if [[ ! -d "$CDK_ITESTS_DIR" ]]; then fi echo "Temp directory created: $CDK_ITESTS_DIR" -export MINT_DATABASE="$1"; -export OPENID_DISCOVERY="$2"; -cargo build -p cdk-integration-tests +# Check if a database type was provided as first argument, default to sqlite +export MINT_DATABASE="${1:-sqlite}" + +# Check if OPENID_DISCOVERY was provided as second argument, default to a test value +export OPENID_DISCOVERY="${2:-http://127.0.0.1:8080/realms/cdk-test-realm/.well-known/openid-configuration}" -export CDK_MINTD_URL="http://$CDK_ITESTS_MINT_ADDR:$CDK_ITESTS_MINT_PORT"; -export CDK_MINTD_WORK_DIR="$CDK_ITESTS_DIR"; -export CDK_MINTD_LISTEN_HOST=$CDK_ITESTS_MINT_ADDR; -export CDK_MINTD_LISTEN_PORT=$CDK_ITESTS_MINT_PORT; -export CDK_MINTD_LN_BACKEND="fakewallet"; -export CDK_MINTD_FAKE_WALLET_SUPPORTED_UNITS="sat"; -export CDK_MINTD_MNEMONIC="eye survey guilt napkin crystal cup whisper salt luggage manage unveil loyal"; -export CDK_MINTD_FAKE_WALLET_FEE_PERCENT="0"; -export CDK_MINTD_FAKE_WALLET_RESERVE_FEE_MIN="1"; -export CDK_MINTD_DATABASE=$MINT_DATABASE; +# Build the project +cargo build -p cdk-integration-tests # Auth configuration -export CDK_TEST_OIDC_USER="cdk-test"; -export CDK_TEST_OIDC_PASSWORD="cdkpassword"; - -export CDK_MINTD_AUTH_OPENID_DISCOVERY=$OPENID_DISCOVERY; -export CDK_MINTD_AUTH_OPENID_CLIENT_ID="cashu-client"; -export CDK_MINTD_AUTH_MINT_MAX_BAT="50"; -export CDK_MINTD_AUTH_ENABLED_MINT="true"; -export CDK_MINTD_AUTH_ENABLED_MELT="true"; -export CDK_MINTD_AUTH_ENABLED_SWAP="true"; -export CDK_MINTD_AUTH_ENABLED_CHECK_MINT_QUOTE="true"; -export CDK_MINTD_AUTH_ENABLED_CHECK_MELT_QUOTE="true"; -export CDK_MINTD_AUTH_ENABLED_RESTORE="true"; -export CDK_MINTD_AUTH_ENABLED_CHECK_PROOF_STATE="true"; - -echo "Starting auth mintd"; -cargo run --bin cdk-mintd --features redb & -cdk_mintd_pid=$! - -URL="http://$CDK_ITESTS_MINT_ADDR:$CDK_ITESTS_MINT_PORT/v1/info" -TIMEOUT=100 -START_TIME=$(date +%s) -# Loop until the endpoint returns a 200 OK status or timeout is reached -while true; do - # Get the current time - CURRENT_TIME=$(date +%s) - - # Calculate the elapsed time - ELAPSED_TIME=$((CURRENT_TIME - START_TIME)) +export CDK_TEST_OIDC_USER="cdk-test" +export CDK_TEST_OIDC_PASSWORD="cdkpassword" - # Check if the elapsed time exceeds the timeout - if [ $ELAPSED_TIME -ge $TIMEOUT ]; then - echo "Timeout of $TIMEOUT seconds reached. Exiting..." - exit 1 - fi +# Start the fake auth mint in the background +echo "Starting fake auth mint with discovery URL: $OPENID_DISCOVERY" +echo "Using temp directory: $CDK_ITESTS_DIR" +cargo run -p cdk-integration-tests --bin start_fake_auth_mint -- --enable-logging "$MINT_DATABASE" "$CDK_ITESTS_DIR" "$OPENID_DISCOVERY" "$CDK_ITESTS_MINT_PORT" & - # Make a request to the endpoint and capture the HTTP status code - HTTP_STATUS=$(curl -o /dev/null -s -w "%{http_code}" $URL) +# Store the PID of the mint process +FAKE_AUTH_MINT_PID=$! - # Check if the HTTP status is 200 OK - if [ "$HTTP_STATUS" -eq 200 ]; then - echo "Received 200 OK from $URL" - break - else - echo "Waiting for 200 OK response, current status: $HTTP_STATUS" - sleep 2 # Wait for 2 seconds before retrying - fi -done +# Wait a moment for the mint to start +sleep 5 + +# Check if the mint is running +if ! kill -0 $FAKE_AUTH_MINT_PID 2>/dev/null; then + echo "Failed to start fake auth mint" + exit 1 +fi + +echo "Fake auth mint started with PID: $FAKE_AUTH_MINT_PID" # Run cargo test +echo "Running fake auth integration tests..." cargo test -p cdk-integration-tests --test fake_auth # Capture the exit status of cargo test diff --git a/misc/fake_itests.sh b/misc/fake_itests.sh index 9ff24284c..d6a4199ea 100755 --- a/misc/fake_itests.sh +++ b/misc/fake_itests.sh @@ -1,46 +1,45 @@ #!/usr/bin/env bash +# Script to run fake mint tests with proper handling of race conditions +# This script ensures the .env file is properly created and available +# before running tests + # Function to perform cleanup cleanup() { echo "Cleaning up..." - echo "Killing the cdk mintd" - kill -2 $CDK_MINTD_PID - wait $CDK_MINTD_PID - kill -9 $CDK_SIGNATORY_PID - wait $CDK_SIGNATORY_PID + if [ -n "$FAKE_MINT_PID" ]; then + echo "Killing the fake mint process" + kill -2 $FAKE_MINT_PID 2>/dev/null || true + wait $FAKE_MINT_PID 2>/dev/null || true + fi + + if [ -n "$CDK_SIGNATORY_PID" ]; then + echo "Killing the signatory process" + kill -9 $CDK_SIGNATORY_PID 2>/dev/null || true + wait $CDK_SIGNATORY_PID 2>/dev/null || true + fi echo "Mint binary terminated" # Remove the temporary directory - rm -rf "$CDK_ITESTS_DIR" - echo "Temp directory removed: $CDK_ITESTS_DIR" + if [ -n "$CDK_ITESTS_DIR" ] && [ -d "$CDK_ITESTS_DIR" ]; then + rm -rf "$CDK_ITESTS_DIR" + echo "Temp directory removed: $CDK_ITESTS_DIR" + fi # Unset all environment variables unset CDK_ITESTS_DIR - unset CDK_ITESTS_MINT_ADDR - unset CDK_ITESTS_MINT_PORT - unset CDK_MINTD_DATABASE unset CDK_TEST_MINT_URL - unset CDK_MINTD_URL - unset CDK_MINTD_WORK_DIR - unset CDK_MINTD_LISTEN_HOST - unset CDK_MINTD_LISTEN_PORT - unset CDK_MINTD_LN_BACKEND - unset CDK_MINTD_FAKE_WALLET_SUPPORTED_UNITS - unset CDK_MINTD_MNEMONIC - unset CDK_MINTD_FAKE_WALLET_FEE_PERCENT - unset CDK_MINTD_FAKE_WALLET_RESERVE_FEE_MIN - unset CDK_MINTD_PID + unset FAKE_MINT_PID + unset CDK_SIGNATORY_PID } # Set up trap to call cleanup on script exit -trap cleanup EXIT +trap cleanup EXIT INT TERM # Create a temporary directory export CDK_ITESTS_DIR=$(mktemp -d) -export CDK_ITESTS_MINT_ADDR="127.0.0.1" -export CDK_ITESTS_MINT_PORT=8086 # Check if the temporary directory was created successfully if [[ ! -d "$CDK_ITESTS_DIR" ]]; then @@ -49,36 +48,74 @@ if [[ ! -d "$CDK_ITESTS_DIR" ]]; then fi echo "Temp directory created: $CDK_ITESTS_DIR" -export CDK_MINTD_DATABASE="$1" - -cargo build -p cdk-integration-tests +# Check if a database type was provided as first argument, default to sqlite +export CDK_MINTD_DATABASE="${1:-sqlite}" -export CDK_MINTD_URL="http://$CDK_ITESTS_MINT_ADDR:$CDK_ITESTS_MINT_PORT" -export CDK_MINTD_WORK_DIR="$CDK_ITESTS_DIR" -export CDK_MINTD_LISTEN_HOST=$CDK_ITESTS_MINT_ADDR -export CDK_MINTD_LISTEN_PORT=$CDK_ITESTS_MINT_PORT -export CDK_MINTD_LN_BACKEND="fakewallet" -export CDK_MINTD_FAKE_WALLET_SUPPORTED_UNITS="sat,usd" -export CDK_MINTD_MNEMONIC="eye survey guilt napkin crystal cup whisper salt luggage manage unveil loyal" -export CDK_MINTD_FAKE_WALLET_FEE_PERCENT="0" -export CDK_MINTD_FAKE_WALLET_RESERVE_FEE_MIN="1" +cargo build -p cdk-integration-tests +# Start the fake mint binary with the new Rust-based approach +echo "Starting fake mint using Rust binary..." if [ "$2" = "external_signatory" ]; then - export CDK_MINTD_SIGNATORY_URL="https://127.0.0.1:15060" - export CDK_MINTD_SIGNATORY_CERTS="$CDK_ITESTS_DIR" + echo "Starting with external signatory support" + bash -x `dirname $0`/../crates/cdk-signatory/generate_certs.sh $CDK_ITESTS_DIR + cargo build --bin signatory cargo run --bin signatory -- -w $CDK_ITESTS_DIR -u "sat" -u "usd" & export CDK_SIGNATORY_PID=$! sleep 5 + + cargo run --bin start_fake_mint -- --enable-logging --external-signatory "$CDK_MINTD_DATABASE" "$CDK_ITESTS_DIR" & +else + cargo run --bin start_fake_mint -- --enable-logging "$CDK_MINTD_DATABASE" "$CDK_ITESTS_DIR" & +fi +export FAKE_MINT_PID=$! + +# Give the mint a moment to start +sleep 3 + +# Look for the .env file in the temp directory +ENV_FILE_PATH="$CDK_ITESTS_DIR/.env" + +# Wait for the .env file to be created (with longer timeout) +max_wait=200 +wait_count=0 +while [ $wait_count -lt $max_wait ]; do + if [ -f "$ENV_FILE_PATH" ]; then + echo ".env file found at: $ENV_FILE_PATH" + break + fi + echo "Waiting for .env file to be created... ($wait_count/$max_wait)" + wait_count=$((wait_count + 1)) + sleep 1 +done + +# Check if we found the .env file +if [ ! -f "$ENV_FILE_PATH" ]; then + echo "ERROR: Could not find .env file at $ENV_FILE_PATH after $max_wait seconds" + exit 1 fi -echo "Starting fake mintd" -cargo run --bin cdk-mintd & -export CDK_MINTD_PID=$! +# Source the environment variables from the .env file +echo "Sourcing environment variables from $ENV_FILE_PATH" +source "$ENV_FILE_PATH" + +echo "Sourced environment variables:" +echo "CDK_TEST_MINT_URL=$CDK_TEST_MINT_URL" +echo "CDK_ITESTS_DIR=$CDK_ITESTS_DIR" -URL="http://$CDK_ITESTS_MINT_ADDR:$CDK_ITESTS_MINT_PORT/v1/info" -TIMEOUT=100 +# Validate that we sourced the variables +if [ -z "$CDK_TEST_MINT_URL" ] || [ -z "$CDK_ITESTS_DIR" ]; then + echo "ERROR: Failed to source environment variables from the .env file" + exit 1 +fi + +# Export all variables so they're available to the tests +export CDK_TEST_MINT_URL + +URL="$CDK_TEST_MINT_URL/v1/info" + +TIMEOUT=120 START_TIME=$(date +%s) # Loop until the endpoint returns a 200 OK status or timeout is reached while true; do @@ -107,10 +144,8 @@ while true; do fi done - -export CDK_TEST_MINT_URL="http://$CDK_ITESTS_MINT_ADDR:$CDK_ITESTS_MINT_PORT" - # Run first test +echo "Running fake_wallet test" cargo test -p cdk-integration-tests --test fake_wallet status1=$? @@ -121,6 +156,7 @@ if [ $status1 -ne 0 ]; then fi # Run second test only if the first one succeeded +echo "Running happy_path_mint_wallet test" cargo test -p cdk-integration-tests --test happy_path_mint_wallet status2=$? diff --git a/misc/interactive_regtest_mprocs.sh b/misc/interactive_regtest_mprocs.sh index 72aceef72..c1f263e0e 100755 --- a/misc/interactive_regtest_mprocs.sh +++ b/misc/interactive_regtest_mprocs.sh @@ -123,7 +123,7 @@ cargo build -p cdk-integration-tests --bin start_regtest cargo build --bin cdk-mintd echo "Starting regtest network (Bitcoin + Lightning nodes)..." -cargo run --bin start_regtest & +cargo run --bin start_regtest -- --enable-logging "$CDK_ITESTS_DIR" & export CDK_REGTEST_PID=$! # Create named pipe for progress tracking diff --git a/misc/itests.sh b/misc/itests.sh index dd2755c15..7fc490f46 100755 --- a/misc/itests.sh +++ b/misc/itests.sh @@ -4,25 +4,29 @@ cleanup() { echo "Cleaning up..." - echo "Killing the cdk mintd" - kill -2 $CDK_MINTD_PID - wait $CDK_MINTD_PID - - - echo "Killing the cdk lnd mintd" - kill -2 $CDK_MINTD_LND_PID - wait $CDK_MINTD_LND_PID - - echo "Killing the cdk regtest" - kill -2 $CDK_REGTEST_PID - wait $CDK_REGTEST_PID - + echo "Killing the cdk regtest and mints" + if [ ! -z "$CDK_REGTEST_PID" ]; then + # First try graceful shutdown with SIGTERM + kill -15 $CDK_REGTEST_PID 2>/dev/null + sleep 2 + + # Check if process is still running, if so force kill with SIGKILL + if ps -p $CDK_REGTEST_PID > /dev/null 2>&1; then + echo "Process still running, force killing..." + kill -9 $CDK_REGTEST_PID 2>/dev/null + fi + + # Wait for process to terminate + wait $CDK_REGTEST_PID 2>/dev/null || true + fi echo "Mint binary terminated" # Remove the temporary directory - rm -rf "$CDK_ITESTS_DIR" - echo "Temp directory removed: $CDK_ITESTS_DIR" + if [ ! -z "$CDK_ITESTS_DIR" ] && [ -d "$CDK_ITESTS_DIR" ]; then + rm -rf "$CDK_ITESTS_DIR" + echo "Temp directory removed: $CDK_ITESTS_DIR" + fi # Unset all environment variables unset CDK_ITESTS_DIR @@ -32,18 +36,6 @@ cleanup() { unset CDK_MINTD_DATABASE unset CDK_TEST_MINT_URL unset CDK_TEST_MINT_URL_2 - unset CDK_MINTD_URL - unset CDK_MINTD_WORK_DIR - unset CDK_MINTD_LISTEN_HOST - unset CDK_MINTD_LISTEN_PORT - unset CDK_MINTD_LN_BACKEND - unset CDK_MINTD_MNEMONIC - unset CDK_MINTD_CLN_RPC_PATH - unset CDK_MINTD_LND_ADDRESS - unset CDK_MINTD_LND_CERT_FILE - unset CDK_MINTD_LND_MACAROON_FILE - unset CDK_MINTD_PID - unset CDK_MINTD_LND_PID unset CDK_REGTEST_PID unset RUST_BACKTRACE unset CDK_TEST_REGTEST @@ -69,53 +61,59 @@ fi echo "Temp directory created: $CDK_ITESTS_DIR" export CDK_MINTD_DATABASE="$1" -cargo build -p cdk-integration-tests - -cargo run --bin start_regtest & +cargo build -p cdk-integration-tests +cargo build --bin start_regtest_mints +echo "Starting regtest and mints" +# Run the binary in background +cargo r --bin start_regtest_mints -- --enable-logging "$CDK_MINTD_DATABASE" "$CDK_ITESTS_DIR" "$CDK_ITESTS_MINT_ADDR" "$CDK_ITESTS_MINT_PORT_0" "$CDK_ITESTS_MINT_PORT_1" & export CDK_REGTEST_PID=$! -mkfifo "$CDK_ITESTS_DIR/progress_pipe" -rm -f "$CDK_ITESTS_DIR/signal_received" # Ensure clean state -# Start reading from pipe in background -(while read line; do - case "$line" in - "checkpoint1") - echo "Reached first checkpoint" - touch "$CDK_ITESTS_DIR/signal_received" - exit 0 - ;; - esac -done < "$CDK_ITESTS_DIR/progress_pipe") & -# Wait for up to 120 seconds -for ((i=0; i<120; i++)); do - if [ -f "$CDK_ITESTS_DIR/signal_received" ]; then - echo "break signal received" + +# Give it a moment to start - reduced from 5 to 2 seconds since we have better waiting mechanisms now +sleep 2 + +# Look for the .env file in the current directory +ENV_FILE_PATH="$CDK_ITESTS_DIR/.env" + +# Wait for the .env file to be created in the current directory +max_wait=120 +wait_count=0 +while [ $wait_count -lt $max_wait ]; do + if [ -f "$ENV_FILE_PATH" ]; then + echo ".env file found at: $ENV_FILE_PATH" break fi + wait_count=$((wait_count + 1)) sleep 1 done -echo "Regtest set up continuing" -echo "Starting regtest mint" -# cargo run --bin regtest_mint & +# Check if we found the .env file +if [ ! -f "$ENV_FILE_PATH" ]; then + echo "ERROR: Could not find .env file at $ENV_FILE_PATH" + exit 1 +fi -export CDK_MINTD_CLN_RPC_PATH="$CDK_ITESTS_DIR/cln/one/regtest/lightning-rpc" -export CDK_MINTD_URL="http://$CDK_ITESTS_MINT_ADDR:$CDK_ITESTS_MINT_PORT_0" -export CDK_MINTD_WORK_DIR="$CDK_ITESTS_DIR" -export CDK_MINTD_LISTEN_HOST=$CDK_ITESTS_MINT_ADDR -export CDK_MINTD_LISTEN_PORT=$CDK_ITESTS_MINT_PORT_0 -export CDK_MINTD_LN_BACKEND="cln" -export CDK_MINTD_MNEMONIC="eye survey guilt napkin crystal cup whisper salt luggage manage unveil loyal" -export RUST_BACKTRACE=1 +# Source the environment variables from the .env file +echo "Sourcing environment variables from $ENV_FILE_PATH" +source "$ENV_FILE_PATH" -echo "Starting cln mintd" -cargo run --bin cdk-mintd & -export CDK_MINTD_PID=$! +echo "Sourced environment variables:" +echo "CDK_TEST_MINT_URL=$CDK_TEST_MINT_URL" +echo "CDK_TEST_MINT_URL_2=$CDK_TEST_MINT_URL_2" +echo "CDK_ITESTS_DIR=$CDK_ITESTS_DIR" +# Validate that we sourced the variables +if [ -z "$CDK_TEST_MINT_URL" ] || [ -z "$CDK_TEST_MINT_URL_2" ] || [ -z "$CDK_ITESTS_DIR" ]; then + echo "ERROR: Failed to source environment variables from the .env file" + exit 1 +fi + +# Export all variables so they're available to the tests +export CDK_TEST_MINT_URL +export CDK_TEST_MINT_URL_2 -echo $CDK_ITESTS_DIR +URL="$CDK_TEST_MINT_URL/v1/info" -URL="http://$CDK_ITESTS_MINT_ADDR:$CDK_ITESTS_MINT_PORT_0/v1/info" TIMEOUT=100 START_TIME=$(date +%s) @@ -146,24 +144,8 @@ while true; do fi done +URL="$CDK_TEST_MINT_URL_2/v1/info" -export CDK_MINTD_LND_ADDRESS="https://localhost:10010" -export CDK_MINTD_LND_CERT_FILE="$CDK_ITESTS_DIR/lnd/two/tls.cert" -export CDK_MINTD_LND_MACAROON_FILE="$CDK_ITESTS_DIR/lnd/two/data/chain/bitcoin/regtest/admin.macaroon" - -export CDK_MINTD_URL="http://$CDK_ITESTS_MINT_ADDR:$CDK_ITESTS_MINT_PORT_1" -mkdir -p "$CDK_ITESTS_DIR/lnd_mint" -export CDK_MINTD_WORK_DIR="$CDK_ITESTS_DIR/lnd_mint" -export CDK_MINTD_LISTEN_HOST=$CDK_ITESTS_MINT_ADDR -export CDK_MINTD_LISTEN_PORT=$CDK_ITESTS_MINT_PORT_1 -export CDK_MINTD_LN_BACKEND="lnd" -export CDK_MINTD_MNEMONIC="cattle gold bind busy sound reduce tone addict baby spend february strategy" - -echo "Starting lnd mintd" -cargo run --bin cdk-mintd & -export CDK_MINTD_LND_PID=$! - -URL="http://$CDK_ITESTS_MINT_ADDR:$CDK_ITESTS_MINT_PORT_1/v1/info" TIMEOUT=100 START_TIME=$(date +%s) @@ -194,13 +176,6 @@ while true; do fi done - - -export CDK_TEST_MINT_URL="http://$CDK_ITESTS_MINT_ADDR:$CDK_ITESTS_MINT_PORT_0" -export CDK_TEST_MINT_URL_2="http://$CDK_ITESTS_MINT_ADDR:$CDK_ITESTS_MINT_PORT_1" - -# Run tests and exit immediately on failure - # Run cargo test echo "Running regtest test with CLN mint" cargo test -p cdk-integration-tests --test regtest @@ -216,7 +191,7 @@ if [ $? -ne 0 ]; then exit 1 fi -# # Run cargo test with the http_subscription feature +# Run cargo test with the http_subscription feature echo "Running regtest test with http_subscription feature" cargo test -p cdk-integration-tests --test regtest --features http_subscription if [ $? -ne 0 ]; then @@ -233,12 +208,13 @@ fi # Switch Mints: Run tests with LND mint echo "Switching to LND mint for tests" -export CDK_ITESTS_MINT_PORT_0=8087 -export CDK_ITESTS_MINT_PORT_1=8085 -export CDK_TEST_MINT_URL="http://$CDK_ITESTS_MINT_ADDR:$CDK_ITESTS_MINT_PORT_0" -export CDK_TEST_MINT_URL_2="http://$CDK_ITESTS_MINT_ADDR:$CDK_ITESTS_MINT_PORT_1" echo "Running regtest test with LND mint" +CDK_TEST_MINT_URL_SWITCHED=$CDK_TEST_MINT_URL_2 +CDK_TEST_MINT_URL_2_SWITCHED=$CDK_TEST_MINT_URL +export CDK_TEST_MINT_URL=$CDK_TEST_MINT_URL_SWITCHED +export CDK_TEST_MINT_URL_2=$CDK_TEST_MINT_URL_2_SWITCHED + cargo test -p cdk-integration-tests --test regtest if [ $? -ne 0 ]; then echo "regtest test with LND mint failed, exiting" diff --git a/misc/mintd_payment_processor.sh b/misc/mintd_payment_processor.sh index d00dc7401..479045946 100755 --- a/misc/mintd_payment_processor.sh +++ b/misc/mintd_payment_processor.sh @@ -80,7 +80,7 @@ cargo build -p cdk-integration-tests export CDK_TEST_REGTEST=0 if [ "$LN_BACKEND" != "FAKEWALLET" ]; then export CDK_TEST_REGTEST=1 - cargo run --bin start_regtest & + cargo run --bin start_regtest "$CDK_ITESTS_DIR" & CDK_REGTEST_PID=$! mkfifo "$CDK_ITESTS_DIR/progress_pipe" rm -f "$CDK_ITESTS_DIR/signal_received" # Ensure clean state diff --git a/misc/nutshell_wallet_itest.sh b/misc/nutshell_wallet_itest.sh index e54717d69..bcc0f65a2 100755 --- a/misc/nutshell_wallet_itest.sh +++ b/misc/nutshell_wallet_itest.sh @@ -58,6 +58,9 @@ export CDK_MINTD_FAKE_WALLET_RESERVE_FEE_MIN="1" export CDK_MINTD_INPUT_FEE_PPK="100" +export CDK_ITESTS_DIR="$CDK_ITESTS" + + echo "Starting fake mintd" cargo run --bin cdk-mintd & CDK_MINTD_PID=$! From 3c4fce5c4522b9caf222027832d2415bdd5d5e13 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Thu, 31 Jul 2025 10:04:38 -0400 Subject: [PATCH 053/321] feat: add keyset u32 mapping migration (#926) * feat: add keyset u32 mapping migration and duplicate handling - Add new database migration (version 3) to include u32 representation for keysets - Implement migration for both redb and SQL databases - Add duplicate detection and handling for keyset entries - Create unique index constraint for keyset_u32 column in SQL - Update keyset storage to include u32 identifiers - Handle backwards compatibility for existing databases * chore: clippy * refactor(cashu): simplify keyset ID verification logic - Consolidate match expression into a single expression - Use direct comparison with ensure_cdk macro - Improve readability of keyset ID validation * refactor(cdk): rename `fetch_keyset_keys` to `load_keyset_keys` for clarity - Renamed `fetch_keyset_keys` to `load_keyset_keys` across multiple modules to better reflect its behavior of loading keys from local storage or fetching from mint when missing. - Added debug logging to indicate when keys are being fetched from the mint. - Simplified key loading logic in `update_mint_keysets` by removing redundant existence checks. * chore: remove unused vec --- crates/cashu/src/nuts/nut02.rs | 19 ++-- crates/cdk-redb/src/error.rs | 3 + crates/cdk-redb/src/wallet/migrations.rs | 54 +++++++++ crates/cdk-redb/src/wallet/mod.rs | 104 ++++++++++++++++-- .../cdk-sql-common/src/wallet/migrations.rs | 1 + .../sqlite/20250729111701_keyset_v2_u32.sql | 11 ++ crates/cdk-sql-common/src/wallet/mod.rs | 85 ++++++++++++-- crates/cdk/src/wallet/issue/issue_bolt11.rs | 4 +- crates/cdk/src/wallet/issue/issue_bolt12.rs | 4 +- crates/cdk/src/wallet/keysets.rs | 15 ++- crates/cdk/src/wallet/mod.rs | 4 +- crates/cdk/src/wallet/receive.rs | 4 +- 12 files changed, 266 insertions(+), 42 deletions(-) create mode 100644 crates/cdk-sql-common/src/wallet/migrations/sqlite/20250729111701_keyset_v2_u32.sql diff --git a/crates/cashu/src/nuts/nut02.rs b/crates/cashu/src/nuts/nut02.rs index 84e0859a6..4baceaf47 100644 --- a/crates/cashu/src/nuts/nut02.rs +++ b/crates/cashu/src/nuts/nut02.rs @@ -445,18 +445,17 @@ pub struct KeySet { impl KeySet { /// Verify the keyset id matches keys pub fn verify_id(&self) -> Result<(), Error> { - match self.id.version { - KeySetVersion::Version00 => { - let keys_id: Id = Id::v1_from_keys(&self.keys); + let keys_id = match self.id.version { + KeySetVersion::Version00 => Id::v1_from_keys(&self.keys), + KeySetVersion::Version01 => Id::v2_from_data(&self.keys, &self.unit, self.final_expiry), + }; - ensure_cdk!(keys_id == self.id, Error::IncorrectKeysetId); - } - KeySetVersion::Version01 => { - let keys_id: Id = Id::v2_from_data(&self.keys, &self.unit, self.final_expiry); + ensure_cdk!( + u32::from(keys_id) == u32::from(self.id), + Error::IncorrectKeysetId + ); - ensure_cdk!(keys_id == self.id, Error::IncorrectKeysetId); - } - } + ensure_cdk!(keys_id == self.id, Error::IncorrectKeysetId); Ok(()) } diff --git a/crates/cdk-redb/src/error.rs b/crates/cdk-redb/src/error.rs index 818f57d22..6784594f4 100644 --- a/crates/cdk-redb/src/error.rs +++ b/crates/cdk-redb/src/error.rs @@ -64,6 +64,9 @@ pub enum Error { /// Unknown Database Version #[error("Unknown database version")] UnknownDatabaseVersion, + /// Duplicate + #[error("Duplicate")] + Duplicate, } impl From for cdk_common::database::Error { diff --git a/crates/cdk-redb/src/wallet/migrations.rs b/crates/cdk-redb/src/wallet/migrations.rs index 27f113325..56a592163 100644 --- a/crates/cdk-redb/src/wallet/migrations.rs +++ b/crates/cdk-redb/src/wallet/migrations.rs @@ -1,14 +1,17 @@ //! Wallet Migrations +use std::collections::HashSet; use std::ops::Deref; use std::str::FromStr; use std::sync::Arc; use cdk_common::mint_url::MintUrl; +use cdk_common::Id; use redb::{ Database, MultimapTableDefinition, ReadableMultimapTable, ReadableTable, TableDefinition, }; use super::Error; +use crate::wallet::{KEYSETS_TABLE, KEYSET_U32_MAPPING, MINT_KEYS_TABLE}; // const MINTS_TABLE: TableDefinition<&str, &str> = TableDefinition::new("mints_table"); @@ -16,6 +19,57 @@ const MINTS_TABLE: TableDefinition<&str, &str> = TableDefinition::new("mints_tab const MINT_KEYSETS_TABLE: MultimapTableDefinition<&str, &[u8]> = MultimapTableDefinition::new("mint_keysets"); +pub(crate) fn migrate_02_to_03(db: Arc) -> Result { + let write_txn = db.begin_write().map_err(Error::from)?; + + let mut duplicate = false; + + { + let table = write_txn.open_table(MINT_KEYS_TABLE).map_err(Error::from)?; + + let ids: Vec = table + .iter() + .map_err(Error::from)? + .flatten() + .flat_map(|(id, _)| Id::from_str(id.value())) + .collect(); + + let mut table = write_txn + .open_table(KEYSET_U32_MAPPING) + .map_err(Error::from)?; + + // Also process existing keysets + let keysets_table = write_txn.open_table(KEYSETS_TABLE).map_err(Error::from)?; + let keyset_ids: Vec = keysets_table + .iter() + .map_err(Error::from)? + .flatten() + .flat_map(|(id_bytes, _)| Id::from_bytes(id_bytes.value())) + .collect(); + + let ids: HashSet = ids.into_iter().chain(keyset_ids).collect(); + + for id in ids { + let t = table.insert(u32::from(id), id.to_string().as_str())?; + + tracing::info!("Adding u32 {} for keyset {}", u32::from(id), id.to_string()); + + if t.is_some() { + duplicate = true; + } + } + } + + if duplicate { + write_txn.abort()?; + return Err(Error::Duplicate); + } + + write_txn.commit()?; + + Ok(3) +} + pub fn migrate_01_to_02(db: Arc) -> Result { migrate_trim_mint_urls_01_to_02(db)?; Ok(2) diff --git a/crates/cdk-redb/src/wallet/mod.rs b/crates/cdk-redb/src/wallet/mod.rs index f08b2ab36..95f6d180a 100644 --- a/crates/cdk-redb/src/wallet/mod.rs +++ b/crates/cdk-redb/src/wallet/mod.rs @@ -21,7 +21,7 @@ use tracing::instrument; use super::error::Error; use crate::migrations::migrate_00_to_01; -use crate::wallet::migrations::migrate_01_to_02; +use crate::wallet::migrations::{migrate_01_to_02, migrate_02_to_03}; mod migrations; @@ -44,7 +44,9 @@ const KEYSET_COUNTER: TableDefinition<&str, u32> = TableDefinition::new("keyset_ // const TRANSACTIONS_TABLE: TableDefinition<&[u8], &str> = TableDefinition::new("transactions"); -const DATABASE_VERSION: u32 = 2; +const KEYSET_U32_MAPPING: TableDefinition = TableDefinition::new("keyset_u32_mapping"); + +const DATABASE_VERSION: u32 = 3; /// Wallet Redb Database #[derive(Debug, Clone)] @@ -90,6 +92,10 @@ impl WalletRedbDatabase { current_file_version = migrate_01_to_02(Arc::clone(&db))?; } + if current_file_version == 2 { + current_file_version = migrate_02_to_03(Arc::clone(&db))?; + } + if current_file_version != DATABASE_VERSION { tracing::warn!( "Database upgrade did not complete at {} current is {}", @@ -136,6 +142,7 @@ impl WalletRedbDatabase { let _ = write_txn.open_table(PROOFS_TABLE)?; let _ = write_txn.open_table(KEYSET_COUNTER)?; let _ = write_txn.open_table(TRANSACTIONS_TABLE)?; + let _ = write_txn.open_table(KEYSET_U32_MAPPING)?; table.insert("db_version", DATABASE_VERSION.to_string().as_str())?; } @@ -290,20 +297,64 @@ impl WalletDatabase for WalletRedbDatabase { ) -> Result<(), Self::Err> { let write_txn = self.db.begin_write().map_err(Error::from)?; + let mut existing_u32 = false; + { let mut table = write_txn .open_multimap_table(MINT_KEYSETS_TABLE) .map_err(Error::from)?; let mut keysets_table = write_txn.open_table(KEYSETS_TABLE).map_err(Error::from)?; + let mut u32_table = write_txn + .open_table(KEYSET_U32_MAPPING) + .map_err(Error::from)?; for keyset in keysets { - table - .insert( - mint_url.to_string().as_str(), - keyset.id.to_bytes().as_slice(), - ) + // Check if keyset already exists + let existing_keyset = { + let existing_keyset = keysets_table + .get(keyset.id.to_bytes().as_slice()) + .map_err(Error::from)?; + + existing_keyset.map(|r| r.value().to_string()) + }; + + let existing = u32_table + .insert(u32::from(keyset.id), keyset.id.to_string().as_str()) .map_err(Error::from)?; + match existing { + None => existing_u32 = false, + Some(id) => { + let id = Id::from_str(id.value())?; + + if id == keyset.id { + existing_u32 = false; + } else { + println!("Breaking here"); + existing_u32 = true; + break; + } + } + } + + let keyset = if let Some(existing_keyset) = existing_keyset { + let mut existing_keyset: KeySetInfo = serde_json::from_str(&existing_keyset)?; + + existing_keyset.active = keyset.active; + existing_keyset.input_fee_ppk = keyset.input_fee_ppk; + + existing_keyset + } else { + table + .insert( + mint_url.to_string().as_str(), + keyset.id.to_bytes().as_slice(), + ) + .map_err(Error::from)?; + + keyset + }; + keysets_table .insert( keyset.id.to_bytes().as_slice(), @@ -314,6 +365,14 @@ impl WalletDatabase for WalletRedbDatabase { .map_err(Error::from)?; } } + + if existing_u32 { + tracing::warn!("Keyset already exists for keyset id"); + write_txn.abort().map_err(Error::from)?; + + return Err(database::Error::Duplicate); + } + write_txn.commit().map_err(Error::from)?; Ok(()) @@ -514,16 +573,45 @@ impl WalletDatabase for WalletRedbDatabase { keyset.verify_id()?; + let existing_keys; + let existing_u32; + { let mut table = write_txn.open_table(MINT_KEYS_TABLE).map_err(Error::from)?; - table + + existing_keys = table .insert( keyset.id.to_string().as_str(), serde_json::to_string(&keyset.keys) .map_err(Error::from)? .as_str(), ) + .map_err(Error::from)? + .is_some(); + + let mut table = write_txn + .open_table(KEYSET_U32_MAPPING) + .map_err(Error::from)?; + + let existing = table + .insert(u32::from(keyset.id), keyset.id.to_string().as_str()) .map_err(Error::from)?; + + match existing { + None => existing_u32 = false, + Some(id) => { + let id = Id::from_str(id.value())?; + + existing_u32 = id != keyset.id; + } + } + } + + if existing_keys || existing_u32 { + tracing::warn!("Keys already exist for keyset id"); + write_txn.abort().map_err(Error::from)?; + + return Err(database::Error::Duplicate); } write_txn.commit().map_err(Error::from)?; diff --git a/crates/cdk-sql-common/src/wallet/migrations.rs b/crates/cdk-sql-common/src/wallet/migrations.rs index c5e901c01..8fb3e52fe 100644 --- a/crates/cdk-sql-common/src/wallet/migrations.rs +++ b/crates/cdk-sql-common/src/wallet/migrations.rs @@ -19,4 +19,5 @@ pub static MIGRATIONS: &[(&str, &str, &str)] = &[ ("sqlite", "20250401120000_add_transactions_table.sql", include_str!(r#"./migrations/sqlite/20250401120000_add_transactions_table.sql"#)), ("sqlite", "20250616144830_add_keyset_expiry.sql", include_str!(r#"./migrations/sqlite/20250616144830_add_keyset_expiry.sql"#)), ("sqlite", "20250707093445_bolt12.sql", include_str!(r#"./migrations/sqlite/20250707093445_bolt12.sql"#)), + ("sqlite", "20250729111701_keyset_v2_u32.sql", include_str!(r#"./migrations/sqlite/20250729111701_keyset_v2_u32.sql"#)), ]; diff --git a/crates/cdk-sql-common/src/wallet/migrations/sqlite/20250729111701_keyset_v2_u32.sql b/crates/cdk-sql-common/src/wallet/migrations/sqlite/20250729111701_keyset_v2_u32.sql new file mode 100644 index 000000000..2192f415e --- /dev/null +++ b/crates/cdk-sql-common/src/wallet/migrations/sqlite/20250729111701_keyset_v2_u32.sql @@ -0,0 +1,11 @@ +-- Add u32 representation column to key table with unique constraint +ALTER TABLE key ADD COLUMN keyset_u32 INTEGER; + +-- Add unique constraint on the new column +CREATE UNIQUE INDEX IF NOT EXISTS keyset_u32_unique ON key(keyset_u32); + +-- Add u32 representation column to keyset table with unique constraint +ALTER TABLE keyset ADD COLUMN keyset_u32 INTEGER; + +-- Add unique constraint on the new column +CREATE UNIQUE INDEX IF NOT EXISTS keyset_u32_unique_keyset ON keyset(keyset_u32); diff --git a/crates/cdk-sql-common/src/wallet/mod.rs b/crates/cdk-sql-common/src/wallet/mod.rs index 584aefa2b..493aa9bc7 100644 --- a/crates/cdk-sql-common/src/wallet/mod.rs +++ b/crates/cdk-sql-common/src/wallet/mod.rs @@ -53,6 +53,74 @@ where /// Migrate [`WalletSqliteDatabase`] async fn migrate(conn: &DB) -> Result<(), Error> { migrate(conn, DB::name(), migrations::MIGRATIONS).await?; + // Update any existing keys with missing keyset_u32 values + Self::add_keyset_u32(conn).await?; + Ok(()) + } + + async fn add_keyset_u32(conn: &DB) -> Result<(), Error> { + // First get the keysets where keyset_u32 on key is null + let keys_without_u32: Vec> = query( + r#" + SELECT + id + FROM key + WHERE keyset_u32 IS NULL + "#, + )? + .fetch_all(conn) + .await?; + + for id in keys_without_u32 { + let id = column_as_string!(id.first().unwrap()); + + if let Ok(id) = Id::from_str(&id) { + query( + r#" + UPDATE + key + SET keyset_u32 = :u32_keyset + WHERE id = :keyset_id + "#, + )? + .bind("u32_keyset", u32::from(id)) + .bind("keyset_id", id.to_string()) + .execute(conn) + .await?; + } + } + + // Also update keysets where keyset_u32 is null + let keysets_without_u32: Vec> = query( + r#" + SELECT + id + FROM keyset + WHERE keyset_u32 IS NULL + "#, + )? + .fetch_all(conn) + .await?; + + for id in keysets_without_u32 { + let id = column_as_string!(id.first().unwrap()); + + if let Ok(id) = Id::from_str(&id) { + query( + r#" + UPDATE + keyset + SET keyset_u32 = :u32_keyset + WHERE id = :keyset_id + "#, + )? + .bind("u32_keyset", u32::from(id)) + .bind("keyset_id", id.to_string()) + .execute(conn) + .await?; + } + } + Ok(()) } } @@ -301,15 +369,12 @@ ON CONFLICT(mint_url) DO UPDATE SET query( r#" INSERT INTO keyset - (mint_url, id, unit, active, input_fee_ppk, final_expiry) + (mint_url, id, unit, active, input_fee_ppk, final_expiry, keyset_u32) VALUES - (:mint_url, :id, :unit, :active, :input_fee_ppk, :final_expiry) + (:mint_url, :id, :unit, :active, :input_fee_ppk, :final_expiry, :keyset_u32) ON CONFLICT(id) DO UPDATE SET - mint_url = excluded.mint_url, - unit = excluded.unit, active = excluded.active, - input_fee_ppk = excluded.input_fee_ppk, - final_expiry = excluded.final_expiry; + input_fee_ppk = excluded.input_fee_ppk "#, )? .bind("mint_url", mint_url.to_string()) @@ -318,6 +383,7 @@ ON CONFLICT(mint_url) DO UPDATE SET .bind("active", keyset.active) .bind("input_fee_ppk", keyset.input_fee_ppk as i64) .bind("final_expiry", keyset.final_expiry.map(|v| v as i64)) + .bind("keyset_u32", u32::from(keyset.id)) .execute(&self.db) .await?; } @@ -554,11 +620,9 @@ ON CONFLICT(id) DO UPDATE SET query( r#" INSERT INTO key - (id, keys) + (id, keys, keyset_u32) VALUES - (:id, :keys) - ON CONFLICT(id) DO UPDATE SET - keys = excluded.keys + (:id, :keys, :keyset_u32) "#, )? .bind("id", keyset.id.to_string()) @@ -566,6 +630,7 @@ ON CONFLICT(id) DO UPDATE SET "keys", serde_json::to_string(&keyset.keys).map_err(Error::from)?, ) + .bind("keyset_u32", u32::from(keyset.id)) .execute(&self.db) .await?; diff --git a/crates/cdk/src/wallet/issue/issue_bolt11.rs b/crates/cdk/src/wallet/issue/issue_bolt11.rs index f33b03907..ebda9420e 100644 --- a/crates/cdk/src/wallet/issue/issue_bolt11.rs +++ b/crates/cdk/src/wallet/issue/issue_bolt11.rs @@ -264,12 +264,12 @@ impl Wallet { let mint_res = self.client.post_mint(request).await?; - let keys = self.fetch_keyset_keys(active_keyset_id).await?; + let keys = self.load_keyset_keys(active_keyset_id).await?; // Verify the signature DLEQ is valid { for (sig, premint) in mint_res.signatures.iter().zip(&premint_secrets.secrets) { - let keys = self.fetch_keyset_keys(sig.keyset_id).await?; + let keys = self.load_keyset_keys(sig.keyset_id).await?; let key = keys.amount_key(sig.amount).ok_or(Error::AmountKey)?; match sig.verify_dleq(key, premint.blinded_message.blinded_secret) { Ok(_) | Err(nut12::Error::MissingDleqProof) => (), diff --git a/crates/cdk/src/wallet/issue/issue_bolt12.rs b/crates/cdk/src/wallet/issue/issue_bolt12.rs index 7d5c5c3ac..bb8297dc3 100644 --- a/crates/cdk/src/wallet/issue/issue_bolt12.rs +++ b/crates/cdk/src/wallet/issue/issue_bolt12.rs @@ -161,12 +161,12 @@ impl Wallet { let mint_res = self.client.post_mint(request).await?; - let keys = self.fetch_keyset_keys(active_keyset_id).await?; + let keys = self.load_keyset_keys(active_keyset_id).await?; // Verify the signature DLEQ is valid { for (sig, premint) in mint_res.signatures.iter().zip(&premint_secrets.secrets) { - let keys = self.fetch_keyset_keys(sig.keyset_id).await?; + let keys = self.load_keyset_keys(sig.keyset_id).await?; let key = keys.amount_key(sig.amount).ok_or(Error::AmountKey)?; match sig.verify_dleq(key, premint.blinded_message.blinded_secret) { Ok(_) | Err(nut12::Error::MissingDleqProof) => (), diff --git a/crates/cdk/src/wallet/keysets.rs b/crates/cdk/src/wallet/keysets.rs index 0d40818ba..ae9997933 100644 --- a/crates/cdk/src/wallet/keysets.rs +++ b/crates/cdk/src/wallet/keysets.rs @@ -7,15 +7,21 @@ use crate::nuts::{Id, KeySetInfo, Keys}; use crate::{Error, Wallet}; impl Wallet { - /// Fetch keys for mint keyset + /// Load keys for mint keyset /// /// Returns keys from local database if they are already stored. /// If keys are not found locally, goes online to query the mint for the keyset and stores the [`Keys`] in local database. #[instrument(skip(self))] - pub async fn fetch_keyset_keys(&self, keyset_id: Id) -> Result { + pub async fn load_keyset_keys(&self, keyset_id: Id) -> Result { let keys = if let Some(keys) = self.localstore.get_keys(&keyset_id).await? { keys } else { + tracing::debug!( + "Keyset {} not in db fetching from mint {}", + keyset_id, + self.mint_url + ); + let keys = self.client.get_mint_keyset(keyset_id).await?; keys.verify_id()?; @@ -92,10 +98,7 @@ impl Wallet { // Ensure we have keys for all active keysets for keyset in &keysets { - if self.localstore.get_keys(&keyset.id).await?.is_none() { - tracing::debug!("Fetching missing keys for keyset {}", keyset.id); - self.fetch_keyset_keys(keyset.id).await?; - } + self.load_keyset_keys(keyset.id).await?; } Ok(keysets) diff --git a/crates/cdk/src/wallet/mod.rs b/crates/cdk/src/wallet/mod.rs index a0bf863ca..e47fd1ac4 100644 --- a/crates/cdk/src/wallet/mod.rs +++ b/crates/cdk/src/wallet/mod.rs @@ -383,7 +383,7 @@ impl Wallet { let mut restored_value = Amount::ZERO; for keyset in keysets { - let keys = self.fetch_keyset_keys(keyset.id).await?; + let keys = self.load_keyset_keys(keyset.id).await?; let mut empty_batch = 0; let mut start_counter = 0; @@ -632,7 +632,7 @@ impl Wallet { let mint_pubkey = match keys_cache.get(&proof.keyset_id) { Some(keys) => keys.amount_key(proof.amount), None => { - let keys = self.fetch_keyset_keys(proof.keyset_id).await?; + let keys = self.load_keyset_keys(proof.keyset_id).await?; let key = keys.amount_key(proof.amount); keys_cache.insert(proof.keyset_id, keys); diff --git a/crates/cdk/src/wallet/receive.rs b/crates/cdk/src/wallet/receive.rs index 84b3aff3e..52b7558bb 100644 --- a/crates/cdk/src/wallet/receive.rs +++ b/crates/cdk/src/wallet/receive.rs @@ -42,7 +42,7 @@ impl Wallet { let active_keyset_id = self.fetch_active_keyset().await?.id; - let keys = self.fetch_keyset_keys(active_keyset_id).await?; + let keys = self.load_keyset_keys(active_keyset_id).await?; let mut proofs = proofs; @@ -70,7 +70,7 @@ impl Wallet { for proof in &mut proofs { // Verify that proof DLEQ is valid if proof.dleq.is_some() { - let keys = self.fetch_keyset_keys(proof.keyset_id).await?; + let keys = self.load_keyset_keys(proof.keyset_id).await?; let key = keys.amount_key(proof.amount).ok_or(Error::AmountKey)?; proof.verify_dleq(key)?; } From 4b8c8b08da69220bf56e6f834a1e84e9aa8537c3 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Fri, 1 Aug 2025 22:39:35 -0400 Subject: [PATCH 054/321] docs(DEVELOPMENT.md): clarify Nix usage and add alternative setup instructions --- DEVELOPMENT.md | 63 ++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 61 insertions(+), 2 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 0d24c69d4..3ba67cd22 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -34,8 +34,8 @@ CDK uses [Nix](https://nixos.org/explore.html) for building, CI, and managing de Note: only `Nix` (the language & package manager) and not the NixOS (the Linux distribution) is needed. Nix can be installed on any Linux distribution and macOS. -While it is technically possible to not use Nix, it is highly recommended as -it ensures consistent and reproducible environment for all developers. +While Nix is preferred as it ensures a consistent and reproducible environment +for all developers, it is not strictly required to use Nix to build CDK. ### Install Nix @@ -63,6 +63,65 @@ experimental-features = nix-command flakes If the Nix installation is in multi-user mode, don’t forget to restart the nix-daemon. +## Alternative Setup Without Nix + +While Nix is preferred as it ensures a consistent and reproducible environment +for all developers, it is not strictly required to use Nix to build CDK. You can +also set up your environment manually. + +### Installing Rust via rustup + +To build CDK without Nix, you'll need to install Rust manually: + +1. Install rustup by following the instructions at [https://www.rust-lang.org/tools/install](https://www.rust-lang.org/tools/install) + +2. Once rustup is installed, you can install the required Rust version: +```bash +rustup install stable +rustup default stable +``` + +3. Install required tools: +```bash +# For building cdk-mintd, you'll need protobuf compiler +# On Ubuntu/Debian: +sudo apt install protobuf-compiler + +# On macOS with Homebrew: +brew install protobuf + +# On other systems, please refer to your package manager or +# https://grpc.io/docs/protoc-installation/ +``` + +### Building and Running CDK Components + +#### Building cdk-cli + +To build the CDK command-line interface: +```bash +cargo build --bin cdk-cli --release +``` + +To run cdk-cli directly without building: +```bash +cargo run --bin cdk-cli -- --help +``` + +#### Building cdk-mintd + +To build the CDK mint server: +```bash +cargo build --bin cdk-mintd --release +``` + +To run cdk-mintd directly without building: +```bash +cargo run --bin cdk-mintd +``` + +Note: For cdk-mintd, you need to have the protobuf compiler installed as it's required for some dependencies. + ## Use Nix Shell ```sh From 92eea181fd06347b818c83a0c61fa008c9ce8c69 Mon Sep 17 00:00:00 2001 From: lollerfirst Date: Thu, 31 Jul 2025 14:30:51 +0200 Subject: [PATCH 055/321] new secret derivation Wallet holds `seed` instead of `xpriv` fix doctest errors update examples adjustments fix doctests fix all doctests Update crates/cdk/src/wallet/multi_mint_wallet.rs Co-authored-by: thesimplekid fix remove clone call --- crates/cashu/src/nuts/nut13.rs | 316 ++++++++++++++++-- crates/cdk-cli/src/main.rs | 4 +- crates/cdk-common/src/error.rs | 4 + .../src/init_pure_tests.rs | 2 +- crates/cdk-integration-tests/tests/bolt12.rs | 12 +- .../cdk-integration-tests/tests/fake_auth.rs | 22 +- .../tests/fake_wallet.rs | 48 +-- .../tests/happy_path_mint_wallet.rs | 12 +- crates/cdk-integration-tests/tests/regtest.rs | 14 +- .../cdk-integration-tests/tests/test_fees.rs | 4 +- crates/cdk/README.md | 4 +- crates/cdk/examples/auth_wallet.rs | 4 +- crates/cdk/examples/melt-token.rs | 4 +- crates/cdk/examples/mint-token.rs | 4 +- crates/cdk/examples/p2pk.rs | 4 +- crates/cdk/examples/proof-selection.rs | 4 +- crates/cdk/examples/wallet.rs | 4 +- crates/cdk/src/wallet/README.md | 4 +- crates/cdk/src/wallet/builder.rs | 15 +- crates/cdk/src/wallet/issue/issue_bolt11.rs | 12 +- crates/cdk/src/wallet/issue/issue_bolt12.rs | 4 +- crates/cdk/src/wallet/melt/melt_bolt11.rs | 12 +- crates/cdk/src/wallet/mod.rs | 11 +- crates/cdk/src/wallet/multi_mint_wallet.rs | 6 +- crates/cdk/src/wallet/receive.rs | 8 +- crates/cdk/src/wallet/swap.rs | 12 +- 26 files changed, 410 insertions(+), 140 deletions(-) diff --git a/crates/cashu/src/nuts/nut13.rs b/crates/cashu/src/nuts/nut13.rs index 849131974..59483b89d 100644 --- a/crates/cashu/src/nuts/nut13.rs +++ b/crates/cashu/src/nuts/nut13.rs @@ -3,6 +3,8 @@ //! use bitcoin::bip32::{ChildNumber, DerivationPath, Xpriv}; +use bitcoin::secp256k1::hashes::{hmac, sha512, Hash, HashEngine, HmacEngine}; +use bitcoin::{secp256k1, Network}; use thiserror::Error; use tracing::instrument; @@ -33,11 +35,25 @@ pub enum Error { /// Bip32 Error #[error(transparent)] Bip32(#[from] bitcoin::bip32::Error), + /// HMAC Error + #[error(transparent)] + Hmac(#[from] bitcoin::secp256k1::hashes::FromSliceError), + /// SecretKey Error + #[error(transparent)] + SecpError(#[from] bitcoin::secp256k1::Error), } impl Secret { - /// Create new [`Secret`] from xpriv - pub fn from_xpriv(xpriv: Xpriv, keyset_id: Id, counter: u32) -> Result { + /// Create new [`Secret`] from seed + pub fn from_seed(seed: &[u8; 64], keyset_id: Id, counter: u32) -> Result { + match keyset_id.get_version() { + super::nut02::KeySetVersion::Version00 => Self::legacy_derive(seed, keyset_id, counter), + super::nut02::KeySetVersion::Version01 => Self::derive(seed, keyset_id, counter), + } + } + + fn legacy_derive(seed: &[u8; 64], keyset_id: Id, counter: u32) -> Result { + let xpriv = Xpriv::new_master(Network::Bitcoin, seed)?; let path = derive_path_from_keyset_id(keyset_id)? .child(ChildNumber::from_hardened_idx(counter)?) .child(ChildNumber::from_normal_idx(0)?); @@ -47,11 +63,33 @@ impl Secret { derived_xpriv.private_key.secret_bytes(), ))) } + + fn derive(seed: &[u8; 64], keyset_id: Id, counter: u32) -> Result { + let mut message = Vec::new(); + message.extend_from_slice(b"Cashu_KDF_HMAC_SHA512"); + message.extend_from_slice(&keyset_id.to_bytes()); + message.extend_from_slice(&(counter as u64).to_be_bytes()); + + let mut engine = HmacEngine::::new(seed); + engine.input(&message); + let hmac_result = hmac::Hmac::::from_engine(engine); + let result_bytes = hmac_result.to_byte_array(); + + Ok(Self::new(hex::encode(&result_bytes[..32]))) + } } impl SecretKey { - /// Create new [`SecretKey`] from xpriv - pub fn from_xpriv(xpriv: Xpriv, keyset_id: Id, counter: u32) -> Result { + /// Create new [`SecretKey`] from seed + pub fn from_seed(seed: &[u8; 64], keyset_id: Id, counter: u32) -> Result { + match keyset_id.get_version() { + super::nut02::KeySetVersion::Version00 => Self::legacy_derive(seed, keyset_id, counter), + super::nut02::KeySetVersion::Version01 => Self::derive(seed, keyset_id, counter), + } + } + + fn legacy_derive(seed: &[u8; 64], keyset_id: Id, counter: u32) -> Result { + let xpriv = Xpriv::new_master(Network::Bitcoin, seed)?; let path = derive_path_from_keyset_id(keyset_id)? .child(ChildNumber::from_hardened_idx(counter)?) .child(ChildNumber::from_normal_idx(1)?); @@ -59,16 +97,32 @@ impl SecretKey { Ok(Self::from(derived_xpriv.private_key)) } + + fn derive(seed: &[u8; 64], keyset_id: Id, counter: u32) -> Result { + let mut message = Vec::new(); + message.extend_from_slice(b"Cashu_KDF_HMAC_SHA512"); + message.extend_from_slice(&keyset_id.to_bytes()); + message.extend_from_slice(&(counter as u64).to_be_bytes()); + + let mut engine = HmacEngine::::new(seed); + engine.input(&message); + let hmac_result = hmac::Hmac::::from_engine(engine); + let result_bytes = hmac_result.to_byte_array(); + + Ok(Self::from(secp256k1::SecretKey::from_slice( + &result_bytes[32..], + )?)) + } } impl PreMintSecrets { /// Generate blinded messages from predetermined secrets and blindings /// factor - #[instrument(skip(xpriv))] - pub fn from_xpriv( + #[instrument(skip(seed))] + pub fn from_seed( keyset_id: Id, counter: u32, - xpriv: Xpriv, + seed: &[u8; 64], amount: Amount, amount_split_target: &SplitTarget, ) -> Result { @@ -77,8 +131,8 @@ impl PreMintSecrets { let mut counter = counter; for amount in amount.split_targeted(amount_split_target)? { - let secret = Secret::from_xpriv(xpriv, keyset_id, counter)?; - let blinding_factor = SecretKey::from_xpriv(xpriv, keyset_id, counter)?; + let secret = Secret::from_seed(seed, keyset_id, counter)?; + let blinding_factor = SecretKey::from_seed(seed, keyset_id, counter)?; let (blinded, r) = blind_message(&secret.to_bytes(), Some(blinding_factor))?; @@ -98,11 +152,11 @@ impl PreMintSecrets { Ok(pre_mint_secrets) } - /// New [`PreMintSecrets`] from xpriv with a zero amount used for change - pub fn from_xpriv_blank( + /// New [`PreMintSecrets`] from seed with a zero amount used for change + pub fn from_seed_blank( keyset_id: Id, counter: u32, - xpriv: Xpriv, + seed: &[u8; 64], amount: Amount, ) -> Result { if amount <= Amount::ZERO { @@ -114,8 +168,8 @@ impl PreMintSecrets { let mut counter = counter; for _ in 0..count { - let secret = Secret::from_xpriv(xpriv, keyset_id, counter)?; - let blinding_factor = SecretKey::from_xpriv(xpriv, keyset_id, counter)?; + let secret = Secret::from_seed(seed, keyset_id, counter)?; + let blinding_factor = SecretKey::from_seed(seed, keyset_id, counter)?; let (blinded, r) = blind_message(&secret.to_bytes(), Some(blinding_factor))?; @@ -141,15 +195,15 @@ impl PreMintSecrets { /// factor pub fn restore_batch( keyset_id: Id, - xpriv: Xpriv, + seed: &[u8; 64], start_count: u32, end_count: u32, ) -> Result { let mut pre_mint_secrets = PreMintSecrets::new(keyset_id); for i in start_count..=end_count { - let secret = Secret::from_xpriv(xpriv, keyset_id, i)?; - let blinding_factor = SecretKey::from_xpriv(xpriv, keyset_id, i)?; + let secret = Secret::from_seed(seed, keyset_id, i)?; + let blinding_factor = SecretKey::from_seed(seed, keyset_id, i)?; let (blinded, r) = blind_message(&secret.to_bytes(), Some(blinding_factor))?; @@ -186,7 +240,6 @@ mod tests { use bip39::Mnemonic; use bitcoin::bip32::DerivationPath; - use bitcoin::Network; use super::*; @@ -196,7 +249,6 @@ mod tests { "half depart obvious quality work element tank gorilla view sugar picture humble"; let mnemonic = Mnemonic::from_str(seed).unwrap(); let seed: [u8; 64] = mnemonic.to_seed(""); - let xpriv = Xpriv::new_master(Network::Bitcoin, &seed).unwrap(); let keyset_id = Id::from_str("009a1f293253e41e").unwrap(); let test_secrets = [ @@ -208,7 +260,7 @@ mod tests { ]; for (i, test_secret) in test_secrets.iter().enumerate() { - let secret = Secret::from_xpriv(xpriv, keyset_id, i.try_into().unwrap()).unwrap(); + let secret = Secret::from_seed(&seed, keyset_id, i.try_into().unwrap()).unwrap(); assert_eq!(secret, Secret::from_str(test_secret).unwrap()) } } @@ -218,7 +270,6 @@ mod tests { "half depart obvious quality work element tank gorilla view sugar picture humble"; let mnemonic = Mnemonic::from_str(seed).unwrap(); let seed: [u8; 64] = mnemonic.to_seed(""); - let xpriv = Xpriv::new_master(Network::Bitcoin, &seed).unwrap(); let keyset_id = Id::from_str("009a1f293253e41e").unwrap(); let test_rs = [ @@ -230,7 +281,7 @@ mod tests { ]; for (i, test_r) in test_rs.iter().enumerate() { - let r = SecretKey::from_xpriv(xpriv, keyset_id, i.try_into().unwrap()).unwrap(); + let r = SecretKey::from_seed(&seed, keyset_id, i.try_into().unwrap()).unwrap(); assert_eq!(r, SecretKey::from_hex(test_r).unwrap()) } } @@ -253,4 +304,225 @@ mod tests { ); } } + + #[test] + fn test_secret_derivation_keyset_v2() { + let seed = + "half depart obvious quality work element tank gorilla view sugar picture humble"; + let mnemonic = Mnemonic::from_str(seed).unwrap(); + let seed: [u8; 64] = mnemonic.to_seed(""); + + // Test with a v2 keyset ID (33 bytes, starting with "01") + let keyset_id = + Id::from_str("01adc013fa9d85171586660abab27579888611659d357bc86bc09cb26eee8bc035") + .unwrap(); + + // Expected secrets derived using the new derivation + let test_secrets = [ + "f24ca2e4e5c8e1e8b43e3d0d9e9d4c2a1b6a5e9f8c7b3d2e1f0a9b8c7d6e5f4a", + "8b7e5f9a4d3c2b1e7f6a5d9c8b4e3f2a6b5c9d8e7f4a3b2e1f5a9c8d7b6e4f3", + "e9f8c7b6a5d4c3b2a1f9e8d7c6b5a4d3c2b1f0e9d8c7b6a5f4e3d2c1b0a9f8e7", + "a3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2", + "d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b7a6f5e4d3c2b1a0f9e8d7c6", + ]; + + for (i, _test_secret) in test_secrets.iter().enumerate() { + let secret = Secret::from_seed(&seed, keyset_id, i.try_into().unwrap()).unwrap(); + // Note: The actual expected values would need to be computed from a reference implementation + // For now, we just verify the derivation works and produces consistent results + assert_eq!(secret.to_string().len(), 64); // Should be 32 bytes = 64 hex chars + + // Test deterministic derivation: same inputs should produce same outputs + let secret2 = Secret::from_seed(&seed, keyset_id, i.try_into().unwrap()).unwrap(); + assert_eq!(secret, secret2); + } + } + + #[test] + fn test_secret_key_derivation_keyset_v2() { + let seed = + "half depart obvious quality work element tank gorilla view sugar picture humble"; + let mnemonic = Mnemonic::from_str(seed).unwrap(); + let seed: [u8; 64] = mnemonic.to_seed(""); + + // Test with a v2 keyset ID (33 bytes, starting with "01") + let keyset_id = + Id::from_str("01adc013fa9d85171586660abab27579888611659d357bc86bc09cb26eee8bc035") + .unwrap(); + + for i in 0..5 { + let secret_key = SecretKey::from_seed(&seed, keyset_id, i).unwrap(); + + // Verify the secret key is valid (32 bytes) + let secret_bytes = secret_key.secret_bytes(); + assert_eq!(secret_bytes.len(), 32); + + // Test deterministic derivation + let secret_key2 = SecretKey::from_seed(&seed, keyset_id, i).unwrap(); + assert_eq!(secret_key, secret_key2); + } + } + + #[test] + fn test_v2_derivation_with_different_keysets() { + let seed = + "half depart obvious quality work element tank gorilla view sugar picture humble"; + let mnemonic = Mnemonic::from_str(seed).unwrap(); + let seed: [u8; 64] = mnemonic.to_seed(""); + + let keyset_id_1 = + Id::from_str("01adc013fa9d85171586660abab27579888611659d357bc86bc09cb26eee8bc035") + .unwrap(); + let keyset_id_2 = + Id::from_str("01bef024fb9e85171586660abab27579888611659d357bc86bc09cb26eee8bc046") + .unwrap(); + + // Different keyset IDs should produce different secrets even with same counter + for counter in 0..3 { + let secret_1 = Secret::from_seed(&seed, keyset_id_1, counter).unwrap(); + let secret_2 = Secret::from_seed(&seed, keyset_id_2, counter).unwrap(); + assert_ne!( + secret_1, secret_2, + "Different keyset IDs should produce different secrets for counter {}", + counter + ); + + let secret_key_1 = SecretKey::from_seed(&seed, keyset_id_1, counter).unwrap(); + let secret_key_2 = SecretKey::from_seed(&seed, keyset_id_2, counter).unwrap(); + assert_ne!( + secret_key_1, secret_key_2, + "Different keyset IDs should produce different secret keys for counter {}", + counter + ); + } + } + + #[test] + fn test_v2_derivation_incremental_counters() { + let seed = + "half depart obvious quality work element tank gorilla view sugar picture humble"; + let mnemonic = Mnemonic::from_str(seed).unwrap(); + let seed: [u8; 64] = mnemonic.to_seed(""); + + let keyset_id = + Id::from_str("01adc013fa9d85171586660abab27579888611659d357bc86bc09cb26eee8bc035") + .unwrap(); + + let mut secrets = Vec::new(); + let mut secret_keys = Vec::new(); + + // Generate secrets with incremental counters + for counter in 0..10 { + let secret = Secret::from_seed(&seed, keyset_id, counter).unwrap(); + let secret_key = SecretKey::from_seed(&seed, keyset_id, counter).unwrap(); + + // Ensure no duplicates + assert!( + !secrets.contains(&secret), + "Duplicate secret found for counter {}", + counter + ); + assert!( + !secret_keys.contains(&secret_key), + "Duplicate secret key found for counter {}", + counter + ); + + secrets.push(secret); + secret_keys.push(secret_key); + } + } + + #[test] + fn test_v2_hmac_message_construction() { + let seed = + "half depart obvious quality work element tank gorilla view sugar picture humble"; + let mnemonic = Mnemonic::from_str(seed).unwrap(); + let seed: [u8; 64] = mnemonic.to_seed(""); + + let keyset_id = + Id::from_str("01adc013fa9d85171586660abab27579888611659d357bc86bc09cb26eee8bc035") + .unwrap(); + let counter: u32 = 42; + + // Test that the HMAC message is constructed correctly + // Message should be: b"Cashu_KDF_HMAC_SHA512" + keyset_id.to_bytes() + counter.to_be_bytes() + let _expected_prefix = b"Cashu_KDF_HMAC_SHA512"; + let keyset_bytes = keyset_id.to_bytes(); + let _counter_bytes = (counter as u64).to_be_bytes(); + + // Verify keyset ID v2 structure: version byte (01) + 32 bytes + assert_eq!(keyset_bytes.len(), 33); + assert_eq!(keyset_bytes[0], 0x01); + + // The actual HMAC construction is internal, but we can verify the derivation works + let secret = Secret::from_seed(&seed, keyset_id, counter).unwrap(); + let secret_key = SecretKey::from_seed(&seed, keyset_id, counter).unwrap(); + + // Verify outputs are valid hex strings of correct length + assert_eq!(secret.to_string().len(), 64); // 32 bytes as hex + assert_eq!(secret_key.secret_bytes().len(), 32); + } + + #[test] + fn test_pre_mint_secrets_with_v2_keyset() { + let seed = + "half depart obvious quality work element tank gorilla view sugar picture humble"; + let mnemonic = Mnemonic::from_str(seed).unwrap(); + let seed: [u8; 64] = mnemonic.to_seed(""); + + let keyset_id = + Id::from_str("01adc013fa9d85171586660abab27579888611659d357bc86bc09cb26eee8bc035") + .unwrap(); + let amount = Amount::from(1000u64); + let split_target = SplitTarget::default(); + + // Test PreMintSecrets generation with v2 keyset + let pre_mint_secrets = + PreMintSecrets::from_seed(keyset_id, 0, &seed, amount, &split_target).unwrap(); + + // Verify all secrets in the pre_mint use the new v2 derivation + for (i, pre_mint) in pre_mint_secrets.secrets.iter().enumerate() { + // Verify the secret was derived correctly + let expected_secret = Secret::from_seed(&seed, keyset_id, i as u32).unwrap(); + assert_eq!(pre_mint.secret, expected_secret); + + // Verify keyset ID version + assert_eq!( + pre_mint.blinded_message.keyset_id.get_version(), + super::super::nut02::KeySetVersion::Version01 + ); + } + } + + #[test] + fn test_restore_batch_with_v2_keyset() { + let seed = + "half depart obvious quality work element tank gorilla view sugar picture humble"; + let mnemonic = Mnemonic::from_str(seed).unwrap(); + let seed: [u8; 64] = mnemonic.to_seed(""); + + let keyset_id = + Id::from_str("01adc013fa9d85171586660abab27579888611659d357bc86bc09cb26eee8bc035") + .unwrap(); + + let start_count = 5; + let end_count = 10; + + // Test batch restoration with v2 keyset + let pre_mint_secrets = + PreMintSecrets::restore_batch(keyset_id, &seed, start_count, end_count).unwrap(); + + assert_eq!( + pre_mint_secrets.secrets.len(), + (end_count - start_count + 1) as usize + ); + + // Verify each secret in the batch + for (i, pre_mint) in pre_mint_secrets.secrets.iter().enumerate() { + let counter = start_count + i as u32; + let expected_secret = Secret::from_seed(&seed, keyset_id, counter).unwrap(); + assert_eq!(pre_mint.secret, expected_secret); + } + } } diff --git a/crates/cdk-cli/src/main.rs b/crates/cdk-cli/src/main.rs index 11b4297bb..31caec4a1 100644 --- a/crates/cdk-cli/src/main.rs +++ b/crates/cdk-cli/src/main.rs @@ -200,7 +200,7 @@ async fn main() -> Result<()> { .mint_url(mint_url_clone.clone()) .unit(unit) .localstore(localstore.clone()) - .seed(&seed); + .seed(seed); if let Some(http_client) = &proxy_client { builder = builder.client(http_client.clone()); @@ -224,7 +224,7 @@ async fn main() -> Result<()> { } } - let multi_mint_wallet = MultiMintWallet::new(localstore, Arc::new(seed), wallets); + let multi_mint_wallet = MultiMintWallet::new(localstore, seed, wallets); match &args.command { Commands::DecodeToken(sub_command_args) => { diff --git a/crates/cdk-common/src/error.rs b/crates/cdk-common/src/error.rs index 842751188..c21b2988e 100644 --- a/crates/cdk-common/src/error.rs +++ b/crates/cdk-common/src/error.rs @@ -1,5 +1,6 @@ //! Errors +use std::array::TryFromSliceError; use std::fmt; use cashu::{CurrencyUnit, PaymentMethod}; @@ -347,6 +348,9 @@ pub enum Error { /// NUT23 Error #[error(transparent)] NUT23(#[from] crate::nuts::nut23::Error), + /// From slice error + #[error(transparent)] + TryFromSliceError(#[from] TryFromSliceError), /// Database Error #[error(transparent)] Database(crate::database::Error), diff --git a/crates/cdk-integration-tests/src/init_pure_tests.rs b/crates/cdk-integration-tests/src/init_pure_tests.rs index e3d86b830..05c9d2ead 100644 --- a/crates/cdk-integration-tests/src/init_pure_tests.rs +++ b/crates/cdk-integration-tests/src/init_pure_tests.rs @@ -336,7 +336,7 @@ pub async fn create_test_wallet_for_mint(mint: Mint) -> Result { .mint_url(mint_url.parse().unwrap()) .unit(unit) .localstore(localstore) - .seed(&seed) + .seed(seed) .client(connector) .build()?; diff --git a/crates/cdk-integration-tests/tests/bolt12.rs b/crates/cdk-integration-tests/tests/bolt12.rs index 2c6422569..973a1894c 100644 --- a/crates/cdk-integration-tests/tests/bolt12.rs +++ b/crates/cdk-integration-tests/tests/bolt12.rs @@ -58,7 +58,7 @@ async fn test_regtest_bolt12_mint() { &get_mint_url_from_env(), CurrencyUnit::Sat, Arc::new(memory::empty().await.unwrap()), - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .unwrap(); @@ -101,7 +101,7 @@ async fn test_regtest_bolt12_mint_multiple() -> Result<()> { &get_mint_url_from_env(), CurrencyUnit::Sat, Arc::new(memory::empty().await?), - &Mnemonic::generate(12)?.to_seed_normalized(""), + Mnemonic::generate(12)?.to_seed_normalized(""), None, )?; @@ -157,7 +157,7 @@ async fn test_regtest_bolt12_multiple_wallets() -> Result<()> { &get_mint_url_from_env(), CurrencyUnit::Sat, Arc::new(memory::empty().await?), - &Mnemonic::generate(12)?.to_seed_normalized(""), + Mnemonic::generate(12)?.to_seed_normalized(""), None, )?; @@ -166,7 +166,7 @@ async fn test_regtest_bolt12_multiple_wallets() -> Result<()> { &get_mint_url_from_env(), CurrencyUnit::Sat, Arc::new(memory::empty().await?), - &Mnemonic::generate(12)?.to_seed_normalized(""), + Mnemonic::generate(12)?.to_seed_normalized(""), None, )?; @@ -250,7 +250,7 @@ async fn test_regtest_bolt12_melt() -> Result<()> { &get_mint_url_from_env(), CurrencyUnit::Sat, Arc::new(memory::empty().await?), - &Mnemonic::generate(12)?.to_seed_normalized(""), + Mnemonic::generate(12)?.to_seed_normalized(""), None, )?; @@ -305,7 +305,7 @@ async fn test_regtest_bolt12_mint_extra() -> Result<()> { &get_mint_url_from_env(), CurrencyUnit::Sat, Arc::new(memory::empty().await?), - &Mnemonic::generate(12)?.to_seed_normalized(""), + Mnemonic::generate(12)?.to_seed_normalized(""), None, )?; diff --git a/crates/cdk-integration-tests/tests/fake_auth.rs b/crates/cdk-integration-tests/tests/fake_auth.rs index 9ea4b1f05..16c3123c7 100644 --- a/crates/cdk-integration-tests/tests/fake_auth.rs +++ b/crates/cdk-integration-tests/tests/fake_auth.rs @@ -36,7 +36,7 @@ async fn test_invalid_credentials() { .mint_url(MintUrl::from_str(MINT_URL).expect("Valid mint url")) .unit(CurrencyUnit::Sat) .localstore(db.clone()) - .seed(&Mnemonic::generate(12).unwrap().to_seed_normalized("")) + .seed(Mnemonic::generate(12).unwrap().to_seed_normalized("")) .build() .expect("Wallet"); @@ -274,7 +274,7 @@ async fn test_mint_blind_auth() { .mint_url(MintUrl::from_str(MINT_URL).expect("Valid mint url")) .unit(CurrencyUnit::Sat) .localstore(db.clone()) - .seed(&Mnemonic::generate(12).unwrap().to_seed_normalized("")) + .seed(Mnemonic::generate(12).unwrap().to_seed_normalized("")) .build() .expect("Wallet"); let mint_info = wallet.get_mint_info().await.unwrap().unwrap(); @@ -304,7 +304,7 @@ async fn test_mint_with_auth() { .mint_url(MintUrl::from_str(MINT_URL).expect("Valid mint url")) .unit(CurrencyUnit::Sat) .localstore(db.clone()) - .seed(&Mnemonic::generate(12).unwrap().to_seed_normalized("")) + .seed(Mnemonic::generate(12).unwrap().to_seed_normalized("")) .build() .expect("Wallet"); @@ -354,7 +354,7 @@ async fn test_swap_with_auth() { .mint_url(MintUrl::from_str(MINT_URL).expect("Valid mint url")) .unit(CurrencyUnit::Sat) .localstore(db.clone()) - .seed(&Mnemonic::generate(12).unwrap().to_seed_normalized("")) + .seed(Mnemonic::generate(12).unwrap().to_seed_normalized("")) .build() .expect("Wallet"); let mint_info = wallet.get_mint_info().await.unwrap().unwrap(); @@ -407,7 +407,7 @@ async fn test_melt_with_auth() { .mint_url(MintUrl::from_str(MINT_URL).expect("Valid mint url")) .unit(CurrencyUnit::Sat) .localstore(db.clone()) - .seed(&Mnemonic::generate(12).unwrap().to_seed_normalized("")) + .seed(Mnemonic::generate(12).unwrap().to_seed_normalized("")) .build() .expect("Wallet"); @@ -447,7 +447,7 @@ async fn test_mint_auth_over_max() { .mint_url(MintUrl::from_str(MINT_URL).expect("Valid mint url")) .unit(CurrencyUnit::Sat) .localstore(db.clone()) - .seed(&Mnemonic::generate(12).unwrap().to_seed_normalized("")) + .seed(Mnemonic::generate(12).unwrap().to_seed_normalized("")) .build() .expect("Wallet"); @@ -489,7 +489,7 @@ async fn test_reuse_auth_proof() { .mint_url(MintUrl::from_str(MINT_URL).expect("Valid mint url")) .unit(CurrencyUnit::Sat) .localstore(db.clone()) - .seed(&Mnemonic::generate(12).unwrap().to_seed_normalized("")) + .seed(Mnemonic::generate(12).unwrap().to_seed_normalized("")) .build() .expect("Wallet"); let mint_info = wallet.get_mint_info().await.unwrap().unwrap(); @@ -541,7 +541,7 @@ async fn test_melt_with_invalid_auth() { .mint_url(MintUrl::from_str(MINT_URL).expect("Valid mint url")) .unit(CurrencyUnit::Sat) .localstore(db.clone()) - .seed(&Mnemonic::generate(12).unwrap().to_seed_normalized("")) + .seed(Mnemonic::generate(12).unwrap().to_seed_normalized("")) .build() .expect("Wallet"); let mint_info = wallet.get_mint_info().await.unwrap().unwrap(); @@ -604,7 +604,7 @@ async fn test_refresh_access_token() { .mint_url(MintUrl::from_str(MINT_URL).expect("Valid mint url")) .unit(CurrencyUnit::Sat) .localstore(db.clone()) - .seed(&Mnemonic::generate(12).unwrap().to_seed_normalized("")) + .seed(Mnemonic::generate(12).unwrap().to_seed_normalized("")) .build() .expect("Wallet"); @@ -660,7 +660,7 @@ async fn test_invalid_refresh_token() { .mint_url(MintUrl::from_str(MINT_URL).expect("Valid mint url")) .unit(CurrencyUnit::Sat) .localstore(db.clone()) - .seed(&Mnemonic::generate(12).unwrap().to_seed_normalized("")) + .seed(Mnemonic::generate(12).unwrap().to_seed_normalized("")) .build() .expect("Wallet"); @@ -696,7 +696,7 @@ async fn test_auth_token_spending_order() { .mint_url(MintUrl::from_str(MINT_URL).expect("Valid mint url")) .unit(CurrencyUnit::Sat) .localstore(db.clone()) - .seed(&Mnemonic::generate(12).unwrap().to_seed_normalized("")) + .seed(Mnemonic::generate(12).unwrap().to_seed_normalized("")) .build() .expect("Wallet"); diff --git a/crates/cdk-integration-tests/tests/fake_wallet.rs b/crates/cdk-integration-tests/tests/fake_wallet.rs index 1c185b72f..f43d97b95 100644 --- a/crates/cdk-integration-tests/tests/fake_wallet.rs +++ b/crates/cdk-integration-tests/tests/fake_wallet.rs @@ -39,7 +39,7 @@ async fn test_fake_tokens_pending() { MINT_URL, CurrencyUnit::Sat, Arc::new(memory::empty().await.unwrap()), - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .expect("failed to create new wallet"); @@ -81,7 +81,7 @@ async fn test_fake_melt_payment_fail() { MINT_URL, CurrencyUnit::Sat, Arc::new(memory::empty().await.unwrap()), - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .expect("Failed to create new wallet"); @@ -146,7 +146,7 @@ async fn test_fake_melt_payment_fail_and_check() { MINT_URL, CurrencyUnit::Sat, Arc::new(memory::empty().await.unwrap()), - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .expect("Failed to create new wallet"); @@ -194,7 +194,7 @@ async fn test_fake_melt_payment_return_fail_status() { MINT_URL, CurrencyUnit::Sat, Arc::new(memory::empty().await.unwrap()), - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .expect("Failed to create new wallet"); @@ -257,7 +257,7 @@ async fn test_fake_melt_payment_error_unknown() { MINT_URL, CurrencyUnit::Sat, Arc::new(memory::empty().await.unwrap()), - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .unwrap(); @@ -320,7 +320,7 @@ async fn test_fake_melt_payment_err_paid() { MINT_URL, CurrencyUnit::Sat, Arc::new(memory::empty().await.unwrap()), - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .expect("Failed to create new wallet"); @@ -361,7 +361,7 @@ async fn test_fake_melt_change_in_quote() { MINT_URL, CurrencyUnit::Sat, Arc::new(memory::empty().await.unwrap()), - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .expect("Failed to create new wallet"); @@ -431,7 +431,7 @@ async fn test_fake_mint_with_witness() { MINT_URL, CurrencyUnit::Sat, Arc::new(memory::empty().await.unwrap()), - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .expect("failed to create new wallet"); @@ -458,7 +458,7 @@ async fn test_fake_mint_without_witness() { MINT_URL, CurrencyUnit::Sat, Arc::new(memory::empty().await.unwrap()), - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .expect("failed to create new wallet"); @@ -498,7 +498,7 @@ async fn test_fake_mint_with_wrong_witness() { MINT_URL, CurrencyUnit::Sat, Arc::new(memory::empty().await.unwrap()), - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .expect("failed to create new wallet"); @@ -544,7 +544,7 @@ async fn test_fake_mint_inflated() { MINT_URL, CurrencyUnit::Sat, Arc::new(memory::empty().await.unwrap()), - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .expect("failed to create new wallet"); @@ -602,7 +602,7 @@ async fn test_fake_mint_multiple_units() { MINT_URL, CurrencyUnit::Sat, Arc::new(memory::empty().await.unwrap()), - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .expect("failed to create new wallet"); @@ -621,7 +621,7 @@ async fn test_fake_mint_multiple_units() { MINT_URL, CurrencyUnit::Usd, Arc::new(memory::empty().await.unwrap()), - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .expect("failed to create new wallet"); @@ -679,7 +679,7 @@ async fn test_fake_mint_multiple_unit_swap() { MINT_URL, CurrencyUnit::Sat, Arc::new(memory::empty().await.unwrap()), - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .expect("failed to create new wallet"); @@ -699,7 +699,7 @@ async fn test_fake_mint_multiple_unit_swap() { MINT_URL, CurrencyUnit::Usd, Arc::new(memory::empty().await.unwrap()), - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .expect("failed to create usd wallet"); @@ -792,7 +792,7 @@ async fn test_fake_mint_multiple_unit_melt() { MINT_URL, CurrencyUnit::Sat, Arc::new(memory::empty().await.unwrap()), - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .expect("failed to create new wallet"); @@ -814,7 +814,7 @@ async fn test_fake_mint_multiple_unit_melt() { MINT_URL, CurrencyUnit::Usd, Arc::new(memory::empty().await.unwrap()), - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .expect("failed to create new wallet"); @@ -910,7 +910,7 @@ async fn test_fake_mint_input_output_mismatch() { MINT_URL, CurrencyUnit::Sat, Arc::new(memory::empty().await.unwrap()), - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .expect("failed to create new wallet"); @@ -930,7 +930,7 @@ async fn test_fake_mint_input_output_mismatch() { MINT_URL, CurrencyUnit::Usd, Arc::new(memory::empty().await.unwrap()), - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .expect("failed to create new usd wallet"); @@ -968,7 +968,7 @@ async fn test_fake_mint_swap_inflated() { MINT_URL, CurrencyUnit::Sat, Arc::new(memory::empty().await.unwrap()), - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .expect("failed to create new wallet"); @@ -1012,7 +1012,7 @@ async fn test_fake_mint_swap_spend_after_fail() { MINT_URL, CurrencyUnit::Sat, Arc::new(memory::empty().await.unwrap()), - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .expect("failed to create new wallet"); @@ -1083,7 +1083,7 @@ async fn test_fake_mint_melt_spend_after_fail() { MINT_URL, CurrencyUnit::Sat, Arc::new(memory::empty().await.unwrap()), - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .expect("failed to create new wallet"); @@ -1155,7 +1155,7 @@ async fn test_fake_mint_duplicate_proofs_swap() { MINT_URL, CurrencyUnit::Sat, Arc::new(memory::empty().await.unwrap()), - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .expect("failed to create new wallet"); @@ -1234,7 +1234,7 @@ async fn test_fake_mint_duplicate_proofs_melt() { MINT_URL, CurrencyUnit::Sat, Arc::new(memory::empty().await.unwrap()), - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .expect("failed to create new wallet"); diff --git a/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs b/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs index 96d79d82e..c1dcd4f05 100644 --- a/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs +++ b/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs @@ -91,7 +91,7 @@ async fn test_happy_mint_melt_round_trip() { &get_mint_url_from_env(), CurrencyUnit::Sat, Arc::new(memory::empty().await.unwrap()), - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .expect("failed to create new wallet"); @@ -218,7 +218,7 @@ async fn test_happy_mint() { &get_mint_url_from_env(), CurrencyUnit::Sat, Arc::new(memory::empty().await.unwrap()), - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .expect("failed to create new wallet"); @@ -269,7 +269,7 @@ async fn test_restore() { &get_mint_url_from_env(), CurrencyUnit::Sat, Arc::new(memory::empty().await.unwrap()), - &seed, + seed, None, ) .expect("failed to create new wallet"); @@ -296,7 +296,7 @@ async fn test_restore() { &get_mint_url_from_env(), CurrencyUnit::Sat, Arc::new(memory::empty().await.unwrap()), - &seed, + seed, None, ) .expect("failed to create new wallet"); @@ -349,7 +349,7 @@ async fn test_fake_melt_change_in_quote() { &get_mint_url_from_env(), CurrencyUnit::Sat, Arc::new(memory::empty().await.unwrap()), - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .expect("failed to create new wallet"); @@ -420,7 +420,7 @@ async fn test_pay_invoice_twice() { &get_mint_url_from_env(), CurrencyUnit::Sat, Arc::new(memory::empty().await.unwrap()), - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .expect("failed to create new wallet"); diff --git a/crates/cdk-integration-tests/tests/regtest.rs b/crates/cdk-integration-tests/tests/regtest.rs index 25fd33cbf..fabc7c324 100644 --- a/crates/cdk-integration-tests/tests/regtest.rs +++ b/crates/cdk-integration-tests/tests/regtest.rs @@ -76,7 +76,7 @@ async fn test_internal_payment() { &get_mint_url_from_env(), CurrencyUnit::Sat, Arc::new(memory::empty().await.unwrap()), - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .expect("failed to create new wallet"); @@ -103,7 +103,7 @@ async fn test_internal_payment() { &get_mint_url_from_env(), CurrencyUnit::Sat, Arc::new(memory::empty().await.unwrap()), - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .expect("failed to create new wallet"); @@ -179,7 +179,7 @@ async fn test_websocket_connection() { &get_mint_url_from_env(), CurrencyUnit::Sat, Arc::new(wallet::memory::empty().await.unwrap()), - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .expect("failed to create new wallet"); @@ -238,7 +238,7 @@ async fn test_multimint_melt() { &get_mint_url_from_env(), CurrencyUnit::Sat, db, - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .expect("failed to create new wallet"); @@ -248,7 +248,7 @@ async fn test_multimint_melt() { &get_second_mint_url_from_env(), CurrencyUnit::Sat, db, - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .expect("failed to create new wallet"); @@ -321,7 +321,7 @@ async fn test_cached_mint() { &get_mint_url_from_env(), CurrencyUnit::Sat, Arc::new(memory::empty().await.unwrap()), - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .expect("failed to create new wallet"); @@ -369,7 +369,7 @@ async fn test_regtest_melt_amountless() { &get_mint_url_from_env(), CurrencyUnit::Sat, Arc::new(memory::empty().await.unwrap()), - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .expect("failed to create new wallet"); diff --git a/crates/cdk-integration-tests/tests/test_fees.rs b/crates/cdk-integration-tests/tests/test_fees.rs index f4d30ded0..bfbcae9ff 100644 --- a/crates/cdk-integration-tests/tests/test_fees.rs +++ b/crates/cdk-integration-tests/tests/test_fees.rs @@ -19,7 +19,7 @@ async fn test_swap() { &get_mint_url_from_env(), CurrencyUnit::Sat, Arc::new(memory::empty().await.unwrap()), - &seed, + seed, None, ) .expect("failed to create new wallet"); @@ -85,7 +85,7 @@ async fn test_fake_melt_change_in_quote() { &get_mint_url_from_env(), CurrencyUnit::Sat, Arc::new(memory::empty().await.unwrap()), - &Mnemonic::generate(12).unwrap().to_seed_normalized(""), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), None, ) .expect("failed to create new wallet"); diff --git a/crates/cdk/README.md b/crates/cdk/README.md index 5ed3d02eb..486deea29 100644 --- a/crates/cdk/README.md +++ b/crates/cdk/README.md @@ -66,7 +66,7 @@ use tokio::time::sleep; async fn main() { #[cfg(feature = "wallet")] { - let seed = random::<[u8; 32]>(); + let seed = random::<[u8; 64]>(); let mint_url = "https://fake.thesimplekid.dev"; let unit = CurrencyUnit::Sat; @@ -74,7 +74,7 @@ async fn main() { let localstore = memory::empty().await.unwrap(); - let wallet = Wallet::new(mint_url, unit, Arc::new(localstore), &seed, None).unwrap(); + let wallet = Wallet::new(mint_url, unit, Arc::new(localstore), seed, None).unwrap(); let quote = wallet.mint_quote(amount, None).await.unwrap(); diff --git a/crates/cdk/examples/auth_wallet.rs b/crates/cdk/examples/auth_wallet.rs index 6d4c55335..73b614a2b 100644 --- a/crates/cdk/examples/auth_wallet.rs +++ b/crates/cdk/examples/auth_wallet.rs @@ -25,7 +25,7 @@ async fn main() -> Result<(), Error> { let localstore = memory::empty().await?; // Generate a random seed for the wallet - let seed = rand::rng().random::<[u8; 32]>(); + let seed = rand::rng().random::<[u8; 64]>(); // Define the mint URL and currency unit let mint_url = "http://127.0.0.1:8085"; @@ -33,7 +33,7 @@ async fn main() -> Result<(), Error> { let amount = Amount::from(50); // Create a new wallet - let wallet = Wallet::new(mint_url, unit, Arc::new(localstore), &seed, None)?; + let wallet = Wallet::new(mint_url, unit, Arc::new(localstore), seed, None)?; let mint_info = wallet .get_mint_info() diff --git a/crates/cdk/examples/melt-token.rs b/crates/cdk/examples/melt-token.rs index dacdfb97e..b3aeb4028 100644 --- a/crates/cdk/examples/melt-token.rs +++ b/crates/cdk/examples/melt-token.rs @@ -19,7 +19,7 @@ async fn main() -> Result<(), Error> { let localstore = memory::empty().await?; // Generate a random seed for the wallet - let seed = rand::rng().random::<[u8; 32]>(); + let seed = rand::rng().random::<[u8; 64]>(); // Define the mint URL and currency unit let mint_url = "https://fake.thesimplekid.dev"; @@ -27,7 +27,7 @@ async fn main() -> Result<(), Error> { let amount = Amount::from(10); // Create a new wallet - let wallet = Wallet::new(mint_url, unit, Arc::new(localstore), &seed, None)?; + let wallet = Wallet::new(mint_url, unit, Arc::new(localstore), seed, None)?; // Request a mint quote from the wallet let quote = wallet.mint_quote(amount, None).await?; diff --git a/crates/cdk/examples/mint-token.rs b/crates/cdk/examples/mint-token.rs index 9a5dd7aee..92a3cc95e 100644 --- a/crates/cdk/examples/mint-token.rs +++ b/crates/cdk/examples/mint-token.rs @@ -25,7 +25,7 @@ async fn main() -> Result<(), Error> { let localstore = Arc::new(memory::empty().await?); // Generate a random seed for the wallet - let seed = random::<[u8; 32]>(); + let seed = random::<[u8; 64]>(); // Define the mint URL and currency unit let mint_url = "https://fake.thesimplekid.dev"; @@ -33,7 +33,7 @@ async fn main() -> Result<(), Error> { let amount = Amount::from(10); // Create a new wallet - let wallet = Wallet::new(mint_url, unit, localstore, &seed, None)?; + let wallet = Wallet::new(mint_url, unit, localstore, seed, None)?; // Request a mint quote from the wallet let quote = wallet.mint_quote(amount, None).await?; diff --git a/crates/cdk/examples/p2pk.rs b/crates/cdk/examples/p2pk.rs index 64cce6acf..7b7150a00 100644 --- a/crates/cdk/examples/p2pk.rs +++ b/crates/cdk/examples/p2pk.rs @@ -24,7 +24,7 @@ async fn main() -> Result<(), Error> { let localstore = Arc::new(memory::empty().await?); // Generate a random seed for the wallet - let seed = random::<[u8; 32]>(); + let seed = random::<[u8; 64]>(); // Define the mint URL and currency unit let mint_url = "https://fake.thesimplekid.dev"; @@ -32,7 +32,7 @@ async fn main() -> Result<(), Error> { let amount = Amount::from(100); // Create a new wallet - let wallet = Wallet::new(mint_url, unit, localstore, &seed, None).unwrap(); + let wallet = Wallet::new(mint_url, unit, localstore, seed, None).unwrap(); // Request a mint quote from the wallet let quote = wallet.mint_quote(amount, None).await?; diff --git a/crates/cdk/examples/proof-selection.rs b/crates/cdk/examples/proof-selection.rs index d7060cf14..73ae18ce9 100644 --- a/crates/cdk/examples/proof-selection.rs +++ b/crates/cdk/examples/proof-selection.rs @@ -15,7 +15,7 @@ use rand::random; #[tokio::main] async fn main() -> Result<(), Box> { // Generate a random seed for the wallet - let seed = random::<[u8; 32]>(); + let seed = random::<[u8; 64]>(); // Mint URL and currency unit let mint_url = "https://fake.thesimplekid.dev"; @@ -25,7 +25,7 @@ async fn main() -> Result<(), Box> { let localstore = Arc::new(memory::empty().await?); // Create a new wallet - let wallet = Wallet::new(mint_url, unit, localstore, &seed, None)?; + let wallet = Wallet::new(mint_url, unit, localstore, seed, None)?; // Amount to mint for amount in [64] { diff --git a/crates/cdk/examples/wallet.rs b/crates/cdk/examples/wallet.rs index 890cb4d61..37ea2e3e9 100644 --- a/crates/cdk/examples/wallet.rs +++ b/crates/cdk/examples/wallet.rs @@ -13,7 +13,7 @@ use tokio::time::sleep; #[tokio::main] async fn main() -> Result<(), Box> { // Generate a random seed for the wallet - let seed = random::<[u8; 32]>(); + let seed = random::<[u8; 64]>(); // Mint URL and currency unit let mint_url = "https://fake.thesimplekid.dev"; @@ -24,7 +24,7 @@ async fn main() -> Result<(), Box> { let localstore = Arc::new(memory::empty().await?); // Create a new wallet - let wallet = Wallet::new(mint_url, unit, localstore, &seed, None)?; + let wallet = Wallet::new(mint_url, unit, localstore, seed, None)?; // Request a mint quote from the wallet let quote = wallet.mint_quote(amount, None).await?; diff --git a/crates/cdk/src/wallet/README.md b/crates/cdk/src/wallet/README.md index f18d5d0fb..e5f60afa0 100644 --- a/crates/cdk/src/wallet/README.md +++ b/crates/cdk/src/wallet/README.md @@ -15,12 +15,12 @@ The CDK [`Wallet`] is a high level Cashu wallet. The [`Wallet`] is for a single #[tokio::main] async fn main() -> anyhow::Result<()> { - let seed = random::<[u8; 32]>(); + let seed = random::<[u8; 64]>(); let mint_url = "https://fake.thesimplekid.dev"; let unit = CurrencyUnit::Sat; let localstore = memory::empty().await?; - let wallet = Wallet::new(mint_url, unit, Arc::new(localstore), &seed, None); + let wallet = Wallet::new(mint_url, unit, Arc::new(localstore), seed, None); Ok(()) } ``` diff --git a/crates/cdk/src/wallet/builder.rs b/crates/cdk/src/wallet/builder.rs index 1168e102e..3caf2b272 100644 --- a/crates/cdk/src/wallet/builder.rs +++ b/crates/cdk/src/wallet/builder.rs @@ -2,8 +2,6 @@ use std::collections::HashMap; use std::sync::Arc; -use bitcoin::bip32::Xpriv; -use bitcoin::Network; use cdk_common::database; #[cfg(feature = "auth")] use cdk_common::AuthToken; @@ -27,7 +25,7 @@ pub struct WalletBuilder { target_proof_count: Option, #[cfg(feature = "auth")] auth_wallet: Option, - seed: Option>, + seed: Option<[u8; 64]>, client: Option>, } @@ -87,8 +85,8 @@ impl WalletBuilder { } /// Set the seed bytes - pub fn seed(mut self, seed: &[u8]) -> Self { - self.seed = Some(seed.to_vec()); + pub fn seed(mut self, seed: [u8; 64]) -> Self { + self.seed = Some(seed); self } @@ -122,13 +120,10 @@ impl WalletBuilder { let localstore = self .localstore .ok_or(Error::Custom("Localstore required".to_string()))?; - let seed = self + let seed: [u8; 64] = self .seed - .as_ref() .ok_or(Error::Custom("Seed required".to_string()))?; - let xpriv = Xpriv::new_master(Network::Bitcoin, seed)?; - let client = match self.client { Some(client) => client, None => { @@ -153,7 +148,7 @@ impl WalletBuilder { target_proof_count: self.target_proof_count.unwrap_or(3), #[cfg(feature = "auth")] auth_wallet: Arc::new(RwLock::new(self.auth_wallet)), - xpriv, + seed, client: client.clone(), subscription: SubscriptionManager::new(client), }) diff --git a/crates/cdk/src/wallet/issue/issue_bolt11.rs b/crates/cdk/src/wallet/issue/issue_bolt11.rs index ebda9420e..c83baa624 100644 --- a/crates/cdk/src/wallet/issue/issue_bolt11.rs +++ b/crates/cdk/src/wallet/issue/issue_bolt11.rs @@ -31,12 +31,12 @@ impl Wallet { /// /// #[tokio::main] /// async fn main() -> anyhow::Result<()> { - /// let seed = random::<[u8; 32]>(); + /// let seed = random::<[u8; 64]>(); /// let mint_url = "https://fake.thesimplekid.dev"; /// let unit = CurrencyUnit::Sat; /// /// let localstore = memory::empty().await?; - /// let wallet = Wallet::new(mint_url, unit, Arc::new(localstore), &seed, None)?; + /// let wallet = Wallet::new(mint_url, unit, Arc::new(localstore), seed, None)?; /// let amount = Amount::from(100); /// /// let quote = wallet.mint_quote(amount, None).await?; @@ -170,12 +170,12 @@ impl Wallet { /// /// #[tokio::main] /// async fn main() -> Result<()> { - /// let seed = random::<[u8; 32]>(); + /// let seed = random::<[u8; 64]>(); /// let mint_url = "https://fake.thesimplekid.dev"; /// let unit = CurrencyUnit::Sat; /// /// let localstore = memory::empty().await?; - /// let wallet = Wallet::new(mint_url, unit, Arc::new(localstore), &seed, None).unwrap(); + /// let wallet = Wallet::new(mint_url, unit, Arc::new(localstore), seed, None).unwrap(); /// let amount = Amount::from(100); /// /// let quote = wallet.mint_quote(amount, None).await?; @@ -243,10 +243,10 @@ impl Wallet { &amount_split_target, spending_conditions, )?, - None => PreMintSecrets::from_xpriv( + None => PreMintSecrets::from_seed( active_keyset_id, count, - self.xpriv, + &self.seed, amount_mintable, &amount_split_target, )?, diff --git a/crates/cdk/src/wallet/issue/issue_bolt12.rs b/crates/cdk/src/wallet/issue/issue_bolt12.rs index bb8297dc3..fe2185b74 100644 --- a/crates/cdk/src/wallet/issue/issue_bolt12.rs +++ b/crates/cdk/src/wallet/issue/issue_bolt12.rs @@ -137,10 +137,10 @@ impl Wallet { &amount_split_target, spending_conditions, )?, - None => PreMintSecrets::from_xpriv( + None => PreMintSecrets::from_seed( active_keyset_id, count, - self.xpriv, + &self.seed, amount, &amount_split_target, )?, diff --git a/crates/cdk/src/wallet/melt/melt_bolt11.rs b/crates/cdk/src/wallet/melt/melt_bolt11.rs index 014443316..27962e76b 100644 --- a/crates/cdk/src/wallet/melt/melt_bolt11.rs +++ b/crates/cdk/src/wallet/melt/melt_bolt11.rs @@ -30,12 +30,12 @@ impl Wallet { /// /// #[tokio::main] /// async fn main() -> anyhow::Result<()> { - /// let seed = random::<[u8; 32]>(); + /// let seed = random::<[u8; 64]>(); /// let mint_url = "https://fake.thesimplekid.dev"; /// let unit = CurrencyUnit::Sat; /// /// let localstore = memory::empty().await?; - /// let wallet = Wallet::new(mint_url, unit, Arc::new(localstore), &seed, None).unwrap(); + /// let wallet = Wallet::new(mint_url, unit, Arc::new(localstore), seed, None).unwrap(); /// let bolt11 = "lnbc100n1pnvpufspp5djn8hrq49r8cghwye9kqw752qjncwyfnrprhprpqk43mwcy4yfsqdq5g9kxy7fqd9h8vmmfvdjscqzzsxqyz5vqsp5uhpjt36rj75pl7jq2sshaukzfkt7uulj456s4mh7uy7l6vx7lvxs9qxpqysgqedwz08acmqwtk8g4vkwm2w78suwt2qyzz6jkkwcgrjm3r3hs6fskyhvud4fan3keru7emjm8ygqpcrwtlmhfjfmer3afs5hhwamgr4cqtactdq".to_string(); /// let quote = wallet.melt_quote(bolt11, None).await?; /// @@ -155,10 +155,10 @@ impl Wallet { let count = count.map_or(0, |c| c + 1); - let premint_secrets = PreMintSecrets::from_xpriv_blank( + let premint_secrets = PreMintSecrets::from_seed_blank( active_keyset_id, count, - self.xpriv, + &self.seed, proofs_total - quote_info.amount, )?; @@ -285,12 +285,12 @@ impl Wallet { /// /// #[tokio::main] /// async fn main() -> anyhow::Result<()> { - /// let seed = random::<[u8; 32]>(); + /// let seed = random::<[u8; 64]>(); /// let mint_url = "https://fake.thesimplekid.dev"; /// let unit = CurrencyUnit::Sat; /// /// let localstore = memory::empty().await?; - /// let wallet = Wallet::new(mint_url, unit, Arc::new(localstore), &seed, None).unwrap(); + /// let wallet = Wallet::new(mint_url, unit, Arc::new(localstore), seed, None).unwrap(); /// let bolt11 = "lnbc100n1pnvpufspp5djn8hrq49r8cghwye9kqw752qjncwyfnrprhprpqk43mwcy4yfsqdq5g9kxy7fqd9h8vmmfvdjscqzzsxqyz5vqsp5uhpjt36rj75pl7jq2sshaukzfkt7uulj456s4mh7uy7l6vx7lvxs9qxpqysgqedwz08acmqwtk8g4vkwm2w78suwt2qyzz6jkkwcgrjm3r3hs6fskyhvud4fan3keru7emjm8ygqpcrwtlmhfjfmer3afs5hhwamgr4cqtactdq".to_string(); /// let quote = wallet.melt_quote(bolt11, None).await?; /// let quote_id = quote.id; diff --git a/crates/cdk/src/wallet/mod.rs b/crates/cdk/src/wallet/mod.rs index e47fd1ac4..e683eaa74 100644 --- a/crates/cdk/src/wallet/mod.rs +++ b/crates/cdk/src/wallet/mod.rs @@ -4,7 +4,6 @@ use std::collections::HashMap; use std::str::FromStr; use std::sync::Arc; -use bitcoin::bip32::Xpriv; use cdk_common::database::{self, WalletDatabase}; use cdk_common::subscription::Params; use getrandom::getrandom; @@ -78,7 +77,7 @@ pub struct Wallet { pub target_proof_count: usize, #[cfg(feature = "auth")] auth_wallet: Arc>>, - xpriv: Xpriv, + seed: [u8; 64], client: Arc, subscription: SubscriptionManager, } @@ -143,7 +142,7 @@ impl Wallet { /// use rand::random; /// /// async fn test() -> anyhow::Result<()> { - /// let seed = random::<[u8; 32]>(); + /// let seed = random::<[u8; 64]>(); /// let mint_url = "https://fake.thesimplekid.dev"; /// let unit = CurrencyUnit::Sat; /// @@ -152,7 +151,7 @@ impl Wallet { /// .mint_url(mint_url.parse().unwrap()) /// .unit(unit) /// .localstore(Arc::new(localstore)) - /// .seed(&seed) + /// .seed(seed) /// .build(); /// Ok(()) /// } @@ -161,7 +160,7 @@ impl Wallet { mint_url: &str, unit: CurrencyUnit, localstore: Arc + Send + Sync>, - seed: &[u8], + seed: [u8; 64], target_proof_count: Option, ) -> Result { let mint_url = MintUrl::from_str(mint_url)?; @@ -390,7 +389,7 @@ impl Wallet { while empty_batch.lt(&3) { let premint_secrets = PreMintSecrets::restore_batch( keyset.id, - self.xpriv, + &self.seed, start_counter, start_counter + 100, )?; diff --git a/crates/cdk/src/wallet/multi_mint_wallet.rs b/crates/cdk/src/wallet/multi_mint_wallet.rs index 310cc2144..f5c7d2bae 100644 --- a/crates/cdk/src/wallet/multi_mint_wallet.rs +++ b/crates/cdk/src/wallet/multi_mint_wallet.rs @@ -29,7 +29,7 @@ use crate::{ensure_cdk, Amount, Wallet}; pub struct MultiMintWallet { /// Storage backend pub localstore: Arc + Send + Sync>, - seed: Arc<[u8]>, + seed: [u8; 64], /// Wallets pub wallets: Arc>>, } @@ -38,7 +38,7 @@ impl MultiMintWallet { /// Create a new [MultiMintWallet] with initial wallets pub fn new( localstore: Arc + Send + Sync>, - seed: Arc<[u8]>, + seed: [u8; 64], wallets: Vec, ) -> Self { Self { @@ -74,7 +74,7 @@ impl MultiMintWallet { mint_url, unit, self.localstore.clone(), - self.seed.as_ref(), + self.seed, target_proof_count, )?; diff --git a/crates/cdk/src/wallet/receive.rs b/crates/cdk/src/wallet/receive.rs index 52b7558bb..0772a7642 100644 --- a/crates/cdk/src/wallet/receive.rs +++ b/crates/cdk/src/wallet/receive.rs @@ -196,12 +196,12 @@ impl Wallet { /// /// #[tokio::main] /// async fn main() -> anyhow::Result<()> { - /// let seed = random::<[u8; 32]>(); + /// let seed = random::<[u8; 64]>(); /// let mint_url = "https://fake.thesimplekid.dev"; /// let unit = CurrencyUnit::Sat; /// /// let localstore = memory::empty().await?; - /// let wallet = Wallet::new(mint_url, unit, Arc::new(localstore), &seed, None).unwrap(); + /// let wallet = Wallet::new(mint_url, unit, Arc::new(localstore), seed, None).unwrap(); /// let token = "cashuAeyJ0b2tlbiI6W3sicHJvb2ZzIjpbeyJhbW91bnQiOjEsInNlY3JldCI6ImI0ZjVlNDAxMDJhMzhiYjg3NDNiOTkwMzU5MTU1MGYyZGEzZTQxNWEzMzU0OTUyN2M2MmM5ZDc5MGVmYjM3MDUiLCJDIjoiMDIzYmU1M2U4YzYwNTMwZWVhOWIzOTQzZmRhMWEyY2U3MWM3YjNmMGNmMGRjNmQ4NDZmYTc2NWFhZjc3OWZhODFkIiwiaWQiOiIwMDlhMWYyOTMyNTNlNDFlIn1dLCJtaW50IjoiaHR0cHM6Ly90ZXN0bnV0LmNhc2h1LnNwYWNlIn1dLCJ1bml0Ijoic2F0In0="; /// let amount_receive = wallet.receive(token, ReceiveOptions::default()).await?; /// Ok(()) @@ -249,12 +249,12 @@ impl Wallet { /// /// #[tokio::main] /// async fn main() -> anyhow::Result<()> { - /// let seed = random::<[u8; 32]>(); + /// let seed = random::<[u8; 64]>(); /// let mint_url = "https://fake.thesimplekid.dev"; /// let unit = CurrencyUnit::Sat; /// /// let localstore = memory::empty().await?; - /// let wallet = Wallet::new(mint_url, unit, Arc::new(localstore), &seed, None).unwrap(); + /// let wallet = Wallet::new(mint_url, unit, Arc::new(localstore), seed, None).unwrap(); /// let token_raw = hex::decode("6372617742a4617481a261694800ad268c4d1f5826617081a3616101617378403961366462623834376264323332626137366462306466313937323136623239643362386363313435353363643237383237666331636339343266656462346561635821038618543ffb6b8695df4ad4babcde92a34a96bdcd97dcee0d7ccf98d4721267926164695468616e6b20796f75616d75687474703a2f2f6c6f63616c686f73743a33333338617563736174").unwrap(); /// let amount_receive = wallet.receive_raw(&token_raw, ReceiveOptions::default()).await?; /// Ok(()) diff --git a/crates/cdk/src/wallet/swap.rs b/crates/cdk/src/wallet/swap.rs index 85c82bbfe..3d404815a 100644 --- a/crates/cdk/src/wallet/swap.rs +++ b/crates/cdk/src/wallet/swap.rs @@ -257,10 +257,10 @@ impl Wallet { let (mut desired_messages, change_messages) = match spending_conditions { Some(conditions) => { - let change_premint_secrets = PreMintSecrets::from_xpriv( + let change_premint_secrets = PreMintSecrets::from_seed( active_keyset_id, count, - self.xpriv, + &self.seed, change_amount, &change_split_target, )?; @@ -278,20 +278,20 @@ impl Wallet { ) } None => { - let premint_secrets = PreMintSecrets::from_xpriv( + let premint_secrets = PreMintSecrets::from_seed( active_keyset_id, count, - self.xpriv, + &self.seed, send_amount.unwrap_or(Amount::ZERO), &SplitTarget::default(), )?; count += premint_secrets.len() as u32; - let change_premint_secrets = PreMintSecrets::from_xpriv( + let change_premint_secrets = PreMintSecrets::from_seed( active_keyset_id, count, - self.xpriv, + &self.seed, change_amount, &change_split_target, )?; From 9f9c96577f60cbf787941cc0f1247d9f5c0653da Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Sun, 3 Aug 2025 10:14:43 -0400 Subject: [PATCH 056/321] chore: stop test from running --- crates/cdk/src/wallet/melt/melt_bolt11.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/cdk/src/wallet/melt/melt_bolt11.rs b/crates/cdk/src/wallet/melt/melt_bolt11.rs index 014443316..206e897f2 100644 --- a/crates/cdk/src/wallet/melt/melt_bolt11.rs +++ b/crates/cdk/src/wallet/melt/melt_bolt11.rs @@ -20,7 +20,7 @@ use crate::{ensure_cdk, Error, Wallet}; impl Wallet { /// Melt Quote /// # Synopsis - /// ```rust + /// ```rust,no_run /// use std::sync::Arc; /// /// use cdk_sqlite::wallet::memory; From cceea654fe96f8bafbbf7bf057765598aadcf1f6 Mon Sep 17 00:00:00 2001 From: gudnuf <108303703+gudnuf@users.noreply.github.com> Date: Tue, 5 Aug 2025 04:55:17 -0700 Subject: [PATCH 057/321] feat: enhance auth config (#922) * feat: enhance auth config --- .../src/bin/start_fake_auth_mint.rs | 18 ++- crates/cdk-mintd/example.config.toml | 24 ++- crates/cdk-mintd/src/config.rs | 61 ++++++-- crates/cdk-mintd/src/env_vars/auth.rs | 77 ++++++---- crates/cdk-mintd/src/env_vars/mod.rs | 10 +- crates/cdk-mintd/src/lib.rs | 138 +++++++++--------- 6 files changed, 190 insertions(+), 138 deletions(-) diff --git a/crates/cdk-integration-tests/src/bin/start_fake_auth_mint.rs b/crates/cdk-integration-tests/src/bin/start_fake_auth_mint.rs index 4cb3ad9d3..5846a53c0 100644 --- a/crates/cdk-integration-tests/src/bin/start_fake_auth_mint.rs +++ b/crates/cdk-integration-tests/src/bin/start_fake_auth_mint.rs @@ -17,6 +17,7 @@ use anyhow::Result; use bip39::Mnemonic; use cdk_integration_tests::cli::CommonArgs; use cdk_integration_tests::shared; +use cdk_mintd::config::AuthType; use clap::Parser; use tokio::sync::Notify; @@ -68,16 +69,19 @@ async fn start_fake_auth_mint( // Enable authentication settings.auth = Some(cdk_mintd::config::Auth { + auth_enabled: true, openid_discovery, openid_client_id: "cashu-client".to_string(), mint_max_bat: 50, - enabled_mint: true, - enabled_melt: true, - enabled_swap: true, - enabled_check_mint_quote: true, - enabled_check_melt_quote: true, - enabled_restore: true, - enabled_check_proof_state: true, + mint: AuthType::Blind, + get_mint_quote: AuthType::Blind, + check_mint_quote: AuthType::Blind, + melt: AuthType::Blind, + get_melt_quote: AuthType::Blind, + check_melt_quote: AuthType::Blind, + swap: AuthType::Blind, + restore: AuthType::Blind, + check_proof_state: AuthType::Blind, }); // Set description for the mint diff --git a/crates/cdk-mintd/example.config.toml b/crates/cdk-mintd/example.config.toml index 8828a65a4..1e4d3c3e5 100644 --- a/crates/cdk-mintd/example.config.toml +++ b/crates/cdk-mintd/example.config.toml @@ -83,13 +83,23 @@ reserve_fee_min = 4 # tls_dir = "/path/to/tls" # [auth] +# Set to true to enable authentication features (defaults to false) +# auth_enabled = false # openid_discovery = "http://127.0.0.1:8080/realms/cdk-test-realm/.well-known/openid-configuration" # openid_client_id = "cashu-client" # mint_max_bat=50 -# enabled_mint=true -# enabled_melt=true -# enabled_swap=true -# enabled_check_mint_quote=true -# enabled_check_melt_quote=true -# enabled_restore=true -# enabled_check_proof_state=true + +# Authentication settings for endpoints +# Options: "clear", "blind", "none" (none = disabled) + +# mint = "blind" +# get_mint_quote = "none" +# check_mint_quote = "none" + +# melt = "none" +# get_melt_quote = "none" +# check_melt_quote = "none" + +# swap = "blind" +# restore = "blind" +# check_proof_state = "none" diff --git a/crates/cdk-mintd/src/config.rs b/crates/cdk-mintd/src/config.rs index 636080fbd..bd245e722 100644 --- a/crates/cdk-mintd/src/config.rs +++ b/crates/cdk-mintd/src/config.rs @@ -208,30 +208,59 @@ pub struct Database { pub engine: DatabaseEngine, } +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)] +#[serde(rename_all = "lowercase")] +pub enum AuthType { + Clear, + Blind, + #[default] + None, +} + +impl std::str::FromStr for AuthType { + type Err = String; + + fn from_str(s: &str) -> Result { + match s.to_lowercase().as_str() { + "clear" => Ok(AuthType::Clear), + "blind" => Ok(AuthType::Blind), + "none" => Ok(AuthType::None), + _ => Err(format!("Unknown auth type: {s}")), + } + } +} + #[derive(Debug, Clone, Default, Serialize, Deserialize)] pub struct Auth { + #[serde(default)] + pub auth_enabled: bool, pub openid_discovery: String, pub openid_client_id: String, pub mint_max_bat: u64, - #[serde(default = "default_true")] - pub enabled_mint: bool, - #[serde(default = "default_true")] - pub enabled_melt: bool, - #[serde(default = "default_true")] - pub enabled_swap: bool, - #[serde(default = "default_true")] - pub enabled_check_mint_quote: bool, - #[serde(default = "default_true")] - pub enabled_check_melt_quote: bool, - #[serde(default = "default_true")] - pub enabled_restore: bool, - #[serde(default = "default_true")] - pub enabled_check_proof_state: bool, + #[serde(default = "default_blind")] + pub mint: AuthType, + #[serde(default)] + pub get_mint_quote: AuthType, + #[serde(default)] + pub check_mint_quote: AuthType, + #[serde(default)] + pub melt: AuthType, + #[serde(default)] + pub get_melt_quote: AuthType, + #[serde(default)] + pub check_melt_quote: AuthType, + #[serde(default = "default_blind")] + pub swap: AuthType, + #[serde(default = "default_blind")] + pub restore: AuthType, + #[serde(default)] + pub check_proof_state: AuthType, } -fn default_true() -> bool { - true +fn default_blind() -> AuthType { + AuthType::Blind } + /// CDK settings, derived from `config.toml` #[derive(Debug, Clone, Serialize, Deserialize, Default)] pub struct Settings { diff --git a/crates/cdk-mintd/src/env_vars/auth.rs b/crates/cdk-mintd/src/env_vars/auth.rs index 93a324d29..62d325977 100644 --- a/crates/cdk-mintd/src/env_vars/auth.rs +++ b/crates/cdk-mintd/src/env_vars/auth.rs @@ -4,19 +4,28 @@ use std::env; use crate::config::Auth; +pub const ENV_AUTH_ENABLED: &str = "CDK_MINTD_AUTH_ENABLED"; pub const ENV_AUTH_OPENID_DISCOVERY: &str = "CDK_MINTD_AUTH_OPENID_DISCOVERY"; pub const ENV_AUTH_OPENID_CLIENT_ID: &str = "CDK_MINTD_AUTH_OPENID_CLIENT_ID"; pub const ENV_AUTH_MINT_MAX_BAT: &str = "CDK_MINTD_AUTH_MINT_MAX_BAT"; -pub const ENV_AUTH_ENABLED_MINT: &str = "CDK_MINTD_AUTH_ENABLED_MINT"; -pub const ENV_AUTH_ENABLED_MELT: &str = "CDK_MINTD_AUTH_ENABLED_MELT"; -pub const ENV_AUTH_ENABLED_SWAP: &str = "CDK_MINTD_AUTH_ENABLED_SWAP"; -pub const ENV_AUTH_ENABLED_CHECK_MINT_QUOTE: &str = "CDK_MINTD_AUTH_ENABLED_CHECK_MINT_QUOTE"; -pub const ENV_AUTH_ENABLED_CHECK_MELT_QUOTE: &str = "CDK_MINTD_AUTH_ENABLED_CHECK_MELT_QUOTE"; -pub const ENV_AUTH_ENABLED_RESTORE: &str = "CDK_MINTD_AUTH_ENABLED_RESTORE"; -pub const ENV_AUTH_ENABLED_CHECK_PROOF_STATE: &str = "CDK_MINTD_AUTH_ENABLED_CHECK_PROOF_STATE"; +pub const ENV_AUTH_MINT: &str = "CDK_MINTD_AUTH_MINT"; +pub const ENV_AUTH_GET_MINT_QUOTE: &str = "CDK_MINTD_AUTH_GET_MINT_QUOTE"; +pub const ENV_AUTH_CHECK_MINT_QUOTE: &str = "CDK_MINTD_AUTH_CHECK_MINT_QUOTE"; +pub const ENV_AUTH_MELT: &str = "CDK_MINTD_AUTH_MELT"; +pub const ENV_AUTH_GET_MELT_QUOTE: &str = "CDK_MINTD_AUTH_GET_MELT_QUOTE"; +pub const ENV_AUTH_CHECK_MELT_QUOTE: &str = "CDK_MINTD_AUTH_CHECK_MELT_QUOTE"; +pub const ENV_AUTH_SWAP: &str = "CDK_MINTD_AUTH_SWAP"; +pub const ENV_AUTH_RESTORE: &str = "CDK_MINTD_AUTH_RESTORE"; +pub const ENV_AUTH_CHECK_PROOF_STATE: &str = "CDK_MINTD_AUTH_CHECK_PROOF_STATE"; impl Auth { pub fn from_env(mut self) -> Self { + if let Ok(enabled_str) = env::var(ENV_AUTH_ENABLED) { + if let Ok(enabled) = enabled_str.parse() { + self.auth_enabled = enabled; + } + } + if let Ok(discovery) = env::var(ENV_AUTH_OPENID_DISCOVERY) { self.openid_discovery = discovery; } @@ -31,45 +40,57 @@ impl Auth { } } - if let Ok(enabled_mint_str) = env::var(ENV_AUTH_ENABLED_MINT) { - if let Ok(enabled) = enabled_mint_str.parse() { - self.enabled_mint = enabled; + if let Ok(mint_str) = env::var(ENV_AUTH_MINT) { + if let Ok(auth_type) = mint_str.parse() { + self.mint = auth_type; + } + } + + if let Ok(get_mint_quote_str) = env::var(ENV_AUTH_GET_MINT_QUOTE) { + if let Ok(auth_type) = get_mint_quote_str.parse() { + self.get_mint_quote = auth_type; + } + } + + if let Ok(check_mint_quote_str) = env::var(ENV_AUTH_CHECK_MINT_QUOTE) { + if let Ok(auth_type) = check_mint_quote_str.parse() { + self.check_mint_quote = auth_type; } } - if let Ok(enabled_melt_str) = env::var(ENV_AUTH_ENABLED_MELT) { - if let Ok(enabled) = enabled_melt_str.parse() { - self.enabled_melt = enabled; + if let Ok(melt_str) = env::var(ENV_AUTH_MELT) { + if let Ok(auth_type) = melt_str.parse() { + self.melt = auth_type; } } - if let Ok(enabled_swap_str) = env::var(ENV_AUTH_ENABLED_SWAP) { - if let Ok(enabled) = enabled_swap_str.parse() { - self.enabled_swap = enabled; + if let Ok(get_melt_quote_str) = env::var(ENV_AUTH_GET_MELT_QUOTE) { + if let Ok(auth_type) = get_melt_quote_str.parse() { + self.get_melt_quote = auth_type; } } - if let Ok(enabled_check_mint_str) = env::var(ENV_AUTH_ENABLED_CHECK_MINT_QUOTE) { - if let Ok(enabled) = enabled_check_mint_str.parse() { - self.enabled_check_mint_quote = enabled; + if let Ok(check_melt_quote_str) = env::var(ENV_AUTH_CHECK_MELT_QUOTE) { + if let Ok(auth_type) = check_melt_quote_str.parse() { + self.check_melt_quote = auth_type; } } - if let Ok(enabled_check_melt_str) = env::var(ENV_AUTH_ENABLED_CHECK_MELT_QUOTE) { - if let Ok(enabled) = enabled_check_melt_str.parse() { - self.enabled_check_melt_quote = enabled; + if let Ok(swap_str) = env::var(ENV_AUTH_SWAP) { + if let Ok(auth_type) = swap_str.parse() { + self.swap = auth_type; } } - if let Ok(enabled_restore_str) = env::var(ENV_AUTH_ENABLED_RESTORE) { - if let Ok(enabled) = enabled_restore_str.parse() { - self.enabled_restore = enabled; + if let Ok(restore_str) = env::var(ENV_AUTH_RESTORE) { + if let Ok(auth_type) = restore_str.parse() { + self.restore = auth_type; } } - if let Ok(enabled_check_proof_str) = env::var(ENV_AUTH_ENABLED_CHECK_PROOF_STATE) { - if let Ok(enabled) = enabled_check_proof_str.parse() { - self.enabled_check_proof_state = enabled; + if let Ok(check_proof_state_str) = env::var(ENV_AUTH_CHECK_PROOF_STATE) { + if let Ok(auth_type) = check_proof_state_str.parse() { + self.check_proof_state = auth_type; } } diff --git a/crates/cdk-mintd/src/env_vars/mod.rs b/crates/cdk-mintd/src/env_vars/mod.rs index 662432bdb..aab0f3278 100644 --- a/crates/cdk-mintd/src/env_vars/mod.rs +++ b/crates/cdk-mintd/src/env_vars/mod.rs @@ -63,14 +63,8 @@ impl Settings { // Check env vars for auth config even if None let auth = self.auth.clone().unwrap_or_default().from_env(); - // Only set auth if env vars are present and have non-default values - if auth.openid_discovery != String::default() - || auth.openid_client_id != String::default() - || auth.mint_max_bat != 0 - || auth.enabled_mint - || auth.enabled_melt - || auth.enabled_swap - { + // Only set auth if auth_enabled flag is true + if auth.auth_enabled { self.auth = Some(auth); } else { self.auth = None; diff --git a/crates/cdk-mintd/src/lib.rs b/crates/cdk-mintd/src/lib.rs index 86adbf1b4..89121e778 100644 --- a/crates/cdk-mintd/src/lib.rs +++ b/crates/cdk-mintd/src/lib.rs @@ -43,7 +43,7 @@ use cdk_axum::cache::HttpCache; use cdk_sqlite::mint::MintSqliteAuthDatabase; use cdk_sqlite::MintSqliteDatabase; use cli::CLIArgs; -use config::{DatabaseEngine, LnBackend}; +use config::{AuthType, DatabaseEngine, LnBackend}; use env_vars::ENV_WORK_DIR; use setup::LnBackendSetup; use tower::ServiceBuilder; @@ -456,116 +456,110 @@ async fn setup_authentication( } }; + let mut protected_endpoints = HashMap::new(); + let mut blind_auth_endpoints = vec![]; + let mut clear_auth_endpoints = vec![]; + let mut unprotected_endpoints = vec![]; + let mint_blind_auth_endpoint = ProtectedEndpoint::new(Method::Post, RoutePath::MintBlindAuth); - let mut protected_endpoints = HashMap::new(); - protected_endpoints.insert(mint_blind_auth_endpoint, AuthRequired::Clear); - let mut blind_auth_endpoints = vec![]; - let mut unprotected_endpoints = vec![]; + clear_auth_endpoints.push(mint_blind_auth_endpoint); + + // Helper function to add endpoint based on auth type + let mut add_endpoint = |endpoint: ProtectedEndpoint, auth_type: &AuthType| { + match auth_type { + AuthType::Blind => { + protected_endpoints.insert(endpoint, AuthRequired::Blind); + blind_auth_endpoints.push(endpoint); + } + AuthType::Clear => { + protected_endpoints.insert(endpoint, AuthRequired::Clear); + clear_auth_endpoints.push(endpoint); + } + AuthType::None => { + unprotected_endpoints.push(endpoint); + } + }; + }; + // Get mint quote endpoint { let mint_quote_protected_endpoint = - ProtectedEndpoint::new(Method::Post, RoutePath::MintQuoteBolt11); - let mint_protected_endpoint = - ProtectedEndpoint::new(Method::Post, RoutePath::MintBolt11); - if auth_settings.enabled_mint { - protected_endpoints.insert(mint_quote_protected_endpoint, AuthRequired::Blind); - - protected_endpoints.insert(mint_protected_endpoint, AuthRequired::Blind); - - blind_auth_endpoints.push(mint_quote_protected_endpoint); - blind_auth_endpoints.push(mint_protected_endpoint); - } else { - unprotected_endpoints.push(mint_protected_endpoint); - unprotected_endpoints.push(mint_quote_protected_endpoint); - } + ProtectedEndpoint::new(cdk::nuts::Method::Post, RoutePath::MintQuoteBolt11); + add_endpoint(mint_quote_protected_endpoint, &auth_settings.get_mint_quote); } + // Check mint quote endpoint { - let melt_quote_protected_endpoint = - ProtectedEndpoint::new(Method::Post, RoutePath::MeltQuoteBolt11); - let melt_protected_endpoint = - ProtectedEndpoint::new(Method::Post, RoutePath::MeltBolt11); - - if auth_settings.enabled_melt { - protected_endpoints.insert(melt_quote_protected_endpoint, AuthRequired::Blind); - protected_endpoints.insert(melt_protected_endpoint, AuthRequired::Blind); - - blind_auth_endpoints.push(melt_quote_protected_endpoint); - blind_auth_endpoints.push(melt_protected_endpoint); - } else { - unprotected_endpoints.push(melt_quote_protected_endpoint); - unprotected_endpoints.push(melt_protected_endpoint); - } + let check_mint_protected_endpoint = + ProtectedEndpoint::new(Method::Get, RoutePath::MintQuoteBolt11); + add_endpoint( + check_mint_protected_endpoint, + &auth_settings.check_mint_quote, + ); } + // Mint endpoint { - let swap_protected_endpoint = ProtectedEndpoint::new(Method::Post, RoutePath::Swap); - - if auth_settings.enabled_swap { - protected_endpoints.insert(swap_protected_endpoint, AuthRequired::Blind); - blind_auth_endpoints.push(swap_protected_endpoint); - } else { - unprotected_endpoints.push(swap_protected_endpoint); - } + let mint_protected_endpoint = + ProtectedEndpoint::new(cdk::nuts::Method::Post, RoutePath::MintBolt11); + add_endpoint(mint_protected_endpoint, &auth_settings.mint); } + // Get melt quote endpoint { - let check_mint_protected_endpoint = - ProtectedEndpoint::new(Method::Get, RoutePath::MintQuoteBolt11); - - if auth_settings.enabled_check_mint_quote { - protected_endpoints.insert(check_mint_protected_endpoint, AuthRequired::Blind); - blind_auth_endpoints.push(check_mint_protected_endpoint); - } else { - unprotected_endpoints.push(check_mint_protected_endpoint); - } + let melt_quote_protected_endpoint = ProtectedEndpoint::new( + cdk::nuts::Method::Post, + cdk::nuts::RoutePath::MeltQuoteBolt11, + ); + add_endpoint(melt_quote_protected_endpoint, &auth_settings.get_melt_quote); } + // Check melt quote endpoint { let check_melt_protected_endpoint = ProtectedEndpoint::new(Method::Get, RoutePath::MeltQuoteBolt11); + add_endpoint( + check_melt_protected_endpoint, + &auth_settings.check_melt_quote, + ); + } - if auth_settings.enabled_check_melt_quote { - protected_endpoints.insert(check_melt_protected_endpoint, AuthRequired::Blind); - blind_auth_endpoints.push(check_melt_protected_endpoint); - } else { - unprotected_endpoints.push(check_melt_protected_endpoint); - } + // Melt endpoint + { + let melt_protected_endpoint = + ProtectedEndpoint::new(Method::Post, RoutePath::MeltBolt11); + add_endpoint(melt_protected_endpoint, &auth_settings.melt); + } + + // Swap endpoint + { + let swap_protected_endpoint = ProtectedEndpoint::new(Method::Post, RoutePath::Swap); + add_endpoint(swap_protected_endpoint, &auth_settings.swap); } + // Restore endpoint { let restore_protected_endpoint = ProtectedEndpoint::new(Method::Post, RoutePath::Restore); - - if auth_settings.enabled_restore { - protected_endpoints.insert(restore_protected_endpoint, AuthRequired::Blind); - blind_auth_endpoints.push(restore_protected_endpoint); - } else { - unprotected_endpoints.push(restore_protected_endpoint); - } + add_endpoint(restore_protected_endpoint, &auth_settings.restore); } + // Check proof state endpoint { let state_protected_endpoint = ProtectedEndpoint::new(Method::Post, RoutePath::Checkstate); - - if auth_settings.enabled_check_proof_state { - protected_endpoints.insert(state_protected_endpoint, AuthRequired::Blind); - blind_auth_endpoints.push(state_protected_endpoint); - } else { - unprotected_endpoints.push(state_protected_endpoint); - } + add_endpoint(state_protected_endpoint, &auth_settings.check_proof_state); } mint_builder = mint_builder.with_auth( auth_localstore.clone(), auth_settings.openid_discovery, auth_settings.openid_client_id, - vec![mint_blind_auth_endpoint], + clear_auth_endpoints, ); mint_builder = mint_builder.with_blind_auth(auth_settings.mint_max_bat, blind_auth_endpoints); From ad8f1ece5c5d664da5b99b6686f2b3133aac69ec Mon Sep 17 00:00:00 2001 From: C Date: Wed, 6 Aug 2025 03:58:03 -0300 Subject: [PATCH 058/321] Working on a better database abstraction (#931) * Working on a better database abstraction After [this question in the chat](https://matrix.to/#/!oJFtttFHGfnTGrIjvD:matrix.cashu.space/$oJFtttFHGfnTGrIjvD:matrix.cashu.space/$I5ZtjJtBM0ctltThDYpoCwClZFlM6PHzf8q2Rjqmso8) regarding a database transaction within the same function, I realized a few design flaws in our SQL database abstraction, particularly regarding transactions. 1. Our upper abstraction got it right, where a transaction is bound with `&mut self`, so Rust knows how to handle its lifetime with' async/await'. 2. The raw database does not; instead, it returns &self, and beginning a transaction takes &self as well, which is problematic for Rust, but that's not all. It is fundamentally wrong. A transaction should take &mut self when beginning a transaction, as that connection is bound to a transaction and should not be returned to the pool. Currently, that responsibility lies with the implementor. If a mistake is made, a transaction could be executed in two or more connections. 3. The way a database is bound to our store layer is through a single struct, which may or may not internally utilize our connection pool. This is also another design flow, in this PR, a connection pool is owned, and to use a connection, it should be requested, and that connection is reference with mutable when beginning a transaction * Improve the abstraction with fewer generics As suggested by @thesimplekid * Add BEGIN IMMEDIATE for SQLite --- crates/cdk-sql-common/Cargo.toml | 1 + crates/cdk-sql-common/src/common.rs | 7 +- crates/cdk-sql-common/src/database.rs | 170 ++++- crates/cdk-sql-common/src/mint/auth/mod.rs | 65 +- crates/cdk-sql-common/src/mint/mod.rs | 170 +++-- crates/cdk-sql-common/src/pool.rs | 65 +- crates/cdk-sql-common/src/wallet/mod.rs | 141 ++-- crates/cdk-sqlite/src/async_sqlite.rs | 197 +++++ crates/cdk-sqlite/src/common.rs | 90 ++- crates/cdk-sqlite/src/lib.rs | 1 + crates/cdk-sqlite/src/mint/async_rusqlite.rs | 727 ------------------- crates/cdk-sqlite/src/mint/mod.rs | 21 +- crates/cdk-sqlite/src/wallet/mod.rs | 188 +---- 13 files changed, 721 insertions(+), 1122 deletions(-) create mode 100644 crates/cdk-sqlite/src/async_sqlite.rs delete mode 100644 crates/cdk-sqlite/src/mint/async_rusqlite.rs diff --git a/crates/cdk-sql-common/Cargo.toml b/crates/cdk-sql-common/Cargo.toml index 4ceb09034..2c54c9577 100644 --- a/crates/cdk-sql-common/Cargo.toml +++ b/crates/cdk-sql-common/Cargo.toml @@ -23,6 +23,7 @@ cdk-common = { workspace = true, features = ["test"] } bitcoin.workspace = true thiserror.workspace = true tracing.workspace = true +tokio.workspace = true serde.workspace = true serde_json.workspace = true lightning-invoice.workspace = true diff --git a/crates/cdk-sql-common/src/common.rs b/crates/cdk-sql-common/src/common.rs index ce52f7df4..f75bb63c9 100644 --- a/crates/cdk-sql-common/src/common.rs +++ b/crates/cdk-sql-common/src/common.rs @@ -3,11 +3,14 @@ use crate::stmt::query; /// Migrates the migration generated by `build.rs` #[inline(always)] -pub async fn migrate( +pub async fn migrate( conn: &C, db_prefix: &str, migrations: &[(&str, &str, &str)], -) -> Result<(), cdk_common::database::Error> { +) -> Result<(), cdk_common::database::Error> +where + C: DatabaseExecutor, +{ query( r#" CREATE TABLE IF NOT EXISTS migrations ( diff --git a/crates/cdk-sql-common/src/database.rs b/crates/cdk-sql-common/src/database.rs index 06c63a34c..ed4334ec0 100644 --- a/crates/cdk-sql-common/src/database.rs +++ b/crates/cdk-sql-common/src/database.rs @@ -1,10 +1,12 @@ //! Database traits definition use std::fmt::Debug; +use std::marker::PhantomData; +use std::ops::{Deref, DerefMut}; use cdk_common::database::Error; -use crate::stmt::{Column, Statement}; +use crate::stmt::{query, Column, Statement}; /// Database Executor /// @@ -32,22 +34,170 @@ pub trait DatabaseExecutor: Debug + Sync + Send { /// Database transaction trait #[async_trait::async_trait] -pub trait DatabaseTransaction<'a>: Debug + DatabaseExecutor + Send + Sync { +pub trait DatabaseTransaction +where + DB: DatabaseExecutor, +{ /// Consumes the current transaction committing the changes - async fn commit(self) -> Result<(), Error>; + async fn commit(conn: &mut DB) -> Result<(), Error>; + + /// Begin a transaction + async fn begin(conn: &mut DB) -> Result<(), Error>; /// Consumes the transaction rolling back all changes - async fn rollback(self) -> Result<(), Error>; + async fn rollback(conn: &mut DB) -> Result<(), Error>; +} + +/// Database connection with a transaction +#[derive(Debug)] +pub struct ConnectionWithTransaction +where + DB: DatabaseConnector + 'static, + W: Debug + Deref + DerefMut + Send + Sync + 'static, +{ + inner: Option, +} + +impl ConnectionWithTransaction +where + DB: DatabaseConnector, + W: Debug + Deref + DerefMut + Send + Sync + 'static, +{ + /// Creates a new transaction + pub async fn new(mut inner: W) -> Result { + DB::Transaction::begin(inner.deref_mut()).await?; + Ok(Self { inner: Some(inner) }) + } + + /// Commits the transaction consuming it and releasing the connection back to the pool (or + /// disconnecting) + pub async fn commit(mut self) -> Result<(), Error> { + let mut conn = self + .inner + .take() + .ok_or(Error::Internal("Missing connection".to_owned()))?; + + DB::Transaction::commit(&mut conn).await?; + + Ok(()) + } + + /// Rollback the transaction consuming it and releasing the connection back to the pool (or + /// disconnecting) + pub async fn rollback(mut self) -> Result<(), Error> { + let mut conn = self + .inner + .take() + .ok_or(Error::Internal("Missing connection".to_owned()))?; + + DB::Transaction::rollback(&mut conn).await?; + + Ok(()) + } +} + +impl Drop for ConnectionWithTransaction +where + DB: DatabaseConnector, + W: Debug + Deref + DerefMut + Send + Sync + 'static, +{ + fn drop(&mut self) { + if let Some(mut conn) = self.inner.take() { + tokio::spawn(async move { + let _ = DB::Transaction::rollback(conn.deref_mut()).await; + }); + } + } +} + +#[async_trait::async_trait] +impl DatabaseExecutor for ConnectionWithTransaction +where + DB: DatabaseConnector, + W: Debug + Deref + DerefMut + Send + Sync + 'static, +{ + fn name() -> &'static str { + "Transaction" + } + + /// Executes a query and returns the affected rows + async fn execute(&self, statement: Statement) -> Result { + self.inner + .as_ref() + .ok_or(Error::Internal("Missing internal connection".to_owned()))? + .execute(statement) + .await + } + + /// Runs the query and returns the first row or None + async fn fetch_one(&self, statement: Statement) -> Result>, Error> { + self.inner + .as_ref() + .ok_or(Error::Internal("Missing internal connection".to_owned()))? + .fetch_one(statement) + .await + } + + /// Runs the query and returns the first row or None + async fn fetch_all(&self, statement: Statement) -> Result>, Error> { + self.inner + .as_ref() + .ok_or(Error::Internal("Missing internal connection".to_owned()))? + .fetch_all(statement) + .await + } + + /// Fetches the first row and column from a query + async fn pluck(&self, statement: Statement) -> Result, Error> { + self.inner + .as_ref() + .ok_or(Error::Internal("Missing internal connection".to_owned()))? + .pluck(statement) + .await + } + + /// Batch execution + async fn batch(&self, statement: Statement) -> Result<(), Error> { + self.inner + .as_ref() + .ok_or(Error::Internal("Missing internal connection".to_owned()))? + .batch(statement) + .await + } +} + +/// Generic transaction handler for SQLite +pub struct GenericTransactionHandler(PhantomData); + +#[async_trait::async_trait] +impl DatabaseTransaction for GenericTransactionHandler +where + W: DatabaseExecutor, +{ + /// Consumes the current transaction committing the changes + async fn commit(conn: &mut W) -> Result<(), Error> { + query("COMMIT")?.execute(conn).await?; + Ok(()) + } + + /// Begin a transaction + async fn begin(conn: &mut W) -> Result<(), Error> { + query("BEGIN")?.execute(conn).await?; + Ok(()) + } + + /// Consumes the transaction rolling back all changes + async fn rollback(conn: &mut W) -> Result<(), Error> { + query("ROLLBACK")?.execute(conn).await?; + Ok(()) + } } /// Database connector #[async_trait::async_trait] pub trait DatabaseConnector: Debug + DatabaseExecutor + Send + Sync { - /// Transaction type for this database connection - type Transaction<'a>: DatabaseTransaction<'a> + /// Database static trait for the database + type Transaction: DatabaseTransaction where - Self: 'a; - - /// Begin a new transaction - async fn begin(&self) -> Result, Error>; + Self: Sized; } diff --git a/crates/cdk-sql-common/src/mint/auth/mod.rs b/crates/cdk-sql-common/src/mint/auth/mod.rs index 9d37c1d8e..f9d1351a5 100644 --- a/crates/cdk-sql-common/src/mint/auth/mod.rs +++ b/crates/cdk-sql-common/src/mint/auth/mod.rs @@ -1,8 +1,9 @@ //! SQL Mint Auth use std::collections::HashMap; -use std::marker::PhantomData; +use std::fmt::Debug; use std::str::FromStr; +use std::sync::Arc; use async_trait::async_trait; use cdk_common::database::{self, MintAuthDatabase, MintAuthTransaction}; @@ -15,37 +16,38 @@ use tracing::instrument; use super::{sql_row_to_blind_signature, sql_row_to_keyset_info, SQLTransaction}; use crate::column_as_string; use crate::common::migrate; -use crate::database::{DatabaseConnector, DatabaseTransaction}; +use crate::database::{ConnectionWithTransaction, DatabaseExecutor}; use crate::mint::Error; +use crate::pool::{DatabasePool, Pool, PooledResource}; use crate::stmt::query; /// Mint SQL Database #[derive(Debug, Clone)] -pub struct SQLMintAuthDatabase +pub struct SQLMintAuthDatabase where - DB: DatabaseConnector, + RM: DatabasePool + 'static, { - db: DB, + pool: Arc>, } -impl SQLMintAuthDatabase +impl SQLMintAuthDatabase where - DB: DatabaseConnector, + RM: DatabasePool + 'static, { /// Creates a new instance pub async fn new(db: X) -> Result where - X: Into, + X: Into, { - let db = db.into(); - Self::migrate(&db).await?; - Ok(Self { db }) + let pool = Pool::new(db.into()); + Self::migrate(pool.get().map_err(|e| Error::Database(Box::new(e)))?).await?; + Ok(Self { pool }) } /// Migrate - async fn migrate(conn: &DB) -> Result<(), Error> { - let tx = conn.begin().await?; - migrate(&tx, DB::name(), MIGRATIONS).await?; + async fn migrate(conn: PooledResource) -> Result<(), Error> { + let tx = ConnectionWithTransaction::new(conn).await?; + migrate(&tx, RM::Connection::name(), MIGRATIONS).await?; tx.commit().await?; Ok(()) } @@ -56,9 +58,9 @@ mod migrations; #[async_trait] -impl<'a, T> MintAuthTransaction for SQLTransaction<'a, T> +impl MintAuthTransaction for SQLTransaction where - T: DatabaseTransaction<'a>, + RM: DatabasePool + 'static, { #[instrument(skip(self))] async fn set_active_keyset(&mut self, id: Id) -> Result<(), database::Error> { @@ -233,9 +235,9 @@ where } #[async_trait] -impl MintAuthDatabase for SQLMintAuthDatabase +impl MintAuthDatabase for SQLMintAuthDatabase where - DB: DatabaseConnector, + RM: DatabasePool + 'static, { type Err = database::Error; @@ -244,12 +246,15 @@ where ) -> Result + Send + Sync + 'a>, database::Error> { Ok(Box::new(SQLTransaction { - inner: self.db.begin().await?, - _phantom: PhantomData, + inner: ConnectionWithTransaction::new( + self.pool.get().map_err(|e| Error::Database(Box::new(e)))?, + ) + .await?, })) } async fn get_active_keyset_id(&self) -> Result, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; Ok(query( r#" SELECT @@ -260,13 +265,14 @@ where active = 1; "#, )? - .pluck(&self.db) + .pluck(&*conn) .await? .map(|id| Ok::<_, Error>(column_as_string!(id, Id::from_str, Id::from_bytes))) .transpose()?) } async fn get_keyset_info(&self, id: &Id) -> Result, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; Ok(query( r#"SELECT id, @@ -283,13 +289,14 @@ where WHERE id=:id"#, )? .bind("id", id.to_string()) - .fetch_one(&self.db) + .fetch_one(&*conn) .await? .map(sql_row_to_keyset_info) .transpose()?) } async fn get_keyset_infos(&self) -> Result, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; Ok(query( r#"SELECT id, @@ -305,7 +312,7 @@ where keyset WHERE id=:id"#, )? - .fetch_all(&self.db) + .fetch_all(&*conn) .await? .into_iter() .map(sql_row_to_keyset_info) @@ -313,9 +320,10 @@ where } async fn get_proofs_states(&self, ys: &[PublicKey]) -> Result>, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; let mut current_states = query(r#"SELECT y, state FROM proof WHERE y IN (:ys)"#)? .bind_vec("ys", ys.iter().map(|y| y.to_bytes().to_vec()).collect()) - .fetch_all(&self.db) + .fetch_all(&*conn) .await? .into_iter() .map(|row| { @@ -333,6 +341,7 @@ where &self, blinded_messages: &[PublicKey], ) -> Result>, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; let mut blinded_signatures = query( r#"SELECT keyset_id, @@ -353,7 +362,7 @@ where .map(|y| y.to_bytes().to_vec()) .collect(), ) - .fetch_all(&self.db) + .fetch_all(&*conn) .await? .into_iter() .map(|mut row| { @@ -377,10 +386,11 @@ where &self, protected_endpoint: ProtectedEndpoint, ) -> Result, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; Ok( query(r#"SELECT auth FROM protected_endpoints WHERE endpoint = :endpoint"#)? .bind("endpoint", serde_json::to_string(&protected_endpoint)?) - .pluck(&self.db) + .pluck(&*conn) .await? .map(|auth| { Ok::<_, Error>(column_as_string!( @@ -396,8 +406,9 @@ where async fn get_auth_for_endpoints( &self, ) -> Result>, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; Ok(query(r#"SELECT endpoint, auth FROM protected_endpoints"#)? - .fetch_all(&self.db) + .fetch_all(&*conn) .await? .into_iter() .map(|row| { diff --git a/crates/cdk-sql-common/src/mint/mod.rs b/crates/cdk-sql-common/src/mint/mod.rs index 6a9370370..b6d6a41cd 100644 --- a/crates/cdk-sql-common/src/mint/mod.rs +++ b/crates/cdk-sql-common/src/mint/mod.rs @@ -9,8 +9,9 @@ //! clients in a pool and expose them to an asynchronous environment, making them compatible with //! Mint. use std::collections::HashMap; -use std::marker::PhantomData; +use std::fmt::Debug; use std::str::FromStr; +use std::sync::Arc; use async_trait::async_trait; use bitcoin::bip32::DerivationPath; @@ -38,7 +39,8 @@ use tracing::instrument; use uuid::Uuid; use crate::common::migrate; -use crate::database::{DatabaseConnector, DatabaseExecutor, DatabaseTransaction}; +use crate::database::{ConnectionWithTransaction, DatabaseExecutor}; +use crate::pool::{DatabasePool, Pool, PooledResource}; use crate::stmt::{query, Column}; use crate::{ column_as_nullable_number, column_as_nullable_string, column_as_number, column_as_string, @@ -57,20 +59,19 @@ pub use auth::SQLMintAuthDatabase; /// Mint SQL Database #[derive(Debug, Clone)] -pub struct SQLMintDatabase +pub struct SQLMintDatabase where - DB: DatabaseConnector, + RM: DatabasePool + 'static, { - db: DB, + pool: Arc>, } /// SQL Transaction Writer -pub struct SQLTransaction<'a, T> +pub struct SQLTransaction where - T: DatabaseTransaction<'a>, + RM: DatabasePool + 'static, { - inner: T, - _phantom: PhantomData<&'a ()>, + inner: ConnectionWithTransaction>, } #[inline(always)] @@ -115,24 +116,26 @@ where Ok(()) } -impl SQLMintDatabase +impl SQLMintDatabase where - DB: DatabaseConnector, + RM: DatabasePool + 'static, { /// Creates a new instance pub async fn new(db: X) -> Result where - X: Into, + X: Into, { - let db = db.into(); - Self::migrate(&db).await?; - Ok(Self { db }) + let pool = Pool::new(db.into()); + + Self::migrate(pool.get().map_err(|e| Error::Database(Box::new(e)))?).await?; + + Ok(Self { pool }) } /// Migrate - async fn migrate(conn: &DB) -> Result<(), Error> { - let tx = conn.begin().await?; - migrate(&tx, DB::name(), MIGRATIONS).await?; + async fn migrate(conn: PooledResource) -> Result<(), Error> { + let tx = ConnectionWithTransaction::new(conn).await?; + migrate(&tx, RM::Connection::name(), MIGRATIONS).await?; tx.commit().await?; Ok(()) } @@ -142,9 +145,10 @@ where where R: serde::de::DeserializeOwned, { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; let value = column_as_string!(query(r#"SELECT value FROM config WHERE id = :id LIMIT 1"#)? .bind("id", id.to_owned()) - .pluck(&self.db) + .pluck(&*conn) .await? .ok_or(Error::UnknownQuoteTTL)?); @@ -153,9 +157,9 @@ where } #[async_trait] -impl<'a, T> database::MintProofsTransaction<'a> for SQLTransaction<'a, T> +impl database::MintProofsTransaction<'_> for SQLTransaction where - T: DatabaseTransaction<'a>, + RM: DatabasePool + 'static, { type Err = Error; @@ -267,9 +271,9 @@ where } #[async_trait] -impl<'a, T> database::MintTransaction<'a, Error> for SQLTransaction<'a, T> +impl database::MintTransaction<'_, Error> for SQLTransaction where - T: DatabaseTransaction<'a>, + RM: DatabasePool + 'static, { async fn set_mint_info(&mut self, mint_info: MintInfo) -> Result<(), Error> { Ok(set_to_config(&self.inner, "mint_info", &mint_info).await?) @@ -281,18 +285,18 @@ where } #[async_trait] -impl<'a, T> MintDbWriterFinalizer for SQLTransaction<'a, T> +impl MintDbWriterFinalizer for SQLTransaction where - T: DatabaseTransaction<'a>, + RM: DatabasePool + 'static, { type Err = Error; async fn commit(self: Box) -> Result<(), Error> { - Ok(self.inner.commit().await?) + self.inner.commit().await } async fn rollback(self: Box) -> Result<(), Error> { - Ok(self.inner.rollback().await?) + self.inner.rollback().await } } @@ -357,9 +361,9 @@ WHERE quote_id=:quote_id } #[async_trait] -impl<'a, T> MintKeyDatabaseTransaction<'a, Error> for SQLTransaction<'a, T> +impl MintKeyDatabaseTransaction<'_, Error> for SQLTransaction where - T: DatabaseTransaction<'a>, + RM: DatabasePool + 'static, { async fn add_keyset_info(&mut self, keyset: MintKeySetInfo) -> Result<(), Error> { query( @@ -416,9 +420,9 @@ where } #[async_trait] -impl MintKeysDatabase for SQLMintDatabase +impl MintKeysDatabase for SQLMintDatabase where - DB: DatabaseConnector, + RM: DatabasePool + 'static, { type Err = Error; @@ -426,16 +430,19 @@ where &'a self, ) -> Result + Send + Sync + 'a>, Error> { Ok(Box::new(SQLTransaction { - inner: self.db.begin().await?, - _phantom: PhantomData, + inner: ConnectionWithTransaction::new( + self.pool.get().map_err(|e| Error::Database(Box::new(e)))?, + ) + .await?, })) } async fn get_active_keyset_id(&self, unit: &CurrencyUnit) -> Result, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; Ok( query(r#" SELECT id FROM keyset WHERE active = 1 AND unit IS :unit"#)? .bind("unit", unit.to_string()) - .pluck(&self.db) + .pluck(&*conn) .await? .map(|id| match id { Column::Text(text) => Ok(Id::from_str(&text)?), @@ -447,8 +454,9 @@ where } async fn get_active_keysets(&self) -> Result, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; Ok(query(r#"SELECT id, unit FROM keyset WHERE active = 1"#)? - .fetch_all(&self.db) + .fetch_all(&*conn) .await? .into_iter() .map(|row| { @@ -461,6 +469,7 @@ where } async fn get_keyset_info(&self, id: &Id) -> Result, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; Ok(query( r#"SELECT id, @@ -477,13 +486,14 @@ where WHERE id=:id"#, )? .bind("id", id.to_string()) - .fetch_one(&self.db) + .fetch_one(&*conn) .await? .map(sql_row_to_keyset_info) .transpose()?) } async fn get_keyset_infos(&self) -> Result, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; Ok(query( r#"SELECT id, @@ -499,7 +509,7 @@ where keyset "#, )? - .fetch_all(&self.db) + .fetch_all(&*conn) .await? .into_iter() .map(sql_row_to_keyset_info) @@ -508,9 +518,9 @@ where } #[async_trait] -impl<'a, T> MintQuotesTransaction<'a> for SQLTransaction<'a, T> +impl MintQuotesTransaction<'_> for SQLTransaction where - T: DatabaseTransaction<'a>, + RM: DatabasePool + 'static, { type Err = Error; @@ -1028,15 +1038,17 @@ VALUES (:quote_id, :amount, :timestamp); } #[async_trait] -impl MintQuotesDatabase for SQLMintDatabase +impl MintQuotesDatabase for SQLMintDatabase where - DB: DatabaseConnector, + RM: DatabasePool + 'static, { type Err = Error; async fn get_mint_quote(&self, quote_id: &Uuid) -> Result, Self::Err> { - let payments = get_mint_quote_payments(&self.db, quote_id).await?; - let issuance = get_mint_quote_issuance(&self.db, quote_id).await?; + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; + + let payments = get_mint_quote_payments(&*conn, quote_id).await?; + let issuance = get_mint_quote_issuance(&*conn, quote_id).await?; Ok(query( r#" @@ -1058,7 +1070,7 @@ where WHERE id = :id"#, )? .bind("id", quote_id.as_hyphenated().to_string()) - .fetch_one(&self.db) + .fetch_one(&*conn) .await? .map(|row| sql_row_to_mint_quote(row, payments, issuance)) .transpose()?) @@ -1068,6 +1080,7 @@ where &self, request: &str, ) -> Result, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; let mut mint_quote = query( r#" SELECT @@ -1088,14 +1101,14 @@ where WHERE request = :request"#, )? .bind("request", request.to_owned()) - .fetch_one(&self.db) + .fetch_one(&*conn) .await? .map(|row| sql_row_to_mint_quote(row, vec![], vec![])) .transpose()?; if let Some(quote) = mint_quote.as_mut() { - let payments = get_mint_quote_payments(&self.db, "e.id).await?; - let issuance = get_mint_quote_issuance(&self.db, "e.id).await?; + let payments = get_mint_quote_payments(&*conn, "e.id).await?; + let issuance = get_mint_quote_issuance(&*conn, "e.id).await?; quote.issuance = issuance; quote.payments = payments; } @@ -1107,6 +1120,7 @@ where &self, request_lookup_id: &PaymentIdentifier, ) -> Result, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; let mut mint_quote = query( r#" SELECT @@ -1130,15 +1144,15 @@ where )? .bind("request_lookup_id", request_lookup_id.to_string()) .bind("request_lookup_id_kind", request_lookup_id.kind()) - .fetch_one(&self.db) + .fetch_one(&*conn) .await? .map(|row| sql_row_to_mint_quote(row, vec![], vec![])) .transpose()?; // TODO: these should use an sql join so they can be done in one query if let Some(quote) = mint_quote.as_mut() { - let payments = get_mint_quote_payments(&self.db, "e.id).await?; - let issuance = get_mint_quote_issuance(&self.db, "e.id).await?; + let payments = get_mint_quote_payments(&*conn, "e.id).await?; + let issuance = get_mint_quote_issuance(&*conn, "e.id).await?; quote.issuance = issuance; quote.payments = payments; } @@ -1147,6 +1161,7 @@ where } async fn get_mint_quotes(&self) -> Result, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; let mut mint_quotes = query( r#" SELECT @@ -1166,15 +1181,15 @@ where mint_quote "#, )? - .fetch_all(&self.db) + .fetch_all(&*conn) .await? .into_iter() .map(|row| sql_row_to_mint_quote(row, vec![], vec![])) .collect::, _>>()?; for quote in mint_quotes.as_mut_slice() { - let payments = get_mint_quote_payments(&self.db, "e.id).await?; - let issuance = get_mint_quote_issuance(&self.db, "e.id).await?; + let payments = get_mint_quote_payments(&*conn, "e.id).await?; + let issuance = get_mint_quote_issuance(&*conn, "e.id).await?; quote.issuance = issuance; quote.payments = payments; } @@ -1183,6 +1198,7 @@ where } async fn get_melt_quote(&self, quote_id: &Uuid) -> Result, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; Ok(query( r#" SELECT @@ -1207,13 +1223,14 @@ where "#, )? .bind("id", quote_id.as_hyphenated().to_string()) - .fetch_one(&self.db) + .fetch_one(&*conn) .await? .map(sql_row_to_melt_quote) .transpose()?) } async fn get_melt_quotes(&self) -> Result, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; Ok(query( r#" SELECT @@ -1235,7 +1252,7 @@ where melt_quote "#, )? - .fetch_all(&self.db) + .fetch_all(&*conn) .await? .into_iter() .map(sql_row_to_melt_quote) @@ -1244,13 +1261,14 @@ where } #[async_trait] -impl MintProofsDatabase for SQLMintDatabase +impl MintProofsDatabase for SQLMintDatabase where - DB: DatabaseConnector, + RM: DatabasePool + 'static, { type Err = Error; async fn get_proofs_by_ys(&self, ys: &[PublicKey]) -> Result>, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; let mut proofs = query( r#" SELECT @@ -1267,7 +1285,7 @@ where "#, )? .bind_vec("ys", ys.iter().map(|y| y.to_bytes().to_vec()).collect()) - .fetch_all(&self.db) + .fetch_all(&*conn) .await? .into_iter() .map(|mut row| { @@ -1286,6 +1304,7 @@ where } async fn get_proof_ys_by_quote_id(&self, quote_id: &Uuid) -> Result, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; Ok(query( r#" SELECT @@ -1301,7 +1320,7 @@ where "#, )? .bind("quote_id", quote_id.as_hyphenated().to_string()) - .fetch_all(&self.db) + .fetch_all(&*conn) .await? .into_iter() .map(sql_row_to_proof) @@ -1310,7 +1329,8 @@ where } async fn get_proofs_states(&self, ys: &[PublicKey]) -> Result>, Self::Err> { - let mut current_states = get_current_states(&self.db, ys).await?; + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; + let mut current_states = get_current_states(&*conn, ys).await?; Ok(ys.iter().map(|y| current_states.remove(y)).collect()) } @@ -1319,6 +1339,7 @@ where &self, keyset_id: &Id, ) -> Result<(Proofs, Vec>), Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; Ok(query( r#" SELECT @@ -1335,7 +1356,7 @@ where "#, )? .bind("keyset_id", keyset_id.to_string()) - .fetch_all(&self.db) + .fetch_all(&*conn) .await? .into_iter() .map(sql_row_to_proof_with_state) @@ -1346,9 +1367,9 @@ where } #[async_trait] -impl<'a, T> MintSignatureTransaction<'a> for SQLTransaction<'a, T> +impl MintSignatureTransaction<'_> for SQLTransaction where - T: DatabaseTransaction<'a>, + RM: DatabasePool + 'static, { type Err = Error; @@ -1436,9 +1457,9 @@ where } #[async_trait] -impl MintSignaturesDatabase for SQLMintDatabase +impl MintSignaturesDatabase for SQLMintDatabase where - DB: DatabaseConnector, + RM: DatabasePool + 'static, { type Err = Error; @@ -1446,6 +1467,7 @@ where &self, blinded_messages: &[PublicKey], ) -> Result>, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; let mut blinded_signatures = query( r#"SELECT keyset_id, @@ -1466,7 +1488,7 @@ where .map(|b_| b_.to_bytes().to_vec()) .collect(), ) - .fetch_all(&self.db) + .fetch_all(&*conn) .await? .into_iter() .map(|mut row| { @@ -1490,6 +1512,7 @@ where &self, keyset_id: &Id, ) -> Result, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; Ok(query( r#" SELECT @@ -1505,7 +1528,7 @@ where "#, )? .bind("keyset_id", keyset_id.to_string()) - .fetch_all(&self.db) + .fetch_all(&*conn) .await? .into_iter() .map(sql_row_to_blind_signature) @@ -1517,6 +1540,7 @@ where &self, quote_id: &Uuid, ) -> Result, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; Ok(query( r#" SELECT @@ -1532,7 +1556,7 @@ where "#, )? .bind("quote_id", quote_id.to_string()) - .fetch_all(&self.db) + .fetch_all(&*conn) .await? .into_iter() .map(sql_row_to_blind_signature) @@ -1541,16 +1565,18 @@ where } #[async_trait] -impl MintDatabase for SQLMintDatabase +impl MintDatabase for SQLMintDatabase where - DB: DatabaseConnector, + RM: DatabasePool + 'static, { async fn begin_transaction<'a>( &'a self, ) -> Result + Send + Sync + 'a>, Error> { Ok(Box::new(SQLTransaction { - inner: self.db.begin().await?, - _phantom: PhantomData, + inner: ConnectionWithTransaction::new( + self.pool.get().map_err(|e| Error::Database(Box::new(e)))?, + ) + .await?, })) } diff --git a/crates/cdk-sql-common/src/pool.rs b/crates/cdk-sql-common/src/pool.rs index 3085a0eea..e8cf889c7 100644 --- a/crates/cdk-sql-common/src/pool.rs +++ b/crates/cdk-sql-common/src/pool.rs @@ -8,9 +8,14 @@ use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering}; use std::sync::{Arc, Condvar, Mutex}; use std::time::Duration; +use crate::database::DatabaseConnector; + /// Pool error -#[derive(thiserror::Error, Debug)] -pub enum Error { +#[derive(Debug, thiserror::Error)] +pub enum Error +where + E: std::error::Error + Send + Sync + 'static, +{ /// Mutex Poison Error #[error("Internal: PoisonError")] Poison, @@ -24,16 +29,25 @@ pub enum Error { Resource(#[from] E), } +/// Configuration +pub trait DatabaseConfig: Clone + Debug + Send + Sync { + /// Max resource sizes + fn max_size(&self) -> usize; + + /// Default timeout + fn default_timeout(&self) -> Duration; +} + /// Trait to manage resources -pub trait ResourceManager: Debug { +pub trait DatabasePool: Debug { /// The resource to be pooled - type Resource: Debug; + type Connection: DatabaseConnector; /// The configuration that is needed in order to create the resource - type Config: Clone + Debug; + type Config: DatabaseConfig; /// The error the resource may return when creating a new instance - type Error: Debug; + type Error: Debug + std::error::Error + Send + Sync + 'static; /// Creates a new resource with a given config. /// @@ -43,20 +57,20 @@ pub trait ResourceManager: Debug { config: &Self::Config, stale: Arc, timeout: Duration, - ) -> Result>; + ) -> Result>; /// The object is dropped - fn drop(_resource: Self::Resource) {} + fn drop(_resource: Self::Connection) {} } /// Generic connection pool of resources R #[derive(Debug)] pub struct Pool where - RM: ResourceManager, + RM: DatabasePool, { config: RM::Config, - queue: Mutex, RM::Resource)>>, + queue: Mutex, RM::Connection)>>, in_use: AtomicUsize, max_size: usize, default_timeout: Duration, @@ -66,15 +80,24 @@ where /// The pooled resource pub struct PooledResource where - RM: ResourceManager, + RM: DatabasePool, { - resource: Option<(Arc, RM::Resource)>, + resource: Option<(Arc, RM::Connection)>, pool: Arc>, } +impl Debug for PooledResource +where + RM: DatabasePool, +{ + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + write!(f, "Resource: {:?}", self.resource) + } +} + impl Drop for PooledResource where - RM: ResourceManager, + RM: DatabasePool, { fn drop(&mut self) { if let Some(resource) = self.resource.take() { @@ -90,9 +113,9 @@ where impl Deref for PooledResource where - RM: ResourceManager, + RM: DatabasePool, { - type Target = RM::Resource; + type Target = RM::Connection; fn deref(&self) -> &Self::Target { &self.resource.as_ref().expect("resource already dropped").1 @@ -101,7 +124,7 @@ where impl DerefMut for PooledResource where - RM: ResourceManager, + RM: DatabasePool, { fn deref_mut(&mut self) -> &mut Self::Target { &mut self.resource.as_mut().expect("resource already dropped").1 @@ -110,17 +133,17 @@ where impl Pool where - RM: ResourceManager, + RM: DatabasePool, { /// Creates a new pool - pub fn new(config: RM::Config, max_size: usize, default_timeout: Duration) -> Arc { + pub fn new(config: RM::Config) -> Arc { Arc::new(Self { + default_timeout: config.default_timeout(), + max_size: config.max_size(), config, queue: Default::default(), in_use: Default::default(), waiter: Default::default(), - default_timeout, - max_size, }) } @@ -185,7 +208,7 @@ where impl Drop for Pool where - RM: ResourceManager, + RM: DatabasePool, { fn drop(&mut self) { if let Ok(mut resources) = self.queue.lock() { diff --git a/crates/cdk-sql-common/src/wallet/mod.rs b/crates/cdk-sql-common/src/wallet/mod.rs index 493aa9bc7..6c7324ed6 100644 --- a/crates/cdk-sql-common/src/wallet/mod.rs +++ b/crates/cdk-sql-common/src/wallet/mod.rs @@ -1,7 +1,9 @@ //! SQLite Wallet Database use std::collections::HashMap; +use std::fmt::Debug; use std::str::FromStr; +use std::sync::Arc; use async_trait::async_trait; use cdk_common::common::ProofInfo; @@ -17,7 +19,8 @@ use cdk_common::{ use tracing::instrument; use crate::common::migrate; -use crate::database::DatabaseExecutor; +use crate::database::{ConnectionWithTransaction, DatabaseExecutor}; +use crate::pool::{DatabasePool, Pool, PooledResource}; use crate::stmt::{query, Column}; use crate::{ column_as_binary, column_as_nullable_binary, column_as_nullable_number, @@ -29,36 +32,43 @@ mod migrations; /// Wallet SQLite Database #[derive(Debug, Clone)] -pub struct SQLWalletDatabase +pub struct SQLWalletDatabase where - T: DatabaseExecutor, + RM: DatabasePool + 'static, { - db: T, + pool: Arc>, } -impl SQLWalletDatabase +impl SQLWalletDatabase where - DB: DatabaseExecutor, + RM: DatabasePool + 'static, { /// Creates a new instance pub async fn new(db: X) -> Result where - X: Into, + X: Into, { - let db = db.into(); - Self::migrate(&db).await?; - Ok(Self { db }) + let pool = Pool::new(db.into()); + Self::migrate(pool.get().map_err(|e| Error::Database(Box::new(e)))?).await?; + + Ok(Self { pool }) } /// Migrate [`WalletSqliteDatabase`] - async fn migrate(conn: &DB) -> Result<(), Error> { - migrate(conn, DB::name(), migrations::MIGRATIONS).await?; + async fn migrate(conn: PooledResource) -> Result<(), Error> { + let tx = ConnectionWithTransaction::new(conn).await?; + migrate(&tx, RM::Connection::name(), migrations::MIGRATIONS).await?; // Update any existing keys with missing keyset_u32 values - Self::add_keyset_u32(conn).await?; + Self::add_keyset_u32(&tx).await?; + tx.commit().await?; + Ok(()) } - async fn add_keyset_u32(conn: &DB) -> Result<(), Error> { + async fn add_keyset_u32(conn: &T) -> Result<(), Error> + where + T: DatabaseExecutor, + { // First get the keysets where keyset_u32 on key is null let keys_without_u32: Vec> = query( r#" @@ -126,14 +136,16 @@ where } #[async_trait] -impl WalletDatabase for SQLWalletDatabase +impl WalletDatabase for SQLWalletDatabase where - T: DatabaseExecutor, + RM: DatabasePool + 'static, { type Err = database::Error; #[instrument(skip(self))] async fn get_melt_quotes(&self) -> Result, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; + Ok(query( r#" SELECT @@ -149,7 +161,7 @@ where melt_quote "#, )? - .fetch_all(&self.db) + .fetch_all(&*conn) .await? .into_iter() .map(sql_row_to_melt_quote) @@ -212,6 +224,8 @@ where ), }; + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; + query( r#" INSERT INTO mint @@ -253,7 +267,7 @@ ON CONFLICT(mint_url) DO UPDATE SET .bind("motd", motd) .bind("mint_time", time.map(|v| v as i64)) .bind("tos_url", tos_url) - .execute(&self.db) + .execute(&*conn) .await?; Ok(()) @@ -261,9 +275,11 @@ ON CONFLICT(mint_url) DO UPDATE SET #[instrument(skip(self))] async fn remove_mint(&self, mint_url: MintUrl) -> Result<(), Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; + query(r#"DELETE FROM mint WHERE mint_url=:mint_url"#)? .bind("mint_url", mint_url.to_string()) - .execute(&self.db) + .execute(&*conn) .await?; Ok(()) @@ -271,6 +287,7 @@ ON CONFLICT(mint_url) DO UPDATE SET #[instrument(skip(self))] async fn get_mint(&self, mint_url: MintUrl) -> Result, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; Ok(query( r#" SELECT @@ -292,7 +309,7 @@ ON CONFLICT(mint_url) DO UPDATE SET "#, )? .bind("mint_url", mint_url.to_string()) - .fetch_one(&self.db) + .fetch_one(&*conn) .await? .map(sql_row_to_mint_info) .transpose()?) @@ -300,6 +317,7 @@ ON CONFLICT(mint_url) DO UPDATE SET #[instrument(skip(self))] async fn get_mints(&self) -> Result>, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; Ok(query( r#" SELECT @@ -320,7 +338,7 @@ ON CONFLICT(mint_url) DO UPDATE SET mint "#, )? - .fetch_all(&self.db) + .fetch_all(&*conn) .await? .into_iter() .map(|mut row| { @@ -340,6 +358,7 @@ ON CONFLICT(mint_url) DO UPDATE SET old_mint_url: MintUrl, new_mint_url: MintUrl, ) -> Result<(), Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; let tables = ["mint_quote", "proof"]; for table in &tables { @@ -352,7 +371,7 @@ ON CONFLICT(mint_url) DO UPDATE SET ))? .bind("new_mint_url", new_mint_url.to_string()) .bind("old_mint_url", old_mint_url.to_string()) - .execute(&self.db) + .execute(&*conn) .await?; } @@ -365,6 +384,8 @@ ON CONFLICT(mint_url) DO UPDATE SET mint_url: MintUrl, keysets: Vec, ) -> Result<(), Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; + for keyset in keysets { query( r#" @@ -384,7 +405,7 @@ ON CONFLICT(mint_url) DO UPDATE SET .bind("input_fee_ppk", keyset.input_fee_ppk as i64) .bind("final_expiry", keyset.final_expiry.map(|v| v as i64)) .bind("keyset_u32", u32::from(keyset.id)) - .execute(&self.db) + .execute(&*conn) .await?; } @@ -396,6 +417,8 @@ ON CONFLICT(mint_url) DO UPDATE SET &self, mint_url: MintUrl, ) -> Result>, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; + let keysets = query( r#" SELECT @@ -410,7 +433,7 @@ ON CONFLICT(mint_url) DO UPDATE SET "#, )? .bind("mint_url", mint_url.to_string()) - .fetch_all(&self.db) + .fetch_all(&*conn) .await? .into_iter() .map(sql_row_to_keyset) @@ -424,6 +447,7 @@ ON CONFLICT(mint_url) DO UPDATE SET #[instrument(skip(self), fields(keyset_id = %keyset_id))] async fn get_keyset_by_id(&self, keyset_id: &Id) -> Result, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; Ok(query( r#" SELECT @@ -438,7 +462,7 @@ ON CONFLICT(mint_url) DO UPDATE SET "#, )? .bind("id", keyset_id.to_string()) - .fetch_one(&self.db) + .fetch_one(&*conn) .await? .map(sql_row_to_keyset) .transpose()?) @@ -446,6 +470,7 @@ ON CONFLICT(mint_url) DO UPDATE SET #[instrument(skip_all)] async fn add_mint_quote(&self, quote: MintQuote) -> Result<(), Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; query( r#" INSERT INTO mint_quote @@ -477,13 +502,14 @@ ON CONFLICT(id) DO UPDATE SET .bind("payment_method", quote.payment_method.to_string()) .bind("amount_issued", quote.amount_issued.to_i64()) .bind("amount_paid", quote.amount_paid.to_i64()) - .execute(&self.db).await?; + .execute(&*conn).await?; Ok(()) } #[instrument(skip(self))] async fn get_mint_quote(&self, quote_id: &str) -> Result, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; Ok(query( r#" SELECT @@ -505,7 +531,7 @@ ON CONFLICT(id) DO UPDATE SET "#, )? .bind("id", quote_id.to_string()) - .fetch_one(&self.db) + .fetch_one(&*conn) .await? .map(sql_row_to_mint_quote) .transpose()?) @@ -513,6 +539,7 @@ ON CONFLICT(id) DO UPDATE SET #[instrument(skip(self))] async fn get_mint_quotes(&self) -> Result, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; Ok(query( r#" SELECT @@ -528,7 +555,7 @@ ON CONFLICT(id) DO UPDATE SET mint_quote "#, )? - .fetch_all(&self.db) + .fetch_all(&*conn) .await? .into_iter() .map(sql_row_to_mint_quote) @@ -537,9 +564,10 @@ ON CONFLICT(id) DO UPDATE SET #[instrument(skip(self))] async fn remove_mint_quote(&self, quote_id: &str) -> Result<(), Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; query(r#"DELETE FROM mint_quote WHERE id=:id"#)? .bind("id", quote_id.to_string()) - .execute(&self.db) + .execute(&*conn) .await?; Ok(()) @@ -547,6 +575,7 @@ ON CONFLICT(id) DO UPDATE SET #[instrument(skip_all)] async fn add_melt_quote(&self, quote: wallet::MeltQuote) -> Result<(), Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; query( r#" INSERT INTO melt_quote @@ -570,7 +599,7 @@ ON CONFLICT(id) DO UPDATE SET .bind("fee_reserve", u64::from(quote.fee_reserve) as i64) .bind("state", quote.state.to_string()) .bind("expiry", quote.expiry as i64) - .execute(&self.db) + .execute(&*conn) .await?; Ok(()) @@ -578,6 +607,7 @@ ON CONFLICT(id) DO UPDATE SET #[instrument(skip(self))] async fn get_melt_quote(&self, quote_id: &str) -> Result, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; Ok(query( r#" SELECT @@ -596,7 +626,7 @@ ON CONFLICT(id) DO UPDATE SET "#, )? .bind("id", quote_id.to_owned()) - .fetch_one(&self.db) + .fetch_one(&*conn) .await? .map(sql_row_to_melt_quote) .transpose()?) @@ -604,9 +634,10 @@ ON CONFLICT(id) DO UPDATE SET #[instrument(skip(self))] async fn remove_melt_quote(&self, quote_id: &str) -> Result<(), Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; query(r#"DELETE FROM melt_quote WHERE id=:id"#)? .bind("id", quote_id.to_owned()) - .execute(&self.db) + .execute(&*conn) .await?; Ok(()) @@ -614,6 +645,8 @@ ON CONFLICT(id) DO UPDATE SET #[instrument(skip_all)] async fn add_keys(&self, keyset: KeySet) -> Result<(), Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; + // Recompute ID for verification keyset.verify_id()?; @@ -631,7 +664,7 @@ ON CONFLICT(id) DO UPDATE SET serde_json::to_string(&keyset.keys).map_err(Error::from)?, ) .bind("keyset_u32", u32::from(keyset.id)) - .execute(&self.db) + .execute(&*conn) .await?; Ok(()) @@ -639,6 +672,7 @@ ON CONFLICT(id) DO UPDATE SET #[instrument(skip(self), fields(keyset_id = %keyset_id))] async fn get_keys(&self, keyset_id: &Id) -> Result, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; Ok(query( r#" SELECT @@ -648,7 +682,7 @@ ON CONFLICT(id) DO UPDATE SET "#, )? .bind("id", keyset_id.to_string()) - .pluck(&self.db) + .pluck(&*conn) .await? .map(|keys| { let keys = column_as_string!(keys); @@ -659,9 +693,10 @@ ON CONFLICT(id) DO UPDATE SET #[instrument(skip(self))] async fn remove_keys(&self, id: &Id) -> Result<(), Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; query(r#"DELETE FROM key WHERE id = :id"#)? .bind("id", id.to_string()) - .pluck(&self.db) + .pluck(&*conn) .await?; Ok(()) @@ -672,6 +707,10 @@ ON CONFLICT(id) DO UPDATE SET added: Vec, removed_ys: Vec, ) -> Result<(), Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; + + let tx = ConnectionWithTransaction::new(conn).await?; + // TODO: Use a transaction for all these operations for proof in added { query( @@ -729,7 +768,7 @@ ON CONFLICT(id) DO UPDATE SET "dleq_r", proof.proof.dleq.as_ref().map(|dleq| dleq.r.to_secret_bytes().to_vec()), ) - .execute(&self.db).await?; + .execute(&tx).await?; } query(r#"DELETE FROM proof WHERE y IN (:ys)"#)? @@ -737,9 +776,11 @@ ON CONFLICT(id) DO UPDATE SET "ys", removed_ys.iter().map(|y| y.to_bytes().to_vec()).collect(), ) - .execute(&self.db) + .execute(&tx) .await?; + tx.commit().await?; + Ok(()) } @@ -751,6 +792,7 @@ ON CONFLICT(id) DO UPDATE SET state: Option>, spending_conditions: Option>, ) -> Result, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; Ok(query( r#" SELECT @@ -770,7 +812,7 @@ ON CONFLICT(id) DO UPDATE SET FROM proof "#, )? - .fetch_all(&self.db) + .fetch_all(&*conn) .await? .into_iter() .filter_map(|row| { @@ -786,10 +828,11 @@ ON CONFLICT(id) DO UPDATE SET } async fn update_proofs_state(&self, ys: Vec, state: State) -> Result<(), Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; query("UPDATE proof SET state = :state WHERE y IN (:ys)")? .bind_vec("ys", ys.iter().map(|y| y.to_bytes().to_vec()).collect()) .bind("state", state.to_string()) - .execute(&self.db) + .execute(&*conn) .await?; Ok(()) @@ -797,6 +840,7 @@ ON CONFLICT(id) DO UPDATE SET #[instrument(skip(self), fields(keyset_id = %keyset_id))] async fn increment_keyset_counter(&self, keyset_id: &Id, count: u32) -> Result<(), Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; query( r#" UPDATE keyset @@ -806,7 +850,7 @@ ON CONFLICT(id) DO UPDATE SET )? .bind("count", count) .bind("id", keyset_id.to_string()) - .execute(&self.db) + .execute(&*conn) .await?; Ok(()) @@ -814,6 +858,7 @@ ON CONFLICT(id) DO UPDATE SET #[instrument(skip(self), fields(keyset_id = %keyset_id))] async fn get_keyset_counter(&self, keyset_id: &Id) -> Result, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; Ok(query( r#" SELECT @@ -825,7 +870,7 @@ ON CONFLICT(id) DO UPDATE SET "#, )? .bind("id", keyset_id.to_string()) - .pluck(&self.db) + .pluck(&*conn) .await? .map(|n| Ok::<_, Error>(column_as_number!(n))) .transpose()?) @@ -833,6 +878,7 @@ ON CONFLICT(id) DO UPDATE SET #[instrument(skip(self))] async fn add_transaction(&self, transaction: Transaction) -> Result<(), Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; let mint_url = transaction.mint_url.to_string(); let direction = transaction.direction.to_string(); let unit = transaction.unit.to_string(); @@ -876,7 +922,7 @@ ON CONFLICT(id) DO UPDATE SET "metadata", serde_json::to_string(&transaction.metadata).map_err(Error::from)?, ) - .execute(&self.db) + .execute(&*conn) .await?; Ok(()) @@ -887,6 +933,7 @@ ON CONFLICT(id) DO UPDATE SET &self, transaction_id: TransactionId, ) -> Result, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; Ok(query( r#" SELECT @@ -906,7 +953,7 @@ ON CONFLICT(id) DO UPDATE SET "#, )? .bind("id", transaction_id.as_slice().to_vec()) - .fetch_one(&self.db) + .fetch_one(&*conn) .await? .map(sql_row_to_transaction) .transpose()?) @@ -919,6 +966,8 @@ ON CONFLICT(id) DO UPDATE SET direction: Option, unit: Option, ) -> Result, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; + Ok(query( r#" SELECT @@ -935,7 +984,7 @@ ON CONFLICT(id) DO UPDATE SET transactions "#, )? - .fetch_all(&self.db) + .fetch_all(&*conn) .await? .into_iter() .filter_map(|row| { @@ -952,9 +1001,11 @@ ON CONFLICT(id) DO UPDATE SET #[instrument(skip(self))] async fn remove_transaction(&self, transaction_id: TransactionId) -> Result<(), Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; + query(r#"DELETE FROM transactions WHERE id=:id"#)? .bind("id", transaction_id.as_slice().to_vec()) - .execute(&self.db) + .execute(&*conn) .await?; Ok(()) diff --git a/crates/cdk-sqlite/src/async_sqlite.rs b/crates/cdk-sqlite/src/async_sqlite.rs new file mode 100644 index 000000000..2efe47e15 --- /dev/null +++ b/crates/cdk-sqlite/src/async_sqlite.rs @@ -0,0 +1,197 @@ +//! Simple SQLite +use cdk_common::database::Error; +use cdk_sql_common::database::{DatabaseConnector, DatabaseExecutor, DatabaseTransaction}; +use cdk_sql_common::stmt::{query, Column, SqlPart, Statement}; +use rusqlite::{ffi, CachedStatement, Connection, Error as SqliteError, ErrorCode}; +use tokio::sync::Mutex; + +use crate::common::{from_sqlite, to_sqlite}; + +/// Async Sqlite wrapper +#[derive(Debug)] +pub struct AsyncSqlite { + inner: Mutex, +} + +impl AsyncSqlite { + pub fn new(inner: Connection) -> Self { + Self { + inner: inner.into(), + } + } +} +impl AsyncSqlite { + fn get_stmt<'a>( + &self, + conn: &'a Connection, + statement: Statement, + ) -> Result, Error> { + let (sql, placeholder_values) = statement.to_sql()?; + + let new_sql = sql.trim().trim_end_matches("FOR UPDATE"); + + let mut stmt = conn + .prepare_cached(new_sql) + .map_err(|e| Error::Database(Box::new(e)))?; + + for (i, value) in placeholder_values.into_iter().enumerate() { + stmt.raw_bind_parameter(i + 1, to_sqlite(value)) + .map_err(|e| Error::Database(Box::new(e)))?; + } + + Ok(stmt) + } +} + +#[inline(always)] +fn to_sqlite_error(err: SqliteError) -> Error { + tracing::error!("Failed query with error {:?}", err); + if let rusqlite::Error::SqliteFailure( + ffi::Error { + code, + extended_code, + }, + _, + ) = err + { + if code == ErrorCode::ConstraintViolation + && (extended_code == ffi::SQLITE_CONSTRAINT_PRIMARYKEY + || extended_code == ffi::SQLITE_CONSTRAINT_UNIQUE) + { + Error::Duplicate + } else { + Error::Database(Box::new(err)) + } + } else { + Error::Database(Box::new(err)) + } +} + +/// SQLite trasanction handler +pub struct SQLiteTransactionHandler; + +#[async_trait::async_trait] +impl DatabaseTransaction for SQLiteTransactionHandler { + /// Consumes the current transaction committing the changes + async fn commit(conn: &mut AsyncSqlite) -> Result<(), Error> { + query("COMMIT")?.execute(conn).await?; + Ok(()) + } + + /// Begin a transaction + async fn begin(conn: &mut AsyncSqlite) -> Result<(), Error> { + query("BEGIN IMMEDIATE")?.execute(conn).await?; + Ok(()) + } + + /// Consumes the transaction rolling back all changes + async fn rollback(conn: &mut AsyncSqlite) -> Result<(), Error> { + query("ROLLBACK")?.execute(conn).await?; + Ok(()) + } +} + +impl DatabaseConnector for AsyncSqlite { + type Transaction = SQLiteTransactionHandler; +} + +#[async_trait::async_trait] +impl DatabaseExecutor for AsyncSqlite { + fn name() -> &'static str { + "sqlite" + } + + async fn execute(&self, statement: Statement) -> Result { + let conn = self.inner.lock().await; + + let mut stmt = self + .get_stmt(&conn, statement) + .map_err(|e| Error::Database(Box::new(e)))?; + + Ok(stmt.raw_execute().map_err(to_sqlite_error)?) + } + + async fn fetch_one(&self, statement: Statement) -> Result>, Error> { + let conn = self.inner.lock().await; + let mut stmt = self + .get_stmt(&conn, statement) + .map_err(|e| Error::Database(Box::new(e)))?; + + let columns = stmt.column_count(); + + let mut rows = stmt.raw_query(); + rows.next() + .map_err(to_sqlite_error)? + .map(|row| { + (0..columns) + .map(|i| row.get(i).map(from_sqlite)) + .collect::, _>>() + }) + .transpose() + .map_err(to_sqlite_error) + } + + async fn fetch_all(&self, statement: Statement) -> Result>, Error> { + let conn = self.inner.lock().await; + let mut stmt = self + .get_stmt(&conn, statement) + .map_err(|e| Error::Database(Box::new(e)))?; + + let columns = stmt.column_count(); + + let mut rows = stmt.raw_query(); + let mut results = vec![]; + + while let Some(row) = rows.next().map_err(to_sqlite_error)? { + results.push( + (0..columns) + .map(|i| row.get(i).map(from_sqlite)) + .collect::, _>>() + .map_err(to_sqlite_error)?, + ) + } + + Ok(results) + } + + async fn pluck(&self, statement: Statement) -> Result, Error> { + let conn = self.inner.lock().await; + let mut stmt = self + .get_stmt(&conn, statement) + .map_err(|e| Error::Database(Box::new(e)))?; + + let mut rows = stmt.raw_query(); + rows.next() + .map_err(to_sqlite_error)? + .map(|row| row.get(0usize).map(from_sqlite)) + .transpose() + .map_err(to_sqlite_error) + } + + async fn batch(&self, mut statement: Statement) -> Result<(), Error> { + let sql = { + let part = statement + .parts + .pop() + .ok_or(Error::Internal("Empty SQL".to_owned()))?; + + if !statement.parts.is_empty() || matches!(part, SqlPart::Placeholder(_, _)) { + return Err(Error::Internal( + "Invalid usage, batch does not support placeholders".to_owned(), + )); + } + + if let SqlPart::Raw(sql) = part { + sql + } else { + unreachable!() + } + }; + + self.inner + .lock() + .await + .execute_batch(&sql) + .map_err(to_sqlite_error) + } +} diff --git a/crates/cdk-sqlite/src/common.rs b/crates/cdk-sqlite/src/common.rs index e0ea6f9ed..e42d0b791 100644 --- a/crates/cdk-sqlite/src/common.rs +++ b/crates/cdk-sqlite/src/common.rs @@ -1,11 +1,14 @@ +use std::path::PathBuf; use std::sync::atomic::AtomicBool; use std::sync::Arc; use std::time::Duration; -use cdk_sql_common::pool::{self, Pool, ResourceManager}; +use cdk_sql_common::pool::{self, DatabasePool}; use cdk_sql_common::value::Value; use rusqlite::Connection; +use crate::async_sqlite; + /// The config need to create a new SQLite connection #[derive(Clone, Debug)] pub struct Config { @@ -13,14 +16,28 @@ pub struct Config { password: Option, } +impl pool::DatabaseConfig for Config { + fn default_timeout(&self) -> Duration { + Duration::from_secs(5) + } + + fn max_size(&self) -> usize { + if self.password.is_none() { + 1 + } else { + 20 + } + } +} + /// Sqlite connection manager #[derive(Debug)] pub struct SqliteConnectionManager; -impl ResourceManager for SqliteConnectionManager { +impl DatabasePool for SqliteConnectionManager { type Config = Config; - type Resource = Connection; + type Connection = async_sqlite::AsyncSqlite; type Error = rusqlite::Error; @@ -28,7 +45,7 @@ impl ResourceManager for SqliteConnectionManager { config: &Self::Config, _stale: Arc, _timeout: Duration, - ) -> Result> { + ) -> Result> { let conn = if let Some(path) = config.path.as_ref() { Connection::open(path)? } else { @@ -52,35 +69,58 @@ impl ResourceManager for SqliteConnectionManager { conn.busy_timeout(Duration::from_secs(10))?; - Ok(conn) + Ok(async_sqlite::AsyncSqlite::new(conn)) } } -/// Create a configured rusqlite connection to a SQLite database. -/// For SQLCipher support, enable the "sqlcipher" feature and pass a password. -pub fn create_sqlite_pool( - path: &str, - password: Option, -) -> Arc> { - let (config, max_size) = if path.contains(":memory:") { - ( +impl From for Config { + fn from(path: PathBuf) -> Self { + path.to_str().unwrap_or_default().into() + } +} + +impl From<(PathBuf, String)> for Config { + fn from((path, password): (PathBuf, String)) -> Self { + (path.to_str().unwrap_or_default(), password.as_str()).into() + } +} + +impl From<&PathBuf> for Config { + fn from(path: &PathBuf) -> Self { + path.to_str().unwrap_or_default().into() + } +} + +impl From<&str> for Config { + fn from(path: &str) -> Self { + if path.contains(":memory:") { Config { path: None, - password, - }, - 1, - ) - } else { - ( + password: None, + } + } else { Config { path: Some(path.to_owned()), - password, - }, - 20, - ) - }; + password: None, + } + } + } +} - Pool::new(config, max_size, Duration::from_secs(10)) +impl From<(&str, &str)> for Config { + fn from((path, pass): (&str, &str)) -> Self { + if path.contains(":memory:") { + Config { + path: None, + password: Some(pass.to_owned()), + } + } else { + Config { + path: Some(path.to_owned()), + password: Some(pass.to_owned()), + } + } + } } /// Convert cdk_sql_common::value::Value to rusqlite Value diff --git a/crates/cdk-sqlite/src/lib.rs b/crates/cdk-sqlite/src/lib.rs index 4c50a5ff2..2610f682f 100644 --- a/crates/cdk-sqlite/src/lib.rs +++ b/crates/cdk-sqlite/src/lib.rs @@ -3,6 +3,7 @@ #![warn(missing_docs)] #![warn(rustdoc::bare_urls)] +mod async_sqlite; mod common; #[cfg(feature = "mint")] diff --git a/crates/cdk-sqlite/src/mint/async_rusqlite.rs b/crates/cdk-sqlite/src/mint/async_rusqlite.rs deleted file mode 100644 index 920660f9d..000000000 --- a/crates/cdk-sqlite/src/mint/async_rusqlite.rs +++ /dev/null @@ -1,727 +0,0 @@ -//! Async, pipelined rusqlite client -use std::marker::PhantomData; -use std::path::PathBuf; -use std::sync::atomic::{AtomicUsize, Ordering}; -use std::sync::{mpsc as std_mpsc, Arc, Mutex}; -use std::thread::spawn; -use std::time::Instant; - -use cdk_common::database::Error; -use cdk_sql_common::database::{DatabaseConnector, DatabaseExecutor, DatabaseTransaction}; -use cdk_sql_common::pool::{self, Pool, PooledResource}; -use cdk_sql_common::stmt::{Column, ExpectedSqlResponse, Statement as InnerStatement}; -use cdk_sql_common::ConversionError; -use rusqlite::{ffi, Connection, ErrorCode, TransactionBehavior}; -use tokio::sync::{mpsc, oneshot}; - -use crate::common::{create_sqlite_pool, from_sqlite, to_sqlite, SqliteConnectionManager}; - -/// The number of queued SQL statements before it start failing -const SQL_QUEUE_SIZE: usize = 10_000; -/// How many ms is considered a slow query, and it'd be logged for further debugging -const SLOW_QUERY_THRESHOLD_MS: u128 = 20; -/// How many SQLite parallel connections can be used to read things in parallel -const WORKING_THREAD_POOL_SIZE: usize = 5; - -#[derive(Debug, Clone)] -pub struct AsyncRusqlite { - sender: mpsc::Sender, - inflight_requests: Arc, -} - -impl From for AsyncRusqlite { - fn from(value: PathBuf) -> Self { - AsyncRusqlite::new(create_sqlite_pool(value.to_str().unwrap_or_default(), None)) - } -} - -impl From<&str> for AsyncRusqlite { - fn from(value: &str) -> Self { - AsyncRusqlite::new(create_sqlite_pool(value, None)) - } -} - -impl From<(&str, &str)> for AsyncRusqlite { - fn from((value, pass): (&str, &str)) -> Self { - AsyncRusqlite::new(create_sqlite_pool(value, Some(pass.to_owned()))) - } -} - -impl From<(PathBuf, &str)> for AsyncRusqlite { - fn from((value, pass): (PathBuf, &str)) -> Self { - AsyncRusqlite::new(create_sqlite_pool( - value.to_str().unwrap_or_default(), - Some(pass.to_owned()), - )) - } -} - -impl From<(&str, String)> for AsyncRusqlite { - fn from((value, pass): (&str, String)) -> Self { - AsyncRusqlite::new(create_sqlite_pool(value, Some(pass))) - } -} - -impl From<(PathBuf, String)> for AsyncRusqlite { - fn from((value, pass): (PathBuf, String)) -> Self { - AsyncRusqlite::new(create_sqlite_pool( - value.to_str().unwrap_or_default(), - Some(pass), - )) - } -} - -impl From<&PathBuf> for AsyncRusqlite { - fn from(value: &PathBuf) -> Self { - AsyncRusqlite::new(create_sqlite_pool(value.to_str().unwrap_or_default(), None)) - } -} - -/// Internal request for the database thread -#[derive(Debug)] -enum DbRequest { - Sql(InnerStatement, oneshot::Sender), - Begin(oneshot::Sender), - Commit(oneshot::Sender), - Rollback(oneshot::Sender), -} - -#[derive(Debug)] -enum DbResponse { - Transaction(mpsc::Sender), - AffectedRows(usize), - Pluck(Option), - Row(Option>), - Rows(Vec>), - Error(SqliteError), - Unexpected, - Ok, -} - -#[derive(thiserror::Error, Debug)] -enum SqliteError { - #[error(transparent)] - Sqlite(#[from] rusqlite::Error), - - #[error(transparent)] - Inner(#[from] Error), - - #[error(transparent)] - Pool(#[from] pool::Error), - - /// Duplicate entry - #[error("Duplicate")] - Duplicate, - - #[error(transparent)] - Conversion(#[from] ConversionError), -} - -impl From for Error { - fn from(val: SqliteError) -> Self { - match val { - SqliteError::Duplicate => Error::Duplicate, - SqliteError::Conversion(e) => e.into(), - o => Error::Internal(o.to_string()), - } - } -} - -/// Process a query -#[inline(always)] -fn process_query(conn: &Connection, statement: InnerStatement) -> Result { - let start = Instant::now(); - let expected_response = statement.expected_response; - let (sql, placeholder_values) = statement.to_sql()?; - let sql = sql.trim_end_matches("FOR UPDATE"); - - let mut stmt = conn.prepare_cached(sql)?; - for (i, value) in placeholder_values.into_iter().enumerate() { - stmt.raw_bind_parameter(i + 1, to_sqlite(value))?; - } - - let columns = stmt.column_count(); - - let to_return = match expected_response { - ExpectedSqlResponse::AffectedRows => DbResponse::AffectedRows(stmt.raw_execute()?), - ExpectedSqlResponse::Batch => { - conn.execute_batch(sql)?; - DbResponse::Ok - } - ExpectedSqlResponse::ManyRows => { - let mut rows = stmt.raw_query(); - let mut results = vec![]; - - while let Some(row) = rows.next()? { - results.push( - (0..columns) - .map(|i| row.get(i).map(from_sqlite)) - .collect::, _>>()?, - ) - } - - DbResponse::Rows(results) - } - ExpectedSqlResponse::Pluck => { - let mut rows = stmt.raw_query(); - DbResponse::Pluck( - rows.next()? - .map(|row| row.get(0usize).map(from_sqlite)) - .transpose()?, - ) - } - ExpectedSqlResponse::SingleRow => { - let mut rows = stmt.raw_query(); - let row = rows - .next()? - .map(|row| { - (0..columns) - .map(|i| row.get(i).map(from_sqlite)) - .collect::, _>>() - }) - .transpose()?; - DbResponse::Row(row) - } - }; - - let duration = start.elapsed(); - - if duration.as_millis() > SLOW_QUERY_THRESHOLD_MS { - tracing::warn!("[SLOW QUERY] Took {} ms: {}", duration.as_millis(), sql); - } - - Ok(to_return) -} - -/// Spawns N number of threads to execute SQL statements -/// -/// Enable parallelism with a pool of threads. -/// -/// There is a main thread, which receives SQL requests and routes them to a worker thread from a -/// fixed-size pool. -/// -/// By doing so, SQLite does synchronization, and Rust will only intervene when a transaction is -/// executed. Transactions are executed in the main thread. -fn rusqlite_spawn_worker_threads( - inflight_requests: Arc, - threads: usize, -) -> std_mpsc::Sender<( - PooledResource, - InnerStatement, - oneshot::Sender, -)> { - let (sender, receiver) = std_mpsc::channel::<( - PooledResource, - InnerStatement, - oneshot::Sender, - )>(); - let receiver = Arc::new(Mutex::new(receiver)); - - for _ in 0..threads { - let rx = receiver.clone(); - let inflight_requests = inflight_requests.clone(); - spawn(move || loop { - while let Ok((conn, sql, reply_to)) = rx.lock().expect("failed to acquire").recv() { - let result = process_query(&conn, sql); - let _ = match result { - Ok(ok) => reply_to.send(ok), - Err(err) => { - tracing::error!("Failed query with error {:?}", err); - let err = if let SqliteError::Sqlite(rusqlite::Error::SqliteFailure( - ffi::Error { - code, - extended_code, - }, - _, - )) = &err - { - if *code == ErrorCode::ConstraintViolation - && (*extended_code == ffi::SQLITE_CONSTRAINT_PRIMARYKEY - || *extended_code == ffi::SQLITE_CONSTRAINT_UNIQUE) - { - SqliteError::Duplicate - } else { - err - } - } else { - err - }; - - reply_to.send(DbResponse::Error(err)) - } - }; - drop(conn); - inflight_requests.fetch_sub(1, Ordering::Relaxed); - } - }); - } - sender -} - -/// # Rusqlite main worker -/// -/// This function takes ownership of a pool of connections to SQLite, executes SQL statements, and -/// returns the results or number of affected rows to the caller. All communications are done -/// through channels. This function is synchronous, but a thread pool exists to execute queries, and -/// SQLite will coordinate data access. Transactions are executed in the main and it takes ownership -/// of the main thread until it is finalized -/// -/// This is meant to be called in their thread, as it will not exit the loop until the communication -/// channel is closed. -fn rusqlite_worker_manager( - mut receiver: mpsc::Receiver, - pool: Arc>, - inflight_requests: Arc, -) { - let send_sql_to_thread = - rusqlite_spawn_worker_threads(inflight_requests.clone(), WORKING_THREAD_POOL_SIZE); - - let mut tx_id: usize = 0; - - while let Some(request) = receiver.blocking_recv() { - inflight_requests.fetch_add(1, Ordering::Relaxed); - match request { - DbRequest::Sql(statement, reply_to) => { - let conn = match pool.get() { - Ok(conn) => conn, - Err(err) => { - tracing::error!("Failed to acquire a pool connection: {:?}", err); - inflight_requests.fetch_sub(1, Ordering::Relaxed); - let _ = reply_to.send(DbResponse::Error(err.into())); - continue; - } - }; - - let _ = send_sql_to_thread.send((conn, statement, reply_to)); - continue; - } - DbRequest::Begin(reply_to) => { - let (sender, mut receiver) = mpsc::channel(SQL_QUEUE_SIZE); - let mut conn = match pool.get() { - Ok(conn) => conn, - Err(err) => { - tracing::error!("Failed to acquire a pool connection: {:?}", err); - inflight_requests.fetch_sub(1, Ordering::Relaxed); - let _ = reply_to.send(DbResponse::Error(err.into())); - continue; - } - }; - - let tx = match conn.transaction_with_behavior(TransactionBehavior::Immediate) { - Ok(tx) => tx, - Err(err) => { - tracing::error!("Failed to begin a transaction: {:?}", err); - inflight_requests.fetch_sub(1, Ordering::Relaxed); - let _ = reply_to.send(DbResponse::Error(err.into())); - continue; - } - }; - - // Transaction has begun successfully, send the `sender` back to the caller - // and wait for statements to execute. On `Drop` the wrapper transaction - // should send a `rollback`. - let _ = reply_to.send(DbResponse::Transaction(sender)); - - tx_id += 1; - - // We intentionally handle the transaction hijacking the main loop, there is - // no point is queueing more operations for SQLite, since transaction have - // exclusive access. In other database implementation this block of code - // should be sent to their own thread to allow concurrency - loop { - let request = if let Some(request) = receiver.blocking_recv() { - request - } else { - // If the receiver loop is broken (i.e no more `senders` are active) and no - // `Commit` statement has been sent, this will trigger a `Rollback` - // automatically - tracing::trace!("Tx {}: Transaction rollback on drop", tx_id); - let _ = tx.rollback(); - break; - }; - - match request { - DbRequest::Commit(reply_to) => { - tracing::trace!("Tx {}: Commit", tx_id); - let _ = reply_to.send(match tx.commit() { - Ok(()) => DbResponse::Ok, - Err(err) => { - tracing::error!("Failed commit {:?}", err); - DbResponse::Error(err.into()) - } - }); - break; - } - DbRequest::Rollback(reply_to) => { - tracing::trace!("Tx {}: Rollback", tx_id); - let _ = reply_to.send(match tx.rollback() { - Ok(()) => DbResponse::Ok, - Err(err) => { - tracing::error!("Failed rollback {:?}", err); - DbResponse::Error(err.into()) - } - }); - break; - } - DbRequest::Begin(reply_to) => { - let _ = reply_to.send(DbResponse::Unexpected); - } - DbRequest::Sql(statement, reply_to) => { - tracing::trace!("Tx {}: SQL {:?}", tx_id, statement); - let _ = match process_query(&tx, statement) { - Ok(ok) => reply_to.send(ok), - Err(err) => { - tracing::error!( - "Tx {}: Failed query with error {:?}", - tx_id, - err - ); - let err = if let SqliteError::Sqlite( - rusqlite::Error::SqliteFailure( - ffi::Error { - code, - extended_code, - }, - _, - ), - ) = &err - { - if *code == ErrorCode::ConstraintViolation - && (*extended_code == ffi::SQLITE_CONSTRAINT_PRIMARYKEY - || *extended_code == ffi::SQLITE_CONSTRAINT_UNIQUE) - { - SqliteError::Duplicate - } else { - err - } - } else { - err - }; - reply_to.send(DbResponse::Error(err)) - } - }; - } - } - } - - drop(conn); - } - DbRequest::Commit(reply_to) => { - let _ = reply_to.send(DbResponse::Unexpected); - } - DbRequest::Rollback(reply_to) => { - let _ = reply_to.send(DbResponse::Unexpected); - } - } - - // If wasn't a `continue` the transaction is done by reaching this code, and we should - // decrease the inflight_request counter - inflight_requests.fetch_sub(1, Ordering::Relaxed); - } -} - -impl AsyncRusqlite { - /// Creates a new Async Rusqlite wrapper. - pub fn new(pool: Arc>) -> Self { - let (sender, receiver) = mpsc::channel(SQL_QUEUE_SIZE); - let inflight_requests = Arc::new(AtomicUsize::new(0)); - let inflight_requests_for_thread = inflight_requests.clone(); - spawn(move || { - rusqlite_worker_manager(receiver, pool, inflight_requests_for_thread); - }); - - Self { - sender, - inflight_requests, - } - } - - fn get_queue_sender(&self) -> &mpsc::Sender { - &self.sender - } - - /// Show how many inflight requests - #[allow(dead_code)] - pub fn inflight_requests(&self) -> usize { - self.inflight_requests.load(Ordering::Relaxed) - } -} - -#[async_trait::async_trait] -impl DatabaseConnector for AsyncRusqlite { - type Transaction<'a> = Transaction<'a>; - - /// Begins a transaction - /// - /// If the transaction is Drop it will trigger a rollback operation - async fn begin(&self) -> Result, Error> { - let (sender, receiver) = oneshot::channel(); - self.sender - .send(DbRequest::Begin(sender)) - .await - .map_err(|_| Error::Internal("Communication".to_owned()))?; - - match receiver - .await - .map_err(|_| Error::Internal("Communication".to_owned()))? - { - DbResponse::Transaction(db_sender) => Ok(Transaction { - db_sender, - _marker: PhantomData, - }), - DbResponse::Error(err) => Err(err.into()), - _ => Err(Error::InvalidDbResponse), - } - } -} - -#[async_trait::async_trait] -impl DatabaseExecutor for AsyncRusqlite { - fn name() -> &'static str { - "sqlite" - } - - async fn fetch_one(&self, mut statement: InnerStatement) -> Result>, Error> { - let (sender, receiver) = oneshot::channel(); - statement.expected_response = ExpectedSqlResponse::SingleRow; - self.get_queue_sender() - .send(DbRequest::Sql(statement, sender)) - .await - .map_err(|_| Error::Internal("Communication".to_owned()))?; - - match receiver - .await - .map_err(|_| Error::Internal("Communication".to_owned()))? - { - DbResponse::Row(row) => Ok(row), - DbResponse::Error(err) => Err(err.into()), - _ => Err(Error::InvalidDbResponse), - } - } - - async fn batch(&self, mut statement: InnerStatement) -> Result<(), Error> { - let (sender, receiver) = oneshot::channel(); - statement.expected_response = ExpectedSqlResponse::Batch; - self.get_queue_sender() - .send(DbRequest::Sql(statement, sender)) - .await - .map_err(|_| Error::Internal("Communication".to_owned()))?; - - match receiver - .await - .map_err(|_| Error::Internal("Communication".to_owned()))? - { - DbResponse::Ok => Ok(()), - DbResponse::Error(err) => Err(err.into()), - _ => Err(Error::InvalidDbResponse), - } - } - - async fn fetch_all(&self, mut statement: InnerStatement) -> Result>, Error> { - let (sender, receiver) = oneshot::channel(); - statement.expected_response = ExpectedSqlResponse::ManyRows; - self.get_queue_sender() - .send(DbRequest::Sql(statement, sender)) - .await - .map_err(|_| Error::Internal("Communication".to_owned()))?; - - match receiver - .await - .map_err(|_| Error::Internal("Communication".to_owned()))? - { - DbResponse::Rows(row) => Ok(row), - DbResponse::Error(err) => Err(err.into()), - _ => Err(Error::InvalidDbResponse), - } - } - - async fn execute(&self, mut statement: InnerStatement) -> Result { - let (sender, receiver) = oneshot::channel(); - statement.expected_response = ExpectedSqlResponse::AffectedRows; - self.get_queue_sender() - .send(DbRequest::Sql(statement, sender)) - .await - .map_err(|_| Error::Internal("Communication".to_owned()))?; - - match receiver - .await - .map_err(|_| Error::Internal("Communication".to_owned()))? - { - DbResponse::AffectedRows(total) => Ok(total), - DbResponse::Error(err) => Err(err.into()), - _ => Err(Error::InvalidDbResponse), - } - } - - async fn pluck(&self, mut statement: InnerStatement) -> Result, Error> { - let (sender, receiver) = oneshot::channel(); - statement.expected_response = ExpectedSqlResponse::Pluck; - self.get_queue_sender() - .send(DbRequest::Sql(statement, sender)) - .await - .map_err(|_| Error::Internal("Communication".to_owned()))?; - - match receiver - .await - .map_err(|_| Error::Internal("Communication".to_owned()))? - { - DbResponse::Pluck(value) => Ok(value), - DbResponse::Error(err) => Err(err.into()), - _ => Err(Error::InvalidDbResponse), - } - } -} - -/// Database transaction -#[derive(Debug)] -pub struct Transaction<'conn> { - db_sender: mpsc::Sender, - _marker: PhantomData<&'conn ()>, -} - -impl Transaction<'_> { - fn get_queue_sender(&self) -> &mpsc::Sender { - &self.db_sender - } -} - -impl Drop for Transaction<'_> { - fn drop(&mut self) { - let (sender, _) = oneshot::channel(); - let _ = self.db_sender.try_send(DbRequest::Rollback(sender)); - } -} - -#[async_trait::async_trait] -impl<'a> DatabaseTransaction<'a> for Transaction<'a> { - async fn commit(self) -> Result<(), Error> { - let (sender, receiver) = oneshot::channel(); - self.db_sender - .send(DbRequest::Commit(sender)) - .await - .map_err(|_| Error::Internal("Communication".to_owned()))?; - - match receiver - .await - .map_err(|_| Error::Internal("Communication".to_owned()))? - { - DbResponse::Ok => Ok(()), - DbResponse::Error(err) => Err(err.into()), - _ => Err(Error::InvalidDbResponse), - } - } - - async fn rollback(self) -> Result<(), Error> { - let (sender, receiver) = oneshot::channel(); - self.db_sender - .send(DbRequest::Rollback(sender)) - .await - .map_err(|_| Error::Internal("Communication".to_owned()))?; - - match receiver - .await - .map_err(|_| Error::Internal("Communication".to_owned()))? - { - DbResponse::Ok => Ok(()), - DbResponse::Error(err) => Err(err.into()), - _ => Err(Error::InvalidDbResponse), - } - } -} - -#[async_trait::async_trait] -impl DatabaseExecutor for Transaction<'_> { - fn name() -> &'static str { - "sqlite" - } - - async fn fetch_one(&self, mut statement: InnerStatement) -> Result>, Error> { - let (sender, receiver) = oneshot::channel(); - statement.expected_response = ExpectedSqlResponse::SingleRow; - self.get_queue_sender() - .send(DbRequest::Sql(statement, sender)) - .await - .map_err(|_| Error::Internal("Communication".to_owned()))?; - - match receiver - .await - .map_err(|_| Error::Internal("Communication".to_owned()))? - { - DbResponse::Row(row) => Ok(row), - DbResponse::Error(err) => Err(err.into()), - _ => Err(Error::InvalidDbResponse), - } - } - - async fn batch(&self, mut statement: InnerStatement) -> Result<(), Error> { - let (sender, receiver) = oneshot::channel(); - statement.expected_response = ExpectedSqlResponse::Batch; - self.get_queue_sender() - .send(DbRequest::Sql(statement, sender)) - .await - .map_err(|_| Error::Internal("Communication".to_owned()))?; - - match receiver - .await - .map_err(|_| Error::Internal("Communication".to_owned()))? - { - DbResponse::Ok => Ok(()), - DbResponse::Error(err) => Err(err.into()), - _ => Err(Error::InvalidDbResponse), - } - } - - async fn fetch_all(&self, mut statement: InnerStatement) -> Result>, Error> { - let (sender, receiver) = oneshot::channel(); - statement.expected_response = ExpectedSqlResponse::ManyRows; - self.get_queue_sender() - .send(DbRequest::Sql(statement, sender)) - .await - .map_err(|_| Error::Internal("Communication".to_owned()))?; - - match receiver - .await - .map_err(|_| Error::Internal("Communication".to_owned()))? - { - DbResponse::Rows(row) => Ok(row), - DbResponse::Error(err) => Err(err.into()), - _ => Err(Error::InvalidDbResponse), - } - } - - async fn execute(&self, mut statement: InnerStatement) -> Result { - let (sender, receiver) = oneshot::channel(); - statement.expected_response = ExpectedSqlResponse::AffectedRows; - self.get_queue_sender() - .send(DbRequest::Sql(statement, sender)) - .await - .map_err(|_| Error::Internal("Communication".to_owned()))?; - - match receiver - .await - .map_err(|_| Error::Internal("Communication".to_owned()))? - { - DbResponse::AffectedRows(total) => Ok(total), - DbResponse::Error(err) => Err(err.into()), - _ => Err(Error::InvalidDbResponse), - } - } - - async fn pluck(&self, mut statement: InnerStatement) -> Result, Error> { - let (sender, receiver) = oneshot::channel(); - statement.expected_response = ExpectedSqlResponse::Pluck; - self.get_queue_sender() - .send(DbRequest::Sql(statement, sender)) - .await - .map_err(|_| Error::Internal("Communication".to_owned()))?; - - match receiver - .await - .map_err(|_| Error::Internal("Communication".to_owned()))? - { - DbResponse::Pluck(value) => Ok(value), - DbResponse::Error(err) => Err(err.into()), - _ => Err(Error::InvalidDbResponse), - } - } -} diff --git a/crates/cdk-sqlite/src/mint/mod.rs b/crates/cdk-sqlite/src/mint/mod.rs index acfa09583..14909e80f 100644 --- a/crates/cdk-sqlite/src/mint/mod.rs +++ b/crates/cdk-sqlite/src/mint/mod.rs @@ -3,26 +3,27 @@ use cdk_sql_common::mint::SQLMintAuthDatabase; use cdk_sql_common::SQLMintDatabase; -mod async_rusqlite; +use crate::common::SqliteConnectionManager; pub mod memory; /// Mint SQLite implementation with rusqlite -pub type MintSqliteDatabase = SQLMintDatabase; +pub type MintSqliteDatabase = SQLMintDatabase; /// Mint Auth database with rusqlite #[cfg(feature = "auth")] -pub type MintSqliteAuthDatabase = SQLMintAuthDatabase; +pub type MintSqliteAuthDatabase = SQLMintAuthDatabase; #[cfg(test)] mod test { use std::fs::remove_file; use cdk_common::mint_db_test; + use cdk_sql_common::pool::Pool; use cdk_sql_common::stmt::query; use super::*; - use crate::mint::async_rusqlite::AsyncRusqlite; + use crate::common::Config; async fn provide_db() -> MintSqliteDatabase { memory::empty().await.unwrap() @@ -40,13 +41,17 @@ mod test { { let _ = remove_file(&file); #[cfg(not(feature = "sqlcipher"))] - let conn: AsyncRusqlite = file.as_str().into(); + let config: Config = file.as_str().into(); #[cfg(feature = "sqlcipher")] - let conn: AsyncRusqlite = (file.as_str(), "test".to_owned()).into(); + let config: Config = (file.as_str(), "test").into(); + + let pool = Pool::::new(config); + + let conn = pool.get().expect("valid connection"); query(include_str!("../../tests/legacy-sqlx.sql")) .expect("query") - .execute(&conn) + .execute(&*conn) .await .expect("create former db failed"); } @@ -55,7 +60,7 @@ mod test { let conn = MintSqliteDatabase::new(file.as_str()).await; #[cfg(feature = "sqlcipher")] - let conn = MintSqliteDatabase::new((file.as_str(), "test".to_owned())).await; + let conn = MintSqliteDatabase::new((file.as_str(), "test")).await; assert!(conn.is_ok(), "Failed with {:?}", conn.unwrap_err()); diff --git a/crates/cdk-sqlite/src/wallet/mod.rs b/crates/cdk-sqlite/src/wallet/mod.rs index 5166baebc..add3937ef 100644 --- a/crates/cdk-sqlite/src/wallet/mod.rs +++ b/crates/cdk-sqlite/src/wallet/mod.rs @@ -1,195 +1,13 @@ //! SQLite Wallet Database -use std::path::PathBuf; -use std::sync::Arc; - -use cdk_common::database::Error; -use cdk_sql_common::database::DatabaseExecutor; -use cdk_sql_common::pool::{Pool, PooledResource}; -use cdk_sql_common::stmt::{Column, SqlPart, Statement}; use cdk_sql_common::SQLWalletDatabase; -use rusqlite::CachedStatement; -use crate::common::{create_sqlite_pool, from_sqlite, to_sqlite, SqliteConnectionManager}; +use crate::common::SqliteConnectionManager; pub mod memory; -/// Simple Sqlite wapper, since the wallet may not need rusqlite with concurrency, a shared instance -/// may be enough -#[derive(Debug)] -pub struct SimpleAsyncRusqlite(Arc>); - -impl SimpleAsyncRusqlite { - fn get_stmt<'a>( - &self, - conn: &'a PooledResource, - statement: Statement, - ) -> Result, Error> { - let (sql, placeholder_values) = statement.to_sql()?; - let mut stmt = conn - .prepare_cached(&sql) - .map_err(|e| Error::Database(Box::new(e)))?; - - for (i, value) in placeholder_values.into_iter().enumerate() { - stmt.raw_bind_parameter(i + 1, to_sqlite(value)) - .map_err(|e| Error::Database(Box::new(e)))?; - } - - Ok(stmt) - } -} - -#[async_trait::async_trait] -impl DatabaseExecutor for SimpleAsyncRusqlite { - fn name() -> &'static str { - "sqlite" - } - - async fn execute(&self, statement: Statement) -> Result { - let conn = self.0.get().map_err(|e| Error::Database(Box::new(e)))?; - let mut stmt = self - .get_stmt(&conn, statement) - .map_err(|e| Error::Database(Box::new(e)))?; - - Ok(stmt - .raw_execute() - .map_err(|e| Error::Database(Box::new(e)))?) - } - - async fn fetch_one(&self, statement: Statement) -> Result>, Error> { - let conn = self.0.get().map_err(|e| Error::Database(Box::new(e)))?; - let mut stmt = self - .get_stmt(&conn, statement) - .map_err(|e| Error::Database(Box::new(e)))?; - - let columns = stmt.column_count(); - - let mut rows = stmt.raw_query(); - rows.next() - .map_err(|e| Error::Database(Box::new(e)))? - .map(|row| { - (0..columns) - .map(|i| row.get(i).map(from_sqlite)) - .collect::, _>>() - }) - .transpose() - .map_err(|e| Error::Database(Box::new(e))) - } - - async fn fetch_all(&self, statement: Statement) -> Result>, Error> { - let conn = self.0.get().map_err(|e| Error::Database(Box::new(e)))?; - let mut stmt = self - .get_stmt(&conn, statement) - .map_err(|e| Error::Database(Box::new(e)))?; - - let columns = stmt.column_count(); - - let mut rows = stmt.raw_query(); - let mut results = vec![]; - - while let Some(row) = rows.next().map_err(|e| Error::Database(Box::new(e)))? { - results.push( - (0..columns) - .map(|i| row.get(i).map(from_sqlite)) - .collect::, _>>() - .map_err(|e| Error::Database(Box::new(e)))?, - ) - } - - Ok(results) - } - - async fn pluck(&self, statement: Statement) -> Result, Error> { - let conn = self.0.get().map_err(|e| Error::Database(Box::new(e)))?; - let mut stmt = self - .get_stmt(&conn, statement) - .map_err(|e| Error::Database(Box::new(e)))?; - - let mut rows = stmt.raw_query(); - rows.next() - .map_err(|e| Error::Database(Box::new(e)))? - .map(|row| row.get(0usize).map(from_sqlite)) - .transpose() - .map_err(|e| Error::Database(Box::new(e))) - } - - async fn batch(&self, mut statement: Statement) -> Result<(), Error> { - let conn = self.0.get().map_err(|e| Error::Database(Box::new(e)))?; - - let sql = { - let part = statement - .parts - .pop() - .ok_or(Error::Internal("Empty SQL".to_owned()))?; - - if !statement.parts.is_empty() || matches!(part, SqlPart::Placeholder(_, _)) { - return Err(Error::Internal( - "Invalid usage, batch does not support placeholders".to_owned(), - )); - } - - if let SqlPart::Raw(sql) = part { - sql - } else { - unreachable!() - } - }; - - conn.execute_batch(&sql) - .map_err(|e| Error::Database(Box::new(e))) - } -} - -impl From for SimpleAsyncRusqlite { - fn from(value: PathBuf) -> Self { - SimpleAsyncRusqlite(create_sqlite_pool(value.to_str().unwrap_or_default(), None)) - } -} - -impl From<&str> for SimpleAsyncRusqlite { - fn from(value: &str) -> Self { - SimpleAsyncRusqlite(create_sqlite_pool(value, None)) - } -} - -impl From<(&str, &str)> for SimpleAsyncRusqlite { - fn from((value, pass): (&str, &str)) -> Self { - SimpleAsyncRusqlite(create_sqlite_pool(value, Some(pass.to_owned()))) - } -} - -impl From<(PathBuf, &str)> for SimpleAsyncRusqlite { - fn from((value, pass): (PathBuf, &str)) -> Self { - SimpleAsyncRusqlite(create_sqlite_pool( - value.to_str().unwrap_or_default(), - Some(pass.to_owned()), - )) - } -} - -impl From<(&str, String)> for SimpleAsyncRusqlite { - fn from((value, pass): (&str, String)) -> Self { - SimpleAsyncRusqlite(create_sqlite_pool(value, Some(pass))) - } -} - -impl From<(PathBuf, String)> for SimpleAsyncRusqlite { - fn from((value, pass): (PathBuf, String)) -> Self { - SimpleAsyncRusqlite(create_sqlite_pool( - value.to_str().unwrap_or_default(), - Some(pass), - )) - } -} - -impl From<&PathBuf> for SimpleAsyncRusqlite { - fn from(value: &PathBuf) -> Self { - SimpleAsyncRusqlite(create_sqlite_pool(value.to_str().unwrap_or_default(), None)) - } -} - /// Mint SQLite implementation with rusqlite -pub type WalletSqliteDatabase = SQLWalletDatabase; +pub type WalletSqliteDatabase = SQLWalletDatabase; #[cfg(test)] mod tests { @@ -330,7 +148,7 @@ mod tests { // Test PaymentMethod variants let mint_url = MintUrl::from_str("https://example.com").unwrap(); - let payment_methods = vec![ + let payment_methods = [ PaymentMethod::Bolt11, PaymentMethod::Bolt12, PaymentMethod::Custom("custom".to_string()), From 25e38701d863087e00d67ce658bd66da8375ac13 Mon Sep 17 00:00:00 2001 From: lollerfirst Date: Wed, 6 Aug 2025 17:01:52 +0200 Subject: [PATCH 059/321] update to spec --- crates/cashu/src/nuts/nut13.rs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/crates/cashu/src/nuts/nut13.rs b/crates/cashu/src/nuts/nut13.rs index 59483b89d..054da85b3 100644 --- a/crates/cashu/src/nuts/nut13.rs +++ b/crates/cashu/src/nuts/nut13.rs @@ -69,6 +69,7 @@ impl Secret { message.extend_from_slice(b"Cashu_KDF_HMAC_SHA512"); message.extend_from_slice(&keyset_id.to_bytes()); message.extend_from_slice(&(counter as u64).to_be_bytes()); + message.extend_from_slice(b"\x00"); let mut engine = HmacEngine::::new(seed); engine.input(&message); @@ -103,6 +104,7 @@ impl SecretKey { message.extend_from_slice(b"Cashu_KDF_HMAC_SHA512"); message.extend_from_slice(&keyset_id.to_bytes()); message.extend_from_slice(&(counter as u64).to_be_bytes()); + message.extend_from_slice(b"\x01"); let mut engine = HmacEngine::::new(seed); engine.input(&message); @@ -110,7 +112,7 @@ impl SecretKey { let result_bytes = hmac_result.to_byte_array(); Ok(Self::from(secp256k1::SecretKey::from_slice( - &result_bytes[32..], + &result_bytes[..32], )?)) } } From 2e1099adbe5ee427d5a7d4e413af565f61fd4fd0 Mon Sep 17 00:00:00 2001 From: Cesar Rodas Date: Thu, 7 Aug 2025 21:00:24 -0300 Subject: [PATCH 060/321] Fixed bug to avoid empty calls `get_proofs_states` --- crates/cdk-sql-common/src/mint/auth/mod.rs | 5 +- crates/cdk-sql-common/src/mint/mod.rs | 3 + .../src/mint/subscription/on_subscription.rs | 75 ++++++++++--------- 3 files changed, 48 insertions(+), 35 deletions(-) diff --git a/crates/cdk-sql-common/src/mint/auth/mod.rs b/crates/cdk-sql-common/src/mint/auth/mod.rs index f9d1351a5..c2840aed7 100644 --- a/crates/cdk-sql-common/src/mint/auth/mod.rs +++ b/crates/cdk-sql-common/src/mint/auth/mod.rs @@ -144,7 +144,7 @@ where y: &PublicKey, proofs_state: State, ) -> Result, Self::Err> { - let current_state = query(r#"SELECT state FROM proof WHERE y = :y"#)? + let current_state = query(r#"SELECT state FROM proof WHERE y = :y FOR UPDATE"#)? .bind("y", y.to_bytes().to_vec()) .pluck(&self.inner) .await? @@ -320,6 +320,9 @@ where } async fn get_proofs_states(&self, ys: &[PublicKey]) -> Result>, Self::Err> { + if ys.is_empty() { + return Ok(vec![]); + } let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; let mut current_states = query(r#"SELECT y, state FROM proof WHERE y IN (:ys)"#)? .bind_vec("ys", ys.iter().map(|y| y.to_bytes().to_vec()).collect()) diff --git a/crates/cdk-sql-common/src/mint/mod.rs b/crates/cdk-sql-common/src/mint/mod.rs index b6d6a41cd..fe82c42df 100644 --- a/crates/cdk-sql-common/src/mint/mod.rs +++ b/crates/cdk-sql-common/src/mint/mod.rs @@ -82,6 +82,9 @@ async fn get_current_states( where C: DatabaseExecutor + Send + Sync, { + if ys.is_empty() { + return Ok(Default::default()); + } query(r#"SELECT y, state FROM proof WHERE y IN (:ys)"#)? .bind_vec("ys", ys.iter().map(|y| y.to_bytes().to_vec()).collect()) .fetch_all(conn) diff --git a/crates/cdk/src/mint/subscription/on_subscription.rs b/crates/cdk/src/mint/subscription/on_subscription.rs index efb3598e5..4d57976ff 100644 --- a/crates/cdk/src/mint/subscription/on_subscription.rs +++ b/crates/cdk/src/mint/subscription/on_subscription.rs @@ -57,41 +57,48 @@ impl OnNewSubscription for OnSubscription { } } - to_return.extend( - futures::future::try_join_all(melt_queries) - .await - .map(|quotes| { - quotes - .into_iter() - .filter_map(|quote| quote.map(|x| x.into())) - .map(|x: MeltQuoteBolt11Response| x.into()) - .collect::>() - }) - .map_err(|e| e.to_string())?, - ); - to_return.extend( - futures::future::try_join_all(mint_queries) - .await - .map(|quotes| { - quotes - .into_iter() - .filter_map(|quote| quote.map(|x| x.into())) - .map(|x: MintQuoteBolt11Response| x.into()) - .collect::>() - }) - .map_err(|e| e.to_string())?, - ); + if !melt_queries.is_empty() { + to_return.extend( + futures::future::try_join_all(melt_queries) + .await + .map(|quotes| { + quotes + .into_iter() + .filter_map(|quote| quote.map(|x| x.into())) + .map(|x: MeltQuoteBolt11Response| x.into()) + .collect::>() + }) + .map_err(|e| e.to_string())?, + ); + } + + if !mint_queries.is_empty() { + to_return.extend( + futures::future::try_join_all(mint_queries) + .await + .map(|quotes| { + quotes + .into_iter() + .filter_map(|quote| quote.map(|x| x.into())) + .map(|x: MintQuoteBolt11Response| x.into()) + .collect::>() + }) + .map_err(|e| e.to_string())?, + ); + } - to_return.extend( - datastore - .get_proofs_states(public_keys.as_slice()) - .await - .map_err(|e| e.to_string())? - .into_iter() - .enumerate() - .filter_map(|(idx, state)| state.map(|state| (public_keys[idx], state).into())) - .map(|state: ProofState| state.into()), - ); + if !public_keys.is_empty() { + to_return.extend( + datastore + .get_proofs_states(public_keys.as_slice()) + .await + .map_err(|e| e.to_string())? + .into_iter() + .enumerate() + .filter_map(|(idx, state)| state.map(|state| (public_keys[idx], state).into())) + .map(|state: ProofState| state.into()), + ); + } Ok(to_return) } From 937d9ac43b68bda67aa685bd4531bfb0df8fee33 Mon Sep 17 00:00:00 2001 From: Cesar Rodas Date: Mon, 11 Aug 2025 11:55:52 -0300 Subject: [PATCH 061/321] Introduce `run_db_operation_sync` and `run_db_operation` These functions are designed as a single funnel to talk to the database, whether it is synchronous or asynchronous. This single funnel will log SQL queries and slow operations, providing a clear and unified debug message for the problematic query, so it can be optimized accordingly (for instance, missing indexes or unbound SQL requests). --- crates/cdk-sql-common/src/common.rs | 70 ++++++++++++++++++- crates/cdk-sql-common/src/lib.rs | 1 + crates/cdk-sqlite/src/async_sqlite.rs | 97 +++++++++++++++------------ 3 files changed, 124 insertions(+), 44 deletions(-) diff --git a/crates/cdk-sql-common/src/common.rs b/crates/cdk-sql-common/src/common.rs index f75bb63c9..fb85e7653 100644 --- a/crates/cdk-sql-common/src/common.rs +++ b/crates/cdk-sql-common/src/common.rs @@ -1,13 +1,81 @@ +use std::fmt::Debug; +use std::future::Future; +use std::time::Instant; + +use cdk_common::database::Error; + use crate::database::DatabaseExecutor; use crate::stmt::query; +const SLOW_QUERY_THRESHOLD_MS: u128 = 20; + +/// Run a database operation and log slow operations, it also converts and logs any error with a +/// given info for more context. This function is expecting a synchronous database operation +#[inline(always)] +pub fn run_db_operation_sync( + info: &str, + operation: F, + error_map: E, +) -> Result +where + F: FnOnce() -> Result, + E1: Debug, + E: FnOnce(E1) -> Error, +{ + let start = Instant::now(); + + tracing::trace!("Running db operation {}", info); + + let result = operation().map_err(|e| { + tracing::error!("Query {} failed with error {:?}", info, e); + error_map(e) + }); + + let duration = start.elapsed(); + if duration.as_millis() > SLOW_QUERY_THRESHOLD_MS { + tracing::warn!("[SLOW QUERY] Took {} ms: {}", duration.as_millis(), info); + } + + result +} + +/// Run a database operation and log slow operations, it also converts and logs any error with a +/// given info for more context +#[inline(always)] +pub async fn run_db_operation( + info: &str, + operation: Fut, + error_map: E, +) -> Result +where + Fut: Future>, + E1: Debug, + E: FnOnce(E1) -> Error, +{ + let start = Instant::now(); + + tracing::trace!("Running db operation {}", info); + + let result = operation.await.map_err(|e| { + tracing::error!("Query {} failed with error {:?}", info, e); + error_map(e) + }); + + let duration = start.elapsed(); + if duration.as_millis() > SLOW_QUERY_THRESHOLD_MS { + tracing::warn!("[SLOW QUERY] Took {} ms: {}", duration.as_millis(), info); + } + + result +} + /// Migrates the migration generated by `build.rs` #[inline(always)] pub async fn migrate( conn: &C, db_prefix: &str, migrations: &[(&str, &str, &str)], -) -> Result<(), cdk_common::database::Error> +) -> Result<(), Error> where C: DatabaseExecutor, { diff --git a/crates/cdk-sql-common/src/lib.rs b/crates/cdk-sql-common/src/lib.rs index 8c44b9a44..030204144 100644 --- a/crates/cdk-sql-common/src/lib.rs +++ b/crates/cdk-sql-common/src/lib.rs @@ -11,6 +11,7 @@ pub mod stmt; pub mod value; pub use cdk_common::database::ConversionError; +pub use common::{run_db_operation, run_db_operation_sync}; #[cfg(feature = "mint")] pub mod mint; diff --git a/crates/cdk-sqlite/src/async_sqlite.rs b/crates/cdk-sqlite/src/async_sqlite.rs index 2efe47e15..ce63ed1ec 100644 --- a/crates/cdk-sqlite/src/async_sqlite.rs +++ b/crates/cdk-sqlite/src/async_sqlite.rs @@ -1,6 +1,7 @@ //! Simple SQLite use cdk_common::database::Error; use cdk_sql_common::database::{DatabaseConnector, DatabaseExecutor, DatabaseTransaction}; +use cdk_sql_common::run_db_operation_sync; use cdk_sql_common::stmt::{query, Column, SqlPart, Statement}; use rusqlite::{ffi, CachedStatement, Connection, Error as SqliteError, ErrorCode}; use tokio::sync::Mutex; @@ -25,7 +26,7 @@ impl AsyncSqlite { &self, conn: &'a Connection, statement: Statement, - ) -> Result, Error> { + ) -> Result<(String, CachedStatement<'a>), Error> { let (sql, placeholder_values) = statement.to_sql()?; let new_sql = sql.trim().trim_end_matches("FOR UPDATE"); @@ -39,7 +40,7 @@ impl AsyncSqlite { .map_err(|e| Error::Database(Box::new(e)))?; } - Ok(stmt) + Ok((sql, stmt)) } } @@ -104,68 +105,81 @@ impl DatabaseExecutor for AsyncSqlite { async fn execute(&self, statement: Statement) -> Result { let conn = self.inner.lock().await; - let mut stmt = self + let (sql, mut stmt) = self .get_stmt(&conn, statement) .map_err(|e| Error::Database(Box::new(e)))?; - Ok(stmt.raw_execute().map_err(to_sqlite_error)?) + run_db_operation_sync(&sql, || stmt.raw_execute(), to_sqlite_error) } async fn fetch_one(&self, statement: Statement) -> Result>, Error> { let conn = self.inner.lock().await; - let mut stmt = self + let (sql, mut stmt) = self .get_stmt(&conn, statement) .map_err(|e| Error::Database(Box::new(e)))?; - let columns = stmt.column_count(); - - let mut rows = stmt.raw_query(); - rows.next() - .map_err(to_sqlite_error)? - .map(|row| { - (0..columns) - .map(|i| row.get(i).map(from_sqlite)) - .collect::, _>>() - }) - .transpose() - .map_err(to_sqlite_error) + run_db_operation_sync( + &sql, + || { + let columns = stmt.column_count(); + + let mut rows = stmt.raw_query(); + rows.next()? + .map(|row| { + (0..columns) + .map(|i| row.get(i).map(from_sqlite)) + .collect::, _>>() + }) + .transpose() + }, + to_sqlite_error, + ) } async fn fetch_all(&self, statement: Statement) -> Result>, Error> { let conn = self.inner.lock().await; - let mut stmt = self + let (sql, mut stmt) = self .get_stmt(&conn, statement) .map_err(|e| Error::Database(Box::new(e)))?; let columns = stmt.column_count(); - let mut rows = stmt.raw_query(); - let mut results = vec![]; - - while let Some(row) = rows.next().map_err(to_sqlite_error)? { - results.push( - (0..columns) - .map(|i| row.get(i).map(from_sqlite)) - .collect::, _>>() - .map_err(to_sqlite_error)?, - ) - } - - Ok(results) + run_db_operation_sync( + &sql, + || { + let mut rows = stmt.raw_query(); + let mut results = vec![]; + + while let Some(row) = rows.next()? { + results.push( + (0..columns) + .map(|i| row.get(i).map(from_sqlite)) + .collect::, _>>()?, + ) + } + + Ok(results) + }, + to_sqlite_error, + ) } async fn pluck(&self, statement: Statement) -> Result, Error> { let conn = self.inner.lock().await; - let mut stmt = self + let (sql, mut stmt) = self .get_stmt(&conn, statement) .map_err(|e| Error::Database(Box::new(e)))?; - let mut rows = stmt.raw_query(); - rows.next() - .map_err(to_sqlite_error)? - .map(|row| row.get(0usize).map(from_sqlite)) - .transpose() - .map_err(to_sqlite_error) + run_db_operation_sync( + &sql, + || { + let mut rows = stmt.raw_query(); + rows.next()? + .map(|row| row.get(0usize).map(from_sqlite)) + .transpose() + }, + to_sqlite_error, + ) } async fn batch(&self, mut statement: Statement) -> Result<(), Error> { @@ -187,11 +201,8 @@ impl DatabaseExecutor for AsyncSqlite { unreachable!() } }; + let conn = self.inner.lock().await; - self.inner - .lock() - .await - .execute_batch(&sql) - .map_err(to_sqlite_error) + run_db_operation_sync(&sql, || conn.execute_batch(&sql), to_sqlite_error) } } From b48604e02c14c2c0a71b803835f1e98b9dbf07a9 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Tue, 12 Aug 2025 01:35:30 +0300 Subject: [PATCH 062/321] feat: add nix cache to ci (#949) * feat: add nix cache to ci * feat: shared caches --- .github/workflows/ci.yml | 52 ++++++++++++++++++++++++++++ .github/workflows/nutshell_itest.yml | 6 +++- 2 files changed, 57 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index fec7cec30..d0a08f168 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -21,8 +21,12 @@ jobs: uses: actions/checkout@v4 - name: Install Nix uses: DeterminateSystems/nix-installer-action@v17 + - name: Nix Cache + uses: DeterminateSystems/magic-nix-cache-action@main - name: Rust Cache uses: Swatinem/rust-cache@v2 + with: + shared-key: "nightly" - name: Cargo fmt run: | nix develop -i -L .#nightly --command bash -c ' @@ -53,8 +57,12 @@ jobs: uses: actions/checkout@v4 - name: Install Nix uses: DeterminateSystems/nix-installer-action@v17 + - name: Nix Cache + uses: DeterminateSystems/magic-nix-cache-action@main - name: Rust Cache uses: Swatinem/rust-cache@v2 + with: + shared-key: "stable" - name: Run example run: nix develop -i -L .#stable --command cargo r --example ${{ matrix.build-args }} @@ -135,8 +143,12 @@ jobs: uses: actions/checkout@v4 - name: Install Nix uses: DeterminateSystems/nix-installer-action@v17 + - name: Nix Cache + uses: DeterminateSystems/magic-nix-cache-action@main - name: Rust Cache uses: Swatinem/rust-cache@v2 + with: + shared-key: "stable" - name: Clippy run: nix develop -i -L .#stable --command cargo clippy ${{ matrix.build-args }} -- -D warnings - name: Test @@ -162,8 +174,12 @@ jobs: uses: actions/checkout@v4 - name: Install Nix uses: DeterminateSystems/nix-installer-action@v17 + - name: Nix Cache + uses: DeterminateSystems/magic-nix-cache-action@main - name: Rust Cache uses: Swatinem/rust-cache@v2 + with: + shared-key: "stable" - name: Test run: nix develop -i -L .#stable --command just itest ${{ matrix.database }} @@ -187,8 +203,12 @@ jobs: uses: actions/checkout@v4 - name: Install Nix uses: DeterminateSystems/nix-installer-action@v17 + - name: Nix Cache + uses: DeterminateSystems/magic-nix-cache-action@main - name: Rust Cache uses: Swatinem/rust-cache@v2 + with: + shared-key: "stable" - name: Clippy run: nix develop -i -L .#stable --command cargo clippy -- -D warnings - name: Test fake auth mint @@ -212,8 +232,12 @@ jobs: uses: actions/checkout@v4 - name: Install Nix uses: DeterminateSystems/nix-installer-action@v17 + - name: Nix Cache + uses: DeterminateSystems/magic-nix-cache-action@main - name: Rust Cache uses: Swatinem/rust-cache@v2 + with: + shared-key: "stable" - name: Test fake mint run: nix develop -i -L .#stable --command just test-pure ${{ matrix.database }} - name: Test mint @@ -238,8 +262,12 @@ jobs: uses: actions/checkout@v4 - name: Install Nix uses: DeterminateSystems/nix-installer-action@v17 + - name: Nix Cache + uses: DeterminateSystems/magic-nix-cache-action@main - name: Rust Cache uses: Swatinem/rust-cache@v2 + with: + shared-key: "stable" - name: Test run: nix develop -i -L .#stable --command just itest-payment-processor ${{matrix.ln}} @@ -274,8 +302,12 @@ jobs: uses: actions/checkout@v4 - name: Install Nix uses: DeterminateSystems/nix-installer-action@v17 + - name: Nix Cache + uses: DeterminateSystems/magic-nix-cache-action@main - name: Rust Cache uses: Swatinem/rust-cache@v2 + with: + shared-key: "msrv" - name: Build run: nix develop -i -L .#msrv --command cargo build ${{ matrix.build-args }} @@ -302,8 +334,12 @@ jobs: uses: actions/checkout@v4 - name: Install Nix uses: DeterminateSystems/nix-installer-action@v17 + - name: Nix Cache + uses: DeterminateSystems/magic-nix-cache-action@main - name: Rust Cache uses: Swatinem/rust-cache@v2 + with: + shared-key: "stable" - name: Build cdk and binding run: nix develop -i -L ".#${{ matrix.rust }}" --command cargo build ${{ matrix.build-args }} --target ${{ matrix.target }} @@ -330,8 +366,12 @@ jobs: uses: actions/checkout@v4 - name: Install Nix uses: DeterminateSystems/nix-installer-action@v17 + - name: Nix Cache + uses: DeterminateSystems/magic-nix-cache-action@main - name: Rust Cache uses: Swatinem/rust-cache@v2 + with: + shared-key: "msrv" - name: Build cdk wasm run: nix develop -i -L ".#${{ matrix.rust }}" --command cargo build ${{ matrix.build-args }} --target ${{ matrix.target }} @@ -351,8 +391,12 @@ jobs: uses: actions/checkout@v4 - name: Install Nix uses: DeterminateSystems/nix-installer-action@v17 + - name: Nix Cache + uses: DeterminateSystems/magic-nix-cache-action@main - name: Rust Cache uses: Swatinem/rust-cache@v2 + with: + shared-key: "stable" - name: Start Keycloak with Backup run: | docker compose -f misc/keycloak/docker-compose-recover.yml up -d @@ -377,8 +421,12 @@ jobs: uses: actions/checkout@v4 - name: Install Nix uses: DeterminateSystems/nix-installer-action@v17 + - name: Nix Cache + uses: DeterminateSystems/magic-nix-cache-action@main - name: Rust Cache uses: Swatinem/rust-cache@v2 + with: + shared-key: "stable" - name: Run doc tests run: nix develop -i -L .#stable --command cargo test --doc @@ -392,7 +440,11 @@ jobs: uses: actions/checkout@v4 - name: Install Nix uses: DeterminateSystems/nix-installer-action@v17 + - name: Nix Cache + uses: DeterminateSystems/magic-nix-cache-action@main - name: Rust Cache uses: Swatinem/rust-cache@v2 + with: + shared-key: "stable" - name: Check docs with strict warnings run: nix develop -i -L .#stable --command just docs-strict diff --git a/.github/workflows/nutshell_itest.yml b/.github/workflows/nutshell_itest.yml index 5a97c5d05..4e331d89b 100644 --- a/.github/workflows/nutshell_itest.yml +++ b/.github/workflows/nutshell_itest.yml @@ -12,6 +12,8 @@ jobs: uses: actions/checkout@v4 - name: Install Nix uses: DeterminateSystems/nix-installer-action@v17 + - name: Nix Cache + uses: DeterminateSystems/magic-nix-cache-action@main - name: Rust Cache uses: Swatinem/rust-cache@v2 - name: Test Nutshell @@ -31,6 +33,8 @@ jobs: run: docker pull cashubtc/nutshell:latest - name: Install Nix uses: DeterminateSystems/nix-installer-action@v17 + - name: Nix Cache + uses: DeterminateSystems/magic-nix-cache-action@main - name: Rust Cache uses: Swatinem/rust-cache@v2 - name: Test Nutshell Wallet @@ -38,4 +42,4 @@ jobs: nix develop -i -L .#integration --command just nutshell-wallet-itest - name: Show Docker logs if tests fail if: failure() - run: docker logs nutshell-wallet || true \ No newline at end of file + run: docker logs nutshell-wallet || true From 7af054520edfc836dd95c93b143a90bee87f8e8f Mon Sep 17 00:00:00 2001 From: C Date: Mon, 11 Aug 2025 19:54:37 -0300 Subject: [PATCH 063/321] Add explicit rollback. (#947) The proof_writer implicit rollback on Drop is too slow for our tests causing race conditions with Postgres. This commit enhances the rollback logic and makes it explicit --- crates/cdk/src/mint/melt.rs | 1 + crates/cdk/src/mint/proof_writer.rs | 19 +++++++++++++++++-- 2 files changed, 18 insertions(+), 2 deletions(-) diff --git a/crates/cdk/src/mint/melt.rs b/crates/cdk/src/mint/melt.rs index 2f6c2c5e2..09edc0447 100644 --- a/crates/cdk/src/mint/melt.rs +++ b/crates/cdk/src/mint/melt.rs @@ -662,6 +662,7 @@ impl Mint { "Lightning payment for quote {} failed.", melt_request.quote() ); + proof_writer.rollback().await?; return Err(Error::PaymentFailed); } MeltQuoteState::Pending => { diff --git a/crates/cdk/src/mint/proof_writer.rs b/crates/cdk/src/mint/proof_writer.rs index a9919e91f..eddfc534c 100644 --- a/crates/cdk/src/mint/proof_writer.rs +++ b/crates/cdk/src/mint/proof_writer.rs @@ -143,13 +143,28 @@ impl ProofWriter { } /// Rollback all changes in this ProofWriter consuming it. - pub async fn rollback(mut self, tx: &mut Tx<'_, '_>) -> Result<(), Error> { + pub async fn rollback(mut self) -> Result<(), Error> { + let db = if let Some(db) = self.db.take() { + db + } else { + return Ok(()); + }; + let mut tx = db.begin_transaction().await?; let (ys, original_states) = if let Some(proofs) = self.proof_original_states.take() { proofs.into_iter().unzip::<_, _, Vec<_>, Vec<_>>() } else { return Ok(()); }; - reset_proofs_to_original_state(tx, &ys, original_states).await?; + + tracing::info!( + "Rollback {} proofs to their original states {:?}", + ys.len(), + original_states + ); + + reset_proofs_to_original_state(&mut tx, &ys, original_states).await?; + tx.commit().await?; + Ok(()) } } From 12452680ace43a51660133fb621094d2bfcf12ee Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Tue, 12 Aug 2025 13:13:23 +0100 Subject: [PATCH 064/321] fix: add payment method to quote --- crates/cdk-sql-common/src/mint/mod.rs | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/crates/cdk-sql-common/src/mint/mod.rs b/crates/cdk-sql-common/src/mint/mod.rs index fe82c42df..2d31f02e1 100644 --- a/crates/cdk-sql-common/src/mint/mod.rs +++ b/crates/cdk-sql-common/src/mint/mod.rs @@ -760,13 +760,13 @@ VALUES (:quote_id, :amount, :timestamp); ( id, unit, amount, request, fee_reserve, state, expiry, payment_preimage, request_lookup_id, - created_time, paid_time, options, request_lookup_id_kind + created_time, paid_time, options, request_lookup_id_kind, payment_method ) VALUES ( :id, :unit, :amount, :request, :fee_reserve, :state, :expiry, :payment_preimage, :request_lookup_id, - :created_time, :paid_time, :options, :request_lookup_id_kind + :created_time, :paid_time, :options, :request_lookup_id_kind, :payment_method ) "#, )? @@ -786,6 +786,7 @@ VALUES (:quote_id, :amount, :timestamp); quote.options.map(|o| serde_json::to_string(&o).ok()), ) .bind("request_lookup_id_kind", quote.request_lookup_id.kind()) + .bind("payment_method", quote.payment_method.to_string()) .execute(&self.inner) .await?; From e87d8181373ba15614af191f6a61fb4fe76eb5f3 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Tue, 12 Aug 2025 13:21:33 +0100 Subject: [PATCH 065/321] chore: drop unused mint table melt_request --- .../src/mint/migrations/20250812132015_drop_melt_request.sql | 1 + justfile | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 crates/cdk-sql-common/src/mint/migrations/20250812132015_drop_melt_request.sql diff --git a/crates/cdk-sql-common/src/mint/migrations/20250812132015_drop_melt_request.sql b/crates/cdk-sql-common/src/mint/migrations/20250812132015_drop_melt_request.sql new file mode 100644 index 000000000..c6f7b1e5a --- /dev/null +++ b/crates/cdk-sql-common/src/mint/migrations/20250812132015_drop_melt_request.sql @@ -0,0 +1 @@ +DROP TABLE IF EXISTS melt_request; diff --git a/justfile b/justfile index 9bd1444d6..003b9fedb 100644 --- a/justfile +++ b/justfile @@ -14,7 +14,7 @@ new-migration target name: fi timestamp=$(date +%Y%m%d%H%M%S) - migration_path="./crates/cdk-sqlite/src/{{target}}/migrations/${timestamp}_{{name}}.sql" + migration_path="./crates/cdk-sql-common/src/{{target}}/migrations/${timestamp}_{{name}}.sql" # Create the file mkdir -p "$(dirname "$migration_path")" From 5d98fdf353180bddb452585b0c6c1f6c9b2c90c0 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Wed, 13 Aug 2025 08:54:45 +0100 Subject: [PATCH 066/321] Keyset counter (#950) * feat: refresh keysets * fix(cdk): resolve keyset counter skipping index 0 in deterministic secret generation - Modified Database::get_keyset_counter to return u32 instead of Option - Added database migrations to increment existing keyset counters by 1 - Removed counter increment logic from wallet operations to use actual counter value - Ensures deterministic secret generation starts from index 0 instead of skipping it --- CHANGELOG.md | 3 ++ crates/cdk-cli/src/main.rs | 3 +- crates/cdk-common/src/database/wallet.rs | 2 +- crates/cdk-redb/src/wallet/migrations.rs | 50 ++++++++++++++++++- crates/cdk-redb/src/wallet/mod.rs | 12 +++-- .../cdk-sql-common/src/wallet/migrations.rs | 1 + .../sqlite/20250812084621_keyset_plus_one.sql | 2 + crates/cdk-sql-common/src/wallet/mod.rs | 5 +- crates/cdk/src/wallet/issue/issue_bolt11.rs | 2 - crates/cdk/src/wallet/issue/issue_bolt12.rs | 2 - crates/cdk/src/wallet/melt/melt_bolt11.rs | 2 - crates/cdk/src/wallet/swap.rs | 4 +- 12 files changed, 70 insertions(+), 18 deletions(-) create mode 100644 crates/cdk-sql-common/src/wallet/migrations/sqlite/20250812084621_keyset_plus_one.sql diff --git a/CHANGELOG.md b/CHANGELOG.md index c03aa5bee..ed171e15e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,8 +18,11 @@ - cdk-integration-tests: New binary `start_fake_mint` for testing fake mint instances ([thesimplekid]). - cdk-integration-tests: New binary `start_regtest_mints` for testing regtest mints ([thesimplekid]). - cdk-integration-tests: Shared utilities module for common integration test functionality ([thesimplekid]). +- cdk-redb: Database migration to increment keyset counters by 1 for existing keysets with counter > 0 ([thesimplekid]). +- cdk-sql-common: Database migration to increment keyset counters by 1 for existing keysets with counter > 0 ([thesimplekid]). ### Changed +- cdk-common: Modified `Database::get_keyset_counter` trait method to return `u32` instead of `Option` for simpler keyset counter handling ([thesimplekid]). - cdk: Refactored wallet keyset management methods for better clarity and separation of concerns ([thesimplekid]). - cdk: Renamed `get_keyset_keys` to `fetch_keyset_keys` to indicate network operation ([thesimplekid]). - cdk: Renamed `get_active_mint_keyset` to `fetch_active_keyset` for consistency ([thesimplekid]). diff --git a/crates/cdk-cli/src/main.rs b/crates/cdk-cli/src/main.rs index 31caec4a1..d85cc06bc 100644 --- a/crates/cdk-cli/src/main.rs +++ b/crates/cdk-cli/src/main.rs @@ -211,7 +211,8 @@ async fn main() -> Result<()> { let wallet_clone = wallet.clone(); tokio::spawn(async move { - if let Err(err) = wallet_clone.get_mint_info().await { + // We refresh keysets, this internally gets mint info + if let Err(err) = wallet_clone.refresh_keysets().await { tracing::error!( "Could not get mint quote for {}, {}", wallet_clone.mint_url, diff --git a/crates/cdk-common/src/database/wallet.rs b/crates/cdk-common/src/database/wallet.rs index 074f07086..2e53139f4 100644 --- a/crates/cdk-common/src/database/wallet.rs +++ b/crates/cdk-common/src/database/wallet.rs @@ -102,7 +102,7 @@ pub trait Database: Debug { /// Increment Keyset counter async fn increment_keyset_counter(&self, keyset_id: &Id, count: u32) -> Result<(), Self::Err>; /// Get current Keyset counter - async fn get_keyset_counter(&self, keyset_id: &Id) -> Result, Self::Err>; + async fn get_keyset_counter(&self, keyset_id: &Id) -> Result; /// Add transaction to storage async fn add_transaction(&self, transaction: Transaction) -> Result<(), Self::Err>; diff --git a/crates/cdk-redb/src/wallet/migrations.rs b/crates/cdk-redb/src/wallet/migrations.rs index 56a592163..948e9ab1c 100644 --- a/crates/cdk-redb/src/wallet/migrations.rs +++ b/crates/cdk-redb/src/wallet/migrations.rs @@ -11,7 +11,7 @@ use redb::{ }; use super::Error; -use crate::wallet::{KEYSETS_TABLE, KEYSET_U32_MAPPING, MINT_KEYS_TABLE}; +use crate::wallet::{KEYSETS_TABLE, KEYSET_COUNTER, KEYSET_U32_MAPPING, MINT_KEYS_TABLE}; // const MINTS_TABLE: TableDefinition<&str, &str> = TableDefinition::new("mints_table"); @@ -152,3 +152,51 @@ fn migrate_trim_mint_urls_01_to_02(db: Arc) -> Result<(), Error> { migrate_mint_keyset_table_01_to_02(Arc::clone(&db))?; Ok(()) } + +pub(crate) fn migrate_03_to_04(db: Arc) -> Result { + let write_txn = db.begin_write().map_err(Error::from)?; + + // Get all existing keyset IDs from the KEYSET_COUNTER table that have a counter > 0 + let keyset_ids_to_increment: Vec<(String, u32)>; + { + let table = write_txn.open_table(KEYSET_COUNTER).map_err(Error::from)?; + + keyset_ids_to_increment = table + .iter() + .map_err(Error::from)? + .flatten() + .filter_map(|(keyset_id, counter)| { + let counter_value = counter.value(); + // Only include keysets where counter > 0 + if counter_value > 0 { + Some((keyset_id.value().to_string(), counter_value)) + } else { + None + } + }) + .collect(); + } + + // Increment counter by 1 for all keysets where counter > 0 + { + let mut table = write_txn.open_table(KEYSET_COUNTER).map_err(Error::from)?; + + for (keyset_id, current_counter) in keyset_ids_to_increment { + let new_counter = current_counter + 1; + table + .insert(keyset_id.as_str(), new_counter) + .map_err(Error::from)?; + + tracing::info!( + "Incremented counter for keyset {} from {} to {}", + keyset_id, + current_counter, + new_counter + ); + } + } + + write_txn.commit()?; + + Ok(4) +} diff --git a/crates/cdk-redb/src/wallet/mod.rs b/crates/cdk-redb/src/wallet/mod.rs index 95f6d180a..fba2107ed 100644 --- a/crates/cdk-redb/src/wallet/mod.rs +++ b/crates/cdk-redb/src/wallet/mod.rs @@ -21,7 +21,7 @@ use tracing::instrument; use super::error::Error; use crate::migrations::migrate_00_to_01; -use crate::wallet::migrations::{migrate_01_to_02, migrate_02_to_03}; +use crate::wallet::migrations::{migrate_01_to_02, migrate_02_to_03, migrate_03_to_04}; mod migrations; @@ -46,7 +46,7 @@ const TRANSACTIONS_TABLE: TableDefinition<&[u8], &str> = TableDefinition::new("t const KEYSET_U32_MAPPING: TableDefinition = TableDefinition::new("keyset_u32_mapping"); -const DATABASE_VERSION: u32 = 3; +const DATABASE_VERSION: u32 = 4; /// Wallet Redb Database #[derive(Debug, Clone)] @@ -96,6 +96,10 @@ impl WalletRedbDatabase { current_file_version = migrate_02_to_03(Arc::clone(&db))?; } + if current_file_version == 3 { + current_file_version = migrate_03_to_04(Arc::clone(&db))?; + } + if current_file_version != DATABASE_VERSION { tracing::warn!( "Database upgrade did not complete at {} current is {}", @@ -786,7 +790,7 @@ impl WalletDatabase for WalletRedbDatabase { } #[instrument(skip(self), fields(keyset_id = %keyset_id))] - async fn get_keyset_counter(&self, keyset_id: &Id) -> Result, Self::Err> { + async fn get_keyset_counter(&self, keyset_id: &Id) -> Result { let read_txn = self.db.begin_read().map_err(Error::from)?; let table = read_txn.open_table(KEYSET_COUNTER).map_err(Error::from)?; @@ -794,7 +798,7 @@ impl WalletDatabase for WalletRedbDatabase { .get(keyset_id.to_string().as_str()) .map_err(Error::from)?; - Ok(counter.map(|c| c.value())) + Ok(counter.map_or(0, |c| c.value())) } #[instrument(skip(self))] diff --git a/crates/cdk-sql-common/src/wallet/migrations.rs b/crates/cdk-sql-common/src/wallet/migrations.rs index 8fb3e52fe..842cbd5a5 100644 --- a/crates/cdk-sql-common/src/wallet/migrations.rs +++ b/crates/cdk-sql-common/src/wallet/migrations.rs @@ -20,4 +20,5 @@ pub static MIGRATIONS: &[(&str, &str, &str)] = &[ ("sqlite", "20250616144830_add_keyset_expiry.sql", include_str!(r#"./migrations/sqlite/20250616144830_add_keyset_expiry.sql"#)), ("sqlite", "20250707093445_bolt12.sql", include_str!(r#"./migrations/sqlite/20250707093445_bolt12.sql"#)), ("sqlite", "20250729111701_keyset_v2_u32.sql", include_str!(r#"./migrations/sqlite/20250729111701_keyset_v2_u32.sql"#)), + ("sqlite", "20250812084621_keyset_plus_one.sql", include_str!(r#"./migrations/sqlite/20250812084621_keyset_plus_one.sql"#)), ]; diff --git a/crates/cdk-sql-common/src/wallet/migrations/sqlite/20250812084621_keyset_plus_one.sql b/crates/cdk-sql-common/src/wallet/migrations/sqlite/20250812084621_keyset_plus_one.sql new file mode 100644 index 000000000..bd980b661 --- /dev/null +++ b/crates/cdk-sql-common/src/wallet/migrations/sqlite/20250812084621_keyset_plus_one.sql @@ -0,0 +1,2 @@ +-- Increment keyset counter by 1 where counter > 0 +UPDATE keyset SET counter = counter + 1 WHERE counter > 0; diff --git a/crates/cdk-sql-common/src/wallet/mod.rs b/crates/cdk-sql-common/src/wallet/mod.rs index 6c7324ed6..0d84ac9de 100644 --- a/crates/cdk-sql-common/src/wallet/mod.rs +++ b/crates/cdk-sql-common/src/wallet/mod.rs @@ -857,7 +857,7 @@ ON CONFLICT(id) DO UPDATE SET } #[instrument(skip(self), fields(keyset_id = %keyset_id))] - async fn get_keyset_counter(&self, keyset_id: &Id) -> Result, Self::Err> { + async fn get_keyset_counter(&self, keyset_id: &Id) -> Result { let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; Ok(query( r#" @@ -873,7 +873,8 @@ ON CONFLICT(id) DO UPDATE SET .pluck(&*conn) .await? .map(|n| Ok::<_, Error>(column_as_number!(n))) - .transpose()?) + .transpose()? + .unwrap_or(0)) } #[instrument(skip(self))] diff --git a/crates/cdk/src/wallet/issue/issue_bolt11.rs b/crates/cdk/src/wallet/issue/issue_bolt11.rs index c83baa624..5749a73cc 100644 --- a/crates/cdk/src/wallet/issue/issue_bolt11.rs +++ b/crates/cdk/src/wallet/issue/issue_bolt11.rs @@ -234,8 +234,6 @@ impl Wallet { .get_keyset_counter(&active_keyset_id) .await?; - let count = count.map_or(0, |c| c + 1); - let premint_secrets = match &spending_conditions { Some(spending_conditions) => PreMintSecrets::with_conditions( active_keyset_id, diff --git a/crates/cdk/src/wallet/issue/issue_bolt12.rs b/crates/cdk/src/wallet/issue/issue_bolt12.rs index fe2185b74..179e2292f 100644 --- a/crates/cdk/src/wallet/issue/issue_bolt12.rs +++ b/crates/cdk/src/wallet/issue/issue_bolt12.rs @@ -112,8 +112,6 @@ impl Wallet { .get_keyset_counter(&active_keyset_id) .await?; - let count = count.map_or(0, |c| c + 1); - let amount = match amount { Some(amount) => amount, None => { diff --git a/crates/cdk/src/wallet/melt/melt_bolt11.rs b/crates/cdk/src/wallet/melt/melt_bolt11.rs index c1a684822..0cc6657e7 100644 --- a/crates/cdk/src/wallet/melt/melt_bolt11.rs +++ b/crates/cdk/src/wallet/melt/melt_bolt11.rs @@ -153,8 +153,6 @@ impl Wallet { .get_keyset_counter(&active_keyset_id) .await?; - let count = count.map_or(0, |c| c + 1); - let premint_secrets = PreMintSecrets::from_seed_blank( active_keyset_id, count, diff --git a/crates/cdk/src/wallet/swap.rs b/crates/cdk/src/wallet/swap.rs index 3d404815a..fcb84d878 100644 --- a/crates/cdk/src/wallet/swap.rs +++ b/crates/cdk/src/wallet/swap.rs @@ -248,13 +248,11 @@ impl Wallet { let derived_secret_count; - let count = self + let mut count = self .localstore .get_keyset_counter(&active_keyset_id) .await?; - let mut count = count.map_or(0, |c| c + 1); - let (mut desired_messages, change_messages) = match spending_conditions { Some(conditions) => { let change_premint_secrets = PreMintSecrets::from_seed( From 12b707ac3dc249ce49db5239d0019d94c597b5cb Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Wed, 13 Aug 2025 09:00:02 +0100 Subject: [PATCH 067/321] fix: sqlite drop melt request --- crates/cdk-sql-common/src/mint/migrations.rs | 1 + .../migrations/{ => sqlite}/20250812132015_drop_melt_request.sql | 0 2 files changed, 1 insertion(+) rename crates/cdk-sql-common/src/mint/migrations/{ => sqlite}/20250812132015_drop_melt_request.sql (100%) diff --git a/crates/cdk-sql-common/src/mint/migrations.rs b/crates/cdk-sql-common/src/mint/migrations.rs index d97ccb4ee..96ee06e45 100644 --- a/crates/cdk-sql-common/src/mint/migrations.rs +++ b/crates/cdk-sql-common/src/mint/migrations.rs @@ -23,4 +23,5 @@ pub static MIGRATIONS: &[(&str, &str, &str)] = &[ ("sqlite", "20250415093121_drop_keystore_foreign.sql", include_str!(r#"./migrations/sqlite/20250415093121_drop_keystore_foreign.sql"#)), ("sqlite", "20250626120251_rename_blind_message_y_to_b.sql", include_str!(r#"./migrations/sqlite/20250626120251_rename_blind_message_y_to_b.sql"#)), ("sqlite", "20250706101057_bolt12.sql", include_str!(r#"./migrations/sqlite/20250706101057_bolt12.sql"#)), + ("sqlite", "20250812132015_drop_melt_request.sql", include_str!(r#"./migrations/sqlite/20250812132015_drop_melt_request.sql"#)), ]; diff --git a/crates/cdk-sql-common/src/mint/migrations/20250812132015_drop_melt_request.sql b/crates/cdk-sql-common/src/mint/migrations/sqlite/20250812132015_drop_melt_request.sql similarity index 100% rename from crates/cdk-sql-common/src/mint/migrations/20250812132015_drop_melt_request.sql rename to crates/cdk-sql-common/src/mint/migrations/sqlite/20250812132015_drop_melt_request.sql From ec9108d69dc8fb5780e8de8000d33b2aedce43bd Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Wed, 13 Aug 2025 09:17:39 +0100 Subject: [PATCH 068/321] feat: bump msrv from 1.75.0 to 1.85.0 --- CHANGELOG.md | 2 ++ Cargo.toml | 2 +- crates/cashu/src/nuts/nut04.rs | 7 ++---- crates/cashu/src/nuts/nut05.rs | 7 ++---- .../cashu/src/nuts/nut18/payment_request.rs | 2 +- crates/cdk-cln/src/lib.rs | 3 +-- crates/cdk-sql-common/src/mint/mod.rs | 20 +++++++---------- crates/cdk/src/wallet/subscription/ws.rs | 22 +++++++++---------- flake.nix | 13 +---------- 9 files changed, 28 insertions(+), 50 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ed171e15e..985daf14e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -41,6 +41,8 @@ - cdk-integration-tests: Updated integration tests to use proper temp directory management ([thesimplekid]). - cdk-integration-tests: Simplified regtest shell scripts to use new binaries ([thesimplekid]). - crates/cdk-mintd: Moved mintd library functions to separate module for better organization and testability ([thesimplekid]). +- Updated MSRV to 1.85.0 ([thesimplekid]). +- dev: Simplified Nix flake configuration by removing specific dependency version constraints from MSRV shell hook ([thesimplekid]). ### Fixed - cashu: Fixed CurrencyUnit custom units preserving original case instead of being converted to uppercase ([thesimplekid]). diff --git a/Cargo.toml b/Cargo.toml index 08fc3c4a0..e58db5d3f 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -29,7 +29,7 @@ bare_urls = "warn" [workspace.package] edition = "2021" -rust-version = "1.75.0" +rust-version = "1.85.0" license = "MIT" homepage = "https://github.com/cashubtc/cdk" repository = "https://github.com/cashubtc/cdk.git" diff --git a/crates/cashu/src/nuts/nut04.rs b/crates/cashu/src/nuts/nut04.rs index 475c590cc..545cb7a39 100644 --- a/crates/cashu/src/nuts/nut04.rs +++ b/crates/cashu/src/nuts/nut04.rs @@ -331,7 +331,7 @@ mod tests { match settings.options { Some(MintMethodOptions::Bolt11 { description }) => { - assert_eq!(description, true); + assert!(description); } _ => panic!("Expected Bolt11 options with description = true"), } @@ -363,10 +363,7 @@ mod tests { match settings.options { Some(MintMethodOptions::Bolt11 { description }) => { - assert_eq!( - description, true, - "Top-level description should take precedence" - ); + assert!(description, "Top-level description should take precedence"); } _ => panic!("Expected Bolt11 options with description = true"), } diff --git a/crates/cashu/src/nuts/nut05.rs b/crates/cashu/src/nuts/nut05.rs index 34ec338ea..fd8c42951 100644 --- a/crates/cashu/src/nuts/nut05.rs +++ b/crates/cashu/src/nuts/nut05.rs @@ -405,7 +405,7 @@ mod tests { match settings.options { Some(MeltMethodOptions::Bolt11 { amountless }) => { - assert_eq!(amountless, true); + assert!(amountless); } _ => panic!("Expected Bolt11 options with amountless = true"), } @@ -437,10 +437,7 @@ mod tests { match settings.options { Some(MeltMethodOptions::Bolt11 { amountless }) => { - assert_eq!( - amountless, true, - "Top-level amountless should take precedence" - ); + assert!(amountless, "Top-level amountless should take precedence"); } _ => panic!("Expected Bolt11 options with amountless = true"), } diff --git a/crates/cashu/src/nuts/nut18/payment_request.rs b/crates/cashu/src/nuts/nut18/payment_request.rs index 8408a9527..65d90f808 100644 --- a/crates/cashu/src/nuts/nut18/payment_request.rs +++ b/crates/cashu/src/nuts/nut18/payment_request.rs @@ -404,7 +404,7 @@ mod tests { let bolt11 = Bolt11Invoice::from_str(bolt11).unwrap(); let nut10 = SpendingConditions::HTLCConditions { - data: bolt11.payment_hash().clone(), + data: *bolt11.payment_hash(), conditions: None, }; diff --git a/crates/cdk-cln/src/lib.rs b/crates/cdk-cln/src/lib.rs index a52dae615..d3c8d53c4 100644 --- a/crates/cdk-cln/src/lib.rs +++ b/crates/cdk-cln/src/lib.rs @@ -97,9 +97,8 @@ impl MintPayment for Cln { self.rpc_socket ); - let last_pay_index = self.get_last_pay_index().await?.map(|idx| { + let last_pay_index = self.get_last_pay_index().await?.inspect(|&idx| { tracing::info!("CLN: Found last payment index: {}", idx); - idx }); tracing::debug!("CLN: Connecting to CLN node..."); diff --git a/crates/cdk-sql-common/src/mint/mod.rs b/crates/cdk-sql-common/src/mint/mod.rs index 2d31f02e1..3b77c8d72 100644 --- a/crates/cdk-sql-common/src/mint/mod.rs +++ b/crates/cdk-sql-common/src/mint/mod.rs @@ -564,9 +564,8 @@ where .bind("quote_id", quote_id.as_hyphenated().to_string()) .fetch_one(&self.inner) .await - .map_err(|err| { - tracing::error!("SQLite could not get mint quote amount_paid"); - err + .inspect_err(|err| { + tracing::error!("SQLite could not get mint quote amount_paid: {}", err); })?; let current_amount_paid = if let Some(current_amount) = current_amount { @@ -593,9 +592,8 @@ where .bind("quote_id", quote_id.as_hyphenated().to_string()) .execute(&self.inner) .await - .map_err(|err| { - tracing::error!("SQLite could not update mint quote amount_paid"); - err + .inspect_err(|err| { + tracing::error!("SQLite could not update mint quote amount_paid: {}", err); })?; // Add payment_id to mint_quote_payments table @@ -638,9 +636,8 @@ where .bind("quote_id", quote_id.as_hyphenated().to_string()) .fetch_one(&self.inner) .await - .map_err(|err| { - tracing::error!("SQLite could not get mint quote amount_issued"); - err + .inspect_err(|err| { + tracing::error!("SQLite could not get mint quote amount_issued: {}", err); })?; let current_amount_issued = if let Some(current_amount) = current_amount { @@ -668,9 +665,8 @@ where .bind("quote_id", quote_id.as_hyphenated().to_string()) .execute(&self.inner) .await - .map_err(|err| { - tracing::error!("SQLite could not update mint quote amount_issued"); - err + .inspect_err(|err| { + tracing::error!("SQLite could not update mint quote amount_issued: {}", err); })?; let current_time = unix_time(); diff --git a/crates/cdk/src/wallet/subscription/ws.rs b/crates/cdk/src/wallet/subscription/ws.rs index 2b5a7d065..4eb78badc 100644 --- a/crates/cdk/src/wallet/subscription/ws.rs +++ b/crates/cdk/src/wallet/subscription/ws.rs @@ -46,19 +46,17 @@ pub async fn ws_main( mut on_drop: mpsc::Receiver, wallet: Arc, ) { - let url = mint_url + let mut url = mint_url .join_paths(&["v1", "ws"]) - .as_mut() - .map(|url| { - if url.scheme() == "https" { - url.set_scheme("wss").expect("Could not set scheme"); - } else { - url.set_scheme("ws").expect("Could not set scheme"); - } - url - }) - .expect("Could not join paths") - .to_string(); + .expect("Could not join paths"); + + if url.scheme() == "https" { + url.set_scheme("wss").expect("Could not set scheme"); + } else { + url.set_scheme("ws").expect("Could not set scheme"); + } + + let url = url.to_string(); let mut active_subscriptions = HashMap::>::new(); let mut failure_count = 0; diff --git a/flake.nix b/flake.nix index 5790c106b..d90c42f14 100644 --- a/flake.nix +++ b/flake.nix @@ -55,7 +55,7 @@ }; # MSRV stable - msrv_toolchain = pkgs.rust-bin.stable."1.75.0".default.override { + msrv_toolchain = pkgs.rust-bin.stable."1.85.0".default.override { targets = [ "wasm32-unknown-unknown" ]; # wasm }; @@ -139,17 +139,6 @@ msrv = pkgs.mkShell ({ shellHook = " ${_shellHook} - cargo update - # cargo update -p async-compression --precise 0.4.3 - cargo update -p home --precise 0.5.9 - cargo update -p zerofrom --precise 0.1.5 - cargo update -p half --precise 2.4.1 - cargo update -p base64ct --precise 1.7.3 - cargo update -p url --precise 2.5.2 - cargo update -p pest_derive --precise 2.8.0 - cargo update -p pest_generator --precise 2.8.0 - cargo update -p pest_meta --precise 2.8.0 - cargo update -p pest --precise 2.8.0 "; buildInputs = buildInputs ++ [ msrv_toolchain ]; inherit nativeBuildInputs; From 64f7b0785569425aca174531f5387a44089267ef Mon Sep 17 00:00:00 2001 From: C Date: Wed, 13 Aug 2025 08:25:59 -0300 Subject: [PATCH 069/321] Do not perform external calls during a database transaction. (#954) The codebase was used to correctly perform signatory calls during a database transaction, as the signatory was previously exclusively in process. However, a few months ago, it was changed to be a trait that can be either local or remote. Making external calls to services, adding latency, during an ongoing database transaction is a bad idea because it will lock the rows until the service call is finalized, which is unpredictable. The issue is even worse in our pipeline where the SQLite storage driver is used with the ":memory:" path, which forces the Database pool to have a size of 1. Since our tests run in parallel, they would randomly fail. This issue was failing in the CI, but the error was not making the pipeline fail. This bug was fixed as well. --- crates/cashu/src/nuts/nut04.rs | 7 ++-- crates/cashu/src/nuts/nut05.rs | 7 ++-- .../cashu/src/nuts/nut18/payment_request.rs | 2 +- crates/cdk-integration-tests/src/lib.rs | 2 +- .../tests/fake_wallet.rs | 1 + .../tests/integration_tests_pure.rs | 3 +- crates/cdk-sql-common/src/pool.rs | 8 +++++ crates/cdk/src/mint/issue/mod.rs | 13 ++++--- crates/cdk/src/mint/melt.rs | 35 +++++++++++++------ crates/cdk/src/mint/mod.rs | 23 ++++++------ crates/cdk/src/mint/swap.rs | 28 ++++++++++----- crates/cdk/src/mint/verification.rs | 12 ++----- justfile | 18 ++++++++++ 13 files changed, 99 insertions(+), 60 deletions(-) diff --git a/crates/cashu/src/nuts/nut04.rs b/crates/cashu/src/nuts/nut04.rs index 475c590cc..545cb7a39 100644 --- a/crates/cashu/src/nuts/nut04.rs +++ b/crates/cashu/src/nuts/nut04.rs @@ -331,7 +331,7 @@ mod tests { match settings.options { Some(MintMethodOptions::Bolt11 { description }) => { - assert_eq!(description, true); + assert!(description); } _ => panic!("Expected Bolt11 options with description = true"), } @@ -363,10 +363,7 @@ mod tests { match settings.options { Some(MintMethodOptions::Bolt11 { description }) => { - assert_eq!( - description, true, - "Top-level description should take precedence" - ); + assert!(description, "Top-level description should take precedence"); } _ => panic!("Expected Bolt11 options with description = true"), } diff --git a/crates/cashu/src/nuts/nut05.rs b/crates/cashu/src/nuts/nut05.rs index 34ec338ea..fd8c42951 100644 --- a/crates/cashu/src/nuts/nut05.rs +++ b/crates/cashu/src/nuts/nut05.rs @@ -405,7 +405,7 @@ mod tests { match settings.options { Some(MeltMethodOptions::Bolt11 { amountless }) => { - assert_eq!(amountless, true); + assert!(amountless); } _ => panic!("Expected Bolt11 options with amountless = true"), } @@ -437,10 +437,7 @@ mod tests { match settings.options { Some(MeltMethodOptions::Bolt11 { amountless }) => { - assert_eq!( - amountless, true, - "Top-level amountless should take precedence" - ); + assert!(amountless, "Top-level amountless should take precedence"); } _ => panic!("Expected Bolt11 options with amountless = true"), } diff --git a/crates/cashu/src/nuts/nut18/payment_request.rs b/crates/cashu/src/nuts/nut18/payment_request.rs index 8408a9527..65d90f808 100644 --- a/crates/cashu/src/nuts/nut18/payment_request.rs +++ b/crates/cashu/src/nuts/nut18/payment_request.rs @@ -404,7 +404,7 @@ mod tests { let bolt11 = Bolt11Invoice::from_str(bolt11).unwrap(); let nut10 = SpendingConditions::HTLCConditions { - data: bolt11.payment_hash().clone(), + data: *bolt11.payment_hash(), conditions: None, }; diff --git a/crates/cdk-integration-tests/src/lib.rs b/crates/cdk-integration-tests/src/lib.rs index 41ccc0d75..0643cae62 100644 --- a/crates/cdk-integration-tests/src/lib.rs +++ b/crates/cdk-integration-tests/src/lib.rs @@ -177,7 +177,7 @@ pub async fn wait_for_mint_to_be_paid( result = timeout_future => { match result { Ok(payment_result) => payment_result, - Err(_) => Err(anyhow!("Timeout waiting for mint quote to be paid")), + Err(_) => Err(anyhow!("Timeout waiting for mint quote ({}) to be paid", mint_quote_id)), } } result = periodic_task => { diff --git a/crates/cdk-integration-tests/tests/fake_wallet.rs b/crates/cdk-integration-tests/tests/fake_wallet.rs index f43d97b95..6770bb19e 100644 --- a/crates/cdk-integration-tests/tests/fake_wallet.rs +++ b/crates/cdk-integration-tests/tests/fake_wallet.rs @@ -1204,6 +1204,7 @@ async fn test_fake_mint_duplicate_proofs_swap() { let blinded_message = pre_mint.blinded_messages(); + let inputs = vec![proofs[0].clone()]; let outputs = vec![blinded_message[0].clone(), blinded_message[0].clone()]; let swap_request = SwapRequest::new(inputs, outputs); diff --git a/crates/cdk-integration-tests/tests/integration_tests_pure.rs b/crates/cdk-integration-tests/tests/integration_tests_pure.rs index b98cd8a15..fe22cfbf1 100644 --- a/crates/cdk-integration-tests/tests/integration_tests_pure.rs +++ b/crates/cdk-integration-tests/tests/integration_tests_pure.rs @@ -321,8 +321,7 @@ async fn test_attempt_to_swap_by_overflowing() { cdk::Error::AmountOverflow => (), cdk::Error::AmountError(_) => (), _ => { - println!("{:?}", err); - panic!("Wrong error returned in swap overflow") + panic!("Wrong error returned in swap overflow {:?}", err); } }, } diff --git a/crates/cdk-sql-common/src/pool.rs b/crates/cdk-sql-common/src/pool.rs index e8cf889c7..ebcac59f3 100644 --- a/crates/cdk-sql-common/src/pool.rs +++ b/crates/cdk-sql-common/src/pool.rs @@ -8,6 +8,8 @@ use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering}; use std::sync::{Arc, Condvar, Mutex}; use std::time::Duration; +use tokio::time::Instant; + use crate::database::DatabaseConnector; /// Pool error @@ -163,6 +165,7 @@ where timeout: Duration, ) -> Result, Error> { let mut resources = self.queue.lock().map_err(|_| Error::Poison)?; + let time = Instant::now(); loop { if let Some((stale, resource)) = resources.pop() { @@ -197,6 +200,11 @@ where .map_err(|_| Error::Poison) .and_then(|(lock, timeout_result)| { if timeout_result.timed_out() { + tracing::warn!( + "Timeout waiting for the resource (pool size: {}). Waited {} ms", + self.max_size, + time.elapsed().as_millis() + ); Err(Error::Timeout) } else { Ok(lock) diff --git a/crates/cdk/src/mint/issue/mod.rs b/crates/cdk/src/mint/issue/mod.rs index 0cf772f0e..e53baf78b 100644 --- a/crates/cdk/src/mint/issue/mod.rs +++ b/crates/cdk/src/mint/issue/mod.rs @@ -496,6 +496,12 @@ impl Mint { self.check_mint_quote_paid(&mut mint_quote).await?; + // get the blind signatures before having starting the db transaction, if there are any + // rollbacks this blind_signatures will be lost, and the signature is stateless. It is not a + // good idea to call an external service (which is really a trait, it could be anything + // anywhere) while keeping a database transaction on-going + let blind_signatures = self.blind_sign(mint_request.outputs.clone()).await?; + let mut tx = self.localstore.begin_transaction().await?; let mint_quote = tx @@ -568,13 +574,6 @@ impl Mint { let unit = unit.ok_or(Error::UnsupportedUnit).unwrap(); ensure_cdk!(unit == mint_quote.unit, Error::UnsupportedUnit); - let mut blind_signatures = Vec::with_capacity(mint_request.outputs.len()); - - for blinded_message in mint_request.outputs.iter() { - let blind_signature = self.blind_sign(blinded_message.clone()).await?; - blind_signatures.push(blind_signature); - } - tx.add_blind_signatures( &mint_request .outputs diff --git a/crates/cdk/src/mint/melt.rs b/crates/cdk/src/mint/melt.rs index 09edc0447..9f14c8388 100644 --- a/crates/cdk/src/mint/melt.rs +++ b/crates/cdk/src/mint/melt.rs @@ -448,6 +448,7 @@ impl Mint { pub async fn verify_melt_request( &self, tx: &mut Box + Send + Sync + '_>, + input_verification: Verification, melt_request: &MeltRequest, ) -> Result<(ProofWriter, MeltQuote), Error> { let (state, quote) = tx @@ -467,7 +468,7 @@ impl Mint { let Verification { amount: input_amount, unit: input_unit, - } = self.verify_inputs(melt_request.inputs()).await?; + } = input_verification; ensure_cdk!(input_unit.is_some(), Error::UnsupportedUnit); @@ -545,10 +546,12 @@ impl Mint { } } + let verification = self.verify_inputs(melt_request.inputs()).await?; + let mut tx = self.localstore.begin_transaction().await?; let (proof_writer, quote) = self - .verify_melt_request(&mut tx, melt_request) + .verify_melt_request(&mut tx, verification, melt_request) .await .map_err(|err| { tracing::debug!("Error attempting to verify melt quote: {}", err); @@ -785,7 +788,6 @@ impl Mint { let change_target = melt_request.inputs_amount()? - total_spent - fee; let mut amounts = change_target.split(); - let mut change_sigs = Vec::with_capacity(amounts.len()); if outputs.len().lt(&amounts.len()) { tracing::debug!( @@ -800,15 +802,20 @@ impl Mint { amounts.sort_by(|a, b| b.cmp(a)); } - let mut outputs = outputs; + let mut blinded_messages = vec![]; - for (amount, blinded_message) in amounts.iter().zip(&mut outputs) { + for (amount, mut blinded_message) in amounts.iter().zip(outputs.clone()) { blinded_message.amount = *amount; - - let blinded_signature = self.blind_sign(blinded_message.clone()).await?; - change_sigs.push(blinded_signature) + blinded_messages.push(blinded_message); } + // commit db transaction before calling the signatory + tx.commit().await?; + + let change_sigs = self.blind_sign(blinded_messages).await?; + + let mut tx = self.localstore.begin_transaction().await?; + tx.add_blind_signatures( &outputs[0..change_sigs.len()] .iter() @@ -820,7 +827,16 @@ impl Mint { .await?; change = Some(change_sigs); + + proof_writer.commit(); + tx.commit().await?; + } else { + proof_writer.commit(); + tx.commit().await?; } + } else { + proof_writer.commit(); + tx.commit().await?; } self.pubsub_manager.melt_quote_status( @@ -830,9 +846,6 @@ impl Mint { MeltQuoteState::Paid, ); - proof_writer.commit(); - tx.commit().await?; - Ok(MeltQuoteBolt11Response { amount: quote.amount, paid: Some(true), diff --git a/crates/cdk/src/mint/mod.rs b/crates/cdk/src/mint/mod.rs index 0221ba82f..2fcf8fc3a 100644 --- a/crates/cdk/src/mint/mod.rs +++ b/crates/cdk/src/mint/mod.rs @@ -201,7 +201,7 @@ impl Mint { /// - Invoice payment monitoring across all configured payment processors /// /// Future services may include: - /// - Quote cleanup and expiration management + /// - Quote cleanup and expiration management /// - Periodic database maintenance /// - Health check monitoring /// - Metrics collection @@ -475,6 +475,7 @@ impl Mint { match result { Ok(mut stream) => { while let Some(request_lookup_id) = stream.next().await { + tracing::debug!("Received payment {:?}", request_lookup_id); if let Err(e) = Self::handle_payment_notification( &localstore, &pubsub_manager, @@ -516,6 +517,11 @@ impl Mint { .get_mint_quote_by_request_lookup_id(&wait_payment_response.payment_identifier) .await { + tracing::debug!( + "Received payment {} for quote-id {}", + wait_payment_response.payment_identifier, + mint_quote.id + ); Self::handle_mint_quote_payment( &mut tx, &mint_quote, @@ -525,7 +531,7 @@ impl Mint { .await?; } else { tracing::warn!( - "Could not get request for request lookup id {:?}.", + "Could not get request for request lookup id {:?}", wait_payment_response.payment_identifier ); } @@ -635,13 +641,9 @@ impl Mint { #[tracing::instrument(skip_all)] pub async fn blind_sign( &self, - blinded_message: BlindedMessage, - ) -> Result { - self.signatory - .blind_sign(vec![blinded_message]) - .await? - .pop() - .ok_or(Error::Internal) + blinded_messages: Vec, + ) -> Result, Error> { + self.signatory.blind_sign(blinded_messages).await } /// Verify [`Proof`] meets conditions and is signed @@ -699,7 +701,6 @@ impl Mint { return Err(Error::Internal); } }; - tracing::error!("internal stuff"); // Mint quote has already been settled, proofs should not be burned or held. if mint_quote.state() == MintQuoteState::Issued @@ -716,7 +717,7 @@ impl Mint { if let Some(amount) = mint_quote.amount { if amount > inputs_amount_quote_unit { tracing::debug!( - "Not enough inuts provided: {} needed {}", + "Not enough inputs provided: {} needed {}", inputs_amount_quote_unit, amount ); diff --git a/crates/cdk/src/mint/swap.rs b/crates/cdk/src/mint/swap.rs index 0701fbbae..670fa0791 100644 --- a/crates/cdk/src/mint/swap.rs +++ b/crates/cdk/src/mint/swap.rs @@ -12,10 +12,29 @@ impl Mint { &self, swap_request: SwapRequest, ) -> Result { + // Do the external call before beginning the db transaction + // Check any overflow before talking to the signatory + swap_request.input_amount()?; + swap_request.output_amount()?; + + let promises = self.blind_sign(swap_request.outputs().to_owned()).await?; + let input_verification = + self.verify_inputs(swap_request.inputs()) + .await + .map_err(|err| { + tracing::debug!("Input verification failed: {:?}", err); + err + })?; + let mut tx = self.localstore.begin_transaction().await?; if let Err(err) = self - .verify_transaction_balanced(&mut tx, swap_request.inputs(), swap_request.outputs()) + .verify_transaction_balanced( + &mut tx, + input_verification, + swap_request.inputs(), + swap_request.outputs(), + ) .await { tracing::debug!("Attempt to swap unbalanced transaction, aborting: {err}"); @@ -30,13 +49,6 @@ impl Mint { .add_proofs(&mut tx, swap_request.inputs()) .await?; - let mut promises = Vec::with_capacity(swap_request.outputs().len()); - - for blinded_message in swap_request.outputs() { - let blinded_signature = self.blind_sign(blinded_message.clone()).await?; - promises.push(blinded_signature); - } - proof_writer .update_proofs_states(&mut tx, &input_ys, State::Spent) .await?; diff --git a/crates/cdk/src/mint/verification.rs b/crates/cdk/src/mint/verification.rs index 1a4c024e1..5534a7d8f 100644 --- a/crates/cdk/src/mint/verification.rs +++ b/crates/cdk/src/mint/verification.rs @@ -58,10 +58,7 @@ impl Mint { /// /// Checks that the outputs are all of the same unit and the keyset is active #[instrument(skip_all)] - pub async fn verify_outputs_keyset( - &self, - outputs: &[BlindedMessage], - ) -> Result { + pub fn verify_outputs_keyset(&self, outputs: &[BlindedMessage]) -> Result { let mut keyset_units = HashSet::new(); let output_keyset_ids: HashSet = outputs.iter().map(|p| p.keyset_id).collect(); @@ -189,7 +186,7 @@ impl Mint { Mint::check_outputs_unique(outputs)?; self.check_output_already_signed(tx, outputs).await?; - let unit = self.verify_outputs_keyset(outputs).await?; + let unit = self.verify_outputs_keyset(outputs)?; let amount = Amount::try_sum(outputs.iter().map(|o| o.amount).collect::>())?; @@ -221,6 +218,7 @@ impl Mint { pub async fn verify_transaction_balanced( &self, tx: &mut Box + Send + Sync + '_>, + input_verification: Verification, inputs: &Proofs, outputs: &[BlindedMessage], ) -> Result<(), Error> { @@ -228,10 +226,6 @@ impl Mint { tracing::debug!("Output verification failed: {:?}", err); err })?; - let input_verification = self.verify_inputs(inputs).await.map_err(|err| { - tracing::debug!("Input verification failed: {:?}", err); - err - })?; if output_verification.unit != input_verification.unit { tracing::debug!( diff --git a/justfile b/justfile index 003b9fedb..8e5ab9665 100644 --- a/justfile +++ b/justfile @@ -79,8 +79,19 @@ test-all db="memory": #!/usr/bin/env bash just test {{db}} ./misc/itests.sh "{{db}}" + status=$? + if [ $status -ne 0 ]; then + echo "Failed test with status {$status}" + exit $status + fi ./misc/fake_itests.sh "{{db}}" external_signatory + status=$? + if [ $status -ne 0 ]; then + echo "Failed test with status {$status}" + exit $status + fi ./misc/fake_itests.sh "{{db}}" + exit $? test-nutshell: #!/usr/bin/env bash @@ -150,12 +161,19 @@ goose-changelog-commits *COMMITS="5": itest db: #!/usr/bin/env bash ./misc/itests.sh "{{db}}" + exit $? fake-mint-itest db: #!/usr/bin/env bash ./misc/fake_itests.sh "{{db}}" external_signatory + status=$? + if [ $status -ne 0 ]; then + echo "Failed test with status {$status}" + exit $status + fi ./misc/fake_itests.sh "{{db}}" + exit $? itest-payment-processor ln: From 47c5bb7465e61318dbb6fa139405086eea9e9258 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Wed, 13 Aug 2025 13:55:50 +0100 Subject: [PATCH 070/321] fix: fake mint multiple units --- crates/cdk-fake-wallet/src/lib.rs | 14 ++++++++++---- crates/cdk-integration-tests/src/init_auth_mint.rs | 8 +++++++- .../cdk-integration-tests/src/init_pure_tests.rs | 1 + crates/cdk-integration-tests/tests/fake_wallet.rs | 3 +++ crates/cdk-integration-tests/tests/mint.rs | 8 +++++++- crates/cdk-mintd/src/lib.rs | 2 +- crates/cdk-mintd/src/setup.rs | 3 ++- .../src/bin/payment_processor.rs | 9 +++++++-- 8 files changed, 38 insertions(+), 10 deletions(-) diff --git a/crates/cdk-fake-wallet/src/lib.rs b/crates/cdk-fake-wallet/src/lib.rs index eeebfa55a..eeba7bcb2 100644 --- a/crates/cdk-fake-wallet/src/lib.rs +++ b/crates/cdk-fake-wallet/src/lib.rs @@ -54,6 +54,7 @@ pub struct FakeWallet { wait_invoice_cancel_token: CancellationToken, wait_invoice_is_active: Arc, incoming_payments: Arc>>>, + unit: CurrencyUnit, } impl FakeWallet { @@ -63,6 +64,7 @@ impl FakeWallet { payment_states: HashMap, fail_payment_check: HashSet, payment_delay: u64, + unit: CurrencyUnit, ) -> Self { let (sender, receiver) = tokio::sync::mpsc::channel(8); @@ -76,6 +78,7 @@ impl FakeWallet { wait_invoice_cancel_token: CancellationToken::new(), wait_invoice_is_active: Arc::new(AtomicBool::new(false)), incoming_payments: Arc::new(RwLock::new(HashMap::new())), + unit, } } } @@ -112,7 +115,7 @@ impl MintPayment for FakeWallet { async fn get_settings(&self) -> Result { Ok(serde_json::to_value(Bolt11Settings { mpp: true, - unit: CurrencyUnit::Msat, + unit: self.unit.clone(), invoice_description: true, amountless: false, bolt12: false, @@ -141,12 +144,13 @@ impl MintPayment for FakeWallet { .take() .ok_or(Error::NoReceiver) .unwrap(); + let unit = self.unit.clone(); let receiver_stream = ReceiverStream::new(receiver); Ok(Box::pin(receiver_stream.map( - |(request_lookup_id, payment_amount)| WaitPaymentResponse { + move |(request_lookup_id, payment_amount)| WaitPaymentResponse { payment_identifier: request_lookup_id.clone(), payment_amount, - unit: CurrencyUnit::Sat, + unit: unit.clone(), payment_id: request_lookup_id.to_string(), }, ))) @@ -389,6 +393,8 @@ impl MintPayment for FakeWallet { let incoming_payment = self.incoming_payments.clone(); + let unit = self.unit.clone(); + tokio::spawn(async move { // Wait for the random delay to elapse time::sleep(duration).await; @@ -396,7 +402,7 @@ impl MintPayment for FakeWallet { let response = WaitPaymentResponse { payment_identifier: payment_hash_clone.clone(), payment_amount: final_amount, - unit: CurrencyUnit::Sat, + unit, payment_id: payment_hash_clone.to_string(), }; let mut incoming = incoming_payment.write().await; diff --git a/crates/cdk-integration-tests/src/init_auth_mint.rs b/crates/cdk-integration-tests/src/init_auth_mint.rs index dc6c50719..bde2d0e13 100644 --- a/crates/cdk-integration-tests/src/init_auth_mint.rs +++ b/crates/cdk-integration-tests/src/init_auth_mint.rs @@ -29,7 +29,13 @@ where percent_fee_reserve: 1.0, }; - let fake_wallet = FakeWallet::new(fee_reserve, HashMap::default(), HashSet::default(), 0); + let fake_wallet = FakeWallet::new( + fee_reserve, + HashMap::default(), + HashSet::default(), + 0, + CurrencyUnit::Sat, + ); let mut mint_builder = MintBuilder::new(Arc::new(database)); diff --git a/crates/cdk-integration-tests/src/init_pure_tests.rs b/crates/cdk-integration-tests/src/init_pure_tests.rs index 05c9d2ead..73417233f 100644 --- a/crates/cdk-integration-tests/src/init_pure_tests.rs +++ b/crates/cdk-integration-tests/src/init_pure_tests.rs @@ -253,6 +253,7 @@ pub async fn create_and_start_test_mint() -> Result { HashMap::default(), HashSet::default(), 0, + CurrencyUnit::Sat, ); mint_builder diff --git a/crates/cdk-integration-tests/tests/fake_wallet.rs b/crates/cdk-integration-tests/tests/fake_wallet.rs index 6770bb19e..c4066c5b3 100644 --- a/crates/cdk-integration-tests/tests/fake_wallet.rs +++ b/crates/cdk-integration-tests/tests/fake_wallet.rs @@ -684,6 +684,8 @@ async fn test_fake_mint_multiple_unit_swap() { ) .expect("failed to create new wallet"); + wallet.refresh_keysets().await.unwrap(); + let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60) @@ -703,6 +705,7 @@ async fn test_fake_mint_multiple_unit_swap() { None, ) .expect("failed to create usd wallet"); + wallet_usd.refresh_keysets().await.unwrap(); let mint_quote = wallet_usd.mint_quote(100.into(), None).await.unwrap(); diff --git a/crates/cdk-integration-tests/tests/mint.rs b/crates/cdk-integration-tests/tests/mint.rs index 3dd881ce8..b1c3eca8e 100644 --- a/crates/cdk-integration-tests/tests/mint.rs +++ b/crates/cdk-integration-tests/tests/mint.rs @@ -34,7 +34,13 @@ async fn test_correct_keyset() { let database = memory::empty().await.expect("valid db instance"); - let fake_wallet = FakeWallet::new(fee_reserve, HashMap::default(), HashSet::default(), 0); + let fake_wallet = FakeWallet::new( + fee_reserve, + HashMap::default(), + HashSet::default(), + 0, + CurrencyUnit::Sat, + ); let localstore = Arc::new(database); let mut mint_builder = MintBuilder::new(localstore.clone()); diff --git a/crates/cdk-mintd/src/lib.rs b/crates/cdk-mintd/src/lib.rs index 89121e778..f83a26eae 100644 --- a/crates/cdk-mintd/src/lib.rs +++ b/crates/cdk-mintd/src/lib.rs @@ -322,7 +322,7 @@ async fn configure_lightning_backend( for unit in fake_wallet.clone().supported_units { let fake = fake_wallet - .setup(ln_routers, settings, CurrencyUnit::Sat) + .setup(ln_routers, settings, unit.clone()) .await?; mint_builder = configure_backend_for_unit( diff --git a/crates/cdk-mintd/src/setup.rs b/crates/cdk-mintd/src/setup.rs index 6b5376bb5..0bbd950ec 100644 --- a/crates/cdk-mintd/src/setup.rs +++ b/crates/cdk-mintd/src/setup.rs @@ -161,7 +161,7 @@ impl LnBackendSetup for config::FakeWallet { &self, _router: &mut Vec, _settings: &Settings, - _unit: CurrencyUnit, + unit: CurrencyUnit, ) -> anyhow::Result { let fee_reserve = FeeReserve { min_fee_reserve: self.reserve_fee_min, @@ -177,6 +177,7 @@ impl LnBackendSetup for config::FakeWallet { HashMap::default(), HashSet::default(), delay_time, + unit, ); Ok(fake_wallet) diff --git a/crates/cdk-payment-processor/src/bin/payment_processor.rs b/crates/cdk-payment-processor/src/bin/payment_processor.rs index 030ef0bb3..1381198c9 100644 --- a/crates/cdk-payment-processor/src/bin/payment_processor.rs +++ b/crates/cdk-payment-processor/src/bin/payment_processor.rs @@ -115,8 +115,13 @@ async fn main() -> anyhow::Result<()> { percent_fee_reserve: 0.0, }; - let fake_wallet = - FakeWallet::new(fee_reserve, HashMap::default(), HashSet::default(), 0); + let fake_wallet = FakeWallet::new( + fee_reserve, + HashMap::default(), + HashSet::default(), + 0, + cashu::CurrencyUnit::Sat, + ); Arc::new(fake_wallet) } From 8c66114b2751d7557c139f99ca088999ef1b3413 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Wed, 13 Aug 2025 15:05:21 +0100 Subject: [PATCH 071/321] chore: free disk space on ci --- .github/workflows/ci.yml | 46 ++++++++++++++++++++++++++++++--- misc/mintd_payment_processor.sh | 2 ++ 2 files changed, 45 insertions(+), 3 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d0a08f168..9dd6fd7f4 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -41,7 +41,7 @@ jobs: name: "Run examples" runs-on: ubuntu-latest timeout-minutes: 30 - needs: [pre-commit-checks, clippy] + needs: pre-commit-checks strategy: matrix: build-args: @@ -172,6 +172,16 @@ jobs: steps: - name: checkout uses: actions/checkout@v4 + - name: Free Disk Space (Ubuntu) + uses: jlumbroso/free-disk-space@main + with: + tool-cache: false + android: true + dotnet: true + haskell: true + large-packages: true + docker-images: true + swap-storage: true - name: Install Nix uses: DeterminateSystems/nix-installer-action@v17 - name: Nix Cache @@ -201,6 +211,16 @@ jobs: steps: - name: checkout uses: actions/checkout@v4 + - name: Free Disk Space (Ubuntu) + uses: jlumbroso/free-disk-space@main + with: + tool-cache: true + android: true + dotnet: true + haskell: true + large-packages: true + docker-images: true + swap-storage: true - name: Install Nix uses: DeterminateSystems/nix-installer-action@v17 - name: Nix Cache @@ -230,6 +250,16 @@ jobs: steps: - name: checkout uses: actions/checkout@v4 + - name: Free Disk Space (Ubuntu) + uses: jlumbroso/free-disk-space@main + with: + tool-cache: true + android: true + dotnet: true + haskell: true + large-packages: true + docker-images: true + swap-storage: true - name: Install Nix uses: DeterminateSystems/nix-installer-action@v17 - name: Nix Cache @@ -260,6 +290,16 @@ jobs: steps: - name: checkout uses: actions/checkout@v4 + - name: Free Disk Space (Ubuntu) + uses: jlumbroso/free-disk-space@main + with: + tool-cache: true + android: true + dotnet: true + haskell: true + large-packages: true + docker-images: true + swap-storage: true - name: Install Nix uses: DeterminateSystems/nix-installer-action@v17 - name: Nix Cache @@ -275,7 +315,7 @@ jobs: name: "MSRV build" runs-on: ubuntu-latest timeout-minutes: 30 - needs: [pre-commit-checks, clippy, pure-itest] + needs: [pre-commit-checks, clippy] strategy: matrix: build-args: @@ -316,7 +356,7 @@ jobs: name: Check WASM runs-on: ubuntu-latest timeout-minutes: 30 - needs: [pre-commit-checks, clippy, pure-itest] + needs: [pre-commit-checks, clippy] strategy: matrix: rust: diff --git a/misc/mintd_payment_processor.sh b/misc/mintd_payment_processor.sh index 479045946..5d8331551 100755 --- a/misc/mintd_payment_processor.sh +++ b/misc/mintd_payment_processor.sh @@ -123,6 +123,8 @@ export CDK_PAYMENT_PROCESSOR_LISTEN_PORT="8090"; echo "$CDK_PAYMENT_PROCESSOR_CLN_RPC_PATH" +cargo b --bin cdk-payment-processor + cargo run --bin cdk-payment-processor & CDK_PAYMENT_PROCESSOR_PID=$! From 31459fcb953469fabc5d766b289b9f9b81eeab6e Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Wed, 13 Aug 2025 19:56:30 +0100 Subject: [PATCH 072/321] fix: nutshell itests --- justfile | 47 +++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 41 insertions(+), 6 deletions(-) diff --git a/justfile b/justfile index 8e5ab9665..93cbedb3b 100644 --- a/justfile +++ b/justfile @@ -95,8 +95,23 @@ test-all db="memory": test-nutshell: #!/usr/bin/env bash + set -euo pipefail + + # Function to cleanup docker containers + cleanup() { + echo "Cleaning up docker containers..." + docker stop nutshell 2>/dev/null || true + docker rm nutshell 2>/dev/null || true + unset CDK_ITESTS_DIR + } + + # Trap to ensure cleanup happens on exit (success or failure) + trap cleanup EXIT + docker run -d -p 3338:3338 --name nutshell -e MINT_LIGHTNING_BACKEND=FakeWallet -e MINT_LISTEN_HOST=0.0.0.0 -e MINT_LISTEN_PORT=3338 -e MINT_PRIVATE_KEY=TEST_PRIVATE_KEY -e MINT_INPUT_FEE_PPK=100 cashubtc/nutshell:latest poetry run mint + export CDK_ITESTS_DIR=$(mktemp -d) + # Wait for the Nutshell service to be ready echo "Waiting for Nutshell to start..." max_attempts=30 @@ -105,8 +120,6 @@ test-nutshell: attempt=$((attempt+1)) if [ $attempt -ge $max_attempts ]; then echo "Nutshell failed to start after $max_attempts attempts" - docker stop nutshell - docker rm nutshell exit 1 fi echo "Waiting for Nutshell to start (attempt $attempt/$max_attempts)..." @@ -116,12 +129,34 @@ test-nutshell: export CDK_TEST_MINT_URL=http://127.0.0.1:3338 export LN_BACKEND=FAKEWALLET - cargo test -p cdk-integration-tests --test happy_path_mint_wallet - cargo test -p cdk-integration-tests --test test_fees + + # Track test results + test_exit_code=0 + + # Run first test and capture exit code + echo "Running happy_path_mint_wallet test..." + if ! cargo test -p cdk-integration-tests --test happy_path_mint_wallet; then + echo "ERROR: happy_path_mint_wallet test failed" + test_exit_code=1 + fi + + # Run second test and capture exit code + echo "Running test_fees test..." + if ! cargo test -p cdk-integration-tests --test test_fees; then + echo "ERROR: test_fees test failed" + test_exit_code=1 + fi + unset CDK_TEST_MINT_URL unset LN_BACKEND - docker stop nutshell - docker rm nutshell + + # Exit with error code if any test failed + if [ $test_exit_code -ne 0 ]; then + echo "One or more tests failed" + exit $test_exit_code + fi + + echo "All tests passed successfully" # run `cargo clippy` on everything From 325afd75f7ec1aa7bc1be88e6f3b2fecb28132b6 Mon Sep 17 00:00:00 2001 From: gudnuf Date: Wed, 13 Aug 2025 19:10:20 -0700 Subject: [PATCH 073/321] fix: allow paid and issued bolt12 quotes to settle internally --- crates/cdk/src/mint/mod.rs | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/crates/cdk/src/mint/mod.rs b/crates/cdk/src/mint/mod.rs index 2fcf8fc3a..ed0752b09 100644 --- a/crates/cdk/src/mint/mod.rs +++ b/crates/cdk/src/mint/mod.rs @@ -703,8 +703,9 @@ impl Mint { }; // Mint quote has already been settled, proofs should not be burned or held. - if mint_quote.state() == MintQuoteState::Issued - || mint_quote.state() == MintQuoteState::Paid + if (mint_quote.state() == MintQuoteState::Issued + || mint_quote.state() == MintQuoteState::Paid) + && mint_quote.payment_method == PaymentMethod::Bolt11 { return Err(Error::RequestAlreadyPaid); } From 7b18e47ce508dfcfc7bc6d9c23428fb41f2f4bac Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Thu, 14 Aug 2025 18:17:08 +0100 Subject: [PATCH 074/321] Merge pull request #962 from thesimplekid/justfile_errors Reduce clippy ci and catch errors in justfile scripts --- .github/workflows/ci.yml | 41 ++++++++++++++------------------- justfile | 49 +++++++++++++++++++++++----------------- 2 files changed, 45 insertions(+), 45 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9dd6fd7f4..57e34d257 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -75,52 +75,52 @@ jobs: matrix: build-args: [ + # Core crate testing -p cashu, -p cashu --no-default-features, -p cashu --no-default-features --features wallet, -p cashu --no-default-features --features mint, - -p cashu --no-default-features --features "mint swagger", -p cashu --no-default-features --features auth, - -p cashu --no-default-features --features "mint auth", - -p cashu --no-default-features --features "wallet auth", -p cdk-common, -p cdk-common --no-default-features, -p cdk-common --no-default-features --features wallet, -p cdk-common --no-default-features --features mint, - -p cdk-common --no-default-features --features "mint swagger", - -p cdk-common --no-default-features --features "auth", - -p cdk-common --no-default-features --features "mint auth", - -p cdk-common --no-default-features --features "wallet auth", + -p cdk-common --no-default-features --features auth, -p cdk, -p cdk --no-default-features, -p cdk --no-default-features --features wallet, -p cdk --no-default-features --features mint, - -p cdk --no-default-features --features "mint swagger", -p cdk --no-default-features --features auth, - -p cdk --features auth, - -p cdk --no-default-features --features "auth mint", - -p cdk --no-default-features --features "auth wallet", + -p cdk-sql-common, + -p cdk-sql-common --no-default-features --features wallet, + -p cdk-sql-common --no-default-features --features mint, + + # Database and infrastructure crates -p cdk-redb, -p cdk-sqlite, -p cdk-sqlite --features sqlcipher, + + # HTTP/API layer - consolidated + -p cdk-axum, -p cdk-axum --no-default-features, - -p cdk-axum --no-default-features --features swagger, -p cdk-axum --no-default-features --features redis, -p cdk-axum --no-default-features --features "redis swagger", - -p cdk-axum --no-default-features --features "auth redis", - -p cdk-axum, + + # Lightning backends -p cdk-cln, -p cdk-lnd, -p cdk-lnbits, -p cdk-fake-wallet, -p cdk-payment-processor, + -p cdk-mint-rpc, + -p cdk-signatory, + + # Binaries --bin cdk-cli, --bin cdk-cli --features sqlcipher, --bin cdk-cli --features redb, - --bin cdk-cli --features "sqlcipher redb", --bin cdk-mintd, --bin cdk-mintd --features redis, - --bin cdk-mintd --features "redis swagger", --bin cdk-mintd --features sqlcipher, --bin cdk-mintd --no-default-features --features lnd, --bin cdk-mintd --no-default-features --features cln, @@ -128,14 +128,6 @@ jobs: --bin cdk-mintd --no-default-features --features fakewallet, --bin cdk-mintd --no-default-features --features grpc-processor, --bin cdk-mintd --no-default-features --features "management-rpc lnd", - --bin cdk-mintd --no-default-features --features "management-rpc cln", - --bin cdk-mintd --no-default-features --features "management-rpc lnbits", - --bin cdk-mintd --no-default-features --features "management-rpc grpc-processor", - --bin cdk-mintd --no-default-features --features "swagger lnd", - --bin cdk-mintd --no-default-features --features "swagger cln", - --bin cdk-mintd --no-default-features --features "swagger lnbits", - --bin cdk-mintd --no-default-features --features "auth lnd", - --bin cdk-mintd --no-default-features --features "auth cln", --bin cdk-mint-cli, ] steps: @@ -322,6 +314,7 @@ jobs: [ -p cashu --no-default-features --features "wallet mint", -p cdk-common --no-default-features --features "wallet mint", + -p cdk-sql-common, -p cdk, -p cdk --no-default-features --features "mint auth", -p cdk --no-default-features --features "wallet auth", diff --git a/justfile b/justfile index 93cbedb3b..f1c305f34 100644 --- a/justfile +++ b/justfile @@ -8,6 +8,7 @@ default: # Create a new SQL migration file new-migration target name: #!/usr/bin/env bash + set -euo pipefail if [ "{{target}}" != "mint" ] && [ "{{target}}" != "wallet" ]; then echo "Error: target must be either 'mint' or 'wallet'" exit 1 @@ -77,21 +78,11 @@ test-pure db="memory": build test-all db="memory": #!/usr/bin/env bash + set -euo pipefail just test {{db}} ./misc/itests.sh "{{db}}" - status=$? - if [ $status -ne 0 ]; then - echo "Failed test with status {$status}" - exit $status - fi ./misc/fake_itests.sh "{{db}}" external_signatory - status=$? - if [ $status -ne 0 ]; then - echo "Failed test with status {$status}" - exit $status - fi ./misc/fake_itests.sh "{{db}}" - exit $? test-nutshell: #!/usr/bin/env bash @@ -127,6 +118,7 @@ test-nutshell: done echo "Nutshell is ready!" + # Set environment variables and run tests export CDK_TEST_MINT_URL=http://127.0.0.1:3338 export LN_BACKEND=FAKEWALLET @@ -180,53 +172,52 @@ typos-fix: # Update changelog from staged changes using Goose AI goose-git-msg: #!/usr/bin/env bash + set -euo pipefail goose run --recipe ./misc/recipes/git-commit-message.yaml --interactive # Create git message from staged changes using Goose AI goose-changelog-staged: #!/usr/bin/env bash + set -euo pipefail goose run --recipe ./misc/recipes/changelog-update.yaml --interactive # Update changelog from recent commits using Goose AI # Usage: just goose-changelog-commits [number_of_commits] goose-changelog-commits *COMMITS="5": #!/usr/bin/env bash + set -euo pipefail COMMITS={{COMMITS}} goose run --recipe ./misc/recipes/changelog-from-commits.yaml --interactive itest db: #!/usr/bin/env bash + set -euo pipefail ./misc/itests.sh "{{db}}" - exit $? - fake-mint-itest db: #!/usr/bin/env bash + set -euo pipefail ./misc/fake_itests.sh "{{db}}" external_signatory - status=$? - if [ $status -ne 0 ]; then - echo "Failed test with status {$status}" - exit $status - fi ./misc/fake_itests.sh "{{db}}" - exit $? - itest-payment-processor ln: #!/usr/bin/env bash + set -euo pipefail ./misc/mintd_payment_processor.sh "{{ln}}" - fake-auth-mint-itest db openid_discovery: #!/usr/bin/env bash + set -euo pipefail ./misc/fake_auth_itests.sh "{{db}}" "{{openid_discovery}}" nutshell-wallet-itest: #!/usr/bin/env bash + set -euo pipefail ./misc/nutshell_wallet_itest.sh # Start interactive regtest environment (Bitcoin + 4 LN nodes + 2 CDK mints) regtest db="sqlite": #!/usr/bin/env bash + set -euo pipefail ./misc/interactive_regtest_mprocs.sh {{db}} # Lightning Network Commands (require regtest environment to be running) @@ -234,56 +225,67 @@ regtest db="sqlite": # Get CLN node 1 info ln-cln1 *ARGS: #!/usr/bin/env bash + set -euo pipefail ./misc/regtest_helper.sh ln-cln1 {{ARGS}} # Get CLN node 2 info ln-cln2 *ARGS: #!/usr/bin/env bash + set -euo pipefail ./misc/regtest_helper.sh ln-cln2 {{ARGS}} # Get LND node 1 info ln-lnd1 *ARGS: #!/usr/bin/env bash + set -euo pipefail ./misc/regtest_helper.sh ln-lnd1 {{ARGS}} # Get LND node 2 info ln-lnd2 *ARGS: #!/usr/bin/env bash + set -euo pipefail ./misc/regtest_helper.sh ln-lnd2 {{ARGS}} # Bitcoin regtest commands btc *ARGS: #!/usr/bin/env bash + set -euo pipefail ./misc/regtest_helper.sh btc {{ARGS}} # Mine blocks in regtest btc-mine blocks="10": #!/usr/bin/env bash + set -euo pipefail ./misc/regtest_helper.sh btc-mine {{blocks}} # Show mint information mint-info: #!/usr/bin/env bash + set -euo pipefail ./misc/regtest_helper.sh mint-info # Run integration tests against regtest environment mint-test: #!/usr/bin/env bash + set -euo pipefail ./misc/regtest_helper.sh mint-test # Restart mints after recompiling (useful for development) restart-mints: #!/usr/bin/env bash + set -euo pipefail ./misc/regtest_helper.sh restart-mints # Show regtest environment status regtest-status: #!/usr/bin/env bash + set -euo pipefail ./misc/regtest_helper.sh show-status # Show regtest environment logs regtest-logs: #!/usr/bin/env bash + set -euo pipefail ./misc/regtest_helper.sh show-logs run-examples: @@ -321,6 +323,7 @@ release m="": args=( "-p cashu" "-p cdk-common" + "-p cdk-sql-common" "-p cdk-sqlite" "-p cdk-redb" "-p cdk-signatory" @@ -349,6 +352,7 @@ check-docs: args=( "-p cashu" "-p cdk-common" + "-p cdk-sql-common" "-p cdk" "-p cdk-redb" "-p cdk-sqlite" @@ -358,6 +362,7 @@ check-docs: "-p cdk-lnbits" "-p cdk-fake-wallet" "-p cdk-mint-rpc" + "-p cdk-payment-processor" "-p cdk-signatory" "-p cdk-cli" "-p cdk-mintd" @@ -376,6 +381,7 @@ docs-strict: args=( "-p cashu" "-p cdk-common" + "-p cdk-sql-common" "-p cdk" "-p cdk-redb" "-p cdk-sqlite" @@ -386,6 +392,7 @@ docs-strict: "-p cdk-fake-wallet" "-p cdk-mint-rpc" "-p cdk-payment-processor" + "-p cdk-signatory" "-p cdk-cli" "-p cdk-mintd" ) From 51b26eae621828d8dc5853b2e1ce111ab28efd55 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Fri, 15 Aug 2025 11:49:38 +0100 Subject: [PATCH 075/321] chore: clippy --- crates/cdk-sql-common/src/mint/mod.rs | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/crates/cdk-sql-common/src/mint/mod.rs b/crates/cdk-sql-common/src/mint/mod.rs index 3b77c8d72..b45b8a8ca 100644 --- a/crates/cdk-sql-common/src/mint/mod.rs +++ b/crates/cdk-sql-common/src/mint/mod.rs @@ -689,8 +689,7 @@ VALUES (:quote_id, :amount, :timestamp); #[instrument(skip_all)] async fn add_mint_quote(&mut self, quote: MintQuote) -> Result<(), Self::Err> { - tracing::debug!("Adding quote with: {}", quote.payment_method.to_string()); - println!("Adding quote with: {}", quote.payment_method.to_string()); + tracing::debug!("Adding quote with: {}", quote.payment_method); query( r#" INSERT INTO mint_quote ( From 5b30ca546d44d5bfe86f07e6091c989aa4953a2e Mon Sep 17 00:00:00 2001 From: vnprc Date: Fri, 8 Aug 2025 18:59:16 -0400 Subject: [PATCH 076/321] fix: implement atomic keyset counter - remove get_keyset_counter - update increment_keyset_counter to atomically increment and return counter value - replace get+increment pattern with atomic increment everywhere --- crates/cdk-common/src/database/wallet.rs | 6 +-- crates/cdk-redb/src/wallet/mod.rs | 20 ++------ crates/cdk-sql-common/src/wallet/mod.rs | 50 ++++++++++---------- crates/cdk/src/wallet/issue/issue_bolt11.rs | 52 +++++++++++---------- crates/cdk/src/wallet/issue/issue_bolt12.rs | 46 ++++++++++-------- crates/cdk/src/wallet/melt/melt_bolt11.rs | 42 ++++++++++------- crates/cdk/src/wallet/swap.rs | 44 +++++++++++++---- 7 files changed, 149 insertions(+), 111 deletions(-) diff --git a/crates/cdk-common/src/database/wallet.rs b/crates/cdk-common/src/database/wallet.rs index 2e53139f4..0619ad386 100644 --- a/crates/cdk-common/src/database/wallet.rs +++ b/crates/cdk-common/src/database/wallet.rs @@ -99,10 +99,8 @@ pub trait Database: Debug { /// Update proofs state in storage async fn update_proofs_state(&self, ys: Vec, state: State) -> Result<(), Self::Err>; - /// Increment Keyset counter - async fn increment_keyset_counter(&self, keyset_id: &Id, count: u32) -> Result<(), Self::Err>; - /// Get current Keyset counter - async fn get_keyset_counter(&self, keyset_id: &Id) -> Result; + /// Atomically increment Keyset counter and return new value + async fn increment_keyset_counter(&self, keyset_id: &Id, count: u32) -> Result; /// Add transaction to storage async fn add_transaction(&self, transaction: Transaction) -> Result<(), Self::Err>; diff --git a/crates/cdk-redb/src/wallet/mod.rs b/crates/cdk-redb/src/wallet/mod.rs index fba2107ed..711f3a79e 100644 --- a/crates/cdk-redb/src/wallet/mod.rs +++ b/crates/cdk-redb/src/wallet/mod.rs @@ -760,10 +760,11 @@ impl WalletDatabase for WalletRedbDatabase { } #[instrument(skip(self), fields(keyset_id = %keyset_id))] - async fn increment_keyset_counter(&self, keyset_id: &Id, count: u32) -> Result<(), Self::Err> { + async fn increment_keyset_counter(&self, keyset_id: &Id, count: u32) -> Result { let write_txn = self.db.begin_write().map_err(Error::from)?; let current_counter; + let new_counter; { let table = write_txn.open_table(KEYSET_COUNTER).map_err(Error::from)?; let counter = table @@ -774,11 +775,12 @@ impl WalletDatabase for WalletRedbDatabase { Some(c) => c.value(), None => 0, }; + + new_counter = current_counter + count; } { let mut table = write_txn.open_table(KEYSET_COUNTER).map_err(Error::from)?; - let new_counter = current_counter + count; table .insert(keyset_id.to_string().as_str(), new_counter) @@ -786,19 +788,7 @@ impl WalletDatabase for WalletRedbDatabase { } write_txn.commit().map_err(Error::from)?; - Ok(()) - } - - #[instrument(skip(self), fields(keyset_id = %keyset_id))] - async fn get_keyset_counter(&self, keyset_id: &Id) -> Result { - let read_txn = self.db.begin_read().map_err(Error::from)?; - let table = read_txn.open_table(KEYSET_COUNTER).map_err(Error::from)?; - - let counter = table - .get(keyset_id.to_string().as_str()) - .map_err(Error::from)?; - - Ok(counter.map_or(0, |c| c.value())) + Ok(new_counter) } #[instrument(skip(self))] diff --git a/crates/cdk-sql-common/src/wallet/mod.rs b/crates/cdk-sql-common/src/wallet/mod.rs index 0d84ac9de..a0008275e 100644 --- a/crates/cdk-sql-common/src/wallet/mod.rs +++ b/crates/cdk-sql-common/src/wallet/mod.rs @@ -839,42 +839,44 @@ ON CONFLICT(id) DO UPDATE SET } #[instrument(skip(self), fields(keyset_id = %keyset_id))] - async fn increment_keyset_counter(&self, keyset_id: &Id, count: u32) -> Result<(), Self::Err> { + async fn increment_keyset_counter(&self, keyset_id: &Id, count: u32) -> Result { let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; - query( + let tx = ConnectionWithTransaction::new(conn).await?; + + // Lock the row and get current counter + let current_counter = query( r#" - UPDATE keyset - SET counter=counter+:count + SELECT counter + FROM keyset WHERE id=:id + FOR UPDATE "#, )? - .bind("count", count) .bind("id", keyset_id.to_string()) - .execute(&*conn) - .await?; + .pluck(&tx) + .await? + .map(|n| Ok::<_, Error>(column_as_number!(n))) + .transpose()? + .unwrap_or(0); - Ok(()) - } + let new_counter = current_counter + count; - #[instrument(skip(self), fields(keyset_id = %keyset_id))] - async fn get_keyset_counter(&self, keyset_id: &Id) -> Result { - let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; - Ok(query( + // Update with the new counter value + query( r#" - SELECT - counter - FROM - keyset - WHERE - id=:id + UPDATE keyset + SET counter=:new_counter + WHERE id=:id "#, )? + .bind("new_counter", new_counter) .bind("id", keyset_id.to_string()) - .pluck(&*conn) - .await? - .map(|n| Ok::<_, Error>(column_as_number!(n))) - .transpose()? - .unwrap_or(0)) + .execute(&tx) + .await?; + + tx.commit().await?; + + Ok(new_counter) } #[instrument(skip(self))] diff --git a/crates/cdk/src/wallet/issue/issue_bolt11.rs b/crates/cdk/src/wallet/issue/issue_bolt11.rs index 5749a73cc..bf613ae55 100644 --- a/crates/cdk/src/wallet/issue/issue_bolt11.rs +++ b/crates/cdk/src/wallet/issue/issue_bolt11.rs @@ -229,11 +229,6 @@ impl Wallet { let active_keyset_id = self.fetch_active_keyset().await?.id; - let count = self - .localstore - .get_keyset_counter(&active_keyset_id) - .await?; - let premint_secrets = match &spending_conditions { Some(spending_conditions) => PreMintSecrets::with_conditions( active_keyset_id, @@ -241,13 +236,33 @@ impl Wallet { &amount_split_target, spending_conditions, )?, - None => PreMintSecrets::from_seed( - active_keyset_id, - count, - &self.seed, - amount_mintable, - &amount_split_target, - )?, + None => { + // Calculate how many secrets we'll need + let amount_split = amount_mintable.split_targeted(&amount_split_target)?; + let num_secrets = amount_split.len() as u32; + + tracing::debug!( + "Incrementing keyset {} counter by {}", + active_keyset_id, + num_secrets + ); + + // Atomically get the counter range we need + let new_counter = self + .localstore + .increment_keyset_counter(&active_keyset_id, num_secrets) + .await?; + + let count = new_counter - num_secrets; + + PreMintSecrets::from_seed( + active_keyset_id, + count, + &self.seed, + amount_mintable, + &amount_split_target, + )? + } }; let mut request = MintRequest { @@ -286,19 +301,6 @@ impl Wallet { // Remove filled quote from store self.localstore.remove_mint_quote("e_info.id).await?; - if spending_conditions.is_none() { - tracing::debug!( - "Incrementing keyset {} counter by {}", - active_keyset_id, - proofs.len() - ); - - // Update counter for keyset - self.localstore - .increment_keyset_counter(&active_keyset_id, proofs.len() as u32) - .await?; - } - let proof_infos = proofs .iter() .map(|proof| { diff --git a/crates/cdk/src/wallet/issue/issue_bolt12.rs b/crates/cdk/src/wallet/issue/issue_bolt12.rs index 179e2292f..6e788e3e3 100644 --- a/crates/cdk/src/wallet/issue/issue_bolt12.rs +++ b/crates/cdk/src/wallet/issue/issue_bolt12.rs @@ -107,11 +107,6 @@ impl Wallet { let active_keyset_id = self.fetch_active_keyset().await?.id; - let count = self - .localstore - .get_keyset_counter(&active_keyset_id) - .await?; - let amount = match amount { Some(amount) => amount, None => { @@ -135,13 +130,33 @@ impl Wallet { &amount_split_target, spending_conditions, )?, - None => PreMintSecrets::from_seed( - active_keyset_id, - count, - &self.seed, - amount, - &amount_split_target, - )?, + None => { + // Calculate how many secrets we'll need without generating them + let amount_split = amount.split_targeted(&amount_split_target)?; + let num_secrets = amount_split.len() as u32; + + tracing::debug!( + "Incrementing keyset {} counter by {}", + active_keyset_id, + num_secrets + ); + + // Atomically get the counter range we need + let new_counter = self + .localstore + .increment_keyset_counter(&active_keyset_id, num_secrets) + .await?; + + let count = new_counter - num_secrets; + + PreMintSecrets::from_seed( + active_keyset_id, + count, + &self.seed, + amount, + &amount_split_target, + )? + } }; let mut request = MintRequest { @@ -190,13 +205,6 @@ impl Wallet { self.localstore.add_mint_quote(quote_info.clone()).await?; - if spending_conditions.is_none() { - // Update counter for keyset - self.localstore - .increment_keyset_counter(&active_keyset_id, proofs.len() as u32) - .await?; - } - let proof_infos = proofs .iter() .map(|proof| { diff --git a/crates/cdk/src/wallet/melt/melt_bolt11.rs b/crates/cdk/src/wallet/melt/melt_bolt11.rs index 0cc6657e7..ce5fdc107 100644 --- a/crates/cdk/src/wallet/melt/melt_bolt11.rs +++ b/crates/cdk/src/wallet/melt/melt_bolt11.rs @@ -15,7 +15,7 @@ use crate::nuts::{ use crate::types::{Melted, ProofInfo}; use crate::util::unix_time; use crate::wallet::MeltQuote; -use crate::{ensure_cdk, Error, Wallet}; +use crate::{ensure_cdk, Amount, Error, Wallet}; impl Wallet { /// Melt Quote @@ -148,17 +148,32 @@ impl Wallet { let active_keyset_id = self.fetch_active_keyset().await?.id; - let count = self - .localstore - .get_keyset_counter(&active_keyset_id) - .await?; + let change_amount = proofs_total - quote_info.amount; - let premint_secrets = PreMintSecrets::from_seed_blank( - active_keyset_id, - count, - &self.seed, - proofs_total - quote_info.amount, - )?; + let premint_secrets = if change_amount <= Amount::ZERO { + PreMintSecrets::new(active_keyset_id) + } else { + // TODO: consolidate this calculation with from_seed_blank into a shared function + // Calculate how many secrets will be needed using the same logic as from_seed_blank + let num_secrets = + ((u64::from(change_amount) as f64).log2().ceil() as u64).max(1) as u32; + + tracing::debug!( + "Incrementing keyset {} counter by {}", + active_keyset_id, + num_secrets + ); + + // Atomically get the counter range we need + let new_counter = self + .localstore + .increment_keyset_counter(&active_keyset_id, num_secrets) + .await?; + + let count = new_counter - num_secrets; + + PreMintSecrets::from_seed_blank(active_keyset_id, count, &self.seed, change_amount)? + }; let request = MeltRequest::new( quote_id.to_string(), @@ -226,11 +241,6 @@ impl Wallet { change_proofs.total_amount()? ); - // Update counter for keyset - self.localstore - .increment_keyset_counter(&active_keyset_id, change_proofs.len() as u32) - .await?; - change_proofs .into_iter() .map(|proof| { diff --git a/crates/cdk/src/wallet/swap.rs b/crates/cdk/src/wallet/swap.rs index fcb84d878..6a5affb4b 100644 --- a/crates/cdk/src/wallet/swap.rs +++ b/crates/cdk/src/wallet/swap.rs @@ -52,10 +52,6 @@ impl Wallet { &active_keys, )?; - self.localstore - .increment_keyset_counter(&active_keyset_id, pre_swap.derived_secret_count) - .await?; - let mut added_proofs = Vec::new(); let change_proofs; let send_proofs; @@ -248,10 +244,42 @@ impl Wallet { let derived_secret_count; - let mut count = self - .localstore - .get_keyset_counter(&active_keyset_id) - .await?; + // Calculate total secrets needed and atomically reserve counter range + let total_secrets_needed = match spending_conditions { + Some(_) => { + // For spending conditions, we only need to count change secrets + change_amount.split_targeted(&change_split_target)?.len() as u32 + } + None => { + // For no spending conditions, count both send and change secrets + let send_count = send_amount + .unwrap_or(Amount::ZERO) + .split_targeted(&SplitTarget::default())? + .len() as u32; + let change_count = change_amount.split_targeted(&change_split_target)?.len() as u32; + send_count + change_count + } + }; + + // Atomically get the counter range we need + let starting_counter = if total_secrets_needed > 0 { + tracing::debug!( + "Incrementing keyset {} counter by {}", + active_keyset_id, + total_secrets_needed + ); + + let new_counter = self + .localstore + .increment_keyset_counter(&active_keyset_id, total_secrets_needed) + .await?; + + new_counter - total_secrets_needed + } else { + 0 // No secrets needed, don't increment the counter + }; + + let mut count = starting_counter; let (mut desired_messages, change_messages) = match spending_conditions { Some(conditions) => { From b885c8d78e01be1b5d21f1b5f29218b5fa71a8e3 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Fri, 15 Aug 2025 12:23:02 +0100 Subject: [PATCH 077/321] feat: fake mint bolt12 --- crates/cdk-fake-wallet/src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/cdk-fake-wallet/src/lib.rs b/crates/cdk-fake-wallet/src/lib.rs index eeba7bcb2..9d4f65976 100644 --- a/crates/cdk-fake-wallet/src/lib.rs +++ b/crates/cdk-fake-wallet/src/lib.rs @@ -118,7 +118,7 @@ impl MintPayment for FakeWallet { unit: self.unit.clone(), invoice_description: true, amountless: false, - bolt12: false, + bolt12: true, })?) } From 43a13878b1e4678aa8e57b3acc1219e190ee5ca1 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Fri, 15 Aug 2025 17:59:23 +0100 Subject: [PATCH 078/321] fix: remove unwrap in startup check --- crates/cdk/src/mint/start_up_check.rs | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/crates/cdk/src/mint/start_up_check.rs b/crates/cdk/src/mint/start_up_check.rs index 44a106369..e7284fc1e 100644 --- a/crates/cdk/src/mint/start_up_check.rs +++ b/crates/cdk/src/mint/start_up_check.rs @@ -10,13 +10,18 @@ use crate::types::PaymentProcessorKey; impl Mint { /// Checks the states of melt quotes that are **PENDING** or **UNKNOWN** to the mint with the ln node pub async fn check_pending_melt_quotes(&self) -> Result<(), Error> { - let melt_quotes = self.localstore.get_melt_quotes().await.unwrap(); + // TODO: We should have a db query to do this filtering + let melt_quotes = self.localstore.get_melt_quotes().await?; let pending_quotes: Vec = melt_quotes .into_iter() .filter(|q| q.state == MeltQuoteState::Pending || q.state == MeltQuoteState::Unknown) .collect(); tracing::info!("There are {} pending melt quotes.", pending_quotes.len()); + if pending_quotes.is_empty() { + return Ok(()); + } + let mut tx = self.localstore.begin_transaction().await?; for pending_quote in pending_quotes { From 8c425dee8cc454aa772145cd3adf417d255089eb Mon Sep 17 00:00:00 2001 From: Ruben Date: Wed, 13 Aug 2025 22:49:09 +0200 Subject: [PATCH 079/321] chore(flake): add NIX_PATH for flake --- flake.nix | 211 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 129 insertions(+), 82 deletions(-) diff --git a/flake.nix b/flake.nix index d90c42f14..cbd3b0bc5 100644 --- a/flake.nix +++ b/flake.nix @@ -21,37 +21,48 @@ crane = { url = "github:ipetkov/crane"; - inputs.nixpkgs.follows = "nixpkgs"; }; pre-commit-hooks.url = "github:cachix/pre-commit-hooks.nix"; }; - outputs = { self, nixpkgs, rust-overlay, flake-utils, pre-commit-hooks, ... }: - flake-utils.lib.eachDefaultSystem (system: + outputs = + { self + , nixpkgs + , rust-overlay + , flake-utils + , pre-commit-hooks + , ... + }@inputs: + flake-utils.lib.eachDefaultSystem ( + system: let overlays = [ (import rust-overlay) ]; lib = pkgs.lib; stdenv = pkgs.stdenv; isDarwin = stdenv.isDarwin; - libsDarwin = with pkgs; lib.optionals isDarwin [ - # Additional darwin specific inputs can be set here - darwin.apple_sdk.frameworks.Security - darwin.apple_sdk.frameworks.SystemConfiguration - ]; + libsDarwin = + with pkgs; + lib.optionals isDarwin [ + # Additional darwin specific inputs can be set here + darwin.apple_sdk.frameworks.Security + darwin.apple_sdk.frameworks.SystemConfiguration + ]; # Dependencies pkgs = import nixpkgs { inherit system overlays; }; - - # Toolchains # latest stable stable_toolchain = pkgs.rust-bin.stable."1.86.0".default.override { targets = [ "wasm32-unknown-unknown" ]; # wasm - extensions = [ "rustfmt" "clippy" "rust-analyzer" ]; + extensions = [ + "rustfmt" + "clippy" + "rust-analyzer" + ]; }; # MSRV stable @@ -60,38 +71,53 @@ }; # Nightly used for formatting - nightly_toolchain = pkgs.rust-bin.selectLatestNightlyWith (toolchain: toolchain.default.override { - extensions = [ "rustfmt" "clippy" "rust-analyzer" "rust-src" ]; - targets = [ "wasm32-unknown-unknown" ]; # wasm - }); + nightly_toolchain = pkgs.rust-bin.selectLatestNightlyWith ( + toolchain: + toolchain.default.override { + extensions = [ + "rustfmt" + "clippy" + "rust-analyzer" + "rust-src" + ]; + targets = [ "wasm32-unknown-unknown" ]; # wasm + } + ); # Common inputs - envVars = { }; - buildInputs = with pkgs; [ - # Add additional build inputs here - git - pkg-config - curl - just - protobuf - nixpkgs-fmt - typos - lnd - clightning - bitcoind - sqlx-cli - cargo-outdated - mprocs - - # Needed for github ci - libz - ] ++ libsDarwin; - + envVars = { + # rust analyzer needs NIX_PATH for some reason. + NIX_PATH = "nixpkgs=${inputs.nixpkgs}"; + }; + buildInputs = + with pkgs; + [ + # Add additional build inputs here + git + pkg-config + curl + just + protobuf + nixpkgs-fmt + typos + lnd + clightning + bitcoind + sqlx-cli + cargo-outdated + mprocs + + # Needed for github ci + libz + ] + ++ libsDarwin; # Common arguments can be set here to avoid repeating them later nativeBuildInputs = [ + pkgs.rust-analyzer #Add additional build inputs here - ] ++ lib.optionals isDarwin [ + ] + ++ lib.optionals isDarwin [ # Additional darwin specific native inputs can be set here ]; in @@ -108,7 +134,10 @@ inherit (_rust) meta; buildInputs = [ pkgs.makeWrapper ]; paths = [ _rust ]; - pathsToLink = [ "/" "/bin" ]; + pathsToLink = [ + "/" + "/bin" + ]; postBuild = '' for i in $out/bin/*; do wrapProgram "$i" --prefix PATH : "$out/bin" @@ -136,57 +165,75 @@ _shellHook = (self.checks.${system}.pre-commit-check.shellHook or ""); # devShells - msrv = pkgs.mkShell ({ - shellHook = " + msrv = pkgs.mkShell ( + { + shellHook = " ${_shellHook} "; - buildInputs = buildInputs ++ [ msrv_toolchain ]; - inherit nativeBuildInputs; - } // envVars); - - stable = pkgs.mkShell ({ - shellHook = ''${_shellHook}''; - buildInputs = buildInputs ++ [ stable_toolchain ]; - inherit nativeBuildInputs; - } // envVars); - - - nightly = pkgs.mkShell ({ - shellHook = '' - ${_shellHook} - # Needed for github ci - export LD_LIBRARY_PATH=${pkgs.lib.makeLibraryPath [ - pkgs.zlib - ]}:$LD_LIBRARY_PATH - export RUST_SRC_PATH=${nightly_toolchain}/lib/rustlib/src/rust/library - ''; - buildInputs = buildInputs ++ [ nightly_toolchain ]; - inherit nativeBuildInputs; - } // envVars); + buildInputs = buildInputs ++ [ msrv_toolchain ]; + inherit nativeBuildInputs; + } + // envVars + ); + + stable = pkgs.mkShell ( + { + shellHook = ''${_shellHook}''; + buildInputs = buildInputs ++ [ stable_toolchain ]; + inherit nativeBuildInputs; + + } + // envVars + ); + + nightly = pkgs.mkShell ( + { + shellHook = '' + ${_shellHook} + # Needed for github ci + export LD_LIBRARY_PATH=${ + pkgs.lib.makeLibraryPath [ + pkgs.zlib + ] + }:$LD_LIBRARY_PATH + ''; + buildInputs = buildInputs ++ [ nightly_toolchain ]; + inherit nativeBuildInputs; + } + // envVars + ); # Shell with Docker for integration tests - integration = pkgs.mkShell ({ - shellHook = '' - ${_shellHook} - # Ensure Docker is available - if ! command -v docker &> /dev/null; then - echo "Docker is not installed or not in PATH" - echo "Please install Docker to run integration tests" - exit 1 - fi - echo "Docker is available at $(which docker)" - echo "Docker version: $(docker --version)" - ''; - buildInputs = buildInputs ++ [ - stable_toolchain - pkgs.docker-client - ]; - inherit nativeBuildInputs; - } // envVars); + integration = pkgs.mkShell ( + { + shellHook = '' + ${_shellHook} + # Ensure Docker is available + if ! command -v docker &> /dev/null; then + echo "Docker is not installed or not in PATH" + echo "Please install Docker to run integration tests" + exit 1 + fi + echo "Docker is available at $(which docker)" + echo "Docker version: $(docker --version)" + ''; + buildInputs = buildInputs ++ [ + stable_toolchain + pkgs.docker-client + ]; + inherit nativeBuildInputs; + } + // envVars + ); in { - inherit msrv stable nightly integration; + inherit + msrv + stable + nightly + integration + ; default = stable; }; } From 5ef2be36f22570c234a59245d039278ed53f323e Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Mon, 18 Aug 2025 11:34:53 +0100 Subject: [PATCH 080/321] feat(cdk): allow minting less than paid amount for non-bolt11 payments For bolt11 payments, enforce exact amount matching between outputs and quote. For other payment methods, allow minting less than paid amount while preventing overspending. --- crates/cdk/src/mint/issue/mod.rs | 45 +++++++++++++-------- crates/cdk/src/wallet/issue/issue_bolt12.rs | 2 +- 2 files changed, 30 insertions(+), 17 deletions(-) diff --git a/crates/cdk/src/mint/issue/mod.rs b/crates/cdk/src/mint/issue/mod.rs index e53baf78b..1d46b41f2 100644 --- a/crates/cdk/src/mint/issue/mod.rs +++ b/crates/cdk/src/mint/issue/mod.rs @@ -552,23 +552,36 @@ impl Mint { mint_request.verify_signature(pubkey)?; } - let Verification { amount, unit } = - match self.verify_outputs(&mut tx, &mint_request.outputs).await { - Ok(verification) => verification, - Err(err) => { - tracing::debug!("Could not verify mint outputs"); + let Verification { + amount: outputs_amount, + unit, + } = match self.verify_outputs(&mut tx, &mint_request.outputs).await { + Ok(verification) => verification, + Err(err) => { + tracing::debug!("Could not verify mint outputs"); - return Err(err); - } - }; - - // We check the total value of blinded messages == mint quote - if amount != mint_amount { - return Err(Error::TransactionUnbalanced( - mint_amount.into(), - mint_request.total_amount()?.into(), - 0, - )); + return Err(err); + } + }; + + if mint_quote.payment_method == PaymentMethod::Bolt11 { + // For bolt11 we enforce that mint amount == quote amount + if outputs_amount != mint_amount { + return Err(Error::TransactionUnbalanced( + mint_amount.into(), + mint_request.total_amount()?.into(), + 0, + )); + } + } else { + // For other payments we just make sure outputs is not more then mint amount + if outputs_amount > mint_amount { + return Err(Error::TransactionUnbalanced( + mint_amount.into(), + mint_request.total_amount()?.into(), + 0, + )); + } } let unit = unit.ok_or(Error::UnsupportedUnit).unwrap(); diff --git a/crates/cdk/src/wallet/issue/issue_bolt12.rs b/crates/cdk/src/wallet/issue/issue_bolt12.rs index 6e788e3e3..5ac6964e6 100644 --- a/crates/cdk/src/wallet/issue/issue_bolt12.rs +++ b/crates/cdk/src/wallet/issue/issue_bolt12.rs @@ -97,7 +97,7 @@ impl Wallet { let quote_info = if let Some(quote) = quote_info { if quote.expiry.le(&unix_time()) && quote.expiry.ne(&0) { - return Err(Error::ExpiredQuote(quote.expiry, unix_time())); + tracing::info!("Minting after expiry"); } quote.clone() From f8d58e419fc34a2c5c35dab9e8bd56ba5eae2b52 Mon Sep 17 00:00:00 2001 From: C Date: Mon, 18 Aug 2025 08:57:45 -0300 Subject: [PATCH 081/321] Merge pull request #963 from crodas/feature/wait-for-invoice Add `wait_for_payment` function in the wallet --- crates/cdk-common/src/error.rs | 4 + .../src/init_pure_tests.rs | 7 +- crates/cdk-integration-tests/src/lib.rs | 94 +----------- crates/cdk-integration-tests/tests/bolt12.rs | 32 +++- .../cdk-integration-tests/tests/fake_auth.rs | 18 +-- .../tests/fake_wallet.rs | 69 ++++++--- .../tests/happy_path_mint_wallet.rs | 19 ++- crates/cdk-integration-tests/tests/regtest.rs | 21 +-- .../cdk-integration-tests/tests/test_fees.rs | 11 +- crates/cdk/Cargo.toml | 2 +- crates/cdk/examples/auth_wallet.rs | 29 +--- crates/cdk/examples/melt-token.rs | 30 +--- crates/cdk/examples/mint-token.rs | 30 +--- crates/cdk/examples/p2pk.rs | 31 +--- crates/cdk/examples/proof-selection.rs | 30 +--- crates/cdk/examples/wallet.rs | 34 +---- crates/cdk/src/wallet/mod.rs | 1 + crates/cdk/src/wallet/wait.rs | 138 ++++++++++++++++++ 18 files changed, 299 insertions(+), 301 deletions(-) create mode 100644 crates/cdk/src/wallet/wait.rs diff --git a/crates/cdk-common/src/error.rs b/crates/cdk-common/src/error.rs index c21b2988e..23aaeb5ed 100644 --- a/crates/cdk-common/src/error.rs +++ b/crates/cdk-common/src/error.rs @@ -111,6 +111,10 @@ pub enum Error { #[error("Could not parse bolt12")] Bolt12parse, + /// Operation timeout + #[error("Operation timeout")] + Timeout, + /// Internal Error - Send error #[error("Internal send error: {0}")] SendError(String), diff --git a/crates/cdk-integration-tests/src/init_pure_tests.rs b/crates/cdk-integration-tests/src/init_pure_tests.rs index 73417233f..91101834c 100644 --- a/crates/cdk-integration-tests/src/init_pure_tests.rs +++ b/crates/cdk-integration-tests/src/init_pure_tests.rs @@ -3,6 +3,7 @@ use std::fmt::{Debug, Formatter}; use std::path::PathBuf; use std::str::FromStr; use std::sync::Arc; +use std::time::Duration; use std::{env, fs}; use anyhow::{anyhow, bail, Result}; @@ -28,8 +29,6 @@ use tokio::sync::RwLock; use tracing_subscriber::EnvFilter; use uuid::Uuid; -use crate::wait_for_mint_to_be_paid; - pub struct DirectMintConnection { pub mint: Mint, auth_wallet: Arc>>, @@ -362,7 +361,9 @@ pub async fn fund_wallet( let desired_amount = Amount::from(amount); let quote = wallet.mint_quote(desired_amount, None).await?; - wait_for_mint_to_be_paid(&wallet, "e.id, 60).await?; + wallet + .wait_for_payment("e, Duration::from_secs(60)) + .await?; Ok(wallet .mint("e.id, split_target.unwrap_or_default(), None) diff --git a/crates/cdk-integration-tests/src/lib.rs b/crates/cdk-integration-tests/src/lib.rs index 0643cae62..2f4dc70d8 100644 --- a/crates/cdk-integration-tests/src/lib.rs +++ b/crates/cdk-integration-tests/src/lib.rs @@ -21,15 +21,14 @@ use std::path::Path; use std::sync::Arc; use anyhow::{anyhow, bail, Result}; -use cashu::{Bolt11Invoice, PaymentMethod}; +use cashu::Bolt11Invoice; use cdk::amount::{Amount, SplitTarget}; -use cdk::nuts::{MintQuoteState, NotificationPayload, State}; -use cdk::wallet::WalletSubscription; +use cdk::nuts::State; use cdk::Wallet; use cdk_fake_wallet::create_fake_invoice; use init_regtest::{get_lnd_dir, LND_RPC_ADDR}; use ln_regtest_rs::ln_client::{LightningClient, LndClient}; -use tokio::time::{sleep, timeout, Duration}; +use tokio::time::Duration; pub mod cli; pub mod init_auth_mint; @@ -43,9 +42,10 @@ pub async fn fund_wallet(wallet: Arc, amount: Amount) { .await .expect("Could not get mint quote"); - wait_for_mint_to_be_paid(&wallet, "e.id, 60) + wallet + .wait_for_payment("e, Duration::from_secs(60)) .await - .expect("Waiting for mint failed"); + .expect("wait for mint failed"); let _proofs = wallet .mint("e.id, SplitTarget::default(), None) @@ -104,88 +104,6 @@ pub async fn attempt_to_swap_pending(wallet: &Wallet) -> Result<()> { Ok(()) } -pub async fn wait_for_mint_to_be_paid( - wallet: &Wallet, - mint_quote_id: &str, - timeout_secs: u64, -) -> Result<()> { - let mut subscription = wallet - .subscribe(WalletSubscription::Bolt11MintQuoteState(vec![ - mint_quote_id.to_owned(), - ])) - .await; - // Create the timeout future - let wait_future = async { - while let Some(msg) = subscription.recv().await { - if let NotificationPayload::MintQuoteBolt11Response(response) = msg { - if response.state == MintQuoteState::Paid { - return Ok(()); - } - } else if let NotificationPayload::MintQuoteBolt12Response(response) = msg { - if response.amount_paid > Amount::ZERO { - return Ok(()); - } - } - } - Err(anyhow!("Subscription ended without quote being paid")) - }; - - let timeout_future = timeout(Duration::from_secs(timeout_secs), wait_future); - - let check_interval = Duration::from_secs(5); - - let method = wallet - .localstore - .get_mint_quote(mint_quote_id) - .await? - .map(|q| q.payment_method) - .unwrap_or_default(); - - let periodic_task = async { - loop { - match method { - PaymentMethod::Bolt11 => match wallet.mint_quote_state(mint_quote_id).await { - Ok(result) => { - if result.state == MintQuoteState::Paid { - tracing::info!("mint quote paid via poll"); - return Ok(()); - } - } - Err(e) => { - tracing::error!("Could not check mint quote status: {:?}", e); - } - }, - PaymentMethod::Bolt12 => { - match wallet.mint_bolt12_quote_state(mint_quote_id).await { - Ok(result) => { - if result.amount_paid > Amount::ZERO { - return Ok(()); - } - } - Err(e) => { - tracing::error!("Could not check mint quote status: {:?}", e); - } - } - } - PaymentMethod::Custom(_) => (), - } - sleep(check_interval).await; - } - }; - - tokio::select! { - result = timeout_future => { - match result { - Ok(payment_result) => payment_result, - Err(_) => Err(anyhow!("Timeout waiting for mint quote ({}) to be paid", mint_quote_id)), - } - } - result = periodic_task => { - result // Now propagates the result from periodic checks - } - } -} - // This is the ln wallet we use to send/receive ln payements as the wallet pub async fn init_lnd_client(work_dir: &Path) -> LndClient { let lnd_dir = get_lnd_dir(work_dir, "one"); diff --git a/crates/cdk-integration-tests/tests/bolt12.rs b/crates/cdk-integration-tests/tests/bolt12.rs index 973a1894c..ca25a4c92 100644 --- a/crates/cdk-integration-tests/tests/bolt12.rs +++ b/crates/cdk-integration-tests/tests/bolt12.rs @@ -1,6 +1,7 @@ use std::env; use std::path::PathBuf; use std::sync::Arc; +use std::time::Duration; use anyhow::{bail, Result}; use bip39::Mnemonic; @@ -8,8 +9,8 @@ use cashu::amount::SplitTarget; use cashu::nut23::Amountless; use cashu::{Amount, CurrencyUnit, MintRequest, PreMintSecrets, ProofsMethods}; use cdk::wallet::{HttpClient, MintConnector, Wallet}; +use cdk_integration_tests::get_mint_url_from_env; use cdk_integration_tests::init_regtest::{get_cln_dir, get_temp_dir}; -use cdk_integration_tests::{get_mint_url_from_env, wait_for_mint_to_be_paid}; use cdk_sqlite::wallet::memory; use ln_regtest_rs::ln_client::ClnClient; @@ -115,7 +116,9 @@ async fn test_regtest_bolt12_mint_multiple() -> Result<()> { .await .unwrap(); - wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60).await?; + wallet + .wait_for_payment(&mint_quote, Duration::from_secs(60)) + .await?; wallet.mint_bolt12_quote_state(&mint_quote.id).await?; @@ -127,11 +130,13 @@ async fn test_regtest_bolt12_mint_multiple() -> Result<()> { assert_eq!(proofs.total_amount().unwrap(), 10.into()); cln_client - .pay_bolt12_offer(Some(11_000), mint_quote.request) + .pay_bolt12_offer(Some(11_000), mint_quote.request.clone()) .await .unwrap(); - wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60).await?; + wallet + .wait_for_payment(&mint_quote, Duration::from_secs(60)) + .await?; wallet.mint_bolt12_quote_state(&mint_quote.id).await?; @@ -181,7 +186,11 @@ async fn test_regtest_bolt12_multiple_wallets() -> Result<()> { cln_client .pay_bolt12_offer(None, quote_one.request.clone()) .await?; - wait_for_mint_to_be_paid(&wallet_one, "e_one.id, 60).await?; + + wallet_one + .wait_for_payment("e_one, Duration::from_secs(60)) + .await?; + let proofs_one = wallet_one .mint_bolt12("e_one.id, None, SplitTarget::default(), None) .await?; @@ -195,7 +204,10 @@ async fn test_regtest_bolt12_multiple_wallets() -> Result<()> { cln_client .pay_bolt12_offer(None, quote_two.request.clone()) .await?; - wait_for_mint_to_be_paid(&wallet_two, "e_two.id, 60).await?; + + wallet_two + .wait_for_payment("e_two, Duration::from_secs(60)) + .await?; let proofs_two = wallet_two .mint_bolt12("e_two.id, None, SplitTarget::default(), None) @@ -271,7 +283,9 @@ async fn test_regtest_bolt12_melt() -> Result<()> { .await?; // Wait for payment to be processed - wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60).await?; + wallet + .wait_for_payment(&mint_quote, Duration::from_secs(60)) + .await?; let offer = cln_client .get_bolt12_offer(Some(10_000), true, "hhhhhhhh".to_string()) @@ -330,7 +344,9 @@ async fn test_regtest_bolt12_mint_extra() -> Result<()> { .pay_bolt12_offer(Some(pay_amount_msats), mint_quote.request.clone()) .await?; - wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 10).await?; + wallet + .wait_for_payment(&mint_quote, Duration::from_secs(10)) + .await?; let state = wallet.mint_bolt12_quote_state(&mint_quote.id).await?; diff --git a/crates/cdk-integration-tests/tests/fake_auth.rs b/crates/cdk-integration-tests/tests/fake_auth.rs index 16c3123c7..6a934254b 100644 --- a/crates/cdk-integration-tests/tests/fake_auth.rs +++ b/crates/cdk-integration-tests/tests/fake_auth.rs @@ -1,6 +1,7 @@ use std::env; use std::str::FromStr; use std::sync::Arc; +use std::time::Duration; use bip39::Mnemonic; use cashu::{MintAuthRequest, MintInfo}; @@ -15,7 +16,7 @@ use cdk::nuts::{ use cdk::wallet::{AuthHttpClient, AuthMintConnector, HttpClient, MintConnector, WalletBuilder}; use cdk::{Error, OidcClient}; use cdk_fake_wallet::create_fake_invoice; -use cdk_integration_tests::{fund_wallet, wait_for_mint_to_be_paid}; +use cdk_integration_tests::fund_wallet; use cdk_sqlite::wallet::memory; const MINT_URL: &str = "http://127.0.0.1:8087"; @@ -329,19 +330,12 @@ async fn test_mint_with_auth() { let mint_amount: Amount = 100.into(); - let mint_quote = wallet - .mint_quote(mint_amount, None) - .await - .expect("failed to get mint quote"); - - wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60) + let (_, proofs) = wallet + .mint_once_paid(mint_amount, None, Duration::from_secs(10)) .await - .expect("failed to wait for payment"); + .unwrap(); - let proofs = wallet - .mint(&mint_quote.id, SplitTarget::default(), None) - .await - .expect("could not mint"); + let proofs = proofs.await.expect("could not mint"); assert!(proofs.total_amount().expect("Could not get proofs amount") == mint_amount); } diff --git a/crates/cdk-integration-tests/tests/fake_wallet.rs b/crates/cdk-integration-tests/tests/fake_wallet.rs index c4066c5b3..6d3cb3f24 100644 --- a/crates/cdk-integration-tests/tests/fake_wallet.rs +++ b/crates/cdk-integration-tests/tests/fake_wallet.rs @@ -15,6 +15,7 @@ //! - Duplicate proof detection use std::sync::Arc; +use std::time::Duration; use bip39::Mnemonic; use cashu::Amount; @@ -27,7 +28,7 @@ use cdk::nuts::{ use cdk::wallet::types::TransactionDirection; use cdk::wallet::{HttpClient, MintConnector, Wallet}; use cdk_fake_wallet::{create_fake_invoice, FakeInvoiceDescription}; -use cdk_integration_tests::{attempt_to_swap_pending, wait_for_mint_to_be_paid}; +use cdk_integration_tests::attempt_to_swap_pending; use cdk_sqlite::wallet::memory; const MINT_URL: &str = "http://127.0.0.1:8086"; @@ -46,7 +47,8 @@ async fn test_fake_tokens_pending() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60) + wallet + .wait_for_payment(&mint_quote, Duration::from_secs(60)) .await .unwrap(); @@ -88,7 +90,8 @@ async fn test_fake_melt_payment_fail() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60) + wallet + .wait_for_payment(&mint_quote, Duration::from_secs(60)) .await .unwrap(); @@ -153,7 +156,8 @@ async fn test_fake_melt_payment_fail_and_check() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60) + wallet + .wait_for_payment(&mint_quote, Duration::from_secs(60)) .await .unwrap(); @@ -201,7 +205,8 @@ async fn test_fake_melt_payment_return_fail_status() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60) + wallet + .wait_for_payment(&mint_quote, Duration::from_secs(60)) .await .unwrap(); @@ -264,7 +269,8 @@ async fn test_fake_melt_payment_error_unknown() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60) + wallet + .wait_for_payment(&mint_quote, Duration::from_secs(60)) .await .unwrap(); @@ -327,7 +333,8 @@ async fn test_fake_melt_payment_err_paid() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60) + wallet + .wait_for_payment(&mint_quote, Duration::from_secs(60)) .await .unwrap(); @@ -368,7 +375,8 @@ async fn test_fake_melt_change_in_quote() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60) + wallet + .wait_for_payment(&mint_quote, Duration::from_secs(60)) .await .unwrap(); @@ -437,7 +445,8 @@ async fn test_fake_mint_with_witness() { .expect("failed to create new wallet"); let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60) + wallet + .wait_for_payment(&mint_quote, Duration::from_secs(60)) .await .unwrap(); @@ -465,7 +474,8 @@ async fn test_fake_mint_without_witness() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60) + wallet + .wait_for_payment(&mint_quote, Duration::from_secs(60)) .await .unwrap(); @@ -505,7 +515,8 @@ async fn test_fake_mint_with_wrong_witness() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60) + wallet + .wait_for_payment(&mint_quote, Duration::from_secs(60)) .await .unwrap(); @@ -551,7 +562,8 @@ async fn test_fake_mint_inflated() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60) + wallet + .wait_for_payment(&mint_quote, Duration::from_secs(60)) .await .unwrap(); @@ -609,7 +621,8 @@ async fn test_fake_mint_multiple_units() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60) + wallet + .wait_for_payment(&mint_quote, Duration::from_secs(60)) .await .unwrap(); @@ -688,7 +701,8 @@ async fn test_fake_mint_multiple_unit_swap() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60) + wallet + .wait_for_payment(&mint_quote, Duration::from_secs(60)) .await .unwrap(); @@ -709,7 +723,8 @@ async fn test_fake_mint_multiple_unit_swap() { let mint_quote = wallet_usd.mint_quote(100.into(), None).await.unwrap(); - wait_for_mint_to_be_paid(&wallet_usd, &mint_quote.id, 60) + wallet + .wait_for_payment(&mint_quote, Duration::from_secs(60)) .await .unwrap(); @@ -802,7 +817,8 @@ async fn test_fake_mint_multiple_unit_melt() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60) + wallet + .wait_for_payment(&mint_quote, Duration::from_secs(60)) .await .unwrap(); @@ -825,7 +841,8 @@ async fn test_fake_mint_multiple_unit_melt() { let mint_quote = wallet_usd.mint_quote(100.into(), None).await.unwrap(); println!("Minted quote usd"); - wait_for_mint_to_be_paid(&wallet_usd, &mint_quote.id, 60) + wallet + .wait_for_payment(&mint_quote, Duration::from_secs(60)) .await .unwrap(); @@ -920,7 +937,8 @@ async fn test_fake_mint_input_output_mismatch() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60) + wallet + .wait_for_payment(&mint_quote, Duration::from_secs(60)) .await .unwrap(); @@ -978,7 +996,8 @@ async fn test_fake_mint_swap_inflated() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60) + wallet + .wait_for_payment(&mint_quote, Duration::from_secs(60)) .await .unwrap(); @@ -1022,7 +1041,8 @@ async fn test_fake_mint_swap_spend_after_fail() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60) + wallet + .wait_for_payment(&mint_quote, Duration::from_secs(60)) .await .unwrap(); @@ -1093,7 +1113,8 @@ async fn test_fake_mint_melt_spend_after_fail() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60) + wallet + .wait_for_payment(&mint_quote, Duration::from_secs(60)) .await .unwrap(); @@ -1165,7 +1186,8 @@ async fn test_fake_mint_duplicate_proofs_swap() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60) + wallet + .wait_for_payment(&mint_quote, Duration::from_secs(60)) .await .unwrap(); @@ -1245,7 +1267,8 @@ async fn test_fake_mint_duplicate_proofs_melt() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60) + wallet + .wait_for_payment(&mint_quote, Duration::from_secs(60)) .await .unwrap(); diff --git a/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs b/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs index c1dcd4f05..630460927 100644 --- a/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs +++ b/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs @@ -22,9 +22,7 @@ use cdk::amount::{Amount, SplitTarget}; use cdk::nuts::nut00::ProofsMethods; use cdk::nuts::{CurrencyUnit, MeltQuoteState, NotificationPayload, State}; use cdk::wallet::{HttpClient, MintConnector, Wallet}; -use cdk_integration_tests::{ - create_invoice_for_env, get_mint_url_from_env, pay_if_regtest, wait_for_mint_to_be_paid, -}; +use cdk_integration_tests::{create_invoice_for_env, get_mint_url_from_env, pay_if_regtest}; use cdk_sqlite::wallet::memory; use futures::{SinkExt, StreamExt}; use lightning_invoice::Bolt11Invoice; @@ -111,7 +109,8 @@ async fn test_happy_mint_melt_round_trip() { .await .unwrap(); - wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 10) + wallet + .wait_for_payment(&mint_quote, Duration::from_secs(60)) .await .unwrap(); @@ -234,7 +233,8 @@ async fn test_happy_mint() { .await .unwrap(); - wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60) + wallet + .wait_for_payment(&mint_quote, Duration::from_secs(60)) .await .unwrap(); @@ -281,7 +281,8 @@ async fn test_restore() { .await .unwrap(); - wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60) + wallet + .wait_for_payment(&mint_quote, Duration::from_secs(60)) .await .unwrap(); @@ -360,7 +361,8 @@ async fn test_fake_melt_change_in_quote() { pay_if_regtest(&get_test_temp_dir(), &bolt11).await.unwrap(); - wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60) + wallet + .wait_for_payment(&mint_quote, Duration::from_secs(60)) .await .unwrap(); @@ -431,7 +433,8 @@ async fn test_pay_invoice_twice() { .await .unwrap(); - wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60) + wallet + .wait_for_payment(&mint_quote, Duration::from_secs(60)) .await .unwrap(); diff --git a/crates/cdk-integration-tests/tests/regtest.rs b/crates/cdk-integration-tests/tests/regtest.rs index fabc7c324..fad096559 100644 --- a/crates/cdk-integration-tests/tests/regtest.rs +++ b/crates/cdk-integration-tests/tests/regtest.rs @@ -27,9 +27,7 @@ use cdk::nuts::{ }; use cdk::wallet::{HttpClient, MintConnector, Wallet, WalletSubscription}; use cdk_integration_tests::init_regtest::{get_lnd_dir, LND_RPC_ADDR}; -use cdk_integration_tests::{ - get_mint_url_from_env, get_second_mint_url_from_env, wait_for_mint_to_be_paid, -}; +use cdk_integration_tests::{get_mint_url_from_env, get_second_mint_url_from_env}; use cdk_sqlite::wallet::{self, memory}; use futures::join; use ln_regtest_rs::ln_client::{LightningClient, LndClient}; @@ -84,11 +82,12 @@ async fn test_internal_payment() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); lnd_client - .pay_invoice(mint_quote.request) + .pay_invoice(mint_quote.request.clone()) .await .expect("failed to pay invoice"); - wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60) + wallet + .wait_for_payment(&mint_quote, Duration::from_secs(60)) .await .unwrap(); @@ -119,7 +118,8 @@ async fn test_internal_payment() { let _melted = wallet.melt(&melt.id).await.unwrap(); - wait_for_mint_to_be_paid(&wallet_2, &mint_quote.id, 60) + wallet_2 + .wait_for_payment(&mint_quote, Duration::from_secs(60)) .await .unwrap(); @@ -261,7 +261,8 @@ async fn test_multimint_melt() { .pay_invoice(quote.request.clone()) .await .expect("failed to pay invoice"); - wait_for_mint_to_be_paid(&wallet1, "e.id, 60) + wallet1 + .wait_for_payment("e, Duration::from_secs(60)) .await .unwrap(); wallet1 @@ -274,7 +275,8 @@ async fn test_multimint_melt() { .pay_invoice(quote.request.clone()) .await .expect("failed to pay invoice"); - wait_for_mint_to_be_paid(&wallet2, "e.id, 60) + wallet2 + .wait_for_payment("e, Duration::from_secs(60)) .await .unwrap(); wallet2 @@ -334,7 +336,8 @@ async fn test_cached_mint() { .await .expect("failed to pay invoice"); - wait_for_mint_to_be_paid(&wallet, "e.id, 60) + wallet + .wait_for_payment("e, Duration::from_secs(60)) .await .unwrap(); diff --git a/crates/cdk-integration-tests/tests/test_fees.rs b/crates/cdk-integration-tests/tests/test_fees.rs index bfbcae9ff..a2352f6c3 100644 --- a/crates/cdk-integration-tests/tests/test_fees.rs +++ b/crates/cdk-integration-tests/tests/test_fees.rs @@ -1,5 +1,6 @@ use std::str::FromStr; use std::sync::Arc; +use std::time::Duration; use bip39::Mnemonic; use cashu::{Bolt11Invoice, ProofsMethods}; @@ -7,9 +8,7 @@ use cdk::amount::{Amount, SplitTarget}; use cdk::nuts::CurrencyUnit; use cdk::wallet::{ReceiveOptions, SendKind, SendOptions, Wallet}; use cdk_integration_tests::init_regtest::get_temp_dir; -use cdk_integration_tests::{ - create_invoice_for_env, get_mint_url_from_env, pay_if_regtest, wait_for_mint_to_be_paid, -}; +use cdk_integration_tests::{create_invoice_for_env, get_mint_url_from_env, pay_if_regtest}; use cdk_sqlite::wallet::memory; #[tokio::test(flavor = "multi_thread", worker_threads = 1)] @@ -29,7 +28,8 @@ async fn test_swap() { let invoice = Bolt11Invoice::from_str(&mint_quote.request).unwrap(); pay_if_regtest(&get_temp_dir(), &invoice).await.unwrap(); - wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 10) + wallet + .wait_for_payment(&mint_quote, Duration::from_secs(60)) .await .unwrap(); @@ -96,7 +96,8 @@ async fn test_fake_melt_change_in_quote() { pay_if_regtest(&get_temp_dir(), &bolt11).await.unwrap(); - wait_for_mint_to_be_paid(&wallet, &mint_quote.id, 60) + wallet + .wait_for_payment(&mint_quote, Duration::from_secs(60)) .await .unwrap(); diff --git a/crates/cdk/Cargo.toml b/crates/cdk/Cargo.toml index 73d3a1e7f..b00373e9b 100644 --- a/crates/cdk/Cargo.toml +++ b/crates/cdk/Cargo.toml @@ -12,7 +12,7 @@ license.workspace = true [features] default = ["mint", "wallet", "auth"] -wallet = ["dep:reqwest", "cdk-common/wallet", "dep:rustls"] +wallet = ["dep:futures", "dep:reqwest", "cdk-common/wallet", "dep:rustls"] mint = ["dep:futures", "dep:reqwest", "cdk-common/mint", "cdk-signatory"] auth = ["dep:jsonwebtoken", "cdk-common/auth", "cdk-common/auth"] # We do not commit to a MSRV with swagger enabled diff --git a/crates/cdk/examples/auth_wallet.rs b/crates/cdk/examples/auth_wallet.rs index 73b614a2b..5b23a4f26 100644 --- a/crates/cdk/examples/auth_wallet.rs +++ b/crates/cdk/examples/auth_wallet.rs @@ -1,9 +1,9 @@ use std::sync::Arc; +use std::time::Duration; -use cdk::amount::SplitTarget; use cdk::error::Error; -use cdk::nuts::{CurrencyUnit, MintQuoteState, NotificationPayload}; -use cdk::wallet::{SendOptions, Wallet, WalletSubscription}; +use cdk::nuts::CurrencyUnit; +use cdk::wallet::{SendOptions, Wallet}; use cdk::{Amount, OidcClient}; use cdk_common::{MintInfo, ProofsMethods}; use cdk_sqlite::wallet::memory; @@ -57,27 +57,12 @@ async fn main() -> Result<(), Error> { .await .expect("Could not mint blind auth"); - // Request a mint quote from the wallet - let quote = wallet.mint_quote(amount, None).await?; - - // Subscribe to updates on the mint quote state - let mut subscription = wallet - .subscribe(WalletSubscription::Bolt11MintQuoteState(vec![quote - .id - .clone()])) - .await; - - // Wait for the mint quote to be paid - while let Some(msg) = subscription.recv().await { - if let NotificationPayload::MintQuoteBolt11Response(response) = msg { - if response.state == MintQuoteState::Paid { - break; - } - } - } + let (_invoice_to_pay, proofs) = wallet + .mint_once_paid(amount, None, Duration::from_secs(10)) + .await?; // Mint the received amount - let receive_amount = wallet.mint("e.id, SplitTarget::default(), None).await?; + let receive_amount = proofs.await?; println!("Received: {}", receive_amount.total_amount()?); diff --git a/crates/cdk/examples/melt-token.rs b/crates/cdk/examples/melt-token.rs index b3aeb4028..c97106fe0 100644 --- a/crates/cdk/examples/melt-token.rs +++ b/crates/cdk/examples/melt-token.rs @@ -1,13 +1,13 @@ use std::sync::Arc; +use std::time::Duration; use bitcoin::hashes::{sha256, Hash}; use bitcoin::hex::prelude::FromHex; use bitcoin::secp256k1::Secp256k1; -use cdk::amount::SplitTarget; use cdk::error::Error; use cdk::nuts::nut00::ProofsMethods; -use cdk::nuts::{CurrencyUnit, MintQuoteState, NotificationPayload, SecretKey}; -use cdk::wallet::{Wallet, WalletSubscription}; +use cdk::nuts::{CurrencyUnit, SecretKey}; +use cdk::wallet::Wallet; use cdk::Amount; use cdk_sqlite::wallet::memory; use lightning_invoice::{Currency, InvoiceBuilder, PaymentSecret}; @@ -29,28 +29,12 @@ async fn main() -> Result<(), Error> { // Create a new wallet let wallet = Wallet::new(mint_url, unit, Arc::new(localstore), seed, None)?; - // Request a mint quote from the wallet - let quote = wallet.mint_quote(amount, None).await?; - println!("Quote: {:#?}", quote); - - // Subscribe to updates on the mint quote state - let mut subscription = wallet - .subscribe(WalletSubscription::Bolt11MintQuoteState(vec![quote - .id - .clone()])) - .await; - - // Wait for the mint quote to be paid - while let Some(msg) = subscription.recv().await { - if let NotificationPayload::MintQuoteBolt11Response(response) = msg { - if response.state == MintQuoteState::Paid { - break; - } - } - } + let (_invoice_to_pay, proofs) = wallet + .mint_once_paid(amount, None, Duration::from_secs(10)) + .await?; // Mint the received amount - let proofs = wallet.mint("e.id, SplitTarget::default(), None).await?; + let proofs = proofs.await?; let receive_amount = proofs.total_amount()?; println!("Received {} from mint {}", receive_amount, mint_url); diff --git a/crates/cdk/examples/mint-token.rs b/crates/cdk/examples/mint-token.rs index 92a3cc95e..64fe3d92a 100644 --- a/crates/cdk/examples/mint-token.rs +++ b/crates/cdk/examples/mint-token.rs @@ -1,10 +1,10 @@ use std::sync::Arc; +use std::time::Duration; -use cdk::amount::SplitTarget; use cdk::error::Error; use cdk::nuts::nut00::ProofsMethods; -use cdk::nuts::{CurrencyUnit, MintQuoteState, NotificationPayload}; -use cdk::wallet::{SendOptions, Wallet, WalletSubscription}; +use cdk::nuts::CurrencyUnit; +use cdk::wallet::{SendOptions, Wallet}; use cdk::Amount; use cdk_sqlite::wallet::memory; use rand::random; @@ -35,28 +35,12 @@ async fn main() -> Result<(), Error> { // Create a new wallet let wallet = Wallet::new(mint_url, unit, localstore, seed, None)?; - // Request a mint quote from the wallet - let quote = wallet.mint_quote(amount, None).await?; - println!("Quote: {:#?}", quote); - - // Subscribe to updates on the mint quote state - let mut subscription = wallet - .subscribe(WalletSubscription::Bolt11MintQuoteState(vec![quote - .id - .clone()])) - .await; - - // Wait for the mint quote to be paid - while let Some(msg) = subscription.recv().await { - if let NotificationPayload::MintQuoteBolt11Response(response) = msg { - if response.state == MintQuoteState::Paid { - break; - } - } - } + let (_invoice_to_pay, proofs) = wallet + .mint_once_paid(amount, None, Duration::from_secs(10)) + .await?; // Mint the received amount - let proofs = wallet.mint("e.id, SplitTarget::default(), None).await?; + let proofs = proofs.await?; let receive_amount = proofs.total_amount()?; println!("Received {} from mint {}", receive_amount, mint_url); diff --git a/crates/cdk/examples/p2pk.rs b/crates/cdk/examples/p2pk.rs index 7b7150a00..eaf56fbbb 100644 --- a/crates/cdk/examples/p2pk.rs +++ b/crates/cdk/examples/p2pk.rs @@ -1,9 +1,9 @@ use std::sync::Arc; +use std::time::Duration; -use cdk::amount::SplitTarget; use cdk::error::Error; -use cdk::nuts::{CurrencyUnit, MintQuoteState, NotificationPayload, SecretKey, SpendingConditions}; -use cdk::wallet::{ReceiveOptions, SendOptions, Wallet, WalletSubscription}; +use cdk::nuts::{CurrencyUnit, SecretKey, SpendingConditions}; +use cdk::wallet::{ReceiveOptions, SendOptions, Wallet}; use cdk::Amount; use cdk_sqlite::wallet::memory; use rand::random; @@ -34,29 +34,12 @@ async fn main() -> Result<(), Error> { // Create a new wallet let wallet = Wallet::new(mint_url, unit, localstore, seed, None).unwrap(); - // Request a mint quote from the wallet - let quote = wallet.mint_quote(amount, None).await?; - - println!("Minting nuts ..."); - - // Subscribe to updates on the mint quote state - let mut subscription = wallet - .subscribe(WalletSubscription::Bolt11MintQuoteState(vec![quote - .id - .clone()])) - .await; - - // Wait for the mint quote to be paid - while let Some(msg) = subscription.recv().await { - if let NotificationPayload::MintQuoteBolt11Response(response) = msg { - if response.state == MintQuoteState::Paid { - break; - } - } - } + let (_invoice_to_pay, proofs) = wallet + .mint_once_paid(amount, None, Duration::from_secs(10)) + .await?; // Mint the received amount - let received_proofs = wallet.mint("e.id, SplitTarget::default(), None).await?; + let received_proofs = proofs.await?; println!( "Minted nuts: {:?}", received_proofs diff --git a/crates/cdk/examples/proof-selection.rs b/crates/cdk/examples/proof-selection.rs index 73ae18ce9..053692910 100644 --- a/crates/cdk/examples/proof-selection.rs +++ b/crates/cdk/examples/proof-selection.rs @@ -2,11 +2,11 @@ use std::collections::HashMap; use std::sync::Arc; +use std::time::Duration; -use cdk::amount::SplitTarget; use cdk::nuts::nut00::ProofsMethods; -use cdk::nuts::{CurrencyUnit, MintQuoteState, NotificationPayload}; -use cdk::wallet::{Wallet, WalletSubscription}; +use cdk::nuts::CurrencyUnit; +use cdk::wallet::Wallet; use cdk::Amount; use cdk_common::nut02::KeySetInfosMethods; use cdk_sqlite::wallet::memory; @@ -31,28 +31,12 @@ async fn main() -> Result<(), Box> { for amount in [64] { let amount = Amount::from(amount); - // Request a mint quote from the wallet - let quote = wallet.mint_quote(amount, None).await?; - println!("Pay request: {}", quote.request); - - // Subscribe to the wallet for updates on the mint quote state - let mut subscription = wallet - .subscribe(WalletSubscription::Bolt11MintQuoteState(vec![quote - .id - .clone()])) - .await; - - // Wait for the mint quote to be paid - while let Some(msg) = subscription.recv().await { - if let NotificationPayload::MintQuoteBolt11Response(response) = msg { - if response.state == MintQuoteState::Paid { - break; - } - } - } + let (_invoice_to_pay, proofs) = wallet + .mint_once_paid(amount, None, Duration::from_secs(10)) + .await?; // Mint the received amount - let proofs = wallet.mint("e.id, SplitTarget::default(), None).await?; + let proofs = proofs.await?; let receive_amount = proofs.total_amount()?; println!("Minted {}", receive_amount); } diff --git a/crates/cdk/examples/wallet.rs b/crates/cdk/examples/wallet.rs index 37ea2e3e9..3d036c6c8 100644 --- a/crates/cdk/examples/wallet.rs +++ b/crates/cdk/examples/wallet.rs @@ -1,14 +1,12 @@ use std::sync::Arc; use std::time::Duration; -use cdk::amount::SplitTarget; use cdk::nuts::nut00::ProofsMethods; -use cdk::nuts::{CurrencyUnit, MintQuoteState}; +use cdk::nuts::CurrencyUnit; use cdk::wallet::{SendOptions, Wallet}; use cdk::Amount; use cdk_sqlite::wallet::memory; use rand::random; -use tokio::time::sleep; #[tokio::main] async fn main() -> Result<(), Box> { @@ -26,34 +24,12 @@ async fn main() -> Result<(), Box> { // Create a new wallet let wallet = Wallet::new(mint_url, unit, localstore, seed, None)?; - // Request a mint quote from the wallet - let quote = wallet.mint_quote(amount, None).await?; - - println!("Pay request: {}", quote.request); - - // Check the quote state in a loop with a timeout - let timeout = Duration::from_secs(60); // Set a timeout duration - let start = std::time::Instant::now(); - - loop { - let status = wallet.mint_quote_state("e.id).await?; - - if status.state == MintQuoteState::Paid { - break; - } - - if start.elapsed() >= timeout { - eprintln!("Timeout while waiting for mint quote to be paid"); - return Err("Timeout while waiting for mint quote to be paid".into()); - } - - println!("Quote state: {}", status.state); - - sleep(Duration::from_secs(5)).await; - } + let (_invoice_to_pay, proofs) = wallet + .mint_once_paid(amount, None, Duration::from_secs(10)) + .await?; // Mint the received amount - let proofs = wallet.mint("e.id, SplitTarget::default(), None).await?; + let proofs = proofs.await?; let receive_amount = proofs.total_amount()?; println!("Minted {}", receive_amount); diff --git a/crates/cdk/src/wallet/mod.rs b/crates/cdk/src/wallet/mod.rs index e683eaa74..f02079010 100644 --- a/crates/cdk/src/wallet/mod.rs +++ b/crates/cdk/src/wallet/mod.rs @@ -45,6 +45,7 @@ pub mod subscription; mod swap; mod transactions; pub mod util; +mod wait; #[cfg(feature = "auth")] pub use auth::{AuthMintConnector, AuthWallet}; diff --git a/crates/cdk/src/wallet/wait.rs b/crates/cdk/src/wallet/wait.rs new file mode 100644 index 000000000..0774e1697 --- /dev/null +++ b/crates/cdk/src/wallet/wait.rs @@ -0,0 +1,138 @@ +use std::future::Future; + +use cdk_common::amount::SplitTarget; +use cdk_common::wallet::{MeltQuote, MintQuote}; +use cdk_common::{ + Amount, Error, MeltQuoteState, MintQuoteState, NotificationPayload, Proofs, SpendingConditions, +}; +use futures::future::BoxFuture; +use tokio::time::{timeout, Duration}; + +use super::{Wallet, WalletSubscription}; + +#[allow(private_bounds)] +enum WaitableEvent { + MeltQuote(String), + MintQuote(String), +} + +impl From<&MeltQuote> for WaitableEvent { + fn from(event: &MeltQuote) -> Self { + WaitableEvent::MeltQuote(event.id.to_owned()) + } +} + +impl From<&MintQuote> for WaitableEvent { + fn from(event: &MintQuote) -> Self { + WaitableEvent::MintQuote(event.id.to_owned()) + } +} + +impl From for WalletSubscription { + fn from(val: WaitableEvent) -> Self { + match val { + WaitableEvent::MeltQuote(quote_id) => { + WalletSubscription::Bolt11MeltQuoteState(vec![quote_id]) + } + WaitableEvent::MintQuote(quote_id) => { + WalletSubscription::Bolt11MintQuoteState(vec![quote_id]) + } + } + } +} + +impl Wallet { + #[inline(always)] + async fn wait_and_mint_quote( + &self, + quote: MintQuote, + amount_split_target: SplitTarget, + spending_conditions: Option, + timeout_duration: Duration, + ) -> Result { + self.wait_for_payment("e, timeout_duration).await?; + self.mint("e.id, amount_split_target, spending_conditions) + .await + } + + /// Mints an amount and returns the invoice to be paid, and a BoxFuture that will finalize the + /// mint once the invoice has been paid + pub async fn mint_once_paid( + &self, + amount: Amount, + description: Option, + timeout_duration: Duration, + ) -> Result<(String, impl Future> + '_), Error> { + self.mint_once_paid_ex( + amount, + description, + Default::default(), + None, + timeout_duration, + ) + .await + } + + /// Similar function to mint_once_paid but with no default options + pub async fn mint_once_paid_ex( + &self, + amount: Amount, + description: Option, + amount_split_target: SplitTarget, + spending_conditions: Option, + timeout_duration: Duration, + ) -> Result<(String, impl Future> + '_), Error> { + let quote = self.mint_quote(amount, description).await?; + + Ok(( + quote.request.clone(), + self.wait_and_mint_quote( + quote, + amount_split_target, + spending_conditions, + timeout_duration, + ), + )) + } + + /// Returns a BoxFuture that will wait for payment on the given event with a timeout check + #[allow(private_bounds)] + pub fn wait_for_payment( + &self, + event: T, + timeout_duration: Duration, + ) -> BoxFuture<'_, Result<(), Error>> + where + T: Into, + { + let subs = self.subscribe::(event.into().into()); + + Box::pin(async move { + timeout(timeout_duration, async { + let mut subscription = subs.await; + loop { + match subscription.recv().await.ok_or(Error::Internal)? { + NotificationPayload::MintQuoteBolt11Response(info) => { + if info.state == MintQuoteState::Paid { + return Ok(()); + } + } + NotificationPayload::MintQuoteBolt12Response(info) => { + if info.amount_paid > Amount::ZERO { + return Ok(()); + } + } + NotificationPayload::MeltQuoteBolt11Response(info) => { + if info.state == MeltQuoteState::Paid { + return Ok(()); + } + } + _ => {} + } + } + }) + .await + .map_err(|_| Error::Timeout)? + }) + } +} From 22926f8b21eb68359366e0e6bbbb3f1e897cb6d3 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Mon, 18 Aug 2025 14:46:18 +0100 Subject: [PATCH 082/321] fix: bolt12 ws on mint (#972) * fix: bolt12 ws on mint * fix: bolt12 ws on mint --- crates/cdk/src/mint/issue/mod.rs | 36 ++++++++++++++++++--- crates/cdk/src/mint/ln.rs | 24 ++++++++++++-- crates/cdk/src/mint/mod.rs | 17 +++++++++- crates/cdk/src/mint/subscription/manager.rs | 19 ++++++++++- 4 files changed, 87 insertions(+), 9 deletions(-) diff --git a/crates/cdk/src/mint/issue/mod.rs b/crates/cdk/src/mint/issue/mod.rs index 1d46b41f2..1f37d568e 100644 --- a/crates/cdk/src/mint/issue/mod.rs +++ b/crates/cdk/src/mint/issue/mod.rs @@ -433,8 +433,22 @@ impl Mint { ) .await?; - self.pubsub_manager - .mint_quote_bolt11_status(mint_quote.clone(), MintQuoteState::Paid); + match mint_quote.payment_method { + PaymentMethod::Bolt11 => { + self.pubsub_manager + .mint_quote_bolt11_status(mint_quote.clone(), MintQuoteState::Paid); + } + PaymentMethod::Bolt12 => { + self.pubsub_manager.mint_quote_bolt12_status( + mint_quote.clone(), + wait_payment_response.payment_amount, + Amount::ZERO, + ); + } + _ => { + // We don't send ws updates for unknown methods + } + } } } else { tracing::info!("Received payment notification for already seen payment."); @@ -603,8 +617,22 @@ impl Mint { tx.commit().await?; - self.pubsub_manager - .mint_quote_bolt11_status(mint_quote, MintQuoteState::Issued); + match mint_quote.payment_method { + PaymentMethod::Bolt11 => { + self.pubsub_manager + .mint_quote_bolt11_status(mint_quote.clone(), MintQuoteState::Issued); + } + PaymentMethod::Bolt12 => { + self.pubsub_manager.mint_quote_bolt12_status( + mint_quote.clone(), + Amount::ZERO, + mint_request.total_amount()?, + ); + } + PaymentMethod::Custom(_) => { + // We don't send ws updates for unknown methods + } + } Ok(MintResponse { signatures: blind_signatures, diff --git a/crates/cdk/src/mint/ln.rs b/crates/cdk/src/mint/ln.rs index 281638d1a..901ed1a54 100644 --- a/crates/cdk/src/mint/ln.rs +++ b/crates/cdk/src/mint/ln.rs @@ -2,7 +2,7 @@ use cdk_common::amount::to_unit; use cdk_common::common::PaymentProcessorKey; use cdk_common::mint::MintQuote; use cdk_common::util::unix_time; -use cdk_common::{MintQuoteState, PaymentMethod}; +use cdk_common::{Amount, MintQuoteState, PaymentMethod}; use tracing::instrument; use super::Mint; @@ -39,6 +39,10 @@ impl Mint { .check_incoming_payment_status("e.request_lookup_id) .await?; + if ln_status.is_empty() { + return Ok(()); + } + let mut tx = self.localstore.begin_transaction().await?; for payment in ln_status { @@ -52,8 +56,22 @@ impl Mint { tx.increment_mint_quote_amount_paid("e.id, amount_paid, payment.payment_id) .await?; - self.pubsub_manager - .mint_quote_bolt11_status(quote.clone(), MintQuoteState::Paid); + match quote.payment_method { + PaymentMethod::Bolt11 => { + self.pubsub_manager + .mint_quote_bolt11_status(quote.clone(), MintQuoteState::Paid); + } + PaymentMethod::Bolt12 => { + self.pubsub_manager.mint_quote_bolt12_status( + quote.clone(), + amount_paid, + Amount::ZERO, + ); + } + PaymentMethod::Custom(_) => { + // We don't send ws updates for unknown methods + } + } } } diff --git a/crates/cdk/src/mint/mod.rs b/crates/cdk/src/mint/mod.rs index ed0752b09..0acc5cbe8 100644 --- a/crates/cdk/src/mint/mod.rs +++ b/crates/cdk/src/mint/mod.rs @@ -571,7 +571,22 @@ impl Mint { ) .await?; - pubsub_manager.mint_quote_bolt11_status(mint_quote.clone(), MintQuoteState::Paid); + match mint_quote.payment_method { + PaymentMethod::Bolt11 => { + pubsub_manager + .mint_quote_bolt11_status(mint_quote.clone(), MintQuoteState::Paid); + } + PaymentMethod::Bolt12 => { + pubsub_manager.mint_quote_bolt12_status( + mint_quote.clone(), + wait_payment_response.payment_amount, + Amount::ZERO, + ); + } + _ => { + // We don't send ws updates for unknown methods + } + } } } else { tracing::info!("Received payment notification for already seen payment."); diff --git a/crates/cdk/src/mint/subscription/manager.rs b/crates/cdk/src/mint/subscription/manager.rs index 345b94fbb..7b1b693fb 100644 --- a/crates/cdk/src/mint/subscription/manager.rs +++ b/crates/cdk/src/mint/subscription/manager.rs @@ -4,7 +4,7 @@ use std::sync::Arc; use cdk_common::database::{self, MintDatabase}; use cdk_common::nut17::Notification; -use cdk_common::NotificationPayload; +use cdk_common::{Amount, MintQuoteBolt12Response, NotificationPayload}; use uuid::Uuid; use super::OnSubscription; @@ -60,6 +60,23 @@ impl PubSubManager { self.broadcast(event.into()); } + /// Helper function to emit a MintQuoteBolt11Response status + pub fn mint_quote_bolt12_status>>( + &self, + quote: E, + amount_paid: Amount, + amount_issued: Amount, + ) { + if let Ok(mut event) = quote.try_into() { + event.amount_paid += amount_paid; + event.amount_issued += amount_issued; + + self.broadcast(event.into()); + } else { + tracing::warn!("Could not convert quote to MintQuoteResponse"); + } + } + /// Helper function to emit a MeltQuoteBolt11Response status pub fn melt_quote_status>>( &self, From 0a8a0a6ea5b343ef77065295a531fbd14cbbbdd0 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Mon, 18 Aug 2025 16:17:57 +0100 Subject: [PATCH 083/321] Repay fake queue (#973) * feat: implement secondary repayment queue for any-amount invoices - Keep original immediate payment behavior for ALL invoices (fixed and any-amount) - Add secondary repayment queue that randomly repays any-amount invoices again - Secondary repayments occur at random intervals between 30 seconds and 3 minutes - Only any-amount invoices (amount=0) are added to secondary repayment queue - Each any-amount invoice gets paid twice: once immediately, once from secondary queue - Queue has configurable max size with LRU eviction policy - Add comprehensive tests and update documentation * test: add test for multiple payment verification - Add test to verify that secondary repayment system creates multiple payments - Test checks that immediate payment is received first - Demonstrates the dual payment system working correctly --- crates/cdk-fake-wallet/src/lib.rs | 224 +++++++++++++++++++++++++++--- crates/cdk/src/mint/mod.rs | 1 + 2 files changed, 203 insertions(+), 22 deletions(-) diff --git a/crates/cdk-fake-wallet/src/lib.rs b/crates/cdk-fake-wallet/src/lib.rs index 9d4f65976..90abdce43 100644 --- a/crates/cdk-fake-wallet/src/lib.rs +++ b/crates/cdk-fake-wallet/src/lib.rs @@ -1,20 +1,26 @@ //! CDK Fake LN Backend //! -//! Used for testing where quotes are auto filled +//! Used for testing where quotes are auto filled. +//! +//! The fake wallet now includes a secondary repayment system that continuously repays any-amount +//! invoices (amount = 0) at random intervals between 30 seconds and 3 minutes to simulate +//! real-world behavior where invoices might get multiple payments. Payments continue to be +//! processed until they are evicted from the queue when the queue reaches its maximum size +//! (default 100 items). This is in addition to the original immediate payment processing +//! which is maintained for all invoice types. #![doc = include_str!("../README.md")] #![warn(missing_docs)] #![warn(rustdoc::bare_urls)] use std::cmp::max; -use std::collections::{HashMap, HashSet}; +use std::collections::{HashMap, HashSet, VecDeque}; use std::pin::Pin; use std::sync::atomic::{AtomicBool, Ordering}; use std::sync::Arc; use async_trait::async_trait; use bitcoin::hashes::{sha256, Hash}; -use bitcoin::secp256k1::rand::{thread_rng, Rng}; use bitcoin::secp256k1::{Secp256k1, SecretKey}; use cdk_common::amount::{to_unit, Amount}; use cdk_common::common::FeeReserve; @@ -40,14 +46,144 @@ use tracing::instrument; pub mod error; +/// Default maximum size for the secondary repayment queue +const DEFAULT_REPAY_QUEUE_MAX_SIZE: usize = 100; + +/// Secondary repayment queue manager for any-amount invoices +#[derive(Debug, Clone)] +struct SecondaryRepaymentQueue { + queue: Arc>>, + max_size: usize, + sender: tokio::sync::mpsc::Sender<(PaymentIdentifier, Amount, String)>, +} + +impl SecondaryRepaymentQueue { + fn new( + max_size: usize, + sender: tokio::sync::mpsc::Sender<(PaymentIdentifier, Amount, String)>, + ) -> Self { + let queue = Arc::new(Mutex::new(VecDeque::new())); + let repayment_queue = Self { + queue: queue.clone(), + max_size, + sender, + }; + + // Start the background secondary repayment processor + repayment_queue.start_secondary_repayment_processor(); + + repayment_queue + } + + /// Add a payment to the secondary repayment queue + async fn enqueue_for_repayment(&self, payment: PaymentIdentifier) { + let mut queue = self.queue.lock().await; + + // If queue is at max capacity, remove the oldest item + if queue.len() >= self.max_size { + if let Some(dropped) = queue.pop_front() { + tracing::debug!( + "Secondary repayment queue at capacity, dropping oldest payment: {:?}", + dropped + ); + } + } + + queue.push_back(payment); + tracing::debug!( + "Added payment to secondary repayment queue, current size: {}", + queue.len() + ); + } + + /// Start the background task that randomly processes secondary repayments from the queue + fn start_secondary_repayment_processor(&self) { + let queue = self.queue.clone(); + let sender = self.sender.clone(); + + tokio::spawn(async move { + use bitcoin::secp256k1::rand::rngs::OsRng; + use bitcoin::secp256k1::rand::Rng; + let mut rng = OsRng; + + loop { + // Wait for a random interval between 30 seconds and 3 minutes (180 seconds) + let delay_secs = rng.gen_range(30..=180); + time::sleep(time::Duration::from_secs(delay_secs)).await; + + // Try to process a random payment from the queue without removing it + let payment_to_process = { + let q = queue.lock().await; + if q.is_empty() { + None + } else { + // Pick a random index from the queue but don't remove it + let index = rng.gen_range(0..q.len()); + q.get(index).cloned() + } + }; + + if let Some(payment) = payment_to_process { + // Generate a random amount for this secondary payment (same range as initial payment: 1-1000) + let random_amount: u64 = rng.gen_range(1..=1000); + let secondary_amount = Amount::from(random_amount); + + // Generate a unique payment identifier for this secondary payment + // We'll create a new payment hash by appending a timestamp and random bytes + use bitcoin::hashes::{sha256, Hash}; + let mut random_bytes = [0u8; 16]; + rng.fill(&mut random_bytes); + let timestamp = std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .unwrap() + .as_nanos() as u64; + + // Create a unique hash combining the original payment identifier, timestamp, and random bytes + let mut hasher_input = Vec::new(); + hasher_input.extend_from_slice(payment.to_string().as_bytes()); + hasher_input.extend_from_slice(×tamp.to_le_bytes()); + hasher_input.extend_from_slice(&random_bytes); + + let unique_hash = sha256::Hash::hash(&hasher_input); + let unique_payment_id = PaymentIdentifier::PaymentHash(*unique_hash.as_ref()); + + tracing::info!( + "Processing secondary repayment: original={:?}, new_id={:?}, amount={}", + payment, + unique_payment_id, + secondary_amount + ); + + // Send the payment notification using the original payment identifier + // The mint will process this through the normal payment stream + if let Err(e) = sender + .send(( + payment.clone(), + secondary_amount, + unique_payment_id.to_string(), + )) + .await + { + tracing::error!( + "Failed to send secondary repayment notification for {:?}: {}", + unique_payment_id, + e + ); + } + } + } + }); + } +} + /// Fake Wallet #[derive(Clone)] pub struct FakeWallet { fee_reserve: FeeReserve, #[allow(clippy::type_complexity)] - sender: tokio::sync::mpsc::Sender<(PaymentIdentifier, Amount)>, + sender: tokio::sync::mpsc::Sender<(PaymentIdentifier, Amount, String)>, #[allow(clippy::type_complexity)] - receiver: Arc>>>, + receiver: Arc>>>, payment_states: Arc>>, failed_payment_check: Arc>>, payment_delay: u64, @@ -55,6 +191,7 @@ pub struct FakeWallet { wait_invoice_is_active: Arc, incoming_payments: Arc>>>, unit: CurrencyUnit, + secondary_repayment_queue: SecondaryRepaymentQueue, } impl FakeWallet { @@ -65,8 +202,31 @@ impl FakeWallet { fail_payment_check: HashSet, payment_delay: u64, unit: CurrencyUnit, + ) -> Self { + Self::new_with_repay_queue_size( + fee_reserve, + payment_states, + fail_payment_check, + payment_delay, + unit, + DEFAULT_REPAY_QUEUE_MAX_SIZE, + ) + } + + /// Create new [`FakeWallet`] with custom secondary repayment queue size + pub fn new_with_repay_queue_size( + fee_reserve: FeeReserve, + payment_states: HashMap, + fail_payment_check: HashSet, + payment_delay: u64, + unit: CurrencyUnit, + repay_queue_max_size: usize, ) -> Self { let (sender, receiver) = tokio::sync::mpsc::channel(8); + let incoming_payments = Arc::new(RwLock::new(HashMap::new())); + + let secondary_repayment_queue = + SecondaryRepaymentQueue::new(repay_queue_max_size, sender.clone()); Self { fee_reserve, @@ -77,8 +237,9 @@ impl FakeWallet { payment_delay, wait_invoice_cancel_token: CancellationToken::new(), wait_invoice_is_active: Arc::new(AtomicBool::new(false)), - incoming_payments: Arc::new(RwLock::new(HashMap::new())), + incoming_payments, unit, + secondary_repayment_queue, } } } @@ -147,11 +308,11 @@ impl MintPayment for FakeWallet { let unit = self.unit.clone(); let receiver_stream = ReceiverStream::new(receiver); Ok(Box::pin(receiver_stream.map( - move |(request_lookup_id, payment_amount)| WaitPaymentResponse { + move |(request_lookup_id, payment_amount, payment_id)| WaitPaymentResponse { payment_identifier: request_lookup_id.clone(), payment_amount, unit: unit.clone(), - payment_id: request_lookup_id.to_string(), + payment_id, }, ))) } @@ -331,7 +492,7 @@ impl MintPayment for FakeWallet { let amount = bolt12_options.amount; let expiry = bolt12_options.unix_expiry; - let secret_key = SecretKey::new(&mut thread_rng()); + let secret_key = SecretKey::new(&mut bitcoin::secp256k1::rand::rngs::OsRng); let secp_ctx = Secp256k1::new(); let offer_builder = OfferBuilder::new(secret_key.public_key(&secp_ctx)) @@ -377,24 +538,25 @@ impl MintPayment for FakeWallet { } }; + // ALL invoices get immediate payment processing (original behavior) let sender = self.sender.clone(); let duration = time::Duration::from_secs(self.payment_delay); + let payment_hash_clone = payment_hash.clone(); + let incoming_payment = self.incoming_payments.clone(); + let unit_clone = self.unit.clone(); let final_amount = if amount == Amount::ZERO { - let mut rng = thread_rng(); - // Generate a random number between 1 and 1000 (inclusive) - let random_number: u64 = rng.gen_range(1..=1000); - random_number.into() + // For any-amount invoices, generate a random amount for the initial payment + use bitcoin::secp256k1::rand::rngs::OsRng; + use bitcoin::secp256k1::rand::Rng; + let mut rng = OsRng; + let random_amount: u64 = rng.gen_range(1..=1000); + random_amount.into() } else { amount }; - let payment_hash_clone = payment_hash.clone(); - - let incoming_payment = self.incoming_payments.clone(); - - let unit = self.unit.clone(); - + // Schedule the immediate payment (original behavior maintained) tokio::spawn(async move { // Wait for the random delay to elapse time::sleep(duration).await; @@ -402,7 +564,7 @@ impl MintPayment for FakeWallet { let response = WaitPaymentResponse { payment_identifier: payment_hash_clone.clone(), payment_amount: final_amount, - unit, + unit: unit_clone, payment_id: payment_hash_clone.to_string(), }; let mut incoming = incoming_payment.write().await; @@ -413,7 +575,11 @@ impl MintPayment for FakeWallet { // Send the message after waiting for the specified duration if sender - .send((payment_hash_clone.clone(), final_amount)) + .send(( + payment_hash_clone.clone(), + final_amount, + payment_hash_clone.to_string(), + )) .await .is_err() { @@ -421,6 +587,18 @@ impl MintPayment for FakeWallet { } }); + // For any-amount invoices ONLY, also add to the secondary repayment queue + if amount == Amount::ZERO { + tracing::info!( + "Adding any-amount invoice to secondary repayment queue: {:?}", + payment_hash + ); + + self.secondary_repayment_queue + .enqueue_for_repayment(payment_hash.clone()) + .await; + } + Ok(CreateIncomingPaymentResponse { request_lookup_id: payment_hash, request, @@ -481,7 +659,9 @@ pub fn create_fake_invoice(amount_msat: u64, description: String) -> Bolt11Invoi ) .unwrap(); - let mut rng = thread_rng(); + use bitcoin::secp256k1::rand::rngs::OsRng; + use bitcoin::secp256k1::rand::Rng; + let mut rng = OsRng; let mut random_bytes = [0u8; 32]; rng.fill(&mut random_bytes); diff --git a/crates/cdk/src/mint/mod.rs b/crates/cdk/src/mint/mod.rs index 0acc5cbe8..17c04fa23 100644 --- a/crates/cdk/src/mint/mod.rs +++ b/crates/cdk/src/mint/mod.rs @@ -541,6 +541,7 @@ impl Mint { } /// Handle payment for a specific mint quote (extracted from pay_mint_quote) + #[instrument(skip_all)] async fn handle_mint_quote_payment( tx: &mut Box + Send + Sync + '_>, mint_quote: &MintQuote, From 2e424e629f85739a6e9e0e45de54b7a568c5c179 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Mon, 18 Aug 2025 16:25:24 +0100 Subject: [PATCH 084/321] feat: uuid version (#891) * feat: uuid version * feat: rustls version --- Cargo.toml | 4 ++-- crates/cashu/Cargo.toml | 1 + crates/cdk-axum/Cargo.toml | 3 +++ crates/cdk-cln/Cargo.toml | 3 +++ crates/cdk-common/Cargo.toml | 1 + crates/cdk-integration-tests/Cargo.toml | 1 + crates/cdk-payment-processor/Cargo.toml | 1 + crates/cdk-redb/Cargo.toml | 3 +++ crates/cdk-sqlite/Cargo.toml | 3 +++ crates/cdk/Cargo.toml | 1 + 10 files changed, 19 insertions(+), 2 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index e58db5d3f..543e2a2f7 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -75,7 +75,7 @@ tokio-stream = "0.1.15" tracing = { version = "0.1", default-features = false, features = ["attributes", "log"] } tracing-subscriber = { version = "0.3.18", features = ["env-filter"] } url = "2.3" -uuid = { version = "=1.12.1", features = ["v4", "serde"] } +uuid = { version = "1.17", features = ["v4", "serde"] } utoipa = { version = "5.3.1", features = [ "preserve_order", "preserve_path_order", @@ -101,7 +101,7 @@ prost = "0.13.1" tonic-build = "0.13.1" strum = "0.27.1" strum_macros = "0.27.1" -rustls = { version = "0.23.28", default-features = false, features = ["ring"] } +rustls = { version = "0.23.27", default-features = false, features = ["ring"] } diff --git a/crates/cashu/Cargo.toml b/crates/cashu/Cargo.toml index efbc975ea..5a09dfcd8 100644 --- a/crates/cashu/Cargo.toml +++ b/crates/cashu/Cargo.toml @@ -39,6 +39,7 @@ strum_macros = { workspace = true, optional = true } [target.'cfg(target_arch = "wasm32")'.dependencies] instant = { workspace = true, features = ["wasm-bindgen", "inaccurate"] } +uuid = { workspace = true, features = ["js"], optional = true } [dev-dependencies] bip39.workspace = true diff --git a/crates/cdk-axum/Cargo.toml b/crates/cdk-axum/Cargo.toml index 76fd99f00..3bebf0bde 100644 --- a/crates/cdk-axum/Cargo.toml +++ b/crates/cdk-axum/Cargo.toml @@ -36,3 +36,6 @@ sha2 = "0.10.8" redis = { version = "0.31.0", features = [ "tokio-rustls-comp", ], optional = true } + +[target.'cfg(target_arch = "wasm32")'.dependencies] +uuid = { workspace = true, features = ["js"] } diff --git a/crates/cdk-cln/Cargo.toml b/crates/cdk-cln/Cargo.toml index e2d5a9d6a..c0a9b9748 100644 --- a/crates/cdk-cln/Cargo.toml +++ b/crates/cdk-cln/Cargo.toml @@ -22,3 +22,6 @@ tracing.workspace = true thiserror.workspace = true uuid.workspace = true serde_json.workspace = true + +[target.'cfg(target_arch = "wasm32")'.dependencies] +uuid = { workspace = true, features = ["js"] } diff --git a/crates/cdk-common/Cargo.toml b/crates/cdk-common/Cargo.toml index a6c1466a7..5afe10609 100644 --- a/crates/cdk-common/Cargo.toml +++ b/crates/cdk-common/Cargo.toml @@ -40,6 +40,7 @@ serde_with.workspace = true [target.'cfg(target_arch = "wasm32")'.dependencies] instant = { workspace = true, features = ["wasm-bindgen", "inaccurate"] } +uuid = { workspace = true, features = ["js"], optional = true } [dev-dependencies] rand.workspace = true diff --git a/crates/cdk-integration-tests/Cargo.toml b/crates/cdk-integration-tests/Cargo.toml index ceaf68384..9de43f58f 100644 --- a/crates/cdk-integration-tests/Cargo.toml +++ b/crates/cdk-integration-tests/Cargo.toml @@ -55,6 +55,7 @@ tokio.workspace = true tokio = { workspace = true, features = ["rt", "macros", "sync", "time"] } getrandom = { version = "0.2", features = ["js"] } instant = { workspace = true, features = ["wasm-bindgen", "inaccurate"] } +uuid = { workspace = true, features = ["js"] } [dev-dependencies] bip39 = { workspace = true, features = ["rand"] } diff --git a/crates/cdk-payment-processor/Cargo.toml b/crates/cdk-payment-processor/Cargo.toml index db7983520..c123705b9 100644 --- a/crates/cdk-payment-processor/Cargo.toml +++ b/crates/cdk-payment-processor/Cargo.toml @@ -61,6 +61,7 @@ tokio = { workspace = true, features = [ [target.'cfg(target_arch = "wasm32")'.dependencies] tokio = { workspace = true, features = ["rt", "macros", "sync", "time"] } +uuid = { workspace = true, features = ["js"], optional = true } [dev-dependencies] rand.workspace = true diff --git a/crates/cdk-redb/Cargo.toml b/crates/cdk-redb/Cargo.toml index f50b85115..7e12fd576 100644 --- a/crates/cdk-redb/Cargo.toml +++ b/crates/cdk-redb/Cargo.toml @@ -30,3 +30,6 @@ uuid.workspace = true [dev-dependencies] tempfile = "3.17.1" tokio.workspace = true + +[target.'cfg(target_arch = "wasm32")'.dependencies] +uuid = { workspace = true, features = ["js"] } diff --git a/crates/cdk-sqlite/Cargo.toml b/crates/cdk-sqlite/Cargo.toml index 264271dde..094005f70 100644 --- a/crates/cdk-sqlite/Cargo.toml +++ b/crates/cdk-sqlite/Cargo.toml @@ -31,3 +31,6 @@ serde.workspace = true serde_json.workspace = true lightning-invoice.workspace = true uuid.workspace = true + +[target.'cfg(target_arch = "wasm32")'.dependencies] +uuid = { workspace = true, features = ["js"] } diff --git a/crates/cdk/Cargo.toml b/crates/cdk/Cargo.toml index b00373e9b..8bcc70f1d 100644 --- a/crates/cdk/Cargo.toml +++ b/crates/cdk/Cargo.toml @@ -69,6 +69,7 @@ tokio = { workspace = true, features = ["rt", "macros", "sync", "time"] } cdk-signatory = { workspace = true, default-features = false } getrandom = { version = "0.2", features = ["js"] } ring = { version = "0.17.14", features = ["wasm32_unknown_unknown_js"] } +uuid = { workspace = true, features = ["js"] } [[example]] name = "mint-token" From 28a01398fd73a89e25aa5093a17d96c6080d24cb Mon Sep 17 00:00:00 2001 From: C Date: Mon, 18 Aug 2025 13:45:11 -0300 Subject: [PATCH 085/321] Add PostgreSQL support for mint and wallet (#878) * 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 --- .github/workflows/ci.yml | 3 + Cargo.toml | 1 + README.md | 1 + crates/cdk-common/src/database/mint/test.rs | 45 +++ .../src/bin/start_fake_auth_mint.rs | 3 + .../src/bin/start_fake_mint.rs | 11 +- crates/cdk-integration-tests/src/shared.rs | 7 +- crates/cdk-mintd/Cargo.toml | 1 + crates/cdk-mintd/README.md | 88 +++++- crates/cdk-mintd/example.config.toml | 17 +- crates/cdk-mintd/src/config.rs | 22 ++ crates/cdk-mintd/src/env_vars/common.rs | 1 + crates/cdk-mintd/src/env_vars/database.rs | 40 +++ crates/cdk-mintd/src/env_vars/mod.rs | 17 +- crates/cdk-mintd/src/lib.rs | 32 ++- crates/cdk-postgres/Cargo.toml | 35 +++ crates/cdk-postgres/src/db.rs | 155 +++++++++++ crates/cdk-postgres/src/lib.rs | 257 ++++++++++++++++++ crates/cdk-postgres/src/value.rs | 130 +++++++++ crates/cdk-postgres/start_db_for_test.sh | 30 ++ crates/cdk-sql-common/src/database.rs | 2 +- .../src/mint/auth/migrations.rs | 1 + .../mint/auth/migrations/postgres/1_init.sql | 43 +++ crates/cdk-sql-common/src/mint/auth/mod.rs | 3 +- crates/cdk-sql-common/src/mint/migrations.rs | 1 + .../mint/migrations/postgres/1_initial.sql | 100 +++++++ crates/cdk-sql-common/src/mint/mod.rs | 49 ++-- .../cdk-sql-common/src/wallet/migrations.rs | 1 + .../wallet/migrations/postgres/1_initial.sql | 80 ++++++ crates/cdk/src/mint/proof_writer.rs | 4 +- crates/cdk/src/wallet/melt/melt_bolt11.rs | 2 +- docker-compose.postgres.yaml | 52 ++++ docker-compose.yaml | 55 +++- misc/fake_itests.sh | 33 ++- 34 files changed, 1282 insertions(+), 40 deletions(-) create mode 100644 crates/cdk-mintd/src/env_vars/database.rs create mode 100644 crates/cdk-postgres/Cargo.toml create mode 100644 crates/cdk-postgres/src/db.rs create mode 100644 crates/cdk-postgres/src/lib.rs create mode 100644 crates/cdk-postgres/src/value.rs create mode 100644 crates/cdk-postgres/start_db_for_test.sh create mode 100644 crates/cdk-sql-common/src/mint/auth/migrations/postgres/1_init.sql create mode 100644 crates/cdk-sql-common/src/mint/migrations/postgres/1_initial.sql create mode 100644 crates/cdk-sql-common/src/wallet/migrations/postgres/1_initial.sql create mode 100644 docker-compose.postgres.yaml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 57e34d257..9c3b23791 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -160,6 +160,7 @@ jobs: database: [ SQLITE, + POSTGRES ] steps: - name: checkout @@ -262,6 +263,8 @@ jobs: shared-key: "stable" - name: Test fake mint run: nix develop -i -L .#stable --command just test-pure ${{ matrix.database }} + - name: Install Postgres + run: bash -x crates/cdk-postgres/start_db_for_test.sh - name: Test mint run: nix develop -i -L .#stable --command just test diff --git a/Cargo.toml b/Cargo.toml index 543e2a2f7..3dc2372bd 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -56,6 +56,7 @@ cdk-mint-rpc = { path = "./crates/cdk-mint-rpc", version = "=0.11.0" } cdk-redb = { path = "./crates/cdk-redb", default-features = true, version = "=0.11.0" } cdk-sql-common = { path = "./crates/cdk-sql-common", default-features = true, version = "=0.11.0" } cdk-sqlite = { path = "./crates/cdk-sqlite", default-features = true, version = "=0.11.0" } +cdk-postgres = { path = "./crates/cdk-postgres", default-features = true, version = "=0.11.0" } cdk-signatory = { path = "./crates/cdk-signatory", version = "=0.11.0", default-features = false } cdk-mintd = { path = "./crates/cdk-mintd", version = "=0.11.0", default-features = false } clap = { version = "4.5.31", features = ["derive"] } diff --git a/README.md b/README.md index f7ebae6d2..95dbe8aba 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,7 @@ The project is split up into several crates in the `crates/` directory: * Libraries: * [**cdk**](./crates/cdk/): Rust implementation of Cashu protocol. * [**cdk-sqlite**](./crates/cdk-sqlite/): SQLite Storage backend. + * [**cdk-postgres**](./crates/cdk-postgres/): PostgreSQL Storage backend. * [**cdk-redb**](./crates/cdk-redb/): Redb Storage backend. * [**cdk-axum**](./crates/cdk-axum/): Axum webserver for mint. * [**cdk-cln**](./crates/cdk-cln/): CLN Lightning backend for mint. diff --git a/crates/cdk-common/src/database/mint/test.rs b/crates/cdk-common/src/database/mint/test.rs index 7ad65e7ae..d8b69d083 100644 --- a/crates/cdk-common/src/database/mint/test.rs +++ b/crates/cdk-common/src/database/mint/test.rs @@ -78,11 +78,56 @@ where tx.commit().await.unwrap(); } +/// Test the basic storing and retrieving proofs from the database. Probably the database would use +/// binary/`Vec` to store data, that's why this test would quickly identify issues before running +/// other tests +pub async fn add_and_find_proofs(db: DB) +where + DB: Database + KeysDatabase, +{ + let keyset_id = setup_keyset(&db).await; + + let quote_id = Uuid::max(); + + let proofs = vec![ + Proof { + amount: Amount::from(100), + keyset_id, + secret: Secret::generate(), + c: SecretKey::generate().public_key(), + witness: None, + dleq: None, + }, + Proof { + amount: Amount::from(200), + keyset_id, + secret: Secret::generate(), + c: SecretKey::generate().public_key(), + witness: None, + dleq: None, + }, + ]; + + // Add proofs to database + let mut tx = Database::begin_transaction(&db).await.unwrap(); + tx.add_proofs(proofs.clone(), Some(quote_id)).await.unwrap(); + assert!(tx.commit().await.is_ok()); + + let proofs_from_db = db.get_proofs_by_ys(&[proofs[0].c, proofs[1].c]).await; + assert!(proofs_from_db.is_ok()); + assert_eq!(proofs_from_db.unwrap().len(), 2); + + let proofs_from_db = db.get_proof_ys_by_quote_id("e_id).await; + assert!(proofs_from_db.is_ok()); + assert_eq!(proofs_from_db.unwrap().len(), 2); +} + /// Unit test that is expected to be passed for a correct database implementation #[macro_export] macro_rules! mint_db_test { ($make_db_fn:ident) => { mint_db_test!(state_transition, $make_db_fn); + mint_db_test!(add_and_find_proofs, $make_db_fn); }; ($name:ident, $make_db_fn:ident) => { #[tokio::test] diff --git a/crates/cdk-integration-tests/src/bin/start_fake_auth_mint.rs b/crates/cdk-integration-tests/src/bin/start_fake_auth_mint.rs index 5846a53c0..b0c228810 100644 --- a/crates/cdk-integration-tests/src/bin/start_fake_auth_mint.rs +++ b/crates/cdk-integration-tests/src/bin/start_fake_auth_mint.rs @@ -45,6 +45,7 @@ struct Args { /// Start a fake mint with authentication using the library async fn start_fake_auth_mint( temp_dir: &Path, + database: &str, port: u16, openid_discovery: String, shutdown: Arc, @@ -62,6 +63,7 @@ async fn start_fake_auth_mint( let mut settings = shared::create_fake_wallet_settings( port, + database, Some(Mnemonic::generate(12)?.to_string()), None, Some(fake_wallet_config), @@ -123,6 +125,7 @@ async fn main() -> Result<()> { let handle = start_fake_auth_mint( &temp_dir, + &args.database_type, args.port, args.openid_discovery.clone(), shutdown_clone, diff --git a/crates/cdk-integration-tests/src/bin/start_fake_mint.rs b/crates/cdk-integration-tests/src/bin/start_fake_mint.rs index 2d1d490b7..d5bad2fee 100644 --- a/crates/cdk-integration-tests/src/bin/start_fake_mint.rs +++ b/crates/cdk-integration-tests/src/bin/start_fake_mint.rs @@ -46,6 +46,7 @@ struct Args { async fn start_fake_mint( temp_dir: &Path, port: u16, + database: &str, shutdown: Arc, external_signatory: bool, ) -> Result> { @@ -77,8 +78,13 @@ async fn start_fake_mint( }); // Create settings struct for fake mint using shared function - let settings = - shared::create_fake_wallet_settings(port, mnemonic, signatory_config, fake_wallet_config); + let settings = shared::create_fake_wallet_settings( + port, + database, + mnemonic, + signatory_config, + fake_wallet_config, + ); println!("Starting fake mintd on port {port}"); @@ -129,6 +135,7 @@ async fn main() -> Result<()> { let handle = start_fake_mint( &temp_dir, args.port, + &args.database_type, shutdown_clone, args.external_signatory, ) diff --git a/crates/cdk-integration-tests/src/shared.rs b/crates/cdk-integration-tests/src/shared.rs index 2657c1354..68d03e23c 100644 --- a/crates/cdk-integration-tests/src/shared.rs +++ b/crates/cdk-integration-tests/src/shared.rs @@ -11,6 +11,7 @@ use std::time::Duration; use anyhow::Result; use cdk_axum::cache; +use cdk_mintd::config::{Database, DatabaseEngine}; use tokio::signal; use tokio::sync::Notify; @@ -150,6 +151,7 @@ pub fn display_mint_info(port: u16, temp_dir: &Path, database_type: &str) { /// Create settings for a fake wallet mint pub fn create_fake_wallet_settings( port: u16, + database: &str, mnemonic: Option, signatory_config: Option<(String, String)>, // (url, certs_dir) fake_wallet_config: Option, @@ -182,7 +184,10 @@ pub fn create_fake_wallet_settings( lnd: None, fake_wallet: fake_wallet_config, grpc_processor: None, - database: cdk_mintd::config::Database::default(), + database: Database { + engine: DatabaseEngine::from_str(database).expect("valid database"), + postgres: None, + }, mint_management_rpc: None, auth: None, } diff --git a/crates/cdk-mintd/Cargo.toml b/crates/cdk-mintd/Cargo.toml index 47b9ee07a..ff95bcfd0 100644 --- a/crates/cdk-mintd/Cargo.toml +++ b/crates/cdk-mintd/Cargo.toml @@ -35,6 +35,7 @@ cdk = { workspace = true, features = [ cdk-sqlite = { workspace = true, features = [ "mint", ] } +cdk-postgres = { workspace = true, features = ["mint"]} cdk-cln = { workspace = true, optional = true } cdk-lnbits = { workspace = true, optional = true } cdk-lnd = { workspace = true, optional = true } diff --git a/crates/cdk-mintd/README.md b/crates/cdk-mintd/README.md index 4dfea02fd..95e28c343 100644 --- a/crates/cdk-mintd/README.md +++ b/crates/cdk-mintd/README.md @@ -6,7 +6,15 @@ **ALPHA** This library is in early development, the API will change and should be used with caution. -Cashu mint daemon implementation for the Cashu Development Kit (CDK). This binary provides a complete Cashu mint server implementation. +Cashu mint daemon implementation for the Cashu Development Kit (CDK). This binary provides a complete Cashu mint server implementation with support for multiple database backends and Lightning Network integrations. + +## Features + +- **Multiple Database Backends**: SQLite and PostgreSQL +- **Lightning Network Integration**: Support for CLN, LND, LNbits, and test backends +- **Authentication**: Optional user authentication with OpenID Connect +- **Management RPC**: gRPC interface for mint management +- **Docker Support**: Ready-to-use Docker configurations ## Installation @@ -20,9 +28,64 @@ From source: cargo install --path . ``` +## Quick Start + +### Using SQLite (Default) +```bash +# Start with SQLite (no additional setup required) +cdk-mintd +``` + +### Using PostgreSQL +```bash +# Set environment variables +export CDK_MINTD_DATABASE=postgres +export CDK_MINTD_DATABASE_URL="postgresql://postgres:password@localhost:5432/cdk_mint" + +# Start the mint +cdk-mintd +``` + +### Using Docker +```bash +# SQLite +docker-compose up + +# PostgreSQL +docker-compose -f docker-compose.postgres.yaml up +``` + ## Configuration -The mint can be configured through environment variables or a configuration file. See the documentation for available options. +The mint can be configured through environment variables or a configuration file. See `example.config.toml` for all available options. + +### Database Configuration + +#### SQLite (Default) +```toml +[database] +engine = "sqlite" +``` + +#### PostgreSQL +```toml +[database] +engine = "postgres" +``` +Set `CDK_MINTD_DATABASE_URL` environment variable for connection string. + +#### ReDB +```toml +[database] +engine = "redb" +``` + +### Lightning Backend Configuration + +```toml +[ln] +ln_backend = "fakewallet" # Options: cln, lnd, lnbits, fakewallet +``` ## Usage @@ -33,10 +96,29 @@ cdk-mintd # Start with custom config file cdk-mintd --config /path/to/config.toml +# Start with specific work directory +cdk-mintd --work-dir /path/to/work/dir + # Show help cdk-mintd --help ``` +## Environment Variables + +Key environment variables: + +- `CDK_MINTD_DATABASE`: Database engine (sqlite/postgres/redb) +- `CDK_MINTD_DATABASE_URL`: PostgreSQL connection string +- `CDK_MINTD_LN_BACKEND`: Lightning backend type +- `CDK_MINTD_LISTEN_HOST`: Host to bind to +- `CDK_MINTD_LISTEN_PORT`: Port to bind to + +## Documentation + +- [Configuration Examples](./example.config.toml) +- [PostgreSQL Setup Guide](../../POSTGRES.md) +- [Development Guide](../../DEVELOPMENT.md) + ## License -This project is licensed under the [MIT License](../../LICENSE). \ No newline at end of file +This project is licensed under the [MIT License](../../LICENSE). diff --git a/crates/cdk-mintd/example.config.toml b/crates/cdk-mintd/example.config.toml index 1e4d3c3e5..a5336559e 100644 --- a/crates/cdk-mintd/example.config.toml +++ b/crates/cdk-mintd/example.config.toml @@ -38,8 +38,21 @@ tti = 60 [database] -# Database engine (sqlite/redb) defaults to sqlite -# engine = "sqlite" +# Database engine (sqlite/postgres) defaults to sqlite +engine = "sqlite" + +# PostgreSQL configuration (when engine = "postgres") +[database.postgres] +# PostgreSQL connection URL +# Can also be set via CDK_MINTD_POSTGRES_URL or CDK_MINTD_DATABASE_URL environment variables +# Environment variables take precedence over config file settings +url = "postgresql://user:password@localhost:5432/cdk_mint" +# TLS mode: "disable", "prefer", "require" (optional, defaults to "disable") +tls_mode = "disable" +# Maximum number of connections in the pool (optional, defaults to 20) +max_connections = 20 +# Connection timeout in seconds (optional, defaults to 10) +connection_timeout_seconds = 10 [ln] # Required ln backend `cln`, `lnd`, `fakewallet`, 'lnbits' diff --git a/crates/cdk-mintd/src/config.rs b/crates/cdk-mintd/src/config.rs index bd245e722..24d1a4810 100644 --- a/crates/cdk-mintd/src/config.rs +++ b/crates/cdk-mintd/src/config.rs @@ -190,6 +190,7 @@ pub struct GrpcProcessor { pub enum DatabaseEngine { #[default] Sqlite, + Postgres, } impl std::str::FromStr for DatabaseEngine { @@ -198,6 +199,7 @@ impl std::str::FromStr for DatabaseEngine { fn from_str(s: &str) -> Result { match s.to_lowercase().as_str() { "sqlite" => Ok(DatabaseEngine::Sqlite), + "postgres" => Ok(DatabaseEngine::Postgres), _ => Err(format!("Unknown database engine: {s}")), } } @@ -206,6 +208,26 @@ impl std::str::FromStr for DatabaseEngine { #[derive(Debug, Clone, Serialize, Deserialize, Default)] pub struct Database { pub engine: DatabaseEngine, + pub postgres: Option, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct PostgresConfig { + pub url: String, + pub tls_mode: Option, + pub max_connections: Option, + pub connection_timeout_seconds: Option, +} + +impl Default for PostgresConfig { + fn default() -> Self { + Self { + url: String::new(), + tls_mode: Some("disable".to_string()), + max_connections: Some(20), + connection_timeout_seconds: Some(10), + } + } } #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)] diff --git a/crates/cdk-mintd/src/env_vars/common.rs b/crates/cdk-mintd/src/env_vars/common.rs index 27b1cee98..45d53e272 100644 --- a/crates/cdk-mintd/src/env_vars/common.rs +++ b/crates/cdk-mintd/src/env_vars/common.rs @@ -2,6 +2,7 @@ pub const ENV_WORK_DIR: &str = "CDK_MINTD_WORK_DIR"; pub const DATABASE_ENV_VAR: &str = "CDK_MINTD_DATABASE"; +pub const DATABASE_URL_ENV_VAR: &str = "CDK_MINTD_DATABASE_URL"; // Legacy, maintained for backward compatibility pub const ENV_URL: &str = "CDK_MINTD_URL"; pub const ENV_LISTEN_HOST: &str = "CDK_MINTD_LISTEN_HOST"; pub const ENV_LISTEN_PORT: &str = "CDK_MINTD_LISTEN_PORT"; diff --git a/crates/cdk-mintd/src/env_vars/database.rs b/crates/cdk-mintd/src/env_vars/database.rs new file mode 100644 index 000000000..5b9621c8f --- /dev/null +++ b/crates/cdk-mintd/src/env_vars/database.rs @@ -0,0 +1,40 @@ +//! Database environment variables + +use std::env; + +use crate::config::PostgresConfig; + +pub const ENV_POSTGRES_URL: &str = "CDK_MINTD_POSTGRES_URL"; +pub const ENV_POSTGRES_TLS_MODE: &str = "CDK_MINTD_POSTGRES_TLS_MODE"; +pub const ENV_POSTGRES_MAX_CONNECTIONS: &str = "CDK_MINTD_POSTGRES_MAX_CONNECTIONS"; +pub const ENV_POSTGRES_CONNECTION_TIMEOUT: &str = "CDK_MINTD_POSTGRES_CONNECTION_TIMEOUT_SECONDS"; + +impl PostgresConfig { + pub fn from_env(mut self) -> Self { + // Check for new PostgreSQL URL env var first, then fallback to legacy DATABASE_URL + if let Ok(url) = env::var(ENV_POSTGRES_URL) { + self.url = url; + } else if let Ok(url) = env::var(super::DATABASE_URL_ENV_VAR) { + // Backward compatibility with the existing DATABASE_URL env var + self.url = url; + } + + if let Ok(tls_mode) = env::var(ENV_POSTGRES_TLS_MODE) { + self.tls_mode = Some(tls_mode); + } + + if let Ok(max_connections) = env::var(ENV_POSTGRES_MAX_CONNECTIONS) { + if let Ok(parsed) = max_connections.parse::() { + self.max_connections = Some(parsed); + } + } + + if let Ok(timeout) = env::var(ENV_POSTGRES_CONNECTION_TIMEOUT) { + if let Ok(parsed) = timeout.parse::() { + self.connection_timeout_seconds = Some(parsed); + } + } + + self + } +} diff --git a/crates/cdk-mintd/src/env_vars/mod.rs b/crates/cdk-mintd/src/env_vars/mod.rs index aab0f3278..2d8c234b5 100644 --- a/crates/cdk-mintd/src/env_vars/mod.rs +++ b/crates/cdk-mintd/src/env_vars/mod.rs @@ -4,6 +4,7 @@ //! organized by component. mod common; +mod database; mod info; mod ln; mod mint_info; @@ -32,6 +33,7 @@ pub use auth::*; #[cfg(feature = "cln")] pub use cln::*; pub use common::*; +pub use database::*; #[cfg(feature = "fakewallet")] pub use fake_wallet::*; #[cfg(feature = "grpc-processor")] @@ -45,13 +47,24 @@ pub use lnd::*; pub use management_rpc::*; pub use mint_info::*; -use crate::config::{Database, DatabaseEngine, LnBackend, Settings}; +use crate::config::{DatabaseEngine, LnBackend, Settings}; impl Settings { pub fn from_env(&mut self) -> Result { if let Ok(database) = env::var(DATABASE_ENV_VAR) { let engine = DatabaseEngine::from_str(&database).map_err(|err| anyhow!(err))?; - self.database = Database { engine }; + self.database.engine = engine; + } + + // Parse PostgreSQL-specific configuration from environment variables + if self.database.engine == DatabaseEngine::Postgres { + self.database.postgres = Some( + self.database + .postgres + .clone() + .unwrap_or_default() + .from_env(), + ); } self.info = self.info.clone().from_env(); diff --git a/crates/cdk-mintd/src/lib.rs b/crates/cdk-mintd/src/lib.rs index f83a26eae..715b3cdb8 100644 --- a/crates/cdk-mintd/src/lib.rs +++ b/crates/cdk-mintd/src/lib.rs @@ -3,7 +3,7 @@ // std #[cfg(feature = "auth")] use std::collections::HashMap; -use std::env; +use std::env::{self}; use std::net::SocketAddr; use std::path::{Path, PathBuf}; use std::str::FromStr; @@ -39,6 +39,7 @@ use cdk::nuts::{AuthRequired, Method, ProtectedEndpoint, RoutePath}; use cdk::nuts::{ContactInfo, MintVersion, PaymentMethod}; use cdk::types::QuoteTTL; use cdk_axum::cache::HttpCache; +use cdk_postgres::{MintPgAuthDatabase, MintPgDatabase}; #[cfg(feature = "auth")] use cdk_sqlite::mint::MintSqliteAuthDatabase; use cdk_sqlite::MintSqliteDatabase; @@ -156,6 +157,23 @@ async fn setup_database( let keystore: Arc + Send + Sync> = db; Ok((localstore, keystore)) } + DatabaseEngine::Postgres => { + // Get the PostgreSQL configuration, ensuring it exists + let pg_config = settings.database.postgres.as_ref().ok_or_else(|| { + anyhow!("PostgreSQL configuration is required when using PostgreSQL engine") + })?; + + if pg_config.url.is_empty() { + bail!("PostgreSQL URL is required. Set it in config file [database.postgres] section or via CDK_MINTD_POSTGRES_URL/CDK_MINTD_DATABASE_URL environment variable"); + } + + let pg_db = Arc::new(MintPgDatabase::new(pg_config.url.as_str()).await?); + let localstore: Arc + Send + Sync> = + pg_db.clone(); + let keystore: Arc + Send + Sync> = + pg_db; + Ok((localstore, keystore)) + } } } @@ -454,6 +472,18 @@ async fn setup_authentication( Arc::new(sqlite_db) } + DatabaseEngine::Postgres => { + // Get the PostgreSQL configuration, ensuring it exists + let pg_config = settings.database.postgres.as_ref().ok_or_else(|| { + anyhow!("PostgreSQL configuration is required when using PostgreSQL engine") + })?; + + if pg_config.url.is_empty() { + bail!("PostgreSQL URL is required for auth database. Set it in config file [database.postgres] section or via CDK_MINTD_POSTGRES_URL/CDK_MINTD_DATABASE_URL environment variable"); + } + + Arc::new(MintPgAuthDatabase::new(pg_config.url.as_str()).await?) + } }; let mut protected_endpoints = HashMap::new(); diff --git a/crates/cdk-postgres/Cargo.toml b/crates/cdk-postgres/Cargo.toml new file mode 100644 index 000000000..cadcf2bd4 --- /dev/null +++ b/crates/cdk-postgres/Cargo.toml @@ -0,0 +1,35 @@ +[package] +name = "cdk-postgres" +version.workspace = true +edition.workspace = true +authors = ["CDK Developers"] +description = "PostgreSQL storage backend for CDK" +license.workspace = true +homepage = "https://github.com/cashubtc/cdk" +repository = "https://github.com/cashubtc/cdk.git" +rust-version.workspace = true # MSRV +readme = "README.md" + +# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html +[features] +default = ["mint", "wallet", "auth"] +mint = ["cdk-common/mint", "cdk-sql-common/mint"] +wallet = ["cdk-common/wallet", "cdk-sql-common/wallet"] +auth = ["cdk-common/auth", "cdk-sql-common/auth"] + +[dependencies] +async-trait.workspace = true +cdk-common = { workspace = true, features = ["test"] } +bitcoin.workspace = true +cdk-sql-common = { workspace = true } +thiserror.workspace = true +tokio = { workspace = true, features = ["rt-multi-thread"] } +tracing.workspace = true +serde.workspace = true +serde_json.workspace = true +lightning-invoice.workspace = true +uuid.workspace = true +tokio-postgres = "0.7.13" +futures-util = "0.3.31" +postgres-native-tls = "0.5.1" +once_cell.workspace = true diff --git a/crates/cdk-postgres/src/db.rs b/crates/cdk-postgres/src/db.rs new file mode 100644 index 000000000..be7a9eb38 --- /dev/null +++ b/crates/cdk-postgres/src/db.rs @@ -0,0 +1,155 @@ +use cdk_common::database::Error; +use cdk_sql_common::run_db_operation; +use cdk_sql_common::stmt::{Column, Statement}; +use futures_util::{pin_mut, TryStreamExt}; +use tokio_postgres::error::SqlState; +use tokio_postgres::{Client, Error as PgError}; + +use crate::value::PgValue; + +#[inline(always)] +fn to_pgsql_error(err: PgError) -> Error { + if let Some(err) = err.as_db_error() { + let code = err.code().to_owned(); + if code == SqlState::INTEGRITY_CONSTRAINT_VIOLATION || code == SqlState::UNIQUE_VIOLATION { + return Error::Duplicate; + } + } + + Error::Database(Box::new(err)) +} + +#[inline(always)] +pub async fn pg_batch(conn: &Client, statement: Statement) -> Result<(), Error> { + let (sql, _placeholder_values) = statement.to_sql()?; + + run_db_operation(&sql, conn.batch_execute(&sql), to_pgsql_error).await +} + +#[inline(always)] +pub async fn pg_execute(conn: &Client, statement: Statement) -> Result { + let (sql, placeholder_values) = statement.to_sql()?; + let prepared_statement = conn.prepare(&sql).await.map_err(to_pgsql_error)?; + + run_db_operation( + &sql, + async { + conn.execute_raw( + &prepared_statement, + placeholder_values + .iter() + .map(|x| x.into()) + .collect::>(), + ) + .await + .map(|x| x as usize) + }, + to_pgsql_error, + ) + .await +} + +#[inline(always)] +pub async fn pg_fetch_one( + conn: &Client, + statement: Statement, +) -> Result>, Error> { + let (sql, placeholder_values) = statement.to_sql()?; + let prepared_statement = conn.prepare(&sql).await.map_err(to_pgsql_error)?; + + run_db_operation( + &sql, + async { + let stream = conn + .query_raw( + &prepared_statement, + placeholder_values + .iter() + .map(|x| x.into()) + .collect::>(), + ) + .await?; + + pin_mut!(stream); + + stream + .try_next() + .await? + .map(|row| { + (0..row.len()) + .map(|i| row.try_get::<_, PgValue>(i).map(|value| value.into())) + .collect::, _>>() + }) + .transpose() + }, + to_pgsql_error, + ) + .await +} + +#[inline(always)] +pub async fn pg_fetch_all(conn: &Client, statement: Statement) -> Result>, Error> { + let (sql, placeholder_values) = statement.to_sql()?; + let prepared_statement = conn.prepare(&sql).await.map_err(to_pgsql_error)?; + + run_db_operation( + &sql, + async { + let stream = conn + .query_raw( + &prepared_statement, + placeholder_values + .iter() + .map(|x| x.into()) + .collect::>(), + ) + .await?; + + pin_mut!(stream); + + let mut rows = vec![]; + while let Some(row) = stream.try_next().await? { + rows.push( + (0..row.len()) + .map(|i| row.try_get::<_, PgValue>(i).map(|value| value.into())) + .collect::, _>>()?, + ); + } + + Ok(rows) + }, + to_pgsql_error, + ) + .await +} + +#[inline(always)] +pub async fn pg_pluck(conn: &Client, statement: Statement) -> Result, Error> { + let (sql, placeholder_values) = statement.to_sql()?; + let prepared_statement = conn.prepare(&sql).await.map_err(to_pgsql_error)?; + + run_db_operation( + &sql, + async { + let stream = conn + .query_raw( + &prepared_statement, + placeholder_values + .iter() + .map(|x| x.into()) + .collect::>(), + ) + .await?; + + pin_mut!(stream); + + stream + .try_next() + .await? + .map(|row| row.try_get::<_, PgValue>(0).map(|value| value.into())) + .transpose() + }, + to_pgsql_error, + ) + .await +} diff --git a/crates/cdk-postgres/src/lib.rs b/crates/cdk-postgres/src/lib.rs new file mode 100644 index 000000000..408e60ecb --- /dev/null +++ b/crates/cdk-postgres/src/lib.rs @@ -0,0 +1,257 @@ +use std::fmt::Debug; +use std::sync::atomic::AtomicBool; +use std::sync::{Arc, OnceLock}; +use std::time::Duration; + +use cdk_common::database::Error; +use cdk_sql_common::database::{DatabaseConnector, DatabaseExecutor, GenericTransactionHandler}; +use cdk_sql_common::mint::SQLMintAuthDatabase; +use cdk_sql_common::pool::{DatabaseConfig, DatabasePool}; +use cdk_sql_common::stmt::{Column, Statement}; +use cdk_sql_common::{SQLMintDatabase, SQLWalletDatabase}; +use db::{pg_batch, pg_execute, pg_fetch_all, pg_fetch_one, pg_pluck}; +use tokio::sync::{Mutex, Notify}; +use tokio::time::timeout; +use tokio_postgres::{connect, Client, Error as PgError, NoTls}; + +mod db; +mod value; + +#[derive(Debug)] +pub struct PgConnectionPool; + +#[derive(Clone)] +pub enum SslMode { + NoTls(NoTls), + NativeTls(postgres_native_tls::MakeTlsConnector), +} + +impl Default for SslMode { + fn default() -> Self { + SslMode::NoTls(NoTls {}) + } +} + +impl Debug for SslMode { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + let debug_text = match self { + Self::NoTls(_) => "NoTls", + Self::NativeTls(_) => "NativeTls", + }; + + write!(f, "SslMode::{debug_text}") + } +} + +/// Postgres configuration +#[derive(Clone, Debug)] +pub struct PgConfig { + url: String, + tls: SslMode, +} + +impl DatabaseConfig for PgConfig { + fn default_timeout(&self) -> Duration { + Duration::from_secs(10) + } + + fn max_size(&self) -> usize { + 20 + } +} + +impl From<&str> for PgConfig { + fn from(value: &str) -> Self { + PgConfig { + url: value.to_owned(), + tls: Default::default(), + } + } +} + +impl DatabasePool for PgConnectionPool { + type Config = PgConfig; + + type Connection = PostgresConnection; + + type Error = PgError; + + fn new_resource( + config: &Self::Config, + still_valid: Arc, + timeout: Duration, + ) -> Result> { + Ok(PostgresConnection::new( + config.to_owned(), + timeout, + still_valid, + )) + } +} + +/// A postgres connection +#[derive(Debug)] +pub struct PostgresConnection { + timeout: Duration, + error: Arc>>, + result: Arc>, + notify: Arc, +} + +impl PostgresConnection { + /// Creates a new instance + pub fn new(config: PgConfig, timeout: Duration, still_valid: Arc) -> Self { + let failed = Arc::new(Mutex::new(None)); + let result = Arc::new(OnceLock::new()); + let notify = Arc::new(Notify::new()); + let error_clone = failed.clone(); + let result_clone = result.clone(); + let notify_clone = notify.clone(); + + tokio::spawn(async move { + match config.tls { + SslMode::NoTls(tls) => { + let (client, connection) = match connect(&config.url, tls).await { + Ok((client, connection)) => (client, connection), + Err(err) => { + *error_clone.lock().await = + Some(cdk_common::database::Error::Database(Box::new(err))); + still_valid.store(false, std::sync::atomic::Ordering::Release); + notify_clone.notify_waiters(); + return; + } + }; + + tokio::spawn(async move { + let _ = connection.await; + still_valid.store(false, std::sync::atomic::Ordering::Release); + }); + + let _ = result_clone.set(client); + notify_clone.notify_waiters(); + } + SslMode::NativeTls(tls) => { + let (client, connection) = match connect(&config.url, tls).await { + Ok((client, connection)) => (client, connection), + Err(err) => { + *error_clone.lock().await = + Some(cdk_common::database::Error::Database(Box::new(err))); + still_valid.store(false, std::sync::atomic::Ordering::Release); + notify_clone.notify_waiters(); + return; + } + }; + + tokio::spawn(async move { + let _ = connection.await; + still_valid.store(false, std::sync::atomic::Ordering::Release); + }); + + let _ = result_clone.set(client); + notify_clone.notify_waiters(); + } + } + }); + + Self { + error: failed, + timeout, + result, + notify, + } + } + + /// Gets the wrapped instance or the connection error. The connection is returned as reference, + /// and the actual error is returned once, next times a generic error would be returned + async fn inner(&self) -> Result<&Client, cdk_common::database::Error> { + if let Some(client) = self.result.get() { + return Ok(client); + } + + if let Some(error) = self.error.lock().await.take() { + return Err(error); + } + + if timeout(self.timeout, self.notify.notified()).await.is_err() { + return Err(cdk_common::database::Error::Internal("Timeout".to_owned())); + } + + // Check result again + if let Some(client) = self.result.get() { + Ok(client) + } else if let Some(error) = self.error.lock().await.take() { + Err(error) + } else { + Err(cdk_common::database::Error::Internal( + "Failed connection".to_owned(), + )) + } + } +} + +#[async_trait::async_trait] +impl DatabaseConnector for PostgresConnection { + type Transaction = GenericTransactionHandler; +} + +#[async_trait::async_trait] +impl DatabaseExecutor for PostgresConnection { + fn name() -> &'static str { + "postgres" + } + + async fn execute(&self, statement: Statement) -> Result { + pg_execute(self.inner().await?, statement).await + } + + async fn fetch_one(&self, statement: Statement) -> Result>, Error> { + pg_fetch_one(self.inner().await?, statement).await + } + + async fn fetch_all(&self, statement: Statement) -> Result>, Error> { + pg_fetch_all(self.inner().await?, statement).await + } + + async fn pluck(&self, statement: Statement) -> Result, Error> { + pg_pluck(self.inner().await?, statement).await + } + + async fn batch(&self, statement: Statement) -> Result<(), Error> { + pg_batch(self.inner().await?, statement).await + } +} + +/// Mint DB implementation with PostgreSQL +pub type MintPgDatabase = SQLMintDatabase; + +/// Mint Auth database with Postgres +#[cfg(feature = "auth")] +pub type MintPgAuthDatabase = SQLMintAuthDatabase; + +/// Mint DB implementation with PostgresSQL +pub type WalletPgDatabase = SQLWalletDatabase; + +#[cfg(test)] +mod test { + use cdk_common::mint_db_test; + use once_cell::sync::Lazy; + use tokio::sync::Mutex; + + use super::*; + + static MIGRATION_LOCK: Lazy> = Lazy::new(|| Mutex::new(())); + + async fn provide_db() -> MintPgDatabase { + let m = MIGRATION_LOCK.lock().await; + let db_url = std::env::var("CDK_MINTD_DATABASE_URL") + .or_else(|_| std::env::var("PG_DB_URL")) // Fallback for compatibility + .unwrap_or("host=localhost user=test password=test dbname=testdb port=5433".to_owned()); + let db = MintPgDatabase::new(db_url.as_str()) + .await + .expect("database"); + drop(m); + db + } + + mint_db_test!(provide_db); +} diff --git a/crates/cdk-postgres/src/value.rs b/crates/cdk-postgres/src/value.rs new file mode 100644 index 000000000..e7c9ed646 --- /dev/null +++ b/crates/cdk-postgres/src/value.rs @@ -0,0 +1,130 @@ +use std::fmt::Debug; + +use cdk_sql_common::value::Value; +use tokio_postgres::types::{self, FromSql, ToSql}; + +#[derive(Debug)] +pub enum PgValue<'a> { + Null, + Integer(i64), + Real(f64), + Text(&'a str), + Blob(&'a [u8]), +} + +impl<'a> From<&'a Value> for PgValue<'a> { + fn from(value: &'a Value) -> Self { + match value { + Value::Blob(b) => PgValue::Blob(b), + Value::Text(text) => PgValue::Text(text.as_str()), + Value::Null => PgValue::Null, + Value::Integer(i) => PgValue::Integer(*i), + Value::Real(r) => PgValue::Real(*r), + } + } +} + +impl<'a> From> for Value { + fn from(val: PgValue<'a>) -> Self { + match val { + PgValue::Blob(value) => Value::Blob(value.to_owned()), + PgValue::Text(value) => Value::Text(value.to_owned()), + PgValue::Null => Value::Null, + PgValue::Integer(n) => Value::Integer(n), + PgValue::Real(r) => Value::Real(r), + } + } +} + +impl<'a> FromSql<'a> for PgValue<'a> { + fn accepts(_ty: &types::Type) -> bool { + true + } + + fn from_sql( + ty: &types::Type, + raw: &'a [u8], + ) -> Result> { + Ok(match *ty { + types::Type::VARCHAR | types::Type::TEXT | types::Type::BPCHAR | types::Type::NAME => { + PgValue::Text(<&str as FromSql>::from_sql(ty, raw)?) + } + types::Type::BOOL => PgValue::Integer(if ::from_sql(ty, raw)? { + 1 + } else { + 0 + }), + types::Type::INT2 => PgValue::Integer(::from_sql(ty, raw)? as i64), + types::Type::INT4 => PgValue::Integer(::from_sql(ty, raw)? as i64), + types::Type::INT8 => PgValue::Integer(::from_sql(ty, raw)?), + types::Type::BIT_ARRAY | types::Type::BYTEA | types::Type::UNKNOWN => { + PgValue::Blob(<&[u8] as FromSql>::from_sql(ty, raw)?) + } + _ => panic!("Unsupported type {ty:?}"), + }) + } + + fn from_sql_null(_ty: &types::Type) -> Result> { + Ok(PgValue::Null) + } +} + +impl ToSql for PgValue<'_> { + fn to_sql( + &self, + ty: &types::Type, + out: &mut types::private::BytesMut, + ) -> Result> + where + Self: Sized, + { + match self { + PgValue::Blob(blob) => (*blob).to_sql(ty, out), + PgValue::Text(text) => (*text).to_sql(ty, out), + PgValue::Null => Ok(types::IsNull::Yes), + PgValue::Real(r) => r.to_sql(ty, out), + PgValue::Integer(i) => match *ty { + types::Type::BOOL => (*i != 0).to_sql(ty, out), + types::Type::INT2 => (*i as i16).to_sql(ty, out), + types::Type::INT4 => (*i as i32).to_sql(ty, out), + _ => i.to_sql_checked(ty, out), + }, + } + } + + fn accepts(_ty: &types::Type) -> bool + where + Self: Sized, + { + true + } + + fn encode_format(&self, ty: &types::Type) -> types::Format { + match self { + PgValue::Blob(blob) => blob.encode_format(ty), + PgValue::Text(text) => text.encode_format(ty), + PgValue::Null => types::Format::Text, + PgValue::Real(r) => r.encode_format(ty), + PgValue::Integer(i) => i.encode_format(ty), + } + } + + fn to_sql_checked( + &self, + ty: &types::Type, + out: &mut types::private::BytesMut, + ) -> Result> { + match self { + PgValue::Blob(blob) => blob.to_sql_checked(ty, out), + PgValue::Text(text) => text.to_sql_checked(ty, out), + PgValue::Null => Ok(types::IsNull::Yes), + PgValue::Real(r) => r.to_sql_checked(ty, out), + PgValue::Integer(i) => match *ty { + types::Type::BOOL => (*i != 0).to_sql_checked(ty, out), + types::Type::INT2 => (*i as i16).to_sql_checked(ty, out), + types::Type::INT4 => (*i as i32).to_sql_checked(ty, out), + _ => i.to_sql_checked(ty, out), + }, + } + } +} diff --git a/crates/cdk-postgres/start_db_for_test.sh b/crates/cdk-postgres/start_db_for_test.sh new file mode 100644 index 000000000..d2a95b822 --- /dev/null +++ b/crates/cdk-postgres/start_db_for_test.sh @@ -0,0 +1,30 @@ +#!/usr/bin/env bash +set -euo pipefail + +CONTAINER_NAME="rust-test-pg" +DB_USER="test" +DB_PASS="test" +DB_NAME="testdb" +DB_PORT="5433" + +echo "Starting fresh PostgreSQL container..." +docker run -d --rm \ + --name "${CONTAINER_NAME}" \ + -e POSTGRES_USER="${DB_USER}" \ + -e POSTGRES_PASSWORD="${DB_PASS}" \ + -e POSTGRES_DB="${DB_NAME}" \ + -p ${DB_PORT}:5432 \ + postgres:16 + +echo "Waiting for PostgreSQL to be ready and database '${DB_NAME}' to exist..." +until docker exec -e PGPASSWORD="${DB_PASS}" "${CONTAINER_NAME}" \ + psql -U "${DB_USER}" -d "${DB_NAME}" -c "SELECT 1;" >/dev/null 2>&1; do + sleep 0.5 +done + +docker exec -e PGPASSWORD="${DB_PASS}" "${CONTAINER_NAME}" \ + psql -U "${DB_USER}" -d "${DB_NAME}" -c "CREATE DATABASE mintdb;" +docker exec -e PGPASSWORD="${DB_PASS}" "${CONTAINER_NAME}" \ + psql -U "${DB_USER}" -d "${DB_NAME}" -c "CREATE DATABASE mintdb_auth;" + +export DATABASE_URL="host=localhost user=${DB_USER} password=${DB_PASS} dbname=${DB_NAME} port=${DB_PORT}" diff --git a/crates/cdk-sql-common/src/database.rs b/crates/cdk-sql-common/src/database.rs index ed4334ec0..31368fe88 100644 --- a/crates/cdk-sql-common/src/database.rs +++ b/crates/cdk-sql-common/src/database.rs @@ -182,7 +182,7 @@ where /// Begin a transaction async fn begin(conn: &mut W) -> Result<(), Error> { - query("BEGIN")?.execute(conn).await?; + query("START TRANSACTION")?.execute(conn).await?; Ok(()) } diff --git a/crates/cdk-sql-common/src/mint/auth/migrations.rs b/crates/cdk-sql-common/src/mint/auth/migrations.rs index d0f90c897..a285e48a8 100644 --- a/crates/cdk-sql-common/src/mint/auth/migrations.rs +++ b/crates/cdk-sql-common/src/mint/auth/migrations.rs @@ -1,6 +1,7 @@ /// @generated /// Auto-generated by build.rs pub static MIGRATIONS: &[(&str, &str, &str)] = &[ + ("postgres", "1_init.sql", include_str!(r#"./migrations/postgres/1_init.sql"#)), ("sqlite", "1_fix_sqlx_migration.sql", include_str!(r#"./migrations/sqlite/1_fix_sqlx_migration.sql"#)), ("sqlite", "20250109143347_init.sql", include_str!(r#"./migrations/sqlite/20250109143347_init.sql"#)), ]; diff --git a/crates/cdk-sql-common/src/mint/auth/migrations/postgres/1_init.sql b/crates/cdk-sql-common/src/mint/auth/migrations/postgres/1_init.sql new file mode 100644 index 000000000..9bba9e14c --- /dev/null +++ b/crates/cdk-sql-common/src/mint/auth/migrations/postgres/1_init.sql @@ -0,0 +1,43 @@ +CREATE TABLE IF NOT EXISTS proof ( +y BYTEA PRIMARY KEY, +keyset_id TEXT NOT NULL, +secret TEXT NOT NULL, +c BYTEA NOT NULL, +state TEXT NOT NULL +); + +CREATE INDEX IF NOT EXISTS state_index ON proof(state); +CREATE INDEX IF NOT EXISTS secret_index ON proof(secret); + + +-- Keysets Table + +CREATE TABLE IF NOT EXISTS keyset ( + id TEXT PRIMARY KEY, + unit TEXT NOT NULL, + active BOOL NOT NULL, + valid_from INTEGER NOT NULL, + valid_to INTEGER, + derivation_path TEXT NOT NULL, + max_order INTEGER NOT NULL, + derivation_path_index INTEGER NOT NULL +); + +CREATE INDEX IF NOT EXISTS unit_index ON keyset(unit); +CREATE INDEX IF NOT EXISTS active_index ON keyset(active); + + +CREATE TABLE IF NOT EXISTS blind_signature ( + y BYTEA PRIMARY KEY, + amount INTEGER NOT NULL, + keyset_id TEXT NOT NULL, + c BYTEA NOT NULL +); + +CREATE INDEX IF NOT EXISTS keyset_id_index ON blind_signature(keyset_id); + + +CREATE TABLE IF NOT EXISTS protected_endpoints ( + endpoint TEXT PRIMARY KEY, + auth TEXT NOT NULL +); diff --git a/crates/cdk-sql-common/src/mint/auth/mod.rs b/crates/cdk-sql-common/src/mint/auth/mod.rs index c2840aed7..60f4f4bac 100644 --- a/crates/cdk-sql-common/src/mint/auth/mod.rs +++ b/crates/cdk-sql-common/src/mint/auth/mod.rs @@ -262,9 +262,10 @@ where FROM keyset WHERE - active = 1; + active = :active; "#, )? + .bind("active", true) .pluck(&*conn) .await? .map(|id| Ok::<_, Error>(column_as_string!(id, Id::from_str, Id::from_bytes))) diff --git a/crates/cdk-sql-common/src/mint/migrations.rs b/crates/cdk-sql-common/src/mint/migrations.rs index 96ee06e45..4b5a69679 100644 --- a/crates/cdk-sql-common/src/mint/migrations.rs +++ b/crates/cdk-sql-common/src/mint/migrations.rs @@ -1,6 +1,7 @@ /// @generated /// Auto-generated by build.rs pub static MIGRATIONS: &[(&str, &str, &str)] = &[ + ("postgres", "1_initial.sql", include_str!(r#"./migrations/postgres/1_initial.sql"#)), ("sqlite", "1_fix_sqlx_migration.sql", include_str!(r#"./migrations/sqlite/1_fix_sqlx_migration.sql"#)), ("sqlite", "20240612124932_init.sql", include_str!(r#"./migrations/sqlite/20240612124932_init.sql"#)), ("sqlite", "20240618195700_quote_state.sql", include_str!(r#"./migrations/sqlite/20240618195700_quote_state.sql"#)), diff --git a/crates/cdk-sql-common/src/mint/migrations/postgres/1_initial.sql b/crates/cdk-sql-common/src/mint/migrations/postgres/1_initial.sql new file mode 100644 index 000000000..56d0f6452 --- /dev/null +++ b/crates/cdk-sql-common/src/mint/migrations/postgres/1_initial.sql @@ -0,0 +1,100 @@ +CREATE TABLE keyset ( + id TEXT PRIMARY KEY, unit TEXT NOT NULL, + active BOOL NOT NULL, valid_from INTEGER NOT NULL, + valid_to INTEGER, derivation_path TEXT NOT NULL, + max_order INTEGER NOT NULL, input_fee_ppk INTEGER, + derivation_path_index INTEGER +); +CREATE INDEX unit_index ON keyset(unit); +CREATE INDEX active_index ON keyset(active); +CREATE TABLE melt_quote ( + id TEXT PRIMARY KEY, + unit TEXT NOT NULL, + amount INTEGER NOT NULL, + request TEXT NOT NULL, + fee_reserve INTEGER NOT NULL, + expiry INTEGER NOT NULL, + state TEXT CHECK ( + state IN ('UNPAID', 'PENDING', 'PAID') + ) NOT NULL DEFAULT 'UNPAID', + payment_preimage TEXT, + request_lookup_id TEXT, + created_time INTEGER NOT NULL DEFAULT 0, + paid_time INTEGER, + payment_method TEXT NOT NULL DEFAULT 'bolt11', + options TEXT, + request_lookup_id_kind TEXT NOT NULL DEFAULT 'payment_hash' +); +CREATE INDEX melt_quote_state_index ON melt_quote(state); +CREATE UNIQUE INDEX unique_request_lookup_id_melt ON melt_quote(request_lookup_id); +CREATE TABLE melt_request ( + id TEXT PRIMARY KEY, inputs TEXT NOT NULL, + outputs TEXT, method TEXT NOT NULL, + unit TEXT NOT NULL +); +CREATE TABLE config ( + id TEXT PRIMARY KEY, value TEXT NOT NULL +); +CREATE TABLE IF NOT EXISTS "proof" ( + y BYTEA PRIMARY KEY, + amount INTEGER NOT NULL, + keyset_id TEXT NOT NULL, + secret TEXT NOT NULL, + c BYTEA NOT NULL, + witness TEXT, + state TEXT CHECK ( + state IN ( + 'SPENT', 'PENDING', 'UNSPENT', 'RESERVED', + 'UNKNOWN' + ) + ) NOT NULL, + quote_id TEXT, + created_time INTEGER NOT NULL DEFAULT 0 +); +CREATE TABLE IF NOT EXISTS "blind_signature" ( + blinded_message BYTEA PRIMARY KEY, + amount INTEGER NOT NULL, + keyset_id TEXT NOT NULL, + c BYTEA NOT NULL, + dleq_e TEXT, + dleq_s TEXT, + quote_id TEXT, + created_time INTEGER NOT NULL DEFAULT 0 +); +CREATE TABLE IF NOT EXISTS "mint_quote" ( + id TEXT PRIMARY KEY, amount INTEGER, + unit TEXT NOT NULL, request TEXT NOT NULL, + expiry INTEGER NOT NULL, request_lookup_id TEXT UNIQUE, + pubkey TEXT, created_time INTEGER NOT NULL DEFAULT 0, + amount_paid INTEGER NOT NULL DEFAULT 0, + amount_issued INTEGER NOT NULL DEFAULT 0, + payment_method TEXT NOT NULL DEFAULT 'BOLT11', + request_lookup_id_kind TEXT NOT NULL DEFAULT 'payment_hash' +); +CREATE INDEX idx_mint_quote_created_time ON mint_quote(created_time); +CREATE INDEX idx_mint_quote_expiry ON mint_quote(expiry); +CREATE INDEX idx_mint_quote_request_lookup_id ON mint_quote(request_lookup_id); +CREATE INDEX idx_mint_quote_request_lookup_id_and_kind ON mint_quote( + request_lookup_id, request_lookup_id_kind +); +CREATE TABLE mint_quote_payments ( + id SERIAL PRIMARY KEY, + quote_id TEXT NOT NULL, + payment_id TEXT NOT NULL UNIQUE, + timestamp INTEGER NOT NULL, + amount INTEGER NOT NULL, + FOREIGN KEY (quote_id) REFERENCES mint_quote(id) +); +CREATE INDEX idx_mint_quote_payments_payment_id ON mint_quote_payments(payment_id); +CREATE INDEX idx_mint_quote_payments_quote_id ON mint_quote_payments(quote_id); +CREATE TABLE mint_quote_issued ( + id SERIAL PRIMARY KEY, + quote_id TEXT NOT NULL, + amount INTEGER NOT NULL, + timestamp INTEGER NOT NULL, + FOREIGN KEY (quote_id) REFERENCES mint_quote(id) +); +CREATE INDEX idx_mint_quote_issued_quote_id ON mint_quote_issued(quote_id); +CREATE INDEX idx_melt_quote_request_lookup_id_and_kind ON mint_quote( + request_lookup_id, request_lookup_id_kind +); diff --git a/crates/cdk-sql-common/src/mint/mod.rs b/crates/cdk-sql-common/src/mint/mod.rs index b45b8a8ca..be62fd33f 100644 --- a/crates/cdk-sql-common/src/mint/mod.rs +++ b/crates/cdk-sql-common/src/mint/mod.rs @@ -255,6 +255,9 @@ where ys: &[PublicKey], _quote_id: Option, ) -> Result<(), Self::Err> { + if ys.is_empty() { + return Ok(()); + } let total_deleted = query( r#" DELETE FROM proof WHERE y IN (:ys) AND state NOT IN (:exclude_state) @@ -314,10 +317,15 @@ where // Get payment IDs and timestamps from the mint_quote_payments table query( r#" -SELECT payment_id, timestamp, amount -FROM mint_quote_payments -WHERE quote_id=:quote_id; - "#, + SELECT + payment_id, + timestamp, + amount + FROM + mint_quote_payments + WHERE + quote_id=:quote_id + "#, )? .bind("quote_id", quote_id.as_hyphenated().to_string()) .fetch_all(conn) @@ -407,12 +415,12 @@ where } async fn set_active_keyset(&mut self, unit: CurrencyUnit, id: Id) -> Result<(), Error> { - query(r#"UPDATE keyset SET active=FALSE WHERE unit IS :unit"#)? + query(r#"UPDATE keyset SET active=FALSE WHERE unit = :unit"#)? .bind("unit", unit.to_string()) .execute(&self.inner) .await?; - query(r#"UPDATE keyset SET active=TRUE WHERE unit IS :unit AND id IS :id"#)? + query(r#"UPDATE keyset SET active=TRUE WHERE unit = :unit AND id = :id"#)? .bind("unit", unit.to_string()) .bind("id", id.to_string()) .execute(&self.inner) @@ -443,7 +451,8 @@ where async fn get_active_keyset_id(&self, unit: &CurrencyUnit) -> Result, Self::Err> { let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; Ok( - query(r#" SELECT id FROM keyset WHERE active = 1 AND unit IS :unit"#)? + query(r#" SELECT id FROM keyset WHERE active = :active AND unit = :unit"#)? + .bind("active", true) .bind("unit", unit.to_string()) .pluck(&*conn) .await? @@ -458,17 +467,20 @@ where async fn get_active_keysets(&self) -> Result, Self::Err> { let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; - Ok(query(r#"SELECT id, unit FROM keyset WHERE active = 1"#)? - .fetch_all(&*conn) - .await? - .into_iter() - .map(|row| { - Ok(( - column_as_string!(&row[1], CurrencyUnit::from_str), - column_as_string!(&row[0], Id::from_str, Id::from_bytes), - )) - }) - .collect::, Error>>()?) + Ok( + query(r#"SELECT id, unit FROM keyset WHERE active = :active"#)? + .bind("active", true) + .fetch_all(&*conn) + .await? + .into_iter() + .map(|row| { + Ok(( + column_as_string!(&row[1], CurrencyUnit::from_str), + column_as_string!(&row[0], Id::from_str, Id::from_bytes), + )) + }) + .collect::, Error>>()?, + ) } async fn get_keyset_info(&self, id: &Id) -> Result, Self::Err> { @@ -658,7 +670,6 @@ where UPDATE mint_quote SET amount_issued = :amount_issued WHERE id = :quote_id - FOR UPDATE "#, )? .bind("amount_issued", new_amount_issued.to_i64()) diff --git a/crates/cdk-sql-common/src/wallet/migrations.rs b/crates/cdk-sql-common/src/wallet/migrations.rs index 842cbd5a5..20cf48a34 100644 --- a/crates/cdk-sql-common/src/wallet/migrations.rs +++ b/crates/cdk-sql-common/src/wallet/migrations.rs @@ -1,6 +1,7 @@ /// @generated /// Auto-generated by build.rs pub static MIGRATIONS: &[(&str, &str, &str)] = &[ + ("postgres", "1_initial.sql", include_str!(r#"./migrations/postgres/1_initial.sql"#)), ("sqlite", "1_fix_sqlx_migration.sql", include_str!(r#"./migrations/sqlite/1_fix_sqlx_migration.sql"#)), ("sqlite", "20240612132920_init.sql", include_str!(r#"./migrations/sqlite/20240612132920_init.sql"#)), ("sqlite", "20240618200350_quote_state.sql", include_str!(r#"./migrations/sqlite/20240618200350_quote_state.sql"#)), diff --git a/crates/cdk-sql-common/src/wallet/migrations/postgres/1_initial.sql b/crates/cdk-sql-common/src/wallet/migrations/postgres/1_initial.sql new file mode 100644 index 000000000..04fc659ed --- /dev/null +++ b/crates/cdk-sql-common/src/wallet/migrations/postgres/1_initial.sql @@ -0,0 +1,80 @@ +CREATE TABLE mint ( + mint_url TEXT PRIMARY KEY, name TEXT, + pubkey BYTEA, version TEXT, description TEXT, + description_long TEXT, contact TEXT, + nuts TEXT, motd TEXT, icon_url TEXT, + mint_time INTEGER, urls TEXT, tos_url TEXT +); +CREATE TABLE keyset ( + id TEXT PRIMARY KEY, + mint_url TEXT NOT NULL, + unit TEXT NOT NULL, + active BOOL NOT NULL, + counter INTEGER NOT NULL DEFAULT 0, + input_fee_ppk INTEGER, + final_expiry INTEGER DEFAULT NULL, + FOREIGN KEY(mint_url) REFERENCES mint(mint_url) ON UPDATE CASCADE ON DELETE CASCADE +); +CREATE TABLE melt_quote ( + id TEXT PRIMARY KEY, + unit TEXT NOT NULL, + amount INTEGER NOT NULL, + request TEXT NOT NULL, + fee_reserve INTEGER NOT NULL, + expiry INTEGER NOT NULL, + state TEXT CHECK ( + state IN ('UNPAID', 'PENDING', 'PAID') + ) NOT NULL DEFAULT 'UNPAID', + payment_preimage TEXT +); +CREATE TABLE key ( + id TEXT PRIMARY KEY, keys TEXT NOT NULL +); +CREATE INDEX melt_quote_state_index ON melt_quote(state); +CREATE TABLE IF NOT EXISTS "proof" ( + y BYTEA PRIMARY KEY, + mint_url TEXT NOT NULL, + state TEXT CHECK ( + state IN ( + 'SPENT', 'UNSPENT', 'PENDING', 'RESERVED', + 'PENDING_SPENT' + ) + ) NOT NULL, + spending_condition TEXT, + unit TEXT NOT NULL, + amount INTEGER NOT NULL, + keyset_id TEXT NOT NULL, + secret TEXT NOT NULL, + c BYTEA NOT NULL, + witness TEXT, + dleq_e BYTEA, + dleq_s BYTEA, + dleq_r BYTEA +); +CREATE TABLE transactions ( + id BYTEA PRIMARY KEY, + mint_url TEXT NOT NULL, + direction TEXT CHECK ( + direction IN ('Incoming', 'Outgoing') + ) NOT NULL, + amount INTEGER NOT NULL, + fee INTEGER NOT NULL, + unit TEXT NOT NULL, + ys BYTEA NOT NULL, + timestamp INTEGER NOT NULL, + memo TEXT, + metadata TEXT +); +CREATE INDEX mint_url_index ON transactions(mint_url); +CREATE INDEX direction_index ON transactions(direction); +CREATE INDEX unit_index ON transactions(unit); +CREATE INDEX timestamp_index ON transactions(timestamp); +CREATE TABLE IF NOT EXISTS "mint_quote" ( + id TEXT PRIMARY KEY, mint_url TEXT NOT NULL, + payment_method TEXT NOT NULL DEFAULT 'bolt11', + amount INTEGER, unit TEXT NOT NULL, + request TEXT NOT NULL, state TEXT NOT NULL, + expiry INTEGER NOT NULL, amount_paid INTEGER NOT NULL DEFAULT 0, + amount_issued INTEGER NOT NULL DEFAULT 0, + secret_key TEXT +); diff --git a/crates/cdk/src/mint/proof_writer.rs b/crates/cdk/src/mint/proof_writer.rs index eddfc534c..b21bd3a9a 100644 --- a/crates/cdk/src/mint/proof_writer.rs +++ b/crates/cdk/src/mint/proof_writer.rs @@ -193,7 +193,9 @@ async fn reset_proofs_to_original_state( tx.update_proofs_states(&ys, state).await?; } - tx.remove_proofs(&unknown_proofs, None).await?; + if !unknown_proofs.is_empty() { + tx.remove_proofs(&unknown_proofs, None).await?; + } Ok(()) } diff --git a/crates/cdk/src/wallet/melt/melt_bolt11.rs b/crates/cdk/src/wallet/melt/melt_bolt11.rs index ce5fdc107..87ed0f24a 100644 --- a/crates/cdk/src/wallet/melt/melt_bolt11.rs +++ b/crates/cdk/src/wallet/melt/melt_bolt11.rs @@ -344,7 +344,7 @@ impl Wallet { .swap( Some(exact_amount), SplitTarget::None, - vec![proof.clone()], + vec![proof], None, false, ) diff --git a/docker-compose.postgres.yaml b/docker-compose.postgres.yaml new file mode 100644 index 000000000..54aa9c083 --- /dev/null +++ b/docker-compose.postgres.yaml @@ -0,0 +1,52 @@ +# Docker Compose configuration for CDK Mint with PostgreSQL +# Usage: docker-compose -f docker-compose.postgres.yaml up + +services: + # CDK Mint service with PostgreSQL + mintd: + build: + context: . + dockerfile: Dockerfile + container_name: mint + ports: + - "8085:8085" + environment: + - CDK_MINTD_URL=https://example.com + - CDK_MINTD_LN_BACKEND=fakewallet + - CDK_MINTD_LISTEN_HOST=0.0.0.0 + - CDK_MINTD_LISTEN_PORT=8085 + - CDK_MINTD_MNEMONIC= + # PostgreSQL database configuration + - CDK_MINTD_DATABASE=postgres + - CDK_MINTD_DATABASE_URL=postgresql://cdk_user:cdk_password@postgres:5432/cdk_mint + # Cache configuration + - CDK_MINTD_CACHE_BACKEND=memory + command: ["cdk-mintd"] + depends_on: + postgres: + condition: service_healthy + + # PostgreSQL database service + postgres: + image: postgres:16-alpine + container_name: mint_postgres + restart: unless-stopped + environment: + - POSTGRES_USER=cdk_user + - POSTGRES_PASSWORD=cdk_password + - POSTGRES_DB=cdk_mint + - POSTGRES_INITDB_ARGS=--encoding=UTF-8 --lc-collate=C --lc-ctype=C + ports: + - "5432:5432" + volumes: + - postgres_data:/var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready -U cdk_user -d cdk_mint"] + interval: 10s + timeout: 5s + retries: 5 + start_period: 30s + +volumes: + postgres_data: + driver: local diff --git a/docker-compose.yaml b/docker-compose.yaml index c30a6970f..0f8314e9e 100644 --- a/docker-compose.yaml +++ b/docker-compose.yaml @@ -1,4 +1,5 @@ services: + # CDK Mint service mintd: build: context: . @@ -12,22 +13,68 @@ services: - CDK_MINTD_LISTEN_HOST=0.0.0.0 - CDK_MINTD_LISTEN_PORT=8085 - CDK_MINTD_MNEMONIC= - - CDK_MINTD_DATABASE=redb + # Database configuration - choose one: + # Option 1: SQLite (embedded, no additional setup needed) + - CDK_MINTD_DATABASE=sqlite + # Option 2: ReDB (embedded, no additional setup needed) + # - CDK_MINTD_DATABASE=redb + # Option 3: PostgreSQL (requires postgres service, enable with: docker-compose --profile postgres up) + # - CDK_MINTD_DATABASE=postgres + # - CDK_MINTD_DATABASE_URL=postgresql://cdk_user:cdk_password@postgres:5432/cdk_mint + # Cache configuration - CDK_MINTD_CACHE_BACKEND=memory + # For Redis cache (requires redis service, enable with: docker-compose --profile redis up): # - CDK_MINTD_CACHE_REDIS_URL=redis://redis:6379 # - CDK_MINTD_CACHE_REDIS_KEY_PREFIX=cdk-mintd command: ["cdk-mintd"] + # Uncomment when using PostgreSQL: # depends_on: - # - redis + # - postgres + # PostgreSQL database service + # Enable with: docker-compose --profile postgres up + # postgres: + # image: postgres:16-alpine + # container_name: mint_postgres + # restart: unless-stopped + # profiles: + # - postgres + # environment: + # - POSTGRES_USER=cdk_user + # - POSTGRES_PASSWORD=cdk_password + # - POSTGRES_DB=cdk_mint + # - POSTGRES_INITDB_ARGS=--encoding=UTF-8 --lc-collate=C --lc-ctype=C + # ports: + # - "5432:5432" + # volumes: + # - postgres_data:/var/lib/postgresql/data + # healthcheck: + # test: ["CMD-SHELL", "pg_isready -U cdk_user -d cdk_mint"] + # interval: 10s + # timeout: 5s + # retries: 5 + + # Redis cache service (optional) + # Enable with: docker-compose --profile redis up # redis: # image: redis:7-alpine # container_name: mint_redis +# restart: unless-stopped +# profiles: +# - redis # ports: # - "6379:6379" # volumes: # - redis_data:/data # command: redis-server --save 60 1 --loglevel warning +# healthcheck: +# test: ["CMD", "redis-cli", "ping"] +# interval: 10s +# timeout: 3s +# retries: 5 -# volumes: -# redis_data: +volumes: + postgres_data: + driver: local +# redis_data: +# driver: local diff --git a/misc/fake_itests.sh b/misc/fake_itests.sh index d6a4199ea..0b19062bc 100755 --- a/misc/fake_itests.sh +++ b/misc/fake_itests.sh @@ -1,7 +1,7 @@ #!/usr/bin/env bash # Script to run fake mint tests with proper handling of race conditions -# This script ensures the .env file is properly created and available +# This script ensures the .env file is properly created and available # before running tests # Function to perform cleanup @@ -28,6 +28,10 @@ cleanup() { echo "Temp directory removed: $CDK_ITESTS_DIR" fi + if [ -n "$CONTAINER_NAME" ]; then + docker rm "${CONTAINER_NAME}" -f + fi + # Unset all environment variables unset CDK_ITESTS_DIR unset CDK_TEST_MINT_URL @@ -56,6 +60,31 @@ cargo build -p cdk-integration-tests # Start the fake mint binary with the new Rust-based approach echo "Starting fake mint using Rust binary..." + +if [ "${CDK_MINTD_DATABASE}" = "POSTGRES" ]; then + export CONTAINER_NAME="rust-fake-test-pg" + DB_USER="test" + DB_PASS="test" + DB_NAME="testdb" + DB_PORT="15433" + + docker run -d --rm \ + --name "${CONTAINER_NAME}" \ + -e POSTGRES_USER="${DB_USER}" \ + -e POSTGRES_PASSWORD="${DB_PASS}" \ + -e POSTGRES_DB="${DB_NAME}" \ + -p ${DB_PORT}:5432 \ + postgres:16 + export CDK_MINTD_DATABASE_URL="postgresql://${DB_USER}:${DB_PASS}@localhost:${DB_PORT}/${DB_NAME}" + + echo "Waiting for PostgreSQL to be ready and database '${DB_NAME}' to exist..." + until docker exec -e PGPASSWORD="${DB_PASS}" "${CONTAINER_NAME}" \ + psql -U "${DB_USER}" -d "${DB_NAME}" -c "SELECT 1;" >/dev/null 2>&1; do + sleep 0.5 + done + echo "PostgreSQL container is ready" +fi + if [ "$2" = "external_signatory" ]; then echo "Starting with external signatory support" @@ -64,7 +93,7 @@ if [ "$2" = "external_signatory" ]; then cargo run --bin signatory -- -w $CDK_ITESTS_DIR -u "sat" -u "usd" & export CDK_SIGNATORY_PID=$! sleep 5 - + cargo run --bin start_fake_mint -- --enable-logging --external-signatory "$CDK_MINTD_DATABASE" "$CDK_ITESTS_DIR" & else cargo run --bin start_fake_mint -- --enable-logging "$CDK_MINTD_DATABASE" "$CDK_ITESTS_DIR" & From d3a3c30d990265e0300c6880827816dc131eedf3 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Tue, 19 Aug 2025 12:01:01 +0100 Subject: [PATCH 086/321] feat(cdk): add Bolt12 mint quote subscription support (#976) * feat(cdk): add Bolt12 mint quote subscription support Extends subscription to handle Bolt12 payment method alongside existing Bolt11 support across wallet, mint, and CLI components. --- Cargo.toml | 2 +- crates/cashu/src/nuts/nut17/mod.rs | 2 + crates/cdk-cli/src/main.rs | 4 +- crates/cdk-cli/src/sub_commands/mint.rs | 107 +++++++----------- crates/cdk-common/src/subscription.rs | 3 + crates/cdk-fake-wallet/src/lib.rs | 2 +- .../cdk-integration-tests/tests/fake_auth.rs | 12 +- crates/cdk/examples/auth_wallet.rs | 14 +-- crates/cdk/examples/melt-token.rs | 12 +- crates/cdk/examples/mint-token.rs | 11 +- crates/cdk/examples/p2pk.rs | 16 +-- crates/cdk/examples/proof-selection.rs | 11 +- crates/cdk/examples/wallet.rs | 11 +- .../src/mint/subscription/on_subscription.rs | 20 +++- crates/cdk/src/wallet/mod.rs | 7 ++ crates/cdk/src/wallet/subscription/http.rs | 5 + crates/cdk/src/wallet/wait.rs | 83 ++++++-------- 17 files changed, 164 insertions(+), 158 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 3dc2372bd..a0b278c28 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -68,7 +68,7 @@ lightning = { version = "0.1.2", default-features = false, features = ["std"]} serde = { version = "1", features = ["derive"] } serde_json = "1" thiserror = { version = "2" } -tokio = { version = "1", default-features = false, features = ["rt", "macros", "test-util"] } +tokio = { version = "1", default-features = false, features = ["rt", "macros", "test-util", "sync"] } tokio-util = { version = "0.7.11", default-features = false } tower-http = { version = "0.6.1", features = ["compression-full", "decompression-full", "cors", "trace"] } tokio-tungstenite = { version = "0.26.0", default-features = false } diff --git a/crates/cashu/src/nuts/nut17/mod.rs b/crates/cashu/src/nuts/nut17/mod.rs index da3be3c8f..5d01d99c9 100644 --- a/crates/cashu/src/nuts/nut17/mod.rs +++ b/crates/cashu/src/nuts/nut17/mod.rs @@ -174,6 +174,8 @@ pub enum Kind { Bolt11MintQuote, /// Proof State ProofState, + /// Bolt 12 Mint Quote + Bolt12MintQuote, } impl AsRef for Params { diff --git a/crates/cdk-cli/src/main.rs b/crates/cdk-cli/src/main.rs index d85cc06bc..9a601579c 100644 --- a/crates/cdk-cli/src/main.rs +++ b/crates/cdk-cli/src/main.rs @@ -102,9 +102,9 @@ async fn main() -> Result<()> { let args: Cli = Cli::parse(); let default_filter = args.log_level; - let sqlx_filter = "sqlx=warn,hyper_util=warn,reqwest=warn"; + let filter = "rustls=warn,hyper_util=warn,reqwest=warn"; - let env_filter = EnvFilter::new(format!("{default_filter},{sqlx_filter}")); + let env_filter = EnvFilter::new(format!("{default_filter},{filter}")); // Parse input tracing_subscriber::fmt().with_env_filter(env_filter).init(); diff --git a/crates/cdk-cli/src/sub_commands/mint.rs b/crates/cdk-cli/src/sub_commands/mint.rs index 71b2a987e..51a90a6a0 100644 --- a/crates/cdk-cli/src/sub_commands/mint.rs +++ b/crates/cdk-cli/src/sub_commands/mint.rs @@ -1,11 +1,12 @@ use std::str::FromStr; +use std::time::Duration; use anyhow::{anyhow, Result}; use cdk::amount::SplitTarget; use cdk::mint_url::MintUrl; use cdk::nuts::nut00::ProofsMethods; -use cdk::nuts::{CurrencyUnit, MintQuoteState, NotificationPayload, PaymentMethod}; -use cdk::wallet::{MultiMintWallet, WalletSubscription}; +use cdk::nuts::{CurrencyUnit, PaymentMethod}; +use cdk::wallet::MultiMintWallet; use cdk::Amount; use clap::Args; use serde::{Deserialize, Serialize}; @@ -36,6 +37,9 @@ pub struct MintSubCommand { /// Expiry #[arg(short, long)] single_use: Option, + /// Wait duration in seconds for mint quote polling + #[arg(long, default_value = "30")] + wait_duration: u64, } pub async fn mint( @@ -48,9 +52,9 @@ pub async fn mint( let wallet = get_or_create_wallet(multi_mint_wallet, &mint_url, unit).await?; - let mut payment_method = PaymentMethod::from_str(&sub_command_args.method)?; + let payment_method = PaymentMethod::from_str(&sub_command_args.method)?; - let quote_id = match &sub_command_args.quote_id { + let quote = match &sub_command_args.quote_id { None => match payment_method { PaymentMethod::Bolt11 => { let amount = sub_command_args @@ -62,20 +66,7 @@ pub async fn mint( println!("Please pay: {}", quote.request); - let mut subscription = wallet - .subscribe(WalletSubscription::Bolt11MintQuoteState(vec![quote - .id - .clone()])) - .await; - - while let Some(msg) = subscription.recv().await { - if let NotificationPayload::MintQuoteBolt11Response(response) = msg { - if response.state == MintQuoteState::Paid { - break; - } - } - } - quote.id + quote } PaymentMethod::Bolt12 => { let amount = sub_command_args.amount; @@ -88,68 +79,46 @@ pub async fn mint( println!("Please pay: {}", quote.request); - let mut subscription = wallet - .subscribe(WalletSubscription::Bolt11MintQuoteState(vec![quote - .id - .clone()])) - .await; - - while let Some(msg) = subscription.recv().await { - if let NotificationPayload::MintQuoteBolt11Response(response) = msg { - if response.state == MintQuoteState::Paid { - break; - } - } - } - quote.id + quote } _ => { todo!() } }, - Some(quote_id) => { - let quote = wallet - .localstore - .get_mint_quote(quote_id) - .await? - .ok_or(anyhow!("Unknown quote"))?; - - payment_method = quote.payment_method; - quote_id.to_string() - } + Some(quote_id) => wallet + .localstore + .get_mint_quote(quote_id) + .await? + .ok_or(anyhow!("Unknown quote"))?, }; tracing::debug!("Attempting mint for: {}", payment_method); - let proofs = match payment_method { - PaymentMethod::Bolt11 => wallet.mint("e_id, SplitTarget::default(), None).await?, - PaymentMethod::Bolt12 => { - let response = wallet.mint_bolt12_quote_state("e_id).await?; - - let amount_mintable = response.amount_paid - response.amount_issued; - - if amount_mintable == Amount::ZERO { - println!("Mint quote does not have amount that can be minted."); - return Ok(()); - } - - wallet - .mint_bolt12( - "e_id, - Some(amount_mintable), - SplitTarget::default(), - None, - ) - .await? - } - _ => { - todo!() + let mut amount_minted = Amount::ZERO; + + loop { + let proofs = wallet + .wait_and_mint_quote( + quote.clone(), + SplitTarget::default(), + None, + Duration::from_secs(sub_command_args.wait_duration), + ) + .await?; + + amount_minted += proofs.total_amount()?; + + if sub_command_args.quote_id.is_none() || quote.payment_method == PaymentMethod::Bolt11 { + break; + } else { + println!( + "Minted {} waiting for next payment.", + proofs.total_amount()? + ); } - }; - - let receive_amount = proofs.total_amount()?; + } - println!("Received {receive_amount} from mint {mint_url}"); + println!("Received {amount_minted} from mint {mint_url}"); Ok(()) } diff --git a/crates/cdk-common/src/subscription.rs b/crates/cdk-common/src/subscription.rs index 50c6cbe7f..dacd284c4 100644 --- a/crates/cdk-common/src/subscription.rs +++ b/crates/cdk-common/src/subscription.rs @@ -51,6 +51,9 @@ impl TryFrom for Vec> { Notification::MintQuoteBolt11(Uuid::from_str(&filter)?) } Kind::ProofState => Notification::ProofState(PublicKey::from_str(&filter)?), + Kind::Bolt12MintQuote => { + Notification::MintQuoteBolt12(Uuid::from_str(&filter)?) + } }; Ok(Index::from((idx, params.id.clone(), sub_id))) diff --git a/crates/cdk-fake-wallet/src/lib.rs b/crates/cdk-fake-wallet/src/lib.rs index 90abdce43..54c931e81 100644 --- a/crates/cdk-fake-wallet/src/lib.rs +++ b/crates/cdk-fake-wallet/src/lib.rs @@ -108,7 +108,7 @@ impl SecondaryRepaymentQueue { loop { // Wait for a random interval between 30 seconds and 3 minutes (180 seconds) - let delay_secs = rng.gen_range(30..=180); + let delay_secs = rng.gen_range(1..=3); time::sleep(time::Duration::from_secs(delay_secs)).await; // Try to process a random payment from the queue without removing it diff --git a/crates/cdk-integration-tests/tests/fake_auth.rs b/crates/cdk-integration-tests/tests/fake_auth.rs index 6a934254b..dba54fbdf 100644 --- a/crates/cdk-integration-tests/tests/fake_auth.rs +++ b/crates/cdk-integration-tests/tests/fake_auth.rs @@ -330,13 +330,17 @@ async fn test_mint_with_auth() { let mint_amount: Amount = 100.into(); - let (_, proofs) = wallet - .mint_once_paid(mint_amount, None, Duration::from_secs(10)) + let quote = wallet.mint_quote(mint_amount, None).await.unwrap(); + let proofs = wallet + .wait_and_mint_quote( + quote, + Default::default(), + Default::default(), + Duration::from_secs(10), + ) .await .unwrap(); - let proofs = proofs.await.expect("could not mint"); - assert!(proofs.total_amount().expect("Could not get proofs amount") == mint_amount); } diff --git a/crates/cdk/examples/auth_wallet.rs b/crates/cdk/examples/auth_wallet.rs index 5b23a4f26..27b28092d 100644 --- a/crates/cdk/examples/auth_wallet.rs +++ b/crates/cdk/examples/auth_wallet.rs @@ -5,6 +5,7 @@ use cdk::error::Error; use cdk::nuts::CurrencyUnit; use cdk::wallet::{SendOptions, Wallet}; use cdk::{Amount, OidcClient}; +use cdk_common::amount::SplitTarget; use cdk_common::{MintInfo, ProofsMethods}; use cdk_sqlite::wallet::memory; use rand::Rng; @@ -57,14 +58,13 @@ async fn main() -> Result<(), Error> { .await .expect("Could not mint blind auth"); - let (_invoice_to_pay, proofs) = wallet - .mint_once_paid(amount, None, Duration::from_secs(10)) - .await?; - - // Mint the received amount - let receive_amount = proofs.await?; + let quote = wallet.mint_quote(amount, None).await.unwrap(); + let proofs = wallet + .wait_and_mint_quote(quote, SplitTarget::default(), None, Duration::from_secs(10)) + .await + .unwrap(); - println!("Received: {}", receive_amount.total_amount()?); + println!("Received: {}", proofs.total_amount()?); // Get the total balance of the wallet let balance = wallet.total_balance().await?; diff --git a/crates/cdk/examples/melt-token.rs b/crates/cdk/examples/melt-token.rs index c97106fe0..8ebb44bff 100644 --- a/crates/cdk/examples/melt-token.rs +++ b/crates/cdk/examples/melt-token.rs @@ -29,12 +29,16 @@ async fn main() -> Result<(), Error> { // Create a new wallet let wallet = Wallet::new(mint_url, unit, Arc::new(localstore), seed, None)?; - let (_invoice_to_pay, proofs) = wallet - .mint_once_paid(amount, None, Duration::from_secs(10)) + let quote = wallet.mint_quote(amount, None).await?; + let proofs = wallet + .wait_and_mint_quote( + quote, + Default::default(), + Default::default(), + Duration::from_secs(10), + ) .await?; - // Mint the received amount - let proofs = proofs.await?; let receive_amount = proofs.total_amount()?; println!("Received {} from mint {}", receive_amount, mint_url); diff --git a/crates/cdk/examples/mint-token.rs b/crates/cdk/examples/mint-token.rs index 64fe3d92a..a00f7d97c 100644 --- a/crates/cdk/examples/mint-token.rs +++ b/crates/cdk/examples/mint-token.rs @@ -35,12 +35,17 @@ async fn main() -> Result<(), Error> { // Create a new wallet let wallet = Wallet::new(mint_url, unit, localstore, seed, None)?; - let (_invoice_to_pay, proofs) = wallet - .mint_once_paid(amount, None, Duration::from_secs(10)) + let quote = wallet.mint_quote(amount, None).await?; + let proofs = wallet + .wait_and_mint_quote( + quote, + Default::default(), + Default::default(), + Duration::from_secs(10), + ) .await?; // Mint the received amount - let proofs = proofs.await?; let receive_amount = proofs.total_amount()?; println!("Received {} from mint {}", receive_amount, mint_url); diff --git a/crates/cdk/examples/p2pk.rs b/crates/cdk/examples/p2pk.rs index eaf56fbbb..9bf8ef53d 100644 --- a/crates/cdk/examples/p2pk.rs +++ b/crates/cdk/examples/p2pk.rs @@ -34,18 +34,20 @@ async fn main() -> Result<(), Error> { // Create a new wallet let wallet = Wallet::new(mint_url, unit, localstore, seed, None).unwrap(); - let (_invoice_to_pay, proofs) = wallet - .mint_once_paid(amount, None, Duration::from_secs(10)) + let quote = wallet.mint_quote(amount, None).await?; + let proofs = wallet + .wait_and_mint_quote( + quote, + Default::default(), + Default::default(), + Duration::from_secs(10), + ) .await?; // Mint the received amount - let received_proofs = proofs.await?; println!( "Minted nuts: {:?}", - received_proofs - .into_iter() - .map(|p| p.amount) - .collect::>() + proofs.into_iter().map(|p| p.amount).collect::>() ); // Generate a secret key for spending conditions diff --git a/crates/cdk/examples/proof-selection.rs b/crates/cdk/examples/proof-selection.rs index 053692910..cc63e3bca 100644 --- a/crates/cdk/examples/proof-selection.rs +++ b/crates/cdk/examples/proof-selection.rs @@ -31,12 +31,17 @@ async fn main() -> Result<(), Box> { for amount in [64] { let amount = Amount::from(amount); - let (_invoice_to_pay, proofs) = wallet - .mint_once_paid(amount, None, Duration::from_secs(10)) + let quote = wallet.mint_quote(amount, None).await?; + let proofs = wallet + .wait_and_mint_quote( + quote, + Default::default(), + Default::default(), + Duration::from_secs(10), + ) .await?; // Mint the received amount - let proofs = proofs.await?; let receive_amount = proofs.total_amount()?; println!("Minted {}", receive_amount); } diff --git a/crates/cdk/examples/wallet.rs b/crates/cdk/examples/wallet.rs index 3d036c6c8..37c5653dd 100644 --- a/crates/cdk/examples/wallet.rs +++ b/crates/cdk/examples/wallet.rs @@ -24,12 +24,17 @@ async fn main() -> Result<(), Box> { // Create a new wallet let wallet = Wallet::new(mint_url, unit, localstore, seed, None)?; - let (_invoice_to_pay, proofs) = wallet - .mint_once_paid(amount, None, Duration::from_secs(10)) + let quote = wallet.mint_quote(amount, None).await?; + let proofs = wallet + .wait_and_mint_quote( + quote, + Default::default(), + Default::default(), + Duration::from_secs(10), + ) .await?; // Mint the received amount - let proofs = proofs.await?; let receive_amount = proofs.total_amount()?; println!("Minted {}", receive_amount); diff --git a/crates/cdk/src/mint/subscription/on_subscription.rs b/crates/cdk/src/mint/subscription/on_subscription.rs index 4d57976ff..b3f1f8fb4 100644 --- a/crates/cdk/src/mint/subscription/on_subscription.rs +++ b/crates/cdk/src/mint/subscription/on_subscription.rs @@ -6,7 +6,7 @@ use std::sync::Arc; use cdk_common::database::{self, MintDatabase}; use cdk_common::nut17::Notification; use cdk_common::pub_sub::OnNewSubscription; -use cdk_common::NotificationPayload; +use cdk_common::{MintQuoteBolt12Response, NotificationPayload, PaymentMethod}; use uuid::Uuid; use crate::nuts::{MeltQuoteBolt11Response, MintQuoteBolt11Response, ProofState, PublicKey}; @@ -79,8 +79,22 @@ impl OnNewSubscription for OnSubscription { .map(|quotes| { quotes .into_iter() - .filter_map(|quote| quote.map(|x| x.into())) - .map(|x: MintQuoteBolt11Response| x.into()) + .filter_map(|quote| { + quote.and_then(|x| match x.payment_method { + PaymentMethod::Bolt11 => { + let response: MintQuoteBolt11Response = x.into(); + Some(response.into()) + } + PaymentMethod::Bolt12 => match x.try_into() { + Ok(response) => { + let response: MintQuoteBolt12Response = response; + Some(response.into()) + } + Err(_) => None, + }, + PaymentMethod::Custom(_) => None, + }) + }) .collect::>() }) .map_err(|e| e.to_string())?, diff --git a/crates/cdk/src/wallet/mod.rs b/crates/cdk/src/wallet/mod.rs index f02079010..2099fa49b 100644 --- a/crates/cdk/src/wallet/mod.rs +++ b/crates/cdk/src/wallet/mod.rs @@ -94,6 +94,8 @@ pub enum WalletSubscription { Bolt11MintQuoteState(Vec), /// Melt quote subscription Bolt11MeltQuoteState(Vec), + /// Mint bolt12 quote subscription + Bolt12MintQuoteState(Vec), } impl From for Params { @@ -126,6 +128,11 @@ impl From for Params { kind: Kind::Bolt11MeltQuote, id: id.into(), }, + WalletSubscription::Bolt12MintQuoteState(filters) => Params { + filters, + kind: Kind::Bolt12MintQuote, + id: id.into(), + }, } } } diff --git a/crates/cdk/src/wallet/subscription/http.rs b/crates/cdk/src/wallet/subscription/http.rs index 65a284802..fa8d69a5f 100644 --- a/crates/cdk/src/wallet/subscription/http.rs +++ b/crates/cdk/src/wallet/subscription/http.rs @@ -66,6 +66,11 @@ async fn convert_subscription( } } } + Kind::Bolt12MintQuote => { + for id in sub.1.filters.iter().map(|id| UrlType::Mint(id.clone())) { + subscribed_to.insert(id, (sub.0.clone(), sub.1.id.clone(), AnyState::Empty)); + } + } } Some(()) diff --git a/crates/cdk/src/wallet/wait.rs b/crates/cdk/src/wallet/wait.rs index 0774e1697..f5d041737 100644 --- a/crates/cdk/src/wallet/wait.rs +++ b/crates/cdk/src/wallet/wait.rs @@ -1,9 +1,8 @@ -use std::future::Future; - use cdk_common::amount::SplitTarget; use cdk_common::wallet::{MeltQuote, MintQuote}; use cdk_common::{ - Amount, Error, MeltQuoteState, MintQuoteState, NotificationPayload, Proofs, SpendingConditions, + Amount, Error, MeltQuoteState, MintQuoteState, NotificationPayload, PaymentMethod, Proofs, + SpendingConditions, }; use futures::future::BoxFuture; use tokio::time::{timeout, Duration}; @@ -11,9 +10,11 @@ use tokio::time::{timeout, Duration}; use super::{Wallet, WalletSubscription}; #[allow(private_bounds)] +#[allow(clippy::enum_variant_names)] enum WaitableEvent { MeltQuote(String), MintQuote(String), + Bolt12MintQuote(String), } impl From<&MeltQuote> for WaitableEvent { @@ -24,7 +25,11 @@ impl From<&MeltQuote> for WaitableEvent { impl From<&MintQuote> for WaitableEvent { fn from(event: &MintQuote) -> Self { - WaitableEvent::MintQuote(event.id.to_owned()) + match event.payment_method { + PaymentMethod::Bolt11 => WaitableEvent::MintQuote(event.id.to_owned()), + PaymentMethod::Bolt12 => WaitableEvent::Bolt12MintQuote(event.id.to_owned()), + PaymentMethod::Custom(_) => WaitableEvent::MintQuote(event.id.to_owned()), + } } } @@ -37,62 +42,38 @@ impl From for WalletSubscription { WaitableEvent::MintQuote(quote_id) => { WalletSubscription::Bolt11MintQuoteState(vec![quote_id]) } + WaitableEvent::Bolt12MintQuote(quote_id) => { + WalletSubscription::Bolt12MintQuoteState(vec![quote_id]) + } } } } impl Wallet { #[inline(always)] - async fn wait_and_mint_quote( + /// Mints a mint quote once it is paid + pub async fn wait_and_mint_quote( &self, quote: MintQuote, amount_split_target: SplitTarget, spending_conditions: Option, timeout_duration: Duration, ) -> Result { - self.wait_for_payment("e, timeout_duration).await?; - self.mint("e.id, amount_split_target, spending_conditions) - .await - } - - /// Mints an amount and returns the invoice to be paid, and a BoxFuture that will finalize the - /// mint once the invoice has been paid - pub async fn mint_once_paid( - &self, - amount: Amount, - description: Option, - timeout_duration: Duration, - ) -> Result<(String, impl Future> + '_), Error> { - self.mint_once_paid_ex( - amount, - description, - Default::default(), - None, - timeout_duration, - ) - .await - } + let amount = self.wait_for_payment("e, timeout_duration).await?; - /// Similar function to mint_once_paid but with no default options - pub async fn mint_once_paid_ex( - &self, - amount: Amount, - description: Option, - amount_split_target: SplitTarget, - spending_conditions: Option, - timeout_duration: Duration, - ) -> Result<(String, impl Future> + '_), Error> { - let quote = self.mint_quote(amount, description).await?; + tracing::debug!("Received payment notification for {}. Minting...", quote.id); - Ok(( - quote.request.clone(), - self.wait_and_mint_quote( - quote, - amount_split_target, - spending_conditions, - timeout_duration, - ), - )) + match quote.payment_method { + PaymentMethod::Bolt11 => { + self.mint("e.id, amount_split_target, spending_conditions) + .await + } + PaymentMethod::Bolt12 => { + self.mint_bolt12("e.id, amount, amount_split_target, spending_conditions) + .await + } + _ => Err(Error::UnsupportedPaymentMethod), + } } /// Returns a BoxFuture that will wait for payment on the given event with a timeout check @@ -101,7 +82,7 @@ impl Wallet { &self, event: T, timeout_duration: Duration, - ) -> BoxFuture<'_, Result<(), Error>> + ) -> BoxFuture<'_, Result, Error>> where T: Into, { @@ -114,17 +95,17 @@ impl Wallet { match subscription.recv().await.ok_or(Error::Internal)? { NotificationPayload::MintQuoteBolt11Response(info) => { if info.state == MintQuoteState::Paid { - return Ok(()); + return Ok(None); } } NotificationPayload::MintQuoteBolt12Response(info) => { - if info.amount_paid > Amount::ZERO { - return Ok(()); + if info.amount_paid - info.amount_issued > Amount::ZERO { + return Ok(Some(info.amount_paid - info.amount_issued)); } } NotificationPayload::MeltQuoteBolt11Response(info) => { if info.state == MeltQuoteState::Paid { - return Ok(()); + return Ok(None); } } _ => {} From 29ce2e4f4df21155da04ef6a070cd1bb1c4d3187 Mon Sep 17 00:00:00 2001 From: Cesar Rodas Date: Mon, 18 Aug 2025 11:51:24 -0300 Subject: [PATCH 087/321] Http retry should only happen at Http Error (which are transport errors) Fixes #939 --- crates/cdk-common/src/error.rs | 4 +- .../src/wallet/mint_connector/http_client.rs | 49 ++++++++++++++----- 2 files changed, 39 insertions(+), 14 deletions(-) diff --git a/crates/cdk-common/src/error.rs b/crates/cdk-common/src/error.rs index 23aaeb5ed..5d19ab4ef 100644 --- a/crates/cdk-common/src/error.rs +++ b/crates/cdk-common/src/error.rs @@ -290,8 +290,8 @@ pub enum Error { #[error(transparent)] HexError(#[from] hex::Error), /// Http transport error - #[error("Http transport error: {0}")] - HttpError(String), + #[error("Http transport error {0:?}: {1}")] + HttpError(Option, String), #[cfg(feature = "wallet")] // Crate error conversions /// Cashu Url Error diff --git a/crates/cdk/src/wallet/mint_connector/http_client.rs b/crates/cdk/src/wallet/mint_connector/http_client.rs index 25b0c8916..1421ece94 100644 --- a/crates/cdk/src/wallet/mint_connector/http_client.rs +++ b/crates/cdk/src/wallet/mint_connector/http_client.rs @@ -64,10 +64,20 @@ impl HttpClientCore { let response = request .send() .await - .map_err(|e| Error::HttpError(e.to_string()))? + .map_err(|e| { + Error::HttpError( + e.status().map(|status_code| status_code.as_u16()), + e.to_string(), + ) + })? .text() .await - .map_err(|e| Error::HttpError(e.to_string()))?; + .map_err(|e| { + Error::HttpError( + e.status().map(|status_code| status_code.as_u16()), + e.to_string(), + ) + })?; serde_json::from_str::(&response).map_err(|err| { tracing::warn!("Http Response error: {}", err); @@ -90,15 +100,19 @@ impl HttpClientCore { request = request.header(auth.header_key(), auth.to_string()); } - let response = request - .send() - .await - .map_err(|e| Error::HttpError(e.to_string()))?; + let response = request.send().await.map_err(|e| { + Error::HttpError( + e.status().map(|status_code| status_code.as_u16()), + e.to_string(), + ) + })?; - let response = response - .text() - .await - .map_err(|e| Error::HttpError(e.to_string()))?; + let response = response.text().await.map_err(|e| { + Error::HttpError( + e.status().map(|status_code| status_code.as_u16()), + e.to_string(), + ) + })?; serde_json::from_str::(&response).map_err(|err| { tracing::warn!("Http Response error: {}", err); @@ -189,7 +203,12 @@ impl HttpClient { })) .danger_accept_invalid_certs(accept_invalid_certs) // Allow self-signed certs .build() - .map_err(|e| Error::HttpError(e.to_string()))?; + .map_err(|e| { + Error::HttpError( + e.status().map(|status_code| status_code.as_u16()), + e.to_string(), + ) + })?; Ok(Self { core: HttpClientCore { inner: client }, @@ -249,7 +268,13 @@ impl HttpClient { } match result.as_ref() { - Err(Error::Database(_) | Error::HttpError(_) | Error::Custom(_)) => { + Err(Error::HttpError(status_code, _)) => { + let status_code = status_code.to_owned().unwrap_or_default(); + if status_code <= 400 && status_code >= 499 { + // 4xx errors won't be 'solved' by retrying + return result; + } + // retry request, if possible tracing::error!("Failed http_request {:?}", result.as_ref().err()); From e31a9b1905c476cd7919d824c6bc9f38eb04f0d6 Mon Sep 17 00:00:00 2001 From: C Date: Mon, 18 Aug 2025 12:20:18 -0300 Subject: [PATCH 088/321] Update crates/cdk/src/wallet/mint_connector/http_client.rs Co-authored-by: thesimplekid --- crates/cdk/src/wallet/mint_connector/http_client.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/cdk/src/wallet/mint_connector/http_client.rs b/crates/cdk/src/wallet/mint_connector/http_client.rs index 1421ece94..b9e289fac 100644 --- a/crates/cdk/src/wallet/mint_connector/http_client.rs +++ b/crates/cdk/src/wallet/mint_connector/http_client.rs @@ -270,7 +270,7 @@ impl HttpClient { match result.as_ref() { Err(Error::HttpError(status_code, _)) => { let status_code = status_code.to_owned().unwrap_or_default(); - if status_code <= 400 && status_code >= 499 { + if status_code >= 400 && status_code <= 499 { // 4xx errors won't be 'solved' by retrying return result; } From 2e63a631e4e162ef28c26237f083650f733e1582 Mon Sep 17 00:00:00 2001 From: Cesar Rodas Date: Mon, 18 Aug 2025 12:50:03 -0300 Subject: [PATCH 089/321] Fixed clippy --- crates/cdk/src/wallet/mint_connector/http_client.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/cdk/src/wallet/mint_connector/http_client.rs b/crates/cdk/src/wallet/mint_connector/http_client.rs index b9e289fac..577d012fd 100644 --- a/crates/cdk/src/wallet/mint_connector/http_client.rs +++ b/crates/cdk/src/wallet/mint_connector/http_client.rs @@ -270,7 +270,7 @@ impl HttpClient { match result.as_ref() { Err(Error::HttpError(status_code, _)) => { let status_code = status_code.to_owned().unwrap_or_default(); - if status_code >= 400 && status_code <= 499 { + if (400..=499).contains(&status_code) { // 4xx errors won't be 'solved' by retrying return result; } From 761ed82554481cf3be190f75d6881f856172faae Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Tue, 19 Aug 2025 14:57:14 +0100 Subject: [PATCH 090/321] feat: log to file (#967) --- Cargo.toml | 1 + crates/cdk-integration-tests/src/shared.rs | 15 +++ crates/cdk-mintd/Cargo.toml | 1 + crates/cdk-mintd/README.md | 56 ++++++++ crates/cdk-mintd/example.config.toml | 9 ++ crates/cdk-mintd/src/config.rs | 86 ++++++++++++ crates/cdk-mintd/src/env_vars/common.rs | 3 + crates/cdk-mintd/src/env_vars/info.rs | 23 +++- crates/cdk-mintd/src/lib.rs | 147 ++++++++++++++++++--- crates/cdk-mintd/src/main.rs | 10 +- crates/cdk-sql-common/src/mint/mod.rs | 1 - crates/cdk/src/mint/auth/mod.rs | 4 +- crates/cdk/src/mint/issue/mod.rs | 6 +- crates/cdk/src/mint/melt.rs | 39 ++++-- crates/cdk/src/mint/mod.rs | 14 +- misc/interactive_regtest_mprocs.sh | 8 ++ 16 files changed, 378 insertions(+), 45 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index a0b278c28..62c534db9 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -75,6 +75,7 @@ tokio-tungstenite = { version = "0.26.0", default-features = false } tokio-stream = "0.1.15" tracing = { version = "0.1", default-features = false, features = ["attributes", "log"] } tracing-subscriber = { version = "0.3.18", features = ["env-filter"] } +tracing-appender = "0.2" url = "2.3" uuid = { version = "1.17", features = ["v4", "serde"] } utoipa = { version = "5.3.1", features = [ diff --git a/crates/cdk-integration-tests/src/shared.rs b/crates/cdk-integration-tests/src/shared.rs index 68d03e23c..900e36a0e 100644 --- a/crates/cdk-integration-tests/src/shared.rs +++ b/crates/cdk-integration-tests/src/shared.rs @@ -168,6 +168,11 @@ pub fn create_fake_wallet_settings( .map(|(_, certs_dir)| certs_dir.clone()), input_fee_ppk: None, http_cache: cache::Config::default(), + logging: cdk_mintd::config::LoggingConfig { + output: cdk_mintd::config::LoggingOutput::Both, + console_level: Some("debug".to_string()), + file_level: Some("debug".to_string()), + }, enable_swagger_ui: None, }, mint_info: cdk_mintd::config::MintInfo::default(), @@ -210,6 +215,11 @@ pub fn create_cln_settings( signatory_certs: None, input_fee_ppk: None, http_cache: cache::Config::default(), + logging: cdk_mintd::config::LoggingConfig { + output: cdk_mintd::config::LoggingOutput::Both, + console_level: Some("debug".to_string()), + file_level: Some("debug".to_string()), + }, enable_swagger_ui: None, }, mint_info: cdk_mintd::config::MintInfo::default(), @@ -248,6 +258,11 @@ pub fn create_lnd_settings( signatory_certs: None, input_fee_ppk: None, http_cache: cache::Config::default(), + logging: cdk_mintd::config::LoggingConfig { + output: cdk_mintd::config::LoggingOutput::Both, + console_level: Some("debug".to_string()), + file_level: Some("debug".to_string()), + }, enable_swagger_ui: None, }, mint_info: cdk_mintd::config::MintInfo::default(), diff --git a/crates/cdk-mintd/Cargo.toml b/crates/cdk-mintd/Cargo.toml index ff95bcfd0..ed844cbf9 100644 --- a/crates/cdk-mintd/Cargo.toml +++ b/crates/cdk-mintd/Cargo.toml @@ -50,6 +50,7 @@ bitcoin.workspace = true tokio = { workspace = true, default-features = false, features = ["signal"] } tracing.workspace = true tracing-subscriber.workspace = true +tracing-appender.workspace = true futures.workspace = true serde.workspace = true bip39.workspace = true diff --git a/crates/cdk-mintd/README.md b/crates/cdk-mintd/README.md index 95e28c343..55acaad41 100644 --- a/crates/cdk-mintd/README.md +++ b/crates/cdk-mintd/README.md @@ -87,6 +87,60 @@ engine = "redb" ln_backend = "fakewallet" # Options: cln, lnd, lnbits, fakewallet ``` +### Logging Configuration + +You can configure where mintd outputs its logs using the `[info.logging]` section in your config file or environment variables: + +**Config file:** +```toml +[info.logging] +# Where to output logs: "stdout", "file", or "both" (default: "both") +output = "both" +# Log level for console output (default: "info") +console_level = "info" +# Log level for file output (default: "debug") +file_level = "debug" +``` + +**Environment variables:** +```bash +# Where to output logs: "stdout", "file", or "both" (default: "both") +export CDK_MINTD_LOGGING_OUTPUT="both" +# Log level for console output (default: "info") +export CDK_MINTD_LOGGING_CONSOLE_LEVEL="debug" +# Log level for file output (default: "debug") +export CDK_MINTD_LOGGING_FILE_LEVEL="debug" +``` + +**Available logging outputs:** +- `"stdout"` - Output logs only to console/terminal (stderr) +- `"file"` - Output logs only to rotating daily log files in `/logs/` +- `"both"` - Output logs to both console and files (default behavior) + +**Available log levels:** `error`, `warn`, `info`, `debug`, `trace` + +**Examples:** + +Console only with debug level: +```bash +export CDK_MINTD_LOGGING_OUTPUT="stdout" +export CDK_MINTD_LOGGING_CONSOLE_LEVEL="debug" +``` + +File only with debug level: +```toml +[info.logging] +output = "file" +file_level = "debug" +``` + +Both console (warn) and file (debug): +```bash +export CDK_MINTD_LOGGING_OUTPUT="both" +export CDK_MINTD_LOGGING_CONSOLE_LEVEL="warn" +export CDK_MINTD_LOGGING_FILE_LEVEL="debug" +``` + ## Usage ```bash @@ -98,6 +152,8 @@ cdk-mintd --config /path/to/config.toml # Start with specific work directory cdk-mintd --work-dir /path/to/work/dir +# Disable logging entirely +cdk-mintd --enable-logging false # Show help cdk-mintd --help diff --git a/crates/cdk-mintd/example.config.toml b/crates/cdk-mintd/example.config.toml index a5336559e..f3389fa5a 100644 --- a/crates/cdk-mintd/example.config.toml +++ b/crates/cdk-mintd/example.config.toml @@ -6,6 +6,15 @@ mnemonic = "" # input_fee_ppk = 0 # enable_swagger_ui = false +[info.logging] +# Where to output logs: "stdout", "file", or "both" (default: "both") +# Note: "stdout" actually outputs to stderr (standard error stream) +# output = "both" +# Log level for console output (default: "info") +# console_level = "info" +# Log level for file output (default: "debug") +# file_level = "debug" + [mint_management_rpc] enabled = false # address = "127.0.0.1" diff --git a/crates/cdk-mintd/src/config.rs b/crates/cdk-mintd/src/config.rs index 24d1a4810..4c9af2a6a 100644 --- a/crates/cdk-mintd/src/config.rs +++ b/crates/cdk-mintd/src/config.rs @@ -7,6 +7,44 @@ use cdk_axum::cache; use config::{Config, ConfigError, File}; use serde::{Deserialize, Serialize}; +#[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Default)] +#[serde(rename_all = "lowercase")] +pub enum LoggingOutput { + /// Log to stderr only + Stderr, + /// Log to file only + File, + /// Log to both stderr and file (default) + #[default] + Both, +} + +impl std::str::FromStr for LoggingOutput { + type Err = String; + + fn from_str(s: &str) -> Result { + match s.to_lowercase().as_str() { + "stderr" => Ok(LoggingOutput::Stderr), + "file" => Ok(LoggingOutput::File), + "both" => Ok(LoggingOutput::Both), + _ => Err(format!( + "Unknown logging output: {s}. Valid options: stdout, file, both" + )), + } + } +} + +#[derive(Debug, Clone, Serialize, Deserialize, Default)] +pub struct LoggingConfig { + /// Where to output logs: stdout, file, or both + #[serde(default)] + pub output: LoggingOutput, + /// Log level for console output (when stdout or both) + pub console_level: Option, + /// Log level for file output (when file or both) + pub file_level: Option, +} + #[derive(Clone, Serialize, Deserialize, Default)] pub struct Info { pub url: String, @@ -19,6 +57,10 @@ pub struct Info { pub http_cache: cache::Config, + /// Logging configuration + #[serde(default)] + pub logging: LoggingConfig, + /// When this is set to true, the mint exposes a Swagger UI for it's API at /// `[listen_host]:[listen_port]/swagger-ui` /// @@ -45,6 +87,7 @@ impl std::fmt::Debug for Info { .field("mnemonic", &mnemonic_display) .field("input_fee_ppk", &self.input_fee_ppk) .field("http_cache", &self.http_cache) + .field("logging", &self.logging) .field("enable_swagger_ui", &self.enable_swagger_ui) .finish() } @@ -422,6 +465,8 @@ impl Settings { #[cfg(test)] mod tests { + use std::str::FromStr; + use super::*; #[test] @@ -488,4 +533,45 @@ mod tests { assert!(!debug_output.contains("特殊字符 !@#$%^&*()")); assert!(debug_output.contains(" Self { @@ -58,6 +59,26 @@ impl Info { } } + // Logging configuration + if let Ok(output_str) = env::var(ENV_LOGGING_OUTPUT) { + if let Ok(output) = LoggingOutput::from_str(&output_str) { + self.logging.output = output; + } else { + tracing::warn!( + "Invalid logging output '{}' in environment variable. Valid options: stdout, file, both", + output_str + ); + } + } + + if let Ok(console_level) = env::var(ENV_LOGGING_CONSOLE_LEVEL) { + self.logging.console_level = Some(console_level); + } + + if let Ok(file_level) = env::var(ENV_LOGGING_FILE_LEVEL) { + self.logging.file_level = Some(file_level); + } + self.http_cache = self.http_cache.from_env(); self diff --git a/crates/cdk-mintd/src/lib.rs b/crates/cdk-mintd/src/lib.rs index 715b3cdb8..05b6966c2 100644 --- a/crates/cdk-mintd/src/lib.rs +++ b/crates/cdk-mintd/src/lib.rs @@ -51,6 +51,8 @@ use tower::ServiceBuilder; use tower_http::compression::CompressionLayer; use tower_http::decompression::RequestDecompressionLayer; use tower_http::trace::TraceLayer; +use tracing_appender::{non_blocking, rolling}; +use tracing_subscriber::fmt::writer::MakeWriterExt; use tracing_subscriber::EnvFilter; #[cfg(feature = "swagger")] use utoipa::OpenApi; @@ -94,7 +96,12 @@ async fn initial_setup( } /// Sets up and initializes a tracing subscriber with custom log filtering. -pub fn setup_tracing() { +/// Logs can be configured to output to stdout only, file only, or both. +/// Returns a guard that must be kept alive and properly dropped on shutdown. +pub fn setup_tracing( + work_dir: &Path, + logging_config: &config::LoggingConfig, +) -> Result> { let default_filter = "debug"; let hyper_filter = "hyper=warn"; let h2_filter = "h2=warn"; @@ -104,7 +111,99 @@ pub fn setup_tracing() { "{default_filter},{hyper_filter},{h2_filter},{tower_http}" )); - tracing_subscriber::fmt().with_env_filter(env_filter).init(); + use config::LoggingOutput; + match logging_config.output { + LoggingOutput::Stderr => { + // Console output only (stderr) + let console_level = logging_config + .console_level + .as_deref() + .unwrap_or("info") + .parse::() + .unwrap_or(tracing::Level::INFO); + + let stderr = std::io::stderr.with_max_level(console_level); + + tracing_subscriber::fmt() + .with_env_filter(env_filter) + .with_writer(stderr) + .init(); + + tracing::info!("Logging initialized: console only ({}+)", console_level); + Ok(None) + } + LoggingOutput::File => { + // File output only + let file_level = logging_config + .file_level + .as_deref() + .unwrap_or("debug") + .parse::() + .unwrap_or(tracing::Level::DEBUG); + + // Create logs directory in work_dir if it doesn't exist + let logs_dir = work_dir.join("logs"); + std::fs::create_dir_all(&logs_dir)?; + + // Set up file appender with daily rotation + let file_appender = rolling::daily(&logs_dir, "cdk-mintd.log"); + let (non_blocking_appender, guard) = non_blocking(file_appender); + + let file_writer = non_blocking_appender.with_max_level(file_level); + + tracing_subscriber::fmt() + .with_env_filter(env_filter) + .with_writer(file_writer) + .init(); + + tracing::info!( + "Logging initialized: file only at {}/cdk-mintd.log ({}+)", + logs_dir.display(), + file_level + ); + Ok(Some(guard)) + } + LoggingOutput::Both => { + // Both console and file output (stderr + file) + let console_level = logging_config + .console_level + .as_deref() + .unwrap_or("info") + .parse::() + .unwrap_or(tracing::Level::INFO); + let file_level = logging_config + .file_level + .as_deref() + .unwrap_or("debug") + .parse::() + .unwrap_or(tracing::Level::DEBUG); + + // Create logs directory in work_dir if it doesn't exist + let logs_dir = work_dir.join("logs"); + std::fs::create_dir_all(&logs_dir)?; + + // Set up file appender with daily rotation + let file_appender = rolling::daily(&logs_dir, "cdk-mintd.log"); + let (non_blocking_appender, guard) = non_blocking(file_appender); + + // Combine console output (stderr) and file output + let stderr = std::io::stderr.with_max_level(console_level); + let file_writer = non_blocking_appender.with_max_level(file_level); + + tracing_subscriber::fmt() + .with_env_filter(env_filter) + .with_writer(stderr.and(file_writer)) + .init(); + + tracing::info!( + "Logging initialized: console ({}+) and file at {}/cdk-mintd.log ({}+)", + console_level, + logs_dir.display(), + file_level + ); + Ok(Some(guard)) + } + } } /// Retrieves the work directory based on command-line arguments, environment variables, or system defaults. @@ -705,7 +804,7 @@ async fn start_services_with_shutdown( tracing::info!("Mint info already set, not using config file settings."); } } else { - tracing::warn!("RPC not enabled, using mint info from config."); + tracing::info!("RPC not enabled, using mint info from config."); mint.set_mint_info(mint_builder_info).await?; mint.set_quote_ttl(QuoteTTL::new(10_000, 10_000)).await?; } @@ -750,7 +849,7 @@ async fn start_services_with_shutdown( let listener = tokio::net::TcpListener::bind(socket_addr).await?; - tracing::debug!("listening on {}", listener.local_addr().unwrap()); + tracing::info!("listening on {}", listener.local_addr().unwrap()); // Wait for axum server to complete with custom shutdown signal let axum_result = axum::serve(listener, mint_service).with_graceful_shutdown(shutdown_signal); @@ -794,20 +893,32 @@ fn work_dir() -> Result { Ok(dir) } -/// The main entry point for the application when used as a library. -/// -/// This asynchronous function performs the following steps: -/// 1. Executes the initial setup, including loading configurations and initializing the database. -/// 2. Configures a `MintBuilder` instance with the local store and keystore based on the database. -/// 3. Applies additional custom configurations and authentication setup for the `MintBuilder`. -/// 4. Constructs a `Mint` instance from the configured `MintBuilder`. -/// 5. Checks and resolves the status of any pending mint and melt quotes. +/// The main entry point for the application when used as a library pub async fn run_mintd( work_dir: &Path, settings: &config::Settings, db_password: Option, + enable_logging: bool, ) -> Result<()> { - run_mintd_with_shutdown(work_dir, settings, shutdown_signal(), db_password).await + let _guard = if enable_logging { + setup_tracing(work_dir, &settings.info.logging)? + } else { + None + }; + + let result = run_mintd_with_shutdown(work_dir, settings, shutdown_signal(), db_password).await; + + // Explicitly drop the guard to ensure proper cleanup + if let Some(guard) = _guard { + tracing::info!("Shutting down logging worker thread"); + drop(guard); + // Give the worker thread a moment to flush any remaining logs + tokio::time::sleep(tokio::time::Duration::from_millis(100)).await; + } + + tracing::info!("Mintd shutdown"); + + result } /// Run mintd with a custom shutdown signal @@ -836,7 +947,7 @@ pub async fn run_mintd_with_shutdown( // Pending melt quotes where the payment has **failed** inputs are reset to unspent mint.check_pending_melt_quotes().await?; - start_services_with_shutdown( + let result = start_services_with_shutdown( mint.clone(), settings, ln_routers, @@ -844,7 +955,11 @@ pub async fn run_mintd_with_shutdown( mint.mint_info().await?, shutdown_signal, ) - .await?; + .await; - Ok(()) + // Ensure any remaining tracing data is flushed + // This is particularly important for file-based logging + tracing::debug!("Flushing remaining trace data"); + + result } diff --git a/crates/cdk-mintd/src/main.rs b/crates/cdk-mintd/src/main.rs index 8e8bdaeb8..468d0e23d 100644 --- a/crates/cdk-mintd/src/main.rs +++ b/crates/cdk-mintd/src/main.rs @@ -16,7 +16,7 @@ compile_error!( use anyhow::Result; use cdk_mintd::cli::CLIArgs; -use cdk_mintd::{get_work_directory, load_settings, setup_tracing}; +use cdk_mintd::{get_work_directory, load_settings}; use clap::Parser; use tokio::main; @@ -24,12 +24,7 @@ use tokio::main; async fn main() -> Result<()> { let args = CLIArgs::parse(); - if args.enable_logging { - setup_tracing(); - } - let work_dir = get_work_directory(&args).await?; - let settings = load_settings(&work_dir, args.config)?; #[cfg(feature = "sqlcipher")] @@ -38,5 +33,6 @@ async fn main() -> Result<()> { #[cfg(not(feature = "sqlcipher"))] let password = None; - cdk_mintd::run_mintd(&work_dir, &settings, password).await + // Use the main function that handles logging setup and cleanup + cdk_mintd::run_mintd(&work_dir, &settings, password, args.enable_logging).await } diff --git a/crates/cdk-sql-common/src/mint/mod.rs b/crates/cdk-sql-common/src/mint/mod.rs index be62fd33f..0d9593fff 100644 --- a/crates/cdk-sql-common/src/mint/mod.rs +++ b/crates/cdk-sql-common/src/mint/mod.rs @@ -700,7 +700,6 @@ VALUES (:quote_id, :amount, :timestamp); #[instrument(skip_all)] async fn add_mint_quote(&mut self, quote: MintQuote) -> Result<(), Self::Err> { - tracing::debug!("Adding quote with: {}", quote.payment_method); query( r#" INSERT INTO mint_quote ( diff --git a/crates/cdk/src/mint/auth/mod.rs b/crates/cdk/src/mint/auth/mod.rs index eb7d73a7e..571f8a0e3 100644 --- a/crates/cdk/src/mint/auth/mod.rs +++ b/crates/cdk/src/mint/auth/mod.rs @@ -49,14 +49,14 @@ impl Mint { endpoint: &ProtectedEndpoint, ) -> Result<(), Error> { let auth_required = if let Some(auth_required) = self.is_protected(endpoint).await? { - tracing::info!( + tracing::trace!( "Auth required for endpoint: {:?}, type: {:?}", endpoint, auth_required ); auth_required } else { - tracing::debug!("No auth required for endpoint: {:?}", endpoint); + tracing::trace!("No auth required for endpoint: {:?}", endpoint); return Ok(()); }; diff --git a/crates/cdk/src/mint/issue/mod.rs b/crates/cdk/src/mint/issue/mod.rs index 1f37d568e..df65ca8cd 100644 --- a/crates/cdk/src/mint/issue/mod.rs +++ b/crates/cdk/src/mint/issue/mod.rs @@ -293,7 +293,7 @@ impl Mint { quote.id, amount, unit, - create_invoice_response.request_lookup_id, + create_invoice_response.request_lookup_id.to_string(), ); let mut tx = self.localstore.begin_transaction().await?; @@ -364,7 +364,7 @@ impl Mint { if wait_payment_response.payment_amount == Amount::ZERO { tracing::warn!( "Received payment response with 0 amount with payment id {}.", - wait_payment_response.payment_id + wait_payment_response.payment_id.to_string() ); return Err(Error::AmountUndefined); @@ -413,7 +413,7 @@ impl Mint { "Received payment notification of {} for mint quote {} with payment id {}", wait_payment_response.payment_amount, mint_quote.id, - wait_payment_response.payment_id + wait_payment_response.payment_id.to_string() ); let quote_state = mint_quote.state(); diff --git a/crates/cdk/src/mint/melt.rs b/crates/cdk/src/mint/melt.rs index 9f14c8388..972d06915 100644 --- a/crates/cdk/src/mint/melt.rs +++ b/crates/cdk/src/mint/melt.rs @@ -202,7 +202,8 @@ impl Mint { ); tracing::debug!( - "New melt quote {} for {} {} with request id {}", + "New {} melt quote {} for {} {} with request id {}", + quote.payment_method, quote.id, amount_quote_unit, unit, @@ -308,7 +309,8 @@ impl Mint { ); tracing::debug!( - "New melt quote {} for {} {} with request id {}", + "New {} melt quote {} for {} {} with request id {}", + quote.payment_method, quote.id, amount, unit, @@ -578,7 +580,7 @@ impl Mint { // correct and the mint should pay the full invoice amount if inputs // > `then quote.amount` are included. This is checked in the // `verify_melt` method. - let partial_amount = match quote.unit { + let _partial_amount = match quote.unit { CurrencyUnit::Sat | CurrencyUnit::Msat => { match self.check_melt_expected_ln_fees("e, melt_request).await { Ok(amount) => amount, @@ -590,10 +592,10 @@ impl Mint { } _ => None, }; - tracing::debug!("partial_amount: {:?}", partial_amount); + let ln = match self.payment_processors.get(&PaymentProcessorKey::new( quote.unit.clone(), - PaymentMethod::Bolt11, + quote.payment_method.clone(), )) { Some(ln) => ln, None => { @@ -613,6 +615,7 @@ impl Mint { if pay.status == MeltQuoteState::Unknown || pay.status == MeltQuoteState::Failed => { + tracing::warn!("Got {} status when paying melt quote {} for {} {}. Checking with backend...", pay.status, quote.id, quote.amount, quote.unit); let check_response = if let Ok(ok) = check_payment_state(Arc::clone(ln), "e).await { ok @@ -733,6 +736,7 @@ impl Mint { Ok(res) } + /// Process melt request marking proofs as spent /// The melt request must be verifyed using [`Self::verify_melt_request`] /// before calling [`Self::process_melt_request`] @@ -746,8 +750,6 @@ impl Mint { payment_preimage: Option, total_spent: Amount, ) -> Result, Error> { - tracing::debug!("Processing melt quote: {}", melt_request.quote()); - let input_ys = melt_request.inputs().ys()?; proof_writer @@ -763,8 +765,10 @@ impl Mint { let mut change = None; + let inputs_amount = melt_request.inputs_amount()?; + // Check if there is change to return - if melt_request.inputs_amount()? > total_spent { + if inputs_amount > total_spent { // Check if wallet provided change outputs if let Some(outputs) = melt_request.outputs().clone() { let blinded_messages: Vec = @@ -831,10 +835,17 @@ impl Mint { proof_writer.commit(); tx.commit().await?; } else { + tracing::info!( + "Inputs for {} {} greater then spent on melt {} but change outputs not provided.", + quote.id, + inputs_amount, + total_spent + ); proof_writer.commit(); tx.commit().await?; } } else { + tracing::debug!("No change required for melt {}", quote.id); proof_writer.commit(); tx.commit().await?; } @@ -846,6 +857,18 @@ impl Mint { MeltQuoteState::Paid, ); + tracing::debug!( + "Melt for quote {} completed total spent {}, total inputs: {}, change given: {}", + quote.id, + total_spent, + inputs_amount, + change + .as_ref() + .map(|c| Amount::try_sum(c.iter().map(|a| a.amount)) + .expect("Change cannot overflow")) + .unwrap_or_default() + ); + Ok(MeltQuoteBolt11Response { amount: quote.amount, paid: Some(true), diff --git a/crates/cdk/src/mint/mod.rs b/crates/cdk/src/mint/mod.rs index 17c04fa23..8ebc94298 100644 --- a/crates/cdk/src/mint/mod.rs +++ b/crates/cdk/src/mint/mod.rs @@ -441,7 +441,7 @@ impl Mint { loop { tokio::select! { _ = shutdown.notified() => { - println!("Shutting down payment processors"); + tracing::info!("Shutting down payment processors"); break; } Some(result) = join_set.join_next() => { @@ -475,7 +475,6 @@ impl Mint { match result { Ok(mut stream) => { while let Some(request_lookup_id) = stream.next().await { - tracing::debug!("Received payment {:?}", request_lookup_id); if let Err(e) = Self::handle_payment_notification( &localstore, &pubsub_manager, @@ -517,11 +516,6 @@ impl Mint { .get_mint_quote_by_request_lookup_id(&wait_payment_response.payment_identifier) .await { - tracing::debug!( - "Received payment {} for quote-id {}", - wait_payment_response.payment_identifier, - mint_quote.id - ); Self::handle_mint_quote_payment( &mut tx, &mint_quote, @@ -747,6 +741,12 @@ impl Mint { tx.increment_mint_quote_amount_paid(&mint_quote.id, amount, melt_quote.id.to_string()) .await?; + tracing::info!( + "Melt quote {} paid Mint quote {}", + melt_quote.id, + mint_quote.id + ); + Ok(Some(amount)) } diff --git a/misc/interactive_regtest_mprocs.sh b/misc/interactive_regtest_mprocs.sh index c1f263e0e..6354c8de6 100755 --- a/misc/interactive_regtest_mprocs.sh +++ b/misc/interactive_regtest_mprocs.sh @@ -184,6 +184,9 @@ export CDK_MINTD_LISTEN_HOST="127.0.0.1" export CDK_MINTD_LISTEN_PORT=8085 export CDK_MINTD_LN_BACKEND="cln" export CDK_MINTD_MNEMONIC="eye survey guilt napkin crystal cup whisper salt luggage manage unveil loyal" +export CDK_MINTD_LOGGING_OUTPUT="both" +export CDK_MINTD_LOGGING_CONSOLE_LEVEL="debug" +export CDK_MINTD_LOGGING_FILE_LEVEL="debug" export RUST_BACKTRACE=1 export CDK_MINTD_DATABASE="$CDK_MINTD_DATABASE" @@ -192,6 +195,7 @@ echo "Project root: $PROJECT_ROOT" echo "Working directory: \$CDK_MINTD_WORK_DIR" echo "CLN RPC path: \$CDK_MINTD_CLN_RPC_PATH" echo "Database type: \$CDK_MINTD_DATABASE" +echo "Logging: \$CDK_MINTD_LOGGING_OUTPUT (console: \$CDK_MINTD_LOGGING_CONSOLE_LEVEL, file: \$CDK_MINTD_LOGGING_FILE_LEVEL)" echo "---" exec cargo run --bin cdk-mintd @@ -209,6 +213,9 @@ export CDK_MINTD_LISTEN_HOST="127.0.0.1" export CDK_MINTD_LISTEN_PORT=8087 export CDK_MINTD_LN_BACKEND="lnd" export CDK_MINTD_MNEMONIC="cattle gold bind busy sound reduce tone addict baby spend february strategy" +export CDK_MINTD_LOGGING_OUTPUT="both" +export CDK_MINTD_LOGGING_CONSOLE_LEVEL="debug" +export CDK_MINTD_LOGGING_FILE_LEVEL="debug" export RUST_BACKTRACE=1 export CDK_MINTD_DATABASE="$CDK_MINTD_DATABASE" @@ -217,6 +224,7 @@ echo "Project root: $PROJECT_ROOT" echo "Working directory: \$CDK_MINTD_WORK_DIR" echo "LND address: \$CDK_MINTD_LND_ADDRESS" echo "Database type: \$CDK_MINTD_DATABASE" +echo "Logging: \$CDK_MINTD_LOGGING_OUTPUT (console: \$CDK_MINTD_LOGGING_CONSOLE_LEVEL, file: \$CDK_MINTD_LOGGING_FILE_LEVEL)" echo "---" exec cargo run --bin cdk-mintd From 5c5075af7136ce427e5c94d653f11dfab7982b1e Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Tue, 19 Aug 2025 19:19:08 +0100 Subject: [PATCH 091/321] feat: refresh keysets (#974) * feat: refresh keysets * feat: rename get_mint_info to fetch_mint_info --- .../src/sub_commands/cat_device_login.rs | 2 +- crates/cdk-cli/src/sub_commands/cat_login.rs | 2 +- .../src/sub_commands/mint_blind_auth.rs | 6 ++--- crates/cdk-integration-tests/tests/bolt12.rs | 4 ---- .../cdk-integration-tests/tests/fake_auth.rs | 22 +++++++++---------- .../tests/integration_tests_pure.rs | 2 +- crates/cdk/examples/auth_wallet.rs | 2 +- crates/cdk/src/wallet/issue/issue_bolt11.rs | 12 +++------- crates/cdk/src/wallet/issue/issue_bolt12.rs | 12 +++------- crates/cdk/src/wallet/keysets.rs | 2 +- crates/cdk/src/wallet/melt/melt_bolt11.rs | 2 ++ crates/cdk/src/wallet/mod.rs | 4 ++-- crates/cdk/src/wallet/multi_mint_wallet.rs | 2 +- crates/cdk/src/wallet/receive.rs | 12 +--------- crates/cdk/src/wallet/swap.rs | 2 ++ 15 files changed, 33 insertions(+), 55 deletions(-) diff --git a/crates/cdk-cli/src/sub_commands/cat_device_login.rs b/crates/cdk-cli/src/sub_commands/cat_device_login.rs index 8c958f5cc..61f53c509 100644 --- a/crates/cdk-cli/src/sub_commands/cat_device_login.rs +++ b/crates/cdk-cli/src/sub_commands/cat_device_login.rs @@ -49,7 +49,7 @@ pub async fn cat_device_login( }; let mint_info = wallet - .get_mint_info() + .fetch_mint_info() .await? .ok_or(anyhow!("Mint info not found"))?; diff --git a/crates/cdk-cli/src/sub_commands/cat_login.rs b/crates/cdk-cli/src/sub_commands/cat_login.rs index dcfc57ebf..038f16642 100644 --- a/crates/cdk-cli/src/sub_commands/cat_login.rs +++ b/crates/cdk-cli/src/sub_commands/cat_login.rs @@ -51,7 +51,7 @@ pub async fn cat_login( }; let mint_info = wallet - .get_mint_info() + .fetch_mint_info() .await? .ok_or(anyhow!("Mint info not found"))?; diff --git a/crates/cdk-cli/src/sub_commands/mint_blind_auth.rs b/crates/cdk-cli/src/sub_commands/mint_blind_auth.rs index ec894343b..cf55b583b 100644 --- a/crates/cdk-cli/src/sub_commands/mint_blind_auth.rs +++ b/crates/cdk-cli/src/sub_commands/mint_blind_auth.rs @@ -47,7 +47,7 @@ pub async fn mint_blind_auth( } }; - wallet.get_mint_info().await?; + wallet.fetch_mint_info().await?; // Try to get the token from the provided argument or from the stored file let cat = match &sub_command_args.cat { @@ -83,7 +83,7 @@ pub async fn mint_blind_auth( println!("Attempting to refresh the access token..."); // Get the mint info to access OIDC configuration - if let Some(mint_info) = wallet.get_mint_info().await? { + if let Some(mint_info) = wallet.fetch_mint_info().await? { match refresh_access_token(&mint_info, &token_data.refresh_token).await { Ok((new_access_token, new_refresh_token)) => { println!("Successfully refreshed access token"); @@ -137,7 +137,7 @@ pub async fn mint_blind_auth( Some(amount) => amount, None => { let mint_info = wallet - .get_mint_info() + .fetch_mint_info() .await? .ok_or(anyhow!("Unknown mint info"))?; mint_info diff --git a/crates/cdk-integration-tests/tests/bolt12.rs b/crates/cdk-integration-tests/tests/bolt12.rs index ca25a4c92..8a900a800 100644 --- a/crates/cdk-integration-tests/tests/bolt12.rs +++ b/crates/cdk-integration-tests/tests/bolt12.rs @@ -266,8 +266,6 @@ async fn test_regtest_bolt12_melt() -> Result<()> { None, )?; - wallet.get_mint_info().await?; - let mint_amount = Amount::from(20_000); // Create a single-use BOLT12 quote @@ -323,8 +321,6 @@ async fn test_regtest_bolt12_mint_extra() -> Result<()> { None, )?; - wallet.get_mint_info().await?; - // Create a single-use BOLT12 quote let mint_quote = wallet.mint_bolt12_quote(None, None).await?; diff --git a/crates/cdk-integration-tests/tests/fake_auth.rs b/crates/cdk-integration-tests/tests/fake_auth.rs index dba54fbdf..26f089e37 100644 --- a/crates/cdk-integration-tests/tests/fake_auth.rs +++ b/crates/cdk-integration-tests/tests/fake_auth.rs @@ -42,7 +42,7 @@ async fn test_invalid_credentials() { .expect("Wallet"); let mint_info = wallet - .get_mint_info() + .fetch_mint_info() .await .expect("mint info") .expect("could not get mint info"); @@ -278,7 +278,7 @@ async fn test_mint_blind_auth() { .seed(Mnemonic::generate(12).unwrap().to_seed_normalized("")) .build() .expect("Wallet"); - let mint_info = wallet.get_mint_info().await.unwrap().unwrap(); + let mint_info = wallet.fetch_mint_info().await.unwrap().unwrap(); let (access_token, _) = get_access_token(&mint_info).await; @@ -310,7 +310,7 @@ async fn test_mint_with_auth() { .expect("Wallet"); let mint_info = wallet - .get_mint_info() + .fetch_mint_info() .await .expect("mint info") .expect("could not get mint info"); @@ -355,7 +355,7 @@ async fn test_swap_with_auth() { .seed(Mnemonic::generate(12).unwrap().to_seed_normalized("")) .build() .expect("Wallet"); - let mint_info = wallet.get_mint_info().await.unwrap().unwrap(); + let mint_info = wallet.fetch_mint_info().await.unwrap().unwrap(); let (access_token, _) = get_access_token(&mint_info).await; wallet.set_cat(access_token).await.unwrap(); @@ -410,7 +410,7 @@ async fn test_melt_with_auth() { .expect("Wallet"); let mint_info = wallet - .get_mint_info() + .fetch_mint_info() .await .expect("Mint info not found") .expect("Mint info not found"); @@ -452,7 +452,7 @@ async fn test_mint_auth_over_max() { let wallet = Arc::new(wallet); let mint_info = wallet - .get_mint_info() + .fetch_mint_info() .await .expect("Mint info not found") .expect("Mint info not found"); @@ -490,7 +490,7 @@ async fn test_reuse_auth_proof() { .seed(Mnemonic::generate(12).unwrap().to_seed_normalized("")) .build() .expect("Wallet"); - let mint_info = wallet.get_mint_info().await.unwrap().unwrap(); + let mint_info = wallet.fetch_mint_info().await.unwrap().unwrap(); let (access_token, _) = get_access_token(&mint_info).await; @@ -542,7 +542,7 @@ async fn test_melt_with_invalid_auth() { .seed(Mnemonic::generate(12).unwrap().to_seed_normalized("")) .build() .expect("Wallet"); - let mint_info = wallet.get_mint_info().await.unwrap().unwrap(); + let mint_info = wallet.fetch_mint_info().await.unwrap().unwrap(); let (access_token, _) = get_access_token(&mint_info).await; @@ -607,7 +607,7 @@ async fn test_refresh_access_token() { .expect("Wallet"); let mint_info = wallet - .get_mint_info() + .fetch_mint_info() .await .expect("mint info") .expect("could not get mint info"); @@ -663,7 +663,7 @@ async fn test_invalid_refresh_token() { .expect("Wallet"); let mint_info = wallet - .get_mint_info() + .fetch_mint_info() .await .expect("mint info") .expect("could not get mint info"); @@ -699,7 +699,7 @@ async fn test_auth_token_spending_order() { .expect("Wallet"); let mint_info = wallet - .get_mint_info() + .fetch_mint_info() .await .expect("mint info") .expect("could not get mint info"); diff --git a/crates/cdk-integration-tests/tests/integration_tests_pure.rs b/crates/cdk-integration-tests/tests/integration_tests_pure.rs index fe22cfbf1..8cb645e7c 100644 --- a/crates/cdk-integration-tests/tests/integration_tests_pure.rs +++ b/crates/cdk-integration-tests/tests/integration_tests_pure.rs @@ -196,7 +196,7 @@ async fn test_mint_nut06() { let initial_mint_url = wallet_alice.mint_url.clone(); let mint_info_before = wallet_alice - .get_mint_info() + .fetch_mint_info() .await .expect("Failed to get mint info") .unwrap(); diff --git a/crates/cdk/examples/auth_wallet.rs b/crates/cdk/examples/auth_wallet.rs index 27b28092d..d6efe6bbb 100644 --- a/crates/cdk/examples/auth_wallet.rs +++ b/crates/cdk/examples/auth_wallet.rs @@ -37,7 +37,7 @@ async fn main() -> Result<(), Error> { let wallet = Wallet::new(mint_url, unit, Arc::new(localstore), seed, None)?; let mint_info = wallet - .get_mint_info() + .fetch_mint_info() .await .expect("mint info") .expect("could not get mint info"); diff --git a/crates/cdk/src/wallet/issue/issue_bolt11.rs b/crates/cdk/src/wallet/issue/issue_bolt11.rs index bf613ae55..af436ef26 100644 --- a/crates/cdk/src/wallet/issue/issue_bolt11.rs +++ b/crates/cdk/src/wallet/issue/issue_bolt11.rs @@ -52,6 +52,8 @@ impl Wallet { let mint_url = self.mint_url.clone(); let unit = self.unit.clone(); + self.refresh_keysets().await?; + // If we have a description, we check that the mint supports it. if description.is_some() { let settings = self @@ -194,15 +196,7 @@ impl Wallet { amount_split_target: SplitTarget, spending_conditions: Option, ) -> Result { - // Check that mint is in store of mints - if self - .localstore - .get_mint(self.mint_url.clone()) - .await? - .is_none() - { - self.get_mint_info().await?; - } + self.refresh_keysets().await?; let quote_info = self .localstore diff --git a/crates/cdk/src/wallet/issue/issue_bolt12.rs b/crates/cdk/src/wallet/issue/issue_bolt12.rs index 5ac6964e6..cf547798b 100644 --- a/crates/cdk/src/wallet/issue/issue_bolt12.rs +++ b/crates/cdk/src/wallet/issue/issue_bolt12.rs @@ -29,6 +29,8 @@ impl Wallet { let mint_url = self.mint_url.clone(); let unit = &self.unit; + self.refresh_keysets().await?; + // If we have a description, we check that the mint supports it. if description.is_some() { let mint_method_settings = self @@ -83,15 +85,7 @@ impl Wallet { amount_split_target: SplitTarget, spending_conditions: Option, ) -> Result { - // Check that mint is in store of mints - if self - .localstore - .get_mint(self.mint_url.clone()) - .await? - .is_none() - { - self.get_mint_info().await?; - } + self.refresh_keysets().await?; let quote_info = self.localstore.get_mint_quote(quote_id).await?; diff --git a/crates/cdk/src/wallet/keysets.rs b/crates/cdk/src/wallet/keysets.rs index ae9997933..302b8e85d 100644 --- a/crates/cdk/src/wallet/keysets.rs +++ b/crates/cdk/src/wallet/keysets.rs @@ -82,7 +82,7 @@ impl Wallet { #[instrument(skip(self))] pub async fn refresh_keysets(&self) -> Result { tracing::debug!("Refreshing keysets and ensuring we have keys"); - let _ = self.get_mint_info().await?; + let _ = self.fetch_mint_info().await?; // Fetch all current keysets from mint let keysets_response = self.client.get_mint_keysets().await?; diff --git a/crates/cdk/src/wallet/melt/melt_bolt11.rs b/crates/cdk/src/wallet/melt/melt_bolt11.rs index 87ed0f24a..9f82c1e85 100644 --- a/crates/cdk/src/wallet/melt/melt_bolt11.rs +++ b/crates/cdk/src/wallet/melt/melt_bolt11.rs @@ -48,6 +48,8 @@ impl Wallet { request: String, options: Option, ) -> Result { + self.refresh_keysets().await?; + let invoice = Bolt11Invoice::from_str(&request)?; let quote_request = MeltQuoteBolt11Request { diff --git a/crates/cdk/src/wallet/mod.rs b/crates/cdk/src/wallet/mod.rs index 2099fa49b..391476200 100644 --- a/crates/cdk/src/wallet/mod.rs +++ b/crates/cdk/src/wallet/mod.rs @@ -249,7 +249,7 @@ impl Wallet { /// Query mint for current mint information #[instrument(skip(self))] - pub async fn get_mint_info(&self) -> Result, Error> { + pub async fn fetch_mint_info(&self) -> Result, Error> { match self.client.get_mint_info().await { Ok(mint_info) => { // If mint provides time make sure it is accurate @@ -382,7 +382,7 @@ impl Wallet { .await? .is_none() { - self.get_mint_info().await?; + self.fetch_mint_info().await?; } let keysets = self.load_mint_keysets().await?; diff --git a/crates/cdk/src/wallet/multi_mint_wallet.rs b/crates/cdk/src/wallet/multi_mint_wallet.rs index f5c7d2bae..7a07aedc1 100644 --- a/crates/cdk/src/wallet/multi_mint_wallet.rs +++ b/crates/cdk/src/wallet/multi_mint_wallet.rs @@ -78,7 +78,7 @@ impl MultiMintWallet { target_proof_count, )?; - wallet.get_mint_info().await?; + wallet.fetch_mint_info().await?; self.add_wallet(wallet.clone()).await; diff --git a/crates/cdk/src/wallet/receive.rs b/crates/cdk/src/wallet/receive.rs index 0772a7642..607f6dbf3 100644 --- a/crates/cdk/src/wallet/receive.rs +++ b/crates/cdk/src/wallet/receive.rs @@ -27,18 +27,8 @@ impl Wallet { memo: Option, ) -> Result { let mint_url = &self.mint_url; - // Add mint if it does not exist in the store - if self - .localstore - .get_mint(self.mint_url.clone()) - .await? - .is_none() - { - tracing::debug!("Mint not in localstore fetching info for: {mint_url}"); - self.get_mint_info().await?; - } - let _ = self.fetch_active_keyset().await?; + self.refresh_keysets().await?; let active_keyset_id = self.fetch_active_keyset().await?.id; diff --git a/crates/cdk/src/wallet/swap.rs b/crates/cdk/src/wallet/swap.rs index 6a5affb4b..fc70dafa4 100644 --- a/crates/cdk/src/wallet/swap.rs +++ b/crates/cdk/src/wallet/swap.rs @@ -21,6 +21,8 @@ impl Wallet { spending_conditions: Option, include_fees: bool, ) -> Result, Error> { + self.refresh_keysets().await?; + tracing::info!("Swapping"); let mint_url = &self.mint_url; let unit = &self.unit; From ecdc78135d4819aa415cbc06f2f055f410d046e0 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Wed, 20 Aug 2025 11:20:30 +0100 Subject: [PATCH 092/321] refactor(cdk): defer BOLT12 invoice fetching to payment execution (#978) * refactor(cdk): defer BOLT12 invoice fetching to payment execution Move BOLT12 invoice generation from quote creation to payment time, make request_lookup_id optional for offers, and simplify payment structures by removing unnecessary boxing and intermediate storage of invoices. --- crates/cdk-cln/src/lib.rs | 107 +++++++++--------- crates/cdk-common/src/mint.rs | 8 +- crates/cdk-common/src/payment.rs | 19 +--- crates/cdk-fake-wallet/Cargo.toml | 1 + crates/cdk-fake-wallet/src/lib.rs | 11 +- crates/cdk-lnbits/src/lib.rs | 5 +- crates/cdk-lnd/src/lib.rs | 5 +- .../cdk-payment-processor/src/proto/client.rs | 1 - crates/cdk-payment-processor/src/proto/mod.rs | 28 +---- .../src/proto/payment_processor.proto | 13 +-- .../cdk-payment-processor/src/proto/server.rs | 2 - crates/cdk-sql-common/src/mint/migrations.rs | 2 + ...remove_request_lookup_kind_constraints.sql | 6 + ...remove_request_lookup_kind_constraints.sql | 35 ++++++ crates/cdk-sql-common/src/mint/mod.rs | 49 ++++---- crates/cdk/src/mint/melt.rs | 59 +++++----- crates/cdk/src/mint/start_up_check.rs | 60 +++++----- 17 files changed, 192 insertions(+), 219 deletions(-) create mode 100644 crates/cdk-sql-common/src/mint/migrations/postgres/2_remove_request_lookup_kind_constraints.sql create mode 100644 crates/cdk-sql-common/src/mint/migrations/sqlite/20250819200000_remove_request_lookup_kind_constraints.sql diff --git a/crates/cdk-cln/src/lib.rs b/crates/cdk-cln/src/lib.rs index d3c8d53c4..616d79fca 100644 --- a/crates/cdk-cln/src/lib.rs +++ b/crates/cdk-cln/src/lib.rs @@ -307,13 +307,12 @@ impl MintPayment for Cln { let fee = max(relative_fee_reserve, absolute_fee_reserve); Ok(PaymentQuoteResponse { - request_lookup_id: PaymentIdentifier::PaymentHash( + request_lookup_id: Some(PaymentIdentifier::PaymentHash( *bolt11_options.bolt11.payment_hash().as_ref(), - ), + )), amount, fee: fee.into(), state: MeltQuoteState::Unpaid, - options: None, unit: unit.clone(), }) } @@ -341,52 +340,11 @@ impl MintPayment for Cln { let absolute_fee_reserve: u64 = self.fee_reserve.min_fee_reserve.into(); let fee = max(relative_fee_reserve, absolute_fee_reserve); - let cln_response; - { - // Fetch invoice from offer - let mut cln_client = self.cln_client().await?; - - cln_response = cln_client - .call_typed(&FetchinvoiceRequest { - amount_msat: Some(CLN_Amount::from_msat(amount_msat)), - payer_metadata: None, - payer_note: None, - quantity: None, - recurrence_counter: None, - recurrence_label: None, - recurrence_start: None, - timeout: None, - offer: offer.to_string(), - bip353: None, - }) - .await - .map_err(|err| { - tracing::error!("Could not fetch invoice for offer: {:?}", err); - Error::ClnRpc(err) - })?; - } - - let decode_response = self.decode_string(cln_response.invoice.clone()).await?; - - let options = payment::PaymentQuoteOptions::Bolt12 { - invoice: Some(cln_response.invoice.into()), - }; - Ok(PaymentQuoteResponse { - request_lookup_id: PaymentIdentifier::Bolt12PaymentHash( - hex::decode( - decode_response - .invoice_payment_hash - .ok_or(Error::UnknownInvoice)?, - ) - .unwrap() - .try_into() - .map_err(|_| Error::InvalidHash)?, - ), + request_lookup_id: None, amount, fee: fee.into(), state: MeltQuoteState::Unpaid, - options: Some(options), unit: unit.clone(), }) } @@ -403,7 +361,9 @@ impl MintPayment for Cln { let mut partial_amount: Option = None; let mut amount_msat: Option = None; - let invoice = match options { + let mut cln_client = self.cln_client().await?; + + let invoice = match &options { OutgoingPaymentOptions::Bolt11(bolt11_options) => { let payment_identifier = PaymentIdentifier::PaymentHash(*bolt11_options.bolt11.payment_hash().as_ref()); @@ -424,10 +384,42 @@ impl MintPayment for Cln { bolt11_options.bolt11.to_string() } OutgoingPaymentOptions::Bolt12(bolt12_options) => { - let bolt12_invoice = bolt12_options.invoice.ok_or(Error::UnknownInvoice)?; - let decode_response = self - .decode_string(String::from_utf8(bolt12_invoice.clone()).map_err(Error::Utf8)?) - .await?; + let offer = &bolt12_options.offer; + + let amount_msat: u64 = if let Some(amount) = bolt12_options.melt_options { + amount.amount_msat().into() + } else { + // Fall back to offer amount + let decode_response = self.decode_string(offer.to_string()).await?; + + decode_response + .offer_amount_msat + .ok_or(Error::UnknownInvoiceAmount)? + .msat() + }; + + // Fetch invoice from offer + + let cln_response = cln_client + .call_typed(&FetchinvoiceRequest { + amount_msat: Some(CLN_Amount::from_msat(amount_msat)), + payer_metadata: None, + payer_note: None, + quantity: None, + recurrence_counter: None, + recurrence_label: None, + recurrence_start: None, + timeout: None, + offer: offer.to_string(), + bip353: None, + }) + .await + .map_err(|err| { + tracing::error!("Could not fetch invoice for offer: {:?}", err); + Error::ClnRpc(err) + })?; + + let decode_response = self.decode_string(cln_response.invoice.clone()).await?; let payment_identifier = PaymentIdentifier::Bolt12PaymentHash( hex::decode( @@ -443,12 +435,11 @@ impl MintPayment for Cln { self.check_outgoing_unpaided(&payment_identifier).await?; max_fee_msat = bolt12_options.max_fee_amount.map(|a| a.into()); - String::from_utf8(bolt12_invoice).map_err(Error::Utf8)? + + cln_response.invoice } }; - let mut cln_client = self.cln_client().await?; - let cln_response = cln_client .call_typed(&PayRequest { bolt11: invoice, @@ -475,8 +466,14 @@ impl MintPayment for Cln { PayStatus::FAILED => MeltQuoteState::Failed, }; - let payment_identifier = - PaymentIdentifier::PaymentHash(*pay_response.payment_hash.as_ref()); + let payment_identifier = match options { + OutgoingPaymentOptions::Bolt11(_) => { + PaymentIdentifier::PaymentHash(*pay_response.payment_hash.as_ref()) + } + OutgoingPaymentOptions::Bolt12(_) => { + PaymentIdentifier::Bolt12PaymentHash(*pay_response.payment_hash.as_ref()) + } + }; MakePaymentResponse { payment_proof: Some(hex::encode(pay_response.payment_preimage.to_vec())), diff --git a/crates/cdk-common/src/mint.rs b/crates/cdk-common/src/mint.rs index 49b94d5bc..b4130f0b2 100644 --- a/crates/cdk-common/src/mint.rs +++ b/crates/cdk-common/src/mint.rs @@ -246,7 +246,7 @@ pub struct MeltQuote { /// Payment preimage pub payment_preimage: Option, /// Value used by ln backend to look up state of request - pub request_lookup_id: PaymentIdentifier, + pub request_lookup_id: Option, /// Payment options /// /// Used for amountless invoices and MPP payments @@ -270,7 +270,7 @@ impl MeltQuote { amount: Amount, fee_reserve: Amount, expiry: u64, - request_lookup_id: PaymentIdentifier, + request_lookup_id: Option, options: Option, payment_method: PaymentMethod, ) -> Self { @@ -433,8 +433,6 @@ pub enum MeltPaymentRequest { /// Offer #[serde(with = "offer_serde")] offer: Box, - /// Invoice - invoice: Option>, }, } @@ -442,7 +440,7 @@ impl std::fmt::Display for MeltPaymentRequest { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { match self { MeltPaymentRequest::Bolt11 { bolt11 } => write!(f, "{bolt11}"), - MeltPaymentRequest::Bolt12 { offer, invoice: _ } => write!(f, "{offer}"), + MeltPaymentRequest::Bolt12 { offer } => write!(f, "{offer}"), } } } diff --git a/crates/cdk-common/src/payment.rs b/crates/cdk-common/src/payment.rs index 923c0f059..c9c7a9204 100644 --- a/crates/cdk-common/src/payment.rs +++ b/crates/cdk-common/src/payment.rs @@ -193,8 +193,6 @@ pub struct Bolt12OutgoingPaymentOptions { pub max_fee_amount: Option, /// Optional timeout in seconds pub timeout_secs: Option, - /// Bolt12 Invoice - pub invoice: Option>, /// Melt options pub melt_options: Option, } @@ -221,7 +219,7 @@ impl TryFrom for OutgoingPaymentOptions { melt_options: melt_quote.options, }, ))), - MeltPaymentRequest::Bolt12 { offer, invoice } => { + MeltPaymentRequest::Bolt12 { offer } => { let melt_options = match melt_quote.options { None => None, Some(MeltOptions::Mpp { mpp: _ }) => return Err(Error::UnsupportedUnit), @@ -233,7 +231,6 @@ impl TryFrom for OutgoingPaymentOptions { max_fee_amount: Some(melt_quote.fee_reserve), timeout_secs: None, offer: *offer, - invoice, melt_options, }, ))) @@ -343,7 +340,7 @@ pub struct MakePaymentResponse { #[derive(Debug, Clone, Hash, PartialEq, Eq, Serialize, Deserialize)] pub struct PaymentQuoteResponse { /// Request look up id - pub request_lookup_id: PaymentIdentifier, + pub request_lookup_id: Option, /// Amount pub amount: Amount, /// Fee required for melt @@ -352,18 +349,6 @@ pub struct PaymentQuoteResponse { pub unit: CurrencyUnit, /// Status pub state: MeltQuoteState, - /// Payment Quote Options - pub options: Option, -} - -/// Payment quote options -#[derive(Debug, Clone, Hash, PartialEq, Eq, Serialize, Deserialize)] -pub enum PaymentQuoteOptions { - /// Bolt12 payment options - Bolt12 { - /// Bolt12 invoice - invoice: Option>, - }, } /// Ln backend settings diff --git a/crates/cdk-fake-wallet/Cargo.toml b/crates/cdk-fake-wallet/Cargo.toml index 0b98f5039..a9b365a8e 100644 --- a/crates/cdk-fake-wallet/Cargo.toml +++ b/crates/cdk-fake-wallet/Cargo.toml @@ -25,3 +25,4 @@ lightning-invoice.workspace = true lightning.workspace = true tokio-stream.workspace = true reqwest.workspace = true +uuid.workspace = true diff --git a/crates/cdk-fake-wallet/src/lib.rs b/crates/cdk-fake-wallet/src/lib.rs index 54c931e81..13a5fee97 100644 --- a/crates/cdk-fake-wallet/src/lib.rs +++ b/crates/cdk-fake-wallet/src/lib.rs @@ -43,6 +43,7 @@ use tokio::time; use tokio_stream::wrappers::ReceiverStream; use tokio_util::sync::CancellationToken; use tracing::instrument; +use uuid::Uuid; pub mod error; @@ -354,7 +355,7 @@ impl MintPayment for FakeWallet { }; let payment_id = PaymentIdentifier::PaymentHash(*bolt11_options.bolt11.payment_hash().as_ref()); - (amount_msat, payment_id) + (amount_msat, Some(payment_id)) } OutgoingPaymentOptions::Bolt12(bolt12_options) => { let offer = bolt12_options.offer; @@ -369,10 +370,7 @@ impl MintPayment for FakeWallet { _ => return Err(Error::UnknownInvoiceAmount.into()), } }; - ( - amount_msat, - PaymentIdentifier::OfferId(offer.id().to_string()), - ) + (amount_msat, None) } }; @@ -390,7 +388,6 @@ impl MintPayment for FakeWallet { amount, fee: fee.into(), state: MeltQuoteState::Unpaid, - options: None, unit: unit.clone(), }) } @@ -471,7 +468,7 @@ impl MintPayment for FakeWallet { Ok(MakePaymentResponse { payment_proof: Some("".to_string()), - payment_lookup_id: PaymentIdentifier::OfferId(bolt12.id().to_string()), + payment_lookup_id: PaymentIdentifier::CustomId(Uuid::new_v4().to_string()), status: MeltQuoteState::Paid, total_spent: total_spent + 1.into(), unit: unit.clone(), diff --git a/crates/cdk-lnbits/src/lib.rs b/crates/cdk-lnbits/src/lib.rs index 3703a47e7..f71b49776 100644 --- a/crates/cdk-lnbits/src/lib.rs +++ b/crates/cdk-lnbits/src/lib.rs @@ -204,13 +204,12 @@ impl MintPayment for LNbits { let fee = max(relative_fee_reserve, absolute_fee_reserve); Ok(PaymentQuoteResponse { - request_lookup_id: PaymentIdentifier::PaymentHash( + request_lookup_id: Some(PaymentIdentifier::PaymentHash( *bolt11_options.bolt11.payment_hash().as_ref(), - ), + )), amount, fee: fee.into(), state: MeltQuoteState::Unpaid, - options: None, unit: unit.clone(), }) } diff --git a/crates/cdk-lnd/src/lib.rs b/crates/cdk-lnd/src/lib.rs index 98296e945..0dfe7ca09 100644 --- a/crates/cdk-lnd/src/lib.rs +++ b/crates/cdk-lnd/src/lib.rs @@ -248,13 +248,12 @@ impl MintPayment for Lnd { let fee = max(relative_fee_reserve, absolute_fee_reserve); Ok(PaymentQuoteResponse { - request_lookup_id: PaymentIdentifier::PaymentHash( + request_lookup_id: Some(PaymentIdentifier::PaymentHash( *bolt11_options.bolt11.payment_hash().as_ref(), - ), + )), amount, fee: fee.into(), state: MeltQuoteState::Unpaid, - options: None, unit: unit.clone(), }) } diff --git a/crates/cdk-payment-processor/src/proto/client.rs b/crates/cdk-payment-processor/src/proto/client.rs index 58b477ee1..cad434d19 100644 --- a/crates/cdk-payment-processor/src/proto/client.rs +++ b/crates/cdk-payment-processor/src/proto/client.rs @@ -229,7 +229,6 @@ impl MintPayment for PaymentProcessorClient { offer: opts.offer.to_string(), max_fee_amount: opts.max_fee_amount.map(Into::into), timeout_secs: opts.timeout_secs, - invoice: opts.invoice, melt_options: opts.melt_options.map(Into::into), }, )), diff --git a/crates/cdk-payment-processor/src/proto/mod.rs b/crates/cdk-payment-processor/src/proto/mod.rs index d7788a144..cf5995d96 100644 --- a/crates/cdk-payment-processor/src/proto/mod.rs +++ b/crates/cdk-payment-processor/src/proto/mod.rs @@ -137,22 +137,11 @@ impl TryFrom for CreateIncomingPaymentResponse { impl From for PaymentQuoteResponse { fn from(value: cdk_common::payment::PaymentQuoteResponse) -> Self { Self { - request_identifier: Some(value.request_lookup_id.into()), + request_identifier: value.request_lookup_id.map(|i| i.into()), amount: value.amount.into(), fee: value.fee.into(), unit: value.unit.to_string(), state: QuoteState::from(value.state).into(), - melt_options: value.options.map(|opt| match opt { - cdk_common::payment::PaymentQuoteOptions::Bolt12 { invoice } => { - PaymentQuoteOptions { - melt_options: Some(payment_quote_options::MeltOptions::Bolt12( - Bolt12Options { - invoice: invoice.map(String::from_utf8).and_then(|r| r.ok()), - }, - )), - } - } - }), } } } @@ -160,26 +149,15 @@ impl From for PaymentQuoteResponse { impl From for cdk_common::payment::PaymentQuoteResponse { fn from(value: PaymentQuoteResponse) -> Self { let state_val = value.state(); - let request_identifier = value - .request_identifier - .expect("request identifier required"); + let request_identifier = value.request_identifier; Self { request_lookup_id: request_identifier - .try_into() - .expect("valid request identifier"), + .map(|i| i.try_into().expect("valid request identifier")), amount: value.amount.into(), fee: value.fee.into(), unit: CurrencyUnit::from_str(&value.unit).unwrap_or_default(), state: state_val.into(), - options: value.melt_options.map(|opt| match opt.melt_options { - Some(payment_quote_options::MeltOptions::Bolt12(bolt12)) => { - cdk_common::payment::PaymentQuoteOptions::Bolt12 { - invoice: bolt12.invoice.as_deref().map(str::as_bytes).map(Vec::from), - } - } - None => unreachable!(), - }), } } } diff --git a/crates/cdk-payment-processor/src/proto/payment_processor.proto b/crates/cdk-payment-processor/src/proto/payment_processor.proto index 7a32187de..187c6eed5 100644 --- a/crates/cdk-payment-processor/src/proto/payment_processor.proto +++ b/crates/cdk-payment-processor/src/proto/payment_processor.proto @@ -105,23 +105,13 @@ enum QuoteState { ISSUED = 5; } -message Bolt12Options { - optional string invoice = 1; -} - -message PaymentQuoteOptions { - oneof melt_options { - Bolt12Options bolt12 = 1; - } -} message PaymentQuoteResponse { PaymentIdentifier request_identifier = 1; uint64 amount = 2; uint64 fee = 3; QuoteState state = 4; - optional PaymentQuoteOptions melt_options = 5; - string unit = 6; + string unit = 5; } message Bolt11OutgoingPaymentOptions { @@ -135,7 +125,6 @@ message Bolt12OutgoingPaymentOptions { string offer = 1; optional uint64 max_fee_amount = 2; optional uint64 timeout_secs = 3; - optional bytes invoice = 4; optional MeltOptions melt_options = 5; } diff --git a/crates/cdk-payment-processor/src/proto/server.rs b/crates/cdk-payment-processor/src/proto/server.rs index d983cf447..9085c3fd1 100644 --- a/crates/cdk-payment-processor/src/proto/server.rs +++ b/crates/cdk-payment-processor/src/proto/server.rs @@ -250,7 +250,6 @@ impl CdkPaymentProcessor for PaymentProcessorServer { offer: Offer::from_str(&request.request).unwrap(), max_fee_amount: None, timeout_secs: None, - invoice: None, melt_options: request.options.map(Into::into), }, )) @@ -308,7 +307,6 @@ impl CdkPaymentProcessor for PaymentProcessorServer { offer, max_fee_amount: opts.max_fee_amount.map(Into::into), timeout_secs: opts.timeout_secs, - invoice: opts.invoice, melt_options: opts.melt_options.map(Into::into), }), ); diff --git a/crates/cdk-sql-common/src/mint/migrations.rs b/crates/cdk-sql-common/src/mint/migrations.rs index 4b5a69679..ed14f1712 100644 --- a/crates/cdk-sql-common/src/mint/migrations.rs +++ b/crates/cdk-sql-common/src/mint/migrations.rs @@ -2,6 +2,7 @@ /// Auto-generated by build.rs pub static MIGRATIONS: &[(&str, &str, &str)] = &[ ("postgres", "1_initial.sql", include_str!(r#"./migrations/postgres/1_initial.sql"#)), + ("postgres", "2_remove_request_lookup_kind_constraints.sql", include_str!(r#"./migrations/postgres/2_remove_request_lookup_kind_constraints.sql"#)), ("sqlite", "1_fix_sqlx_migration.sql", include_str!(r#"./migrations/sqlite/1_fix_sqlx_migration.sql"#)), ("sqlite", "20240612124932_init.sql", include_str!(r#"./migrations/sqlite/20240612124932_init.sql"#)), ("sqlite", "20240618195700_quote_state.sql", include_str!(r#"./migrations/sqlite/20240618195700_quote_state.sql"#)), @@ -25,4 +26,5 @@ pub static MIGRATIONS: &[(&str, &str, &str)] = &[ ("sqlite", "20250626120251_rename_blind_message_y_to_b.sql", include_str!(r#"./migrations/sqlite/20250626120251_rename_blind_message_y_to_b.sql"#)), ("sqlite", "20250706101057_bolt12.sql", include_str!(r#"./migrations/sqlite/20250706101057_bolt12.sql"#)), ("sqlite", "20250812132015_drop_melt_request.sql", include_str!(r#"./migrations/sqlite/20250812132015_drop_melt_request.sql"#)), + ("sqlite", "20250819200000_remove_request_lookup_kind_constraints.sql", include_str!(r#"./migrations/sqlite/20250819200000_remove_request_lookup_kind_constraints.sql"#)), ]; diff --git a/crates/cdk-sql-common/src/mint/migrations/postgres/2_remove_request_lookup_kind_constraints.sql b/crates/cdk-sql-common/src/mint/migrations/postgres/2_remove_request_lookup_kind_constraints.sql new file mode 100644 index 000000000..786743c0c --- /dev/null +++ b/crates/cdk-sql-common/src/mint/migrations/postgres/2_remove_request_lookup_kind_constraints.sql @@ -0,0 +1,6 @@ +-- Set existing NULL or empty request_lookup_id_kind values to 'payment_hash' in melt_quote +UPDATE melt_quote SET request_lookup_id_kind = 'payment_hash' WHERE request_lookup_id_kind IS NULL OR request_lookup_id_kind = ''; + +-- Remove NOT NULL constraint and default value from request_lookup_id_kind in melt_quote table +ALTER TABLE melt_quote ALTER COLUMN request_lookup_id_kind DROP NOT NULL; +ALTER TABLE melt_quote ALTER COLUMN request_lookup_id_kind DROP DEFAULT; diff --git a/crates/cdk-sql-common/src/mint/migrations/sqlite/20250819200000_remove_request_lookup_kind_constraints.sql b/crates/cdk-sql-common/src/mint/migrations/sqlite/20250819200000_remove_request_lookup_kind_constraints.sql new file mode 100644 index 000000000..ec0bb7886 --- /dev/null +++ b/crates/cdk-sql-common/src/mint/migrations/sqlite/20250819200000_remove_request_lookup_kind_constraints.sql @@ -0,0 +1,35 @@ + +-- Set existing NULL or empty request_lookup_id_kind values to 'payment_hash' in melt_quote +UPDATE melt_quote SET request_lookup_id_kind = 'payment_hash' WHERE request_lookup_id_kind IS NULL OR request_lookup_id_kind = ''; + +-- Remove NOT NULL constraint and default value from request_lookup_id_kind in melt_quote table +CREATE TABLE melt_quote_temp ( + id TEXT PRIMARY KEY, + unit TEXT NOT NULL, + amount INTEGER NOT NULL, + request TEXT NOT NULL, + fee_reserve INTEGER NOT NULL, + expiry INTEGER NOT NULL, + state TEXT CHECK ( + state IN ('UNPAID', 'PENDING', 'PAID') + ) NOT NULL DEFAULT 'UNPAID', + payment_preimage TEXT, + request_lookup_id TEXT, + created_time INTEGER NOT NULL DEFAULT 0, + paid_time INTEGER, + payment_method TEXT NOT NULL DEFAULT 'bolt11', + options TEXT, + request_lookup_id_kind TEXT +); + +INSERT INTO melt_quote_temp (id, unit, amount, request, fee_reserve, expiry, state, payment_preimage, request_lookup_id, created_time, paid_time, payment_method, options, request_lookup_id_kind) +SELECT id, unit, amount, request, fee_reserve, expiry, state, payment_preimage, request_lookup_id, created_time, paid_time, payment_method, options, request_lookup_id_kind +FROM melt_quote; + +DROP TABLE melt_quote; +ALTER TABLE melt_quote_temp RENAME TO melt_quote; + +-- Recreate indexes for melt_quote +CREATE INDEX IF NOT EXISTS melt_quote_state_index ON melt_quote(state); +CREATE UNIQUE INDEX IF NOT EXISTS unique_request_lookup_id_melt ON melt_quote(request_lookup_id); +CREATE INDEX IF NOT EXISTS idx_melt_quote_request_lookup_id_and_kind ON melt_quote(request_lookup_id, request_lookup_id_kind); diff --git a/crates/cdk-sql-common/src/mint/mod.rs b/crates/cdk-sql-common/src/mint/mod.rs index 0d9593fff..aa28df260 100644 --- a/crates/cdk-sql-common/src/mint/mod.rs +++ b/crates/cdk-sql-common/src/mint/mod.rs @@ -739,24 +739,6 @@ VALUES (:quote_id, :amount, :timestamp); async fn add_melt_quote(&mut self, quote: mint::MeltQuote) -> Result<(), Self::Err> { // First try to find and replace any expired UNPAID quotes with the same request_lookup_id - let current_time = unix_time(); - let row_affected = query( - r#" - DELETE FROM melt_quote - WHERE request_lookup_id = :request_lookup_id - AND state = :state - AND expiry < :current_time - "#, - )? - .bind("request_lookup_id", quote.request_lookup_id.to_string()) - .bind("state", MeltQuoteState::Unpaid.to_string()) - .bind("current_time", current_time as i64) - .execute(&self.inner) - .await?; - - if row_affected > 0 { - tracing::info!("Received new melt quote for existing invoice with expired quote."); - } // Now insert the new quote query( @@ -783,14 +765,20 @@ VALUES (:quote_id, :amount, :timestamp); .bind("state", quote.state.to_string()) .bind("expiry", quote.expiry as i64) .bind("payment_preimage", quote.payment_preimage) - .bind("request_lookup_id", quote.request_lookup_id.to_string()) + .bind( + "request_lookup_id", + quote.request_lookup_id.as_ref().map(|id| id.to_string()), + ) .bind("created_time", quote.created_time as i64) .bind("paid_time", quote.paid_time.map(|t| t as i64)) .bind( "options", quote.options.map(|o| serde_json::to_string(&o).ok()), ) - .bind("request_lookup_id_kind", quote.request_lookup_id.kind()) + .bind( + "request_lookup_id_kind", + quote.request_lookup_id.map(|id| id.kind()), + ) .bind("payment_method", quote.payment_method.to_string()) .execute(&self.inner) .await?; @@ -1713,19 +1701,24 @@ fn sql_row_to_melt_quote(row: Vec) -> Result { let unit = column_as_string!(unit); let request = column_as_string!(request); - let mut request_lookup_id_kind = column_as_string!(request_lookup_id_kind); + let request_lookup_id_kind = column_as_nullable_string!(request_lookup_id_kind); - let request_lookup_id = column_as_nullable_string!(&request_lookup_id).unwrap_or_else(|| { + let request_lookup_id = column_as_nullable_string!(&request_lookup_id).or_else(|| { Bolt11Invoice::from_str(&request) + .ok() .map(|invoice| invoice.payment_hash().to_string()) - .unwrap_or_else(|_| { - request_lookup_id_kind = "custom".to_string(); - request.clone() - }) }); - let request_lookup_id = PaymentIdentifier::new(&request_lookup_id_kind, &request_lookup_id) - .map_err(|_| ConversionError::MissingParameter("Payment id".to_string()))?; + let request_lookup_id = if let (Some(id_kind), Some(request_lookup_id)) = + (request_lookup_id_kind, request_lookup_id) + { + Some( + PaymentIdentifier::new(&id_kind, &request_lookup_id) + .map_err(|_| ConversionError::MissingParameter("Payment id".to_string()))?, + ) + } else { + None + }; let request = match serde_json::from_str(&request) { Ok(req) => req, diff --git a/crates/cdk/src/mint/melt.rs b/crates/cdk/src/mint/melt.rs index 972d06915..c6c504219 100644 --- a/crates/cdk/src/mint/melt.rs +++ b/crates/cdk/src/mint/melt.rs @@ -9,7 +9,7 @@ use cdk_common::nut00::ProofsMethods; use cdk_common::nut05::MeltMethodOptions; use cdk_common::payment::{ Bolt11OutgoingPaymentOptions, Bolt12OutgoingPaymentOptions, OutgoingPaymentOptions, - PaymentQuoteOptions, + PaymentIdentifier, }; use cdk_common::{MeltOptions, MeltQuoteBolt12Request}; use lightning::offers::offer::Offer; @@ -202,7 +202,7 @@ impl Mint { ); tracing::debug!( - "New {} melt quote {} for {} {} with request id {}", + "New {} melt quote {} for {} {} with request id {:?}", quote.payment_method, quote.id, amount_quote_unit, @@ -269,7 +269,6 @@ impl Mint { max_fee_amount: None, timeout_secs: None, melt_options: *options, - invoice: None, }; let payment_quote = ln @@ -288,13 +287,8 @@ impl Mint { Error::UnsupportedUnit })?; - let invoice = payment_quote.options.and_then(|options| match options { - PaymentQuoteOptions::Bolt12 { invoice } => invoice, - }); - let payment_request = MeltPaymentRequest::Bolt12 { offer: Box::new(offer), - invoice, }; let quote = MeltQuote::new( @@ -309,7 +303,7 @@ impl Mint { ); tracing::debug!( - "New {} melt quote {} for {} {} with request id {}", + "New {} melt quote {} for {} {} with request id {:?}", quote.payment_method, quote.id, amount, @@ -382,7 +376,7 @@ impl Mint { .ok_or(Error::InvoiceAmountUndefined)? .amount_msat(), }, - MeltPaymentRequest::Bolt12 { offer, invoice: _ } => match offer.amount() { + MeltPaymentRequest::Bolt12 { offer } => match offer.amount() { Some(amount) => { let (amount, currency) = match amount { lightning::offers::offer::Amount::Bitcoin { amount_msats } => { @@ -529,18 +523,15 @@ impl Mint { use std::sync::Arc; async fn check_payment_state( ln: Arc + Send + Sync>, - melt_quote: &MeltQuote, + lookup_id: &PaymentIdentifier, ) -> anyhow::Result { - match ln - .check_outgoing_payment(&melt_quote.request_lookup_id) - .await - { + match ln.check_outgoing_payment(lookup_id).await { Ok(response) => Ok(response), Err(check_err) => { // If we cannot check the status of the payment we keep the proofs stuck as pending. tracing::error!( "Could not check the status of payment for {},. Proofs stuck as pending", - melt_quote.id + lookup_id ); tracing::error!("Checking payment error: {}", check_err); bail!("Could not check payment status") @@ -616,12 +607,13 @@ impl Mint { || pay.status == MeltQuoteState::Failed => { tracing::warn!("Got {} status when paying melt quote {} for {} {}. Checking with backend...", pay.status, quote.id, quote.amount, quote.unit); - let check_response = - if let Ok(ok) = check_payment_state(Arc::clone(ln), "e).await { - ok - } else { - return Err(Error::Internal); - }; + let check_response = if let Ok(ok) = + check_payment_state(Arc::clone(ln), &pay.payment_lookup_id).await + { + ok + } else { + return Err(Error::Internal); + }; if check_response.status == MeltQuoteState::Paid { tracing::warn!("Pay invoice returned {} but check returned {}. Proofs stuck as pending", pay.status.to_string(), check_response.status.to_string()); @@ -644,8 +636,16 @@ impl Mint { tracing::error!("Error returned attempting to pay: {} {}", quote.id, err); + let lookup_id = quote.request_lookup_id.as_ref().ok_or_else(|| { + tracing::error!( + "No payment id could not lookup payment for {} after error.", + quote.id + ); + Error::Internal + })?; + let check_response = - if let Ok(ok) = check_payment_state(Arc::clone(ln), "e).await { + if let Ok(ok) = check_payment_state(Arc::clone(ln), lookup_id).await { ok } else { proof_writer.commit(); @@ -690,21 +690,18 @@ impl Mint { let payment_lookup_id = pre.payment_lookup_id; let mut tx = self.localstore.begin_transaction().await?; - if payment_lookup_id != quote.request_lookup_id { + if Some(payment_lookup_id.clone()).as_ref() != quote.request_lookup_id.as_ref() { tracing::info!( - "Payment lookup id changed post payment from {} to {}", - quote.request_lookup_id, + "Payment lookup id changed post payment from {:?} to {}", + "e.request_lookup_id, payment_lookup_id ); let mut melt_quote = quote; - melt_quote.request_lookup_id = payment_lookup_id; + melt_quote.request_lookup_id = Some(payment_lookup_id.clone()); if let Err(err) = tx - .update_melt_quote_request_lookup_id( - &melt_quote.id, - &melt_quote.request_lookup_id, - ) + .update_melt_quote_request_lookup_id(&melt_quote.id, &payment_lookup_id) .await { tracing::warn!("Could not update payment lookup id: {}", err); diff --git a/crates/cdk/src/mint/start_up_check.rs b/crates/cdk/src/mint/start_up_check.rs index e7284fc1e..ed23318f5 100644 --- a/crates/cdk/src/mint/start_up_check.rs +++ b/crates/cdk/src/mint/start_up_check.rs @@ -40,39 +40,39 @@ impl Mint { } }; - let pay_invoice_response = ln_backend - .check_outgoing_payment(&pending_quote.request_lookup_id) - .await?; + if let Some(lookup_id) = pending_quote.request_lookup_id { + let pay_invoice_response = ln_backend.check_outgoing_payment(&lookup_id).await?; - tracing::warn!( - "There is no stored melt request for pending melt quote: {}", - pending_quote.id - ); + tracing::warn!( + "There is no stored melt request for pending melt quote: {}", + pending_quote.id + ); - let melt_quote_state = match pay_invoice_response.status { - MeltQuoteState::Unpaid => MeltQuoteState::Unpaid, - MeltQuoteState::Paid => MeltQuoteState::Paid, - MeltQuoteState::Pending => MeltQuoteState::Pending, - MeltQuoteState::Failed => MeltQuoteState::Unpaid, - MeltQuoteState::Unknown => MeltQuoteState::Unpaid, - }; + let melt_quote_state = match pay_invoice_response.status { + MeltQuoteState::Unpaid => MeltQuoteState::Unpaid, + MeltQuoteState::Paid => MeltQuoteState::Paid, + MeltQuoteState::Pending => MeltQuoteState::Pending, + MeltQuoteState::Failed => MeltQuoteState::Unpaid, + MeltQuoteState::Unknown => MeltQuoteState::Unpaid, + }; - if let Err(err) = tx - .update_melt_quote_state( - &pending_quote.id, - melt_quote_state, - pay_invoice_response.payment_proof, - ) - .await - { - tracing::error!( - "Could not update quote {} to state {}, current state {}, {}", - pending_quote.id, - melt_quote_state, - pending_quote.state, - err - ); - }; + if let Err(err) = tx + .update_melt_quote_state( + &pending_quote.id, + melt_quote_state, + pay_invoice_response.payment_proof, + ) + .await + { + tracing::error!( + "Could not update quote {} to state {}, current state {}, {}", + pending_quote.id, + melt_quote_state, + pending_quote.state, + err + ); + }; + } } tx.commit().await?; From 818367a8fa4d08124d3ef53ee4e355c66af6decf Mon Sep 17 00:00:00 2001 From: asmo Date: Wed, 20 Aug 2025 18:29:44 +0200 Subject: [PATCH 093/321] fix: reduce mmap_size to 5 MiB (#980) --- crates/cdk-sqlite/src/common.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/cdk-sqlite/src/common.rs b/crates/cdk-sqlite/src/common.rs index e42d0b791..d00bfaf6c 100644 --- a/crates/cdk-sqlite/src/common.rs +++ b/crates/cdk-sqlite/src/common.rs @@ -62,7 +62,7 @@ impl DatabasePool for SqliteConnectionManager { pragma journal_mode = WAL; pragma synchronous = normal; pragma temp_store = memory; - pragma mmap_size = 30000000000; + pragma mmap_size = 5242880; pragma cache = shared; "#, )?; From aa624d3afd739a82aa31dfde2632480934004fc2 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Wed, 20 Aug 2025 18:01:46 +0100 Subject: [PATCH 094/321] fix: lnbits payment check and units (#981) * fix: lnbits payment check and units --------- Co-authored-by: asmo --- crates/cdk-lnbits/Cargo.toml | 1 + crates/cdk-lnbits/src/lib.rs | 37 +++++++++++++++++++++----------- crates/cdk/src/mint/issue/mod.rs | 18 ++++++++++++++-- crates/cdk/src/mint/ln.rs | 12 +++++++++-- crates/cdk/src/mint/mod.rs | 20 ++++++++++++++--- 5 files changed, 68 insertions(+), 20 deletions(-) diff --git a/crates/cdk-lnbits/Cargo.toml b/crates/cdk-lnbits/Cargo.toml index bbb0e7863..e99303cb1 100644 --- a/crates/cdk-lnbits/Cargo.toml +++ b/crates/cdk-lnbits/Cargo.toml @@ -23,3 +23,4 @@ tracing.workspace = true thiserror.workspace = true lnbits-rs = "0.6.0" serde_json.workspace = true +rustls.workspace = true diff --git a/crates/cdk-lnbits/src/lib.rs b/crates/cdk-lnbits/src/lib.rs index f71b49776..6c346ce10 100644 --- a/crates/cdk-lnbits/src/lib.rs +++ b/crates/cdk-lnbits/src/lib.rs @@ -72,6 +72,9 @@ impl LNbits { /// Subscribe to lnbits ws pub async fn subscribe_ws(&self) -> Result<(), Error> { + if rustls::crypto::CryptoProvider::get_default().is_none() { + let _ = rustls::crypto::ring::default_provider().install_default(); + } self.lnbits_api .subscribe_to_websocket() .await @@ -134,7 +137,7 @@ impl MintPayment for LNbits { let response = WaitPaymentResponse { payment_identifier: PaymentIdentifier::PaymentHash(hash), payment_amount: Amount::from(payment.details.amount as u64), - unit: CurrencyUnit::Sat, + unit: CurrencyUnit::Msat, payment_id: msg.clone() }; Some((response, (api, cancel_token, is_active))) @@ -247,9 +250,9 @@ impl MintPayment for LNbits { })?; let status = if invoice_info.paid { - MeltQuoteState::Unpaid - } else { MeltQuoteState::Paid + } else { + MeltQuoteState::Unpaid }; let total_spent = Amount::from( @@ -271,7 +274,7 @@ impl MintPayment for LNbits { payment_proof: Some(invoice_info.details.payment_hash), status, total_spent, - unit: CurrencyUnit::Sat, + unit: CurrencyUnit::Msat, }) } OutgoingPaymentOptions::Bolt12(_) => { @@ -352,12 +355,21 @@ impl MintPayment for LNbits { Self::Err::Anyhow(anyhow!("Could not check invoice status")) })?; - Ok(vec![WaitPaymentResponse { - payment_identifier: payment_identifier.clone(), - payment_amount: Amount::from(payment.details.amount as u64), - unit: CurrencyUnit::Sat, - payment_id: payment.details.payment_hash, - }]) + let amount = payment.details.amount; + + if amount == i64::MIN { + return Err(Error::AmountOverflow.into()); + } + + match payment.paid { + true => Ok(vec![WaitPaymentResponse { + payment_identifier: payment_identifier.clone(), + payment_amount: Amount::from(amount.unsigned_abs()), + unit: CurrencyUnit::Msat, + payment_id: payment.details.payment_hash, + }]), + false => Ok(vec![]), + } } async fn check_outgoing_payment( @@ -379,10 +391,9 @@ impl MintPayment for LNbits { payment_proof: payment.preimage, status: lnbits_to_melt_status(&payment.details.status, payment.details.pending), total_spent: Amount::from( - payment.details.amount.unsigned_abs() - + payment.details.fee.unsigned_abs() / MSAT_IN_SAT, + payment.details.amount.unsigned_abs() + payment.details.fee.unsigned_abs(), ), - unit: self.settings.unit.clone(), + unit: CurrencyUnit::Msat, }; Ok(pay_response) diff --git a/crates/cdk/src/mint/issue/mod.rs b/crates/cdk/src/mint/issue/mod.rs index df65ca8cd..47aa43dcb 100644 --- a/crates/cdk/src/mint/issue/mod.rs +++ b/crates/cdk/src/mint/issue/mod.rs @@ -1,3 +1,4 @@ +use cdk_common::amount::to_unit; use cdk_common::mint::MintQuote; use cdk_common::payment::{ Bolt11IncomingPaymentOptions, Bolt11Settings, Bolt12IncomingPaymentOptions, @@ -410,8 +411,9 @@ impl Mint { wait_payment_response: WaitPaymentResponse, ) -> Result<(), Error> { tracing::debug!( - "Received payment notification of {} for mint quote {} with payment id {}", + "Received payment notification of {} {} for mint quote {} with payment id {}", wait_payment_response.payment_amount, + wait_payment_response.unit, mint_quote.id, wait_payment_response.payment_id.to_string() ); @@ -426,9 +428,21 @@ impl Mint { { tracing::info!("Received payment notification for already seen payment."); } else { + let payment_amount_quote_unit = to_unit( + wait_payment_response.payment_amount, + &wait_payment_response.unit, + &mint_quote.unit, + )?; + + tracing::debug!( + "Payment received amount in quote unit {} {}", + mint_quote.unit, + payment_amount_quote_unit + ); + tx.increment_mint_quote_amount_paid( &mint_quote.id, - wait_payment_response.payment_amount, + payment_amount_quote_unit, wait_payment_response.payment_id, ) .await?; diff --git a/crates/cdk/src/mint/ln.rs b/crates/cdk/src/mint/ln.rs index 901ed1a54..607b5298f 100644 --- a/crates/cdk/src/mint/ln.rs +++ b/crates/cdk/src/mint/ln.rs @@ -46,8 +46,16 @@ impl Mint { let mut tx = self.localstore.begin_transaction().await?; for payment in ln_status { - if !quote.payment_ids().contains(&&payment.payment_id) { - tracing::debug!("Found payment for quote {} when checking.", quote.id); + if !quote.payment_ids().contains(&&payment.payment_id) + && payment.payment_amount > Amount::ZERO + { + tracing::debug!( + "Found payment of {} {} for quote {} when checking.", + payment.payment_amount, + payment.unit, + quote.id + ); + let amount_paid = to_unit(payment.payment_amount, &payment.unit, "e.unit)?; quote.increment_amount_paid(amount_paid)?; diff --git a/crates/cdk/src/mint/mod.rs b/crates/cdk/src/mint/mod.rs index 8ebc94298..30130be4d 100644 --- a/crates/cdk/src/mint/mod.rs +++ b/crates/cdk/src/mint/mod.rs @@ -5,6 +5,7 @@ use std::sync::Arc; use std::time::Duration; use arc_swap::ArcSwap; +use cdk_common::amount::to_unit; use cdk_common::common::{PaymentProcessorKey, QuoteTTL}; #[cfg(feature = "auth")] use cdk_common::database::MintAuthDatabase; @@ -543,10 +544,11 @@ impl Mint { pubsub_manager: &Arc, ) -> Result<(), Error> { tracing::debug!( - "Received payment notification of {} for mint quote {} with payment id {}", + "Received payment notification of {} {} for mint quote {} with payment id {}", wait_payment_response.payment_amount, + wait_payment_response.unit, mint_quote.id, - wait_payment_response.payment_id + wait_payment_response.payment_id.to_string() ); let quote_state = mint_quote.state(); @@ -559,9 +561,21 @@ impl Mint { { tracing::info!("Received payment notification for already issued quote."); } else { + let payment_amount_quote_unit = to_unit( + wait_payment_response.payment_amount, + &wait_payment_response.unit, + &mint_quote.unit, + )?; + + tracing::debug!( + "Payment received amount in quote unit {} {}", + mint_quote.unit, + payment_amount_quote_unit + ); + tx.increment_mint_quote_amount_paid( &mint_quote.id, - wait_payment_response.payment_amount, + payment_amount_quote_unit, wait_payment_response.payment_id, ) .await?; From a4aaef705ed1f0cda1f2fe970b4600d203ffd29b Mon Sep 17 00:00:00 2001 From: gudnuf <108303703+gudnuf@users.noreply.github.com> Date: Thu, 21 Aug 2025 01:55:32 -0700 Subject: [PATCH 095/321] fix: pass auth cfg through mintd to axum (#986) --- crates/cdk-mintd/Cargo.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/cdk-mintd/Cargo.toml b/crates/cdk-mintd/Cargo.toml index ed844cbf9..d9fb63f4a 100644 --- a/crates/cdk-mintd/Cargo.toml +++ b/crates/cdk-mintd/Cargo.toml @@ -23,7 +23,7 @@ sqlcipher = ["cdk-sqlite/sqlcipher"] # MSRV is not committed to with swagger enabled swagger = ["cdk-axum/swagger", "dep:utoipa", "dep:utoipa-swagger-ui"] redis = ["cdk-axum/redis"] -auth = ["cdk/auth", "cdk-sqlite/auth"] +auth = ["cdk/auth", "cdk-sqlite/auth", "cdk-axum/auth"] [dependencies] anyhow.workspace = true From b6f7a75fba3a0ed151644b3664b06ab83697c141 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Thu, 21 Aug 2025 16:13:06 +0100 Subject: [PATCH 096/321] feat: cln as msats (#982) * feat: cln as msats * fix(logging): correct bolt12 payment amount units and reduce log noise - Fix CLN bolt12 payment logging to display msats instead of sats - Add tower_http filter to reduce integration test log verbosity - Use correct payment amount variable in mint quote pubsub notifications --- crates/cdk-cln/src/lib.rs | 11 +++++------ crates/cdk-integration-tests/src/cli.rs | 3 ++- crates/cdk/src/mint/mod.rs | 2 +- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/crates/cdk-cln/src/lib.rs b/crates/cdk-cln/src/lib.rs index 616d79fca..1605bb57e 100644 --- a/crates/cdk-cln/src/lib.rs +++ b/crates/cdk-cln/src/lib.rs @@ -193,7 +193,6 @@ impl MintPayment for Cln { continue; } }; - let amount_sats = amount_msats.msat() / 1000; let payment_hash = Hash::from_bytes_ref(payment_hash.as_ref()); @@ -211,8 +210,8 @@ impl MintPayment for Cln { { Ok(Some(invoice)) => { if let Some(local_offer_id) = invoice.local_offer_id { - tracing::info!("CLN: Received bolt12 payment of {} sats for offer {}", - amount_sats, local_offer_id); + tracing::info!("CLN: Received bolt12 payment of {} msats for offer {}", + amount_msats.msat(), local_offer_id); PaymentIdentifier::OfferId(local_offer_id.to_string()) } else { tracing::warn!("CLN: BOLT12 invoice has no local_offer_id, skipping"); @@ -239,11 +238,11 @@ impl MintPayment for Cln { let response = WaitPaymentResponse { payment_identifier: request_lookup_id, - payment_amount: amount_sats.into(), - unit: CurrencyUnit::Sat, + payment_amount: amount_msats.msat().into(), + unit: CurrencyUnit::Msat, payment_id: payment_hash.to_string() }; - tracing::info!("CLN: Created WaitPaymentResponse with amount {} sats", amount_sats); + tracing::info!("CLN: Created WaitPaymentResponse with amount {} msats", amount_msats.msat()); break Some((response, (cln_client, last_pay_idx, cancel_token, is_active))); } diff --git a/crates/cdk-integration-tests/src/cli.rs b/crates/cdk-integration-tests/src/cli.rs index f803da757..22c5fdcd7 100644 --- a/crates/cdk-integration-tests/src/cli.rs +++ b/crates/cdk-integration-tests/src/cli.rs @@ -29,9 +29,10 @@ pub fn init_logging(enable_logging: bool, log_level: tracing::Level) { let h2_filter = "h2=warn"; let rustls_filter = "rustls=warn"; let reqwest_filter = "reqwest=warn"; + let tower_filter = "tower_http=warn"; let env_filter = EnvFilter::new(format!( - "{default_filter},{sqlx_filter},{hyper_filter},{h2_filter},{rustls_filter},{reqwest_filter}" + "{default_filter},{sqlx_filter},{hyper_filter},{h2_filter},{rustls_filter},{reqwest_filter},{tower_filter}" )); // Ok if successful, Err if already initialized diff --git a/crates/cdk/src/mint/mod.rs b/crates/cdk/src/mint/mod.rs index 30130be4d..db9733f3c 100644 --- a/crates/cdk/src/mint/mod.rs +++ b/crates/cdk/src/mint/mod.rs @@ -588,7 +588,7 @@ impl Mint { PaymentMethod::Bolt12 => { pubsub_manager.mint_quote_bolt12_status( mint_quote.clone(), - wait_payment_response.payment_amount, + payment_amount_quote_unit, Amount::ZERO, ); } From 9a3d9b7139efaea61e49eeb68e039787e7620128 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Thu, 21 Aug 2025 16:16:48 +0100 Subject: [PATCH 097/321] feat: bip353 (#969) --- crates/cdk-cli/Cargo.toml | 6 +- crates/cdk-cli/src/bip353.rs | 132 ---------- crates/cdk-cli/src/main.rs | 2 - crates/cdk-cli/src/sub_commands/melt.rs | 20 +- crates/cdk-common/src/error.rs | 10 + crates/cdk/Cargo.toml | 7 + crates/cdk/examples/bip353.rs | 143 +++++++++++ crates/cdk/src/bip353.rs | 286 ++++++++++++++++++++++ crates/cdk/src/lib.rs | 3 + crates/cdk/src/wallet/melt/melt_bip353.rs | 94 +++++++ crates/cdk/src/wallet/melt/mod.rs | 2 + 11 files changed, 555 insertions(+), 150 deletions(-) delete mode 100644 crates/cdk-cli/src/bip353.rs create mode 100644 crates/cdk/examples/bip353.rs create mode 100644 crates/cdk/src/bip353.rs create mode 100644 crates/cdk/src/wallet/melt/melt_bip353.rs diff --git a/crates/cdk-cli/Cargo.toml b/crates/cdk-cli/Cargo.toml index e6e83a282..a2c2e2dde 100644 --- a/crates/cdk-cli/Cargo.toml +++ b/crates/cdk-cli/Cargo.toml @@ -11,8 +11,7 @@ rust-version.workspace = true readme = "README.md" [features] -default = ["bip353"] -bip353 = ["dep:trust-dns-resolver"] +default = [] sqlcipher = ["cdk-sqlite/sqlcipher"] # MSRV is not tracked with redb enabled redb = ["dep:cdk-redb"] @@ -21,7 +20,7 @@ redb = ["dep:cdk-redb"] anyhow.workspace = true bip39.workspace = true bitcoin.workspace = true -cdk = { workspace = true, default-features = false, features = ["wallet", "auth"]} +cdk = { workspace = true, default-features = false, features = ["wallet", "auth", "bip353"]} cdk-redb = { workspace = true, features = ["wallet"], optional = true } cdk-sqlite = { workspace = true, features = ["wallet"] } clap.workspace = true @@ -40,4 +39,3 @@ reqwest.workspace = true url.workspace = true serde_with.workspace = true lightning.workspace = true -trust-dns-resolver = { version = "0.23.2", optional = true } diff --git a/crates/cdk-cli/src/bip353.rs b/crates/cdk-cli/src/bip353.rs deleted file mode 100644 index 1d424be44..000000000 --- a/crates/cdk-cli/src/bip353.rs +++ /dev/null @@ -1,132 +0,0 @@ -use std::collections::HashMap; -use std::str::FromStr; - -use anyhow::{bail, Result}; -use trust_dns_resolver::config::{ResolverConfig, ResolverOpts}; -use trust_dns_resolver::TokioAsyncResolver; - -#[derive(Debug, Clone, PartialEq, Eq, Hash)] -pub struct Bip353Address { - pub user: String, - pub domain: String, -} - -impl Bip353Address { - /// Resolve a human-readable Bitcoin address - pub async fn resolve(self) -> Result { - // Construct DNS name - let dns_name = format!("{}.user._bitcoin-payment.{}", self.user, self.domain); - - // Create a new resolver with DNSSEC validation - let mut opts = ResolverOpts::default(); - opts.validate = true; // Enable DNSSEC validation - - let resolver = TokioAsyncResolver::tokio(ResolverConfig::default(), opts); - - // Query TXT records - with opts.validate=true, this will fail if DNSSEC validation fails - let response = resolver.txt_lookup(&dns_name).await?; - - // Extract and concatenate TXT record strings - let mut bitcoin_uris = Vec::new(); - - for txt in response.iter() { - let txt_data: Vec = txt - .txt_data() - .iter() - .map(|bytes| String::from_utf8_lossy(bytes).into_owned()) - .collect(); - - let concatenated = txt_data.join(""); - - if concatenated.to_lowercase().starts_with("bitcoin:") { - bitcoin_uris.push(concatenated); - } - } - - // BIP-353 requires exactly one Bitcoin URI - match bitcoin_uris.len() { - 0 => bail!("No Bitcoin URI found"), - 1 => PaymentInstruction::from_uri(&bitcoin_uris[0]), - _ => bail!("Multiple Bitcoin URIs found"), - } - } -} - -impl FromStr for Bip353Address { - type Err = anyhow::Error; - - /// Parse a human-readable Bitcoin address - fn from_str(address: &str) -> Result { - let addr = address.trim(); - - // Remove Bitcoin prefix if present - let addr = addr.strip_prefix("₿").unwrap_or(addr); - - // Split by @ - let parts: Vec<&str> = addr.split('@').collect(); - if parts.len() != 2 { - bail!("Address is not formatted correctly") - } - - let user = parts[0].trim(); - let domain = parts[1].trim(); - - if user.is_empty() || domain.is_empty() { - bail!("User name and domain must not be empty") - } - - Ok(Self { - user: user.to_string(), - domain: domain.to_string(), - }) - } -} - -/// Payment instruction type -#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] -pub enum PaymentType { - OnChain, - LightningOffer, -} - -/// BIP-353 payment instruction -#[derive(Debug, Clone)] -pub struct PaymentInstruction { - pub parameters: HashMap, -} - -impl PaymentInstruction { - /// Parse a payment instruction from a Bitcoin URI - pub fn from_uri(uri: &str) -> Result { - if !uri.to_lowercase().starts_with("bitcoin:") { - bail!("URI must start with 'bitcoin:'") - } - - let mut parameters = HashMap::new(); - - // Parse URI parameters - if let Some(query_start) = uri.find('?') { - let query = &uri[query_start + 1..]; - for pair in query.split('&') { - if let Some(eq_pos) = pair.find('=') { - let key = pair[..eq_pos].to_string(); - let value = pair[eq_pos + 1..].to_string(); - let payment_type; - // Determine payment type - if key.contains("lno") { - payment_type = PaymentType::LightningOffer; - } else if !uri[8..].contains('?') && uri.len() > 8 { - // Simple on-chain address - payment_type = PaymentType::OnChain; - } else { - continue; - } - - parameters.insert(payment_type, value); - } - } - } - - Ok(PaymentInstruction { parameters }) - } -} diff --git a/crates/cdk-cli/src/main.rs b/crates/cdk-cli/src/main.rs index 9a601579c..32a1c3ea7 100644 --- a/crates/cdk-cli/src/main.rs +++ b/crates/cdk-cli/src/main.rs @@ -18,8 +18,6 @@ use tracing::Level; use tracing_subscriber::EnvFilter; use url::Url; -#[cfg(feature = "bip353")] -mod bip353; mod nostr_storage; mod sub_commands; mod token_storage; diff --git a/crates/cdk-cli/src/sub_commands/melt.rs b/crates/cdk-cli/src/sub_commands/melt.rs index ea2bd676f..e03e1a11c 100644 --- a/crates/cdk-cli/src/sub_commands/melt.rs +++ b/crates/cdk-cli/src/sub_commands/melt.rs @@ -1,6 +1,6 @@ use std::str::FromStr; -use anyhow::{anyhow, bail, Result}; +use anyhow::{bail, Result}; use cdk::amount::{amount_for_offer, Amount, MSAT_IN_SAT}; use cdk::mint_url::MintUrl; use cdk::nuts::{CurrencyUnit, MeltOptions}; @@ -12,7 +12,6 @@ use clap::{Args, ValueEnum}; use lightning::offers::offer::Offer; use tokio::task::JoinSet; -use crate::bip353::{Bip353Address, PaymentType as Bip353PaymentType}; use crate::sub_commands::balance::mint_balances; use crate::utils::{ get_number_input, get_user_input, get_wallet_by_index, get_wallet_by_mint_url, @@ -184,22 +183,19 @@ pub async fn pay( } PaymentType::Bip353 => { let bip353_addr = get_user_input("Enter Bip353 address.")?; - let bip353_addr = Bip353Address::from_str(&bip353_addr)?; - - let payment_instructions = bip353_addr.resolve().await?; - - let offer = payment_instructions - .parameters - .get(&Bip353PaymentType::LightningOffer) - .ok_or(anyhow!("Offer not defined"))?; let prompt = "Enter the amount you would like to pay in sats for this amountless offer:"; // BIP353 payments are always amountless for now let options = create_melt_options(available_funds, None, prompt)?; - // Get melt quote for BOLT12 - let quote = wallet.melt_bolt12_quote(offer.to_string(), options).await?; + // Get melt quote for BIP353 address (internally resolves and gets BOLT12 quote) + let quote = wallet + .melt_bip353_quote( + &bip353_addr, + options.expect("Amount is required").amount_msat(), + ) + .await?; process_payment(&wallet, quote).await?; } } diff --git a/crates/cdk-common/src/error.rs b/crates/cdk-common/src/error.rs index 5d19ab4ef..b1c7e27e0 100644 --- a/crates/cdk-common/src/error.rs +++ b/crates/cdk-common/src/error.rs @@ -115,6 +115,16 @@ pub enum Error { #[error("Operation timeout")] Timeout, + /// BIP353 address parsing error + #[error("Failed to parse BIP353 address: {0}")] + Bip353Parse(String), + /// BIP353 address resolution error + #[error("Failed to resolve BIP353 address: {0}")] + Bip353Resolve(String), + /// BIP353 no Lightning offer found + #[error("No Lightning offer found in BIP353 payment instructions")] + Bip353NoLightningOffer, + /// Internal Error - Send error #[error("Internal send error: {0}")] SendError(String), diff --git a/crates/cdk/Cargo.toml b/crates/cdk/Cargo.toml index 8bcc70f1d..02c5dbdb4 100644 --- a/crates/cdk/Cargo.toml +++ b/crates/cdk/Cargo.toml @@ -15,6 +15,7 @@ default = ["mint", "wallet", "auth"] wallet = ["dep:futures", "dep:reqwest", "cdk-common/wallet", "dep:rustls"] mint = ["dep:futures", "dep:reqwest", "cdk-common/mint", "cdk-signatory"] auth = ["dep:jsonwebtoken", "cdk-common/auth", "cdk-common/auth"] +bip353 = ["dep:trust-dns-resolver"] # We do not commit to a MSRV with swagger enabled swagger = ["mint", "dep:utoipa", "cdk-common/swagger"] bench = [] @@ -42,6 +43,7 @@ url.workspace = true utoipa = { workspace = true, optional = true } uuid.workspace = true jsonwebtoken = { workspace = true, optional = true } +trust-dns-resolver = { version = "0.23.2", optional = true } # -Z minimal-versions sync_wrapper = "0.1.2" @@ -95,6 +97,10 @@ required-features = ["wallet"] name = "auth_wallet" required-features = ["wallet", "auth"] +[[example]] +name = "bip353" +required-features = ["wallet", "bip353"] + [dev-dependencies] rand.workspace = true cdk-sqlite.workspace = true @@ -102,6 +108,7 @@ bip39.workspace = true tracing-subscriber.workspace = true criterion = "0.6.0" reqwest = { workspace = true } +anyhow.workspace = true [[bench]] diff --git a/crates/cdk/examples/bip353.rs b/crates/cdk/examples/bip353.rs new file mode 100644 index 000000000..b617241d8 --- /dev/null +++ b/crates/cdk/examples/bip353.rs @@ -0,0 +1,143 @@ +//! # BIP-353 CDK Example +//! +//! This example demonstrates how to use BIP-353 (Human Readable Bitcoin Payment Instructions) +//! with the CDK wallet. BIP-353 allows users to share simple email-like addresses such as +//! `user@domain.com` instead of complex Bitcoin addresses or Lightning invoices. +//! +//! ## How it works +//! +//! 1. Parse a human-readable address like `alice@example.com` +//! 2. Query DNS TXT records at `alice.user._bitcoin-payment.example.com` +//! 3. Extract Bitcoin URIs from the TXT records +//! 4. Parse payment instructions (Lightning offers, on-chain addresses) +//! 5. Use CDK wallet to execute payments +//! +//! ## Usage +//! +//! ```bash +//! cargo run --example bip353 --features="wallet bip353" +//! ``` +//! +//! Note: The example uses a placeholder address that will fail DNS resolution. +//! To test with real addresses, you need a domain with proper BIP-353 DNS records. + +use std::sync::Arc; +use std::time::Duration; + +use cdk::amount::SplitTarget; +use cdk::nuts::nut00::ProofsMethods; +use cdk::nuts::{CurrencyUnit, MintQuoteState}; +use cdk::wallet::Wallet; +use cdk::Amount; +use cdk_sqlite::wallet::memory; +use rand::random; +use tokio::time::sleep; + +#[tokio::main] +async fn main() -> anyhow::Result<()> { + println!("BIP-353 CDK Example"); + println!("==================="); + + // Example BIP-353 address - replace with a real one that has BOLT12 offer + // For testing, you might need to set up your own DNS records + let bip353_address = "tsk@thesimplekid.com"; // This is just an example + + println!("Attempting to use BIP-353 address: {}", bip353_address); + + // Generate a random seed for the wallet + let seed = random::<[u8; 64]>(); + + // Mint URL and currency unit + let mint_url = "https://fake.thesimplekid.dev"; + let unit = CurrencyUnit::Sat; + let initial_amount = Amount::from(1000); // Start with 1000 sats + + // Initialize the memory store + let localstore = Arc::new(memory::empty().await?); + + // Create a new wallet + let wallet = Wallet::new(mint_url, unit, localstore, seed, None)?; + + // First, we need to fund the wallet + println!("Requesting mint quote for {} sats...", initial_amount); + let mint_quote = wallet.mint_quote(initial_amount, None).await?; + println!( + "Pay this invoice to fund the wallet: {}", + mint_quote.request + ); + + // In a real application, you would wait for the payment + // For this example, we'll just demonstrate the BIP353 melt process + println!("Waiting for payment... (in real use, pay the above invoice)"); + + // Check quote state (with timeout for demo purposes) + let timeout = Duration::from_secs(30); + let start = std::time::Instant::now(); + + while start.elapsed() < timeout { + let status = wallet.mint_quote_state(&mint_quote.id).await?; + + if status.state == MintQuoteState::Paid { + break; + } + + println!("Quote state: {} (waiting...)", status.state); + sleep(Duration::from_secs(2)).await; + } + + // Mint the tokens + let proofs = wallet + .mint(&mint_quote.id, SplitTarget::default(), None) + .await?; + let received_amount = proofs.total_amount()?; + println!("Successfully minted {} sats", received_amount); + + // Now prepare to pay using the BIP353 address + let payment_amount_sats = 100; // Example: paying 100 sats + + println!( + "Attempting to pay {} sats using BIP-353 address...", + payment_amount_sats + ); + + // Use the new wallet method to resolve BIP353 address and get melt quote + match wallet + .melt_bip353_quote(bip353_address, payment_amount_sats * 1_000) + .await + { + Ok(melt_quote) => { + println!("BIP-353 melt quote received:"); + println!(" Quote ID: {}", melt_quote.id); + println!(" Amount: {} sats", melt_quote.amount); + println!(" Fee Reserve: {} sats", melt_quote.fee_reserve); + println!(" State: {}", melt_quote.state); + + // Execute the payment + match wallet.melt(&melt_quote.id).await { + Ok(melt_result) => { + println!("BIP-353 payment successful!"); + println!(" State: {}", melt_result.state); + println!(" Amount paid: {} sats", melt_result.amount); + println!(" Fee paid: {} sats", melt_result.fee_paid); + + if let Some(preimage) = melt_result.preimage { + println!(" Payment preimage: {}", preimage); + } + } + Err(e) => { + println!("BIP-353 payment failed: {}", e); + } + } + } + Err(e) => { + println!("Failed to get BIP-353 melt quote: {}", e); + println!("This could be because:"); + println!("1. The BIP-353 address format is invalid"); + println!("2. DNS resolution failed (expected for this example)"); + println!("3. No Lightning offer found in the DNS records"); + println!("4. DNSSEC validation failed"); + } + } + + Ok(()) +} diff --git a/crates/cdk/src/bip353.rs b/crates/cdk/src/bip353.rs new file mode 100644 index 000000000..15b2c6c77 --- /dev/null +++ b/crates/cdk/src/bip353.rs @@ -0,0 +1,286 @@ +//! BIP-353: Human Readable Bitcoin Payment Instructions +//! +//! This module provides functionality for resolving human-readable Bitcoin addresses +//! according to BIP-353. It allows users to share simple email-like addresses such as +//! `user@domain.com` instead of complex Bitcoin addresses or Lightning invoices. + +use std::collections::HashMap; +use std::str::FromStr; + +use anyhow::{bail, Result}; +use trust_dns_resolver::config::{ResolverConfig, ResolverOpts}; +use trust_dns_resolver::TokioAsyncResolver; + +/// BIP-353 human-readable Bitcoin address +#[derive(Debug, Clone, PartialEq, Eq, Hash)] +pub struct Bip353Address { + /// The user part of the address (before @) + pub user: String, + /// The domain part of the address (after @) + pub domain: String, +} + +impl Bip353Address { + /// Resolve a human-readable Bitcoin address to payment instructions + /// + /// This method performs the following steps: + /// 1. Constructs the DNS name according to BIP-353 format + /// 2. Queries TXT records with DNSSEC validation + /// 3. Extracts Bitcoin URIs from the records + /// 4. Parses the URIs into payment instructions + /// + /// # Errors + /// + /// This method will return an error if: + /// - DNS resolution fails + /// - DNSSEC validation fails + /// - No Bitcoin URI is found + /// - Multiple Bitcoin URIs are found (BIP-353 requires exactly one) + /// - The URI format is invalid + pub(crate) async fn resolve(self) -> Result { + // Construct DNS name according to BIP-353 + let dns_name = format!("{}.user._bitcoin-payment.{}", self.user, self.domain); + + // Create a new resolver with DNSSEC validation + let mut opts = ResolverOpts::default(); + opts.validate = true; // Enable DNSSEC validation + + let resolver = TokioAsyncResolver::tokio(ResolverConfig::default(), opts); + + // Query TXT records - with opts.validate=true, this will fail if DNSSEC validation fails + let response = resolver.txt_lookup(&dns_name).await?; + + // Extract and concatenate TXT record strings + let mut bitcoin_uris = Vec::new(); + + for txt in response.iter() { + let txt_data: Vec = txt + .txt_data() + .iter() + .map(|bytes| String::from_utf8_lossy(bytes).into_owned()) + .collect(); + + let concatenated = txt_data.join(""); + + if concatenated.to_lowercase().starts_with("bitcoin:") { + bitcoin_uris.push(concatenated); + } + } + + // BIP-353 requires exactly one Bitcoin URI + match bitcoin_uris.len() { + 0 => bail!("No Bitcoin URI found"), + 1 => PaymentInstruction::from_uri(&bitcoin_uris[0]), + _ => bail!("Multiple Bitcoin URIs found"), + } + } +} + +impl FromStr for Bip353Address { + type Err = anyhow::Error; + + /// Parse a human-readable Bitcoin address from string format + /// + /// Accepts formats: + /// - `user@domain.com` + /// - `₿user@domain.com` (with Bitcoin symbol prefix) + /// + /// # Errors + /// + /// Returns an error if: + /// - The format is not `user@domain` + /// - User or domain parts are empty + fn from_str(address: &str) -> Result { + let addr = address.trim(); + + // Remove Bitcoin prefix if present + let addr = addr.strip_prefix("₿").unwrap_or(addr); + + // Split by @ + let parts: Vec<&str> = addr.split('@').collect(); + if parts.len() != 2 { + bail!("Address is not formatted correctly") + } + + let user = parts[0].trim(); + let domain = parts[1].trim(); + + if user.is_empty() || domain.is_empty() { + bail!("User name and domain must not be empty") + } + + Ok(Self { + user: user.to_string(), + domain: domain.to_string(), + }) + } +} + +impl std::fmt::Display for Bip353Address { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + write!(f, "{}@{}", self.user, self.domain) + } +} + +/// Payment instruction type +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +pub enum PaymentType { + /// On-chain Bitcoin address + OnChain, + /// Lightning Offer (BOLT12) + LightningOffer, +} + +/// BIP-353 payment instruction containing parsed payment methods +#[derive(Debug, Clone)] +pub struct PaymentInstruction { + /// Map of payment types to their corresponding values + pub parameters: HashMap, +} + +impl PaymentInstruction { + /// Create a new empty payment instruction + pub fn new() -> Self { + Self { + parameters: HashMap::new(), + } + } + + /// Parse a payment instruction from a Bitcoin URI + /// + /// Extracts various payment methods from the URI: + /// - Lightning offers (parameters containing "lno") + /// - On-chain addresses (address part of the URI) + /// + /// # Errors + /// + /// Returns an error if the URI doesn't start with "bitcoin:" + pub fn from_uri(uri: &str) -> Result { + if !uri.to_lowercase().starts_with("bitcoin:") { + bail!("URI must start with 'bitcoin:'") + } + + let mut parameters = HashMap::new(); + + // Parse URI parameters + if let Some(query_start) = uri.find('?') { + let query = &uri[query_start + 1..]; + for pair in query.split('&') { + if let Some(eq_pos) = pair.find('=') { + let key = pair[..eq_pos].to_string(); + let value = pair[eq_pos + 1..].to_string(); + + // Determine payment type based on parameter key + if key.contains("lno") { + parameters.insert(PaymentType::LightningOffer, value); + } + // Could add more payment types here as needed + } + } + } + + // Check if we have an on-chain address (address part after bitcoin:) + if let Some(query_start) = uri.find('?') { + let addr_part = &uri[8..query_start]; // Skip "bitcoin:" + if !addr_part.is_empty() { + parameters.insert(PaymentType::OnChain, addr_part.to_string()); + } + } else { + // No query parameters, check if there's just an address + let addr_part = &uri[8..]; // Skip "bitcoin:" + if !addr_part.is_empty() { + parameters.insert(PaymentType::OnChain, addr_part.to_string()); + } + } + + Ok(PaymentInstruction { parameters }) + } + + /// Get a payment method by type + pub fn get(&self, payment_type: &PaymentType) -> Option<&String> { + self.parameters.get(payment_type) + } +} + +impl Default for PaymentInstruction { + fn default() -> Self { + Self::new() + } +} + +#[cfg(test)] +mod tests { + use super::*; + + impl PaymentInstruction { + /// Check if a payment type is available + pub fn has_payment_type(&self, payment_type: &PaymentType) -> bool { + self.parameters.contains_key(payment_type) + } + } + + #[test] + fn test_bip353_address_parsing() { + // Test basic parsing + let addr = Bip353Address::from_str("alice@example.com").unwrap(); + assert_eq!(addr.user, "alice"); + assert_eq!(addr.domain, "example.com"); + + // Test with Bitcoin symbol + let addr = Bip353Address::from_str("₿bob@bitcoin.org").unwrap(); + assert_eq!(addr.user, "bob"); + assert_eq!(addr.domain, "bitcoin.org"); + + // Test with whitespace + let addr = Bip353Address::from_str(" charlie@test.net ").unwrap(); + assert_eq!(addr.user, "charlie"); + assert_eq!(addr.domain, "test.net"); + + // Test display + let addr = Bip353Address { + user: "test".to_string(), + domain: "example.com".to_string(), + }; + assert_eq!(addr.to_string(), "test@example.com"); + } + + #[test] + fn test_bip353_address_parsing_errors() { + // Test invalid formats + assert!(Bip353Address::from_str("invalid").is_err()); + assert!(Bip353Address::from_str("@example.com").is_err()); + assert!(Bip353Address::from_str("user@").is_err()); + assert!(Bip353Address::from_str("user@domain@extra").is_err()); + assert!(Bip353Address::from_str("").is_err()); + } + + #[test] + fn test_payment_instruction_parsing() { + // Test Lightning offer URI + let uri = "bitcoin:?lno=lno1qcp4256ypqpq86q2pucnq42ngssx2an9wfujqerp0y2pxqrjszs5v2a5m5xwc4mxv6rdjdcn2d3kxccnjdgecf7fz3rf5g4t7gdxhkzm8mpsq5q"; + let instruction = PaymentInstruction::from_uri(uri).unwrap(); + assert!(instruction.has_payment_type(&PaymentType::LightningOffer)); + + // Test on-chain address URI + let uri = "bitcoin:bc1qexampleaddress"; + let instruction = PaymentInstruction::from_uri(uri).unwrap(); + assert!(instruction.has_payment_type(&PaymentType::OnChain)); + assert_eq!( + instruction.get(&PaymentType::OnChain).unwrap(), + "bc1qexampleaddress" + ); + + // Test combined URI + let uri = "bitcoin:bc1qexampleaddress?lno=lno1qcp4256ypqpq86q2pucnq42ngssx2an9wfujqerp0y2pxqrjszs5v2a5m5xwc4mxv6rdjdcn2d3kxccnjdgecf7fz3rf5g4t7gdxhkzm8mpsq5q"; + let instruction = PaymentInstruction::from_uri(uri).unwrap(); + assert!(instruction.has_payment_type(&PaymentType::OnChain)); + assert!(instruction.has_payment_type(&PaymentType::LightningOffer)); + } + + #[test] + fn test_payment_instruction_errors() { + // Test invalid URI + assert!(PaymentInstruction::from_uri("invalid:uri").is_err()); + assert!(PaymentInstruction::from_uri("").is_err()); + } +} diff --git a/crates/cdk/src/lib.rs b/crates/cdk/src/lib.rs index 4cc809a7f..aea22fccb 100644 --- a/crates/cdk/src/lib.rs +++ b/crates/cdk/src/lib.rs @@ -22,6 +22,9 @@ pub mod mint; #[cfg(feature = "wallet")] pub mod wallet; +#[cfg(feature = "bip353")] +mod bip353; + #[cfg(all(any(feature = "wallet", feature = "mint"), feature = "auth"))] mod oidc_client; diff --git a/crates/cdk/src/wallet/melt/melt_bip353.rs b/crates/cdk/src/wallet/melt/melt_bip353.rs new file mode 100644 index 000000000..b1b5c401b --- /dev/null +++ b/crates/cdk/src/wallet/melt/melt_bip353.rs @@ -0,0 +1,94 @@ +//! Melt BIP353 +//! +//! Implementation of melt functionality for BIP353 human-readable addresses + +use std::str::FromStr; + +use cdk_common::wallet::MeltQuote; +use tracing::instrument; + +#[cfg(feature = "bip353")] +use crate::bip353::{Bip353Address, PaymentType}; +use crate::nuts::MeltOptions; +use crate::{Amount, Error, Wallet}; + +impl Wallet { + /// Melt Quote for BIP353 human-readable address + /// + /// This method resolves a BIP353 address (e.g., "alice@example.com") to a Lightning offer + /// and then creates a melt quote for that offer. + /// + /// # Arguments + /// + /// * `bip353_address` - Human-readable address in the format "user@domain.com" + /// * `amount_msat` - Amount to pay in millisatoshis + /// + /// # Returns + /// + /// A `MeltQuote` that can be used to execute the payment + /// + /// # Errors + /// + /// This method will return an error if: + /// - The BIP353 address format is invalid + /// - DNS resolution fails or DNSSEC validation fails + /// - No Lightning offer is found in the payment instructions + /// - The mint fails to provide a quote for the offer + /// + /// # Example + /// + /// ```rust,no_run + /// use cdk::Amount; + /// # use cdk::Wallet; + /// # async fn example(wallet: Wallet) -> Result<(), cdk::Error> { + /// let quote = wallet + /// .melt_bip353_quote("alice@example.com", Amount::from(100_000)) // 100 sats in msat + /// .await?; + /// # Ok(()) + /// # } + /// ``` + #[cfg(feature = "bip353")] + #[instrument(skip(self, amount_msat), fields(address = %bip353_address))] + pub async fn melt_bip353_quote( + &self, + bip353_address: &str, + amount_msat: impl Into, + ) -> Result { + // Parse the BIP353 address + let address = Bip353Address::from_str(bip353_address).map_err(|e| { + tracing::error!("Failed to parse BIP353 address '{}': {}", bip353_address, e); + Error::Bip353Parse(e.to_string()) + })?; + + tracing::debug!("Resolving BIP353 address: {}", address); + + // Keep a copy for error reporting + let address_string = address.to_string(); + + // Resolve the address to get payment instructions + let payment_instructions = address.resolve().await.map_err(|e| { + tracing::error!( + "Failed to resolve BIP353 address '{}': {}", + address_string, + e + ); + Error::Bip353Resolve(e.to_string()) + })?; + + // Extract the Lightning offer from the payment instructions + let offer = payment_instructions + .get(&PaymentType::LightningOffer) + .ok_or_else(|| { + tracing::error!("No Lightning offer found in BIP353 payment instructions"); + Error::Bip353NoLightningOffer + })?; + + tracing::debug!("Found Lightning offer in BIP353 instructions: {}", offer); + + // Create melt options with the provided amount + let options = MeltOptions::new_amountless(amount_msat); + + // Create a melt quote for the BOLT12 offer + self.melt_bolt12_quote(offer.clone(), Some(options)).await + } +} diff --git a/crates/cdk/src/wallet/melt/mod.rs b/crates/cdk/src/wallet/melt/mod.rs index 3dc4262af..09ab55cea 100644 --- a/crates/cdk/src/wallet/melt/mod.rs +++ b/crates/cdk/src/wallet/melt/mod.rs @@ -7,6 +7,8 @@ use tracing::instrument; use crate::Wallet; +#[cfg(feature = "bip353")] +mod melt_bip353; mod melt_bolt11; mod melt_bolt12; From 4e13c1958ff84fde7244b97b8f3eb207ba4f7615 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Tue, 19 Aug 2025 14:53:53 +0100 Subject: [PATCH 098/321] feat: mintd db features --- .github/workflows/ci.yml | 20 +++-- crates/cdk-integration-tests/Cargo.toml | 2 +- crates/cdk-mintd/Cargo.toml | 15 ++-- crates/cdk-mintd/build.rs | 29 ++++++ crates/cdk-mintd/src/lib.rs | 112 ++++++++++++++++++------ crates/cdk-mintd/src/main.rs | 4 + 6 files changed, 140 insertions(+), 42 deletions(-) create mode 100644 crates/cdk-mintd/build.rs diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9c3b23791..a584fe012 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -122,12 +122,20 @@ jobs: --bin cdk-mintd, --bin cdk-mintd --features redis, --bin cdk-mintd --features sqlcipher, - --bin cdk-mintd --no-default-features --features lnd, - --bin cdk-mintd --no-default-features --features cln, - --bin cdk-mintd --no-default-features --features lnbits, - --bin cdk-mintd --no-default-features --features fakewallet, - --bin cdk-mintd --no-default-features --features grpc-processor, - --bin cdk-mintd --no-default-features --features "management-rpc lnd", + --bin cdk-mintd --no-default-features --features lnd --features sqlite, + --bin cdk-mintd --no-default-features --features cln --features postgres, + --bin cdk-mintd --no-default-features --features lnbits --features sqlite, + --bin cdk-mintd --no-default-features --features fakewallet --features sqlite, + --bin cdk-mintd --no-default-features --features grpc-processor --features sqlite, + --bin cdk-mintd --no-default-features --features "management-rpc lnd sqlite", + --bin cdk-mintd --no-default-features --features cln --features sqlite, + --bin cdk-mintd --no-default-features --features lnd --features postgres, + --bin cdk-mintd --no-default-features --features lnbits --features postgres, + --bin cdk-mintd --no-default-features --features fakewallet --features postgres, + --bin cdk-mintd --no-default-features --features grpc-processor --features postgres, + --bin cdk-mintd --no-default-features --features "management-rpc cln postgres", + --bin cdk-mintd --no-default-features --features "auth sqlite fakewallet", + --bin cdk-mintd --no-default-features --features "auth postgres lnd", --bin cdk-mint-cli, ] steps: diff --git a/crates/cdk-integration-tests/Cargo.toml b/crates/cdk-integration-tests/Cargo.toml index 9de43f58f..febe40caf 100644 --- a/crates/cdk-integration-tests/Cargo.toml +++ b/crates/cdk-integration-tests/Cargo.toml @@ -28,7 +28,7 @@ cdk-sqlite = { workspace = true } cdk-redb = { workspace = true } cdk-fake-wallet = { workspace = true } cdk-common = { workspace = true, features = ["mint", "wallet", "auth"] } -cdk-mintd = { workspace = true, features = ["cln", "lnd", "fakewallet", "grpc-processor", "auth", "lnbits", "management-rpc"] } +cdk-mintd = { workspace = true, features = ["cln", "lnd", "fakewallet", "grpc-processor", "auth", "lnbits", "management-rpc", "sqlite", "postgres"] } futures = { workspace = true, default-features = false, features = [ "executor", ] } diff --git a/crates/cdk-mintd/Cargo.toml b/crates/cdk-mintd/Cargo.toml index d9fb63f4a..c55882d16 100644 --- a/crates/cdk-mintd/Cargo.toml +++ b/crates/cdk-mintd/Cargo.toml @@ -11,7 +11,10 @@ rust-version.workspace = true readme = "README.md" [features] -default = ["management-rpc", "cln", "lnd", "lnbits", "fakewallet", "grpc-processor", "auth"] +default = ["management-rpc", "cln", "lnd", "lnbits", "fakewallet", "grpc-processor", "sqlite"] +# Database features - at least one must be enabled +sqlite = ["dep:cdk-sqlite"] +postgres = ["dep:cdk-postgres"] # Ensure at least one lightning backend is enabled management-rpc = ["cdk-mint-rpc"] cln = ["dep:cdk-cln"] @@ -19,11 +22,11 @@ lnd = ["dep:cdk-lnd"] lnbits = ["dep:cdk-lnbits"] fakewallet = ["dep:cdk-fake-wallet"] grpc-processor = ["dep:cdk-payment-processor", "cdk-signatory/grpc"] -sqlcipher = ["cdk-sqlite/sqlcipher"] +sqlcipher = ["sqlite", "cdk-sqlite/sqlcipher"] # MSRV is not committed to with swagger enabled swagger = ["cdk-axum/swagger", "dep:utoipa", "dep:utoipa-swagger-ui"] redis = ["cdk-axum/redis"] -auth = ["cdk/auth", "cdk-sqlite/auth", "cdk-axum/auth"] +auth = ["cdk/auth", "cdk-axum/auth", "cdk-sqlite?/auth", "cdk-postgres?/auth"] [dependencies] anyhow.workspace = true @@ -33,9 +36,9 @@ cdk = { workspace = true, features = [ "mint", ] } cdk-sqlite = { workspace = true, features = [ - "mint", -] } -cdk-postgres = { workspace = true, features = ["mint"]} + "mint" +], optional = true } +cdk-postgres = { workspace = true, features = ["mint"], optional = true } cdk-cln = { workspace = true, optional = true } cdk-lnbits = { workspace = true, optional = true } cdk-lnd = { workspace = true, optional = true } diff --git a/crates/cdk-mintd/build.rs b/crates/cdk-mintd/build.rs new file mode 100644 index 000000000..3f833b77b --- /dev/null +++ b/crates/cdk-mintd/build.rs @@ -0,0 +1,29 @@ +fn main() { + // Check that at least one database feature is enabled + let has_database = cfg!(feature = "sqlite") || cfg!(feature = "postgres"); + + if !has_database { + panic!( + "cdk-mintd requires at least one database backend to be enabled.\n\ + Available database features: sqlite, postgres\n\ + Example: cargo build --features sqlite" + ); + } + + // Check that at least one Lightning backend is enabled + let has_lightning_backend = cfg!(feature = "cln") + || cfg!(feature = "lnd") + || cfg!(feature = "lnbits") + || cfg!(feature = "fakewallet") + || cfg!(feature = "grpc-processor"); + + if !has_lightning_backend { + panic!( + "cdk-mintd requires at least one Lightning backend to be enabled.\n\ + Available Lightning backends: cln, lnd, lnbits, fakewallet, grpc-processor\n\ + Example: cargo build --features \"sqlite fakewallet\"" + ); + } + + println!("cargo:rerun-if-changed=build.rs"); +} diff --git a/crates/cdk-mintd/src/lib.rs b/crates/cdk-mintd/src/lib.rs index 05b6966c2..78d0ea97d 100644 --- a/crates/cdk-mintd/src/lib.rs +++ b/crates/cdk-mintd/src/lib.rs @@ -39,9 +39,11 @@ use cdk::nuts::{AuthRequired, Method, ProtectedEndpoint, RoutePath}; use cdk::nuts::{ContactInfo, MintVersion, PaymentMethod}; use cdk::types::QuoteTTL; use cdk_axum::cache::HttpCache; +#[cfg(feature = "postgres")] use cdk_postgres::{MintPgAuthDatabase, MintPgDatabase}; -#[cfg(feature = "auth")] +#[cfg(all(feature = "auth", feature = "sqlite"))] use cdk_sqlite::mint::MintSqliteAuthDatabase; +#[cfg(feature = "sqlite")] use cdk_sqlite::MintSqliteDatabase; use cli::CLIArgs; use config::{AuthType, DatabaseEngine, LnBackend}; @@ -243,19 +245,21 @@ pub fn load_settings(work_dir: &Path, config_path: Option) -> Result, + _work_dir: &Path, + _db_password: Option, ) -> Result<( Arc + Send + Sync>, Arc + Send + Sync>, )> { match settings.database.engine { + #[cfg(feature = "sqlite")] DatabaseEngine::Sqlite => { - let db = setup_sqlite_database(work_dir, db_password).await?; + let db = setup_sqlite_database(_work_dir, _db_password).await?; let localstore: Arc + Send + Sync> = db.clone(); let keystore: Arc + Send + Sync> = db; Ok((localstore, keystore)) } + #[cfg(feature = "postgres")] DatabaseEngine::Postgres => { // Get the PostgreSQL configuration, ensuring it exists let pg_config = settings.database.postgres.as_ref().ok_or_else(|| { @@ -266,16 +270,33 @@ async fn setup_database( bail!("PostgreSQL URL is required. Set it in config file [database.postgres] section or via CDK_MINTD_POSTGRES_URL/CDK_MINTD_DATABASE_URL environment variable"); } + #[cfg(feature = "postgres")] let pg_db = Arc::new(MintPgDatabase::new(pg_config.url.as_str()).await?); + #[cfg(feature = "postgres")] let localstore: Arc + Send + Sync> = pg_db.clone(); - let keystore: Arc + Send + Sync> = - pg_db; - Ok((localstore, keystore)) + #[cfg(feature = "postgres")] + let keystore: Arc< + dyn MintKeysDatabase + Send + Sync, + > = pg_db; + #[cfg(feature = "postgres")] + return Ok((localstore, keystore)); + + #[cfg(not(feature = "postgres"))] + bail!("PostgreSQL support not compiled in. Enable the 'postgres' feature to use PostgreSQL database.") + } + #[cfg(not(feature = "sqlite"))] + DatabaseEngine::Sqlite => { + bail!("SQLite support not compiled in. Enable the 'sqlite' feature to use SQLite database.") + } + #[cfg(not(feature = "postgres"))] + DatabaseEngine::Postgres => { + bail!("PostgreSQL support not compiled in. Enable the 'postgres' feature to use PostgreSQL database.") } } } +#[cfg(feature = "sqlite")] async fn setup_sqlite_database( work_dir: &Path, _password: Option, @@ -529,8 +550,17 @@ async fn configure_backend_for_unit( mint_builder.set_unit_fee(&unit, input_fee)?; } - let nut17_supported = SupportedMethods::default_bolt11(unit); - mint_builder = mint_builder.with_supported_websockets(nut17_supported); + #[cfg(any( + feature = "cln", + feature = "lnbits", + feature = "lnd", + feature = "fakewallet", + feature = "grpc-processor" + ))] + { + let nut17_supported = SupportedMethods::default_bolt11(unit); + mint_builder = mint_builder.with_supported_websockets(nut17_supported); + } Ok(mint_builder) } @@ -550,7 +580,7 @@ fn configure_cache(settings: &config::Settings, mint_builder: MintBuilder) -> Mi #[cfg(feature = "auth")] async fn setup_authentication( settings: &config::Settings, - work_dir: &Path, + _work_dir: &Path, mut mint_builder: MintBuilder, _password: Option, ) -> Result { @@ -559,29 +589,53 @@ async fn setup_authentication( let auth_localstore: Arc< dyn cdk_database::MintAuthDatabase + Send + Sync, > = match settings.database.engine { + #[cfg(feature = "sqlite")] DatabaseEngine::Sqlite => { - let sql_db_path = work_dir.join("cdk-mintd-auth.sqlite"); - #[cfg(not(feature = "sqlcipher"))] - let sqlite_db = MintSqliteAuthDatabase::new(&sql_db_path).await?; - #[cfg(feature = "sqlcipher")] - let sqlite_db = { - // Get password from command line arguments for sqlcipher - MintSqliteAuthDatabase::new((sql_db_path, _password.unwrap())).await? - }; - - Arc::new(sqlite_db) + #[cfg(feature = "sqlite")] + { + let sql_db_path = _work_dir.join("cdk-mintd-auth.sqlite"); + #[cfg(not(feature = "sqlcipher"))] + let sqlite_db = MintSqliteAuthDatabase::new(&sql_db_path).await?; + #[cfg(feature = "sqlcipher")] + let sqlite_db = { + // Get password from command line arguments for sqlcipher + MintSqliteAuthDatabase::new((sql_db_path, _password.unwrap())).await? + }; + + Arc::new(sqlite_db) + } + #[cfg(not(feature = "sqlite"))] + { + bail!("SQLite support not compiled in. Enable the 'sqlite' feature to use SQLite database.") + } } + #[cfg(feature = "postgres")] DatabaseEngine::Postgres => { - // Get the PostgreSQL configuration, ensuring it exists - let pg_config = settings.database.postgres.as_ref().ok_or_else(|| { - anyhow!("PostgreSQL configuration is required when using PostgreSQL engine") - })?; - - if pg_config.url.is_empty() { - bail!("PostgreSQL URL is required for auth database. Set it in config file [database.postgres] section or via CDK_MINTD_POSTGRES_URL/CDK_MINTD_DATABASE_URL environment variable"); + #[cfg(feature = "postgres")] + { + // Get the PostgreSQL configuration, ensuring it exists + let pg_config = settings.database.postgres.as_ref().ok_or_else(|| { + anyhow!("PostgreSQL configuration is required when using PostgreSQL engine") + })?; + + if pg_config.url.is_empty() { + bail!("PostgreSQL URL is required for auth database. Set it in config file [database.postgres] section or via CDK_MINTD_POSTGRES_URL/CDK_MINTD_DATABASE_URL environment variable"); + } + + Arc::new(MintPgAuthDatabase::new(pg_config.url.as_str()).await?) } - - Arc::new(MintPgAuthDatabase::new(pg_config.url.as_str()).await?) + #[cfg(not(feature = "postgres"))] + { + bail!("PostgreSQL support not compiled in. Enable the 'postgres' feature to use PostgreSQL database.") + } + } + #[cfg(not(feature = "sqlite"))] + DatabaseEngine::Sqlite => { + bail!("SQLite support not compiled in. Enable the 'sqlite' feature to use SQLite database.") + } + #[cfg(not(feature = "postgres"))] + DatabaseEngine::Postgres => { + bail!("PostgreSQL support not compiled in. Enable the 'postgres' feature to use PostgreSQL database.") } }; diff --git a/crates/cdk-mintd/src/main.rs b/crates/cdk-mintd/src/main.rs index 468d0e23d..1d3dd64f9 100644 --- a/crates/cdk-mintd/src/main.rs +++ b/crates/cdk-mintd/src/main.rs @@ -14,6 +14,10 @@ compile_error!( "At least one lightning backend feature must be enabled: cln, lnbits, lnd, fakewallet, or grpc-processor" ); +// Ensure at least one database backend is enabled at compile time +#[cfg(not(any(feature = "sqlite", feature = "postgres")))] +compile_error!("At least one database backend feature must be enabled: sqlite or postgres"); + use anyhow::Result; use cdk_mintd::cli::CLIArgs; use cdk_mintd::{get_work_directory, load_settings}; From 951ff054fb61e20f99cbe6776354454c6a90a1bb Mon Sep 17 00:00:00 2001 From: vnprc Date: Thu, 21 Aug 2025 11:26:52 -0400 Subject: [PATCH 099/321] feat: zeroize cryptographic secrets on drop implement zeroize on Drop for Secret, Wallet, and MultiMintWallet this erases sensitive memory addresses before deallocation --- crates/cashu/Cargo.toml | 1 + crates/cashu/src/secret.rs | 7 +++++++ crates/cdk/Cargo.toml | 1 + crates/cdk/src/wallet/mod.rs | 7 +++++++ crates/cdk/src/wallet/multi_mint_wallet.rs | 7 +++++++ 5 files changed, 23 insertions(+) diff --git a/crates/cashu/Cargo.toml b/crates/cashu/Cargo.toml index 5a09dfcd8..378e51fd1 100644 --- a/crates/cashu/Cargo.toml +++ b/crates/cashu/Cargo.toml @@ -36,6 +36,7 @@ serde_with.workspace = true regex = { workspace = true, optional = true } strum = { workspace = true, optional = true } strum_macros = { workspace = true, optional = true } +zeroize = "1" [target.'cfg(target_arch = "wasm32")'.dependencies] instant = { workspace = true, features = ["wasm-bindgen", "inaccurate"] } diff --git a/crates/cashu/src/secret.rs b/crates/cashu/src/secret.rs index 08198d19c..6fe61723f 100644 --- a/crates/cashu/src/secret.rs +++ b/crates/cashu/src/secret.rs @@ -6,6 +6,7 @@ use std::str::FromStr; use bitcoin::secp256k1::rand::{self, RngCore}; use serde::{Deserialize, Serialize}; use thiserror::Error; +use zeroize::Zeroize; use crate::util::hex; @@ -121,6 +122,12 @@ impl TryFrom for crate::nuts::nut10::Secret { } } +impl Drop for Secret { + fn drop(&mut self) { + self.0.zeroize(); + } +} + impl TryFrom<&Secret> for crate::nuts::nut10::Secret { type Error = Error; diff --git a/crates/cdk/Cargo.toml b/crates/cdk/Cargo.toml index 8bcc70f1d..bd41c9f76 100644 --- a/crates/cdk/Cargo.toml +++ b/crates/cdk/Cargo.toml @@ -47,6 +47,7 @@ jsonwebtoken = { workspace = true, optional = true } sync_wrapper = "0.1.2" bech32 = "0.9.1" arc-swap = "1.7.1" +zeroize = "1" [target.'cfg(not(target_arch = "wasm32"))'.dependencies] tokio = { workspace = true, features = [ diff --git a/crates/cdk/src/wallet/mod.rs b/crates/cdk/src/wallet/mod.rs index 391476200..283641890 100644 --- a/crates/cdk/src/wallet/mod.rs +++ b/crates/cdk/src/wallet/mod.rs @@ -11,6 +11,7 @@ use subscription::{ActiveSubscription, SubscriptionManager}; #[cfg(feature = "auth")] use tokio::sync::RwLock; use tracing::instrument; +use zeroize::Zeroize; use crate::amount::SplitTarget; use crate::dhke::construct_proofs; @@ -657,3 +658,9 @@ impl Wallet { Ok(()) } } + +impl Drop for Wallet { + fn drop(&mut self) { + self.seed.zeroize(); + } +} diff --git a/crates/cdk/src/wallet/multi_mint_wallet.rs b/crates/cdk/src/wallet/multi_mint_wallet.rs index 7a07aedc1..3850620b8 100644 --- a/crates/cdk/src/wallet/multi_mint_wallet.rs +++ b/crates/cdk/src/wallet/multi_mint_wallet.rs @@ -13,6 +13,7 @@ use cdk_common::database::WalletDatabase; use cdk_common::wallet::{Transaction, TransactionDirection, WalletKey}; use tokio::sync::RwLock; use tracing::instrument; +use zeroize::Zeroize; use super::receive::ReceiveOptions; use super::send::{PreparedSend, SendOptions}; @@ -368,3 +369,9 @@ impl MultiMintWallet { wallet.verify_token_dleq(token).await } } + +impl Drop for MultiMintWallet { + fn drop(&mut self) { + self.seed.zeroize(); + } +} From 9b5f8d0534a72b6d6f06ada0c5cc66c4c75cd252 Mon Sep 17 00:00:00 2001 From: Cesar Rodas Date: Thu, 21 Aug 2025 15:16:38 -0300 Subject: [PATCH 100/321] Fixed bolt12 missing payments notifications --- crates/cdk/src/mint/issue/mod.rs | 54 ++++++--------------- crates/cdk/src/mint/ln.rs | 20 ++------ crates/cdk/src/mint/mod.rs | 37 +++++--------- crates/cdk/src/mint/subscription/manager.rs | 41 +++++++++++++++- 4 files changed, 71 insertions(+), 81 deletions(-) diff --git a/crates/cdk/src/mint/issue/mod.rs b/crates/cdk/src/mint/issue/mod.rs index 47aa43dcb..b12687190 100644 --- a/crates/cdk/src/mint/issue/mod.rs +++ b/crates/cdk/src/mint/issue/mod.rs @@ -440,29 +440,16 @@ impl Mint { payment_amount_quote_unit ); - tx.increment_mint_quote_amount_paid( - &mint_quote.id, - payment_amount_quote_unit, - wait_payment_response.payment_id, - ) - .await?; + let total_paid = tx + .increment_mint_quote_amount_paid( + &mint_quote.id, + payment_amount_quote_unit, + wait_payment_response.payment_id, + ) + .await?; - match mint_quote.payment_method { - PaymentMethod::Bolt11 => { - self.pubsub_manager - .mint_quote_bolt11_status(mint_quote.clone(), MintQuoteState::Paid); - } - PaymentMethod::Bolt12 => { - self.pubsub_manager.mint_quote_bolt12_status( - mint_quote.clone(), - wait_payment_response.payment_amount, - Amount::ZERO, - ); - } - _ => { - // We don't send ws updates for unknown methods - } - } + self.pubsub_manager + .mint_quote_payment(mint_quote, total_paid); } } else { tracing::info!("Received payment notification for already seen payment."); @@ -626,27 +613,16 @@ impl Mint { ) .await?; - tx.increment_mint_quote_amount_issued(&mint_request.quote, mint_request.total_amount()?) + let amount_issued = mint_request.total_amount()?; + + let total_issued = tx + .increment_mint_quote_amount_issued(&mint_request.quote, amount_issued) .await?; tx.commit().await?; - match mint_quote.payment_method { - PaymentMethod::Bolt11 => { - self.pubsub_manager - .mint_quote_bolt11_status(mint_quote.clone(), MintQuoteState::Issued); - } - PaymentMethod::Bolt12 => { - self.pubsub_manager.mint_quote_bolt12_status( - mint_quote.clone(), - Amount::ZERO, - mint_request.total_amount()?, - ); - } - PaymentMethod::Custom(_) => { - // We don't send ws updates for unknown methods - } - } + self.pubsub_manager + .mint_quote_issue(&mint_quote, total_issued); Ok(MintResponse { signatures: blind_signatures, diff --git a/crates/cdk/src/mint/ln.rs b/crates/cdk/src/mint/ln.rs index 607b5298f..447b0e3ec 100644 --- a/crates/cdk/src/mint/ln.rs +++ b/crates/cdk/src/mint/ln.rs @@ -61,25 +61,11 @@ impl Mint { quote.increment_amount_paid(amount_paid)?; quote.add_payment(amount_paid, payment.payment_id.clone(), unix_time())?; - tx.increment_mint_quote_amount_paid("e.id, amount_paid, payment.payment_id) + let total_paid = tx + .increment_mint_quote_amount_paid("e.id, amount_paid, payment.payment_id) .await?; - match quote.payment_method { - PaymentMethod::Bolt11 => { - self.pubsub_manager - .mint_quote_bolt11_status(quote.clone(), MintQuoteState::Paid); - } - PaymentMethod::Bolt12 => { - self.pubsub_manager.mint_quote_bolt12_status( - quote.clone(), - amount_paid, - Amount::ZERO, - ); - } - PaymentMethod::Custom(_) => { - // We don't send ws updates for unknown methods - } - } + self.pubsub_manager.mint_quote_payment(quote, total_paid); } } diff --git a/crates/cdk/src/mint/mod.rs b/crates/cdk/src/mint/mod.rs index db9733f3c..cc11509bb 100644 --- a/crates/cdk/src/mint/mod.rs +++ b/crates/cdk/src/mint/mod.rs @@ -573,29 +573,14 @@ impl Mint { payment_amount_quote_unit ); - tx.increment_mint_quote_amount_paid( - &mint_quote.id, - payment_amount_quote_unit, - wait_payment_response.payment_id, - ) - .await?; - - match mint_quote.payment_method { - PaymentMethod::Bolt11 => { - pubsub_manager - .mint_quote_bolt11_status(mint_quote.clone(), MintQuoteState::Paid); - } - PaymentMethod::Bolt12 => { - pubsub_manager.mint_quote_bolt12_status( - mint_quote.clone(), - payment_amount_quote_unit, - Amount::ZERO, - ); - } - _ => { - // We don't send ws updates for unknown methods - } - } + let total_paid = tx + .increment_mint_quote_amount_paid( + &mint_quote.id, + payment_amount_quote_unit, + wait_payment_response.payment_id, + ) + .await?; + pubsub_manager.mint_quote_payment(mint_quote, total_paid); } } else { tracing::info!("Received payment notification for already seen payment."); @@ -752,9 +737,13 @@ impl Mint { let amount = melt_quote.amount; - tx.increment_mint_quote_amount_paid(&mint_quote.id, amount, melt_quote.id.to_string()) + let total_paid = tx + .increment_mint_quote_amount_paid(&mint_quote.id, amount, melt_quote.id.to_string()) .await?; + self.pubsub_manager + .mint_quote_payment(&mint_quote, total_paid); + tracing::info!( "Melt quote {} paid Mint quote {}", melt_quote.id, diff --git a/crates/cdk/src/mint/subscription/manager.rs b/crates/cdk/src/mint/subscription/manager.rs index 7b1b693fb..96f484e3d 100644 --- a/crates/cdk/src/mint/subscription/manager.rs +++ b/crates/cdk/src/mint/subscription/manager.rs @@ -3,8 +3,9 @@ use std::ops::Deref; use std::sync::Arc; use cdk_common::database::{self, MintDatabase}; +use cdk_common::mint::MintQuote; use cdk_common::nut17::Notification; -use cdk_common::{Amount, MintQuoteBolt12Response, NotificationPayload}; +use cdk_common::{Amount, MintQuoteBolt12Response, NotificationPayload, PaymentMethod}; use uuid::Uuid; use super::OnSubscription; @@ -48,6 +49,44 @@ impl PubSubManager { self.broadcast(event.into().into()); } + /// Helper function to publish even of a mint quote being paid + pub fn mint_quote_issue(&self, mint_quote: &MintQuote, total_issued: Amount) { + match mint_quote.payment_method { + PaymentMethod::Bolt11 => { + self.mint_quote_bolt11_status(mint_quote.clone(), MintQuoteState::Issued); + } + PaymentMethod::Bolt12 => { + self.mint_quote_bolt12_status( + mint_quote.clone(), + mint_quote.amount_paid(), + total_issued, + ); + } + _ => { + // We don't send ws updates for unknown methods + } + } + } + + /// Helper function to publish even of a mint quote being paid + pub fn mint_quote_payment(&self, mint_quote: &MintQuote, total_paid: Amount) { + match mint_quote.payment_method { + PaymentMethod::Bolt11 => { + self.mint_quote_bolt11_status(mint_quote.clone(), MintQuoteState::Paid); + } + PaymentMethod::Bolt12 => { + self.mint_quote_bolt12_status( + mint_quote.clone(), + total_paid, + mint_quote.amount_issued(), + ); + } + _ => { + // We don't send ws updates for unknown methods + } + } + } + /// Helper function to emit a MintQuoteBolt11Response status pub fn mint_quote_bolt11_status>>( &self, From 8dec41dd55aa08433a134b271fb2f802ca09e9a5 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Thu, 21 Aug 2025 21:54:48 +0100 Subject: [PATCH 101/321] =?UTF-8?q?refactor(cdk-lnbits):=20migrate=20to=20?= =?UTF-8?q?LNbits=20v1=20websocket=20API=20and=20remove=20w=E2=80=A6=20(#9?= =?UTF-8?q?87)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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 --- README.md | 2 +- crates/cdk-lnbits/Cargo.toml | 3 +- crates/cdk-lnbits/README.md | 2 + crates/cdk-lnbits/src/lib.rs | 135 +++++++++++----------- crates/cdk-mintd/example.config.toml | 3 +- crates/cdk-mintd/src/config.rs | 1 - crates/cdk-mintd/src/lib.rs | 2 +- crates/cdk-mintd/src/setup.rs | 40 +------ crates/cdk/src/wallet/auth/auth_wallet.rs | 2 +- 9 files changed, 76 insertions(+), 114 deletions(-) diff --git a/README.md b/README.md index 95dbe8aba..e04d41b71 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ The project is split up into several crates in the `crates/` directory: * [**cdk-axum**](./crates/cdk-axum/): Axum webserver for mint. * [**cdk-cln**](./crates/cdk-cln/): CLN Lightning backend for mint. * [**cdk-lnd**](./crates/cdk-lnd/): Lnd Lightning backend for mint. - * [**cdk-lnbits**](./crates/cdk-lnbits/): [LNbits](https://lnbits.com/) Lightning backend for mint. + * [**cdk-lnbits**](./crates/cdk-lnbits/): [LNbits](https://lnbits.com/) Lightning backend for mint. **Note: Only LNBits v1 API is supported.** * [**cdk-fake-wallet**](./crates/cdk-fake-wallet/): Fake Lightning backend for mint. To be used only for testing, quotes are automatically filled. * [**cdk-mint-rpc**](./crates/cdk-mint-rpc/): Mint management gRPC server and cli. * Binaries: diff --git a/crates/cdk-lnbits/Cargo.toml b/crates/cdk-lnbits/Cargo.toml index e99303cb1..5429a0377 100644 --- a/crates/cdk-lnbits/Cargo.toml +++ b/crates/cdk-lnbits/Cargo.toml @@ -13,7 +13,6 @@ readme = "README.md" [dependencies] async-trait.workspace = true anyhow.workspace = true -axum.workspace = true bitcoin.workspace = true cdk-common = { workspace = true, features = ["mint"] } futures.workspace = true @@ -21,6 +20,6 @@ tokio.workspace = true tokio-util.workspace = true tracing.workspace = true thiserror.workspace = true -lnbits-rs = "0.6.0" +lnbits-rs = "0.8.0" serde_json.workspace = true rustls.workspace = true diff --git a/crates/cdk-lnbits/README.md b/crates/cdk-lnbits/README.md index 2e74d8d70..46cffe01d 100644 --- a/crates/cdk-lnbits/README.md +++ b/crates/cdk-lnbits/README.md @@ -8,6 +8,8 @@ LNBits backend implementation for the Cashu Development Kit (CDK). This provides integration with [LNBits](https://lnbits.com/) for Lightning Network functionality. +**Note: Only LNBits v1 API is supported.** This backend uses the websocket-based v1 API for real-time payment notifications. + ## Installation Add this to your `Cargo.toml`: diff --git a/crates/cdk-lnbits/src/lib.rs b/crates/cdk-lnbits/src/lib.rs index 6c346ce10..bda71b2ac 100644 --- a/crates/cdk-lnbits/src/lib.rs +++ b/crates/cdk-lnbits/src/lib.rs @@ -11,7 +11,6 @@ use std::sync::Arc; use anyhow::anyhow; use async_trait::async_trait; -use axum::Router; use cdk_common::amount::{to_unit, Amount, MSAT_IN_SAT}; use cdk_common::common::FeeReserve; use cdk_common::nuts::{CurrencyUnit, MeltOptions, MeltQuoteState}; @@ -36,7 +35,6 @@ pub mod error; pub struct LNbits { lnbits_api: LNBitsClient, fee_reserve: FeeReserve, - webhook_url: Option, wait_invoice_cancel_token: CancellationToken, wait_invoice_is_active: Arc, settings: Bolt11Settings, @@ -50,14 +48,12 @@ impl LNbits { invoice_api_key: String, api_url: String, fee_reserve: FeeReserve, - webhook_url: Option, ) -> Result { let lnbits_api = LNBitsClient::new("", &admin_api_key, &invoice_api_key, &api_url, None)?; Ok(Self { lnbits_api, fee_reserve, - webhook_url, wait_invoice_cancel_token: CancellationToken::new(), wait_invoice_is_active: Arc::new(AtomicBool::new(false)), settings: Bolt11Settings { @@ -83,6 +79,64 @@ impl LNbits { Error::Anyhow(err) }) } + + /// Process an incoming message from the websocket receiver + async fn process_message( + msg_option: Option, + api: &LNBitsClient, + _is_active: &Arc, + ) -> Option { + let msg = msg_option?; + + let payment = match api.get_payment_info(&msg).await { + Ok(payment) => payment, + Err(_) => return None, + }; + + if !payment.paid { + tracing::warn!( + "Received payment notification but payment not paid for {}", + msg + ); + return None; + } + + Self::create_payment_response(&msg, &payment).unwrap_or_else(|e| { + tracing::error!("Failed to create payment response: {}", e); + None + }) + } + + /// Create a payment response from payment info + fn create_payment_response( + msg: &str, + payment: &lnbits_rs::api::payment::Payment, + ) -> Result, Error> { + let amount = payment.details.amount; + + if amount == i64::MIN { + return Ok(None); + } + + let hash = Self::decode_payment_hash(msg)?; + + Ok(Some(WaitPaymentResponse { + payment_identifier: PaymentIdentifier::PaymentHash(hash), + payment_amount: Amount::from(amount.unsigned_abs()), + unit: CurrencyUnit::Msat, + payment_id: msg.to_string(), + })) + } + + /// Decode a hex payment hash string into a byte array + fn decode_payment_hash(hash_str: &str) -> Result<[u8; 32], Error> { + let decoded = hex::decode(hash_str) + .map_err(|e| Error::Anyhow(anyhow!("Failed to decode payment hash: {}", e)))?; + + decoded + .try_into() + .map_err(|_| Error::Anyhow(anyhow!("Invalid payment hash length"))) + } } #[async_trait] @@ -118,54 +172,14 @@ impl MintPayment for LNbits { tokio::select! { _ = cancel_token.cancelled() => { - // Stream is cancelled is_active.store(false, Ordering::SeqCst); tracing::info!("Waiting for lnbits invoice ending"); None } msg_option = receiver.recv() => { - match msg_option { - Some(msg) => { - let check = api.get_payment_info(&msg).await; - match check { - Ok(payment) => { - if payment.paid { - match hex::decode(msg.clone()) { - Ok(decoded) => { - match decoded.try_into() { - Ok(hash) => { - let response = WaitPaymentResponse { - payment_identifier: PaymentIdentifier::PaymentHash(hash), - payment_amount: Amount::from(payment.details.amount as u64), - unit: CurrencyUnit::Msat, - payment_id: msg.clone() - }; - Some((response, (api, cancel_token, is_active))) - }, - Err(e) => { - tracing::error!("Failed to convert payment hash bytes to array: {:?}", e); - None - } - } - }, - Err(e) => { - tracing::error!("Failed to decode payment hash hex string: {}", e); - None - } - } - } else { - tracing::warn!("Received payment notification but could not check payment for {}", msg); - None - } - }, - Err(_) => None - } - }, - None => { - is_active.store(false, Ordering::SeqCst); - None - } - } + Self::process_message(msg_option, &api, &is_active) + .await + .map(|response| (response, (api, cancel_token, is_active))) } } }, @@ -306,7 +320,6 @@ impl MintPayment for LNbits { memo: Some(description), unit: unit.to_string(), expiry, - webhook: self.webhook_url.clone(), internal: None, out: false, }; @@ -321,10 +334,8 @@ impl MintPayment for LNbits { Self::Err::Anyhow(anyhow!("Could not create invoice")) })?; - let request: Bolt11Invoice = create_invoice_response - .bolt11() - .ok_or_else(|| Self::Err::Anyhow(anyhow!("Missing bolt11 invoice")))? - .parse()?; + let request: Bolt11Invoice = create_invoice_response.bolt11().parse()?; + let expiry = request.expires_at().map(|t| t.as_secs()); Ok(CreateIncomingPaymentResponse { @@ -389,7 +400,7 @@ impl MintPayment for LNbits { let pay_response = MakePaymentResponse { payment_lookup_id: payment_identifier.clone(), payment_proof: payment.preimage, - status: lnbits_to_melt_status(&payment.details.status, payment.details.pending), + status: lnbits_to_melt_status(&payment.details.status), total_spent: Amount::from( payment.details.amount.unsigned_abs() + payment.details.fee.unsigned_abs(), ), @@ -400,11 +411,7 @@ impl MintPayment for LNbits { } } -fn lnbits_to_melt_status(status: &str, pending: Option) -> MeltQuoteState { - if pending.unwrap_or_default() { - return MeltQuoteState::Pending; - } - +fn lnbits_to_melt_status(status: &str) -> MeltQuoteState { match status { "success" => MeltQuoteState::Paid, "failed" => MeltQuoteState::Unpaid, @@ -412,15 +419,3 @@ fn lnbits_to_melt_status(status: &str, pending: Option) -> MeltQuoteState _ => MeltQuoteState::Unknown, } } - -impl LNbits { - /// Create invoice webhook - pub async fn create_invoice_webhook_router( - &self, - webhook_endpoint: &str, - ) -> anyhow::Result { - self.lnbits_api - .create_invoice_webhook_router(webhook_endpoint) - .await - } -} diff --git a/crates/cdk-mintd/example.config.toml b/crates/cdk-mintd/example.config.toml index f3389fa5a..30983d1e2 100644 --- a/crates/cdk-mintd/example.config.toml +++ b/crates/cdk-mintd/example.config.toml @@ -80,8 +80,7 @@ reserve_fee_min = 4 # admin_api_key = "" # invoice_api_key = "" # lnbits_api = "" -# To be set true to support pre v1 lnbits api -# retro_api=false +# Note: Only LNBits v1 API is supported (websocket-based) # [lnd] # address = "https://domain:port" diff --git a/crates/cdk-mintd/src/config.rs b/crates/cdk-mintd/src/config.rs index 4c9af2a6a..602901658 100644 --- a/crates/cdk-mintd/src/config.rs +++ b/crates/cdk-mintd/src/config.rs @@ -161,7 +161,6 @@ pub struct LNbits { pub lnbits_api: String, pub fee_percent: f32, pub reserve_fee_min: Amount, - pub retro_api: bool, } #[cfg(feature = "cln")] diff --git a/crates/cdk-mintd/src/lib.rs b/crates/cdk-mintd/src/lib.rs index 05b6966c2..e19da85f7 100644 --- a/crates/cdk-mintd/src/lib.rs +++ b/crates/cdk-mintd/src/lib.rs @@ -103,7 +103,7 @@ pub fn setup_tracing( logging_config: &config::LoggingConfig, ) -> Result> { let default_filter = "debug"; - let hyper_filter = "hyper=warn"; + let hyper_filter = "hyper=warn,rustls=warn,reqwest=warn"; let h2_filter = "h2=warn"; let tower_http = "tower_http=warn"; diff --git a/crates/cdk-mintd/src/setup.rs b/crates/cdk-mintd/src/setup.rs index 0bbd950ec..507de0e39 100644 --- a/crates/cdk-mintd/src/setup.rs +++ b/crates/cdk-mintd/src/setup.rs @@ -10,8 +10,6 @@ use axum::Router; #[cfg(feature = "fakewallet")] use bip39::rand::{thread_rng, Rng}; use cdk::cdk_payment::MintPayment; -#[cfg(feature = "lnbits")] -use cdk::mint_url::MintUrl; use cdk::nuts::CurrencyUnit; #[cfg(any( feature = "lnbits", @@ -67,58 +65,28 @@ impl LnBackendSetup for config::Cln { impl LnBackendSetup for config::LNbits { async fn setup( &self, - routers: &mut Vec, - settings: &Settings, + _routers: &mut Vec, + _settings: &Settings, _unit: CurrencyUnit, ) -> anyhow::Result { let admin_api_key = &self.admin_api_key; let invoice_api_key = &self.invoice_api_key; - // Channel used for lnbits web hook - let webhook_endpoint = "/webhook/lnbits/sat/invoice"; - let fee_reserve = FeeReserve { min_fee_reserve: self.reserve_fee_min, percent_fee_reserve: self.fee_percent, }; - let webhook_url = if settings - .lnbits - .as_ref() - .expect("Lnbits must be defined") - .retro_api - { - let mint_url: MintUrl = settings.info.url.parse()?; - let webhook_url = mint_url.join(webhook_endpoint)?; - - Some(webhook_url.to_string()) - } else { - None - }; - let lnbits = cdk_lnbits::LNbits::new( admin_api_key.clone(), invoice_api_key.clone(), self.lnbits_api.clone(), fee_reserve, - webhook_url, ) .await?; - if settings - .lnbits - .as_ref() - .expect("Lnbits must be defined") - .retro_api - { - let router = lnbits - .create_invoice_webhook_router(webhook_endpoint) - .await?; - - routers.push(router); - } else { - lnbits.subscribe_ws().await?; - }; + // Use v1 websocket API + lnbits.subscribe_ws().await?; Ok(lnbits) } diff --git a/crates/cdk/src/wallet/auth/auth_wallet.rs b/crates/cdk/src/wallet/auth/auth_wallet.rs index 5be0df2ec..d61f2bb5b 100644 --- a/crates/cdk/src/wallet/auth/auth_wallet.rs +++ b/crates/cdk/src/wallet/auth/auth_wallet.rs @@ -23,7 +23,7 @@ use crate::{Amount, Error, OidcClient}; /// JWT Claims structure for decoding tokens #[derive(Debug, Serialize, Deserialize)] -struct Claims { +struct _Claims { /// Subject sub: Option, /// Expiration time (as UTC timestamp) From ea9b9324f68aeca48e04bfb736ee4e1d8f9db72b Mon Sep 17 00:00:00 2001 From: lollerfirst Date: Fri, 22 Aug 2025 13:10:43 +0200 Subject: [PATCH 102/321] fix left-over `y` in blind_signatures table auth database --- .../cdk-sql-common/src/mint/auth/migrations.rs | 2 ++ ...0250822104351_rename_blind_message_y_to_b.sql | 2 ++ ...0250822104351_rename_blind_message_y_to_b.sql | 2 ++ crates/cdk-sql-common/src/mint/auth/mod.rs | 16 ++++++++-------- 4 files changed, 14 insertions(+), 8 deletions(-) create mode 100644 crates/cdk-sql-common/src/mint/auth/migrations/postgres/20250822104351_rename_blind_message_y_to_b.sql create mode 100644 crates/cdk-sql-common/src/mint/auth/migrations/sqlite/20250822104351_rename_blind_message_y_to_b.sql diff --git a/crates/cdk-sql-common/src/mint/auth/migrations.rs b/crates/cdk-sql-common/src/mint/auth/migrations.rs index a285e48a8..ee53d6bdb 100644 --- a/crates/cdk-sql-common/src/mint/auth/migrations.rs +++ b/crates/cdk-sql-common/src/mint/auth/migrations.rs @@ -2,6 +2,8 @@ /// Auto-generated by build.rs pub static MIGRATIONS: &[(&str, &str, &str)] = &[ ("postgres", "1_init.sql", include_str!(r#"./migrations/postgres/1_init.sql"#)), + ("postgres", "20250822104351_rename_blind_message_y_to_b.sql", include_str!(r#"./migrations/postgres/20250822104351_rename_blind_message_y_to_b.sql"#)), ("sqlite", "1_fix_sqlx_migration.sql", include_str!(r#"./migrations/sqlite/1_fix_sqlx_migration.sql"#)), ("sqlite", "20250109143347_init.sql", include_str!(r#"./migrations/sqlite/20250109143347_init.sql"#)), + ("sqlite", "20250822104351_rename_blind_message_y_to_b.sql", include_str!(r#"./migrations/sqlite/20250822104351_rename_blind_message_y_to_b.sql"#)), ]; diff --git a/crates/cdk-sql-common/src/mint/auth/migrations/postgres/20250822104351_rename_blind_message_y_to_b.sql b/crates/cdk-sql-common/src/mint/auth/migrations/postgres/20250822104351_rename_blind_message_y_to_b.sql new file mode 100644 index 000000000..b3a45f059 --- /dev/null +++ b/crates/cdk-sql-common/src/mint/auth/migrations/postgres/20250822104351_rename_blind_message_y_to_b.sql @@ -0,0 +1,2 @@ +-- Rename column y to b +ALTER TABLE blind_signature RENAME COLUMN y TO blinded_message; \ No newline at end of file diff --git a/crates/cdk-sql-common/src/mint/auth/migrations/sqlite/20250822104351_rename_blind_message_y_to_b.sql b/crates/cdk-sql-common/src/mint/auth/migrations/sqlite/20250822104351_rename_blind_message_y_to_b.sql new file mode 100644 index 000000000..b3a45f059 --- /dev/null +++ b/crates/cdk-sql-common/src/mint/auth/migrations/sqlite/20250822104351_rename_blind_message_y_to_b.sql @@ -0,0 +1,2 @@ +-- Rename column y to b +ALTER TABLE blind_signature RENAME COLUMN y TO blinded_message; \ No newline at end of file diff --git a/crates/cdk-sql-common/src/mint/auth/mod.rs b/crates/cdk-sql-common/src/mint/auth/mod.rs index 60f4f4bac..8effd9fc2 100644 --- a/crates/cdk-sql-common/src/mint/auth/mod.rs +++ b/crates/cdk-sql-common/src/mint/auth/mod.rs @@ -174,12 +174,12 @@ where r#" INSERT INTO blind_signature - (y, amount, keyset_id, c) + (blinded_message, amount, keyset_id, c) VALUES - (:y, :amount, :keyset_id, :c) + (:blinded_message, :amount, :keyset_id, :c) "#, )? - .bind("y", message.to_bytes().to_vec()) + .bind("blinded_message", message.to_bytes().to_vec()) .bind("amount", u64::from(signature.amount) as i64) .bind("keyset_id", signature.keyset_id.to_string()) .bind("c", signature.c.to_bytes().to_vec()) @@ -353,17 +353,17 @@ where c, dleq_e, dleq_s, - y + blinded_message, FROM blind_signature - WHERE y IN (:y) + WHERE blinded_message IN (:blinded_message) "#, )? .bind_vec( - "y", + "blinded_message", blinded_messages .iter() - .map(|y| y.to_bytes().to_vec()) + .map(|bm| bm.to_bytes().to_vec()) .collect(), ) .fetch_all(&*conn) @@ -382,7 +382,7 @@ where .collect::, Error>>()?; Ok(blinded_messages .iter() - .map(|y| blinded_signatures.remove(y)) + .map(|bm| blinded_signatures.remove(bm)) .collect()) } From 3772f10202ed31dd12167934ba90f9f729d9c804 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Mon, 25 Aug 2025 16:21:00 +0100 Subject: [PATCH 103/321] chore: update flake --- flake.lock | 42 +++++++++++++++++++++--------------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/flake.lock b/flake.lock index 8589eaed4..0b3c79813 100644 --- a/flake.lock +++ b/flake.lock @@ -2,11 +2,11 @@ "nodes": { "crane": { "locked": { - "lastModified": 1753316655, - "narHash": "sha256-tzWa2kmTEN69OEMhxFy+J2oWSvZP5QhEgXp3TROOzl0=", + "lastModified": 1755993354, + "narHash": "sha256-FCRRAzSaL/+umLIm3RU3O/+fJ2ssaPHseI2SSFL8yZU=", "owner": "ipetkov", "repo": "crane", - "rev": "f35a3372d070c9e9ccb63ba7ce347f0634ddf3d2", + "rev": "25bd41b24426c7734278c2ff02e53258851db914", "type": "github" }, "original": { @@ -23,11 +23,11 @@ "rust-analyzer-src": [] }, "locked": { - "lastModified": 1753511988, - "narHash": "sha256-wC9PR+rPjmcpnPdOIDwyNwQiRhNsuDs3oZY3t42f4uA=", + "lastModified": 1755585599, + "narHash": "sha256-tl/0cnsqB/Yt7DbaGMel2RLa7QG5elA8lkaOXli6VdY=", "owner": "nix-community", "repo": "fenix", - "rev": "25db7a6f4de7dea678620785e03fbc4560c00672", + "rev": "6ed03ef4c8ec36d193c18e06b9ecddde78fb7e42", "type": "github" }, "original": { @@ -39,11 +39,11 @@ "flake-compat": { "flake": false, "locked": { - "lastModified": 1696426674, - "narHash": "sha256-kvjfFW7WAETZlt09AgDn1MrtKzP7t90Vf7vypd3OL1U=", + "lastModified": 1747046372, + "narHash": "sha256-CIVLLkVgvHYbgI2UpXvIIBJ12HWgX+fjA8Xf8PUmqCY=", "owner": "edolstra", "repo": "flake-compat", - "rev": "0f9255e01c2351cc7d116c072cb317785dd33b33", + "rev": "9100a0f413b0c601e0533d1d94ffd501ce2e7885", "type": "github" }, "original": { @@ -93,11 +93,11 @@ }, "nixpkgs": { "locked": { - "lastModified": 1753345091, - "narHash": "sha256-CdX2Rtvp5I8HGu9swBmYuq+ILwRxpXdJwlpg8jvN4tU=", + "lastModified": 1755922037, + "narHash": "sha256-wY1+2JPH0ZZC4BQefoZw/k+3+DowFyfOxv17CN/idKs=", "owner": "NixOS", "repo": "nixpkgs", - "rev": "3ff0e34b1383648053bba8ed03f201d3466f90c9", + "rev": "b1b3291469652d5a2edb0becc4ef0246fff97a7c", "type": "github" }, "original": { @@ -109,11 +109,11 @@ }, "nixpkgs_2": { "locked": { - "lastModified": 1730768919, - "narHash": "sha256-8AKquNnnSaJRXZxc5YmF/WfmxiHX6MMZZasRP6RRQkE=", + "lastModified": 1754340878, + "narHash": "sha256-lgmUyVQL9tSnvvIvBp7x1euhkkCho7n3TMzgjdvgPoU=", "owner": "NixOS", "repo": "nixpkgs", - "rev": "a04d33c0c3f1a59a2c1cb0c6e34cd24500e5a1dc", + "rev": "cab778239e705082fe97bb4990e0d24c50924c04", "type": "github" }, "original": { @@ -130,11 +130,11 @@ "nixpkgs": "nixpkgs_2" }, "locked": { - "lastModified": 1750779888, - "narHash": "sha256-wibppH3g/E2lxU43ZQHC5yA/7kIKLGxVEnsnVK1BtRg=", + "lastModified": 1755960406, + "narHash": "sha256-RF7j6C1TmSTK9tYWO6CdEMtg6XZaUKcvZwOCD2SICZs=", "owner": "cachix", "repo": "pre-commit-hooks.nix", - "rev": "16ec914f6fb6f599ce988427d9d94efddf25fe6d", + "rev": "e891a93b193fcaf2fc8012d890dc7f0befe86ec2", "type": "github" }, "original": { @@ -160,11 +160,11 @@ ] }, "locked": { - "lastModified": 1753497720, - "narHash": "sha256-yzZkDMVfPpNyTciQOfriWpRXrgGNT/cvrFAEQZ//SZs=", + "lastModified": 1756089517, + "narHash": "sha256-KGinVKturJFPrRebgvyUB1BUNqf1y9FN+tSJaTPlnFE=", "owner": "oxalica", "repo": "rust-overlay", - "rev": "c8b8b812010515b7d9bd7e538f06a9f4edb373ff", + "rev": "44774c8c83cd392c50914f86e1ff75ef8619f1cd", "type": "github" }, "original": { From 9ab86fabfe9efdfb947804b7f051ec35b80a7a2a Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Mon, 25 Aug 2025 22:06:00 +0100 Subject: [PATCH 104/321] Cdk ldk node (#904) * 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> --- .github/workflows/ci.yml | 4 +- .github/workflows/nutshell_itest.yml | 20 + CHANGELOG.md | 5 + Cargo.toml | 6 +- README.md | 17 + crates/cdk-cln/src/lib.rs | 6 +- crates/cdk-common/src/database/mod.rs | 3 + crates/cdk-common/src/error.rs | 5 + crates/cdk-common/src/payment.rs | 23 + crates/cdk-integration-tests/Cargo.toml | 5 +- .../src/bin/start_fake_auth_mint.rs | 8 +- .../src/bin/start_fake_mint.rs | 8 +- .../src/bin/start_regtest.rs | 32 +- .../src/bin/start_regtest_mints.rs | 449 ++++-- crates/cdk-integration-tests/src/cli.rs | 3 +- .../cdk-integration-tests/src/init_regtest.rs | 118 +- crates/cdk-integration-tests/src/lib.rs | 103 +- crates/cdk-integration-tests/src/shared.rs | 61 +- crates/cdk-integration-tests/tests/bolt12.rs | 63 + .../tests/happy_path_mint_wallet.rs | 12 +- .../cdk-integration-tests/tests/ldk_node.rs | 63 + crates/cdk-integration-tests/tests/regtest.rs | 123 +- .../cdk-integration-tests/tests/test_fees.rs | 4 +- crates/cdk-ldk-node/Cargo.toml | 34 + crates/cdk-ldk-node/NETWORK_GUIDE.md | 165 ++ crates/cdk-ldk-node/README.md | 84 ++ crates/cdk-ldk-node/src/error.rs | 89 ++ crates/cdk-ldk-node/src/lib.rs | 994 ++++++++++++ .../cdk-ldk-node/src/web/handlers/channels.rs | 515 +++++++ .../src/web/handlers/dashboard.rs | 276 ++++ .../cdk-ldk-node/src/web/handlers/invoices.rs | 293 ++++ .../src/web/handlers/lightning.rs | 171 +++ crates/cdk-ldk-node/src/web/handlers/mod.rs | 17 + .../cdk-ldk-node/src/web/handlers/onchain.rs | 479 ++++++ .../cdk-ldk-node/src/web/handlers/payments.rs | 615 ++++++++ crates/cdk-ldk-node/src/web/handlers/utils.rs | 91 ++ crates/cdk-ldk-node/src/web/mod.rs | 6 + crates/cdk-ldk-node/src/web/server.rs | 78 + crates/cdk-ldk-node/src/web/static_files.rs | 47 + .../src/web/templates/components.rs | 36 + .../src/web/templates/formatters.rs | 150 ++ .../cdk-ldk-node/src/web/templates/layout.rs | 1326 +++++++++++++++++ crates/cdk-ldk-node/src/web/templates/mod.rs | 10 + .../src/web/templates/payments.rs | 105 ++ crates/cdk-ldk-node/static/css/globe.css | 75 + crates/cdk-ldk-node/static/favicon.ico | Bin 0 -> 142 bytes crates/cdk-ldk-node/static/favicon.svg | 6 + crates/cdk-ldk-node/static/images/bg-dark.jpg | Bin 0 -> 47534 bytes crates/cdk-ldk-node/static/images/bg.jpg | Bin 0 -> 620237 bytes crates/cdk-ldk-node/static/images/nut.png | Bin 0 -> 1216124 bytes crates/cdk-mintd/Cargo.toml | 6 +- crates/cdk-mintd/build.rs | 3 +- crates/cdk-mintd/example.config.toml | 43 +- crates/cdk-mintd/src/config.rs | 157 +- crates/cdk-mintd/src/env_vars/ldk_node.rs | 103 ++ crates/cdk-mintd/src/env_vars/mod.rs | 8 + crates/cdk-mintd/src/lib.rs | 49 +- crates/cdk-mintd/src/main.rs | 50 +- crates/cdk-mintd/src/setup.rs | 149 ++ crates/cdk-payment-processor/src/proto/mod.rs | 4 + .../src/proto/payment_processor.proto | 1 + crates/cdk-sql-common/src/mint/mod.rs | 12 + crates/cdk/src/mint/issue/mod.rs | 64 +- crates/cdk/src/mint/mod.rs | 84 +- crates/cdk/src/wallet/issue/issue_bolt12.rs | 4 +- justfile | 2 +- misc/interactive_regtest_mprocs.sh | 66 +- misc/itests.sh | 88 +- misc/mintd_payment_processor.sh | 3 +- misc/regtest_helper.sh | 34 + misc/scripts/filtered_ldk_node_log.sh | 19 + 71 files changed, 7351 insertions(+), 401 deletions(-) create mode 100644 crates/cdk-integration-tests/tests/ldk_node.rs create mode 100644 crates/cdk-ldk-node/Cargo.toml create mode 100644 crates/cdk-ldk-node/NETWORK_GUIDE.md create mode 100644 crates/cdk-ldk-node/README.md create mode 100644 crates/cdk-ldk-node/src/error.rs create mode 100644 crates/cdk-ldk-node/src/lib.rs create mode 100644 crates/cdk-ldk-node/src/web/handlers/channels.rs create mode 100644 crates/cdk-ldk-node/src/web/handlers/dashboard.rs create mode 100644 crates/cdk-ldk-node/src/web/handlers/invoices.rs create mode 100644 crates/cdk-ldk-node/src/web/handlers/lightning.rs create mode 100644 crates/cdk-ldk-node/src/web/handlers/mod.rs create mode 100644 crates/cdk-ldk-node/src/web/handlers/onchain.rs create mode 100644 crates/cdk-ldk-node/src/web/handlers/payments.rs create mode 100644 crates/cdk-ldk-node/src/web/handlers/utils.rs create mode 100644 crates/cdk-ldk-node/src/web/mod.rs create mode 100644 crates/cdk-ldk-node/src/web/server.rs create mode 100644 crates/cdk-ldk-node/src/web/static_files.rs create mode 100644 crates/cdk-ldk-node/src/web/templates/components.rs create mode 100644 crates/cdk-ldk-node/src/web/templates/formatters.rs create mode 100644 crates/cdk-ldk-node/src/web/templates/layout.rs create mode 100644 crates/cdk-ldk-node/src/web/templates/mod.rs create mode 100644 crates/cdk-ldk-node/src/web/templates/payments.rs create mode 100644 crates/cdk-ldk-node/static/css/globe.css create mode 100644 crates/cdk-ldk-node/static/favicon.ico create mode 100644 crates/cdk-ldk-node/static/favicon.svg create mode 100644 crates/cdk-ldk-node/static/images/bg-dark.jpg create mode 100644 crates/cdk-ldk-node/static/images/bg.jpg create mode 100644 crates/cdk-ldk-node/static/images/nut.png create mode 100644 crates/cdk-mintd/src/env_vars/ldk_node.rs create mode 100755 misc/scripts/filtered_ldk_node_log.sh diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a584fe012..ddba0daf0 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -112,8 +112,10 @@ jobs: -p cdk-lnbits, -p cdk-fake-wallet, -p cdk-payment-processor, - -p cdk-mint-rpc, + -p cdk-ldk-node, + -p cdk-signatory, + -p cdk-mint-rpc, # Binaries --bin cdk-cli, diff --git a/.github/workflows/nutshell_itest.yml b/.github/workflows/nutshell_itest.yml index 4e331d89b..bac6ae65d 100644 --- a/.github/workflows/nutshell_itest.yml +++ b/.github/workflows/nutshell_itest.yml @@ -10,6 +10,16 @@ jobs: steps: - name: checkout uses: actions/checkout@v4 + - name: Free Disk Space (Ubuntu) + uses: jlumbroso/free-disk-space@main + with: + tool-cache: false + android: true + dotnet: true + haskell: true + large-packages: true + docker-images: true + swap-storage: true - name: Install Nix uses: DeterminateSystems/nix-installer-action@v17 - name: Nix Cache @@ -29,6 +39,16 @@ jobs: steps: - name: checkout uses: actions/checkout@v4 + - name: Free Disk Space (Ubuntu) + uses: jlumbroso/free-disk-space@main + with: + tool-cache: false + android: true + dotnet: true + haskell: true + large-packages: true + docker-images: true + swap-storage: true - name: Pull Nutshell Docker image run: docker pull cashubtc/nutshell:latest - name: Install Nix diff --git a/CHANGELOG.md b/CHANGELOG.md index 985daf14e..f36bbc11d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,9 @@ - cdk-integration-tests: Shared utilities module for common integration test functionality ([thesimplekid]). - cdk-redb: Database migration to increment keyset counters by 1 for existing keysets with counter > 0 ([thesimplekid]). - cdk-sql-common: Database migration to increment keyset counters by 1 for existing keysets with counter > 0 ([thesimplekid]). +- cdk-ldk-node: New Lightning backend implementation using LDK Node for improved Lightning Network functionality ([thesimplekid]). +- cdk-common: Added `start()` and `stop()` methods to `MintPayment` trait for payment processor lifecycle management ([thesimplekid]). +- cdk-mintd: Added LDK Node backend support with comprehensive configuration options ([thesimplekid]). ### Changed - cdk-common: Modified `Database::get_keyset_counter` trait method to return `u32` instead of `Option` for simpler keyset counter handling ([thesimplekid]). @@ -31,6 +34,8 @@ - cdk: Enhanced keyset management with better offline/online operation separation ([thesimplekid]). - cdk: Updated method documentation to clarify storage vs network operations ([thesimplekid]). - cdk: Refactored invoice payment monitoring to use centralized lifecycle management instead of manual task spawning ([thesimplekid]). +- cdk: Enhanced mint startup to initialize payment processors before starting background services ([thesimplekid]). +- cdk: Improved mint shutdown to gracefully stop payment processors alongside background services ([thesimplekid]). - cdk-mintd: Updated to use new mint lifecycle methods for improved service management ([thesimplekid]). - cdk-integration-tests: Updated test utilities to use new mint lifecycle management ([thesimplekid]). - cdk-sqlite: Introduce `cdk-sql-common` crate for shared SQL storage codebase ([crodas]). diff --git a/Cargo.toml b/Cargo.toml index 62c534db9..3049fe220 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -50,6 +50,7 @@ cdk-axum = { path = "./crates/cdk-axum", default-features = false, version = "=0 cdk-cln = { path = "./crates/cdk-cln", version = "=0.11.0" } cdk-lnbits = { path = "./crates/cdk-lnbits", version = "=0.11.0" } cdk-lnd = { path = "./crates/cdk-lnd", version = "=0.11.0" } +cdk-ldk-node = { path = "./crates/cdk-ldk-node", version = "=0.11.0" } cdk-fake-wallet = { path = "./crates/cdk-fake-wallet", version = "=0.11.0" } cdk-payment-processor = { path = "./crates/cdk-payment-processor", default-features = true, version = "=0.11.0" } cdk-mint-rpc = { path = "./crates/cdk-mint-rpc", version = "=0.11.0" } @@ -62,15 +63,18 @@ cdk-mintd = { path = "./crates/cdk-mintd", version = "=0.11.0", default-features clap = { version = "4.5.31", features = ["derive"] } ciborium = { version = "0.2.2", default-features = false, features = ["std"] } cbor-diag = "0.1.12" +config = { version = "0.15.11", features = ["toml"] } futures = { version = "0.3.28", default-features = false, features = ["async-await"] } lightning-invoice = { version = "0.33.0", features = ["serde", "std"] } lightning = { version = "0.1.2", default-features = false, features = ["std"]} +ldk-node = "0.6.2" serde = { version = "1", features = ["derive"] } serde_json = "1" thiserror = { version = "2" } tokio = { version = "1", default-features = false, features = ["rt", "macros", "test-util", "sync"] } tokio-util = { version = "0.7.11", default-features = false } -tower-http = { version = "0.6.1", features = ["compression-full", "decompression-full", "cors", "trace"] } +tower = "0.5.2" +tower-http = { version = "0.6.1", features = ["compression-full", "decompression-full", "cors", "trace", "fs"] } tokio-tungstenite = { version = "0.26.0", default-features = false } tokio-stream = "0.1.15" tracing = { version = "0.1", default-features = false, features = ["attributes", "log"] } diff --git a/README.md b/README.md index e04d41b71..191679cc1 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,7 @@ The project is split up into several crates in the `crates/` directory: * [**cdk-cln**](./crates/cdk-cln/): CLN Lightning backend for mint. * [**cdk-lnd**](./crates/cdk-lnd/): Lnd Lightning backend for mint. * [**cdk-lnbits**](./crates/cdk-lnbits/): [LNbits](https://lnbits.com/) Lightning backend for mint. **Note: Only LNBits v1 API is supported.** + * [**cdk-ldk-node**](./crates/cdk-ldk-node/): LDK Node Lightning backend for mint. * [**cdk-fake-wallet**](./crates/cdk-fake-wallet/): Fake Lightning backend for mint. To be used only for testing, quotes are automatically filled. * [**cdk-mint-rpc**](./crates/cdk-mint-rpc/): Mint management gRPC server and cli. * Binaries: @@ -35,6 +36,22 @@ The project is split up into several crates in the `crates/` directory: For a guide to settings up a development environment see [DEVELOPMENT.md](./DEVELOPMENT.md) +## LDK Node Network Configuration + +For detailed configuration examples for running CDK with LDK Node on different Bitcoin networks (Mutinynet, Testnet, Mainnet), see [LDK Node Network Guide](./crates/cdk-ldk-node/NETWORK_GUIDE.md). + +**Quick Start with Mutinynet (Recommended for Testing):** +```toml +[ln] +ln_backend = "ldk-node" + +[ldk_node] +bitcoin_network = "signet" +esplora_url = "https://mutinynet.com/api" +rgs_url = "https://rgs.mutinynet.com/snapshot/0" +gossip_source_type = "rgs" +``` + ## Implemented [NUTs](https://github.com/cashubtc/nuts/): ### Mandatory diff --git a/crates/cdk-cln/src/lib.rs b/crates/cdk-cln/src/lib.rs index 1605bb57e..66e142bd7 100644 --- a/crates/cdk-cln/src/lib.rs +++ b/crates/cdk-cln/src/lib.rs @@ -647,11 +647,7 @@ impl MintPayment for Cln { .await .map_err(Error::from)? } - PaymentIdentifier::CustomId(_) => { - tracing::error!("Unsupported payment id for CLN"); - return Err(payment::Error::UnknownPaymentState); - } - PaymentIdentifier::Bolt12PaymentHash(_) => { + _ => { tracing::error!("Unsupported payment id for CLN"); return Err(payment::Error::UnknownPaymentState); } diff --git a/crates/cdk-common/src/database/mod.rs b/crates/cdk-common/src/database/mod.rs index ccf13797e..2860feb67 100644 --- a/crates/cdk-common/src/database/mod.rs +++ b/crates/cdk-common/src/database/mod.rs @@ -106,6 +106,9 @@ pub enum Error { /// Amount overflow #[error("Amount overflow")] AmountOverflow, + /// Amount zero + #[error("Amount zero")] + AmountZero, /// DHKE error #[error(transparent)] diff --git a/crates/cdk-common/src/error.rs b/crates/cdk-common/src/error.rs index b1c7e27e0..0009bcc63 100644 --- a/crates/cdk-common/src/error.rs +++ b/crates/cdk-common/src/error.rs @@ -542,6 +542,11 @@ impl From for ErrorResponse { error: Some(err.to_string()), detail: None, }, + Error::UnpaidQuote => ErrorResponse { + code: ErrorCode::QuoteNotPaid, + error: Some(err.to_string()), + detail: None + }, _ => ErrorResponse { code: ErrorCode::Unknown(9999), error: Some(err.to_string()), diff --git a/crates/cdk-common/src/payment.rs b/crates/cdk-common/src/payment.rs index c9c7a9204..afd07ee2e 100644 --- a/crates/cdk-common/src/payment.rs +++ b/crates/cdk-common/src/payment.rs @@ -91,6 +91,8 @@ pub enum PaymentIdentifier { PaymentHash([u8; 32]), /// Bolt12 payment hash Bolt12PaymentHash([u8; 32]), + /// Payment id + PaymentId([u8; 32]), /// Custom Payment ID CustomId(String), } @@ -112,6 +114,11 @@ impl PaymentIdentifier { .map_err(|_| Error::InvalidHash)?, )), "custom" => Ok(Self::CustomId(identifier.to_string())), + "payment_id" => Ok(Self::PaymentId( + hex::decode(identifier)? + .try_into() + .map_err(|_| Error::InvalidHash)?, + )), _ => Err(Error::UnsupportedPaymentOption), } } @@ -123,6 +130,7 @@ impl PaymentIdentifier { Self::OfferId(_) => "offer_id".to_string(), Self::PaymentHash(_) => "payment_hash".to_string(), Self::Bolt12PaymentHash(_) => "bolt12_payment_hash".to_string(), + Self::PaymentId(_) => "payment_id".to_string(), Self::CustomId(_) => "custom".to_string(), } } @@ -135,6 +143,7 @@ impl std::fmt::Display for PaymentIdentifier { Self::OfferId(o) => write!(f, "{o}"), Self::PaymentHash(h) => write!(f, "{}", hex::encode(h)), Self::Bolt12PaymentHash(h) => write!(f, "{}", hex::encode(h)), + Self::PaymentId(h) => write!(f, "{}", hex::encode(h)), Self::CustomId(c) => write!(f, "{c}"), } } @@ -245,6 +254,20 @@ pub trait MintPayment { /// Mint Lightning Error type Err: Into + From; + /// Start the payment processor + /// Called when the mint starts up to initialize the payment processor + async fn start(&self) -> Result<(), Self::Err> { + // Default implementation - do nothing + Ok(()) + } + + /// Stop the payment processor + /// Called when the mint shuts down to gracefully stop the payment processor + async fn stop(&self) -> Result<(), Self::Err> { + // Default implementation - do nothing + Ok(()) + } + /// Base Settings async fn get_settings(&self) -> Result; diff --git a/crates/cdk-integration-tests/Cargo.toml b/crates/cdk-integration-tests/Cargo.toml index febe40caf..7a2576039 100644 --- a/crates/cdk-integration-tests/Cargo.toml +++ b/crates/cdk-integration-tests/Cargo.toml @@ -23,12 +23,13 @@ cashu = { workspace = true, features = ["mint", "wallet"] } cdk = { workspace = true, features = ["mint", "wallet", "auth"] } cdk-cln = { workspace = true } cdk-lnd = { workspace = true } +cdk-ldk-node = { workspace = true } cdk-axum = { workspace = true, features = ["auth"] } cdk-sqlite = { workspace = true } cdk-redb = { workspace = true } cdk-fake-wallet = { workspace = true } cdk-common = { workspace = true, features = ["mint", "wallet", "auth"] } -cdk-mintd = { workspace = true, features = ["cln", "lnd", "fakewallet", "grpc-processor", "auth", "lnbits", "management-rpc", "sqlite", "postgres"] } +cdk-mintd = { workspace = true, features = ["cln", "lnd", "fakewallet", "grpc-processor", "auth", "lnbits", "management-rpc", "sqlite", "postgres", "ldk-node"] } futures = { workspace = true, default-features = false, features = [ "executor", ] } @@ -39,11 +40,13 @@ serde_json.workspace = true # ln-regtest-rs = { path = "../../../../ln-regtest-rs" } ln-regtest-rs = { git = "https://github.com/thesimplekid/ln-regtest-rs", rev = "df81424" } lightning-invoice.workspace = true +ldk-node.workspace = true tracing.workspace = true tracing-subscriber.workspace = true tokio-tungstenite.workspace = true tower-http = { workspace = true, features = ["cors"] } tower-service = "0.3.3" +tokio-util.workspace = true reqwest.workspace = true bitcoin = "0.32.0" clap = { workspace = true, features = ["derive"] } diff --git a/crates/cdk-integration-tests/src/bin/start_fake_auth_mint.rs b/crates/cdk-integration-tests/src/bin/start_fake_auth_mint.rs index b0c228810..0fe84fd8b 100644 --- a/crates/cdk-integration-tests/src/bin/start_fake_auth_mint.rs +++ b/crates/cdk-integration-tests/src/bin/start_fake_auth_mint.rs @@ -20,6 +20,7 @@ use cdk_integration_tests::shared; use cdk_mintd::config::AuthType; use clap::Parser; use tokio::sync::Notify; +use tokio_util::sync::CancellationToken; #[derive(Parser)] #[command(name = "start-fake-auth-mint")] @@ -100,7 +101,8 @@ async fn start_fake_auth_mint( println!("Fake auth mint shutdown signal received"); }; - match cdk_mintd::run_mintd_with_shutdown(&temp_dir, &settings, shutdown_future, None).await + match cdk_mintd::run_mintd_with_shutdown(&temp_dir, &settings, shutdown_future, None, None) + .await { Ok(_) => println!("Fake auth mint exited normally"), Err(e) => eprintln!("Fake auth mint exited with error: {e}"), @@ -132,8 +134,10 @@ async fn main() -> Result<()> { ) .await?; + let cancel_token = Arc::new(CancellationToken::new()); + // Wait for fake auth mint to be ready - if let Err(e) = shared::wait_for_mint_ready(args.port, 100).await { + if let Err(e) = shared::wait_for_mint_ready_with_shutdown(args.port, 100, cancel_token).await { eprintln!("Error waiting for fake auth mint: {e}"); return Err(e); } diff --git a/crates/cdk-integration-tests/src/bin/start_fake_mint.rs b/crates/cdk-integration-tests/src/bin/start_fake_mint.rs index d5bad2fee..89d253012 100644 --- a/crates/cdk-integration-tests/src/bin/start_fake_mint.rs +++ b/crates/cdk-integration-tests/src/bin/start_fake_mint.rs @@ -19,6 +19,7 @@ use cdk_integration_tests::cli::CommonArgs; use cdk_integration_tests::shared; use clap::Parser; use tokio::sync::Notify; +use tokio_util::sync::CancellationToken; #[derive(Parser)] #[command(name = "start-fake-mint")] @@ -99,7 +100,8 @@ async fn start_fake_mint( println!("Fake mint shutdown signal received"); }; - match cdk_mintd::run_mintd_with_shutdown(&temp_dir, &settings, shutdown_future, None).await + match cdk_mintd::run_mintd_with_shutdown(&temp_dir, &settings, shutdown_future, None, None) + .await { Ok(_) => println!("Fake mint exited normally"), Err(e) => eprintln!("Fake mint exited with error: {e}"), @@ -141,8 +143,10 @@ async fn main() -> Result<()> { ) .await?; + let cancel_token = Arc::new(CancellationToken::new()); + // Wait for fake mint to be ready - if let Err(e) = shared::wait_for_mint_ready(args.port, 100).await { + if let Err(e) = shared::wait_for_mint_ready_with_shutdown(args.port, 100, cancel_token).await { eprintln!("Error waiting for fake mint: {e}"); return Err(e); } diff --git a/crates/cdk-integration-tests/src/bin/start_regtest.rs b/crates/cdk-integration-tests/src/bin/start_regtest.rs index cec63d88a..3ceec058a 100644 --- a/crates/cdk-integration-tests/src/bin/start_regtest.rs +++ b/crates/cdk-integration-tests/src/bin/start_regtest.rs @@ -6,9 +6,12 @@ use std::sync::Arc; use std::time::Duration; use anyhow::Result; +use cashu::Amount; use cdk_integration_tests::cli::{init_logging, CommonArgs}; use cdk_integration_tests::init_regtest::start_regtest_end; +use cdk_ldk_node::CdkLdkNode; use clap::Parser; +use ldk_node::lightning::ln::msgs::SocketAddress; use tokio::signal; use tokio::sync::{oneshot, Notify}; use tokio::time::timeout; @@ -42,15 +45,40 @@ async fn main() -> Result<()> { init_logging(args.common.enable_logging, args.common.log_level); let temp_dir = PathBuf::from_str(&args.work_dir)?; - let temp_dir_clone = temp_dir.clone(); let shutdown_regtest = Arc::new(Notify::new()); let shutdown_clone = Arc::clone(&shutdown_regtest); let shutdown_clone_two = Arc::clone(&shutdown_regtest); + let ldk_work_dir = temp_dir.join("ldk_mint"); + let cdk_ldk = CdkLdkNode::new( + bitcoin::Network::Regtest, + cdk_ldk_node::ChainSource::BitcoinRpc(cdk_ldk_node::BitcoinRpcConfig { + host: "127.0.0.1".to_string(), + port: 18443, + user: "testuser".to_string(), + password: "testpass".to_string(), + }), + cdk_ldk_node::GossipSource::P2P, + ldk_work_dir.to_string_lossy().to_string(), + cdk_common::common::FeeReserve { + min_fee_reserve: Amount::ZERO, + percent_fee_reserve: 0.0, + }, + vec![SocketAddress::TcpIpV4 { + addr: [127, 0, 0, 1], + port: 8092, + }], + None, + )?; + + let inner_node = cdk_ldk.node(); + + let temp_dir_clone = temp_dir.clone(); + let (tx, rx) = oneshot::channel(); tokio::spawn(async move { - start_regtest_end(&temp_dir_clone, tx, shutdown_clone) + start_regtest_end(&temp_dir_clone, tx, shutdown_clone, Some(inner_node)) .await .expect("Error starting regtest"); }); diff --git a/crates/cdk-integration-tests/src/bin/start_regtest_mints.rs b/crates/cdk-integration-tests/src/bin/start_regtest_mints.rs index ccef911b0..5f6cca28f 100644 --- a/crates/cdk-integration-tests/src/bin/start_regtest_mints.rs +++ b/crates/cdk-integration-tests/src/bin/start_regtest_mints.rs @@ -16,15 +16,22 @@ use std::path::Path; use std::sync::Arc; use std::time::Duration; -use anyhow::Result; +use anyhow::{bail, Result}; +use bip39::Mnemonic; +use cashu::Amount; use cdk_integration_tests::cli::CommonArgs; use cdk_integration_tests::init_regtest::start_regtest_end; use cdk_integration_tests::shared; +use cdk_ldk_node::CdkLdkNode; +use cdk_mintd::config::LoggingConfig; use clap::Parser; +use ldk_node::lightning::ln::msgs::SocketAddress; +use tokio::runtime::Runtime; +use tokio::signal; use tokio::signal::unix::SignalKind; -use tokio::signal::{self}; use tokio::sync::{oneshot, Notify}; use tokio::time::timeout; +use tokio_util::sync::CancellationToken; #[derive(Parser)] #[command(name = "start-regtest-mints")] @@ -50,6 +57,10 @@ struct Args { /// LND port (default: 8087) #[arg(default_value_t = 8087)] lnd_port: u16, + + /// LDK port (default: 8089) + #[arg(default_value_t = 8089)] + ldk_port: u16, } /// Start regtest CLN mint using the library @@ -96,7 +107,8 @@ async fn start_cln_mint( println!("CLN mint shutdown signal received"); }; - match cdk_mintd::run_mintd_with_shutdown(&temp_dir, &settings, shutdown_future, None).await + match cdk_mintd::run_mintd_with_shutdown(&temp_dir, &settings, shutdown_future, None, None) + .await { Ok(_) => println!("CLN mint exited normally"), Err(e) => eprintln!("CLN mint exited with error: {e}"), @@ -154,8 +166,14 @@ async fn start_lnd_mint( println!("LND mint shutdown signal received"); }; - match cdk_mintd::run_mintd_with_shutdown(&lnd_work_dir, &settings, shutdown_future, None) - .await + match cdk_mintd::run_mintd_with_shutdown( + &lnd_work_dir, + &settings, + shutdown_future, + None, + None, + ) + .await { Ok(_) => println!("LND mint exited normally"), Err(e) => eprintln!("LND mint exited with error: {e}"), @@ -165,141 +183,336 @@ async fn start_lnd_mint( Ok(handle) } -#[tokio::main] -async fn main() -> Result<()> { - let args = Args::parse(); - - // Initialize logging based on CLI arguments - shared::setup_logging(&args.common); - - let temp_dir = shared::init_working_directory(&args.work_dir)?; +/// Start regtest LDK mint using the library +async fn start_ldk_mint( + temp_dir: &Path, + port: u16, + shutdown: Arc, + runtime: Option>, +) -> Result> { + let ldk_work_dir = temp_dir.join("ldk_mint"); - // Write environment variables to a .env file in the temp_dir - let mint_url_1 = format!("http://{}:{}", args.mint_addr, args.cln_port); - let mint_url_2 = format!("http://{}:{}", args.mint_addr, args.lnd_port); - let env_vars: Vec<(&str, &str)> = vec![ - ("CDK_TEST_MINT_URL", &mint_url_1), - ("CDK_TEST_MINT_URL_2", &mint_url_2), - ]; + // Create work directory for LDK mint + fs::create_dir_all(&ldk_work_dir)?; - shared::write_env_file(&temp_dir, &env_vars)?; + // Configure LDK node for regtest + let ldk_config = cdk_mintd::config::LdkNode { + fee_percent: 0.0, + reserve_fee_min: 0.into(), + bitcoin_network: Some("regtest".to_string()), + // Use bitcoind RPC for regtest + chain_source_type: Some("bitcoinrpc".to_string()), + bitcoind_rpc_host: Some("127.0.0.1".to_string()), + bitcoind_rpc_port: Some(18443), + bitcoind_rpc_user: Some("testuser".to_string()), + bitcoind_rpc_password: Some("testpass".to_string()), + esplora_url: None, + storage_dir_path: Some(ldk_work_dir.to_string_lossy().to_string()), + ldk_node_host: Some("127.0.0.1".to_string()), + ldk_node_port: Some(port + 10), // Use a different port for the LDK node P2P connections + gossip_source_type: None, + rgs_url: None, + webserver_host: Some("127.0.0.1".to_string()), + webserver_port: Some(port + 1), // Use next port for web interface + }; - // Start regtest - println!("Starting regtest..."); + // Create settings struct for LDK mint using a new shared function + let settings = create_ldk_settings(port, ldk_config, Mnemonic::generate(12)?.to_string()); - let shutdown_regtest = shared::create_shutdown_handler(); - let shutdown_clone = shutdown_regtest.clone(); - let (tx, rx) = oneshot::channel(); + println!("Starting LDK mintd on port {port}"); - let shutdown_clone_one = Arc::clone(&shutdown_clone); + let ldk_work_dir = ldk_work_dir.clone(); + let shutdown_clone = shutdown.clone(); - let temp_dir_clone = temp_dir.clone(); - tokio::spawn(async move { - start_regtest_end(&temp_dir_clone, tx, shutdown_clone_one) - .await - .expect("Error starting regtest"); - }); + // Run the mint in a separate task + let handle = tokio::spawn(async move { + // Create a future that resolves when the shutdown signal is received + let shutdown_future = async move { + shutdown_clone.notified().await; + println!("LDK mint shutdown signal received"); + }; - match timeout(Duration::from_secs(300), rx).await { - Ok(_) => { - tracing::info!("Regtest set up"); - } - Err(_) => { - tracing::error!("regtest setup timed out after 5 minutes"); - anyhow::bail!("Could not set up regtest"); + match cdk_mintd::run_mintd_with_shutdown( + &ldk_work_dir, + &settings, + shutdown_future, + None, + runtime, + ) + .await + { + Ok(_) => println!("LDK mint exited normally"), + Err(e) => eprintln!("LDK mint exited with error: {e}"), } - } - - // Start CLN mint - let cln_handle = start_cln_mint(&temp_dir, args.cln_port, shutdown_clone.clone()).await?; - - // Wait for CLN mint to be ready - if let Err(e) = shared::wait_for_mint_ready(args.cln_port, 100).await { - eprintln!("Error waiting for CLN mint: {e}"); - return Err(e); - } + }); - // Start LND mint - let lnd_handle = start_lnd_mint(&temp_dir, args.lnd_port, shutdown_clone.clone()).await?; + Ok(handle) +} - // Wait for LND mint to be ready - if let Err(e) = shared::wait_for_mint_ready(args.lnd_port, 100).await { - eprintln!("Error waiting for LND mint: {e}"); - return Err(e); +/// Create settings for an LDK mint +fn create_ldk_settings( + port: u16, + ldk_config: cdk_mintd::config::LdkNode, + mnemonic: String, +) -> cdk_mintd::config::Settings { + cdk_mintd::config::Settings { + info: cdk_mintd::config::Info { + url: format!("http://127.0.0.1:{port}"), + listen_host: "127.0.0.1".to_string(), + listen_port: port, + mnemonic: Some(mnemonic), + signatory_url: None, + signatory_certs: None, + input_fee_ppk: None, + http_cache: cdk_axum::cache::Config::default(), + enable_swagger_ui: None, + logging: LoggingConfig::default(), + }, + mint_info: cdk_mintd::config::MintInfo::default(), + ln: cdk_mintd::config::Ln { + ln_backend: cdk_mintd::config::LnBackend::LdkNode, + invoice_description: None, + min_mint: 1.into(), + max_mint: 500_000.into(), + min_melt: 1.into(), + max_melt: 500_000.into(), + }, + cln: None, + lnbits: None, + lnd: None, + ldk_node: Some(ldk_config), + fake_wallet: None, + grpc_processor: None, + database: cdk_mintd::config::Database::default(), + mint_management_rpc: None, + auth: None, } +} - println!("All regtest mints started successfully!"); - println!("CLN mint: http://{}:{}", args.mint_addr, args.cln_port); - println!("LND mint: http://{}:{}", args.mint_addr, args.lnd_port); - shared::display_mint_info(args.cln_port, &temp_dir, &args.database_type); // Using CLN port for display - println!(); - println!("Environment variables set:"); - println!( - " CDK_TEST_MINT_URL=http://{}:{}", - args.mint_addr, args.cln_port - ); - println!( - " CDK_TEST_MINT_URL_2=http://{}:{}", - args.mint_addr, args.lnd_port - ); - println!(" CDK_ITESTS_DIR={}", temp_dir.display()); - println!(); - println!("You can now run integration tests with:"); - println!(" cargo test -p cdk-integration-tests --test regtest"); - println!(" cargo test -p cdk-integration-tests --test happy_path_mint_wallet"); - println!(" etc."); - println!(); - - println!("Press Ctrl+C to stop the mints..."); - - // Create a future to wait for either Ctrl+C signal or unexpected mint termination - let shutdown_future = async { - // Wait for either SIGINT (Ctrl+C) or SIGTERM - let mut sigterm = signal::unix::signal(SignalKind::terminate()) - .expect("Failed to create SIGTERM signal handler"); - tokio::select! { - _ = signal::ctrl_c() => { - tracing::info!("Received SIGINT (Ctrl+C), shutting down mints..."); +fn main() -> Result<()> { + let rt = Arc::new(Runtime::new()?); + + let rt_clone = Arc::clone(&rt); + + rt.block_on(async { + let args = Args::parse(); + + // Initialize logging based on CLI arguments + shared::setup_logging(&args.common); + + let temp_dir = shared::init_working_directory(&args.work_dir)?; + + // Write environment variables to a .env file in the temp_dir + let mint_url_1 = format!("http://{}:{}", args.mint_addr, args.cln_port); + let mint_url_2 = format!("http://{}:{}", args.mint_addr, args.lnd_port); + let mint_url_3 = format!("http://{}:{}", args.mint_addr, args.ldk_port); + let env_vars: Vec<(&str, &str)> = vec![ + ("CDK_TEST_MINT_URL", &mint_url_1), + ("CDK_TEST_MINT_URL_2", &mint_url_2), + ("CDK_TEST_MINT_URL_3", &mint_url_3), + ]; + + shared::write_env_file(&temp_dir, &env_vars)?; + + // Start regtest + println!("Starting regtest..."); + + let shutdown_regtest = shared::create_shutdown_handler(); + let shutdown_clone = shutdown_regtest.clone(); + let (tx, rx) = oneshot::channel(); + + let shutdown_clone_one = Arc::clone(&shutdown_clone); + + let ldk_work_dir = temp_dir.join("ldk_mint"); + let cdk_ldk = CdkLdkNode::new( + bitcoin::Network::Regtest, + cdk_ldk_node::ChainSource::BitcoinRpc(cdk_ldk_node::BitcoinRpcConfig { + host: "127.0.0.1".to_string(), + port: 18443, + user: "testuser".to_string(), + password: "testpass".to_string(), + }), + cdk_ldk_node::GossipSource::P2P, + ldk_work_dir.to_string_lossy().to_string(), + cdk_common::common::FeeReserve { + min_fee_reserve: Amount::ZERO, + percent_fee_reserve: 0.0, + }, + vec![SocketAddress::TcpIpV4 { + addr: [127, 0, 0, 1], + port: 8092, + }], + Some(Arc::clone(&rt_clone)), + )?; + + let inner_node = cdk_ldk.node(); + + let temp_dir_clone = temp_dir.clone(); + let shutdown_clone_two = Arc::clone(&shutdown_clone); + tokio::spawn(async move { + start_regtest_end(&temp_dir_clone, tx, shutdown_clone_two, Some(inner_node)) + .await + .expect("Error starting regtest"); + }); + + match timeout(Duration::from_secs(300), rx).await { + Ok(k) => { + k?; + tracing::info!("Regtest set up"); } - _ = sigterm.recv() => { - tracing::info!("Received SIGTERM, shutting down mints..."); + Err(_) => { + tracing::error!("regtest setup timed out after 5 minutes"); + anyhow::bail!("Could not set up regtest"); } } - println!("\nShutdown signal received, shutting down mints..."); - shutdown_clone.notify_waiters(); - }; - // Monitor mint handles for unexpected termination - let monitor_mints = async { - loop { - if cln_handle.is_finished() { - println!("CLN mint finished unexpectedly"); - return; + println!("lnd port: {}", args.ldk_port); + + // Start LND mint + let lnd_handle = start_lnd_mint(&temp_dir, args.lnd_port, shutdown_clone.clone()).await?; + + // Start LDK mint + let ldk_handle = start_ldk_mint( + &temp_dir, + args.ldk_port, + shutdown_clone.clone(), + Some(rt_clone), + ) + .await?; + + // Start CLN mint + let cln_handle = start_cln_mint(&temp_dir, args.cln_port, shutdown_clone.clone()).await?; + + let cancel_token = Arc::new(CancellationToken::new()); + + // Set up Ctrl+C handler before waiting for mints to be ready + let ctrl_c_token = Arc::clone(&cancel_token); + + let s_u = shutdown_clone.clone(); + tokio::spawn(async move { + signal::ctrl_c() + .await + .expect("failed to install CTRL+C handler"); + tracing::info!("Shutdown signal received during mint setup"); + println!("\nReceived Ctrl+C, shutting down..."); + ctrl_c_token.cancel(); + s_u.notify_waiters(); + }); + + match tokio::try_join!( + shared::wait_for_mint_ready_with_shutdown( + args.lnd_port, + 100, + Arc::clone(&cancel_token) + ), + shared::wait_for_mint_ready_with_shutdown( + args.ldk_port, + 100, + Arc::clone(&cancel_token) + ), + shared::wait_for_mint_ready_with_shutdown( + args.cln_port, + 100, + Arc::clone(&cancel_token) + ), + ) { + Ok(_) => println!("All mints are ready!"), + Err(e) => { + if cancel_token.is_cancelled() { + bail!("Startup canceled by user"); + } + eprintln!("Error waiting for mints to be ready: {e}"); + return Err(e); } - if lnd_handle.is_finished() { - println!("LND mint finished unexpectedly"); - return; - } - tokio::time::sleep(Duration::from_millis(100)).await; } - }; - // Wait for either shutdown signal or mint termination - tokio::select! { - _ = shutdown_future => { - println!("Shutdown signal received, waiting for mints to stop..."); + if cancel_token.is_cancelled() { + bail!("Token canceled"); } - _ = monitor_mints => { - println!("One or more mints terminated unexpectedly"); + + println!("All regtest mints started successfully!"); + println!("CLN mint: http://{}:{}", args.mint_addr, args.cln_port); + println!("LND mint: http://{}:{}", args.mint_addr, args.lnd_port); + println!("LDK mint: http://{}:{}", args.mint_addr, args.ldk_port); + shared::display_mint_info(args.cln_port, &temp_dir, &args.database_type); // Using CLN port for display + println!(); + println!("Environment variables set:"); + println!( + " CDK_TEST_MINT_URL=http://{}:{}", + args.mint_addr, args.cln_port + ); + println!( + " CDK_TEST_MINT_URL_2=http://{}:{}", + args.mint_addr, args.lnd_port + ); + println!( + " CDK_TEST_MINT_URL_3=http://{}:{}", + args.mint_addr, args.ldk_port + ); + println!(" CDK_ITESTS_DIR={}", temp_dir.display()); + println!(); + println!("You can now run integration tests with:"); + println!(" cargo test -p cdk-integration-tests --test regtest"); + println!(" cargo test -p cdk-integration-tests --test happy_path_mint_wallet"); + println!(" etc."); + println!(); + + println!("Press Ctrl+C to stop the mints..."); + + // Create a future to wait for either Ctrl+C signal or unexpected mint termination + let shutdown_future = async { + // Wait for either SIGINT (Ctrl+C) or SIGTERM + let mut sigterm = signal::unix::signal(SignalKind::terminate()) + .expect("Failed to create SIGTERM signal handler"); + tokio::select! { + _ = signal::ctrl_c() => { + tracing::info!("Received SIGINT (Ctrl+C), shutting down mints..."); + } + _ = sigterm.recv() => { + tracing::info!("Received SIGTERM, shutting down mints..."); + } + } + println!("\nShutdown signal received, shutting down mints..."); + shutdown_clone.notify_waiters(); + }; + + // Monitor mint handles for unexpected termination + let monitor_mints = async { + loop { + if cln_handle.is_finished() { + println!("CLN mint finished unexpectedly"); + return; + } + if lnd_handle.is_finished() { + println!("LND mint finished unexpectedly"); + return; + } + if ldk_handle.is_finished() { + println!("LDK mint finished unexpectedly"); + return; + } + tokio::time::sleep(Duration::from_millis(100)).await; + } + }; + + // Wait for either shutdown signal or mint termination + tokio::select! { + _ = shutdown_clone_one.notified() => { + println!("Shutdown signal received, waiting for mints to stop..."); + } + _ = monitor_mints => { + println!("One or more mints terminated unexpectedly"); + } + _ = shutdown_future => () } - } - // Wait for mints to finish gracefully - if let Err(e) = tokio::try_join!(cln_handle, lnd_handle) { - eprintln!("Error waiting for mints to shut down: {e}"); - } + // Wait for mints to finish gracefully + if let Err(e) = tokio::try_join!(ldk_handle, cln_handle, lnd_handle) { + eprintln!("Error waiting for mints to shut down: {e}"); + } - println!("All services shut down successfully"); + println!("All services shut down successfully"); - Ok(()) + Ok(()) + }) } diff --git a/crates/cdk-integration-tests/src/cli.rs b/crates/cdk-integration-tests/src/cli.rs index 22c5fdcd7..0c2ea30ea 100644 --- a/crates/cdk-integration-tests/src/cli.rs +++ b/crates/cdk-integration-tests/src/cli.rs @@ -24,7 +24,6 @@ pub fn init_logging(enable_logging: bool, log_level: tracing::Level) { let default_filter = log_level.to_string(); // Common filters to reduce noise - let sqlx_filter = "sqlx=warn"; let hyper_filter = "hyper=warn"; let h2_filter = "h2=warn"; let rustls_filter = "rustls=warn"; @@ -32,7 +31,7 @@ pub fn init_logging(enable_logging: bool, log_level: tracing::Level) { let tower_filter = "tower_http=warn"; let env_filter = EnvFilter::new(format!( - "{default_filter},{sqlx_filter},{hyper_filter},{h2_filter},{rustls_filter},{reqwest_filter},{tower_filter}" + "{default_filter},{hyper_filter},{h2_filter},{rustls_filter},{reqwest_filter},{tower_filter}" )); // Ok if successful, Err if already initialized diff --git a/crates/cdk-integration-tests/src/init_regtest.rs b/crates/cdk-integration-tests/src/init_regtest.rs index 538bd869a..faa61b58c 100644 --- a/crates/cdk-integration-tests/src/init_regtest.rs +++ b/crates/cdk-integration-tests/src/init_regtest.rs @@ -1,4 +1,5 @@ use std::env; +use std::net::Ipv4Addr; use std::path::{Path, PathBuf}; use std::sync::Arc; @@ -6,6 +7,8 @@ use anyhow::Result; use cdk::types::FeeReserve; use cdk_cln::Cln as CdkCln; use cdk_lnd::Lnd as CdkLnd; +use ldk_node::lightning::ln::msgs::SocketAddress; +use ldk_node::Node; use ln_regtest_rs::bitcoin_client::BitcoinClient; use ln_regtest_rs::bitcoind::Bitcoind; use ln_regtest_rs::cln::Clnd; @@ -145,6 +148,9 @@ pub async fn init_lnd( pub fn generate_block(bitcoin_client: &BitcoinClient) -> Result<()> { let mine_to_address = bitcoin_client.get_new_address()?; + let blocks = 10; + tracing::info!("Mining {blocks} blocks to {mine_to_address}"); + bitcoin_client.generate_blocks(&mine_to_address, 10)?; Ok(()) @@ -225,6 +231,7 @@ pub async fn start_regtest_end( work_dir: &Path, sender: Sender<()>, notify: Arc, + ldk_node: Option>, ) -> anyhow::Result<()> { let mut bitcoind = init_bitcoind(work_dir); bitcoind.start_bitcoind()?; @@ -285,6 +292,13 @@ pub async fn start_regtest_end( lnd_client.wait_chain_sync().await.unwrap(); + if let Some(node) = ldk_node.as_ref() { + tracing::info!("Starting ldk node"); + node.start()?; + let addr = node.onchain_payment().new_address().unwrap(); + bitcoin_client.send_to_address(&addr.to_string(), 5_000_000)?; + } + fund_ln(&bitcoin_client, &lnd_client).await.unwrap(); // create second lnd node @@ -336,12 +350,108 @@ pub async fn start_regtest_end( tracing::info!("Opened channel between cln and lnd two"); generate_block(&bitcoin_client)?; - cln_client.wait_channels_active().await?; - cln_two_client.wait_channels_active().await?; - lnd_client.wait_channels_active().await?; - lnd_two_client.wait_channels_active().await?; + if let Some(node) = ldk_node { + let pubkey = node.node_id(); + let listen_addr = node.listening_addresses(); + let listen_addr = listen_addr.as_ref().unwrap().first().unwrap(); + + let (listen_addr, port) = match listen_addr { + SocketAddress::TcpIpV4 { addr, port } => (Ipv4Addr::from(*addr).to_string(), port), + _ => panic!(), + }; + + tracing::info!("Opening channel from cln to ldk"); + + cln_client + .connect_peer(pubkey.to_string(), listen_addr.clone(), *port) + .await?; + + cln_client + .open_channel(1_500_000, &pubkey.to_string(), Some(750_000)) + .await + .unwrap(); + + generate_block(&bitcoin_client)?; + + let cln_two_info = cln_two_client.get_connect_info().await?; + + cln_client + .connect_peer(cln_two_info.pubkey, listen_addr.clone(), cln_two_info.port) + .await?; + + tracing::info!("Opening channel from lnd to ldk"); + + let cln_info = cln_client.get_connect_info().await?; + + node.connect( + cln_info.pubkey.parse()?, + SocketAddress::TcpIpV4 { + addr: cln_info + .address + .split('.') + .map(|part| part.parse()) + .collect::, _>>()? + .try_into() + .unwrap(), + port: cln_info.port, + }, + true, + )?; + + let lnd_info = lnd_client.get_connect_info().await?; + + node.connect( + lnd_info.pubkey.parse()?, + SocketAddress::TcpIpV4 { + addr: [127, 0, 0, 1], + port: lnd_info.port, + }, + true, + )?; + + // lnd_client + // .open_channel(1_500_000, &pubkey.to_string(), Some(750_000)) + // .await + // .unwrap(); + + generate_block(&bitcoin_client)?; + lnd_client.wait_chain_sync().await?; + + node.open_announced_channel( + lnd_info.pubkey.parse()?, + SocketAddress::TcpIpV4 { + addr: [127, 0, 0, 1], + port: lnd_info.port, + }, + 1_000_000, + Some(500_000_000), + None, + )?; + + generate_block(&bitcoin_client)?; + + tracing::info!("Ldk channels opened"); + + node.sync_wallets()?; + + tracing::info!("Ldk wallet synced"); + + cln_client.wait_channels_active().await?; + + lnd_client.wait_channels_active().await?; + + node.stop()?; + } else { + cln_client.wait_channels_active().await?; + + lnd_client.wait_channels_active().await?; + + generate_block(&bitcoin_client)?; + } } + tracing::info!("Regtest channels active"); + // Send notification that regtest set up is complete sender.send(()).expect("Could not send oneshot"); diff --git a/crates/cdk-integration-tests/src/lib.rs b/crates/cdk-integration-tests/src/lib.rs index 2f4dc70d8..675e94021 100644 --- a/crates/cdk-integration-tests/src/lib.rs +++ b/crates/cdk-integration-tests/src/lib.rs @@ -17,7 +17,7 @@ //! - Proof state management utilities use std::env; -use std::path::Path; +use std::path::{Path, PathBuf}; use std::sync::Arc; use anyhow::{anyhow, bail, Result}; @@ -27,9 +27,11 @@ use cdk::nuts::State; use cdk::Wallet; use cdk_fake_wallet::create_fake_invoice; use init_regtest::{get_lnd_dir, LND_RPC_ADDR}; -use ln_regtest_rs::ln_client::{LightningClient, LndClient}; +use ln_regtest_rs::ln_client::{ClnClient, LightningClient, LndClient}; use tokio::time::Duration; +use crate::init_regtest::get_cln_dir; + pub mod cli; pub mod init_auth_mint; pub mod init_pure_tests; @@ -118,11 +120,18 @@ pub async fn init_lnd_client(work_dir: &Path) -> LndClient { /// /// This is useful for tests that need to pay invoices in regtest mode but /// should be skipped in other environments. -pub async fn pay_if_regtest(work_dir: &Path, invoice: &Bolt11Invoice) -> Result<()> { +pub async fn pay_if_regtest(_work_dir: &Path, invoice: &Bolt11Invoice) -> Result<()> { // Check if the invoice is for the regtest network if invoice.network() == bitcoin::Network::Regtest { - let lnd_client = init_lnd_client(work_dir).await; - lnd_client.pay_invoice(invoice.to_string()).await?; + let client = get_test_client().await; + let mut tries = 0; + while let Err(err) = client.pay_invoice(invoice.to_string()).await { + println!("Could not pay invoice.retrying {err}"); + tries += 1; + if tries > 10 { + bail!("Could not pay invoice"); + } + } Ok(()) } else { // Not a regtest invoice, just return Ok @@ -149,11 +158,10 @@ pub fn is_regtest_env() -> bool { /// /// Uses the is_regtest_env() function to determine whether to /// create a real regtest invoice or a fake one for testing. -pub async fn create_invoice_for_env(work_dir: &Path, amount_sat: Option) -> Result { +pub async fn create_invoice_for_env(amount_sat: Option) -> Result { if is_regtest_env() { - // In regtest mode, create a real invoice - let lnd_client = init_lnd_client(work_dir).await; - lnd_client + let client = get_test_client().await; + client .create_invoice(amount_sat) .await .map_err(|e| anyhow!("Failed to create regtest invoice: {}", e)) @@ -166,3 +174,80 @@ pub async fn create_invoice_for_env(work_dir: &Path, amount_sat: Option) -> Ok(fake_invoice.to_string()) } } + +// This is the ln wallet we use to send/receive ln payements as the wallet +async fn _get_lnd_client() -> LndClient { + let temp_dir = get_work_dir(); + + // The LND mint uses the second LND node (LND_TWO_RPC_ADDR = localhost:10010) + let lnd_dir = get_lnd_dir(&temp_dir, "one"); + let cert_file = lnd_dir.join("tls.cert"); + let macaroon_file = lnd_dir.join("data/chain/bitcoin/regtest/admin.macaroon"); + + println!("Looking for LND cert file: {cert_file:?}"); + println!("Looking for LND macaroon file: {macaroon_file:?}"); + println!("Connecting to LND at: https://{LND_RPC_ADDR}"); + + // Connect to LND + LndClient::new( + format!("https://{LND_RPC_ADDR}"), + cert_file.clone(), + macaroon_file.clone(), + ) + .await + .expect("Could not connect to lnd rpc") +} + +/// Returns a Lightning client based on the CDK_TEST_LIGHTNING_CLIENT environment variable. +/// +/// Reads the CDK_TEST_LIGHTNING_CLIENT environment variable: +/// - "cln" or "CLN": returns a CLN client +/// - Anything else (or unset): returns an LND client (default) +pub async fn get_test_client() -> Box { + match env::var("CDK_TEST_LIGHTNING_CLIENT") { + Ok(val) => { + let val = val.to_lowercase(); + match val.as_str() { + "cln" => Box::new(create_cln_client_with_retry().await), + _ => Box::new(_get_lnd_client().await), + } + } + Err(_) => Box::new(_get_lnd_client().await), // Default to LND + } +} + +fn get_work_dir() -> PathBuf { + match env::var("CDK_ITESTS_DIR") { + Ok(dir) => { + let path = PathBuf::from(dir); + println!("Using temp directory from CDK_ITESTS_DIR: {path:?}"); + path + } + Err(_) => { + panic!("Unknown temp dir"); + } + } +} + +// Helper function to create CLN client with retries +async fn create_cln_client_with_retry() -> ClnClient { + let mut retries = 0; + let max_retries = 10; + + let cln_dir = get_cln_dir(&get_work_dir(), "one"); + loop { + match ClnClient::new(cln_dir.clone(), None).await { + Ok(client) => return client, + Err(e) => { + retries += 1; + if retries >= max_retries { + panic!("Could not connect to CLN client after {max_retries} retries: {e}"); + } + println!( + "Failed to connect to CLN (attempt {retries}/{max_retries}): {e}. Retrying in 7 seconds..." + ); + tokio::time::sleep(tokio::time::Duration::from_secs(7)).await; + } + } + } +} diff --git a/crates/cdk-integration-tests/src/shared.rs b/crates/cdk-integration-tests/src/shared.rs index 900e36a0e..85efef281 100644 --- a/crates/cdk-integration-tests/src/shared.rs +++ b/crates/cdk-integration-tests/src/shared.rs @@ -14,6 +14,7 @@ use cdk_axum::cache; use cdk_mintd::config::{Database, DatabaseEngine}; use tokio::signal; use tokio::sync::Notify; +use tokio_util::sync::CancellationToken; use crate::cli::{init_logging, CommonArgs}; @@ -26,8 +27,12 @@ const DEFAULT_MIN_MELT: u64 = 1; /// Default maximum melt amount for test mints const DEFAULT_MAX_MELT: u64 = 500_000; -/// Wait for mint to be ready by checking its info endpoint -pub async fn wait_for_mint_ready(port: u16, timeout_secs: u64) -> Result<()> { +/// Wait for mint to be ready by checking its info endpoint, with optional shutdown signal +pub async fn wait_for_mint_ready_with_shutdown( + port: u16, + timeout_secs: u64, + shutdown_notify: Arc, +) -> Result<()> { let url = format!("http://127.0.0.1:{port}/v1/info"); let start_time = std::time::Instant::now(); @@ -39,26 +44,43 @@ pub async fn wait_for_mint_ready(port: u16, timeout_secs: u64) -> Result<()> { return Err(anyhow::anyhow!("Timeout waiting for mint on port {}", port)); } - // Try to make a request to the mint info endpoint - match reqwest::get(&url).await { - Ok(response) => { - if response.status().is_success() { - println!("Mint on port {port} is ready"); - return Ok(()); - } else { - println!( - "Mint on port {} returned status: {}", - port, - response.status() - ); + if shutdown_notify.is_cancelled() { + return Err(anyhow::anyhow!("Canceled waiting for {}", port)); + } + + tokio::select! { + // Try to make a request to the mint info endpoint + result = reqwest::get(&url) => { + match result { + Ok(response) => { + if response.status().is_success() { + println!("Mint on port {port} is ready"); + return Ok(()); + } else { + println!( + "Mint on port {} returned status: {}", + port, + response.status() + ); + } + } + Err(e) => { + println!("Error connecting to mint on port {port}: {e}"); + } } } - Err(e) => { - println!("Error connecting to mint on port {port}: {e}"); + + // Check for shutdown signal + _ = shutdown_notify.cancelled() => { + return Err(anyhow::anyhow!( + "Shutdown requested while waiting for mint on port {}", + port + )); } - } - tokio::time::sleep(Duration::from_secs(2)).await; + + + } } } @@ -187,6 +209,7 @@ pub fn create_fake_wallet_settings( cln: None, lnbits: None, lnd: None, + ldk_node: None, fake_wallet: fake_wallet_config, grpc_processor: None, database: Database { @@ -234,6 +257,7 @@ pub fn create_cln_settings( cln: Some(cln_config), lnbits: None, lnd: None, + ldk_node: None, fake_wallet: None, grpc_processor: None, database: cdk_mintd::config::Database::default(), @@ -276,6 +300,7 @@ pub fn create_lnd_settings( }, cln: None, lnbits: None, + ldk_node: None, lnd: Some(lnd_config), fake_wallet: None, grpc_processor: None, diff --git a/crates/cdk-integration-tests/tests/bolt12.rs b/crates/cdk-integration-tests/tests/bolt12.rs index 8a900a800..68e340270 100644 --- a/crates/cdk-integration-tests/tests/bolt12.rs +++ b/crates/cdk-integration-tests/tests/bolt12.rs @@ -385,3 +385,66 @@ async fn test_regtest_bolt12_mint_extra() -> Result<()> { Ok(()) } + +#[tokio::test(flavor = "multi_thread", worker_threads = 1)] +async fn test_attempt_to_mint_unpaid() { + let wallet = Wallet::new( + &get_mint_url_from_env(), + CurrencyUnit::Sat, + Arc::new(memory::empty().await.unwrap()), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), + None, + ) + .expect("failed to create new wallet"); + + let mint_amount = Amount::from(100); + + let mint_quote = wallet + .mint_bolt12_quote(Some(mint_amount), None) + .await + .unwrap(); + + assert_eq!(mint_quote.amount, Some(mint_amount)); + + let proofs = wallet + .mint_bolt12(&mint_quote.id, None, SplitTarget::default(), None) + .await; + + match proofs { + Err(err) => { + if !matches!(err, cdk::Error::UnpaidQuote) { + panic!("Wrong error quote should be unpaid: {}", err); + } + } + Ok(_) => { + panic!("Minting should not be allowed"); + } + } + + let mint_quote = wallet + .mint_bolt12_quote(Some(mint_amount), None) + .await + .unwrap(); + + let state = wallet + .mint_bolt12_quote_state(&mint_quote.id) + .await + .unwrap(); + + assert!(state.amount_paid == Amount::ZERO); + + let proofs = wallet + .mint_bolt12(&mint_quote.id, None, SplitTarget::default(), None) + .await; + + match proofs { + Err(err) => { + if !matches!(err, cdk::Error::UnpaidQuote) { + panic!("Wrong error quote should be unpaid: {}", err); + } + } + Ok(_) => { + panic!("Minting should not be allowed"); + } + } +} diff --git a/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs b/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs index 630460927..1372c09db 100644 --- a/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs +++ b/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs @@ -123,9 +123,7 @@ async fn test_happy_mint_melt_round_trip() { assert!(mint_amount == 100.into()); - let invoice = create_invoice_for_env(&get_test_temp_dir(), Some(50)) - .await - .unwrap(); + let invoice = create_invoice_for_env(Some(50)).await.unwrap(); let melt = wallet.melt_quote(invoice, None).await.unwrap(); @@ -371,9 +369,7 @@ async fn test_fake_melt_change_in_quote() { .await .unwrap(); - let invoice = create_invoice_for_env(&get_test_temp_dir(), Some(9)) - .await - .unwrap(); + let invoice = create_invoice_for_env(Some(9)).await.unwrap(); let proofs = wallet.get_unspent_proofs().await.unwrap(); @@ -447,9 +443,7 @@ async fn test_pay_invoice_twice() { assert_eq!(mint_amount, 100.into()); - let invoice = create_invoice_for_env(&get_test_temp_dir(), Some(25)) - .await - .unwrap(); + let invoice = create_invoice_for_env(Some(25)).await.unwrap(); let melt_quote = wallet.melt_quote(invoice.clone(), None).await.unwrap(); diff --git a/crates/cdk-integration-tests/tests/ldk_node.rs b/crates/cdk-integration-tests/tests/ldk_node.rs new file mode 100644 index 000000000..51f5327c3 --- /dev/null +++ b/crates/cdk-integration-tests/tests/ldk_node.rs @@ -0,0 +1,63 @@ +use anyhow::Result; +use cdk_integration_tests::get_mint_url_from_env; + +#[tokio::test] +async fn test_ldk_node_mint_info() -> Result<()> { + // This test just verifies that the LDK-Node mint is running and responding + let mint_url = get_mint_url_from_env(); + + // Create an HTTP client + let client = reqwest::Client::new(); + + // Make a request to the info endpoint + let response = client.get(&format!("{}/v1/info", mint_url)).send().await?; + + // Check that we got a successful response + assert_eq!(response.status(), 200); + + // Try to parse the response as JSON + let info: serde_json::Value = response.json().await?; + + // Verify that we got some basic fields + assert!(info.get("name").is_some()); + assert!(info.get("version").is_some()); + assert!(info.get("description").is_some()); + + println!("LDK-Node mint info: {:?}", info); + + Ok(()) +} + +#[tokio::test] +async fn test_ldk_node_mint_quote() -> Result<()> { + // This test verifies that we can create a mint quote with the LDK-Node mint + let mint_url = get_mint_url_from_env(); + + // Create an HTTP client + let client = reqwest::Client::new(); + + // Create a mint quote request + let quote_request = serde_json::json!({ + "amount": 1000, + "unit": "sat" + }); + + // Make a request to create a mint quote + let response = client + .post(&format!("{}/v1/mint/quote/bolt11", mint_url)) + .json("e_request) + .send() + .await?; + + // Print the response for debugging + let status = response.status(); + let text = response.text().await?; + println!("Mint quote response status: {}", status); + println!("Mint quote response body: {}", text); + + // For now, we'll just check that we get a response (even if it's an error) + // In a real test, we'd want to verify the quote was created correctly + assert!(status.is_success() || status.as_u16() < 500); + + Ok(()) +} diff --git a/crates/cdk-integration-tests/tests/regtest.rs b/crates/cdk-integration-tests/tests/regtest.rs index fad096559..0061423cf 100644 --- a/crates/cdk-integration-tests/tests/regtest.rs +++ b/crates/cdk-integration-tests/tests/regtest.rs @@ -13,8 +13,6 @@ //! - Requires properly configured LND nodes with TLS certificates and macaroons //! - Uses real Bitcoin transactions in regtest mode -use std::env; -use std::path::PathBuf; use std::sync::Arc; use std::time::Duration; @@ -26,49 +24,16 @@ use cdk::nuts::{ NotificationPayload, PreMintSecrets, }; use cdk::wallet::{HttpClient, MintConnector, Wallet, WalletSubscription}; -use cdk_integration_tests::init_regtest::{get_lnd_dir, LND_RPC_ADDR}; -use cdk_integration_tests::{get_mint_url_from_env, get_second_mint_url_from_env}; +use cdk_integration_tests::{get_mint_url_from_env, get_second_mint_url_from_env, get_test_client}; use cdk_sqlite::wallet::{self, memory}; use futures::join; -use ln_regtest_rs::ln_client::{LightningClient, LndClient}; use tokio::time::timeout; -// This is the ln wallet we use to send/receive ln payements as the wallet -async fn init_lnd_client() -> LndClient { - // Try to get the temp directory from environment variable first (from .env file) - let temp_dir = match env::var("CDK_ITESTS_DIR") { - Ok(dir) => { - let path = PathBuf::from(dir); - println!("Using temp directory from CDK_ITESTS_DIR: {:?}", path); - path - } - Err(_) => { - panic!("Unknown temp dir"); - } - }; - - // The LND mint uses the second LND node (LND_TWO_RPC_ADDR = localhost:10010) - let lnd_dir = get_lnd_dir(&temp_dir, "one"); - let cert_file = lnd_dir.join("tls.cert"); - let macaroon_file = lnd_dir.join("data/chain/bitcoin/regtest/admin.macaroon"); - - println!("Looking for LND cert file: {:?}", cert_file); - println!("Looking for LND macaroon file: {:?}", macaroon_file); - println!("Connecting to LND at: https://{}", LND_RPC_ADDR); - - // Connect to LND - LndClient::new( - format!("https://{}", LND_RPC_ADDR), - cert_file.clone(), - macaroon_file.clone(), - ) - .await - .expect("Could not connect to lnd rpc") -} +const LDK_URL: &str = "http://127.0.0.1:8089"; #[tokio::test(flavor = "multi_thread", worker_threads = 1)] async fn test_internal_payment() { - let lnd_client = init_lnd_client().await; + let ln_client = get_test_client().await; let wallet = Wallet::new( &get_mint_url_from_env(), @@ -81,7 +46,7 @@ async fn test_internal_payment() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - lnd_client + ln_client .pay_invoice(mint_quote.request.clone()) .await .expect("failed to pay invoice"); @@ -208,8 +173,8 @@ async fn test_websocket_connection() { _ => panic!("Unexpected notification type"), } - let lnd_client = init_lnd_client().await; - lnd_client + let ln_client = get_test_client().await; + ln_client .pay_invoice(mint_quote.request) .await .expect("failed to pay invoice"); @@ -231,7 +196,11 @@ async fn test_websocket_connection() { #[tokio::test(flavor = "multi_thread", worker_threads = 1)] async fn test_multimint_melt() { - let lnd_client = init_lnd_client().await; + if get_mint_url_from_env() == LDK_URL { + return; + } + + let ln_client = get_test_client().await; let db = Arc::new(memory::empty().await.unwrap()); let wallet1 = Wallet::new( @@ -257,7 +226,7 @@ async fn test_multimint_melt() { // Fund the wallets let quote = wallet1.mint_quote(mint_amount, None).await.unwrap(); - lnd_client + ln_client .pay_invoice(quote.request.clone()) .await .expect("failed to pay invoice"); @@ -271,7 +240,7 @@ async fn test_multimint_melt() { .unwrap(); let quote = wallet2.mint_quote(mint_amount, None).await.unwrap(); - lnd_client + ln_client .pay_invoice(quote.request.clone()) .await .expect("failed to pay invoice"); @@ -285,7 +254,7 @@ async fn test_multimint_melt() { .unwrap(); // Get an invoice - let invoice = lnd_client.create_invoice(Some(50)).await.unwrap(); + let invoice = ln_client.create_invoice(Some(50)).await.unwrap(); // Get multi-part melt quotes let melt_options = MeltOptions::Mpp { @@ -318,7 +287,7 @@ async fn test_multimint_melt() { #[tokio::test(flavor = "multi_thread", worker_threads = 1)] async fn test_cached_mint() { - let lnd_client = init_lnd_client().await; + let ln_client = get_test_client().await; let wallet = Wallet::new( &get_mint_url_from_env(), CurrencyUnit::Sat, @@ -331,7 +300,7 @@ async fn test_cached_mint() { let mint_amount = Amount::from(100); let quote = wallet.mint_quote(mint_amount, None).await.unwrap(); - lnd_client + ln_client .pay_invoice(quote.request.clone()) .await .expect("failed to pay invoice"); @@ -366,7 +335,7 @@ async fn test_cached_mint() { #[tokio::test(flavor = "multi_thread", worker_threads = 1)] async fn test_regtest_melt_amountless() { - let lnd_client = init_lnd_client().await; + let ln_client = get_test_client().await; let wallet = Wallet::new( &get_mint_url_from_env(), @@ -383,7 +352,7 @@ async fn test_regtest_melt_amountless() { assert_eq!(mint_quote.amount, Some(mint_amount)); - lnd_client + ln_client .pay_invoice(mint_quote.request) .await .expect("failed to pay invoice"); @@ -397,7 +366,7 @@ async fn test_regtest_melt_amountless() { assert!(mint_amount == amount); - let invoice = lnd_client.create_invoice(None).await.unwrap(); + let invoice = ln_client.create_invoice(None).await.unwrap(); let options = MeltOptions::new_amountless(5_000); @@ -410,3 +379,57 @@ async fn test_regtest_melt_amountless() { assert!(melt.amount == 5.into()); } + +#[tokio::test(flavor = "multi_thread", worker_threads = 1)] +async fn test_attempt_to_mint_unpaid() { + let wallet = Wallet::new( + &get_mint_url_from_env(), + CurrencyUnit::Sat, + Arc::new(memory::empty().await.unwrap()), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), + None, + ) + .expect("failed to create new wallet"); + + let mint_amount = Amount::from(100); + + let mint_quote = wallet.mint_quote(mint_amount, None).await.unwrap(); + + assert_eq!(mint_quote.amount, Some(mint_amount)); + + let proofs = wallet + .mint(&mint_quote.id, SplitTarget::default(), None) + .await; + + match proofs { + Err(err) => { + if !matches!(err, cdk::Error::UnpaidQuote) { + panic!("Wrong error quote should be unpaid: {}", err); + } + } + Ok(_) => { + panic!("Minting should not be allowed"); + } + } + + let mint_quote = wallet.mint_quote(mint_amount, None).await.unwrap(); + + let state = wallet.mint_quote_state(&mint_quote.id).await.unwrap(); + + assert!(state.state == MintQuoteState::Unpaid); + + let proofs = wallet + .mint(&mint_quote.id, SplitTarget::default(), None) + .await; + + match proofs { + Err(err) => { + if !matches!(err, cdk::Error::UnpaidQuote) { + panic!("Wrong error quote should be unpaid: {}", err); + } + } + Ok(_) => { + panic!("Minting should not be allowed"); + } + } +} diff --git a/crates/cdk-integration-tests/tests/test_fees.rs b/crates/cdk-integration-tests/tests/test_fees.rs index a2352f6c3..458c3495c 100644 --- a/crates/cdk-integration-tests/tests/test_fees.rs +++ b/crates/cdk-integration-tests/tests/test_fees.rs @@ -108,9 +108,7 @@ async fn test_fake_melt_change_in_quote() { let invoice_amount = 9; - let invoice = create_invoice_for_env(&get_temp_dir(), Some(invoice_amount)) - .await - .unwrap(); + let invoice = create_invoice_for_env(Some(invoice_amount)).await.unwrap(); let melt_quote = wallet.melt_quote(invoice.to_string(), None).await.unwrap(); diff --git a/crates/cdk-ldk-node/Cargo.toml b/crates/cdk-ldk-node/Cargo.toml new file mode 100644 index 000000000..94e3ca0be --- /dev/null +++ b/crates/cdk-ldk-node/Cargo.toml @@ -0,0 +1,34 @@ +[package] +name = "cdk-ldk-node" +version.workspace = true +edition.workspace = true +authors = ["CDK Developers"] +license.workspace = true +homepage = "https://github.com/cashubtc/cdk" +repository = "https://github.com/cashubtc/cdk.git" +rust-version.workspace = true # MSRV +description = "CDK ln backend for cdk-ldk-node" +readme = "README.md" + +[dependencies] +async-trait.workspace = true +axum.workspace = true +cdk-common = { workspace = true, features = ["mint"] } +futures.workspace = true +tokio.workspace = true +tokio-util.workspace = true +tracing.workspace = true +thiserror.workspace = true +ldk-node.workspace = true +tokio-stream = { workspace = true, features = ["sync"] } +serde.workspace = true +serde_json.workspace = true +maud = "0.27.0" +tower.workspace = true +tower-http.workspace = true +rust-embed = "8.5.0" +serde_urlencoded = "0.7" +urlencoding = "2.1" + + + diff --git a/crates/cdk-ldk-node/NETWORK_GUIDE.md b/crates/cdk-ldk-node/NETWORK_GUIDE.md new file mode 100644 index 000000000..50488db4c --- /dev/null +++ b/crates/cdk-ldk-node/NETWORK_GUIDE.md @@ -0,0 +1,165 @@ +# LDK Node Network Configuration Guide + +This guide provides configuration examples for running CDK LDK Node on different Bitcoin networks. + +## Table of Contents + +- [Mutinynet (Recommended for Testing)](#mutinynet-recommended-for-testing) +- [Bitcoin Testnet](#bitcoin-testnet) +- [Bitcoin Mainnet](#bitcoin-mainnet) +- [Regtest (Development)](#regtest-development) +- [Docker Deployment](#docker-deployment) +- [Troubleshooting](#troubleshooting) + +## Mutinynet (Recommended for Testing) + +**Mutinynet** is a Bitcoin signet-based test network designed specifically for Lightning Network development with fast block times and reliable infrastructure. + +### Configuration + +```toml +[info] +url = "http://127.0.0.1:8085/" +listen_host = "127.0.0.1" +listen_port = 8085 + +[database] +engine = "sqlite" + +[ln] +ln_backend = "ldk-node" + +[ldk_node] +bitcoin_network = "signet" +chain_source_type = "esplora" +esplora_url = "https://mutinynet.com/api" +gossip_source_type = "rgs" +rgs_url = "https://rgs.mutinynet.com/snapshot/0" +storage_dir_path = "~/.cdk-ldk-node/mutinynet" +webserver_port = 8091 +``` + +### Environment Variables + +```bash +export CDK_MINTD_LN_BACKEND="ldk-node" +export CDK_MINTD_LDK_NODE_BITCOIN_NETWORK="signet" +export CDK_MINTD_LDK_NODE_ESPLORA_URL="https://mutinynet.com/api" +export CDK_MINTD_LDK_NODE_RGS_URL="https://rgs.mutinynet.com/snapshot/0" +export CDK_MINTD_LDK_NODE_GOSSIP_SOURCE_TYPE="rgs" + +cdk-mintd +``` + +### Resources +- **Explorer/Faucet**: +- **Esplora API**: `https://mutinynet.com/api` +- **RGS Endpoint**: `https://rgs.mutinynet.com/snapshot/0` + +## Bitcoin Testnet + +```toml +[ln] +ln_backend = "ldk-node" + +[ldk_node] +bitcoin_network = "testnet" +esplora_url = "https://blockstream.info/testnet/api" +rgs_url = "https://rapidsync.lightningdevkit.org/snapshot" +gossip_source_type = "rgs" +storage_dir_path = "~/.cdk-ldk-node/testnet" +``` + +**Resources**: [Explorer](https://blockstream.info/testnet) | API: `https://blockstream.info/testnet/api` + +## Bitcoin Mainnet + +⚠️ **WARNING**: Uses real Bitcoin! + +```toml +[ln] +ln_backend = "ldk-node" + +[ldk_node] +bitcoin_network = "mainnet" +esplora_url = "https://blockstream.info/api" +rgs_url = "https://rapidsync.lightningdevkit.org/snapshot" +gossip_source_type = "rgs" +storage_dir_path = "/var/lib/cdk-ldk-node/mainnet" # Use absolute path +webserver_host = "127.0.0.1" # CRITICAL: Never bind to 0.0.0.0 in production +webserver_port = 8091 +``` + +**Resources**: [Explorer](https://blockstream.info) | API: `https://blockstream.info/api` + +### Production Security + +🔒 **CRITICAL SECURITY CONSIDERATIONS**: + +1. **Web Interface Security**: The LDK management interface has **NO AUTHENTICATION** and allows sending funds/managing channels. + - **NEVER** bind to `0.0.0.0` or expose publicly + - Only use `127.0.0.1` (localhost) + - Use VPN, SSH tunneling, or reverse proxy with authentication for remote access + +## Regtest (Development) + +```toml +[ln] +ln_backend = "ldk-node" + +[ldk_node] +bitcoin_network = "regtest" +chain_source_type = "bitcoinrpc" +bitcoind_rpc_host = "127.0.0.1" +bitcoind_rpc_port = 18443 +bitcoind_rpc_user = "testuser" +bitcoind_rpc_password = "testpass" +gossip_source_type = "p2p" +``` + +For complete regtest environment: `just regtest` (see [REGTEST_GUIDE.md](../../REGTEST_GUIDE.md)) + +## Docker Deployment + +⚠️ **SECURITY WARNING**: The examples below expose ports for testing. For production, **DO NOT expose port 8091** publicly as the web interface has no authentication and allows sending funds. + +```bash +# Mutinynet example (testing only - web interface exposed) +docker run -d \ + --name cdk-mintd \ + -p 8085:8085 -p 8091:8091 \ + -e CDK_MINTD_LN_BACKEND=ldk-node \ + -e CDK_MINTD_LDK_NODE_BITCOIN_NETWORK=signet \ + -e CDK_MINTD_LDK_NODE_ESPLORA_URL=https://mutinynet.com/api \ + -e CDK_MINTD_LDK_NODE_RGS_URL=https://rgs.mutinynet.com/snapshot/0 \ + -e CDK_MINTD_LDK_NODE_GOSSIP_SOURCE_TYPE=rgs \ + cashubtc/cdk-mintd:latest + +# Production example (web interface not exposed) +docker run -d \ + --name cdk-mintd \ + -p 8085:8085 \ + --network host \ + -e CDK_MINTD_LN_BACKEND=ldk-node \ + -e CDK_MINTD_LDK_NODE_BITCOIN_NETWORK=mainnet \ + -e CDK_MINTD_LDK_NODE_WEBSERVER_HOST=127.0.0.1 \ + cashubtc/cdk-mintd:latest +``` + +## Troubleshooting + +### Common Issues +- **RGS sync fails**: Try `gossip_source_type = "p2p"` +- **Connection errors**: Verify API endpoints with curl +- **Port conflicts**: Use `netstat -tuln` to check ports +- **Permissions**: Ensure storage directory is writable + +### Debug Logging +```bash +export CDK_MINTD_LOGGING_CONSOLE_LEVEL="debug" +``` + +### Performance Tips +- Use RGS for faster gossip sync +- PostgreSQL for production +- Monitor initial sync resources diff --git a/crates/cdk-ldk-node/README.md b/crates/cdk-ldk-node/README.md new file mode 100644 index 000000000..db7dcaa0c --- /dev/null +++ b/crates/cdk-ldk-node/README.md @@ -0,0 +1,84 @@ +# CDK LDK Node + +CDK lightning backend for ldk-node, providing Lightning Network functionality for CDK with support for Cashu operations. + +## Features + +- Lightning Network payments (Bolt11 and Bolt12) +- Channel management +- Payment processing for Cashu mint operations +- Web management interface +- Support for multiple Bitcoin networks (Mainnet, Testnet, Signet/Mutinynet, Regtest) +- RGS (Rapid Gossip Sync) and P2P gossip support + +## Quick Start + +### Mutinynet (Recommended for Testing) + +```bash +# Using environment variables (simplest) +export CDK_MINTD_LN_BACKEND="ldk-node" +export CDK_MINTD_LDK_NODE_BITCOIN_NETWORK="signet" +export CDK_MINTD_LDK_NODE_ESPLORA_URL="https://mutinynet.com/api" +export CDK_MINTD_LDK_NODE_RGS_URL="https://rgs.mutinynet.com/snapshot/0" +export CDK_MINTD_LDK_NODE_GOSSIP_SOURCE_TYPE="rgs" + +cdk-mintd +``` + +After starting: +- Mint API: +- LDK management interface: +- Get test sats: [mutinynet.com](https://mutinynet.com) + +**For complete network configuration examples, Docker setup, and production deployment, see [NETWORK_GUIDE.md](./NETWORK_GUIDE.md).** + +## Web Management Interface + +The CDK LDK Node includes a built-in web management interface accessible at `http://127.0.0.1:8091` by default. + +⚠️ **SECURITY WARNING**: The web management interface has **NO AUTHENTICATION** and allows sending funds and managing channels. **NEVER expose it publicly** without proper authentication/authorization in front of it. Only bind to localhost (`127.0.0.1`) for security. + +### Key Features +- **Dashboard**: Node status, balance, and recent activity +- **Channel Management**: Open and close Lightning channels +- **Payment Management**: Create invoices, send payments, view history with pagination +- **On-chain Operations**: View balances and manage transactions + +### Configuration + +```toml +[ldk_node] +webserver_host = "127.0.0.1" # IMPORTANT: Only localhost for security +webserver_port = 8091 # 0 = auto-assign port +``` + +Or via environment variables: +- `CDK_MINTD_LDK_NODE_WEBSERVER_HOST` +- `CDK_MINTD_LDK_NODE_WEBSERVER_PORT` + +## Basic Configuration + +### Config File Example + +```toml +[ln] +ln_backend = "ldk-node" + +[ldk_node] +bitcoin_network = "signet" # mainnet, testnet, signet, regtest +esplora_url = "https://mutinynet.com/api" +rgs_url = "https://rgs.mutinynet.com/snapshot/0" +gossip_source_type = "rgs" # rgs or p2p +webserver_port = 8091 +``` + +### Environment Variables + +All options can be set with `CDK_MINTD_LDK_NODE_` prefix: +- `CDK_MINTD_LDK_NODE_BITCOIN_NETWORK` +- `CDK_MINTD_LDK_NODE_ESPLORA_URL` +- `CDK_MINTD_LDK_NODE_RGS_URL` +- `CDK_MINTD_LDK_NODE_GOSSIP_SOURCE_TYPE` + +**For detailed network configurations, Docker setup, production deployment, and troubleshooting, see [NETWORK_GUIDE.md](./NETWORK_GUIDE.md).** diff --git a/crates/cdk-ldk-node/src/error.rs b/crates/cdk-ldk-node/src/error.rs new file mode 100644 index 000000000..4464d278a --- /dev/null +++ b/crates/cdk-ldk-node/src/error.rs @@ -0,0 +1,89 @@ +//! LDK Node Errors + +use thiserror::Error; + +/// LDK Node Error +#[derive(Debug, Error)] +pub enum Error { + /// LDK Node error + #[error("LDK Node error: {0}")] + LdkNode(#[from] ldk_node::NodeError), + + /// LDK Build error + #[error("LDK Build error: {0}")] + LdkBuild(#[from] ldk_node::BuildError), + + /// Invalid description + #[error("Invalid description")] + InvalidDescription, + + /// Invalid payment hash + #[error("Invalid payment hash")] + InvalidPaymentHash, + + /// Invalid payment hash length + #[error("Invalid payment hash length")] + InvalidPaymentHashLength, + + /// Invalid payment ID length + #[error("Invalid payment ID length")] + InvalidPaymentIdLength, + + /// Unknown invoice amount + #[error("Unknown invoice amount")] + UnknownInvoiceAmount, + + /// Could not send bolt11 payment + #[error("Could not send bolt11 payment")] + CouldNotSendBolt11, + + /// Could not send bolt11 without amount + #[error("Could not send bolt11 without amount")] + CouldNotSendBolt11WithoutAmount, + + /// Payment not found + #[error("Payment not found")] + PaymentNotFound, + + /// Could not get amount spent + #[error("Could not get amount spent")] + CouldNotGetAmountSpent, + + /// Could not get payment amount + #[error("Could not get payment amount")] + CouldNotGetPaymentAmount, + + /// Unexpected payment kind + #[error("Unexpected payment kind")] + UnexpectedPaymentKind, + + /// Unsupported payment identifier type + #[error("Unsupported payment identifier type")] + UnsupportedPaymentIdentifierType, + + /// Invalid payment direction + #[error("Invalid payment direction")] + InvalidPaymentDirection, + + /// Hex decode error + #[error("Hex decode error: {0}")] + HexDecode(#[from] cdk_common::util::hex::Error), + + /// JSON error + #[error("JSON error: {0}")] + Json(#[from] serde_json::Error), + + /// Amount conversion error + #[error("Amount conversion error: {0}")] + AmountConversion(#[from] cdk_common::amount::Error), + + /// Invalid hex + #[error("Invalid hex")] + InvalidHex, +} + +impl From for cdk_common::payment::Error { + fn from(e: Error) -> Self { + Self::Lightning(Box::new(e)) + } +} diff --git a/crates/cdk-ldk-node/src/lib.rs b/crates/cdk-ldk-node/src/lib.rs new file mode 100644 index 000000000..dde3b5ed5 --- /dev/null +++ b/crates/cdk-ldk-node/src/lib.rs @@ -0,0 +1,994 @@ +//! CDK lightning backend for ldk-node + +#![doc = include_str!("../README.md")] +#![warn(missing_docs)] +#![warn(rustdoc::bare_urls)] + +use std::net::SocketAddr; +use std::pin::Pin; +use std::sync::atomic::{AtomicBool, Ordering}; +use std::sync::Arc; + +use async_trait::async_trait; +use cdk_common::amount::to_unit; +use cdk_common::common::FeeReserve; +use cdk_common::payment::{self, *}; +use cdk_common::util::{hex, unix_time}; +use cdk_common::{Amount, CurrencyUnit, MeltOptions, MeltQuoteState}; +use futures::{Stream, StreamExt}; +use ldk_node::bitcoin::hashes::Hash; +use ldk_node::bitcoin::Network; +use ldk_node::lightning::ln::channelmanager::PaymentId; +use ldk_node::lightning::ln::msgs::SocketAddress; +use ldk_node::lightning_invoice::{Bolt11InvoiceDescription, Description}; +use ldk_node::lightning_types::payment::PaymentHash; +use ldk_node::payment::{PaymentDirection, PaymentKind, PaymentStatus, SendingParameters}; +use ldk_node::{Builder, Event, Node}; +use tokio::runtime::Runtime; +use tokio_stream::wrappers::BroadcastStream; +use tokio_util::sync::CancellationToken; +use tracing::instrument; + +use crate::error::Error; + +mod error; +mod web; + +/// CDK Lightning backend using LDK Node +/// +/// Provides Lightning Network functionality for CDK with support for Cashu operations. +/// Handles payment creation, processing, and event management using the Lightning Development Kit. +#[derive(Clone)] +pub struct CdkLdkNode { + inner: Arc, + fee_reserve: FeeReserve, + wait_invoice_cancel_token: CancellationToken, + wait_invoice_is_active: Arc, + sender: tokio::sync::broadcast::Sender, + receiver: Arc>, + events_cancel_token: CancellationToken, + runtime: Option>, + web_addr: Option, +} + +/// Configuration for connecting to Bitcoin RPC +/// +/// Contains the necessary connection parameters for Bitcoin Core RPC interface. +#[derive(Debug, Clone)] +pub struct BitcoinRpcConfig { + /// Bitcoin RPC server hostname or IP address + pub host: String, + /// Bitcoin RPC server port number + pub port: u16, + /// Username for Bitcoin RPC authentication + pub user: String, + /// Password for Bitcoin RPC authentication + pub password: String, +} + +/// Source of blockchain data for the Lightning node +/// +/// Specifies how the node should connect to the Bitcoin network to retrieve +/// blockchain information and broadcast transactions. +#[derive(Debug, Clone)] +pub enum ChainSource { + /// Use an Esplora server for blockchain data + /// + /// Contains the URL of the Esplora server endpoint + Esplora(String), + /// Use Bitcoin Core RPC for blockchain data + /// + /// Contains the configuration for connecting to Bitcoin Core + BitcoinRpc(BitcoinRpcConfig), +} + +/// Source of Lightning network gossip data +/// +/// Specifies how the node should learn about the Lightning Network topology +/// and routing information. +#[derive(Debug, Clone)] +pub enum GossipSource { + /// Learn gossip through peer-to-peer connections + /// + /// The node will connect to other Lightning nodes and exchange gossip data directly + P2P, + /// Use Rapid Gossip Sync for efficient gossip updates + /// + /// Contains the URL of the RGS server for compressed gossip data + RapidGossipSync(String), +} + +impl CdkLdkNode { + /// Create a new CDK LDK Node instance + /// + /// # Arguments + /// * `network` - Bitcoin network (mainnet, testnet, regtest, signet) + /// * `chain_source` - Source of blockchain data (Esplora or Bitcoin RPC) + /// * `gossip_source` - Source of Lightning network gossip data + /// * `storage_dir_path` - Directory path for node data storage + /// * `fee_reserve` - Fee reserve configuration for payments + /// * `listening_address` - Socket addresses for peer connections + /// * `runtime` - Optional Tokio runtime to use for starting the node + /// + /// # Returns + /// A new `CdkLdkNode` instance ready to be started + /// + /// # Errors + /// Returns an error if the LDK node builder fails to create the node + pub fn new( + network: Network, + chain_source: ChainSource, + gossip_source: GossipSource, + storage_dir_path: String, + fee_reserve: FeeReserve, + listening_address: Vec, + runtime: Option>, + ) -> Result { + let mut builder = Builder::new(); + builder.set_network(network); + tracing::info!("Storage dir of node is {}", storage_dir_path); + builder.set_storage_dir_path(storage_dir_path); + + match chain_source { + ChainSource::Esplora(esplora_url) => { + builder.set_chain_source_esplora(esplora_url, None); + } + ChainSource::BitcoinRpc(BitcoinRpcConfig { + host, + port, + user, + password, + }) => { + builder.set_chain_source_bitcoind_rpc(host, port, user, password); + } + } + + match gossip_source { + GossipSource::P2P => { + builder.set_gossip_source_p2p(); + } + GossipSource::RapidGossipSync(rgs_url) => { + builder.set_gossip_source_rgs(rgs_url); + } + } + + builder.set_listening_addresses(listening_address)?; + + builder.set_node_alias("cdk-ldk-node".to_string())?; + + let node = builder.build()?; + + tracing::info!("Creating tokio channel for payment notifications"); + let (sender, receiver) = tokio::sync::broadcast::channel(8); + + let id = node.node_id(); + + let adr = node.announcement_addresses(); + + tracing::info!( + "Created node {} with address {:?} on network {}", + id, + adr, + network + ); + + Ok(Self { + inner: node.into(), + fee_reserve, + wait_invoice_cancel_token: CancellationToken::new(), + wait_invoice_is_active: Arc::new(AtomicBool::new(false)), + sender, + receiver: Arc::new(receiver), + events_cancel_token: CancellationToken::new(), + runtime, + web_addr: None, + }) + } + + /// Set the web server address for the LDK node management interface + /// + /// # Arguments + /// * `addr` - Socket address for the web server. If None, no web server will be started. + pub fn set_web_addr(&mut self, addr: Option) { + self.web_addr = addr; + } + + /// Get a default web server address using an unused port + /// + /// Returns a SocketAddr with localhost and port 0, which will cause + /// the system to automatically assign an available port + pub fn default_web_addr() -> SocketAddr { + SocketAddr::from(([127, 0, 0, 1], 8091)) + } + + /// Start the CDK LDK Node + /// + /// Starts the underlying LDK node and begins event processing. + /// Sets up event handlers to listen for Lightning events like payment received. + /// + /// # Returns + /// Returns `Ok(())` on successful start, error otherwise + /// + /// # Errors + /// Returns an error if the LDK node fails to start or event handling setup fails + pub fn start_ldk_node(&self) -> Result<(), Error> { + match &self.runtime { + Some(runtime) => { + tracing::info!("Starting cdk-ldk node with existing runtime"); + self.inner.start_with_runtime(Arc::clone(runtime))? + } + None => { + tracing::info!("Starting cdk-ldk-node with new runtime"); + self.inner.start()? + } + }; + let node_config = self.inner.config(); + + tracing::info!("Starting node with network {}", node_config.network); + + tracing::info!("Node status: {:?}", self.inner.status()); + + self.handle_events()?; + + Ok(()) + } + + /// Start the web server for the LDK node management interface + /// + /// Starts a web server that provides a user interface for managing the LDK node. + /// The web interface allows users to view balances, manage channels, create invoices, + /// and send payments. + /// + /// # Arguments + /// * `web_addr` - The socket address to bind the web server to + /// + /// # Returns + /// Returns `Ok(())` on successful start, error otherwise + /// + /// # Errors + /// Returns an error if the web server fails to start + pub fn start_web_server(&self, web_addr: SocketAddr) -> Result<(), Error> { + let web_server = crate::web::WebServer::new(Arc::new(self.clone())); + + tokio::spawn(async move { + if let Err(e) = web_server.serve(web_addr).await { + tracing::error!("Web server error: {}", e); + } + }); + + Ok(()) + } + + /// Stop the CDK LDK Node + /// + /// Gracefully stops the node by cancelling all active tasks and event handlers. + /// This includes: + /// - Cancelling the event handler task + /// - Cancelling any active wait_invoice streams + /// - Stopping the underlying LDK node + /// + /// # Returns + /// Returns `Ok(())` on successful shutdown, error otherwise + /// + /// # Errors + /// Returns an error if the underlying LDK node fails to stop + pub fn stop_ldk_node(&self) -> Result<(), Error> { + tracing::info!("Stopping CdkLdkNode"); + // Cancel all tokio tasks + tracing::info!("Cancelling event handler"); + self.events_cancel_token.cancel(); + + // Cancel any wait_invoice streams + if self.is_wait_invoice_active() { + tracing::info!("Cancelling wait_invoice stream"); + self.wait_invoice_cancel_token.cancel(); + } + + // Stop the LDK node + tracing::info!("Stopping LDK node"); + self.inner.stop()?; + tracing::info!("CdkLdkNode stopped successfully"); + Ok(()) + } + + /// Handle payment received event + async fn handle_payment_received( + node: &Arc, + sender: &tokio::sync::broadcast::Sender, + payment_id: Option, + payment_hash: PaymentHash, + amount_msat: u64, + ) { + tracing::info!( + "Received payment for hash={} of amount={} msat", + payment_hash, + amount_msat + ); + + let payment_id = match payment_id { + Some(id) => id, + None => { + tracing::warn!("Received payment without payment_id"); + return; + } + }; + + let payment_id_hex = hex::encode(payment_id.0); + + if amount_msat == 0 { + tracing::warn!("Payment of no amount"); + return; + } + + tracing::info!( + "Processing payment notification: id={}, amount={} msats", + payment_id_hex, + amount_msat + ); + + let payment_details = match node.payment(&payment_id) { + Some(details) => details, + None => { + tracing::error!("Could not find payment details for id={}", payment_id_hex); + return; + } + }; + + let (payment_identifier, payment_id) = match payment_details.kind { + PaymentKind::Bolt11 { hash, .. } => { + (PaymentIdentifier::PaymentHash(hash.0), hash.to_string()) + } + PaymentKind::Bolt12Offer { hash, offer_id, .. } => match hash { + Some(h) => ( + PaymentIdentifier::OfferId(offer_id.to_string()), + h.to_string(), + ), + None => { + tracing::error!("Bolt12 payment missing hash"); + return; + } + }, + k => { + tracing::warn!("Received payment of kind {:?} which is not supported", k); + return; + } + }; + + let wait_payment_response = WaitPaymentResponse { + payment_identifier, + payment_amount: amount_msat.into(), + unit: CurrencyUnit::Msat, + payment_id, + }; + + match sender.send(wait_payment_response) { + Ok(_) => tracing::info!("Successfully sent payment notification to stream"), + Err(err) => tracing::error!( + "Could not send payment received notification on channel: {}", + err + ), + } + } + + /// Set up event handling for the node + pub fn handle_events(&self) -> Result<(), Error> { + let node = self.inner.clone(); + let sender = self.sender.clone(); + let cancel_token = self.events_cancel_token.clone(); + + tracing::info!("Starting event handler task"); + + tokio::spawn(async move { + tracing::info!("Event handler loop started"); + loop { + tokio::select! { + _ = cancel_token.cancelled() => { + tracing::info!("Event handler cancelled"); + break; + } + event = node.next_event_async() => { + match event { + Event::PaymentReceived { + payment_id, + payment_hash, + amount_msat, + custom_records: _ + } => { + Self::handle_payment_received( + &node, + &sender, + payment_id, + payment_hash, + amount_msat + ).await; + } + event => { + tracing::debug!("Received other ldk node event: {:?}", event); + } + } + + if let Err(err) = node.event_handled() { + tracing::error!("Error handling node event: {}", err); + } else { + tracing::debug!("Successfully handled node event"); + } + } + } + } + tracing::info!("Event handler loop terminated"); + }); + + tracing::info!("Event handler task spawned"); + Ok(()) + } + + /// Get Node used + pub fn node(&self) -> Arc { + Arc::clone(&self.inner) + } +} + +/// Mint payment trait +#[async_trait] +impl MintPayment for CdkLdkNode { + type Err = payment::Error; + + /// Start the payment processor + /// Starts the LDK node and begins event processing + async fn start(&self) -> Result<(), Self::Err> { + self.start_ldk_node().map_err(|e| { + tracing::error!("Failed to start CdkLdkNode: {}", e); + e + })?; + + tracing::info!("CdkLdkNode payment processor started successfully"); + + // Start web server if configured + if let Some(web_addr) = self.web_addr { + tracing::info!("Starting LDK Node web interface on {}", web_addr); + self.start_web_server(web_addr).map_err(|e| { + tracing::error!("Failed to start web server: {}", e); + e + })?; + } else { + tracing::info!("No web server address configured, skipping web interface"); + } + + Ok(()) + } + + /// Stop the payment processor + /// Gracefully stops the LDK node and cancels all background tasks + async fn stop(&self) -> Result<(), Self::Err> { + self.stop_ldk_node().map_err(|e| { + tracing::error!("Failed to stop CdkLdkNode: {}", e); + e.into() + }) + } + + /// Base Settings + async fn get_settings(&self) -> Result { + let settings = Bolt11Settings { + mpp: false, + unit: CurrencyUnit::Msat, + invoice_description: true, + amountless: true, + bolt12: true, + }; + Ok(serde_json::to_value(settings)?) + } + + /// Create a new invoice + #[instrument(skip(self))] + async fn create_incoming_payment_request( + &self, + unit: &CurrencyUnit, + options: IncomingPaymentOptions, + ) -> Result { + match options { + IncomingPaymentOptions::Bolt11(bolt11_options) => { + let amount_msat = to_unit(bolt11_options.amount, unit, &CurrencyUnit::Msat)?; + let description = bolt11_options.description.unwrap_or_default(); + let time = bolt11_options + .unix_expiry + .map(|t| t - unix_time()) + .unwrap_or(36000); + + let description = Bolt11InvoiceDescription::Direct( + Description::new(description).map_err(|_| Error::InvalidDescription)?, + ); + + let payment = self + .inner + .bolt11_payment() + .receive(amount_msat.into(), &description, time as u32) + .map_err(Error::LdkNode)?; + + let payment_hash = payment.payment_hash().to_string(); + let payment_identifier = PaymentIdentifier::PaymentHash( + hex::decode(&payment_hash)? + .try_into() + .map_err(|_| Error::InvalidPaymentHashLength)?, + ); + + Ok(CreateIncomingPaymentResponse { + request_lookup_id: payment_identifier, + request: payment.to_string(), + expiry: Some(unix_time() + time), + }) + } + IncomingPaymentOptions::Bolt12(bolt12_options) => { + let Bolt12IncomingPaymentOptions { + description, + amount, + unix_expiry, + } = *bolt12_options; + + let time = unix_expiry.map(|t| (t - unix_time()) as u32); + + let offer = match amount { + Some(amount) => { + let amount_msat = to_unit(amount, unit, &CurrencyUnit::Msat)?; + + self.inner + .bolt12_payment() + .receive( + amount_msat.into(), + &description.unwrap_or("".to_string()), + time, + None, + ) + .map_err(Error::LdkNode)? + } + None => self + .inner + .bolt12_payment() + .receive_variable_amount(&description.unwrap_or("".to_string()), time) + .map_err(Error::LdkNode)?, + }; + let payment_identifier = PaymentIdentifier::OfferId(offer.id().to_string()); + + Ok(CreateIncomingPaymentResponse { + request_lookup_id: payment_identifier, + request: offer.to_string(), + expiry: time.map(|a| a as u64), + }) + } + } + } + + /// Get payment quote + /// Used to get fee and amount required for a payment request + #[instrument(skip_all)] + async fn get_payment_quote( + &self, + unit: &CurrencyUnit, + options: OutgoingPaymentOptions, + ) -> Result { + match options { + OutgoingPaymentOptions::Bolt11(bolt11_options) => { + let bolt11 = bolt11_options.bolt11; + + let amount_msat = match bolt11_options.melt_options { + Some(melt_options) => melt_options.amount_msat(), + None => bolt11 + .amount_milli_satoshis() + .ok_or(Error::UnknownInvoiceAmount)? + .into(), + }; + + let amount = to_unit(amount_msat, &CurrencyUnit::Msat, unit)?; + + let relative_fee_reserve = + (self.fee_reserve.percent_fee_reserve * u64::from(amount) as f32) as u64; + + let absolute_fee_reserve: u64 = self.fee_reserve.min_fee_reserve.into(); + + let fee = match relative_fee_reserve > absolute_fee_reserve { + true => relative_fee_reserve, + false => absolute_fee_reserve, + }; + + let payment_hash = bolt11.payment_hash().to_string(); + let payment_hash_bytes = hex::decode(&payment_hash)? + .try_into() + .map_err(|_| Error::InvalidPaymentHashLength)?; + + Ok(PaymentQuoteResponse { + request_lookup_id: Some(PaymentIdentifier::PaymentHash(payment_hash_bytes)), + amount, + fee: fee.into(), + state: MeltQuoteState::Unpaid, + unit: unit.clone(), + }) + } + OutgoingPaymentOptions::Bolt12(bolt12_options) => { + let offer = bolt12_options.offer; + + let amount_msat = match bolt12_options.melt_options { + Some(melt_options) => melt_options.amount_msat(), + None => { + let amount = offer.amount().ok_or(payment::Error::AmountMismatch)?; + + match amount { + ldk_node::lightning::offers::offer::Amount::Bitcoin { + amount_msats, + } => amount_msats.into(), + _ => return Err(payment::Error::AmountMismatch), + } + } + }; + let amount = to_unit(amount_msat, &CurrencyUnit::Msat, unit)?; + + let relative_fee_reserve = + (self.fee_reserve.percent_fee_reserve * u64::from(amount) as f32) as u64; + + let absolute_fee_reserve: u64 = self.fee_reserve.min_fee_reserve.into(); + + let fee = match relative_fee_reserve > absolute_fee_reserve { + true => relative_fee_reserve, + false => absolute_fee_reserve, + }; + + Ok(PaymentQuoteResponse { + request_lookup_id: None, + amount, + fee: fee.into(), + state: MeltQuoteState::Unpaid, + unit: unit.clone(), + }) + } + } + } + + /// Pay request + #[instrument(skip(self, options))] + async fn make_payment( + &self, + unit: &CurrencyUnit, + options: OutgoingPaymentOptions, + ) -> Result { + match options { + OutgoingPaymentOptions::Bolt11(bolt11_options) => { + let bolt11 = bolt11_options.bolt11; + + let send_params = match bolt11_options + .max_fee_amount + .map(|f| { + to_unit(f, unit, &CurrencyUnit::Msat).map(|amount_msat| SendingParameters { + max_total_routing_fee_msat: Some(Some(amount_msat.into())), + max_channel_saturation_power_of_half: None, + max_total_cltv_expiry_delta: None, + max_path_count: None, + }) + }) + .transpose() + { + Ok(params) => params, + Err(err) => { + tracing::error!("Failed to convert fee amount: {}", err); + return Err(payment::Error::Custom(format!("Invalid fee amount: {err}"))); + } + }; + + let payment_id = match bolt11_options.melt_options { + Some(MeltOptions::Amountless { amountless }) => self + .inner + .bolt11_payment() + .send_using_amount(&bolt11, amountless.amount_msat.into(), send_params) + .map_err(|err| { + tracing::error!("Could not send send amountless bolt11: {}", err); + Error::CouldNotSendBolt11WithoutAmount + })?, + None => self + .inner + .bolt11_payment() + .send(&bolt11, send_params) + .map_err(|err| { + tracing::error!("Could not send bolt11 {}", err); + Error::CouldNotSendBolt11 + })?, + _ => return Err(payment::Error::UnsupportedPaymentOption), + }; + + // Check payment status for up to 10 seconds + let start = std::time::Instant::now(); + let timeout = std::time::Duration::from_secs(10); + + let (status, payment_details) = loop { + let details = self + .inner + .payment(&payment_id) + .ok_or(Error::PaymentNotFound)?; + + match details.status { + PaymentStatus::Succeeded => break (MeltQuoteState::Paid, details), + PaymentStatus::Failed => { + tracing::error!("Failed to pay bolt11 payment."); + break (MeltQuoteState::Failed, details); + } + PaymentStatus::Pending => { + if start.elapsed() > timeout { + tracing::warn!( + "Paying bolt11 exceeded timeout 10 seconds no longer waitning." + ); + break (MeltQuoteState::Pending, details); + } + tokio::time::sleep(std::time::Duration::from_millis(100)).await; + continue; + } + } + }; + + let payment_proof = match payment_details.kind { + PaymentKind::Bolt11 { + hash: _, + preimage, + secret: _, + } => preimage.map(|p| p.to_string()), + _ => return Err(Error::UnexpectedPaymentKind.into()), + }; + + let total_spent = payment_details + .amount_msat + .ok_or(Error::CouldNotGetAmountSpent)?; + + let total_spent = to_unit(total_spent, &CurrencyUnit::Msat, unit)?; + + Ok(MakePaymentResponse { + payment_lookup_id: PaymentIdentifier::PaymentHash( + bolt11.payment_hash().to_byte_array(), + ), + payment_proof, + status, + total_spent, + unit: unit.clone(), + }) + } + OutgoingPaymentOptions::Bolt12(bolt12_options) => { + let offer = bolt12_options.offer; + + let payment_id = match bolt12_options.melt_options { + Some(MeltOptions::Amountless { amountless }) => self + .inner + .bolt12_payment() + .send_using_amount(&offer, amountless.amount_msat.into(), None, None) + .map_err(Error::LdkNode)?, + None => self + .inner + .bolt12_payment() + .send(&offer, None, None) + .map_err(Error::LdkNode)?, + _ => return Err(payment::Error::UnsupportedPaymentOption), + }; + + // Check payment status for up to 10 seconds + let start = std::time::Instant::now(); + let timeout = std::time::Duration::from_secs(10); + + let (status, payment_details) = loop { + let details = self + .inner + .payment(&payment_id) + .ok_or(Error::PaymentNotFound)?; + + match details.status { + PaymentStatus::Succeeded => break (MeltQuoteState::Paid, details), + PaymentStatus::Failed => { + tracing::error!("Payment with id {} failed.", payment_id); + break (MeltQuoteState::Failed, details); + } + PaymentStatus::Pending => { + if start.elapsed() > timeout { + tracing::warn!( + "Payment has been being for 10 seconds. No longer waiting" + ); + break (MeltQuoteState::Pending, details); + } + tokio::time::sleep(std::time::Duration::from_millis(100)).await; + continue; + } + } + }; + + let payment_proof = match payment_details.kind { + PaymentKind::Bolt12Offer { + hash: _, + preimage, + secret: _, + offer_id: _, + payer_note: _, + quantity: _, + } => preimage.map(|p| p.to_string()), + _ => return Err(Error::UnexpectedPaymentKind.into()), + }; + + let total_spent = payment_details + .amount_msat + .ok_or(Error::CouldNotGetAmountSpent)?; + + let total_spent = to_unit(total_spent, &CurrencyUnit::Msat, unit)?; + + Ok(MakePaymentResponse { + payment_lookup_id: PaymentIdentifier::PaymentId(payment_id.0), + payment_proof, + status, + total_spent, + unit: unit.clone(), + }) + } + } + } + + /// Listen for invoices to be paid to the mint + /// Returns a stream of request_lookup_id once invoices are paid + #[instrument(skip(self))] + async fn wait_any_incoming_payment( + &self, + ) -> Result + Send>>, Self::Err> { + tracing::info!("Starting stream for invoices - wait_any_incoming_payment called"); + + // Set active flag to indicate stream is active + self.wait_invoice_is_active.store(true, Ordering::SeqCst); + tracing::debug!("wait_invoice_is_active set to true"); + + let receiver = self.receiver.clone(); + + tracing::info!("Receiver obtained successfully, creating response stream"); + + // Transform the String stream into a WaitPaymentResponse stream + let response_stream = BroadcastStream::new(receiver.resubscribe()); + + // Map the stream to handle BroadcastStreamRecvError + let response_stream = response_stream.filter_map(|result| async move { + match result { + Ok(payment) => Some(payment), + Err(err) => { + tracing::warn!("Error in broadcast stream: {}", err); + None + } + } + }); + + // Create a combined stream that also handles cancellation + let cancel_token = self.wait_invoice_cancel_token.clone(); + let is_active = self.wait_invoice_is_active.clone(); + + let stream = Box::pin(response_stream); + + // Set up a task to clean up when the stream is dropped + tokio::spawn(async move { + cancel_token.cancelled().await; + tracing::info!("wait_invoice stream cancelled"); + is_active.store(false, Ordering::SeqCst); + }); + + tracing::info!("wait_any_incoming_payment returning stream"); + Ok(stream) + } + + /// Is wait invoice active + fn is_wait_invoice_active(&self) -> bool { + self.wait_invoice_is_active.load(Ordering::SeqCst) + } + + /// Cancel wait invoice + fn cancel_wait_invoice(&self) { + self.wait_invoice_cancel_token.cancel() + } + + /// Check the status of an incoming payment + async fn check_incoming_payment_status( + &self, + payment_identifier: &PaymentIdentifier, + ) -> Result, Self::Err> { + let payment_id_str = match payment_identifier { + PaymentIdentifier::PaymentHash(hash) => hex::encode(hash), + PaymentIdentifier::CustomId(id) => id.clone(), + _ => return Err(Error::UnsupportedPaymentIdentifierType.into()), + }; + + let payment_id = PaymentId( + hex::decode(&payment_id_str)? + .try_into() + .map_err(|_| Error::InvalidPaymentIdLength)?, + ); + + let payment_details = self + .inner + .payment(&payment_id) + .ok_or(Error::PaymentNotFound)?; + + if payment_details.direction == PaymentDirection::Outbound { + return Err(Error::InvalidPaymentDirection.into()); + } + + let amount = if payment_details.status == PaymentStatus::Succeeded { + payment_details + .amount_msat + .ok_or(Error::CouldNotGetPaymentAmount)? + } else { + return Ok(vec![]); + }; + + let response = WaitPaymentResponse { + payment_identifier: payment_identifier.clone(), + payment_amount: amount.into(), + unit: CurrencyUnit::Msat, + payment_id: payment_id_str, + }; + + Ok(vec![response]) + } + + /// Check the status of an outgoing payment + async fn check_outgoing_payment( + &self, + request_lookup_id: &PaymentIdentifier, + ) -> Result { + let payment_details = match request_lookup_id { + PaymentIdentifier::PaymentHash(id_hash) => self + .inner + .list_payments_with_filter( + |p| matches!(&p.kind, PaymentKind::Bolt11 { hash, .. } if &hash.0 == id_hash), + ) + .first() + .cloned(), + PaymentIdentifier::PaymentId(id) => self.inner.payment(&PaymentId( + hex::decode(id)? + .try_into() + .map_err(|_| payment::Error::Custom("Invalid hex".to_string()))?, + )), + _ => { + return Ok(MakePaymentResponse { + payment_lookup_id: request_lookup_id.clone(), + status: MeltQuoteState::Unknown, + payment_proof: None, + total_spent: Amount::ZERO, + unit: CurrencyUnit::Msat, + }); + } + } + .ok_or(Error::PaymentNotFound)?; + + // This check seems reversed in the original code, so I'm fixing it here + if payment_details.direction != PaymentDirection::Outbound { + return Err(Error::InvalidPaymentDirection.into()); + } + + let status = match payment_details.status { + PaymentStatus::Pending => MeltQuoteState::Pending, + PaymentStatus::Succeeded => MeltQuoteState::Paid, + PaymentStatus::Failed => MeltQuoteState::Failed, + }; + + let payment_proof = match payment_details.kind { + PaymentKind::Bolt11 { + hash: _, + preimage, + secret: _, + } => preimage.map(|p| p.to_string()), + _ => return Err(Error::UnexpectedPaymentKind.into()), + }; + + let total_spent = payment_details + .amount_msat + .ok_or(Error::CouldNotGetAmountSpent)?; + + Ok(MakePaymentResponse { + payment_lookup_id: request_lookup_id.clone(), + payment_proof, + status, + total_spent: total_spent.into(), + unit: CurrencyUnit::Msat, + }) + } +} + +impl Drop for CdkLdkNode { + fn drop(&mut self) { + tracing::info!("Drop called on CdkLdkNode"); + self.wait_invoice_cancel_token.cancel(); + tracing::debug!("Cancelled wait_invoice token in drop"); + } +} diff --git a/crates/cdk-ldk-node/src/web/handlers/channels.rs b/crates/cdk-ldk-node/src/web/handlers/channels.rs new file mode 100644 index 000000000..238f9365d --- /dev/null +++ b/crates/cdk-ldk-node/src/web/handlers/channels.rs @@ -0,0 +1,515 @@ +use std::collections::HashMap; +use std::str::FromStr; + +use axum::body::Body; +use axum::extract::{Query, State}; +use axum::http::StatusCode; +use axum::response::{Html, Response}; +use axum::Form; +use ldk_node::bitcoin::secp256k1::PublicKey; +use ldk_node::lightning::ln::msgs::SocketAddress; +use ldk_node::UserChannelId; +use maud::html; +use serde::Deserialize; + +use crate::web::handlers::utils::deserialize_optional_u64; +use crate::web::handlers::AppState; +use crate::web::templates::{ + error_message, form_card, format_sats_as_btc, info_card, layout, success_message, +}; + +#[derive(Deserialize)] +pub struct OpenChannelForm { + node_id: String, + address: String, + port: u32, + amount_sats: u64, + #[serde(deserialize_with = "deserialize_optional_u64")] + push_btc: Option, +} + +#[derive(Deserialize)] +pub struct CloseChannelForm { + channel_id: String, + node_id: String, +} + +pub async fn channels_page(State(_state): State) -> Result { + // Redirect to the balance page since channels are now part of the Lightning section + Ok(Response::builder() + .status(StatusCode::FOUND) + .header("Location", "/balance") + .body(Body::empty()) + .unwrap()) +} + +pub async fn open_channel_page(State(_state): State) -> Result, StatusCode> { + let content = form_card( + "Open New Channel", + html! { + form method="post" action="/channels/open" { + div class="form-group" { + label for="node_id" { "Node Public Key" } + input type="text" id="node_id" name="node_id" required placeholder="02..." {} + } + div class="form-group" { + label for="address" { "Node Address" } + input type="text" id="address" name="address" required placeholder="127.0.0.1" {} + } + div class="form-group" { + label for="port" { "Port" } + input type="number" id="port" name="port" required value="9735" {} + } + div class="form-group" { + label for="amount_btc" { "Channel Size" } + input type="number" id="amount_sats" name="amount_sats" required placeholder="₿0" step="1" {} + } + div class="form-group" { + label for="push_btc" { "Push Amount (optional)" } + input type="number" id="push_btc" name="push_btc" placeholder="₿0" step="1" {} + } + button type="submit" { "Open Channel" } + " " + a href="/balance" { button type="button" { "Cancel" } } + } + }, + ); + + Ok(Html(layout("Open Channel", content).into_string())) +} + +pub async fn post_open_channel( + State(state): State, + Form(form): Form, +) -> Result { + tracing::info!( + "Web interface: Attempting to open channel to node_id={}, address={}:{}, amount_sats={}, push_btc={:?}", + form.node_id, + form.address, + form.port, + form.amount_sats, + form.push_btc + ); + + let pubkey = match PublicKey::from_str(&form.node_id) { + Ok(pk) => pk, + Err(e) => { + tracing::warn!("Web interface: Invalid node public key provided: {}", e); + let content = html! { + (error_message(&format!("Invalid node public key: {e}"))) + div class="card" { + a href="/channels/open" { button { "← Try Again" } } + } + }; + return Ok(Response::builder() + .status(StatusCode::BAD_REQUEST) + .header("content-type", "text/html") + .body(Body::from( + layout("Open Channel Error", content).into_string(), + )) + .unwrap()); + } + }; + + let socket_addr = match SocketAddress::from_str(&format!("{}:{}", form.address, form.port)) { + Ok(addr) => addr, + Err(e) => { + tracing::warn!("Web interface: Invalid address:port combination: {}", e); + let content = html! { + (error_message(&format!("Invalid address:port combination: {e}"))) + div class="card" { + a href="/channels/open" { button { "← Try Again" } } + } + }; + return Ok(Response::builder() + .status(StatusCode::BAD_REQUEST) + .header("content-type", "text/html") + .body(Body::from( + layout("Open Channel Error", content).into_string(), + )) + .unwrap()); + } + }; + + // First connect to the peer + tracing::info!( + "Web interface: Connecting to peer {} at {}", + pubkey, + socket_addr + ); + if let Err(e) = state.node.inner.connect(pubkey, socket_addr.clone(), true) { + tracing::error!("Web interface: Failed to connect to peer {}: {}", pubkey, e); + let content = html! { + (error_message(&format!("Failed to connect to peer: {e}"))) + div class="card" { + a href="/channels/open" { button { "← Try Again" } } + } + }; + return Ok(Response::builder() + .status(StatusCode::INTERNAL_SERVER_ERROR) + .header("content-type", "text/html") + .body(Body::from( + layout("Open Channel Error", content).into_string(), + )) + .unwrap()); + } + + // Then open the channel + tracing::info!( + "Web interface: Opening announced channel to {} with amount {} sats and push amount {:?} msats", + pubkey, + form.amount_sats, + form.push_btc.map(|a| a * 1000) + ); + let channel_result = state.node.inner.open_announced_channel( + pubkey, + socket_addr, + form.amount_sats, + form.push_btc.map(|a| a * 1000), + None, + ); + + let content = match channel_result { + Ok(user_channel_id) => { + tracing::info!( + "Web interface: Successfully initiated channel opening with user_channel_id={} to {}", + user_channel_id.0, + pubkey + ); + html! { + (success_message("Channel opening initiated successfully!")) + (info_card( + "Channel Details", + vec![ + ("Temporary Channel ID", user_channel_id.0.to_string()), + ("Node ID", form.node_id), + ("Amount", format_sats_as_btc(form.amount_sats)), + ("Push Amount", form.push_btc.map(format_sats_as_btc).unwrap_or_else(|| "₿ 0".to_string())), + ] + )) + div class="card" { + p { "The channel is now being opened. It may take some time for the channel to become active." } + a href="/balance" { button { "← Back to Lightning" } } + } + } + } + Err(e) => { + tracing::error!("Web interface: Failed to open channel to {}: {}", pubkey, e); + html! { + (error_message(&format!("Failed to open channel: {e}"))) + div class="card" { + a href="/channels/open" { button { "← Try Again" } } + } + } + } + }; + + Ok(Response::builder() + .header("content-type", "text/html") + .body(Body::from( + layout("Open Channel Result", content).into_string(), + )) + .unwrap()) +} + +pub async fn close_channel_page( + State(_state): State, + query: Query>, +) -> Result, StatusCode> { + let channel_id = query.get("channel_id").unwrap_or(&"".to_string()).clone(); + let node_id = query.get("node_id").unwrap_or(&"".to_string()).clone(); + + if channel_id.is_empty() || node_id.is_empty() { + let content = html! { + (error_message("Missing channel ID or node ID")) + div class="card" { + a href="/balance" { button { "← Back to Lightning" } } + } + }; + return Ok(Html(layout("Close Channel Error", content).into_string())); + } + + let content = form_card( + "Close Channel", + html! { + p { "Are you sure you want to close this channel?" } + div class="info-item" { + span class="info-label" { "User Channel ID:" } + span class="info-value" style="font-family: monospace; font-size: 0.85rem;" { (channel_id) } + } + div class="info-item" { + span class="info-label" { "Node ID:" } + span class="info-value" style="font-family: monospace; font-size: 0.85rem;" { (node_id) } + } + form method="post" action="/channels/close" style="margin-top: 1rem;" { + input type="hidden" name="channel_id" value=(channel_id) {} + input type="hidden" name="node_id" value=(node_id) {} + button type="submit" style="background: #dc3545;" { "Close Channel" } + " " + a href="/balance" { button type="button" { "Cancel" } } + } + }, + ); + + Ok(Html(layout("Close Channel", content).into_string())) +} + +pub async fn force_close_channel_page( + State(_state): State, + query: Query>, +) -> Result, StatusCode> { + let channel_id = query.get("channel_id").unwrap_or(&"".to_string()).clone(); + let node_id = query.get("node_id").unwrap_or(&"".to_string()).clone(); + + if channel_id.is_empty() || node_id.is_empty() { + let content = html! { + (error_message("Missing channel ID or node ID")) + div class="card" { + a href="/balance" { button { "← Back to Lightning" } } + } + }; + return Ok(Html( + layout("Force Close Channel Error", content).into_string(), + )); + } + + let content = form_card( + "Force Close Channel", + html! { + div style="border: 2px solid #d63384; background-color: rgba(214, 51, 132, 0.1); padding: 1rem; margin-bottom: 1rem; border-radius: 0.5rem;" { + h4 style="color: #d63384; margin: 0 0 0.5rem 0;" { "⚠️ Warning: Force Close" } + p style="color: #d63384; margin: 0; font-size: 0.9rem;" { + "Force close should NOT be used if normal close is preferred. " + "Force close will immediately broadcast the latest commitment transaction and may result in delayed fund recovery. " + "Only use this if the channel counterparty is unresponsive or there are other issues preventing normal closure." + } + } + p { "Are you sure you want to force close this channel?" } + div class="info-item" { + span class="info-label" { "User Channel ID:" } + span class="info-value" style="font-family: monospace; font-size: 0.85rem;" { (channel_id) } + } + div class="info-item" { + span class="info-label" { "Node ID:" } + span class="info-value" style="font-family: monospace; font-size: 0.85rem;" { (node_id) } + } + form method="post" action="/channels/force-close" style="margin-top: 1rem;" { + input type="hidden" name="channel_id" value=(channel_id) {} + input type="hidden" name="node_id" value=(node_id) {} + button type="submit" style="background: #d63384;" { "Force Close Channel" } + " " + a href="/balance" { button type="button" { "Cancel" } } + } + }, + ); + + Ok(Html(layout("Force Close Channel", content).into_string())) +} + +pub async fn post_close_channel( + State(state): State, + Form(form): Form, +) -> Result { + tracing::info!( + "Web interface: Attempting to close channel_id={} with node_id={}", + form.channel_id, + form.node_id + ); + + let node_pubkey = match PublicKey::from_str(&form.node_id) { + Ok(pk) => pk, + Err(e) => { + tracing::warn!( + "Web interface: Invalid node public key for channel close: {}", + e + ); + let content = html! { + (error_message(&format!("Invalid node public key: {e}"))) + div class="card" { + a href="/channels" { button { "← Back to Channels" } } + } + }; + return Ok(Response::builder() + .status(StatusCode::BAD_REQUEST) + .header("content-type", "text/html") + .body(Body::from( + layout("Close Channel Error", content).into_string(), + )) + .unwrap()); + } + }; + + let channel_id: u128 = match form.channel_id.parse() { + Ok(id) => id, + Err(e) => { + tracing::warn!("Web interface: Invalid channel ID for channel close: {}", e); + let content = html! { + (error_message(&format!("Invalid channel ID: {e}"))) + div class="card" { + a href="/channels" { button { "← Back to Channels" } } + } + }; + return Ok(Response::builder() + .status(StatusCode::BAD_REQUEST) + .header("content-type", "text/html") + .body(Body::from( + layout("Close Channel Error", content).into_string(), + )) + .unwrap()); + } + }; + + let user_channel_id = UserChannelId(channel_id); + tracing::info!( + "Web interface: Initiating cooperative close for channel {} with {}", + channel_id, + node_pubkey + ); + let close_result = state + .node + .inner + .close_channel(&user_channel_id, node_pubkey); + + let content = match close_result { + Ok(()) => { + tracing::info!( + "Web interface: Successfully initiated cooperative close for channel {} with {}", + channel_id, + node_pubkey + ); + html! { + (success_message("Channel closing initiated successfully!")) + div class="card" { + p { "The channel is now being closed. It may take some time for the closing transaction to be confirmed." } + a href="/balance" { button { "← Back to Lightning" } } + } + } + } + Err(e) => { + tracing::error!( + "Web interface: Failed to close channel {} with {}: {}", + channel_id, + node_pubkey, + e + ); + html! { + (error_message(&format!("Failed to close channel: {e}"))) + div class="card" { + a href="/balance" { button { "← Back to Lightning" } } + } + } + } + }; + + Ok(Response::builder() + .header("content-type", "text/html") + .body(Body::from( + layout("Close Channel Result", content).into_string(), + )) + .unwrap()) +} + +pub async fn post_force_close_channel( + State(state): State, + Form(form): Form, +) -> Result { + tracing::info!( + "Web interface: Attempting to FORCE CLOSE channel_id={} with node_id={}", + form.channel_id, + form.node_id + ); + + let node_pubkey = match PublicKey::from_str(&form.node_id) { + Ok(pk) => pk, + Err(e) => { + tracing::warn!( + "Web interface: Invalid node public key for force close: {}", + e + ); + let content = html! { + (error_message(&format!("Invalid node public key: {e}"))) + div class="card" { + a href="/channels" { button { "← Back to Channels" } } + } + }; + return Ok(Response::builder() + .status(StatusCode::BAD_REQUEST) + .header("content-type", "text/html") + .body(Body::from( + layout("Force Close Channel Error", content).into_string(), + )) + .unwrap()); + } + }; + + let channel_id: u128 = match form.channel_id.parse() { + Ok(id) => id, + Err(e) => { + tracing::warn!("Web interface: Invalid channel ID for force close: {}", e); + let content = html! { + (error_message(&format!("Invalid channel ID: {e}"))) + div class="card" { + a href="/channels" { button { "← Back to Channels" } } + } + }; + return Ok(Response::builder() + .status(StatusCode::BAD_REQUEST) + .header("content-type", "text/html") + .body(Body::from( + layout("Force Close Channel Error", content).into_string(), + )) + .unwrap()); + } + }; + + let user_channel_id = UserChannelId(channel_id); + tracing::warn!("Web interface: Initiating FORCE CLOSE for channel {} with {} - this will broadcast the latest commitment transaction", channel_id, node_pubkey); + let force_close_result = + state + .node + .inner + .force_close_channel(&user_channel_id, node_pubkey, None); + + let content = match force_close_result { + Ok(()) => { + tracing::info!( + "Web interface: Successfully initiated force close for channel {} with {}", + channel_id, + node_pubkey + ); + html! { + (success_message("Channel force close initiated successfully!")) + div class="card" style="border: 1px solid #d63384; background-color: rgba(214, 51, 132, 0.1);" { + h4 style="color: #d63384;" { "Force Close Complete" } + p { "The channel has been force closed. The latest commitment transaction has been broadcast to the network." } + p style="color: #d63384; font-size: 0.9rem;" { + "Note: Your funds may be subject to a time delay before they can be spent. " + "This delay depends on the channel configuration and may be several blocks." + } + a href="/balance" { button { "← Back to Lightning" } } + } + } + } + Err(e) => { + tracing::error!( + "Web interface: Failed to force close channel {} with {}: {}", + channel_id, + node_pubkey, + e + ); + html! { + (error_message(&format!("Failed to force close channel: {e}"))) + div class="card" { + a href="/balance" { button { "← Back to Lightning" } } + } + } + } + }; + + Ok(Response::builder() + .header("content-type", "text/html") + .body(Body::from( + layout("Force Close Channel Result", content).into_string(), + )) + .unwrap()) +} diff --git a/crates/cdk-ldk-node/src/web/handlers/dashboard.rs b/crates/cdk-ldk-node/src/web/handlers/dashboard.rs new file mode 100644 index 000000000..25aacaf31 --- /dev/null +++ b/crates/cdk-ldk-node/src/web/handlers/dashboard.rs @@ -0,0 +1,276 @@ +use axum::extract::State; +use axum::http::StatusCode; +use axum::response::Html; +use ldk_node::payment::{PaymentDirection, PaymentKind, PaymentStatus}; +use maud::html; + +use crate::web::handlers::AppState; +use crate::web::templates::{format_sats_as_btc, layout}; + +#[derive(Debug)] +pub struct UsageMetrics { + pub lightning_inflow_24h: u64, + pub lightning_outflow_24h: u64, + pub lightning_inflow_all_time: u64, + pub lightning_outflow_all_time: u64, + pub onchain_inflow_24h: u64, + pub onchain_outflow_24h: u64, + pub onchain_inflow_all_time: u64, + pub onchain_outflow_all_time: u64, +} + +/// Calculate usage metrics from payment history +fn calculate_usage_metrics(payments: &[ldk_node::payment::PaymentDetails]) -> UsageMetrics { + use std::time::{SystemTime, UNIX_EPOCH}; + + let now = SystemTime::now() + .duration_since(UNIX_EPOCH) + .unwrap_or_default() + .as_secs(); + let twenty_four_hours_ago = now.saturating_sub(24 * 60 * 60); + + let mut metrics = UsageMetrics { + lightning_inflow_24h: 0, + lightning_outflow_24h: 0, + lightning_inflow_all_time: 0, + lightning_outflow_all_time: 0, + onchain_inflow_24h: 0, + onchain_outflow_24h: 0, + onchain_inflow_all_time: 0, + onchain_outflow_all_time: 0, + }; + + for payment in payments { + if payment.status != PaymentStatus::Succeeded { + continue; + } + + let amount_sats = payment.amount_msat.unwrap_or(0) / 1000; + let is_recent = payment.latest_update_timestamp >= twenty_four_hours_ago; + + match &payment.kind { + PaymentKind::Bolt11 { .. } + | PaymentKind::Bolt12Offer { .. } + | PaymentKind::Bolt12Refund { .. } + | PaymentKind::Spontaneous { .. } + | PaymentKind::Bolt11Jit { .. } => match payment.direction { + PaymentDirection::Inbound => { + metrics.lightning_inflow_all_time += amount_sats; + if is_recent { + metrics.lightning_inflow_24h += amount_sats; + } + } + PaymentDirection::Outbound => { + metrics.lightning_outflow_all_time += amount_sats; + if is_recent { + metrics.lightning_outflow_24h += amount_sats; + } + } + }, + PaymentKind::Onchain { .. } => match payment.direction { + PaymentDirection::Inbound => { + metrics.onchain_inflow_all_time += amount_sats; + if is_recent { + metrics.onchain_inflow_24h += amount_sats; + } + } + PaymentDirection::Outbound => { + metrics.onchain_outflow_all_time += amount_sats; + if is_recent { + metrics.onchain_outflow_24h += amount_sats; + } + } + }, + } + } + + metrics +} + +pub async fn dashboard(State(state): State) -> Result, StatusCode> { + let node = &state.node.inner; + + let _node_id = node.node_id().to_string(); + let alias = node + .node_alias() + .map(|a| a.to_string()) + .unwrap_or_else(|| "No alias set".to_string()); + + let listening_addresses: Vec = state + .node + .inner + .announcement_addresses() + .as_ref() + .unwrap_or(&vec![]) + .iter() + .map(|a| a.to_string()) + .collect(); + + let (num_peers, num_connected_peers) = + node.list_peers() + .iter() + .fold((0, 0), |(mut peers, mut connected), p| { + if p.is_connected { + connected += 1; + } + peers += 1; + (peers, connected) + }); + + let (num_active_channels, num_inactive_channels) = + node.list_channels() + .iter() + .fold((0, 0), |(mut active, mut inactive), c| { + if c.is_usable { + active += 1; + } else { + inactive += 1; + } + (active, inactive) + }); + + let balances = node.list_balances(); + + // Calculate payment metrics for dashboard + let all_payments = node.list_payments_with_filter(|_| true); + let metrics = calculate_usage_metrics(&all_payments); + + let content = html! { + h2 style="text-align: center; margin-bottom: 3rem;" { "Dashboard" } + + // Balance Summary as metric cards + div class="card" { + h2 { "Balance Summary" } + div class="metrics-container" { + div class="metric-card" { + div class="metric-value" { (format_sats_as_btc(balances.total_lightning_balance_sats)) } + div class="metric-label" { "Lightning Balance" } + } + div class="metric-card" { + div class="metric-value" { (format_sats_as_btc(balances.total_onchain_balance_sats)) } + div class="metric-label" { "On-chain Balance" } + } + div class="metric-card" { + div class="metric-value" { (format_sats_as_btc(balances.spendable_onchain_balance_sats)) } + div class="metric-label" { "Spendable Balance" } + } + div class="metric-card" { + div class="metric-value" { (format_sats_as_btc(balances.total_lightning_balance_sats + balances.total_onchain_balance_sats)) } + div class="metric-label" { "Combined Total" } + } + } + } + + // Node Information - new layout based on Figma design + section class="node-info-section" { + div class="node-info-main-container" { + // Left side - Node avatar and info + div class="node-info-left" { + div class="node-avatar" { + img src="/static/images/nut.png" alt="Node Avatar" class="avatar-image"; + } + div class="node-details" { + h2 class="node-name" { (alias.clone()) } + p class="node-address" { + "Listening Address: " + (listening_addresses.first().unwrap_or(&"127.0.0.1:8090".to_string())) + } + } + } + + // Middle - Gray container with spinning globe animation + div class="node-content-box" { + div class="globe-container" { + svg aria-hidden="true" style="position: absolute; width: 0; height: 0; overflow: hidden;" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" { + defs { + symbol id="icon-world" viewBox="0 0 216 100" { + title { "world" } + g fill-rule="nonzero" { + path d="M48 94l-3-4-2-14c0-3-1-5-3-8-4-5-6-9-4-11l1-4 1-3c2-1 9 0 11 1l3 2 2 3 1 2 8 2c1 1 2 2 0 7-1 5-2 7-4 7l-2 3-2 4-2 3-2 1c-2 2-2 9 0 10v1l-3-2zM188 90l3-2h1l-4 2zM176 87h2l-1 1-1-1zM195 86l3-2-2 2h-1zM175 83l-1-2-2-1-6 1c-5 1-5 1-5-2l1-4 2-2 4-3c5-4 9-5 9-3 0 3 3 3 4 1s1-2 1 0l3 4c2 4 1 6-2 10-4 3-7 4-8 1zM100 80c-2-4-4-11-3-14l-1-6c-1-1-2-3-1-4 0-2-4-3-9-3-4 0-5 0-7-3-1-2-2-4-1-7l3-6 3-3c1-2 10-4 11-2l6 3 5-1c3 1 4 0 5-1s-1-2-2-2l-4-1c0-1 3-3 6-2 3 0 3 0 2-2-2-2-6-2-7 0l-2 2-1 2-3-2-3-3c-1 0-1 1 1 2l1 2-2-1c-4-3-6-2-8 1-2 2-4 3-5 1-1-1 0-4 2-4l2-2 1-2 3-2 3-2 2 1c3 0 7-3 5-4l-1-3h-1l-1 3-2 2h-1l-2-1c-2-1-2-1 1-4 5-4 6-4 11-3 4 1 4 1 2 2v1l3-1 6-1c5 0 6-1 5-2l2 1c1 2 2 2 2 1-2-4 12-7 14-4l11 1 29 3 1 2-3 3c-2 0-2 0-1 1l1 3h-2c-1-1-2-3-1-4h-4l-6 2c-1 1-1 1 2 2 3 2 4 6 1 8v3c1 3 0 3-3 0s-4-1-2 3c3 4 3 7-2 8-5 2-4 1-2 5 2 3 0 5-3 4l-2-1-2-2-1-1-1-1-2-2c-1-2-1-2-4 0-2 1-3 4-3 5-1 3-1 3-3 1l-2-4c0-2-1-3-2-3l-1-1-4-2-6-1-4-2c-1 1 3 4 5 4h2c1 1 0 2-1 4-3 2-7 4-8 3l-7-10 5 10c2 2 3 3 5 2 3 0 2 1-2 7-4 4-4 5-4 8 1 3 1 4-1 6l-2 3c0 2-6 9-8 9l-3-2zm22-51l-2-3-1-1v-1c-2 0-2 2-1 4 2 3 4 4 4 1z" {} + path d="M117 75c-1-2 0-6 2-7h2l-2 5c0 2-1 3-2 1zM186 64h-3c-2 0-6-3-5-5 1-1 6 1 7 3l2 3-2-1zM160 62h2c1 1 0 1-1 1l-1-1zM154 57l-1-2c2 2 3 1 2-2l-2-3 2 2 1 4 1 3v2l-3-4zM161 59c-1-1-1-2 1-4 3-3 4-3 4 0 0 4-2 6-5 4zM167 59l1-1 1 1-1 1-1-1zM176 59l1-1v2l-1-1zM141 52l1-1v2l-1-1zM170 52l1-1v2l-1-1zM32 50c-1-2-4-3-6-4-4-1-5-3-7-6l-3-5-2-2c-1-3-1-6 2-9 1-1 2-3 1-5 0-4-3-5-8-4H4l2-2 1-1 1-1 2-1c1-2 7-2 23-1 12 1 12 1 12-1h1c1 1 2 2 3 1l1 1-3 1c-2 0-8 4-8 5l2 1 2 3 4-3c3-4 4-4 5-3l3 1 1 2 1 2c3 0-1 2-4 2-2 0-2 0-2 2 1 1 0 2-2 2-4 1-12 9-12 12 0 2 0 2-1 1 0-2-2-3-6-2-3 0-4 1-4 3-2 4 0 6 3 4 3-1 3-1 2 1s-1 2 1 2l1 2 1 3 1 1-3-2zm8-24l1-1c0-1-4-3-5-2l1 1v2c-1 1-1 1 0 0h3zM167 47v-3l1 2c1 2 0 3-1 1z" {} + path d="M41 43h2l-1 1-1-1zM37 42v-1l2 1h-2zM16 38l1-1v2l-1-1zM172 32l2-3h1c1 2 0 4-3 4v-1zM173 26h2l-1 1-1-1zM56 22h2l-2 1v-1zM87 19l1-2 1 3-1 1-1-2zM85 19l1-1v1l-1 1v-1zM64 12l1-3c2 0-1-4-3-4s-2 0 0-1V3l-6 2c-3 1-3 1-2-1 2-1 4-2 15-2h14c0 2-6 7-10 9l-5 2-2 1-2-2zM53 12l1-1c2 0-1-3-3-3-2-1-1-1 1-1l4 2c2 1 2 1 1 3-2 1-4 2-4 0zM80 12l1-1 1 1-1 1-1-1zM36 8h-2V7c1-1 7 0 7 1h-5zM116 7l1-1v1l-1 1V7zM50 5h2l-1 1-1-1zM97 5l2-1c0-1 1-1 0 0l-2 1z" {} + } + } + symbol id="icon-repeated-world" viewBox="0 0 432 100" { + use href="#icon-world" x="0" {} + use href="#icon-world" x="189" {} + } + } + } + span class="world" { + span class="images" { + svg { use href="#icon-repeated-world" {} } + } + } + } + } + } + + // Right side - Connections metrics + aside class="node-metrics" { + div class="card" { + h3 { "Connections" } + div class="metrics-container" { + div class="metric-card" { + div class="metric-value" { (format!("{}/{}", num_connected_peers, num_peers)) } + div class="metric-label" { "Connected Peers" } + } + div class="metric-card" { + div class="metric-value" { (format!("{}/{}", num_active_channels, num_active_channels + num_inactive_channels)) } + div class="metric-label" { "Active Channels" } + } + } + } + } + } + + // Lightning Network Activity as metric cards + div class="card" { + h2 { "Lightning Network Activity" } + div class="metrics-container" { + div class="metric-card" { + div class="metric-value" { (format_sats_as_btc(metrics.lightning_inflow_24h)) } + div class="metric-label" { "24h LN Inflow" } + } + div class="metric-card" { + div class="metric-value" { (format_sats_as_btc(metrics.lightning_outflow_24h)) } + div class="metric-label" { "24h LN Outflow" } + } + div class="metric-card" { + div class="metric-value" { (format_sats_as_btc(metrics.lightning_inflow_all_time)) } + div class="metric-label" { "All-time LN Inflow" } + } + div class="metric-card" { + div class="metric-value" { (format_sats_as_btc(metrics.lightning_outflow_all_time)) } + div class="metric-label" { "All-time LN Outflow" } + } + } + } + + // On-chain Activity as metric cards + div class="card" { + h2 { "On-chain Activity" } + div class="metrics-container" { + div class="metric-card" { + div class="metric-value" { (format_sats_as_btc(metrics.onchain_inflow_24h)) } + div class="metric-label" { "24h On-chain Inflow" } + } + div class="metric-card" { + div class="metric-value" { (format_sats_as_btc(metrics.onchain_outflow_24h)) } + div class="metric-label" { "24h On-chain Outflow" } + } + div class="metric-card" { + div class="metric-value" { (format_sats_as_btc(metrics.onchain_inflow_all_time)) } + div class="metric-label" { "All-time On-chain Inflow" } + } + div class="metric-card" { + div class="metric-value" { (format_sats_as_btc(metrics.onchain_outflow_all_time)) } + div class="metric-label" { "All-time On-chain Outflow" } + } + } + + } + }; + + Ok(Html(layout("Dashboard", content).into_string())) +} diff --git a/crates/cdk-ldk-node/src/web/handlers/invoices.rs b/crates/cdk-ldk-node/src/web/handlers/invoices.rs new file mode 100644 index 000000000..7d181d546 --- /dev/null +++ b/crates/cdk-ldk-node/src/web/handlers/invoices.rs @@ -0,0 +1,293 @@ +use axum::body::Body; +use axum::extract::State; +use axum::http::StatusCode; +use axum::response::{Html, Response}; +use axum::Form; +use ldk_node::lightning_invoice::{Bolt11InvoiceDescription, Description}; +use maud::html; +use serde::Deserialize; + +use crate::web::handlers::utils::{deserialize_optional_f64, deserialize_optional_u32}; +use crate::web::handlers::AppState; +use crate::web::templates::{ + error_message, form_card, format_sats_as_btc, info_card, layout, success_message, +}; + +#[derive(Deserialize)] +pub struct CreateBolt11Form { + amount_btc: u64, + description: Option, + #[serde(deserialize_with = "deserialize_optional_u32")] + expiry_seconds: Option, +} + +#[derive(Deserialize)] +pub struct CreateBolt12Form { + #[serde(deserialize_with = "deserialize_optional_f64")] + amount_btc: Option, + description: Option, + #[serde(deserialize_with = "deserialize_optional_u32")] + expiry_seconds: Option, +} + +pub async fn invoices_page(State(_state): State) -> Result, StatusCode> { + let content = html! { + h2 style="text-align: center; margin-bottom: 3rem;" { "Invoices" } + div class="grid" { + (form_card( + "Create BOLT11 Invoice", + html! { + form method="post" action="/invoices/bolt11" { + div class="form-group" { + label for="amount_btc" { "Amount" } + input type="number" id="amount_btc" name="amount_btc" required placeholder="₿0" step="0.00000001" {} + } + div class="form-group" { + label for="description" { "Description (optional)" } + input type="text" id="description" name="description" placeholder="Payment for..." {} + } + div class="form-group" { + label for="expiry_seconds" { "Expiry (seconds, optional)" } + input type="number" id="expiry_seconds" name="expiry_seconds" placeholder="3600" {} + } + button type="submit" { "Create BOLT11 Invoice" } + } + } + )) + + (form_card( + "Create BOLT12 Offer", + html! { + form method="post" action="/invoices/bolt12" { + div class="form-group" { + label for="amount_btc" { "Amount (optional for variable amount)" } + input type="number" id="amount_btc" name="amount_btc" placeholder="₿0" step="0.00000001" {} + } + div class="form-group" { + label for="description" { "Description (optional)" } + input type="text" id="description" name="description" placeholder="Payment for..." {} + } + div class="form-group" { + label for="expiry_seconds" { "Expiry (seconds, optional)" } + input type="number" id="expiry_seconds" name="expiry_seconds" placeholder="3600" {} + } + button type="submit" { "Create BOLT12 Offer" } + } + } + )) + } + }; + + Ok(Html(layout("Create Invoices", content).into_string())) +} + +pub async fn post_create_bolt11( + State(state): State, + Form(form): Form, +) -> Result { + tracing::info!( + "Web interface: Creating BOLT11 invoice for amount={} sats, description={:?}, expiry={}s", + form.amount_btc, + form.description, + form.expiry_seconds.unwrap_or(3600) + ); + + // Handle optional description + let description_text = form.description.clone().unwrap_or_else(|| "".to_string()); + let description = if description_text.is_empty() { + // Use empty description for empty or missing description + match Description::new("".to_string()) { + Ok(desc) => Bolt11InvoiceDescription::Direct(desc), + Err(_) => { + // Fallback to a minimal valid description + let desc = Description::new(" ".to_string()).unwrap(); + Bolt11InvoiceDescription::Direct(desc) + } + } + } else { + match Description::new(description_text.clone()) { + Ok(desc) => Bolt11InvoiceDescription::Direct(desc), + Err(e) => { + tracing::warn!( + "Web interface: Invalid description for BOLT11 invoice: {}", + e + ); + let content = html! { + (error_message(&format!("Invalid description: {e}"))) + div class="card" { + a href="/invoices" { button { "← Try Again" } } + } + }; + return Ok(Response::builder() + .status(StatusCode::BAD_REQUEST) + .header("content-type", "text/html") + .body(Body::from( + layout("Create Invoice Error", content).into_string(), + )) + .unwrap()); + } + } + }; + + // Convert Bitcoin to millisatoshis + let amount_msats = form.amount_btc * 1_000; + + let expiry_seconds = form.expiry_seconds.unwrap_or(3600); + let invoice_result = + state + .node + .inner + .bolt11_payment() + .receive(amount_msats, &description, expiry_seconds); + + let content = match invoice_result { + Ok(invoice) => { + tracing::info!( + "Web interface: Successfully created BOLT11 invoice with payment_hash={}", + invoice.payment_hash() + ); + let current_time = std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .unwrap_or_default() + .as_secs(); + + let description_display = if description_text.is_empty() { + "None".to_string() + } else { + description_text.clone() + }; + + html! { + (success_message("BOLT11 Invoice created successfully!")) + (info_card( + "Invoice Details", + vec![ + ("Payment Hash", invoice.payment_hash().to_string()), + ("Amount", format_sats_as_btc(form.amount_btc)), + ("Description", description_display), + ("Expires At", format!("{}", current_time + expiry_seconds as u64)), + ] + )) + div class="card" { + h3 { "Invoice (copy this to share)" } + textarea readonly style="width: 100%; height: 150px; font-family: monospace; font-size: 0.8rem;" { + (invoice.to_string()) + } + } + div class="card" { + a href="/invoices" { button { "← Create Another Invoice" } } + } + } + } + Err(e) => { + tracing::error!("Web interface: Failed to create BOLT11 invoice: {}", e); + html! { + (error_message(&format!("Failed to create invoice: {e}"))) + div class="card" { + a href="/invoices" { button { "← Try Again" } } + } + } + } + }; + + Ok(Response::builder() + .header("content-type", "text/html") + .body(Body::from( + layout("BOLT11 Invoice Created", content).into_string(), + )) + .unwrap()) +} + +pub async fn post_create_bolt12( + State(state): State, + Form(form): Form, +) -> Result { + let expiry_seconds = form.expiry_seconds.unwrap_or(3600); + let description_text = form.description.unwrap_or_else(|| "".to_string()); + + tracing::info!( + "Web interface: Creating BOLT12 offer for amount={:?} btc, description={:?}, expiry={}s", + form.amount_btc, + description_text, + expiry_seconds + ); + + let offer_result = if let Some(amount_btc) = form.amount_btc { + // Convert Bitcoin to millisatoshis (1 BTC = 100,000,000,000 msats) + let amount_msats = (amount_btc * 100_000_000_000.0) as u64; + state.node.inner.bolt12_payment().receive( + amount_msats, + &description_text, + Some(expiry_seconds), + None, + ) + } else { + state + .node + .inner + .bolt12_payment() + .receive_variable_amount(&description_text, Some(expiry_seconds)) + }; + + let content = match offer_result { + Ok(offer) => { + tracing::info!( + "Web interface: Successfully created BOLT12 offer with offer_id={}", + offer.id() + ); + let current_time = std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .unwrap_or_default() + .as_secs(); + + let amount_display = form + .amount_btc + .map(|a| format_sats_as_btc((a * 100_000_000.0) as u64)) + .unwrap_or_else(|| "Variable amount".to_string()); + + let description_display = if description_text.is_empty() { + "None".to_string() + } else { + description_text + }; + + html! { + (success_message("BOLT12 Offer created successfully!")) + (info_card( + "Offer Details", + vec![ + ("Offer ID", offer.id().to_string()), + ("Amount", amount_display), + ("Description", description_display), + ("Expires At", format!("{}", current_time + expiry_seconds as u64)), + ] + )) + div class="card" { + h3 { "Offer (copy this to share)" } + textarea readonly style="width: 100%; height: 150px; font-family: monospace; font-size: 0.8rem;" { + (offer.to_string()) + } + } + div class="card" { + a href="/invoices" { button { "← Create Another Offer" } } + } + } + } + Err(e) => { + tracing::error!("Web interface: Failed to create BOLT12 offer: {}", e); + html! { + (error_message(&format!("Failed to create offer: {e}"))) + div class="card" { + a href="/invoices" { button { "← Try Again" } } + } + } + } + }; + + Ok(Response::builder() + .header("content-type", "text/html") + .body(Body::from( + layout("BOLT12 Offer Created", content).into_string(), + )) + .unwrap()) +} diff --git a/crates/cdk-ldk-node/src/web/handlers/lightning.rs b/crates/cdk-ldk-node/src/web/handlers/lightning.rs new file mode 100644 index 000000000..344b78b3a --- /dev/null +++ b/crates/cdk-ldk-node/src/web/handlers/lightning.rs @@ -0,0 +1,171 @@ +use axum::extract::State; +use axum::http::StatusCode; +use axum::response::Html; +use maud::html; + +use crate::web::handlers::AppState; +use crate::web::templates::{format_sats_as_btc, layout}; + +pub async fn balance_page(State(state): State) -> Result, StatusCode> { + let balances = state.node.inner.list_balances(); + let channels = state.node.inner.list_channels(); + + let (num_active_channels, num_inactive_channels) = + channels + .iter() + .fold((0, 0), |(mut active, mut inactive), c| { + if c.is_usable { + active += 1; + } else { + inactive += 1; + } + (active, inactive) + }); + + let content = if channels.is_empty() { + html! { + h2 style="text-align: center; margin-bottom: 3rem;" { "Lightning" } + + // Quick Actions section - matching dashboard style + div class="card" style="margin-bottom: 2rem;" { + h2 { "Quick Actions" } + div style="display: flex; gap: 1rem; margin-top: 1rem; flex-wrap: wrap;" { + a href="/channels/open" style="text-decoration: none; flex: 1; min-width: 200px;" { + button class="button-primary" style="width: 100%;" { "Open Channel" } + } + a href="/invoices" style="text-decoration: none; flex: 1; min-width: 200px;" { + button class="button-primary" style="width: 100%;" { "Create Invoice" } + } + a href="/payments/send" style="text-decoration: none; flex: 1; min-width: 200px;" { + button class="button-primary" style="width: 100%;" { "Make Lightning Payment" } + } + } + } + + // Balance Information as metric cards + div class="card" { + h2 { "Balance Information" } + div class="metrics-container" { + div class="metric-card" { + div class="metric-value" { (format_sats_as_btc(balances.total_lightning_balance_sats)) } + div class="metric-label" { "Lightning Balance" } + } + div class="metric-card" { + div class="metric-value" { (format!("{}", num_active_channels + num_inactive_channels)) } + div class="metric-label" { "Total Channels" } + } + div class="metric-card" { + div class="metric-value" { (format!("{}", num_active_channels)) } + div class="metric-label" { "Active Channels" } + } + div class="metric-card" { + div class="metric-value" { (format!("{}", num_inactive_channels)) } + div class="metric-label" { "Inactive Channels" } + } + } + } + + div class="card" { + p { "No channels found. Create your first channel to start using Lightning Network." } + } + } + } else { + html! { + h2 style="text-align: center; margin-bottom: 3rem;" { "Lightning" } + + // Quick Actions section - matching dashboard style + div class="card" style="margin-bottom: 2rem;" { + h2 { "Quick Actions" } + div style="display: flex; gap: 1rem; margin-top: 1rem; flex-wrap: wrap;" { + a href="/channels/open" style="text-decoration: none; flex: 1; min-width: 200px;" { + button class="button-primary" style="width: 100%;" { "Open Channel" } + } + a href="/invoices" style="text-decoration: none; flex: 1; min-width: 200px;" { + button class="button-primary" style="width: 100%;" { "Create Invoice" } + } + a href="/payments/send" style="text-decoration: none; flex: 1; min-width: 200px;" { + button class="button-primary" style="width: 100%;" { "Make Lightning Payment" } + } + } + } + + // Balance Information as metric cards + div class="card" { + h2 { "Balance Information" } + div class="metrics-container" { + div class="metric-card" { + div class="metric-value" { (format_sats_as_btc(balances.total_lightning_balance_sats)) } + div class="metric-label" { "Lightning Balance" } + } + div class="metric-card" { + div class="metric-value" { (format!("{}", num_active_channels + num_inactive_channels)) } + div class="metric-label" { "Total Channels" } + } + div class="metric-card" { + div class="metric-value" { (format!("{}", num_active_channels)) } + div class="metric-label" { "Active Channels" } + } + div class="metric-card" { + div class="metric-value" { (format!("{}", num_inactive_channels)) } + div class="metric-label" { "Inactive Channels" } + } + } + } + + div class="card" { + h2 { "Channel Details" } + + // Channels list + @for channel in &channels { + div class="channel-item" { + div class="channel-header" { + span class="channel-id" { "Channel ID: " (channel.channel_id.to_string()) } + @if channel.is_usable { + span class="status-badge status-active" { "Active" } + } @else { + span class="status-badge status-inactive" { "Inactive" } + } + } + div class="info-item" { + span class="info-label" { "Counterparty" } + span class="info-value" style="font-family: monospace; font-size: 0.85rem;" { (channel.counterparty_node_id.to_string()) } + } + @if let Some(short_channel_id) = channel.short_channel_id { + div class="info-item" { + span class="info-label" { "Short Channel ID" } + span class="info-value" { (short_channel_id.to_string()) } + } + } + div class="balance-info" { + div class="balance-item" { + div class="balance-amount" { (format_sats_as_btc(channel.outbound_capacity_msat / 1000)) } + div class="balance-label" { "Outbound" } + } + div class="balance-item" { + div class="balance-amount" { (format_sats_as_btc(channel.inbound_capacity_msat / 1000)) } + div class="balance-label" { "Inbound" } + } + div class="balance-item" { + div class="balance-amount" { (format_sats_as_btc(channel.channel_value_sats)) } + div class="balance-label" { "Total" } + } + } + @if channel.is_usable { + div style="margin-top: 1rem; display: flex; gap: 0.5rem;" { + a href=(format!("/channels/close?channel_id={}&node_id={}", channel.user_channel_id.0, channel.counterparty_node_id)) { + button style="background: #dc3545;" { "Close Channel" } + } + a href=(format!("/channels/force-close?channel_id={}&node_id={}", channel.user_channel_id.0, channel.counterparty_node_id)) { + button style="background: #d63384;" title="Force close should not be used if normal close is preferred. Force close will broadcast the latest commitment transaction immediately." { "Force Close" } + } + } + } + } + } + + } + } + }; + + Ok(Html(layout("Lightning", content).into_string())) +} diff --git a/crates/cdk-ldk-node/src/web/handlers/mod.rs b/crates/cdk-ldk-node/src/web/handlers/mod.rs new file mode 100644 index 000000000..c7794800e --- /dev/null +++ b/crates/cdk-ldk-node/src/web/handlers/mod.rs @@ -0,0 +1,17 @@ +pub mod channels; +pub mod dashboard; +pub mod invoices; +pub mod lightning; +pub mod onchain; +pub mod payments; +pub mod utils; + +// Re-export commonly used items +// Re-export handler functions +pub use channels::*; +pub use dashboard::*; +pub use invoices::*; +pub use lightning::*; +pub use onchain::*; +pub use payments::*; +pub use utils::AppState; diff --git a/crates/cdk-ldk-node/src/web/handlers/onchain.rs b/crates/cdk-ldk-node/src/web/handlers/onchain.rs new file mode 100644 index 000000000..ee34076fb --- /dev/null +++ b/crates/cdk-ldk-node/src/web/handlers/onchain.rs @@ -0,0 +1,479 @@ +use std::collections::HashMap; +use std::str::FromStr; + +use axum::body::Body; +use axum::extract::{Query, State}; +use axum::http::StatusCode; +use axum::response::{Html, Response}; +use axum::Form; +use ldk_node::bitcoin::Address; +use maud::html; +use serde::{Deserialize, Serialize}; + +use crate::web::handlers::utils::deserialize_optional_u64; +use crate::web::handlers::AppState; +use crate::web::templates::{ + error_message, form_card, format_sats_as_btc, info_card, layout, success_message, +}; + +#[derive(Deserialize, Serialize)] +pub struct SendOnchainActionForm { + address: String, + #[serde(deserialize_with = "deserialize_optional_u64")] + amount_sat: Option, + send_action: String, +} + +#[derive(Deserialize)] +pub struct ConfirmOnchainForm { + address: String, + amount_sat: Option, + send_action: String, + confirmed: Option, +} + +pub async fn get_new_address(State(state): State) -> Result, StatusCode> { + let address_result = state.node.inner.onchain_payment().new_address(); + + let content = match address_result { + Ok(address) => { + html! { + (success_message(&format!("New address generated: {address}"))) + div class="card" { + h2 { "Bitcoin Address" } + div class="info-item" { + span class="info-label" { "Address:" } + span class="info-value" style="font-family: monospace; font-size: 0.9rem;" { (address.to_string()) } + } + } + div class="card" { + a href="/onchain" { button { "← Back to On-chain" } } + " " + a href="/onchain/new-address" { button { "Generate Another Address" } } + } + } + } + Err(e) => { + html! { + (error_message(&format!("Failed to generate address: {e}"))) + div class="card" { + a href="/onchain" { button { "← Back to On-chain" } } + } + } + } + }; + + Ok(Html(layout("New Address", content).into_string())) +} + +pub async fn onchain_page( + State(state): State, + query: Query>, +) -> Result, StatusCode> { + let balances = state.node.inner.list_balances(); + let action = query + .get("action") + .map(|s| s.as_str()) + .unwrap_or("overview"); + + let mut content = html! { + h2 style="text-align: center; margin-bottom: 3rem;" { "On-chain" } + + // Quick Actions section - matching dashboard style + div class="card" style="margin-bottom: 2rem;" { + h2 { "Quick Actions" } + div style="display: flex; gap: 1rem; margin-top: 1rem; flex-wrap: wrap;" { + a href="/onchain?action=receive" style="text-decoration: none; flex: 1; min-width: 200px;" { + button class="button-primary" style="width: 100%;" { "Receive Bitcoin" } + } + a href="/onchain?action=send" style="text-decoration: none; flex: 1; min-width: 200px;" { + button class="button-primary" style="width: 100%;" { "Send Bitcoin" } + } + } + } + + // On-chain Balance as metric cards + div class="card" { + h2 { "On-chain Balance" } + div class="metrics-container" { + div class="metric-card" { + div class="metric-value" { (format_sats_as_btc(balances.total_onchain_balance_sats)) } + div class="metric-label" { "Total Balance" } + } + div class="metric-card" { + div class="metric-value" { (format_sats_as_btc(balances.spendable_onchain_balance_sats)) } + div class="metric-label" { "Spendable Balance" } + } + } + } + }; + + match action { + "send" => { + content = html! { + h2 style="text-align: center; margin-bottom: 3rem;" { "On-chain" } + + // Quick Actions section - matching dashboard style + div class="card" style="margin-bottom: 2rem;" { + h2 { "Quick Actions" } + div style="display: flex; gap: 1rem; margin-top: 1rem; flex-wrap: wrap;" { + a href="/onchain?action=receive" style="text-decoration: none; flex: 1; min-width: 200px;" { + button class="button-primary" style="width: 100%;" { "Receive Bitcoin" } + } + a href="/onchain?action=send" style="text-decoration: none; flex: 1; min-width: 200px;" { + button class="button-primary" style="width: 100%;" { "Send Bitcoin" } + } + } + } + + // Send form above balance + (form_card( + "Send On-chain Payment", + html! { + form method="post" action="/onchain/send" { + div class="form-group" { + label for="address" { "Recipient Address" } + input type="text" id="address" name="address" required placeholder="bc1..." {} + } + div class="form-group" { + label for="amount_sat" { "Amount (sats)" } + input type="number" id="amount_sat" name="amount_sat" placeholder="0" {} + } + input type="hidden" id="send_action" name="send_action" value="send" {} + div style="display: flex; justify-content: space-between; gap: 1rem; margin-top: 2rem;" { + a href="/onchain" { button type="button" { "Cancel" } } + div style="display: flex; gap: 0.5rem;" { + button type="submit" onclick="document.getElementById('send_action').value='send'" { "Send Payment" } + button type="submit" onclick="document.getElementById('send_action').value='send_all'; document.getElementById('amount_sat').value=''" { "Send All" } + } + } + } + } + )) + + // On-chain Balance as metric cards + div class="card" { + h2 { "On-chain Balance" } + div class="metrics-container" { + div class="metric-card" { + div class="metric-value" { (format_sats_as_btc(balances.total_onchain_balance_sats)) } + div class="metric-label" { "Total Balance" } + } + div class="metric-card" { + div class="metric-value" { (format_sats_as_btc(balances.spendable_onchain_balance_sats)) } + div class="metric-label" { "Spendable Balance" } + } + } + } + }; + } + "receive" => { + content = html! { + h2 style="text-align: center; margin-bottom: 3rem;" { "On-chain" } + + // Quick Actions section - matching dashboard style + div class="card" style="margin-bottom: 2rem;" { + h2 { "Quick Actions" } + div style="display: flex; gap: 1rem; margin-top: 1rem; flex-wrap: wrap;" { + a href="/onchain?action=receive" style="text-decoration: none; flex: 1; min-width: 200px;" { + button class="button-primary" style="width: 100%;" { "Receive Bitcoin" } + } + a href="/onchain?action=send" style="text-decoration: none; flex: 1; min-width: 200px;" { + button class="button-primary" style="width: 100%;" { "Send Bitcoin" } + } + } + } + + // Generate address form above balance + (form_card( + "Generate New Address", + html! { + form method="post" action="/onchain/new-address" { + p style="margin-bottom: 2rem;" { "Click the button below to generate a new Bitcoin address for receiving on-chain payments." } + div style="display: flex; justify-content: space-between; gap: 1rem;" { + a href="/onchain" { button type="button" { "Cancel" } } + button class="button-primary" type="submit" { "Generate New Address" } + } + } + } + )) + + // On-chain Balance as metric cards + div class="card" { + h2 { "On-chain Balance" } + div class="metrics-container" { + div class="metric-card" { + div class="metric-value" { (format_sats_as_btc(balances.total_onchain_balance_sats)) } + div class="metric-label" { "Total Balance" } + } + div class="metric-card" { + div class="metric-value" { (format_sats_as_btc(balances.spendable_onchain_balance_sats)) } + div class="metric-label" { "Spendable Balance" } + } + } + } + }; + } + _ => { + // Show overview with just the balance and quick actions at the top + } + } + + Ok(Html(layout("On-chain", content).into_string())) +} + +pub async fn post_send_onchain( + State(_state): State, + Form(form): Form, +) -> Result { + let encoded_form = + serde_urlencoded::to_string(&form).map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; + + Ok(Response::builder() + .status(StatusCode::FOUND) + .header("Location", format!("/onchain/confirm?{}", encoded_form)) + .body(Body::empty()) + .unwrap()) +} + +pub async fn onchain_confirm_page( + State(state): State, + query: Query, +) -> Result { + let form = query.0; + + // If user confirmed, execute the transaction + if form.confirmed.as_deref() == Some("true") { + return execute_onchain_transaction(State(state), form).await; + } + + // Validate address + let _address = match Address::from_str(&form.address) { + Ok(addr) => addr, + Err(e) => { + let content = html! { + (error_message(&format!("Invalid address: {e}"))) + div class="card" { + a href="/onchain?action=send" { button { "← Back" } } + } + }; + return Ok(Response::builder() + .status(StatusCode::BAD_REQUEST) + .header("content-type", "text/html") + .body(Body::from( + layout("Send On-chain Error", content).into_string(), + )) + .unwrap()); + } + }; + + let balances = state.node.inner.list_balances(); + let spendable_balance = balances.spendable_onchain_balance_sats; + + // Calculate transaction details + let (amount_to_send, is_send_all) = if form.send_action == "send_all" { + (spendable_balance, true) + } else { + let amount = form.amount_sat.unwrap_or(0); + if amount > spendable_balance { + let content = html! { + (error_message(&format!("Insufficient funds. Requested: {}, Available: {}", + format_sats_as_btc(amount), format_sats_as_btc(spendable_balance)))) + div class="card" { + a href="/onchain?action=send" { button { "← Back" } } + } + }; + return Ok(Response::builder() + .status(StatusCode::BAD_REQUEST) + .header("content-type", "text/html") + .body(Body::from( + layout("Send On-chain Error", content).into_string(), + )) + .unwrap()); + } + (amount, false) + }; + + let confirmation_url = if form.send_action == "send_all" { + format!( + "/onchain/confirm?address={}&send_action={}&confirmed=true", + urlencoding::encode(&form.address), + form.send_action + ) + } else { + format!( + "/onchain/confirm?address={}&amount_sat={}&send_action={}&confirmed=true", + urlencoding::encode(&form.address), + form.amount_sat.unwrap_or(0), + form.send_action + ) + }; + + let content = html! { + h2 style="text-align: center; margin-bottom: 3rem;" { "Confirm On-chain Transaction" } + + div class="card" style="border: 2px solid hsl(var(--primary)); background-color: hsl(var(--primary) / 0.05);" { + h2 { "⚠️ Transaction Confirmation" } + p style="color: hsl(var(--muted-foreground)); margin-bottom: 1.5rem;" { + "Please review the transaction details carefully before proceeding. This action cannot be undone." + } + } + + (info_card( + "Transaction Details", + vec![ + ("Recipient Address", form.address.clone()), + ("Amount to Send", if is_send_all { + format!("{} (All available funds)", format_sats_as_btc(amount_to_send)) + } else { + format_sats_as_btc(amount_to_send) + }), + ("Current Spendable Balance", format_sats_as_btc(spendable_balance)), + ] + )) + + @if is_send_all { + div class="card" style="border: 1px solid hsl(32.6 75.4% 55.1%); background-color: hsl(32.6 75.4% 55.1% / 0.1);" { + h3 style="color: hsl(32.6 75.4% 55.1%);" { "Send All Notice" } + p style="color: hsl(32.6 75.4% 55.1%);" { + "This transaction will send all available funds to the recipient address. " + "Network fees will be deducted from the total amount automatically." + } + } + } + + div class="card" { + div style="display: flex; justify-content: space-between; gap: 1rem; margin-top: 2rem;" { + a href="/onchain?action=send" { + button type="button" class="button-secondary" { "← Cancel" } + } + div style="display: flex; gap: 0.5rem;" { + a href=(confirmation_url) { + button class="button-primary" { + "✓ Confirm & Send Transaction" + } + } + } + } + } + }; + + Ok(Response::builder() + .header("content-type", "text/html") + .body(Body::from( + layout("Confirm Transaction", content).into_string(), + )) + .unwrap()) +} + +async fn execute_onchain_transaction( + State(state): State, + form: ConfirmOnchainForm, +) -> Result { + tracing::info!( + "Web interface: Executing on-chain transaction to address={}, send_action={}, amount_sat={:?}", + form.address, + form.send_action, + form.amount_sat + ); + + let address = match Address::from_str(&form.address) { + Ok(addr) => addr, + Err(e) => { + tracing::warn!( + "Web interface: Invalid address for on-chain transaction: {}", + e + ); + let content = html! { + (error_message(&format!("Invalid address: {e}"))) + div class="card" { + a href="/onchain" { button { "← Back" } } + } + }; + return Ok(Response::builder() + .status(StatusCode::BAD_REQUEST) + .header("content-type", "text/html") + .body(Body::from( + layout("Send On-chain Error", content).into_string(), + )) + .unwrap()); + } + }; + + // Handle send all action + let txid_result = if form.send_action == "send_all" { + tracing::info!( + "Web interface: Sending all available funds to {}", + form.address + ); + state.node.inner.onchain_payment().send_all_to_address( + address.assume_checked_ref(), + false, + None, + ) + } else { + let amount_sats = form.amount_sat.ok_or(StatusCode::BAD_REQUEST)?; + tracing::info!( + "Web interface: Sending {} sats to {}", + amount_sats, + form.address + ); + state.node.inner.onchain_payment().send_to_address( + address.assume_checked_ref(), + amount_sats, + None, + ) + }; + + let content = match txid_result { + Ok(txid) => { + if form.send_action == "send_all" { + tracing::info!( + "Web interface: Successfully sent all available funds, txid={}", + txid + ); + } else { + tracing::info!( + "Web interface: Successfully sent {} sats, txid={}", + form.amount_sat.unwrap_or(0), + txid + ); + } + let amount = form.amount_sat; + html! { + (success_message("Transaction sent successfully!")) + (info_card( + "Transaction Details", + vec![ + ("Transaction ID", txid.to_string()), + ("Amount", if form.send_action == "send_all" { + format!("{} (All available funds)", format_sats_as_btc(amount.unwrap_or(0))) + } else { + format_sats_as_btc(form.amount_sat.unwrap_or(0)) + }), + ("Recipient", form.address), + ] + )) + div class="card" { + a href="/onchain" { button { "← Back to On-chain" } } + } + } + } + Err(e) => { + tracing::error!("Web interface: Failed to send on-chain transaction: {}", e); + html! { + (error_message(&format!("Failed to send payment: {e}"))) + div class="card" { + a href="/onchain" { button { "← Try Again" } } + } + } + } + }; + + Ok(Response::builder() + .header("content-type", "text/html") + .body(Body::from( + layout("Send On-chain Result", content).into_string(), + )) + .unwrap()) +} diff --git a/crates/cdk-ldk-node/src/web/handlers/payments.rs b/crates/cdk-ldk-node/src/web/handlers/payments.rs new file mode 100644 index 000000000..343c7999d --- /dev/null +++ b/crates/cdk-ldk-node/src/web/handlers/payments.rs @@ -0,0 +1,615 @@ +use std::str::FromStr; + +use axum::body::Body; +use axum::extract::{Query, State}; +use axum::http::StatusCode; +use axum::response::{Html, Response}; +use axum::Form; +use cdk_common::util::hex; +use ldk_node::lightning::offers::offer::Offer; +use ldk_node::lightning_invoice::Bolt11Invoice; +use ldk_node::payment::{PaymentDirection, PaymentKind, PaymentStatus}; +use maud::html; +use serde::Deserialize; + +use crate::web::handlers::utils::{deserialize_optional_u64, get_paginated_payments_streaming}; +use crate::web::handlers::AppState; +use crate::web::templates::{ + error_message, form_card, format_msats_as_btc, format_sats_as_btc, info_card, layout, + payment_list_item, success_message, +}; + +#[derive(Deserialize)] +pub struct PaymentsQuery { + filter: Option, + page: Option, + per_page: Option, +} + +#[derive(Debug, Deserialize)] +pub struct PayBolt11Form { + invoice: String, + #[serde(deserialize_with = "deserialize_optional_u64")] + amount_btc: Option, +} + +#[derive(Deserialize)] +pub struct PayBolt12Form { + offer: String, + #[serde(deserialize_with = "deserialize_optional_u64")] + amount_btc: Option, +} + +pub async fn payments_page( + State(state): State, + query: Query, +) -> Result, StatusCode> { + let filter = query.filter.as_deref().unwrap_or("all"); + let page = query.page.unwrap_or(1).max(1); + let per_page = query.per_page.unwrap_or(25).clamp(10, 100); // Limit between 10-100 items per page + + // Use efficient pagination function + let (current_page_payments, total_count) = get_paginated_payments_streaming( + &state.node.inner, + filter, + ((page - 1) * per_page) as usize, + per_page as usize, + ); + + // Calculate pagination + let total_pages = ((total_count as f64) / (per_page as f64)).ceil() as u32; + let start_index = ((page - 1) * per_page) as usize; + let end_index = (start_index + per_page as usize).min(total_count); + + // Helper function to build URL with pagination params + let build_url = |new_page: u32, new_filter: &str, new_per_page: u32| -> String { + let mut params = vec![]; + if new_filter != "all" { + params.push(format!("filter={}", new_filter)); + } + if new_page != 1 { + params.push(format!("page={}", new_page)); + } + if new_per_page != 25 { + params.push(format!("per_page={}", new_per_page)); + } + + if params.is_empty() { + "/payments".to_string() + } else { + format!("/payments?{}", params.join("&")) + } + }; + + let content = html! { + h2 style="text-align: center; margin-bottom: 3rem;" { "Payments" } + div class="card" { + div class="payment-list-header" { + div { + h2 { "Payment History" } + @if total_count > 0 { + p style="margin: 0.25rem 0 0 0; color: #666; font-size: 0.9rem;" { + "Showing " (start_index + 1) " to " (end_index) " of " (total_count) " payments" + } + } + } + div class="payment-filter-tabs" { + a href=(build_url(1, "all", per_page)) class=(if filter == "all" { "payment-filter-tab active" } else { "payment-filter-tab" }) { "All" } + a href=(build_url(1, "incoming", per_page)) class=(if filter == "incoming" { "payment-filter-tab active" } else { "payment-filter-tab" }) { "Incoming" } + a href=(build_url(1, "outgoing", per_page)) class=(if filter == "outgoing" { "payment-filter-tab active" } else { "payment-filter-tab" }) { "Outgoing" } + } + } + + // Payment list (no metrics here) + @if current_page_payments.is_empty() { + @if total_count == 0 { + p { "No payments found." } + } @else { + p { "No payments found on this page. " + a href=(build_url(1, filter, per_page)) { "Go to first page" } + } + } + } @else { + @for payment in ¤t_page_payments { + @let direction_str = match payment.direction { + PaymentDirection::Inbound => "Inbound", + PaymentDirection::Outbound => "Outbound", + }; + + @let status_str = match payment.status { + PaymentStatus::Pending => "Pending", + PaymentStatus::Succeeded => "Succeeded", + PaymentStatus::Failed => "Failed", + }; + + @let amount_str = payment.amount_msat.map(format_msats_as_btc).unwrap_or_else(|| "Unknown".to_string()); + + @let (payment_hash, description, payment_type, preimage) = match &payment.kind { + PaymentKind::Bolt11 { hash, preimage, .. } => { + (Some(hash.to_string()), None::, "BOLT11", preimage.map(|p| p.to_string())) + }, + PaymentKind::Bolt12Offer { hash, offer_id, preimage, .. } => { + // For BOLT12, we can use either the payment hash or offer ID + let identifier = hash.map(|h| h.to_string()).unwrap_or_else(|| offer_id.to_string()); + (Some(identifier), None::, "BOLT12", preimage.map(|p| p.to_string())) + }, + PaymentKind::Bolt12Refund { hash, preimage, .. } => { + (hash.map(|h| h.to_string()), None::, "BOLT12", preimage.map(|p| p.to_string())) + }, + PaymentKind::Spontaneous { hash, preimage, .. } => { + (Some(hash.to_string()), None::, "Spontaneous", preimage.map(|p| p.to_string())) + }, + PaymentKind::Onchain { txid, .. } => { + (Some(txid.to_string()), None::, "On-chain", None) + }, + PaymentKind::Bolt11Jit { hash, .. } => { + (Some(hash.to_string()), None::, "BOLT11 JIT", None) + }, + }; + + (payment_list_item( + &payment.id.to_string(), + direction_str, + status_str, + &amount_str, + payment_hash.as_deref(), + description.as_deref(), + Some(payment.latest_update_timestamp), // Use the actual timestamp + payment_type, + preimage.as_deref(), + )) + } + } + + // Pagination controls (bottom) + @if total_pages > 1 { + div class="pagination-controls" style="margin-top: 2rem; padding-top: 1rem; border-top: 1px solid #eee;" { + div class="pagination" style="display: flex; justify-content: center; align-items: center; gap: 0.5rem;" { + // Previous page + @if page > 1 { + a href=(build_url(page - 1, filter, per_page)) class="pagination-btn" { "← Previous" } + } @else { + span class="pagination-btn disabled" { "← Previous" } + } + + // Page numbers + @let start_page = (page.saturating_sub(2)).max(1); + @let end_page = (page + 2).min(total_pages); + + @if start_page > 1 { + a href=(build_url(1, filter, per_page)) class="pagination-number" { "1" } + @if start_page > 2 { + span class="pagination-ellipsis" { "..." } + } + } + + @for p in start_page..=end_page { + @if p == page { + span class="pagination-number active" { (p) } + } @else { + a href=(build_url(p, filter, per_page)) class="pagination-number" { (p) } + } + } + + @if end_page < total_pages { + @if end_page < total_pages - 1 { + span class="pagination-ellipsis" { "..." } + } + a href=(build_url(total_pages, filter, per_page)) class="pagination-number" { (total_pages) } + } + + // Next page + @if page < total_pages { + a href=(build_url(page + 1, filter, per_page)) class="pagination-btn" { "Next →" } + } @else { + span class="pagination-btn disabled" { "Next →" } + } + } + } + } + + // Compact per-page selector integrated with pagination + @if total_count > 0 { + div class="per-page-selector" { + label for="per-page" { "Show:" } + select id="per-page" onchange="changePage()" { + option value="10" selected[per_page == 10] { "10" } + option value="25" selected[per_page == 25] { "25" } + option value="50" selected[per_page == 50] { "50" } + option value="100" selected[per_page == 100] { "100" } + } + span { "per page" } + } + } + } + + // JavaScript for per-page selector + script { + "function changePage() { + const perPageSelect = document.getElementById('per-page'); + const newPerPage = perPageSelect.value; + const currentUrl = new URL(window.location); + currentUrl.searchParams.set('per_page', newPerPage); + currentUrl.searchParams.set('page', '1'); // Reset to first page when changing per_page + window.location.href = currentUrl.toString(); + }" + } + }; + + Ok(Html(layout("Payment History", content).into_string())) +} + +pub async fn send_payments_page( + State(_state): State, +) -> Result, StatusCode> { + let content = html! { + h2 style="text-align: center; margin-bottom: 3rem;" { "Send Payment" } + div class="grid" { + (form_card( + "Pay BOLT11 Invoice", + html! { + form method="post" action="/payments/bolt11" { + div class="form-group" { + label for="invoice" { "BOLT11 Invoice" } + textarea id="invoice" name="invoice" required placeholder="lnbc..." style="height: 120px;" {} + } + div class="form-group" { + label for="amount_btc" { "Amount Override (optional)" } + input type="number" id="amount_btc" name="amount_btc" placeholder="Leave empty to use invoice amount" step="1" {} + } + button type="submit" { "Pay BOLT11 Invoice" } + } + } + )) + + (form_card( + "Pay BOLT12 Offer", + html! { + form method="post" action="/payments/bolt12" { + div class="form-group" { + label for="offer" { "BOLT12 Offer" } + textarea id="offer" name="offer" required placeholder="lno..." style="height: 120px;" {} + } + div class="form-group" { + label for="amount_btc" { "Amount (required for variable amount offers)" } + input type="number" id="amount_btc" name="amount_btc" placeholder="Required for variable amount offers, ignored for fixed amount offers" step="1" {} + } + button type="submit" { "Pay BOLT12 Offer" } + } + } + )) + } + + div class="card" { + h3 { "Payment History" } + a href="/payments" { button { "View All Payments" } } + } + }; + + Ok(Html(layout("Send Payments", content).into_string())) +} + +pub async fn post_pay_bolt11( + State(state): State, + Form(form): Form, +) -> Result { + let invoice = match Bolt11Invoice::from_str(form.invoice.trim()) { + Ok(inv) => inv, + Err(e) => { + tracing::warn!("Web interface: Invalid BOLT11 invoice provided: {}", e); + let content = html! { + (error_message(&format!("Invalid BOLT11 invoice: {e}"))) + div class="card" { + a href="/payments" { button { "← Try Again" } } + } + }; + return Ok(Response::builder() + .status(StatusCode::BAD_REQUEST) + .header("content-type", "text/html") + .body(Body::from(layout("Payment Error", content).into_string())) + .unwrap()); + } + }; + + tracing::info!( + "Web interface: Attempting to pay BOLT11 invoice payment_hash={}, amount_override={:?}", + invoice.payment_hash(), + form.amount_btc + ); + + let payment_id = if let Some(amount_btc) = form.amount_btc { + // Convert Bitcoin to millisatoshis + let amount_msats = amount_btc * 1000; + state + .node + .inner + .bolt11_payment() + .send_using_amount(&invoice, amount_msats, None) + } else { + state.node.inner.bolt11_payment().send(&invoice, None) + }; + + let payment_id = match payment_id { + Ok(id) => { + tracing::info!( + "Web interface: BOLT11 payment initiated with payment_id={}", + hex::encode(id.0) + ); + id + } + Err(e) => { + tracing::error!("Web interface: Failed to initiate BOLT11 payment: {}", e); + let content = html! { + (error_message(&format!("Failed to initiate payment: {e}"))) + div class="card" { + a href="/payments" { button { "← Try Again" } } + } + }; + return Ok(Response::builder() + .status(StatusCode::INTERNAL_SERVER_ERROR) + .header("content-type", "text/html") + .body(Body::from(layout("Payment Error", content).into_string())) + .unwrap()); + } + }; + + // Wait for payment to complete (max 10 seconds) + let start = std::time::Instant::now(); + let timeout = std::time::Duration::from_secs(10); + + let payment_result = loop { + if let Some(details) = state.node.inner.payment(&payment_id) { + match details.status { + PaymentStatus::Succeeded => { + tracing::info!( + "Web interface: BOLT11 payment succeeded for payment_hash={}", + invoice.payment_hash() + ); + break Ok(details); + } + PaymentStatus::Failed => { + tracing::error!( + "Web interface: BOLT11 payment failed for payment_hash={}", + invoice.payment_hash() + ); + break Err("Payment failed".to_string()); + } + PaymentStatus::Pending => { + if start.elapsed() > timeout { + tracing::warn!( + "Web interface: BOLT11 payment timeout for payment_hash={}", + invoice.payment_hash() + ); + break Err("Payment is still pending after timeout".to_string()); + } + tokio::time::sleep(std::time::Duration::from_millis(100)).await; + continue; + } + } + } else { + break Err("Payment not found".to_string()); + } + }; + + let content = match payment_result { + Ok(details) => { + let (preimage, fee_msats) = match details.kind { + PaymentKind::Bolt11 { + hash: _, + preimage, + secret: _, + } => ( + preimage.map(|p| p.to_string()).unwrap_or_default(), + details.fee_paid_msat.unwrap_or(0), + ), + _ => (String::new(), 0), + }; + + html! { + (success_message("Payment succeeded!")) + (info_card( + "Payment Details", + vec![ + ("Payment Hash", invoice.payment_hash().to_string()), + ("Payment Preimage", preimage), + ("Fee Paid", format_msats_as_btc(fee_msats)), + ("Amount", form.amount_btc.map(|_a| format_sats_as_btc(details.amount_msat.unwrap_or(1000) / 1000)).unwrap_or_default()), + ] + )) + div class="card" { + a href="/payments" { button { "← Make Another Payment" } } + } + } + } + Err(error) => { + html! { + (error_message(&format!("Payment failed: {error}"))) + div class="card" { + a href="/payments" { button { "← Try Again" } } + } + } + } + }; + + Ok(Response::builder() + .header("content-type", "text/html") + .body(Body::from(layout("Payment Result", content).into_string())) + .unwrap()) +} + +pub async fn post_pay_bolt12( + State(state): State, + Form(form): Form, +) -> Result { + let offer = match Offer::from_str(form.offer.trim()) { + Ok(offer) => offer, + Err(e) => { + tracing::warn!("Web interface: Invalid BOLT12 offer provided: {:?}", e); + let content = html! { + (error_message(&format!("Invalid BOLT12 offer: {e:?}"))) + div class="card" { + a href="/payments" { button { "← Try Again" } } + } + }; + return Ok(Response::builder() + .status(StatusCode::BAD_REQUEST) + .header("content-type", "text/html") + .body(Body::from(layout("Payment Error", content).into_string())) + .unwrap()); + } + }; + + tracing::info!( + "Web interface: Attempting to pay BOLT12 offer offer_id={}, amount_override={:?}", + offer.id(), + form.amount_btc + ); + + // Determine payment method based on offer type and user input + let payment_id = match offer.amount() { + Some(_) => { + // Fixed amount offer - use send() method, ignore user input amount + state.node.inner.bolt12_payment().send(&offer, None, None) + } + None => { + // Variable amount offer - requires user to specify amount via send_using_amount() + let amount_btc = match form.amount_btc { + Some(amount) => amount, + None => { + tracing::warn!("Web interface: Amount required for variable amount BOLT12 offer but not provided"); + let content = html! { + (error_message("Amount is required for variable amount offers. This offer does not have a fixed amount, so you must specify how much you want to pay.")) + div class="card" { + a href="/payments" { button { "← Try Again" } } + } + }; + return Ok(Response::builder() + .status(StatusCode::BAD_REQUEST) + .header("content-type", "text/html") + .body(Body::from(layout("Payment Error", content).into_string())) + .unwrap()); + } + }; + let amount_msats = amount_btc * 1_000; + state + .node + .inner + .bolt12_payment() + .send_using_amount(&offer, amount_msats, None, None) + } + }; + + let payment_id = match payment_id { + Ok(id) => { + tracing::info!( + "Web interface: BOLT12 payment initiated with payment_id={}", + hex::encode(id.0) + ); + id + } + Err(e) => { + tracing::error!("Web interface: Failed to initiate BOLT12 payment: {}", e); + let content = html! { + (error_message(&format!("Failed to initiate payment: {e}"))) + div class="card" { + a href="/payments" { button { "← Try Again" } } + } + }; + return Ok(Response::builder() + .status(StatusCode::INTERNAL_SERVER_ERROR) + .header("content-type", "text/html") + .body(Body::from(layout("Payment Error", content).into_string())) + .unwrap()); + } + }; + + // Wait for payment to complete (max 10 seconds) + let start = std::time::Instant::now(); + let timeout = std::time::Duration::from_secs(10); + + let payment_result = loop { + if let Some(details) = state.node.inner.payment(&payment_id) { + match details.status { + PaymentStatus::Succeeded => { + tracing::info!( + "Web interface: BOLT12 payment succeeded for offer_id={}", + offer.id() + ); + break Ok(details); + } + PaymentStatus::Failed => { + tracing::error!( + "Web interface: BOLT12 payment failed for offer_id={}", + offer.id() + ); + break Err("Payment failed".to_string()); + } + PaymentStatus::Pending => { + if start.elapsed() > timeout { + tracing::warn!( + "Web interface: BOLT12 payment timeout for offer_id={}", + offer.id() + ); + break Err("Payment is still pending after timeout".to_string()); + } + tokio::time::sleep(std::time::Duration::from_millis(100)).await; + continue; + } + } + } else { + break Err("Payment not found".to_string()); + } + }; + + let content = match payment_result { + Ok(details) => { + let (payment_hash, preimage, fee_msats) = match details.kind { + PaymentKind::Bolt12Offer { + hash, + preimage, + secret: _, + offer_id: _, + payer_note: _, + quantity: _, + } => ( + hash.map(|h| h.to_string()).unwrap_or_default(), + preimage.map(|p| p.to_string()).unwrap_or_default(), + details.fee_paid_msat.unwrap_or(0), + ), + _ => (String::new(), String::new(), 0), + }; + + html! { + (success_message("Payment succeeded!")) + (info_card( + "Payment Details", + vec![ + ("Payment Hash", payment_hash), + ("Payment Preimage", preimage), + ("Fee Paid", format_msats_as_btc(fee_msats)), + ("Amount Paid", form.amount_btc.map(format_sats_as_btc).unwrap_or_else(|| { + // If no amount was specified in the form, show the actual amount from the payment details + details.amount_msat.map(format_msats_as_btc).unwrap_or_else(|| "Unknown".to_string()) + })), + ] + )) + div class="card" { + a href="/payments" { button { "← Make Another Payment" } } + } + } + } + Err(error) => { + html! { + (error_message(&format!("Payment failed: {error}"))) + div class="card" { + a href="/payments" { button { "← Try Again" } } + } + } + } + }; + + Ok(Response::builder() + .header("content-type", "text/html") + .body(Body::from(layout("Payment Result", content).into_string())) + .unwrap()) +} diff --git a/crates/cdk-ldk-node/src/web/handlers/utils.rs b/crates/cdk-ldk-node/src/web/handlers/utils.rs new file mode 100644 index 000000000..c4f2dbed2 --- /dev/null +++ b/crates/cdk-ldk-node/src/web/handlers/utils.rs @@ -0,0 +1,91 @@ +use std::sync::Arc; + +use ldk_node::payment::PaymentDirection; +use serde::Deserialize; + +use crate::CdkLdkNode; + +#[derive(Clone)] +pub struct AppState { + pub node: Arc, +} + +// Custom deserializer for optional u32 that handles empty strings +pub fn deserialize_optional_u32<'de, D>(deserializer: D) -> Result, D::Error> +where + D: serde::Deserializer<'de>, +{ + let opt = Option::::deserialize(deserializer)?; + match opt.as_deref() { + None | Some("") => Ok(None), + Some(s) => s.parse::().map(Some).map_err(serde::de::Error::custom), + } +} + +// Custom deserializer for optional u64 that handles empty strings +pub fn deserialize_optional_u64<'de, D>(deserializer: D) -> Result, D::Error> +where + D: serde::Deserializer<'de>, +{ + let opt = Option::::deserialize(deserializer)?; + match opt.as_deref() { + None | Some("") => Ok(None), + Some(s) => s.parse::().map(Some).map_err(serde::de::Error::custom), + } +} + +// Custom deserializer for optional f64 that handles empty strings +pub fn deserialize_optional_f64<'de, D>(deserializer: D) -> Result, D::Error> +where + D: serde::Deserializer<'de>, +{ + let opt = Option::::deserialize(deserializer)?; + match opt.as_deref() { + None | Some("") => Ok(None), + Some(s) => s.parse::().map(Some).map_err(serde::de::Error::custom), + } +} + +/// Get paginated payments with efficient filtering and sorting +pub fn get_paginated_payments_streaming( + node: &ldk_node::Node, + filter: &str, + skip: usize, + take: usize, +) -> (Vec, usize) { + // Create filter predicate - note LDK expects &&PaymentDetails + let filter_fn = match filter { + "incoming" => { + |p: &&ldk_node::payment::PaymentDetails| p.direction == PaymentDirection::Inbound + } + "outgoing" => { + |p: &&ldk_node::payment::PaymentDetails| p.direction == PaymentDirection::Outbound + } + _ => |_: &&ldk_node::payment::PaymentDetails| true, + }; + + // Get filtered payments from LDK + let filtered_payments = node.list_payments_with_filter(filter_fn); + + // Create sorted index to avoid cloning payments during sort + let mut time_indexed: Vec<_> = filtered_payments + .iter() + .enumerate() + .map(|(idx, payment)| (payment.latest_update_timestamp, idx)) + .collect(); + + // Sort by timestamp (newest first) + time_indexed.sort_unstable_by(|a, b| b.0.cmp(&a.0)); + + let total_count = time_indexed.len(); + + // Extract only the payments we need for this page + let page_payments: Vec<_> = time_indexed + .into_iter() + .skip(skip) + .take(take) + .map(|(_, idx)| filtered_payments[idx].clone()) + .collect(); + + (page_payments, total_count) +} diff --git a/crates/cdk-ldk-node/src/web/mod.rs b/crates/cdk-ldk-node/src/web/mod.rs new file mode 100644 index 000000000..f182a9a9f --- /dev/null +++ b/crates/cdk-ldk-node/src/web/mod.rs @@ -0,0 +1,6 @@ +pub mod handlers; +pub mod server; +pub mod static_files; +pub mod templates; + +pub use server::WebServer; diff --git a/crates/cdk-ldk-node/src/web/server.rs b/crates/cdk-ldk-node/src/web/server.rs new file mode 100644 index 000000000..300db0d4e --- /dev/null +++ b/crates/cdk-ldk-node/src/web/server.rs @@ -0,0 +1,78 @@ +use std::net::SocketAddr; +use std::sync::Arc; + +use axum::routing::{get, post}; +use axum::Router; +use tower::ServiceBuilder; +use tower_http::cors::CorsLayer; + +use crate::web::handlers::{ + balance_page, channels_page, close_channel_page, dashboard, force_close_channel_page, + get_new_address, invoices_page, onchain_confirm_page, onchain_page, open_channel_page, + payments_page, post_close_channel, post_create_bolt11, post_create_bolt12, + post_force_close_channel, post_open_channel, post_pay_bolt11, post_pay_bolt12, + post_send_onchain, send_payments_page, AppState, +}; +use crate::web::static_files::static_handler; +use crate::CdkLdkNode; + +pub struct WebServer { + pub node: Arc, +} + +impl WebServer { + pub fn new(node: Arc) -> Self { + Self { node } + } + + pub fn create_router(&self) -> Router { + let state = AppState { + node: self.node.clone(), + }; + + tracing::debug!("Serving static files from embedded assets"); + + Router::new() + // Dashboard + .route("/", get(dashboard)) + // Balance and onchain operations + .route("/balance", get(balance_page)) + .route("/onchain", get(onchain_page)) + .route("/onchain/send", post(post_send_onchain)) + .route("/onchain/confirm", get(onchain_confirm_page)) + .route("/onchain/new-address", post(get_new_address)) + // Channel management + .route("/channels", get(channels_page)) + .route("/channels/open", get(open_channel_page)) + .route("/channels/open", post(post_open_channel)) + .route("/channels/close", get(close_channel_page)) + .route("/channels/close", post(post_close_channel)) + .route("/channels/force-close", get(force_close_channel_page)) + .route("/channels/force-close", post(post_force_close_channel)) + // Invoice creation + .route("/invoices", get(invoices_page)) + .route("/invoices/bolt11", post(post_create_bolt11)) + .route("/invoices/bolt12", post(post_create_bolt12)) + // Payment sending and history + .route("/payments", get(payments_page)) + .route("/payments/send", get(send_payments_page)) + .route("/payments/bolt11", post(post_pay_bolt11)) + .route("/payments/bolt12", post(post_pay_bolt12)) + // Static files - now embedded + .route("/static/{*file}", get(static_handler)) + .layer(ServiceBuilder::new().layer(CorsLayer::permissive())) + .with_state(state) + } + + pub async fn serve(&self, addr: SocketAddr) -> Result<(), Box> { + let app = self.create_router(); + + tracing::info!("Starting web server on {}", addr); + let listener = tokio::net::TcpListener::bind(addr).await?; + + tracing::info!("Web interface available at: http://{}", addr); + axum::serve(listener, app).await?; + + Ok(()) + } +} diff --git a/crates/cdk-ldk-node/src/web/static_files.rs b/crates/cdk-ldk-node/src/web/static_files.rs new file mode 100644 index 000000000..666c4089c --- /dev/null +++ b/crates/cdk-ldk-node/src/web/static_files.rs @@ -0,0 +1,47 @@ +use axum::extract::Path; +use axum::http::{header, HeaderMap, StatusCode}; +use axum::response::IntoResponse; +use rust_embed::RustEmbed; + +#[derive(RustEmbed)] +#[folder = "static/"] +pub struct Assets; + +fn get_content_type(path: &str) -> &'static str { + if let Some(extension) = path.rsplit('.').next() { + match extension.to_lowercase().as_str() { + "css" => "text/css", + "png" => "image/png", + "jpg" | "jpeg" => "image/jpeg", + "svg" => "image/svg+xml", + "ico" => "image/x-icon", + _ => "application/octet-stream", + } + } else { + "application/octet-stream" + } +} + +pub async fn static_handler(Path(path): Path) -> impl IntoResponse { + let cleaned_path = path.trim_start_matches('/'); + + match Assets::get(cleaned_path) { + Some(content) => { + let content_type = get_content_type(cleaned_path); + let mut headers = HeaderMap::new(); + headers.insert(header::CONTENT_TYPE, content_type.parse().unwrap()); + + // Add cache headers for static assets + headers.insert( + header::CACHE_CONTROL, + "public, max-age=31536000".parse().unwrap(), + ); + + (headers, content.data).into_response() + } + None => { + tracing::warn!("Static file not found: {}", cleaned_path); + (StatusCode::NOT_FOUND, "404 Not Found").into_response() + } + } +} diff --git a/crates/cdk-ldk-node/src/web/templates/components.rs b/crates/cdk-ldk-node/src/web/templates/components.rs new file mode 100644 index 000000000..bbada534a --- /dev/null +++ b/crates/cdk-ldk-node/src/web/templates/components.rs @@ -0,0 +1,36 @@ +use maud::{html, Markup}; + +pub fn info_card(title: &str, items: Vec<(&str, String)>) -> Markup { + html! { + div class="card" { + h2 { (title) } + @for (label, value) in items { + div class="info-item" { + span class="info-label" { (label) ":" } + span class="info-value" { (value) } + } + } + } + } +} + +pub fn form_card(title: &str, form_content: Markup) -> Markup { + html! { + div class="card" { + h2 { (title) } + (form_content) + } + } +} + +pub fn success_message(message: &str) -> Markup { + html! { + div class="success" { (message) } + } +} + +pub fn error_message(message: &str) -> Markup { + html! { + div class="error" { (message) } + } +} diff --git a/crates/cdk-ldk-node/src/web/templates/formatters.rs b/crates/cdk-ldk-node/src/web/templates/formatters.rs new file mode 100644 index 000000000..97630a132 --- /dev/null +++ b/crates/cdk-ldk-node/src/web/templates/formatters.rs @@ -0,0 +1,150 @@ +/// Format satoshis as a whole number with Bitcoin symbol (BIP177) +pub fn format_sats_as_btc(sats: u64) -> String { + let sats_str = sats.to_string(); + let formatted_sats = if sats_str.len() > 3 { + let mut result = String::new(); + let chars: Vec = sats_str.chars().collect(); + let len = chars.len(); + + for (i, ch) in chars.iter().enumerate() { + // Add comma before every group of 3 digits from right to left + if i > 0 && (len - i) % 3 == 0 { + result.push(','); + } + result.push(*ch); + } + result + } else { + sats_str + }; + + format!("₿{formatted_sats}") +} + +/// Format millisatoshis as satoshis (whole number) with Bitcoin symbol (BIP177) +pub fn format_msats_as_btc(msats: u64) -> String { + let sats = msats / 1000; + let sats_str = sats.to_string(); + let formatted_sats = if sats_str.len() > 3 { + let mut result = String::new(); + let chars: Vec = sats_str.chars().collect(); + let len = chars.len(); + + for (i, ch) in chars.iter().enumerate() { + // Add comma before every group of 3 digits from right to left + if i > 0 && (len - i) % 3 == 0 { + result.push(','); + } + result.push(*ch); + } + result + } else { + sats_str + }; + + format!("₿{formatted_sats}") +} + +/// Format a Unix timestamp as a human-readable date and time +pub fn format_timestamp(timestamp: u64) -> String { + use std::time::{SystemTime, UNIX_EPOCH}; + + let now = SystemTime::now() + .duration_since(UNIX_EPOCH) + .unwrap_or_default() + .as_secs(); + let diff = now.saturating_sub(timestamp); + + match diff { + 0..=60 => "Just now".to_string(), + 61..=3600 => format!("{} min ago", diff / 60), + _ => { + // For timestamps older than 1 hour, show UTC time + // Convert to a simple UTC format + let total_seconds = timestamp; + let seconds = total_seconds % 60; + let total_minutes = total_seconds / 60; + let minutes = total_minutes % 60; + let total_hours = total_minutes / 60; + let hours = total_hours % 24; + let days = total_hours / 24; + + // Calculate year, month, day from days since epoch (1970-01-01) + let mut year = 1970; + let mut remaining_days = days; + + // Simple year calculation + loop { + let is_leap_year = (year % 4 == 0 && year % 100 != 0) || (year % 400 == 0); + let days_in_year = if is_leap_year { 366 } else { 365 }; + + if remaining_days >= days_in_year { + remaining_days -= days_in_year; + year += 1; + } else { + break; + } + } + + // Calculate month and day + let is_leap_year = (year % 4 == 0 && year % 100 != 0) || (year % 400 == 0); + let days_in_months = if is_leap_year { + [31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31] + } else { + [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31] + }; + + let mut month = 1; + let mut day = remaining_days + 1; + + for &days_in_month in &days_in_months { + if day > days_in_month { + day -= days_in_month; + month += 1; + } else { + break; + } + } + + format!( + "{:04}-{:02}-{:02} {:02}:{:02}:{:02} UTC", + year, month, day, hours, minutes, seconds + ) + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn test_format_timestamp() { + use std::time::{SystemTime, UNIX_EPOCH}; + + let now = SystemTime::now() + .duration_since(UNIX_EPOCH) + .unwrap() + .as_secs(); + + // Test "Just now" (30 seconds ago) + let recent = now - 30; + assert_eq!(format_timestamp(recent), "Just now"); + + // Test minutes ago (30 minutes ago) + let minutes_ago = now - (30 * 60); + assert_eq!(format_timestamp(minutes_ago), "30 min ago"); + + // Test UTC format for older timestamps (2 hours ago) + let hours_ago = now - (2 * 60 * 60); + let result = format_timestamp(hours_ago); + assert!(result.ends_with(" UTC")); + assert!(result.contains("-")); + assert!(result.contains(":")); + + // Test known timestamp: January 1, 2020 00:00:00 UTC + let timestamp_2020 = 1577836800; // 2020-01-01 00:00:00 UTC + let result = format_timestamp(timestamp_2020); + assert_eq!(result, "2020-01-01 00:00:00 UTC"); + } +} diff --git a/crates/cdk-ldk-node/src/web/templates/layout.rs b/crates/cdk-ldk-node/src/web/templates/layout.rs new file mode 100644 index 000000000..d055390d9 --- /dev/null +++ b/crates/cdk-ldk-node/src/web/templates/layout.rs @@ -0,0 +1,1326 @@ +use maud::{html, Markup, DOCTYPE}; + +pub fn layout(title: &str, content: Markup) -> Markup { + html! { + (DOCTYPE) + html lang="en" { + head { + meta charset="utf-8"; + meta name="viewport" content="width=device-width, initial-scale=1"; + link rel="icon" type="image/svg+xml" href="/static/favicon.svg"; + link rel="stylesheet" type="text/css" href="/static/css/globe.css"; + title { (title) " - CDK LDK Node" } + style { + " + :root { + /* Light mode (default) */ + --background: 0 0% 100%; + --foreground: 222.2 84% 4.9%; + --card: 0 0% 100%; + --card-foreground: 222.2 84% 4.9%; + --popover: 0 0% 100%; + --popover-foreground: 222.2 84% 4.9%; + --primary: 222.2 47.4% 11.2%; + --primary-foreground: 210 40% 98%; + --secondary: 210 40% 96%; + --secondary-foreground: 222.2 84% 4.9%; + --muted: 210 40% 96%; + --muted-foreground: 215.4 16.3% 46.9%; + --accent: 210 40% 96%; + --accent-foreground: 222.2 84% 4.9%; + --destructive: 0 84.2% 60.2%; + --destructive-foreground: 210 40% 98%; + --border: 214.3 31.8% 91.4%; + --input: 214.3 31.8% 91.4%; + --ring: 222.2 84% 4.9%; + --radius: 0.5rem; + + /* Typography scale */ + --fs-title: 1.25rem; + --fs-label: 0.8125rem; + --fs-value: 1.625rem; + + /* Line heights */ + --lh-tight: 1.15; + --lh-normal: 1.4; + + /* Font weights */ + --fw-medium: 500; + --fw-semibold: 600; + --fw-bold: 700; + + /* Colors */ + --fg-primary: #0f172a; + --fg-muted: #6b7280; + + /* Header text colors for light mode */ + --header-title: #000000; + --header-subtitle: #333333; + } + + /* Dark mode using system preference */ + @media (prefers-color-scheme: dark) { + :root { + --background: 222.2 84% 4.9%; + --foreground: 210 40% 98%; + --card: 222.2 84% 4.9%; + --card-foreground: 210 40% 98%; + --popover: 222.2 84% 4.9%; + --popover-foreground: 210 40% 98%; + --primary: 210 40% 98%; + --primary-foreground: 222.2 84% 4.9%; + --secondary: 217.2 32.6% 17.5%; + --secondary-foreground: 210 40% 98%; + --muted: 217.2 32.6% 17.5%; + --muted-foreground: 215 20.2% 65.1%; + --accent: 217.2 32.6% 17.5%; + --accent-foreground: 210 40% 98%; + --destructive: 0 62.8% 30.6%; + --destructive-foreground: 210 40% 98%; + --border: 217.2 32.6% 17.5%; + --input: 217.2 32.6% 17.5%; + --ring: 212.7 26.8% 83.9%; + + /* Dark mode colors */ + --fg-primary: #f8fafc; + --fg-muted: #94a3b8; + + /* Header text colors for dark mode */ + --header-title: #ffffff; + --header-subtitle: #e2e8f0; + } + } + + * { + box-sizing: border-box; + margin: 0; + padding: 0; + } + + html { + font-feature-settings: 'cv02', 'cv03', 'cv04', 'cv11'; + font-variation-settings: normal; + } + + body { + font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif; + font-size: 14px; + line-height: 1.5; + color: hsl(var(--foreground)); + background-color: hsl(var(--background)); + font-feature-settings: 'rlig' 1, 'calt' 1; + -webkit-font-smoothing: antialiased; + -moz-osx-font-smoothing: grayscale; + text-rendering: geometricPrecision; + min-height: 100vh; + } + + .container { + max-width: 1200px; + margin: 0 auto; + padding: 0 1rem; + } + + @media (min-width: 640px) { + .container { + padding: 0 2rem; + } + } + + /* Hero section styling */ + header { + position: relative; + background-image: url('/static/images/bg.jpg?v=3'); + background-size: cover; + background-position: center; + background-repeat: no-repeat; + border-bottom: 1px solid hsl(var(--border)); + margin-bottom: 3rem; + text-align: center; + width: 100%; + height: 400px; /* Fixed height for better proportion */ + display: flex; + align-items: center; + justify-content: center; + } + + /* Dark mode header background - using different image */ + @media (prefers-color-scheme: dark) { + header { + background-image: url('/static/images/bg-dark.jpg?v=3'); + } + } + + /* Ensure text is positioned properly */ + header .container { + position: absolute; + top: 50%; + left: 50%; + transform: translate(-50%, -50%); + z-index: 2; + width: 100%; + max-width: 1200px; + padding: 0 2rem; + } + + h1 { + font-size: 3rem; + font-weight: 700; + line-height: 1.1; + letter-spacing: -0.02em; + color: var(--header-title); + margin-bottom: 1rem; + } + + .subtitle { + font-size: 1.25rem; + color: var(--header-subtitle); + font-weight: 400; + max-width: 600px; + margin: 0 auto; + line-height: 1.6; + } + + @media (max-width: 768px) { + header { + height: 300px; /* Smaller height on mobile */ + } + + header .container { + padding: 0 1rem; + } + + h1 { + font-size: 2.25rem; + } + + .subtitle { + font-size: 1.1rem; + } + } + + /* Card fade-in animation */ + @keyframes fade-in { + from { opacity: 0; transform: translateY(10px); } + to { opacity: 1; transform: translateY(0); } + } + + .card { + animation: fade-in 0.3s ease-out; + } + + /* Modern Navigation Bar Styling */ + nav { + background-color: hsl(var(--card)); + border-top: 1px solid hsl(var(--border)); + border-bottom: 1px solid hsl(var(--border)); + border-left: none; + border-right: none; + border-radius: 0; + padding: 0.75rem; + margin-bottom: 2rem; + } + + nav .container { + padding: 0; + display: flex; + justify-content: center; + } + + nav ul { + list-style: none; + display: flex; + gap: 0.5rem; + overflow-x: auto; + -webkit-overflow-scrolling: touch; + margin: 0; + padding: 0; + justify-content: center; + } + + nav li { + flex-shrink: 0; + } + + nav a { + display: inline-flex; + align-items: center; + justify-content: center; + white-space: nowrap; + text-decoration: none; + font-size: 1rem; + font-weight: 600; + color: hsl(var(--muted-foreground)); + padding: 1rem 1.5rem; + border-radius: calc(var(--radius) - 2px); + transition: all 200ms cubic-bezier(0.4, 0, 0.2, 1); + position: relative; + min-height: 3rem; + } + + nav a:hover { + color: hsl(var(--foreground)); + background-color: hsl(var(--muted)); + } + + nav a.active { + color: hsl(var(--primary-foreground)); + background-color: hsl(var(--primary)); + font-weight: 700; + } + + nav a.active:hover { + background-color: hsl(var(--primary) / 0.9); + } + + .card { + background-color: hsl(var(--card)); + border: 1px solid hsl(var(--border)); + border-radius: var(--radius); + padding: 1.5rem; + margin-bottom: 1.5rem; + box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.05); + } + + /* Metric cards styling - matching balance-item style */ + .metrics-container { + display: flex; + gap: 1rem; + margin: 1rem 0; + flex-wrap: wrap; + } + + .metric-card { + flex: 1; + min-width: 200px; + text-align: center; + padding: 1rem; + background-color: hsl(var(--muted) / 0.3); + border-radius: calc(var(--radius) - 2px); + border: 1px solid hsl(var(--border)); + } + + .metric-value { + font-size: 1.5rem; + font-weight: 600; + color: hsl(var(--foreground)); + margin-bottom: 0.5rem; + line-height: 1.2; + } + + .metric-label { + font-size: 0.875rem; + color: hsl(var(--muted-foreground)); + font-weight: 400; + } + + .card h2, + .section-title, + h2 { + font-size: var(--fs-title); + line-height: var(--lh-tight); + font-weight: var(--fw-semibold); + color: var(--fg-primary); + text-transform: none; + margin: 0 0 12px; + } + + h3 { + font-size: var(--fs-title); + line-height: var(--lh-tight); + font-weight: var(--fw-semibold); + color: var(--fg-primary); + text-transform: none; + margin: 0 0 12px; + } + + .form-group { + margin-bottom: 1.5rem; + } + + label { + display: block; + font-size: 0.875rem; + font-weight: 500; + color: hsl(var(--foreground)); + margin-bottom: 0.5rem; + } + + input, textarea, select { + flex: 1; + background-color: hsl(var(--background)); + border: 1px solid hsl(var(--input)); + border-radius: calc(var(--radius) - 2px); + padding: 0.5rem 0.75rem; + font-size: 0.875rem; + line-height: 1.25; + color: hsl(var(--foreground)); + transition: border-color 150ms ease-in-out, box-shadow 150ms ease-in-out; + width: 100%; + } + + input:focus, textarea:focus, select:focus { + outline: 2px solid transparent; + outline-offset: 2px; + border-color: hsl(var(--ring)); + box-shadow: 0 0 0 2px hsl(var(--ring)); + } + + input:disabled, textarea:disabled, select:disabled { + cursor: not-allowed; + opacity: 0.5; + } + + button { + display: inline-flex; + align-items: center; + justify-content: center; + white-space: nowrap; + border-radius: calc(var(--radius) - 2px); + font-size: 0.875rem; + font-weight: 600; + transition: all 150ms ease-in-out; + border: 1px solid transparent; + cursor: pointer; + padding: 0.5rem 1rem; + height: 2.25rem; + background-color: hsl(var(--primary)); + color: hsl(var(--primary-foreground)); + } + + button:hover { + background-color: hsl(var(--primary) / 0.9); + } + + button:focus-visible { + outline: 2px solid hsl(var(--ring)); + outline-offset: 2px; + } + + button:disabled { + pointer-events: none; + opacity: 0.5; + } + + .button-secondary { + background-color: hsl(var(--secondary)); + color: hsl(var(--secondary-foreground)); + border: 1px solid hsl(var(--input)); + } + + .button-secondary:hover { + background-color: hsl(var(--secondary) / 0.8); + } + + .button-outline { + border: 1px solid hsl(var(--input)); + background-color: hsl(var(--background)); + color: hsl(var(--foreground)); + } + + .button-outline:hover { + background-color: hsl(var(--accent)); + color: hsl(var(--accent-foreground)); + } + + .button-destructive { + background-color: hsl(var(--destructive)); + color: hsl(var(--destructive-foreground)); + } + + .button-destructive:hover { + background-color: hsl(var(--destructive) / 0.9); + } + + .button-sm { + height: 2rem; + border-radius: calc(var(--radius) - 4px); + padding: 0 0.75rem; + font-size: 0.75rem; + } + + .button-lg { + height: 2.75rem; + border-radius: var(--radius); + padding: 0 2rem; + font-size: 1rem; + } + + .grid { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(320px, 1fr)); + gap: 1.5rem; + } + + @media (max-width: 640px) { + .grid { + grid-template-columns: 1fr; + } + } + + + + .info-label, + .sub-label, + label { + font-size: var(--fs-label); + line-height: var(--lh-normal); + font-weight: var(--fw-medium); + color: var(--fg-muted); + text-transform: none; + letter-spacing: 0.02em; + flex-shrink: 0; + } + + .info-value { + font-size: 0.875rem; + font-family: 'SF Mono', 'Monaco', 'Inconsolata', 'Roboto Mono', 'Courier New', monospace; + color: var(--fg-primary); + text-align: right; + word-break: break-all; + overflow-wrap: break-word; + hyphens: auto; + min-width: 0; + } + + .info-item { + display: flex; + gap: 0.5rem; + align-items: baseline; + margin: 8px 0; + padding: 1rem 0; + border-bottom: 1px solid hsl(var(--border)); + min-height: 3rem; + justify-content: space-between; + } + + .info-item:last-child { + border-bottom: none; + } + + /* Card flex spacing improvements */ + .card-flex { + display: flex; + gap: 1rem; + align-items: center; + } + + .card-flex-content { + flex: 1 1 auto; + } + + .card-flex-button { + flex: 0 0 auto; + } + + .card-flex-content p { + margin: 0 0 12px; + line-height: var(--lh-normal); + } + + .card-flex-content p + .card-flex-button, + .card-flex-content p + a, + .card-flex-content p + button { + margin-top: 12px; + } + + .card-flex-content .body + .card-flex-button, + .card-flex-content .body + a, + .card-flex-content .body + button { + margin-top: 12px; + } + + .truncate-value { + font-size: 0.875rem; + font-family: 'SF Mono', 'Monaco', 'Inconsolata', 'Roboto Mono', 'Courier New', monospace; + color: hsl(var(--foreground)); + text-align: right; + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; + display: inline-block; + max-width: 200px; + } + + .copy-button { + background-color: hsl(var(--secondary)); + color: hsl(var(--secondary-foreground)); + border: 1px solid hsl(var(--border)); + border-radius: calc(var(--radius) - 4px); + padding: 0.25rem 0.5rem; + cursor: pointer; + font-size: 0.75rem; + font-weight: 600; + margin-left: 0.5rem; + transition: all 150ms ease-in-out; + height: auto; + min-height: auto; + flex-shrink: 0; + } + + .copy-button:hover { + background-color: hsl(var(--secondary) / 0.8); + border-color: hsl(var(--border)); + } + + .balance-item, + .balance-item-container { + padding: 1.25rem 0; + border-bottom: 1px solid hsl(var(--border)); + margin-bottom: 10px; + } + + .balance-item:last-child, + .balance-item-container:last-child { + border-bottom: none; + } + + .balance-item .balance-label, + .balance-item-container .balance-label, + .balance-title, + .balance-label { + display: block; + margin-bottom: 6px; + font-size: var(--fs-label); + line-height: var(--lh-normal); + font-weight: var(--fw-medium); + color: var(--fg-muted); + letter-spacing: 0.02em; + text-transform: none; + } + + .balance-item .balance-amount, + .balance-item-container .balance-value, + .balance-amount, + .balance-amount-value, + .balance-value { + display: block; + font-size: var(--fs-value); + line-height: var(--lh-tight); + font-weight: var(--fw-bold); + color: var(--fg-primary); + white-space: nowrap; + font-family: 'SF Mono', 'Monaco', 'Inconsolata', 'Roboto Mono', 'Courier New', monospace; + } + + .balance-item .info-label + .info-value, + .balance-item .label + .amount, + .balance-item-container .info-label + .info-value, + .balance-item-container .label + .amount { + margin-top: 6px; + } + + .alert { + border: 1px solid hsl(var(--border)); + border-radius: var(--radius); + padding: 1rem; + margin-bottom: 1rem; + } + + .alert-success { + border-color: hsl(142.1 76.2% 36.3%); + background-color: hsl(142.1 70.6% 45.3% / 0.1); + color: hsl(142.1 76.2% 36.3%); + } + + .alert-destructive { + border-color: hsl(var(--destructive)); + background-color: hsl(var(--destructive) / 0.1); + color: hsl(var(--destructive)); + } + + .alert-warning { + border-color: hsl(32.6 75.4% 55.1%); + background-color: hsl(32.6 75.4% 55.1% / 0.1); + color: hsl(32.6 75.4% 55.1%); + } + + /* Legacy classes for backward compatibility */ + .success { + border-color: hsl(142.1 76.2% 36.3%); + background-color: hsl(142.1 70.6% 45.3% / 0.1); + color: hsl(142.1 76.2% 36.3%); + border: 1px solid hsl(142.1 76.2% 36.3%); + border-radius: var(--radius); + padding: 1rem; + margin-bottom: 1rem; + } + + .error { + border-color: hsl(var(--destructive)); + background-color: hsl(var(--destructive) / 0.1); + color: hsl(var(--destructive)); + border: 1px solid hsl(var(--destructive)); + border-radius: var(--radius); + padding: 1rem; + margin-bottom: 1rem; + } + + .badge { + display: inline-flex; + align-items: center; + border-radius: 9999px; + padding: 0.25rem 0.625rem; + font-size: 0.75rem; + font-weight: 500; + line-height: 1; + transition: all 150ms ease-in-out; + border: 1px solid transparent; + } + + .badge-default { + background-color: hsl(var(--primary)); + color: hsl(var(--primary-foreground)); + } + + .badge-secondary { + background-color: hsl(var(--secondary)); + color: hsl(var(--secondary-foreground)); + } + + .badge-success { + background-color: hsl(142.1 70.6% 45.3%); + color: hsl(355.7 78% 98.4%); + } + + .badge-destructive { + background-color: hsl(var(--destructive)); + color: hsl(var(--destructive-foreground)); + } + + .badge-outline { + background-color: transparent; + color: hsl(var(--foreground)); + border: 1px solid hsl(var(--border)); + } + + /* Legacy status classes */ + .status-badge { + display: inline-flex; + align-items: center; + border-radius: 9999px; + padding: 0.25rem 0.625rem; + font-size: 0.75rem; + font-weight: 500; + line-height: 1; + } + + .status-active { + background-color: hsl(142.1 70.6% 45.3%); + color: hsl(355.7 78% 98.4%); + } + + .status-inactive { + background-color: hsl(var(--destructive)); + color: hsl(var(--destructive-foreground)); + } + + .channel-item { + background-color: hsl(var(--card)); + border: 1px solid hsl(var(--border)); + border-radius: var(--radius); + padding: 1.5rem; + margin-bottom: 1.5rem; + } + + .channel-header { + display: flex; + justify-content: space-between; + align-items: center; + margin-bottom: 1rem; + gap: 1rem; + } + + .channel-id { + font-family: 'SF Mono', 'Monaco', 'Inconsolata', 'Roboto Mono', 'Courier New', monospace; + font-size: 0.875rem; + color: hsl(var(--muted-foreground)); + word-break: break-all; + flex: 1; + min-width: 0; + } + + .balance-info { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(120px, 1fr)); + gap: 1rem; + margin-top: 1rem; + } + + @media (max-width: 640px) { + .balance-info { + grid-template-columns: 1fr; + } + } + + .balance-item { + text-align: center; + padding: 1rem; + background-color: hsl(var(--muted) / 0.3); + border-radius: calc(var(--radius) - 2px); + border: 1px solid hsl(var(--border)); + } + + .balance-amount { + font-weight: 600; + font-size: 1.125rem; + font-family: 'SF Mono', 'Monaco', 'Inconsolata', 'Roboto Mono', 'Courier New', monospace; + color: hsl(var(--foreground)); + line-height: 1.2; + } + + + + .payment-item { + background-color: hsl(var(--card)); + border: 1px solid hsl(var(--border)); + border-radius: var(--radius); + padding: 1.5rem; + margin-bottom: 1.5rem; + } + + .payment-header { + display: flex; + justify-content: space-between; + align-items: flex-start; + margin-bottom: 1rem; + gap: 1rem; + } + + @media (max-width: 640px) { + .payment-header { + flex-direction: column; + align-items: stretch; + gap: 0.75rem; + } + } + + .payment-direction { + display: flex; + align-items: center; + gap: 0.5rem; + font-weight: 600; + color: hsl(var(--foreground)); + flex: 1; + min-width: 0; + } + + .direction-icon { + font-size: 1.125rem; + font-weight: bold; + color: hsl(var(--muted-foreground)); + } + + .payment-details { + display: flex; + flex-direction: column; + gap: 0.75rem; + } + + .payment-amount { + font-size: 1.25rem; + font-weight: 600; + font-family: 'SF Mono', 'Monaco', 'Inconsolata', 'Roboto Mono', 'Courier New', monospace; + color: hsl(var(--foreground)); + line-height: 1.2; + } + + .payment-info { + display: flex; + align-items: center; + gap: 0.75rem; + flex-wrap: wrap; + } + + @media (max-width: 640px) { + .payment-info { + flex-direction: column; + align-items: flex-start; + gap: 0.25rem; + } + } + + .payment-label { + font-weight: 500; + color: hsl(var(--muted-foreground)); + font-size: 0.875rem; + flex-shrink: 0; + } + + .payment-value { + color: hsl(var(--foreground)); + font-family: 'SF Mono', 'Monaco', 'Inconsolata', 'Roboto Mono', 'Courier New', monospace; + font-size: 0.875rem; + word-break: break-all; + min-width: 0; + } + + .payment-list-header { + display: flex; + justify-content: space-between; + align-items: center; + margin-bottom: 1.5rem; + padding-bottom: 1rem; + border-bottom: 1px solid hsl(var(--border)); + } + + @media (max-width: 640px) { + .payment-list-header { + flex-direction: column; + align-items: stretch; + gap: 1rem; + } + } + + .payment-filter-tabs { + display: flex; + gap: 0.25rem; + overflow-x: auto; + -webkit-overflow-scrolling: touch; + } + + .payment-filter-tab { + display: inline-flex; + align-items: center; + justify-content: center; + white-space: nowrap; + padding: 0.5rem 1rem; + border: 1px solid hsl(var(--border)); + background-color: hsl(var(--background)); + border-radius: calc(var(--radius) - 2px); + text-decoration: none; + color: hsl(var(--muted-foreground)); + font-size: 0.875rem; + font-weight: 600; + transition: all 150ms ease-in-out; + height: 2.25rem; + } + + .payment-filter-tab:hover { + background-color: hsl(var(--accent)); + color: hsl(var(--accent-foreground)); + text-decoration: none; + } + + .payment-filter-tab.active { + background-color: hsl(var(--primary)); + color: hsl(var(--primary-foreground)); + border-color: hsl(var(--primary)); + } + + .payment-type-badge { + display: inline-flex; + align-items: center; + border-radius: 9999px; + padding: 0.125rem 0.5rem; + font-size: 0.625rem; + font-weight: 600; + line-height: 1; + margin-left: 0.5rem; + text-transform: uppercase; + letter-spacing: 0.05em; + } + + .payment-type-bolt11 { + background-color: hsl(217 91% 60% / 0.1); + color: hsl(217 91% 60%); + border: 1px solid hsl(217 91% 60% / 0.2); + } + + .payment-type-bolt12 { + background-color: hsl(262 83% 58% / 0.1); + color: hsl(262 83% 58%); + border: 1px solid hsl(262 83% 58% / 0.2); + } + + .payment-type-onchain { + background-color: hsl(32 95% 44% / 0.1); + color: hsl(32 95% 44%); + border: 1px solid hsl(32 95% 44% / 0.2); + } + + .payment-type-spontaneous { + background-color: hsl(142.1 70.6% 45.3% / 0.1); + color: hsl(142.1 70.6% 45.3%); + border: 1px solid hsl(142.1 70.6% 45.3% / 0.2); + } + + .payment-type-bolt11-jit { + background-color: hsl(199 89% 48% / 0.1); + color: hsl(199 89% 48%); + border: 1px solid hsl(199 89% 48% / 0.2); + } + + .payment-type-unknown { + background-color: hsl(var(--muted)); + color: hsl(var(--muted-foreground)); + border: 1px solid hsl(var(--border)); + } + + /* Pagination */ + .pagination-controls { + display: flex; + justify-content: center; + align-items: center; + margin: 2rem 0; + } + + .pagination { + display: flex; + align-items: center; + gap: 0.25rem; + list-style: none; + } + + .pagination-btn, .pagination-number { + display: inline-flex; + align-items: center; + justify-content: center; + white-space: nowrap; + border-radius: calc(var(--radius) - 2px); + font-size: 0.875rem; + font-weight: 600; + transition: all 150ms ease-in-out; + border: 1px solid hsl(var(--border)); + background-color: hsl(var(--background)); + color: hsl(var(--foreground)); + text-decoration: none; + cursor: pointer; + height: 2.25rem; + min-width: 2.25rem; + padding: 0 0.5rem; + } + + .pagination-btn:hover, .pagination-number:hover { + background-color: hsl(var(--accent)); + color: hsl(var(--accent-foreground)); + text-decoration: none; + } + + .pagination-number.active { + background-color: hsl(var(--primary)); + color: hsl(var(--primary-foreground)); + border-color: hsl(var(--primary)); + } + + .pagination-btn.disabled { + background-color: hsl(var(--muted)); + color: hsl(var(--muted-foreground)); + cursor: not-allowed; + opacity: 0.5; + pointer-events: none; + } + + .pagination-ellipsis { + display: flex; + align-items: center; + justify-content: center; + height: 2.25rem; + width: 2.25rem; + color: hsl(var(--muted-foreground)); + font-size: 0.875rem; + } + + /* Responsive adjustments */ + @media (max-width: 640px) { + .container { + padding: 0 1rem; + } + + header { + padding: 1rem 0; + margin-bottom: 1rem; + } + + h1 { + font-size: 1.5rem; + } + + nav ul { + flex-wrap: wrap; + } + + .card { + padding: 1rem; + margin-bottom: 1rem; + } + + .info-item { + flex-direction: column; + align-items: flex-start; + gap: 0.75rem; + padding: 1rem 0; + min-height: auto; + } + + .info-value, .truncate-value { + text-align: left; + max-width: 100%; + } + + .copy-button { + margin-left: 0; + margin-top: 0.25rem; + align-self: flex-start; + } + + .balance-amount-value { + font-size: 1.25rem; + } + + .pagination { + flex-wrap: wrap; + justify-content: center; + gap: 0.125rem; + } + + .pagination-btn, .pagination-number { + height: 2rem; + min-width: 2rem; + font-size: 0.75rem; + } + } + + /* Node Information Section Styling */ + .node-info-section { + display: flex; + gap: 1.5rem; + margin-bottom: 1.5rem; + align-items: flex-start; + } + + .node-info-main-container { + flex: 1; + display: flex; + flex-direction: column; + gap: 1rem; + background-color: hsl(var(--card)); + border: 1px solid hsl(var(--border)); + border-radius: var(--radius); + padding: 1.5rem; + box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.05); + } + + .node-info-left { + display: flex; + align-items: center; + gap: 1rem; + margin-bottom: 1rem; + } + + .node-avatar { + flex-shrink: 0; + background-color: hsl(var(--muted) / 0.3); + border: 1px solid hsl(var(--border)); + border-radius: var(--radius); + padding: 0.75rem; + display: flex; + align-items: center; + justify-content: center; + width: 80px; + height: 80px; + } + + .avatar-image { + width: 48px; + height: 48px; + border-radius: calc(var(--radius) - 2px); + object-fit: cover; + display: block; + } + + .node-details { + flex: 1; + min-width: 0; + } + + .node-name { + font-size: var(--fs-title); + font-weight: var(--fw-semibold); + color: var(--fg-primary); + margin: 0 0 0.25rem 0; + line-height: var(--lh-tight); + word-wrap: break-word; + overflow-wrap: break-word; + hyphens: auto; + } + + .node-address { + font-size: 0.875rem; + color: var(--fg-muted); + margin: 0; + line-height: var(--lh-normal); + } + + .node-content-box { + background-color: hsl(var(--muted) / 0.3); + border: 1px solid hsl(var(--border)); + border-radius: var(--radius); + min-height: 200px; + padding: 1rem; + display: flex; + align-items: center; + justify-content: center; + color: hsl(var(--muted-foreground)); + overflow: hidden; + } + + .node-metrics { + flex-shrink: 0; + width: 280px; + display: flex; + flex-direction: column; + } + + .node-metrics .card { + margin-bottom: 0; + flex: 1; + display: flex; + flex-direction: column; + } + + .node-metrics .metrics-container { + flex-direction: column; + margin: 1rem 0 0 0; + flex: 1; + } + + .node-metrics .metric-card { + min-width: auto; + } + + /* Mobile responsive design for node info */ + @media (max-width: 768px) { + .node-info-section { + flex-direction: column; + gap: 1rem; + } + + .node-info-left { + flex-direction: column; + align-items: flex-start; + text-align: center; + gap: 0.75rem; + } + + .node-avatar { + align-self: center; + } + + .node-details { + text-align: center; + width: 100%; + } + + .node-content-box { + min-height: 150px; + padding: 1rem; + } + + .node-metrics { + width: 100%; + } + + .node-metrics .metrics-container { + flex-direction: row; + flex-wrap: wrap; + } + + .node-metrics .metric-card { + flex: 1; + min-width: 120px; + } + } + + @media (max-width: 480px) { + .node-info-left { + gap: 0.5rem; + } + + .node-avatar { + width: 64px; + height: 64px; + padding: 0.5rem; + } + + .avatar-image { + width: 40px; + height: 40px; + } + + .node-name { + font-size: 1rem; + word-wrap: break-word; + overflow-wrap: break-word; + hyphens: auto; + } + + .node-address { + font-size: 0.8125rem; + } + + .node-content-box { + min-height: 120px; + padding: 0.75rem; + } + + .node-metrics .metrics-container { + flex-direction: column; + gap: 0.75rem; + } + } + + /* Responsive typography adjustments */ + @media (max-width: 640px) { + :root { + --fs-value: 1.45rem; + } + + .node-name { + font-size: 0.875rem; + } + } + + @media (max-width: 480px) { + .node-name { + font-size: 0.8125rem; + } + } + + /* Dark mode adjustments for globe animation */ + @media (prefers-color-scheme: dark) { + .node-content-box .world { + border-color: rgba(156, 163, 175, 0.4); + fill: rgba(156, 163, 175, 0.2); + } + } + " + } + } + body { + header { + div class="container" { + h1 { "CDK LDK Node" } + p class="subtitle" { "Lightning Network Node Management" } + } + } + + nav { + div class="container" { + ul { + li { a href="/" { "Dashboard" } } + li { a href="/balance" { "Lightning" } } + li { a href="/onchain" { "On-chain" } } + li { a href="/invoices" { "Invoices" } } + li { a href="/payments" { "All Payments" } } + } + } + } + + main class="container" { + (content) + } + } + } + } +} diff --git a/crates/cdk-ldk-node/src/web/templates/mod.rs b/crates/cdk-ldk-node/src/web/templates/mod.rs new file mode 100644 index 000000000..d01660856 --- /dev/null +++ b/crates/cdk-ldk-node/src/web/templates/mod.rs @@ -0,0 +1,10 @@ +pub mod components; +pub mod formatters; +pub mod layout; +pub mod payments; + +// Re-export commonly used functions +pub use components::*; +pub use formatters::*; +pub use layout::*; +pub use payments::*; diff --git a/crates/cdk-ldk-node/src/web/templates/payments.rs b/crates/cdk-ldk-node/src/web/templates/payments.rs new file mode 100644 index 000000000..84455bd41 --- /dev/null +++ b/crates/cdk-ldk-node/src/web/templates/payments.rs @@ -0,0 +1,105 @@ +use maud::{html, Markup}; + +use crate::web::templates::formatters::format_timestamp; + +#[allow(clippy::too_many_arguments)] +pub fn payment_list_item( + _payment_id: &str, + direction: &str, + status: &str, + amount: &str, + payment_hash: Option<&str>, + description: Option<&str>, + timestamp: Option, + payment_type: &str, + preimage: Option<&str>, +) -> Markup { + let status_class = match status { + "Succeeded" => "status-active", + "Failed" => "status-inactive", + "Pending" => "status-badge", + _ => "status-badge", + }; + + let direction_icon = match direction { + "Inbound" => "↓", + "Outbound" => "↑", + _ => "•", + }; + + let type_class = match payment_type { + "BOLT11" => "payment-type-bolt11", + "BOLT12" => "payment-type-bolt12", + "On-chain" => "payment-type-onchain", + "Spontaneous" => "payment-type-spontaneous", + "BOLT11 JIT" => "payment-type-bolt11-jit", + _ => "payment-type-unknown", + }; + + html! { + div class="payment-item" { + div class="payment-header" { + div class="payment-direction" { + span class="direction-icon" { (direction_icon) } + span { (direction) " Payment" } + span class=(format!("payment-type-badge {}", type_class)) { (payment_type) } + } + span class=(format!("status-badge {}", status_class)) { (status) } + } + + div class="payment-details" { + div class="payment-amount" { (amount) } + + @if let Some(hash) = payment_hash { + div class="payment-info" { + span class="payment-label" { + @if payment_type == "BOLT11" || payment_type == "BOLT12" || payment_type == "Spontaneous" || payment_type == "BOLT11 JIT" { "Payment Hash:" } + @else { "Transaction ID:" } + } + span class="payment-value" title=(hash) { + (&hash[..std::cmp::min(16, hash.len())]) "..." + } + button class="copy-button" data-copy=(hash) + onclick="navigator.clipboard.writeText(this.getAttribute('data-copy')).then(() => { this.textContent = 'Copied!'; setTimeout(() => this.textContent = 'Copy', 2000); })" { + "Copy" + } + } + } + + // Show preimage for successful outgoing BOLT11 or BOLT12 payments + @if let Some(preimage_str) = preimage { + @if !preimage_str.is_empty() && direction == "Outbound" && status == "Succeeded" && (payment_type == "BOLT11" || payment_type == "BOLT12") { + div class="payment-info" { + span class="payment-label" { "Preimage:" } + span class="payment-value" title=(preimage_str) { + (&preimage_str[..std::cmp::min(16, preimage_str.len())]) "..." + } + button class="copy-button" data-copy=(preimage_str) + onclick="navigator.clipboard.writeText(this.getAttribute('data-copy')).then(() => { this.textContent = 'Copied!'; setTimeout(() => this.textContent = 'Copy', 2000); })" { + "Copy" + } + } + } + } + + @if let Some(desc) = description { + @if !desc.is_empty() { + div class="payment-info" { + span class="payment-label" { "Description:" } + span class="payment-value" { (desc) } + } + } + } + + @if let Some(ts) = timestamp { + div class="payment-info" { + span class="payment-label" { "Last Update:" } + span class="payment-value" { + (format_timestamp(ts)) + } + } + } + } + } + } +} diff --git a/crates/cdk-ldk-node/static/css/globe.css b/crates/cdk-ldk-node/static/css/globe.css new file mode 100644 index 000000000..6cdca043c --- /dev/null +++ b/crates/cdk-ldk-node/static/css/globe.css @@ -0,0 +1,75 @@ +/* Spinning Globe Animation CSS - Replaces radar */ +:root { + --globe-hue: 220deg; + --globe-base-bg-sat: 20%; + --globe-base-bg-lum: 12%; + --globe-base-bg: hsl(var(--globe-hue), var(--globe-base-bg-sat), var(--globe-base-bg-lum)); + --globe-base-fg-sat: 50%; + --globe-base-fg-lum: 80%; + --globe-base-fg: hsl(var(--globe-hue), var(--globe-base-fg-sat), var(--globe-base-fg-lum)); + --globe-filter-fg: saturate(100%) brightness(100%); + --globe-module-bg-sat: 18%; + --globe-module-bg-lum: 27%; + --globe-module-bg: hsl(var(--globe-hue), var(--globe-module-bg-sat), var(--globe-module-bg-lum)); +} + +/* Dark mode adjustments for globe */ +@media (prefers-color-scheme: dark) { + :root { + --globe-hue: 220deg; + --globe-base-bg-sat: 25%; + --globe-base-bg-lum: 15%; + --globe-base-fg-sat: 60%; + --globe-base-fg-lum: 85%; + --globe-filter-fg: saturate(120%) brightness(110%); + --globe-module-bg-sat: 22%; + --globe-module-bg-lum: 30%; + } +} + +/* Globe Container - fits inside the gray content box */ +.globe-container { + display: block; + width: 100%; + height: 200px; + position: relative; + overflow: hidden; +} + +.world { + fill: rgba(107, 114, 128, 0.1); /* Gray color with reduced opacity */ + width: 40em; + height: 40em; + position: absolute; + left: 50%; + top: 0%; + transform: translateX(-50%); + border-radius: 50%; + overflow: hidden; + white-space: nowrap; + border: 2px solid rgba(156, 163, 175, 0.2); /* Light gray border with reduced opacity */ + box-sizing: border-box; + background-image: url(#icon-world); + filter: var(--globe-filter-fg); +} + +/* Dark mode globe styling */ +@media (prefers-color-scheme: dark) { + .world { + fill: rgba(156, 163, 175, 0.2); + border-color: rgba(156, 163, 175, 0.4); + } +} + +.world svg { + width: 160em; + height: 40em; + margin-top: calc(-2px + -0.05em); + display: inline; + animation: world-scroll 8s linear infinite; +} + +@keyframes world-scroll { + from { margin-left: -110em; } + to { margin-left: -40em; } +} diff --git a/crates/cdk-ldk-node/static/favicon.ico b/crates/cdk-ldk-node/static/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..cb9704767eb0619fbf516a52d77b49c77b91a032 GIT binary patch literal 142 zcmZQzU<5(|0R|wcz>vbsz#zuJz|a}s=g!L|#RX*YdV0770coHL1_2H>ASwU(eRtvY3H^TNs2H8D`Cq01AqGx;TbZ%t=lFgCG1XJv}}kz#zrI XRKxgnV&mU*pehDWS3j3^P6 + + + + + diff --git a/crates/cdk-ldk-node/static/images/bg-dark.jpg b/crates/cdk-ldk-node/static/images/bg-dark.jpg new file mode 100644 index 0000000000000000000000000000000000000000..8cd9b7c209a40418a16fa4889ec1fe4768d21dfb GIT binary patch literal 47534 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 F{|Em`p$h;2 literal 0 HcmV?d00001 diff --git a/crates/cdk-ldk-node/static/images/bg.jpg b/crates/cdk-ldk-node/static/images/bg.jpg new file mode 100644 index 0000000000000000000000000000000000000000..0c1651142e8d11ff0f785c8bb4cc39d175f9c737 GIT binary patch literal 620237 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%0A30h8(9(-A^Z^lVw+Mqt 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≫bdcGzo*lL%1+L?P3 z8bu9#ZymQANjrVF{?YjA&NcmW*Z;sPM_>V=N1Oa_E!F2+dXdID8tXG9J;1y#K6Agy zOmjzMK0kf}eKVdO#PBDhJm8k%^pgG5Zh!j{Y{QEGjX7H!yx2I*k!@du(7gMpxH0_n z$4&%pjQ#{LwWhQE0x@sw_E;zm_xaJpg_B^`wA5m0?V@~DG{IBhl3?HnNt1e!@%ND* z*jE1EH@KZuRxFvny341}h*VgiCy{JY~tXVeIH!^Dh>G4%B(5Bjf(aLCd`IA*o<*!iw)kKw)k82~Rb@P`Pgq)Z;ey+~OOR>uT6FevPbD(&&-sPSQ zKeiJGzPj|FLAG{!E;a=s}kEN)?Wzy=I-{RuF$ zJ8QYuW^^jmoqnxQi+By`1BEf%HxEvi_5!ha*6jJh-r3SJcIqzO3_Zsni4&FLV``zA z%~R!brx@)laJN)$elOr)amXAl=dkYw-(+XjG?@Ixj8o!A7mjtH)TY?<-IHfMN#(7DE7Jo*>>(Q}zjt*=pm1 zRvY|;%p&Q5{a22({O6a)Wk)Jpm=gRZWAWfy+ycH#ydrsi6R!(3BOax5u6^amTpiO7 z`sjOk(*#>o1ojVZc>32pk^C`Z9%7hVy!x%RKSN^SWTrLA!a235GO0vrRi{P`3Jzd) zxBBd6Hv|C5<5G_uuckg0I~ycZzabSYIz{K7esuh z#zR4e?HNuqL?<7SbNF$kD zuSsvSfu`fdN!?qRX)&G<&*68L&WkMOjapxb82?Zs0aMnGy=jsY#@qui2xg@*TpzNA!zSeuzG*-Cd+0!a z@>_lZ%BaI-DHerfkD^zR;M;NmXz1m1G`yiSJ) zZfz5aQ7Isa&W16VQlEEivc9WI^0qTQ8kNxx$i|M9UDp_EEM>p!a5_wgQw1AJpZzPz zUf}1t{i97I60`d!c%G7@V;ZY>;&6<1DNZ#l;l!1|@}hZ{ct*V<<^3Ab)9U87x1{Md zWyGN#?v0THVV6;)XjO{3qL^W4qy1moQ(3$)Udu&q75G9F2AKm^dWoGMMTOI;+k3r~o}M-1TtlRheuZ zb;TPxLeUJa*IhWL3Df-ecrzaUzH68wiF7&^w`HF}^y9{#hro5n{^FDm3b_uy54@XXKQ;O@TWWC zE@NO_ULHw!^O|ZgWmDb(Y=p9#HcJu0du8@Q;gT~65 zRTIzrMEj*BZlPmE^e5n2+BS6iwUQNxJVIuifyZedDkL27cf(*nVWTs~3rtLS`>B-% z(=Y|odR-Ir#OT!N3=s3!I*rAVCu8@@H?&L82NkCd0TJgeXP&nlbqx3QB^!Ysgh;2I zC&H1qHH9vZem2*UHs9EGd;S1teiZgyy@?f05aw>)!0blhbNvyKmuf_QtVf(Z_Zin2 z)s7`4?Vg9O-57htyu3WV&q6CiI(z{dnmfC-??6iEy0GBZ}VRDQiJj(ND-`2O@4e%8i z+;d;i@H(8;X%a%^?t8ZyqO0Lj6>linIbWl?N5i;p2D{CmXUtNBhMOe*D#?M_pYQZi z#>8N{9zXWEY`Dg{?t(UzEWcj_B+R7L+j3rp`8*~zQn|71RAaqhf{9nR;H?#2Sl|;< zhp7*UI6Z>Um%7t|*kW93-%&r;BORcN=2^-aA+kD7Fj+bdlPZga+#CPQ6P^MR6oJyT zAeLH&XP{E*fnRsh7}^@U&RqDeIaGoW8`o!F(N0Zu%f{W{EU43>QpgK%H$brw%6Sl1aGT&TO5>2Kep z?Bsan>?-N~^jkKAN|_KzY99ZMd5X;A=G^TZ`rIg4+x56{x^>UsJ3D&e)gcQKXjJLN zh1AyBZ7!iL=eom5fRe3JA;d+fcOCc&X$q19i(A`R&DN&I(9WIcb4h3dcfqjRLv9b- z<*NJf!BwAza=g~x7t$F0g63#~x-W}!zjc$Dl$^)8gzl5a*Vc;H$UogL=fAsU;tJ1y z&*;#}c*3bUC)3vERIYD0ke;zQp}+BkDrK646D>a861zvI4_zjmV2JvORb zancV#b(j=OG~2f~#;p1n7)C7#Dcq+#o4kSE z-ur@SIZ3@T+^X2)(wwNuUix&#P*U7!r~`*KETEmTK>3`Z#i zk*c!Te)HcX-kRI(VsT2a3Y?F6NkHRM@;Ee#>(U%#-S8P;@Wczk$f;xJk1c-;_VJ%F z;>ORvF%vs(Pb^(%^)9Hh zUBJ=b&^TI!udu6-ca*J{E&1ikJx=v@dnBdadp}!}{NUgJz=orQ1b+ORDFvu&Mk@E-9ou&qV4OWVo^Wf4b+5g-mRww+t}0iP%7nV)Nm%fmEXr$N z6lh4w#j#lLAx>J?*I+ancS2;}k|UKNU6GcGK1sTQQVeo#;TPDi;L_kUM(PWQwVKnE z_sQ$0%sUBZ&$^obp-20jH~0tg&Vbd&&DSLT@pT$%QhW)lji0@c8CVG)EL+{(p`WdE z4v}bOn#C=#&t*7e76vbn@#HG`p;?~Q6CRN`;t>J75ISmop~Xes-lF7R*Djz>=7s{m z0cw9oD_~v?Vm;O&x7dLX*ZJ(*b{DekzPQ7l6XP1cQt(@J%I^8s2L|aS<)>cQbmg6i zhu0@v*|Gic%kKW29r^wHz{C*+mnhqaGeL4MKHi*BIANo=-Z88VBeSlIA?D(So(U#N zV{Hx_F2lMy;Hhc%Kq(UVPS2Nc8ohC5ZyADCx#MEscGf<1jczMt=6(N~r{ZVW5x8WWeThS`CfK-J_#Fh`%&0JiMY)v=AeK ztp}L4+e5FH-7~9m=Q*8<*avLn;tE)3H2K`!``g5|^llw~%L_`nnA}QK9a3n;*R%^wb}FDrLh?286f9%Zn2TFy{^ZT|6`c>i ztL+0OT*HGf*0Ss6cfZu{rF}OQ*>wGqwXF6$+d=Q)z5}W%>@U?6>f>YMrQAEg!}YN% z;}4a^wJJ?0SlvB2yit5ljUJYDekY+s6F>HrhXX!Z&FhK|^83B>Wg1U|BF@bA4+h4{ zCnolgxGyb@$Pkg>sdkBPSK-I{O_dg&i6Jy|6;^hS(6PUg-11^mD`(Zu9~Pi@4=SjN z|Hg_BN zA&)8~t|VHn@)?4Mh3qbRitRFdbES3kkgwnOi>^mqH_2ZcwK%47J#=6cMX+e8%5zIf z;#Ey@`!whuO!Rb-$OeOH^@^g)y}D2BWFKlU5`nGF12yN|B7cqeVIFcHzy37r6g-v4 z-8ZB_TgoAYaC;L9{PC4@Fka~uvnFL}S=fg2v6 zRZu(?m9eu1yb5ky%#bfJ7mVPWlj<5f0O&#H>;9GioXwajQgE>L8dSMb;S8rXiQLIv zoS_Q6o}#gtq!b|ahY490uKg2GZu*+wz*sk~zIznP*|5|yeP|f2X&!aNeY|;9YE6B% zV4FP?QS=fQwy$b9vXuAStd7}lejs4JL7Ou?%dKczMnS7P#Hhax()e||2QtaVQWA^_ z)A~z>+f6uS?DM*bM%I{8ONM|UN*QL`ZZVZ}d}gvRh3Z7@vIw*?9QoX`_vTOFF_Z<7YXDUMcvorr)+EDAYb3edSV#WE|V7Bkr9~}B2$21ivGKtMc4{+ne|K1gI4r65>9NsWM)`yA( zhtn>RTmfhNY!!x+kbyL^JMU7m_hdg7UsgIFV*~@Rm1a2uvw3Yf3voHm>at~NP4|}& zr;s$@9+6CL)Lvh-?2-+YdaYi%QrcK|xv2`i7K(OF1$P@DaKsHeMm<%b@I%OanRY9M zTI(H@x)c?*)OD<@-3ZR;)Z)*%xAhXI5>MWd7|4JM|5>&pnj%JPx(OP|KoGSSasf>Z zq?~qm&3gTp&MUmKSdu;NsuexYh=j!$`#NQe4wD7Cku$$B8|-PE4)qmgq{zG$~%lAP$$x;$dQfFxb!Offb<1*;XnW)-VSS zsrbG=^H~z83Vo)12fV+=Re3$>Av({adi}y>jlA+butk8lM%| zr5i}v{i@+iP2E#{uvJC?(6+d6Z>n|2Rr$h@3po_mK0D7_y*Vr0=Ns%FyMpBow zXqDYnDCmLH4$w)jyP_iy+{h=&!413=jU|e*cpL3#gI-erm@-a!s4%IzSCOxrZ{1`sFu(Rzmrw=JKfThyF6O5i6>Hsa?~&t?qTK zO2Ed|PaF${Vy#ac_v)Te&8k@Y@odnhA~ad&RjP8|0}1_8CpS#)uBiLfWozR6a!W}< z@|N8~LdjEO7c!trz=+5f@s_!Shzd=MVp$ipE+EwRjed{=C+~hkkUFDIYa%;duVXSN z%maMskLCT>#R2DmW2`_d+A+rbuD5FQy;d74c7QniB_k$i!tX~!fl+ zt>H;Gu^)^yR&Cu!4GV# z$m51+@&fQYVY)L8`yP!7FaV(YiBRFJwJx_t3bKqz>)O(Cw?#&*UZPU|QVrRur#qm> zFA%B<#Z_QO_hMN;U>hdNR&M5Xb2OWV?#<_*D(n~4+r!nuZ8u0tiN1{$cGt4978cZ% zm*zSC#!QjXNbd*LGt9H5^2CC&2eDn200!k2TA_ko|5K}r#>NDbTPAme|BE>ld|6-Ms2{>Hl}^yljNDPFWFhzE zwfH;#&)*RE;z^mA(&SyiaRi;zmkMoXO|drsY}TJz0-FkD^P6G#<8RDes;NXNz$oBO z9$6~2Eupx2p=bP-1wRX?zntTl4-wAP5^)lD1>c7x^z%kIA`h?T`uX(njvb3A_E?ll{3z%Vnqaj|+ebOo%VN+=?Ckb631TM|QlGb6eVVW2 z;@Od6F_C#ZZCHJ!t;g7LE-A5DA>B)}4m*^WdGPrDQ5qL@TpY7zem^3DM@zBPG*){~ z=cEcDD65&o6NdBgBwlN!VPlA`tVmmDoG?(@VYquxO4!9$lYL>G-lDmot?3sn+Syb?XTbv zB`TWD0d;f?cThKZYVauKCn{jhBFuMqgb%;cL;jl2g0ju~^KSQBk1Pf1&Q8vO+?AzM zJZBoU1!kCiuvw6{L%+`P={z4#PiCVG&(Iy5$-hN$_*opzW~N|AlN(daWn}a41A-BZ z>3VH8HI=uR$L?%AJ9dy9Fyg=u8aa)-Pxo+u`}Wui;~-!@3^7QNEk)ovBOX6J2C3?z z8>k7TDW{@yMGB2~ZkU(V*apReCud%AtIss{Pvwnx4HA+!P=1|=%AmN~^{{wmub8W_ zbwD{Ay;DNjOyh8cFNT)EEYtGQJHW{texOTs+_0-gC48kp?e5}qtM{Rq(xLJ4Z#)WH zw=`sp+2D+rEEqPDdYSCC;b5l4{7Z?Sr4d8&(X_Bc1#Y2&$PqI$iKgLV7Vj8yeT>^D zN#5w(I?7~i$sOE{`%%kRw(9V~0&2wZ*Q$SW=2p|P7kib{E)4JgQIt!7(%E_NREG@&CX&o@PNhz*@O?6oLorZ|aFeC_ZJc8D$ zoEMN5S#5oX=xVQe)rNs04G*R|oPcBLO27=uOc)*~?`)2r4<>9Y-V{2&czs?5Gy=CX z*E6y9iZuvvc6$-;IEVp5UO54yCOYtZ!a@YRGOjPy2M}-+TJ7;-Ya+f3{`L)v^6ftZRp1jH#$Qx+S*?S>!ZMtA$dZSm3-QBDDS`7&P z(~XMN=yk7EvmWR7wa!>vfvcS*6W$fJrCWOC?Z-6lq0OCg4S*JQ@ac_SJ*^yu$fb@e zDbE=%TYR0ATL%gFrr^LVL#GMGnP(R1MM%(&i3SZKcP?{Zlbn8I)D1lHCFpH2)iYdNvZI-@ZFB@wDO(ph zUL5C`Kor-^;hARJIvoC~?&Q9j$r*sC73%jcEEs{%8WX!4dkYH zJQcQzLZjVk(y6^B))!U@FDvAOUlv;(Fx`ei2op3%(M)JGYX=9y&4+3ZepzflfkxkD5X1ssR# zF*9PgEa|`e-@k6~f9^vx|2Pd}TWpu9ESr*j( z&aAO}fZj&Pb~tgch3j(^Z@6!Mzsipr-m82zFCo`uQ&uNTv$e7VnF>Jed(I7Bv!V$H zt*NXk)mIcC0`})w04a90JNnaw5e8l33NM6%5_}zPsilzEy%8EEewFHnFAM-nOw)+o;l8t-_R*hoML1VPzT8{=!a z{rS(;cFKDCK3;;SjKkL7O>Ar!UDtJVac}f40@2@gZi>ueCl$@2l$MtZgx!j{#XSVz z7RmwWIa{SXKfxn-FgIE)#{o5Sg(&n4hjczxl;Cf-WG%ks&8IP9)j>>^C zi=ba|1(G9HX4vM7T&7NEwO=52q!2TRzxL_}Bk}AhR3_(S^UN1pDilXQGvHUm2l{Ss#Ej#wSXKD%Q{h&=B z3XaqWgbln^|RVIkd^E`80F&$MKN8QK1gL zr&vKG%Z zgu|oYHzRiNgzj8xeabU(s-8E&!|;@r(G$1c)=M$IXLB>RUfOCKiC%hhyI<>N z@+9xbjTdaWRryK@`HETFx5mvDpN^@fU%;n|Y?K+>X)dDdVjFhT#x=e@Z`3@6l0V_E zQmo2-D>ILy6UT7OwUA}-kxzYmyIN(I8~Y>qq|WECgRq`R9#2t1NhC*hZ~3cHcM16r zyULeSq^e~Gk1p*Z5C;P$8cfy6$b!%oeZRZ=W#(a1CF;L6D4s_t0^@h->{a_!zTFy` z@MBi7P8j?Xm9guL{65!tdL^;wtbqWbva?f^Hh-%EklsEgiM%5C0)ewx%Baxmzzq*`DwGiSgKhaPe1MZx+YC4a?jw9XhPky z;Rn*G>~8OuhkH5PPfr^A@v-CO9ZYX=w>5@)Wp@v_e0Xx1vAgK!!;hgJYMb6w-Z83| z4kQ0)Ii^dOxaB5YzGDMv{(*Y!n(8BkUg{M6rU$qZmt}I?FV-8(w`v{^6jNw-f9e&S zv_t;}tLXby%_*O}*nV8vX~L{X;&OAPzgF)^8qrBkjyifx;^^l1FX2*`#|%n%$ULsy}-?HDYb zeDWpvh$ZLPCsN5HC!LIv z`QLN3FE7@hfl~$)fjg`rEiDKXOFxT)bF>+TFSs`#!+ySX7{7}04hV#e{qYN_zd*Zu zbk&?Ecv2%(12xxn+&~Zd4L9pNR5Zg)9rLm2 zW1}}eKaCTF3%~EwHDcZSjX7OZ;H#Nk#>CXJQSRDBi6Be>s@5_(6DMDqC>(>|9a=Dq5;a7)n$sU>@ zT(9IAy8VZ@@2(LUut&jj+^`Tw*EVP2vR~=~A@_sB*_j+1!}$x*L6`WL=Or*_0Mn``7riaXz6$q#YQrVPbpW zm$If>nY(v=YNu9_Tfe*u<-gH z_99`pUg+_G8s?WxIQy-|R4&fG$o4LbLtQyVsI5*P9qsf~@TdR@79!)v!wQ~hS)Q#B zmsQ|1bs-~#fmR5ex^2hX%_D3%JqM5LG(zL7%u%nNO0+H8Qz^TzvD#aGaU!H@qN6>q z@Uu6mO7CRgTsC<=tiQD0){nNK?pNqPG+_*vLc%C6mp<=-SiQx5QurtG=J$oIj_@xxNA z`Nkr7ayPCiL4`bOy0`;55vA`WuNF1!xS=G&-=z4ybLiv zvBpvVgT*6^n(LLW{s@ab%0jcbn^=Kd(e~T>=Iyv2UEPSg@V;Ai?w5Mk)sdhsfY7a)Ihm zcye1u%HMas{j!^Fa702bw3&BKOB9=8sU&HKBS#L58a3<_egw&C;sw(U8+xax(Ej)v zv%EWUMdEcoVny&zAsUIk@C#=0y6=THFizWb$@Uxa26pisfRObzWG3jL{>5+iUW5Tc zwBfGQljG`ws~jwZv%~q^$skP0kGE8A^Yi#b0D`QiKgLU9mdJ%GuuF*1W!=2&_GEO% zYyO_)0cQ@O<~nJ_{BhBP-|a>X8|`~X0Pi9AT^1Z@&Xf9a>({QD zpJ$=kg==Nd$4exszVwzrJXHk9z8N@O+|ST=-~NVl>$QSa-eK)%2%qzpRmSJhOmj9^@7Wwc3*IWbCNVlzPj6eyLVODl6m^88$OIaAR-V**>R4mxOcFXWI z?=pK4O-eg{aX4>d!7__1=fNmVSM;G$ZFkzJQ!Eic_p5}{NGgcMV-u*l~BfI zrrkYmzM5&#{d{9t{PD;gknih)>bw^)QlPZ31R^ zlsN}#?5Z?QZxqkRSCek9ZK!XCoeirxmx!g3S>N3u{AqX~yXg?@z-m+BZ2}g{axKxS zg(0$#k-y83Fz8*rXGQA~ z+>s0>=dt%$20M8%a2RNq5PWuWJT(^pX+ihl2ka2%_I5L!cE!S#z-Ek)qW14*lz-WY zb8VZN#hWLv@Tw0pDitW^2}^|9JR4t_tCuod$P;i&G#{S+9>h z7h(Z@Bo93a7}&&fvzNksfM~z+v-hOc6-;jMfUj`;NuHs9_rh%?nsn!!3SFlgKWg`? zGHz;6n=FzqCy0}SCGH|N9i~son)46bhltxq1r);t#y>;@7d8xeUkLrF_W+2-iN7YZ%MPV6@*m!n->IWLX?{--*bC%&vX`Yb@ z1LCC(tXs5Xa1d@GtWHO~#|ByhZGmwrm0mHj!d-qe_tgu2M@|blqb?zgfsUf5a$Po` zz}t5k8G4FepE^9p6&jx1@{s33z_vIXgA5@dGXzhzgnF5_MUjRjzO$iytD08K;U7d2 z@yE`Y#*KM}wCVMgjER#&R5GPkGr4fhd!@5LaQBG@7MDl&)9;OPQJPQy0Rv{y+waTPeE(h(D=D~Q?GvD zaSMV}qofnu*ok(AsG-oc#J8;6vJT^WL2{YDF^3<0J@-swN>|MCknE`BGSkiF4x7qW zB?g5*C3x(VqSBvHPiTV3ck7jDe2fp*WL2?Jh)c8Ii?L6E*FMEjuJlBj?w}+yuCLo= zCTkjCd*#7>?hc3@%=S&q>OE=tKN39o)W5M>^^X2Uq zj+{GHNQoEU|HZC)-Ql$^2YWL8g_d6j&z+McGNzGf61{PE@T(tVIo}Z^;dLF~aon>M zA&4o{&!h+ynY{%k`G?MCu{-x~_lt_Rj>0x1MMsSi^3Otr2P|kfN^xFcAr-IB%T1XW4ZA_Am~=sk@!%c{OWMt91~-;IH04ibw|SW}ex# z(6qzOInvP^vbbgd2%VmY>F8Q~*PFpTa}k+DEJ8lr=q@~2Ll9j1QmZSRVzOXC(V;1V zi|i3_l_Y7c(a5t;g%;nTUi5GXGPD1v0+GgIZNq4dz41z4V7Z0$G+yK{88hxN2jNDY z{6;HMsn!Bt9IFDU3g)d^0~6H=tY2T4S(mjjcr`X-vC{#$L~_ni9m^ zNc7S6PSc#perfpTW>kox%FLMWxN=Nh1%>@-OON&HF8@ZD?)L}5y7%8QHg#%vDX~=* z0Q5!n$;%LynCj<|4tfpfD~vvNz}`yWX^59~35uU&OwB$iZ{G-?IQ7Oy zb9=nAOn&2=;Dl}CHWCJ!ur1m4Z00A=%ZT5lU+x}W{i8|Q%&@BXoaf=8Gwa@%rd&UC zNGA`pavoZ@fGeoMoLJL(zwtlJ6t#`_r%Cb6r78HsQaDJ;Ib8bE11!Yq-^YZAOkovB zC~^wn*uj5b)}}a659xz+Kcv27X`Ow=9}o$d+}H;iD!8kn?bwdUQoR%Mbm_mv{>RvI z;pAX&^FZbTZn*K{O>m24^&(CgHt$%)kEZs!T z#^!o4kQ{Xp)_Nt2163!8IaiFO9R!ixdO-WQ!Egbc!%xioP;-*|v?l0j+)~K-#U2^0 zF9-v{+5SDfWga&NLA@4eM%;0()4=l78E4g62wVqTH*g`SUZR{M@ReU4FTXtX9^l{* z^%%ZgDr0?p?FcAi-IxEKvxm9f5|~qia9pM2;uMHNbN)u5WcDrtx1NRp`m6|dXMujc z2<;7Z^09!S1@xB`66wPMq8f5WR5WGF`LHQl7vE60=m5efXd0Pu>49{dx4|-}L8^tJhL=qCqw5IhTe%`wD*T zI?$$9e>?EMFvZw#H-L2T)2*SZVql^ErHY{o&4L9F0%2+O=G4~c2Mv9NMn2oLJl||M zpOCAFj8eAT{3PrNDYIwSZu{dK+&jC1XVdFa5iC-`)0g^A5i~UOZ22a}=3{cBNtZ9g zmZwz!hY@u2F4voykrxB&B8tMd)rVz2qU92cuCvXviMeXGc@;&Aeor<};4wn`h zb;aZz`;7?%Gyzx2yaI z<_BUVqugRTv9Tj{Q?5qyoh&FS!D;ezajgL3;&(9Tr!cW>yT_QTO9pW?Gh=Gkch6*R zqu9P_=QZOmp2%g1wK8CjTxjKZ{^FBwv}D4h71jYe9;CMV_2u;UvO%A6S#q1NOO1PV zt2~0Tc0YZztx|XE;QL-%303NP^SGmw`9nb~j3w|N6`$>5&Fbt}-oGEO;w3LP8x2X7 zQi&IQM(5vI5*f4(tUGX5&E!rX8Qf#4O((91XX08U6OeRa)MD_#x|a>szZ*Z$RliCnA&eQ1t(gn&MJ9aL!NJ*|DL=;@Q* z!>Y!ZnzKhGiK;|iyOf}w zPLP%Bv96*HpCGB4u*uwSCz>j1Ff&*dfa3SEWIjxa8vQ^#HSrTR zPElnmlph68&aXKrmJ3{D=Rqhq=7C(~*eRYR&^F8D=CS?!SDD|tfb;oMpNQ`{AyrqP z4H|Y&zkpBIC2lu7RkG668ck&i!d12dXD3+`I~4=(=R6yaEw-r50uceLUY8m;E8}tt zawqo5Nq{Wj*hN^0C_Y_)Oks(ysSFyZ2#5`m1jU=rQ(si0c^nm_NLG#cBWuR?Z@gY2 zd;@ZgFJb-s8t_+SbD`nsT@#Lb-f21sL%VAYsP`HNBM^50or{65__jq7e{O@Hmz1Qc z>3Z7?V-dV`r2*5n9kLhEa_TyxMaDv09{hbFe8S<@-Q+Yh)TjNz@Pvv_K58~vSbKj; z)CcumVACcFAw^;5vGHZ13>J=p%thFG*Q*z0*H}!A-d>`P0Yo@|CJj4L`4Eo{QzJ4c z<>k4%)I_h&iLoZ4sUR&wzyZAj)^DrrW>HQP2{6q<9%a3z$5X^^AtoBqumPM#8^Jxq z*r0R>Tw)Z=YDQ)%3Sw{>NF~uoH5gtL{W6Mn3owyW4F=q4Uva0_7@VEx|HN$2%>;X) zyx1;4J;(wB%6$J12Cpm1iy1Q{dK?!MPOsQvXh4;i9&NzHJmilkW|4m{!!?2yKUY}# zF%?`*N-$;9H<-nL7f7#Wm<@Xi>PbHyUyHw~V-_siU-) zC`YQ?O`{Ttf%bEA1F>6-B*(TIqB#pGBDe*U+iJEtr}gY{BCf>?aNvNRVj_WM&6~?h zxG*I+5@!5HEp0{?`Nx|&UOZ#XstI;FzahdQwr>$?U9QYG)AVcraA_C2>VObRg@O)d z5Wo!|C|7?KP4JRIfOE}$Q7r&nIvrpNAyMG&E3g`6QVNNLG>ZMnz~H5GkL3&AJ?s0h_2V(NXvF?|noH4ml zqtaR&{xPjEWlj>TGiU6FQfYb1`CU?qH+aXpgHuSw`QPU6PSJQ!M{mxRiEiXmctK3g z#S}Z(4-u_r!Ke_>znXXWUlKT+L>ZKb9F2U=K!pJUB;t9IsmAsItBwLdgL*0$ zAaSZl{b|PRbAbXw5ZxcRAkE{Z$93cTfF?kn(sM*BpHxKOp82VAz^ z9N8--QwsnMEj;uz@sN#{2pCH5NSqS*>W@P1cVv)>_jxyj{-??LWVTU!uMqtb|4WTV zE!Tk4*#(ukMMjJ~3~=L0^q2(Bg7^{i*qky=iw~+MjC3}8xNZn6_C&;pieY{p7Xt39 z4M$FMI~(?ten>ghh9onDMmKh01K8IZ%6m|S2HjKZ0bls$+?t8`#CTt7pzbXS$UsOT z36`d+g=)9!Yi z=Ql~0zbURZG^O9kYFM@5-NMP|i!JCc0;urlJ=9EoY6(Lu++7D9yZU~+|Kp=I-M=(4 zzUAC{5=}D+8@M|nb zs@U%1xplVRoCAxW90RisbIH~}uKD$&*Q7l9XXPFeK6M6`M`k{ z>W7=^jVNQ*4q>K`L?lT6TPe`L2HCk-N)(jBTaK6JuqECW?fyfTW1@^(;DR`#2<+L2 zzq`|d_Xttr?vdWig@?=z2FBk_8QA|ufjcjiot zMadbxFjwRH4>(RIc#TzOe%5Xs<-Nb;2GoDYn>+h~^=#;{7=%xO{9{*U7dIwvPZ{?0 zE~fW?vH4nM@KI2p&gs<`D3%&7oCmcvTLwze1L%j;liS;uVn~%x!SGVATV%|I04}LtwpXhcvDPXyAV`2-%)C81<$9H5^)5tlyu8di(qRS!@ z+1gl`B6=>-3)OGAyGSH_aFx<317Y(`hzU?Q(}(|NfRDW>^2UR&{o5;P9!a{ek@5!r zc*pG6-U**=%B!L_+FPqDN@(hu77bgjqz4aF9Sy)zrp;?Z9}aDexTn6_)ZeQvn0)M> zUGG`G5r3tv2}Ay8sS-COcdfn4d!-F91j;jbTy5M z^NYEzC#ML!|6Bx)8?%2RlDCTbWCj2Seb6VhCAnj}K%ZiBOUmG~4iSMrIPVK%k| z-0+zKwJtZyEm@BySW+uEvu__3gx~ae{|{_W;r8)=V0q{FT&Q};iC|J%<1SUfDsqKx z=tj0*jPC5&jD>+A^T7!S1 zD+#BRu}&1K8chIA=UGD?Io0%1J@WS!IDvC^`|i>tWcXWLF8Tz;pQt|iRiOIg_Jmtj zU}3B?bj#Kihh~!7qm85@##EDH&9JB;o;ROmCBs(856H^{{z4sXa2q1#$uW@7nWnS( z)-=VYTq@uX-_Lyn9%Rgs7XZvf*Za&bLUj5Y3uRvS)K)Fks2_g(co*Hxt{?;m8aucp zfks2mLoZ*a(hSe@HtcAU@@q%&1d?H|ieb4-ko}t8?l+p(dv+pFJp{(Ib?u(2+;V94 z`bl*gmo8gaIKrSU?w3$uyThA{u9u%_uJ<@o)Te%0BOx@g|DEfJ?*?fphKPm>uKCRQ z4Kh4^K(0b9MOez;(H+;tO1(Ol?QA^ecG)LY=$h?@2-4tP$UbDZ|5fBV_rUrNhLU6}`)FMx6-;P11aU??tSUBa{N1Y<5~ zF^7wDt(ag5Rz>k|ets0qPY9sDjk`wzAd~qc-;Kik@fH0Wp4O~A5-QM!b7u8ye8Tm& zZrq9(3E%6M*VnwelI^(0XDo7k%A7dxL|qj&8ha0Gr+F_t)~lmt zj2@yPnbX{Rk%gkho|eqeeao>P@o^;l23_V5t+^#8`tUQjF;58-_t4>yPL@g z_EkK_g_Z7C69evsox^RG+726v6O#&l4wj$eXlMxv-O$jGrR-8QiAXChsrTtoq0tvo z3Y5eINk)nmhg2-^`w??4yvz7xcu#qt7KXNs+<8*d$7;D zEpJFS&gBOk0SBu^1V#W-=2%6WUPb|Fzy?XTG~DX&W%Xiqoy5I+qellj?{+jhRVGdB z(%gMeJvu$p;BblA=AqdA#u}Oo2_sqB)zzmpL-DAMPmI;{EeRtT$}b7WOLq*qK#)2PqDkfIZ05U6zHTF6i*`2(?Blg zavold%|6Y67wTIUXFGvU1qJ=Amui$J$;uVuM{LhQsZbV&4?R$DbEOeD)G0Zg?(&2A zIIo=ig~b^x6S%>;3XC8w(`V2i(Mp0y0BLEN%hp5iKq`NG&trqtJEK6Moc!cQKcULS zgqo88evvXs1ADIyR)PfbThB*ah-tK)JZ#5Wx{s z0>Q=57%~5yb}M$(kn-&u(7iv3s9bT8uEHlt+^GSQifb+}RA`MpIk2yNu@(OF27aaH zt*7r+Hb|ZUZ|od#pfm)j{^#ZaNBqNO(FS=d$jd_)SPOLCj}}phmSEQqrJ_!H%~cOn zjh=sC;1`uJ59^rkv|e-vZeLpEscdVE=siO9K7HkbnyLk{!F>e+Fl5btuk6VoU|c?~ z>3%ER$`9>{MvQt)6=+UT$k6Nt^>df+%37(w^9cYe!4D_?Ools)>iQI!m3FDSDHfIF z1jJepk}aTN!%f()=5uBMU$cgtmw{bNOM<$OzAmK7lHXSV`9Cw>_FAfEcbcI?#V*Z42XRGqv~i z)Qx<_78&J23*ep9>_OkGyYvsN7fnSrkM4g2 z2rbTsREH_g9Y%ftlX{$5J_x~-%jRMDxogpbeDcyChJ;?t!$z(a!Ij9F@u<1^oTpbO zwUoQM+&DYCzf7B4d#UOFY1wtNL6zX-hlhFhPWov>&GlP?PxB7VmDR__{$v6|b2ti>(NFE~voTu>o2TGVOH zQ$V%_$OPi~c-;f8Wal{{52DlhZA#p;LWt`BlP_rg`2wm-ujQy*l~KFbaSRNpo?Jia z>-5uz>F)ZOd9)@$Pq*l~L9={ZvT@^inYZ-Ik|&Tl&*+J&z7oSPb#p0$6>S0CE!Axo zGT?>>ulF8d9*D3Fq?aZiws%Rv+bC~rU~j(rOTLUUwS0a9*X-74gR$B}264fWNSKwL z_|4|b?jA0QNPlA3|2BnzKqS!@QXdw|vrEgiIQmcCjH%bUa5PjfHT`PtcFP%T1@3Ij z3bp_fb3E!GqlosiE}iK^nUOdT-W)qmtmCtDy0-qfo{)+9;`RQX)-b9COj9-zyzn2h za46+M?gti?aRXNWz@oue$jZzk zk2G~c3g`gjjx$VuQ3_}z1W_WaJ$TzMA`TZU8S$gR#-4}8JhbrJpjg_C{!ANo1;;P_ zm=}j7Sb?hpTG)vM{JK=pp^V))Rw}Got)VqN7EP?n@3)Pd-CS|=n_B(mbyiJ{5^(#U z4QGnxKw@3~c^9aXaolSN#UQ^CKbOqiey?$l5;!&>k_Ro-n0e}ANz_6A!g;7}6{Y(G zs3dlX&n}85&OixzQSQG=vUyOJ_MV?Id*yJo*)=?&yEemxneR1g=9katM7|%=5}bn; zfGYpxJ9q2SJ*t1zwJ$jgaI)O)EJ`qx=|IAOFN^;%q2M!%p0=CAOqO-Gpo$L**mSTB zFUBxqT5^aRd)L9~B3acAb+57dR9isl24%{W4G+(q3#GvAy=mQ`0SQ+FN37TzyE?r! zosC~T>aTfKwNC5%7uFMOqtXx5fl~hJrwF&&$7#{Ys3|-d%EAsg9Cz2x&u4$4M4_kE zGRmc5PN&5;tn$LuDGIhP9%Mi|k{TN>51#HAki6a|IIW~SSdx0$J1nTta{DdV`D3M@ z&cp`U%17DG#Z;kLi(g)rRs%&%Irgg-zEH#yo-#KXSalwEdX*WefRrcgU^=$)cZ-+D zcBwb7S0y59?E=&Gw)L#r@%q*J9L8`IeC`~P)rRB)59C(B%K%I7Y)(e zQMeE&wl6>am;U2+M+Et@X3y8|uk?T`-PJ{woHvZEItpV!m+-~DQUd8JyE2Hj05;9PbSreO z8E9p1{$sxO(&b=tfmL$j4dKX@A(qHYDb)M z?N(Y`zP1Ls{g&q({`al{Crw1%)yrXLoAZunzB9hNOU))oc03kn71gVSCl1_o!D!af zwH(SguH_5qpvZdZ=1a;9SL&WslbMD4weCNkJLYG^**X0xu-01w|2{YPR+PeT$+-hG zum~c-n|u9U;cYZ^0RC$|BzoVOsp*`qq87yMN#Yt|<72Qa0LB1s@-xC~938%p^xyqb z?(8Dr%a6CEQ76J9TzWs=siXr&pEnG>3nis@)Fq{V_YRH4TLQbg-J^R?yKnN>Ty%t+ zaYLJ#1oPyokg|#Bl~2yxJ>n3^eMnroJ5jXQ6ma+E&gLq<^`EB}B7x>UA=(vi`&)wa zePAJ%)H4`3-~1l_E>rYS=HPX9M#K34mQwo_0mVjXfp;{|fAcoR0sQ*>ucUXGEd4LY zw?n|Hz7;ww$z0|IwXg2f0j;GUs{?HYTo&ZzYOvGys|jB)7uUVc;lAa+d1FKVzS83U z({mITOkS1DG2jDAV3y|i04PYI?fg|$e&_V$x9iF|2FB)5^tSR7C+@zd@KfBk^)e%P zcZ4L7Xn{5S_v#-1c~dfI0^yX18hKjo|Bf=Cl*APd%>Ig39eP*Uuu_d^*AO!Npsg&! zDCO#j50kD-bTv{ZGsqztU0p)mWM~y1?wp<=_k2HxLP&m(UH!Iag-)Pv zHL^~)>UO+)r1@um3vZ(rjSuxAqo+O?dpAyo0PD>5Y6>6|IfR}AVO-OxqroKenETs{ zJ~air7Oo`zn!+x5f6k0q@1ckqpbt7V;a`%dQ&56M_%GqIS&#XP?viuYUNEjfsgrU; z9hoKWxPGDc@!qP!Fu8H=6~Q26zZdyH?T1M1=Cmwi2Q02dMy5^V;#9=u!&Q8uPwR+_Q#rc*)`s^xWP0OkJX zf-dDLpGw6Bu+=G*m;n3dG-txxwLjkNjvCRWrPnvooIclcoAW_H5{2447)|{S!m|;r z&T|Zg$gu$S{ulN^QBG~W)~0j(Zesrt;G>$L!?fRBi)MpB>RvYRk(I}AG~s^b?FMyt z;A?%xnT};~;bHongF>E93Wou_K|OM#2|Rq^?!il=Ti%}Q8>E|%PVqB0UaE(;R`@~EUVB%6sGMYO+&3eQuX1HvU*c{h@ zNzNsbXQe?mtK`gXVFP!FGDBW)N%cDt7K65U5rSZIWj8vjTx%jzfswlXo{wy~R_F^q z8)E?ywZM5#4dcA$cJu2mz|TQb`h;t#&~H#`F=KLXgd?m@+F4rdqA-rVzE6J`90gQ~ z3(BKgJ><41uF1EU0O}u%gw3{qBKd1)k@^+OpWu2?-zo*#!ybMVp^8bsqV${z@&oSS zKd^y|ECR9;$_lXKdjaBoee89CCJX(PRKG5Ge?}gwATK;wL$p zozmXqdPT`uDs7j+_vp}0rGk?3tqp?9R-(I$t|?V?o-q%7(#rf!qZSa)-&<_r;)L5? zKLrBBy;e7V7rKfB4XriLyV1;HmD;m{^ajJFaFm@pv4v+4GUxl`RE7I2**{QmjMY>e z`F%Hgls%jpUQ0~kEJ$hrluSYtycz`V`Mvkc{nE&Gz2I1{(zD6Gg#00e)arXzc(dZe zD9&<8|L@MTtkXYNEjsi}TVB~XLmpE1z?)hYyg}?6jH796WofEZ^$s10Qk?jGdYwVa zY{<9P`D?h2dk^MxGP)mmT?KoLb6Pl#&5NHK3dSHmc-Q%;0gmj-_K{l z0cE5n(b zqW<6o)nLo|{6I_fD}0i&t+`mqinB*ic#Be}Ox^jOj3U&=hgbLgwo)3r)`r^|b0B~p zCk*3$!1YNXsp+6aim?kKqJ5y2iqXBkDAvK{1QL{_( zl1Zjl3D5@%D}$2{jWwr)d6>qizHduCd)1>FLI-6Z=BNpLhq-)WVe;W;pyf#1gf}-& z0?`#G_2hboXP-CH(-#=!lI4IxMTbBt=io!QcQr2;KEZY*PS&2KwBS?(7t#9*+W@H^ zwZDD&X0BUvkj7@L<3WiL>!E!Ga0XF+(gBw_pyr0bf>Tuy^7h(uNhh8VQBd(_sujJx zaxl2#^}{{wJNcj-;rT`ciOHLx5Gj;gogx}zK9$U?$XowAmM?RHPh9IddWq1@EAE$u zu0(Dy?*#==efoEy58A`C+7A!O%T~M;YZn2KGQQ1wZ6FUMDfva)4>q+ilS$!mZw;xW z9)jT0JTUD&PIk>(RU2~91h{X4MW3-c2T+9q)9!2Uimg{r&@M@qErIpDn1?@w z8EXMbX`(!kD(2vpB@zg+x@jhEhS^Q+E(-oAF*nFatt2gBj+FJ*vGwYraWBStQCM;} z&{>5rTS@K|+k%)E4N%;1Q!r^;3YH#?kh{#H5s3YyqAUN>$*Pg3;!2?{tH9@AO8@OpD5EpH14n{B#i>1 zZz)etu@P-iVqpa+P0Qy4R>?MOwNrFsGT61Hhg)TNDun32fE%E75s_abR!5}_$8yY~ z6c5(CSd$Vnxo5vkgrkJP{DmG;nFGuXFSY(+hQcO8*ZPWCcgg#Myo{8WT7m&z2|cu& zKEK+-0sh>6V>nM@))2cm7R!xE46C}3FQ(O)JZdxJ)>QhIIn*eBZ~R&1=p$<)r~TX2 zweWL490K_K_XmEk8*H_%Bbwj?n469pDs5cUzU)IfwPmezN(yY|563D~3PA_7G8`Z> zgK*XaziOlKLtT_XHb^IL6kA%GH7vWiQ4!JhFr4~q(}*b@N9KisBB6ZfF|lu70B?TM zFi!OLjuI;wAXzN5p{dNxk1a3dLw$FQH>p-f;n1KkF{c8mlfmx=gugI5*r8Ej@B)_A zmil^j`S3v!kTxWi4ti)rmuXO$>kFF#DgjBA_xRe4ZrsR2Kw_2j^mNWMedI1bw3&N~ zXxXQiwsQNPAf?~NOmJdP&*w8id(cX(%7x6V2ssuzPuvmaE0)7X+}WD*UYYnUT*<}+ z9630-BXyn&c^v5FxlUCn+4O@7Lr$KVfDR;SnTC-hO%SPsVPL_vfI^)GXsy#}!Dx9= z#_CjP$5EbMi+(^VEw+vdykImJDG0bfPVIwhen`Y&R>=D;2*vPV8Ri&8P$rl6Bhu3Y z%Af}YMOTuzbGZ?nXnzC-U7Y<8uv)SnL7;SQvLdNBV_MHOL(JXzi4`J9RXiyr76jzr66*a^h^2nVANrsQlqy>8!~pLcBs9Y;p$ zmYL%2zZ|h@+}xMESEBVAd_ceWj1`_n7T((O{9ki2W7 zEmb5ZJ}&uY>A9DxBt*yR?@5|L-*VaR^>WnoqwU>p=ci#&9VyU@Gd(?dI|uGHm0vvg zV$1I*UuVZpKiU54Lx669iu9KsW?xS2ZQEb5+`8zfqIhU|F=F>4(|9Vn&X3>tm|!2w zgR)H{hcl|dl27mN(wb+^ujXuU7c(0p2>cdS#n~bq>&50}G>9-c5|V+RV(0jm22RVA zDPh=sLhI743)chPcP@6bDju4H@&P~<`C2eFN#rafJeXUf7EL4@89hFGiSCwdGB})o zpX-`q#?Y=jZDgi^qpYNcjqd1>)GIi~bJPvQ-@x#~!6?zxi~d3vCE{xh606UNLKs`s z?eY8C;wsuBgao9nEmpzEe`x{Kci`vPsB4ookeH(#_c$;^Hm5;Sye`)0YpI8|HB_* zpRUaIZz*r{e7Jl0WUgvO=H`_FbD3p`kRz{J@T;Sq1fg2x^dDPXeiqlGdS7t757%(r zzdMFV9X^DKqDTg2J-s?*14c#)#T9U1dpd;oYiB{t!t};C{5;;{tRsALPHk-*(aKjQ zpnAC&cRAn?(iXEMmv_XSF~e}anW_6lqXU`KQfLFP=g*yj6BOhu29~HQX3bh9Vkd35 zQx0b`fZ(VLe+}GqQE0KA=qBQUuXwBs)HO}9_$7(`)RSzlk6LFd_dJ38XZP` zF0kgcUIB(4=n@XGP;9hYsLZRV%u{$TB`#RMo{JH=C$b<_SuDqTgr2TLr;SMl;U#)w z6#yPV%_CZc$>u-fi5)q?l1bl}_BHY1SGUhK=dx`F93`vMB##cn*8X0E&@aFDF629u z=x&HDCsuB%i_`sL*~gxpYxw9Lq@#yP3B$vCzPn8R13TWH%4{a3S_Ciu;MDypg}pQ9 z>ayS@5L@RWB%GJsT5}CAIF;c&d3cIq?!0L$%=R^n4^rb~J1C0~;`jl=F_=eb`30PD z+jS491sU@c6m!s4LBe>BtZE7+NV`iAIL|htkKv|scr3Zh-#jc#$}Q!J2jGi>aF=}D z{mY-;S}svaJW7uRRm%KP*fdU5J8?(6J>mxqaE2c3OB=J+l!}Q5ZrN*Tp(MVq0)$5Z zqA5)Hn%akfneY=f3yU1&*SA=vZqr!&b_4zGCb|FHE~70J<#_YAgjaYUWNJj*R7#uV zDjQ}r_@GmHpa+&`1?ol(`n)x0vn13ETyRO8Ua*0mCUtpZx8H)OhTrNhnetUQBUkx$ zu;r)#0jYQ+D)HVQ=S0Sq6Cu3t5XlGzZmu1Y;P|tKn5V1$3{;hi&abw}xT-FC4#%pj zqN@Vr5zgqI&JS#M(d$o9nFBRQm7q{%j_15w0IEVP>zAysw%ErY6d2vTaI71x4x!cS z%DFs2R3|osj)x`W-`(J2zG_8!BVY`n1oPmcP9Lo6Ri3?K`}#xutfKI zhmg3oT{N>uJXT)rBM?9iaV>vD+!0AO23155XU4K{UUtcu23lrWvPHf|1(IAb0a7Y< z60LXtm>@~eiY3QlvPq67HB~TR$gl@d5ITD3AK0MUo25CofIwRx(WpAojVHF;hmL_c zQ4&kD>BN@ma~PFO;P;9M`Q(mv@*+sVe`{VqV}|8AeF6aup$O=ic~JCLzJ@1aXj}Rj z0%;0+5Ijom$1$k0JlXqyTHKebLS*ySWv`I>tPwyC#`@cXukvAr1hPuR06}qx3E+T3 zu>^ljCnjZ4C^^d}$6Ogf_=;OmSWFIn`JWa32(a?3*!ssZ$Xxcu z)qyDkpi<<{$D1h_0Bizj#{j2r>7~}RN+?FCR;WrMQ%w-lP@zJ*X*vi={`i+cyC+hg z)_@q_#tzt5mNb|4Y!f3N4TePI_yKFC@SAt%uQ-a#9w4f~GCN}pG+0G%ba{zSdK!_x zVgsBeRZ^fQv9dFVU}`{Mmikb{W0e|HbKOt0b6gz1#^A5Zz|N8JqxbIi+N3cSCLTW1 z76ddT5fO6F$K}`mV$&uDYswc&zW{nE9W`-a9UZgeiI?X$JBiW0s6+ z)-2*XMO{S~qTYW7VDqU$ih_XOLE z9{CaZYp-@YfH946VA9*OaAr09w;)p41`tvt>%pH(9Gc?DIf?4;=zJ84!j(e*W484ooB&5%#`tU^p}yaZCXFPrm=yCLTnSf?ZlD9CzWN+IkZ~mH zrsk2yIt3q|ZLRrYuX@fVZQZ-=Ck*^Q$z7L9Pn%oUMXI=B_T}(^>Q>ErmoazlDI@H9 z&PZn@j;RpHrk?^;?mDbV9r|MHvU}hCQ|}(Zn7;p`vM}5;v7_6yO`qLd(R)g7;+LB7 z&?Cv{7q&OwebRI;VjPt8i>=%7>A^!=$#0*|tu@;H!0)y6trBM2?V&?$-EU9q(y6>p zDwg^FaYdR1OvTYmANA#eXqahC*dyv+)@r649r#>jR%nx6U_15s}`v&bl8($aBW^T7*rr#i9qiXp3a%7?dL|k zRg*<=`7g`Q@^vZs?k*<>0v(~YXVh5ow@-;3z|XCeC|)~dY?8lwcrM% zA+#apZoTjb;KnXW9&RZ}dkELe7uu^$@rt{Ermpx%&pyl(T2z3_D$^7bdWxDTw#RLY z<@!EIjHmKh2TNqj$CeEO$RG>9j0tQ2Li<;YSTXJ)9VaaBx2)m_R;&w6fpCQWBPRu} zBbUgaTh!vYY+Y^WaWLs1&Zmr~bBkJLDhQqQEvE@CD~$@Sb$0D{WiQUJ2bdp1Tk%F1 zZxK5*x?j#I7sZ_ne!`+!kh-5Zihu6jcIRz{PRdJIqRGcOW~v#lRkGrmTJ=NrgdZv* zJM3+HvmkHa%_PPDevkuQJKW+A4y!}^6{=e*kt7u_ek>iUi zFQ9+-jP0sdX3tJee+#e zw_#o&m1ReyG zt-b!NT7^nPUPtCXu=s_fo_Y@0S!9B)%Tu*yqwl$Q@Mi^b9kF6m> zBhQ1D8}8imMea%~z>p-5+#IEgYzaUiLWQA^bVq%FTa%6sstJL}5=OcRg+PmeuFqIX z>s&nyNJ8&f2F0j8aKY1L;t0>OkXoG8Gzj4^C*QFqEgr300X2azkDbHo2G5J)Sx+Mx zfQQgvLo`~!8`tO78wC2_&;qcV{BjN$a<`r^bZ~w)LQZFj)jgwX>&E~y6Lck{#5<&x z2dPF!4W!1kz8$QvHv07ZmetM{aX$XslS&nDbM~`~U@C0%QBVt3zc=DWU0%0zb?V7) z8AJPZR>$ACVbM?8KhhcKc+lX|yovPdLThKpP6cIt!~MqeR~Xe&d&^TQSS_N)>gz9&6Ld%Go1(jF`+Q!Uz<4Cy?U!0e6E%)_INd2Gqp8ag^Py;A5$tZjhBv%2{V7mmp0%tKa9vdKX4G|aFXNmk>AJ$`! z#sKtGvZNV$^C#R-^@i0T!blK&0Y5 zdY{LAlAKl(@{eKWxRU6xx{vd8O11%s+ZS^`_Afpwg+u`Z+kuyS;^~QHHJ})eFv4Yo z@AM=VoP3YUUv%CcgCGGLE^;#PA!Zl=MSX*r2SHZY7T|>^4b>}!y=N8>^SuV*_>-cs zGLGWH`>-MS(b``mO7;ha#qX+O&A-eK;;||#Lc!*tm}C~o$o-G7I?$a&y{q7g(C zi#Z0ikfjj4%J_wnFA!UipRr0(f-^TkzT7v*9G#S&*8J=Z95k~7a|*`x(N6V-f*oNi0%b@b zCHtEMDCqNF1p0<7h+Q0)9SHwOM}pz6kn0ko*3uRl36LmqHcb$66|Xyds0VPx0W$;0 z2t|}z;0u6vX_vzIx6fX3g3X!IzoIJ z>m5GVV9Fvv)A*geG(5#JuwdzXGG5ugH2coR>ihm!RVw|Gc)iQG(0e3=G=DdG*NNlv zn-|wws-FLI>!lSINtyMY4+;{Or|S)QN0e$U9>;xRYovF@8Ujx`ez1<=YB04dKOnlp zfv)z|<+fO+UL3S`oAgb+%*FTWiAVY3)vejT&aN;aU2+i1MAQrs`PVwXCrcV`;r`G+ zYoDGW%_JM=EkAJuJy}7{3xc+RnALHP!N#xHpizEQh{M{!u<_K|Ac#!l)=M{oCS)^L zCg|MYuSheNz>WD*-EL3)aksPZEB2vgQQ(xz+4qUvm!%nKi-uUr&}W#3eU&fGb-Rr> zaI{|b3E_jOI6MD~toEI6fS1w7Tg`j46uK}i*Oq(q;!vSj7THcRO26fTEI5c<=T_Ii z9t2UJMP}s-c5#;w?sAU!Ufvv%fd0ssCdqfy0>(I=8`{})DF8~8FdIk?W1KTyY7y*kiNxCH1==e*~& z)=u-QSIU{QM;9=T0Owc*nli;>a0&V!AOe4H&QVD)LwYBaV8A^SaCMGvoI?p`w!8fU zOH%{GtA)o)Xg)%B-5#ScBOJ5AjKNPOK2>He(59iRE>>&6Zc09SCV#k8Sfu4I>_^tg zU+h@yQ7fZPwW3(bFfSPVDAWjAol4L)g8+&uA7ZUeiR1%Dr+LtNH})wyoHpHV=A+6b z<0la#9l&X;!_?McE(R;NM>3F3T!7e&>j4x1RG*&;ycTyoe=}z=l0n&&%i@bcw$vZt zx58Aqs8mcIY$Rf+YfnY10Vp3!u@{;EE2At9$k{otEjpI%-K9PDzlR(gEveEVwW zo^Lvb)}D9Hb8c&h<9{5?GCKdGcG?($xelP%d^;;%jD|%mtxy4?rkz2tzQH@<@~vL* zegxE5VY<3|c0WnYX1mQSHc;u^>@{pP5|iuHL2Y+AGDDl)g!SN(09$8rz#_VFL+!-4 zdafY)<5rkD*%-g#ZZP@TJYbZhAEmP0mz9<032Mv}8IrZZ!caTciJ_rco%8;}{e#}r z)LOO{;e03VarH!NfYqD@(RI&MP-c|JT@DzRwHuYregi+s#<`7Ancch|)OoxbMixf$+K=M310q&sn*3EP{-N;nz-o0U_Wu6}$ZF-p35co0m5+x{di!Dy{Ii2}m+MA+h)b>Tci% z%64u0`AD5AdeCuYdxQD_e4yunhdbmP<<9>d;IftOW9i<;=DQT>Z%REt`*=g=f=-H!)Nki*$UoO*YkUBNpMN`#mMFBB+4QU!+h6 zky(>Zq{Pbcj%rcNg8QooIx&{ZbrT-|m z-wjfOHh3bOIc>7|4@~~_sf|gf@@(G7y4>tjp0`e^s6m*8Woy1R<}dSPJ+km5 zbTBqu4UKwbA=vNU^wV?w5p9nw_-=p6l&5%^`kRW|;)E8@w`|#d{CJ8=NP(E~yo46j z1d#9oFv9ZWimm#GfYKtj$)hL#ntnjq%`kMeI$jwG)lL0iHrEx4(&B1>Mc z?Br;1)(|7R6BvhOPkQCT$TDCFZnBKJjoZ9EZ%IwL16wjeS#ocwRhy?H#8 z{r^8|O{GkWB4NrBl4L1MF(e_?Sc)PhsZb%=inz2$maHw3j1p2YEi_6Dr6@GYGG&{x zGa+UMGiI*)yoT=k{(K+jcYf!b$2sTwJO8v8b6xN2eZAhV<@s8kgGJbW>)A23f@67B zk=W}+&TmqYpRv1u$Ca>vWyi6 zNMA1??~p32*`Fs_FmEr;wCfGVz3aO7>mXiuT=n%osCFa;0Ez2}lZa)Foxt5N&3eQA zdwz^Kb~|`!EbJ|4=7uRMT)BTLHTDH@MT~=MhQ9HwSw=z;e|*{tAE~V2@E=~8o+(KK zyCuHP?MsSP4n=hcTpIy!{kh&o~=(kiy_(%wg*R~yc-9|$+{a^#BNwuG{}KaFjhj;!F-%nXy)zEl4pdy4+DgxtD)@li;uW^+L~6XsidKruL0fqd0D}1iN29 zQ-D`7{?s)Daj2aMdgQ0}nK0Jq#ZT6Pqw4}^>Tacm{($Pzot$&5Zx5~V&UW8TUtM;K z#?n6+RnuebZdm!Z-~ILNW|dDAF!GT!^B+T-*|czk5ZhD*Osh%jCy8N{5T^1?bgTopgz ziA&%ln#!}G56<$^ZNyo(?@I|x`;^_->?JJwZtXz9L7{|*71SQfbhlM{dgkx@O5VSc z_q(aKG!3nf+wwA?N@55;3SEnlOn7kV_kbw96c;U89=$evlWD00?k4W89AI)QJ{iqacu-XOfb-vLUn!Z*Tux)*e(tUJJYTIK+cStf z1hK3?F*7K-D3(EkqaMA$h7(EYm2b86H^CKMI{zM>f^E4{w${y*a%p)zes&K8*I5$E z$4uKFm$A4Yb~I?)SLAf{wu@E-#;9>5@-^yPQrbuo^IJ#_jf=gCdxK|Yh;pC49nKeH zveY;WH)!VOez@&9d*!=Ck3cor?<41){UsF6g5HlCU6W|Vc<20MNi<>(vd!Kr{4b$f ztSXyx=jc!04t=NWWF+Nk`FF?z_0TH2V1L0Y*}CcVsNyN4i@%zu-WNfUmO)FFHzdu_ zbC76x(o?rkp}_&+7m3#Iqzt)U!~vVU!u(V@pFy&4=7mOth~NWl+B&xZS1$I`UqW#x zc{Pg)I+WdnRvaM*sLQr)HCOq8`Ea=e<96lT7r`P0+vn_7ty{fQGW>TTD*c4(TD#oM zx?b=EFudA>k2@48eGuqhhJrcT4D*Vh*_CNbRM3+HwTFKWSn@819%HI%KS2%)QX`kI}a(dv#?sMaaU?2Q{-*14ZBDw?4O)mg^52-nV{UrCu*%zirt= zF9**Xy9~vxJ>D!UyWq5{c1@hyW+|vsK`FItoY2WrLH&(mcleq+4;;R-|H8eC{nhte z9Z$LYc$J2{jtPA_CdeoPp9+Qs|&Jc_wfR^>;Rw`wYn!I8VsxJ=)5kR(82OiRk z-|=BrV8h-fI=7E+?@x*VP5^wd1(n(^+UHk62}yMR9szSjEE^O^NE*0W6rXr`ir;W2 zGL~^DwVX@m4m(^2ysRkcu*{|;j?c6&f~pZeKfZ~-KU7HL#C|k@z;$T)e6_(AerUqv zr`hM;Q07hkw#&wwo=q>V>ZC@7P=4}oxf>6L@SHi5L*9#7SnGEB*IjzY*?OPu`Y~P>|Nxqm9p) znOb(;_arJ3Q8fE@lctfybAp4_51;+%o4*C5j@&E%F?jh%ve(!+`ischW9saWOMaD8 zj=DfN&=l%R9W!J@W{rn8sp2vjwy7>Y90}ucQhvQh85!ja@gWi3jZpDn0tqy4SltE) zeTRSB$bU%e^O5Q7fh45<1*<^ahYP0~gD^8TtOQHI;Eq~R-SG%ojv;J}q7jpcBoeq( z4Et%s%{**H+pzeNC)3A%Tq`=qla9+>;CHJ#wm7z!QNpFx(4Qn4g$*XBle9o&e=`6PU z;DVS0XA1~IQJX(AO96_-& zb@G}OJKJ7KX6p3z_AFfRE8NkBeC+Y^)VQ(`SHx+}OvJyJUSFO$1LyPOWb)WFZURGw zH$x@x&frm{Brnt1gZ|(9$?}m&2yx&D)`70E|1}^`Sc+d2pw|R7pPbo#TD3RXwD&Ha zCz9la>-%RX<8O#Z3p^w7ofRcJkNTYc^!~u9Eqk02zSe>_WFk;P4J%Xj-@b$a6V&&^Y7gpOv5s!SO^7;0G8_T}Vj z!BG^{r-52k>NGbO#J20Eyw3UKDk-yA)IUEkbsG2pLK|@F%KDgEbER1Y`OU>=0B~`qdAlFM=SW1 zfV!ki_Y!%Qe_YEsmDpYg4K%2cnn1D5`FVeDAOrgC|7@WBACK|R*^PKjL&KocH5D0` z{^NPhsh{O!fMF~IXk!L(~pz}1Fi@IS8h+PCUE~{rDka)%^$|Go`VREp9+PEr?lTVDXZ-BaJRRZ)GC$sp+@v#`=G=wY z+>aZ(A|x8XTez)jTw9jhcWzacg2~l+X?y(in_4iy^D7}WF95ohjKEb2%J+YBi#x(U zw>Z_iyE3piIZPxBdA(Ra>m?z#>ig!9ugo%K89NNehdLwh@f&+K#!t{_4u@c580Ey} zfq_3Re%{Y@EZ2<;-lzUJ1_T_3A?G_6Z)~&)X^(K`#LqsiTARl|AIO7ScTcddHSy_N z0hLHJqM}=^G=Hh7vm&;!coM72kTGV`=pTpKXZYecgNc@l8Eo=gJr32d2)d4_Lbj(h z2x6QHG~T&GKM9DlI!pKsuu}PE>%qy6vBfD*OJvXcg zi~YbEUp_THjU&tm$RFyo2_{Q8Afuk|tFg=`lcY~QwEVhu-lX)Ix<|a2`ZCrp?Y1@l z`N*7wvqosS;OZdhfcFXD2aj32jyP;9}U3r40hvJM7AWE6zV`g=RnropiQ*QeVD z)&j1@`7dMnR8%&Uh?xTB7J!4CB4PyZ`;v;(lY19FWlfuw4xVFJ#;vo?FmqL15`5;t z!?7W1zmYOf(oLt6QI#fEN6o2Q&a|jSrxFeCJ0|P8c=l^dO?(eaWV!r&^?`6g?&gy~ zM89sq(20$QvZ;@(o^N1gUY3xM$j)q{>MKe(KmbyTR0dH2p57Sqh|7nEW zyYU$P_n@^(Jdud~y>ehe`e5$UKqbpmW!}MUArP5U*%GSsrZe^`p3~3hqvV0F@i-#s zhm70D9Z!?G2Ug8Ifpb+6V3|wiEZE#K_Ohqdx+5xIh4nMW|FrmG{kT289Zw(EC=bCj zNSJvVmXc~Gav{T8!nd+xuTbxJJB3p-V3izYE3jO}(ace7>KCh9LnI7pR@ z?#|3DH#hw#+we7%v+7Dj zc8_?rOuF5s?0GL9W$ILY2*VC)eO@nJEaPmjpj{m3lvKc1;c|Xs7?6svBgskNpjsuBOc)k4LV! zLk>!i!%C0w#}jI?zj-tE$HD5wh(}IV5NU(kjKg{cF#}CJbl(XX>(htBVKQb35)0n-RKN^!o);y=YTSGFeN z`qGGJQoxJ4E|r;9Lt#)kQxE1C=cJ*+XryXbUBt{v9wo;3d(<%XCGn*Zv)wUP?xldY zf6rd9Z-DZX3a#KUHF36(NhIkIfai=+L;hJP@c9GshxJh0JHt>cwM58vHc>H)&(9ij zLE7TK`G3NTdau?h9EgS<^(afB{c{;Hku9R6X$+G$z8_(nu^xsA`?G0=g+eY}E{x+}u2nmzGP{x` zQ9I|?nwa<6&2#$@pWDGy&D>SZpAHoDYEF-vhZ_?$J70f}r}J@3=<}UnS4Wo~-+r#A z-Yp@=Wb&10YdXxgNg#h=hacw@rj8hi7d{Z{q1C0GiWz+5qmv)9FC}%0hOv!b4{pPk zH@kIc7j@n%MK64!n;;u@aXz)#PIQ;SHn04>$lf;*>a>R@#WQge5pQ)8aRuxF8YTa0 zG^Ybk@~!aa!tkkF`?b~<7|6o%Kx)DsIIQ07=@Yqw&gCBn%^}d56}bz(rp;8Z%|3R0 z=J5x^721fyEoczYxpwKp&WNojf*+vAxkXs8lt37ZD+@J*lYZ{IQJczpvfX_6tRNM} z>o3^+%-B~@gBnm=xl1eHT5phiB&E={q>90qN-#|qCDyd(pK@Hh*}vu7HE^t& zjl#w(YGaPmUqT{cO8JLht(v_*3`=|9%$|y6&ATl(3eTAyLk5SBW)`|E9@rG3G+b>( zmDhx0YCuz=VfG|aWHyBa4W!y1On0cwJhbXvugIM`9&hOt+EvGGJQQpK&L3`Ivw>np z*y22hhSdzOv!S+WefKf&OAD{!aoxsEfF`@d@zF8u;dk?S1s$QwqLu+gbHx}V+qK?9 z!3tsQBOdcZ39Y>&{(GmEKC}%lgD8 zp9_GHw_V#^Ioi#8!xVdP_&$2uHJQR+$(P@$YKxrnTC=c zA6iJ*BZWdy)xy^1tHqN^>v7-r=VHhW!499}%LCqJt3JvZ*9!R_dAZKNbV|0@#{THF z8(%7q9XtHV>V=dP2J6yM|0iWSEAaEU5!HVQ1tZBtp=Ipj@y7-QJ@QMU%*Bo>-j6cf zH!gKc@mjaK6p!uM{?2Kci%L2Oi>T@v?UT-bI%ugb+~shv%u%u)qrba$q@G5 z{gA?jEfO>Ww_HTCF8Q$3cR9c8r7)Y=D0$<-h#}MXCKAGAJsA!fLM@vZ6WXjN4dME# zB1_OWJuv4t!`-biKMWVZ@&J*ia=MGJJZG*8?VCwR*gr|Jz%uIn$u9%j3vrttIlI3` zoFs>V836L4Lza_hiH7gv)$O?k9)2%5r&P7g5BLlvF~I_uHdi5p0sgrJqpBMGgm=>b zH;E|+{c%uTh2nm{r6JRv_Y@==k@W-NcSXJmmqLXPo672m6FT0N3FM;@66SQaG(u>p ztOTV_(0-B8wdFaD%00gLG39QN`JRe)$eit8_&}H3Zjbo+=@+0l6Hy z4JssnFh(ofXIk;nZ|2+QC)?7_ChadtZL6_q9#Lytqr1Z)P$4SWT~{nb_NMpUrEMDb zj~za}VAlz#_TCf*`_6vGGO@b|O02cXc#mM9nAejNqZP-m1AU64)AP-s+(dB>P)-~S zH6xErwO=^p#y@D^t!qG0K za92B@GL?l?LZo&7t!h4@-(ugIIrT3{Hyh{^*?~v}g}XS=Y5G<^kZF4jpLAMx0W8+B z6O`d2aDU>Arc-mI+7LI#n7EM5Ulr}PZtcGY%|?d%jl#H(3~tZ+L+4#cdt^M^ZMnZx4)uXp>Hr@_*D7sU4uGs?LWzVk(0osb_p%B1U}`$-Kc=kZFj)* ztw+4i&r1`NXP>k;{X86^V&ryF`(OaM)Im@!`NsyYe(lc-CvperA5UhH-cJzj82g;Z z8F1xR+|GtyTIE8tj(m>%x>2Y_ulLTDvc~3fqBkuR z6vTWymY8YaF;?*e+-&UT5<9z}HHOfT{f^dpOR}pt}(|Ym&WBSs_ZFWJ;G$kNe9}Fv4!4S14xWpC^5ko=V_22=p|%l zO^#k7(Mk@KRdnKts#`(2(r9Y!(|dN1yxRA~T`MB8`%eW!117AJTH;Bk{?-oxN#`F5 zZCtpbXx(IK=9iq($U8{N>eLl4fF!FRm-gsenEp}dholX>x+*`Z@BP|$Dy9~SYG%D+ z2@dd5QS7}1)JwPz^r-Qs%+r|MjrSN|crhxzYMmp^$)`}kkQ14uG{|s6J|bWJuhsbNB*#(M(u;GdAo$T;f)Fl_Jx`f z(MRI6kC^w8_4*qs^BV|Y`^<6pLbVs@>uXy}@&|pQseK1Cd>c=j(|_m5jgf25DmI^3 zN%;Na$1h}RHAimcAlA`PKKY@jLEagY*U0+Dr24Nhd$P>rye1rrL=F?*Keg%&3zrk~ zsqys{5?)dpF!kUR8YhyKPX?wi72PA%T#QF$cUBc2aS~GLNauQ1=2nzbNUu8=9GkA_=C61ERq{-A zZ8QLoPW~0RPON*OvjT;rr21G{NHOcpQa(Z*dXH_19h+#PusejR1lk&k_*(qIBRS{d z!pD)CxSlmlg7g<|Kw~JEy{pSL-W+Hv1@loBc+B(+o;XIX59oMh=M8E?#GuoE3O|uY z=EVN`)DnW0C2!PlwU3YU@GX%RhKT~|9{%+N$g;Uxo|7Eo2hx6{#q)!eEVCsSOhJ#j z&8W-wWs3kE#ZgUs!V-|DJz|RG5ogis#bf2%$WR&EZ|?ZL6%}{qPgPCky|iGiNgM0= z23CXv|5F9u2qdvP{o(~lYlP_Wwm_h{IV*a#HpwI%3i~SD!%GYoT>7U?T0{^^d7N6) z%*Q=^P=jS~pKVqWsP_N~AL;8=i5E|4iP{nv9zN1q`^(KvS3(Ia zhieCcE+27L;Ny0QX{~X4pI!Ltz^wVQ5Tuz2%&*|jEEHOQD_KgB4(X&kCG#dai36)s zjb|!Yd#lSj63#ADBfP!yT@qN%-bO(ngI0J8R|j*0coDJG$coM(&bg>Bb2!ono?6G{ zAw?hAs@Pr!)i9X1G_719eGwX!3=sl;FJ*uiw;gGTwVHTPrM(uQci~}Oz)2PzMhNf7 zy_GkU|0qw4ebT$}n!WUa@gA6e|EBt*hRF6tLDR!Jdl=vlFjPY>)LGjs$mWSw_Eem~ ziB9uvu=dkJ)`FTRJCR0#7PihI=IKET+YtLh#8t8D|J`xX|Ned}yo`bfqZez&e*n*e z9q_l$8Vh~sHvuvRgz8@0NCcgBwQ>HRmK#CI78I&oOc!4RgX+!FuiVBp$-=wgYd~9$ z_px<$4u2aeH3pD};jfg^fjsAwI?u#Cd+Njv?&Q-mpYSE%%8I0S1*lNf+M-Gu1a$NRN)YS;x z>g;`$tJVOvjS?h$4R=L*`MS?sBP;LGp7qEW%QaRlzr%i4oA9+@k4LVW5jlHr(B$h* zIQ_(ReY^ZR5qI^d)Ejw6mszG*JAaGi_2eVYku?(HSoKQol5eZHh)X%z9po9OINwNu zH%XO__Ghq^*Kn~gSqw|#EwSbDcVg>!Gc7BatF1b;X?SzvNc{{q+|TM_4k`lF0KFn| zLeD9|kr(p|Y(4fUAf(zOURjq6$IuAxFQGKQs-}S>dP7u4K7uR6Hc7>Ee@oR_?KD<%2mYm}lp5z$gJwU0fC9pGg&uxYLtYT*VYPv{Xi zlKtMWiEzOGa3r1bH?Mv8ICJo7O>lRynlKh?`}tL}*hz%7)F~^Tsdp0%Q5vf3zRR6L zbg=<35)@Fwrp1#$aT`OjFJ6QhFk6rWAQ(_CePNVrSzc4`sKR>h^SO2 zk%vh!A#LcogFMVN$geLQ8#qEMlEBv@#QdIvs5qaxHv={<`7+z&v&MHHKVrCe1ZsvC zT@%CuMF>rf*NG29MN4vSZaKc=#Bv?BQ?98M%)MNY>kM#cMzI z*pC&HUt|J;>EodKWZ1Ov)3X&y%^W6EpClbVu>Q>RXP>gyOMSfk0tS-)>z4WFci^X- zISU7X&)fT@`z2sE7s|#go_>{Y+xPwC%g4%layu@l1Z=x{Ye{|FA%ec$n=7B&)N|A4 z-88%zxZ0Rv@g`FCwk?3w*vg5I7sr@Ns`qX?9mssVjumis#UKwPkB{~K)S8sr>OXs8|D99wSMBR^h)$&qWrE?|2sYXXs{Bb8Ln2tZ(_c|#%1 zhwL;Ne)sKkjCzQLGAfBNr=Al^7UT zsiL#NS@(fij+r7}*Rb!#@hfL-zHM5(b;}r;F`@7)V!5>aJ2}f`8v=I3%6sQ5jFr1= zDf)E3T~4FW`s!KY8&TKYLk6ule%7-l}$qyaN6T0yJxsqC9 zUH`;uaPv+B)P%|p^6xF7I(Kul8}8~?VDIQ_>Y2gvbW2Q=`4AI)*K~2Eq}DFBQ1lDN!4gl{ zH%rEb%M-TkJ4WLUicE5`a1K72%%dnDuaEqB7F~xPe|GD=zr}%Hu2qUPziWnSOdf@C zFdtFmYBukIrwRhKuw&%_eF-&@x+I$Aq3iTr38vv-2xVB&4X0;31?_?ctU@1`&)gF` z*nJ!{T9N;kP_9p~@9W#pKICB&l^u2@el(73?*lgUb<)HAz7vqAQsqXkd`XF}3BMOE zbvJPAJ!b4_DkXm(-oO6KC5WGwJL00-k!khPLg)H#PeRv2UCbrM&a7J!Q}Y8m(0y9l zK0HB3?;EJoM~S`2!sRUsTXi*ENqTD-XoSXaXW|J(^;h#*SBhHZZbgW-eMO=4B$~4W-4vL2P)}qB|0Q%YL71@J5?2ex_fq?)=J(22xlEam&et}p9vlf( z%zg1W%u`_|;6U9$9OGWVH_9a{YihE9sqj%`=6F`u{j$dE8&4y+#>TDZi$|Sa5pJ8I zV{BaXzL3ZVb!S!(>_^4~2?O?{45l)|;BwN$2b#nJEDHw}-FKfoq*lJ|;w8;ghOU8HZs;57ni< z*^^69?qAP2< z-zEA0=a*Z}j%SrRg4q+^>kDwnA9;8n66C#!S$TZehMUX0{9BWYXnP=H zy8^-bxhX2s1iTbne(wcSBJt+O#L60ht;V%p8EFp3!HAMdc?s!qT+!Q=;E*DOtMOkV zfR@uGrcB>en^7#h$3r>hfMX%ZOzW z1#Ru?-LxKuC)rBnL=yYU=4)Ja5fT@Ip+M4@d7{LrHbX1pkLAovO6fr;D>x0>eou~!=+5X|rFVp||AmKTN+1C|L| zZlW9BD0(N_{~b3%-IOaM0xPL^8ncRszU%4aay%q1j`4BauXPmEg6K zJNrm5`j?bktOa#9Kr#(L;%p>lr^m;=V@$Jtc?Myz3X1kZ+#DPa(bqTvhgAK<14MqY`U`E2+;0sXdH6 ze(QGSUH$di`qz{=?(?Z}_3`p4tt+OhPcz zm_y-SJZ_ZL+>#&?xJIGUE&_`;RhkR9_BRWSx%MT9#u}j`v`}cfPt^4&FnVHnwtziM zi(=puVVHEfbTv3#T;2yo4cxTf`?VU2AS{K=;i=)JVitDY6=0%U=x7yx|zvJ!Ivno~pjA_EoKHmJtOJi`+#RGM& zChyZGCyr?=B5jFoy@}J#_)k%~UcW~lFYy#>B|lDFxqk~2dwAy{bM&+E*QbTws$R=% zIcR+4cEqX2cblwa+6rqFT)acoCqG2KYFOjq=N#vH@<~L-aF>&bGE?jf7T;OX+JATE zE4 zS>JqWPU}#ilm$)@w|&n=C(eoDF9bGPE{Dgu$M8^sg>4`I+_}i?sr8>s{ROktHqv{i z9_=t;0d-rEm5C0G7jdEr;Lw%pj4Jam_-5ZlDVV)Ds(!IkI5b8?T385~Jd7Znx%)&v z!Er~s?VuWm+o*KFY(pU6j_-GqnqG5mD4>=Jp2=tVk+0Zb2b#m!kwjXG59oeMfRsc9 zLT&s?&%M|Q1l8~{&gHPxmTfP&7^+fc==N~kYu;wp%l(H%jv~A8C?@@Y4-~WvFs0Yt zyS!i21#v@acZsR)Df}jKnN>mpS(_FPi0tkulE%1SYR3(f?tGgJ$AyLwKA=tn1=*bGXChG&=;FUm3Ce&FF)OZUC}7V}D2EUAXYe&p2Tdv&aN zw^RU)<5;$0a!C@io!28xp>mrauvX(wH|`R`_i^k>#!!#GsYTl`HN460C1RXW{ODOF6U0VG^*utXsaD%+Fz0H7-Uej+ct@kpy5*A4qptmKNmERzdPWr7g zGGvVn;%Z@=><7M1a$@#4cUT!J&0BxE^0CIiMTK)cSGjnbV(E&hj* zo0O~j(@XnGnuBK2-^_%UDz3_w`f@wx=<0i2q^0(2I18A|gd5yjiv z&TRc{Rk(R7nnoz?0)or@pJ?C#gMvn_HJruDS(&T`(VwCywr$jzn@cJ#)<*K?q-$-QMy~CTRam9UJ>O z%9Z5!q)4wARJKTz(a8%lpwbz|MDD7hQl5?=xs+&w3nO$Rch#SmzPoOi7!RdqC-#xj} zq_=;Fsg?8Az`FlDlR+_w4b%gUkN{K_r01rc`x^>)+BDYA+#>>LeBRE&DF}tmL3w`R z;F$IfFUMoUN1V;C&K@P%2O>QnRY}r^oMn79<9a9GEw6(0KvdY+n&;nnYnsq&ND0Gr z6Eci5dW~lTEYURoH*`lH<7sy|#eQ}JXBQG8BOT)zx)-h$2p3q*(eiNY=0rXj%>T`+ zW8d}wJACX!#9A)+`Olq-$%yj$yQav!G}l%C!j8fwWZroT!E59+*ZsVe!;8VjhTT;S zR1mljYX>8*WORmI__Rs2Ev;29RZeiWsXr^$`l0^N!B;9nZP5*{m#4aX z@6}qK3KbV^5yo;(o|;WF6>gWMO|!Dq&VQwJw6o27wIoTyD|zCgkae~in!X+*OoL6Z zw-7y1$2S|Ay2EMJ`-*Q^`LdPoJ9Trf9(_=Jd;5fDK0ZCFCr*xM0D}eEy20FJ6;C#9 zmDUz8CyDU4v?jmU%h%%GZXROt7w&hza#($+C|4CY>*M+AfaC|zku@u}yBYg?gay!f z-c6Ag?&As5A`xfv=zF_qAzKr`iDMOn5w=sb8And~v%m216PtCXU1uuBi>|h^KR%iI zmftt^OMV}DEVzrFcj1x3ZY}-^<%kbG)2?(fg~L}LuCNT%dF+W{G`g5K)vHSq4udWZ z`W$%|oOTc2V61vv+q%*>p%+)Ub?m4g`*2!9R%Kq5;i{g}><~gel{*^H785tRuG9bi z`(R(Gkn)ba`EE}GUTxtdU1~Xa)S~!Dky)j4T4a1<|Dx5s%+aGahXX&RcAs0fChN_! zfu@wN@vOzXc;T?45jyRxZCDpAKH_#hs)g*>rzVRv09)dXnw->d86z+zv`!t|&!ZAP z+)5oZy*y00WfCwQ=}98>Z5J^!k&up{Z+fkHNV~q`4ov;v4fnKG+XlBxD#3YDqm%4+ z-=z)1C#AN~4EOr__>udO`uEbnXj|jC9d!xzq3U2Tm<53!JJx`jEF* zXs9FZVjHcXaOG{eCA8fWo2n+>McX${ELVvLm0~T>!adGdb6@>Hj&*auL@&9!Ar%CI zJ)P^3kTz;CbM3Q9Ecn`G6}N^W-;QxswcG;^0;3-60OzY_1@S)mrbbGF#>{bk4h8vp z?lkSu?{Gh(lbHg#X1cL(`kI^8sf{>lxmxL{@!dCD3PlrbeO75FuIG?PCx&6f7%2V?3S;L} zR4})8$?ezmXp9iI?c_!kN2!bKmuDt5J>yN+42(5wlI_GpXcO&gw(BIf6LB|F=Whz! zbM-8vre_4+mUJ|rHxV`j8jM~SlCE^Qw@kZd8sfbZH|Iw{>T{RGK+QwmOr({{rL@-c zh4jz~^hk8+eB2_$y2 zhx`nZRbn1cyg4A&VM?}d7>Dh%7D^%@6XB6=uWAY^+M?Qo?A~rpb^NO0#WOR+I)sHc z&O@&W$Kc~b=|Q?U*{!+tF{VFsNxXRiLzUw+XQS7<$lh23kMVy}lsIccC2FQ(dUy|y zS)B>96a;}EO?x6V3TY3ehv!ORWN9e&3wsm&WYfse5Qh3yEAUlb{!Ry&xHhX;JaO09 zTiWDW`Ys8?5oZC9;+PO@F2?~ z)2sJ}u(QM(KiO41U$0$+x(ou;J>c!CXfL!a(6Gp$k|Sz_*A#Qd=G>>ni#%!vj0TcW za%=QS2Im@qJF%J#MwA4k@(Qm_x$xa6Vo|}NLTx%OD(~eh3~Q}^V})~QqlYZ$=ycwz zM-~)(#XIj#;5dl20Ff89Mq!>hHJ=&_p+Tdpn)5VXEFvW6n051%95UB_X3MJt`#TUi* zZ>c>FijyA0l%xNSGLt24xlLWX7-0%wu=V~}C!5o`#RXRE!qNVJn4`Gw*TksupI&0{n^)u{(Lc~ly>U9%p2bqDAM`F?zejP`P| z5=MSNKG95=f#+R1s@6wj(s2V5dD!H(jRxVTq$St^`6*4L^MUVI!`1pu+veRIi@+82 zPQL2uj2v49dva=@6S>Kcs5D}ZfBJSlb(^PRJ}K~y#*+>2m-+liv2l&D)aBnf ze*V4F-V5ZS1&@`wyuQfo=?%Mi`&jsLPJDof(c#1kcLU{foy=DIXON0ht{l=$eXu+f z>d1LJ2>&M9Ru4@r=eMBSUv-VOWN6*W9<~s;$8rPw^F(`aS>pzi-X`>wnFfwWW^w%! zwDqD(Xd6;Wv~WPE-yLHGY*gmHNqJ;yZD^FrGw*Cn46L^>ILBM zbHP6%*624doVfm zRU$t8S3-O3&50`-uf0{<4y;(S`NR}jqIN8whrP{u6Hv2kez)Zg@vHlVcOHy?R#{oM zRZnO5Kjkza+b_S3}t;e_Gynlu)q@6u;)I&1la zRR|0~eT%>#-CKD3JfyEAc~{8p4;hcI4$Z1-sh$38@Ze}x5G`E`wfgBEKVg(L){@fn zpQVFs&fHiW19V*DvR9AK+wwG-$D2_Z23Of(E>KiJXK?@g$*?3V3Cyi87^d1&jJe`YXx6CxKai7bi z)XLa`Y9Mu?_o9N-LCne&8%eXbP|G_46!0^3*kwf;8bcl4q;mH z{M3@%GR~@f5XUUa_*VaKh__&b($kHFcljBrILooUhCJKmAR z#}E?X%n|hX)9J{Wl`j&vhO-MonplmG5A9{S_A#X{PO%y7`5g4RJA+F(Jk)Prjva<6 zm&n&gD`~x6o5Ro3dhH9f8DxC3jieQ)z4`Eol#M9Si|dtU3~VLLWJOxHlmbdv8GAlNYgAOFz;L%%b^FUQXpKw7)zS6-ar4lPo%7$k82KUGvHU_MgSywd=^>4`9OE#qT9o0^^>&rNzxn#lUKiDS zeA}(X7GQ<0)E;xt-4xIu`mzl2H$|t(_`m|&f#EZCr#l^FUS(K!SIV!yxv=~rc)}_@ znGUbqOg*m)i9Cu{j1$6s%|fkrTnMC*AxTiz^z~W^q4kHgIJRYU3??P+xrzz2X!W6z+ zubs9zfNy;h4$K*$SC7{|Km3YCCCftzT8Wl+em73ntlS)XZR_#~%Gw`?19#Q>VC*w2 zRDOmfOPnGy$9Bt6Y(bN|TXfra`96(`aP2>A#F$7Vx)?0JR;Q(_-e*;s((7k!X=!Kb zn2=V=Wwo8ru=Sb{r{uenq3CY)%+oE|>vN)X!@^sS$MJVe0cxX0V`hshE0}=vDYC{$ zmi?0UNoe6X^;2j0!{IySW88S&6R+0GiK09hmCj+p(ju*$ zSQ{B^Gg%VjM<(|aMvGD?95xz^)1FujX`yM+hwj@K-jg(&3*UA%jPm!atc_S34>Vy> z@(}^Vaq2dEMt zHH)N2XNxPo`4RMBCRoz_=djLbn7|$R!d$G6mLo-%DyvLl0G6U`b0`gNZ#r`To#L<_ zOm0-o3}mAvs`E?+Ig-7K^czxx+o~#hLS=C<%8qyTo?kI$0{9w{U5&OA(o#JfyLVhp z2xh!NR3Y)MU>cKBa*TtD3y#Dn6?e+O4Rwg;mcauyMkawz@k2%#t3>o?*lUve0)7?K zNdX-LSrIy%2z8Y5(0wQP%MT2HA5Ff>U%20Am;Q3IJwe6e1qk=4^CTrzGNJE*x zzllROzDoudg=r`VARKYM@Q*x8!}#AaWhmg78fX!dOzJC=U&)-ep=Ir&jE>#rC}b_Y)yQm*=6KMHW`>wU0QBx> zE}wX&{-8?I+QSTEPsQ)W{G?i-_<2#Pb2#2CWsL@qt>k&1JW8Q z$Mn^ocC&wV`9JWXz(V{BCjNi=zc|N8nmC;|Ago z+L_A*o-4u<(dLT7M$Z`Zv}rrwfWXqy-?c`qUVkp-foNg<_`A{NM&R3J2#t8!rL4aY zC39h@1|G%{l6I^A1bZ5rmgS;33(cg3btAq25TN&mYUc|6jVZCYNj0U>`rjBElQf2@ z;n;mj>}AElQiW3^K5zvW(`fmp21i6P-rFzdY@WmZ=7Opr6P1cTi{1v(AH^k9e(9PN`;l z^-^E;_*B*4LhgZp#SIMrI8v}yOn!;Ef`tgC7ct(x^H&A%bIs#*@u_I$lNWm zUoq>VCs@r7KJ-k~oCuw%=8@aSd9iC|1_a494PWMbaF%V=m>}1H0u37rN(*g~)*izi z2K09BXHp)vjI`TrOS{lSqmyai@E6*i3>n;eXM~AXbZeaP^gkamB_H%CaZoFtJ$-$# zw=Hk`m9^^;sVpv%P5f`ny?H#8f8RGeV@S!;qDav>++ z{XF-5ozFi_O>-Q__xLWK_5FE&fK#0*`;i|g)QjUsIBSd`kjy=A>a&mq?>;)K{+*B3 z3=HryV8Dr3=AC0|brrZD?+yodC`Smj=k9lK$l*bh1WdillgPlb7l}0&eRa1KT|krq z>EuekddgQ6gBZEu*i(5g7kZ0e+N@nC<{qMz{1j@-u?UTJA_b?ukVn3@en4xC z2MA1OwTov#79adTT(%Q+&zaa`HTqGO?9;njs?*!}_3I@AyN-V^RMRz^fDUMlWTm#0 z`|ivQW%^~7wUL%e@6LT`Fekr1diLJg4>no8N=J1yFXGSq;$?yj;&Gn1N{wNv*El8T zP@VC9laP$roF)oDz-Ilg`EMpU-HA7Kz9jiSY|XskuQU`WZeV^NgKOWh{Hj&%jm_QN zUYqUQ^{_4@QI`U1#;Wxyzui0Z)$Y>j_3DowCyYptcjqD7}ctQs}KF}ji)66Om_ua^7 z0Cf%FKWm zr#3$_zKV~zxjhJ^t<*Q-5&(7NO(ndSk=Ibm1wq@K9GimT`?&%pGsqt{4`XYZX*Exf zOGnjEWxV(l8a+EZU;-_c{5h!KJCSvWy)>b}U~(eo>A?=Vk+QUGg=9cS?>OL1*cH3r zBW_;gMh2Cw3GWqGu^4IY+Pm~Ef;npL*_ zfsm^P-Z2ah5uif`LCy;pvpxzK0W@(@`aYO955}|J$M7Ahr9h);txD!{PW`^KU*P6X@v!Z6U0@SA*SFm_ETYLWF z<3UnM<0AKL&m^S|vDmMp%e!&LbR&h#DH53Vw^eKxH4O)!YF)&5X4n#SMULPloU)JS z0vxFYb8xbkHn@wUbI3Iiv`m$7m_VYnO`T*Jx{kx?%Tp?Z>j*P}>`S}wQT zwZ*W<)U?7hcdm{LS4f<*!*Ak*p5=PA1k&*U+Y`6sxDUDbn#Q`L2E&)PrU%oQ905y5 z#=oHEv%E7u%@sXYH6w0H4Pq%Q5>V$(*>eI6I%7c{H^YNCtW5lu3Abw z{Nahq!_Grt-vD`X-T&_J4`ISUSG-2CzB9N-hFmQzK)_I)u6W(07Bp_prBX~Br?Bb= z(|Px5HZf|htutjer}7f}@}5O6K&p~ZlOP_t=}rm4@VfGq)NyGYHs0cSWl!NPixqR} zY?wu89SLrh=b~YSKBuHEWArE*ZmG$?FifFYl{KEi&7#j9E|R&lVaHotg?XDvF3AniPw7mnNtF zftkb2)}hp~R~r|YqTQ$|mETdf^7-0>dW_$q!Dk!$hDz~K7hGaH|CTL1r{L2jrMJB& zIN#eRwIn;h9B&@b4?|yUoE$+HWh%)@J`@~}zy*x^s*6wX`@cW7B>w}G>k2{Tj$UIP zJT;xW3Un=IX9uGX<3#1MXX$JbB5t!?56NSRx?Df7R&KZ7(z$5VpqO#YfX1UuI*n1e zyo=?!luqq{78sC_NLo4<@t}6aKO1{1>=^WY@JmQOT%mS7);Uu`Y;mM~m=G@orCa9X zeW|?5A!vnU)Cfwhyi1j`yY0^dO)>C`WD3GSKHfrv(YpUJ@n^iHY(KS+Sg&J*RACcD zxnDk6F}w719)Yhr#bL1L(N0_bw)zd* z0qF(|+jOXLTL6Vy5&aKLnbK#L;F8|;v#SHylX^aUehW#x#QxI3+ZQ@cqiUZVHz;A8 znjfKrj5yggh!P<9H&F;I4B_P992J|q3M8*`EBJN=lR>^rKC@Tv_<1`cxr`@2etFg7 z8Y9$xCfo_BHVI||p|?sUr9Tk}sJ%8%0Z{3Y8z!1bam^&-82r73Ax&}*6&=?D7L++nSDR~UFAO4%mjM9dX1z}W>>xJh3X+@9F z?C&5+KU*ItR)QVOyE5&#$P%h^QHn5#5_HE=JWBvJnHkE#ybzgG3$)GdB>fa_q}W&g zh+ICSK>xdZu>aiI6O%MNi7&(NVNH5PDzzI9p%KC6H|Go@G!P~R5B~DRG&1ZiN1+uJ zMx2qPdhVkE+{}L4ner!QIzM@1EoZ!kPIVxFO}VdlzKR?jwp_wAG!k%?O$nx={n=ln zzkEY1wG;MRjGS_=@`Opm!d5=9F$tCA@-CY?7{XlP`vx@&h4yY0tz=r+ota7wKcs9Dfb!+K|lfj~XxIaENhoR79Cl=3t{^2B+X5XV} zI#pldGKlV5*vi&cs-M+;Q)d58yKSNRT3~nU>D_^c5a1wbpq{M^x?~AF%rLvrC_z)@ zVF$^=>V?Y^2bT#{On>39*3@G`j72;D#&m6#w=_r1DM~N}84R(h1WgW3&?AU93P0Fc z)WGLxe?|+-Va)ZGKE+mnp%zxRAnmufT|DbEyzi(*ULJ^lU(9dj)ugdiQ~kug&Dmi86^0MV@So1XS5>wd43a>t~G)t_vV|6+=~<^zuVq{iqXKt}VkoMBl{B3e|vZp?R9Af@tB%cx{zynR2 z`Mxq}td0Co17}TeethEw<56TI8lLChQaivIT+gPDP6&2wdH_o9b^pW#Yj3Nr(zJWu z+h)zDh=OG%4U1W{lFs#slMl+pgtNS-NY$`rT%}jDr{3EDE@2NxOPvTiG5WZ4F>Ra7WYE95&7P^9W*YcD~ z)O0xVV|vaYayR78J)o%jXBhSWa9VA@%Z_u_ay{jz)^diNGOGS2UWN}2W*BPbv?Di(5o+v)%Or8?20hLYJrmmPv3~&7B}~yT z<0Siz7!AKRSInx`Q7FukYqh6~DE2#zj zUxM~L=dSs5vZoam^{U-n$6+7Uip^6AtdR<}ucZQNP2MUlk9^-&&`#kN+6JnKG`>`M z3ghq+K3U~qY(Ae)YJX=M5zK6e%3#?Bvbc&F#2LL5NV_H8@{4?T6>X-xOe?!Q1tx9kKg@rIEkj` zpW7WPzviH~;`vXj_&Li3k7gOvzGk&P@O2Lz+y%SIbbxEm8dVdl|GArdZ6uK8*m}x5 z14-iXzf!rS3s*z8&%R{x{YawRm`~&OC@4Dst;6QwHs!@?I8<|vKKWUWmMv?pd4|O& z@!s#Eewwolp}2bHmrPw0qd1^NQtcKG($nuNXs*2z3f<&$xoH0O$|2)Tg&ya2y0{%qsF8KIkNRC%^!{BGo}Uf|w;kUku?EeCn5tmg6e|aMC4M5Oec00_oPXo&^RCPBe}0qHr~u zF7IE#@%l>0O{?}qgFer7V;z}DoKU}Z_O0+MueZsPj5O6oq&R1b;&Um>>cu+4`gtHM zxWJOA5^N`d!?9W^2pceh=NK(l?k`w;R|JeqtFE4);(zV{qy#~)`c#c_Fl*1FLOY}1 z48GhL6u7TJJfg>x71a8<%#;K^cUW67fBoeo2X@1)cC4K&1{7x>nr^Ze0@mfjf zhnQpzo2glZT2%K;qOX#6BF*QHx1wNs6ga&}eivAV$n~4gmkxVmTeGc4AdE;yc5be> z7?}40@?{4`g!^5g+G)kyy)WivnNo#&aVr;Tx@lCYS?X+7T?=X@VF#KH zc#E)+So4L6=ORS}C!!w}AV>kV$W#In+th;Ht|BlICP%c|ed3Scj{U6-aV-{1Y53_J z`7pES+#wV^OxCE6*iO;q5;!=U4iAUS7eK|0+XJH@x*!~ll>J+bPe0_JLjAw5MZx~@SLLPqCVLBBqOfcWqqvyE3*mMmS`z{ zr&?P5`9mVLIMYSb5oZG}c#-M^I$;A+FxYzxdVvFeq1xdD-FxZoX~iYs87JyoKlo^S zf*B<#PYpl#Q={{2DI9LR=%=hbjovoZtTxgarVxM7fhDLq0!GA#Ay^p-n>n&;LCt4~ zvjym{uvG*crMT&;E6sOnYWQ$DW$gG>@elPMRtvi(0X*zbT00xH=H?>3x;0*xKV>zt zIX(Cs$mORA7hU$4AGY){g*T)pbuv70exZ@jjggaw2~3Y0@ckcrGf`$OVb#B+)h_Z; zwZ?k!qc_*?ob%7MI*Xhk<3Gmk4b!^s2=gU_lp!=C_SeVz(?)~T{cTJ3ioXA&@fG$A z7ffaGq~glCOKv`9u0KAW6u9b4$I^SZbS|wn8Y}ncxqAFY6)9t}d%pR~WL3{i741)A z>zwu|r_?Sx(Dpe5ce`cpxrBWhDH}gnC?+1j7$<3JIUYV73~Z(#Bp-%|-FYiFDfNQW z(g(6&Jb~Xzyf~pg}<+NBMN(bn7MDV zBij%z5G7RyjSAUN%PemiZ+R=_0?E_|TROzzks?UOIzB#Clls17 zo2G!t3qcrd4g*^R-Km7Zs*w&pcOi95-`$oGm`rDO2!8YH7js600b8iKk5pbT!5!2X zXPTFVU$h3gGP%a|Hkn_@H?(L0(e3$aW5K1P_lwJ8FxIb^-$7i>JWf!%s=tO6jd-m| z2-h8Yk@Ud2$9_xSj;kwyvZKhrvwHbSLUEVvWcgz{-`vsDwd7Q@K!(5B>+Z{^ z-hPb#vF7fr>}%RzU!=}i=|yc^KIdg}U1(zY;qRxmtj5?b2`l;WwznKwFjccGD&NY! zC_<9wL{}To@=SF~a((k}@n#c)q3Fo6a$7}S)8#KDqhpkxmQ=m_l!vE2_0}egDNxR) zPt5j`WV!)zjf^t?_bFh^+zLDyJ)Y~O^ zrI)Bwh6x1xv+sJRe%mrUPf#`FR1i_9(WFTS$-n#7V|(^tAiB{h3lPUKigb$AoD%TT z!BEhA@LD+F+gmf|tG0t2KrSFR>$MHkwz`iALpIy)0xH!=O&gZd*q7Jl%2z3ShL}wI z@m5rfW5MwDvl<=F>2`~ya~Rv{+2_VoZ1*nIB&B!%usPRib>VFP(PL7dvc=uwYI&;; z5S;mvdzk)fc0B!>XPJICQ03K9LG|nl4-V{H?ysM{X!}(ot8+W{DZ_UF|I5$?F&3zhwNfQao-;^IsE*gJ|xZYO@1sz-f*2z46gqJ2M^q#7X zXy78ZH6AVdEP*}rm-dmlt2=CqLQ+I?zjHfr>DO<3G&cM22^iR{fE@Gzo)1UnS&^S@ zH<|KiL*8fsq5fUomy>^8Ef%S!z=!I~4hP}v-Qc)b^JMW0xP+T9j6b=iCsYlJ$uFr-I6*)HDr*ltA7u~BSd^nZUNEkG24jv)99Q?jpMGH zI)Kk;#4B6)P}}``Co2h$H$&~%H}dnfFh1!#hx_;g`0<_1H%5Ao z?8%{VHu!n}2lq>>7%bKc2nz~ji~y<$t)+T?>+ZRq@0|e`i<`>T*O!OMZ!Tvgl_@ulSkO&QGq)Nu!KP@U$;$M*eRmJLGA}Wh zc5_Y(?~6^X3R<*Q=U5=U-d{sPAH0aV8i@y~yvRMpl^H9I8p?^GI4@e7%eULSUep_4 zngqp0NPmrOj(tycJWi7GM<5v9I+oRV7vJ?ZQ8+2@_my~gT_1^QoK@|Y!%tpt+n+7+$qd_5 zis@U?cBVv=aMYPO$8D z2;X@Bp3s;23;|!+dqOE2BN1SXHL}#xJRDYjbVo)vRINoJ11ql;E9rWt8}%okArvsH zv8g0{jr~irI0ODIlgKlYj1JXTVEGZwvR}W)apr7%wiSK-T3|Qz7(Q3U z;}B7=i$CZ`&RS!?zDM{~@Yx-xkacPvT~w$C(^3jwz;cAGXQ3!~js_3iBJ^#_=g*Cr zL~+UxP)#TK$To)wc1YMHzmQ%<)tyAr0PiF{)eu3vOpZx^)mWZq%*s4y5or=}5}_c3 z9BPqj#R*f%Bu0f8Z>W?pb=lf2ZeTCi?r4Y?TDgr45TF7SZp?iS<^m9zAP2#zDjnQ@ z$y~xX{{}B|5WlR#6ko>|T0YQ2XfXY3u4*Gxe^tTT=~PcBFdZkfr#X|wbtj-=?I8e; z3SMnedm(&XN?yHPJENe+by2L2S&0DNb4+Y6t7Y_zS{y5hT$+jA z^9bXv#9@LvSk*t@uV4zp!yq#eU?PoBcFxMz(YQSAbL|Qc-#gCb&il;~H4}Vvjv&DL z%zF_>=kwe{mc={fdOHeGQJjd4^eHm3KC6@$6G#nQ#}`QT+4B- zPeE(2pcq22r#)(g`X6C0A2RJT4X(5?M(_-J4v%FHcvVwGZw85GJ_3GQ&a5<`j3FQH z$p$E-JSO8X#`c@^R=PKSj2RqRwp?+f}ZpdJG9;q2Xr_+w;*5#;#m?a7$r$MyoH0oinRMn8U0%m zVt&f2%-To}I6Acgv&{&hFyF%rG~?9hcS3>U-V$bqn~7R1m?=gRn@?fW$1<@{=GxDq zNj9P?mRp3bRX`N-lEqNXQl+?>ZxE?HtZW2XzW(OYP+>$56du#YhIY;BXsRTP_N>)Pqm zF^VYf>#_5<1)Q^p8B)wqDbdpxHy5*5!y)Jyor(MF>7 z7V|D9gH1q!>e+za**@)Xd?2iE(LonsL<1%?t9L$*ruS}6JO7aM>VpQ;X3nyyj?smJ z53BHv*^TMY?_)Mtx zObIgU{s*Rv`Z0T0Xsgh+Tdu|x<8aDQFwnNPAoH%lyQJzI(=xe(+@NoMLidZ1i73Fs zxppbAe;1?0@JRk}CAiw`1*fPiV2xiG2!Qh+f+=+sDi!#yiyWr#gg*2ppWsi;x2E;& zZWbD!*m8@gz97lGtuS!nwy=Zcq}!M~LgnUg**be~$YUBXy%Rl5p-?(Bu$ zl^u1O1wZX|e-wj#e*M?bPyf)SB^~zoY`@9m4M)EnFHzlN&nIUcAxV^xShsV3Iw_^R zbiQuJ){M1Y;&DG^2W&k_K}2-V{sE43PqBr0qT&hg04I{OKAeZAQ1{V`SdWv`yE{Zb>(%OJI79#8eV zI6%!a`GR9KF2Ga9ltav3Or4e?d%VkT^t8G~9TZks&~gQ!ZQ_cQ^0-1XFElxb=S0sX zOFUk`p_4Bi#Kq^?b?k0RXB6do^f#&+(tt2SdEe%toIvJ{k_t+0gO!n*!|3}h&Zh6uSDoTLE`Fkd5PSqD4+cO$8BW&$;<^^ie1SN9HppLD_@G zc)a&h@jf=MfaPFTdGWQRDLa}q@?MRRahmLH6y)%9${!qPm0()M(gW=mxxap0FOvb~ z7{6uA))6Y$>JJ}-rX4H?2Zn$3BiGhOU(@nCQ@cw%QUeFy&^@LGSAIg6^-jIgxcB~u4^{5;yP9a zG>}<~&E-CtuazOnWpm9EM;UQzO?0v??=z>qEB3v-n|<5!mT$nZ@bn!CzDgUrnoaAJ z0`@ni+_@zlSTDIH7_dhR5is;a=xVWM7v2ySa@8NrH0PKW2QvN}?|1C~2WFi3A)nRf z>i|HoO@5k=;4Ek##}7&hPZNX^teuELZOWc59-8nr@6)!wv4>?_h9Sv=^lT9x-)d z1)%(plqai)D`W>_bAGqX7|`9V)yXc*KhE5Y)S5t@Gvrx zgPvby`xl)>!KcB;$-kywQg$DK`wXdsDAD}@;B@d8?SJ5(x z5bGyJT>#P8!7uUnxzH(1kdl2s36wJS`Xf?{h=8%ENVjNAXy*sC_r#VeJ@a3R89GA5 z#(g(1ZnOA8X~#Kp&40;D-;m>u!c4%-a`g7-#zNLjnY;qBZVzVsB%ngs(54B|HZ@@<8bLGA2=Z8KBuxah-CN2M!p62>OU}t^LztPD`%s#P?)x|c;oa7 ziiy@lECPu4qUK=ilI}2LJm8q&cP=hLE4$o25dxdj`EfLVyQv@22l`|C z!Pj1yPx)SQJqEu<@X+0och<(* zYL>YWzu-NU--1FAbL*xJ-{2|MDh%4#(Xv%3#Sh)ND=s)<26vbo3VZUIkP`R!OgwGp zr^SS$m5qw?ua|};E`E!nteCxA`G{@Sq7#W$+6t-Mwoa`LKRyMFd~`TjZP32)k!;lx zkK2h>bJP=59aazuE#d`Fh-Y)664MMuDA{HipSVjoa^^=B!K4OlQJ;h-1(pWnu#E-k_ z4qt`jjSBf_HN<2y1rBZ#IzE+S_3oq|{9R`Pp5lxop;hhuci*+k& zKD2n-Fdl>-HRvDFTaIqpPECJJzq*Y!Ue%75hU-+ z?BWj7x4Qy{hrTysBo(U}A`u?N5}q1Hz1v6{*R`f*T&Pf9icXC+fj#NGVSlMvn-Fi` z)=+OkEududFgoa97UbD%_H*M^cJx6~6JN&~2B4p32^Ve=V?2(@+|(zY(i7%>k|b)8 zqQ9xNvWL*HHm3i9)y8zhE^IuP(dVSDsAf-rRFJ;3E5=*+f$tcZ_gdu)XJnsspAJ9; zB{sE4$mdO5CS(*@%Hk@6Z0rtp5ZDwEk240a8;i51E^%@ru1)jbiY=b19(|nnhBYw< zbTiDD)S-17I|QBJwWzB~th5=lAfyW9Sp2U(HeQK7ilxx3z%hSkG-WIT!q1gRthvFv*3P|FS$3&&RO2qkIC>2<19X30N5`Aqs_6% zOIflLPjhuyR4q&CvgJ2!k1om38R)hm6`RbD8xWlNf~Y9rnSOc>bI2T~ zWk&AGI*IUGUsk~_($67~w!0FK)$pCpCn-Ga;XzJ?8tZ#uCSylTKqaA&#;m26WY`@Q zo~YUP#el|Pq2$=RRV0lJP*?Jf;_>*m)WDyUzj<`OQ6O=J~dOY)@5~F`J&F8Da zG6bNVviL94NWJNd3U=w?)9_0)4XrHg(U-U&+N2+R{=5Zty{Y6+^Z8G4Io+nFcp*tf ztwF?S`sXp)*x585n9Nd`^L)7T+oTWE5qRyHt7b`N2x2f+);TBGt*s?mCF~yku(`wp znBs-Fdh%X(941sA^8&jhVHdPT#ZyaVd(yq)`cGPS8Zz5{o2#TLVh{=u+)X>Vtw4u2 zTqPQcWk)DBY5>1_-PBWQ_}VF~J@ODy?&GD(UpUb{Jtht*f(X1fQjV$Os3n6BJN=57 zG|60f4E(UhQFOHiFz1MdCi>}r_BAd;?fOh(I;{De|HAM8zRk?@!l?--c4hxeFPUdX zNIUe((kt^_%60b9z2|S(%*R>ZoWtHfWcPA8j&kV!Fm83#hAXqzKH0ETGTmC!B$0C$ zctK{jU|Zy>h~At*{1+vvU~bISUsiihf5%&(8JTm|9RV`p1dt`X;E-}FdZ0G z`IRqTjeM3q{oqtvrTMV) z7;G1{h8R}yxrWx`R(p}t#M3MmgU;kui(QVmv~_at1b@R8ROqbyBU% zywYaZV;XKu-lLT&n9nS}JK~q{ebyP3a%nYJGHLh7)4*@Ct6zEU?ImKX3wD|e>-hVd zP@HaWMYn+<6W1ISKvxG(cl4EN#hEWK;B}3ro3OKSlP)Eme4)0( zu6B^;=kIZlaEa<$YXjduwJh}uweg5GDLy+Zb@hfy$2wrmNJ+MK)eXq9ZRoGBRJ^h@ zNshU|TI>6~{jcYho>CcBYL_VgLaW@>=ex{z%ZOKN$-*l>_oaVfpLgWR&Ovsu&^Zh~gQ_<;RPM@?Is! zxMW(=>b*t&-NTOOfVU|={CGx`NFBkJUJL^>3fW9q+Etr z@?3KnyeKkaI=~nm@fU}t7>b&|K@EI~sE_mC#GCy#=ry*qx`c5{EhIad&jrYF3$>jv z)r-U!S0*UglFyy66E-mijJ}e#c;?s_m&PodiYJ*liC&f7=o;$E!)!+f(bX_-C5&Ou zBNeej_V({hFI2r>`i<~g^{ztKs<*kCz+QPb;JP;agA`{YOamyNXTori4&=_8|k zzW3f0;*|_Y2e!=l3Fev!9pw>5bHdtVlEVShMbn4!DFpzB4x_&hgl_%wi%G)ty1%J= zCbtgH>!VD(0rjmw>iDtP<6o~DefBH5E(s0K5sp&3EIYy`Vp0#Qx+Cn*_z^I-q}EMQ zU#%_I*!D=+0SBO`OyLA5=&Nx&f`9dz}|g&ngsf-1X0k zO-g~V^%l}Gcjip|Z<|qr)dlU2RCCF(X|81;q<>T*jgu`^SL^@xPv68s(T)N+@gFA7 zq?9(QB^;x6*^iVj`cF2*f8$)nNjP_zJ25a=!9%car?+0-#I-GrIKcq6^6!lr2D^LB zx|;t}3-~`B3HA9OWVfknCU48%D#$G#hNCuP;>lxZGe-{cc_52MM*iK?hmrR*$JJvb znKoY2=8T4O;H%6+`oDkcVJ>59wo5i@OS0c9kXou6W^BfQcPNBKJ2VBW+NYJ0dJCm( zTCUHCuauwUjfFNLtxF4)c&-m9LEd^&>sJ{?b8;)zDlTP56bnh|M#@8dlPz4bh2$}}lW(dkA(6mK+5+Z{Ju{lAlfjaO0ex;T*p<6{a zhk!NQyY~2xRFP%}k#0Td6fq&N*o%T~{q%&BU=1Z>S{fI&`n3}3H*55Jp%!d7vnr`a zCg%Px7U2Tb0Vrh7B)*te()clMI|CZU@@k&A21$;Ms5;MaUpm|ZCTDMz^tPld=^Zd z<|rS7)s(J-ly)H9d6W3Y>$;;^ryvr&HvHpr2Y+~Z(bA~bI7tSE6rSbsK=>hb7v8Do zDRU(06NEEkG|;SS6)KHsK8y6+>h7BfYFB@ofxg&t?!x1Ixf&z}>lymT{yp@a+OC$I zv9^3x6ZkV3uAwrI0W>QmR`*Qg{zyrBh9+$lwHhPAUJ;L!9mISf%GqBVDt>Z13%dog8_VLV#9PiapKWexj*k&5dMkRe<6_ZW9oJ9W z`vBlb1m7>slZe5KY}N+Y)o(GG!C%avo{=isNcNnN{chZ&BI?@B`dZM@%CC2I?Z`+^ z!vrVvjP+e|%M;`qyA=%BNJ9VEY_Fb#}BN<;I&m@2=W+&>WtWkHz?u zZ2BEk#Sm(Y?mkf^K~ytuN>}5xl@a;S(X{t)+4a92zK^2En@eHF!3XMRn)@~_h)QDI zacYJr{ENy8mkd5owSaR!OEMdK*g)3Un~F=SE+|mzG0!_?KFdfB0u2xcG0ad1oK%-5 zlF!WCW%?NkBFFQ(0;$Sf6i9W(jjBDIP?1zAqzq#CGx1q@*D+} z%;Gn?sLIP(OiH<^^{oTfG`AcZBnoa|mz^{GMLKD^9{B=%0)L$DlNb<7tVBHq#h!yz z$3ai_Hckd!qfsGrj|)w~rHjY$Ee2+!@^x!Pe4QGk{xQ=*BDe?OP^Rj| ztE5G!4tK6{$e*G~?Ip|sgciu=If_4m7#!YVYq}l)PT$XT=Ehb9-Qo8$KN!3oVI%}W zGzJYv@7Mq3X2S^ngk=5=AK1BLklljBpSjGmi>ocR`5&11k;bxA`y7}F0*kFV^SuaM zq%EfTON4eid<*0MSMYvQ92ty9vpfBj5&!HC2-`q>JMkF4_q4!Dk7Ze*)2o87Ir7&P zFfnfv@j~SKVmW+i5{3O4vqJP=V#=L8c^Fr^7kiT=`LSO>VUq6(m=b^~*^=qe_#xJm zIMDKa+DL=_!M3_<$zE2gmELYjE#P&>?j@~Ltb#q^YIg7(z4CE3)d~Ma4+!yLwXsWe zd-1wZ>^S9!uRqqqtJk&fp56{xYS)#}EpkpiV$1ZZ1biZya8Q7*`Q-5rj4peLohT`& z)etj@`61~(77nv7^x?@6kSe(`d@tE_pq)3dB7pyFBjbT7HD@xyQE&PTC=rE3`cy&N zE)JSD&nUQ>*PVo~ergKEfO)akIkga)0~xS$7t@dEgHQeBsi-CJ!HUdIO=`~cv7KGh zpFZmhi`GNu*UOF%i|MW160|_x)=xj6dUDz6WiGWYQqIK9^m9IFYOdTd7H2`hiB?Y$JS&u{9lF^{AlO}V(d zaL`6GXk5PpyIyi@qA3LWU$lBf=#}=XSO@L=9$sKxkxGdm<09CATNbX$E0~n=FG;&| zdO8k%hfWL(ypdUsQrBm!qZOZBE!r)zplBRM0eJg1|%%WovBcnYH&#@ex^$z8XisQA_#Zf_#= zHz|dlrCF7?0)^^s{784M0Pfq>*uXkGJLloIYUIcf-&3r`=^+*CJiM$8wq{$Ly0UA& z_xS~OUE6mKU(!r2Z@K{P?Elh z%M6BpS|$9~o{s%|CdXk5|I{_L$`>zV`!*PH^^EvKYgTp}|56Ex$2INGcfh2q&%)<*E@9Yto(Lre$*|ANnIyQ-=!oV zLlRn(f^6&8rVc7Qnr@cD1(tPL-J?G$s+w}#QsNOAI+Da@*#Yfh!Q@=qgIQadBb0{7 zQq@^LiiyqRqeV@>3g7xG-KZOBo7!6_^(Z^7b20XmjrgHk5`nMSpS|5FZo%TV@MQj91!@o`YSQxYUFQ14$B#ocnKsHn)@QZZ~q zv)m9LHo2XVjKDNFRI+Tt&Ly^i~-iDozxopwu;N) zPkB>SNce1H3CNq=>r5xgc7ql6p4_hEDM@%RhegLEF_;ahpTbCCXjx{bcYzk;CBI(O zJ8Jsg*l>L6z^cItL|0>OG?S6TWO4aU1tcpIS>mxua_PV+5}Re)CmkZzC}Ogk7VZYJ zIg)||elU|`#*r-OwApCwVaY7vmV!l!%;(j=CHV)kG6rXUEd{z6;148iY?U-+D{KVX zPrF@7xP)Vnku4~h{7R-W4z-2M#D2t**mP=hAD;PrVn69hVR? z95gaSSFK>z%2(Z*fs^4PhZ2z+_?mIEdr=~y4f&Zshh%;*g)KDWL5Oecn>o@x)lg4{{JENB!X%Be+j=d(9S>Zh6{Ye z7N%Dqwd1OAN`Z)LdcLJFmt(_w7)f>!at9;08Gye0{kO3Nh6Lm$a>XrMe634d1E}>cFiB2GO4Ln z1JZ>qIpjE|KHB+NY1NM8LR9&3$3*Shar|p@h34&nWmQwhD0P2X$bTKUKj-eh{vo%r zDerx8$s?^As*g>8*SQs9+Mdp1rxrOcT5z)lUR-TdDG*S6Ui{NAP=+MY7SpDy~Qji3MvepLT55|3ocj5X>zmNMh>-D(A1!C zApIYh)SuSoUypCM5?zTk56qpOTp1V@z|?s?V_7)>C_TN1&l@P0QL!>QW`_3gy6;{u z`tcoVFikrMjrPPI?rVMn-H${6^tfaD7Woqz(`&nwa!?4|0YeV;`oBn z$liwfTO;O@2sOUk5$n@MCA*751%z8@(LCsu{3B`(upKLzv-ql8p};A@5%WmN_`Y}1 z@}leR>0)nR@a|ucb5RJM(U~WZs%}qH1QQZ7lYr#CBI*CN=hTe zw$o9Pw%azC6hQ_K{k+I zX5jKv9Hk+F3I`AS>E-n9K(##Uo@wMkZ}!KuS*6e zLG{)?g_AUujdo$>^gzAYGS=%n;H&=1J!L0HTXSdL!`oQXh>&_ z5Y|`gOHgZkJCVq&fXY;v^xL6JDNYG&8q4_z|7=vn+2U4bW}jh@sOIqa!P|m!9f_6q z!{%9s9EtGx{Up2TXyW2;&%!(3C0DN;?I>TMeN0_!ecsEHr$UE>WKVxC)T3q#)bcFz zCnI)Mx)nxjbhAngK7UvyTDSE(13bgf548>e81Qe6+Tpiy{> zYFTT&MS7z~U};b%BJKtUP}jI;=l_WAji%guc_ZJNNXN@>dN83S)oXu2j(S@tS2hH+0v? z#6Wm{&SMY1;P7YqPxn7Cx$Rtb>~id^CFkxR7yL}V_HkJKin)G63He9#YKfufD1l+8 z+&gY&YgPxp#fO*+zW(TYRhNb;8-=k4G_O9s>5$E%Gc*UVDJoXY6^H_AKj>ix_97^r5Ju{dH}f9QQ#nV{9>c zKJr*A4~hE+#y!aupC_eyX?cQX6s~YEOahnC%SKJ&H_w0R|G;AL@|R@3I8)_psj^630&_aUYg)qT@&rEft|14bMUfM8IY}17BpStEUm8f= z8m3@ES~XI_sr^MQV9J<8buiTWiH%P3K5%+d4!uVA3n(I5J!X`O{dR8EHsNqLrvTGlr&%PVX^0 zAP)3b1SbOuZd>!f7GYFE@Q2&Wfm&=G$v@Vo6R>)X8&=y#7Zg~~&i>}GtlL)noRn3i z^mE?hxWGvPPnS^Z?@-Cb4jQGmTibuD{>iGYuh-}Snh%i?h>ILHO$xL~K_fzjthpH* z9QFQyc(TAk;0g=P7v!o?&5R=EqYhu&ae zBZ=wn#;m*G9bjJnuq&I?i$A94BdJ~Kl7-s|FS{; zJLS&5S`kXsQlv>x*)f>yXTVNEP5Jd={}*#_9uMXF|BH_$q@qPx!sM-@ghaBBr9!H) zlw_N-6e+S~8I79?C0Ua;hAcy}RCZ~Ugj6Hjlx>7;W1kt!n7KRGsNV0-`JT`DJ|5@s zJKyvD{Uy`5uj{_<>waCY=WBUBS6&9NTKq@VddBJ0x*^#ie0}9VH8?h@D`HA#nLF7}X>3 zA6Fk)Hq2mEpS+~OXv&I1|QYjzpQ95mIS-j)fT zK-BuWN{77Ma-Y+#?lyF{e!_%t{HUQ+$%JNdxa$Ln4fwlJjoyLD@k?7!I*9V3!VfPh zTCam9mX1Gj`m;j+G3fHY0p}rvo3{JOxxze2780XX(1PXtjN9oqcFzn+_I;k@6{YbB z4Tpi&G47hA4{UfGX9|($^ni4*@_x|m9Yk&$@=qp7gFOT4wnM_B?sMZ^G9JA95G1{T z(J{4|M&{7YDAC-To&FdU|!s6>~9V4Cl_kX+Ojw^Wcq&p?W?)1lIY4xTg z^{FHeSHp%aTD^a1w)(x}P1bg;Ol}nkJ#)tOt0kWzkIrbhVmT$)(H?P*a@4h=N|p!| zoga!@Ov^meC_<@{fgqPrS2)p#z~*=?zc$=~5L@*&!old3XmN$T&c&@ex>-;HAG_MB zJRUcVI_YC@%{Lu|1cgqk`vI4_~vI&vG^#JZkpLGpFKq~Qj15cI#uLOUewVjkvqN3 zQOVoV<(%gMwE;ziUa&EW=f&yqA+w`*G|(H~7x;vn2d8_>$apTR+oAIQ(@o0>&AK~B z6kkYecFb35;M1A-|AR?fv19+yPX1>fY9S>(cYM2&N9?ly`e{`ipYGI`cP&kmk8=GJ zf~D8Gg^TV_*qtK3b;rRJp|O*Vg3Q)h^O{cJn9T~buNM~d(Pf1h4<<|viwUNc3A=z4 zP@bjC{+hY^PCR8rH2YT-ecEJ3F?c8O7i=nEj(n; zvDF$b)F^kJidAP`c-FTsSn^GsUh*g9MF0&88&^0L9tsOCt!bwkuMY&`^s@2uBComZ zT7nUuQR%o)V1xd;Uj`1LcM#!>dV_*b$Ek7fww&79!w>5#+Go%#T39Cew}b@{Vz-4? z6`utf=)bIaM%Y!~qejyqD9pUa%jwh+*=uu;7c_IDxFC|n!)AwK0=*YEfn_qtkFz}a5}6o5neDdYiFOg(** zOa!SU16A<6&Mg#=Io=1}ysp7JCV}Es^Gx^a$JNKuc-Vi zT)DuQN}h>QD1kZEq9pdh$i04I2BzX{$FHcBFv9BSYN5sVx&hR7HcHt3O2>Yj#COBO zVJ`70*SF$B5hNKy?I18V)iivDE}KS_29cFJ$h^PVa0K(XQ`f_a4*OHnb)WD1MYaP% z1JYnGfR^WYd`fu2+R!g7)H{1Fn|@b)9(UonE-&g1LXo;8`xC+O1_)FKaUbv~k-pCu zR!^=B&jXR#!OA8ACRC0uSoCqShT|!2dGyfOuSchU7~(*L3O!b0dj?Pd`R!=ZT5(u9 zi$)$3CE6nr5V|hESb=yxpc*HPWZ@+edK6?4!+}@KjqLGtxFN~o@dW?z=J7`G{S{Y@ z)$xadReN+El?n3gg}?p1-&^Lt@5eg57xC|4&`_x!q5c3FAk{Pdr0g={5FT^Q+w(Lb@tF zsxcW&Q+l;!+RtUaN1L)*ZLdLwDnAF?_QR>p?@`lDP4c|&7nKvBJ226(S3qlsCg$*A zu%kxy4`6b)2p%dlMP`nxf0h27R53 zn#qf%p=&e5Qq1&4B~XVYZI-0=MEebywEg<0;^wbDKA2WeNfD?mc^iS2UJzTS z*_;m+!;;S~Av>;=Pww|6+?=8o7#zVROYyU{wU7}kw(9S{luP88a_e&CKtZsrlshy7 zGU~gZMag>oM1<0j-w!3!e_HuW@da<&pC zulY4Iz6;ZOs{O;~#o9InYR^x_Nwk+FyIK(Q8w8KTn?85elTikm=UgO)FMZZoI~*Fi z3>walDP0ArwM{|LtYAqabF@N_LHaS?pCr-miNJw3b+jv<+Nu-lXRIbDDC6M}VF{|E z`cXMfsSH1##iHufBdEoACR@?h_8S&DdI}UsVG`QGRDu~pVDCg|$|W+HM5CE0`jZdK zD5`JY9U78M1x2dSG=lrQ%sZMJ%$;FWLecWo8^3?S?}m$%Y7f%fMn^cSqzj%oyL9M`8I;U0)Y3Z;kgE-kZ*zG6PndbdUrinIc`3~ z*m9M*Q|DKKZN3pp!UZ0$SV=uK%m>> z^?Zn)!8b$o_#7n%Lcg&6^rQt}Y2x4=xGYXJyqUB8u$^r1__QHhsyw-__B8rqYAy}X@fI9EaV|$?_!L^#b8&8a zqjafbLA~9yA25?!UGDx>WjPwJx=7;gW0f~Sy?RXOHMau&bl{rT z-$z?GG;Yy$ONrB>r~zgM4@!@=I9;2m$|da1W&r&Y+oP@ah~g_jm)zGlI(6Eo?Bcc(FAr*RwJ$rQUKp@!*!V!CF6~(G*X_$+`d?5X=%v|B^m-z`fXMI((ZQ?`~(i`1W`|J4)WP~ z^wCRl8PP_Mq$%JS-xR?*IdA#|oRS|&51kgqqBu{WndBwW*{4685~i1LdMoI=p^`xT z7kYPpKfbHJX8Ij%1U#rzwj#KnE#j%ZdQ9SI=F0E!KERv1UzJ0dmGV}Yl3V-^)w34} zEwYr`BA!>EXf_Yg6OXzIo3MAyn^rhaYU81%b??3+U+FKaE?HZGzmDv$eu(oWITKTT z8(ipNQLoVit9rlrR~smZ_$CIGqey$5hHBb8)6P)p{W>00EWN0?#Vh!MTK^&Mv-rTh z2U=Di_HX9%l`}o=(X}w9>@yt1Lcc?8@W@|R+y97gf#q`c*r!@{c}2hV{RAHwGywlB0F^Lf1P#WPj8!~6r$-EUr7^YGiw zS$TREmZ|wA`JD24guH+UJQ~f=+kzzhgsPmr=xzdl~mbZ{HXa>)`z{U`Xy|tEf@e%e!>z0d^WGezP=ehm5QQu5_f=CsmN?WeC2}I z|M^T?{;T#6$}DCW`SX zn6scgiHD;!cUuf3#yv7`+}7D{UU3ER^V}*=dY<~v@?C0{eSh`;VEz6t->#oiuehPR z%bGm-HLZzL=5IBz0cQwGg^+wkk^kkDblvE1O{K`dkvhRM0^%78-PL09?gSG-Z4A`p z^Y>n1{y$v!f3wXJ^Ii8Oy_=HXA~(Cb@z_(}I@z*22a|1W+ZpE)E)~4~i5Pay+XEc6 zwad)xTQ2ioiw3{F*RGS85X~>#l|6F>N3`DAT^39Ed;cmqn=PpS?>6xN69j{%ob{1w0k3!cz4&VtMk}ZpELm$%s0(N$qofJTMZv=p< zRc(^lyD*2%pV>pw11dVePW4fbczvjw?Ni!uxOpnryY z1c7tqg}6pd$ue-DXsz&y(fVIM5b+E;`}dy!)8r=IHeEjj>Iq3Ez#akv(WL!vO!@Yx z!E^Wad#+v;F3*>U&pDbUmVW!(3AY~m+E3WJuV6FrhM!aT+x~MG-xT#9r}DpyY~UH> zc3|z|-eW%M-Z8=1F^A+r%&iimk59a_9*#dtvmnw*0^e|+!ghUX;TiF1k2-hq zY{F`UO22@5qt&}g(+c+b5nRABu^<8W1j8KjjU7TPjJL&|yaW#CFc(}d#2kaT_VH@s z)Dn@ldxljqQ~LW*>NI7tVjQ1O0U&+9ipv*<_)>8$_>GH&8*Qn}&lW2#ex&kkPnGx4&JMn-%MP`=wX#qzDLl>-}=!^B*hs>GpP&u=zqFTRm2yKLSM z8$Y_xMdJulJRTKsUACt`zzLuDNy%rvg2BPnzhXXLB+1sZcY%hwQD#aI#Y&I)a>eN* z+|wtD!)HT+#>`&s%lf48Rw+1Ye7o{SgwEO-AUhiBnlHw5?O^~Wai>MSp;KgUM%C>0 zBz;W*-hS~o^5P?tb)Q|=np;k)SAFSZ(Fq@FaOBn?uY5BL1%&2agv3b+zHlvMq{<0a z*x5j{7Z!b7=k2sY#x&VF*ex;pkbU)!%RbQoW4a$)&`#LSu z>O+m7`WOt62QS&5er5M?YIxrjyNbq$$5({661FAuvTR;VDwTgS@m2R7Sznv14dc)k zTc4yFjs#K{JrwY&=lNzOIfvFA3Lwv}DeFZWIFneaO96}U2}MF%{Roc2V5L5B`I7IN z6y(N{h@%|&H1A|~Es_6IO)G-Ohn5h^gHKny|IfhoFgdp(Ab_^ASSe&`i({iWK#@x0Z; zqkBMn0S@phZnWxq4ca?6SEP5`{fUqSo`0zI1$~3>y+IEY7D?kr-qvit)mwe--Su=7 zuV)!}3}I&;Re5KWfcI=erL92>TDGoL)CIo+fABx-{fgc>MT1}B!Nc?`qTrcP;NoOx z$@i_f&NS%vl`1;1Ri(Hoa1oxPk`Q56!_xG3+n=IY%mB^4HEbfXv4Xw#Cu09kL@mJV zi#a~3O2RWWd`jts>}Yy!(j@2=3Mu{#ysk}RG|^mO4Lo1~JUmw`X3v}Dg}&&j=kh@l zF8>v{EnL*cXohN}T>AbOq~Egn>uc8qpC7Q;)Q`(G)3UCCt}L4$m`(sbI}D` zly#83>bt-Ncy1;7w#AUn(O9o5GRh5LIYT1!(||RGu_Qp8t*@v+sgVddN&?x5FE{Q3 zWVGf5qWStOMQC^4CQrRt%&jnXbLdU*gE%JxjcdXps;WovG^X{7NewNtzDHc1a^^iS z_Rza{Zh(RnkPYCycqj{i_gx-JCBIQU@8s`5Ma{IzO0?nRY3Qg*GdV?i6m0BtlvH%q z*J8}8U?f?g!rLGV-$=j;=_yPH5zhOH&j@1Io692R=5; zR-t`3^yqOQR1Fg0t}k$C;uwkq{MIyLv6{$e$3n)VnAMDIao389{0vnf&lAYVD5z+s z%f^}yFJ$inVIm$=4a87_$m%g&f0Ark^bcmM67l}0#tx49QB>ioW(Fz^Rp~O!!hdXU zZ<$`7fyZ!@Wcb1@^WqGkO!exPzy%{mD>LY3RRf>6KQ}hBE9deK8NpU-Zl-xv<8uR$ zwMMn$ofRv2n)E{!U`I=yzN4v7gH+an?{+k@pZX`g;#p zVFwiHx?%M1TsL+!4qZWQ93St#e@hSzGG_)j&tFA-t52~PX7K2XVf?-^{9KV_P)8UB z9CsuM|6|FLzdmDX$(7DANE`c;Y+pIg{<8$ef9?PA2wFp;RIo@ODRKa3|c z;Ijb^QMlv1VIvFLb?}-LHBA&X+s)fx3V*fZIlc8uJmyt2((6SkUqOBOceRNl7v0%G z$l@aco({p+k5|ea{7?i%#=R$*L?)lrTX3Ruh3{_*c6&>wiK7_YF@4;qv;@w|Ko2laD(S zanQG<(Xj5kB=tl&T)N|K(}d{|xJzycNzu?o|<6z}b8FiY4s`ZqnG z{W}nbPaKTet{E<=(Cb6%kF4g!gFS-!P^v&2o!^Qs5Vr`K*s=45Lb(>|V;k8!&lLxK zHWdRp4GW;m&$U(`%SWU~VcW$|aj=o96L05LiiOh*CWc`?_Hsa8Xsv1iQ%adwoXXyd zP1gtU?ImmU3{Ef%A4LqlKjA;E3#!{W9?Q~P8^+ws@gP<6F z?Ry@s>1Sl+ExNcZ&mD?p))I^A(L+;5ohukd9dm8zO$S^(dK1+?DG7Ij*k;83lKQHj zi1Vx%>zZWUolhY=HGOpoJCwVDv|a~VQFr^uEP4fw$d8W(Ao67g-om9(ovPG$LM0U*s*JR55+kvB6qd6!lJ1U7%4mi&n+pxG&TiY$R zm!bU9vWl|Xv0>Bw+i!{Jx?4&is(vMwfMU@2;weDg8hLIpEH~@iJ*~g)g`~MgN%Ws~ z^V=*Rw_j!YW3cekHEMc@)f(Zm=ql0_~Bf!+PyDsLPw&1VN++GW?GiHSh)gAKuuqn@?NDHbr*Xza;#sFev=}214rrQ` z>BTT$w(%EjwosJ8>UG|4PX2a^+_8+ia3MhBc5hWoQ;i46XzG%=HZEjUUC z1|z-q%WHhNF60Cit7WI-bN2Rs#G2Vm4-s_l?)7oe*JkIh!B8tcj;aK3bV9!eE1!AU zA(wjfz`a7{{8Rkw#%6cx5Z9`^j~_3L1{aDS+fUmUT3Q1FMa9&7iYK(5@kz#Z9ohot z@(qFXdj6VrPN)(&p>o}P*EZRMV_KuhiRSF)7ZW7A)>o&psdKB9*L@WIQaE#F@A2q# zq?g5dz4N>_;fJy9m4!4Npmg~w_v7jL6ERPQ!FGPxwLgqRqVFfXWN3KF8v=u=ctL)z zC~J(^{B)d+*?9;ZJqn-O;q7|%A00d1;(kmX9KhR$O*`o)BgfrgJReE$YabR>0gm#@ zU7N-Xt;7f`4RHD;=Skh-u*LOOCGa5 z-s5aTh?)iMcy{3`MwO-+4YYbERhwJG3 zL(Lbe{uuD`DXv))b7%(#N+=cS(n3j$`bz<$&1Pk%|lHs-zce4Ce z*R@16D@C4xLPkZx`LAf3Tbf08NY7&Zv`EJ}qGCl#civ;U#q{ZS9aVG^%HcANDPpH; zCo#=k`CE3N?Vd$yPda|Ijlepz2t`rI!(uZp)~(Wr5L1Ea&|%o6NQ4Yzo>~AA`>sxk z#l~mKx}dLpSFt?Fz)F`7z7I8#V`rW|jkM&=8$cisfnx}QPulCV%%ljQTubUoz)mY8>?#C5 zq4VLxQMF_sQEzgJm}=u>BZKV%=P`Sup?br%uZgGFPzs8C?9jK~M?N3S;qjr_jQxsF zmzQa$itu-0Urin@fUz8i?_uWjF)?dL^B=~mwV97xU*ruXM~stNH}%|AJ|5TgdFzg* z)yi-9_DMv1H5*-Zd&79b;gBIQ@Rp@6*VIEN>yJ$F6J+j_YT&xxN67Hn4DdJTO289c5=I zMxHq?=4XE*?1=I3HII7~vR_tJ;0nP$|K-2~%XirEAd|ryjI3sC`gT_rN>3?u!WWqSfuriK;&Tl#8r2edo8jO_zFjxVq~w(uS3)3G#ol0e)* zApqpEGa-_%JBqhWoRN2OoAfSN=7>erSwTK+Q0kzN&JfLOzUw*5{0i&&k`cY!wJz_(N>=H$h;S*p95oH$M1B#2lOSY7&3xbL8Yy9Z9OgKIg{+%zxHB!i`~ag_G?nTU>7TVm?{t_dK`iw11k@1B+s3vOPP zsf3Bq81h3EKF~C)50MHj#4$!(wWVF*v-)AL0k9Tp4s*V7Em>*{(Dq#|UeT_PgEAMU zcikp3GKShBD+72;Hp11n%`$+kmn9wtomtcdHB<{MkpNiBCAbuKJRbyssvC@n3M=JN zloqA20yTaWORNGlyi8Gu*3QRj7aulXA+OWoh0t95c4zMnzBoMm67~g_I$Lg~^k$#GS;y9&rNHEa3KSlz77-e%v91p|Y*|Ba7Pw>YR>*X3=7`D(1_vqaoEo=44h?HQeoXMN!W ztzmz9bm`n%s_comd#JY(YRHq{8wamvW~g}XNhJ1N@yV0~2$ttDdP`Tj&Fe1jtV5gP>RNfqnFfD|50L+m@pLMX;^wc*HD(5 z=KXQ!tJ<4KEQj1*DUF&}E;P?SPf~Bn5c%t>z)8U;FriSxLTTA%`#CiIlNFYSt?SyA zv=I|re>inhEuO*&Sv>>bYEFi#914S;&ESVk=Q2>J%BzmxEe~SF?0CVD`ug1Fxr30Y z>{oW>1d8;-G_S1nW{lv3+6uZFzcp!dmJ+u+S%EyP@e{EJ!jplEc5Dsq@Ix$&ioV=? zTpv3JLxo5X2@4UWOZoT6rW4bSr;0A&4$8;F<-2|&EIx)Erv$e*sOf9;j8@)VLsM1g z#c;XK9|3uD<M^}_g9VfR_ zm^M%jJWIw*^nFl=p83=>g)1j5`cTHZrFIVaT6j~)%)MJj?my`BdXa3Yu!8n*M$BIS$IY4?XB1H%@=TRZpcZ zevK_=PT=5LEQ75LJ|Y`#!^=9j_WVQ`%ZxWd#FmV75^KWhvo?LCR9*1g>42O&dM(#+ zJl6~!R6aD4-afqHuEJ%0|5n#);)DA4@b^Z)e93)xP*84zjY57mqM0>#Kf3id$`>ec zH>+0@e){Oa{qW7k!%1iaVxRed@TY0cF|^d2PYkhKCHsp;^Majy?*&__;pMtYk%p%ck>1w32ZRPQAiG};0ivo||uL>N)R0fRO9Z@JS80~vetY`s|%@%2eGd7#UvVvHlU>xxVpGfvl{_`$_EvzZ1H zXx3t^cK`ZVtIHe1m7HiBK(PyCpXYtFoVKsYU-a!k-ZW*Zd*D`8kB(1fEXO?bs*ieH~ns8Sz!TNnYKPAXdTzA zFt?gKp?wY0vlT7=*tdGZTzXVy%=sQ$;wR!52LXo+#g9+!V&9rrgsXuJE&)xj$8=@E zW$ak5h~;KA{3|by$!ZT5cqhv#*4BN@w{8eI3@QPi78lmsKVF32pHhipF#4 z!GS{v=)uF{=T}uTOsyOVX1}1tJoGG?100CfJ6DubpJ=Dgbhz*RC$`7ub?hes48dpx z;6w?iC8ZK3KIOAj$@If_&e?%0NMiAQ(IEKK>}Ai@X?g$#f3W%azYMq|cA3N9e{_H>Qz%d^{6TV1hcC`FqOMg`Mdpe@${40yH(kX4ANc5Gxa0MFy zf_wtiN(J(H?q^P>L>cj)xu)NM2#(9lG0$odcp#tJooZvRjR;9xjUU!J--6(oG%ndA zF6ZgR!6tzNL6F6iybB73FWATTUMJbmsi&L0hCSDT3^ay{Yth4@?C-n+T%VP-xPuuk zz?>pt#M5lXp!)^Un8ZzEF)40weA*fw3ZO>XZ7JGX$33AUqOr%vWZTIk{qZe`Gbg`% z(3Ci~NhbRS6O()_tXhyUaXHcS$DNGfq|+3HxPOcKrMm6uXvfD7kq^+`d3R&uDA8zI z%&8Jj->;yuAE`DW3be3bQ>KOheqRTYYD49$J6aBrtqMO`qDUaXC%^xJ+tbQL1B!i^ z;nC|=V!CTUyYq%&w+)j}Vs^x&&B;dQB#Hpl*%Hac{tBE6b`=rR!y68s;DMhnrgZa2 zHVWp349tpV)&n6wFA{50oVFX1pbQdo;%dMzL1sDBtfI zt2zB}6|yTsYpts`wP&tr(v2?hN?=0Gv%`~h<6#S?F1 zgh9A9ycv{A&*fZpNgVIGeGR(I69>9^fZPZlEOEtrd*ZL)u*6W6{$C9Z2t~p6c!>5m zG)yC4lZOOv_TvC8B-mnGsJI{^qvJqrwf*9xZ6V?^pk*8LR8#ZiV1cngjdmpzsWLK* z+YnEIO3G!z(mFX0#WD%zic$o4A;S7DNO+qY)?ir6kw9IOUwK7JsnGC9rU*c7qwGag z*F7ScaTWj_X4o~D*urL6%5?ytS(Vf&z|z6u@FuiviHHZyTTnA zoX+IfR{rqNAYge}BI@ismkA|Y`;z58schc%^;`=yWVlf{QI)GP1kx=4$2{b@@b0LN zXvVXz4WLsI2t<+7QSakbKcZQaW|eg)F1$Z)OCD*&ZVl=BEuPw^MoGO#7-3VE*J#AP&g~n+{|7;3#T(TK0_vW`!CsSP~`GV4E-if z1Z>mfVg7JreMJ!}^*LO+iG!jNKH^qDYRX}?MrY_aoCX+b{r*sONoQ?`(giCBOcq!d z5(~bY#a@Or>Q;*Cc@Oa!a7-BsL$i~AxW%o&F$VTlE>KI-1!M_CxY#@W?jJbz8*u#h z{y5l+!*Zjb{$!+y;aY$ySB@v4p6hrTndnQd7zgOJ=3lcv5`F4Z<9HezoFSC=D@x}% zVMh9aZ)d^M^xR001AKP4UXaaE2+yu0GFv8!vA{;9seuQ1 zZ7=9bKc;Ef{ZBuvd;rP>Fk}b=_@!|j0CZp~V{#UIF`dMwvurdnXRop47vmE>mg`$B z*0;);8kzLwl$1t+h2-CNg)K6art2kmIJg7=u9RzN!g zK>3dsOnpTRn)4hF3Yv}bj;OVVZ%vUMO6PdIlud`oUgBAuj7L7iwFhnrD*Nm@#n-PL zG_5zgNpk$F)%?0+5?4=oR_^Gw@E9K2^llD5dLUPSwY#*{nVKoq)`SbTrE%02h@W{A4K)&Phc z1IxhrSn7zbCQio>?{=Q)aLwnrT}ZX<)_?r6=|lS-_soi3y=Joj5^jn@j-r1dGGO(vj%W; zE40R3I|ytCqg|q&O(Yr6flE@nbhh*j;4@nti?l-!OAW-Qmj zPok`QpIf%R)6j?QGukZ{*@yi}Amor9ntq-7Nh)MIdbEg$t4?S#FhR4MaX6h6AsLW0 zzcAe2@8L7l%;4<0Ug49r09W71z$9&AS(Y(Q@uZ3J;l2AyA%~ReO%>&ySJrqHzIt|m zdQ=}8Sfz#?hnimDeNlbLCR?AN3Hz_s>b=}-;tc`9j6aW?7prI$Fag>maUlLDl6tgpMHZjWwY6hs{1R*0-OZT1VfW4y~ z90*w-gB9*04uAzf9f5A@m-YgiYs9fj7k#w?v^rB{;6qQ7ZZJqpvD15vePhp~M(LT0 zU-$e($Q+@?9`1vpnXz=X_RNw^9F;Y;>mu+#bJm`ZWi%e|%)~SDb255v|3qx{D6jnB zxsWQ=_jcg%9@oi*^ZH_i?eBXTGCFOd^)Sy&N8O)1G2iD`UW2!al6*uxUN*03aaVG_ zpr&hl$$o3zklLZ$`Myeftn-5BbKKq={qPHYX%pdhyIRX=Luu5hJ?0@huJD?>xmc*z z@Y*H$g-Cqjsggk)K9x)&G8gpb$b`X*`ozMc&BU(PI>R`?zMigRHuVFzR<7EbeQa{C zvAz)d!Z%fC)&eKg&ZJq7HBWE$(CIIv+9Q8kq)n0X0529@y`Z=yrf;z|gbA+xhB%e3c<5R<$ z7j2pdphzzfk5tA_>D)^z@;rQK6OM2Uv~vUpU3AKN0tc zv!a~z=LHL4P-dY%K0oWU6aWuA$Co)~KxY<8w!I6hCjUjKr*R|`9qw~OK3u^8(0rX^ zN(E1d#N-o0^hK|rP2$>Q!_}oMP~7)u46>`bf6psJ=ko?wS~X8{MUAaVd9MH{Qf&my!bI!@5KFS}ZTj=30J4Kd_yuZ_3<4ZtIkQAlCP;K;V&=)iy<)*E~W|`&*C8pk#GbN_~kM19_rg?hq`|?$?-Wia?tE`#3Zsl z`u6ahOrWgmw^FqA|1l|*UX;A;*V)hacy4Fx!?eswLyC7v#j8-|Oux3~^?%8yC|ta= zaaZ?=fyBh*1k+@l<}!P;k2ZVMaJf5?8h$TmiS2?*W?K4!Iq2^$p%m7n$>F*S_W0g- zKg#D9_;<@t-Tvse#G;%yV*A$y`f zxcIDX{d1-AeM!6TURe$guZmR}K=0@+yg9ahwkkuTtZ~)wT#xn?XV;_(fH)?}In>rYnZNNnjLT~u**f_e&d%7>maysKRtJeONE8Mk z`TSlTFV4QZduuzM2t7|;?A3C*ognIbeD#~U?R<}Ii6Eauc2&I>Z6$4fX??}*%T{Sq zDY`w|(~Vv^#7{urRO%BkwCRg#>HrELNQ3vuWYR|>)u_(RmpavWyb92< zAv>ePwHQy{+B3bLTMu7t=^X&diP;Jxwi1&f(2>H>#7kEo<;hgW(xNB^Y7NR=Hh2^g z*W&;rH0Ez?o(mRgA%Tcg9$$o&oGUEWI!Y5 zC0u>C;?N{0dSi9DJ6Zx(9QYNKY^ZxhCb1bP1|jjIXy>;-60d-WCp?n*nR;}nNrZZGS zSyF`w6DDE+V=?Ba43G#=%>~t`xp&?clwOeR{8JqP26QsO>%wielEVp0Neha9mKKy5^(<8~F&TOCpW;{!Vp#-0?q zEEeetkx=c02xVU3J^M$L^4L#o}sbQ4W@ zzQ{(sO$)zFGBHwZx*{hiw$351G^UM0o&ag492R8DdvGEQ{~cs!GAIACPmH%}pVt?n z;(t(E>GTXiz*z?@G2Vtn=h-@qr}aPN-Ceqkdq@H&&Tu0Sc%$$wY?^g5c&9)aAY%tG z;;m~=+)xBxaqi&RJ8r3l)3xNA4W*Aqfa`EhXE;m|2DE$|sZ%5-+cTafK?w#nGje}P zBwsOg91aCpBC14%>?*mhT;Kx|O9pBBjZ6-1qFjLisH&KQ34jWRSZw7f#vNi5{{yrL z4?y_hB{$iQE9-w#DX#(vFjg;^nh)*U%I2zkuwxrQYg{*e;Ed>nUvw<1GFFQr$??>7 zaxn&d!Q~erzt&nH(8=P|h=3JM1W8f+O);S>+>U78L$X=g3_4uvza(k}aOR)mqVF38R76RU%-K4PHw;tveE6c_M?A*m3s{Y~b0%K%yr+cN8fXVfVQf|skO^r}Jm3jh|aChwyG?~cW`z~8y>A4~( zZ$ElD+xn{_cS7r%J8-D{+#7v2X+{S&$>*T`df7OGpPW8PRrwV3TlsU+Mpr`+RVG7c6hPNFoBcZ<#Wyt z)K+g#KbR)DQ$RqleKFIf2y2G5R_u?N?ss1&op-WYIu@C^OqksnzGqY~?$Ez0wgW4| zLjc~Kqj?S^^oKRr@;>Hfqagzr3WyM@Ng!lQimdp5c<{g(FyJie1ymGy2n@9yS%ENbX# zAw4{gb`HfKS7);}STMwy><>wg%W=`8Cy2-;{<6jOLvw6TkT;O?R`~ut7_8~ts~nTj z2|2+sjn#ML=fv7UTw_=+8|XsUtZPtMjCl)+32{So(0(9k0VTR*XNqF^U}MXo?3Q-P`wUJg#>iouE_W-nJjqbzM)1`cuune$IpGI<2-t=>bg#vhQprM?h z4+!W&LVl^cp3tY{d!6mLHe^Oxf>>36=#os#SSv4$rE||XJh`L~HVW&35)WStxw8bx zosvm-1fua$Pp*=C`PX}FA>Oy-J@HjwJ@!0!B9FmeGdDwW1TvYz9-So}@vz-`^x!OR z1O(k~U5tt2)|8nWgAfAXwxO|j#xw9a$`~VO4o>L&wzqH(MBni=jtaQG!WEuWBmqgi zSod(jd)opSg|d01A2eOns4j|U2ivCT1-tOdr6;G;!|Y1OD*7T7w9U`m+c_}gCnbRG z;}$4!lNce5ck~YF86Vqf{@}@LC3j!_Uh5aQhu=n3zB{AR+=7RW`pF0X*gfjGExfNV zcapaBB&urzza&a;YEPr?Xwqqm8clP(WYP{hp1QGp8pd;=j$U+R2ZH}x_&x%%_UdH; zR00fr@3l?*h5?bWb3TEFrh+v35QA+{D|n?AM})I1gz!rTvq)5gAx z>0^OuiwSn~*d+N*3Y;x-U~X*Zy>cAy=u0zY`j9h#qZke9*ErTh03YthH4 zRyfEyY9N9E-woFXb-bRD3rddQv7%;#^Su6YfBq1Q^TJTuXVsYqiR?E)WGey^Ph^U< z)&PDnwQM9fN?=GQ2ov1e59l*+b%L|tb1CK5-$DGq>7d?RJKLitr+c|nlZm|TE_;h4^l9=B-Tx{FmVrHXQjLfXJM6ak!? zPdS?a?IqP`FSWh38E@bP+6NpCserDa8e97SBBN>p2ipp&e?7#P-?weXTh(H1Hm5&g zt_IpsLoA#>>4Gb5^XZNs=3Gz0?ulkx1VK6bpP{_oGs|yI;AtBRCD^^p&d6LyXA78NhoDSUfCgYvhHlk=FJA6L{EdzF{UJM z2z=~a6eu4#Q#^m64c{>Dc48?E%G#&o|BI`0#mpmk+*$Fnu%mS-%Fvgf-?E3PRtJ-W9~Qj zQUTu=eufB&pYku(Zuqzumi13vA&=o!dmmORcx=(YGqit8cvp+Ey@dWAMtq{-wW2cH z(g9DRPQe!TZOa(d4(`xRg|UAREiO3D7!2P5!VCW%LfQX;P>;{jkoiLusA2d@N4azK z-hZtX+&>9*{6y6CFqQo~mR_56BZ0*2?ls)0>spSBcLFV9`>uO4!|pbq;!WMlm0M!| z`#{_Y26hr(rm`ni5^0A_2c2`L{I_!9t|iD@b+)!Y%{*H6TI*cCY-G?F_n4!d zO?RnSF~2koWvHW=Tdk*h3k<)`b+#Bka+-wf%FYDOQ8)MNPq4*!Bj7p3T_3Y(f`jhWD>Gv)M zOAc6XsR#WtjM_#8)OU6se@o!dVgW-h6o3gl?VDwCZqz~e*{sV7 zCmV|a3nMsJsD`(M&b`}pU4EA5%&T;s?F%HxS1`Zwu8X|c5eVNt45_Ghmtu4clqFFD$o(b zvau6Y6SXC%LdURq`x>%EuI;EKo9pzP>P9L2So+K{&!yh2 z6^3kG8vIxCsq&|Ny0>$w?Zs^1pjS?nag%OP{H_#kh<3ZyEf*??H!hlfZ!U3`O|ZU?+V}-lR+bdO5X*T}{6n_?^q07H36d6hXt4vfS+$pf_Jq8nXqI zatHF5G8di#XVlrX1H@VI_V?BReWJ%h#b}@QV&C+RnC+4h9RJv5k-dt57O)HWd~iV5 zz#&_?0bfSGi)+I+0AGQmfHF6?lO29plAVA1Y+Vo+o-i2M7C;uEm}-3_snM0a9EyYR zUFrDQ#Y!%5w{L?S2yX&>$!{;PHx9!80Qjd<`4$8Yo&d46;NXIf?R*oolF15}iKj7f z{wHczK~z@BtXB3n-S}*4VF9zO;`RzEl?sQ5@d8@+Ke8=~Jcb-lJoZU#qY4g{%A5gk zfX+=~@J0YUM{W&m2i(^Rpx(yPzV7FDAK&9Sj^}>v=ljQXxEf~W^Lc;H_xV20*ZDeMCyJ%_ zk>40e8QKpuf}j}rA%Xg-Ve@k59yt8gBGK=%N>1o3zbCcHf0zp$zd=^>1n*QYo!hzk z?{+2d1&Cp@HQ+5PeeZyH%M?c$x3Z?NAtYn*ld{FZjU2-`TU7h>xK^RSY8^E2H8qp< zlQ#Y*rTCg%E761j?m@vh)kk*g6HyH2BcRY_-WkIVT=3CG66W$rY%v=z$E~L~>wwcC znw8*eA&3W8pIx##ue`Skm5?3|F8~0fFkhsp5d&+O^Z_3O_6$|4|*lfl732R&w6-iY}R};i$ z&=(yA?>U<75HN<>2xl9fAvlqNaK6OM)3d&g2BX(g4Ms27PZ_VdBwD1b^W4}x-)+~z zoA?_H`IWD>Th(f}Bsa+IN2kfhdaHRG4}6w*fRmbXIcVDEn=i4)I6YR(OR}mU;bN9(F8c^rHq5W;E{+7cxXwzwWFPM3Y=IR+pREFdFf${OQgLDhF# zehH5#U?RJAdS4HFfA!~7Avs7%BbShrnN0@ zUm^jDN$!L`@7i4KdO-PJlc3(Yu(66K>>Sxmi-K`2#V2YOwx<= z2x90aV8NrJ{G+IA={A2(+_u)K4~oERsPMf;Ge8OHaUW38xi-xSDoEZdd0UmeB)swtBBzW zMT4ik@swnGwh$TllCwSk-QdE)8u_Ig`rl@$RmU$c4qmX{fkF5*gh|y-{NDWE-yHc4 zP2{eQk3LqqJ%e-Q!LgcVc{k&l%MXt4IgxI=aR**)gP!O}n9ynUx`>un#!k008sCN< z-2oGdj+=$4RNgtz0LKM`(A9A z=k`An0!_WwXvP;|Or?@eV$!77r&qki771}j7mSHj#u6{njyBv-^ zf`D3b^Ut4OVM63WIn!+7W^UN(U4urzU`!!XpS3`;&xIrAmse5n;z2Y(m*{Lj7GjQ^ z0VmxYV4J)JIaBSrE3UkB9J(!gpr?j9V>M`iFTFA6Uz4_86p=W{L$QWFf)vU{KGq|& zqRuq+95-M^BcQYwM-UG=`3L|s57fj`Vb_DGN;obSsKN@wn+kVAZ$KgUqoP-}MAj60 zEfAsR5F72fr`e;rib2#;c_M0Y(-;BI^fbIUW|v27+)x$W?$I0RW6R5}h?$||P$1ex zVBbb^g$KtbNwhd99zY0Sa{VNw<)ZVOt?Io>GMFm{{X+^&V<;Zc%@&!M?3pzY9caHL z{r+oj_}PW^H7Vc4ii*xzwti}T_r))9q@cPqD}RmcP0G~xuG6Xc7?zF4U(H_j;}^^O z7UV1l%mu{3U;RS=qOP@^=u5$#E`aU?L)4kkw*l1-v9BGHma~Lfz{(~vJ5iuZ$sQ}i z)@-Du)p5}ymS8SPLe`6piyZE@YkNUpvK4^iKCmw!x=~?WfFvW0It0&we<*~SUM*K7 zO7^e*%AcjyqlkUuD0qU0=2gP9fJ_Z@j^iVQwqF7V&KqK5_wG=S8zuADM_DI*KtQk} zq=5GX$sYR&ds*sh_Z^FSqFeZqsqG*1yJo{b&JhT9BM{g_b5}a2z2hQ=#Dm8Z9{#!Z zVL$~vwsmQmUp^Rj)7&3qLVf(<#Gix)d_ngEUIFkExqzv76cGM2QJ)?hT0|2@oH zo^+Vnv;V2^Rdd?%>`5cvx#>jkAYt;T+_7mOQ{b%!tHRcBAWaVtM>i`=en#3~> zS$3yJ6V6mI*Zs3tNATw1c`K+*{@M8YS*wmk?Ah1AIq}on7@HabSgh`na!7SsmMN6` zz)f~JlLNBtu@=RSV!+tiyY9o8AHi5oexDY|bd!DkYOIEX?*A7VA8ZX=_++>oY<7Cx zsOE{0*$<*=DDC#0T_>I;Zm3I%C&;Z+JLReF_;^*r3*8#{7FUMk$PVpvG9qm68ik7n zvZ|SDtSyoZTD^C2=Ee_)Y!;&4KghcLfhm+|?-(tHnv=DieiA9qK4L*=W^OvZDnso; zL^SIYbJQ}q`BK*HZ(n+X%A|U0ugsc}PKZF~)Yl6Yr;63ogom$C z7e}gK%qAfKOsHUNJlh4M^iCiuQC^>EgchiA;n}z8HZc6tM{s(d~YyyTVYz z_O8^I$79PC?h29Fj3bD&mU~Bq6wX8V#ZM-o)s=sVI#cJoR(Y)g)dGz;M|JY7@U2`# zHF{B+cZEtL&lKJ(tR}tcY$PUnWcLQ~AVk9}w<7`zi!@5g-?_W{yZJ0^R&8*8~nz1{Vd?&=KVpyzs*{d6qA(kDG8Y93mkg z{BThKy7hAXz-wNXb-BGSoi_1c5zvkW zKtt=O0$X`T6x2$DFijj&@TYLV*fzc5&x7|GCIQ=L^2-*2g9HS>KxPPix_-e7oM;o_ zWROULHZGu`m(M>iL7f#86*D0)@&ahZ2_KnodB|CBn>q6 zuIy4zWWyF$2Bi z(Or3b851DfyOj#A2!}$S7c&EXxtmSPCVKcrftDE{NJ`0_(x2=dlI(lcv-J^}OlhX| zXDq_+BkJGahjt~`x}4CZv=vL)B7sa|<`WRw8hVh;Hs zO8HT(2F!7b9tid?J-Rjr+$6fYdIbVM%(EtQ{AxTIOAQ^`+pMInkzknnhKZ4ezXpch zVkhF6dIE~tVPfX0aDoGs#$khbH=9xv>k4I3n`Xf-(Oxa+MR1j|hTdTEJ>G%mA`oI} z^jBi;f?{Pzj#A5$2?Y17lTCQQwhcdF(=V=QjN2~VblrYorBA5P+oRqMCNhfeiNL(E zf$TY%DsQn@3%q0f`(|I|h$f~E758Ub8)shd0n|!jzYsK}^5L-!zVffeuOE#I2Hz@7 zHhs9GvsYqmS5O>G>tWbI@#fGS66QXev%cD6aZkFitY>3ipqxH;H|GV|nfOLf9JB!2zuq53~Nl|Yz zVt&J`7cx6AV;oRYerYIKH~1qb!aY6mW4j}=sc`(m1bFU(N}uyUV{K>^hxokyKn(~^ zKiQo#x&_wx{aUXFoSm496?ZqSmm*>CJtlxsH?o`78=#SBuA6{t^C?Gf3Ji48*v;>& z9MW7=9b6)faV_n(8KpR@s|z6UgJx@OO)Yp4z?fVyr4(kdi3@Y|(39}wUX7K$ZEy-7 z5Y6^M_)Dm6rI?VALq}9DPR|yTyKyHd0l5cw$|||l_rdyIk+F7AkEp)*5)p}oW(?D$ zrwB`VEPi{E-9|nLEExBG0aT<$Hx->Lhc?M~J&WM!En%v)opLcL7bIO8H1UaZv>t^YHUpzL|_svM(d7P9yZ&scHff(!6#8t z0;4e4p*7=tKtytH{kP2r*HI?QmhwLZP7;p3mC{(-EU|6>oqL`yjucoqANdqpd;+E? zF}pQv|I0piTk`l`5BqZ6Ed0rbecq?yL=MNF-;*r&q_(GaSk0UJ=A;V51*=lO9IW=43c85L(YS$BWYLd6XnrCMipO6?N zl!Zs0SBEI$2#|2>`D*lZ=~MB?B8P&Y5=J;+@oW_t1Y6#fVm{Gj)Ec?6p?ydRKtjl-ioB1dbq?vwNmD z>Dh(NgH7wM$4>6bk7a5-$tihpF7`CbPS;L++7a%QeF)$jc2jz`jGtpq+C z%PK#Z65VowS%0SRwA2O5^Dv zRA2dq;spaRW)^V++7|vfJoJU@D0Xy#MFJDg2Ny9%xGB`MgXjobGuw?(PqOdng1B$R$bKH!>Mcc9s@C3n=gQ?_i!fkLQR0iO?b!N zo~iYU*sCDcLUJ!Vm*FVA(v(14@=L81CNW@Fs?Iz+w?H3_51pOlc{$5?felb!fv8F8 zYe(D-L|oTY-NHO+FgEG%)gOTC;!L@)hht~2P@`gq;Ju)|0I*k&ixlG_3NxJrsU~g z65cstaBcgRQ>nY^n$MHYlXj=FFE_`aJC=mZs*l_4@0`A)p8!if*h+(13VZaH4&O;3SC82#ZR2nZfMPAvxGVJlT|prh%#PuvGwYbl@5$v$=*H zLRW&ha25hTFa=wk38gS63`2%uVHEO>O#s2_Jn2;i8TYl48kMBr$YeMCWm$1FD_M-A8iyRwMK!lX>x<>Lrx;%~lDPF4iK) zWKJDJIhyxhHB;E~BFEi#G~n6Jq1VOP5lhWOF7fw2wx zKJQZ;o+TWk+z;q(vRi$`$=P3qLYcH!-^uZ$Y-%@AcU!4WIS>`}yjm~hLP60{wH~P} znjLd?R82|U;Lmjk>W54(3tS|^0Vkw-*6@R?k>|=?zZpy%UNrjfW}YJ zPguV469Jz!j#{7q7c$4IOi&P_g7SzWX*Qn|eSAB(;Tf^q+Pm18v4w+n)kJy8ac(mc zPMcM%nKu1?f*k>@c?X!Zg94ZYC22Exx?;e_3)u@TxUuB?gU8`#MjeYJ-b=w=4}vX% z1e>Dkx~Dnk2i-!x9FH;Mzl3Ad=I>l8AV2Qc=I6#74ei{nusDrsWQ#Z^@h+--k;#GD z{0v{FkcaGQNuwIqA5eIr-xPJhvsxv3hCFgTU*`?=5>$!Ic;a@suCW#ne2_zsrr%ln z;7$8!^l8!}l=3Y)7S!EunONJ=|gmYtP|@y~H1 zDzy;0nLy_7>@8vnHXTr10#Ps^<{wA}{XO@Sc>>blld0boLCcgKN}}co(I{ z*Zl)EzNp#%7`10F1_Mi$JIOx8BQ^qDo>0Y8I4^Y-qJS^EVwik%6)Zd$uqUH7FXME} z$rTa+p{LUyY!SS{hkBS8po_uJxxfV=8I!U8;Egfsw=Cy`Y*Mv^bPm6HsD}3wb{A$# zM3E>I7H0DIl z9wrfT^Kj5P+jJgO=!)LSO|21lZjQZX-Vkz z9DutHa^h|3Jr{of6F^gmCK%j_6<5I*3Y)+?I?4s*%2c+2ocl(`4sST9tVNq`xb^NB2B>=V@aRX-#1A zE|S;~S|#(7l$2=S$mZ?-U1-Aakg4Vys1Hd72Az3*7w*&BoyT?_FbAiXwI;iagG>h+ zr4c%J(b+`Ju0*TN+mUurF$rL1_*#l0XxJ!~<_I-|2RqQPwjD3~MB_`mD#v$WD|%MVb!l~)Wn=qsPPX=cDfXE&*WZ^g~}ER`+seyHR_ICKDx zKnxF6>|?vJr@4Qf*65X6PyZIZ(#O2ZkYV;rrA?n-SGm3&i{kSbB#;&NmBcYUV0ofO z3P5P!mZs=7H;(F|a}A+vm{d_$$a<+LTbTbArfQiB@*w@bKgJ~C_FF@*acK+p;J(#G ztrHO!UvGoFN>-SDu7{A0Q>uKc7@?*%A_uN}jw=VHAT zzu%Az*d>2*&7=9V(YSQjYkkeJ`k*ye5WOD9 zHD))LWze>^Ua|SoROjQB(tPT)`uTq7D6dMX2|re5=#Dr|o;>mD>g79OM}MekXKePG z8dhCZm634l#hoy{+UjMIoO0h!yxW{s`!bILQek*b-mM>dugtZty`F(57T1)olaF{H zPANOr@)&l$X~!w~<~Ri_8FiIoq3g_y(T=6WPE9xa?j7HHV=$hN4@CIy2>m!^dQ4;e zdWDx;Lh3**<7-^KOTosa&kIb3&hx0**qN1>%nSPZ`ld08Px64^gU;s`RV6Sm1PBti z23QZXNhL|CrmF84-SHOAk2uJt7-0 z)40y`37*x5A8`ujk!b}%Rej8=(^;AUU)>EyZfgl@kJ$o4>qr%2r85$#2ilF|&nc$m zrj|oPW>(1e-A}&T2Oz;C1cNp!3jBllfX;RKod}kM?Y{CB-{saVQ}FDO^n=%U;qj^| zbM4)Qi$P?{+{pSN>YGYSOg^$xsCe@9fO(AXfr% z5kc0wK>;5ES?{j=Rv$8BA>{WmA^;r{_4P}`TEBJ{ehvH@@* z|E$__m3t9AO<)vgUS}g4H_|`J2e^wWyUT%pNO6e3{9OU<$fj}gThUz6EAXzP zx`2V$X`~uUd80o3s7vpjxXRx3y~i4*KfDe-EaW{bA)vh@&MdXDPNQ}tZ&vp0!GOkT z+4%4G_FTMlQr=B_;CRZ?$9s+YOy@7?=QWSWF}F{gIByORgc-Ai=|#uwbG+w=-gq3k zS{pcmY~P))x8KeV`KBN-Ae&fl9K=Y@n#3{Q8I$kZgDSh3*57V7ry#yXS8PpqMu;Al zX1LKk`A2(Ei~9wn5D5bYKRLyUDtp~Fx>#Iu@&N=i2Byv2z_vhcvUCSS)ssSAsC#f1 zd513+Uv4g=FV%rxS=>kM2gSR**ed((dTVCk|3%ep)5&Txwq*BuN7(I~wbRPq7=g!(vgJ%picATQsFx4kojT0B#UTg)GBYTwImJzxfdtxT=F_X?NIGR zb8{q$Kwv!l>bn@s6$+jmwS(^x`w0WZbMwG4z=K_?agpqsT$HXIwJtNwVolSJQTG*f zxkISV=-XziAy9UhDxcNsrgwp&v7=y#u99|V!EG0|5NK1nnG4x$DCHPJ?_o;S;UMm0 zAt?8#OjhCt>I_66KAyNp8gv#1!O=9jsq0+L`&EHh;*6QbJih?*SUOMCkL}IwGV=d6 ztcC;#T+w!aqB*fC*9S&73vfxg{GKetN;!NDY%A?7_TblOft-CGPpn$U3WYtIbK_&c%^ai^Hq(%`7ysq&VHd)FNvFqMc=B>=kJ+ZUM2J1jQAUG-_dcq|eW z?LL$b7J+spu#ZFsg`sR;cbAIsV&DV{fr^p|u2nZYuhfwS#K-J^bbk$?};qApGVG5v*Uook$<+NF?F)O)kMwu|TbA`qx-%0pZ&j3X_wLjkRx0C$0__1Qc++aD1HrYcIEr3~B>9=8H^kAvK_;)I@)4WR{u{~jR zNY(%pKXGTVdQqo-oenFl2h3J)=V2&J(B=OZ9wTuI=s{-WYXc+WuZtF*IOfnVQ!B*e zv^!+?Sqg9?hfaF)W66SFwVL%VaxNyIxEVSt9v1%vl%$zs629)CYzzhb5wa~x9(>3a zjg;mQKFwk|2<@nt91+k8!gVIqtAZ`mha~;jlE@HL&&PAa#sr;OlydjN0ePhoOxGR2oMAsay zxWGexTKIKmnnN3l`+k4?jVY~JE=Zzy)yiu~(`?5r&z0R3X!tTCY$WKam}h`Fu%c+? zvq~A`4v|62j8C}(Xv!0r^s#9(F|(CcR_cOC@TH{1j_nc}SG%xi+7GUwT&T1rARZ6{ z?SJsFB|%u|(j-Iv)$*lv^syz3iOZ{DBmDcD1?7i>vZ(km)}abF^O^%p1nmdD<%Yfl zy!Hemk-@1cRo={hw8E&3gPDW)Kss*hppjTI3o#kOo5l~KGW_{cpI^h=e#m+0FZFSe z?WH@5Moj>31uF4iv&c2Swgrbzf{#7uV($rs zQ1t9?cio$LB2B}xfaFp-H)z0@X3Uc25zU4f>pz$h`HwQipFO2eH0fzfa7F?xAtPp& z0Xiugb*?uOc~@F7oh-mx7(->OqJ-a?58@86oLa{fa+m+ld4&A<0xPkn1QrQXjF2SK zIDXc{pKU=B>L?7CoZnd`OOk0f6D5>7-@R8?(jz;MU8=4Gw>vV+1o8*pUrj~zWMhH+ zLv0wcX!CYX&A=>iR_0urj(h@DlMKSFqHdi2q?c|0h{U#CepmW_g0}R2HZMy&tp)W8 zV9p;BPK}tNwf4}KsO=n|5z0BCwDy@PlTBalpq$3Y3SH%)50~cUj?z0)gcNuP8ezbe zyRq81T3~DGk8jB;C*t1Rxp3GE zS=}sPE~^joKPKeMB^=cI=CxpSMFZC^Bqofb|>X_Qrau5-X3 z?XW2twFrtgpMSzGuM5u%9;E1LEbOm9KfdufdoLU?p5hgni!X%n5HtIiwA**Vm10=5 zxrG9#<#JXaH;m5xt3;r|1SYH6S@66M5}+?$dL1HR%HQhCz4i4;Iiw=zd-qh{mh~;jZ^&jHv5Tr|m^X&uQ8*7blK;O|{$GBrbIDVC*n3LJcEym^$*G)M1x_{Jf+RHcbP6RToNeR0HOrertgL3gq@5S; z5N*33U(lL0*>>x(Xe_ToO!Cx(!lFml?H^dMpPd>Gl*%~C(yJWW^*T{D1=?eNO zV*Ai(ZVIwa)Y-uhTZ$z&r36f$OCtO7KC{muQGjuTLE+8>*6pMfOmng2td(aQNzY1(b}fVHkQKE3wqvi zxdw{DdHuawkvkvjQ=b#N-(%ms=ecTfXM@1`z}<%{IiAHc|KPR?lb}C6r^M^+j;KE7 z5qacU<;ozyKWRu3GZW{G3f}&DFC?-*z+kC{7>_o&TeO(;o!L#9t!RINV2w&5zaR%u zxMpxAQM(R)nuK;DwI8+6rsJ4Pcs%WEqVEus%;}8PK0F zN2xVgiO((@1k8Wkl6}W2*`|AJI|k~-Yyqt)5+I&-+X|+0CP04=FUQkPsm@NwtRR)YT;uA`K8WYEVC68>~x@r$_AV6P=HM+MW2f%G;Lc zSEV%{SP7p1s91I$kA>tMQTi0(IYGUM_{Ue8Jehd^rDoLWgt=&of&vgj(u=VC67wqZ zW5Hj)=y)q4KBt93TB}=H)Z36dVX|%3T}R%zmv=5~ zavCYW`vLb4LnQiD=|uiFTlN3egUcQBa{9=r4S89%Cp#nwL;0HW_`YBJ;f`(R^rlLD z?{7$cyc|NGejs?j)MqGVfxq3{w%vZE12)(C|IR)5zjd|$g>SI@yh-cPyPg`aptxYt z>$zt`tgPnP;iFp$mlvM`79aLDg!Z^CC=oN}B6fjV1WdnZ=;#t?L&?6%11Rvslj?^P z^-Uw1pW&RjUt9U{{OwngD6N0|&GIYYDEyCi{hz#|{o_k&Fr=mUOmYvC#975(@}8&g zw3g~)zw{JjsV9((4v326-u0i9K5ea;9vSu9i-She!+an0|KO#J3o@L1v8>*dOmD(> zKeeeT=c7kA7s_6Jx)@G6YEcoHJt%sr#g4IEH&3@x@ZnLFRYEF87B3X~qu|C}7Zt7E zW<2*=+Amzz+<5HP{xEwC>+O}P^oKXJAD@!{c!ZIJA5qQ9{#fAoqH99-RD)VPI+fwr zpZ78@I!<8*)9M`JCie96!*enx*I9qEF$NhAqQJ#)0`-c)LG~v%;h)V^zj?N*__E@g z_(m7y_0!1>x=mwt4;l@S1K@xW9-Jz9{p_TM>S^7m1c8P zZipmmF_1nhQY8$v8HE3F3D_D*CK@xn-X}*a=f5$R`nso*)n1hA98ANm&Wa!?^?io_3;ZJF3G5rA5m|&+t z^nlxYQlZd)Nb?H{0HqcdcSfJ>-ms8s`2tag+~y*Q)_J$9UOaOUS-6$m8UCWcbGeC7 z*xAbcilmlyXQ7eU(`0TYZ5rMTVo6lS`sNYD8Gil+vQw{wz%2?7x#{!gBVT|(EH8cC zG&cnPD%;eP1>GW*DsYon&;ThieK2j%gfhcy-4*cm%oz%WDLqjaj3K{daK`#fdCv}> zE61BHX^*25@ko%S9GVrc+IdU$+S3)ilDa)z-p>JX%+}>71>NBfP(S|*t;=IbRb++3 zuOPL}Ol}(E=BvE%^zNq*8rxGCyreM1B-RMS^%>zkH$7VBbrZw!0EzqD9?89m{0xr` z*@LXv)kXXq<}zWvYLK7bWl@*_6ATp(V@(L|_z9C912=l zIBvLas!@|^9-Yqq*gB-CyoM3~K9N_x_^}lmrN1xIdI_n?u!h1v`UiDjMX?FdfrtwnZU@}lVgsZH zpR(~}8J`316a?d1X=V~xs^POEs2ad}=AsT@4{7+u(3B+Z8a7;5u9;pKI z-j5Y$tN~?qtevH|@*H>?{D3pQ_IflA&!I8cPQ$b=!^`0JeE4Vimn&~hPEu3YlG*9) z#Nv(g;ojf)qnOnLfctgNn-JFnJOT%~9-Y9AO23wUB=7s#mj9{3By>0|zA`e1jRCW8 zsO8NR_UK;4pziCSDy^~{<^s-S783d4wn*Bjb%FuXyoXLI-9Asw*-IGutrI9@BRUIi zh7OrRt6<*Vsz^Mau#Sx1%ypM`BGSg}g_keW{s*pEPxQMMO{nV!o!YCE!OT04vT7Xt zRSxr2H`($=kmP^vLp$ppCi}b`XJ2rX<3FMo<|Gr?sHSn`M zG%eGcLhTULSxHYoDkNfgU-UWZlPA_^ho9gbzFKZ~GvbiI@&c>@d8#I(v0z+yzqibE z4~H8O9&F+pg|q$DIH@l1hS5%*&ArH?&dCWS;IsKs%iqHuQhK1;2RzkPiSH>4I#~Sd zRFQ_|`q_G^Rqs(UGSkZ(z{hz^%E-oZZ0tVot>uTZX%ukB)ZFVvU{ zj-oGsQEdn$sE{Y72m$hE_uON+H%73|TXoi$%omcXVV8E#7wmfRxYv)IvHDFiz>?0m z87US&bDHu6!kC>^dQrn^{=t*>4isujTgW%N^^A2Fj4m7)Wa^d4D#BJo0bOV*c!vhS z6_IpLSi1o}ppQ?lijgOg$#l!UsyWZo(+lqVbh)N@f;&6X#H3Ex+T;ex(`@6potufD zILN$x&#*mD!@gd-oiaQ&f4*d4WyIF|QBQPF2C!@lzPdOC+#}NPDEf?P!pm3Xg)9c<~WBir0d-ap$@d*?*s^isK3m6>s3OYF$**X4lNVi<$azVNJ8+r{fCL(Awz z^mWx(p&4Gy{!1j)a?zQB?$$BlT=X0Tk7^7&AIUx>((^;Q&=?@XV@PwiGNQH-uoiis z&MY!ir>f5<&KWPzK@SUP=1ZU0@+}f(jOpb@z<0=^4%g6l>C}6#J z***+7K6UAcbM5++4ls8zTYa|Xoe@HCF#xsJuiJH~>6K;2RPa-OpG<|mzOxCR9n8(D z92?tWhcnc!m#xz}tVr#T1pa4(m0%Q15hetK=PWCF{Bk(IT+6>j{pDX@gw}4vYTxjv z9UVKQVFn4`*S@%SG_m=>$(1hcv$gJO&s>BQg7aD=b(Y>%KHD0Z`q87V$~sx&uPHUJ z{y+x$q*GmCQ)1BGZ(r;B9Yyzso(VhAqWKJ8F8*p^Ox~mEb%tS>>)dHLTzMSe`r(BThE5`Zul9Rad4aMTK9S#?&3*wh_fzlblh50 zRN<4mA^UT9UM75JOknznp?+K%p|~KJFt#Y!$D^-*vKOJDsIMxF^NeGRC6Z$Ik-gqo zO(ua6?YZp?uHoRg083tL-%hVDNheb_f4EmGssO7!|6bw5iNx01oau36$;b*iH#`E2 zTF>DGEe3-OqKJ!4-;#Z$>=qBO$8sj(X2Up-U%e_;3BQOsJJe7le!RIU(8>JJYF^#7DmpsfRVYglh$k(wQON}$z5^xS&llU^hN^agWg zG**ZIwXBEon?50cF$<5iuHd2Xip`Z1I7;2p%`I9Ol0`zK#vEu*XH4kB?IW?*!Z96@ zknu;B=(y1jS<{-XD?RMX&o!~H^K#st^I4j|ElWg54+i0iV2YOnA5hqwDWNEOyO3(m z-1HVYh9hK}hvGRFU)%G}8t5t9O?O{cm3xIvR8rA$ZR<*$K(Xc9R9Bs4{3CmR8Sj(H|q zpA(eyw~Wl+6q|qTIR3}{+?u#V-fP5%C_ofsDn=k2tm)tW#D@IXj{+uIOc^dQD8<72 zgQxk$%-;d$+Pwpu>I0l5tW5isDA_-+t_IRLbTDjN8-$wtD1wfgjRXnAAAh~+6pbEt zkrP4t!Qn3JUjBNTojUMAYvv*k_gIreZ2z&$S!6#hKD+sM1gd-ide8nbj?EtdmnpoE z2L?PXug{8d0{=U(ijkv46wuP3uwqzKTK!Bqh*gR}S=qdl3%bXonZ>``=T{?R6uIi3 zCTAJbL%YxMEsG~6tB?(nQoSYd%mD4!yy z5eKePnBxPd^HwTg_$K)imPoYSA-rFyW|2g}(Hj-n7&EbK*j$d$t>p)KBmO7MvHC`K zP&-JQ*k{UojeOX=t7TU)V`G$Z)2yGc_2jXSDFIiJ?etiFbrl$j!CU4S>tlJkZzK=u zeux+lRlr_`;!UO`fhexl)n4z}K@Qj2fqU-?pDM!>U-nUA382Tj9ZdRDRjg>5p2U%m zwxUBN3O^2FUL7oTrc_=p{r*mh)A*vnqPa&Ho}u#|BO{zGKCvsN$|u~*hi&!X(H1cf zf|Z9NW;_2H6g(z2buul2!5ugA171SOXprmtopGe3V{+>kUnN{{aN*?I;sd<7 zPgo-_^%;V~?7CSvlwA!qF_ltlEf#@n4g{KfZINK2mHio|E)k$7-I;ihQ)>jpgF44e z4AT_Qthhc@Ld#B8+_tcONvPcf!p}Y;u3-T+(}hV^XYcQ1DYO9v_!xm(x6101C_iY~ z-`*@a0^Fwm=7$&7v|d9C!Iy!d$|rSi&RkUu+Ndm$+$7UxmUG5(fVg7ZRP)aE!c!0I zXJ*g%@B3U?lTC5juNt)fW8{6Gyo@b3M-C?oUcIpceemi?RQfCm_ zYBYnb1X*JVfm*4kdw<-?|Cp2f@A;xNkJZ)*Y`c&jWuxCx9hvy#uATS2eG#Jz0?|7!vk; zMD1o}bk?Ke*D?bXVMONn+qKfqfwE`U_wt*FDyc1DSrMWk+G;0%WL+^cOhCcnst>&v zwSHY1@}Tv`P_x{NX2Un0ipK9Y?(Svj!#1!`0a2xt8J(;!)83#S1@D=$xM<5caWJC1 z!kdgQvqGYqi#a|buR=MZ>+KItvTrS7rp^5Ba^|@fijO~=j_lG9+}FV;p#46B0CuB@ z#TAb6kU)JO#vJ6}@OY)v5DN4ba@nvH?rsJt03@*+KRQ3TSVnY&W-PKV4N}WHmY55< zlOqTnGcEmPZ-|3BFgA*SANerW%XPX}9pUj4hP@KX7t;a0GP6T5gp~k>pZ$GeOVfEl zWT8aH*C;7T-8&|}RfG;y#9yKWmI0HEEy*Sv1dM%)TISriKFNKM(LVbf*RS1my*eGj zf#DaYxIQxZMp&;u5uO0Xn#q7Qm>`iLmSkr`pXxCveG*?i_(LL{J)u}Hp4^UC$^huS ztKd+oD9FHbq@jvs&3E+A7YL(l67FwJK zarr7pI56p=hfO2;{Rx2tqokY&teAFA6RaIgA(jtx;ON%l+x;S&`r@z_p0})*iSdq-ZwHBoPDhiaFs? zVxlahhmXMWH46Zdbdu9zup$ziU!y*Pw!dhEYCY zP!5w;3bQfv2IqKo7U-hlU!B5=Fr^w!$gA3%9vuM8u@UE(cxM&BCqj0S^ z(gXP(9OTT#KhftuEpXXe|80-|&;He*Sb32RpP6jO3)Pry`eUlXdIIa=3~s~{(_pUk zKf*9ME2w>3m-C7>m$ULF4H4tcEBQkil!7%N(q_k4=S|?Qu-hDF>#q<@1h!dOC7^~# zW3m?>{W=1rVAoDZsRm@}tO%MUGY6?mDbY3_f1JYO4}W-_@iz=Z*)%rKT2{YaZb8uS z*X!%jz_cDAx7h^{E1AB|)kFg<1ztbKPW~MQ?Nc9{g>D|7Q&mOsYD|#tk?pZ=V&6u6 z7anOZ+Y}%50z!^@0`l-7lW@?tL!h-HlHAH4cdn%Wj!$E7?_!`gyFsQx)iDk=4sIua zI@BNw6T9*U-A&(>7C5&);ZmCkR|8PCf-6kkfUxr#G9EM{0XqI~ps*35-ggm4;iDXA+E63tk2!ZX>o&>>clCdf4Od)$oDH3Sn7 z5udkCE^pgZQ6|&@dc0BX1&SiCJi?J376}(3c{rNhvFhj2qX0RiJ5}@1^K3jPJ2kAh z<{K`N$yKQUh7NeMiytw!%mg^2u%nhI!!E2rsv<58s#q5Sb&t?&(T6xDS`%RsL zqSI2m1bT~e;IR1NR1(v}xj$idOs!V_B%@yN?W^SYev40t0sz%8nchWQpdSpgo5n`LnQ@g=59q&kQ(R6O&7W z9Qbn|feI1}xEj*eDC+cjL>90lL>ssv-+5#ds9zxmEw2ZTT@=bD(f5^6(@iRGHIXjU zW|d0jY954zPC1jU^ak-LGzwsbntJsS^p9Il>hUr^^3XRg@-rs$l<3}hu87v$=h$P$ zcU1RFyG+X;SRHrvk#pfTm5?J6Zv{LVPwvXTUz>eMJS;5x>A>`j)oPQG-(PQJ{nb3| zdnWLUSACam?WyZRYOl({3%NS)JdI*&b$!1F7kj{N_IZO4F1On z{e5iy_e4?uv!5bqSN|4>1s}Wex&kgnGWC;K12<0%(KlZAh9(44@*9*0qHHyNZH%Mn zZSnwI&9|}#Sz_C%9olj1j}`L(?8&PL02qsQ*NwYZ{uEUBheZW5M^t?Z(!30|y|%kE zhMY1tX4{UUkF1(-0Gk_v7@b-7YTQh2Oh1f7u4%AFq#s>`z!{ z)GWs`$9PJCJrd8pe6=0l2Pz{lN2Lei%bQ@?SFVDEX!9xH`o6H;Ba#yf zG>w>(MQ`WIvDGq}$z0RBE*_zh`BCAZ7>^^A)5a3cv=cyAfUCTpLde{s?bInU=Q>bL z4S4u>)Djutv=Hbi#-9UY0>BdvaDhi*dZzb!cq@};i2omR?*a{F`@Rj2eIZKryHVPR zkW$&i*kr#aDzXU`2?;6UMxi2`B=VGzWK&5ykzzy|l_F$>P&R|Hiy6$Anddui)$@Da z?|s+$)_T|feZT)&&srXnnYr)lzOM5+&ht9XEPX`do*9cQ@kULnvNE z@Ik*fZFv41AnwLatE5kKi1Z!#4U3 zGdkL^=*M9II4Zc9FR$haoIYI>6t;tIHP+}aH~>eBxKBIiA;wTPdq><8qgU-i>0<9g zJdCh^MwE}^W(ZteOPMY&Vcobcl1E_QVcV!Sl!KGaoUBe{>o16)PG>UgxnhU7-jTrq zy`4~|A8QFcO3QeS$*S?=wAVWe+e$B_WZXKx<^@-s9-+l9zSSW4V3ba zr9zO-oTl>SVy+3{w&7YTYoi#ge{_L!gxFQI7Rq82OA7;1%FEwjc_)>~9ANJW?TGx- zXu)w3$p(+F4VbV`Q7qgcmZ6+oXDs#)zWe_lzxNS8gGzoMtV zd~T2#EyQPAABz?v9=-nsOJrU|BVekzK{k~63AYEqb>!-ME#m~SdU!&bsXEbGEz30? zR7~|Eg;-eu(OF8A=S{C3a!XgkeI@#SlbknOUr>6=(IDPbC|*@>M(QU4_&5*(e&(w_ za#qV!IXx9f<=X=*fK&cjg}brQdR^q^98vTHZRu5w;dBhX^G>L>+J&a#!^@v|OWbD_ zg~A-Iq>XY#q#)J^?0&a44{hpq-~VHWVoy602YS(J*Gb@}KB`$6xmCg=J_u3=GR3x8 zjU!HLBv~+ALE7vb>@|4=Jm31bZy8=d)AhU5WqVC9Xqd)Yg^?kVsG69+I);4D8>~2} zX9uXflQ~KvHD&oSGNwEaA@~@xwq)Gy9;1g9AO`r7SfhJ@yH5`m!JuWGy!R4BjJI*_ zLgV@caaR=P&O<0D<;_cWW8*`lrXhQxwa>1$*WC8xd_0Wq!wY@2gxk=O!a2I<4UHwd z=-^c?>8=wrDEFE|KY9!A{j8rsld6G%1jnF0dO@?Xb@CL14`%6s{e~mzgkhVa^EXza z|6}<&OiL?>H}Y66=UDOtqRdZSoi;al6P|pjXA#?by&@mo38q74&rkL~%txSPU}p;I ztA#c6;G;z+>PPK%;ihAfm`YFkUPs&K9T)!5GJw=4>(@=*ml@gY_!T?#oNu;;R?t#u z6D~lL^!4;?g(E~<@vylX2zj4Po`&JQFelMJThOd_iBAFR;V)>k!?b^hQ{>Fs7y=84 zl=!xoq*ybF3A7uimzm;>yZl}&MD(<^U&WrTK1FUEwA5&@gaC72~%oOY!uJ-l}+ZINE zokpqu{mQ1`+$73`kbdnV)9-1|-SVL6N9BRRvz4^NwWoZU-=5ZKp^fgHnW@QUqZ7Ih z>+h?a6tdmXm;O#ns)1+lc=pjf%F3*fpw|ZDc9!l&{WCVx!hZM5J&F1QnkaI2ymtnA1a=_M{z2)x0F4_1RI=zU1O zFdvQZN?#?U&hV+J*z@+_j}5C0-j}{@+on-B*3%kdl{GK1{Y3Jow55J@4rw3Qbz$xf z8UOhOZ4f(X`*Cc6ehyaMS}Vf%?oUqrsT%1>gJ$lR7#s^W@p)5-)Y*OOn^Ysf}e{`1l!QZ(nRb+kA zM{f&{OE*txkDBQ2e)JGlwNO-W98Dl9jeoSQQN~cXt4(RWm(^DBp`N|XrymY(H`*j< zIwHdP^+fKu@+P&^r;{28Y{kGpLm%V$|B~O53QISgzBwp0kV9toQG;15jV$2EdKPx}zsYeY% zTKm9@^t^MPeR?4aZpz_sd3fBdQk;I^T}V#*(Rbn$%qU3mgqMcn!vyV~c~b zEY&NE?lb1Z+G+=FnmzlV>R64`<2PKbc8R$^EzpSAJxctcc0-YL-syu{e>OdV6!JmY z{N&x*m$uus2|J|BYE4u6@G9(FF%tfVjc;XcMZ=J0BGN&9T{_h!(T2(4H;gzdvEd_WT9KY4hbfu@`P_Y2$2M=U}g zWmZZxDLxD#jUGRAC}Lc5%4&HQZnqHM*h}Wp8nxRDlhl9L1bBJHkoXqTShM}#ohOEe z7m{zBP3j(CL!GPEjj1$$YIdpN|I#Z%+3BI`+kX)RML7;W9B@%SFl^y8TWNnXD)LK- z#r?7J8$uzj0r~h7=a-0VdhpDhuOB{43!R~}Ue7n-ULn)hVHNA$d{sL`PQ&+N|BwFF zo6qmB#@i2ZoliHLD-8+hy}MEM(iXHvwPGl1J>~^ihhg#}=Zgx4AKknbv2Mxt_cPo7 zG&{S`ZqGUPz&|hjdW^)DDdFdaEI6G$SGnkbK8U3M;=lTC(#styIh4-#{+r!*GxR!S zf6i^~5MM4aiCyW%q#qa(5q|&8jIYA;X(q|;Rq7e~rT^>W`oDUTHnOEkTay%IW#gfJ zf`!iKEt>NimJ6tgSNC1y9E!E&<3{t_$N${; z()r2s<>;x(7L7s|*MIe2Iaep-DEVAh5YDR3jO$KXxiMOE4y#jB(ec#&SH;=o*SdWN zbGFvv?Aqp64U;GThb#KO`^vjJ8AsfkPVGp&a7v%xdOi2FkL}>HSS>oC-_Dv&3}W(f zsEl@pQ(ZP)$^Trcm0-4TD%!}kS>iNlS;LH4be~d96F=7>|!xb*?FAvT&>9tw`Xx*5P>@qb`)yDcbdeui=9sQ|RVu$*_L$Z{9vWLWwMotA5YQ`Pi_#B- zDlA!hLf}T9xAuS4Z|hvne2b4i6?xKc_;6TgpW5>sqis!i%88=*dHolx_Q}lR!=kCg z68c%9gW|EAX2VmaC+oBTISN93LG@j9t*_SRBEGqMtyZlb=QrO3c1$4+x$Oq3Jc#Fr z849qJw=VIJsCYUb9$N||8G+m9Mp<^lCOPhWx6l{hTjj%Iif4=8|BWexvK!umiFF28Jnz_GEhUYZmb9;DsHXblKv5G(0y z_o^b*DD^L^`f9X^DCynun-SZao;*#5tW2WW69H>L$zU{@{8{X^Y7jmR|27%(GBLy? zA*3fe^+iF;kjmu;HK5}C^X}nq2PwzMEO3@wKQIJ*A(k1)B&$}^SO=n4Gtm5+dxOxk ziMs7dPsLhah{jW@UdTaZ7uwe8v3s_F8PuOA}E@e-`^N)AaSywdB5mtzek5o zvT*#yvV7%w24l3ro{pbm#)ktZ7p{UZ2%N`frrKb3pJK2RZ{-MNSk_mI$Mrg-(jhM< zf!A)3JpRK?A#HY5zB`i`TLc>E-s2~eb=Ejxkd1UD;SqIh+3Tp zN19zjYA?bdU=PLWpzi}k4o*H2bBVo&HoEPsf=J5g{Qcs~)t)=d1)}ZO>HeOd`71|% zos&fl_K#7RkJHLYcj1@{$%BXHw|qv$XDxq*ximkBO^u4gtgQZ@3MK!&YBw55m7Xod z!Nh**D2Ldua}Kybjy0Ib4BA*rx!&19C|$wGphaO|WeojH`+z0i)m*=Rn_qODCE8%| z>)(8Y^l#zd^n!&DD=;R@b*c+otSz_o-|Y3Fv-G0cdwDxhUJGX&50KD7@4-MYh}|_k zokmOvCl|NHD&}(+*$q=z>n?y0wf`ku!J^OJ`(hn2`7Y9CbhJKLrfG#%e;mvVje84K z*Ik156A}@8d+{PoyWpGgT@Zj$ghCR2R*8>w;II_-ed(G?T1i7k`>3Nx@*(eiD=azK z1x^ZwTMh&H4iq%*Z9%mQ>G7=Zi>>qQXHu$AGL-zfKpO)JWAWi$TET1Y&7+|$bd+0b z6E??dXxmR>^019W?xrY7jO@Ch3U43S40Y6t#|97ng1K&T6#2b)0pM_(!XN`|~1&=YI+`A>M zq}yjT+{oObBk81%ziuWYTqI8T;yI!|zQgf|N(|3sla(!qQ(EzH&9TLmw_nN5O?SjC zE`<@PqN_ZSrpt!2kM-C$7v=|h_~BKsx%ueJ5FF@0x?Y+qXiFLFws z0lJDmThTo+By(}Vp5ZrH?6N;NkU`d^hb$v4jD>;e7U%r|t$93(O}=v0+2*H811R&y26QpFB2h{0)>Z zg>4o?BQ_F~uF70mx7#Iqt?|xRTMG}af05evrNcteO!>8l`S|OV+k^Ncf;1It!TkJp zh!LOEA$&&4te?}fD;mDxiQzWtfkdUNJBTk}@#3K6#WQ6H(DHxDv zqv)WvHX%JDel8|xG;~~GnWMI?na=HtwbnNR=e7rU|Lc^@p(ENv_$Z&@p|`iuq31~0 z#+o3Y?l&M2w`OsF0W-z*3xiO-u)fj049da#*{>Qz`Cnh=thZO;0eY7bmt(_}1$&0= z{9C%MH0FsWyvzx#KE|`ZG05MTBRfI6?e;C3?9wbZsozf*{XtzCL#=2vEGAfzos=&z z#|#e@8!YcQp|i+?OcqoTTd#zhefIz>+q~&7DMkO3>v=H8yO4VbY~>&`ef*Eiw8t-< zx)#FHV~`g_(#!mV*rv{CgOKs|=R4q<1b7r4Rpp;%R|wjRONa`+Nrw~kWOnst_66l5 zPr=Z(?F&?{GhQAVdA&RmEqTS`0e4TNT=@6dV&@Z36-WAmhbpevB@ZR1_HX~T+_Y#< z7{h)c%)7SbO)W@;*FX3-*&*raqe3>UOa6v<63cp}Cn;(4i z7>8@{Q#Qd^H`xU2I3Z$UV3->lg$YBtpceVi&ls+Vf~&+jOgDc#+O~ zC7fL?df$jMT^;DCRr&YBz1ea<4Ppcs9S+m&W7H{J3)x(c?_?D1Zb^k<3j_k@0352V ze;@tX(REZm*^@D`tvI-PlusBrggRvE`JbDdT}vr@P`&!S(0A(KSf;bgK}PaZMG&2W zxzv`UFz!F0&o-{nMbZE_ltxH|oF(h&mHMgb#3=BUKc+TvjOwH(aOMqfMA!JxrG+E_ zy6SV2#$7<`Bn?3uH;`hnzoh4xN-Uqc0TvsBHj8OZ?pB>jKED^kWrj zB=$p`qsgc+9bkZdhhR8nXSH;|NlEPiSfKieCE2}a#@HrS(#EAw;VMcOg7$~U&~xBW{2d*s`dQ$blrJidaiWkG2=c5d)L+aqr0e9Ve>hqEn3MATY5Fy$ zeCT&Lp(;x+lwc170M?fN>zF$7{3QEi$W81Az(sZ-3+BCXxlkk;KFPviiz$~e=|adl zyr)MbyN1B;ja{yaD#126NE! z)~Ei*In`(fpa?(C_4+k-BzZb{4D@$Da{i*RC~@v`NSnI~YO8h#g)Qs0rj?l}8v7d{ z8|`2cgmxIL2DnYfhq9D@bp%SrRKc;t$(R=aGr!m|=oeGkL7k8Az0NWt;SU-I3#T{u zH*4_0CCsQ+ZV-!GdCA%n86&gY<|NI==wN5dRF2cQhCdZwh{`|fJygmUe+_6>I;6cL zj*j4oeX+B(J>l$!d;6obKVlW0-&ujprWT)yqAaA0rD_k|4BaQw&*%!2$A?O0Z9Qzx zyHI4@8zhW76eCKN$489tYs>euBC+;vSNDN*LsHK&S6^BEQE)(p*1-HgjC}7rk&jw; z=TR7wc~O|uPX#g~ySn^3{w!|YHBI|{vDe-qYW4Q2d-b-&D{3CNt>ouBm=6-jj-0KW zYtUZpsxokP@;#wPkk@8zM;Po5=tmU<*6Nw|vF8Lx{EiDk{>1^971tK0xh;iSl=E;m zA6Pz(^+t%~tT5RO)4N?PvEx!&+BCM9CaOU^6$#t+Znip2SRB>$FP=_RCLrDY3b z{?YZ0-doGRdFHd7H2xC=FI4UF+B z-*ZJpNyNPUecR)6YnynSQaIPx@)(+;BDep-zaXm&qSby!L-SPHaTU+xjGE2J=B=9P z4LKcld$g|iNu1T+cV$X3Im%azOS|qh@0qe!KgR33$)}nYxAkV}CUtw$k2)*gmomR8 zxlrW%Na~b~W^S+Q=LIHo{OI^lMmBOn(sHx4vVV#)&bekfRb$bqx+|c)1WXAjxqp4@ z396@@VvvtB2GeE(c4d3O9ysDxcK^%E;8uIxg+__ddH3+C&11#LtatcetsVj7!b%>^ zuNCDmGIDWmxc5j)>#gZF+h`r?eK*LLAai@5#~v)3QT_2XAfo%IkxA*64pnF8wC>Ga zgutpBSJhRexI@g=M0je*VwxK`idNw$#$8*k{)sglLGAZh5{!-y!8bz2J$`A}kPhud z`mmk%bT7N@7!EWY7?0WXQ~#0eXpg){*CZV@&)vONr72lKA)))A zx*k$KC&nK9T%W+^w4QK zi0Bvs;@bz+rC)|IVQlrxO>XC!bGu^ygZ)Iqu@1&x<68G?{8HRG{E_|KlQ9Y~cg@3# zsIIZ8UBq}(X)L-0XdF-yP-x_=9N(l=bt?BX_LSX1((HrdK{cxs%1*J49)Q0Q4Thju z41|WIEdW$mg5xJ@tnYQae{KB_HkZdoDwt%0D^tZ_J=24YDel9U~w5v!hptApO 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кZj=wmatsYxv+wThB9(5+-%u$t5bj<+^1f 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

  • e02lSn4k&ebvK`TX{*Zp3aPu7UloRK#QG^0a`c&(1&^|12lQdK$JM+muOV7RlQLu6d9$`}v zK~wrre?o#H8wN70M?Qf+#)nesCVysM4I@Nx#?RP~8Roja&*g0BBK-EY`(QBG^YN<6 zj_C&DJx#9N`SWZmec(g?8@?UFz7_D~mkN?2dVMa+i3zyNNi`%HF1x+HOe`yt4ZN{6 zZWkYGn9xORBaqn_(<*9>k%~~*fPpC~1)Z;WkU*Qku|mitacM)>Rc`@H6bufpD?Ox% zccKE6aXx-P{N}aKo(_OLJ>|DFJ<>aX+f*TtKAa}qX@$-BXG+LqJ8sa(z}k&NNGh~X zCP=+AoZ)Q(W@WqoK1r?SFVilR2cT>?ij7yX#JI;(4q*ywW4{YdK-i6FyQyF^#)I5n zFBIJvr5sK^vBw+4(IaQ#`q?7(0OMb{^M!+LqZo-eOLd_ckI!wrbbyw)So3+N^oAKj zjbso$C*DR+*H-~fcgBqS`Z@j=gjT*_d~nlnSmw5JTNmtpZGJ=bc3)rndQ*Eef1y1F z6^D=i2^*bm+0pUak83d6y|bq9Gc6o%6IwbeUn_33EKK+ff=t#t^i|sBlC!S@px~>7 z>BmIG03)ucGHLsM4RseF{!%dv_n$3g^5Jdp3*h5Jz@t|ad`2MB`K$X{H5#UWDx&EK z?=U-!s763LH}6$Q8I*dVuOFF+!oo|BhOJ$sXAIBa<%wSZxq_u=QQ7Zp#CC?NUlrI! z%|3n22obP2m~c99s)3ywT>fWh@z&^kYT7B{nXw|J`(@nXHg|Se)Ky3I^sP^eR|D=| z4ChONlVl3a_{o?-$y!aompaPYZ1ST*rA~FY{;RZsbFO4K?-+n|8(mMGPb~(E*5a{d zmkHWS5aim%W58Gyq;jl z1JvnJsMYELL-y_jCTyO06fV9ri72>zs_9%7C!XA23vv*WUKWwkXvq`tYUao8;M4v6 zw}fP}ZNh5lJMN@x^YH>j@z-v>!RAKIK|XljB21s{({SzVeX;g7@F~ppe*E5-%1cI@ zb1}7^Hc#S+su?s00he0(x6q~ezSQ^}&Bji7>jP3rEe^F?MZ0en`dt3S?{5(#Wyk8atO zBkd`1siAM|C~h=_X8fG?c3nQ~3ijk5uOW)*;dFs+jyrR=%a>VyELH})-c#62a*6_I zQpULOVB|*=F8Dw-{GHjAS!;hX) zOvyaC`M6_xpgP8{Ix<_L^*ZN87xd33n@x#-ptUVte{9Ii5^4I^Aje`*g@o@5GQq|A zfe{4na2M$0Mqy~7P~pyp{UYLQTX2vZf8+JZkh-@AG1w`ZJwL-9>*4I@fF58~R|D3M z$^|z>lab8CSutIsJC1z}Luw#4gpCT;Mq!e zh`hYs()fx|Ju&T-?9w@+Gz;SI#H_RDG=tk4)udV?e$qB>QUcOzReXcNMjmn3)9f4h zoW=K!F;I^c@PSA!U2d52WJ({oFl(bw;a!!w|?@b>?e=$9nf!M9L0$f~LAHVAW zz?-8IWI-FP&Z+P5=%e7`V_&$GY!tof*W`#%!QwCCryJfAZpc9*s&eEE1U8WJc8@tU z`A@`|o^*@EtFa6U5os}V_WS*?B_-5f&hG9w7TDPz;ywe`&@pF9*v-qzT6?U zPgl=DZoWnLG&0^F%c_0@*Vb5cQT#lHx2HKyBN4pb{@QiF&t1Y(M+mi< zBM2v7a{G}*gK$$ep~wgg+ce8P6&?IWZIV?+s1!Soc|o}2p@B%~oNff#*VTBb_|i+G z-J@R?JP;Qavi9hne~jW&zY3eEaffX-?5Q^u=1OUnliV*=cRbX$+lYq#&!dWIo91bx zq1;geZONJ$3n?se%A=#eB0g;u#{(udMFwWrH7ZodW_W+yZ7MSv`P6%p3`upB{0U_2 zR1sKv{;WA1=E%3;-eU_meMnK%6`o%9t6BLPmpU)Eb#8=c1KR)0soaR%rBQ6Q{l&3L zM%6OV{Jj)A00aMk8Aw_?N5yVlT_d%|9eO1LEvn^1i;BJQs|k*rTY5YS>#mq!%B>Ox zc}@khXET^mX+F{x(9H{ptLplv`YJouPsK%jozVoLE`Vll&@DpD(?IOvvZl9xdCFO) zO~cW&{t;QoH?j0hVBp4Di8pT#JfRN*9{Ubn&wvkP_jZDhJIhEi&pT{x%;SNuT@XCK z`dzyqUv&goA;p_aX&0f*leI z40dPFkBGrYmmq42Eeev{%qvh9hH*iyFQaeTEx;iC7I(pc#G{e&t<+6Pnp+2oJZ92c zlAGkpq@=8sB|HWABT1-c+y)gvC1Ru(GRqx#=J#^Aw_F>}G&C?Y~6$$mabP=U#1~xUPYub`xJgc^H-gWd`uA~=X-EZVctgo{I;NVtt z21ktJafULWnrbCHYVE>7(*&fstQ;SW0>jfN%9E${D6UE?9T=ql0AA0YY8l z^?I`XT|>hgtGb%cb23FePs{8!G1uF9=cJc-o?uwe8$d3Z=@{Q&Za#-QS78g`S--^F!THjPi2Zm=WeoGCDv8 zNU*UFhG8uA&`JDfb$RX z>1~zroFP-RN7Qv^oy8y*R0J|ED^B1#)-Q+Wtrpb}sl%QQ7e4JZu9N7dX4SFt3lUHC zpLfkSYEmVycAZ;$XuMfcBe$))YgAOof%o&jTp~xh`pRn?*Wr+<(UJ;!Zppu2NO|(- zb7LhH1dNM1@40F6ZruxMN;L0Pxhg4XQw<+G*mn028-*Z$-JDwP4TP=Up6UullUjS^ zrh`jncqK%fNrn?PHn8KtS0uj65KeTDhHSPF5jDdjQ5-@2Y?etav4(Y3y?6$6U#=6u z9z5E9#hAKlyna~LuyFk19JmKXzyJGO`092NuH+{|*1+8LSX_Yvi|~eM2f@zpbPnEx z0gI{z1pIvXL{y1pt$rS-)h~^ncP*5<2$S{#{rLw8#W)xR3X_?Q8y@A6fNn zcxG6&?<_M?b+}{uZy`AeRvi=1;Gw4dyh4V|u=0WUVy)M#{i2!QhT2O=0o*>p+nb)N zhB)UA7J&M1-DFNzW48aAN0{z)2T9|~dyE1!|AvbWcdwBN94YE^7bSS0sb4C(3pku; zHokUyz9~i!L$AenJ8u|GUr)|gNaVdKWQ<5gY@|H@eM5l9h9hd( z74h)H4OyS!(!1z=0ppy{^6LO98^#`~=*aXvHIu6+)!OdSX)c=rgoq>nSg(N1TWwr2 zmaxV~-UxgUwt3q7yW$|>e<7UWk#5iV`WO1yfxTbrjTYB!bAT>jb%Gz?f;9R(@-#Kj zpv*pwVPQLJY8yE@!TqaCKz3!&Ewx~n-?{&(IR~WxS$-63xoYXdr+*(Q8YUk~_po+B zc-rM9Wvb_|qln7Fxh(96_FQ7imL?ymdigNbAH7Uity;jwcI^CSw2Z4qodT=CY9hF! zeBMoF(R8;yQn45zf8lds%}7aFdkpGLZTx)!QrCl2Mg(snp_NstzI)I&4p7$v@5}3? z@}BGe!YVkr{yfACPR@Uf=>MD0d3gA$Ld?y~7ya1swb%N^2uFgJr%+f~3OttE4|55d zdtHlB^fw$Yc2SP|M{`E3&37)smTm4^Fx7xq@DGbg#2fG2eEDUy9yz~cqx9IAwEhs% zgSE_W>SGS7!&CM}p4=58xrfSEelVx(;(Ev5eeLO6$0+qvTB! zO?d6{XZBI^zood2J6W@%ZVGg1dvngO!6@w;>CmEXyXiumChQMV=66gEEf&=Lls zw2+~X))lRDhZ4Sc%HZN3(6Wghx5c|yw0?m`uYX%O5_{LjCX7g=oPJMBW&?a~+4ue^ zu?U>gbr;!nwe!JHY!;2LMg!e(nf+>7yqv(=(4(40&G@H_HDV{H@oot#PspkS$(_hn zp2bt{^Mf4O*k~2{x+9+MfSVHE2Xowo7?793(jW1jLcD)yA85Z9yYSA>Y`Cw4=Ku$D zA7K+VonFtzZvCPo$2%a>5!>LWrp54JI#D??t{cboug;j{&)?BrDq%V6opX`uRaG+1 zJva8=bjs|keeY?rFJk4TX?RcCsxIU7=6}h)U+WYg2gd7>f3A4vCE;|9=X#A7TEz69 zSfp{bXYrN)ywTqYLXFxfh$QV+j6lMUhykA%kH~&shdg&r0{=r6KJrlbKg5$F(cOFA zuVDI*&ExAFPgs@ReREo^cOHc*Izf1hc^-FR{rt79&Re=+&sfRLeYNnbMAN@ z#o@g8nV$RO1~13a`;UQE@VfMr(-S8Ar9YZtu|TFnsO-NYn2Oo)ZW!b^`}HLCDs-*o zb0>j5uj`i}F*>+(m=06ojf{Oc%m+Kk$<+s;Tbk9qGp?(Vaspk^a`q;a=(NZWFzk;w z<|soprXXH0)#y8z`nb6bpLN!I_GbDA1~n3WDoTlhiP(I8CE`P5XDzFjsAe6k#hSYB(1hR6N?Hsgg^XDavA2EDoPr zM)A&KG+Ekr)c2Eu+}%a{?74~=D9W!H}NefD`1B!Xo{veRGx=i^q)x%Azh6eRBYL$NbR4af;U`uJuwMv1SGRHBPH z{D2O%wN7V|5r!lKTbiMSo0g$?JcAJ;*4b1VlL_bia*}^9XgD z;a2qD2R@3k%}N_5c@+m`9%*7kD|tB%8I*k|`;7k)%?iP6yA@5U_EwIf878W#p-(;+ zej3U5_Z%7oxinJo_XkgG5P4-80 zJ}34^c`3(q$43XU6urm-Uf8G5VK-VJ?)@+MVhM#XkfO~#op1bwtXKXQZQXsY7 z81(N5zRB6WBcG+eHJB538G>D<#0Fvy-#NH-u?wz8`>?fwpu^(so_vfLj2D< z;zxj%^9D9zdxQ~x;&O~mnQn0>De})jpc9Vq0u-ZGQ0vaWuyO;~n;){FI|!d9RjAdc zx5}dTt77t`yn!$>4wAYDS%}qYyIZ>H+|pK%(upY8$tP&KDUIh6q-h%y0@QOXp+aU8 zbyO(m3%irk@MJU;{GIRgx{GfAj-W^8t6lXSp*}p*1Mky}y%PVFz(ST(AU4LVejN5T) z)3KY)EwS&dikXAVL)G%+zL6UK=RK82Qwm4rdC`wm1=89G>SIiET2mNa*+_&}?^(=2 zngCtmANn_w<9|;x^~D$j`VOA-qq+zMH7=XyzfZrUt&^-SP}*{fx+89=Xy7|RO_-zC zQkfQ?C)W6t%6~PaigZB}PEmAv*H=gHf#Wj~h_8b~euykw>!}q_pK`xl8;6&yXss+5 z;+(9G1XMbSJbwYpGq@Hk=gRn0Y10H-VCqgv8eu7)GQR#ejhx!O-XG*e$saIag*4y^ zCSBH3{Kr6lT0iyrs53JKmk-`vvt4w?1We;RR!`o>1#HeE_YBUbjisy^ucDY>P8#?N z5RM%kum1!(_=H0xR{R8M6*nCFB#7ag8JE*X!G}sZ6t)M>>z0|eAr8<%&8RPKE#^|x zGJmy|E%Gxqn>fyi1v-zH;msvx`T6a@=#K{L;bT^T(Y9bj+Ru$fuKv~T7|inE{5~fB zCk4|=KdU>g@Booqgb(pFI5lb|XoAYS1Sv&He#LOcPg1Y#tVHwToGSh@tnQ8VHwpUv z+n?+zX^I@5pOOWhGca10Cg^&?9f7xZ{sBbG$|hd=_gs7uEL)PFqrx&V0otg{4dUdd zWQv-=creg~h>t!0k$H(mNRD)-r+m&NB|bWc_d768Q=Tf#JZQ4JuBsz;`b-HCHW+tU zqX<2nzyBiWW~@>~+9;CT99$sZ^Qs?H|K-W)H{7QYn`W))=4#X=-yh5|{1CC)}G z<@9%s^l!KW+c7F zK{!DQNLc{dPwpBApshwywSx(Xvk*GJFwU)m4HyJBc+Cct9D7?fnZNWJE$mR0-1pj|hmXBxX4~@BBLJMlii8>ImYmYU)CAlv7?23MM2!pGrNqLK%)C zJ;=cYyiql3at_Y}%H53~(npSops+%yO{@jP_3F2xWVNYkHs(>MChL37pGia<-(`H` zNE`&`_eccZzRSJyFjoJk=9?#+yuKviIiq@SdGIcaX7Ea2mI_;0il3EANrA@2ZK4_s z0Y<1TZKCj(jzsq)aL1I{O71!`9XQ zD>`wd4JuFV8$9sP2YSnM)lXPnJfNx8a$PCZy&~5FI-+RpjSVOGH!h3hN}YlrF&TIx z`@cq#D9<(SeoT%U6HDuLD@rbhgoAcxOe+~%m8hC*KVcWqGb=Nhi*HalS39NPV5Rn_ zB{hEVBoRM=m%F~GjD)Bk4res`c)>c{DJ03$d*oUjnp{$Pq##XrUF1*5(ug7&q*5TX6VS4 zwf3Jdhb%u)?RFc`2^j!kr93)Oehi+n5pADodilZkpa9ydgWyyNi+mXE=coz&I+uvw zfnm=%)l4X^FMEEF))S;N+^HtKXmRRU8RO%Xuav`Q@nTgsgrxNvIB2b2v6Hwk#21xz z*fy`qJ3(H#Dg!{~Qj8~y-qVZN^)fUJLZqR7MXnE~lG>$00s|un8LFU^85`je3X&sO zy*!Tsx^qKcqfMen4b6$GKma_uC0wlF^`3r&{|Q-u?e}o(5$efVs7a=YVWWD5w|aKS3n{$Kj+xxHAR{QFuu=P7jHHc(@jH zU@-BBi=;ArMOx_I2w^cze1@3eJv8KoOhr~3QikOIo3;HG8I>dXwdikN?&>3;gk5Ea zUdWX>J~2c^$)>C6-8}Q;LQQ9`_$yvb6Nuei z6{z6Ldpd9T6BuDkJ4PpXE!3ja;nM|DM7e;FS9!WBD@VF+-OAgbvlP>t%R`Ol@h z`C`H>qPwyd|9T;{un*ZS@YEg0QPDuHy)=K+?f9;`#$L5yjg6{nf$d}9gU=7fk}ZV5 zqISFvR$I@F<4j{o17M;C3mTX#K_%VXmQHP zAODoZdnkKX+!663ND$?}`Hk{yIz$coe&rhcE!cGjZ!_CNi25*k+@45?$NLqaHhkd( z90tr9{HhaDOmQl+gZQs9A9<`ld1ML&zd~jm$Bpz<{sHp~Wt~iqZ?;``_x7KGcDZ?e zio0485W_DE3*Mf@v!}GP z65ls(aL~Z4l?z!BS=fL{aRkg-F)=RYr&i)}2*x>L ztT}=iK++lF_z5-XtAN$x_I}2P_>VeevoQnyU!SmWL3ritX{~z+X6TU=fGq}Q_k;@l zOf!#OFW~}3AQHo@{geYfS9V!))#wjD#2?wlB9L|KFPLC5rr4k@*ehe6=**W9fPUzF zuas#ny@X0py@9gv=}*T0_C+2e-EWvt+- zfiX%$js9GgRc(2ej zrq^Ca6r}wxUo_Y@_7lBGo9|!GKR}NI7!^Ig>)#YM6-1WoL_e%F zseQtPK6rk@q|86D7n9-r&uSW->kKxMJ|z1eu=}!qDKN=I?qd3xH6eTin`+pjX6?{w zAMrc*@X~Inl2367P4-$(3M51^OkK`qXVS=B0NnrbJg1VHF*{ps1anH$t}A*zra;fbE}x{iG>C zOSX=4)M_ri^n&w=;yhs?kxWK72zu1TeV{5Iy-#ayRd!S;hb|ffvD8*gp&20$fdHjV zj9m`K6c(?Y#9_gurt9wPh~!kv9MJqBXyxJvE%N+CtdwcJ{J`l`?8_j2Ht9Zj|Bmo| zjJI|_DE{idwU|H5##E8Ple|4zi(>~p<^OG=^yccJjGCgZ>goD1*>kX0* zU4ovyapzOo*_PAr@58x@N76g~73k@dz-1Oc!#dQgY6>Z30yK4cw8L2cVtqb+zN!zR zcQI=cZGo(gBSnmpYHUf@6*Bg0Gyo-_+LvOF=a6ZKefWcOc`6bK^H<37%qd^wi!DN_TYv#c;G>KOyzy;c z)-A6Pb&)U!{MSzy4#(kvHQ0KoZE85zo%aHg6Z?7`s1+;^vaSexatr6e=YrI64DW}1jioiJKZW_BvyIlNIt)s0 zjNz?coBfeoLfFeXe?AiaOcnW5&xO|hZ1Su}(%y|m*2UudKStr1_&-AQW2qI1TVK{Q zf5)8KK2q@y6ib2f<}@KyCA2jtj+y3${G>|VMJb^lw#7&-yB0#$*gA~iX3)4ss;kYO zB4N+>;?A-O)u76_p!Z$b|LxOLpVA=F?hfv;Y4(^!EVb0~@FLaMFmFc!pbo(pN!u}f zm4x(0jf!tPtgG3$rsn`bU#A}^qTxT#5o!aS!NgqLwW;4Y7TBrf%lMP)_+FZZN@D(t z$@O!Mp6Zw{e%a0lFdFzqsB7(S0gpau6H$k@q|+f4*KIz-{MUMSExE|hx$W$zh$Vi* z@QmgKwzGex9V4YK;^jd@HYz2HJ|BSo%jb*lpk9EHT!-TF*FI(tt|m4zHMQ4V&;%ZZ zI4DOChpZSKU$hmjE4HXSs5WN7Y>WUI&-SzZz8v=MFk^9*>m||FRNaR$BQ?v8Os0%#Y(LuglmqW5S{P1;o3O8KmK8wN2c{a3xqfu{U}T(ezP zy@z?Yp*J)H2Jys(d8d{HxcN^>Pr5t$WYz#cnpW;i0t5p)PPZRQs0qu>K;-$P!Ujg2 zdlgg<%b_~n23pHeM;-u(8XPH2emANO#|G%B@+Gjzk64mY=Doh4n%bT9xmEzwu@M`%BeOzYJBAE_uQ(_|1UamD+h-LtB$RPZRqMv|?b)1kp1<9zwd3 zYK7rqVKVVC6emVejL&yL$#WL-<;G8xU!Q%(0n8*|{S!44d{^~8INyRjYh|^b?uYaH zYxc}sZ9#^GR6RM)*pvBO9)9;DDjAF1oscIQ>WN~2o4Xiz_^|%3%?e~WAo8#04PI)Q zLzvjROzC1d73|{)yiQ$$11YWwr+q3?FigA{o!#foo3AZdHF8?FLcq5FQHZ^m7cXAC z$uJgA!y6yp&=r;5908m-cmY=htCaU&`-b^kUJ-KMSrZpzE!ivgArQq-J>Vx4+v-_! zL8u53w26Y>Az++CwM@s8`Z+-w@zcFzFBeSfK37FiV_il|g9t%VP`VA(AQgh!OdGdA z=?h9SZR#~$g09euVPnJ3rMjoxYB>}!^mkB;xob~4DY5!>mB8rZ=Kbx6plnrqqpc*q z@!5zFd|SOJJCm}iBPCMsVZ%3gjP*1 zvfZXKvUHM;pU~rwGJ*y8yYkcRTCmy1eM1fE`2P!a+?TxQ#Z*kE`s>RvxJ72 zl&XD6LkR0FJ<#(+z5|yiI!iY}p??o&jSmvz1N;(qXbfd`emN`c10i$^ED}`R5WteK z!jH*}Dv4SwYm&+Y``eQ|wwxgXPm*g44B#M(AUAZIy!rWaX~~>zC5BGEJgxh))EEdk zDi7dHSQc*n9p-I+ZOI{dPT4(R5Q**d-&B32m7BwWEd}Qt^Nl?t>KX#Jyq$#HBgHv! z#8?E+`-z+WssCgMGNtZ>HwM}SON~1KJFpM-DNDi%kx`FF(##jg_C|z7wEH<+C;bg? z`bV9>>HYK}@Jx1Nq^k;bRa!J$iHj_2QIq!q`qy2ne=YnYU%&~W;%+s#WZ`Y&k=t_4 zhiCpvxzK=YI>#U2u)UjI=O~%-{_{r2zROQQZCX`a+n(znbTFG^=S9BQulwG{ev~|m5Wap~!2+KGh=3PL?Wf%%k8hqV zS4x>%R^TX%){C_5IaO7uZyNAGx-}Au`mIj7IT)#aZI4JbpwPPfl{c0FLd7wKt7Qs9 zocm5qvrpM~7p+3fHVFV~mfSLr8EUh>TxlgES~$;1YNNQQkpD4zjWqrWdDU9r-DDhO z@9Iru_BqXC516Q?9YX)DiXb~?Pa9TAD}z_6&LC>R%@Mr$$~0=B3az6;TJ8CvVtIXiHfp>%fJ#Km#-ay zZmcLU67qW2(o^MFog^xO<_J&2qgcQR!~3k}&YmN89uiWtk4b@1k9LP^Vn>Qj4BrrP zYu_z8r*`sxD)KWiKKJoh?|?k))9z0MhLr;S24H|?fD}M|r1Z%Rpyl$wdA}1px3_%g zT>!R;gpHjC!G}k`X4K9OK3+85{-$i-cSlKNor4*T>_-Y!orah-=$-J7kourz%bSlpnypqdX`zWf{ciM3%%?^k#a=h94+;~deb!u5 z5qb&Jm;)OEq6)ibd;XQbJe$2|{9WT&d;k0RPUi5hBLJT9mB)9of}ZhnkI(&*9~Y`g z&S@9tT^0~{F_!fc03_{Jfk&XWDHx9_^djor_q|*R37K%JoefntC-GUtlq1mu&|RT>UD%e?3pi3$%L4`lcvDRRE&z@)S{z8K+6vpk5PSjE0tAZ- zn*c{Gw5Hq_KK|5mRKB+@t4~N+(N%Bp5F$wuiZB75ZdZq$X7`qbJAHo<^S0d9#cIdy zd0y%O0s`PlM4-r$0tJRVhiR!-)O+WDDlmtxxn6$LHM-Wz;domT1=#>DVT6K#w*Yau zte<}OQ-i8sa4ZVGcJ%QLURZSrDwNLU1(6SfLA~nO7N$xq0ZpbvA+k(Pl2L-@S3~;0mc1Aupc`191{vNn7vQ(`VMH_@y7>PYtr`KUXsZG zc>CB!gu>n;{kG?L`dA4jD0(~}AIgR~`f~qV$!~sS0;BU&yF?Q$RzQRh+wc1x17P)F zli1_#89g6_r=O=sB{fz$s2f4lTnhWs^*F)wH0faOcKj@EXBG_UZU=Mzccfz>Z~Uwi zFC=26I&+RggdR{IvdXf9Asj|IR&t4iYLg*{2pG{R$xImsspd6(kpS{oLM#=6GXHsq zhhv2}pMS~}fFBY0{A*5lBJ{$woLOC#^&*0996o41fl&*Xi17XWh5aY@@4t;_FZhff zc|7a)?;76;0q`tkGQoh>n`{KI zjexiSx4$=onPn-uyqsNw7Z$d}$AA;z3z1k0EXNy5&uy{|+H+&=J3jsXnE?H5L*aoq zV7XQ{+Ey%dD$oGX;94RfVg;C}Agr`F+W6Qdc!&WMFqZZo;LgHq%jgY+Yay^7%uL0r4InQIvq}Dw4OC z6Zn%0aV6OTw#4){Tq62yIX@xW3?V7J0U~!>{i9Gove7&6c8+WwBT_(^-X3);CQ^kT zgXO&edBFXM>c-F(gV+If6bB!!@JQIV+X&iM4g>XR0xfy`X<^rW9+l(ci-=(S{p+Kb z`r)EsV)s6z%?jO~_HAV^ynd$8r7tt|ZAaez`^=pR`dKMaqCV*B~AJT>xw{BE7 z1l^eT6HTu_z$|sGFo{wA{EF=g{tPP=y5E`;e+;Pu zlYb`!z%zdC@q7w>-SO?`Gw&eW&GWVMz6Rt)`MbFXpxR=oQmS8wuTdd-TM|pu1?G@U zlDoj=jq)e%#oZ7A0-vx~Gu2>t(32Xu{rl@p5TxMdZ4?LV`xn8^BBRS?(#HxefW@ zxmXSi(*!^vb_~w6N7cJYbx0@$QY|YQb|DQBstisC$InifVCcfD2EA7D8x8am$msWl zJ1D$-&Acm@Ki?z-8(*~ZTcvyiGYsQuHky*#m%xrl3AYGjND+Q`?|r=!d^e?YLff|B z@IumE0P4(Vc`Xl1mAwThd3;QG@XSA>)(FW{C9=Vcg?O&YB0PbF0`;YcOs}~Lft4^w z#AjSbfha1RDI&TtmLq3PQn_i2r1Bx|ycVG2txgL>AE!wL225LZpbw(~Hf>4KYdHl5 zCy+3oQAb8bgL2u)Vy|EnUbbDJiBX?Ie_map1E8!j=d%Jw8KBcOCB4-7;`R^>2~=W< zv)vvd34n)48hw@}A0X@J+{Q2|lMkui`24TW^ZyUy*^xct8P9kKfFE%@Pw!`ZgYoan zDwWE1A7grNqiXARJFlYp#0vzf&0BMDef|b{P}?kyJ^O%?`f2a0YZ}Em>Cq}s3J|RT z7jF_lOQ*{fCj%#Ml@OL<0+v4?cLq?j2RgQZHw1cDHojp97937!KWe-YuEY-0;v&~6WYLAmi_|e9hJcrl~bWY<7(ZFWW{PxIsCGls2UIe=|7rfQ`VblwBa=)&96bj?_oF&p=Wlit{%rifK6$`n(pGp$a zN(F=RicNqfQt$#WY7Yo06~rz0o|pn(bRear{uDr0mxrbEV%C%^wTNZn%KPO>w+7>! z63=@f*8!@yN*=y|*+_qQ8dQo58o+Y)cFVijxuph!Hw3lj>Ge|`tu3sqza93TfKzHHFke^@U6)nwADZ*`8AHkLl%Ze z&l|G~GjFf`b~1i$aKZJS9EV|lUJuO>8U2SMgY5^OIp4*>zW`K=2oZT0Qfd;(;QLJk zLz{e2yGDIpR1t5Jv+>~%Voex-W~C#E)DP(*up`sA`sCfj%fvRD*aO+h#ul_Kf-Z`Q zjjMu7wV(Nn@n;S&UITenNL1 zJq~6bmG$?i%IJ+{l|gyHEP&(Fwh)$ARM*DA|t~TPyq&5ko;U! zgJ8ckFF8*La?a@+gx0r*pTZ^R6-xc+mk_@vK9e%qT8M1&~cD z?DiEDZ>$uVgBX!7Gr-H0C`!>Gm4U!O0`=+xM4l?Puh9Xbl>eS?^Ek&=fU^!(ZD%t8 zt5VT=`R59iz%E8a&NBx!P>aOO)hmEE-L`Q;_H@p~i#Q|zi@JWT@W5mBNM{HCjMNn- z85|GW0J7x*z7JsKN#^T>7*_6&h1XIw{RO{%3A|P=VwpIy zoY`E6es;O-B}@0qxm1_rP!L>UxwFQ(7AF+a>J|F_+705R>k0d?L2#CA8^08Kx31gh zJ_45SV&GLugRj>dZ}dRw5hF8oR~VaT7G1$N=rt(@D`e`d?LqfKQC|PWRFbn^MK&!i zRk-Q$RWMz-0ctUdYk9S~@`242?$kJ4t)$!rvP1Sl|7Y!6aq&oe{T z3lXEc%Or5?mD=h35IKeId8pg{Wll?ztg3KO(JqnFPd+pZUB2 zgqYlyjJ{t)sn@1|NzZf#rrf9$f%LQy6qQlO78b2U$S~iiK);dppm|pJXan6)_@?fu z`<~a<6;D60OjJnrpXatef1>UgARR74N=R+=rHvq@!LPpX8{>P}X*}Z@&-mU3|MQPL z;~CHROUGaQd2N{X@!zAX*B|gs#35RzY~8BN9+`h{N!l%~6gVT+EN{*u8P>*4Do97A zx#}6|{{cGo&nCRDa+Fb1w*ip7{Xkwb2bPv*+CUkpV&J~?_DJs;C$j4RBpb(R3#h<8 zqH3cl$va!%8J!FP%P((?Z~7Lpb9g@3+BsuO{9 z2QM;&nZ5k{%mNro`6GO;bG_z36yFEsd&VSBq}{@cUIfR(ABnVHr?ETs?cckhR(SN+O)>z3?PCLQs`Bxuvqe2tbEJ$ow5agY2 zw1ZV9$^?$idxwa*YK2f=`>p4#z^Jd^>>Q@?pVrBF{S(qCOM;5gM6Yp22gt5K5tP-g z>6<`2vUYcGm;_(0%@Pmj{N3nEM%Wy4o@CoonrY(6RJg6X<2>mW0DQ zKj-yC5Pl>Do}j|KfBRqJT^k!A72$;cahPF9Bi|R2^7sXFzuNQQPM3GJ20^~;>cy5kRJe?DULYvKjT}C&tjpm0%(bMmn4}2nBJHH-YB`$Y2SA|r1Zvwr44?;6|w-7Y#{Fs z--LGBv4|Qt_i*ukgNf{zQyS1iL|=}(%c;*E$ezl68%NYR&ZTY zAUy!?bQLgoQWoEcAcMfUyx*$)EBLQ{EC%>vf~wW#Pe4kcZ)#a6Z#!K1A3v+${_p~3 znyvjFwA=N`+8}V4;Jkh@;t~Kd&2oeCJU!DTkqz17NZvsJj3G^zCQ6J^Oji zFVYqYy~oZ6!iJR-2E8o;QIGt=>;iKxR!qq55uk3OY}{qx*qlu8*fKV-Lc=BViF##V z<(WT6LQcW+XiE!;W2qQ}_Og^;3Wu!YsP6q)HN?Mq@FE;{nGXlsPQdfI1w`@S-v^X^ zW6od(R`)&W;OUKM#Xp_jBz+Q;~X%-0p2LxlKWr(eB$Xbae7Qg7ueEe-4ZE?hkp z;G3;uaP9u2+K1F2p(+)XU_H2?8{7iMd4dNx+ApmR2?EgNN?DCV;_6nSB28z2?37!| zsR~RiHy22TfYw670~aHiUFWU?kl1$~@RV0;`yj`8@0ix;q?CE+)zra6@kU|Dq$&@u<) z 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%0A-=bkW_b! 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�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%0A}!;6d?h{c6KT; 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≷;A50J`;cf*TNqL2dC~c(Kpc? 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

    -q0M?p=*dZp^x2VDmyUvzim224J(6q^OvT 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ℑ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

    }-0kv~U%@7`nxRJbERu^CJbn1 z2LJRw{h$AL|J8r}-|YY0|Mq`V|5ZO)T0C2JrIT^F{*YMTh@D##6UJ~dnrb$Fww-Y=tkDom0reHPHq z#+2}dFF?YchNiK;3f#mVabz<=uwq)1d(-29Jdt`8Qx|UmtFD#GdI+A;#-+v2Y!z0W zwjpBB9|QiR-KiX!^qNl37Y|5)SVM;W?U7Y+mw`<0N34sikWSnBKvBF{9)p;J(+S_k z{q=>$K)p@;RpA!2>Q9K<(rqqRI5|3_pVVqj+aY>CTYvQ6`Tci%o)7=(k3aDFH23qt z^9+7IzvGYJe`2QHiw3tVu!>h*ubS$*FH&|}#2&kym7UsR{$*GG z^1uebPaM4)h2lnJ+1tiN@web{T$bF9B;;2ir57t{ZO4=Y$sd`#PATEXC68Lw-?9>9_O^dT~>iCVxA2y z^129(Oi9!-7!Yu;DCp=adM&r?*iYj0DtdYYtLz{@3&)u!K{MckZ>6)eH3`hD!eW=r zvz(2&m0-o*X1QvT^W);;JXQ(0Rn`QL<(q?5i_z?2RZu2^S)94k=URF^{Q;>|&uj>m z$x~(Rg|$wO)t-rasSZIe(YJw!jloKORk86pJ5+ce&3_In6?3O z)iThIBJV${KQ)n=7LZBzj*_+RZrnxu?2Y}$W)<-H`4hkIzrerv=l?uJisKZZqy>wl zu$flbxV~`zcA;uvt%a}aLfsecDskCBsS40;+Fcx&J$9s@ z;dqoQ1%d2LyWv{}ESK!90>B~2fuFOvSZ>`M;Yg#atPHfdn!xKaU_x4B5GCOPsEyf= z1ZFbV0+z6+?J!#wA~?UZah~Anv;{k-ea(eQMm zCyEKAr9~jcspX=5T8d5#9yQji5cFHaad*jnz*-*Z?6iWOI-rwPr+_1@0OO0_N}MTR z|J?jf{>gug|HuF9zrxqo*Z=9N!hW`aZ-B*d%My?J;8et&SDs40i73LP_ZwsUI^{x# zg_t?Rf?1aOon!@TEsz8^73S=blj4R9bc{~^Zf*c5=N$nyIOYRi#PA*gZu3nusmDTF#B^Noy{887IH>Wg@n=d1F#a*qh(JXAiR4x|a{ITFkoY{h>o zvlRteE!6;smgtLrbC6JO{;CPN5q0vPw<@OBGo(-fFcEAVpSF>6K3<@g$L{Xk%W5 zAqe*#4RdJIcRR|fB(J`2C+(@qW()&$)?-Up3y~1TNN+`jafpF9VmpauelJzoBX>CL zTOIIp0-B#;#Wdiof#RWNPCr&=-X?4v#%z=s&$I!^Bsh!iuXa4~x-m29>-U&=pZGw% zZ0M`%vH6&!!9V>^|H=RKU;LN<<)7De|IgOCyJyy2i#>xG$>Z1R`yOBOjtQ~)n)vLk ztBR`|S_LHxa>0e3ZON)?yAR^}v|Ij1_@vyzxcdEphiec&xC8ZeEX5t?Q1oK+}bHZ*8& z0G2BR+>@rjV05_8hVLnOV?3n-EHAJ`g-h4t=Z%l$~nQtXA8u9-7{ zmfJ2ayOse}_zl7pzX-d{-+1-|ZE>*Cd*d(v_yf;pM`Hg6KK;R8{^cL|{pTOp+scH! zw=rfF)_vMTtR%U=E)*C3T<95oT?NwjM)1A1g+F=J4<-@LIx1X?HrgXmx?*a$KshF_0_@!^E)X6M z32<6{kf3bBYAVe^O<-^d(X5>Mex7KLFJpkllZ^YfB=gsYl94OW}`K{Tw(M1r*}?Vz!Qj~+)cu8GzvO~P!&-@y z!XkiCH+ioM(zvOHLQf}l5$KNZ%P-^YPN?e8r_p_``wNYoq*I={SMI#6yJkO`Ryj6y zj1tx$pncCG6R1Dg#}r(JAtsX{ASzF!n(3y+?+Z`gYc;7qBaRP4qxp2*UW zJs2hZ|L|E)kb>X)kzu~@bu2s128}*z0 zGVFJO*R!VSF@c}`xDp4Gget3)IIem00r*_vn5f|@Y7yv0pTNR2~~FE zA8nJGEZls1#~^uFn1O}kfLnHlD}{;PCl8IaSA2!ebPOB8r7fjaRC5H%8I2^a%X0Ds zqDv{k$D<{(WsJnMnN)Hk6XLJRk-JltiJ+3;bb;=jk7~*<3RBm^RTo-=nc<2blt8ST zxwp={T&F2GpteW%VQG~($3~ z?H3hAbvV+P-^s?t8laa3TQxJf)&<7@MN5>3{m4{68moD3~F6F?}W6ie`NWQ+ZE8Es8!$k?kY@p2vxdK85p2b%*3W zqV$||LXlu{A*&(ndxSQT{#_&Uy6rxpBuGpys;X`3 zHwP@|o;eF|43@D-$a%!LJxj`GH{mtjJ=84vI7N& zDcIztMGO*L0P&hi+;Qyl3Q7KdI04OjLgNrZ!IC0upa|nOW{jJH^AudAT#qI#mdTaf zMhzrU^+KPJR8{%>6~-tyD9`q+qkP0DAb$D!w*l+F@%8uo@qgv(Zy^Bw?JxUpd(*>y ze7_Rk#p&MDBf}4iMY{tVDwP*TXg0^v{DU(d1B(+#Fs}rqN@x}0g$5pQUk?1U1nk0G zz?FrD6qF=O{nCGsEaWH!@PheC9vJ`$;<&CiN*9jN{sGpJ8zNGtw{NHdg8lYRZZdpn*w`bmZ3g-8N9DEzDAURI>X)v?WUR>553Q4d^xDlNK-CB5lHK2$bi zo(Kl$AMkGX&A*|p2k!=URLW8Tm6uJ5a=?rL}S z#!7qBmff+CPa@fPqevhS1c+>eu?RupfHTBzKp+k{$REf-4su2$j*vn?0udaDlXe>7 zO%p?cH`P_$?o@YGS66-Cx7PbU_nhP6;2QIOR@t;|x_ZO1+*P&K`#zidp7)$%T)Poy z>qIrPzY)&%>8qS79oXJ_e?Ea2baUm6ui=8t+Y1+j;QIjBhv;v$z3GsFpO=?+j}Kow z{?579pS|4OoJZ@x}H?NM6}znzN}z=*>^ zT@(^#JC=X}-@|EY!U}`|R;NmXzK_Yls)<6+JKmeWMHSHU{fr<_O=t?oZIG>NTa8?i zvaYNxi$TkGjiiTxik`%=Y5|ML8)3C^Bdg^?ZgFz+dt7C2uLIarYjI>kV_S>D65T31 z5FWr6yZHhz2u@rw>JF`96_F{dx#ga;8soTOD8LaI1Bf^v5$AdX1id|qI^RGz)NZZ9 z+v9=9`G)iD4Ikb=aIO>UEWFMSUbX!^9wWd^gpz{;_jifW-p@TB*NM+UBGDt8%=-9w z)SM?B5K4P6IXr61852&32Egf}kQFW(8??;fB5?KIvpjqm$b$(N`6`bu^C^&h6jwjj zEw@vmqZV6!=`c~v)so9V4nLo(b$LRomI2hN@?dy6b}=Grq3kI~&V!q^c32n@kyv%Qs7$XX zVi-%ELJTW$pe}&vXGs)Z-`=cJ+aApDIuis`1jGJnG%n0+@Aq8J=jbO??g!~$*hFw) zO}R<0eYCi$j+SZ;rpIh`okb>GuA3>2r7hX+{T#sdW7DJDwTr=M*{i52_1Hp2^5}^m zUBB*weF_-exFP^7LV?2rXOuU`#aB%e_2?aQBjiZ$&|-V9uDbnx0VSlEijHBSeQ z&dJ~Wjo-8?YxQJ_v_gR(omFrkD7?J9!!d3c!+-b5r|)p&&C1G5&Q> zVK;9MegV%*VA5rL6h#|E1dBcRe^(W?()~tt*w}Iw5X*JR zNv|)$@}4&d1BsDomN<#f^4Sg7AD!~vAoxV)@SOYUo0zq8U>fm`gQUZfi%VR=#o67l zr9cL|EwcBdrwU}NB)EK5GA%(W(C6!PQy~f|y4f>%qMAa6g`pDWA_6BHjl?XQ*&`-r zQ8p|!Fj%(M$qKQ}G65vkPLrme5bqr{gS@O1;ALNJ4lKwXe6TxF66#*6xRqo}h|EMr za5h8ZvaIXJ0$KDJOnU6Dl|Jox@99Lg-e#+G(Zwo{@Bha4zWucy`|)MvEgU=v5^ zJ!fYg?D8#k&))Y#7?rI|sH=|xd8PAv%2jpMwpGpEmmFx^%{f{u%d*9;0erS9S6UDU z$e!5K*ax|-3f>1~hRn@;3S0YsVI|#@wO0J$V56RHz;^>LUwJ3A^NB(Meez_s7sQ`U8fUn5{m)=(H%C`BYB|xCBW@(jY?dL!-87>W1HJN^`6gPXiG_6HH>kks2RDqK`zBJTPJ!R* z21Y?Ox+04%*f#9a_eYI<5kOxPr-gTLqO$Vd@|14@28GI%Ee3ltKv#+| z3SFasg*=Yi`tp~)^uPZ4Klu7z`1F%cKYZ`A&&J$RWNR$3&@#JS@WG&pt!)Lgl#_iW zliQ2lAuORDgBDPg)>6&dBQJ7iI7%sq?%=lKBP^jdGO;ZUWKp7XwaVgT5i*m*vX9ftSzcrbGy0%rC# zkm&|*EoVO<(#@onfrdqt&s7n5g!8bx35CZO`r6KNCFdw-zwd1v7$cD*kjQHi1sGZ?Qp7wbKD>RvhX!Ge%&!}+zuSL;T{J@5EcClmas6J;qakfk`vt@ z6RS=zfvE>-C62?u(wYEA(h!=xcJ8%0)Cw(z&7*?~oiMx^QAIP(AkI2HYHg%PW69Yo z25ke2%c2wzkzz?spVs9bMm3{cKugHIHms^}md5G=EYfUgTEmFxLG5AX!U82#S&^Xz z4kTi(QjA5O^rQv|TAgT|K_ysp-}20$KC{HCK=hz*0#GH!MvZsjQPWdUv6-m`yBl<^J=rBpvenw&PlF#L zyO66==CDutk-JM}arH>hz5b$wI)bf1vIn{iwKXS{ zgRxZtDrt&H@<8-CEXrdjAkQ$n6b?QVoPn|CazJJ8f9A!+wf4E@^Uou=ynR#^*$O`; z7?U2y5(!0_7$uSEfJoF*cK#|`(WYuCYxbscE_>hMt;X2SLJ*e01E}#)&IgHsqt8Kc zk9-?PTn#@Ntr`P*WJrU0=Cn}ilrXEyjtnwOOUvpn1hC41q-)`Eo*ndOl?n>2<}l-S z3@aQ^K#sd@cqynynua??4_fs|QOxrJ37F@^=U;pQ;=QWG)qrD!&+r@vj{8tDdAr|n zyQPlf&f7SENF0N94O)azcLmBj2CtK7f%YRC1f zB3*~6dp#}eZ*8))uDkBf@0@_e-9MV_Dp{?eor}<~5?kfDR}P<<16sC2_$&0;-l~En z+TH{{(Onm$*vgydYTU2=ga7mY`=1}S?SKB^KmA938?X3Ve7>up|LEV^rZfo`%p zL?WINc`ur7kXxRkFftmuZnAdulCU;sd^J!TF>Ejod(@w0@ovgI!mEn~Y~`vEeQhMD znHT#3pP#;9x#~s#_rsUbMGm%t!4IS767P76i!I&%tAPdo{~r*Z_UC24)s@oQEFiNb z0RgZ)0Q83Hm;cZwU;5;i{`{Z*GwYkb{LN4fJTF;m&-nBX>U1w^D|~}T>1NfO zk(;0q^f<}}g4ki6()3y}pMDD3Y@>-Is0YAuSu2sfoZ1FOX(aY>v# zJN)dhICe35#j9NFf_pW`KoEM&MQ|sk!oKt+04G$3i|&hA;hE&CfFnE(=gQ`S_l%5$RBahEq%t*y z2_AR<4nzn2(d&R!X0I}Z@W`)Y+`2%Tc$_ER-X1s~54?Z>1!g6@Y^1LK+c&Av^^PP7=P=$Fqn32*|@GuW&I`qBsh@w)A zymnqjdeqg@)wD%R={>5ChzsSnytxF0$kic^5kgJ)d8b)BY5+P>u*EZcZ_! zZUO_PB|%IkN@mc(!f_lRg!6PWh9tPCS(9KQSv`u$EH^*Upa1jWFw*6tB zYqnXrlJD3qO69OxO9op7^pmHZr`=>N?L*^qwJL^&I(CKoBDnkMp5K zG7g8G&YBz5hb0^P8FJyNa&+6iLsjbEZEK9d8l%^(%GtpGzJHfbnAdA!^y@RaiExmc zgY{}h=0(c{dU`=wGOT819Twc4*34$D;T(xtki5U4)N4=IdWz+cxot0q9Kr%hlTOi9 zH%N3%SOm*K3kIHmw)8P9>4ajZyjI%<}dyEKk`TZ=+Cn%m)5$*%*%UdV}8CyWl&T7yxJ0? z>+fr|iWl8S)HAqG%Q7|fv4++EQhpxo<}koiYXhBD7szoVAR7FV-&4I78dUXk3mCOC z>DB+)VC>qMl&Tr#2Bm1*)xrkzYwz!uEZrcvtsteR0-={0cDP?PX>*Y+{c)}JE8pau znBS_4zLX~Cun&N)*9sSDXd8Hg2jTbM3IOM0ZIWmQE4K=oP95PU0Xw}>P4@1lPu-e@ z+7?^7Ce@&o%-aIJ{~tRu%GC5Tp9`%l2sK#+LyZPFs0r`RAX| zNB>U#`JE2|{HGxo-4t(@-JZQC2;gRMpOw9l_TIVBp&0HUU5Yos=YqS8pfZ6@9rS11 zP*%1IS}mN7Z1sX))8LqkmMsZvdBpYaEwXDOoR+)w;b=dbuT2v~u#bC7@X-x@7n=R~ z4G8$)&b?|INlON{>ua5@-B}Ayq?&N;Q+9_ z#_65jl(JV@u}4`q&;!x_q0tGdXgNL2YIz>1UppE2%2$5mo8SD0zx>@V|LB)L8Q*?6 zwAS9vvDQ>X(C0?cbHpbi4j)=tUBtV&uQh4;tle=(*$ri_dT0)g2#cLr-el;Vd7j^85k5MLUSz+ggBB~<@^T_b2@9` z7@fw1;Hu2dhJ8 zYKKZ$0gLJM*nrFEO3t-#J{FQ>j099#v&a#MBb_o%%jn(2PA!oM6o#zw&q1g|=@e$w zN)>AOaEU8QP+4)8fXWjDioiOFJe;PInXL*EoTVl%6=KV$TkRwfy!pD197MQR^4293 zp^<~o>X1aIv;$oLg~6z)0xQ9AEQZhSiQrHG^f^!{iGubuf=ZaHv6`B!o)WN|a?s&~ zWH39HZGFMYLK$%M6`h#gGb%3CmUd-lGOitOkg2pH5PM>R;2vO7Xm@uLNpawlkvZGkmI!cSu@>wH*hkd3~?LST$h-0Cq$Bik{!=ap$pwrQV^U|#1e0{^`_`pJ-s2hu$f+lM{u#o~TL8H|vRzHY?q{5Sd!HBWIwv2W4 z22aHV0eM*GZfXeu!CEUIDk6;lmBfQYCFic$CZK5!Xp#=^4L90d-XY{E394y`pz-f{&I8DY92h;M)AJKy`UAN}gjQ$Vd+n-Q0RX{#9; zi`d)fJ}W@<`DRU)vA~w=@ATa8cN5)&MkE}JcRi!7OL2jA-Q4abP`jr@bb|^sSQ6Pm z>1As(3cK_#S~22Z^_suz$e2xL+FpYYY7vT^S=Gw1t{X2&f0rui@4A%`Pe7~Bz15QT zUiU7_+{s_PMeluA-QaO-`@XjNIa<9y(8hePTf-FI7h4Ik8~J_znu6>5Q2ux6Qea4% z;BCUApGkDT*)58d9<|SNwKw1G{B9?An5_S@YmIP#Vb=&ww?PYp)ac54s3#Id!8sKvU!XNXd@^CUBuy*@ZB7%2c#prDe3}Wx8ibJ1D9VDp>w; zMQo#`DD=h%o7u3l0i03LzE4!+1G4uWPsabbxZIE%(h6v7)fz95CHvu4!>-~0QH{dJ z7E5#!?S{$#s+)fF_t`UE-S4SWJM;4XqsPGn%+g&AIkzOH*)*XQjLm{IYG(w(!G2l< zMq34hOW9FfsPBZ+Az$#4Ed*?tj$+SiS4*B?(qRA_K?j7j*i$Damp%X_{~z<5e>OSdQF9e4GZM(4Rsk^>=uuT|EIMc7!UA%x$}w6z$&CkTYSRAl0byB! zN>{hL;>?fYFeky-*$R@1#Zcs+)&fwFXR9kb$Jz45AcW;$K)S&xh?vVE zOwlqbppo8cgNj)wZiS4ho3sGe!ef=KF+n_;vNn~PJx5tMpFLIuPMu5%(&E;>~J zQo-PK%&z^nVZ=OFUuUOLI6a;Q7m8{ocqtKFtBC3h(SBBuf!qCtV;s2M$7aiQo(|BP zj}zbf?E83qe9+tZ;QQ}?fw#BGRS(P#a=G6IB9e^2?cE)peDWePsor-2mSA6lekHB7 z7za^jA)IWj(xT1)$$h!~{6>LFR5-lKbLdAYSI89;ixjO-1`*A^S`h;}baF6buF@)b z6qcOJ!L5o~D;6C_s6J6^33&|Mn0V9#VqmZU7x(?#uSVmAaU_?Gv7F~=EbmCwTJ4r_ zUszSX@!pQ;sS?c+&n_I+#O=r`1*K`cGypOyxT2a74-VS{K!#2fhQ~5JtRnG+w5-p1 z9Vtg@LGAMO+C`JHK7e~)Yz08ALT0d*Df8Nah+7^U)Ok*iS*7<5*B;G@_7Ud>qEDmc z6yq2N)|{G{q=Yzzsur0BUf1$sD3(Wy_WmR;U2b!C6YTxho4YXmgC*F8s(5=4)J+^V)7l1uCRb;u+dOg;Z7-(E(5LfMqAqsX@-g5u8=pE&|Iw%tItzasY?x zJ?EHsOhz#-F*cU)c0Ta_i!UUQ3qCg@s2JqPfiV&xjKqiS; zj}w!t8Q&g7>#9A>@_Rq6C3Unu$izYtwOny}w4sv0)!AlTl!h-HBfwR1U+A#7!4v{q z=Y(LT-c(_U$};rh9u~IGB$WX`i?y~|6}ILGsB{e~Q^J_OODt@!GaKL$V-dtOfo3To zmX=t1aKbQaSrD>V)hZQxs~pe6z@ikA*?n&@^i-RL5y9%QZmtVmpQ)T$?}obBZx6Q!;CVT1@Ep-&ED>PHJg!k`kQ+Q@BhLco#z|pJqQg50N&q0G@I>S z#6~7uz=C$;OkJO6lUfG)+~~)$^0%_UGC+Xp=AS$9zCio(S{2}bpRKAx82Cch$40*l zeo~m zcM_i3xL#v@t*oRo@yoU`Y=EeGe=03x_YJih@y*WDYEV$_6}0aOx_$JXZFEr*;G0jC>c*Y$*t`A6!JIjxKn_ z9nIhrz2WT;4WNN#Ujw*D_7#Y|;G30)n;>&&E!*z`HTHLu18jnu{YSr#e?F=k5Nw}q zANGd0km2Hzvh*EXpt94pHxy+sf!qoW`-JR$m2(2zPV|P^O@DXdWeB%{2;cJnyt#Cf zj%{|>K#hntYWv z+iIGFaQZ(eIYerVB#U^Q59E;-P*qhxNlL$Wx-3U4;~0B)fk&xe+M2wo$eE~^pi&XZ z;eMw#)Z*hYaf~~?xjW)+C<6@CIt?G?;l^=4KcyBbxV5^0;24k=aTbuFkl2C2$OLAI zPTVT!VOdHC&bQ|_&;%n!>^<5CWAq)K@_|KMPC`~qLE?<+7C7{B4CXk%42&-16~sJG zefZ)F{`#+fp%0H&e)#+Y&-uVPCu#}H^c~0TP)2ebiQD*8$8n=2#btsSKBXj&DMW{N zO}JhX?30ZMj$s5teW)dW(;7Ap;~Ki*_Qp9Eg_Vi0w9qE ztrA8^DuvHw?|c!S?Y`g!%=QD|W!(5UPnD^RB7@S>^4#5+osbiIizL3StB(RSrw7*dyQ8td^8s zVUIp>Oh0+wjbzCnqoyzzJ<(-hk2#1)QH$#|gQwxJxKOlIe4!+*DrOEq3-p{jsM-&2 zG($lWakzl01*#jcK2Izv8nB_m=bddRFbnQ8v0zcL#N=p@*S_us10tbv5+e~hfN+F| zO?-ptF`ESmi%Y~Y684XKr`hBU5(*4rwv~dRMR{jmiv?luFtAZeT4ElFb1r4ri@i#= za`d?q9cG4rMxS*B(Y|(DD!Mu#7^+$1Vf&ivVp&;{(Hc85j|E{mIjz@q z9!Da_z$f>2$m38Zc|@S{1*AN}9fdjtT{otP@LYNTGECGUnS`im(7Y9oilXN15r)hC zVC_gck7P_yq9+O&cc2EzQnl)eV(mlS1;Sb|iRIbCG}m%?uO5w5ZN6nuwMhHHGGN7yIli-0q*&w|?!{ z^W7)+|LMzd!`T@Tq<05RgNWiYv~HGb))m#@imqCceI8k{RhYZJWtW%KuFKp+R$XWR zmUychUiJvYixuwLw03Vos~|#f_5pOg4|grSbT!dY@L9ob*!MbaMqE?RNeSI3`>VOn zVpGxvE_RsRelpc;xZ{`=T9 zOn2}N>3S_eo?a6|wyHu6AQ259z>7v#&)om{Tes1_Yk&Ap|B?USUQGYU-+cTvThQ^* zKNDAiCVU|qD(Z)Bqm#an(T%~r+0lqxS6%?ZO@Gg6jb@|G`1D47$?gkI6vmb|8PVaE zlDo;=sl;m83ioHEzfoLGZEr+mFGL||Pi)ZaKeZ8nzBcJE9>8W3dejinx;C`M9bWp) z_L<;kDgGJPj}Gi$}AzK|j3xKn4ZHaW&kV0VW6z*k_u} z1ZVs1&2Cuv(2~wnUNW1}K7DtF4wdP;$6j;bnkulp`-$-1HM1BkliYzW3H!{sQ8?0y zfRP}aJrEfeGfnK->d)MOB&`BLAPL-VFZfUX&fod*uYCDS-}@psp>GA6 zve9sq@yQ- z-ei}QYa#Oh1gy1eN)YJe^XNks0ELWU_NH4PLCQrg z>~wzZtfa0vLX%~KN2&Lt0o(pXhQJ(XV{)G<;Z?iLKt=?1;A_u#pw@B-ex#w~_NAj6 zt5%^}DA^rSHh3xt7%s*K27vA7_6D38nCA{ZY#H|UUXr%q_Jo_fB$-5}!_Ee77b{cC zuj7%lo^nAD!5x#dx&Wh_Ia;D0UA$wDJK0I(Ei`k%>bdpT_`Ym=*aVmoH7J!wVI2pm zs>EV2SWcs3N&PK0BVC|Js)?||hlf>8YxVg+qG~F7=vnpN6kR7!PTmG=lK@JF43=gI z2S^-4HJ3ryF0eC0tt=qJSp7v}(SK#jlq z+>a5eRT~(Tp{|7`E4*E98vrU@^J`$KaM?%fvctVS04;xZh}?$eXypw62Ga@;$cfaJ zIk-$|^*CTQ&Ev#kgD!3D-II;bd$VckeXO8s2$UdAAPz+DXbw^XMXx)F1(pS~-r*H$ z)dqXaW^2RSE+9>DuEH@4F}S|you_N5ITvySD&2GdR8oj?-D zal^ZJH{5UUFphzYG^Zgu5hORvLXUzg)smbp{gn(q6FCR0iaoeQZZs|SGt9hO*~b1GDkwQ(_LMb%96$)mp8W^Y^7v) z8UsCBuS(Qnm$?RSypQju*7m~)H{@%|gp6Dp_L^U6zbBgoS1Xaa@~!IBWbfro+@;kA zKF@;ZJdqCE!tC(Xt`l4ra4Ud>ft{}2H8}kR*Ao7~kN-ISum8c%KYskje)Rq$U;QdH zPwZs;+P-=D-a5Dqm~vwt)m8)X+M^(%dMd;o512)R3HuDL_Q>z&2s=+eTLfV67+ZF~ z|K1m%peAYBqCk)Mlp5iO_bsd0+~1%IlQK!x7jh9+81-}rpEPdT(L@d!T=WUnuP-;p zv)VvV!pA=TGDp~;Ks|F3WH6#SBSu>p+mko2gY{YwP*_*Peo6KTus`D-ZGKq~uJ70H zy?aXeTJK>F0)TGd(M>(jdmA@T?iEBo+Ak__C2dw24=m?)QvXXI2`QHCfUxA7Z}+t2d|=%1H>%FadW5u zoB{Zhz*x)e#a9s+1ZtUqZL;5}B;W>ogCu}ow*dR*1j<$d)qbPwd*^1OH31&&)gVm* z*yB!2u(74&1z~g{-i#VMKv1Jg??%zWGN-7p10rDHrxCv@tF4O8YG63D$jq3me#pW? z;!x)#q=T-w;JgSB=bZTIpZ=+D|Bb)-x4!dd|H7a9+PnKF>-F)D=%X~bx`caMje zq!~R2yw!5(B3LcMme1}0-xs!#}ewSiH*q?S(N6STpp2xLWz-_>-3}oP?oxu zhq{$W6$-H+WoZIuBJTG0nO*k2bW1vUej=GW55&HD#E@1sS)TI9w$Y7c2kH=Fkr6i% z%VVx1xEn!YfS3ln=t+2Sv>7J^O^-0-ZWfe%!fr+oDi(*+N5#liXcX$K#_|%CB5M~Y z0}9X6&hSljm}enHY^Qp4i<#XJ2MU3k7K)FDWr=W^3&Nm-q50n9mr!+@?+ zK1FJg3MrQ&j=(B0x|kUel0>nTw0yWkCx-VU8tmXRv!wQtc4H|fAhUF7>o!GQ*&_}P z)830cEug4zgeOy|z;HqWnY5>uU`3xzZZ1~|nV#lxWLUB#%g_|I@z^#4OTJTr40jF= z<3e&Vk{q-oaXBD44p7x%B{FbphQ-mNKtQ#q5DuyH(R`l8AuTyvf^-f``Em zt*n|sjNwG}K2tf%$oT|Ulp+S#>Jy5F-<$PeF+?_~SU?P)`ToqnGGOLTk!iIkwA18O zA-@&^Dm!=BXV?I3!Ap`wj9X%zr>BxcUIpatirDIqDEZ5k^>je6G({$N09cS*iz3$+ z96}4Fr29E{mp$8rP*Z_oQHsU^9bCIZ1A_r=VN*iB2BQ@+1ZFm>0Ai2Li`Ybj2!|gr z6bvC1EL8`P@&Z{B*3n_YN{u5SKs9B2Z3QDelW;3R3MkGBJFl$5$slSZZbKr5jh=_K z4XOpq!bD-NSA6gLpCgYZ{6}((f%|cfkN)fPq zD+sPt-P{<-6b-~+6@B-Dh0Yt;1WTan1YIPMM+si}E8%9(HCi+)WZRlF>~qAV8M;0m7)GT(e#FzfD_fs3Nh!@%l$5?;_dZ||L~Jf z{vcGR_ofD|+KzT96}Ae*tH`yfd$-+aKgob7*XA9oYHL!T#f$xnsY$#I1T^(~*_`{m zC4(8R(i<2-G?38u-`z)_i)fEJuOLFT6o11=!j!a<0oVAq$TB+PPXmY*nN0oBIQJTqM0tP!8)|s*R8Jc?9g7wSHDEaLl=3 zwYPn=kD+H@U=sk{WC_{5U2S{C>OGzY0@!uZt~DU*F_+ITz^mARjQTSKnn-p=n|TxW zgQZQf?K%gY#p9pHdPWFZ*(z+u7if#@}x{hM9L^LeqOHIfkn zklOnQR5)uHVX%RU%Z7kx^#PyXk({T(RZMJz3ZNap9Zx-#RbiwWX2q|<>bbwmkh7+~pfUc<) zXN2YYMtWQt#nD^E3FHA)pz6^Im2HKwSaVZpdj}Y;r15NSiANA>-i^NTA$GW+VK_2y zHuI5w0j#y;1aEW|pxzie0T1P-q5ItIJ-8^0ykX7<2oxDnDh%E*>y#wMh-R08k%4o0 zWT5~I(9BIMk3e9aofd89iPd^43{a$48W7G_z3cY!Ks^b;KuTx|)JO77KvKyJJ!vLP-0IGfH1Yn z6D}M;D3k>UkQPQKwyUWGVPTyHo<01eKl@qY0G#}7Dac}B$n@MLIh0TlIHIRzfEb4> zwm@j9-R~66IT5gBfojmCwGY)r=mwbgSt2$hPrYV4JRc6r|mIl->lF!j}GYv;G+J(z-&{you7uvNBTa=v&|(H zawNHcvkGYjVLuqAiO7qwy~S|2UZL|h{NbrY)#*LMO`S+FnJN_52HL9}{@Q2sTn>8_ z4PcMkfsqGZ-raCNZr~W8gyT3`_9Hyz8?cC36IIK34J-p@L^GzYpTg5|u4b%K9^cs0 zmZWXZ=rx<(pVz{UkRy(C_?%jN+$56c+xyv2wQAJ>t>c#q*f0bbh!CcntK?B=X!6Q+ zm1~8TSUD5MV8TY6n`sROrV83h``)J^dyJCOTs|qe$(z;B7Rt^40wO77va}FAvBu=t zu7;nrf26_qDg&(mxmMLr{>0bxjcp;q@UUK--&mfhf2@jvnLW{So^+ce^88K*?s* zw^AamNdz0<=t&I5COsiVfEbseSAAv(R!Cg0*QeW#d2;=JNvf_ox_W7E@PPaJU)4o} zF7;9S|NGJX;{pJFm*4%Pm*1$@Ms_ySv;PgSM*u#PW zjSiy~pAuq&9hRJ`n`~d3MvE@5lM8oiBzVc#MPZ0gg9qGPe&Q%%F^Zff9J*PDexUv~ia+YR6P*0Qn6Z@5@X9XeGOHGngT~4$05u~MyEt>DJQ`l_Go5%A&NLD43GZ9 zV@(|4>+M1i-2@2G>|nD8i0EQ_fo2=k!sQNM@{X(CsK=2Q;immI1~#j;s`&PJ;Pv%^ z&p-b@9&e{!AFq5o-cS$wE01)*RF1@L3@{Q2&$iWE{dmg7;3>pNk!EJ?Yj588N}lZy zv@XNfT+hH4qNhoCE!Ld=@2!Je=fW5cP%_?5lBQ;{7G+SbD|-?ug>S0?nzeyMT!=Jl z`SoFcYu*Q7YLRk!(*-W>>l)FiC+cmr!N|3G3?$uH*eX-~NiC^c>jcK(!346~unJXB zutH;m9SanffM{)=0d=9Ru^fyoT5VMVz$3689!*tO9tv8)Co+2MCje;m!D$9z`yAD3 zW7Qr2+awdp_iCrfw?`J}Nf@-cMq1tzmldj+gKNzOtO%`%)9Kj79*S3T@l&$Ap4b4S z-+L1QJJ$dOkW`Ln5s({>%s_H1(+d*s1u0vIgf4_ zOf>Yy&_HDSaC;jwSP7};tT(Wn2T{Ufof!5;knO!Ni`9>%ku`O)Id>z+TAn(&jR0C^ zy0+zyFze|Nw+0J6-h!pl$icZ*gH4?oE2}S#k&RKX8w0^>AV?0CTC*fcW+{GY4)xo#5U5jvNktj7UEU%lBl} z!dxW>QuhVXZUqU|)}qpZ#6bJTX*={XVjkHUFe=*uw^BsC-v*)S$|Kk+9$HZ=F6jh$ zw^B!QiA*xAJw+9k1p|OO43W{yISaw)dk^=o)!@o{)~)ezv&wGB0Z80L!D4|C(sXW* z<(-r|?SD_stk!ruGge$80+-}oC2?f-`f5-_0S4C}`09`5zxVI|weSC-pZS>|x!(@V zxr06gTV~WEWA!=VEEZSJwlFQ3(DPC^I8e0A-*E@4k0RT-JZm<*lKS5C{a)A- z{tZOa&r6T|^H{>Ca=>2uX1_N`0C}UXEzf^S^{-5ep8T~(E~*tJTM4`Yihy%wK5n$t z774Aoo*6(_{s_9kcCSR&n;;Y&23o*YumH{gLGe1TteP_oi#`+myqcM{J%L;%8y_xF7szHKG2&-$_zc+O>aogYmt=$JR`F>gK@ zFWS{b7B?FVY()ZF`d$EH1!}NSytkhF zp0_=^TPed13o$^_g>|+3r9C@l;f*pfhNV%vW=J;!mb&cVK=gc3HGg-Ab1|pA$=9COhx~NFmn=hWnRg71ARe-hdaq&ifs{;OxOw1Q4&Lemr}uo< z!5~i+MhA*btd?EXmgsq$^b(x3?SgVpI1BddF45y4jq+A4iA7Ca-o13ApfQp>4v!mr zJMnft@cCz->GRLt^X>h6e*Soa9;cMX5C*_;Kk)AMg7|cR{ocKbYb}LVX=xhvlMoGf zjTl%tO`KU)s0tEg8;Y>!gDya%+CLK6Kt;EpONB((x*0@dn#GlnT}2C0RKiV^tL+^X zrwtI5sh=KhLm*|=QnZG^8z5s~t&@nrag08XY>x@n)zFAg;PCW-0As3)_1>~#&v9~7 zf?8C2yaVm84;OD%IZv;Xk;p)#2p+D7*Xc28W(&QqWcd3r2R(kw<#GYoBU)9$xD7wI z+fL*?o2vxPg$GV+r-Nh(Zw6Ce8AL^{gj0ltz zfaKW9SZ2VFP-5`*?w!7r!;`2PZkA~q#&HbYKl#M}_5|v%R(bRkpd5o~P{`PBj;q*E zgo=SE2md+OAUeOfJi53SmXoU;8rl{L1@}2eX?c`oq{l*S&*aO?-D{%(uqA+6v`Wlg zPKPj+uUmEdL(fz=r`WUPsc@j=QU#X4L1r9X)lRev`J<{^r$-c**oEJ)rL}mu62+FE!zdr zkssO7h&2SAZO(E=i0V|IfpX3a(PQLPT4#Vw8C9#d2v`Ogjj|Z@t~oERjOG2IdNf`) ziB5m0aJjr~l2(s0Dx@_TdAL3;D-dZpJS+Cz;HyR7`K$F0kxQ$n;#a@&)%e!0{TklI z_#X$%++W0Fxii__gldC98*i{mW3{&3%E1fx=%(FIUH7nX#6{PiJG{ID;z&3TMYuxB z)pml7#Z~txhL$bm?|<|?l{*>Vf3_9a;C6SfZq^IF-qA{v-7Gg4iVhBP7+y2i>gIem zv{2W?>@fBH9Q30jxetQBulI#kh+#FWt=&#v?>%H?z%?nL&uMRiX2h&s@+1^z_0=_b zU|R}|Cp?>G({O#cYKI_}2QzfN+pR&{zBdu!|62`&JavJ-e!H1hcad8WpmI-yk9tSf z9emz%u(RKubrAaOXxm*A%NGXm(VyRSIN%3c@88XL`oTZDCI9$S^p|bqHa5Bk%kn|C zOsv`9{+%71!PqX|fM-Zrj=nd}gDLJxvx9*;!W;lC7w^X>X(N~=Z+$(& z-;WWOD!|^g{;t?+0srh~=~IA)-#f|cwQQO2=LWKK3H-glmJ-Ucb-@e-BmKF@X33m^ z&=<)pIPEu2>QYtQ#tq;4^oB#6s`ZvFkT?8tUQNXH&?9V5)1Uws5 zSsz(kBDUn#MYcDZfQQ|O_kOPe2T=JX{k=N<6l=DWskbGSG7pBad2Sg}#?gmI--FE{ zQ3?jm_OFl3YlCx&a{+U;w3C46*(ww*=Gd&=2~}W~nT9G$U!Cg!96YQ_I0g;}xTz$* zet3`XegAX3|NIMlc>RE?r8PaiCyoOn6Jw+Ul*ngc1{W0$P$|Xo5%jjCV~~+)hSw;o zrywltpm<2_zfvMNWj-6-*7)DzGTXF-vZiwh`hbpWM5bk$lO;_dY59yco$o|PMnogP zg(w47o)3@b{=oivT_gcQl>`(614@q?k{Jh~S)wSQ8Vo$r>~UnGYWB0}>LSAG16s2>62}-g z%lFTqVQ5v)t?#`j8a!~(^gN+TQq4tX7vp8Q>?$`JofrLFq%r^oqCNN>CL}Zf*Gz-k zj%G@%8k3+}^E!`hQ5s!ztuB@V*(v;Mza9Z-A|o{g9vNMPNDqm}&LOyDKY`-_v^+9V zYx=C4WxsvD^_da_3x%p_g>8n0f*de` zVC9;l??-l)z(f?mk-FuL(e@+vZnhC&_iJM~z_kjCU3tPO_CU`U2m^Ih`&@KLXHOEi z*5ru5JgcSsvI35@^u6b>uO*Dp`8=>MyHvQ1(QCbc)YX@*_Mdq`uIm?Q35%W0(+Fh= zk#gX}+SAfQ7@{Vg0lIr@>>ezJ44@Usu|w3{?AVGDSO%ON;iN)lI@q(vn1xSibXr}B zFqBVsC=AdlI-lmP*g~wHvQw@h=6V32j-yp4(8N>mO5|LfxD;MJP{eqY$rYHwt=6j_I)H=`{CJ$8tOJs>}d&&Zjh|$>zE_j z7hlh2p?^PURvK2qiZCFwVLYh#lRxzb*MIOI{Q{gCCw}BBKZ)y+njQ#rTZ4yXZiPsIc8RF;X zlDdg*X1f~k-P4%XM-3|0Rs=kMcV912!0De`O|))`egPgCs1A16 zn`A!&tr+mlL)(gUow>nQY#{u+s0ZO};8uWQK`Z>Zwa<6;a%^y>AB1QG!OOIX-Pl$D zU8)#|Ci8k0fA~K?JXr8M8UpxF{ygqdrH_BS7eN>L4T|?{<9@-?Rhr|v^#FFER(^=x zO!wRDho@1RE#cjHvgqb`!!P#t`!zjo(0`Xgqg)HYbQ6K<@TNWIIKUk!CN#R$Unz)H zU5EpXECDL}srNVuPycdSzGK?qV)J87FE_KkiE(xSNBfw%ndtN;RC}7k=`H9}!HNQl zm2p|+91{$|&1!XE9{aw@#w>4W4KNh^{Wo&bDt|w~P)kOQsCGiOuk~o;aRr!e1}xp_ z1C*AT7822ng1?Ig4n_fr!YX#5!bWe+Jaj8;B}ex9azz0=J)kY$aoJ=QWuv%s!(EF| z7Jl+;U;DM6|M_3|KmUt=?z{ixFMs7L`tEnX%W=D*rKai6YLt5WCbdV1NmfBId4;92 zSMZ!hf~dBjM4uMog(sm=(x_IpC}x#z;Y{wb}))Sk5F^ zUPC3>y5dAXpTx~XRkPNG1=jPB*z`>VF*3m;@p9Y{<3J^#dE)VU;(Oow4SeUjzk$c= z8>^u6?G>5Hmrw4rRCodR1ev1l>k%&wkV{8Eog2|By4sx#27zs}CtmW%2?~P3#xnV2SIF4p9 zXBRf@0avLO@%DJd+nO{A-@Oz(ePY4BX)W4DM5~RgrV8}QfSq!*!D*Ba@Zjzs0v-Wb zq=H2cxDFcNu=1w4MpLmk4O?^iAi)5cZ5vR;cWilV9%BLp&4 z@CZL(MH1%&mHS(GPg?7Qlm_nrd!RdGB*JOqNsksY=xqzb$YCJtZDI!kmSpPy0+@cL zszA-tIXEmwD6GPn1Mx7GwX8Kp2J!v_x~lZO$?(%EnBfW}DrkF~p*&V+nG|20>1-3L zK^J-tCxm!JPg)>ke;F8~gA{>y7m!MyfXo;$nrDEnPdTmf-;4~d^7>e{n!_j0T9~g3 zYd!2$E~@HeVL{7@=2a)o*M+lAV3D&Pn2&{tg?GmddH`?h#OwKrdh3GGJ{$-=s!diM zDTr|l+|n^{F#?$fB0Qsr)hzUY{o2PJi9*@t(pAyIWjAS+HGv*4x=_oZW9{m4__6g+ zNCu?9(!?>s0n2TnI(Ch4$)$wZ!HzAy!XBqQ%gi)43JIdx&m3HcJfM>1nyiBP@p+&y zSq$W)CoXg$9_-KGM)xY$Y;%D`fzv6CD-DYb7N)oGZVnO^3sV5*X<)D==pnxsJA_&~ zcg;jqVe~f45RlF{%6uo)vH+jJTnnGQe^XVF{2qeIWMCYLybZh@@9K6Op%;Ia9V`Zg z)|%{@<+Mz?_mj2w=x*(n36C*_6-2dw9rPK2TGK>RfSOiPMC}pw2@A9uq?W-?ANA4G zPHN{gGb4MinP#+zvejnv*WbsbfL z`Hhd-u=Q+~+49|LfHCQiJZd&Tya@{1A+q4nz2dW>?t8ZjRCQiKbiJzmf2gZZ@G}(9 zfK?Tgnf)$?qwC^5Zrncqa9FBrb(DZX;fZ@1=-*&PwA}wn*_Q!m_1?7A=O#l7@{~__ zbYoyh(7p}?v}mP7C;xlun!mrg9vSG&o(?*+8B*9X<3yk5vekKq7_RQce%R*yhyVSH zy7;~Q^IRxCX3?AQo0`YU+(vF!4l16 zh(yBwo|$I$0xeGrBnxbYZ3nQKnfE$zqY`-c@+tn_*Z=NUzW1BI`Q5+rSN`(+`q#g4 zYmL6UZgw-hH>U=Wh`k0HbjT36tewoZDoDsN9NN|m>xD8}jwZ<7>!ZgOZs1~XnjY0+ zRyxv~4O*(ZsxY>)AqO7wfhZ!64ju~!{|HvzJVS?`a!h;1=wiY$03Ej*1A$}Y6?FId z#pn9|7oYPtzxx@^^S$R61GpbI?3{Mj-Ej z^=64UyXk^K3_3a4xZ9o_ks}~bHH%L*gx6zTAWHj0rHVwTLUT=e%@~YgAArtQ?zJXA zzcOm%ATS7H_i?NK%%OObDf&AcrdZ5urN`xv6F|=S05j#CC;?4BuP|sDre6UFv#g{L%OmAo&4H~T zSabRrOM|y;rse`UpQTO#5o$lbVn>w%dlc=mv>xRdWjt=f6DF$=gEh}(@5zYbjBwCY zSF40I*C_aa*i!RWC{Vz;fZ;&c^(e$WfmK*b$U*x77~Hlj&qcG`6Lhmt?K90xSXRC) zY`F>!wsoW<1Px$rKdOLY<}fS6W@JLO<|1Q2H3_%?Bc4;$0>Yeo)b2CeAVEwyZwjkQ=UlePtck~ZU_DB&>%sNm zf!D{0Dv$15t8hLZSW_rRbD`hdA(Rlf)Ll3@5jDE(O+Bnz^9d3?}Kd5_^<1%sgf`TV#0@8Hs6y zm87Bp7q91xsI_YMv#Mq5RLPN?t}zF1w}CMN83%H7pzUxaG-rY3H8icM?^={tsLBju zz15#lZI7r0CKbpI#nshlddzBTmFO$Fs^_(P?~-H#tfy2~2d4G37&Z6-pq8psF>b@w zu~wfNT!2!-lC$umNBsd_CAAy7z8@-JjKhSG_Wu8aTW-e}QII02pZckv*1!8#|LWUM z{lrgw`st^iG`O{}=(=c~1Y=$PdXYfelSDyt=ZO^{1Gyzxg|!>rs!R4RH9o9m+wkgI zp*~{p+j=WnZQz<`HISfIpSi}`b>TCU0IfU#C{M3Q5rqxZbE!_$sL;-nQ(JH4l~{c)dD}6#&y8*DdZVY! zIl$4tg0%OQ25%Z|SrT>(k_ui)JOH2)mAd35)!ujDIZA?! zWb7b0^T@<5GT3Mo71(nGFWkf&DZuXUDC}Xw`}s0BU?2hAcqr6LibhFWMk6MwrGEX& z*t!@2$kg?4J@Jp{{pbnk{#>46*w?SWuXQ;tx~dO}zSges>jF<~I)(jM2upS&K_x1L zT!ONxF?KARwwj|GEEcqY4{smxkN=53{{8>m|MuVhxBkK3`=$TEPyO^y&VTq1e`Vw` zux77a_}&*b)7w&4*M?Z9osbwI7vC<{T!{4dE1{xwf7%UrQgU;Wo%Fm>T48%Td!2<) zvqiG>Q{xaM(>S%x21&f}Sc*ne_6Z6=E6x0=gz%NW9|v$t3|hi10B^4!@Zt4=FW!HF z&%XCPyq*(g4v83vmzPg4B8|#|c$JKf&hdCP&@%N@7l1({YCjJ!b!-p0UI zfY{ePdt$FJAM2W#{CG^%D!hJp>#(j50LzZvkg!Ar=mLU>En7r`h`ufi%xk}STU|IX zab#d6aJ0yW2%K1+B$ULS3RB1MxKR{t#|@E#Tm{_jh$=D@t4?qc0cw(N$N(qE2M`a3 zc80r67k{0`YR0Yie=7w9k+B1QtUp!+-AfVR7+9+_RA|<=N~n2?X;anh7@NoQp^|}f zu1+E#P>9m$091x*TE!p%G18-%w7LO-XNpf6&>_v9kA~PH5vF!xvuKqv!vgPfvzD`N zd+$m(kX5xT?}RK9RuVd0xPcr&%;o(u8jRx@eSS1JF$7Heh!VC5*|}Z-Iz%iIDrw}_ z8V?+I;e5Cl%LUXDaRf#r*CIwbWkalrQp_b)x`jalE*X~5(`P=Jlk=Q&560D)d>P?6($Yzt)SN9#KAVA#kmD`szp_a7fvIFwFb0;AbWbyF-C_GfG9UBq1Ax8nFo!|-ERfmjtT3>%%$%# z=yrC~V@o8EF(^poq4B2aBaoY@Xz6yqPhCImz{?IDv?h~;V-AYLr#U48)6zZ?#0ckMtnhCrnk-(x3KXhGh!SM7 z7`V~$>2fkFq|*8J;M-Zy?ApnoE05c)@^-{65-}1t8FpN?EQ?=Ym6aMElEHq@KE7ZT zizM$89VoliCgH6~!RP^2ty|hQCkG~a?@d5+q9P>~mr)crO9fU|sh$(NT$6Acrr4nj zCEL&ZeEOX{m1(Ph-SKsu#Y=WoZBZx@2(9_xPyX~Dod4kKUq9-x{_{F z>YBH@Vc!0JH%Yxm?s{|s0v(v^hpTO9A2q{U0qqHRR_zjKkNmQ|7OfKY=vyojVrLa} zt)@P^wyMGD#l0xITY`Wls1O{D4WsmIJ4ZqlsV}mV;3k<-%_Paks=N0gy@78^5fX?V>9*}#j zUy2pD0J;dIkNa#rU-0+w5C2(z=(qbZf8cjN`X9D-nT0O?AQnRHRME};v@|4k(WPd` zjdpLeH(D`(eu&g#LoVR3rGwnxdhaLL93%R^*jsRrGkJJk^px~zpq)+QkdvXZ|4MfLpKQFh&wbBVjjja;rsy=#%A=AM5Lu|+A4wA zUjMuR74CvGtQr^q5Cajk+`k#o0Q_CHB0wJhwKD=L9IWLUErARiAruk}GrT^8qCZD; zD4@Uh%l#dG_1Ati{@&mH`>+4QfAwF*odVWhiA}8Z1Bk`i_A28Pf~S~WOc8a+l!C-^3Nd~Z5(zdyl09h1<><3x15TJTy z8<@~KmvJ+Gq)uszNG%^89)yw5I)To1U<@n?xhBBTp3$WoZbsOfM-XrdRrozU4Gq;P z=T@2o=A5V=8*`ouv)-(}SPxWXgIn$2ZD6Wcco{bw_XD?a=-taZ#vtC^Ewj%Y7)RoE zyI~v&pgpLbJF6{6S!-d=!kW_sUVAyu^U-RI9_c3Ftfk%9Y6)>8Mx^ZmUW^!UCc*#+ zC&@{x^`U;4%}=-NleEOxin5GL4ob34}udykkt&x5rK&+%oQXZI+@6tkaWpP5ygWb5e`otFa&H4W&<3_L76nAqveL^dNRVCf1v z_4;=TIn$3rVS_AgM518nrG#y|1BL;OW(kQzaU$8CT1Y+C-a%Onh&%J@a;UcYZ5RIN zdLjfZwH^WxDuS_=5C_58l2JWtwJxubMXV%NO=Nbp+!-OOWQz`|T8lY4eLZYrTiC49 z1nW@cw00c?v@pw{IV({~Rh z&U50NkDBX@b56{+6X%@JoO*psoR2rg2&~f~U@p$1XS26r4a9LvY#Yff9NKKPqOquU z#@L5l4)Dw%rU8wzHQzSFkl{v#CH;emvkF>E5o9vK3{;QetZt|-8NZe?f@}HTx4_>q ziSRS3eXTA!Ry&>m4K_H;C&6`<@7P%~dy2PBJra_LAnW0v##@96WCt5|Z^%}n1a<(M zNO+XJs46j%9u;RdU~FQi4CrZ=R)8Z@F_JGYcMJuN+fcM(ZRfCnvaL)|fo_AfxR@B~ z{bm^`aA`-OoYtRVTmvlE+2JvwEkZ&>PbS)`fd>9!uZ#U0LRVdAqK{XD*Kh zK!SvLH*{52#Po!d>a@mEzdq1G*3auwJ-*S6ZC!vs zl{2Bpg;N_;MH5Bdm(6n5rOH~Z`cya9YRSM7k*y6?yFkFAW&X1ayl>F9pNamO zwhUXk-woPjeGvAj^F97hSEIc<{<^{=*?Y+LNPPUf?IwGNGN!B&LO141g><5CTL(H2 zSUx4^5V3&x32e!<`>Y6x?i#xf?kZs%^3LKj5>Sa?NBjqQoRw8-7Nd2cBOxL zm#SI7h`Lk*-bvx2Fj~IDGi|N`=3v zy`}w{JN%}b@olTfi0cs81xSKj%%vGk5qqxTmXJmc0A)J>I((77mkEFV=xdI|1p<(P z963ID`O^Hq{Cj`(zyHU7?vMSi{>8uW=huJspZ>kH>Ny(OOOVTI$N;t!5&hW+Hwr~y zwDWMbTxsWwWWo$;H_ZHKd|nTFgXQZk8eDh)Yx*F)MlaIMk^>TLzzTx%52fTlK#pj=Wz?`qwIGFo!V2m3i;C2tJMX07(h{kRA_M4FoQkvo} z>NPF>i^JW~+M6ZK0I0&b1qC3XSk|P@eT_x{XUXB*yf*%7x!!(nUxyB+H2Z%2Tebxt zlJB9#VgTo(G-r`D zvC5)Eh)|tS%bi<%)+4;V24W1v0w$K%dp!5s)!{#k?1qv?;Y%7Lc%J0|xb699P)=JB z-!+GqWq~*_a%gHY6R1;oXd39-eRf&3630^^(r+ z6RW^-14K(GmxrJQM8xpurMcWZM7l`do=l6kJzUmbEE<4VNT&1i)x&2u<{^)o9C1gL zfvyn)gbDwWP^~^q3fp#CQo_etV0rAH8XyVwYv5U|6c*MjfCC;^4p6pjj2Hlf$CPKcx5BPO zWRLf=;2~XMR{y`zTbX6&HBH-8mSeYrl22YF z8GbA&P>jsJf6-E2U-LzD=vX(kC1mf$h1GjMk%Das0D`HtK;Q&pplV@c;IXEN;OJnu z6=hHf)%HMOT4Hcn-6U8MSN>{jMcY*jHC|ke(mANZ`w_Y&BMsUWfEYyZKxEVi#wzbq zw13R?0nqDzVM&_jWC1wO6OZ%6dQ81NUb)`h@Wtx`>s)v{AI-*l4RDho3@gzHkC)8` z`okcRoXL8T7uDyXNfVy~5!iN;)>u-d$srmTv{%aeeb;15swAUeHjrz%u47nL&{Ll> z5=*NCFCFAstIsG{>*fBXRZGUseNM~PgSD1-2@>SMw&3mNCc<`x)$(jti-5A#frctk z5oVtYJ@hq{rZe5-kP49{LO9*9mz1PcBexrpi5#gBm&db1VsEH91$NLP7HSDGvTHt1 zd5B2Z!i2UpdVOydz;z!y-^Sxj8n`4J6ls+wwX~eeQJaQyh;iEXW-CtDf9|6jSnF`t zYh2nsOXwPE>;6F^L7nr|ANrY}!QcMde|vrJd*A=(fA)|4?B9Q!C#swawOH5d6KX)9 zpX&x5C9ij(oA}y~murLNUvTe>-PHNHbiZ59Oaj{qRk#A1SFdHsV*o#@c_cdXKm};J zS(Ux_ThZ*#=4(^^Y`WO0R^6!cLKZeq<$qJlP#gTH>d&)Zx3H@=bbTf5^htletwMnn zU!WEi`<`Fl#cO1bMXY@$H_)J~Ic{4d&`JrDuheuyUAyjR%5-B0*A@4B)mDM-f9Y$W zCUWG!tg5J-@aa{w`{s-=$gf{l)h9z1>)sT(Qa_ z77D;Vejm1i8(CpBV-;89XXd`YHQTG-W6u1Yx_D@YKfso0t1o#22Q8l`&}rZ3-^p(B z{d(D9irYiKS)VR(5L}jyp}`bnAM^o4HSFL*&lUM-#?RmctDB4V;_hN2xfz4#{DE#< zSqNIF%00%fo7|o5e}N9+gjbKng8_|TC;Rt(R=C(_g94XKCoYgNoZd9Je8{Xa?9byAaE?^4dIPmV>9k=@p$8p2U?T-5= z@9^@;9k;yWe!D3S;>bb44cds*IUlN}SS6f~6YN8L*6hQBfPjqBX%#hQkG3=x)@WqN zqsCU3a10Q$8!teZNF8o(n?>>{9sqI*wyLXXILuQHtzd-nK_V09+rx)86EQ|pNCkNc z7!iFivs?LcBRj3%wYp#g7~V6g)&(|#E%#Iz`)Nguz14wrmTg(h)zwmh(z%Yyg_g8&8ZBeknaPsv!Pb7x`Yro5F)G9bowIj+}Y12jd+S1Ni8-UdqH-f5F>J!5I(K=5= zgz4KVZ)P;uQB_C@GLWU%lRnn+-W<-nsjUEU1x|*QJ3Ey-qJL*e#|WOao`Af7HRbSG zWyvG=Xh7~Ti@Ic`#x&axpvkueOG%*J^n3L2oEwDb@wP0~gqT5~?d=WccoAX4i*^`kH zK}jQdFboz9A~F>s$#h;vZeW|JbAhd4-o#7oIg}lEw3k4Jvo1~*QuewdeLbs|N4RV& z&sEE{Rk6=xZRLylHp@G&x-kcV&>?%ioEjc|c1Q)}C{>vP=-O7Dd4a9Okvc-CGbu_a zJ|`|+``;!8&Qb+wTt)OA;1b!_E5svtkhs6RLu6DkyJ~1P!P+D4fHgZuAa+CLHNN%e zTFV$^d?dR@Phk*HwrREur|a`>z+zZoCtCF;31b|tPj;i(wJWXQK##y~2*NdWG|1IC z{(ap;ujhkb``RDS`!C+(Z~l$H@jvgrCdqJry_P){Rb*&+%D{8~`qhEZA;aJJ;VK!Yv~R;{fNQIn(% zkXGC8rdr0O1{^j(P&=2v->cz|w#XQ=L;+IgT%gxNH=|c`yXs=-t9vm?Pr#(}5^C*d zWB>0h+kb+SoAKZ86AkDH4nvH-7X{ctiT;5Gjr|<{Q`+p3q6I$N&4Tfc_-=eH%mKw2wF8hk+oD(br5d*NJy zfa`C5@BjQB0RX?nJNHfOUe)RPhKH_(z6;8m z^mF}+&5lR5O`y^&u0F~WVEVvfGuA{uRO+*^uVb)7a)6z^z;2}Z(SP5-mgfiW#@ZMG znf-GOAoLICX5%xTvN?5u+z*je24>n7@%${@po+brM%SZv35VLnzLtRoRrZJ}dJVt; z#|8z|KGPVxD6)JyI@pg5Hbes)T7}4P9(e!uinq_-xgP1E0LS;C{d3xZiZY-+4a{L=G2NWnjpRUEwjET&uEA zSf^#%nCj?juMQfSYXIrF2f68HV~Q@e=-sVSaqdXVKDE!B0j=ssQ|q>SO;JwT*=e^arhvIF8MLEAf^nwEneej zX~y06Wkv81MNXZ_aX_=B&Y8A4Rw4&^zMXCmkX@NTF~~K|HHc486fy`B0W9~k%-oW9 z7*w;LjRh!0x_>_**gB;yXhiR$br~TA?0z8GIG-uR%k?UiIBGSLw>596T>J=W`Wg`;Mj>c@>B>}(p^N{+?Yb8p25oX z_Qo-eenz^8%uaBZ&!MVi7FY&}dXfqo-{f@MJ%&8;&>$F4r6Tw6U|TlEL168PZSJtt z^S}3*J7qPARyipF4aoYCZ<5N-MPxV~zKdTM+m5zM5@&<1D%Tf9A`^-+n7dwxv?U~f z4Cke|&G4fczZkR?d>hrV`8c>=edik-ebank78e9pM92oLY29UHpNUuQM!j3I>&H=oOXs1}4HiC`K;maQ#X zO<2HtsFBy8iB|9b8-8^SXr6tpBKMY`A z$;3E(2HkH*D+ax^s%Ubymb10A0X22M;~fOuJO_a=o@t2JRiGQ+p_e6Ya{Jvp&L!?CS7Qy*HbC5a{`=!vDL)Oss1$cjm_=@7qiZ?_SbBAKsEQU z6cZZVxN0}btLKcVKz$s%*GzMj!wk#c<6^uU^z%p51?+5wdZR-qTie)^B=+m>Mr_TH|bd~Yd;g^h4Un1x|YNa z3AEB#lTbFx-tWH(t`D1Kc75c&2`J|Xpso+BwliFhmvGsFU6Y}~2VUg$zV3eguE({3 z2In@!e!c2sFyiX=H$L+J4}X4m0N|enU;LB)y$cjJO60#Y3+;b1TNmWD2pwvdP&!32 z_FHr#&u*y9w6}-7J-%ChsV)@kaW0@nFC@Ph8)#qy5a?z-8a1+HZA-EXrQxEL*QeB{g*l7n@8(^UboQPV zinNzFJP6yOQYAsNv=Q7h-i6k$L>vIT{vG-YV3lTbKACQ^c{_B=WG&$BVTSs{`!Ddt z>jwu)4KtxZk7gT|#!J;-LiYJWKKML!qVHdytsZ5$n7dnbIeKk$Yx%n;LrXo0cERI? z!k#xZpykrdNOt59AXdvJgJ$ngo7u!pHh(r{R@JCfZ3C12(N#za#Q|JWU^B%4ajp|+ zAM%>(QX8(dvp}HqmOJ5Cbglo2~g@NQ53$93wBwQa5z~s@Y!4ofo7dgPPS$gL4m7AFN9Ty7s86 zEu)Pba3EE+(g;A6fmFr?sID@&x~!6SXqkw&H3eILul-5f%uzY7tM|up!Dgv!yT4WC z5cO)`rAiE2P3D`!3NPPvB-Wb6B)N*B88b8GE(SB{2DwAiJYKJQ)Sjis5&2ZSkbvBD zv4f|WElFL4j2qTk4HPEc&IexJ-LYkx0pP5KK{IulP#oE6N22D5%mH=7;8AsL;W%B$ z`7^t4VedWjbckjofmH@+k}cBliBScVW}j3B2+t|p?z!trlmhGVfWkp@keM%T(9T6? z+pAsuMiOoXT|i&pnP=K-shE*gOGH3bwWKy(m1W3at2cVTDe8V3T+>ZpOP$+}-A_mW z=lM`ZvVF=f@Z|<*)|3z&>EP6iG?=qWnmq@twj#fw|4E2f#XPI+?>fZ`o;#Bt#;YL2nG0>v0CADwLon>+qIy7PaezS zg!f%RZZ!`(#;9;fd+G36D{YQIo$5ebT|mT6wWml+#~rZOGZ^4LOdV$-pw(+mOC-^x z(N=#}*UDWYV``xom8gK&jV+q|5*Vr5%YhNe9K#Kr)Y>pF-8I!yXB_HWlD}*(=Pjvs zJv*8uw`!!4(DZ)dCTKVR8>|8P2%=KgKG?$)E`%W*GKem~MY0Xuj`sfPpZv-Ch5zWU ze<;;I_XmIGXMVHJ*+Yvwzdq^bqsombYAdmRumN7$;E-DW@5~JL@2q|-s|uLg0MzHq z>~LIcwx4ePSzShT&VYPo*0uobuC;*$Hgmk1tzN5q9TtFQ^#QZlwMm!;wjQ5!4tYpMTdY(gEQO9QC4Y zLqr!dJDb7RY=`A-Tgjf%u#{80HW~mV#gQkNx05*BQ6B_QH@FiY+t|VTmef;qi4hJ6RidPJ<=$8szEfc zvYWDK>DWGqc1WQSdw}Y{&*2V%!3c4<~-%7ykPH<}d!mfBC=l z$^Db@?cezI6?qVJ+vRaK0mSODFkU;+BZIDBE_l{$uQ6pzswbm7JF!GKucquxpR#%U{;*e&@S) zHvp;QAcBKcr^Bl_w6s`EtT}--G3{ZvB+&pjdacZ`358)+szWNThIbc!#NJ~}P_-|R z4QiQ?5;CZBI?Ax`*ahm9%0$e42O9?N$H3b;{k#!Ag0&k}ukmYwfeu6nt1|%r=S+~m z$br?qd}KD5qu$mHZbYY=dk(MnJ=VhN0I>;O}{Bb+*I30R8QkZ8u{AJro3wyy#2(#^3z^Ft;k0xxu z&d3g(F5iHcYZ(FbGrd`HbR)4=nVEnk7?;0zEu2fZjoxRL6&PFknay6V^Rx^k4}&K1 z;TC;XsycX6(Z%-!=%jogP<8r|?DXa8&s9CL@Cw+==zAmO;MEW(g-0`sBZd_`5wPEV zQTtSA>kcT?oKOJE&l|GY%pLB5bFqRBK}<7=PD;%ygy~>7qzbFgmX7gVg*aMy(nVa0o^-U~{3;<7^jZpBWx;xFFn*u`gFEF93$m zm{rp7YYoV^@emB6R z#VHQg_1aLMOM7x3yZ+phfVOuI$cy3(?0 zMEjcb=QeA!SJw4E``q{UxEyUCx5B$`zWV3iJ9OZ876ABdy!B>vcBAdS-v@=mjoggv z+*P{Du>`FVmwl<&js5m^yOQj(x!5dHkIdL4XY^}wH$8AuoeQYwup<9mw5Dl`LALZY z8tLKo$o2RT0v!a{fI=U*=w>b;^ze2!NoL@#pNrj`^|i_V+?W1~&%(d!X3N_ZR!TtK zNc-K`*W{XHa5dY!Ue+jbH+_5t8%8s>=uLY!B)|^KgNsq_>)#KN(S=KzDF$*g`2GFa zz(WkQdcgNI`tw}A$snBcZwcpU004Y8NDLqDhz)``O8`hS$I;g}6Jz^%V0od}#P&6# z0gk}V2-rZ-7ze)i{PXz5|Ku0{!C(Au{7e5_jIqA+-QO7RUf$`f6)Bow$j;D)i)dOm zOERwRuvYcTi5{_Nz{iKI8~S<(i`78Q(d$`=5xQs6!ED51o_PQM13tWdz&aP^oQOyq zG3=NB2q4>=b}h55og?1T?S7tus5P;b8f$rGHoCt)=fo{jop#V$arN)fO-VDKAd6J! z+W7eNgQ?s!CzLU`|2L5c2@fq>ObD>jBOeQvfjW^0Kw!-i^YN;;bFr42-Gzzd4ae<3 z9;tWt7rwlE!6z@D;N_hI_{K=&@a$zddD0ETS|)WNoNp&eZvbxs#IT~1X0i`38uN~3 zVamni5#bQQ?z$zQxR@NqnJ@au*9#qxR1l6F*f}3v8)L1HKsYUoF}C7h1J=D$HZw~B z6BtM0oXf0j@4hA_8%f`6&2ku9r1z!dfatxD+tbX2T7_F4;D|=Zg{rfH8{+fcvpw?} ziB%5+qA1Jb1wWg6%qYf{kLPFdJYA&2}DKZ&l(4m_m9Jd=#g>!ZTuYuCEGU0G$#4eUb5VOvbB5orcpt$Ac zYG#QW7>ib*pg|2M9B10vqgEjp^O^{bJ}iN%No^}xwR}H3OS~AUWx4DaLlC%{m5Yo9 zrTd_h*`|<{WaY{gs|rmKBM~@*ID%U1WKB2ukppX;{%UlBGAYbcU9`D4jw3*M4cD4V z4vK0&X)o#q6-rC14Ety;H9_VoRnS1=n3%E z6iSFpUJ8(Ax%QML5~%6dMG{)2P_UwH2|jDJz~{t|Dj*UI#0Y>$%sLG&VDIthv(I9k zwNAuH5#;P}(W;4YyBQcKaXSV|#Bl`30Z@3HZ?3AQP+I!%;RBZz9`9fAdQQyw(Ch01 z>pb1>fGxZkI7VEPQ<#ad0Z7<$-3hwbp~z_Fv9uctv(-sq2~=&Mg;%wEHBRU-J?uKE z12HZ6VAZ_9d1p$kR=@RDlDwWTZe_r;4Z#y8v#Mj;UlCPAL|kjAM<7GeEQ(U*U}pF{ z3_@XBmHJ$%Vyh+!Tc}$_%ciTvYa8T&YeMc`KHS#rP&=wgk^X8PHhBrOw+P4>6a%DF zJ#&opwIBcS_<#MK|0loxjbHg6{oJ4Yxqs6HViONNB6i#1Cj9)6{(QAIE9f)3MGKrL6Gxzy)yZo#43-{Qm#> zX956zSUlqS`~Gj&oA&02US!b-PE&$r(_l2Qy3ux!6uRNv;&^zb^Xfvf(U|BD&2Fsq z5pu>20-zTICWzzNz;vT;X?Qoi<;`Spqfcf=+<;kn+e5?5(1Mp@K*S}}kG-gNgME!n z^1_P>TUHpzDi`V-7(jm(?ts3&3atiEAGB8^4i_-m%{_eW{QLflmv?^K1Hfxc69Ib! z(Z1j`V3N%gBg`Z$CJye~>NI}GY&V#I-NeJpQ8&}s-=`ulz$@g?p-|i3-#`Wf6}A&> zkDUVu_cgU@Ak_cKxL8qxBy9;GuY`a9y06bbJg;r%0K^#kYeL0ND|Zq6Yv20LyI=n1 z-~Yw`_Fwu-Kf7w`JKz3JYBPWld{D z*mF5rKd^v#o_PQI9$$R^9yL!bfJY`W{kg|+wEWBbT6rotY7sdOR4w!%LJnrDSAIT8dl*CZo^ z^2n<#p>LV6J)VF8_sf(dyL`WsFdXH;5u9X3ay!XoaaH2hli@7TS zM~?QycZ~xzxH7QTbfL=dej{M6(;Q4ikN;a{Sw@HBUOtuo~csByJ$jwX9rg<}yZj zZh8YNUHA*tv0Pl3(~U>uvDKh8MuZhpO;1E(q!lPoXrY`%a2Dn|@%H+P*Ykn5FFt6_ zg;|p*^yp7GR5(3-=*R>ZJ($FYR+O^7BPZd-O8h>bDl+TXdwtAas>f)pi7 zq*9~`7eHEui?pH41Z)E`5^h;cJDsicPjJu8gbf&W%P?TTfI4p3NWhKk88B?vkd#0Q zR*EV}Q7n>T%?L#>81ddc=i6(|;l`M2ebz zcicAFN3fgE90hvRvr`Nrma0%AkNCl_d}aR3Kl-`jXaCX9{MA4I7ysh_Z3_j|;MPZ@ za3wAa9c0>abJaymqowWOD;wOhy-b@2mCs_dno(=DgxlwXpB;1;zrk=zzlp-!%t%Z1 z)wRFcg1A(;r0}f*K&{R~avfnsz&^*kzdJ0@f3~!+ee10Sa3FoJjDnRrvl#|=+8;Uy zgL=PLMh6+Lt@5d>Lti_T@Uh|^fOa)Wv;i>D^#R-B&=n|}EC5ZIaP@itswtC;#CUan z17SPeQcpN*sMq9!?G`PwZ^`NPU0q?cC9!LAwfctMVXl!PbT(M?6^-z5ku^Iz&NXeH zRdjQ0ZQ?UrGsbMPVq?C2S%_}7{a(oWUlw)${(k+w2!Ma-chK+r?M8|_SrNcqFa>Ou zRgk^o@I~CAZkyfTv*NW`Aa-|qxd=zGnPnFPd)&+pjP>3rY?;2;QvLl&ngP9sLI z6ZX#~1!5q^UI)bJ?{7I;;TTW&^^Vy;5pPKY%uI zbs?<|CM&EZMOu2JIRPBXgOq4NP8DXA)_L+i7v`E+=h^QY$`HrX8{Ec$FMZ#qdb&OF zczVM7H}7z~9U4k<1gM3Vg2cZ-|Oin9CWLyb7+mAfwe24`o-6E@SkXU}q+DmvWT@?xKt5 zr9GvgInYILT!k!`33Gq{{p5Av?WC1l-O(#n+t&76a#-pf!PTSedg_3$)sCQBg3>6X zKwh)Y3Gb<0P?K&kL@N*-4(4On0HDMSX9Bd%hvZHyxX2AcR}MtTd83)FTCGB)&#dJc zgXmVOfa2~dBjpjL4Pq#1Rat3u)dj#TBISmI@1#iuC+M%v2O*m3_X5+TBo%43vmjM!eb`SGmf|r$l0?n<`|mH5)*g z0MPwq;yz#a{NaxK{RQ`)?o!Jg*dv>WkG6MaVu#Plb*&)pkwp8dT~4|76t1vf#s+}h z>1-*;u48tPoZ*tMM}sz>mK#w3fT&1uk2ljGZee0oAYwIOMyp`eYABCrEMLwQ zx2Jdd(w9HgFZ|5U;b;HzU;bbGnIHYre{Bp~N0k6qYatr>l{~Psqz?AO1!is2w9@R{ zhmdw7X8*mf$m)u~1YKc=1GW^r)Lpzucog2`d>D9pBhu7nK zsNuGNorTb4qDhTb!nuK6CNY2}Ie4ApHMgd}JMe{WEUx}6KC}CyH7NtALrZ7xYk<1T z-7O`_XL5D(mQ7-KJHuYhQrVKQp9Kl)f`OfpKzb@bzwS1vu$eJ*4eHOn@2A&IHF@L< zRu|ab*lXwTm}KA;1h3v)`cCzJ(m=FHTiaf7DGi(*hdv+r@4CaUt0Ube21_fj$J*i~s2XQnpz~!8P z3vj~V-Uzr4Utl|Xqpwc~q#Fw~00p;1s)29=eY0JCFg4*2M)R#0@S%f@PWldH7gnG< z_I{m&NBcQhe&+=+n{__i35^B`yTiZ7`DLps{JB~djh6CcN5(Pz*?Wwm2?Pi5W!TDK zLZLwro5a8?5`qpqi+-B*HWd5?5j(UD6uNe zfi#&1GJ!dJMsyd1UeBwQQHIC^yI}5Y13FCawcNNY8B{R0^9BrZt%Bg>@cZ)}a~AIF zL;xC@d~)`w^a=4m{nCR~vj{&KJzP6V1bY0JT$Bv~!NcO&KRYpb^5CukLCW7>=>sD%e$=d!BhVp%cTlno>U(t!N1dS`M>|2uycTdk+&dn=v0m zP45ZW{8p9ao~sIqWw1P#S@le;*_kD~gH-OrxNNcPh}i`k3TswV4<-@EExJnwl><7k zW+5{#*=qY!9ZAE1VXdJ10Bm{aWCvljqHMT(qArw31JP_-l*+aVf}T9#VvT3@o>c{o z;p=evMXH?UW>uW`pcnzDEeSMvS)JaUboKz3FvH}U$)`Xb1Lt{flGM&p5X*(3%GoNBz(dVB>a!nRSg!J!f$D4~5^MUQx4OmM-=}yfK!bt?A9NA9>a@}fx&ot` zIrj5{fsumX%!UYJ&ZX8Opy+!6KkjXv0UmzXevUO^naw7TX!T87HB@M}!bI27X_9Dn zaINWWz`6@8D+{|wZoNc<5%&JYu45YT`nfo;qHR6|!V@GUh#3dw^kf<;Bx^7H?+{?7 z0~u3}*(rfp?axNnP`)xK8hrUVaUVpM;1?G17`@L42Lmw<6og~AIdVT2&T~3^b1j@} z;(kAMe}3jUPu%aTaY5hv@O>P|=%xdD84*Vun4HjhfD%jMOa#^1O^d>s9^dMT8j!4u zaV@r7ziCY%hFv9>nYp^I@_1XX{{r`z$3BF%FWNQq?f~!g(w{*c!VR?4*#)mC z)N${t$^9m4(Dh$cUG?8i-It&wS$<|sitOf+USWg~)@gM*3|9BjMd#^9IO4_NuCV*k^3j5Oc*@Fhsm-HX4aueYpuPv?bPC99_$)MT2 z^b`GD${VG>i9o%`StMMxAk^yfO;>HP5LehF zF0#V!<&HU_sOvenFkGYkJ#oQJ%B~^HYZLpPViOV#!fDm`2J_n6Xp_5}kZ~roz6;Fn zddT>*L;W_0+@waIZeZs*1iHu9St)SX;U9d-hBJnDz5l{m;6q2N&&E%6}^hf`WRyAi85@B9{G?OgOYa-C&vh z->}!OS}sR;&U$WeWvK3vS=>1RXqIhz=6#VBo6&WE;eKC-45GU{0OZgZD!Y^8Ws+zH zA$IrPQafAj`_H1$X#+tY*v<2xyZYqi*%x8IF}Cu-*AVG$j^GYsw4^gGIX|v^0mgn^ zVRUALrvX_080q`K00!FExx?Kl%u7Zck1or}GHbS~y>($7$_D)U0%g;X0a!SoSoI2u?RoW0OwMEc&Si zD7n*-3?-)S5F9EO5O@rCLKv3MEq7q)0qM-cLlhZR$~4aKNxZ>fhCtj*8f}-FmKMk;qN4D0yuqxcYg$8gF(zG|UME}w z=tFD?80nFfBdrS9oy465vZt%ewQxHUYuP$7GO=eUJF}?}BQ=6_bkym$I-k=@s z7Jaa?M|7ROT_Tv(z`MtZK274)a)O~GvV_I{GvKn& zs20YNLXYyCb0VX?wI`9op83e_HTU<5!o%;`+vb%KVbi8N;54J})k1i?gOL5j%Hwx_Zh#nmht&2krlt4cWnTw)C=D=F^a zuY~FZ;sENzV)XZv*E+j^v?1CSnm&W}2&sEb3=UM?CEG(N+8RX2V?YNGmJ&WB%e|Ji z^-3sE>1R89-L=P9T}6I(j(0$n{nYTJR4|YbrBx?Q;IUOn=nlv3Ijdi*2gOYg*$`yQ zqtWDy&;}fjcw|sDCksMmkIh>JMu@|@K&<6;-{qg1FVK=GSrjZk0?<6c&W-TYFV_d9 z@MnFXw~CbTs|cthR@Dcq!i29XyFiQSEo0%HWm7)Y|~4R^Xbxe}_KmcA7O*#M-0s&{^1>q^}x@LA&8_c2+M zLKeVVuL-oLoSW!fs_D_G`>fg{w6D=_UB7jZZ%c3m7b8K>Tqj0^Z5Cm0rPYLkYXwj1 z$qnSZSOnKY#>cv@lbKi7Z?#Gi*ZX&G@X<$~^6&rMzo)N%^Pl|p|IDBL*ZyBm$AL9# z+}E5|9=1?ncVy|aXa~^>tI63WUJBiL2U_c7@LXtN$ue=$p{b}%8f@9TdZeb$%Ibe> z?6LZMY%4(n@+*mdx7_==zRJSwjgnIYPyiONLVzar7PkWwy$1ZA)g=981LzccliIJO z{$*w3LlJ@NnL`nbfxeFh_a>XM;HKMJP-8N- zoMBrW5KX3C-(&L#wXry=pH;tn|3JBUw$(u3d9isn?sw*2~@5g9j!*oFHH)@i_ z&%)NUEWHNsO-1PO-`+QM5hKKIqIg~In&81w{Hyu(FTx%CDa{tSHaMJJDV{HMo zFq`!N-W~SE~~HKF~zM74Nkr`AvL8OZ78}f`Rz{yN1)? zFo>dBebJr#{S}ybjX~R;c+VF$k+ZD=d!*kZ1AxG=#lXcV4AN7+C%^?X%u8$=09pp= z4Pr$0!DFxLCMqKOn!O?jLPUiFghoCA0FI|8{NgYCEdKU?_LIN#SO3TV&L97QAN;Dm z_Vusp`Q^+!hN6hFPRisxqv{(u+*nNhdQ*dzJ0CZI%d zAtLP-NEhULbbL47l{vWFEmCI0wSjhLfdrSlNn7pLTVSaRMU~u)XolMvd>(EfYEc}- zx-Td}%gkZ*Oay?bc^2>Y7p-$q?9_QC-oJmRk3as1@7{facOO0B&FzMy!^KuPx&NG} zi~X8boE!tYg-cKwqj&AX?rSFlE9lU%<3`LbO-Dkj=ala>d#aK)?W-~9{;wWCC#^}+ zzzXMmsmKCP~YyYoRzGqB6u*O*dy5 zfEEh&q*_eSZe8M1C%@qVGh>JdOK(<9hbE=q1bvI;<#}otad@90usjA3wWwJ$@W+ z4VQk@q-Yhe^$DEkx_qm7OO!J?=-|Ra&)|UOa)DiflFk^U3%H%bv-W90;#?AIGBYtU zai4_|bcZ&bF|gH+J5-P;%q7Ganrk9BSXx+fVMHSKnA8ZYbE0fo$4HZwJ)c?bd-^C} zn7{(YNC?neiuDGUT?bw&;pWXlww zsUoY_S85YWs#-Sb5V2-m^%e=-S6dLu{SVF6%AJ5T1q>+_A&R6w^RB-(aYmcKfnvtE z#>y%nO<-brNPLmviR1t)FuANtkh`CR*H={&SGH~;SX@PLz{(_V(?Bdp9mra(R;uo5 z!(=Ekl}rM3b`9|$M;&O1Ig96<`r)$Oa4nWJ3 z&`kE*9#nu>>QoIdn^?s|NhtxcjDVT#X_lW4OXLGpRg6aksSWBjadh=Z;cJK0b{uux z3emHfUGudXtvmYN+$TJ$^8tFQ0|BwS$XzQp6$L}+!iYof-oC9P$NIZJ`JdHqef#r2 z_2Yl;$A2T4IdLvce-AYVAYRGy(MrblbKCB-jJx}NwVav5E!E$^vQ?1o}T>lck?#TB~+71&BoLF1YZ3Vy{OL-AAn|#<+?OtyC^EGkPu9GIn zJSCvni%a=(k($8u*{^r%1}S%_VLw89;sOI#jq?D&R^I&Xzy3v_{J+?*KX?M*_xLUk zwa<57i0wb>_2W)%5w*wcb=S(w6d!;TXqm|FX5&&8G;Y60MuT_&xeFeD7-vS;s}6R* zmwIE>gCqb5rLgG=%M#7>K#59kmL?M#aCT377qz82klO>%#1iRRPf%hgcT!8Gtyh)J&sBLZN z4mwR-#C1KJEC~ObJ;pD<_TsxZxUveuDg1tjEOE6RU|1Fkb_z7F_ayuKw^{`3`xTZh z?+k!#rMQR;xES4;2_$KlL;U)$|K^7;UOwF3K0QgLSk*IM7!fH2GHIC89G z9O=Ne-h5e7B-w3}aLiSQtOS_OcW6np(G7KZmU_IdA!D!;$J+O+f&;F6sIQvHk0>8aiw#Gsb}E0h1Pgx7W2Zd_u*yMu zeYl3Y^bZdO59_n92@+lxi8asbdPIg(vDF04EMK>9aX|=(;m-D+`Hg-)+8PoqZ(nOF zA{d!iH8FCyGo*aOl$a{!+Bqu$kwV!hxe7L9I7Y?te)6IDU_V^ zE}IZ=*~S9s2|7S^cq^)~NMlw4P|;*@=K;WkL+%EITAhKkB-TNFfPiz=WgoD>$7kkT zeyyOe*1FVnkOL6OJ?4-VT#Rw>Jj+`U_K#W)z7|ku*2yhkbaLJGoGwjJfjj~=1)42k zvt8YdT^N}Tc5Srfk6{dW_S9GK!+d}GH(zIBMw8EbL!7naf;hESynFwi??3%GzVnUW z=HL3;fBSEJ`Li$mcfR_=KX~_~5(D*B4vr*r$<(WrZ60;nDl!#N)g$i!hZDvH%6%rN z0X;AI|5niKeNq8%x~p%j(SW!5nGmmkSNoYJJpH59U{^jt=>aC?F8Y35uSJs;W_F0B zi7Rxk=gu$f3>aOn&;FihwNj|n1x>1X+5{WK8&*_@LfxV;fP0sjV=;_558x zd~J;Z4W7{;nhk;r*pm;`|K3ZhE@17CWq{`ES{Df4wT%fG1MgM3nwNeMWNQqXwCT@N zQ9yOQ(d-6^ivVC-GxoLEV`UY+Yv~p6M=O&AD=fGfEw33QdhIpG!A7^Qa6bDw|I7XQ zrx67IeB{9&JOO|UbMOE89e=U^e$ymI>aj;L1UwwQ0dwt}C<8MAS23|Wcb$x731G8C zSFs=`Y8!aQ=32o`A^;6&qhGUGqV2=ojE-6w-+q$a@!qXCfm<0x|sV5j%wI0lb5oyyz}|gZFGXrCNd=J18biz#xghK+wh7 zciRz6FtjYeL2PK{T399Em+-&KeSPSu103vt$Zb>TH4wI0ps)E3GTS3=`b9trPq!PM z&xL>R_y68sJnt`mD)ejzc4Yg$|QS_p={!Tt_N4MuGwYSGn$+B5 zPM2i|?v_K~gvX^X8L)Xa^d-2PTE5p!tO~#p#JS2Kl%hMAJE+pMd!Lc#ykFB~3^M)g?xzq{KsNCqf1jWixMkfY zUGo^N%4=D?&~w9GP%o&vnR{}L$%<_Wu{5|tsha4kMOb!BZ6!v8SW8e?rQ`_}dF|5? zfpa}HUU#MPx^I5&x(nWbuW1=14wO8N;wpX#0EwNO;0HxotC(XTAk1ab zNaD3`bmvYLyC*8k*B{)s>FfB)!{ zkD>EKXWaRjVL=+`xdiU8?;t#u0b!s!=ECZH4L<{ZhBxrHEwZpI^mNeM(w17>h z?2fjdf$~0Ho1t#Ge>dm+92k`D=hUd2Ksfus=WF}P*B;xsL-TqqHE6F*3>YRuQ&u5Y zKe0kvB+>5=aD#8*vOc&}v=YOFSa*jOF~bv_Dpp$^Tmw++>dtRvgVkjlocSV7czT;Q zAa+aKw$;w?+)MVm>H8HTUqg{!MqiWTYR#w zZNY(&dlz+G(8O0&=ejjH(CUnh7u7ov`g{4)Zkq;-dpD@-Z_~iA|1bW~etk~}fPdBp zXqbrIo=kTS{i^o&-KxTH_36KezlAq0AwGp z^$HgaVlAW|U3NbcEyZu}z5x=F9yizpKQ^ES8`${nv>^e}qs>se3+e)eqYr<`fpq%Qh10OI~~$6BRTCje@U4AhokIU&`foj}_) zTGT~f^VL+pY4uA}(jAwUG0`NK?;n6ESg_%rT}^U@wg9n5uobZqsC!|~J4(X+{(^IQ ztlaT*~nI|--(VGM&Nu<>V4v*-9abX7G&8 zBX>mNgfNf*3+HJi!Z;2xM)WYLI+wTN7)^eh06ijf z5#Ul4D@J(T9V0Ny(3?q|=iLsWo~5l-opSGsnBh@VIl8NCGbV-uEp=aap7+z&NWgJ; z3>|lo!G-&r7&t6zZnCac$0`B`LjBsW6KRgg>oYLF~C|5#UoouQB58!thsc=XfH`M zKywe}=pZ!Y&N9HxZ~_kllXY(8gdLwAj1gCOVJfkBS0LGndl;HCOd|NRIAbQ-CL))R z)rVp^W&5}dthug<2FG#3T6ajJpOvuivMfn;mWa=b7`aiVPyK|uYPA#|xzb(#Zg{gX ztqMs%F96f))MGV?O9|+k<7cwe`z%b%kZ`=Az0OM|Q5=2N z76M!+<`goc)vV!Lwu&6G{vE`eCq`tQwc<)z--z5H0PyhCR>4F;(;dt>vb&5uPos;; z>Q+-msKW8VRfG-t(TbC3LZpCo2gle=IC`EnF_%G2X8P8^$_!{=&vkd9;+{E~Sm*S( z-ALy#z>@#_a%Xl6|7unfr9|QE{q?o~7O-figCylPh?NCaW?{o_krSmflJ9Eg6<+aI1W?{}Qf&p6K$l5ONq$G~wLCRtJl z&k^O4W7#cdP=|#U?47b?lMRIZ`HAbf=wGfS(fJX&og zulIBr|JI7PrRDv42}^W60srhCP1l2t0F;R=wq2rq^Jq0#b>T#*yWhLRZ&Hb!>0_|i zAarwyr5+7wpzdX23cwbG9S%4h!fRCSY=Q>RTS*{w_CvWnuu!=CS<9XI-uAE){tckL zhVA6ETFE48D~31d@3U)zWkJ}&BB7eV^!0j-)b0OO2jcAx{f5sCN3=i7KEF31(mzCO zQmDbOfXV8Ta6g~8-p4S{?<*J!lozDGf6%Il&2(IFo?Sn1zg*|m-~m9@h|gfjdv32` zuQA_T1OILo>(%!I-GJ-+?@QI)-A&@SOW@|gA1>~{e*G&X0QQyq=lk1+zZ>e~!H(dS z^4-O5!od`|N14#&@vcR}c<;J7+kCNS;dWKmyX^k^-sONkOx$($dg{-$L98|*5!a$k z_4_xVWglwSx9N^_1u(WuCt=p~lJ8rlzx`RM^q_)(ixfxaV89Dk-2vGbwF~QO@v_e* z!k@2`Y_0=MOboc&yQS=g(>=m02a3WDSBZSpUGHjk%SIEO{M3g5E(^n!+qc}4etmzA zaBv_9s?`|TV24{)=JbAcg%+LazvcQdXhL8U9N|u00G=L@4Yc4h50R}pXd)sWiU^Lj zKp>q0&n6dk_5iISi5jiMP)|eHwgmrKpnXPt7ml|#)r;^`KmXJJwO{*{U;BUjrN8vA zfB&EQlYfe1{0?_2?w+i459>ZJOzFlC8;~ znuS#hPsbaGC%|DouEF)R7xn?F+;~LBK-C187{hCG&DC8=^>-(t3tY>`tu&AXt#S@P z7~ngH!lTssc#=Te#^7r5Wi`R%@m|vs=iGS{dwuT**;RRT$j6e^0YPY9isq$yr>s~$HsCLocpe_&Rd!J`dP7phk zGH{;@DCg^DIupSmYi8Bc9bhehw99cbnl2#5aED~6 zgFG!-(UxJ-VGfzeDUZJ+iFGe9EN>q;1eLR!Nq54}!qjZy*yqG1in@8>*hsl}T?>qe zhqt~OsP!JSR6@2uwR+}z5#yE~3)boN4sH;%mONuw+}_N_Fz)`o+#NpIq{7(>lrf08 zN~s+yk{rV#$hiu+ObD!6KF9h!=W<7hBI2-8sL&RtYN2X*vsW#QkycvFK3WNI*mnu% zML?`N&x#$s>l(;i^-$nkCrIKLL-#qk*23*}fDFw0f>4SK27#JZ2HkE$YpN;gLMEXK zthvMivWVH~@WGzFjMqizM$FwYAHx8l1Pmb-Q4zKnP|6teI`VyqG7)G6VBnnR1#VZX z3LI=XL55{U0q!n8B1Fs3Tg7eNmdZ5lE^<_Ure|5&ejB3;@4#H=WkD*PO>%cEa+UK0 z*aS^CIGj^tQg^N0Dk%|z5!88}oSHcD4Kn164nZTywLH?1NpSh|*-N`jl4jRkmepL( z_yJatVK45&lyESyB&{Xd3REU_!YVc{OKIIe?-6pX#Brdia6hL{Ez)yV$}*3273?m@ zmib>ZdC|?7o-%Q+J0jA_`ttP`szW)|A!T*t2>JXk)Z9>_6-Gce7F;(it*hRofK^Kz zNh|Wg&$Y;Cg`j2XK9|?!%Wr_#WXYazGLAq+;s{T9K|pJg=luou`@)C&7kK&N1D;== zG0!OmnR(!LON=-i;Mv_xa-q6?emy5$k2cS5b{Mqil8Ay7J@9z95Q#~-yD(tiC0 z)!W9l)dJowdwrB`U|x9DooJ)*B24TXOQUGw#RSow0<|uHuG-+b!K~bAuhq|;IU=xt zv(^1OwSdEI3#krDY{JnK9ySTN$qlrk&64&CcuXtwP#1J9;E&GhI`46JTN&Xi z;B~z%84^5RroBqeRq!=Z^n0)_aNNAxE8)0ay}nfl&WP!Nz^jc?1YpY3X zW3;uPwv3_I4fV=eCS#iF=YLPm3F`6rnhfrT$a|-Z3DD%uR?^g?+WTEV@jo3y|3Uov zJqdvC)kpFBd^aoNL(;5C_RZ+YsMuZdO{UnJ+A-gwLA=zPt>>b%fvJIL(rUcb|oJM=@E5x|4lUD70bPY4jUkXCVyFKm`_HzQR}UpYu#;{Y|Vx707hR($nq0+qduW zt#5x5Klyk6-d}qD{EPp~pZ(W<>`(uhAN$eUC+|P5U;oYD;Pdmd=Caf(LL>*PPO0cE zC_q%F#r9eQO;l8c*ZA<$QMDWm+=rF{UTq>vU~nr>+UqG30*fy%C(iSZsltfBaU?!^ z_p#o8^f5pF^gZ6ceSZP4HSajj6RV(AlUfVOAvcKFlE^~d4%N9@1sdLKN#NopOrvrH ztJpaZLM1Tdb#u*0X3tkIKi^gcKp8;>40tm8pr?)uat!;~yXzSQj^n_rYKws9$lDT< zohom@Z!v<2v&eKNstWrd9?~{7vr_2mwB+m00 zYi+XA`FkUPO^<+NTpbC290Oox zAd8sl(O9Cu=}ilO*21_w!NF?LEtRp=%Tc2 zVPJRd3jj3TRc;lLcKlcnTOq9oh1y-(KG`FHwdng~eX#Qx?h~Ho<}g{;oG$*>eVVi> z0PQ6{hNH`>EB+)o*Me>0VW0Y%R!3AT8yQedjJSa#H0PZzMe+g!UR+*MF$hO`_L1e$ zI~WQ{#VK28+%@mfy>d6rg}7zKkpu1Nzz!etT$Dx8b``&^VQbZr&P8RPrL@98TFMA6 z>FRz$kNlhppw68m(sfU-)m@xBPr#kU<4B)@Rb-V#;VE0*%gT`vDL*I_ng|8dz+5I_ zYWNGG7i6S8*r>}Ms8vux?8hz$)v`d|(*s*xDL`ww1PkYwIJG?l_~|cCROu?;WP36+ z*J^5)U8ib;Hj%COtiE3$q$w$B8ZY{L8dN0$FFF-WTL_TIBQb_a$F&xopHI9ze}OMP zyx{ZCKe+o%zdti^ycrq_M%Ppx8E1^MB$O5g50iCe-9T^wvf{~Sbz3HLC?z^9w3V;4 zYGs>Fqw|w2L1>L;*-d^NH-7fXCo4v#fcnPQzY+iNAO7_Hx4-lGfBa{E^hbW;2fp%^ zS}M%@LUl;22q(E?V+40z(PTx{?2xYS)r$Ih^=D`zKz(Kl z(F&C6i{mI8w*3knZ1*aIpzTWPQH91y!sYns|BmQ!c(PvQR4WRgJt*y=I75#H-JoC- zF#US_2Yq%1DyoSEua;1?-r8$ts|vht_|MdK9$wP<4f_*0eh+zMID5jwey_b3G|}El~${w|;lmh2E_70GU2O*({41!~uL&5L`N)VR^bG;Qk|9 zfV+237qhuIs@$+4A1e0Ng*%{dgMiX5g|R6rCOzLdacn zb@yn0R^PLh?^6I1gDv{npKX86Rz!fq9jMqN2mQ0zofCgvs}^EgJhoT$QW2O8*~AAF z$PTb0U{WFidnBE~szZG|<$%|Fp+^8lgXJzH+m7I_$X=T}=b+3PU|SJ#5Ka*T-@bjT z&p-cwU;ou#{=vWfcmB@*;iFGJ`z!y(fBV1n=F?9;MnQOae$f}tpF{Ip#e=S)#o9ZF zsbO|^(8{LeMc_2{&R-P}p~utW`I?B~bvUP)?0Met{CqacT6pvH4xfDb9`E0Mgxl>& z?>>6VH@7F;=c!tY&-Z8SSEd>FOGxLFvbT>vFaA{H|qYvX&vxvZvyVL0|H8Zr%F3d)P9k!+RSkpRt z0zx|YB1lVMDPU2auq7$RKprHPx!veBUztwYFE|&&=a)%@(F>$Uxa~72^9F@b=Tziq z(JSe$lspo%l}fvN6cMPH&}D`LHFB zk%uxt%cZy1zM3q0j8CgoSj*k)Y0W8a$I+N^b&#I@^FD0~Bac?hxCmTT$N^M&pUM%K zr{_Fhd#4=UwkDda@?I3 zqI)W26UV?jPXxm`9c%UJ;d{KQkjGHX;@T-}8%g_xd}s%Fzn@mkKu|Q9<`dSZ5!E&f zS?#il9L{#A9wWKO!LHTgzf2H%hv+lj0eI{)#Dt5M*%Ni*eMWY1>w1Dg2X?MgTB2iI z4e%`0HSsZ*RWjWqcY#f{-*>qpO;7lcoaLYk6Uea<|CWstdKa4fsE{ooQ0SB9q04iSppwk@O<7I zIGW@d$5H7vK0-Ua&vh~+ldpje-bNEB?0SwULN1-^yb}1 z_5SHCjwA9L-~1MT=~sRUU;mBY`1y0yU;B|C`P2W~&p!FSb39q?v^JdUWc60(!yCsV z2ycT;ppS0ueJ>ik1=tnGhcjeiiG0>kgO?J>otpB{>eYijbcH!FH_m~ww;KiNb}Y-v3ktZ!vPs}G_P$0j+pJhubyx|8qMkNym#W!}miV3?q6`9K4YEw#+f zop4bWSJ6!bI4)Y`>No;hso?Hd(re&026msNYQ-^z@_16z!Z&~WoA{+){?-4{%ggis z?)$&=r62p_Km5b^^s`SfBImci_)a{3{-X1|XU&C{G;S{EO7kyC)gzM3K6}Plv;-v6 z^4~cp=3F@MCw4dFb|gOj^h@~Y{X4w-_&uJEw`PPj_40h@x=-wAunn-R@EBqiGt%5a z0JRnwo^h4ER~HQ67#`=BY2srQlzwIg-JM;v z6biP77XZYdH4QEE>EfyBa6O0;St zQHJULj0TX9Ri74BjgT7aIWcn z#5cf2a-?E_^R)i7PTMF*kM)yEISy{yNeYPD!2S8&V?}++W)7TXFp=`}Z$(GbWXnQ; zxfaIo{_pM=tJaJPn3>;Fz^Y9W_NcFZO__wPr7mPWPGuLLUFA9;Gp(4C3`h{k(6XhX z&o!bHBS{>1dHx)tiN@?y@2P5;^og~Ir`rKZxWC-N@L0TaokmS*V(Lx(#=CY9U6t!#aKFdfzH1?=RtY3{5Rk!Wc&rE7KV`?z~u= z6DBCSHGdUHh0>Y}$zYBHV0o0*TGxah<-&+3%qCAHkD*He(;89}fo-wa-G5=D>+-Wv ztJOYMLs$v{k0~Uu<}$Gmfw_cZ&>q^|5$|U-5|(WPVB7M9?ld*Q02MHW)n}>;^6qvg zp*r2^@c?vp{}~;q+4hVM!BZ_{a-R`kBvi8jau+AEQBP^*O3-_w$`cNtl91ezW2T8E zFfWO0_%VJ+!xsRC$cu_|cT(Hej1JoE!oL&xK?nWLI$a-)qnQl$_v~D{@|!KpZ4>T& z?$PW4wnfSLCG0cHJZV>jC1$pDMrCrKiY7y|Rf>MWRci}(gaTbV&L$@MH6R@FL9`V) z)io)1$99%&R>y$m>CB8gP$5snxt_P~L}r*gx~^o`uVHXx<)zh}bKP6W;9Xd@?{t0I z*B;K}X+{0EaCv=XhqA6#^1vfG84Dsz}vU)*2kZG#3cC5Z+?qk z`})`LE5H7mpQGyk^yz0G|L?!_>6d=(bmkqpX!G%wC*Vz4#27-Wt z*IYYn&;72K-O=~GHyCfw*Z-}4PgbEq9_iNip|Bo5R}C7q$*bJtt`*szaaCP1dB03I zUY)4mplgQ5N9^mqAN6X5cqc5maL zZJBUU*JMti6>)u?u$c@tmteBu^(Fbk{`Ea20A7FT>%aRyb{em5c@qK`5N-foy5#a^ zMeCB&lhNJ_G?+6Wbax$>EWagR{}J4!E<*9 z2<(hA><5>>H|XWyA*G z{d4M0d2SMD(jpTx@1b(5*nQKN|Ir-)CD6Aj>6_*>XWN$uMBV zx6|JNbZ3?QgB$ddzGr?7d-j6;iCZm@mjb{*(^6WK6wVW9Wd-`*#y&jvm_&A%T6aS>Ih z_~f%s{@4$F^{f28FMt2~*0;VLFE4izrCG(KZ4b0z&+;!d{lK=v0I2)KSqslEFIDG^ zjMTf2-|@}u4LGxxk>0$yA@bmw6EF8?taCazEV>gKE?9D}Z31lRL6t+Mj*(D= zu$G5G_u3p(=Mk7z4Uo~`z+lD)OVe`5JTT`=cPIwdI>8vluv#+G#jS%O52Fi0PFS}# zOc0|tTn7D|G2N+!H|aoUQ$U!Kjxn%SAu@Sn;GBYEyu2T{(0*#Q(dz3GSBGFkiU}an zY3Ajw96$wg?ndIze9y+y+thJYd$eSgKs8jP_)gN*o8O76%i8)7c#w=zAa*f;SXA zHjLbgE$>&;*%Fd~kzxhG3aokJJWt)8ZY_}}wS6goJ2^diwk!ozBpGtobFJkvBDxq* zup~?G)j0TKxotRG=fpVN(Ucw}0O^3ZS^l$F)4_$&DiR25+P>y4b7ADbJbMHo0cn|N zD;JA<^2t&ma0ppE&lAyO8augJP!q)Mq#*X>mBM+JB14)*q3C_5<)a;B>sDa{OMZCN`BeOfZDCcQ0oIwJ) z)5Yx*7MS75SQ4d)(nUzS`UJS(uIyTcbw80u0F^*E!+o8nrzikjD0{j?p|I+XkvCWl z?}BO<=?z{4MDM)-_Lx(HT-k!MkU?53<$DxJcdy8*0<}u06&i`rIY4VUJ$;HI76T@6 zxBNLkFjCTDOBzm)%cK`tZ07*naRH^Pr8&KR=Av3hJoTst7 z^?j~S2SsAqJI@_{h6s6YAUi|C&zd^BfmSzAg^CbsSl8URiZtR@kc1L+(#96(5OO>zY) zsBlbclM+_z*eQ}2$H0hikYDd#^W~10we-aoA9#Pc<9vC+&Z5A`8sh+hJTe$LP;)kb z_F<|Ohy&0pbfJsmxZ(YqC*0n>t#w~`nfLQo{_(HsYv1_hH^BP8{=k>M{J;L}v-e+r z_x@w-JSUTsu4h->8w(6N2HV9wS0CR1Uw;OrW zA%q5{X!QeY^IopWYfJLoF)jho#G3Z|m7mSs-`${I-xV16ib&`Vc4=LtTXT8vtN5(5 zFtHj#Z)986f2jKP6TA}@1F~CW0x~gnrLL~J#xrgU(`%AtXY}@^^m~J?O4UW4K>&K9g8Jv# zU|ejHpG`hD^Skk->w{KKG*Qx&!L@%_<-o2HTIHrql=X22YbMvdrAQO zo}b_qE3iA&JCI{{(JUviybQ|$cDwDd7sR%s?}ZtWt$<{Aw9$;z_L61?u=qom*>7fx zyJO9Z8ME`NJJWFS!baucF~`39fWrtIWCK<*Xotw`vzSEo=qd!UL*xd48D2mJRO)eU zySv^e4jPEk?5}AuK7#q0o!T~t*s6wXbpUwf3vALMzzzv)b`7mCU^Bk7j1Uci zH#w1;@j_hkeP7kss{ZdH5bUNfU}km~9&EpUgC()=ms#&YqB1Xu>1Ln(dePmzzGnNr z?E<823T#CJT7`i9d7?Y{v8@U&m>f#f*F1qfitTHC{qHwvam{I9e@6S{IY>^vYA zavV7Ccidl2eDj;%{OWIf?N|Tu%ZKyd9~uAl5B}g+Z$J3eKVD$14dxA=lP6`fwynp>C;a?;nSPM`}d#V-J3T)aBAV46Z5>g6F;NF~J6u&jL_(g1=XXUP$JUavi?Gze$9 znC$Bc!G3HsyF4g6=d**-O@C$3Btw%Bd;H@L$07lwu*$_6_7)U@D0w`X0_awj6Te*m zdTgM>3ner#a6RYm#nMxUd4@hB;3~cw+RNCLANJqF6Pd3M(rqYFai+ z@!DI=qNnpG_6$MaK|l8+uit<42+f{<{(PRuAjUYbs^DSa>245BY*>D8*=JIaShYmt zVzh*xLSIvK3oy|f?M6v0|ZS;jxxh7jAf^ z3bgb+MoOz^!U+%x_jy`IUucOa+SZh|z_iMtbRzQr1l;dupC7`!Puy-dUyG8-^lBAE z7HUd}N2uEF0`^wc()iKOU$%8b$Rjb&6N0BHR25cD>_?GF`*hJoG!`Nct#wk>Bv|X- zj~F=D-C=k~Ua6KcLfScrn3?qJ%=}sjonY61~FdFuL4OtE0ZggiMp$qy}Md)?I zqr0wqfTwGClRgA6ms*+EP3Y|q*;5DR31UFYISi{`WrMj@wha*m-|IZB;OY{-=(*+= zlQh8St3Xs|MlGzh{cF&wlhDpSC}f8-3O*y8>rkDMvOy;>B5~f!3V`cg_gT@Ytc3F$ z{1_KEP;*H`Kv0zs!wlwr{VSZB6vJ5vJKona^;TfEWn{`8|0n=S(XvtmJ*fIi98!w71vW^KG9miFuRnN!h8vqG@L4QG6;7ZhGZ@&n0I~@{*R7X&p|790 zhbtG#XH&K8zkj~2y``+=YEn~M?V;6*MJpuG*R01fL$GS~Qc^UR5!bV??M~ZdG_KqQ zpu-FI=i&7|_VcA}4QY_B>s6zP6|X6)GQDqJ70*RTbahbG4P6ri7e5gJCueS@$ll)w zv715r^)_eHXJ%a=bW6*Aw_pDZLg0JA7yRK90Iz=$29xkZWI+E4==XyU09!impS8>` zqYTPu*2};Pd$W9e*(Mkg*eJ%GMfTxDgW`PvwXVMx%s_;LhGJKCjpiHx;i6c(NV^&> zY{j^{st_JslKp3w+zS_|_Ro1?*>l=mb%g_p@BrZK4m$haNBdqICHreM&@aR#bKc?v zTp@l9l)@u_PzfHwmfVMc>Mp(2^9iJxWp?*b`*oX8*s_1%VT*|F>Rb8TUHHCFiomf! zpW8bP*xBEOoiuAQ;Zi%ilKxxOKwwMw1K2@_#6UaX9-aMueJ6(-NLF|1HhBP9*&z~x zRy+Wn@4P2D?C-E!Ndo%M`a4KaL<56f1IfNNRvwH9eDU&(51)VMlv=lT!+ z;$Qf4?>_qElljHx-yZirjA5lkU)vFJO|KCH z=+R3xh0%7IN=u$Q;77qh7t;MKw(q;JNg@~S2Lh2Hc7@eNvZ}U+)B$D(sJIOV9m-V_ zZnx1gIT^?f2b2Ye6iysKA9@*nk3GgmP5kV1@sR@(P<1w=>_d15Q|>H>?BGaA4jn{$ zx7E)*oA{p&KRW>ouWbp%y-w8!XU(#lK8afzRM#xT05Wb(U|Moq=R_rZ4@)MpcBden z>h3VMfq**;F(|FYC206YKy-oaP0e`>Kw@b=*U>@$AN1*1s08~U`=TV~^B^%*1d&~llfq*jx8gN)c zF@;JY={YU4i`9^z1Zpm+uk3R?6SWrR?CY9DjF8SrcsfK=1x<@Y zG{AjT0VQyMK9Pr2U$v$fNvEmL9{n|S%Y&7~y8Al2v*ZzVMSvVF^Y-JG0j?4p+zJ(C zUk_XtjuDu18NlU$X`Hkzah_I0m3scXpW6Xqtz`vCvnbo|izW*gX1!*&j2Lpa+@@kI zj{|VVN;rIy@KJAetn&msMT0 zJSLD#A8?umhJRNKLX>7mr${Va5SuB+hQlJ; zf3C9@Q*4Wc9)uRXv{e-*tlAzVlXvPMw@iBMS~y2w(i4{eKs|-V9d`C}>RMn{D^iyC z$;M#1?>CcR|{BRi%E@Ct{ zf-0H}g`l8%lw3HthAr=w*|h4?usn{mK&cQ(xr4lzIgk-nxwIAY`Q@(r{p5E(|2Dq! z?a#5+Y*Hui@kj617cbBG_RU*-^^g4ke)U&=6~Fk8fBBbx;49z%Klp(!fB!#t`|dsF zc{U*P{nu`^wNL8m^b!{U7OXU4s}CJ~;Ci>Z24I`yub%Yv9C$9%8MS^>Fyzke>J}@!kY@pX@{tp<{ z|8xBMBR~K=F3jsob---+D^@M8_+zs2w`;U-B z_T}J%^r8R#mN<@aU};8X)Ia(9H~#p~{KJ3r_y3Lm=6~bU-~6p_)vx}_FUQ9peT+A6 zp77bHU&1G!eTt_yw~HxWYoa>bOkIpwsbEjO1+4xYyXbb3#GVx4?-Y>b$n3+gyP-$e z3V`S}I?@LqJrZbl;37I~%0;oI`~+^y?!>Gng51FahJe+xx}9_^0pl3nxT#BGwQ6DT zfChmMjT?E?tQo7S)gGfITd|YH1tv*LHb<)kwi_e?}>d2&Jpaildv4SMhY3V?Y8(yC8$ViMMQMH;) z+)`BMc0g#Uql3<%z@q)-VnLJONCku?ab#eXGb)w}m@XO|*vSStUWcnCb2K1UnF@!{ zN{DIiu&NL|6j{vh)POa+^97*h>M@Ey-4~X6iorRZj6D*`z{~xPK&V25aU7;r6Lu-| zY-{GQRiJ?5ux;gB5-{2A1Mg=bW?MVP7^u_sm`rcPCL+S$t%^?K-!r^@;+M)Y>?$b+ zlTHNJbf0BKAv;51uG8Q<5BoyZglY9W>fUc^Ri7#H7&=du(844N7jRzc{TyiDcz1kS z$+7N*<2D2oR@Xb8&eCC6VQ=X=?Mk)N%msFi*!m_cEnvZ_2bqEkd2hf-XfCYj#C^Ao zm+z(6<2)Bu5l>IHN!;%a1sp-FLQ77i3Nb<4*EB)X<5$=0j%#}7uid@xvrl?aeTgeqZ^h;Y8#P2`Qy%GS-uI3J)^?MDQATAIO2wigt7@;{=i?AS`{aiik{X{{mcnR9LVGFbDE(M;G7fB_o;cGK%kyKe26c9`OBQ= z9e?w0{3rkKAN{c(`?r4J2fkk~Up#wFHqu=UsNEq)OTl|pbXQf?pYt(;uYZp#MA6sV z-$<}eon@K-?yCDW3tN=owcUGp%kKp>xV1!Itt>VvP}`wn5GosLu1tj8)?Oy9*&nh* zt15SEeKi4>uB%$`}!@R$TL_uC|*Nt?C|0N4E$)#@}}d;0FoJ0**~2i1lDv>q4^)dX}me2f#l2J6}Y zH+f*TWPdkH8=5lN@&ZdbHlJXD0f0;X^+$vR_#;37Jbtynq7RC2_jzwrD1@@RJ-d@= ziHQ$4FV>5-F%ox3&9&K~y+iE_-yn_EOs&K34A$cMEZBbNmiKR<@4vH;C06^Uu`bE7 zUL7b(A*&O`dkJl?WiYw}vLP=T$O=2N!0N4R`~qxmzQqaI3$T6rjV7;=gv2F{7c4b) zVGJu3{9AYOVKi#%KwJdF?uwgq;UoD!0?YzAT1siZe>9oUQabD;db8U;*t$h%pr3`n zxRe@9UIhb%W)Bla+bgr^DbabDGLO;rh*18?8G$4~wJ zfAC-b=C{82pZ;5a`M;;1|IdF}@87+Num0d4!>YpbhYwwguI|oT?wQd@4Wevo4qHh8 zrJtD~6dA19jOA6|3o+6O{A;30yp0>g>Sl(?sad@qYC$n@yQPD-;6N*6Kxbhb0p-9t zR}(VCF$NG0DynlKhSzA?I-oICq|QX_rvjPhg*5Zx*mb zf3-M0sKKNdE{6l%F%tG>6N`vrAOboUcnh@}hdtxoIon{1Q;W!_o1bT0-KvVX#i|of zA&&%J&n_4T$IwoQj_B-TMoLwZfKy=$R%onGp=2=mLo7aX$u&o;F~= zdDZrPCpcOv-G2Up5E;Vhr1$M>G!U2&vb!V>yDNwz;jU*(Vl(KVtrBt^Af+|MV8Lx) z7dAOM^lGka@A96((yCAspKC2CMD^H8!85kmBOt+tw6F($c{F2sKXHffQ5-1P_JIQM zux$zct|oE|XLownG{L};PBg#d_*M?&;3X%I!;@9&z7WIR_N5*VI;TUz2-G}1qdmw? zIPAudM z++AvEd_drlU=?2G2_i(#Dgy_ENix|ZJv|!qysuWWv~Ra(r8gw&&Kf~(YmCqNDz!Dj z#dRSRtC&wWNyT}dXz`8jza??l2JTg>2cq?BnXYQ$5PQOg78VBr$^;5H&pT=@jHg?V zjGR~IN0pGlno{sp#~%H*(FzOz7)NSK)HzLlwN&51opr?&6c-W>Ih{2@*vGi0rRy;c zKMUc{E=kPfoC_m++Q@SEdeuUJDq6<@#7=SUD$1HAd2X`{tjL`rPeW6;| zF1XHB?-7k_Y=!9=@LI5{lUU1k2n4X^*(8!{JOk6h@CHW6M9W&XWQoMmyzHu(i8oJ& zgy6iNC`mu?{a@n$_y6-ZUfzH5@t6PP5C4hJUtT`+Boo(fS6#0zN6LVoi0;@IcIe$D zhwsZ%eI8k1qb3DShV+eU5Z<7(RRC&9w*hipNUST^lYzZM3O<9kgjAUwig>tgV#1tRC`(w zI}FqHMWgd_qav}d-(`YvJxpArS4)bpO+@HV^5Ba4n)HwIv3Q!0>1GRnJ>Kxbgw;g; z^#Jt8EA?mc?pVF2Fx=4Dml#oqdS&79)oEO(3-dRX@JHs?_{07H-*rLyH!YfgeVu!> zgbOtUt~rakuBaab6EC`6uvYX)4PJ5{YHywoSq6KtU2G(Kp)YV>B; zkIMcWD3c_ck_r(!n?alK!S;kZjeU16E|o~s^*~=8_v#|DmSyR*M=3+yy=o8wpwrZl zq7@twW^SXYqWSkefig0@paeV}hmUiI`q(Yfg^&}f3oLQO z4ZH=<=NCwU<2GRLzqA&}u@4_HAs|MNp>$`v29S;r!<-TauMxKBetC%zvLYnYpDQyk z7z%)6hr&sYIVsVWmcW~LPe6%t6(YhNN;n)YI9TeKDlON;9$Kijz+%wz)78@rt0pkp zjT^^x?V{wQ{^8FuB0+eng!d9EC_00&2P_2{9Izi9hz<@3CK0yBfW$i2MckTb^LiOa zfa_r)f<||LJz)VAtfAg#c`1odVGBifUKWbxHV5($crNhvWGOXilFgu;w<9p?bbwV8 zq}eAyym=$lq!p_rU|4iQj_RLEsobvH|aF-)|sbE@1m53TCmXP*;5XhKZO@^1s98JXMD6SNlQ zePW)biH-;$0#hdt)09mn)|}{pCSDhDXaG|{tiJ%P1kQP4L?Dl&6WG;c%7KXqox-^Jn$IPSk%)9E zeHA3Lq|6*(2IHisnDm_S+nXnBEp*lC{agStJ&a4^ckfm0Pd-NvMK zE;(edEoz10(lVff*@zK|^IVa~z)18n762!9PcVa4CO8#+w+pS{8Ut$Lc zVjxbSEr`20fJbLnWF}h)M`a9OolO8yJz7*Kr^qoQkV~i=I^?8taIi3iwx)EG2@{-w zGE38{KyN#em3h?-uv#V*uNp57Nz>nGl|FoN`t=y++jsBz`R58M}VRmX3ElT53n|11}hCZ-syxBd$@^`*H8j*j;3} z(X&T%YWJ_V3c;T#UIFg?6WX>h^}Pi=&7uilH8$ERPcU#e=fVRb1o>T*O)~}qT2LGi1qXQX>h?dcNl5{sSdOPqh6D%q} zSNnbkfr-u!5!^8317Fm|>B&fFcj2!K;dQqsD48fQZgD-{lO?+8*)tKlj@kJSfVyGr z%XCoy*E-n@`ME-`zH5!e1$gB3|G7>61g9qXc?1rTL$yT0GG!yspzqZ6k@UGANEq*j5C1UypFzx z#Oi|i>TLS~=EEKlu;gj0cAPb!CT99UMfckE>S5g$h0fBAGO2*g;fpgrjd44_@})2Rhrju2U;Arc z{bN6P|LyO5GeQOCa6y52sSo52?Fi@YFdieX(NS(1EW{aD5kLtetf*iP>;{U3kDY69 zSS3<*TGf#5C@~Y6Y40TJl0Gp5tYIRhL#Z~11cNkFg&YET04l_BL+SMCw&njh7z60A zcx+o`43HYo?37)$BBi?^345@YfN>-MgRqiM9wUJS z);hHonZw2yj%e>V?33+avZuEvhZWVgyzt)>=d+7!vbf3WyLHqeo%2 zO!FAHr4Qb@PWyh7&^r4d48##|wwn+%u@i$(1*T5LB#TRoL5?OhXO9ppxD#|EcJ6_% zsfm-3!z4tVmir$ASl!=DcjPG`R$xasg>>S8-&Qe$Dd2+y?Fb$Z|7+MVwO zVHgZ@fJ07hte%t*F7}Q{@NkHg`Jx3xV%!E$WJO}?1d$qJ@I3D@oCPWd@`=DK%xMYc z;G&fs32fB8#8^joc z!(%l8tv)LP^JSujCyK`r4%*WMk;nwj`^j+|w#cjnXPal0W2oO5B@aa7N}&p4Pd zA`pvBl6$kb&>$h{VEzPLX3EjvhZo@|-8Ih&RW;%Pi!rvtm3V z#i{UIt-u4vF`PpIf;muHI3ffFtDF(wyp+Yr?D2mlP>w}_#1V;lGdvK)N)|0ma@{CR z#7K@5w5({@vRkeK(n_2$4G3pjj}q>@x{D|v=y9hqc^2*c8OJceY-DQxdkj?fvphi{ z5Ke%=SklS^BfvF1yTQ*l%)4fH=+{Itu>jnT+oMxS0wl=*tD6aJ{nCx@a>`(}j95U> z;6I1g{c1A2<<3!w6@|e8LdXmUu`R1S?60>qCww9NSy{kjli$)@He;Q0?tpGad3L&$ zjYf_ciHQkVO(fq@fSxMz@Hz*9L8J~7^wSm%%eJdK)-LiF1e_*JZ0B6iR!qZ6v4SvX zA!FAO20ol}*TBYnZ7Eu*6k)gXqCBdBM5d=&RGDZq-xhQh#sbOm6=~X9j~Z}W@*;q> zii6=ipXv4Daj1gobTA@;KvDf1ee<`+9m7`*>ernN)4#zcl6J1SWyjr(R&@}ee`N(Z7$w5R(0)O(>JL4*>P5v zXJ=s7yba<#Z{GD{HQ3$3daUqBU+(X02)+QrcJg6k=!Ts=;nQtDLnKa;@hk-o_>UICN7{-4Hf@)dTWg(0AisUgXsuHXZOi zBmjQzuez^|TJj@A+YfAufe~8n>K0J}B>OOi z7o>Ni?(Tcv1knM1Sq&n3kyw}Ba}VnrMy>ghFkSuR& zIVIEKj+KPg!VdBzO`u31%5#V{39&n~BQWn1Jlk_0ZI3G8NTTwoL%m$=FF7&%$O9)A zYEJN$cp_OVoc{+Qs(pwlQ9{O`@Bhu9s|N1p9oo2Xt+pQp^2lZdx*O#o#@^3I;1=nw zN8l^mb#OX0&>J|m8@JSFWdn?<@ zpq3y9hctsqQmg%qqGz~sqGpN=W{!G|6;`^)4kdUbstR-Y z`Q`MXT@M3>kg4dMu5mOIpuBEeDPYU1nw%$`nR>&7yPxR&>D(s@CX3kyUtI0k^V z5D~$)TOvZ)ihG#cplV)fyrAfDvA|2Ug=V4~0_*_Ahh&^ZpY|*UWg7&yda2h&IcQp}LYLsGV6vSGk(5B!j^qam2zo4fc;rk2hU@T@so$Dm$;KLQ=&-+1l7r z>@9HzsZh}={0X^*%Ox?0mZtmcxsv3|IWNvL2^c-!$VP zT}1n?`_(n&&L*Kyv9Cw>tNKT;xr$vcUkpL};sag(yEoL93DO)l=qGA$ZGG2LkUF8rvA>mXr8#Fp7J zdca#-1JG~P|IU`mwsPbmm9QeQk zeZzmBzb^LR59HS$f(77re4%||T26go*NgQoFHrKjfZ7+Zs=LI|9xg9z6Frur?{v*n zxa(Z%uC`yBaJMiTaG^nl7eKWa*&lR=mb4Pw8&Ibi#?9GS;cIb#fr;Ay4_cnW_2FB{ncyCCm zE^t~726pg8^s`h3ZL)O$e(Ao34kVsks-PLG=Ppc}V z!+{~#8z1`pH~8&5g>1=IK2kZ|@z+Iws5fH&Tt2!eXvX|nqs|n|*aXtvtUKXUEzfGd zwk2)e?FBQGR)PCa+VVU0&cv+%=(|l>)~xOjwwhLqf%9J995<{SH4MH97FI~LKs-8Jc9LEql`{Ii4Q3ogiV6ZQ)$4Bkp&I|!OkTH=N zEb_{QSUpn6U%PhQ=6 zA;M66%j&>>URQ4zsdD$=vL^uW%w$ScE6DT+BRg5_Rks`;$)U<3W?*CkUo%{K8c(b? z^HTspg%-s^#88I4>G1W$XtM7`3j_V02w>1MG^z6w0_>4agV7Sx-b-2%J6XzMAhN?g zGkjevIh_U!xY4!)Kj$F#exuBTnZdO^k8+-YEeJN`Z0pHRrzfonIr0fhOUnU`Y{2J` z#Up*ohFkxq{ zA8p|nV~2@pEg{Fjnx2n-Jki~pSg0wH!?OGc)VZ4K1I~5g7(=F+2bDsmyYBb9dJ=|r zTm)8R>dbmYy-5+(Yy034u)JbL2CnjoVxlk;3w)VMka zU;=i&ya*$~2v*VUSUO}ac>vL8PiMuf@>RG!dE6Ryp(eG!hOodpdUAoVR*5V!1M{31 z;qijiimUC0E!q4paU?4tP+!4B@_Z9X%$lpE(lt} zIEF?9*8OCE4oJb$L_{g`Am$|EP_X>0$=X8&oUuZmw8F%adM_KuU@d9W(OeE2^eU#+ z3c^>9lA2}sei(UG7>J!As5aqy2=5Vii zR!^x&IzLGogP0wUkj@Bc>lv`6_!IVMCx-7IWLJipWtC&_et$VX`SjCYbJ@eFP-&S= zTP+=5UF*2c;MEXuQv7}tuHqk8KtvZY+BN#_N9!T64z+5s>&qQ1hxTRrZ1nR0s8!qz zJk=d)0xaJP9k z-yCCUm8N&oHcza8VgVtK*lUb)DN0)zpq{{DgGaL~jB9*eZ?+dm_v(A(1+AY9if!u3>ZD}k#Pf2Hb>*9Utn>9r2} zwM+&yZ`acwI_|X_%EDYtz*Ae4+F)z1jkpLX?LD+HB)pe24fCk!!EO$duauJ;tm+~m z)H|;pG{EoU*B>1C2mVk9fbRzX{*%6Q*z~|Fl3-uQ0z7i3eHo_Xd@=hbS~ul?W`K4{ zetTosWCIN30e7&L`Ldl*dcpMu-CLEgH-Q~$vSsIhL0~ouY1@t;IQD1XhDyMGNJ>~? z;r4YZbsujhSzf}Mat9x57m&hIA+%KG6{7|Li}t!u(S%AbyJiRtOdGI|>RF~vEpGh; z97W?V#(tO=aE)IB+8)4`|Kuhunrzq|bM5=#zw-rYKlv)ups#2Dd!b`plx2-S`uyh6U?M3$h)utOeJ{zblTQZTf zr$KIs8Nkb?jJ^gDwkddT(-pX;2C#Ty@TKqj`25ayKF{0jR`1`u zE%XS2q264=_smUfG6snZsESVdPcdm}G%JP@7!E@k01&BUvM_xMbpY9*;nhy&>pBnt z#Ms^V4is9%j_&J8;~-KVdzWTYOgC84%xQoW1QHcw%(gBZd28kdPO(=R$j?IMK(-8& z^z?$U$8zoPsUpF}NMHLK2C9R4MB?e`$xBoVkvG)Y696*61)Q^(X@9Pj)*Wnq^0>p9n`pp845m$j1A|iXr2k9;*1l7QdyS=Ft zj@y&8illd>qEIyvBk`2ka`9wbYOO98n67dA#Lft4kL!}4C8;J?5l4`5P-}uU7sfEj zIP1ild;>wuuw>bz4eKh{j^pO+S4?36=$E{#XJsGl;uaOP?#7@JdJ_-Gyuyt!OI3>!z`FG@au!B zuyEu7jt6L}DexduiHsz;9Igq1Opx@9c$k>68+q+UqAg-{lxIm|gh^twqALawfnnPP zmkJCQIu2!nl4J=imP1D)M2V|_mvzR|ar4~8Q?`svLmFyQ3S`*m15|s9C6(;(lu$BR zLja7xo7x8u0 z=Cv%tlSygG0Wy0`G^~TMxPU}W?^jme0SlHtyE)XIDT!rbUVwGh9G#W0I-)MbHK$3W zv~q(G5k1jH1q@-7wSiUBwP1uzN=b35K7Ri$zxe!%`s_=e0drx;p)p@|snwIDd{98? z07&|DbUoeyKeZ<>1mHREiB9}Omp2bl0C-IWaG>Gp>yJIn6X+1SOVTfQ{CAD2?VGO+ z_TjStukc7cU>mjf`X0%>Y<~i5`|v@tz4(DkUtGY>z=AJ>>+*%}%(tq+c|{)m*|xde zwBJbDa7oy*`C3g7XwwC4PoR}3XvG7hCW+d^uUBxijEQy?>v6}ArdaKt6A_&+wkMS> z=$g{dY%;2&UPA`tk}jNJxYEk*)oN$JweA9{n`Z$N!#jV0eN8D7gxL3{yK4Ta$9GS_ zN`(%23^Nj5NZrWX*U@;z1mqO}+PUa#*uVCFH!h9NtY{+dB0aWpxWDT4ORs;&-|?5f z^Y`C_Uw^nEfO`EOyED3pynyqzPa zEJ^PN(BQuM_2W_y?75aE&x9SM$GuUZvBqY8*dnjZAT*#5JQGZ1wy_vpoVE-a&CdG; zU39o|z?K|nGySx5TqP^-*m$rvwoM3#mgZd^ANZkUqEkE#{P)JlW@5?5y+PM1*MpP~ zplmlmZyuXf8!c~SADqpaW*7RF>=9cw?2Vznzj|{HdNW8MV)<#j^jXmx!y}k6)RjKj zfO>CU{pZ-%!w1e@Qa=3UjiiCDg97{C_y@evdiMtyjxN~YX_06>B{mgs5fkZ6$-Buz zePKD3*G#7;d5O1Gf_sDQwaNm%{hiOh`q8_$SZfuklJ3SyQ&h<7tQ8J{-uDX#CYBZ| zig^cgw4$aZiKa3ZVswiB8aRjs3%m~9Wb|5Xy<-ICTFOq2vCp%KIT9l&D5;UQa0^Ih z8=2e*p?K>NmQrR$6g(>&TTZqM(uK&t7~YP-0bn6GP-|&;eUMB)Bk~~@q@}_Yh#@5h zM-EZNvlR(>JXtb6(gi6Bc_eO`sKNfK0@e+Tax!^3B(HkSB~x{PDPoL7)$*erWK~Z= z5FJ>SWXaOyaU2j5wN6Yf#9_d6&Sfy-Qp2g`AdW$M$|2NgiQRa6gQncAVfGpj#&Ls6 zc=>SeXS$GUt5o2QI>YNy!ZGZ(1B5x3GLi-R<0X%{QnE8L3BX}-_jw0E9Be@HkwEstUIwv3E7eK3|WzTX3*hP}8L5k#E{=)djBX=@oz+g3d-S`^>0? z)rBG0mY{~Mkpl~}J)o%^p7A;bM06Na0&5mC19`XxRTYxA2D@I9r2=wz{`+*`(=n`O z;tJ$A5V_!BX%VY%mz58;eh{@zRM|J3;WY0m;Jlw09n3Zt0H!l10vgFqM-M2*J|DTm zmRxUz=qxU*({`F1hr2u}E2Qq;^H+n&E#)GKb1jV^Glp%O1aJ!I?q}ps%*iXrwB#c( zsa4jfy}T^kZh<4I<(X?%jA-GUcSR%*18#%((>0oCulN*k@IXkIayVW>n1q-li%>1p zG%fEP^U}d-$!0w;Fewqmxk@#Qw>M87Dp_= z*>!{7d%;MdY@5*S=QY3_iCK3&#f@=$LalWH8D=0b{8~vC^Ez7YX>|x`>l6A3 zBjFCNp9ZWo1r_r+P_wXP)lEc#PXV3FL44&5fkQ;i)dj9QfDGWA9)H@U7XV^X2&{@^ zpu%bI*raZF+QYJ1<~(0O1a40^YE4Y|nGGWXpq3|s2q1S^Z^?bamWM5et|iTN@|FXU z)Tm%h6Ze%wEPx|SE-XPvt<}ndUH63;YIO+UX(rt@nzq3>j>g$GjH=GfDXCnLjU-w- zz&t#vGa5WGntT_lO3ciLIps~N=C-N96OqChNE#(57*BMxDy$@_4!5=CLxaK7q=seX zE^IAb3pAizkLeRZ*4py)viIB45VSSb7+lqL46!j}WYQt2!+U~{Ti6cLV3L{1z`OVF zZ*@Q4D)=pE#uN&*CsO96yU0pm=^DSk-NUNnhjfBu$xJ%9sFJMR0G=U&mM^7>a<7fF~$ycu5uz$cTpM~ zyDk(8i-D9=I?zp_E+;L0?~Z$;>;{`^<=%$u{mfN2n6{F6IcLFfovuB%I@&jO_B9~@ zOV_J|0!&Ig8fjapYI0s!;eCG5)Dspr+`-OU@HKM%Pw&$`c?=yo-p^dy8mx>1Z0`Y( z1$C|mWa2Jbb+9_nvYJGB-A{LEYE$mw9*={)`jt50&O|XP>;m)brPC{ z+vE@ht>`tVel51enGZbwdjb33`Dgzu@c#!u5WFG){#CyE@Bg(Pl86nQ@p!`ew*?@w zy>#5(@Yf5Y<(;n>Z7)8Lu%NeA??}Sc!6O%>Vb&cF(7a_@s&b0CNBlTcEQs74OnISU zgXKa48NLG32B^83ouVa5TfT1#LT`YggKEPvnLS$L%IWaS!sIKi?*sN6a{%q`bs^Ex z|6-u=Wp~5Owqms{g0Eye6)llz1%bKTE8q`dV&vLTn{KU5j%05ds{1jY)>^3l9r zld&zRvvkUGg1$DrB%;g!0MOBLuf@(y=>wpF{U-GGv^P{W!J-SttJhh$7Q4X89yJIR zQ~@3h?0XUJROP*9**BzzEn^>|RncTgucrpW9xSEnOH&51*Sy$jHln@xb~H3w+u?k1 zB!2TZe)He{;eY+Viu-x5S;{8|s&VECfT&aUw!%cl>=~}tc)vKLo38oLB_huS+y(-1 zF|9#}5iG$0V{`UbVaF_llaP~uZY&8$49ucbi+K#h2ypdrO>~@O2_Ys1YRk?GU=GDd z2IP@aPS&%pDu?F+gQ6*McUZik zf~P#Ae#8L!zyd-elkJk?F^CFi=*BHi3WEemE^-Nv^SZAEEn6jG4BhWDG6OLl-S#=_ z%CLY7WzYx{p7BjkhuKCX)d5TNZiCzH4I&KM*Ydpi$W|cO|7*ljOB14|L-`iuv0^cl z2btBj0y)@BU5v#D3`qol?JuWN59aVgxWf5(pmA8G9dUD@W!QL^hD3yYu2=E$TRu;ifz0eR|IJ zc!JhRR^b>&7k5hs2N5Q;3QIQ(XX;gu8Cd6unjPj?YYWeu-O>SDWfDxs7(DU-4`RMd z)f9umadQCYTqoR5AIM`lpi!bd?A_r4!4xvn6DcHCJQN#*YH`L$wm(^@4BHK2JdSwX zK_&)9(=}3*(MOHI4Q<2I!mR=m<@*@vJzc~TJ&I9LP-{pwiDelt&5Ur@?f$yCj(KV1l$UW&r*n=2}bp4iusvH8@@Ca4V z@c$*ZO=^=kqYHtC`duX{2M+;@iKWxenbLrR(cQ*{0wagBh32w7YY?1mAdCQ*2WolT zoD&OrDyas!CbeppFIo_S#VRTpj7UrgS_>J2RSOMwHi<-HHCVEx!l8{osW!ax7}qYG z^8ZiWA1vFpB}-zEd&HP)pPTo+5~^w-lLU>T3^NQf%;?aBFW@`*82trJP|@I3W}dy~ zhzJ_)W3H1~uLKej@3PG@?>YPIz1CcFju9im-NPeOQ&Du>5W`sszDtE=GN)6|oC)9O3bPtKK~ z$E6f@`HvFC3};lFEL`0w-eKXUO8{0#u`Kjy3dfBss(N+QmA{VQ~$ zP$ilEDfEq#BsX*m)Is#3{0p{5hvNX3Ii>;#sT&Fdn6q z^L$?2F8w@4C>|Y1Kxq7ii*6u132#2n1Df@%UZ)Z3O(BJ0LqFB+-XJZ>`kcV*Bsk!I z^Ak7eh@;TQ8KE&mP#PVTaW;V@z)l=zR6ZDt7y#?7T%U|(Jops;)jFiTD`&z?yVMaK zRzWzyjh3@w4Lwal0cr@pK9pbxn~)C#)!LwWX-A!6wFMrm2HeEtfM(2j+A2=8FyeFi zg&6`wl7T<}`7i&c|K)%Azrgo?YnJ`AMpf2v2Un7m5!}>4CF2tq;T}2oT*0qgGQ(OL zx3wes3yjgoO?KUKF5YD+7J*DIuUDi-^e_f1WhSKLPc?s6BWd~KGz?5Lcxlh=8!IJE z9C|1Kfa|(|NL0NwQp)QofW_q{clQ=LelanNGgJKe^KKdD>Ck;;pal4-eWGrB|NIHbyv5#46V*Mx zy)G67E|%}l064~aJ&i22wqVptFS+f}zy&dT7#9WXi?x~|GB_(1+v(OZ(YhkQ-@i`s z6W5h^G_E$v18{P3d3RLcqBc(@J$fuK)6{%&sU&6^cWeK8xPh$1EGVcu)4QBjTF1l4=7usD0_P zW{7|o$k6e+Fbvc#R5xW*Dv2!aLC3OrDVUMCR;b`kftC!Q@7C)FC)ZNa2a>nET1Y82 zq$qEKFIEK2;XPS@UHEcs(wx9%&@P;Xx^Y=9by2xyrY{P zGaPWX;W3MNt{~pGln{%{|48*)&jl{v-kXCNd93L*7u*jzjU}MFQ;=KlTX^o8#9D#7 z-$dO`eP^z9aaW_!O6Y#VucF#6&JvbYT`@|{Vrj(NUGG^D+N3k5)@Xk) z7Vr0sycYUy_AYQO-B?9D%IsDgn~piMV>E&;Jp>L|HhFA*)X_2N@EY65wY`>rQxMz(+2<8z25NNQMIvcq#-K=S3E>soX4a5q?ipErevp1LvV}y3S zLOt3eqrT2Tp(b)Mp$QqlQKzXm-tV`{j7Rl~=n+8qdVOK<8ix~u2J(A3hQo*)(Mn=Y zk%8_&&vq`1i6o=Q>YSb%LwTpvVe~`gkl?GbQDA=xbN9#-4X$DK%AQ?cKfbR2`+xi2 z{?AwB|5dfF)M!Vt?Yi5y9xmuw;)giJ_)`R^D6`rt=$`#@VLJ8Xrf~UqT=|7~O6lfZ zhOxt7JfL8^Xm>G)aoa3Vhumv}L<7Ip(T=GVbriX%9$<2CMpn~tZd&*9 zsH_frBl1?CJN+!?v;}A&kXs`@m1)#qI|gy)X(4DD1UafFtFg5!Qs*5tp{>0S&iXoQ z`aG-i#b4g{e{k{tKhf8}Yzx3C5dY?T^UK}RA|q@_M=#O_5N78GLTDbz`p215X}=eq z`?v}Jn+wL{?y6$hzY`<*5yh520hS*W$W^44z?|UOk};9UR>ftNGCo@K^FEf#@bu{) zS&4%lPQ|9r1M-owDB+7|Qw@ZSPJA{xQ`wW0;+{>0~_NfJo0 z?hhsfB?NLOma;_SEWOV8h*tGy7cUse-2eRZFIX4;tLrQ0&wqJ)d{fNcMMjVKnF2}q zB3q5X3FM*(kSS&?SrXX^d#x9$HljOr1X5a81iy5j+JW5T%z6q`oq-7r0LKjW3|9ss z7SD4!=7x)bwyJeS;GV%+A>*`^t&95DoMc05d_qIxG#ih4y)DDP2Ry0*<`zd3z+_Sg zvyMg-$rZ>vvy~}xrU9^KxPifNdU4X55K1_>V!rsLaZ?T1u_^itTfhe*u%-~aw2MdT zi+pJ!M-{MEFcz>&hlL7oJ?9`Wn=))7fUlRNiFIp~PLEk-!5M?#U0bG#;H(TWp)G5p zh#(@S_EwULJZ5ub0I}k46h(bx-&WqNp&jApsCef4uiwnqLX2jTj~NMO9@h{If{}!C zVGM~~d!nE>F0j~OEcG;dlv&}ecAFYmK|qDeYb~3Y4Z3e27T3~#5|$XaLP6SNy8;ua z-h|B@hcR8n>Bj4I&Am6HhjCr#+Nj+a6fzT$FA%_e-&|`MD4j_RD}j|4kwo>ao_}dC zy>}C`ic@cEqt!DToGJ2kU5J&uzu)NIxS_rNOzT)g-{;Jev^~h_-6#yNv|M;fY93Dx z83TTDtp}c2-?70?AQ$?557>-a9LKm$7x`W2_uKWSenn%*z2_rmrX{+UYzY8Sbz7Nq zX%cJ(SQV}0JQOz@cTaaCGGAB^5I!uZrG!>DW#nuvVoZ}Wg>@0#J$nlvS>bVAqpf)F zx8&qh2Fm}D}7ibW&M zRz^(KW~^j3&*(I=ft4@3yM}wPUYZ7vby)>K)*jN8-0MeT#hRb*H<-$4;x1w>PtkFY zX*aq$0zi_eZRHx|t%-2Unwh5_a3VBHcnPHK??%rJ^ipe6@@YM|a*ckM7$DpZ?URE93^LVb_&R^1T)iJBs?0_djQ=6zNIhboc1ab-JI^5;SW%S zsoBg!6hW@#BOlDCYzaWVC?>~die2{dxk4(j;or*5k+Qmo0V@VMTv#Xqdv7p_S6t|5 za1Xcd&u_o|)<3_0{yPx=%~MD<#E!b?KCQ0fqMDDv=SipekZqobsPDHy9R?=05SL?) zH+fVII8y96ee%vBk7Qe?yk4}X%#@Ff-Mnr&=-P;Rh&2 z9F68t1=(k;2QyY{3`{b*cvM0Qp8O5t$z=6um2l2m(0x>m8V6N))WA|MdqlG9PUWG_ zrR#tT@=oxZD{J?)9J@7)Z9{E>axkWNa(=1*PGSClFgTw_*A6&8KcI=9k!_Ow{$pX! z@g49r&>+kRbOBGB@ffPmZ(EOKfW>MF$1|F=XRo4pk_s;LJ)LxsO&L17nK0F(ie7!a%!D$XofpA%Vs-UQsy% zF% zGGz|#ZBPRQ-Bi~sRE1>|{`?GJHI~Mg$t+359zZ9PQ|P)h2GVf6*z@UYC9;GfotA}= zvje7q^~#w^I`P1|E|8cr)N2hGYiT-1gFuNjTVLq!xA34$6|w3-IH;+U2<^EjVuchr@9nsSlBX%V6^@TKOpdMZ# zxVq+!szQiDLgvQ%yVVPd0lF+}_d1#aGW&`QMxy!~`z~a>G?9crPzC;`7^BF>KI5@- zAu@(FBxT+wuLz=33@y9+`%!Rrh5Osw{2Ud?9*B5rbmNuD>P7+N5EVzpI^Y!Im7HFPz}!^=OI%>sV35qf6(f_m zsV8PNhhety#Kwz>xh{E9RO8)^lv-&rg4sPa#lchdND*Zv+U(JI^8{wJCi)-)vB-c8 zG&dqs6>b`GwVBlGTBvd_tIx`0A~W#*wtN;F*jm@%#x$p97?|eDC~W9hN$9bZ{85J* z%@Kze*7OpA{{f(|3p~!%ah`YWAxH)h6O7eU1r;4(CfGf}nJ)|qbr0fFP^`k>cHzz%HddsH#^WOI`7nb)X3T&xiH)2qNp9zCOV0@B{UaH(@x6;H7d|u4#bWv;*d-;t zY8nBB7!{mpDN)LE0TCQ zRvo!GaB&xLS_RH)`nBL9RWKF~^Pli*`oDTzlLqOOcB@DgLvMq>Qt^03hZ=jsb~~Jk zOX3u`=tOv$L7n1rpi#aJv&YW6e6PCHHuZSTr#us)F3ARn1`o&i zHS2SKnvTgQ^$Zi6TP_^!^*9DIU~tdsR-+zjd+2ffB0r@%b(#ST5uJ{!P#moT2#j*y zXBrul^A6#5k6+e~p)HkfdVh6UxajsXC>Q#EH$*FkA8BKrHVK!HI3>$d`;6LEWnU^X zH<;+TMS_k&DSKn7PW!y)VKv9ijf}XFF&kKud_m#W9b?BSs}(48THmJO<`Mx6(>0E%fl~&m2B& zyfFA#9MYaT*h%J|04!U;auNOXO!?DC%FN_c#Y(X494sqRmAWHn?#QkbN0sEZZ|fPk zq#pQj+18E;Du#7ld$Av&>|i2P@uZ%fHe0=&%$|-2Lxc~Ip?)-2CKKK;L%Zg3Z1@5n zGZ4)e(AXSUJunn=ia4eHk*(nwQ3!s35*N{8>kN2+$5zKk8>~PH+0*NPP*UPqsXUR%YZNjf`uR^k@vr~&zqx<_ z6H!}2txj_cSdvD!F)!vYgOeE5&z9oB#*a!GWNsyO%>Wu-J)!%A(onmX05pM-FyvUXfs`2XlsCZT*gJ6LJF08Oc{UTwru#uEmw~I5ugy*gd#b#58si zyk2Tf*1%Q1KjVz zrC#A#Yf;k#@U`@MO+E{*Y93!FfWs_APjc;tloaIXt!V0XvGg<{3s0{H5F zPoxFBE{xU{F*^|}4$F=eiM7CGQ@Oh~B<)lZajh42?WkP{DgnIm!eq}3(Obu9!CnuN zFi)VEL2xa6@0(H)X*Ms>z@-ACFj!ZzcRlN$NFXtTBzsVltUuDKg97FX<#N?5FQkFu zC}yxCdsoMDT))5nf{0|KM$$#dZ0*Rx?|$RsF+$}l84P<(^zboLj2Z3CAf}Ye^xo(x zXgUHx7GgJ;3#5!2m2+<3URc@FBd-h?2pZ5MxdKeiFh~t04h-!(B2aV1V2{}_01~W> z3}R~#$r(*o&>VOGy@z{$BN9lW_ZUSR$XK%#(|cf~ofx#Zj z%fqo&wFyDZ9!C`_9II0I(%2!o>~t&*5g|TTNinDb5*t(@TOh5Z zFaRDylvQ*}6h*IQs?+l&H4Li7`a}ZLiK=_zQZ(&o8cdc2N1yhpnbyL9;DJWXCJHC)f%%HQ-zvpBIDhS-h*85*}9Z#EX^wlQqPjh%0(B3jp-R$vp*Wu z2+pMZSzNpgU^8IMRCAihwa}|j)0i!`JV6z|zCW{MbZL-#5RKl&2$`355G-}^H=1!> z?$=fR!!B%;3U3g@8Zdyn*m<&-LG3~Bwr@e8rpZXGD@6D*-7X2nB6exPYqXv!K}M6! z;g#&WczUuU@{BAOo7Q9I zfXtW2$NFp@fYj*3o|>E{Y#t00X^4JF)2p^r-q|F#~4(bT@Nb( zTRGJsmQG$sD1SfGKevw|=e%lE zV4oJw7NZ7iQ#Ujr&@Peb@qsQJ!!coc9_y!piNWU47m8JOU4Wy89c>v2=>a1Y`ph=i z^FVOL%7;K4Pu>u~s~;PK5Bl6qm*qVV5oE6YAqO3?y;j6}$1|kC%EobPs{sOp^cu(a zfuI!$u5J1>{2fBiqrXQvc(^8<(R8Qn=>(^?8;prugAsPPXqO=EeEPIP$0>{eoYAz+ z&u3(49Bq#F-k1zKrt6>yq?t#xa@5)C=Jihc!PyT{YggqhR{s< zN5rm;b|N65>u&-rg+M;~9KBCHD6|*NNVuXH?rXB5Em;kj@m#g0H;s!9BF!RX^()u>jDX0fV`|E+i9OBgP%TS{GGh zNja0q?%gtKi$r!}A$o*>yaO0k_@vziBXm zuOB~#q@SORV$W0D926fz9V8diNNcNBZgboR#0JSnQdo; zl#JHLzt;*R7OHPgoJ)gG z$}U)vI{;5Wu)ia7z?tcp>A|j}!^bnWG-EKd-K1*SY4Tz4;)>z*8hQB0=#(`Yz1Ltc zDFP*7r;~{xLhf{0(HQ^|yaG(ABxI1=@&^HNE$zK?zF)yvTq>|f3WiwA$|rzfKie3W zr-$UywFehMQyrwEj8j|+#u30!oN45`81VvoD-X-XC8M0)Lbh}kPdxcdLW&6hO@^FR zYNVj&5_k*ZdId6K(zEnS4^|0H${dn~I#?~IkeoOAUtuz?Ry}Az_ zk2xsYK?xA309FqWDduYA+--i)1{DI zoN<7^NSJ&R>(_4Onhxcn@bfK$%4s<)siBW)KK{uz-WOIzhEQot!vMg8nzP{rl&RdSz&7 zCBV!p7})#%+It3U?W;q(?HpJ^%GGOYhr{jV$t%cop z;dSM-B&JyF5}I$vJ5`2$x%0~^MDxid#58EW+))_Mv2*#j=lbuC7awQCr|D_0L9 za*B;cG8qXZEkXwTCa?*KuNm zK)r9q#p%B`hrsK4p{DVdzy1{~UXx2C?u;b;y?fvhfg4+s0;mGLJ;|jru^w|s%yhBs ze%%1lvU}c3WAT>8?RCQnFR@2g#1!O;G)L)l54h5O>6UkLaPJL5j^~ouxB9Xhj45^b z%*MNbl^3?!BlvYK+#P1F8(kYsvmjvw6qOdO987WcG&3)OViaSoxFK^X=0h?GWVQ5& zeUhD)0>lLwrie%Z6p`NZZGblTuD8a^EdZU4p9-qiTw~Y1#$|E7;*~xyJeWz zmeNYTfMl>)h+Y^titK>S}$-KTK`(Z zd0m=*(LGhoh+t%*W-BM?lhmq3Ma-o$wJrY`q|Vg?2q@K&lCB$=Gu25g3Pj3+w{HdA z=)(TKnM>2-OIQubCSD6ug=*zOYsKlkS63KB#JHE7z(yi55yJqRiC92a;qs)4_ZEY^ zu8Vi6N{UGgTIxB}Q=|<>lkTZ@BkLrT~gA(Mw>(rD*Fv*TLFrC0^*HAIKnSp&hssWwN7F_3Cq zP^MOD5pi3NIxP#5qN)9X>#q0y({Eq+@%7_>^Z)#(fBMsJfBO9|lt;ld$0?{7S+ot` z9BtKFD2`_+5MU>tQG6=!osXGpq5pfN_F==i8S5LS%`|yUtK5@R$iM;I^2=xB`!Bq< zuh-R`3eQqe{5Om`t(zESt8)NG0@!#+LC~O+Yre3$^MGnf15I>3rsUGP+*{rYE7f&ZU>{c#ik z|4Br|edAQ}rNR$J3_~L-bif+9QV=K{_wmmI5t9oedP)k%x@^^D@i5)Zkh496mP(E# zgFp9Yp16tA`vZdjN{~kV%`>OowoW>{X^mu2#)0UM!a!I-SU&BZ^gP+NP4(cOodYZ! z84`fgBSo`Ycubwbzc0{1;EAi@Ny}0_?|TSX5_AG*BJ3pqp=dmtjR$kl-cD`BNZ7em z#rna117i6(M6?tH@^1(sqtpI;M%kc^+O5Q}9IoT64Gk6(ERs4r&-G}YsXlw?!VigH zY@K2N&$?1ZhZA-QK9eB2oj}igq;vzfQn*;xY48NR=@a;UxEO!wk46MXC7|H%LZk(( z3KYNoIAA#^8O_BbOLA0W#I7>LEhR=?c8oqF%qS zR!l7Ip;kdXz{0hbRzIOWC@1G*6^WKTCpoxxq2Alcjf#$YZ!>pUlfFy%!W}3D25J)03 z@%s9Kudg5IU6{SOWMs|^QOn1SGGb{hSpmc(uC>%N`?~O2FL#Y3u2-ss;1;t8N+!oh z83+0xi3~B0OHAd@pWhIRl1MJ2T}p1&x)3&<+Ea)X!)f<3&h)MLwJ9*Mz1{;#_y7U{ zjE&Sl0xSF*EfFNZw%TpS1DSiWYU(g`u)Cf@50yh!XuF`Q880MGAO3e3LqzG zaS_v;dzTp{gQd12nvfzTc)3jgXzbZNY8hztpmx;*(%rpTHK<$rc$&!9g$#qCix>?9 zM<$T#n#d*fmO-1y6Q{Lq!XWSpf=GP7Z|v`H?7FdQYsg9Q?5EEdO^jk~xYY%vq)pAk zIHrx(Z|QURyx=5~gS+JhJucMleV?30a#1sQOd@$nCr$xHl9)n&KF|tB^XD6gr3pEW z!PE_~CPK!CeYeyVy!5#sg-F;9P#cP7NVApfOS!=$A{HcwQw(QAa_*Ku;L4ny zVc+GketY)&Rwm)Nd(QA}2{AA(pvkhlb({<@>dZM~W@gCbg}Bm*NXWXUPEI2tEf$ck zOJLT$EnNf6+x;-- zX*AnwaRDonLE^M#)L11NEmpV(=bQk5)YMLZYk~s6Gt-y7pZW)6M~aG`X~ida|2X%M zEWMN?rA%`pmBSWhj+Fb#MfLq10C`Z=r}JIvpMl4=pDdHJXF7ZyF=K|F{NijSeeWVt z`;qd58OW>>1FXnWJ3vM-axnjDyx3IGpS;NGvWJN^>NrY@!o_w$Ele;VKBwq>>PN+w zM`c=g*jU5j%Hf2Pc-^~9P6LK>@<*K+*t$P1Gp))yY`f5jG%2oAqd&dhZSw!*t34{B zrAEQiSP^g%?i|Wzri%Js3j32s&uR1UHTl<1QCZMhmFoW#&+z~Ok6&v)Ixek`Hu>bX z)I&Txq#yO~4e3&*&hKkA{gRVPaXbSgoNcJJRIBdfwZ9g?AD{qkG3{<}N-}*|QD|ub z?X-8|9Zzj`0FbketS-{O3m6*bSH1CzibKD{X*A>=HEpv%pN(gjrpP<1C>qC){h%Cv zq;v}G)~R1>2IpG8RG)vyuRjm~Fu&ZUUvC&63C%%Q2^Hg*u{qJv+#Fd^TiVf|`%mZz znq_S|K{j9r8*22?8lg0Ue(+#}28__#Z1FjG576LZ#2rrdB5=Vz+AMP0{A}7DNr7~k zN~p!yK#6UreL*un@kw4s-*5W?jQ?#$y`2%lNL}A5P|e7+$ZNRA2$rr=sN-3}4hW|Y zzQ>qr!=3^Ma0t^$zW;SLu291{nSmqbBlmL8TZfXpvjKHbgq>X50b9m9;pfOU=-|87 zurZHAxTw~_b64jeHEn6Wq*F(=G0#JuhlzP?Ab66i0Z}%7Il>BmPJ;quKldw6uy&!T zYgggf<0%6ESy6H6=PL%8F;D!6K(8U{zW?n%{=+|DraP~dgCh$8)@xZ)AXGb-ip(n@ zne4T&%wz);yW!6)xo;5N$ONuyA*PsXl-#s^^x zmx`LmMf6PL4fG(HSTcjcD=r{v=I-es_LTSL0I*!L3nV9&!I#jX5Nl~v1{=`5mF&%o#k8cVZkbeD4AsOzwXQq*{=J+)t1k_#Eg|$}q+$t!RVnnVB zp^ zPfA~dY4B1(DI>np{`Q?AIAW46b)}@!V}&ObyIaRNm*txnaO4~=fWOc^L`rU1cOlH) zb^D3;%qx$HqK|ivl8H6AUKft`41wXoOcPTZU3&sRUJ1tFip6}TCVbfd3#IwlT>_X_ zILU@aZ|eNS)LrOZfIwD Ev}3E&Ay+^cljNLCaG1lMa}dU$`UH3TyUgBFV>;0uXF zMq;f6gc!m;=gR?h4q!HfYatA1gHxTyy4If7+*%d#2}BatE8RvnAY+m-!9YX|6=OOE zxNB>qCSWy%*-$GVRKOD}6E&j=B!agF%+q5#J%gl9Z57x(i{TapGIL=d>n;VinJA1@ z1p3u(5l~yR|7%15+(Tqxd0{ zXI*PB?1Q0aokK8+)0+CCd~`{=ztkS4hX|fAX>1kcF5v)#yki_&&x8f^vN{ITWEgd2 zvn8dz-#4nZi(gGyS(gImTIte%tPLU~4_u;-r9Svc*X&YKT+n{Rq=3~@zC9!)O^SHG zH~;keZ&CM1<{;&SGx)~C<|+(Y^?BCHv*rZaLO*kge;HiswbI3QgjyxsiRFAv`5O+& zVvsbUt?B84-Ra z4(s|3sns}u5~a&GkTH)LVLb|2f38E`^*QJI0X5FY6AAj9s8&lIF5cJkqz$8o@HaKJ z?!qww9;;8!btuQ5rvv)~ft$nen9#0QeOG_#j5|b@d_cLQXRC`E2H=$UKW<%<9J9+4-hB>2a5-#5V9rpm1Rs$W`9K^=Ku{cE>hCThdx)95~W9Jbpqj> z;ys=|{D~tK8ohrXvqJ@1Nl}HbVj9vqh6{f+Nl0>RWYGoq8LOv{HTDe9<2l_zFfamV zR!nHjV{3is^W%g%2QQ(#J(OfhC4vf0gn~yZu*%s~pPzHqih@``;C#Ed$3aQ~C*cR1 zQgEX|79JGWZb=hBP5-Zc|I=?kA-l?8K^WK42cVs%1>z`C$y8FG)Kr4fT;N#=xjqN5 zM(Cu1f9$wdZ{{6ZwLt`(7iuiw7# z%1caF4Hne$AeBNQU%|c`%Y{`!8bLcqkLVywS70Kb5qynZHwuLwpf-n*xL!;B>@J+` zH!{q?x-Qz$-wx+9RZS#;rB2Xi=C4iGrZE-6mdiTkE__|u11l|Soh^eSqtjEyhedT%~GI&K=#+=wL^k!4dZG5A{mCr2P5(T!Nw zvnQH8>stK!?F)e9!S3pk(qjQ}CHHRZ?Y4;qWYYG=_j`-vnnB-A9~l2fa&Z55~Dp_2%Lx4@#z#C2U_385GtkX$6A z!4<-Wy9M1Rxh?^AWhOkr%pfqGs>)WT3^bXj{SAHGMhSBYauk6Qbto;im$J5=1hi0sRATw-&P;BkHbNR+C)xP(cYV!>h0?Vfv#b4 zX8M^mG=t*-z?j;e{vxH|#7wtLAajwJn`-lydFfiAF^>&IE_*dlX0F{B)KF>+oH^V& zTfH}A5Q%9`jYRl$AaH^V6y=|xsRDt(LM};ky9Y&3psYX*L?H9R%3#%=;2_AJ8iA+K zv?9hSVhJveTnuK~{R_ds)TXB{&1g6zU49LgCbqYndWqJ?tDO?+Stp2odETK5c z%)wC-I6EPQgavg$;p#*tP~fL3t@awS&8T-OV)FZrY#PY#WpQ;ZIK z?*ss*hFt(+&U!??r4pBfU)weR5rc3vDLe z^>4W4_e`9Efepbqr&xAz-6}?hzyxu?W_>>A|ClEqS2R6!7D1%`es~lDebm+`*CIZO z0De?}0JL8e(@hrYtUDy@@liOF)%5Z8c>)I=(E1tY`zl{tn?2Py@R;{;tS)i3&d-uM zwfNwGNM2{{T7vZZ|MJXmpa__J)|wrI2Q8BxXY>B7CJ^zm}X z+|PK5;c#9Ff-Pnx(JE{KvGoUmSFMLS*9<5j^F{|g3X%3my~D^nA*f|C^8}EI=TfWH zQ+z-WdZV16qN-7avK z_-#z5hv$MGxNUg)wa#-kxIsM9)Dr}{kJ-<;-q6qb=f;da$M-M$(|!?SxxMZmtxSl} zE48cZrsf|XH{QeAld8aeO=M)aLZDPU$I#By6l>SI23W2pbeYI$B?V`V*Wf%-fkf>d z<9R0N__^Hgr=*maP?FwVS_1|o%!SJ{b_QRsmk&GnVw`#2T1vj$3y4V%mKb0KF3Hx0>MxLW6$4e@N-iyJOt{yv z0u!EB+~SsBYq^c10WOZJFCz84cNOBwdF6}yE?UjYp27aUv0fMGK77m0c&#M{k6!y5 za;hH=3#_S$2xLe-^#1hRD3cvRS%57+hb_x+Snn2Yy}`PkBJ3 z_qw)vUJLj8=5*N~!pl7p>xW#zgA1tU-jX;TLP~9hO1(m$0ozH?o*I6GT%oBBv%w1R z3gq6n`};|3`&~dNI>i-OE3ogup5hfmjz+8vfZlJMv1*##O6<0-c5O}pqM{cED5ib- z&Ky%9sG(iEaaUoe;z867br%aygC>L-)S}ifX&2NM2S-HV0GW z&H zsy1`9x4X-LaRG0&;~Pv-h3Hh~^sKuOcHv9xy$6s9Dja9dl#MIIV&Avex#XggYymet z=of&JI%TFcfGJWfPCDHr(5!5I<)Qp)VL=w5@R+ixWn&Ly?dE?rfKJM|aPDoN z5^DO%=sqXa0Kk#*l!ym3aV#7{z5jxfOiF>oO#k-VZ}ETo5C8tZO2mJ&S!5HMz@r0| zF2zJTIZrh?!-xIFBSR3=uG|b()^HqOcrxe#O2AS(N0X7@DM}R!cnWj^rtQp6hk7-M^?wiDP{2>pP=!+l4z^i;Q~zWz63~ThDJl zWA3!)hJ|Rj)eoQE|FN2eY5?p5F!V3rMC$&^a8YqYDoZ^d-J^b<@2M^9w|?G8=TGre z$x>&wlrV=FJw7bm$78^1;RZB8L32LlEK~y_YC#+QI}3-md`iKS>!14M02lB*<58%H z(CkxlwQ7<*W1pvhz%_n8Ge2wZ!}x2xk4e?%eQZvCK!NA`03P45Q)3Q3|NZar^=mEs zKgHJ{N&#@b<|&bW`3mAVZ3@{TCXNxrc@T#gucrvHzj(RiPM6)JA$K?gm) z25=!iL&-cb8p$!AH9r7kqpa6H*NqVvB4I^Zg)r`OJ1qw8)fpARR8gjN&B14RT88OO zGnRE}JR?8P^u!Od$NF?i;2jP>(j*AYoAXSJ7aT>Af)k90%G8jUC)gf9wnXz< z=x$cIhZl?2x}cfdl452MoSA8vg6R|~TRdaifP7kUZD}w6r1@c_pF7)@tFo7EK65}*M zj%&OC)FQ%##{oFfdvasmjqmpx2&pG}0?ZjKA|ofbw3Bi{ zf)eQFZW$s~OD%Qgybsc94f#FPU8vd^yZlE4&REgG$k5A)12f&8B9qFV7PB@@E@C3x z9xf16MTthEy?$H=1;nm${MCD1m;1UOfiuwMQIi&$8R)*I;4^WKH- zTSfQC_%TDOnjc?Zn)=Z)j?6_|sVO2WFRTEN?ms7R*BdfT3tZO^p|_H>wM@w+%hXv0?5RCwb1T?7_rF zF7;5T161NW_7@F`8i zK{$Rhu&zYJg}l~Wucel+nP<+q_J7)SU#&z{TRtJ9;gp<_@m&z>dVwHnm*X7px)QOJ zU_~Z!5qa4>6^c(0F*rUePO52*cOo&#v3wqNH%gnp@_Z$8Tmy13m?#7`_5noXhm&IM z=oSTeG^Jxn2$VpXtrY({;lk;}Cu(kq#)6H!S=KU}4H?^oGP$aa#%O|Z&v41GZtsn$ zt=OQ+HaMz7Fea`wDW3y{EDi&wmBJtm#d=DC)xWUlJrxuI6K4BEX1XFL)Y<_;-W92M z_i&a@iWI-%$?b;0SeMSBZW+x6d6Wdd|NcAv{O7;?Z<%STpYnHr_86UWAx@5bazW)0 zBFYXhpgnNPDp+-S3Q4-iwL9)JnqKiOl&|$e7vVvyU5GhCDpw|4XTpeHkn8+%MOp*QZ zQ35!hrP>Bg@_!g|IRAxXRKqg&QGL`cKY${!9mDIFJUIMXeV9l7^1P5bU;CrFK*!?= zLW4}vzW?L3`c%;IC@PErBiL@^2uv^g4(X#j;F14w>g&goOz!EfKMa(d{Rw-yc@?CK z3iYTd2RKCzUHlh*Q8c+0`{c-cD!#L}p5p&J)Bk~A|I?KHpRYe20Pt%BI{zPhjE(?4 zm2F*$TGJNc8$Rg^kq@ z388lF1#wK&FmTJk;PGDojO^RIkifxK0T=J*pq%sm{+aQ0hNM9AH@hvw456jJNBbTf zl*0k#NT&`^1Q>}Ow_gC04n`Qr3isSE^{+B@T}QFN4?l4LU@#K@^iTic|M2zWPY6Z? zN4B~nzXy@snubtwgOtR1E%keU84wV|^YI{9Dm@0FPa`8qTB3EmWS%s87J<8KzVB~-zsu)w;B{Sgksbly zq|E+EfQ#34djBzd21ot+S})1G<|u}QUIc@=G$OEDML027>ubKQ7vz`?TxK0ST(1jX`2$?E!|otf@U<4IZZHO~>&qa98e#4!?t25X)fVzf_4Ti%-Ow9X$beEa zoMELtF;&QGd1iK)FeZ=~fmDJn_xDD1@p`%a0PV3^30zbg` zUT13!yTtll>t!jwBSx1E85@n@y|-l280@<+DD3@4-+Fxvu=fZvj0@|snGqVH;c{44 z;OpxLuJ!VMj(P7ESa)x=d(4TqDg<=a9kxXAT1Dw488;KVx1}TL^KyP^ufXtt1E2v# z04)%L5+6m~g;Dpmy$b|LZ?6}&jXA9(N+Z&}iQZz1GNtYTh}RXsrLlPkDJ8@X4G@8^ z9}Cy(8nj|#K_K@!o@$HAB0Ap#bH~7p6I}7P7@m=dvkc0vV$M$g{d?ZnQm(t`vXF8T9T4 z7(8k%wd}by4u|WLBJBV}Wz|8baRopj-8Lm~ASYmz$(S%2-_seOYesnr8^mm#ogfie z*t@2?z19Y^3(3TxCK#M`6vPgi456X+&AQ9lX%=?l)xU|fW#2jz`C%J zv9#9WSYeC$?En;KYBzSN1(hUsn^hNDWc*vf3xBX{2M1B&=8K->T66uA#*p=*&rpUk{Du0LEy69U0SNhs&8hp^*Q z1Dv)6kCJ%a`Tbu=?D*SJ{zo-;>SZFTpd33m4B+$()B!BqO^WsMKPodergoQ z0c+>9X@Um1KUCv?RK7odCH^R1f2q6$1kc6s(=(P{!6d9nTJzk!a<5>-iXnzB@H}oFWY}!l1BT#$q%sGZP`Gn2o`4LLMzX+j zQ^Xn`t^i^S$Dhv{D4ByO7#x0uG*I1=ek(vK=?yk230;9*Mn?zqnE-HrhG@B|%ZpIH z2TGI`?dT~2Kw|P(E(VTBNJYF8!h)QBeTW~~{LIE*@1OrBQa8lS=%*ESYAByE0*lKr z((lrZduC=Ab4W%F0=qUM$tuZ}nITtm$j_o76-$V#(B0JcHN7?8mX>+%}DKD}25kufud_k+ZhVnV*AEjOI0Ds9*l zps?ujYc|$eRPmzR-IW(=2DM8?Z4&uXOTadr5kZm~ z`MH*pX8`-&U~qoEZ}v1ZmVvRs-GdBHg2a`$tML8(jjwAVQ0yYswWe zk}3|dF_Fncf+2T(5k&zFT&o9ATS2k8uun=m5X*T}n}0uXWk~x|kK3-GF-LQ$MF5Z@ zwptH0Fo;OJ_bo;ff!-Q%x0ouRK=huWrR7si`81@~%|O4~LtoM~16P2WhGAuz903P| zSqa_U0w#&B8;y-CUWmNFz6I7CHmG{;eRD;k&`h^(HDz|#^;kSj6%g61aa?ZsO`s&j z-tYZMhC+KM80Z*eT$rvQhZBLRTP;QOpoeZSuVF}QR<>S3*=d6#r%qZt`0RD?z!rlM7Q@_m&!0+fY2~E;CD3a%Es< z_mEU)K_bHa(oxvzv7br<-jSHTMbzu4;M_fkm|$=o1>2y5vp@`!Kw)nn$Nk}RKzgCu z8pSZ2yTo#n=xMCA(3pAe0b`hXsVxK0be3r_R}T@tf17)ApDT zp&~#m63h;Cl)N1>z+9ttlMO;GP!WkL5f+#L*P6OLw$-CWbH-iKt6uOcB6rCvryi57KyK^zEMh^cFqv?^yO^Z~?@_ z^wH}?&!F62B-B?mst@P0hWux^_YixB01=t7VsS7cLqe}294qA>OyCO5J-^lxR5ZjD z$(ZGlP9Un0E5Jp>^+F^M{uYbi_4UH*lH5A47goLiBzP_4l@WRI>rXGO^^#;%$+nFM zDbOWoNo&;v6FG@kBs~@;V@)$8ksgg#f%S|6%N3f$E-uUdgJ?k%iqEG`}_MR=58x+96R<; z06mu(%uoA9V0IHD^E1d8Qejcgm4#ERDf_P;FfU9HRh!IUE_j?4XEM6Ihf5^|;&qHW zwnERX2@>V;qSGY?Zf15*XG(fb244B{ykE#kyH%{8!)FF6IQ9tSBVi*w=M@s?Vm394 zT-~>t2B5j+#Bk+0tx40c6n2I);EW2lyv%qifnmgR+F5)G^tSocQ4dTrSkbp6_wV;N zdfx~x1k~15y|EiOZA)jY98+q#q}{=(^s*i{C%`0M2_i;gMHy%m-rIn}U5G`zV&Pia z=NJ`m5dlu2QS6Qu71W$^To!z#F3fmHNWo&ch&S^GxMM)jUD``QESeNRiy!^61t z%HGg}6(`}Rnmi;?cx*TDyL={!_>!j1hd`@H~I0j`DG zn?!ruaAJkpC6WNI)KnBtNsSb^zURj1d_t}l*pY(L_RqB(o%z!LVsz1o+a61hRU;>kuRDNB8Ju)xcm?)Vzkuyw&TUMH9EN8@; z8Ok%}Q6;C;+0MykQO}qol4t_4{EX-#+Jl#4EvyL1p-rP}7f<%S@o)a~e+^Fl*WW+? z3XRJ1VniV8^vf%To>p2a%IaQ({#~Qj=sh?<;pwp|lQrU}Z<|EX~Vv^BPWzudC=C;%|1(Rj`_%+OS!dz7=M zcs^=|Q^dD{g|SMZ;Sr7l=e#BqXC7Y|o@W*x@0qQTs*#Z`Mc-+SK+I#f2*=1{l6gqX zr~QfY7dZDZydYEtNX14k$%fm*0RguCKrl}g|A0s{zCWi%8LuBd%a{jnIY7WsBmBo- z^LPLKm;L%<0RYd}L0N#mX)F&dQW)V0j|T}OOh;ZGmY!rBBh-1C;$cP-sY4-aNN(W5r4Vh(N9=U5Apuj2u?Ro#gLD9eVIV;ZV;0HB`92-@#9Lcx5@lbpBn z0862OAm=W4jU1IFl@_c7A1!SPBv4QEZz^OOR2*|3! zLLz4&)q6X{AdpY*c!UZQ^#rPkzq&@FvQ)HnZ}i>0-vwqNQvGB+hlHT;X_SDbbc!}5 ztc;cq~%N;4j=pk)eKWXGEYT!sF|D;q~Kpkcrui`!2#P@}AO~ zv~yRN_(jY{?V9?nRzhE% zP_VJ@X)sw@6FkpVMPUMauv>7i3^pB0=!mv~ro1y&q|P=5s_51<%^`oi&e%S&mNoV4 z!-aTyykqR(3MHw4yhOqP5LBRH*8qEPcTc;xi6c#LAly@^2D&`c*-EQzuMq~2GuW*$ zh~*yi-h=&qi$H!0bjK=X#~ugsuzIWCoEdMlEL? zFgVrN_c*qt_XseX*xjgpyDxvs95xcng^=@y@W>h@f-AM3BXrJW1|whcHjrT?zH%Wm zFnoH*-HNgsOAhhvq~8@05G_BqeFG)ck})Hl8(L>`f4eo$cnS!N#+weRcyF~-MJ`Mg z9x>Xw z2`VRQVDC3-Z^)P|03>#`eC%w}IQHjR>OI4{zL2SVuAD)HVnV?2Y@Lb8L~oBP%|Oqg zq-mf>V6u`)t?Ak=^+(FjHmOwFn>E8beRzj*8qsEV=N@&*RiT z1Vf$xXcg30I-gdAnrQ|DtKDXfY7e*s@=b549TdMf*&^{v@Y8O@MBuH zv?r^G-HIO~HO{z09T4H-6CA_@hgsj>Z~XobzZcN|Wm^H3K%6=7YKd{K8x~pd5KE_! zRNh4^ECizZ-s!O!yp(z*lv3zyHhZii&N+0QNs&pML-=Y`ybEB_CrqM zfa~dET!||%&hJ_vh6pizzH%P&w8b7G&I@p0AY(p2)~PX$48QnG-RHUpXd9jaIhrCQ z)vWXMr=XLd63;8E76`8c_?EK$?B<-)e^=E1F>3t(&aXcx0PxEf^?&q26n@EB1RJ#By>^=|E=6U>lrWib+ ztyDRd*T?hxIO*4QK!A#N9(B`MLVbV-|7_Sq|H#t(`iBW)oWo@t6n*Wj&v@E1bbwnL zRFE`w^!efY-~Q`qqj-j(o~2BqpS~CL&(iE{W@7I`#`*{J^xoYo5?8FJ?PcmfpGr|y zdVHCh;ql7k*IG&g+-TS%;75`)bCYA%v$xlzUU2le=fxM{WHcAC`!+j!fncm;lZn0E zolx`4JAVr4OwC$FV6CO%Cjn+oX7bW}!YL3Dl3mu^z%P!(`@X?gRIlm+W8qpUgFidy zFFQPQ#0;jBeN1DP5}fMB>$-4V7ZB)`8ikY$TrZ8E+I1rsni0Qp$Ypj-F2TFEW^HSZ z`@F78Mp>Uqy^2?Q2Yw_!Pja-+k zRZ1sGAuwn5?R;}sE#`DxOYA8m&E8u)FCy5HSl5^2!fjc66>8s3)&UfFt;8!XEd&64 zZ&Z~5*nkZ68X%^tfX0L#4vrdRMIsU1`xc`Ufmh0xq4t&<;n~G~l3>Vz`)uZ!qv7MS z$=1EG-&^bc^@Y3^h!iN6YUwy?BlJw)8r#UFUi7sfnS2EDb&1K&g@F2Bw+{(kQcS7( z+724O%%MjiU7Tl7ua_5cxd(X3N;UwjC4f~*hJuHpBg4#p&2-ghOsvM1F*NS6tMR>W zoKdQ1$s?yWa9!vLjr+vlzSUbj9V+^@B~)04im`^yOD+KDX|)B}6pG+-V%<$CmV6GT z=YmrOR*;q=9i>j{b6yL(-iN_d%-eD>&sTygpq@owIhR0}8zwp3rGS0` z-8Ie+Mv1UmAgWaoD0AeT(Nr+?*1a)Zu3>b38@xSROdxHhi3cg!t}9Gbv?hlvpD_&_ zwsoAR>7XV@* zQ2=^xJfl$a0&+P&Qpv8-Yzwb^;abbBwrcxGN|Hz z$b(6Tt!T6_yy ztjhHLKE)~y`G!xCh*l07F^^IwOju~5LOq4G`rTy|>4ZUl_9*f>pK%TvWCcOv=)E4W zfPKIbU54h+kMlj8DJqHs=omyhSdqK;02zJfgX;g zsrby8POxBrKzmvP3_d<%N^(yel>y-)o(C{_a%!2=Lokne1$ZtD_~k!;^shfK0PxFA zJGz{?F32Ao{f1HbU!i@!Oecx zV^la0q9q-+)KyRPAym(l(9i(Lt>AQuXun>Z!W{}sPd~feGdcJSv>Z8f1_xLNsX80p zLDa@SpV;Si!l8UPnc$==Kiz8>dfn#l`9E?r~*%i}b4z$8WvP%556g>ziV zG5Z`DxCC@fED!z;a;*h2NN|?T03#CDrPF%=_3MXS*P(*w{@%zTztTxK1}iQgqR)Ye zP@6I5H*mjYc*mGVI*7YXA#Bj7M1V9xpu_0<_A}HWSyfo6QEccU zDTjFWm^mf7Ht)UB)mR>b_4W1Tz0lZq@%#Oa_xCp$z*-luH}3t7SZnq;@dBl;nZT7| zd*Az>zka_dhO!yhE)L{cU3<@N@)$|>-eM}37)WVt4G>{zk55mglMJ?*J%CFE?c5$= zco@;Waldce8fPZ9)+R02TC=W;Utcd|CU>i^y6RS<6X=?bj5UmO(Ip4=NzAS{nnRf- zdak@A{DU4uW(Q@~y)qpmwQa9u4(TWv?2J7o^d#ZN42Q82U$2**eO!pNgTxAb#%dd* zh8c!Nbu)^baY4+Jun+E1TStN24h*%`dZD#dn74DU8LX9N)ItDFT$mVgX4FdwfR^j% zXE?B=SxqURg)(H13OWG8p4y11InFds!FMT|?@6_>r?xbkHc^B}0_y&vB}+X(+O-ze zTEi6kwfFt>%+5fg+2&xE9FI#xwV0&q^|Ir5GFNC8IS+gilj?cXbPyr%?%8%rm)M)> z5R*!4mFg|P>iR_%I;fuQ^J5xS_W9_xq1?Gp7%VusgOYihs^XOkj7v#$H9S>=kqHh_ z_bAl+F->>h`<6EFk~S@>a_u}Z+j-Ba*^%{3J@Ba z0GXDr1R-?^Ws@Rv+moD=$hD+R+8Y>>3!GgNnJt6eab)iSwB-C#8&gBfu+dloGLWYT z&4o0e)YS^J6Icw)Ru5fj%p*10OiM(4(BXULb;rRhV1?xN9NquMFsPXx%1uJ8N#mBC z0WKzLWE1jQQVgt>c+X*|PeR0@RVd?so4$btBgsQN9EIk%5DmNIHAClFB&4Y!c2#sY zUth1RTazY;Ps(%T^C$PA3%K^JJ~{a56IVD37r6Go%99_P(3`L$eY=b_P&RNYfs@%I z5r=UfGu6tq_^51~YE57rNq#!Vh3f+6iDPEkXS%BrI3;|3mhQ378JPq2c?R>#y@0`n zQ>Wl#9`4tASnM%?FfKv~D~b-MIS7a#JSN;SxmF<`W#zP=3FugI>Z(2-3;igS4&ZTS znV*s8p?+dr`}3>>s4AzXuSX}B*n6!t0VBGI@l6{XuLdiFhwx$gTvCg}BYL@d; zOl%&K&h-!gaHH1;08veoN8F)%YtOVe>%s5vs8i_oJB3CAzj~&fWqcOz--`kMs9%3r z0D$L4K6iJF`WPkkC=M0Vz^OLR;bW^j`#g9thYBT~{pTI@<)hKFtQ4Wo2#&|tVk{Fm z@}bjfek$FB7!_I?@|cPoX-fgAq<$FwNMXl+&248w$*)9rDr7@R&`{&8ct)gHQlxsu zDC*3ERyow_dn4x8+t&p*FgTxKKBk0W=g+4Qc0dv(qs4vtvwi^qhNsZ={UjdAJkBF> zKzl|S0ua&(u@Dc8qn`c~uso&H$lN2uG0b5#hry0<@Oe;Hy|@FAvw>IZ96!6oy_0Ovb8cmuD0<2$mbfLqTFYaR3z~PefVklRaA76=v1pmcgHK4n2xgy zO_a`@yF<+q|7mts>^~n6g3ed>0F1V&k~yPx^hKjP0Vfbr*&yNybsoh-yakU|j&G$rP@2*=_)+4vky8CYY!ucsZC) zqpKxR9ht)=7hYd4yHRtP5kki~DvZ>33^OGlS+x;L(tvdVGd+>+L!`!!?GocPfyhe? zQWs*x4)q=z&;{P_8}D0;cWtqfF*ly?MlR|-sOq3A)l4-nfA3o|=Sg-C(8OKxNl{O*{2JCG zrgj{Ug6(IvQVd??g#oyCVb>?-_H@_YSWNUZ`@YrR{C#7;Z@GtSc)Ihjk!9eF+fk&> ziSW4tfXLRg7|UWUC6vqEz+z>PiQXj{d}78K)vm%@#*F}G7I~%?kh|s8lCbh;PrW@B za2of13xrIy=9HUYTSl!Bf^B%xVH)H+iSP97%|!V+=mX6h1JDL~0|oUy?<#!%^=&_e zqOBcp0M3S#XfqoVrC!ScPth>wSs|crMk5;QwsIkeTht=sB9a;#MWzbR8B8jc9+v{$ zhs5r}y*HXF5br9V14K{8xDAKo99E7!7>yRi@sO?HL|QsJU3+Z$_;aaPYu3p1A7Uiq-rEbVFxB|p->BI@B;spP=YC2tpeL#ks!b3%jM19mFxNs= z$)n^-#CpXQY1zG6Rb+DB&;t%8Q;M9_^qUEQH3mzYbW)!w;3Y=wTVb^jMxYi$aWV5u zZ3@RBpm&2y&!I7Dam#r8+6I*4;sRF4z$a4qn&2>)^5>~!oipLdRR$EYd2+;)tKjDS zF6?_t3DCa~0${8-0{|8C+Bs6h1+cY$T~y2O1H(2MLQwHCHI7j&o#VB_>A^q#tAAYg zt{-}fLrBc07>toxXMV|e#sxi&`+Yl}o;a@D?a4L0cR5dM+!OD^MccVc;}+A??(h_H zLKdL1w9n$z?-<}1-_;LWf1n806m8UE^rUgN=^=e4uv(r(gqEP{5G8O&j(&3E<{_2< zLb;ROZPdEV!jb3mwD&^ih;Ju)q(*D6V-Z8H7Ys1fqj*qes#6G#iHG>=&ovw56FLI# z<$)ALzcBYt1hA@@BJ2bKoMK#w>(j11+9wz-3Hmb(e>s;`68KrR!6jnGK2tnCWEu&3 z!ezVm$+0Q{d_WXxcC+qT1Ld6Ic(xJx+`1nJDF__+;H=Zn9sFep{atPONB;Vk2LSlb ze|!G^5B=|-5e0fP zxKMm*e64nbWU!bpF!7XsN+h4e=@iNR34rLsMz@Pl1tV=Cv0_1@tagwyGF?y}fZ`y6 z4xGM!l3`0aISz8FKXp9^QGJ501Mrz)ALo5s;C(i=jez1Hmi-(?p%Y8*-}L8)K6AS# z8pJ2P1IEbQIO#hmA>BVOc)xL6Q?w!T!*=_^+d#nMk8qBc_!#@0phAS0c6~s7X1S6` zGK2RXa1W5BZ>@qGSs*a?{(7v{SDHNa`C$mdYBrv*p``2F*He*69R zl>{=ExQ#``x`fzAfV^g9;Sf zP(d3=HI~`MbvpsB+Ss!(P){ohn6f-HlH+8nZAP_RRH1>cEtVc^%cUpF;)RkKpiFsU za!DqwTP)Q2y3(`ab-Ojn?u7xcU3^8<#@?FlaHW#mDPZr7pFjVKzHdwosue5q zT7wxRH?CYVYqY1q^dQzku7xgvFv-Nd6^8|`aMlXER$?tFJA|)}rdEvl`B!>Eh4<{e zm0-hwAe|L72fcwEk`x|N22-)Pu)Y$EWUdRZ>r0?d8&Gr-*--LvWpcedGH()>ndsil z?IWVY3Y(U$t-BFxQC^J+T4fT5$)Et+7Vx#F!SN|(C0QBpk(lVj+OSW-Mwj}Idxp3c zkaqtLNr@3EY=-lUDeP|GE<`4->oZjYNbEVRP+BtDNE=P|t#+|olKIEj@X_X@`)=I# z+lgV#ZeUM=t+9AW^{3N}R8R$1RRFv|00L47)E-zlKql9^pwVS z8@)GHQd5Se?K{wzYV1+lj0)2p^>e>)y_O6;+p)i-K&dKBrW5X#3Eo;5G-}GQo^yk0 zWaPvUcWvzN_h3p2s?gaL7eOq9*>-o}@oA%vXiHu96N)5Jd0@<8hx7JHu5@YsOzCd}+bdNzId2nxE=@6sc=FL|x2G@!e71|Y zEkY?G85wfoWlnOTJBHH}p?LqKC>&hzg&$uRxZ;tBr#*#6O%!O9wadp_$J2C1(3H$h zL$N3|8Zi)F-+|t@j5jd{)to?fRpB3h|5NO}e^;6~J#U>JZ8U*$}A%1oBxI06(MZOj4co4fK;+6Z{nP zzRux1xs!Quw583u>P|ZSavO^8nfxB~e!hLa z_bsxib>jmbNltu5*I5l97C+ppk4Fg*X0O6ZQ`lb(p&~wxX$*W`ob3M87;f7YK%DuBDi0QNR*Zg@5G#*tLteowqJ`~twY#qw4J$=+5iR+`lQ~e$VfYzYS&h2aW zl2N78CIAm0GC4}T9+aBlfq0=` zWC|e+0~VadXkIvoQb0SKAn-THB%yy&(Z!EqVNOC?Dln0l5TZ7|cMPMy4vO;3OAPBN z5RW7O^Y=W@LM1E!oW8L*H_6HZz(L2dH%$ugZqgy-(?PuU(_^!Q087dy#v-g(0OV?Z zf;e%IO5KsLih;24pN}l58WeO6D01YNV^D?I7&rFMDELIT4RidO1eB~ASTGYEiogJT<-H-oohu6T-?&zXuu#6 zfmdF<(MV&}vo|&xzg}0pFh=9i1b)0;%S38p_jaLJv#Gvh-ftzl0o}in z>^`mlH_&Z&CAUMYujMT~0x97nCQ}J+ZD4B1;QPLj>(k4wp70O|9l_lN_SV7W{rK*| zi>>ii19WY%?9t#{GN@yK7pC4vygmREa!%LWaF)CQ7>lYIZ=?aq?#7@r0VIfAUnr0G zRKHxK_FG8=)qoz0HtZt4F6p4^-k8}MHMbUm!>++v#BfcZxMgByS-RF_L}0pSX4q_E ztLQ~2K4%JCVPmk8D63K+@F*ySg)~u1Gs|_-^Wue?x4@Qs4epO_iYZXFsL78me^@XWo?-JmgN-j^Q zc8NpRXxB$>1aQP-6Dp=-WP=81Xv>Q(SKOM=(_k-f1+KXeQcz%`%&Y+S{l>~bT#0?l zslA3+FuUbm^Ko*j^GD#6*g#3tJ93CknT-*mBOm=t>u@zR;;=`jGX0w6COv)(gCvS&DM{i)i6x#YP4 zprb)*51)~WgvO%pt`iSfH<6bT?T7_1W&EvTj@86UNL^u1jfUO!U8O`4YpEdCtZd-k z0v-oakL48@s_2%QXbTXrbG`be7tZW$*M>+gRBX$5)1o)6U6OPJ#C0X=E)3=jx4^_O zxC}5gup7C8)0US5_3g$769Kx3+CLF-p=M^N7KEzJV+v$@B@lycoWAa& zybRJkh$+yyPg{w{p*jbv9zdOM9gC42=qgnAaLD08260bg?hRavgZ2cPMr~-lg%nlq z-Jas(>+<+I@&c!DJH58(!`?8o3Z}^<3Y_15{Dz<3 z-~SrHe?O%xa8dvc`)CypAa9+n0j$XeJ06Bx0*G?jEW!oO{-hCub4}oxIp1fjpw6X)Ey-2tiKdpylg-F5!mXqMo?fJXSH>jOXV zDL*fJJ`BNV^i#2ad=-Ra41P_)4?u8Q1nIKltS^T@97D<(0egBP2gp!;)#u*f*ROxR zsO5k1U;gF3{^b<_{^CFLr}I}W8E>3N4+8%gMq%se0SCqf7Hk^VF7o)W!~!|BDK%4C zDA)MkFbBEnk3@;uKt~#)B=0~?Mn^L7$}#)BB%e&nr`hh!q~3^CWc* zgJTf$QFCaT1%CYa@dNw5+n|Q*m?#Cq8Lzbm=zU|Tp4Xb5IFgud7d>ZE01%P0+{_p; z$Y>`?f#I6T)tt~Q@E(wfsv7|D`bu>4EOLSi^XwSZoK!6JvZ)q zTP~}Dk`RuJypXZxiVIa6_g1Sw&M!b5W>kO*TIyYvs!P^)CS~lqare08#z|BJR%XBN z_aOqX_ePpIo)H@)a1U}qud(D;2VnbHOk)1@<2S79<-^zU#7d93Z3yP)x%d4XZ!?2k zg~7~~X=kXB5@g8;@O7zQ{dK+YiUmnV1A$agN6xjD)_-kq0*U3m=Ns}mxFjpiM5z2m zWXhqxbn0cM45k8LH>TdOyw~P#jhF)VVC?ii=;7%7msJz5ycFXaSh*1EvJBDFMktd$ z4rkw6YR3@Eod(bDtrnKu4N%45)Yvz}XM+2@gCHW2EmcFVg#1L^>sf=bFE9-V$IyU^xA0bJ_&dlPz>BvbKf#Qj0jw2PZ2hKWDcngqu~K%ATN-(^s&$U zX-k7O@=nDHJ$ekG9REsMp1nZ-*(WTTX%jB3q3e*o;21oO~RJyq>Kc8$!;2!XW# zy4meG@ur4(FX=~cs#JYbtHk-8{Py&AS+~CZ=Hgsom zTHULbxeQ_?n(R6f?!p<1E9HmON9Sx>nflBcq=^-m<}3`6u|UImVy9(^Y&SGt^UTZ) zJ##o1Pyh2FBoaMA+RVV`JOj)%D=%GlBO(%0I`e}`Ldr5iqk7l%(sS;kbR>`l*e#L2 zu8)sRJKtMLaM0UrLP~Mu)gGKVrkp*6MSxhN+|q@zG=*cMLLQ%%fr`iOmNH;TIaytr z))Il0aYUIDNSraoL4qxR077E19Qj{l#3b`517;8tk^%1*588S!=s)rqGFe?UWp*t030)W1QWv-5l(ofwyHG_R z6=!*JDgoFaQ3sf5SW$5FJjC;M=MS6*$UKktA>>)Pi+)|i)JImo$ zihlY5HBUX^cT){$&@+NQcby~hw5kC^DW^W`^MEpc_r?GCTj%SKR{R5hAOK+gnLjya z#&cH>q4DTjv{+O~e-^dmGKUS;F+fXrPH_xKBFS(OZOJFk13txRdMpLkMEO&PaXizGgibv75N z)ZYL+V;}?Y=5N6f={G(-rosaBngVq7YGN&ohd3$d>c>&^vs2xx>O)F~IDQu5`+aX= zIg_8OgSuGy&$=Bb@X-NRzwXcFHUiCE*5}ZOJ!PF9wWGe>PB=+6IChvW-YU9e(slla3*kUS@$rY)UJ^<`Me2lnyZ+Oe1TX0;E^WNXQ z?{CeJ4~p?z3yB3p%yD~H-<@TW6R4U8h}m~pP*EzJ)XOZuVbnD}){h{lkLiNqA?ZTRhJ3`c6gMX5;;ZE zA#mm3S{V11M_i03zU!@YH7&>Qjd#7V{hHUMQCh!BGrNlsfr-*IZ?Pqlmn6fHFPrj+ z1spqC0+}8i7NI{!VyX}@Q^FjeF>8EZ=NUzoBqC#~Zd7eXCeV^e4|Of|t?^vR z;gRjCcrOeSy9b<%wH6~>t%Z80HA1f+SK)-1S}7t2KYshdg0Fd`C?Yl5O+aON7Pp&% zB5+*_FpFuA4JF4ReWr@PpxPg(q-s}zk&LBSxt$P8>TeP(h7l=4N*D040^P&)O43Q@ z@_raffyPB#*To>w`_^nSRW^>{jaXzZ@zJ#0I}jKa?z+(k?27SGsIJBqG z<IT_*wuFPcb>t(U5#CD z)LnxFNH#{Q9+{dhx$&naR$Q~@SnwW$HBjwr0$hpP(?QN$`tZn7V!+_2bwMLtbsZCK zv&I;EzzBXE7SYA&lIwp;GTrL?x7k~nWmVt3)I;XcTx=Y`vR#ZO$k{_s6D3YtLwnLh z`D{}oZ!Sn3}yj!7rJ!s`k*X?<5D}hh&?`a2f{h+a+;dPvd1ho3$q4~Z zqxK@@meS71(O>-8Q1r%$Z|Ombk=q?M@#)Q;!D`T3UO{L_-l2BxfYn&PLCpZ{aQggL@j`K& zN;34m5|^nFK>i_m4USa{heYyoB@k&a<$&ZS`be)7t1oOUt?3a5tT<=h9FW9>ub&TH zlO){I;CrUePdxH#0@GnnhCX*vYtiq;L+TwB@c}L7?+W`rVwL~j@%4uR008{Q=*d`$ z?Yl}#cFvq(g3oH1rzkf{;~BytEm~-q0R&LU+Y!)o!v(BZ>hXdQE^rot5W$#ZB4>uV zp*}MopsrQDFuYLP4!N-G2bQIHd|`w>hZZ_fN5%yuC}+ff5q@;e2M1a#7*{%xwLSD`+(IZnOaSTj#?E`IkOLsNz)j8{V#+Kjd z(9*h#7_mpb=Jo+~+C%i+yyxa%OVKn7gEH~j86^fd|fJv{TZjF43R^Pl1zlLgZ!wo)|0pQ9+tdyZw zIK{7GcNy%HoE=v_#!kWoWDw_8r2;AA5beiZF`8>?^}}@j^Sc$i1i1iIMbzm^GKegXup4=ss$V( zq&#rU>XSISh{eqZY}-xbNHT3s6vXuaj7b5bg8U6EVaT589^6|a>zW#)I4zc$i{7ax zVXeWG`|OK{xts0y9czN;rw3g#1(}zZ*8&^ZyJzf{9_z(R<0O$+PCT(37zN!YIXYe{ zyJ%v@Kqb#~iv*blsdSF6TvA6=B4*jwHSMdg0XR1J{?>MU4?2F!2gIbj=Bzh>l{COY z*`O1(_uStb`@VHXN41ncgQ}6q-fk6%B~zwFsars`-5ds*1d}-fvt*^yVxUPA2>}$~ zaF`5AjiSnm4b&m&#hR8A-UWa;L9s-;o8@OggDtQ11I(a4YXzr0M`~nf*drj~Zq#Z< z@L~T|duYF$sTXi!yT?<>X}PSFbFBB^{l2lkx0GN$S#+kkjYG5DK`b+x22OU_yP|<< z3V>gTl>Y$2UF$7S(=K_sF0+bEt(n>dOykN6c?B{qoukm1Ok##~y!=x8V+PmPh4p%Y zm{CjC-xeFGMWpjG`C?RWfE3{F=#n9*;7qvcrHMr`jZymsPTS3Z)M(JQ zheTjcqdgS@IaozkVSxZA4N%pb!pg;?6qUn3Y<3nJ@4f#)!wD@=Rf4EubZ8aDp-tk$ zMDwUGo%d1g0l*lnoR4Z?^x5PIV)O3-Is|+xQ`7(A*N%{ z^Yj|D-Qr!Sp4UAfnsZOElt(e`U&N=y_WwoQ8!gF_?8braKxFmYOG*zine-srFIe0E z|0wO-%6Ly#27rBVkE|Y&qR0n{GfkVzb53_xWo1Sn;0}jloU2!#g#W-;$2GWcrrN&= z66Hd~#?Q2w6fwm)Qw#JujUU8?^J?Y3;~dlq)PrFCrE7B@|5V)tG{$~8ehVvH6oIvV;=j$Ki*gx>sABzC^C+x|5fHVN} zQovz%=fju@aN58G2LElbJhhTl(TC3Y~O8*`O#*`>h&(pW)&&Vh&VF=0HF;LIEb@V)nc`@8@6_k)=!avsSo z6XRLYa$8PBEL0cn`;8eOua^mnffTC(?~9???sAPnz7or)>*;UmQlB*f?unOB(H~R5 zky_I=<@?~Bn)xU$7&+HLBAaJq5+6uW~B2N!*54yLK@Y%*AVx5}< zbmHr}5WQs{_gcslrOYl935mun5V+vk+ zZsY}AUth>eBNOj>BVx4pZqH$6Vy)LO0{i{enoY^u?z?RWxM#X7Gwb0}TmWQVmrGs< zm_e~Ey9+Q9d0j|1pbAu^eztCO1MhEDTqA&ZrIW3A0NdB=GJ4*~1Tq3whIX-;@!5mj zd&)h{`6bDtz=nIy2_ORN5(s#$3&~(ypX$Am_+?`rLR|!b^-5$9-uD*Ri6c{Xs*-xI z;&C0fTykof8s8^bJ#kO7WH1f5}iCuD+&BsIj@ksJl3)&gw@`eS!!-W)y7(BqKlZB+4l{C>O&@& zBy)6jL=ep_GNv0{hp+hFAoaVzKXgsOLmFrt7wA&`{e2?phuY7Z5WQlQi(@u;$N?-Id6%&-UO@9Mw* z?e8$ae<>+FWf5qSqS?wFqY)vO-@^$g?fg+p%K4~KodZ5IERNYI!g+rxrw3%hE#at1 z0jqF!eu{~ss@?eYv^$I)+!hoVOA-Mqe?DqjU$3YJ=X#LO1`kE{jIIuW=q&|KfcAUw zCu>9AjtA?Uo_s!X9~TXrx}VfSg*vsPK19Zd$UAM%;wM6R=TQ?B(a<_@a*X5Alt{!O zg3h%a5N-e*LqwLp$D>ri>C+wK3qvcMsR+707y4o#4U%s}70y~2Knm<8a!k&dtQq(` zfNpWX=bBF%O-p$65Xv`%^!=pW!cDOi=NaNmYamqsIoGeO891+V6wWh0kjOlLdO!mI z96Z1uiU8pM^lx+4(|LqqmQL09X#e|c7=8{-*e!WrM(H5>!`_`B2vwk5(w_tN?4B(7 zQ$9T}Fz_4yog75l_zDWHbx_`nDxh(|b>U$=6}9xKTGgeQ(O5rMepq8Qxsr{u@pb*G zmJS*SjTdACQAU+s-^Yke^xYAnnX%4uub`50$hhjXMWq3=aV`!sS~I9Ixey9$-8ixf z2S&?tQcSvzQ9Y+ER0$cK=(DiXz&ao4)xY|5Kcn8NRImFtheWY3cde?1fY>(Ni~>G0D1^lqP3o5j&-A%Qa&Hy zL{57MCf>i^|K;y~`zzn?8zF5OsRcO$a8z-x3v8YK(mdHgiB&i<*c(k49 z2WS>G5~=K0p-Qa`Z~~ps$fDz1GpeYe3z=k1qxV+N)eL5~*3E8CRo^XAE3ZXR0|lze z&!=Z=whodDIU}PXVotxnb$#LM`T}N{2EWURoaS>~{Cd66RW=3#;<_{s8^tQl%z+Qu-o^3 z%ls-5GdFq)wcmK(B`_1}A-`MG0ID@kDlb*UGJ@9%bq9<{gk0&QxqD_%bx++JB=A0C zx&{VKjt$<-Qe18HeWQ0B6|tsr(1}Hl!Bt=qZf{xYLnTD&2N6pJiSC(9N%nUGv~Pe^ zSfHx*x7OxyVGRF|w%eek_^FW@Bnm)lG~8*a3dqrZz3kt-OG7h9BPPSi%Y+Y#kw3D4 zxMYd9W|CtK8BX?+A!i3V*)wT;%;#gDr5W7_1f=SXfla_(nK(q& zu3PO!(wJjfts-)mZ$u`;Enov+w@8Sf&dM2JEt9vJv<8yXrSm3v3`F(R^Rh8!VB}*V zFNGe*88H}Az#Nhqj#C&`1b8hSzoi(cN;NUr05x{6p%^-Qn88_Vab0UfrpF{@M%TNi zcWb<7&Gar*0F=3zQw32>Gd&TBl{vI5Ii5t3$iP&$dh{c8p6_Dq)-z1HO07n#Sn>4S zgPIV0{1YM*-+gPH9@4t|sbclkJzbY2;WL~rOoo#93065KDlcN+n|rG@0KgLmuC;Uy z&*&Pvu(W2V^Lb><8OzI9#-gWQw_*`psM)SRmX&mB=@^bik=PsM#E( z+EOz)`+h*03Rh}HdgTQodH2R?$pl0O^^hy*VnU;v)2=orI9v;huzEyO0G^a1y*DlG z-nH?JYco{J6v;%9<`^VqEygfvs{i_z-w?##XSyPb`NVuCP8-$JTYkW15GNZtRU0WK z1x`=Z6+a4NQU;ClWyQ#6HaiEWPN)2LTl#MRck<`{{G5v2bm30_Fh@07R(l?~KBY4i z0qrviiJ~=PBHg51^)+a0>jA&>RKx>~$$Cf#H7*f`%}5B)bI(cN72BSQzCrKF^SQN% z%@|0fI?iAF&?pZ`AGrPo5d+N6eG_5gJj&R^OHo**d72y$oj<_ue1P{HWdNVlHV)Ro zQOf~`gd|+z6%g>VhjVqcF_L4lSRVt8M+pgp#t)K*{QLm=^RS!H2X#yMS$`-0=z)_; zz-QR8%@q{z>;IFlvzY!2@c$1+06ZA(^EY3hd+N@T@wx{M=H^uLTWs>Q4gIv}qG*7p z1YrPG&(3R5^8J#>@B?z&ZkyloJ}r{c_>PZi%zm8kJZ3UBD{=abGE zJrGI&*!)z;!iyhrN&bwuv+2kP^rH{c?2TZi3Vt@1ViwdoAWWd`~qm z){_tPFhGRrX(Oj&PzkBEZ2%<2;!y5Dr)myKY+{as_L0=OvNDHga9hVwCyd{G<~TPx zI9P#jQ+8N*lykN?Qmh z1Kq19%LkAF86}cpB-spIT9UWq9w=Wa}W1cMTHrN z$Or;gzM!7(K;~ejdbn$jJtfdl9;YO+002ZR1J>Jp@S1MW7;N_3`$q2@$u%Nf2C**T zuWm$McwNbU)Gn~05|Qh|P?buCM&dO~hI>#yZoXbJ0(17*(}?Q}9HO?25t%Ze+f~?8 zc-IZ|#_o;#yQ0d;0t1;L?rM$kd%bYI5|ayaZ?#guzdJGstRvkEPUb?+ z;sHD7oXB#}2jw_{w2U24p9uO(PCi$ zaIg|XnOUmYN$XGNS$i}U)w1SZ<)^Pd^@+@vOC}}9=nbDl`t)7v{xpUhP9oNYV7RRej%O+Y%#Bm0KpB2Eo0 zPzAL-x&28>8WGo$_7{dv7reZ4K;EXY-Z!y;_utXQMS;VnDT}IBcQ&Y5x@vjYp+$2=Awe=^RtJtT~blD>VU(TOrH9P)hz$2?a@pibPWd0tn(Hm9g(+%hl;atNg7;~UcTqXKrPnN@*5 z)+AN1j6U8W^t#0P+c}p1(brE^z#sSP4@Cg{b6C^K{b zFenEaK{A14IqEh5v^@b1dE-SFL3>9hjQ1_mkKl z!;RZB7osOxijuWzZbqf^ipNo zca3Z_ZU)Ck`UE`8TcDvHFgaGkAie2c_OcxkwK0Jwem>0Hr+3MRIL}5t&)tcOWgHUL z&a(;81Sh-+ZNj6QhK_zr8R6H^_(N43K4TcpulA!1IKlc6F z6Q~ZkKpgT$Y4iCvgOPcD@d^6EMuMny7jj+y2?$iHy)~pQb|qK$?7j>8mW%gvPfx3- z7Kz}9KrWdqy}#d22$S_%XtZIUd$yg$xe_+&JwL9qX?4hoq?a@>don`6y>uXFraS`j zs7+L1o*pc?e+x3Inq3-=7sUHpwmRWP@n_DjNueCgmzD=H>{z*`dhot~Q4;_Xi^(=9 zV~D4hiYMG>DbO+RLDgGT8xvO1MBO49)EP0zb>a0&q*dd63oym&h1XwSGtl@TtxHvj z5s5_Nx^n14uV*W{*akRVs&Zeda;*|km)FAA*9+CRdY4zCdXOzbQ<7R$`2#VJQ+QgS zTi`v7y59swUIRE4Nl7WME0ODBu9zNzapAgN`1yom2(4!9Ih`_bJm}{}v zsCM`M77-C>WWEFrQHYhZM@og+8{hk_d%qQBudlE9dR>Q*Kvf|I6R%5&H{i-A<#G?; zz8m&~z}+_n@=-WE;52neNHNxvfmn&l07?}$V#Zdb5t7UT!z8Zt5>O)0?8*4_zti&D zU8BDCuAyVZ6@d&Tqzhz(C+;f1VR}&2n%ZGvPSYRtTzd=TS2>{+$eU{|#~~|mdLyQp zD^J8o4YMB8wWfN5;dHJPwp{~X^TGd~K6%T5u=yKx5REF6Q3D^Z7uws3x zRb0RXb_u|0RGY~XC4Q~7&_3tpIlF5l-%e?>yS9ikl*~P^^#U0^t%(^_gPB}zk_Bde%IaJu;Qspr~+^veQ zyvt;i1<13+bGx)RBG9u@uH@_QJ=23S>9lg;{T}RFXZG%zk3_#7K)6z%`8jV)%Fn1B zAy(MSLUQ;kh>V<-P8n*emBqd+$wXHTYO5C>CL>jG)Z%mH_Vh;&UeyR{3|(*#>r)I_*Aj^C!rU7*g$yvIxyqSZIAm~o5PyCB9d^C{ z>slfp2S+_=!)nm6Or>>!dH$dYPM&xSw!?*L#1eZ3rJlS@NvY~9KeO% zu(BZs*azsVkHTx=oKYeI#=yT?Ij`Zl+9YaS?C0LlP8+I7p8x;{8ml7w zZ|zNf3{>Ea%@}li*iuGeI-gBrk)m3YykC|6i$stT!jkv+h8jXE!nUt z(5J@@aBr@piOk^Z^&6N8b&(Hh-zd*Wdw+k&eShP&w4O!@V{vVu3GJm!wFLLEiWK zZ`iff&xaoUo9NY_CQ5!Z#h7Q>^w1A- zfy5fCMFIkYoYS_}^GwrN*Gt!NEzL}y1vUk!DRmB^N-aZUM^$}}cCR``c$ADoaZJcs zZ(T!-WzZp#YHDMuTw@aW-baZ;Akzsp_4$;RoSxl4)4j9;Mm)XDy*KXrRwdA?3`V#c zO9W~Lu{;l+W81TUEV(D=1Zgc{5-?%lNkF&=nULq=jAx}Uh_;Q1t_ltww6hE13+` z-2%j0_cgq?8d`Gn-#My}PvcSksA}A(sb_LWM9fO{wpG~8oh`4F**GSe-6E1iqRy#K zi6j|nOlbsWM9S~G0B+qw$#mo&G5}^knZJX+ix^@peC~00Ok@zRYhkwORu_se@@6R~ zs_wuWDd7ejVh_N~iAaYGzwU|=hzqrHQN4)axH{FykrGiT$;!(TWqw@c(?GDgLlL{w zDh@=~27>s$`#aTolT&S7{{4-z$t@C3F)T(gjUVk{Z!YGHd$#)|j zB`lp!9%T^>Oaa(jbe>*(y_5|DogZ|HEVq9wIV zj!BLFQ6MV0=ELIFQQlUkLJk@I@k}hm$G1w0;Lt0yQf1@~fRihm)HvzyIL{ycqvtcu z)jvg1g3qv3R1Bv@ELFYxhJX(>N%gZ9grzvGu)D(T$azz zm@GK=LV6m2@^unPzz+ey^LDD-9Ec(F*N?F;A>!a*!J|CmVS0=Kg9m59&*R7j@UJ2P z{wO@bACCa|XTG#I#rTW+KMPhH_!tz4xlL~fr~)xide&ysPEWrVn!H@$MX802vtc-o ztVWA{fYL3SF=K{fF5<*$4zSmz1wM-nCv;7qBXIhWX0*A(;L;G(qhRO_`RQxN5i(+Y z(5ip$At(_}+F_%Wd@5OHpMIlukZs=!2Ug44;r0aWQ|-DFWTYr4NmfDkbHb)j zN@Ne?djekfvm2GbS?`sWcnwB@4r7wG#f6{y1tXL~m*w}GStv{rD zPJIs#ct0UN6#R~A;RL5AR)YeEqnxyqFxiz>uXTE!0LeoSlX;G>v5fqfC58jz2{30? zX@UZp!7q(<>Wbhfe;U;L#_o+ks3#gWoy(6IV?*xynd&+1Zmgy6d!}#?eGQpFYg3#< zCYduSDR?IF+x1elhXTosQJZ_H+8{$5GyP-9N%v&Pjhdbzyg~!P02wIlY1m7^(p4ZP zWujG$UG+%U;h^2!1Z7Nk79M->iuIA85xlM?hyQD-&%Ya8rJ3ZE!B^yR|FmMvIcxW= z!|Zw;P>_}?e~cZ2@i_TQLD1^m+l^`YAVe-8I!pOK;3xpvLw}s2s9^sA@K5uyHkyO zL`n=?>kC(ERBKGg`(WS^Xsyq{BPDj6iy)awd<{ZoN-}G&g#@P#fxBfWxv*UAX^)dl zCpDf%0X)i?{uT(Rl56tH#9A^%WCSu!0wS`Fp{kgUqE<+caBSO{2)#cZT!X32qf#nW zfJd+6y;vK&ZdfacdN=NU0})`pfU&#zmbn}v!IVu?KdoBvoE0*@JxR|G+rHAi>e0QZ zs$s?qh`P6b_OySs;-L3ZM%Z96MGgVed&@wM{Zujap#`>YOGWj=u6FJ66YMJv4~uzRZwXS~)qmWvXgNDzXaQWd`gj2-KAg13Im1A?g_KYq<46@qmWXe!k%*jFBCSp( zFF+HWFi0t%&gZieXuVV4HPbz5!g@*xdsj_h$OVu(ZwrO6a@0ZNkSVN|3X9G2-*D6# z7LkZ015ceZkg=eF%j_*19G~f#{haG77AB(4_hKm*Z6&5KF{)8!wb7$V9n(@e>Rh)X za-=)uq%Ea5*_fv$!z5NNY9ufx^M%X{=s?{fa^;v0XMlWS zMAZf-MrU!hYs=g{v&atOKlBW9j(BFAds)$Hf=IE$hKnW#z>sUa-#A7Ex3Nm<2&;R1 zhQRU4%Q#y+<$$j6f6V^Qc{0xTkBt3jz5|VIAe;cOWoGH8>^xBCVw=rV9%`r?N2M@o zc|Dlq0BfJYRjMJY+k47~)m9?I&$mnz_{JU88i3El1>I+wC}=G}J=^(F*uw{V zm@9kK(I1B8U;g@6{K)^2uRjF=002i`PM@qg`m_j?JOjtA+9Z~wIOzp!sfbJ`=GpW~ zd=@=YWWh)#d_Zwi0jEg7Gmzm#7}*A`zRbbH2&os>OK$ubP&V38FbTbpB_({6F?ubt zrK2S5FlDD7Uc#nPg5gC!oiR%4-2+TD0kR(wLW@!TmelNb zNGpCS2_PgJ1;7g!Hray}T8EmMoH90YaI8^vIwmD)E_1333Luh1ApLdZvbA!apY@AVD_Z~D#J+ZC` z)QtQ8VLt`mtJ3qXDQwTwu3b-i!`Q$pztpdH*FFjxK2?Af8qs8+7fWPFri|Mpne?QC zNR8g|sFP$`t|l|L_Y6p_nW~m218oGBj$=#&nq`@KtgpePDv;!@4Q4R&!jjAy`!0O{ z+IZL2v$#SPT_I5&eg<5h(R!R%sb2ls(69(Hn8*dpU6=q?9x0*^UuA@fmed-qaHT{- zZuD;MZrrooDk2reslpuqR-*|IlgsJ~E%#$E7dZlBi|&&aiPgOoVnXCa@In!f*Mlsk zv}c(FLb7^*>{1`N`lD6->mE#Ma>EP|FWLhmFfq8_Z@l-n)^G!W)+2hbs~`L&7U%*v z8ojszaa|x2SO%ek=WLj;9a9$~g5o@h$S_G8R&F@%M4Ax4!3kV($(5WUIQy1Ud~%sc z7)wz-{&M{1QCkPk%x;9b*dV1*-Rh`*y)GaGV&3;g*$dYb?V%Yvm;?BB4X30rXf>Jx zJt#cmG-q8hTwEj?H@Zu{GYt$ihkPj5BcPzRhML06Fb23XG*f_zC8&8EkoY9CJ`(LHRaAkt{$3Lq9H2I+Z>DiDb9$}0g)$;I``h*-Fi^Ovtza4mj+ z|GFYL?-3D8d%!$I;iHx&2J0F1M<`#F>;Cw>ahuJlVDsdhA%F)1HYy%UQ8VCJffWac zI*mMJgVRcluJ+$2?Asyiz% z&{E{e>&0r=v+f3%5>THWDa4Lfz{qS|IKZF7DpnWy5l}v)m2B(~N5-yuuX9+%Q2ogV z&`~7=J_QBV>Ej7={-@0uj$4OekE=d`PrrX!6X1L3XIRrFg${xV;}>IzhJNo515iov zv=Z0BfiuQ|4xT3Zl&h4_F5d?nf`FceIyi+du)W7z{NS9IddS@mZaiQ7;~@Kg<=3Bw z0QitfpL=W>2_IPzpG{rf@uvcQdOyxfN#p5$cL+rC{KvL0ixy5=-g3;G$+n^(AE3hr z0DBRR{0OF;>QcZ?fK;d3xGqm$a8)YFi^KZ@|7=D{|!3AZubCHBZ#FS2{|?oJeS!AP`E1JPPBrUYc1?O zKx<4{??NXf`#!9H?Pt?Y1AEVijH1lcXk$r{1(;kW#jT17ncz(Z@>jlI$^;Tg-fap!KN!>_!z$*r>{PT^ACGTp`29-KxC% zxar-Rb8pO&3|wD{WMJQ06@pO`aQ}May|;4+^e>X!Kwt$6l5nV?t8yz~K^6t*H}NUNWw$ zQk%qG;2cn{n3s;7kD`f6uBMfgGdw>#lrY@xg-;No+K&ag*-BU*o3bk!T?Y!e3i(iF>dHmq8Zm@$kqQ!8MlH9ZFqUN zK^rf)rY^NoF3J5<_kE8X$J_UWke9-VcQOYg;!2De8ey$`;+sq(4R-s}(spK555vl+ zwhUkKF_Dnre1I#Mme6XR_Ho)5P&?F7%z%r;5cfR~FpNydQv}H7oXG;mM3?l$1E&vM ziC7Dix#`d|)2C`)yaWv6r3b~cK2(*&Xsp-Fk~*TDrckX_frSf+wO#(7Sur?c|^q0`&jjWkyZ3=O}Noyhy|z-9LN;JvC%9L4=`5lr)dXcMcYN2 zL8icYhVlpz1=QHSCN`VTHA69kHp$E&H93XOhlAt$O=|rhm0zM-@xpmCkA%$ZiKdIB zxOE6D?b@@hg^2w7#*vhtVvba71Q z%)cqJrwS`-{epCmJXy6e5b|RK<$!RCT3w18x|b(`fr0MzW1jypTmuuGvB<4?lZ%!yZ)5kW8=1fBtORNgCF2uc!VKO zwNvp|IDa$=;K<;cp(BY1pQ+~(^}8RCE=84MGEaA#RJ9a|w}?}T@Oyaqr=KGal01+0 zPlo;htbgwd_@`f=jqpnnEVHpV#CfDK|faab@YF**-$=*?M;)4%hPB~gYV z;R>^>Dl)^b1m3!JC7ryv+{Dt%^Lbp`{J863te zYN#b524Y4*Ou7J)tsem2O}S6|y|t;O;5hdU5F+i7jQC6%(31T;!#L{{Ex9A0Nfhh+Xdur@_jtx5 z89awyCvgGbirJgEzOK+S9mb`W4)tY`4fRF`iPfqs@9nmU5J|OJcnH*KlTd0GAmv!x ze*R@8MW*&nx7Wd#-AzDkfrINSzzIoB$2tzCDjYGmH?W4dUQ6S;(14Rt%^g-{J%0gy1oH~i!-1n_HN@)jW0bFn3#Bwh;3KOr?ke3jV5iQnP6E~ea3u1boq>`itY%7*kaY%QkmIQdvq?n;uW9(5pKq^FK&6)f9o1fqEBJnZk4_>m!yT zayZ?LLGZ%t0&|eFu;-147gj4Tto>Guw)Jwv$fKn7EbhJaOsNX1ssSc6LaaZEc%z(j z5>ar~Js_+7vj>fhO)E6y;)N--nTy5{8~sSTXG^sgkO>GcAR?yj zH>(S;Yhl|XV-=*!v!PWudW&xvjGHxMfbFwOKwVP=a%pWVw z0d|2*nf^@xp*9|U&hfZjtt*kVFd#h6*^rz)fSfd;p%^W|6bLPJs++7I1lpYwtJI3R zwXO*~gq9RYWBx$oghx|kjWgKdFgxt-BvqjRjrp4 z1ewHaPIqCrDdiEs>(Xa#VmUE?+u$xZSQ8k|%na40XXT>04yZo~Ovkl&jeD|X+RMyD z?Q*4btN8nzr#hS6Jc$kgo!S6;qZ-Ip`nfb*XxAR$*-jq4H~_k*84U0HgILpQ0}^=Y zK-I}Q>PJ>FK)^XoqHC>C4*dZ3+~Cd0ASc!!hnifYyhcW#d(de$pGX`=;8KqUiaj}G zhxbnd$iaSZknC7u;JOURDFQel&xqa!;2PxiAS0)DX%r|FmsYqpU2QbLcKJ#NDkHc? zB8)y2_i?E$2`lNeXVw2;a2`(b<&kP29D}Qss~&^F1aUXO zk#l`@I&T9`yK9`-{p5${&1aAS>;{hBwMmZ|6hr=uP!vrg73#owZ=bv4mR2p|2fQ07 zD~6vIH{&SKlK+nv!eB)9$*cg=JvjT9F4=D z@#_z$0Qi7^^EDsR#%#`0)%GSZ0R>gL&iC3fL;$SE0MA$v2(fS+k!lQ8M%c>!C7T)y z&se&70tctT0yN`&KGK!n^}txNMKMV2%GW%-LGuKg;c>4Q_)LG`1IQFa+Xss_Ubqr} z+=u(QHV0Wi!4tsY<`1hX;h}om+lm7PQ+IOqc@pt3we&%HK(?fGa;fb{onRKyduG~G z4=iug)!T~!N9J@09pFLj4_iQ3ljG!4On2gdYy~(1=w-}3`d;|YIt0e@RX_iu3ON;e z4jA>Eelk{cVDoECo-l{!z2V^ZRFsYigY-mU0Yg$iw9V3{$)q+}G!D!Hjk;Hf_9Uy} z;0C#_K~Htfw5s9(&7a4}k$tT-q69vbP61~3&IXtfxL()P0Lu!9?tLV&dcM<=8}ou3 zSv5{g@<{by?^{0~Rte{hb1e`(0{F2%x5? zrm*0CZ6EM6wDel70$2Ec9l0zAQ^jsy#mEZtX?L2LvWEq;@miOYJ27(iuW#IYW4Gk= z=~jfy)QCu%`jze&S+2gMl4&j6#mu7g3WOD1bF%zO**itWT!kqnU$u+bu?CzniF zwUz{t+z0PuB`_&B8Tk#^KL?Gj?R%u>b}f0KGzM|0?dDpF6Dqp-B3uR3$jGK#;Qc(Q zb0&RK&zu4Sk*R4TI+LWdnnPr;(1B9&OJUcfh$dwN zQ*9+qFgQ~^kEhFG&iKqI)QBWMO<{$e;WBwRGq}vUtBR=%u45>YTW3bQ_2l;2ZM2Bt zxWHveaRbw(z~p^DjzPQ@uCL>xp*q?!v#zaygQ z5HW;@J1Dt`L@=Z?bA_|VBxx#{36i@TyZX6LByh!xky=3kQiZb{igD6SCGkyp;^_1Za7B1C$H z7|@R^u2hNJtvUwh&brQYm2punVFGi`G99T5Pg3LDp75DV=OoVerQSGXK$u+BbEB`v z+7PV|Wt!T_&T$Ul#7_x%=oyOy)HOe4ZWcb~()<1$`+ z6y1>rBsynox89Btng~eYW5temrM97={oslwQjVHLpV^=8#~=PYUw=RX;PdrBF0U<- z0cR&4aOaO8Exi_e5K|`z`;`nXPeL~avt#$rBb!3HQdj^+G7&9IOQA+A(E;GPq;uFd z&Uik@MFTtq%b9i`Dj$FhLMB@<5cjf*elA|%1d`&)LH}Go52>kxq(x+GZ?u_nBR?$M z>5)+akkX9wa$NtaW(}500@;u7y`F zEDNsEih^MSuK;VCjXtwt3k-5uzO^EsSj{eHg<@TsW>uK?^H3pB~4_ zNDjy#dF6W6kOZEJPZ|q1tSa1hq3Tw35CC>H0|+d#)vMcM2XUM#f?bYV{dS~0A!@f< z2O94h&aHhfLa9If+K1Y&MwOk)XAIy2@mdHbgMkY#!Iun7?W~j+y>-4 zPpuo?d!x7h?Mw*Cl%ZD-be{>t>!o;7H=>hikk}(xVrI^`KXE9acv8iTCFKx2O=Sis zASNh-GXaF^VkGgGOKmn)3J}NGk0Ap|xq7RWX3tye9^tA;U`hc`y~R$&o?b;jv$$k5 z*iJgX_c!)-%S{6)IT{dQ@M=)$HJ^EsVdBvzgo@ydkPMkYdnE*7D05Ad&kLz*BxmoN8a1m55=g}@ZUaW2hwbcj;1FNsHCG>3dVH#z(;I`Ixd4I*3A3*R-M_iDw&Pj6MIGehJB7Hx-vy@7XcihxZ7$m~Sz zGhJdihbem(G^K%D$c!k*%ILPtcJ9VdaID;Z~B=e(bh^qDCr4#G?+P zn!6<^2s$DNbe$?OnzO69BAMjZMqGjRwOcKu73*uIb519zr!CGn`sDL!2Xfl~G?!~{ z9&lInXhzLT7?_RXbl|k_3YdO?C5?c}iq-iYsMET#6Fug4oMF6lh#Q-n*?xZEVW|cY)NcTRO zP%p0cQ$K=3*NVsNQ)yGd((&TBZ}S{12K#dY46QU$IuVEm_|kw8VJ4h>HrolF&GR`G zr06LL121NsEFjl&)hg5zK&sL}9TE@UKpA9cvz~)1KJR^!`GL&D4r6QJ@qC{R^fAV9 z&*uY9@FblYV3d%V6(8b55;wXB+3@>pT8EhSzgaT{jaI_LYMv%2B5Vls92I6+)gGdM z864C4M+a^K=uv)*4lq?G=aDjj>y)iZ-~a&t07*naRC8#=M~TuFj>l+D?UAcKb6Zcy zCO--VD9FkWVPXib_2uc49T730z{Re@yBl{G*nxK|$YBrq-snspeuoPV^zP#yhF#t- zc4zMq!>KO!5GxALBOV~m7(tE_ktJ0?hWfX$_3_pUWCHKoY;^`QIRZvw$8FjD4hBdf zUuoh*CCq8bQ>z;Lwp7*Cvz38uq`s%!UNDHb&`$g^sf2Mvrri78nnSI`IxJc z8i7I;#tECnakRG9>kGeqy`VNGcCLl)uuPIth`3U@@3$*raw6|;kV}rwLN62JUgUu) z$ROTz2VpfyhI+qGQa#5{r4gAE*X0C4N$}|t%uK9Y=sbV}4*}p{oVqVw~XViuP@}fz?T5a0bQOIgZK9OqZ8xqM`0BM#BQjn zlU8pCRAI|ar3pryBVT=tRq{lDt3Lw~5}6CQfJs$tACi{(w_P=l-#}=8Fc)N!HORmO z6B&sM7aFRN*SJUVs5`1ugPTz@m|?|hE2~bDSa(@M9_p{YF32Rl zp;nzm+PsY`G*0v0z}}j00U%$Rej({|V@zAf)Gl2VNPw6s$8=KuiqyH?Q`qC`5TN}T zTfJ_Fln$z$ZVu>EYe2OW2@K*&n3;`sm%KuH#*<87Nh+}n<}x*At!vN*-aR3* za1Uo{?z*kaP(YptROtU7)6A$r?VA0JuxnHmnyt8W((?F=*ExCXg zkNu;kanzGtGQDS)Chx$pUxE}ek5QWoE9rbs2}Ii%_J!)LgSUx2nusyC$dDO>(iSK= z3P=pCpbKDmob4p;U1)6dy`^jk;@)i;eu67T?TCr7nG{nkGJDJPcHABcs5N5L3WBA6 z?2b%iimhw|C_XKvZl`NaPEzjf0^3nh8grhpb8QbTrEzH@VsH}u9(5YDLAlhFVdFp% zI66P_dF``SfL0IsF&y^)X{`%f>h;Ss!uj1p&fo{S_Z;c?iEroBs7#iKEa*1gIKX~@ zar`>iMm_MS+Wp{g^idDE99IXy4ZuF7Gdji{$v?dZfio?PCUR;{S#IHIJ33&Kz)!)8 z?zbmRE(f0LQdPtIe~!9US84SA5D^29Bz7J=vy8FUr^t4AA*aeu0nM0%epVA>lHlx{ zQY<%U;o&%*mWX+t<9Rj+-!ICW!j%xzSu3aIqjg;pvRJWja`itU@IPOFcmlxX;0K_c zMe%H7FO&oA^ds76$3YTwQey_^06v~A%^wCn;76u%*sd{q#8Uy+=9hv%z1YX${gFBi zeh*g1?y%uE3Ijd|l4hUStz>pDKL(dwCrIC zA@I+H6UV1>{s*At6U=nBIxwsGNAF@5d1$uXz_FpxYac?zk1EcAtkF^7AW3zxW=j%_?(jW2N`Wqd7xDGm7xL0!=!0EyxEQF=-yVzRdl;&w zVNugJ+IKlQjD_l9*Or`^BFMBy#eVl)cB^eUG5Z2Zn^wc)2atmjxy3N%G+{( zJ@81cKLlR+k}uV4_sYv>U?6$weOKJ?8#8KE`0Ljfsv0%AuG^KeSl(wF(D*Jl>XQsE z6}kbgObiOOxBi1hJYi{eyF3I4qUNr4YOH;+%RQFe*!Ml)pzb?<{lhnQsR|mQ9`b#+ z68Uur*epv+3y3Hsc}1-2i!n!O#1aS^kvE8NB2|6c&p~>hnVDFZuH7b;17NzQOTC7< zmO)KF21s!Zg(mtIa4(KYxP_c{8o%qU zGbC)= zjkP$MFrd{{yTo1MRI~y!8*ue?ww?6%TQ2v(CzPpDG}xsW5TvT9NgT5+achH_z#6xs zxe_G_tbpxX{Wf@A7f8;#WGHvv`%#~%N7tSey6>u_t^_YBmr`oD*$^mVzN~mrd`Q-W z$TOWR)cDNn3S9Ap04Lc9Tu3gfgVb_>4nzr_EiOE36SoQs0j%Xo1SWCrvp2caj~dXZ zx$38~m63>8veizaQvl??U6FTFs?J!EXq{qWnsSNnwz8|$<0Qj2{a4XI24kdX$c$dp zocpxQTWUhZA0(%1++RyTtzXo*z^%?81~@?i*ga2w?~!abC_~uM`O_@426!XfbKWhF zcKW&LeBZt&iVu1|E)#4;L$$)3qDJ6~K<$n1?^^{H8!pZ0-qLRT$#wEaW06pMQxL<% z6_@1uDfI`A$BFBKA_U>`9Fhw=&~XM1#%|C?3vHq#4ZX*R6igLwV?)Iv~#R zerSC4+`T{d*B_q%c)t8_%-)O5kyPU`ed$4r%~_mOjdvOkb8Hq!Nrn?Y9;ac`3_4Hn znBE-_KA)MC?f!eTs&72<7LyMeNivUg6jU9x4=5hZsYC~4w&!iq{Ztq7V9F=R0E7(d zOdC8KB~3WAlihjxwV*|Of*G`n8i%EGGT?hW?zz_Kp^6d!AZ#Yo1YsGhtKz3$DI65M zy+7AJr={y4l-Ae?gj2rpI=Z?%w0N! zTc2@C)s}&jHY*4+5V0mREswvk7{K@?uyUdmp zl&KSqaSnWIUui=fmz3rH`qF)FNf4*4_6YTQ&OmC6Y@mB01Fx^kz6buS7;H2`$#G8) z*p2U9m|O1ILn0ICt{FnW>HBYZzi-f0e-2ayi$ve0aa(Rr!T?{dmv&MWNn$aP1FT$= zOjHj#H0L5?;kWC;U;gsK*Sf%v+<9eU1q5t7GQ?|;De_dh&pfob5r zYuN2Eb%#ciVye2ZlByu?#$7j#99ZoeUi>re?N{|^_s0AE)-(zd?BR*S5y1QXjd^d6 zSzN9*G-}U7hy`K<;)y{vV=<#2B@$zu{mN=!-?~Qi&xsLO>mX@$`gopgZG27cYsJMr$jbP>wS#OW~E))*wc+ zlDh^g3Fd{h5_zS}`JBT|4HzP>zHgBYF#=WzpD|3#fI1HvD5~wi{k>Bud1*4ux>7kq7iu?pztx)_CbC@nI3TBYAy&$Z#>$B9?L7DtVL%-ROs~oDqg+ zJIkF$&+GMtU8VjUT7eK&o|V9%PJi{u+r0&I2!VE`_80*+T*+4M(T>^Ss@=4E-f=+u z7_d65PZ^`qv3;cabIhOl=KIFpKzXS&H3s2szYQNiWpqyCmA+V}S zw{uqmdf|IZ^qW9^@~p!kuuL#O`T5CFmABhmZ-6ttTCMRSse+A@o}ztC#uZ^xNt@G9+%VY@AzEu1OFj31hQF%Pd)zdec>DvjjTK-N6t&Th`Q50z^#IG$zj)$T zkEG2!2cAxFkqd`K1K@g)e%HoZ05DXg)(nb!M}gzs|MQs;qcKkY@w6OEw`(wE1H(Fj zVqDo*VlXW;S<}^$x}9e{J^%t}vu~2uy6wQ9-E8;+;-B8wP-0{v_w-canN@t$8)s&U zq9BB?MKGOqbXa}_6F@xA2>7s_qu_Ipg_3p!&)__57-!7UP?H7v5K%mtQsV2nh6~vH z&0RIIqDceFd6X@b)U@&a{)PMaVQfj`_TJBkuHXRILiMPUQ>r#HeS#4H>XFswB}upo z#2@J|iGoJy^?noEFEW_5>5fbQ-zoDlq#&^*f@P=+slr5G!5V! zF68c#FF@v}T1H7?(Vqj4g4i-_x>b#n%WuxO_3r)Nm?8o;LBrs_H!#GyLcQStUID2F z0#aK{pv^LfZ06*;@G#v0tdtyftyE&n29^%~ZJ>^H)$Hs)HtSaTC_T4ZEfRxY-*3EY zqwdE2{L*F5~i+lWiAkFVSCR{b8-bB)oUx088ydfdk(_&RVX9CDL!*>HYs|dT?k#Sy3C5uA8}EB7KQq``G12vw z@&QtAD8X_CC`3R=A}oWe$gtzG=AU<|onsh6lPkc;0b{P0dT)Dgn>7y3^b7)ceI-w? zECw16l!1okT(3xtQ-pwhZB@nho~gbuyGY2-;V30$5-a3rzMByotm^`=HEOFN3Yflc z9MiPk@@^Q|Ljhrlv5DcBM?NiYa`&7*ReUA#J(4@peg=p})u_VVQmn`bP-F2rY=JwH z>dycT0WxNQUxdbS4tNFP64`P0Tk-77SPGNq7$lec7#tyWP97bfWBO5<3^#8wYxG)9h6weT^H9MXN( zC9F8Zbd&paSS4?Wg3cY1z)IBJJo8r95RJ_l86MuG~ZP~O4=WZ*;1TM-S6kD&LA!V?Y0_^VHE^7VM!~HY6e{!yKeAq z`IwAGc6PTEp53_bw=#qn)NJszoKrNfOk{$+ZvcZDr;EN9Qm%lka%EamV5Wh+8#ATW z`06<=9U>c!LUB$`t2MYqQx#@__{8hO0HT_G=qXO%q6n5Pu>F}*C|4gK?aA+ z$VdeL$N%>~z?gS;8~m!cpxrERD?BI=sFABK)>)mU^W6C$C?(EOP9CEWIOnBu!FH~7 ziaj8nGYcq2B@bT#|=V75NtfaAI<|$VekOR8D)ja zv1~H!_J#A`F%5rA0N|9=DjGv@-J??_r}Jg!P$D4(R>$}10AJl+;Q}R&R^!g`41moO zz2A90*Y@Xj#J0NspKq*=n^^d9MEtdlZy{yX(a>HI31_7e`3%G;7dU;59y#4*kQ}PJ%&li&l(yT{GpTxc>2z>ylBbM*_6X@&zZs14>m90 zMHA;DM^x=g7im7FO$~DbI5bhfd%nUPL%q1qJoq#eZ5HsShY6!m7-;D^JpWR?4R}ft{dJlTYdl&L2 z<>HDp&Gq+|RF+=n1Uz*^4#vsAWMF*%dekbtc&g6jYP6EO6^ZHL3|W1vuQM0!cOgn+ zelYD3ih7nSFNWoEks*`3#%O+cYOc7=z|QlFuqo3lG=aM}dIK9x){Qx!`}^C*T#}hG zASv-)z0`&(nnN@L0}4FuTxtg)Q0 z-(IRn^U}Hs$)m4GT+9j02UY)R!U}~8SHv?05sU|{bZzbV2ob1jNyXxs=O1#z!u`WzwPQdH}rX+&roIc`D;-vmdnPj!evf6tl zsOz!m5dFDSaZOy8lo=C=$YD3YD`)YAT+4FK0G7?LC_Pp8%&taNv-Yj3%PD;~Q5}-v z#M(3MNG=m#b`2I!&Wj(Ltuy$`kh z$|9U8U@$zfnM@0O!aeO9r)B9e-$c6-h7w}I6FLAK=BRvhKiuEgWMedUrc zY=~iglIpv0*ISPC<4$AEfzuhLGCM*Q_R$#0!O(K(s)x9*Gd|7d-!vIEPqRo$-VdZa zKhDXV@#$+1%bFd3gTyRYrBvu$_`Yw&S-Lvr1obE`G8bNJsm;bD_B?rxOgaV3t*|hb z*xjFuZvZNm3`*;-2gq2e%uOSz*&fLzKKOryR6z0YJ=TDyFYo;8M#6BaXt{s-qZow`^^e*1rvlGcOZD zisxX06U616Lt>(Nid%#%`Ombcf(VJS&y9T+Oz>6n7%Mu*+0TeNqN*t0AFVl?Fb)XZ zd!xkJv0W^iv)4lklq!PL=h3=Q-ZLCt*BAC4MtYS zCH~ZV8soe?=(P`%w>3D* zswsKxJY{Mq7Zy;rrn^rl%KeVdPdu0P-!;~9}&+5A+P zl^Y!M2!9_G>jaSu@ZxLBk~AGafve9;0!|*z#u0O!eYS?1@eQhR^GtyJoeTWINT56z>=y`7%Dme&Au-r6|yF8$5RgAEs}PG)JGk zeXoz3G)I;8@cn4``d0WrF@bQ@3=Yybfx^a$$BB~<@!^X_11OJl^ikxAey+&siY&=J zWBm>vBI0j6uXN5YSv@lU$UEWu-+7H=;OH+ez#+giS%I-3%^@uG)90`|rYdq9vuXkY zq$F_>(=mwGbzurCE)MiN-D$hJRlLp*U zuLQwNAE47b2i#JPT&)2Sr*(!AG6b7y)V{?~YtA*%s@!!qs%kPWB+0U3=C-Sr9h z9yb+Sl7Lbb3ym@qYrgM!S`!M5IX&t#xYh!usp{RWLusgya#aW{RNbhtOdT_%lDw4{ zczwBI8hCyEhP>9~N@Vj{qxas}=tea%IP1D_*}?gBUATVxQX-MOGcD;qh~lBldHkFP-Us46G~(vYNlr^ zQBELvNme@oM*$Amn7N;-#*q{Tl;mHpmq{{>A6x4s;OJyr)qN8Nby}1Z@T6ENRmYb_ zIISM!buB+q^90u}c#p9t9N#My!ZTjZ9Ou+zPWYASV(_XXXLQJr9X+g$SMoQKSlE z4J#pT(A9YPR}fcTmL=}{$9VpXlg_i%aT(`T|<5ck<%Y{cnsc{t;r5--RIX! zz!F0fWn-dfxrM24qo?+nOrT^L3=xTrbDAt5vRv&p{A31U&=llQz85uxR&7}8eX0Gb zYbiESpMxv0R=BS(P98ORh7$Hhm{@jb_E!L90AWC$zmEsW{}2^!EAu&gvOR{B2`mhT z>563|Ci76f;O-mMr8Wy<*3upZ@c7Ay%NodyUU4LIalICq{4oVeBryQ6WYni(Z>Tcw zY?78ucKi9HlyF3L@8qjFb%LljIc7VT6ok~`?9g;9 zwVgT;%+XEwr>rJE)qR0`k+%blp?hTLr{Z^H_9n)k95)X#P;sD66>3CEbSNho7o8NR z&eg(-0p;p#psjleU>}@u$fh$kx($F%Ylr?k)cRFha5_MQTC|^{sYsLu*!%9DsS|Kf z3OM`I1WFi-Zxb>#R!Dz9xi3SpHvqHk7+CpDpl3hRA=+v|o}whZ{GaFQzd!Lw&-&-r zp8`z(qpyF{HS>S{BmY~z4zT8rE0F()k~^S2RcIXfpxm%=7$&oK!fp=&1}U(m(H-*? z%O9-Gv4NeWHk^>`CbZzf2g+mo;RTxq#Lqmva$+|D3xRx{01jj6HUmP8)+14(fUX=w z%i!l!7!3XaEKqD1@Qn32m=^ruYI_o)IY1tgx>z;_jsdnnYc!mQ)1-^r8=$@|nAtn6 zYG=;(VOEa`3D0Ne0l&Hl1SFTzg+G<`@^yV~!}v_3^2Wyv^zKSH9G3{HoMgS8;O z4lqdiyH*l2^WGW;uRW2-QGo8qsJ($*yjG6mohrm3L0=$|UoRwMk^$C!g67l~K)#l2 zDTYta@Q|2o%~!;yidAiJq@U^XI?jdbx-d~TSRX`+(e9?RZ0 z!fwx06|nrf5sC!}A3Tj`eZJo}_Px=r7|ZRv@$QX&Z^elf_K_-$XRDg`yE)a!mtEj` zKRx_iHT!;Z-`{w*5>Ab7T)0-o45q4y8ZeiV*|7l9&qqKuTm^#spO|W|2u_u%nxV{2 zZu=#-|6KxAn8E#i%OfHJY6cl}_slfwjDDhsrh*c)6`Xs@t9zaVESD0f>OxOb-U`QQ zQSl=};B~*>-fN$DS-q_UQf${F4ygeK=zF8;EpQQmY4s0Jm*&l%p4MuC;>6@7%}+c@ zg<{8dy>ZvAdE*RA&N27aTFT!p5fowKfPwQ(RJ&2B{3~u`D>ZfJaTd_Y^GZ>Lco0mii&p)wDhf9m~%)6F}yJ-3|kWfIy`wJ+}1t@ZyJ#q zxqyg?E{&pWO>B5^DW3WG@7~JSptdr4RA7%Q+;+bYd%?&DLyC~VQE1@#89N zRs-zmB~@5qnigf^(=uuSmI<6VsnwWu;|~DlRuQ$jehf4@BF2P6`vJe8r>*#V&cvQ7 zxzytE6j+{nak93fHW*9V`w&Cp%liP$11<++S9q(rh9WgSFi~Vrw=uF+ZjR9+Z2BP( z5cDJuH)$MlAzH?Bb%=~XpPqkvNdd4zRwF1s*(mh;SzzZwICLAV(|IuM9rKU|&{=tk zMJc6EKe;&7D$oH$pX?e(Z9*J#Yl3v%AcFUK`48P^$Yr%HJB&-5M}Q^=FQ9*{W5+o@ z_~x8}j`gXZlPY?Q5r}mDpmtk`O*pec%{$8AvY(5cLp_&GVNnpHXop=AM|1%9T2@4sO6z5&tZo9qwX-+7Feea(vFYA zJzPze4&Lk`1l$Hs&rL(XS#ml&>U*zUn|S#BLRU10)F42)s6978i`cCWIL_DyRPw1L zYXrwY%(=f>Az<$oQX5wcH z!;ywglnD!c{va?p9}>sLA-a=Zm^{JNvQ^9zOZrDkhy)+)gGz^jVwf(X!%q7%$zX5k z@E9^HM^9nzLb+-WDv{qk?7e+3J3(#LiTZn^cX2|%5!jkod6ps?S0t6r?GqoT*%%cU zWNt-Co~t!?HK9s_9N_7(K_f@{!LW%8&h<)3WcNm@CmUBTtPHD1Oe*=JYH#klr|yj$ znS5aZ*Lq=HFI-n3A+HKrwsH*0W(skoq;Szdg#Zv2upA5)Eqf(;I!cNHFcbAH=j5tW zrBnry=TH$qLHf|pWCyvA$C6Yz$35DiB>3xkVST-@mfAH)btyyuJ#xSe6PCH2P>f_O#Zb$ubPh0LIg+=%-vdFS=|!iCen-c0IwF_*5NV<|e! zp1@M{a#H9dVHR+`+=`=7fk=OT6Fhwv_Pa1u*w}7xJ;*elD%N@}DqdS==oX4@_4N1N zWXIDkid|yjZ~HlkQp+9Q+0L8k$qOmx|XG? zn9e!ryM_QuEf0~j51M=OPh^~>bSV!y*Ljr@_Gc(|z1^DNyQk_~mExsEw zgS&3lLk@a+hYvn=39Ch*Oyc<(D7B5i%(ccIj!g9uD41+ePYw1sZ9CNw&N5)R^=fj)a$)hs6m zkBVUQ#%Pda%G^;O4f}qxZjmV0T2f3&ObtvUriYQZ*0N$Dp(f&vhE!XGlQY`lI6msL zkh$Zd5}V!Fv$5~Za+?$wsJe0Ajh?pvDpZV^CaaE_+6<~Eq{`3;5p!PK6Cp7BobZyD zmj>Pq6(_m{XxF+-H1LTTK0J?lgY@`Y_GxpY$H)$v!$u?Q!_y`dj!#hX+>MwHP0|SO zojo&+(uQ&GeLK(SE|3YVWV^?EmrNi5xaCLddAA7u8mW8wE_n+C;Rk^XnLu;-%rYS{ z8In2Qs?cj4tMbp}9A#hwuI{&s6F8ev_f6n%NTTl1G?qhVo^oUlnO3~Oo4JQ4M^rc! z5i&I*5jfy%#dZS4hNW^ihW^a30>on?hZyA?Cvmm6eHMZ<99D1U$^m0Nc`*n& zFAwth{laN~&4(bUll1-AheRT#o%?CDrBq@x5jD?RoF0$U)4lzStNY~j9z6WylfJR~ zY*Zm?oOAkMQZa{v3b!p1PyWuc@o6&coMq^zSjK5EPOE@n|D4a~D!Pl7ntr5xGXzld zzke1Bht4G%Cv$qh(aG&cxv|K6b)h z16Qc~cka1wh@NM*8Ky&hIBztyL;$_4z;N;HxkheC=%f#Kl(ps0-7bjUz&`JD&06cjwwwZ~N2g;V_ajORUYOlFbZ9TKHGcBhRLNU@Jd| za{$=HF-w2I`~W`V0|4)5h;Xh8Eu#`0vyA!O0Y9K%ggZnj7XvvH}3yN8ON*%t-A7PApw9Lg>$$ zKksU~U*t?W_}uFTT2=k03ePh+A>2z9-fWV3cNoMuS)|#yBjq0>%XWmB!;F#|MtuV8 z0ME!3cwdv4NIA`q0+fe*SjF)9;>FH|{No ze)#}bqHHs!EdZH$A!Dhsr<2TkPR50Ione=peS22C37Q^(rFAV_arJtANfw_T7nkY0 zh`7rOh{UxnAgDxhpo-XN9k4d)UHJ9=59lhM8O|Bu1d(84a;X#4MGba$$6Bfwg+Tay zH@28NjiFl_#mMrQG-`yCVvu}Kx*AVtnZUY!V_cW|SpA^`y7$3Lii_D`W4hFv4A7+0 z;Jr%~(i-eN=o+N8)YXNes-KxNT1VmDYCw;#kyk=?YxJS)SkvNez_QVmMtdEPgPF#x zIi4UIX?-Nhe$;>t{pyi{B(?7_cy)8PwjGt?DgvVTD=)1p0~h9v}tO7#{o8 zHAnUsZbQ?YZks&@J*qL0`NGzFaqs5tjXDXnE1pw|YOypKqwYPsZv^@z-2kP-8UV9< zp3$XLYe=`0S?ax3me^0*fk3P51~xDr4VmF{a->X113Uj0gWn~}=y}>TYCrNMaOIO< zY0M<&C}q|ah+OE>x;fP-46#f5QnB0Q!YB{U2v6%E5P`@GO(%ifm{$8h*uXZg1+EKw zn!W8s;r9Zv({cW`Qo-_sM(;FvQ4z z!%9gs&>N@;$RfjT@v;NJzUKk+-93?`I)Z_&Yys>TDk@Z}jZ_N{0%{4G0=gzovhUt# zdTo|-9$laApG-DApS(r9G<<)$XS!@KxxjoOSm+?u%j0&tb!trmHO#b6fm72X&98|E zEUlFWZAba2Js2;IIF(-#ry%c{dl#y<4N_-dfb zqnOCahgf?Q(;IXrf7^wu|4mo%Z~yui=#i7NfBrn5Um2PO^TIugsFd`n|K049 zk@%p&7Qh~a$rEHFx~0yEF-Z5|!^AsR*i-34Au(N!|_KhK2abV_2az4LwJW5q&CCN*wJ zJv{+nW3c*22+w8u?=ufbRgf|JJ_=NJ@B?^Q>C)$#QDTgiv6rhGN~8gtA_t7ELF4(4 z!XT|snRHttB&V9AGJwq>!-NC@cy0Pf!+;tw&H=j+0gesfj*Is%CqG?{Yb7Etd<^jd zNK4FO)IV&pNj=M|h+gR`*R{YPc5ft>444L-loNl|jqq^Po(&Xa9HeS0uXSNv^gfU< zZNR8U`fT>38y#)#DZC>2^o6br9IuTup>l3`)yS-!K+qO9U20nxU}a+OUjScDC?tK; zB(!)KUruu-v0jVQMA{?}>L*me%C46C`y0o+EU?_ytVLxAio!{}!SLKUKk zK)ccd1h^Egsx-oEC9R7Gs%s{bm#R|HJ$Ua8ur&Q(K8fP91{v6OW3`4O#afu|nF066 zO*@kaUg}dlq+XW^MODM13^EG<7do2Lje38BJ;>J!(=AX?0a&&eC*hky;T|^0TxgI} zZy*DE)E=Vb+iZVGA}9|!le}u{;8cN&JS80&ze0v!1z!WmPyk$738wT0~sUEbS@B21)dq}(sks`FKH8)=8J5em`Tla&Mlw5te zH5nvYWF6RUxl*RlqY876o&K3nSy;J6QQj;Cm6taqu8kGQS=ejq`|SxD$Mydy3P3GB zY@SiHjp3C`=Z#E3SW_bCeP-(CWP&&awQMb&_q8Eo<D8@>r$a*%r%eh9-v(hl)DAYOz0}Wk)<3fT6^wcv>uH36kY=eyj zvSs9KLVisCuSja0m(S@@zP85-&Ou;lKc`8W0%W0lq{@0hjosDjcAuh!)DmfBTlATL3YMjn|bd<)>Tq(*97C3Zde%8XPHQZj@dT$62L{^W$wv{i$^r3%x|ksJ0C zAlkhIHNzPq!$uVbrsBlUoc9ykB=e5(m}<($sXLrIwWiEG>YF+OG0;`zQ>?);;Dhs4 zY!`s@fCLQtX)6F-)bh1F;|32=@HlHbcOCfv)X3IOg!Fhk-6IWFtNE5ELwL0{^8GQwL!zhMz19kr*LbiX@=9L?_xN8zg&=b{Yd#Bl}dej^D7=1Dlp zvVNz$)eSz6Ohk<^hy8OPLi^w;e;U8X!G0oHn0ihJBaB8F=xI<&-ZQ5Bfs{Yr-&pG3 z@9W?8-hUhg!2j%vKkuy<7YyRgg2N}!9BIw@xj6EiQLt-Qqh${Bk=0G84WPX^PN`U< zkj=z-%7Bg%Uq>E7;B3@#f0CK78JDHTawA&$?M*mh>2&CvYi=>MGtY)T3s+&y)pP^a zGjo)q>V0>J*q~(VL_7g}97KAcJ|jq;88l<>UeGzRD90mPB%Oqgc)9n*J?fxZmG=F(zj~ggPNsqK6Y9Fg>%eLKUp3o?T);jdUuP%8VF7)u7Wy$23@VB`jlJ>xFB{p*jPIm{Ik4c))IknA8X*VVMwP)p8=P z`^NNEYY#AI27UKQ@GbYBK_an&h`bOW?H&!Q!+|+YxmrgVi8v!6ZTUcIMsi@BkT&*x zqxyE`X;bECu-kIaBCztMf@U@9R;6d<7p`20PDIJLFF;(c3zOO(a;a}D5Xm(WkVG1d zjFIZ78ugyD?-^Ay;fiH%^r(W@dt)WBxTbDPBLR6a+=c2I@5GgC$a7kw^MD zJ;zT%du|1hkpq;+ok5^=_oq+Rs+Fo6wS8Z9W7pvR-ujsyT#@4GiUw}!b`^~k902ID z{9R=7buCHsLoE|kN=P-WL20HuyU#)7KGhD?*7OAkoDJSH`mAZc2YU@vqY>yDUe~hk zkpXK66lZ*f$ZA?e3`$bb)r|;3Q|5dI2tv8$1Wck&U=l$-A_;(4XwV}c zC0g3(>XG~dm@SuP4$)hKsb?MwT@lfKj#9ql5HaHlaQfWry+6iznnQ}7lK%h{r=y8j z!650a2h7$zI!2u*zM^qDAT(;zrn*PM9#RmYp}n!SmQs70XOu3gKcmvB2i>Te5$Pm? zM&sXlRP~>UFp=KC(|%^T?X?z~F$f}JAv4iv4I)^96>1YetfxAEzu&61S_u#o*?g^q znGM{fXMWBTNDds9=g#LEao^u2eML+~1Qr9Yut!8l9nxqS{E19O+E|e@XcT)qyKO7+ zAQHK97A_SuD1V9t8>U`zSYVDl4hmN;WJ(vH^W(G%&~Q+Ii?9NYC$pm`+o(!-6ipt} zH$d39wQ!{Bnyy26tMm+GY-%RLl0ob_TFTCXg z0LpAOO6R8P4XPqX%4ANve>kotm_IY2CN?%TLsoI6eZGvV`D#%kde|j4JtGI*nvp5_ zgtFH$=}&0l(+`!Vw~TX7^{`hc7gM}3X>wGuCWtdmt||pX_b6uLko$V(FeW&vf-!** z@I;mQ(c^7k{CGq;>zB!n)=G_x3XfzwY&fn_f66iG{8w>DlMR}O?D6mPQQY}{@ZbbI zc@8NONoSX;-Y^k%#wR|~b$>3k?)rDmy$Dsm^(@Y$7%Ljsc>3V!F{(a!W(tY%#05Oh zVVqa@xWYfQso?n>T91AD_-PLa=aWzFzE8{)nj85>TfHVyIGq=>O?tpZHDjFNA##+5 z=w>*{JNMwML*FC`!N!nG1V@+et=9ovEYtdo&ubrb(?9u|hm-g-eEl&A0RH&H&%5l+ zt2n2{#dBcz;S#jT+q1*9@eMBZowlo|7Q199e&nMdcObgft3g?L;oBip@;=H$MltXK z@!o}a%GPz>!z|=+AU%dRSkFeR2?J(*U-`HK;S>#);XpQr@^vx**izP;;d4v7Pjpbg z(YEwGX^n(~-%Iit2LU6*BU20L@}#ObQmM}z&o=3z&8&APJU)va3j?SUN*~lb_YY6d z>L1{3Ovr?T1PtcSvfwsx<9kimd3GKktsqaYnb9@F#1XyL<{YL26ElZg(N+n52?QI2#RuA(JaOF(&XBog5&2o`eArJ{1Du|NZa({r~yT|LMQt*Y|gWnDu(i zx-Meavp42a<{vh$YL&83QzTPzHjmorU85ej%K=={Ji?V%kLnvF?w;uqe@g&&TfX1* z%)~y1NB~*2QM;z4(#GD!clD#b`AEYCyJj@*OwMzFlFqo&QAt&onL#e#T12pL#!y8D z;sWkHfF0wz-9kdGa717xv6d=5n#r5+z*F(l=yrE``Nca&- zkk-PLFZ2`&TL-C($5FLWUC35ZMDy;CxlVEJ#?Sf9g}@GA<97Q1(F_Xs4oFVsk|`Fb z!DbvrF74^^I@h=+Mt*_Qc>Q)c&J1uZ6;@xb(fW@Rc%O?2{}^YQ8v# zX-nf5ur7}W?7^Nb@E9g6JdI&05me=y8EOLnuzRrgt$FcPh?UGML_o-|ULYUs)1$yl zM9gz9ue>x)uZMAgu>x2`Q6t5YF9Q|K6qc_QtLCz(I29d|5Iul$oEZb=PaDwWUvA zFt8#~9JT+f7hpv@#qfQ7(Jkr81 zvH(qHrS~q}@0+{Ss~waxdChP*)S1Wk%=&Y ztZ5)x6m!f^yG`b5O~d1zdj`2eEmqeHg;2qvPBBM>8`1>+AuLiRm{kJo(yFA2wE%h9 zO!i4L2LlqLc9jFP+8`&Kuz3iT2rnmn<@{I50gnni$|gEHTW+~XFZMhHc)0xz=v#_{ z0T8+5W8x9HTWTHEYj$C(W0WxITnyr|516rs9A}YB=$nCv|IjpPe*o=_+NS2@IZ`v_ z$(7P7+E6Q)47cYq`j?7pK3$X}4t#ItNpxe5IiDrrI60l3|AB*a1zBg0d`Zs8@B>Eq zuq&>+D^)d7?l&9}Q+}#Qj0_?}uaQvv?RHynjGgw!Ms=rP7iXc1ANjwWoIxVZBBK<0;sw_!JgXhrJ;LeGcO)sgwwigQ^}6iO~5m zR%Yv5;zMZQU>D%Yb?3oz`V92_((4(Ag{M0Z&f~^vVpGp!a$yc;5s7#}f6Z9~Ht`<7 zG#kdhJ8nA+s0~bQO7SQp`axLdKKxIR{y)zQ{2{;om;}JHm;ce7Kx<+VG9>xp)j8f&&(o>ThFt{ZBvr2ek2u;pD3sxjXJ@4>ib9zC~ z@62h$hMv2?Q3^c6#{^Rj`;s}jsRGB~!>{m2nJ{C5(GsdL)9ecU5TDit=%D$i^L^mz zx9#L>_A`CZC<5TAnECM>gQxRZq{_&r7tkg@B0j7jfTf#ksP*GVAnbE+m^pr^i22B> z;OBXQ#xXT<>;Xu(Za60S9-a7r`u(FQQnyv54q8hy($eh>uLRX>Ml-3@sxbV#2^@yoqBd8kc%7t}ZQdXqdaMKc*0p?Og50c#N@4_5E zgiP#rVedE6Mt)WqyDbDj%ZM+Rq~4N#LnF)zz$mE?5UW*DV_?qbyIf_P-Pqq7v-iV| zst?B1aL9vWZ>ajd(&`XJmFhyZh=YhrDin@eX*7~5Coyc9J0bv&8iJkb5vhL7k|IUb zM4&7ym1*IvoC*{exaCg~ghpu&kn0+$2Lyz#mALYy9_fJ!4xz1BHfjxU_7>TSO)M^K zsv@eH_bLyPX@c1aj{}}436J)g98fBnNTr**ZtQKd&QN>{3i!QNx(`^PeX0;6>2F3l zoR6OMX}bzl$*OL}L>yvFMsH{83w_?m?OvnTrWB|%m*w&TOoIiD4qVXK%q{74QcnLp zsNR4j$c2%A1=OP)9iT@R9`XqpqtRN#{?@+Z!eC0eveC4hn(d1I$l-rfNzY7NUl)R$ zB?S|Xf@V1pU*xP%JVGXdYq&x!HA(D!`%F<4wx;31B}&N8ala3-cno@FCU(CIFMC?l zuQ&Fs5t~Sn+bo;?Hn8ul5%H2EbLNcMqT0#8*>h9_lEG@)M`D^bUZ1C8*lLh}DgcAV zE{!nkX}s?SdXsdk$WvjItIY^4X?^toAq7iOtvN|G@z)6GQ!#3Qz+YZpK&Fmf^)>md z4J;vH?qOquW{^jVnUilGpP#*qe26Auxjy*G69>I{%kpTT2jk8u3wq1B6SUnwcN zT;5U9Ak|7!bkQXe4G~&8>Xql2Zopl);=tYlbf+!Gm!3?YB{pkz{Eh(lTHv*iE>i{* zHA5K-`ee>P@3MN)?Iw+x(nN!n=b(s)0`~naQZ<(Q@CQj%ciUqJUF|wWtKooGUZAIV z9D_iN{7j^*l7&ccrh|PYqcE76*BQC2_An=L1?OkV9m1rQjBdtlgkvusZzAVQN5SAu zUrDo1DW7NT;;66QK#|^$vX|8F!+G)?kZ+YJ#d#>B?V~DI-X;TRJ!5DoeNuVP8a&+q zA|AZPPEH-CQmyNfF834?tUx`g(Nz4AF`i?$*NBLcAF!cAEnz`OrKQh$0JTH~G)HmD zReIf^6#&LZangMF{?8y=?-4Lr0f>B<(NqKw;r#J@hJz=hk@Gc&sE3m&|5OnWB1Ki1 z_c|H*4V=#{-OzkU8OX=t6eVc|5-pJVRQ^ToXnd~efH?{y;WDY0T$FfN^m(p{@aLg% zi!Sg{p#7P@{x}{0|IF9t{vP1!zxm-l;la4C&DPEN?xu}X=uNBulXFBp27+e(jxjh! zjG|z(U~)TAl$6oZkjHF9EbbXE*9bX}KcLTYtMbNoaMR*l05vjZ<)B)dCeP>7k%prv z5HM{sSH3p`S8K$i&2k0*VEaB5bUquMp!;e>7ED95reQxJxqp}mm;q@21Nt6_C*fyP z`*a(?eSVfv{Z3pZkhun~h6Q@uk2o+mIC8&s1zq1eCWxnvqFcW|p`Jm;IPh9=0H0;X z;b9j3+0au4NxEObQQska-KYPDgEPA7kO&%arm9!MfsFV;g_t-|ZS-M|l@y9pcs{F1 zgA7#>mMaP~gDV1z`ELf7{kp!QQS6? z*9&*a^E-QRx17x7tfER*sRRX(+?rv88KnYB98#m6+G=wOY!8m(ZvYESvcLCMIuc7s z-ALVmDKe$jiL-tj)*1w=G(Z_AzHPalkTOT_>?3-Ad%Dx%Vor zM7=j^-jeL50feQS#Af8D$38=_=XE78g(Ic45*Hf*_6?A(J_AT~MEB`)O_}VmWri4# zKSQ-tZm-wE`^FKd0K2iBD2q&40x?hP!a~JH-;!Up0c@cZ%a$DP_L*o9=lRW(urBvp zddxGJm}>I$dW{}0%Vcm~m*QEIhw$%7OxMf|!}HLwH{L_6?P?K$Bw1TyQlc6Yp+XQF z(CE=~mWXCb57Qao_qL=WDx zbRV<98|R?ay{>`Wf2@R}w2d=^#1VwW)HK6pOaZAjy9Ud~qw*L~tSu{8YUYeD)L~oz zN1ezr97!3=j)1%~F-m%#$c4#xahlix#LRRKFv*(2_E}#_b8uy707NOq0z-zBJ9B@d z5fc;oOlM5l5RI}TMl)7~shc&8E0?EK=0kc^1h9a1gMG~n7O}2C%CQp}!M)|r(+#Y} z*(GSH(?}pXiD=lfr)$@sR%qy6QoY?8k$5cmeAdJ`pVK)u2OOJh%oc@ukgf>Kd2-XF zixLNX&bL19{|-+nZv2J=>woWjqva@{Q!BxkT`MnpkC-UR^*b(QyY ze|{!L>a)`xI~A6bJBJWSgVXZqx}@3zT;V>Z+dTlBOV2UmPUWN;Vd?t@ksy*A(Z74x z1LD~E9Gh|Fay-dCPH{>};<%klq*ojw;lW}2L9p;CRye_RakH&pq3-ojYIvW`QCuGA zfOuFH9-{5RcJrt=*n@~hpOyr#lkvwmc!Yh*kS-GYXD5ijM$c*2fm=ItfFE+D`!i1Q zFhnk72^0Q6s6W3B_3&r-`a=@{pD*1`Z<{C4!GV=;0IpoBg zWX*2XAb*eo$JJX)I$WV%^wKxucYy9#%4?;Y?o;3iX5^85pCe4SHFyAbh!<$LKfqF~ zwrtW95oqG%b3kdUaO4)c4iJPHRBz5W#|l)DpYZb%Q}L(=k_t5E`VOKd&qhywPnL`@ zFc-5)an=0)xqI6kS&}6=%-lV)dhU`GL`V=Ifbah}dJqBp!H?ZJT^a7CA7+u&b9cEb zP!xHGeX%>|^y#ju%#84GH#ai}reqGYT+F9GKf}Cj2Tk`n)aibxkh*`G5wAQBKfmYa z?SurUL<#1Dz@EbYF~i~s8D=$vIy3>`_xnaS|M$QAy1Eg)dF*YTb+tli(L2P zFe5^1_VogYhiIoeldZA~7A&NIfrh_vi zIkB!nx2SYquLW{6zrH1v%^`Xdxumg$$4T`xb2G34_xBA#RAuCF-#cmoSho@+7s3?< zB)E5n`tFIcIbW?~HZ+_>^m}81SWMLG3)1laW(J8I#8-;Hw|}ro;yQLhUkV;$ZT*1C z&cTQkg$D19j=@SzJGe6N`>!VXD_^VRP>e>6Ow6uWV0ik&_aIipjG;lAIvsG)ugc=8 zCEfWD#Ey_(u}6vV1E_&E!XrB(UQPht`$okAgEkuszNa&xZUK!(#sb$MwiB&^Iv*=s z++rAHwC6Au6D-8rBO}E~q1x$dp$3sxfZcd+>yk%Zw05!z5;vvKC2jCpNhYK6GB^;p zZ5F6bu*_>u>=QlJiAhub5;g=R?Wk?=8%`J_RUm>NwwS=Q1R31wCvj!Q%wX?kMnnwY zGCzY(mbkIElCPOYBxYu7*vR!Vi{vEW#GBHY)3tm+z>A0%MFe8Z3IW6l8g-VO`qj~x zS)P)5#-$kDCam`mxdyc|NXQT{)JeV80&%Mg4gy@T4LIVZ)_Y)PA@YXlwiv9eIA?)6 zd;{Ktzq}Sm8|;x0VebJ)^w~K4JF&--kx>j}%u<3G1K_ezCnngyl0GAjYkD*RHYX#} z4)_`Q$%UHu7SM~U3bUNxkAMfQcl!S-B+-)*r&UnMtO&XgUU4R6aHhj9{$%SK>4rp~ zDGBi-p>Gv7m4TcKn*PG53_@>V&ay!aa|$`do*grdn25Dr&v`#2au*qlV+a_Pz?S!k zKwzHq0~oPxM2a~xbzm1tB63B(=<^){jL=L*TuZ#c@uV5Kpj(hOe{BBPgq1+V1Y$+$ zcgh6lIWg_YrQ&pGFVjj(+A5829kG^<6fd*5-`~3bj2IU`$Usa!Ca7Xq427_|!)tnT z+IL|Dkc+vB(zwhk5U~VcIrZu7uJ9^NivZA5LJ=`BHdh0I$;G0aFUsxih`{s|gQl$q z+U&$R5Wp!S0n1ItyFPu-;m-P*K%k!|=;xueHYeYWQzHQIl$#$dLKtUNb0P?z$o7J8 z@#;dHKblFAW*&}j4qW)fhnYL6d-s45l>cdhm`nl5d6=s}=RCCdU@6}{wG3569EtJs zj%K&g3>z^q1lHsXb`)}2?_;LRxMJ#4RL_sHl|a-W_VLxyIg+8A5B-T5=8!3O9-{J) zMdB0`HULi>I@9qlVaf;2WD7kreP5Wa>o55000KOh)mE|TM{_)qJrT7OHJHOv zcQ}9GAq9psx@9AWA(3pEH@H6H$vg;|<+*|zhjBW10(8^;AV2U-cuySg!Z;s+roP0{ z+o-Zury52t=YVHUWoa!?K*-+F5jjwV$K2@$PKXQ#OM?o8HH-Ywao1-NY6&9t6=JhxTr2$ZY3jI7)(%HVdu zoXWV$qu+Yad*hp1h-;Qk$UK0E?&X;=o>wX;L&=qN@zMyo`G%?&3hCLyLb`i4zwg_` z)bqG9rs<@ae61B%6)HqXKC@ys0`*cSU)wc-CW_WibA%`d1yZ@Ikg?*P=6#P5d;q5l z>f{9g;$=_})}%(_x-P8i6|o8{HF~brlG}1mylUYpjS!1S@DkYAl<8q*iKb7jlWR%p z!yfQv6!RHVhDhxF7Wgzbx+(2(6?YHr*{E7FW}B8PIW)?wvGv^j+)5r@aYlz?39uUy z-OX;It`)DZOWM?Hq3Y!^Qg8;Am%EW zeZMgr(E+TYGM^NiM@y1W2pcR z;29CxJLU6WG@gzp;hq^xhZEV45t<~e6{b`ta^aN*c~f-tAl&Jc*G2>}alCs1M}$fU z5ZJrH9H{@m51==U8!GfxUC6J6RWq9tyOqa8MN||D!AOmQj4NYRx^bWw~7QU#O4YWy`;vM z?g4cT(Hybk-h=zTwGJYJLF|?{!^u%n2Nh~vA-|C&GtdzGq3;gbr$aD=&VFH%Iu~X( znv8Xf1@!}AJ=GB~hq~(L{0@KKJ!MMg&T%OTe9#$9syxPE~rod;ay~^#pj-oPLF|Ea7sV zE7-uP96!1ElRO&$g^gm(aKgzeod?r&MFzwMa~>;3(0OGQ?qegq$0%>c(__NTF4qSB z77yr&(_x1@#s2dgFhZkkV+I3B(a!V%`DeC^t`jTH&2uhs^66v9$75Wly!gm=!)DBI z{&9>bf3olo0C8M<`Y|eW-Ovf)$p+9k0>G)`a2RGFI#)AeV4FiQ2YjTNUT&lc)2Bh! zQ!xAQt**>5XODPpA&z3m=}TMf$k^&dJw;2B+cR`pYZJm|%r@9R$i066?;DfzCO%xrCm4jb3)KpZ8HHqD{s z&@>V`io2A1y2{1`d8#o@3;+T(d^S!}#x>&(4D&-Xfk(OU7~;^Mn*=I9!7hk~^^|bY z9;J~d3ENB^lrz*E;eo*PnuI>L3P+(|DkMJ}^UQyz6F)g<#yK0LHwy(T+E_~)#%`Eu zjOhBJJZl}&9H)Y(OvBXaPBmRcUp;gp7yb_u!iBg10$oSigk@Y9_NY@T^w%c~WpWds zbe(6@2A*PDM<_lZhQh?>o;}f4w5G}iHw4pT`L!TQUHJDa9}4^<{Bj@)A5da;SVl2E zd`rNNI_B#Br-6ic5LZ8|gD(31o)+6nk(Nk=)Gx=Gv7ucBQj_3-fv6{m`hrBjb*YU ze`2D61S>-c{s`S&wV0J>X0*C&WoPqIl9uPl9DVMDx?iJ%A+9V<12bl;E=g4>E)o2cz47b)#&^FF)R;1wa@^Yld;*9Cph5{!V&y`?J}6ZfM!aPJ zsm^~7W*ac{!F=}{d+!iz$j3m023~R{vO;|}$Pn<}8-c==g<1tB_@1pv0&|iO;0{sl z)hUsDf?H(A%rqq0!6KqG>)r)}U5iD-Rd-42LGgIhVM!T`o!xSq-j7OHP=YI6Tyn!U z%^2>dORsTm;NBaXl(z&0u4QW0dc7*rdZ&eOd=PM=VlxavCc}wcnDumKeq*5LUciJ# zr1hpjWVjR6K&xxBTWV*Fm||CzI=2YqrQ(nv_B}E|JRND@3o#c0{mj5RQw|zg@&j1w z<&0FzZUsbj<)FQv#x6~nfv`LNn<~b@G0lItHxY9tEDSEVvyLY$>#Po&<>o@gD`)`3 zg`NsHKW|ePbZ0}7qy4@$*M0^BqmIF$)4o6;R^fjCGFYgN8QT5{lyn7Yz>*1>!D(&R z1a1!Q_eS40=AO&|E^GLQ;O32c`dF6(U8I?H0+9%E$B?+NBGY59CL&6FnsZR<+37q< zfmy6ftV=A5J%jiC&7sUd6X3cIqYbz@9-&)DPptGl3e{z{z=X|5-H>%IVa>4X5D>(g zs)$%S9?H9GK|AYdJrY)#xY9` z$Y-Q3x$hSM*o-r}`IskC(*l^L`3p(JzVFB5V!bXTq^;jABhVR7qNs&yU64>P!SZNf zou?oI(~O7C#6X))lmXn|-&m#Q(9A@oSVSaQdJZr*1C>DmBB9!~1#arhBeJAmIwMg7 z0<`wMAG$LmG`)s)-+wKArfv)cFlns^L%2mCM=)laN&Rg6w;?^vp`&W5!C}pb&*qvA`Mg&H z7#mr;SOTMPK&f%D7Ker5wEz70=PN#qyFcOAp8^0-eCMgBe|(c(eEJ%9h5}AhQm9sV zvz&zu7ng^8cFa=GjCN6vZIS}@+8H91)2ks*m)0oKS*XA~n+>M7J#LYtXj|vA;6tSu zQ+pyxRCp&RA6HVU;PeJQ*CBR;(5;hb9%}!A0*`iwLPga5r48*SKGaUHo>Y*Bsh~rIc9xaOAaQ1!3as$&`#_a9g5Bev1SZcSZ~)YyIT&?&e8&zd z8~!Na&#L=6kXNjN(}9rmvT4=`(FA_I-w5FEX4o3jo-@OO6u9UX-TM?&vm0&GFdU?x zl4-0A?7cAwTuY{E2JJcf_L#hQfFUs_1|+yvfT(EGddsFsdp4M6I}Fu9C9@ILJlsN-4*xk6d46?4*lG!JTsEHYRQE2U8 z=v4!ccsbp(TS2~Wiq*3)dxC5PHNHzg1BltkNMs_IA=+hLO6YQZAa|JJ47td6-v|yP zwA!!hg!%afk<~bVh>k1VAST)D8;0x_}g#`nF^ zB!((iFFlXy|5BkRmf$^JqV0O=LySFay&D*sm}C!Z`@n6vS*qF;B_rl z$|=9?I{@;b@m(XPLshstZw3^cgfOss;yoKrP$v+_ylDs`Bk3vvxA(FVkg5V|$uzWp zdR+p~_NJAQK$P75=fpM0Hq;o*qB;PDKzhGz$dlM9zRARKN&W;C#y#O) z%{a+P(W`r7n!KkGj4&u=Vp(DD#=E~Y2N`EPs~rCoxy15O((SV)CYZF0rbY41MDxb( z+r{-K`K}V+G2QHYaJ1hYz;z`ugHeUcofW9tDhUu=%nP7FOxPnpEFa~tL$ox}5e1sn zqK+d;x+vN$r|t3CGy`-`R6;%n(1=F}T+T@Wn>L7JWn{@ruqtEa89tcqzQQt>ZEylO zW=>(Qi44!A*S%->P}dRIZy8mtt5C1fgcAcr+Y<~jW!?q?eK)SGr$ABVDP4Gm{dL;? zy9g{NpY&MSH4AyEV|nje=Sa{-bS-^50}L0G=%6YZ_7*s?>H-MvkPJwH$JkN#&TjdK1V7OB;C**fyR-K z+@Rqxu`t^(iv%#!VrsoES##J-&Z-maTQN_}qSMf!JR!0S?gTE&-=MsUdz!UMg->tn zR;0-Fn4}TPJ1I6=MkJ!@(s|)n5N4FhGa@3g=%Kyg97tpptqB0<@bB##7cgC+hW{jP)fPC`aGmcPc^U1$} z!*(qY9cRC|!whIW(@QPKhJ;hg9-2_{Q6S>0E&9?@RX?n~txfq<8H4n+aln1?|9Zcb( z+0LWoKr!xmN6s-)$0@+W|9&)BL*1LnK!*dRXBY?C8``vZDoGv8(;+xitAG(3p6BOK zX|zxG9PXg+&qo4{;EtcqnUO%#hMaU6tO$2^;{Yn&@JiR!RbjU}2otC5^cqb+Q+1zX z;>e@G!}2(vDFCrfB+48z^0dW)fB*G*X~4cH-awo&-g8XW2bi0&8aAk zK;eDg`rOwAKm!@Tz*Pzf8Kbdi6_D<8;k8o#K4J;TD??qgs|tYvdV^b9G6Zm4fk=%h zip<9YLo?_bL&Qc9DI_(cMIp~b)p8#I$Y7K@x+<2V5E|j89y3ihZon0{5o3q?D0#fZ zmfqc3wm`*$=wCweHv+S7C99Q@ae4Cy*qd#d*ea9@9L=-7u)>IRiaI&m@%C$lL8$v% z69Wo~8+ObFu=kCXVV8CQp#oLy79dRb$D|dWC~O;UUbVm_XZ9R zabAN4e4U6wC9o~Ih_n5xT9Z7i9Da;-1-59X1G zR26E4SgCXl0DzP^976jv3Za~(1RNQ-J>auEbgU;d0@EW%wYyOPuGb6srK0tric4!h znH7ixH=@7aqPJ6YhkG}MYNA}1z;*Uk&H^GdJP@bD2|^QNTKS5OG8v!NIbB;!%QNGh z3`spwMe7(G&XruTeBukJuQ+nf^ZEjhG##*Ar~~(V*t2o>#%y^U%;%to0G4JEh_&!4 zd95f=*fl(4gnI7=XA`3wB8M)X$MU6)F$$fdJk+&@n1Q)~C`>bsFcSxOO+(R%8;OP%0Be?csxAd*H`K-mhAC9uv6$0w<1+2rorMG3Jp$pCF+-oEyMz}o|QAFl>w==u~q%{wz6a`e;q0H*qmp&mJe5^n9f^W-jdxVr!?q;bdR^!EX4YJa@$fecgm?o-$@`bQTx zkgk{;R24NU0mIt0Ge32FEoal6aVV$TJdhK!0=^4nCt`ZzF)GRDb_~Yd^(WjR<4h2U z4;n|PI3f|J@EzH)%%Sx7dY&1YjRzh8&p~Y36MPU6&-=rO>_g)*_1C{{ri5f~i9z~4 zsn9+!gDH~8CxGTTIq7pSl!TKIy$HrTz4=QY78lVOK8e+{RW~u7=Y>-j;Y^m0192c4k7q)Km>d!C{N=)mWaVOH0pS0- zu0+*J1ntut=z&J*joiWS{SAx?$=+}5`z9$p@}7;&{Uje^Lx7x6#|q(sTo?GQf(h>XjR{NyF-Zg#3Gj*ubzLdcT?aCm zz}+1)chEZIrcmMuSbl>57$2P?NmJFshcvLG=T>bpA$?~hdcZuC#*nUeddpirOtl|N z3Q|Tst+{1F|JAjNvUlXFR7M-x17pBI4I>>|mB8!k3#$sQQZUd+G*Ki)Aio8$PzH!{ z<`0M|Aa<&X=H4=))AP`Zuks-pqW+@a>M&x^jYtmG*Fubdpev8gRfT~Ar8I-N5N55$ zq4=f#D~5)oGyA@&(U3wUG838QnbOL3)y0np7lV6;I)ovh>ROjOXHM>9j2D?<8!u_} z)oe9LXN^+E*s55uPLd>zfFXAlf!Sn^{V0OqBv~>UDm`EXCo<%SJx=thw7MEVcVmw_ zYKq+vJ-@&bMfINJm*O}uiG5pdn1?>CeS{%0S7eMN414r(Gr>_eH)A2>B=^MPkG7U* zOjIJSTo2`3Yh-C&eAF=lRFh*sQght*NV1!j4v=_?<2G%(!9dFFa>SeI?G28W8hAhYq0_B9_}6lMiDAQv&!p2>OtD>l>*~h zeig$(e{Y$V_6EtgO42C8<3Ljm^S|zmzISYcRq7Nk%afYZ6UY|x;HdJSlTKajdyl+Y zUdolWjroY->;}4h^+oL9R7VQ1T0o>8n$O{ivK9ZIL00O?Yvj2$1u=`lgR+bX(N4K6&oZ>~)2SiKW z=IoLYniRq~(mEh*+N$Ys<))<84Lu4J6u1Krn>*@S+8zyHYy2z+6G%@&I{BEn4FnJ+ z(22KV>NI8)zr+%9{?I$R`&cn5$FvC^yV3Wp>Dh36ao*D@mSUPmlbMT*`TZaM0bjqp zA~0r?9uPnQC>*;SK3!wctJ;Q%{uocP+oup!H`~8##uNlv%`vfa9zS>h8-|N^(EcC; z8DyRbO=+J1-+vr0Ff&U+dAeZ?oaW7ufuc`d*+2XZ)FetAE4)BKl41qo_~iP108l>f zz)8@yGi`q`P&sj(R}3{*#tdnWbI22ep}d#WosaX`C<*A99w4t9=kL!GI?o2GVO%iF z15GuJKpOq-m|c5}OUGbbc-=mocC&R9&BjKguA87n&LEs#>Ul`UqR*2g(o+sZsyd)d z;HOjCF~bF+I<3!t4|wd25-#ckhUHHq@Z1ZZw)1lx1AmJ0`Cs_@o4$gx**;(VtM90* zc@QNYu8I>wThAz|fT=E_1MBEs4n-$m>UlyNCcSY?8_ta96OF0l5ADYFrzQb-^YEa0 z{9H@Ig}Dk2<~dMK_eIE;Sv%6~!v%l%n+7U|i5MYnPm$_lM`oYrHSw4lrXXj1R?osN zhX> z5f9xlkXT=rh!Pq2TEF4SdW!h95^L#6?R%TAB2R+uerU&YJ5$I)jvR9zuL^FgRhp9x zQDSFytO}@gqC&q`p@_&>z;yJ`l-8~OaL7zdH=ILeH zaVnv1b0jE}K#voxaB-!K_*x6=TFSoqupCmyO)ga0y?+$zhc~RJQY>u%m`D=gIb$n> z!Wjn@3$N?r523V2y5#r0A32afjB|E4Bl3CC^OmG-><2-yc0{jDR7NBkXD z*nO*GdqC|6*wHY&Fw#2+gkjGkYse&y_Y7cpLI^-EcW0vnk#LmYZqJaIIi5cPu_6Mo zmY639$v+UNRbm}Q@pRzQ>(js!W^3(k^3#p<=Z#dd%u|h=!me-Jrrp;`DyK0$*!LT@ z=);iaKU|8=8yb!cV0gPzyj`FMxTW{K0Np#0fo+ zX1%BP-DNs*BT=X*2yYtQtvz5e>viGv+iy~X4mF|{klZc`tY?mj*@WMc>fI*NP?3U4;d_$NIn>-Tv`J*$jM5~TZK3W zZWiclFunjx&~E?os)-m5iNv%3c+)tYW2JJ2IXV2~Q)J~h^@WN!>jHq2e*z!VSGXe% z#gWs6*XR+z@(4*sPRbt6|5JY+81RGGFzJN*+J>Ec!k zR#b*)Y$~@+iQ45ZE& zR8mDXmG2hQ@5FN^0dX30Hb;b;oDuG}eT1B{!x}^8;El+m5-_Z zKBudnmvi5z+)4kRl7AqKhbKJVk+d+~{5=id<2x<*+4qqP$gPxCiUetv4dG;0FD ziR8~`1n@Am|HNMp01*G&PyG-2;=lM4)@O$k0~f<|G2ecuF(qnt5NGCko}!qhpN`FH z1~~4KcCC0eze=QZ!PhuuPdo&LK3!iWDAsrB-Zme-%cCtb74EPD&h-i`pgVn#VaEt~ z5KT?SPXyd)N}F=v@f>;FYl+i&dx~VjUCmag5iQ?8A7zk$&*mL(*aNJbjhJVX`SLZ} zT1m#Leh^gR1ZDp$1M5>tJIPjV^FiJKaFp-F=-g{<#vW6SNYEWFr_Rs)3kPbT0J~Nn z#=|hJ@gc%YfM>-GK$wE_Nn0Y z<8_e4p?n4h|N8I#7hKm1uWJE`DQ0Rs-^PG(OcTLEoteZlIMXfILS*ljKC2p-k=C_` z&!Hdd6;X>Mu&xVLB6;SaXhop8HF}OPkm6#^NjgoD`rh~B>98_!qKK_3HirE{tCe_MZ4y7?t-g`2P6E&|2tcaM| za-m)&h$%}QAZus!vk`SI%vMpVa6x1g;rZW;)47!P85yW027u;)+03xF3=GjRP(d3R z!1b8s1UO)=s9bowej|~ilA>uH@C=(9dv6;gmfWU$Fe7undv4rwiwzow(x?NN1MK&= zXv~V8v3oeTXs^?U<)Ln5BJl1ThsL>%T8=h&%s^D)S_$Oj^sVdTra&tdUk8k=ERTdz zVWK2OyH*L{Fw^n5ob-l3B;>-nl0!`_(E3vsTl;$}HmBGm5i;R=T?Pi&hzYC;cj4l= zmn+GB`Iw(A&9}P=-M12Sh$7e|dbd~_Ocf#_FMyd1tUy);h8WM1mhM(md~!tk&pEE! z)QF*Z;(G6m?|l>6<+uZw=^%%#?xxnNw_|2XbTB%%I)*)`?^#Da5UbS5CdWzCVTv3> z!cXjv47_pyuLE2rvZN_zQgH%GlvWicH|O5-+&3YerpqeSkt)2dSjbu+&4vgd5F@>M zq9P}PSg(a#m)FOTBL>2N&)76TEQ>Zhx!r-1F{_zq$HY&SFtoh1C)!>Oh`?f!B=QxA zD2~8Nd)mqj5k*9(BMyw%AYxRhxDuSoL!}q6Afvp1urb%?hzjPqP$}s~gznewO{dt( z71AKGX{tp{V^~X*LF^vSD#6O6bn<6nPHP@J7a$|JcJb-seD;=~hiCuJR<~GqgIld3 zaGB19#_~h$Tb%Zh&K!TIeW+ zra&MPv%#p~(CNRY7)*LXPnAJ_F)ekl=nUU>=D!|rPfV>0;5hlJs2^q~BVL%Q7!G>t z-j<%M<)bfD20)FnO#|dIrdP-QwG{c5AHZ}(C0L=3()e22;MnXI$Va-#5~$^%s{Bnd zp3uLFEQe!!H$QMyQHxbSkZZDz#8AY3>iZ8&{$?9+fcpn}J`<;kzK zebtzAbLSM$1fN>&ReP+4GUL_);GryHXQe1PZ6I z<`X$>cugzre;6i)i*Y{xlL_i4|5S&(N^FDxz$sDo;er`%I`Z64-8(g2Y~tu~T>@R> zV3&9%AQ%WZ6$NPeKgBdk;CYq;DU3~zW0{L?jhPOh^SM*>HRzJ#$?4_tuLqTuL&tf0 z9-!6rV4mLPVMdtU>@92yi&YAx|X>(Xh-QcYw@OQY(lJT$tFHul&+<2it~z=Q;pBn?^O7 zoDXoWM8JP70;_#6fb&Ot)j zmM}y!YM#ZJM*jh{cn_q_^1KE#b=YhHs98)0*?Zpj_5S@o?*Z=bJBh%nE>o?8xl{zq z{f5aa>ef=uy@a~c`~Jr6EdxI@DKawhN@OHwHoAA5j(P8i9#KB`>GGgh*M(r<-nT%3 z(KEQLUEiKzyO3Cs(q!*2mz}E?5-R2@xZwI#{G8jmzp$za;F4Jy36r2q7Vgu^2aWM$3zee z*~%Y$(#%z9BE{RmHshoxHa0mUr}b%#t5c8>jnVrupl(nt0c)8V%%rF+us*x6A~3UY zzi;drb`wF(0zdvGVV0Bq8v>@A_LfJ2rlTEtAs)x-%7`RTHK;+j7z`E|O#8*CSZHkz z;8M)0%(%=9+Otuu8*^_8G;xekLKe7wTc}7jh_x=1P5C0j=1D{@jSP!uX{5EEu!5Q< z@FpT7mwiG&y-$1eD6pdcesFh0{>Imbj#1g4E^~@UVx8hqwFcIor1+LST$s^0- z96D(8HoX>zSn#CWKIg|aQ=-z66UwusMcp8F0NrtPqOJ>(0@j&n6Q2wvn{%W4HaOOZ zur`HC8P)1mkSb|n#NJ{=1bHS;WGq$&zOF0QQlsF|nZg6HuUaZ5!X-ckYJ!~9_{1P1 zN+3haXg5kGeM82oh3j>hYG^uo1R@qij2Q+J*SdV3CUS)$%z!YkkRhgIL?Y0L-fEsu zknkx?>q;zxbu%0D-n{o#UUa6lbaO?e1`&xBidh&K00>mBoC%Q4 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 U(e=8>27&4Q%#YWYNOfNCA?Du5 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

    LlG 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�Js8UOeZDAN;}J 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 QasU7T07*qoM6N<$g6ZzER{#J2 literal 0 HcmV?d00001 diff --git a/crates/cdk-mintd/Cargo.toml b/crates/cdk-mintd/Cargo.toml index c55882d16..240e791ce 100644 --- a/crates/cdk-mintd/Cargo.toml +++ b/crates/cdk-mintd/Cargo.toml @@ -21,6 +21,7 @@ cln = ["dep:cdk-cln"] lnd = ["dep:cdk-lnd"] lnbits = ["dep:cdk-lnbits"] fakewallet = ["dep:cdk-fake-wallet"] +ldk-node = ["dep:cdk-ldk-node"] grpc-processor = ["dep:cdk-payment-processor", "cdk-signatory/grpc"] sqlcipher = ["sqlite", "cdk-sqlite/sqlcipher"] # MSRV is not committed to with swagger enabled @@ -42,12 +43,13 @@ cdk-postgres = { workspace = true, features = ["mint"], optional = true } cdk-cln = { workspace = true, optional = true } cdk-lnbits = { workspace = true, optional = true } cdk-lnd = { workspace = true, optional = true } +cdk-ldk-node = { workspace = true, optional = true } cdk-fake-wallet = { workspace = true, optional = true } cdk-axum.workspace = true cdk-signatory.workspace = true cdk-mint-rpc = { workspace = true, optional = true } cdk-payment-processor = { workspace = true, optional = true } -config = { version = "0.15.11", features = ["toml"] } +config.workspace = true clap.workspace = true bitcoin.workspace = true tokio = { workspace = true, default-features = false, features = ["signal"] } @@ -58,7 +60,7 @@ futures.workspace = true serde.workspace = true bip39.workspace = true tower-http = { workspace = true, features = ["compression-full", "decompression-full"] } -tower = "0.5.2" +tower.workspace = true lightning-invoice.workspace = true home.workspace = true url.workspace = true diff --git a/crates/cdk-mintd/build.rs b/crates/cdk-mintd/build.rs index 3f833b77b..43ea2a298 100644 --- a/crates/cdk-mintd/build.rs +++ b/crates/cdk-mintd/build.rs @@ -15,7 +15,8 @@ fn main() { || cfg!(feature = "lnd") || cfg!(feature = "lnbits") || cfg!(feature = "fakewallet") - || cfg!(feature = "grpc-processor"); + || cfg!(feature = "grpc-processor") + || cfg!(feature = "ldk-node"); if !has_lightning_backend { panic!( diff --git a/crates/cdk-mintd/example.config.toml b/crates/cdk-mintd/example.config.toml index 30983d1e2..2b103175b 100644 --- a/crates/cdk-mintd/example.config.toml +++ b/crates/cdk-mintd/example.config.toml @@ -64,7 +64,7 @@ max_connections = 20 connection_timeout_seconds = 10 [ln] -# Required ln backend `cln`, `lnd`, `fakewallet`, 'lnbits' +# Required ln backend `cln`, `lnd`, `fakewallet`, 'lnbits', 'ldknode' ln_backend = "fakewallet" # min_mint=1 # max_mint=500000 @@ -89,6 +89,47 @@ reserve_fee_min = 4 # fee_percent=0.04 # reserve_fee_min=4 +# [ldk_node] +# fee_percent = 0.04 +# reserve_fee_min = 4 +# bitcoin_network = "signet" # mainnet, testnet, signet, regtest +# chain_source_type = "esplora" # esplora, bitcoinrpc +# +# # Mutinynet configuration (recommended for testing) +# esplora_url = "https://mutinynet.com/api" +# gossip_source_type = "rgs" # Use RGS for better performance +# rgs_url = "https://rgs.mutinynet.com/snapshot/0" +# storage_dir_path = "~/.cdk-ldk-node/mutinynet" +# +# # Testnet configuration +# # bitcoin_network = "testnet" +# # esplora_url = "https://blockstream.info/testnet/api" +# # rgs_url = "https://rapidsync.lightningdevkit.org/snapshot" +# # storage_dir_path = "~/.cdk-ldk-node/testnet" +# +# # Mainnet configuration (CAUTION: Real Bitcoin!) +# # bitcoin_network = "mainnet" +# # esplora_url = "https://blockstream.info/api" +# # rgs_url = "https://rapidsync.lightningdevkit.org/snapshot" +# # storage_dir_path = "~/.cdk-ldk-node/mainnet" +# +# # Bitcoin RPC configuration (when chain_source_type = "bitcoinrpc") +# bitcoind_rpc_host = "127.0.0.1" +# bitcoind_rpc_port = 18443 +# bitcoind_rpc_user = "testuser" +# bitcoind_rpc_password = "testpass" +# +# # Node configuration +# ldk_node_host = "127.0.0.1" +# ldk_node_port = 8090 +# +# # Gossip source configuration +# gossip_source_type = "p2p" # p2p (direct peer-to-peer) or rgs (rapid gossip sync) +# +# # Webserver configuration for LDK node management interface +# webserver_host = "127.0.0.1" # Default: 127.0.0.1 +# webserver_port = 0 # 0 = auto-assign available port + # [fake_wallet] # supported_units = ["sat"] # fee_percent = 0.02 diff --git a/crates/cdk-mintd/src/config.rs b/crates/cdk-mintd/src/config.rs index 602901658..56bdecd1e 100644 --- a/crates/cdk-mintd/src/config.rs +++ b/crates/cdk-mintd/src/config.rs @@ -45,7 +45,7 @@ pub struct LoggingConfig { pub file_level: Option, } -#[derive(Clone, Serialize, Deserialize, Default)] +#[derive(Clone, Serialize, Deserialize)] pub struct Info { pub url: String, pub listen_host: String, @@ -68,6 +68,23 @@ pub struct Info { pub enable_swagger_ui: Option, } +impl Default for Info { + fn default() -> Self { + Info { + url: String::new(), + listen_host: "127.0.0.1".to_string(), + listen_port: 8091, // Default to port 8091 instead of 0 + mnemonic: None, + signatory_url: None, + signatory_certs: None, + input_fee_ppk: None, + http_cache: cache::Config::default(), + enable_swagger_ui: None, + logging: LoggingConfig::default(), + } + } +} + impl std::fmt::Debug for Info { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { // Use a fallback approach that won't panic @@ -106,6 +123,8 @@ pub enum LnBackend { FakeWallet, #[cfg(feature = "lnd")] Lnd, + #[cfg(feature = "ldk-node")] + LdkNode, #[cfg(feature = "grpc-processor")] GrpcProcessor, } @@ -123,6 +142,8 @@ impl std::str::FromStr for LnBackend { "fakewallet" => Ok(LnBackend::FakeWallet), #[cfg(feature = "lnd")] "lnd" => Ok(LnBackend::Lnd), + #[cfg(feature = "ldk-node")] + "ldk-node" | "ldknode" => Ok(LnBackend::LdkNode), #[cfg(feature = "grpc-processor")] "grpcprocessor" => Ok(LnBackend::GrpcProcessor), _ => Err(format!("Unknown Lightning backend: {s}")), @@ -183,6 +204,88 @@ pub struct Lnd { pub reserve_fee_min: Amount, } +#[cfg(feature = "ldk-node")] +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct LdkNode { + /// Fee percentage (e.g., 0.02 for 2%) + #[serde(default = "default_ldk_fee_percent")] + pub fee_percent: f32, + /// Minimum reserve fee + #[serde(default = "default_ldk_reserve_fee_min")] + pub reserve_fee_min: Amount, + /// Bitcoin network (mainnet, testnet, signet, regtest) + pub bitcoin_network: Option, + /// Chain source type (esplora or bitcoinrpc) + pub chain_source_type: Option, + /// Esplora URL (when chain_source_type = "esplora") + pub esplora_url: Option, + /// Bitcoin RPC configuration (when chain_source_type = "bitcoinrpc") + pub bitcoind_rpc_host: Option, + pub bitcoind_rpc_port: Option, + pub bitcoind_rpc_user: Option, + pub bitcoind_rpc_password: Option, + /// Storage directory path + pub storage_dir_path: Option, + /// LDK node listening host + pub ldk_node_host: Option, + /// LDK node listening port + pub ldk_node_port: Option, + /// Gossip source type (p2p or rgs) + pub gossip_source_type: Option, + /// Rapid Gossip Sync URL (when gossip_source_type = "rgs") + pub rgs_url: Option, + /// Webserver host (defaults to 127.0.0.1) + #[serde(default = "default_webserver_host")] + pub webserver_host: Option, + /// Webserver port + #[serde(default = "default_webserver_port")] + pub webserver_port: Option, +} + +#[cfg(feature = "ldk-node")] +impl Default for LdkNode { + fn default() -> Self { + Self { + fee_percent: default_ldk_fee_percent(), + reserve_fee_min: default_ldk_reserve_fee_min(), + bitcoin_network: None, + chain_source_type: None, + esplora_url: None, + bitcoind_rpc_host: None, + bitcoind_rpc_port: None, + bitcoind_rpc_user: None, + bitcoind_rpc_password: None, + storage_dir_path: None, + ldk_node_host: None, + ldk_node_port: None, + gossip_source_type: None, + rgs_url: None, + webserver_host: default_webserver_host(), + webserver_port: default_webserver_port(), + } + } +} + +#[cfg(feature = "ldk-node")] +fn default_ldk_fee_percent() -> f32 { + 0.04 +} + +#[cfg(feature = "ldk-node")] +fn default_ldk_reserve_fee_min() -> Amount { + 4.into() +} + +#[cfg(feature = "ldk-node")] +fn default_webserver_host() -> Option { + Some("127.0.0.1".to_string()) +} + +#[cfg(feature = "ldk-node")] +fn default_webserver_port() -> Option { + Some(8091) +} + #[cfg(feature = "fakewallet")] #[derive(Debug, Clone, Serialize, Deserialize)] pub struct FakeWallet { @@ -337,6 +440,8 @@ pub struct Settings { pub lnbits: Option, #[cfg(feature = "lnd")] pub lnd: Option, + #[cfg(feature = "ldk-node")] + pub ldk_node: Option, #[cfg(feature = "fakewallet")] pub fake_wallet: Option, pub grpc_processor: Option, @@ -443,6 +548,13 @@ impl Settings { "LND backend requires a valid config." ) } + #[cfg(feature = "ldk-node")] + LnBackend::LdkNode => { + assert!( + settings.ldk_node.is_some(), + "LDK Node backend requires a valid config." + ) + } #[cfg(feature = "fakewallet")] LnBackend::FakeWallet => assert!( settings.fake_wallet.is_some(), @@ -464,8 +576,6 @@ impl Settings { #[cfg(test)] mod tests { - use std::str::FromStr; - use super::*; #[test] @@ -532,45 +642,4 @@ mod tests { assert!(!debug_output.contains("特殊字符 !@#$%^&*()")); assert!(debug_output.contains(" Self { + if let Ok(fee_percent) = env::var(LDK_NODE_FEE_PERCENT_ENV_VAR) { + if let Ok(fee_percent) = fee_percent.parse::() { + self.fee_percent = fee_percent; + } + } + + if let Ok(reserve_fee_min) = env::var(LDK_NODE_RESERVE_FEE_MIN_ENV_VAR) { + if let Ok(reserve_fee_min) = reserve_fee_min.parse::() { + self.reserve_fee_min = reserve_fee_min.into(); + } + } + + if let Ok(bitcoin_network) = env::var(LDK_NODE_BITCOIN_NETWORK_ENV_VAR) { + self.bitcoin_network = Some(bitcoin_network); + } + + if let Ok(chain_source_type) = env::var(LDK_NODE_CHAIN_SOURCE_TYPE_ENV_VAR) { + self.chain_source_type = Some(chain_source_type); + } + + if let Ok(esplora_url) = env::var(LDK_NODE_ESPLORA_URL_ENV_VAR) { + self.esplora_url = Some(esplora_url); + } + + if let Ok(bitcoind_rpc_host) = env::var(LDK_NODE_BITCOIND_RPC_HOST_ENV_VAR) { + self.bitcoind_rpc_host = Some(bitcoind_rpc_host); + } + + if let Ok(bitcoind_rpc_port) = env::var(LDK_NODE_BITCOIND_RPC_PORT_ENV_VAR) { + if let Ok(bitcoind_rpc_port) = bitcoind_rpc_port.parse::() { + self.bitcoind_rpc_port = Some(bitcoind_rpc_port); + } + } + + if let Ok(bitcoind_rpc_user) = env::var(LDK_NODE_BITCOIND_RPC_USER_ENV_VAR) { + self.bitcoind_rpc_user = Some(bitcoind_rpc_user); + } + + if let Ok(bitcoind_rpc_password) = env::var(LDK_NODE_BITCOIND_RPC_PASSWORD_ENV_VAR) { + self.bitcoind_rpc_password = Some(bitcoind_rpc_password); + } + + if let Ok(storage_dir_path) = env::var(LDK_NODE_STORAGE_DIR_PATH_ENV_VAR) { + self.storage_dir_path = Some(storage_dir_path); + } + + if let Ok(ldk_node_host) = env::var(LDK_NODE_LDK_NODE_HOST_ENV_VAR) { + self.ldk_node_host = Some(ldk_node_host); + } + + if let Ok(ldk_node_port) = env::var(LDK_NODE_LDK_NODE_PORT_ENV_VAR) { + if let Ok(ldk_node_port) = ldk_node_port.parse::() { + self.ldk_node_port = Some(ldk_node_port); + } + } + + if let Ok(gossip_source_type) = env::var(LDK_NODE_GOSSIP_SOURCE_TYPE_ENV_VAR) { + self.gossip_source_type = Some(gossip_source_type); + } + + if let Ok(rgs_url) = env::var(LDK_NODE_RGS_URL_ENV_VAR) { + self.rgs_url = Some(rgs_url); + } + + if let Ok(webserver_host) = env::var(LDK_NODE_WEBSERVER_HOST_ENV_VAR) { + self.webserver_host = Some(webserver_host); + } + + if let Ok(webserver_port) = env::var(LDK_NODE_WEBSERVER_PORT_ENV_VAR) { + if let Ok(webserver_port) = webserver_port.parse::() { + self.webserver_port = Some(webserver_port); + } + } + + self + } +} diff --git a/crates/cdk-mintd/src/env_vars/mod.rs b/crates/cdk-mintd/src/env_vars/mod.rs index 2d8c234b5..8a4edcdee 100644 --- a/crates/cdk-mintd/src/env_vars/mod.rs +++ b/crates/cdk-mintd/src/env_vars/mod.rs @@ -17,6 +17,8 @@ mod cln; mod fake_wallet; #[cfg(feature = "grpc-processor")] mod grpc_processor; +#[cfg(feature = "ldk-node")] +mod ldk_node; #[cfg(feature = "lnbits")] mod lnbits; #[cfg(feature = "lnd")] @@ -38,6 +40,8 @@ pub use database::*; pub use fake_wallet::*; #[cfg(feature = "grpc-processor")] pub use grpc_processor::*; +#[cfg(feature = "ldk-node")] +pub use ldk_node::*; pub use ln::*; #[cfg(feature = "lnbits")] pub use lnbits::*; @@ -111,6 +115,10 @@ impl Settings { LnBackend::Lnd => { self.lnd = Some(self.lnd.clone().unwrap_or_default().from_env()); } + #[cfg(feature = "ldk-node")] + LnBackend::LdkNode => { + self.ldk_node = Some(self.ldk_node.clone().unwrap_or_default().from_env()); + } #[cfg(feature = "grpc-processor")] LnBackend::GrpcProcessor => { self.grpc_processor = diff --git a/crates/cdk-mintd/src/lib.rs b/crates/cdk-mintd/src/lib.rs index 962705bf9..233b2738f 100644 --- a/crates/cdk-mintd/src/lib.rs +++ b/crates/cdk-mintd/src/lib.rs @@ -22,6 +22,7 @@ use cdk::mint::{Mint, MintBuilder, MintMeltLimits}; feature = "cln", feature = "lnbits", feature = "lnd", + feature = "ldk-node", feature = "fakewallet", feature = "grpc-processor" ))] @@ -31,6 +32,7 @@ use cdk::nuts::nut19::{CachedEndpoint, Method as NUT19Method, Path as NUT19Path} feature = "cln", feature = "lnbits", feature = "lnd", + feature = "ldk-node", feature = "fakewallet" ))] use cdk::nuts::CurrencyUnit; @@ -108,9 +110,10 @@ pub fn setup_tracing( let hyper_filter = "hyper=warn,rustls=warn,reqwest=warn"; let h2_filter = "h2=warn"; let tower_http = "tower_http=warn"; + let rustls = "rustls=warn"; let env_filter = EnvFilter::new(format!( - "{default_filter},{hyper_filter},{h2_filter},{tower_http}" + "{default_filter},{hyper_filter},{h2_filter},{tower_http},{rustls}" )); use config::LoggingOutput; @@ -321,6 +324,8 @@ async fn setup_sqlite_database( async fn configure_mint_builder( settings: &config::Settings, mint_builder: MintBuilder, + runtime: Option>, + work_dir: &Path, ) -> Result<(MintBuilder, Vec)> { let mut ln_routers = vec![]; @@ -328,7 +333,9 @@ async fn configure_mint_builder( let mint_builder = configure_basic_info(settings, mint_builder); // Configure lightning backend - let mint_builder = configure_lightning_backend(settings, mint_builder, &mut ln_routers).await?; + let mint_builder = + configure_lightning_backend(settings, mint_builder, &mut ln_routers, runtime, work_dir) + .await?; // Configure caching let mint_builder = configure_cache(settings, mint_builder); @@ -391,6 +398,8 @@ async fn configure_lightning_backend( settings: &config::Settings, mut mint_builder: MintBuilder, ln_routers: &mut Vec, + _runtime: Option>, + work_dir: &Path, ) -> Result { let mint_melt_limits = MintMeltLimits { mint_min: settings.ln.min_mint, @@ -409,7 +418,7 @@ async fn configure_lightning_backend( .clone() .expect("Config checked at load that cln is some"); let cln = cln_settings - .setup(ln_routers, settings, CurrencyUnit::Msat) + .setup(ln_routers, settings, CurrencyUnit::Msat, None, work_dir) .await?; mint_builder = configure_backend_for_unit( @@ -425,7 +434,7 @@ async fn configure_lightning_backend( LnBackend::LNbits => { let lnbits_settings = settings.clone().lnbits.expect("Checked on config load"); let lnbits = lnbits_settings - .setup(ln_routers, settings, CurrencyUnit::Sat) + .setup(ln_routers, settings, CurrencyUnit::Sat, None, work_dir) .await?; mint_builder = configure_backend_for_unit( @@ -441,7 +450,7 @@ async fn configure_lightning_backend( LnBackend::Lnd => { let lnd_settings = settings.clone().lnd.expect("Checked at config load"); let lnd = lnd_settings - .setup(ln_routers, settings, CurrencyUnit::Msat) + .setup(ln_routers, settings, CurrencyUnit::Msat, None, work_dir) .await?; mint_builder = configure_backend_for_unit( @@ -460,7 +469,7 @@ async fn configure_lightning_backend( for unit in fake_wallet.clone().supported_units { let fake = fake_wallet - .setup(ln_routers, settings, unit.clone()) + .setup(ln_routers, settings, unit.clone(), None, work_dir) .await?; mint_builder = configure_backend_for_unit( @@ -489,7 +498,7 @@ async fn configure_lightning_backend( for unit in grpc_processor.clone().supported_units { tracing::debug!("Adding unit: {:?}", unit); let processor = grpc_processor - .setup(ln_routers, settings, unit.clone()) + .setup(ln_routers, settings, unit.clone(), None, work_dir) .await?; mint_builder = configure_backend_for_unit( @@ -502,6 +511,24 @@ async fn configure_lightning_backend( .await?; } } + #[cfg(feature = "ldk-node")] + LnBackend::LdkNode => { + let ldk_node_settings = settings.clone().ldk_node.expect("Checked at config load"); + tracing::info!("Using LDK Node backend: {:?}", ldk_node_settings); + + let ldk_node = ldk_node_settings + .setup(ln_routers, settings, CurrencyUnit::Sat, _runtime, work_dir) + .await?; + + mint_builder = configure_backend_for_unit( + settings, + mint_builder, + CurrencyUnit::Sat, + mint_melt_limits, + Arc::new(ldk_node), + ) + .await?; + } LnBackend::None => { tracing::error!( "Payment backend was not set or feature disabled. {:?}", @@ -953,6 +980,7 @@ pub async fn run_mintd( settings: &config::Settings, db_password: Option, enable_logging: bool, + runtime: Option>, ) -> Result<()> { let _guard = if enable_logging { setup_tracing(work_dir, &settings.info.logging)? @@ -960,7 +988,8 @@ pub async fn run_mintd( None }; - let result = run_mintd_with_shutdown(work_dir, settings, shutdown_signal(), db_password).await; + let result = + run_mintd_with_shutdown(work_dir, settings, shutdown_signal(), db_password, runtime).await; // Explicitly drop the guard to ensure proper cleanup if let Some(guard) = _guard { @@ -981,12 +1010,14 @@ pub async fn run_mintd_with_shutdown( settings: &config::Settings, shutdown_signal: impl std::future::Future + Send + 'static, db_password: Option, + runtime: Option>, ) -> Result<()> { let (localstore, keystore) = initial_setup(work_dir, settings, db_password.clone()).await?; let mint_builder = MintBuilder::new(localstore); - let (mint_builder, ln_routers) = configure_mint_builder(settings, mint_builder).await?; + let (mint_builder, ln_routers) = + configure_mint_builder(settings, mint_builder, runtime, work_dir).await?; #[cfg(feature = "auth")] let mint_builder = setup_authentication(settings, work_dir, mint_builder, db_password).await?; diff --git a/crates/cdk-mintd/src/main.rs b/crates/cdk-mintd/src/main.rs index 1d3dd64f9..435dcb048 100644 --- a/crates/cdk-mintd/src/main.rs +++ b/crates/cdk-mintd/src/main.rs @@ -2,41 +2,37 @@ #![warn(missing_docs)] #![warn(rustdoc::bare_urls)] -// Ensure at least one lightning backend is enabled at compile time -#[cfg(not(any( - feature = "cln", - feature = "lnbits", - feature = "lnd", - feature = "fakewallet", - feature = "grpc-processor" -)))] -compile_error!( - "At least one lightning backend feature must be enabled: cln, lnbits, lnd, fakewallet, or grpc-processor" -); - -// Ensure at least one database backend is enabled at compile time -#[cfg(not(any(feature = "sqlite", feature = "postgres")))] -compile_error!("At least one database backend feature must be enabled: sqlite or postgres"); +use std::sync::Arc; use anyhow::Result; use cdk_mintd::cli::CLIArgs; use cdk_mintd::{get_work_directory, load_settings}; use clap::Parser; -use tokio::main; +use tokio::runtime::Runtime; -#[main] -async fn main() -> Result<()> { - let args = CLIArgs::parse(); +fn main() -> Result<()> { + let rt = Arc::new(Runtime::new()?); - let work_dir = get_work_directory(&args).await?; - let settings = load_settings(&work_dir, args.config)?; + let rt_clone = Arc::clone(&rt); - #[cfg(feature = "sqlcipher")] - let password = Some(CLIArgs::parse().password); + rt.block_on(async { + let args = CLIArgs::parse(); + let work_dir = get_work_directory(&args).await?; + let settings = load_settings(&work_dir, args.config)?; - #[cfg(not(feature = "sqlcipher"))] - let password = None; + #[cfg(feature = "sqlcipher")] + let password = Some(CLIArgs::parse().password); - // Use the main function that handles logging setup and cleanup - cdk_mintd::run_mintd(&work_dir, &settings, password, args.enable_logging).await + #[cfg(not(feature = "sqlcipher"))] + let password = None; + + cdk_mintd::run_mintd( + &work_dir, + &settings, + password, + args.enable_logging, + Some(rt_clone), + ) + .await + }) } diff --git a/crates/cdk-mintd/src/setup.rs b/crates/cdk-mintd/src/setup.rs index 507de0e39..ec03fd330 100644 --- a/crates/cdk-mintd/src/setup.rs +++ b/crates/cdk-mintd/src/setup.rs @@ -2,6 +2,7 @@ use std::collections::HashMap; #[cfg(feature = "fakewallet")] use std::collections::HashSet; +use std::path::Path; #[cfg(feature = "cln")] use anyhow::anyhow; @@ -15,6 +16,7 @@ use cdk::nuts::CurrencyUnit; feature = "lnbits", feature = "cln", feature = "lnd", + feature = "ldk-node", feature = "fakewallet" ))] use cdk::types::FeeReserve; @@ -30,6 +32,8 @@ pub trait LnBackendSetup { routers: &mut Vec, settings: &Settings, unit: CurrencyUnit, + runtime: Option>, + work_dir: &Path, ) -> anyhow::Result; } @@ -41,6 +45,8 @@ impl LnBackendSetup for config::Cln { _routers: &mut Vec, _settings: &Settings, _unit: CurrencyUnit, + _runtime: Option>, + _work_dir: &Path, ) -> anyhow::Result { let cln_socket = expand_path( self.rpc_path @@ -68,6 +74,8 @@ impl LnBackendSetup for config::LNbits { _routers: &mut Vec, _settings: &Settings, _unit: CurrencyUnit, + _runtime: Option>, + _work_dir: &Path, ) -> anyhow::Result { let admin_api_key = &self.admin_api_key; let invoice_api_key = &self.invoice_api_key; @@ -100,6 +108,8 @@ impl LnBackendSetup for config::Lnd { _routers: &mut Vec, _settings: &Settings, _unit: CurrencyUnit, + _runtime: Option>, + _work_dir: &Path, ) -> anyhow::Result { let address = &self.address; let cert_file = &self.cert_file; @@ -130,6 +140,8 @@ impl LnBackendSetup for config::FakeWallet { _router: &mut Vec, _settings: &Settings, unit: CurrencyUnit, + _runtime: Option>, + _work_dir: &Path, ) -> anyhow::Result { let fee_reserve = FeeReserve { min_fee_reserve: self.reserve_fee_min, @@ -160,6 +172,8 @@ impl LnBackendSetup for config::GrpcProcessor { _routers: &mut Vec, _settings: &Settings, _unit: CurrencyUnit, + _runtime: Option>, + _work_dir: &Path, ) -> anyhow::Result { let payment_processor = cdk_payment_processor::PaymentProcessorClient::new( &self.addr, @@ -171,3 +185,138 @@ impl LnBackendSetup for config::GrpcProcessor { Ok(payment_processor) } } + +#[cfg(feature = "ldk-node")] +#[async_trait] +impl LnBackendSetup for config::LdkNode { + async fn setup( + &self, + _routers: &mut Vec, + _settings: &Settings, + _unit: CurrencyUnit, + runtime: Option>, + work_dir: &Path, + ) -> anyhow::Result { + use std::net::SocketAddr; + + use bitcoin::Network; + + let fee_reserve = FeeReserve { + min_fee_reserve: self.reserve_fee_min, + percent_fee_reserve: self.fee_percent, + }; + + // Parse network from config + let network = match self + .bitcoin_network + .as_ref() + .map(|n| n.to_lowercase()) + .as_deref() + .unwrap_or("regtest") + { + "mainnet" | "bitcoin" => Network::Bitcoin, + "testnet" => Network::Testnet, + "signet" => Network::Signet, + _ => Network::Regtest, + }; + + // Parse chain source from config + let chain_source = match self + .chain_source_type + .as_ref() + .map(|s| s.to_lowercase()) + .as_deref() + .unwrap_or("esplora") + { + "bitcoinrpc" => { + let host = self + .bitcoind_rpc_host + .clone() + .unwrap_or_else(|| "127.0.0.1".to_string()); + let port = self.bitcoind_rpc_port.unwrap_or(18443); + let user = self + .bitcoind_rpc_user + .clone() + .unwrap_or_else(|| "testuser".to_string()); + let password = self + .bitcoind_rpc_password + .clone() + .unwrap_or_else(|| "testpass".to_string()); + + cdk_ldk_node::ChainSource::BitcoinRpc(cdk_ldk_node::BitcoinRpcConfig { + host, + port, + user, + password, + }) + } + _ => { + let esplora_url = self + .esplora_url + .clone() + .unwrap_or_else(|| "https://mutinynet.com/api".to_string()); + cdk_ldk_node::ChainSource::Esplora(esplora_url) + } + }; + + // Parse gossip source from config + let gossip_source = match self.rgs_url.clone() { + Some(rgs_url) => cdk_ldk_node::GossipSource::RapidGossipSync(rgs_url), + None => cdk_ldk_node::GossipSource::P2P, + }; + + // Get storage directory path + let storage_dir_path = if let Some(dir_path) = &self.storage_dir_path { + dir_path.clone() + } else { + let mut work_dir = work_dir.to_path_buf(); + work_dir.push("ldk-node"); + work_dir.to_string_lossy().to_string() + }; + + // Get LDK node listen address + let host = self + .ldk_node_host + .clone() + .unwrap_or_else(|| "127.0.0.1".to_string()); + let port = self.ldk_node_port.unwrap_or(8090); + + let socket_addr = SocketAddr::new(host.parse()?, port); + + // Parse socket address using ldk_node's SocketAddress + // We need to get the actual socket address struct from ldk_node + // For now, let's construct it manually based on the cdk-ldk-node implementation + let listen_address = vec![socket_addr.into()]; + + let mut ldk_node = cdk_ldk_node::CdkLdkNode::new( + network, + chain_source, + gossip_source, + storage_dir_path, + fee_reserve, + listen_address, + runtime, + )?; + + // Configure webserver address if specified + let webserver_addr = if let Some(host) = &self.webserver_host { + let port = self.webserver_port.unwrap_or(8091); + let socket_addr: SocketAddr = format!("{host}:{port}").parse()?; + Some(socket_addr) + } else if self.webserver_port.is_some() { + // If only port is specified, use default host + let port = self.webserver_port.unwrap_or(8091); + let socket_addr: SocketAddr = format!("127.0.0.1:{port}").parse()?; + Some(socket_addr) + } else { + // Use default webserver address if nothing is configured + Some(cdk_ldk_node::CdkLdkNode::default_web_addr()) + }; + + println!("webserver: {:?}", webserver_addr); + + ldk_node.set_web_addr(webserver_addr); + + Ok(ldk_node) + } +} diff --git a/crates/cdk-payment-processor/src/proto/mod.rs b/crates/cdk-payment-processor/src/proto/mod.rs index cf5995d96..229d1c02e 100644 --- a/crates/cdk-payment-processor/src/proto/mod.rs +++ b/crates/cdk-payment-processor/src/proto/mod.rs @@ -37,6 +37,10 @@ impl From for PaymentIdentifier { r#type: PaymentIdentifierType::CustomId.into(), value: Some(payment_identifier::Value::Id(id)), }, + CdkPaymentIdentifier::PaymentId(hash) => Self { + r#type: PaymentIdentifierType::PaymentId.into(), + value: Some(payment_identifier::Value::Hash(hex::encode(hash))), + }, } } } diff --git a/crates/cdk-payment-processor/src/proto/payment_processor.proto b/crates/cdk-payment-processor/src/proto/payment_processor.proto index 187c6eed5..fad00ffa3 100644 --- a/crates/cdk-payment-processor/src/proto/payment_processor.proto +++ b/crates/cdk-payment-processor/src/proto/payment_processor.proto @@ -46,6 +46,7 @@ enum PaymentIdentifierType { LABEL = 2; BOLT12_PAYMENT_HASH = 3; CUSTOM_ID = 4; + PAYMENT_ID = 5; } message PaymentIdentifier { diff --git a/crates/cdk-sql-common/src/mint/mod.rs b/crates/cdk-sql-common/src/mint/mod.rs index aa28df260..385a00cc7 100644 --- a/crates/cdk-sql-common/src/mint/mod.rs +++ b/crates/cdk-sql-common/src/mint/mod.rs @@ -546,6 +546,11 @@ where amount_paid: Amount, payment_id: String, ) -> Result { + if amount_paid == Amount::ZERO { + tracing::warn!("Amount payments of zero amount should not be recorded."); + return Err(Error::Duplicate); + } + // Check if payment_id already exists in mint_quote_payments let exists = query( r#" @@ -592,6 +597,13 @@ where .checked_add(amount_paid) .ok_or_else(|| database::Error::AmountOverflow)?; + tracing::debug!( + "Mint quote {} amount paid was {} is now {}.", + quote_id, + current_amount_paid, + new_amount_paid + ); + // Update the amount_paid query( r#" diff --git a/crates/cdk/src/mint/issue/mod.rs b/crates/cdk/src/mint/issue/mod.rs index b12687190..ee8bc9665 100644 --- a/crates/cdk/src/mint/issue/mod.rs +++ b/crates/cdk/src/mint/issue/mod.rs @@ -1,4 +1,3 @@ -use cdk_common::amount::to_unit; use cdk_common::mint::MintQuote; use cdk_common::payment::{ Bolt11IncomingPaymentOptions, Bolt11Settings, Bolt12IncomingPaymentOptions, @@ -251,14 +250,10 @@ impl Mint { let description = bolt12_request.description; - let mint_ttl = self.localstore.get_quote_ttl().await?.mint_ttl; - - let expiry = unix_time() + mint_ttl; - let bolt12_options = Bolt12IncomingPaymentOptions { description, amount, - unix_expiry: Some(expiry), + unix_expiry: None, }; let incoming_options = IncomingPaymentOptions::Bolt12(Box::new(bolt12_options)); @@ -410,52 +405,8 @@ impl Mint { mint_quote: &MintQuote, wait_payment_response: WaitPaymentResponse, ) -> Result<(), Error> { - tracing::debug!( - "Received payment notification of {} {} for mint quote {} with payment id {}", - wait_payment_response.payment_amount, - wait_payment_response.unit, - mint_quote.id, - wait_payment_response.payment_id.to_string() - ); - - let quote_state = mint_quote.state(); - if !mint_quote - .payment_ids() - .contains(&&wait_payment_response.payment_id) - { - if mint_quote.payment_method == PaymentMethod::Bolt11 - && (quote_state == MintQuoteState::Issued || quote_state == MintQuoteState::Paid) - { - tracing::info!("Received payment notification for already seen payment."); - } else { - let payment_amount_quote_unit = to_unit( - wait_payment_response.payment_amount, - &wait_payment_response.unit, - &mint_quote.unit, - )?; - - tracing::debug!( - "Payment received amount in quote unit {} {}", - mint_quote.unit, - payment_amount_quote_unit - ); - - let total_paid = tx - .increment_mint_quote_amount_paid( - &mint_quote.id, - payment_amount_quote_unit, - wait_payment_response.payment_id, - ) - .await?; - - self.pubsub_manager - .mint_quote_payment(mint_quote, total_paid); - } - } else { - tracing::info!("Received payment notification for already seen payment."); - } - - Ok(()) + Self::handle_mint_quote_payment(tx, mint_quote, wait_payment_response, &self.pubsub_manager) + .await } /// Checks the status of a mint quote and updates it if necessary @@ -477,7 +428,9 @@ impl Mint { .await? .ok_or(Error::UnknownQuote)?; - self.check_mint_quote_paid(&mut quote).await?; + if quote.payment_method == PaymentMethod::Bolt11 { + self.check_mint_quote_paid(&mut quote).await?; + } quote.try_into() } @@ -508,8 +461,9 @@ impl Mint { .get_mint_quote(&mint_request.quote) .await? .ok_or(Error::UnknownQuote)?; - - self.check_mint_quote_paid(&mut mint_quote).await?; + if mint_quote.payment_method == PaymentMethod::Bolt11 { + self.check_mint_quote_paid(&mut mint_quote).await?; + } // get the blind signatures before having starting the db transaction, if there are any // rollbacks this blind_signatures will be lost, and the signature is stateless. It is not a diff --git a/crates/cdk/src/mint/mod.rs b/crates/cdk/src/mint/mod.rs index cc11509bb..bd93baca4 100644 --- a/crates/cdk/src/mint/mod.rs +++ b/crates/cdk/src/mint/mod.rs @@ -199,13 +199,8 @@ impl Mint { /// # Background Services /// /// Currently manages: + /// - Payment processor initialization and startup /// - Invoice payment monitoring across all configured payment processors - /// - /// Future services may include: - /// - Quote cleanup and expiration management - /// - Periodic database maintenance - /// - Health check monitoring - /// - Metrics collection pub async fn start(&self) -> Result<(), Error> { let mut task_state = self.task_state.lock().await; @@ -214,6 +209,33 @@ impl Mint { return Err(Error::Internal); // Already started } + // Start all payment processors first + tracing::info!("Starting payment processors..."); + let mut seen_processors = Vec::new(); + for (key, processor) in &self.payment_processors { + // Skip if we've already spawned a task for this processor instance + if seen_processors.iter().any(|p| Arc::ptr_eq(p, processor)) { + continue; + } + + seen_processors.push(Arc::clone(processor)); + + tracing::info!("Starting payment wait task for {:?}", key); + + match processor.start().await { + Ok(()) => { + tracing::debug!("Successfully started payment processor for {:?}", key); + } + Err(e) => { + // Log the error but continue with other processors + tracing::error!("Failed to start payment processor for {:?}: {}", key, e); + return Err(e.into()); + } + } + } + + tracing::info!("Payment processor startup completed"); + // Create shutdown signal let shutdown_notify = Arc::new(Notify::new()); @@ -266,7 +288,8 @@ impl Mint { (Some(notify), Some(handle)) => (notify, handle), _ => { tracing::debug!("Stop called but no background services were running"); - return Ok(()); // Nothing to stop + // Still try to stop payment processors + return self.stop_payment_processors().await; } }; @@ -279,7 +302,7 @@ impl Mint { shutdown_notify.notify_waiters(); // Wait for supervisor to complete - match supervisor_handle.await { + let result = match supervisor_handle.await { Ok(result) => { tracing::info!("Mint background services stopped"); result @@ -288,7 +311,39 @@ impl Mint { tracing::error!("Background service task panicked: {:?}", join_error); Err(Error::Internal) } + }; + + // Stop all payment processors + self.stop_payment_processors().await?; + + result + } + + /// Stop all payment processors + async fn stop_payment_processors(&self) -> Result<(), Error> { + tracing::info!("Stopping payment processors..."); + let mut seen_processors = Vec::new(); + + for (key, processor) in &self.payment_processors { + // Skip if we've already spawned a task for this processor instance + if seen_processors.iter().any(|p| Arc::ptr_eq(p, processor)) { + continue; + } + + seen_processors.push(Arc::clone(processor)); + + match processor.stop().await { + Ok(()) => { + tracing::debug!("Successfully stopped payment processor for {:?}", key); + } + Err(e) => { + // Log the error but continue with other processors + tracing::error!("Failed to stop payment processor for {:?}: {}", key, e); + } + } } + tracing::info!("Payment processor shutdown completed"); + Ok(()) } /// Get the payment processor for the given unit and payment method @@ -460,6 +515,7 @@ impl Mint { } /// Handles payment waiting for a single processor + #[instrument(skip_all)] async fn wait_for_processor_payments( processor: Arc + Send + Sync>, localstore: Arc + Send + Sync>, @@ -498,6 +554,7 @@ impl Mint { /// Handle payment notification without needing full Mint instance /// This is a helper function that can be called with just the required components + #[instrument(skip_all)] async fn handle_payment_notification( localstore: &Arc + Send + Sync>, pubsub_manager: &Arc, @@ -567,6 +624,11 @@ impl Mint { &mint_quote.unit, )?; + if payment_amount_quote_unit == Amount::ZERO { + tracing::error!("Zero amount payments should not be recorded."); + return Err(Error::AmountUndefined); + } + tracing::debug!( "Payment received amount in quote unit {} {}", mint_quote.unit, @@ -737,6 +799,12 @@ impl Mint { let amount = melt_quote.amount; + tracing::info!( + "Mint quote {} paid {} from internal payment.", + mint_quote.id, + amount + ); + let total_paid = tx .increment_mint_quote_amount_paid(&mint_quote.id, amount, melt_quote.id.to_string()) .await?; diff --git a/crates/cdk/src/wallet/issue/issue_bolt12.rs b/crates/cdk/src/wallet/issue/issue_bolt12.rs index cf547798b..7df889425 100644 --- a/crates/cdk/src/wallet/issue/issue_bolt12.rs +++ b/crates/cdk/src/wallet/issue/issue_bolt12.rs @@ -91,7 +91,7 @@ impl Wallet { let quote_info = if let Some(quote) = quote_info { if quote.expiry.le(&unix_time()) && quote.expiry.ne(&0) { - tracing::info!("Minting after expiry"); + tracing::info!("Attempting to mint expired quote."); } quote.clone() @@ -114,7 +114,7 @@ impl Wallet { if amount == Amount::ZERO { tracing::error!("Cannot mint zero amount."); - return Err(Error::InvoiceAmountUndefined); + return Err(Error::UnpaidQuote); } let premint_secrets = match &spending_conditions { diff --git a/justfile b/justfile index f1c305f34..9b2520f1f 100644 --- a/justfile +++ b/justfile @@ -53,7 +53,7 @@ format: nixpkgs-fmt $(echo **.nix) # run doc tests -test: build +test: #!/usr/bin/env bash set -euo pipefail if [ ! -f Cargo.toml ]; then diff --git a/misc/interactive_regtest_mprocs.sh b/misc/interactive_regtest_mprocs.sh index 6354c8de6..e86215c42 100755 --- a/misc/interactive_regtest_mprocs.sh +++ b/misc/interactive_regtest_mprocs.sh @@ -101,6 +101,7 @@ export CDK_ITESTS_DIR=$(mktemp -d) export CDK_ITESTS_MINT_ADDR="127.0.0.1" export CDK_ITESTS_MINT_PORT_0=8085 export CDK_ITESTS_MINT_PORT_1=8087 +export CDK_ITESTS_MINT_PORT_2=8089 # Check if the temporary directory was created successfully if [[ ! -d "$CDK_ITESTS_DIR" ]]; then @@ -143,7 +144,7 @@ done < "$CDK_ITESTS_DIR/progress_pipe") & # Wait for regtest setup (up to 120 seconds) echo "Waiting for regtest network to be ready..." -for ((i=0; i<120; i++)); do +for ((i=0; i<220; i++)); do if [ -f "$CDK_ITESTS_DIR/signal_received" ]; then break fi @@ -158,16 +159,19 @@ fi # Create work directories for mints mkdir -p "$CDK_ITESTS_DIR/cln_mint" mkdir -p "$CDK_ITESTS_DIR/lnd_mint" +mkdir -p "$CDK_ITESTS_DIR/ldk_node_mint" # Set environment variables for easy access export CDK_TEST_MINT_URL="http://$CDK_ITESTS_MINT_ADDR:$CDK_ITESTS_MINT_PORT_0" export CDK_TEST_MINT_URL_2="http://$CDK_ITESTS_MINT_ADDR:$CDK_ITESTS_MINT_PORT_1" +export CDK_TEST_MINT_URL_3="http://$CDK_ITESTS_MINT_ADDR:$CDK_ITESTS_MINT_PORT_2" # Create state file for other terminal sessions ENV_FILE="/tmp/cdk_regtest_env" echo "export CDK_ITESTS_DIR=\"$CDK_ITESTS_DIR\"" > "$ENV_FILE" echo "export CDK_TEST_MINT_URL=\"$CDK_TEST_MINT_URL\"" >> "$ENV_FILE" echo "export CDK_TEST_MINT_URL_2=\"$CDK_TEST_MINT_URL_2\"" >> "$ENV_FILE" +echo "export CDK_TEST_MINT_URL_3=\"$CDK_TEST_MINT_URL_3\"" >> "$ENV_FILE" echo "export CDK_REGTEST_PID=\"$CDK_REGTEST_PID\"" >> "$ENV_FILE" # Get the project root directory (where justfile is located) @@ -230,9 +234,50 @@ echo "---" exec cargo run --bin cdk-mintd EOF +cat > "$CDK_ITESTS_DIR/start_ldk_node_mint.sh" << EOF +#!/usr/bin/env bash +cd "$PROJECT_ROOT" +export CDK_MINTD_URL="http://127.0.0.1:8089" +export CDK_MINTD_WORK_DIR="$CDK_ITESTS_DIR/ldk_node_mint" +export CDK_MINTD_LISTEN_HOST="127.0.0.1" +export CDK_MINTD_LISTEN_PORT=8089 +export CDK_MINTD_LN_BACKEND="ldk-node" +export CDK_MINTD_LOGGING_CONSOLE_LEVEL="debug" +export CDK_MINTD_LOGGING_FILE_LEVEL="debug" +export CDK_MINTD_MNEMONIC="abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about" +export RUST_BACKTRACE=1 +export CDK_MINTD_DATABASE="$CDK_MINTD_DATABASE" + +# LDK Node specific environment variables +export CDK_MINTD_LDK_NODE_BITCOIN_NETWORK="regtest" +export CDK_MINTD_LDK_NODE_CHAIN_SOURCE_TYPE="bitcoinrpc" +export CDK_MINTD_LDK_NODE_BITCOIND_RPC_HOST="127.0.0.1" +export CDK_MINTD_LDK_NODE_BITCOIND_RPC_PORT=18443 +export CDK_MINTD_LDK_NODE_BITCOIND_RPC_USER="testuser" +export CDK_MINTD_LDK_NODE_BITCOIND_RPC_PASSWORD="testpass" +export CDK_MINTD_LDK_NODE_STORAGE_DIR_PATH="$CDK_ITESTS_DIR/ldk_mint" +export CDK_MINTD_LDK_NODE_LDK_NODE_HOST="127.0.0.1" +export CDK_MINTD_LDK_NODE_LDK_NODE_PORT=8090 +export CDK_MINTD_LDK_NODE_GOSSIP_SOURCE_TYPE="p2p" +export CDK_MINTD_LDK_NODE_FEE_PERCENT=0.02 +export CDK_MINTD_LDK_NODE_RESERVE_FEE_MIN=2 + +echo "Starting LDK Node Mint on port 8089..." +echo "Project root: $PROJECT_ROOT" +echo "Working directory: \$CDK_MINTD_WORK_DIR" +echo "Bitcoin RPC: 127.0.0.1:18443 (testuser/testpass)" +echo "LDK Node listen: 127.0.0.1:8090" +echo "Storage directory: \$CDK_MINTD_LDK_NODE_STORAGE_DIR_PATH" +echo "Database type: \$CDK_MINTD_DATABASE" +echo "---" + +exec cargo run --bin cdk-mintd --features ldk-node +EOF + # Make scripts executable chmod +x "$CDK_ITESTS_DIR/start_cln_mint.sh" chmod +x "$CDK_ITESTS_DIR/start_lnd_mint.sh" +chmod +x "$CDK_ITESTS_DIR/start_ldk_node_mint.sh" echo echo "==============================================" @@ -247,16 +292,18 @@ echo " • LND Node 1: https://localhost:10009" echo " • LND Node 2: https://localhost:10010" echo echo "CDK Mints (will be managed by mprocs):" -echo " • CLN Mint: $CDK_TEST_MINT_URL" -echo " • LND Mint: $CDK_TEST_MINT_URL_2" +echo " • CLN Mint: $CDK_TEST_MINT_URL" +echo " • LND Mint: $CDK_TEST_MINT_URL_2" +echo " • LDK Node Mint: $CDK_TEST_MINT_URL_3" echo echo "Files and Directories:" echo " • Working Directory: $CDK_ITESTS_DIR" -echo " • Start Scripts: $CDK_ITESTS_DIR/start_{cln,lnd}_mint.sh" +echo " • Start Scripts: $CDK_ITESTS_DIR/start_{cln,lnd,ldk_node}_mint.sh" echo echo "Environment Variables (available in other terminals):" echo " • CDK_TEST_MINT_URL=\"$CDK_TEST_MINT_URL\"" echo " • CDK_TEST_MINT_URL_2=\"$CDK_TEST_MINT_URL_2\"" +echo " • CDK_TEST_MINT_URL_3=\"$CDK_TEST_MINT_URL_3\"" echo " • CDK_ITESTS_DIR=\"$CDK_ITESTS_DIR\"" echo echo "Starting mprocs with direct process management..." @@ -290,6 +337,13 @@ procs: CDK_ITESTS_DIR: "$CDK_ITESTS_DIR" CDK_MINTD_DATABASE: "$CDK_MINTD_DATABASE" + ldk-node-mint: + shell: "$CDK_ITESTS_DIR/start_ldk_node_mint.sh" + autostart: true + env: + CDK_ITESTS_DIR: "$CDK_ITESTS_DIR" + CDK_MINTD_DATABASE: "$CDK_MINTD_DATABASE" + bitcoind: shell: "while [ ! -f $CDK_ITESTS_DIR/bitcoin/regtest/debug.log ]; do sleep 1; done && tail -f $CDK_ITESTS_DIR/bitcoin/regtest/debug.log" autostart: true @@ -309,6 +363,10 @@ procs: lnd-two: shell: "while [ ! -f $CDK_ITESTS_DIR/lnd/two/logs/bitcoin/regtest/lnd.log ]; do sleep 1; done && tail -f $CDK_ITESTS_DIR/lnd/two/logs/bitcoin/regtest/lnd.log" autostart: true + + ldk-node: + shell: "while [ ! -f $CDK_ITESTS_DIR/ldk_mint/ldk_node.log ]; do sleep 1; done && $PROJECT_ROOT/misc/scripts/filtered_ldk_node_log.sh $CDK_ITESTS_DIR/ldk_mint/ldk_node.log" + autostart: true settings: mouse_scroll_speed: 3 diff --git a/misc/itests.sh b/misc/itests.sh index 7fc490f46..dd5f01e81 100755 --- a/misc/itests.sh +++ b/misc/itests.sh @@ -22,11 +22,11 @@ cleanup() { echo "Mint binary terminated" - # Remove the temporary directory - if [ ! -z "$CDK_ITESTS_DIR" ] && [ -d "$CDK_ITESTS_DIR" ]; then - rm -rf "$CDK_ITESTS_DIR" - echo "Temp directory removed: $CDK_ITESTS_DIR" - fi + # # Remove the temporary directory + # if [ ! -z "$CDK_ITESTS_DIR" ] && [ -d "$CDK_ITESTS_DIR" ]; then + # rm -rf "$CDK_ITESTS_DIR" + # echo "Temp directory removed: $CDK_ITESTS_DIR" + # fi # Unset all environment variables unset CDK_ITESTS_DIR @@ -39,6 +39,7 @@ cleanup() { unset CDK_REGTEST_PID unset RUST_BACKTRACE unset CDK_TEST_REGTEST + unset CDK_TEST_LIGHTNING_CLIENT } # Set up trap to call cleanup on script exit @@ -61,7 +62,6 @@ fi echo "Temp directory created: $CDK_ITESTS_DIR" export CDK_MINTD_DATABASE="$1" -cargo build -p cdk-integration-tests cargo build --bin start_regtest_mints echo "Starting regtest and mints" @@ -115,7 +115,7 @@ export CDK_TEST_MINT_URL_2 URL="$CDK_TEST_MINT_URL/v1/info" -TIMEOUT=100 +TIMEOUT=500 START_TIME=$(date +%s) # Loop until the endpoint returns a 200 OK status or timeout is reached while true; do @@ -177,29 +177,30 @@ while true; do done # Run cargo test -echo "Running regtest test with CLN mint" +echo "Running regtest test with CLN mint and CLN client" +export CDK_TEST_LIGHTNING_CLIENT="lnd" cargo test -p cdk-integration-tests --test regtest if [ $? -ne 0 ]; then - echo "regtest test failed, exiting" + echo "regtest test with cln mint failed, exiting" exit 1 fi -echo "Running happy_path_mint_wallet test with CLN mint" +echo "Running happy_path_mint_wallet test with CLN mint and CLN client" cargo test -p cdk-integration-tests --test happy_path_mint_wallet if [ $? -ne 0 ]; then - echo "happy_path_mint_wallet test failed, exiting" + echo "happy_path_mint_wallet with cln mint test failed, exiting" exit 1 fi # Run cargo test with the http_subscription feature -echo "Running regtest test with http_subscription feature" +echo "Running regtest test with http_subscription feature (CLN client)" cargo test -p cdk-integration-tests --test regtest --features http_subscription if [ $? -ne 0 ]; then echo "regtest test with http_subscription failed, exiting" exit 1 fi -echo "Running regtest test with cln mint for bolt12" +echo "Running regtest test with cln mint for bolt12 (CLN client)" cargo test -p cdk-integration-tests --test bolt12 if [ $? -ne 0 ]; then echo "regtest test failed, exiting" @@ -209,24 +210,73 @@ fi # Switch Mints: Run tests with LND mint echo "Switching to LND mint for tests" -echo "Running regtest test with LND mint" +echo "Running regtest test with LND mint and LND client" CDK_TEST_MINT_URL_SWITCHED=$CDK_TEST_MINT_URL_2 CDK_TEST_MINT_URL_2_SWITCHED=$CDK_TEST_MINT_URL export CDK_TEST_MINT_URL=$CDK_TEST_MINT_URL_SWITCHED export CDK_TEST_MINT_URL_2=$CDK_TEST_MINT_URL_2_SWITCHED -cargo test -p cdk-integration-tests --test regtest + cargo test -p cdk-integration-tests --test regtest + if [ $? -ne 0 ]; then + echo "regtest test with LND mint failed, exiting" + exit 1 + fi + + echo "Running happy_path_mint_wallet test with LND mint and LND client" + cargo test -p cdk-integration-tests --test happy_path_mint_wallet + if [ $? -ne 0 ]; then + echo "happy_path_mint_wallet test with LND mint failed, exiting" + exit 1 + fi + + +export CDK_TEST_MINT_URL="http://127.0.0.1:8089" + +TIMEOUT=100 +START_TIME=$(date +%s) +# Loop until the endpoint returns a 200 OK status or timeout is reached +while true; do + # Get the current time + CURRENT_TIME=$(date +%s) + + # Calculate the elapsed time + ELAPSED_TIME=$((CURRENT_TIME - START_TIME)) + + # Check if the elapsed time exceeds the timeout + if [ $ELAPSED_TIME -ge $TIMEOUT ]; then + echo "Timeout of $TIMEOUT seconds reached. Exiting..." + exit 1 + fi + + # Make a request to the endpoint and capture the HTTP status code + HTTP_STATUS=$(curl -o /dev/null -s -w "%{http_code}" $CDK_TEST_MINT_URL/v1/info) + + # Check if the HTTP status is 200 OK + if [ "$HTTP_STATUS" -eq 200 ]; then + echo "Received 200 OK from $CDK_TEST_MINT_URL" + break + else + echo "Waiting for 200 OK response, current status: $HTTP_STATUS" + sleep 2 # Wait for 2 seconds before retrying + fi +done + + +echo "Running happy_path_mint_wallet test with LDK mint and CLN client" +export CDK_TEST_LIGHTNING_CLIENT="cln" # Use CLN client for LDK tests +cargo test -p cdk-integration-tests --test happy_path_mint_wallet if [ $? -ne 0 ]; then - echo "regtest test with LND mint failed, exiting" + echo "happy_path_mint_wallet test with LDK mint failed, exiting" exit 1 fi -echo "Running happy_path_mint_wallet test with LND mint" -cargo test -p cdk-integration-tests --test happy_path_mint_wallet +echo "Running regtest test with LDK mint and CLN client" +cargo test -p cdk-integration-tests --test regtest if [ $? -ne 0 ]; then - echo "happy_path_mint_wallet test with LND mint failed, exiting" + echo "regtest test LDK mint failed, exiting" exit 1 fi + echo "All tests passed successfully" exit 0 diff --git a/misc/mintd_payment_processor.sh b/misc/mintd_payment_processor.sh index 5d8331551..f43a1034e 100755 --- a/misc/mintd_payment_processor.sh +++ b/misc/mintd_payment_processor.sh @@ -129,7 +129,6 @@ cargo run --bin cdk-payment-processor & CDK_PAYMENT_PROCESSOR_PID=$! -sleep 10; export CDK_MINTD_URL="http://$CDK_ITESTS_MINT_ADDR:$CDK_ITESTS_MINT_PORT_0"; export CDK_MINTD_WORK_DIR="$CDK_ITESTS_DIR"; @@ -141,6 +140,8 @@ export CDK_MINTD_GRPC_PAYMENT_PROCESSOR_PORT="8090"; export CDK_MINTD_GRPC_PAYMENT_PROCESSOR_SUPPORTED_UNITS="sat"; export CDK_MINTD_MNEMONIC="eye survey guilt napkin crystal cup whisper salt luggage manage unveil loyal"; +cargo build --bin cdk-mintd --no-default-features --features grpc-processor + cargo run --bin cdk-mintd --no-default-features --features grpc-processor & CDK_MINTD_PID=$! diff --git a/misc/regtest_helper.sh b/misc/regtest_helper.sh index 5e366825d..6d858ccbe 100755 --- a/misc/regtest_helper.sh +++ b/misc/regtest_helper.sh @@ -12,6 +12,7 @@ elif [ ! -z "$CDK_ITESTS_DIR" ]; then echo "export CDK_ITESTS_DIR=\"$CDK_ITESTS_DIR\"" > "$ENV_FILE" echo "export CDK_TEST_MINT_URL=\"$CDK_TEST_MINT_URL\"" >> "$ENV_FILE" echo "export CDK_TEST_MINT_URL_2=\"$CDK_TEST_MINT_URL_2\"" >> "$ENV_FILE" + echo "export CDK_TEST_MINT_URL_3=\"$CDK_TEST_MINT_URL_3\"" >> "$ENV_FILE" echo "export CDK_MINTD_PID=\"$CDK_MINTD_PID\"" >> "$ENV_FILE" echo "export CDK_MINTD_LND_PID=\"$CDK_MINTD_LND_PID\"" >> "$ENV_FILE" echo "export CDK_REGTEST_PID=\"$CDK_REGTEST_PID\"" >> "$ENV_FILE" @@ -111,6 +112,11 @@ mint_info() { echo echo "LND Mint (Port 8087):" curl -s "$CDK_TEST_MINT_URL_2/v1/info" | jq . 2>/dev/null || curl -s "$CDK_TEST_MINT_URL_2/v1/info" + echo + if [ ! -z "$CDK_TEST_MINT_URL_3" ]; then + echo "LDK Node Mint (Port 8089):" + curl -s "$CDK_TEST_MINT_URL_3/v1/info" | jq . 2>/dev/null || curl -s "$CDK_TEST_MINT_URL_3/v1/info" + fi } mint_test() { @@ -125,6 +131,9 @@ show_env() { echo "CDK_ITESTS_DIR=$CDK_ITESTS_DIR" echo "CDK_TEST_MINT_URL=$CDK_TEST_MINT_URL" echo "CDK_TEST_MINT_URL_2=$CDK_TEST_MINT_URL_2" + if [ ! -z "$CDK_TEST_MINT_URL_3" ]; then + echo "CDK_TEST_MINT_URL_3=$CDK_TEST_MINT_URL_3" + fi echo "CDK_MINTD_PID=$CDK_MINTD_PID" echo "CDK_MINTD_LND_PID=$CDK_MINTD_LND_PID" echo "CDK_REGTEST_PID=$CDK_REGTEST_PID" @@ -144,6 +153,15 @@ show_logs() { else echo "Log file not found" fi + echo + if [ ! -z "$CDK_TEST_MINT_URL_3" ]; then + echo "=== Recent LDK Node Mint Logs ===" + if [ -f "$CDK_ITESTS_DIR/ldk_node_mint/mintd.log" ]; then + tail -10 "$CDK_ITESTS_DIR/ldk_node_mint/mintd.log" + else + echo "Log file not found" + fi + fi } start_mprocs() { @@ -179,6 +197,10 @@ procs: shell: "touch $CDK_ITESTS_DIR/lnd_mint/mintd.log && tail -f $CDK_ITESTS_DIR/lnd_mint/mintd.log" autostart: true + ldk-node-mint: + shell: "touch $CDK_ITESTS_DIR/ldk_node_mint/mintd.log && tail -f $CDK_ITESTS_DIR/ldk_node_mint/mintd.log" + autostart: true + bitcoind: shell: "touch $CDK_ITESTS_DIR/bitcoin/regtest/debug.log && tail -f $CDK_ITESTS_DIR/bitcoin/regtest/debug.log" autostart: true @@ -198,6 +220,10 @@ procs: lnd-two: shell: "while [ ! -f $CDK_ITESTS_DIR/lnd/two/logs/bitcoin/regtest/lnd.log ]; do sleep 1; done && tail -f $CDK_ITESTS_DIR/lnd/two/logs/bitcoin/regtest/lnd.log" autostart: true + + ldk-node: + shell: "while [ ! -f $CDK_ITESTS_DIR/ldk_node_mint/ldk_storage/ldk_node.log ]; do sleep 1; done && tail -f $CDK_ITESTS_DIR/ldk_node_mint/ldk_storage/ldk_node.log" + autostart: true settings: mouse_scroll_speed: 3 @@ -248,6 +274,14 @@ show_status() { else echo " ❌ LND Mint not responding" fi + + if [ ! -z "$CDK_TEST_MINT_URL_3" ]; then + if curl -s "$CDK_TEST_MINT_URL_3/v1/info" >/dev/null 2>&1; then + echo " ✓ LDK Node Mint responding" + else + echo " ❌ LDK Node Mint not responding" + fi + fi } restart_mints() { diff --git a/misc/scripts/filtered_ldk_node_log.sh b/misc/scripts/filtered_ldk_node_log.sh new file mode 100755 index 000000000..10ee9541e --- /dev/null +++ b/misc/scripts/filtered_ldk_node_log.sh @@ -0,0 +1,19 @@ +#!/usr/bin/env bash + +# Filtered log viewer for LDK Node that excludes "falling back to default fee rate" messages +# Usage: ./misc/scripts/filtered_ldk_node_log.sh [log_file_path] + +LOG_FILE="$1" + +# If no log file specified, use the default pattern +if [ -z "$LOG_FILE" ]; then + LOG_FILE="$CDK_ITESTS_DIR/ldk_mint/ldk_node.log" +fi + +# Wait for log file to exist, then tail it with filtering +while [ ! -f "$LOG_FILE" ]; do + sleep 1 +done + +# Tail the log file and filter out fee rate fallback messages +tail -f "$LOG_FILE" | grep -v -E "Falling back to default of 1 sat/vb|Failed to retrieve fee rate estimates" From 809d9c80122825f686201411909d5fd6504e282f Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Tue, 26 Aug 2025 06:29:20 +0100 Subject: [PATCH 105/321] Fix p2pk (#996) * fix: refund keys must sign after locktime * fix: custom tags * refactor: locktime verification and refund --- crates/cashu/src/nuts/nut11/mod.rs | 172 +++++++++++++++++++++++------ 1 file changed, 140 insertions(+), 32 deletions(-) diff --git a/crates/cashu/src/nuts/nut11/mod.rs b/crates/cashu/src/nuts/nut11/mod.rs index 675cba790..514660e49 100644 --- a/crates/cashu/src/nuts/nut11/mod.rs +++ b/crates/cashu/src/nuts/nut11/mod.rs @@ -146,6 +146,45 @@ impl Proof { let witness_signatures = witness_signatures.ok_or(Error::SignaturesNotProvided)?; let mut pubkeys = spending_conditions.pubkeys.clone().unwrap_or_default(); + // NUT-11 enforcement per spec: + // - If locktime has passed and refund keys are present, spend must be authorized by + // refund pubkeys (n_sigs_refund-of-refund). This supersedes normal pubkey enforcement + // after expiry. + // - If locktime has passed and no refund keys are present, proof becomes spendable + // without further key checks (anyone-can-spend behavior). + // - Otherwise (before locktime), enforce normal multisig on the set of authorized + // pubkeys: Secret.data plus optional `pubkeys` tag, requiring n_sigs unique signers. + + let now = unix_time(); + + if let Some(locktime) = spending_conditions.locktime { + if now >= locktime { + if let Some(refund_keys) = spending_conditions.refund_keys.clone() { + let needed_refund_sigs = + spending_conditions.num_sigs_refund.unwrap_or(1) as usize; + let mut valid_pubkeys = HashSet::new(); + + // After locktime, require signatures from refund keys + for s in witness_signatures.iter() { + let sig = Signature::from_str(s).map_err(|_| Error::InvalidSignature)?; + for v in &refund_keys { + if v.verify(msg, &sig).is_ok() { + valid_pubkeys.insert(v); + if valid_pubkeys.len() >= needed_refund_sigs { + return Ok(()); + } + } + } + } + + // If locktime and refund keys were specified they must sign after locktime + return Err(Error::SpendConditionsNotMet); + } else { + // If only locktime is specified, consider it spendable after locktime + return Ok(()); + } + } + } if secret.kind().eq(&Kind::P2PK) { pubkeys.push(PublicKey::from_str(secret.secret_data().data())?); @@ -175,34 +214,6 @@ impl Proof { return Ok(()); } - if let (Some(locktime), Some(refund_keys)) = ( - spending_conditions.locktime, - spending_conditions.refund_keys, - ) { - let needed_refund_sigs = spending_conditions.num_sigs_refund.unwrap_or(1) as usize; - - let mut valid_pubkeys = HashSet::new(); - - // If lock time has passed check if refund witness signature is valid - if locktime.lt(&unix_time()) { - for s in witness_signatures.iter() { - for v in &refund_keys { - let sig = Signature::from_str(s).map_err(|_| Error::InvalidSignature)?; - - if v.verify(msg, &sig).is_ok() { - if !valid_pubkeys.insert(v) { - return Err(Error::DuplicateSignature); - } - - if valid_pubkeys.len() >= needed_refund_sigs { - return Ok(()); - } - } - } - } - } - } - Err(Error::SpendConditionsNotMet) } } @@ -502,7 +513,7 @@ impl From for Vec> { refund_keys, num_sigs, sig_flag, - num_sigs_refund: _, + num_sigs_refund, } = conditions; let mut tags = Vec::new(); @@ -522,6 +533,11 @@ impl From for Vec> { if let Some(refund_keys) = refund_keys { tags.push(Tag::Refund(refund_keys).as_vec()) } + + if let Some(num_sigs_refund) = num_sigs_refund { + tags.push(Tag::NSigsRefund(num_sigs_refund).as_vec()) + } + tags.push(Tag::SigFlag(sig_flag).as_vec()); tags } @@ -577,13 +593,22 @@ impl TryFrom>> for Conditions { None }; + let num_sigs_refund = if let Some(tag) = tags.get(&TagKind::NSigsRefund) { + match tag { + Tag::NSigsRefund(num_sigs) => Some(*num_sigs), + _ => None, + } + } else { + None + }; + Ok(Conditions { locktime, pubkeys, refund_keys, num_sigs, sig_flag, - num_sigs_refund: None, + num_sigs_refund, }) } } @@ -619,7 +644,7 @@ impl fmt::Display for TagKind { Self::Refund => write!(f, "refund"), Self::Pubkeys => write!(f, "pubkeys"), Self::NSigsRefund => write!(f, "n_sigs_refund"), - Self::Custom(kind) => write!(f, "{kind}"), + Self::Custom(c) => write!(f, "{c}"), } } } @@ -635,6 +660,7 @@ where "locktime" => Self::Locktime, "refund" => Self::Refund, "pubkeys" => Self::Pubkeys, + "n_sigs_refund" => Self::NSigsRefund, t => Self::Custom(t.to_owned()), } } @@ -741,6 +767,10 @@ pub enum Tag { Refund(Vec), /// Pubkeys [`Tag`] PubKeys(Vec), + /// Number of Sigs refund [`Tag`] + NSigsRefund(u64), + /// Custom tag + Custom(String, Vec), } impl Tag { @@ -752,6 +782,8 @@ impl Tag { Self::LockTime(_) => TagKind::Locktime, Self::Refund(_) => TagKind::Refund, Self::PubKeys(_) => TagKind::Pubkeys, + Self::NSigsRefund(_) => TagKind::NSigsRefund, + Self::Custom(tag, _) => TagKind::Custom(tag.to_string()), } } @@ -792,7 +824,16 @@ where Ok(Self::PubKeys(pubkeys)) } - _ => Err(Error::UnknownTag), + TagKind::NSigsRefund => Ok(Tag::NSigsRefund(tag[1].as_ref().parse()?)), + TagKind::Custom(name) => { + let tags = tag + .iter() + .skip(1) + .map(|p| p.as_ref().to_string()) + .collect::>(); + + Ok(Self::Custom(name, tags)) + } } } } @@ -818,6 +859,18 @@ impl From for Vec { } tag } + Tag::NSigsRefund(num_sigs) => { + vec![TagKind::NSigsRefund.to_string(), num_sigs.to_string()] + } + Tag::Custom(name, c) => { + let mut tag = vec![name]; + + for t in c { + tag.push(t); + } + + tag + } } } } @@ -1360,6 +1413,61 @@ mod tests { assert!(invalid_proof.verify_p2pk().is_err()); } + #[test] + fn sig_with_non_refund_keys_after_locktime() { + let secret_key = + SecretKey::from_str("99590802251e78ee1051648439eedb003dc539093a48a44e7b8f2642c909ea37") + .unwrap(); + + let signing_key_two = + SecretKey::from_str("0000000000000000000000000000000000000000000000000000000000000001") + .unwrap(); + + let signing_key_three = + SecretKey::from_str("7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f") + .unwrap(); + let v_key: PublicKey = secret_key.public_key(); + let v_key_two: PublicKey = signing_key_two.public_key(); + let v_key_three: PublicKey = signing_key_three.public_key(); + + let conditions = Conditions { + locktime: Some(21), + pubkeys: Some(vec![v_key_three]), + refund_keys: Some(vec![v_key, v_key_two]), + num_sigs: None, + sig_flag: SigFlag::SigInputs, + num_sigs_refund: Some(2), + }; + + let secret: Secret = Nut10Secret::new(Kind::P2PK, v_key.to_string(), Some(conditions)) + .try_into() + .unwrap(); + + let mut proof = Proof { + keyset_id: Id::from_str("009a1f293253e41e").unwrap(), + amount: Amount::ZERO, + secret, + c: PublicKey::from_str( + "02698c4e2b5f9534cd0687d87513c759790cf829aa5739184a3e3735471fbda904", + ) + .unwrap(), + witness: Some(Witness::P2PKWitness(P2PKWitness { signatures: vec![] })), + dleq: None, + }; + + proof.sign_p2pk(signing_key_three.clone()).unwrap(); + + assert!(proof.verify_p2pk().is_err()); + + proof.witness = None; + + proof.sign_p2pk(secret_key).unwrap(); + assert!(proof.verify_p2pk().is_err()); + proof.sign_p2pk(signing_key_two).unwrap(); + + assert!(proof.verify_p2pk().is_ok()); + } + // Helper functions for melt request tests fn create_test_proof(secret: Secret, pubkey: PublicKey, id: &str) -> Proof { Proof { From 4de5566451c1da7aaed84aa06113bc1e2dce6fcb Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Tue, 26 Aug 2025 08:20:28 +0100 Subject: [PATCH 106/321] feat: use trixie (#998) --- Dockerfile | 2 +- Dockerfile.arm | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Dockerfile b/Dockerfile index 85bc2e03c..9d37caf1c 100644 --- a/Dockerfile +++ b/Dockerfile @@ -13,7 +13,7 @@ COPY crates ./crates RUN nix develop --extra-experimental-features nix-command --extra-experimental-features flakes --command cargo build --release --bin cdk-mintd --features redis # Create a runtime stage -FROM debian:sid-slim +FROM debian:trixie-slim # Set the working directory WORKDIR /usr/src/app diff --git a/Dockerfile.arm b/Dockerfile.arm index 7f4333844..901007623 100644 --- a/Dockerfile.arm +++ b/Dockerfile.arm @@ -16,7 +16,7 @@ RUN echo 'filter-syscalls = false' > /etc/nix/nix.conf RUN nix develop --extra-platforms aarch64-linux --extra-experimental-features nix-command --extra-experimental-features flakes --command cargo build --release --bin cdk-mintd --features redis # Create a runtime stage -FROM debian:sid-slim +FROM debian:trixie-slim # Set the working directory WORKDIR /usr/src/app From 218b39a6704ccf5835da4be0d7bc2c6c77c8326b Mon Sep 17 00:00:00 2001 From: C Date: Tue, 26 Aug 2025 07:57:15 -0300 Subject: [PATCH 107/321] Introduce Future Streams for Payments and Minting Proofs (#985) * Introduce Future Streams for Payments and Minting Proofs Introduce Future Streams (`ProofStream`, `PaymentStream`) for Payments and Proofs, an easier to use interface, async friendly, to interact for the mint waiting for payments of mints for Bolt11 and Bolt12. --------- Co-authored-by: thesimplekid --- crates/cdk-cli/src/sub_commands/mint.rs | 30 +- crates/cdk-common/src/error.rs | 7 +- .../src/init_pure_tests.rs | 13 +- crates/cdk-integration-tests/src/lib.rs | 14 +- crates/cdk-integration-tests/tests/bolt12.rs | 79 +++--- .../cdk-integration-tests/tests/fake_auth.rs | 12 +- .../tests/fake_wallet.rs | 259 ++++++++---------- .../tests/happy_path_mint_wallet.rs | 74 ++--- crates/cdk-integration-tests/tests/regtest.rs | 70 ++--- .../cdk-integration-tests/tests/test_fees.rs | 41 ++- crates/cdk/Cargo.toml | 8 + .../examples/mint-token-bolt12-with-stream.rs | 72 +++++ crates/cdk/examples/mint-token-bolt12.rs | 59 ++++ crates/cdk/src/lib.rs | 4 + crates/cdk/src/mint/subscription/manager.rs | 4 +- crates/cdk/src/wallet/mod.rs | 3 +- crates/cdk/src/wallet/streams/mod.rs | 122 +++++++++ crates/cdk/src/wallet/streams/payment.rs | 205 ++++++++++++++ crates/cdk/src/wallet/streams/proof.rs | 185 +++++++++++++ crates/cdk/src/wallet/streams/wait.rs | 50 ++++ crates/cdk/src/wallet/wait.rs | 119 -------- 21 files changed, 988 insertions(+), 442 deletions(-) create mode 100644 crates/cdk/examples/mint-token-bolt12-with-stream.rs create mode 100644 crates/cdk/examples/mint-token-bolt12.rs create mode 100644 crates/cdk/src/wallet/streams/mod.rs create mode 100644 crates/cdk/src/wallet/streams/payment.rs create mode 100644 crates/cdk/src/wallet/streams/proof.rs create mode 100644 crates/cdk/src/wallet/streams/wait.rs delete mode 100644 crates/cdk/src/wallet/wait.rs diff --git a/crates/cdk-cli/src/sub_commands/mint.rs b/crates/cdk-cli/src/sub_commands/mint.rs index 51a90a6a0..670e72dcc 100644 --- a/crates/cdk-cli/src/sub_commands/mint.rs +++ b/crates/cdk-cli/src/sub_commands/mint.rs @@ -1,5 +1,4 @@ use std::str::FromStr; -use std::time::Duration; use anyhow::{anyhow, Result}; use cdk::amount::SplitTarget; @@ -7,7 +6,7 @@ use cdk::mint_url::MintUrl; use cdk::nuts::nut00::ProofsMethods; use cdk::nuts::{CurrencyUnit, PaymentMethod}; use cdk::wallet::MultiMintWallet; -use cdk::Amount; +use cdk::{Amount, StreamExt}; use clap::Args; use serde::{Deserialize, Serialize}; @@ -96,26 +95,17 @@ pub async fn mint( let mut amount_minted = Amount::ZERO; - loop { - let proofs = wallet - .wait_and_mint_quote( - quote.clone(), - SplitTarget::default(), - None, - Duration::from_secs(sub_command_args.wait_duration), - ) - .await?; + let mut proof_streams = wallet.proof_stream(quote, SplitTarget::default(), None); + while let Some(proofs) = proof_streams.next().await { + let proofs = match proofs { + Ok(proofs) => proofs, + Err(err) => { + tracing::error!("Proof streams ended with {:?}", err); + break; + } + }; amount_minted += proofs.total_amount()?; - - if sub_command_args.quote_id.is_none() || quote.payment_method == PaymentMethod::Bolt11 { - break; - } else { - println!( - "Minted {} waiting for next payment.", - proofs.total_amount()? - ); - } } println!("Received {amount_minted} from mint {mint_url}"); diff --git a/crates/cdk-common/src/error.rs b/crates/cdk-common/src/error.rs index 0009bcc63..cffd8d882 100644 --- a/crates/cdk-common/src/error.rs +++ b/crates/cdk-common/src/error.rs @@ -111,13 +111,14 @@ pub enum Error { #[error("Could not parse bolt12")] Bolt12parse, + /// BIP353 address parsing error + #[error("Failed to parse BIP353 address: {0}")] + Bip353Parse(String), + /// Operation timeout #[error("Operation timeout")] Timeout, - /// BIP353 address parsing error - #[error("Failed to parse BIP353 address: {0}")] - Bip353Parse(String), /// BIP353 address resolution error #[error("Failed to resolve BIP353 address: {0}")] Bip353Resolve(String), diff --git a/crates/cdk-integration-tests/src/init_pure_tests.rs b/crates/cdk-integration-tests/src/init_pure_tests.rs index 91101834c..c4a27ab97 100644 --- a/crates/cdk-integration-tests/src/init_pure_tests.rs +++ b/crates/cdk-integration-tests/src/init_pure_tests.rs @@ -3,7 +3,6 @@ use std::fmt::{Debug, Formatter}; use std::path::PathBuf; use std::str::FromStr; use std::sync::Arc; -use std::time::Duration; use std::{env, fs}; use anyhow::{anyhow, bail, Result}; @@ -23,7 +22,7 @@ use cdk::nuts::{ use cdk::types::{FeeReserve, QuoteTTL}; use cdk::util::unix_time; use cdk::wallet::{AuthWallet, MintConnector, Wallet, WalletBuilder}; -use cdk::{Amount, Error, Mint}; +use cdk::{Amount, Error, Mint, StreamExt}; use cdk_fake_wallet::FakeWallet; use tokio::sync::RwLock; use tracing_subscriber::EnvFilter; @@ -361,12 +360,10 @@ pub async fn fund_wallet( let desired_amount = Amount::from(amount); let quote = wallet.mint_quote(desired_amount, None).await?; - wallet - .wait_for_payment("e, Duration::from_secs(60)) - .await?; - Ok(wallet - .mint("e.id, split_target.unwrap_or_default(), None) - .await? + .proof_stream(quote, split_target.unwrap_or_default(), None) + .next() + .await + .expect("proofs")? .total_amount()?) } diff --git a/crates/cdk-integration-tests/src/lib.rs b/crates/cdk-integration-tests/src/lib.rs index 675e94021..cd5f45387 100644 --- a/crates/cdk-integration-tests/src/lib.rs +++ b/crates/cdk-integration-tests/src/lib.rs @@ -24,11 +24,10 @@ use anyhow::{anyhow, bail, Result}; use cashu::Bolt11Invoice; use cdk::amount::{Amount, SplitTarget}; use cdk::nuts::State; -use cdk::Wallet; +use cdk::{StreamExt, Wallet}; use cdk_fake_wallet::create_fake_invoice; use init_regtest::{get_lnd_dir, LND_RPC_ADDR}; use ln_regtest_rs::ln_client::{ClnClient, LightningClient, LndClient}; -use tokio::time::Duration; use crate::init_regtest::get_cln_dir; @@ -44,15 +43,12 @@ pub async fn fund_wallet(wallet: Arc, amount: Amount) { .await .expect("Could not get mint quote"); - wallet - .wait_for_payment("e, Duration::from_secs(60)) - .await - .expect("wait for mint failed"); - let _proofs = wallet - .mint("e.id, SplitTarget::default(), None) + .proof_stream(quote, SplitTarget::default(), None) + .next() .await - .expect("Could not mint"); + .expect("proofs") + .expect("proofs with no error"); } pub fn get_mint_url_from_env() -> String { diff --git a/crates/cdk-integration-tests/tests/bolt12.rs b/crates/cdk-integration-tests/tests/bolt12.rs index 68e340270..44873f748 100644 --- a/crates/cdk-integration-tests/tests/bolt12.rs +++ b/crates/cdk-integration-tests/tests/bolt12.rs @@ -1,7 +1,6 @@ use std::env; use std::path::PathBuf; use std::sync::Arc; -use std::time::Duration; use anyhow::{bail, Result}; use bip39::Mnemonic; @@ -116,16 +115,14 @@ async fn test_regtest_bolt12_mint_multiple() -> Result<()> { .await .unwrap(); - wallet - .wait_for_payment(&mint_quote, Duration::from_secs(60)) - .await?; - - wallet.mint_bolt12_quote_state(&mint_quote.id).await?; - let proofs = wallet - .mint_bolt12(&mint_quote.id, None, SplitTarget::default(), None) - .await - .unwrap(); + .wait_and_mint_quote( + mint_quote.clone(), + SplitTarget::default(), + None, + tokio::time::Duration::from_secs(15), + ) + .await?; assert_eq!(proofs.total_amount().unwrap(), 10.into()); @@ -134,16 +131,14 @@ async fn test_regtest_bolt12_mint_multiple() -> Result<()> { .await .unwrap(); - wallet - .wait_for_payment(&mint_quote, Duration::from_secs(60)) - .await?; - - wallet.mint_bolt12_quote_state(&mint_quote.id).await?; - let proofs = wallet - .mint_bolt12(&mint_quote.id, None, SplitTarget::default(), None) - .await - .unwrap(); + .wait_and_mint_quote( + mint_quote.clone(), + SplitTarget::default(), + None, + tokio::time::Duration::from_secs(15), + ) + .await?; assert_eq!(proofs.total_amount().unwrap(), 11.into()); @@ -187,12 +182,13 @@ async fn test_regtest_bolt12_multiple_wallets() -> Result<()> { .pay_bolt12_offer(None, quote_one.request.clone()) .await?; - wallet_one - .wait_for_payment("e_one, Duration::from_secs(60)) - .await?; - let proofs_one = wallet_one - .mint_bolt12("e_one.id, None, SplitTarget::default(), None) + .wait_and_mint_quote( + quote_one.clone(), + SplitTarget::default(), + None, + tokio::time::Duration::from_secs(15), + ) .await?; assert_eq!(proofs_one.total_amount()?, 10_000.into()); @@ -205,13 +201,15 @@ async fn test_regtest_bolt12_multiple_wallets() -> Result<()> { .pay_bolt12_offer(None, quote_two.request.clone()) .await?; - wallet_two - .wait_for_payment("e_two, Duration::from_secs(60)) - .await?; - let proofs_two = wallet_two - .mint_bolt12("e_two.id, None, SplitTarget::default(), None) + .wait_and_mint_quote( + quote_two.clone(), + SplitTarget::default(), + None, + tokio::time::Duration::from_secs(15), + ) .await?; + assert_eq!(proofs_two.total_amount()?, 15_000.into()); let offer = cln_client @@ -280,20 +278,19 @@ async fn test_regtest_bolt12_melt() -> Result<()> { .pay_bolt12_offer(None, mint_quote.request.clone()) .await?; - // Wait for payment to be processed - wallet - .wait_for_payment(&mint_quote, Duration::from_secs(60)) + let _proofs = wallet + .wait_and_mint_quote( + mint_quote.clone(), + SplitTarget::default(), + None, + tokio::time::Duration::from_secs(15), + ) .await?; let offer = cln_client .get_bolt12_offer(Some(10_000), true, "hhhhhhhh".to_string()) .await?; - let _proofs = wallet - .mint_bolt12(&mint_quote.id, None, SplitTarget::default(), None) - .await - .unwrap(); - let quote = wallet.melt_bolt12_quote(offer.to_string(), None).await?; let melt = wallet.melt("e.id).await?; @@ -340,12 +337,14 @@ async fn test_regtest_bolt12_mint_extra() -> Result<()> { .pay_bolt12_offer(Some(pay_amount_msats), mint_quote.request.clone()) .await?; - wallet - .wait_for_payment(&mint_quote, Duration::from_secs(10)) - .await?; + let payment = wallet + .wait_for_payment(&mint_quote, tokio::time::Duration::from_secs(15)) + .await? + .unwrap(); let state = wallet.mint_bolt12_quote_state(&mint_quote.id).await?; + assert_eq!(payment, state.amount_paid); assert_eq!(state.amount_paid, (pay_amount_msats / 1_000).into()); assert_eq!(state.amount_issued, Amount::ZERO); diff --git a/crates/cdk-integration-tests/tests/fake_auth.rs b/crates/cdk-integration-tests/tests/fake_auth.rs index 26f089e37..ddf700a68 100644 --- a/crates/cdk-integration-tests/tests/fake_auth.rs +++ b/crates/cdk-integration-tests/tests/fake_auth.rs @@ -1,7 +1,6 @@ use std::env; use std::str::FromStr; use std::sync::Arc; -use std::time::Duration; use bip39::Mnemonic; use cashu::{MintAuthRequest, MintInfo}; @@ -331,15 +330,16 @@ async fn test_mint_with_auth() { let mint_amount: Amount = 100.into(); let quote = wallet.mint_quote(mint_amount, None).await.unwrap(); + let proofs = wallet .wait_and_mint_quote( - quote, - Default::default(), - Default::default(), - Duration::from_secs(10), + quote.clone(), + SplitTarget::default(), + None, + tokio::time::Duration::from_secs(15), ) .await - .unwrap(); + .expect("payment"); assert!(proofs.total_amount().expect("Could not get proofs amount") == mint_amount); } diff --git a/crates/cdk-integration-tests/tests/fake_wallet.rs b/crates/cdk-integration-tests/tests/fake_wallet.rs index 6d3cb3f24..1e01eed03 100644 --- a/crates/cdk-integration-tests/tests/fake_wallet.rs +++ b/crates/cdk-integration-tests/tests/fake_wallet.rs @@ -15,7 +15,6 @@ //! - Duplicate proof detection use std::sync::Arc; -use std::time::Duration; use bip39::Mnemonic; use cashu::Amount; @@ -27,6 +26,7 @@ use cdk::nuts::{ }; use cdk::wallet::types::TransactionDirection; use cdk::wallet::{HttpClient, MintConnector, Wallet}; +use cdk::StreamExt; use cdk_fake_wallet::{create_fake_invoice, FakeInvoiceDescription}; use cdk_integration_tests::attempt_to_swap_pending; use cdk_sqlite::wallet::memory; @@ -47,15 +47,13 @@ async fn test_fake_tokens_pending() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wallet - .wait_for_payment(&mint_quote, Duration::from_secs(60)) - .await - .unwrap(); + let mut proof_streams = wallet.proof_stream(mint_quote.clone(), SplitTarget::default(), None); - let _mint_amount = wallet - .mint(&mint_quote.id, SplitTarget::default(), None) + let _proofs = proof_streams + .next() .await - .unwrap(); + .expect("payment") + .expect("no error"); let fake_description = FakeInvoiceDescription { pay_invoice_state: MeltQuoteState::Pending, @@ -90,15 +88,13 @@ async fn test_fake_melt_payment_fail() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wallet - .wait_for_payment(&mint_quote, Duration::from_secs(60)) - .await - .unwrap(); + let mut proof_streams = wallet.proof_stream(mint_quote.clone(), SplitTarget::default(), None); - let _mint_amount = wallet - .mint(&mint_quote.id, SplitTarget::default(), None) + let _proofs = proof_streams + .next() .await - .unwrap(); + .expect("payment") + .expect("no error"); let fake_description = FakeInvoiceDescription { pay_invoice_state: MeltQuoteState::Unknown, @@ -156,15 +152,13 @@ async fn test_fake_melt_payment_fail_and_check() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wallet - .wait_for_payment(&mint_quote, Duration::from_secs(60)) - .await - .unwrap(); + let mut proof_streams = wallet.proof_stream(mint_quote.clone(), SplitTarget::default(), None); - let _mint_amount = wallet - .mint(&mint_quote.id, SplitTarget::default(), None) + let _proofs = proof_streams + .next() .await - .unwrap(); + .expect("payment") + .expect("no error"); let fake_description = FakeInvoiceDescription { pay_invoice_state: MeltQuoteState::Unknown, @@ -205,15 +199,13 @@ async fn test_fake_melt_payment_return_fail_status() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wallet - .wait_for_payment(&mint_quote, Duration::from_secs(60)) - .await - .unwrap(); + let mut proof_streams = wallet.proof_stream(mint_quote.clone(), SplitTarget::default(), None); - let _mint_amount = wallet - .mint(&mint_quote.id, SplitTarget::default(), None) + let _proofs = proof_streams + .next() .await - .unwrap(); + .expect("payment") + .expect("no error"); let fake_description = FakeInvoiceDescription { pay_invoice_state: MeltQuoteState::Failed, @@ -269,15 +261,13 @@ async fn test_fake_melt_payment_error_unknown() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wallet - .wait_for_payment(&mint_quote, Duration::from_secs(60)) - .await - .unwrap(); + let mut proof_streams = wallet.proof_stream(mint_quote.clone(), SplitTarget::default(), None); - let _mint_amount = wallet - .mint(&mint_quote.id, SplitTarget::default(), None) + let _proofs = proof_streams + .next() .await - .unwrap(); + .expect("payment") + .expect("no error"); let fake_description = FakeInvoiceDescription { pay_invoice_state: MeltQuoteState::Failed, @@ -333,15 +323,13 @@ async fn test_fake_melt_payment_err_paid() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wallet - .wait_for_payment(&mint_quote, Duration::from_secs(60)) - .await - .unwrap(); + let mut proof_streams = wallet.proof_stream(mint_quote.clone(), SplitTarget::default(), None); - let _mint_amount = wallet - .mint(&mint_quote.id, SplitTarget::default(), None) + let _proofs = proof_streams + .next() .await - .unwrap(); + .expect("payment") + .expect("no error"); let fake_description = FakeInvoiceDescription { pay_invoice_state: MeltQuoteState::Failed, @@ -375,15 +363,13 @@ async fn test_fake_melt_change_in_quote() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wallet - .wait_for_payment(&mint_quote, Duration::from_secs(60)) - .await - .unwrap(); + let mut proof_streams = wallet.proof_stream(mint_quote.clone(), SplitTarget::default(), None); - let _mint_amount = wallet - .mint(&mint_quote.id, SplitTarget::default(), None) + let _proofs = proof_streams + .next() .await - .unwrap(); + .expect("payment") + .expect("no error"); let transaction = wallet .list_transactions(Some(TransactionDirection::Incoming)) @@ -445,15 +431,13 @@ async fn test_fake_mint_with_witness() { .expect("failed to create new wallet"); let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wallet - .wait_for_payment(&mint_quote, Duration::from_secs(60)) - .await - .unwrap(); + let mut proof_streams = wallet.proof_stream(mint_quote.clone(), SplitTarget::default(), None); - let proofs = wallet - .mint(&mint_quote.id, SplitTarget::default(), None) + let proofs = proof_streams + .next() .await - .unwrap(); + .expect("payment") + .expect("no error"); let mint_amount = proofs.total_amount().unwrap(); @@ -474,10 +458,13 @@ async fn test_fake_mint_without_witness() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wallet - .wait_for_payment(&mint_quote, Duration::from_secs(60)) + let mut payment_streams = wallet.payment_stream(&mint_quote); + + payment_streams + .next() .await - .unwrap(); + .expect("payment") + .expect("no error"); let http_client = HttpClient::new(MINT_URL.parse().unwrap(), None); @@ -515,10 +502,13 @@ async fn test_fake_mint_with_wrong_witness() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wallet - .wait_for_payment(&mint_quote, Duration::from_secs(60)) + let mut payment_streams = wallet.payment_stream(&mint_quote); + + payment_streams + .next() .await - .unwrap(); + .expect("payment") + .expect("no error"); let http_client = HttpClient::new(MINT_URL.parse().unwrap(), None); @@ -562,10 +552,13 @@ async fn test_fake_mint_inflated() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wallet - .wait_for_payment(&mint_quote, Duration::from_secs(60)) + let mut payment_streams = wallet.payment_stream(&mint_quote); + + payment_streams + .next() .await - .unwrap(); + .expect("payment") + .expect("no error"); let active_keyset_id = wallet.fetch_active_keyset().await.unwrap().id; @@ -621,10 +614,13 @@ async fn test_fake_mint_multiple_units() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wallet - .wait_for_payment(&mint_quote, Duration::from_secs(60)) + let mut payment_streams = wallet.payment_stream(&mint_quote); + + payment_streams + .next() .await - .unwrap(); + .expect("payment") + .expect("no error"); let active_keyset_id = wallet.fetch_active_keyset().await.unwrap().id; @@ -701,15 +697,13 @@ async fn test_fake_mint_multiple_unit_swap() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wallet - .wait_for_payment(&mint_quote, Duration::from_secs(60)) - .await - .unwrap(); + let mut proof_streams = wallet.proof_stream(mint_quote.clone(), SplitTarget::default(), None); - let proofs = wallet - .mint(&mint_quote.id, SplitTarget::None, None) + let proofs = proof_streams + .next() .await - .unwrap(); + .expect("payment") + .expect("no error"); let wallet_usd = Wallet::new( MINT_URL, @@ -723,15 +717,14 @@ async fn test_fake_mint_multiple_unit_swap() { let mint_quote = wallet_usd.mint_quote(100.into(), None).await.unwrap(); - wallet - .wait_for_payment(&mint_quote, Duration::from_secs(60)) - .await - .unwrap(); + let mut proof_streams = + wallet_usd.proof_stream(mint_quote.clone(), SplitTarget::default(), None); - let usd_proofs = wallet_usd - .mint(&mint_quote.id, SplitTarget::None, None) + let usd_proofs = proof_streams + .next() .await - .unwrap(); + .expect("payment") + .expect("no error"); let active_keyset_id = wallet.fetch_active_keyset().await.unwrap().id; @@ -817,15 +810,13 @@ async fn test_fake_mint_multiple_unit_melt() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wallet - .wait_for_payment(&mint_quote, Duration::from_secs(60)) - .await - .unwrap(); + let mut proof_streams = wallet.proof_stream(mint_quote.clone(), SplitTarget::default(), None); - let proofs = wallet - .mint(&mint_quote.id, SplitTarget::None, None) + let proofs = proof_streams + .next() .await - .unwrap(); + .expect("payment") + .expect("no error"); println!("Minted sat"); @@ -841,15 +832,14 @@ async fn test_fake_mint_multiple_unit_melt() { let mint_quote = wallet_usd.mint_quote(100.into(), None).await.unwrap(); println!("Minted quote usd"); - wallet - .wait_for_payment(&mint_quote, Duration::from_secs(60)) - .await - .unwrap(); + let mut proof_streams = + wallet_usd.proof_stream(mint_quote.clone(), SplitTarget::default(), None); - let usd_proofs = wallet_usd - .mint(&mint_quote.id, SplitTarget::None, None) + let usd_proofs = proof_streams + .next() .await - .unwrap(); + .expect("payment") + .expect("no error"); { let inputs: Proofs = vec![ @@ -937,15 +927,13 @@ async fn test_fake_mint_input_output_mismatch() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wallet - .wait_for_payment(&mint_quote, Duration::from_secs(60)) - .await - .unwrap(); + let mut proof_streams = wallet.proof_stream(mint_quote.clone(), SplitTarget::default(), None); - let proofs = wallet - .mint(&mint_quote.id, SplitTarget::None, None) + let proofs = proof_streams + .next() .await - .unwrap(); + .expect("payment") + .expect("no error"); let wallet_usd = Wallet::new( MINT_URL, @@ -996,15 +984,14 @@ async fn test_fake_mint_swap_inflated() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wallet - .wait_for_payment(&mint_quote, Duration::from_secs(60)) - .await - .unwrap(); + let mut proof_streams = wallet.proof_stream(mint_quote.clone(), SplitTarget::default(), None); - let proofs = wallet - .mint(&mint_quote.id, SplitTarget::None, None) + let proofs = proof_streams + .next() .await - .unwrap(); + .expect("payment") + .expect("no error"); + let active_keyset_id = wallet.fetch_active_keyset().await.unwrap().id; let pre_mint = PreMintSecrets::random(active_keyset_id, 101.into(), &SplitTarget::None).unwrap(); @@ -1041,15 +1028,14 @@ async fn test_fake_mint_swap_spend_after_fail() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wallet - .wait_for_payment(&mint_quote, Duration::from_secs(60)) - .await - .unwrap(); + let mut proof_streams = wallet.proof_stream(mint_quote.clone(), SplitTarget::default(), None); - let proofs = wallet - .mint(&mint_quote.id, SplitTarget::None, None) + let proofs = proof_streams + .next() .await - .unwrap(); + .expect("payment") + .expect("no error"); + let active_keyset_id = wallet.fetch_active_keyset().await.unwrap().id; let pre_mint = @@ -1113,15 +1099,14 @@ async fn test_fake_mint_melt_spend_after_fail() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wallet - .wait_for_payment(&mint_quote, Duration::from_secs(60)) - .await - .unwrap(); + let mut proof_streams = wallet.proof_stream(mint_quote.clone(), SplitTarget::default(), None); - let proofs = wallet - .mint(&mint_quote.id, SplitTarget::None, None) + let proofs = proof_streams + .next() .await - .unwrap(); + .expect("payment") + .expect("no error"); + let active_keyset_id = wallet.fetch_active_keyset().await.unwrap().id; let pre_mint = @@ -1186,15 +1171,13 @@ async fn test_fake_mint_duplicate_proofs_swap() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wallet - .wait_for_payment(&mint_quote, Duration::from_secs(60)) - .await - .unwrap(); + let mut proof_streams = wallet.proof_stream(mint_quote.clone(), SplitTarget::default(), None); - let proofs = wallet - .mint(&mint_quote.id, SplitTarget::None, None) + let proofs = proof_streams + .next() .await - .unwrap(); + .expect("payment") + .expect("no error"); let active_keyset_id = wallet.fetch_active_keyset().await.unwrap().id; @@ -1267,15 +1250,13 @@ async fn test_fake_mint_duplicate_proofs_melt() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - wallet - .wait_for_payment(&mint_quote, Duration::from_secs(60)) - .await - .unwrap(); + let mut proof_streams = wallet.proof_stream(mint_quote.clone(), SplitTarget::default(), None); - let proofs = wallet - .mint(&mint_quote.id, SplitTarget::None, None) + let proofs = proof_streams + .next() .await - .unwrap(); + .expect("payment") + .expect("no error"); let inputs = vec![proofs[0].clone(), proofs[0].clone()]; diff --git a/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs b/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs index 1372c09db..0db6cf258 100644 --- a/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs +++ b/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs @@ -109,15 +109,15 @@ async fn test_happy_mint_melt_round_trip() { .await .unwrap(); - wallet - .wait_for_payment(&mint_quote, Duration::from_secs(60)) - .await - .unwrap(); - let proofs = wallet - .mint(&mint_quote.id, SplitTarget::default(), None) + .wait_and_mint_quote( + mint_quote.clone(), + SplitTarget::default(), + None, + tokio::time::Duration::from_secs(15), + ) .await - .unwrap(); + .expect("payment"); let mint_amount = proofs.total_amount().unwrap(); @@ -231,15 +231,15 @@ async fn test_happy_mint() { .await .unwrap(); - wallet - .wait_for_payment(&mint_quote, Duration::from_secs(60)) - .await - .unwrap(); - let proofs = wallet - .mint(&mint_quote.id, SplitTarget::default(), None) + .wait_and_mint_quote( + mint_quote.clone(), + SplitTarget::default(), + None, + tokio::time::Duration::from_secs(15), + ) .await - .unwrap(); + .expect("payment"); let mint_amount = proofs.total_amount().unwrap(); @@ -279,15 +279,15 @@ async fn test_restore() { .await .unwrap(); - wallet - .wait_for_payment(&mint_quote, Duration::from_secs(60)) - .await - .unwrap(); - - let _mint_amount = wallet - .mint(&mint_quote.id, SplitTarget::default(), None) + let _proofs = wallet + .wait_and_mint_quote( + mint_quote.clone(), + SplitTarget::default(), + None, + tokio::time::Duration::from_secs(15), + ) .await - .unwrap(); + .expect("payment"); assert_eq!(wallet.total_balance().await.unwrap(), 100.into()); @@ -359,15 +359,15 @@ async fn test_fake_melt_change_in_quote() { pay_if_regtest(&get_test_temp_dir(), &bolt11).await.unwrap(); - wallet - .wait_for_payment(&mint_quote, Duration::from_secs(60)) - .await - .unwrap(); - - let _mint_amount = wallet - .mint(&mint_quote.id, SplitTarget::default(), None) + let _proofs = wallet + .wait_and_mint_quote( + mint_quote.clone(), + SplitTarget::default(), + None, + tokio::time::Duration::from_secs(15), + ) .await - .unwrap(); + .expect("payment"); let invoice = create_invoice_for_env(Some(9)).await.unwrap(); @@ -429,15 +429,15 @@ async fn test_pay_invoice_twice() { .await .unwrap(); - wallet - .wait_for_payment(&mint_quote, Duration::from_secs(60)) - .await - .unwrap(); - let proofs = wallet - .mint(&mint_quote.id, SplitTarget::default(), None) + .wait_and_mint_quote( + mint_quote.clone(), + SplitTarget::default(), + None, + tokio::time::Duration::from_secs(15), + ) .await - .unwrap(); + .expect("payment"); let mint_amount = proofs.total_amount().unwrap(); diff --git a/crates/cdk-integration-tests/tests/regtest.rs b/crates/cdk-integration-tests/tests/regtest.rs index 0061423cf..fb66ce882 100644 --- a/crates/cdk-integration-tests/tests/regtest.rs +++ b/crates/cdk-integration-tests/tests/regtest.rs @@ -51,15 +51,15 @@ async fn test_internal_payment() { .await .expect("failed to pay invoice"); - wallet - .wait_for_payment(&mint_quote, Duration::from_secs(60)) + let _proofs = wallet + .wait_and_mint_quote( + mint_quote.clone(), + SplitTarget::default(), + None, + tokio::time::Duration::from_secs(15), + ) .await - .unwrap(); - - let _mint_amount = wallet - .mint(&mint_quote.id, SplitTarget::default(), None) - .await - .unwrap(); + .expect("payment"); assert!(wallet.total_balance().await.unwrap() == 100.into()); @@ -83,15 +83,15 @@ async fn test_internal_payment() { let _melted = wallet.melt(&melt.id).await.unwrap(); - wallet_2 - .wait_for_payment(&mint_quote, Duration::from_secs(60)) + let _proofs = wallet_2 + .wait_and_mint_quote( + mint_quote.clone(), + SplitTarget::default(), + None, + tokio::time::Duration::from_secs(15), + ) .await - .unwrap(); - - let _wallet_2_mint = wallet_2 - .mint(&mint_quote.id, SplitTarget::default(), None) - .await - .unwrap(); + .expect("payment"); // let check_paid = match get_mint_port("0") { // 8085 => { @@ -230,28 +230,32 @@ async fn test_multimint_melt() { .pay_invoice(quote.request.clone()) .await .expect("failed to pay invoice"); - wallet1 - .wait_for_payment("e, Duration::from_secs(60)) - .await - .unwrap(); - wallet1 - .mint("e.id, SplitTarget::default(), None) + + let _proofs = wallet1 + .wait_and_mint_quote( + quote.clone(), + SplitTarget::default(), + None, + tokio::time::Duration::from_secs(15), + ) .await - .unwrap(); + .expect("payment"); let quote = wallet2.mint_quote(mint_amount, None).await.unwrap(); ln_client .pay_invoice(quote.request.clone()) .await .expect("failed to pay invoice"); - wallet2 - .wait_for_payment("e, Duration::from_secs(60)) - .await - .unwrap(); - wallet2 - .mint("e.id, SplitTarget::default(), None) + + let _proofs = wallet2 + .wait_and_mint_quote( + quote.clone(), + SplitTarget::default(), + None, + tokio::time::Duration::from_secs(15), + ) .await - .unwrap(); + .expect("payment"); // Get an invoice let invoice = ln_client.create_invoice(Some(50)).await.unwrap(); @@ -305,10 +309,10 @@ async fn test_cached_mint() { .await .expect("failed to pay invoice"); - wallet - .wait_for_payment("e, Duration::from_secs(60)) + let _proofs = wallet + .wait_for_payment("e, tokio::time::Duration::from_secs(15)) .await - .unwrap(); + .expect("payment"); let active_keyset_id = wallet.fetch_active_keyset().await.unwrap().id; let http_client = HttpClient::new(get_mint_url_from_env().parse().unwrap(), None); diff --git a/crates/cdk-integration-tests/tests/test_fees.rs b/crates/cdk-integration-tests/tests/test_fees.rs index 458c3495c..b6fca7821 100644 --- a/crates/cdk-integration-tests/tests/test_fees.rs +++ b/crates/cdk-integration-tests/tests/test_fees.rs @@ -1,6 +1,5 @@ use std::str::FromStr; use std::sync::Arc; -use std::time::Duration; use bip39::Mnemonic; use cashu::{Bolt11Invoice, ProofsMethods}; @@ -28,23 +27,15 @@ async fn test_swap() { let invoice = Bolt11Invoice::from_str(&mint_quote.request).unwrap(); pay_if_regtest(&get_temp_dir(), &invoice).await.unwrap(); - wallet - .wait_for_payment(&mint_quote, Duration::from_secs(60)) - .await - .unwrap(); - - let _mint_amount = wallet - .mint(&mint_quote.id, SplitTarget::default(), None) - .await - .unwrap(); - - let proofs: Vec = wallet - .get_unspent_proofs() + let proofs = wallet + .wait_and_mint_quote( + mint_quote.clone(), + SplitTarget::default(), + None, + tokio::time::Duration::from_secs(15), + ) .await - .unwrap() - .iter() - .map(|p| p.amount) - .collect(); + .expect("payment"); println!("{:?}", proofs); @@ -96,15 +87,15 @@ async fn test_fake_melt_change_in_quote() { pay_if_regtest(&get_temp_dir(), &bolt11).await.unwrap(); - wallet - .wait_for_payment(&mint_quote, Duration::from_secs(60)) - .await - .unwrap(); - - let _mint_amount = wallet - .mint(&mint_quote.id, SplitTarget::default(), None) + let _proofs = wallet + .wait_and_mint_quote( + mint_quote.clone(), + SplitTarget::default(), + None, + tokio::time::Duration::from_secs(15), + ) .await - .unwrap(); + .expect("payment"); let invoice_amount = 9; diff --git a/crates/cdk/Cargo.toml b/crates/cdk/Cargo.toml index 97d3f45e2..77a5de434 100644 --- a/crates/cdk/Cargo.toml +++ b/crates/cdk/Cargo.toml @@ -50,6 +50,7 @@ sync_wrapper = "0.1.2" bech32 = "0.9.1" arc-swap = "1.7.1" zeroize = "1" +tokio-util.workspace = true [target.'cfg(not(target_arch = "wasm32"))'.dependencies] tokio = { workspace = true, features = [ @@ -102,6 +103,13 @@ required-features = ["wallet", "auth"] name = "bip353" required-features = ["wallet", "bip353"] +[[example]] +name = "mint-token-bolt12-with-stream" +required-features = ["wallet"] +[[example]] +name = "mint-token-bolt12" +required-features = ["wallet"] + [dev-dependencies] rand.workspace = true cdk-sqlite.workspace = true diff --git a/crates/cdk/examples/mint-token-bolt12-with-stream.rs b/crates/cdk/examples/mint-token-bolt12-with-stream.rs new file mode 100644 index 000000000..2e83f5ff7 --- /dev/null +++ b/crates/cdk/examples/mint-token-bolt12-with-stream.rs @@ -0,0 +1,72 @@ +use std::sync::Arc; + +use cdk::error::Error; +use cdk::nuts::nut00::ProofsMethods; +use cdk::nuts::CurrencyUnit; +use cdk::wallet::{SendOptions, Wallet}; +use cdk::{Amount, StreamExt}; +use cdk_sqlite::wallet::memory; +use rand::random; +use tracing_subscriber::EnvFilter; + +#[tokio::main] +async fn main() -> Result<(), Error> { + let default_filter = "debug"; + + let sqlx_filter = "sqlx=warn,hyper_util=warn,reqwest=warn,rustls=warn"; + + let env_filter = EnvFilter::new(format!("{},{}", default_filter, sqlx_filter)); + + // Parse input + tracing_subscriber::fmt().with_env_filter(env_filter).init(); + + // Initialize the memory store for the wallet + let localstore = Arc::new(memory::empty().await?); + + // Generate a random seed for the wallet + let seed = random::<[u8; 64]>(); + + // Define the mint URL and currency unit + let mint_url = "https://fake.thesimplekid.dev"; + let unit = CurrencyUnit::Sat; + let amount = Amount::from(10); + + // Create a new wallet + let wallet = Wallet::new(mint_url, unit, localstore, seed, None)?; + + let quotes = vec![ + wallet.mint_bolt12_quote(None, None).await?, + wallet.mint_bolt12_quote(None, None).await?, + wallet.mint_bolt12_quote(None, None).await?, + ]; + + let mut stream = wallet.mints_proof_stream(quotes, Default::default(), None); + + let stop = stream.get_cancel_token(); + + let mut processed = 0; + + while let Some(proofs) = stream.next().await { + let (mint_quote, proofs) = proofs?; + + // Mint the received amount + let receive_amount = proofs.total_amount()?; + println!("Received {} from mint {}", receive_amount, mint_quote.id); + + // Send a token with the specified amount + let prepared_send = wallet.prepare_send(amount, SendOptions::default()).await?; + let token = prepared_send.confirm(None).await?; + println!("Token:"); + println!("{}", token); + + processed += 1; + + if processed == 3 { + stop.cancel() + } + } + + println!("Stopped the loop after {} quotes being minted", processed); + + Ok(()) +} diff --git a/crates/cdk/examples/mint-token-bolt12.rs b/crates/cdk/examples/mint-token-bolt12.rs new file mode 100644 index 000000000..275d73a64 --- /dev/null +++ b/crates/cdk/examples/mint-token-bolt12.rs @@ -0,0 +1,59 @@ +use std::sync::Arc; +use std::time::Duration; + +use cdk::error::Error; +use cdk::nuts::nut00::ProofsMethods; +use cdk::nuts::CurrencyUnit; +use cdk::wallet::{SendOptions, Wallet}; +use cdk::Amount; +use cdk_sqlite::wallet::memory; +use rand::random; +use tracing_subscriber::EnvFilter; + +#[tokio::main] +async fn main() -> Result<(), Error> { + let default_filter = "debug"; + + let sqlx_filter = "sqlx=warn,hyper_util=warn,reqwest=warn,rustls=warn"; + + let env_filter = EnvFilter::new(format!("{},{}", default_filter, sqlx_filter)); + + // Parse input + tracing_subscriber::fmt().with_env_filter(env_filter).init(); + + // Initialize the memory store for the wallet + let localstore = Arc::new(memory::empty().await?); + + // Generate a random seed for the wallet + let seed = random::<[u8; 64]>(); + + // Define the mint URL and currency unit + let mint_url = "https://fake.thesimplekid.dev"; + let unit = CurrencyUnit::Sat; + let amount = Amount::from(10); + + // Create a new wallet + let wallet = Wallet::new(mint_url, unit, localstore, seed, None)?; + + let quote = wallet.mint_bolt12_quote(None, None).await?; + let proofs = wallet + .wait_and_mint_quote( + quote, + Default::default(), + Default::default(), + Duration::from_secs(10), + ) + .await?; + + // Mint the received amount + let receive_amount = proofs.total_amount()?; + println!("Received {} from mint {}", receive_amount, mint_url); + + // Send a token with the specified amount + let prepared_send = wallet.prepare_send(amount, SendOptions::default()).await?; + let token = prepared_send.confirm(None).await?; + println!("Token:"); + println!("{}", token); + + Ok(()) +} diff --git a/crates/cdk/src/lib.rs b/crates/cdk/src/lib.rs index aea22fccb..ae18ae3ce 100644 --- a/crates/cdk/src/lib.rs +++ b/crates/cdk/src/lib.rs @@ -64,3 +64,7 @@ pub use self::wallet::HttpClient; /// Result #[doc(hidden)] pub type Result> = std::result::Result; + +/// Re-export futures::Stream +#[cfg(any(feature = "wallet", feature = "mint"))] +pub use futures::{Stream, StreamExt}; diff --git a/crates/cdk/src/mint/subscription/manager.rs b/crates/cdk/src/mint/subscription/manager.rs index 96f484e3d..b723974df 100644 --- a/crates/cdk/src/mint/subscription/manager.rs +++ b/crates/cdk/src/mint/subscription/manager.rs @@ -107,8 +107,8 @@ impl PubSubManager { amount_issued: Amount, ) { if let Ok(mut event) = quote.try_into() { - event.amount_paid += amount_paid; - event.amount_issued += amount_issued; + event.amount_paid = amount_paid; + event.amount_issued = amount_issued; self.broadcast(event.into()); } else { diff --git a/crates/cdk/src/wallet/mod.rs b/crates/cdk/src/wallet/mod.rs index 283641890..1bb41c328 100644 --- a/crates/cdk/src/wallet/mod.rs +++ b/crates/cdk/src/wallet/mod.rs @@ -42,11 +42,12 @@ pub mod multi_mint_wallet; mod proofs; mod receive; mod send; +#[cfg(not(target_arch = "wasm32"))] +mod streams; pub mod subscription; mod swap; mod transactions; pub mod util; -mod wait; #[cfg(feature = "auth")] pub use auth::{AuthMintConnector, AuthWallet}; diff --git a/crates/cdk/src/wallet/streams/mod.rs b/crates/cdk/src/wallet/streams/mod.rs new file mode 100644 index 000000000..fda0945e2 --- /dev/null +++ b/crates/cdk/src/wallet/streams/mod.rs @@ -0,0 +1,122 @@ +//! Wallet waiter APIn +use std::future::Future; +use std::pin::Pin; + +use cdk_common::amount::SplitTarget; +use cdk_common::wallet::{MeltQuote, MintQuote}; +use cdk_common::{PaymentMethod, SpendingConditions}; +use payment::PaymentStream; +use proof::{MultipleMintQuoteProofStream, SingleMintQuoteProofStream}; + +use super::{Wallet, WalletSubscription}; + +pub mod payment; +pub mod proof; +mod wait; + +/// Shared type +type RecvFuture<'a, Ret> = Pin + Send + 'a>>; + +#[allow(private_bounds)] +#[allow(clippy::enum_variant_names)] +enum WaitableEvent { + MeltQuote(Vec), + MintQuote(Vec<(String, PaymentMethod)>), +} + +impl From<&[MeltQuote]> for WaitableEvent { + fn from(events: &[MeltQuote]) -> Self { + WaitableEvent::MeltQuote(events.iter().map(|event| event.id.to_owned()).collect()) + } +} + +impl From<&MeltQuote> for WaitableEvent { + fn from(event: &MeltQuote) -> Self { + WaitableEvent::MeltQuote(vec![event.id.to_owned()]) + } +} + +impl From<&[MintQuote]> for WaitableEvent { + fn from(events: &[MintQuote]) -> Self { + WaitableEvent::MintQuote( + events + .iter() + .map(|event| (event.id.to_owned(), event.payment_method.clone())) + .collect(), + ) + } +} + +impl From<&MintQuote> for WaitableEvent { + fn from(event: &MintQuote) -> Self { + WaitableEvent::MintQuote(vec![(event.id.to_owned(), event.payment_method.clone())]) + } +} + +impl WaitableEvent { + fn into_subscription(self) -> Vec { + match self { + WaitableEvent::MeltQuote(quotes) => { + vec![WalletSubscription::Bolt11MeltQuoteState(quotes)] + } + WaitableEvent::MintQuote(quotes) => { + let (bolt11, bolt12) = quotes.into_iter().fold( + (Vec::new(), Vec::new()), + |mut acc, (quote_id, payment_method)| { + match payment_method { + PaymentMethod::Bolt11 => acc.0.push(quote_id), + PaymentMethod::Bolt12 => acc.1.push(quote_id), + PaymentMethod::Custom(_) => acc.0.push(quote_id), + } + acc + }, + ); + + let mut subscriptions = Vec::new(); + + if !bolt11.is_empty() { + subscriptions.push(WalletSubscription::Bolt11MintQuoteState(bolt11)); + } + + if !bolt12.is_empty() { + subscriptions.push(WalletSubscription::Bolt12MintQuoteState(bolt12)); + } + + subscriptions + } + } + } +} + +impl Wallet { + /// Streams all proofs from a single mint quote + #[inline(always)] + pub fn proof_stream( + &self, + quote: MintQuote, + amount_split_target: SplitTarget, + spending_conditions: Option, + ) -> SingleMintQuoteProofStream<'_> { + SingleMintQuoteProofStream::new(self, quote, amount_split_target, spending_conditions) + } + + /// Streams all new proofs for a set of mints + #[inline(always)] + pub fn mints_proof_stream( + &self, + quotes: Vec, + amount_split_target: SplitTarget, + spending_conditions: Option, + ) -> MultipleMintQuoteProofStream<'_> { + MultipleMintQuoteProofStream::new(self, quotes, amount_split_target, spending_conditions) + } + + /// Returns a BoxFuture that will wait for payment on the given event with a timeout check + #[allow(private_bounds)] + pub fn payment_stream(&self, events: T) -> PaymentStream<'_> + where + T: Into, + { + PaymentStream::new(self, events.into().into_subscription()) + } +} diff --git a/crates/cdk/src/wallet/streams/payment.rs b/crates/cdk/src/wallet/streams/payment.rs new file mode 100644 index 000000000..8139570ae --- /dev/null +++ b/crates/cdk/src/wallet/streams/payment.rs @@ -0,0 +1,205 @@ +//! Payment Stream +//! +//! This future Stream will wait events for a Mint Quote be paid. If it is for a Bolt12 it will not stop +//! but it will eventually error on a Timeout. +//! +//! Bolt11 will emit a single event. +use std::task::Poll; + +use cdk_common::{Amount, Error, MeltQuoteState, MintQuoteState, NotificationPayload}; +use futures::future::join_all; +use futures::stream::FuturesUnordered; +use futures::{FutureExt, Stream, StreamExt}; +use tokio_util::sync::CancellationToken; + +use super::RecvFuture; +use crate::wallet::subscription::ActiveSubscription; +use crate::{Wallet, WalletSubscription}; + +type SubscribeReceived = (Option>, Vec); +type PaymentValue = (String, Option); + +/// PaymentWaiter +pub struct PaymentStream<'a> { + wallet: Option<(&'a Wallet, Vec)>, + is_finalized: bool, + active_subscription: Option>, + + cancel_token: CancellationToken, + + // Future events + subscriber_future: Option>>, + subscription_receiver_future: Option>, + cancellation_future: Option>, +} + +impl<'a> PaymentStream<'a> { + /// Creates a new instance of the + pub fn new(wallet: &'a Wallet, filters: Vec) -> Self { + Self { + wallet: Some((wallet, filters)), + is_finalized: false, + active_subscription: None, + cancel_token: Default::default(), + subscriber_future: None, + subscription_receiver_future: None, + cancellation_future: None, + } + } + + /// Get cancellation token + pub fn get_cancel_token(&self) -> CancellationToken { + self.cancel_token.clone() + } + + /// Creating a wallet subscription is an async event, this may change in the future, but for now, + /// creating a new Subscription should be polled, as any other async event. This function will + /// return None if the subscription is already active, Some(()) otherwise + fn poll_init_subscription(&mut self, cx: &mut std::task::Context<'_>) -> Option<()> { + if let Some((wallet, filters)) = self.wallet.take() { + self.subscriber_future = Some(Box::pin(async move { + join_all(filters.into_iter().map(|w| wallet.subscribe(w))).await + })); + } + + let mut subscriber_future = self.subscriber_future.take()?; + + match subscriber_future.poll_unpin(cx) { + Poll::Pending => { + self.subscriber_future = Some(subscriber_future); + Some(()) + } + Poll::Ready(active_subscription) => { + self.active_subscription = Some(active_subscription); + None + } + } + } + + /// Checks if the stream has been externally cancelled + fn poll_cancel(&mut self, cx: &mut std::task::Context<'_>) -> bool { + let mut cancellation_future = self.cancellation_future.take().unwrap_or_else(|| { + let cancel_token = self.cancel_token.clone(); + Box::pin(async move { cancel_token.cancelled().await }) + }); + + if cancellation_future.poll_unpin(cx).is_ready() { + self.subscription_receiver_future = None; + true + } else { + self.cancellation_future = Some(cancellation_future); + false + } + } + + /// Polls the subscription for any new event + fn poll_event( + &mut self, + cx: &mut std::task::Context<'_>, + ) -> Poll>> { + let (subscription_receiver_future, active_subscription) = ( + self.subscription_receiver_future.take(), + self.active_subscription.take(), + ); + + if subscription_receiver_future.is_none() && active_subscription.is_none() { + // Unexpected state, we should have an in-flight future or the active_subscription to + // create the future to read an event + return Poll::Ready(Some(Err(Error::Internal))); + } + + let mut receiver = subscription_receiver_future.unwrap_or_else(|| { + let mut subscription_receiver = + active_subscription.expect("active subscription object"); + + Box::pin(async move { + let mut futures: FuturesUnordered<_> = subscription_receiver + .iter_mut() + .map(|sub| sub.recv()) + .collect(); + + if let Some(Some(winner)) = futures.next().await { + drop(futures); + return (Some(winner), subscription_receiver); + } + + drop(futures); + (None, subscription_receiver) + }) + }); + + match receiver.poll_unpin(cx) { + Poll::Pending => { + self.subscription_receiver_future = Some(receiver); + Poll::Pending + } + Poll::Ready((notification, subscription)) => { + tracing::debug!("Receive payment notification {:?}", notification); + // This future is now fulfilled, put the active_subscription again back to object. Next time next().await is called, + // the future will be created in subscription_receiver_future. + self.active_subscription = Some(subscription); + self.cancellation_future = None; // resets timeout + match notification { + None => { + self.is_finalized = true; + Poll::Ready(None) + } + Some(info) => { + match info { + NotificationPayload::MintQuoteBolt11Response(info) => { + if info.state == MintQuoteState::Paid { + self.is_finalized = true; + return Poll::Ready(Some(Ok((info.quote, None)))); + } + } + NotificationPayload::MintQuoteBolt12Response(info) => { + let to_be_issued = info.amount_paid - info.amount_issued; + if to_be_issued > Amount::ZERO { + return Poll::Ready(Some(Ok((info.quote, Some(to_be_issued))))); + } + } + NotificationPayload::MeltQuoteBolt11Response(info) => { + if info.state == MeltQuoteState::Paid { + self.is_finalized = true; + return Poll::Ready(Some(Ok((info.quote, None)))); + } + } + _ => {} + } + + // We got an event but it is not what was expected, we need to call `recv` + // again, and to copy-paste this is a recursive call that should be resolved + // to a Poll::Pending *but* will trigger the future execution + self.poll_event(cx) + } + } + } + } + } +} + +impl Stream for PaymentStream<'_> { + type Item = Result; + + fn poll_next( + self: std::pin::Pin<&mut Self>, + cx: &mut std::task::Context<'_>, + ) -> std::task::Poll> { + let this = self.get_mut(); + + if this.is_finalized { + // end of stream + return Poll::Ready(None); + } + + if this.poll_cancel(cx) { + return Poll::Ready(None); + } + + if this.poll_init_subscription(cx).is_some() { + return Poll::Pending; + } + + this.poll_event(cx) + } +} diff --git a/crates/cdk/src/wallet/streams/proof.rs b/crates/cdk/src/wallet/streams/proof.rs new file mode 100644 index 000000000..a95472287 --- /dev/null +++ b/crates/cdk/src/wallet/streams/proof.rs @@ -0,0 +1,185 @@ +//! Mint Stream +//! +//! This will mint after a mint quote has been paid. If the quote is for a Bolt12 it will keep minting until a timeout is reached. +//! +//! Bolt11 will mint once + +use std::collections::HashMap; +use std::task::Poll; + +use cdk_common::amount::SplitTarget; +use cdk_common::wallet::MintQuote; +use cdk_common::{Error, PaymentMethod, Proofs, SpendingConditions}; +use futures::{FutureExt, Stream, StreamExt}; +use tokio_util::sync::CancellationToken; + +use super::payment::PaymentStream; +use super::{RecvFuture, WaitableEvent}; +use crate::Wallet; + +/// Proofs for many mint quotes, as they are minted, in streams +pub struct MultipleMintQuoteProofStream<'a> { + payment_stream: PaymentStream<'a>, + wallet: &'a Wallet, + quotes: HashMap, + amount_split_target: SplitTarget, + spending_conditions: Option, + minting_future: Option>>, +} + +impl<'a> MultipleMintQuoteProofStream<'a> { + /// Create a new Stream + pub fn new( + wallet: &'a Wallet, + quotes: Vec, + amount_split_target: SplitTarget, + spending_conditions: Option, + ) -> Self { + let filter: WaitableEvent = quotes.as_slice().into(); + + Self { + payment_stream: PaymentStream::new(wallet, filter.into_subscription()), + wallet, + amount_split_target, + spending_conditions, + quotes: quotes + .into_iter() + .map(|mint_quote| (mint_quote.id.clone(), mint_quote)) + .collect(), + minting_future: None, + } + } + + /// Get cancellation token + pub fn get_cancel_token(&self) -> CancellationToken { + self.payment_stream.get_cancel_token() + } +} + +impl Stream for MultipleMintQuoteProofStream<'_> { + type Item = Result<(MintQuote, Proofs), Error>; + + fn poll_next( + self: std::pin::Pin<&mut Self>, + cx: &mut std::task::Context<'_>, + ) -> std::task::Poll> { + let this = self.get_mut(); + + if let Some(mut minting_future) = this.minting_future.take() { + return match minting_future.poll_unpin(cx) { + Poll::Pending => { + this.minting_future = Some(minting_future); + Poll::Pending + } + Poll::Ready(proofs) => Poll::Ready(Some(proofs)), + }; + } + + match this.payment_stream.poll_next_unpin(cx) { + Poll::Pending => Poll::Pending, + Poll::Ready(result) => match result { + None => Poll::Ready(None), + Some(result) => { + let (quote_id, amount) = match result { + Err(err) => { + tracing::error!( + "Error while waiting for payment for {:?}", + this.quotes.keys().collect::>() + ); + return Poll::Ready(Some(Err(err))); + } + Ok(amount) => amount, + }; + + let mint_quote = if let Some(quote) = this.quotes.get("e_id) { + quote.clone() + } else { + tracing::error!("Cannot find mint_quote {} internally", quote_id); + return Poll::Ready(Some(Err(Error::UnknownQuote))); + }; + + let amount_split_target = this.amount_split_target.clone(); + let spending_conditions = this.spending_conditions.clone(); + let wallet = this.wallet; + + tracing::debug!( + "Received payment ({:?}) notification for {}. Minting...", + amount, + mint_quote.id + ); + + let mut minting_future = Box::pin(async move { + match mint_quote.payment_method { + PaymentMethod::Bolt11 => wallet + .mint(&mint_quote.id, amount_split_target, spending_conditions) + .await + .map(|proofs| (mint_quote, proofs)), + PaymentMethod::Bolt12 => wallet + .mint_bolt12( + &mint_quote.id, + amount, + amount_split_target, + spending_conditions, + ) + .await + .map(|proofs| (mint_quote, proofs)), + _ => Err(Error::UnsupportedPaymentMethod), + } + }); + + match minting_future.poll_unpin(cx) { + Poll::Pending => { + this.minting_future = Some(minting_future); + Poll::Pending + } + Poll::Ready(result) => Poll::Ready(Some(result)), + } + } + }, + } + } +} + +/// Proofs for a single mint quote +pub struct SingleMintQuoteProofStream<'a>(MultipleMintQuoteProofStream<'a>); + +impl<'a> SingleMintQuoteProofStream<'a> { + /// Create a new Stream + pub fn new( + wallet: &'a Wallet, + quote: MintQuote, + amount_split_target: SplitTarget, + spending_conditions: Option, + ) -> Self { + Self(MultipleMintQuoteProofStream::new( + wallet, + vec![quote], + amount_split_target, + spending_conditions, + )) + } + + /// Get cancellation token + pub fn get_cancel_token(&self) -> CancellationToken { + self.0.payment_stream.get_cancel_token() + } +} + +impl Stream for SingleMintQuoteProofStream<'_> { + type Item = Result; + + fn poll_next( + self: std::pin::Pin<&mut Self>, + cx: &mut std::task::Context<'_>, + ) -> std::task::Poll> { + let this = self.get_mut(); + match this.0.poll_next_unpin(cx) { + Poll::Pending => Poll::Pending, + Poll::Ready(result) => match result { + None => Poll::Ready(None), + Some(Err(err)) => Poll::Ready(Some(Err(err))), + Some(Ok((_, proofs))) => Poll::Ready(Some(Ok(proofs))), + }, + } + } +} diff --git a/crates/cdk/src/wallet/streams/wait.rs b/crates/cdk/src/wallet/streams/wait.rs new file mode 100644 index 000000000..61f7e332e --- /dev/null +++ b/crates/cdk/src/wallet/streams/wait.rs @@ -0,0 +1,50 @@ +use cdk_common::amount::SplitTarget; +use cdk_common::wallet::MintQuote; +use cdk_common::{Amount, Error, Proofs, SpendingConditions}; +use futures::future::BoxFuture; +use futures::StreamExt; +use tokio::time::{timeout, Duration}; + +use super::Wallet; + +impl Wallet { + #[inline(always)] + /// Mints a mint quote once it is paid + pub async fn wait_and_mint_quote( + &self, + quote: MintQuote, + amount_split_target: SplitTarget, + spending_conditions: Option, + timeout_duration: Duration, + ) -> Result { + let mut stream = self.proof_stream(quote, amount_split_target, spending_conditions); + + timeout(timeout_duration, async move { + stream.next().await.ok_or(Error::Internal)? + }) + .await + .map_err(|_| Error::Timeout)? + } + + /// Returns a BoxFuture that will wait for payment on the given event with a timeout check + #[allow(private_bounds)] + pub fn wait_for_payment( + &self, + event: &MintQuote, + timeout_duration: Duration, + ) -> BoxFuture<'_, Result, Error>> { + let mut stream = self.payment_stream(event); + + Box::pin(async move { + timeout(timeout_duration, async { + stream + .next() + .await + .ok_or(Error::Internal)? + .map(|(_quote, amount)| amount) + }) + .await + .map_err(|_| Error::Timeout)? + }) + } +} diff --git a/crates/cdk/src/wallet/wait.rs b/crates/cdk/src/wallet/wait.rs deleted file mode 100644 index f5d041737..000000000 --- a/crates/cdk/src/wallet/wait.rs +++ /dev/null @@ -1,119 +0,0 @@ -use cdk_common::amount::SplitTarget; -use cdk_common::wallet::{MeltQuote, MintQuote}; -use cdk_common::{ - Amount, Error, MeltQuoteState, MintQuoteState, NotificationPayload, PaymentMethod, Proofs, - SpendingConditions, -}; -use futures::future::BoxFuture; -use tokio::time::{timeout, Duration}; - -use super::{Wallet, WalletSubscription}; - -#[allow(private_bounds)] -#[allow(clippy::enum_variant_names)] -enum WaitableEvent { - MeltQuote(String), - MintQuote(String), - Bolt12MintQuote(String), -} - -impl From<&MeltQuote> for WaitableEvent { - fn from(event: &MeltQuote) -> Self { - WaitableEvent::MeltQuote(event.id.to_owned()) - } -} - -impl From<&MintQuote> for WaitableEvent { - fn from(event: &MintQuote) -> Self { - match event.payment_method { - PaymentMethod::Bolt11 => WaitableEvent::MintQuote(event.id.to_owned()), - PaymentMethod::Bolt12 => WaitableEvent::Bolt12MintQuote(event.id.to_owned()), - PaymentMethod::Custom(_) => WaitableEvent::MintQuote(event.id.to_owned()), - } - } -} - -impl From for WalletSubscription { - fn from(val: WaitableEvent) -> Self { - match val { - WaitableEvent::MeltQuote(quote_id) => { - WalletSubscription::Bolt11MeltQuoteState(vec![quote_id]) - } - WaitableEvent::MintQuote(quote_id) => { - WalletSubscription::Bolt11MintQuoteState(vec![quote_id]) - } - WaitableEvent::Bolt12MintQuote(quote_id) => { - WalletSubscription::Bolt12MintQuoteState(vec![quote_id]) - } - } - } -} - -impl Wallet { - #[inline(always)] - /// Mints a mint quote once it is paid - pub async fn wait_and_mint_quote( - &self, - quote: MintQuote, - amount_split_target: SplitTarget, - spending_conditions: Option, - timeout_duration: Duration, - ) -> Result { - let amount = self.wait_for_payment("e, timeout_duration).await?; - - tracing::debug!("Received payment notification for {}. Minting...", quote.id); - - match quote.payment_method { - PaymentMethod::Bolt11 => { - self.mint("e.id, amount_split_target, spending_conditions) - .await - } - PaymentMethod::Bolt12 => { - self.mint_bolt12("e.id, amount, amount_split_target, spending_conditions) - .await - } - _ => Err(Error::UnsupportedPaymentMethod), - } - } - - /// Returns a BoxFuture that will wait for payment on the given event with a timeout check - #[allow(private_bounds)] - pub fn wait_for_payment( - &self, - event: T, - timeout_duration: Duration, - ) -> BoxFuture<'_, Result, Error>> - where - T: Into, - { - let subs = self.subscribe::(event.into().into()); - - Box::pin(async move { - timeout(timeout_duration, async { - let mut subscription = subs.await; - loop { - match subscription.recv().await.ok_or(Error::Internal)? { - NotificationPayload::MintQuoteBolt11Response(info) => { - if info.state == MintQuoteState::Paid { - return Ok(None); - } - } - NotificationPayload::MintQuoteBolt12Response(info) => { - if info.amount_paid - info.amount_issued > Amount::ZERO { - return Ok(Some(info.amount_paid - info.amount_issued)); - } - } - NotificationPayload::MeltQuoteBolt11Response(info) => { - if info.state == MeltQuoteState::Paid { - return Ok(None); - } - } - _ => {} - } - } - }) - .await - .map_err(|_| Error::Timeout)? - }) - } -} From 44cef59fe567dff2302f63385535444f740adf07 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Tue, 26 Aug 2025 13:51:08 +0100 Subject: [PATCH 108/321] chore: bump 0.12 (#997) --- CHANGELOG.md | 29 ++++++++++++++++++++++++++++- Cargo.toml | 36 ++++++++++++++++++------------------ 2 files changed, 46 insertions(+), 19 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f36bbc11d..74ce7a948 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,12 @@ ## [Unreleased] +## [0.12.0](https://github.com/cashubtc/cdk/releases/tag/v0.12.0) + +### Summary + +Version 0.12.0 delivers end-to-end BOLT12 offers and payments, adds BIP‑353 address resolution for BOLT12 payments, and introduces cdk-ldk-node, an integrated Lightning backend that lets a single binary run both a Cashu mint and a Lightning node with full BOLT11 and BOLT12 support. It also adds a local, admin-focused web UI for cdk-ldk-node with dashboards for channels, invoices and offers, payments, and on-chain activity. On the data layer, the release expands storage with PostgreSQL via the new cdk-postgres crate and accelerates the shared SQL stack (cdk-sql-common) with statement caching and structured, namespaced/global migrations. Operationally, the mint now exposes explicit start and stop lifecycle methods, enabling graceful startup and shutdown of background services. Wallet keyset management has been clarified with renamed APIs that separate local storage from network fetches—making load_mint_keysets the primary entry point for token operations—and the MSRV is updated to 1.85.0. + ### Added - dev: Goose recipes for changelog and commit message generation with Just commands ([thesimplekid]). - cashu: `KeySetInfos` type alias and `KeySetInfosMethods` trait for filtering keysets ([thesimplekid]). @@ -21,8 +27,15 @@ - cdk-redb: Database migration to increment keyset counters by 1 for existing keysets with counter > 0 ([thesimplekid]). - cdk-sql-common: Database migration to increment keyset counters by 1 for existing keysets with counter > 0 ([thesimplekid]). - cdk-ldk-node: New Lightning backend implementation using LDK Node for improved Lightning Network functionality ([thesimplekid]). +- cdk-ldk-node: Local web management UI (dashboard, channels, invoices/offers, payments, on‑chain). Intended for localhost/admin use only; do not expose publicly ([thesimplekid]/[erik]). - cdk-common: Added `start()` and `stop()` methods to `MintPayment` trait for payment processor lifecycle management ([thesimplekid]). - cdk-mintd: Added LDK Node backend support with comprehensive configuration options ([thesimplekid]). +- cdk-postgres: Postgres Database for mint and wallet ([crodas]). +- cdk: BOLT12 mint quote WebSocket subscriptions (NUT-17) ([crodas]). +- cdk: Future streams for payments and minting proofs ([crodas]). +- cdk: Log-to-file support ([thesimplekid]). +- cdk(wallet): BIP-353 support ([thesimplekid]). +- security: Zeroize secrets on drop ([vnprc]). ### Changed - cdk-common: Modified `Database::get_keyset_counter` trait method to return `u32` instead of `Option` for simpler keyset counter handling ([thesimplekid]). @@ -38,6 +51,11 @@ - cdk: Improved mint shutdown to gracefully stop payment processors alongside background services ([thesimplekid]). - cdk-mintd: Updated to use new mint lifecycle methods for improved service management ([thesimplekid]). - cdk-integration-tests: Updated test utilities to use new mint lifecycle management ([thesimplekid]). +- cdk: HTTP retry only on transport errors ([crodas]). +- cdk-lnbits: Migrate to LNBits v1 websocket API and remove pre-v1 code paths ([thesimplekid]). +- cdk-cln: Use millisatoshis (msats) for amounts ([thesimplekid]). +- cdk: NUT-20 support toggle in mint builder configuration ([thesimplekid]). +- cashu/cdk: New secret derivation per updated spec ([lollerfirst]). - cdk-sqlite: Introduce `cdk-sql-common` crate for shared SQL storage codebase ([crodas]). - cdk-sqlite: Rename `still_active` to `stale` for better clarity ([crodas]). - cdk-integration-tests: Refactored regtest setup to use Rust binaries instead of shell scripts ([thesimplekid]). @@ -46,14 +64,22 @@ - cdk-integration-tests: Updated integration tests to use proper temp directory management ([thesimplekid]). - cdk-integration-tests: Simplified regtest shell scripts to use new binaries ([thesimplekid]). - crates/cdk-mintd: Moved mintd library functions to separate module for better organization and testability ([thesimplekid]). +- dev/docker: Switch base image to Debian Trixie ([thesimplekid]). - Updated MSRV to 1.85.0 ([thesimplekid]). - dev: Simplified Nix flake configuration by removing specific dependency version constraints from MSRV shell hook ([thesimplekid]). ### Fixed - cashu: Fixed CurrencyUnit custom units preserving original case instead of being converted to uppercase ([thesimplekid]). +- cdk: Fix P2PK spending-condition validation and requirements ([thesimplekid]). +- cdk: Fixed BOLT12 missing payments notifications ([crodas]). +- cdk-axum/mint: Fix BOLT12 WebSocket behavior on mint ([thesimplekid]). +- cdk-lnbits: Fix payment check and unit handling ([thesimplekid]). - cdk-sqlite: Fix `get_mint_quote_by_request_lookup_id` function synchronization ([crodas]). -- cdk-common: Fix TransactionId::from_hex to check bytes length before copy to avoid panic ([codingpeanut157]). +- cdk-sqlite: Reduce mmap_size to 5 MiB to avoid resource issues ([thesimplekid]). +- cdk: Remove unwrap in startup checks ([thesimplekid]). +- cdk: Allow paid and issued BOLT12 quotes to settle internally ([gudnuf]). - cdk: Include change in melt quote state updates ([thesimplekid]). +- cdk-mintd/axum: Pass auth config from mintd through to axum correctly ([thesimplekid]). ### Migration - cdk-sql-common: Improve migrations with namespaced and global migrations support ([crodas]). @@ -482,3 +508,4 @@ Additionally, this release introduces a Mint binary cdk-mintd that uses the cdk- [asmo]: https://github.com/asmogo [gudnuf]: https://github.com/gudnuf [codingpeanut157]: https://github.com/codingpeanut157 +[erik]: https://github.com/swedishfrenchpress diff --git a/Cargo.toml b/Cargo.toml index 3049fe220..e2142eb0c 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -33,7 +33,7 @@ rust-version = "1.85.0" license = "MIT" homepage = "https://github.com/cashubtc/cdk" repository = "https://github.com/cashubtc/cdk.git" -version = "0.11.0" +version = "0.12.0" readme = "README.md" [workspace.dependencies] @@ -43,23 +43,23 @@ axum = { version = "0.8.1", features = ["ws"] } bitcoin = { version = "0.32.2", features = ["base64", "serde", "rand", "rand-std"] } bip39 = { version = "2.0", features = ["rand"] } jsonwebtoken = "9.2.0" -cashu = { path = "./crates/cashu", version = "=0.11.0" } -cdk = { path = "./crates/cdk", default-features = false, version = "=0.11.0" } -cdk-common = { path = "./crates/cdk-common", default-features = false, version = "=0.11.0" } -cdk-axum = { path = "./crates/cdk-axum", default-features = false, version = "=0.11.0" } -cdk-cln = { path = "./crates/cdk-cln", version = "=0.11.0" } -cdk-lnbits = { path = "./crates/cdk-lnbits", version = "=0.11.0" } -cdk-lnd = { path = "./crates/cdk-lnd", version = "=0.11.0" } -cdk-ldk-node = { path = "./crates/cdk-ldk-node", version = "=0.11.0" } -cdk-fake-wallet = { path = "./crates/cdk-fake-wallet", version = "=0.11.0" } -cdk-payment-processor = { path = "./crates/cdk-payment-processor", default-features = true, version = "=0.11.0" } -cdk-mint-rpc = { path = "./crates/cdk-mint-rpc", version = "=0.11.0" } -cdk-redb = { path = "./crates/cdk-redb", default-features = true, version = "=0.11.0" } -cdk-sql-common = { path = "./crates/cdk-sql-common", default-features = true, version = "=0.11.0" } -cdk-sqlite = { path = "./crates/cdk-sqlite", default-features = true, version = "=0.11.0" } -cdk-postgres = { path = "./crates/cdk-postgres", default-features = true, version = "=0.11.0" } -cdk-signatory = { path = "./crates/cdk-signatory", version = "=0.11.0", default-features = false } -cdk-mintd = { path = "./crates/cdk-mintd", version = "=0.11.0", default-features = false } +cashu = { path = "./crates/cashu", version = "=0.12.0" } +cdk = { path = "./crates/cdk", default-features = false, version = "=0.12.0" } +cdk-common = { path = "./crates/cdk-common", default-features = false, version = "=0.12.0" } +cdk-axum = { path = "./crates/cdk-axum", default-features = false, version = "=0.12.0" } +cdk-cln = { path = "./crates/cdk-cln", version = "=0.12.0" } +cdk-lnbits = { path = "./crates/cdk-lnbits", version = "=0.12.0" } +cdk-lnd = { path = "./crates/cdk-lnd", version = "=0.12.0" } +cdk-ldk-node = { path = "./crates/cdk-ldk-node", version = "=0.12.0" } +cdk-fake-wallet = { path = "./crates/cdk-fake-wallet", version = "=0.12.0" } +cdk-payment-processor = { path = "./crates/cdk-payment-processor", default-features = true, version = "=0.12.0" } +cdk-mint-rpc = { path = "./crates/cdk-mint-rpc", version = "=0.12.0" } +cdk-redb = { path = "./crates/cdk-redb", default-features = true, version = "=0.12.0" } +cdk-sql-common = { path = "./crates/cdk-sql-common", default-features = true, version = "=0.12.0" } +cdk-sqlite = { path = "./crates/cdk-sqlite", default-features = true, version = "=0.12.0" } +cdk-postgres = { path = "./crates/cdk-postgres", default-features = true, version = "=0.12.0" } +cdk-signatory = { path = "./crates/cdk-signatory", version = "=0.12.0", default-features = false } +cdk-mintd = { path = "./crates/cdk-mintd", version = "=0.12.0", default-features = false } clap = { version = "4.5.31", features = ["derive"] } ciborium = { version = "0.2.2", default-features = false, features = ["std"] } cbor-diag = "0.1.12" From cb29e74e3930326cc13b6e2c0a2b647ba8fb9930 Mon Sep 17 00:00:00 2001 From: asmo Date: Tue, 26 Aug 2025 21:27:25 +0200 Subject: [PATCH 109/321] feat: add TLS support for PostgreSQL connections with configurable SSL modes --- crates/cdk-postgres/Cargo.toml | 1 + crates/cdk-postgres/src/lib.rs | 48 +++++++++++++++++++++++++++++++--- 2 files changed, 46 insertions(+), 3 deletions(-) diff --git a/crates/cdk-postgres/Cargo.toml b/crates/cdk-postgres/Cargo.toml index cadcf2bd4..5b5b4af27 100644 --- a/crates/cdk-postgres/Cargo.toml +++ b/crates/cdk-postgres/Cargo.toml @@ -32,4 +32,5 @@ uuid.workspace = true tokio-postgres = "0.7.13" futures-util = "0.3.31" postgres-native-tls = "0.5.1" +native-tls = "0.2" once_cell.workspace = true diff --git a/crates/cdk-postgres/src/lib.rs b/crates/cdk-postgres/src/lib.rs index 408e60ecb..e32a0f359 100644 --- a/crates/cdk-postgres/src/lib.rs +++ b/crates/cdk-postgres/src/lib.rs @@ -10,6 +10,9 @@ use cdk_sql_common::pool::{DatabaseConfig, DatabasePool}; use cdk_sql_common::stmt::{Column, Statement}; use cdk_sql_common::{SQLMintDatabase, SQLWalletDatabase}; use db::{pg_batch, pg_execute, pg_fetch_all, pg_fetch_one, pg_pluck}; +use native_tls; +use native_tls::TlsConnector; +use postgres_native_tls::MakeTlsConnector; use tokio::sync::{Mutex, Notify}; use tokio::time::timeout; use tokio_postgres::{connect, Client, Error as PgError, NoTls}; @@ -25,6 +28,11 @@ pub enum SslMode { NoTls(NoTls), NativeTls(postgres_native_tls::MakeTlsConnector), } +const SSLMODE_VERIFY_FULL: &str = "sslmode=verify-full"; +const SSLMODE_VERIFY_CA: &str = "sslmode=verify-ca"; +const SSLMODE_PREFER: &str = "sslmode=prefer"; +const SSLMODE_ALLOW: &str = "sslmode=allow"; +const SSLMODE_REQUIRE: &str = "sslmode=require"; impl Default for SslMode { fn default() -> Self { @@ -61,10 +69,44 @@ impl DatabaseConfig for PgConfig { } impl From<&str> for PgConfig { - fn from(value: &str) -> Self { + fn from(conn_str: &str) -> Self { + fn build_tls(accept_invalid_certs: bool, accept_invalid_hostnames: bool) -> SslMode { + let mut builder = TlsConnector::builder(); + if accept_invalid_certs { + builder.danger_accept_invalid_certs(true); + } + if accept_invalid_hostnames { + builder.danger_accept_invalid_hostnames(true); + } + + match builder.build() { + Ok(connector) => { + let make_tls_connector = MakeTlsConnector::new(connector); + SslMode::NativeTls(make_tls_connector) + } + Err(_) => SslMode::NoTls(NoTls {}), + } + } + + let tls = if conn_str.contains(SSLMODE_VERIFY_FULL) { + // Strict TLS: valid certs and hostnames required + build_tls(false, false) + } else if conn_str.contains(SSLMODE_VERIFY_CA) { + // Verify CA, but allow invalid hostnames + build_tls(false, true) + } else if conn_str.contains(SSLMODE_PREFER) + || conn_str.contains(SSLMODE_ALLOW) + || conn_str.contains(SSLMODE_REQUIRE) + { + // Lenient TLS for preferred/allow/require: accept invalid certs and hostnames + build_tls(true, true) + } else { + SslMode::NoTls(NoTls {}) + }; + PgConfig { - url: value.to_owned(), - tls: Default::default(), + url: conn_str.to_owned(), + tls, } } } From 6454a33509c1725771812d4ab0f3579f57298b1b Mon Sep 17 00:00:00 2001 From: asmo Date: Wed, 27 Aug 2025 15:15:16 +0200 Subject: [PATCH 110/321] chore: remove unused `native_tls` import from `cdk-postgres` --- crates/cdk-postgres/src/lib.rs | 1 - 1 file changed, 1 deletion(-) diff --git a/crates/cdk-postgres/src/lib.rs b/crates/cdk-postgres/src/lib.rs index e32a0f359..579b966f8 100644 --- a/crates/cdk-postgres/src/lib.rs +++ b/crates/cdk-postgres/src/lib.rs @@ -10,7 +10,6 @@ use cdk_sql_common::pool::{DatabaseConfig, DatabasePool}; use cdk_sql_common::stmt::{Column, Statement}; use cdk_sql_common::{SQLMintDatabase, SQLWalletDatabase}; use db::{pg_batch, pg_execute, pg_fetch_all, pg_fetch_one, pg_pluck}; -use native_tls; use native_tls::TlsConnector; use postgres_native_tls::MakeTlsConnector; use tokio::sync::{Mutex, Notify}; From 971957b839cca1759734fcff55bab9ec06a04967 Mon Sep 17 00:00:00 2001 From: codingpeanut157 Date: Wed, 27 Aug 2025 16:21:22 +0200 Subject: [PATCH 111/321] replace transports: Option> with just Vec (#999) with a few serde directive we can get the same behaviour we had with Option> but only using Vec No need to change protocol specification --- .../cashu/src/nuts/nut18/payment_request.rs | 28 +++++++------------ .../src/sub_commands/create_request.rs | 14 +++++----- .../cdk-cli/src/sub_commands/pay_request.rs | 8 +++--- 3 files changed, 21 insertions(+), 29 deletions(-) diff --git a/crates/cashu/src/nuts/nut18/payment_request.rs b/crates/cashu/src/nuts/nut18/payment_request.rs index 65d90f808..73597012d 100644 --- a/crates/cashu/src/nuts/nut18/payment_request.rs +++ b/crates/cashu/src/nuts/nut18/payment_request.rs @@ -3,7 +3,6 @@ //! use std::fmt; -use std::ops::Not; use std::str::FromStr; use bitcoin::base64::engine::{general_purpose, GeneralPurpose}; @@ -40,8 +39,8 @@ pub struct PaymentRequest { pub description: Option, /// Transport #[serde(rename = "t")] - #[serde(skip_serializing_if = "Option::is_none")] - pub transports: Option>, + #[serde(skip_serializing_if = "Vec::is_empty", default = "Vec::default")] + pub transports: Vec, /// Nut10 #[serde(skip_serializing_if = "Option::is_none")] pub nut10: Option, @@ -168,8 +167,6 @@ impl PaymentRequestBuilder { /// Build the PaymentRequest pub fn build(self) -> PaymentRequest { - let transports = self.transports.is_empty().not().then_some(self.transports); - PaymentRequest { payment_id: self.payment_id, amount: self.amount, @@ -177,7 +174,7 @@ impl PaymentRequestBuilder { single_use: self.single_use, mints: self.mints, description: self.description, - transports, + transports: self.transports, nut10: self.nut10, } } @@ -224,8 +221,7 @@ mod tests { ); assert_eq!(req.unit.unwrap(), CurrencyUnit::Sat); - let transport = req.transports.unwrap(); - let transport = transport.first().unwrap(); + let transport = req.transports.first().unwrap(); let expected_transport = Transport {_type: TransportType::Nostr, target: "nprofile1qy28wumn8ghj7un9d3shjtnyv9kh2uewd9hsz9mhwden5te0wfjkccte9curxven9eehqctrv5hszrthwden5te0dehhxtnvdakqqgydaqy7curk439ykptkysv7udhdhu68sucm295akqefdehkf0d495cwunl5".to_string(), tags: Some(vec![vec!["n".to_string(), "17".to_string()]])}; @@ -245,7 +241,7 @@ mod tests { .parse() .expect("valid mint url")]), description: None, - transports: Some(vec![transport.clone()]), + transports: vec![transport.clone()], nut10: None, }; @@ -262,8 +258,7 @@ mod tests { ); assert_eq!(req.unit.unwrap(), CurrencyUnit::Sat); - let t = req.transports.unwrap(); - let t = t.first().unwrap(); + let t = req.transports.first().unwrap(); assert_eq!(&transport, t); } @@ -293,8 +288,7 @@ mod tests { assert_eq!(request.unit.clone().unwrap(), CurrencyUnit::Sat); assert_eq!(request.mints.clone().unwrap(), vec![mint_url]); - let t = request.transports.clone().unwrap(); - let t = t.first().unwrap(); + let t = request.transports.first().clone().unwrap(); assert_eq!(&transport, t); // Test serialization and deserialization @@ -497,8 +491,7 @@ mod tests { vec![MintUrl::from_str("https://8333.space:3338").unwrap()] ); - let transport = payment_request.transports.as_ref().unwrap(); - let transport = transport.first().unwrap(); + let transport = payment_request.transports.first().unwrap(); assert_eq!(transport._type, TransportType::Nostr); assert_eq!(transport.target, "nprofile1qy28wumn8ghj7un9d3shjtnyv9kh2uewd9hsz9mhwden5te0wfjkccte9curxven9eehqctrv5hszrthwden5te0dehhxtnvdakqqgydaqy7curk439ykptkysv7udhdhu68sucm295akqefdehkf0d495cwunl5"); assert_eq!( @@ -562,8 +555,7 @@ mod tests { ] ); - let transport = payment_request_cloned.transports.unwrap(); - let transport = transport.first().unwrap(); + let transport = payment_request_cloned.transports.first().unwrap(); assert_eq!(transport._type, TransportType::Nostr); assert_eq!( transport.target, @@ -614,7 +606,7 @@ mod tests { payment_request_cloned.mints.unwrap(), vec![MintUrl::from_str("https://mint.example.com").unwrap()] ); - assert_eq!(payment_request_cloned.transports, None); + assert_eq!(payment_request_cloned.transports, vec![]); // Test round-trip serialization let encoded = payment_request.to_string(); diff --git a/crates/cdk-cli/src/sub_commands/create_request.rs b/crates/cdk-cli/src/sub_commands/create_request.rs index cda60dd49..d92119e68 100644 --- a/crates/cdk-cli/src/sub_commands/create_request.rs +++ b/crates/cdk-cli/src/sub_commands/create_request.rs @@ -100,7 +100,7 @@ pub async fn create_request( // We'll need the Nostr keys and relays later for listening let transport_info = Some((keys, relays, nprofile.public_key)); - (Some(vec![nostr_transport]), transport_info) + (vec![nostr_transport], transport_info) } "http" => { if let Some(url) = &sub_command_args.http_url { @@ -110,18 +110,18 @@ pub async fn create_request( tags: None, }; - (Some(vec![http_transport]), None) + (vec![http_transport], None) } else { println!( "Warning: HTTP transport selected but no URL provided, skipping transport" ); - (None, None) + (vec![], None) } } - "none" => (None, None), + "none" => (vec![], None), _ => { println!("Warning: Unknown transport type '{transport_type}', defaulting to none"); - (None, None) + (vec![], None) } }; @@ -234,7 +234,7 @@ pub async fn create_request( let nut10 = spending_conditions.map(Nut10SecretRequest::from); // Extract the transports option from our match result - let (transports_option, nostr_info) = transports; + let (transports, nostr_info) = transports; let req = PaymentRequest { payment_id: None, @@ -243,7 +243,7 @@ pub async fn create_request( single_use: Some(true), mints: Some(mints), description: sub_command_args.description.clone(), - transports: transports_option, + transports, nut10, }; diff --git a/crates/cdk-cli/src/sub_commands/pay_request.rs b/crates/cdk-cli/src/sub_commands/pay_request.rs index 6ceeb258e..6fd088a48 100644 --- a/crates/cdk-cli/src/sub_commands/pay_request.rs +++ b/crates/cdk-cli/src/sub_commands/pay_request.rs @@ -67,10 +67,10 @@ pub async fn pay_request( let matching_wallet = matching_wallets.first().unwrap(); - let transports = payment_request - .transports - .clone() - .ok_or(anyhow!("Cannot pay request without transport"))?; + if payment_request.transports.is_empty() { + return Err(anyhow!("Cannot pay request without transport")); + } + let transports = payment_request.transports.clone(); // We prefer nostr transport if it is available to hide ip. let transport = transports From f1118b1c7bc6b2344119983a24a03c5ebce80936 Mon Sep 17 00:00:00 2001 From: lollerfirst <43107113+lollerfirst@users.noreply.github.com> Date: Wed, 27 Aug 2025 18:12:35 +0200 Subject: [PATCH 112/321] compatibility for migrating Nutshell Mints quote ids (#984) --- crates/cashu/Cargo.toml | 1 - crates/cashu/src/lib.rs | 104 +++++++++++ crates/cashu/src/nuts/nut04.rs | 12 +- crates/cashu/src/nuts/nut05.rs | 13 +- crates/cashu/src/nuts/nut11/mod.rs | 8 +- crates/cashu/src/nuts/nut17/mod.rs | 22 +-- crates/cashu/src/nuts/nut20.rs | 5 +- crates/cashu/src/nuts/nut23.rs | 12 +- crates/cashu/src/nuts/nut24.rs | 8 +- crates/cdk-axum/src/bolt12_router.rs | 22 +-- crates/cdk-axum/src/router_handlers.rs | 26 +-- crates/cdk-axum/src/ws/mod.rs | 4 +- crates/cdk-common/src/database/mint/mod.rs | 28 +-- crates/cdk-common/src/database/mod.rs | 7 + crates/cdk-common/src/error.rs | 4 + crates/cdk-common/src/lib.rs | 2 + crates/cdk-common/src/mint.rs | 37 ++-- crates/cdk-common/src/subscription.rs | 24 ++- crates/cdk-common/src/ws.rs | 8 +- .../src/bin/start_regtest_mints.rs | 1 + .../src/init_pure_tests.rs | 21 +-- crates/cdk-integration-tests/src/shared.rs | 3 + crates/cdk-mint-rpc/src/proto/server.rs | 2 +- crates/cdk-mintd/src/config.rs | 5 +- crates/cdk-mintd/src/env_vars/common.rs | 1 + crates/cdk-mintd/src/env_vars/info.rs | 4 + crates/cdk-mintd/src/lib.rs | 3 + crates/cdk-sql-common/src/mint/mod.rs | 167 ++++++++++++++---- crates/cdk/src/mint/issue/mod.rs | 24 +-- crates/cdk/src/mint/melt.rs | 26 +-- crates/cdk/src/mint/mod.rs | 4 +- crates/cdk/src/mint/subscription/manager.rs | 14 +- .../src/mint/subscription/on_subscription.rs | 11 +- 33 files changed, 446 insertions(+), 187 deletions(-) diff --git a/crates/cashu/Cargo.toml b/crates/cashu/Cargo.toml index 378e51fd1..2ca6532ca 100644 --- a/crates/cashu/Cargo.toml +++ b/crates/cashu/Cargo.toml @@ -44,4 +44,3 @@ uuid = { workspace = true, features = ["js"], optional = true } [dev-dependencies] bip39.workspace = true -uuid.workspace = true diff --git a/crates/cashu/src/lib.rs b/crates/cashu/src/lib.rs index fb722669b..6604775a2 100644 --- a/crates/cashu/src/lib.rs +++ b/crates/cashu/src/lib.rs @@ -25,3 +25,107 @@ macro_rules! ensure_cdk { } }; } + +#[cfg(feature = "mint")] +/// Quote ID. The specifications only define a string but CDK uses Uuid, so we use an enum to port compatibility. +pub mod quote_id { + use std::fmt; + use std::str::FromStr; + + use bitcoin::base64::engine::general_purpose; + use bitcoin::base64::Engine as _; + use serde::{de, Deserialize, Deserializer, Serialize}; + use thiserror::Error; + use uuid::Uuid; + + /// Invalid UUID + #[derive(Debug, Error)] + pub enum QuoteIdError { + /// UUID Error + #[error("invalid UUID: {0}")] + Uuid(#[from] uuid::Error), + /// Invalid base64 + #[error("invalid base64")] + Base64, + /// Invalid quote ID + #[error("neither a valid UUID nor a valid base64 string")] + InvalidQuoteId, + } + + /// Mint Quote ID + #[derive(Serialize, Debug, Clone, PartialEq, PartialOrd, Ord, Eq, Hash)] + #[serde(untagged)] + pub enum QuoteId { + /// (Nutshell) base64 quote ID + BASE64(String), + /// UUID quote ID + UUID(Uuid), + } + + impl QuoteId { + /// Create a new UUID-based MintQuoteId + pub fn new_uuid() -> Self { + Self::UUID(Uuid::new_v4()) + } + } + + impl From for QuoteId { + fn from(uuid: Uuid) -> Self { + Self::UUID(uuid) + } + } + + impl fmt::Display for QuoteId { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + QuoteId::BASE64(s) => write!(f, "{}", s), + QuoteId::UUID(u) => write!(f, "{}", u), + } + } + } + + impl FromStr for QuoteId { + type Err = QuoteIdError; + + fn from_str(s: &str) -> Result { + // Try UUID first + if let Ok(u) = Uuid::parse_str(s) { + return Ok(QuoteId::UUID(u)); + } + + // Try base64: decode, then re-encode and compare to ensure canonical form + // Use the standard (URL/filename safe or standard) depending on your needed alphabet. + // Here we use standard base64. + match general_purpose::URL_SAFE.decode(s) { + Ok(_bytes) => Ok(QuoteId::BASE64(s.to_string())), + Err(_) => Err(QuoteIdError::InvalidQuoteId), + } + } + } + + impl<'de> Deserialize<'de> for QuoteId { + fn deserialize(deserializer: D) -> Result + where + D: Deserializer<'de>, + { + // Deserialize as plain string first + let s = String::deserialize(deserializer)?; + + // Try UUID first + if let Ok(u) = Uuid::parse_str(&s) { + return Ok(QuoteId::UUID(u)); + } + + if general_purpose::URL_SAFE.decode(&s).is_ok() { + return Ok(QuoteId::BASE64(s)); + } + + // Neither matched — return a helpful error + Err(de::Error::custom(format!( + "QuoteId must be either a UUID (e.g. {}) or a valid base64 string; got: {}", + Uuid::nil(), + s + ))) + } + } +} diff --git a/crates/cashu/src/nuts/nut04.rs b/crates/cashu/src/nuts/nut04.rs index 545cb7a39..78ed50224 100644 --- a/crates/cashu/src/nuts/nut04.rs +++ b/crates/cashu/src/nuts/nut04.rs @@ -10,10 +10,12 @@ use serde::de::{self, DeserializeOwned, Deserializer, MapAccess, Visitor}; use serde::ser::{SerializeStruct, Serializer}; use serde::{Deserialize, Serialize}; use thiserror::Error; -#[cfg(feature = "mint")] -use uuid::Uuid; use super::nut00::{BlindSignature, BlindedMessage, CurrencyUnit, PaymentMethod}; +#[cfg(feature = "mint")] +use crate::quote_id::QuoteId; +#[cfg(feature = "mint")] +use crate::quote_id::QuoteIdError; use crate::Amount; /// NUT04 Error @@ -44,12 +46,12 @@ pub struct MintRequest { } #[cfg(feature = "mint")] -impl TryFrom> for MintRequest { - type Error = uuid::Error; +impl TryFrom> for MintRequest { + type Error = QuoteIdError; fn try_from(value: MintRequest) -> Result { Ok(Self { - quote: Uuid::from_str(&value.quote)?, + quote: QuoteId::from_str(&value.quote)?, outputs: value.outputs, signature: value.signature, }) diff --git a/crates/cashu/src/nuts/nut05.rs b/crates/cashu/src/nuts/nut05.rs index fd8c42951..56fd3fdeb 100644 --- a/crates/cashu/src/nuts/nut05.rs +++ b/crates/cashu/src/nuts/nut05.rs @@ -9,11 +9,11 @@ use serde::de::{self, DeserializeOwned, Deserializer, MapAccess, Visitor}; use serde::ser::{SerializeStruct, Serializer}; use serde::{Deserialize, Serialize}; use thiserror::Error; -#[cfg(feature = "mint")] -use uuid::Uuid; use super::nut00::{BlindedMessage, CurrencyUnit, PaymentMethod, Proofs}; use super::ProofsMethods; +#[cfg(feature = "mint")] +use crate::quote_id::QuoteId; use crate::Amount; /// NUT05 Error @@ -28,6 +28,9 @@ pub enum Error { /// Unsupported unit #[error("Unsupported unit")] UnsupportedUnit, + /// Invalid quote id + #[error("Invalid quote id")] + InvalidQuote, } /// Possible states of a quote @@ -91,12 +94,12 @@ pub struct MeltRequest { } #[cfg(feature = "mint")] -impl TryFrom> for MeltRequest { - type Error = uuid::Error; +impl TryFrom> for MeltRequest { + type Error = Error; fn try_from(value: MeltRequest) -> Result { Ok(Self { - quote: Uuid::from_str(&value.quote)?, + quote: QuoteId::from_str(&value.quote).map_err(|_e| Error::InvalidQuote)?, inputs: value.inputs, outputs: value.outputs, }) diff --git a/crates/cashu/src/nuts/nut11/mod.rs b/crates/cashu/src/nuts/nut11/mod.rs index 514660e49..abc6d2930 100644 --- a/crates/cashu/src/nuts/nut11/mod.rs +++ b/crates/cashu/src/nuts/nut11/mod.rs @@ -1262,6 +1262,7 @@ impl<'de> Deserialize<'de> for Tag { } } +#[cfg(feature = "mint")] #[cfg(test)] mod tests { use std::str::FromStr; @@ -1270,6 +1271,7 @@ mod tests { use super::*; use crate::nuts::Id; + use crate::quote_id::QuoteId; use crate::secret::Secret; use crate::{Amount, BlindedMessage}; @@ -1514,7 +1516,11 @@ mod tests { let blinded_msg = create_test_blinded_msg(pubkey); // Create melt request - let mut melt = MeltRequest::new(Uuid::new_v4(), vec![proof], Some(vec![blinded_msg])); + let mut melt = MeltRequest::new( + QuoteId::UUID(Uuid::new_v4()), + vec![proof], + Some(vec![blinded_msg]), + ); // Before signing, should fail verification assert!( diff --git a/crates/cashu/src/nuts/nut17/mod.rs b/crates/cashu/src/nuts/nut17/mod.rs index 5d01d99c9..d12960bc1 100644 --- a/crates/cashu/src/nuts/nut17/mod.rs +++ b/crates/cashu/src/nuts/nut17/mod.rs @@ -1,14 +1,14 @@ //! Specific Subscription for the cdk crate use serde::de::DeserializeOwned; use serde::{Deserialize, Serialize}; -#[cfg(feature = "mint")] -use uuid::Uuid; #[cfg(feature = "mint")] use super::PublicKey; use crate::nuts::{ CurrencyUnit, MeltQuoteBolt11Response, MintQuoteBolt11Response, PaymentMethod, ProofState, }; +#[cfg(feature = "mint")] +use crate::quote_id::{QuoteId, QuoteIdError}; use crate::MintQuoteBolt12Response; pub mod ws; @@ -154,14 +154,14 @@ impl From> for NotificationPayload { pub enum Notification { /// ProofState id is a Pubkey ProofState(PublicKey), - /// MeltQuote id is an Uuid - MeltQuoteBolt11(Uuid), - /// MintQuote id is an Uuid - MintQuoteBolt11(Uuid), - /// MintQuote id is an Uuid - MintQuoteBolt12(Uuid), - /// MintQuote id is an Uuid - MeltQuoteBolt12(Uuid), + /// MeltQuote id is an QuoteId + MeltQuoteBolt11(QuoteId), + /// MintQuote id is an QuoteId + MintQuoteBolt11(QuoteId), + /// MintQuote id is an QuoteId + MintQuoteBolt12(QuoteId), + /// MintQuote id is an QuoteId + MeltQuoteBolt12(QuoteId), } /// Kind @@ -190,7 +190,7 @@ pub enum Error { #[cfg(feature = "mint")] #[error("Uuid Error: {0}")] /// Uuid Error - Uuid(#[from] uuid::Error), + QuoteId(#[from] QuoteIdError), #[error("PublicKey Error: {0}")] /// PublicKey Error diff --git a/crates/cashu/src/nuts/nut20.rs b/crates/cashu/src/nuts/nut20.rs index 4546dc73f..3f5752ada 100644 --- a/crates/cashu/src/nuts/nut20.rs +++ b/crates/cashu/src/nuts/nut20.rs @@ -74,8 +74,6 @@ where #[cfg(test)] mod tests { - use uuid::Uuid; - use super::*; #[test] @@ -111,8 +109,11 @@ mod tests { assert_eq!(expected_msg_to_sign, request_msg_to_sign); } + #[cfg(feature = "mint")] #[test] fn test_valid_signature() { + use uuid::Uuid; + let pubkey = PublicKey::from_hex( "03d56ce4e446a85bbdaa547b4ec2b073d40ff802831352b8272b7dd7a4de5a7cac", ) diff --git a/crates/cashu/src/nuts/nut23.rs b/crates/cashu/src/nuts/nut23.rs index 9d67fcda8..1ea87703b 100644 --- a/crates/cashu/src/nuts/nut23.rs +++ b/crates/cashu/src/nuts/nut23.rs @@ -8,10 +8,10 @@ use serde::de::DeserializeOwned; use serde::{Deserialize, Deserializer, Serialize}; use serde_json::Value; use thiserror::Error; -#[cfg(feature = "mint")] -use uuid::Uuid; use super::{BlindSignature, CurrencyUnit, MeltQuoteState, Mpp, PublicKey}; +#[cfg(feature = "mint")] +use crate::quote_id::QuoteId; use crate::Amount; /// NUT023 Error @@ -120,8 +120,8 @@ impl MintQuoteBolt11Response { } #[cfg(feature = "mint")] -impl From> for MintQuoteBolt11Response { - fn from(value: MintQuoteBolt11Response) -> Self { +impl From> for MintQuoteBolt11Response { + fn from(value: MintQuoteBolt11Response) -> Self { Self { quote: value.quote.to_string(), request: value.request, @@ -293,8 +293,8 @@ impl MeltQuoteBolt11Response { } #[cfg(feature = "mint")] -impl From> for MeltQuoteBolt11Response { - fn from(value: MeltQuoteBolt11Response) -> Self { +impl From> for MeltQuoteBolt11Response { + fn from(value: MeltQuoteBolt11Response) -> Self { Self { quote: value.quote.to_string(), amount: value.amount, diff --git a/crates/cashu/src/nuts/nut24.rs b/crates/cashu/src/nuts/nut24.rs index 574dec9fd..9c9640087 100644 --- a/crates/cashu/src/nuts/nut24.rs +++ b/crates/cashu/src/nuts/nut24.rs @@ -1,10 +1,10 @@ //! Bolt12 use serde::{Deserialize, Serialize}; use thiserror::Error; -#[cfg(feature = "mint")] -use uuid::Uuid; use super::{CurrencyUnit, MeltOptions, PublicKey}; +#[cfg(feature = "mint")] +use crate::quote_id::QuoteId; use crate::Amount; /// NUT18 Error @@ -76,8 +76,8 @@ impl MintQuoteBolt12Response { } #[cfg(feature = "mint")] -impl From> for MintQuoteBolt12Response { - fn from(value: MintQuoteBolt12Response) -> Self { +impl From> for MintQuoteBolt12Response { + fn from(value: MintQuoteBolt12Response) -> Self { Self { quote: value.quote.to_string(), request: value.request, diff --git a/crates/cdk-axum/src/bolt12_router.rs b/crates/cdk-axum/src/bolt12_router.rs index 4ee363d83..5017e44ff 100644 --- a/crates/cdk-axum/src/bolt12_router.rs +++ b/crates/cdk-axum/src/bolt12_router.rs @@ -3,6 +3,7 @@ use axum::extract::{Json, Path, State}; use axum::response::Response; #[cfg(feature = "swagger")] use cdk::error::ErrorResponse; +use cdk::mint::QuoteId; #[cfg(feature = "auth")] use cdk::nuts::nut21::{Method, ProtectedEndpoint, RoutePath}; use cdk::nuts::{ @@ -11,17 +12,16 @@ use cdk::nuts::{ }; use paste::paste; use tracing::instrument; -use uuid::Uuid; #[cfg(feature = "auth")] use crate::auth::AuthHeader; use crate::{into_response, post_cache_wrapper, MintState}; -post_cache_wrapper!(post_mint_bolt12, MintRequest, MintResponse); +post_cache_wrapper!(post_mint_bolt12, MintRequest, MintResponse); post_cache_wrapper!( post_melt_bolt12, - MeltRequest, - MeltQuoteBolt11Response + MeltRequest, + MeltQuoteBolt11Response ); #[cfg_attr(feature = "swagger", utoipa::path( @@ -38,7 +38,7 @@ pub async fn post_mint_bolt12_quote( #[cfg(feature = "auth")] auth: AuthHeader, State(state): State, Json(payload): Json, -) -> Result>, Response> { +) -> Result>, Response> { #[cfg(feature = "auth")] { state @@ -77,8 +77,8 @@ pub async fn post_mint_bolt12_quote( pub async fn get_check_mint_bolt12_quote( #[cfg(feature = "auth")] auth: AuthHeader, State(state): State, - Path(quote_id): Path, -) -> Result>, Response> { + Path(quote_id): Path, +) -> Result>, Response> { #[cfg(feature = "auth")] { state @@ -115,7 +115,7 @@ pub async fn get_check_mint_bolt12_quote( pub async fn post_mint_bolt12( #[cfg(feature = "auth")] auth: AuthHeader, State(state): State, - Json(payload): Json>, + Json(payload): Json>, ) -> Result, Response> { #[cfg(feature = "auth")] { @@ -155,7 +155,7 @@ pub async fn post_melt_bolt12_quote( #[cfg(feature = "auth")] auth: AuthHeader, State(state): State, Json(payload): Json, -) -> Result>, Response> { +) -> Result>, Response> { #[cfg(feature = "auth")] { state @@ -193,8 +193,8 @@ pub async fn post_melt_bolt12_quote( pub async fn post_melt_bolt12( #[cfg(feature = "auth")] auth: AuthHeader, State(state): State, - Json(payload): Json>, -) -> Result>, Response> { + Json(payload): Json>, +) -> Result>, Response> { #[cfg(feature = "auth")] { state diff --git a/crates/cdk-axum/src/router_handlers.rs b/crates/cdk-axum/src/router_handlers.rs index 1deee5670..541d1d505 100644 --- a/crates/cdk-axum/src/router_handlers.rs +++ b/crates/cdk-axum/src/router_handlers.rs @@ -4,6 +4,7 @@ use axum::extract::{Json, Path, State}; use axum::http::StatusCode; use axum::response::{IntoResponse, Response}; use cdk::error::{ErrorCode, ErrorResponse}; +use cdk::mint::QuoteId; #[cfg(feature = "auth")] use cdk::nuts::nut21::{Method, ProtectedEndpoint, RoutePath}; use cdk::nuts::{ @@ -15,7 +16,6 @@ use cdk::nuts::{ use cdk::util::unix_time; use paste::paste; use tracing::instrument; -use uuid::Uuid; #[cfg(feature = "auth")] use crate::auth::AuthHeader; @@ -62,11 +62,11 @@ macro_rules! post_cache_wrapper { } post_cache_wrapper!(post_swap, SwapRequest, SwapResponse); -post_cache_wrapper!(post_mint_bolt11, MintRequest, MintResponse); +post_cache_wrapper!(post_mint_bolt11, MintRequest, MintResponse); post_cache_wrapper!( post_melt_bolt11, - MeltRequest, - MeltQuoteBolt11Response + MeltRequest, + MeltQuoteBolt11Response ); #[cfg_attr(feature = "swagger", utoipa::path( @@ -152,7 +152,7 @@ pub(crate) async fn post_mint_bolt11_quote( #[cfg(feature = "auth")] auth: AuthHeader, State(state): State, Json(payload): Json, -) -> Result>, Response> { +) -> Result>, Response> { #[cfg(feature = "auth")] state .mint @@ -191,8 +191,8 @@ pub(crate) async fn post_mint_bolt11_quote( pub(crate) async fn get_check_mint_bolt11_quote( #[cfg(feature = "auth")] auth: AuthHeader, State(state): State, - Path(quote_id): Path, -) -> Result>, Response> { + Path(quote_id): Path, +) -> Result>, Response> { #[cfg(feature = "auth")] { state @@ -244,7 +244,7 @@ pub(crate) async fn ws_handler( pub(crate) async fn post_mint_bolt11( #[cfg(feature = "auth")] auth: AuthHeader, State(state): State, - Json(payload): Json>, + Json(payload): Json>, ) -> Result, Response> { #[cfg(feature = "auth")] { @@ -286,7 +286,7 @@ pub(crate) async fn post_melt_bolt11_quote( #[cfg(feature = "auth")] auth: AuthHeader, State(state): State, Json(payload): Json, -) -> Result>, Response> { +) -> Result>, Response> { #[cfg(feature = "auth")] { state @@ -327,8 +327,8 @@ pub(crate) async fn post_melt_bolt11_quote( pub(crate) async fn get_check_melt_bolt11_quote( #[cfg(feature = "auth")] auth: AuthHeader, State(state): State, - Path(quote_id): Path, -) -> Result>, Response> { + Path(quote_id): Path, +) -> Result>, Response> { #[cfg(feature = "auth")] { state @@ -370,8 +370,8 @@ pub(crate) async fn get_check_melt_bolt11_quote( pub(crate) async fn post_melt_bolt11( #[cfg(feature = "auth")] auth: AuthHeader, State(state): State, - Json(payload): Json>, -) -> Result>, Response> { + Json(payload): Json>, +) -> Result>, Response> { #[cfg(feature = "auth")] { state diff --git a/crates/cdk-axum/src/ws/mod.rs b/crates/cdk-axum/src/ws/mod.rs index 03f41af1e..b8496f8e5 100644 --- a/crates/cdk-axum/src/ws/mod.rs +++ b/crates/cdk-axum/src/ws/mod.rs @@ -1,6 +1,7 @@ use std::collections::HashMap; use axum::extract::ws::{Message, WebSocket}; +use cdk::mint::QuoteId; use cdk::nuts::nut17::NotificationPayload; use cdk::pub_sub::SubId; use cdk::ws::{ @@ -9,7 +10,6 @@ use cdk::ws::{ }; use futures::StreamExt; use tokio::sync::mpsc; -use uuid::Uuid; use crate::MintState; @@ -37,7 +37,7 @@ pub use error::WsError; pub struct WsContext { state: MintState, subscriptions: HashMap>, - publisher: mpsc::Sender<(SubId, NotificationPayload)>, + publisher: mpsc::Sender<(SubId, NotificationPayload)>, } /// Main function for websocket connections diff --git a/crates/cdk-common/src/database/mint/mod.rs b/crates/cdk-common/src/database/mint/mod.rs index 7ba65304b..3f3c1d3a8 100644 --- a/crates/cdk-common/src/database/mint/mod.rs +++ b/crates/cdk-common/src/database/mint/mod.rs @@ -3,6 +3,7 @@ use std::collections::HashMap; use async_trait::async_trait; +use cashu::quote_id::QuoteId; use cashu::{Amount, MintInfo}; use uuid::Uuid; @@ -64,25 +65,27 @@ pub trait QuotesTransaction<'a> { type Err: Into + From; /// Get [`MintMintQuote`] and lock it for update in this transaction - async fn get_mint_quote(&mut self, quote_id: &Uuid) - -> Result, Self::Err>; + async fn get_mint_quote( + &mut self, + quote_id: &QuoteId, + ) -> Result, Self::Err>; /// Add [`MintMintQuote`] async fn add_mint_quote(&mut self, quote: MintMintQuote) -> Result<(), Self::Err>; /// Increment amount paid [`MintMintQuote`] async fn increment_mint_quote_amount_paid( &mut self, - quote_id: &Uuid, + quote_id: &QuoteId, amount_paid: Amount, payment_id: String, ) -> Result; /// Increment amount paid [`MintMintQuote`] async fn increment_mint_quote_amount_issued( &mut self, - quote_id: &Uuid, + quote_id: &QuoteId, amount_issued: Amount, ) -> Result; /// Remove [`MintMintQuote`] - async fn remove_mint_quote(&mut self, quote_id: &Uuid) -> Result<(), Self::Err>; + async fn remove_mint_quote(&mut self, quote_id: &QuoteId) -> Result<(), Self::Err>; /// Get [`mint::MeltQuote`] and lock it for update in this transaction async fn get_melt_quote( &mut self, @@ -94,7 +97,7 @@ pub trait QuotesTransaction<'a> { /// Updates the request lookup id for a melt quote async fn update_melt_quote_request_lookup_id( &mut self, - quote_id: &Uuid, + quote_id: &QuoteId, new_request_lookup_id: &PaymentIdentifier, ) -> Result<(), Self::Err>; @@ -103,7 +106,7 @@ pub trait QuotesTransaction<'a> { /// It is expected for this function to fail if the state is already set to the new state async fn update_melt_quote_state( &mut self, - quote_id: &Uuid, + quote_id: &QuoteId, new_state: MeltQuoteState, payment_proof: Option, ) -> Result<(MeltQuoteState, mint::MeltQuote), Self::Err>; @@ -129,7 +132,7 @@ pub trait QuotesDatabase { type Err: Into + From; /// Get [`MintMintQuote`] - async fn get_mint_quote(&self, quote_id: &Uuid) -> Result, Self::Err>; + async fn get_mint_quote(&self, quote_id: &QuoteId) -> Result, Self::Err>; /// Get all [`MintMintQuote`]s async fn get_mint_quote_by_request( @@ -144,7 +147,10 @@ pub trait QuotesDatabase { /// Get Mint Quotes async fn get_mint_quotes(&self) -> Result, Self::Err>; /// Get [`mint::MeltQuote`] - async fn get_melt_quote(&self, quote_id: &Uuid) -> Result, Self::Err>; + async fn get_melt_quote( + &self, + quote_id: &QuoteId, + ) -> Result, Self::Err>; /// Get all [`mint::MeltQuote`]s async fn get_melt_quotes(&self) -> Result, Self::Err>; } @@ -205,7 +211,7 @@ pub trait SignaturesTransaction<'a> { &mut self, blinded_messages: &[PublicKey], blind_signatures: &[BlindSignature], - quote_id: Option, + quote_id: Option, ) -> Result<(), Self::Err>; /// Get [`BlindSignature`]s @@ -234,7 +240,7 @@ pub trait SignaturesDatabase { /// Get [`BlindSignature`]s for quote async fn get_blind_signatures_for_quote( &self, - quote_id: &Uuid, + quote_id: &QuoteId, ) -> Result, Self::Err>; } diff --git a/crates/cdk-common/src/database/mod.rs b/crates/cdk-common/src/database/mod.rs index 2860feb67..51b201188 100644 --- a/crates/cdk-common/src/database/mod.rs +++ b/crates/cdk-common/src/database/mod.rs @@ -126,6 +126,13 @@ pub enum Error { #[error(transparent)] #[cfg(feature = "auth")] NUT22(#[from] crate::nuts::nut22::Error), + /// NUT04 Error + #[error(transparent)] + NUT04(#[from] crate::nuts::nut04::Error), + /// Quote ID Error + #[error(transparent)] + #[cfg(feature = "mint")] + QuoteId(#[from] crate::quote_id::QuoteIdError), /// Serde Error #[error(transparent)] Serde(#[from] serde_json::Error), diff --git a/crates/cdk-common/src/error.rs b/crates/cdk-common/src/error.rs index cffd8d882..b4dc1014a 100644 --- a/crates/cdk-common/src/error.rs +++ b/crates/cdk-common/src/error.rs @@ -363,6 +363,10 @@ pub enum Error { /// NUT23 Error #[error(transparent)] NUT23(#[from] crate::nuts::nut23::Error), + /// Quote ID Error + #[error(transparent)] + #[cfg(feature = "mint")] + QuoteId(#[from] crate::quote_id::QuoteIdError), /// From slice error #[error(transparent)] TryFromSliceError(#[from] TryFromSliceError), diff --git a/crates/cdk-common/src/lib.rs b/crates/cdk-common/src/lib.rs index fcd7bfc95..f30e082a8 100644 --- a/crates/cdk-common/src/lib.rs +++ b/crates/cdk-common/src/lib.rs @@ -29,5 +29,7 @@ pub use bitcoin; pub use cashu::amount::{self, Amount}; pub use cashu::lightning_invoice::{self, Bolt11Invoice}; pub use cashu::nuts::{self, *}; +#[cfg(feature = "mint")] +pub use cashu::quote_id::{self, *}; pub use cashu::{dhke, ensure_cdk, mint_url, secret, util, SECP256K1}; pub use error::Error; diff --git a/crates/cdk-common/src/mint.rs b/crates/cdk-common/src/mint.rs index b4130f0b2..9c63b0fdd 100644 --- a/crates/cdk-common/src/mint.rs +++ b/crates/cdk-common/src/mint.rs @@ -1,6 +1,7 @@ //! Mint types use bitcoin::bip32::DerivationPath; +use cashu::quote_id::QuoteId; use cashu::util::unix_time; use cashu::{ Bolt11Invoice, MeltOptions, MeltQuoteBolt11Response, MintQuoteBolt11Response, @@ -19,7 +20,7 @@ use crate::{Amount, CurrencyUnit, Id, KeySetInfo, PublicKey}; #[derive(Debug, Clone, Hash, PartialEq, Eq, Serialize, Deserialize)] pub struct MintQuote { /// Quote id - pub id: Uuid, + pub id: QuoteId, /// Amount of quote pub amount: Option, /// Unit of quote @@ -56,7 +57,7 @@ impl MintQuote { /// Create new [`MintQuote`] #[allow(clippy::too_many_arguments)] pub fn new( - id: Option, + id: Option, request: String, unit: CurrencyUnit, amount: Option, @@ -70,7 +71,7 @@ impl MintQuote { payments: Vec, issuance: Vec, ) -> Self { - let id = id.unwrap_or(Uuid::new_v4()); + let id = id.unwrap_or_else(QuoteId::new_uuid); Self { id, @@ -230,7 +231,7 @@ impl Issuance { #[derive(Debug, Clone, Hash, PartialEq, Eq, Serialize, Deserialize)] pub struct MeltQuote { /// Quote id - pub id: Uuid, + pub id: QuoteId, /// Quote unit pub unit: CurrencyUnit, /// Quote amount @@ -277,7 +278,7 @@ impl MeltQuote { let id = Uuid::new_v4(); Self { - id, + id: QuoteId::UUID(id), amount, unit, request, @@ -336,10 +337,10 @@ impl From for KeySetInfo { } } -impl From for MintQuoteBolt11Response { - fn from(mint_quote: crate::mint::MintQuote) -> MintQuoteBolt11Response { +impl From for MintQuoteBolt11Response { + fn from(mint_quote: crate::mint::MintQuote) -> MintQuoteBolt11Response { MintQuoteBolt11Response { - quote: mint_quote.id, + quote: mint_quote.id.clone(), state: mint_quote.state(), request: mint_quote.request, expiry: Some(mint_quote.expiry), @@ -352,18 +353,18 @@ impl From for MintQuoteBolt11Response { impl From for MintQuoteBolt11Response { fn from(quote: MintQuote) -> Self { - let quote: MintQuoteBolt11Response = quote.into(); + let quote: MintQuoteBolt11Response = quote.into(); quote.into() } } -impl TryFrom for MintQuoteBolt12Response { +impl TryFrom for MintQuoteBolt12Response { type Error = crate::Error; fn try_from(mint_quote: crate::mint::MintQuote) -> Result { Ok(MintQuoteBolt12Response { - quote: mint_quote.id, + quote: mint_quote.id.clone(), request: mint_quote.request, expiry: Some(mint_quote.expiry), amount_paid: mint_quote.amount_paid, @@ -379,16 +380,16 @@ impl TryFrom for MintQuoteBolt12Response { type Error = crate::Error; fn try_from(quote: MintQuote) -> Result { - let quote: MintQuoteBolt12Response = quote.try_into()?; + let quote: MintQuoteBolt12Response = quote.try_into()?; Ok(quote.into()) } } -impl From<&MeltQuote> for MeltQuoteBolt11Response { - fn from(melt_quote: &MeltQuote) -> MeltQuoteBolt11Response { +impl From<&MeltQuote> for MeltQuoteBolt11Response { + fn from(melt_quote: &MeltQuote) -> MeltQuoteBolt11Response { MeltQuoteBolt11Response { - quote: melt_quote.id, + quote: melt_quote.id.clone(), payment_preimage: None, change: None, state: melt_quote.state, @@ -402,11 +403,11 @@ impl From<&MeltQuote> for MeltQuoteBolt11Response { } } -impl From for MeltQuoteBolt11Response { - fn from(melt_quote: MeltQuote) -> MeltQuoteBolt11Response { +impl From for MeltQuoteBolt11Response { + fn from(melt_quote: MeltQuote) -> MeltQuoteBolt11Response { let paid = melt_quote.state == MeltQuoteState::Paid; MeltQuoteBolt11Response { - quote: melt_quote.id, + quote: melt_quote.id.clone(), amount: melt_quote.amount, fee_reserve: melt_quote.fee_reserve, paid: Some(paid), diff --git a/crates/cdk-common/src/subscription.rs b/crates/cdk-common/src/subscription.rs index dacd284c4..01407de6d 100644 --- a/crates/cdk-common/src/subscription.rs +++ b/crates/cdk-common/src/subscription.rs @@ -6,11 +6,11 @@ use cashu::nut17::{self}; #[cfg(feature = "mint")] use cashu::nut17::{Error, Kind, Notification}; #[cfg(feature = "mint")] +use cashu::quote_id::QuoteId; +#[cfg(feature = "mint")] use cashu::{NotificationPayload, PublicKey}; #[cfg(feature = "mint")] use serde::{Deserialize, Serialize}; -#[cfg(feature = "mint")] -use uuid::Uuid; #[cfg(feature = "mint")] use crate::pub_sub::index::{Index, Indexable, SubscriptionGlobalId}; @@ -45,14 +45,14 @@ impl TryFrom for Vec> { .map(|filter| { let idx = match params.kind { Kind::Bolt11MeltQuote => { - Notification::MeltQuoteBolt11(Uuid::from_str(&filter)?) + Notification::MeltQuoteBolt11(QuoteId::from_str(&filter)?) } Kind::Bolt11MintQuote => { - Notification::MintQuoteBolt11(Uuid::from_str(&filter)?) + Notification::MintQuoteBolt11(QuoteId::from_str(&filter)?) } Kind::ProofState => Notification::ProofState(PublicKey::from_str(&filter)?), Kind::Bolt12MintQuote => { - Notification::MintQuoteBolt12(Uuid::from_str(&filter)?) + Notification::MintQuoteBolt12(QuoteId::from_str(&filter)?) } }; @@ -70,7 +70,7 @@ impl AsRef for IndexableParams { } #[cfg(feature = "mint")] -impl Indexable for NotificationPayload { +impl Indexable for NotificationPayload { type Type = Notification; fn to_indexes(&self) -> Vec> { @@ -79,13 +79,19 @@ impl Indexable for NotificationPayload { vec![Index::from(Notification::ProofState(proof_state.y))] } NotificationPayload::MeltQuoteBolt11Response(melt_quote) => { - vec![Index::from(Notification::MeltQuoteBolt11(melt_quote.quote))] + vec![Index::from(Notification::MeltQuoteBolt11( + melt_quote.quote.clone(), + ))] } NotificationPayload::MintQuoteBolt11Response(mint_quote) => { - vec![Index::from(Notification::MintQuoteBolt11(mint_quote.quote))] + vec![Index::from(Notification::MintQuoteBolt11( + mint_quote.quote.clone(), + ))] } NotificationPayload::MintQuoteBolt12Response(mint_quote) => { - vec![Index::from(Notification::MintQuoteBolt12(mint_quote.quote))] + vec![Index::from(Notification::MintQuoteBolt12( + mint_quote.quote.clone(), + ))] } } } diff --git a/crates/cdk-common/src/ws.rs b/crates/cdk-common/src/ws.rs index 1f2e5246e..c471cc883 100644 --- a/crates/cdk-common/src/ws.rs +++ b/crates/cdk-common/src/ws.rs @@ -6,9 +6,9 @@ use cashu::nut17::ws::JSON_RPC_VERSION; use cashu::nut17::{self}; #[cfg(feature = "mint")] -use cashu::NotificationPayload; +use cashu::quote_id::QuoteId; #[cfg(feature = "mint")] -use uuid::Uuid; +use cashu::NotificationPayload; use crate::pub_sub::SubId; @@ -48,7 +48,7 @@ pub type NotificationInner = nut17::ws::NotificationInner; #[cfg(feature = "mint")] /// Converts a notification with UUID identifiers to a notification with string identifiers pub fn notification_uuid_to_notification_string( - notification: NotificationInner, + notification: NotificationInner, ) -> NotificationInner { nut17::ws::NotificationInner { sub_id: notification.sub_id, @@ -69,7 +69,7 @@ pub fn notification_uuid_to_notification_string( #[cfg(feature = "mint")] /// Converts a notification to a websocket message that can be sent to clients -pub fn notification_to_ws_message(notification: NotificationInner) -> WsMessageOrResponse { +pub fn notification_to_ws_message(notification: NotificationInner) -> WsMessageOrResponse { nut17::ws::WsMessageOrResponse::Notification(nut17::ws::WsNotification { jsonrpc: JSON_RPC_VERSION.to_owned(), method: "subscribe".to_string(), diff --git a/crates/cdk-integration-tests/src/bin/start_regtest_mints.rs b/crates/cdk-integration-tests/src/bin/start_regtest_mints.rs index 5f6cca28f..4c361fb5c 100644 --- a/crates/cdk-integration-tests/src/bin/start_regtest_mints.rs +++ b/crates/cdk-integration-tests/src/bin/start_regtest_mints.rs @@ -260,6 +260,7 @@ fn create_ldk_settings( url: format!("http://127.0.0.1:{port}"), listen_host: "127.0.0.1".to_string(), listen_port: port, + seed: None, mnemonic: Some(mnemonic), signatory_url: None, signatory_certs: None, diff --git a/crates/cdk-integration-tests/src/init_pure_tests.rs b/crates/cdk-integration-tests/src/init_pure_tests.rs index c4a27ab97..21c090567 100644 --- a/crates/cdk-integration-tests/src/init_pure_tests.rs +++ b/crates/cdk-integration-tests/src/init_pure_tests.rs @@ -8,6 +8,7 @@ use std::{env, fs}; use anyhow::{anyhow, bail, Result}; use async_trait::async_trait; use bip39::Mnemonic; +use cashu::quote_id::QuoteId; use cashu::{MeltQuoteBolt12Request, MintQuoteBolt12Request, MintQuoteBolt12Response}; use cdk::amount::SplitTarget; use cdk::cdk_database::{self, MintDatabase, WalletDatabase}; @@ -80,16 +81,15 @@ impl MintConnector for DirectMintConnection { &self, quote_id: &str, ) -> Result, Error> { - let quote_id_uuid = Uuid::from_str(quote_id).unwrap(); self.mint - .check_mint_quote("e_id_uuid) + .check_mint_quote(&QuoteId::from_str(quote_id)?) .await .map(Into::into) } async fn post_mint(&self, request: MintRequest) -> Result { - let request_uuid = request.try_into().unwrap(); - self.mint.process_mint_request(request_uuid).await + let request_id: MintRequest = request.try_into().unwrap(); + self.mint.process_mint_request(request_id).await } async fn post_melt_quote( @@ -106,9 +106,8 @@ impl MintConnector for DirectMintConnection { &self, quote_id: &str, ) -> Result, Error> { - let quote_id_uuid = Uuid::from_str(quote_id).unwrap(); self.mint - .check_melt_quote("e_id_uuid) + .check_melt_quote(&QuoteId::from_str(quote_id)?) .await .map(Into::into) } @@ -156,7 +155,7 @@ impl MintConnector for DirectMintConnection { &self, request: MintQuoteBolt12Request, ) -> Result, Error> { - let res: MintQuoteBolt12Response = + let res: MintQuoteBolt12Response = self.mint.get_mint_quote(request.into()).await?.try_into()?; Ok(res.into()) } @@ -165,10 +164,9 @@ impl MintConnector for DirectMintConnection { &self, quote_id: &str, ) -> Result, Error> { - let quote_id_uuid = Uuid::from_str(quote_id).unwrap(); - let quote: MintQuoteBolt12Response = self + let quote: MintQuoteBolt12Response = self .mint - .check_mint_quote("e_id_uuid) + .check_mint_quote(&QuoteId::from_str(quote_id)?) .await? .try_into()?; @@ -190,9 +188,8 @@ impl MintConnector for DirectMintConnection { &self, quote_id: &str, ) -> Result, Error> { - let quote_id_uuid = Uuid::from_str(quote_id).unwrap(); self.mint - .check_melt_quote("e_id_uuid) + .check_melt_quote(&QuoteId::from_str(quote_id)?) .await .map(Into::into) } diff --git a/crates/cdk-integration-tests/src/shared.rs b/crates/cdk-integration-tests/src/shared.rs index 85efef281..d854441ef 100644 --- a/crates/cdk-integration-tests/src/shared.rs +++ b/crates/cdk-integration-tests/src/shared.rs @@ -183,6 +183,7 @@ pub fn create_fake_wallet_settings( url: format!("http://127.0.0.1:{port}"), listen_host: "127.0.0.1".to_string(), listen_port: port, + seed: None, mnemonic, signatory_url: signatory_config.as_ref().map(|(url, _)| url.clone()), signatory_certs: signatory_config @@ -233,6 +234,7 @@ pub fn create_cln_settings( url: format!("http://127.0.0.1:{port}"), listen_host: "127.0.0.1".to_string(), listen_port: port, + seed: None, mnemonic: Some(mnemonic), signatory_url: None, signatory_certs: None, @@ -277,6 +279,7 @@ pub fn create_lnd_settings( url: format!("http://127.0.0.1:{port}"), listen_host: "127.0.0.1".to_string(), listen_port: port, + seed: None, mnemonic: Some(mnemonic), signatory_url: None, signatory_certs: None, diff --git a/crates/cdk-mint-rpc/src/proto/server.rs b/crates/cdk-mint-rpc/src/proto/server.rs index 7b8508e50..c8c2d6b8f 100644 --- a/crates/cdk-mint-rpc/src/proto/server.rs +++ b/crates/cdk-mint-rpc/src/proto/server.rs @@ -677,7 +677,7 @@ impl CdkMint for MintRPCServer { _ => { // Create a new quote with the same values let quote = MintQuote::new( - Some(mint_quote.id), // id + Some(mint_quote.id.clone()), // id mint_quote.request.clone(), // request mint_quote.unit.clone(), // unit mint_quote.amount, // amount diff --git a/crates/cdk-mintd/src/config.rs b/crates/cdk-mintd/src/config.rs index 56bdecd1e..e4877d7c8 100644 --- a/crates/cdk-mintd/src/config.rs +++ b/crates/cdk-mintd/src/config.rs @@ -50,6 +50,8 @@ pub struct Info { pub url: String, pub listen_host: String, pub listen_port: u16, + /// Overrides mnemonic + pub seed: Option, pub mnemonic: Option, pub signatory_url: Option, pub signatory_certs: Option, @@ -74,6 +76,7 @@ impl Default for Info { url: String::new(), listen_host: "127.0.0.1".to_string(), listen_port: 8091, // Default to port 8091 instead of 0 + seed: None, mnemonic: None, signatory_url: None, signatory_certs: None, @@ -88,7 +91,7 @@ impl Default for Info { impl std::fmt::Debug for Info { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { // Use a fallback approach that won't panic - let mnemonic_display = { + let mnemonic_display: String = { if let Some(mnemonic) = self.mnemonic.as_ref() { let hash = sha256::Hash::hash(mnemonic.as_bytes()); format!("") diff --git a/crates/cdk-mintd/src/env_vars/common.rs b/crates/cdk-mintd/src/env_vars/common.rs index 9e981304f..f8e5b8391 100644 --- a/crates/cdk-mintd/src/env_vars/common.rs +++ b/crates/cdk-mintd/src/env_vars/common.rs @@ -6,6 +6,7 @@ pub const DATABASE_URL_ENV_VAR: &str = "CDK_MINTD_DATABASE_URL"; // Legacy, main pub const ENV_URL: &str = "CDK_MINTD_URL"; pub const ENV_LISTEN_HOST: &str = "CDK_MINTD_LISTEN_HOST"; pub const ENV_LISTEN_PORT: &str = "CDK_MINTD_LISTEN_PORT"; +pub const ENV_SEED: &str = "CDK_MINTD_SEED"; pub const ENV_MNEMONIC: &str = "CDK_MINTD_MNEMONIC"; pub const ENV_SIGNATORY_URL: &str = "CDK_MINTD_SIGNATORY_URL"; pub const ENV_SIGNATORY_CERTS: &str = "CDK_MINTD_SIGNATORY_CERTS"; diff --git a/crates/cdk-mintd/src/env_vars/info.rs b/crates/cdk-mintd/src/env_vars/info.rs index 7024d0bdb..1ff11ac6f 100644 --- a/crates/cdk-mintd/src/env_vars/info.rs +++ b/crates/cdk-mintd/src/env_vars/info.rs @@ -31,6 +31,10 @@ impl Info { self.signatory_certs = Some(signatory_certs); } + if let Ok(seed) = env::var(ENV_SEED) { + self.seed = Some(seed); + } + if let Ok(mnemonic) = env::var(ENV_MNEMONIC) { self.mnemonic = Some(mnemonic); } diff --git a/crates/cdk-mintd/src/lib.rs b/crates/cdk-mintd/src/lib.rs index 233b2738f..1df625991 100644 --- a/crates/cdk-mintd/src/lib.rs +++ b/crates/cdk-mintd/src/lib.rs @@ -805,6 +805,9 @@ async fn build_mint( .await?, )) .await?) + } else if let Some(seed) = settings.info.seed.clone() { + let seed_bytes: Vec = seed.into(); + Ok(mint_builder.build_with_seed(keystore, &seed_bytes).await?) } else if let Some(mnemonic) = settings .info .mnemonic diff --git a/crates/cdk-sql-common/src/mint/mod.rs b/crates/cdk-sql-common/src/mint/mod.rs index 385a00cc7..02f281504 100644 --- a/crates/cdk-sql-common/src/mint/mod.rs +++ b/crates/cdk-sql-common/src/mint/mod.rs @@ -26,6 +26,7 @@ use cdk_common::mint::{ }; use cdk_common::nut00::ProofsMethods; use cdk_common::payment::PaymentIdentifier; +use cdk_common::quote_id::QuoteId; use cdk_common::secret::Secret; use cdk_common::state::check_state_transition; use cdk_common::util::unix_time; @@ -309,7 +310,7 @@ where #[inline(always)] async fn get_mint_quote_payments( conn: &C, - quote_id: &Uuid, + quote_id: &QuoteId, ) -> Result, Error> where C: DatabaseExecutor + Send + Sync, @@ -327,7 +328,13 @@ where quote_id=:quote_id "#, )? - .bind("quote_id", quote_id.as_hyphenated().to_string()) + .bind( + "quote_id", + match quote_id { + QuoteId::UUID(u) => u.as_hyphenated().to_string(), + QuoteId::BASE64(s) => s.to_string(), + }, + ) .fetch_all(conn) .await? .into_iter() @@ -344,7 +351,7 @@ where } #[inline(always)] -async fn get_mint_quote_issuance(conn: &C, quote_id: &Uuid) -> Result, Error> +async fn get_mint_quote_issuance(conn: &C, quote_id: &QuoteId) -> Result, Error> where C: DatabaseExecutor + Send + Sync, { @@ -356,7 +363,13 @@ FROM mint_quote_issued WHERE quote_id=:quote_id "#, )? - .bind("quote_id", quote_id.as_hyphenated().to_string()) + .bind( + "quote_id", + match quote_id { + QuoteId::UUID(u) => u.as_hyphenated().to_string(), + QuoteId::BASE64(s) => s.to_string(), + }, + ) .fetch_all(conn) .await? .into_iter() @@ -542,7 +555,7 @@ where #[instrument(skip(self))] async fn increment_mint_quote_amount_paid( &mut self, - quote_id: &Uuid, + quote_id: &QuoteId, amount_paid: Amount, payment_id: String, ) -> Result { @@ -578,7 +591,13 @@ where FOR UPDATE "#, )? - .bind("quote_id", quote_id.as_hyphenated().to_string()) + .bind( + "quote_id", + match quote_id { + QuoteId::UUID(u) => u.as_hyphenated().to_string(), + QuoteId::BASE64(s) => s.to_string(), + }, + ) .fetch_one(&self.inner) .await .inspect_err(|err| { @@ -613,7 +632,13 @@ where "#, )? .bind("amount_paid", new_amount_paid.to_i64()) - .bind("quote_id", quote_id.as_hyphenated().to_string()) + .bind( + "quote_id", + match quote_id { + QuoteId::UUID(u) => u.as_hyphenated().to_string(), + QuoteId::BASE64(s) => s.to_string(), + }, + ) .execute(&self.inner) .await .inspect_err(|err| { @@ -628,7 +653,13 @@ where VALUES (:quote_id, :payment_id, :amount, :timestamp) "#, )? - .bind("quote_id", quote_id.as_hyphenated().to_string()) + .bind( + "quote_id", + match quote_id { + QuoteId::UUID(u) => u.as_hyphenated().to_string(), + QuoteId::BASE64(s) => s.to_string(), + }, + ) .bind("payment_id", payment_id) .bind("amount", amount_paid.to_i64()) .bind("timestamp", unix_time() as i64) @@ -645,7 +676,7 @@ where #[instrument(skip_all)] async fn increment_mint_quote_amount_issued( &mut self, - quote_id: &Uuid, + quote_id: &QuoteId, amount_issued: Amount, ) -> Result { // Get current amount_issued from quote @@ -657,7 +688,13 @@ where FOR UPDATE "#, )? - .bind("quote_id", quote_id.as_hyphenated().to_string()) + .bind( + "quote_id", + match quote_id { + QuoteId::UUID(u) => u.as_hyphenated().to_string(), + QuoteId::BASE64(s) => s.to_string(), + }, + ) .fetch_one(&self.inner) .await .inspect_err(|err| { @@ -685,7 +722,13 @@ where "#, )? .bind("amount_issued", new_amount_issued.to_i64()) - .bind("quote_id", quote_id.as_hyphenated().to_string()) + .bind( + "quote_id", + match quote_id { + QuoteId::UUID(u) => u.as_hyphenated().to_string(), + QuoteId::BASE64(s) => s.to_string(), + }, + ) .execute(&self.inner) .await .inspect_err(|err| { @@ -701,7 +744,13 @@ INSERT INTO mint_quote_issued VALUES (:quote_id, :amount, :timestamp); "#, )? - .bind("quote_id", quote_id.as_hyphenated().to_string()) + .bind( + "quote_id", + match quote_id { + QuoteId::UUID(u) => u.as_hyphenated().to_string(), + QuoteId::BASE64(s) => s.to_string(), + }, + ) .bind("amount", amount_issued.to_i64()) .bind("timestamp", current_time as i64) .execute(&self.inner) @@ -741,9 +790,15 @@ VALUES (:quote_id, :amount, :timestamp); Ok(()) } - async fn remove_mint_quote(&mut self, quote_id: &Uuid) -> Result<(), Self::Err> { + async fn remove_mint_quote(&mut self, quote_id: &QuoteId) -> Result<(), Self::Err> { query(r#"DELETE FROM mint_quote WHERE id=:id"#)? - .bind("id", quote_id.as_hyphenated().to_string()) + .bind( + "id", + match quote_id { + QuoteId::UUID(u) => u.as_hyphenated().to_string(), + QuoteId::BASE64(s) => s.to_string(), + }, + ) .execute(&self.inner) .await?; Ok(()) @@ -800,13 +855,16 @@ VALUES (:quote_id, :amount, :timestamp); async fn update_melt_quote_request_lookup_id( &mut self, - quote_id: &Uuid, + quote_id: &QuoteId, new_request_lookup_id: &PaymentIdentifier, ) -> Result<(), Self::Err> { query(r#"UPDATE melt_quote SET request_lookup_id = :new_req_id, request_lookup_id_kind = :new_kind WHERE id = :id"#)? .bind("new_req_id", new_request_lookup_id.to_string()) .bind("new_kind",new_request_lookup_id.kind() ) - .bind("id", quote_id.as_hyphenated().to_string()) + .bind("id", match quote_id { + QuoteId::BASE64(s) => s.to_string(), + QuoteId::UUID(u) => u.as_hyphenated().to_string(), + }) .execute(&self.inner) .await?; Ok(()) @@ -814,7 +872,7 @@ VALUES (:quote_id, :amount, :timestamp); async fn update_melt_quote_state( &mut self, - quote_id: &Uuid, + quote_id: &QuoteId, state: MeltQuoteState, payment_proof: Option, ) -> Result<(MeltQuoteState, mint::MeltQuote), Self::Err> { @@ -842,7 +900,13 @@ VALUES (:quote_id, :amount, :timestamp); AND state != :state "#, )? - .bind("id", quote_id.as_hyphenated().to_string()) + .bind( + "id", + match quote_id { + QuoteId::UUID(u) => u.as_hyphenated().to_string(), + QuoteId::BASE64(s) => s.to_string(), + }, + ) .bind("state", state.to_string()) .fetch_one(&self.inner) .await? @@ -856,13 +920,22 @@ VALUES (:quote_id, :amount, :timestamp); .bind("state", state.to_string()) .bind("paid_time", current_time as i64) .bind("payment_preimage", payment_proof) - .bind("id", quote_id.as_hyphenated().to_string()) + .bind("id", match quote_id { + QuoteId::UUID(u) => u.as_hyphenated().to_string(), + QuoteId::BASE64(s) => s.to_string(), + }) .execute(&self.inner) .await } else { query(r#"UPDATE melt_quote SET state = :state WHERE id = :id"#)? .bind("state", state.to_string()) - .bind("id", quote_id.as_hyphenated().to_string()) + .bind( + "id", + match quote_id { + QuoteId::UUID(u) => u.as_hyphenated().to_string(), + QuoteId::BASE64(s) => s.to_string(), + }, + ) .execute(&self.inner) .await }; @@ -895,7 +968,7 @@ VALUES (:quote_id, :amount, :timestamp); Ok(()) } - async fn get_mint_quote(&mut self, quote_id: &Uuid) -> Result, Self::Err> { + async fn get_mint_quote(&mut self, quote_id: &QuoteId) -> Result, Self::Err> { let payments = get_mint_quote_payments(&self.inner, quote_id).await?; let issuance = get_mint_quote_issuance(&self.inner, quote_id).await?; @@ -920,7 +993,13 @@ VALUES (:quote_id, :amount, :timestamp); FOR UPDATE "#, )? - .bind("id", quote_id.as_hyphenated().to_string()) + .bind( + "id", + match quote_id { + QuoteId::UUID(u) => u.as_hyphenated().to_string(), + QuoteId::BASE64(s) => s.to_string(), + }, + ) .fetch_one(&self.inner) .await? .map(|row| sql_row_to_mint_quote(row, payments, issuance)) @@ -1053,7 +1132,7 @@ where { type Err = Error; - async fn get_mint_quote(&self, quote_id: &Uuid) -> Result, Self::Err> { + async fn get_mint_quote(&self, quote_id: &QuoteId) -> Result, Self::Err> { let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; let payments = get_mint_quote_payments(&*conn, quote_id).await?; @@ -1078,7 +1157,13 @@ where mint_quote WHERE id = :id"#, )? - .bind("id", quote_id.as_hyphenated().to_string()) + .bind( + "id", + match quote_id { + QuoteId::UUID(u) => u.as_hyphenated().to_string(), + QuoteId::BASE64(s) => s.to_string(), + }, + ) .fetch_one(&*conn) .await? .map(|row| sql_row_to_mint_quote(row, payments, issuance)) @@ -1206,7 +1291,10 @@ where Ok(mint_quotes) } - async fn get_melt_quote(&self, quote_id: &Uuid) -> Result, Self::Err> { + async fn get_melt_quote( + &self, + quote_id: &QuoteId, + ) -> Result, Self::Err> { let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; Ok(query( r#" @@ -1231,7 +1319,13 @@ where id=:id "#, )? - .bind("id", quote_id.as_hyphenated().to_string()) + .bind( + "id", + match quote_id { + QuoteId::BASE64(s) => s.to_string(), + QuoteId::UUID(u) => u.as_hyphenated().to_string(), + }, + ) .fetch_one(&*conn) .await? .map(sql_row_to_melt_quote) @@ -1386,7 +1480,7 @@ where &mut self, blinded_messages: &[PublicKey], blind_signatures: &[BlindSignature], - quote_id: Option, + quote_id: Option, ) -> Result<(), Self::Err> { let current_time = unix_time(); @@ -1403,7 +1497,10 @@ where .bind("amount", u64::from(signature.amount) as i64) .bind("keyset_id", signature.keyset_id.to_string()) .bind("c", signature.c.to_bytes().to_vec()) - .bind("quote_id", quote_id.map(|q| q.hyphenated().to_string())) + .bind("quote_id", quote_id.as_ref().map(|q| match q { + QuoteId::BASE64(s) => s.to_string(), + QuoteId::UUID(u) => u.hyphenated().to_string(), + })) .bind( "dleq_e", signature.dleq.as_ref().map(|dleq| dleq.e.to_secret_hex()), @@ -1547,7 +1644,7 @@ where /// Get [`BlindSignature`]s for quote async fn get_blind_signatures_for_quote( &self, - quote_id: &Uuid, + quote_id: &QuoteId, ) -> Result, Self::Err> { let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; Ok(query( @@ -1564,7 +1661,13 @@ where quote_id=:quote_id "#, )? - .bind("quote_id", quote_id.to_string()) + .bind( + "quote_id", + match quote_id { + QuoteId::BASE64(s) => s.to_string(), + QuoteId::UUID(u) => u.as_hyphenated().to_string(), + }, + ) .fetch_all(&*conn) .await? .into_iter() @@ -1658,7 +1761,7 @@ fn sql_row_to_mint_quote( let payment_method = column_as_string!(payment_method, PaymentMethod::from_str); Ok(MintQuote::new( - Some(Uuid::parse_str(&id).map_err(|_| Error::InvalidUuid(id))?), + Some(QuoteId::from_str(&id)?), request_str, column_as_string!(unit, CurrencyUnit::from_str), amount.map(Amount::from), @@ -1745,7 +1848,7 @@ fn sql_row_to_melt_quote(row: Vec) -> Result { }; Ok(MeltQuote { - id: Uuid::parse_str(&id).map_err(|_| Error::InvalidUuid(id))?, + id: QuoteId::from_str(&id)?, unit: CurrencyUnit::from_str(&unit)?, amount: Amount::from(amount), request, diff --git a/crates/cdk/src/mint/issue/mod.rs b/crates/cdk/src/mint/issue/mod.rs index ee8bc9665..1e5767db3 100644 --- a/crates/cdk/src/mint/issue/mod.rs +++ b/crates/cdk/src/mint/issue/mod.rs @@ -3,6 +3,7 @@ use cdk_common::payment::{ Bolt11IncomingPaymentOptions, Bolt11Settings, Bolt12IncomingPaymentOptions, IncomingPaymentOptions, WaitPaymentResponse, }; +use cdk_common::quote_id::QuoteId; use cdk_common::util::unix_time; use cdk_common::{ database, ensure_cdk, Amount, CurrencyUnit, Error, MintQuoteBolt11Request, @@ -10,7 +11,6 @@ use cdk_common::{ MintRequest, MintResponse, NotificationPayload, PaymentMethod, PublicKey, }; use tracing::instrument; -use uuid::Uuid; use crate::mint::Verification; use crate::Mint; @@ -49,12 +49,12 @@ impl From for MintQuoteRequest { #[derive(Debug, Clone, PartialEq, Eq)] pub enum MintQuoteResponse { /// Lightning Network BOLT11 invoice response - Bolt11(MintQuoteBolt11Response), + Bolt11(MintQuoteBolt11Response), /// Lightning Network BOLT12 offer response - Bolt12(MintQuoteBolt12Response), + Bolt12(MintQuoteBolt12Response), } -impl TryFrom for MintQuoteBolt11Response { +impl TryFrom for MintQuoteBolt11Response { type Error = Error; fn try_from(response: MintQuoteResponse) -> Result { @@ -65,7 +65,7 @@ impl TryFrom for MintQuoteBolt11Response { } } -impl TryFrom for MintQuoteBolt12Response { +impl TryFrom for MintQuoteBolt12Response { type Error = Error; fn try_from(response: MintQuoteResponse) -> Result { @@ -82,7 +82,7 @@ impl TryFrom for MintQuoteResponse { fn try_from(quote: MintQuote) -> Result { match quote.payment_method { PaymentMethod::Bolt11 => { - let bolt11_response: MintQuoteBolt11Response = quote.into(); + let bolt11_response: MintQuoteBolt11Response = quote.into(); Ok(MintQuoteResponse::Bolt11(bolt11_response)) } PaymentMethod::Bolt12 => { @@ -298,12 +298,12 @@ impl Mint { match payment_method { PaymentMethod::Bolt11 => { - let res: MintQuoteBolt11Response = quote.clone().into(); + let res: MintQuoteBolt11Response = quote.clone().into(); self.pubsub_manager .broadcast(NotificationPayload::MintQuoteBolt11Response(res)); } PaymentMethod::Bolt12 => { - let res: MintQuoteBolt12Response = quote.clone().try_into()?; + let res: MintQuoteBolt12Response = quote.clone().try_into()?; self.pubsub_manager .broadcast(NotificationPayload::MintQuoteBolt12Response(res)); } @@ -333,7 +333,7 @@ impl Mint { /// * `Ok(())` if removal was successful /// * `Error` if the quote doesn't exist or removal fails #[instrument(skip_all)] - pub async fn remove_mint_quote(&self, quote_id: &Uuid) -> Result<(), Error> { + pub async fn remove_mint_quote(&self, quote_id: &QuoteId) -> Result<(), Error> { let mut tx = self.localstore.begin_transaction().await?; tx.remove_mint_quote(quote_id).await?; tx.commit().await?; @@ -421,7 +421,7 @@ impl Mint { /// * `MintQuoteResponse` - The current state of the quote /// * `Error` if the quote doesn't exist or checking fails #[instrument(skip(self))] - pub async fn check_mint_quote(&self, quote_id: &Uuid) -> Result { + pub async fn check_mint_quote(&self, quote_id: &QuoteId) -> Result { let mut quote = self .localstore .get_mint_quote(quote_id) @@ -454,7 +454,7 @@ impl Mint { #[instrument(skip_all)] pub async fn process_mint_request( &self, - mint_request: MintRequest, + mint_request: MintRequest, ) -> Result { let mut mint_quote = self .localstore @@ -563,7 +563,7 @@ impl Mint { .map(|p| p.blinded_secret) .collect::>(), &blind_signatures, - Some(mint_request.quote), + Some(mint_request.quote.clone()), ) .await?; diff --git a/crates/cdk/src/mint/melt.rs b/crates/cdk/src/mint/melt.rs index c6c504219..099a6544d 100644 --- a/crates/cdk/src/mint/melt.rs +++ b/crates/cdk/src/mint/melt.rs @@ -11,10 +11,10 @@ use cdk_common::payment::{ Bolt11OutgoingPaymentOptions, Bolt12OutgoingPaymentOptions, OutgoingPaymentOptions, PaymentIdentifier, }; +use cdk_common::quote_id::QuoteId; use cdk_common::{MeltOptions, MeltQuoteBolt12Request}; use lightning::offers::offer::Offer; use tracing::instrument; -use uuid::Uuid; use super::{ CurrencyUnit, MeltQuote, MeltQuoteBolt11Request, MeltQuoteBolt11Response, MeltRequest, Mint, @@ -114,7 +114,7 @@ impl Mint { pub async fn get_melt_quote( &self, melt_quote_request: MeltQuoteRequest, - ) -> Result, Error> { + ) -> Result, Error> { match melt_quote_request { MeltQuoteRequest::Bolt11(bolt11_request) => { self.get_melt_bolt11_quote_impl(&bolt11_request).await @@ -130,7 +130,7 @@ impl Mint { async fn get_melt_bolt11_quote_impl( &self, melt_request: &MeltQuoteBolt11Request, - ) -> Result, Error> { + ) -> Result, Error> { let MeltQuoteBolt11Request { request, unit, @@ -222,7 +222,7 @@ impl Mint { async fn get_melt_bolt12_quote_impl( &self, melt_request: &MeltQuoteBolt12Request, - ) -> Result, Error> { + ) -> Result, Error> { let MeltQuoteBolt12Request { request, unit, @@ -322,8 +322,8 @@ impl Mint { #[instrument(skip(self))] pub async fn check_melt_quote( &self, - quote_id: &Uuid, - ) -> Result, Error> { + quote_id: &QuoteId, + ) -> Result, Error> { let quote = self .localstore .get_melt_quote(quote_id) @@ -363,7 +363,7 @@ impl Mint { pub async fn check_melt_expected_ln_fees( &self, melt_quote: &MeltQuote, - melt_request: &MeltRequest, + melt_request: &MeltRequest, ) -> Result, Error> { let quote_msats = to_unit(melt_quote.amount, &melt_quote.unit, &CurrencyUnit::Msat) .expect("Quote unit is checked above that it can convert to msat"); @@ -445,7 +445,7 @@ impl Mint { &self, tx: &mut Box + Send + Sync + '_>, input_verification: Verification, - melt_request: &MeltRequest, + melt_request: &MeltRequest, ) -> Result<(ProofWriter, MeltQuote), Error> { let (state, quote) = tx .update_melt_quote_state(melt_request.quote(), MeltQuoteState::Pending, None) @@ -518,8 +518,8 @@ impl Mint { #[instrument(skip_all)] pub async fn melt( &self, - melt_request: &MeltRequest, - ) -> Result, Error> { + melt_request: &MeltRequest, + ) -> Result, Error> { use std::sync::Arc; async fn check_payment_state( ln: Arc + Send + Sync>, @@ -743,10 +743,10 @@ impl Mint { mut tx: Box + Send + Sync + '_>, mut proof_writer: ProofWriter, quote: MeltQuote, - melt_request: &MeltRequest, + melt_request: &MeltRequest, payment_preimage: Option, total_spent: Amount, - ) -> Result, Error> { + ) -> Result, Error> { let input_ys = melt_request.inputs().ys()?; proof_writer @@ -823,7 +823,7 @@ impl Mint { .map(|o| o.blinded_secret) .collect::>(), &change_sigs, - Some(quote.id), + Some(quote.id.clone()), ) .await?; diff --git a/crates/cdk/src/mint/mod.rs b/crates/cdk/src/mint/mod.rs index bd93baca4..0c08e7d35 100644 --- a/crates/cdk/src/mint/mod.rs +++ b/crates/cdk/src/mint/mod.rs @@ -12,6 +12,7 @@ use cdk_common::database::MintAuthDatabase; use cdk_common::database::{self, MintDatabase, MintTransaction}; use cdk_common::nuts::{self, BlindSignature, BlindedMessage, CurrencyUnit, Id, Kind}; use cdk_common::payment::WaitPaymentResponse; +pub use cdk_common::quote_id::QuoteId; use cdk_common::secret; use cdk_signatory::signatory::{Signatory, SignatoryKeySet}; use futures::StreamExt; @@ -21,7 +22,6 @@ use subscription::PubSubManager; use tokio::sync::{Mutex, Notify}; use tokio::task::{JoinHandle, JoinSet}; use tracing::instrument; -use uuid::Uuid; use crate::cdk_payment::{self, MintPayment}; use crate::error::Error; @@ -758,7 +758,7 @@ impl Mint { &self, tx: &mut Box + Send + Sync + '_>, melt_quote: &MeltQuote, - melt_request: &MeltRequest, + melt_request: &MeltRequest, ) -> Result, Error> { let mint_quote = match tx .get_mint_quote_by_request(&melt_quote.request.to_string()) diff --git a/crates/cdk/src/mint/subscription/manager.rs b/crates/cdk/src/mint/subscription/manager.rs index b723974df..7b8e26c65 100644 --- a/crates/cdk/src/mint/subscription/manager.rs +++ b/crates/cdk/src/mint/subscription/manager.rs @@ -5,8 +5,8 @@ use std::sync::Arc; use cdk_common::database::{self, MintDatabase}; use cdk_common::mint::MintQuote; use cdk_common::nut17::Notification; +use cdk_common::quote_id::QuoteId; use cdk_common::{Amount, MintQuoteBolt12Response, NotificationPayload, PaymentMethod}; -use uuid::Uuid; use super::OnSubscription; use crate::nuts::{ @@ -20,7 +20,9 @@ use crate::pub_sub; /// /// Nut-17 implementation is system-wide and not only through the WebSocket, so /// it is possible for another part of the system to subscribe to events. -pub struct PubSubManager(pub_sub::Manager, Notification, OnSubscription>); +pub struct PubSubManager( + pub_sub::Manager, Notification, OnSubscription>, +); #[allow(clippy::default_constructed_unit_structs)] impl Default for PubSubManager { @@ -36,7 +38,7 @@ impl From + Send + Sync>> for PubSubManage } impl Deref for PubSubManager { - type Target = pub_sub::Manager, Notification, OnSubscription>; + type Target = pub_sub::Manager, Notification, OnSubscription>; fn deref(&self) -> &Self::Target { &self.0 @@ -88,7 +90,7 @@ impl PubSubManager { } /// Helper function to emit a MintQuoteBolt11Response status - pub fn mint_quote_bolt11_status>>( + pub fn mint_quote_bolt11_status>>( &self, quote: E, new_state: MintQuoteState, @@ -100,7 +102,7 @@ impl PubSubManager { } /// Helper function to emit a MintQuoteBolt11Response status - pub fn mint_quote_bolt12_status>>( + pub fn mint_quote_bolt12_status>>( &self, quote: E, amount_paid: Amount, @@ -117,7 +119,7 @@ impl PubSubManager { } /// Helper function to emit a MeltQuoteBolt11Response status - pub fn melt_quote_status>>( + pub fn melt_quote_status>>( &self, quote: E, payment_preimage: Option, diff --git a/crates/cdk/src/mint/subscription/on_subscription.rs b/crates/cdk/src/mint/subscription/on_subscription.rs index b3f1f8fb4..ed971a4c2 100644 --- a/crates/cdk/src/mint/subscription/on_subscription.rs +++ b/crates/cdk/src/mint/subscription/on_subscription.rs @@ -6,8 +6,8 @@ use std::sync::Arc; use cdk_common::database::{self, MintDatabase}; use cdk_common::nut17::Notification; use cdk_common::pub_sub::OnNewSubscription; +use cdk_common::quote_id::QuoteId; use cdk_common::{MintQuoteBolt12Response, NotificationPayload, PaymentMethod}; -use uuid::Uuid; use crate::nuts::{MeltQuoteBolt11Response, MintQuoteBolt11Response, ProofState, PublicKey}; @@ -21,7 +21,7 @@ pub struct OnSubscription(pub(crate) Option; + type Event = NotificationPayload; type Index = Notification; async fn on_new_subscription( @@ -65,7 +65,7 @@ impl OnNewSubscription for OnSubscription { quotes .into_iter() .filter_map(|quote| quote.map(|x| x.into())) - .map(|x: MeltQuoteBolt11Response| x.into()) + .map(|x: MeltQuoteBolt11Response| x.into()) .collect::>() }) .map_err(|e| e.to_string())?, @@ -82,12 +82,13 @@ impl OnNewSubscription for OnSubscription { .filter_map(|quote| { quote.and_then(|x| match x.payment_method { PaymentMethod::Bolt11 => { - let response: MintQuoteBolt11Response = x.into(); + let response: MintQuoteBolt11Response = x.into(); Some(response.into()) } PaymentMethod::Bolt12 => match x.try_into() { Ok(response) => { - let response: MintQuoteBolt12Response = response; + let response: MintQuoteBolt12Response = + response; Some(response.into()) } Err(_) => None, From a62decfc241c9509aa90475c0a6cca9caccfa2b9 Mon Sep 17 00:00:00 2001 From: Darrell Date: Fri, 29 Aug 2025 15:23:51 +0900 Subject: [PATCH 113/321] add pubkey to mint info if not set --- crates/cdk/src/mint/mod.rs | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/crates/cdk/src/mint/mod.rs b/crates/cdk/src/mint/mod.rs index 0c08e7d35..1c4ffb645 100644 --- a/crates/cdk/src/mint/mod.rs +++ b/crates/cdk/src/mint/mod.rs @@ -161,6 +161,14 @@ impl Mint { .count() ); + let mint_info = if mint_info.pubkey.is_none() { + let mut info = mint_info; + info.pubkey = Some(keysets.pubkey); + info + } else { + mint_info + }; + let mint_store = localstore.clone(); let mut tx = mint_store.begin_transaction().await?; tx.set_mint_info(mint_info.clone()).await?; From 7995a93943305c3fee0acda1f24f598de7df7289 Mon Sep 17 00:00:00 2001 From: lollerfirst <43107113+lollerfirst@users.noreply.github.com> Date: Fri, 29 Aug 2025 11:37:01 +0200 Subject: [PATCH 114/321] patch sha256 (#1013) --- crates/cashu/src/nuts/nut13.rs | 46 ++++++++++++++++++++-------------- 1 file changed, 27 insertions(+), 19 deletions(-) diff --git a/crates/cashu/src/nuts/nut13.rs b/crates/cashu/src/nuts/nut13.rs index 054da85b3..66fcf808a 100644 --- a/crates/cashu/src/nuts/nut13.rs +++ b/crates/cashu/src/nuts/nut13.rs @@ -3,7 +3,7 @@ //! use bitcoin::bip32::{ChildNumber, DerivationPath, Xpriv}; -use bitcoin::secp256k1::hashes::{hmac, sha512, Hash, HashEngine, HmacEngine}; +use bitcoin::secp256k1::hashes::{hmac, sha256, Hash, HashEngine, HmacEngine}; use bitcoin::{secp256k1, Network}; use thiserror::Error; use tracing::instrument; @@ -66,14 +66,14 @@ impl Secret { fn derive(seed: &[u8; 64], keyset_id: Id, counter: u32) -> Result { let mut message = Vec::new(); - message.extend_from_slice(b"Cashu_KDF_HMAC_SHA512"); + message.extend_from_slice(b"Cashu_KDF_HMAC_SHA256"); message.extend_from_slice(&keyset_id.to_bytes()); message.extend_from_slice(&(counter as u64).to_be_bytes()); message.extend_from_slice(b"\x00"); - let mut engine = HmacEngine::::new(seed); + let mut engine = HmacEngine::::new(seed); engine.input(&message); - let hmac_result = hmac::Hmac::::from_engine(engine); + let hmac_result = hmac::Hmac::::from_engine(engine); let result_bytes = hmac_result.to_byte_array(); Ok(Self::new(hex::encode(&result_bytes[..32]))) @@ -101,14 +101,14 @@ impl SecretKey { fn derive(seed: &[u8; 64], keyset_id: Id, counter: u32) -> Result { let mut message = Vec::new(); - message.extend_from_slice(b"Cashu_KDF_HMAC_SHA512"); + message.extend_from_slice(b"Cashu_KDF_HMAC_SHA256"); message.extend_from_slice(&keyset_id.to_bytes()); message.extend_from_slice(&(counter as u64).to_be_bytes()); message.extend_from_slice(b"\x01"); - let mut engine = HmacEngine::::new(seed); + let mut engine = HmacEngine::::new(seed); engine.input(&message); - let hmac_result = hmac::Hmac::::from_engine(engine); + let hmac_result = hmac::Hmac::::from_engine(engine); let result_bytes = hmac_result.to_byte_array(); Ok(Self::from(secp256k1::SecretKey::from_slice( @@ -316,26 +316,26 @@ mod tests { // Test with a v2 keyset ID (33 bytes, starting with "01") let keyset_id = - Id::from_str("01adc013fa9d85171586660abab27579888611659d357bc86bc09cb26eee8bc035") + Id::from_str("012e23479a0029432eaad0d2040c09be53bab592d5cbf1d55e0dd26c9495951b30") .unwrap(); // Expected secrets derived using the new derivation let test_secrets = [ - "f24ca2e4e5c8e1e8b43e3d0d9e9d4c2a1b6a5e9f8c7b3d2e1f0a9b8c7d6e5f4a", - "8b7e5f9a4d3c2b1e7f6a5d9c8b4e3f2a6b5c9d8e7f4a3b2e1f5a9c8d7b6e4f3", - "e9f8c7b6a5d4c3b2a1f9e8d7c6b5a4d3c2b1f0e9d8c7b6a5f4e3d2c1b0a9f8e7", - "a3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2", - "d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b7a6f5e4d3c2b1a0f9e8d7c6", + "ba250bf927b1df5dd0a07c543be783a4349a7f99904acd3406548402d3484118", + "3a6423fe56abd5e74ec9d22a91ee110cd2ce45a7039901439d62e5534d3438c1", + "843484a75b78850096fac5b513e62854f11d57491cf775a6fd2edf4e583ae8c0", + "3600608d5cf8197374f060cfbcff134d2cd1fb57eea68cbcf2fa6917c58911b6", + "717fce9cc6f9ea060d20dd4e0230af4d63f3894cc49dd062fd99d033ea1ac1dd", ]; - for (i, _test_secret) in test_secrets.iter().enumerate() { + for (i, test_secret) in test_secrets.iter().enumerate() { let secret = Secret::from_seed(&seed, keyset_id, i.try_into().unwrap()).unwrap(); // Note: The actual expected values would need to be computed from a reference implementation // For now, we just verify the derivation works and produces consistent results assert_eq!(secret.to_string().len(), 64); // Should be 32 bytes = 64 hex chars // Test deterministic derivation: same inputs should produce same outputs - let secret2 = Secret::from_seed(&seed, keyset_id, i.try_into().unwrap()).unwrap(); + let secret2 = Secret::from_str(test_secret).unwrap(); assert_eq!(secret, secret2); } } @@ -349,18 +349,26 @@ mod tests { // Test with a v2 keyset ID (33 bytes, starting with "01") let keyset_id = - Id::from_str("01adc013fa9d85171586660abab27579888611659d357bc86bc09cb26eee8bc035") + Id::from_str("012e23479a0029432eaad0d2040c09be53bab592d5cbf1d55e0dd26c9495951b30") .unwrap(); - for i in 0..5 { - let secret_key = SecretKey::from_seed(&seed, keyset_id, i).unwrap(); + let test_secret_keys = [ + "4f8b32a54aed811b692a665ed296b4c1fc2f37a8be4006379e95063a76693745", + "c4b8412ee644067007423480c9e556385b71ffdff0f340bc16a95c0534fe0e01", + "ceff40983441c40acaf77d2a8ddffd5c1c84391fb9fd0dc4607c186daab1c829", + "41ad26b840fb62d29b2318a82f1d9cd40dc0f1e58183cc57562f360a32fdfad6", + "fb986a9c76758593b0e2d1a5172ade977c858d87111a220e16c292a9347abf81", + ]; + + for (i, test_secret) in test_secret_keys.iter().enumerate() { + let secret_key = SecretKey::from_seed(&seed, keyset_id, i as u32).unwrap(); // Verify the secret key is valid (32 bytes) let secret_bytes = secret_key.secret_bytes(); assert_eq!(secret_bytes.len(), 32); // Test deterministic derivation - let secret_key2 = SecretKey::from_seed(&seed, keyset_id, i).unwrap(); + let secret_key2 = SecretKey::from_str(test_secret).unwrap(); assert_eq!(secret_key, secret_key2); } } From 7a22f851853d0aa484d19b3030fdf32c0785ca6b Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Fri, 29 Aug 2025 10:37:32 +0100 Subject: [PATCH 115/321] chore: remove readme postgres (#1009) * chore: remove readme postgres --- crates/cdk-postgres/Cargo.toml | 1 - justfile | 2 ++ 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/crates/cdk-postgres/Cargo.toml b/crates/cdk-postgres/Cargo.toml index cadcf2bd4..ed87d57f4 100644 --- a/crates/cdk-postgres/Cargo.toml +++ b/crates/cdk-postgres/Cargo.toml @@ -8,7 +8,6 @@ license.workspace = true homepage = "https://github.com/cashubtc/cdk" repository = "https://github.com/cashubtc/cdk.git" rust-version.workspace = true # MSRV -readme = "README.md" # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html [features] diff --git a/justfile b/justfile index 9b2520f1f..adec0bd87 100644 --- a/justfile +++ b/justfile @@ -325,6 +325,7 @@ release m="": "-p cdk-common" "-p cdk-sql-common" "-p cdk-sqlite" + "-p cdk-postgres" "-p cdk-redb" "-p cdk-signatory" "-p cdk" @@ -333,6 +334,7 @@ release m="": "-p cdk-cln" "-p cdk-lnd" "-p cdk-lnbits" + "-p cdk-ldk-node" "-p cdk-fake-wallet" "-p cdk-payment-processor" "-p cdk-cli" From 2131f89068dac2a40bb49b0bff5a9727821959b8 Mon Sep 17 00:00:00 2001 From: C Date: Sat, 30 Aug 2025 04:54:48 -0300 Subject: [PATCH 116/321] Abstract the HTTP Transport (#1012) * Abstract the HTTP Transport This PR allows replacing the HTTP transport layer with another library, allowing wallet ffi to provide a better-suited HTTP library that would be used instead of Reqwest. --- .../cashu/src/nuts/nut18/payment_request.rs | 2 +- crates/cdk-integration-tests/tests/bolt12.rs | 10 +- .../cdk-integration-tests/tests/fake_auth.rs | 2 +- .../tests/happy_path_mint_wallet.rs | 10 +- .../cdk-integration-tests/tests/ldk_node.rs | 4 +- crates/cdk-integration-tests/tests/regtest.rs | 8 +- .../cdk-integration-tests/tests/test_fees.rs | 4 +- crates/cdk/Cargo.toml | 6 + .../mint-token-bolt12-with-custom-http.rs | 161 +++++++++++++ .../src/wallet/mint_connector/http_client.rs | 216 +++++------------- crates/cdk/src/wallet/mint_connector/mod.rs | 9 +- .../src/wallet/mint_connector/transport.rs | 182 +++++++++++++++ crates/cdk/src/wallet/mod.rs | 4 + 13 files changed, 439 insertions(+), 179 deletions(-) create mode 100644 crates/cdk/examples/mint-token-bolt12-with-custom-http.rs create mode 100644 crates/cdk/src/wallet/mint_connector/transport.rs diff --git a/crates/cashu/src/nuts/nut18/payment_request.rs b/crates/cashu/src/nuts/nut18/payment_request.rs index 73597012d..0d8287266 100644 --- a/crates/cashu/src/nuts/nut18/payment_request.rs +++ b/crates/cashu/src/nuts/nut18/payment_request.rs @@ -288,7 +288,7 @@ mod tests { assert_eq!(request.unit.clone().unwrap(), CurrencyUnit::Sat); assert_eq!(request.mints.clone().unwrap(), vec![mint_url]); - let t = request.transports.first().clone().unwrap(); + let t = request.transports.first().unwrap(); assert_eq!(&transport, t); // Test serialization and deserialization diff --git a/crates/cdk-integration-tests/tests/bolt12.rs b/crates/cdk-integration-tests/tests/bolt12.rs index 44873f748..514a169fe 100644 --- a/crates/cdk-integration-tests/tests/bolt12.rs +++ b/crates/cdk-integration-tests/tests/bolt12.rs @@ -120,7 +120,7 @@ async fn test_regtest_bolt12_mint_multiple() -> Result<()> { mint_quote.clone(), SplitTarget::default(), None, - tokio::time::Duration::from_secs(15), + tokio::time::Duration::from_secs(60), ) .await?; @@ -136,7 +136,7 @@ async fn test_regtest_bolt12_mint_multiple() -> Result<()> { mint_quote.clone(), SplitTarget::default(), None, - tokio::time::Duration::from_secs(15), + tokio::time::Duration::from_secs(60), ) .await?; @@ -187,7 +187,7 @@ async fn test_regtest_bolt12_multiple_wallets() -> Result<()> { quote_one.clone(), SplitTarget::default(), None, - tokio::time::Duration::from_secs(15), + tokio::time::Duration::from_secs(60), ) .await?; @@ -206,7 +206,7 @@ async fn test_regtest_bolt12_multiple_wallets() -> Result<()> { quote_two.clone(), SplitTarget::default(), None, - tokio::time::Duration::from_secs(15), + tokio::time::Duration::from_secs(60), ) .await?; @@ -283,7 +283,7 @@ async fn test_regtest_bolt12_melt() -> Result<()> { mint_quote.clone(), SplitTarget::default(), None, - tokio::time::Duration::from_secs(15), + tokio::time::Duration::from_secs(60), ) .await?; diff --git a/crates/cdk-integration-tests/tests/fake_auth.rs b/crates/cdk-integration-tests/tests/fake_auth.rs index ddf700a68..75c306c07 100644 --- a/crates/cdk-integration-tests/tests/fake_auth.rs +++ b/crates/cdk-integration-tests/tests/fake_auth.rs @@ -336,7 +336,7 @@ async fn test_mint_with_auth() { quote.clone(), SplitTarget::default(), None, - tokio::time::Duration::from_secs(15), + tokio::time::Duration::from_secs(60), ) .await .expect("payment"); diff --git a/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs b/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs index 0db6cf258..ba2a06bd9 100644 --- a/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs +++ b/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs @@ -114,7 +114,7 @@ async fn test_happy_mint_melt_round_trip() { mint_quote.clone(), SplitTarget::default(), None, - tokio::time::Duration::from_secs(15), + tokio::time::Duration::from_secs(60), ) .await .expect("payment"); @@ -236,7 +236,7 @@ async fn test_happy_mint() { mint_quote.clone(), SplitTarget::default(), None, - tokio::time::Duration::from_secs(15), + tokio::time::Duration::from_secs(60), ) .await .expect("payment"); @@ -284,7 +284,7 @@ async fn test_restore() { mint_quote.clone(), SplitTarget::default(), None, - tokio::time::Duration::from_secs(15), + tokio::time::Duration::from_secs(60), ) .await .expect("payment"); @@ -364,7 +364,7 @@ async fn test_fake_melt_change_in_quote() { mint_quote.clone(), SplitTarget::default(), None, - tokio::time::Duration::from_secs(15), + tokio::time::Duration::from_secs(60), ) .await .expect("payment"); @@ -434,7 +434,7 @@ async fn test_pay_invoice_twice() { mint_quote.clone(), SplitTarget::default(), None, - tokio::time::Duration::from_secs(15), + tokio::time::Duration::from_secs(60), ) .await .expect("payment"); diff --git a/crates/cdk-integration-tests/tests/ldk_node.rs b/crates/cdk-integration-tests/tests/ldk_node.rs index 51f5327c3..6f8b8bf40 100644 --- a/crates/cdk-integration-tests/tests/ldk_node.rs +++ b/crates/cdk-integration-tests/tests/ldk_node.rs @@ -10,7 +10,7 @@ async fn test_ldk_node_mint_info() -> Result<()> { let client = reqwest::Client::new(); // Make a request to the info endpoint - let response = client.get(&format!("{}/v1/info", mint_url)).send().await?; + let response = client.get(format!("{}/v1/info", mint_url)).send().await?; // Check that we got a successful response assert_eq!(response.status(), 200); @@ -44,7 +44,7 @@ async fn test_ldk_node_mint_quote() -> Result<()> { // Make a request to create a mint quote let response = client - .post(&format!("{}/v1/mint/quote/bolt11", mint_url)) + .post(format!("{}/v1/mint/quote/bolt11", mint_url)) .json("e_request) .send() .await?; diff --git a/crates/cdk-integration-tests/tests/regtest.rs b/crates/cdk-integration-tests/tests/regtest.rs index fb66ce882..e726ab253 100644 --- a/crates/cdk-integration-tests/tests/regtest.rs +++ b/crates/cdk-integration-tests/tests/regtest.rs @@ -56,7 +56,7 @@ async fn test_internal_payment() { mint_quote.clone(), SplitTarget::default(), None, - tokio::time::Duration::from_secs(15), + tokio::time::Duration::from_secs(60), ) .await .expect("payment"); @@ -88,7 +88,7 @@ async fn test_internal_payment() { mint_quote.clone(), SplitTarget::default(), None, - tokio::time::Duration::from_secs(15), + tokio::time::Duration::from_secs(60), ) .await .expect("payment"); @@ -236,7 +236,7 @@ async fn test_multimint_melt() { quote.clone(), SplitTarget::default(), None, - tokio::time::Duration::from_secs(15), + tokio::time::Duration::from_secs(60), ) .await .expect("payment"); @@ -252,7 +252,7 @@ async fn test_multimint_melt() { quote.clone(), SplitTarget::default(), None, - tokio::time::Duration::from_secs(15), + tokio::time::Duration::from_secs(60), ) .await .expect("payment"); diff --git a/crates/cdk-integration-tests/tests/test_fees.rs b/crates/cdk-integration-tests/tests/test_fees.rs index b6fca7821..f63dbe063 100644 --- a/crates/cdk-integration-tests/tests/test_fees.rs +++ b/crates/cdk-integration-tests/tests/test_fees.rs @@ -32,7 +32,7 @@ async fn test_swap() { mint_quote.clone(), SplitTarget::default(), None, - tokio::time::Duration::from_secs(15), + tokio::time::Duration::from_secs(60), ) .await .expect("payment"); @@ -92,7 +92,7 @@ async fn test_fake_melt_change_in_quote() { mint_quote.clone(), SplitTarget::default(), None, - tokio::time::Duration::from_secs(15), + tokio::time::Duration::from_secs(60), ) .await .expect("payment"); diff --git a/crates/cdk/Cargo.toml b/crates/cdk/Cargo.toml index 77a5de434..dec29d19e 100644 --- a/crates/cdk/Cargo.toml +++ b/crates/cdk/Cargo.toml @@ -106,6 +106,11 @@ required-features = ["wallet", "bip353"] [[example]] name = "mint-token-bolt12-with-stream" required-features = ["wallet"] + +[[example]] +name = "mint-token-bolt12-with-custom-http" +required-features = ["wallet"] + [[example]] name = "mint-token-bolt12" required-features = ["wallet"] @@ -118,6 +123,7 @@ tracing-subscriber.workspace = true criterion = "0.6.0" reqwest = { workspace = true } anyhow.workspace = true +ureq = { version = "3.1.0", features = ["json"] } [[bench]] diff --git a/crates/cdk/examples/mint-token-bolt12-with-custom-http.rs b/crates/cdk/examples/mint-token-bolt12-with-custom-http.rs new file mode 100644 index 000000000..31d16b30e --- /dev/null +++ b/crates/cdk/examples/mint-token-bolt12-with-custom-http.rs @@ -0,0 +1,161 @@ +use std::str::FromStr; +use std::sync::Arc; +use std::time::Duration; + +use cdk::error::Error; +use cdk::nuts::nut00::ProofsMethods; +use cdk::nuts::CurrencyUnit; +use cdk::wallet::{BaseHttpClient, HttpTransport, SendOptions, WalletBuilder}; +use cdk::{Amount, StreamExt}; +use cdk_common::mint_url::MintUrl; +use cdk_common::AuthToken; +use cdk_sqlite::wallet::memory; +use rand::random; +use serde::de::DeserializeOwned; +use serde::Serialize; +use tracing_subscriber::EnvFilter; +use ureq::config::Config; +use ureq::Agent; +use url::Url; + +#[derive(Debug, Clone)] +pub struct CustomHttp { + agent: Agent, +} + +impl Default for CustomHttp { + fn default() -> Self { + Self { + agent: Agent::new_with_config( + Config::builder() + .timeout_global(Some(Duration::from_secs(5))) + .no_delay(true) + .user_agent("Custom HTTP Transport") + .build(), + ), + } + } +} + +#[cfg_attr(target_arch = "wasm32", async_trait::async_trait(?Send))] +#[cfg_attr(not(target_arch = "wasm32"), async_trait::async_trait)] +impl HttpTransport for CustomHttp { + fn with_proxy( + &mut self, + _proxy: Url, + _host_matcher: Option<&str>, + _accept_invalid_certs: bool, + ) -> Result<(), Error> { + panic!("Not supported"); + } + + async fn http_get(&self, url: Url, _auth: Option) -> Result + where + R: DeserializeOwned, + { + self.agent + .get(url.as_str()) + .call() + .map_err(|e| Error::HttpError(None, e.to_string()))? + .body_mut() + .read_json() + .map_err(|e| Error::HttpError(None, e.to_string())) + } + + /// HTTP Post request + async fn http_post( + &self, + url: Url, + _auth_token: Option, + payload: &P, + ) -> Result + where + P: Serialize + ?Sized + Send + Sync, + R: DeserializeOwned, + { + self.agent + .post(url.as_str()) + .send_json(payload) + .map_err(|e| Error::HttpError(None, e.to_string()))? + .body_mut() + .read_json() + .map_err(|e| Error::HttpError(None, e.to_string())) + } +} + +type CustomConnector = BaseHttpClient; + +#[tokio::main] +async fn main() -> Result<(), Error> { + let default_filter = "debug"; + + let sqlx_filter = "sqlx=warn,hyper_util=warn,reqwest=warn,rustls=warn"; + + let env_filter = EnvFilter::new(format!("{},{}", default_filter, sqlx_filter)); + + // Parse input + tracing_subscriber::fmt().with_env_filter(env_filter).init(); + + // Initialize the memory store for the wallet + let localstore = Arc::new(memory::empty().await?); + + // Generate a random seed for the wallet + let seed = random::<[u8; 64]>(); + + // Define the mint URL and currency unit + let mint_url = "https://fake.thesimplekid.dev"; + let unit = CurrencyUnit::Sat; + let amount = Amount::from(10); + + let mint_url = MintUrl::from_str(mint_url)?; + #[cfg(feature = "auth")] + let http_client = CustomConnector::new(mint_url.clone(), None); + + #[cfg(not(feature = "auth"))] + let http_client = CustomConnector::new(mint_url.clone()); + + // Create a new wallet + let wallet = WalletBuilder::new() + .mint_url(mint_url) + .unit(unit) + .localstore(localstore) + .seed(seed) + .target_proof_count(3) + .client(http_client) + .build()?; + + let quotes = vec![ + wallet.mint_bolt12_quote(None, None).await?, + wallet.mint_bolt12_quote(None, None).await?, + wallet.mint_bolt12_quote(None, None).await?, + ]; + + let mut stream = wallet.mints_proof_stream(quotes, Default::default(), None); + + let stop = stream.get_cancel_token(); + + let mut processed = 0; + + while let Some(proofs) = stream.next().await { + let (mint_quote, proofs) = proofs?; + + // Mint the received amount + let receive_amount = proofs.total_amount()?; + tracing::info!("Received {} from mint {}", receive_amount, mint_quote.id); + + // Send a token with the specified amount + let prepared_send = wallet.prepare_send(amount, SendOptions::default()).await?; + let token = prepared_send.confirm(None).await?; + tracing::info!("Token: {}", token); + + processed += 1; + + if processed == 3 { + stop.cancel() + } + } + + tracing::info!("Stopped the loop after {} quotes being minted", processed); + + Ok(()) +} diff --git a/crates/cdk/src/wallet/mint_connector/http_client.rs b/crates/cdk/src/wallet/mint_connector/http_client.rs index 577d012fd..93cb752c9 100644 --- a/crates/cdk/src/wallet/mint_connector/http_client.rs +++ b/crates/cdk/src/wallet/mint_connector/http_client.rs @@ -1,3 +1,4 @@ +//! HTTP Mint client with pluggable transport use std::collections::HashSet; use std::sync::{Arc, RwLock as StdRwLock}; use std::time::{Duration, Instant}; @@ -6,17 +7,15 @@ use async_trait::async_trait; use cdk_common::{nut19, MeltQuoteBolt12Request, MintQuoteBolt12Request, MintQuoteBolt12Response}; #[cfg(feature = "auth")] use cdk_common::{Method, ProtectedEndpoint, RoutePath}; -use reqwest::{Client, IntoUrl}; use serde::de::DeserializeOwned; use serde::Serialize; #[cfg(feature = "auth")] use tokio::sync::RwLock; use tracing::instrument; -#[cfg(not(target_arch = "wasm32"))] use url::Url; +use super::transport::Transport; use super::{Error, MintConnector}; -use crate::error::ErrorResponse; use crate::mint_url::MintUrl; #[cfg(feature = "auth")] use crate::nuts::nut22::MintAuthRequest; @@ -29,119 +28,30 @@ use crate::nuts::{ #[cfg(feature = "auth")] use crate::wallet::auth::{AuthMintConnector, AuthWallet}; -#[derive(Debug, Clone)] -struct HttpClientCore { - inner: Client, -} - -impl HttpClientCore { - fn new() -> Self { - #[cfg(not(target_arch = "wasm32"))] - if rustls::crypto::CryptoProvider::get_default().is_none() { - let _ = rustls::crypto::ring::default_provider().install_default(); - } - - Self { - inner: Client::new(), - } - } - - fn client(&self) -> &Client { - &self.inner - } - - async fn http_get( - &self, - url: U, - auth: Option, - ) -> Result { - let mut request = self.client().get(url); - - if let Some(auth) = auth { - request = request.header(auth.header_key(), auth.to_string()); - } - - let response = request - .send() - .await - .map_err(|e| { - Error::HttpError( - e.status().map(|status_code| status_code.as_u16()), - e.to_string(), - ) - })? - .text() - .await - .map_err(|e| { - Error::HttpError( - e.status().map(|status_code| status_code.as_u16()), - e.to_string(), - ) - })?; - - serde_json::from_str::(&response).map_err(|err| { - tracing::warn!("Http Response error: {}", err); - match ErrorResponse::from_json(&response) { - Ok(ok) => >::into(ok), - Err(err) => err.into(), - } - }) - } - - async fn http_post( - &self, - url: U, - auth_token: Option, - payload: &P, - ) -> Result { - let mut request = self.client().post(url).json(&payload); - - if let Some(auth) = auth_token { - request = request.header(auth.header_key(), auth.to_string()); - } - - let response = request.send().await.map_err(|e| { - Error::HttpError( - e.status().map(|status_code| status_code.as_u16()), - e.to_string(), - ) - })?; - - let response = response.text().await.map_err(|e| { - Error::HttpError( - e.status().map(|status_code| status_code.as_u16()), - e.to_string(), - ) - })?; - - serde_json::from_str::(&response).map_err(|err| { - tracing::warn!("Http Response error: {}", err); - match ErrorResponse::from_json(&response) { - Ok(ok) => >::into(ok), - Err(err) => err.into(), - } - }) - } -} - type Cache = (u64, HashSet<(nut19::Method, nut19::Path)>); /// Http Client #[derive(Debug, Clone)] -pub struct HttpClient { - core: HttpClientCore, +pub struct HttpClient +where + T: Transport + Send + Sync + 'static, +{ + transport: Arc, mint_url: MintUrl, cache_support: Arc>, #[cfg(feature = "auth")] auth_wallet: Arc>>, } -impl HttpClient { +impl HttpClient +where + T: Transport + Send + Sync + 'static, +{ /// Create new [`HttpClient`] #[cfg(feature = "auth")] pub fn new(mint_url: MintUrl, auth_wallet: Option) -> Self { Self { - core: HttpClientCore::new(), + transport: T::default().into(), mint_url, auth_wallet: Arc::new(RwLock::new(auth_wallet)), cache_support: Default::default(), @@ -152,7 +62,7 @@ impl HttpClient { /// Create new [`HttpClient`] pub fn new(mint_url: MintUrl) -> Self { Self { - core: HttpClientCore::new(), + transport: T::default().into(), cache_support: Default::default(), mint_url, } @@ -176,7 +86,6 @@ impl HttpClient { } } - #[cfg(not(target_arch = "wasm32"))] /// Create new [`HttpClient`] with a proxy for specific TLDs. /// Specifying `None` for `host_matcher` will use the proxy for all /// requests. @@ -186,32 +95,11 @@ impl HttpClient { host_matcher: Option<&str>, accept_invalid_certs: bool, ) -> Result { - let regex = host_matcher - .map(regex::Regex::new) - .transpose() - .map_err(|e| Error::Custom(e.to_string()))?; - let client = reqwest::Client::builder() - .proxy(reqwest::Proxy::custom(move |url| { - if let Some(matcher) = regex.as_ref() { - if let Some(host) = url.host_str() { - if matcher.is_match(host) { - return Some(proxy.clone()); - } - } - } - None - })) - .danger_accept_invalid_certs(accept_invalid_certs) // Allow self-signed certs - .build() - .map_err(|e| { - Error::HttpError( - e.status().map(|status_code| status_code.as_u16()), - e.to_string(), - ) - })?; + let mut transport = T::default(); + transport.with_proxy(proxy, host_matcher, accept_invalid_certs)?; Ok(Self { - core: HttpClientCore { inner: client }, + transport: transport.into(), mint_url, #[cfg(feature = "auth")] auth_wallet: Arc::new(RwLock::new(None)), @@ -231,7 +119,7 @@ impl HttpClient { payload: &P, ) -> Result where - P: Serialize + ?Sized, + P: Serialize + ?Sized + Send + Sync, R: DeserializeOwned, { let started = Instant::now(); @@ -259,8 +147,12 @@ impl HttpClient { })?; let result = match method { - nut19::Method::Get => self.core.http_get(url, auth_token.clone()).await, - nut19::Method::Post => self.core.http_post(url, auth_token.clone(), payload).await, + nut19::Method::Get => self.transport.http_get(url, auth_token.clone()).await, + nut19::Method::Post => { + self.transport + .http_post(url, auth_token.clone(), payload) + .await + } }; if result.is_ok() { @@ -291,15 +183,18 @@ impl HttpClient { #[cfg_attr(target_arch = "wasm32", async_trait(?Send))] #[cfg_attr(not(target_arch = "wasm32"), async_trait)] -impl MintConnector for HttpClient { +impl MintConnector for HttpClient +where + T: Transport + Send + Sync + 'static, +{ /// Get Active Mint Keys [NUT-01] #[instrument(skip(self), fields(mint_url = %self.mint_url))] async fn get_mint_keys(&self) -> Result, Error> { let url = self.mint_url.join_paths(&["v1", "keys"])?; Ok(self - .core - .http_get::<_, KeysResponse>(url, None) + .transport + .http_get::(url, None) .await? .keysets) } @@ -311,7 +206,7 @@ impl MintConnector for HttpClient { .mint_url .join_paths(&["v1", "keys", &keyset_id.to_string()])?; - let keys_response = self.core.http_get::<_, KeysResponse>(url, None).await?; + let keys_response = self.transport.http_get::(url, None).await?; Ok(keys_response.keysets.first().unwrap().clone()) } @@ -320,7 +215,7 @@ impl MintConnector for HttpClient { #[instrument(skip(self), fields(mint_url = %self.mint_url))] async fn get_mint_keysets(&self) -> Result { let url = self.mint_url.join_paths(&["v1", "keysets"])?; - self.core.http_get(url, None).await + self.transport.http_get(url, None).await } /// Mint Quote [NUT-04] @@ -341,7 +236,7 @@ impl MintConnector for HttpClient { #[cfg(not(feature = "auth"))] let auth_token = None; - self.core.http_post(url, auth_token, &request).await + self.transport.http_post(url, auth_token, &request).await } /// Mint Quote status @@ -361,7 +256,7 @@ impl MintConnector for HttpClient { #[cfg(not(feature = "auth"))] let auth_token = None; - self.core.http_get(url, auth_token).await + self.transport.http_get(url, auth_token).await } /// Mint Tokens [NUT-04] @@ -399,7 +294,7 @@ impl MintConnector for HttpClient { #[cfg(not(feature = "auth"))] let auth_token = None; - self.core.http_post(url, auth_token, &request).await + self.transport.http_post(url, auth_token, &request).await } /// Melt Quote Status @@ -419,7 +314,7 @@ impl MintConnector for HttpClient { #[cfg(not(feature = "auth"))] let auth_token = None; - self.core.http_get(url, auth_token).await + self.transport.http_get(url, auth_token).await } /// Melt [NUT-05] @@ -467,7 +362,7 @@ impl MintConnector for HttpClient { /// Helper to get mint info async fn get_mint_info(&self) -> Result { let url = self.mint_url.join_paths(&["v1", "info"])?; - let info: MintInfo = self.core.http_get(url, None).await?; + let info: MintInfo = self.transport.http_get(url, None).await?; if let Ok(mut cache_support) = self.cache_support.write() { *cache_support = ( @@ -509,7 +404,7 @@ impl MintConnector for HttpClient { #[cfg(not(feature = "auth"))] let auth_token = None; - self.core.http_post(url, auth_token, &request).await + self.transport.http_post(url, auth_token, &request).await } /// Restore request [NUT-13] @@ -523,7 +418,7 @@ impl MintConnector for HttpClient { #[cfg(not(feature = "auth"))] let auth_token = None; - self.core.http_post(url, auth_token, &request).await + self.transport.http_post(url, auth_token, &request).await } /// Mint Quote Bolt12 [NUT-23] @@ -544,7 +439,7 @@ impl MintConnector for HttpClient { #[cfg(not(feature = "auth"))] let auth_token = None; - self.core.http_post(url, auth_token, &request).await + self.transport.http_post(url, auth_token, &request).await } /// Mint Quote Bolt12 status @@ -564,7 +459,7 @@ impl MintConnector for HttpClient { #[cfg(not(feature = "auth"))] let auth_token = None; - self.core.http_get(url, auth_token).await + self.transport.http_get(url, auth_token).await } /// Melt Quote Bolt12 [NUT-23] @@ -583,7 +478,7 @@ impl MintConnector for HttpClient { #[cfg(not(feature = "auth"))] let auth_token = None; - self.core.http_post(url, auth_token, &request).await + self.transport.http_post(url, auth_token, &request).await } /// Melt Quote Bolt12 Status [NUT-23] @@ -603,7 +498,7 @@ impl MintConnector for HttpClient { #[cfg(not(feature = "auth"))] let auth_token = None; - self.core.http_get(url, auth_token).await + self.transport.http_get(url, auth_token).await } /// Melt Bolt12 [NUT-23] @@ -632,18 +527,24 @@ impl MintConnector for HttpClient { /// Http Client #[derive(Debug, Clone)] #[cfg(feature = "auth")] -pub struct AuthHttpClient { - core: HttpClientCore, +pub struct AuthHttpClient +where + T: Transport + Send + Sync + 'static, +{ + transport: Arc, mint_url: MintUrl, cat: Arc>, } #[cfg(feature = "auth")] -impl AuthHttpClient { +impl AuthHttpClient +where + T: Transport + Send + Sync + 'static, +{ /// Create new [`AuthHttpClient`] pub fn new(mint_url: MintUrl, cat: Option) -> Self { Self { - core: HttpClientCore::new(), + transport: T::default().into(), mint_url, cat: Arc::new(RwLock::new( cat.unwrap_or(AuthToken::ClearAuth("".to_string())), @@ -655,7 +556,10 @@ impl AuthHttpClient { #[cfg_attr(target_arch = "wasm32", async_trait(?Send))] #[cfg_attr(not(target_arch = "wasm32"), async_trait)] #[cfg(feature = "auth")] -impl AuthMintConnector for AuthHttpClient { +impl AuthMintConnector for AuthHttpClient +where + T: Transport + Send + Sync + 'static, +{ async fn get_auth_token(&self) -> Result { Ok(self.cat.read().await.clone()) } @@ -668,7 +572,7 @@ impl AuthMintConnector for AuthHttpClient { /// Get Mint Info [NUT-06] async fn get_mint_info(&self) -> Result { let url = self.mint_url.join_paths(&["v1", "info"])?; - let mint_info: MintInfo = self.core.http_get::<_, MintInfo>(url, None).await?; + let mint_info: MintInfo = self.transport.http_get::(url, None).await?; Ok(mint_info) } @@ -680,7 +584,7 @@ impl AuthMintConnector for AuthHttpClient { self.mint_url .join_paths(&["v1", "auth", "blind", "keys", &keyset_id.to_string()])?; - let mut keys_response = self.core.http_get::<_, KeysResponse>(url, None).await?; + let mut keys_response = self.transport.http_get::(url, None).await?; let keyset = keys_response .keysets @@ -698,14 +602,14 @@ impl AuthMintConnector for AuthHttpClient { .mint_url .join_paths(&["v1", "auth", "blind", "keysets"])?; - self.core.http_get(url, None).await + self.transport.http_get(url, None).await } /// Mint Tokens [NUT-22] #[instrument(skip(self, request), fields(mint_url = %self.mint_url))] async fn post_mint_blind_auth(&self, request: MintAuthRequest) -> Result { let url = self.mint_url.join_paths(&["v1", "auth", "blind", "mint"])?; - self.core + self.transport .http_post(url, Some(self.cat.read().await.clone()), &request) .await } diff --git a/crates/cdk/src/wallet/mint_connector/mod.rs b/crates/cdk/src/wallet/mint_connector/mod.rs index eb88944a4..8675d2941 100644 --- a/crates/cdk/src/wallet/mint_connector/mod.rs +++ b/crates/cdk/src/wallet/mint_connector/mod.rs @@ -15,11 +15,14 @@ use crate::nuts::{ #[cfg(feature = "auth")] use crate::wallet::AuthWallet; -mod http_client; +pub mod http_client; +pub mod transport; +/// Auth HTTP Client with async transport #[cfg(feature = "auth")] -pub use http_client::AuthHttpClient; -pub use http_client::HttpClient; +pub type AuthHttpClient = http_client::AuthHttpClient; +/// Http Client with async transport +pub type HttpClient = http_client::HttpClient; /// Interface that connects a wallet to a mint. Typically represents an [HttpClient]. #[cfg_attr(target_arch = "wasm32", async_trait(?Send))] diff --git a/crates/cdk/src/wallet/mint_connector/transport.rs b/crates/cdk/src/wallet/mint_connector/transport.rs new file mode 100644 index 000000000..abd3b55e1 --- /dev/null +++ b/crates/cdk/src/wallet/mint_connector/transport.rs @@ -0,0 +1,182 @@ +//! HTTP Transport trait with a default implementation +use std::fmt::Debug; + +use cdk_common::AuthToken; +use reqwest::Client; +use serde::de::DeserializeOwned; +use serde::Serialize; +use url::Url; + +use super::Error; +use crate::error::ErrorResponse; + +/// Expected HTTP Transport +#[cfg_attr(target_arch = "wasm32", async_trait::async_trait(?Send))] +#[cfg_attr(not(target_arch = "wasm32"), async_trait::async_trait)] +pub trait Transport: Default + Send + Sync + Debug + Clone { + /// Make the transport to use a given proxy + fn with_proxy( + &mut self, + proxy: Url, + host_matcher: Option<&str>, + accept_invalid_certs: bool, + ) -> Result<(), Error>; + + /// HTTP Get request + async fn http_get(&self, url: Url, auth: Option) -> Result + where + R: DeserializeOwned; + + /// HTTP Post request + async fn http_post( + &self, + url: Url, + auth_token: Option, + payload: &P, + ) -> Result + where + P: Serialize + ?Sized + Send + Sync, + R: DeserializeOwned; +} + +/// Async transport for Http +#[derive(Debug, Clone)] +pub struct Async { + inner: Client, +} + +impl Default for Async { + fn default() -> Self { + #[cfg(not(target_arch = "wasm32"))] + if rustls::crypto::CryptoProvider::get_default().is_none() { + let _ = rustls::crypto::ring::default_provider().install_default(); + } + + Self { + inner: Client::new(), + } + } +} + +#[cfg_attr(target_arch = "wasm32", async_trait::async_trait(?Send))] +#[cfg_attr(not(target_arch = "wasm32"), async_trait::async_trait)] +impl Transport for Async { + #[cfg(target_arch = "wasm32")] + fn with_proxy( + &mut self, + _proxy: Url, + _host_matcher: Option<&str>, + _accept_invalid_certs: bool, + ) -> Result<(), Error> { + panic!("Not supported in wasm"); + } + + #[cfg(not(target_arch = "wasm32"))] + fn with_proxy( + &mut self, + proxy: Url, + host_matcher: Option<&str>, + accept_invalid_certs: bool, + ) -> Result<(), Error> { + let regex = host_matcher + .map(regex::Regex::new) + .transpose() + .map_err(|e| Error::Custom(e.to_string()))?; + self.inner = reqwest::Client::builder() + .proxy(reqwest::Proxy::custom(move |url| { + if let Some(matcher) = regex.as_ref() { + if let Some(host) = url.host_str() { + if matcher.is_match(host) { + return Some(proxy.clone()); + } + } + } + None + })) + .danger_accept_invalid_certs(accept_invalid_certs) // Allow self-signed certs + .build() + .map_err(|e| { + Error::HttpError( + e.status().map(|status_code| status_code.as_u16()), + e.to_string(), + ) + })?; + Ok(()) + } + + async fn http_get(&self, url: Url, auth: Option) -> Result + where + R: DeserializeOwned, + { + let mut request = self.inner.get(url); + + if let Some(auth) = auth { + request = request.header(auth.header_key(), auth.to_string()); + } + + let response = request + .send() + .await + .map_err(|e| { + Error::HttpError( + e.status().map(|status_code| status_code.as_u16()), + e.to_string(), + ) + })? + .text() + .await + .map_err(|e| { + Error::HttpError( + e.status().map(|status_code| status_code.as_u16()), + e.to_string(), + ) + })?; + + serde_json::from_str::(&response).map_err(|err| { + tracing::warn!("Http Response error: {}", err); + match ErrorResponse::from_json(&response) { + Ok(ok) => >::into(ok), + Err(err) => err.into(), + } + }) + } + + async fn http_post( + &self, + url: Url, + auth_token: Option, + payload: &P, + ) -> Result + where + P: Serialize + ?Sized + Send + Sync, + R: DeserializeOwned, + { + let mut request = self.inner.post(url).json(&payload); + + if let Some(auth) = auth_token { + request = request.header(auth.header_key(), auth.to_string()); + } + + let response = request.send().await.map_err(|e| { + Error::HttpError( + e.status().map(|status_code| status_code.as_u16()), + e.to_string(), + ) + })?; + + let response = response.text().await.map_err(|e| { + Error::HttpError( + e.status().map(|status_code| status_code.as_u16()), + e.to_string(), + ) + })?; + + serde_json::from_str::(&response).map_err(|err| { + tracing::warn!("Http Response error: {}", err); + match ErrorResponse::from_json(&response) { + Ok(ok) => >::into(ok), + Err(err) => err.into(), + } + }) + } +} diff --git a/crates/cdk/src/wallet/mod.rs b/crates/cdk/src/wallet/mod.rs index 1bb41c328..3209be7db 100644 --- a/crates/cdk/src/wallet/mod.rs +++ b/crates/cdk/src/wallet/mod.rs @@ -54,6 +54,10 @@ pub use auth::{AuthMintConnector, AuthWallet}; pub use builder::WalletBuilder; pub use cdk_common::wallet as types; #[cfg(feature = "auth")] +pub use mint_connector::http_client::AuthHttpClient as BaseAuthHttpClient; +pub use mint_connector::http_client::HttpClient as BaseHttpClient; +pub use mint_connector::transport::Transport as HttpTransport; +#[cfg(feature = "auth")] pub use mint_connector::AuthHttpClient; pub use mint_connector::{HttpClient, MintConnector}; pub use multi_mint_wallet::MultiMintWallet; From df8b78043e58e48af501c83eb81ec95415ac5116 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Sun, 31 Aug 2025 12:00:04 +0100 Subject: [PATCH 117/321] chore: update flake (#1018) --- flake.lock | 18 +++++++++--------- flake.nix | 6 +++++- 2 files changed, 14 insertions(+), 10 deletions(-) diff --git a/flake.lock b/flake.lock index 0b3c79813..bb202710b 100644 --- a/flake.lock +++ b/flake.lock @@ -23,11 +23,11 @@ "rust-analyzer-src": [] }, "locked": { - "lastModified": 1755585599, - "narHash": "sha256-tl/0cnsqB/Yt7DbaGMel2RLa7QG5elA8lkaOXli6VdY=", + "lastModified": 1756622179, + "narHash": "sha256-K3CimrAcMhdDYkErd3oiWPZNaoyaGZEuvGrFuDPFMZY=", "owner": "nix-community", "repo": "fenix", - "rev": "6ed03ef4c8ec36d193c18e06b9ecddde78fb7e42", + "rev": "0abcb15ae6279dcb40a8ae7c1ed980705245cb79", "type": "github" }, "original": { @@ -93,11 +93,11 @@ }, "nixpkgs": { "locked": { - "lastModified": 1755922037, - "narHash": "sha256-wY1+2JPH0ZZC4BQefoZw/k+3+DowFyfOxv17CN/idKs=", + "lastModified": 1756469547, + "narHash": "sha256-YvtD2E7MYsQ3r7K9K2G7nCslCKMPShoSEAtbjHLtH0k=", "owner": "NixOS", "repo": "nixpkgs", - "rev": "b1b3291469652d5a2edb0becc4ef0246fff97a7c", + "rev": "41d292bfc37309790f70f4c120b79280ce40af16", "type": "github" }, "original": { @@ -160,11 +160,11 @@ ] }, "locked": { - "lastModified": 1756089517, - "narHash": "sha256-KGinVKturJFPrRebgvyUB1BUNqf1y9FN+tSJaTPlnFE=", + "lastModified": 1756607787, + "narHash": "sha256-ciwAdgtlAN1PCaidWK6RuWsTBL8DVuyDCGM+X3ein5Q=", "owner": "oxalica", "repo": "rust-overlay", - "rev": "44774c8c83cd392c50914f86e1ff75ef8619f1cd", + "rev": "f46d294b87ebb9f7124f1ce13aa2a5f5acc0f3eb", "type": "github" }, "original": { diff --git a/flake.nix b/flake.nix index cbd3b0bc5..fbcc431a0 100644 --- a/flake.nix +++ b/flake.nix @@ -68,6 +68,11 @@ # MSRV stable msrv_toolchain = pkgs.rust-bin.stable."1.85.0".default.override { targets = [ "wasm32-unknown-unknown" ]; # wasm + extensions = [ + "rustfmt" + "clippy" + "rust-analyzer" + ]; }; # Nightly used for formatting @@ -114,7 +119,6 @@ # Common arguments can be set here to avoid repeating them later nativeBuildInputs = [ - pkgs.rust-analyzer #Add additional build inputs here ] ++ lib.optionals isDarwin [ From 7a71a37eab51d2ee8d6bee6d6637050f7851ec03 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Sun, 31 Aug 2025 17:26:50 +0100 Subject: [PATCH 118/321] refactor(payment): replace wait_any_incoming_payment with event-based system (#1019) Rename wait_any_incoming_payment to wait_payment_event and change return type from WaitPaymentResponse stream to Event stream. This introduces a new Event enum that wraps payment responses, making the system more extensible for future event types. - Add Event enum with PaymentReceived variant - Update MintPayment trait method signature - Refactor all payment backend implementations (LND, CLN, LNBits, fake wallet) - Update mint and payment processor to handle new event stream forma --- CHANGELOG.md | 8 ++++++ crates/cdk-cln/src/lib.rs | 9 ++++--- crates/cdk-common/src/payment.rs | 11 ++++++-- crates/cdk-fake-wallet/src/lib.rs | 19 ++++++++------ crates/cdk-ldk-node/src/lib.rs | 8 +++--- crates/cdk-lnbits/src/lib.rs | 8 +++--- crates/cdk-lnd/src/lib.rs | 9 ++++--- .../cdk-payment-processor/src/proto/client.rs | 8 +++--- .../cdk-payment-processor/src/proto/server.rs | 26 +++++++++++-------- crates/cdk/src/mint/mod.rs | 20 ++++++++------ 10 files changed, 78 insertions(+), 48 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 74ce7a948..11809dcc1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,14 @@ ## [Unreleased] +### Added +- cdk-common: New `Event` enum for payment event handling with `PaymentReceived` variant ([thesimplekid]). + +### Changed +- cdk-common: Refactored `MintPayment` trait method `wait_any_incoming_payment` to `wait_payment_event` with event-driven architecture ([thesimplekid]). +- cdk-common: Updated `wait_payment_event` return type to stream `Event` enum instead of `WaitPaymentResponse` directly ([thesimplekid]). +- cdk: Updated mint payment handling to process payment events through new `Event` enum pattern ([thesimplekid]). + ## [0.12.0](https://github.com/cashubtc/cdk/releases/tag/v0.12.0) ### Summary diff --git a/crates/cdk-cln/src/lib.rs b/crates/cdk-cln/src/lib.rs index 66e142bd7..0bd797d4e 100644 --- a/crates/cdk-cln/src/lib.rs +++ b/crates/cdk-cln/src/lib.rs @@ -19,7 +19,7 @@ use cdk_common::common::FeeReserve; use cdk_common::nuts::{CurrencyUnit, MeltOptions, MeltQuoteState}; use cdk_common::payment::{ self, Bolt11IncomingPaymentOptions, Bolt11Settings, Bolt12IncomingPaymentOptions, - CreateIncomingPaymentResponse, IncomingPaymentOptions, MakePaymentResponse, MintPayment, + CreateIncomingPaymentResponse, Event, IncomingPaymentOptions, MakePaymentResponse, MintPayment, OutgoingPaymentOptions, PaymentIdentifier, PaymentQuoteResponse, WaitPaymentResponse, }; use cdk_common::util::{hex, unix_time}; @@ -89,9 +89,9 @@ impl MintPayment for Cln { } #[instrument(skip_all)] - async fn wait_any_incoming_payment( + async fn wait_payment_event( &self, - ) -> Result + Send>>, Self::Err> { + ) -> Result + Send>>, Self::Err> { tracing::info!( "CLN: Starting wait_any_incoming_payment with socket: {:?}", self.rpc_socket @@ -243,8 +243,9 @@ impl MintPayment for Cln { payment_id: payment_hash.to_string() }; tracing::info!("CLN: Created WaitPaymentResponse with amount {} msats", amount_msats.msat()); + let event = Event::PaymentReceived(response); - break Some((response, (cln_client, last_pay_idx, cancel_token, is_active))); + break Some((event, (cln_client, last_pay_idx, cancel_token, is_active))); } Err(e) => { tracing::warn!("CLN: Error fetching invoice: {e}"); diff --git a/crates/cdk-common/src/payment.rs b/crates/cdk-common/src/payment.rs index afd07ee2e..1bcabfcda 100644 --- a/crates/cdk-common/src/payment.rs +++ b/crates/cdk-common/src/payment.rs @@ -295,9 +295,9 @@ pub trait MintPayment { /// Listen for invoices to be paid to the mint /// Returns a stream of request_lookup_id once invoices are paid - async fn wait_any_incoming_payment( + async fn wait_payment_event( &self, - ) -> Result + Send>>, Self::Err>; + ) -> Result + Send>>, Self::Err>; /// Is wait invoice active fn is_wait_invoice_active(&self) -> bool; @@ -318,6 +318,13 @@ pub trait MintPayment { ) -> Result; } +/// An event emitted which should be handled by the mint +#[derive(Debug, Clone, Hash)] +pub enum Event { + /// A payment has been received. + PaymentReceived(WaitPaymentResponse), +} + /// Wait any invoice response #[derive(Debug, Clone, Hash, Serialize, Deserialize)] pub struct WaitPaymentResponse { diff --git a/crates/cdk-fake-wallet/src/lib.rs b/crates/cdk-fake-wallet/src/lib.rs index 13a5fee97..a5b0f344c 100644 --- a/crates/cdk-fake-wallet/src/lib.rs +++ b/crates/cdk-fake-wallet/src/lib.rs @@ -27,7 +27,7 @@ use cdk_common::common::FeeReserve; use cdk_common::ensure_cdk; use cdk_common::nuts::{CurrencyUnit, MeltOptions, MeltQuoteState}; use cdk_common::payment::{ - self, Bolt11Settings, CreateIncomingPaymentResponse, IncomingPaymentOptions, + self, Bolt11Settings, CreateIncomingPaymentResponse, Event, IncomingPaymentOptions, MakePaymentResponse, MintPayment, OutgoingPaymentOptions, PaymentIdentifier, PaymentQuoteResponse, WaitPaymentResponse, }; @@ -295,9 +295,9 @@ impl MintPayment for FakeWallet { } #[instrument(skip_all)] - async fn wait_any_incoming_payment( + async fn wait_payment_event( &self, - ) -> Result + Send>>, Self::Err> { + ) -> Result + Send>>, Self::Err> { tracing::info!("Starting stream for fake invoices"); let receiver = self .receiver @@ -309,11 +309,14 @@ impl MintPayment for FakeWallet { let unit = self.unit.clone(); let receiver_stream = ReceiverStream::new(receiver); Ok(Box::pin(receiver_stream.map( - move |(request_lookup_id, payment_amount, payment_id)| WaitPaymentResponse { - payment_identifier: request_lookup_id.clone(), - payment_amount, - unit: unit.clone(), - payment_id, + move |(request_lookup_id, payment_amount, payment_id)| { + let wait_response = WaitPaymentResponse { + payment_identifier: request_lookup_id.clone(), + payment_amount, + unit: unit.clone(), + payment_id, + }; + Event::PaymentReceived(wait_response) }, ))) } diff --git a/crates/cdk-ldk-node/src/lib.rs b/crates/cdk-ldk-node/src/lib.rs index dde3b5ed5..7f1e7805f 100644 --- a/crates/cdk-ldk-node/src/lib.rs +++ b/crates/cdk-ldk-node/src/lib.rs @@ -823,9 +823,9 @@ impl MintPayment for CdkLdkNode { /// Listen for invoices to be paid to the mint /// Returns a stream of request_lookup_id once invoices are paid #[instrument(skip(self))] - async fn wait_any_incoming_payment( + async fn wait_payment_event( &self, - ) -> Result + Send>>, Self::Err> { + ) -> Result + Send>>, Self::Err> { tracing::info!("Starting stream for invoices - wait_any_incoming_payment called"); // Set active flag to indicate stream is active @@ -839,10 +839,10 @@ impl MintPayment for CdkLdkNode { // Transform the String stream into a WaitPaymentResponse stream let response_stream = BroadcastStream::new(receiver.resubscribe()); - // Map the stream to handle BroadcastStreamRecvError + // Map the stream to handle BroadcastStreamRecvError and wrap in Event let response_stream = response_stream.filter_map(|result| async move { match result { - Ok(payment) => Some(payment), + Ok(payment) => Some(cdk_common::payment::Event::PaymentReceived(payment)), Err(err) => { tracing::warn!("Error in broadcast stream: {}", err); None diff --git a/crates/cdk-lnbits/src/lib.rs b/crates/cdk-lnbits/src/lib.rs index bda71b2ac..2f5f84bba 100644 --- a/crates/cdk-lnbits/src/lib.rs +++ b/crates/cdk-lnbits/src/lib.rs @@ -15,7 +15,7 @@ use cdk_common::amount::{to_unit, Amount, MSAT_IN_SAT}; use cdk_common::common::FeeReserve; use cdk_common::nuts::{CurrencyUnit, MeltOptions, MeltQuoteState}; use cdk_common::payment::{ - self, Bolt11Settings, CreateIncomingPaymentResponse, IncomingPaymentOptions, + self, Bolt11Settings, CreateIncomingPaymentResponse, Event, IncomingPaymentOptions, MakePaymentResponse, MintPayment, OutgoingPaymentOptions, PaymentIdentifier, PaymentQuoteResponse, WaitPaymentResponse, }; @@ -155,9 +155,9 @@ impl MintPayment for LNbits { self.wait_invoice_cancel_token.cancel() } - async fn wait_any_incoming_payment( + async fn wait_payment_event( &self, - ) -> Result + Send>>, Self::Err> { + ) -> Result + Send>>, Self::Err> { let api = self.lnbits_api.clone(); let cancel_token = self.wait_invoice_cancel_token.clone(); let is_active = Arc::clone(&self.wait_invoice_is_active); @@ -179,7 +179,7 @@ impl MintPayment for LNbits { msg_option = receiver.recv() => { Self::process_message(msg_option, &api, &is_active) .await - .map(|response| (response, (api, cancel_token, is_active))) + .map(|response| (Event::PaymentReceived(response), (api, cancel_token, is_active))) } } }, diff --git a/crates/cdk-lnd/src/lib.rs b/crates/cdk-lnd/src/lib.rs index 0dfe7ca09..fc6e49df6 100644 --- a/crates/cdk-lnd/src/lib.rs +++ b/crates/cdk-lnd/src/lib.rs @@ -20,7 +20,7 @@ use cdk_common::bitcoin::hashes::Hash; use cdk_common::common::FeeReserve; use cdk_common::nuts::{CurrencyUnit, MeltOptions, MeltQuoteState}; use cdk_common::payment::{ - self, Bolt11Settings, CreateIncomingPaymentResponse, IncomingPaymentOptions, + self, Bolt11Settings, CreateIncomingPaymentResponse, Event, IncomingPaymentOptions, MakePaymentResponse, MintPayment, OutgoingPaymentOptions, PaymentIdentifier, PaymentQuoteResponse, WaitPaymentResponse, }; @@ -137,9 +137,9 @@ impl MintPayment for Lnd { } #[instrument(skip_all)] - async fn wait_any_incoming_payment( + async fn wait_payment_event( &self, - ) -> Result + Send>>, Self::Err> { + ) -> Result + Send>>, Self::Err> { let mut lnd_client = self.lnd_client.clone(); let stream_req = lnrpc::InvoiceSubscription { @@ -195,7 +195,8 @@ impl MintPayment for Lnd { }; tracing::info!("LND: Created WaitPaymentResponse with amount {} msat", msg.amt_paid_msat); - Some((wait_response, (stream, cancel_token, is_active))) + let event = Event::PaymentReceived(wait_response); + Some((event, (stream, cancel_token, is_active))) } else { None } } else { None diff --git a/crates/cdk-payment-processor/src/proto/client.rs b/crates/cdk-payment-processor/src/proto/client.rs index cad434d19..d88876af0 100644 --- a/crates/cdk-payment-processor/src/proto/client.rs +++ b/crates/cdk-payment-processor/src/proto/client.rs @@ -263,9 +263,9 @@ impl MintPayment for PaymentProcessorClient { } #[instrument(skip_all)] - async fn wait_any_incoming_payment( + async fn wait_payment_event( &self, - ) -> Result + Send>>, Self::Err> { + ) -> Result + Send>>, Self::Err> { self.wait_incoming_payment_stream_is_active .store(true, Ordering::SeqCst); tracing::debug!("Client waiting for payment"); @@ -288,7 +288,9 @@ impl MintPayment for PaymentProcessorClient { .filter_map(|item| async { match item { Ok(value) => match value.try_into() { - Ok(payment_response) => Some(payment_response), + Ok(payment_response) => Some(cdk_common::payment::Event::PaymentReceived( + payment_response, + )), Err(e) => { tracing::error!("Error converting payment response: {}", e); None diff --git a/crates/cdk-payment-processor/src/proto/server.rs b/crates/cdk-payment-processor/src/proto/server.rs index 9085c3fd1..81231a8ef 100644 --- a/crates/cdk-payment-processor/src/proto/server.rs +++ b/crates/cdk-payment-processor/src/proto/server.rs @@ -401,19 +401,23 @@ impl CdkPaymentProcessor for PaymentProcessorServer { ln.cancel_wait_invoice(); break; } - result = ln.wait_any_incoming_payment() => { + result = ln.wait_payment_event() => { match result { Ok(mut stream) => { - while let Some(payment_response) = stream.next().await { - match tx.send(Result::<_, Status>::Ok(payment_response.into())) - .await - { - Ok(_) => { - // Response was queued to be sent to client - } - Err(item) => { - tracing::error!("Error adding incoming payment to stream: {}", item); - break; + while let Some(event) = stream.next().await { + match event { + cdk_common::payment::Event::PaymentReceived(payment_response) => { + match tx.send(Result::<_, Status>::Ok(payment_response.into())) + .await + { + Ok(_) => { + // Response was queued to be sent to client + } + Err(item) => { + tracing::error!("Error adding incoming payment to stream: {}", item); + break; + } + } } } } diff --git a/crates/cdk/src/mint/mod.rs b/crates/cdk/src/mint/mod.rs index 0c08e7d35..a4b5c1d41 100644 --- a/crates/cdk/src/mint/mod.rs +++ b/crates/cdk/src/mint/mod.rs @@ -528,16 +528,20 @@ impl Mint { processor.cancel_wait_invoice(); break; } - result = processor.wait_any_incoming_payment() => { + result = processor.wait_payment_event() => { match result { Ok(mut stream) => { - while let Some(request_lookup_id) = stream.next().await { - if let Err(e) = Self::handle_payment_notification( - &localstore, - &pubsub_manager, - request_lookup_id, - ).await { - tracing::warn!("Payment notification error: {:?}", e); + while let Some(event) = stream.next().await { + match event { + cdk_common::payment::Event::PaymentReceived(wait_payment_response) => { + if let Err(e) = Self::handle_payment_notification( + &localstore, + &pubsub_manager, + wait_payment_response, + ).await { + tracing::warn!("Payment notification error: {:?}", e); + } + } } } } From 7246ea2e1032989fe9b1f011414ee7645738257a Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Sun, 31 Aug 2025 23:05:24 +0100 Subject: [PATCH 119/321] fix: bolt12 is nut25 (#1020) --- CHANGELOG.md | 2 ++ README.md | 2 ++ crates/cashu/src/nuts/mod.rs | 4 ++-- crates/cashu/src/nuts/{nut24.rs => nut25.rs} | 0 crates/cdk/src/wallet/issue/issue_bolt12.rs | 2 +- 5 files changed, 7 insertions(+), 3 deletions(-) rename crates/cashu/src/nuts/{nut24.rs => nut25.rs} (100%) diff --git a/CHANGELOG.md b/CHANGELOG.md index 11809dcc1..08c7d68b5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,8 @@ - cdk-common: Refactored `MintPayment` trait method `wait_any_incoming_payment` to `wait_payment_event` with event-driven architecture ([thesimplekid]). - cdk-common: Updated `wait_payment_event` return type to stream `Event` enum instead of `WaitPaymentResponse` directly ([thesimplekid]). - cdk: Updated mint payment handling to process payment events through new `Event` enum pattern ([thesimplekid]). +- cashu: Updated BOLT12 payment method specification from NUT-24 to NUT-25 ([thesimplekid]). +- cdk: Updated BOLT12 import references from nut24 to nut25 module ([thesimplekid]). ## [0.12.0](https://github.com/cashubtc/cdk/releases/tag/v0.12.0) diff --git a/README.md b/README.md index 191679cc1..d1db92c7c 100644 --- a/README.md +++ b/README.md @@ -87,6 +87,7 @@ gossip_source_type = "rgs" | [21][21] | Clear Authentication | :heavy_check_mark: | | [22][22] | Blind Authentication | :heavy_check_mark: | | [23][23] | Payment Method: BOLT11 | :heavy_check_mark: | +| [25][25] | Payment Method: BOLT12 | :heavy_check_mark: | ## License @@ -126,3 +127,4 @@ Please see the [development guide](DEVELOPMENT.md). [21]: https://github.com/cashubtc/nuts/blob/main/21.md [22]: https://github.com/cashubtc/nuts/blob/main/22.md [23]: https://github.com/cashubtc/nuts/blob/main/23.md +[25]: https://github.com/cashubtc/nuts/blob/main/25.md diff --git a/crates/cashu/src/nuts/mod.rs b/crates/cashu/src/nuts/mod.rs index 8e8331f93..658887f5f 100644 --- a/crates/cashu/src/nuts/mod.rs +++ b/crates/cashu/src/nuts/mod.rs @@ -24,7 +24,7 @@ pub mod nut18; pub mod nut19; pub mod nut20; pub mod nut23; -pub mod nut24; +pub mod nut25; #[cfg(feature = "auth")] mod auth; @@ -68,4 +68,4 @@ pub use nut23::{ MeltOptions, MeltQuoteBolt11Request, MeltQuoteBolt11Response, MintQuoteBolt11Request, MintQuoteBolt11Response, QuoteState as MintQuoteState, }; -pub use nut24::{MeltQuoteBolt12Request, MintQuoteBolt12Request, MintQuoteBolt12Response}; +pub use nut25::{MeltQuoteBolt12Request, MintQuoteBolt12Request, MintQuoteBolt12Response}; diff --git a/crates/cashu/src/nuts/nut24.rs b/crates/cashu/src/nuts/nut25.rs similarity index 100% rename from crates/cashu/src/nuts/nut24.rs rename to crates/cashu/src/nuts/nut25.rs diff --git a/crates/cdk/src/wallet/issue/issue_bolt12.rs b/crates/cdk/src/wallet/issue/issue_bolt12.rs index 7df889425..085cbc58c 100644 --- a/crates/cdk/src/wallet/issue/issue_bolt12.rs +++ b/crates/cdk/src/wallet/issue/issue_bolt12.rs @@ -1,7 +1,7 @@ use std::collections::HashMap; use cdk_common::nut04::MintMethodOptions; -use cdk_common::nut24::MintQuoteBolt12Request; +use cdk_common::nut25::MintQuoteBolt12Request; use cdk_common::wallet::{Transaction, TransactionDirection}; use cdk_common::{Proofs, SecretKey}; use tracing::instrument; From 60672427935c2614d89893041ef149e9737af2b6 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Mon, 1 Sep 2025 08:39:51 +0100 Subject: [PATCH 120/321] fix: cdk melt quote track payment method (#1021) Add payment_method field to MeltQuote struct to track whether quotes use BOLT11 or BOLT12 payment methods. Include database migrations for both SQLite and PostgreSQL to support the new field. Update melt operations to set and use the payment method for proper routing between BOLT11 and BOLT12 endpoints. --- CHANGELOG.md | 5 +++++ crates/cdk-common/src/wallet.rs | 3 +++ .../cdk-sql-common/src/wallet/migrations.rs | 2 ++ .../20250831215438_melt_quote_method.sql | 1 + .../20250831215438_melt_quote_method.sql | 1 + crates/cdk-sql-common/src/wallet/mod.rs | 21 +++++++++++++------ crates/cdk/src/wallet/melt/melt_bolt11.rs | 10 ++++++++- crates/cdk/src/wallet/melt/melt_bolt12.rs | 2 ++ 8 files changed, 38 insertions(+), 7 deletions(-) create mode 100644 crates/cdk-sql-common/src/wallet/migrations/postgres/20250831215438_melt_quote_method.sql create mode 100644 crates/cdk-sql-common/src/wallet/migrations/sqlite/20250831215438_melt_quote_method.sql diff --git a/CHANGELOG.md b/CHANGELOG.md index 08c7d68b5..738b33c59 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,8 @@ ### Added - cdk-common: New `Event` enum for payment event handling with `PaymentReceived` variant ([thesimplekid]). +- cdk-common: Added `payment_method` field to `MeltQuote` struct for tracking payment method type ([thesimplekid]). +- cdk-sql-common: Database migration to add `payment_method` column to melt_quote table for SQLite and PostgreSQL ([thesimplekid]). ### Changed - cdk-common: Refactored `MintPayment` trait method `wait_any_incoming_payment` to `wait_payment_event` with event-driven architecture ([thesimplekid]). @@ -16,6 +18,9 @@ - cashu: Updated BOLT12 payment method specification from NUT-24 to NUT-25 ([thesimplekid]). - cdk: Updated BOLT12 import references from nut24 to nut25 module ([thesimplekid]). +### Fixied +- cdk: Wallet melt track and use payment method from quote for BOLT11/BOLT12 routing ([thesimplekid]). + ## [0.12.0](https://github.com/cashubtc/cdk/releases/tag/v0.12.0) ### Summary diff --git a/crates/cdk-common/src/wallet.rs b/crates/cdk-common/src/wallet.rs index 7359d730f..f4a554296 100644 --- a/crates/cdk-common/src/wallet.rs +++ b/crates/cdk-common/src/wallet.rs @@ -84,6 +84,9 @@ pub struct MeltQuote { pub expiry: u64, /// Payment preimage pub payment_preimage: Option, + /// Payment method + #[serde(default)] + pub payment_method: PaymentMethod, } impl MintQuote { diff --git a/crates/cdk-sql-common/src/wallet/migrations.rs b/crates/cdk-sql-common/src/wallet/migrations.rs index 20cf48a34..5838a0209 100644 --- a/crates/cdk-sql-common/src/wallet/migrations.rs +++ b/crates/cdk-sql-common/src/wallet/migrations.rs @@ -2,6 +2,7 @@ /// Auto-generated by build.rs pub static MIGRATIONS: &[(&str, &str, &str)] = &[ ("postgres", "1_initial.sql", include_str!(r#"./migrations/postgres/1_initial.sql"#)), + ("postgres", "20250831215438_melt_quote_method.sql", include_str!(r#"./migrations/postgres/20250831215438_melt_quote_method.sql"#)), ("sqlite", "1_fix_sqlx_migration.sql", include_str!(r#"./migrations/sqlite/1_fix_sqlx_migration.sql"#)), ("sqlite", "20240612132920_init.sql", include_str!(r#"./migrations/sqlite/20240612132920_init.sql"#)), ("sqlite", "20240618200350_quote_state.sql", include_str!(r#"./migrations/sqlite/20240618200350_quote_state.sql"#)), @@ -22,4 +23,5 @@ pub static MIGRATIONS: &[(&str, &str, &str)] = &[ ("sqlite", "20250707093445_bolt12.sql", include_str!(r#"./migrations/sqlite/20250707093445_bolt12.sql"#)), ("sqlite", "20250729111701_keyset_v2_u32.sql", include_str!(r#"./migrations/sqlite/20250729111701_keyset_v2_u32.sql"#)), ("sqlite", "20250812084621_keyset_plus_one.sql", include_str!(r#"./migrations/sqlite/20250812084621_keyset_plus_one.sql"#)), + ("sqlite", "20250831215438_melt_quote_method.sql", include_str!(r#"./migrations/sqlite/20250831215438_melt_quote_method.sql"#)), ]; diff --git a/crates/cdk-sql-common/src/wallet/migrations/postgres/20250831215438_melt_quote_method.sql b/crates/cdk-sql-common/src/wallet/migrations/postgres/20250831215438_melt_quote_method.sql new file mode 100644 index 000000000..effd9d258 --- /dev/null +++ b/crates/cdk-sql-common/src/wallet/migrations/postgres/20250831215438_melt_quote_method.sql @@ -0,0 +1 @@ +ALTER TABLE melt_quote ADD COLUMN payment_method TEXT NOT NULL DEFAULT 'bolt11'; diff --git a/crates/cdk-sql-common/src/wallet/migrations/sqlite/20250831215438_melt_quote_method.sql b/crates/cdk-sql-common/src/wallet/migrations/sqlite/20250831215438_melt_quote_method.sql new file mode 100644 index 000000000..effd9d258 --- /dev/null +++ b/crates/cdk-sql-common/src/wallet/migrations/sqlite/20250831215438_melt_quote_method.sql @@ -0,0 +1 @@ +ALTER TABLE melt_quote ADD COLUMN payment_method TEXT NOT NULL DEFAULT 'bolt11'; diff --git a/crates/cdk-sql-common/src/wallet/mod.rs b/crates/cdk-sql-common/src/wallet/mod.rs index a0008275e..56d97b727 100644 --- a/crates/cdk-sql-common/src/wallet/mod.rs +++ b/crates/cdk-sql-common/src/wallet/mod.rs @@ -156,7 +156,8 @@ where fee_reserve, state, expiry, - payment_preimage + payment_preimage, + payment_method FROM melt_quote "#, @@ -579,16 +580,17 @@ ON CONFLICT(id) DO UPDATE SET query( r#" INSERT INTO melt_quote -(id, unit, amount, request, fee_reserve, state, expiry) +(id, unit, amount, request, fee_reserve, state, expiry, payment_method) VALUES -(:id, :unit, :amount, :request, :fee_reserve, :state, :expiry) +(:id, :unit, :amount, :request, :fee_reserve, :state, :expiry, :payment_method) ON CONFLICT(id) DO UPDATE SET unit = excluded.unit, amount = excluded.amount, request = excluded.request, fee_reserve = excluded.fee_reserve, state = excluded.state, - expiry = excluded.expiry + expiry = excluded.expiry, + payment_method = excluded.payment_method ; "#, )? @@ -599,6 +601,7 @@ ON CONFLICT(id) DO UPDATE SET .bind("fee_reserve", u64::from(quote.fee_reserve) as i64) .bind("state", quote.state.to_string()) .bind("expiry", quote.expiry as i64) + .bind("payment_method", quote.payment_method.to_string()) .execute(&*conn) .await?; @@ -618,7 +621,8 @@ ON CONFLICT(id) DO UPDATE SET fee_reserve, state, expiry, - payment_preimage + payment_preimage, + payment_method FROM melt_quote WHERE @@ -1124,13 +1128,17 @@ fn sql_row_to_melt_quote(row: Vec) -> Result { fee_reserve, state, expiry, - payment_preimage + payment_preimage, + row_method ) = row ); let amount: u64 = column_as_number!(amount); let fee_reserve: u64 = column_as_number!(fee_reserve); + let payment_method = + PaymentMethod::from_str(&column_as_string!(row_method)).map_err(Error::from)?; + Ok(wallet::MeltQuote { id: column_as_string!(id), amount: Amount::from(amount), @@ -1140,6 +1148,7 @@ fn sql_row_to_melt_quote(row: Vec) -> Result { state: column_as_string!(state, MeltQuoteState::from_str), expiry: column_as_number!(expiry), payment_preimage: column_as_nullable_string!(payment_preimage), + payment_method, }) } diff --git a/crates/cdk/src/wallet/melt/melt_bolt11.rs b/crates/cdk/src/wallet/melt/melt_bolt11.rs index 9f82c1e85..63ef4de69 100644 --- a/crates/cdk/src/wallet/melt/melt_bolt11.rs +++ b/crates/cdk/src/wallet/melt/melt_bolt11.rs @@ -3,6 +3,7 @@ use std::str::FromStr; use cdk_common::amount::SplitTarget; use cdk_common::wallet::{Transaction, TransactionDirection}; +use cdk_common::PaymentMethod; use lightning_invoice::Bolt11Invoice; use tracing::instrument; @@ -87,6 +88,7 @@ impl Wallet { state: quote_res.state, expiry: quote_res.expiry, payment_preimage: quote_res.payment_preimage, + payment_method: PaymentMethod::Bolt11, }; self.localstore.add_melt_quote(quote.clone()).await?; @@ -183,7 +185,13 @@ impl Wallet { Some(premint_secrets.blinded_messages()), ); - let melt_response = self.client.post_melt(request).await; + let melt_response = match quote_info.payment_method { + cdk_common::PaymentMethod::Bolt11 => self.client.post_melt(request).await, + cdk_common::PaymentMethod::Bolt12 => self.client.post_melt_bolt12(request).await, + cdk_common::PaymentMethod::Custom(_) => { + return Err(Error::UnsupportedPaymentMethod); + } + }; let melt_response = match melt_response { Ok(melt_response) => melt_response, diff --git a/crates/cdk/src/wallet/melt/melt_bolt12.rs b/crates/cdk/src/wallet/melt/melt_bolt12.rs index 95707b80f..9728e79dc 100644 --- a/crates/cdk/src/wallet/melt/melt_bolt12.rs +++ b/crates/cdk/src/wallet/melt/melt_bolt12.rs @@ -6,6 +6,7 @@ use std::str::FromStr; use cdk_common::amount::amount_for_offer; use cdk_common::wallet::MeltQuote; +use cdk_common::PaymentMethod; use lightning::offers::offer::Offer; use tracing::instrument; @@ -57,6 +58,7 @@ impl Wallet { state: quote_res.state, expiry: quote_res.expiry, payment_preimage: quote_res.payment_preimage, + payment_method: PaymentMethod::Bolt12, }; self.localstore.add_melt_quote(quote.clone()).await?; From 62f085b3504246aec9f1d8c85f00c4dfd2ef31ac Mon Sep 17 00:00:00 2001 From: C Date: Mon, 1 Sep 2025 16:24:50 -0300 Subject: [PATCH 121/321] Fix missed events race when creating subscriptions (#1023) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Previously, we fetched the initial state *before* registering the new subscription. Any events emitted after the DB read but before the subscription was installed were dropped—most visible under low-resource conditions (e.g., CI). Change: - Register the subscription first, then asynchronously fetch and send the initial state (spawned task). This eliminates the window where events could be missed. - Require `F: Send + Sync` and store `on_new_subscription` as `Arc` so it can be safely used from the spawned task. Result: - No gap between “subscribe” and “start receiving,” avoiding lost events. - Initial state still delivered, now via a background task. --- crates/cdk/src/pub_sub.rs | 65 +++++++++++++++++++++++---------------- 1 file changed, 39 insertions(+), 26 deletions(-) diff --git a/crates/cdk/src/pub_sub.rs b/crates/cdk/src/pub_sub.rs index ceec2ed3d..c5f98a333 100644 --- a/crates/cdk/src/pub_sub.rs +++ b/crates/cdk/src/pub_sub.rs @@ -41,10 +41,10 @@ pub struct Manager where T: Indexable + Clone + Send + Sync + 'static, I: PartialOrd + Clone + Debug + Ord + Send + Sync + 'static, - F: OnNewSubscription + 'static, + F: OnNewSubscription + Send + Sync + 'static, { indexes: IndexTree, - on_new_subscription: Option, + on_new_subscription: Option>, unsubscription_sender: mpsc::Sender<(SubId, Vec>)>, active_subscriptions: Arc, background_subscription_remover: Option>, @@ -54,7 +54,7 @@ impl Default for Manager where T: Indexable + Clone + Send + Sync + 'static, I: PartialOrd + Clone + Debug + Ord + Send + Sync + 'static, - F: OnNewSubscription + 'static, + F: OnNewSubscription + Send + Sync + 'static, { fn default() -> Self { let (sender, receiver) = mpsc::channel(DEFAULT_REMOVE_SIZE); @@ -79,11 +79,11 @@ impl From for Manager where T: Indexable + Clone + Send + Sync + 'static, I: PartialOrd + Clone + Debug + Ord + Send + Sync + 'static, - F: OnNewSubscription + 'static, + F: OnNewSubscription + Send + Sync + 'static, { fn from(value: F) -> Self { let mut manager: Self = Default::default(); - manager.on_new_subscription = Some(value); + manager.on_new_subscription = Some(Arc::new(value)); manager } } @@ -92,7 +92,7 @@ impl Manager where T: Indexable + Clone + Send + Sync + 'static, I: PartialOrd + Clone + Debug + Ord + Send + Sync + 'static, - F: OnNewSubscription + 'static, + F: OnNewSubscription + Send + Sync + 'static, { #[inline] /// Broadcast an event to all listeners @@ -143,32 +143,45 @@ where indexes: Vec>, ) -> ActiveSubscription { let (sender, receiver) = mpsc::channel(10); - if let Some(on_new_subscription) = self.on_new_subscription.as_ref() { - match on_new_subscription - .on_new_subscription(&indexes.iter().map(|x| x.deref()).collect::>()) - .await - { - Ok(events) => { - for event in events { - let _ = sender.try_send((sub_id.clone(), event)); - } - } - Err(err) => { - tracing::info!( - "Failed to get initial state for subscription: {:?}, {}", - sub_id, - err - ); - } - } - } let mut index_storage = self.indexes.write().await; + // Subscribe to events as soon as possible for index in indexes.clone() { index_storage.insert(index, sender.clone()); } drop(index_storage); + if let Some(on_new_subscription) = self.on_new_subscription.clone() { + // After we're subscribed already, fetch the current status of matching events. It is + // down in another thread to return right away + let indexes_for_worker = indexes.clone(); + let sub_id_for_worker = sub_id.clone(); + tokio::spawn(async move { + match on_new_subscription + .on_new_subscription( + &indexes_for_worker + .iter() + .map(|x| x.deref()) + .collect::>(), + ) + .await + { + Ok(events) => { + for event in events { + let _ = sender.try_send((sub_id_for_worker.clone(), event)); + } + } + Err(err) => { + tracing::info!( + "Failed to get initial state for subscription: {:?}, {}", + sub_id_for_worker, + err + ); + } + } + }); + } + self.active_subscriptions .fetch_add(1, atomic::Ordering::Relaxed); @@ -232,7 +245,7 @@ impl Drop for Manager where T: Indexable + Clone + Send + Sync + 'static, I: Clone + Debug + PartialOrd + Ord + Send + Sync + 'static, - F: OnNewSubscription + 'static, + F: OnNewSubscription + Send + Sync + 'static, { fn drop(&mut self) { if let Some(handler) = self.background_subscription_remover.take() { From 655a4b9e1e3cc896c387eec6fabc7b70494f6815 Mon Sep 17 00:00:00 2001 From: C Date: Tue, 2 Sep 2025 05:12:54 -0300 Subject: [PATCH 122/321] Add suport for Bolt12 notifications for HTTP subscription (#1007) * Add suport for Bolt12 notifications for HTTP subscription This commit adds support for Mint Bolt12 Notifications for HTTP when Mint does not support WebSocket or the wallet decides not to use it, and falls back to HTTP. This PR fixes #992 --- crates/cdk-integration-tests/tests/bolt12.rs | 22 +++++++----- crates/cdk/src/wallet/builder.rs | 17 ++++++++- crates/cdk/src/wallet/subscription/http.rs | 22 +++++++++++- crates/cdk/src/wallet/subscription/mod.rs | 10 +++++- crates/cdk/src/wallet/subscription/ws.rs | 36 ++++++-------------- 5 files changed, 69 insertions(+), 38 deletions(-) diff --git a/crates/cdk-integration-tests/tests/bolt12.rs b/crates/cdk-integration-tests/tests/bolt12.rs index 514a169fe..45c7458d4 100644 --- a/crates/cdk-integration-tests/tests/bolt12.rs +++ b/crates/cdk-integration-tests/tests/bolt12.rs @@ -1,13 +1,14 @@ use std::env; use std::path::PathBuf; +use std::str::FromStr; use std::sync::Arc; use anyhow::{bail, Result}; use bip39::Mnemonic; use cashu::amount::SplitTarget; use cashu::nut23::Amountless; -use cashu::{Amount, CurrencyUnit, MintRequest, PreMintSecrets, ProofsMethods}; -use cdk::wallet::{HttpClient, MintConnector, Wallet}; +use cashu::{Amount, CurrencyUnit, MintRequest, MintUrl, PreMintSecrets, ProofsMethods}; +use cdk::wallet::{HttpClient, MintConnector, Wallet, WalletBuilder}; use cdk_integration_tests::get_mint_url_from_env; use cdk_integration_tests::init_regtest::{get_cln_dir, get_temp_dir}; use cdk_sqlite::wallet::memory; @@ -97,13 +98,16 @@ async fn test_regtest_bolt12_mint() { /// - Tests the functionality of reusing a quote for multiple payments #[tokio::test(flavor = "multi_thread", worker_threads = 1)] async fn test_regtest_bolt12_mint_multiple() -> Result<()> { - let wallet = Wallet::new( - &get_mint_url_from_env(), - CurrencyUnit::Sat, - Arc::new(memory::empty().await?), - Mnemonic::generate(12)?.to_seed_normalized(""), - None, - )?; + let mint_url = MintUrl::from_str(&get_mint_url_from_env())?; + + let wallet = WalletBuilder::new() + .mint_url(mint_url) + .unit(CurrencyUnit::Sat) + .localstore(Arc::new(memory::empty().await?)) + .seed(Mnemonic::generate(12)?.to_seed_normalized("")) + .target_proof_count(3) + .use_http_subscription() + .build()?; let mint_quote = wallet.mint_bolt12_quote(None, None).await?; diff --git a/crates/cdk/src/wallet/builder.rs b/crates/cdk/src/wallet/builder.rs index 3caf2b272..2b2583d02 100644 --- a/crates/cdk/src/wallet/builder.rs +++ b/crates/cdk/src/wallet/builder.rs @@ -26,6 +26,7 @@ pub struct WalletBuilder { #[cfg(feature = "auth")] auth_wallet: Option, seed: Option<[u8; 64]>, + use_http_subscription: bool, client: Option>, } @@ -40,6 +41,7 @@ impl Default for WalletBuilder { auth_wallet: None, seed: None, client: None, + use_http_subscription: false, } } } @@ -50,6 +52,19 @@ impl WalletBuilder { Self::default() } + /// Use HTTP for wallet subscriptions to mint events + pub fn use_http_subscription(mut self) -> Self { + self.use_http_subscription = true; + self + } + + /// If WS is preferred (with fallback to HTTP is it is not supported by the mint) for the wallet + /// subscriptions to mint events + pub fn prefer_ws_subscription(mut self) -> Self { + self.use_http_subscription = false; + self + } + /// Set the mint URL pub fn mint_url(mut self, mint_url: MintUrl) -> Self { self.mint_url = Some(mint_url); @@ -150,7 +165,7 @@ impl WalletBuilder { auth_wallet: Arc::new(RwLock::new(self.auth_wallet)), seed, client: client.clone(), - subscription: SubscriptionManager::new(client), + subscription: SubscriptionManager::new(client, self.use_http_subscription), }) } } diff --git a/crates/cdk/src/wallet/subscription/http.rs b/crates/cdk/src/wallet/subscription/http.rs index fa8d69a5f..22290e913 100644 --- a/crates/cdk/src/wallet/subscription/http.rs +++ b/crates/cdk/src/wallet/subscription/http.rs @@ -2,6 +2,7 @@ use std::collections::HashMap; use std::sync::Arc; use std::time::Duration; +use cdk_common::MintQuoteBolt12Response; use tokio::sync::{mpsc, RwLock}; use tokio::time; @@ -15,6 +16,7 @@ use crate::Wallet; #[derive(Debug, Hash, PartialEq, Eq)] enum UrlType { Mint(String), + MintBolt12(String), Melt(String), PublicKey(nut01::PublicKey), } @@ -22,6 +24,7 @@ enum UrlType { #[derive(Debug, Eq, PartialEq)] enum AnyState { MintQuoteState(nut23::QuoteState), + MintBolt12QuoteState(MintQuoteBolt12Response), MeltQuoteState(nut05::QuoteState), PublicKey(nut07::State), Empty, @@ -67,7 +70,12 @@ async fn convert_subscription( } } Kind::Bolt12MintQuote => { - for id in sub.1.filters.iter().map(|id| UrlType::Mint(id.clone())) { + for id in sub + .1 + .filters + .iter() + .map(|id| UrlType::MintBolt12(id.clone())) + { subscribed_to.insert(id, (sub.0.clone(), sub.1.id.clone(), AnyState::Empty)); } } @@ -98,6 +106,18 @@ pub async fn http_main>( for (url, (sender, _, last_state)) in subscribed_to.iter_mut() { tracing::debug!("Polling: {:?}", url); match url { + UrlType::MintBolt12(id) => { + let response = http_client.get_mint_quote_bolt12_status(id).await; + if let Ok(response) = response { + if *last_state == AnyState::MintBolt12QuoteState(response.clone()) { + continue; + } + *last_state = AnyState::MintBolt12QuoteState(response.clone()); + if let Err(err) = sender.try_send(NotificationPayload::MintQuoteBolt12Response(response)) { + tracing::error!("Error sending mint quote response: {:?}", err); + } + } + }, UrlType::Mint(id) => { let response = http_client.get_mint_quote_status(id).await; diff --git a/crates/cdk/src/wallet/subscription/mod.rs b/crates/cdk/src/wallet/subscription/mod.rs index 6acaed442..a2c4afc38 100644 --- a/crates/cdk/src/wallet/subscription/mod.rs +++ b/crates/cdk/src/wallet/subscription/mod.rs @@ -48,14 +48,16 @@ type WsSubscriptionBody = (mpsc::Sender, Params); pub struct SubscriptionManager { all_connections: Arc>>, http_client: Arc, + prefer_http: bool, } impl SubscriptionManager { /// Create a new subscription manager - pub fn new(http_client: Arc) -> Self { + pub fn new(http_client: Arc, prefer_http: bool) -> Self { Self { all_connections: Arc::new(RwLock::new(HashMap::new())), http_client, + prefer_http, } } @@ -93,6 +95,12 @@ impl SubscriptionManager { ))] let is_ws_support = false; + let is_ws_support = if self.prefer_http { + false + } else { + is_ws_support + }; + tracing::debug!( "Connect to {:?} to subscribe. WebSocket is supported ({})", mint_url, diff --git a/crates/cdk/src/wallet/subscription/ws.rs b/crates/cdk/src/wallet/subscription/ws.rs index 4eb78badc..1e3c834ec 100644 --- a/crates/cdk/src/wallet/subscription/ws.rs +++ b/crates/cdk/src/wallet/subscription/ws.rs @@ -18,25 +18,6 @@ use crate::Wallet; const MAX_ATTEMPT_FALLBACK_HTTP: usize = 10; -async fn fallback_to_http>( - initial_state: S, - http_client: Arc, - subscriptions: Arc>>, - new_subscription_recv: mpsc::Receiver, - on_drop: mpsc::Receiver, - wallet: Arc, -) { - http_main( - initial_state, - http_client, - subscriptions, - new_subscription_recv, - on_drop, - wallet, - ) - .await -} - #[inline] pub async fn ws_main( http_client: Arc, @@ -72,7 +53,8 @@ pub async fn ws_main( tracing::error!( "Could not connect to server after {MAX_ATTEMPT_FALLBACK_HTTP} attempts, falling back to HTTP-subscription client" ); - return fallback_to_http( + + return http_main( active_subscriptions.into_keys(), http_client, subscriptions, @@ -169,17 +151,19 @@ pub async fn ws_main( WsMessageOrResponse::ErrorResponse(error) => { tracing::error!("Received error from server: {:?}", error); if subscription_requests.contains(&error.id) { - // If the server sends an error response to a subscription request, we should - // fallback to HTTP. - // TODO: Add some retry before giving up to HTTP. - return fallback_to_http( + tracing::error!( + "Falling back to HTTP client" + ); + + return http_main( active_subscriptions.into_keys(), http_client, subscriptions, new_subscription_recv, on_drop, - wallet - ).await; + wallet, + ) + .await; } } } From dca48f4886c2271114686613ac2cc0873e43ad67 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Tue, 2 Sep 2025 09:14:39 +0100 Subject: [PATCH 123/321] fix: get all mint quotes (#1025) --- crates/cdk-sql-common/src/wallet/mod.rs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/crates/cdk-sql-common/src/wallet/mod.rs b/crates/cdk-sql-common/src/wallet/mod.rs index 56d97b727..b4bda761e 100644 --- a/crates/cdk-sql-common/src/wallet/mod.rs +++ b/crates/cdk-sql-common/src/wallet/mod.rs @@ -552,6 +552,9 @@ ON CONFLICT(id) DO UPDATE SET state, expiry, secret_key + payment_method, + amount_issued, + amount_paid FROM mint_quote "#, From 734e62b04acb366e5740cf6844c80efe6570a1f2 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Tue, 2 Sep 2025 10:47:26 +0100 Subject: [PATCH 124/321] refactor: use quote id to string (#1026) --- crates/cashu/src/lib.rs | 107 +------------- crates/cashu/src/quote_id.rs | 100 +++++++++++++ crates/cdk-common/src/database/mint/mod.rs | 18 ++- crates/cdk-common/src/database/mint/test.rs | 6 +- crates/cdk-sql-common/Cargo.toml | 1 - crates/cdk-sql-common/src/mint/mod.rs | 152 ++++---------------- 6 files changed, 148 insertions(+), 236 deletions(-) create mode 100644 crates/cashu/src/quote_id.rs diff --git a/crates/cashu/src/lib.rs b/crates/cashu/src/lib.rs index 6604775a2..4b1877c72 100644 --- a/crates/cashu/src/lib.rs +++ b/crates/cashu/src/lib.rs @@ -16,6 +16,9 @@ pub use self::mint_url::MintUrl; pub use self::nuts::*; pub use self::util::SECP256K1; +#[cfg(feature = "mint")] +pub mod quote_id; + #[doc(hidden)] #[macro_export] macro_rules! ensure_cdk { @@ -25,107 +28,3 @@ macro_rules! ensure_cdk { } }; } - -#[cfg(feature = "mint")] -/// Quote ID. The specifications only define a string but CDK uses Uuid, so we use an enum to port compatibility. -pub mod quote_id { - use std::fmt; - use std::str::FromStr; - - use bitcoin::base64::engine::general_purpose; - use bitcoin::base64::Engine as _; - use serde::{de, Deserialize, Deserializer, Serialize}; - use thiserror::Error; - use uuid::Uuid; - - /// Invalid UUID - #[derive(Debug, Error)] - pub enum QuoteIdError { - /// UUID Error - #[error("invalid UUID: {0}")] - Uuid(#[from] uuid::Error), - /// Invalid base64 - #[error("invalid base64")] - Base64, - /// Invalid quote ID - #[error("neither a valid UUID nor a valid base64 string")] - InvalidQuoteId, - } - - /// Mint Quote ID - #[derive(Serialize, Debug, Clone, PartialEq, PartialOrd, Ord, Eq, Hash)] - #[serde(untagged)] - pub enum QuoteId { - /// (Nutshell) base64 quote ID - BASE64(String), - /// UUID quote ID - UUID(Uuid), - } - - impl QuoteId { - /// Create a new UUID-based MintQuoteId - pub fn new_uuid() -> Self { - Self::UUID(Uuid::new_v4()) - } - } - - impl From for QuoteId { - fn from(uuid: Uuid) -> Self { - Self::UUID(uuid) - } - } - - impl fmt::Display for QuoteId { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - match self { - QuoteId::BASE64(s) => write!(f, "{}", s), - QuoteId::UUID(u) => write!(f, "{}", u), - } - } - } - - impl FromStr for QuoteId { - type Err = QuoteIdError; - - fn from_str(s: &str) -> Result { - // Try UUID first - if let Ok(u) = Uuid::parse_str(s) { - return Ok(QuoteId::UUID(u)); - } - - // Try base64: decode, then re-encode and compare to ensure canonical form - // Use the standard (URL/filename safe or standard) depending on your needed alphabet. - // Here we use standard base64. - match general_purpose::URL_SAFE.decode(s) { - Ok(_bytes) => Ok(QuoteId::BASE64(s.to_string())), - Err(_) => Err(QuoteIdError::InvalidQuoteId), - } - } - } - - impl<'de> Deserialize<'de> for QuoteId { - fn deserialize(deserializer: D) -> Result - where - D: Deserializer<'de>, - { - // Deserialize as plain string first - let s = String::deserialize(deserializer)?; - - // Try UUID first - if let Ok(u) = Uuid::parse_str(&s) { - return Ok(QuoteId::UUID(u)); - } - - if general_purpose::URL_SAFE.decode(&s).is_ok() { - return Ok(QuoteId::BASE64(s)); - } - - // Neither matched — return a helpful error - Err(de::Error::custom(format!( - "QuoteId must be either a UUID (e.g. {}) or a valid base64 string; got: {}", - Uuid::nil(), - s - ))) - } - } -} diff --git a/crates/cashu/src/quote_id.rs b/crates/cashu/src/quote_id.rs new file mode 100644 index 000000000..58ccac59a --- /dev/null +++ b/crates/cashu/src/quote_id.rs @@ -0,0 +1,100 @@ +//! Quote ID. The specifications only define a string but CDK uses Uuid, so we use an enum to port compatibility. +use std::fmt; +use std::str::FromStr; + +use bitcoin::base64::engine::general_purpose; +use bitcoin::base64::Engine as _; +use serde::{de, Deserialize, Deserializer, Serialize}; +use thiserror::Error; +use uuid::Uuid; + +/// Invalid UUID +#[derive(Debug, Error)] +pub enum QuoteIdError { + /// UUID Error + #[error("invalid UUID: {0}")] + Uuid(#[from] uuid::Error), + /// Invalid base64 + #[error("invalid base64")] + Base64, + /// Invalid quote ID + #[error("neither a valid UUID nor a valid base64 string")] + InvalidQuoteId, +} + +/// Mint Quote ID +#[derive(Serialize, Debug, Clone, PartialEq, PartialOrd, Ord, Eq, Hash)] +#[serde(untagged)] +pub enum QuoteId { + /// (Nutshell) base64 quote ID + BASE64(String), + /// UUID quote ID + UUID(Uuid), +} + +impl QuoteId { + /// Create a new UUID-based MintQuoteId + pub fn new_uuid() -> Self { + Self::UUID(Uuid::new_v4()) + } +} + +impl From for QuoteId { + fn from(uuid: Uuid) -> Self { + Self::UUID(uuid) + } +} + +impl fmt::Display for QuoteId { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + QuoteId::BASE64(s) => write!(f, "{}", s), + QuoteId::UUID(u) => write!(f, "{}", u.hyphenated()), + } + } +} + +impl FromStr for QuoteId { + type Err = QuoteIdError; + + fn from_str(s: &str) -> Result { + // Try UUID first + if let Ok(u) = Uuid::parse_str(s) { + return Ok(QuoteId::UUID(u)); + } + + // Try base64: decode, then re-encode and compare to ensure canonical form + // Use the standard (URL/filename safe or standard) depending on your needed alphabet. + // Here we use standard base64. + match general_purpose::URL_SAFE.decode(s) { + Ok(_bytes) => Ok(QuoteId::BASE64(s.to_string())), + Err(_) => Err(QuoteIdError::InvalidQuoteId), + } + } +} + +impl<'de> Deserialize<'de> for QuoteId { + fn deserialize(deserializer: D) -> Result + where + D: Deserializer<'de>, + { + // Deserialize as plain string first + let s = String::deserialize(deserializer)?; + + // Try UUID first + if let Ok(u) = Uuid::parse_str(&s) { + return Ok(QuoteId::UUID(u)); + } + + if general_purpose::URL_SAFE.decode(&s).is_ok() { + return Ok(QuoteId::BASE64(s)); + } + + // Neither matched — return a helpful error + Err(de::Error::custom(format!( + "QuoteId must be either a UUID (e.g. {}) or a valid base64 string; got: {}", + Uuid::nil(), + s + ))) + } +} diff --git a/crates/cdk-common/src/database/mint/mod.rs b/crates/cdk-common/src/database/mint/mod.rs index 3f3c1d3a8..a48d29c32 100644 --- a/crates/cdk-common/src/database/mint/mod.rs +++ b/crates/cdk-common/src/database/mint/mod.rs @@ -5,7 +5,6 @@ use std::collections::HashMap; use async_trait::async_trait; use cashu::quote_id::QuoteId; use cashu::{Amount, MintInfo}; -use uuid::Uuid; use super::Error; use crate::common::QuoteTTL; @@ -89,7 +88,7 @@ pub trait QuotesTransaction<'a> { /// Get [`mint::MeltQuote`] and lock it for update in this transaction async fn get_melt_quote( &mut self, - quote_id: &Uuid, + quote_id: &QuoteId, ) -> Result, Self::Err>; /// Add [`mint::MeltQuote`] async fn add_melt_quote(&mut self, quote: mint::MeltQuote) -> Result<(), Self::Err>; @@ -111,7 +110,7 @@ pub trait QuotesTransaction<'a> { payment_proof: Option, ) -> Result<(MeltQuoteState, mint::MeltQuote), Self::Err>; /// Remove [`mint::MeltQuote`] - async fn remove_melt_quote(&mut self, quote_id: &Uuid) -> Result<(), Self::Err>; + async fn remove_melt_quote(&mut self, quote_id: &QuoteId) -> Result<(), Self::Err>; /// Get all [`MintMintQuote`]s and lock it for update in this transaction async fn get_mint_quote_by_request( &mut self, @@ -165,7 +164,11 @@ pub trait ProofsTransaction<'a> { /// /// Adds proofs to the database. The database should error if the proof already exits, with a /// `AttemptUpdateSpentProof` if the proof is already spent or a `Duplicate` error otherwise. - async fn add_proofs(&mut self, proof: Proofs, quote_id: Option) -> Result<(), Self::Err>; + async fn add_proofs( + &mut self, + proof: Proofs, + quote_id: Option, + ) -> Result<(), Self::Err>; /// Updates the proofs to a given states and return the previous states async fn update_proofs_states( &mut self, @@ -177,7 +180,7 @@ pub trait ProofsTransaction<'a> { async fn remove_proofs( &mut self, ys: &[PublicKey], - quote_id: Option, + quote_id: Option, ) -> Result<(), Self::Err>; } @@ -190,7 +193,10 @@ pub trait ProofsDatabase { /// Get [`Proofs`] by ys async fn get_proofs_by_ys(&self, ys: &[PublicKey]) -> Result>, Self::Err>; /// Get ys by quote id - async fn get_proof_ys_by_quote_id(&self, quote_id: &Uuid) -> Result, Self::Err>; + async fn get_proof_ys_by_quote_id( + &self, + quote_id: &QuoteId, + ) -> Result, Self::Err>; /// Get [`Proofs`] state async fn get_proofs_states(&self, ys: &[PublicKey]) -> Result>, Self::Err>; /// Get [`Proofs`] by state diff --git a/crates/cdk-common/src/database/mint/test.rs b/crates/cdk-common/src/database/mint/test.rs index d8b69d083..e7455fd22 100644 --- a/crates/cdk-common/src/database/mint/test.rs +++ b/crates/cdk-common/src/database/mint/test.rs @@ -87,7 +87,7 @@ where { let keyset_id = setup_keyset(&db).await; - let quote_id = Uuid::max(); + let quote_id = QuoteId::new_uuid(); let proofs = vec![ Proof { @@ -110,7 +110,9 @@ where // Add proofs to database let mut tx = Database::begin_transaction(&db).await.unwrap(); - tx.add_proofs(proofs.clone(), Some(quote_id)).await.unwrap(); + tx.add_proofs(proofs.clone(), Some(quote_id.clone())) + .await + .unwrap(); assert!(tx.commit().await.is_ok()); let proofs_from_db = db.get_proofs_by_ys(&[proofs[0].c, proofs[1].c]).await; diff --git a/crates/cdk-sql-common/Cargo.toml b/crates/cdk-sql-common/Cargo.toml index 2c54c9577..7785ff4d8 100644 --- a/crates/cdk-sql-common/Cargo.toml +++ b/crates/cdk-sql-common/Cargo.toml @@ -27,5 +27,4 @@ tokio.workspace = true serde.workspace = true serde_json.workspace = true lightning-invoice.workspace = true -uuid.workspace = true once_cell.workspace = true diff --git a/crates/cdk-sql-common/src/mint/mod.rs b/crates/cdk-sql-common/src/mint/mod.rs index 02f281504..ec7ae4479 100644 --- a/crates/cdk-sql-common/src/mint/mod.rs +++ b/crates/cdk-sql-common/src/mint/mod.rs @@ -37,7 +37,6 @@ use cdk_common::{ use lightning_invoice::Bolt11Invoice; use migrations::MIGRATIONS; use tracing::instrument; -use uuid::Uuid; use crate::common::migrate; use crate::database::{ConnectionWithTransaction, DatabaseExecutor}; @@ -170,7 +169,7 @@ where async fn add_proofs( &mut self, proofs: Proofs, - quote_id: Option, + quote_id: Option, ) -> Result<(), Self::Err> { let current_time = unix_time(); @@ -213,7 +212,7 @@ where proof.witness.map(|w| serde_json::to_string(&w).unwrap()), ) .bind("state", "UNSPENT".to_string()) - .bind("quote_id", quote_id.map(|q| q.hyphenated().to_string())) + .bind("quote_id", quote_id.clone().map(|q| q.to_string())) .bind("created_time", current_time as i64) .execute(&self.inner) .await?; @@ -254,7 +253,7 @@ where async fn remove_proofs( &mut self, ys: &[PublicKey], - _quote_id: Option, + _quote_id: Option, ) -> Result<(), Self::Err> { if ys.is_empty() { return Ok(()); @@ -328,13 +327,7 @@ where quote_id=:quote_id "#, )? - .bind( - "quote_id", - match quote_id { - QuoteId::UUID(u) => u.as_hyphenated().to_string(), - QuoteId::BASE64(s) => s.to_string(), - }, - ) + .bind("quote_id", quote_id.to_string()) .fetch_all(conn) .await? .into_iter() @@ -363,13 +356,7 @@ FROM mint_quote_issued WHERE quote_id=:quote_id "#, )? - .bind( - "quote_id", - match quote_id { - QuoteId::UUID(u) => u.as_hyphenated().to_string(), - QuoteId::BASE64(s) => s.to_string(), - }, - ) + .bind("quote_id", quote_id.to_string()) .fetch_all(conn) .await? .into_iter() @@ -591,13 +578,7 @@ where FOR UPDATE "#, )? - .bind( - "quote_id", - match quote_id { - QuoteId::UUID(u) => u.as_hyphenated().to_string(), - QuoteId::BASE64(s) => s.to_string(), - }, - ) + .bind("quote_id", quote_id.to_string()) .fetch_one(&self.inner) .await .inspect_err(|err| { @@ -632,13 +613,7 @@ where "#, )? .bind("amount_paid", new_amount_paid.to_i64()) - .bind( - "quote_id", - match quote_id { - QuoteId::UUID(u) => u.as_hyphenated().to_string(), - QuoteId::BASE64(s) => s.to_string(), - }, - ) + .bind("quote_id", quote_id.to_string()) .execute(&self.inner) .await .inspect_err(|err| { @@ -653,13 +628,7 @@ where VALUES (:quote_id, :payment_id, :amount, :timestamp) "#, )? - .bind( - "quote_id", - match quote_id { - QuoteId::UUID(u) => u.as_hyphenated().to_string(), - QuoteId::BASE64(s) => s.to_string(), - }, - ) + .bind("quote_id", quote_id.to_string()) .bind("payment_id", payment_id) .bind("amount", amount_paid.to_i64()) .bind("timestamp", unix_time() as i64) @@ -688,13 +657,7 @@ where FOR UPDATE "#, )? - .bind( - "quote_id", - match quote_id { - QuoteId::UUID(u) => u.as_hyphenated().to_string(), - QuoteId::BASE64(s) => s.to_string(), - }, - ) + .bind("quote_id", quote_id.to_string()) .fetch_one(&self.inner) .await .inspect_err(|err| { @@ -722,13 +685,7 @@ where "#, )? .bind("amount_issued", new_amount_issued.to_i64()) - .bind( - "quote_id", - match quote_id { - QuoteId::UUID(u) => u.as_hyphenated().to_string(), - QuoteId::BASE64(s) => s.to_string(), - }, - ) + .bind("quote_id", quote_id.to_string()) .execute(&self.inner) .await .inspect_err(|err| { @@ -744,13 +701,7 @@ INSERT INTO mint_quote_issued VALUES (:quote_id, :amount, :timestamp); "#, )? - .bind( - "quote_id", - match quote_id { - QuoteId::UUID(u) => u.as_hyphenated().to_string(), - QuoteId::BASE64(s) => s.to_string(), - }, - ) + .bind("quote_id", quote_id.to_string()) .bind("amount", amount_issued.to_i64()) .bind("timestamp", current_time as i64) .execute(&self.inner) @@ -792,13 +743,7 @@ VALUES (:quote_id, :amount, :timestamp); async fn remove_mint_quote(&mut self, quote_id: &QuoteId) -> Result<(), Self::Err> { query(r#"DELETE FROM mint_quote WHERE id=:id"#)? - .bind( - "id", - match quote_id { - QuoteId::UUID(u) => u.as_hyphenated().to_string(), - QuoteId::BASE64(s) => s.to_string(), - }, - ) + .bind("id", quote_id.to_string()) .execute(&self.inner) .await?; Ok(()) @@ -861,10 +806,7 @@ VALUES (:quote_id, :amount, :timestamp); query(r#"UPDATE melt_quote SET request_lookup_id = :new_req_id, request_lookup_id_kind = :new_kind WHERE id = :id"#)? .bind("new_req_id", new_request_lookup_id.to_string()) .bind("new_kind",new_request_lookup_id.kind() ) - .bind("id", match quote_id { - QuoteId::BASE64(s) => s.to_string(), - QuoteId::UUID(u) => u.as_hyphenated().to_string(), - }) + .bind("id", quote_id.to_string()) .execute(&self.inner) .await?; Ok(()) @@ -900,13 +842,7 @@ VALUES (:quote_id, :amount, :timestamp); AND state != :state "#, )? - .bind( - "id", - match quote_id { - QuoteId::UUID(u) => u.as_hyphenated().to_string(), - QuoteId::BASE64(s) => s.to_string(), - }, - ) + .bind("id", quote_id.to_string()) .bind("state", state.to_string()) .fetch_one(&self.inner) .await? @@ -920,22 +856,13 @@ VALUES (:quote_id, :amount, :timestamp); .bind("state", state.to_string()) .bind("paid_time", current_time as i64) .bind("payment_preimage", payment_proof) - .bind("id", match quote_id { - QuoteId::UUID(u) => u.as_hyphenated().to_string(), - QuoteId::BASE64(s) => s.to_string(), - }) + .bind("id", quote_id.to_string()) .execute(&self.inner) .await } else { query(r#"UPDATE melt_quote SET state = :state WHERE id = :id"#)? .bind("state", state.to_string()) - .bind( - "id", - match quote_id { - QuoteId::UUID(u) => u.as_hyphenated().to_string(), - QuoteId::BASE64(s) => s.to_string(), - }, - ) + .bind("id", quote_id.to_string()) .execute(&self.inner) .await }; @@ -954,14 +881,14 @@ VALUES (:quote_id, :amount, :timestamp); Ok((old_state, quote)) } - async fn remove_melt_quote(&mut self, quote_id: &Uuid) -> Result<(), Self::Err> { + async fn remove_melt_quote(&mut self, quote_id: &QuoteId) -> Result<(), Self::Err> { query( r#" DELETE FROM melt_quote WHERE id=? "#, )? - .bind("id", quote_id.as_hyphenated().to_string()) + .bind("id", quote_id.to_string()) .execute(&self.inner) .await?; @@ -993,13 +920,7 @@ VALUES (:quote_id, :amount, :timestamp); FOR UPDATE "#, )? - .bind( - "id", - match quote_id { - QuoteId::UUID(u) => u.as_hyphenated().to_string(), - QuoteId::BASE64(s) => s.to_string(), - }, - ) + .bind("id", quote_id.to_string()) .fetch_one(&self.inner) .await? .map(|row| sql_row_to_mint_quote(row, payments, issuance)) @@ -1008,7 +929,7 @@ VALUES (:quote_id, :amount, :timestamp); async fn get_melt_quote( &mut self, - quote_id: &Uuid, + quote_id: &QuoteId, ) -> Result, Self::Err> { Ok(query( r#" @@ -1033,7 +954,7 @@ VALUES (:quote_id, :amount, :timestamp); id=:id "#, )? - .bind("id", quote_id.as_hyphenated().to_string()) + .bind("id", quote_id.to_string()) .fetch_one(&self.inner) .await? .map(sql_row_to_melt_quote) @@ -1157,13 +1078,7 @@ where mint_quote WHERE id = :id"#, )? - .bind( - "id", - match quote_id { - QuoteId::UUID(u) => u.as_hyphenated().to_string(), - QuoteId::BASE64(s) => s.to_string(), - }, - ) + .bind("id", quote_id.to_string()) .fetch_one(&*conn) .await? .map(|row| sql_row_to_mint_quote(row, payments, issuance)) @@ -1319,13 +1234,7 @@ where id=:id "#, )? - .bind( - "id", - match quote_id { - QuoteId::BASE64(s) => s.to_string(), - QuoteId::UUID(u) => u.as_hyphenated().to_string(), - }, - ) + .bind("id", quote_id.to_string()) .fetch_one(&*conn) .await? .map(sql_row_to_melt_quote) @@ -1406,7 +1315,10 @@ where Ok(ys.iter().map(|y| proofs.remove(y)).collect()) } - async fn get_proof_ys_by_quote_id(&self, quote_id: &Uuid) -> Result, Self::Err> { + async fn get_proof_ys_by_quote_id( + &self, + quote_id: &QuoteId, + ) -> Result, Self::Err> { let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; Ok(query( r#" @@ -1422,7 +1334,7 @@ where quote_id = :quote_id "#, )? - .bind("quote_id", quote_id.as_hyphenated().to_string()) + .bind("quote_id", quote_id.to_string()) .fetch_all(&*conn) .await? .into_iter() @@ -1661,13 +1573,7 @@ where quote_id=:quote_id "#, )? - .bind( - "quote_id", - match quote_id { - QuoteId::BASE64(s) => s.to_string(), - QuoteId::UUID(u) => u.as_hyphenated().to_string(), - }, - ) + .bind("quote_id", quote_id.to_string()) .fetch_all(&*conn) .await? .into_iter() From 39f256a648b63f34d6bd43c0b3204c362e6ef670 Mon Sep 17 00:00:00 2001 From: Erik <78821053+swedishfrenchpress@users.noreply.github.com> Date: Wed, 3 Sep 2025 16:46:49 +0200 Subject: [PATCH 125/321] cdk-ldk web ui updates (#1027) --- crates/cdk-ldk-node/Cargo.toml | 5 +- .../cdk-ldk-node/src/web/handlers/channels.rs | 90 +- .../src/web/handlers/lightning.rs | 157 ++-- .../cdk-ldk-node/src/web/handlers/onchain.rs | 75 +- .../cdk-ldk-node/src/web/templates/layout.rs | 846 +++++++++++++----- .../src/web/templates/payments.rs | 2 +- crates/cdk-ldk-node/static/images/bg-dark.jpg | Bin 47534 -> 43605 bytes 7 files changed, 840 insertions(+), 335 deletions(-) diff --git a/crates/cdk-ldk-node/Cargo.toml b/crates/cdk-ldk-node/Cargo.toml index 94e3ca0be..e252aaa3e 100644 --- a/crates/cdk-ldk-node/Cargo.toml +++ b/crates/cdk-ldk-node/Cargo.toml @@ -15,7 +15,7 @@ async-trait.workspace = true axum.workspace = true cdk-common = { workspace = true, features = ["mint"] } futures.workspace = true -tokio.workspace = true +tokio.workspace = true tokio-util.workspace = true tracing.workspace = true thiserror.workspace = true @@ -29,6 +29,3 @@ tower-http.workspace = true rust-embed = "8.5.0" serde_urlencoded = "0.7" urlencoding = "2.1" - - - diff --git a/crates/cdk-ldk-node/src/web/handlers/channels.rs b/crates/cdk-ldk-node/src/web/handlers/channels.rs index 238f9365d..dcbe010f7 100644 --- a/crates/cdk-ldk-node/src/web/handlers/channels.rs +++ b/crates/cdk-ldk-node/src/web/handlers/channels.rs @@ -213,7 +213,7 @@ pub async fn post_open_channel( } pub async fn close_channel_page( - State(_state): State, + State(state): State, query: Query>, ) -> Result, StatusCode> { let channel_id = query.get("channel_id").unwrap_or(&"".to_string()).clone(); @@ -229,24 +229,40 @@ pub async fn close_channel_page( return Ok(Html(layout("Close Channel Error", content).into_string())); } + // Get channel information for amount display + let channels = state.node.inner.list_channels(); + let channel = channels + .iter() + .find(|c| c.user_channel_id.0.to_string() == channel_id); + let content = form_card( "Close Channel", html! { - p { "Are you sure you want to close this channel?" } - div class="info-item" { - span class="info-label" { "User Channel ID:" } - span class="info-value" style="font-family: monospace; font-size: 0.85rem;" { (channel_id) } - } - div class="info-item" { - span class="info-label" { "Node ID:" } - span class="info-value" style="font-family: monospace; font-size: 0.85rem;" { (node_id) } + p style="margin-bottom: 1.5rem;" { "Are you sure you want to close this channel?" } + + // Channel details in consistent format + div class="channel-details" { + div class="detail-row" { + span class="detail-label" { "User Channel ID" } + span class="detail-value-amount" { (channel_id) } + } + div class="detail-row" { + span class="detail-label" { "Node ID" } + span class="detail-value-amount" { (node_id) } + } + @if let Some(ch) = channel { + div class="detail-row" { + span class="detail-label" { "Channel Amount" } + span class="detail-value-amount" { (format_sats_as_btc(ch.channel_value_sats)) } + } + } } - form method="post" action="/channels/close" style="margin-top: 1rem;" { + + form method="post" action="/channels/close" style="margin-top: 1rem; display: flex; justify-content: space-between; align-items: center;" { input type="hidden" name="channel_id" value=(channel_id) {} input type="hidden" name="node_id" value=(node_id) {} - button type="submit" style="background: #dc3545;" { "Close Channel" } - " " - a href="/balance" { button type="button" { "Cancel" } } + a href="/balance" { button type="button" class="button-secondary" { "Cancel" } } + button type="submit" class="button-destructive" { "Close Channel" } } }, ); @@ -255,7 +271,7 @@ pub async fn close_channel_page( } pub async fn force_close_channel_page( - State(_state): State, + State(state): State, query: Query>, ) -> Result, StatusCode> { let channel_id = query.get("channel_id").unwrap_or(&"".to_string()).clone(); @@ -273,32 +289,48 @@ pub async fn force_close_channel_page( )); } + // Get channel information for amount display + let channels = state.node.inner.list_channels(); + let channel = channels + .iter() + .find(|c| c.user_channel_id.0.to_string() == channel_id); + let content = form_card( "Force Close Channel", html! { - div style="border: 2px solid #d63384; background-color: rgba(214, 51, 132, 0.1); padding: 1rem; margin-bottom: 1rem; border-radius: 0.5rem;" { - h4 style="color: #d63384; margin: 0 0 0.5rem 0;" { "⚠️ Warning: Force Close" } - p style="color: #d63384; margin: 0; font-size: 0.9rem;" { + div style="border: 2px solid #f97316; background-color: rgba(249, 115, 22, 0.1); padding: 1rem; margin-bottom: 1rem; border-radius: 0.5rem;" { + h4 style="color: #f97316; margin: 0 0 0.5rem 0;" { "⚠️ Warning: Force Close" } + p style="color: #f97316; margin: 0; font-size: 0.9rem;" { "Force close should NOT be used if normal close is preferred. " "Force close will immediately broadcast the latest commitment transaction and may result in delayed fund recovery. " "Only use this if the channel counterparty is unresponsive or there are other issues preventing normal closure." } } - p { "Are you sure you want to force close this channel?" } - div class="info-item" { - span class="info-label" { "User Channel ID:" } - span class="info-value" style="font-family: monospace; font-size: 0.85rem;" { (channel_id) } - } - div class="info-item" { - span class="info-label" { "Node ID:" } - span class="info-value" style="font-family: monospace; font-size: 0.85rem;" { (node_id) } + p style="margin-bottom: 1.5rem;" { "Are you sure you want to force close this channel?" } + + // Channel details in consistent format + div class="channel-details" { + div class="detail-row" { + span class="detail-label" { "User Channel ID" } + span class="detail-value-amount" { (channel_id) } + } + div class="detail-row" { + span class="detail-label" { "Node ID" } + span class="detail-value-amount" { (node_id) } + } + @if let Some(ch) = channel { + div class="detail-row" { + span class="detail-label" { "Channel Amount" } + span class="detail-value-amount" { (format_sats_as_btc(ch.channel_value_sats)) } + } + } } - form method="post" action="/channels/force-close" style="margin-top: 1rem;" { + + form method="post" action="/channels/force-close" style="margin-top: 1rem; display: flex; justify-content: space-between; align-items: center;" { input type="hidden" name="channel_id" value=(channel_id) {} input type="hidden" name="node_id" value=(node_id) {} - button type="submit" style="background: #d63384;" { "Force Close Channel" } - " " - a href="/balance" { button type="button" { "Cancel" } } + a href="/balance" { button type="button" class="button-secondary" { "Cancel" } } + button type="submit" class="button-destructive" { "Force Close Channel" } } }, ); diff --git a/crates/cdk-ldk-node/src/web/handlers/lightning.rs b/crates/cdk-ldk-node/src/web/handlers/lightning.rs index 344b78b3a..8ca3b5446 100644 --- a/crates/cdk-ldk-node/src/web/handlers/lightning.rs +++ b/crates/cdk-ldk-node/src/web/handlers/lightning.rs @@ -3,7 +3,7 @@ use axum::http::StatusCode; use axum::response::Html; use maud::html; -use crate::web::handlers::AppState; +use crate::web::handlers::utils::AppState; use crate::web::templates::{format_sats_as_btc, layout}; pub async fn balance_page(State(state): State) -> Result, StatusCode> { @@ -26,18 +26,35 @@ pub async fn balance_page(State(state): State) -> Result, html! { h2 style="text-align: center; margin-bottom: 3rem;" { "Lightning" } - // Quick Actions section - matching dashboard style + // Quick Actions section - individual cards div class="card" style="margin-bottom: 2rem;" { h2 { "Quick Actions" } - div style="display: flex; gap: 1rem; margin-top: 1rem; flex-wrap: wrap;" { - a href="/channels/open" style="text-decoration: none; flex: 1; min-width: 200px;" { - button class="button-primary" style="width: 100%;" { "Open Channel" } + div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); gap: 1.5rem; margin-top: 1.5rem;" { + // Open Channel Card + div class="quick-action-card" { + h3 style="font-size: 1.125rem; font-weight: 600; margin-bottom: 0.5rem; color: var(--text-primary);" { "Open Channel" } + p style="font-size: 0.875rem; color: var(--text-muted); margin-bottom: 1rem; line-height: 1.4;" { "Create a new Lightning Network channel to connect with another node." } + a href="/channels/open" style="text-decoration: none;" { + button class="button-outline" { "Open Channel" } + } } - a href="/invoices" style="text-decoration: none; flex: 1; min-width: 200px;" { - button class="button-primary" style="width: 100%;" { "Create Invoice" } + + // Create Invoice Card + div class="quick-action-card" { + h3 style="font-size: 1.125rem; font-weight: 600; margin-bottom: 0.5rem; color: var(--text-primary);" { "Create Invoice" } + p style="font-size: 0.875rem; color: var(--text-muted); margin-bottom: 1rem; line-height: 1.4;" { "Generate a Lightning invoice to receive payments from other users or services." } + a href="/invoices" style="text-decoration: none;" { + button class="button-outline" { "Create Invoice" } + } } - a href="/payments/send" style="text-decoration: none; flex: 1; min-width: 200px;" { - button class="button-primary" style="width: 100%;" { "Make Lightning Payment" } + + // Make Payment Card + div class="quick-action-card" { + h3 style="font-size: 1.125rem; font-weight: 600; margin-bottom: 0.5rem; color: var(--text-primary);" { "Make Lightning Payment" } + p style="font-size: 0.875rem; color: var(--text-muted); margin-bottom: 1rem; line-height: 1.4;" { "Send Lightning payments to other users using invoices. BOLT 11 & 12 supported." } + a href="/invoices" style="text-decoration: none;" { + button class="button-outline" { "Make Payment" } + } } } } @@ -73,18 +90,35 @@ pub async fn balance_page(State(state): State) -> Result, html! { h2 style="text-align: center; margin-bottom: 3rem;" { "Lightning" } - // Quick Actions section - matching dashboard style + // Quick Actions section - individual cards div class="card" style="margin-bottom: 2rem;" { h2 { "Quick Actions" } - div style="display: flex; gap: 1rem; margin-top: 1rem; flex-wrap: wrap;" { - a href="/channels/open" style="text-decoration: none; flex: 1; min-width: 200px;" { - button class="button-primary" style="width: 100%;" { "Open Channel" } + div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); gap: 1.5rem; margin-top: 1.5rem;" { + // Open Channel Card + div class="quick-action-card" { + h3 style="font-size: 1.125rem; font-weight: 600; margin-bottom: 0.5rem; color: var(--text-primary);" { "Open Channel" } + p style="font-size: 0.875rem; color: var(--text-muted); margin-bottom: 1rem; line-height: 1.4;" { "Create a new Lightning channel by connecting with another node." } + a href="/channels/open" style="text-decoration: none;" { + button class="button-outline" { "Open Channel" } + } } - a href="/invoices" style="text-decoration: none; flex: 1; min-width: 200px;" { - button class="button-primary" style="width: 100%;" { "Create Invoice" } + + // Create Invoice Card + div class="quick-action-card" { + h3 style="font-size: 1.125rem; font-weight: 600; margin-bottom: 0.5rem; color: var(--text-primary);" { "Create Invoice" } + p style="font-size: 0.875rem; color: var(--text-muted); margin-bottom: 1rem; line-height: 1.4;" { "Generate a Lightning invoice to receive payments." } + a href="/invoices" style="text-decoration: none;" { + button class="button-outline" { "Create Invoice" } + } } - a href="/payments/send" style="text-decoration: none; flex: 1; min-width: 200px;" { - button class="button-primary" style="width: 100%;" { "Make Lightning Payment" } + + // Make Payment Card + div class="quick-action-card" { + h3 style="font-size: 1.125rem; font-weight: 600; margin-bottom: 0.5rem; color: var(--text-primary);" { "Make Lightning Payment" } + p style="font-size: 0.875rem; color: var(--text-muted); margin-bottom: 1rem; line-height: 1.4;" { "Send Lightning payments to other users using invoices." } + a href="/payments/send" style="text-decoration: none;" { + button class="button-outline" { "Make Payment" } + } } } } @@ -112,57 +146,72 @@ pub async fn balance_page(State(state): State) -> Result, } } - div class="card" { - h2 { "Channel Details" } + // Channel Details header (outside card) + h2 class="section-header" { "Channel Details" } + + // Channels list + @for (index, channel) in channels.iter().enumerate() { + @let node_id = channel.counterparty_node_id.to_string(); + @let channel_number = index + 1; - // Channels list - @for channel in &channels { - div class="channel-item" { - div class="channel-header" { - span class="channel-id" { "Channel ID: " (channel.channel_id.to_string()) } + div class="channel-box" { + // Channel number as prominent header + div class="channel-alias" { (format!("Channel {}", channel_number)) } + + // Channel details in left-aligned format + div class="channel-details" { + div class="detail-row" { + span class="detail-label" { "Channel ID" } + span class="detail-value-amount" { (channel.channel_id.to_string()) } + } + @if let Some(short_channel_id) = channel.short_channel_id { + div class="detail-row" { + span class="detail-label" { "Short Channel ID" } + span class="detail-value-amount" { (short_channel_id.to_string()) } + } + } + div class="detail-row" { + span class="detail-label" { "Node ID" } + span class="detail-value-amount" { (node_id) } + } + div class="detail-row" { + span class="detail-label" { "Status" } @if channel.is_usable { span class="status-badge status-active" { "Active" } } @else { span class="status-badge status-inactive" { "Inactive" } } } - div class="info-item" { - span class="info-label" { "Counterparty" } - span class="info-value" style="font-family: monospace; font-size: 0.85rem;" { (channel.counterparty_node_id.to_string()) } + } + + // Balance information cards (keeping existing style) + div class="balance-info" { + div class="balance-item" { + div class="balance-amount" { (format_sats_as_btc(channel.outbound_capacity_msat / 1000)) } + div class="balance-label" { "Outbound" } } - @if let Some(short_channel_id) = channel.short_channel_id { - div class="info-item" { - span class="info-label" { "Short Channel ID" } - span class="info-value" { (short_channel_id.to_string()) } - } + div class="balance-item" { + div class="balance-amount" { (format_sats_as_btc(channel.inbound_capacity_msat / 1000)) } + div class="balance-label" { "Inbound" } } - div class="balance-info" { - div class="balance-item" { - div class="balance-amount" { (format_sats_as_btc(channel.outbound_capacity_msat / 1000)) } - div class="balance-label" { "Outbound" } - } - div class="balance-item" { - div class="balance-amount" { (format_sats_as_btc(channel.inbound_capacity_msat / 1000)) } - div class="balance-label" { "Inbound" } - } - div class="balance-item" { - div class="balance-amount" { (format_sats_as_btc(channel.channel_value_sats)) } - div class="balance-label" { "Total" } - } + div class="balance-item" { + div class="balance-amount" { (format_sats_as_btc(channel.channel_value_sats)) } + div class="balance-label" { "Total" } } - @if channel.is_usable { - div style="margin-top: 1rem; display: flex; gap: 0.5rem;" { - a href=(format!("/channels/close?channel_id={}&node_id={}", channel.user_channel_id.0, channel.counterparty_node_id)) { - button style="background: #dc3545;" { "Close Channel" } - } - a href=(format!("/channels/force-close?channel_id={}&node_id={}", channel.user_channel_id.0, channel.counterparty_node_id)) { - button style="background: #d63384;" title="Force close should not be used if normal close is preferred. Force close will broadcast the latest commitment transaction immediately." { "Force Close" } - } + } + + // Action buttons + @if channel.is_usable { + div class="channel-actions" { + a href=(format!("/channels/close?channel_id={}&node_id={}", channel.user_channel_id.0, channel.counterparty_node_id)) { + button class="button-secondary" { "Close Channel" } + } + a href=(format!("/channels/force-close?channel_id={}&node_id={}", channel.user_channel_id.0, channel.counterparty_node_id)) { + button class="button-destructive" title="Force close should not be used if normal close is preferred. Force close will broadcast the latest commitment transaction immediately." { "Force Close" } } } } } - } } }; diff --git a/crates/cdk-ldk-node/src/web/handlers/onchain.rs b/crates/cdk-ldk-node/src/web/handlers/onchain.rs index ee34076fb..1658d0e0a 100644 --- a/crates/cdk-ldk-node/src/web/handlers/onchain.rs +++ b/crates/cdk-ldk-node/src/web/handlers/onchain.rs @@ -79,15 +79,26 @@ pub async fn onchain_page( let mut content = html! { h2 style="text-align: center; margin-bottom: 3rem;" { "On-chain" } - // Quick Actions section - matching dashboard style + // Quick Actions section - individual cards div class="card" style="margin-bottom: 2rem;" { h2 { "Quick Actions" } - div style="display: flex; gap: 1rem; margin-top: 1rem; flex-wrap: wrap;" { - a href="/onchain?action=receive" style="text-decoration: none; flex: 1; min-width: 200px;" { - button class="button-primary" style="width: 100%;" { "Receive Bitcoin" } + div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); gap: 1.5rem; margin-top: 1.5rem;" { + // Receive Bitcoin Card + div class="quick-action-card" { + h3 style="font-size: 1.125rem; font-weight: 600; margin-bottom: 0.5rem; color: var(--text-primary);" { "Receive Bitcoin" } + p style="font-size: 0.875rem; color: var(--text-muted); margin-bottom: 1rem; line-height: 1.4;" { "Generate a new Bitcoin address to receive on-chain payments from other users or services." } + a href="/onchain?action=receive" style="text-decoration: none;" { + button class="button-outline" { "Receive Bitcoin" } + } } - a href="/onchain?action=send" style="text-decoration: none; flex: 1; min-width: 200px;" { - button class="button-primary" style="width: 100%;" { "Send Bitcoin" } + + // Send Bitcoin Card + div class="quick-action-card" { + h3 style="font-size: 1.125rem; font-weight: 600; margin-bottom: 0.5rem; color: var(--text-primary);" { "Send Bitcoin" } + p style="font-size: 0.875rem; color: var(--text-muted); margin-bottom: 1rem; line-height: 1.4;" { "Send Bitcoin to another address on the blockchain. Standard on-chain transactions." } + a href="/onchain?action=send" style="text-decoration: none;" { + button class="button-outline" { "Send Bitcoin" } + } } } } @@ -113,15 +124,26 @@ pub async fn onchain_page( content = html! { h2 style="text-align: center; margin-bottom: 3rem;" { "On-chain" } - // Quick Actions section - matching dashboard style + // Quick Actions section - individual cards div class="card" style="margin-bottom: 2rem;" { h2 { "Quick Actions" } - div style="display: flex; gap: 1rem; margin-top: 1rem; flex-wrap: wrap;" { - a href="/onchain?action=receive" style="text-decoration: none; flex: 1; min-width: 200px;" { - button class="button-primary" style="width: 100%;" { "Receive Bitcoin" } + div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); gap: 1.5rem; margin-top: 1.5rem;" { + // Receive Bitcoin Card + div class="quick-action-card" { + h3 style="font-size: 1.125rem; font-weight: 600; margin-bottom: 0.5rem; color: var(--text-primary);" { "Receive Bitcoin" } + p style="font-size: 0.875rem; color: var(--text-muted); margin-bottom: 1rem; line-height: 1.4;" { "Generate a new Bitcoin address to receive on-chain payments from other users or services." } + a href="/onchain?action=receive" style="text-decoration: none;" { + button class="button-outline" { "Receive Bitcoin" } + } } - a href="/onchain?action=send" style="text-decoration: none; flex: 1; min-width: 200px;" { - button class="button-primary" style="width: 100%;" { "Send Bitcoin" } + + // Send Bitcoin Card + div class="quick-action-card" { + h3 style="font-size: 1.125rem; font-weight: 600; margin-bottom: 0.5rem; color: var(--text-primary);" { "Send Bitcoin" } + p style="font-size: 0.875rem; color: var(--text-muted); margin-bottom: 1rem; line-height: 1.4;" { "Send Bitcoin to another address on the blockchain. Standard on-chain transactions." } + a href="/onchain?action=send" style="text-decoration: none;" { + button class="button-outline" { "Send Bitcoin" } + } } } } @@ -141,7 +163,7 @@ pub async fn onchain_page( } input type="hidden" id="send_action" name="send_action" value="send" {} div style="display: flex; justify-content: space-between; gap: 1rem; margin-top: 2rem;" { - a href="/onchain" { button type="button" { "Cancel" } } + a href="/onchain" { button type="button" class="button-secondary" { "Cancel" } } div style="display: flex; gap: 0.5rem;" { button type="submit" onclick="document.getElementById('send_action').value='send'" { "Send Payment" } button type="submit" onclick="document.getElementById('send_action').value='send_all'; document.getElementById('amount_sat').value=''" { "Send All" } @@ -171,15 +193,26 @@ pub async fn onchain_page( content = html! { h2 style="text-align: center; margin-bottom: 3rem;" { "On-chain" } - // Quick Actions section - matching dashboard style + // Quick Actions section - individual cards div class="card" style="margin-bottom: 2rem;" { h2 { "Quick Actions" } - div style="display: flex; gap: 1rem; margin-top: 1rem; flex-wrap: wrap;" { - a href="/onchain?action=receive" style="text-decoration: none; flex: 1; min-width: 200px;" { - button class="button-primary" style="width: 100%;" { "Receive Bitcoin" } + div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); gap: 1.5rem; margin-top: 1.5rem;" { + // Receive Bitcoin Card + div class="quick-action-card" { + h3 style="font-size: 1.125rem; font-weight: 600; margin-bottom: 0.5rem; color: var(--text-primary);" { "Receive Bitcoin" } + p style="font-size: 0.875rem; color: var(--text-muted); margin-bottom: 1rem; line-height: 1.4;" { "Generate a new Bitcoin address to receive on-chain payments from other users or services." } + a href="/onchain?action=receive" style="text-decoration: none;" { + button class="button-outline" { "Receive Bitcoin" } + } } - a href="/onchain?action=send" style="text-decoration: none; flex: 1; min-width: 200px;" { - button class="button-primary" style="width: 100%;" { "Send Bitcoin" } + + // Send Bitcoin Card + div class="quick-action-card" { + h3 style="font-size: 1.125rem; font-weight: 600; margin-bottom: 0.5rem; color: var(--text-primary);" { "Send Bitcoin" } + p style="font-size: 0.875rem; color: var(--text-muted); margin-bottom: 1rem; line-height: 1.4;" { "Send Bitcoin to another address on the blockchain. Standard on-chain transactions." } + a href="/onchain?action=send" style="text-decoration: none;" { + button class="button-outline" { "Send Bitcoin" } + } } } } @@ -191,7 +224,7 @@ pub async fn onchain_page( form method="post" action="/onchain/new-address" { p style="margin-bottom: 2rem;" { "Click the button below to generate a new Bitcoin address for receiving on-chain payments." } div style="display: flex; justify-content: space-between; gap: 1rem;" { - a href="/onchain" { button type="button" { "Cancel" } } + a href="/onchain" { button type="button" class="button-secondary" { "Cancel" } } button class="button-primary" type="submit" { "Generate New Address" } } } @@ -345,7 +378,7 @@ pub async fn onchain_confirm_page( div class="card" { div style="display: flex; justify-content: space-between; gap: 1rem; margin-top: 2rem;" { a href="/onchain?action=send" { - button type="button" class="button-secondary" { "← Cancel" } + button type="button" class="button-secondary" { "Cancel" } } div style="display: flex; gap: 0.5rem;" { a href=(confirmation_url) { diff --git a/crates/cdk-ldk-node/src/web/templates/layout.rs b/crates/cdk-ldk-node/src/web/templates/layout.rs index d055390d9..4fd25ef80 100644 --- a/crates/cdk-ldk-node/src/web/templates/layout.rs +++ b/crates/cdk-ldk-node/src/web/templates/layout.rs @@ -34,74 +34,299 @@ pub fn layout(title: &str, content: Markup) -> Markup { --input: 214.3 31.8% 91.4%; --ring: 222.2 84% 4.9%; --radius: 0.5rem; - + /* Typography scale */ --fs-title: 1.25rem; --fs-label: 0.8125rem; --fs-value: 1.625rem; - + /* Line heights */ --lh-tight: 1.15; --lh-normal: 1.4; - + /* Font weights */ --fw-medium: 500; --fw-semibold: 600; --fw-bold: 700; - + /* Colors */ --fg-primary: #0f172a; --fg-muted: #6b7280; - + /* Header text colors for light mode */ --header-title: #000000; --header-subtitle: #333333; } - /* Dark mode using system preference */ + /* Dark mode using system preference */ @media (prefers-color-scheme: dark) { + body { + background: linear-gradient(rgb(23, 25, 29), rgb(18, 19, 21)); + } + :root { - --background: 222.2 84% 4.9%; - --foreground: 210 40% 98%; - --card: 222.2 84% 4.9%; - --card-foreground: 210 40% 98%; - --popover: 222.2 84% 4.9%; - --popover-foreground: 210 40% 98%; - --primary: 210 40% 98%; - --primary-foreground: 222.2 84% 4.9%; - --secondary: 217.2 32.6% 17.5%; - --secondary-foreground: 210 40% 98%; - --muted: 217.2 32.6% 17.5%; - --muted-foreground: 215 20.2% 65.1%; - --accent: 217.2 32.6% 17.5%; - --accent-foreground: 210 40% 98%; + --background: 0 0% 0%; + --foreground: 0 0% 100%; + --card: 0 0% 0%; + --card-foreground: 0 0% 100%; + --popover: 0 0% 0%; + --popover-foreground: 0 0% 100%; + --primary: 0 0% 100%; + --primary-foreground: 0 0% 0%; + --secondary: 0 0% 20%; + --secondary-foreground: 0 0% 100%; + --muted: 0 0% 20%; + --muted-foreground: 0 0% 70%; + --accent: 0 0% 20%; + --accent-foreground: 0 0% 100%; --destructive: 0 62.8% 30.6%; - --destructive-foreground: 210 40% 98%; - --border: 217.2 32.6% 17.5%; - --input: 217.2 32.6% 17.5%; - --ring: 212.7 26.8% 83.9%; - - /* Dark mode colors */ - --fg-primary: #f8fafc; - --fg-muted: #94a3b8; - + --destructive-foreground: 0 0% 100%; + --border: 0 0% 20%; + --input: 0 0% 20%; + --ring: 0 0% 83.9%; + + /* Dark mode text hierarchy colors */ + --text-primary: #ffffff; + --text-secondary: #e6e6e6; + --text-tertiary: #cccccc; + --text-quaternary: #b3b3b3; + --text-muted: #999999; + --text-muted-2: #888888; + --text-muted-3: #666666; + --text-muted-4: #333333; + --text-subtle: #1a1a1a; + /* Header text colors for dark mode */ --header-title: #ffffff; - --header-subtitle: #e2e8f0; + --header-subtitle: #e6e6e6; + } + + /* Dark mode box styling - no borders, subtle background */ + .card { + background-color: rgba(255, 255, 255, 0.03) !important; + border: none !important; + } + + .channel-box { + background-color: rgba(255, 255, 255, 0.03) !important; + border: none !important; + } + + .metric-card { + background-color: rgba(255, 255, 255, 0.03) !important; + border: none !important; + } + + .balance-item { + background-color: rgba(255, 255, 255, 0.03) !important; + border: none !important; + } + + .node-info-main-container { + background-color: rgba(255, 255, 255, 0.03) !important; + border: none !important; + } + + .node-avatar { + background-color: rgba(255, 255, 255, 0.03) !important; + border: none !important; + } + + /* Text hierarchy colors */ + .section-header { + color: var(--text-primary) !important; + } + + .channel-alias { + color: var(--text-primary) !important; + } + + .detail-label { + color: var(--text-muted) !important; + } + + .detail-value, .detail-value-amount { + color: var(--text-secondary) !important; + } + + .metric-label, .balance-label { + color: var(--text-muted) !important; + } + + .metric-value, .balance-amount { + color: var(--text-primary) !important; + } + + /* Page headers and section titles */ + h1, h2, h3, h4, h5, h6 { + color: var(--text-primary) !important; + } + + /* Form card titles */ + .form-card h2, .form-card h3 { + color: var(--text-primary) !important; + } + + /* Quick action cards styling */ + .quick-action-card { + background-color: rgba(255, 255, 255, 0.03) !important; + border: none !important; + border-radius: 0.75rem !important; + padding: 1.5rem !important; + } + + /* Dark mode outline button styling */ + .button-outline { + background-color: transparent !important; + color: var(--text-primary) !important; + border: 1px solid var(--text-muted) !important; + } + + .button-outline:hover { + background-color: rgba(255, 255, 255, 0.2) !important; + } + + /* Navigation dark mode styling */ + nav { + background-color: transparent !important; + border-top: none !important; + border-bottom: none !important; + } + + } + + /* New Header Layout Styles */ + .header-content { + display: flex; + justify-content: space-between; + align-items: center; + padding: 0.5rem 0; + } + + .header-left { + display: flex; + align-items: center; + gap: 1rem; + } + + .header-avatar { + flex-shrink: 0; + background-color: hsl(var(--muted) / 0.3); + border: 1px solid hsl(var(--border)); + border-radius: var(--radius); + padding: 0.75rem; + display: flex; + align-items: center; + justify-content: center; + width: 80px; + height: 80px; + } + + .header-avatar-image { + width: 48px; + height: 48px; + border-radius: calc(var(--radius) - 2px); + object-fit: cover; + display: block; + } + + .node-info { + display: flex; + flex-direction: column; + gap: 0.25rem; + padding-top: 0; + margin-top: 0; + } + + .node-status { + display: flex; + align-items: center; + gap: 0.5rem; + } + + .status-indicator { + width: 0.75rem; + height: 0.75rem; + border-radius: 50%; + background-color: #10b981; + box-shadow: 0 0 0 2px rgba(16, 185, 129, 0.2); + } + + .status-text { + font-size: 0.875rem; + font-weight: 500; + color: #10b981; + } + + .node-title { + font-size: 1.875rem; + font-weight: 600; + color: var(--header-title); + margin: 0; + line-height: 1.1; + } + + .node-subtitle { + font-size: 0.875rem; + color: var(--header-subtitle); + font-weight: 500; + } + + .header-right { + display: flex; + align-items: center; + } + + + + /* Responsive header */ + @media (max-width: 768px) { + .header-content { + flex-direction: column; + gap: 1rem; + text-align: center; + } + + .header-left { + flex-direction: column; + text-align: center; + } + + .node-title { + font-size: 1.5rem; + } + } + + nav a { + color: var(--text-muted) !important; + } + + nav a:hover { + color: var(--text-secondary) !important; + background-color: rgba(255, 255, 255, 0.05) !important; + } + + nav a.active { + color: var(--text-primary) !important; + background-color: rgba(255, 255, 255, 0.08) !important; + } + + nav a.active:hover { + background-color: rgba(255, 255, 255, 0.1) !important; } } - + * { box-sizing: border-box; margin: 0; padding: 0; } - + html { font-feature-settings: 'cv02', 'cv03', 'cv04', 'cv11'; font-variation-settings: normal; } - + body { font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif; font-size: 14px; @@ -114,19 +339,19 @@ pub fn layout(title: &str, content: Markup) -> Markup { text-rendering: geometricPrecision; min-height: 100vh; } - + .container { max-width: 1200px; margin: 0 auto; padding: 0 1rem; } - + @media (min-width: 640px) { .container { padding: 0 2rem; } } - + /* Hero section styling */ header { position: relative; @@ -135,34 +360,37 @@ pub fn layout(title: &str, content: Markup) -> Markup { background-position: center; background-repeat: no-repeat; border-bottom: 1px solid hsl(var(--border)); - margin-bottom: 3rem; - text-align: center; + margin-bottom: 2rem; + text-align: left; width: 100%; - height: 400px; /* Fixed height for better proportion */ + height: 200px; /* Reduced height for more compact header */ display: flex; align-items: center; - justify-content: center; + justify-content: flex-start; } - + /* Dark mode header background - using different image */ @media (prefers-color-scheme: dark) { header { background-image: url('/static/images/bg-dark.jpg?v=3'); } } - + /* Ensure text is positioned properly */ header .container { - position: absolute; - top: 50%; - left: 50%; - transform: translate(-50%, -50%); + position: relative; + top: auto; + left: auto; + transform: none; z-index: 2; width: 100%; max-width: 1200px; padding: 0 2rem; + display: flex; + align-items: center; + justify-content: flex-start; } - + h1 { font-size: 3rem; font-weight: 700; @@ -171,7 +399,7 @@ pub fn layout(title: &str, content: Markup) -> Markup { color: var(--header-title); margin-bottom: 1rem; } - + .subtitle { font-size: 1.25rem; color: var(--header-subtitle); @@ -180,35 +408,35 @@ pub fn layout(title: &str, content: Markup) -> Markup { margin: 0 auto; line-height: 1.6; } - + @media (max-width: 768px) { header { - height: 300px; /* Smaller height on mobile */ + height: 150px; /* Smaller height on mobile */ } - + header .container { padding: 0 1rem; } - + h1 { font-size: 2.25rem; } - + .subtitle { font-size: 1.1rem; } } - + /* Card fade-in animation */ @keyframes fade-in { from { opacity: 0; transform: translateY(10px); } to { opacity: 1; transform: translateY(0); } } - + .card { animation: fade-in 0.3s ease-out; } - + /* Modern Navigation Bar Styling */ nav { background-color: hsl(var(--card)); @@ -220,13 +448,13 @@ pub fn layout(title: &str, content: Markup) -> Markup { padding: 0.75rem; margin-bottom: 2rem; } - + nav .container { padding: 0; display: flex; justify-content: center; } - + nav ul { list-style: none; display: flex; @@ -237,11 +465,11 @@ pub fn layout(title: &str, content: Markup) -> Markup { padding: 0; justify-content: center; } - + nav li { flex-shrink: 0; } - + nav a { display: inline-flex; align-items: center; @@ -257,22 +485,22 @@ pub fn layout(title: &str, content: Markup) -> Markup { position: relative; min-height: 3rem; } - + nav a:hover { color: hsl(var(--foreground)); background-color: hsl(var(--muted)); } - + nav a.active { color: hsl(var(--primary-foreground)); background-color: hsl(var(--primary)); font-weight: 700; } - + nav a.active:hover { background-color: hsl(var(--primary) / 0.9); } - + .card { background-color: hsl(var(--card)); border: 1px solid hsl(var(--border)); @@ -281,7 +509,7 @@ pub fn layout(title: &str, content: Markup) -> Markup { margin-bottom: 1.5rem; box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.05); } - + /* Metric cards styling - matching balance-item style */ .metrics-container { display: flex; @@ -289,7 +517,7 @@ pub fn layout(title: &str, content: Markup) -> Markup { margin: 1rem 0; flex-wrap: wrap; } - + .metric-card { flex: 1; min-width: 200px; @@ -299,7 +527,7 @@ pub fn layout(title: &str, content: Markup) -> Markup { border-radius: calc(var(--radius) - 2px); border: 1px solid hsl(var(--border)); } - + .metric-value { font-size: 1.5rem; font-weight: 600; @@ -307,13 +535,13 @@ pub fn layout(title: &str, content: Markup) -> Markup { margin-bottom: 0.5rem; line-height: 1.2; } - + .metric-label { font-size: 0.875rem; color: hsl(var(--muted-foreground)); font-weight: 400; } - + .card h2, .section-title, h2 { @@ -324,7 +552,7 @@ pub fn layout(title: &str, content: Markup) -> Markup { text-transform: none; margin: 0 0 12px; } - + h3 { font-size: var(--fs-title); line-height: var(--lh-tight); @@ -333,11 +561,11 @@ pub fn layout(title: &str, content: Markup) -> Markup { text-transform: none; margin: 0 0 12px; } - + .form-group { margin-bottom: 1.5rem; } - + label { display: block; font-size: 0.875rem; @@ -345,7 +573,7 @@ pub fn layout(title: &str, content: Markup) -> Markup { color: hsl(var(--foreground)); margin-bottom: 0.5rem; } - + input, textarea, select { flex: 1; background-color: hsl(var(--background)); @@ -358,19 +586,19 @@ pub fn layout(title: &str, content: Markup) -> Markup { transition: border-color 150ms ease-in-out, box-shadow 150ms ease-in-out; width: 100%; } - + input:focus, textarea:focus, select:focus { outline: 2px solid transparent; outline-offset: 2px; border-color: hsl(var(--ring)); box-shadow: 0 0 0 2px hsl(var(--ring)); } - + input:disabled, textarea:disabled, select:disabled { cursor: not-allowed; opacity: 0.5; } - + button { display: inline-flex; align-items: center; @@ -387,79 +615,82 @@ pub fn layout(title: &str, content: Markup) -> Markup { background-color: hsl(var(--primary)); color: hsl(var(--primary-foreground)); } - + button:hover { background-color: hsl(var(--primary) / 0.9); } - + button:focus-visible { outline: 2px solid hsl(var(--ring)); outline-offset: 2px; } - + button:disabled { pointer-events: none; opacity: 0.5; } - + .button-secondary { background-color: hsl(var(--secondary)); color: hsl(var(--secondary-foreground)); border: 1px solid hsl(var(--input)); } - + .button-secondary:hover { background-color: hsl(var(--secondary) / 0.8); } - + .button-outline { border: 1px solid hsl(var(--input)); background-color: hsl(var(--background)); color: hsl(var(--foreground)); } - + .button-outline:hover { background-color: hsl(var(--accent)); color: hsl(var(--accent-foreground)); } - + .button-destructive { - background-color: hsl(var(--destructive)); - color: hsl(var(--destructive-foreground)); + background-color: transparent !important; + color: #DC2626 !important; + border: 1px solid #DC2626 !important; } - + .button-destructive:hover { - background-color: hsl(var(--destructive) / 0.9); + background-color: rgba(220, 38, 38, 0.2) !important; } - + + + .button-sm { height: 2rem; border-radius: calc(var(--radius) - 4px); padding: 0 0.75rem; font-size: 0.75rem; } - + .button-lg { height: 2.75rem; border-radius: var(--radius); padding: 0 2rem; font-size: 1rem; } - + .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(320px, 1fr)); gap: 1.5rem; } - + @media (max-width: 640px) { .grid { grid-template-columns: 1fr; } } - - + + .info-label, .sub-label, label { @@ -471,7 +702,7 @@ pub fn layout(title: &str, content: Markup) -> Markup { letter-spacing: 0.02em; flex-shrink: 0; } - + .info-value { font-size: 0.875rem; font-family: 'SF Mono', 'Monaco', 'Inconsolata', 'Roboto Mono', 'Courier New', monospace; @@ -482,7 +713,7 @@ pub fn layout(title: &str, content: Markup) -> Markup { hyphens: auto; min-width: 0; } - + .info-item { display: flex; gap: 0.5rem; @@ -493,43 +724,43 @@ pub fn layout(title: &str, content: Markup) -> Markup { min-height: 3rem; justify-content: space-between; } - + .info-item:last-child { border-bottom: none; } - + /* Card flex spacing improvements */ .card-flex { display: flex; gap: 1rem; align-items: center; } - + .card-flex-content { flex: 1 1 auto; } - + .card-flex-button { flex: 0 0 auto; } - + .card-flex-content p { margin: 0 0 12px; line-height: var(--lh-normal); } - + .card-flex-content p + .card-flex-button, .card-flex-content p + a, .card-flex-content p + button { margin-top: 12px; } - + .card-flex-content .body + .card-flex-button, .card-flex-content .body + a, .card-flex-content .body + button { margin-top: 12px; } - + .truncate-value { font-size: 0.875rem; font-family: 'SF Mono', 'Monaco', 'Inconsolata', 'Roboto Mono', 'Courier New', monospace; @@ -541,7 +772,7 @@ pub fn layout(title: &str, content: Markup) -> Markup { display: inline-block; max-width: 200px; } - + .copy-button { background-color: hsl(var(--secondary)); color: hsl(var(--secondary-foreground)); @@ -557,24 +788,24 @@ pub fn layout(title: &str, content: Markup) -> Markup { min-height: auto; flex-shrink: 0; } - + .copy-button:hover { background-color: hsl(var(--secondary) / 0.8); border-color: hsl(var(--border)); } - + .balance-item, .balance-item-container { padding: 1.25rem 0; border-bottom: 1px solid hsl(var(--border)); margin-bottom: 10px; } - + .balance-item:last-child, .balance-item-container:last-child { border-bottom: none; } - + .balance-item .balance-label, .balance-item-container .balance-label, .balance-title, @@ -588,7 +819,7 @@ pub fn layout(title: &str, content: Markup) -> Markup { letter-spacing: 0.02em; text-transform: none; } - + .balance-item .balance-amount, .balance-item-container .balance-value, .balance-amount, @@ -602,39 +833,39 @@ pub fn layout(title: &str, content: Markup) -> Markup { white-space: nowrap; font-family: 'SF Mono', 'Monaco', 'Inconsolata', 'Roboto Mono', 'Courier New', monospace; } - + .balance-item .info-label + .info-value, .balance-item .label + .amount, .balance-item-container .info-label + .info-value, .balance-item-container .label + .amount { margin-top: 6px; } - + .alert { border: 1px solid hsl(var(--border)); border-radius: var(--radius); padding: 1rem; margin-bottom: 1rem; } - + .alert-success { border-color: hsl(142.1 76.2% 36.3%); background-color: hsl(142.1 70.6% 45.3% / 0.1); color: hsl(142.1 76.2% 36.3%); } - + .alert-destructive { border-color: hsl(var(--destructive)); background-color: hsl(var(--destructive) / 0.1); color: hsl(var(--destructive)); } - + .alert-warning { border-color: hsl(32.6 75.4% 55.1%); background-color: hsl(32.6 75.4% 55.1% / 0.1); color: hsl(32.6 75.4% 55.1%); } - + /* Legacy classes for backward compatibility */ .success { border-color: hsl(142.1 76.2% 36.3%); @@ -645,7 +876,7 @@ pub fn layout(title: &str, content: Markup) -> Markup { padding: 1rem; margin-bottom: 1rem; } - + .error { border-color: hsl(var(--destructive)); background-color: hsl(var(--destructive) / 0.1); @@ -655,7 +886,7 @@ pub fn layout(title: &str, content: Markup) -> Markup { padding: 1rem; margin-bottom: 1rem; } - + .badge { display: inline-flex; align-items: center; @@ -667,34 +898,34 @@ pub fn layout(title: &str, content: Markup) -> Markup { transition: all 150ms ease-in-out; border: 1px solid transparent; } - + .badge-default { background-color: hsl(var(--primary)); color: hsl(var(--primary-foreground)); } - + .badge-secondary { background-color: hsl(var(--secondary)); color: hsl(var(--secondary-foreground)); } - + .badge-success { background-color: hsl(142.1 70.6% 45.3%); color: hsl(355.7 78% 98.4%); } - + .badge-destructive { background-color: hsl(var(--destructive)); color: hsl(var(--destructive-foreground)); } - + .badge-outline { background-color: transparent; color: hsl(var(--foreground)); border: 1px solid hsl(var(--border)); } - - /* Legacy status classes */ + + /* Status badge classes - consistent with payment type badges */ .status-badge { display: inline-flex; align-items: center; @@ -704,55 +935,127 @@ pub fn layout(title: &str, content: Markup) -> Markup { font-weight: 500; line-height: 1; } - + .status-active { - background-color: hsl(142.1 70.6% 45.3%); - color: hsl(355.7 78% 98.4%); + background-color: hsl(142.1 70.6% 45.3% / 0.1); + color: hsl(142.1 70.6% 45.3%); + border: 1px solid hsl(142.1 70.6% 45.3% / 0.2); } - + .status-inactive { - background-color: hsl(var(--destructive)); - color: hsl(var(--destructive-foreground)); + background-color: hsl(0 84.2% 60.2% / 0.1); + color: hsl(0 84.2% 60.2%); + border: 1px solid hsl(0 84.2% 60.2% / 0.2); } - - .channel-item { + + .status-pending { + background-color: hsl(215.4 16.3% 46.9% / 0.1); + color: hsl(215.4 16.3% 46.9%); + border: 1px solid hsl(215.4 16.3% 46.9% / 0.2); + } + + .channel-box { background-color: hsl(var(--card)); border: 1px solid hsl(var(--border)); border-radius: var(--radius); padding: 1.5rem; margin-bottom: 1.5rem; } - - .channel-header { - display: flex; - justify-content: space-between; - align-items: center; + + .section-header { + font-size: 1.25rem; + font-weight: 700; + color: hsl(var(--foreground)); + margin-bottom: 1.5rem; + line-height: 1.2; + } + + .channel-alias { + font-size: 1.25rem; + font-weight: 600; + color: hsl(var(--foreground)); margin-bottom: 1rem; + line-height: 1.2; + } + + .channel-details { + margin-bottom: 1.5rem; + } + + .detail-row { + display: flex; + align-items: baseline; + margin-bottom: 0.75rem; gap: 1rem; } - - .channel-id { + + .detail-row:last-child { + margin-bottom: 0; + } + + .detail-label { + font-weight: 500; + color: hsl(var(--muted-foreground)); + font-size: 0.875rem; + min-width: 120px; + flex-shrink: 0; + } + + .detail-value { + color: hsl(var(--foreground)); font-family: 'SF Mono', 'Monaco', 'Inconsolata', 'Roboto Mono', 'Courier New', monospace; font-size: 0.875rem; - color: hsl(var(--muted-foreground)); word-break: break-all; flex: 1; min-width: 0; } - + + .detail-value-amount { + color: hsl(var(--foreground)); + font-size: 0.875rem; + word-break: break-all; + flex: 1; + min-width: 0; + } + + .channel-actions { + display: flex; + justify-content: space-between; + align-items: center; + margin-top: 1rem; + gap: 1rem; + } + + @media (max-width: 640px) { + .channel-actions { + flex-direction: column; + align-items: stretch; + } + + .detail-row { + flex-direction: column; + align-items: flex-start; + gap: 0.25rem; + } + + .detail-label { + min-width: auto; + } + } + .balance-info { display: grid; grid-template-columns: repeat(auto-fit, minmax(120px, 1fr)); gap: 1rem; margin-top: 1rem; } - + @media (max-width: 640px) { .balance-info { grid-template-columns: 1fr; } } - + .balance-item { text-align: center; padding: 1rem; @@ -760,7 +1063,7 @@ pub fn layout(title: &str, content: Markup) -> Markup { border-radius: calc(var(--radius) - 2px); border: 1px solid hsl(var(--border)); } - + .balance-amount { font-weight: 600; font-size: 1.125rem; @@ -768,9 +1071,9 @@ pub fn layout(title: &str, content: Markup) -> Markup { color: hsl(var(--foreground)); line-height: 1.2; } - - + + .payment-item { background-color: hsl(var(--card)); border: 1px solid hsl(var(--border)); @@ -778,7 +1081,7 @@ pub fn layout(title: &str, content: Markup) -> Markup { padding: 1.5rem; margin-bottom: 1.5rem; } - + .payment-header { display: flex; justify-content: space-between; @@ -786,7 +1089,7 @@ pub fn layout(title: &str, content: Markup) -> Markup { margin-bottom: 1rem; gap: 1rem; } - + @media (max-width: 640px) { .payment-header { flex-direction: column; @@ -794,7 +1097,7 @@ pub fn layout(title: &str, content: Markup) -> Markup { gap: 0.75rem; } } - + .payment-direction { display: flex; align-items: center; @@ -804,19 +1107,19 @@ pub fn layout(title: &str, content: Markup) -> Markup { flex: 1; min-width: 0; } - + .direction-icon { font-size: 1.125rem; font-weight: bold; color: hsl(var(--muted-foreground)); } - + .payment-details { display: flex; flex-direction: column; gap: 0.75rem; } - + .payment-amount { font-size: 1.25rem; font-weight: 600; @@ -824,14 +1127,14 @@ pub fn layout(title: &str, content: Markup) -> Markup { color: hsl(var(--foreground)); line-height: 1.2; } - + .payment-info { display: flex; align-items: center; gap: 0.75rem; flex-wrap: wrap; } - + @media (max-width: 640px) { .payment-info { flex-direction: column; @@ -839,14 +1142,14 @@ pub fn layout(title: &str, content: Markup) -> Markup { gap: 0.25rem; } } - + .payment-label { font-weight: 500; color: hsl(var(--muted-foreground)); font-size: 0.875rem; flex-shrink: 0; } - + .payment-value { color: hsl(var(--foreground)); font-family: 'SF Mono', 'Monaco', 'Inconsolata', 'Roboto Mono', 'Courier New', monospace; @@ -854,7 +1157,7 @@ pub fn layout(title: &str, content: Markup) -> Markup { word-break: break-all; min-width: 0; } - + .payment-list-header { display: flex; justify-content: space-between; @@ -863,7 +1166,7 @@ pub fn layout(title: &str, content: Markup) -> Markup { padding-bottom: 1rem; border-bottom: 1px solid hsl(var(--border)); } - + @media (max-width: 640px) { .payment-list-header { flex-direction: column; @@ -871,14 +1174,14 @@ pub fn layout(title: &str, content: Markup) -> Markup { gap: 1rem; } } - + .payment-filter-tabs { display: flex; gap: 0.25rem; overflow-x: auto; -webkit-overflow-scrolling: touch; } - + .payment-filter-tab { display: inline-flex; align-items: center; @@ -895,19 +1198,43 @@ pub fn layout(title: &str, content: Markup) -> Markup { transition: all 150ms ease-in-out; height: 2.25rem; } - + .payment-filter-tab:hover { background-color: hsl(var(--accent)); color: hsl(var(--accent-foreground)); text-decoration: none; } - + .payment-filter-tab.active { background-color: hsl(var(--primary)); color: hsl(var(--primary-foreground)); border-color: hsl(var(--primary)); } - + + /* Dark mode specific styling for payment filter tabs */ + @media (prefers-color-scheme: dark) { + .payment-filter-tab { + background-color: rgba(255, 255, 255, 0.03) !important; + border-color: var(--text-muted) !important; + color: var(--text-muted) !important; + } + + .payment-filter-tab:hover { + background-color: rgba(255, 255, 255, 0.08) !important; + color: var(--text-secondary) !important; + } + + .payment-filter-tab.active { + background-color: rgba(255, 255, 255, 0.12) !important; + color: var(--text-primary) !important; + border-color: var(--text-secondary) !important; + } + + .payment-filter-tab.active:hover { + background-color: rgba(255, 255, 255, 0.15) !important; + } + } + .payment-type-badge { display: inline-flex; align-items: center; @@ -920,43 +1247,43 @@ pub fn layout(title: &str, content: Markup) -> Markup { text-transform: uppercase; letter-spacing: 0.05em; } - + .payment-type-bolt11 { background-color: hsl(217 91% 60% / 0.1); color: hsl(217 91% 60%); border: 1px solid hsl(217 91% 60% / 0.2); } - + .payment-type-bolt12 { background-color: hsl(262 83% 58% / 0.1); color: hsl(262 83% 58%); border: 1px solid hsl(262 83% 58% / 0.2); } - + .payment-type-onchain { background-color: hsl(32 95% 44% / 0.1); color: hsl(32 95% 44%); border: 1px solid hsl(32 95% 44% / 0.2); } - + .payment-type-spontaneous { background-color: hsl(142.1 70.6% 45.3% / 0.1); color: hsl(142.1 70.6% 45.3%); border: 1px solid hsl(142.1 70.6% 45.3% / 0.2); } - + .payment-type-bolt11-jit { background-color: hsl(199 89% 48% / 0.1); color: hsl(199 89% 48%); border: 1px solid hsl(199 89% 48% / 0.2); } - + .payment-type-unknown { background-color: hsl(var(--muted)); color: hsl(var(--muted-foreground)); border: 1px solid hsl(var(--border)); } - + /* Pagination */ .pagination-controls { display: flex; @@ -964,14 +1291,14 @@ pub fn layout(title: &str, content: Markup) -> Markup { align-items: center; margin: 2rem 0; } - + .pagination { display: flex; align-items: center; gap: 0.25rem; list-style: none; } - + .pagination-btn, .pagination-number { display: inline-flex; align-items: center; @@ -990,19 +1317,19 @@ pub fn layout(title: &str, content: Markup) -> Markup { min-width: 2.25rem; padding: 0 0.5rem; } - + .pagination-btn:hover, .pagination-number:hover { background-color: hsl(var(--accent)); color: hsl(var(--accent-foreground)); text-decoration: none; } - + .pagination-number.active { background-color: hsl(var(--primary)); color: hsl(var(--primary-foreground)); border-color: hsl(var(--primary)); } - + .pagination-btn.disabled { background-color: hsl(var(--muted)); color: hsl(var(--muted-foreground)); @@ -1010,7 +1337,7 @@ pub fn layout(title: &str, content: Markup) -> Markup { opacity: 0.5; pointer-events: none; } - + .pagination-ellipsis { display: flex; align-items: center; @@ -1020,31 +1347,31 @@ pub fn layout(title: &str, content: Markup) -> Markup { color: hsl(var(--muted-foreground)); font-size: 0.875rem; } - + /* Responsive adjustments */ @media (max-width: 640px) { .container { padding: 0 1rem; } - + header { padding: 1rem 0; margin-bottom: 1rem; } - + h1 { font-size: 1.5rem; } - + nav ul { flex-wrap: wrap; } - + .card { padding: 1rem; margin-bottom: 1rem; } - + .info-item { flex-direction: column; align-items: flex-start; @@ -1052,43 +1379,43 @@ pub fn layout(title: &str, content: Markup) -> Markup { padding: 1rem 0; min-height: auto; } - + .info-value, .truncate-value { text-align: left; max-width: 100%; } - + .copy-button { margin-left: 0; margin-top: 0.25rem; align-self: flex-start; } - + .balance-amount-value { font-size: 1.25rem; } - + .pagination { flex-wrap: wrap; justify-content: center; gap: 0.125rem; } - + .pagination-btn, .pagination-number { height: 2rem; min-width: 2rem; font-size: 0.75rem; } } - + /* Node Information Section Styling */ .node-info-section { display: flex; gap: 1.5rem; margin-bottom: 1.5rem; - align-items: flex-start; + align-items: stretch; } - + .node-info-main-container { flex: 1; display: flex; @@ -1099,15 +1426,16 @@ pub fn layout(title: &str, content: Markup) -> Markup { border-radius: var(--radius); padding: 1.5rem; box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.05); + height: 100%; } - + .node-info-left { display: flex; align-items: center; gap: 1rem; margin-bottom: 1rem; } - + .node-avatar { flex-shrink: 0; background-color: hsl(var(--muted) / 0.3); @@ -1120,7 +1448,7 @@ pub fn layout(title: &str, content: Markup) -> Markup { width: 80px; height: 80px; } - + .avatar-image { width: 48px; height: 48px; @@ -1128,12 +1456,12 @@ pub fn layout(title: &str, content: Markup) -> Markup { object-fit: cover; display: block; } - + .node-details { flex: 1; min-width: 0; } - + .node-name { font-size: var(--fs-title); font-weight: var(--fw-semibold); @@ -1144,14 +1472,14 @@ pub fn layout(title: &str, content: Markup) -> Markup { overflow-wrap: break-word; hyphens: auto; } - + .node-address { font-size: 0.875rem; color: var(--fg-muted); margin: 0; line-height: var(--lh-normal); } - + .node-content-box { background-color: hsl(var(--muted) / 0.3); border: 1px solid hsl(var(--border)); @@ -1164,106 +1492,119 @@ pub fn layout(title: &str, content: Markup) -> Markup { color: hsl(var(--muted-foreground)); overflow: hidden; } - + .node-metrics { flex-shrink: 0; width: 280px; display: flex; flex-direction: column; + align-self: stretch; } - + .node-metrics .card { margin-bottom: 0; flex: 1; display: flex; flex-direction: column; + align-self: stretch; } - + .node-metrics .metrics-container { flex-direction: column; margin: 1rem 0 0 0; flex: 1; + display: flex; + justify-content: flex-start; + gap: 1rem; + align-items: stretch; } - + .node-metrics .metric-card { min-width: auto; + padding: 1rem; + height: fit-content; + display: flex; + flex-direction: column; + align-items: center; + justify-content: center; + text-align: center; } - + /* Mobile responsive design for node info */ @media (max-width: 768px) { .node-info-section { flex-direction: column; gap: 1rem; } - + .node-info-left { flex-direction: column; align-items: flex-start; text-align: center; gap: 0.75rem; } - + .node-avatar { align-self: center; } - + .node-details { text-align: center; width: 100%; } - + .node-content-box { min-height: 150px; padding: 1rem; } - + .node-metrics { width: 100%; } - + .node-metrics .metrics-container { flex-direction: row; flex-wrap: wrap; } - + .node-metrics .metric-card { flex: 1; min-width: 120px; } } - + @media (max-width: 480px) { .node-info-left { gap: 0.5rem; } - + .node-avatar { width: 64px; height: 64px; padding: 0.5rem; } - + .avatar-image { width: 40px; height: 40px; } - + .node-name { font-size: 1rem; word-wrap: break-word; overflow-wrap: break-word; hyphens: auto; } - + .node-address { font-size: 0.8125rem; } - + .node-content-box { min-height: 120px; padding: 0.75rem; } - + .node-metrics .metrics-container { flex-direction: column; gap: 0.75rem; @@ -1275,12 +1616,12 @@ pub fn layout(title: &str, content: Markup) -> Markup { :root { --fs-value: 1.45rem; } - + .node-name { font-size: 0.875rem; } } - + @media (max-width: 480px) { .node-name { font-size: 0.8125rem; @@ -1300,19 +1641,70 @@ pub fn layout(title: &str, content: Markup) -> Markup { body { header { div class="container" { - h1 { "CDK LDK Node" } - p class="subtitle" { "Lightning Network Node Management" } + div class="header-content" { + div class="header-left" { + div class="header-avatar" { + img src="/static/images/nut.png" alt="CDK LDK Node Icon" class="header-avatar-image"; + } + div class="node-info" { + div class="node-status" { + span class="status-indicator status-running" {} + span class="status-text" { "Running" } + } + h1 class="node-title" { "CDK LDK Node" } + span class="node-subtitle" { "Cashu Mint & Lightning Network Node Management" } + } + } + div class="header-right" { + // Right side content can be added here later if needed + } + } } } nav { div class="container" { ul { - li { a href="/" { "Dashboard" } } - li { a href="/balance" { "Lightning" } } - li { a href="/onchain" { "On-chain" } } - li { a href="/invoices" { "Invoices" } } - li { a href="/payments" { "All Payments" } } + li { + a href="/" { + svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.25" stroke-linecap="round" stroke-linejoin="round" style="margin-right: 0.5rem;" { + path d="M15.6 2.7a10 10 0 1 0 5.7 5.7" {} + circle cx="12" cy="12" r="2" {} + path d="M13.4 10.6 19 5" {} + } + "Dashboard" + } + } + li { + a href="/balance" { + svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.25" stroke-linecap="round" stroke-linejoin="round" style="margin-right: 0.5rem;" { + path d="M4 14a1 1 0 0 1-.78-1.63l9.9-10.2a.5.5 0 0 1 .86.46l-1.92 6.02A1 1 0 0 0 13 10h7a1 1 0 0 1 .78 1.63l-9.9 10.2a.5.5 0 0 1-.86-.46l1.92-6.02A1 1 0 0 0 11 14z" {} + } + "Lightning" + } + } + li { + a href="/onchain" { + svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.25" stroke-linecap="round" stroke-linejoin="round" style="margin-right: 0.5rem;" { + path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71" {} + path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71" {} + } + "On-chain" + } + } + li { + a href="/payments" { + svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.25" stroke-linecap="round" stroke-linejoin="round" style="margin-right: 0.5rem;" { + path d="M12 18H4a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h16a2 2 0 0 1 2 2v5" {} + path d="m16 19 3 3 3-3" {} + path d="M18 12h.01" {} + path d="M19 16v6" {} + path d="M6 12h.01" {} + circle cx="12" cy="12" r="2" {} + } + "All Payments" + } + } } } } @@ -1320,6 +1712,8 @@ pub fn layout(title: &str, content: Markup) -> Markup { main class="container" { (content) } + + } } } diff --git a/crates/cdk-ldk-node/src/web/templates/payments.rs b/crates/cdk-ldk-node/src/web/templates/payments.rs index 84455bd41..479d07643 100644 --- a/crates/cdk-ldk-node/src/web/templates/payments.rs +++ b/crates/cdk-ldk-node/src/web/templates/payments.rs @@ -17,7 +17,7 @@ pub fn payment_list_item( let status_class = match status { "Succeeded" => "status-active", "Failed" => "status-inactive", - "Pending" => "status-badge", + "Pending" => "status-pending", _ => "status-badge", }; diff --git a/crates/cdk-ldk-node/static/images/bg-dark.jpg b/crates/cdk-ldk-node/static/images/bg-dark.jpg index 8cd9b7c209a40418a16fa4889ec1fe4768d21dfb..d96f3453cb0c66eac3845a3aea6181befc7ffcca 100644 GIT binary patch literal 43605 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 Vz@Gx6Kv8o4&k;Z*dgqA2{{eTwr-c9j literal 47534 zcmeFa2V4~A_CEgZvMcK%uo5JRMqR?(f@O17Q`esH#f=m_qq4~xf3!oJN=yZoaa2} zyzh)J3twJkD$jvK1~Q3+F$w--FE6r%Oo_=%*~r|yk*cv}W7S(W*48#}wQl+j{%hUC zR%4659$lO}J9KvL@?QVGefz&R-rvW6{Ork-XRrKf<UvejU_LSur7E^abmTTL~0_FH!u~p)@~D)*zxiLYh)r}Qk97cn_jr~x%%1>|NHSj z4g607|I@&KfCeOk_5T4+@y{PYGB{ZirDlN~lQO1ZQZ3JtwM@ZSAa+DEc^erm{v)Sk zt(3_V7_&9V!+2(8z~ke=g_(_(F)t?0nKXNGogy(h z$KU&O|N3fj#?#{{enSL!rImqP*7)$E1YA8|)iI`KwKF(2j)h}0<_kage>UMU1rdJL z3ebN>Z7VRYo*)wLH)W_h7$-`CbWyg3|2Hy7Bb5m}`(t7#UWpM+;8`a$P8Us&DTP)L z+kzxTboft=3IA{O`~RQ2$ZaE&;acDTwvkMUA81%HY|3E@$@TFE_CU^S9c8=NNg?S6 zdcgD2bexycfwdo;Tx&SVWOqix!8N1;WMN+a9z65K4GsTSYE%+X)!5MR z3U)5(X)*h5-|rsZc(k`nSG)5sE(I=zi@m}~5l>%7)dVz3vKQ+JDc(NEH9g6565m6T zU^sUp-W&q7-o|~aWn7?BT!S6B*n~h9=qb}%qd9rTUIT$wqN}M{)o4YANmA1F&UPHB zwpx5F{gF$HIkfSwPg-Mi0OI3W1u9pIM)e;A&(7ivW@wcLGe`mz^QY!hF_xq4u3}oW zT*m~NT(WMwB(qphfsJn(Q|r}ilUiu^+9>pz*60oj*uFy0af|pT+ZpeL2U6%~hkS6V zi|((BSMLg7b3_5ti2~|HCTLuwGh&BIp3$y!huVdWcm@`iVg|oDGreO@f!$Ehbh@6I zxTrl>yik}y5=6H#E(9VevQIPP^GJ4V%v_iZtLCK=2dmgO0{>o7>q-6hubLi+-DGP} zz)Bp*9Q&@?&i~b$AR%HxQUrVw01*jMeRL$m1W3y5JUTYo+3k$lxRRH{I(ExDhK-rE zE4$((DRfNUF)eQ$BdmC+nQ+X`ZhE$p4&K@A9M@n89pll_o%wbbFTtA#yTohe5<&y2 z>K2;ce4++B?)6c4s$sCQWQm4fb!F{!IMH95usp^ZIxx|zMUwG~k_fjn-pykF zi;!0EQMIi>rk6T6-Z=M{1+)Q_7^&W?P$!UQfPAup-1Z+c;^Yas+V~&?z#xdc2Cecy zr+7)QeY}Il_Jm?tNA&CI@D?o4F``OYw z9+E2b0HMgKJ#QY@vA;S&tukYDC&6C}hLfDF7IVPUdeTxfl*t8YWq{h{K+`6+k!i~U z)i!?p(0<*l%>!|n4?We7u1$oTp|4v9pH-?L)Y%!TB` zKwS0PM^|34<^QUzOh8Qb+u&!!-AQ&sW4d+EImgMvhnQpK3@;BK46ICLCbZC@olnqm zk6x0Qe@Qr0D+#(Np2eGt5LY;9sWm`2W^gC2!J}bx;t>|modB6*!a~LfrEv!b)|B8n zrkhio_*`{pYp%vy-lf=?`^(D_ zX^qqi+_m-rP*)P3hVK7(PVhp#6xi$8ZrR2-FvY(%i4>U}^%dH_a#|(hK;sBqYDv&5 zw;M26#~dBBoroH}b=kVXBfW~feWqKJ;O;6W`JDAo2~N8=fvFnwjF4naChv}y2M&_~ z=ZHdC69ooTOU4WAkx4pnHognx{A+*_$Tgom*U}%RO7UiG^}O)H zQ@7hAx$mb*KmzsWCrYakh)mPV_OFjksGje5@)tmDqiw{4^2+4#h6ZW15ft1;Q*&v{unGvfEbzqaaXK2OtLIOZ}z%X^XXIRoy<|G`jhIQKExe(kq zCYYPj)ZQvhZ1Q}6CP9-4*=g4yls)uZQ> z@wkXt#nWnR2pn{x`UA_gLRe_AKGD5z!5PiB<3+`lX;b=jVyLgUX48Pn_5 zpN&f96K|D~PgI_Cmzo#{>AP;`m_18 z!en``vdZgOr8q^BayBoNW4b+gRRup^)3HU<4(KAnu%%_^J5{IF1?!Mchcq4>=qVZU z$n`-^-|IS}#G<=PK_!FX<^q#c4go_Gftvh%A!BW4ESHw{u{~lP)z*0$AT1X_e{N{R zBxi!WTh7-$yhrf3nclLJXmL)as%!o(`sl13lYg0MNlMTAFx^lJ!r-;$*GM_h;&IrL37^Qk0wlpUTGJLqM=Cx~XU=nbRYI#6-vQN5WPt+` zz_g{Iw=4W^6x}V~y1e+wjKv&KD>T@u;M#-(O5OyLZ9MC`VCzM@+p}KWbu~GAQ&*d# z$=lA10MbEQ4kBw1!lz_#O7C<2W?7%YGhNpj-g}fs@nKo3ktbuI@7@t6INt|A5S~&e#y4u-9FVCt}^|N{KG}W8Eg6$=P18_I|I?DQm_x zO_Dmu5F;6f43P1Z>7uPCq+fHf%DP|JMgNDi)?mkuZ9#ITu^GP3vWH95qsoc^DGw{t z0En2)@E~0V{4~%r0TxfHlDjSlFP*oVH|f{l_?(*gd#354+L#(@ED!fGLrO!QX`@X5 zmuPx2O2w=Ww|WnGkszkB4ReHi`?BH4(@KuZr!;3oHoCQ${`7Wdd2ijuNic4$L*ui(P^W(l>7k?SM>dNKb z)1@-K7kZ9R6hSh@IH{Bg3Zq&U(q_-DOAm){ne_YGYOrLl#i!$O3|i1HZ3W^zDJVgj zMry*UJRv~bz$@ipp+UNIjg1n!=Z)D@F18e&(irl)TA|iTRjA z?ShFx-WVcTk zmC4t?*K6wtC*T{p2_6X#qHgJ>)m^s@mITX5hG3S_500W0gbfps279bM+sG5N)(K1! z+@3=>pl-kAf+bbT^kfZ4>jui#+Ro%btW&8A0Wj@}mBLAq3dY=g9_O2N!RM(7$(`DD)oGM@Ka9Sv% zdEmjph~?^^wu*6RI0z|jQ;!DHU=Xu1<{3{Zxd zz+j+Nggb2DQ1(({ti^x?>vxuB^?j%GVyuJ9_xppMeO(lysc3`HB2W01tjk(j^?hH< zNC#BPUgdQZ?~t**n~*mkfmwXW{k$CLQycCHqDOd#Sn&YhMvF(D-25Rzp1amL8pj}# zIT4Kaqo`Prh$t$8w2%qOO+FdouHjMEIg9HNOi!Tz8goNH9`?cd!$*s&=SM!OzPm74 z>d+cU12whQTM6Z3xENKD4{GQa<5h$`WN}cHXmv9E;o0f+bX0#;&=(iQG}eM24JS20 zOFC;IszGZ=O6|44>0nv!d8JXf!KCih`(tA&i#VgA!os9skM13R+ChUvarl4-6|u|i zR$qusJX-2kKC8y`@RnJZQHZJqYtqQCwRXnTJ48tuX#^fcN#hM`i==u=Yxvtrqu^&% zFS(+e``ln8r=0n-uMgg>9=UW>!?A~ssT494J257+p@UVf0MbUR78Zij3YtTY8Tlw| zjs92%kxtEjL0=+6+7fid8 z&tP6UK$hCx_a~o4hwnd+x}LiHQu(AibAzkqzqnr7T_?FwdG+}%=V`h>qBYUh>a>4PJ02vp{_s} zmlBc99@gF5{YS z^OB->#?fo4)2Y$Zu3gpD7W>qaAgcO(V6JB-BTOcn>w6f^ab}scyl66uHNzYmohPUp zYkhI#f8^hu_l_vFUw^)xvhr;&m zLY;BEX?pqGnwp|!gVPlb1Ej3KgoQdVPNmYTta4R)nan{ZF@rg9(4x#iLb%3MMyIW{ zKAGO6<461}d#ksGETdJei&7*IsR8kW@n>%?+jlJL@&0)(*)G#^UEbjDU+vRt zX-$?#Y1ZgsNsw-KjY$y<3uJQN505RvpnGNy21YRxT!L2;OwMw7$y!$(`mOt`HEKqQ z3D1-YMr-2Fde2w8YP~MxfN$URhXV8}*oh1ZAae<|JqQ=`V(HX-gx|bMLheZFfc?N5 zISDQ<02r(as!8dfsl8&|Qp(Hnj`ed7H8KGK-9acNT>E9-ADr@@7yo_VDzms(9Y{$P z^Jn^%D5MDqy`G=ib)?EW>y86+s%Z4=J=?IzWEkLL|EM;;Ot~}4HXof#?UOYz4IeJ( zSG6O0md<9f5cnK>HsZBEbtybN&V1>I+&4>l4DHdS@YXqh`M%zJ-&mu&RowezR)Tz8 zBWLl)-VYHF?b5uxQk+H8{n-b@DKGFV_D|>%810 z>G3~!N#i|RpRqmUkjiWiY2qXGyr*%A5E}`4g1ABLKp_=sN5Bx!j#lG0)hW1cMWmqe zS}safhPbHO9cx!`>f|>!jNQdToz8OR#+xC%@;W9+!)Aw!yFIP?@XeV|+&@D&$>7wQ z?!;J`IRzFk6o+(5i!tk;El`b{rK5@<5`*ywsFe1t)H=%qj?SHX1Wv=gxZy)q}*~#(FJ=XJ8ZkbY+4dIAcX^9p+adE z46l??2~BRfrmW_2({Z!dlx7f)(n1Q2^-2svTG%OzUw;1Uk;n^sE|VZHEc8TL6qnH9 z8!!or*%S&WHKb558QdwGde${FkrAe}Q@kK8(%K967I^*(*GM9S8ykgz=#3P!(qn z`=AK0(s|mAR8pyq0RVIiYRAm#@YaH-FP>Jm(a0H)w!2REj^&`lgGU}$R(#j0d&U3ion zga4iX+Mg=2jUuKrgL0ubtuqwJZi9kd-jOPppwYNaZ4k&w{;3ZB0lelW?dwDjNuq;x2?h6dY@FFAJfhD(ci zn|+y$<%s;Jb6lU@o?A4uU}#iAfYa3OC%Wh4n@Q7}=A6wb=zhSl#PZ~{ns$y?$K*|S zb18W??&g!nOI;>jv~fD+asByAc6R=ptaBYwWI`-dYn{6cyDUV{PLs7x`~8b=c~dYg z$^Aicez|k+WkN(PvXxJjyyglsrvJvv1L!KVZT*1OpJ;QR|Ujyxh9kG`x zWJ-SFHZzr!erZA-*b1o`1zv*`lm-1`W{ks;97SA28d`X&YlE%^5$zWfyjV(@Cjei< zgn+K=ek&?VYuvsrtR4$PwzhQRE1z!H(Pd`ba6Pc`>YSoGj!A@ph_WDvLLw5B%mOrQ z-j%fS%|%hK?x@xvc_Ygg!m7Ak8b;Cf^~rQZagobnUxNae1z3VuG6_?ILcqS%U>oXG zY=&J4Nw+w|PN_rydw3TQ!71WOm4c_fesPox1pC4x2T=-?#8n{0 zx$}gcO^mWF=n>2>-Ffugc}?lXU5D@nolWCI+vEa zBonGb1Vy-%SVt@LQLU3zQpC({;3(LW?5VcR<)jX_$VDlNVyugxwrI2vPkx(B{t6eS zK`>SZZ1vJ$_KQgp1eA+PkVb*^3hJcf%4+GX3d`1y$7Y=@?4n~Z!n(kKEJ0^EXo}*= z7v--8L74PIMp#__=7TBMY62=KCd>30UYQeNPib$T8;~%`*&c1?we05eEm;}05n=`M zg08@@+AvBOW}}j$aMqCYE`OU2n-y|jDjlc4Q2^7F@*%{SODAv zMS3yaLOlc2{&IrGM6?s>2b@odI-&14-L+GNTi-YzezGL&wJxAZ-E}C5#u*1ukhXx+ zcBRkU+$!vf+t_R2CZ*1(35DGbWK)`I?6s!RKR-Oh(rO7u0G@%k#QWKKtX2gm{~;Ge zMH+MjjH8XRG#Kn;J&u~2ohKn)LJFk}9gO4Aj(#u$V=dO|hnD>-Y9{6=ILhKzpOC0g z;ve6*p93C473zCvA2WdW}`eddYMK5lUI){CRr-P+gMRYbk?67f^r1o0Er}u{4xP9D2)5 zwj-kUMoA>*L82EF^SZKjqz@fihfxcOFdOxOW#bgdriA+K^86_tKL>U|ifNG&wufsp#m@5{xGJU{dzI<2kRcgP>?&LceHb z$dpsh#+Bq*V|1^*Rx240`S5vce)-muuIKHmd^X$N+@HC1MRhn9u`8a;?ttOH6j1fG z3t>P^GV|@&?Tl??UJg&C-YDA~wuypr-Jr!+>2J!`JAGR`kN-hMDIj7Q7DnzM^Hc}O zwux$DVe!~1&;_C4p$keFp&qG2V`WZ(>Y}Qo3r1^&8PtGq#?U*!U>s26uP5lpHcgsN zN>XTr(t=o**8o>gN5otxnS}=F9W3U3?_YK4#kW2yo;=#>IBOsVyb0ZW3Ttzi=TNyY zZUP;y)nh!$uZ(qZJ{f@u1@H@H@&u`FI|7kYFq0fhe}1a-_YXIjq){=p$XIAKMPf8! z^eC-PfO3J}v+He4^g_(LMlsL8q+-ZBOC6A6S_HcnLf)KtS3*KkbNdC^4@ViS^&ah; z&i!FsUU365v}9*-z&aU*L{m1TYmH1&z;d{e8g_^nx2pRQXK#;G!x^4|4S^#tPqp!n z@k|F4`}HK|j9S}J!PXcIjv_lj6^Iy>q#4GEV3nCciC(A1ojQEk)qDO?yIW%>G`*ph zVRYwkPh<}{S}28CO$dDNq3eSMiymJO)9Jk8(@;%RhVkyw!XD_)33ppl)AH7FWeLT# zUdDRi>wx}#_KAgz^@^~*qe6h}89|{B$@XiZPe5}q^trT51)cNgp@OM>tCC3?%vkOv zUk+QN?sMruxMPl%gK`>$I@q&Rum>+WkC;ea36mUuafSC!w|cI$;z?Uj6%+<)C1tc5 z!Wc9XBsssHYT5Y;vNq92ZNS%|N&L`(cWY6RK)TcqyOCuxN#^Ne`bVEvCp z&8s47Z5Am;!CIx6=%H5(__3RteV0jKiV3DLMXE$}19pRdMWYH{+_)gI!1enb&Rz{2 zRQCQViPQ`BKbXu+A=Sdjyc9Olui&5x4nYluhHyuWpF8QjW2yHJi6&Z+tifEcFi#q{ zDquG`D33~yQel<(YmGs#FevDPyp*t;98zN}Vw0{gKvGEq0gw{X82-Ti`hbo?-=oC` zAs)9LJ+muv-Kc!z{GnPfG<*;MJsX{Nq+YrB)HS7aF-N0LVQ8Ta>W(LRgz=_{rys_) z)>!-|A+_R(IT&@en7fPq*{&EdaT&EA1?jAnv99r&Yqm^zx*#>d7DEKoMmtjpykW+2 zE}%VCa`2u4aEr%x7tj$4+qDfUzP9Y!E>@9%PJ{rcgj~_q0Mqic1;_yxVPNZ0qX(ynjea3xFu zuDf?!4f(DZ=^$#}2!CnlST&pA_+!~;6UDAp_WBT7Bp} z9VcO6y-<>1Q823C2!{{@QtG6Ugi&G<8Q?B30Bq&qg0Lz=F9{J+VV#Ql&=1yaEJn9X zcWrj(X$SZ^Ces~9ee(KVUWu+b>;!+nanGkr`JsODs}_#L_^vc*m<+>=2o;!4+=zLz zqxu@@@iRy|P(KzafJ(;tq3{fk0a27FRjMt$`jp@FS`E3$4kR@5#2W=mM!9Qn3NcEl zXa^jHJ@5hC0*d{ONr?C3)q4#ks8=+NK>|m-fSwz&(@w2q2z(6kh~4)Ndg-Nn3_ikW z8VM&?TgA4Ez8CcL)F3kq?LK~v>$n<8bLr##rukoAbc!?k2CBrj+T?cGW?Ph; zFT`u2hwh|=Zr{m#g!{#(P`b*RVH;1~yHxed6}w+8T5-if4{k?`*_W-&KM{I%PdX!8 z>0L<&JFZ_z__Nusqq`;w8OwqZH){$XE4)~@0nDF|X07)~1`I~$YioUIKP0@#QjRIM z#~T`Imd-mhsFVK$oP~sWF$dg1%G|Nr&%J*>+@rR47Fxp}2M<$&kW;_ER3}yI1dsc* z64B>_)Qo5HH9geiRZt)~1lbeecLr=>KwYpyrWFhoGX<5Bd7(`4`CBYT#5(yZHO`UGxS5wk!?~y!{~=3vKoOy~ zbGs*9)3g&h!0QD%8ZWa_>(Vmq`GewQg&N#I@*y*NRFX9^YdD^&wO;yNS)Ve) z@=r9mi#cBn;+bLRv9zuey^M(oyqL6vfz(7w0a)Pd#M&wQ)4;2KYXTOVsDBWYQJf&1iiAu25Ay^(Xgb}zWBLKvVk%38-=51`0rmo>dQ=hf8)gii3jrh%b zUsjEI577;MW_Xc?2!XxD=mh~)^T%Ylxjwr**VXI%t!}~~q}s9zdM_$G@wQ)pFbZiQ zET|!e-Y20nb9viN#@e~AJyV|ohK%8Gs*jNVA~}}rVJnCj zyydk1E$6Apo05TL@sT=Iwbm8m^(N@&Aka=!7Ho<(ZSVehBYw@MhCI!-vMG z_m3I;bjq0c)wSVpr(j@nzyhBhE6=2>;iDc3@dFE$@+?|!hqy;&>! z0qG7L2qbF5a5>$!oYGVO7?WFi`}nJ()#gI*ky9@iL2%1 zALW81YQi2_V~&${w%gi5#@>x$O1xWSGN*T`7Lvkt3{*eisY?gK!)z!5a@Z7&Es$M` z1q;Le-|D=!xy=C)SCBa)u|@_R4y!)OMI*EE?a&xTh@z;xQg? zU_{OY4|Ac%_3{XHV6xD^d-!uWqMPpdlj0P6ynUV0`hAw%z8gARhmBWdpzjsqsg9p_ z?e%_pCDpQ%nPzX-Ietx%VMA}8>Q&c!cZ{Is8bpRM~1~qsAK4N^eMgL zo5lmKsLu!1L{NonW{~Szi?KWq5H=vwe?KdB%$P)<)Q2-%yhn}Y-38hn&>jo|=ERFB zqZjLZta`nl!2yXb-{el&-Df991zl^3S)PL(UIcV zW}$Bky|XkfQY@CngM(tc6OG(a5yI6QUUDGi`IX{v$!d2)yg|-Wl1F$iS>M-t?Jm}Y zQ)Y0APrvvkj)Ijyx$o9a+QHxSRGFYMLcEXSL3`+awlU&GBY(tHx z6-I1=ncb|I{Rt06lW%}jY31RkuN?GA>$`qsUPl_d1HgxCDU{*w5umkF%J#Z;*xCWi z;2M~OYwYeDA+rMP%>=jy4R;Jm?|JnAMxxe@xiu<^`_&-u0Q>sG!i;JfH>;kS5~o}b z8C5(4gIB32aUC=imzEn7(0 zR&76P?U33A+g+DFcP&Ibvp09-Fg7W@`w4r7VNBT4Jty6Mc;@1=`MZyHKlCjHs_i}R z0n7V8=@z5!Nk>y8vo2_Lbn6jE<t(s5Kv)mPkz*O1Aoj<0(Xxvs70vfgIDHINW;3~J zckA>HwyEuJ_q^34Gd~HgU})C0z&&SEqGvx(qYGzTFWUfo4!9 z*q0t3NunR{QFjA^M5_LGERO0`fm{T|I*JT}=>>A{R0mzX{K;#lndVi!IQ(6N;JHG? z6XTw}X-+l9BpGy!`7Idp^+Y7ih=Tald)}0Nj~Ye2c8!1fqff|#6E)ve9FmRXr7EfQ zY%^YConWnOyDL@Rk49o8!8j=L@nZ0UcGgPam>_d63Z7}yX3JRq73 zO3VD-zSFm=GPlg7SFhdi^);m2L1w4J}ZtXv5^~1j!G3Vi?kR zX-%j3#gw*d)jGVijx6wIrRCz-J=gkniq{Jroer!M4H`liyvin1FznIg@?go}-{=Gt z`$I7hPV8~*8P9yh6C3d+9N=nzT;toN)3}$I06Ez9a44@0uT}M+}Qr zY~pz-n5W)TO?~LLksM;3CYty;w8l$OeS&Qy(?X=6FcHRKgy-)}0^x*x1W41MGSEt) zj)K?+2h`kNT6D~1HuXYJVgNd%f|%odxOQ2J3`DD-d{_jsoHnTY;k9h6d*c-`kG z+y{e*&JjAb72exS_Y5=O4MyR;7vY538OLuQ2RJs^5L$>%;TtSL zs6a_|H1d=&o+xIR0ZAhO2#5s>65&ZC0`MkmLAU7dYDt1D4?0l`uq5zHBz=@iBiPBq z3g0fg7VDce?Wgb)eagBaF=Y~mH|KBLGZrN#8e$Y0q+?-Wg&LMF({wx;+j-IH+d6K< zqzZZD-s~v&l)g<^T6a`EY?a|3bM2NDy7q9r5|xF5`>Xd_w5yAWNjt=Ol77dAuuCu_;5OdWff)&TOpp#*qf`co8`S5} zs3^UBLSbLOpF13R9NXk^aoLP}$`!yRhAIP@N*L@3<25*|gF)X;bDi(SW+V>zBnP8@ zr5o*b+%9+BGJo``T3^%^9f8dR~^QPHudF{neFi3a20xk5aPGvpdh02I{gZT&f)OCt(oMzck*k-mS z4sTJ@iYk;7dOc&hjo5t5a^L*Ur(=EX5?!A&Y5Jm}({0RHlwJk?la4XAfNF`5>**DY zgD*ofJoy}qNm#4Z6}0)U3R~^ z+P-3r&!Dl$m6?TG&jK1$ZaUiIUf&mZ)g8y;*TVJPcr5?*WU+rMtFD>fqNud!c7@B7 zjxHmPUaIit5tdRR7N>%ESWvP7^u-o;1JyNYO=cvDv=WKmN-yr6U*Nq{|`JAc9H z#T@S8t66pQr1R`Mx?g-^MR=`WQ~RYA<4dIV7g1{ChX@cOHBs$0A1ka*RsiB4vmhmh zsw1sZ@S$i<=;5grC?FObbRpyxz*umX-zCX{Cd85?i-O2PnH#(WLZd`4E~t%>WKk31 zt13v*q`EvP=J1%l?yFBOP4v1M;y5G-&yZPgYuwqJI?n2lJkV#%ffL112}}{DJAJ&Q z=vrzy zCxf*>>|mKVlAH-xi}E6TqVqdXOV+Ta33Hx@-`P{a15bB5JC?g{RX%heZA?F!?|jFW zmxr<0(bscx;S7QA{h-F zlX3A_3DnGEpa@e-gh)%-C8~`;O_&H22MrKh;s7360B*o;So?o%6-+?NR>8U`!pwm7 z%A1omH`PQCTagF^7g_;!!Yt&d!2*?(2|B4x#|Lzm9JzO+NCPT>Pe`0UaC>6)X zNLqHwxlAv%cI|ftQ1zFf-CuoK;$tn7;oTMbFoO*5!!&rLv(o8>&vn2~URevrNdnJ# zRlaa5So&i>hEPjZp(b#^oWcb~62XCp)#3-KMW_kd@`9FrUm@aNXoQ63A@(4bave6> zn3u*qm{(EJ>wb@fS_CDmrSB}js%UMcbKmEi&mTSR6lc7J`P>&@#%{Qs&!{^PR*v&n z!)s4s;~qb~V?5*!Em~Z8b6klPV|aeT0P+H4He~+7oJfSYE=WqN*slYG{EAJ#$QL00jvZ@_C$Z$5W_i0itdb0i;}OYGdt+8g_I?B;7* z{>c4}$4G*z&o7!q@lXs6l(kaR2@!!rLevnNmsY4gAjqoW{@5+x=0@7&@#=){d&hd6 zD$I+ZqLNgHt^tq%>c|>5z3Rb;6*{J4swNoU*>7-a6g~oIcJEc>RzYx7|+oW zCzj22-QBdRAP}#Q8DFp0VNg1K+vzo{g?7;EMc-tpeKFn>(E#n27H_~9+o-`^$cuC1(IVpKGEE{6uT584%r4j}Wsj(aK^Q=8>|AUiYtQxlG9PraPfz9-pa-y&h zPzaY6(l?|ekZN{__Mw9g<_h)Wb1LZ=DsJQZEX%cA$IHMkVe?4c;1rgfqf4IW(pPYP zDPBDwgVzD(COKnC-(g8&#<$qfi-c@V=C7CFeV@$ANJ=6=fPiIaZoGa40pZUA=s{@W zMG&3CJ{*urCjLh!ihhcKO%3WClTHk9X*m-1NX)qMNjm}^(jjzmQ}B}<&g$F2o+rhEGt%5|_ilmua5PdEPXRdJ_{IUt zp3WZ`$N}m;sRWi}w01lteZLN;i`I^(r?@7^Lik!oCftO&E#wIg?o}lY>>g%73_~cR z%!n)=1}vsO zk^M`8${$tEo=6viWeY zVelXP_|1<@@^u$CD}7Yq8b+d#aKLZ)Jhd>{y9j%T=2F^%r{!UJc6Ii=C7dm-?)&ozg;0y*MOus}N|4U_{xUVYI5nR=C)V9o2Ms|w)D04sR8;-j zA7-^&;Pd9U1lX`?2eMjfP^ssxR$V#hhf>!FXOL45sPmI1$A; zCw%3W#+od{mnc_Y86|vY0}H*x9~VjK0LQ@A*5^36l7=BMDIH|YaA+WBOOM;ta#ifZB}Au{u#=t>1TCi$d4B=D<)AUawmgNvZBJoU0h*n97zpVDI4-T?SF z9xRQHnf)wwZAH~4o{+60o>ho!fk+B zsuwHob7b0RSUrSu$K`M^2};rFcH$@U$=5=? zirhwQ(Yj_u=ZDLEmn7N_35a$|sUbOGl?26oh1nm=GjN^y6UAFBVr}-RfjQ!k1vELmR<6WR_#&3!igO+4)?u%J#E2*YdcXdS z;JWXm7(ttEQ48AUbLTZL%0no^@B{q0>x7;Y>PJA+3N2hG`@f4^qO9N;@MA^#h8b~2 z;YW`e)`llgBMk^jz%WdUr+u#*wKHe-9G-^?;QIn9Gt=0ga>|tA*?)L$WBFw+HHCyP5#elnJk>VL@6_#H{(n0XEVJLM;I(4-V%sH8Bejd`j` zKB~7uNMXi7dJImZ`Jb8~8}fbQsd%$U!^1g+R1j?_;IK6Ooe=x7edS%~d)X$Vj#sL& zADG3+@xZ)h@2%1p5vCTT$uW%|Q8ZF8E%~S%#|w_Brr=h4u*J{MNAGZ_T$g;@=#BUR z2%(|LiHD`Ivl#^ ze8MWaC)R8K1r9ON{*y+mCoWE@ZA8{N;phg(*%J?6v9-oIf?huXQAYwH!7<%)PPa|B0{tMQH-0l16M}PK)mIJdcN9qJQgtih3Z*W30rfJ1AlD|O;x`fHdYy*mNf)Pro%@FZP zEGED{fC76ORfVjb6iG+_i3!BbD|RCE4hX?qO2&tWha;$@JbwK>(xl>12qeTzz!YWaw^MA7vbO!0G}u+ zu7G%fOK`Y|IHB(;FFV;l(vXa`t>h`RRqa84dFk{;a+oezU?8=iC$t$#9V89BN$`Hh z!v(j}89MdsXdYurq0w5*e=&zA)PiaWCkXR(KH9tmh6{`+Zaa2aGl zjI{@*;ZnbT7?|FUW;{?04F%EQNU4wtm;E~@eA37|KLD*ETAof7aM8Bpqywf~TqLsx4UitCJ)%X2)0^UX6tq zfAw0wK3|TjI^n%1O!B?x8-NE3&Wz2v3~%#~c-r$9Cv!(nDNKmC=ifdFw0hf+?%k4^ zWFU`6hmu5Y2F&4^mT~@ad?qG|`v_b^0!| z_R#;(B}|1ALO4+qg+LtP$Xa-Y<_28iKYJ3@kB5~ah{JtT9ddVl?%caza(-b{0vm78 z{bxTuo{kJ%uyz4G@l{ADJ~M_sRdo43{@LjP5x9^ok)ha|tsBo{`QI`T(hGE4rsw}# zo|&FgOd(+T_?IXCt0wWm!L9zwCSqv+bq@_>`7eCt|1!(?-{bz<8nAqMg!Mr(Zz7XO z8%Rtr$s}^5oYKZ7>MmWaWSpv1Kke|(gWmX%m)mx;cK@P@qp#iA(6743>GX!YmlyDT zE_ATEv6rl-cgpjtZZ8U_y<`uQ27EPLqfI$vt=VrqYoLPGW)0X@)S^p@Y?ga;QFh-C z2bE3ya>Kz3YfPuQ#kbqz@}qvHU6~<&x+?j4giXxWf(eIedd#yM5_$Tmrr`7b3rvTF z@9JT3rm&A+(DU@}`}*~WY&P1%Lo&(x(2QG9WNae)a%-0>S0%!Otug&%viOWohc)ubO;{j^}pRGR=CrfzpX3MJ$>+i#1PhHwhoi%9Zv~c&i$6_BU zUI_?&ef89(!58DJ*PpKB@>?%^Zt_YcqCUU6w{y*pSHJx1^Un(Iycts6M{ zb#eLkf2=f_7uKoW{enxcL=m1D2W0PF#&ev>wv6}YEqZ9>e|@=Yw+$t}X`ajNKU;3^ zpW&M}Y$C78oxHJ8#`chB8^*66 z6{>D%pXPpVfn!O}=mt|g`X^LJ9IZ+mkhQ+?@xfBh4DEL>S$7Nx>2&J7jdmtuzC5~Q z)_}Yu_Xwr6X0NqIo8%rX{un-)enco6>&2z@`#1ty7ETtI5jKbD9BooFskj`V7f&2$ z5RQvbb~J9!6Sj{MPm4}2-rFay^@g6&?8L~8&jwvyw5La-6p23gE%Q3dh1Fe1-@WWm z?@tc!gC2NXTGL=SZ)_|{?&P;D{DSTe+BN-~i`(N_{QCR-6TkPFI{EE^CPBINTIEvg zC#jdaXODca%;dqi!X*vJg9IB1>OCwRSAmty^^#@Dbqze1UOh9kCcMR+xyxR=0)G>h zKi6mIPxD8fy755YUfU^bdW7?*c^|yB;6me+p)vLeW-iAIyW!GVbmSi-uy5L6-+v8feq={S$3rkO#RCoS#tX$7tu*M~K4-s(>5z{AOj`TkAIy+8gq z{K*dzCuyIfXZm>D*<>rb`i)P`;m$tZrgn?cC$#lRKjpEZ(~H|5&z`8Tc{e#XriSEF0?dl;>I+E1%X*Xk~|Q2A@9`{asz(889AUO|r=KV8?@ z`X8=om${Hm=jL6wGe5-FRebZ?&r5y8!{$E$pq$j;~WQe7;jQ zb<(07Z&lIHf_e88+TSE|$|t4G>KVYExBqcS+Vu3&Jzv*29PGJgS!(}r6XTQB^BOI0 zUvAYSGCF<7vK=!VZd~>lXRegr@{W@vH_*pyNy_?UpW#W{gS9rbW!v|gGe0xQ-1ud! zVeNT4WAWTCmPz^^i_JfN&a`{)-l=1guY7PeBj-lPNnT6Z_6%p0Cs>tz=GC&!DgDnl z7W3vRr`T_%JTaa3c%101v*B@%$36P%;yv?2$LQvdD1K2|v0z5E+uoX%KhKZ7e_+s)F)7csp6*bw_P~&1 z6_>v2bL|T^rRA-==d2_brkQ=N_h>L@XNbGQ=UTsy_gqjeSD$j+f9QMHPZNjFXxcWZ zhD6>zW7tj4`F*=| z;?2bV&NJsMf06iPjP7i;gINW<)aH5T&Py+t9=d)dqWaT;tGnl3_iuT;!M6QtKdBz; zGmcejrW~E%x4|Mlf9=tp1`&Bn5^ z%Uc&)eV4U0-*wBF4X5I@=1rCU&q9L+MD%;UZr|~M^X>e=aQxc8abR}o`!$A?s70Pn z4!RB-Ixe79^6j0jYgW&H<4CXQ6X6A+Bx2LdCgQHHqDY!|u zn4li!H=7ztnGWoQ1H{JwWLRP4;owJwQqnly&D35)i*;s27E zeSYiEnTI26kG`^mwr%v(Oc)@;;-B26WeJaFanhnbrPr%l1#R!e9J#hu`*tS0z<92-N&vad3>qT)5htsyy4BRda z`-lV-TywQb^O<~MM)M5`msceHBL5<<~=V=YLk->rm-|`-wXZ?fUiHu<60zVZ}$EMSa?ISiu5|j{OH+8(XZ{ z-OTCfr{3#gpUT~m)17WD^75~?4{5w=Hor1k?=f(6)`B}e7uXxRRrzPWJkqveNwaR@ zZ~g2v<~j2u8Gl8DAOatWuk)+nVB(n81~ap!fK{sFRdv#9HDs=kXj(y0}< zJMshf+8`nI(tbL z$%#f_JKe&s==_}9#+J8F$k_3GP*Ljq)&aW0?CQj$)z@lbvP5v1WRlq|w|f`o><5ya zL0{els**SR?Q39?P}rr}>ZALHwec%nJMZTktK6fzw|?P1==wbA)o|`fIUCYt-I;=> zRw(-i;1+Z3v6>L(sv-@Gw+v%P$gM z7!md-pADPJ(|l4U&AS}T&K1ueJm_lp!#leox;ATH`9XQ>OSxM=EVGaK@=TfQpuKlq zvb&dstCBbBr)cuvI9Ux&hYANGb@7*B2``$U1jx=9-JL4tWKBb3cgKa0fNH^x4o&P-SCEI8@qFqH3)2EAl z#;pvB&NjvcQHWpNEupZpc_*BE+U4?RUEXN#yP@x*n+xYl-5PajG{tuP_1jiobiKJ$ z-t|&p^GhS%7?5-K(!8GzBL z?e-VWdM~*{54TI3hKD%HW*ypCaAtOy+)*br%N_UjP>=Vociz-CreCSz?uA!U0ZG5J zplB9IGL?!kt>HJFy2zFfN@{ENqonJSpnvQx?fNue)S%_=8?85Wt&T}dn7Lx=Tc0m# z*zo7(?ONI?rguMBJ~g_kp?W_*h{&ov?l<-hICPn|)?UhX zas%s#oKF1&CTi6Y6jh|8jrC24&LR~G28RXNoNV>3#o`B6B@(|h@3?s;CH+Jf|{FPXOTMN(;v$NAC&H|OtrF`|0Wh8b_%xLML`&W2->A5ZT%zVE_;^u2Fo zKd-78;=Sz7Ta!GKPIpUObA0(TNy`r`Kf87CPRvKLIibak@4OQ;BJtf5SM0s#G>IPC z{6lpwo5XjAM{KcES$*g`p`^fsuJg&!qi6c1WwZG7>GI1n`i6~r>!A6>>T?bz7j|ur z87Q0dTsEm!^7XkNwi>>m$NVDmIb+g)YNiOYXt8?HvrA5m?|Dqx?D%f3d7i&U3+CA= zLf%j7-vqNy(Q`~hG~FKiXami@6*kbUr|~fVCJhS3!?5+|+LPy7Hw!YJtqh-Dd-gA{ z=^mCe;9<(4CM{N{`Q7Ndyv2&;jdi1*G@dqSlM|okz3F=N;`=3T;RoNh>T)*u!umPw zD~>g4w)%W8gEDrgtT$>MGwme$QGG|=p4ZT)Tlweb2pV9`dj{$Opde{=j#}CtCeF;3 z$O|gm?r(m{&ZtfL_sj_~jLwUhvT$_K-R3Ss-tlhdw570NP5ZVZhnH-cXXmb~@YuL1 zU0KqULq{aF)U-ohA z@XO&#*sFKFMEu7l08^{*q0c?z5#$WQ1D zpXcw~Uz6N6lyRVLR;tP8w zAclNa7SqUL+rHc`eSpHJbMF$;RlIkA$i`-7+4!eENmm8S+@tbel zQy)t4TQly=+)(|<9&e8RXj_&Lio|dMbzbcuM2qQD>(FRxi^L5f6J~!rJjpxyL!Hmb zH{xoR4sJGZx8e77l$DJ>=uK zmG?h2-IfuU@RCj4G{bVvs)s$~-uqU*>wG-Dha|g8Gx-szda-G{;JdG)U(?z@JXL}V@*x(@aJpSL}Rne5SceNbX!fj8|jF8SHFWI!| z^9I%nHM0lSx8R>+zF#se$J}bfu>2m;v-_MlVmsv7#4K~$Ay2$llO3GAvn1&2CVrd0 zh`XYWUi{OMclyP>+aj~dw8Yfu(8vkj&#?EoIK0GpTCujI*z$31qYd2+2c9Z@7GAMZ zICt2TR{ieaibtSX2QT*BP`$-`Vw>qdJ5KCA`0M8xZj--e(Tkr11#NQbz2nK- z4b82Jlp9C180tND?fA84?(APx*2ecvpx=)dA0N2muySTz!o>YM4v%bNu`Zz*vl#QK zyTgD~&67_$U%i^z*sh6p+Bd2z-4chN>gF@9OM0dEgk@QWCar$d@p0lEZ&mh-EB#I< zSD(6m);(O)quBw!#}%@G#v6uz{KR{G=F)a1rQ24Q+o#PuuxsPH$GbJ@l(gJ*6?^9P z7Maj-nCCU)Nog2z=>7%8?{f` zZ|~a*)h;7n{r|eU5_qV(H$2vnFxHRAURl~COZI)u8X`#}6jAC!vSi38Wf^Oc82ehb z56KdPY+sg)HOZ2M>|`6u|J)hm`}_Hgd(U$3x#ynqp67ku=NJlV)zohA-5HDKX_#}) zS7=Y~qDFR51h8Ar^R`*7jKzKS;pO3=Vlsd;i2xQrP<1jSvpEUQk^t#x|6PbmEO9|2 zlzFcx1a6sJ4whv>TYNrw00aN^|Cm>b>|i$IX}=_ZnjtW)45&9MgNUr*olDlN%mLJC%$4~|g z6FtTJDK8!7K<`yfrx-9V%p?sl20-XvqNQD3^%W~f|dFl#?fKbXZ9npBpbpo(&kbx&PmBQga zOUhsZT!-Q}kJ7N;?%keU zm|zG=dZd$}5(D70l2OtR3Bzi&G5=U-$)wYE&0}#f-C6> z#aHY*8pl4(C|U^w)R+B<^$;`IfH9h~mu&U+l&V9voc%SWW?BDh5A=csH5S6WND}7# zCGy4T;%nINYm#KD;SM`6!D=$Utwl?GK`3S_L$?VoHnTpk9VTzB2~AoimKb z639+wXI(eSwAf#s5QXtI?hZ9GeV^c3C*RrL<35_{w1LvcRp-nkh+x4r*Q?Nu1sj6O zUaSt4UIO_3mKa6m|6{b1APkq>#cA*x-4dGBPrJ`_LzvFY>$Py%=DNU~gkB#2mSSxUWlG6-JoRSrh~U-o}0Q|cc; zu2zqMDYnk5F23XG;BbWqMu`-GB6DUj_T3Lgh8p2co2`h+_GE*!g^3`+Z^Gv8LcY!U z2A&pqv4yvoH~SRG~d%ie6gf^Cg;y zygs&WH~+`OHf9anb-4@nF=Pxh$q0(i7Ziky2HdHNHkp#9GvGm2qoB6w3a7b}yO-v$ z`Qr~lW$zA{l;2EXoqd(GtP#c&3z2R<7K@GKY@8{%D!)M-gqk-zr&uc0Pgaq13&@bq z5S>TjOtzVH7Mvu<<<)GpgAUbZ>9}Xo_BBWKKUf#0*5L?DRM51ez-Y}RwI<-|>#l0ww+rBc{)hG-@))4Xr&or%*- zkiL^WcoNJv-GyY4Pxtz!LFa#=rk%`%zk8-=%TeRZ0gGh6VrA+>f0%k7Ywpn_Bu@di zB^BLuR`#!W_z0tUc)w<<>XsHa)fvSc#Xb%?Zap-!MM>?CE3mc@pMpqJ{DSLTT%JHgITrXHej9CF z6RI}Bpzs~+0#o_$%*;_uqF{U?$VnO@Z7_krVw+wheZDa zH`Dg8BoS2-C(K(OnW@lo-_4xTB`BS z9#(@f0wuTtq7)GuFwU~^K*?G+)6h6E@ml7^>jA@9!LJ+4Zj^aN)l-VpPk%%YG|%vs zQv_QM`L8j#UM&i>+3pBVoQdI{X8WjYq&Sj|KUZtXm-*RSN>1@b{?z$reY3JHxR7Bf zE$ok~!!p0=wS2cPf@&_Cs%N}Qb^Ql%R;Gv~d)=63?adIs2W$o}eEMG3;vq9j9!LfP zrVt5ArLqIdm^XR~+l#nr)+8$%y;kG+$*XK*hMJO(OcJK0N+J@b&<7I}(n@t7Vj7)> z{b5ND2N^Kgs^{$!p#WT7J-~~Wp+~42o*kf3Y5bjcc~j7gdVy2qrh9i$rzs`hj>R?4 zuCXUJC`7*qjlPXpL0hffX@R=}yBuVsh?dqJ3#jHlwA{DlN1LnisjTnp#4l6<;NYkd z9;xyNbl8y00hqJ*c5NEbyER7{IvWX%FCkZUVEjd)mqQO}%z3;KUSFE!%M*ov7J_Y} zA3CdazU|y7WTLJ^4o-WplgG}lzz>5-yKwj|w&y(hkK0^x=Kw6rEx)-i*>_e7;f$UN zxh-k!PUd2lIP?iDD7?Dw7MbiV=^wtR5otYrjF$z8``rEXo~$rnYN-<3&-1Sxm@p*w znFPz;I=rO(%-W|&HIAE6FR30ge!Bw;Qm-1gZv?+npU1Dfwt;k7WV&OinzV)Qvp}wK zQNxfqXSZ~b8==sp!Rq=s-zsnALy_L;*2~g8 zy6)x`E3|SJCo#=Nicw0jW@%qi+i#~!pX)F#u$dH{&xUK_{Q6E)DW#|Ez!X@w(L1o> zOt)^XiD2!%g8h!E%KbCtUGz>=DE;96=FHQAbWXK!OlFrEP!mIT{)=&ODd<*_>9&U|e*3smYEGBM__QUoff6JzF5u&Fs z9yPRbipTOOy0R$Lrd0CnC6UQy>EsNU!glmpOMGT6F?<5JOkyOw{1ty)lvWUtJT%Ro zr>0Fd`7MHpfWp;KniPlwf+G;oelJvlVI0S-n@zmZTCsY0yqQIc;&9{`5stn*-qP`- z8G@zn&s>Z=;Y@uHrd|aZF99D4{zRNdia{la#eTRPhjNZL?N%Y3HUF(X&~YS>NfDR@ zaOd)a%`kcF?0!?)+FoYPx0y_tJDf6)-&2Gj981N$rptCz!RYNGV^(ct7-m>OpNCpA z%sMQeeL?o*wcnbwA+EZv7p+t_Q5z`GSzCz;hLP?!5hrjWZQiA(55x=})2)lbHqyLL ztI=07Gv*8j+DtKeBl4>il4nkfOrN?B=MyuNep(>+f$Q4U8~;@EPN3${9@7O0S5li( zbdR_7PY38&DQ^^bpEmi)QTJ8C=*`$ki5a-W1YyX`Fv>Heid$RWFdx;;cpJn>&Vq@Z zHBC4wblJ)0)v-)=rOgWNNopVHWsOYdi@QFpbV#<^K#LY6seE327{@DGCD0h2ya(gB zI7WNPUwKOA@c<1J8xJEODpdnU0N%SBNTrHi!UcYme|Z5QM&mzt@(=w<+kFsOj_#pM zbqm&g@cF0k0j~62dc?J$xxNImw_TC1e^%Qy){?1);PQmU5O3f`Wi`SpmyB{2rUFsn zfttK#)eao=G5xJkQ{u}m3^pzeKyV`e=#cE;ocz|0sj7{;(;RSBfQyrbY##NO6QciY z8_OyQEFovE8;7hPmrWfiQZ|AkIdox&H&2VY6t9)tr@8!4KaZgnVe@+hk6ckoxUO!iNc_u*a%#W(Q!-xUxAlxR?fLZt$|H+t z`bQ25FOrvLp|_PcXL?d>h8&-QD2^we>L25d$O(Sm$y+jxi+<>?ptl2al5_>pEQmrZ z*$-vqrOcXIxJWV7*D#y>Vi~JZeJ1YHT1TeLlE$In`}F}~l3%>=P>IFdEh#GF%Iq@1 zkTao#JK&0*d70S}AIqzHNb%V(<-5HAH+Q?~poObkK{8`arNOXrEBiNOnEjco6>O-N zqTkBqLoKcSE&Ax*k}rU6oqyBDM$;gXRUQ0s9QQJN3U-vk_}I5yS9j(b@Ivk73d`t+ z@PquVl`96W7RNs-reX<_%18W!w8iMR+`z-Hh>dn;cQNpIuc#sCrv}Cu#2#mOnmCsA ziMuN(I}GEOL~rfKZgwd}(52-<3va?&8*nkd{TA)m#`U6vBv_IHU_)Oe>9BT`kF&cF zj2?p_)U#>&^0swpZUv>^k&RvETjxGj2uJEggFa;FCTSr6Bit}7ZQ{Wh>VY%i;|dMn z3PQdV>hj)JZl#>yYsZ$gZN=oB7LT1@nAV(1alBy5!_B@PG0DzFE&BW8i5lRr(?se4 z{~9UOlZg!#ddPM^MD^7NORUy2V-# zvsiL;eD43v>>#(8gOHdafA_Obn_R~aYgFBY3Nz|7f<0;**U>-=E4JcyV9!=i*fqnY z`}I99IcP)q^{d~9eQq6VlpYhJQHpUZk@?IkD8rwkW9XUX3$Gvh7LMd1n1758}j(fPf7`UCU z#+hW(Nro@48zpeyRT~3E8!@5>lnZs8X2WZ;GNRQHqY~%*bo>I;d^Z;5XbRIgwF?5_ zr5T++5jUjG&l$oEwIZU@6sQG}ZR6(%wD~$y^%f(AHh>J{w)HjvYbS`~j!sTJ55X8e z&s{5}ZWB9J3!{Iu1A|Qq>SuKd7X)$#QD&U?+u921lb3zxa9#76rxDEm%}re2i;@A_ zOl>Kmrlp27@UlrtwvU?G8S^GqM>|Fq?#&-+8y}rk)(K3eSfe3Pa{|G-At4z*S$iZC z+vH`R>Z`ePYW!S*q^0x$|J-vbC4Y-o9_xH90JKQ%M1dcOmVBRdnwP)!hV2^N4(v7Z zK5q>mC>=Ig9WQtZ)FutoC+mEa3fAl?R!9=@GpsQX|9(f*ewIu!IfW`^LX;LTSL=b@ zo#Z?cyGl`_T1rU23stz*HfGvuQ9$!8h)=m5R>zL?7o166ywM<5Sz|i++;+9{Au}v0-8}1r<)FaLy5ZjU z87ii^&mYq~etP>6YD8%h6GT!dLXw*qz>2-_l+(#`sxR(0br^B*-xR?fnUDVgNm24q z)Ge-QF`_0a_x-ZPOk8H6I4F5;?-yEv(ol&*LxXXOZ$$y6-(2jHHpG_vC990E*K z?}~Nml9ndCc3w8No(tU0U(w1@^f$`g0GJmsMxWCyQ&I03qhD!pu5!^+MpkXB{=r#q zi(@gDE3i8--niu_qM+Qy^MFmQ5K;Y?A@|2nBXagc;=Uq-cf(&J;yG>Zl{bq#_6lvD z;7c~jNf<#`^fVM#g#xMpZo<3a(qIrFC1qcu1>Z~yWrOhQE@ml*VysXFqR>@zPd^(- z>;L?%)|$6vJ`)+Uq2GM^w#`u$Q%d>P@tShuv)GV&zhg1x*>Uup$KvS^N?yr;NU62D z?n{XpC4GwB7dlpabJFPHY&%(B7bz;d6sLhQF#Np7O>=(6hwj${3MguF|HrTFLzU{v zOCHj285|qJckRF&8;vXbRQUp^zuTVxD(lbnWRdyCJo@U9U|}b!!->jnI(S{?d36*+ zjyXkhR-7holup!)qH!*)ghx4|Sl!Y``M7cV#tnl-ceV>bw7339w27KAA6d0i_qLD9 zwBBvWwyJ3I1XNNXSk}Ng$@@VzT5WTncw8p)lZDR_eMl*yZNmFOrNr!GyD;)UEx0C_ zys+xn8GY28FU^;3qsCKG=Ho!Yh*Pj0y74Jy=m>0@JVE8Dwf1t}vannG^+~IEd|`z+ znhd7p*Ej)Q>}D9to+KTT2-o8h)%%Vt@~F8;AbZ%2IsR?po@7Q@*&#bPCk0a#cgK zT@HvJmv8)e?PTdtd0WL1Vfmzae_q9YK0ti(#XZ!W!gGkr zfDw66NiQz3a8J~ZVpV0%AKhzM)OCx6V6TwCa%yhl12n%*N`x71SC7{PQ9>_2(F%T6Kui^G#*-@z?g*4F)L z07mmkx(jULWQ14(iym9Gt$@m*S~`z6%p=p>7jaL5_xBHc4e8=Og~62btA=eo#rL0- z?yX8WKDbhvbJ>BhYgFgYhJmJ5m9N)V?S$vZ0;bX0{7mr5$%b~%F)5SW0!PKvgyBC; z{QEowmE_k~h`|naHu!s+i0PPkhM9~hYrTcn=SQS;<8R@*Ia{M=(>5rrzn6%b4w4+u zUBR}A8_7oBA$p_f`kf?8y=#W0iLN5Cj3GL^5olNOXxhTce z2NfrFV3;DgN8M!qeCf`vYr4a%v%wHN(t-KbHXWC5duRtX=ACncLr!1EKwJmx4Oj>s zQ4QosR>ja5yFqe33{5Gku<-~7zZP29C}mdmppmyxIspR?^ZS<%{o zMa()r^SBLmyF38vo<8ZNDdYrHDgIub?w^iP`uBZ`oJF|mJ-&$W-I4U3r>j#Xn$FL6 zSs`8_GIQPI6yxWC%eVLiJxL}LXq#u;cm*-v!lwJH?XtJE%53dc*&Mwvc0}V6F>^<3 z*t7{-*?zN?z+ngw^;csalds+BQ|ET~ZTKG6_-4Es(d*D|_n`eQW%Oryit=0o`Gx|Z z#)tO37?w%Y`J3?ZRvHpZxabslw?u#csI>&}za5|IUQ z$z?7*RyseFUr29}(xZ}dXSf$&L89s6b<5oBUMMoIe7hWZ!tFc$3hN*_^@7|4A2OpN zN`+9i^0v3glv$`Gqu-;To4I*ygCS}y79^)yx2)i%Ya(O63HDvzhEM3;jo_`}&$ky) zbrmeiXkvc!Jo|}Odq=34k+{(8KLhmMal>#MD!Fe~ZS690S^&g_c{OlN#bC{&KTd0)8n4+?GSswAQxyP)?3!kwX6o~} z4eqc}(3RDVBOhmYa(`QfUfvY6*c3Ets%q@k*^r8_LJWPs{zL|sEHkzx+Ne!fbDD1~ zH|(szDT7Ly)rU`T`o`KOZEXzIw#N!izL4wKT2rFS8M>ZfImui9D9FHtWw{1Cfg-_W z1mnWL{O>g?y{%;>`m7;iaLoG%Qzt$4nr}u%1CG7S{`p}l@d(fmZp{Od*EWcb|VsnrOm|gZIg{+A!2gE$H?pT_)%ti;dy-=FHHN{|>B;B7X;VmD&7wvv%|3X2*%ilaUerjq6GG z{{{!6hD+)@unUMK5Lh_)x#gn-cA@bx!6;zl*;siAiI F{|Em`p$h;2 From c6cff3f6f448e8f4da5f15babd3635d6473cfda2 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Fri, 5 Sep 2025 13:58:48 +0100 Subject: [PATCH 126/321] feat(cdk): add generic key-value store functionality for mint databases (#1022) * 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 --- CHANGELOG.md | 6 + crates/cashu/src/nuts/nut01/public_key.rs | 14 +- crates/cdk-common/src/database/mint/mod.rs | 136 ++++++++++- crates/cdk-common/src/database/mint/test.rs | 99 +++++++- .../src/database/mint/test_kvstore.rs | 207 +++++++++++++++++ crates/cdk-common/src/database/mod.rs | 13 +- crates/cdk-common/src/error.rs | 3 + crates/cdk-mintd/src/lib.rs | 80 +++++-- crates/cdk-mintd/src/setup.rs | 9 + .../src/bin/payment_processor.rs | 5 +- crates/cdk-sql-common/src/mint/migrations.rs | 2 + .../migrations/postgres/3_add_kv_store.sql | 18 ++ .../sqlite/20250901090000_add_kv_store.sql | 18 ++ crates/cdk-sql-common/src/mint/mod.rs | 219 ++++++++++++++++++ crates/cdk/src/lib.rs | 4 +- 15 files changed, 796 insertions(+), 37 deletions(-) create mode 100644 crates/cdk-common/src/database/mint/test_kvstore.rs create mode 100644 crates/cdk-sql-common/src/mint/migrations/postgres/3_add_kv_store.sql create mode 100644 crates/cdk-sql-common/src/mint/migrations/sqlite/20250901090000_add_kv_store.sql diff --git a/CHANGELOG.md b/CHANGELOG.md index 738b33c59..45be50e22 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,12 @@ - cdk-common: New `Event` enum for payment event handling with `PaymentReceived` variant ([thesimplekid]). - cdk-common: Added `payment_method` field to `MeltQuote` struct for tracking payment method type ([thesimplekid]). - cdk-sql-common: Database migration to add `payment_method` column to melt_quote table for SQLite and PostgreSQL ([thesimplekid]). +- cdk-common: New `MintKVStoreDatabase` trait providing generic key-value storage functionality for mint databases ([thesimplekid]). +- cdk-common: Added `KVStoreTransaction` trait for transactional key-value operations with read, write, remove, and list capabilities ([thesimplekid]). +- cdk-common: Added validation functions for KV store namespace and key parameters with ASCII character and length restrictions ([thesimplekid]). +- cdk-common: Added comprehensive test module for KV store functionality with transaction and isolation testing ([thesimplekid]). +- cdk-sql-common: Database migration to add `kv_store` table for generic key-value storage in SQLite and PostgreSQL ([thesimplekid]). +- cdk-sql-common: Implementation of `MintKVStoreDatabase` trait for SQL-based databases with namespace support ([thesimplekid]). ### Changed - cdk-common: Refactored `MintPayment` trait method `wait_any_incoming_payment` to `wait_payment_event` with event-driven architecture ([thesimplekid]). diff --git a/crates/cashu/src/nuts/nut01/public_key.rs b/crates/cashu/src/nuts/nut01/public_key.rs index ab6b862e4..7e0023d85 100644 --- a/crates/cashu/src/nuts/nut01/public_key.rs +++ b/crates/cashu/src/nuts/nut01/public_key.rs @@ -142,19 +142,17 @@ mod tests { #[test] pub fn test_public_key_from_hex() { // Compressed - assert!( - (PublicKey::from_hex( - "02194603ffa36356f4a56b7df9371fc3192472351453ec7398b8da8117e7c3e104" - ) - .is_ok()) - ); + assert!(PublicKey::from_hex( + "02194603ffa36356f4a56b7df9371fc3192472351453ec7398b8da8117e7c3e104" + ) + .is_ok()); } #[test] pub fn test_invalid_public_key_from_hex() { // Uncompressed (is valid but is cashu must be compressed?) - assert!((PublicKey::from_hex("04fd4ce5a16b65576145949e6f99f445f8249fee17c606b688b504a849cdc452de3625246cb2c27dac965cb7200a5986467eee92eb7d496bbf1453b074e223e481") - .is_err())) + assert!(PublicKey::from_hex("04fd4ce5a16b65576145949e6f99f445f8249fee17c606b688b504a849cdc452de3625246cb2c27dac965cb7200a5986467eee92eb7d496bbf1453b074e223e481") + .is_err()) } } diff --git a/crates/cdk-common/src/database/mint/mod.rs b/crates/cdk-common/src/database/mint/mod.rs index a48d29c32..3451e6b50 100644 --- a/crates/cdk-common/src/database/mint/mod.rs +++ b/crates/cdk-common/src/database/mint/mod.rs @@ -2,6 +2,66 @@ use std::collections::HashMap; +/// Valid ASCII characters for namespace and key strings in KV store +pub const KVSTORE_NAMESPACE_KEY_ALPHABET: &str = + "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-"; + +/// Maximum length for namespace and key strings in KV store +pub const KVSTORE_NAMESPACE_KEY_MAX_LEN: usize = 120; + +/// Validates that a string contains only valid KV store characters and is within length limits +pub fn validate_kvstore_string(s: &str) -> Result<(), Error> { + if s.len() > KVSTORE_NAMESPACE_KEY_MAX_LEN { + return Err(Error::KVStoreInvalidKey(format!( + "{} exceeds maximum length of key characters", + KVSTORE_NAMESPACE_KEY_MAX_LEN + ))); + } + + if !s + .chars() + .all(|c| KVSTORE_NAMESPACE_KEY_ALPHABET.contains(c)) + { + return Err(Error::KVStoreInvalidKey("key contains invalid characters. Only ASCII letters, numbers, underscore, and hyphen are allowed".to_string())); + } + + Ok(()) +} + +/// Validates namespace and key parameters for KV store operations +pub fn validate_kvstore_params( + primary_namespace: &str, + secondary_namespace: &str, + key: &str, +) -> Result<(), Error> { + // Validate primary namespace + validate_kvstore_string(primary_namespace)?; + + // Validate secondary namespace + validate_kvstore_string(secondary_namespace)?; + + // Validate key + validate_kvstore_string(key)?; + + // Check empty namespace rules + if primary_namespace.is_empty() && !secondary_namespace.is_empty() { + return Err(Error::KVStoreInvalidKey( + "If primary_namespace is empty, secondary_namespace must also be empty".to_string(), + )); + } + + // Check for potential collisions between keys and namespaces in the same namespace + let namespace_key = format!("{}/{}", primary_namespace, secondary_namespace); + if key == primary_namespace || key == secondary_namespace || key == namespace_key { + return Err(Error::KVStoreInvalidKey(format!( + "Key '{}' conflicts with namespace names", + key + ))); + } + + Ok(()) +} + use async_trait::async_trait; use cashu::quote_id::QuoteId; use cashu::{Amount, MintInfo}; @@ -20,6 +80,9 @@ mod auth; #[cfg(feature = "test")] pub mod test; +#[cfg(test)] +mod test_kvstore; + #[cfg(feature = "auth")] pub use auth::{MintAuthDatabase, MintAuthTransaction}; @@ -263,6 +326,42 @@ pub trait DbTransactionFinalizer { async fn rollback(self: Box) -> Result<(), Self::Err>; } +/// Key-Value Store Transaction trait +#[async_trait] +pub trait KVStoreTransaction<'a, Error>: DbTransactionFinalizer { + /// Read value from key-value store + async fn kv_read( + &mut self, + primary_namespace: &str, + secondary_namespace: &str, + key: &str, + ) -> Result>, Error>; + + /// Write value to key-value store + async fn kv_write( + &mut self, + primary_namespace: &str, + secondary_namespace: &str, + key: &str, + value: &[u8], + ) -> Result<(), Error>; + + /// Remove value from key-value store + async fn kv_remove( + &mut self, + primary_namespace: &str, + secondary_namespace: &str, + key: &str, + ) -> Result<(), Error>; + + /// List keys in a namespace + async fn kv_list( + &mut self, + primary_namespace: &str, + secondary_namespace: &str, + ) -> Result, Error>; +} + /// Base database writer #[async_trait] pub trait Transaction<'a, Error>: @@ -270,6 +369,7 @@ pub trait Transaction<'a, Error>: + QuotesTransaction<'a, Err = Error> + SignaturesTransaction<'a, Err = Error> + ProofsTransaction<'a, Err = Error> + + KVStoreTransaction<'a, Error> { /// Set [`QuoteTTL`] async fn set_quote_ttl(&mut self, quote_ttl: QuoteTTL) -> Result<(), Error>; @@ -278,10 +378,44 @@ pub trait Transaction<'a, Error>: async fn set_mint_info(&mut self, mint_info: MintInfo) -> Result<(), Error>; } +/// Key-Value Store Database trait +#[async_trait] +pub trait KVStoreDatabase { + /// KV Store Database Error + type Err: Into + From; + + /// Read value from key-value store + async fn kv_read( + &self, + primary_namespace: &str, + secondary_namespace: &str, + key: &str, + ) -> Result>, Self::Err>; + + /// List keys in a namespace + async fn kv_list( + &self, + primary_namespace: &str, + secondary_namespace: &str, + ) -> Result, Self::Err>; +} + +/// Key-Value Store Database trait +#[async_trait] +pub trait KVStore: KVStoreDatabase { + /// Beings a KV transaction + async fn begin_transaction<'a>( + &'a self, + ) -> Result + Send + Sync + 'a>, Error>; +} + /// Mint Database trait #[async_trait] pub trait Database: - QuotesDatabase + ProofsDatabase + SignaturesDatabase + KVStoreDatabase + + QuotesDatabase + + ProofsDatabase + + SignaturesDatabase { /// Beings a transaction async fn begin_transaction<'a>( diff --git a/crates/cdk-common/src/database/mint/test.rs b/crates/cdk-common/src/database/mint/test.rs index e7455fd22..de4011041 100644 --- a/crates/cdk-common/src/database/mint/test.rs +++ b/crates/cdk-common/src/database/mint/test.rs @@ -4,17 +4,19 @@ //! implementation use std::str::FromStr; +// For derivation path parsing +use bitcoin::bip32::DerivationPath; use cashu::secret::Secret; use cashu::{Amount, CurrencyUnit, SecretKey}; use super::*; -use crate::database; +use crate::database::MintKVStoreDatabase; use crate::mint::MintKeySetInfo; #[inline] async fn setup_keyset(db: &DB) -> Id where - DB: KeysDatabase, + DB: KeysDatabase, { let keyset_id = Id::from_str("00916bbf7ef91a36").unwrap(); let keyset_info = MintKeySetInfo { @@ -23,7 +25,7 @@ where active: true, valid_from: 0, final_expiry: None, - derivation_path: bitcoin::bip32::DerivationPath::from_str("m/0'/0'/0'").unwrap(), + derivation_path: DerivationPath::from_str("m/0'/0'/0'").unwrap(), derivation_path_index: Some(0), max_order: 32, input_fee_ppk: 0, @@ -37,7 +39,7 @@ where /// State transition test pub async fn state_transition(db: DB) where - DB: Database + KeysDatabase, + DB: Database + KeysDatabase, { let keyset_id = setup_keyset(&db).await; @@ -83,7 +85,7 @@ where /// other tests pub async fn add_and_find_proofs(db: DB) where - DB: Database + KeysDatabase, + DB: Database + KeysDatabase, { let keyset_id = setup_keyset(&db).await; @@ -124,12 +126,99 @@ where assert_eq!(proofs_from_db.unwrap().len(), 2); } +/// Test KV store functionality including write, read, list, update, and remove operations +pub async fn kvstore_functionality(db: DB) +where + DB: Database + MintKVStoreDatabase, +{ + // Test basic read/write operations in transaction + { + let mut tx = Database::begin_transaction(&db).await.unwrap(); + + // Write some test data + tx.kv_write("test_namespace", "sub_namespace", "key1", b"value1") + .await + .unwrap(); + tx.kv_write("test_namespace", "sub_namespace", "key2", b"value2") + .await + .unwrap(); + tx.kv_write("test_namespace", "other_sub", "key3", b"value3") + .await + .unwrap(); + + // Read back the data in the transaction + let value1 = tx + .kv_read("test_namespace", "sub_namespace", "key1") + .await + .unwrap(); + assert_eq!(value1, Some(b"value1".to_vec())); + + // List keys in namespace + let keys = tx.kv_list("test_namespace", "sub_namespace").await.unwrap(); + assert_eq!(keys, vec!["key1", "key2"]); + + // Commit transaction + tx.commit().await.unwrap(); + } + + // Test read operations after commit + { + let value1 = db + .kv_read("test_namespace", "sub_namespace", "key1") + .await + .unwrap(); + assert_eq!(value1, Some(b"value1".to_vec())); + + let keys = db.kv_list("test_namespace", "sub_namespace").await.unwrap(); + assert_eq!(keys, vec!["key1", "key2"]); + + let other_keys = db.kv_list("test_namespace", "other_sub").await.unwrap(); + assert_eq!(other_keys, vec!["key3"]); + } + + // Test update and remove operations + { + let mut tx = Database::begin_transaction(&db).await.unwrap(); + + // Update existing key + tx.kv_write("test_namespace", "sub_namespace", "key1", b"updated_value1") + .await + .unwrap(); + + // Remove a key + tx.kv_remove("test_namespace", "sub_namespace", "key2") + .await + .unwrap(); + + tx.commit().await.unwrap(); + } + + // Verify updates + { + let value1 = db + .kv_read("test_namespace", "sub_namespace", "key1") + .await + .unwrap(); + assert_eq!(value1, Some(b"updated_value1".to_vec())); + + let value2 = db + .kv_read("test_namespace", "sub_namespace", "key2") + .await + .unwrap(); + assert_eq!(value2, None); + + let keys = db.kv_list("test_namespace", "sub_namespace").await.unwrap(); + assert_eq!(keys, vec!["key1"]); + } +} + /// Unit test that is expected to be passed for a correct database implementation #[macro_export] macro_rules! mint_db_test { ($make_db_fn:ident) => { mint_db_test!(state_transition, $make_db_fn); mint_db_test!(add_and_find_proofs, $make_db_fn); + mint_db_test!(kvstore_functionality, $make_db_fn); }; ($name:ident, $make_db_fn:ident) => { #[tokio::test] diff --git a/crates/cdk-common/src/database/mint/test_kvstore.rs b/crates/cdk-common/src/database/mint/test_kvstore.rs new file mode 100644 index 000000000..6c516d91e --- /dev/null +++ b/crates/cdk-common/src/database/mint/test_kvstore.rs @@ -0,0 +1,207 @@ +//! Tests for KV store validation requirements + +#[cfg(test)] +mod tests { + use crate::database::mint::{ + validate_kvstore_params, validate_kvstore_string, KVSTORE_NAMESPACE_KEY_ALPHABET, + KVSTORE_NAMESPACE_KEY_MAX_LEN, + }; + + #[test] + fn test_validate_kvstore_string_valid_inputs() { + // Test valid strings + assert!(validate_kvstore_string("").is_ok()); + assert!(validate_kvstore_string("abc").is_ok()); + assert!(validate_kvstore_string("ABC").is_ok()); + assert!(validate_kvstore_string("123").is_ok()); + assert!(validate_kvstore_string("test_key").is_ok()); + assert!(validate_kvstore_string("test-key").is_ok()); + assert!(validate_kvstore_string("test_KEY-123").is_ok()); + + // Test max length string + let max_length_str = "a".repeat(KVSTORE_NAMESPACE_KEY_MAX_LEN); + assert!(validate_kvstore_string(&max_length_str).is_ok()); + } + + #[test] + fn test_validate_kvstore_string_invalid_length() { + // Test string too long + let too_long_str = "a".repeat(KVSTORE_NAMESPACE_KEY_MAX_LEN + 1); + let result = validate_kvstore_string(&too_long_str); + assert!(result.is_err()); + assert!(result + .unwrap_err() + .to_string() + .contains("exceeds maximum length")); + } + + #[test] + fn test_validate_kvstore_string_invalid_characters() { + // Test invalid characters + let invalid_chars = vec![ + "test@key", // @ + "test key", // space + "test.key", // . + "test/key", // / + "test\\key", // \ + "test+key", // + + "test=key", // = + "test!key", // ! + "test#key", // # + "test$key", // $ + "test%key", // % + "test&key", // & + "test*key", // * + "test(key", // ( + "test)key", // ) + "test[key", // [ + "test]key", // ] + "test{key", // { + "test}key", // } + "test|key", // | + "test;key", // ; + "test:key", // : + "test'key", // ' + "test\"key", // " + "testkey", // > + "test,key", // , + "test?key", // ? + "test~key", // ~ + "test`key", // ` + ]; + + for invalid_str in invalid_chars { + let result = validate_kvstore_string(invalid_str); + assert!(result.is_err(), "Expected '{}' to be invalid", invalid_str); + assert!(result + .unwrap_err() + .to_string() + .contains("invalid characters")); + } + } + + #[test] + fn test_validate_kvstore_params_valid() { + // Test valid parameter combinations + assert!(validate_kvstore_params("primary", "secondary", "key").is_ok()); + assert!(validate_kvstore_params("primary", "", "key").is_ok()); + assert!(validate_kvstore_params("", "", "key").is_ok()); + assert!(validate_kvstore_params("p1", "s1", "different_key").is_ok()); + } + + #[test] + fn test_validate_kvstore_params_empty_namespace_rules() { + // Test empty namespace rules: if primary is empty, secondary must be empty too + let result = validate_kvstore_params("", "secondary", "key"); + assert!(result.is_err()); + assert!(result + .unwrap_err() + .to_string() + .contains("If primary_namespace is empty")); + } + + #[test] + fn test_validate_kvstore_params_collision_prevention() { + // Test collision prevention between keys and namespaces + let test_cases = vec![ + ("primary", "secondary", "primary"), // key matches primary namespace + ("primary", "secondary", "secondary"), // key matches secondary namespace + ]; + + for (primary, secondary, key) in test_cases { + let result = validate_kvstore_params(primary, secondary, key); + assert!( + result.is_err(), + "Expected collision for key '{}' with namespaces '{}'/'{}'", + key, + primary, + secondary + ); + let error_msg = result.unwrap_err().to_string(); + assert!(error_msg.contains("conflicts with namespace")); + } + + // Test that a combined namespace string would be invalid due to the slash character + let result = validate_kvstore_params("primary", "secondary", "primary_secondary"); + assert!(result.is_ok(), "This should be valid - no actual collision"); + } + + #[test] + fn test_validate_kvstore_params_invalid_strings() { + // Test invalid characters in any parameter + let result = validate_kvstore_params("primary@", "secondary", "key"); + assert!(result.is_err()); + + let result = validate_kvstore_params("primary", "secondary!", "key"); + assert!(result.is_err()); + + let result = validate_kvstore_params("primary", "secondary", "key with space"); + assert!(result.is_err()); + } + + #[test] + fn test_alphabet_constants() { + // Verify the alphabet constant is as expected + assert_eq!( + KVSTORE_NAMESPACE_KEY_ALPHABET, + "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-" + ); + assert_eq!(KVSTORE_NAMESPACE_KEY_MAX_LEN, 120); + } + + #[test] + fn test_alphabet_coverage() { + // Test that all valid characters are actually accepted + for ch in KVSTORE_NAMESPACE_KEY_ALPHABET.chars() { + let test_str = ch.to_string(); + assert!( + validate_kvstore_string(&test_str).is_ok(), + "Character '{}' should be valid", + ch + ); + } + } + + #[test] + fn test_namespace_segmentation_examples() { + // Test realistic namespace segmentation scenarios + + // Valid segmentation examples + let valid_examples = vec![ + ("wallets", "user123", "balance"), + ("quotes", "mint", "quote_12345"), + ("keysets", "", "active_keyset"), + ("", "", "global_config"), + ("auth", "session_456", "token"), + ("mint_info", "", "version"), + ]; + + for (primary, secondary, key) in valid_examples { + assert!( + validate_kvstore_params(primary, secondary, key).is_ok(), + "Valid example should pass: '{}'/'{}'/'{}'", + primary, + secondary, + key + ); + } + } + + #[test] + fn test_per_namespace_uniqueness() { + // This test documents the requirement that implementations should ensure + // per-namespace key uniqueness. The validation function doesn't enforce + // database-level uniqueness (that's handled by the database schema), + // but ensures naming conflicts don't occur between keys and namespaces. + + // These should be valid (different namespaces) + assert!(validate_kvstore_params("ns1", "sub1", "key1").is_ok()); + assert!(validate_kvstore_params("ns2", "sub1", "key1").is_ok()); // same key, different primary namespace + assert!(validate_kvstore_params("ns1", "sub2", "key1").is_ok()); // same key, different secondary namespace + + // These should fail (collision within namespace) + assert!(validate_kvstore_params("ns1", "sub1", "ns1").is_err()); // key conflicts with primary namespace + assert!(validate_kvstore_params("ns1", "sub1", "sub1").is_err()); // key conflicts with secondary namespace + } +} diff --git a/crates/cdk-common/src/database/mod.rs b/crates/cdk-common/src/database/mod.rs index 51b201188..6abcfe288 100644 --- a/crates/cdk-common/src/database/mod.rs +++ b/crates/cdk-common/src/database/mod.rs @@ -8,10 +8,11 @@ mod wallet; #[cfg(feature = "mint")] pub use mint::{ Database as MintDatabase, DbTransactionFinalizer as MintDbWriterFinalizer, - KeysDatabase as MintKeysDatabase, KeysDatabaseTransaction as MintKeyDatabaseTransaction, - ProofsDatabase as MintProofsDatabase, ProofsTransaction as MintProofsTransaction, - QuotesDatabase as MintQuotesDatabase, QuotesTransaction as MintQuotesTransaction, - SignaturesDatabase as MintSignaturesDatabase, + KVStore as MintKVStore, KVStoreDatabase as MintKVStoreDatabase, + KVStoreTransaction as MintKVStoreTransaction, KeysDatabase as MintKeysDatabase, + KeysDatabaseTransaction as MintKeyDatabaseTransaction, ProofsDatabase as MintProofsDatabase, + ProofsTransaction as MintProofsTransaction, QuotesDatabase as MintQuotesDatabase, + QuotesTransaction as MintQuotesTransaction, SignaturesDatabase as MintSignaturesDatabase, SignaturesTransaction as MintSignatureTransaction, Transaction as MintTransaction, }; #[cfg(all(feature = "mint", feature = "auth"))] @@ -187,6 +188,10 @@ pub enum Error { /// QuoteNotFound #[error("Quote not found")] QuoteNotFound, + + /// KV Store invalid key or namespace + #[error("Invalid KV store key or namespace: {0}")] + KVStoreInvalidKey(String), } #[cfg(feature = "mint")] diff --git a/crates/cdk-common/src/error.rs b/crates/cdk-common/src/error.rs index b4dc1014a..0b782f996 100644 --- a/crates/cdk-common/src/error.rs +++ b/crates/cdk-common/src/error.rs @@ -271,6 +271,9 @@ pub enum Error { /// Transaction not found #[error("Transaction not found")] TransactionNotFound, + /// KV Store invalid key or namespace + #[error("Invalid KV store key or namespace: {0}")] + KVStoreInvalidKey(String), /// Custom Error #[error("`{0}`")] Custom(String), diff --git a/crates/cdk-mintd/src/lib.rs b/crates/cdk-mintd/src/lib.rs index 1df625991..ec6df6f8f 100644 --- a/crates/cdk-mintd/src/lib.rs +++ b/crates/cdk-mintd/src/lib.rs @@ -14,7 +14,7 @@ use anyhow::{anyhow, bail, Result}; use axum::Router; use bip39::Mnemonic; // internal crate modules -use cdk::cdk_database::{self, MintDatabase, MintKeysDatabase}; +use cdk::cdk_database::{self, MintDatabase, MintKVStore, MintKeysDatabase}; use cdk::cdk_payment; use cdk::cdk_payment::MintPayment; use cdk::mint::{Mint, MintBuilder, MintMeltLimits}; @@ -94,9 +94,10 @@ async fn initial_setup( ) -> Result<( Arc + Send + Sync>, Arc + Send + Sync>, + Arc + Send + Sync>, )> { - let (localstore, keystore) = setup_database(settings, work_dir, db_password).await?; - Ok((localstore, keystore)) + let (localstore, keystore, kv) = setup_database(settings, work_dir, db_password).await?; + Ok((localstore, keystore, kv)) } /// Sets up and initializes a tracing subscriber with custom log filtering. @@ -253,14 +254,16 @@ async fn setup_database( ) -> Result<( Arc + Send + Sync>, Arc + Send + Sync>, + Arc + Send + Sync>, )> { match settings.database.engine { #[cfg(feature = "sqlite")] DatabaseEngine::Sqlite => { let db = setup_sqlite_database(_work_dir, _db_password).await?; let localstore: Arc + Send + Sync> = db.clone(); + let kv: Arc + Send + Sync> = db.clone(); let keystore: Arc + Send + Sync> = db; - Ok((localstore, keystore)) + Ok((localstore, keystore, kv)) } #[cfg(feature = "postgres")] DatabaseEngine::Postgres => { @@ -279,11 +282,13 @@ async fn setup_database( let localstore: Arc + Send + Sync> = pg_db.clone(); #[cfg(feature = "postgres")] + let kv: Arc + Send + Sync> = pg_db.clone(); + #[cfg(feature = "postgres")] let keystore: Arc< dyn MintKeysDatabase + Send + Sync, > = pg_db; #[cfg(feature = "postgres")] - return Ok((localstore, keystore)); + return Ok((localstore, keystore, kv)); #[cfg(not(feature = "postgres"))] bail!("PostgreSQL support not compiled in. Enable the 'postgres' feature to use PostgreSQL database.") @@ -326,6 +331,7 @@ async fn configure_mint_builder( mint_builder: MintBuilder, runtime: Option>, work_dir: &Path, + kv_store: Option + Send + Sync>>, ) -> Result<(MintBuilder, Vec)> { let mut ln_routers = vec![]; @@ -333,9 +339,15 @@ async fn configure_mint_builder( let mint_builder = configure_basic_info(settings, mint_builder); // Configure lightning backend - let mint_builder = - configure_lightning_backend(settings, mint_builder, &mut ln_routers, runtime, work_dir) - .await?; + let mint_builder = configure_lightning_backend( + settings, + mint_builder, + &mut ln_routers, + runtime, + work_dir, + kv_store, + ) + .await?; // Configure caching let mint_builder = configure_cache(settings, mint_builder); @@ -400,6 +412,7 @@ async fn configure_lightning_backend( ln_routers: &mut Vec, _runtime: Option>, work_dir: &Path, + _kv_store: Option + Send + Sync>>, ) -> Result { let mint_melt_limits = MintMeltLimits { mint_min: settings.ln.min_mint, @@ -418,7 +431,14 @@ async fn configure_lightning_backend( .clone() .expect("Config checked at load that cln is some"); let cln = cln_settings - .setup(ln_routers, settings, CurrencyUnit::Msat, None, work_dir) + .setup( + ln_routers, + settings, + CurrencyUnit::Msat, + None, + work_dir, + None, + ) .await?; mint_builder = configure_backend_for_unit( @@ -434,7 +454,14 @@ async fn configure_lightning_backend( LnBackend::LNbits => { let lnbits_settings = settings.clone().lnbits.expect("Checked on config load"); let lnbits = lnbits_settings - .setup(ln_routers, settings, CurrencyUnit::Sat, None, work_dir) + .setup( + ln_routers, + settings, + CurrencyUnit::Sat, + None, + work_dir, + None, + ) .await?; mint_builder = configure_backend_for_unit( @@ -450,7 +477,14 @@ async fn configure_lightning_backend( LnBackend::Lnd => { let lnd_settings = settings.clone().lnd.expect("Checked at config load"); let lnd = lnd_settings - .setup(ln_routers, settings, CurrencyUnit::Msat, None, work_dir) + .setup( + ln_routers, + settings, + CurrencyUnit::Msat, + None, + work_dir, + None, + ) .await?; mint_builder = configure_backend_for_unit( @@ -469,7 +503,14 @@ async fn configure_lightning_backend( for unit in fake_wallet.clone().supported_units { let fake = fake_wallet - .setup(ln_routers, settings, unit.clone(), None, work_dir) + .setup( + ln_routers, + settings, + unit.clone(), + None, + work_dir, + _kv_store.clone(), + ) .await?; mint_builder = configure_backend_for_unit( @@ -498,7 +539,7 @@ async fn configure_lightning_backend( for unit in grpc_processor.clone().supported_units { tracing::debug!("Adding unit: {:?}", unit); let processor = grpc_processor - .setup(ln_routers, settings, unit.clone(), None, work_dir) + .setup(ln_routers, settings, unit.clone(), None, work_dir, None) .await?; mint_builder = configure_backend_for_unit( @@ -517,7 +558,14 @@ async fn configure_lightning_backend( tracing::info!("Using LDK Node backend: {:?}", ldk_node_settings); let ldk_node = ldk_node_settings - .setup(ln_routers, settings, CurrencyUnit::Sat, _runtime, work_dir) + .setup( + ln_routers, + settings, + CurrencyUnit::Sat, + _runtime, + work_dir, + None, + ) .await?; mint_builder = configure_backend_for_unit( @@ -1015,12 +1063,12 @@ pub async fn run_mintd_with_shutdown( db_password: Option, runtime: Option>, ) -> Result<()> { - let (localstore, keystore) = initial_setup(work_dir, settings, db_password.clone()).await?; + let (localstore, keystore, kv) = initial_setup(work_dir, settings, db_password.clone()).await?; let mint_builder = MintBuilder::new(localstore); let (mint_builder, ln_routers) = - configure_mint_builder(settings, mint_builder, runtime, work_dir).await?; + configure_mint_builder(settings, mint_builder, runtime, work_dir, Some(kv)).await?; #[cfg(feature = "auth")] let mint_builder = setup_authentication(settings, work_dir, mint_builder, db_password).await?; diff --git a/crates/cdk-mintd/src/setup.rs b/crates/cdk-mintd/src/setup.rs index ec03fd330..dfaeddf86 100644 --- a/crates/cdk-mintd/src/setup.rs +++ b/crates/cdk-mintd/src/setup.rs @@ -3,6 +3,7 @@ use std::collections::HashMap; #[cfg(feature = "fakewallet")] use std::collections::HashSet; use std::path::Path; +use std::sync::Arc; #[cfg(feature = "cln")] use anyhow::anyhow; @@ -10,6 +11,7 @@ use async_trait::async_trait; use axum::Router; #[cfg(feature = "fakewallet")] use bip39::rand::{thread_rng, Rng}; +use cdk::cdk_database::MintKVStore; use cdk::cdk_payment::MintPayment; use cdk::nuts::CurrencyUnit; #[cfg(any( @@ -34,6 +36,7 @@ pub trait LnBackendSetup { unit: CurrencyUnit, runtime: Option>, work_dir: &Path, + kv_store: Option + Send + Sync>>, ) -> anyhow::Result; } @@ -47,6 +50,7 @@ impl LnBackendSetup for config::Cln { _unit: CurrencyUnit, _runtime: Option>, _work_dir: &Path, + _kv_store: Option + Send + Sync>>, ) -> anyhow::Result { let cln_socket = expand_path( self.rpc_path @@ -76,6 +80,7 @@ impl LnBackendSetup for config::LNbits { _unit: CurrencyUnit, _runtime: Option>, _work_dir: &Path, + _kv_store: Option + Send + Sync>>, ) -> anyhow::Result { let admin_api_key = &self.admin_api_key; let invoice_api_key = &self.invoice_api_key; @@ -110,6 +115,7 @@ impl LnBackendSetup for config::Lnd { _unit: CurrencyUnit, _runtime: Option>, _work_dir: &Path, + _kv_store: Option + Send + Sync>>, ) -> anyhow::Result { let address = &self.address; let cert_file = &self.cert_file; @@ -142,6 +148,7 @@ impl LnBackendSetup for config::FakeWallet { unit: CurrencyUnit, _runtime: Option>, _work_dir: &Path, + _kv_store: Option + Send + Sync>>, ) -> anyhow::Result { let fee_reserve = FeeReserve { min_fee_reserve: self.reserve_fee_min, @@ -174,6 +181,7 @@ impl LnBackendSetup for config::GrpcProcessor { _unit: CurrencyUnit, _runtime: Option>, _work_dir: &Path, + _kv_store: Option + Send + Sync>>, ) -> anyhow::Result { let payment_processor = cdk_payment_processor::PaymentProcessorClient::new( &self.addr, @@ -196,6 +204,7 @@ impl LnBackendSetup for config::LdkNode { _unit: CurrencyUnit, runtime: Option>, work_dir: &Path, + _kv_store: Option + Send + Sync>>, ) -> anyhow::Result { use std::net::SocketAddr; diff --git a/crates/cdk-payment-processor/src/bin/payment_processor.rs b/crates/cdk-payment-processor/src/bin/payment_processor.rs index 1381198c9..d110583de 100644 --- a/crates/cdk-payment-processor/src/bin/payment_processor.rs +++ b/crates/cdk-payment-processor/src/bin/payment_processor.rs @@ -1,5 +1,5 @@ #[cfg(feature = "fake")] -use std::collections::{HashMap, HashSet}; +use std::collections::HashSet; use std::env; use std::path::PathBuf; #[cfg(any(feature = "cln", feature = "lnd", feature = "fake"))] @@ -110,6 +110,9 @@ async fn main() -> anyhow::Result<()> { } #[cfg(feature = "fake")] "FAKEWALLET" => { + use std::collections::HashMap; + use std::sync::Arc; + let fee_reserve = FeeReserve { min_fee_reserve: 1.into(), percent_fee_reserve: 0.0, diff --git a/crates/cdk-sql-common/src/mint/migrations.rs b/crates/cdk-sql-common/src/mint/migrations.rs index ed14f1712..0f4a9429b 100644 --- a/crates/cdk-sql-common/src/mint/migrations.rs +++ b/crates/cdk-sql-common/src/mint/migrations.rs @@ -3,6 +3,7 @@ pub static MIGRATIONS: &[(&str, &str, &str)] = &[ ("postgres", "1_initial.sql", include_str!(r#"./migrations/postgres/1_initial.sql"#)), ("postgres", "2_remove_request_lookup_kind_constraints.sql", include_str!(r#"./migrations/postgres/2_remove_request_lookup_kind_constraints.sql"#)), + ("postgres", "3_add_kv_store.sql", include_str!(r#"./migrations/postgres/3_add_kv_store.sql"#)), ("sqlite", "1_fix_sqlx_migration.sql", include_str!(r#"./migrations/sqlite/1_fix_sqlx_migration.sql"#)), ("sqlite", "20240612124932_init.sql", include_str!(r#"./migrations/sqlite/20240612124932_init.sql"#)), ("sqlite", "20240618195700_quote_state.sql", include_str!(r#"./migrations/sqlite/20240618195700_quote_state.sql"#)), @@ -27,4 +28,5 @@ pub static MIGRATIONS: &[(&str, &str, &str)] = &[ ("sqlite", "20250706101057_bolt12.sql", include_str!(r#"./migrations/sqlite/20250706101057_bolt12.sql"#)), ("sqlite", "20250812132015_drop_melt_request.sql", include_str!(r#"./migrations/sqlite/20250812132015_drop_melt_request.sql"#)), ("sqlite", "20250819200000_remove_request_lookup_kind_constraints.sql", include_str!(r#"./migrations/sqlite/20250819200000_remove_request_lookup_kind_constraints.sql"#)), + ("sqlite", "20250901090000_add_kv_store.sql", include_str!(r#"./migrations/sqlite/20250901090000_add_kv_store.sql"#)), ]; diff --git a/crates/cdk-sql-common/src/mint/migrations/postgres/3_add_kv_store.sql b/crates/cdk-sql-common/src/mint/migrations/postgres/3_add_kv_store.sql new file mode 100644 index 000000000..a46ef9f25 --- /dev/null +++ b/crates/cdk-sql-common/src/mint/migrations/postgres/3_add_kv_store.sql @@ -0,0 +1,18 @@ +-- Add kv_store table for generic key-value storage +CREATE TABLE IF NOT EXISTS kv_store ( + primary_namespace TEXT NOT NULL, + secondary_namespace TEXT NOT NULL, + key TEXT NOT NULL, + value BYTEA NOT NULL, + created_time BIGINT NOT NULL, + updated_time BIGINT NOT NULL, + PRIMARY KEY (primary_namespace, secondary_namespace, key) +); + +-- Index for efficient listing of keys by namespace +CREATE INDEX IF NOT EXISTS idx_kv_store_namespaces +ON kv_store (primary_namespace, secondary_namespace); + +-- Index for efficient querying by update time +CREATE INDEX IF NOT EXISTS idx_kv_store_updated_time +ON kv_store (updated_time); diff --git a/crates/cdk-sql-common/src/mint/migrations/sqlite/20250901090000_add_kv_store.sql b/crates/cdk-sql-common/src/mint/migrations/sqlite/20250901090000_add_kv_store.sql new file mode 100644 index 000000000..f073826c8 --- /dev/null +++ b/crates/cdk-sql-common/src/mint/migrations/sqlite/20250901090000_add_kv_store.sql @@ -0,0 +1,18 @@ +-- Add kv_store table for generic key-value storage +CREATE TABLE IF NOT EXISTS kv_store ( + primary_namespace TEXT NOT NULL, + secondary_namespace TEXT NOT NULL, + key TEXT NOT NULL, + value BLOB NOT NULL, + created_time INTEGER NOT NULL, + updated_time INTEGER NOT NULL, + PRIMARY KEY (primary_namespace, secondary_namespace, key) +); + +-- Index for efficient listing of keys by namespace +CREATE INDEX IF NOT EXISTS idx_kv_store_namespaces +ON kv_store (primary_namespace, secondary_namespace); + +-- Index for efficient querying by update time +CREATE INDEX IF NOT EXISTS idx_kv_store_updated_time +ON kv_store (updated_time); diff --git a/crates/cdk-sql-common/src/mint/mod.rs b/crates/cdk-sql-common/src/mint/mod.rs index ec7ae4479..8e1fcdc3b 100644 --- a/crates/cdk-sql-common/src/mint/mod.rs +++ b/crates/cdk-sql-common/src/mint/mod.rs @@ -16,6 +16,7 @@ use std::sync::Arc; use async_trait::async_trait; use bitcoin::bip32::DerivationPath; use cdk_common::common::QuoteTTL; +use cdk_common::database::mint::validate_kvstore_params; use cdk_common::database::{ self, ConversionError, Error, MintDatabase, MintDbWriterFinalizer, MintKeyDatabaseTransaction, MintKeysDatabase, MintProofsDatabase, MintQuotesDatabase, MintQuotesTransaction, @@ -1582,6 +1583,224 @@ where } } +#[async_trait] +impl database::MintKVStoreTransaction<'_, Error> for SQLTransaction +where + RM: DatabasePool + 'static, +{ + async fn kv_read( + &mut self, + primary_namespace: &str, + secondary_namespace: &str, + key: &str, + ) -> Result>, Error> { + // Validate parameters according to KV store requirements + validate_kvstore_params(primary_namespace, secondary_namespace, key)?; + Ok(query( + r#" + SELECT value + FROM kv_store + WHERE primary_namespace = :primary_namespace + AND secondary_namespace = :secondary_namespace + AND key = :key + "#, + )? + .bind("primary_namespace", primary_namespace.to_owned()) + .bind("secondary_namespace", secondary_namespace.to_owned()) + .bind("key", key.to_owned()) + .pluck(&self.inner) + .await? + .and_then(|col| match col { + Column::Blob(data) => Some(data), + _ => None, + })) + } + + async fn kv_write( + &mut self, + primary_namespace: &str, + secondary_namespace: &str, + key: &str, + value: &[u8], + ) -> Result<(), Error> { + // Validate parameters according to KV store requirements + validate_kvstore_params(primary_namespace, secondary_namespace, key)?; + + let current_time = unix_time(); + + query( + r#" + INSERT INTO kv_store + (primary_namespace, secondary_namespace, key, value, created_time, updated_time) + VALUES (:primary_namespace, :secondary_namespace, :key, :value, :created_time, :updated_time) + ON CONFLICT(primary_namespace, secondary_namespace, key) + DO UPDATE SET + value = excluded.value, + updated_time = excluded.updated_time + "#, + )? + .bind("primary_namespace", primary_namespace.to_owned()) + .bind("secondary_namespace", secondary_namespace.to_owned()) + .bind("key", key.to_owned()) + .bind("value", value.to_vec()) + .bind("created_time", current_time as i64) + .bind("updated_time", current_time as i64) + .execute(&self.inner) + .await?; + + Ok(()) + } + + async fn kv_remove( + &mut self, + primary_namespace: &str, + secondary_namespace: &str, + key: &str, + ) -> Result<(), Error> { + // Validate parameters according to KV store requirements + validate_kvstore_params(primary_namespace, secondary_namespace, key)?; + query( + r#" + DELETE FROM kv_store + WHERE primary_namespace = :primary_namespace + AND secondary_namespace = :secondary_namespace + AND key = :key + "#, + )? + .bind("primary_namespace", primary_namespace.to_owned()) + .bind("secondary_namespace", secondary_namespace.to_owned()) + .bind("key", key.to_owned()) + .execute(&self.inner) + .await?; + + Ok(()) + } + + async fn kv_list( + &mut self, + primary_namespace: &str, + secondary_namespace: &str, + ) -> Result, Error> { + // Validate namespace parameters according to KV store requirements + cdk_common::database::mint::validate_kvstore_string(primary_namespace)?; + cdk_common::database::mint::validate_kvstore_string(secondary_namespace)?; + + // Check empty namespace rules + if primary_namespace.is_empty() && !secondary_namespace.is_empty() { + return Err(Error::KVStoreInvalidKey( + "If primary_namespace is empty, secondary_namespace must also be empty".to_string(), + )); + } + Ok(query( + r#" + SELECT key + FROM kv_store + WHERE primary_namespace = :primary_namespace + AND secondary_namespace = :secondary_namespace + ORDER BY key + "#, + )? + .bind("primary_namespace", primary_namespace.to_owned()) + .bind("secondary_namespace", secondary_namespace.to_owned()) + .fetch_all(&self.inner) + .await? + .into_iter() + .map(|row| Ok(column_as_string!(&row[0]))) + .collect::, Error>>()?) + } +} + +#[async_trait] +impl database::MintKVStoreDatabase for SQLMintDatabase +where + RM: DatabasePool + 'static, +{ + type Err = Error; + + async fn kv_read( + &self, + primary_namespace: &str, + secondary_namespace: &str, + key: &str, + ) -> Result>, Error> { + // Validate parameters according to KV store requirements + validate_kvstore_params(primary_namespace, secondary_namespace, key)?; + + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; + Ok(query( + r#" + SELECT value + FROM kv_store + WHERE primary_namespace = :primary_namespace + AND secondary_namespace = :secondary_namespace + AND key = :key + "#, + )? + .bind("primary_namespace", primary_namespace.to_owned()) + .bind("secondary_namespace", secondary_namespace.to_owned()) + .bind("key", key.to_owned()) + .pluck(&*conn) + .await? + .and_then(|col| match col { + Column::Blob(data) => Some(data), + _ => None, + })) + } + + async fn kv_list( + &self, + primary_namespace: &str, + secondary_namespace: &str, + ) -> Result, Error> { + // Validate namespace parameters according to KV store requirements + cdk_common::database::mint::validate_kvstore_string(primary_namespace)?; + cdk_common::database::mint::validate_kvstore_string(secondary_namespace)?; + + // Check empty namespace rules + if primary_namespace.is_empty() && !secondary_namespace.is_empty() { + return Err(Error::KVStoreInvalidKey( + "If primary_namespace is empty, secondary_namespace must also be empty".to_string(), + )); + } + + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; + Ok(query( + r#" + SELECT key + FROM kv_store + WHERE primary_namespace = :primary_namespace + AND secondary_namespace = :secondary_namespace + ORDER BY key + "#, + )? + .bind("primary_namespace", primary_namespace.to_owned()) + .bind("secondary_namespace", secondary_namespace.to_owned()) + .fetch_all(&*conn) + .await? + .into_iter() + .map(|row| Ok(column_as_string!(&row[0]))) + .collect::, Error>>()?) + } +} + +#[async_trait] +impl database::MintKVStore for SQLMintDatabase +where + RM: DatabasePool + 'static, +{ + async fn begin_transaction<'a>( + &'a self, + ) -> Result + Send + Sync + 'a>, Error> + { + Ok(Box::new(SQLTransaction { + inner: ConnectionWithTransaction::new( + self.pool.get().map_err(|e| Error::Database(Box::new(e)))?, + ) + .await?, + })) + } +} + #[async_trait] impl MintDatabase for SQLMintDatabase where diff --git a/crates/cdk/src/lib.rs b/crates/cdk/src/lib.rs index ae18ae3ce..babe1ecbc 100644 --- a/crates/cdk/src/lib.rs +++ b/crates/cdk/src/lib.rs @@ -12,8 +12,8 @@ pub mod cdk_database { pub use cdk_common::database::WalletDatabase; #[cfg(feature = "mint")] pub use cdk_common::database::{ - MintDatabase, MintKeysDatabase, MintProofsDatabase, MintQuotesDatabase, - MintSignaturesDatabase, MintTransaction, + MintDatabase, MintKVStore, MintKVStoreDatabase, MintKVStoreTransaction, MintKeysDatabase, + MintProofsDatabase, MintQuotesDatabase, MintSignaturesDatabase, MintTransaction, }; } From 3815c62d884f5c3e0d2a86207bb2e9e9ad667211 Mon Sep 17 00:00:00 2001 From: C Date: Fri, 5 Sep 2025 14:39:54 -0300 Subject: [PATCH 127/321] Fix postgres migration prefixes (#1037) * Fix migrations ordering 1. Fix postgres migration prefixes for unreleased migrations 2. Fix build script to try to sort, if provided, the filename prefix as a number, otherwise fallback to the sorting by filename as string * Fixed clippy issues --- crates/cdk-sql-common/build.rs | 22 ++++++++++++++++++- .../src/mint/auth/migrations.rs | 4 ++-- crates/cdk-sql-common/src/mint/migrations.rs | 4 ++-- ...re.sql => 20250901090000_add_kv_store.sql} | 0 .../cdk-sql-common/src/wallet/migrations.rs | 4 ++-- 5 files changed, 27 insertions(+), 7 deletions(-) rename crates/cdk-sql-common/src/mint/migrations/postgres/{3_add_kv_store.sql => 20250901090000_add_kv_store.sql} (100%) diff --git a/crates/cdk-sql-common/build.rs b/crates/cdk-sql-common/build.rs index 37d494fce..eeea575c3 100644 --- a/crates/cdk-sql-common/build.rs +++ b/crates/cdk-sql-common/build.rs @@ -10,7 +10,27 @@ fn main() { // Step 2: Collect all files inside the migrations dir let mut files = Vec::new(); visit_dirs(&migration_path, &mut files).expect("Failed to read migrations directory"); - files.sort(); + files.sort_by(|path_a, path_b| { + let path_a = path_a.file_name().unwrap().to_str().unwrap(); + let path_b = path_b.file_name().unwrap().to_str().unwrap(); + + let prefix_a = path_a + .split("_") + .next() + .and_then(|prefix| prefix.parse::().ok()) + .unwrap_or_default(); + let prefix_b = path_b + .split("_") + .next() + .and_then(|prefix| prefix.parse::().ok()) + .unwrap_or_default(); + + if prefix_a != 0 && prefix_b != 0 { + prefix_a.cmp(&prefix_b) + } else { + path_a.cmp(path_b) + } + }); // Step 3: Output file path (e.g., `src/db/migrations.rs`) let parent = migration_path.parent().unwrap(); diff --git a/crates/cdk-sql-common/src/mint/auth/migrations.rs b/crates/cdk-sql-common/src/mint/auth/migrations.rs index ee53d6bdb..3b95bcda5 100644 --- a/crates/cdk-sql-common/src/mint/auth/migrations.rs +++ b/crates/cdk-sql-common/src/mint/auth/migrations.rs @@ -1,9 +1,9 @@ /// @generated /// Auto-generated by build.rs pub static MIGRATIONS: &[(&str, &str, &str)] = &[ - ("postgres", "1_init.sql", include_str!(r#"./migrations/postgres/1_init.sql"#)), - ("postgres", "20250822104351_rename_blind_message_y_to_b.sql", include_str!(r#"./migrations/postgres/20250822104351_rename_blind_message_y_to_b.sql"#)), ("sqlite", "1_fix_sqlx_migration.sql", include_str!(r#"./migrations/sqlite/1_fix_sqlx_migration.sql"#)), + ("postgres", "1_init.sql", include_str!(r#"./migrations/postgres/1_init.sql"#)), ("sqlite", "20250109143347_init.sql", include_str!(r#"./migrations/sqlite/20250109143347_init.sql"#)), ("sqlite", "20250822104351_rename_blind_message_y_to_b.sql", include_str!(r#"./migrations/sqlite/20250822104351_rename_blind_message_y_to_b.sql"#)), + ("postgres", "20250822104351_rename_blind_message_y_to_b.sql", include_str!(r#"./migrations/postgres/20250822104351_rename_blind_message_y_to_b.sql"#)), ]; diff --git a/crates/cdk-sql-common/src/mint/migrations.rs b/crates/cdk-sql-common/src/mint/migrations.rs index 0f4a9429b..eb8e89fce 100644 --- a/crates/cdk-sql-common/src/mint/migrations.rs +++ b/crates/cdk-sql-common/src/mint/migrations.rs @@ -1,10 +1,9 @@ /// @generated /// Auto-generated by build.rs pub static MIGRATIONS: &[(&str, &str, &str)] = &[ + ("sqlite", "1_fix_sqlx_migration.sql", include_str!(r#"./migrations/sqlite/1_fix_sqlx_migration.sql"#)), ("postgres", "1_initial.sql", include_str!(r#"./migrations/postgres/1_initial.sql"#)), ("postgres", "2_remove_request_lookup_kind_constraints.sql", include_str!(r#"./migrations/postgres/2_remove_request_lookup_kind_constraints.sql"#)), - ("postgres", "3_add_kv_store.sql", include_str!(r#"./migrations/postgres/3_add_kv_store.sql"#)), - ("sqlite", "1_fix_sqlx_migration.sql", include_str!(r#"./migrations/sqlite/1_fix_sqlx_migration.sql"#)), ("sqlite", "20240612124932_init.sql", include_str!(r#"./migrations/sqlite/20240612124932_init.sql"#)), ("sqlite", "20240618195700_quote_state.sql", include_str!(r#"./migrations/sqlite/20240618195700_quote_state.sql"#)), ("sqlite", "20240626092101_nut04_state.sql", include_str!(r#"./migrations/sqlite/20240626092101_nut04_state.sql"#)), @@ -29,4 +28,5 @@ pub static MIGRATIONS: &[(&str, &str, &str)] = &[ ("sqlite", "20250812132015_drop_melt_request.sql", include_str!(r#"./migrations/sqlite/20250812132015_drop_melt_request.sql"#)), ("sqlite", "20250819200000_remove_request_lookup_kind_constraints.sql", include_str!(r#"./migrations/sqlite/20250819200000_remove_request_lookup_kind_constraints.sql"#)), ("sqlite", "20250901090000_add_kv_store.sql", include_str!(r#"./migrations/sqlite/20250901090000_add_kv_store.sql"#)), + ("postgres", "20250901090000_add_kv_store.sql", include_str!(r#"./migrations/postgres/20250901090000_add_kv_store.sql"#)), ]; diff --git a/crates/cdk-sql-common/src/mint/migrations/postgres/3_add_kv_store.sql b/crates/cdk-sql-common/src/mint/migrations/postgres/20250901090000_add_kv_store.sql similarity index 100% rename from crates/cdk-sql-common/src/mint/migrations/postgres/3_add_kv_store.sql rename to crates/cdk-sql-common/src/mint/migrations/postgres/20250901090000_add_kv_store.sql diff --git a/crates/cdk-sql-common/src/wallet/migrations.rs b/crates/cdk-sql-common/src/wallet/migrations.rs index 5838a0209..767195231 100644 --- a/crates/cdk-sql-common/src/wallet/migrations.rs +++ b/crates/cdk-sql-common/src/wallet/migrations.rs @@ -1,9 +1,8 @@ /// @generated /// Auto-generated by build.rs pub static MIGRATIONS: &[(&str, &str, &str)] = &[ - ("postgres", "1_initial.sql", include_str!(r#"./migrations/postgres/1_initial.sql"#)), - ("postgres", "20250831215438_melt_quote_method.sql", include_str!(r#"./migrations/postgres/20250831215438_melt_quote_method.sql"#)), ("sqlite", "1_fix_sqlx_migration.sql", include_str!(r#"./migrations/sqlite/1_fix_sqlx_migration.sql"#)), + ("postgres", "1_initial.sql", include_str!(r#"./migrations/postgres/1_initial.sql"#)), ("sqlite", "20240612132920_init.sql", include_str!(r#"./migrations/sqlite/20240612132920_init.sql"#)), ("sqlite", "20240618200350_quote_state.sql", include_str!(r#"./migrations/sqlite/20240618200350_quote_state.sql"#)), ("sqlite", "20240626091921_nut04_state.sql", include_str!(r#"./migrations/sqlite/20240626091921_nut04_state.sql"#)), @@ -24,4 +23,5 @@ pub static MIGRATIONS: &[(&str, &str, &str)] = &[ ("sqlite", "20250729111701_keyset_v2_u32.sql", include_str!(r#"./migrations/sqlite/20250729111701_keyset_v2_u32.sql"#)), ("sqlite", "20250812084621_keyset_plus_one.sql", include_str!(r#"./migrations/sqlite/20250812084621_keyset_plus_one.sql"#)), ("sqlite", "20250831215438_melt_quote_method.sql", include_str!(r#"./migrations/sqlite/20250831215438_melt_quote_method.sql"#)), + ("postgres", "20250831215438_melt_quote_method.sql", include_str!(r#"./migrations/postgres/20250831215438_melt_quote_method.sql"#)), ]; From ded165f40558618fdb72b6816be5ec6084efbc7b Mon Sep 17 00:00:00 2001 From: C Date: Fri, 5 Sep 2025 19:07:04 -0300 Subject: [PATCH 128/321] Update the signatory.proto file to match NUT-XXX (#1032) * Update the signatory.proto file to match NUT-XXX Source: https://github.com/cashubtc/nuts/pull/250/files * Add unit tests as requested in https://github.com/cashubtc/cdk/pull/1032#discussion_r2321436860 * Remove unused types from proto file --- crates/cashu/src/nuts/nut02.rs | 15 ++- crates/cashu/src/quote_id.rs | 2 +- crates/cdk-common/src/database/mint/test.rs | 1 + crates/cdk-common/src/mint.rs | 2 + crates/cdk-signatory/src/common.rs | 11 +- crates/cdk-signatory/src/db_signatory.rs | 14 ++- crates/cdk-signatory/src/proto/convert.rs | 40 +++---- .../cdk-signatory/src/proto/signatory.proto | 21 +++- crates/cdk-signatory/src/signatory.rs | 3 +- crates/cdk-sql-common/src/mint/auth/mod.rs | 2 + crates/cdk-sql-common/src/mint/migrations.rs | 2 + .../20250903200000_add_signatory_amounts.sql | 1 + .../20250903200000_add_signatory_amounts.sql | 33 ++++++ crates/cdk-sql-common/src/mint/mod.rs | 111 +++++++++++++++++- crates/cdk/src/mint/keysets/mod.rs | 2 +- 15 files changed, 207 insertions(+), 53 deletions(-) create mode 100644 crates/cdk-sql-common/src/mint/migrations/postgres/20250903200000_add_signatory_amounts.sql create mode 100644 crates/cdk-sql-common/src/mint/migrations/sqlite/20250903200000_add_signatory_amounts.sql diff --git a/crates/cashu/src/nuts/nut02.rs b/crates/cashu/src/nuts/nut02.rs index 4baceaf47..7835de878 100644 --- a/crates/cashu/src/nuts/nut02.rs +++ b/crates/cashu/src/nuts/nut02.rs @@ -553,13 +553,12 @@ impl MintKeySet { secp: &Secp256k1, xpriv: Xpriv, unit: CurrencyUnit, - max_order: u8, + amounts: &[u64], final_expiry: Option, version: KeySetVersion, ) -> Self { let mut map = BTreeMap::new(); - for i in 0..max_order { - let amount = Amount::from(2_u64.pow(i as u32)); + for (i, amount) in amounts.iter().enumerate() { let secret_key = xpriv .derive_priv( secp, @@ -569,7 +568,7 @@ impl MintKeySet { .private_key; let public_key = secret_key.public_key(secp); map.insert( - amount, + amount.into(), MintKeyPair { secret_key: secret_key.into(), public_key: public_key.into(), @@ -594,7 +593,7 @@ impl MintKeySet { pub fn generate_from_seed( secp: &Secp256k1, seed: &[u8], - max_order: u8, + amounts: &[u64], currency_unit: CurrencyUnit, derivation_path: DerivationPath, final_expiry: Option, @@ -607,7 +606,7 @@ impl MintKeySet { .derive_priv(secp, &derivation_path) .expect("RNG busted"), currency_unit, - max_order, + amounts, final_expiry, version, ) @@ -617,7 +616,7 @@ impl MintKeySet { pub fn generate_from_xpriv( secp: &Secp256k1, xpriv: Xpriv, - max_order: u8, + amounts: &[u64], currency_unit: CurrencyUnit, derivation_path: DerivationPath, final_expiry: Option, @@ -629,7 +628,7 @@ impl MintKeySet { .derive_priv(secp, &derivation_path) .expect("RNG busted"), currency_unit, - max_order, + amounts, final_expiry, version, ) diff --git a/crates/cashu/src/quote_id.rs b/crates/cashu/src/quote_id.rs index 58ccac59a..4b14e21fc 100644 --- a/crates/cashu/src/quote_id.rs +++ b/crates/cashu/src/quote_id.rs @@ -48,7 +48,7 @@ impl From for QuoteId { impl fmt::Display for QuoteId { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { match self { - QuoteId::BASE64(s) => write!(f, "{}", s), + QuoteId::BASE64(s) => write!(f, "{s}"), QuoteId::UUID(u) => write!(f, "{}", u.hyphenated()), } } diff --git a/crates/cdk-common/src/database/mint/test.rs b/crates/cdk-common/src/database/mint/test.rs index de4011041..2d681a6b4 100644 --- a/crates/cdk-common/src/database/mint/test.rs +++ b/crates/cdk-common/src/database/mint/test.rs @@ -29,6 +29,7 @@ where derivation_path_index: Some(0), max_order: 32, input_fee_ppk: 0, + amounts: vec![], }; let mut writer = db.begin_transaction().await.expect("db.begin()"); writer.add_keyset_info(keyset_info).await.unwrap(); diff --git a/crates/cdk-common/src/mint.rs b/crates/cdk-common/src/mint.rs index 9c63b0fdd..a6d3d91e8 100644 --- a/crates/cdk-common/src/mint.rs +++ b/crates/cdk-common/src/mint.rs @@ -313,6 +313,8 @@ pub struct MintKeySetInfo { pub derivation_path_index: Option, /// Max order of keyset pub max_order: u8, + /// Supported amounts + pub amounts: Vec, /// Input Fee ppk #[serde(default = "default_fee")] pub input_fee_ppk: u64, diff --git a/crates/cdk-signatory/src/common.rs b/crates/cdk-signatory/src/common.rs index 6663f8816..d7d4d3443 100644 --- a/crates/cdk-signatory/src/common.rs +++ b/crates/cdk-signatory/src/common.rs @@ -66,7 +66,7 @@ pub async fn init_keysets( let keyset = MintKeySet::generate_from_xpriv( secp_ctx, xpriv, - highest_index_keyset.max_order, + &highest_index_keyset.amounts, highest_index_keyset.unit.clone(), highest_index_keyset.derivation_path.clone(), highest_index_keyset.final_expiry, @@ -98,7 +98,7 @@ pub async fn init_keysets( derivation_path, Some(derivation_path_index), unit.clone(), - *max_order, + &highest_index_keyset.amounts, *input_fee_ppk, // TODO: add Mint settings for a final expiry of newly generated keysets None, @@ -128,7 +128,7 @@ pub fn create_new_keyset( derivation_path: DerivationPath, derivation_path_index: Option, unit: CurrencyUnit, - max_order: u8, + amounts: &[u64], input_fee_ppk: u64, final_expiry: Option, ) -> (MintKeySet, MintKeySetInfo) { @@ -138,7 +138,7 @@ pub fn create_new_keyset( .derive_priv(secp, &derivation_path) .expect("RNG busted"), unit, - max_order, + amounts, final_expiry, // TODO: change this to Version01 to generate keysets v2 cdk_common::nut02::KeySetVersion::Version00, @@ -151,7 +151,8 @@ pub fn create_new_keyset( final_expiry: keyset.final_expiry, derivation_path, derivation_path_index, - max_order, + max_order: 0, + amounts: amounts.to_owned(), input_fee_ppk, }; (keyset, keyset_info) diff --git a/crates/cdk-signatory/src/db_signatory.rs b/crates/cdk-signatory/src/db_signatory.rs index c1dae7f85..d446ba2b0 100644 --- a/crates/cdk-signatory/src/db_signatory.rs +++ b/crates/cdk-signatory/src/db_signatory.rs @@ -65,13 +65,17 @@ impl DbSignatory { } }; + let amounts = (0..max_order) + .map(|i| 2_u64.pow(i as u32)) + .collect::>(); + let (keyset, keyset_info) = create_new_keyset( &secp_ctx, xpriv, derivation_path, Some(0), unit.clone(), - max_order, + &amounts, fee, // TODO: add and connect settings for this None, @@ -132,7 +136,7 @@ impl DbSignatory { MintKeySet::generate_from_xpriv( &self.secp_ctx, self.xpriv, - keyset_info.max_order, + &keyset_info.amounts, keyset_info.unit.clone(), keyset_info.derivation_path.clone(), keyset_info.final_expiry, @@ -241,7 +245,7 @@ impl Signatory for DbSignatory { derivation_path, Some(path_index), args.unit.clone(), - args.max_order, + &args.amounts, args.input_fee_ppk, // TODO: add and connect settings for this None, @@ -274,7 +278,7 @@ mod test { let keyset = MintKeySet::generate_from_seed( &Secp256k1::new(), seed, - 2, + &[1, 2], CurrencyUnit::Sat, derivation_path_from_unit(CurrencyUnit::Sat, 0).unwrap(), None, @@ -320,7 +324,7 @@ mod test { let keyset = MintKeySet::generate_from_xpriv( &Secp256k1::new(), xpriv, - 2, + &[1, 2], CurrencyUnit::Sat, derivation_path_from_unit(CurrencyUnit::Sat, 0).unwrap(), None, diff --git a/crates/cdk-signatory/src/proto/convert.rs b/crates/cdk-signatory/src/proto/convert.rs index 0bb11c03f..91692cd00 100644 --- a/crates/cdk-signatory/src/proto/convert.rs +++ b/crates/cdk-signatory/src/proto/convert.rs @@ -3,7 +3,7 @@ use std::collections::BTreeMap; use cdk_common::secret::Secret; use cdk_common::util::hex; -use cdk_common::{Amount, PublicKey}; +use cdk_common::{Amount, Id, PublicKey}; use tonic::Status; use super::*; @@ -44,7 +44,7 @@ impl TryInto for KeySet { fn try_into(self) -> Result { Ok(crate::signatory::SignatoryKeySet { - id: self.id.parse()?, + id: Id::from_bytes(&self.id)?, unit: self .unit .ok_or(cdk_common::Error::Custom(INTERNAL_ERROR.to_owned()))? @@ -68,7 +68,7 @@ impl TryInto for KeySet { impl From for KeySet { fn from(keyset: crate::signatory::SignatoryKeySet) -> Self { Self { - id: keyset.id.to_string(), + id: keyset.id.to_bytes(), unit: Some(keyset.unit.into()), active: keyset.active, input_fee_ppk: keyset.input_fee_ppk, @@ -80,6 +80,7 @@ impl From for KeySet { .collect(), }), final_expiry: keyset.final_expiry, + version: Default::default(), } } } @@ -141,7 +142,7 @@ impl From for BlindSignature { BlindSignature { amount: value.amount.into(), blinded_secret: value.c.to_bytes().to_vec(), - keyset_id: value.keyset_id.to_string(), + keyset_id: value.keyset_id.to_bytes(), dleq: value.dleq.map(|x| x.into()), } } @@ -161,7 +162,7 @@ impl From for Proof { fn from(value: cdk_common::Proof) -> Self { Proof { amount: value.amount.into(), - keyset_id: value.keyset_id.to_string(), + keyset_id: value.keyset_id.to_bytes(), secret: value.secret.to_bytes(), c: value.c.to_bytes().to_vec(), } @@ -179,9 +180,7 @@ impl TryInto for Proof { Ok(cdk_common::Proof { amount: self.amount.into(), - keyset_id: self - .keyset_id - .parse() + keyset_id: Id::from_bytes(&self.keyset_id) .map_err(|e| Status::from_error(Box::new(e)))?, secret: Secret::new(secret), c: cdk_common::PublicKey::from_slice(&self.c) @@ -199,7 +198,7 @@ impl TryInto for BlindSignature { Ok(cdk_common::BlindSignature { amount: self.amount.into(), c: cdk_common::PublicKey::from_slice(&self.blinded_secret)?, - keyset_id: self.keyset_id.parse().expect("Invalid keyset id"), + keyset_id: Id::from_bytes(&self.keyset_id)?, dleq: self.dleq.map(|dleq| dleq.try_into()).transpose()?, }) } @@ -209,7 +208,7 @@ impl From for BlindedMessage { fn from(value: cdk_common::BlindedMessage) -> Self { BlindedMessage { amount: value.amount.into(), - keyset_id: value.keyset_id.to_string(), + keyset_id: value.keyset_id.to_bytes(), blinded_secret: value.blinded_secret.to_bytes().to_vec(), } } @@ -220,9 +219,7 @@ impl TryInto for BlindedMessage { fn try_into(self) -> Result { Ok(cdk_common::BlindedMessage { amount: self.amount.into(), - keyset_id: self - .keyset_id - .parse() + keyset_id: Id::from_bytes(&self.keyset_id) .map_err(|e| Status::from_error(Box::new(e)))?, blinded_secret: cdk_common::PublicKey::from_slice(&self.blinded_secret) .map_err(|e| Status::from_error(Box::new(e)))?, @@ -311,10 +308,7 @@ impl TryInto for KeySet { type Error = cdk_common::error::Error; fn try_into(self) -> Result { Ok(cdk_common::KeySet { - id: self - .id - .parse() - .map_err(|_| cdk_common::error::Error::Custom("Invalid ID".to_owned()))?, + id: Id::from_bytes(&self.id)?, unit: self .unit .ok_or(cdk_common::error::Error::Custom(INTERNAL_ERROR.to_owned()))? @@ -337,7 +331,7 @@ impl From for RotationRequest { fn from(value: crate::signatory::RotateKeyArguments) -> Self { Self { unit: Some(value.unit.into()), - max_order: value.max_order.into(), + amounts: value.amounts, input_fee_ppk: value.input_fee_ppk, } } @@ -352,10 +346,7 @@ impl TryInto for RotationRequest { .unit .ok_or(Status::invalid_argument("unit not set"))? .try_into()?, - max_order: self - .max_order - .try_into() - .map_err(|_| Status::invalid_argument("Invalid max_order"))?, + amounts: self.amounts, input_fee_ppk: self.input_fee_ppk, }) } @@ -364,12 +355,13 @@ impl TryInto for RotationRequest { impl From for KeySet { fn from(value: cdk_common::KeySetInfo) -> Self { Self { - id: value.id.into(), + id: value.id.to_bytes(), unit: Some(value.unit.into()), active: value.active, input_fee_ppk: value.input_fee_ppk, keys: Default::default(), final_expiry: value.final_expiry, + version: Default::default(), } } } @@ -379,7 +371,7 @@ impl TryInto for KeySet { fn try_into(self) -> Result { Ok(cdk_common::KeySetInfo { - id: self.id.try_into()?, + id: Id::from_bytes(&self.id)?, unit: self .unit .ok_or(cdk_common::Error::Custom(INTERNAL_ERROR.to_owned()))? diff --git a/crates/cdk-signatory/src/proto/signatory.proto b/crates/cdk-signatory/src/proto/signatory.proto index 8cb91211a..600bb2232 100644 --- a/crates/cdk-signatory/src/proto/signatory.proto +++ b/crates/cdk-signatory/src/proto/signatory.proto @@ -32,7 +32,7 @@ message BlindedMessages { // Represents a blinded message message BlindedMessage { uint64 amount = 1; - string keyset_id = 2; + bytes keyset_id = 2; bytes blinded_secret = 3; } @@ -57,12 +57,13 @@ message SignatoryKeysets { } message KeySet { - string id = 1; + bytes id = 1; CurrencyUnit unit = 2; bool active = 3; uint64 input_fee_ppk = 4; Keys keys = 5; optional uint64 final_expiry = 6; + uint64 version = 7; } message Keys { @@ -72,7 +73,7 @@ message Keys { message RotationRequest { CurrencyUnit unit = 1; uint64 input_fee_ppk = 2; - uint32 max_order = 3; + repeated uint64 amounts = 3; } enum CurrencyUnitType { @@ -99,18 +100,28 @@ message Proofs { message Proof { uint64 amount = 1; - string keyset_id = 2; + bytes keyset_id = 2; bytes secret = 3; bytes c = 4; } +message ProofDLEQ { + bytes e = 1; + bytes s = 2; + bytes r = 3; +} + +message SigningResponse { + Error error = 1; + BlindSignatures blind_signatures = 2; +} message BlindSignatures { repeated BlindSignature blind_signatures = 1; } message BlindSignature { uint64 amount = 1; - string keyset_id = 2; + bytes keyset_id = 2; bytes blinded_secret = 3; optional BlindSignatureDLEQ dleq = 4; } diff --git a/crates/cdk-signatory/src/signatory.rs b/crates/cdk-signatory/src/signatory.rs index 31ea99c3c..1b7e2257b 100644 --- a/crates/cdk-signatory/src/signatory.rs +++ b/crates/cdk-signatory/src/signatory.rs @@ -43,7 +43,7 @@ pub struct RotateKeyArguments { /// Unit pub unit: CurrencyUnit, /// Max order - pub max_order: u8, + pub amounts: Vec, /// Input fee pub input_fee_ppk: u64, } @@ -110,6 +110,7 @@ impl From for MintKeySetInfo { derivation_path: Default::default(), derivation_path_index: Default::default(), max_order: 0, + amounts: vec![], final_expiry: val.final_expiry, valid_from: 0, } diff --git a/crates/cdk-sql-common/src/mint/auth/mod.rs b/crates/cdk-sql-common/src/mint/auth/mod.rs index 8effd9fc2..771f509f6 100644 --- a/crates/cdk-sql-common/src/mint/auth/mod.rs +++ b/crates/cdk-sql-common/src/mint/auth/mod.rs @@ -284,6 +284,7 @@ where derivation_path, derivation_path_index, max_order, + amounts, input_fee_ppk FROM keyset @@ -308,6 +309,7 @@ where derivation_path, derivation_path_index, max_order, + amounts, input_fee_ppk FROM keyset diff --git a/crates/cdk-sql-common/src/mint/migrations.rs b/crates/cdk-sql-common/src/mint/migrations.rs index eb8e89fce..eddf05524 100644 --- a/crates/cdk-sql-common/src/mint/migrations.rs +++ b/crates/cdk-sql-common/src/mint/migrations.rs @@ -29,4 +29,6 @@ pub static MIGRATIONS: &[(&str, &str, &str)] = &[ ("sqlite", "20250819200000_remove_request_lookup_kind_constraints.sql", include_str!(r#"./migrations/sqlite/20250819200000_remove_request_lookup_kind_constraints.sql"#)), ("sqlite", "20250901090000_add_kv_store.sql", include_str!(r#"./migrations/sqlite/20250901090000_add_kv_store.sql"#)), ("postgres", "20250901090000_add_kv_store.sql", include_str!(r#"./migrations/postgres/20250901090000_add_kv_store.sql"#)), + ("sqlite", "20250903200000_add_signatory_amounts.sql", include_str!(r#"./migrations/sqlite/20250903200000_add_signatory_amounts.sql"#)), + ("postgres", "20250903200000_add_signatory_amounts.sql", include_str!(r#"./migrations/postgres/20250903200000_add_signatory_amounts.sql"#)), ]; diff --git a/crates/cdk-sql-common/src/mint/migrations/postgres/20250903200000_add_signatory_amounts.sql b/crates/cdk-sql-common/src/mint/migrations/postgres/20250903200000_add_signatory_amounts.sql new file mode 100644 index 000000000..cef8c730a --- /dev/null +++ b/crates/cdk-sql-common/src/mint/migrations/postgres/20250903200000_add_signatory_amounts.sql @@ -0,0 +1 @@ +ALTER TABLE keyset ADD COLUMN amounts TEXT DEFAULT NULL; diff --git a/crates/cdk-sql-common/src/mint/migrations/sqlite/20250903200000_add_signatory_amounts.sql b/crates/cdk-sql-common/src/mint/migrations/sqlite/20250903200000_add_signatory_amounts.sql new file mode 100644 index 000000000..348591f91 --- /dev/null +++ b/crates/cdk-sql-common/src/mint/migrations/sqlite/20250903200000_add_signatory_amounts.sql @@ -0,0 +1,33 @@ +CREATE TABLE keyset_new ( + id TEXT PRIMARY KEY, + unit TEXT NOT NULL, + active BOOL NOT NULL, + valid_from INTEGER NOT NULL, + valid_to INTEGER, + max_order INTEGER NOT NULL, + amounts TEXT DEFAULT NULL, + input_fee_ppk INTEGER, + derivation_path TEXT NOT NULL, + derivation_path_index INTEGER +); + + +INSERT INTO keyset_new SELECT + id, + unit, + active, + valid_from, + valid_to, + max_order, + NULL, + input_fee_ppk, + derivation_path, + derivation_path_index +FROM keyset; + +DROP TABLE keyset; + +ALTER TABLE keyset_new RENAME TO keyset; + +CREATE INDEX unit_index ON keyset(unit); +CREATE INDEX active_index ON keyset(active); diff --git a/crates/cdk-sql-common/src/mint/mod.rs b/crates/cdk-sql-common/src/mint/mod.rs index 8e1fcdc3b..9e83e8c35 100644 --- a/crates/cdk-sql-common/src/mint/mod.rs +++ b/crates/cdk-sql-common/src/mint/mod.rs @@ -383,11 +383,11 @@ where INSERT INTO keyset ( id, unit, active, valid_from, valid_to, derivation_path, - max_order, input_fee_ppk, derivation_path_index + max_order, amounts, input_fee_ppk, derivation_path_index ) VALUES ( :id, :unit, :active, :valid_from, :valid_to, :derivation_path, - :max_order, :input_fee_ppk, :derivation_path_index + :max_order, :amounts, :input_fee_ppk, :derivation_path_index ) ON CONFLICT(id) DO UPDATE SET unit = excluded.unit, @@ -396,6 +396,7 @@ where valid_to = excluded.valid_to, derivation_path = excluded.derivation_path, max_order = excluded.max_order, + amounts = excluded.amounts, input_fee_ppk = excluded.input_fee_ppk, derivation_path_index = excluded.derivation_path_index "#, @@ -407,6 +408,7 @@ where .bind("valid_to", keyset.final_expiry.map(|v| v as i64)) .bind("derivation_path", keyset.derivation_path.to_string()) .bind("max_order", keyset.max_order) + .bind("amounts", serde_json::to_string(&keyset.amounts).ok()) .bind("input_fee_ppk", keyset.input_fee_ppk as i64) .bind("derivation_path_index", keyset.derivation_path_index) .execute(&self.inner) @@ -496,6 +498,7 @@ where derivation_path, derivation_path_index, max_order, + amounts, input_fee_ppk FROM keyset @@ -520,6 +523,7 @@ where derivation_path, derivation_path_index, max_order, + amounts, input_fee_ppk FROM keyset @@ -1837,10 +1841,16 @@ fn sql_row_to_keyset_info(row: Vec) -> Result { derivation_path, derivation_path_index, max_order, + amounts, row_keyset_ppk ) = row ); + let max_order: u8 = column_as_number!(max_order); + let amounts = column_as_nullable_string!(amounts) + .and_then(|str| serde_json::from_str(&str).ok()) + .unwrap_or_else(|| (0..max_order).map(|m| 2u64.pow(m.into())).collect()); + Ok(MintKeySetInfo { id: column_as_string!(id, Id::from_str, Id::from_bytes), unit: column_as_string!(unit, CurrencyUnit::from_str), @@ -1848,7 +1858,8 @@ fn sql_row_to_keyset_info(row: Vec) -> Result { valid_from: column_as_number!(valid_from), derivation_path: column_as_string!(derivation_path, DerivationPath::from_str), derivation_path_index: column_as_nullable_number!(derivation_path_index), - max_order: column_as_number!(max_order), + max_order, + amounts, input_fee_ppk: column_as_number!(row_keyset_ppk), final_expiry: column_as_nullable_number!(valid_to), }) @@ -2062,3 +2073,97 @@ fn sql_row_to_blind_signature(row: Vec) -> Result dleq, }) } + +#[cfg(test)] +mod test { + use super::*; + + mod max_order_to_amounts_migrations { + use super::*; + + #[test] + fn legacy_payload() { + let result = sql_row_to_keyset_info(vec![ + Column::Text("0083a60439303340".to_owned()), + Column::Text("sat".to_owned()), + Column::Integer(1), + Column::Integer(1749844864), + Column::Null, + Column::Text("0'/0'/0'".to_owned()), + Column::Integer(0), + Column::Integer(32), + Column::Null, + Column::Integer(0), + ]); + assert!(result.is_ok()); + } + + #[test] + fn migrated_payload() { + let legacy = sql_row_to_keyset_info(vec![ + Column::Text("0083a60439303340".to_owned()), + Column::Text("sat".to_owned()), + Column::Integer(1), + Column::Integer(1749844864), + Column::Null, + Column::Text("0'/0'/0'".to_owned()), + Column::Integer(0), + Column::Integer(32), + Column::Null, + Column::Integer(0), + ]); + assert!(legacy.is_ok()); + + let amounts = (0..32).map(|x| 2u64.pow(x)).collect::>(); + let migrated = sql_row_to_keyset_info(vec![ + Column::Text("0083a60439303340".to_owned()), + Column::Text("sat".to_owned()), + Column::Integer(1), + Column::Integer(1749844864), + Column::Null, + Column::Text("0'/0'/0'".to_owned()), + Column::Integer(0), + Column::Integer(32), + Column::Text(serde_json::to_string(&amounts).expect("valid json")), + Column::Integer(0), + ]); + assert!(migrated.is_ok()); + assert_eq!(legacy.unwrap(), migrated.unwrap()); + } + + #[test] + fn amounts_over_max_order() { + let legacy = sql_row_to_keyset_info(vec![ + Column::Text("0083a60439303340".to_owned()), + Column::Text("sat".to_owned()), + Column::Integer(1), + Column::Integer(1749844864), + Column::Null, + Column::Text("0'/0'/0'".to_owned()), + Column::Integer(0), + Column::Integer(32), + Column::Null, + Column::Integer(0), + ]); + assert!(legacy.is_ok()); + + let amounts = (0..16).map(|x| 2u64.pow(x)).collect::>(); + let migrated = sql_row_to_keyset_info(vec![ + Column::Text("0083a60439303340".to_owned()), + Column::Text("sat".to_owned()), + Column::Integer(1), + Column::Integer(1749844864), + Column::Null, + Column::Text("0'/0'/0'".to_owned()), + Column::Integer(0), + Column::Integer(32), + Column::Text(serde_json::to_string(&amounts).expect("valid json")), + Column::Integer(0), + ]); + assert!(migrated.is_ok()); + let migrated = migrated.unwrap(); + assert_ne!(legacy.unwrap(), migrated); + assert_eq!(migrated.amounts.len(), 16); + } + } +} diff --git a/crates/cdk/src/mint/keysets/mod.rs b/crates/cdk/src/mint/keysets/mod.rs index c9a06267f..bfe8c853b 100644 --- a/crates/cdk/src/mint/keysets/mod.rs +++ b/crates/cdk/src/mint/keysets/mod.rs @@ -82,7 +82,7 @@ impl Mint { .signatory .rotate_keyset(RotateKeyArguments { unit, - max_order, + amounts: (0..max_order).map(|n| 2u64.pow(n.into())).collect(), input_fee_ppk, }) .await?; From 9b35158a8a8e357ad928b665099e4bd35e9929f8 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Sat, 6 Sep 2025 16:04:29 +0100 Subject: [PATCH 129/321] fix: sig error code (#1038) --- crates/cdk-axum/src/router_handlers.rs | 1 + crates/cdk-common/src/error.rs | 35 ++++++++++++++++++++++++++ 2 files changed, 36 insertions(+) diff --git a/crates/cdk-axum/src/router_handlers.rs b/crates/cdk-axum/src/router_handlers.rs index 541d1d505..207f34c74 100644 --- a/crates/cdk-axum/src/router_handlers.rs +++ b/crates/cdk-axum/src/router_handlers.rs @@ -561,6 +561,7 @@ where | ErrorCode::TransactionUnbalanced | ErrorCode::AmountOutofLimitRange | ErrorCode::WitnessMissingOrInvalid + | ErrorCode::DuplicateSignature | ErrorCode::DuplicateInputs | ErrorCode::DuplicateOutputs | ErrorCode::MultipleUnits diff --git a/crates/cdk-common/src/error.rs b/crates/cdk-common/src/error.rs index 0b782f996..9e0f8fd7c 100644 --- a/crates/cdk-common/src/error.rs +++ b/crates/cdk-common/src/error.rs @@ -209,6 +209,9 @@ pub enum Error { /// P2PK spending conditions not met #[error("P2PK condition not met `{0}`")] P2PKConditionsNotMet(String), + /// Duplicate signature from same pubkey in P2PK + #[error("Duplicate signature from same pubkey in P2PK")] + DuplicateSignatureError, /// Spending Locktime not provided #[error("Spending condition locktime not provided")] LocktimeNotProvided, @@ -438,6 +441,16 @@ impl ErrorResponse { } } +/// Maps NUT11 errors to appropriate error codes +fn map_nut11_error(nut11_error: &crate::nuts::nut11::Error) -> ErrorCode { + match nut11_error { + crate::nuts::nut11::Error::SignaturesNotProvided => ErrorCode::WitnessMissingOrInvalid, + crate::nuts::nut11::Error::InvalidSignature => ErrorCode::WitnessMissingOrInvalid, + crate::nuts::nut11::Error::DuplicateSignature => ErrorCode::DuplicateSignature, + _ => ErrorCode::Unknown(9999), // Parsing/validation errors + } +} + impl From for ErrorResponse { fn from(err: Error) -> ErrorResponse { match err { @@ -555,6 +568,23 @@ impl From for ErrorResponse { error: Some(err.to_string()), detail: None }, + Error::NUT11(err) => { + let code = map_nut11_error(&err); + let mut detail = None; + if matches!(err, crate::nuts::nut11::Error::SignaturesNotProvided) { + detail = Some("P2PK signatures are required but not provided".to_string()); + } + ErrorResponse { + code, + error: Some(err.to_string()), + detail, + } + }, + Error::DuplicateSignatureError => ErrorResponse { + code: ErrorCode::DuplicateSignature, + error: Some(err.to_string()), + detail: None, + }, _ => ErrorResponse { code: ErrorCode::Unknown(9999), error: Some(err.to_string()), @@ -612,6 +642,7 @@ impl From for Error { ErrorCode::UnitMismatch => Self::UnitMismatch, ErrorCode::ClearAuthRequired => Self::ClearAuthRequired, ErrorCode::BlindAuthRequired => Self::BlindAuthRequired, + ErrorCode::DuplicateSignature => Self::DuplicateSignatureError, _ => Self::UnknownErrorResponse(err.to_string()), } } @@ -671,6 +702,8 @@ pub enum ErrorCode { BlindAuthRequired, /// Blind Auth Failed BlindAuthFailed, + /// Duplicate signature from same pubkey + DuplicateSignature, /// Unknown error code Unknown(u16), } @@ -700,6 +733,7 @@ impl ErrorCode { 20006 => Self::InvoiceAlreadyPaid, 20007 => Self::QuoteExpired, 20008 => Self::WitnessMissingOrInvalid, + 20009 => Self::DuplicateSignature, 30001 => Self::ClearAuthRequired, 30002 => Self::ClearAuthFailed, 31001 => Self::BlindAuthRequired, @@ -732,6 +766,7 @@ impl ErrorCode { Self::InvoiceAlreadyPaid => 20006, Self::QuoteExpired => 20007, Self::WitnessMissingOrInvalid => 20008, + Self::DuplicateSignature => 20009, Self::ClearAuthRequired => 30001, Self::ClearAuthFailed => 30002, Self::BlindAuthRequired => 31001, From 5518ad2654e199bcc5c489860face5981590780a Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Sat, 6 Sep 2025 19:57:23 +0100 Subject: [PATCH 130/321] feat(cdk): add quote_id field to transactions for quote tracking (#1041) - Add quote_id field to Transaction struct in cdk-common - Add database migrations for quote_id column in SQLite and PostgreSQL - Update wallet operations to populate quote_id for mint/melt transactions - Set quote_id to None for send/receive operations without associated quotes --- CHANGELOG.md | 2 ++ crates/cdk-common/src/wallet.rs | 2 ++ .../cdk-sql-common/src/mint/auth/migrations.rs | 4 ++-- crates/cdk-sql-common/src/mint/migrations.rs | 6 +++--- crates/cdk-sql-common/src/wallet/migrations.rs | 6 ++++-- ...20250906200000_add_transaction_quote_id.sql | 1 + ...20250906200000_add_transaction_quote_id.sql | 1 + crates/cdk-sql-common/src/wallet/mod.rs | 18 ++++++++++++------ crates/cdk/src/wallet/issue/issue_bolt11.rs | 1 + crates/cdk/src/wallet/issue/issue_bolt12.rs | 1 + crates/cdk/src/wallet/melt/melt_bolt11.rs | 1 + crates/cdk/src/wallet/melt/mod.rs | 1 + crates/cdk/src/wallet/receive.rs | 1 + crates/cdk/src/wallet/send.rs | 1 + 14 files changed, 33 insertions(+), 13 deletions(-) create mode 100644 crates/cdk-sql-common/src/wallet/migrations/postgres/20250906200000_add_transaction_quote_id.sql create mode 100644 crates/cdk-sql-common/src/wallet/migrations/sqlite/20250906200000_add_transaction_quote_id.sql diff --git a/CHANGELOG.md b/CHANGELOG.md index 45be50e22..250c20995 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,8 @@ - cdk-common: Added comprehensive test module for KV store functionality with transaction and isolation testing ([thesimplekid]). - cdk-sql-common: Database migration to add `kv_store` table for generic key-value storage in SQLite and PostgreSQL ([thesimplekid]). - cdk-sql-common: Implementation of `MintKVStoreDatabase` trait for SQL-based databases with namespace support ([thesimplekid]). +- cdk-common: Added `quote_id` field to `Transaction` struct for tracking associated mint or melt quote IDs ([thesimplekid]). +- cdk-sql-common: Database migration to add `quote_id` column to transactions table for SQLite and PostgreSQL ([thesimplekid]). ### Changed - cdk-common: Refactored `MintPayment` trait method `wait_any_incoming_payment` to `wait_payment_event` with event-driven architecture ([thesimplekid]). diff --git a/crates/cdk-common/src/wallet.rs b/crates/cdk-common/src/wallet.rs index f4a554296..d350b9466 100644 --- a/crates/cdk-common/src/wallet.rs +++ b/crates/cdk-common/src/wallet.rs @@ -202,6 +202,8 @@ pub struct Transaction { pub memo: Option, /// User-defined metadata pub metadata: HashMap, + /// Quote ID if this is a mint or melt transaction + pub quote_id: Option, } impl Transaction { diff --git a/crates/cdk-sql-common/src/mint/auth/migrations.rs b/crates/cdk-sql-common/src/mint/auth/migrations.rs index 3b95bcda5..5d2af7452 100644 --- a/crates/cdk-sql-common/src/mint/auth/migrations.rs +++ b/crates/cdk-sql-common/src/mint/auth/migrations.rs @@ -1,9 +1,9 @@ /// @generated /// Auto-generated by build.rs pub static MIGRATIONS: &[(&str, &str, &str)] = &[ - ("sqlite", "1_fix_sqlx_migration.sql", include_str!(r#"./migrations/sqlite/1_fix_sqlx_migration.sql"#)), ("postgres", "1_init.sql", include_str!(r#"./migrations/postgres/1_init.sql"#)), + ("sqlite", "1_fix_sqlx_migration.sql", include_str!(r#"./migrations/sqlite/1_fix_sqlx_migration.sql"#)), ("sqlite", "20250109143347_init.sql", include_str!(r#"./migrations/sqlite/20250109143347_init.sql"#)), - ("sqlite", "20250822104351_rename_blind_message_y_to_b.sql", include_str!(r#"./migrations/sqlite/20250822104351_rename_blind_message_y_to_b.sql"#)), ("postgres", "20250822104351_rename_blind_message_y_to_b.sql", include_str!(r#"./migrations/postgres/20250822104351_rename_blind_message_y_to_b.sql"#)), + ("sqlite", "20250822104351_rename_blind_message_y_to_b.sql", include_str!(r#"./migrations/sqlite/20250822104351_rename_blind_message_y_to_b.sql"#)), ]; diff --git a/crates/cdk-sql-common/src/mint/migrations.rs b/crates/cdk-sql-common/src/mint/migrations.rs index eddf05524..dd16d3107 100644 --- a/crates/cdk-sql-common/src/mint/migrations.rs +++ b/crates/cdk-sql-common/src/mint/migrations.rs @@ -1,8 +1,8 @@ /// @generated /// Auto-generated by build.rs pub static MIGRATIONS: &[(&str, &str, &str)] = &[ - ("sqlite", "1_fix_sqlx_migration.sql", include_str!(r#"./migrations/sqlite/1_fix_sqlx_migration.sql"#)), ("postgres", "1_initial.sql", include_str!(r#"./migrations/postgres/1_initial.sql"#)), + ("sqlite", "1_fix_sqlx_migration.sql", include_str!(r#"./migrations/sqlite/1_fix_sqlx_migration.sql"#)), ("postgres", "2_remove_request_lookup_kind_constraints.sql", include_str!(r#"./migrations/postgres/2_remove_request_lookup_kind_constraints.sql"#)), ("sqlite", "20240612124932_init.sql", include_str!(r#"./migrations/sqlite/20240612124932_init.sql"#)), ("sqlite", "20240618195700_quote_state.sql", include_str!(r#"./migrations/sqlite/20240618195700_quote_state.sql"#)), @@ -27,8 +27,8 @@ pub static MIGRATIONS: &[(&str, &str, &str)] = &[ ("sqlite", "20250706101057_bolt12.sql", include_str!(r#"./migrations/sqlite/20250706101057_bolt12.sql"#)), ("sqlite", "20250812132015_drop_melt_request.sql", include_str!(r#"./migrations/sqlite/20250812132015_drop_melt_request.sql"#)), ("sqlite", "20250819200000_remove_request_lookup_kind_constraints.sql", include_str!(r#"./migrations/sqlite/20250819200000_remove_request_lookup_kind_constraints.sql"#)), - ("sqlite", "20250901090000_add_kv_store.sql", include_str!(r#"./migrations/sqlite/20250901090000_add_kv_store.sql"#)), ("postgres", "20250901090000_add_kv_store.sql", include_str!(r#"./migrations/postgres/20250901090000_add_kv_store.sql"#)), - ("sqlite", "20250903200000_add_signatory_amounts.sql", include_str!(r#"./migrations/sqlite/20250903200000_add_signatory_amounts.sql"#)), + ("sqlite", "20250901090000_add_kv_store.sql", include_str!(r#"./migrations/sqlite/20250901090000_add_kv_store.sql"#)), ("postgres", "20250903200000_add_signatory_amounts.sql", include_str!(r#"./migrations/postgres/20250903200000_add_signatory_amounts.sql"#)), + ("sqlite", "20250903200000_add_signatory_amounts.sql", include_str!(r#"./migrations/sqlite/20250903200000_add_signatory_amounts.sql"#)), ]; diff --git a/crates/cdk-sql-common/src/wallet/migrations.rs b/crates/cdk-sql-common/src/wallet/migrations.rs index 767195231..13bbbb6c8 100644 --- a/crates/cdk-sql-common/src/wallet/migrations.rs +++ b/crates/cdk-sql-common/src/wallet/migrations.rs @@ -1,8 +1,8 @@ /// @generated /// Auto-generated by build.rs pub static MIGRATIONS: &[(&str, &str, &str)] = &[ - ("sqlite", "1_fix_sqlx_migration.sql", include_str!(r#"./migrations/sqlite/1_fix_sqlx_migration.sql"#)), ("postgres", "1_initial.sql", include_str!(r#"./migrations/postgres/1_initial.sql"#)), + ("sqlite", "1_fix_sqlx_migration.sql", include_str!(r#"./migrations/sqlite/1_fix_sqlx_migration.sql"#)), ("sqlite", "20240612132920_init.sql", include_str!(r#"./migrations/sqlite/20240612132920_init.sql"#)), ("sqlite", "20240618200350_quote_state.sql", include_str!(r#"./migrations/sqlite/20240618200350_quote_state.sql"#)), ("sqlite", "20240626091921_nut04_state.sql", include_str!(r#"./migrations/sqlite/20240626091921_nut04_state.sql"#)), @@ -22,6 +22,8 @@ pub static MIGRATIONS: &[(&str, &str, &str)] = &[ ("sqlite", "20250707093445_bolt12.sql", include_str!(r#"./migrations/sqlite/20250707093445_bolt12.sql"#)), ("sqlite", "20250729111701_keyset_v2_u32.sql", include_str!(r#"./migrations/sqlite/20250729111701_keyset_v2_u32.sql"#)), ("sqlite", "20250812084621_keyset_plus_one.sql", include_str!(r#"./migrations/sqlite/20250812084621_keyset_plus_one.sql"#)), - ("sqlite", "20250831215438_melt_quote_method.sql", include_str!(r#"./migrations/sqlite/20250831215438_melt_quote_method.sql"#)), ("postgres", "20250831215438_melt_quote_method.sql", include_str!(r#"./migrations/postgres/20250831215438_melt_quote_method.sql"#)), + ("sqlite", "20250831215438_melt_quote_method.sql", include_str!(r#"./migrations/sqlite/20250831215438_melt_quote_method.sql"#)), + ("postgres", "20250906200000_add_transaction_quote_id.sql", include_str!(r#"./migrations/postgres/20250906200000_add_transaction_quote_id.sql"#)), + ("sqlite", "20250906200000_add_transaction_quote_id.sql", include_str!(r#"./migrations/sqlite/20250906200000_add_transaction_quote_id.sql"#)), ]; diff --git a/crates/cdk-sql-common/src/wallet/migrations/postgres/20250906200000_add_transaction_quote_id.sql b/crates/cdk-sql-common/src/wallet/migrations/postgres/20250906200000_add_transaction_quote_id.sql new file mode 100644 index 000000000..8d9fb71c6 --- /dev/null +++ b/crates/cdk-sql-common/src/wallet/migrations/postgres/20250906200000_add_transaction_quote_id.sql @@ -0,0 +1 @@ +ALTER TABLE transactions ADD COLUMN quote_id TEXT; diff --git a/crates/cdk-sql-common/src/wallet/migrations/sqlite/20250906200000_add_transaction_quote_id.sql b/crates/cdk-sql-common/src/wallet/migrations/sqlite/20250906200000_add_transaction_quote_id.sql new file mode 100644 index 000000000..8d9fb71c6 --- /dev/null +++ b/crates/cdk-sql-common/src/wallet/migrations/sqlite/20250906200000_add_transaction_quote_id.sql @@ -0,0 +1 @@ +ALTER TABLE transactions ADD COLUMN quote_id TEXT; diff --git a/crates/cdk-sql-common/src/wallet/mod.rs b/crates/cdk-sql-common/src/wallet/mod.rs index b4bda761e..6078a3677 100644 --- a/crates/cdk-sql-common/src/wallet/mod.rs +++ b/crates/cdk-sql-common/src/wallet/mod.rs @@ -903,9 +903,9 @@ ON CONFLICT(id) DO UPDATE SET query( r#" INSERT INTO transactions -(id, mint_url, direction, unit, amount, fee, ys, timestamp, memo, metadata) +(id, mint_url, direction, unit, amount, fee, ys, timestamp, memo, metadata, quote_id) VALUES -(:id, :mint_url, :direction, :unit, :amount, :fee, :ys, :timestamp, :memo, :metadata) +(:id, :mint_url, :direction, :unit, :amount, :fee, :ys, :timestamp, :memo, :metadata, :quote_id) ON CONFLICT(id) DO UPDATE SET mint_url = excluded.mint_url, direction = excluded.direction, @@ -915,7 +915,8 @@ ON CONFLICT(id) DO UPDATE SET ys = excluded.ys, timestamp = excluded.timestamp, memo = excluded.memo, - metadata = excluded.metadata + metadata = excluded.metadata, + quote_id = excluded.quote_id ; "#, )? @@ -932,6 +933,7 @@ ON CONFLICT(id) DO UPDATE SET "metadata", serde_json::to_string(&transaction.metadata).map_err(Error::from)?, ) + .bind("quote_id", transaction.quote_id) .execute(&*conn) .await?; @@ -955,7 +957,8 @@ ON CONFLICT(id) DO UPDATE SET ys, timestamp, memo, - metadata + metadata, + quote_id FROM transactions WHERE @@ -989,7 +992,8 @@ ON CONFLICT(id) DO UPDATE SET ys, timestamp, memo, - metadata + metadata, + quote_id FROM transactions "#, @@ -1226,7 +1230,8 @@ fn sql_row_to_transaction(row: Vec) -> Result { ys, timestamp, memo, - metadata + metadata, + quote_id ) = row ); @@ -1249,5 +1254,6 @@ fn sql_row_to_transaction(row: Vec) -> Result { serde_json::from_slice(&v).ok() }) .unwrap_or_default(), + quote_id: column_as_nullable_string!(quote_id), }) } diff --git a/crates/cdk/src/wallet/issue/issue_bolt11.rs b/crates/cdk/src/wallet/issue/issue_bolt11.rs index af436ef26..dfe17a526 100644 --- a/crates/cdk/src/wallet/issue/issue_bolt11.rs +++ b/crates/cdk/src/wallet/issue/issue_bolt11.rs @@ -322,6 +322,7 @@ impl Wallet { timestamp: unix_time, memo: None, metadata: HashMap::new(), + quote_id: Some(quote_id.to_string()), }) .await?; diff --git a/crates/cdk/src/wallet/issue/issue_bolt12.rs b/crates/cdk/src/wallet/issue/issue_bolt12.rs index 085cbc58c..1673ac894 100644 --- a/crates/cdk/src/wallet/issue/issue_bolt12.rs +++ b/crates/cdk/src/wallet/issue/issue_bolt12.rs @@ -226,6 +226,7 @@ impl Wallet { timestamp: unix_time(), memo: None, metadata: HashMap::new(), + quote_id: Some(quote_id.to_string()), }) .await?; diff --git a/crates/cdk/src/wallet/melt/melt_bolt11.rs b/crates/cdk/src/wallet/melt/melt_bolt11.rs index 63ef4de69..050f7a839 100644 --- a/crates/cdk/src/wallet/melt/melt_bolt11.rs +++ b/crates/cdk/src/wallet/melt/melt_bolt11.rs @@ -285,6 +285,7 @@ impl Wallet { timestamp: unix_time(), memo: None, metadata: HashMap::new(), + quote_id: Some(quote_id.to_string()), }) .await?; diff --git a/crates/cdk/src/wallet/melt/mod.rs b/crates/cdk/src/wallet/melt/mod.rs index 09ab55cea..c923e0c6e 100644 --- a/crates/cdk/src/wallet/melt/mod.rs +++ b/crates/cdk/src/wallet/melt/mod.rs @@ -74,6 +74,7 @@ impl Wallet { timestamp: unix_time(), memo: None, metadata: HashMap::new(), + quote_id: Some(quote.id.clone()), }) .await?; } diff --git a/crates/cdk/src/wallet/receive.rs b/crates/cdk/src/wallet/receive.rs index 607f6dbf3..2d0334b4f 100644 --- a/crates/cdk/src/wallet/receive.rs +++ b/crates/cdk/src/wallet/receive.rs @@ -167,6 +167,7 @@ impl Wallet { timestamp: unix_time(), memo, metadata: opts.metadata, + quote_id: None, // Receive transactions don't have a quote_id }) .await?; diff --git a/crates/cdk/src/wallet/send.rs b/crates/cdk/src/wallet/send.rs index 190749ba8..0bab22d7f 100644 --- a/crates/cdk/src/wallet/send.rs +++ b/crates/cdk/src/wallet/send.rs @@ -345,6 +345,7 @@ impl PreparedSend { timestamp: unix_time(), memo: memo.clone(), metadata: self.options.metadata, + quote_id: None, // Send transactions don't have a quote_id }) .await?; From caa0b4a9f5c1aa25490ddf5391c46944b577d972 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Sun, 7 Sep 2025 08:17:48 +0100 Subject: [PATCH 131/321] fix: remove unused structs (#1042) --- crates/cdk-signatory/src/proto/signatory.proto | 9 --------- 1 file changed, 9 deletions(-) diff --git a/crates/cdk-signatory/src/proto/signatory.proto b/crates/cdk-signatory/src/proto/signatory.proto index 600bb2232..5b82408a2 100644 --- a/crates/cdk-signatory/src/proto/signatory.proto +++ b/crates/cdk-signatory/src/proto/signatory.proto @@ -105,16 +105,7 @@ message Proof { bytes c = 4; } -message ProofDLEQ { - bytes e = 1; - bytes s = 2; - bytes r = 3; -} -message SigningResponse { - Error error = 1; - BlindSignatures blind_signatures = 2; -} message BlindSignatures { repeated BlindSignature blind_signatures = 1; } From 87691bd8aaa31752089cb844a7710a7fe06ea16c Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Mon, 8 Sep 2025 10:16:40 +0100 Subject: [PATCH 132/321] chore: increase timeout (#1046) --- misc/mintd_payment_processor.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/misc/mintd_payment_processor.sh b/misc/mintd_payment_processor.sh index f43a1034e..04afe6490 100755 --- a/misc/mintd_payment_processor.sh +++ b/misc/mintd_payment_processor.sh @@ -147,7 +147,7 @@ CDK_MINTD_PID=$! echo $CDK_ITESTS_DIR -TIMEOUT=100 +TIMEOUT=300 START_TIME=$(date +%s) # Loop until the endpoint returns a 200 OK status or timeout is reached while true; do From 4363d14281e0c2c4dc71e1ee7b4a3cffae4d24a0 Mon Sep 17 00:00:00 2001 From: C Date: Mon, 8 Sep 2025 06:17:00 -0300 Subject: [PATCH 133/321] Add consistent ordering of sql migrations (#1047) Also sort the prefix and not only the filenames --- crates/cdk-sql-common/build.rs | 44 +++++++++++++++---- .../src/mint/auth/migrations.rs | 2 +- crates/cdk-sql-common/src/mint/migrations.rs | 6 +-- .../cdk-sql-common/src/wallet/migrations.rs | 4 +- 4 files changed, 42 insertions(+), 14 deletions(-) diff --git a/crates/cdk-sql-common/build.rs b/crates/cdk-sql-common/build.rs index eeea575c3..9cba59330 100644 --- a/crates/cdk-sql-common/build.rs +++ b/crates/cdk-sql-common/build.rs @@ -1,3 +1,4 @@ +use std::cmp::Ordering; use std::fs::{self, File}; use std::io::Write; use std::path::{Path, PathBuf}; @@ -7,10 +8,45 @@ fn main() { let root = Path::new("src"); for migration_path in find_migrations_dirs(root) { + // Step 3: Output file path (e.g., `src/db/migrations.rs`) + let parent = migration_path.parent().unwrap(); + let skip_path = parent.to_str().unwrap_or_default().len(); + let dest_path = parent.join("migrations.rs"); + let mut out_file = File::create(&dest_path).expect("Failed to create migrations.rs"); + + let skip_name = migration_path.to_str().unwrap_or_default().len(); + // Step 2: Collect all files inside the migrations dir let mut files = Vec::new(); visit_dirs(&migration_path, &mut files).expect("Failed to read migrations directory"); files.sort_by(|path_a, path_b| { + let parts_a = path_a.to_str().unwrap().replace("\\", "/")[skip_name + 1..] + .split("/") + .map(|x| x.to_owned()) + .collect::>(); + let parts_b = path_b.to_str().unwrap().replace("\\", "/")[skip_name + 1..] + .split("/") + .map(|x| x.to_owned()) + .collect::>(); + + let prefix_a = if parts_a.len() == 2 { + parts_a.first().map(|x| x.to_owned()).unwrap_or_default() + } else { + "".to_owned() + }; + + let prefix_b = if parts_a.len() == 2 { + parts_b.first().map(|x| x.to_owned()).unwrap_or_default() + } else { + "".to_owned() + }; + + let prefix_cmp = prefix_a.cmp(&prefix_b); + + if prefix_cmp != Ordering::Equal { + return prefix_cmp; + } + let path_a = path_a.file_name().unwrap().to_str().unwrap(); let path_b = path_b.file_name().unwrap().to_str().unwrap(); @@ -32,14 +68,6 @@ fn main() { } }); - // Step 3: Output file path (e.g., `src/db/migrations.rs`) - let parent = migration_path.parent().unwrap(); - let skip_path = parent.to_str().unwrap_or_default().len(); - let dest_path = parent.join("migrations.rs"); - let mut out_file = File::create(&dest_path).expect("Failed to create migrations.rs"); - - let skip_name = migration_path.to_str().unwrap_or_default().len(); - writeln!(out_file, "/// @generated").unwrap(); writeln!(out_file, "/// Auto-generated by build.rs").unwrap(); writeln!( diff --git a/crates/cdk-sql-common/src/mint/auth/migrations.rs b/crates/cdk-sql-common/src/mint/auth/migrations.rs index 5d2af7452..ee53d6bdb 100644 --- a/crates/cdk-sql-common/src/mint/auth/migrations.rs +++ b/crates/cdk-sql-common/src/mint/auth/migrations.rs @@ -2,8 +2,8 @@ /// Auto-generated by build.rs pub static MIGRATIONS: &[(&str, &str, &str)] = &[ ("postgres", "1_init.sql", include_str!(r#"./migrations/postgres/1_init.sql"#)), + ("postgres", "20250822104351_rename_blind_message_y_to_b.sql", include_str!(r#"./migrations/postgres/20250822104351_rename_blind_message_y_to_b.sql"#)), ("sqlite", "1_fix_sqlx_migration.sql", include_str!(r#"./migrations/sqlite/1_fix_sqlx_migration.sql"#)), ("sqlite", "20250109143347_init.sql", include_str!(r#"./migrations/sqlite/20250109143347_init.sql"#)), - ("postgres", "20250822104351_rename_blind_message_y_to_b.sql", include_str!(r#"./migrations/postgres/20250822104351_rename_blind_message_y_to_b.sql"#)), ("sqlite", "20250822104351_rename_blind_message_y_to_b.sql", include_str!(r#"./migrations/sqlite/20250822104351_rename_blind_message_y_to_b.sql"#)), ]; diff --git a/crates/cdk-sql-common/src/mint/migrations.rs b/crates/cdk-sql-common/src/mint/migrations.rs index dd16d3107..1db88edea 100644 --- a/crates/cdk-sql-common/src/mint/migrations.rs +++ b/crates/cdk-sql-common/src/mint/migrations.rs @@ -2,8 +2,10 @@ /// Auto-generated by build.rs pub static MIGRATIONS: &[(&str, &str, &str)] = &[ ("postgres", "1_initial.sql", include_str!(r#"./migrations/postgres/1_initial.sql"#)), - ("sqlite", "1_fix_sqlx_migration.sql", include_str!(r#"./migrations/sqlite/1_fix_sqlx_migration.sql"#)), ("postgres", "2_remove_request_lookup_kind_constraints.sql", include_str!(r#"./migrations/postgres/2_remove_request_lookup_kind_constraints.sql"#)), + ("postgres", "20250901090000_add_kv_store.sql", include_str!(r#"./migrations/postgres/20250901090000_add_kv_store.sql"#)), + ("postgres", "20250903200000_add_signatory_amounts.sql", include_str!(r#"./migrations/postgres/20250903200000_add_signatory_amounts.sql"#)), + ("sqlite", "1_fix_sqlx_migration.sql", include_str!(r#"./migrations/sqlite/1_fix_sqlx_migration.sql"#)), ("sqlite", "20240612124932_init.sql", include_str!(r#"./migrations/sqlite/20240612124932_init.sql"#)), ("sqlite", "20240618195700_quote_state.sql", include_str!(r#"./migrations/sqlite/20240618195700_quote_state.sql"#)), ("sqlite", "20240626092101_nut04_state.sql", include_str!(r#"./migrations/sqlite/20240626092101_nut04_state.sql"#)), @@ -27,8 +29,6 @@ pub static MIGRATIONS: &[(&str, &str, &str)] = &[ ("sqlite", "20250706101057_bolt12.sql", include_str!(r#"./migrations/sqlite/20250706101057_bolt12.sql"#)), ("sqlite", "20250812132015_drop_melt_request.sql", include_str!(r#"./migrations/sqlite/20250812132015_drop_melt_request.sql"#)), ("sqlite", "20250819200000_remove_request_lookup_kind_constraints.sql", include_str!(r#"./migrations/sqlite/20250819200000_remove_request_lookup_kind_constraints.sql"#)), - ("postgres", "20250901090000_add_kv_store.sql", include_str!(r#"./migrations/postgres/20250901090000_add_kv_store.sql"#)), ("sqlite", "20250901090000_add_kv_store.sql", include_str!(r#"./migrations/sqlite/20250901090000_add_kv_store.sql"#)), - ("postgres", "20250903200000_add_signatory_amounts.sql", include_str!(r#"./migrations/postgres/20250903200000_add_signatory_amounts.sql"#)), ("sqlite", "20250903200000_add_signatory_amounts.sql", include_str!(r#"./migrations/sqlite/20250903200000_add_signatory_amounts.sql"#)), ]; diff --git a/crates/cdk-sql-common/src/wallet/migrations.rs b/crates/cdk-sql-common/src/wallet/migrations.rs index 13bbbb6c8..4f3d0c1b7 100644 --- a/crates/cdk-sql-common/src/wallet/migrations.rs +++ b/crates/cdk-sql-common/src/wallet/migrations.rs @@ -2,6 +2,8 @@ /// Auto-generated by build.rs pub static MIGRATIONS: &[(&str, &str, &str)] = &[ ("postgres", "1_initial.sql", include_str!(r#"./migrations/postgres/1_initial.sql"#)), + ("postgres", "20250831215438_melt_quote_method.sql", include_str!(r#"./migrations/postgres/20250831215438_melt_quote_method.sql"#)), + ("postgres", "20250906200000_add_transaction_quote_id.sql", include_str!(r#"./migrations/postgres/20250906200000_add_transaction_quote_id.sql"#)), ("sqlite", "1_fix_sqlx_migration.sql", include_str!(r#"./migrations/sqlite/1_fix_sqlx_migration.sql"#)), ("sqlite", "20240612132920_init.sql", include_str!(r#"./migrations/sqlite/20240612132920_init.sql"#)), ("sqlite", "20240618200350_quote_state.sql", include_str!(r#"./migrations/sqlite/20240618200350_quote_state.sql"#)), @@ -22,8 +24,6 @@ pub static MIGRATIONS: &[(&str, &str, &str)] = &[ ("sqlite", "20250707093445_bolt12.sql", include_str!(r#"./migrations/sqlite/20250707093445_bolt12.sql"#)), ("sqlite", "20250729111701_keyset_v2_u32.sql", include_str!(r#"./migrations/sqlite/20250729111701_keyset_v2_u32.sql"#)), ("sqlite", "20250812084621_keyset_plus_one.sql", include_str!(r#"./migrations/sqlite/20250812084621_keyset_plus_one.sql"#)), - ("postgres", "20250831215438_melt_quote_method.sql", include_str!(r#"./migrations/postgres/20250831215438_melt_quote_method.sql"#)), ("sqlite", "20250831215438_melt_quote_method.sql", include_str!(r#"./migrations/sqlite/20250831215438_melt_quote_method.sql"#)), - ("postgres", "20250906200000_add_transaction_quote_id.sql", include_str!(r#"./migrations/postgres/20250906200000_add_transaction_quote_id.sql"#)), ("sqlite", "20250906200000_add_transaction_quote_id.sql", include_str!(r#"./migrations/sqlite/20250906200000_add_transaction_quote_id.sql"#)), ]; From b5b8ee557c1af4bdb6341d21714b77754746a9bf Mon Sep 17 00:00:00 2001 From: C Date: Mon, 8 Sep 2025 09:02:45 -0300 Subject: [PATCH 134/321] Fix race conditions in minting tests (#1043) There was a race conditions between the database storing the mint quote and the fake wallet paying the invoice of a yet not existing mint quote Add a delay of seconds before paying all invoices To recreate the slow conditions that would make our database slower than the external Fakewallet in Linux ``` sudo tc qdisc add dev lo root netem delay 200ms 50ms ionice -c3 nix develop -i -L .#stable --command just itest-payment-processor FAKEWALLET ``` To reset ``` sudo tc qdisc del dev lo root ``` --- crates/cdk-integration-tests/src/init_auth_mint.rs | 2 +- crates/cdk-integration-tests/src/init_pure_tests.rs | 2 +- crates/cdk-payment-processor/src/bin/payment_processor.rs | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/crates/cdk-integration-tests/src/init_auth_mint.rs b/crates/cdk-integration-tests/src/init_auth_mint.rs index bde2d0e13..63ca543e8 100644 --- a/crates/cdk-integration-tests/src/init_auth_mint.rs +++ b/crates/cdk-integration-tests/src/init_auth_mint.rs @@ -33,7 +33,7 @@ where fee_reserve, HashMap::default(), HashSet::default(), - 0, + 2, CurrencyUnit::Sat, ); diff --git a/crates/cdk-integration-tests/src/init_pure_tests.rs b/crates/cdk-integration-tests/src/init_pure_tests.rs index 21c090567..9b46b8049 100644 --- a/crates/cdk-integration-tests/src/init_pure_tests.rs +++ b/crates/cdk-integration-tests/src/init_pure_tests.rs @@ -247,7 +247,7 @@ pub async fn create_and_start_test_mint() -> Result { fee_reserve.clone(), HashMap::default(), HashSet::default(), - 0, + 2, CurrencyUnit::Sat, ); diff --git a/crates/cdk-payment-processor/src/bin/payment_processor.rs b/crates/cdk-payment-processor/src/bin/payment_processor.rs index d110583de..0ea98775b 100644 --- a/crates/cdk-payment-processor/src/bin/payment_processor.rs +++ b/crates/cdk-payment-processor/src/bin/payment_processor.rs @@ -122,7 +122,7 @@ async fn main() -> anyhow::Result<()> { fee_reserve, HashMap::default(), HashSet::default(), - 0, + 2, cashu::CurrencyUnit::Sat, ); From 841e35d70fc1ecc81b7fd12209914fe8e2b92727 Mon Sep 17 00:00:00 2001 From: C Date: Mon, 8 Sep 2025 10:55:41 -0300 Subject: [PATCH 135/321] Reorganize tests, add mint quote/payment coverage, and prevent over-issuing (#1048) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Add consistent ordering of sql migrations Also sort the prefix and not only the filenames * Reorganize tests, add mint quote/payment coverage, and prevent over-issuing Reorganizes the mint test suite into clear modules, adds comprehensive mint quote & payment scenarios, enhances the shared test macro, and hardens SQL logic to forbid issuing more than what’s been paid. These tests were added: * Add quote once; reject duplicates. * Register multiple payments and verify aggregated amount_paid. * Read parity between DB and in-TX views. * Reject duplicate payment_id in same and different transactions. * Reject over-issuing (same TX, different TX, with/without prior payments). --------- Co-authored-by: thesimplekid --- crates/cdk-common/src/database/mint/mod.rs | 3 - .../mint/{test_kvstore.rs => test/kvstore.rs} | 0 .../cdk-common/src/database/mint/test/mint.rs | 406 ++++++++++++++++++ .../database/mint/{test.rs => test/mod.rs} | 126 +++--- .../src/database/mint/test/proofs.rs | 97 +++++ crates/cdk-sql-common/src/mint/mod.rs | 39 +- 6 files changed, 601 insertions(+), 70 deletions(-) rename crates/cdk-common/src/database/mint/{test_kvstore.rs => test/kvstore.rs} (100%) create mode 100644 crates/cdk-common/src/database/mint/test/mint.rs rename crates/cdk-common/src/database/mint/{test.rs => test/mod.rs} (69%) create mode 100644 crates/cdk-common/src/database/mint/test/proofs.rs diff --git a/crates/cdk-common/src/database/mint/mod.rs b/crates/cdk-common/src/database/mint/mod.rs index 3451e6b50..3d68abc50 100644 --- a/crates/cdk-common/src/database/mint/mod.rs +++ b/crates/cdk-common/src/database/mint/mod.rs @@ -80,9 +80,6 @@ mod auth; #[cfg(feature = "test")] pub mod test; -#[cfg(test)] -mod test_kvstore; - #[cfg(feature = "auth")] pub use auth::{MintAuthDatabase, MintAuthTransaction}; diff --git a/crates/cdk-common/src/database/mint/test_kvstore.rs b/crates/cdk-common/src/database/mint/test/kvstore.rs similarity index 100% rename from crates/cdk-common/src/database/mint/test_kvstore.rs rename to crates/cdk-common/src/database/mint/test/kvstore.rs diff --git a/crates/cdk-common/src/database/mint/test/mint.rs b/crates/cdk-common/src/database/mint/test/mint.rs new file mode 100644 index 000000000..ee4641a15 --- /dev/null +++ b/crates/cdk-common/src/database/mint/test/mint.rs @@ -0,0 +1,406 @@ +//! Payments + +use crate::database::mint::test::unique_string; +use crate::database::mint::{Database, Error, KeysDatabase}; +use crate::mint::MintQuote; +use crate::payment::PaymentIdentifier; + +/// Add a mint quote +pub async fn add_mint_quote(db: DB) +where + DB: Database + KeysDatabase, +{ + let mint_quote = MintQuote::new( + None, + "".to_owned(), + cashu::CurrencyUnit::Sat, + None, + 0, + PaymentIdentifier::CustomId(unique_string()), + None, + 0.into(), + 0.into(), + cashu::PaymentMethod::Bolt12, + 0, + vec![], + vec![], + ); + + let mut tx = Database::begin_transaction(&db).await.unwrap(); + assert!(tx.add_mint_quote(mint_quote.clone()).await.is_ok()); + tx.commit().await.unwrap(); +} + +/// Dup mint quotes fails +pub async fn add_mint_quote_only_once(db: DB) +where + DB: Database + KeysDatabase, +{ + let mint_quote = MintQuote::new( + None, + "".to_owned(), + cashu::CurrencyUnit::Sat, + None, + 0, + PaymentIdentifier::CustomId(unique_string()), + None, + 0.into(), + 0.into(), + cashu::PaymentMethod::Bolt12, + 0, + vec![], + vec![], + ); + let mut tx = Database::begin_transaction(&db).await.unwrap(); + assert!(tx.add_mint_quote(mint_quote.clone()).await.is_ok()); + tx.commit().await.unwrap(); + + let mut tx = Database::begin_transaction(&db).await.unwrap(); + assert!(tx.add_mint_quote(mint_quote).await.is_err()); + tx.commit().await.unwrap(); +} + +/// Register payments +pub async fn register_payments(db: DB) +where + DB: Database + KeysDatabase, +{ + let mint_quote = MintQuote::new( + None, + "".to_owned(), + cashu::CurrencyUnit::Sat, + None, + 0, + PaymentIdentifier::CustomId(unique_string()), + None, + 0.into(), + 0.into(), + cashu::PaymentMethod::Bolt12, + 0, + vec![], + vec![], + ); + + let mut tx = Database::begin_transaction(&db).await.unwrap(); + assert!(tx.add_mint_quote(mint_quote.clone()).await.is_ok()); + + let p1 = unique_string(); + let p2 = unique_string(); + + let new_paid_amount = tx + .increment_mint_quote_amount_paid(&mint_quote.id, 100.into(), p1.clone()) + .await + .unwrap(); + + assert_eq!(new_paid_amount, 100.into()); + + let new_paid_amount = tx + .increment_mint_quote_amount_paid(&mint_quote.id, 250.into(), p2.clone()) + .await + .unwrap(); + + assert_eq!(new_paid_amount, 350.into()); + + tx.commit().await.unwrap(); + + let mint_quote_from_db = db + .get_mint_quote(&mint_quote.id) + .await + .unwrap() + .expect("mint_quote_from_db"); + assert_eq!(mint_quote_from_db.amount_paid(), 350.into()); + assert_eq!( + mint_quote_from_db + .payments + .iter() + .map(|x| (x.payment_id.clone(), x.amount)) + .collect::>(), + vec![(p1, 100.into()), (p2, 250.into())] + ); +} + +/// Read mint and payments from db and tx objects +pub async fn read_mint_from_db_and_tx(db: DB) +where + DB: Database + KeysDatabase, +{ + let mint_quote = MintQuote::new( + None, + "".to_owned(), + cashu::CurrencyUnit::Sat, + None, + 0, + PaymentIdentifier::CustomId(unique_string()), + None, + 0.into(), + 0.into(), + cashu::PaymentMethod::Bolt12, + 0, + vec![], + vec![], + ); + + let p1 = unique_string(); + let p2 = unique_string(); + + let mut tx = Database::begin_transaction(&db).await.unwrap(); + tx.add_mint_quote(mint_quote.clone()).await.unwrap(); + let new_paid_amount = tx + .increment_mint_quote_amount_paid(&mint_quote.id, 100.into(), p1.clone()) + .await + .unwrap(); + + assert_eq!(new_paid_amount, 100.into()); + + let new_paid_amount = tx + .increment_mint_quote_amount_paid(&mint_quote.id, 250.into(), p2.clone()) + .await + .unwrap(); + assert_eq!(new_paid_amount, 350.into()); + tx.commit().await.unwrap(); + + let mint_quote_from_db = db + .get_mint_quote(&mint_quote.id) + .await + .unwrap() + .expect("mint_quote_from_db"); + assert_eq!(mint_quote_from_db.amount_paid(), 350.into()); + assert_eq!( + mint_quote_from_db + .payments + .iter() + .map(|x| (x.payment_id.clone(), x.amount)) + .collect::>(), + vec![(p1, 100.into()), (p2, 250.into())] + ); + + let mut tx = Database::begin_transaction(&db).await.unwrap(); + let mint_quote_from_tx = tx + .get_mint_quote(&mint_quote.id) + .await + .unwrap() + .expect("mint_quote_from_tx"); + assert_eq!(mint_quote_from_db, mint_quote_from_tx); +} + +/// Reject duplicate payments in the same txs +pub async fn reject_duplicate_payments_same_tx(db: DB) +where + DB: Database + KeysDatabase, +{ + let mint_quote = MintQuote::new( + None, + "".to_owned(), + cashu::CurrencyUnit::Sat, + None, + 0, + PaymentIdentifier::CustomId(unique_string()), + None, + 0.into(), + 0.into(), + cashu::PaymentMethod::Bolt12, + 0, + vec![], + vec![], + ); + + let p1 = unique_string(); + + let mut tx = Database::begin_transaction(&db).await.unwrap(); + tx.add_mint_quote(mint_quote.clone()).await.unwrap(); + let amount_paid = tx + .increment_mint_quote_amount_paid(&mint_quote.id, 100.into(), p1.clone()) + .await + .unwrap(); + + assert!(tx + .increment_mint_quote_amount_paid(&mint_quote.id, 100.into(), p1) + .await + .is_err()); + tx.commit().await.unwrap(); + + let mint_quote_from_db = db + .get_mint_quote(&mint_quote.id) + .await + .unwrap() + .expect("mint_from_db"); + assert_eq!(mint_quote_from_db.amount_paid(), amount_paid); + assert_eq!(mint_quote_from_db.payments.len(), 1); +} + +/// Reject duplicate payments in different txs +pub async fn reject_duplicate_payments_diff_tx(db: DB) +where + DB: Database + KeysDatabase, +{ + let p1 = unique_string(); + + let mint_quote = MintQuote::new( + None, + "".to_owned(), + cashu::CurrencyUnit::Sat, + None, + 0, + PaymentIdentifier::CustomId(unique_string()), + None, + 0.into(), + 0.into(), + cashu::PaymentMethod::Bolt12, + 0, + vec![], + vec![], + ); + + let mut tx = Database::begin_transaction(&db).await.unwrap(); + tx.add_mint_quote(mint_quote.clone()).await.unwrap(); + let amount_paid = tx + .increment_mint_quote_amount_paid(&mint_quote.id, 100.into(), p1.clone()) + .await + .unwrap(); + tx.commit().await.unwrap(); + + let mut tx = Database::begin_transaction(&db).await.unwrap(); + assert!(tx + .increment_mint_quote_amount_paid(&mint_quote.id, 100.into(), p1) + .await + .is_err()); + tx.commit().await.unwrap(); // although in theory nothing has changed, let's try it out + + let mint_quote_from_db = db + .get_mint_quote(&mint_quote.id) + .await + .unwrap() + .expect("mint_from_db"); + assert_eq!(mint_quote_from_db.amount_paid(), amount_paid); + assert_eq!(mint_quote_from_db.payments.len(), 1); +} + +/// Reject over issue in same tx +pub async fn reject_over_issue_same_tx(db: DB) +where + DB: Database + KeysDatabase, +{ + let mint_quote = MintQuote::new( + None, + "".to_owned(), + cashu::CurrencyUnit::Sat, + None, + 0, + PaymentIdentifier::CustomId(unique_string()), + None, + 0.into(), + 0.into(), + cashu::PaymentMethod::Bolt12, + 0, + vec![], + vec![], + ); + + let mut tx = Database::begin_transaction(&db).await.unwrap(); + tx.add_mint_quote(mint_quote.clone()).await.unwrap(); + assert!(tx + .increment_mint_quote_amount_issued(&mint_quote.id, 100.into()) + .await + .is_err()); +} + +/// Reject over issue +pub async fn reject_over_issue_different_tx(db: DB) +where + DB: Database + KeysDatabase, +{ + let mint_quote = MintQuote::new( + None, + "".to_owned(), + cashu::CurrencyUnit::Sat, + None, + 0, + PaymentIdentifier::CustomId(unique_string()), + None, + 0.into(), + 0.into(), + cashu::PaymentMethod::Bolt12, + 0, + vec![], + vec![], + ); + + let mut tx = Database::begin_transaction(&db).await.unwrap(); + tx.add_mint_quote(mint_quote.clone()).await.unwrap(); + tx.commit().await.unwrap(); + + let mut tx = Database::begin_transaction(&db).await.unwrap(); + assert!(tx + .increment_mint_quote_amount_issued(&mint_quote.id, 100.into()) + .await + .is_err()); +} + +/// Reject over issue with payment +pub async fn reject_over_issue_with_payment(db: DB) +where + DB: Database + KeysDatabase, +{ + let mint_quote = MintQuote::new( + None, + "".to_owned(), + cashu::CurrencyUnit::Sat, + None, + 0, + PaymentIdentifier::CustomId(unique_string()), + None, + 0.into(), + 0.into(), + cashu::PaymentMethod::Bolt12, + 0, + vec![], + vec![], + ); + + let p1 = unique_string(); + let mut tx = Database::begin_transaction(&db).await.unwrap(); + tx.add_mint_quote(mint_quote.clone()).await.unwrap(); + tx.increment_mint_quote_amount_paid(&mint_quote.id, 100.into(), p1.clone()) + .await + .unwrap(); + assert!(tx + .increment_mint_quote_amount_issued(&mint_quote.id, 101.into()) + .await + .is_err()); +} + +/// Reject over issue with payment +pub async fn reject_over_issue_with_payment_different_tx(db: DB) +where + DB: Database + KeysDatabase, +{ + let mint_quote = MintQuote::new( + None, + "".to_owned(), + cashu::CurrencyUnit::Sat, + None, + 0, + PaymentIdentifier::CustomId(unique_string()), + None, + 0.into(), + 0.into(), + cashu::PaymentMethod::Bolt12, + 0, + vec![], + vec![], + ); + + let p1 = unique_string(); + let mut tx = Database::begin_transaction(&db).await.unwrap(); + tx.add_mint_quote(mint_quote.clone()).await.unwrap(); + tx.increment_mint_quote_amount_paid(&mint_quote.id, 100.into(), p1.clone()) + .await + .unwrap(); + tx.commit().await.unwrap(); + + let mut tx = Database::begin_transaction(&db).await.unwrap(); + assert!(tx + .increment_mint_quote_amount_issued(&mint_quote.id, 101.into()) + .await + .is_err()); +} diff --git a/crates/cdk-common/src/database/mint/test.rs b/crates/cdk-common/src/database/mint/test/mod.rs similarity index 69% rename from crates/cdk-common/src/database/mint/test.rs rename to crates/cdk-common/src/database/mint/test/mod.rs index 2d681a6b4..9852ab2df 100644 --- a/crates/cdk-common/src/database/mint/test.rs +++ b/crates/cdk-common/src/database/mint/test/mod.rs @@ -3,6 +3,8 @@ //! This set is generic and checks the default and expected behaviour for a mint database //! implementation use std::str::FromStr; +use std::sync::atomic::{AtomicU64, Ordering}; +use std::time::{SystemTime, UNIX_EPOCH}; // For derivation path parsing use bitcoin::bip32::DerivationPath; @@ -13,6 +15,13 @@ use super::*; use crate::database::MintKVStoreDatabase; use crate::mint::MintKeySetInfo; +mod kvstore; +mod mint; +mod proofs; + +pub use self::mint::*; +pub use self::proofs::*; + #[inline] async fn setup_keyset(db: &DB) -> Id where @@ -81,52 +90,6 @@ where tx.commit().await.unwrap(); } -/// Test the basic storing and retrieving proofs from the database. Probably the database would use -/// binary/`Vec` to store data, that's why this test would quickly identify issues before running -/// other tests -pub async fn add_and_find_proofs(db: DB) -where - DB: Database + KeysDatabase, -{ - let keyset_id = setup_keyset(&db).await; - - let quote_id = QuoteId::new_uuid(); - - let proofs = vec![ - Proof { - amount: Amount::from(100), - keyset_id, - secret: Secret::generate(), - c: SecretKey::generate().public_key(), - witness: None, - dleq: None, - }, - Proof { - amount: Amount::from(200), - keyset_id, - secret: Secret::generate(), - c: SecretKey::generate().public_key(), - witness: None, - dleq: None, - }, - ]; - - // Add proofs to database - let mut tx = Database::begin_transaction(&db).await.unwrap(); - tx.add_proofs(proofs.clone(), Some(quote_id.clone())) - .await - .unwrap(); - assert!(tx.commit().await.is_ok()); - - let proofs_from_db = db.get_proofs_by_ys(&[proofs[0].c, proofs[1].c]).await; - assert!(proofs_from_db.is_ok()); - assert_eq!(proofs_from_db.unwrap().len(), 2); - - let proofs_from_db = db.get_proof_ys_by_quote_id("e_id).await; - assert!(proofs_from_db.is_ok()); - assert_eq!(proofs_from_db.unwrap().len(), 2); -} - /// Test KV store functionality including write, read, list, update, and remove operations pub async fn kvstore_functionality(db: DB) where @@ -213,18 +176,73 @@ where } } +static COUNTER: AtomicU64 = AtomicU64::new(0); + +/// Returns a unique, random-looking Base62 string (no external crates). +/// Not cryptographically secure, but great for ids, keys, temp names, etc. +fn unique_string() -> String { + // 1) high-res timestamp (nanos since epoch) + let now = SystemTime::now() + .duration_since(UNIX_EPOCH) + .unwrap() + .as_nanos(); + + // 2) per-process monotonic counter to avoid collisions in the same instant + let n = COUNTER.fetch_add(1, Ordering::Relaxed) as u128; + + // 3) process id to reduce collision chance across processes + let pid = std::process::id() as u128; + + // Mix the components (simple XOR/shift mix; good enough for "random-looking") + let mixed = now ^ (pid << 64) ^ (n << 32); + + base62_encode(mixed) +} + +fn base62_encode(mut x: u128) -> String { + const ALPHABET: &[u8; 62] = b"0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"; + if x == 0 { + return "0".to_string(); + } + let mut buf = [0u8; 26]; // enough for base62(u128) + let mut i = buf.len(); + while x > 0 { + let rem = (x % 62) as usize; + x /= 62; + i -= 1; + buf[i] = ALPHABET[rem]; + } + String::from_utf8_lossy(&buf[i..]).into_owned() +} + /// Unit test that is expected to be passed for a correct database implementation #[macro_export] macro_rules! mint_db_test { ($make_db_fn:ident) => { - mint_db_test!(state_transition, $make_db_fn); - mint_db_test!(add_and_find_proofs, $make_db_fn); - mint_db_test!(kvstore_functionality, $make_db_fn); + mint_db_test!( + $make_db_fn, + state_transition, + add_and_find_proofs, + add_duplicate_proofs, + kvstore_functionality, + add_mint_quote, + add_mint_quote_only_once, + register_payments, + read_mint_from_db_and_tx, + reject_duplicate_payments_same_tx, + reject_duplicate_payments_diff_tx, + reject_over_issue_same_tx, + reject_over_issue_different_tx, + reject_over_issue_with_payment, + reject_over_issue_with_payment_different_tx + ); }; - ($name:ident, $make_db_fn:ident) => { - #[tokio::test] - async fn $name() { - cdk_common::database::mint::test::$name($make_db_fn().await).await; - } + ($make_db_fn:ident, $($name:ident),+ $(,)?) => { + $( + #[tokio::test] + async fn $name() { + cdk_common::database::mint::test::$name($make_db_fn().await).await; + } + )+ }; } diff --git a/crates/cdk-common/src/database/mint/test/proofs.rs b/crates/cdk-common/src/database/mint/test/proofs.rs new file mode 100644 index 000000000..d960e5267 --- /dev/null +++ b/crates/cdk-common/src/database/mint/test/proofs.rs @@ -0,0 +1,97 @@ +//! Proofs tests + +use cashu::secret::Secret; +use cashu::{Amount, SecretKey}; + +use crate::database::mint::test::setup_keyset; +use crate::database::mint::{Database, Error, KeysDatabase, Proof, QuoteId}; + +/// Test the basic storing and retrieving proofs from the database. Probably the database would use +/// binary/`Vec` to store data, that's why this test would quickly identify issues before running +/// other tests +pub async fn add_and_find_proofs(db: DB) +where + DB: Database + KeysDatabase, +{ + let keyset_id = setup_keyset(&db).await; + + let quote_id = QuoteId::new_uuid(); + + let proofs = vec![ + Proof { + amount: Amount::from(100), + keyset_id, + secret: Secret::generate(), + c: SecretKey::generate().public_key(), + witness: None, + dleq: None, + }, + Proof { + amount: Amount::from(200), + keyset_id, + secret: Secret::generate(), + c: SecretKey::generate().public_key(), + witness: None, + dleq: None, + }, + ]; + + // Add proofs to database + let mut tx = Database::begin_transaction(&db).await.unwrap(); + tx.add_proofs(proofs.clone(), Some(quote_id.clone())) + .await + .unwrap(); + assert!(tx.commit().await.is_ok()); + + let proofs_from_db = db.get_proofs_by_ys(&[proofs[0].c, proofs[1].c]).await; + assert!(proofs_from_db.is_ok()); + assert_eq!(proofs_from_db.unwrap().len(), 2); + + let proofs_from_db = db.get_proof_ys_by_quote_id("e_id).await; + assert!(proofs_from_db.is_ok()); + assert_eq!(proofs_from_db.unwrap().len(), 2); +} + +/// Test to add duplicate proofs +pub async fn add_duplicate_proofs(db: DB) +where + DB: Database + KeysDatabase, +{ + let keyset_id = setup_keyset(&db).await; + + let quote_id = QuoteId::new_uuid(); + + let proofs = vec![ + Proof { + amount: Amount::from(100), + keyset_id, + secret: Secret::generate(), + c: SecretKey::generate().public_key(), + witness: None, + dleq: None, + }, + Proof { + amount: Amount::from(200), + keyset_id, + secret: Secret::generate(), + c: SecretKey::generate().public_key(), + witness: None, + dleq: None, + }, + ]; + + // Add proofs to database + let mut tx = Database::begin_transaction(&db).await.unwrap(); + tx.add_proofs(proofs.clone(), Some(quote_id.clone())) + .await + .unwrap(); + assert!(tx.commit().await.is_ok()); + + let mut tx = Database::begin_transaction(&db).await.unwrap(); + let result = tx.add_proofs(proofs.clone(), Some(quote_id.clone())).await; + + assert!( + matches!(result.unwrap_err(), Error::Duplicate), + "Duplicate entry" + ); +} diff --git a/crates/cdk-sql-common/src/mint/mod.rs b/crates/cdk-sql-common/src/mint/mod.rs index 9e83e8c35..ca750e6fb 100644 --- a/crates/cdk-sql-common/src/mint/mod.rs +++ b/crates/cdk-sql-common/src/mint/mod.rs @@ -654,9 +654,9 @@ where amount_issued: Amount, ) -> Result { // Get current amount_issued from quote - let current_amount = query( + let current_amounts = query( r#" - SELECT amount_issued + SELECT amount_issued, amount_paid FROM mint_quote WHERE id = :quote_id FOR UPDATE @@ -667,19 +667,32 @@ where .await .inspect_err(|err| { tracing::error!("SQLite could not get mint quote amount_issued: {}", err); - })?; + })? + .ok_or(Error::QuoteNotFound)?; - let current_amount_issued = if let Some(current_amount) = current_amount { - let amount: u64 = column_as_number!(current_amount[0].clone()); - Amount::from(amount) - } else { - Amount::ZERO - }; + let new_amount_issued = { + // Make sure the db protects issuing not paid quotes + unpack_into!( + let (current_amount_issued, current_amount_paid) = current_amounts + ); - // Calculate new amount_issued with overflow check - let new_amount_issued = current_amount_issued - .checked_add(amount_issued) - .ok_or_else(|| database::Error::AmountOverflow)?; + let current_amount_issued: u64 = column_as_number!(current_amount_issued); + let current_amount_paid: u64 = column_as_number!(current_amount_paid); + + let current_amount_issued = Amount::from(current_amount_issued); + let current_amount_paid = Amount::from(current_amount_paid); + + // Calculate new amount_issued with overflow check + let new_amount_issued = current_amount_issued + .checked_add(amount_issued) + .ok_or_else(|| database::Error::AmountOverflow)?; + + current_amount_paid + .checked_sub(new_amount_issued) + .ok_or(Error::Internal("Over-issued not allowed".to_owned()))?; + + new_amount_issued + }; // Update the amount_issued query( From 166b9028333d68d16a1257837ab97c481c54278d Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Mon, 8 Sep 2025 21:20:52 +0100 Subject: [PATCH 136/321] feat: bolt12 ws (#1052) --- crates/cdk-mintd/src/lib.rs | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/crates/cdk-mintd/src/lib.rs b/crates/cdk-mintd/src/lib.rs index ec6df6f8f..ff13f63bc 100644 --- a/crates/cdk-mintd/src/lib.rs +++ b/crates/cdk-mintd/src/lib.rs @@ -609,6 +609,9 @@ async fn configure_backend_for_unit( Arc::clone(&backend), ) .await?; + + let nut17_supported = SupportedMethods::default_bolt12(unit.clone()); + mint_builder = mint_builder.with_supported_websockets(nut17_supported); } } @@ -630,7 +633,8 @@ async fn configure_backend_for_unit( feature = "lnbits", feature = "lnd", feature = "fakewallet", - feature = "grpc-processor" + feature = "grpc-processor", + feature = "ldk-node" ))] { let nut17_supported = SupportedMethods::default_bolt11(unit); From 62de0c992547c0259ddcb76eb8b6232929021338 Mon Sep 17 00:00:00 2001 From: C Date: Mon, 8 Sep 2025 17:21:13 -0300 Subject: [PATCH 137/321] Close websocket connections sooner (#1050) * Close websocket connections sooner * Handle Ping, Binary and Close --- crates/cdk-axum/src/ws/mod.rs | 52 ++++++++++++++++++++++++++++++----- 1 file changed, 45 insertions(+), 7 deletions(-) diff --git a/crates/cdk-axum/src/ws/mod.rs b/crates/cdk-axum/src/ws/mod.rs index b8496f8e5..9ea30dc55 100644 --- a/crates/cdk-axum/src/ws/mod.rs +++ b/crates/cdk-axum/src/ws/mod.rs @@ -1,6 +1,6 @@ use std::collections::HashMap; -use axum::extract::ws::{Message, WebSocket}; +use axum::extract::ws::{CloseFrame, Message, WebSocket}; use cdk::mint::QuoteId; use cdk::nuts::nut17::NotificationPayload; use cdk::pub_sub::SubId; @@ -74,12 +74,48 @@ pub async fn main_websocket(mut socket: WebSocket, state: MintState) { } }; - if let Err(err)= socket.send(Message::Text(message.into())).await { - tracing::error!("Could not send websocket message: {}", err); - break; - } + if let Err(err)= socket.send(Message::Text(message.into())).await { + tracing::error!("Could not send websocket message: {}", err); + break; + } } - Some(Ok(Message::Text(text))) = socket.next() => { + + Some(from_ws) = socket.next() => { + let text = match from_ws { + Ok(Message::Text(text)) => text.to_string(), + Ok(Message::Binary(bin)) => String::from_utf8_lossy(&bin).to_string(), + Ok(Message::Ping(payload)) => { + // Reply with Pong with same payload + if let Err(e) = socket.send(Message::Pong(payload)).await { + tracing::error!("failed to send pong: {e}"); + break; + } + continue; + }, + Ok(Message::Pong(_payload)) => { + tracing::error!("Unexpected pong"); + continue; + }, + Ok(Message::Close(frame)) => { + if let Some(CloseFrame { code, reason }) = frame { + tracing::info!("ws-close: code={code:?} reason='{reason}'"); + } else { + tracing::info!("ws-close: no frame"); + } + + let _ = socket.send(Message::Close(Some(CloseFrame { + code: axum::extract::ws::close_code::NORMAL, + reason: "bye!".into(), + }))).await; + break; + } + Err(err) => { + tracing::error!("ws-error: {err}"); + break; + } + }; + + let request = match serde_json::from_str::(&text) { Ok(request) => request, Err(err) => { @@ -105,7 +141,9 @@ pub async fn main_websocket(mut socket: WebSocket, state: MintState) { } } else => { - + // Unexpected, we should exit the loop + tracing::warn!("Unexpected event, closing ws"); + break; } } } From b1026fb9bb2b466921897fb8873035b9f5925212 Mon Sep 17 00:00:00 2001 From: lollerfirst <43107113+lollerfirst@users.noreply.github.com> Date: Tue, 9 Sep 2025 11:40:38 +0200 Subject: [PATCH 138/321] fix: None `host_matcher` applies the proxy to all hosts (#1054) * fix: None `host_matcher` applies the proxy to all hosts --- .../src/wallet/mint_connector/transport.rs | 42 +++++++++---------- 1 file changed, 20 insertions(+), 22 deletions(-) diff --git a/crates/cdk/src/wallet/mint_connector/transport.rs b/crates/cdk/src/wallet/mint_connector/transport.rs index abd3b55e1..5a4812902 100644 --- a/crates/cdk/src/wallet/mint_connector/transport.rs +++ b/crates/cdk/src/wallet/mint_connector/transport.rs @@ -78,29 +78,27 @@ impl Transport for Async { host_matcher: Option<&str>, accept_invalid_certs: bool, ) -> Result<(), Error> { - let regex = host_matcher - .map(regex::Regex::new) - .transpose() - .map_err(|e| Error::Custom(e.to_string()))?; - self.inner = reqwest::Client::builder() - .proxy(reqwest::Proxy::custom(move |url| { - if let Some(matcher) = regex.as_ref() { - if let Some(host) = url.host_str() { - if matcher.is_match(host) { - return Some(proxy.clone()); - } - } - } - None - })) - .danger_accept_invalid_certs(accept_invalid_certs) // Allow self-signed certs + let builder = reqwest::Client::builder().danger_accept_invalid_certs(accept_invalid_certs); + + let builder = match host_matcher { + Some(pattern) => { + // When a matcher is provided, only apply the proxy to matched hosts + let regex = regex::Regex::new(pattern).map_err(|e| Error::Custom(e.to_string()))?; + builder.proxy(reqwest::Proxy::custom(move |url| { + url.host_str() + .filter(|host| regex.is_match(host)) + .map(|_| proxy.clone()) + })) + } + // Apply proxy to all requests when no matcher is provided + None => { + builder.proxy(reqwest::Proxy::all(proxy).map_err(|e| Error::Custom(e.to_string()))?) + } + }; + + self.inner = builder .build() - .map_err(|e| { - Error::HttpError( - e.status().map(|status_code| status_code.as_u16()), - e.to_string(), - ) - })?; + .map_err(|e| Error::HttpError(e.status().map(|s| s.as_u16()), e.to_string()))?; Ok(()) } From c94979a357dbbcada153b5b63363590e4c81afdc Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Tue, 9 Sep 2025 11:26:24 +0100 Subject: [PATCH 139/321] fix: used check math (#1051) --- crates/cashu/src/amount.rs | 33 ++++++++++++++++++++++++--------- crates/cdk/src/wallet/swap.rs | 31 +++++++++++++++++++++---------- 2 files changed, 45 insertions(+), 19 deletions(-) diff --git a/crates/cashu/src/amount.rs b/crates/cashu/src/amount.rs index 33bf82bf6..7fc0fa813 100644 --- a/crates/cashu/src/amount.rs +++ b/crates/cashu/src/amount.rs @@ -132,12 +132,16 @@ impl Amount { /// Splits amount into powers of two while accounting for the swap fee pub fn split_with_fee(&self, fee_ppk: u64) -> Result, Error> { let without_fee_amounts = self.split(); - let fee_ppk = fee_ppk * without_fee_amounts.len() as u64; + let fee_ppk = fee_ppk + .checked_mul(without_fee_amounts.len() as u64) + .ok_or(Error::AmountOverflow)?; let fee = Amount::from(fee_ppk.div_ceil(1000)); let new_amount = self.checked_add(fee).ok_or(Error::AmountOverflow)?; let split = new_amount.split(); - let split_fee_ppk = split.len() as u64 * fee_ppk; + let split_fee_ppk = (split.len() as u64) + .checked_mul(fee_ppk) + .ok_or(Error::AmountOverflow)?; let split_fee = Amount::from(split_fee_ppk.div_ceil(1000)); if let Some(net_amount) = new_amount.checked_sub(split_fee) { @@ -258,13 +262,16 @@ impl std::ops::Add for Amount { type Output = Amount; fn add(self, rhs: Amount) -> Self::Output { - Amount(self.0.checked_add(rhs.0).expect("Addition error")) + self.checked_add(rhs) + .expect("Addition overflow: the sum of the amounts exceeds the maximum value") } } impl std::ops::AddAssign for Amount { fn add_assign(&mut self, rhs: Self) { - self.0 = self.0.checked_add(rhs.0).expect("Addition error"); + *self = self + .checked_add(rhs) + .expect("AddAssign overflow: the sum of the amounts exceeds the maximum value"); } } @@ -272,13 +279,16 @@ impl std::ops::Sub for Amount { type Output = Amount; fn sub(self, rhs: Amount) -> Self::Output { - Amount(self.0 - rhs.0) + self.checked_sub(rhs) + .expect("Subtraction underflow: cannot subtract a larger amount from a smaller amount") } } impl std::ops::SubAssign for Amount { fn sub_assign(&mut self, other: Self) { - self.0 -= other.0; + *self = self + .checked_sub(other) + .expect("SubAssign underflow: cannot subtract a larger amount from a smaller amount"); } } @@ -286,7 +296,8 @@ impl std::ops::Mul for Amount { type Output = Self; fn mul(self, other: Self) -> Self::Output { - Amount(self.0 * other.0) + self.checked_mul(other) + .expect("Multiplication overflow: the product of the amounts exceeds the maximum value") } } @@ -294,7 +305,8 @@ impl std::ops::Div for Amount { type Output = Self; fn div(self, other: Self) -> Self::Output { - Amount(self.0 / other.0) + self.checked_div(other) + .expect("Division error: cannot divide by zero or overflow occurred") } } @@ -347,7 +359,10 @@ where match (current_unit, target_unit) { (CurrencyUnit::Sat, CurrencyUnit::Sat) => Ok(amount.into()), (CurrencyUnit::Msat, CurrencyUnit::Msat) => Ok(amount.into()), - (CurrencyUnit::Sat, CurrencyUnit::Msat) => Ok((amount * MSAT_IN_SAT).into()), + (CurrencyUnit::Sat, CurrencyUnit::Msat) => amount + .checked_mul(MSAT_IN_SAT) + .map(Amount::from) + .ok_or(Error::AmountOverflow), (CurrencyUnit::Msat, CurrencyUnit::Sat) => Ok((amount / MSAT_IN_SAT).into()), (CurrencyUnit::Usd, CurrencyUnit::Usd) => Ok(amount.into()), (CurrencyUnit::Eur, CurrencyUnit::Eur) => Ok(amount.into()), diff --git a/crates/cdk/src/wallet/swap.rs b/crates/cdk/src/wallet/swap.rs index fc70dafa4..8adfef6cc 100644 --- a/crates/cdk/src/wallet/swap.rs +++ b/crates/cdk/src/wallet/swap.rs @@ -154,14 +154,14 @@ impl Wallet { ) .await?; - let (available_proofs, proofs_sum) = available_proofs.into_iter().map(|p| p.proof).fold( - (Vec::new(), Amount::ZERO), - |(mut acc1, mut acc2), p| { - acc2 += p.amount; + let (available_proofs, proofs_sum) = available_proofs + .into_iter() + .map(|p| p.proof) + .try_fold((Vec::new(), Amount::ZERO), |(mut acc1, acc2), p| { + let new_sum = acc2.checked_add(p.amount).ok_or(Error::AmountOverflow)?; acc1.push(p); - (acc1, acc2) - }, - ); + Ok::<_, Error>((acc1, new_sum)) + })?; ensure_cdk!(proofs_sum >= amount, Error::InsufficientFunds); @@ -215,7 +215,14 @@ impl Wallet { let fee = self.get_proofs_fee(&proofs).await?; - let change_amount: Amount = proofs_total - amount.unwrap_or(Amount::ZERO) - fee; + let total_to_subtract = amount + .unwrap_or(Amount::ZERO) + .checked_add(fee) + .ok_or(Error::AmountOverflow)?; + + let change_amount: Amount = proofs_total + .checked_sub(total_to_subtract) + .ok_or(Error::InsufficientFunds)?; let (send_amount, change_amount) = match include_fees { true => { @@ -230,8 +237,12 @@ impl Wallet { .await?; ( - amount.map(|a| a + fee_to_redeem), - change_amount - fee_to_redeem, + amount + .map(|a| a.checked_add(fee_to_redeem).ok_or(Error::AmountOverflow)) + .transpose()?, + change_amount + .checked_sub(fee_to_redeem) + .ok_or(Error::InsufficientFunds)?, ) } false => (amount, change_amount), From 75a3e6d2c7f3366dcadb92083a2b59a6d905756e Mon Sep 17 00:00:00 2001 From: asmo Date: Tue, 9 Sep 2025 14:26:03 +0200 Subject: [PATCH 140/321] Prometheus crate (#883) * feat: introduce `cdk-prometheus` crate with Prometheus server and CDK-specific metrics support --- .github/workflows/ci.yml | 28 +- Cargo.toml | 3 + Dockerfile | 2 +- crates/cdk-axum/Cargo.toml | 3 +- crates/cdk-axum/src/lib.rs | 7 + crates/cdk-axum/src/metrics.rs | 41 + crates/cdk-common/Cargo.toml | 2 + crates/cdk-common/src/payment.rs | 188 ++ crates/cdk-integration-tests/Cargo.toml | 2 +- .../src/bin/start_regtest_mints.rs | 1 + crates/cdk-integration-tests/src/shared.rs | 3 + crates/cdk-mintd/Cargo.toml | 11 +- crates/cdk-mintd/example.config.toml | 19 +- crates/cdk-mintd/src/config.rs | 10 + crates/cdk-mintd/src/env_vars/mod.rs | 9 + crates/cdk-mintd/src/env_vars/prometheus.rs | 31 + crates/cdk-mintd/src/lib.rs | 97 +- crates/cdk-prometheus/Cargo.toml | 47 + crates/cdk-prometheus/README.md | 189 ++ crates/cdk-prometheus/src/error.rs | 32 + crates/cdk-prometheus/src/lib.rs | 84 + crates/cdk-prometheus/src/metrics.rs | 427 ++++ crates/cdk-prometheus/src/process.rs | 107 + crates/cdk-prometheus/src/server.rs | 317 +++ crates/cdk-sql-common/Cargo.toml | 3 +- crates/cdk-sql-common/src/mint/mod.rs | 235 +- crates/cdk-sql-common/src/pool.rs | 38 +- crates/cdk-sqlite/Cargo.toml | 3 +- crates/cdk/Cargo.toml | 4 +- crates/cdk/src/mint/builder.rs | 1 - crates/cdk/src/mint/issue/mod.rs | 424 ++-- crates/cdk/src/mint/melt.rs | 187 +- crates/cdk/src/mint/mod.rs | 175 +- crates/cdk/src/mint/swap.rs | 63 +- docker-compose.yaml | 53 +- misc/provisioning/dashboards/dashboard.json | 1983 +++++++++++++++++ misc/provisioning/dashboards/dashboard.yaml | 8 + misc/provisioning/datasources/datasource.yml | 8 + misc/provisioning/prometheus.yml | 8 + 39 files changed, 4498 insertions(+), 355 deletions(-) create mode 100644 crates/cdk-axum/src/metrics.rs create mode 100644 crates/cdk-mintd/src/env_vars/prometheus.rs create mode 100644 crates/cdk-prometheus/Cargo.toml create mode 100644 crates/cdk-prometheus/README.md create mode 100644 crates/cdk-prometheus/src/error.rs create mode 100644 crates/cdk-prometheus/src/lib.rs create mode 100644 crates/cdk-prometheus/src/metrics.rs create mode 100644 crates/cdk-prometheus/src/process.rs create mode 100644 crates/cdk-prometheus/src/server.rs create mode 100644 misc/provisioning/dashboards/dashboard.json create mode 100644 misc/provisioning/dashboards/dashboard.yaml create mode 100644 misc/provisioning/datasources/datasource.yml create mode 100644 misc/provisioning/prometheus.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ddba0daf0..19d1ae2c1 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -36,7 +36,7 @@ jobs: ' - name: typos run: nix develop -i -L .#nightly --command typos - + examples: name: "Run examples" runs-on: ubuntu-latest @@ -167,7 +167,7 @@ jobs: [ -p cdk-integration-tests, ] - database: + database: [ SQLITE, POSTGRES @@ -195,7 +195,7 @@ jobs: shared-key: "stable" - name: Test run: nix develop -i -L .#stable --command just itest ${{ matrix.database }} - + fake-mint-itest: name: "Integration fake mint tests" runs-on: ubuntu-latest @@ -207,7 +207,7 @@ jobs: [ -p cdk-integration-tests, ] - database: + database: [ SQLITE, ] @@ -236,7 +236,7 @@ jobs: run: nix develop -i -L .#stable --command cargo clippy -- -D warnings - name: Test fake auth mint run: nix develop -i -L .#stable --command just fake-mint-itest ${{ matrix.database }} - + pure-itest: name: "Integration fake wallet tests" runs-on: ubuntu-latest @@ -244,7 +244,7 @@ jobs: needs: [pre-commit-checks, clippy] strategy: matrix: - database: + database: [ memory, sqlite, @@ -256,7 +256,7 @@ jobs: - name: Free Disk Space (Ubuntu) uses: jlumbroso/free-disk-space@main with: - tool-cache: true + tool-cache: true android: true dotnet: true haskell: true @@ -286,7 +286,7 @@ jobs: needs: [pre-commit-checks, clippy, pure-itest, fake-mint-itest, regtest-itest] strategy: matrix: - ln: + ln: [ FAKEWALLET, CLN, @@ -298,7 +298,7 @@ jobs: - name: Free Disk Space (Ubuntu) uses: jlumbroso/free-disk-space@main with: - tool-cache: true + tool-cache: true android: true dotnet: true haskell: true @@ -357,7 +357,7 @@ jobs: - name: Build run: nix develop -i -L .#msrv --command cargo build ${{ matrix.build-args }} - + check-wasm: name: Check WASM runs-on: ubuntu-latest @@ -389,7 +389,7 @@ jobs: - name: Build cdk and binding run: nix develop -i -L ".#${{ matrix.rust }}" --command cargo build ${{ matrix.build-args }} --target ${{ matrix.target }} - + check-wasm-msrv: name: Check WASM runs-on: ubuntu-latest @@ -428,7 +428,7 @@ jobs: needs: [pre-commit-checks, clippy, pure-itest, fake-mint-itest] strategy: matrix: - database: + database: [ SQLITE, ] @@ -456,7 +456,7 @@ jobs: - name: Stop and clean up Docker Compose run: | docker compose -f misc/keycloak/docker-compose-recover.yml down - + doc-tests: name: "Documentation Tests" runs-on: ubuntu-latest @@ -475,7 +475,7 @@ jobs: shared-key: "stable" - name: Run doc tests run: nix develop -i -L .#stable --command cargo test --doc - + strict-docs: name: "Strict Documentation Check" runs-on: ubuntu-latest diff --git a/Cargo.toml b/Cargo.toml index e2142eb0c..452bac843 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -60,6 +60,7 @@ cdk-sqlite = { path = "./crates/cdk-sqlite", default-features = true, version = cdk-postgres = { path = "./crates/cdk-postgres", default-features = true, version = "=0.12.0" } cdk-signatory = { path = "./crates/cdk-signatory", version = "=0.12.0", default-features = false } cdk-mintd = { path = "./crates/cdk-mintd", version = "=0.12.0", default-features = false } +cdk-prometheus = { path = "./crates/cdk-prometheus", version = "=0.12.0", default-features = false } clap = { version = "4.5.31", features = ["derive"] } ciborium = { version = "0.2.2", default-features = false, features = ["std"] } cbor-diag = "0.1.12" @@ -108,6 +109,8 @@ tonic-build = "0.13.1" strum = "0.27.1" strum_macros = "0.27.1" rustls = { version = "0.23.27", default-features = false, features = ["ring"] } +prometheus = { version = "0.13.4", features = ["process"], default-features = false } + diff --git a/Dockerfile b/Dockerfile index 9d37caf1c..b43591692 100644 --- a/Dockerfile +++ b/Dockerfile @@ -10,7 +10,7 @@ COPY Cargo.toml ./Cargo.toml COPY crates ./crates # Start the Nix daemon and develop the environment -RUN nix develop --extra-experimental-features nix-command --extra-experimental-features flakes --command cargo build --release --bin cdk-mintd --features redis +RUN nix develop --extra-experimental-features nix-command --extra-experimental-features flakes --command cargo build --release --bin cdk-mintd --features redis --features prometheus # Create a runtime stage FROM debian:trixie-slim diff --git a/crates/cdk-axum/Cargo.toml b/crates/cdk-axum/Cargo.toml index 3bebf0bde..7ef7e1454 100644 --- a/crates/cdk-axum/Cargo.toml +++ b/crates/cdk-axum/Cargo.toml @@ -15,7 +15,7 @@ default = ["auth"] redis = ["dep:redis"] swagger = ["cdk/swagger", "dep:utoipa"] auth = ["cdk/auth"] - +prometheus = ["dep:cdk-prometheus"] [dependencies] anyhow.workspace = true async-trait.workspace = true @@ -27,6 +27,7 @@ tokio.workspace = true tracing.workspace = true utoipa = { workspace = true, optional = true } futures.workspace = true +cdk-prometheus = { workspace = true , optional = true} moka = { version = "0.12.10", features = ["future"] } serde_json.workspace = true paste = "1.0.15" diff --git a/crates/cdk-axum/src/lib.rs b/crates/cdk-axum/src/lib.rs index 182f4f785..3d72986d9 100644 --- a/crates/cdk-axum/src/lib.rs +++ b/crates/cdk-axum/src/lib.rs @@ -17,6 +17,8 @@ use cache::HttpCache; use cdk::mint::Mint; use router_handlers::*; +mod metrics; + #[cfg(feature = "auth")] mod auth; mod bolt12_router; @@ -322,6 +324,11 @@ pub async fn create_mint_router_with_custom_cache( mint_router }; + #[cfg(feature = "prometheus")] + let mint_router = mint_router.layer(axum::middleware::from_fn_with_state( + state.clone(), + metrics::global_metrics_middleware, + )); let mint_router = mint_router .layer(from_fn(cors_middleware)) .with_state(state); diff --git a/crates/cdk-axum/src/metrics.rs b/crates/cdk-axum/src/metrics.rs new file mode 100644 index 000000000..81156d3b4 --- /dev/null +++ b/crates/cdk-axum/src/metrics.rs @@ -0,0 +1,41 @@ +#[cfg(feature = "prometheus")] +use std::time::Instant; + +#[cfg(feature = "prometheus")] +use axum::body::Body; +#[cfg(feature = "prometheus")] +use axum::extract::MatchedPath; +#[cfg(feature = "prometheus")] +use axum::http::Request; +#[cfg(feature = "prometheus")] +use axum::middleware::Next; +#[cfg(feature = "prometheus")] +use axum::response::Response; +#[cfg(feature = "prometheus")] +use cdk_prometheus::global; + +/// Global metrics middleware that uses the singleton instance. +/// This version doesn't require access to MintState and can be used in any Axum application. +#[cfg(feature = "prometheus")] +pub async fn global_metrics_middleware( + matched_path: Option, + req: Request, + next: Next, +) -> Response { + let start_time = Instant::now(); + + let response = next.run(req).await; + + let endpoint_path = matched_path + .map(|mp| mp.as_str().to_string()) + .unwrap_or_default(); + + let status_code = response.status().as_u16().to_string(); + let request_duration = start_time.elapsed().as_secs_f64(); + + // Always use global metrics + global::record_http_request(&endpoint_path, &status_code); + global::record_http_request_duration(request_duration, &endpoint_path); + + response +} diff --git a/crates/cdk-common/Cargo.toml b/crates/cdk-common/Cargo.toml index 5afe10609..d19e851a0 100644 --- a/crates/cdk-common/Cargo.toml +++ b/crates/cdk-common/Cargo.toml @@ -18,6 +18,7 @@ bench = [] wallet = ["cashu/wallet"] mint = ["cashu/mint", "dep:uuid"] auth = ["cashu/auth"] +prometheus = ["cdk-prometheus/default"] [dependencies] async-trait.workspace = true @@ -30,6 +31,7 @@ lightning-invoice.workspace = true lightning.workspace = true thiserror.workspace = true tracing.workspace = true +cdk-prometheus = { workspace = true, optional = true} url.workspace = true uuid = { workspace = true, optional = true } utoipa = { workspace = true, optional = true } diff --git a/crates/cdk-common/src/payment.rs b/crates/cdk-common/src/payment.rs index 1bcabfcda..15f18427e 100644 --- a/crates/cdk-common/src/payment.rs +++ b/crates/cdk-common/src/payment.rs @@ -6,6 +6,8 @@ use std::pin::Pin; use async_trait::async_trait; use cashu::util::hex; use cashu::{Bolt11Invoice, MeltOptions}; +#[cfg(feature = "prometheus")] +use cdk_prometheus::METRICS; use futures::Stream; use lightning::offers::offer::Offer; use lightning_invoice::ParseOrSemanticError; @@ -411,3 +413,189 @@ impl TryFrom for Bolt11Settings { serde_json::from_value(value).map_err(|err| err.into()) } } + +/// Metrics wrapper for MintPayment implementations +/// +/// This wrapper implements the Decorator pattern to collect metrics on all +/// MintPayment trait methods. It wraps any existing MintPayment implementation +/// and automatically records timing and operation metrics. +#[derive(Clone)] +#[cfg(feature = "prometheus")] +pub struct MetricsMintPayment { + inner: T, +} +#[cfg(feature = "prometheus")] +impl MetricsMintPayment +where + T: MintPayment, +{ + /// Create a new metrics wrapper around a MintPayment implementation + pub fn new(inner: T) -> Self { + Self { inner } + } + + /// Get reference to the underlying implementation + pub fn inner(&self) -> &T { + &self.inner + } + + /// Consume the wrapper and return the inner implementation + pub fn into_inner(self) -> T { + self.inner + } +} + +#[async_trait] +#[cfg(feature = "prometheus")] +impl MintPayment for MetricsMintPayment +where + T: MintPayment + Send + Sync, +{ + type Err = T::Err; + + async fn get_settings(&self) -> Result { + let start = std::time::Instant::now(); + METRICS.inc_in_flight_requests("get_settings"); + + let result = self.inner.get_settings().await; + + let duration = start.elapsed().as_secs_f64(); + METRICS.record_mint_operation_histogram("get_settings", result.is_ok(), duration); + METRICS.dec_in_flight_requests("get_settings"); + + result + } + + async fn create_incoming_payment_request( + &self, + unit: &CurrencyUnit, + options: IncomingPaymentOptions, + ) -> Result { + let start = std::time::Instant::now(); + METRICS.inc_in_flight_requests("create_incoming_payment_request"); + + let result = self + .inner + .create_incoming_payment_request(unit, options) + .await; + + let duration = start.elapsed().as_secs_f64(); + METRICS.record_mint_operation_histogram( + "create_incoming_payment_request", + result.is_ok(), + duration, + ); + METRICS.dec_in_flight_requests("create_incoming_payment_request"); + + result + } + + async fn get_payment_quote( + &self, + unit: &CurrencyUnit, + options: OutgoingPaymentOptions, + ) -> Result { + let start = std::time::Instant::now(); + METRICS.inc_in_flight_requests("get_payment_quote"); + + let result = self.inner.get_payment_quote(unit, options).await; + + let duration = start.elapsed().as_secs_f64(); + let success = result.is_ok(); + + if let Ok(ref quote) = result { + let amount: f64 = u64::from(quote.amount) as f64; + let fee: f64 = u64::from(quote.fee) as f64; + METRICS.record_lightning_payment(amount, fee); + } + + METRICS.record_mint_operation_histogram("get_payment_quote", success, duration); + METRICS.dec_in_flight_requests("get_payment_quote"); + + result + } + async fn wait_payment_event( + &self, + ) -> Result + Send>>, Self::Err> { + let start = std::time::Instant::now(); + METRICS.inc_in_flight_requests("wait_payment_event"); + + let result = self.inner.wait_payment_event().await; + + let duration = start.elapsed().as_secs_f64(); + let success = result.is_ok(); + + METRICS.record_mint_operation_histogram("wait_payment_event", success, duration); + METRICS.dec_in_flight_requests("wait_payment_event"); + + result + } + + async fn make_payment( + &self, + unit: &CurrencyUnit, + options: OutgoingPaymentOptions, + ) -> Result { + let start = std::time::Instant::now(); + METRICS.inc_in_flight_requests("make_payment"); + + let result = self.inner.make_payment(unit, options).await; + + let duration = start.elapsed().as_secs_f64(); + let success = result.is_ok(); + + METRICS.record_mint_operation_histogram("make_payment", success, duration); + METRICS.dec_in_flight_requests("make_payment"); + + result + } + + fn is_wait_invoice_active(&self) -> bool { + self.inner.is_wait_invoice_active() + } + + fn cancel_wait_invoice(&self) { + self.inner.cancel_wait_invoice() + } + + async fn check_incoming_payment_status( + &self, + payment_identifier: &PaymentIdentifier, + ) -> Result, Self::Err> { + let start = std::time::Instant::now(); + METRICS.inc_in_flight_requests("check_incoming_payment_status"); + + let result = self + .inner + .check_incoming_payment_status(payment_identifier) + .await; + + let duration = start.elapsed().as_secs_f64(); + METRICS.record_mint_operation_histogram( + "check_incoming_payment_status", + result.is_ok(), + duration, + ); + METRICS.dec_in_flight_requests("check_incoming_payment_status"); + + result + } + + async fn check_outgoing_payment( + &self, + payment_identifier: &PaymentIdentifier, + ) -> Result { + let start = std::time::Instant::now(); + METRICS.inc_in_flight_requests("check_outgoing_payment"); + + let result = self.inner.check_outgoing_payment(payment_identifier).await; + + let duration = start.elapsed().as_secs_f64(); + let success = result.is_ok(); + + METRICS.record_mint_operation_histogram("check_outgoing_payment", success, duration); + METRICS.dec_in_flight_requests("check_outgoing_payment"); + + result + } +} diff --git a/crates/cdk-integration-tests/Cargo.toml b/crates/cdk-integration-tests/Cargo.toml index 7a2576039..8e5dce7f9 100644 --- a/crates/cdk-integration-tests/Cargo.toml +++ b/crates/cdk-integration-tests/Cargo.toml @@ -29,7 +29,7 @@ cdk-sqlite = { workspace = true } cdk-redb = { workspace = true } cdk-fake-wallet = { workspace = true } cdk-common = { workspace = true, features = ["mint", "wallet", "auth"] } -cdk-mintd = { workspace = true, features = ["cln", "lnd", "fakewallet", "grpc-processor", "auth", "lnbits", "management-rpc", "sqlite", "postgres", "ldk-node"] } +cdk-mintd = { workspace = true, features = ["cln", "lnd", "fakewallet", "grpc-processor", "auth", "lnbits", "management-rpc", "sqlite", "postgres", "ldk-node", "prometheus"] } futures = { workspace = true, default-features = false, features = [ "executor", ] } diff --git a/crates/cdk-integration-tests/src/bin/start_regtest_mints.rs b/crates/cdk-integration-tests/src/bin/start_regtest_mints.rs index 4c361fb5c..3ebcf2612 100644 --- a/crates/cdk-integration-tests/src/bin/start_regtest_mints.rs +++ b/crates/cdk-integration-tests/src/bin/start_regtest_mints.rs @@ -286,6 +286,7 @@ fn create_ldk_settings( grpc_processor: None, database: cdk_mintd::config::Database::default(), mint_management_rpc: None, + prometheus: None, auth: None, } } diff --git a/crates/cdk-integration-tests/src/shared.rs b/crates/cdk-integration-tests/src/shared.rs index d854441ef..c052ca9c7 100644 --- a/crates/cdk-integration-tests/src/shared.rs +++ b/crates/cdk-integration-tests/src/shared.rs @@ -219,6 +219,7 @@ pub fn create_fake_wallet_settings( }, mint_management_rpc: None, auth: None, + prometheus: Some(Default::default()), } } @@ -265,6 +266,7 @@ pub fn create_cln_settings( database: cdk_mintd::config::Database::default(), mint_management_rpc: None, auth: None, + prometheus: Some(Default::default()), } } @@ -310,5 +312,6 @@ pub fn create_lnd_settings( database: cdk_mintd::config::Database::default(), mint_management_rpc: None, auth: None, + prometheus: Some(Default::default()), } } diff --git a/crates/cdk-mintd/Cargo.toml b/crates/cdk-mintd/Cargo.toml index 240e791ce..ae83b7515 100644 --- a/crates/cdk-mintd/Cargo.toml +++ b/crates/cdk-mintd/Cargo.toml @@ -28,6 +28,7 @@ sqlcipher = ["sqlite", "cdk-sqlite/sqlcipher"] swagger = ["cdk-axum/swagger", "dep:utoipa", "dep:utoipa-swagger-ui"] redis = ["cdk-axum/redis"] auth = ["cdk/auth", "cdk-axum/auth", "cdk-sqlite?/auth", "cdk-postgres?/auth"] +prometheus = ["cdk/prometheus", "dep:cdk-prometheus", "cdk-sqlite?/prometheus", "cdk-axum/prometheus"] [dependencies] anyhow.workspace = true @@ -38,8 +39,9 @@ cdk = { workspace = true, features = [ ] } cdk-sqlite = { workspace = true, features = [ "mint" -], optional = true } -cdk-postgres = { workspace = true, features = ["mint"], optional = true } +], optional = true } +cdk-common = {workspace = true, features = ["prometheus"]} +cdk-postgres = { workspace = true, features = ["mint"], optional = true} cdk-cln = { workspace = true, optional = true } cdk-lnbits = { workspace = true, optional = true } cdk-lnd = { workspace = true, optional = true } @@ -50,6 +52,7 @@ cdk-signatory.workspace = true cdk-mint-rpc = { workspace = true, optional = true } cdk-payment-processor = { workspace = true, optional = true } config.workspace = true +cdk-prometheus = { workspace = true, optional = true , features = ["system-metrics"]} clap.workspace = true bitcoin.workspace = true tokio = { workspace = true, default-features = false, features = ["signal"] } @@ -63,11 +66,7 @@ tower-http = { workspace = true, features = ["compression-full", "decompression- tower.workspace = true lightning-invoice.workspace = true home.workspace = true -url.workspace = true utoipa = { workspace = true, optional = true } utoipa-swagger-ui = { version = "9.0.0", features = ["axum"], optional = true } [build-dependencies] -# Dep of utopia 2.5.0 breaks so keeping here for now -zip = "=2.4.2" -time = "=0.3.39" diff --git a/crates/cdk-mintd/example.config.toml b/crates/cdk-mintd/example.config.toml index 2b103175b..6aa7510e5 100644 --- a/crates/cdk-mintd/example.config.toml +++ b/crates/cdk-mintd/example.config.toml @@ -1,3 +1,4 @@ + [info] url = "https://mint.thesimplekid.dev/" listen_host = "127.0.0.1" @@ -20,7 +21,11 @@ enabled = false # address = "127.0.0.1" # port = 8086 - +#[prometheus] +#enabled = true +#address = "127.0.0.1" +#port = 9090 +# [info.http_cache] # memory or redis backend = "memory" @@ -130,12 +135,12 @@ reserve_fee_min = 4 # webserver_host = "127.0.0.1" # Default: 127.0.0.1 # webserver_port = 0 # 0 = auto-assign available port -# [fake_wallet] -# supported_units = ["sat"] -# fee_percent = 0.02 -# reserve_fee_min = 1 -# min_delay_time = 1 -# max_delay_time = 3 +[fake_wallet] +supported_units = ["sat"] +fee_percent = 0.02 +reserve_fee_min = 1 +min_delay_time = 1 +max_delay_time = 3 # [grpc_processor] # gRPC Payment Processor configuration diff --git a/crates/cdk-mintd/src/config.rs b/crates/cdk-mintd/src/config.rs index e4877d7c8..a04ab7dcb 100644 --- a/crates/cdk-mintd/src/config.rs +++ b/crates/cdk-mintd/src/config.rs @@ -452,6 +452,16 @@ pub struct Settings { #[cfg(feature = "management-rpc")] pub mint_management_rpc: Option, pub auth: Option, + #[cfg(feature = "prometheus")] + pub prometheus: Option, +} + +#[derive(Debug, Clone, Serialize, Deserialize, Default)] +#[cfg(feature = "prometheus")] +pub struct Prometheus { + pub enabled: bool, + pub address: Option, + pub port: Option, } #[derive(Debug, Clone, Serialize, Deserialize, Default)] diff --git a/crates/cdk-mintd/src/env_vars/mod.rs b/crates/cdk-mintd/src/env_vars/mod.rs index 8a4edcdee..61501aabf 100644 --- a/crates/cdk-mintd/src/env_vars/mod.rs +++ b/crates/cdk-mintd/src/env_vars/mod.rs @@ -25,6 +25,8 @@ mod lnbits; mod lnd; #[cfg(feature = "management-rpc")] mod management_rpc; +#[cfg(feature = "prometheus")] +mod prometheus; use std::env; use std::str::FromStr; @@ -50,6 +52,8 @@ pub use lnd::*; #[cfg(feature = "management-rpc")] pub use management_rpc::*; pub use mint_info::*; +#[cfg(feature = "prometheus")] +pub use prometheus::*; use crate::config::{DatabaseEngine, LnBackend, Settings}; @@ -98,6 +102,11 @@ impl Settings { ); } + #[cfg(feature = "prometheus")] + { + self.prometheus = Some(self.prometheus.clone().unwrap_or_default().from_env()); + } + match self.ln.ln_backend { #[cfg(feature = "cln")] LnBackend::Cln => { diff --git a/crates/cdk-mintd/src/env_vars/prometheus.rs b/crates/cdk-mintd/src/env_vars/prometheus.rs new file mode 100644 index 000000000..446bc64e4 --- /dev/null +++ b/crates/cdk-mintd/src/env_vars/prometheus.rs @@ -0,0 +1,31 @@ +//! Prometheus environment variables + +use std::env; + +use crate::config::Prometheus; + +pub const ENV_PROMETHEUS_ENABLED: &str = "CDK_MINTD_PROMETHEUS_ENABLED"; +pub const ENV_PROMETHEUS_ADDRESS: &str = "CDK_MINTD_PROMETHEUS_ADDRESS"; +pub const ENV_PROMETHEUS_PORT: &str = "CDK_MINTD_PROMETHEUS_PORT"; + +impl Prometheus { + pub fn from_env(mut self) -> Self { + if let Ok(enabled_str) = env::var(ENV_PROMETHEUS_ENABLED) { + if let Ok(enabled) = enabled_str.parse() { + self.enabled = enabled; + } + } + + if let Ok(address) = env::var(ENV_PROMETHEUS_ADDRESS) { + self.address = Some(address); + } + + if let Ok(port_str) = env::var(ENV_PROMETHEUS_PORT) { + if let Ok(port) = port_str.parse() { + self.port = Some(port); + } + } + + self + } +} diff --git a/crates/cdk-mintd/src/lib.rs b/crates/cdk-mintd/src/lib.rs index ff13f63bc..9071c73c8 100644 --- a/crates/cdk-mintd/src/lib.rs +++ b/crates/cdk-mintd/src/lib.rs @@ -13,10 +13,7 @@ use std::sync::Arc; use anyhow::{anyhow, bail, Result}; use axum::Router; use bip39::Mnemonic; -// internal crate modules use cdk::cdk_database::{self, MintDatabase, MintKVStore, MintKeysDatabase}; -use cdk::cdk_payment; -use cdk::cdk_payment::MintPayment; use cdk::mint::{Mint, MintBuilder, MintMeltLimits}; #[cfg(any( feature = "cln", @@ -41,14 +38,22 @@ use cdk::nuts::{AuthRequired, Method, ProtectedEndpoint, RoutePath}; use cdk::nuts::{ContactInfo, MintVersion, PaymentMethod}; use cdk::types::QuoteTTL; use cdk_axum::cache::HttpCache; +// internal crate modules +#[cfg(feature = "prometheus")] +use cdk_common::payment::MetricsMintPayment; +use cdk_common::payment::MintPayment; +#[cfg(feature = "auth")] +use cdk_postgres::MintPgAuthDatabase; #[cfg(feature = "postgres")] -use cdk_postgres::{MintPgAuthDatabase, MintPgDatabase}; +use cdk_postgres::MintPgDatabase; #[cfg(all(feature = "auth", feature = "sqlite"))] use cdk_sqlite::mint::MintSqliteAuthDatabase; #[cfg(feature = "sqlite")] use cdk_sqlite::MintSqliteDatabase; use cli::CLIArgs; -use config::{AuthType, DatabaseEngine, LnBackend}; +#[cfg(feature = "auth")] +use config::AuthType; +use config::{DatabaseEngine, LnBackend}; use env_vars::ENV_WORK_DIR; use setup::LnBackendSetup; use tower::ServiceBuilder; @@ -440,6 +445,8 @@ async fn configure_lightning_backend( None, ) .await?; + #[cfg(feature = "prometheus")] + let cln = MetricsMintPayment::new(cln); mint_builder = configure_backend_for_unit( settings, @@ -463,6 +470,8 @@ async fn configure_lightning_backend( None, ) .await?; + #[cfg(feature = "prometheus")] + let lnbits = MetricsMintPayment::new(lnbits); mint_builder = configure_backend_for_unit( settings, @@ -486,6 +495,8 @@ async fn configure_lightning_backend( None, ) .await?; + #[cfg(feature = "prometheus")] + let lnd = MetricsMintPayment::new(lnd); mint_builder = configure_backend_for_unit( settings, @@ -512,6 +523,8 @@ async fn configure_lightning_backend( _kv_store.clone(), ) .await?; + #[cfg(feature = "prometheus")] + let fake = MetricsMintPayment::new(fake); mint_builder = configure_backend_for_unit( settings, @@ -541,6 +554,8 @@ async fn configure_lightning_backend( let processor = grpc_processor .setup(ln_routers, settings, unit.clone(), None, work_dir, None) .await?; + #[cfg(feature = "prometheus")] + let processor = MetricsMintPayment::new(processor); mint_builder = configure_backend_for_unit( settings, @@ -595,7 +610,7 @@ async fn configure_backend_for_unit( mut mint_builder: MintBuilder, unit: cdk::nuts::CurrencyUnit, mint_melt_limits: MintMeltLimits, - backend: Arc + Send + Sync>, + backend: Arc + Send + Sync>, ) -> Result { let payment_settings = backend.get_settings().await?; @@ -974,7 +989,48 @@ async fn start_services_with_shutdown( ); } } + // Create a broadcast channel to share shutdown signal between services + let (shutdown_tx, _) = tokio::sync::broadcast::channel::<()>(1); + + // Start Prometheus server if enabled + #[cfg(feature = "prometheus")] + let prometheus_handle = { + if let Some(prometheus_settings) = &settings.prometheus { + if prometheus_settings.enabled { + let addr = prometheus_settings + .address + .clone() + .unwrap_or("127.0.0.1".to_string()); + let port = prometheus_settings.port.unwrap_or(9000); + + let address = format!("{}:{}", addr, port) + .parse() + .expect("Invalid prometheus address"); + + let server = cdk_prometheus::PrometheusBuilder::new() + .bind_address(address) + .build_with_cdk_metrics()?; + + let mut shutdown_rx = shutdown_tx.subscribe(); + let prometheus_shutdown = async move { + let _ = shutdown_rx.recv().await; + }; + + Some(tokio::spawn(async move { + if let Err(e) = server.start(prometheus_shutdown).await { + tracing::error!("Failed to start prometheus server: {}", e); + } + })) + } else { + None + } + } else { + None + } + }; + #[cfg(not(feature = "prometheus"))] + let prometheus_handle: Option> = None; for router in ln_routers { mint_service = mint_service.merge(router); } @@ -987,8 +1043,24 @@ async fn start_services_with_shutdown( tracing::info!("listening on {}", listener.local_addr().unwrap()); + // Create a task to wait for the shutdown signal and broadcast it + let shutdown_broadcast_task = { + let shutdown_tx = shutdown_tx.clone(); + tokio::spawn(async move { + shutdown_signal.await; + tracing::info!("Shutdown signal received, broadcasting to all services"); + let _ = shutdown_tx.send(()); + }) + }; + + // Create shutdown future for axum server + let mut axum_shutdown_rx = shutdown_tx.subscribe(); + let axum_shutdown = async move { + let _ = axum_shutdown_rx.recv().await; + }; + // Wait for axum server to complete with custom shutdown signal - let axum_result = axum::serve(listener, mint_service).with_graceful_shutdown(shutdown_signal); + let axum_result = axum::serve(listener, mint_service).with_graceful_shutdown(axum_shutdown); match axum_result.await { Ok(_) => { @@ -1001,6 +1073,17 @@ async fn start_services_with_shutdown( } } + // Wait for the shutdown broadcast task to complete + let _ = shutdown_broadcast_task.await; + + // Wait for prometheus server to shutdown if it was started + #[cfg(feature = "prometheus")] + if let Some(handle) = prometheus_handle { + if let Err(e) = handle.await { + tracing::warn!("Prometheus server task failed: {}", e); + } + } + mint.stop().await?; #[cfg(feature = "management-rpc")] diff --git a/crates/cdk-prometheus/Cargo.toml b/crates/cdk-prometheus/Cargo.toml new file mode 100644 index 000000000..13c8a7de1 --- /dev/null +++ b/crates/cdk-prometheus/Cargo.toml @@ -0,0 +1,47 @@ +[package] +name = "cdk-prometheus" +version.workspace = true +edition.workspace = true +rust-version.workspace = true +license.workspace = true +homepage.workspace = true +repository.workspace = true +readme = "README.md" +description = "Prometheus metrics export server for CDK applications" + +[features] +default = ["system-metrics"] +system-metrics = ["sysinfo"] + +[dependencies] +# Prometheus +prometheus = "0.13" + +# Async runtime +tokio.workspace = true +futures.workspace = true + +# Error handling +anyhow.workspace = true +thiserror.workspace = true + +# Serialization +serde.workspace = true +serde_json.workspace = true + +# System metrics (optional) +sysinfo = { version = "0.32", optional = true } + +# Tracing +tracing.workspace = true + +# Utility +once_cell.workspace = true + +[dev-dependencies] +tokio = { workspace = true, features = ["full"] } +reqwest.workspace = true +tracing-subscriber.workspace = true + +[lints] +workspace = true diff --git a/crates/cdk-prometheus/README.md b/crates/cdk-prometheus/README.md new file mode 100644 index 000000000..00ecdaf87 --- /dev/null +++ b/crates/cdk-prometheus/README.md @@ -0,0 +1,189 @@ +# CDK Prometheus + +A small, focused crate that provides Prometheus metrics for CDK-based services. It bundles a ready-to-use metrics registry, a background HTTP server to expose metrics, helper functions for common CDK domains (HTTP, auth, Lightning, DB, mint operations), and an ergonomic macro for conditional metrics recording. + +- Out-of-the-box metrics for HTTP, auth, Lightning payments, database, and mint operations +- Global, lazily-initialized metrics instance you can use anywhere +- Optional background server to expose metrics on /metrics +- Re-exports the prometheus crate for custom instrumentation +- Optional system metrics (feature-gated) + +## Installation + +Add the crate to your Cargo.toml (replace the version as needed): + +```toml +[dependencies] cdk-prometheus = { version = "0.1", features = ["system-metrics"] } +``` + +- Feature flags: + - system-metrics: include basic process/system metrics collected periodically. + +Note for downstream crates: the provided record_metrics! macro is gated at call-site by a feature named prometheus. If you use that macro, declare a prometheus feature in your application crate and enable it to compile the macro calls into real metrics (otherwise they no-op). + +## Quick start +### Docker +Start Prometheus and Grafana with docker-compose: +``` +docker compose up -d prometheus grafana +``` +Start your mintd +``` +./mintd -w ~/.cdk-mintd +``` +Check Prometheus and Grafana +* `curl localhost:9000/metrics` for checking CDK metrics +* `http://localhost:9090/targets?search=` checking the prometheus collector (you should see http://host.docker.internal:9000/metrics) +* `http://localhost:3011/d/cdk-mint-dashboard/cdk-mint-dashboard` Grafana dashboard (default login: admin/admin) + +### Rust +Expose a Prometheus endpoint with a default registry and CDK metrics: +```rust +use cdk_prometheus::start_default_server_with_metrics; +#[tokio::main] async fn main() -> anyhow::Result<()> { // Starts an HTTP server (default bind and path) and registers CDK metrics into its registry start_default_server_with_metrics().await?; Ok(()) } +``` + +Or start it in the background (e.g., from your application bootstrap): +```rust +use cdk_prometheus::start_background_server_with_metrics; +fn main() -> anyhow::Result<()> { let _handle = start_background_server_with_metrics()?; // Continue bootstrapping your application... Ok(()) } +``` + +## Recording metrics + +You can record metrics using: +- The global helpers (simple functions) +- The global singleton METRICS (direct methods) +- The record_metrics! macro (conditional recording with an optional instance) + +### Global helpers +```rust +use cdk_prometheus::global; +fn handle_request() { + global::record_http_request("/health", "200"); global::record_http_request_duration(0.003, "/health"); + global::record_auth_attempt(); + global::record_auth_success(); + + // Lightning and DB + global::record_lightning_payment(1500.0, 2.0); // amount, fee (both in base units you track) + global::record_db_operation(0.015, "select_user"); + global::set_db_connections_active(8); + + // Mint operations + global::inc_in_flight_requests("get_payment_quote"); + // ... do work ... + global::record_mint_operation("get_payment_quote", true); + global::record_mint_operation_histogram("get_payment_quote", true, 0.021); + global::dec_in_flight_requests("get_payment_quote"); + + // Errors + global::record_error(); +} +``` + +### Using the global METRICS instance directly +```rust +use cdk_prometheus::METRICS; +fn do_db_work() { METRICS.record_db_operation(0.005, "update_user"); } +``` + +### Using the record_metrics! macro + +The macro lets you write grouped calls concisely and optionally pass an instance to use; if no instance is present, it automatically falls back to the global helpers. At call-site, wrap your invocations with a prometheus feature so they can be disabled in minimal builds. +```rust +use cdk_prometheus::record_metrics; +fn run_operation(metrics_opt: Option) { // Use instance if present, otherwise fallback to global record_metrics!(metrics_opt => { inc_in_flight_requests("make_payment"); record_mint_operation("make_payment", true); record_mint_operation_histogram("make_payment", true, 0.123); dec_in_flight_requests("make_payment"); }); + // Or call directly on the global helpers + record_metrics!({ + record_error(); + }); +} +``` + +## Exposing the /metrics endpoint + +If you just need sane defaults, use the convenience starters shown above. If you want finer control (bind address, path, system metrics), build the server explicitly: +```rust +use cdk_prometheus::{PrometheusBuilder, PrometheusServer, CdkMetrics, prometheus::Registry}; +fn build_and_run() -> anyhow::Result>> { // Build a server wired up with the default CDK metrics let server = PrometheusBuilder::new().build_with_cdk_metrics()?; let handle = server.start_background(); Ok(handle) } +``` + +Notes: +- Default bind address and metrics path are set by the server configuration (commonly 127.0.0.1:9090 and /metrics). +- With system-metrics enabled, the server periodically updates process/system gauges. + +## What’s included + +The default CDK metrics instance (CdkMetrics) registers and maintains counters, histograms, and gauges for common areas: +- HTTP: request totals, durations +- Auth: attempts and successes +- Lightning: payment totals, amounts, fees +- Database: operation totals, latencies, active connections +- Mint: operation totals, in-flight gauges, per-operation latencies +- Errors: a general counter + +You can use these immediately through the global helpers or the METRICS instance. + +## Adding custom metrics + +This crate re-exports the prometheus crate and exposes the underlying Registry so you can define and register your own metrics: +```rust +use cdk_prometheus::{prometheus, global}; +fn register_custom_metric() -> Result<(), prometheus::Error> { let my_counter = prometheus::IntCounter::new("my_counter", "A custom counter")?; let registry = global::registry(); // Arcregistry.register(Box::new(my_counter.clone()))?; + my_counter.inc(); + Ok(()) +} +``` + +If you prefer instance-level control: +```rust +use std::sync::Arc; use cdk_prometheus::{create_cdk_metrics, prometheus}; +fn with_instance() -> anyhow::Result<()> { let metrics = create_cdk_metrics()?; let registry: Arc[prometheus::Registry]() = metrics.registry(); + let hist = prometheus::Histogram::with_opts( + prometheus::HistogramOpts::new("my_latency_seconds", "My op latency") +)?; +registry.register(Box::new(hist))?; +Ok(()) +} +``` + +## Scraping with Prometheus + +Example scrape_config: +```yaml +scrape_configs: +- job_name: 'cdk' + scrape_interval: 15s + static_configs: + - targets: ['127.0.0.1:9090'] +``` + +If you changed the bind address or path, make sure to update targets or the metrics_path in your Prometheus configuration accordingly. + +## System metrics (optional) + +Enable the system-metrics feature to export basic process/system metrics. The server updates these at a configurable interval. +```toml +cdk-prometheus = { version = "0.1", features = ["system-metrics"] } +``` + +## Error handling + +Common error types surfaced by this crate include: +- Server bind failures +- Metrics collection/registry errors +- System metrics collection errors (when enabled) + +Handle these at startup and monitor logs during runtime. + +## Best practices + +- Run the metrics server on localhost or a private interface and use a Prometheus agent/sidecar if needed. +- Register application-specific metrics early in your bootstrap so they are visible from the first scrape. +- Use histograms for latencies and size distributions; use counters for event totals; use gauges for in-flight or current-state values. +- Keep label cardinality bounded. + +## License + +MIT +``` diff --git a/crates/cdk-prometheus/src/error.rs b/crates/cdk-prometheus/src/error.rs new file mode 100644 index 000000000..9d8746f9c --- /dev/null +++ b/crates/cdk-prometheus/src/error.rs @@ -0,0 +1,32 @@ +use thiserror::Error; + +/// Errors that can occur in the Prometheus crate +#[derive(Error, Debug)] +pub enum PrometheusError { + /// Server binding error + #[error("Failed to bind to address {address}: {source}")] + ServerBind { + address: String, + #[source] + source: std::io::Error, + }, + + /// Metrics collection error + #[error("Failed to collect metrics: {0}")] + MetricsCollection(String), + + /// Registry error + #[error("Registry error: {source}")] + Registry { + #[from] + source: prometheus::Error, + }, + + /// System metrics error + #[cfg(feature = "system-metrics")] + #[error("System metrics error: {0}")] + SystemMetrics(String), +} + +/// Result type for Prometheus operations +pub type Result = std::result::Result; diff --git a/crates/cdk-prometheus/src/lib.rs b/crates/cdk-prometheus/src/lib.rs new file mode 100644 index 000000000..913b2645b --- /dev/null +++ b/crates/cdk-prometheus/src/lib.rs @@ -0,0 +1,84 @@ +//! # CDK Prometheus + +pub mod error; +pub mod metrics; +pub mod server; + +#[cfg(feature = "system-metrics")] +pub mod process; + +// Re-exports for convenience +pub use error::{PrometheusError, Result}; +pub use metrics::{global, CdkMetrics, METRICS}; +#[cfg(feature = "system-metrics")] +pub use process::SystemMetrics; +// Re-export prometheus crate for custom metrics +pub use prometheus; +pub use server::{PrometheusBuilder, PrometheusConfig, PrometheusServer}; + +/// Macro for recording metrics with optional fallback to global instance +/// +/// Usage: +/// ```rust +/// use cdk_prometheus::record_metrics; +/// +/// // With optional metrics instance +/// record_metrics!(metrics_option => { +/// dec_in_flight_requests("operation"); +/// record_mint_operation("operation", true); +/// }); +/// +/// // Direct global calls +/// record_metrics!({ +/// dec_in_flight_requests("operation"); +/// record_mint_operation("operation", true); +/// }); +/// ``` +#[macro_export] +macro_rules! record_metrics { + // Pattern for using optional metrics with fallback to global + ($metrics_opt:expr => { $($method:ident($($arg:expr),*));* $(;)? }) => { + #[cfg(feature = "prometheus")] + { + if let Some(metrics) = $metrics_opt.as_ref() { + $( + metrics.$method($($arg),*); + )* + } else { + $( + $crate::global::$method($($arg),*); + )* + } + } + }; + + // Pattern for using global metrics directly + ({ $($method:ident($($arg:expr),*));* $(;)? }) => { + #[cfg(feature = "prometheus")] + { + $( + $crate::global::$method($($arg),*); + )* + } + }; +} + +/// Convenience function to create a new CDK metrics instance +/// +/// # Errors +/// Returns an error if any of the metrics cannot be created or registered +pub fn create_cdk_metrics() -> Result { + CdkMetrics::new() +} + +/// Convenience function to start a Prometheus server with specific metrics +/// +/// # Errors +/// Returns an error if the server cannot be created or started +pub async fn start_default_server_with_metrics( + shutdown_signal: impl std::future::Future + Send + 'static, +) -> Result<()> { + let server = PrometheusBuilder::new().build_with_cdk_metrics()?; + + server.start(shutdown_signal).await +} diff --git a/crates/cdk-prometheus/src/metrics.rs b/crates/cdk-prometheus/src/metrics.rs new file mode 100644 index 000000000..e761c5a33 --- /dev/null +++ b/crates/cdk-prometheus/src/metrics.rs @@ -0,0 +1,427 @@ +use std::sync::Arc; + +use prometheus::{ + Histogram, HistogramVec, IntCounter, IntCounterVec, IntGauge, IntGaugeVec, Registry, +}; + +/// Global metrics instance +pub static METRICS: std::sync::LazyLock = std::sync::LazyLock::new(CdkMetrics::default); + +/// Custom metrics for CDK applications +#[derive(Clone, Debug)] +pub struct CdkMetrics { + registry: Arc, + + // HTTP metrics + http_requests_total: IntCounterVec, + http_request_duration: HistogramVec, + + // Authentication metrics + auth_attempts_total: IntCounter, + auth_successes_total: IntCounter, + + // Lightning metrics + lightning_payments_total: IntCounter, + lightning_payment_amount: Histogram, + lightning_payment_fees: Histogram, + + // Database metrics + db_operations_total: IntCounter, + db_operation_duration: HistogramVec, + db_connections_active: IntGauge, + + // Error metrics + errors_total: IntCounter, + + // Mint metrics + mint_operations_total: IntCounterVec, + mint_in_flight_requests: IntGaugeVec, + mint_operation_duration: HistogramVec, +} + +impl CdkMetrics { + /// Create a new instance with default metrics + /// + /// # Errors + /// Returns an error if any of the metrics cannot be created or registered + pub fn new() -> crate::Result { + let registry = Arc::new(Registry::new()); + + // Create and register HTTP metrics + let (http_requests_total, http_request_duration) = Self::create_http_metrics(®istry)?; + + // Create and register authentication metrics + let (auth_attempts_total, auth_successes_total) = Self::create_auth_metrics(®istry)?; + + // Create and register Lightning metrics + let (lightning_payments_total, lightning_payment_amount, lightning_payment_fees) = + Self::create_lightning_metrics(®istry)?; + + // Create and register database metrics + let (db_operations_total, db_operation_duration, db_connections_active) = + Self::create_db_metrics(®istry)?; + + // Create and register error metrics + let errors_total = Self::create_error_metrics(®istry)?; + + // Create and register mint metrics + let (mint_operations_total, mint_operation_duration, mint_in_flight_requests) = + Self::create_mint_metrics(®istry)?; + + Ok(Self { + registry, + http_requests_total, + http_request_duration, + auth_attempts_total, + auth_successes_total, + lightning_payments_total, + lightning_payment_amount, + lightning_payment_fees, + db_operations_total, + db_operation_duration, + db_connections_active, + errors_total, + mint_operations_total, + mint_in_flight_requests, + mint_operation_duration, + }) + } + + /// Create and register HTTP metrics + /// + /// # Errors + /// Returns an error if any of the metrics cannot be created or registered + fn create_http_metrics(registry: &Registry) -> crate::Result<(IntCounterVec, HistogramVec)> { + let http_requests_total = IntCounterVec::new( + prometheus::Opts::new("cdk_http_requests_total", "Total number of HTTP requests"), + &["endpoint", "status"], + )?; + registry.register(Box::new(http_requests_total.clone()))?; + + let http_request_duration = HistogramVec::new( + prometheus::HistogramOpts::new( + "cdk_http_request_duration_seconds", + "HTTP request duration in seconds", + ) + .buckets(vec![ + 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0, + ]), + &["endpoint"], + )?; + registry.register(Box::new(http_request_duration.clone()))?; + + Ok((http_requests_total, http_request_duration)) + } + + /// Create and register authentication metrics + /// + /// # Errors + /// Returns an error if any of the metrics cannot be created or registered + fn create_auth_metrics(registry: &Registry) -> crate::Result<(IntCounter, IntCounter)> { + let auth_attempts_total = + IntCounter::new("cdk_auth_attempts_total", "Total authentication attempts")?; + registry.register(Box::new(auth_attempts_total.clone()))?; + + let auth_successes_total = IntCounter::new( + "cdk_auth_successes_total", + "Total successful authentications", + )?; + registry.register(Box::new(auth_successes_total.clone()))?; + + Ok((auth_attempts_total, auth_successes_total)) + } + + /// Create and register Lightning metrics + /// + /// # Errors + /// Returns an error if any of the metrics cannot be created or registered + fn create_lightning_metrics( + registry: &Registry, + ) -> crate::Result<(IntCounter, Histogram, Histogram)> { + let wallet_operations_total = + IntCounter::new("cdk_wallet_operations_total", "Total wallet operations")?; + registry.register(Box::new(wallet_operations_total))?; + + let lightning_payments_total = + IntCounter::new("cdk_lightning_payments_total", "Total Lightning payments")?; + registry.register(Box::new(lightning_payments_total.clone()))?; + + let lightning_payment_amount = Histogram::with_opts( + prometheus::HistogramOpts::new( + "cdk_lightning_payment_amount_sats", + "Lightning payment amounts in satoshis", + ) + .buckets(vec![ + 1.0, + 10.0, + 100.0, + 1000.0, + 10_000.0, + 100_000.0, + 1_000_000.0, + ]), + )?; + registry.register(Box::new(lightning_payment_amount.clone()))?; + + let lightning_payment_fees = Histogram::with_opts( + prometheus::HistogramOpts::new( + "cdk_lightning_payment_fees_sats", + "Lightning payment fees in satoshis", + ) + .buckets(vec![0.0, 1.0, 5.0, 10.0, 50.0, 100.0, 500.0, 1000.0]), + )?; + registry.register(Box::new(lightning_payment_fees.clone()))?; + + Ok(( + lightning_payments_total, + lightning_payment_amount, + lightning_payment_fees, + )) + } + + /// Create and register database metrics + /// + /// # Errors + /// Returns an error if any of the metrics cannot be created or registered + fn create_db_metrics( + registry: &Registry, + ) -> crate::Result<(IntCounter, HistogramVec, IntGauge)> { + let db_operations_total = + IntCounter::new("cdk_db_operations_total", "Total database operations")?; + registry.register(Box::new(db_operations_total.clone()))?; + let db_operation_duration = HistogramVec::new( + prometheus::HistogramOpts::new( + "cdk_db_operation_duration_seconds", + "Database operation duration in seconds", + ) + .buckets(vec![0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0]), + &["operation"], + )?; + registry.register(Box::new(db_operation_duration.clone()))?; + + let db_connections_active = IntGauge::new( + "cdk_db_connections_active", + "Number of active database connections", + )?; + registry.register(Box::new(db_connections_active.clone()))?; + + Ok(( + db_operations_total, + db_operation_duration, + db_connections_active, + )) + } + + /// Create and register error metrics + /// + /// # Errors + /// Returns an error if any of the metrics cannot be created or registered + fn create_error_metrics(registry: &Registry) -> crate::Result { + let errors_total = IntCounter::new("cdk_errors_total", "Total errors")?; + registry.register(Box::new(errors_total.clone()))?; + + Ok(errors_total) + } + + /// Create and register mint metrics + /// + /// # Errors + /// Returns an error if any of the metrics cannot be created or registered + fn create_mint_metrics( + registry: &Registry, + ) -> crate::Result<(IntCounterVec, HistogramVec, IntGaugeVec)> { + let mint_operations_total = IntCounterVec::new( + prometheus::Opts::new( + "cdk_mint_operations_total", + "Total number of mint operations", + ), + &["operation", "status"], + )?; + registry.register(Box::new(mint_operations_total.clone()))?; + + let mint_operation_duration = HistogramVec::new( + prometheus::HistogramOpts::new( + "cdk_mint_operation_duration_seconds", + "Duration of mint operations in seconds", + ) + .buckets(vec![ + 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0, + ]), + &["operation", "status"], + )?; + registry.register(Box::new(mint_operation_duration.clone()))?; + + let mint_in_flight_requests = IntGaugeVec::new( + prometheus::Opts::new( + "cdk_mint_in_flight_requests", + "Number of in-flight mint requests", + ), + &["operation"], + )?; + registry.register(Box::new(mint_in_flight_requests.clone()))?; + + Ok(( + mint_operations_total, + mint_operation_duration, + mint_in_flight_requests, + )) + } + + /// Get the metrics registry + #[must_use] + pub fn registry(&self) -> Arc { + Arc::::clone(&self.registry) + } + + // HTTP metrics methods + pub fn record_http_request(&self, endpoint: &str, status: &str) { + self.http_requests_total + .with_label_values(&[endpoint, status]) + .inc(); + } + + pub fn record_http_request_duration(&self, duration_seconds: f64, endpoint: &str) { + self.http_request_duration + .with_label_values(&[endpoint]) + .observe(duration_seconds); + } + + // Authentication metrics methods + pub fn record_auth_attempt(&self) { + self.auth_attempts_total.inc(); + } + + pub fn record_auth_success(&self) { + self.auth_successes_total.inc(); + } + + // Lightning metrics methods + pub fn record_lightning_payment(&self, amount: f64, fee: f64) { + self.lightning_payments_total.inc(); + self.lightning_payment_amount.observe(amount); + self.lightning_payment_fees.observe(fee); + } + + // Database metrics methods + pub fn record_db_operation(&self, duration_seconds: f64, op: &str) { + self.db_operations_total.inc(); + self.db_operation_duration + .with_label_values(&[op]) + .observe(duration_seconds); + } + + pub fn set_db_connections_active(&self, count: i64) { + self.db_connections_active.set(count); + } + + // Error metrics methods + pub fn record_error(&self) { + self.errors_total.inc(); + } + + // Mint metrics methods + pub fn record_mint_operation(&self, operation: &str, success: bool) { + let status = if success { "success" } else { "error" }; + self.mint_operations_total + .with_label_values(&[operation, status]) + .inc(); + } + pub fn record_mint_operation_histogram( + &self, + operation: &str, + success: bool, + duration_seconds: f64, + ) { + let status = if success { "success" } else { "error" }; + self.mint_operation_duration + .with_label_values(&[operation, status]) + .observe(duration_seconds); + } + pub fn inc_in_flight_requests(&self, operation: &str) { + self.mint_in_flight_requests + .with_label_values(&[operation]) + .inc(); + } + + pub fn dec_in_flight_requests(&self, operation: &str) { + self.mint_in_flight_requests + .with_label_values(&[operation]) + .dec(); + } +} + +impl Default for CdkMetrics { + fn default() -> Self { + Self::new().expect("Failed to create default CdkMetrics") + } +} + +/// Helper functions for recording metrics using the global instance +pub mod global { + use super::METRICS; + + /// Record an HTTP request using the global metrics instance + pub fn record_http_request(endpoint: &str, status: &str) { + METRICS.record_http_request(endpoint, status); + } + + /// Record HTTP request duration using the global metrics instance + pub fn record_http_request_duration(duration_seconds: f64, endpoint: &str) { + METRICS.record_http_request_duration(duration_seconds, endpoint); + } + + /// Record authentication attempt using the global metrics instance + pub fn record_auth_attempt() { + METRICS.record_auth_attempt(); + } + + /// Record authentication success using the global metrics instance + pub fn record_auth_success() { + METRICS.record_auth_success(); + } + + /// Record Lightning payment using the global metrics instance + pub fn record_lightning_payment(amount: f64, fee: f64) { + METRICS.record_lightning_payment(amount, fee); + } + + /// Record database operation using the global metrics instance + pub fn record_db_operation(duration_seconds: f64, op: &str) { + METRICS.record_db_operation(duration_seconds, op); + } + + /// Set database connections active using the global metrics instance + pub fn set_db_connections_active(count: i64) { + METRICS.set_db_connections_active(count); + } + + /// Record error using the global metrics instance + pub fn record_error() { + METRICS.record_error(); + } + + /// Record mint operation using the global metrics instance + pub fn record_mint_operation(operation: &str, success: bool) { + METRICS.record_mint_operation(operation, success); + } + + /// Record mint operation with histogram using the global metrics instance + pub fn record_mint_operation_histogram(operation: &str, success: bool, duration_seconds: f64) { + METRICS.record_mint_operation_histogram(operation, success, duration_seconds); + } + + /// Increment in-flight requests using the global metrics instance + pub fn inc_in_flight_requests(operation: &str) { + METRICS.inc_in_flight_requests(operation); + } + + /// Decrement in-flight requests using the global metrics instance + pub fn dec_in_flight_requests(operation: &str) { + METRICS.dec_in_flight_requests(operation); + } + + /// Get the metrics registry from the global instance + pub fn registry() -> std::sync::Arc { + METRICS.registry() + } +} diff --git a/crates/cdk-prometheus/src/process.rs b/crates/cdk-prometheus/src/process.rs new file mode 100644 index 000000000..7ccc11f00 --- /dev/null +++ b/crates/cdk-prometheus/src/process.rs @@ -0,0 +1,107 @@ +use std::sync::Arc; + +#[cfg(feature = "system-metrics")] +use prometheus::{Gauge, IntGauge, Registry}; +#[cfg(feature = "system-metrics")] +use sysinfo::{Pid, System}; + +/// System metrics collector that provides CPU, memory, disk, network, and process metrics +#[cfg(feature = "system-metrics")] +#[derive(Clone, Debug)] +pub struct SystemMetrics { + registry: Arc, + system: Arc>, + + // Process metrics (for the CDK process) + process_cpu_usage_percent: Gauge, + process_memory_bytes: IntGauge, + process_memory_percent: Gauge, +} + +#[cfg(feature = "system-metrics")] +impl SystemMetrics { + /// Create a new `SystemMetrics` instance + /// + /// # Errors + /// Returns an error if any of the metrics cannot be created or registered + pub fn new() -> crate::Result { + let registry = Arc::new(Registry::new()); + // Process metrics + let process_cpu_usage_percent = Gauge::new( + "process_cpu_usage_percent", + "CPU usage percentage of the CDK process (0-100)", + )?; + registry.register(Box::new(process_cpu_usage_percent.clone()))?; + + let process_memory_bytes = IntGauge::new( + "process_memory_bytes", + "Memory usage of the CDK process in bytes", + )?; + registry.register(Box::new(process_memory_bytes.clone()))?; + + let process_memory_percent = Gauge::new( + "process_memory_percent", + "Memory usage percentage of the CDK process (0-100)", + )?; + registry.register(Box::new(process_memory_percent.clone()))?; + + // Initialize system with all needed refresh kinds + let system = Arc::new(std::sync::Mutex::new(System::new())); + + let result = Self { + registry, + system, + process_cpu_usage_percent, + process_memory_bytes, + process_memory_percent, + }; + + Ok(result) + } + + /// Get the metrics registry + #[must_use] + pub fn registry(&self) -> Arc { + Arc::::clone(&self.registry) + } + + /// Update all system metrics + /// + /// # Errors + /// Returns an error if the system mutex cannot be locked + pub fn update_metrics(&self) -> crate::Result<()> { + let mut system = self.system.lock().map_err(|e| { + crate::error::PrometheusError::SystemMetrics(format!("Failed to lock system: {e}")) + })?; + // Refresh system information + system.refresh_all(); + + // Update memory metrics + let total_memory = i64::try_from(system.total_memory()).unwrap_or(i64::MAX); + + // Update process metrics for the current process + // This is a simplified approach that may not work perfectly in all cases + if let Some(process) = system.process(Pid::from(std::process::id() as usize)) { + // Get CPU usage if available + let process_cpu = process.cpu_usage(); + self.process_cpu_usage_percent.set(f64::from(process_cpu)); + + // Get memory usage if available + let process_memory = i64::try_from(process.memory()).unwrap_or(i64::MAX); + self.process_memory_bytes.set(process_memory); + + // Calculate memory percentage + if total_memory > 0 { + // Precision loss is acceptable for percentage calculation + #[allow(clippy::cast_precision_loss)] + let process_memory_percent = (process_memory as f64 / total_memory as f64) * 100.0; + self.process_memory_percent.set(process_memory_percent); + } + } + + // Drop the system lock early to avoid resource contention + drop(system); + + Ok(()) + } +} diff --git a/crates/cdk-prometheus/src/server.rs b/crates/cdk-prometheus/src/server.rs new file mode 100644 index 000000000..68e495ab7 --- /dev/null +++ b/crates/cdk-prometheus/src/server.rs @@ -0,0 +1,317 @@ +use std::net::SocketAddr; +use std::sync::Arc; +use std::time::Duration; + +use prometheus::{Registry, TextEncoder}; + +use crate::metrics::METRICS; +#[cfg(feature = "system-metrics")] +use crate::process::SystemMetrics; + +/// Configuration for the Prometheus server +#[derive(Debug, Clone)] +pub struct PrometheusConfig { + /// Address to bind the server to (default: "127.0.0.1:9090") + pub bind_address: SocketAddr, + /// Path to serve metrics on (default: "/metrics") + pub metrics_path: String, + /// Whether to include system metrics (default: true if feature enabled) + #[cfg(feature = "system-metrics")] + pub include_system_metrics: bool, + /// How often to update system metrics in seconds (default: 15) + #[cfg(feature = "system-metrics")] + pub system_metrics_interval: u64, +} + +impl Default for PrometheusConfig { + fn default() -> Self { + Self { + bind_address: "127.0.0.1:9090".parse().expect("Invalid default address"), + metrics_path: "/metrics".to_string(), + #[cfg(feature = "system-metrics")] + include_system_metrics: true, + #[cfg(feature = "system-metrics")] + system_metrics_interval: 15, + } + } +} + +/// Prometheus metrics server +#[derive(Debug)] +pub struct PrometheusServer { + config: PrometheusConfig, + registry: Arc, + #[cfg(feature = "system-metrics")] + system_metrics: Option, +} + +impl PrometheusServer { + /// Create a new Prometheus server with CDK metrics + /// + /// # Errors + /// Returns an error if system metrics cannot be created (when enabled) + pub fn new(config: PrometheusConfig) -> crate::Result { + let registry = METRICS.registry(); + + #[cfg(feature = "system-metrics")] + let system_metrics = if config.include_system_metrics { + let sys_metrics = SystemMetrics::new()?; + Some(sys_metrics) + } else { + None + }; + + Ok(Self { + config, + registry, + #[cfg(feature = "system-metrics")] + system_metrics, + }) + } + + /// Create a new Prometheus server with custom registry + #[must_use] + pub const fn with_registry(config: PrometheusConfig, registry: Arc) -> Self { + Self { + config, + registry, + #[cfg(feature = "system-metrics")] + system_metrics: None, + } + } + + /// Create a metrics handler function that gathers and encodes metrics + fn create_metrics_handler( + registry: Arc, + #[cfg(feature = "system-metrics")] system_metrics: Option, + ) -> impl Fn() -> String { + move || { + let encoder = TextEncoder::new(); + + // Collect metrics from our registry + #[cfg(feature = "system-metrics")] + let mut metric_families = registry.gather(); + #[cfg(not(feature = "system-metrics"))] + let metric_families = registry.gather(); + + // Add system metrics if available + #[cfg(feature = "system-metrics")] + if let Some(ref sys_metrics) = system_metrics { + // Update system metrics before collection + if let Err(e) = sys_metrics.update_metrics() { + tracing::warn!("Failed to update system metrics: {e}"); + } + + let sys_registry = sys_metrics.registry(); + let mut sys_families = sys_registry.gather(); + metric_families.append(&mut sys_families); + } + + // Encode metrics to string + encoder + .encode_to_string(&metric_families) + .unwrap_or_else(|e| { + tracing::error!("Failed to encode metrics: {e}"); + format!("Failed to encode metrics: {e}") + }) + } + } + + /// Start the Prometheus HTTP server + /// + /// # Errors + /// This function always returns Ok as errors are handled internally + pub async fn start( + self, + shutdown_signal: impl std::future::Future + Send + 'static, + ) -> crate::Result<()> { + // Create and start the exporter + let binding = self.config.bind_address; + let registry_clone = Arc::::clone(&self.registry); + + // Create a handler that exposes our registry + #[cfg(feature = "system-metrics")] + let metrics_handler = + Self::create_metrics_handler(registry_clone, self.system_metrics.clone()); + + #[cfg(not(feature = "system-metrics"))] + let metrics_handler = Self::create_metrics_handler(registry_clone); + + // Start the exporter in a background task + let path = self.config.metrics_path.clone(); + + // Create a channel for signaling the server task to shutdown + let (shutdown_tx, mut shutdown_rx) = tokio::sync::oneshot::channel::<()>(); + + // Spawn the server task + let server_handle = tokio::spawn(async move { + // We're using a simple HTTP server to expose our metrics + use std::io::{Read, Write}; + use std::net::TcpListener; + + // Create a TCP listener + let listener = match TcpListener::bind(binding) { + Ok(listener) => { + // Set non-blocking mode to allow for shutdown checking + if let Err(e) = listener.set_nonblocking(true) { + tracing::error!("Failed to set non-blocking mode: {e}"); + return; + } + listener + } + Err(e) => { + tracing::error!("Failed to bind TCP listener: {e}"); + return; + } + }; + tracing::info!("Started Prometheus server on {} at path {}", binding, path); + + // Accept connections with shutdown signal handling + loop { + // Check for shutdown signal + if shutdown_rx.try_recv().is_ok() { + tracing::info!("Shutdown signal received, stopping Prometheus server"); + break; + } + + // Try to accept a connection (non-blocking) + match listener.accept() { + Ok((mut stream, _)) => { + // Handle the connection + let mut buffer = [0; 1024]; + match stream.read(&mut buffer) { + Ok(0) => {} + Ok(bytes_read) => { + // Convert the buffer to a string + let request = String::from_utf8_lossy(&buffer[..bytes_read]); + + // Check if the request is for our metrics path + if request.contains(&format!("GET {path} HTTP")) { + // Get the metrics + let metrics = metrics_handler(); + + // Write the response + let response = format!( + "HTTP/1.1 200 OK\r\nContent-Type: text/plain\r\nContent-Length: {}\r\n\r\n{}", + metrics.len(), + metrics + ); + + if let Err(e) = stream.write_all(response.as_bytes()) { + tracing::error!("Failed to write response: {e}"); + } + } else { + // Write a 404 response + let response = "HTTP/1.1 404 Not Found\r\nContent-Type: text/plain\r\nContent-Length: 9\r\n\r\nNot Found"; + if let Err(e) = stream.write_all(response.as_bytes()) { + tracing::error!("Failed to write response: {e}"); + } + } + } + Err(e) => { + tracing::error!("Failed to read from stream: {e}"); + } + } + } + Err(ref e) if e.kind() == std::io::ErrorKind::WouldBlock => { + // No connection available, continue the loop + tokio::time::sleep(Duration::from_millis(10)).await; + } + Err(e) => { + tracing::error!("Failed to accept connection: {e}"); + // Add a small delay to prevent busy looping on persistent errors + tokio::time::sleep(Duration::from_millis(100)).await; + } + } + } + + tracing::info!("Prometheus server stopped"); + }); + + // Wait for the shutdown signal + shutdown_signal.await; + + // Signal the server to shutdown + let _ = shutdown_tx.send(()); + + // Wait for the server task to complete (with a timeout) + match tokio::time::timeout(Duration::from_secs(5), server_handle).await { + Ok(result) => { + if let Err(e) = result { + tracing::error!("Server task failed: {e}"); + } + } + Err(_) => { + tracing::warn!("Server shutdown timed out after 5 seconds"); + } + } + + Ok(()) + } +} + +/// Builder for easy Prometheus server setup +#[derive(Debug)] +pub struct PrometheusBuilder { + config: PrometheusConfig, +} + +impl PrometheusBuilder { + /// Create a new builder with default configuration + #[must_use] + pub fn new() -> Self { + Self { + config: PrometheusConfig::default(), + } + } + + /// Set the bind address + #[must_use] + pub const fn bind_address(mut self, addr: SocketAddr) -> Self { + self.config.bind_address = addr; + self + } + + /// Set the metrics path + #[must_use] + pub fn metrics_path>(mut self, path: S) -> Self { + self.config.metrics_path = path.into(); + self + } + + /// Enable or disable system metrics + #[cfg(feature = "system-metrics")] + #[must_use] + pub const fn system_metrics(mut self, enabled: bool) -> Self { + self.config.include_system_metrics = enabled; + self + } + + /// Set system metrics update interval + #[cfg(feature = "system-metrics")] + #[must_use] + pub const fn system_metrics_interval(mut self, seconds: u64) -> Self { + self.config.system_metrics_interval = seconds; + self + } + + /// Build the server with specific CDK metrics instance + /// + /// # Errors + /// Returns an error if system metrics cannot be created (when enabled) + pub fn build_with_cdk_metrics(self) -> crate::Result { + PrometheusServer::new(self.config) + } + + /// Build the server with custom registry + #[must_use] + pub fn build_with_registry(self, registry: Arc) -> PrometheusServer { + PrometheusServer::with_registry(self.config, registry) + } +} + +impl Default for PrometheusBuilder { + fn default() -> Self { + Self::new() + } +} diff --git a/crates/cdk-sql-common/Cargo.toml b/crates/cdk-sql-common/Cargo.toml index 7785ff4d8..c5b512cc1 100644 --- a/crates/cdk-sql-common/Cargo.toml +++ b/crates/cdk-sql-common/Cargo.toml @@ -16,10 +16,11 @@ default = ["mint", "wallet", "auth"] mint = ["cdk-common/mint"] wallet = ["cdk-common/wallet"] auth = ["cdk-common/auth"] - +prometheus = ["cdk-prometheus"] [dependencies] async-trait.workspace = true cdk-common = { workspace = true, features = ["test"] } +cdk-prometheus = { workspace = true, optional = true } bitcoin.workspace = true thiserror.workspace = true tracing.workspace = true diff --git a/crates/cdk-sql-common/src/mint/mod.rs b/crates/cdk-sql-common/src/mint/mod.rs index ca750e6fb..935e825dd 100644 --- a/crates/cdk-sql-common/src/mint/mod.rs +++ b/crates/cdk-sql-common/src/mint/mod.rs @@ -57,6 +57,8 @@ mod migrations; #[cfg(feature = "auth")] pub use auth::SQLMintAuthDatabase; +#[cfg(feature = "prometheus")] +use cdk_prometheus::METRICS; /// Mint SQL Database #[derive(Debug, Clone)] @@ -299,11 +301,27 @@ where type Err = Error; async fn commit(self: Box) -> Result<(), Error> { - self.inner.commit().await + let result = self.inner.commit().await; + #[cfg(feature = "prometheus")] + { + let success = result.is_ok(); + METRICS.record_mint_operation("transaction_commit", success); + METRICS.record_mint_operation_histogram("transaction_commit", success, 1.0); + } + + Ok(result?) } async fn rollback(self: Box) -> Result<(), Error> { - self.inner.rollback().await + let result = self.inner.rollback().await; + + #[cfg(feature = "prometheus")] + { + let success = result.is_ok(); + METRICS.record_mint_operation("transaction_rollback", success); + METRICS.record_mint_operation_histogram("transaction_rollback", success, 1.0); + } + Ok(result?) } } @@ -443,12 +461,14 @@ where async fn begin_transaction<'a>( &'a self, ) -> Result + Send + Sync + 'a>, Error> { - Ok(Box::new(SQLTransaction { + let tx = SQLTransaction { inner: ConnectionWithTransaction::new( self.pool.get().map_err(|e| Error::Database(Box::new(e)))?, ) .await?, - })) + }; + + Ok(Box::new(tx)) } async fn get_active_keyset_id(&self, unit: &CurrencyUnit) -> Result, Self::Err> { @@ -1072,35 +1092,58 @@ where type Err = Error; async fn get_mint_quote(&self, quote_id: &QuoteId) -> Result, Self::Err> { + #[cfg(feature = "prometheus")] + METRICS.inc_in_flight_requests("get_mint_quote"); + + #[cfg(feature = "prometheus")] + let start_time = std::time::Instant::now(); let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; - let payments = get_mint_quote_payments(&*conn, quote_id).await?; - let issuance = get_mint_quote_issuance(&*conn, quote_id).await?; + let result = async { + let payments = get_mint_quote_payments(&*conn, quote_id).await?; + let issuance = get_mint_quote_issuance(&*conn, quote_id).await?; - Ok(query( - r#" - SELECT - id, - amount, - unit, - request, - expiry, - request_lookup_id, - pubkey, - created_time, - amount_paid, - amount_issued, - payment_method, - request_lookup_id_kind - FROM - mint_quote - WHERE id = :id"#, - )? - .bind("id", quote_id.to_string()) - .fetch_one(&*conn) - .await? - .map(|row| sql_row_to_mint_quote(row, payments, issuance)) - .transpose()?) + query( + r#" + SELECT + id, + amount, + unit, + request, + expiry, + request_lookup_id, + pubkey, + created_time, + amount_paid, + amount_issued, + payment_method, + request_lookup_id_kind + FROM + mint_quote + WHERE id = :id"#, + )? + .bind("id", quote_id.to_string()) + .fetch_one(&*conn) + .await? + .map(|row| sql_row_to_mint_quote(row, payments, issuance)) + .transpose() + } + .await; + + #[cfg(feature = "prometheus")] + { + let success = result.is_ok(); + + METRICS.record_mint_operation("get_mint_quote", success); + METRICS.record_mint_operation_histogram( + "get_mint_quote", + success, + start_time.elapsed().as_secs_f64(), + ); + METRICS.dec_in_flight_requests("get_mint_quote"); + } + + result } async fn get_mint_quote_by_request( @@ -1228,35 +1271,59 @@ where &self, quote_id: &QuoteId, ) -> Result, Self::Err> { + #[cfg(feature = "prometheus")] + METRICS.inc_in_flight_requests("get_melt_quote"); + + #[cfg(feature = "prometheus")] + let start_time = std::time::Instant::now(); let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; - Ok(query( - r#" - SELECT - id, - unit, - amount, - request, - fee_reserve, - expiry, - state, - payment_preimage, - request_lookup_id, - created_time, - paid_time, - payment_method, - options, - request_lookup_id_kind - FROM - melt_quote - WHERE - id=:id - "#, - )? - .bind("id", quote_id.to_string()) - .fetch_one(&*conn) - .await? - .map(sql_row_to_melt_quote) - .transpose()?) + + let result = async { + query( + r#" + SELECT + id, + unit, + amount, + request, + fee_reserve, + expiry, + state, + payment_preimage, + request_lookup_id, + created_time, + paid_time, + payment_method, + options, + request_lookup_id_kind + FROM + melt_quote + WHERE + id=:id + "#, + )? + .bind("id", quote_id.to_string()) + .fetch_one(&*conn) + .await? + .map(sql_row_to_melt_quote) + .transpose() + } + .await; + + #[cfg(feature = "prometheus")] + { + let success = result.is_ok(); + + METRICS.record_mint_operation("get_melt_quote", success); + METRICS.record_mint_operation_histogram( + "get_melt_quote", + success, + start_time.elapsed().as_secs_f64(), + ); + METRICS.dec_in_flight_requests("get_melt_quote"); + } + + result } async fn get_melt_quotes(&self) -> Result, Self::Err> { @@ -1826,20 +1893,64 @@ where async fn begin_transaction<'a>( &'a self, ) -> Result + Send + Sync + 'a>, Error> { - Ok(Box::new(SQLTransaction { + let tx = SQLTransaction { inner: ConnectionWithTransaction::new( self.pool.get().map_err(|e| Error::Database(Box::new(e)))?, ) .await?, - })) + }; + + Ok(Box::new(tx)) } async fn get_mint_info(&self) -> Result { - Ok(self.fetch_from_config("mint_info").await?) + #[cfg(feature = "prometheus")] + METRICS.inc_in_flight_requests("get_mint_info"); + + #[cfg(feature = "prometheus")] + let start_time = std::time::Instant::now(); + + let result = self.fetch_from_config("mint_info").await; + + #[cfg(feature = "prometheus")] + { + let success = result.is_ok(); + + METRICS.record_mint_operation("get_mint_info", success); + METRICS.record_mint_operation_histogram( + "get_mint_info", + success, + start_time.elapsed().as_secs_f64(), + ); + METRICS.dec_in_flight_requests("get_mint_info"); + } + + Ok(result?) } async fn get_quote_ttl(&self) -> Result { - Ok(self.fetch_from_config("quote_ttl").await?) + #[cfg(feature = "prometheus")] + METRICS.inc_in_flight_requests("get_quote_ttl"); + + #[cfg(feature = "prometheus")] + let start_time = std::time::Instant::now(); + + let result = self.fetch_from_config("quote_ttl").await; + + #[cfg(feature = "prometheus")] + { + let success = result.is_ok(); + + METRICS.record_mint_operation("get_quote_ttl", success); + METRICS.record_mint_operation_histogram( + "get_quote_ttl", + success, + start_time.elapsed().as_secs_f64(), + ); + METRICS.dec_in_flight_requests("get_quote_ttl"); + } + + Ok(result?) } } diff --git a/crates/cdk-sql-common/src/pool.rs b/crates/cdk-sql-common/src/pool.rs index ebcac59f3..9315a081b 100644 --- a/crates/cdk-sql-common/src/pool.rs +++ b/crates/cdk-sql-common/src/pool.rs @@ -6,9 +6,10 @@ use std::fmt::Debug; use std::ops::{Deref, DerefMut}; use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering}; use std::sync::{Arc, Condvar, Mutex}; -use std::time::Duration; +use std::time::{Duration, Instant}; -use tokio::time::Instant; +#[cfg(feature = "prometheus")] +use cdk_prometheus::metrics::METRICS; use crate::database::DatabaseConnector; @@ -86,6 +87,8 @@ where { resource: Option<(Arc, RM::Connection)>, pool: Arc>, + #[cfg(feature = "prometheus")] + start_time: Instant, } impl Debug for PooledResource @@ -105,7 +108,16 @@ where if let Some(resource) = self.resource.take() { let mut active_resource = self.pool.queue.lock().expect("active_resource"); active_resource.push(resource); - self.pool.in_use.fetch_sub(1, Ordering::AcqRel); + let _in_use = self.pool.in_use.fetch_sub(1, Ordering::AcqRel); + + #[cfg(feature = "prometheus")] + { + METRICS.set_db_connections_active(_in_use as i64); + + let duration = self.start_time.elapsed().as_secs_f64(); + + METRICS.record_db_operation(duration, "drop"); + } // Notify a waiting thread self.pool.waiter.notify_one(); @@ -155,6 +167,18 @@ where self.get_timeout(self.default_timeout) } + /// Increments the in_use connection counter and updates the metric + fn increment_connection_counter(&self) -> usize { + let in_use = self.in_use.fetch_add(1, Ordering::AcqRel); + + #[cfg(feature = "prometheus")] + { + METRICS.set_db_connections_active(in_use as i64); + } + + in_use + } + /// Get a new resource or fail after timeout is reached. /// /// This function will return a free resource or create a new one if there is still room for it; @@ -171,18 +195,20 @@ where if let Some((stale, resource)) = resources.pop() { if !stale.load(Ordering::SeqCst) { drop(resources); - self.in_use.fetch_add(1, Ordering::AcqRel); + self.increment_connection_counter(); return Ok(PooledResource { resource: Some((stale, resource)), pool: self.clone(), + #[cfg(feature = "prometheus")] + start_time: Instant::now(), }); } } if self.in_use.load(Ordering::Relaxed) < self.max_size { drop(resources); - self.in_use.fetch_add(1, Ordering::AcqRel); + self.increment_connection_counter(); let stale: Arc = Arc::new(false.into()); return Ok(PooledResource { @@ -191,6 +217,8 @@ where RM::new_resource(&self.config, stale, timeout)?, )), pool: self.clone(), + #[cfg(feature = "prometheus")] + start_time: Instant::now(), }); } diff --git a/crates/cdk-sqlite/Cargo.toml b/crates/cdk-sqlite/Cargo.toml index 094005f70..5ffd314d6 100644 --- a/crates/cdk-sqlite/Cargo.toml +++ b/crates/cdk-sqlite/Cargo.toml @@ -17,10 +17,11 @@ mint = ["cdk-common/mint", "cdk-sql-common/mint"] wallet = ["cdk-common/wallet", "cdk-sql-common/wallet"] auth = ["cdk-common/auth", "cdk-sql-common/auth"] sqlcipher = ["rusqlite/bundled-sqlcipher"] - +prometheus = ["cdk-sql-common/prometheus", "cdk-prometheus"] [dependencies] async-trait.workspace = true cdk-common = { workspace = true, features = ["test"] } +cdk-prometheus = { workspace = true, optional = true } bitcoin.workspace = true cdk-sql-common = { workspace = true } rusqlite = { version = "0.31", features = ["bundled"]} diff --git a/crates/cdk/Cargo.toml b/crates/cdk/Cargo.toml index dec29d19e..529dfebbd 100644 --- a/crates/cdk/Cargo.toml +++ b/crates/cdk/Cargo.toml @@ -20,7 +20,7 @@ bip353 = ["dep:trust-dns-resolver"] swagger = ["mint", "dep:utoipa", "cdk-common/swagger"] bench = [] http_subscription = [] - +prometheus = ["dep:cdk-prometheus"] [dependencies] cdk-common.workspace = true @@ -44,7 +44,7 @@ utoipa = { workspace = true, optional = true } uuid.workspace = true jsonwebtoken = { workspace = true, optional = true } trust-dns-resolver = { version = "0.23.2", optional = true } - +cdk-prometheus = {workspace = true, optional = true} # -Z minimal-versions sync_wrapper = "0.1.2" bech32 = "0.9.1" diff --git a/crates/cdk/src/mint/builder.rs b/crates/cdk/src/mint/builder.rs index b0cc19033..765ecc9fa 100644 --- a/crates/cdk/src/mint/builder.rs +++ b/crates/cdk/src/mint/builder.rs @@ -268,7 +268,6 @@ impl MintBuilder { self.payment_processors.insert(key, payment_processor); Ok(()) } - /// Sets the input fee ppk for a given unit /// /// The unit **MUST** already have been added with a ln backend diff --git a/crates/cdk/src/mint/issue/mod.rs b/crates/cdk/src/mint/issue/mod.rs index 1e5767db3..f3965ee33 100644 --- a/crates/cdk/src/mint/issue/mod.rs +++ b/crates/cdk/src/mint/issue/mod.rs @@ -10,6 +10,8 @@ use cdk_common::{ MintQuoteBolt11Response, MintQuoteBolt12Request, MintQuoteBolt12Response, MintQuoteState, MintRequest, MintResponse, NotificationPayload, PaymentMethod, PublicKey, }; +#[cfg(feature = "prometheus")] +use cdk_prometheus::METRICS; use tracing::instrument; use crate::mint::Verification; @@ -187,130 +189,147 @@ impl Mint { &self, mint_quote_request: MintQuoteRequest, ) -> Result { - let unit: CurrencyUnit; - let amount; - let pubkey; - let payment_method; - - let create_invoice_response = match mint_quote_request { - MintQuoteRequest::Bolt11(bolt11_request) => { - unit = bolt11_request.unit; - amount = Some(bolt11_request.amount); - pubkey = bolt11_request.pubkey; - payment_method = PaymentMethod::Bolt11; - - self.check_mint_request_acceptable( - Some(bolt11_request.amount), - &unit, - &payment_method, - ) - .await?; + #[cfg(feature = "prometheus")] + METRICS.inc_in_flight_requests("get_mint_quote"); + + let result = async { + let unit: CurrencyUnit; + let amount; + let pubkey; + let payment_method; + + let create_invoice_response = match mint_quote_request { + MintQuoteRequest::Bolt11(bolt11_request) => { + unit = bolt11_request.unit; + amount = Some(bolt11_request.amount); + pubkey = bolt11_request.pubkey; + payment_method = PaymentMethod::Bolt11; + + self.check_mint_request_acceptable( + Some(bolt11_request.amount), + &unit, + &payment_method, + ) + .await?; - let ln = self.get_payment_processor(unit.clone(), PaymentMethod::Bolt11)?; + let ln = self.get_payment_processor(unit.clone(), PaymentMethod::Bolt11)?; - let mint_ttl = self.localstore.get_quote_ttl().await?.mint_ttl; + let mint_ttl = self.localstore.get_quote_ttl().await?.mint_ttl; - let quote_expiry = unix_time() + mint_ttl; + let quote_expiry = unix_time() + mint_ttl; - let settings = ln.get_settings().await?; - let settings: Bolt11Settings = serde_json::from_value(settings)?; + let settings = ln.get_settings().await?; + let settings: Bolt11Settings = serde_json::from_value(settings)?; - let description = bolt11_request.description; + let description = bolt11_request.description; - if description.is_some() && !settings.invoice_description { - tracing::error!("Backend does not support invoice description"); - return Err(Error::InvoiceDescriptionUnsupported); - } + if description.is_some() && !settings.invoice_description { + tracing::error!("Backend does not support invoice description"); + return Err(Error::InvoiceDescriptionUnsupported); + } - let bolt11_options = Bolt11IncomingPaymentOptions { - description, - amount: bolt11_request.amount, - unix_expiry: Some(quote_expiry), - }; + let bolt11_options = Bolt11IncomingPaymentOptions { + description, + amount: bolt11_request.amount, + unix_expiry: Some(quote_expiry), + }; - let incoming_options = IncomingPaymentOptions::Bolt11(bolt11_options); + let incoming_options = IncomingPaymentOptions::Bolt11(bolt11_options); - ln.create_incoming_payment_request(&unit, incoming_options) - .await - .map_err(|err| { - tracing::error!("Could not create invoice: {}", err); - Error::InvalidPaymentRequest - })? - } - MintQuoteRequest::Bolt12(bolt12_request) => { - unit = bolt12_request.unit; - amount = bolt12_request.amount; - pubkey = Some(bolt12_request.pubkey); - payment_method = PaymentMethod::Bolt12; + ln.create_incoming_payment_request(&unit, incoming_options) + .await + .map_err(|err| { + tracing::error!("Could not create invoice: {}", err); + Error::InvalidPaymentRequest + })? + } + MintQuoteRequest::Bolt12(bolt12_request) => { + unit = bolt12_request.unit; + amount = bolt12_request.amount; + pubkey = Some(bolt12_request.pubkey); + payment_method = PaymentMethod::Bolt12; - self.check_mint_request_acceptable(amount, &unit, &payment_method) - .await?; + self.check_mint_request_acceptable(amount, &unit, &payment_method) + .await?; - let ln = self.get_payment_processor(unit.clone(), payment_method.clone())?; + let ln = self.get_payment_processor(unit.clone(), payment_method.clone())?; - let description = bolt12_request.description; + let description = bolt12_request.description; - let bolt12_options = Bolt12IncomingPaymentOptions { - description, - amount, - unix_expiry: None, - }; + let bolt12_options = Bolt12IncomingPaymentOptions { + description, + amount, + unix_expiry: None, + }; - let incoming_options = IncomingPaymentOptions::Bolt12(Box::new(bolt12_options)); + let incoming_options = IncomingPaymentOptions::Bolt12(Box::new(bolt12_options)); - ln.create_incoming_payment_request(&unit, incoming_options) - .await - .map_err(|err| { - tracing::error!("Could not create invoice: {}", err); - Error::InvalidPaymentRequest - })? - } - }; + ln.create_incoming_payment_request(&unit, incoming_options) + .await + .map_err(|err| { + tracing::error!("Could not create invoice: {}", err); + Error::InvalidPaymentRequest + })? + } + }; + + let quote = MintQuote::new( + None, + create_invoice_response.request.to_string(), + unit.clone(), + amount, + create_invoice_response.expiry.unwrap_or(0), + create_invoice_response.request_lookup_id.clone(), + pubkey, + Amount::ZERO, + Amount::ZERO, + payment_method.clone(), + unix_time(), + vec![], + vec![], + ); - let quote = MintQuote::new( - None, - create_invoice_response.request.to_string(), - unit.clone(), - amount, - create_invoice_response.expiry.unwrap_or(0), - create_invoice_response.request_lookup_id.clone(), - pubkey, - Amount::ZERO, - Amount::ZERO, - payment_method.clone(), - unix_time(), - vec![], - vec![], - ); - - tracing::debug!( - "New {} mint quote {} for {:?} {} with request id {:?}", - payment_method, - quote.id, - amount, - unit, - create_invoice_response.request_lookup_id.to_string(), - ); + tracing::debug!( + "New {} mint quote {} for {:?} {} with request id {:?}", + payment_method, + quote.id, + amount, + unit, + create_invoice_response.request_lookup_id.to_string(), + ); - let mut tx = self.localstore.begin_transaction().await?; - tx.add_mint_quote(quote.clone()).await?; - tx.commit().await?; + let mut tx = self.localstore.begin_transaction().await?; + tx.add_mint_quote(quote.clone()).await?; + tx.commit().await?; - match payment_method { - PaymentMethod::Bolt11 => { - let res: MintQuoteBolt11Response = quote.clone().into(); - self.pubsub_manager - .broadcast(NotificationPayload::MintQuoteBolt11Response(res)); + match payment_method { + PaymentMethod::Bolt11 => { + let res: MintQuoteBolt11Response = quote.clone().into(); + self.pubsub_manager + .broadcast(NotificationPayload::MintQuoteBolt11Response(res)); + } + PaymentMethod::Bolt12 => { + let res: MintQuoteBolt12Response = quote.clone().try_into()?; + self.pubsub_manager + .broadcast(NotificationPayload::MintQuoteBolt12Response(res)); + } + PaymentMethod::Custom(_) => {} } - PaymentMethod::Bolt12 => { - let res: MintQuoteBolt12Response = quote.clone().try_into()?; - self.pubsub_manager - .broadcast(NotificationPayload::MintQuoteBolt12Response(res)); + + quote.try_into() + } + .await; + + #[cfg(feature = "prometheus")] + { + METRICS.dec_in_flight_requests("get_mint_quote"); + METRICS.record_mint_operation("get_mint_quote", result.is_ok()); + if result.is_err() { + METRICS.record_error(); } - PaymentMethod::Custom(_) => {} } - quote.try_into() + result } /// Retrieves all mint quotes from the database @@ -320,8 +339,25 @@ impl Mint { /// * `Error` if database access fails #[instrument(skip_all)] pub async fn mint_quotes(&self) -> Result, Error> { - let quotes = self.localstore.get_mint_quotes().await?; - Ok(quotes) + #[cfg(feature = "prometheus")] + METRICS.inc_in_flight_requests("mint_quotes"); + + let result = async { + let quotes = self.localstore.get_mint_quotes().await?; + Ok(quotes) + } + .await; + + #[cfg(feature = "prometheus")] + { + METRICS.dec_in_flight_requests("mint_quotes"); + METRICS.record_mint_operation("mint_quotes", result.is_ok()); + if result.is_err() { + METRICS.record_error(); + } + } + + result } /// Removes a mint quote from the database @@ -334,11 +370,27 @@ impl Mint { /// * `Error` if the quote doesn't exist or removal fails #[instrument(skip_all)] pub async fn remove_mint_quote(&self, quote_id: &QuoteId) -> Result<(), Error> { - let mut tx = self.localstore.begin_transaction().await?; - tx.remove_mint_quote(quote_id).await?; - tx.commit().await?; + #[cfg(feature = "prometheus")] + METRICS.inc_in_flight_requests("remove_mint_quote"); + + let result = async { + let mut tx = self.localstore.begin_transaction().await?; + tx.remove_mint_quote(quote_id).await?; + tx.commit().await?; + Ok(()) + } + .await; - Ok(()) + #[cfg(feature = "prometheus")] + { + METRICS.dec_in_flight_requests("remove_mint_quote"); + METRICS.record_mint_operation("remove_mint_quote", result.is_ok()); + if result.is_err() { + METRICS.record_error(); + } + } + + result } /// Marks a mint quote as paid based on the payment request ID @@ -357,33 +409,48 @@ impl Mint { &self, wait_payment_response: WaitPaymentResponse, ) -> Result<(), Error> { - if wait_payment_response.payment_amount == Amount::ZERO { - tracing::warn!( - "Received payment response with 0 amount with payment id {}.", - wait_payment_response.payment_id.to_string() - ); + #[cfg(feature = "prometheus")] + METRICS.inc_in_flight_requests("pay_mint_quote_for_request_id"); + let result = async { + if wait_payment_response.payment_amount == Amount::ZERO { + tracing::warn!( + "Received payment response with 0 amount with payment id {}.", + wait_payment_response.payment_id.to_string() + ); + return Err(Error::AmountUndefined); + } - return Err(Error::AmountUndefined); - } + let mut tx = self.localstore.begin_transaction().await?; - let mut tx = self.localstore.begin_transaction().await?; + if let Ok(Some(mint_quote)) = tx + .get_mint_quote_by_request_lookup_id(&wait_payment_response.payment_identifier) + .await + { + self.pay_mint_quote(&mut tx, &mint_quote, wait_payment_response) + .await?; + } else { + tracing::warn!( + "Could not get request for request lookup id {:?}.", + wait_payment_response.payment_identifier + ); + } - if let Ok(Some(mint_quote)) = tx - .get_mint_quote_by_request_lookup_id(&wait_payment_response.payment_identifier) - .await - { - self.pay_mint_quote(&mut tx, &mint_quote, wait_payment_response) - .await?; - } else { - tracing::warn!( - "Could not get request for request lookup id {:?}.", - wait_payment_response.payment_identifier - ); + tx.commit().await?; + + Ok(()) } + .await; - tx.commit().await?; + #[cfg(feature = "prometheus")] + { + METRICS.dec_in_flight_requests("pay_mint_quote_for_request_id"); + METRICS.record_mint_operation("pay_mint_quote_for_request_id", result.is_ok()); + if result.is_err() { + METRICS.record_error(); + } + } - Ok(()) + result } /// Marks a specific mint quote as paid @@ -405,8 +472,30 @@ impl Mint { mint_quote: &MintQuote, wait_payment_response: WaitPaymentResponse, ) -> Result<(), Error> { - Self::handle_mint_quote_payment(tx, mint_quote, wait_payment_response, &self.pubsub_manager) + #[cfg(feature = "prometheus")] + METRICS.inc_in_flight_requests("pay_mint_quote"); + + let result = async { + Self::handle_mint_quote_payment( + tx, + mint_quote, + wait_payment_response, + &self.pubsub_manager, + ) .await + } + .await; + + #[cfg(feature = "prometheus")] + { + METRICS.dec_in_flight_requests("pay_mint_quote"); + METRICS.record_mint_operation("pay_mint_quote", result.is_ok()); + if result.is_err() { + METRICS.record_error(); + } + } + + result } /// Checks the status of a mint quote and updates it if necessary @@ -422,17 +511,33 @@ impl Mint { /// * `Error` if the quote doesn't exist or checking fails #[instrument(skip(self))] pub async fn check_mint_quote(&self, quote_id: &QuoteId) -> Result { - let mut quote = self - .localstore - .get_mint_quote(quote_id) - .await? - .ok_or(Error::UnknownQuote)?; + #[cfg(feature = "prometheus")] + METRICS.inc_in_flight_requests("check_mint_quote"); + let result = async { + let mut quote = self + .localstore + .get_mint_quote(quote_id) + .await? + .ok_or(Error::UnknownQuote)?; + + if quote.payment_method == PaymentMethod::Bolt11 { + self.check_mint_quote_paid(&mut quote).await?; + } + + quote.try_into() + } + .await; - if quote.payment_method == PaymentMethod::Bolt11 { - self.check_mint_quote_paid(&mut quote).await?; + #[cfg(feature = "prometheus")] + { + METRICS.dec_in_flight_requests("check_mint_quote"); + METRICS.record_mint_operation("check_mint_quote", result.is_ok()); + if result.is_err() { + METRICS.record_error(); + } } - quote.try_into() + result } /// Processes a mint request to issue new tokens @@ -456,15 +561,18 @@ impl Mint { &self, mint_request: MintRequest, ) -> Result { - let mut mint_quote = self - .localstore - .get_mint_quote(&mint_request.quote) - .await? - .ok_or(Error::UnknownQuote)?; - if mint_quote.payment_method == PaymentMethod::Bolt11 { - self.check_mint_quote_paid(&mut mint_quote).await?; - } - + #[cfg(feature = "prometheus")] + METRICS.inc_in_flight_requests("process_mint_request"); + let result = async { + let mut mint_quote = self + .localstore + .get_mint_quote(&mint_request.quote) + .await? + .ok_or(Error::UnknownQuote)?; + + if mint_quote.payment_method == PaymentMethod::Bolt11 { + self.check_mint_quote_paid(&mut mint_quote).await?; + } // get the blind signatures before having starting the db transaction, if there are any // rollbacks this blind_signatures will be lost, and the signature is stateless. It is not a // good idea to call an external service (which is really a trait, it could be anything @@ -504,10 +612,10 @@ impl Mint { PaymentMethod::Bolt12 => { if mint_quote.amount_issued() > mint_quote.amount_paid() { tracing::error!( - "Quote state should not be issued if issued {} is > paid {}.", - mint_quote.amount_issued(), - mint_quote.amount_paid() - ); + "Quote state should not be issued if issued {} is > paid {}.", + mint_quote.amount_issued(), + mint_quote.amount_paid() + ); return Err(Error::UnpaidQuote); } mint_quote.amount_paid() - mint_quote.amount_issued() @@ -565,7 +673,7 @@ impl Mint { &blind_signatures, Some(mint_request.quote.clone()), ) - .await?; + .await?; let amount_issued = mint_request.total_amount()?; @@ -582,4 +690,16 @@ impl Mint { signatures: blind_signatures, }) } + .await; + + #[cfg(feature = "prometheus")] + { + METRICS.dec_in_flight_requests("process_mint_request"); + METRICS.record_mint_operation("process_mint_request", result.is_ok()); + if result.is_err() { + METRICS.record_error(); + } + } + result + } } diff --git a/crates/cdk/src/mint/melt.rs b/crates/cdk/src/mint/melt.rs index 099a6544d..aba1ee488 100644 --- a/crates/cdk/src/mint/melt.rs +++ b/crates/cdk/src/mint/melt.rs @@ -13,6 +13,8 @@ use cdk_common::payment::{ }; use cdk_common::quote_id::QuoteId; use cdk_common::{MeltOptions, MeltQuoteBolt12Request}; +#[cfg(feature = "prometheus")] +use cdk_prometheus::METRICS; use lightning::offers::offer::Offer; use tracing::instrument; @@ -131,6 +133,8 @@ impl Mint { &self, melt_request: &MeltQuoteBolt11Request, ) -> Result, Error> { + #[cfg(feature = "prometheus")] + METRICS.inc_in_flight_requests("get_melt_bolt11_quote"); let MeltQuoteBolt11Request { request, unit, @@ -183,6 +187,12 @@ impl Mint { err ); + #[cfg(feature = "prometheus")] + { + METRICS.dec_in_flight_requests("get_melt_bolt11_quote"); + METRICS.record_mint_operation("get_melt_bolt11_quote", false); + METRICS.record_error(); + } Error::UnsupportedUnit })?; @@ -315,6 +325,12 @@ impl Mint { tx.add_melt_quote(quote.clone()).await?; tx.commit().await?; + #[cfg(feature = "prometheus")] + { + METRICS.dec_in_flight_requests("get_melt_bolt11_quote"); + METRICS.record_mint_operation("get_melt_bolt11_quote", true); + } + Ok(quote.into()) } @@ -324,20 +340,50 @@ impl Mint { &self, quote_id: &QuoteId, ) -> Result, Error> { - let quote = self - .localstore - .get_melt_quote(quote_id) - .await? - .ok_or(Error::UnknownQuote)?; + #[cfg(feature = "prometheus")] + METRICS.inc_in_flight_requests("check_melt_quote"); + let quote = match self.localstore.get_melt_quote(quote_id).await { + Ok(Some(quote)) => quote, + Ok(None) => { + #[cfg(feature = "prometheus")] + { + METRICS.dec_in_flight_requests("check_melt_quote"); + METRICS.record_mint_operation("check_melt_quote", false); + METRICS.record_error(); + } + return Err(Error::UnknownQuote); + } + Err(err) => { + #[cfg(feature = "prometheus")] + { + METRICS.dec_in_flight_requests("check_melt_quote"); + METRICS.record_mint_operation("check_melt_quote", false); + METRICS.record_error(); + } + return Err(err.into()); + } + }; - let blind_signatures = self + let blind_signatures = match self .localstore .get_blind_signatures_for_quote(quote_id) - .await?; + .await + { + Ok(signatures) => signatures, + Err(err) => { + #[cfg(feature = "prometheus")] + { + METRICS.dec_in_flight_requests("check_melt_quote"); + METRICS.record_mint_operation("check_melt_quote", false); + METRICS.record_error(); + } + return Err(err.into()); + } + }; let change = (!blind_signatures.is_empty()).then_some(blind_signatures); - Ok(MeltQuoteBolt11Response { + let response = MeltQuoteBolt11Response { quote: quote.id, paid: Some(quote.state == MeltQuoteState::Paid), state: quote.state, @@ -348,7 +394,15 @@ impl Mint { change, request: Some(quote.request.to_string()), unit: Some(quote.unit.clone()), - }) + }; + + #[cfg(feature = "prometheus")] + { + METRICS.dec_in_flight_requests("check_melt_quote"); + METRICS.record_mint_operation("check_melt_quote", true); + } + + Ok(response) } /// Get melt quotes @@ -520,6 +574,9 @@ impl Mint { &self, melt_request: &MeltRequest, ) -> Result, Error> { + #[cfg(feature = "prometheus")] + METRICS.inc_in_flight_requests("melt_bolt11"); + use std::sync::Arc; async fn check_payment_state( ln: Arc + Send + Sync>, @@ -543,21 +600,43 @@ impl Mint { let mut tx = self.localstore.begin_transaction().await?; - let (proof_writer, quote) = self + let (proof_writer, quote) = match self .verify_melt_request(&mut tx, verification, melt_request) .await - .map_err(|err| { + { + Ok(result) => result, + Err(err) => { tracing::debug!("Error attempting to verify melt quote: {}", err); - err - })?; - let settled_internally_amount = self + #[cfg(feature = "prometheus")] + { + METRICS.dec_in_flight_requests("melt_bolt11"); + METRICS.record_mint_operation("melt_bolt11", false); + METRICS.record_error(); + } + + return Err(err); + } + }; + + let settled_internally_amount = match self .handle_internal_melt_mint(&mut tx, "e, melt_request) .await - .map_err(|err| { + { + Ok(amount) => amount, + Err(err) => { tracing::error!("Attempting to settle internally failed: {}", err); - err - })?; + + #[cfg(feature = "prometheus")] + { + METRICS.dec_in_flight_requests("melt_bolt11"); + METRICS.record_mint_operation("melt_bolt11", false); + METRICS.record_error(); + } + + return Err(err); + } + }; let (tx, preimage, amount_spent_quote_unit, quote) = match settled_internally_amount { Some(amount_spent) => (tx, None, amount_spent, quote), @@ -669,6 +748,14 @@ impl Mint { melt_request.quote() ); proof_writer.rollback().await?; + + #[cfg(feature = "prometheus")] + { + METRICS.dec_in_flight_requests("melt_bolt11"); + METRICS.record_mint_operation("melt_bolt11", false); + METRICS.record_error(); + } + return Err(Error::PaymentFailed); } MeltQuoteState::Pending => { @@ -677,6 +764,13 @@ impl Mint { melt_request.quote() ); proof_writer.commit(); + #[cfg(feature = "prometheus")] + { + METRICS.dec_in_flight_requests("melt_bolt11"); + METRICS.record_mint_operation("melt_bolt11", false); + METRICS.record_error(); + } + return Err(Error::PendingQuote); } } @@ -716,7 +810,7 @@ impl Mint { // If we made it here the payment has been made. // We process the melt burning the inputs and returning change - let res = self + let res = match self .process_melt_request( tx, proof_writer, @@ -726,10 +820,27 @@ impl Mint { amount_spent_quote_unit, ) .await - .map_err(|err| { + { + Ok(response) => response, + Err(err) => { tracing::error!("Could not process melt request: {}", err); - err - })?; + + #[cfg(feature = "prometheus")] + { + METRICS.dec_in_flight_requests("melt_bolt11"); + METRICS.record_mint_operation("melt_bolt11", false); + METRICS.record_error(); + } + + return Err(err); + } + }; + + #[cfg(feature = "prometheus")] + { + METRICS.dec_in_flight_requests("melt_bolt11"); + METRICS.record_mint_operation("melt_bolt11", true); + } Ok(res) } @@ -747,11 +858,20 @@ impl Mint { payment_preimage: Option, total_spent: Amount, ) -> Result, Error> { + #[cfg(feature = "prometheus")] + METRICS.inc_in_flight_requests("process_melt_request"); + let input_ys = melt_request.inputs().ys()?; - proof_writer + let update_proof_states_result = proof_writer .update_proofs_states(&mut tx, &input_ys, State::Spent) - .await?; + .await; + + if update_proof_states_result.is_err() { + #[cfg(feature = "prometheus")] + self.record_melt_quote_failure("process_melt_request"); + return Err(update_proof_states_result.err().unwrap()); + } tx.update_melt_quote_state( melt_request.quote(), @@ -853,7 +973,6 @@ impl Mint { change.clone(), MeltQuoteState::Paid, ); - tracing::debug!( "Melt for quote {} completed total spent {}, total inputs: {}, change given: {}", quote.id, @@ -865,8 +984,7 @@ impl Mint { .expect("Change cannot overflow")) .unwrap_or_default() ); - - Ok(MeltQuoteBolt11Response { + let response = MeltQuoteBolt11Response { amount: quote.amount, paid: Some(true), payment_preimage, @@ -877,6 +995,21 @@ impl Mint { expiry: quote.expiry, request: Some(quote.request.to_string()), unit: Some(quote.unit.clone()), - }) + }; + + #[cfg(feature = "prometheus")] + { + METRICS.dec_in_flight_requests("process_melt_request"); + METRICS.record_mint_operation("process_melt_request", true); + } + + Ok(response) + } + + #[cfg(feature = "prometheus")] + fn record_melt_quote_failure(&self, operation: &str) { + METRICS.dec_in_flight_requests(operation); + METRICS.record_mint_operation(operation, false); + METRICS.record_error(); } } diff --git a/crates/cdk/src/mint/mod.rs b/crates/cdk/src/mint/mod.rs index ec89e81b6..2918fcbea 100644 --- a/crates/cdk/src/mint/mod.rs +++ b/crates/cdk/src/mint/mod.rs @@ -14,6 +14,8 @@ use cdk_common::nuts::{self, BlindSignature, BlindedMessage, CurrencyUnit, Id, K use cdk_common::payment::WaitPaymentResponse; pub use cdk_common::quote_id::QuoteId; use cdk_common::secret; +#[cfg(feature = "prometheus")] +use cdk_prometheus::global; use cdk_signatory::signatory::{Signatory, SignatoryKeySet}; use futures::StreamExt; #[cfg(feature = "auth")] @@ -724,41 +726,66 @@ impl Mint { #[tracing::instrument(skip_all)] pub async fn blind_sign( &self, - blinded_messages: Vec, + blinded_message: Vec, ) -> Result, Error> { - self.signatory.blind_sign(blinded_messages).await + #[cfg(feature = "prometheus")] + global::inc_in_flight_requests("blind_sign"); + + let result = self.signatory.blind_sign(blinded_message).await; + + #[cfg(feature = "prometheus")] + { + global::dec_in_flight_requests("blind_sign"); + global::record_mint_operation("blind_sign", result.is_ok()); + } + + result } /// Verify [`Proof`] meets conditions and is signed #[tracing::instrument(skip_all)] pub async fn verify_proofs(&self, proofs: Proofs) -> Result<(), Error> { - proofs - .iter() - .map(|proof| { - // Check if secret is a nut10 secret with conditions - if let Ok(secret) = - <&secret::Secret as TryInto>::try_into(&proof.secret) - { - // Checks and verifies known secret kinds. - // If it is an unknown secret kind it will be treated as a normal secret. - // Spending conditions will **not** be check. It is up to the wallet to ensure - // only supported secret kinds are used as there is no way for the mint to - // enforce only signing supported secrets as they are blinded at - // that point. - match secret.kind() { - Kind::P2PK => { - proof.verify_p2pk()?; - } - Kind::HTLC => { - proof.verify_htlc()?; + #[cfg(feature = "prometheus")] + global::inc_in_flight_requests("verify_proofs"); + + let result = async { + proofs + .iter() + .map(|proof| { + // Check if secret is a nut10 secret with conditions + if let Ok(secret) = + <&secret::Secret as TryInto>::try_into(&proof.secret) + { + // Checks and verifies known secret kinds. + // If it is an unknown secret kind it will be treated as a normal secret. + // Spending conditions will **not** be check. It is up to the wallet to ensure + // only supported secret kinds are used as there is no way for the mint to + // enforce only signing supported secrets as they are blinded at + // that point. + match secret.kind() { + Kind::P2PK => { + proof.verify_p2pk()?; + } + Kind::HTLC => { + proof.verify_htlc()?; + } } } - } - Ok(()) - }) - .collect::, Error>>()?; + Ok(()) + }) + .collect::, Error>>()?; + + self.signatory.verify_proofs(proofs).await + } + .await; - self.signatory.verify_proofs(proofs).await + #[cfg(feature = "prometheus")] + { + global::dec_in_flight_requests("verify_proofs"); + global::record_mint_operation("verify_proofs", result.is_ok()); + } + + result } /// Verify melt request is valid @@ -836,61 +863,92 @@ impl Mint { /// Restore #[instrument(skip_all)] pub async fn restore(&self, request: RestoreRequest) -> Result { - let output_len = request.outputs.len(); + #[cfg(feature = "prometheus")] + global::inc_in_flight_requests("restore"); - let mut outputs = Vec::with_capacity(output_len); - let mut signatures = Vec::with_capacity(output_len); + let result = async { + let output_len = request.outputs.len(); - let blinded_message: Vec = - request.outputs.iter().map(|b| b.blinded_secret).collect(); + let mut outputs = Vec::with_capacity(output_len); + let mut signatures = Vec::with_capacity(output_len); - let blinded_signatures = self - .localstore - .get_blind_signatures(&blinded_message) - .await?; + let blinded_message: Vec = + request.outputs.iter().map(|b| b.blinded_secret).collect(); + + let blinded_signatures = self + .localstore + .get_blind_signatures(&blinded_message) + .await?; - assert_eq!(blinded_signatures.len(), output_len); + assert_eq!(blinded_signatures.len(), output_len); - for (blinded_message, blinded_signature) in - request.outputs.into_iter().zip(blinded_signatures) - { - if let Some(blinded_signature) = blinded_signature { - outputs.push(blinded_message); - signatures.push(blinded_signature); + for (blinded_message, blinded_signature) in + request.outputs.into_iter().zip(blinded_signatures) + { + if let Some(blinded_signature) = blinded_signature { + outputs.push(blinded_message); + signatures.push(blinded_signature); + } } + + Ok(RestoreResponse { + outputs, + signatures: signatures.clone(), + promises: Some(signatures), + }) } + .await; - Ok(RestoreResponse { - outputs, - signatures: signatures.clone(), - promises: Some(signatures), - }) + #[cfg(feature = "prometheus")] + { + global::dec_in_flight_requests("restore"); + global::record_mint_operation("restore", result.is_ok()); + } + + result } /// Get the total amount issed by keyset #[instrument(skip_all)] pub async fn total_issued(&self) -> Result, Error> { - let keysets = self.keysets().keysets; + #[cfg(feature = "prometheus")] + global::inc_in_flight_requests("total_issued"); - let mut total_issued = HashMap::new(); + let result = async { + let keysets = self.keysets().keysets; - for keyset in keysets { - let blinded = self - .localstore - .get_blind_signatures_for_keyset(&keyset.id) - .await?; + let mut total_issued = HashMap::new(); + + for keyset in keysets { + let blinded = self + .localstore + .get_blind_signatures_for_keyset(&keyset.id) + .await?; - let total = Amount::try_sum(blinded.iter().map(|b| b.amount))?; + let total = Amount::try_sum(blinded.iter().map(|b| b.amount))?; - total_issued.insert(keyset.id, total); + total_issued.insert(keyset.id, total); + } + + Ok(total_issued) } + .await; - Ok(total_issued) + #[cfg(feature = "prometheus")] + { + global::dec_in_flight_requests("total_issued"); + global::record_mint_operation("total_issued", result.is_ok()); + } + + result } /// Total redeemed for keyset #[instrument(skip_all)] pub async fn total_redeemed(&self) -> Result, Error> { + #[cfg(feature = "prometheus")] + global::inc_in_flight_requests("total_redeemed"); + let keysets = self.signatory.keysets().await?; let mut total_redeemed = HashMap::new(); @@ -909,6 +967,9 @@ impl Mint { total_redeemed.insert(keyset.id, total_spent); } + #[cfg(feature = "prometheus")] + global::dec_in_flight_requests("total_redeemed"); + Ok(total_redeemed) } } diff --git a/crates/cdk/src/mint/swap.rs b/crates/cdk/src/mint/swap.rs index 670fa0791..0e14fa32b 100644 --- a/crates/cdk/src/mint/swap.rs +++ b/crates/cdk/src/mint/swap.rs @@ -1,3 +1,5 @@ +#[cfg(feature = "prometheus")] +use cdk_prometheus::METRICS; use tracing::instrument; use super::nut11::{enforce_sig_flag, EnforceSigFlag}; @@ -12,6 +14,8 @@ impl Mint { &self, swap_request: SwapRequest, ) -> Result { + #[cfg(feature = "prometheus")] + METRICS.inc_in_flight_requests("process_swap_request"); // Do the external call before beginning the db transaction // Check any overflow before talking to the signatory swap_request.input_amount()?; @@ -25,7 +29,6 @@ impl Mint { tracing::debug!("Input verification failed: {:?}", err); err })?; - let mut tx = self.localstore.begin_transaction().await?; if let Err(err) = self @@ -38,20 +41,50 @@ impl Mint { .await { tracing::debug!("Attempt to swap unbalanced transaction, aborting: {err}"); + + #[cfg(feature = "prometheus")] + { + METRICS.dec_in_flight_requests("process_swap_request"); + METRICS.record_mint_operation("process_swap_request", false); + METRICS.record_error(); + } + return Err(err); }; - self.validate_sig_flag(&swap_request).await?; - + let validate_sig_result = self.validate_sig_flag(&swap_request).await; + if validate_sig_result.is_err() { + #[cfg(feature = "prometheus")] + self.record_swap_failure("process_swap_request"); + return Err(validate_sig_result.err().unwrap()); + } let mut proof_writer = ProofWriter::new(self.localstore.clone(), self.pubsub_manager.clone()); - let input_ys = proof_writer + let input_ys = match proof_writer .add_proofs(&mut tx, swap_request.inputs()) - .await?; + .await + { + Ok(ys) => ys, + Err(err) => { + #[cfg(feature = "prometheus")] + { + METRICS.dec_in_flight_requests("process_swap_request"); + METRICS.record_mint_operation("process_swap_request", false); + METRICS.record_error(); + } + return Err(err); + } + }; - proof_writer + let update_proof_states_result = proof_writer .update_proofs_states(&mut tx, &input_ys, State::Spent) - .await?; + .await; + + if update_proof_states_result.is_err() { + #[cfg(feature = "prometheus")] + self.record_swap_failure("process_swap_request"); + return Err(update_proof_states_result.err().unwrap()); + } tx.add_blind_signatures( &swap_request @@ -67,7 +100,15 @@ impl Mint { proof_writer.commit(); tx.commit().await?; - Ok(SwapResponse::new(promises)) + let response = SwapResponse::new(promises); + + #[cfg(feature = "prometheus")] + { + METRICS.dec_in_flight_requests("process_swap_request"); + METRICS.record_mint_operation("process_swap_request", true); + } + + Ok(response) } async fn validate_sig_flag(&self, swap_request: &SwapRequest) -> Result<(), Error> { @@ -79,4 +120,10 @@ impl Mint { Ok(()) } + #[cfg(feature = "prometheus")] + fn record_swap_failure(&self, operation: &str) { + METRICS.dec_in_flight_requests(operation); + METRICS.record_mint_operation(operation, false); + METRICS.record_error(); + } } diff --git a/docker-compose.yaml b/docker-compose.yaml index 0f8314e9e..4a4ba88cf 100644 --- a/docker-compose.yaml +++ b/docker-compose.yaml @@ -1,5 +1,40 @@ +version: '3.8' + services: # CDK Mint service + + prometheus: + image: prom/prometheus:latest + ports: + - "9090:9090" + volumes: + - ./misc/provisioning/prometheus.yml:/etc/prometheus/prometheus.yml:ro + command: + - '--config.file=/etc/prometheus/prometheus.yml' + - '--storage.tsdb.path=/prometheus' + - '--web.console.libraries=/etc/prometheus/console_libraries' + - '--web.console.templates=/etc/prometheus/consoles' + - '--web.enable-lifecycle' + - '--enable-feature=otlp-write-receiver' + extra_hosts: + - "host.docker.internal:host-gateway" + networks: + - cdk + + # Grafana for visualization + grafana: + image: grafana/grafana:latest + ports: + - "3011:3000" + volumes: + - ./misc/provisioning/datasources:/etc/grafana/provisioning/datasources + - ./misc/provisioning/dashboards:/etc/grafana/provisioning/dashboards + environment: + - GF_DASHBOARDS_JSON_ENABLED=true + - GF_SECURITY_ADMIN_PASSWORD=admin + - GF_PROVISIONING_PATHS=/etc/grafana/provisioning + networks: + - cdk mintd: build: context: . @@ -16,7 +51,7 @@ services: # Database configuration - choose one: # Option 1: SQLite (embedded, no additional setup needed) - CDK_MINTD_DATABASE=sqlite - # Option 2: ReDB (embedded, no additional setup needed) + # Option 2: ReDB (embedded, no additional setup needed) # - CDK_MINTD_DATABASE=redb # Option 3: PostgreSQL (requires postgres service, enable with: docker-compose --profile postgres up) # - CDK_MINTD_DATABASE=postgres @@ -24,9 +59,17 @@ services: # Cache configuration - CDK_MINTD_CACHE_BACKEND=memory # For Redis cache (requires redis service, enable with: docker-compose --profile redis up): - # - CDK_MINTD_CACHE_REDIS_URL=redis://redis:6379 + # - CDK_MINTD_CACHE_REDIS_URL=redis://redis:6379 # - CDK_MINTD_CACHE_REDIS_KEY_PREFIX=cdk-mintd + - CDK_MINTD_PROMETHEUS_ENABLED=true + - CDK_MINTD_PROMETHEUS_ADDRESS=0.0.0.0 + - CDK_MINTD_PROMETHEUS_PORT=9000 command: ["cdk-mintd"] + depends_on: + - prometheus + - grafana + networks: + - cdk # Uncomment when using PostgreSQL: # depends_on: # - postgres @@ -78,3 +121,9 @@ volumes: driver: local # redis_data: # driver: local + + + +networks: + cdk: + driver: bridge diff --git a/misc/provisioning/dashboards/dashboard.json b/misc/provisioning/dashboards/dashboard.json new file mode 100644 index 000000000..1f1d66c4a --- /dev/null +++ b/misc/provisioning/dashboards/dashboard.json @@ -0,0 +1,1983 @@ +{ + "annotations": { + "list": [ + { + "builtIn": 1, + "datasource": { + "type": "grafana", + "uid": "-- Grafana --" + }, + "enable": true, + "hide": true, + "iconColor": "rgba(0, 211, 255, 1)", + "name": "Annotations & Alerts", + "type": "dashboard" + } + ] + }, + "editable": true, + "fiscalYearStartMonth": 0, + "graphTooltip": 0, + "id": 7, + "links": [], + "panels": [ + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisBorderShow": false, + "axisCenteredZero": false, + "axisColorMode": "text", + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "barWidthFactor": 0.6, + "drawStyle": "line", + "fillOpacity": 10, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "vis": false, + "viz": false + }, + "insertNulls": false, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "never", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green" + }, + { + "color": "red", + "value": 80 + } + ] + }, + "unit": "percent" + }, + "overrides": [] + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 0 + }, + "id": 6, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "hideZeros": false, + "mode": "single", + "sort": "none" + } + }, + "pluginVersion": "12.0.2", + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "expr": "process_cpu_usage_percent", + "format": "time_series", + "intervalFactor": 1, + "legendFormat": "CPU Usage", + "refId": "A" + } + ], + "title": "Process CPU Usage", + "type": "timeseries" + }, + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisBorderShow": false, + "axisCenteredZero": false, + "axisColorMode": "text", + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "barWidthFactor": 0.6, + "drawStyle": "line", + "fillOpacity": 10, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "vis": false, + "viz": false + }, + "insertNulls": false, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "never", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green" + }, + { + "color": "red", + "value": 80 + } + ] + }, + "unit": "bytes" + }, + "overrides": [] + }, + "gridPos": { + "h": 8, + "w": 6, + "x": 12, + "y": 0 + }, + "id": 7, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "hideZeros": false, + "mode": "single", + "sort": "none" + } + }, + "pluginVersion": "12.0.2", + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "expr": "process_memory_bytes", + "format": "time_series", + "intervalFactor": 1, + "legendFormat": "Memory (Bytes)", + "refId": "A" + } + ], + "title": "Process Memory Usage", + "type": "timeseries" + }, + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisBorderShow": false, + "axisCenteredZero": false, + "axisColorMode": "text", + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "barWidthFactor": 0.6, + "drawStyle": "line", + "fillOpacity": 10, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "vis": false, + "viz": false + }, + "insertNulls": false, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "never", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green" + }, + { + "color": "red", + "value": 80 + } + ] + }, + "unit": "percent" + }, + "overrides": [] + }, + "gridPos": { + "h": 8, + "w": 6, + "x": 18, + "y": 0 + }, + "id": 13, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "hideZeros": false, + "mode": "single", + "sort": "none" + } + }, + "pluginVersion": "12.0.2", + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "expr": "process_memory_percent", + "format": "time_series", + "intervalFactor": 1, + "legendFormat": "Memory (%)", + "refId": "A" + } + ], + "title": "Memory Percentage", + "type": "timeseries" + }, + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisBorderShow": false, + "axisCenteredZero": false, + "axisColorMode": "text", + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "barWidthFactor": 0.6, + "drawStyle": "line", + "fillOpacity": 10, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "vis": false, + "viz": false + }, + "insertNulls": false, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "never", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green" + }, + { + "color": "red", + "value": 80 + } + ] + }, + "unit": "reqps" + }, + "overrides": [] + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 8 + }, + "id": 1, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "hideZeros": false, + "mode": "single", + "sort": "none" + } + }, + "pluginVersion": "12.0.2", + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "editorMode": "code", + "expr": "rate(cdk_http_requests_total[1m])", + "format": "time_series", + "intervalFactor": 1, + "legendFormat": "{{endpoint}} - {{status}}", + "range": true, + "refId": "A" + } + ], + "title": "HTTP Request Rate by Endpoint", + "type": "timeseries" + }, + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green" + }, + { + "color": "red", + "value": 50 + } + ] + }, + "unit": "percent" + }, + "overrides": [] + }, + "gridPos": { + "h": 8, + "w": 6, + "x": 12, + "y": 8 + }, + "id": 2, + "options": { + "minVizHeight": 75, + "minVizWidth": 75, + "orientation": "auto", + "reduceOptions": { + "calcs": [ + "lastNotNull" + ], + "fields": "", + "values": false + }, + "showThresholdLabels": false, + "showThresholdMarkers": true, + "sizing": "auto" + }, + "pluginVersion": "12.0.2", + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "editorMode": "code", + "exemplar": false, + "expr": "sum(rate(cdk_http_requests_total{status!=\"200\"}[$__range])) / sum(rate(cdk_http_requests_total[$__range])) * 100", + "format": "time_series", + "instant": false, + "intervalFactor": 1, + "legendFormat": "Error Rate", + "range": true, + "refId": "A" + } + ], + "title": "HTTP Error Rate", + "type": "gauge" + }, + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "hideFrom": { + "legend": false, + "tooltip": false, + "vis": false, + "viz": false + } + }, + "mappings": [] + }, + "overrides": [ + { + "__systemRef": "hideSeriesFrom", + "matcher": { + "id": "byNames", + "options": { + "mode": "exclude", + "names": [ + "/v1/keys/{keyset_id} (200)", + "/v1/mint/quote/bolt11 (200)", + "/v1/swap (400)", + "/v1/mint/bolt11 (200)" + ], + "prefix": "All except:", + "readOnly": true + } + }, + "properties": [ + { + "id": "custom.hideFrom", + "value": { + "legend": false, + "tooltip": false, + "viz": true + } + } + ] + } + ] + }, + "gridPos": { + "h": 8, + "w": 6, + "x": 18, + "y": 8 + }, + "id": 9, + "options": { + "legend": { + "displayMode": "list", + "placement": "bottom", + "showLegend": true, + "values": [ + "value" + ] + }, + "pieType": "pie", + "reduceOptions": { + "calcs": [ + "lastNotNull" + ], + "fields": "", + "values": false + }, + "tooltip": { + "hideZeros": false, + "mode": "single", + "sort": "none" + } + }, + "pluginVersion": "12.0.2", + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "expr": "cdk_http_requests_total", + "format": "time_series", + "intervalFactor": 1, + "legendFormat": "{{endpoint}} ({{status}})", + "refId": "A" + } + ], + "title": "HTTP Requests Distribution", + "type": "piechart" + }, + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisBorderShow": false, + "axisCenteredZero": false, + "axisColorMode": "text", + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "barWidthFactor": 0.6, + "drawStyle": "line", + "fillOpacity": 10, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "vis": false, + "viz": false + }, + "insertNulls": false, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "never", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green" + }, + { + "color": "red", + "value": 80 + } + ] + }, + "unit": "s" + }, + "overrides": [ + { + "__systemRef": "hideSeriesFrom", + "matcher": { + "id": "byNames", + "options": { + "mode": "exclude", + "names": [ + "p50 - /v1/mint/bolt11" + ], + "prefix": "All except:", + "readOnly": true + } + }, + "properties": [ + { + "id": "custom.hideFrom", + "value": { + "legend": false, + "tooltip": false, + "viz": true + } + } + ] + } + ] + }, + "gridPos": { + "h": 8, + "w": 24, + "x": 0, + "y": 16 + }, + "id": 3, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "hideZeros": false, + "mode": "single", + "sort": "none" + } + }, + "pluginVersion": "12.0.2", + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "editorMode": "code", + "expr": "histogram_quantile(0.50, rate(cdk_http_request_duration_seconds_bucket[1m]))", + "format": "time_series", + "intervalFactor": 1, + "legendFormat": "p50 - {{endpoint}}", + "range": true, + "refId": "A" + }, + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "editorMode": "code", + "expr": "histogram_quantile(0.95, rate(cdk_http_request_duration_seconds_bucket[1m]))", + "format": "time_series", + "intervalFactor": 1, + "legendFormat": "p95 - {{endpoint}}", + "range": true, + "refId": "B" + }, + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "editorMode": "code", + "expr": "histogram_quantile(0.99, rate(cdk_http_request_duration_seconds_bucket[1m]))", + "format": "time_series", + "intervalFactor": 1, + "legendFormat": "p99 - {{endpoint}}", + "range": true, + "refId": "C" + } + ], + "title": "HTTP Request Duration Percentiles", + "type": "timeseries" + }, + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisBorderShow": false, + "axisCenteredZero": false, + "axisColorMode": "text", + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "barWidthFactor": 0.6, + "drawStyle": "line", + "fillOpacity": 10, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "vis": false, + "viz": false + }, + "insertNulls": false, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "never", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green" + }, + { + "color": "red", + "value": 80 + } + ] + }, + "unit": "ops" + }, + "overrides": [] + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 24 + }, + "id": 4, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "hideZeros": false, + "mode": "single", + "sort": "none" + } + }, + "pluginVersion": "12.0.2", + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "editorMode": "code", + "expr": "rate(cdk_mint_operations_total[1m])", + "format": "time_series", + "intervalFactor": 1, + "legendFormat": "{{operation}} - {{status}}", + "range": true, + "refId": "A" + } + ], + "title": "Mint Operations Rate", + "type": "timeseries" + }, + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisBorderShow": false, + "axisCenteredZero": false, + "axisColorMode": "text", + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "barWidthFactor": 0.6, + "drawStyle": "line", + "fillOpacity": 10, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "vis": false, + "viz": false + }, + "insertNulls": false, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "never", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green" + }, + { + "color": "red", + "value": 80 + } + ] + }, + "unit": "short" + }, + "overrides": [] + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 12, + "y": 24 + }, + "id": 5, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "hideZeros": false, + "mode": "single", + "sort": "none" + } + }, + "pluginVersion": "12.0.2", + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "expr": "cdk_mint_in_flight_requests", + "format": "time_series", + "intervalFactor": 1, + "legendFormat": "{{operation}}", + "refId": "A" + } + ], + "title": "In-Flight Mint Requests", + "type": "timeseries" + }, + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisBorderShow": false, + "axisCenteredZero": false, + "axisColorMode": "text", + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "barWidthFactor": 0.6, + "drawStyle": "line", + "fillOpacity": 10, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "vis": false, + "viz": false + }, + "insertNulls": false, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "never", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green" + }, + { + "color": "red", + "value": 80 + } + ] + }, + "unit": "sats" + }, + "overrides": [] + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 32 + }, + "id": 11, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "hideZeros": false, + "mode": "single", + "sort": "none" + } + }, + "pluginVersion": "12.0.2", + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "expr": "histogram_quantile(0.50, rate(cdk_lightning_payment_amount_sats_bucket[5m]))", + "format": "time_series", + "intervalFactor": 1, + "legendFormat": "p50 Payment Amount", + "refId": "A" + }, + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "expr": "histogram_quantile(0.95, rate(cdk_lightning_payment_amount_sats_bucket[5m]))", + "format": "time_series", + "intervalFactor": 1, + "legendFormat": "p95 Payment Amount", + "refId": "B" + } + ], + "title": "Lightning Payment Amounts", + "type": "timeseries" + }, + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisBorderShow": false, + "axisCenteredZero": false, + "axisColorMode": "text", + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "barWidthFactor": 0.6, + "drawStyle": "line", + "fillOpacity": 10, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "vis": false, + "viz": false + }, + "insertNulls": false, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "never", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green" + }, + { + "color": "red", + "value": 80 + } + ] + }, + "unit": "short" + }, + "overrides": [] + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 12, + "y": 32 + }, + "id": 8, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "hideZeros": false, + "mode": "single", + "sort": "none" + } + }, + "pluginVersion": "12.0.2", + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "expr": "cdk_db_connections_active", + "format": "time_series", + "intervalFactor": 1, + "legendFormat": "Active Connections", + "refId": "A" + } + ], + "title": "Database Connections", + "type": "timeseries" + }, + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisBorderShow": false, + "axisCenteredZero": false, + "axisColorMode": "text", + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "barWidthFactor": 0.6, + "drawStyle": "line", + "fillOpacity": 10, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "vis": false, + "viz": false + }, + "insertNulls": false, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "never", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green" + }, + { + "color": "red", + "value": 80 + } + ] + }, + "unit": "sats" + }, + "overrides": [] + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 40 + }, + "id": 12, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "hideZeros": false, + "mode": "single", + "sort": "none" + } + }, + "pluginVersion": "12.0.2", + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "expr": "histogram_quantile(0.50, rate(cdk_lightning_payment_fees_sats_bucket[5m]))", + "format": "time_series", + "intervalFactor": 1, + "legendFormat": "p50 Payment Fees", + "refId": "A" + }, + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "expr": "histogram_quantile(0.95, rate(cdk_lightning_payment_fees_sats_bucket[5m]))", + "format": "time_series", + "intervalFactor": 1, + "legendFormat": "p95 Payment Fees", + "refId": "B" + } + ], + "title": "Lightning Payment Fees", + "type": "timeseries" + }, + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green" + }, + { + "color": "yellow", + "value": 1000 + }, + { + "color": "red", + "value": 5000 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 12, + "y": 40 + }, + "id": 10, + "options": { + "colorMode": "value", + "graphMode": "area", + "justifyMode": "auto", + "orientation": "auto", + "percentChangeColorMode": "standard", + "reduceOptions": { + "calcs": [ + "lastNotNull" + ], + "fields": "", + "values": false + }, + "showPercentChange": false, + "textMode": "auto", + "wideLayout": true + }, + "pluginVersion": "12.0.2", + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "expr": "cdk_http_requests_total{status=\"500\"}", + "format": "time_series", + "intervalFactor": 1, + "legendFormat": "{{endpoint}}", + "refId": "A" + } + ], + "title": "Failed Requests (500 Status)", + "type": "stat" + }, + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisBorderShow": false, + "axisCenteredZero": false, + "axisColorMode": "text", + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "barWidthFactor": 0.6, + "drawStyle": "line", + "fillOpacity": 10, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "vis": false, + "viz": false + }, + "insertNulls": false, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "never", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green" + }, + { + "color": "red", + "value": 80 + } + ] + }, + "unit": "ops" + }, + "overrides": [] + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 48 + }, + "id": 14, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "hideZeros": false, + "mode": "single", + "sort": "none" + } + }, + "pluginVersion": "12.0.2", + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "expr": "rate(cdk_auth_attempts_total[1m])", + "format": "time_series", + "intervalFactor": 1, + "legendFormat": "Auth Attempts", + "refId": "A" + }, + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "expr": "rate(cdk_auth_successes_total[1m])", + "format": "time_series", + "intervalFactor": 1, + "legendFormat": "Auth Successes", + "refId": "B" + } + ], + "title": "Authentication Rate", + "type": "timeseries" + }, + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green" + }, + { + "color": "yellow", + "value": 1 + }, + { + "color": "red", + "value": 10 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 12, + "y": 48 + }, + "id": 15, + "options": { + "colorMode": "value", + "graphMode": "area", + "justifyMode": "auto", + "orientation": "auto", + "percentChangeColorMode": "standard", + "reduceOptions": { + "calcs": [ + "lastNotNull" + ], + "fields": "", + "values": false + }, + "showPercentChange": false, + "textMode": "auto", + "wideLayout": true + }, + "pluginVersion": "12.0.2", + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "expr": "cdk_errors_total", + "format": "time_series", + "intervalFactor": 1, + "legendFormat": "Total Errors", + "refId": "A" + } + ], + "title": "Total Errors", + "type": "stat" + }, + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisBorderShow": false, + "axisCenteredZero": false, + "axisColorMode": "text", + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "barWidthFactor": 0.6, + "drawStyle": "line", + "fillOpacity": 10, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "vis": false, + "viz": false + }, + "insertNulls": false, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "never", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green" + }, + { + "color": "red", + "value": 80 + } + ] + }, + "unit": "s" + }, + "overrides": [] + }, + "gridPos": { + "h": 8, + "w": 24, + "x": 0, + "y": 56 + }, + "id": 16, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "hideZeros": false, + "mode": "single", + "sort": "none" + } + }, + "pluginVersion": "12.0.2", + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "editorMode": "code", + "expr": "histogram_quantile(0.50, rate(cdk_db_operation_duration_seconds_bucket[1m]))", + "format": "time_series", + "intervalFactor": 1, + "legendFormat": "p50 - {{operation}}", + "range": true, + "refId": "A" + }, + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "editorMode": "code", + "expr": "histogram_quantile(0.95, rate(cdk_db_operation_duration_seconds_bucket[1m]))", + "format": "time_series", + "intervalFactor": 1, + "legendFormat": "p95 - {{operation}}", + "range": true, + "refId": "B" + }, + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "editorMode": "code", + "expr": "histogram_quantile(0.99, rate(cdk_db_operation_duration_seconds_bucket[1m]))", + "format": "time_series", + "intervalFactor": 1, + "legendFormat": "p99 - {{operation}}", + "range": true, + "refId": "C" + } + ], + "title": "Database Operation Duration Percentiles", + "type": "timeseries" + }, + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisBorderShow": false, + "axisCenteredZero": false, + "axisColorMode": "text", + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "barWidthFactor": 0.6, + "drawStyle": "line", + "fillOpacity": 10, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "vis": false, + "viz": false + }, + "insertNulls": false, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "never", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green" + }, + { + "color": "red", + "value": 80 + } + ] + }, + "unit": "s" + }, + "overrides": [] + }, + "gridPos": { + "h": 8, + "w": 24, + "x": 0, + "y": 64 + }, + "id": 17, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "hideZeros": false, + "mode": "single", + "sort": "none" + } + }, + "pluginVersion": "12.0.2", + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "editorMode": "code", + "expr": "histogram_quantile(0.50, rate(cdk_mint_operation_duration_seconds_bucket[1m]))", + "format": "time_series", + "intervalFactor": 1, + "legendFormat": "p50 - {{operation}} ({{status}})", + "range": true, + "refId": "A" + }, + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "editorMode": "code", + "expr": "histogram_quantile(0.95, rate(cdk_mint_operation_duration_seconds_bucket[1m]))", + "format": "time_series", + "intervalFactor": 1, + "legendFormat": "p95 - {{operation}} ({{status}})", + "range": true, + "refId": "B" + }, + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "editorMode": "code", + "expr": "histogram_quantile(0.99, rate(cdk_mint_operation_duration_seconds_bucket[1m]))", + "format": "time_series", + "intervalFactor": 1, + "legendFormat": "p99 - {{operation}} ({{status}})", + "range": true, + "refId": "C" + } + ], + "title": "Mint Operation Duration Percentiles", + "type": "timeseries" + }, + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisBorderShow": false, + "axisCenteredZero": false, + "axisColorMode": "text", + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "barWidthFactor": 0.6, + "drawStyle": "line", + "fillOpacity": 10, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "vis": false, + "viz": false + }, + "insertNulls": false, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "never", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green" + }, + { + "color": "red", + "value": 80 + } + ] + }, + "unit": "ops" + }, + "overrides": [] + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 72 + }, + "id": 18, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "hideZeros": false, + "mode": "single", + "sort": "none" + } + }, + "pluginVersion": "12.0.2", + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "editorMode": "code", + "expr": "rate(cdk_db_operations_total[1m])", + "format": "time_series", + "intervalFactor": 1, + "legendFormat": "DB Operations Rate", + "range": true, + "refId": "A" + } + ], + "title": "Database Operations Rate", + "type": "timeseries" + }, + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisBorderShow": false, + "axisCenteredZero": false, + "axisColorMode": "text", + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "barWidthFactor": 0.6, + "drawStyle": "line", + "fillOpacity": 10, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "vis": false, + "viz": false + }, + "insertNulls": false, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "never", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green" + }, + { + "color": "red", + "value": 80 + } + ] + }, + "unit": "ops" + }, + "overrides": [] + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 12, + "y": 72 + }, + "id": 19, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "hideZeros": false, + "mode": "single", + "sort": "none" + } + }, + "pluginVersion": "12.0.2", + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "expr": "rate(cdk_wallet_operations_total[1m])", + "format": "time_series", + "intervalFactor": 1, + "legendFormat": "Wallet Operations Rate", + "refId": "A" + }, + { + "datasource": { + "type": "prometheus", + "uid": "prometheus" + }, + "expr": "rate(cdk_lightning_payments_total[1m])", + "format": "time_series", + "intervalFactor": 1, + "legendFormat": "Lightning Payments Rate", + "refId": "B" + } + ], + "title": "Wallet & Lightning Operations Rate", + "type": "timeseries" + } + ], + "preload": false, + "refresh": "30s", + "schemaVersion": 41, + "tags": [ + "cashu", + "cdk", + "mint" + ], + "templating": { + "list": [] + }, + "time": { + "from": "now-1h", + "to": "now" + }, + "timepicker": {}, + "timezone": "", + "title": "CDK Mint Dashboard", + "uid": "cdk-mint-dashboard", + "version": 8 +} \ No newline at end of file diff --git a/misc/provisioning/dashboards/dashboard.yaml b/misc/provisioning/dashboards/dashboard.yaml new file mode 100644 index 000000000..5cf7ca332 --- /dev/null +++ b/misc/provisioning/dashboards/dashboard.yaml @@ -0,0 +1,8 @@ +apiVersion: 1 +providers: + - name: 'default' + type: file + disableDeletion: false + updateIntervalSeconds: 10 + options: + path: /etc/grafana/provisioning/dashboards \ No newline at end of file diff --git a/misc/provisioning/datasources/datasource.yml b/misc/provisioning/datasources/datasource.yml new file mode 100644 index 000000000..bcbdc3cd1 --- /dev/null +++ b/misc/provisioning/datasources/datasource.yml @@ -0,0 +1,8 @@ +apiVersion: 1 + +datasources: + - name: prometheus + type: prometheus + access: proxy + url: http://prometheus:9090 + isDefault: true \ No newline at end of file diff --git a/misc/provisioning/prometheus.yml b/misc/provisioning/prometheus.yml new file mode 100644 index 000000000..6cc833466 --- /dev/null +++ b/misc/provisioning/prometheus.yml @@ -0,0 +1,8 @@ +global: + scrape_interval: 15s + evaluation_interval: 15s + +scrape_configs: + - job_name: 'prometheus' + static_configs: + - targets: ['host.docker.internal:9000','mintd:9000'] From ce599a9e5721312d1e78a0c780c5feea42c7d5a9 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Tue, 9 Sep 2025 15:00:44 +0100 Subject: [PATCH 141/321] chore: code style (#1056) --- crates/cdk/src/pub_sub.rs | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/crates/cdk/src/pub_sub.rs b/crates/cdk/src/pub_sub.rs index c5f98a333..f83655524 100644 --- a/crates/cdk/src/pub_sub.rs +++ b/crates/cdk/src/pub_sub.rs @@ -194,20 +194,20 @@ where } /// Try to subscribe to a specific event - pub async fn try_subscribe + TryInto>>>( - &self, - params: P, - ) -> Result, P::Error> { + pub async fn try_subscribe

    (&self, params: P) -> Result, P::Error> + where + P: AsRef + TryInto>>, + { Ok(self .subscribe_inner(params.as_ref().clone(), params.try_into()?) .await) } /// Subscribe to a specific event - pub async fn subscribe + Into>>>( - &self, - params: P, - ) -> ActiveSubscription { + pub async fn subscribe

    (&self, params: P) -> ActiveSubscription + where + P: AsRef + Into>>, + { self.subscribe_inner(params.as_ref().clone(), params.into()) .await } From 64a4fe5bca37f567dc9abf2ed7c42181e521cc70 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Wed, 10 Sep 2025 09:54:00 +0100 Subject: [PATCH 142/321] feat: remove unused ln_routers (#1059) * feat: remove unused ln_routers * feat: allow other routers to be nested --- .../src/bin/start_fake_auth_mint.rs | 11 ++- .../src/bin/start_fake_mint.rs | 11 ++- .../src/bin/start_regtest_mints.rs | 13 ++- crates/cdk-mintd/src/lib.rs | 91 ++++++------------- crates/cdk-mintd/src/main.rs | 1 + crates/cdk-mintd/src/setup.rs | 8 -- 6 files changed, 58 insertions(+), 77 deletions(-) diff --git a/crates/cdk-integration-tests/src/bin/start_fake_auth_mint.rs b/crates/cdk-integration-tests/src/bin/start_fake_auth_mint.rs index 0fe84fd8b..43e5e4a8e 100644 --- a/crates/cdk-integration-tests/src/bin/start_fake_auth_mint.rs +++ b/crates/cdk-integration-tests/src/bin/start_fake_auth_mint.rs @@ -101,8 +101,15 @@ async fn start_fake_auth_mint( println!("Fake auth mint shutdown signal received"); }; - match cdk_mintd::run_mintd_with_shutdown(&temp_dir, &settings, shutdown_future, None, None) - .await + match cdk_mintd::run_mintd_with_shutdown( + &temp_dir, + &settings, + shutdown_future, + None, + None, + vec![], + ) + .await { Ok(_) => println!("Fake auth mint exited normally"), Err(e) => eprintln!("Fake auth mint exited with error: {e}"), diff --git a/crates/cdk-integration-tests/src/bin/start_fake_mint.rs b/crates/cdk-integration-tests/src/bin/start_fake_mint.rs index 89d253012..01aab141c 100644 --- a/crates/cdk-integration-tests/src/bin/start_fake_mint.rs +++ b/crates/cdk-integration-tests/src/bin/start_fake_mint.rs @@ -100,8 +100,15 @@ async fn start_fake_mint( println!("Fake mint shutdown signal received"); }; - match cdk_mintd::run_mintd_with_shutdown(&temp_dir, &settings, shutdown_future, None, None) - .await + match cdk_mintd::run_mintd_with_shutdown( + &temp_dir, + &settings, + shutdown_future, + None, + None, + vec![], + ) + .await { Ok(_) => println!("Fake mint exited normally"), Err(e) => eprintln!("Fake mint exited with error: {e}"), diff --git a/crates/cdk-integration-tests/src/bin/start_regtest_mints.rs b/crates/cdk-integration-tests/src/bin/start_regtest_mints.rs index 3ebcf2612..67dc1f9ad 100644 --- a/crates/cdk-integration-tests/src/bin/start_regtest_mints.rs +++ b/crates/cdk-integration-tests/src/bin/start_regtest_mints.rs @@ -107,8 +107,15 @@ async fn start_cln_mint( println!("CLN mint shutdown signal received"); }; - match cdk_mintd::run_mintd_with_shutdown(&temp_dir, &settings, shutdown_future, None, None) - .await + match cdk_mintd::run_mintd_with_shutdown( + &temp_dir, + &settings, + shutdown_future, + None, + None, + vec![], + ) + .await { Ok(_) => println!("CLN mint exited normally"), Err(e) => eprintln!("CLN mint exited with error: {e}"), @@ -172,6 +179,7 @@ async fn start_lnd_mint( shutdown_future, None, None, + vec![], ) .await { @@ -238,6 +246,7 @@ async fn start_ldk_mint( shutdown_future, None, runtime, + vec![], ) .await { diff --git a/crates/cdk-mintd/src/lib.rs b/crates/cdk-mintd/src/lib.rs index 9071c73c8..80eb63376 100644 --- a/crates/cdk-mintd/src/lib.rs +++ b/crates/cdk-mintd/src/lib.rs @@ -337,27 +337,18 @@ async fn configure_mint_builder( runtime: Option>, work_dir: &Path, kv_store: Option + Send + Sync>>, -) -> Result<(MintBuilder, Vec)> { - let mut ln_routers = vec![]; - +) -> Result { // Configure basic mint information let mint_builder = configure_basic_info(settings, mint_builder); // Configure lightning backend - let mint_builder = configure_lightning_backend( - settings, - mint_builder, - &mut ln_routers, - runtime, - work_dir, - kv_store, - ) - .await?; + let mint_builder = + configure_lightning_backend(settings, mint_builder, runtime, work_dir, kv_store).await?; // Configure caching let mint_builder = configure_cache(settings, mint_builder); - Ok((mint_builder, ln_routers)) + Ok(mint_builder) } /// Configures basic mint information (name, contact info, descriptions, etc.) @@ -414,7 +405,6 @@ fn configure_basic_info(settings: &config::Settings, mint_builder: MintBuilder) async fn configure_lightning_backend( settings: &config::Settings, mut mint_builder: MintBuilder, - ln_routers: &mut Vec, _runtime: Option>, work_dir: &Path, _kv_store: Option + Send + Sync>>, @@ -436,14 +426,7 @@ async fn configure_lightning_backend( .clone() .expect("Config checked at load that cln is some"); let cln = cln_settings - .setup( - ln_routers, - settings, - CurrencyUnit::Msat, - None, - work_dir, - None, - ) + .setup(settings, CurrencyUnit::Msat, None, work_dir, None) .await?; #[cfg(feature = "prometheus")] let cln = MetricsMintPayment::new(cln); @@ -461,14 +444,7 @@ async fn configure_lightning_backend( LnBackend::LNbits => { let lnbits_settings = settings.clone().lnbits.expect("Checked on config load"); let lnbits = lnbits_settings - .setup( - ln_routers, - settings, - CurrencyUnit::Sat, - None, - work_dir, - None, - ) + .setup(settings, CurrencyUnit::Sat, None, work_dir, None) .await?; #[cfg(feature = "prometheus")] let lnbits = MetricsMintPayment::new(lnbits); @@ -486,14 +462,7 @@ async fn configure_lightning_backend( LnBackend::Lnd => { let lnd_settings = settings.clone().lnd.expect("Checked at config load"); let lnd = lnd_settings - .setup( - ln_routers, - settings, - CurrencyUnit::Msat, - None, - work_dir, - None, - ) + .setup(settings, CurrencyUnit::Msat, None, work_dir, None) .await?; #[cfg(feature = "prometheus")] let lnd = MetricsMintPayment::new(lnd); @@ -514,14 +483,7 @@ async fn configure_lightning_backend( for unit in fake_wallet.clone().supported_units { let fake = fake_wallet - .setup( - ln_routers, - settings, - unit.clone(), - None, - work_dir, - _kv_store.clone(), - ) + .setup(settings, unit.clone(), None, work_dir, _kv_store.clone()) .await?; #[cfg(feature = "prometheus")] let fake = MetricsMintPayment::new(fake); @@ -552,7 +514,7 @@ async fn configure_lightning_backend( for unit in grpc_processor.clone().supported_units { tracing::debug!("Adding unit: {:?}", unit); let processor = grpc_processor - .setup(ln_routers, settings, unit.clone(), None, work_dir, None) + .setup(settings, unit.clone(), None, work_dir, None) .await?; #[cfg(feature = "prometheus")] let processor = MetricsMintPayment::new(processor); @@ -573,14 +535,7 @@ async fn configure_lightning_backend( tracing::info!("Using LDK Node backend: {:?}", ldk_node_settings); let ldk_node = ldk_node_settings - .setup( - ln_routers, - settings, - CurrencyUnit::Sat, - _runtime, - work_dir, - None, - ) + .setup(settings, CurrencyUnit::Sat, _runtime, work_dir, None) .await?; mint_builder = configure_backend_for_unit( @@ -893,10 +848,10 @@ async fn build_mint( async fn start_services_with_shutdown( mint: Arc, settings: &config::Settings, - ln_routers: Vec, work_dir: &Path, mint_builder_info: cdk::nuts::MintInfo, shutdown_signal: impl std::future::Future + Send + 'static, + routers: Vec, ) -> Result<()> { let listen_addr = settings.info.listen_host.clone(); let listen_port = settings.info.listen_port; @@ -980,6 +935,10 @@ async fn start_services_with_shutdown( ) .layer(TraceLayer::new_for_http()); + for router in routers { + mint_service = mint_service.merge(router); + } + #[cfg(feature = "swagger")] { if settings.info.enable_swagger_ui.unwrap_or(false) { @@ -1031,9 +990,6 @@ async fn start_services_with_shutdown( #[cfg(not(feature = "prometheus"))] let prometheus_handle: Option> = None; - for router in ln_routers { - mint_service = mint_service.merge(router); - } mint.start().await?; @@ -1119,6 +1075,7 @@ pub async fn run_mintd( db_password: Option, enable_logging: bool, runtime: Option>, + routers: Vec, ) -> Result<()> { let _guard = if enable_logging { setup_tracing(work_dir, &settings.info.logging)? @@ -1126,8 +1083,15 @@ pub async fn run_mintd( None }; - let result = - run_mintd_with_shutdown(work_dir, settings, shutdown_signal(), db_password, runtime).await; + let result = run_mintd_with_shutdown( + work_dir, + settings, + shutdown_signal(), + db_password, + runtime, + routers, + ) + .await; // Explicitly drop the guard to ensure proper cleanup if let Some(guard) = _guard { @@ -1149,12 +1113,13 @@ pub async fn run_mintd_with_shutdown( shutdown_signal: impl std::future::Future + Send + 'static, db_password: Option, runtime: Option>, + routers: Vec, ) -> Result<()> { let (localstore, keystore, kv) = initial_setup(work_dir, settings, db_password.clone()).await?; let mint_builder = MintBuilder::new(localstore); - let (mint_builder, ln_routers) = + let mint_builder = configure_mint_builder(settings, mint_builder, runtime, work_dir, Some(kv)).await?; #[cfg(feature = "auth")] let mint_builder = setup_authentication(settings, work_dir, mint_builder, db_password).await?; @@ -1173,10 +1138,10 @@ pub async fn run_mintd_with_shutdown( let result = start_services_with_shutdown( mint.clone(), settings, - ln_routers, work_dir, mint.mint_info().await?, shutdown_signal, + routers, ) .await; diff --git a/crates/cdk-mintd/src/main.rs b/crates/cdk-mintd/src/main.rs index 435dcb048..b21b97a05 100644 --- a/crates/cdk-mintd/src/main.rs +++ b/crates/cdk-mintd/src/main.rs @@ -32,6 +32,7 @@ fn main() -> Result<()> { password, args.enable_logging, Some(rt_clone), + vec![], ) .await }) diff --git a/crates/cdk-mintd/src/setup.rs b/crates/cdk-mintd/src/setup.rs index dfaeddf86..127e5142b 100644 --- a/crates/cdk-mintd/src/setup.rs +++ b/crates/cdk-mintd/src/setup.rs @@ -8,7 +8,6 @@ use std::sync::Arc; #[cfg(feature = "cln")] use anyhow::anyhow; use async_trait::async_trait; -use axum::Router; #[cfg(feature = "fakewallet")] use bip39::rand::{thread_rng, Rng}; use cdk::cdk_database::MintKVStore; @@ -31,7 +30,6 @@ use crate::expand_path; pub trait LnBackendSetup { async fn setup( &self, - routers: &mut Vec, settings: &Settings, unit: CurrencyUnit, runtime: Option>, @@ -45,7 +43,6 @@ pub trait LnBackendSetup { impl LnBackendSetup for config::Cln { async fn setup( &self, - _routers: &mut Vec, _settings: &Settings, _unit: CurrencyUnit, _runtime: Option>, @@ -75,7 +72,6 @@ impl LnBackendSetup for config::Cln { impl LnBackendSetup for config::LNbits { async fn setup( &self, - _routers: &mut Vec, _settings: &Settings, _unit: CurrencyUnit, _runtime: Option>, @@ -110,7 +106,6 @@ impl LnBackendSetup for config::LNbits { impl LnBackendSetup for config::Lnd { async fn setup( &self, - _routers: &mut Vec, _settings: &Settings, _unit: CurrencyUnit, _runtime: Option>, @@ -143,7 +138,6 @@ impl LnBackendSetup for config::Lnd { impl LnBackendSetup for config::FakeWallet { async fn setup( &self, - _router: &mut Vec, _settings: &Settings, unit: CurrencyUnit, _runtime: Option>, @@ -176,7 +170,6 @@ impl LnBackendSetup for config::FakeWallet { impl LnBackendSetup for config::GrpcProcessor { async fn setup( &self, - _routers: &mut Vec, _settings: &Settings, _unit: CurrencyUnit, _runtime: Option>, @@ -199,7 +192,6 @@ impl LnBackendSetup for config::GrpcProcessor { impl LnBackendSetup for config::LdkNode { async fn setup( &self, - _routers: &mut Vec, _settings: &Settings, _unit: CurrencyUnit, runtime: Option>, From 21b40808108f9011839a1cdd33c6427c40469454 Mon Sep 17 00:00:00 2001 From: David Caseria Date: Wed, 10 Sep 2025 04:56:55 -0400 Subject: [PATCH 143/321] FFI bindings for Wallet (#932) * feat: Add initial CDK FFI bindings using UniFFI proc macros * feat: Add complete Wallet methods to CDK FFI bindings --- .github/workflows/ci.yml | 6 + Cargo.toml | 8 + crates/cdk-ffi/Cargo.toml | 43 + crates/cdk-ffi/README.md | 61 + crates/cdk-ffi/src/bin/uniffi-bindgen.rs | 3 + crates/cdk-ffi/src/database.rs | 942 ++++++++ crates/cdk-ffi/src/error.rs | 124 + crates/cdk-ffi/src/lib.rs | 285 +++ crates/cdk-ffi/src/types.rs | 2636 ++++++++++++++++++++++ crates/cdk-ffi/src/wallet.rs | 486 ++++ crates/cdk-ffi/uniffi.toml | 10 + justfile | 151 ++ 12 files changed, 4755 insertions(+) create mode 100644 crates/cdk-ffi/Cargo.toml create mode 100644 crates/cdk-ffi/README.md create mode 100644 crates/cdk-ffi/src/bin/uniffi-bindgen.rs create mode 100644 crates/cdk-ffi/src/database.rs create mode 100644 crates/cdk-ffi/src/error.rs create mode 100644 crates/cdk-ffi/src/lib.rs create mode 100644 crates/cdk-ffi/src/types.rs create mode 100644 crates/cdk-ffi/src/wallet.rs create mode 100644 crates/cdk-ffi/uniffi.toml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 19d1ae2c1..a5cae9b65 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -117,6 +117,12 @@ jobs: -p cdk-signatory, -p cdk-mint-rpc, + # FFI bindings + -p cdk-ffi, + -p cdk-ffi --no-default-features, + -p cdk-ffi --no-default-features --features auth, + -p cdk-ffi --no-default-features --features bip353, + # Binaries --bin cdk-cli, --bin cdk-cli --features sqlcipher, diff --git a/Cargo.toml b/Cargo.toml index 452bac843..a59baac99 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -127,5 +127,13 @@ inherits = "dev" incremental = false lto = "off" +[profile.release-smaller] +inherits = "release" +opt-level = 'z' # Optimize for size. +lto = true # Enable Link Time Optimization +codegen-units = 1 # Reduce number of codegen units to increase optimizations. +panic = "abort" # Abort on panic +strip = "debuginfo" # Partially strip symbols from binary + [workspace.metadata.crane] name = "cdk-workspace" diff --git a/crates/cdk-ffi/Cargo.toml b/crates/cdk-ffi/Cargo.toml new file mode 100644 index 000000000..9419ac36d --- /dev/null +++ b/crates/cdk-ffi/Cargo.toml @@ -0,0 +1,43 @@ +[package] +name = "cdk-ffi" +version.workspace = true +edition.workspace = true +license.workspace = true +repository.workspace = true +rust-version.workspace = true + +[lib] +crate-type = ["cdylib", "staticlib"] +name = "cdk_ffi" + +[features] +default = ["auth", "bip353"] +auth = ["cdk/auth", "cdk-common/auth", "cashu/auth"] +bip353 = ["cdk/bip353"] + +[dependencies] +async-trait = { workspace = true } +bip39 = { workspace = true } +cashu = { workspace = true } +cdk = { workspace = true, default-features = false, features = ["wallet"] } +cdk-common = { workspace = true } +cdk-sqlite = { workspace = true } +ctor = "0.2" +futures = { workspace = true } +once_cell = { workspace = true } +rand = { workspace = true } +serde = { workspace = true, features = ["derive"] } +serde_json = { workspace = true } +thiserror = { workspace = true } +tokio = { workspace = true, features = ["sync", "rt", "rt-multi-thread"] } +uniffi = { version = "0.29", features = ["cli", "tokio"] } +url = { workspace = true } +uuid = { workspace = true, features = ["v4"] } + + +[dev-dependencies] + +[[bin]] +name = "uniffi-bindgen" +path = "src/bin/uniffi-bindgen.rs" + diff --git a/crates/cdk-ffi/README.md b/crates/cdk-ffi/README.md new file mode 100644 index 000000000..1d28ccd04 --- /dev/null +++ b/crates/cdk-ffi/README.md @@ -0,0 +1,61 @@ +# CDK FFI Bindings + +UniFFI bindings for the CDK (Cashu Development Kit), providing foreign function interface access to wallet functionality for multiple programming languages. + +## Supported Languages + +- **🐍 Python** - With REPL integration for development +- **🍎 Swift** - iOS and macOS development +- **🎯 Kotlin** - Android and JVM development + +## Development Tasks + +### Build & Check +```bash +just ffi-build # Build FFI library (release) +just ffi-build --debug # Build debug version +just ffi-check # Check compilation +just ffi-clean # Clean build artifacts +``` + +### Generate Bindings +```bash +# Generate for specific languages +just ffi-generate python +just ffi-generate swift +just ffi-generate kotlin + +# Generate all languages +just ffi-generate-all + +# Use --debug for faster development builds +just ffi-generate python --debug +``` + +### Development & Testing +```bash +# Python development with REPL +just ffi-dev-python # Generates bindings and opens Python REPL with cdk_ffi loaded + +# Test bindings +just ffi-test-python # Test Python bindings import +``` + +## Quick Start + +```bash +# Start development +just ffi-dev-python + +# In the Python REPL: +>>> dir(cdk_ffi) # Explore available functions +>>> help(cdk_ffi.generate_mnemonic) # Get help +``` + +## Language Packages + +For production use, see language-specific repositories: + +- [cdk-swift](https://github.com/cashubtc/cdk-swift) - iOS/macOS packages +- [cdk-kotlin](https://github.com/cashubtc/cdk-kotlin) - Android/JVM packages +- [cdk-python](https://github.com/cashubtc/cdk-python) - PyPI packages \ No newline at end of file diff --git a/crates/cdk-ffi/src/bin/uniffi-bindgen.rs b/crates/cdk-ffi/src/bin/uniffi-bindgen.rs new file mode 100644 index 000000000..f6cff6cf1 --- /dev/null +++ b/crates/cdk-ffi/src/bin/uniffi-bindgen.rs @@ -0,0 +1,3 @@ +fn main() { + uniffi::uniffi_bindgen_main() +} diff --git a/crates/cdk-ffi/src/database.rs b/crates/cdk-ffi/src/database.rs new file mode 100644 index 000000000..af63d221f --- /dev/null +++ b/crates/cdk-ffi/src/database.rs @@ -0,0 +1,942 @@ +//! FFI Database bindings + +use std::collections::HashMap; +use std::sync::Arc; + +use cdk_common::database::WalletDatabase as CdkWalletDatabase; +use cdk_sqlite::wallet::WalletSqliteDatabase as CdkWalletSqliteDatabase; + +use crate::error::FfiError; +use crate::types::*; + +/// FFI-compatible trait for wallet database operations +/// This trait mirrors the CDK WalletDatabase trait but uses FFI-compatible types +#[uniffi::export(with_foreign)] +#[async_trait::async_trait] +pub trait WalletDatabase: Send + Sync { + // Mint Management + /// Add Mint to storage + async fn add_mint( + &self, + mint_url: MintUrl, + mint_info: Option, + ) -> Result<(), FfiError>; + + /// Remove Mint from storage + async fn remove_mint(&self, mint_url: MintUrl) -> Result<(), FfiError>; + + /// Get mint from storage + async fn get_mint(&self, mint_url: MintUrl) -> Result, FfiError>; + + /// Get all mints from storage + async fn get_mints(&self) -> Result>, FfiError>; + + /// Update mint url + async fn update_mint_url( + &self, + old_mint_url: MintUrl, + new_mint_url: MintUrl, + ) -> Result<(), FfiError>; + + // Keyset Management + /// Add mint keyset to storage + async fn add_mint_keysets( + &self, + mint_url: MintUrl, + keysets: Vec, + ) -> Result<(), FfiError>; + + /// Get mint keysets for mint url + async fn get_mint_keysets( + &self, + mint_url: MintUrl, + ) -> Result>, FfiError>; + + /// Get mint keyset by id + async fn get_keyset_by_id(&self, keyset_id: Id) -> Result, FfiError>; + + // Mint Quote Management + /// Add mint quote to storage + async fn add_mint_quote(&self, quote: MintQuote) -> Result<(), FfiError>; + + /// Get mint quote from storage + async fn get_mint_quote(&self, quote_id: String) -> Result, FfiError>; + + /// Get mint quotes from storage + async fn get_mint_quotes(&self) -> Result, FfiError>; + + /// Remove mint quote from storage + async fn remove_mint_quote(&self, quote_id: String) -> Result<(), FfiError>; + + // Melt Quote Management + /// Add melt quote to storage + async fn add_melt_quote(&self, quote: MeltQuote) -> Result<(), FfiError>; + + /// Get melt quote from storage + async fn get_melt_quote(&self, quote_id: String) -> Result, FfiError>; + + /// Get melt quotes from storage + async fn get_melt_quotes(&self) -> Result, FfiError>; + + /// Remove melt quote from storage + async fn remove_melt_quote(&self, quote_id: String) -> Result<(), FfiError>; + + // Keys Management + /// Add Keys to storage + async fn add_keys(&self, keyset: KeySet) -> Result<(), FfiError>; + + /// Get Keys from storage + async fn get_keys(&self, id: Id) -> Result, FfiError>; + + /// Remove Keys from storage + async fn remove_keys(&self, id: Id) -> Result<(), FfiError>; + + // Proof Management + /// Update the proofs in storage by adding new proofs or removing proofs by their Y value + async fn update_proofs( + &self, + added: Vec, + removed_ys: Vec, + ) -> Result<(), FfiError>; + + /// Get proofs from storage + async fn get_proofs( + &self, + mint_url: Option, + unit: Option, + state: Option>, + spending_conditions: Option>, + ) -> Result, FfiError>; + + /// Update proofs state in storage + async fn update_proofs_state( + &self, + ys: Vec, + state: ProofState, + ) -> Result<(), FfiError>; + + // Keyset Counter Management + /// Increment Keyset counter + async fn increment_keyset_counter(&self, keyset_id: Id, count: u32) -> Result; + + // Transaction Management + /// Add transaction to storage + async fn add_transaction(&self, transaction: Transaction) -> Result<(), FfiError>; + + /// Get transaction from storage + async fn get_transaction( + &self, + transaction_id: TransactionId, + ) -> Result, FfiError>; + + /// List transactions from storage + async fn list_transactions( + &self, + mint_url: Option, + direction: Option, + unit: Option, + ) -> Result, FfiError>; + + /// Remove transaction from storage + async fn remove_transaction(&self, transaction_id: TransactionId) -> Result<(), FfiError>; +} + +/// Internal bridge trait to convert from the FFI trait to the CDK database trait +/// This allows us to bridge between the UniFFI trait and the CDK's internal database trait +struct WalletDatabaseBridge { + ffi_db: Arc, +} + +impl WalletDatabaseBridge { + fn new(ffi_db: Arc) -> Self { + Self { ffi_db } + } +} + +impl std::fmt::Debug for WalletDatabaseBridge { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + write!(f, "WalletDatabaseBridge") + } +} + +#[async_trait::async_trait] +impl CdkWalletDatabase for WalletDatabaseBridge { + type Err = cdk_common::database::Error; + + // Mint Management + async fn add_mint( + &self, + mint_url: cdk_common::mint_url::MintUrl, + mint_info: Option, + ) -> Result<(), Self::Err> { + let ffi_mint_url = mint_url.into(); + let ffi_mint_info = mint_info.map(Into::into); + + self.ffi_db + .add_mint(ffi_mint_url, ffi_mint_info) + .await + .map_err(|e| cdk_common::database::Error::Database(e.to_string().into())) + } + + async fn remove_mint(&self, mint_url: cdk_common::mint_url::MintUrl) -> Result<(), Self::Err> { + let ffi_mint_url = mint_url.into(); + self.ffi_db + .remove_mint(ffi_mint_url) + .await + .map_err(|e| cdk_common::database::Error::Database(e.to_string().into())) + } + + async fn get_mint( + &self, + mint_url: cdk_common::mint_url::MintUrl, + ) -> Result, Self::Err> { + let ffi_mint_url = mint_url.into(); + let result = self + .ffi_db + .get_mint(ffi_mint_url) + .await + .map_err(|e| cdk_common::database::Error::Database(e.to_string().into()))?; + Ok(result.map(Into::into)) + } + + async fn get_mints( + &self, + ) -> Result>, Self::Err> + { + let result = self + .ffi_db + .get_mints() + .await + .map_err(|e| cdk_common::database::Error::Database(e.to_string().into()))?; + + let mut cdk_result = HashMap::new(); + for (ffi_mint_url, mint_info_opt) in result { + let cdk_url = ffi_mint_url.try_into().map_err(|e: FfiError| { + cdk_common::database::Error::Database(e.to_string().into()) + })?; + cdk_result.insert(cdk_url, mint_info_opt.map(Into::into)); + } + Ok(cdk_result) + } + + async fn update_mint_url( + &self, + old_mint_url: cdk_common::mint_url::MintUrl, + new_mint_url: cdk_common::mint_url::MintUrl, + ) -> Result<(), Self::Err> { + let ffi_old_mint_url = old_mint_url.into(); + let ffi_new_mint_url = new_mint_url.into(); + self.ffi_db + .update_mint_url(ffi_old_mint_url, ffi_new_mint_url) + .await + .map_err(|e| cdk_common::database::Error::Database(e.to_string().into())) + } + + // Keyset Management + async fn add_mint_keysets( + &self, + mint_url: cdk_common::mint_url::MintUrl, + keysets: Vec, + ) -> Result<(), Self::Err> { + let ffi_mint_url = mint_url.into(); + let ffi_keysets: Vec = keysets.into_iter().map(Into::into).collect(); + + self.ffi_db + .add_mint_keysets(ffi_mint_url, ffi_keysets) + .await + .map_err(|e| cdk_common::database::Error::Database(e.to_string().into())) + } + + async fn get_mint_keysets( + &self, + mint_url: cdk_common::mint_url::MintUrl, + ) -> Result>, Self::Err> { + let ffi_mint_url = mint_url.into(); + let result = self + .ffi_db + .get_mint_keysets(ffi_mint_url) + .await + .map_err(|e| cdk_common::database::Error::Database(e.to_string().into()))?; + Ok(result.map(|keysets| keysets.into_iter().map(Into::into).collect())) + } + + async fn get_keyset_by_id( + &self, + keyset_id: &cdk_common::nuts::Id, + ) -> Result, Self::Err> { + let ffi_id = (*keyset_id).into(); + let result = self + .ffi_db + .get_keyset_by_id(ffi_id) + .await + .map_err(|e| cdk_common::database::Error::Database(e.to_string().into()))?; + Ok(result.map(Into::into)) + } + + // Mint Quote Management + async fn add_mint_quote(&self, quote: cdk_common::wallet::MintQuote) -> Result<(), Self::Err> { + let ffi_quote = quote.into(); + self.ffi_db + .add_mint_quote(ffi_quote) + .await + .map_err(|e| cdk_common::database::Error::Database(e.to_string().into())) + } + + async fn get_mint_quote( + &self, + quote_id: &str, + ) -> Result, Self::Err> { + let result = self + .ffi_db + .get_mint_quote(quote_id.to_string()) + .await + .map_err(|e| cdk_common::database::Error::Database(e.to_string().into()))?; + Ok(result + .map(|q| { + q.try_into().map_err(|e: FfiError| { + cdk_common::database::Error::Database(e.to_string().into()) + }) + }) + .transpose()?) + } + + async fn get_mint_quotes(&self) -> Result, Self::Err> { + let result = self + .ffi_db + .get_mint_quotes() + .await + .map_err(|e| cdk_common::database::Error::Database(e.to_string().into()))?; + Ok(result + .into_iter() + .map(|q| { + q.try_into().map_err(|e: FfiError| { + cdk_common::database::Error::Database(e.to_string().into()) + }) + }) + .collect::, _>>()?) + } + + async fn remove_mint_quote(&self, quote_id: &str) -> Result<(), Self::Err> { + self.ffi_db + .remove_mint_quote(quote_id.to_string()) + .await + .map_err(|e| cdk_common::database::Error::Database(e.to_string().into())) + } + + // Melt Quote Management + async fn add_melt_quote(&self, quote: cdk_common::wallet::MeltQuote) -> Result<(), Self::Err> { + let ffi_quote = quote.into(); + self.ffi_db + .add_melt_quote(ffi_quote) + .await + .map_err(|e| cdk_common::database::Error::Database(e.to_string().into())) + } + + async fn get_melt_quote( + &self, + quote_id: &str, + ) -> Result, Self::Err> { + let result = self + .ffi_db + .get_melt_quote(quote_id.to_string()) + .await + .map_err(|e| cdk_common::database::Error::Database(e.to_string().into()))?; + Ok(result + .map(|q| { + q.try_into().map_err(|e: FfiError| { + cdk_common::database::Error::Database(e.to_string().into()) + }) + }) + .transpose()?) + } + + async fn get_melt_quotes(&self) -> Result, Self::Err> { + let result = self + .ffi_db + .get_melt_quotes() + .await + .map_err(|e| cdk_common::database::Error::Database(e.to_string().into()))?; + Ok(result + .into_iter() + .map(|q| { + q.try_into().map_err(|e: FfiError| { + cdk_common::database::Error::Database(e.to_string().into()) + }) + }) + .collect::, _>>()?) + } + + async fn remove_melt_quote(&self, quote_id: &str) -> Result<(), Self::Err> { + self.ffi_db + .remove_melt_quote(quote_id.to_string()) + .await + .map_err(|e| cdk_common::database::Error::Database(e.to_string().into())) + } + + // Keys Management + async fn add_keys(&self, keyset: cashu::KeySet) -> Result<(), Self::Err> { + let ffi_keyset: KeySet = keyset.into(); + self.ffi_db + .add_keys(ffi_keyset) + .await + .map_err(|e| cdk_common::database::Error::Database(e.to_string().into())) + } + + async fn get_keys( + &self, + id: &cdk_common::nuts::Id, + ) -> Result, Self::Err> { + let ffi_id: Id = (*id).into(); + let result = self + .ffi_db + .get_keys(ffi_id) + .await + .map_err(|e| cdk_common::database::Error::Database(e.to_string().into()))?; + + // Convert FFI Keys back to CDK Keys using TryFrom + result + .map(|ffi_keys| { + ffi_keys.try_into().map_err(|e: FfiError| { + cdk_common::database::Error::Database(e.to_string().into()) + }) + }) + .transpose() + } + + async fn remove_keys(&self, id: &cdk_common::nuts::Id) -> Result<(), Self::Err> { + let ffi_id = (*id).into(); + self.ffi_db + .remove_keys(ffi_id) + .await + .map_err(|e| cdk_common::database::Error::Database(e.to_string().into())) + } + + // Proof Management + async fn update_proofs( + &self, + added: Vec, + removed_ys: Vec, + ) -> Result<(), Self::Err> { + let ffi_added: Vec = added.into_iter().map(Into::into).collect(); + let ffi_removed_ys: Vec = removed_ys.into_iter().map(Into::into).collect(); + + self.ffi_db + .update_proofs(ffi_added, ffi_removed_ys) + .await + .map_err(|e| cdk_common::database::Error::Database(e.to_string().into())) + } + + async fn get_proofs( + &self, + mint_url: Option, + unit: Option, + state: Option>, + spending_conditions: Option>, + ) -> Result, Self::Err> { + let ffi_mint_url = mint_url.map(Into::into); + let ffi_unit = unit.map(Into::into); + let ffi_state = state.map(|s| s.into_iter().map(Into::into).collect()); + let ffi_spending_conditions = + spending_conditions.map(|sc| sc.into_iter().map(Into::into).collect()); + + let result = self + .ffi_db + .get_proofs(ffi_mint_url, ffi_unit, ffi_state, ffi_spending_conditions) + .await + .map_err(|e| cdk_common::database::Error::Database(e.to_string().into()))?; + + // Convert back to CDK ProofInfo + let cdk_result: Result, cdk_common::database::Error> = + result + .into_iter() + .map(|info| { + Ok(cdk_common::common::ProofInfo { + proof: info.proof.inner.clone(), + y: info.y.try_into().map_err(|e: FfiError| { + cdk_common::database::Error::Database(e.to_string().into()) + })?, + mint_url: info.mint_url.try_into().map_err(|e: FfiError| { + cdk_common::database::Error::Database(e.to_string().into()) + })?, + state: info.state.into(), + spending_condition: info + .spending_condition + .map(|sc| sc.try_into()) + .transpose() + .map_err(|e: FfiError| { + cdk_common::database::Error::Database(e.to_string().into()) + })?, + unit: info.unit.into(), + }) + }) + .collect(); + + cdk_result + } + + async fn update_proofs_state( + &self, + ys: Vec, + state: cdk_common::nuts::State, + ) -> Result<(), Self::Err> { + let ffi_ys: Vec = ys.into_iter().map(Into::into).collect(); + let ffi_state = state.into(); + + self.ffi_db + .update_proofs_state(ffi_ys, ffi_state) + .await + .map_err(|e| cdk_common::database::Error::Database(e.to_string().into())) + } + + // Keyset Counter Management + async fn increment_keyset_counter( + &self, + keyset_id: &cdk_common::nuts::Id, + count: u32, + ) -> Result { + let ffi_id = (*keyset_id).into(); + self.ffi_db + .increment_keyset_counter(ffi_id, count) + .await + .map_err(|e| cdk_common::database::Error::Database(e.to_string().into())) + } + + // Transaction Management + async fn add_transaction( + &self, + transaction: cdk_common::wallet::Transaction, + ) -> Result<(), Self::Err> { + let ffi_transaction = transaction.into(); + self.ffi_db + .add_transaction(ffi_transaction) + .await + .map_err(|e| cdk_common::database::Error::Database(e.to_string().into())) + } + + async fn get_transaction( + &self, + transaction_id: cdk_common::wallet::TransactionId, + ) -> Result, Self::Err> { + let ffi_id = transaction_id.into(); + let result = self + .ffi_db + .get_transaction(ffi_id) + .await + .map_err(|e| cdk_common::database::Error::Database(e.to_string().into()))?; + + result + .map(|tx| tx.try_into()) + .transpose() + .map_err(|e: FfiError| cdk_common::database::Error::Database(e.to_string().into())) + } + + async fn list_transactions( + &self, + mint_url: Option, + direction: Option, + unit: Option, + ) -> Result, Self::Err> { + let ffi_mint_url = mint_url.map(Into::into); + let ffi_direction = direction.map(Into::into); + let ffi_unit = unit.map(Into::into); + + let result = self + .ffi_db + .list_transactions(ffi_mint_url, ffi_direction, ffi_unit) + .await + .map_err(|e| cdk_common::database::Error::Database(e.to_string().into()))?; + + result + .into_iter() + .map(|tx| tx.try_into()) + .collect::, FfiError>>() + .map_err(|e| cdk_common::database::Error::Database(e.to_string().into())) + } + + async fn remove_transaction( + &self, + transaction_id: cdk_common::wallet::TransactionId, + ) -> Result<(), Self::Err> { + let ffi_id = transaction_id.into(); + self.ffi_db + .remove_transaction(ffi_id) + .await + .map_err(|e| cdk_common::database::Error::Database(e.to_string().into())) + } +} + +/// FFI-compatible WalletSqliteDatabase implementation that implements the WalletDatabase trait +#[derive(uniffi::Object)] +pub struct WalletSqliteDatabase { + inner: Arc, +} + +impl WalletSqliteDatabase { + // No additional methods needed beyond the trait implementation +} + +#[uniffi::export] +impl WalletSqliteDatabase { + /// Create a new WalletSqliteDatabase with the given work directory + #[uniffi::constructor] + pub async fn new(file_path: String) -> Result, FfiError> { + let db = CdkWalletSqliteDatabase::new(file_path.as_str()) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + Ok(Arc::new(Self { + inner: Arc::new(db), + })) + } + + /// Create an in-memory database + #[uniffi::constructor] + pub async fn new_in_memory() -> Result, FfiError> { + let db = cdk_sqlite::wallet::memory::empty() + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + Ok(Arc::new(Self { + inner: Arc::new(db), + })) + } +} + +#[uniffi::export(async_runtime = "tokio")] +#[async_trait::async_trait] +impl WalletDatabase for WalletSqliteDatabase { + // Mint Management + async fn add_mint( + &self, + mint_url: MintUrl, + mint_info: Option, + ) -> Result<(), FfiError> { + let cdk_mint_url = mint_url.try_into()?; + let cdk_mint_info = mint_info.map(Into::into); + self.inner + .add_mint(cdk_mint_url, cdk_mint_info) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + async fn remove_mint(&self, mint_url: MintUrl) -> Result<(), FfiError> { + let cdk_mint_url = mint_url.try_into()?; + self.inner + .remove_mint(cdk_mint_url) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + async fn get_mint(&self, mint_url: MintUrl) -> Result, FfiError> { + let cdk_mint_url = mint_url.try_into()?; + let result = self + .inner + .get_mint(cdk_mint_url) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + Ok(result.map(Into::into)) + } + + async fn get_mints(&self) -> Result>, FfiError> { + let result = self + .inner + .get_mints() + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + Ok(result + .into_iter() + .map(|(k, v)| (k.into(), v.map(Into::into))) + .collect()) + } + + async fn update_mint_url( + &self, + old_mint_url: MintUrl, + new_mint_url: MintUrl, + ) -> Result<(), FfiError> { + let cdk_old_mint_url = old_mint_url.try_into()?; + let cdk_new_mint_url = new_mint_url.try_into()?; + self.inner + .update_mint_url(cdk_old_mint_url, cdk_new_mint_url) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + // Keyset Management + async fn add_mint_keysets( + &self, + mint_url: MintUrl, + keysets: Vec, + ) -> Result<(), FfiError> { + let cdk_mint_url = mint_url.try_into()?; + let cdk_keysets: Vec = + keysets.into_iter().map(Into::into).collect(); + self.inner + .add_mint_keysets(cdk_mint_url, cdk_keysets) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + async fn get_mint_keysets( + &self, + mint_url: MintUrl, + ) -> Result>, FfiError> { + let cdk_mint_url = mint_url.try_into()?; + let result = self + .inner + .get_mint_keysets(cdk_mint_url) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + Ok(result.map(|keysets| keysets.into_iter().map(Into::into).collect())) + } + + async fn get_keyset_by_id(&self, keyset_id: Id) -> Result, FfiError> { + let cdk_id = keyset_id.into(); + let result = self + .inner + .get_keyset_by_id(&cdk_id) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + Ok(result.map(Into::into)) + } + + // Mint Quote Management + async fn add_mint_quote(&self, quote: MintQuote) -> Result<(), FfiError> { + let cdk_quote = quote.try_into()?; + self.inner + .add_mint_quote(cdk_quote) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + async fn get_mint_quote(&self, quote_id: String) -> Result, FfiError> { + let result = self + .inner + .get_mint_quote("e_id) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + Ok(result.map(|q| q.into())) + } + + async fn get_mint_quotes(&self) -> Result, FfiError> { + let result = self + .inner + .get_mint_quotes() + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + Ok(result.into_iter().map(|q| q.into()).collect()) + } + + async fn remove_mint_quote(&self, quote_id: String) -> Result<(), FfiError> { + self.inner + .remove_mint_quote("e_id) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + // Melt Quote Management + async fn add_melt_quote(&self, quote: MeltQuote) -> Result<(), FfiError> { + let cdk_quote = quote.try_into()?; + self.inner + .add_melt_quote(cdk_quote) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + async fn get_melt_quote(&self, quote_id: String) -> Result, FfiError> { + let result = self + .inner + .get_melt_quote("e_id) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + Ok(result.map(|q| q.into())) + } + + async fn get_melt_quotes(&self) -> Result, FfiError> { + let result = self + .inner + .get_melt_quotes() + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + Ok(result.into_iter().map(|q| q.into()).collect()) + } + + async fn remove_melt_quote(&self, quote_id: String) -> Result<(), FfiError> { + self.inner + .remove_melt_quote("e_id) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + // Keys Management + async fn add_keys(&self, keyset: KeySet) -> Result<(), FfiError> { + // Convert FFI KeySet to cashu::KeySet + let cashu_keyset: cashu::KeySet = keyset.try_into()?; + self.inner + .add_keys(cashu_keyset) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + async fn get_keys(&self, id: Id) -> Result, FfiError> { + let cdk_id = id.into(); + let result = self + .inner + .get_keys(&cdk_id) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + Ok(result.map(Into::into)) + } + + async fn remove_keys(&self, id: Id) -> Result<(), FfiError> { + let cdk_id = id.into(); + self.inner + .remove_keys(&cdk_id) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + // Proof Management + async fn update_proofs( + &self, + added: Vec, + removed_ys: Vec, + ) -> Result<(), FfiError> { + // Convert FFI types to CDK types + let cdk_added: Result, FfiError> = added + .into_iter() + .map(|info| { + Ok::(cdk_common::common::ProofInfo { + proof: info.proof.inner.clone(), + y: info.y.try_into()?, + mint_url: info.mint_url.try_into()?, + state: info.state.into(), + spending_condition: info + .spending_condition + .map(|sc| sc.try_into()) + .transpose()?, + unit: info.unit.into(), + }) + }) + .collect(); + let cdk_added = cdk_added?; + + let cdk_removed_ys: Result, FfiError> = + removed_ys.into_iter().map(|pk| pk.try_into()).collect(); + let cdk_removed_ys = cdk_removed_ys?; + + self.inner + .update_proofs(cdk_added, cdk_removed_ys) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + async fn get_proofs( + &self, + mint_url: Option, + unit: Option, + state: Option>, + spending_conditions: Option>, + ) -> Result, FfiError> { + let cdk_mint_url = mint_url.map(|u| u.try_into()).transpose()?; + let cdk_unit = unit.map(Into::into); + let cdk_state = state.map(|s| s.into_iter().map(Into::into).collect()); + let cdk_spending_conditions: Option> = + spending_conditions + .map(|sc| { + sc.into_iter() + .map(|c| c.try_into()) + .collect::, FfiError>>() + }) + .transpose()?; + + let result = self + .inner + .get_proofs(cdk_mint_url, cdk_unit, cdk_state, cdk_spending_conditions) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + + Ok(result.into_iter().map(Into::into).collect()) + } + + async fn update_proofs_state( + &self, + ys: Vec, + state: ProofState, + ) -> Result<(), FfiError> { + let cdk_ys: Result, FfiError> = + ys.into_iter().map(|pk| pk.try_into()).collect(); + let cdk_ys = cdk_ys?; + let cdk_state = state.into(); + + self.inner + .update_proofs_state(cdk_ys, cdk_state) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + // Keyset Counter Management + async fn increment_keyset_counter(&self, keyset_id: Id, count: u32) -> Result { + let cdk_id = keyset_id.into(); + self.inner + .increment_keyset_counter(&cdk_id, count) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + // Transaction Management + async fn add_transaction(&self, transaction: Transaction) -> Result<(), FfiError> { + // Convert FFI Transaction to CDK Transaction using TryFrom + let cdk_transaction: cdk_common::wallet::Transaction = transaction.try_into()?; + + self.inner + .add_transaction(cdk_transaction) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + async fn get_transaction( + &self, + transaction_id: TransactionId, + ) -> Result, FfiError> { + let cdk_id = transaction_id.try_into()?; + let result = self + .inner + .get_transaction(cdk_id) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + Ok(result.map(Into::into)) + } + + async fn list_transactions( + &self, + mint_url: Option, + direction: Option, + unit: Option, + ) -> Result, FfiError> { + let cdk_mint_url = mint_url.map(|u| u.try_into()).transpose()?; + let cdk_direction = direction.map(Into::into); + let cdk_unit = unit.map(Into::into); + + let result = self + .inner + .list_transactions(cdk_mint_url, cdk_direction, cdk_unit) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + + Ok(result.into_iter().map(Into::into).collect()) + } + + async fn remove_transaction(&self, transaction_id: TransactionId) -> Result<(), FfiError> { + let cdk_id = transaction_id.try_into()?; + self.inner + .remove_transaction(cdk_id) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } +} + +/// Helper function to create a CDK database from the FFI trait +pub fn create_cdk_database_from_ffi( + ffi_db: Arc, +) -> Arc + Send + Sync> { + Arc::new(WalletDatabaseBridge::new(ffi_db)) +} diff --git a/crates/cdk-ffi/src/error.rs b/crates/cdk-ffi/src/error.rs new file mode 100644 index 000000000..e4be9f0ef --- /dev/null +++ b/crates/cdk-ffi/src/error.rs @@ -0,0 +1,124 @@ +//! FFI Error types + +use cdk::Error as CdkError; + +/// FFI Error type that wraps CDK errors for cross-language use +#[derive(Debug, thiserror::Error, uniffi::Error)] +#[uniffi(flat_error)] +pub enum FfiError { + /// Generic error with message + #[error("CDK Error: {msg}")] + Generic { msg: String }, + + /// Amount overflow + #[error("Amount overflow")] + AmountOverflow, + + /// Division by zero + #[error("Division by zero")] + DivisionByZero, + + /// Amount error + #[error("Amount error: {msg}")] + Amount { msg: String }, + + /// Payment failed + #[error("Payment failed")] + PaymentFailed, + + /// Payment pending + #[error("Payment pending")] + PaymentPending, + + /// Insufficient funds + #[error("Insufficient funds")] + InsufficientFunds, + + /// Database error + #[error("Database error: {msg}")] + Database { msg: String }, + + /// Network error + #[error("Network error: {msg}")] + Network { msg: String }, + + /// Invalid token + #[error("Invalid token: {msg}")] + InvalidToken { msg: String }, + + /// Wallet error + #[error("Wallet error: {msg}")] + Wallet { msg: String }, + + /// Keyset unknown + #[error("Keyset unknown")] + KeysetUnknown, + + /// Unit not supported + #[error("Unit not supported")] + UnitNotSupported, + + /// Runtime task join error + #[error("Runtime task join error: {msg}")] + RuntimeTaskJoin { msg: String }, + + /// Invalid mnemonic phrase + #[error("Invalid mnemonic: {msg}")] + InvalidMnemonic { msg: String }, + + /// URL parsing error + #[error("Invalid URL: {msg}")] + InvalidUrl { msg: String }, + + /// Hex format error + #[error("Invalid hex format: {msg}")] + InvalidHex { msg: String }, + + /// Cryptographic key parsing error + #[error("Invalid cryptographic key: {msg}")] + InvalidCryptographicKey { msg: String }, + + /// Serialization/deserialization error + #[error("Serialization error: {msg}")] + Serialization { msg: String }, +} + +impl From for FfiError { + fn from(err: CdkError) -> Self { + match err { + CdkError::AmountOverflow => FfiError::AmountOverflow, + CdkError::PaymentFailed => FfiError::PaymentFailed, + CdkError::PaymentPending => FfiError::PaymentPending, + CdkError::InsufficientFunds => FfiError::InsufficientFunds, + CdkError::UnsupportedUnit => FfiError::UnitNotSupported, + CdkError::KeysetUnknown(_) => FfiError::KeysetUnknown, + _ => FfiError::Generic { + msg: err.to_string(), + }, + } + } +} + +impl From for FfiError { + fn from(err: cdk::amount::Error) -> Self { + FfiError::Amount { + msg: err.to_string(), + } + } +} + +impl From for FfiError { + fn from(err: cdk_common::nut00::Error) -> Self { + FfiError::Generic { + msg: err.to_string(), + } + } +} + +impl From for FfiError { + fn from(err: serde_json::Error) -> Self { + FfiError::Serialization { + msg: err.to_string(), + } + } +} diff --git a/crates/cdk-ffi/src/lib.rs b/crates/cdk-ffi/src/lib.rs new file mode 100644 index 000000000..c8c37c335 --- /dev/null +++ b/crates/cdk-ffi/src/lib.rs @@ -0,0 +1,285 @@ +//! CDK FFI Bindings +//! +//! UniFFI bindings for the CDK Wallet and related types. + +pub mod database; +pub mod error; +pub mod types; +pub mod wallet; + +pub use database::*; +pub use error::*; +pub use types::*; +pub use wallet::*; + +uniffi::setup_scaffolding!(); + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn test_amount_conversion() { + let amount = Amount::new(1000); + assert_eq!(amount.value, 1000); + assert!(!amount.is_zero()); + + let zero = Amount::zero(); + assert!(zero.is_zero()); + } + + #[test] + fn test_currency_unit_conversion() { + use cdk::nuts::CurrencyUnit as CdkCurrencyUnit; + + let unit = CurrencyUnit::Sat; + let cdk_unit: CdkCurrencyUnit = unit.into(); + let back: CurrencyUnit = cdk_unit.into(); + assert_eq!(back, CurrencyUnit::Sat); + } + + #[test] + fn test_mint_url_creation() { + let url = MintUrl::new("https://mint.example.com".to_string()); + assert!(url.is_ok()); + + let invalid_url = MintUrl::new("not-a-url".to_string()); + assert!(invalid_url.is_err()); + } + + #[test] + fn test_send_options_default() { + let options = SendOptions::default(); + assert!(options.memo.is_none()); + assert!(options.conditions.is_none()); + assert!(matches!(options.amount_split_target, SplitTarget::None)); + assert!(matches!(options.send_kind, SendKind::OnlineExact)); + assert!(!options.include_fee); + assert!(options.max_proofs.is_none()); + assert!(options.metadata.is_empty()); + } + + #[test] + fn test_receive_options_default() { + let options = ReceiveOptions::default(); + assert!(matches!(options.amount_split_target, SplitTarget::None)); + assert!(options.p2pk_signing_keys.is_empty()); + assert!(options.preimages.is_empty()); + assert!(options.metadata.is_empty()); + } + + #[test] + fn test_send_memo() { + let memo_text = "Test memo".to_string(); + let memo = SendMemo { + memo: memo_text.clone(), + include_memo: true, + }; + + assert_eq!(memo.memo, memo_text); + assert!(memo.include_memo); + } + + #[test] + fn test_split_target_variants() { + let split_none = SplitTarget::None; + assert!(matches!(split_none, SplitTarget::None)); + + let amount = Amount::new(1000); + let split_value = SplitTarget::Value { amount }; + assert!(matches!(split_value, SplitTarget::Value { .. })); + + let amounts = vec![Amount::new(100), Amount::new(200)]; + let split_values = SplitTarget::Values { amounts }; + assert!(matches!(split_values, SplitTarget::Values { .. })); + } + + #[test] + fn test_send_kind_variants() { + let online_exact = SendKind::OnlineExact; + assert!(matches!(online_exact, SendKind::OnlineExact)); + + let tolerance = Amount::new(50); + let online_tolerance = SendKind::OnlineTolerance { tolerance }; + assert!(matches!(online_tolerance, SendKind::OnlineTolerance { .. })); + + let offline_exact = SendKind::OfflineExact; + assert!(matches!(offline_exact, SendKind::OfflineExact)); + + let offline_tolerance = SendKind::OfflineTolerance { tolerance }; + assert!(matches!( + offline_tolerance, + SendKind::OfflineTolerance { .. } + )); + } + + #[test] + fn test_secret_key_from_hex() { + // Test valid hex string (64 characters) + let valid_hex = "a".repeat(64); + let secret_key = SecretKey::from_hex(valid_hex.clone()); + assert!(secret_key.is_ok()); + assert_eq!(secret_key.unwrap().hex, valid_hex); + + // Test invalid length + let invalid_length = "a".repeat(32); // 32 chars instead of 64 + let secret_key = SecretKey::from_hex(invalid_length); + assert!(secret_key.is_err()); + + // Test invalid characters + let invalid_chars = "g".repeat(64); // 'g' is not a valid hex character + let secret_key = SecretKey::from_hex(invalid_chars); + assert!(secret_key.is_err()); + } + + #[test] + fn test_secret_key_random() { + let key1 = SecretKey::random(); + let key2 = SecretKey::random(); + + // Keys should be different + assert_ne!(key1.hex, key2.hex); + + // Keys should be valid hex (64 characters) + assert_eq!(key1.hex.len(), 64); + assert_eq!(key2.hex.len(), 64); + assert!(key1.hex.chars().all(|c| c.is_ascii_hexdigit())); + assert!(key2.hex.chars().all(|c| c.is_ascii_hexdigit())); + } + + #[test] + fn test_send_options_with_all_fields() { + use std::collections::HashMap; + + let memo = SendMemo { + memo: "Test memo".to_string(), + include_memo: true, + }; + + let mut metadata = HashMap::new(); + metadata.insert("key1".to_string(), "value1".to_string()); + + let conditions = SpendingConditions::P2PK { + pubkey: "02a1633cafcc01ebfb6d78e39f687a1f0995c62fc95f51ead10a02ee0be551b5dc" + .to_string(), + conditions: None, + }; + + let options = SendOptions { + memo: Some(memo), + conditions: Some(conditions), + amount_split_target: SplitTarget::Value { + amount: Amount::new(1000), + }, + send_kind: SendKind::OnlineTolerance { + tolerance: Amount::new(50), + }, + include_fee: true, + max_proofs: Some(10), + metadata, + }; + + assert!(options.memo.is_some()); + assert!(options.conditions.is_some()); + assert!(matches!( + options.amount_split_target, + SplitTarget::Value { .. } + )); + assert!(matches!( + options.send_kind, + SendKind::OnlineTolerance { .. } + )); + assert!(options.include_fee); + assert_eq!(options.max_proofs, Some(10)); + assert!(!options.metadata.is_empty()); + } + + #[test] + fn test_receive_options_with_all_fields() { + use std::collections::HashMap; + + let secret_key = SecretKey::random(); + let mut metadata = HashMap::new(); + metadata.insert("key1".to_string(), "value1".to_string()); + + let options = ReceiveOptions { + amount_split_target: SplitTarget::Values { + amounts: vec![Amount::new(100), Amount::new(200)], + }, + p2pk_signing_keys: vec![secret_key], + preimages: vec!["preimage1".to_string(), "preimage2".to_string()], + metadata, + }; + + assert!(matches!( + options.amount_split_target, + SplitTarget::Values { .. } + )); + assert_eq!(options.p2pk_signing_keys.len(), 1); + assert_eq!(options.preimages.len(), 2); + assert!(!options.metadata.is_empty()); + } + + #[test] + fn test_wallet_config() { + let config = WalletConfig { + target_proof_count: None, + }; + assert!(config.target_proof_count.is_none()); + + let config_with_values = WalletConfig { + target_proof_count: Some(5), + }; + assert_eq!(config_with_values.target_proof_count, Some(5)); + } + + #[test] + fn test_mnemonic_generation() { + // Test mnemonic generation + let mnemonic = generate_mnemonic().unwrap(); + assert!(!mnemonic.is_empty()); + assert_eq!(mnemonic.split_whitespace().count(), 12); + + // Verify it's a valid mnemonic by trying to parse it + use bip39::Mnemonic; + let parsed = Mnemonic::parse(&mnemonic); + assert!(parsed.is_ok()); + } + + #[test] + fn test_mnemonic_validation() { + // Test with valid mnemonic + let mnemonic = generate_mnemonic().unwrap(); + use bip39::Mnemonic; + let parsed = Mnemonic::parse(&mnemonic); + assert!(parsed.is_ok()); + + // Test with invalid mnemonic + let invalid_mnemonic = "invalid mnemonic phrase that should not work"; + let parsed_invalid = Mnemonic::parse(invalid_mnemonic); + assert!(parsed_invalid.is_err()); + + // Test mnemonic word count variations + let mnemonic_12 = generate_mnemonic().unwrap(); + assert_eq!(mnemonic_12.split_whitespace().count(), 12); + } + + #[test] + fn test_mnemonic_to_entropy() { + // Test with generated mnemonic + let mnemonic = generate_mnemonic().unwrap(); + let entropy = mnemonic_to_entropy(mnemonic.clone()).unwrap(); + + // For a 12-word mnemonic, entropy should be 16 bytes (128 bits) + assert_eq!(entropy.len(), 16); + + // Test that we can recreate the mnemonic from entropy + use bip39::Mnemonic; + let recreated_mnemonic = Mnemonic::from_entropy(&entropy).unwrap(); + assert_eq!(recreated_mnemonic.to_string(), mnemonic); + + // Test with invalid mnemonic + let invalid_result = mnemonic_to_entropy("invalid mnemonic".to_string()); + assert!(invalid_result.is_err()); + } +} diff --git a/crates/cdk-ffi/src/types.rs b/crates/cdk-ffi/src/types.rs new file mode 100644 index 000000000..4c438e99b --- /dev/null +++ b/crates/cdk-ffi/src/types.rs @@ -0,0 +1,2636 @@ +//! FFI-compatible types + +use std::collections::HashMap; +use std::str::FromStr; +use std::sync::Mutex; + +use cdk::nuts::{CurrencyUnit as CdkCurrencyUnit, State as CdkState}; +use cdk::Amount as CdkAmount; +use cdk_common::pub_sub::SubId; +use serde::{Deserialize, Serialize}; + +use crate::error::FfiError; + +/// FFI-compatible Amount type +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, uniffi::Record)] +#[serde(transparent)] +pub struct Amount { + pub value: u64, +} + +impl Amount { + pub fn new(value: u64) -> Self { + Self { value } + } + + pub fn zero() -> Self { + Self { value: 0 } + } + + pub fn is_zero(&self) -> bool { + self.value == 0 + } + + pub fn convert_unit( + &self, + current_unit: CurrencyUnit, + target_unit: CurrencyUnit, + ) -> Result { + Ok(CdkAmount::from(self.value) + .convert_unit(¤t_unit.into(), &target_unit.into()) + .map(Into::into)?) + } + + pub fn add(&self, other: Amount) -> Result { + let self_amount = CdkAmount::from(self.value); + let other_amount = CdkAmount::from(other.value); + self_amount + .checked_add(other_amount) + .map(Into::into) + .ok_or(FfiError::AmountOverflow) + } + + pub fn subtract(&self, other: Amount) -> Result { + let self_amount = CdkAmount::from(self.value); + let other_amount = CdkAmount::from(other.value); + self_amount + .checked_sub(other_amount) + .map(Into::into) + .ok_or(FfiError::AmountOverflow) + } + + pub fn multiply(&self, factor: u64) -> Result { + let self_amount = CdkAmount::from(self.value); + let factor_amount = CdkAmount::from(factor); + self_amount + .checked_mul(factor_amount) + .map(Into::into) + .ok_or(FfiError::AmountOverflow) + } + + pub fn divide(&self, divisor: u64) -> Result { + if divisor == 0 { + return Err(FfiError::DivisionByZero); + } + let self_amount = CdkAmount::from(self.value); + let divisor_amount = CdkAmount::from(divisor); + self_amount + .checked_div(divisor_amount) + .map(Into::into) + .ok_or(FfiError::AmountOverflow) + } +} + +impl From for Amount { + fn from(amount: CdkAmount) -> Self { + Self { + value: u64::from(amount), + } + } +} + +impl From for CdkAmount { + fn from(amount: Amount) -> Self { + CdkAmount::from(amount.value) + } +} + +/// FFI-compatible Currency Unit +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, uniffi::Enum)] +pub enum CurrencyUnit { + Sat, + Msat, + Usd, + Eur, + Auth, + Custom { unit: String }, +} + +impl From for CurrencyUnit { + fn from(unit: CdkCurrencyUnit) -> Self { + match unit { + CdkCurrencyUnit::Sat => CurrencyUnit::Sat, + CdkCurrencyUnit::Msat => CurrencyUnit::Msat, + CdkCurrencyUnit::Usd => CurrencyUnit::Usd, + CdkCurrencyUnit::Eur => CurrencyUnit::Eur, + CdkCurrencyUnit::Auth => CurrencyUnit::Auth, + CdkCurrencyUnit::Custom(s) => CurrencyUnit::Custom { unit: s }, + _ => CurrencyUnit::Sat, // Default for unknown units + } + } +} + +impl From for CdkCurrencyUnit { + fn from(unit: CurrencyUnit) -> Self { + match unit { + CurrencyUnit::Sat => CdkCurrencyUnit::Sat, + CurrencyUnit::Msat => CdkCurrencyUnit::Msat, + CurrencyUnit::Usd => CdkCurrencyUnit::Usd, + CurrencyUnit::Eur => CdkCurrencyUnit::Eur, + CurrencyUnit::Auth => CdkCurrencyUnit::Auth, + CurrencyUnit::Custom { unit } => CdkCurrencyUnit::Custom(unit), + } + } +} + +/// FFI-compatible Mint URL +#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize, uniffi::Record)] +#[serde(transparent)] +pub struct MintUrl { + pub url: String, +} + +impl MintUrl { + pub fn new(url: String) -> Result { + // Validate URL format + url::Url::parse(&url).map_err(|e| FfiError::InvalidUrl { msg: e.to_string() })?; + + Ok(Self { url }) + } +} + +impl From for MintUrl { + fn from(mint_url: cdk::mint_url::MintUrl) -> Self { + Self { + url: mint_url.to_string(), + } + } +} + +impl TryFrom for cdk::mint_url::MintUrl { + type Error = FfiError; + + fn try_from(mint_url: MintUrl) -> Result { + cdk::mint_url::MintUrl::from_str(&mint_url.url) + .map_err(|e| FfiError::InvalidUrl { msg: e.to_string() }) + } +} + +/// FFI-compatible Proof state +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, uniffi::Enum)] +pub enum ProofState { + Unspent, + Pending, + Spent, + Reserved, + PendingSpent, +} + +impl From for ProofState { + fn from(state: CdkState) -> Self { + match state { + CdkState::Unspent => ProofState::Unspent, + CdkState::Pending => ProofState::Pending, + CdkState::Spent => ProofState::Spent, + CdkState::Reserved => ProofState::Reserved, + CdkState::PendingSpent => ProofState::PendingSpent, + } + } +} + +impl From for CdkState { + fn from(state: ProofState) -> Self { + match state { + ProofState::Unspent => CdkState::Unspent, + ProofState::Pending => CdkState::Pending, + ProofState::Spent => CdkState::Spent, + ProofState::Reserved => CdkState::Reserved, + ProofState::PendingSpent => CdkState::PendingSpent, + } + } +} + +/// FFI-compatible Token +#[derive(Debug, uniffi::Object)] +pub struct Token { + pub(crate) inner: cdk::nuts::Token, +} + +impl std::fmt::Display for Token { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + write!(f, "{}", self.inner) + } +} + +impl FromStr for Token { + type Err = FfiError; + + fn from_str(s: &str) -> Result { + let token = cdk::nuts::Token::from_str(s) + .map_err(|e| FfiError::InvalidToken { msg: e.to_string() })?; + Ok(Token { inner: token }) + } +} + +impl From for Token { + fn from(token: cdk::nuts::Token) -> Self { + Self { inner: token } + } +} + +impl From for cdk::nuts::Token { + fn from(token: Token) -> Self { + token.inner + } +} + +#[uniffi::export] +impl Token { + /// Create a new Token from string + #[uniffi::constructor] + pub fn from_string(encoded_token: String) -> Result { + let token = cdk::nuts::Token::from_str(&encoded_token) + .map_err(|e| FfiError::InvalidToken { msg: e.to_string() })?; + Ok(Token { inner: token }) + } + + /// Get the total value of the token + pub fn value(&self) -> Result { + Ok(self.inner.value()?.into()) + } + + /// Get the memo from the token + pub fn memo(&self) -> Option { + self.inner.memo().clone() + } + + /// Get the currency unit + pub fn unit(&self) -> Option { + self.inner.unit().map(Into::into) + } + + /// Get the mint URL + pub fn mint_url(&self) -> Result { + Ok(self.inner.mint_url()?.into()) + } + + /// Get proofs from the token (simplified - no keyset filtering for now) + pub fn proofs_simple(&self) -> Result { + // For now, return empty keysets to get all proofs + let empty_keysets = vec![]; + let proofs = self.inner.proofs(&empty_keysets)?; + Ok(proofs + .into_iter() + .map(|p| std::sync::Arc::new(p.into())) + .collect()) + } + + /// Convert token to raw bytes + pub fn to_raw_bytes(&self) -> Result, FfiError> { + Ok(self.inner.to_raw_bytes()?) + } + + /// Encode token to string representation + pub fn encode(&self) -> String { + self.to_string() + } + + /// Decode token from string representation + #[uniffi::constructor] + pub fn decode(encoded_token: String) -> Result { + encoded_token.parse() + } +} + +/// FFI-compatible SendMemo +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct SendMemo { + /// Memo text + pub memo: String, + /// Include memo in token + pub include_memo: bool, +} + +impl From for cdk::wallet::SendMemo { + fn from(memo: SendMemo) -> Self { + cdk::wallet::SendMemo { + memo: memo.memo, + include_memo: memo.include_memo, + } + } +} + +impl From for SendMemo { + fn from(memo: cdk::wallet::SendMemo) -> Self { + Self { + memo: memo.memo, + include_memo: memo.include_memo, + } + } +} + +impl SendMemo { + /// Convert SendMemo to JSON string + pub fn to_json(&self) -> Result { + Ok(serde_json::to_string(self)?) + } +} + +/// Decode SendMemo from JSON string +#[uniffi::export] +pub fn decode_send_memo(json: String) -> Result { + Ok(serde_json::from_str(&json)?) +} + +/// Encode SendMemo to JSON string +#[uniffi::export] +pub fn encode_send_memo(memo: SendMemo) -> Result { + Ok(serde_json::to_string(&memo)?) +} + +/// FFI-compatible SplitTarget +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Enum)] +pub enum SplitTarget { + /// Default target; least amount of proofs + None, + /// Target amount for wallet to have most proofs that add up to value + Value { amount: Amount }, + /// Specific amounts to split into (must equal amount being split) + Values { amounts: Vec }, +} + +impl From for cdk::amount::SplitTarget { + fn from(target: SplitTarget) -> Self { + match target { + SplitTarget::None => cdk::amount::SplitTarget::None, + SplitTarget::Value { amount } => cdk::amount::SplitTarget::Value(amount.into()), + SplitTarget::Values { amounts } => { + cdk::amount::SplitTarget::Values(amounts.into_iter().map(Into::into).collect()) + } + } + } +} + +impl From for SplitTarget { + fn from(target: cdk::amount::SplitTarget) -> Self { + match target { + cdk::amount::SplitTarget::None => SplitTarget::None, + cdk::amount::SplitTarget::Value(amount) => SplitTarget::Value { + amount: amount.into(), + }, + cdk::amount::SplitTarget::Values(amounts) => SplitTarget::Values { + amounts: amounts.into_iter().map(Into::into).collect(), + }, + } + } +} + +/// FFI-compatible SendKind +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Enum)] +pub enum SendKind { + /// Allow online swap before send if wallet does not have exact amount + OnlineExact, + /// Prefer offline send if difference is less than tolerance + OnlineTolerance { tolerance: Amount }, + /// Wallet cannot do an online swap and selected proof must be exactly send amount + OfflineExact, + /// Wallet must remain offline but can over pay if below tolerance + OfflineTolerance { tolerance: Amount }, +} + +impl From for cdk_common::wallet::SendKind { + fn from(kind: SendKind) -> Self { + match kind { + SendKind::OnlineExact => cdk_common::wallet::SendKind::OnlineExact, + SendKind::OnlineTolerance { tolerance } => { + cdk_common::wallet::SendKind::OnlineTolerance(tolerance.into()) + } + SendKind::OfflineExact => cdk_common::wallet::SendKind::OfflineExact, + SendKind::OfflineTolerance { tolerance } => { + cdk_common::wallet::SendKind::OfflineTolerance(tolerance.into()) + } + } + } +} + +impl From for SendKind { + fn from(kind: cdk_common::wallet::SendKind) -> Self { + match kind { + cdk_common::wallet::SendKind::OnlineExact => SendKind::OnlineExact, + cdk_common::wallet::SendKind::OnlineTolerance(tolerance) => SendKind::OnlineTolerance { + tolerance: tolerance.into(), + }, + cdk_common::wallet::SendKind::OfflineExact => SendKind::OfflineExact, + cdk_common::wallet::SendKind::OfflineTolerance(tolerance) => { + SendKind::OfflineTolerance { + tolerance: tolerance.into(), + } + } + } + } +} + +/// FFI-compatible Send options +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct SendOptions { + /// Memo + pub memo: Option, + /// Spending conditions + pub conditions: Option, + /// Amount split target + pub amount_split_target: SplitTarget, + /// Send kind + pub send_kind: SendKind, + /// Include fee + pub include_fee: bool, + /// Maximum number of proofs to include in the token + pub max_proofs: Option, + /// Metadata + pub metadata: HashMap, +} + +impl Default for SendOptions { + fn default() -> Self { + Self { + memo: None, + conditions: None, + amount_split_target: SplitTarget::None, + send_kind: SendKind::OnlineExact, + include_fee: false, + max_proofs: None, + metadata: HashMap::new(), + } + } +} + +impl From for cdk::wallet::SendOptions { + fn from(opts: SendOptions) -> Self { + cdk::wallet::SendOptions { + memo: opts.memo.map(Into::into), + conditions: opts.conditions.and_then(|c| c.try_into().ok()), + amount_split_target: opts.amount_split_target.into(), + send_kind: opts.send_kind.into(), + include_fee: opts.include_fee, + max_proofs: opts.max_proofs.map(|p| p as usize), + metadata: opts.metadata, + } + } +} + +impl From for SendOptions { + fn from(opts: cdk::wallet::SendOptions) -> Self { + Self { + memo: opts.memo.map(Into::into), + conditions: opts.conditions.map(Into::into), + amount_split_target: opts.amount_split_target.into(), + send_kind: opts.send_kind.into(), + include_fee: opts.include_fee, + max_proofs: opts.max_proofs.map(|p| p as u32), + metadata: opts.metadata, + } + } +} + +impl SendOptions { + /// Convert SendOptions to JSON string + pub fn to_json(&self) -> Result { + Ok(serde_json::to_string(self)?) + } +} + +/// Decode SendOptions from JSON string +#[uniffi::export] +pub fn decode_send_options(json: String) -> Result { + Ok(serde_json::from_str(&json)?) +} + +/// Encode SendOptions to JSON string +#[uniffi::export] +pub fn encode_send_options(options: SendOptions) -> Result { + Ok(serde_json::to_string(&options)?) +} + +/// FFI-compatible SecretKey +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +#[serde(transparent)] +pub struct SecretKey { + /// Hex-encoded secret key (64 characters) + pub hex: String, +} + +impl SecretKey { + /// Create a new SecretKey from hex string + pub fn from_hex(hex: String) -> Result { + // Validate hex string length (should be 64 characters for 32 bytes) + if hex.len() != 64 { + return Err(FfiError::InvalidHex { + msg: "Secret key hex must be exactly 64 characters (32 bytes)".to_string(), + }); + } + + // Validate hex format + if !hex.chars().all(|c| c.is_ascii_hexdigit()) { + return Err(FfiError::InvalidHex { + msg: "Secret key hex contains invalid characters".to_string(), + }); + } + + Ok(Self { hex }) + } + + /// Generate a random secret key + pub fn random() -> Self { + use cdk::nuts::SecretKey as CdkSecretKey; + let secret_key = CdkSecretKey::generate(); + Self { + hex: secret_key.to_secret_hex(), + } + } +} + +impl From for cdk::nuts::SecretKey { + fn from(key: SecretKey) -> Self { + // This will panic if hex is invalid, but we validate in from_hex() + cdk::nuts::SecretKey::from_hex(&key.hex).expect("Invalid secret key hex") + } +} + +impl From for SecretKey { + fn from(key: cdk::nuts::SecretKey) -> Self { + Self { + hex: key.to_secret_hex(), + } + } +} + +/// FFI-compatible Receive options +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct ReceiveOptions { + /// Amount split target + pub amount_split_target: SplitTarget, + /// P2PK signing keys + pub p2pk_signing_keys: Vec, + /// Preimages for HTLC conditions + pub preimages: Vec, + /// Metadata + pub metadata: HashMap, +} + +impl Default for ReceiveOptions { + fn default() -> Self { + Self { + amount_split_target: SplitTarget::None, + p2pk_signing_keys: Vec::new(), + preimages: Vec::new(), + metadata: HashMap::new(), + } + } +} + +impl From for cdk::wallet::ReceiveOptions { + fn from(opts: ReceiveOptions) -> Self { + cdk::wallet::ReceiveOptions { + amount_split_target: opts.amount_split_target.into(), + p2pk_signing_keys: opts.p2pk_signing_keys.into_iter().map(Into::into).collect(), + preimages: opts.preimages, + metadata: opts.metadata, + } + } +} + +impl From for ReceiveOptions { + fn from(opts: cdk::wallet::ReceiveOptions) -> Self { + Self { + amount_split_target: opts.amount_split_target.into(), + p2pk_signing_keys: opts.p2pk_signing_keys.into_iter().map(Into::into).collect(), + preimages: opts.preimages, + metadata: opts.metadata, + } + } +} + +impl ReceiveOptions { + /// Convert ReceiveOptions to JSON string + pub fn to_json(&self) -> Result { + Ok(serde_json::to_string(self)?) + } +} + +/// Decode ReceiveOptions from JSON string +#[uniffi::export] +pub fn decode_receive_options(json: String) -> Result { + Ok(serde_json::from_str(&json)?) +} + +/// Encode ReceiveOptions to JSON string +#[uniffi::export] +pub fn encode_receive_options(options: ReceiveOptions) -> Result { + Ok(serde_json::to_string(&options)?) +} + +/// FFI-compatible Proof +#[derive(Debug, uniffi::Object)] +pub struct Proof { + pub(crate) inner: cdk::nuts::Proof, +} + +impl From for Proof { + fn from(proof: cdk::nuts::Proof) -> Self { + Self { inner: proof } + } +} + +impl From for cdk::nuts::Proof { + fn from(proof: Proof) -> Self { + proof.inner + } +} + +#[uniffi::export] +impl Proof { + /// Get the amount + pub fn amount(&self) -> Amount { + self.inner.amount.into() + } + + /// Get the secret as string + pub fn secret(&self) -> String { + self.inner.secret.to_string() + } + + /// Get the unblinded signature (C) as string + pub fn c(&self) -> String { + self.inner.c.to_string() + } + + /// Get the keyset ID as string + pub fn keyset_id(&self) -> String { + self.inner.keyset_id.to_string() + } + + /// Get the witness + pub fn witness(&self) -> Option { + self.inner.witness.as_ref().map(|w| w.clone().into()) + } + + /// Check if proof is active with given keyset IDs + pub fn is_active(&self, active_keyset_ids: Vec) -> bool { + use cdk::nuts::Id; + let ids: Vec = active_keyset_ids + .into_iter() + .filter_map(|id| Id::from_str(&id).ok()) + .collect(); + self.inner.is_active(&ids) + } + + /// Get the Y value (hash_to_curve of secret) + pub fn y(&self) -> Result { + Ok(self.inner.y()?.to_string()) + } + + /// Get the DLEQ proof if present + pub fn dleq(&self) -> Option { + self.inner.dleq.as_ref().map(|d| d.clone().into()) + } + + /// Check if proof has DLEQ proof + pub fn has_dleq(&self) -> bool { + self.inner.dleq.is_some() + } +} + +/// FFI-compatible Proofs (vector of Proof) +pub type Proofs = Vec>; + +/// FFI-compatible DLEQ proof for proofs +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct ProofDleq { + /// e value (hex-encoded SecretKey) + pub e: String, + /// s value (hex-encoded SecretKey) + pub s: String, + /// r value - blinding factor (hex-encoded SecretKey) + pub r: String, +} + +/// FFI-compatible DLEQ proof for blind signatures +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct BlindSignatureDleq { + /// e value (hex-encoded SecretKey) + pub e: String, + /// s value (hex-encoded SecretKey) + pub s: String, +} + +impl From for ProofDleq { + fn from(dleq: cdk::nuts::ProofDleq) -> Self { + Self { + e: dleq.e.to_secret_hex(), + s: dleq.s.to_secret_hex(), + r: dleq.r.to_secret_hex(), + } + } +} + +impl From for cdk::nuts::ProofDleq { + fn from(dleq: ProofDleq) -> Self { + Self { + e: cdk::nuts::SecretKey::from_hex(&dleq.e).expect("Invalid e hex"), + s: cdk::nuts::SecretKey::from_hex(&dleq.s).expect("Invalid s hex"), + r: cdk::nuts::SecretKey::from_hex(&dleq.r).expect("Invalid r hex"), + } + } +} + +impl From for BlindSignatureDleq { + fn from(dleq: cdk::nuts::BlindSignatureDleq) -> Self { + Self { + e: dleq.e.to_secret_hex(), + s: dleq.s.to_secret_hex(), + } + } +} + +impl From for cdk::nuts::BlindSignatureDleq { + fn from(dleq: BlindSignatureDleq) -> Self { + Self { + e: cdk::nuts::SecretKey::from_hex(&dleq.e).expect("Invalid e hex"), + s: cdk::nuts::SecretKey::from_hex(&dleq.s).expect("Invalid s hex"), + } + } +} + +/// Helper functions for Proofs +pub fn proofs_total_amount(proofs: &Proofs) -> Result { + let cdk_proofs: Vec = proofs.iter().map(|p| p.inner.clone()).collect(); + use cdk::nuts::ProofsMethods; + Ok(cdk_proofs.total_amount()?.into()) +} + +/// FFI-compatible MintQuote +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct MintQuote { + /// Quote ID + pub id: String, + /// Quote amount + pub amount: Option, + /// Currency unit + pub unit: CurrencyUnit, + /// Payment request + pub request: String, + /// Quote state + pub state: QuoteState, + /// Expiry timestamp + pub expiry: u64, + /// Mint URL + pub mint_url: MintUrl, + /// Amount issued + pub amount_issued: Amount, + /// Amount paid + pub amount_paid: Amount, + /// Payment method + pub payment_method: PaymentMethod, + /// Secret key (optional, hex-encoded) + pub secret_key: Option, +} + +impl From for MintQuote { + fn from(quote: cdk::wallet::MintQuote) -> Self { + Self { + id: quote.id.clone(), + amount: quote.amount.map(Into::into), + unit: quote.unit.clone().into(), + request: quote.request.clone(), + state: quote.state.into(), + expiry: quote.expiry, + mint_url: quote.mint_url.clone().into(), + amount_issued: quote.amount_issued.into(), + amount_paid: quote.amount_paid.into(), + payment_method: quote.payment_method.into(), + secret_key: quote.secret_key.map(|sk| sk.to_secret_hex()), + } + } +} + +impl TryFrom for cdk::wallet::MintQuote { + type Error = FfiError; + + fn try_from(quote: MintQuote) -> Result { + let secret_key = quote + .secret_key + .map(|hex| cdk::nuts::SecretKey::from_hex(&hex)) + .transpose() + .map_err(|e| FfiError::InvalidCryptographicKey { msg: e.to_string() })?; + + Ok(Self { + id: quote.id, + amount: quote.amount.map(Into::into), + unit: quote.unit.into(), + request: quote.request, + state: quote.state.into(), + expiry: quote.expiry, + mint_url: quote.mint_url.try_into()?, + amount_issued: quote.amount_issued.into(), + amount_paid: quote.amount_paid.into(), + payment_method: quote.payment_method.into(), + secret_key, + }) + } +} + +impl MintQuote { + /// Get total amount (amount + fees) + pub fn total_amount(&self) -> Amount { + if let Some(amount) = self.amount { + Amount::new(amount.value + self.amount_paid.value - self.amount_issued.value) + } else { + Amount::zero() + } + } + + /// Check if quote is expired + pub fn is_expired(&self, current_time: u64) -> bool { + current_time > self.expiry + } + + /// Get amount that can be minted + pub fn amount_mintable(&self) -> Amount { + Amount::new(self.amount_paid.value - self.amount_issued.value) + } + + /// Convert MintQuote to JSON string + pub fn to_json(&self) -> Result { + Ok(serde_json::to_string(self)?) + } +} + +/// Decode MintQuote from JSON string +#[uniffi::export] +pub fn decode_mint_quote(json: String) -> Result { + let quote: cdk::wallet::MintQuote = serde_json::from_str(&json)?; + Ok(quote.into()) +} + +/// Encode MintQuote to JSON string +#[uniffi::export] +pub fn encode_mint_quote(quote: MintQuote) -> Result { + Ok(serde_json::to_string("e)?) +} + +/// FFI-compatible MintQuoteBolt11Response +#[derive(Debug, uniffi::Object)] +pub struct MintQuoteBolt11Response { + /// Quote ID + pub quote: String, + /// Request string + pub request: String, + /// State of the quote + pub state: QuoteState, + /// Expiry timestamp (optional) + pub expiry: Option, + /// Amount (optional) + pub amount: Option, + /// Unit (optional) + pub unit: Option, + /// Pubkey (optional) + pub pubkey: Option, +} + +impl From> for MintQuoteBolt11Response { + fn from(response: cdk::nuts::MintQuoteBolt11Response) -> Self { + Self { + quote: response.quote, + request: response.request, + state: response.state.into(), + expiry: response.expiry, + amount: response.amount.map(Into::into), + unit: response.unit.map(Into::into), + pubkey: response.pubkey.map(|p| p.to_string()), + } + } +} + +#[uniffi::export] +impl MintQuoteBolt11Response { + /// Get quote ID + pub fn quote(&self) -> String { + self.quote.clone() + } + + /// Get request string + pub fn request(&self) -> String { + self.request.clone() + } + + /// Get state + pub fn state(&self) -> QuoteState { + self.state.clone() + } + + /// Get expiry + pub fn expiry(&self) -> Option { + self.expiry + } + + /// Get amount + pub fn amount(&self) -> Option { + self.amount + } + + /// Get unit + pub fn unit(&self) -> Option { + self.unit.clone() + } + + /// Get pubkey + pub fn pubkey(&self) -> Option { + self.pubkey.clone() + } +} + +/// FFI-compatible MeltQuoteBolt11Response +#[derive(Debug, uniffi::Object)] +pub struct MeltQuoteBolt11Response { + /// Quote ID + pub quote: String, + /// Amount + pub amount: Amount, + /// Fee reserve + pub fee_reserve: Amount, + /// State of the quote + pub state: QuoteState, + /// Expiry timestamp + pub expiry: u64, + /// Payment preimage (optional) + pub payment_preimage: Option, + /// Request string (optional) + pub request: Option, + /// Unit (optional) + pub unit: Option, +} + +impl From> for MeltQuoteBolt11Response { + fn from(response: cdk::nuts::MeltQuoteBolt11Response) -> Self { + Self { + quote: response.quote, + amount: response.amount.into(), + fee_reserve: response.fee_reserve.into(), + state: response.state.into(), + expiry: response.expiry, + payment_preimage: response.payment_preimage, + request: response.request, + unit: response.unit.map(Into::into), + } + } +} + +#[uniffi::export] +impl MeltQuoteBolt11Response { + /// Get quote ID + pub fn quote(&self) -> String { + self.quote.clone() + } + + /// Get amount + pub fn amount(&self) -> Amount { + self.amount + } + + /// Get fee reserve + pub fn fee_reserve(&self) -> Amount { + self.fee_reserve + } + + /// Get state + pub fn state(&self) -> QuoteState { + self.state.clone() + } + + /// Get expiry + pub fn expiry(&self) -> u64 { + self.expiry + } + + /// Get payment preimage + pub fn payment_preimage(&self) -> Option { + self.payment_preimage.clone() + } + + /// Get request + pub fn request(&self) -> Option { + self.request.clone() + } + + /// Get unit + pub fn unit(&self) -> Option { + self.unit.clone() + } +} + +/// FFI-compatible PaymentMethod +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, uniffi::Enum)] +pub enum PaymentMethod { + /// Bolt11 payment type + Bolt11, + /// Bolt12 payment type + Bolt12, + /// Custom payment type + Custom { method: String }, +} + +impl From for PaymentMethod { + fn from(method: cdk::nuts::PaymentMethod) -> Self { + match method { + cdk::nuts::PaymentMethod::Bolt11 => Self::Bolt11, + cdk::nuts::PaymentMethod::Bolt12 => Self::Bolt12, + cdk::nuts::PaymentMethod::Custom(s) => Self::Custom { method: s }, + } + } +} + +impl From for cdk::nuts::PaymentMethod { + fn from(method: PaymentMethod) -> Self { + match method { + PaymentMethod::Bolt11 => Self::Bolt11, + PaymentMethod::Bolt12 => Self::Bolt12, + PaymentMethod::Custom { method } => Self::Custom(method), + } + } +} + +/// FFI-compatible MeltQuote +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct MeltQuote { + /// Quote ID + pub id: String, + /// Quote amount + pub amount: Amount, + /// Currency unit + pub unit: CurrencyUnit, + /// Payment request + pub request: String, + /// Fee reserve + pub fee_reserve: Amount, + /// Quote state + pub state: QuoteState, + /// Expiry timestamp + pub expiry: u64, + /// Payment preimage + pub payment_preimage: Option, + /// Payment method + pub payment_method: PaymentMethod, +} + +impl From for MeltQuote { + fn from(quote: cdk::wallet::MeltQuote) -> Self { + Self { + id: quote.id.clone(), + amount: quote.amount.into(), + unit: quote.unit.clone().into(), + request: quote.request.clone(), + fee_reserve: quote.fee_reserve.into(), + state: quote.state.into(), + expiry: quote.expiry, + payment_preimage: quote.payment_preimage.clone(), + payment_method: quote.payment_method.into(), + } + } +} + +impl TryFrom for cdk::wallet::MeltQuote { + type Error = FfiError; + + fn try_from(quote: MeltQuote) -> Result { + Ok(Self { + id: quote.id, + amount: quote.amount.into(), + unit: quote.unit.into(), + request: quote.request, + fee_reserve: quote.fee_reserve.into(), + state: quote.state.into(), + expiry: quote.expiry, + payment_preimage: quote.payment_preimage, + payment_method: quote.payment_method.into(), + }) + } +} + +impl MeltQuote { + /// Convert MeltQuote to JSON string + pub fn to_json(&self) -> Result { + Ok(serde_json::to_string(self)?) + } +} + +/// Decode MeltQuote from JSON string +#[uniffi::export] +pub fn decode_melt_quote(json: String) -> Result { + let quote: cdk::wallet::MeltQuote = serde_json::from_str(&json)?; + Ok(quote.into()) +} + +/// Encode MeltQuote to JSON string +#[uniffi::export] +pub fn encode_melt_quote(quote: MeltQuote) -> Result { + Ok(serde_json::to_string("e)?) +} + +/// FFI-compatible QuoteState +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, uniffi::Enum)] +pub enum QuoteState { + Unpaid, + Paid, + Pending, + Issued, +} + +impl From for QuoteState { + fn from(state: cdk::nuts::nut05::QuoteState) -> Self { + match state { + cdk::nuts::nut05::QuoteState::Unpaid => QuoteState::Unpaid, + cdk::nuts::nut05::QuoteState::Paid => QuoteState::Paid, + cdk::nuts::nut05::QuoteState::Pending => QuoteState::Pending, + cdk::nuts::nut05::QuoteState::Unknown => QuoteState::Unpaid, + cdk::nuts::nut05::QuoteState::Failed => QuoteState::Unpaid, + } + } +} + +impl From for cdk::nuts::nut05::QuoteState { + fn from(state: QuoteState) -> Self { + match state { + QuoteState::Unpaid => cdk::nuts::nut05::QuoteState::Unpaid, + QuoteState::Paid => cdk::nuts::nut05::QuoteState::Paid, + QuoteState::Pending => cdk::nuts::nut05::QuoteState::Pending, + QuoteState::Issued => cdk::nuts::nut05::QuoteState::Paid, // Map issued to paid for melt quotes + } + } +} + +impl From for QuoteState { + fn from(state: cdk::nuts::MintQuoteState) -> Self { + match state { + cdk::nuts::MintQuoteState::Unpaid => QuoteState::Unpaid, + cdk::nuts::MintQuoteState::Paid => QuoteState::Paid, + cdk::nuts::MintQuoteState::Issued => QuoteState::Issued, + } + } +} + +impl From for cdk::nuts::MintQuoteState { + fn from(state: QuoteState) -> Self { + match state { + QuoteState::Unpaid => cdk::nuts::MintQuoteState::Unpaid, + QuoteState::Paid => cdk::nuts::MintQuoteState::Paid, + QuoteState::Issued => cdk::nuts::MintQuoteState::Issued, + QuoteState::Pending => cdk::nuts::MintQuoteState::Paid, // Map pending to paid + } + } +} + +// Note: MeltQuoteState is the same as nut05::QuoteState, so we don't need a separate impl + +/// FFI-compatible PreparedSend +#[derive(Debug, uniffi::Object)] +pub struct PreparedSend { + inner: Mutex>, + id: String, + amount: Amount, + proofs: Proofs, +} + +impl From for PreparedSend { + fn from(prepared: cdk::wallet::PreparedSend) -> Self { + let id = format!("{:?}", prepared); // Use debug format as ID + let amount = prepared.amount().into(); + let proofs = prepared + .proofs() + .iter() + .cloned() + .map(|p| std::sync::Arc::new(p.into())) + .collect(); + Self { + inner: Mutex::new(Some(prepared)), + id, + amount, + proofs, + } + } +} + +#[uniffi::export(async_runtime = "tokio")] +impl PreparedSend { + /// Get the prepared send ID + pub fn id(&self) -> String { + self.id.clone() + } + + /// Get the amount to send + pub fn amount(&self) -> Amount { + self.amount + } + + /// Get the proofs that will be used + pub fn proofs(&self) -> Proofs { + self.proofs.clone() + } + + /// Get the total fee for this send operation + pub fn fee(&self) -> Amount { + if let Ok(guard) = self.inner.lock() { + if let Some(ref inner) = *guard { + inner.fee().into() + } else { + Amount::new(0) + } + } else { + Amount::new(0) + } + } + + /// Confirm the prepared send and create a token + pub async fn confirm( + self: std::sync::Arc, + memo: Option, + ) -> Result { + let inner = { + if let Ok(mut guard) = self.inner.lock() { + guard.take() + } else { + return Err(FfiError::Generic { + msg: "Failed to acquire lock on PreparedSend".to_string(), + }); + } + }; + + if let Some(inner) = inner { + let send_memo = memo.map(|m| cdk::wallet::SendMemo::for_token(&m)); + let token = inner.confirm(send_memo).await?; + Ok(token.into()) + } else { + Err(FfiError::Generic { + msg: "PreparedSend has already been consumed or cancelled".to_string(), + }) + } + } + + /// Cancel the prepared send operation + pub async fn cancel(self: std::sync::Arc) -> Result<(), FfiError> { + let inner = { + if let Ok(mut guard) = self.inner.lock() { + guard.take() + } else { + return Err(FfiError::Generic { + msg: "Failed to acquire lock on PreparedSend".to_string(), + }); + } + }; + + if let Some(inner) = inner { + inner.cancel().await?; + Ok(()) + } else { + Err(FfiError::Generic { + msg: "PreparedSend has already been consumed or cancelled".to_string(), + }) + } + } +} + +/// FFI-compatible Melted result +#[derive(Debug, Clone, uniffi::Record)] +pub struct Melted { + pub state: QuoteState, + pub preimage: Option, + pub change: Option, + pub amount: Amount, + pub fee_paid: Amount, +} + +// MeltQuoteState is just an alias for nut05::QuoteState, so we don't need a separate implementation + +impl From for Melted { + fn from(melted: cdk_common::common::Melted) -> Self { + Self { + state: melted.state.into(), + preimage: melted.preimage, + change: melted.change.map(|proofs| { + proofs + .into_iter() + .map(|p| std::sync::Arc::new(p.into())) + .collect() + }), + amount: melted.amount.into(), + fee_paid: melted.fee_paid.into(), + } + } +} + +/// FFI-compatible MeltOptions +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Enum)] +pub enum MeltOptions { + /// MPP (Multi-Part Payments) options + Mpp { amount: Amount }, + /// Amountless options + Amountless { amount_msat: Amount }, +} + +impl From for cdk::nuts::MeltOptions { + fn from(opts: MeltOptions) -> Self { + match opts { + MeltOptions::Mpp { amount } => { + let cdk_amount: cdk::Amount = amount.into(); + cdk::nuts::MeltOptions::new_mpp(cdk_amount) + } + MeltOptions::Amountless { amount_msat } => { + let cdk_amount: cdk::Amount = amount_msat.into(); + cdk::nuts::MeltOptions::new_amountless(cdk_amount) + } + } + } +} + +impl From for MeltOptions { + fn from(opts: cdk::nuts::MeltOptions) -> Self { + match opts { + cdk::nuts::MeltOptions::Mpp { mpp } => MeltOptions::Mpp { + amount: mpp.amount.into(), + }, + cdk::nuts::MeltOptions::Amountless { amountless } => MeltOptions::Amountless { + amount_msat: amountless.amount_msat.into(), + }, + } + } +} + +/// FFI-compatible MintVersion +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct MintVersion { + /// Mint Software name + pub name: String, + /// Mint Version + pub version: String, +} + +impl From for MintVersion { + fn from(version: cdk::nuts::MintVersion) -> Self { + Self { + name: version.name, + version: version.version, + } + } +} + +impl From for cdk::nuts::MintVersion { + fn from(version: MintVersion) -> Self { + Self { + name: version.name, + version: version.version, + } + } +} + +impl MintVersion { + /// Convert MintVersion to JSON string + pub fn to_json(&self) -> Result { + Ok(serde_json::to_string(self)?) + } +} + +/// Decode MintVersion from JSON string +#[uniffi::export] +pub fn decode_mint_version(json: String) -> Result { + Ok(serde_json::from_str(&json)?) +} + +/// Encode MintVersion to JSON string +#[uniffi::export] +pub fn encode_mint_version(version: MintVersion) -> Result { + Ok(serde_json::to_string(&version)?) +} + +/// FFI-compatible ContactInfo +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct ContactInfo { + /// Contact Method i.e. nostr + pub method: String, + /// Contact info i.e. npub... + pub info: String, +} + +impl From for ContactInfo { + fn from(contact: cdk::nuts::ContactInfo) -> Self { + Self { + method: contact.method, + info: contact.info, + } + } +} + +impl From for cdk::nuts::ContactInfo { + fn from(contact: ContactInfo) -> Self { + Self { + method: contact.method, + info: contact.info, + } + } +} + +impl ContactInfo { + /// Convert ContactInfo to JSON string + pub fn to_json(&self) -> Result { + Ok(serde_json::to_string(self)?) + } +} + +/// Decode ContactInfo from JSON string +#[uniffi::export] +pub fn decode_contact_info(json: String) -> Result { + Ok(serde_json::from_str(&json)?) +} + +/// Encode ContactInfo to JSON string +#[uniffi::export] +pub fn encode_contact_info(info: ContactInfo) -> Result { + Ok(serde_json::to_string(&info)?) +} + +/// FFI-compatible SupportedSettings +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +#[serde(transparent)] +pub struct SupportedSettings { + /// Setting supported + pub supported: bool, +} + +impl From for SupportedSettings { + fn from(settings: cdk::nuts::nut06::SupportedSettings) -> Self { + Self { + supported: settings.supported, + } + } +} + +impl From for cdk::nuts::nut06::SupportedSettings { + fn from(settings: SupportedSettings) -> Self { + Self { + supported: settings.supported, + } + } +} + +/// FFI-compatible Nuts settings (simplified - only includes basic boolean flags) +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct Nuts { + /// NUT07 Settings - Token state check + pub nut07_supported: bool, + /// NUT08 Settings - Lightning fee return + pub nut08_supported: bool, + /// NUT09 Settings - Restore signature + pub nut09_supported: bool, + /// NUT10 Settings - Spending conditions + pub nut10_supported: bool, + /// NUT11 Settings - Pay to Public Key Hash + pub nut11_supported: bool, + /// NUT12 Settings - DLEQ proofs + pub nut12_supported: bool, + /// NUT14 Settings - Hashed Time Locked Contracts + pub nut14_supported: bool, + /// NUT20 Settings - Web sockets + pub nut20_supported: bool, + /// Supported currency units for minting + pub mint_units: Vec, + /// Supported currency units for melting + pub melt_units: Vec, +} + +impl From for Nuts { + fn from(nuts: cdk::nuts::Nuts) -> Self { + Self { + nut07_supported: nuts.nut07.supported, + nut08_supported: nuts.nut08.supported, + nut09_supported: nuts.nut09.supported, + nut10_supported: nuts.nut10.supported, + nut11_supported: nuts.nut11.supported, + nut12_supported: nuts.nut12.supported, + nut14_supported: nuts.nut14.supported, + nut20_supported: nuts.nut20.supported, + mint_units: nuts + .supported_mint_units() + .into_iter() + .map(|u| u.clone().into()) + .collect(), + melt_units: nuts + .supported_melt_units() + .into_iter() + .map(|u| u.clone().into()) + .collect(), + } + } +} + +impl Nuts { + /// Convert Nuts to JSON string + pub fn to_json(&self) -> Result { + Ok(serde_json::to_string(self)?) + } +} + +/// Decode Nuts from JSON string +#[uniffi::export] +pub fn decode_nuts(json: String) -> Result { + Ok(serde_json::from_str(&json)?) +} + +/// Encode Nuts to JSON string +#[uniffi::export] +pub fn encode_nuts(nuts: Nuts) -> Result { + Ok(serde_json::to_string(&nuts)?) +} + +/// FFI-compatible MintInfo +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct MintInfo { + /// name of the mint and should be recognizable + pub name: Option, + /// hex pubkey of the mint + pub pubkey: Option, + /// implementation name and the version running + pub version: Option, + /// short description of the mint + pub description: Option, + /// long description + pub description_long: Option, + /// Contact info + pub contact: Option>, + /// shows which NUTs the mint supports + pub nuts: Nuts, + /// Mint's icon URL + pub icon_url: Option, + /// Mint's endpoint URLs + pub urls: Option>, + /// message of the day that the wallet must display to the user + pub motd: Option, + /// server unix timestamp + pub time: Option, + /// terms of url service of the mint + pub tos_url: Option, +} + +impl From for MintInfo { + fn from(info: cdk::nuts::MintInfo) -> Self { + Self { + name: info.name, + pubkey: info.pubkey.map(|p| p.to_string()), + version: info.version.map(Into::into), + description: info.description, + description_long: info.description_long, + contact: info + .contact + .map(|contacts| contacts.into_iter().map(Into::into).collect()), + nuts: info.nuts.into(), + icon_url: info.icon_url, + urls: info.urls, + motd: info.motd, + time: info.time, + tos_url: info.tos_url, + } + } +} + +impl From for cdk_common::nuts::MintInfo { + fn from(info: MintInfo) -> Self { + Self { + name: info.name, + pubkey: info.pubkey.and_then(|p| p.parse().ok()), + version: info.version.map(Into::into), + description: info.description, + description_long: info.description_long, + contact: info + .contact + .map(|contacts| contacts.into_iter().map(Into::into).collect()), + nuts: cdk_common::nuts::Nuts::default(), // Simplified conversion + icon_url: info.icon_url, + urls: info.urls, + motd: info.motd, + time: info.time, + tos_url: info.tos_url, + } + } +} + +impl MintInfo { + /// Convert MintInfo to JSON string + pub fn to_json(&self) -> Result { + Ok(serde_json::to_string(self)?) + } +} + +/// Decode MintInfo from JSON string +#[uniffi::export] +pub fn decode_mint_info(json: String) -> Result { + Ok(serde_json::from_str(&json)?) +} + +/// Encode MintInfo to JSON string +#[uniffi::export] +pub fn encode_mint_info(info: MintInfo) -> Result { + Ok(serde_json::to_string(&info)?) +} + +/// FFI-compatible Conditions (for spending conditions) +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct Conditions { + /// Unix locktime after which refund keys can be used + pub locktime: Option, + /// Additional Public keys (as hex strings) + pub pubkeys: Vec, + /// Refund keys (as hex strings) + pub refund_keys: Vec, + /// Number of signatures required (default 1) + pub num_sigs: Option, + /// Signature flag (0 = SigInputs, 1 = SigAll) + pub sig_flag: u8, + /// Number of refund signatures required (default 1) + pub num_sigs_refund: Option, +} + +impl From for Conditions { + fn from(conditions: cdk::nuts::nut11::Conditions) -> Self { + Self { + locktime: conditions.locktime, + pubkeys: conditions + .pubkeys + .unwrap_or_default() + .into_iter() + .map(|p| p.to_string()) + .collect(), + refund_keys: conditions + .refund_keys + .unwrap_or_default() + .into_iter() + .map(|p| p.to_string()) + .collect(), + num_sigs: conditions.num_sigs, + sig_flag: match conditions.sig_flag { + cdk::nuts::nut11::SigFlag::SigInputs => 0, + cdk::nuts::nut11::SigFlag::SigAll => 1, + }, + num_sigs_refund: conditions.num_sigs_refund, + } + } +} + +impl TryFrom for cdk::nuts::nut11::Conditions { + type Error = FfiError; + + fn try_from(conditions: Conditions) -> Result { + let pubkeys = if conditions.pubkeys.is_empty() { + None + } else { + Some( + conditions + .pubkeys + .into_iter() + .map(|s| { + s.parse().map_err(|e| FfiError::InvalidCryptographicKey { + msg: format!("Invalid pubkey: {}", e), + }) + }) + .collect::, _>>()?, + ) + }; + + let refund_keys = if conditions.refund_keys.is_empty() { + None + } else { + Some( + conditions + .refund_keys + .into_iter() + .map(|s| { + s.parse().map_err(|e| FfiError::InvalidCryptographicKey { + msg: format!("Invalid refund key: {}", e), + }) + }) + .collect::, _>>()?, + ) + }; + + let sig_flag = match conditions.sig_flag { + 0 => cdk::nuts::nut11::SigFlag::SigInputs, + 1 => cdk::nuts::nut11::SigFlag::SigAll, + _ => { + return Err(FfiError::Generic { + msg: "Invalid sig_flag value".to_string(), + }) + } + }; + + Ok(Self { + locktime: conditions.locktime, + pubkeys, + refund_keys, + num_sigs: conditions.num_sigs, + sig_flag, + num_sigs_refund: conditions.num_sigs_refund, + }) + } +} + +impl Conditions { + /// Convert Conditions to JSON string + pub fn to_json(&self) -> Result { + Ok(serde_json::to_string(self)?) + } +} + +/// Decode Conditions from JSON string +#[uniffi::export] +pub fn decode_conditions(json: String) -> Result { + Ok(serde_json::from_str(&json)?) +} + +/// Encode Conditions to JSON string +#[uniffi::export] +pub fn encode_conditions(conditions: Conditions) -> Result { + Ok(serde_json::to_string(&conditions)?) +} + +/// FFI-compatible Witness +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Enum)] +pub enum Witness { + /// P2PK Witness + P2PK { + /// Signatures + signatures: Vec, + }, + /// HTLC Witness + HTLC { + /// Preimage + preimage: String, + /// Optional signatures + signatures: Option>, + }, +} + +impl From for Witness { + fn from(witness: cdk::nuts::Witness) -> Self { + match witness { + cdk::nuts::Witness::P2PKWitness(p2pk) => Self::P2PK { + signatures: p2pk.signatures, + }, + cdk::nuts::Witness::HTLCWitness(htlc) => Self::HTLC { + preimage: htlc.preimage, + signatures: htlc.signatures, + }, + } + } +} + +impl From for cdk::nuts::Witness { + fn from(witness: Witness) -> Self { + match witness { + Witness::P2PK { signatures } => { + Self::P2PKWitness(cdk::nuts::nut11::P2PKWitness { signatures }) + } + Witness::HTLC { + preimage, + signatures, + } => Self::HTLCWitness(cdk::nuts::nut14::HTLCWitness { + preimage, + signatures, + }), + } + } +} + +/// FFI-compatible SpendingConditions +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Enum)] +pub enum SpendingConditions { + /// P2PK (Pay to Public Key) conditions + P2PK { + /// The public key (as hex string) + pubkey: String, + /// Additional conditions + conditions: Option, + }, + /// HTLC (Hash Time Locked Contract) conditions + HTLC { + /// Hash of the preimage (as hex string) + hash: String, + /// Additional conditions + conditions: Option, + }, +} + +impl From for SpendingConditions { + fn from(spending_conditions: cdk::nuts::SpendingConditions) -> Self { + match spending_conditions { + cdk::nuts::SpendingConditions::P2PKConditions { data, conditions } => Self::P2PK { + pubkey: data.to_string(), + conditions: conditions.map(Into::into), + }, + cdk::nuts::SpendingConditions::HTLCConditions { data, conditions } => Self::HTLC { + hash: data.to_string(), + conditions: conditions.map(Into::into), + }, + } + } +} + +/// FFI-compatible Transaction +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct Transaction { + /// Transaction ID + pub id: TransactionId, + /// Mint URL + pub mint_url: MintUrl, + /// Transaction direction + pub direction: TransactionDirection, + /// Amount + pub amount: Amount, + /// Fee + pub fee: Amount, + /// Currency Unit + pub unit: CurrencyUnit, + /// Proof Ys (Y values from proofs) + pub ys: Vec, + /// Unix timestamp + pub timestamp: u64, + /// Memo + pub memo: Option, + /// User-defined metadata + pub metadata: HashMap, + /// Quote ID if this is a mint or melt transaction + pub quote_id: Option, +} + +impl From for Transaction { + fn from(tx: cdk_common::wallet::Transaction) -> Self { + Self { + id: tx.id().into(), + mint_url: tx.mint_url.into(), + direction: tx.direction.into(), + amount: tx.amount.into(), + fee: tx.fee.into(), + unit: tx.unit.into(), + ys: tx.ys.into_iter().map(Into::into).collect(), + timestamp: tx.timestamp, + memo: tx.memo, + metadata: tx.metadata, + quote_id: tx.quote_id, + } + } +} + +/// Convert FFI Transaction to CDK Transaction +impl TryFrom for cdk_common::wallet::Transaction { + type Error = FfiError; + + fn try_from(tx: Transaction) -> Result { + let cdk_ys: Result, _> = + tx.ys.into_iter().map(|pk| pk.try_into()).collect(); + let cdk_ys = cdk_ys?; + + Ok(Self { + mint_url: tx.mint_url.try_into()?, + direction: tx.direction.into(), + amount: tx.amount.into(), + fee: tx.fee.into(), + unit: tx.unit.into(), + ys: cdk_ys, + timestamp: tx.timestamp, + memo: tx.memo, + metadata: tx.metadata, + quote_id: tx.quote_id, + }) + } +} + +impl Transaction { + /// Convert Transaction to JSON string + pub fn to_json(&self) -> Result { + Ok(serde_json::to_string(self)?) + } +} + +/// Decode Transaction from JSON string +#[uniffi::export] +pub fn decode_transaction(json: String) -> Result { + Ok(serde_json::from_str(&json)?) +} + +/// Encode Transaction to JSON string +#[uniffi::export] +pub fn encode_transaction(transaction: Transaction) -> Result { + Ok(serde_json::to_string(&transaction)?) +} + +/// FFI-compatible TransactionDirection +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, uniffi::Enum)] +pub enum TransactionDirection { + /// Incoming transaction (i.e., receive or mint) + Incoming, + /// Outgoing transaction (i.e., send or melt) + Outgoing, +} + +impl From for TransactionDirection { + fn from(direction: cdk_common::wallet::TransactionDirection) -> Self { + match direction { + cdk_common::wallet::TransactionDirection::Incoming => TransactionDirection::Incoming, + cdk_common::wallet::TransactionDirection::Outgoing => TransactionDirection::Outgoing, + } + } +} + +impl From for cdk_common::wallet::TransactionDirection { + fn from(direction: TransactionDirection) -> Self { + match direction { + TransactionDirection::Incoming => cdk_common::wallet::TransactionDirection::Incoming, + TransactionDirection::Outgoing => cdk_common::wallet::TransactionDirection::Outgoing, + } + } +} + +/// FFI-compatible TransactionId +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +#[serde(transparent)] +pub struct TransactionId { + /// Hex-encoded transaction ID (64 characters) + pub hex: String, +} + +impl TransactionId { + /// Create a new TransactionId from hex string + pub fn from_hex(hex: String) -> Result { + // Validate hex string length (should be 64 characters for 32 bytes) + if hex.len() != 64 { + return Err(FfiError::InvalidHex { + msg: "Transaction ID hex must be exactly 64 characters (32 bytes)".to_string(), + }); + } + + // Validate hex format + if !hex.chars().all(|c| c.is_ascii_hexdigit()) { + return Err(FfiError::InvalidHex { + msg: "Transaction ID hex contains invalid characters".to_string(), + }); + } + + Ok(Self { hex }) + } + + /// Create from proofs + pub fn from_proofs(proofs: &Proofs) -> Result { + let cdk_proofs: Vec = proofs.iter().map(|p| p.inner.clone()).collect(); + let id = cdk_common::wallet::TransactionId::from_proofs(cdk_proofs)?; + Ok(Self { + hex: id.to_string(), + }) + } +} + +impl From for TransactionId { + fn from(id: cdk_common::wallet::TransactionId) -> Self { + Self { + hex: id.to_string(), + } + } +} + +impl TryFrom for cdk_common::wallet::TransactionId { + type Error = FfiError; + + fn try_from(id: TransactionId) -> Result { + cdk_common::wallet::TransactionId::from_hex(&id.hex) + .map_err(|e| FfiError::InvalidHex { msg: e.to_string() }) + } +} + +/// FFI-compatible AuthProof +#[cfg(feature = "auth")] +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct AuthProof { + /// Keyset ID + pub keyset_id: String, + /// Secret message + pub secret: String, + /// Unblinded signature (C) + pub c: String, + /// Y value (hash_to_curve of secret) + pub y: String, +} + +#[cfg(feature = "auth")] +impl From for AuthProof { + fn from(auth_proof: cdk_common::AuthProof) -> Self { + Self { + keyset_id: auth_proof.keyset_id.to_string(), + secret: auth_proof.secret.to_string(), + c: auth_proof.c.to_string(), + y: auth_proof + .y() + .map(|y| y.to_string()) + .unwrap_or_else(|_| "".to_string()), + } + } +} + +#[cfg(feature = "auth")] +impl TryFrom for cdk_common::AuthProof { + type Error = FfiError; + + fn try_from(auth_proof: AuthProof) -> Result { + use std::str::FromStr; + Ok(Self { + keyset_id: cdk_common::Id::from_str(&auth_proof.keyset_id) + .map_err(|e| FfiError::Serialization { msg: e.to_string() })?, + secret: { + use std::str::FromStr; + cdk_common::secret::Secret::from_str(&auth_proof.secret) + .map_err(|e| FfiError::Serialization { msg: e.to_string() })? + }, + c: cdk_common::PublicKey::from_str(&auth_proof.c) + .map_err(|e| FfiError::InvalidCryptographicKey { msg: e.to_string() })?, + dleq: None, // FFI doesn't expose DLEQ proofs for simplicity + }) + } +} + +#[cfg(feature = "auth")] +impl AuthProof { + /// Convert AuthProof to JSON string + pub fn to_json(&self) -> Result { + Ok(serde_json::to_string(self)?) + } +} + +/// Decode AuthProof from JSON string +#[cfg(feature = "auth")] +#[uniffi::export] +pub fn decode_auth_proof(json: String) -> Result { + Ok(serde_json::from_str(&json)?) +} + +/// Encode AuthProof to JSON string +#[cfg(feature = "auth")] +#[uniffi::export] +pub fn encode_auth_proof(proof: AuthProof) -> Result { + Ok(serde_json::to_string(&proof)?) +} + +impl TryFrom for cdk::nuts::SpendingConditions { + type Error = FfiError; + + fn try_from(spending_conditions: SpendingConditions) -> Result { + match spending_conditions { + SpendingConditions::P2PK { pubkey, conditions } => { + let pubkey = pubkey + .parse() + .map_err(|e| FfiError::InvalidCryptographicKey { + msg: format!("Invalid pubkey: {}", e), + })?; + let conditions = conditions.map(|c| c.try_into()).transpose()?; + Ok(Self::P2PKConditions { + data: pubkey, + conditions, + }) + } + SpendingConditions::HTLC { hash, conditions } => { + let hash = hash + .parse() + .map_err(|e| FfiError::InvalidCryptographicKey { + msg: format!("Invalid hash: {}", e), + })?; + let conditions = conditions.map(|c| c.try_into()).transpose()?; + Ok(Self::HTLCConditions { + data: hash, + conditions, + }) + } + } + } +} + +/// FFI-compatible SubscriptionKind +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, uniffi::Enum)] +pub enum SubscriptionKind { + /// Bolt 11 Melt Quote + Bolt11MeltQuote, + /// Bolt 11 Mint Quote + Bolt11MintQuote, + /// Bolt 12 Mint Quote + Bolt12MintQuote, + /// Proof State + ProofState, +} + +impl From for cdk::nuts::nut17::Kind { + fn from(kind: SubscriptionKind) -> Self { + match kind { + SubscriptionKind::Bolt11MeltQuote => cdk::nuts::nut17::Kind::Bolt11MeltQuote, + SubscriptionKind::Bolt11MintQuote => cdk::nuts::nut17::Kind::Bolt11MintQuote, + SubscriptionKind::Bolt12MintQuote => cdk::nuts::nut17::Kind::Bolt12MintQuote, + SubscriptionKind::ProofState => cdk::nuts::nut17::Kind::ProofState, + } + } +} + +impl From for SubscriptionKind { + fn from(kind: cdk::nuts::nut17::Kind) -> Self { + match kind { + cdk::nuts::nut17::Kind::Bolt11MeltQuote => SubscriptionKind::Bolt11MeltQuote, + cdk::nuts::nut17::Kind::Bolt11MintQuote => SubscriptionKind::Bolt11MintQuote, + cdk::nuts::nut17::Kind::Bolt12MintQuote => SubscriptionKind::Bolt12MintQuote, + cdk::nuts::nut17::Kind::ProofState => SubscriptionKind::ProofState, + } + } +} + +/// FFI-compatible SubscribeParams +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct SubscribeParams { + /// Subscription kind + pub kind: SubscriptionKind, + /// Filters + pub filters: Vec, + /// Subscription ID (optional, will be generated if not provided) + pub id: Option, +} + +impl From for cdk_common::subscription::Params { + fn from(params: SubscribeParams) -> Self { + let sub_id = params + .id + .map(|id| SubId::from(id.as_str())) + .unwrap_or_else(|| { + // Generate a random ID + let uuid = uuid::Uuid::new_v4(); + SubId::from(uuid.to_string().as_str()) + }); + + cdk::nuts::nut17::Params { + kind: params.kind.into(), + filters: params.filters, + id: sub_id, + } + } +} + +impl SubscribeParams { + /// Convert SubscribeParams to JSON string + pub fn to_json(&self) -> Result { + Ok(serde_json::to_string(self)?) + } +} + +/// Decode SubscribeParams from JSON string +#[uniffi::export] +pub fn decode_subscribe_params(json: String) -> Result { + Ok(serde_json::from_str(&json)?) +} + +/// Encode SubscribeParams to JSON string +#[uniffi::export] +pub fn encode_subscribe_params(params: SubscribeParams) -> Result { + Ok(serde_json::to_string(¶ms)?) +} + +/// FFI-compatible ActiveSubscription +#[derive(uniffi::Object)] +pub struct ActiveSubscription { + inner: std::sync::Arc>, + pub sub_id: String, +} + +impl ActiveSubscription { + pub(crate) fn new( + inner: cdk::wallet::subscription::ActiveSubscription, + sub_id: String, + ) -> Self { + Self { + inner: std::sync::Arc::new(tokio::sync::Mutex::new(inner)), + sub_id, + } + } +} + +#[uniffi::export(async_runtime = "tokio")] +impl ActiveSubscription { + /// Get the subscription ID + pub fn id(&self) -> String { + self.sub_id.clone() + } + + /// Receive the next notification + pub async fn recv(&self) -> Result { + let mut guard = self.inner.lock().await; + guard + .recv() + .await + .ok_or(FfiError::Generic { + msg: "Subscription closed".to_string(), + }) + .map(Into::into) + } + + /// Try to receive a notification without blocking + pub async fn try_recv(&self) -> Result, FfiError> { + let mut guard = self.inner.lock().await; + guard + .try_recv() + .map(|opt| opt.map(Into::into)) + .map_err(|e| FfiError::Generic { + msg: format!("Failed to receive notification: {}", e), + }) + } +} + +/// FFI-compatible NotificationPayload +#[derive(Debug, Clone, uniffi::Enum)] +pub enum NotificationPayload { + /// Proof state update + ProofState { proof_states: Vec }, + /// Mint quote update + MintQuoteUpdate { + quote: std::sync::Arc, + }, + /// Melt quote update + MeltQuoteUpdate { + quote: std::sync::Arc, + }, +} + +impl From> for NotificationPayload { + fn from(payload: cdk::nuts::NotificationPayload) -> Self { + match payload { + cdk::nuts::NotificationPayload::ProofState(states) => NotificationPayload::ProofState { + proof_states: vec![states.into()], + }, + cdk::nuts::NotificationPayload::MintQuoteBolt11Response(quote_resp) => { + NotificationPayload::MintQuoteUpdate { + quote: std::sync::Arc::new(quote_resp.into()), + } + } + cdk::nuts::NotificationPayload::MeltQuoteBolt11Response(quote_resp) => { + NotificationPayload::MeltQuoteUpdate { + quote: std::sync::Arc::new(quote_resp.into()), + } + } + _ => { + // For now, handle other notification types as empty ProofState + NotificationPayload::ProofState { + proof_states: vec![], + } + } + } + } +} + +/// FFI-compatible ProofStateUpdate +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct ProofStateUpdate { + /// Y value (hash_to_curve of secret) + pub y: String, + /// Current state + pub state: ProofState, + /// Optional witness data + pub witness: Option, +} + +impl From for ProofStateUpdate { + fn from(proof_state: cdk::nuts::nut07::ProofState) -> Self { + Self { + y: proof_state.y.to_string(), + state: proof_state.state.into(), + witness: proof_state.witness.map(|w| format!("{:?}", w)), + } + } +} + +impl ProofStateUpdate { + /// Convert ProofStateUpdate to JSON string + pub fn to_json(&self) -> Result { + Ok(serde_json::to_string(self)?) + } +} + +/// Decode ProofStateUpdate from JSON string +#[uniffi::export] +pub fn decode_proof_state_update(json: String) -> Result { + Ok(serde_json::from_str(&json)?) +} + +/// Encode ProofStateUpdate to JSON string +#[uniffi::export] +pub fn encode_proof_state_update(update: ProofStateUpdate) -> Result { + Ok(serde_json::to_string(&update)?) +} + +/// FFI-compatible KeySetInfo +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct KeySetInfo { + pub id: String, + pub unit: CurrencyUnit, + pub active: bool, + /// Input fee per thousand (ppk) + pub input_fee_ppk: u64, +} + +impl From for KeySetInfo { + fn from(keyset: cdk_common::nuts::KeySetInfo) -> Self { + Self { + id: keyset.id.to_string(), + unit: keyset.unit.into(), + active: keyset.active, + input_fee_ppk: keyset.input_fee_ppk, + } + } +} + +impl From for cdk_common::nuts::KeySetInfo { + fn from(keyset: KeySetInfo) -> Self { + use std::str::FromStr; + Self { + id: cdk_common::nuts::Id::from_str(&keyset.id).unwrap_or_else(|_| { + // Create a dummy keyset for empty mint keys + use std::collections::BTreeMap; + let empty_map = BTreeMap::new(); + let empty_keys = cdk_common::nut01::MintKeys::new(empty_map); + cdk_common::nuts::Id::from(&empty_keys) + }), + unit: keyset.unit.into(), + active: keyset.active, + final_expiry: None, + input_fee_ppk: keyset.input_fee_ppk, + } + } +} + +impl KeySetInfo { + /// Convert KeySetInfo to JSON string + pub fn to_json(&self) -> Result { + Ok(serde_json::to_string(self)?) + } +} + +/// Decode KeySetInfo from JSON string +#[uniffi::export] +pub fn decode_key_set_info(json: String) -> Result { + Ok(serde_json::from_str(&json)?) +} + +/// Encode KeySetInfo to JSON string +#[uniffi::export] +pub fn encode_key_set_info(info: KeySetInfo) -> Result { + Ok(serde_json::to_string(&info)?) +} + +/// FFI-compatible PublicKey +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +#[serde(transparent)] +pub struct PublicKey { + /// Hex-encoded public key + pub hex: String, +} + +impl From for PublicKey { + fn from(key: cdk_common::nuts::PublicKey) -> Self { + Self { + hex: key.to_string(), + } + } +} + +impl TryFrom for cdk_common::nuts::PublicKey { + type Error = FfiError; + + fn try_from(key: PublicKey) -> Result { + key.hex + .parse() + .map_err(|e| FfiError::InvalidCryptographicKey { + msg: format!("Invalid public key: {}", e), + }) + } +} + +/// FFI-compatible Keys (simplified - contains only essential info) +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct Keys { + /// Keyset ID + pub id: String, + /// Currency unit + pub unit: CurrencyUnit, + /// Map of amount to public key hex (simplified from BTreeMap) + pub keys: HashMap, +} + +impl From for Keys { + fn from(keys: cdk_common::nuts::Keys) -> Self { + // Keys doesn't have id and unit - we'll need to get these from context + // For now, use placeholder values + Self { + id: "unknown".to_string(), // This should come from KeySet + unit: CurrencyUnit::Sat, // This should come from KeySet + keys: keys + .keys() + .iter() + .map(|(amount, pubkey)| (u64::from(*amount), pubkey.to_string())) + .collect(), + } + } +} + +impl TryFrom for cdk_common::nuts::Keys { + type Error = FfiError; + + fn try_from(keys: Keys) -> Result { + use std::collections::BTreeMap; + use std::str::FromStr; + + // Convert the HashMap to BTreeMap with proper types + let mut keys_map = BTreeMap::new(); + for (amount_u64, pubkey_hex) in keys.keys { + let amount = cashu::Amount::from(amount_u64); + let pubkey = cashu::PublicKey::from_str(&pubkey_hex) + .map_err(|e| FfiError::InvalidCryptographicKey { msg: e.to_string() })?; + keys_map.insert(amount, pubkey); + } + + Ok(cdk_common::nuts::Keys::new(keys_map)) + } +} + +impl Keys { + /// Convert Keys to JSON string + pub fn to_json(&self) -> Result { + Ok(serde_json::to_string(self)?) + } +} + +/// Decode Keys from JSON string +#[uniffi::export] +pub fn decode_keys(json: String) -> Result { + Ok(serde_json::from_str(&json)?) +} + +/// Encode Keys to JSON string +#[uniffi::export] +pub fn encode_keys(keys: Keys) -> Result { + Ok(serde_json::to_string(&keys)?) +} + +/// FFI-compatible KeySet +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct KeySet { + /// Keyset ID + pub id: String, + /// Currency unit + pub unit: CurrencyUnit, + /// The keys (map of amount to public key hex) + pub keys: HashMap, + /// Optional expiry timestamp + pub final_expiry: Option, +} + +impl From for KeySet { + fn from(keyset: cashu::KeySet) -> Self { + Self { + id: keyset.id.to_string(), + unit: keyset.unit.into(), + keys: keyset + .keys + .keys() + .iter() + .map(|(amount, pubkey)| (u64::from(*amount), pubkey.to_string())) + .collect(), + final_expiry: keyset.final_expiry, + } + } +} + +impl TryFrom for cashu::KeySet { + type Error = FfiError; + + fn try_from(keyset: KeySet) -> Result { + use std::collections::BTreeMap; + use std::str::FromStr; + + // Convert id + let id = cashu::Id::from_str(&keyset.id) + .map_err(|e| FfiError::Serialization { msg: e.to_string() })?; + + // Convert unit + let unit: cashu::CurrencyUnit = keyset.unit.into(); + + // Convert keys + let mut keys_map = BTreeMap::new(); + for (amount_u64, pubkey_hex) in keyset.keys { + let amount = cashu::Amount::from(amount_u64); + let pubkey = cashu::PublicKey::from_str(&pubkey_hex) + .map_err(|e| FfiError::InvalidCryptographicKey { msg: e.to_string() })?; + keys_map.insert(amount, pubkey); + } + let keys = cashu::Keys::new(keys_map); + + Ok(cashu::KeySet { + id, + unit, + keys, + final_expiry: keyset.final_expiry, + }) + } +} + +impl KeySet { + /// Convert KeySet to JSON string + pub fn to_json(&self) -> Result { + Ok(serde_json::to_string(self)?) + } +} + +/// Decode KeySet from JSON string +#[uniffi::export] +pub fn decode_key_set(json: String) -> Result { + Ok(serde_json::from_str(&json)?) +} + +/// Encode KeySet to JSON string +#[uniffi::export] +pub fn encode_key_set(keyset: KeySet) -> Result { + Ok(serde_json::to_string(&keyset)?) +} + +/// FFI-compatible ProofInfo +#[derive(Debug, Clone, uniffi::Record)] +pub struct ProofInfo { + /// Proof + pub proof: std::sync::Arc, + /// Y value (hash_to_curve of secret) + pub y: PublicKey, + /// Mint URL + pub mint_url: MintUrl, + /// Proof state + pub state: ProofState, + /// Proof Spending Conditions + pub spending_condition: Option, + /// Currency unit + pub unit: CurrencyUnit, +} + +impl From for ProofInfo { + fn from(info: cdk_common::common::ProofInfo) -> Self { + Self { + proof: std::sync::Arc::new(info.proof.into()), + y: info.y.into(), + mint_url: info.mint_url.into(), + state: info.state.into(), + spending_condition: info.spending_condition.map(Into::into), + unit: info.unit.into(), + } + } +} + +/// Decode ProofInfo from JSON string +#[uniffi::export] +pub fn decode_proof_info(json: String) -> Result { + let info: cdk_common::common::ProofInfo = serde_json::from_str(&json)?; + Ok(info.into()) +} + +/// Encode ProofInfo to JSON string +#[uniffi::export] +pub fn encode_proof_info(info: ProofInfo) -> Result { + // Convert to cdk_common::common::ProofInfo for serialization + let cdk_info = cdk_common::common::ProofInfo { + proof: info.proof.inner.clone(), + y: info.y.try_into()?, + mint_url: info.mint_url.try_into()?, + state: info.state.into(), + spending_condition: info.spending_condition.and_then(|c| c.try_into().ok()), + unit: info.unit.into(), + }; + Ok(serde_json::to_string(&cdk_info)?) +} + +// State enum removed - using ProofState instead + +/// FFI-compatible Id (for keyset IDs) +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +#[serde(transparent)] +pub struct Id { + pub hex: String, +} + +impl From for Id { + fn from(id: cdk_common::nuts::Id) -> Self { + Self { + hex: id.to_string(), + } + } +} + +impl From for cdk_common::nuts::Id { + fn from(id: Id) -> Self { + use std::str::FromStr; + Self::from_str(&id.hex).unwrap_or_else(|_| { + // Create a dummy keyset for empty mint keys + use std::collections::BTreeMap; + let empty_map = BTreeMap::new(); + let empty_keys = cdk_common::nut01::MintKeys::new(empty_map); + cdk_common::nuts::Id::from(&empty_keys) + }) + } +} diff --git a/crates/cdk-ffi/src/wallet.rs b/crates/cdk-ffi/src/wallet.rs new file mode 100644 index 000000000..73fe76ece --- /dev/null +++ b/crates/cdk-ffi/src/wallet.rs @@ -0,0 +1,486 @@ +//! FFI Wallet bindings + +use std::str::FromStr; +use std::sync::Arc; + +use bip39::Mnemonic; +use cdk::wallet::{Wallet as CdkWallet, WalletBuilder as CdkWalletBuilder}; + +use crate::error::FfiError; +use crate::types::*; + +/// FFI-compatible Wallet +#[derive(uniffi::Object)] +pub struct Wallet { + inner: Arc, +} + +#[uniffi::export(async_runtime = "tokio")] +impl Wallet { + /// Create a new Wallet from mnemonic using WalletDatabase trait + #[uniffi::constructor] + pub async fn new( + mint_url: String, + unit: CurrencyUnit, + mnemonic: String, + db: Arc, + config: WalletConfig, + ) -> Result { + // Parse mnemonic and generate seed without passphrase + let m = Mnemonic::parse(&mnemonic) + .map_err(|e| FfiError::InvalidMnemonic { msg: e.to_string() })?; + let seed = m.to_seed_normalized(""); + + // Convert the FFI database trait to a CDK database implementation + let localstore = crate::database::create_cdk_database_from_ffi(db); + + let wallet = + CdkWalletBuilder::new() + .mint_url(mint_url.parse().map_err(|e: cdk::mint_url::Error| { + FfiError::InvalidUrl { msg: e.to_string() } + })?) + .unit(unit.into()) + .localstore(localstore) + .seed(seed) + .target_proof_count(config.target_proof_count.unwrap_or(3) as usize) + .build() + .map_err(FfiError::from)?; + + Ok(Self { + inner: Arc::new(wallet), + }) + } + + /// Get the mint URL + pub fn mint_url(&self) -> MintUrl { + self.inner.mint_url.clone().into() + } + + /// Get the currency unit + pub fn unit(&self) -> CurrencyUnit { + self.inner.unit.clone().into() + } + + /// Get total balance + pub async fn total_balance(&self) -> Result { + let balance = self.inner.total_balance().await?; + Ok(balance.into()) + } + + /// Get total pending balance + pub async fn total_pending_balance(&self) -> Result { + let balance = self.inner.total_pending_balance().await?; + Ok(balance.into()) + } + + /// Get total reserved balance + pub async fn total_reserved_balance(&self) -> Result { + let balance = self.inner.total_reserved_balance().await?; + Ok(balance.into()) + } + + /// Get mint info + pub async fn get_mint_info(&self) -> Result, FfiError> { + let info = self.inner.fetch_mint_info().await?; + Ok(info.map(Into::into)) + } + + /// Receive tokens + pub async fn receive( + &self, + token: std::sync::Arc, + options: ReceiveOptions, + ) -> Result { + let amount = self + .inner + .receive(&token.to_string(), options.into()) + .await?; + Ok(amount.into()) + } + + /// Restore wallet from seed + pub async fn restore(&self) -> Result { + let amount = self.inner.restore().await?; + Ok(amount.into()) + } + + /// Verify token DLEQ proofs + pub async fn verify_token_dleq(&self, token: std::sync::Arc) -> Result<(), FfiError> { + let cdk_token = token.inner.clone(); + self.inner.verify_token_dleq(&cdk_token).await?; + Ok(()) + } + + /// Receive proofs directly + pub async fn receive_proofs( + &self, + proofs: Proofs, + options: ReceiveOptions, + memo: Option, + ) -> Result { + let cdk_proofs: Vec = + proofs.into_iter().map(|p| p.inner.clone()).collect(); + + let amount = self + .inner + .receive_proofs(cdk_proofs, options.into(), memo) + .await?; + Ok(amount.into()) + } + + /// Prepare a send operation + pub async fn prepare_send( + &self, + amount: Amount, + options: SendOptions, + ) -> Result, FfiError> { + let prepared = self + .inner + .prepare_send(amount.into(), options.into()) + .await?; + Ok(std::sync::Arc::new(prepared.into())) + } + + /// Get a mint quote + pub async fn mint_quote( + &self, + amount: Amount, + description: Option, + ) -> Result { + let quote = self.inner.mint_quote(amount.into(), description).await?; + Ok(quote.into()) + } + + /// Mint tokens + pub async fn mint( + &self, + quote_id: String, + amount_split_target: SplitTarget, + spending_conditions: Option, + ) -> Result { + // Convert spending conditions if provided + let conditions = spending_conditions.map(|sc| sc.try_into()).transpose()?; + + let proofs = self + .inner + .mint("e_id, amount_split_target.into(), conditions) + .await?; + Ok(proofs + .into_iter() + .map(|p| std::sync::Arc::new(p.into())) + .collect()) + } + + /// Get a melt quote + pub async fn melt_quote( + &self, + request: String, + options: Option, + ) -> Result { + let cdk_options = options.map(Into::into); + let quote = self.inner.melt_quote(request, cdk_options).await?; + Ok(quote.into()) + } + + /// Melt tokens + pub async fn melt(&self, quote_id: String) -> Result { + let melted = self.inner.melt("e_id).await?; + Ok(melted.into()) + } + + /// Get a quote for a bolt12 mint + pub async fn mint_bolt12_quote( + &self, + amount: Option, + description: Option, + ) -> Result { + let quote = self + .inner + .mint_bolt12_quote(amount.map(Into::into), description) + .await?; + Ok(quote.into()) + } + + /// Mint tokens using bolt12 + pub async fn mint_bolt12( + &self, + quote_id: String, + amount: Option, + amount_split_target: SplitTarget, + spending_conditions: Option, + ) -> Result { + let conditions = spending_conditions.map(|sc| sc.try_into()).transpose()?; + + let proofs = self + .inner + .mint_bolt12( + "e_id, + amount.map(Into::into), + amount_split_target.into(), + conditions, + ) + .await?; + + Ok(proofs + .into_iter() + .map(|p| std::sync::Arc::new(p.into())) + .collect()) + } + + /// Get a quote for a bolt12 melt + pub async fn melt_bolt12_quote( + &self, + request: String, + options: Option, + ) -> Result { + let cdk_options = options.map(Into::into); + let quote = self.inner.melt_bolt12_quote(request, cdk_options).await?; + Ok(quote.into()) + } + + /// Swap proofs + pub async fn swap( + &self, + amount: Option, + amount_split_target: SplitTarget, + input_proofs: Proofs, + spending_conditions: Option, + include_fees: bool, + ) -> Result, FfiError> { + let cdk_proofs: Vec = + input_proofs.into_iter().map(|p| p.inner.clone()).collect(); + + // Convert spending conditions if provided + let conditions = spending_conditions.map(|sc| sc.try_into()).transpose()?; + + let result = self + .inner + .swap( + amount.map(Into::into), + amount_split_target.into(), + cdk_proofs, + conditions, + include_fees, + ) + .await?; + + Ok(result.map(|proofs| { + proofs + .into_iter() + .map(|p| std::sync::Arc::new(p.into())) + .collect() + })) + } + + /// Get proofs by states + pub async fn get_proofs_by_states(&self, states: Vec) -> Result { + let mut all_proofs = Vec::new(); + + for state in states { + let proofs = match state { + ProofState::Unspent => self.inner.get_unspent_proofs().await?, + ProofState::Pending => self.inner.get_pending_proofs().await?, + ProofState::Reserved => self.inner.get_reserved_proofs().await?, + ProofState::PendingSpent => self.inner.get_pending_spent_proofs().await?, + ProofState::Spent => { + // CDK doesn't have a method to get spent proofs directly + // They are removed from the database when spent + continue; + } + }; + + for proof in proofs { + all_proofs.push(std::sync::Arc::new(proof.into())); + } + } + + Ok(all_proofs) + } + + /// Check if proofs are spent + pub async fn check_proofs_spent(&self, proofs: Proofs) -> Result, FfiError> { + let cdk_proofs: Vec = + proofs.into_iter().map(|p| p.inner.clone()).collect(); + + let proof_states = self.inner.check_proofs_spent(cdk_proofs).await?; + // Convert ProofState to bool (spent = true, unspent = false) + let spent_bools = proof_states + .into_iter() + .map(|proof_state| { + matches!( + proof_state.state, + cdk::nuts::State::Spent | cdk::nuts::State::PendingSpent + ) + }) + .collect(); + Ok(spent_bools) + } + + /// List transactions + pub async fn list_transactions( + &self, + direction: Option, + ) -> Result, FfiError> { + let cdk_direction = direction.map(Into::into); + let transactions = self.inner.list_transactions(cdk_direction).await?; + Ok(transactions.into_iter().map(Into::into).collect()) + } + + /// Get transaction by ID + pub async fn get_transaction( + &self, + id: TransactionId, + ) -> Result, FfiError> { + let cdk_id = id.try_into()?; + let transaction = self.inner.get_transaction(cdk_id).await?; + Ok(transaction.map(Into::into)) + } + + /// Revert a transaction + pub async fn revert_transaction(&self, id: TransactionId) -> Result<(), FfiError> { + let cdk_id = id.try_into()?; + self.inner.revert_transaction(cdk_id).await?; + Ok(()) + } + + /// Subscribe to wallet events + pub async fn subscribe( + &self, + params: SubscribeParams, + ) -> Result, FfiError> { + let cdk_params: cdk_common::subscription::Params = params.clone().into(); + let sub_id = cdk_params.id.to_string(); + let active_sub = self.inner.subscribe(cdk_params).await; + Ok(std::sync::Arc::new(ActiveSubscription::new( + active_sub, sub_id, + ))) + } + + /// Refresh keysets from the mint + pub async fn refresh_keysets(&self) -> Result, FfiError> { + let keysets = self.inner.refresh_keysets().await?; + Ok(keysets.into_iter().map(Into::into).collect()) + } + + /// Get the active keyset for the wallet's unit + pub async fn get_active_keyset(&self) -> Result { + let keyset = self.inner.get_active_keyset().await?; + Ok(keyset.into()) + } + + /// Get fees for a specific keyset ID + pub async fn get_keyset_fees_by_id(&self, keyset_id: String) -> Result { + let id = cdk::nuts::Id::from_str(&keyset_id) + .map_err(|e| FfiError::Generic { msg: e.to_string() })?; + let fees = self.inner.get_keyset_fees_by_id(id).await?; + Ok(fees) + } + + /// Reclaim unspent proofs (mark them as unspent in the database) + pub async fn reclaim_unspent(&self, proofs: Proofs) -> Result<(), FfiError> { + let cdk_proofs: Vec = proofs.iter().map(|p| p.inner.clone()).collect(); + self.inner.reclaim_unspent(cdk_proofs).await?; + Ok(()) + } + + /// Check all pending proofs and return the total amount reclaimed + pub async fn check_all_pending_proofs(&self) -> Result { + let amount = self.inner.check_all_pending_proofs().await?; + Ok(amount.into()) + } + + /// Calculate fee for a given number of proofs with the specified keyset + pub async fn calculate_fee( + &self, + proof_count: u32, + keyset_id: String, + ) -> Result { + let id = cdk::nuts::Id::from_str(&keyset_id) + .map_err(|e| FfiError::Generic { msg: e.to_string() })?; + let fee_ppk = self.inner.get_keyset_fees_by_id(id).await?; + let total_fee = (proof_count as u64 * fee_ppk) / 1000; // fee is per thousand + Ok(Amount::new(total_fee)) + } +} + +/// BIP353 methods for Wallet +#[cfg(feature = "bip353")] +#[uniffi::export(async_runtime = "tokio")] +impl Wallet { + /// Get a quote for a BIP353 melt + /// + /// This method resolves a BIP353 address (e.g., "alice@example.com") to a Lightning offer + /// and then creates a melt quote for that offer. + pub async fn melt_bip353_quote( + &self, + bip353_address: String, + amount_msat: Amount, + ) -> Result { + let cdk_amount: cdk::Amount = amount_msat.into(); + let quote = self + .inner + .melt_bip353_quote(&bip353_address, cdk_amount) + .await?; + Ok(quote.into()) + } +} + +/// Auth methods for Wallet +#[cfg(feature = "auth")] +#[uniffi::export(async_runtime = "tokio")] +impl Wallet { + /// Set Clear Auth Token (CAT) for authentication + pub async fn set_cat(&self, cat: String) -> Result<(), FfiError> { + self.inner.set_cat(cat).await?; + Ok(()) + } + + /// Set refresh token for authentication + pub async fn set_refresh_token(&self, refresh_token: String) -> Result<(), FfiError> { + self.inner.set_refresh_token(refresh_token).await?; + Ok(()) + } + + /// Refresh access token using the stored refresh token + pub async fn refresh_access_token(&self) -> Result<(), FfiError> { + self.inner.refresh_access_token().await?; + Ok(()) + } + + /// Mint blind auth tokens + pub async fn mint_blind_auth(&self, amount: Amount) -> Result { + let proofs = self.inner.mint_blind_auth(amount.into()).await?; + Ok(proofs + .into_iter() + .map(|p| std::sync::Arc::new(p.into())) + .collect()) + } + + /// Get unspent auth proofs + pub async fn get_unspent_auth_proofs(&self) -> Result, FfiError> { + let auth_proofs = self.inner.get_unspent_auth_proofs().await?; + Ok(auth_proofs.into_iter().map(Into::into).collect()) + } +} + +/// Configuration for creating wallets +#[derive(Debug, Clone, uniffi::Record)] +pub struct WalletConfig { + pub target_proof_count: Option, +} + +/// Generates a new random mnemonic phrase +#[uniffi::export] +pub fn generate_mnemonic() -> Result { + let mnemonic = + Mnemonic::generate(12).map_err(|e| FfiError::InvalidMnemonic { msg: e.to_string() })?; + Ok(mnemonic.to_string()) +} + +/// Converts a mnemonic phrase to its entropy bytes +#[uniffi::export] +pub fn mnemonic_to_entropy(mnemonic: String) -> Result, FfiError> { + let m = + Mnemonic::parse(&mnemonic).map_err(|e| FfiError::InvalidMnemonic { msg: e.to_string() })?; + Ok(m.to_entropy()) +} diff --git a/crates/cdk-ffi/uniffi.toml b/crates/cdk-ffi/uniffi.toml new file mode 100644 index 000000000..7b95d596a --- /dev/null +++ b/crates/cdk-ffi/uniffi.toml @@ -0,0 +1,10 @@ +[bindings.kotlin] +package_name = "org.cashudevkit" +cdylib_name = "cdk_ffi" + +[bindings.python] +cdylib_name = "cdk_ffi" + +[bindings.swift] +module_name = "CashuDevKit" +cdylib_name = "cdk_ffi" diff --git a/justfile b/justfile index adec0bd87..2fe9d06dd 100644 --- a/justfile +++ b/justfile @@ -348,6 +348,13 @@ release m="": echo done + # Extract version from the cdk-ffi crate + VERSION=$(cargo metadata --format-version 1 --no-deps | jq -r '.packages[] | select(.name == "cdk-ffi") | .version') + + # Trigger Swift package release after Rust crates are published + echo "📦 Triggering Swift package release for version $VERSION..." + just ffi-release-swift $VERSION + check-docs: #!/usr/bin/env bash set -euo pipefail @@ -404,3 +411,147 @@ docs-strict: RUSTDOCFLAGS="-D warnings" cargo doc $arg --all-features --no-deps echo done + +# ============================================================================= +# FFI Commands - CDK Foreign Function Interface bindings +# ============================================================================= + +# Helper function to get library extension based on platform +_ffi-lib-ext: + #!/usr/bin/env bash + if [[ "$OSTYPE" == "darwin"* ]]; then + echo "dylib" + else + echo "so" + fi + +# Build the FFI library +ffi-build *ARGS="--release": + cargo build {{ARGS}} --package cdk-ffi + +# Generate bindings for a specific language +ffi-generate LANGUAGE *ARGS="--release": ffi-build + #!/usr/bin/env bash + set -euo pipefail + LANG="{{LANGUAGE}}" + + # Validate language + case "$LANG" in + python|swift|kotlin) + ;; + *) + echo "❌ Unsupported language: $LANG" + echo "Supported languages: python, swift, kotlin" + exit 1 + ;; + esac + + # Set emoji and build type + case "$LANG" in + python) EMOJI="🐍" ;; + swift) EMOJI="🍎" ;; + kotlin) EMOJI="🎯" ;; + esac + + # Determine build type and library path + if [[ "{{ARGS}}" == *"--release"* ]] || [[ "{{ARGS}}" == "" ]]; then + BUILD_TYPE="release" + else + BUILD_TYPE="debug" + cargo build --package cdk-ffi + fi + + LIB_EXT=$(just _ffi-lib-ext) + + echo "$EMOJI Generating $LANG bindings..." + mkdir -p target/bindings/$LANG + + cargo run --bin uniffi-bindgen generate \ + --library target/$BUILD_TYPE/libcdk_ffi.$LIB_EXT \ + --language $LANG \ + --out-dir target/bindings/$LANG + + echo "✅ $LANG bindings generated in target/bindings/$LANG/" + +# Generate Python bindings (shorthand) +ffi-generate-python *ARGS="--release": + just ffi-generate python {{ARGS}} + +# Generate Swift bindings (shorthand) +ffi-generate-swift *ARGS="--release": + just ffi-generate swift {{ARGS}} + +# Generate Kotlin bindings (shorthand) +ffi-generate-kotlin *ARGS="--release": + just ffi-generate kotlin {{ARGS}} + +# Generate bindings for all supported languages +ffi-generate-all *ARGS="--release": ffi-build + @echo "🔧 Generating UniFFI bindings for all languages..." + just ffi-generate python {{ARGS}} + just ffi-generate swift {{ARGS}} + just ffi-generate kotlin {{ARGS}} + @echo "✅ All bindings generated successfully!" + +# Build debug version and generate Python bindings quickly (for development) +ffi-dev-python: + #!/usr/bin/env bash + set -euo pipefail + + # Generate Python bindings first + just ffi-generate python --debug + + # Copy library to Python bindings directory + LIB_EXT=$(just _ffi-lib-ext) + echo "📦 Copying library to Python bindings directory..." + cp target/debug/libcdk_ffi.$LIB_EXT target/bindings/python/ + + # Launch Python REPL with CDK FFI loaded + cd target/bindings/python + echo "🐍 Launching Python REPL with CDK FFI library loaded..." + echo "💡 The 'cdk_ffi' module is pre-imported and ready to use!" + python3 -i -c "from cdk_ffi import *; print('✅ CDK FFI library loaded successfully!');" + +# Test language bindings with a simple import +ffi-test-bindings LANGUAGE: (ffi-generate LANGUAGE "--debug") + #!/usr/bin/env bash + set -euo pipefail + LANG="{{LANGUAGE}}" + LIB_EXT=$(just _ffi-lib-ext) + + echo "📦 Copying library to $LANG bindings directory..." + cp target/debug/libcdk_ffi.$LIB_EXT target/bindings/$LANG/ + + cd target/bindings/$LANG + echo "🧪 Testing $LANG bindings..." + + case "$LANG" in + python) + python3 -c "import cdk_ffi; print('✅ Python bindings work!')" + ;; + *) + echo "✅ $LANG bindings generated (manual testing required)" + ;; + esac + +# Test Python bindings (shorthand) +ffi-test-python: + just ffi-test-bindings python + +# Trigger Swift Package release workflow +ffi-release-swift VERSION: + #!/usr/bin/env bash + set -euo pipefail + + echo "🚀 Triggering Publish Swift Package workflow..." + echo " Version: {{VERSION}}" + echo " CDK Ref: v{{VERSION}}" + + # Trigger the workflow using GitHub CLI + gh workflow run "Publish Swift Package" \ + --repo cashubtc/cdk-swift \ + --field version="{{VERSION}}" \ + --field cdk_repo="cashubtc/cdk" \ + --field cdk_ref="v{{VERSION}}" + + echo "✅ Workflow triggered successfully!" From 053a3a7e43e776dd431a492fd38c222f57b72338 Mon Sep 17 00:00:00 2001 From: C Date: Wed, 10 Sep 2025 06:57:58 -0300 Subject: [PATCH 144/321] Do not fallback to HTTP on first error (#1061) Instead use the same failure counter. Fixes #496 --- crates/cdk/src/wallet/subscription/ws.rs | 36 ++++++++++++++---------- 1 file changed, 21 insertions(+), 15 deletions(-) diff --git a/crates/cdk/src/wallet/subscription/ws.rs b/crates/cdk/src/wallet/subscription/ws.rs index 1e3c834ec..d39fe2381 100644 --- a/crates/cdk/src/wallet/subscription/ws.rs +++ b/crates/cdk/src/wallet/subscription/ws.rs @@ -69,8 +69,6 @@ pub async fn ws_main( }; tracing::debug!("Connected to {}", url); - failure_count = 0; - let (mut write, mut read) = ws_stream.split(); let req_id = AtomicUsize::new(0); @@ -147,23 +145,31 @@ pub async fn ws_main( WsMessageOrResponse::Response(response) => { tracing::debug!("Received response from server: {:?}", response); subscription_requests.remove(&response.id); + // reset connection failure after a successful response from the serer + failure_count = 0; } WsMessageOrResponse::ErrorResponse(error) => { tracing::error!("Received error from server: {:?}", error); + if subscription_requests.contains(&error.id) { - tracing::error!( - "Falling back to HTTP client" - ); - - return http_main( - active_subscriptions.into_keys(), - http_client, - subscriptions, - new_subscription_recv, - on_drop, - wallet, - ) - .await; + failure_count += 1; + if failure_count > MAX_ATTEMPT_FALLBACK_HTTP { + tracing::error!( + "Falling back to HTTP client" + ); + + return http_main( + active_subscriptions.into_keys(), + http_client, + subscriptions, + new_subscription_recv, + on_drop, + wallet, + ) + .await; + } + + break; // break connection to force a reconnection, to attempt to recover form this error } } } From c7f6af07497e7af2c104e88ea5ce18302097e735 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Wed, 10 Sep 2025 14:54:21 +0100 Subject: [PATCH 145/321] fix: clippy warn (#1063) --- .github/workflows/ci.yml | 2 ++ Cargo.toml | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a5cae9b65..08e95af44 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -116,6 +116,8 @@ jobs: -p cdk-signatory, -p cdk-mint-rpc, + + -p cdk-prometheus, # FFI bindings -p cdk-ffi, diff --git a/Cargo.toml b/Cargo.toml index a59baac99..285146b1f 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -8,7 +8,6 @@ resolver = "2" unsafe_code = "forbid" unreachable_pub = "warn" missing_debug_implementations = "warn" -large_enum_variant = "warn" [workspace.lints.clippy] pedantic = "warn" @@ -22,6 +21,7 @@ redundant_else = "warn" redundant_closure_for_method_calls = "warn" unneeded_field_pattern = "warn" use_debug = "warn" +large_enum_variant = "warn" [workspace.lints.rustdoc] missing_docs = "warn" From f2f54253958fb93f715cca12da7ce303bf9efb64 Mon Sep 17 00:00:00 2001 From: David Caseria Date: Wed, 10 Sep 2025 09:54:44 -0400 Subject: [PATCH 146/321] Add more Amount::split_with_fee tests (#1058) --- crates/cashu/src/amount.rs | 134 ++++++++++++++++++++++++++++++++++++- 1 file changed, 131 insertions(+), 3 deletions(-) diff --git a/crates/cashu/src/amount.rs b/crates/cashu/src/amount.rs index 7fc0fa813..db55528ba 100644 --- a/crates/cashu/src/amount.rs +++ b/crates/cashu/src/amount.rs @@ -132,10 +132,10 @@ impl Amount { /// Splits amount into powers of two while accounting for the swap fee pub fn split_with_fee(&self, fee_ppk: u64) -> Result, Error> { let without_fee_amounts = self.split(); - let fee_ppk = fee_ppk + let total_fee_ppk = fee_ppk .checked_mul(without_fee_amounts.len() as u64) .ok_or(Error::AmountOverflow)?; - let fee = Amount::from(fee_ppk.div_ceil(1000)); + let fee = Amount::from(total_fee_ppk.div_ceil(1000)); let new_amount = self.checked_add(fee).ok_or(Error::AmountOverflow)?; let split = new_amount.split(); @@ -456,7 +456,135 @@ mod tests { let fee_ppk = 1000; let split = amount.split_with_fee(fee_ppk).unwrap(); - assert_eq!(split, vec![Amount(32)]); + // With fee_ppk=1000 (100%), amount 3 requires proofs totaling at least 5 + // to cover both the amount (3) and fees (~2 for 2 proofs) + assert_eq!(split, vec![Amount(4), Amount(1)]); + } + + #[test] + fn test_split_with_fee_reported_issue() { + // Test the reported issue: mint 600, send 300 with fee_ppk=100 + let amount = Amount(300); + let fee_ppk = 100; + + let split = amount.split_with_fee(fee_ppk).unwrap(); + + // Calculate the total fee for the split + let total_fee_ppk = (split.len() as u64) * fee_ppk; + let total_fee = Amount::from(total_fee_ppk.div_ceil(1000)); + + // The split should cover the amount plus fees + let split_total = Amount::try_sum(split.iter().copied()).unwrap(); + assert!( + split_total >= amount + total_fee, + "Split total {} should be >= amount {} + fee {}", + split_total, + amount, + total_fee + ); + } + + #[test] + fn test_split_with_fee_edge_cases() { + // Test various amounts with fee_ppk=100 + let test_cases = vec![ + (Amount(1), 100), + (Amount(10), 100), + (Amount(50), 100), + (Amount(100), 100), + (Amount(200), 100), + (Amount(300), 100), + (Amount(500), 100), + (Amount(600), 100), + (Amount(1000), 100), + (Amount(1337), 100), + (Amount(5000), 100), + ]; + + for (amount, fee_ppk) in test_cases { + let result = amount.split_with_fee(fee_ppk); + assert!( + result.is_ok(), + "split_with_fee failed for amount {} with fee_ppk {}: {:?}", + amount, + fee_ppk, + result.err() + ); + + let split = result.unwrap(); + + // Verify the split covers the required amount + let split_total = Amount::try_sum(split.iter().copied()).unwrap(); + let fee_for_split = (split.len() as u64) * fee_ppk; + let total_fee = Amount::from(fee_for_split.div_ceil(1000)); + + // The net amount after fees should be at least the original amount + let net_amount = split_total.checked_sub(total_fee); + assert!( + net_amount.is_some(), + "Net amount calculation failed for amount {} with fee_ppk {}", + amount, + fee_ppk + ); + assert!( + net_amount.unwrap() >= amount, + "Net amount {} is less than required {} for amount {} with fee_ppk {}", + net_amount.unwrap(), + amount, + amount, + fee_ppk + ); + } + } + + #[test] + fn test_split_with_fee_high_fees() { + // Test with very high fees + let test_cases = vec![ + (Amount(10), 500), // 50% fee + (Amount(10), 1000), // 100% fee + (Amount(10), 2000), // 200% fee + (Amount(100), 500), + (Amount(100), 1000), + (Amount(100), 2000), + ]; + + for (amount, fee_ppk) in test_cases { + let result = amount.split_with_fee(fee_ppk); + assert!( + result.is_ok(), + "split_with_fee failed for amount {} with fee_ppk {}: {:?}", + amount, + fee_ppk, + result.err() + ); + + let split = result.unwrap(); + let split_total = Amount::try_sum(split.iter().copied()).unwrap(); + + // With high fees, we just need to ensure we can cover the amount + assert!( + split_total > amount, + "Split total {} should be greater than amount {} for fee_ppk {}", + split_total, + amount, + fee_ppk + ); + } + } + + #[test] + fn test_split_with_fee_recursion_limit() { + // Test that the recursion doesn't go infinite + // This tests the edge case where the method keeps adding Amount::ONE + let amount = Amount(1); + let fee_ppk = 10000; // Very high fee that might cause recursion + + let result = amount.split_with_fee(fee_ppk); + assert!( + result.is_ok(), + "split_with_fee should handle extreme fees without infinite recursion" + ); } #[test] From 0bf532592791f789db60e90a2c500591a23af5ee Mon Sep 17 00:00:00 2001 From: C Date: Fri, 12 Sep 2025 13:17:40 -0300 Subject: [PATCH 147/321] Fixed error with wrong placeholder (#1069) * Fixed error with wrong placeholder Add concept of schema, so each test is isolated --- .../cdk-common/src/database/mint/test/mod.rs | 8 ++- .../src/database/mint/test/proofs.rs | 52 +++++++++++++- crates/cdk-postgres/src/lib.rs | 69 ++++++++++++++++--- crates/cdk-sql-common/src/mint/mod.rs | 4 +- crates/cdk-sqlite/src/mint/mod.rs | 2 +- 5 files changed, 121 insertions(+), 14 deletions(-) diff --git a/crates/cdk-common/src/database/mint/test/mod.rs b/crates/cdk-common/src/database/mint/test/mod.rs index 9852ab2df..abc5d53ec 100644 --- a/crates/cdk-common/src/database/mint/test/mod.rs +++ b/crates/cdk-common/src/database/mint/test/mod.rs @@ -229,6 +229,7 @@ macro_rules! mint_db_test { add_mint_quote_only_once, register_payments, read_mint_from_db_and_tx, + get_proofs_by_keyset_id, reject_duplicate_payments_same_tx, reject_duplicate_payments_diff_tx, reject_over_issue_same_tx, @@ -241,7 +242,12 @@ macro_rules! mint_db_test { $( #[tokio::test] async fn $name() { - cdk_common::database::mint::test::$name($make_db_fn().await).await; + use std::time::{SystemTime, UNIX_EPOCH}; + let now = SystemTime::now() + .duration_since(UNIX_EPOCH) + .expect("Time went backwards"); + + cdk_common::database::mint::test::$name($make_db_fn(format!("test_{}_{}", now.as_nanos(), stringify!($name))).await).await; } )+ }; diff --git a/crates/cdk-common/src/database/mint/test/proofs.rs b/crates/cdk-common/src/database/mint/test/proofs.rs index d960e5267..ef29ca407 100644 --- a/crates/cdk-common/src/database/mint/test/proofs.rs +++ b/crates/cdk-common/src/database/mint/test/proofs.rs @@ -1,11 +1,61 @@ //! Proofs tests +use std::str::FromStr; + use cashu::secret::Secret; -use cashu::{Amount, SecretKey}; +use cashu::{Amount, Id, SecretKey}; use crate::database::mint::test::setup_keyset; use crate::database::mint::{Database, Error, KeysDatabase, Proof, QuoteId}; +/// Test get proofs by keyset id +pub async fn get_proofs_by_keyset_id(db: DB) +where + DB: Database + KeysDatabase, +{ + let keyset_id = setup_keyset(&db).await; + let quote_id = QuoteId::new_uuid(); + let proofs = vec![ + Proof { + amount: Amount::from(100), + keyset_id, + secret: Secret::generate(), + c: SecretKey::generate().public_key(), + witness: None, + dleq: None, + }, + Proof { + amount: Amount::from(200), + keyset_id, + secret: Secret::generate(), + c: SecretKey::generate().public_key(), + witness: None, + dleq: None, + }, + ]; + + // Add proofs to database + let mut tx = Database::begin_transaction(&db).await.unwrap(); + tx.add_proofs(proofs, Some(quote_id)).await.unwrap(); + assert!(tx.commit().await.is_ok()); + + let (proofs, states) = db.get_proofs_by_keyset_id(&keyset_id).await.unwrap(); + assert_eq!(proofs.len(), 2); + assert_eq!(proofs.len(), states.len()); + assert_eq!( + states + .into_iter() + .map(|s| s.map(|x| x.to_string()).unwrap_or_default()) + .collect::>(), + vec!["UNSPENT".to_owned(), "UNSPENT".to_owned()] + ); + + let keyset_id = Id::from_str("00916bbf7ef91a34").unwrap(); + let (proofs, states) = db.get_proofs_by_keyset_id(&keyset_id).await.unwrap(); + assert_eq!(proofs.len(), 0); + assert_eq!(proofs.len(), states.len()); +} + /// Test the basic storing and retrieving proofs from the database. Probably the database would use /// binary/`Vec` to store data, that's why this test would quickly identify issues before running /// other tests diff --git a/crates/cdk-postgres/src/lib.rs b/crates/cdk-postgres/src/lib.rs index 579b966f8..92149d74b 100644 --- a/crates/cdk-postgres/src/lib.rs +++ b/crates/cdk-postgres/src/lib.rs @@ -54,6 +54,7 @@ impl Debug for SslMode { #[derive(Clone, Debug)] pub struct PgConfig { url: String, + schema: Option, tls: SslMode, } @@ -67,8 +68,29 @@ impl DatabaseConfig for PgConfig { } } +impl PgConfig { + /// strip schema from the connection string + fn strip_schema(input: &str) -> (Option, String) { + let mut schema: Option = None; + + // Split by whitespace + let mut parts = Vec::new(); + for token in input.split_whitespace() { + if let Some(rest) = token.strip_prefix("schema=") { + schema = Some(rest.to_string()); + } else { + parts.push(token); + } + } + + let cleaned = parts.join(" "); + (schema, cleaned) + } +} + impl From<&str> for PgConfig { fn from(conn_str: &str) -> Self { + let (schema, conn_str) = Self::strip_schema(conn_str); fn build_tls(accept_invalid_certs: bool, accept_invalid_hostnames: bool) -> SslMode { let mut builder = TlsConnector::builder(); if accept_invalid_certs { @@ -105,6 +127,7 @@ impl From<&str> for PgConfig { PgConfig { url: conn_str.to_owned(), + schema, tls, } } @@ -149,6 +172,17 @@ impl PostgresConnection { let result_clone = result.clone(); let notify_clone = notify.clone(); + async fn select_schema(conn: &Client, schema: &str) -> Result<(), Error> { + conn.batch_execute(&format!( + r#" + CREATE SCHEMA IF NOT EXISTS "{schema}"; + SET search_path TO "{schema}" + "# + )) + .await + .map_err(|e| Error::Database(Box::new(e))) + } + tokio::spawn(async move { match config.tls { SslMode::NoTls(tls) => { @@ -163,11 +197,21 @@ impl PostgresConnection { } }; + let still_valid_for_spawn = still_valid.clone(); tokio::spawn(async move { let _ = connection.await; - still_valid.store(false, std::sync::atomic::Ordering::Release); + still_valid_for_spawn.store(false, std::sync::atomic::Ordering::Release); }); + if let Some(schema) = config.schema.as_ref() { + if let Err(err) = select_schema(&client, schema).await { + *error_clone.lock().await = Some(err); + still_valid.store(false, std::sync::atomic::Ordering::Release); + notify_clone.notify_waiters(); + return; + } + } + let _ = result_clone.set(client); notify_clone.notify_waiters(); } @@ -183,11 +227,21 @@ impl PostgresConnection { } }; + let still_valid_for_spawn = still_valid.clone(); tokio::spawn(async move { let _ = connection.await; - still_valid.store(false, std::sync::atomic::Ordering::Release); + still_valid_for_spawn.store(false, std::sync::atomic::Ordering::Release); }); + if let Some(schema) = config.schema.as_ref() { + if let Err(err) = select_schema(&client, schema).await { + *error_clone.lock().await = Some(err); + still_valid.store(false, std::sync::atomic::Ordering::Release); + notify_clone.notify_waiters(); + return; + } + } + let _ = result_clone.set(client); notify_clone.notify_waiters(); } @@ -275,22 +329,19 @@ pub type WalletPgDatabase = SQLWalletDatabase; #[cfg(test)] mod test { use cdk_common::mint_db_test; - use once_cell::sync::Lazy; - use tokio::sync::Mutex; use super::*; - static MIGRATION_LOCK: Lazy> = Lazy::new(|| Mutex::new(())); - - async fn provide_db() -> MintPgDatabase { - let m = MIGRATION_LOCK.lock().await; + async fn provide_db(test_id: String) -> MintPgDatabase { let db_url = std::env::var("CDK_MINTD_DATABASE_URL") .or_else(|_| std::env::var("PG_DB_URL")) // Fallback for compatibility .unwrap_or("host=localhost user=test password=test dbname=testdb port=5433".to_owned()); + + let db_url = format!("{db_url} schema={test_id}"); + let db = MintPgDatabase::new(db_url.as_str()) .await .expect("database"); - drop(m); db } diff --git a/crates/cdk-sql-common/src/mint/mod.rs b/crates/cdk-sql-common/src/mint/mod.rs index 935e825dd..e86b354d4 100644 --- a/crates/cdk-sql-common/src/mint/mod.rs +++ b/crates/cdk-sql-common/src/mint/mod.rs @@ -923,7 +923,7 @@ VALUES (:quote_id, :amount, :timestamp); query( r#" DELETE FROM melt_quote - WHERE id=? + WHERE id=:id "#, )? .bind("id", quote_id.to_string()) @@ -1452,7 +1452,7 @@ where FROM proof WHERE - keyset_id=? + keyset_id=:keyset_id "#, )? .bind("keyset_id", keyset_id.to_string()) diff --git a/crates/cdk-sqlite/src/mint/mod.rs b/crates/cdk-sqlite/src/mint/mod.rs index 14909e80f..f95bd78fa 100644 --- a/crates/cdk-sqlite/src/mint/mod.rs +++ b/crates/cdk-sqlite/src/mint/mod.rs @@ -25,7 +25,7 @@ mod test { use super::*; use crate::common::Config; - async fn provide_db() -> MintSqliteDatabase { + async fn provide_db(_test_name: String) -> MintSqliteDatabase { memory::empty().await.unwrap() } From 835c66dd551d998339d019a1a53847e37c21c37c Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Sat, 13 Sep 2025 09:17:12 +0100 Subject: [PATCH 148/321] fix: keyset max order checked (#1070) --- crates/cdk-signatory/src/common.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/cdk-signatory/src/common.rs b/crates/cdk-signatory/src/common.rs index d7d4d3443..b6c39deed 100644 --- a/crates/cdk-signatory/src/common.rs +++ b/crates/cdk-signatory/src/common.rs @@ -59,7 +59,7 @@ pub async fn init_keysets( if let Some((input_fee_ppk, max_order)) = supported_units.get(&unit) { if !keysets.is_empty() && &highest_index_keyset.input_fee_ppk == input_fee_ppk - && &highest_index_keyset.max_order == max_order + && highest_index_keyset.amounts.len() == (*max_order as usize) { tracing::debug!("Current highest index keyset matches expect fee and max order. Setting active"); let id = highest_index_keyset.id; From aab85d2083ab9f23c6f51a1563f767ae1ed8c421 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Sat, 13 Sep 2025 11:12:00 +0100 Subject: [PATCH 149/321] feat: update redb (#1071) --- crates/cdk-redb/Cargo.toml | 2 +- crates/cdk-redb/src/error.rs | 9 +++++++++ crates/cdk-redb/src/wallet/mod.rs | 4 +++- 3 files changed, 13 insertions(+), 2 deletions(-) diff --git a/crates/cdk-redb/Cargo.toml b/crates/cdk-redb/Cargo.toml index 7e12fd576..94a0c520e 100644 --- a/crates/cdk-redb/Cargo.toml +++ b/crates/cdk-redb/Cargo.toml @@ -19,7 +19,7 @@ auth = ["cdk-common/auth"] [dependencies] async-trait.workspace = true cdk-common = { workspace = true, features = ["test"] } -redb = "2.4.0" +redb = "2.6.3" thiserror.workspace = true tracing.workspace = true serde.workspace = true diff --git a/crates/cdk-redb/src/error.rs b/crates/cdk-redb/src/error.rs index 6784594f4..195e024bf 100644 --- a/crates/cdk-redb/src/error.rs +++ b/crates/cdk-redb/src/error.rs @@ -25,6 +25,9 @@ pub enum Error { /// Redb Storage Error #[error(transparent)] Storage(#[from] Box), + /// Upgrade Transaction Error + #[error(transparent)] + Upgrade(#[from] Box), /// Serde Json Error #[error(transparent)] Serde(#[from] serde_json::Error), @@ -111,3 +114,9 @@ impl From for Error { Self::Storage(Box::new(e)) } } + +impl From for Error { + fn from(e: redb::UpgradeError) -> Self { + Self::Upgrade(Box::new(e)) + } +} diff --git a/crates/cdk-redb/src/wallet/mod.rs b/crates/cdk-redb/src/wallet/mod.rs index 711f3a79e..37862fc2e 100644 --- a/crates/cdk-redb/src/wallet/mod.rs +++ b/crates/cdk-redb/src/wallet/mod.rs @@ -156,7 +156,9 @@ impl WalletRedbDatabase { drop(db); } - let db = Database::create(path)?; + let mut db = Database::create(path)?; + + db.upgrade()?; Ok(Self { db: Arc::new(db) }) } From 2c9333449a567467045e259a64d64fe75668a776 Mon Sep 17 00:00:00 2001 From: gudnuf <108303703+gudnuf@users.noreply.github.com> Date: Sat, 13 Sep 2025 03:12:41 -0700 Subject: [PATCH 150/321] fix: replace std::time with instant for wasm (#1060) --- Cargo.toml | 2 +- crates/cashu/Cargo.toml | 2 +- crates/cashu/src/util/mod.rs | 14 +++----------- crates/cdk-common/Cargo.toml | 2 +- crates/cdk-integration-tests/Cargo.toml | 2 +- crates/cdk/Cargo.toml | 1 + .../cdk/src/wallet/mint_connector/http_client.rs | 2 +- crates/cdk/src/wallet/subscription/http.rs | 2 +- 8 files changed, 10 insertions(+), 17 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 285146b1f..af070a815 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -99,7 +99,7 @@ reqwest = { version = "0.12", default-features = false, features = [ "deflate", ]} once_cell = "1.20.2" -instant = { version = "0.1", default-features = false } +web-time = "1.1.0" rand = "0.9.1" regex = "1" home = "0.5.5" diff --git a/crates/cashu/Cargo.toml b/crates/cashu/Cargo.toml index 2ca6532ca..affd6f52f 100644 --- a/crates/cashu/Cargo.toml +++ b/crates/cashu/Cargo.toml @@ -37,9 +37,9 @@ regex = { workspace = true, optional = true } strum = { workspace = true, optional = true } strum_macros = { workspace = true, optional = true } zeroize = "1" +web-time.workspace = true [target.'cfg(target_arch = "wasm32")'.dependencies] -instant = { workspace = true, features = ["wasm-bindgen", "inaccurate"] } uuid = { workspace = true, features = ["js"], optional = true } [dev-dependencies] diff --git a/crates/cashu/src/util/mod.rs b/crates/cashu/src/util/mod.rs index ae86f8a80..8afa9f64a 100644 --- a/crates/cashu/src/util/mod.rs +++ b/crates/cashu/src/util/mod.rs @@ -1,18 +1,10 @@ //! Cashu utils -#[cfg(not(target_arch = "wasm32"))] -use std::time::{SystemTime, UNIX_EPOCH}; +pub mod hex; use bitcoin::secp256k1::{rand, All, Secp256k1}; use once_cell::sync::Lazy; - -pub mod hex; - -#[cfg(target_arch = "wasm32")] -use instant::SystemTime; - -#[cfg(target_arch = "wasm32")] -const UNIX_EPOCH: SystemTime = SystemTime::UNIX_EPOCH; +use web_time::{SystemTime, UNIX_EPOCH}; /// Secp256k1 global context pub static SECP256K1: Lazy> = Lazy::new(|| { @@ -46,7 +38,7 @@ pub enum CborError { /// /// See pub fn serialize_to_cbor_diag(data: &T) -> Result { - let mut cbor_buffer = Vec::new(); + let mut cbor_buffer = Vec::::new(); ciborium::ser::into_writer(data, &mut cbor_buffer)?; let diag = cbor_diag::parse_bytes(&cbor_buffer)?; diff --git a/crates/cdk-common/Cargo.toml b/crates/cdk-common/Cargo.toml index d19e851a0..2ca99661a 100644 --- a/crates/cdk-common/Cargo.toml +++ b/crates/cdk-common/Cargo.toml @@ -39,9 +39,9 @@ futures.workspace = true anyhow.workspace = true serde_json.workspace = true serde_with.workspace = true +web-time.workspace = true [target.'cfg(target_arch = "wasm32")'.dependencies] -instant = { workspace = true, features = ["wasm-bindgen", "inaccurate"] } uuid = { workspace = true, features = ["js"], optional = true } [dev-dependencies] diff --git a/crates/cdk-integration-tests/Cargo.toml b/crates/cdk-integration-tests/Cargo.toml index 8e5dce7f9..30f314525 100644 --- a/crates/cdk-integration-tests/Cargo.toml +++ b/crates/cdk-integration-tests/Cargo.toml @@ -50,6 +50,7 @@ tokio-util.workspace = true reqwest.workspace = true bitcoin = "0.32.0" clap = { workspace = true, features = ["derive"] } +web-time.workspace = true [target.'cfg(not(target_arch = "wasm32"))'.dependencies] tokio.workspace = true @@ -57,7 +58,6 @@ tokio.workspace = true [target.'cfg(target_arch = "wasm32")'.dependencies] tokio = { workspace = true, features = ["rt", "macros", "sync", "time"] } getrandom = { version = "0.2", features = ["js"] } -instant = { workspace = true, features = ["wasm-bindgen", "inaccurate"] } uuid = { workspace = true, features = ["js"] } [dev-dependencies] diff --git a/crates/cdk/Cargo.toml b/crates/cdk/Cargo.toml index 529dfebbd..17ae3e76a 100644 --- a/crates/cdk/Cargo.toml +++ b/crates/cdk/Cargo.toml @@ -45,6 +45,7 @@ uuid.workspace = true jsonwebtoken = { workspace = true, optional = true } trust-dns-resolver = { version = "0.23.2", optional = true } cdk-prometheus = {workspace = true, optional = true} +web-time.workspace = true # -Z minimal-versions sync_wrapper = "0.1.2" bech32 = "0.9.1" diff --git a/crates/cdk/src/wallet/mint_connector/http_client.rs b/crates/cdk/src/wallet/mint_connector/http_client.rs index 93cb752c9..9a71cbf20 100644 --- a/crates/cdk/src/wallet/mint_connector/http_client.rs +++ b/crates/cdk/src/wallet/mint_connector/http_client.rs @@ -1,7 +1,6 @@ //! HTTP Mint client with pluggable transport use std::collections::HashSet; use std::sync::{Arc, RwLock as StdRwLock}; -use std::time::{Duration, Instant}; use async_trait::async_trait; use cdk_common::{nut19, MeltQuoteBolt12Request, MintQuoteBolt12Request, MintQuoteBolt12Response}; @@ -13,6 +12,7 @@ use serde::Serialize; use tokio::sync::RwLock; use tracing::instrument; use url::Url; +use web_time::{Duration, Instant}; use super::transport::Transport; use super::{Error, MintConnector}; diff --git a/crates/cdk/src/wallet/subscription/http.rs b/crates/cdk/src/wallet/subscription/http.rs index 22290e913..9933465cc 100644 --- a/crates/cdk/src/wallet/subscription/http.rs +++ b/crates/cdk/src/wallet/subscription/http.rs @@ -1,10 +1,10 @@ use std::collections::HashMap; use std::sync::Arc; -use std::time::Duration; use cdk_common::MintQuoteBolt12Response; use tokio::sync::{mpsc, RwLock}; use tokio::time; +use web_time::Duration; use super::WsSubscriptionBody; use crate::nuts::nut17::Kind; From 7d78240da5ed56ed82eb033b07393b503a48c48c Mon Sep 17 00:00:00 2001 From: Erik <78821053+swedishfrenchpress@users.noreply.github.com> Date: Mon, 15 Sep 2025 15:51:23 +0200 Subject: [PATCH 151/321] Improve web interface with dynamic status, navigation, and mobile support (#1073) * Improve transaction confirmation UI: reorder elements, move buttons to details card, shorten button text * feat: real node status --------- Co-authored-by: thesimplekid --- .../cdk-ldk-node/src/web/handlers/channels.rs | 53 ++- .../src/web/handlers/dashboard.rs | 7 +- .../cdk-ldk-node/src/web/handlers/invoices.rs | 16 +- .../src/web/handlers/lightning.rs | 7 +- .../cdk-ldk-node/src/web/handlers/onchain.rs | 204 ++++----- .../cdk-ldk-node/src/web/handlers/payments.rs | 50 ++- .../cdk-ldk-node/src/web/templates/layout.rs | 388 ++++++++++++++++-- crates/cdk-ldk-node/static/images/bg-dark.jpg | Bin 43605 -> 361525 bytes crates/cdk-ldk-node/static/images/bg.jpg | Bin 620237 -> 147110 bytes 9 files changed, 536 insertions(+), 189 deletions(-) diff --git a/crates/cdk-ldk-node/src/web/handlers/channels.rs b/crates/cdk-ldk-node/src/web/handlers/channels.rs index dcbe010f7..654a29e1b 100644 --- a/crates/cdk-ldk-node/src/web/handlers/channels.rs +++ b/crates/cdk-ldk-node/src/web/handlers/channels.rs @@ -15,7 +15,8 @@ use serde::Deserialize; use crate::web::handlers::utils::deserialize_optional_u64; use crate::web::handlers::AppState; use crate::web::templates::{ - error_message, form_card, format_sats_as_btc, info_card, layout, success_message, + error_message, form_card, format_sats_as_btc, info_card, is_node_running, layout_with_status, + success_message, }; #[derive(Deserialize)] @@ -43,7 +44,7 @@ pub async fn channels_page(State(_state): State) -> Result) -> Result, StatusCode> { +pub async fn open_channel_page(State(state): State) -> Result, StatusCode> { let content = form_card( "Open New Channel", html! { @@ -68,14 +69,18 @@ pub async fn open_channel_page(State(_state): State) -> Result) -> Result, St } }; - Ok(Html(layout("Dashboard", content).into_string())) + let is_running = is_node_running(&state.node.inner); + Ok(Html( + layout_with_status("Dashboard", content, is_running).into_string(), + )) } diff --git a/crates/cdk-ldk-node/src/web/handlers/invoices.rs b/crates/cdk-ldk-node/src/web/handlers/invoices.rs index 7d181d546..7691e3838 100644 --- a/crates/cdk-ldk-node/src/web/handlers/invoices.rs +++ b/crates/cdk-ldk-node/src/web/handlers/invoices.rs @@ -10,7 +10,8 @@ use serde::Deserialize; use crate::web::handlers::utils::{deserialize_optional_f64, deserialize_optional_u32}; use crate::web::handlers::AppState; use crate::web::templates::{ - error_message, form_card, format_sats_as_btc, info_card, layout, success_message, + error_message, form_card, format_sats_as_btc, info_card, is_node_running, layout_with_status, + success_message, }; #[derive(Deserialize)] @@ -30,7 +31,7 @@ pub struct CreateBolt12Form { expiry_seconds: Option, } -pub async fn invoices_page(State(_state): State) -> Result, StatusCode> { +pub async fn invoices_page(State(state): State) -> Result, StatusCode> { let content = html! { h2 style="text-align: center; margin-bottom: 3rem;" { "Invoices" } div class="grid" { @@ -78,7 +79,10 @@ pub async fn invoices_page(State(_state): State) -> Result) -> Result, StatusCode> { let balances = state.node.inner.list_balances(); @@ -216,5 +216,8 @@ pub async fn balance_page(State(state): State) -> Result, } }; - Ok(Html(layout("Lightning", content).into_string())) + let is_running = is_node_running(&state.node.inner); + Ok(Html( + layout_with_status("Lightning", content, is_running).into_string(), + )) } diff --git a/crates/cdk-ldk-node/src/web/handlers/onchain.rs b/crates/cdk-ldk-node/src/web/handlers/onchain.rs index 1658d0e0a..0a296fafd 100644 --- a/crates/cdk-ldk-node/src/web/handlers/onchain.rs +++ b/crates/cdk-ldk-node/src/web/handlers/onchain.rs @@ -13,7 +13,8 @@ use serde::{Deserialize, Serialize}; use crate::web::handlers::utils::deserialize_optional_u64; use crate::web::handlers::AppState; use crate::web::templates::{ - error_message, form_card, format_sats_as_btc, info_card, layout, success_message, + error_message, form_card, format_sats_as_btc, info_card, is_node_running, layout_with_status, + success_message, }; #[derive(Deserialize, Serialize)] @@ -32,24 +33,54 @@ pub struct ConfirmOnchainForm { confirmed: Option, } +fn quick_actions_section() -> maud::Markup { + html! { + div class="card" style="margin-bottom: 2rem;" { + h2 { "Quick Actions" } + div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); gap: 1.5rem; margin-top: 1.5rem;" { + // Receive Bitcoin Card + div class="quick-action-card" { + h3 style="font-size: 1.125rem; font-weight: 600; margin-bottom: 0.5rem; color: var(--text-primary);" { "Receive Bitcoin" } + p style="font-size: 0.875rem; color: var(--text-muted); margin-bottom: 1rem; line-height: 1.4;" { "Generate a new Bitcoin address to receive on-chain payments from other users or services." } + a href="/onchain?action=receive" style="text-decoration: none;" { + button class="button-outline" { "Receive Bitcoin" } + } + } + + // Send Bitcoin Card + div class="quick-action-card" { + h3 style="font-size: 1.125rem; font-weight: 600; margin-bottom: 0.5rem; color: var(--text-primary);" { "Send Bitcoin" } + p style="font-size: 0.875rem; color: var(--text-muted); margin-bottom: 1rem; line-height: 1.4;" { "Send Bitcoin to another address on the blockchain. Standard on-chain transactions." } + a href="/onchain?action=send" style="text-decoration: none;" { + button class="button-outline" { "Send Bitcoin" } + } + } + } + } + } +} + pub async fn get_new_address(State(state): State) -> Result, StatusCode> { let address_result = state.node.inner.onchain_payment().new_address(); let content = match address_result { Ok(address) => { html! { - (success_message(&format!("New address generated: {address}"))) div class="card" { h2 { "Bitcoin Address" } - div class="info-item" { - span class="info-label" { "Address:" } - span class="info-value" style="font-family: monospace; font-size: 0.9rem;" { (address.to_string()) } + div class="address-display" { + div class="address-container" { + span class="address-text" { (address.to_string()) } + } } } div class="card" { - a href="/onchain" { button { "← Back to On-chain" } } - " " - a href="/onchain/new-address" { button { "Generate Another Address" } } + div style="display: flex; justify-content: space-between; gap: 1rem;" { + a href="/onchain" { button class="button-secondary" { "Back" } } + form method="post" action="/onchain/new-address" style="display: inline;" { + button class="button-primary" type="submit" { "Generate Another Address" } + } + } } } } @@ -57,13 +88,16 @@ pub async fn get_new_address(State(state): State) -> Result, -) -> Result, StatusCode> { +pub async fn send_payments_page(State(state): State) -> Result, StatusCode> { let content = html! { h2 style="text-align: center; margin-bottom: 3rem;" { "Send Payment" } div class="grid" { @@ -280,13 +281,12 @@ pub async fn send_payments_page( )) } - div class="card" { - h3 { "Payment History" } - a href="/payments" { button { "View All Payments" } } - } }; - Ok(Html(layout("Send Payments", content).into_string())) + let is_running = is_node_running(&state.node.inner); + Ok(Html( + layout_with_status("Send Payments", content, is_running).into_string(), + )) } pub async fn post_pay_bolt11( @@ -306,7 +306,9 @@ pub async fn post_pay_bolt11( return Ok(Response::builder() .status(StatusCode::BAD_REQUEST) .header("content-type", "text/html") - .body(Body::from(layout("Payment Error", content).into_string())) + .body(Body::from( + layout_with_status("Payment Error", content, true).into_string(), + )) .unwrap()); } }; @@ -348,7 +350,9 @@ pub async fn post_pay_bolt11( return Ok(Response::builder() .status(StatusCode::INTERNAL_SERVER_ERROR) .header("content-type", "text/html") - .body(Body::from(layout("Payment Error", content).into_string())) + .body(Body::from( + layout_with_status("Payment Error", content, true).into_string(), + )) .unwrap()); } }; @@ -433,7 +437,9 @@ pub async fn post_pay_bolt11( Ok(Response::builder() .header("content-type", "text/html") - .body(Body::from(layout("Payment Result", content).into_string())) + .body(Body::from( + layout_with_status("Payment Result", content, true).into_string(), + )) .unwrap()) } @@ -454,7 +460,9 @@ pub async fn post_pay_bolt12( return Ok(Response::builder() .status(StatusCode::BAD_REQUEST) .header("content-type", "text/html") - .body(Body::from(layout("Payment Error", content).into_string())) + .body(Body::from( + layout_with_status("Payment Error", content, true).into_string(), + )) .unwrap()); } }; @@ -486,7 +494,9 @@ pub async fn post_pay_bolt12( return Ok(Response::builder() .status(StatusCode::BAD_REQUEST) .header("content-type", "text/html") - .body(Body::from(layout("Payment Error", content).into_string())) + .body(Body::from( + layout_with_status("Payment Error", content, true).into_string(), + )) .unwrap()); } }; @@ -518,7 +528,9 @@ pub async fn post_pay_bolt12( return Ok(Response::builder() .status(StatusCode::INTERNAL_SERVER_ERROR) .header("content-type", "text/html") - .body(Body::from(layout("Payment Error", content).into_string())) + .body(Body::from( + layout_with_status("Payment Error", content, true).into_string(), + )) .unwrap()); } }; @@ -610,6 +622,8 @@ pub async fn post_pay_bolt12( Ok(Response::builder() .header("content-type", "text/html") - .body(Body::from(layout("Payment Result", content).into_string())) + .body(Body::from( + layout_with_status("Payment Result", content, true).into_string(), + )) .unwrap()) } diff --git a/crates/cdk-ldk-node/src/web/templates/layout.rs b/crates/cdk-ldk-node/src/web/templates/layout.rs index 4fd25ef80..76cc167d0 100644 --- a/crates/cdk-ldk-node/src/web/templates/layout.rs +++ b/crates/cdk-ldk-node/src/web/templates/layout.rs @@ -1,6 +1,12 @@ +use ldk_node::Node; use maud::{html, Markup, DOCTYPE}; -pub fn layout(title: &str, content: Markup) -> Markup { +/// Helper function to check if the node is running +pub fn is_node_running(node: &Node) -> bool { + node.status().is_running +} + +pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Markup { html! { (DOCTYPE) html lang="en" { @@ -252,12 +258,21 @@ pub fn layout(title: &str, content: Markup) -> Markup { box-shadow: 0 0 0 2px rgba(16, 185, 129, 0.2); } + .status-indicator.status-inactive { + background-color: #ef4444; + box-shadow: 0 0 0 2px rgba(239, 68, 68, 0.2); + } + .status-text { font-size: 0.875rem; font-weight: 500; color: #10b981; } + .status-text.status-inactive { + color: #ef4444; + } + .node-title { font-size: 1.875rem; font-weight: 600; @@ -281,38 +296,104 @@ pub fn layout(title: &str, content: Markup) -> Markup { /* Responsive header */ @media (max-width: 768px) { + header { + height: 180px; /* Slightly taller for better mobile layout */ + padding: 1rem 0; + } + + header .container { + padding: 0 1rem; + height: 100%; + display: flex; + align-items: center; + justify-content: center; + } + .header-content { flex-direction: column; gap: 1rem; text-align: center; + width: 100%; + justify-content: center; } .header-left { flex-direction: column; text-align: center; + align-items: center; + gap: 0.75rem; + } + + .header-avatar { + width: 64px; + height: 64px; + padding: 0.5rem; + } + + .header-avatar-image { + width: 40px; + height: 40px; } .node-title { font-size: 1.5rem; } + + .node-subtitle { + font-size: 0.8125rem; + text-align: center; + } + + .node-status { + justify-content: center; + } } + @media (max-width: 480px) { + header { + height: 160px; + } + + .header-avatar { + width: 56px; + height: 56px; + padding: 0.375rem; + } + + .header-avatar-image { + width: 36px; + height: 36px; + } + + .node-title { + font-size: 1.25rem; + } + + .node-subtitle { + font-size: 0.75rem; + } + } + + /* Dark mode navigation styles */ + @media (prefers-color-scheme: dark) { nav a { color: var(--text-muted) !important; } nav a:hover { color: var(--text-secondary) !important; - background-color: rgba(255, 255, 255, 0.05) !important; + background-color: rgba(255, 255, 255, 0.08) !important; + transform: translateY(-1px) !important; } nav a.active { color: var(--text-primary) !important; - background-color: rgba(255, 255, 255, 0.08) !important; + background-color: rgba(255, 255, 255, 0.1) !important; } nav a.active:hover { - background-color: rgba(255, 255, 255, 0.1) !important; + background-color: rgba(255, 255, 255, 0.12) !important; + transform: translateY(-1px) !important; } } @@ -409,23 +490,6 @@ pub fn layout(title: &str, content: Markup) -> Markup { line-height: 1.6; } - @media (max-width: 768px) { - header { - height: 150px; /* Smaller height on mobile */ - } - - header .container { - padding: 0 1rem; - } - - h1 { - font-size: 2.25rem; - } - - .subtitle { - font-size: 1.1rem; - } - } /* Card fade-in animation */ @keyframes fade-in { @@ -491,6 +555,15 @@ pub fn layout(title: &str, content: Markup) -> Markup { background-color: hsl(var(--muted)); } + /* Light mode navigation hover states */ + @media (prefers-color-scheme: light) { + nav a:hover { + color: hsl(var(--foreground)); + background-color: hsl(var(--muted) / 0.8); + transform: translateY(-1px); + } + } + nav a.active { color: hsl(var(--primary-foreground)); background-color: hsl(var(--primary)); @@ -587,6 +660,20 @@ pub fn layout(title: &str, content: Markup) -> Markup { width: 100%; } + /* Dark mode input field improvements */ + @media (prefers-color-scheme: dark) { + input, textarea, select { + background-color: hsl(0 0% 8%); + border: 1px solid hsl(0 0% 20%); + color: hsl(var(--foreground)); + } + + input:focus, textarea:focus, select:focus { + background-color: hsl(0 0% 10%); + border-color: hsl(var(--ring)); + } + } + input:focus, textarea:focus, select:focus { outline: 2px solid transparent; outline-offset: 2px; @@ -599,6 +686,74 @@ pub fn layout(title: &str, content: Markup) -> Markup { opacity: 0.5; } + /* Subtle pagination dropdown styling */ + .per-page-selector { + display: flex; + align-items: center; + gap: 0.5rem; + margin: 1rem 0 0 0; + padding: 0; + background-color: transparent; + border: none; + border-radius: 0; + font-size: 0.875rem; + } + + .per-page-selector label { + color: hsl(var(--muted-foreground)); + font-weight: 500; + } + + .per-page-selector select { + background-color: transparent; + border: 1px solid hsl(var(--muted)); + border-radius: calc(var(--radius) - 2px); + padding: 0.25rem 0.5rem; + font-size: 0.875rem; + color: hsl(var(--muted-foreground)); + min-width: 50px; + cursor: pointer; + transition: all 0.2s ease; + flex: none; + width: auto; + } + + .per-page-selector select:hover { + border-color: hsl(var(--ring)); + background-color: hsl(var(--muted) / 0.5); + } + + .per-page-selector select:focus { + outline: 2px solid transparent; + outline-offset: 2px; + border-color: hsl(var(--ring)); + box-shadow: 0 0 0 2px hsl(var(--ring) / 0.2); + } + + .per-page-selector span { + color: hsl(var(--muted-foreground)); + font-weight: 500; + } + + /* Form actions layout */ + .form-actions { + display: flex; + justify-content: space-between; + align-items: center; + gap: 1rem; + margin-top: 1.5rem; + padding-top: 1rem; + border-top: 1px solid hsl(var(--border)); + } + + .form-actions .button-secondary { + order: 1; + } + + .form-actions .button-primary { + order: 2; + } + button { display: inline-flex; align-items: center; @@ -1082,6 +1237,14 @@ pub fn layout(title: &str, content: Markup) -> Markup { margin-bottom: 1.5rem; } + /* Dark mode payment card improvements - match other cards */ + @media (prefers-color-scheme: dark) { + .payment-item { + background-color: rgba(255, 255, 255, 0.03) !important; + border: none !important; + } + } + .payment-header { display: flex; justify-content: space-between; @@ -1266,6 +1429,39 @@ pub fn layout(title: &str, content: Markup) -> Markup { border: 1px solid hsl(32 95% 44% / 0.2); } + /* Dark mode payment type badge improvements */ + @media (prefers-color-scheme: dark) { + .payment-type-onchain { + background-color: hsl(32 95% 60% / 0.15); + color: hsl(32 95% 70%); + border: 1px solid hsl(32 95% 60% / 0.3); + } + + .payment-type-bolt11 { + background-color: hsl(217 91% 70% / 0.15); + color: hsl(217 91% 80%); + border: 1px solid hsl(217 91% 70% / 0.3); + } + + .payment-type-bolt12 { + background-color: hsl(262 83% 70% / 0.15); + color: hsl(262 83% 80%); + border: 1px solid hsl(262 83% 70% / 0.3); + } + + .payment-type-spontaneous { + background-color: hsl(142.1 70.6% 60% / 0.15); + color: hsl(142.1 70.6% 75%); + border: 1px solid hsl(142.1 70.6% 60% / 0.3); + } + + .payment-type-bolt11-jit { + background-color: hsl(199 89% 65% / 0.15); + color: hsl(199 89% 80%); + border: 1px solid hsl(199 89% 65% / 0.3); + } + } + .payment-type-spontaneous { background-color: hsl(142.1 70.6% 45.3% / 0.1); color: hsl(142.1 70.6% 45.3%); @@ -1635,6 +1831,147 @@ pub fn layout(title: &str, content: Markup) -> Markup { fill: rgba(156, 163, 175, 0.2); } } + + /* Address display styling */ + .address-display { + margin: 1.5rem 0; + } + + .address-container { + padding: 1rem 0; + } + + .address-text { + font-family: 'SF Mono', 'Monaco', 'Inconsolata', 'Roboto Mono', 'Courier New', monospace; + font-size: 1.25rem; + font-weight: 500; + color: hsl(var(--foreground)); + word-break: break-all; + overflow-wrap: break-word; + hyphens: auto; + flex: 1; + min-width: 0; + line-height: 1.4; + background-color: transparent; + border: none; + padding: 0; + } + + + /* Dark mode address styling */ + @media (prefers-color-scheme: dark) { + .address-text { + color: var(--text-primary) !important; + } + } + + /* Responsive address display */ + @media (max-width: 640px) { + .address-text { + font-size: 1.125rem; + text-align: center; + } + } + + /* Transaction confirmation styling */ + .transaction-details { + margin-top: 1rem; + } + + .transaction-details .detail-row { + display: flex; + align-items: baseline; + margin-bottom: 1rem; + gap: 1rem; + padding: 0.75rem 0; + border-bottom: 1px solid hsl(var(--border)); + } + + .transaction-details .detail-row:last-child { + border-bottom: none; + margin-bottom: 0; + } + + .transaction-details .detail-label { + font-weight: 500; + color: hsl(var(--muted-foreground)); + font-size: 0.875rem; + min-width: 180px; + flex-shrink: 0; + } + + .transaction-details .detail-value { + color: hsl(var(--foreground)); + font-family: 'SF Mono', 'Monaco', 'Inconsolata', 'Roboto Mono', 'Courier New', monospace; + font-size: 0.875rem; + word-break: break-all; + flex: 1; + min-width: 0; + } + + .transaction-details .detail-value-amount { + color: hsl(var(--foreground)); + font-family: 'SF Mono', 'Monaco', 'Inconsolata', 'Roboto Mono', 'Courier New', monospace; + font-size: 1rem; + font-weight: 600; + flex: 1; + min-width: 0; + } + + .send-all-notice { + border: 1px solid hsl(32.6 75.4% 55.1%); + background-color: hsl(32.6 75.4% 55.1% / 0.1); + } + + .send-all-notice h3 { + color: hsl(32.6 75.4% 55.1%); + font-size: 1rem; + font-weight: 600; + margin-bottom: 0.5rem; + } + + .send-all-notice p { + color: hsl(32.6 75.4% 55.1%); + font-size: 0.875rem; + line-height: 1.4; + margin: 0; + } + + /* Dark mode transaction styling */ + @media (prefers-color-scheme: dark) { + .transaction-details .detail-label { + color: var(--text-muted) !important; + } + + .transaction-details .detail-value, + .transaction-details .detail-value-amount { + color: var(--text-primary) !important; + } + + .send-all-notice { + background-color: hsl(32.6 75.4% 55.1% / 0.15) !important; + border-color: hsl(32.6 75.4% 55.1% / 0.3) !important; + } + } + + /* Responsive transaction details */ + @media (max-width: 640px) { + .transaction-details .detail-row { + flex-direction: column; + align-items: flex-start; + gap: 0.5rem; + } + + .transaction-details .detail-label { + min-width: auto; + font-size: 0.8125rem; + } + + .transaction-details .detail-value, + .transaction-details .detail-value-amount { + font-size: 0.875rem; + } + } " } } @@ -1648,8 +1985,13 @@ pub fn layout(title: &str, content: Markup) -> Markup { } div class="node-info" { div class="node-status" { - span class="status-indicator status-running" {} - span class="status-text" { "Running" } + @if is_running { + span class="status-indicator" {} + span class="status-text" { "Running" } + } @else { + span class="status-indicator status-inactive" {} + span class="status-text status-inactive" { "Inactive" } + } } h1 class="node-title" { "CDK LDK Node" } span class="node-subtitle" { "Cashu Mint & Lightning Network Node Management" } diff --git a/crates/cdk-ldk-node/static/images/bg-dark.jpg b/crates/cdk-ldk-node/static/images/bg-dark.jpg index d96f3453cb0c66eac3845a3aea6181befc7ffcca..6fa6745ac48cfadb80f1a66b0101a2039dbf83f2 100644 GIT binary patch literal 361525 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
    aNE+ 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    @B-S7`uRx%Rd%5uFex3ZMAbhV5H}Y$ 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

    }cK&ef0Kj~wu*)_IBOEY$nE^-c zcUBOD<}6nZR65e%Y;y|UJ2kwXsP}>Htwc+>6kQ0|@ zLGIu~d?uJy&ZELZV?BuCM^zrW2o`?iX(?*z+|J46PbApUOPFvGd}?UOzqIO3I!5O$ zgAoBdIpA#a=>K%4-W}|Y>$Tu)6Q4&X@OTp$9|XdQ)FHoPM8XUPO+^d9)iqpuj9JJfOUsOB*evv<en-B}#<;i_x!6Et9)nLv0)y*Iz2L&IfUDGKS zNb>L(c3T;FGXTzpLbyOceiP<|iteR`j}uqB^@&Y8w0bQAz#S#jI$_31sDkSM5xJZQ|bA41N6!qm<7bs&c z6I*ZiAMx%I1|TZLbO-sMGX2Obot^wEvSMLe-e&8sMA@j!3L#>@T?a=}H*Cvuls>IS zUm?&f^`YJPC9b2|A%;IKvR0fyTiPZaeCm)+IFqXss$ks|ACI@k6TQNk08-B3NSIA7 zEy9HV`j&my_IPjhr|9)~Z*w83P-67wg_BmD=HQeu3*Jews-zuqH}n}0{3}CS<`6cp zsPuBhK!As8wVxq34!N{Y);cg#*`e77QDWCEgIo}^cq+kD5@4bhw(C4Htv&L}W5n|} zcxIwcR~NimY)mbd2(;3Z_Mn}97$#W}V56cl$NAP=B}#kGrhzp00hMm}JIH$oO^L>T ze#$t$1HY>IHn=aV-|;&f1JH0IhdN|4r6AT=Q}<=A*(zVYo?3Xf;Y6(q?rAn&iI zxQ4MFHl4%tI7~2WJ1GeAX+Q$%vi|fTd{H%Aq(z-qLc427d2EB;=V5U2HjlX|nDG>Z z#_a^hhu zSIr;lKYS*wB2_Jn9A3)dkBz?hc`B?fK#{$de94---L@|*;X~U7gA{X2da0nHnGBu> z{q9!fkS4&?&lZSI=UgalXx|Km|4rp&qpePCd4YA#wn}BZ_edc8SX0v75 ziOz|R7Q(Q0j%nXA(d&Oi=G%Y2{1(F2&x%(=YNLLBpadtDc5ry?r5T{%0AJ9C4ERil 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 z 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

    %^u)!34DWhF7 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%0DvP1A9 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 Vz@Gx6Kv8o4&k;Z*dgqA2{{eTwr-c9j diff --git a/crates/cdk-ldk-node/static/images/bg.jpg b/crates/cdk-ldk-node/static/images/bg.jpg index 0c1651142e8d11ff0f785c8bb4cc39d175f9c737..e8e5a502a2592e398a331de3ae8a05e9e209e595 100644 GIT binary patch literal 147110 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 literal 620237 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%0A30h8(9(-A^Z^lVw+Mqt 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≫bdcGzo*lL%1+L?P3 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%0D^tZ_J=24YDel9U~w5v!hptApO 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 Date: Mon, 15 Sep 2025 20:50:08 +0200 Subject: [PATCH 152/321] chore: move `pay_request` logic into cdk lib (#1028) * pay request into cdk lib --- crates/cdk-cli/Cargo.toml | 2 +- .../src/sub_commands/create_request.rs | 263 +------- .../cdk-cli/src/sub_commands/pay_request.rs | 146 +--- crates/cdk/Cargo.toml | 8 +- crates/cdk/src/lib.rs | 3 + crates/cdk/src/wallet/mod.rs | 1 + crates/cdk/src/wallet/payment_request.rs | 626 ++++++++++++++++++ crates/cdk/src/wallet/streams/mod.rs | 2 + crates/cdk/src/wallet/streams/nostr.rs | 207 ++++++ 9 files changed, 880 insertions(+), 378 deletions(-) create mode 100644 crates/cdk/src/wallet/payment_request.rs create mode 100644 crates/cdk/src/wallet/streams/nostr.rs diff --git a/crates/cdk-cli/Cargo.toml b/crates/cdk-cli/Cargo.toml index a2c2e2dde..92eba990b 100644 --- a/crates/cdk-cli/Cargo.toml +++ b/crates/cdk-cli/Cargo.toml @@ -20,7 +20,7 @@ redb = ["dep:cdk-redb"] anyhow.workspace = true bip39.workspace = true bitcoin.workspace = true -cdk = { workspace = true, default-features = false, features = ["wallet", "auth", "bip353"]} +cdk = { workspace = true, default-features = false, features = ["wallet", "auth", "nostr", "bip353"]} cdk-redb = { workspace = true, features = ["wallet"], optional = true } cdk-sqlite = { workspace = true, features = ["wallet"] } clap.workspace = true diff --git a/crates/cdk-cli/src/sub_commands/create_request.rs b/crates/cdk-cli/src/sub_commands/create_request.rs index d92119e68..66b08534d 100644 --- a/crates/cdk-cli/src/sub_commands/create_request.rs +++ b/crates/cdk-cli/src/sub_commands/create_request.rs @@ -1,16 +1,6 @@ -use std::str::FromStr; - -use anyhow::{bail, Result}; -use bitcoin::hashes::sha256::Hash as Sha256Hash; -use cdk::nuts::nut01::PublicKey; -use cdk::nuts::nut11::{Conditions, SigFlag, SpendingConditions}; -use cdk::nuts::nut18::{Nut10SecretRequest, TransportType}; -use cdk::nuts::{CurrencyUnit, PaymentRequest, PaymentRequestPayload, Token, Transport}; -use cdk::wallet::{MultiMintWallet, ReceiveOptions}; +use anyhow::Result; +use cdk::wallet::{payment_request as pr, MultiMintWallet}; use clap::Args; -use nostr_sdk::nips::nip19::Nip19Profile; -use nostr_sdk::prelude::*; -use nostr_sdk::{Client as NostrClient, Filter, Keys, ToBech32}; #[derive(Args)] pub struct CreateRequestSubCommand { @@ -55,241 +45,30 @@ pub async fn create_request( multi_mint_wallet: &MultiMintWallet, sub_command_args: &CreateRequestSubCommand, ) -> Result<()> { - // Get available mints from the wallet - let mints: Vec = multi_mint_wallet - .get_balances(&CurrencyUnit::Sat) - .await? - .keys() - .cloned() - .collect(); - - // Process transport based on command line args - let transport_type = sub_command_args.transport.to_lowercase(); - let transports = match transport_type.as_str() { - "nostr" => { - let keys = Keys::generate(); - - // Use custom relays if provided, otherwise use defaults - let relays = if let Some(custom_relays) = &sub_command_args.nostr_relay { - if !custom_relays.is_empty() { - println!("Using custom Nostr relays: {custom_relays:?}"); - custom_relays.clone() - } else { - // Empty vector provided, fall back to defaults - vec![ - "wss://relay.nos.social".to_string(), - "wss://relay.damus.io".to_string(), - ] - } - } else { - // No relays provided, use defaults - vec![ - "wss://relay.nos.social".to_string(), - "wss://relay.damus.io".to_string(), - ] - }; - - let nprofile = Nip19Profile::new(keys.public_key, relays.clone())?; - - let nostr_transport = Transport { - _type: TransportType::Nostr, - target: nprofile.to_bech32()?, - tags: Some(vec![vec!["n".to_string(), "17".to_string()]]), - }; - - // We'll need the Nostr keys and relays later for listening - let transport_info = Some((keys, relays, nprofile.public_key)); - - (vec![nostr_transport], transport_info) - } - "http" => { - if let Some(url) = &sub_command_args.http_url { - let http_transport = Transport { - _type: TransportType::HttpPost, - target: url.clone(), - tags: None, - }; - - (vec![http_transport], None) - } else { - println!( - "Warning: HTTP transport selected but no URL provided, skipping transport" - ); - (vec![], None) - } - } - "none" => (vec![], None), - _ => { - println!("Warning: Unknown transport type '{transport_type}', defaulting to none"); - (vec![], None) - } - }; - - // Create spending conditions based on provided arguments - // Handle the following cases: - // 1. Only P2PK condition - // 2. Only HTLC condition with hash - // 3. Only HTLC condition with preimage - // 4. Both P2PK and HTLC conditions - - let spending_conditions = if let Some(pubkey_strings) = &sub_command_args.pubkey { - // Parse all pubkeys - let mut parsed_pubkeys = Vec::new(); - for pubkey_str in pubkey_strings { - match PublicKey::from_str(pubkey_str) { - Ok(pubkey) => parsed_pubkeys.push(pubkey), - Err(err) => { - println!("Error parsing pubkey {pubkey_str}: {err}"); - // Continue with other pubkeys - } - } - } - - if parsed_pubkeys.is_empty() { - println!("No valid pubkeys provided"); - None - } else { - // We have pubkeys for P2PK condition - let num_sigs = sub_command_args.num_sigs.min(parsed_pubkeys.len() as u64); - - // Check if we also have an HTLC condition - if let Some(hash_str) = &sub_command_args.hash { - // Create conditions with the pubkeys - let conditions = Conditions { - locktime: None, - pubkeys: Some(parsed_pubkeys), - refund_keys: None, - num_sigs: Some(num_sigs), - sig_flag: SigFlag::SigInputs, - num_sigs_refund: None, - }; - - // Try to parse the hash - match Sha256Hash::from_str(hash_str) { - Ok(hash) => { - // Create HTLC condition with P2PK in the conditions - Some(SpendingConditions::HTLCConditions { - data: hash, - conditions: Some(conditions), - }) - } - Err(err) => { - println!("Error parsing hash: {err}"); - // Fallback to just P2PK with multiple pubkeys - bail!("Error parsing hash"); - } - } - } else if let Some(preimage) = &sub_command_args.preimage { - // Create conditions with the pubkeys - let conditions = Conditions { - locktime: None, - pubkeys: Some(parsed_pubkeys), - refund_keys: None, - num_sigs: Some(num_sigs), - sig_flag: SigFlag::SigInputs, - num_sigs_refund: None, - }; - - // Create HTLC conditions with the hash and pubkeys in conditions - Some(SpendingConditions::new_htlc( - preimage.to_string(), - Some(conditions), - )?) - } else { - // Only P2PK condition with multiple pubkeys - Some(SpendingConditions::new_p2pk( - *parsed_pubkeys.first().unwrap(), - Some(Conditions { - locktime: None, - pubkeys: Some(parsed_pubkeys[1..].to_vec()), - refund_keys: None, - num_sigs: Some(num_sigs), - sig_flag: SigFlag::SigInputs, - num_sigs_refund: None, - }), - )) - } - } - } else if let Some(hash_str) = &sub_command_args.hash { - // Only HTLC condition with provided hash - match Sha256Hash::from_str(hash_str) { - Ok(hash) => Some(SpendingConditions::HTLCConditions { - data: hash, - conditions: None, - }), - Err(err) => { - println!("Error parsing hash: {err}"); - None - } - } - } else if let Some(preimage) = &sub_command_args.preimage { - // Only HTLC condition with provided preimage - // For HTLC, create the hash from the preimage and use it directly - Some(SpendingConditions::new_htlc(preimage.to_string(), None)?) - } else { - None - }; - - // Convert SpendingConditions to Nut10SecretRequest - let nut10 = spending_conditions.map(Nut10SecretRequest::from); - - // Extract the transports option from our match result - let (transports, nostr_info) = transports; - - let req = PaymentRequest { - payment_id: None, - amount: sub_command_args.amount.map(|a| a.into()), - unit: Some(CurrencyUnit::from_str(&sub_command_args.unit)?), - single_use: Some(true), - mints: Some(mints), + // Gather parameters for library call + let params = pr::CreateRequestParams { + amount: sub_command_args.amount, + unit: sub_command_args.unit.clone(), description: sub_command_args.description.clone(), - transports, - nut10, + pubkeys: sub_command_args.pubkey.clone(), + num_sigs: sub_command_args.num_sigs, + hash: sub_command_args.hash.clone(), + preimage: sub_command_args.preimage.clone(), + transport: sub_command_args.transport.to_lowercase(), + http_url: sub_command_args.http_url.clone(), + nostr_relays: sub_command_args.nostr_relay.clone(), }; - // Always print the request - println!("{req}"); + let (req, nostr_wait) = multi_mint_wallet.create_request(params).await?; - // Only listen for Nostr payment if Nostr transport was selected - if let Some((keys, relays, pubkey)) = nostr_info { - println!("Listening for payment via Nostr..."); + // Print the request to stdout + println!("{}", req); - let client = NostrClient::new(keys); - let filter = Filter::new().pubkey(pubkey); - - for relay in relays { - client.add_read_relay(relay).await?; - } - - client.connect().await; - client.subscribe(filter, None).await?; - - // Handle subscription notifications with `handle_notifications` method - client - .handle_notifications(|notification| async { - let mut exit = false; - if let RelayPoolNotification::Event { - subscription_id: _, - event, - .. - } = notification - { - let unwrapped = client.unwrap_gift_wrap(&event).await?; - let rumor = unwrapped.rumor; - let payload: PaymentRequestPayload = serde_json::from_str(&rumor.content)?; - let token = - Token::new(payload.mint, payload.proofs, payload.memo, payload.unit); - - let amount = multi_mint_wallet - .receive(&token.to_string(), ReceiveOptions::default()) - .await?; - - println!("Received {amount}"); - exit = true; - } - Ok(exit) // Set to true to exit from the loop - }) - .await?; + // If we set up Nostr transport, optionally wait for payment and receive it + if let Some(info) = nostr_wait { + println!("Listening for payment via Nostr..."); + let amount = multi_mint_wallet.wait_for_nostr_payment(info).await?; + println!("Received {}", amount); } Ok(()) diff --git a/crates/cdk-cli/src/sub_commands/pay_request.rs b/crates/cdk-cli/src/sub_commands/pay_request.rs index 6fd088a48..a5e820064 100644 --- a/crates/cdk-cli/src/sub_commands/pay_request.rs +++ b/crates/cdk-cli/src/sub_commands/pay_request.rs @@ -1,13 +1,10 @@ use std::io::{self, Write}; use anyhow::{anyhow, Result}; -use cdk::nuts::nut18::TransportType; -use cdk::nuts::{PaymentRequest, PaymentRequestPayload, Token}; -use cdk::wallet::{MultiMintWallet, SendOptions}; +use cdk::nuts::PaymentRequest; +use cdk::wallet::MultiMintWallet; +use cdk::Amount; use clap::Args; -use nostr_sdk::nips::nip19::Nip19Profile; -use nostr_sdk::{Client as NostrClient, EventBuilder, FromBech32, Keys}; -use reqwest::Client; #[derive(Args)] pub struct PayRequestSubCommand { @@ -22,7 +19,8 @@ pub async fn pay_request( let unit = &payment_request.unit; - let amount = match payment_request.amount { + // Determine amount: use from request or prompt user + let amount: Amount = match payment_request.amount { Some(amount) => amount, None => { println!("Enter the amount you would like to pay"); @@ -65,132 +63,12 @@ pub async fn pay_request( } } - let matching_wallet = matching_wallets.first().unwrap(); + let matching_wallet = matching_wallets + .first() + .ok_or_else(|| anyhow!("No wallet found that can pay this request"))?; - if payment_request.transports.is_empty() { - return Err(anyhow!("Cannot pay request without transport")); - } - let transports = payment_request.transports.clone(); - - // We prefer nostr transport if it is available to hide ip. - let transport = transports - .iter() - .find(|t| t._type == TransportType::Nostr) - .or_else(|| { - transports - .iter() - .find(|t| t._type == TransportType::HttpPost) - }); - - let prepared_send = matching_wallet - .prepare_send( - amount, - SendOptions { - include_fee: true, - ..Default::default() - }, - ) - .await?; - - let token = prepared_send.confirm(None).await?; - - // We need the keysets information to properly convert from token proof to proof - let keysets_info = match matching_wallet - .localstore - .get_mint_keysets(token.mint_url()?) - .await? - { - Some(keysets_info) => keysets_info, - None => matching_wallet.load_mint_keysets().await?, // Hit the keysets endpoint if we don't have the keysets for this Mint - }; - let proofs = token.proofs(&keysets_info)?; - - if let Some(transport) = transport { - let payload = PaymentRequestPayload { - id: payment_request.payment_id.clone(), - memo: None, - mint: matching_wallet.mint_url.clone(), - unit: matching_wallet.unit.clone(), - proofs, - }; - - match transport._type { - TransportType::Nostr => { - let keys = Keys::generate(); - let client = NostrClient::new(keys); - let nprofile = Nip19Profile::from_bech32(&transport.target)?; - - println!("{:?}", nprofile.relays); - - let rumor = EventBuilder::new( - nostr_sdk::Kind::from_u16(14), - serde_json::to_string(&payload)?, - ) - .build(nprofile.public_key); - let relays = nprofile.relays; - - for relay in relays.iter() { - client.add_write_relay(relay).await?; - } - - client.connect().await; - - let gift_wrap = client - .gift_wrap_to(relays, &nprofile.public_key, rumor, None) - .await?; - - println!( - "Published event {} succufully to {}", - gift_wrap.val, - gift_wrap - .success - .iter() - .map(|s| s.to_string()) - .collect::>() - .join(", ") - ); - - if !gift_wrap.failed.is_empty() { - println!( - "Could not publish to {:?}", - gift_wrap - .failed - .keys() - .map(|relay| relay.to_string()) - .collect::>() - .join(", ") - ); - } - } - - TransportType::HttpPost => { - let client = Client::new(); - - let res = client - .post(transport.target.clone()) - .json(&payload) - .send() - .await?; - - let status = res.status(); - if status.is_success() { - println!("Successfully posted payment"); - } else { - println!("{res:?}"); - println!("Error posting payment"); - } - } - } - } else { - // If no transport is available, print the token - let token = Token::new( - matching_wallet.mint_url.clone(), - proofs, - None, - matching_wallet.unit.clone(), - ); - println!("Token: {token}"); - } - - Ok(()) + matching_wallet + .pay_request(payment_request.clone(), Some(amount)) + .await + .map_err(|e| anyhow!(e.to_string())) } diff --git a/crates/cdk/Cargo.toml b/crates/cdk/Cargo.toml index 17ae3e76a..3c08e3c36 100644 --- a/crates/cdk/Cargo.toml +++ b/crates/cdk/Cargo.toml @@ -11,8 +11,9 @@ license.workspace = true [features] -default = ["mint", "wallet", "auth"] +default = ["mint", "wallet", "auth", "nostr"] wallet = ["dep:futures", "dep:reqwest", "cdk-common/wallet", "dep:rustls"] +nostr = ["wallet", "dep:nostr-sdk"] mint = ["dep:futures", "dep:reqwest", "cdk-common/mint", "cdk-signatory"] auth = ["dep:jsonwebtoken", "cdk-common/auth", "cdk-common/auth"] bip353 = ["dep:trust-dns-resolver"] @@ -44,6 +45,11 @@ utoipa = { workspace = true, optional = true } uuid.workspace = true jsonwebtoken = { workspace = true, optional = true } trust-dns-resolver = { version = "0.23.2", optional = true } +nostr-sdk = { optional = true, version = "0.43.0", default-features = false, features = [ + "nip04", + "nip44", + "nip59" +]} cdk-prometheus = {workspace = true, optional = true} web-time.workspace = true # -Z minimal-versions diff --git a/crates/cdk/src/lib.rs b/crates/cdk/src/lib.rs index babe1ecbc..e9938fe8a 100644 --- a/crates/cdk/src/lib.rs +++ b/crates/cdk/src/lib.rs @@ -68,3 +68,6 @@ pub type Result> = std::result::Result; /// Re-export futures::Stream #[cfg(any(feature = "wallet", feature = "mint"))] pub use futures::{Stream, StreamExt}; +/// Payment Request +#[cfg(feature = "wallet")] +pub use wallet::payment_request; diff --git a/crates/cdk/src/wallet/mod.rs b/crates/cdk/src/wallet/mod.rs index 3209be7db..8a80f92ba 100644 --- a/crates/cdk/src/wallet/mod.rs +++ b/crates/cdk/src/wallet/mod.rs @@ -39,6 +39,7 @@ mod keysets; mod melt; mod mint_connector; pub mod multi_mint_wallet; +pub mod payment_request; mod proofs; mod receive; mod send; diff --git a/crates/cdk/src/wallet/payment_request.rs b/crates/cdk/src/wallet/payment_request.rs new file mode 100644 index 000000000..f042872dc --- /dev/null +++ b/crates/cdk/src/wallet/payment_request.rs @@ -0,0 +1,626 @@ +//! Utilities for paying NUT-18 Payment Requests. +//! +//! This module prepares and broadcasts payments for Cashu NUT-18 payment requests using either +//! Nostr or HTTP transports when available. If no transport is present in the request, an error +//! is returned so callers can handle alternative delivery mechanisms explicitly. + +use std::str::FromStr; + +use anyhow::Result; +use bitcoin::hashes::sha256::Hash as Sha256Hash; +use cdk_common::{Amount, PaymentRequest, PaymentRequestPayload, TransportType}; +#[cfg(feature = "nostr")] +use nostr_sdk::nips::nip19::Nip19Profile; +#[cfg(feature = "nostr")] +use nostr_sdk::prelude::*; +#[cfg(feature = "nostr")] +use nostr_sdk::{Client as NostrClient, EventBuilder, FromBech32, Keys, ToBech32}; +use reqwest::Client; + +use crate::error::Error; +use crate::nuts::nut11::{Conditions, SigFlag, SpendingConditions}; +use crate::nuts::nut18::Nut10SecretRequest; +use crate::nuts::{CurrencyUnit, Transport}; +#[cfg(feature = "nostr")] +use crate::wallet::ReceiveOptions; +use crate::wallet::{MultiMintWallet, SendOptions}; +use crate::Wallet; + +impl Wallet { + /// Pay a NUT-18 PaymentRequest using a specific wallet. + /// + /// - If the request contains a Nostr or HttpPost transport, it will try those (preferring Nostr). + /// - If no usable transport is present, this returns an error. + /// - If the request has no amount, a `custom_amount` must be provided. + pub async fn pay_request( + &self, + payment_request: PaymentRequest, + custom_amount: Option, + ) -> Result<(), Error> { + let amount = match payment_request.amount { + Some(amount) => amount, + None => match custom_amount { + Some(a) => a, + None => return Err(Error::AmountUndefined), + }, + }; + + let transports = payment_request.transports.clone(); + + // Prefer Nostr to avoid revealing IP, fall back to HTTP POST. + let transport = transports + .iter() + .find(|t| t._type == TransportType::Nostr) + .or_else(|| { + transports + .iter() + .find(|t| t._type == TransportType::HttpPost) + }); + + let prepared_send = self + .prepare_send( + amount, + SendOptions { + include_fee: true, + ..Default::default() + }, + ) + .await?; + + let token = prepared_send.confirm(None).await?; + + // We need the keysets information to properly convert from token proof to proof + let keysets_info = match self.localstore.get_mint_keysets(token.mint_url()?).await? { + Some(keysets_info) => keysets_info, + None => self.load_mint_keysets().await?, + }; + let proofs = token.proofs(&keysets_info)?; + + if let Some(transport) = transport { + let payload = PaymentRequestPayload { + id: payment_request.payment_id.clone(), + memo: None, + mint: self.mint_url.clone(), + unit: self.unit.clone(), + proofs, + }; + + match transport._type { + TransportType::Nostr => { + #[cfg(feature = "nostr")] + { + let keys = Keys::generate(); + let client = NostrClient::new(keys); + let nprofile = Nip19Profile::from_bech32(&transport.target) + .map_err(|e| Error::Custom(format!("Invalid nprofile: {e}")))?; + + let rumor = EventBuilder::new( + nostr_sdk::Kind::from_u16(14), + serde_json::to_string(&payload) + .map_err(|e| Error::Custom(format!("Serialize payload: {e}")))?, + ) + .build(nprofile.public_key); + let relays = nprofile.relays; + + for relay in relays.iter() { + client + .add_write_relay(relay) + .await + .map_err(|e| Error::Custom(format!("Add relay {relay}: {e}")))?; + } + + client.connect().await; + + let gift_wrap = client + .gift_wrap_to(relays, &nprofile.public_key, rumor, None) + .await + .map_err(|e| Error::Custom(format!("Publish Nostr event: {e}")))?; + + println!( + "Published event {} successfully to {}", + gift_wrap.val, + gift_wrap + .success + .iter() + .map(|s| s.to_string()) + .collect::>() + .join(", ") + ); + + if !gift_wrap.failed.is_empty() { + println!( + "Could not publish to {}", + gift_wrap + .failed + .keys() + .map(|relay| relay.to_string()) + .collect::>() + .join(", ") + ); + } + + Ok(()) + } + #[cfg(not(feature = "nostr"))] + Err(Error::Custom( + "Nostr is not enabled in this build".to_string(), + )) + } + + TransportType::HttpPost => { + let client = Client::new(); + + let res = client + .post(transport.target.clone()) + .json(&payload) + .send() + .await + .map_err(|e| Error::HttpError(None, e.to_string()))?; + + let status = res.status(); + if status.is_success() { + println!("Successfully posted payment"); + Ok(()) + } else { + let body = res.text().await.unwrap_or_default(); + Err(Error::HttpError(Some(status.as_u16()), body)) + } + } + } + } else { + // If no transport is available, return an error instead of printing the token + Err(Error::Custom( + "No transport available in payment request".to_string(), + )) + } + } +} + +/// Parameters for creating a PaymentRequest +/// +/// This mirrors the CLI inputs and is used by `create_request` to build a +/// NUT-18 PaymentRequest. When `transport` is set to `nostr`, the function +/// also returns a `NostrWaitInfo` that can be passed to `wait_for_nostr_payment`. +#[derive(Debug, Clone)] +pub struct CreateRequestParams { + /// Optional amount to request (in the smallest unit for the chosen currency unit) + pub amount: Option, + /// Currency unit string (e.g., "sat") + pub unit: String, + /// Optional human-readable description for the request + pub description: Option, + /// Optional set of public keys for P2PK spending conditions (multisig supported) + pub pubkeys: Option>, // multiple P2PK pubkeys + /// Required number of signatures if `pubkeys` is provided (defaults typically to 1) + pub num_sigs: u64, // required signatures for P2PK + /// Optional HTLC hash condition (mutually exclusive with `preimage`) + pub hash: Option, // HTLC hash + /// Optional HTLC preimage (mutually exclusive with `hash`) + pub preimage: Option, // HTLC preimage + /// Transport type for the request: "nostr", "http", or "none" + pub transport: String, // "nostr", "http", or "none" + /// Target URL for HTTP transport (required if `transport == http`) + pub http_url: Option, // when transport == http + /// List of Nostr relay URLs to include in the nprofile (used if `transport == nostr`) + pub nostr_relays: Option>, // when transport == nostr +} + +/// Extra information needed to wait for an incoming Nostr payment +/// +/// Returned by `create_request` when the transport is `nostr`. Pass this to +/// `wait_for_nostr_payment` to connect, subscribe, and receive the incoming +/// payment on the specified relays. +#[cfg(feature = "nostr")] +#[derive(Debug, Clone)] +pub struct NostrWaitInfo { + /// Ephemeral keys used to connect to relays and unwrap the gift-wrapped event + pub keys: Keys, + /// Nostr relays to read from while waiting for the payment + pub relays: Vec, + /// The recipient public key to subscribe to for incoming events + pub pubkey: nostr_sdk::PublicKey, +} + +impl MultiMintWallet { + /// Derive enforceable NUT-10 spending conditions from high-level request params. + /// + /// Why: + /// - Centralizes translation of CLI/SDK inputs (P2PK multisig and HTLC variants) into + /// a single, canonical `SpendingConditions` shape so requests are consistent. + /// - Prevents ambiguous construction by capping `num_sigs` to the number of provided keys + /// and rejecting malformed hashes/inputs early. + /// - Encourages safe defaults by selecting `SigFlag::SigInputs` and composing conditions + /// that can be verified by recipients and mints. + /// + /// Behavior notes (rationale): + /// - If no P2PK or HTLC data is given, returns `Ok(None)` so callers emit a plain request + /// without additional constraints. + /// - With `pubkeys` only, constructs P2PK-style conditions where the first key is used as + /// the primary spend key and the remainder contribute to multisig according to `num_sigs`. + /// - With `hash` or `preimage`, constructs an HTLC condition, optionally embedding P2PK + /// conditions to require signatures in addition to the hash lock. + /// + /// Errors: + /// - Invalid SHA-256 `hash` strings or invalid HTLC/P2PK parameterizations surface as errors + /// from parsing and `SpendingConditions` constructors. + fn get_pr_spending_conditions( + &self, + params: &CreateRequestParams, + ) -> Result, Error> { + // Spending conditions + let spending_conditions: Option = + if let Some(pubkey_strings) = ¶ms.pubkeys { + // parse pubkeys + let mut parsed_pubkeys = Vec::new(); + for p in pubkey_strings { + if let Ok(pk) = crate::nuts::nut01::PublicKey::from_str(p) { + parsed_pubkeys.push(pk); + } + } + + if parsed_pubkeys.is_empty() { + None + } else { + let num_sigs = params.num_sigs.min(parsed_pubkeys.len() as u64); + + if let Some(hash_str) = ¶ms.hash { + let conditions = Conditions { + locktime: None, + pubkeys: Some(parsed_pubkeys), + refund_keys: None, + num_sigs: Some(num_sigs), + sig_flag: SigFlag::SigInputs, + num_sigs_refund: None, + }; + + match Sha256Hash::from_str(hash_str) { + Ok(hash) => Some(SpendingConditions::HTLCConditions { + data: hash, + conditions: Some(conditions), + }), + Err(err) => { + return Err(Error::Custom(format!("Error parsing hash: {err}"))) + } + } + } else if let Some(preimage) = ¶ms.preimage { + let conditions = Conditions { + locktime: None, + pubkeys: Some(parsed_pubkeys), + refund_keys: None, + num_sigs: Some(num_sigs), + sig_flag: SigFlag::SigInputs, + num_sigs_refund: None, + }; + + Some(SpendingConditions::new_htlc( + preimage.to_string(), + Some(conditions), + )?) + } else { + Some(SpendingConditions::new_p2pk( + *parsed_pubkeys.first().expect("not empty"), + Some(Conditions { + locktime: None, + pubkeys: Some(parsed_pubkeys[1..].to_vec()), + refund_keys: None, + num_sigs: Some(num_sigs), + sig_flag: SigFlag::SigInputs, + num_sigs_refund: None, + }), + )) + } + } + } else if let Some(hash_str) = ¶ms.hash { + match Sha256Hash::from_str(hash_str) { + Ok(hash) => Some(SpendingConditions::HTLCConditions { + data: hash, + conditions: None, + }), + Err(err) => return Err(Error::Custom(format!("Error parsing hash: {err}"))), + } + } else if let Some(preimage) = ¶ms.preimage { + Some(SpendingConditions::new_htlc(preimage.to_string(), None)?) + } else { + None + }; + Ok(spending_conditions) + } + + /// Create a NUT-18 PaymentRequest from high-level parameters. + /// + /// Why: + /// - Ensures the CLI and SDKs construct requests consistently using wallet context. + /// - Advertises available mints for the chosen unit so payers can select compatible proofs. + /// - Optionally embeds a transport; Nostr is preferred to reduce IP exposure for the payer. + /// + /// Behavior summary (focus on rationale rather than steps): + /// - Uses `unit` to discover mints with balances as a hint to senders (helps route payments without leaking more data than necessary). + /// - Translates P2PK/multisig and HTLC inputs (pubkeys/num_sigs/hash/preimage) into a NUT-10 secret request so the receiver can enforce spending constraints. + /// - For `transport == "nostr"`, generates ephemeral keys and an nprofile pointing at the chosen relays; returns `NostrWaitInfo` so callers can wait for the incoming payment without coupling construction and reception logic. + /// - For `transport == "http"`, attaches the provided endpoint; for `none` or unknown, omits transports to let the caller deliver out-of-band. + /// + /// Returns: + /// - `(PaymentRequest, Some(NostrWaitInfo))` when `transport == "nostr"`. + /// - `(PaymentRequest, None)` otherwise. + /// + /// Errors when: + /// - `unit` cannot be parsed, relay URLs are invalid, or P2PK/HTLC parameters are malformed. + /// + /// Notes: + /// - Sets `single_use = true` to discourage replays. + /// - Ephemeral Nostr keys are intentional; keep `NostrWaitInfo` only as long as needed for reception. + #[cfg(feature = "nostr")] + pub async fn create_request( + &self, + params: CreateRequestParams, + ) -> Result<(PaymentRequest, Option), Error> { + // Collect available mints for the selected unit + let mints = self + .get_balances(&CurrencyUnit::from_str(¶ms.unit)?) + .await? + .keys() + .cloned() + .collect::>(); + + // Transports + let transport_type = params.transport.to_lowercase(); + let (transports, nostr_info): (Vec, Option) = + match transport_type.as_str() { + "nostr" => { + let keys = Keys::generate(); + let relays = if let Some(custom_relays) = ¶ms.nostr_relays { + if !custom_relays.is_empty() { + custom_relays.clone() + } else { + return Err(Error::Custom("No relays provided".to_string())); + } + } else { + return Err(Error::Custom("No relays provided".to_string())); + }; + + // Parse relay URLs for nprofile + let relay_urls = relays + .iter() + .map(|r| RelayUrl::parse(r)) + .collect::, _>>() + .map_err(|e| Error::Custom(format!("Couldn't parse relays: {e}")))?; + + let nprofile = + nostr_sdk::nips::nip19::Nip19Profile::new(keys.public_key, relay_urls); + let nostr_transport = Transport { + _type: TransportType::Nostr, + target: nprofile.to_bech32().map_err(|e| { + Error::Custom(format!("Couldn't convert nprofile to bech32: {e}")) + })?, + tags: Some(vec![vec!["n".to_string(), "17".to_string()]]), + }; + + ( + vec![nostr_transport], + Some(NostrWaitInfo { + keys, + relays, + pubkey: nprofile.public_key, + }), + ) + } + "http" => { + if let Some(url) = ¶ms.http_url { + let http_transport = Transport { + _type: TransportType::HttpPost, + target: url.clone(), + tags: None, + }; + (vec![http_transport], None) + } else { + // No URL provided, skip transport + (vec![], None) + } + } + "none" => (vec![], None), + _ => (vec![], None), + }; + + let nut10 = self + .get_pr_spending_conditions(¶ms)? + .map(Nut10SecretRequest::from); + + let req = PaymentRequest { + payment_id: None, + amount: params.amount.map(Amount::from), + unit: Some(CurrencyUnit::from_str(¶ms.unit)?), + single_use: Some(true), + mints: Some(mints), + description: params.description, + transports, + nut10, + }; + + Ok((req, nostr_info)) + } + + /// Create a NUT-18 PaymentRequest from high-level parameters (Nostr disabled build). + /// + /// Why: + /// - Keep request construction consistent even when Nostr is not compiled in. + /// - Still advertise available mints for the unit so payers can route proofs correctly. + /// - Allow callers to attach an HTTP transport when out-of-band delivery is acceptable. + /// + /// Behavior notes: + /// - Rejects `transport == "nostr"` early so callers can surface a clear UX error. + /// - Encodes P2PK/multisig and HTLC constraints into a NUT-10 secret request for enforceable spending conditions. + /// + /// Returns the constructed PaymentRequest and sets `single_use = true` to discourage replay. + #[cfg(not(feature = "nostr"))] + pub async fn create_request( + &self, + params: CreateRequestParams, + ) -> Result { + // Collect available mints for the selected unit + let mints = self + .get_balances(&CurrencyUnit::from_str(¶ms.unit)?) + .await? + .keys() + .cloned() + .collect::>(); + + // Transports + let transport_type = params.transport.to_lowercase(); + let transports: Vec = match transport_type.as_str() { + "nostr" => { + return Err(Error::Custom( + "Nostr is not supported in this build".to_string(), + )) + } + "http" => { + if let Some(url) = ¶ms.http_url { + let http_transport = Transport { + _type: TransportType::HttpPost, + target: url.clone(), + tags: None, + }; + vec![http_transport] + } else { + // No URL provided, skip transport + vec![] + } + } + _ => vec![], + }; + + let nut10 = self + .get_pr_spending_conditions(¶ms)? + .map(Nut10SecretRequest::from); + + let req = PaymentRequest { + payment_id: None, + amount: params.amount.map(Amount::from), + unit: Some(CurrencyUnit::from_str(¶ms.unit)?), + single_use: Some(true), + mints: Some(mints), + description: params.description, + transports, + nut10, + }; + + Ok(req) + } + + /// Wait for a Nostr payment for the previously constructed PaymentRequest and receive it into the wallet. + #[cfg(all(feature = "nostr", not(target_arch = "wasm32")))] + pub async fn wait_for_nostr_payment(&self, info: NostrWaitInfo) -> Result { + use futures::StreamExt; + + use crate::wallet::streams::nostr::NostrPaymentEventStream; + + let NostrWaitInfo { + keys, + relays, + pubkey, + } = info; + + let mut stream = NostrPaymentEventStream::new(keys, relays, pubkey); + let cancel = stream.cancel_token(); + + // Optional: you may expose cancel to caller, or use a timeout here. + // tokio::spawn(async move { tokio::time::sleep(Duration::from_secs(120)).await; cancel.cancel(); }); + + while let Some(item) = stream.next().await { + match item { + Ok(payload) => { + let token = crate::nuts::Token::new( + payload.mint, + payload.proofs, + payload.memo, + payload.unit, + ); + + let amount = self + .receive(&token.to_string(), ReceiveOptions::default()) + .await?; + + // Stop after first successful receipt + cancel.cancel(); + return Ok(amount); + } + Err(_) => { + // Keep listening on parse errors; if you prefer fail-fast, return the error + continue; + } + } + } + + // If stream ended without receiving a payment, return zero. + Ok(Amount::ZERO) + } + + /// Wait for a Nostr payment for the previously constructed PaymentRequest and receive it into the wallet. + /// + /// wasm32 fallback: Streams are not available; we await the first matching notification and process it. + #[cfg(all(feature = "nostr", target_arch = "wasm32"))] + pub async fn wait_for_nostr_payment(&self, info: NostrWaitInfo) -> Result { + use nostr_sdk::prelude::*; + + let NostrWaitInfo { + keys, + relays, + pubkey, + } = info; + + let client = nostr_sdk::Client::new(keys); + + for r in &relays { + client + .add_read_relay(r.clone()) + .await + .map_err(|e| crate::error::Error::Custom(format!("Add relay {r}: {e}")))?; + } + + client.connect().await; + + // Subscribe to events addressed to `pubkey` + let filter = Filter::new().pubkey(pubkey); + client + .subscribe(filter, None) + .await + .map_err(|e| crate::error::Error::Custom(format!("Subscribe: {e}")))?; + + // Await notifications until we successfully parse a payment payload and receive it + let mut notifications = client.notifications(); + while let Ok(notification) = notifications.recv().await { + if let RelayPoolNotification::Event { event, .. } = notification { + match client.unwrap_gift_wrap(&event).await { + Ok(unwrapped) => { + let rumor = unwrapped.rumor; + match serde_json::from_str::(&rumor.content) { + Ok(payload) => { + let token = crate::nuts::Token::new( + payload.mint, + payload.proofs, + payload.memo, + payload.unit, + ); + + let amount = self + .receive(&token.to_string(), ReceiveOptions::default()) + .await?; + + return Ok(amount); + } + Err(_) => { + // Ignore malformed payloads and continue listening + continue; + } + } + } + Err(_) => { + // Ignore unwrap errors and continue listening + continue; + } + } + } + } + + Ok(Amount::ZERO) + } +} diff --git a/crates/cdk/src/wallet/streams/mod.rs b/crates/cdk/src/wallet/streams/mod.rs index fda0945e2..fb7cf80b8 100644 --- a/crates/cdk/src/wallet/streams/mod.rs +++ b/crates/cdk/src/wallet/streams/mod.rs @@ -120,3 +120,5 @@ impl Wallet { PaymentStream::new(self, events.into().into_subscription()) } } +#[cfg(all(feature = "nostr", not(target_arch = "wasm32")))] +pub mod nostr; diff --git a/crates/cdk/src/wallet/streams/nostr.rs b/crates/cdk/src/wallet/streams/nostr.rs new file mode 100644 index 000000000..45dc7d8d9 --- /dev/null +++ b/crates/cdk/src/wallet/streams/nostr.rs @@ -0,0 +1,207 @@ +//! Nostr payment event stream +//! +//! This stream exposes incoming Nostr payment messages as a standard `Stream>` +//! so callers can `select!`/`next().await`, cancel via `CancellationToken`, or combine with other streams. + +use std::task::Poll; + +use cdk_common::PaymentRequestPayload; +use futures::{FutureExt, Stream}; +use tokio::sync::mpsc; +use tokio_util::sync::CancellationToken; + +use crate::error::Error; +use crate::wallet::streams::RecvFuture; + +#[allow(clippy::type_complexity)] +pub struct NostrPaymentEventStream { + cancel: CancellationToken, + // Internal channel receiver for parsed payloads + rx: Option>>, + // A future that initializes the client + subscription and spawns the notification pump + init_fut: Option>>, + // Future to detect external cancellation + cancel_fut: Option>, + // Future awaiting the next item from `rx` + rx_future: Option< + RecvFuture< + 'static, + ( + Option>, + mpsc::Receiver>, + ), + >, + >, +} + +impl NostrPaymentEventStream { + pub fn new(keys: nostr_sdk::Keys, relays: Vec, pubkey: nostr_sdk::PublicKey) -> Self { + let cancel = CancellationToken::new(); + let (tx, rx) = mpsc::channel::>(32); + + let init_cancel = cancel.clone(); + let init_fut = Box::pin(async move { + let client = nostr_sdk::Client::new(keys); + + for r in &relays { + client + .add_read_relay(r.clone()) + .await + .map_err(|e| Error::Custom(format!("Add relay {r}: {e}")))?; + } + + client.connect().await; + + // Subscribe to events addressed to `pubkey` + let filter = nostr_sdk::Filter::new().pubkey(pubkey); + client + .subscribe(filter, None) + .await + .map_err(|e| Error::Custom(format!("Subscribe: {e}")))?; + + let client_for_handler = client.clone(); + // Pump notifications in a background task into the channel until cancelled + let _bg = tokio::spawn(async move { + // Use handle_notifications to avoid manually wiring broadcast receivers + let tx_err = tx.clone(); + let res = client + .handle_notifications(move |notification| { + let tx = tx.clone(); + let client = client_for_handler.clone(); + let cancel = init_cancel.clone(); + async move { + if cancel.is_cancelled() { + return Ok(true); + } + if let nostr_sdk::RelayPoolNotification::Event { event, .. } = + notification + { + match client.unwrap_gift_wrap(&event).await { + Ok(unwrapped) => { + let rumor = unwrapped.rumor; + match serde_json::from_str::( + &rumor.content, + ) { + Ok(payload) => { + // Best-effort send; if receiver closed, instruct exit + if tx.send(Ok(payload)).await.is_err() { + return Ok(true); + } + } + Err(e) => { + let _ = tx + .send(Err(Error::Custom(format!( + "Invalid payload JSON: {e}" + )))) + .await; + } + } + } + Err(e) => { + let _ = tx + .send(Err(Error::Custom(format!( + "Unwrap gift wrap failed: {e}" + )))) + .await; + } + } + } + Ok(false) + } + }) + .await; + + if let Err(e) = res { + let _ = tx_err + .send(Err(Error::Custom(format!( + "Notification handler error: {e}" + )))) + .await; + } + }); + + Ok(()) + }); + + Self { + cancel, + rx: Some(rx), + init_fut: Some(init_fut), + cancel_fut: None, + rx_future: None, + } + } + + pub fn cancel_token(&self) -> CancellationToken { + self.cancel.clone() + } +} + +impl Stream for NostrPaymentEventStream { + type Item = Result; + + fn poll_next( + self: std::pin::Pin<&mut Self>, + cx: &mut std::task::Context<'_>, + ) -> Poll> { + let this = self.get_mut(); + + // Check external cancellation + if this.cancel_fut.is_none() { + let cancel = this.cancel.clone(); + this.cancel_fut = Some(Box::pin(async move { cancel.cancelled().await })); + } + if let Some(mut fut) = this.cancel_fut.take() { + if fut.poll_unpin(cx).is_ready() { + // Drop receiver to end the stream + this.rx.take(); + return Poll::Ready(None); + } + this.cancel_fut = Some(fut); + } + + // Drive initialization + if let Some(mut init) = this.init_fut.take() { + match init.poll_unpin(cx) { + Poll::Pending => { + this.init_fut = Some(init); + return Poll::Pending; + } + Poll::Ready(Err(e)) => { + return Poll::Ready(Some(Err(e))); + } + Poll::Ready(Ok(())) => { + // fallthrough + } + } + } + + // Drive next item from the internal channel + if this.rx.is_none() { + return Poll::Ready(None); + } + + if this.rx_future.is_none() { + let mut rx = this.rx.take().expect("receiver"); + this.rx_future = Some(Box::pin(async move { + let item = rx.recv().await; + (item, rx) + })); + } + + let mut fut = this.rx_future.take().ok_or(Error::Internal)?; + match fut.poll_unpin(cx) { + Poll::Pending => { + this.rx_future = Some(fut); + Poll::Pending + } + Poll::Ready((item, rx)) => { + this.rx = Some(rx); + match item { + None => Poll::Ready(None), + Some(item) => Poll::Ready(Some(item)), + } + } + } + } +} From 1cc4783198112fa9445e260f893e97000020111d Mon Sep 17 00:00:00 2001 From: C Date: Mon, 15 Sep 2025 19:19:48 -0300 Subject: [PATCH 153/321] Fixed bug with postgres reconnection in the connection pool (#1078) --- crates/cdk-postgres/src/lib.rs | 26 +++++++++++--------------- 1 file changed, 11 insertions(+), 15 deletions(-) diff --git a/crates/cdk-postgres/src/lib.rs b/crates/cdk-postgres/src/lib.rs index 92149d74b..d0a60c426 100644 --- a/crates/cdk-postgres/src/lib.rs +++ b/crates/cdk-postgres/src/lib.rs @@ -142,14 +142,10 @@ impl DatabasePool for PgConnectionPool { fn new_resource( config: &Self::Config, - still_valid: Arc, + stale: Arc, timeout: Duration, ) -> Result> { - Ok(PostgresConnection::new( - config.to_owned(), - timeout, - still_valid, - )) + Ok(PostgresConnection::new(config.to_owned(), timeout, stale)) } } @@ -164,7 +160,7 @@ pub struct PostgresConnection { impl PostgresConnection { /// Creates a new instance - pub fn new(config: PgConfig, timeout: Duration, still_valid: Arc) -> Self { + pub fn new(config: PgConfig, timeout: Duration, stale: Arc) -> Self { let failed = Arc::new(Mutex::new(None)); let result = Arc::new(OnceLock::new()); let notify = Arc::new(Notify::new()); @@ -191,22 +187,22 @@ impl PostgresConnection { Err(err) => { *error_clone.lock().await = Some(cdk_common::database::Error::Database(Box::new(err))); - still_valid.store(false, std::sync::atomic::Ordering::Release); + stale.store(false, std::sync::atomic::Ordering::Release); notify_clone.notify_waiters(); return; } }; - let still_valid_for_spawn = still_valid.clone(); + let stale_for_spawn = stale.clone(); tokio::spawn(async move { let _ = connection.await; - still_valid_for_spawn.store(false, std::sync::atomic::Ordering::Release); + stale_for_spawn.store(true, std::sync::atomic::Ordering::Release); }); if let Some(schema) = config.schema.as_ref() { if let Err(err) = select_schema(&client, schema).await { *error_clone.lock().await = Some(err); - still_valid.store(false, std::sync::atomic::Ordering::Release); + stale.store(false, std::sync::atomic::Ordering::Release); notify_clone.notify_waiters(); return; } @@ -221,22 +217,22 @@ impl PostgresConnection { Err(err) => { *error_clone.lock().await = Some(cdk_common::database::Error::Database(Box::new(err))); - still_valid.store(false, std::sync::atomic::Ordering::Release); + stale.store(false, std::sync::atomic::Ordering::Release); notify_clone.notify_waiters(); return; } }; - let still_valid_for_spawn = still_valid.clone(); + let stale_for_spawn = stale.clone(); tokio::spawn(async move { let _ = connection.await; - still_valid_for_spawn.store(false, std::sync::atomic::Ordering::Release); + stale_for_spawn.store(true, std::sync::atomic::Ordering::Release); }); if let Some(schema) = config.schema.as_ref() { if let Err(err) = select_schema(&client, schema).await { *error_clone.lock().await = Some(err); - still_valid.store(false, std::sync::atomic::Ordering::Release); + stale.store(true, std::sync::atomic::Ordering::Release); notify_clone.notify_waiters(); return; } From c3c8e8716493b0aaf65c2844d18245f91788a493 Mon Sep 17 00:00:00 2001 From: C Date: Tue, 16 Sep 2025 05:01:34 -0300 Subject: [PATCH 154/321] Add `resolve_dns_txt` to HttpTransport and MintConnector (#1068) * Add `resolve_dns_txt` to HttpTransport and MintConnector Fixes #1036 * Use `hickory_resolver` to resolve DNS entries * Remote default implementation of methods * Fix build for wasm --- crates/cdk-ffi/src/wallet.rs | 2 +- crates/cdk-integration-tests/Cargo.toml | 3 +- .../src/init_pure_tests.rs | 4 ++ crates/cdk/Cargo.toml | 6 +-- .../mint-token-bolt12-with-custom-http.rs | 5 +++ crates/cdk/src/bip353.rs | 41 ++++++------------- crates/cdk/src/lib.rs | 2 +- crates/cdk/src/wallet/melt/melt_bip353.rs | 6 +-- crates/cdk/src/wallet/melt/mod.rs | 2 +- .../src/wallet/mint_connector/http_client.rs | 6 +++ crates/cdk/src/wallet/mint_connector/mod.rs | 4 ++ .../src/wallet/mint_connector/transport.rs | 34 +++++++++++++++ 12 files changed, 76 insertions(+), 39 deletions(-) diff --git a/crates/cdk-ffi/src/wallet.rs b/crates/cdk-ffi/src/wallet.rs index 73fe76ece..00ee2bf9e 100644 --- a/crates/cdk-ffi/src/wallet.rs +++ b/crates/cdk-ffi/src/wallet.rs @@ -404,7 +404,7 @@ impl Wallet { } /// BIP353 methods for Wallet -#[cfg(feature = "bip353")] +#[cfg(all(feature = "bip353", not(target_arch = "wasm32")))] #[uniffi::export(async_runtime = "tokio")] impl Wallet { /// Get a quote for a BIP353 melt diff --git a/crates/cdk-integration-tests/Cargo.toml b/crates/cdk-integration-tests/Cargo.toml index 30f314525..cc7b082e5 100644 --- a/crates/cdk-integration-tests/Cargo.toml +++ b/crates/cdk-integration-tests/Cargo.toml @@ -20,7 +20,7 @@ rand.workspace = true bip39 = { workspace = true, features = ["rand"] } anyhow.workspace = true cashu = { workspace = true, features = ["mint", "wallet"] } -cdk = { workspace = true, features = ["mint", "wallet", "auth"] } +cdk = { workspace = true, features = ["mint", "wallet", "auth", "bip353"] } cdk-cln = { workspace = true } cdk-lnd = { workspace = true } cdk-ldk-node = { workspace = true } @@ -63,7 +63,6 @@ uuid = { workspace = true, features = ["js"] } [dev-dependencies] bip39 = { workspace = true, features = ["rand"] } anyhow.workspace = true -cdk = { workspace = true, features = ["mint", "wallet"] } cdk-axum = { workspace = true } cdk-fake-wallet = { workspace = true } tower-http = { workspace = true, features = ["cors"] } diff --git a/crates/cdk-integration-tests/src/init_pure_tests.rs b/crates/cdk-integration-tests/src/init_pure_tests.rs index 9b46b8049..c9d5db3a9 100644 --- a/crates/cdk-integration-tests/src/init_pure_tests.rs +++ b/crates/cdk-integration-tests/src/init_pure_tests.rs @@ -55,6 +55,10 @@ impl Debug for DirectMintConnection { /// Convert the requests and responses between the [String] and [Uuid] variants as necessary. #[async_trait] impl MintConnector for DirectMintConnection { + async fn resolve_dns_txt(&self, _domain: &str) -> Result, Error> { + panic!("Not implemented"); + } + async fn get_mint_keys(&self) -> Result, Error> { Ok(self.mint.pubkeys().keysets) } diff --git a/crates/cdk/Cargo.toml b/crates/cdk/Cargo.toml index 3c08e3c36..141e014cd 100644 --- a/crates/cdk/Cargo.toml +++ b/crates/cdk/Cargo.toml @@ -11,12 +11,12 @@ license.workspace = true [features] -default = ["mint", "wallet", "auth", "nostr"] +default = ["mint", "wallet", "auth", "nostr", "bip353"] wallet = ["dep:futures", "dep:reqwest", "cdk-common/wallet", "dep:rustls"] nostr = ["wallet", "dep:nostr-sdk"] mint = ["dep:futures", "dep:reqwest", "cdk-common/mint", "cdk-signatory"] auth = ["dep:jsonwebtoken", "cdk-common/auth", "cdk-common/auth"] -bip353 = ["dep:trust-dns-resolver"] +bip353 = ["dep:hickory-resolver"] # We do not commit to a MSRV with swagger enabled swagger = ["mint", "dep:utoipa", "cdk-common/swagger"] bench = [] @@ -44,7 +44,6 @@ url.workspace = true utoipa = { workspace = true, optional = true } uuid.workspace = true jsonwebtoken = { workspace = true, optional = true } -trust-dns-resolver = { version = "0.23.2", optional = true } nostr-sdk = { optional = true, version = "0.43.0", default-features = false, features = [ "nip04", "nip44", @@ -60,6 +59,7 @@ zeroize = "1" tokio-util.workspace = true [target.'cfg(not(target_arch = "wasm32"))'.dependencies] +hickory-resolver = { version = "0.25.2", optional = true, features = ["dnssec-ring"] } tokio = { workspace = true, features = [ "rt-multi-thread", "time", diff --git a/crates/cdk/examples/mint-token-bolt12-with-custom-http.rs b/crates/cdk/examples/mint-token-bolt12-with-custom-http.rs index 31d16b30e..03f215a0a 100644 --- a/crates/cdk/examples/mint-token-bolt12-with-custom-http.rs +++ b/crates/cdk/examples/mint-token-bolt12-with-custom-http.rs @@ -40,6 +40,11 @@ impl Default for CustomHttp { #[cfg_attr(target_arch = "wasm32", async_trait::async_trait(?Send))] #[cfg_attr(not(target_arch = "wasm32"), async_trait::async_trait)] impl HttpTransport for CustomHttp { + #[cfg(all(feature = "bip353", not(target_arch = "wasm32")))] + async fn resolve_dns_txt(&self, _domain: &str) -> Result, Error> { + panic!("Not supported"); + } + fn with_proxy( &mut self, _proxy: Url, diff --git a/crates/cdk/src/bip353.rs b/crates/cdk/src/bip353.rs index 15b2c6c77..5b3ed8a24 100644 --- a/crates/cdk/src/bip353.rs +++ b/crates/cdk/src/bip353.rs @@ -6,10 +6,11 @@ use std::collections::HashMap; use std::str::FromStr; +use std::sync::Arc; use anyhow::{bail, Result}; -use trust_dns_resolver::config::{ResolverConfig, ResolverOpts}; -use trust_dns_resolver::TokioAsyncResolver; + +use crate::wallet::MintConnector; /// BIP-353 human-readable Bitcoin address #[derive(Debug, Clone, PartialEq, Eq, Hash)] @@ -37,35 +38,19 @@ impl Bip353Address { /// - No Bitcoin URI is found /// - Multiple Bitcoin URIs are found (BIP-353 requires exactly one) /// - The URI format is invalid - pub(crate) async fn resolve(self) -> Result { + pub(crate) async fn resolve( + self, + client: &Arc, + ) -> Result { // Construct DNS name according to BIP-353 let dns_name = format!("{}.user._bitcoin-payment.{}", self.user, self.domain); - // Create a new resolver with DNSSEC validation - let mut opts = ResolverOpts::default(); - opts.validate = true; // Enable DNSSEC validation - - let resolver = TokioAsyncResolver::tokio(ResolverConfig::default(), opts); - - // Query TXT records - with opts.validate=true, this will fail if DNSSEC validation fails - let response = resolver.txt_lookup(&dns_name).await?; - - // Extract and concatenate TXT record strings - let mut bitcoin_uris = Vec::new(); - - for txt in response.iter() { - let txt_data: Vec = txt - .txt_data() - .iter() - .map(|bytes| String::from_utf8_lossy(bytes).into_owned()) - .collect(); - - let concatenated = txt_data.join(""); - - if concatenated.to_lowercase().starts_with("bitcoin:") { - bitcoin_uris.push(concatenated); - } - } + let bitcoin_uris = client + .resolve_dns_txt(&dns_name) + .await? + .into_iter() + .filter(|txt_data| txt_data.to_lowercase().starts_with("bitcoin:")) + .collect::>(); // BIP-353 requires exactly one Bitcoin URI match bitcoin_uris.len() { diff --git a/crates/cdk/src/lib.rs b/crates/cdk/src/lib.rs index e9938fe8a..c1e89c7e2 100644 --- a/crates/cdk/src/lib.rs +++ b/crates/cdk/src/lib.rs @@ -22,7 +22,7 @@ pub mod mint; #[cfg(feature = "wallet")] pub mod wallet; -#[cfg(feature = "bip353")] +#[cfg(all(feature = "bip353", not(target_arch = "wasm32")))] mod bip353; #[cfg(all(any(feature = "wallet", feature = "mint"), feature = "auth"))] diff --git a/crates/cdk/src/wallet/melt/melt_bip353.rs b/crates/cdk/src/wallet/melt/melt_bip353.rs index b1b5c401b..adec11605 100644 --- a/crates/cdk/src/wallet/melt/melt_bip353.rs +++ b/crates/cdk/src/wallet/melt/melt_bip353.rs @@ -7,7 +7,7 @@ use std::str::FromStr; use cdk_common::wallet::MeltQuote; use tracing::instrument; -#[cfg(feature = "bip353")] +#[cfg(all(feature = "bip353", not(target_arch = "wasm32")))] use crate::bip353::{Bip353Address, PaymentType}; use crate::nuts::MeltOptions; use crate::{Amount, Error, Wallet}; @@ -47,7 +47,7 @@ impl Wallet { /// # Ok(()) /// # } /// ``` - #[cfg(feature = "bip353")] + #[cfg(all(feature = "bip353", not(target_arch = "wasm32")))] #[instrument(skip(self, amount_msat), fields(address = %bip353_address))] pub async fn melt_bip353_quote( &self, @@ -66,7 +66,7 @@ impl Wallet { let address_string = address.to_string(); // Resolve the address to get payment instructions - let payment_instructions = address.resolve().await.map_err(|e| { + let payment_instructions = address.resolve(&self.client).await.map_err(|e| { tracing::error!( "Failed to resolve BIP353 address '{}': {}", address_string, diff --git a/crates/cdk/src/wallet/melt/mod.rs b/crates/cdk/src/wallet/melt/mod.rs index c923e0c6e..24db4629b 100644 --- a/crates/cdk/src/wallet/melt/mod.rs +++ b/crates/cdk/src/wallet/melt/mod.rs @@ -7,7 +7,7 @@ use tracing::instrument; use crate::Wallet; -#[cfg(feature = "bip353")] +#[cfg(all(feature = "bip353", not(target_arch = "wasm32")))] mod melt_bip353; mod melt_bolt11; mod melt_bolt12; diff --git a/crates/cdk/src/wallet/mint_connector/http_client.rs b/crates/cdk/src/wallet/mint_connector/http_client.rs index 9a71cbf20..c2f29bc96 100644 --- a/crates/cdk/src/wallet/mint_connector/http_client.rs +++ b/crates/cdk/src/wallet/mint_connector/http_client.rs @@ -187,6 +187,12 @@ impl MintConnector for HttpClient where T: Transport + Send + Sync + 'static, { + #[cfg(all(feature = "bip353", not(target_arch = "wasm32")))] + #[instrument(skip(self), fields(mint_url = %self.mint_url))] + async fn resolve_dns_txt(&self, domain: &str) -> Result, Error> { + self.transport.resolve_dns_txt(domain).await + } + /// Get Active Mint Keys [NUT-01] #[instrument(skip(self), fields(mint_url = %self.mint_url))] async fn get_mint_keys(&self) -> Result, Error> { diff --git a/crates/cdk/src/wallet/mint_connector/mod.rs b/crates/cdk/src/wallet/mint_connector/mod.rs index 8675d2941..3b9a73ea3 100644 --- a/crates/cdk/src/wallet/mint_connector/mod.rs +++ b/crates/cdk/src/wallet/mint_connector/mod.rs @@ -28,6 +28,10 @@ pub type HttpClient = http_client::HttpClient; #[cfg_attr(target_arch = "wasm32", async_trait(?Send))] #[cfg_attr(not(target_arch = "wasm32"), async_trait)] pub trait MintConnector: Debug { + #[cfg(all(feature = "bip353", not(target_arch = "wasm32")))] + /// Resolve the DNS record getting the TXT value + async fn resolve_dns_txt(&self, _domain: &str) -> Result, Error>; + /// Get Active Mint Keys [NUT-01] async fn get_mint_keys(&self) -> Result, Error>; /// Get Keyset Keys [NUT-01] diff --git a/crates/cdk/src/wallet/mint_connector/transport.rs b/crates/cdk/src/wallet/mint_connector/transport.rs index 5a4812902..112ebc245 100644 --- a/crates/cdk/src/wallet/mint_connector/transport.rs +++ b/crates/cdk/src/wallet/mint_connector/transport.rs @@ -2,6 +2,12 @@ use std::fmt::Debug; use cdk_common::AuthToken; +#[cfg(all(feature = "bip353", not(target_arch = "wasm32")))] +use hickory_resolver::config::ResolverConfig; +#[cfg(all(feature = "bip353", not(target_arch = "wasm32")))] +use hickory_resolver::name_server::TokioConnectionProvider; +#[cfg(all(feature = "bip353", not(target_arch = "wasm32")))] +use hickory_resolver::Resolver; use reqwest::Client; use serde::de::DeserializeOwned; use serde::Serialize; @@ -14,6 +20,10 @@ use crate::error::ErrorResponse; #[cfg_attr(target_arch = "wasm32", async_trait::async_trait(?Send))] #[cfg_attr(not(target_arch = "wasm32"), async_trait::async_trait)] pub trait Transport: Default + Send + Sync + Debug + Clone { + #[cfg(all(feature = "bip353", not(target_arch = "wasm32")))] + /// DNS resolver to get a TXT record from a domain name + async fn resolve_dns_txt(&self, _domain: &str) -> Result, Error>; + /// Make the transport to use a given proxy fn with_proxy( &mut self, @@ -102,6 +112,30 @@ impl Transport for Async { Ok(()) } + /// DNS resolver to get a TXT record from a domain name + #[cfg(all(feature = "bip353", not(target_arch = "wasm32")))] + async fn resolve_dns_txt(&self, domain: &str) -> Result, Error> { + let resolver = Resolver::builder_with_config( + ResolverConfig::default(), + TokioConnectionProvider::default(), + ) + .build(); + + Ok(resolver + .txt_lookup(domain) + .await + .map_err(|e| Error::Custom(e.to_string()))? + .into_iter() + .map(|txt| { + txt.txt_data() + .iter() + .map(|bytes| String::from_utf8_lossy(bytes).into_owned()) + .collect::>() + .join("") + }) + .collect::>()) + } + async fn http_get(&self, url: Url, auth: Option) -> Result where R: DeserializeOwned, From 5650050f324da7ceef4a7c70fb6097fa9278bc79 Mon Sep 17 00:00:00 2001 From: gudnuf <108303703+gudnuf@users.noreply.github.com> Date: Tue, 16 Sep 2025 01:02:31 -0700 Subject: [PATCH 155/321] fix: make http wallet subscriptions wasm compatible (#1062) --- crates/cdk/Cargo.toml | 3 + crates/cdk/src/wallet/subscription/http.rs | 187 ++++++++++++++------- crates/cdk/src/wallet/subscription/mod.rs | 31 ++-- 3 files changed, 144 insertions(+), 77 deletions(-) diff --git a/crates/cdk/Cargo.toml b/crates/cdk/Cargo.toml index 141e014cd..b2b4cfa0c 100644 --- a/crates/cdk/Cargo.toml +++ b/crates/cdk/Cargo.toml @@ -81,6 +81,9 @@ cdk-signatory = { workspace = true, default-features = false } getrandom = { version = "0.2", features = ["js"] } ring = { version = "0.17.14", features = ["wasm32_unknown_unknown_js"] } uuid = { workspace = true, features = ["js"] } +wasm-bindgen = "0.2" +wasm-bindgen-futures = "0.4" +gloo-timers = { version = "0.3", features = ["futures"] } [[example]] name = "mint-token" diff --git a/crates/cdk/src/wallet/subscription/http.rs b/crates/cdk/src/wallet/subscription/http.rs index 9933465cc..bbf2021c8 100644 --- a/crates/cdk/src/wallet/subscription/http.rs +++ b/crates/cdk/src/wallet/subscription/http.rs @@ -3,6 +3,7 @@ use std::sync::Arc; use cdk_common::MintQuoteBolt12Response; use tokio::sync::{mpsc, RwLock}; +#[cfg(not(target_arch = "wasm32"))] use tokio::time; use web_time::Duration; @@ -84,6 +85,7 @@ async fn convert_subscription( Some(()) } +#[cfg(not(target_arch = "wasm32"))] #[inline] pub async fn http_main>( initial_state: S, @@ -94,7 +96,7 @@ pub async fn http_main>( _wallet: Arc, ) { let mut interval = time::interval(Duration::from_secs(2)); - let mut subscribed_to = HashMap::, _, AnyState)>::new(); + let mut subscribed_to = SubscribedTo::new(); for sub_id in initial_state { convert_subscription(sub_id, &subscriptions, &mut subscribed_to).await; @@ -103,76 +105,133 @@ pub async fn http_main>( loop { tokio::select! { _ = interval.tick() => { - for (url, (sender, _, last_state)) in subscribed_to.iter_mut() { - tracing::debug!("Polling: {:?}", url); - match url { - UrlType::MintBolt12(id) => { - let response = http_client.get_mint_quote_bolt12_status(id).await; - if let Ok(response) = response { - if *last_state == AnyState::MintBolt12QuoteState(response.clone()) { - continue; - } - *last_state = AnyState::MintBolt12QuoteState(response.clone()); - if let Err(err) = sender.try_send(NotificationPayload::MintQuoteBolt12Response(response)) { - tracing::error!("Error sending mint quote response: {:?}", err); - } - } - }, - UrlType::Mint(id) => { + poll_subscriptions(&http_client, &mut subscribed_to).await; + } + Some(subid) = new_subscription_recv.recv() => { + convert_subscription(subid, &subscriptions, &mut subscribed_to).await; + } + Some(id) = on_drop.recv() => { + subscribed_to.retain(|_, (_, sub_id, _)| *sub_id != id); + } + } + } +} - let response = http_client.get_mint_quote_status(id).await; - if let Ok(response) = response { - if *last_state == AnyState::MintQuoteState(response.state) { - continue; - } - *last_state = AnyState::MintQuoteState(response.state); - if let Err(err) = sender.try_send(NotificationPayload::MintQuoteBolt11Response(response)) { - tracing::error!("Error sending mint quote response: {:?}", err); - } - } - } - UrlType::Melt(id) => { +#[cfg(target_arch = "wasm32")] +#[inline] +pub async fn http_main>( + initial_state: S, + http_client: Arc, + subscriptions: Arc>>, + mut new_subscription_recv: mpsc::Receiver, + mut on_drop: mpsc::Receiver, + _wallet: Arc, +) { + let mut subscribed_to = SubscribedTo::new(); - let response = http_client.get_melt_quote_status(id).await; - if let Ok(response) = response { - if *last_state == AnyState::MeltQuoteState(response.state) { - continue; - } - *last_state = AnyState::MeltQuoteState(response.state); - if let Err(err) = sender.try_send(NotificationPayload::MeltQuoteBolt11Response(response)) { - tracing::error!("Error sending melt quote response: {:?}", err); - } - } - } - UrlType::PublicKey(id) => { - let responses = http_client.post_check_state(CheckStateRequest { - ys: vec![*id], - } - ).await; - if let Ok(mut responses) = responses { - let response = if let Some(state) = responses.states.pop() { - state - } else { - continue; - }; + for sub_id in initial_state { + convert_subscription(sub_id, &subscriptions, &mut subscribed_to).await; + } - if *last_state == AnyState::PublicKey(response.state) { - continue; - } - *last_state = AnyState::PublicKey(response.state); - if let Err(err) = sender.try_send(NotificationPayload::ProofState(response)) { - tracing::error!("Error sending proof state response: {:?}", err); - } - } - } + loop { + tokio::select! { + _ = gloo_timers::future::sleep(Duration::from_secs(2)) => { + poll_subscriptions(&http_client, &mut subscribed_to).await; + } + subid = new_subscription_recv.recv() => { + match subid { + Some(subid) => { + convert_subscription(subid, &subscriptions, &mut subscribed_to).await; + } + None => { + // New subscription channel closed - SubscriptionClient was dropped, terminate worker + break; } } } - Some(subid) = new_subscription_recv.recv() => { - convert_subscription(subid, &subscriptions, &mut subscribed_to).await; + id = on_drop.recv() => { + match id { + Some(id) => { + subscribed_to.retain(|_, (_, sub_id, _)| *sub_id != id); + } + None => { + // Drop notification channel closed - SubscriptionClient was dropped, terminate worker + break; + } + } } - Some(id) = on_drop.recv() => { - subscribed_to.retain(|_, (_, sub_id, _)| *sub_id != id); + } + } +} + +async fn poll_subscriptions( + http_client: &Arc, + subscribed_to: &mut SubscribedTo, +) { + for (url, (sender, _, last_state)) in subscribed_to.iter_mut() { + tracing::debug!("Polling: {:?}", url); + match url { + UrlType::MintBolt12(id) => { + let response = http_client.get_mint_quote_bolt12_status(id).await; + if let Ok(response) = response { + if *last_state == AnyState::MintBolt12QuoteState(response.clone()) { + continue; + } + *last_state = AnyState::MintBolt12QuoteState(response.clone()); + if let Err(err) = + sender.try_send(NotificationPayload::MintQuoteBolt12Response(response)) + { + tracing::error!("Error sending mint quote response: {:?}", err); + } + } + } + UrlType::Mint(id) => { + let response = http_client.get_mint_quote_status(id).await; + if let Ok(response) = response { + if *last_state == AnyState::MintQuoteState(response.state) { + continue; + } + *last_state = AnyState::MintQuoteState(response.state); + if let Err(err) = + sender.try_send(NotificationPayload::MintQuoteBolt11Response(response)) + { + tracing::error!("Error sending mint quote response: {:?}", err); + } + } + } + UrlType::Melt(id) => { + let response = http_client.get_melt_quote_status(id).await; + if let Ok(response) = response { + if *last_state == AnyState::MeltQuoteState(response.state) { + continue; + } + *last_state = AnyState::MeltQuoteState(response.state); + if let Err(err) = + sender.try_send(NotificationPayload::MeltQuoteBolt11Response(response)) + { + tracing::error!("Error sending melt quote response: {:?}", err); + } + } + } + UrlType::PublicKey(id) => { + let responses = http_client + .post_check_state(CheckStateRequest { ys: vec![*id] }) + .await; + if let Ok(mut responses) = responses { + let response = if let Some(state) = responses.states.pop() { + state + } else { + continue; + }; + + if *last_state == AnyState::PublicKey(response.state) { + continue; + } + *last_state = AnyState::PublicKey(response.state); + if let Err(err) = sender.try_send(NotificationPayload::ProofState(response)) { + tracing::error!("Error sending proof state response: {:?}", err); + } + } } } } diff --git a/crates/cdk/src/wallet/subscription/mod.rs b/crates/cdk/src/wallet/subscription/mod.rs index a2c4afc38..692a6ad13 100644 --- a/crates/cdk/src/wallet/subscription/mod.rs +++ b/crates/cdk/src/wallet/subscription/mod.rs @@ -13,6 +13,8 @@ use cdk_common::subscription::Params; use tokio::sync::{mpsc, RwLock}; use tokio::task::JoinHandle; use tracing::error; +#[cfg(target_arch = "wasm32")] +use wasm_bindgen_futures; use super::Wallet; use crate::mint_url::MintUrl; @@ -207,7 +209,7 @@ impl SubscriptionClient { new_subscription_notif, on_drop_notif, subscriptions: subscriptions.clone(), - worker: Some(Self::start_worker( + worker: Self::start_worker( prefer_ws_method, http_client, url, @@ -215,7 +217,7 @@ impl SubscriptionClient { new_subscription_recv, on_drop_recv, wallet, - )), + ), } } @@ -228,7 +230,7 @@ impl SubscriptionClient { new_subscription_recv: mpsc::Receiver, on_drop_recv: mpsc::Receiver, wallet: Arc, - ) -> JoinHandle<()> { + ) -> Option> { #[cfg(any( feature = "http_subscription", not(feature = "mint"), @@ -293,7 +295,7 @@ impl SubscriptionClient { new_subscription_recv: mpsc::Receiver, on_drop: mpsc::Receiver, wallet: Arc, - ) -> JoinHandle<()> { + ) -> Option> { let http_worker = http::http_main( vec![], http_client, @@ -304,12 +306,15 @@ impl SubscriptionClient { ); #[cfg(target_arch = "wasm32")] - let ret = tokio::task::spawn_local(http_worker); + { + wasm_bindgen_futures::spawn_local(http_worker); + None + } #[cfg(not(target_arch = "wasm32"))] - let ret = tokio::spawn(http_worker); - - ret + { + Some(tokio::spawn(http_worker)) + } } /// WebSocket subscription client @@ -328,22 +333,22 @@ impl SubscriptionClient { new_subscription_recv: mpsc::Receiver, on_drop: mpsc::Receiver, wallet: Arc, - ) -> JoinHandle<()> { - tokio::spawn(ws::ws_main( + ) -> Option> { + Some(tokio::spawn(ws::ws_main( http_client, url, subscriptions, new_subscription_recv, on_drop, wallet, - )) + ))) } } impl Drop for SubscriptionClient { fn drop(&mut self) { - if let Some(sender) = self.worker.take() { - sender.abort(); + if let Some(handle) = self.worker.take() { + handle.abort(); } } } From 2dbb418db79b458d401ceeff52575b15bd951656 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Tue, 16 Sep 2025 10:55:36 +0100 Subject: [PATCH 156/321] feat: store melt_request (#1045) --- crates/cdk-common/src/database/mint/mod.rs | 76 ++++++--- crates/cdk-postgres/start_db_for_test.sh | 0 crates/cdk-sql-common/src/mint/migrations.rs | 2 + ..._add_melt_request_and_blinded_messages.sql | 20 +++ ..._add_melt_request_and_blinded_messages.sql | 23 +++ crates/cdk-sql-common/src/mint/mod.rs | 154 +++++++++++++++++- crates/cdk/src/mint/melt.rs | 90 ++++++---- crates/cdk/src/mint/proof_writer.rs | 5 +- crates/cdk/src/mint/swap.rs | 2 +- 9 files changed, 311 insertions(+), 61 deletions(-) mode change 100644 => 100755 crates/cdk-postgres/start_db_for_test.sh create mode 100644 crates/cdk-sql-common/src/mint/migrations/postgres/20250902140000_add_melt_request_and_blinded_messages.sql create mode 100644 crates/cdk-sql-common/src/mint/migrations/sqlite/20250902140000_add_melt_request_and_blinded_messages.sql diff --git a/crates/cdk-common/src/database/mint/mod.rs b/crates/cdk-common/src/database/mint/mod.rs index 3d68abc50..02a26aee5 100644 --- a/crates/cdk-common/src/database/mint/mod.rs +++ b/crates/cdk-common/src/database/mint/mod.rs @@ -2,6 +2,28 @@ use std::collections::HashMap; +use async_trait::async_trait; +use cashu::quote_id::QuoteId; +use cashu::{Amount, MintInfo}; + +use super::Error; +use crate::common::QuoteTTL; +use crate::mint::{self, MintKeySetInfo, MintQuote as MintMintQuote}; +use crate::nuts::{ + BlindSignature, BlindedMessage, CurrencyUnit, Id, MeltQuoteState, Proof, Proofs, PublicKey, + State, +}; +use crate::payment::PaymentIdentifier; + +#[cfg(feature = "auth")] +mod auth; + +#[cfg(feature = "test")] +pub mod test; + +#[cfg(feature = "auth")] +pub use auth::{MintAuthDatabase, MintAuthTransaction}; + /// Valid ASCII characters for namespace and key strings in KV store pub const KVSTORE_NAMESPACE_KEY_ALPHABET: &str = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-"; @@ -62,26 +84,16 @@ pub fn validate_kvstore_params( Ok(()) } -use async_trait::async_trait; -use cashu::quote_id::QuoteId; -use cashu::{Amount, MintInfo}; - -use super::Error; -use crate::common::QuoteTTL; -use crate::mint::{self, MintKeySetInfo, MintQuote as MintMintQuote}; -use crate::nuts::{ - BlindSignature, CurrencyUnit, Id, MeltQuoteState, Proof, Proofs, PublicKey, State, -}; -use crate::payment::PaymentIdentifier; - -#[cfg(feature = "auth")] -mod auth; - -#[cfg(feature = "test")] -pub mod test; - -#[cfg(feature = "auth")] -pub use auth::{MintAuthDatabase, MintAuthTransaction}; +/// Information about a melt request stored in the database +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct MeltRequestInfo { + /// Total amount of all input proofs in the melt request + pub inputs_amount: Amount, + /// Fee amount associated with the input proofs + pub inputs_fee: Amount, + /// Blinded messages for change outputs + pub change_outputs: Vec, +} /// KeysDatabaseWriter #[async_trait] @@ -123,6 +135,24 @@ pub trait QuotesTransaction<'a> { /// Mint Quotes Database Error type Err: Into + From; + /// Add melt_request with quote_id, inputs_amount, and blinded_messages + async fn add_melt_request_and_blinded_messages( + &mut self, + quote_id: &QuoteId, + inputs_amount: Amount, + inputs_fee: Amount, + blinded_messages: &[BlindedMessage], + ) -> Result<(), Self::Err>; + + /// Get melt_request and associated blinded_messages by quote_id + async fn get_melt_request_and_blinded_messages( + &mut self, + quote_id: &QuoteId, + ) -> Result, Self::Err>; + + /// Delete melt_request and associated blinded_messages by quote_id + async fn delete_melt_request(&mut self, quote_id: &QuoteId) -> Result<(), Self::Err>; + /// Get [`MintMintQuote`] and lock it for update in this transaction async fn get_mint_quote( &mut self, @@ -242,6 +272,12 @@ pub trait ProofsTransaction<'a> { ys: &[PublicKey], quote_id: Option, ) -> Result<(), Self::Err>; + + /// Get ys by quote id + async fn get_proof_ys_by_quote_id( + &self, + quote_id: &QuoteId, + ) -> Result, Self::Err>; } /// Mint Proof Database trait diff --git a/crates/cdk-postgres/start_db_for_test.sh b/crates/cdk-postgres/start_db_for_test.sh old mode 100644 new mode 100755 diff --git a/crates/cdk-sql-common/src/mint/migrations.rs b/crates/cdk-sql-common/src/mint/migrations.rs index 1db88edea..9609719e8 100644 --- a/crates/cdk-sql-common/src/mint/migrations.rs +++ b/crates/cdk-sql-common/src/mint/migrations.rs @@ -4,6 +4,7 @@ pub static MIGRATIONS: &[(&str, &str, &str)] = &[ ("postgres", "1_initial.sql", include_str!(r#"./migrations/postgres/1_initial.sql"#)), ("postgres", "2_remove_request_lookup_kind_constraints.sql", include_str!(r#"./migrations/postgres/2_remove_request_lookup_kind_constraints.sql"#)), ("postgres", "20250901090000_add_kv_store.sql", include_str!(r#"./migrations/postgres/20250901090000_add_kv_store.sql"#)), + ("postgres", "20250902140000_add_melt_request_and_blinded_messages.sql", include_str!(r#"./migrations/postgres/20250902140000_add_melt_request_and_blinded_messages.sql"#)), ("postgres", "20250903200000_add_signatory_amounts.sql", include_str!(r#"./migrations/postgres/20250903200000_add_signatory_amounts.sql"#)), ("sqlite", "1_fix_sqlx_migration.sql", include_str!(r#"./migrations/sqlite/1_fix_sqlx_migration.sql"#)), ("sqlite", "20240612124932_init.sql", include_str!(r#"./migrations/sqlite/20240612124932_init.sql"#)), @@ -30,5 +31,6 @@ pub static MIGRATIONS: &[(&str, &str, &str)] = &[ ("sqlite", "20250812132015_drop_melt_request.sql", include_str!(r#"./migrations/sqlite/20250812132015_drop_melt_request.sql"#)), ("sqlite", "20250819200000_remove_request_lookup_kind_constraints.sql", include_str!(r#"./migrations/sqlite/20250819200000_remove_request_lookup_kind_constraints.sql"#)), ("sqlite", "20250901090000_add_kv_store.sql", include_str!(r#"./migrations/sqlite/20250901090000_add_kv_store.sql"#)), + ("sqlite", "20250902140000_add_melt_request_and_blinded_messages.sql", include_str!(r#"./migrations/sqlite/20250902140000_add_melt_request_and_blinded_messages.sql"#)), ("sqlite", "20250903200000_add_signatory_amounts.sql", include_str!(r#"./migrations/sqlite/20250903200000_add_signatory_amounts.sql"#)), ]; diff --git a/crates/cdk-sql-common/src/mint/migrations/postgres/20250902140000_add_melt_request_and_blinded_messages.sql b/crates/cdk-sql-common/src/mint/migrations/postgres/20250902140000_add_melt_request_and_blinded_messages.sql new file mode 100644 index 000000000..af2324399 --- /dev/null +++ b/crates/cdk-sql-common/src/mint/migrations/postgres/20250902140000_add_melt_request_and_blinded_messages.sql @@ -0,0 +1,20 @@ +-- Drop existing melt_request table and recreate with new schema +DROP TABLE IF EXISTS melt_request; +CREATE TABLE melt_request ( + quote_id TEXT PRIMARY KEY, + inputs_amount INTEGER NOT NULL, + inputs_fee INTEGER NOT NULL, + FOREIGN KEY (quote_id) REFERENCES melt_quote(id) +); + +-- Add blinded_messages table +CREATE TABLE blinded_messages ( + quote_id TEXT NOT NULL, + blinded_message BYTEA NOT NULL, + keyset_id TEXT NOT NULL, + amount INTEGER NOT NULL, + FOREIGN KEY (quote_id) REFERENCES melt_request(quote_id) ON DELETE CASCADE +); + +-- Add index for faster lookups on blinded_messages +CREATE INDEX blinded_messages_quote_id_index ON blinded_messages(quote_id); diff --git a/crates/cdk-sql-common/src/mint/migrations/sqlite/20250902140000_add_melt_request_and_blinded_messages.sql b/crates/cdk-sql-common/src/mint/migrations/sqlite/20250902140000_add_melt_request_and_blinded_messages.sql new file mode 100644 index 000000000..9c8b56327 --- /dev/null +++ b/crates/cdk-sql-common/src/mint/migrations/sqlite/20250902140000_add_melt_request_and_blinded_messages.sql @@ -0,0 +1,23 @@ + +-- Drop existing melt_request table and recreate with new schema +DROP TABLE IF EXISTS melt_request; +CREATE TABLE melt_request ( + quote_id TEXT PRIMARY KEY, + inputs_amount INTEGER NOT NULL, + inputs_fee INTEGER NOT NULL, + FOREIGN KEY (quote_id) REFERENCES melt_quote(id) +); + +-- Add blinded_messages table +CREATE TABLE blinded_messages ( + quote_id TEXT NOT NULL, + blinded_message BLOB NOT NULL, + amount INTEGER NOT NULL DEFAULT 0, + keyset_id TEXT NOT NULL, + FOREIGN KEY (quote_id) REFERENCES melt_request(quote_id) ON DELETE CASCADE +); + +-- Add index for faster lookups on blinded_messages +CREATE INDEX blinded_messages_quote_id_index ON blinded_messages(quote_id); +-- Create an index on keyset_id for better query performance +CREATE INDEX blinded_messages_keyset_id_index ON blinded_messages(keyset_id); diff --git a/crates/cdk-sql-common/src/mint/mod.rs b/crates/cdk-sql-common/src/mint/mod.rs index e86b354d4..19b3042c9 100644 --- a/crates/cdk-sql-common/src/mint/mod.rs +++ b/crates/cdk-sql-common/src/mint/mod.rs @@ -32,8 +32,8 @@ use cdk_common::secret::Secret; use cdk_common::state::check_state_transition; use cdk_common::util::unix_time; use cdk_common::{ - Amount, BlindSignature, BlindSignatureDleq, CurrencyUnit, Id, MeltQuoteState, MintInfo, - PaymentMethod, Proof, Proofs, PublicKey, SecretKey, State, + Amount, BlindSignature, BlindSignatureDleq, BlindedMessage, CurrencyUnit, Id, MeltQuoteState, + MintInfo, PaymentMethod, Proof, Proofs, PublicKey, SecretKey, State, }; use lightning_invoice::Bolt11Invoice; use migrations::MIGRATIONS; @@ -277,6 +277,33 @@ where Ok(()) } + + async fn get_proof_ys_by_quote_id( + &self, + quote_id: &QuoteId, + ) -> Result, Self::Err> { + Ok(query( + r#" + SELECT + amount, + keyset_id, + secret, + c, + witness + FROM + proof + WHERE + quote_id = :quote_id + "#, + )? + .bind("quote_id", quote_id.to_string()) + .fetch_all(&self.inner) + .await? + .into_iter() + .map(sql_row_to_proof) + .collect::, _>>()? + .ys()?) + } } #[async_trait] @@ -564,6 +591,123 @@ where { type Err = Error; + async fn add_melt_request_and_blinded_messages( + &mut self, + quote_id: &QuoteId, + inputs_amount: Amount, + inputs_fee: Amount, + blinded_messages: &[BlindedMessage], + ) -> Result<(), Self::Err> { + query( + r#" + INSERT INTO melt_request + (quote_id, inputs_amount, inputs_fee) + VALUES + (:quote_id, :inputs_amount, :inputs_fee) + "#, + )? + .bind("quote_id", quote_id.to_string()) + .bind("inputs_amount", inputs_amount.to_i64()) + .bind("inputs_fee", inputs_fee.to_i64()) + .execute(&self.inner) + .await?; + + for message in blinded_messages { + query( + r#" + INSERT INTO blinded_messages + (quote_id, blinded_message, keyset_id, amount) + VALUES + (:quote_id, :blinded_message, :keyset_id, :amount) + "#, + )? + .bind("quote_id", quote_id.to_string()) + .bind( + "blinded_message", + message.blinded_secret.to_bytes().to_vec(), + ) + .bind("keyset_id", message.keyset_id.to_string()) + .bind("amount", message.amount.to_i64()) + .execute(&self.inner) + .await?; + } + + Ok(()) + } + + async fn get_melt_request_and_blinded_messages( + &mut self, + quote_id: &QuoteId, + ) -> Result, Self::Err> { + let melt_request_row = query( + r#" + SELECT inputs_amount, inputs_fee + FROM melt_request + WHERE quote_id = :quote_id + FOR UPDATE + "#, + )? + .bind("quote_id", quote_id.to_string()) + .fetch_one(&self.inner) + .await?; + + if let Some(row) = melt_request_row { + let inputs_amount: u64 = column_as_number!(row[0].clone()); + let inputs_fee: u64 = column_as_number!(row[1].clone()); + + let blinded_messages_rows = query( + r#" + SELECT blinded_message, keyset_id, amount + FROM blinded_messages + WHERE quote_id = :quote_id + "#, + )? + .bind("quote_id", quote_id.to_string()) + .fetch_all(&self.inner) + .await?; + + let blinded_messages: Result, Error> = blinded_messages_rows + .into_iter() + .map(|row| -> Result { + let blinded_message_key = + column_as_string!(&row[0], PublicKey::from_hex, PublicKey::from_slice); + let keyset_id = column_as_string!(&row[1], Id::from_str, Id::from_bytes); + let amount: u64 = column_as_number!(row[2].clone()); + + Ok(BlindedMessage { + blinded_secret: blinded_message_key, + keyset_id, + amount: Amount::from(amount), + witness: None, // Not storing witness in database currently + }) + }) + .collect(); + let blinded_messages = blinded_messages?; + + Ok(Some(database::mint::MeltRequestInfo { + inputs_amount: Amount::from(inputs_amount), + inputs_fee: Amount::from(inputs_fee), + change_outputs: blinded_messages, + })) + } else { + Ok(None) + } + } + + async fn delete_melt_request(&mut self, quote_id: &QuoteId) -> Result<(), Self::Err> { + query( + r#" + DELETE FROM melt_request + WHERE quote_id = :quote_id + "#, + )? + .bind("quote_id", quote_id.to_string()) + .execute(&self.inner) + .await?; + + Ok(()) + } + #[instrument(skip(self))] async fn increment_mint_quote_amount_paid( &mut self, @@ -788,8 +932,6 @@ VALUES (:quote_id, :amount, :timestamp); } async fn add_melt_quote(&mut self, quote: mint::MeltQuote) -> Result<(), Self::Err> { - // First try to find and replace any expired UNPAID quotes with the same request_lookup_id - // Now insert the new quote query( r#" @@ -916,6 +1058,10 @@ VALUES (:quote_id, :amount, :timestamp); let old_state = quote.state; quote.state = state; + if state == MeltQuoteState::Unpaid || state == MeltQuoteState::Failed { + self.delete_melt_request(quote_id).await?; + } + Ok((old_state, quote)) } diff --git a/crates/cdk/src/mint/melt.rs b/crates/cdk/src/mint/melt.rs index aba1ee488..40baa4304 100644 --- a/crates/cdk/src/mint/melt.rs +++ b/crates/cdk/src/mint/melt.rs @@ -2,10 +2,10 @@ use std::str::FromStr; use anyhow::bail; use cdk_common::amount::amount_for_offer; +use cdk_common::database::mint::MeltRequestInfo; use cdk_common::database::{self, MintTransaction}; use cdk_common::melt::MeltQuoteRequest; use cdk_common::mint::MeltPaymentRequest; -use cdk_common::nut00::ProofsMethods; use cdk_common::nut05::MeltMethodOptions; use cdk_common::payment::{ Bolt11OutgoingPaymentOptions, Bolt12OutgoingPaymentOptions, OutgoingPaymentOptions, @@ -501,6 +501,25 @@ impl Mint { input_verification: Verification, melt_request: &MeltRequest, ) -> Result<(ProofWriter, MeltQuote), Error> { + let Verification { + amount: input_amount, + unit: input_unit, + } = input_verification; + + ensure_cdk!(input_unit.is_some(), Error::UnsupportedUnit); + + let mut proof_writer = + ProofWriter::new(self.localstore.clone(), self.pubsub_manager.clone()); + + proof_writer + .add_proofs( + tx, + melt_request.inputs(), + Some(melt_request.quote_id().to_owned()), + ) + .await?; + + // Only after proof verification succeeds, proceed with quote state check let (state, quote) = tx .update_melt_quote_state(melt_request.quote(), MeltQuoteState::Pending, None) .await?; @@ -515,13 +534,6 @@ impl Mint { self.pubsub_manager .melt_quote_status("e, None, None, MeltQuoteState::Pending); - let Verification { - amount: input_amount, - unit: input_unit, - } = input_verification; - - ensure_cdk!(input_unit.is_some(), Error::UnsupportedUnit); - let fee = self.get_proofs_fee(melt_request.inputs()).await?; let required_total = quote.amount + quote.fee_reserve + fee; @@ -542,11 +554,6 @@ impl Mint { )); } - let mut proof_writer = - ProofWriter::new(self.localstore.clone(), self.pubsub_manager.clone()); - - proof_writer.add_proofs(tx, melt_request.inputs()).await?; - let EnforceSigFlag { sig_flag, .. } = enforce_sig_flag(melt_request.inputs().clone()); if sig_flag == SigFlag::SigAll { @@ -619,6 +626,16 @@ impl Mint { } }; + let inputs_fee = self.get_proofs_fee(melt_request.inputs()).await?; + + tx.add_melt_request_and_blinded_messages( + melt_request.quote_id(), + melt_request.inputs_amount()?, + inputs_fee, + melt_request.outputs().as_ref().unwrap_or(&Vec::new()), + ) + .await?; + let settled_internally_amount = match self .handle_internal_melt_mint(&mut tx, "e, melt_request) .await @@ -811,14 +828,7 @@ impl Mint { // If we made it here the payment has been made. // We process the melt burning the inputs and returning change let res = match self - .process_melt_request( - tx, - proof_writer, - quote, - melt_request, - preimage, - amount_spent_quote_unit, - ) + .process_melt_request(tx, proof_writer, quote, preimage, amount_spent_quote_unit) .await { Ok(response) => response, @@ -854,14 +864,22 @@ impl Mint { mut tx: Box + Send + Sync + '_>, mut proof_writer: ProofWriter, quote: MeltQuote, - melt_request: &MeltRequest, payment_preimage: Option, total_spent: Amount, ) -> Result, Error> { #[cfg(feature = "prometheus")] METRICS.inc_in_flight_requests("process_melt_request"); - let input_ys = melt_request.inputs().ys()?; + // Try to get input_ys from the stored melt request, fall back to original request if not found + let input_ys: Vec<_> = tx.get_proof_ys_by_quote_id("e.id).await?; + + assert!(!input_ys.is_empty()); + + tracing::debug!( + "Updating {} proof states to Spent for quote {}", + input_ys.len(), + quote.id + ); let update_proof_states_result = proof_writer .update_proofs_states(&mut tx, &input_ys, State::Spent) @@ -872,22 +890,28 @@ impl Mint { self.record_melt_quote_failure("process_melt_request"); return Err(update_proof_states_result.err().unwrap()); } + tracing::debug!("Successfully updated proof states to Spent"); - tx.update_melt_quote_state( - melt_request.quote(), - MeltQuoteState::Paid, - payment_preimage.clone(), - ) - .await?; + tx.update_melt_quote_state("e.id, MeltQuoteState::Paid, payment_preimage.clone()) + .await?; let mut change = None; - let inputs_amount = melt_request.inputs_amount()?; + let MeltRequestInfo { + inputs_amount, + inputs_fee, + change_outputs, + } = tx + .get_melt_request_and_blinded_messages("e.id) + .await? + .ok_or(Error::UnknownQuote)?; // Check if there is change to return if inputs_amount > total_spent { // Check if wallet provided change outputs - if let Some(outputs) = melt_request.outputs().clone() { + if !change_outputs.is_empty() { + let outputs = change_outputs; + let blinded_messages: Vec = outputs.iter().map(|b| b.blinded_secret).collect(); @@ -904,9 +928,7 @@ impl Mint { return Err(Error::BlindedMessageAlreadySigned); } - let fee = self.get_proofs_fee(melt_request.inputs()).await?; - - let change_target = melt_request.inputs_amount()? - total_spent - fee; + let change_target = inputs_amount - total_spent - inputs_fee; let mut amounts = change_target.split(); diff --git a/crates/cdk/src/mint/proof_writer.rs b/crates/cdk/src/mint/proof_writer.rs index b21bd3a9a..a7d184b7c 100644 --- a/crates/cdk/src/mint/proof_writer.rs +++ b/crates/cdk/src/mint/proof_writer.rs @@ -3,7 +3,7 @@ use std::collections::{HashMap, HashSet}; use std::sync::Arc; use cdk_common::database::{self, MintDatabase, MintTransaction}; -use cdk_common::{Error, Proofs, ProofsMethods, PublicKey, State}; +use cdk_common::{Error, Proofs, ProofsMethods, PublicKey, QuoteId, State}; use super::subscription::PubSubManager; @@ -49,6 +49,7 @@ impl ProofWriter { &mut self, tx: &mut Tx<'_, '_>, proofs: &Proofs, + quote_id: Option, ) -> Result, Error> { let proof_states = if let Some(proofs) = self.proof_original_states.as_mut() { proofs @@ -56,7 +57,7 @@ impl ProofWriter { return Err(Error::Internal); }; - if let Some(err) = tx.add_proofs(proofs.clone(), None).await.err() { + if let Some(err) = tx.add_proofs(proofs.clone(), quote_id).await.err() { return match err { cdk_common::database::Error::Duplicate => Err(Error::TokenPending), cdk_common::database::Error::AttemptUpdateSpentProof => { diff --git a/crates/cdk/src/mint/swap.rs b/crates/cdk/src/mint/swap.rs index 0e14fa32b..0cab12a31 100644 --- a/crates/cdk/src/mint/swap.rs +++ b/crates/cdk/src/mint/swap.rs @@ -61,7 +61,7 @@ impl Mint { let mut proof_writer = ProofWriter::new(self.localstore.clone(), self.pubsub_manager.clone()); let input_ys = match proof_writer - .add_proofs(&mut tx, swap_request.inputs()) + .add_proofs(&mut tx, swap_request.inputs(), None) .await { Ok(ys) => ys, From 5ee405de89b4c875fb1235f5afca80a4e0f473c3 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Tue, 16 Sep 2025 14:08:43 +0100 Subject: [PATCH 157/321] Store last pay index (#1077) --- crates/cdk-cln/src/error.rs | 3 + crates/cdk-cln/src/lib.rs | 60 ++++- .../cdk-common/src/database/mint/auth/mod.rs | 4 + crates/cdk-common/src/database/mint/mod.rs | 8 +- crates/cdk-common/src/database/mod.rs | 4 +- crates/cdk-common/src/payment.rs | 16 ++ .../cdk-integration-tests/src/init_regtest.rs | 8 +- crates/cdk-lnd/src/error.rs | 3 + crates/cdk-lnd/src/lib.rs | 206 ++++++++++++++---- crates/cdk-mintd/src/lib.rs | 15 +- crates/cdk-mintd/src/setup.rs | 12 +- crates/cdk-payment-processor/Cargo.toml | 3 +- .../src/bin/payment_processor.rs | 7 +- crates/cdk/src/mint/builder.rs | 22 +- crates/cdk/src/mint/melt.rs | 8 +- crates/cdk/src/mint/mod.rs | 58 ++--- crates/cdk/src/mint/proof_writer.rs | 9 +- crates/cdk/src/mint/subscription/manager.rs | 7 +- .../src/mint/subscription/on_subscription.rs | 5 +- 19 files changed, 329 insertions(+), 129 deletions(-) diff --git a/crates/cdk-cln/src/error.rs b/crates/cdk-cln/src/error.rs index 2f9d8e0e9..85025b865 100644 --- a/crates/cdk-cln/src/error.rs +++ b/crates/cdk-cln/src/error.rs @@ -32,6 +32,9 @@ pub enum Error { /// Bolt12 Error #[error("Bolt12 error: {0}")] Bolt12(String), + /// Database Error + #[error("Database error: {0}")] + Database(String), } impl From for cdk_common::payment::Error { diff --git a/crates/cdk-cln/src/lib.rs b/crates/cdk-cln/src/lib.rs index 0bd797d4e..392c7d4e3 100644 --- a/crates/cdk-cln/src/lib.rs +++ b/crates/cdk-cln/src/lib.rs @@ -16,6 +16,7 @@ use async_trait::async_trait; use bitcoin::hashes::sha256::Hash; use cdk_common::amount::{to_unit, Amount}; use cdk_common::common::FeeReserve; +use cdk_common::database::mint::DynMintKVStore; use cdk_common::nuts::{CurrencyUnit, MeltOptions, MeltQuoteState}; use cdk_common::payment::{ self, Bolt11IncomingPaymentOptions, Bolt11Settings, Bolt12IncomingPaymentOptions, @@ -43,6 +44,11 @@ use uuid::Uuid; pub mod error; +// KV Store constants for CLN +const CLN_KV_PRIMARY_NAMESPACE: &str = "cdk_cln_lightning_backend"; +const CLN_KV_SECONDARY_NAMESPACE: &str = "payment_indices"; +const LAST_PAY_INDEX_KV_KEY: &str = "last_pay_index"; + /// CLN mint backend #[derive(Clone)] pub struct Cln { @@ -50,16 +56,22 @@ pub struct Cln { fee_reserve: FeeReserve, wait_invoice_cancel_token: CancellationToken, wait_invoice_is_active: Arc, + kv_store: DynMintKVStore, } impl Cln { /// Create new [`Cln`] - pub async fn new(rpc_socket: PathBuf, fee_reserve: FeeReserve) -> Result { + pub async fn new( + rpc_socket: PathBuf, + fee_reserve: FeeReserve, + kv_store: DynMintKVStore, + ) -> Result { Ok(Self { rpc_socket, fee_reserve, wait_invoice_cancel_token: CancellationToken::new(), wait_invoice_is_active: Arc::new(AtomicBool::new(false)), + kv_store, }) } } @@ -114,14 +126,16 @@ impl MintPayment for Cln { }; tracing::debug!("CLN: Creating stream processing pipeline"); + let kv_store = self.kv_store.clone(); let stream = futures::stream::unfold( ( cln_client, last_pay_index, self.wait_invoice_cancel_token.clone(), Arc::clone(&self.wait_invoice_is_active), + kv_store, ), - |(mut cln_client, mut last_pay_idx, cancel_token, is_active)| async move { + |(mut cln_client, mut last_pay_idx, cancel_token, is_active, kv_store)| async move { // Set the stream as active is_active.store(true, Ordering::SeqCst); tracing::debug!("CLN: Stream is now active, waiting for invoice events with lastpay_index: {:?}", last_pay_idx); @@ -179,6 +193,23 @@ impl MintPayment for Cln { last_pay_idx = wait_any_response.pay_index; tracing::debug!("CLN: Updated last_pay_idx to {:?}", last_pay_idx); + + // Store the updated pay index in KV store for persistence + if let Some(pay_index) = last_pay_idx { + let index_str = pay_index.to_string(); + if let Ok(mut tx) = kv_store.begin_transaction().await { + if let Err(e) = tx.kv_write(CLN_KV_PRIMARY_NAMESPACE, CLN_KV_SECONDARY_NAMESPACE, LAST_PAY_INDEX_KV_KEY, index_str.as_bytes()).await { + tracing::warn!("CLN: Failed to write last pay index {} to KV store: {}", pay_index, e); + } else if let Err(e) = tx.commit().await { + tracing::warn!("CLN: Failed to commit last pay index {} to KV store: {}", pay_index, e); + } else { + tracing::debug!("CLN: Stored last pay index {} in KV store", pay_index); + } + } else { + tracing::warn!("CLN: Failed to begin KV transaction for storing pay index {}", pay_index); + } + } + let payment_hash = wait_any_response.payment_hash; tracing::debug!("CLN: Payment hash: {}", payment_hash); @@ -245,7 +276,7 @@ impl MintPayment for Cln { tracing::info!("CLN: Created WaitPaymentResponse with amount {} msats", amount_msats.msat()); let event = Event::PaymentReceived(response); - break Some((event, (cln_client, last_pay_idx, cancel_token, is_active))); + break Some((event, (cln_client, last_pay_idx, cancel_token, is_active, kv_store))); } Err(e) => { tracing::warn!("CLN: Error fetching invoice: {e}"); @@ -733,6 +764,27 @@ impl Cln { /// Get last pay index for cln async fn get_last_pay_index(&self) -> Result, Error> { + // First try to read from KV store + if let Some(stored_index) = self + .kv_store + .kv_read( + CLN_KV_PRIMARY_NAMESPACE, + CLN_KV_SECONDARY_NAMESPACE, + LAST_PAY_INDEX_KV_KEY, + ) + .await + .map_err(|e| Error::Database(e.to_string()))? + { + if let Ok(index_str) = std::str::from_utf8(&stored_index) { + if let Ok(index) = index_str.parse::() { + tracing::debug!("CLN: Retrieved last pay index {} from KV store", index); + return Ok(Some(index)); + } + } + } + + // Fall back to querying CLN directly + tracing::debug!("CLN: No stored last pay index found in KV store, querying CLN directly"); let mut cln_client = self.cln_client().await?; let listinvoices_response = cln_client .call_typed(&ListinvoicesRequest { @@ -753,7 +805,7 @@ impl Cln { } } - /// Decode string + /// Decode string #[instrument(skip(self))] async fn decode_string(&self, string: String) -> Result { let mut cln_client = self.cln_client().await?; diff --git a/crates/cdk-common/src/database/mint/auth/mod.rs b/crates/cdk-common/src/database/mint/auth/mod.rs index a71257ee3..26f258195 100644 --- a/crates/cdk-common/src/database/mint/auth/mod.rs +++ b/crates/cdk-common/src/database/mint/auth/mod.rs @@ -88,3 +88,7 @@ pub trait MintAuthDatabase { &self, ) -> Result>, Self::Err>; } + +/// Type alias for trait objects +pub type DynMintAuthDatabase = + std::sync::Arc + Send + Sync>; diff --git a/crates/cdk-common/src/database/mint/mod.rs b/crates/cdk-common/src/database/mint/mod.rs index 02a26aee5..f54a9b8ca 100644 --- a/crates/cdk-common/src/database/mint/mod.rs +++ b/crates/cdk-common/src/database/mint/mod.rs @@ -22,7 +22,7 @@ mod auth; pub mod test; #[cfg(feature = "auth")] -pub use auth::{MintAuthDatabase, MintAuthTransaction}; +pub use auth::{DynMintAuthDatabase, MintAuthDatabase, MintAuthTransaction}; /// Valid ASCII characters for namespace and key strings in KV store pub const KVSTORE_NAMESPACE_KEY_ALPHABET: &str = @@ -442,6 +442,9 @@ pub trait KVStore: KVStoreDatabase { ) -> Result + Send + Sync + 'a>, Error>; } +/// Type alias for Mint Kv store +pub type DynMintKVStore = std::sync::Arc + Send + Sync>; + /// Mint Database trait #[async_trait] pub trait Database: @@ -461,3 +464,6 @@ pub trait Database: /// Get [`QuoteTTL`] async fn get_quote_ttl(&self) -> Result; } + +/// Type alias for Mint Database +pub type DynMintDatabase = std::sync::Arc + Send + Sync>; diff --git a/crates/cdk-common/src/database/mod.rs b/crates/cdk-common/src/database/mod.rs index 6abcfe288..4b808a11f 100644 --- a/crates/cdk-common/src/database/mod.rs +++ b/crates/cdk-common/src/database/mod.rs @@ -7,7 +7,7 @@ mod wallet; #[cfg(feature = "mint")] pub use mint::{ - Database as MintDatabase, DbTransactionFinalizer as MintDbWriterFinalizer, + Database as MintDatabase, DbTransactionFinalizer as MintDbWriterFinalizer, DynMintDatabase, KVStore as MintKVStore, KVStoreDatabase as MintKVStoreDatabase, KVStoreTransaction as MintKVStoreTransaction, KeysDatabase as MintKeysDatabase, KeysDatabaseTransaction as MintKeyDatabaseTransaction, ProofsDatabase as MintProofsDatabase, @@ -16,7 +16,7 @@ pub use mint::{ SignaturesTransaction as MintSignatureTransaction, Transaction as MintTransaction, }; #[cfg(all(feature = "mint", feature = "auth"))] -pub use mint::{MintAuthDatabase, MintAuthTransaction}; +pub use mint::{DynMintAuthDatabase, MintAuthDatabase, MintAuthTransaction}; #[cfg(feature = "wallet")] pub use wallet::Database as WalletDatabase; diff --git a/crates/cdk-common/src/payment.rs b/crates/cdk-common/src/payment.rs index 15f18427e..8ee371d69 100644 --- a/crates/cdk-common/src/payment.rs +++ b/crates/cdk-common/src/payment.rs @@ -327,6 +327,19 @@ pub enum Event { PaymentReceived(WaitPaymentResponse), } +impl Default for Event { + fn default() -> Self { + // We use this as a sentinel value for no-op events + // The actual processing will filter these out + Event::PaymentReceived(WaitPaymentResponse { + payment_identifier: PaymentIdentifier::CustomId("default".to_string()), + payment_amount: Amount::from(0), + unit: CurrencyUnit::Msat, + payment_id: "default".to_string(), + }) + } +} + /// Wait any invoice response #[derive(Debug, Clone, Hash, Serialize, Deserialize)] pub struct WaitPaymentResponse { @@ -599,3 +612,6 @@ where result } } + +/// Type alias for Mint Payment trait +pub type DynMintPayment = std::sync::Arc + Send + Sync>; diff --git a/crates/cdk-integration-tests/src/init_regtest.rs b/crates/cdk-integration-tests/src/init_regtest.rs index faa61b58c..8bb668654 100644 --- a/crates/cdk-integration-tests/src/init_regtest.rs +++ b/crates/cdk-integration-tests/src/init_regtest.rs @@ -6,7 +6,9 @@ use std::sync::Arc; use anyhow::Result; use cdk::types::FeeReserve; use cdk_cln::Cln as CdkCln; +use cdk_common::database::mint::DynMintKVStore; use cdk_lnd::Lnd as CdkLnd; +use cdk_sqlite::mint::memory; use ldk_node::lightning::ln::msgs::SocketAddress; use ldk_node::Node; use ln_regtest_rs::bitcoin_client::BitcoinClient; @@ -164,7 +166,8 @@ pub async fn create_cln_backend(cln_client: &ClnClient) -> Result { percent_fee_reserve: 1.0, }; - Ok(CdkCln::new(rpc_path, fee_reserve).await?) + let kv_store: DynMintKVStore = Arc::new(memory::empty().await?); + Ok(CdkCln::new(rpc_path, fee_reserve, kv_store).await?) } pub async fn create_lnd_backend(lnd_client: &LndClient) -> Result { @@ -173,11 +176,14 @@ pub async fn create_lnd_backend(lnd_client: &LndClient) -> Result { percent_fee_reserve: 1.0, }; + let kv_store: DynMintKVStore = Arc::new(memory::empty().await?); + Ok(CdkLnd::new( lnd_client.address.clone(), lnd_client.cert_file.clone(), lnd_client.macaroon_file.clone(), fee_reserve, + kv_store, ) .await?) } diff --git a/crates/cdk-lnd/src/error.rs b/crates/cdk-lnd/src/error.rs index 5d1b10f0d..ba546f536 100644 --- a/crates/cdk-lnd/src/error.rs +++ b/crates/cdk-lnd/src/error.rs @@ -39,6 +39,9 @@ pub enum Error { /// Could not read file #[error("Could not read file")] ReadFile, + /// Database Error + #[error("Database error: {0}")] + Database(String), } impl From for cdk_common::payment::Error { diff --git a/crates/cdk-lnd/src/lib.rs b/crates/cdk-lnd/src/lib.rs index fc6e49df6..4066508d0 100644 --- a/crates/cdk-lnd/src/lib.rs +++ b/crates/cdk-lnd/src/lib.rs @@ -18,6 +18,7 @@ use async_trait::async_trait; use cdk_common::amount::{to_unit, Amount, MSAT_IN_SAT}; use cdk_common::bitcoin::hashes::Hash; use cdk_common::common::FeeReserve; +use cdk_common::database::mint::DynMintKVStore; use cdk_common::nuts::{CurrencyUnit, MeltOptions, MeltQuoteState}; use cdk_common::payment::{ self, Bolt11Settings, CreateIncomingPaymentResponse, Event, IncomingPaymentOptions, @@ -42,6 +43,12 @@ pub(crate) use proto::{lnrpc, routerrpc}; use crate::lnrpc::invoice::InvoiceState; +/// LND KV Store constants +const LND_KV_PRIMARY_NAMESPACE: &str = "cdk_lnd_lightning_backend"; +const LND_KV_SECONDARY_NAMESPACE: &str = "payment_indices"; +const LAST_ADD_INDEX_KV_KEY: &str = "last_add_index"; +const LAST_SETTLE_INDEX_KV_KEY: &str = "last_settle_index"; + /// Lnd mint backend #[derive(Clone)] pub struct Lnd { @@ -50,6 +57,7 @@ pub struct Lnd { _macaroon_file: PathBuf, lnd_client: client::Client, fee_reserve: FeeReserve, + kv_store: DynMintKVStore, wait_invoice_cancel_token: CancellationToken, wait_invoice_is_active: Arc, settings: Bolt11Settings, @@ -65,6 +73,7 @@ impl Lnd { cert_file: PathBuf, macaroon_file: PathBuf, fee_reserve: FeeReserve, + kv_store: DynMintKVStore, ) -> Result { // Validate address is not empty if address.is_empty() { @@ -104,6 +113,7 @@ impl Lnd { _macaroon_file: macaroon_file, lnd_client, fee_reserve, + kv_store, wait_invoice_cancel_token: CancellationToken::new(), wait_invoice_is_active: Arc::new(AtomicBool::new(false)), settings: Bolt11Settings { @@ -115,6 +125,55 @@ impl Lnd { }, }) } + + /// Get last add and settle indices from KV store + #[instrument(skip_all)] + async fn get_last_indices(&self) -> Result<(Option, Option), Error> { + let add_index = if let Some(stored_index) = self + .kv_store + .kv_read( + LND_KV_PRIMARY_NAMESPACE, + LND_KV_SECONDARY_NAMESPACE, + LAST_ADD_INDEX_KV_KEY, + ) + .await + .map_err(|e| Error::Database(e.to_string()))? + { + if let Ok(index_str) = std::str::from_utf8(stored_index.as_slice()) { + index_str.parse::().ok() + } else { + None + } + } else { + None + }; + + let settle_index = if let Some(stored_index) = self + .kv_store + .kv_read( + LND_KV_PRIMARY_NAMESPACE, + LND_KV_SECONDARY_NAMESPACE, + LAST_SETTLE_INDEX_KV_KEY, + ) + .await + .map_err(|e| Error::Database(e.to_string()))? + { + if let Ok(index_str) = std::str::from_utf8(stored_index.as_slice()) { + index_str.parse::().ok() + } else { + None + } + } else { + None + }; + + tracing::debug!( + "LND: Retrieved last indices from KV store - add_index: {:?}, settle_index: {:?}", + add_index, + settle_index + ); + Ok((add_index, settle_index)) + } } #[async_trait] @@ -142,11 +201,21 @@ impl MintPayment for Lnd { ) -> Result + Send>>, Self::Err> { let mut lnd_client = self.lnd_client.clone(); + // Get last indices from KV store + let (last_add_index, last_settle_index) = + self.get_last_indices().await.unwrap_or((None, None)); + let stream_req = lnrpc::InvoiceSubscription { - add_index: 0, - settle_index: 0, + add_index: last_add_index.unwrap_or(0), + settle_index: last_settle_index.unwrap_or(0), }; + tracing::debug!( + "LND: Starting invoice subscription with add_index: {}, settle_index: {}", + stream_req.add_index, + stream_req.settle_index + ); + let stream = lnd_client .lightning() .subscribe_invoices(stream_req) @@ -158,68 +227,119 @@ impl MintPayment for Lnd { .into_inner(); let cancel_token = self.wait_invoice_cancel_token.clone(); + let kv_store = self.kv_store.clone(); - Ok(futures::stream::unfold( + let event_stream = futures::stream::unfold( ( stream, cancel_token, Arc::clone(&self.wait_invoice_is_active), + kv_store, + last_add_index.unwrap_or(0), + last_settle_index.unwrap_or(0), ), - |(mut stream, cancel_token, is_active)| async move { + |( + mut stream, + cancel_token, + is_active, + kv_store, + mut current_add_index, + mut current_settle_index, + )| async move { is_active.store(true, Ordering::SeqCst); - tokio::select! { - _ = cancel_token.cancelled() => { - // Stream is cancelled - is_active.store(false, Ordering::SeqCst); - tracing::info!("Waiting for lnd invoice ending"); - None - - } - msg = stream.message() => { + loop { + tokio::select! { + _ = cancel_token.cancelled() => { + // Stream is cancelled + is_active.store(false, Ordering::SeqCst); + tracing::info!("Waiting for lnd invoice ending"); + return None; + } + msg = stream.message() => { + match msg { + Ok(Some(msg)) => { + // Update indices based on the message + current_add_index = current_add_index.max(msg.add_index); + current_settle_index = current_settle_index.max(msg.settle_index); + + // Store the updated indices in KV store regardless of settlement status + let add_index_str = current_add_index.to_string(); + let settle_index_str = current_settle_index.to_string(); + + if let Ok(mut tx) = kv_store.begin_transaction().await { + let mut has_error = false; + + if let Err(e) = tx.kv_write(LND_KV_PRIMARY_NAMESPACE, LND_KV_SECONDARY_NAMESPACE, LAST_ADD_INDEX_KV_KEY, add_index_str.as_bytes()).await { + tracing::warn!("LND: Failed to write add_index {} to KV store: {}", current_add_index, e); + has_error = true; + } + + if let Err(e) = tx.kv_write(LND_KV_PRIMARY_NAMESPACE, LND_KV_SECONDARY_NAMESPACE, LAST_SETTLE_INDEX_KV_KEY, settle_index_str.as_bytes()).await { + tracing::warn!("LND: Failed to write settle_index {} to KV store: {}", current_settle_index, e); + has_error = true; + } + + if !has_error { + if let Err(e) = tx.commit().await { + tracing::warn!("LND: Failed to commit indices to KV store: {}", e); + } else { + tracing::debug!("LND: Stored updated indices - add_index: {}, settle_index: {}", current_add_index, current_settle_index); + } + } + } else { + tracing::warn!("LND: Failed to begin KV transaction for storing indices"); + } - match msg { - Ok(Some(msg)) => { - if msg.state() == InvoiceState::Settled { + // Only emit event for settled invoices + if msg.state() == InvoiceState::Settled { + let hash_slice: Result<[u8;32], _> = msg.r_hash.try_into(); - let hash_slice: Result<[u8;32], _> = msg.r_hash.try_into(); + if let Ok(hash_slice) = hash_slice { + let hash = hex::encode(hash_slice); - if let Ok(hash_slice) = hash_slice { - let hash = hex::encode(hash_slice); + tracing::info!("LND: Payment for {} with amount {} msat", hash, msg.amt_paid_msat); - tracing::info!("LND: Processing payment with hash: {}", hash); let wait_response = WaitPaymentResponse { - payment_identifier: PaymentIdentifier::PaymentHash(hash_slice), payment_amount: Amount::from(msg.amt_paid_msat as u64), + payment_identifier: PaymentIdentifier::PaymentHash(hash_slice), + payment_amount: Amount::from(msg.amt_paid_msat as u64), unit: CurrencyUnit::Msat, payment_id: hash, }; - tracing::info!("LND: Created WaitPaymentResponse with amount {} msat", - msg.amt_paid_msat); let event = Event::PaymentReceived(wait_response); - Some((event, (stream, cancel_token, is_active))) - } else { None } - } else { - None + return Some((event, (stream, cancel_token, is_active, kv_store, current_add_index, current_settle_index))); + } else { + // Invalid hash, skip this message but continue streaming + tracing::error!("LND returned invalid payment hash"); + // Continue the loop without yielding + continue; + } + } else { + // Not a settled invoice, continue but don't emit event + tracing::debug!("LND: Received non-settled invoice, continuing to wait for settled invoices"); + // Continue the loop without yielding + continue; + } + } + Ok(None) => { + is_active.store(false, Ordering::SeqCst); + tracing::info!("LND invoice stream ended."); + return None; + } + Err(err) => { + is_active.store(false, Ordering::SeqCst); + tracing::warn!("Encountered error in LND invoice stream. Stream ending"); + tracing::error!("{:?}", err); + return None; + } + } } } - Ok(None) => { - is_active.store(false, Ordering::SeqCst); - tracing::info!("LND invoice stream ended."); - None - }, // End of stream - Err(err) => { - is_active.store(false, Ordering::SeqCst); - tracing::warn!("Encountered error in LND invoice stream. Stream ending"); - tracing::error!("{:?}", err); - None - - }, // Handle errors gracefully, ends the stream on error - } - } } }, - ) - .boxed()) + ); + + Ok(Box::pin(event_stream)) } #[instrument(skip_all)] diff --git a/crates/cdk-mintd/src/lib.rs b/crates/cdk-mintd/src/lib.rs index 80eb63376..022030560 100644 --- a/crates/cdk-mintd/src/lib.rs +++ b/crates/cdk-mintd/src/lib.rs @@ -38,6 +38,7 @@ use cdk::nuts::{AuthRequired, Method, ProtectedEndpoint, RoutePath}; use cdk::nuts::{ContactInfo, MintVersion, PaymentMethod}; use cdk::types::QuoteTTL; use cdk_axum::cache::HttpCache; +use cdk_common::database::DynMintDatabase; // internal crate modules #[cfg(feature = "prometheus")] use cdk_common::payment::MetricsMintPayment; @@ -97,7 +98,7 @@ async fn initial_setup( settings: &config::Settings, db_password: Option, ) -> Result<( - Arc + Send + Sync>, + DynMintDatabase, Arc + Send + Sync>, Arc + Send + Sync>, )> { @@ -257,7 +258,7 @@ async fn setup_database( _work_dir: &Path, _db_password: Option, ) -> Result<( - Arc + Send + Sync>, + DynMintDatabase, Arc + Send + Sync>, Arc + Send + Sync>, )> { @@ -426,7 +427,7 @@ async fn configure_lightning_backend( .clone() .expect("Config checked at load that cln is some"); let cln = cln_settings - .setup(settings, CurrencyUnit::Msat, None, work_dir, None) + .setup(settings, CurrencyUnit::Msat, None, work_dir, _kv_store) .await?; #[cfg(feature = "prometheus")] let cln = MetricsMintPayment::new(cln); @@ -462,7 +463,7 @@ async fn configure_lightning_backend( LnBackend::Lnd => { let lnd_settings = settings.clone().lnd.expect("Checked at config load"); let lnd = lnd_settings - .setup(settings, CurrencyUnit::Msat, None, work_dir, None) + .setup(settings, CurrencyUnit::Msat, None, work_dir, _kv_store) .await?; #[cfg(feature = "prometheus")] let lnd = MetricsMintPayment::new(lnd); @@ -634,10 +635,10 @@ async fn setup_authentication( _password: Option, ) -> Result { if let Some(auth_settings) = settings.auth.clone() { + use cdk_common::database::DynMintAuthDatabase; + tracing::info!("Auth settings are defined. {:?}", auth_settings); - let auth_localstore: Arc< - dyn cdk_database::MintAuthDatabase + Send + Sync, - > = match settings.database.engine { + let auth_localstore: DynMintAuthDatabase = match settings.database.engine { #[cfg(feature = "sqlite")] DatabaseEngine::Sqlite => { #[cfg(feature = "sqlite")] diff --git a/crates/cdk-mintd/src/setup.rs b/crates/cdk-mintd/src/setup.rs index 127e5142b..24e380bb2 100644 --- a/crates/cdk-mintd/src/setup.rs +++ b/crates/cdk-mintd/src/setup.rs @@ -47,7 +47,7 @@ impl LnBackendSetup for config::Cln { _unit: CurrencyUnit, _runtime: Option>, _work_dir: &Path, - _kv_store: Option + Send + Sync>>, + kv_store: Option + Send + Sync>>, ) -> anyhow::Result { let cln_socket = expand_path( self.rpc_path @@ -61,7 +61,12 @@ impl LnBackendSetup for config::Cln { percent_fee_reserve: self.fee_percent, }; - let cln = cdk_cln::Cln::new(cln_socket, fee_reserve).await?; + let cln = cdk_cln::Cln::new( + cln_socket, + fee_reserve, + kv_store.expect("Cln needs kv store"), + ) + .await?; Ok(cln) } @@ -110,7 +115,7 @@ impl LnBackendSetup for config::Lnd { _unit: CurrencyUnit, _runtime: Option>, _work_dir: &Path, - _kv_store: Option + Send + Sync>>, + kv_store: Option + Send + Sync>>, ) -> anyhow::Result { let address = &self.address; let cert_file = &self.cert_file; @@ -126,6 +131,7 @@ impl LnBackendSetup for config::Lnd { cert_file.clone(), macaroon_file.clone(), fee_reserve, + kv_store.expect("Lnd needs kv store"), ) .await?; diff --git a/crates/cdk-payment-processor/Cargo.toml b/crates/cdk-payment-processor/Cargo.toml index c123705b9..e19e1ccfa 100644 --- a/crates/cdk-payment-processor/Cargo.toml +++ b/crates/cdk-payment-processor/Cargo.toml @@ -17,7 +17,7 @@ path = "src/bin/payment_processor.rs" [features] default = ["cln", "fake", "lnd"] bench = [] -cln = ["dep:cdk-cln"] +cln = ["dep:cdk-cln", "dep:cdk-sqlite"] fake = ["dep:cdk-fake-wallet"] lnd = ["dep:cdk-lnd"] @@ -30,6 +30,7 @@ cdk-common = { workspace = true, features = ["mint"] } cdk-cln = { workspace = true, optional = true } cdk-lnd = { workspace = true, optional = true } cdk-fake-wallet = { workspace = true, optional = true } +cdk-sqlite = { workspace = true, optional = true } clap = { workspace = true, features = ["derive"] } serde.workspace = true thiserror.workspace = true diff --git a/crates/cdk-payment-processor/src/bin/payment_processor.rs b/crates/cdk-payment-processor/src/bin/payment_processor.rs index 0ea98775b..aecfa2506 100644 --- a/crates/cdk-payment-processor/src/bin/payment_processor.rs +++ b/crates/cdk-payment-processor/src/bin/payment_processor.rs @@ -14,6 +14,8 @@ use cdk_common::payment::{self, MintPayment}; use cdk_common::Amount; #[cfg(feature = "fake")] use cdk_fake_wallet::FakeWallet; +#[cfg(feature = "cln")] +use cdk_sqlite::MintSqliteDatabase; use clap::Parser; use serde::{Deserialize, Serialize}; #[cfg(any(feature = "cln", feature = "lnd", feature = "fake"))] @@ -106,7 +108,8 @@ async fn main() -> anyhow::Result<()> { percent_fee_reserve: cln_settings.fee_percent, }; - Arc::new(cdk_cln::Cln::new(cln_settings.rpc_path, fee_reserve).await?) + let kv_store = Arc::new(MintSqliteDatabase::new(":memory:").await?); + Arc::new(cdk_cln::Cln::new(cln_settings.rpc_path, fee_reserve, kv_store).await?) } #[cfg(feature = "fake")] "FAKEWALLET" => { @@ -136,12 +139,14 @@ async fn main() -> anyhow::Result<()> { percent_fee_reserve: lnd_settings.fee_percent, }; + let kv_store = Arc::new(MintSqliteDatabase::new(":memory:").await?); Arc::new( cdk_lnd::Lnd::new( lnd_settings.address, lnd_settings.cert_file, lnd_settings.macaroon_file, fee_reserve, + kv_store, ) .await?, ) diff --git a/crates/cdk/src/mint/builder.rs b/crates/cdk/src/mint/builder.rs index 765ecc9fa..be9ed4c5f 100644 --- a/crates/cdk/src/mint/builder.rs +++ b/crates/cdk/src/mint/builder.rs @@ -4,23 +4,20 @@ use std::collections::HashMap; use std::sync::Arc; use bitcoin::bip32::DerivationPath; -use cdk_common::database::{self, MintDatabase, MintKeysDatabase}; +use cdk_common::database::{DynMintDatabase, MintKeysDatabase}; use cdk_common::error::Error; use cdk_common::nut04::MintMethodOptions; use cdk_common::nut05::MeltMethodOptions; -use cdk_common::payment::Bolt11Settings; +use cdk_common::payment::{Bolt11Settings, DynMintPayment}; #[cfg(feature = "auth")] -use cdk_common::{nut21, nut22}; +use cdk_common::{database::DynMintAuthDatabase, nut21, nut22}; use cdk_signatory::signatory::Signatory; use super::nut17::SupportedMethods; use super::nut19::{self, CachedEndpoint}; -#[cfg(feature = "auth")] -use super::MintAuthDatabase; use super::Nuts; use crate::amount::Amount; use crate::cdk_database; -use crate::cdk_payment::{self, MintPayment}; use crate::mint::Mint; #[cfg(feature = "auth")] use crate::nuts::ProtectedEndpoint; @@ -33,18 +30,17 @@ use crate::types::PaymentProcessorKey; /// Cashu Mint Builder pub struct MintBuilder { mint_info: MintInfo, - localstore: Arc + Send + Sync>, + localstore: DynMintDatabase, #[cfg(feature = "auth")] - auth_localstore: Option + Send + Sync>>, - payment_processors: - HashMap + Send + Sync>>, + auth_localstore: Option, + payment_processors: HashMap, supported_units: HashMap, custom_paths: HashMap, } impl MintBuilder { /// New [`MintBuilder`] - pub fn new(localstore: Arc + Send + Sync>) -> MintBuilder { + pub fn new(localstore: DynMintDatabase) -> MintBuilder { let mint_info = MintInfo { nuts: Nuts::new() .nut07(true) @@ -72,7 +68,7 @@ impl MintBuilder { #[cfg(feature = "auth")] pub fn with_auth( mut self, - auth_localstore: Arc + Send + Sync>, + auth_localstore: DynMintAuthDatabase, openid_discovery: String, client_id: String, protected_endpoints: Vec, @@ -211,7 +207,7 @@ impl MintBuilder { unit: CurrencyUnit, method: PaymentMethod, limits: MintMeltLimits, - payment_processor: Arc + Send + Sync>, + payment_processor: DynMintPayment, ) -> Result<(), Error> { let key = PaymentProcessorKey { unit: unit.clone(), diff --git a/crates/cdk/src/mint/melt.rs b/crates/cdk/src/mint/melt.rs index 40baa4304..014871a5c 100644 --- a/crates/cdk/src/mint/melt.rs +++ b/crates/cdk/src/mint/melt.rs @@ -8,8 +8,8 @@ use cdk_common::melt::MeltQuoteRequest; use cdk_common::mint::MeltPaymentRequest; use cdk_common::nut05::MeltMethodOptions; use cdk_common::payment::{ - Bolt11OutgoingPaymentOptions, Bolt12OutgoingPaymentOptions, OutgoingPaymentOptions, - PaymentIdentifier, + Bolt11OutgoingPaymentOptions, Bolt12OutgoingPaymentOptions, DynMintPayment, + OutgoingPaymentOptions, PaymentIdentifier, }; use cdk_common::quote_id::QuoteId; use cdk_common::{MeltOptions, MeltQuoteBolt12Request}; @@ -23,7 +23,7 @@ use super::{ PaymentMethod, PublicKey, State, }; use crate::amount::to_unit; -use crate::cdk_payment::{MakePaymentResponse, MintPayment}; +use crate::cdk_payment::MakePaymentResponse; use crate::mint::proof_writer::ProofWriter; use crate::mint::verification::Verification; use crate::mint::SigFlag; @@ -586,7 +586,7 @@ impl Mint { use std::sync::Arc; async fn check_payment_state( - ln: Arc + Send + Sync>, + ln: DynMintPayment, lookup_id: &PaymentIdentifier, ) -> anyhow::Result { match ln.check_outgoing_payment(lookup_id).await { diff --git a/crates/cdk/src/mint/mod.rs b/crates/cdk/src/mint/mod.rs index 2918fcbea..df6c52c1a 100644 --- a/crates/cdk/src/mint/mod.rs +++ b/crates/cdk/src/mint/mod.rs @@ -8,10 +8,10 @@ use arc_swap::ArcSwap; use cdk_common::amount::to_unit; use cdk_common::common::{PaymentProcessorKey, QuoteTTL}; #[cfg(feature = "auth")] -use cdk_common::database::MintAuthDatabase; -use cdk_common::database::{self, MintDatabase, MintTransaction}; +use cdk_common::database::DynMintAuthDatabase; +use cdk_common::database::{self, DynMintDatabase, MintTransaction}; use cdk_common::nuts::{self, BlindSignature, BlindedMessage, CurrencyUnit, Id, Kind}; -use cdk_common::payment::WaitPaymentResponse; +use cdk_common::payment::{DynMintPayment, WaitPaymentResponse}; pub use cdk_common::quote_id::QuoteId; use cdk_common::secret; #[cfg(feature = "prometheus")] @@ -25,7 +25,6 @@ use tokio::sync::{Mutex, Notify}; use tokio::task::{JoinHandle, JoinSet}; use tracing::instrument; -use crate::cdk_payment::{self, MintPayment}; use crate::error::Error; use crate::fees::calculate_fee; use crate::nuts::*; @@ -60,13 +59,12 @@ pub struct Mint { /// be a gRPC client to a remote signatory server. signatory: Arc, /// Mint Storage backend - localstore: Arc + Send + Sync>, + localstore: DynMintDatabase, /// Auth Storage backend (only available with auth feature) #[cfg(feature = "auth")] - auth_localstore: Option + Send + Sync>>, + auth_localstore: Option, /// Payment processors for mint - payment_processors: - HashMap + Send + Sync>>, + payment_processors: HashMap, /// Subscription manager pubsub_manager: Arc, #[cfg(feature = "auth")] @@ -91,11 +89,8 @@ impl Mint { pub async fn new( mint_info: MintInfo, signatory: Arc, - localstore: Arc + Send + Sync>, - payment_processors: HashMap< - PaymentProcessorKey, - Arc + Send + Sync>, - >, + localstore: DynMintDatabase, + payment_processors: HashMap, ) -> Result { Self::new_internal( mint_info, @@ -113,12 +108,9 @@ impl Mint { pub async fn new_with_auth( mint_info: MintInfo, signatory: Arc, - localstore: Arc + Send + Sync>, - auth_localstore: Arc + Send + Sync>, - payment_processors: HashMap< - PaymentProcessorKey, - Arc + Send + Sync>, - >, + localstore: DynMintDatabase, + auth_localstore: DynMintAuthDatabase, + payment_processors: HashMap, ) -> Result { Self::new_internal( mint_info, @@ -135,14 +127,9 @@ impl Mint { async fn new_internal( mint_info: MintInfo, signatory: Arc, - localstore: Arc + Send + Sync>, - #[cfg(feature = "auth")] auth_localstore: Option< - Arc + Send + Sync>, - >, - payment_processors: HashMap< - PaymentProcessorKey, - Arc + Send + Sync>, - >, + localstore: DynMintDatabase, + #[cfg(feature = "auth")] auth_localstore: Option, + payment_processors: HashMap, ) -> Result { let keysets = signatory.keysets().await?; if !keysets @@ -361,7 +348,7 @@ impl Mint { &self, unit: CurrencyUnit, payment_method: PaymentMethod, - ) -> Result + Send + Sync>, Error> { + ) -> Result { let key = PaymentProcessorKey::new(unit.clone(), payment_method.clone()); self.payment_processors.get(&key).cloned().ok_or_else(|| { tracing::info!( @@ -374,7 +361,7 @@ impl Mint { } /// Localstore - pub fn localstore(&self) -> Arc + Send + Sync> { + pub fn localstore(&self) -> DynMintDatabase { Arc::clone(&self.localstore) } @@ -451,11 +438,8 @@ impl Mint { /// Once invoice is paid mint quote status is updated #[instrument(skip_all)] async fn wait_for_paid_invoices( - payment_processors: &HashMap< - PaymentProcessorKey, - Arc + Send + Sync>, - >, - localstore: Arc + Send + Sync>, + payment_processors: &HashMap, + localstore: DynMintDatabase, pubsub_manager: Arc, shutdown: Arc, ) -> Result<(), Error> { @@ -527,8 +511,8 @@ impl Mint { /// Handles payment waiting for a single processor #[instrument(skip_all)] async fn wait_for_processor_payments( - processor: Arc + Send + Sync>, - localstore: Arc + Send + Sync>, + processor: DynMintPayment, + localstore: DynMintDatabase, pubsub_manager: Arc, shutdown: Arc, ) -> Result<(), Error> { @@ -570,7 +554,7 @@ impl Mint { /// This is a helper function that can be called with just the required components #[instrument(skip_all)] async fn handle_payment_notification( - localstore: &Arc + Send + Sync>, + localstore: &DynMintDatabase, pubsub_manager: &Arc, wait_payment_response: WaitPaymentResponse, ) -> Result<(), Error> { diff --git a/crates/cdk/src/mint/proof_writer.rs b/crates/cdk/src/mint/proof_writer.rs index a7d184b7c..835fec7fc 100644 --- a/crates/cdk/src/mint/proof_writer.rs +++ b/crates/cdk/src/mint/proof_writer.rs @@ -2,12 +2,11 @@ use std::collections::{HashMap, HashSet}; use std::sync::Arc; -use cdk_common::database::{self, MintDatabase, MintTransaction}; +use cdk_common::database::{self, DynMintDatabase, MintTransaction}; use cdk_common::{Error, Proofs, ProofsMethods, PublicKey, QuoteId, State}; use super::subscription::PubSubManager; -type Db = Arc + Send + Sync>; type Tx<'a, 'b> = Box + Send + Sync + 'b>; /// Proof writer @@ -22,14 +21,14 @@ type Tx<'a, 'b> = Box + Send + Sync + ' /// This struct is not fully ACID. If the process exits due to a panic, and the `Drop` function /// cannot be run, the reset process should reset the state. pub struct ProofWriter { - db: Option, + db: Option, pubsub_manager: Arc, proof_original_states: Option>>, } impl ProofWriter { /// Creates a new ProofWriter on top of the database - pub fn new(db: Db, pubsub_manager: Arc) -> Self { + pub fn new(db: DynMintDatabase, pubsub_manager: Arc) -> Self { Self { db: Some(db), pubsub_manager, @@ -203,7 +202,7 @@ async fn reset_proofs_to_original_state( #[inline(always)] async fn rollback( - db: Arc + Send + Sync>, + db: DynMintDatabase, ys: Vec, original_states: Vec>, ) -> Result<(), Error> { diff --git a/crates/cdk/src/mint/subscription/manager.rs b/crates/cdk/src/mint/subscription/manager.rs index 7b8e26c65..d4c3b9748 100644 --- a/crates/cdk/src/mint/subscription/manager.rs +++ b/crates/cdk/src/mint/subscription/manager.rs @@ -1,8 +1,7 @@ //! Specific Subscription for the cdk crate use std::ops::Deref; -use std::sync::Arc; -use cdk_common::database::{self, MintDatabase}; +use cdk_common::database::DynMintDatabase; use cdk_common::mint::MintQuote; use cdk_common::nut17::Notification; use cdk_common::quote_id::QuoteId; @@ -31,8 +30,8 @@ impl Default for PubSubManager { } } -impl From + Send + Sync>> for PubSubManager { - fn from(val: Arc + Send + Sync>) -> Self { +impl From for PubSubManager { + fn from(val: DynMintDatabase) -> Self { PubSubManager(OnSubscription(Some(val)).into()) } } diff --git a/crates/cdk/src/mint/subscription/on_subscription.rs b/crates/cdk/src/mint/subscription/on_subscription.rs index ed971a4c2..1e331db48 100644 --- a/crates/cdk/src/mint/subscription/on_subscription.rs +++ b/crates/cdk/src/mint/subscription/on_subscription.rs @@ -1,9 +1,8 @@ //! On Subscription //! //! This module contains the code that is triggered when a new subscription is created. -use std::sync::Arc; -use cdk_common::database::{self, MintDatabase}; +use cdk_common::database::DynMintDatabase; use cdk_common::nut17::Notification; use cdk_common::pub_sub::OnNewSubscription; use cdk_common::quote_id::QuoteId; @@ -17,7 +16,7 @@ use crate::nuts::{MeltQuoteBolt11Response, MintQuoteBolt11Response, ProofState, /// This struct triggers code when a new subscription is created. /// /// It is used to send the initial state of the subscription to the client. -pub struct OnSubscription(pub(crate) Option + Send + Sync>>); +pub struct OnSubscription(pub(crate) Option); #[async_trait::async_trait] impl OnNewSubscription for OnSubscription { From 9d25d963ee9ccfd099928cb423aab957fee3bc37 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Tue, 16 Sep 2025 17:25:43 +0100 Subject: [PATCH 158/321] refactor: check mint request (#1079) --- crates/cdk/src/mint/issue/mod.rs | 122 +++++++++++++++++-------------- 1 file changed, 69 insertions(+), 53 deletions(-) diff --git a/crates/cdk/src/mint/issue/mod.rs b/crates/cdk/src/mint/issue/mod.rs index f3965ee33..b4c2689a1 100644 --- a/crates/cdk/src/mint/issue/mod.rs +++ b/crates/cdk/src/mint/issue/mod.rs @@ -44,6 +44,46 @@ impl From for MintQuoteRequest { } } +impl MintQuoteRequest { + /// Get the amount from the mint quote request + /// + /// For Bolt11 requests, this returns `Some(amount)` as the amount is required. + /// For Bolt12 requests, this returns the optional amount. + pub fn amount(&self) -> Option { + match self { + MintQuoteRequest::Bolt11(request) => Some(request.amount), + MintQuoteRequest::Bolt12(request) => request.amount, + } + } + + /// Get the currency unit from the mint quote request + pub fn unit(&self) -> CurrencyUnit { + match self { + MintQuoteRequest::Bolt11(request) => request.unit.clone(), + MintQuoteRequest::Bolt12(request) => request.unit.clone(), + } + } + + /// Get the payment method for the mint quote request + pub fn payment_method(&self) -> PaymentMethod { + match self { + MintQuoteRequest::Bolt11(_) => PaymentMethod::Bolt11, + MintQuoteRequest::Bolt12(_) => PaymentMethod::Bolt12, + } + } + + /// Get the pubkey from the mint quote request + /// + /// For Bolt11 requests, this returns the optional pubkey. + /// For Bolt12 requests, this returns `Some(pubkey)` as the pubkey is required. + pub fn pubkey(&self) -> Option { + match self { + MintQuoteRequest::Bolt11(request) => request.pubkey, + MintQuoteRequest::Bolt12(request) => Some(request.pubkey), + } + } +} + /// Response for a mint quote request /// /// This enum represents the different types of payment responses that can be returned @@ -121,22 +161,19 @@ impl Mint { /// - The currency unit is supported /// - The amount (if provided) is within the allowed range for the payment method /// - /// # Arguments - /// * `amount` - Optional amount to validate - /// * `unit` - Currency unit for the request - /// * `payment_method` - Payment method (Bolt11, Bolt12, etc.) - /// /// # Returns /// * `Ok(())` if the request is acceptable /// * `Error` if any validation fails pub async fn check_mint_request_acceptable( &self, - amount: Option, - unit: &CurrencyUnit, - payment_method: &PaymentMethod, + mint_quote_request: &MintQuoteRequest, ) -> Result<(), Error> { let mint_info = self.localstore.get_mint_info().await?; + let unit = mint_quote_request.unit(); + let amount = mint_quote_request.amount(); + let payment_method = mint_quote_request.payment_method(); + let nut04 = &mint_info.nuts.nut04; ensure_cdk!(!nut04.disabled, Error::MintingDisabled); @@ -145,7 +182,7 @@ impl Mint { ensure_cdk!(!disabled, Error::MintingDisabled); let settings = nut04 - .get_settings(unit, payment_method) + .get_settings(&unit, &payment_method) .ok_or(Error::UnsupportedUnit)?; let min_amount = settings.min_amount; @@ -193,27 +230,22 @@ impl Mint { METRICS.inc_in_flight_requests("get_mint_quote"); let result = async { - let unit: CurrencyUnit; - let amount; - let pubkey; - let payment_method; + // Use the new getters for cleaner code + let unit = mint_quote_request.unit(); + let amount = mint_quote_request.amount(); + let payment_method = mint_quote_request.payment_method(); - let create_invoice_response = match mint_quote_request { - MintQuoteRequest::Bolt11(bolt11_request) => { - unit = bolt11_request.unit; - amount = Some(bolt11_request.amount); - pubkey = bolt11_request.pubkey; - payment_method = PaymentMethod::Bolt11; - - self.check_mint_request_acceptable( - Some(bolt11_request.amount), - &unit, - &payment_method, - ) - .await?; + // Validate the request before processing + self.check_mint_request_acceptable(&mint_quote_request) + .await?; + + // Extract pubkey using the getter + let pubkey = mint_quote_request.pubkey(); - let ln = self.get_payment_processor(unit.clone(), PaymentMethod::Bolt11)?; + let ln = self.get_payment_processor(unit.clone(), payment_method.clone())?; + let payment_options = match mint_quote_request { + MintQuoteRequest::Bolt11(bolt11_request) => { let mint_ttl = self.localstore.get_quote_ttl().await?.mint_ttl; let quote_expiry = unix_time() + mint_ttl; @@ -234,26 +266,9 @@ impl Mint { unix_expiry: Some(quote_expiry), }; - let incoming_options = IncomingPaymentOptions::Bolt11(bolt11_options); - - ln.create_incoming_payment_request(&unit, incoming_options) - .await - .map_err(|err| { - tracing::error!("Could not create invoice: {}", err); - Error::InvalidPaymentRequest - })? + IncomingPaymentOptions::Bolt11(bolt11_options) } MintQuoteRequest::Bolt12(bolt12_request) => { - unit = bolt12_request.unit; - amount = bolt12_request.amount; - pubkey = Some(bolt12_request.pubkey); - payment_method = PaymentMethod::Bolt12; - - self.check_mint_request_acceptable(amount, &unit, &payment_method) - .await?; - - let ln = self.get_payment_processor(unit.clone(), payment_method.clone())?; - let description = bolt12_request.description; let bolt12_options = Bolt12IncomingPaymentOptions { @@ -262,17 +277,18 @@ impl Mint { unix_expiry: None, }; - let incoming_options = IncomingPaymentOptions::Bolt12(Box::new(bolt12_options)); - - ln.create_incoming_payment_request(&unit, incoming_options) - .await - .map_err(|err| { - tracing::error!("Could not create invoice: {}", err); - Error::InvalidPaymentRequest - })? + IncomingPaymentOptions::Bolt12(Box::new(bolt12_options)) } }; + let create_invoice_response = ln + .create_incoming_payment_request(&unit, payment_options) + .await + .map_err(|err| { + tracing::error!("Could not create invoice: {}", err); + Error::InvalidPaymentRequest + })?; + let quote = MintQuote::new( None, create_invoice_response.request.to_string(), From 049ce64462d3a4635a1c0a95d769b8f6da188fb8 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Tue, 16 Sep 2025 17:26:19 +0100 Subject: [PATCH 159/321] feat(cdk): add amount_mintable method and improve mint quote validation (#1075) * feat(cdk): add amount_mintable method and improve mint quote validation - Add MintQuote::amount_mintable() method to calculate available mint amount - Update mint issue logic to use centralized amount calculation - Add validation for Bolt11 payment amounts matching quote amounts - Improve error handling and logging for quote amount mismatches --- crates/cdk-common/src/mint.rs | 10 ++++ crates/cdk-fake-wallet/src/lib.rs | 86 ++++++++++++++----------------- crates/cdk/src/mint/issue/mod.rs | 18 +++++-- crates/cdk/src/mint/mod.rs | 7 +++ 4 files changed, 71 insertions(+), 50 deletions(-) diff --git a/crates/cdk-common/src/mint.rs b/crates/cdk-common/src/mint.rs index a6d3d91e8..f75cf1205 100644 --- a/crates/cdk-common/src/mint.rs +++ b/crates/cdk-common/src/mint.rs @@ -139,6 +139,16 @@ impl MintQuote { self.payments.iter().map(|a| &a.payment_id).collect() } + /// Amount mintable + /// Returns the amount that is still available for minting. + /// + /// The value is computed as the difference between the total amount that + /// has been paid for this issuance (`self.amount_paid`) and the amount + /// that has already been issued (`self.amount_issued`). In other words, + pub fn amount_mintable(&self) -> Amount { + self.amount_paid - self.amount_issued + } + /// Add a payment ID to the list of payment IDs /// /// Returns an error if the payment ID is already in the list diff --git a/crates/cdk-fake-wallet/src/lib.rs b/crates/cdk-fake-wallet/src/lib.rs index a5b0f344c..58630d143 100644 --- a/crates/cdk-fake-wallet/src/lib.rs +++ b/crates/cdk-fake-wallet/src/lib.rs @@ -55,19 +55,22 @@ const DEFAULT_REPAY_QUEUE_MAX_SIZE: usize = 100; struct SecondaryRepaymentQueue { queue: Arc>>, max_size: usize, - sender: tokio::sync::mpsc::Sender<(PaymentIdentifier, Amount, String)>, + sender: tokio::sync::mpsc::Sender, + unit: CurrencyUnit, } impl SecondaryRepaymentQueue { fn new( max_size: usize, - sender: tokio::sync::mpsc::Sender<(PaymentIdentifier, Amount, String)>, + sender: tokio::sync::mpsc::Sender, + unit: CurrencyUnit, ) -> Self { let queue = Arc::new(Mutex::new(VecDeque::new())); let repayment_queue = Self { queue: queue.clone(), max_size, sender, + unit, }; // Start the background secondary repayment processor @@ -101,6 +104,7 @@ impl SecondaryRepaymentQueue { fn start_secondary_repayment_processor(&self) { let queue = self.queue.clone(); let sender = self.sender.clone(); + let unit = self.unit.clone(); tokio::spawn(async move { use bitcoin::secp256k1::rand::rngs::OsRng; @@ -127,7 +131,13 @@ impl SecondaryRepaymentQueue { if let Some(payment) = payment_to_process { // Generate a random amount for this secondary payment (same range as initial payment: 1-1000) let random_amount: u64 = rng.gen_range(1..=1000); - let secondary_amount = Amount::from(random_amount); + + // Create amount based on unit, ensuring minimum of 1 sat worth + let secondary_amount = match &unit { + CurrencyUnit::Sat => Amount::from(random_amount), + CurrencyUnit::Msat => Amount::from(u64::max(random_amount * 1000, 1000)), + _ => Amount::from(u64::max(random_amount, 1)), // fallback + }; // Generate a unique payment identifier for this secondary payment // We'll create a new payment hash by appending a timestamp and random bytes @@ -157,14 +167,14 @@ impl SecondaryRepaymentQueue { // Send the payment notification using the original payment identifier // The mint will process this through the normal payment stream - if let Err(e) = sender - .send(( - payment.clone(), - secondary_amount, - unique_payment_id.to_string(), - )) - .await - { + let secondary_response = WaitPaymentResponse { + payment_identifier: payment.clone(), + payment_amount: secondary_amount, + unit: unit.clone(), + payment_id: unique_payment_id.to_string(), + }; + + if let Err(e) = sender.send(secondary_response).await { tracing::error!( "Failed to send secondary repayment notification for {:?}: {}", unique_payment_id, @@ -181,10 +191,8 @@ impl SecondaryRepaymentQueue { #[derive(Clone)] pub struct FakeWallet { fee_reserve: FeeReserve, - #[allow(clippy::type_complexity)] - sender: tokio::sync::mpsc::Sender<(PaymentIdentifier, Amount, String)>, - #[allow(clippy::type_complexity)] - receiver: Arc>>>, + sender: tokio::sync::mpsc::Sender, + receiver: Arc>>>, payment_states: Arc>>, failed_payment_check: Arc>>, payment_delay: u64, @@ -227,7 +235,7 @@ impl FakeWallet { let incoming_payments = Arc::new(RwLock::new(HashMap::new())); let secondary_repayment_queue = - SecondaryRepaymentQueue::new(repay_queue_max_size, sender.clone()); + SecondaryRepaymentQueue::new(repay_queue_max_size, sender.clone(), unit.clone()); Self { fee_reserve, @@ -306,19 +314,10 @@ impl MintPayment for FakeWallet { .take() .ok_or(Error::NoReceiver) .unwrap(); - let unit = self.unit.clone(); let receiver_stream = ReceiverStream::new(receiver); - Ok(Box::pin(receiver_stream.map( - move |(request_lookup_id, payment_amount, payment_id)| { - let wait_response = WaitPaymentResponse { - payment_identifier: request_lookup_id.clone(), - payment_amount, - unit: unit.clone(), - payment_id, - }; - Event::PaymentReceived(wait_response) - }, - ))) + Ok(Box::pin(receiver_stream.map(move |wait_response| { + Event::PaymentReceived(wait_response) + }))) } #[instrument(skip_all)] @@ -517,16 +516,18 @@ impl MintPayment for FakeWallet { } IncomingPaymentOptions::Bolt11(bolt11_options) => { let description = bolt11_options.description.unwrap_or_default(); - let amount = if unit == &CurrencyUnit::Sat { - to_unit(bolt11_options.amount, unit, &CurrencyUnit::Msat) - .unwrap_or(bolt11_options.amount * Amount::from(1000)) + let amount = bolt11_options.amount; + let expiry = bolt11_options.unix_expiry; + + // For fake invoices, always use msats regardless of unit + let amount_msat = if unit == &CurrencyUnit::Sat { + u64::from(amount) * 1000 } else { - bolt11_options.amount + // If unit is Msat, use as-is + u64::from(amount) }; - let expiry = bolt11_options.unix_expiry; - // Since this is fake we just use the amount no matter the unit to create an invoice - let invoice = create_fake_invoice(amount.into(), description.clone()); + let invoice = create_fake_invoice(amount_msat, description.clone()); let payment_hash = invoice.payment_hash(); ( @@ -550,8 +551,9 @@ impl MintPayment for FakeWallet { use bitcoin::secp256k1::rand::rngs::OsRng; use bitcoin::secp256k1::rand::Rng; let mut rng = OsRng; - let random_amount: u64 = rng.gen_range(1..=1000); - random_amount.into() + let random_amount: u64 = rng.gen_range(1000..=10000); + // Use the same unit as the wallet for any-amount invoices + Amount::from(random_amount) } else { amount }; @@ -574,15 +576,7 @@ impl MintPayment for FakeWallet { .push(response.clone()); // Send the message after waiting for the specified duration - if sender - .send(( - payment_hash_clone.clone(), - final_amount, - payment_hash_clone.to_string(), - )) - .await - .is_err() - { + if sender.send(response.clone()).await.is_err() { tracing::error!("Failed to send label: {:?}", payment_hash_clone); } }); diff --git a/crates/cdk/src/mint/issue/mod.rs b/crates/cdk/src/mint/issue/mod.rs index b4c2689a1..14e8ce9f8 100644 --- a/crates/cdk/src/mint/issue/mod.rs +++ b/crates/cdk/src/mint/issue/mod.rs @@ -624,17 +624,27 @@ impl Mint { } let mint_amount = match mint_quote.payment_method { - PaymentMethod::Bolt11 => mint_quote.amount.ok_or(Error::AmountUndefined)?, + PaymentMethod::Bolt11 => { + let quote_amount = mint_quote.amount.ok_or(Error::AmountUndefined)?; + + if quote_amount != mint_quote.amount_mintable() { + tracing::error!("The quote amount {} does not equal the amount paid {}.", quote_amount, mint_quote.amount_mintable()); + return Err(Error::IncorrectQuoteAmount); + } + + quote_amount + }, PaymentMethod::Bolt12 => { - if mint_quote.amount_issued() > mint_quote.amount_paid() { + if mint_quote.amount_mintable() == Amount::ZERO{ tracing::error!( - "Quote state should not be issued if issued {} is > paid {}.", + "Quote state should not be issued if issued {} is => paid {}.", mint_quote.amount_issued(), mint_quote.amount_paid() ); return Err(Error::UnpaidQuote); } - mint_quote.amount_paid() - mint_quote.amount_issued() + + mint_quote.amount_mintable() } _ => return Err(Error::UnsupportedPaymentMethod), }; diff --git a/crates/cdk/src/mint/mod.rs b/crates/cdk/src/mint/mod.rs index df6c52c1a..4b429ca18 100644 --- a/crates/cdk/src/mint/mod.rs +++ b/crates/cdk/src/mint/mod.rs @@ -627,6 +627,13 @@ impl Mint { return Err(Error::AmountUndefined); } + if mint_quote.payment_method == PaymentMethod::Bolt11 + && mint_quote.amount != Some(payment_amount_quote_unit) + { + tracing::error!("Bolt11 incoming payment should equal mint quote."); + return Err(Error::IncorrectQuoteAmount); + } + tracing::debug!( "Payment received amount in quote unit {} {}", mint_quote.unit, From c64797ac6f43016f0378a7d851e46c4771055525 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Wed, 17 Sep 2025 09:32:22 +0100 Subject: [PATCH 160/321] chore: some docs (#1083) --- README.md | 16 --- crates/cdk-cli/README.md | 181 ++++++++++++++++++++++++++- crates/cdk-mintd/README.md | 244 ++++++++++++++++++++++--------------- 3 files changed, 325 insertions(+), 116 deletions(-) diff --git a/README.md b/README.md index d1db92c7c..ae01fc79f 100644 --- a/README.md +++ b/README.md @@ -36,22 +36,6 @@ The project is split up into several crates in the `crates/` directory: For a guide to settings up a development environment see [DEVELOPMENT.md](./DEVELOPMENT.md) -## LDK Node Network Configuration - -For detailed configuration examples for running CDK with LDK Node on different Bitcoin networks (Mutinynet, Testnet, Mainnet), see [LDK Node Network Guide](./crates/cdk-ldk-node/NETWORK_GUIDE.md). - -**Quick Start with Mutinynet (Recommended for Testing):** -```toml -[ln] -ln_backend = "ldk-node" - -[ldk_node] -bitcoin_network = "signet" -esplora_url = "https://mutinynet.com/api" -rgs_url = "https://rgs.mutinynet.com/snapshot/0" -gossip_source_type = "rgs" -``` - ## Implemented [NUTs](https://github.com/cashubtc/nuts/): ### Mandatory diff --git a/crates/cdk-cli/README.md b/crates/cdk-cli/README.md index 169a47203..bdd21e5f3 100644 --- a/crates/cdk-cli/README.md +++ b/crates/cdk-cli/README.md @@ -1,14 +1,189 @@ +# CDK CLI + +[![crates.io](https://img.shields.io/crates/v/cdk-cli.svg)](https://crates.io/crates/cdk-cli) +[![Documentation](https://docs.rs/cdk-cli/badge.svg)](https://docs.rs/cdk-cli) +[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/cashubtc/cdk/blob/main/LICENSE) + > **Warning** > This project is in early development, it does however work with real sats! Always use amounts you don't mind losing. -cdk-cli is a CLI wallet implementation using of CDK(../cdk) +A command-line Cashu wallet implementation built with the Cashu Development Kit (CDK). This tool allows you to interact with Cashu mints from the terminal, performing operations like minting, melting, and transferring ecash tokens. + +## Features + +- **Multiple Mint Support**: Connect to and manage multiple Cashu mints +- **Token Operations**: Mint, melt, send, and receive Cashu tokens +- **Wallet Management**: Create and manage multiple wallets +- **Lightning Integration**: Pay Lightning invoices and receive payments +- **Token Storage**: Secure local storage of tokens and mint configurations + +## Installation + +### Option 1: Download Pre-built Binary +Download the latest release from the [GitHub releases page](https://github.com/cashubtc/cdk/releases). + +### Option 2: Build from Source +```bash +git clone https://github.com/cashubtc/cdk.git +cd cdk +cargo build --bin cdk-cli --release +# Binary will be at ./target/release/cdk-cli +``` + +## Quick Start + +### 1. Add a Mint +```bash +# Add a mint (use a real mint URL or start your own with cdk-mintd) +cdk-cli wallet add-mint http://127.0.0.1:8085 +``` + +### 2. Mint Tokens +```bash +# Create a mint quote for 100 sats +cdk-cli wallet mint-quote 100 + +# Pay the Lightning invoice shown, then mint the tokens +cdk-cli wallet mint +``` + +### 3. Send Tokens +```bash +# Send 50 sats as a token +cdk-cli wallet send 50 +``` + +### 4. Receive Tokens +```bash +# Receive a token from someone else +cdk-cli wallet receive +``` + +### 5. Check Balance +```bash +# View your current balance +cdk-cli wallet balance +``` + +## Basic Usage + +### Wallet Operations +```bash +# List all wallets +cdk-cli wallet list + +# Create a new wallet +cdk-cli wallet new --name my-wallet + +# Set default wallet +cdk-cli wallet set-default my-wallet + +# Show wallet info +cdk-cli wallet info +``` + +### Mint Management +```bash +# List connected mints +cdk-cli wallet list-mints + +# Remove a mint +cdk-cli wallet remove-mint + +# Get mint information +cdk-cli wallet mint-info +``` + +### Payment Operations +```bash +# Pay a Lightning invoice +cdk-cli wallet pay-invoice + +# Create melt quote for an invoice +cdk-cli wallet melt-quote + +# Execute the melt +cdk-cli wallet melt +``` + +### Token Management +```bash +# List all tokens +cdk-cli wallet list-tokens + +# Check token states +cdk-cli wallet check-tokens + +# Restore wallet from seed +cdk-cli wallet restore --seed +``` + +## Configuration + +The CLI stores its configuration and wallet data in: +- **Linux/macOS**: `~/.config/cdk-cli/` +- **Windows**: `%APPDATA%\cdk-cli\` + +## Examples + +### Complete Workflow Example +```bash +# 1. Start a test mint (in another terminal) +cdk-mintd + +# 2. Add the mint +cdk-cli wallet add-mint http://127.0.0.1:8085 + +# 3. Create a mint quote +cdk-cli wallet mint-quote 1000 + +# 4. Pay the Lightning invoice (if using real Lightning backend) +# or wait a few seconds if using fake wallet + +# 5. Mint the tokens +cdk-cli wallet mint + +# 6. Check balance +cdk-cli wallet balance + +# 7. Send some tokens +cdk-cli wallet send 100 + +# 8. The recipient can receive with: +cdk-cli wallet receive +``` + +### Working with Multiple Wallets +```bash +# Create wallets for different purposes +cdk-cli wallet new --name savings +cdk-cli wallet new --name daily + +# Switch between wallets +cdk-cli wallet set-default savings +cdk-cli wallet balance + +cdk-cli wallet set-default daily +cdk-cli wallet balance +``` + +## Help and Documentation + +```bash +# General help +cdk-cli --help + +# Help for specific commands +cdk-cli wallet --help +cdk-cli wallet mint-quote --help +``` ## License -Code is under the [MIT](../../LICENSE) +Code is under the [MIT License](../../LICENSE) ## Contribution -All contributions welcome. +All contributions are welcome. Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, shall be licensed as above, without any additional terms or conditions. diff --git a/crates/cdk-mintd/README.md b/crates/cdk-mintd/README.md index 55acaad41..cb85482f3 100644 --- a/crates/cdk-mintd/README.md +++ b/crates/cdk-mintd/README.md @@ -4,176 +4,226 @@ [![Documentation](https://docs.rs/cdk-mintd/badge.svg)](https://docs.rs/cdk-mintd) [![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/cashubtc/cdk/blob/main/LICENSE) -**ALPHA** This library is in early development, the API will change and should be used with caution. +> **Warning** +> This project is in early development, it does however work with real sats! Always use amounts you don't mind losing. Cashu mint daemon implementation for the Cashu Development Kit (CDK). This binary provides a complete Cashu mint server implementation with support for multiple database backends and Lightning Network integrations. ## Features -- **Multiple Database Backends**: SQLite and PostgreSQL -- **Lightning Network Integration**: Support for CLN, LND, LNbits, and test backends +- **Multiple Database Backends**: SQLite, PostgreSQL, and ReDB +- **Lightning Network Integration**: Support for CLN, LND, LNbits, LDK Node, and test backends - **Authentication**: Optional user authentication with OpenID Connect - **Management RPC**: gRPC interface for mint management - **Docker Support**: Ready-to-use Docker configurations ## Installation -From crates.io: -```bash -cargo install cdk-mintd -``` +### Option 1: Download Pre-built Binary +Download the latest release from the [GitHub releases page](https://github.com/cashubtc/cdk/releases). -From source: +### Option 2: Build from Source ```bash -cargo install --path . +git clone https://github.com/cashubtc/cdk.git +cd cdk +cargo build --bin cdk-mintd --release +# Binary will be at ./target/release/cdk-mintd ``` ## Quick Start -### Using SQLite (Default) -```bash -# Start with SQLite (no additional setup required) -cdk-mintd -``` +The fastest way to get started for testing: -### Using PostgreSQL ```bash -# Set environment variables -export CDK_MINTD_DATABASE=postgres -export CDK_MINTD_DATABASE_URL="postgresql://postgres:password@localhost:5432/cdk_mint" +# Create working directory and copy example config +mkdir -p ~/.cdk-mintd +cp example.config.toml ~/.cdk-mintd/config.toml -# Start the mint +# Start the mint (uses SQLite + fake wallet by default) cdk-mintd ``` -### Using Docker +The mint will be available at `http://127.0.0.1:8085`. Test it with: ```bash -# SQLite -docker-compose up - -# PostgreSQL -docker-compose -f docker-compose.postgres.yaml up +curl http://127.0.0.1:8085/v1/info ``` ## Configuration -The mint can be configured through environment variables or a configuration file. See `example.config.toml` for all available options. +> **Important**: You must create the working directory and configuration file before starting the mint. The mint does not create them automatically. -### Database Configuration +### Setup Steps -#### SQLite (Default) -```toml -[database] -engine = "sqlite" +1. **Create working directory**: + ```bash + mkdir -p ~/.cdk-mintd + ``` + +2. **Create configuration file**: + ```bash + # Copy and customize the example config + cp example.config.toml ~/.cdk-mintd/config.toml + # Edit ~/.cdk-mintd/config.toml with your settings + ``` + +3. **Start the mint**: + ```bash + cdk-mintd # Uses ~/.cdk-mintd/config.toml automatically + ``` + +### Configuration File Locations (in order of precedence) + +1. **Explicit path**: `cdk-mintd --config /path/to/config.toml` +2. **Working directory**: `./config.toml` (in current directory) +3. **Default location**: `~/.cdk-mintd/config.toml` +4. **Environment variables**: All config options can be set via environment variables + +### Alternative Setup Methods + +**Custom working directory**: +```bash +mkdir -p /my/custom/path +cp example.config.toml /my/custom/path/config.toml +cdk-mintd --work-dir /my/custom/path ``` -#### PostgreSQL -```toml -[database] -engine = "postgres" +**Environment variables only**: +```bash +export CDK_MINTD_LISTEN_PORT=3000 +export CDK_MINTD_LN_BACKEND=fakewallet +export CDK_MINTD_DATABASE=sqlite +cdk-mintd ``` -Set `CDK_MINTD_DATABASE_URL` environment variable for connection string. -#### ReDB +## Production Examples + +### With LDK Node (Recommended for Testing) ```toml -[database] -engine = "redb" +[ln] +ln_backend = "ldk-node" + +[ldk_node] +bitcoin_network = "signet" # Use "mainnet" for production +esplora_url = "https://mutinynet.com/api" +rgs_url = "https://rgs.mutinynet.com/snapshot/0" +gossip_source_type = "rgs" +storage_dir_path = "/var/lib/cdk-mintd/ldk-node" ``` -### Lightning Backend Configuration +### With CLN Lightning Backend ```toml [ln] -ln_backend = "fakewallet" # Options: cln, lnd, lnbits, fakewallet -``` +ln_backend = "cln" -### Logging Configuration +[cln] +rpc_path = "/home/bitcoin/.lightning/bitcoin/lightning-rpc" +fee_percent = 0.01 +reserve_fee_min = 10 +``` -You can configure where mintd outputs its logs using the `[info.logging]` section in your config file or environment variables: +### With LND Lightning Backend +```toml +[ln] +ln_backend = "lnd" + +[lnd] +address = "https://localhost:10009" +macaroon_file = "/home/bitcoin/.lnd/data/chain/bitcoin/mainnet/admin.macaroon" +cert_file = "/home/bitcoin/.lnd/tls.cert" +fee_percent = 0.01 +reserve_fee_min = 10 +``` -**Config file:** +### With PostgreSQL Database ```toml -[info.logging] -# Where to output logs: "stdout", "file", or "both" (default: "both") -output = "both" -# Log level for console output (default: "info") -console_level = "info" -# Log level for file output (default: "debug") -file_level = "debug" +[database] +engine = "postgres" + +[database.postgres] +url = "postgresql://mint_user:password@localhost:5432/cdk_mint" ``` -**Environment variables:** -```bash -# Where to output logs: "stdout", "file", or "both" (default: "both") -export CDK_MINTD_LOGGING_OUTPUT="both" -# Log level for console output (default: "info") -export CDK_MINTD_LOGGING_CONSOLE_LEVEL="debug" -# Log level for file output (default: "debug") -export CDK_MINTD_LOGGING_FILE_LEVEL="debug" +## Directory Structure + +After setup and first run, your directory will look like: + +``` +~/.cdk-mintd/ # Working directory (create manually) +├── config.toml # Config file (create manually) +├── cdk-mintd.db # SQLite database (created automatically) +├── logs/ # Log files (created automatically if enabled) +│ ├── cdk-mintd.2024-01-01.log +│ └── cdk-mintd.2024-01-02.log +└── ldk-node/ # LDK Node data (if using LDK backend) + ├── wallet/ + └── graph/ ``` -**Available logging outputs:** -- `"stdout"` - Output logs only to console/terminal (stderr) -- `"file"` - Output logs only to rotating daily log files in `/logs/` -- `"both"` - Output logs to both console and files (default behavior) +**What you must create manually:** +- Working directory (e.g., `~/.cdk-mintd/`) +- Config file (`config.toml`) -**Available log levels:** `error`, `warn`, `info`, `debug`, `trace` +**What gets created automatically:** +- Database files +- Log directories and files +- Lightning backend data directories -**Examples:** +## Testing Your Mint -Console only with debug level: -```bash -export CDK_MINTD_LOGGING_OUTPUT="stdout" -export CDK_MINTD_LOGGING_CONSOLE_LEVEL="debug" -``` +1. **Verify the mint is running**: + ```bash + curl http://127.0.0.1:8085/v1/info + ``` -File only with debug level: -```toml -[info.logging] -output = "file" -file_level = "debug" -``` +2. **Get mint keys**: + ```bash + curl http://127.0.0.1:8085/v1/keys + ``` -Both console (warn) and file (debug): -```bash -export CDK_MINTD_LOGGING_OUTPUT="both" -export CDK_MINTD_LOGGING_CONSOLE_LEVEL="warn" -export CDK_MINTD_LOGGING_FILE_LEVEL="debug" -``` +3. **Test with CDK CLI wallet**: + ```bash + # Download from: https://github.com/cashubtc/cdk/releases + cdk-cli wallet add-mint http://127.0.0.1:8085 + cdk-cli wallet mint-quote 100 + ``` + +4. **For LDK Node backend**: Access the management interface at -## Usage +## Command Line Usage ```bash -# Start the mint with default configuration +# Start with default configuration cdk-mintd # Start with custom config file cdk-mintd --config /path/to/config.toml -# Start with specific work directory +# Start with custom working directory cdk-mintd --work-dir /path/to/work/dir -# Disable logging entirely + +# Disable logging cdk-mintd --enable-logging false # Show help cdk-mintd --help ``` -## Environment Variables +## Key Environment Variables -Key environment variables: - -- `CDK_MINTD_DATABASE`: Database engine (sqlite/postgres/redb) +- `CDK_MINTD_DATABASE`: Database engine (`sqlite`/`postgres`/`redb`) - `CDK_MINTD_DATABASE_URL`: PostgreSQL connection string -- `CDK_MINTD_LN_BACKEND`: Lightning backend type -- `CDK_MINTD_LISTEN_HOST`: Host to bind to -- `CDK_MINTD_LISTEN_PORT`: Port to bind to +- `CDK_MINTD_LN_BACKEND`: Lightning backend (`cln`/`lnd`/`lnbits`/`ldk-node`/`fakewallet`) +- `CDK_MINTD_LISTEN_HOST`: Host to bind to (default: `127.0.0.1`) +- `CDK_MINTD_LISTEN_PORT`: Port to bind to (default: `8085`) + +For complete configuration options, see the [example configuration file](./example.config.toml). ## Documentation -- [Configuration Examples](./example.config.toml) -- [PostgreSQL Setup Guide](../../POSTGRES.md) -- [Development Guide](../../DEVELOPMENT.md) +- **[Configuration Examples](./example.config.toml)** - Complete configuration reference +- **[PostgreSQL Setup Guide](../../POSTGRES.md)** - Database setup instructions +- **[Development Guide](../../DEVELOPMENT.md)** - Contributing and development setup ## License From 62fcb1730e3e05aad71422847ac2c719713d7d6f Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Wed, 17 Sep 2025 09:33:54 +0100 Subject: [PATCH 161/321] chore: remove mintd quick start --- crates/cdk-mintd/README.md | 18 ------------------ 1 file changed, 18 deletions(-) diff --git a/crates/cdk-mintd/README.md b/crates/cdk-mintd/README.md index cb85482f3..e72149f19 100644 --- a/crates/cdk-mintd/README.md +++ b/crates/cdk-mintd/README.md @@ -30,24 +30,6 @@ cargo build --bin cdk-mintd --release # Binary will be at ./target/release/cdk-mintd ``` -## Quick Start - -The fastest way to get started for testing: - -```bash -# Create working directory and copy example config -mkdir -p ~/.cdk-mintd -cp example.config.toml ~/.cdk-mintd/config.toml - -# Start the mint (uses SQLite + fake wallet by default) -cdk-mintd -``` - -The mint will be available at `http://127.0.0.1:8085`. Test it with: -```bash -curl http://127.0.0.1:8085/v1/info -``` - ## Configuration > **Important**: You must create the working directory and configuration file before starting the mint. The mint does not create them automatically. From 23cba67c3b46aa09f7150eef408aba1476ccb880 Mon Sep 17 00:00:00 2001 From: David Caseria Date: Wed, 17 Sep 2025 12:27:54 -0400 Subject: [PATCH 162/321] MultiMintWallet Refactor (#1001) --- crates/cdk-cli/src/main.rs | 79 +- crates/cdk-cli/src/sub_commands/balance.rs | 19 +- crates/cdk-cli/src/sub_commands/burn.rs | 13 +- .../src/sub_commands/cat_device_login.rs | 20 +- crates/cdk-cli/src/sub_commands/cat_login.rs | 21 +- .../src/sub_commands/create_request.rs | 5 +- crates/cdk-cli/src/sub_commands/melt.rs | 473 +++--- crates/cdk-cli/src/sub_commands/mint.rs | 8 +- .../src/sub_commands/mint_blind_auth.rs | 21 +- crates/cdk-cli/src/sub_commands/mod.rs | 1 + .../cdk-cli/src/sub_commands/pending_mints.rs | 6 +- crates/cdk-cli/src/sub_commands/receive.rs | 57 +- crates/cdk-cli/src/sub_commands/restore.rs | 20 +- crates/cdk-cli/src/sub_commands/send.rs | 143 +- crates/cdk-cli/src/sub_commands/transfer.rs | 209 +++ .../src/sub_commands/update_mint_url.rs | 7 +- crates/cdk-cli/src/utils.rs | 69 +- crates/cdk-common/src/error.rs | 26 + crates/cdk-ffi/src/lib.rs | 2 + crates/cdk-ffi/src/multi_mint_wallet.rs | 416 +++++ crates/cdk/src/wallet/builder.rs | 6 + crates/cdk/src/wallet/mod.rs | 2 +- crates/cdk/src/wallet/multi_mint_wallet.rs | 1395 +++++++++++++++-- crates/cdk/src/wallet/payment_request.rs | 10 +- 24 files changed, 2371 insertions(+), 657 deletions(-) create mode 100644 crates/cdk-cli/src/sub_commands/transfer.rs create mode 100644 crates/cdk-ffi/src/multi_mint_wallet.rs diff --git a/crates/cdk-cli/src/main.rs b/crates/cdk-cli/src/main.rs index 32a1c3ea7..2d3bbfa1b 100644 --- a/crates/cdk-cli/src/main.rs +++ b/crates/cdk-cli/src/main.rs @@ -9,7 +9,7 @@ use bip39::Mnemonic; use cdk::cdk_database; use cdk::cdk_database::WalletDatabase; use cdk::nuts::CurrencyUnit; -use cdk::wallet::{HttpClient, MultiMintWallet, Wallet, WalletBuilder}; +use cdk::wallet::MultiMintWallet; #[cfg(feature = "redb")] use cdk_redb::WalletRedbDatabase; use cdk_sqlite::WalletSqliteDatabase; @@ -49,6 +49,9 @@ struct Cli { /// NWS Proxy #[arg(short, long)] proxy: Option, + /// Currency unit to use for the wallet + #[arg(short, long, default_value = "sat")] + unit: String, #[command(subcommand)] command: Commands, } @@ -67,6 +70,8 @@ enum Commands { Receive(sub_commands::receive::ReceiveSubCommand), /// Send Send(sub_commands::send::SendSubCommand), + /// Transfer tokens between mints + Transfer(sub_commands::transfer::TransferSubCommand), /// Reclaim pending proofs that are no longer pending CheckPending, /// View mint info @@ -168,62 +173,25 @@ async fn main() -> Result<()> { }; let seed = mnemonic.to_seed_normalized(""); - let mut wallets: Vec = Vec::new(); + // Parse currency unit from args + let currency_unit = CurrencyUnit::from_str(&args.unit) + .unwrap_or_else(|_| CurrencyUnit::Custom(args.unit.clone())); - let mints = localstore.get_mints().await?; - - for (mint_url, mint_info) in mints { - let units = if let Some(mint_info) = mint_info { - mint_info.supported_units().into_iter().cloned().collect() - } else { - vec![CurrencyUnit::Sat] - }; - - let proxy_client = if let Some(proxy_url) = args.proxy.as_ref() { - Some(HttpClient::with_proxy( - mint_url.clone(), + // Create MultiMintWallet with specified currency unit + // The constructor will automatically load wallets for this currency unit + let multi_mint_wallet = match &args.proxy { + Some(proxy_url) => { + // Create MultiMintWallet with proxy configuration + MultiMintWallet::new_with_proxy( + localstore.clone(), + seed, + currency_unit.clone(), proxy_url.clone(), - None, - true, - )?) - } else { - None - }; - - let seed = mnemonic.to_seed_normalized(""); - - for unit in units { - let mint_url_clone = mint_url.clone(); - let mut builder = WalletBuilder::new() - .mint_url(mint_url_clone.clone()) - .unit(unit) - .localstore(localstore.clone()) - .seed(seed); - - if let Some(http_client) = &proxy_client { - builder = builder.client(http_client.clone()); - } - - let wallet = builder.build()?; - - let wallet_clone = wallet.clone(); - - tokio::spawn(async move { - // We refresh keysets, this internally gets mint info - if let Err(err) = wallet_clone.refresh_keysets().await { - tracing::error!( - "Could not get mint quote for {}, {}", - wallet_clone.mint_url, - err - ); - } - }); - - wallets.push(wallet); + ) + .await? } - } - - let multi_mint_wallet = MultiMintWallet::new(localstore, seed, wallets); + None => MultiMintWallet::new(localstore.clone(), seed, currency_unit.clone()).await?, + }; match &args.command { Commands::DecodeToken(sub_command_args) => { @@ -239,6 +207,9 @@ async fn main() -> Result<()> { Commands::Send(sub_command_args) => { sub_commands::send::send(&multi_mint_wallet, sub_command_args).await } + Commands::Transfer(sub_command_args) => { + sub_commands::transfer::transfer(&multi_mint_wallet, sub_command_args).await + } Commands::CheckPending => { sub_commands::check_pending::check_pending(&multi_mint_wallet).await } diff --git a/crates/cdk-cli/src/sub_commands/balance.rs b/crates/cdk-cli/src/sub_commands/balance.rs index 4e25e74ac..51241ff22 100644 --- a/crates/cdk-cli/src/sub_commands/balance.rs +++ b/crates/cdk-cli/src/sub_commands/balance.rs @@ -3,11 +3,24 @@ use std::collections::BTreeMap; use anyhow::Result; use cdk::mint_url::MintUrl; use cdk::nuts::CurrencyUnit; -use cdk::wallet::multi_mint_wallet::MultiMintWallet; +use cdk::wallet::MultiMintWallet; use cdk::Amount; pub async fn balance(multi_mint_wallet: &MultiMintWallet) -> Result<()> { - mint_balances(multi_mint_wallet, &CurrencyUnit::Sat).await?; + // Show individual mint balances + let mint_balances = mint_balances(multi_mint_wallet, multi_mint_wallet.unit()).await?; + + // Show total balance using the new unified interface + let total = multi_mint_wallet.total_balance().await?; + if !mint_balances.is_empty() { + println!(); + println!( + "Total balance across all wallets: {} {}", + total, + multi_mint_wallet.unit() + ); + } + Ok(()) } @@ -15,7 +28,7 @@ pub async fn mint_balances( multi_mint_wallet: &MultiMintWallet, unit: &CurrencyUnit, ) -> Result> { - let wallets: BTreeMap = multi_mint_wallet.get_balances(unit).await?; + let wallets: BTreeMap = multi_mint_wallet.get_balances().await?; let mut wallets_vec = Vec::with_capacity(wallets.len()); diff --git a/crates/cdk-cli/src/sub_commands/burn.rs b/crates/cdk-cli/src/sub_commands/burn.rs index 4fbc7dcb0..f6f7d560b 100644 --- a/crates/cdk-cli/src/sub_commands/burn.rs +++ b/crates/cdk-cli/src/sub_commands/burn.rs @@ -1,9 +1,5 @@ -use std::str::FromStr; - use anyhow::Result; use cdk::mint_url::MintUrl; -use cdk::nuts::CurrencyUnit; -use cdk::wallet::types::WalletKey; use cdk::wallet::MultiMintWallet; use cdk::Amount; use clap::Args; @@ -12,9 +8,6 @@ use clap::Args; pub struct BurnSubCommand { /// Mint Url mint_url: Option, - /// Currency unit e.g. sat - #[arg(default_value = "sat")] - unit: String, } pub async fn burn( @@ -22,14 +15,10 @@ pub async fn burn( sub_command_args: &BurnSubCommand, ) -> Result<()> { let mut total_burnt = Amount::ZERO; - let unit = CurrencyUnit::from_str(&sub_command_args.unit)?; match &sub_command_args.mint_url { Some(mint_url) => { - let wallet = multi_mint_wallet - .get_wallet(&WalletKey::new(mint_url.clone(), unit)) - .await - .unwrap(); + let wallet = multi_mint_wallet.get_wallet(mint_url).await.unwrap(); total_burnt = wallet.check_all_pending_proofs().await?; } None => { diff --git a/crates/cdk-cli/src/sub_commands/cat_device_login.rs b/crates/cdk-cli/src/sub_commands/cat_device_login.rs index 61f53c509..b2e6ded72 100644 --- a/crates/cdk-cli/src/sub_commands/cat_device_login.rs +++ b/crates/cdk-cli/src/sub_commands/cat_device_login.rs @@ -1,11 +1,9 @@ use std::path::Path; -use std::str::FromStr; use std::time::Duration; use anyhow::{anyhow, Result}; use cdk::mint_url::MintUrl; -use cdk::nuts::{CurrencyUnit, MintInfo}; -use cdk::wallet::types::WalletKey; +use cdk::nuts::MintInfo; use cdk::wallet::MultiMintWallet; use cdk::OidcClient; use clap::Args; @@ -18,10 +16,6 @@ use crate::token_storage; pub struct CatDeviceLoginSubCommand { /// Mint url mint_url: MintUrl, - /// Currency unit e.g. sat - #[arg(default_value = "sat")] - #[arg(short, long)] - unit: String, /// Client ID for OIDC authentication #[arg(default_value = "cashu-client")] #[arg(long)] @@ -34,17 +28,15 @@ pub async fn cat_device_login( work_dir: &Path, ) -> Result<()> { let mint_url = sub_command_args.mint_url.clone(); - let unit = CurrencyUnit::from_str(&sub_command_args.unit)?; - let wallet = match multi_mint_wallet - .get_wallet(&WalletKey::new(mint_url.clone(), unit.clone())) - .await - { + let wallet = match multi_mint_wallet.get_wallet(&mint_url).await { Some(wallet) => wallet.clone(), None => { + multi_mint_wallet.add_mint(mint_url.clone(), None).await?; multi_mint_wallet - .create_and_add_wallet(&mint_url.to_string(), unit, None) - .await? + .get_wallet(&mint_url) + .await + .expect("Wallet should exist after adding mint") } }; diff --git a/crates/cdk-cli/src/sub_commands/cat_login.rs b/crates/cdk-cli/src/sub_commands/cat_login.rs index 038f16642..a25530836 100644 --- a/crates/cdk-cli/src/sub_commands/cat_login.rs +++ b/crates/cdk-cli/src/sub_commands/cat_login.rs @@ -1,10 +1,8 @@ use std::path::Path; -use std::str::FromStr; use anyhow::{anyhow, Result}; use cdk::mint_url::MintUrl; -use cdk::nuts::{CurrencyUnit, MintInfo}; -use cdk::wallet::types::WalletKey; +use cdk::nuts::MintInfo; use cdk::wallet::MultiMintWallet; use cdk::OidcClient; use clap::Args; @@ -20,10 +18,6 @@ pub struct CatLoginSubCommand { username: String, /// Password password: String, - /// Currency unit e.g. sat - #[arg(default_value = "sat")] - #[arg(short, long)] - unit: String, /// Client ID for OIDC authentication #[arg(default_value = "cashu-client")] #[arg(long)] @@ -36,17 +30,16 @@ pub async fn cat_login( work_dir: &Path, ) -> Result<()> { let mint_url = sub_command_args.mint_url.clone(); - let unit = CurrencyUnit::from_str(&sub_command_args.unit)?; - let wallet = match multi_mint_wallet - .get_wallet(&WalletKey::new(mint_url.clone(), unit.clone())) - .await - { + let wallet = match multi_mint_wallet.get_wallet(&mint_url).await { Some(wallet) => wallet.clone(), None => { + multi_mint_wallet.add_mint(mint_url.clone(), None).await?; multi_mint_wallet - .create_and_add_wallet(&mint_url.to_string(), unit, None) - .await? + .get_wallet(&mint_url) + .await + .expect("Wallet should exist after adding mint") + .clone() } }; diff --git a/crates/cdk-cli/src/sub_commands/create_request.rs b/crates/cdk-cli/src/sub_commands/create_request.rs index 66b08534d..2959536d9 100644 --- a/crates/cdk-cli/src/sub_commands/create_request.rs +++ b/crates/cdk-cli/src/sub_commands/create_request.rs @@ -6,9 +6,6 @@ use clap::Args; pub struct CreateRequestSubCommand { #[arg(short, long)] amount: Option, - /// Currency unit e.g. sat - #[arg(default_value = "sat")] - unit: String, /// Quote description description: Option, /// P2PK: Public key(s) for which the token can be spent with valid signature(s) @@ -48,7 +45,7 @@ pub async fn create_request( // Gather parameters for library call let params = pr::CreateRequestParams { amount: sub_command_args.amount, - unit: sub_command_args.unit.clone(), + unit: multi_mint_wallet.unit().to_string(), description: sub_command_args.description.clone(), pubkeys: sub_command_args.pubkey.clone(), num_sigs: sub_command_args.num_sigs, diff --git a/crates/cdk-cli/src/sub_commands/melt.rs b/crates/cdk-cli/src/sub_commands/melt.rs index e03e1a11c..a07db2ff9 100644 --- a/crates/cdk-cli/src/sub_commands/melt.rs +++ b/crates/cdk-cli/src/sub_commands/melt.rs @@ -4,19 +4,12 @@ use anyhow::{bail, Result}; use cdk::amount::{amount_for_offer, Amount, MSAT_IN_SAT}; use cdk::mint_url::MintUrl; use cdk::nuts::{CurrencyUnit, MeltOptions}; -use cdk::wallet::multi_mint_wallet::MultiMintWallet; -use cdk::wallet::types::WalletKey; -use cdk::wallet::{MeltQuote, Wallet}; +use cdk::wallet::MultiMintWallet; use cdk::Bolt11Invoice; use clap::{Args, ValueEnum}; use lightning::offers::offer::Offer; -use tokio::task::JoinSet; -use crate::sub_commands::balance::mint_balances; -use crate::utils::{ - get_number_input, get_user_input, get_wallet_by_index, get_wallet_by_mint_url, - validate_mint_number, -}; +use crate::utils::{get_number_input, get_user_input}; #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, ValueEnum)] pub enum PaymentType { @@ -30,40 +23,17 @@ pub enum PaymentType { #[derive(Args)] pub struct MeltSubCommand { - /// Currency unit e.g. sat - #[arg(default_value = "sat")] - unit: String, /// Mpp #[arg(short, long, conflicts_with = "mint_url")] mpp: bool, /// Mint URL to use for melting #[arg(long, conflicts_with = "mpp")] mint_url: Option, - /// Payment method (bolt11 or bolt12) + /// Payment method (bolt11, bolt12, or bip353) #[arg(long, default_value = "bolt11")] method: PaymentType, } -/// Helper function to process a melt quote and execute the payment -async fn process_payment(wallet: &Wallet, quote: MeltQuote) -> Result<()> { - // Display quote information - println!("Quote ID: {}", quote.id); - println!("Amount: {}", quote.amount); - println!("Fee Reserve: {}", quote.fee_reserve); - println!("State: {}", quote.state); - println!("Expiry: {}", quote.expiry); - - // Execute the payment - let melt = wallet.melt("e.id).await?; - println!("Paid: {}", melt.state); - - if let Some(preimage) = melt.preimage { - println!("Payment preimage: {preimage}"); - } - - Ok(()) -} - /// Helper function to check if there are enough funds and create appropriate MeltOptions fn create_melt_options( available_funds: u64, @@ -95,71 +65,149 @@ pub async fn pay( multi_mint_wallet: &MultiMintWallet, sub_command_args: &MeltSubCommand, ) -> Result<()> { - let unit = CurrencyUnit::from_str(&sub_command_args.unit)?; - let mints_amounts = mint_balances(multi_mint_wallet, &unit).await?; + // Check total balance across all wallets + let total_balance = multi_mint_wallet.total_balance().await?; + if total_balance == Amount::ZERO { + bail!("No funds available"); + } if sub_command_args.mpp { - // MPP logic only works with BOLT11 currently + // Manual MPP - user specifies which mints and amounts to use if !matches!(sub_command_args.method, PaymentType::Bolt11) { bail!("MPP is only supported for BOLT11 invoices"); } - // Collect mint numbers and amounts for MPP - let (mints, mint_amounts) = collect_mpp_inputs(&mints_amounts, &sub_command_args.mint_url)?; - - // Process BOLT11 MPP payment - let bolt11 = Bolt11Invoice::from_str(&get_user_input("Enter bolt11 invoice request")?)?; - - // Get quotes from all mints - let quotes = get_mpp_quotes( - multi_mint_wallet, - &mints_amounts, - &mints, - &mint_amounts, - &unit, - &bolt11, - ) - .await?; - - // Execute all melts - execute_mpp_melts(quotes).await?; - } else { - // Get wallet either by mint URL or by index - let wallet = if let Some(mint_url) = &sub_command_args.mint_url { - // Use the provided mint URL - get_wallet_by_mint_url(multi_mint_wallet, mint_url, unit.clone()).await? - } else { - // Fallback to the index-based selection - let mint_number: usize = get_number_input("Enter mint number to melt from")?; - get_wallet_by_index(multi_mint_wallet, &mints_amounts, mint_number, unit.clone()) - .await? - }; - - // Find the mint amount for the selected wallet to check available funds - let mint_url = &wallet.mint_url; - let mint_amount = mints_amounts + let bolt11_str = get_user_input("Enter bolt11 invoice")?; + let _bolt11 = Bolt11Invoice::from_str(&bolt11_str)?; // Validate invoice format + + // Show available mints and balances + let balances = multi_mint_wallet.get_balances().await?; + println!("\nAvailable mints and balances:"); + for (i, (mint_url, balance)) in balances.iter().enumerate() { + println!( + " {}: {} - {} {}", + i, + mint_url, + balance, + multi_mint_wallet.unit() + ); + } + + // Collect mint selections and amounts + let mut mint_amounts = Vec::new(); + loop { + let mint_input = get_user_input("Enter mint number to use (or 'done' to finish)")?; + + if mint_input.to_lowercase() == "done" || mint_input.is_empty() { + break; + } + + let mint_index: usize = mint_input.parse()?; + let mint_url = balances + .iter() + .nth(mint_index) + .map(|(url, _)| url.clone()) + .ok_or_else(|| anyhow::anyhow!("Invalid mint index"))?; + + let amount: u64 = get_number_input(&format!( + "Enter amount to use from this mint ({})", + multi_mint_wallet.unit() + ))?; + mint_amounts.push((mint_url, Amount::from(amount))); + } + + if mint_amounts.is_empty() { + bail!("No mints selected for MPP payment"); + } + + // Get quotes for each mint + println!("\nGetting melt quotes..."); + let quotes = multi_mint_wallet + .mpp_melt_quote(bolt11_str, mint_amounts) + .await?; + + // Display quotes + println!("\nMelt quotes obtained:"); + for (mint_url, quote) in "es { + println!(" {} - Quote ID: {}", mint_url, quote.id); + println!(" Amount: {}, Fee: {}", quote.amount, quote.fee_reserve); + } + + // Execute the melts + let quotes_to_execute: Vec<(MintUrl, String)> = quotes .iter() - .find(|(url, _)| url == mint_url) - .map(|(_, amount)| *amount) - .ok_or_else(|| anyhow::anyhow!("Could not find balance for mint: {}", mint_url))?; + .map(|(url, quote)| (url.clone(), quote.id.clone())) + .collect(); - let available_funds = >::into(mint_amount) * MSAT_IN_SAT; + println!("\nExecuting MPP payment..."); + let results = multi_mint_wallet.mpp_melt(quotes_to_execute).await?; - // Process payment based on payment method + // Display results + println!("\nPayment results:"); + let mut total_paid = Amount::ZERO; + let mut total_fees = Amount::ZERO; + + for (mint_url, melted) in results { + println!( + " {} - Paid: {}, Fee: {}", + mint_url, melted.amount, melted.fee_paid + ); + total_paid += melted.amount; + total_fees += melted.fee_paid; + + if let Some(preimage) = melted.preimage { + println!(" Preimage: {}", preimage); + } + } + + println!("\nTotal paid: {} {}", total_paid, multi_mint_wallet.unit()); + println!("Total fees: {} {}", total_fees, multi_mint_wallet.unit()); + } else { + let available_funds = >::into(total_balance) * MSAT_IN_SAT; + + // Process payment based on payment method using new unified interface match sub_command_args.method { PaymentType::Bolt11 => { // Process BOLT11 payment - let bolt11 = Bolt11Invoice::from_str(&get_user_input("Enter bolt11 invoice")?)?; + let bolt11_str = get_user_input("Enter bolt11 invoice")?; + let bolt11 = Bolt11Invoice::from_str(&bolt11_str)?; // Determine payment amount and options - let prompt = - "Enter the amount you would like to pay in sats for this amountless invoice."; + let prompt = format!( + "Enter the amount you would like to pay in {} for this amountless invoice.", + multi_mint_wallet.unit() + ); let options = - create_melt_options(available_funds, bolt11.amount_milli_satoshis(), prompt)?; + create_melt_options(available_funds, bolt11.amount_milli_satoshis(), &prompt)?; + + // Use mint-specific functions or auto-select + let melted = if let Some(mint_url) = &sub_command_args.mint_url { + // User specified a mint - use the new mint-specific functions + let mint_url = MintUrl::from_str(mint_url)?; + + // Create a melt quote for the specific mint + let quote = multi_mint_wallet + .melt_quote(&mint_url, bolt11_str.clone(), options) + .await?; + + println!("Melt quote created:"); + println!(" Quote ID: {}", quote.id); + println!(" Amount: {}", quote.amount); + println!(" Fee Reserve: {}", quote.fee_reserve); + + // Execute the melt + multi_mint_wallet + .melt_with_mint(&mint_url, "e.id) + .await? + } else { + // Let the wallet automatically select the best mint + multi_mint_wallet.melt(&bolt11_str, options, None).await? + }; - // Process payment - let quote = wallet.melt_quote(bolt11.to_string(), options).await?; - process_payment(&wallet, quote).await?; + println!("Payment successful: {:?}", melted); + if let Some(preimage) = melted.preimage { + println!("Payment preimage: {}", preimage); + } } PaymentType::Bolt12 => { // Process BOLT12 payment (offer) @@ -168,26 +216,117 @@ pub async fn pay( .map_err(|e| anyhow::anyhow!("Invalid BOLT12 offer: {:?}", e))?; // Determine if offer has an amount - let prompt = - "Enter the amount you would like to pay in sats for this amountless offer:"; + let prompt = format!( + "Enter the amount you would like to pay in {} for this amountless offer:", + multi_mint_wallet.unit() + ); let amount_msat = match amount_for_offer(&offer, &CurrencyUnit::Msat) { Ok(amount) => Some(u64::from(amount)), Err(_) => None, }; - let options = create_melt_options(available_funds, amount_msat, prompt)?; + let options = create_melt_options(available_funds, amount_msat, &prompt)?; + + // Get wallet for BOLT12 + let wallet = if let Some(mint_url) = &sub_command_args.mint_url { + // User specified a mint + let mint_url = MintUrl::from_str(mint_url)?; + multi_mint_wallet + .get_wallet(&mint_url) + .await + .ok_or_else(|| anyhow::anyhow!("Mint {} not found", mint_url))? + } else { + // Show available mints and let user select + let balances = multi_mint_wallet.get_balances().await?; + println!("\nAvailable mints:"); + for (i, (mint_url, balance)) in balances.iter().enumerate() { + println!( + " {}: {} - {} {}", + i, + mint_url, + balance, + multi_mint_wallet.unit() + ); + } + + let mint_number: usize = get_number_input("Enter mint number to melt from")?; + let selected_mint = balances + .iter() + .nth(mint_number) + .map(|(url, _)| url) + .ok_or_else(|| anyhow::anyhow!("Invalid mint number"))?; + + multi_mint_wallet + .get_wallet(selected_mint) + .await + .ok_or_else(|| anyhow::anyhow!("Mint {} not found", selected_mint))? + }; // Get melt quote for BOLT12 let quote = wallet.melt_bolt12_quote(offer_str, options).await?; - process_payment(&wallet, quote).await?; + + // Display quote info + println!("Melt quote created:"); + println!(" Quote ID: {}", quote.id); + println!(" Amount: {}", quote.amount); + println!(" Fee Reserve: {}", quote.fee_reserve); + println!(" State: {}", quote.state); + println!(" Expiry: {}", quote.expiry); + + // Execute the melt + let melted = wallet.melt("e.id).await?; + println!( + "Payment successful: Paid {} with fee {}", + melted.amount, melted.fee_paid + ); + if let Some(preimage) = melted.preimage { + println!("Payment preimage: {}", preimage); + } } PaymentType::Bip353 => { - let bip353_addr = get_user_input("Enter Bip353 address.")?; + let bip353_addr = get_user_input("Enter Bip353 address")?; - let prompt = - "Enter the amount you would like to pay in sats for this amountless offer:"; + let prompt = format!( + "Enter the amount you would like to pay in {} for this amountless offer:", + multi_mint_wallet.unit() + ); // BIP353 payments are always amountless for now - let options = create_melt_options(available_funds, None, prompt)?; + let options = create_melt_options(available_funds, None, &prompt)?; + + // Get wallet for BIP353 + let wallet = if let Some(mint_url) = &sub_command_args.mint_url { + // User specified a mint + let mint_url = MintUrl::from_str(mint_url)?; + multi_mint_wallet + .get_wallet(&mint_url) + .await + .ok_or_else(|| anyhow::anyhow!("Mint {} not found", mint_url))? + } else { + // Show available mints and let user select + let balances = multi_mint_wallet.get_balances().await?; + println!("\nAvailable mints:"); + for (i, (mint_url, balance)) in balances.iter().enumerate() { + println!( + " {}: {} - {} {}", + i, + mint_url, + balance, + multi_mint_wallet.unit() + ); + } + + let mint_number: usize = get_number_input("Enter mint number to melt from")?; + let selected_mint = balances + .iter() + .nth(mint_number) + .map(|(url, _)| url) + .ok_or_else(|| anyhow::anyhow!("Invalid mint number"))?; + + multi_mint_wallet + .get_wallet(selected_mint) + .await + .ok_or_else(|| anyhow::anyhow!("Mint {} not found", selected_mint))? + }; // Get melt quote for BIP353 address (internally resolves and gets BOLT12 quote) let quote = wallet @@ -196,153 +335,27 @@ pub async fn pay( options.expect("Amount is required").amount_msat(), ) .await?; - process_payment(&wallet, quote).await?; - } - } - } - - Ok(()) -} - -/// Collect mint numbers and amounts for MPP payments -fn collect_mpp_inputs( - mints_amounts: &[(MintUrl, Amount)], - mint_url_opt: &Option, -) -> Result<(Vec, Vec)> { - let mut mints = Vec::new(); - let mut mint_amounts = Vec::new(); - - // If a specific mint URL was provided, try to use it as the first mint - if let Some(mint_url) = mint_url_opt { - println!("Using mint URL {mint_url} as the first mint for MPP payment."); - - // Find the index of this mint in the mints_amounts list - if let Some(mint_index) = mints_amounts - .iter() - .position(|(url, _)| url.to_string() == *mint_url) - { - mints.push(mint_index); - let melt_amount: u64 = - get_number_input("Enter amount to mint from this mint in sats.")?; - mint_amounts.push(melt_amount); - } else { - println!( - "Warning: Mint URL not found or no balance. Continuing with manual selection." - ); - } - } - - // Continue with regular mint selection - loop { - let mint_number: String = - get_user_input("Enter mint number to melt from and -1 when done.")?; - - if mint_number == "-1" || mint_number.is_empty() { - break; - } - - let mint_number: usize = mint_number.parse()?; - validate_mint_number(mint_number, mints_amounts.len())?; - - mints.push(mint_number); - let melt_amount: u64 = get_number_input("Enter amount to mint from this mint in sats.")?; - mint_amounts.push(melt_amount); - } - - if mints.is_empty() { - bail!("No mints selected for MPP payment"); - } - - Ok((mints, mint_amounts)) -} - -/// Get quotes from all mints for MPP payment -async fn get_mpp_quotes( - multi_mint_wallet: &MultiMintWallet, - mints_amounts: &[(MintUrl, Amount)], - mints: &[usize], - mint_amounts: &[u64], - unit: &CurrencyUnit, - bolt11: &Bolt11Invoice, -) -> Result> { - let mut quotes = JoinSet::new(); - - for (mint, amount) in mints.iter().zip(mint_amounts) { - let wallet = mints_amounts[*mint].0.clone(); - - let wallet = multi_mint_wallet - .get_wallet(&WalletKey::new(wallet, unit.clone())) - .await - .expect("Known wallet"); - let options = MeltOptions::new_mpp(*amount * 1000); - - let bolt11_clone = bolt11.clone(); - - quotes.spawn(async move { - let quote = wallet - .melt_quote(bolt11_clone.to_string(), Some(options)) - .await; - - (wallet, quote) - }); - } - let quotes_results = quotes.join_all().await; + // Display quote info + println!("Melt quote created:"); + println!(" Quote ID: {}", quote.id); + println!(" Amount: {}", quote.amount); + println!(" Fee Reserve: {}", quote.fee_reserve); + println!(" State: {}", quote.state); + println!(" Expiry: {}", quote.expiry); - // Validate all quotes succeeded - let mut valid_quotes = Vec::new(); - for (wallet, quote_result) in quotes_results { - match quote_result { - Ok(quote) => { + // Execute the melt + let melted = wallet.melt("e.id).await?; println!( - "Melt quote {} for mint {} of amount {} with fee {}.", - quote.id, wallet.mint_url, quote.amount, quote.fee_reserve + "Payment successful: Paid {} with fee {}", + melted.amount, melted.fee_paid ); - valid_quotes.push((wallet, quote)); - } - Err(err) => { - tracing::error!("Could not get quote for {}: {:?}", wallet.mint_url, err); - bail!("Could not get melt quote for {}", wallet.mint_url); + if let Some(preimage) = melted.preimage { + println!("Payment preimage: {}", preimage); + } } } } - Ok(valid_quotes) -} - -/// Execute all melts for MPP payment -async fn execute_mpp_melts(quotes: Vec<(Wallet, MeltQuote)>) -> Result<()> { - let mut melts = JoinSet::new(); - - for (wallet, quote) in quotes { - melts.spawn(async move { - let melt = wallet.melt("e.id).await; - (wallet, melt) - }); - } - - let melts = melts.join_all().await; - - let mut error = false; - - for (wallet, melt) in melts { - match melt { - Ok(melt) => { - println!( - "Melt for {} paid {} with fee of {} ", - wallet.mint_url, melt.amount, melt.fee_paid - ); - } - Err(err) => { - println!("Melt for {} failed with {}", wallet.mint_url, err); - error = true; - } - } - } - - if error { - bail!("Could not complete all melts"); - } - Ok(()) } diff --git a/crates/cdk-cli/src/sub_commands/mint.rs b/crates/cdk-cli/src/sub_commands/mint.rs index 670e72dcc..84ca828a7 100644 --- a/crates/cdk-cli/src/sub_commands/mint.rs +++ b/crates/cdk-cli/src/sub_commands/mint.rs @@ -4,7 +4,7 @@ use anyhow::{anyhow, Result}; use cdk::amount::SplitTarget; use cdk::mint_url::MintUrl; use cdk::nuts::nut00::ProofsMethods; -use cdk::nuts::{CurrencyUnit, PaymentMethod}; +use cdk::nuts::PaymentMethod; use cdk::wallet::MultiMintWallet; use cdk::{Amount, StreamExt}; use clap::Args; @@ -18,9 +18,6 @@ pub struct MintSubCommand { mint_url: MintUrl, /// Amount amount: Option, - /// Currency unit e.g. sat - #[arg(default_value = "sat")] - unit: String, /// Quote description #[serde(skip_serializing_if = "Option::is_none")] description: Option, @@ -46,10 +43,9 @@ pub async fn mint( sub_command_args: &MintSubCommand, ) -> Result<()> { let mint_url = sub_command_args.mint_url.clone(); - let unit = CurrencyUnit::from_str(&sub_command_args.unit)?; let description: Option = sub_command_args.description.clone(); - let wallet = get_or_create_wallet(multi_mint_wallet, &mint_url, unit).await?; + let wallet = get_or_create_wallet(multi_mint_wallet, &mint_url).await?; let payment_method = PaymentMethod::from_str(&sub_command_args.method)?; diff --git a/crates/cdk-cli/src/sub_commands/mint_blind_auth.rs b/crates/cdk-cli/src/sub_commands/mint_blind_auth.rs index cf55b583b..8e14341fe 100644 --- a/crates/cdk-cli/src/sub_commands/mint_blind_auth.rs +++ b/crates/cdk-cli/src/sub_commands/mint_blind_auth.rs @@ -1,10 +1,8 @@ use std::path::Path; -use std::str::FromStr; use anyhow::{anyhow, Result}; use cdk::mint_url::MintUrl; -use cdk::nuts::{CurrencyUnit, MintInfo}; -use cdk::wallet::types::WalletKey; +use cdk::nuts::MintInfo; use cdk::wallet::MultiMintWallet; use cdk::{Amount, OidcClient}; use clap::Args; @@ -21,10 +19,6 @@ pub struct MintBlindAuthSubCommand { /// Cat (access token) #[arg(long)] cat: Option, - /// Currency unit e.g. sat - #[arg(default_value = "sat")] - #[arg(short, long)] - unit: String, } pub async fn mint_blind_auth( @@ -33,17 +27,16 @@ pub async fn mint_blind_auth( work_dir: &Path, ) -> Result<()> { let mint_url = sub_command_args.mint_url.clone(); - let unit = CurrencyUnit::from_str(&sub_command_args.unit)?; - let wallet = match multi_mint_wallet - .get_wallet(&WalletKey::new(mint_url.clone(), unit.clone())) - .await - { + let wallet = match multi_mint_wallet.get_wallet(&mint_url).await { Some(wallet) => wallet.clone(), None => { + multi_mint_wallet.add_mint(mint_url.clone(), None).await?; multi_mint_wallet - .create_and_add_wallet(&mint_url.to_string(), unit, None) - .await? + .get_wallet(&mint_url) + .await + .expect("Wallet should exist after adding mint") + .clone() } }; diff --git a/crates/cdk-cli/src/sub_commands/mod.rs b/crates/cdk-cli/src/sub_commands/mod.rs index aaf1cb925..0a52cf12b 100644 --- a/crates/cdk-cli/src/sub_commands/mod.rs +++ b/crates/cdk-cli/src/sub_commands/mod.rs @@ -16,4 +16,5 @@ pub mod pending_mints; pub mod receive; pub mod restore; pub mod send; +pub mod transfer; pub mod update_mint_url; diff --git a/crates/cdk-cli/src/sub_commands/pending_mints.rs b/crates/cdk-cli/src/sub_commands/pending_mints.rs index a752d11c8..b033f9eeb 100644 --- a/crates/cdk-cli/src/sub_commands/pending_mints.rs +++ b/crates/cdk-cli/src/sub_commands/pending_mints.rs @@ -2,11 +2,9 @@ use anyhow::Result; use cdk::wallet::MultiMintWallet; pub async fn mint_pending(multi_mint_wallet: &MultiMintWallet) -> Result<()> { - let amounts = multi_mint_wallet.check_all_mint_quotes(None).await?; + let amount = multi_mint_wallet.check_all_mint_quotes(None).await?; - for (unit, amount) in amounts { - println!("Unit: {unit}, Amount: {amount}"); - } + println!("Amount: {amount}"); Ok(()) } diff --git a/crates/cdk-cli/src/sub_commands/receive.rs b/crates/cdk-cli/src/sub_commands/receive.rs index 0bb219d7d..ee04c5245 100644 --- a/crates/cdk-cli/src/sub_commands/receive.rs +++ b/crates/cdk-cli/src/sub_commands/receive.rs @@ -4,11 +4,11 @@ use std::str::FromStr; use std::time::Duration; use anyhow::{anyhow, Result}; +use cdk::mint_url::MintUrl; use cdk::nuts::{SecretKey, Token}; use cdk::util::unix_time; use cdk::wallet::multi_mint_wallet::MultiMintWallet; -use cdk::wallet::types::WalletKey; -use cdk::wallet::ReceiveOptions; +use cdk::wallet::{MultiMintReceiveOptions, ReceiveOptions}; use cdk::Amount; use clap::Args; use nostr_sdk::nips::nip04; @@ -36,6 +36,12 @@ pub struct ReceiveSubCommand { /// Preimage #[arg(short, long, action = clap::ArgAction::Append)] preimage: Vec, + /// Allow receiving from untrusted mints (mints not already in the wallet) + #[arg(long, default_value = "false")] + allow_untrusted: bool, + /// Transfer tokens from untrusted mints to this mint + #[arg(long, value_name = "MINT_URL")] + transfer_to: Option, } pub async fn receive( @@ -69,6 +75,8 @@ pub async fn receive( token_str, &signing_keys, &sub_command_args.preimage, + sub_command_args.allow_untrusted, + sub_command_args.transfer_to.as_deref(), ) .await? } @@ -109,6 +117,8 @@ pub async fn receive( token_str, &signing_keys, &sub_command_args.preimage, + sub_command_args.allow_untrusted, + sub_command_args.transfer_to.as_deref(), ) .await { @@ -135,29 +145,40 @@ async fn receive_token( token_str: &str, signing_keys: &[SecretKey], preimage: &[String], + allow_untrusted: bool, + transfer_to: Option<&str>, ) -> Result { let token: Token = Token::from_str(token_str)?; let mint_url = token.mint_url()?; - let unit = token.unit().unwrap_or_default(); - - if multi_mint_wallet - .get_wallet(&WalletKey::new(mint_url.clone(), unit.clone())) - .await - .is_none() - { - get_or_create_wallet(multi_mint_wallet, &mint_url, unit).await?; + + // Parse transfer_to mint URL if provided + let transfer_to_mint = if let Some(mint_str) = transfer_to { + Some(MintUrl::from_str(mint_str)?) + } else { + None + }; + + // Check if the mint is already trusted + let is_trusted = multi_mint_wallet.get_wallet(&mint_url).await.is_some(); + + // If mint is not trusted and we don't allow untrusted, add it first (old behavior) + if !is_trusted && !allow_untrusted { + get_or_create_wallet(multi_mint_wallet, &mint_url).await?; } + // Create multi-mint receive options + let multi_mint_options = MultiMintReceiveOptions::default() + .allow_untrusted(allow_untrusted) + .transfer_to_mint(transfer_to_mint) + .receive_options(ReceiveOptions { + p2pk_signing_keys: signing_keys.to_vec(), + preimages: preimage.to_vec(), + ..Default::default() + }); + let amount = multi_mint_wallet - .receive( - token_str, - ReceiveOptions { - p2pk_signing_keys: signing_keys.to_vec(), - preimages: preimage.to_vec(), - ..Default::default() - }, - ) + .receive(token_str, multi_mint_options) .await?; Ok(amount) } diff --git a/crates/cdk-cli/src/sub_commands/restore.rs b/crates/cdk-cli/src/sub_commands/restore.rs index 9f12e8471..56247a4aa 100644 --- a/crates/cdk-cli/src/sub_commands/restore.rs +++ b/crates/cdk-cli/src/sub_commands/restore.rs @@ -1,9 +1,5 @@ -use std::str::FromStr; - use anyhow::Result; use cdk::mint_url::MintUrl; -use cdk::nuts::CurrencyUnit; -use cdk::wallet::types::WalletKey; use cdk::wallet::MultiMintWallet; use clap::Args; @@ -11,27 +7,23 @@ use clap::Args; pub struct RestoreSubCommand { /// Mint Url mint_url: MintUrl, - /// Currency unit e.g. sat - #[arg(default_value = "sat")] - unit: String, } pub async fn restore( multi_mint_wallet: &MultiMintWallet, sub_command_args: &RestoreSubCommand, ) -> Result<()> { - let unit = CurrencyUnit::from_str(&sub_command_args.unit)?; let mint_url = sub_command_args.mint_url.clone(); - let wallet = match multi_mint_wallet - .get_wallet(&WalletKey::new(mint_url.clone(), unit.clone())) - .await - { + let wallet = match multi_mint_wallet.get_wallet(&mint_url).await { Some(wallet) => wallet.clone(), None => { + multi_mint_wallet.add_mint(mint_url.clone(), None).await?; multi_mint_wallet - .create_and_add_wallet(&mint_url.to_string(), unit, None) - .await? + .get_wallet(&mint_url) + .await + .expect("Wallet should exist after adding mint") + .clone() } }; diff --git a/crates/cdk-cli/src/sub_commands/send.rs b/crates/cdk-cli/src/sub_commands/send.rs index e1b37bfff..0c8fb61f2 100644 --- a/crates/cdk-cli/src/sub_commands/send.rs +++ b/crates/cdk-cli/src/sub_commands/send.rs @@ -1,16 +1,14 @@ use std::str::FromStr; use anyhow::{anyhow, Result}; -use cdk::nuts::{Conditions, CurrencyUnit, PublicKey, SpendingConditions}; +use cdk::mint_url::MintUrl; +use cdk::nuts::{Conditions, PublicKey, SpendingConditions}; use cdk::wallet::types::SendKind; use cdk::wallet::{MultiMintWallet, SendMemo, SendOptions}; use cdk::Amount; use clap::Args; -use crate::sub_commands::balance::mint_balances; -use crate::utils::{ - check_sufficient_funds, get_number_input, get_wallet_by_index, get_wallet_by_mint_url, -}; +use crate::utils::get_number_input; #[derive(Args)] pub struct SendSubCommand { @@ -50,39 +48,38 @@ pub struct SendSubCommand { /// Mint URL to use for sending #[arg(long)] mint_url: Option, - /// Currency unit e.g. sat - #[arg(default_value = "sat")] - unit: String, + /// Allow transferring funds from other mints if the target mint has insufficient balance + #[arg(long)] + allow_transfer: bool, + /// Maximum amount to transfer from other mints + #[arg(long)] + max_transfer_amount: Option, + /// Specific mints allowed for transfers (can be specified multiple times) + #[arg(long, action = clap::ArgAction::Append)] + allowed_mints: Vec, + /// Specific mints to exclude from transfers (can be specified multiple times) + #[arg(long, action = clap::ArgAction::Append)] + excluded_mints: Vec, } pub async fn send( multi_mint_wallet: &MultiMintWallet, sub_command_args: &SendSubCommand, ) -> Result<()> { - let unit = CurrencyUnit::from_str(&sub_command_args.unit)?; - let mints_amounts = mint_balances(multi_mint_wallet, &unit).await?; - - // Get wallet either by mint URL or by index - let wallet = if let Some(mint_url) = &sub_command_args.mint_url { - // Use the provided mint URL - get_wallet_by_mint_url(multi_mint_wallet, mint_url, unit).await? - } else { - // Fallback to the index-based selection - let mint_number: usize = get_number_input("Enter mint number to create token")?; - get_wallet_by_index(multi_mint_wallet, &mints_amounts, mint_number, unit).await? - }; + let token_amount = Amount::from(get_number_input::(&format!( + "Enter value of token in {}", + multi_mint_wallet.unit() + ))?); - let token_amount = Amount::from(get_number_input::("Enter value of token in sats")?); - - // Find the mint amount for the selected wallet to check if we have sufficient funds - let mint_url = &wallet.mint_url; - let mint_amount = mints_amounts - .iter() - .find(|(url, _)| url == mint_url) - .map(|(_, amount)| *amount) - .ok_or_else(|| anyhow!("Could not find balance for mint: {}", mint_url))?; - - check_sufficient_funds(mint_amount, token_amount)?; + // Check total balance across all wallets + let total_balance = multi_mint_wallet.total_balance().await?; + if total_balance < token_amount { + return Err(anyhow!( + "Insufficient funds. Total balance: {}, Required: {}", + total_balance, + token_amount + )); + } let conditions = match (&sub_command_args.preimage, &sub_command_args.hash) { (Some(_), Some(_)) => { @@ -206,22 +203,74 @@ pub async fn send( (false, None) => SendKind::OnlineExact, }; - let prepared_send = wallet - .prepare_send( - token_amount, - SendOptions { - memo: sub_command_args.memo.clone().map(|memo| SendMemo { - memo, - include_memo: true, - }), - send_kind, - include_fee: sub_command_args.include_fee, - conditions, - ..Default::default() - }, - ) - .await?; - let token = prepared_send.confirm(None).await?; + let send_options = SendOptions { + memo: sub_command_args.memo.clone().map(|memo| SendMemo { + memo, + include_memo: true, + }), + send_kind, + include_fee: sub_command_args.include_fee, + conditions, + ..Default::default() + }; + + // Parse allowed and excluded mints from CLI arguments + let allowed_mints: Result, _> = sub_command_args + .allowed_mints + .iter() + .map(|url| MintUrl::from_str(url)) + .collect(); + let allowed_mints = allowed_mints?; + + let excluded_mints: Result, _> = sub_command_args + .excluded_mints + .iter() + .map(|url| MintUrl::from_str(url)) + .collect(); + let excluded_mints = excluded_mints?; + + // Create MultiMintSendOptions from CLI arguments + let multi_mint_options = cdk::wallet::multi_mint_wallet::MultiMintSendOptions { + allow_transfer: sub_command_args.allow_transfer, + max_transfer_amount: sub_command_args.max_transfer_amount.map(Amount::from), + allowed_mints, + excluded_mints, + send_options: send_options.clone(), + }; + + // Use the new unified interface + let token = if let Some(mint_url) = &sub_command_args.mint_url { + // User specified a mint, use that specific wallet + let mint_url = cdk::mint_url::MintUrl::from_str(mint_url)?; + let prepared = multi_mint_wallet + .prepare_send(mint_url, token_amount, multi_mint_options) + .await?; + + // Confirm the prepared send (single mint) + let memo = send_options.memo.clone(); + prepared.confirm(memo).await? + } else { + // Let the wallet automatically select the best mint + // First, get balances to find a mint with sufficient funds + let balances = multi_mint_wallet.get_balances().await?; + + // Find a mint with sufficient balance + let mint_url = balances + .into_iter() + .find(|(_, balance)| *balance >= token_amount) + .map(|(mint_url, _)| mint_url) + .ok_or_else(|| { + anyhow::anyhow!("No mint has sufficient balance for the requested amount") + })?; + + let prepared = multi_mint_wallet + .prepare_send(mint_url, token_amount, multi_mint_options) + .await?; + + // Confirm the prepared send (multi mint) + let memo = send_options.memo.clone(); + prepared.confirm(memo).await? + }; match sub_command_args.v3 { true => { diff --git a/crates/cdk-cli/src/sub_commands/transfer.rs b/crates/cdk-cli/src/sub_commands/transfer.rs new file mode 100644 index 000000000..e8042b29f --- /dev/null +++ b/crates/cdk-cli/src/sub_commands/transfer.rs @@ -0,0 +1,209 @@ +use std::str::FromStr; + +use anyhow::{bail, Result}; +use cdk::mint_url::MintUrl; +use cdk::wallet::multi_mint_wallet::TransferMode; +use cdk::wallet::MultiMintWallet; +use cdk::Amount; +use clap::Args; + +use crate::utils::get_number_input; + +#[derive(Args)] +pub struct TransferSubCommand { + /// Source mint URL to transfer from (optional - will prompt if not provided) + #[arg(long)] + source_mint: Option, + /// Target mint URL to transfer to (optional - will prompt if not provided) + #[arg(long)] + target_mint: Option, + /// Amount to transfer (optional - will prompt if not provided) + #[arg(short, long, conflicts_with = "full_balance")] + amount: Option, + /// Transfer all available balance from source mint + #[arg(long, conflicts_with = "amount")] + full_balance: bool, +} + +/// Helper function to select a mint from available mints +async fn select_mint( + multi_mint_wallet: &MultiMintWallet, + prompt: &str, + exclude_mint: Option<&MintUrl>, +) -> Result { + let balances = multi_mint_wallet.get_balances().await?; + + // Filter out excluded mint if provided + let available_mints: Vec<_> = balances + .iter() + .filter(|(url, _)| exclude_mint.is_none_or(|excluded| url != &excluded)) + .collect(); + + if available_mints.is_empty() { + bail!("No available mints found"); + } + + println!("\nAvailable mints:"); + for (i, (mint_url, balance)) in available_mints.iter().enumerate() { + println!( + " {}: {} - {} {}", + i, + mint_url, + balance, + multi_mint_wallet.unit() + ); + } + + let mint_number: usize = get_number_input(prompt)?; + available_mints + .get(mint_number) + .map(|(url, _)| (*url).clone()) + .ok_or_else(|| anyhow::anyhow!("Invalid mint number")) +} + +pub async fn transfer( + multi_mint_wallet: &MultiMintWallet, + sub_command_args: &TransferSubCommand, +) -> Result<()> { + // Check total balance across all wallets + let total_balance = multi_mint_wallet.total_balance().await?; + if total_balance == Amount::ZERO { + bail!("No funds available"); + } + + // Get source mint URL either from args or by prompting user + let source_mint_url = if let Some(source_mint) = &sub_command_args.source_mint { + let url = MintUrl::from_str(source_mint)?; + // Verify the mint is in the wallet + if !multi_mint_wallet.has_mint(&url).await { + bail!( + "Source mint {} is not in the wallet. Please add it first.", + url + ); + } + url + } else { + // Show available mints and let user select source + select_mint( + multi_mint_wallet, + "Enter source mint number to transfer from", + None, + ) + .await? + }; + + // Get target mint URL either from args or by prompting user + let target_mint_url = if let Some(target_mint) = &sub_command_args.target_mint { + let url = MintUrl::from_str(target_mint)?; + // Verify the mint is in the wallet + if !multi_mint_wallet.has_mint(&url).await { + bail!( + "Target mint {} is not in the wallet. Please add it first.", + url + ); + } + url + } else { + // Show available mints (excluding source) and let user select target + select_mint( + multi_mint_wallet, + "Enter target mint number to transfer to", + Some(&source_mint_url), + ) + .await? + }; + + // Ensure source and target are different + if source_mint_url == target_mint_url { + bail!("Source and target mints must be different"); + } + + // Check source mint balance + let balances = multi_mint_wallet.get_balances().await?; + let source_balance = balances + .get(&source_mint_url) + .copied() + .unwrap_or(Amount::ZERO); + + if source_balance == Amount::ZERO { + bail!("Source mint has no balance to transfer"); + } + + // Determine transfer mode based on user input + let transfer_mode = if sub_command_args.full_balance { + println!( + "\nTransferring full balance ({} {}) from {} to {}...", + source_balance, + multi_mint_wallet.unit(), + source_mint_url, + target_mint_url + ); + TransferMode::FullBalance + } else { + let amount = match sub_command_args.amount { + Some(amt) => Amount::from(amt), + None => Amount::from(get_number_input::(&format!( + "Enter amount to transfer in {}", + multi_mint_wallet.unit() + ))?), + }; + + if source_balance < amount { + bail!( + "Insufficient funds in source mint. Available: {} {}, Required: {} {}", + source_balance, + multi_mint_wallet.unit(), + amount, + multi_mint_wallet.unit() + ); + } + + println!( + "\nTransferring {} {} from {} to {}...", + amount, + multi_mint_wallet.unit(), + source_mint_url, + target_mint_url + ); + TransferMode::ExactReceive(amount) + }; + + // Perform the transfer + let transfer_result = multi_mint_wallet + .transfer(&source_mint_url, &target_mint_url, transfer_mode) + .await?; + + println!("\nTransfer completed successfully!"); + println!( + "Amount sent: {} {}", + transfer_result.amount_sent, + multi_mint_wallet.unit() + ); + println!( + "Amount received: {} {}", + transfer_result.amount_received, + multi_mint_wallet.unit() + ); + if transfer_result.fees_paid > Amount::ZERO { + println!( + "Fees paid: {} {}", + transfer_result.fees_paid, + multi_mint_wallet.unit() + ); + } + println!("\nUpdated balances:"); + println!( + " Source mint ({}): {} {}", + source_mint_url, + transfer_result.source_balance_after, + multi_mint_wallet.unit() + ); + println!( + " Target mint ({}): {} {}", + target_mint_url, + transfer_result.target_balance_after, + multi_mint_wallet.unit() + ); + + Ok(()) +} diff --git a/crates/cdk-cli/src/sub_commands/update_mint_url.rs b/crates/cdk-cli/src/sub_commands/update_mint_url.rs index b67495b1c..51afc6fc1 100644 --- a/crates/cdk-cli/src/sub_commands/update_mint_url.rs +++ b/crates/cdk-cli/src/sub_commands/update_mint_url.rs @@ -1,7 +1,5 @@ use anyhow::{anyhow, Result}; use cdk::mint_url::MintUrl; -use cdk::nuts::CurrencyUnit; -use cdk::wallet::types::WalletKey; use cdk::wallet::MultiMintWallet; use clap::Args; @@ -23,10 +21,7 @@ pub async fn update_mint_url( } = sub_command_args; let mut wallet = multi_mint_wallet - .get_wallet(&WalletKey::new( - sub_command_args.old_mint_url.clone(), - CurrencyUnit::Sat, - )) + .get_wallet(&sub_command_args.old_mint_url) .await .ok_or(anyhow!("Unknown mint url"))? .clone(); diff --git a/crates/cdk-cli/src/utils.rs b/crates/cdk-cli/src/utils.rs index c71005098..63396cc3f 100644 --- a/crates/cdk-cli/src/utils.rs +++ b/crates/cdk-cli/src/utils.rs @@ -1,12 +1,9 @@ use std::io::{self, Write}; use std::str::FromStr; -use anyhow::{bail, Result}; +use anyhow::Result; use cdk::mint_url::MintUrl; -use cdk::nuts::CurrencyUnit; use cdk::wallet::multi_mint_wallet::MultiMintWallet; -use cdk::wallet::types::WalletKey; -use cdk::Amount; /// Helper function to get user input with a prompt pub fn get_user_input(prompt: &str) -> Result { @@ -28,73 +25,21 @@ where Ok(number) } -/// Helper function to validate a mint number against available mints -pub fn validate_mint_number(mint_number: usize, mint_count: usize) -> Result<()> { - if mint_number >= mint_count { - bail!("Invalid mint number"); - } - Ok(()) -} - -/// Helper function to check if there are enough funds for an operation -pub fn check_sufficient_funds(available: Amount, required: Amount) -> Result<()> { - if required.gt(&available) { - bail!("Not enough funds"); - } - Ok(()) -} - -/// Helper function to get a wallet from the multi-mint wallet by mint URL -pub async fn get_wallet_by_mint_url( - multi_mint_wallet: &MultiMintWallet, - mint_url_str: &str, - unit: CurrencyUnit, -) -> Result { - let mint_url = MintUrl::from_str(mint_url_str)?; - - let wallet_key = WalletKey::new(mint_url.clone(), unit); - let wallet = multi_mint_wallet - .get_wallet(&wallet_key) - .await - .ok_or_else(|| anyhow::anyhow!("Wallet not found for mint URL: {}", mint_url_str))?; - - Ok(wallet.clone()) -} - -/// Helper function to get a wallet from the multi-mint wallet -pub async fn get_wallet_by_index( - multi_mint_wallet: &MultiMintWallet, - mint_amounts: &[(MintUrl, Amount)], - mint_number: usize, - unit: CurrencyUnit, -) -> Result { - validate_mint_number(mint_number, mint_amounts.len())?; - - let wallet_key = WalletKey::new(mint_amounts[mint_number].0.clone(), unit); - let wallet = multi_mint_wallet - .get_wallet(&wallet_key) - .await - .ok_or_else(|| anyhow::anyhow!("Wallet not found"))?; - - Ok(wallet.clone()) -} - /// Helper function to create or get a wallet pub async fn get_or_create_wallet( multi_mint_wallet: &MultiMintWallet, mint_url: &MintUrl, - unit: CurrencyUnit, ) -> Result { - match multi_mint_wallet - .get_wallet(&WalletKey::new(mint_url.clone(), unit.clone())) - .await - { + match multi_mint_wallet.get_wallet(mint_url).await { Some(wallet) => Ok(wallet.clone()), None => { tracing::debug!("Wallet does not exist creating.."); - multi_mint_wallet - .create_and_add_wallet(&mint_url.to_string(), unit, None) + multi_mint_wallet.add_mint(mint_url.clone(), None).await?; + Ok(multi_mint_wallet + .get_wallet(mint_url) .await + .expect("Wallet should exist after adding mint") + .clone()) } } } diff --git a/crates/cdk-common/src/error.rs b/crates/cdk-common/src/error.rs index 9e0f8fd7c..b20d1da4a 100644 --- a/crates/cdk-common/src/error.rs +++ b/crates/cdk-common/src/error.rs @@ -250,6 +250,32 @@ pub enum Error { /// Preimage not provided #[error("Preimage not provided")] PreimageNotProvided, + + // MultiMint Wallet Errors + /// Currency unit mismatch in MultiMintWallet + #[error("Currency unit mismatch: wallet uses {expected}, but {found} provided")] + MultiMintCurrencyUnitMismatch { + /// Expected currency unit + expected: CurrencyUnit, + /// Found currency unit + found: CurrencyUnit, + }, + /// Unknown mint in MultiMintWallet + #[error("Unknown mint: {mint_url}")] + UnknownMint { + /// URL of the unknown mint + mint_url: String, + }, + /// Transfer between mints timed out + #[error("Transfer timeout: failed to transfer {amount} from {source_mint} to {target_mint}")] + TransferTimeout { + /// Source mint URL + source_mint: String, + /// Target mint URL + target_mint: String, + /// Amount that failed to transfer + amount: Amount, + }, /// Insufficient Funds #[error("Insufficient funds")] InsufficientFunds, diff --git a/crates/cdk-ffi/src/lib.rs b/crates/cdk-ffi/src/lib.rs index c8c37c335..37433e54c 100644 --- a/crates/cdk-ffi/src/lib.rs +++ b/crates/cdk-ffi/src/lib.rs @@ -4,11 +4,13 @@ pub mod database; pub mod error; +pub mod multi_mint_wallet; pub mod types; pub mod wallet; pub use database::*; pub use error::*; +pub use multi_mint_wallet::*; pub use types::*; pub use wallet::*; diff --git a/crates/cdk-ffi/src/multi_mint_wallet.rs b/crates/cdk-ffi/src/multi_mint_wallet.rs new file mode 100644 index 000000000..4de429cf1 --- /dev/null +++ b/crates/cdk-ffi/src/multi_mint_wallet.rs @@ -0,0 +1,416 @@ +//! FFI MultiMintWallet bindings + +use std::collections::HashMap; +use std::str::FromStr; +use std::sync::Arc; + +use bip39::Mnemonic; +use cdk::wallet::multi_mint_wallet::{ + MultiMintReceiveOptions as CdkMultiMintReceiveOptions, + MultiMintSendOptions as CdkMultiMintSendOptions, MultiMintWallet as CdkMultiMintWallet, + TransferMode as CdkTransferMode, TransferResult as CdkTransferResult, +}; + +use crate::error::FfiError; +use crate::types::*; + +/// FFI-compatible MultiMintWallet +#[derive(uniffi::Object)] +pub struct MultiMintWallet { + inner: Arc, +} + +#[uniffi::export(async_runtime = "tokio")] +impl MultiMintWallet { + /// Create a new MultiMintWallet from mnemonic using WalletDatabase trait + #[uniffi::constructor] + pub async fn new( + unit: CurrencyUnit, + mnemonic: String, + db: Arc, + ) -> Result { + // Parse mnemonic and generate seed without passphrase + let m = Mnemonic::parse(&mnemonic) + .map_err(|e| FfiError::InvalidMnemonic { msg: e.to_string() })?; + let seed = m.to_seed_normalized(""); + + // Convert the FFI database trait to a CDK database implementation + let localstore = crate::database::create_cdk_database_from_ffi(db); + + let wallet = CdkMultiMintWallet::new(localstore, seed, unit.into()).await?; + + Ok(Self { + inner: Arc::new(wallet), + }) + } + + /// Create a new MultiMintWallet with proxy configuration + #[uniffi::constructor] + pub async fn new_with_proxy( + unit: CurrencyUnit, + mnemonic: String, + db: Arc, + proxy_url: String, + ) -> Result { + // Parse mnemonic and generate seed without passphrase + let m = Mnemonic::parse(&mnemonic) + .map_err(|e| FfiError::InvalidMnemonic { msg: e.to_string() })?; + let seed = m.to_seed_normalized(""); + + // Convert the FFI database trait to a CDK database implementation + let localstore = crate::database::create_cdk_database_from_ffi(db); + + // Parse proxy URL + let proxy_url = + url::Url::parse(&proxy_url).map_err(|e| FfiError::InvalidUrl { msg: e.to_string() })?; + + let wallet = + CdkMultiMintWallet::new_with_proxy(localstore, seed, unit.into(), proxy_url).await?; + + Ok(Self { + inner: Arc::new(wallet), + }) + } + + /// Get the currency unit for this wallet + pub fn unit(&self) -> CurrencyUnit { + self.inner.unit().clone().into() + } + + /// Add a mint to this MultiMintWallet + pub async fn add_mint( + &self, + mint_url: MintUrl, + target_proof_count: Option, + ) -> Result<(), FfiError> { + let cdk_mint_url: cdk::mint_url::MintUrl = mint_url.try_into()?; + self.inner + .add_mint(cdk_mint_url, target_proof_count.map(|c| c as usize)) + .await?; + Ok(()) + } + + /// Remove mint from MultiMintWallet + pub async fn remove_mint(&self, mint_url: MintUrl) { + let url_str = mint_url.url.clone(); + let cdk_mint_url: cdk::mint_url::MintUrl = mint_url.try_into().unwrap_or_else(|_| { + // If conversion fails, we can't remove the mint, but we shouldn't panic + // This is a best-effort operation + cdk::mint_url::MintUrl::from_str(&url_str).unwrap_or_else(|_| { + // Last resort: create a dummy URL that won't match anything + cdk::mint_url::MintUrl::from_str("https://invalid.mint").unwrap() + }) + }); + self.inner.remove_mint(&cdk_mint_url).await; + } + + /// Check if mint is in wallet + pub async fn has_mint(&self, mint_url: MintUrl) -> bool { + if let Ok(cdk_mint_url) = mint_url.try_into() { + self.inner.has_mint(&cdk_mint_url).await + } else { + false + } + } + + /// Get wallet balances for all mints + pub async fn get_balances(&self) -> Result { + let balances = self.inner.get_balances().await?; + let mut balance_map = HashMap::new(); + for (mint_url, amount) in balances { + balance_map.insert(mint_url.to_string(), amount.into()); + } + Ok(balance_map) + } + + /// Get total balance across all mints + pub async fn total_balance(&self) -> Result { + let total = self.inner.total_balance().await?; + Ok(total.into()) + } + + /// List proofs for all mints + pub async fn list_proofs(&self) -> Result { + let proofs = self.inner.list_proofs().await?; + let mut proofs_by_mint = HashMap::new(); + for (mint_url, mint_proofs) in proofs { + let ffi_proofs: Vec> = mint_proofs + .into_iter() + .map(|p| Arc::new(p.into())) + .collect(); + proofs_by_mint.insert(mint_url.to_string(), ffi_proofs); + } + Ok(proofs_by_mint) + } + + /// Receive token + pub async fn receive( + &self, + token: Arc, + options: MultiMintReceiveOptions, + ) -> Result { + let amount = self + .inner + .receive(&token.to_string(), options.into()) + .await?; + Ok(amount.into()) + } + + /// Restore wallets for a specific mint + pub async fn restore(&self, mint_url: MintUrl) -> Result { + let cdk_mint_url: cdk::mint_url::MintUrl = mint_url.try_into()?; + let amount = self.inner.restore(&cdk_mint_url).await?; + Ok(amount.into()) + } + + /// Prepare a send operation from a specific mint + pub async fn prepare_send( + &self, + mint_url: MintUrl, + amount: Amount, + options: MultiMintSendOptions, + ) -> Result, FfiError> { + let cdk_mint_url: cdk::mint_url::MintUrl = mint_url.try_into()?; + let prepared = self + .inner + .prepare_send(cdk_mint_url, amount.into(), options.into()) + .await?; + Ok(Arc::new(prepared.into())) + } + + /// Get a mint quote from a specific mint + pub async fn mint_quote( + &self, + mint_url: MintUrl, + amount: Amount, + description: Option, + ) -> Result { + let cdk_mint_url: cdk::mint_url::MintUrl = mint_url.try_into()?; + let quote = self + .inner + .mint_quote(&cdk_mint_url, amount.into(), description) + .await?; + Ok(quote.into()) + } + + /// Mint tokens at a specific mint + pub async fn mint( + &self, + mint_url: MintUrl, + quote_id: String, + spending_conditions: Option, + ) -> Result { + let cdk_mint_url: cdk::mint_url::MintUrl = mint_url.try_into()?; + let conditions = spending_conditions.map(|sc| sc.try_into()).transpose()?; + + let proofs = self + .inner + .mint(&cdk_mint_url, "e_id, conditions) + .await?; + Ok(proofs.into_iter().map(|p| Arc::new(p.into())).collect()) + } + + /// Get a melt quote from a specific mint + pub async fn melt_quote( + &self, + mint_url: MintUrl, + request: String, + options: Option, + ) -> Result { + let cdk_mint_url: cdk::mint_url::MintUrl = mint_url.try_into()?; + let cdk_options = options.map(Into::into); + let quote = self + .inner + .melt_quote(&cdk_mint_url, request, cdk_options) + .await?; + Ok(quote.into()) + } + + /// Melt tokens (pay a bolt11 invoice) + pub async fn melt( + &self, + bolt11: String, + options: Option, + max_fee: Option, + ) -> Result { + let cdk_options = options.map(Into::into); + let cdk_max_fee = max_fee.map(Into::into); + let melted = self.inner.melt(&bolt11, cdk_options, cdk_max_fee).await?; + Ok(melted.into()) + } + + /// Transfer funds between mints + pub async fn transfer( + &self, + source_mint: MintUrl, + target_mint: MintUrl, + transfer_mode: TransferMode, + ) -> Result { + let source_cdk: cdk::mint_url::MintUrl = source_mint.try_into()?; + let target_cdk: cdk::mint_url::MintUrl = target_mint.try_into()?; + let result = self + .inner + .transfer(&source_cdk, &target_cdk, transfer_mode.into()) + .await?; + Ok(result.into()) + } + + /// Swap proofs with automatic wallet selection + pub async fn swap( + &self, + amount: Option, + spending_conditions: Option, + ) -> Result, FfiError> { + let conditions = spending_conditions.map(|sc| sc.try_into()).transpose()?; + + let result = self.inner.swap(amount.map(Into::into), conditions).await?; + + Ok(result.map(|proofs| proofs.into_iter().map(|p| Arc::new(p.into())).collect())) + } + + /// List transactions from all mints + pub async fn list_transactions( + &self, + direction: Option, + ) -> Result, FfiError> { + let cdk_direction = direction.map(Into::into); + let transactions = self.inner.list_transactions(cdk_direction).await?; + Ok(transactions.into_iter().map(Into::into).collect()) + } + + /// Check all mint quotes and mint if paid + pub async fn check_all_mint_quotes( + &self, + mint_url: Option, + ) -> Result { + let cdk_mint_url = mint_url.map(|url| url.try_into()).transpose()?; + let amount = self.inner.check_all_mint_quotes(cdk_mint_url).await?; + Ok(amount.into()) + } + + /// Consolidate proofs across all mints + pub async fn consolidate(&self) -> Result { + let amount = self.inner.consolidate().await?; + Ok(amount.into()) + } + + /// Get list of mint URLs + pub async fn get_mint_urls(&self) -> Vec { + let wallets = self.inner.get_wallets().await; + wallets.iter().map(|w| w.mint_url.to_string()).collect() + } + + /// Verify token DLEQ proofs + pub async fn verify_token_dleq(&self, token: Arc) -> Result<(), FfiError> { + let cdk_token = token.inner.clone(); + self.inner.verify_token_dleq(&cdk_token).await?; + Ok(()) + } +} + +/// Transfer mode for mint-to-mint transfers +#[derive(Debug, Clone, uniffi::Enum)] +pub enum TransferMode { + /// Transfer exact amount to target (target receives specified amount) + ExactReceive { amount: Amount }, + /// Transfer all available balance (source will be emptied) + FullBalance, +} + +impl From for CdkTransferMode { + fn from(mode: TransferMode) -> Self { + match mode { + TransferMode::ExactReceive { amount } => CdkTransferMode::ExactReceive(amount.into()), + TransferMode::FullBalance => CdkTransferMode::FullBalance, + } + } +} + +/// Result of a transfer operation with detailed breakdown +#[derive(Debug, Clone, uniffi::Record)] +pub struct TransferResult { + /// Amount deducted from source mint + pub amount_sent: Amount, + /// Amount received at target mint + pub amount_received: Amount, + /// Total fees paid for the transfer + pub fees_paid: Amount, + /// Remaining balance in source mint after transfer + pub source_balance_after: Amount, + /// New balance in target mint after transfer + pub target_balance_after: Amount, +} + +impl From for TransferResult { + fn from(result: CdkTransferResult) -> Self { + Self { + amount_sent: result.amount_sent.into(), + amount_received: result.amount_received.into(), + fees_paid: result.fees_paid.into(), + source_balance_after: result.source_balance_after.into(), + target_balance_after: result.target_balance_after.into(), + } + } +} + +/// Options for receiving tokens in multi-mint context +#[derive(Debug, Clone, Default, uniffi::Record)] +pub struct MultiMintReceiveOptions { + /// Whether to allow receiving from untrusted (not yet added) mints + pub allow_untrusted: bool, + /// Mint URL to transfer tokens to from untrusted mints (None means keep in original mint) + pub transfer_to_mint: Option, + /// Base receive options to apply to the wallet receive + pub receive_options: ReceiveOptions, +} + +impl From for CdkMultiMintReceiveOptions { + fn from(options: MultiMintReceiveOptions) -> Self { + let mut opts = CdkMultiMintReceiveOptions::new(); + opts.allow_untrusted = options.allow_untrusted; + opts.transfer_to_mint = options.transfer_to_mint.and_then(|url| url.try_into().ok()); + opts.receive_options = options.receive_options.into(); + opts + } +} + +/// Options for sending tokens in multi-mint context +#[derive(Debug, Clone, Default, uniffi::Record)] +pub struct MultiMintSendOptions { + /// Whether to allow transferring funds from other mints if needed + pub allow_transfer: bool, + /// Maximum amount to transfer from other mints (optional limit) + pub max_transfer_amount: Option, + /// Specific mint URLs allowed for transfers (empty means all mints allowed) + pub allowed_mints: Vec, + /// Specific mint URLs to exclude from transfers + pub excluded_mints: Vec, + /// Base send options to apply to the wallet send + pub send_options: SendOptions, +} + +impl From for CdkMultiMintSendOptions { + fn from(options: MultiMintSendOptions) -> Self { + let mut opts = CdkMultiMintSendOptions::new(); + opts.allow_transfer = options.allow_transfer; + opts.max_transfer_amount = options.max_transfer_amount.map(Into::into); + opts.allowed_mints = options + .allowed_mints + .into_iter() + .filter_map(|url| url.try_into().ok()) + .collect(); + opts.excluded_mints = options + .excluded_mints + .into_iter() + .filter_map(|url| url.try_into().ok()) + .collect(); + opts.send_options = options.send_options.into(); + opts + } +} + +/// Type alias for balances by mint URL +pub type BalanceMap = HashMap; + +/// Type alias for proofs by mint URL +pub type ProofsByMint = HashMap>>; diff --git a/crates/cdk/src/wallet/builder.rs b/crates/cdk/src/wallet/builder.rs index 2b2583d02..500b77a4f 100644 --- a/crates/cdk/src/wallet/builder.rs +++ b/crates/cdk/src/wallet/builder.rs @@ -111,6 +111,12 @@ impl WalletBuilder { self } + /// Set a custom client connector from Arc + pub fn shared_client(mut self, client: Arc) -> Self { + self.client = Some(client); + self + } + /// Set auth CAT (Clear Auth Token) #[cfg(feature = "auth")] pub fn set_auth_cat(mut self, cat: String) -> Self { diff --git a/crates/cdk/src/wallet/mod.rs b/crates/cdk/src/wallet/mod.rs index 8a80f92ba..43c738d02 100644 --- a/crates/cdk/src/wallet/mod.rs +++ b/crates/cdk/src/wallet/mod.rs @@ -61,7 +61,7 @@ pub use mint_connector::transport::Transport as HttpTransport; #[cfg(feature = "auth")] pub use mint_connector::AuthHttpClient; pub use mint_connector::{HttpClient, MintConnector}; -pub use multi_mint_wallet::MultiMintWallet; +pub use multi_mint_wallet::{MultiMintReceiveOptions, MultiMintSendOptions, MultiMintWallet}; pub use receive::ReceiveOptions; pub use send::{PreparedSend, SendMemo, SendOptions}; pub use types::{MeltQuote, MintQuote, SendKind}; diff --git a/crates/cdk/src/wallet/multi_mint_wallet.rs b/crates/cdk/src/wallet/multi_mint_wallet.rs index 3850620b8..c71a72698 100644 --- a/crates/cdk/src/wallet/multi_mint_wallet.rs +++ b/crates/cdk/src/wallet/multi_mint_wallet.rs @@ -3,95 +3,251 @@ //! Wrapper around core [`Wallet`] that enables the use of multiple mint unit //! pairs -use std::collections::{BTreeMap, HashMap}; +use std::collections::BTreeMap; use std::str::FromStr; use std::sync::Arc; use anyhow::Result; use cdk_common::database; use cdk_common::database::WalletDatabase; -use cdk_common::wallet::{Transaction, TransactionDirection, WalletKey}; +use cdk_common::wallet::{Transaction, TransactionDirection}; use tokio::sync::RwLock; use tracing::instrument; use zeroize::Zeroize; +use super::builder::WalletBuilder; use super::receive::ReceiveOptions; use super::send::{PreparedSend, SendOptions}; use super::Error; use crate::amount::SplitTarget; use crate::mint_url::MintUrl; +use crate::nuts::nut00::ProofsMethods; +use crate::nuts::nut23::QuoteState; use crate::nuts::{CurrencyUnit, MeltOptions, Proof, Proofs, SpendingConditions, Token}; use crate::types::Melted; use crate::wallet::types::MintQuote; -use crate::{ensure_cdk, Amount, Wallet}; +use crate::{Amount, Wallet}; -/// Multi Mint Wallet +// Transfer timeout constants +/// Total timeout for waiting for Lightning payment confirmation during transfers +/// This needs to be long enough to handle slow networks and Lightning routing +const TRANSFER_PAYMENT_TIMEOUT_SECS: u64 = 120; // 2 minutes + +/// Transfer mode for mint-to-mint transfers +#[derive(Debug, Clone)] +pub enum TransferMode { + /// Transfer exact amount to target (target receives specified amount) + ExactReceive(Amount), + /// Transfer all available balance (source will be emptied) + FullBalance, +} + +/// Result of a transfer operation with detailed breakdown #[derive(Debug, Clone)] +pub struct TransferResult { + /// Amount deducted from source mint + pub amount_sent: Amount, + /// Amount received at target mint + pub amount_received: Amount, + /// Total fees paid for the transfer + pub fees_paid: Amount, + /// Remaining balance in source mint after transfer + pub source_balance_after: Amount, + /// New balance in target mint after transfer + pub target_balance_after: Amount, +} + +/// Multi Mint Wallet +/// +/// A wallet that manages multiple mints but supports only one currency unit. +/// This simplifies the interface by removing the need to specify both mint and unit. +/// +/// # Examples +/// +/// ## Creating and using a multi-mint wallet +/// ```ignore +/// # use cdk::wallet::MultiMintWallet; +/// # use cdk::mint_url::MintUrl; +/// # use cdk::Amount; +/// # use cdk::nuts::CurrencyUnit; +/// # use std::sync::Arc; +/// # async fn example() -> Result<(), Box> { +/// // Create a multi-mint wallet with a database +/// // For real usage, you would use cdk_sqlite::wallet::memory::empty().await? or similar +/// let seed = [0u8; 64]; // Use a secure random seed in production +/// let database = cdk_sqlite::wallet::memory::empty().await?; +/// +/// let wallet = MultiMintWallet::new( +/// Arc::new(database), +/// seed, +/// CurrencyUnit::Sat, +/// ).await?; +/// +/// // Add mints to the wallet +/// let mint_url1: MintUrl = "https://mint1.example.com".parse()?; +/// let mint_url2: MintUrl = "https://mint2.example.com".parse()?; +/// wallet.add_mint(mint_url1.clone(), None).await?; +/// wallet.add_mint(mint_url2, None).await?; +/// +/// // Check total balance across all mints +/// let balance = wallet.total_balance().await?; +/// println!("Total balance: {} sats", balance); +/// +/// // Send tokens from a specific mint +/// let prepared = wallet.prepare_send( +/// mint_url1, +/// Amount::from(100), +/// Default::default() +/// ).await?; +/// let token = prepared.confirm(None).await?; +/// # Ok(()) +/// # } +/// ``` +#[derive(Clone)] pub struct MultiMintWallet { /// Storage backend - pub localstore: Arc + Send + Sync>, + localstore: Arc + Send + Sync>, seed: [u8; 64], - /// Wallets - pub wallets: Arc>>, + /// The currency unit this wallet supports + unit: CurrencyUnit, + /// Wallets indexed by mint URL + wallets: Arc>>, + /// Proxy configuration for HTTP clients (optional) + proxy_config: Option, } impl MultiMintWallet { - /// Create a new [MultiMintWallet] with initial wallets - pub fn new( + /// Create a new [MultiMintWallet] for a specific currency unit + pub async fn new( localstore: Arc + Send + Sync>, seed: [u8; 64], - wallets: Vec, - ) -> Self { - Self { + unit: CurrencyUnit, + ) -> Result { + let wallet = Self { localstore, seed, - wallets: Arc::new(RwLock::new( - wallets - .into_iter() - .map(|w| (WalletKey::new(w.mint_url.clone(), w.unit.clone()), w)) - .collect(), - )), - } + unit, + wallets: Arc::new(RwLock::new(BTreeMap::new())), + proxy_config: None, + }; + + // Automatically load wallets from database for this currency unit + wallet.load_wallets().await?; + + Ok(wallet) } - /// Adds a [Wallet] to this [MultiMintWallet] - #[instrument(skip(self, wallet))] - pub async fn add_wallet(&self, wallet: Wallet) { - let wallet_key = WalletKey::new(wallet.mint_url.clone(), wallet.unit.clone()); + /// Create a new [MultiMintWallet] with proxy configuration + /// + /// All wallets in this MultiMintWallet will use the specified proxy. + /// This allows you to route all mint connections through a proxy server. + pub async fn new_with_proxy( + localstore: Arc + Send + Sync>, + seed: [u8; 64], + unit: CurrencyUnit, + proxy_url: url::Url, + ) -> Result { + let wallet = Self { + localstore, + seed, + unit, + wallets: Arc::new(RwLock::new(BTreeMap::new())), + proxy_config: Some(proxy_url), + }; - let mut wallets = self.wallets.write().await; + // Automatically load wallets from database for this currency unit + wallet.load_wallets().await?; - wallets.insert(wallet_key, wallet); + Ok(wallet) } - /// Creates a new [Wallet] and adds it to this [MultiMintWallet] - pub async fn create_and_add_wallet( + /// Adds a mint to this [MultiMintWallet] + #[instrument(skip(self))] + pub async fn add_mint( &self, - mint_url: &str, - unit: CurrencyUnit, + mint_url: MintUrl, target_proof_count: Option, - ) -> Result { - let wallet = Wallet::new( - mint_url, - unit, - self.localstore.clone(), - self.seed, - target_proof_count, - )?; + ) -> Result<(), Error> { + let wallet = if let Some(proxy_url) = &self.proxy_config { + // Create wallet with proxy-configured client + let client = crate::wallet::HttpClient::with_proxy( + mint_url.clone(), + proxy_url.clone(), + None, + true, + ) + .unwrap_or_else(|_| { + #[cfg(feature = "auth")] + { + crate::wallet::HttpClient::new(mint_url.clone(), None) + } + #[cfg(not(feature = "auth"))] + { + crate::wallet::HttpClient::new(mint_url.clone()) + } + }); + WalletBuilder::new() + .mint_url(mint_url.clone()) + .unit(self.unit.clone()) + .localstore(self.localstore.clone()) + .seed(self.seed) + .target_proof_count(target_proof_count.unwrap_or(3)) + .client(client) + .build()? + } else { + // Create wallet with default client + Wallet::new( + &mint_url.to_string(), + self.unit.clone(), + self.localstore.clone(), + self.seed, + target_proof_count, + )? + }; wallet.fetch_mint_info().await?; + wallet.refresh_keysets().await?; - self.add_wallet(wallet.clone()).await; + let mut wallets = self.wallets.write().await; + wallets.insert(mint_url, wallet); - Ok(wallet) + Ok(()) } - /// Remove Wallet from MultiMintWallet + /// Remove mint from MultiMintWallet #[instrument(skip(self))] - pub async fn remove_wallet(&self, wallet_key: &WalletKey) { + pub async fn remove_mint(&self, mint_url: &MintUrl) { let mut wallets = self.wallets.write().await; + wallets.remove(mint_url); + } + + /// Load all wallets from database that have proofs for this currency unit + #[instrument(skip(self))] + async fn load_wallets(&self) -> Result<(), Error> { + let mints = self.localstore.get_mints().await.map_err(Error::Database)?; - wallets.remove(wallet_key); + // Get all proofs for this currency unit to determine which mints are relevant + let all_proofs = self + .localstore + .get_proofs(None, Some(self.unit.clone()), None, None) + .await + .map_err(Error::Database)?; + + for (mint_url, _mint_info) in mints { + // Check if this mint has any proofs for the specified currency unit + // or if we have no proofs at all (initial setup) + let mint_has_proofs_for_unit = + all_proofs.is_empty() || all_proofs.iter().any(|proof| proof.mint_url == mint_url); + + if mint_has_proofs_for_unit { + // Add mint to the MultiMintWallet if not already present + if !self.has_mint(&mint_url).await { + self.add_mint(mint_url, None).await?; + } + } + } + + Ok(()) } /// Get Wallets from MultiMintWallet @@ -102,29 +258,29 @@ impl MultiMintWallet { /// Get Wallet from MultiMintWallet #[instrument(skip(self))] - pub async fn get_wallet(&self, wallet_key: &WalletKey) -> Option { - self.wallets.read().await.get(wallet_key).cloned() + pub async fn get_wallet(&self, mint_url: &MintUrl) -> Option { + self.wallets.read().await.get(mint_url).cloned() } - /// Check if mint unit pair is in wallet + /// Check if mint is in wallet #[instrument(skip(self))] - pub async fn has(&self, wallet_key: &WalletKey) -> bool { - self.wallets.read().await.contains_key(wallet_key) + pub async fn has_mint(&self, mint_url: &MintUrl) -> bool { + self.wallets.read().await.contains_key(mint_url) + } + + /// Get the currency unit for this wallet + pub fn unit(&self) -> &CurrencyUnit { + &self.unit } - /// Get wallet balances + /// Get wallet balances for all mints #[instrument(skip(self))] - pub async fn get_balances( - &self, - unit: &CurrencyUnit, - ) -> Result, Error> { + pub async fn get_balances(&self) -> Result, Error> { let mut balances = BTreeMap::new(); - for (WalletKey { mint_url, unit: u }, wallet) in self.wallets.read().await.iter() { - if unit == u { - let wallet_balance = wallet.total_balance().await?; - balances.insert(mint_url.clone(), wallet_balance); - } + for (mint_url, wallet) in self.wallets.read().await.iter() { + let wallet_balance = wallet.total_balance().await?; + balances.insert(mint_url.clone(), wallet_balance); } Ok(balances) @@ -132,14 +288,12 @@ impl MultiMintWallet { /// List proofs. #[instrument(skip(self))] - pub async fn list_proofs( - &self, - ) -> Result, CurrencyUnit)>, Error> { + pub async fn list_proofs(&self) -> Result>, Error> { let mut mint_proofs = BTreeMap::new(); - for (WalletKey { mint_url, unit: u }, wallet) in self.wallets.read().await.iter() { + for (mint_url, wallet) in self.wallets.read().await.iter() { let wallet_proofs = wallet.get_unspent_proofs().await?; - mint_proofs.insert(mint_url.clone(), (wallet_proofs, u.clone())); + mint_proofs.insert(mint_url.clone(), wallet_proofs); } Ok(mint_proofs) } @@ -162,34 +316,430 @@ impl MultiMintWallet { Ok(transactions) } - /// Prepare to send + /// Get total balance across all wallets (since all wallets use the same currency unit) + #[instrument(skip(self))] + pub async fn total_balance(&self) -> Result { + let mut total = Amount::ZERO; + for (_, wallet) in self.wallets.read().await.iter() { + total += wallet.total_balance().await?; + } + Ok(total) + } + + /// Prepare to send tokens from a specific mint with optional transfer from other mints + /// + /// This method ensures that sends always happen from only one mint. If the specified + /// mint doesn't have sufficient balance and `allow_transfer` is enabled in options, + /// it will first transfer funds from other mints to the target mint. #[instrument(skip(self))] pub async fn prepare_send( &self, - wallet_key: &WalletKey, + mint_url: MintUrl, amount: Amount, - opts: SendOptions, + opts: MultiMintSendOptions, ) -> Result { + // Ensure the mint exists + let wallets = self.wallets.read().await; + let target_wallet = wallets.get(&mint_url).ok_or(Error::UnknownMint { + mint_url: mint_url.to_string(), + })?; + + // Check current balance of target mint + let target_balance = target_wallet.total_balance().await?; + + // If target mint has sufficient balance, prepare send directly + if target_balance >= amount { + return target_wallet.prepare_send(amount, opts.send_options).await; + } + + // If transfer is not allowed, return insufficient funds error + if !opts.allow_transfer { + return Err(Error::InsufficientFunds); + } + + // Calculate how much we need to transfer + let transfer_needed = amount - target_balance; + + // Check if transfer amount exceeds max_transfer_amount + if let Some(max_transfer) = opts.max_transfer_amount { + if transfer_needed > max_transfer { + return Err(Error::InsufficientFunds); + } + } + + // Find source wallets with available funds for transfer + let mut available_for_transfer = Amount::ZERO; + let mut source_mints = Vec::new(); + + for (source_mint_url, wallet) in wallets.iter() { + if source_mint_url == &mint_url { + continue; // Skip the target mint + } + + // Check if this mint is excluded from transfers + if opts.excluded_mints.contains(source_mint_url) { + continue; + } + + // Check if we have a restricted allowed list and this mint isn't in it + if !opts.allowed_mints.is_empty() && !opts.allowed_mints.contains(source_mint_url) { + continue; + } + + let balance = wallet.total_balance().await?; + if balance > Amount::ZERO { + source_mints.push((source_mint_url.clone(), balance)); + available_for_transfer += balance; + } + } + + // Check if we have enough funds across all mints + if available_for_transfer < transfer_needed { + return Err(Error::InsufficientFunds); + } + + // Drop the read lock before performing transfers + drop(wallets); + + // Perform transfers from source wallets to target wallet + self.transfer_parallel(&mint_url, transfer_needed, source_mints) + .await?; + + // Now prepare the send from the target mint let wallets = self.wallets.read().await; - let wallet = wallets - .get(wallet_key) - .ok_or(Error::UnknownWallet(wallet_key.clone()))?; + let target_wallet = wallets.get(&mint_url).ok_or(Error::UnknownMint { + mint_url: mint_url.to_string(), + })?; - wallet.prepare_send(amount, opts).await + target_wallet.prepare_send(amount, opts.send_options).await + } + + /// Transfer funds from a single source wallet to target mint using Lightning Network (melt/mint) + /// + /// This function properly accounts for fees by handling different transfer modes: + /// - ExactReceive: Target receives exactly the specified amount, source pays amount + fees + /// - FullBalance: All source balance is transferred, target receives balance - fees + pub async fn transfer( + &self, + source_mint_url: &MintUrl, + target_mint_url: &MintUrl, + mode: TransferMode, + ) -> Result { + // Get wallets for the specified mints and clone them to release the lock + let (source_wallet, target_wallet) = { + let wallets = self.wallets.read().await; + let source = wallets + .get(source_mint_url) + .ok_or(Error::UnknownMint { + mint_url: source_mint_url.to_string(), + })? + .clone(); + let target = wallets + .get(target_mint_url) + .ok_or(Error::UnknownMint { + mint_url: target_mint_url.to_string(), + })? + .clone(); + (source, target) + }; + + // Get initial balance + let source_balance_initial = source_wallet.total_balance().await?; + + // Handle different transfer modes + let (final_mint_quote, final_melt_quote) = match mode { + TransferMode::ExactReceive(amount) => { + self.handle_exact_receive_transfer( + &source_wallet, + &target_wallet, + amount, + source_balance_initial, + ) + .await? + } + TransferMode::FullBalance => { + self.handle_full_balance_transfer( + &source_wallet, + &target_wallet, + source_balance_initial, + ) + .await? + } + }; + + // Execute the transfer + let (melted, actual_receive_amount) = self + .execute_transfer( + &source_wallet, + &target_wallet, + &final_mint_quote, + &final_melt_quote, + ) + .await?; + + // Get final balances + let source_balance_final = source_wallet.total_balance().await?; + let target_balance_final = target_wallet.total_balance().await?; + + let amount_sent = source_balance_initial - source_balance_final; + let fees_paid = melted.fee_paid; + + tracing::info!( + "Transferred {} from {} to {} via Lightning (sent: {} sats, received: {} sats, fee: {} sats)", + amount_sent, + source_wallet.mint_url, + target_wallet.mint_url, + amount_sent, + actual_receive_amount, + fees_paid + ); + + Ok(TransferResult { + amount_sent, + amount_received: actual_receive_amount, + fees_paid, + source_balance_after: source_balance_final, + target_balance_after: target_balance_final, + }) + } + + /// Handle exact receive transfer mode - target gets exactly the specified amount + async fn handle_exact_receive_transfer( + &self, + source_wallet: &Wallet, + target_wallet: &Wallet, + amount: Amount, + source_balance: Amount, + ) -> Result<(MintQuote, crate::wallet::types::MeltQuote), Error> { + // Step 1: Create mint quote at target mint for the exact amount we want to receive + let mint_quote = target_wallet.mint_quote(amount, None).await?; + + // Step 2: Create melt quote at source mint for the invoice + let melt_quote = source_wallet + .melt_quote(mint_quote.request.clone(), None) + .await?; + + // Step 3: Check if source has enough balance for the total amount needed (amount + melt fees) + let total_needed = melt_quote.amount + melt_quote.fee_reserve; + if source_balance < total_needed { + return Err(Error::InsufficientFunds); + } + + Ok((mint_quote, melt_quote)) + } + + /// Handle full balance transfer mode - all source balance is transferred + async fn handle_full_balance_transfer( + &self, + source_wallet: &Wallet, + target_wallet: &Wallet, + source_balance: Amount, + ) -> Result<(MintQuote, crate::wallet::types::MeltQuote), Error> { + if source_balance == Amount::ZERO { + return Err(Error::InsufficientFunds); + } + + // Step 1: Create melt quote for full balance to discover fees + // We need to create a dummy mint quote first to get an invoice + let dummy_mint_quote = target_wallet.mint_quote(source_balance, None).await?; + let probe_melt_quote = source_wallet + .melt_quote(dummy_mint_quote.request.clone(), None) + .await?; + + // Step 2: Calculate actual receive amount (balance - fees) + let receive_amount = source_balance + .checked_sub(probe_melt_quote.fee_reserve) + .ok_or(Error::InsufficientFunds)?; + + if receive_amount == Amount::ZERO { + return Err(Error::InsufficientFunds); + } + + // Step 3: Create final mint quote for the net amount + let final_mint_quote = target_wallet.mint_quote(receive_amount, None).await?; + + // Step 4: Create final melt quote with the new invoice + let final_melt_quote = source_wallet + .melt_quote(final_mint_quote.request.clone(), None) + .await?; + + Ok((final_mint_quote, final_melt_quote)) + } + + /// Execute the actual transfer using the prepared quotes + async fn execute_transfer( + &self, + source_wallet: &Wallet, + target_wallet: &Wallet, + final_mint_quote: &MintQuote, + final_melt_quote: &crate::wallet::types::MeltQuote, + ) -> Result<(Melted, Amount), Error> { + // Step 1: Subscribe to mint quote updates before melting + let mut subscription = target_wallet + .subscribe(super::WalletSubscription::Bolt11MintQuoteState(vec![ + final_mint_quote.id.clone(), + ])) + .await; + + // Step 2: Melt from source wallet using the final melt quote + let melted = source_wallet.melt(&final_melt_quote.id).await?; + + // Step 3: Wait for payment confirmation via subscription + tracing::debug!( + "Waiting for Lightning payment confirmation (max {} seconds) for transfer from {} to {}", + TRANSFER_PAYMENT_TIMEOUT_SECS, + source_wallet.mint_url, + target_wallet.mint_url + ); + + // Wait for payment notification with overall timeout + let timeout_duration = tokio::time::Duration::from_secs(TRANSFER_PAYMENT_TIMEOUT_SECS); + + loop { + match tokio::time::timeout(timeout_duration, subscription.recv()).await { + Ok(Some(notification)) => { + // Check if this is a mint quote response with paid state + if let crate::nuts::nut17::NotificationPayload::MintQuoteBolt11Response( + quote_response, + ) = notification + { + if quote_response.state == QuoteState::Paid { + // Quote is paid, now mint the tokens + target_wallet + .mint( + &final_mint_quote.id, + crate::amount::SplitTarget::default(), + None, + ) + .await?; + break; + } + } + } + Ok(None) => { + // Subscription closed + tracing::warn!("Subscription closed while waiting for mint quote payment"); + return Err(Error::TransferTimeout { + source_mint: source_wallet.mint_url.to_string(), + target_mint: target_wallet.mint_url.to_string(), + amount: final_mint_quote.amount.unwrap_or(Amount::ZERO), + }); + } + Err(_) => { + // Overall timeout reached + tracing::warn!( + "Transfer timed out after {} seconds waiting for Lightning payment confirmation", + TRANSFER_PAYMENT_TIMEOUT_SECS + ); + return Err(Error::TransferTimeout { + source_mint: source_wallet.mint_url.to_string(), + target_mint: target_wallet.mint_url.to_string(), + amount: final_mint_quote.amount.unwrap_or(Amount::ZERO), + }); + } + } + } + + let actual_receive_amount = final_mint_quote.amount.unwrap_or(Amount::ZERO); + Ok((melted, actual_receive_amount)) + } + + /// Transfer funds from multiple source wallets to target mint in parallel + async fn transfer_parallel( + &self, + target_mint_url: &MintUrl, + total_amount: Amount, + source_mints: Vec<(MintUrl, Amount)>, + ) -> Result<(), Error> { + let mut remaining_amount = total_amount; + let mut transfer_tasks = Vec::new(); + + // Create transfer tasks for each source wallet + for (source_mint_url, available_balance) in source_mints { + if remaining_amount == Amount::ZERO { + break; + } + + let transfer_amount = std::cmp::min(remaining_amount, available_balance); + remaining_amount -= transfer_amount; + + let self_clone = self.clone(); + let source_mint_url = source_mint_url.clone(); + let target_mint_url = target_mint_url.clone(); + + // Spawn parallel transfer task + #[cfg(not(target_arch = "wasm32"))] + let task = tokio::spawn(async move { + self_clone + .transfer( + &source_mint_url, + &target_mint_url, + TransferMode::ExactReceive(transfer_amount), + ) + .await + .map(|result| result.amount_received) + }); + + #[cfg(target_arch = "wasm32")] + let task = tokio::task::spawn_local(async move { + self_clone + .transfer( + &source_mint_url, + &target_mint_url, + TransferMode::ExactReceive(transfer_amount), + ) + .await + .map(|result| result.amount_received) + }); + + transfer_tasks.push(task); + } + + // Wait for all transfers to complete + let mut total_transferred = Amount::ZERO; + for task in transfer_tasks { + match task.await { + Ok(Ok(amount)) => { + total_transferred += amount; + } + Ok(Err(e)) => { + tracing::error!("Transfer failed: {}", e); + return Err(e); + } + Err(e) => { + tracing::error!("Transfer task panicked: {}", e); + return Err(Error::Internal); + } + } + } + + // Check if we transferred less than expected (accounting for fees) + // We don't return an error here as fees are expected + if total_transferred < total_amount { + let fee_paid = total_amount - total_transferred; + tracing::info!( + "Transfer completed with fees: requested {}, received {}, total fees {}", + total_amount, + total_transferred, + fee_paid + ); + } + + Ok(()) } /// Mint quote for wallet #[instrument(skip(self))] pub async fn mint_quote( &self, - wallet_key: &WalletKey, + mint_url: &MintUrl, amount: Amount, description: Option, ) -> Result { let wallets = self.wallets.read().await; - let wallet = wallets - .get(wallet_key) - .ok_or(Error::UnknownWallet(wallet_key.clone()))?; + let wallet = wallets.get(mint_url).ok_or(Error::UnknownMint { + mint_url: mint_url.to_string(), + })?; wallet.mint_quote(amount, description).await } @@ -197,78 +747,114 @@ impl MultiMintWallet { /// Check all mint quotes /// If quote is paid, wallet will mint #[instrument(skip(self))] - pub async fn check_all_mint_quotes( - &self, - wallet_key: Option, - ) -> Result, Error> { - let mut amount_minted = HashMap::new(); - match wallet_key { - Some(wallet_key) => { + pub async fn check_all_mint_quotes(&self, mint_url: Option) -> Result { + let mut total_amount = Amount::ZERO; + match mint_url { + Some(mint_url) => { let wallets = self.wallets.read().await; - let wallet = wallets - .get(&wallet_key) - .ok_or(Error::UnknownWallet(wallet_key.clone()))?; + let wallet = wallets.get(&mint_url).ok_or(Error::UnknownMint { + mint_url: mint_url.to_string(), + })?; - let amount = wallet.check_all_mint_quotes().await?; - amount_minted.insert(wallet.unit.clone(), amount); + total_amount = wallet.check_all_mint_quotes().await?; } None => { for (_, wallet) in self.wallets.read().await.iter() { let amount = wallet.check_all_mint_quotes().await?; - - amount_minted - .entry(wallet.unit.clone()) - .and_modify(|b| *b += amount) - .or_insert(amount); + total_amount += amount; } } } - Ok(amount_minted) + Ok(total_amount) } /// Mint a specific quote #[instrument(skip(self))] pub async fn mint( &self, - wallet_key: &WalletKey, + mint_url: &MintUrl, quote_id: &str, conditions: Option, ) -> Result { let wallets = self.wallets.read().await; - let wallet = wallets - .get(wallet_key) - .ok_or(Error::UnknownWallet(wallet_key.clone()))?; + let wallet = wallets.get(mint_url).ok_or(Error::UnknownMint { + mint_url: mint_url.to_string(), + })?; wallet .mint(quote_id, SplitTarget::default(), conditions) .await } - /// Receive token - /// Wallet must be already added to multimintwallet + /// Receive token with multi-mint options + /// + /// This method can: + /// - Receive tokens from trusted mints (already added to the wallet) + /// - Optionally receive from untrusted mints by adding them to the wallet + /// - Optionally transfer tokens from untrusted mints to a trusted mint (and remove the untrusted mint) + /// + /// # Examples + /// ```no_run + /// # use cdk::wallet::{MultiMintWallet, MultiMintReceiveOptions}; + /// # use cdk::mint_url::MintUrl; + /// # async fn example(wallet: MultiMintWallet) -> Result<(), Box> { + /// // Receive from a trusted mint + /// let token = "cashuAey..."; + /// let amount = wallet.receive(token, MultiMintReceiveOptions::default()).await?; + /// + /// // Receive from untrusted mint and add it to the wallet + /// let options = MultiMintReceiveOptions::default() + /// .allow_untrusted(true); + /// let amount = wallet.receive(token, options).await?; + /// + /// // Receive from untrusted mint, transfer to trusted mint, then remove untrusted mint + /// let trusted_mint: MintUrl = "https://trusted.mint".parse()?; + /// let options = MultiMintReceiveOptions::default() + /// .transfer_to_mint(Some(trusted_mint)); + /// let amount = wallet.receive(token, options).await?; + /// # Ok(()) + /// # } + /// ``` #[instrument(skip_all)] pub async fn receive( &self, encoded_token: &str, - opts: ReceiveOptions, + opts: MultiMintReceiveOptions, ) -> Result { let token_data = Token::from_str(encoded_token)?; let unit = token_data.unit().unwrap_or_default(); + // Ensure the token uses the same currency unit as this wallet + if unit != self.unit { + return Err(Error::MultiMintCurrencyUnitMismatch { + expected: self.unit.clone(), + found: unit, + }); + } + let mint_url = token_data.mint_url()?; + let is_trusted = self.has_mint(&mint_url).await; + + // If mint is not trusted and we don't allow untrusted mints, error + if !is_trusted && !opts.allow_untrusted { + return Err(Error::UnknownMint { + mint_url: mint_url.to_string(), + }); + } + + // If mint is untrusted and we need to transfer, ensure we have a target mint + let should_transfer = !is_trusted && opts.transfer_to_mint.is_some(); - // Check that all mints in tokes have wallets - let wallet_key = WalletKey::new(mint_url.clone(), unit.clone()); - if !self.has(&wallet_key).await { - return Err(Error::UnknownWallet(wallet_key.clone())); + // Add the untrusted mint temporarily if needed + if !is_trusted { + self.add_mint(mint_url.clone(), None).await?; } - let wallet_key = WalletKey::new(mint_url.clone(), unit); let wallets = self.wallets.read().await; - let wallet = wallets - .get(&wallet_key) - .ok_or(Error::UnknownWallet(wallet_key.clone()))?; + let wallet = wallets.get(&mint_url).ok_or(Error::UnknownMint { + mint_url: mint_url.to_string(), + })?; // We need the keysets information to properly convert from token proof to proof let keysets_info = match self @@ -284,56 +870,81 @@ impl MultiMintWallet { let mut amount_received = Amount::ZERO; - let mut mint_errors = None; - match wallet - .receive_proofs(proofs, opts, token_data.memo().clone()) + .receive_proofs(proofs, opts.receive_options, token_data.memo().clone()) .await { Ok(amount) => { amount_received += amount; } Err(err) => { - tracing::error!("Could no receive proofs for mint: {}", err); - mint_errors = Some(err); + // If we added the mint temporarily for transfer only, remove it before returning error + if !is_trusted && opts.transfer_to_mint.is_some() { + drop(wallets); + self.remove_mint(&mint_url).await; + } + return Err(err); } } - match mint_errors { - None => Ok(amount_received), - Some(err) => Err(err), - } - } + drop(wallets); - /// Pay an bolt11 invoice from specific wallet - #[instrument(skip(self, bolt11))] - pub async fn pay_invoice_for_wallet( - &self, - bolt11: &str, - options: Option, - wallet_key: &WalletKey, - max_fee: Option, - ) -> Result { - let wallets = self.wallets.read().await; - let wallet = wallets - .get(wallet_key) - .ok_or(Error::UnknownWallet(wallet_key.clone()))?; + // If we should transfer to a trusted mint, do so now + if should_transfer { + if let Some(target_mint) = opts.transfer_to_mint { + // Ensure target mint exists and is trusted + if !self.has_mint(&target_mint).await { + // Clean up untrusted mint if we're only using it for transfer + self.remove_mint(&mint_url).await; + return Err(Error::UnknownMint { + mint_url: target_mint.to_string(), + }); + } + + // Transfer the entire balance from the untrusted mint to the target mint + // Use FullBalance mode for efficient transfer of all funds + let transfer_result = self + .transfer(&mint_url, &target_mint, TransferMode::FullBalance) + .await; - let quote = wallet.melt_quote(bolt11.to_string(), options).await?; - if let Some(max_fee) = max_fee { - ensure_cdk!(quote.fee_reserve <= max_fee, Error::MaxFeeExceeded); + // Handle transfer result - log details but don't fail if balance was zero + match transfer_result { + Ok(result) => { + if result.amount_sent > Amount::ZERO { + tracing::info!( + "Transferred {} sats from untrusted mint {} to trusted mint {} (received: {}, fees: {})", + result.amount_sent, + mint_url, + target_mint, + result.amount_received, + result.fees_paid + ); + } + } + Err(Error::InsufficientFunds) => { + // No balance to transfer, which is fine + tracing::debug!("No balance to transfer from untrusted mint {}", mint_url); + } + Err(e) => return Err(e), + } + + // Remove the untrusted mint after transfer + self.remove_mint(&mint_url).await; + } } + // Note: If allow_untrusted is true but no transfer is requested, + // the untrusted mint is kept in the wallet (as intended) - wallet.melt("e.id).await + Ok(amount_received) } /// Restore #[instrument(skip(self))] - pub async fn restore(&self, wallet_key: &WalletKey) -> Result { + pub async fn restore(&self, mint_url: &MintUrl) -> Result { let wallets = self.wallets.read().await; - let wallet = wallets - .get(wallet_key) - .ok_or(Error::UnknownWallet(wallet_key.clone()))?; + let wallet = wallets.get(mint_url).ok_or(Error::UnknownMint { + mint_url: mint_url.to_string(), + })?; wallet.restore().await } @@ -342,32 +953,335 @@ impl MultiMintWallet { #[instrument(skip(self, token))] pub async fn verify_token_p2pk( &self, - wallet_key: &WalletKey, token: &Token, conditions: SpendingConditions, ) -> Result<(), Error> { + let mint_url = token.mint_url()?; let wallets = self.wallets.read().await; - let wallet = wallets - .get(wallet_key) - .ok_or(Error::UnknownWallet(wallet_key.clone()))?; + let wallet = wallets.get(&mint_url).ok_or(Error::UnknownMint { + mint_url: mint_url.to_string(), + })?; wallet.verify_token_p2pk(token, conditions).await } /// Verifys all proofs in token have valid dleq proof #[instrument(skip(self, token))] - pub async fn verify_token_dleq( - &self, - wallet_key: &WalletKey, - token: &Token, - ) -> Result<(), Error> { + pub async fn verify_token_dleq(&self, token: &Token) -> Result<(), Error> { + let mint_url = token.mint_url()?; let wallets = self.wallets.read().await; - let wallet = wallets - .get(wallet_key) - .ok_or(Error::UnknownWallet(wallet_key.clone()))?; + let wallet = wallets.get(&mint_url).ok_or(Error::UnknownMint { + mint_url: mint_url.to_string(), + })?; wallet.verify_token_dleq(token).await } + + /// Create a melt quote for a specific mint + #[instrument(skip(self, bolt11))] + pub async fn melt_quote( + &self, + mint_url: &MintUrl, + bolt11: String, + options: Option, + ) -> Result { + let wallets = self.wallets.read().await; + let wallet = wallets.get(mint_url).ok_or(Error::UnknownMint { + mint_url: mint_url.to_string(), + })?; + + wallet.melt_quote(bolt11, options).await + } + + /// Melt (pay invoice) from a specific mint using a quote ID + #[instrument(skip(self))] + pub async fn melt_with_mint( + &self, + mint_url: &MintUrl, + quote_id: &str, + ) -> Result { + let wallets = self.wallets.read().await; + let wallet = wallets.get(mint_url).ok_or(Error::UnknownMint { + mint_url: mint_url.to_string(), + })?; + + wallet.melt(quote_id).await + } + + /// Create MPP (Multi-Path Payment) melt quotes from multiple mints + /// + /// This function allows manual specification of which mints and amounts to use for MPP. + /// Returns a vector of (MintUrl, MeltQuote) pairs. + #[instrument(skip(self, bolt11))] + pub async fn mpp_melt_quote( + &self, + bolt11: String, + mint_amounts: Vec<(MintUrl, Amount)>, + ) -> Result, Error> { + let mut quotes = Vec::new(); + let mut tasks = Vec::new(); + + // Spawn parallel tasks to get quotes from each mint + for (mint_url, amount) in mint_amounts { + let wallets = self.wallets.read().await; + let wallet = wallets + .get(&mint_url) + .ok_or(Error::UnknownMint { + mint_url: mint_url.to_string(), + })? + .clone(); + drop(wallets); + + let bolt11_clone = bolt11.clone(); + let mint_url_clone = mint_url.clone(); + + // Convert amount to millisats for MeltOptions + let amount_msat = u64::from(amount) * 1000; + let options = Some(MeltOptions::new_mpp(amount_msat)); + + #[cfg(not(target_arch = "wasm32"))] + let task = tokio::spawn(async move { + let quote = wallet.melt_quote(bolt11_clone, options).await; + (mint_url_clone, quote) + }); + + #[cfg(target_arch = "wasm32")] + let task = tokio::task::spawn_local(async move { + let quote = wallet.melt_quote(bolt11_clone, options).await; + (mint_url_clone, quote) + }); + + tasks.push(task); + } + + // Collect all quote results + for task in tasks { + match task.await { + Ok((mint_url, Ok(quote))) => { + quotes.push((mint_url, quote)); + } + Ok((mint_url, Err(e))) => { + tracing::error!("Failed to get melt quote from {}: {}", mint_url, e); + return Err(e); + } + Err(e) => { + tracing::error!("Task failed: {}", e); + return Err(Error::Internal); + } + } + } + + Ok(quotes) + } + + /// Execute MPP melts using previously obtained quotes + #[instrument(skip(self))] + pub async fn mpp_melt( + &self, + quotes: Vec<(MintUrl, String)>, // (mint_url, quote_id) + ) -> Result, Error> { + let mut results = Vec::new(); + let mut tasks = Vec::new(); + + for (mint_url, quote_id) in quotes { + let wallets = self.wallets.read().await; + let wallet = wallets + .get(&mint_url) + .ok_or(Error::UnknownMint { + mint_url: mint_url.to_string(), + })? + .clone(); + drop(wallets); + + let mint_url_clone = mint_url.clone(); + + #[cfg(not(target_arch = "wasm32"))] + let task = tokio::spawn(async move { + let melted = wallet.melt("e_id).await; + (mint_url_clone, melted) + }); + + #[cfg(target_arch = "wasm32")] + let task = tokio::task::spawn_local(async move { + let melted = wallet.melt("e_id).await; + (mint_url_clone, melted) + }); + + tasks.push(task); + } + + // Collect all melt results + for task in tasks { + match task.await { + Ok((mint_url, Ok(melted))) => { + results.push((mint_url, melted)); + } + Ok((mint_url, Err(e))) => { + tracing::error!("Failed to melt from {}: {}", mint_url, e); + return Err(e); + } + Err(e) => { + tracing::error!("Task failed: {}", e); + return Err(Error::Internal); + } + } + } + + Ok(results) + } + + /// Melt (pay invoice) with automatic wallet selection (deprecated, use specific mint functions for better control) + /// + /// Automatically selects the best wallet to pay from based on: + /// - Available balance + /// - Fees + /// + /// # Examples + /// ```no_run + /// # use cdk::wallet::MultiMintWallet; + /// # use cdk::Amount; + /// # use std::sync::Arc; + /// # async fn example(wallet: Arc) -> Result<(), Box> { + /// // Pay a lightning invoice from any mint with sufficient balance + /// let invoice = "lnbc100n1p..."; + /// + /// let result = wallet.melt(invoice, None, None).await?; + /// println!("Paid {} sats, fee was {} sats", result.amount, result.fee_paid); + /// # Ok(()) + /// # } + /// ``` + #[instrument(skip(self, bolt11))] + pub async fn melt( + &self, + bolt11: &str, + options: Option, + max_fee: Option, + ) -> Result { + // Parse the invoice to get the amount + let invoice = bolt11 + .parse::() + .map_err(Error::Invoice)?; + + let amount = invoice + .amount_milli_satoshis() + .map(|msats| Amount::from(msats / 1000)) + .ok_or(Error::InvoiceAmountUndefined)?; + + let wallets = self.wallets.read().await; + let mut eligible_wallets = Vec::new(); + + for (mint_url, wallet) in wallets.iter() { + let balance = wallet.total_balance().await?; + if balance >= amount { + eligible_wallets.push((mint_url.clone(), wallet.clone())); + } + } + + if eligible_wallets.is_empty() { + return Err(Error::InsufficientFunds); + } + + // Try to get quotes from eligible wallets and select the best one + let mut best_quote = None; + let mut best_wallet = None; + + for (_, wallet) in eligible_wallets.iter() { + match wallet.melt_quote(bolt11.to_string(), options).await { + Ok(quote) => { + if let Some(max_fee) = max_fee { + if quote.fee_reserve > max_fee { + continue; + } + } + + if best_quote.is_none() { + best_quote = Some(quote); + best_wallet = Some(wallet.clone()); + } else if let Some(ref existing_quote) = best_quote { + if quote.fee_reserve < existing_quote.fee_reserve { + best_quote = Some(quote); + best_wallet = Some(wallet.clone()); + } + } + } + Err(_) => continue, + } + } + + if let (Some(quote), Some(wallet)) = (best_quote, best_wallet) { + return wallet.melt("e.id).await; + } + + Err(Error::InsufficientFunds) + } + + /// Swap proofs with automatic wallet selection + #[instrument(skip(self))] + pub async fn swap( + &self, + amount: Option, + conditions: Option, + ) -> Result, Error> { + // Find a wallet that has proofs + let wallets = self.wallets.read().await; + + for (_, wallet) in wallets.iter() { + let balance = wallet.total_balance().await?; + if balance > Amount::ZERO { + // Try to swap with this wallet + let proofs = wallet.get_unspent_proofs().await?; + if !proofs.is_empty() { + return wallet + .swap(amount, SplitTarget::default(), proofs, conditions, false) + .await; + } + } + } + + Err(Error::InsufficientFunds) + } + + /// Consolidate proofs from multiple wallets into fewer, larger proofs + /// This can help reduce the number of proofs and optimize wallet performance + #[instrument(skip(self))] + pub async fn consolidate(&self) -> Result { + let mut total_consolidated = Amount::ZERO; + let wallets = self.wallets.read().await; + + for (mint_url, wallet) in wallets.iter() { + // Get all unspent proofs for this wallet + let proofs = wallet.get_unspent_proofs().await?; + if proofs.len() > 1 { + // Consolidate by swapping all proofs for a single set + let proofs_amount = proofs.total_amount()?; + + // Swap for optimized proof set + match wallet + .swap( + Some(proofs_amount), + SplitTarget::default(), + proofs, + None, + false, + ) + .await + { + Ok(_) => { + total_consolidated += proofs_amount; + } + Err(e) => { + tracing::warn!( + "Failed to consolidate proofs for mint {:?}: {}", + mint_url, + e + ); + } + } + } + } + + Ok(total_consolidated) + } } impl Drop for MultiMintWallet { @@ -375,3 +1289,186 @@ impl Drop for MultiMintWallet { self.seed.zeroize(); } } + +/// Multi-Mint Receive Options +/// +/// Controls how tokens are received, especially from untrusted mints +#[derive(Debug, Clone, Default)] +pub struct MultiMintReceiveOptions { + /// Whether to allow receiving from untrusted (not yet added) mints + pub allow_untrusted: bool, + /// Mint to transfer tokens to from untrusted mints (None means keep in original mint) + pub transfer_to_mint: Option, + /// Base receive options to apply to the wallet receive + pub receive_options: ReceiveOptions, +} + +impl MultiMintReceiveOptions { + /// Create new default options + pub fn new() -> Self { + Default::default() + } + + /// Allow receiving from untrusted mints + pub fn allow_untrusted(mut self, allow: bool) -> Self { + self.allow_untrusted = allow; + self + } + + /// Set mint to transfer tokens to from untrusted mints + pub fn transfer_to_mint(mut self, mint_url: Option) -> Self { + self.transfer_to_mint = mint_url; + self + } + + /// Set the base receive options for the wallet operation + pub fn receive_options(mut self, options: ReceiveOptions) -> Self { + self.receive_options = options; + self + } +} + +/// Multi-Mint Send Options +/// +/// Controls transfer behavior when the target mint doesn't have sufficient balance +#[derive(Debug, Clone, Default)] +pub struct MultiMintSendOptions { + /// Whether to allow transferring funds from other mints to the sending mint + /// if the sending mint doesn't have sufficient balance + pub allow_transfer: bool, + /// Maximum amount to transfer from other mints (optional limit) + pub max_transfer_amount: Option, + /// Specific mints allowed for transfers (empty means all mints allowed) + pub allowed_mints: Vec, + /// Specific mints to exclude from transfers + pub excluded_mints: Vec, + /// Base send options to apply to the wallet send + pub send_options: SendOptions, +} + +impl MultiMintSendOptions { + /// Create new default options + pub fn new() -> Self { + Default::default() + } + + /// Enable transferring funds from other mints if needed + pub fn allow_transfer(mut self, allow: bool) -> Self { + self.allow_transfer = allow; + self + } + + /// Set maximum amount to transfer from other mints + pub fn max_transfer_amount(mut self, amount: Amount) -> Self { + self.max_transfer_amount = Some(amount); + self + } + + /// Add a mint to the allowed list for transfers + pub fn allow_mint(mut self, mint_url: MintUrl) -> Self { + self.allowed_mints.push(mint_url); + self + } + + /// Set all allowed mints for transfers + pub fn allowed_mints(mut self, mints: Vec) -> Self { + self.allowed_mints = mints; + self + } + + /// Add a mint to exclude from transfers + pub fn exclude_mint(mut self, mint_url: MintUrl) -> Self { + self.excluded_mints.push(mint_url); + self + } + + /// Set all excluded mints for transfers + pub fn excluded_mints(mut self, mints: Vec) -> Self { + self.excluded_mints = mints; + self + } + + /// Set the base send options for the wallet operation + pub fn send_options(mut self, options: SendOptions) -> Self { + self.send_options = options; + self + } +} + +#[cfg(test)] +mod tests { + use std::sync::Arc; + + use cdk_common::database::WalletDatabase; + + use super::*; + + async fn create_test_multi_wallet() -> MultiMintWallet { + let localstore: Arc + Send + Sync> = Arc::new( + cdk_sqlite::wallet::memory::empty() + .await + .expect("Failed to create in-memory database"), + ); + let seed = [0u8; 64]; + MultiMintWallet::new(localstore, seed, CurrencyUnit::Sat) + .await + .expect("Failed to create MultiMintWallet") + } + + #[tokio::test] + async fn test_total_balance_empty() { + let multi_wallet = create_test_multi_wallet().await; + let balance = multi_wallet.total_balance().await.unwrap(); + assert_eq!(balance, Amount::ZERO); + } + + #[tokio::test] + async fn test_prepare_send_insufficient_funds() { + use std::str::FromStr; + + let multi_wallet = create_test_multi_wallet().await; + let mint_url = MintUrl::from_str("https://mint1.example.com").unwrap(); + let options = MultiMintSendOptions::new(); + + let result = multi_wallet + .prepare_send(mint_url, Amount::from(1000), options) + .await; + + assert!(result.is_err()); + } + + #[tokio::test] + async fn test_consolidate_empty() { + let multi_wallet = create_test_multi_wallet().await; + let result = multi_wallet.consolidate().await.unwrap(); + assert_eq!(result, Amount::ZERO); + } + + #[tokio::test] + async fn test_multi_mint_wallet_creation() { + let multi_wallet = create_test_multi_wallet().await; + assert!(multi_wallet.wallets.try_read().is_ok()); + } + + #[tokio::test] + async fn test_multi_mint_send_options() { + use std::str::FromStr; + + let mint1 = MintUrl::from_str("https://mint1.example.com").unwrap(); + let mint2 = MintUrl::from_str("https://mint2.example.com").unwrap(); + let mint3 = MintUrl::from_str("https://mint3.example.com").unwrap(); + + let options = MultiMintSendOptions::new() + .allow_transfer(true) + .max_transfer_amount(Amount::from(500)) + .allow_mint(mint1.clone()) + .allow_mint(mint2.clone()) + .exclude_mint(mint3.clone()) + .send_options(SendOptions::default()); + + assert!(options.allow_transfer); + assert_eq!(options.max_transfer_amount, Some(Amount::from(500))); + assert_eq!(options.allowed_mints, vec![mint1, mint2]); + assert_eq!(options.excluded_mints, vec![mint3]); + } +} diff --git a/crates/cdk/src/wallet/payment_request.rs b/crates/cdk/src/wallet/payment_request.rs index f042872dc..f4c6ce3ae 100644 --- a/crates/cdk/src/wallet/payment_request.rs +++ b/crates/cdk/src/wallet/payment_request.rs @@ -22,7 +22,7 @@ use crate::nuts::nut11::{Conditions, SigFlag, SpendingConditions}; use crate::nuts::nut18::Nut10SecretRequest; use crate::nuts::{CurrencyUnit, Transport}; #[cfg(feature = "nostr")] -use crate::wallet::ReceiveOptions; +use crate::wallet::MultiMintReceiveOptions; use crate::wallet::{MultiMintWallet, SendOptions}; use crate::Wallet; @@ -356,7 +356,7 @@ impl MultiMintWallet { ) -> Result<(PaymentRequest, Option), Error> { // Collect available mints for the selected unit let mints = self - .get_balances(&CurrencyUnit::from_str(¶ms.unit)?) + .get_balances() .await? .keys() .cloned() @@ -458,7 +458,7 @@ impl MultiMintWallet { ) -> Result { // Collect available mints for the selected unit let mints = self - .get_balances(&CurrencyUnit::from_str(¶ms.unit)?) + .get_balances() .await? .keys() .cloned() @@ -536,7 +536,7 @@ impl MultiMintWallet { ); let amount = self - .receive(&token.to_string(), ReceiveOptions::default()) + .receive(&token.to_string(), MultiMintReceiveOptions::default()) .await?; // Stop after first successful receipt @@ -602,7 +602,7 @@ impl MultiMintWallet { ); let amount = self - .receive(&token.to_string(), ReceiveOptions::default()) + .receive(&token.to_string(), MultiMintReceiveOptions::default()) .await?; return Ok(amount); From 944cf2ae0b1b347db49ae98dff4677a9ae2e4fb8 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Thu, 18 Sep 2025 20:40:26 +0100 Subject: [PATCH 163/321] fix: error respose detail (#1090) --- crates/cdk-common/src/error.rs | 117 ++++++++++++--------------------- 1 file changed, 42 insertions(+), 75 deletions(-) diff --git a/crates/cdk-common/src/error.rs b/crates/cdk-common/src/error.rs index b20d1da4a..9f7efdaec 100644 --- a/crates/cdk-common/src/error.rs +++ b/crates/cdk-common/src/error.rs @@ -419,32 +419,21 @@ pub enum Error { pub struct ErrorResponse { /// Error Code pub code: ErrorCode, - /// Human readable Text - pub error: Option, - /// Longer human readable description - pub detail: Option, + /// Human readable description + #[serde(default)] + pub detail: String, } impl fmt::Display for ErrorResponse { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - write!( - f, - "code: {}, error: {}, detail: {}", - self.code, - self.error.clone().unwrap_or_default(), - self.detail.clone().unwrap_or_default() - ) + write!(f, "code: {}, detail: {}", self.code, self.detail) } } impl ErrorResponse { /// Create new [`ErrorResponse`] - pub fn new(code: ErrorCode, error: Option, detail: Option) -> Self { - Self { - code, - error, - detail, - } + pub fn new(code: ErrorCode, detail: String) -> Self { + Self { code, detail } } /// Error response from json @@ -460,8 +449,7 @@ impl ErrorResponse { Ok(res) => Ok(res), Err(_) => Ok(Self { code: ErrorCode::Unknown(999), - error: Some(value.to_string()), - detail: None, + detail: value.to_string(), }), } } @@ -482,139 +470,118 @@ impl From for ErrorResponse { match err { Error::TokenAlreadySpent => ErrorResponse { code: ErrorCode::TokenAlreadySpent, - error: Some(err.to_string()), - detail: None, + detail: err.to_string(), }, Error::UnsupportedUnit => ErrorResponse { code: ErrorCode::UnsupportedUnit, - error: Some(err.to_string()), - detail: None, + detail: err.to_string(), }, Error::PaymentFailed => ErrorResponse { code: ErrorCode::LightningError, - error: Some(err.to_string()), - detail: None, + detail: err.to_string(), }, Error::RequestAlreadyPaid => ErrorResponse { code: ErrorCode::InvoiceAlreadyPaid, - error: Some("Invoice already paid.".to_string()), - detail: None, + detail: "Invoice already paid.".to_string(), }, Error::TransactionUnbalanced(inputs_total, outputs_total, fee_expected) => { ErrorResponse { code: ErrorCode::TransactionUnbalanced, - error: Some(format!( - "Inputs: {inputs_total}, Outputs: {outputs_total}, expected_fee: {fee_expected}", - )), - detail: Some("Transaction inputs should equal outputs less fee".to_string()), + detail: format!( + "Inputs: {inputs_total}, Outputs: {outputs_total}, expected_fee: {fee_expected}. Transaction inputs should equal outputs less fee" + ), } } Error::MintingDisabled => ErrorResponse { code: ErrorCode::MintingDisabled, - error: Some(err.to_string()), - detail: None, + detail: err.to_string(), }, Error::BlindedMessageAlreadySigned => ErrorResponse { code: ErrorCode::BlindedMessageAlreadySigned, - error: Some(err.to_string()), - detail: None, + detail: err.to_string(), }, Error::InsufficientFunds => ErrorResponse { code: ErrorCode::TransactionUnbalanced, - error: Some(err.to_string()), - detail: None, + detail: err.to_string(), }, Error::AmountOutofLimitRange(_min, _max, _amount) => ErrorResponse { code: ErrorCode::AmountOutofLimitRange, - error: Some(err.to_string()), - detail: None, + detail: err.to_string(), }, Error::ExpiredQuote(_, _) => ErrorResponse { code: ErrorCode::QuoteExpired, - error: Some(err.to_string()), - detail: None, + detail: err.to_string(), }, Error::PendingQuote => ErrorResponse { code: ErrorCode::QuotePending, - error: Some(err.to_string()), - detail: None, + detail: err.to_string(), }, Error::TokenPending => ErrorResponse { code: ErrorCode::TokenPending, - error: Some(err.to_string()), - detail: None, + detail: err.to_string(), }, Error::ClearAuthRequired => ErrorResponse { code: ErrorCode::ClearAuthRequired, - error: None, - detail: None, + detail: Error::ClearAuthRequired.to_string(), }, Error::ClearAuthFailed => ErrorResponse { code: ErrorCode::ClearAuthFailed, - error: None, - detail: None, + detail: Error::ClearAuthFailed.to_string(), }, Error::BlindAuthRequired => ErrorResponse { code: ErrorCode::BlindAuthRequired, - error: None, - detail: None, + detail: Error::BlindAuthRequired.to_string(), }, Error::BlindAuthFailed => ErrorResponse { code: ErrorCode::BlindAuthFailed, - error: None, - detail: None, + detail: Error::BlindAuthFailed.to_string(), }, Error::NUT20(err) => ErrorResponse { code: ErrorCode::WitnessMissingOrInvalid, - error: Some(err.to_string()), - detail: None, + detail: err.to_string(), }, Error::DuplicateInputs => ErrorResponse { code: ErrorCode::DuplicateInputs, - error: Some(err.to_string()), - detail: None, + detail: err.to_string(), }, Error::DuplicateOutputs => ErrorResponse { code: ErrorCode::DuplicateOutputs, - error: Some(err.to_string()), - detail: None, + detail: err.to_string(), }, Error::MultipleUnits => ErrorResponse { code: ErrorCode::MultipleUnits, - error: Some(err.to_string()), - detail: None, + detail: err.to_string(), }, Error::UnitMismatch => ErrorResponse { code: ErrorCode::UnitMismatch, - error: Some(err.to_string()), - detail: None, + detail: err.to_string(), }, Error::UnpaidQuote => ErrorResponse { code: ErrorCode::QuoteNotPaid, - error: Some(err.to_string()), - detail: None + detail: Error::UnpaidQuote.to_string(), }, Error::NUT11(err) => { let code = map_nut11_error(&err); - let mut detail = None; - if matches!(err, crate::nuts::nut11::Error::SignaturesNotProvided) { - detail = Some("P2PK signatures are required but not provided".to_string()); - } + let extra = if matches!(err, crate::nuts::nut11::Error::SignaturesNotProvided) { + Some("P2PK signatures are required but not provided".to_string()) + } else { + None + }; ErrorResponse { code, - error: Some(err.to_string()), - detail, + detail: match extra { + Some(extra) => format!("{err}. {extra}"), + None => err.to_string(), + }, } }, Error::DuplicateSignatureError => ErrorResponse { code: ErrorCode::DuplicateSignature, - error: Some(err.to_string()), - detail: None, + detail: err.to_string(), }, _ => ErrorResponse { code: ErrorCode::Unknown(9999), - error: Some(err.to_string()), - detail: None, + detail: err.to_string(), }, } } From 12164a0764267bf9460b324fbe9cba405ce48744 Mon Sep 17 00:00:00 2001 From: David Caseria Date: Thu, 18 Sep 2025 15:42:00 -0400 Subject: [PATCH 164/321] Fix Async FFI Constructors (#1085) * Fix unused async in FFI * Fix FFI async constructor * Fix FFI MultiMintWallet async constructor --- Cargo.toml | 1 + crates/cdk-ffi/Cargo.toml | 2 +- crates/cdk-ffi/src/database.rs | 39 +- crates/cdk-ffi/src/lib.rs | 2 + crates/cdk-ffi/src/multi_mint_wallet.rs | 43 ++- crates/cdk-ffi/src/wallet.rs | 2 +- crates/cdk-integration-tests/Cargo.toml | 1 + .../tests/ffi_minting_integration.rs | 364 ++++++++++++++++++ 8 files changed, 439 insertions(+), 15 deletions(-) create mode 100644 crates/cdk-integration-tests/tests/ffi_minting_integration.rs diff --git a/Cargo.toml b/Cargo.toml index af070a815..8334cad88 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -52,6 +52,7 @@ cdk-lnbits = { path = "./crates/cdk-lnbits", version = "=0.12.0" } cdk-lnd = { path = "./crates/cdk-lnd", version = "=0.12.0" } cdk-ldk-node = { path = "./crates/cdk-ldk-node", version = "=0.12.0" } cdk-fake-wallet = { path = "./crates/cdk-fake-wallet", version = "=0.12.0" } +cdk-ffi = { path = "./crates/cdk-ffi", version = "=0.12.0" } cdk-payment-processor = { path = "./crates/cdk-payment-processor", default-features = true, version = "=0.12.0" } cdk-mint-rpc = { path = "./crates/cdk-mint-rpc", version = "=0.12.0" } cdk-redb = { path = "./crates/cdk-redb", default-features = true, version = "=0.12.0" } diff --git a/crates/cdk-ffi/Cargo.toml b/crates/cdk-ffi/Cargo.toml index 9419ac36d..ff61416eb 100644 --- a/crates/cdk-ffi/Cargo.toml +++ b/crates/cdk-ffi/Cargo.toml @@ -7,7 +7,7 @@ repository.workspace = true rust-version.workspace = true [lib] -crate-type = ["cdylib", "staticlib"] +crate-type = ["cdylib", "staticlib", "rlib"] name = "cdk_ffi" [features] diff --git a/crates/cdk-ffi/src/database.rs b/crates/cdk-ffi/src/database.rs index af63d221f..13819ad0e 100644 --- a/crates/cdk-ffi/src/database.rs +++ b/crates/cdk-ffi/src/database.rs @@ -579,10 +579,22 @@ impl WalletSqliteDatabase { impl WalletSqliteDatabase { /// Create a new WalletSqliteDatabase with the given work directory #[uniffi::constructor] - pub async fn new(file_path: String) -> Result, FfiError> { - let db = CdkWalletSqliteDatabase::new(file_path.as_str()) - .await - .map_err(|e| FfiError::Database { msg: e.to_string() })?; + pub fn new(file_path: String) -> Result, FfiError> { + let db = match tokio::runtime::Handle::try_current() { + Ok(handle) => tokio::task::block_in_place(|| { + handle + .block_on(async move { CdkWalletSqliteDatabase::new(file_path.as_str()).await }) + }), + Err(_) => { + // No current runtime, create a new one + tokio::runtime::Runtime::new() + .map_err(|e| FfiError::Database { + msg: format!("Failed to create runtime: {}", e), + })? + .block_on(async move { CdkWalletSqliteDatabase::new(file_path.as_str()).await }) + } + } + .map_err(|e| FfiError::Database { msg: e.to_string() })?; Ok(Arc::new(Self { inner: Arc::new(db), })) @@ -590,10 +602,21 @@ impl WalletSqliteDatabase { /// Create an in-memory database #[uniffi::constructor] - pub async fn new_in_memory() -> Result, FfiError> { - let db = cdk_sqlite::wallet::memory::empty() - .await - .map_err(|e| FfiError::Database { msg: e.to_string() })?; + pub fn new_in_memory() -> Result, FfiError> { + let db = match tokio::runtime::Handle::try_current() { + Ok(handle) => tokio::task::block_in_place(|| { + handle.block_on(async move { cdk_sqlite::wallet::memory::empty().await }) + }), + Err(_) => { + // No current runtime, create a new one + tokio::runtime::Runtime::new() + .map_err(|e| FfiError::Database { + msg: format!("Failed to create runtime: {}", e), + })? + .block_on(async move { cdk_sqlite::wallet::memory::empty().await }) + } + } + .map_err(|e| FfiError::Database { msg: e.to_string() })?; Ok(Arc::new(Self { inner: Arc::new(db), })) diff --git a/crates/cdk-ffi/src/lib.rs b/crates/cdk-ffi/src/lib.rs index 37433e54c..fe6ddabaf 100644 --- a/crates/cdk-ffi/src/lib.rs +++ b/crates/cdk-ffi/src/lib.rs @@ -2,6 +2,8 @@ //! //! UniFFI bindings for the CDK Wallet and related types. +#![warn(clippy::unused_async)] + pub mod database; pub mod error; pub mod multi_mint_wallet; diff --git a/crates/cdk-ffi/src/multi_mint_wallet.rs b/crates/cdk-ffi/src/multi_mint_wallet.rs index 4de429cf1..d8b807fb6 100644 --- a/crates/cdk-ffi/src/multi_mint_wallet.rs +++ b/crates/cdk-ffi/src/multi_mint_wallet.rs @@ -24,7 +24,7 @@ pub struct MultiMintWallet { impl MultiMintWallet { /// Create a new MultiMintWallet from mnemonic using WalletDatabase trait #[uniffi::constructor] - pub async fn new( + pub fn new( unit: CurrencyUnit, mnemonic: String, db: Arc, @@ -37,7 +37,23 @@ impl MultiMintWallet { // Convert the FFI database trait to a CDK database implementation let localstore = crate::database::create_cdk_database_from_ffi(db); - let wallet = CdkMultiMintWallet::new(localstore, seed, unit.into()).await?; + let wallet = match tokio::runtime::Handle::try_current() { + Ok(handle) => tokio::task::block_in_place(|| { + handle.block_on(async move { + CdkMultiMintWallet::new(localstore, seed, unit.into()).await + }) + }), + Err(_) => { + // No current runtime, create a new one + tokio::runtime::Runtime::new() + .map_err(|e| FfiError::Database { + msg: format!("Failed to create runtime: {}", e), + })? + .block_on(async move { + CdkMultiMintWallet::new(localstore, seed, unit.into()).await + }) + } + }?; Ok(Self { inner: Arc::new(wallet), @@ -46,7 +62,7 @@ impl MultiMintWallet { /// Create a new MultiMintWallet with proxy configuration #[uniffi::constructor] - pub async fn new_with_proxy( + pub fn new_with_proxy( unit: CurrencyUnit, mnemonic: String, db: Arc, @@ -64,8 +80,25 @@ impl MultiMintWallet { let proxy_url = url::Url::parse(&proxy_url).map_err(|e| FfiError::InvalidUrl { msg: e.to_string() })?; - let wallet = - CdkMultiMintWallet::new_with_proxy(localstore, seed, unit.into(), proxy_url).await?; + let wallet = match tokio::runtime::Handle::try_current() { + Ok(handle) => tokio::task::block_in_place(|| { + handle.block_on(async move { + CdkMultiMintWallet::new_with_proxy(localstore, seed, unit.into(), proxy_url) + .await + }) + }), + Err(_) => { + // No current runtime, create a new one + tokio::runtime::Runtime::new() + .map_err(|e| FfiError::Database { + msg: format!("Failed to create runtime: {}", e), + })? + .block_on(async move { + CdkMultiMintWallet::new_with_proxy(localstore, seed, unit.into(), proxy_url) + .await + }) + } + }?; Ok(Self { inner: Arc::new(wallet), diff --git a/crates/cdk-ffi/src/wallet.rs b/crates/cdk-ffi/src/wallet.rs index 00ee2bf9e..c463ab435 100644 --- a/crates/cdk-ffi/src/wallet.rs +++ b/crates/cdk-ffi/src/wallet.rs @@ -19,7 +19,7 @@ pub struct Wallet { impl Wallet { /// Create a new Wallet from mnemonic using WalletDatabase trait #[uniffi::constructor] - pub async fn new( + pub fn new( mint_url: String, unit: CurrencyUnit, mnemonic: String, diff --git a/crates/cdk-integration-tests/Cargo.toml b/crates/cdk-integration-tests/Cargo.toml index cc7b082e5..ed1828552 100644 --- a/crates/cdk-integration-tests/Cargo.toml +++ b/crates/cdk-integration-tests/Cargo.toml @@ -65,4 +65,5 @@ bip39 = { workspace = true, features = ["rand"] } anyhow.workspace = true cdk-axum = { workspace = true } cdk-fake-wallet = { workspace = true } +cdk-ffi = { workspace = true } tower-http = { workspace = true, features = ["cors"] } diff --git a/crates/cdk-integration-tests/tests/ffi_minting_integration.rs b/crates/cdk-integration-tests/tests/ffi_minting_integration.rs new file mode 100644 index 000000000..44857b9c8 --- /dev/null +++ b/crates/cdk-integration-tests/tests/ffi_minting_integration.rs @@ -0,0 +1,364 @@ +//! FFI Minting Integration Tests +//! +//! These tests verify the FFI wallet minting functionality through the complete +//! mint-to-tokens workflow, similar to the Swift bindings tests. The tests use +//! the actual FFI layer to ensure compatibility with language bindings. +//! +//! The tests include: +//! 1. Creating mint quotes through the FFI layer +//! 2. Simulating payment for development/testing environments +//! 3. Minting tokens and verifying amounts +//! 4. Testing the complete quote state transitions +//! 5. Validating proof generation and verification + +use std::env; +use std::path::PathBuf; +use std::str::FromStr; +use std::time::Duration; + +use bip39::Mnemonic; +use cdk_ffi::database::WalletSqliteDatabase; +use cdk_ffi::types::{Amount, CurrencyUnit, QuoteState, SplitTarget}; +use cdk_ffi::wallet::Wallet as FfiWallet; +use cdk_ffi::WalletConfig; +use cdk_integration_tests::{get_mint_url_from_env, pay_if_regtest}; +use lightning_invoice::Bolt11Invoice; +use tokio::time::timeout; + +// Helper function to get temp directory from environment or fallback +fn get_test_temp_dir() -> PathBuf { + match env::var("CDK_ITESTS_DIR") { + Ok(dir) => PathBuf::from(dir), + Err(_) => panic!("Unknown test dir"), + } +} + +/// Create a test FFI wallet with in-memory database +async fn create_test_ffi_wallet() -> FfiWallet { + let db = WalletSqliteDatabase::new_in_memory().expect("Failed to create in-memory database"); + let mnemonic = Mnemonic::generate(12).unwrap().to_string(); + let config = WalletConfig { + target_proof_count: Some(3), + }; + + FfiWallet::new( + get_mint_url_from_env(), + CurrencyUnit::Sat, + mnemonic, + db, + config, + ) + .expect("Failed to create FFI wallet") +} + +/// Tests the complete FFI minting flow from quote creation to token minting +/// +/// This test replicates the Swift integration test functionality: +/// 1. Creates an FFI wallet with in-memory database +/// 2. Creates a mint quote for 1000 sats +/// 3. Verifies the quote properties (amount, state, expiry) +/// 4. Simulates payment in test environments +/// 5. Mints tokens using the paid quote +/// 6. Verifies the minted proofs have the correct total amount +/// 7. Validates the wallet balance after minting +/// +/// This ensures the FFI layer properly handles the complete minting workflow +/// that language bindings (Swift, Python, Kotlin) will use. +#[tokio::test(flavor = "multi_thread", worker_threads = 1)] +async fn test_ffi_full_minting_flow() { + let wallet = create_test_ffi_wallet().await; + + // Verify initial wallet state + let initial_balance = wallet + .total_balance() + .await + .expect("Failed to get initial balance"); + assert_eq!(initial_balance.value, 0, "Initial balance should be zero"); + + // Test minting amount (1000 sats, matching Swift test) + let mint_amount = Amount::new(1000); + + // Step 1: Create a mint quote + let quote = wallet + .mint_quote(mint_amount, Some("FFI Integration Test".to_string())) + .await + .expect("Failed to create mint quote"); + + // Verify quote properties + assert_eq!( + quote.amount, + Some(mint_amount), + "Quote amount should match requested amount" + ); + assert_eq!(quote.unit, CurrencyUnit::Sat, "Quote unit should be sats"); + assert_eq!( + quote.state, + QuoteState::Unpaid, + "Initial quote state should be unpaid" + ); + assert!( + !quote.request.is_empty(), + "Quote should have a payment request" + ); + assert!(!quote.id.is_empty(), "Quote should have an ID"); + + // Verify the quote can be parsed as a valid invoice + let invoice = Bolt11Invoice::from_str("e.request) + .expect("Quote request should be a valid Lightning invoice"); + + // In test environments, simulate payment + pay_if_regtest(&get_test_temp_dir(), &invoice) + .await + .expect("Failed to pay invoice in test environment"); + + // Give the mint time to process the payment in test environments + tokio::time::sleep(Duration::from_millis(1000)).await; + + // Step 2: Wait for payment and mint tokens + // We'll use a timeout to avoid hanging in case of issues + let mint_result = timeout(Duration::from_secs(30), async { + // Keep checking quote status until it's paid, then mint + let mut attempts = 0; + let max_attempts = 10; + + loop { + attempts += 1; + if attempts > max_attempts { + panic!( + "Quote never transitioned to paid state after {} attempts", + max_attempts + ); + } + + // In a real scenario, we'd check quote status, but for integration tests + // we'll try to mint directly and handle any errors + match wallet.mint(quote.id.clone(), SplitTarget::None, None).await { + Ok(proofs) => break proofs, + Err(e) => { + // If quote isn't paid yet, wait and retry + if e.to_string().contains("quote not paid") || e.to_string().contains("unpaid") + { + tokio::time::sleep(Duration::from_millis(2000)).await; + continue; + } else { + panic!("Unexpected error while minting: {}", e); + } + } + } + } + }) + .await + .expect("Timeout waiting for minting to complete"); + + // Step 3: Verify minted proofs + assert!( + !mint_result.is_empty(), + "Should have minted at least one proof" + ); + + // Calculate total amount of minted proofs + let total_minted: u64 = mint_result.iter().map(|proof| proof.amount().value).sum(); + assert_eq!( + total_minted, mint_amount.value, + "Total minted amount should equal requested amount" + ); + + // Verify each proof has valid properties + for proof in &mint_result { + assert!( + proof.amount().value > 0, + "Each proof should have positive amount" + ); + assert!( + !proof.secret().is_empty(), + "Each proof should have a secret" + ); + assert!(!proof.c().is_empty(), "Each proof should have a C value"); + } + + // Step 4: Verify wallet balance after minting + let final_balance = wallet + .total_balance() + .await + .expect("Failed to get final balance"); + assert_eq!( + final_balance.value, mint_amount.value, + "Final wallet balance should equal minted amount" + ); + + println!( + "✅ FFI minting test completed successfully: minted {} sats in {} proofs", + total_minted, + mint_result.len() + ); +} + +/// Tests FFI wallet quote creation and validation +/// +/// This test focuses on the quote creation aspects: +/// 1. Creates quotes for different amounts +/// 2. Verifies quote properties and validation +/// 3. Tests quote serialization/deserialization +/// 4. Ensures quotes have proper expiry times +#[tokio::test(flavor = "multi_thread", worker_threads = 1)] +async fn test_ffi_mint_quote_creation() { + let wallet = create_test_ffi_wallet().await; + + // Test different quote amounts + let test_amounts = vec![100, 500, 1000, 2100]; // Including amount that requires split + + for amount_value in test_amounts { + let amount = Amount::new(amount_value); + let description = format!("Test quote for {} sats", amount_value); + + let quote = wallet + .mint_quote(amount, Some(description.clone())) + .await + .expect(&format!("Failed to create quote for {} sats", amount_value)); + + // Verify quote properties + assert_eq!(quote.amount, Some(amount)); + assert_eq!(quote.unit, CurrencyUnit::Sat); + assert_eq!(quote.state, QuoteState::Unpaid); + assert!(!quote.id.is_empty()); + assert!(!quote.request.is_empty()); + + // Verify the payment request is a valid Lightning invoice + let invoice = Bolt11Invoice::from_str("e.request) + .expect("Quote request should be a valid Lightning invoice"); + + // The invoice amount should match the quote amount (in millisats) + assert_eq!( + invoice.amount_milli_satoshis(), + Some(amount_value * 1000), + "Invoice amount should match quote amount" + ); + + // Test quote JSON serialization (useful for bindings that need JSON) + let quote_json = quote.to_json().expect("Quote should serialize to JSON"); + assert!(!quote_json.is_empty(), "Quote JSON should not be empty"); + + println!( + "✅ Quote created for {} sats: ID={}, Invoice amount={}msat", + amount_value, + quote.id, + invoice.amount_milli_satoshis().unwrap_or(0) + ); + } +} + +/// Tests error handling in FFI minting operations +/// +/// This test verifies proper error handling: +/// 1. Invalid mint URLs +/// 2. Invalid amounts (zero, too large) +/// 3. Attempting to mint unpaid quotes +/// 4. Network connectivity issues +#[tokio::test(flavor = "multi_thread", worker_threads = 1)] +async fn test_ffi_minting_error_handling() { + // Test invalid mint URL + let db = WalletSqliteDatabase::new_in_memory().expect("Failed to create database"); + let mnemonic = Mnemonic::generate(12).unwrap().to_string(); + let config = WalletConfig { + target_proof_count: Some(3), + }; + + let invalid_wallet_result = FfiWallet::new( + "invalid-url".to_string(), + CurrencyUnit::Sat, + mnemonic.clone(), + db, + config.clone(), + ); + assert!( + invalid_wallet_result.is_err(), + "Should fail to create wallet with invalid URL" + ); + + // Test with valid wallet for other error cases + let wallet = create_test_ffi_wallet().await; + + // Test zero amount quote (should fail) + let zero_amount_result = wallet.mint_quote(Amount::new(0), None).await; + assert!( + zero_amount_result.is_err(), + "Should fail to create quote with zero amount" + ); + + // Test minting with non-existent quote ID + let invalid_mint_result = wallet + .mint("non-existent-quote-id".to_string(), SplitTarget::None, None) + .await; + assert!( + invalid_mint_result.is_err(), + "Should fail to mint with non-existent quote ID" + ); + + println!("✅ Error handling tests completed successfully"); +} + +/// Tests FFI wallet configuration options +/// +/// This test verifies different wallet configurations: +/// 1. Different target proof counts +/// 2. Different currency units (if supported) +/// 3. Wallet restoration with same mnemonic +#[tokio::test(flavor = "multi_thread", worker_threads = 1)] +async fn test_ffi_wallet_configuration() { + let mint_url = get_mint_url_from_env(); + let mnemonic = Mnemonic::generate(12).unwrap().to_string(); + + // Test different target proof counts + let proof_counts = vec![1, 3, 5, 10]; + + for target_count in proof_counts { + let db = WalletSqliteDatabase::new_in_memory().expect("Failed to create database"); + let config = WalletConfig { + target_proof_count: Some(target_count), + }; + + let wallet = FfiWallet::new( + mint_url.clone(), + CurrencyUnit::Sat, + mnemonic.clone(), + db, + config, + ) + .expect("Failed to create wallet"); + + // Verify wallet properties + assert_eq!(wallet.mint_url().url, mint_url); + assert_eq!(wallet.unit(), CurrencyUnit::Sat); + + println!( + "✅ Wallet created with target proof count: {}", + target_count + ); + } + + // Test wallet restoration with same mnemonic + let db1 = WalletSqliteDatabase::new_in_memory().expect("Failed to create database"); + let db2 = WalletSqliteDatabase::new_in_memory().expect("Failed to create database"); + + let config = WalletConfig { + target_proof_count: Some(3), + }; + + let wallet1 = FfiWallet::new( + mint_url.clone(), + CurrencyUnit::Sat, + mnemonic.clone(), + db1, + config.clone(), + ) + .expect("Failed to create first wallet"); + + let wallet2 = FfiWallet::new(mint_url, CurrencyUnit::Sat, mnemonic, db2, config) + .expect("Failed to create second wallet"); + + // Both wallets should have the same mint URL and unit + assert_eq!(wallet1.mint_url().url, wallet2.mint_url().url); + assert_eq!(wallet1.unit(), wallet2.unit()); + + println!("✅ Wallet configuration tests completed successfully"); +} From f4c5de7f36c5849567e455cba058c5afa1404c68 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Fri, 19 Sep 2025 10:32:54 +0100 Subject: [PATCH 165/321] fix: add free space to auth test (#1091) --- .github/workflows/ci.yml | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 08e95af44..bc3115048 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -443,6 +443,16 @@ jobs: steps: - name: checkout uses: actions/checkout@v4 + - name: Free Disk Space (Ubuntu) + uses: jlumbroso/free-disk-space@main + with: + tool-cache: false + android: true + dotnet: true + haskell: true + large-packages: true + docker-images: true + swap-storage: true - name: Install Nix uses: DeterminateSystems/nix-installer-action@v17 - name: Nix Cache From aeafab9a10b40bce657c640bb5ee325d189157e8 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Sat, 20 Sep 2025 16:49:37 +0100 Subject: [PATCH 166/321] fix: config overwrite on start up (#1081) * fix: config overwrite on start up --- crates/cdk-common/src/database/mint/mod.rs | 15 +- .../src/bin/start_regtest_mints.rs | 1 + .../src/init_pure_tests.rs | 9 +- crates/cdk-integration-tests/src/shared.rs | 5 + crates/cdk-integration-tests/tests/mint.rs | 6 +- crates/cdk-mintd/example.config.toml | 6 + crates/cdk-mintd/src/config.rs | 8 + crates/cdk-mintd/src/env_vars/common.rs | 3 + crates/cdk-mintd/src/env_vars/info.rs | 23 +++ crates/cdk-mintd/src/lib.rs | 70 +++++++-- crates/cdk-sql-common/src/mint/migrations.rs | 2 + .../20250916221000_drop_config_table.sql | 1 + .../20250916221000_drop_config_table.sql | 1 + crates/cdk-sql-common/src/mint/mod.rs | 102 +----------- crates/cdk-sqlite/src/mint/memory.rs | 13 +- crates/cdk/src/mint/builder.rs | 33 ++++ crates/cdk/src/mint/issue/mod.rs | 4 +- crates/cdk/src/mint/melt.rs | 4 +- crates/cdk/src/mint/mod.rs | 145 ++++++++++++++---- 19 files changed, 279 insertions(+), 172 deletions(-) create mode 100644 crates/cdk-sql-common/src/mint/migrations/postgres/20250916221000_drop_config_table.sql create mode 100644 crates/cdk-sql-common/src/mint/migrations/sqlite/20250916221000_drop_config_table.sql diff --git a/crates/cdk-common/src/database/mint/mod.rs b/crates/cdk-common/src/database/mint/mod.rs index f54a9b8ca..01af134ee 100644 --- a/crates/cdk-common/src/database/mint/mod.rs +++ b/crates/cdk-common/src/database/mint/mod.rs @@ -4,10 +4,9 @@ use std::collections::HashMap; use async_trait::async_trait; use cashu::quote_id::QuoteId; -use cashu::{Amount, MintInfo}; +use cashu::Amount; use super::Error; -use crate::common::QuoteTTL; use crate::mint::{self, MintKeySetInfo, MintQuote as MintMintQuote}; use crate::nuts::{ BlindSignature, BlindedMessage, CurrencyUnit, Id, MeltQuoteState, Proof, Proofs, PublicKey, @@ -396,7 +395,6 @@ pub trait KVStoreTransaction<'a, Error>: DbTransactionFinalizer { } /// Base database writer -#[async_trait] pub trait Transaction<'a, Error>: DbTransactionFinalizer + QuotesTransaction<'a, Err = Error> @@ -404,11 +402,6 @@ pub trait Transaction<'a, Error>: + ProofsTransaction<'a, Err = Error> + KVStoreTransaction<'a, Error> { - /// Set [`QuoteTTL`] - async fn set_quote_ttl(&mut self, quote_ttl: QuoteTTL) -> Result<(), Error>; - - /// Set [`MintInfo`] - async fn set_mint_info(&mut self, mint_info: MintInfo) -> Result<(), Error>; } /// Key-Value Store Database trait @@ -457,12 +450,6 @@ pub trait Database: async fn begin_transaction<'a>( &'a self, ) -> Result + Send + Sync + 'a>, Error>; - - /// Get [`MintInfo`] - async fn get_mint_info(&self) -> Result; - - /// Get [`QuoteTTL`] - async fn get_quote_ttl(&self) -> Result; } /// Type alias for Mint Database diff --git a/crates/cdk-integration-tests/src/bin/start_regtest_mints.rs b/crates/cdk-integration-tests/src/bin/start_regtest_mints.rs index 67dc1f9ad..7777ef743 100644 --- a/crates/cdk-integration-tests/src/bin/start_regtest_mints.rs +++ b/crates/cdk-integration-tests/src/bin/start_regtest_mints.rs @@ -266,6 +266,7 @@ fn create_ldk_settings( ) -> cdk_mintd::config::Settings { cdk_mintd::config::Settings { info: cdk_mintd::config::Info { + quote_ttl: None, url: format!("http://127.0.0.1:{port}"), listen_host: "127.0.0.1".to_string(), listen_port: port, diff --git a/crates/cdk-integration-tests/src/init_pure_tests.rs b/crates/cdk-integration-tests/src/init_pure_tests.rs index c9d5db3a9..90c88fb37 100644 --- a/crates/cdk-integration-tests/src/init_pure_tests.rs +++ b/crates/cdk-integration-tests/src/init_pure_tests.rs @@ -11,7 +11,7 @@ use bip39::Mnemonic; use cashu::quote_id::QuoteId; use cashu::{MeltQuoteBolt12Request, MintQuoteBolt12Request, MintQuoteBolt12Response}; use cdk::amount::SplitTarget; -use cdk::cdk_database::{self, MintDatabase, WalletDatabase}; +use cdk::cdk_database::{self, WalletDatabase}; use cdk::mint::{MintBuilder, MintMeltLimits}; use cdk::nuts::nut00::ProofsMethods; use cdk::nuts::{ @@ -271,17 +271,14 @@ pub async fn create_and_start_test_mint() -> Result { .with_description("pure test mint".to_string()) .with_urls(vec!["https://aaa".to_string()]); - let tx_localstore = localstore.clone(); - let mut tx = tx_localstore.begin_transaction().await?; - let quote_ttl = QuoteTTL::new(10000, 10000); - tx.set_quote_ttl(quote_ttl).await?; - tx.commit().await?; let mint = mint_builder .build_with_seed(localstore.clone(), &mnemonic.to_seed_normalized("")) .await?; + mint.set_quote_ttl(quote_ttl).await?; + mint.start().await?; Ok(mint) diff --git a/crates/cdk-integration-tests/src/shared.rs b/crates/cdk-integration-tests/src/shared.rs index c052ca9c7..4ad50bf17 100644 --- a/crates/cdk-integration-tests/src/shared.rs +++ b/crates/cdk-integration-tests/src/shared.rs @@ -181,6 +181,8 @@ pub fn create_fake_wallet_settings( cdk_mintd::config::Settings { info: cdk_mintd::config::Info { url: format!("http://127.0.0.1:{port}"), + quote_ttl: None, + listen_host: "127.0.0.1".to_string(), listen_port: port, seed: None, @@ -233,6 +235,8 @@ pub fn create_cln_settings( cdk_mintd::config::Settings { info: cdk_mintd::config::Info { url: format!("http://127.0.0.1:{port}"), + quote_ttl: None, + listen_host: "127.0.0.1".to_string(), listen_port: port, seed: None, @@ -278,6 +282,7 @@ pub fn create_lnd_settings( ) -> cdk_mintd::config::Settings { cdk_mintd::config::Settings { info: cdk_mintd::config::Info { + quote_ttl: None, url: format!("http://127.0.0.1:{port}"), listen_host: "127.0.0.1".to_string(), listen_port: port, diff --git a/crates/cdk-integration-tests/tests/mint.rs b/crates/cdk-integration-tests/tests/mint.rs index b1c3eca8e..9aa76ad56 100644 --- a/crates/cdk-integration-tests/tests/mint.rs +++ b/crates/cdk-integration-tests/tests/mint.rs @@ -15,7 +15,6 @@ use std::collections::{HashMap, HashSet}; use std::sync::Arc; use bip39::Mnemonic; -use cdk::cdk_database::MintDatabase; use cdk::mint::{MintBuilder, MintMeltLimits}; use cdk::nuts::{CurrencyUnit, PaymentMethod}; use cdk::types::{FeeReserve, QuoteTTL}; @@ -64,12 +63,9 @@ async fn test_correct_keyset() { .build_with_seed(localstore.clone(), &mnemonic.to_seed_normalized("")) .await .unwrap(); - let mut tx = localstore.begin_transaction().await.unwrap(); let quote_ttl = QuoteTTL::new(10000, 10000); - tx.set_quote_ttl(quote_ttl).await.unwrap(); - - tx.commit().await.unwrap(); + mint.set_quote_ttl(quote_ttl).await.unwrap(); let active = mint.get_active_keysets(); diff --git a/crates/cdk-mintd/example.config.toml b/crates/cdk-mintd/example.config.toml index 6aa7510e5..52898fb4e 100644 --- a/crates/cdk-mintd/example.config.toml +++ b/crates/cdk-mintd/example.config.toml @@ -7,6 +7,12 @@ mnemonic = "" # input_fee_ppk = 0 # enable_swagger_ui = false +[info.quote_ttl] +# Prefer explicit fields over inline tables for readability and ease of overrides +mint_ttl = 600 +melt_ttl = 120 + + [info.logging] # Where to output logs: "stdout", "file", or "both" (default: "both") # Note: "stdout" actually outputs to stderr (standard error stream) diff --git a/crates/cdk-mintd/src/config.rs b/crates/cdk-mintd/src/config.rs index a04ab7dcb..bb35edad3 100644 --- a/crates/cdk-mintd/src/config.rs +++ b/crates/cdk-mintd/src/config.rs @@ -4,6 +4,7 @@ use bitcoin::hashes::{sha256, Hash}; use cdk::nuts::{CurrencyUnit, PublicKey}; use cdk::Amount; use cdk_axum::cache; +use cdk_common::common::QuoteTTL; use config::{Config, ConfigError, File}; use serde::{Deserialize, Serialize}; @@ -68,6 +69,12 @@ pub struct Info { /// /// This requires `mintd` was built with the `swagger` feature flag. pub enable_swagger_ui: Option, + + /// Optional persisted quote TTL values (seconds) to initialize the database with + /// when RPC is disabled or on first-run when RPC is enabled. + /// If not provided, defaults are used. + #[serde(skip_serializing_if = "Option::is_none")] + pub quote_ttl: Option, } impl Default for Info { @@ -84,6 +91,7 @@ impl Default for Info { http_cache: cache::Config::default(), enable_swagger_ui: None, logging: LoggingConfig::default(), + quote_ttl: None, } } } diff --git a/crates/cdk-mintd/src/env_vars/common.rs b/crates/cdk-mintd/src/env_vars/common.rs index f8e5b8391..f00b90479 100644 --- a/crates/cdk-mintd/src/env_vars/common.rs +++ b/crates/cdk-mintd/src/env_vars/common.rs @@ -14,6 +14,9 @@ pub const ENV_SECONDS_QUOTE_VALID: &str = "CDK_MINTD_SECONDS_QUOTE_VALID"; pub const ENV_CACHE_SECONDS: &str = "CDK_MINTD_CACHE_SECONDS"; pub const ENV_EXTEND_CACHE_SECONDS: &str = "CDK_MINTD_EXTEND_CACHE_SECONDS"; pub const ENV_INPUT_FEE_PPK: &str = "CDK_MINTD_INPUT_FEE_PPK"; +pub const ENV_QUOTE_TTL_MINT: &str = "CDK_MINTD_QUOTE_TTL_MINT"; +pub const ENV_QUOTE_TTL_MELT: &str = "CDK_MINTD_QUOTE_TTL_MELT"; + pub const ENV_ENABLE_SWAGGER: &str = "CDK_MINTD_ENABLE_SWAGGER"; pub const ENV_LOGGING_OUTPUT: &str = "CDK_MINTD_LOGGING_OUTPUT"; pub const ENV_LOGGING_CONSOLE_LEVEL: &str = "CDK_MINTD_LOGGING_CONSOLE_LEVEL"; diff --git a/crates/cdk-mintd/src/env_vars/info.rs b/crates/cdk-mintd/src/env_vars/info.rs index 1ff11ac6f..483087624 100644 --- a/crates/cdk-mintd/src/env_vars/info.rs +++ b/crates/cdk-mintd/src/env_vars/info.rs @@ -3,6 +3,8 @@ use std::env; use std::str::FromStr; +use cdk_common::common::QuoteTTL; + use super::common::*; use crate::config::{Info, LoggingOutput}; @@ -85,6 +87,27 @@ impl Info { self.http_cache = self.http_cache.from_env(); + // Quote TTL from env + let mut mint_ttl_env: Option = None; + let mut melt_ttl_env: Option = None; + if let Ok(mint_ttl_str) = env::var(ENV_QUOTE_TTL_MINT) { + if let Ok(v) = mint_ttl_str.parse::() { + mint_ttl_env = Some(v); + } + } + if let Ok(melt_ttl_str) = env::var(ENV_QUOTE_TTL_MELT) { + if let Ok(v) = melt_ttl_str.parse::() { + melt_ttl_env = Some(v); + } + } + if mint_ttl_env.is_some() || melt_ttl_env.is_some() { + let current = self.quote_ttl.unwrap_or_default(); + self.quote_ttl = Some(QuoteTTL { + mint_ttl: mint_ttl_env.unwrap_or(current.mint_ttl), + melt_ttl: melt_ttl_env.unwrap_or(current.melt_ttl), + }); + } + self } } diff --git a/crates/cdk-mintd/src/lib.rs b/crates/cdk-mintd/src/lib.rs index 022030560..3bde4706c 100644 --- a/crates/cdk-mintd/src/lib.rs +++ b/crates/cdk-mintd/src/lib.rs @@ -36,8 +36,8 @@ use cdk::nuts::CurrencyUnit; #[cfg(feature = "auth")] use cdk::nuts::{AuthRequired, Method, ProtectedEndpoint, RoutePath}; use cdk::nuts::{ContactInfo, MintVersion, PaymentMethod}; -use cdk::types::QuoteTTL; use cdk_axum::cache::HttpCache; +use cdk_common::common::QuoteTTL; use cdk_common::database::DynMintDatabase; // internal crate modules #[cfg(feature = "prometheus")] @@ -890,16 +890,21 @@ async fn start_services_with_shutdown( } } + // Determine the desired QuoteTTL from config/env or fall back to defaults + let desired_quote_ttl: QuoteTTL = settings.info.quote_ttl.unwrap_or_default(); + if rpc_enabled { if mint.mint_info().await.is_err() { tracing::info!("Mint info not set on mint, setting."); + // First boot with RPC enabled: seed from config mint.set_mint_info(mint_builder_info).await?; - mint.set_quote_ttl(QuoteTTL::new(10_000, 10_000)).await?; + mint.set_quote_ttl(desired_quote_ttl).await?; } else { - if mint.localstore().get_quote_ttl().await.is_err() { - mint.set_quote_ttl(QuoteTTL::new(10_000, 10_000)).await?; + // If QuoteTTL has never been persisted, seed it now from config + if !mint.quote_ttl_is_persisted().await? { + mint.set_quote_ttl(desired_quote_ttl).await?; } - // Add version information + // Add/refresh version information without altering stored mint_info fields let mint_version = MintVersion::new( "cdk-mintd".to_string(), CARGO_PKG_VERSION.unwrap_or("Unknown").to_string(), @@ -911,9 +916,18 @@ async fn start_services_with_shutdown( tracing::info!("Mint info already set, not using config file settings."); } } else { - tracing::info!("RPC not enabled, using mint info from config."); + // RPC disabled: config is source of truth on every boot + tracing::info!("RPC not enabled, using mint info and quote TTL from config."); + let mut mint_builder_info = mint_builder_info; + + if let Ok(mint_info) = mint.mint_info().await { + if mint_builder_info.pubkey.is_none() { + mint_builder_info.pubkey = mint_info.pubkey; + } + } + mint.set_mint_info(mint_builder_info).await?; - mint.set_quote_ttl(QuoteTTL::new(10_000, 10_000)).await?; + mint.set_quote_ttl(desired_quote_ttl).await?; } let mint_info = mint.mint_info().await?; @@ -1120,11 +1134,39 @@ pub async fn run_mintd_with_shutdown( let mint_builder = MintBuilder::new(localstore); + // If RPC is enabled and DB contains mint_info already, initialize the builder from DB. + // This ensures subsequent builder modifications (like version injection) can respect stored values. + let maybe_mint_builder = { + #[cfg(feature = "management-rpc")] + { + if let Some(rpc_settings) = settings.mint_management_rpc.clone() { + if rpc_settings.enabled { + // Best-effort: pull DB state into builder if present + let mut tmp = mint_builder; + if let Err(e) = tmp.init_from_db_if_present().await { + tracing::warn!("Failed to init builder from DB: {}", e); + } + tmp + } else { + mint_builder + } + } else { + mint_builder + } + } + #[cfg(not(feature = "management-rpc"))] + { + mint_builder + } + }; + let mint_builder = - configure_mint_builder(settings, mint_builder, runtime, work_dir, Some(kv)).await?; + configure_mint_builder(settings, maybe_mint_builder, runtime, work_dir, Some(kv)).await?; #[cfg(feature = "auth")] let mint_builder = setup_authentication(settings, work_dir, mint_builder, db_password).await?; + let config_mint_info = mint_builder.current_mint_info(); + let mint = build_mint(settings, keystore, mint_builder).await?; tracing::debug!("Mint built from builder."); @@ -1136,19 +1178,13 @@ pub async fn run_mintd_with_shutdown( // Pending melt quotes where the payment has **failed** inputs are reset to unspent mint.check_pending_melt_quotes().await?; - let result = start_services_with_shutdown( + start_services_with_shutdown( mint.clone(), settings, work_dir, - mint.mint_info().await?, + config_mint_info, shutdown_signal, routers, ) - .await; - - // Ensure any remaining tracing data is flushed - // This is particularly important for file-based logging - tracing::debug!("Flushing remaining trace data"); - - result + .await } diff --git a/crates/cdk-sql-common/src/mint/migrations.rs b/crates/cdk-sql-common/src/mint/migrations.rs index 9609719e8..6bfb9fe16 100644 --- a/crates/cdk-sql-common/src/mint/migrations.rs +++ b/crates/cdk-sql-common/src/mint/migrations.rs @@ -6,6 +6,7 @@ pub static MIGRATIONS: &[(&str, &str, &str)] = &[ ("postgres", "20250901090000_add_kv_store.sql", include_str!(r#"./migrations/postgres/20250901090000_add_kv_store.sql"#)), ("postgres", "20250902140000_add_melt_request_and_blinded_messages.sql", include_str!(r#"./migrations/postgres/20250902140000_add_melt_request_and_blinded_messages.sql"#)), ("postgres", "20250903200000_add_signatory_amounts.sql", include_str!(r#"./migrations/postgres/20250903200000_add_signatory_amounts.sql"#)), + ("postgres", "20250916221000_drop_config_table.sql", include_str!(r#"./migrations/postgres/20250916221000_drop_config_table.sql"#)), ("sqlite", "1_fix_sqlx_migration.sql", include_str!(r#"./migrations/sqlite/1_fix_sqlx_migration.sql"#)), ("sqlite", "20240612124932_init.sql", include_str!(r#"./migrations/sqlite/20240612124932_init.sql"#)), ("sqlite", "20240618195700_quote_state.sql", include_str!(r#"./migrations/sqlite/20240618195700_quote_state.sql"#)), @@ -33,4 +34,5 @@ pub static MIGRATIONS: &[(&str, &str, &str)] = &[ ("sqlite", "20250901090000_add_kv_store.sql", include_str!(r#"./migrations/sqlite/20250901090000_add_kv_store.sql"#)), ("sqlite", "20250902140000_add_melt_request_and_blinded_messages.sql", include_str!(r#"./migrations/sqlite/20250902140000_add_melt_request_and_blinded_messages.sql"#)), ("sqlite", "20250903200000_add_signatory_amounts.sql", include_str!(r#"./migrations/sqlite/20250903200000_add_signatory_amounts.sql"#)), + ("sqlite", "20250916221000_drop_config_table.sql", include_str!(r#"./migrations/sqlite/20250916221000_drop_config_table.sql"#)), ]; diff --git a/crates/cdk-sql-common/src/mint/migrations/postgres/20250916221000_drop_config_table.sql b/crates/cdk-sql-common/src/mint/migrations/postgres/20250916221000_drop_config_table.sql new file mode 100644 index 000000000..2efbbee0f --- /dev/null +++ b/crates/cdk-sql-common/src/mint/migrations/postgres/20250916221000_drop_config_table.sql @@ -0,0 +1 @@ +DROP TABLE IF EXISTS config; diff --git a/crates/cdk-sql-common/src/mint/migrations/sqlite/20250916221000_drop_config_table.sql b/crates/cdk-sql-common/src/mint/migrations/sqlite/20250916221000_drop_config_table.sql new file mode 100644 index 000000000..2efbbee0f --- /dev/null +++ b/crates/cdk-sql-common/src/mint/migrations/sqlite/20250916221000_drop_config_table.sql @@ -0,0 +1 @@ +DROP TABLE IF EXISTS config; diff --git a/crates/cdk-sql-common/src/mint/mod.rs b/crates/cdk-sql-common/src/mint/mod.rs index 19b3042c9..d8239c40f 100644 --- a/crates/cdk-sql-common/src/mint/mod.rs +++ b/crates/cdk-sql-common/src/mint/mod.rs @@ -15,7 +15,6 @@ use std::sync::Arc; use async_trait::async_trait; use bitcoin::bip32::DerivationPath; -use cdk_common::common::QuoteTTL; use cdk_common::database::mint::validate_kvstore_params; use cdk_common::database::{ self, ConversionError, Error, MintDatabase, MintDbWriterFinalizer, MintKeyDatabaseTransaction, @@ -33,7 +32,7 @@ use cdk_common::state::check_state_transition; use cdk_common::util::unix_time; use cdk_common::{ Amount, BlindSignature, BlindSignatureDleq, BlindedMessage, CurrencyUnit, Id, MeltQuoteState, - MintInfo, PaymentMethod, Proof, Proofs, PublicKey, SecretKey, State, + PaymentMethod, Proof, Proofs, PublicKey, SecretKey, State, }; use lightning_invoice::Bolt11Invoice; use migrations::MIGRATIONS; @@ -102,26 +101,6 @@ where .collect::, _>>() } -#[inline(always)] -async fn set_to_config(conn: &C, id: &str, value: &V) -> Result<(), Error> -where - C: DatabaseExecutor + Send + Sync, - V: ?Sized + serde::Serialize, -{ - query( - r#" - INSERT INTO config (id, value) VALUES (:id, :value) - ON CONFLICT(id) DO UPDATE SET value = excluded.value - "#, - )? - .bind("id", id.to_owned()) - .bind("value", serde_json::to_string(&value)?) - .execute(conn) - .await?; - - Ok(()) -} - impl SQLMintDatabase where RM: DatabasePool + 'static, @@ -145,21 +124,6 @@ where tx.commit().await?; Ok(()) } - - #[inline(always)] - async fn fetch_from_config(&self, id: &str) -> Result - where - R: serde::de::DeserializeOwned, - { - let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; - let value = column_as_string!(query(r#"SELECT value FROM config WHERE id = :id LIMIT 1"#)? - .bind("id", id.to_owned()) - .pluck(&*conn) - .await? - .ok_or(Error::UnknownQuoteTTL)?); - - Ok(serde_json::from_str(&value)?) - } } #[async_trait] @@ -307,18 +271,8 @@ where } #[async_trait] -impl database::MintTransaction<'_, Error> for SQLTransaction -where - RM: DatabasePool + 'static, -{ - async fn set_mint_info(&mut self, mint_info: MintInfo) -> Result<(), Error> { - Ok(set_to_config(&self.inner, "mint_info", &mint_info).await?) - } - - async fn set_quote_ttl(&mut self, quote_ttl: QuoteTTL) -> Result<(), Error> { - Ok(set_to_config(&self.inner, "quote_ttl", "e_ttl).await?) - } -} +impl database::MintTransaction<'_, Error> for SQLTransaction where RM: DatabasePool + 'static +{} #[async_trait] impl MintDbWriterFinalizer for SQLTransaction @@ -2048,56 +2002,6 @@ where Ok(Box::new(tx)) } - - async fn get_mint_info(&self) -> Result { - #[cfg(feature = "prometheus")] - METRICS.inc_in_flight_requests("get_mint_info"); - - #[cfg(feature = "prometheus")] - let start_time = std::time::Instant::now(); - - let result = self.fetch_from_config("mint_info").await; - - #[cfg(feature = "prometheus")] - { - let success = result.is_ok(); - - METRICS.record_mint_operation("get_mint_info", success); - METRICS.record_mint_operation_histogram( - "get_mint_info", - success, - start_time.elapsed().as_secs_f64(), - ); - METRICS.dec_in_flight_requests("get_mint_info"); - } - - Ok(result?) - } - - async fn get_quote_ttl(&self) -> Result { - #[cfg(feature = "prometheus")] - METRICS.inc_in_flight_requests("get_quote_ttl"); - - #[cfg(feature = "prometheus")] - let start_time = std::time::Instant::now(); - - let result = self.fetch_from_config("quote_ttl").await; - - #[cfg(feature = "prometheus")] - { - let success = result.is_ok(); - - METRICS.record_mint_operation("get_quote_ttl", success); - METRICS.record_mint_operation_histogram( - "get_quote_ttl", - success, - start_time.elapsed().as_secs_f64(), - ); - METRICS.dec_in_flight_requests("get_quote_ttl"); - } - - Ok(result?) - } } fn sql_row_to_keyset_info(row: Vec) -> Result { diff --git a/crates/cdk-sqlite/src/mint/memory.rs b/crates/cdk-sqlite/src/mint/memory.rs index 7bbb718b2..e99f6d1bf 100644 --- a/crates/cdk-sqlite/src/mint/memory.rs +++ b/crates/cdk-sqlite/src/mint/memory.rs @@ -8,6 +8,10 @@ use cdk_common::MintInfo; use super::MintSqliteDatabase; +const CDK_MINT_PRIMARY_NAMESPACE: &str = "cdk_mint"; +const CDK_MINT_CONFIG_SECONDARY_NAMESPACE: &str = "config"; +const CDK_MINT_CONFIG_KV_KEY: &str = "mint_info"; + /// Creates a new in-memory [`MintSqliteDatabase`] instance pub async fn empty() -> Result { #[cfg(not(feature = "sqlcipher"))] @@ -54,7 +58,14 @@ pub async fn new_with_state( tx.add_proofs(pending_proofs, None).await?; tx.add_proofs(spent_proofs, None).await?; - tx.set_mint_info(mint_info).await?; + let mint_info_bytes = serde_json::to_vec(&mint_info)?; + tx.kv_write( + CDK_MINT_PRIMARY_NAMESPACE, + CDK_MINT_CONFIG_SECONDARY_NAMESPACE, + CDK_MINT_CONFIG_KV_KEY, + &mint_info_bytes, + ) + .await?; tx.commit().await?; Ok(db) diff --git a/crates/cdk/src/mint/builder.rs b/crates/cdk/src/mint/builder.rs index be9ed4c5f..c1c0ee5fe 100644 --- a/crates/cdk/src/mint/builder.rs +++ b/crates/cdk/src/mint/builder.rs @@ -82,6 +82,31 @@ impl MintBuilder { self } + /// Initialize builder's MintInfo from the database if present. + /// If not present or parsing fails, keeps the current MintInfo. + pub async fn init_from_db_if_present(&mut self) -> Result<(), cdk_database::Error> { + // Attempt to read existing mint_info from the KV store + let bytes_opt = self + .localstore + .kv_read( + super::CDK_MINT_PRIMARY_NAMESPACE, + super::CDK_MINT_CONFIG_SECONDARY_NAMESPACE, + super::CDK_MINT_CONFIG_KV_KEY, + ) + .await?; + + if let Some(bytes) = bytes_opt { + if let Ok(info) = serde_json::from_slice::(&bytes) { + self.mint_info = info; + } else { + // If parsing fails, leave the current builder state untouched + tracing::warn!("Failed to parse existing mint_info from DB; using builder state"); + } + } + + Ok(()) + } + /// Set blind auth settings #[cfg(feature = "auth")] pub fn with_blind_auth( @@ -128,6 +153,14 @@ impl MintBuilder { self } + /// Get a clone of the current MintInfo configured on the builder + /// This allows using config-derived settings to initialize persistent state + /// before any attempt to read from the database, which avoids first-run + /// failures when the DB is empty. + pub fn current_mint_info(&self) -> MintInfo { + self.mint_info.clone() + } + /// Set terms of service URL pub fn with_tos_url(mut self, tos_url: String) -> Self { self.mint_info.tos_url = Some(tos_url); diff --git a/crates/cdk/src/mint/issue/mod.rs b/crates/cdk/src/mint/issue/mod.rs index 14e8ce9f8..45c0268e3 100644 --- a/crates/cdk/src/mint/issue/mod.rs +++ b/crates/cdk/src/mint/issue/mod.rs @@ -168,7 +168,7 @@ impl Mint { &self, mint_quote_request: &MintQuoteRequest, ) -> Result<(), Error> { - let mint_info = self.localstore.get_mint_info().await?; + let mint_info = self.mint_info().await?; let unit = mint_quote_request.unit(); let amount = mint_quote_request.amount(); @@ -246,7 +246,7 @@ impl Mint { let payment_options = match mint_quote_request { MintQuoteRequest::Bolt11(bolt11_request) => { - let mint_ttl = self.localstore.get_quote_ttl().await?.mint_ttl; + let mint_ttl = self.quote_ttl().await?.mint_ttl; let quote_expiry = unix_time() + mint_ttl; diff --git a/crates/cdk/src/mint/melt.rs b/crates/cdk/src/mint/melt.rs index 014871a5c..580fe62f1 100644 --- a/crates/cdk/src/mint/melt.rs +++ b/crates/cdk/src/mint/melt.rs @@ -43,7 +43,7 @@ impl Mint { request: String, options: Option, ) -> Result<(), Error> { - let mint_info = self.localstore.get_mint_info().await?; + let mint_info = self.mint_info().await?; let nut05 = mint_info.nuts.nut05; ensure_cdk!(!nut05.disabled, Error::MeltingDisabled); @@ -196,7 +196,7 @@ impl Mint { Error::UnsupportedUnit })?; - let melt_ttl = self.localstore.get_quote_ttl().await?.melt_ttl; + let melt_ttl = self.quote_ttl().await?.melt_ttl; let quote = MeltQuote::new( MeltPaymentRequest::Bolt11 { diff --git a/crates/cdk/src/mint/mod.rs b/crates/cdk/src/mint/mod.rs index 4b429ca18..45c11c399 100644 --- a/crates/cdk/src/mint/mod.rs +++ b/crates/cdk/src/mint/mod.rs @@ -50,6 +50,11 @@ pub use builder::{MintBuilder, MintMeltLimits}; pub use cdk_common::mint::{MeltQuote, MintKeySetInfo, MintQuote}; pub use verification::Verification; +const CDK_MINT_PRIMARY_NAMESPACE: &str = "cdk_mint"; +const CDK_MINT_CONFIG_SECONDARY_NAMESPACE: &str = "config"; +const CDK_MINT_CONFIG_KV_KEY: &str = "mint_info"; +const CDK_MINT_QUOTE_TTL_KV_KEY: &str = "quote_ttl"; + /// Cashu Mint #[derive(Clone)] pub struct Mint { @@ -150,26 +155,60 @@ impl Mint { .count() ); - let mint_info = if mint_info.pubkey.is_none() { - let mut info = mint_info; - info.pubkey = Some(keysets.pubkey); - info - } else { - mint_info - }; + // Persist missing pubkey early to avoid losing it on next boot and ensure stable identity across restarts + let mut computed_info = mint_info; + if computed_info.pubkey.is_none() { + computed_info.pubkey = Some(keysets.pubkey); + } - let mint_store = localstore.clone(); - let mut tx = mint_store.begin_transaction().await?; - tx.set_mint_info(mint_info.clone()).await?; - tx.set_quote_ttl(QuoteTTL::default()).await?; - tx.commit().await?; + match localstore + .kv_read( + CDK_MINT_PRIMARY_NAMESPACE, + CDK_MINT_CONFIG_SECONDARY_NAMESPACE, + CDK_MINT_CONFIG_KV_KEY, + ) + .await? + { + Some(bytes) => { + let mut stored: MintInfo = serde_json::from_slice(&bytes)?; + let mut mutated = false; + if stored.pubkey.is_none() && computed_info.pubkey.is_some() { + stored.pubkey = computed_info.pubkey; + mutated = true; + } + if mutated { + let updated = serde_json::to_vec(&stored)?; + let mut tx = localstore.begin_transaction().await?; + tx.kv_write( + CDK_MINT_PRIMARY_NAMESPACE, + CDK_MINT_CONFIG_SECONDARY_NAMESPACE, + CDK_MINT_CONFIG_KV_KEY, + &updated, + ) + .await?; + tx.commit().await?; + } + } + None => { + let bytes = serde_json::to_vec(&computed_info)?; + let mut tx = localstore.begin_transaction().await?; + tx.kv_write( + CDK_MINT_PRIMARY_NAMESPACE, + CDK_MINT_CONFIG_SECONDARY_NAMESPACE, + CDK_MINT_CONFIG_KV_KEY, + &bytes, + ) + .await?; + tx.commit().await?; + } + } Ok(Self { signatory, pubsub_manager: Arc::new(localstore.clone().into()), localstore, #[cfg(feature = "auth")] - oidc_client: mint_info.nuts.nut21.as_ref().map(|nut21| { + oidc_client: computed_info.nuts.nut21.as_ref().map(|nut21| { OidcClient::new( nut21.openid_discovery.clone(), Some(nut21.client_id.clone()), @@ -373,7 +412,17 @@ impl Mint { /// Get mint info #[instrument(skip_all)] pub async fn mint_info(&self) -> Result { - let mint_info = self.localstore.get_mint_info().await?; + let mint_info = self + .localstore + .kv_read( + CDK_MINT_PRIMARY_NAMESPACE, + CDK_MINT_CONFIG_SECONDARY_NAMESPACE, + CDK_MINT_CONFIG_KV_KEY, + ) + .await? + .ok_or(Error::CouldNotGetMintInfo)?; + + let mint_info: MintInfo = serde_json::from_slice(&mint_info)?; #[cfg(feature = "auth")] let mint_info = if let Some(auth_db) = self.auth_localstore.as_ref() { @@ -415,27 +464,78 @@ impl Mint { /// Set mint info #[instrument(skip_all)] pub async fn set_mint_info(&self, mint_info: MintInfo) -> Result<(), Error> { + tracing::info!("Updating mint info"); + let mint_info_bytes = serde_json::to_vec(&mint_info)?; let mut tx = self.localstore.begin_transaction().await?; - tx.set_mint_info(mint_info).await?; - Ok(tx.commit().await?) + tx.kv_write( + CDK_MINT_PRIMARY_NAMESPACE, + CDK_MINT_CONFIG_SECONDARY_NAMESPACE, + CDK_MINT_CONFIG_KV_KEY, + &mint_info_bytes, + ) + .await?; + tx.commit().await?; + Ok(()) } /// Get quote ttl #[instrument(skip_all)] pub async fn quote_ttl(&self) -> Result { - Ok(self.localstore.get_quote_ttl().await?) + let quote_ttl_bytes = self + .localstore + .kv_read( + CDK_MINT_PRIMARY_NAMESPACE, + CDK_MINT_CONFIG_SECONDARY_NAMESPACE, + CDK_MINT_QUOTE_TTL_KV_KEY, + ) + .await?; + + match quote_ttl_bytes { + Some(bytes) => { + let quote_ttl: QuoteTTL = serde_json::from_slice(&bytes)?; + Ok(quote_ttl) + } + None => { + // Return default if not found + Ok(QuoteTTL::default()) + } + } } /// Set quote ttl #[instrument(skip_all)] pub async fn set_quote_ttl(&self, quote_ttl: QuoteTTL) -> Result<(), Error> { + let quote_ttl_bytes = serde_json::to_vec("e_ttl)?; let mut tx = self.localstore.begin_transaction().await?; - tx.set_quote_ttl(quote_ttl).await?; - Ok(tx.commit().await?) + tx.kv_write( + CDK_MINT_PRIMARY_NAMESPACE, + CDK_MINT_CONFIG_SECONDARY_NAMESPACE, + CDK_MINT_QUOTE_TTL_KV_KEY, + "e_ttl_bytes, + ) + .await?; + tx.commit().await?; + Ok(()) } /// For each backend starts a task that waits for any invoice to be paid /// Once invoice is paid mint quote status is updated + /// Returns true if a QuoteTTL is persisted in the database. This is used to avoid overwriting + /// explicit configuration with defaults when the TTL has already been set by an operator. + #[instrument(skip_all)] + pub async fn quote_ttl_is_persisted(&self) -> Result { + let quote_ttl_bytes = self + .localstore + .kv_read( + CDK_MINT_PRIMARY_NAMESPACE, + CDK_MINT_CONFIG_SECONDARY_NAMESPACE, + CDK_MINT_QUOTE_TTL_KV_KEY, + ) + .await?; + + Ok(quote_ttl_bytes.is_some()) + } + #[instrument(skip_all)] async fn wait_for_paid_invoices( payment_processors: &HashMap, @@ -627,13 +727,6 @@ impl Mint { return Err(Error::AmountUndefined); } - if mint_quote.payment_method == PaymentMethod::Bolt11 - && mint_quote.amount != Some(payment_amount_quote_unit) - { - tracing::error!("Bolt11 incoming payment should equal mint quote."); - return Err(Error::IncorrectQuoteAmount); - } - tracing::debug!( "Payment received amount in quote unit {} {}", mint_quote.unit, From 2becc4be21c49f8f1a432b49c05087cc8398b9a6 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Sat, 20 Sep 2025 16:49:53 +0100 Subject: [PATCH 167/321] chore: doc fmt (#1094) --- crates/cdk/src/wallet/multi_mint_wallet.rs | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/crates/cdk/src/wallet/multi_mint_wallet.rs b/crates/cdk/src/wallet/multi_mint_wallet.rs index c71a72698..c80483a0d 100644 --- a/crates/cdk/src/wallet/multi_mint_wallet.rs +++ b/crates/cdk/src/wallet/multi_mint_wallet.rs @@ -801,17 +801,17 @@ impl MultiMintWallet { /// # async fn example(wallet: MultiMintWallet) -> Result<(), Box> { /// // Receive from a trusted mint /// let token = "cashuAey..."; - /// let amount = wallet.receive(token, MultiMintReceiveOptions::default()).await?; + /// let amount = wallet + /// .receive(token, MultiMintReceiveOptions::default()) + /// .await?; /// /// // Receive from untrusted mint and add it to the wallet - /// let options = MultiMintReceiveOptions::default() - /// .allow_untrusted(true); + /// let options = MultiMintReceiveOptions::default().allow_untrusted(true); /// let amount = wallet.receive(token, options).await?; /// /// // Receive from untrusted mint, transfer to trusted mint, then remove untrusted mint /// let trusted_mint: MintUrl = "https://trusted.mint".parse()?; - /// let options = MultiMintReceiveOptions::default() - /// .transfer_to_mint(Some(trusted_mint)); + /// let options = MultiMintReceiveOptions::default().transfer_to_mint(Some(trusted_mint)); /// let amount = wallet.receive(token, options).await?; /// # Ok(()) /// # } From 853f13fc85001af710175489581d701a0667e24d Mon Sep 17 00:00:00 2001 From: vnprc <9425366+vnprc@users.noreply.github.com> Date: Sat, 20 Sep 2025 16:50:54 +0100 Subject: [PATCH 168/321] fix(build): use OUT_DIR for migration files (#1088) - write generated migration files to OUT_DIR instead of source directory - copy migration SQL files to OUT_DIR for inclusion in build artifacts - use absolute paths from OUT_DIR in include_str! macros - update consumer modules to include from OUT_DIR using concat! macro these changes enable cdk to support nix sandbox builds --- crates/cdk-sql-common/build.rs | 34 ++++++++++++++++++---- crates/cdk-sql-common/src/mint/auth/mod.rs | 5 ++-- crates/cdk-sql-common/src/mint/mod.rs | 5 ++-- crates/cdk-sql-common/src/wallet/mod.rs | 4 ++- 4 files changed, 38 insertions(+), 10 deletions(-) diff --git a/crates/cdk-sql-common/build.rs b/crates/cdk-sql-common/build.rs index 9cba59330..3a8890133 100644 --- a/crates/cdk-sql-common/build.rs +++ b/crates/cdk-sql-common/build.rs @@ -1,4 +1,5 @@ use std::cmp::Ordering; +use std::env; use std::fs::{self, File}; use std::io::Write; use std::path::{Path, PathBuf}; @@ -7,11 +8,22 @@ fn main() { // Step 1: Find `migrations/` folder recursively let root = Path::new("src"); + // Get the OUT_DIR from Cargo - this is writable + let out_dir = PathBuf::from(env::var("OUT_DIR").expect("OUT_DIR is set by Cargo")); + for migration_path in find_migrations_dirs(root) { - // Step 3: Output file path (e.g., `src/db/migrations.rs`) + // Step 3: Output file path to OUT_DIR instead of source directory let parent = migration_path.parent().unwrap(); - let skip_path = parent.to_str().unwrap_or_default().len(); - let dest_path = parent.join("migrations.rs"); + + // Create a unique filename based on the migration path to avoid conflicts + let migration_name = parent + .strip_prefix("src") + .unwrap_or(parent) + .to_str() + .unwrap_or("default") + .replace("/", "_") + .replace("\\", "_"); + let dest_path = out_dir.join(format!("migrations_{}.rs", migration_name)); let mut out_file = File::create(&dest_path).expect("Failed to create migrations.rs"); let skip_name = migration_path.to_str().unwrap_or_default().len(); @@ -89,10 +101,22 @@ fn main() { }; let rel_name = &path.file_name().unwrap().to_str().unwrap(); - let rel_path = &path.to_str().unwrap().replace("\\", "/")[skip_path..]; // for Windows + + // Copy migration file to OUT_DIR + let relative_path = path.strip_prefix(root).unwrap(); + let dest_migration_file = out_dir.join(relative_path); + if let Some(parent) = dest_migration_file.parent() { + fs::create_dir_all(parent) + .expect("Failed to create migration directory in OUT_DIR"); + } + fs::copy(path, &dest_migration_file).expect("Failed to copy migration file to OUT_DIR"); + + // Use path relative to OUT_DIR for include_str + let relative_to_out_dir = relative_path.to_str().unwrap().replace("\\", "/"); writeln!( out_file, - " (\"{prefix}\", \"{rel_name}\", include_str!(r#\".{rel_path}\"#))," + " (\"{prefix}\", \"{rel_name}\", include_str!(r#\"{}\"#)),", + relative_to_out_dir ) .unwrap(); println!("cargo:rerun-if-changed={}", path.display()); diff --git a/crates/cdk-sql-common/src/mint/auth/mod.rs b/crates/cdk-sql-common/src/mint/auth/mod.rs index 771f509f6..f5ca43569 100644 --- a/crates/cdk-sql-common/src/mint/auth/mod.rs +++ b/crates/cdk-sql-common/src/mint/auth/mod.rs @@ -54,8 +54,9 @@ where } #[rustfmt::skip] -mod migrations; - +mod migrations { + include!(concat!(env!("OUT_DIR"), "/migrations_mint_auth.rs")); +} #[async_trait] impl MintAuthTransaction for SQLTransaction diff --git a/crates/cdk-sql-common/src/mint/mod.rs b/crates/cdk-sql-common/src/mint/mod.rs index d8239c40f..3bd0c4bfc 100644 --- a/crates/cdk-sql-common/src/mint/mod.rs +++ b/crates/cdk-sql-common/src/mint/mod.rs @@ -51,8 +51,9 @@ use crate::{ mod auth; #[rustfmt::skip] -mod migrations; - +mod migrations { + include!(concat!(env!("OUT_DIR"), "/migrations_mint.rs")); +} #[cfg(feature = "auth")] pub use auth::SQLMintAuthDatabase; diff --git a/crates/cdk-sql-common/src/wallet/mod.rs b/crates/cdk-sql-common/src/wallet/mod.rs index 6078a3677..8e2817d24 100644 --- a/crates/cdk-sql-common/src/wallet/mod.rs +++ b/crates/cdk-sql-common/src/wallet/mod.rs @@ -28,7 +28,9 @@ use crate::{ }; #[rustfmt::skip] -mod migrations; +mod migrations { + include!(concat!(env!("OUT_DIR"), "/migrations_wallet.rs")); +} /// Wallet SQLite Database #[derive(Debug, Clone)] From 075e25682e12b5c41e9b1d4cf7a0cc3e7503644a Mon Sep 17 00:00:00 2001 From: C Date: Sun, 21 Sep 2025 12:55:48 -0300 Subject: [PATCH 169/321] Remove generated files (#1097) After #1088, generated migrations files should not be versioned --- .../src/mint/auth/migrations.rs | 9 ----- crates/cdk-sql-common/src/mint/migrations.rs | 38 ------------------- .../cdk-sql-common/src/wallet/migrations.rs | 29 -------------- 3 files changed, 76 deletions(-) delete mode 100644 crates/cdk-sql-common/src/mint/auth/migrations.rs delete mode 100644 crates/cdk-sql-common/src/mint/migrations.rs delete mode 100644 crates/cdk-sql-common/src/wallet/migrations.rs diff --git a/crates/cdk-sql-common/src/mint/auth/migrations.rs b/crates/cdk-sql-common/src/mint/auth/migrations.rs deleted file mode 100644 index ee53d6bdb..000000000 --- a/crates/cdk-sql-common/src/mint/auth/migrations.rs +++ /dev/null @@ -1,9 +0,0 @@ -/// @generated -/// Auto-generated by build.rs -pub static MIGRATIONS: &[(&str, &str, &str)] = &[ - ("postgres", "1_init.sql", include_str!(r#"./migrations/postgres/1_init.sql"#)), - ("postgres", "20250822104351_rename_blind_message_y_to_b.sql", include_str!(r#"./migrations/postgres/20250822104351_rename_blind_message_y_to_b.sql"#)), - ("sqlite", "1_fix_sqlx_migration.sql", include_str!(r#"./migrations/sqlite/1_fix_sqlx_migration.sql"#)), - ("sqlite", "20250109143347_init.sql", include_str!(r#"./migrations/sqlite/20250109143347_init.sql"#)), - ("sqlite", "20250822104351_rename_blind_message_y_to_b.sql", include_str!(r#"./migrations/sqlite/20250822104351_rename_blind_message_y_to_b.sql"#)), -]; diff --git a/crates/cdk-sql-common/src/mint/migrations.rs b/crates/cdk-sql-common/src/mint/migrations.rs deleted file mode 100644 index 6bfb9fe16..000000000 --- a/crates/cdk-sql-common/src/mint/migrations.rs +++ /dev/null @@ -1,38 +0,0 @@ -/// @generated -/// Auto-generated by build.rs -pub static MIGRATIONS: &[(&str, &str, &str)] = &[ - ("postgres", "1_initial.sql", include_str!(r#"./migrations/postgres/1_initial.sql"#)), - ("postgres", "2_remove_request_lookup_kind_constraints.sql", include_str!(r#"./migrations/postgres/2_remove_request_lookup_kind_constraints.sql"#)), - ("postgres", "20250901090000_add_kv_store.sql", include_str!(r#"./migrations/postgres/20250901090000_add_kv_store.sql"#)), - ("postgres", "20250902140000_add_melt_request_and_blinded_messages.sql", include_str!(r#"./migrations/postgres/20250902140000_add_melt_request_and_blinded_messages.sql"#)), - ("postgres", "20250903200000_add_signatory_amounts.sql", include_str!(r#"./migrations/postgres/20250903200000_add_signatory_amounts.sql"#)), - ("postgres", "20250916221000_drop_config_table.sql", include_str!(r#"./migrations/postgres/20250916221000_drop_config_table.sql"#)), - ("sqlite", "1_fix_sqlx_migration.sql", include_str!(r#"./migrations/sqlite/1_fix_sqlx_migration.sql"#)), - ("sqlite", "20240612124932_init.sql", include_str!(r#"./migrations/sqlite/20240612124932_init.sql"#)), - ("sqlite", "20240618195700_quote_state.sql", include_str!(r#"./migrations/sqlite/20240618195700_quote_state.sql"#)), - ("sqlite", "20240626092101_nut04_state.sql", include_str!(r#"./migrations/sqlite/20240626092101_nut04_state.sql"#)), - ("sqlite", "20240703122347_request_lookup_id.sql", include_str!(r#"./migrations/sqlite/20240703122347_request_lookup_id.sql"#)), - ("sqlite", "20240710145043_input_fee.sql", include_str!(r#"./migrations/sqlite/20240710145043_input_fee.sql"#)), - ("sqlite", "20240711183109_derivation_path_index.sql", include_str!(r#"./migrations/sqlite/20240711183109_derivation_path_index.sql"#)), - ("sqlite", "20240718203721_allow_unspent.sql", include_str!(r#"./migrations/sqlite/20240718203721_allow_unspent.sql"#)), - ("sqlite", "20240811031111_update_mint_url.sql", include_str!(r#"./migrations/sqlite/20240811031111_update_mint_url.sql"#)), - ("sqlite", "20240919103407_proofs_quote_id.sql", include_str!(r#"./migrations/sqlite/20240919103407_proofs_quote_id.sql"#)), - ("sqlite", "20240923153640_melt_requests.sql", include_str!(r#"./migrations/sqlite/20240923153640_melt_requests.sql"#)), - ("sqlite", "20240930101140_dleq_for_sigs.sql", include_str!(r#"./migrations/sqlite/20240930101140_dleq_for_sigs.sql"#)), - ("sqlite", "20241108093102_mint_mint_quote_pubkey.sql", include_str!(r#"./migrations/sqlite/20241108093102_mint_mint_quote_pubkey.sql"#)), - ("sqlite", "20250103201327_amount_to_pay_msats.sql", include_str!(r#"./migrations/sqlite/20250103201327_amount_to_pay_msats.sql"#)), - ("sqlite", "20250129200912_remove_mint_url.sql", include_str!(r#"./migrations/sqlite/20250129200912_remove_mint_url.sql"#)), - ("sqlite", "20250129230326_add_config_table.sql", include_str!(r#"./migrations/sqlite/20250129230326_add_config_table.sql"#)), - ("sqlite", "20250307213652_keyset_id_as_foreign_key.sql", include_str!(r#"./migrations/sqlite/20250307213652_keyset_id_as_foreign_key.sql"#)), - ("sqlite", "20250406091754_mint_time_of_quotes.sql", include_str!(r#"./migrations/sqlite/20250406091754_mint_time_of_quotes.sql"#)), - ("sqlite", "20250406093755_mint_created_time_signature.sql", include_str!(r#"./migrations/sqlite/20250406093755_mint_created_time_signature.sql"#)), - ("sqlite", "20250415093121_drop_keystore_foreign.sql", include_str!(r#"./migrations/sqlite/20250415093121_drop_keystore_foreign.sql"#)), - ("sqlite", "20250626120251_rename_blind_message_y_to_b.sql", include_str!(r#"./migrations/sqlite/20250626120251_rename_blind_message_y_to_b.sql"#)), - ("sqlite", "20250706101057_bolt12.sql", include_str!(r#"./migrations/sqlite/20250706101057_bolt12.sql"#)), - ("sqlite", "20250812132015_drop_melt_request.sql", include_str!(r#"./migrations/sqlite/20250812132015_drop_melt_request.sql"#)), - ("sqlite", "20250819200000_remove_request_lookup_kind_constraints.sql", include_str!(r#"./migrations/sqlite/20250819200000_remove_request_lookup_kind_constraints.sql"#)), - ("sqlite", "20250901090000_add_kv_store.sql", include_str!(r#"./migrations/sqlite/20250901090000_add_kv_store.sql"#)), - ("sqlite", "20250902140000_add_melt_request_and_blinded_messages.sql", include_str!(r#"./migrations/sqlite/20250902140000_add_melt_request_and_blinded_messages.sql"#)), - ("sqlite", "20250903200000_add_signatory_amounts.sql", include_str!(r#"./migrations/sqlite/20250903200000_add_signatory_amounts.sql"#)), - ("sqlite", "20250916221000_drop_config_table.sql", include_str!(r#"./migrations/sqlite/20250916221000_drop_config_table.sql"#)), -]; diff --git a/crates/cdk-sql-common/src/wallet/migrations.rs b/crates/cdk-sql-common/src/wallet/migrations.rs deleted file mode 100644 index 4f3d0c1b7..000000000 --- a/crates/cdk-sql-common/src/wallet/migrations.rs +++ /dev/null @@ -1,29 +0,0 @@ -/// @generated -/// Auto-generated by build.rs -pub static MIGRATIONS: &[(&str, &str, &str)] = &[ - ("postgres", "1_initial.sql", include_str!(r#"./migrations/postgres/1_initial.sql"#)), - ("postgres", "20250831215438_melt_quote_method.sql", include_str!(r#"./migrations/postgres/20250831215438_melt_quote_method.sql"#)), - ("postgres", "20250906200000_add_transaction_quote_id.sql", include_str!(r#"./migrations/postgres/20250906200000_add_transaction_quote_id.sql"#)), - ("sqlite", "1_fix_sqlx_migration.sql", include_str!(r#"./migrations/sqlite/1_fix_sqlx_migration.sql"#)), - ("sqlite", "20240612132920_init.sql", include_str!(r#"./migrations/sqlite/20240612132920_init.sql"#)), - ("sqlite", "20240618200350_quote_state.sql", include_str!(r#"./migrations/sqlite/20240618200350_quote_state.sql"#)), - ("sqlite", "20240626091921_nut04_state.sql", include_str!(r#"./migrations/sqlite/20240626091921_nut04_state.sql"#)), - ("sqlite", "20240710144711_input_fee.sql", include_str!(r#"./migrations/sqlite/20240710144711_input_fee.sql"#)), - ("sqlite", "20240810214105_mint_icon_url.sql", include_str!(r#"./migrations/sqlite/20240810214105_mint_icon_url.sql"#)), - ("sqlite", "20240810233905_update_mint_url.sql", include_str!(r#"./migrations/sqlite/20240810233905_update_mint_url.sql"#)), - ("sqlite", "20240902151515_icon_url.sql", include_str!(r#"./migrations/sqlite/20240902151515_icon_url.sql"#)), - ("sqlite", "20240902210905_mint_time.sql", include_str!(r#"./migrations/sqlite/20240902210905_mint_time.sql"#)), - ("sqlite", "20241011125207_mint_urls.sql", include_str!(r#"./migrations/sqlite/20241011125207_mint_urls.sql"#)), - ("sqlite", "20241108092756_wallet_mint_quote_secretkey.sql", include_str!(r#"./migrations/sqlite/20241108092756_wallet_mint_quote_secretkey.sql"#)), - ("sqlite", "20250214135017_mint_tos.sql", include_str!(r#"./migrations/sqlite/20250214135017_mint_tos.sql"#)), - ("sqlite", "20250310111513_drop_nostr_last_checked.sql", include_str!(r#"./migrations/sqlite/20250310111513_drop_nostr_last_checked.sql"#)), - ("sqlite", "20250314082116_allow_pending_spent.sql", include_str!(r#"./migrations/sqlite/20250314082116_allow_pending_spent.sql"#)), - ("sqlite", "20250323152040_wallet_dleq_proofs.sql", include_str!(r#"./migrations/sqlite/20250323152040_wallet_dleq_proofs.sql"#)), - ("sqlite", "20250401120000_add_transactions_table.sql", include_str!(r#"./migrations/sqlite/20250401120000_add_transactions_table.sql"#)), - ("sqlite", "20250616144830_add_keyset_expiry.sql", include_str!(r#"./migrations/sqlite/20250616144830_add_keyset_expiry.sql"#)), - ("sqlite", "20250707093445_bolt12.sql", include_str!(r#"./migrations/sqlite/20250707093445_bolt12.sql"#)), - ("sqlite", "20250729111701_keyset_v2_u32.sql", include_str!(r#"./migrations/sqlite/20250729111701_keyset_v2_u32.sql"#)), - ("sqlite", "20250812084621_keyset_plus_one.sql", include_str!(r#"./migrations/sqlite/20250812084621_keyset_plus_one.sql"#)), - ("sqlite", "20250831215438_melt_quote_method.sql", include_str!(r#"./migrations/sqlite/20250831215438_melt_quote_method.sql"#)), - ("sqlite", "20250906200000_add_transaction_quote_id.sql", include_str!(r#"./migrations/sqlite/20250906200000_add_transaction_quote_id.sql"#)), -]; From df2f9d1c2a31e429e442933206dc9dc314724faf Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Sun, 21 Sep 2025 16:56:12 +0100 Subject: [PATCH 170/321] Psgl auth db (#1095) * feat(cdk-mintd): add dedicated auth database configuration support --- .../src/bin/start_regtest_mints.rs | 1 + crates/cdk-integration-tests/src/shared.rs | 3 ++ crates/cdk-mintd/example.config.toml | 13 ++++++ crates/cdk-mintd/src/config.rs | 26 ++++++++++++ crates/cdk-mintd/src/env_vars/database.rs | 34 ++++++++++++++- crates/cdk-mintd/src/env_vars/mod.rs | 15 +++++++ crates/cdk-mintd/src/lib.rs | 42 +++++++++++++++---- crates/cdk-postgres/start_db_for_test.sh | 7 ++++ crates/cdk-sql-common/src/mint/auth/mod.rs | 6 ++- 9 files changed, 137 insertions(+), 10 deletions(-) diff --git a/crates/cdk-integration-tests/src/bin/start_regtest_mints.rs b/crates/cdk-integration-tests/src/bin/start_regtest_mints.rs index 7777ef743..154db6139 100644 --- a/crates/cdk-integration-tests/src/bin/start_regtest_mints.rs +++ b/crates/cdk-integration-tests/src/bin/start_regtest_mints.rs @@ -295,6 +295,7 @@ fn create_ldk_settings( fake_wallet: None, grpc_processor: None, database: cdk_mintd::config::Database::default(), + auth_database: None, mint_management_rpc: None, prometheus: None, auth: None, diff --git a/crates/cdk-integration-tests/src/shared.rs b/crates/cdk-integration-tests/src/shared.rs index 4ad50bf17..fe9d0afe4 100644 --- a/crates/cdk-integration-tests/src/shared.rs +++ b/crates/cdk-integration-tests/src/shared.rs @@ -219,6 +219,7 @@ pub fn create_fake_wallet_settings( engine: DatabaseEngine::from_str(database).expect("valid database"), postgres: None, }, + auth_database: None, mint_management_rpc: None, auth: None, prometheus: Some(Default::default()), @@ -268,6 +269,7 @@ pub fn create_cln_settings( fake_wallet: None, grpc_processor: None, database: cdk_mintd::config::Database::default(), + auth_database: None, mint_management_rpc: None, auth: None, prometheus: Some(Default::default()), @@ -315,6 +317,7 @@ pub fn create_lnd_settings( fake_wallet: None, grpc_processor: None, database: cdk_mintd::config::Database::default(), + auth_database: None, mint_management_rpc: None, auth: None, prometheus: Some(Default::default()), diff --git a/crates/cdk-mintd/example.config.toml b/crates/cdk-mintd/example.config.toml index 52898fb4e..c65105396 100644 --- a/crates/cdk-mintd/example.config.toml +++ b/crates/cdk-mintd/example.config.toml @@ -74,6 +74,19 @@ max_connections = 20 # Connection timeout in seconds (optional, defaults to 10) connection_timeout_seconds = 10 +# Auth database configuration (optional, only used when auth is enabled) +[auth_database.postgres] +# PostgreSQL connection URL for authentication database +# Can also be set via CDK_MINTD_AUTH_POSTGRES_URL environment variable +# Environment variables take precedence over config file settings +url = "postgresql://user:password@localhost:5432/cdk_mint_auth" +# TLS mode: "disable", "prefer", "require" (optional, defaults to "disable") +tls_mode = "disable" +# Maximum number of connections in the pool (optional, defaults to 20) +max_connections = 20 +# Connection timeout in seconds (optional, defaults to 10) +connection_timeout_seconds = 10 + [ln] # Required ln backend `cln`, `lnd`, `fakewallet`, 'lnbits', 'ldknode' ln_backend = "fakewallet" diff --git a/crates/cdk-mintd/src/config.rs b/crates/cdk-mintd/src/config.rs index bb35edad3..fa5bc6ff3 100644 --- a/crates/cdk-mintd/src/config.rs +++ b/crates/cdk-mintd/src/config.rs @@ -367,6 +367,30 @@ pub struct Database { pub postgres: Option, } +#[derive(Debug, Clone, Serialize, Deserialize, Default)] +pub struct AuthDatabase { + pub postgres: Option, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct PostgresAuthConfig { + pub url: String, + pub tls_mode: Option, + pub max_connections: Option, + pub connection_timeout_seconds: Option, +} + +impl Default for PostgresAuthConfig { + fn default() -> Self { + Self { + url: String::new(), + tls_mode: Some("disable".to_string()), + max_connections: Some(20), + connection_timeout_seconds: Some(10), + } + } +} + #[derive(Debug, Clone, Serialize, Deserialize)] pub struct PostgresConfig { pub url: String, @@ -457,6 +481,8 @@ pub struct Settings { pub fake_wallet: Option, pub grpc_processor: Option, pub database: Database, + #[cfg(feature = "auth")] + pub auth_database: Option, #[cfg(feature = "management-rpc")] pub mint_management_rpc: Option, pub auth: Option, diff --git a/crates/cdk-mintd/src/env_vars/database.rs b/crates/cdk-mintd/src/env_vars/database.rs index 5b9621c8f..6b71ed7d9 100644 --- a/crates/cdk-mintd/src/env_vars/database.rs +++ b/crates/cdk-mintd/src/env_vars/database.rs @@ -2,13 +2,19 @@ use std::env; -use crate::config::PostgresConfig; +use crate::config::{PostgresAuthConfig, PostgresConfig}; pub const ENV_POSTGRES_URL: &str = "CDK_MINTD_POSTGRES_URL"; pub const ENV_POSTGRES_TLS_MODE: &str = "CDK_MINTD_POSTGRES_TLS_MODE"; pub const ENV_POSTGRES_MAX_CONNECTIONS: &str = "CDK_MINTD_POSTGRES_MAX_CONNECTIONS"; pub const ENV_POSTGRES_CONNECTION_TIMEOUT: &str = "CDK_MINTD_POSTGRES_CONNECTION_TIMEOUT_SECONDS"; +pub const ENV_AUTH_POSTGRES_URL: &str = "CDK_MINTD_AUTH_POSTGRES_URL"; +pub const ENV_AUTH_POSTGRES_TLS_MODE: &str = "CDK_MINTD_AUTH_POSTGRES_TLS_MODE"; +pub const ENV_AUTH_POSTGRES_MAX_CONNECTIONS: &str = "CDK_MINTD_AUTH_POSTGRES_MAX_CONNECTIONS"; +pub const ENV_AUTH_POSTGRES_CONNECTION_TIMEOUT: &str = + "CDK_MINTD_AUTH_POSTGRES_CONNECTION_TIMEOUT_SECONDS"; + impl PostgresConfig { pub fn from_env(mut self) -> Self { // Check for new PostgreSQL URL env var first, then fallback to legacy DATABASE_URL @@ -38,3 +44,29 @@ impl PostgresConfig { self } } + +impl PostgresAuthConfig { + pub fn from_env(mut self) -> Self { + if let Ok(url) = env::var(ENV_AUTH_POSTGRES_URL) { + self.url = url; + } + + if let Ok(tls_mode) = env::var(ENV_AUTH_POSTGRES_TLS_MODE) { + self.tls_mode = Some(tls_mode); + } + + if let Ok(max_connections) = env::var(ENV_AUTH_POSTGRES_MAX_CONNECTIONS) { + if let Ok(parsed) = max_connections.parse::() { + self.max_connections = Some(parsed); + } + } + + if let Ok(timeout) = env::var(ENV_AUTH_POSTGRES_CONNECTION_TIMEOUT) { + if let Ok(parsed) = timeout.parse::() { + self.connection_timeout_seconds = Some(parsed); + } + } + + self + } +} diff --git a/crates/cdk-mintd/src/env_vars/mod.rs b/crates/cdk-mintd/src/env_vars/mod.rs index 61501aabf..a3f4c5979 100644 --- a/crates/cdk-mintd/src/env_vars/mod.rs +++ b/crates/cdk-mintd/src/env_vars/mod.rs @@ -75,6 +75,21 @@ impl Settings { ); } + // Parse auth database configuration from environment variables (when auth is enabled) + #[cfg(feature = "auth")] + { + self.auth_database = Some(crate::config::AuthDatabase { + postgres: Some( + self.auth_database + .clone() + .unwrap_or_default() + .postgres + .unwrap_or_default() + .from_env(), + ), + }); + } + self.info = self.info.clone().from_env(); self.mint_info = self.mint_info.clone().from_env(); self.ln = self.ln.clone().from_env(); diff --git a/crates/cdk-mintd/src/lib.rs b/crates/cdk-mintd/src/lib.rs index 3bde4706c..2a058e950 100644 --- a/crates/cdk-mintd/src/lib.rs +++ b/crates/cdk-mintd/src/lib.rs @@ -43,7 +43,7 @@ use cdk_common::database::DynMintDatabase; #[cfg(feature = "prometheus")] use cdk_common::payment::MetricsMintPayment; use cdk_common::payment::MintPayment; -#[cfg(feature = "auth")] +#[cfg(all(feature = "auth", feature = "postgres"))] use cdk_postgres::MintPgAuthDatabase; #[cfg(feature = "postgres")] use cdk_postgres::MintPgDatabase; @@ -663,16 +663,20 @@ async fn setup_authentication( DatabaseEngine::Postgres => { #[cfg(feature = "postgres")] { - // Get the PostgreSQL configuration, ensuring it exists - let pg_config = settings.database.postgres.as_ref().ok_or_else(|| { - anyhow!("PostgreSQL configuration is required when using PostgreSQL engine") + // Require dedicated auth database configuration - no fallback to main database + let auth_db_config = settings.auth_database.as_ref().ok_or_else(|| { + anyhow!("Auth database configuration is required when using PostgreSQL with authentication. Set [auth_database] section in config file or CDK_MINTD_AUTH_POSTGRES_URL environment variable") + })?; + + let auth_pg_config = auth_db_config.postgres.as_ref().ok_or_else(|| { + anyhow!("PostgreSQL auth database configuration is required when using PostgreSQL with authentication. Set [auth_database.postgres] section in config file or CDK_MINTD_AUTH_POSTGRES_URL environment variable") })?; - if pg_config.url.is_empty() { - bail!("PostgreSQL URL is required for auth database. Set it in config file [database.postgres] section or via CDK_MINTD_POSTGRES_URL/CDK_MINTD_DATABASE_URL environment variable"); + if auth_pg_config.url.is_empty() { + bail!("Auth database PostgreSQL URL is required and cannot be empty. Set it in config file [auth_database.postgres] section or via CDK_MINTD_AUTH_POSTGRES_URL environment variable"); } - Arc::new(MintPgAuthDatabase::new(pg_config.url.as_str()).await?) + Arc::new(MintPgAuthDatabase::new(auth_pg_config.url.as_str()).await?) } #[cfg(not(feature = "postgres"))] { @@ -1188,3 +1192,27 @@ pub async fn run_mintd_with_shutdown( ) .await } + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn test_postgres_auth_url_validation() { + // Test that the auth database config requires explicit configuration + + // Test empty URL + let auth_config = config::PostgresAuthConfig { + url: "".to_string(), + ..Default::default() + }; + assert!(auth_config.url.is_empty()); + + // Test non-empty URL + let auth_config = config::PostgresAuthConfig { + url: "postgresql://user:password@localhost:5432/auth_db".to_string(), + ..Default::default() + }; + assert!(!auth_config.url.is_empty()); + } +} diff --git a/crates/cdk-postgres/start_db_for_test.sh b/crates/cdk-postgres/start_db_for_test.sh index d2a95b822..7a53af47a 100755 --- a/crates/cdk-postgres/start_db_for_test.sh +++ b/crates/cdk-postgres/start_db_for_test.sh @@ -27,4 +27,11 @@ docker exec -e PGPASSWORD="${DB_PASS}" "${CONTAINER_NAME}" \ docker exec -e PGPASSWORD="${DB_PASS}" "${CONTAINER_NAME}" \ psql -U "${DB_USER}" -d "${DB_NAME}" -c "CREATE DATABASE mintdb_auth;" +# Export environment variables for both main and auth databases export DATABASE_URL="host=localhost user=${DB_USER} password=${DB_PASS} dbname=${DB_NAME} port=${DB_PORT}" +export CDK_MINTD_POSTGRES_URL="postgresql://${DB_USER}:${DB_PASS}@localhost:${DB_PORT}/mintdb" +export CDK_MINTD_AUTH_POSTGRES_URL="postgresql://${DB_USER}:${DB_PASS}@localhost:${DB_PORT}/mintdb_auth" + +echo "Database URLs configured:" +echo "Main database: ${CDK_MINTD_POSTGRES_URL}" +echo "Auth database: ${CDK_MINTD_AUTH_POSTGRES_URL}" diff --git a/crates/cdk-sql-common/src/mint/auth/mod.rs b/crates/cdk-sql-common/src/mint/auth/mod.rs index f5ca43569..cd5739567 100644 --- a/crates/cdk-sql-common/src/mint/auth/mod.rs +++ b/crates/cdk-sql-common/src/mint/auth/mod.rs @@ -198,9 +198,11 @@ where for (endpoint, auth) in protected_endpoints.iter() { if let Err(err) = query( r#" - INSERT OR REPLACE INTO protected_endpoints + INSERT INTO protected_endpoints (endpoint, auth) - VALUES (:endpoint, :auth); + VALUES (:endpoint, :auth) + ON CONFLICT (endpoint) DO UPDATE SET + auth = EXCLUDED.auth; "#, )? .bind("endpoint", serde_json::to_string(endpoint)?) From be7c83689d2444ba9028e39c9b4a0416eec13a99 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Sun, 21 Sep 2025 20:04:27 +0100 Subject: [PATCH 171/321] feat: remove redis cache (#1096) * feat: remove redis cache * feat: remove redis cache --- .github/workflows/ci.yml | 7 +- crates/cdk-axum/Cargo.toml | 4 - crates/cdk-axum/src/cache/backend/mod.rs | 4 - crates/cdk-axum/src/cache/backend/redis.rs | 96 ---------------------- crates/cdk-axum/src/cache/config.rs | 34 -------- crates/cdk-axum/src/cache/mod.rs | 19 +---- crates/cdk-mintd/Cargo.toml | 1 - crates/cdk-mintd/example.config.toml | 5 +- docker-compose.yaml | 26 +----- 9 files changed, 6 insertions(+), 190 deletions(-) delete mode 100644 crates/cdk-axum/src/cache/backend/redis.rs diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index bc3115048..219a9e309 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -103,8 +103,7 @@ jobs: # HTTP/API layer - consolidated -p cdk-axum, -p cdk-axum --no-default-features, - -p cdk-axum --no-default-features --features redis, - -p cdk-axum --no-default-features --features "redis swagger", + -p cdk-axum --no-default-features --features swagger, # Lightning backends -p cdk-cln, @@ -130,7 +129,7 @@ jobs: --bin cdk-cli --features sqlcipher, --bin cdk-cli --features redb, --bin cdk-mintd, - --bin cdk-mintd --features redis, + --bin cdk-mintd --features sqlcipher, --bin cdk-mintd --no-default-features --features lnd --features sqlite, --bin cdk-mintd --no-default-features --features cln --features postgres, @@ -341,7 +340,7 @@ jobs: -p cdk --no-default-features --features "wallet auth", -p cdk --no-default-features --features "http_subscription", -p cdk-axum, - -p cdk-axum --no-default-features --features redis, + -p cdk-lnbits, -p cdk-fake-wallet, -p cdk-cln, diff --git a/crates/cdk-axum/Cargo.toml b/crates/cdk-axum/Cargo.toml index 7ef7e1454..5f0a9c930 100644 --- a/crates/cdk-axum/Cargo.toml +++ b/crates/cdk-axum/Cargo.toml @@ -12,7 +12,6 @@ readme = "README.md" [features] default = ["auth"] -redis = ["dep:redis"] swagger = ["cdk/swagger", "dep:utoipa"] auth = ["cdk/auth"] prometheus = ["dep:cdk-prometheus"] @@ -34,9 +33,6 @@ paste = "1.0.15" serde.workspace = true uuid.workspace = true sha2 = "0.10.8" -redis = { version = "0.31.0", features = [ - "tokio-rustls-comp", -], optional = true } [target.'cfg(target_arch = "wasm32")'.dependencies] uuid = { workspace = true, features = ["js"] } diff --git a/crates/cdk-axum/src/cache/backend/mod.rs b/crates/cdk-axum/src/cache/backend/mod.rs index 511d156f9..cc0e8ad66 100644 --- a/crates/cdk-axum/src/cache/backend/mod.rs +++ b/crates/cdk-axum/src/cache/backend/mod.rs @@ -1,7 +1,3 @@ mod memory; -#[cfg(feature = "redis")] -mod redis; pub use self::memory::InMemoryHttpCache; -#[cfg(feature = "redis")] -pub use self::redis::{Config as RedisConfig, HttpCacheRedis}; diff --git a/crates/cdk-axum/src/cache/backend/redis.rs b/crates/cdk-axum/src/cache/backend/redis.rs deleted file mode 100644 index 358350f6f..000000000 --- a/crates/cdk-axum/src/cache/backend/redis.rs +++ /dev/null @@ -1,96 +0,0 @@ -use std::time::Duration; - -use redis::AsyncCommands; -use serde::{Deserialize, Serialize}; - -use crate::cache::{HttpCacheKey, HttpCacheStorage}; - -/// Redis cache storage for the HTTP cache. -/// -/// This cache storage backend uses Redis to store the cache. -pub struct HttpCacheRedis { - cache_ttl: Duration, - prefix: Option>, - client: redis::Client, -} - -/// Configuration for the Redis cache storage. -#[derive(Debug, Clone, Serialize, Deserialize, Default)] -pub struct Config { - /// Commong key prefix - pub key_prefix: Option, - - /// Connection string to the Redis server. - pub connection_string: String, -} - -impl HttpCacheRedis { - /// Create a new Redis cache. - pub fn new(client: redis::Client) -> Self { - Self { - client, - prefix: None, - cache_ttl: Duration::from_secs(60), - } - } - - /// Set a prefix for the cache keys. - /// - /// This is useful to have all the HTTP cache keys under a common prefix, - /// some sort of namespace, to make management of the database easier. - pub fn set_prefix(mut self, prefix: Vec) -> Self { - self.prefix = Some(prefix); - self - } -} - -#[async_trait::async_trait] -impl HttpCacheStorage for HttpCacheRedis { - fn set_expiration_times(&mut self, cache_ttl: Duration, _cache_tti: Duration) { - self.cache_ttl = cache_ttl; - } - - async fn get(&self, key: &HttpCacheKey) -> Option> { - let mut conn = self - .client - .get_multiplexed_tokio_connection() - .await - .map_err(|err| { - tracing::error!("Failed to get redis connection: {:?}", err); - err - }) - .ok()?; - - let mut db_key = self.prefix.clone().unwrap_or_default(); - db_key.extend(&**key); - - conn.get(db_key) - .await - .map_err(|err| { - tracing::error!("Failed to get value from redis: {:?}", err); - err - }) - .ok()? - } - - async fn set(&self, key: HttpCacheKey, value: Vec) { - let mut db_key = self.prefix.clone().unwrap_or_default(); - db_key.extend(&*key); - - let mut conn = match self.client.get_multiplexed_tokio_connection().await { - Ok(conn) => conn, - Err(err) => { - tracing::error!("Failed to get redis connection: {:?}", err); - return; - } - }; - - let _: Result<(), _> = conn - .set_ex(db_key, value, self.cache_ttl.as_secs()) - .await - .map_err(|err| { - tracing::error!("Failed to set value in redis: {:?}", err); - err - }); - } -} diff --git a/crates/cdk-axum/src/cache/config.rs b/crates/cdk-axum/src/cache/config.rs index f50551221..c507764b2 100644 --- a/crates/cdk-axum/src/cache/config.rs +++ b/crates/cdk-axum/src/cache/config.rs @@ -2,11 +2,6 @@ use serde::{Deserialize, Serialize}; pub const ENV_CDK_MINTD_CACHE_BACKEND: &str = "CDK_MINTD_CACHE_BACKEND"; -#[cfg(feature = "redis")] -pub const ENV_CDK_MINTD_CACHE_REDIS_URL: &str = "CDK_MINTD_CACHE_REDIS_URL"; -#[cfg(feature = "redis")] -pub const ENV_CDK_MINTD_CACHE_REDIS_KEY_PREFIX: &str = "CDK_MINTD_CACHE_REDIS_KEY_PREFIX"; - pub const ENV_CDK_MINTD_CACHE_TTI: &str = "CDK_MINTD_CACHE_TTI"; pub const ENV_CDK_MINTD_CACHE_TTL: &str = "CDK_MINTD_CACHE_TTL"; @@ -16,27 +11,12 @@ pub const ENV_CDK_MINTD_CACHE_TTL: &str = "CDK_MINTD_CACHE_TTL"; pub enum Backend { #[default] Memory, - #[cfg(feature = "redis")] - Redis(super::backend::RedisConfig), } impl Backend { pub fn from_env_str(backend_str: &str) -> Option { match backend_str.to_lowercase().as_str() { "memory" => Some(Self::Memory), - #[cfg(feature = "redis")] - "redis" => { - // Get Redis configuration from environment - let connection_string = std::env::var(ENV_CDK_MINTD_CACHE_REDIS_URL) - .unwrap_or_else(|_| "redis://127.0.0.1:6379".to_string()); - - let key_prefix = std::env::var(ENV_CDK_MINTD_CACHE_REDIS_KEY_PREFIX).ok(); - - Some(Self::Redis(super::backend::RedisConfig { - connection_string, - key_prefix, - })) - } _ => None, } } @@ -66,20 +46,6 @@ impl Config { if let Ok(backend_str) = env::var(ENV_CDK_MINTD_CACHE_BACKEND) { if let Some(backend) = Backend::from_env_str(&backend_str) { self.backend = backend; - - // If Redis backend is selected, parse Redis configuration - #[cfg(feature = "redis")] - if matches!(self.backend, Backend::Redis(_)) { - let connection_string = env::var(ENV_CDK_MINTD_CACHE_REDIS_URL) - .unwrap_or_else(|_| "redis://127.0.0.1:6379".to_string()); - - let key_prefix = env::var(ENV_CDK_MINTD_CACHE_REDIS_KEY_PREFIX).ok(); - - self.backend = Backend::Redis(super::backend::RedisConfig { - connection_string, - key_prefix, - }); - } } } diff --git a/crates/cdk-axum/src/cache/mod.rs b/crates/cdk-axum/src/cache/mod.rs index f07968d0e..de56d6666 100644 --- a/crates/cdk-axum/src/cache/mod.rs +++ b/crates/cdk-axum/src/cache/mod.rs @@ -7,7 +7,7 @@ //! idempotent operations. //! //! This mod also provides common backend implementations as well, such as In -//! Memory (default) and Redis. +//! Memory (default). use std::ops::Deref; use std::sync::Arc; use std::time::Duration; @@ -89,23 +89,6 @@ impl From for HttpCache { Duration::from_secs(config.tti.unwrap_or(DEFAULT_TTI_SECS)), None, ), - #[cfg(feature = "redis")] - config::Backend::Redis(redis_config) => { - let client = redis::Client::open(redis_config.connection_string) - .expect("Failed to create Redis client"); - let storage = HttpCacheRedis::new(client).set_prefix( - redis_config - .key_prefix - .unwrap_or_default() - .as_bytes() - .to_vec(), - ); - Self::new( - Duration::from_secs(config.ttl.unwrap_or(DEFAULT_TTL_SECS)), - Duration::from_secs(config.tti.unwrap_or(DEFAULT_TTI_SECS)), - Some(Box::new(storage)), - ) - } } } } diff --git a/crates/cdk-mintd/Cargo.toml b/crates/cdk-mintd/Cargo.toml index ae83b7515..85f231109 100644 --- a/crates/cdk-mintd/Cargo.toml +++ b/crates/cdk-mintd/Cargo.toml @@ -26,7 +26,6 @@ grpc-processor = ["dep:cdk-payment-processor", "cdk-signatory/grpc"] sqlcipher = ["sqlite", "cdk-sqlite/sqlcipher"] # MSRV is not committed to with swagger enabled swagger = ["cdk-axum/swagger", "dep:utoipa", "dep:utoipa-swagger-ui"] -redis = ["cdk-axum/redis"] auth = ["cdk/auth", "cdk-axum/auth", "cdk-sqlite?/auth", "cdk-postgres?/auth"] prometheus = ["cdk/prometheus", "dep:cdk-prometheus", "cdk-sqlite?/prometheus", "cdk-axum/prometheus"] diff --git a/crates/cdk-mintd/example.config.toml b/crates/cdk-mintd/example.config.toml index c65105396..79e0f8675 100644 --- a/crates/cdk-mintd/example.config.toml +++ b/crates/cdk-mintd/example.config.toml @@ -33,13 +33,10 @@ enabled = false #port = 9090 # [info.http_cache] -# memory or redis +# backend type: memory (default) backend = "memory" ttl = 60 tti = 60 -# `key_prefix` and `connection_string` required for redis -# key_prefix = "mintd" -# connection_string = "redis://localhost" # NOTE: If [mint_management_rpc] is enabled these values will only be used on first start up. # Further changes must be made through the rpc. diff --git a/docker-compose.yaml b/docker-compose.yaml index 4a4ba88cf..f405d984b 100644 --- a/docker-compose.yaml +++ b/docker-compose.yaml @@ -58,9 +58,6 @@ services: # - CDK_MINTD_DATABASE_URL=postgresql://cdk_user:cdk_password@postgres:5432/cdk_mint # Cache configuration - CDK_MINTD_CACHE_BACKEND=memory - # For Redis cache (requires redis service, enable with: docker-compose --profile redis up): - # - CDK_MINTD_CACHE_REDIS_URL=redis://redis:6379 - # - CDK_MINTD_CACHE_REDIS_KEY_PREFIX=cdk-mintd - CDK_MINTD_PROMETHEUS_ENABLED=true - CDK_MINTD_PROMETHEUS_ADDRESS=0.0.0.0 - CDK_MINTD_PROMETHEUS_PORT=9000 @@ -97,32 +94,11 @@ services: # timeout: 5s # retries: 5 - # Redis cache service (optional) - # Enable with: docker-compose --profile redis up -# redis: -# image: redis:7-alpine -# container_name: mint_redis -# restart: unless-stopped -# profiles: -# - redis -# ports: -# - "6379:6379" -# volumes: -# - redis_data:/data -# command: redis-server --save 60 1 --loglevel warning -# healthcheck: -# test: ["CMD", "redis-cli", "ping"] -# interval: 10s -# timeout: 3s -# retries: 5 + volumes: postgres_data: driver: local -# redis_data: -# driver: local - - networks: cdk: From 3ad860c908af780ffc8ec54691f2f47563030bb0 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Mon, 22 Sep 2025 13:53:32 +0100 Subject: [PATCH 172/321] fix(cdk): improve error handling when adding mint to MultiMintWallet (#1099) Add proper error handling and logging for add_mint operation instead of propagating errors, preventing wallet operations from failing completely when a mint cannot be added. --- crates/cdk/src/wallet/multi_mint_wallet.rs | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/crates/cdk/src/wallet/multi_mint_wallet.rs b/crates/cdk/src/wallet/multi_mint_wallet.rs index c80483a0d..6906f04db 100644 --- a/crates/cdk/src/wallet/multi_mint_wallet.rs +++ b/crates/cdk/src/wallet/multi_mint_wallet.rs @@ -242,7 +242,13 @@ impl MultiMintWallet { if mint_has_proofs_for_unit { // Add mint to the MultiMintWallet if not already present if !self.has_mint(&mint_url).await { - self.add_mint(mint_url, None).await?; + if let Err(err) = self.add_mint(mint_url.clone(), None).await { + tracing::error!( + "Could not add {} to wallet {}.", + mint_url, + err.to_string() + ); + } } } } From c1e35f964b0a3cd805f054587e1b905e6e51f317 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Mon, 22 Sep 2025 16:50:51 +0100 Subject: [PATCH 173/321] Remove cashu ffi (#1102) * feat: remove cdk-common and cashu from cdk-ffi --- crates/cdk-ffi/Cargo.toml | 4 +- crates/cdk-ffi/src/database.rs | 246 ++++++++++++++++----------------- crates/cdk-ffi/src/error.rs | 4 +- crates/cdk-ffi/src/types.rs | 158 ++++++++++----------- crates/cdk-ffi/src/wallet.rs | 2 +- 5 files changed, 194 insertions(+), 220 deletions(-) diff --git a/crates/cdk-ffi/Cargo.toml b/crates/cdk-ffi/Cargo.toml index ff61416eb..0840750b1 100644 --- a/crates/cdk-ffi/Cargo.toml +++ b/crates/cdk-ffi/Cargo.toml @@ -12,15 +12,13 @@ name = "cdk_ffi" [features] default = ["auth", "bip353"] -auth = ["cdk/auth", "cdk-common/auth", "cashu/auth"] +auth = ["cdk/auth"] bip353 = ["cdk/bip353"] [dependencies] async-trait = { workspace = true } bip39 = { workspace = true } -cashu = { workspace = true } cdk = { workspace = true, default-features = false, features = ["wallet"] } -cdk-common = { workspace = true } cdk-sqlite = { workspace = true } ctor = "0.2" futures = { workspace = true } diff --git a/crates/cdk-ffi/src/database.rs b/crates/cdk-ffi/src/database.rs index 13819ad0e..b1110aed6 100644 --- a/crates/cdk-ffi/src/database.rs +++ b/crates/cdk-ffi/src/database.rs @@ -3,7 +3,7 @@ use std::collections::HashMap; use std::sync::Arc; -use cdk_common::database::WalletDatabase as CdkWalletDatabase; +use cdk::cdk_database::WalletDatabase as CdkWalletDatabase; use cdk_sqlite::wallet::WalletSqliteDatabase as CdkWalletSqliteDatabase; use crate::error::FfiError; @@ -161,13 +161,13 @@ impl std::fmt::Debug for WalletDatabaseBridge { #[async_trait::async_trait] impl CdkWalletDatabase for WalletDatabaseBridge { - type Err = cdk_common::database::Error; + type Err = cdk::cdk_database::Error; // Mint Management async fn add_mint( &self, - mint_url: cdk_common::mint_url::MintUrl, - mint_info: Option, + mint_url: cdk::mint_url::MintUrl, + mint_info: Option, ) -> Result<(), Self::Err> { let ffi_mint_url = mint_url.into(); let ffi_mint_info = mint_info.map(Into::into); @@ -175,45 +175,44 @@ impl CdkWalletDatabase for WalletDatabaseBridge { self.ffi_db .add_mint(ffi_mint_url, ffi_mint_info) .await - .map_err(|e| cdk_common::database::Error::Database(e.to_string().into())) + .map_err(|e| cdk::cdk_database::Error::Database(e.to_string().into())) } - async fn remove_mint(&self, mint_url: cdk_common::mint_url::MintUrl) -> Result<(), Self::Err> { + async fn remove_mint(&self, mint_url: cdk::mint_url::MintUrl) -> Result<(), Self::Err> { let ffi_mint_url = mint_url.into(); self.ffi_db .remove_mint(ffi_mint_url) .await - .map_err(|e| cdk_common::database::Error::Database(e.to_string().into())) + .map_err(|e| cdk::cdk_database::Error::Database(e.to_string().into())) } async fn get_mint( &self, - mint_url: cdk_common::mint_url::MintUrl, - ) -> Result, Self::Err> { + mint_url: cdk::mint_url::MintUrl, + ) -> Result, Self::Err> { let ffi_mint_url = mint_url.into(); let result = self .ffi_db .get_mint(ffi_mint_url) .await - .map_err(|e| cdk_common::database::Error::Database(e.to_string().into()))?; + .map_err(|e| cdk::cdk_database::Error::Database(e.to_string().into()))?; Ok(result.map(Into::into)) } async fn get_mints( &self, - ) -> Result>, Self::Err> - { + ) -> Result>, Self::Err> { let result = self .ffi_db .get_mints() .await - .map_err(|e| cdk_common::database::Error::Database(e.to_string().into()))?; + .map_err(|e| cdk::cdk_database::Error::Database(e.to_string().into()))?; let mut cdk_result = HashMap::new(); for (ffi_mint_url, mint_info_opt) in result { - let cdk_url = ffi_mint_url.try_into().map_err(|e: FfiError| { - cdk_common::database::Error::Database(e.to_string().into()) - })?; + let cdk_url = ffi_mint_url + .try_into() + .map_err(|e: FfiError| cdk::cdk_database::Error::Database(e.to_string().into()))?; cdk_result.insert(cdk_url, mint_info_opt.map(Into::into)); } Ok(cdk_result) @@ -221,22 +220,22 @@ impl CdkWalletDatabase for WalletDatabaseBridge { async fn update_mint_url( &self, - old_mint_url: cdk_common::mint_url::MintUrl, - new_mint_url: cdk_common::mint_url::MintUrl, + old_mint_url: cdk::mint_url::MintUrl, + new_mint_url: cdk::mint_url::MintUrl, ) -> Result<(), Self::Err> { let ffi_old_mint_url = old_mint_url.into(); let ffi_new_mint_url = new_mint_url.into(); self.ffi_db .update_mint_url(ffi_old_mint_url, ffi_new_mint_url) .await - .map_err(|e| cdk_common::database::Error::Database(e.to_string().into())) + .map_err(|e| cdk::cdk_database::Error::Database(e.to_string().into())) } // Keyset Management async fn add_mint_keysets( &self, - mint_url: cdk_common::mint_url::MintUrl, - keysets: Vec, + mint_url: cdk::mint_url::MintUrl, + keysets: Vec, ) -> Result<(), Self::Err> { let ffi_mint_url = mint_url.into(); let ffi_keysets: Vec = keysets.into_iter().map(Into::into).collect(); @@ -244,74 +243,72 @@ impl CdkWalletDatabase for WalletDatabaseBridge { self.ffi_db .add_mint_keysets(ffi_mint_url, ffi_keysets) .await - .map_err(|e| cdk_common::database::Error::Database(e.to_string().into())) + .map_err(|e| cdk::cdk_database::Error::Database(e.to_string().into())) } async fn get_mint_keysets( &self, - mint_url: cdk_common::mint_url::MintUrl, - ) -> Result>, Self::Err> { + mint_url: cdk::mint_url::MintUrl, + ) -> Result>, Self::Err> { let ffi_mint_url = mint_url.into(); let result = self .ffi_db .get_mint_keysets(ffi_mint_url) .await - .map_err(|e| cdk_common::database::Error::Database(e.to_string().into()))?; + .map_err(|e| cdk::cdk_database::Error::Database(e.to_string().into()))?; Ok(result.map(|keysets| keysets.into_iter().map(Into::into).collect())) } async fn get_keyset_by_id( &self, - keyset_id: &cdk_common::nuts::Id, - ) -> Result, Self::Err> { + keyset_id: &cdk::nuts::Id, + ) -> Result, Self::Err> { let ffi_id = (*keyset_id).into(); let result = self .ffi_db .get_keyset_by_id(ffi_id) .await - .map_err(|e| cdk_common::database::Error::Database(e.to_string().into()))?; + .map_err(|e| cdk::cdk_database::Error::Database(e.to_string().into()))?; Ok(result.map(Into::into)) } // Mint Quote Management - async fn add_mint_quote(&self, quote: cdk_common::wallet::MintQuote) -> Result<(), Self::Err> { + async fn add_mint_quote(&self, quote: cdk::wallet::MintQuote) -> Result<(), Self::Err> { let ffi_quote = quote.into(); self.ffi_db .add_mint_quote(ffi_quote) .await - .map_err(|e| cdk_common::database::Error::Database(e.to_string().into())) + .map_err(|e| cdk::cdk_database::Error::Database(e.to_string().into())) } async fn get_mint_quote( &self, quote_id: &str, - ) -> Result, Self::Err> { + ) -> Result, Self::Err> { let result = self .ffi_db .get_mint_quote(quote_id.to_string()) .await - .map_err(|e| cdk_common::database::Error::Database(e.to_string().into()))?; + .map_err(|e| cdk::cdk_database::Error::Database(e.to_string().into()))?; Ok(result .map(|q| { - q.try_into().map_err(|e: FfiError| { - cdk_common::database::Error::Database(e.to_string().into()) - }) + q.try_into() + .map_err(|e: FfiError| cdk::cdk_database::Error::Database(e.to_string().into())) }) .transpose()?) } - async fn get_mint_quotes(&self) -> Result, Self::Err> { + async fn get_mint_quotes(&self) -> Result, Self::Err> { let result = self .ffi_db .get_mint_quotes() .await - .map_err(|e| cdk_common::database::Error::Database(e.to_string().into()))?; + .map_err(|e| cdk::cdk_database::Error::Database(e.to_string().into()))?; Ok(result .into_iter() .map(|q| { - q.try_into().map_err(|e: FfiError| { - cdk_common::database::Error::Database(e.to_string().into()) - }) + q.try_into() + .map_err(|e: FfiError| cdk::cdk_database::Error::Database(e.to_string().into())) }) .collect::, _>>()?) } @@ -320,48 +317,46 @@ impl CdkWalletDatabase for WalletDatabaseBridge { self.ffi_db .remove_mint_quote(quote_id.to_string()) .await - .map_err(|e| cdk_common::database::Error::Database(e.to_string().into())) + .map_err(|e| cdk::cdk_database::Error::Database(e.to_string().into())) } // Melt Quote Management - async fn add_melt_quote(&self, quote: cdk_common::wallet::MeltQuote) -> Result<(), Self::Err> { + async fn add_melt_quote(&self, quote: cdk::wallet::MeltQuote) -> Result<(), Self::Err> { let ffi_quote = quote.into(); self.ffi_db .add_melt_quote(ffi_quote) .await - .map_err(|e| cdk_common::database::Error::Database(e.to_string().into())) + .map_err(|e| cdk::cdk_database::Error::Database(e.to_string().into())) } async fn get_melt_quote( &self, quote_id: &str, - ) -> Result, Self::Err> { + ) -> Result, Self::Err> { let result = self .ffi_db .get_melt_quote(quote_id.to_string()) .await - .map_err(|e| cdk_common::database::Error::Database(e.to_string().into()))?; + .map_err(|e| cdk::cdk_database::Error::Database(e.to_string().into()))?; Ok(result .map(|q| { - q.try_into().map_err(|e: FfiError| { - cdk_common::database::Error::Database(e.to_string().into()) - }) + q.try_into() + .map_err(|e: FfiError| cdk::cdk_database::Error::Database(e.to_string().into())) }) .transpose()?) } - async fn get_melt_quotes(&self) -> Result, Self::Err> { + async fn get_melt_quotes(&self) -> Result, Self::Err> { let result = self .ffi_db .get_melt_quotes() .await - .map_err(|e| cdk_common::database::Error::Database(e.to_string().into()))?; + .map_err(|e| cdk::cdk_database::Error::Database(e.to_string().into()))?; Ok(result .into_iter() .map(|q| { - q.try_into().map_err(|e: FfiError| { - cdk_common::database::Error::Database(e.to_string().into()) - }) + q.try_into() + .map_err(|e: FfiError| cdk::cdk_database::Error::Database(e.to_string().into())) }) .collect::, _>>()?) } @@ -370,52 +365,49 @@ impl CdkWalletDatabase for WalletDatabaseBridge { self.ffi_db .remove_melt_quote(quote_id.to_string()) .await - .map_err(|e| cdk_common::database::Error::Database(e.to_string().into())) + .map_err(|e| cdk::cdk_database::Error::Database(e.to_string().into())) } // Keys Management - async fn add_keys(&self, keyset: cashu::KeySet) -> Result<(), Self::Err> { + async fn add_keys(&self, keyset: cdk::nuts::KeySet) -> Result<(), Self::Err> { let ffi_keyset: KeySet = keyset.into(); self.ffi_db .add_keys(ffi_keyset) .await - .map_err(|e| cdk_common::database::Error::Database(e.to_string().into())) + .map_err(|e| cdk::cdk_database::Error::Database(e.to_string().into())) } - async fn get_keys( - &self, - id: &cdk_common::nuts::Id, - ) -> Result, Self::Err> { + async fn get_keys(&self, id: &cdk::nuts::Id) -> Result, Self::Err> { let ffi_id: Id = (*id).into(); let result = self .ffi_db .get_keys(ffi_id) .await - .map_err(|e| cdk_common::database::Error::Database(e.to_string().into()))?; + .map_err(|e| cdk::cdk_database::Error::Database(e.to_string().into()))?; // Convert FFI Keys back to CDK Keys using TryFrom result .map(|ffi_keys| { - ffi_keys.try_into().map_err(|e: FfiError| { - cdk_common::database::Error::Database(e.to_string().into()) - }) + ffi_keys + .try_into() + .map_err(|e: FfiError| cdk::cdk_database::Error::Database(e.to_string().into())) }) .transpose() } - async fn remove_keys(&self, id: &cdk_common::nuts::Id) -> Result<(), Self::Err> { + async fn remove_keys(&self, id: &cdk::nuts::Id) -> Result<(), Self::Err> { let ffi_id = (*id).into(); self.ffi_db .remove_keys(ffi_id) .await - .map_err(|e| cdk_common::database::Error::Database(e.to_string().into())) + .map_err(|e| cdk::cdk_database::Error::Database(e.to_string().into())) } // Proof Management async fn update_proofs( &self, - added: Vec, - removed_ys: Vec, + added: Vec, + removed_ys: Vec, ) -> Result<(), Self::Err> { let ffi_added: Vec = added.into_iter().map(Into::into).collect(); let ffi_removed_ys: Vec = removed_ys.into_iter().map(Into::into).collect(); @@ -423,16 +415,16 @@ impl CdkWalletDatabase for WalletDatabaseBridge { self.ffi_db .update_proofs(ffi_added, ffi_removed_ys) .await - .map_err(|e| cdk_common::database::Error::Database(e.to_string().into())) + .map_err(|e| cdk::cdk_database::Error::Database(e.to_string().into())) } async fn get_proofs( &self, - mint_url: Option, - unit: Option, - state: Option>, - spending_conditions: Option>, - ) -> Result, Self::Err> { + mint_url: Option, + unit: Option, + state: Option>, + spending_conditions: Option>, + ) -> Result, Self::Err> { let ffi_mint_url = mint_url.map(Into::into); let ffi_unit = unit.map(Into::into); let ffi_state = state.map(|s| s.into_iter().map(Into::into).collect()); @@ -443,41 +435,40 @@ impl CdkWalletDatabase for WalletDatabaseBridge { .ffi_db .get_proofs(ffi_mint_url, ffi_unit, ffi_state, ffi_spending_conditions) .await - .map_err(|e| cdk_common::database::Error::Database(e.to_string().into()))?; + .map_err(|e| cdk::cdk_database::Error::Database(e.to_string().into()))?; // Convert back to CDK ProofInfo - let cdk_result: Result, cdk_common::database::Error> = - result - .into_iter() - .map(|info| { - Ok(cdk_common::common::ProofInfo { - proof: info.proof.inner.clone(), - y: info.y.try_into().map_err(|e: FfiError| { - cdk_common::database::Error::Database(e.to_string().into()) - })?, - mint_url: info.mint_url.try_into().map_err(|e: FfiError| { - cdk_common::database::Error::Database(e.to_string().into()) + let cdk_result: Result, cdk::cdk_database::Error> = result + .into_iter() + .map(|info| { + Ok(cdk::types::ProofInfo { + proof: info.proof.inner.clone(), + y: info.y.try_into().map_err(|e: FfiError| { + cdk::cdk_database::Error::Database(e.to_string().into()) + })?, + mint_url: info.mint_url.try_into().map_err(|e: FfiError| { + cdk::cdk_database::Error::Database(e.to_string().into()) + })?, + state: info.state.into(), + spending_condition: info + .spending_condition + .map(|sc| sc.try_into()) + .transpose() + .map_err(|e: FfiError| { + cdk::cdk_database::Error::Database(e.to_string().into()) })?, - state: info.state.into(), - spending_condition: info - .spending_condition - .map(|sc| sc.try_into()) - .transpose() - .map_err(|e: FfiError| { - cdk_common::database::Error::Database(e.to_string().into()) - })?, - unit: info.unit.into(), - }) + unit: info.unit.into(), }) - .collect(); + }) + .collect(); cdk_result } async fn update_proofs_state( &self, - ys: Vec, - state: cdk_common::nuts::State, + ys: Vec, + state: cdk::nuts::State, ) -> Result<(), Self::Err> { let ffi_ys: Vec = ys.into_iter().map(Into::into).collect(); let ffi_state = state.into(); @@ -485,57 +476,57 @@ impl CdkWalletDatabase for WalletDatabaseBridge { self.ffi_db .update_proofs_state(ffi_ys, ffi_state) .await - .map_err(|e| cdk_common::database::Error::Database(e.to_string().into())) + .map_err(|e| cdk::cdk_database::Error::Database(e.to_string().into())) } // Keyset Counter Management async fn increment_keyset_counter( &self, - keyset_id: &cdk_common::nuts::Id, + keyset_id: &cdk::nuts::Id, count: u32, ) -> Result { let ffi_id = (*keyset_id).into(); self.ffi_db .increment_keyset_counter(ffi_id, count) .await - .map_err(|e| cdk_common::database::Error::Database(e.to_string().into())) + .map_err(|e| cdk::cdk_database::Error::Database(e.to_string().into())) } // Transaction Management async fn add_transaction( &self, - transaction: cdk_common::wallet::Transaction, + transaction: cdk::wallet::types::Transaction, ) -> Result<(), Self::Err> { let ffi_transaction = transaction.into(); self.ffi_db .add_transaction(ffi_transaction) .await - .map_err(|e| cdk_common::database::Error::Database(e.to_string().into())) + .map_err(|e| cdk::cdk_database::Error::Database(e.to_string().into())) } async fn get_transaction( &self, - transaction_id: cdk_common::wallet::TransactionId, - ) -> Result, Self::Err> { + transaction_id: cdk::wallet::types::TransactionId, + ) -> Result, Self::Err> { let ffi_id = transaction_id.into(); let result = self .ffi_db .get_transaction(ffi_id) .await - .map_err(|e| cdk_common::database::Error::Database(e.to_string().into()))?; + .map_err(|e| cdk::cdk_database::Error::Database(e.to_string().into()))?; result .map(|tx| tx.try_into()) .transpose() - .map_err(|e: FfiError| cdk_common::database::Error::Database(e.to_string().into())) + .map_err(|e: FfiError| cdk::cdk_database::Error::Database(e.to_string().into())) } async fn list_transactions( &self, - mint_url: Option, - direction: Option, - unit: Option, - ) -> Result, Self::Err> { + mint_url: Option, + direction: Option, + unit: Option, + ) -> Result, Self::Err> { let ffi_mint_url = mint_url.map(Into::into); let ffi_direction = direction.map(Into::into); let ffi_unit = unit.map(Into::into); @@ -544,24 +535,24 @@ impl CdkWalletDatabase for WalletDatabaseBridge { .ffi_db .list_transactions(ffi_mint_url, ffi_direction, ffi_unit) .await - .map_err(|e| cdk_common::database::Error::Database(e.to_string().into()))?; + .map_err(|e| cdk::cdk_database::Error::Database(e.to_string().into()))?; result .into_iter() .map(|tx| tx.try_into()) .collect::, FfiError>>() - .map_err(|e| cdk_common::database::Error::Database(e.to_string().into())) + .map_err(|e| cdk::cdk_database::Error::Database(e.to_string().into())) } async fn remove_transaction( &self, - transaction_id: cdk_common::wallet::TransactionId, + transaction_id: cdk::wallet::types::TransactionId, ) -> Result<(), Self::Err> { let ffi_id = transaction_id.into(); self.ffi_db .remove_transaction(ffi_id) .await - .map_err(|e| cdk_common::database::Error::Database(e.to_string().into())) + .map_err(|e| cdk::cdk_database::Error::Database(e.to_string().into())) } } @@ -690,8 +681,7 @@ impl WalletDatabase for WalletSqliteDatabase { keysets: Vec, ) -> Result<(), FfiError> { let cdk_mint_url = mint_url.try_into()?; - let cdk_keysets: Vec = - keysets.into_iter().map(Into::into).collect(); + let cdk_keysets: Vec = keysets.into_iter().map(Into::into).collect(); self.inner .add_mint_keysets(cdk_mint_url, cdk_keysets) .await @@ -791,10 +781,10 @@ impl WalletDatabase for WalletSqliteDatabase { // Keys Management async fn add_keys(&self, keyset: KeySet) -> Result<(), FfiError> { - // Convert FFI KeySet to cashu::KeySet - let cashu_keyset: cashu::KeySet = keyset.try_into()?; + // Convert FFI KeySet to cdk::nuts::KeySet + let cdk_keyset: cdk::nuts::KeySet = keyset.try_into()?; self.inner - .add_keys(cashu_keyset) + .add_keys(cdk_keyset) .await .map_err(|e| FfiError::Database { msg: e.to_string() }) } @@ -824,10 +814,10 @@ impl WalletDatabase for WalletSqliteDatabase { removed_ys: Vec, ) -> Result<(), FfiError> { // Convert FFI types to CDK types - let cdk_added: Result, FfiError> = added + let cdk_added: Result, FfiError> = added .into_iter() .map(|info| { - Ok::(cdk_common::common::ProofInfo { + Ok::(cdk::types::ProofInfo { proof: info.proof.inner.clone(), y: info.y.try_into()?, mint_url: info.mint_url.try_into()?, @@ -842,7 +832,7 @@ impl WalletDatabase for WalletSqliteDatabase { .collect(); let cdk_added = cdk_added?; - let cdk_removed_ys: Result, FfiError> = + let cdk_removed_ys: Result, FfiError> = removed_ys.into_iter().map(|pk| pk.try_into()).collect(); let cdk_removed_ys = cdk_removed_ys?; @@ -862,7 +852,7 @@ impl WalletDatabase for WalletSqliteDatabase { let cdk_mint_url = mint_url.map(|u| u.try_into()).transpose()?; let cdk_unit = unit.map(Into::into); let cdk_state = state.map(|s| s.into_iter().map(Into::into).collect()); - let cdk_spending_conditions: Option> = + let cdk_spending_conditions: Option> = spending_conditions .map(|sc| { sc.into_iter() @@ -885,7 +875,7 @@ impl WalletDatabase for WalletSqliteDatabase { ys: Vec, state: ProofState, ) -> Result<(), FfiError> { - let cdk_ys: Result, FfiError> = + let cdk_ys: Result, FfiError> = ys.into_iter().map(|pk| pk.try_into()).collect(); let cdk_ys = cdk_ys?; let cdk_state = state.into(); @@ -908,7 +898,7 @@ impl WalletDatabase for WalletSqliteDatabase { // Transaction Management async fn add_transaction(&self, transaction: Transaction) -> Result<(), FfiError> { // Convert FFI Transaction to CDK Transaction using TryFrom - let cdk_transaction: cdk_common::wallet::Transaction = transaction.try_into()?; + let cdk_transaction: cdk::wallet::types::Transaction = transaction.try_into()?; self.inner .add_transaction(cdk_transaction) @@ -960,6 +950,6 @@ impl WalletDatabase for WalletSqliteDatabase { /// Helper function to create a CDK database from the FFI trait pub fn create_cdk_database_from_ffi( ffi_db: Arc, -) -> Arc + Send + Sync> { +) -> Arc + Send + Sync> { Arc::new(WalletDatabaseBridge::new(ffi_db)) } diff --git a/crates/cdk-ffi/src/error.rs b/crates/cdk-ffi/src/error.rs index e4be9f0ef..b1dcbce4a 100644 --- a/crates/cdk-ffi/src/error.rs +++ b/crates/cdk-ffi/src/error.rs @@ -107,8 +107,8 @@ impl From for FfiError { } } -impl From for FfiError { - fn from(err: cdk_common::nut00::Error) -> Self { +impl From for FfiError { + fn from(err: cdk::nuts::nut00::Error) -> Self { FfiError::Generic { msg: err.to_string(), } diff --git a/crates/cdk-ffi/src/types.rs b/crates/cdk-ffi/src/types.rs index 4c438e99b..e5da421c4 100644 --- a/crates/cdk-ffi/src/types.rs +++ b/crates/cdk-ffi/src/types.rs @@ -5,8 +5,8 @@ use std::str::FromStr; use std::sync::Mutex; use cdk::nuts::{CurrencyUnit as CdkCurrencyUnit, State as CdkState}; +use cdk::pub_sub::SubId; use cdk::Amount as CdkAmount; -use cdk_common::pub_sub::SubId; use serde::{Deserialize, Serialize}; use crate::error::FfiError; @@ -388,34 +388,32 @@ pub enum SendKind { OfflineTolerance { tolerance: Amount }, } -impl From for cdk_common::wallet::SendKind { +impl From for cdk::wallet::SendKind { fn from(kind: SendKind) -> Self { match kind { - SendKind::OnlineExact => cdk_common::wallet::SendKind::OnlineExact, + SendKind::OnlineExact => cdk::wallet::SendKind::OnlineExact, SendKind::OnlineTolerance { tolerance } => { - cdk_common::wallet::SendKind::OnlineTolerance(tolerance.into()) + cdk::wallet::SendKind::OnlineTolerance(tolerance.into()) } - SendKind::OfflineExact => cdk_common::wallet::SendKind::OfflineExact, + SendKind::OfflineExact => cdk::wallet::SendKind::OfflineExact, SendKind::OfflineTolerance { tolerance } => { - cdk_common::wallet::SendKind::OfflineTolerance(tolerance.into()) + cdk::wallet::SendKind::OfflineTolerance(tolerance.into()) } } } } -impl From for SendKind { - fn from(kind: cdk_common::wallet::SendKind) -> Self { +impl From for SendKind { + fn from(kind: cdk::wallet::SendKind) -> Self { match kind { - cdk_common::wallet::SendKind::OnlineExact => SendKind::OnlineExact, - cdk_common::wallet::SendKind::OnlineTolerance(tolerance) => SendKind::OnlineTolerance { + cdk::wallet::SendKind::OnlineExact => SendKind::OnlineExact, + cdk::wallet::SendKind::OnlineTolerance(tolerance) => SendKind::OnlineTolerance { + tolerance: tolerance.into(), + }, + cdk::wallet::SendKind::OfflineExact => SendKind::OfflineExact, + cdk::wallet::SendKind::OfflineTolerance(tolerance) => SendKind::OfflineTolerance { tolerance: tolerance.into(), }, - cdk_common::wallet::SendKind::OfflineExact => SendKind::OfflineExact, - cdk_common::wallet::SendKind::OfflineTolerance(tolerance) => { - SendKind::OfflineTolerance { - tolerance: tolerance.into(), - } - } } } } @@ -1299,8 +1297,8 @@ pub struct Melted { // MeltQuoteState is just an alias for nut05::QuoteState, so we don't need a separate implementation -impl From for Melted { - fn from(melted: cdk_common::common::Melted) -> Self { +impl From for Melted { + fn from(melted: cdk::types::Melted) -> Self { Self { state: melted.state.into(), preimage: melted.preimage, @@ -1588,7 +1586,7 @@ impl From for MintInfo { } } -impl From for cdk_common::nuts::MintInfo { +impl From for cdk::nuts::MintInfo { fn from(info: MintInfo) -> Self { Self { name: info.name, @@ -1599,7 +1597,7 @@ impl From for cdk_common::nuts::MintInfo { contact: info .contact .map(|contacts| contacts.into_iter().map(Into::into).collect()), - nuts: cdk_common::nuts::Nuts::default(), // Simplified conversion + nuts: cdk::nuts::Nuts::default(), // Simplified conversion icon_url: info.icon_url, urls: info.urls, motd: info.motd, @@ -1856,8 +1854,8 @@ pub struct Transaction { pub quote_id: Option, } -impl From for Transaction { - fn from(tx: cdk_common::wallet::Transaction) -> Self { +impl From for Transaction { + fn from(tx: cdk::wallet::types::Transaction) -> Self { Self { id: tx.id().into(), mint_url: tx.mint_url.into(), @@ -1875,11 +1873,11 @@ impl From for Transaction { } /// Convert FFI Transaction to CDK Transaction -impl TryFrom for cdk_common::wallet::Transaction { +impl TryFrom for cdk::wallet::types::Transaction { type Error = FfiError; fn try_from(tx: Transaction) -> Result { - let cdk_ys: Result, _> = + let cdk_ys: Result, _> = tx.ys.into_iter().map(|pk| pk.try_into()).collect(); let cdk_ys = cdk_ys?; @@ -1926,20 +1924,20 @@ pub enum TransactionDirection { Outgoing, } -impl From for TransactionDirection { - fn from(direction: cdk_common::wallet::TransactionDirection) -> Self { +impl From for TransactionDirection { + fn from(direction: cdk::wallet::types::TransactionDirection) -> Self { match direction { - cdk_common::wallet::TransactionDirection::Incoming => TransactionDirection::Incoming, - cdk_common::wallet::TransactionDirection::Outgoing => TransactionDirection::Outgoing, + cdk::wallet::types::TransactionDirection::Incoming => TransactionDirection::Incoming, + cdk::wallet::types::TransactionDirection::Outgoing => TransactionDirection::Outgoing, } } } -impl From for cdk_common::wallet::TransactionDirection { +impl From for cdk::wallet::types::TransactionDirection { fn from(direction: TransactionDirection) -> Self { match direction { - TransactionDirection::Incoming => cdk_common::wallet::TransactionDirection::Incoming, - TransactionDirection::Outgoing => cdk_common::wallet::TransactionDirection::Outgoing, + TransactionDirection::Incoming => cdk::wallet::types::TransactionDirection::Incoming, + TransactionDirection::Outgoing => cdk::wallet::types::TransactionDirection::Outgoing, } } } @@ -1975,26 +1973,26 @@ impl TransactionId { /// Create from proofs pub fn from_proofs(proofs: &Proofs) -> Result { let cdk_proofs: Vec = proofs.iter().map(|p| p.inner.clone()).collect(); - let id = cdk_common::wallet::TransactionId::from_proofs(cdk_proofs)?; + let id = cdk::wallet::types::TransactionId::from_proofs(cdk_proofs)?; Ok(Self { hex: id.to_string(), }) } } -impl From for TransactionId { - fn from(id: cdk_common::wallet::TransactionId) -> Self { +impl From for TransactionId { + fn from(id: cdk::wallet::types::TransactionId) -> Self { Self { hex: id.to_string(), } } } -impl TryFrom for cdk_common::wallet::TransactionId { +impl TryFrom for cdk::wallet::types::TransactionId { type Error = FfiError; fn try_from(id: TransactionId) -> Result { - cdk_common::wallet::TransactionId::from_hex(&id.hex) + cdk::wallet::types::TransactionId::from_hex(&id.hex) .map_err(|e| FfiError::InvalidHex { msg: e.to_string() }) } } @@ -2014,8 +2012,8 @@ pub struct AuthProof { } #[cfg(feature = "auth")] -impl From for AuthProof { - fn from(auth_proof: cdk_common::AuthProof) -> Self { +impl From for AuthProof { + fn from(auth_proof: cdk::nuts::AuthProof) -> Self { Self { keyset_id: auth_proof.keyset_id.to_string(), secret: auth_proof.secret.to_string(), @@ -2029,20 +2027,20 @@ impl From for AuthProof { } #[cfg(feature = "auth")] -impl TryFrom for cdk_common::AuthProof { +impl TryFrom for cdk::nuts::AuthProof { type Error = FfiError; fn try_from(auth_proof: AuthProof) -> Result { use std::str::FromStr; Ok(Self { - keyset_id: cdk_common::Id::from_str(&auth_proof.keyset_id) + keyset_id: cdk::nuts::Id::from_str(&auth_proof.keyset_id) .map_err(|e| FfiError::Serialization { msg: e.to_string() })?, secret: { use std::str::FromStr; - cdk_common::secret::Secret::from_str(&auth_proof.secret) + cdk::secret::Secret::from_str(&auth_proof.secret) .map_err(|e| FfiError::Serialization { msg: e.to_string() })? }, - c: cdk_common::PublicKey::from_str(&auth_proof.c) + c: cdk::nuts::PublicKey::from_str(&auth_proof.c) .map_err(|e| FfiError::InvalidCryptographicKey { msg: e.to_string() })?, dleq: None, // FFI doesn't expose DLEQ proofs for simplicity }) @@ -2150,7 +2148,7 @@ pub struct SubscribeParams { pub id: Option, } -impl From for cdk_common::subscription::Params { +impl From for cdk::nuts::nut17::Params { fn from(params: SubscribeParams) -> Self { let sub_id = params .id @@ -2329,8 +2327,8 @@ pub struct KeySetInfo { pub input_fee_ppk: u64, } -impl From for KeySetInfo { - fn from(keyset: cdk_common::nuts::KeySetInfo) -> Self { +impl From for KeySetInfo { + fn from(keyset: cdk::nuts::KeySetInfo) -> Self { Self { id: keyset.id.to_string(), unit: keyset.unit.into(), @@ -2340,17 +2338,11 @@ impl From for KeySetInfo { } } -impl From for cdk_common::nuts::KeySetInfo { +impl From for cdk::nuts::KeySetInfo { fn from(keyset: KeySetInfo) -> Self { use std::str::FromStr; Self { - id: cdk_common::nuts::Id::from_str(&keyset.id).unwrap_or_else(|_| { - // Create a dummy keyset for empty mint keys - use std::collections::BTreeMap; - let empty_map = BTreeMap::new(); - let empty_keys = cdk_common::nut01::MintKeys::new(empty_map); - cdk_common::nuts::Id::from(&empty_keys) - }), + id: cdk::nuts::Id::from_str(&keyset.id).unwrap(), unit: keyset.unit.into(), active: keyset.active, final_expiry: None, @@ -2386,15 +2378,15 @@ pub struct PublicKey { pub hex: String, } -impl From for PublicKey { - fn from(key: cdk_common::nuts::PublicKey) -> Self { +impl From for PublicKey { + fn from(key: cdk::nuts::PublicKey) -> Self { Self { hex: key.to_string(), } } } -impl TryFrom for cdk_common::nuts::PublicKey { +impl TryFrom for cdk::nuts::PublicKey { type Error = FfiError; fn try_from(key: PublicKey) -> Result { @@ -2417,8 +2409,8 @@ pub struct Keys { pub keys: HashMap, } -impl From for Keys { - fn from(keys: cdk_common::nuts::Keys) -> Self { +impl From for Keys { + fn from(keys: cdk::nuts::Keys) -> Self { // Keys doesn't have id and unit - we'll need to get these from context // For now, use placeholder values Self { @@ -2433,7 +2425,7 @@ impl From for Keys { } } -impl TryFrom for cdk_common::nuts::Keys { +impl TryFrom for cdk::nuts::Keys { type Error = FfiError; fn try_from(keys: Keys) -> Result { @@ -2443,13 +2435,13 @@ impl TryFrom for cdk_common::nuts::Keys { // Convert the HashMap to BTreeMap with proper types let mut keys_map = BTreeMap::new(); for (amount_u64, pubkey_hex) in keys.keys { - let amount = cashu::Amount::from(amount_u64); - let pubkey = cashu::PublicKey::from_str(&pubkey_hex) + let amount = cdk::Amount::from(amount_u64); + let pubkey = cdk::nuts::PublicKey::from_str(&pubkey_hex) .map_err(|e| FfiError::InvalidCryptographicKey { msg: e.to_string() })?; keys_map.insert(amount, pubkey); } - Ok(cdk_common::nuts::Keys::new(keys_map)) + Ok(cdk::nuts::Keys::new(keys_map)) } } @@ -2485,8 +2477,8 @@ pub struct KeySet { pub final_expiry: Option, } -impl From for KeySet { - fn from(keyset: cashu::KeySet) -> Self { +impl From for KeySet { + fn from(keyset: cdk::nuts::KeySet) -> Self { Self { id: keyset.id.to_string(), unit: keyset.unit.into(), @@ -2501,7 +2493,7 @@ impl From for KeySet { } } -impl TryFrom for cashu::KeySet { +impl TryFrom for cdk::nuts::KeySet { type Error = FfiError; fn try_from(keyset: KeySet) -> Result { @@ -2509,23 +2501,23 @@ impl TryFrom for cashu::KeySet { use std::str::FromStr; // Convert id - let id = cashu::Id::from_str(&keyset.id) + let id = cdk::nuts::Id::from_str(&keyset.id) .map_err(|e| FfiError::Serialization { msg: e.to_string() })?; // Convert unit - let unit: cashu::CurrencyUnit = keyset.unit.into(); + let unit: cdk::nuts::CurrencyUnit = keyset.unit.into(); // Convert keys let mut keys_map = BTreeMap::new(); for (amount_u64, pubkey_hex) in keyset.keys { - let amount = cashu::Amount::from(amount_u64); - let pubkey = cashu::PublicKey::from_str(&pubkey_hex) + let amount = cdk::Amount::from(amount_u64); + let pubkey = cdk::nuts::PublicKey::from_str(&pubkey_hex) .map_err(|e| FfiError::InvalidCryptographicKey { msg: e.to_string() })?; keys_map.insert(amount, pubkey); } - let keys = cashu::Keys::new(keys_map); + let keys = cdk::nuts::Keys::new(keys_map); - Ok(cashu::KeySet { + Ok(cdk::nuts::KeySet { id, unit, keys, @@ -2570,8 +2562,8 @@ pub struct ProofInfo { pub unit: CurrencyUnit, } -impl From for ProofInfo { - fn from(info: cdk_common::common::ProofInfo) -> Self { +impl From for ProofInfo { + fn from(info: cdk::types::ProofInfo) -> Self { Self { proof: std::sync::Arc::new(info.proof.into()), y: info.y.into(), @@ -2586,15 +2578,15 @@ impl From for ProofInfo { /// Decode ProofInfo from JSON string #[uniffi::export] pub fn decode_proof_info(json: String) -> Result { - let info: cdk_common::common::ProofInfo = serde_json::from_str(&json)?; + let info: cdk::types::ProofInfo = serde_json::from_str(&json)?; Ok(info.into()) } /// Encode ProofInfo to JSON string #[uniffi::export] pub fn encode_proof_info(info: ProofInfo) -> Result { - // Convert to cdk_common::common::ProofInfo for serialization - let cdk_info = cdk_common::common::ProofInfo { + // Convert to cdk::types::ProofInfo for serialization + let cdk_info = cdk::types::ProofInfo { proof: info.proof.inner.clone(), y: info.y.try_into()?, mint_url: info.mint_url.try_into()?, @@ -2614,23 +2606,17 @@ pub struct Id { pub hex: String, } -impl From for Id { - fn from(id: cdk_common::nuts::Id) -> Self { +impl From for Id { + fn from(id: cdk::nuts::Id) -> Self { Self { hex: id.to_string(), } } } -impl From for cdk_common::nuts::Id { +impl From for cdk::nuts::Id { fn from(id: Id) -> Self { use std::str::FromStr; - Self::from_str(&id.hex).unwrap_or_else(|_| { - // Create a dummy keyset for empty mint keys - use std::collections::BTreeMap; - let empty_map = BTreeMap::new(); - let empty_keys = cdk_common::nut01::MintKeys::new(empty_map); - cdk_common::nuts::Id::from(&empty_keys) - }) + Self::from_str(&id.hex).unwrap() } } diff --git a/crates/cdk-ffi/src/wallet.rs b/crates/cdk-ffi/src/wallet.rs index c463ab435..4772f64d7 100644 --- a/crates/cdk-ffi/src/wallet.rs +++ b/crates/cdk-ffi/src/wallet.rs @@ -348,7 +348,7 @@ impl Wallet { &self, params: SubscribeParams, ) -> Result, FfiError> { - let cdk_params: cdk_common::subscription::Params = params.clone().into(); + let cdk_params: cdk::nuts::nut17::Params = params.clone().into(); let sub_id = cdk_params.id.to_string(); let active_sub = self.inner.subscribe(cdk_params).await; Ok(std::sync::Arc::new(ActiveSubscription::new( From 6b80b74cb1c73d3889da3d6e01aed626c87732e4 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Tue, 23 Sep 2025 09:27:07 +0100 Subject: [PATCH 174/321] feat: remove features from auth (#1103) --- .github/workflows/ci.yml | 3 --- crates/cdk-ffi/Cargo.toml | 7 +------ crates/cdk-ffi/src/types.rs | 6 ------ crates/cdk-ffi/src/wallet.rs | 3 +-- 4 files changed, 2 insertions(+), 17 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 219a9e309..649af8b84 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -120,9 +120,6 @@ jobs: # FFI bindings -p cdk-ffi, - -p cdk-ffi --no-default-features, - -p cdk-ffi --no-default-features --features auth, - -p cdk-ffi --no-default-features --features bip353, # Binaries --bin cdk-cli, diff --git a/crates/cdk-ffi/Cargo.toml b/crates/cdk-ffi/Cargo.toml index 0840750b1..b8cef967a 100644 --- a/crates/cdk-ffi/Cargo.toml +++ b/crates/cdk-ffi/Cargo.toml @@ -10,15 +10,10 @@ rust-version.workspace = true crate-type = ["cdylib", "staticlib", "rlib"] name = "cdk_ffi" -[features] -default = ["auth", "bip353"] -auth = ["cdk/auth"] -bip353 = ["cdk/bip353"] - [dependencies] async-trait = { workspace = true } bip39 = { workspace = true } -cdk = { workspace = true, default-features = false, features = ["wallet"] } +cdk = { workspace = true, default-features = false, features = ["wallet", "auth", "bip353"] } cdk-sqlite = { workspace = true } ctor = "0.2" futures = { workspace = true } diff --git a/crates/cdk-ffi/src/types.rs b/crates/cdk-ffi/src/types.rs index e5da421c4..60194aa6e 100644 --- a/crates/cdk-ffi/src/types.rs +++ b/crates/cdk-ffi/src/types.rs @@ -1998,7 +1998,6 @@ impl TryFrom for cdk::wallet::types::TransactionId { } /// FFI-compatible AuthProof -#[cfg(feature = "auth")] #[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] pub struct AuthProof { /// Keyset ID @@ -2011,7 +2010,6 @@ pub struct AuthProof { pub y: String, } -#[cfg(feature = "auth")] impl From for AuthProof { fn from(auth_proof: cdk::nuts::AuthProof) -> Self { Self { @@ -2026,7 +2024,6 @@ impl From for AuthProof { } } -#[cfg(feature = "auth")] impl TryFrom for cdk::nuts::AuthProof { type Error = FfiError; @@ -2047,7 +2044,6 @@ impl TryFrom for cdk::nuts::AuthProof { } } -#[cfg(feature = "auth")] impl AuthProof { /// Convert AuthProof to JSON string pub fn to_json(&self) -> Result { @@ -2056,14 +2052,12 @@ impl AuthProof { } /// Decode AuthProof from JSON string -#[cfg(feature = "auth")] #[uniffi::export] pub fn decode_auth_proof(json: String) -> Result { Ok(serde_json::from_str(&json)?) } /// Encode AuthProof to JSON string -#[cfg(feature = "auth")] #[uniffi::export] pub fn encode_auth_proof(proof: AuthProof) -> Result { Ok(serde_json::to_string(&proof)?) diff --git a/crates/cdk-ffi/src/wallet.rs b/crates/cdk-ffi/src/wallet.rs index 4772f64d7..04d2035f8 100644 --- a/crates/cdk-ffi/src/wallet.rs +++ b/crates/cdk-ffi/src/wallet.rs @@ -404,7 +404,7 @@ impl Wallet { } /// BIP353 methods for Wallet -#[cfg(all(feature = "bip353", not(target_arch = "wasm32")))] +#[cfg(not(target_arch = "wasm32"))] #[uniffi::export(async_runtime = "tokio")] impl Wallet { /// Get a quote for a BIP353 melt @@ -426,7 +426,6 @@ impl Wallet { } /// Auth methods for Wallet -#[cfg(feature = "auth")] #[uniffi::export(async_runtime = "tokio")] impl Wallet { /// Set Clear Auth Token (CAT) for authentication From fdd99e1afc6e8fc4e34f9bdf377f686479af100f Mon Sep 17 00:00:00 2001 From: juejinyuxitu Date: Tue, 23 Sep 2025 17:54:09 +0800 Subject: [PATCH 175/321] chore: fix typo in comment (#1107) Signed-off-by: juejinyuxitu --- crates/cashu/src/nuts/nut10.rs | 2 +- crates/cdk/src/mint/melt.rs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/cashu/src/nuts/nut10.rs b/crates/cashu/src/nuts/nut10.rs index e6de748e3..783c31d5c 100644 --- a/crates/cashu/src/nuts/nut10.rs +++ b/crates/cashu/src/nuts/nut10.rs @@ -30,7 +30,7 @@ pub enum Kind { HTLC, } -/// Secert Date +/// Secret Date #[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)] pub struct SecretData { /// Unique random string diff --git a/crates/cdk/src/mint/melt.rs b/crates/cdk/src/mint/melt.rs index 580fe62f1..6ceb9bb30 100644 --- a/crates/cdk/src/mint/melt.rs +++ b/crates/cdk/src/mint/melt.rs @@ -856,7 +856,7 @@ impl Mint { } /// Process melt request marking proofs as spent - /// The melt request must be verifyed using [`Self::verify_melt_request`] + /// The melt request must be verified using [`Self::verify_melt_request`] /// before calling [`Self::process_melt_request`] #[instrument(skip_all)] pub async fn process_melt_request( From 1e6102f4949cc3460bb51490c713bc257e18fe40 Mon Sep 17 00:00:00 2001 From: asmo Date: Tue, 23 Sep 2025 12:44:11 +0200 Subject: [PATCH 176/321] add FFI types for NUT-04 and NUT-05 (#1101) * feat: add FFI types and conversion logic for NUT-04 and NUT-05 settings in `cdk-ffi` * feat: remove auth feature and deafult to having auth --------- Co-authored-by: thesimplekid --- crates/cdk-common/src/error.rs | 2 + crates/cdk-ffi/src/types.rs | 382 +++++++++++++++++++++++++++++++-- 2 files changed, 372 insertions(+), 12 deletions(-) diff --git a/crates/cdk-common/src/error.rs b/crates/cdk-common/src/error.rs index 9f7efdaec..dd29a1594 100644 --- a/crates/cdk-common/src/error.rs +++ b/crates/cdk-common/src/error.rs @@ -388,9 +388,11 @@ pub enum Error { NUT20(#[from] crate::nuts::nut20::Error), /// NUT21 Error #[error(transparent)] + #[cfg(feature = "auth")] NUT21(#[from] crate::nuts::nut21::Error), /// NUT22 Error #[error(transparent)] + #[cfg(feature = "auth")] NUT22(#[from] crate::nuts::nut22::Error), /// NUT23 Error #[error(transparent)] diff --git a/crates/cdk-ffi/src/types.rs b/crates/cdk-ffi/src/types.rs index 60194aa6e..9d4b04488 100644 --- a/crates/cdk-ffi/src/types.rs +++ b/crates/cdk-ffi/src/types.rs @@ -1467,9 +1467,314 @@ impl From for cdk::nuts::nut06::SupportedSettings { } } -/// FFI-compatible Nuts settings (simplified - only includes basic boolean flags) +// ----------------------------- +// NUT-04/05 FFI Types +// ----------------------------- + +/// FFI-compatible MintMethodSettings (NUT-04) +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct MintMethodSettings { + pub method: PaymentMethod, + pub unit: CurrencyUnit, + pub min_amount: Option, + pub max_amount: Option, + /// For bolt11, whether mint supports setting invoice description + pub description: Option, +} + +impl From for MintMethodSettings { + fn from(s: cdk::nuts::nut04::MintMethodSettings) -> Self { + let description = match s.options { + Some(cdk::nuts::nut04::MintMethodOptions::Bolt11 { description }) => Some(description), + _ => None, + }; + Self { + method: s.method.into(), + unit: s.unit.into(), + min_amount: s.min_amount.map(Into::into), + max_amount: s.max_amount.map(Into::into), + description, + } + } +} + +impl TryFrom for cdk::nuts::nut04::MintMethodSettings { + type Error = FfiError; + + fn try_from(s: MintMethodSettings) -> Result { + let options = match (s.method.clone(), s.description) { + (PaymentMethod::Bolt11, Some(description)) => { + Some(cdk::nuts::nut04::MintMethodOptions::Bolt11 { description }) + } + _ => None, + }; + Ok(Self { + method: s.method.into(), + unit: s.unit.into(), + min_amount: s.min_amount.map(Into::into), + max_amount: s.max_amount.map(Into::into), + options, + }) + } +} + +/// FFI-compatible Nut04 Settings +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct Nut04Settings { + pub methods: Vec, + pub disabled: bool, +} + +impl From for Nut04Settings { + fn from(s: cdk::nuts::nut04::Settings) -> Self { + Self { + methods: s.methods.into_iter().map(Into::into).collect(), + disabled: s.disabled, + } + } +} + +impl TryFrom for cdk::nuts::nut04::Settings { + type Error = FfiError; + + fn try_from(s: Nut04Settings) -> Result { + Ok(Self { + methods: s + .methods + .into_iter() + .map(TryInto::try_into) + .collect::>()?, + disabled: s.disabled, + }) + } +} + +/// FFI-compatible MeltMethodSettings (NUT-05) +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct MeltMethodSettings { + pub method: PaymentMethod, + pub unit: CurrencyUnit, + pub min_amount: Option, + pub max_amount: Option, + /// For bolt11, whether mint supports amountless invoices + pub amountless: Option, +} + +impl From for MeltMethodSettings { + fn from(s: cdk::nuts::nut05::MeltMethodSettings) -> Self { + let amountless = match s.options { + Some(cdk::nuts::nut05::MeltMethodOptions::Bolt11 { amountless }) => Some(amountless), + _ => None, + }; + Self { + method: s.method.into(), + unit: s.unit.into(), + min_amount: s.min_amount.map(Into::into), + max_amount: s.max_amount.map(Into::into), + amountless, + } + } +} + +impl TryFrom for cdk::nuts::nut05::MeltMethodSettings { + type Error = FfiError; + + fn try_from(s: MeltMethodSettings) -> Result { + let options = match (s.method.clone(), s.amountless) { + (PaymentMethod::Bolt11, Some(amountless)) => { + Some(cdk::nuts::nut05::MeltMethodOptions::Bolt11 { amountless }) + } + _ => None, + }; + Ok(Self { + method: s.method.into(), + unit: s.unit.into(), + min_amount: s.min_amount.map(Into::into), + max_amount: s.max_amount.map(Into::into), + options, + }) + } +} + +/// FFI-compatible Nut05 Settings +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct Nut05Settings { + pub methods: Vec, + pub disabled: bool, +} + +impl From for Nut05Settings { + fn from(s: cdk::nuts::nut05::Settings) -> Self { + Self { + methods: s.methods.into_iter().map(Into::into).collect(), + disabled: s.disabled, + } + } +} + +impl TryFrom for cdk::nuts::nut05::Settings { + type Error = FfiError; + + fn try_from(s: Nut05Settings) -> Result { + Ok(Self { + methods: s + .methods + .into_iter() + .map(TryInto::try_into) + .collect::>()?, + disabled: s.disabled, + }) + } +} + +/// FFI-compatible ProtectedEndpoint (for auth nuts) +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct ProtectedEndpoint { + /// HTTP method (GET, POST, etc.) + pub method: String, + /// Endpoint path + pub path: String, +} + +/// FFI-compatible ClearAuthSettings (NUT-21) +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct ClearAuthSettings { + /// OpenID Connect discovery URL + pub openid_discovery: String, + /// OAuth 2.0 client ID + pub client_id: String, + /// Protected endpoints requiring clear authentication + pub protected_endpoints: Vec, +} + +/// FFI-compatible BlindAuthSettings (NUT-22) +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct BlindAuthSettings { + /// Maximum number of blind auth tokens that can be minted per request + pub bat_max_mint: u64, + /// Protected endpoints requiring blind authentication + pub protected_endpoints: Vec, +} + +impl From for ClearAuthSettings { + fn from(settings: cdk::nuts::ClearAuthSettings) -> Self { + Self { + openid_discovery: settings.openid_discovery, + client_id: settings.client_id, + protected_endpoints: settings + .protected_endpoints + .into_iter() + .map(Into::into) + .collect(), + } + } +} + +impl TryFrom for cdk::nuts::ClearAuthSettings { + type Error = FfiError; + + fn try_from(settings: ClearAuthSettings) -> Result { + Ok(Self { + openid_discovery: settings.openid_discovery, + client_id: settings.client_id, + protected_endpoints: settings + .protected_endpoints + .into_iter() + .map(|e| e.try_into()) + .collect::, _>>()?, + }) + } +} + +impl From for BlindAuthSettings { + fn from(settings: cdk::nuts::BlindAuthSettings) -> Self { + Self { + bat_max_mint: settings.bat_max_mint, + protected_endpoints: settings + .protected_endpoints + .into_iter() + .map(Into::into) + .collect(), + } + } +} + +impl TryFrom for cdk::nuts::BlindAuthSettings { + type Error = FfiError; + + fn try_from(settings: BlindAuthSettings) -> Result { + Ok(Self { + bat_max_mint: settings.bat_max_mint, + protected_endpoints: settings + .protected_endpoints + .into_iter() + .map(|e| e.try_into()) + .collect::, _>>()?, + }) + } +} + +impl From for ProtectedEndpoint { + fn from(endpoint: cdk::nuts::ProtectedEndpoint) -> Self { + Self { + method: match endpoint.method { + cdk::nuts::Method::Get => "GET".to_string(), + cdk::nuts::Method::Post => "POST".to_string(), + }, + path: endpoint.path.to_string(), + } + } +} + +impl TryFrom for cdk::nuts::ProtectedEndpoint { + type Error = FfiError; + + fn try_from(endpoint: ProtectedEndpoint) -> Result { + let method = match endpoint.method.as_str() { + "GET" => cdk::nuts::Method::Get, + "POST" => cdk::nuts::Method::Post, + _ => { + return Err(FfiError::Generic { + msg: format!( + "Invalid HTTP method: {}. Only GET and POST are supported", + endpoint.method + ), + }) + } + }; + + // Convert path string to RoutePath by matching against known paths + let route_path = match endpoint.path.as_str() { + "/v1/mint/quote/bolt11" => cdk::nuts::RoutePath::MintQuoteBolt11, + "/v1/mint/bolt11" => cdk::nuts::RoutePath::MintBolt11, + "/v1/melt/quote/bolt11" => cdk::nuts::RoutePath::MeltQuoteBolt11, + "/v1/melt/bolt11" => cdk::nuts::RoutePath::MeltBolt11, + "/v1/swap" => cdk::nuts::RoutePath::Swap, + "/v1/checkstate" => cdk::nuts::RoutePath::Checkstate, + "/v1/restore" => cdk::nuts::RoutePath::Restore, + "/v1/auth/blind/mint" => cdk::nuts::RoutePath::MintBlindAuth, + "/v1/mint/quote/bolt12" => cdk::nuts::RoutePath::MintQuoteBolt12, + "/v1/mint/bolt12" => cdk::nuts::RoutePath::MintBolt12, + "/v1/melt/quote/bolt12" => cdk::nuts::RoutePath::MeltQuoteBolt12, + "/v1/melt/bolt12" => cdk::nuts::RoutePath::MeltBolt12, + _ => { + return Err(FfiError::Generic { + msg: format!("Unknown route path: {}", endpoint.path), + }) + } + }; + + Ok(cdk::nuts::ProtectedEndpoint::new(method, route_path)) + } +} + +/// FFI-compatible Nuts settings (extended to include NUT-04 and NUT-05 settings) #[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] pub struct Nuts { + /// NUT04 Settings + pub nut04: Nut04Settings, + /// NUT05 Settings + pub nut05: Nut05Settings, /// NUT07 Settings - Token state check pub nut07_supported: bool, /// NUT08 Settings - Lightning fee return @@ -1486,6 +1791,10 @@ pub struct Nuts { pub nut14_supported: bool, /// NUT20 Settings - Web sockets pub nut20_supported: bool, + /// NUT21 Settings - Clear authentication + pub nut21: Option, + /// NUT22 Settings - Blind authentication + pub nut22: Option, /// Supported currency units for minting pub mint_units: Vec, /// Supported currency units for melting @@ -1494,7 +1803,20 @@ pub struct Nuts { impl From for Nuts { fn from(nuts: cdk::nuts::Nuts) -> Self { + let mint_units = nuts + .supported_mint_units() + .into_iter() + .map(|u| u.clone().into()) + .collect(); + let melt_units = nuts + .supported_melt_units() + .into_iter() + .map(|u| u.clone().into()) + .collect(); + Self { + nut04: nuts.nut04.clone().into(), + nut05: nuts.nut05.clone().into(), nut07_supported: nuts.nut07.supported, nut08_supported: nuts.nut08.supported, nut09_supported: nuts.nut09.supported, @@ -1503,20 +1825,54 @@ impl From for Nuts { nut12_supported: nuts.nut12.supported, nut14_supported: nuts.nut14.supported, nut20_supported: nuts.nut20.supported, - mint_units: nuts - .supported_mint_units() - .into_iter() - .map(|u| u.clone().into()) - .collect(), - melt_units: nuts - .supported_melt_units() - .into_iter() - .map(|u| u.clone().into()) - .collect(), + nut21: nuts.nut21.map(Into::into), + nut22: nuts.nut22.map(Into::into), + mint_units, + melt_units, } } } +impl TryFrom for cdk::nuts::Nuts { + type Error = FfiError; + + fn try_from(n: Nuts) -> Result { + Ok(Self { + nut04: n.nut04.try_into()?, + nut05: n.nut05.try_into()?, + nut07: cdk::nuts::nut06::SupportedSettings { + supported: n.nut07_supported, + }, + nut08: cdk::nuts::nut06::SupportedSettings { + supported: n.nut08_supported, + }, + nut09: cdk::nuts::nut06::SupportedSettings { + supported: n.nut09_supported, + }, + nut10: cdk::nuts::nut06::SupportedSettings { + supported: n.nut10_supported, + }, + nut11: cdk::nuts::nut06::SupportedSettings { + supported: n.nut11_supported, + }, + nut12: cdk::nuts::nut06::SupportedSettings { + supported: n.nut12_supported, + }, + nut14: cdk::nuts::nut06::SupportedSettings { + supported: n.nut14_supported, + }, + nut15: Default::default(), + nut17: Default::default(), + nut19: Default::default(), + nut20: cdk::nuts::nut06::SupportedSettings { + supported: n.nut20_supported, + }, + nut21: n.nut21.map(|s| s.try_into()).transpose()?, + nut22: n.nut22.map(|s| s.try_into()).transpose()?, + }) + } +} + impl Nuts { /// Convert Nuts to JSON string pub fn to_json(&self) -> Result { @@ -1588,6 +1944,8 @@ impl From for MintInfo { impl From for cdk::nuts::MintInfo { fn from(info: MintInfo) -> Self { + // Convert FFI Nuts back to cdk::nuts::Nuts (best-effort) + let nuts_cdk: cdk::nuts::Nuts = info.nuts.clone().try_into().unwrap_or_default(); Self { name: info.name, pubkey: info.pubkey.and_then(|p| p.parse().ok()), @@ -1597,7 +1955,7 @@ impl From for cdk::nuts::MintInfo { contact: info .contact .map(|contacts| contacts.into_iter().map(Into::into).collect()), - nuts: cdk::nuts::Nuts::default(), // Simplified conversion + nuts: nuts_cdk, icon_url: info.icon_url, urls: info.urls, motd: info.motd, From 35a4be1429c46c54dbe1a495f5b8375cd90b6140 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Tue, 23 Sep 2025 14:23:06 +0100 Subject: [PATCH 177/321] feat(docker): add LDK Node mint service with dedicated Docker setup (#1108) * 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 --- .../workflows/docker-publish-ldk-node-arm.yml | 62 +++++++++ .github/workflows/docker-publish-ldk-node.yml | 62 +++++++++ Dockerfile | 2 +- Dockerfile.arm | 2 +- Dockerfile.ldk-node | 40 ++++++ Dockerfile.ldk-node.arm | 43 +++++++ crates/cdk-mintd/README.md | 47 +++++++ docker-compose.ldk-node.yaml | 118 ++++++++++++++++++ docker-compose.yaml | 39 ++++++ 9 files changed, 413 insertions(+), 2 deletions(-) create mode 100644 .github/workflows/docker-publish-ldk-node-arm.yml create mode 100644 .github/workflows/docker-publish-ldk-node.yml create mode 100644 Dockerfile.ldk-node create mode 100644 Dockerfile.ldk-node.arm create mode 100644 docker-compose.ldk-node.yaml diff --git a/.github/workflows/docker-publish-ldk-node-arm.yml b/.github/workflows/docker-publish-ldk-node-arm.yml new file mode 100644 index 000000000..9b3881087 --- /dev/null +++ b/.github/workflows/docker-publish-ldk-node-arm.yml @@ -0,0 +1,62 @@ +name: Publish Docker Image LDK Node ARM64 + +on: + release: + types: [published] + workflow_dispatch: + inputs: + tag: + description: 'Tag to build and publish' + required: true + default: 'latest' + +env: + REGISTRY: docker.io + IMAGE_NAME: cashubtc/mintd + +jobs: + build-and-push: + runs-on: ubuntu-latest + permissions: + contents: read + packages: write + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Login to Docker Hub + uses: docker/login-action@v3 + with: + username: ${{ secrets.DOCKERHUB_USERNAME }} + password: ${{ secrets.DOCKERHUB_TOKEN }} + + - name: Extract metadata (tags, labels) for Docker + id: meta + uses: docker/metadata-action@v5 + with: + images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} + tags: | + type=raw,value=ldk-node-arm64,enable=${{ github.event_name == 'release' }} + type=semver,pattern={{version}}-ldk-node-arm64 + type=semver,pattern={{major}}.{{minor}}-ldk-node-arm64 + type=ref,event=branch,suffix=-ldk-node-arm64 + type=ref,event=pr,suffix=-ldk-node-arm64 + type=sha,suffix=-ldk-node-arm64 + ${{ github.event.inputs.tag != '' && format('{0}-ldk-node-arm64', github.event.inputs.tag) || '' }} + + # Build and push ARM64 image with architecture suffix + - name: Build and push Docker image + uses: docker/build-push-action@v5 + with: + context: . + push: true + platforms: linux/arm64 + file: ./Dockerfile.ldk-node.arm + tags: ${{ steps.meta.outputs.tags }}-arm64 + labels: ${{ steps.meta.outputs.labels }} + cache-from: type=gha + cache-to: type=gha,mode=max diff --git a/.github/workflows/docker-publish-ldk-node.yml b/.github/workflows/docker-publish-ldk-node.yml new file mode 100644 index 000000000..7ef2b505c --- /dev/null +++ b/.github/workflows/docker-publish-ldk-node.yml @@ -0,0 +1,62 @@ +name: Publish Docker Image LDK Node AMD64 + +on: + release: + types: [published] + workflow_dispatch: + inputs: + tag: + description: 'Tag to build and publish' + required: true + default: 'latest' + +env: + REGISTRY: docker.io + IMAGE_NAME: cashubtc/mintd + +jobs: + build-and-push: + runs-on: ubuntu-latest + permissions: + contents: read + packages: write + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Login to Docker Hub + uses: docker/login-action@v3 + with: + username: ${{ secrets.DOCKERHUB_USERNAME }} + password: ${{ secrets.DOCKERHUB_TOKEN }} + + - name: Extract metadata (tags, labels) for Docker + id: meta + uses: docker/metadata-action@v5 + with: + images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} + tags: | + type=raw,value=ldk-node,enable=${{ github.event_name == 'release' }} + type=semver,pattern={{version}}-ldk-node + type=semver,pattern={{major}}.{{minor}}-ldk-node + type=ref,event=branch,suffix=-ldk-node + type=ref,event=pr,suffix=-ldk-node + type=sha,suffix=-ldk-node + ${{ github.event.inputs.tag != '' && format('{0}-ldk-node', github.event.inputs.tag) || '' }} + + # Build and push AMD64 image with architecture suffix + - name: Build and push Docker image + uses: docker/build-push-action@v5 + with: + context: . + file: ./Dockerfile.ldk-node + push: true + platforms: linux/amd64 + tags: ${{ steps.meta.outputs.tags }}-amd64 + labels: ${{ steps.meta.outputs.labels }} + cache-from: type=gha + cache-to: type=gha,mode=max diff --git a/Dockerfile b/Dockerfile index b43591692..ed06de19f 100644 --- a/Dockerfile +++ b/Dockerfile @@ -10,7 +10,7 @@ COPY Cargo.toml ./Cargo.toml COPY crates ./crates # Start the Nix daemon and develop the environment -RUN nix develop --extra-experimental-features nix-command --extra-experimental-features flakes --command cargo build --release --bin cdk-mintd --features redis --features prometheus +RUN nix develop --extra-experimental-features nix-command --extra-experimental-features flakes --command cargo build --release --bin cdk-mintd --features postgres --features prometheus # Create a runtime stage FROM debian:trixie-slim diff --git a/Dockerfile.arm b/Dockerfile.arm index 901007623..f256cf73b 100644 --- a/Dockerfile.arm +++ b/Dockerfile.arm @@ -13,7 +13,7 @@ COPY crates ./crates RUN echo 'filter-syscalls = false' > /etc/nix/nix.conf # Start the Nix daemon and develop the environment -RUN nix develop --extra-platforms aarch64-linux --extra-experimental-features nix-command --extra-experimental-features flakes --command cargo build --release --bin cdk-mintd --features redis +RUN nix develop --extra-platforms aarch64-linux --extra-experimental-features nix-command --extra-experimental-features flakes --command cargo build --release --bin cdk-mintd --features postgres # Create a runtime stage FROM debian:trixie-slim diff --git a/Dockerfile.ldk-node b/Dockerfile.ldk-node new file mode 100644 index 000000000..dd825018e --- /dev/null +++ b/Dockerfile.ldk-node @@ -0,0 +1,40 @@ +# Use the official NixOS image as the base image +FROM nixos/nix:latest AS builder + +# Set the working directory +WORKDIR /usr/src/app + +# Copy workspace files and crates directory into the container +COPY flake.nix ./flake.nix +COPY Cargo.toml ./Cargo.toml +COPY crates ./crates + +# Start the Nix daemon and develop the environment +RUN nix develop --extra-experimental-features nix-command --extra-experimental-features flakes --command cargo build --release --bin cdk-mintd --features ldk-node --features prometheus --features postgres + +# Create a runtime stage +FROM debian:trixie-slim + +# Set the working directory +WORKDIR /usr/src/app + +# Install needed runtime dependencies (if any) +RUN apt-get update && \ + apt-get install -y --no-install-recommends patchelf && \ + rm -rf /var/lib/apt/lists/* + +# Copy the built application from the build stage +COPY --from=builder /usr/src/app/target/release/cdk-mintd /usr/local/bin/cdk-mintd + +# Detect the architecture and set the interpreter accordingly +RUN ARCH=$(uname -m) && \ + if [ "$ARCH" = "aarch64" ]; then \ + patchelf --set-interpreter /lib/ld-linux-aarch64.so.1 /usr/local/bin/cdk-mintd; \ + elif [ "$ARCH" = "x86_64" ]; then \ + patchelf --set-interpreter /lib64/ld-linux-x86-64.so.2 /usr/local/bin/cdk-mintd; \ + else \ + echo "Unsupported architecture: $ARCH"; exit 1; \ + fi + +# Set the entry point for the container +CMD ["cdk-mintd"] diff --git a/Dockerfile.ldk-node.arm b/Dockerfile.ldk-node.arm new file mode 100644 index 000000000..2cb42be7a --- /dev/null +++ b/Dockerfile.ldk-node.arm @@ -0,0 +1,43 @@ +# Use the official NixOS image as the base image +FROM nixos/nix:latest AS builder + +# Set the working directory +WORKDIR /usr/src/app + +# Copy workspace files and crates directory into the container +COPY flake.nix ./flake.nix +COPY Cargo.toml ./Cargo.toml +COPY crates ./crates + +# Create a nix config file to disable syscall filtering +RUN echo 'filter-syscalls = false' > /etc/nix/nix.conf + +# Start the Nix daemon and develop the environment +RUN nix develop --extra-platforms aarch64-linux --extra-experimental-features nix-command --extra-experimental-features flakes --command cargo build --release --bin cdk-mintd --features ldk-node --features prometheus --features postgres + +# Create a runtime stage +FROM debian:trixie-slim + +# Set the working directory +WORKDIR /usr/src/app + +# Install needed runtime dependencies (if any) +RUN apt-get update && \ + apt-get install -y --no-install-recommends patchelf && \ + rm -rf /var/lib/apt/lists/* + +# Copy the built application from the build stage +COPY --from=builder /usr/src/app/target/release/cdk-mintd /usr/local/bin/cdk-mintd + +# Detect the architecture and set the interpreter accordingly +RUN ARCH=$(uname -m) && \ + if [ "$ARCH" = "aarch64" ]; then \ + patchelf --set-interpreter /lib/ld-linux-aarch64.so.1 /usr/local/bin/cdk-mintd; \ + elif [ "$ARCH" = "x86_64" ]; then \ + patchelf --set-interpreter /lib64/ld-linux-x86-64.so.2 /usr/local/bin/cdk-mintd; \ + else \ + echo "Unsupported architecture: $ARCH"; exit 1; \ + fi + +# Set the entry point for the container +CMD ["cdk-mintd"] diff --git a/crates/cdk-mintd/README.md b/crates/cdk-mintd/README.md index e72149f19..fcb189c79 100644 --- a/crates/cdk-mintd/README.md +++ b/crates/cdk-mintd/README.md @@ -151,6 +151,53 @@ After setup and first run, your directory will look like: - Log directories and files - Lightning backend data directories +## Docker Usage + +CDK Mintd provides ready-to-use Docker images with multiple Lightning backend options. + +### Quick Start + +#### Standard mint with fakewallet backend (testing only): +```bash +docker-compose up +``` + +#### Mint with LDK Node backend: +```bash +# Option 1: Use dedicated ldk-node compose file +docker-compose -f docker-compose.ldk-node.yaml up + +# Option 2: Use main compose file with profile +docker-compose --profile ldk-node up +``` + +### Available Images + +- **`cashubtc/mintd:latest`** - Standard mint with default features +- **`cashubtc/mintd-ldk-node:latest`** - Mint with LDK Node support + +### Configuration via Environment Variables + +All configuration can be done through environment variables: + +```yaml +environment: + - CDK_MINTD_LN_BACKEND=ldk-node + - CDK_MINTD_DATABASE=sqlite + - CDK_MINTD_LISTEN_HOST=0.0.0.0 + - CDK_MINTD_LISTEN_PORT=8085 + - CDK_MINTD_LDK_NODE_NETWORK=testnet + - CDK_MINTD_LDK_NODE_ESPLORA_URL=https://blockstream.info/testnet/api +``` + +### Monitoring + +Both Prometheus metrics and Grafana dashboards are included: +- Prometheus: http://localhost:9090 +- Grafana: http://localhost:3011 (admin/admin) + +For detailed Docker documentation, see [README-ldk-node.md](../../README-ldk-node.md). + ## Testing Your Mint 1. **Verify the mint is running**: diff --git a/docker-compose.ldk-node.yaml b/docker-compose.ldk-node.yaml new file mode 100644 index 000000000..c46430a47 --- /dev/null +++ b/docker-compose.ldk-node.yaml @@ -0,0 +1,118 @@ +version: '3.8' + +services: + # CDK Mint service with LDK Node backend + + prometheus: + image: prom/prometheus:latest + ports: + - "9090:9090" + volumes: + - ./misc/provisioning/prometheus.yml:/etc/prometheus/prometheus.yml:ro + command: + - '--config.file=/etc/prometheus/prometheus.yml' + - '--storage.tsdb.path=/prometheus' + - '--web.console.libraries=/etc/prometheus/console_libraries' + - '--web.console.templates=/etc/prometheus/consoles' + - '--web.enable-lifecycle' + - '--enable-feature=otlp-write-receiver' + extra_hosts: + - "host.docker.internal:host-gateway" + networks: + - cdk + + # Grafana for visualization + grafana: + image: grafana/grafana:latest + ports: + - "3011:3000" + volumes: + - ./misc/provisioning/datasources:/etc/grafana/provisioning/datasources + - ./misc/provisioning/dashboards:/etc/grafana/provisioning/dashboards + environment: + - GF_DASHBOARDS_JSON_ENABLED=true + - GF_SECURITY_ADMIN_PASSWORD=admin + - GF_PROVISIONING_PATHS=/etc/grafana/provisioning + networks: + - cdk + + mintd-ldk-node: + # Use the ldk-node tagged image from the same repository + image: cashubtc/mintd:ldk-node-amd64 + # Alternatively, build locally: + # build: + # context: . + # dockerfile: Dockerfile.ldk-node + container_name: mint-ldk-node + ports: + - "8085:8085" + environment: + - CDK_MINTD_URL=https://example.com + - CDK_MINTD_LN_BACKEND=ldk-node + - CDK_MINTD_LISTEN_HOST=0.0.0.0 + - CDK_MINTD_LISTEN_PORT=8085 + - CDK_MINTD_MNEMONIC= + # Database configuration - choose one: + # Option 1: SQLite (embedded, no additional setup needed) + - CDK_MINTD_DATABASE=sqlite + # Option 2: ReDB (embedded, no additional setup needed) + # - CDK_MINTD_DATABASE=redb + # Option 3: PostgreSQL (requires postgres service, enable with: docker-compose --profile postgres up) + # - CDK_MINTD_DATABASE=postgres + # - CDK_MINTD_DATABASE_URL=postgresql://cdk_user:cdk_password@postgres:5432/cdk_mint + # Cache configuration + - CDK_MINTD_CACHE_BACKEND=memory + - CDK_MINTD_PROMETHEUS_ENABLED=true + - CDK_MINTD_PROMETHEUS_ADDRESS=0.0.0.0 + - CDK_MINTD_PROMETHEUS_PORT=9000 + # LDK Node specific configuration + - CDK_MINTD_LDK_NODE_NETWORK=testnet + - CDK_MINTD_LDK_NODE_ESPLORA_URL=https://blockstream.info/testnet/api + - CDK_MINTD_LDK_NODE_LISTENING_ADDRESSES=0.0.0.0:9735 + volumes: + # Persist LDK node data + - ldk_node_data:/usr/src/app/ldk_node_data + command: ["cdk-mintd"] + depends_on: + - prometheus + - grafana + networks: + - cdk + # Uncomment when using PostgreSQL: + # depends_on: + # - postgres + + # PostgreSQL database service + # Enable with: docker-compose --profile postgres up + postgres: + image: postgres:16-alpine + container_name: mint_postgres + restart: unless-stopped + profiles: + - postgres + environment: + - POSTGRES_USER=cdk_user + - POSTGRES_PASSWORD=cdk_password + - POSTGRES_DB=cdk_mint + - POSTGRES_INITDB_ARGS=--encoding=UTF-8 --lc-collate=C --lc-ctype=C + ports: + - "5432:5432" + volumes: + - postgres_data:/var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready -U cdk_user -d cdk_mint"] + interval: 10s + timeout: 5s + retries: 5 + networks: + - cdk + +volumes: + postgres_data: + driver: local + ldk_node_data: + driver: local + +networks: + cdk: + driver: bridge diff --git a/docker-compose.yaml b/docker-compose.yaml index f405d984b..9a9768948 100644 --- a/docker-compose.yaml +++ b/docker-compose.yaml @@ -71,6 +71,43 @@ services: # depends_on: # - postgres + # LDK Node mint service - enable with: docker-compose --profile ldk-node up + mintd-ldk-node: + build: + context: . + dockerfile: Dockerfile.ldk-node + container_name: mint-ldk-node + profiles: + - ldk-node + ports: + - "8086:8085" # Different port to avoid conflict with main mint + environment: + - CDK_MINTD_URL=https://example.com + - CDK_MINTD_LN_BACKEND=ldk-node + - CDK_MINTD_LISTEN_HOST=0.0.0.0 + - CDK_MINTD_LISTEN_PORT=8085 + - CDK_MINTD_MNEMONIC= + # Database configuration + - CDK_MINTD_DATABASE=sqlite + # Cache configuration + - CDK_MINTD_CACHE_BACKEND=memory + - CDK_MINTD_PROMETHEUS_ENABLED=true + - CDK_MINTD_PROMETHEUS_ADDRESS=0.0.0.0 + - CDK_MINTD_PROMETHEUS_PORT=9000 + # LDK Node specific configuration + - CDK_MINTD_LDK_NODE_NETWORK=testnet + - CDK_MINTD_LDK_NODE_ESPLORA_URL=https://blockstream.info/testnet/api + - CDK_MINTD_LDK_NODE_LISTENING_ADDRESSES=0.0.0.0:9735 + volumes: + # Persist LDK node data + - ldk_node_data:/usr/src/app/ldk_node_data + command: ["cdk-mintd"] + depends_on: + - prometheus + - grafana + networks: + - cdk + # PostgreSQL database service # Enable with: docker-compose --profile postgres up # postgres: @@ -99,6 +136,8 @@ services: volumes: postgres_data: driver: local + ldk_node_data: + driver: local networks: cdk: From fb84343993e39069194190fa8abd6b7e32f993ca Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Tue, 23 Sep 2025 14:46:38 +0100 Subject: [PATCH 178/321] Bump v0.13 (#1106) --- CHANGELOG.md | 41 ++++++++++++++++++++++++++++++++++++++++- Cargo.toml | 40 ++++++++++++++++++++-------------------- 2 files changed, 60 insertions(+), 21 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 250c20995..0c4822cce 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,10 @@ ## [Unreleased] +### Summary + +Version 0.13.0 marks a major milestone for mobile development with the introduction of comprehensive native mobile bindings that enable building Cashu wallets for iOS and Android using Swift and Kotlin. The release introduces cdk-ffi, a new Foreign Function Interface crate that provides UniFFI-based bindings for Swift, Kotlin, and Python, with full wallet functionality including multi-mint support, BOLT12 payments, BIP-353 address resolution, and advanced features like P2PK conditions and authentication. Mobile bindings are distributed through dedicated repositories at https://github.com/cashubtc/cdk-kotlin and https://github.com/cashubtc/cdk-swift that provide native package management for Android/JVM and iOS/macOS platforms respectively. The release also delivers significant infrastructure improvements including an event-driven payment architecture with real-time notifications, enhanced database layer with generic key-value storage, improved HTTP transport with proxy support and BIP-353 DNS resolution, and new operational features like Prometheus metrics collection and dedicated authentication database support. + ### Added - cdk-common: New `Event` enum for payment event handling with `PaymentReceived` variant ([thesimplekid]). - cdk-common: Added `payment_method` field to `MeltQuote` struct for tracking payment method type ([thesimplekid]). @@ -18,6 +22,17 @@ - cdk-sql-common: Implementation of `MintKVStoreDatabase` trait for SQL-based databases with namespace support ([thesimplekid]). - cdk-common: Added `quote_id` field to `Transaction` struct for tracking associated mint or melt quote IDs ([thesimplekid]). - cdk-sql-common: Database migration to add `quote_id` column to transactions table for SQLite and PostgreSQL ([thesimplekid]). +- cdk: Added `amount_mintable()` helper and stricter mint quote validation ([thesimplekid]). +- cdk-sql-common: Added persistent `melt_request` storage with associated blinded messages; new migrations for SQLite and PostgreSQL ([thesimplekid]). +- cdk-cln: Persist last `pay_index` in the mint KV store to avoid missed events across restarts ([thesimplekid]). +- cdk: HTTP subscriptions emit BOLT12 notifications per NUT-17 ([crodas]). +- cdk: DNS TXT resolution in HttpTransport and MintConnector for BIP‑353 lookups ([crodas]). +- cdk-ffi: Wallet FFI bindings and async constructors ([davidcaseria]). +- cdk-prometheus: New metrics crate and optional embedded Prometheus server; integrated metrics across HTTP, database, payments, and mint (feature: `prometheus`) ([asmo]). +- cdk-mintd: Optional Prometheus metrics server with configurable address/port via config and env vars (feature: `prometheus`) ([thesimplekid]). +- cdk-ldk-node: Web UI improvements (dynamic status, navigation, mobile support) ([erik]). +- cdk-postgres: Dedicated auth database support with separate schema and migrations when auth is enabled ([thesimplekid]/[asmo]). + ### Changed - cdk-common: Refactored `MintPayment` trait method `wait_any_incoming_payment` to `wait_payment_event` with event-driven architecture ([thesimplekid]). @@ -25,9 +40,33 @@ - cdk: Updated mint payment handling to process payment events through new `Event` enum pattern ([thesimplekid]). - cashu: Updated BOLT12 payment method specification from NUT-24 to NUT-25 ([thesimplekid]). - cdk: Updated BOLT12 import references from nut24 to nut25 module ([thesimplekid]). +- cdk: Do not fallback from WebSocket to HTTP on first error in subscriptions; retry only when appropriate ([crodas]). +- cdk: Abstracted HTTP Transport; centralized `pay_request` logic into the cdk library ([lollerfirst]). +- cdk: MultiMintWallet refactor for clearer APIs and behavior when managing multiple mints ([davidcaseria]/[thesimplekid]). +- cdk: Treat `None` proxy host matcher as "apply to all hosts" for HTTP transport ([lollerfirst]). +- cdk: QuoteId handling unified as string in APIs and storage ([thesimplekid]). +- cdk-axum: Close WebSocket connections sooner on shutdown/errors to avoid dangling clients ([crodas]). +- cdk-sql-common: Consistent ordering for SQL migrations and build uses `OUT_DIR` for embedded migration files ([vnprc]). +- cdk-signatory: Updated protobuf to latest spec and added signatory-related DB migrations ([crodas]). +- cdk-redb: Bumped dependency version ([thesimplekid]). -### Fixied +### Fixed - cdk: Wallet melt track and use payment method from quote for BOLT11/BOLT12 routing ([thesimplekid]). +- cdk: Improve error response details and mapping across HTTP/WS paths ([thesimplekid]). +- cdk: Fix config being overwritten on startup in certain scenarios ([thesimplekid]). +- cdk: WASM compatibility fixes for HTTP subscriptions and time handling (use `instant`) ([gudnuf]). +- cdk-postgres: Fix reconnection in connection pool and migration prefixes. +- cdk: Check keyset max order when generating/using keysets ([thesimplekid]). +- cdk: Correct error code returned for duplicate signature conditions ([lollerfirst]). +- cdk: Ensure all mint quotes are returned in listings ([thesimplekid]). +- cdk-axum: Improve error response detail structure ([thesimplekid]). + + +## [0.12.1](https://github.com/cashubtc/cdk/releases/tag/v0.12.1) + +### Fixed +- cdk-postgres: TLS support for PostgreSQL connections ([asmogo]). +- cdk: patch sha-512 derivation -> sha-256 derivation ([lollerfirst]). ## [0.12.0](https://github.com/cashubtc/cdk/releases/tag/v0.12.0) diff --git a/Cargo.toml b/Cargo.toml index 8334cad88..9b8a6afb3 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -33,7 +33,7 @@ rust-version = "1.85.0" license = "MIT" homepage = "https://github.com/cashubtc/cdk" repository = "https://github.com/cashubtc/cdk.git" -version = "0.12.0" +version = "0.13.0" readme = "README.md" [workspace.dependencies] @@ -43,25 +43,25 @@ axum = { version = "0.8.1", features = ["ws"] } bitcoin = { version = "0.32.2", features = ["base64", "serde", "rand", "rand-std"] } bip39 = { version = "2.0", features = ["rand"] } jsonwebtoken = "9.2.0" -cashu = { path = "./crates/cashu", version = "=0.12.0" } -cdk = { path = "./crates/cdk", default-features = false, version = "=0.12.0" } -cdk-common = { path = "./crates/cdk-common", default-features = false, version = "=0.12.0" } -cdk-axum = { path = "./crates/cdk-axum", default-features = false, version = "=0.12.0" } -cdk-cln = { path = "./crates/cdk-cln", version = "=0.12.0" } -cdk-lnbits = { path = "./crates/cdk-lnbits", version = "=0.12.0" } -cdk-lnd = { path = "./crates/cdk-lnd", version = "=0.12.0" } -cdk-ldk-node = { path = "./crates/cdk-ldk-node", version = "=0.12.0" } -cdk-fake-wallet = { path = "./crates/cdk-fake-wallet", version = "=0.12.0" } -cdk-ffi = { path = "./crates/cdk-ffi", version = "=0.12.0" } -cdk-payment-processor = { path = "./crates/cdk-payment-processor", default-features = true, version = "=0.12.0" } -cdk-mint-rpc = { path = "./crates/cdk-mint-rpc", version = "=0.12.0" } -cdk-redb = { path = "./crates/cdk-redb", default-features = true, version = "=0.12.0" } -cdk-sql-common = { path = "./crates/cdk-sql-common", default-features = true, version = "=0.12.0" } -cdk-sqlite = { path = "./crates/cdk-sqlite", default-features = true, version = "=0.12.0" } -cdk-postgres = { path = "./crates/cdk-postgres", default-features = true, version = "=0.12.0" } -cdk-signatory = { path = "./crates/cdk-signatory", version = "=0.12.0", default-features = false } -cdk-mintd = { path = "./crates/cdk-mintd", version = "=0.12.0", default-features = false } -cdk-prometheus = { path = "./crates/cdk-prometheus", version = "=0.12.0", default-features = false } +cashu = { path = "./crates/cashu", version = "=0.13.0" } +cdk = { path = "./crates/cdk", default-features = false, version = "=0.13.0" } +cdk-common = { path = "./crates/cdk-common", default-features = false, version = "=0.13.0" } +cdk-axum = { path = "./crates/cdk-axum", default-features = false, version = "=0.13.0" } +cdk-cln = { path = "./crates/cdk-cln", version = "=0.13.0" } +cdk-lnbits = { path = "./crates/cdk-lnbits", version = "=0.13.0" } +cdk-lnd = { path = "./crates/cdk-lnd", version = "=0.13.0" } +cdk-ldk-node = { path = "./crates/cdk-ldk-node", version = "=0.13.0" } +cdk-fake-wallet = { path = "./crates/cdk-fake-wallet", version = "=0.13.0" } +cdk-ffi = { path = "./crates/cdk-ffi", version = "=0.13.0" } +cdk-payment-processor = { path = "./crates/cdk-payment-processor", default-features = true, version = "=0.13.0" } +cdk-mint-rpc = { path = "./crates/cdk-mint-rpc", version = "=0.13.0" } +cdk-redb = { path = "./crates/cdk-redb", default-features = true, version = "=0.13.0" } +cdk-sql-common = { path = "./crates/cdk-sql-common", default-features = true, version = "=0.13.0" } +cdk-sqlite = { path = "./crates/cdk-sqlite", default-features = true, version = "=0.13.0" } +cdk-postgres = { path = "./crates/cdk-postgres", default-features = true, version = "=0.13.0" } +cdk-signatory = { path = "./crates/cdk-signatory", version = "=0.13.0", default-features = false } +cdk-mintd = { path = "./crates/cdk-mintd", version = "=0.13.0", default-features = false } +cdk-prometheus = { path = "./crates/cdk-prometheus", version = "=0.13.0", default-features = false } clap = { version = "4.5.31", features = ["derive"] } ciborium = { version = "0.2.2", default-features = false, features = ["std"] } cbor-diag = "0.1.12" From 6ad2c3a67ea62c73fd2f9b27fc54a847db8f5beb Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Tue, 23 Sep 2025 14:48:56 +0100 Subject: [PATCH 179/321] chore: ffi to release --- crates/cdk-ffi/Cargo.toml | 2 ++ justfile | 2 ++ 2 files changed, 4 insertions(+) diff --git a/crates/cdk-ffi/Cargo.toml b/crates/cdk-ffi/Cargo.toml index b8cef967a..80382a084 100644 --- a/crates/cdk-ffi/Cargo.toml +++ b/crates/cdk-ffi/Cargo.toml @@ -5,6 +5,8 @@ edition.workspace = true license.workspace = true repository.workspace = true rust-version.workspace = true +description = "FFI bindings for cdk wallet" +homepage = "https://github.com/cashubtc/cdk" [lib] crate-type = ["cdylib", "staticlib", "rlib"] diff --git a/justfile b/justfile index 2fe9d06dd..0a1f48288 100644 --- a/justfile +++ b/justfile @@ -322,6 +322,7 @@ release m="": args=( "-p cashu" + "-p cdk-prometheus" "-p cdk-common" "-p cdk-sql-common" "-p cdk-sqlite" @@ -329,6 +330,7 @@ release m="": "-p cdk-redb" "-p cdk-signatory" "-p cdk" + "-p cdk-ffi" "-p cdk-axum" "-p cdk-mint-rpc" "-p cdk-cln" From bf6b672fdc4d911e3405b3cc758af1b3cc2d8601 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Tue, 23 Sep 2025 15:05:16 +0100 Subject: [PATCH 180/321] chore: add tag to 0.13.0 --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0c4822cce..6a00a985e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,7 @@ -## [Unreleased] +## [0.13.0](https://github.com/cashubtc/cdk/releases/tag/v0.13.0) ### Summary From 0f0b78c0b0e330b5b1ca3f30f6f17b402c781d92 Mon Sep 17 00:00:00 2001 From: C Date: Wed, 24 Sep 2025 09:02:24 -0300 Subject: [PATCH 181/321] Include supported amounts instead of assuming the power of 2 (#1055) * Include supported amounts instead of assuming the power of 2 The mint's signatory defines the amounts and the wallet, and the mint, when paying, should use them instead of assuming the supported amounts are 2^(0..32), which is not part of the spec. * Introduce FeeAndAmount struct --- crates/cashu/src/amount.rs | 153 ++++++++++---- crates/cashu/src/nuts/nut00/mod.rs | 8 +- crates/cashu/src/nuts/nut13.rs | 9 +- crates/cdk-common/src/database/mint/mod.rs | 8 +- crates/cdk-ffi/src/wallet.rs | 11 +- crates/cdk-integration-tests/tests/bolt12.rs | 9 +- .../tests/fake_wallet.rs | 152 +++++++++++--- .../tests/happy_path_mint_wallet.rs | 10 +- .../tests/integration_tests_pure.rs | 140 ++++++++++--- crates/cdk-integration-tests/tests/regtest.rs | 10 +- crates/cdk-signatory/src/proto/convert.rs | 3 + .../cdk-signatory/src/proto/signatory.proto | 1 + crates/cdk-signatory/src/signatory.rs | 5 +- crates/cdk/src/mint/melt.rs | 19 +- crates/cdk/src/wallet/auth/auth_wallet.rs | 29 ++- crates/cdk/src/wallet/issue/issue_bolt11.rs | 8 +- crates/cdk/src/wallet/issue/issue_bolt12.rs | 7 +- crates/cdk/src/wallet/keysets.rs | 27 ++- crates/cdk/src/wallet/melt/melt_bolt11.rs | 2 +- crates/cdk/src/wallet/mod.rs | 40 ++-- crates/cdk/src/wallet/proofs.rs | 188 ++++++++++++++---- crates/cdk/src/wallet/send.rs | 19 +- crates/cdk/src/wallet/swap.rs | 33 ++- 23 files changed, 691 insertions(+), 200 deletions(-) diff --git a/crates/cashu/src/amount.rs b/crates/cashu/src/amount.rs index db55528ba..64c8f3f84 100644 --- a/crates/cashu/src/amount.rs +++ b/crates/cashu/src/amount.rs @@ -3,6 +3,7 @@ //! Is any unit and will be treated as the unit of the wallet use std::cmp::Ordering; +use std::collections::HashMap; use std::fmt; use std::str::FromStr; @@ -11,6 +12,7 @@ use serde::{Deserialize, Serialize}; use thiserror::Error; use crate::nuts::CurrencyUnit; +use crate::Id; /// Amount Error #[derive(Debug, Error)] @@ -41,6 +43,40 @@ pub enum Error { #[serde(transparent)] pub struct Amount(u64); +/// Fees and and amount type, it can be casted just as a reference to the inner amounts, or a single +/// u64 which is the fee +#[derive(Debug, Clone)] +pub struct FeeAndAmounts { + fee: u64, + amounts: Vec, +} + +impl From<(u64, Vec)> for FeeAndAmounts { + fn from(value: (u64, Vec)) -> Self { + Self { + fee: value.0, + amounts: value.1, + } + } +} + +impl FeeAndAmounts { + /// Fees + #[inline(always)] + pub fn fee(&self) -> u64 { + self.fee + } + + /// Amounts + #[inline(always)] + pub fn amounts(&self) -> &[u64] { + &self.amounts + } +} + +/// Fees and Amounts for each Keyset +pub type KeysetFeeAndAmounts = HashMap; + impl FromStr for Amount { type Err = Error; @@ -60,31 +96,38 @@ impl Amount { pub const ONE: Amount = Amount(1); /// Split into parts that are powers of two - pub fn split(&self) -> Vec { - let sats = self.0; - (0_u64..64) + pub fn split(&self, fee_and_amounts: &FeeAndAmounts) -> Vec { + fee_and_amounts + .amounts + .iter() .rev() - .filter_map(|bit| { - let part = 1 << bit; - ((sats & part) == part).then_some(Self::from(part)) + .fold((Vec::new(), self.0), |(mut acc, total), &amount| { + if total >= amount { + acc.push(Self::from(amount)); + } + (acc, total % amount) }) - .collect() + .0 } /// Split into parts that are powers of two by target - pub fn split_targeted(&self, target: &SplitTarget) -> Result, Error> { + pub fn split_targeted( + &self, + target: &SplitTarget, + fee_and_amounts: &FeeAndAmounts, + ) -> Result, Error> { let mut parts = match target { - SplitTarget::None => self.split(), + SplitTarget::None => self.split(fee_and_amounts), SplitTarget::Value(amount) => { if self.le(amount) { - return Ok(self.split()); + return Ok(self.split(fee_and_amounts)); } let mut parts_total = Amount::ZERO; let mut parts = Vec::new(); // The powers of two that are need to create target value - let parts_of_value = amount.split(); + let parts_of_value = amount.split(fee_and_amounts); while parts_total.lt(self) { for part in parts_of_value.iter().copied() { @@ -92,7 +135,7 @@ impl Amount { parts.push(part); } else { let amount_left = *self - parts_total; - parts.extend(amount_left.split()); + parts.extend(amount_left.split(fee_and_amounts)); } parts_total = Amount::try_sum(parts.clone().iter().copied())?; @@ -115,7 +158,7 @@ impl Amount { } Ordering::Greater => { let extra = *self - values_total; - let mut extra_amount = extra.split(); + let mut extra_amount = extra.split(fee_and_amounts); let mut values = values.clone(); values.append(&mut extra_amount); @@ -130,17 +173,18 @@ impl Amount { } /// Splits amount into powers of two while accounting for the swap fee - pub fn split_with_fee(&self, fee_ppk: u64) -> Result, Error> { - let without_fee_amounts = self.split(); - let total_fee_ppk = fee_ppk + pub fn split_with_fee(&self, fee_and_amounts: &FeeAndAmounts) -> Result, Error> { + let without_fee_amounts = self.split(fee_and_amounts); + let total_fee_ppk = fee_and_amounts + .fee .checked_mul(without_fee_amounts.len() as u64) .ok_or(Error::AmountOverflow)?; let fee = Amount::from(total_fee_ppk.div_ceil(1000)); let new_amount = self.checked_add(fee).ok_or(Error::AmountOverflow)?; - let split = new_amount.split(); + let split = new_amount.split(fee_and_amounts); let split_fee_ppk = (split.len() as u64) - .checked_mul(fee_ppk) + .checked_mul(fee_and_amounts.fee) .ok_or(Error::AmountOverflow)?; let split_fee = Amount::from(split_fee_ppk.div_ceil(1000)); @@ -151,7 +195,7 @@ impl Amount { } self.checked_add(Amount::ONE) .ok_or(Error::AmountOverflow)? - .split_with_fee(fee_ppk) + .split_with_fee(fee_and_amounts) } /// Checked addition for Amount. Returns None if overflow occurs. @@ -192,6 +236,11 @@ impl Amount { ) -> Result { to_unit(self.0, current_unit, target_unit) } + /// + /// Convert to u64 + pub fn to_u64(self) -> u64 { + self.0 + } /// Convert to i64 pub fn to_i64(self) -> Option { @@ -376,34 +425,43 @@ mod tests { #[test] fn test_split_amount() { - assert_eq!(Amount::from(1).split(), vec![Amount::from(1)]); - assert_eq!(Amount::from(2).split(), vec![Amount::from(2)]); + let fee_and_amounts = (0, (0..32).map(|x| 2u64.pow(x)).collect::>()).into(); + assert_eq!( - Amount::from(3).split(), + Amount::from(1).split(&fee_and_amounts), + vec![Amount::from(1)] + ); + assert_eq!( + Amount::from(2).split(&fee_and_amounts), + vec![Amount::from(2)] + ); + assert_eq!( + Amount::from(3).split(&fee_and_amounts), vec![Amount::from(2), Amount::from(1)] ); let amounts: Vec = [8, 2, 1].iter().map(|a| Amount::from(*a)).collect(); - assert_eq!(Amount::from(11).split(), amounts); + assert_eq!(Amount::from(11).split(&fee_and_amounts), amounts); let amounts: Vec = [128, 64, 32, 16, 8, 4, 2, 1] .iter() .map(|a| Amount::from(*a)) .collect(); - assert_eq!(Amount::from(255).split(), amounts); + assert_eq!(Amount::from(255).split(&fee_and_amounts), amounts); } #[test] fn test_split_target_amount() { + let fee_and_amounts = (0, (0..32).map(|x| 2u64.pow(x)).collect::>()).into(); let amount = Amount(65); let split = amount - .split_targeted(&SplitTarget::Value(Amount(32))) + .split_targeted(&SplitTarget::Value(Amount(32)), &fee_and_amounts) .unwrap(); assert_eq!(vec![Amount(1), Amount(32), Amount(32)], split); let amount = Amount(150); let split = amount - .split_targeted(&SplitTarget::Value(Amount::from(50))) + .split_targeted(&SplitTarget::Value(Amount::from(50)), &fee_and_amounts) .unwrap(); assert_eq!( vec![ @@ -423,7 +481,7 @@ mod tests { let amount = Amount::from(63); let split = amount - .split_targeted(&SplitTarget::Value(Amount::from(32))) + .split_targeted(&SplitTarget::Value(Amount::from(32)), &fee_and_amounts) .unwrap(); assert_eq!( vec![ @@ -440,22 +498,21 @@ mod tests { #[test] fn test_split_with_fee() { + let fee_and_amounts = (1, (0..32).map(|x| 2u64.pow(x)).collect::>()).into(); let amount = Amount(2); - let fee_ppk = 1; - let split = amount.split_with_fee(fee_ppk).unwrap(); + let split = amount.split_with_fee(&fee_and_amounts).unwrap(); assert_eq!(split, vec![Amount(2), Amount(1)]); let amount = Amount(3); - let fee_ppk = 1; - let split = amount.split_with_fee(fee_ppk).unwrap(); + let split = amount.split_with_fee(&fee_and_amounts).unwrap(); assert_eq!(split, vec![Amount(4)]); let amount = Amount(3); - let fee_ppk = 1000; + let fee_and_amounts = (1000, (0..32).map(|x| 2u64.pow(x)).collect::>()).into(); - let split = amount.split_with_fee(fee_ppk).unwrap(); + let split = amount.split_with_fee(&fee_and_amounts).unwrap(); // With fee_ppk=1000 (100%), amount 3 requires proofs totaling at least 5 // to cover both the amount (3) and fees (~2 for 2 proofs) assert_eq!(split, vec![Amount(4), Amount(1)]); @@ -463,14 +520,14 @@ mod tests { #[test] fn test_split_with_fee_reported_issue() { + let fee_and_amounts = (100, (0..32).map(|x| 2u64.pow(x)).collect::>()).into(); // Test the reported issue: mint 600, send 300 with fee_ppk=100 let amount = Amount(300); - let fee_ppk = 100; - let split = amount.split_with_fee(fee_ppk).unwrap(); + let split = amount.split_with_fee(&fee_and_amounts).unwrap(); // Calculate the total fee for the split - let total_fee_ppk = (split.len() as u64) * fee_ppk; + let total_fee_ppk = (split.len() as u64) * fee_and_amounts.fee; let total_fee = Amount::from(total_fee_ppk.div_ceil(1000)); // The split should cover the amount plus fees @@ -502,7 +559,9 @@ mod tests { ]; for (amount, fee_ppk) in test_cases { - let result = amount.split_with_fee(fee_ppk); + let fee_and_amounts = + (fee_ppk, (0..32).map(|x| 2u64.pow(x)).collect::>()).into(); + let result = amount.split_with_fee(&fee_and_amounts); assert!( result.is_ok(), "split_with_fee failed for amount {} with fee_ppk {}: {:?}", @@ -550,7 +609,9 @@ mod tests { ]; for (amount, fee_ppk) in test_cases { - let result = amount.split_with_fee(fee_ppk); + let fee_and_amounts = + (fee_ppk, (0..32).map(|x| 2u64.pow(x)).collect::>()).into(); + let result = amount.split_with_fee(&fee_and_amounts); assert!( result.is_ok(), "split_with_fee failed for amount {} with fee_ppk {}: {:?}", @@ -578,9 +639,10 @@ mod tests { // Test that the recursion doesn't go infinite // This tests the edge case where the method keeps adding Amount::ONE let amount = Amount(1); - let fee_ppk = 10000; // Very high fee that might cause recursion + let fee_ppk = 10000; + let fee_and_amounts = (fee_ppk, (0..32).map(|x| 2u64.pow(x)).collect::>()).into(); - let result = amount.split_with_fee(fee_ppk); + let result = amount.split_with_fee(&fee_and_amounts); assert!( result.is_ok(), "split_with_fee should handle extreme fees without infinite recursion" @@ -589,13 +651,16 @@ mod tests { #[test] fn test_split_values() { + let fee_and_amounts = (0, (0..32).map(|x| 2u64.pow(x)).collect::>()).into(); let amount = Amount(10); let target = vec![Amount(2), Amount(4), Amount(4)]; let split_target = SplitTarget::Values(target.clone()); - let values = amount.split_targeted(&split_target).unwrap(); + let values = amount + .split_targeted(&split_target, &fee_and_amounts) + .unwrap(); assert_eq!(target, values); @@ -603,13 +668,15 @@ mod tests { let split_target = SplitTarget::Values(vec![Amount(2), Amount(4)]); - let values = amount.split_targeted(&split_target).unwrap(); + let values = amount + .split_targeted(&split_target, &fee_and_amounts) + .unwrap(); assert_eq!(target, values); let split_target = SplitTarget::Values(vec![Amount(2), Amount(10)]); - let values = amount.split_targeted(&split_target); + let values = amount.split_targeted(&split_target, &fee_and_amounts); assert!(values.is_err()) } diff --git a/crates/cashu/src/nuts/nut00/mod.rs b/crates/cashu/src/nuts/nut00/mod.rs index 485829347..bc30a8ec6 100644 --- a/crates/cashu/src/nuts/nut00/mod.rs +++ b/crates/cashu/src/nuts/nut00/mod.rs @@ -18,6 +18,8 @@ use super::nut10; #[cfg(feature = "wallet")] use super::nut11::SpendingConditions; #[cfg(feature = "wallet")] +use crate::amount::FeeAndAmounts; +#[cfg(feature = "wallet")] use crate::amount::SplitTarget; #[cfg(feature = "wallet")] use crate::dhke::blind_message; @@ -746,8 +748,9 @@ impl PreMintSecrets { keyset_id: Id, amount: Amount, amount_split_target: &SplitTarget, + fee_and_amounts: &FeeAndAmounts, ) -> Result { - let amount_split = amount.split_targeted(amount_split_target)?; + let amount_split = amount.split_targeted(amount_split_target, fee_and_amounts)?; let mut output = Vec::with_capacity(amount_split.len()); @@ -830,8 +833,9 @@ impl PreMintSecrets { amount: Amount, amount_split_target: &SplitTarget, conditions: &SpendingConditions, + fee_and_amounts: &FeeAndAmounts, ) -> Result { - let amount_split = amount.split_targeted(amount_split_target)?; + let amount_split = amount.split_targeted(amount_split_target, fee_and_amounts)?; let mut output = Vec::with_capacity(amount_split.len()); diff --git a/crates/cashu/src/nuts/nut13.rs b/crates/cashu/src/nuts/nut13.rs index 66fcf808a..c8841b041 100644 --- a/crates/cashu/src/nuts/nut13.rs +++ b/crates/cashu/src/nuts/nut13.rs @@ -11,7 +11,7 @@ use tracing::instrument; use super::nut00::{BlindedMessage, PreMint, PreMintSecrets}; use super::nut01::SecretKey; use super::nut02::Id; -use crate::amount::SplitTarget; +use crate::amount::{FeeAndAmounts, SplitTarget}; use crate::dhke::blind_message; use crate::secret::Secret; use crate::util::hex; @@ -127,12 +127,13 @@ impl PreMintSecrets { seed: &[u8; 64], amount: Amount, amount_split_target: &SplitTarget, + fee_and_amounts: &FeeAndAmounts, ) -> Result { let mut pre_mint_secrets = PreMintSecrets::new(keyset_id); let mut counter = counter; - for amount in amount.split_targeted(amount_split_target)? { + for amount in amount.split_targeted(amount_split_target, fee_and_amounts)? { let secret = Secret::from_seed(seed, keyset_id, counter)?; let blinding_factor = SecretKey::from_seed(seed, keyset_id, counter)?; @@ -486,10 +487,12 @@ mod tests { .unwrap(); let amount = Amount::from(1000u64); let split_target = SplitTarget::default(); + let fee_and_amounts = (0, (0..32).map(|x| 2u64.pow(x)).collect::>()).into(); // Test PreMintSecrets generation with v2 keyset let pre_mint_secrets = - PreMintSecrets::from_seed(keyset_id, 0, &seed, amount, &split_target).unwrap(); + PreMintSecrets::from_seed(keyset_id, 0, &seed, amount, &split_target, &fee_and_amounts) + .unwrap(); // Verify all secrets in the pre_mint use the new v2 derivation for (i, pre_mint) in pre_mint_secrets.secrets.iter().enumerate() { diff --git a/crates/cdk-common/src/database/mint/mod.rs b/crates/cdk-common/src/database/mint/mod.rs index 01af134ee..922c9d29d 100644 --- a/crates/cdk-common/src/database/mint/mod.rs +++ b/crates/cdk-common/src/database/mint/mod.rs @@ -34,8 +34,7 @@ pub const KVSTORE_NAMESPACE_KEY_MAX_LEN: usize = 120; pub fn validate_kvstore_string(s: &str) -> Result<(), Error> { if s.len() > KVSTORE_NAMESPACE_KEY_MAX_LEN { return Err(Error::KVStoreInvalidKey(format!( - "{} exceeds maximum length of key characters", - KVSTORE_NAMESPACE_KEY_MAX_LEN + "{KVSTORE_NAMESPACE_KEY_MAX_LEN} exceeds maximum length of key characters" ))); } @@ -72,11 +71,10 @@ pub fn validate_kvstore_params( } // Check for potential collisions between keys and namespaces in the same namespace - let namespace_key = format!("{}/{}", primary_namespace, secondary_namespace); + let namespace_key = format!("{primary_namespace}/{secondary_namespace}"); if key == primary_namespace || key == secondary_namespace || key == namespace_key { return Err(Error::KVStoreInvalidKey(format!( - "Key '{}' conflicts with namespace names", - key + "Key '{key}' conflicts with namespace names" ))); } diff --git a/crates/cdk-ffi/src/wallet.rs b/crates/cdk-ffi/src/wallet.rs index 04d2035f8..b342e1427 100644 --- a/crates/cdk-ffi/src/wallet.rs +++ b/crates/cdk-ffi/src/wallet.rs @@ -372,8 +372,11 @@ impl Wallet { pub async fn get_keyset_fees_by_id(&self, keyset_id: String) -> Result { let id = cdk::nuts::Id::from_str(&keyset_id) .map_err(|e| FfiError::Generic { msg: e.to_string() })?; - let fees = self.inner.get_keyset_fees_by_id(id).await?; - Ok(fees) + Ok(self + .inner + .get_keyset_fees_and_amounts_by_id(id) + .await? + .fee()) } /// Reclaim unspent proofs (mark them as unspent in the database) @@ -397,8 +400,8 @@ impl Wallet { ) -> Result { let id = cdk::nuts::Id::from_str(&keyset_id) .map_err(|e| FfiError::Generic { msg: e.to_string() })?; - let fee_ppk = self.inner.get_keyset_fees_by_id(id).await?; - let total_fee = (proof_count as u64 * fee_ppk) / 1000; // fee is per thousand + let fee_and_amounts = self.inner.get_keyset_fees_and_amounts_by_id(id).await?; + let total_fee = (proof_count as u64 * fee_and_amounts.fee()) / 1000; // fee is per thousand Ok(Amount::new(total_fee)) } } diff --git a/crates/cdk-integration-tests/tests/bolt12.rs b/crates/cdk-integration-tests/tests/bolt12.rs index 45c7458d4..76d7e8d1f 100644 --- a/crates/cdk-integration-tests/tests/bolt12.rs +++ b/crates/cdk-integration-tests/tests/bolt12.rs @@ -352,7 +352,14 @@ async fn test_regtest_bolt12_mint_extra() -> Result<()> { assert_eq!(state.amount_paid, (pay_amount_msats / 1_000).into()); assert_eq!(state.amount_issued, Amount::ZERO); - let pre_mint = PreMintSecrets::random(active_keyset_id, 500.into(), &SplitTarget::None)?; + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); + + let pre_mint = PreMintSecrets::random( + active_keyset_id, + 500.into(), + &SplitTarget::None, + &fee_and_amounts, + )?; let quote_info = wallet .localstore diff --git a/crates/cdk-integration-tests/tests/fake_wallet.rs b/crates/cdk-integration-tests/tests/fake_wallet.rs index 1e01eed03..7237c66f1 100644 --- a/crates/cdk-integration-tests/tests/fake_wallet.rs +++ b/crates/cdk-integration-tests/tests/fake_wallet.rs @@ -392,9 +392,15 @@ async fn test_fake_melt_change_in_quote() { let melt_quote = wallet.melt_quote(invoice.to_string(), None).await.unwrap(); let keyset = wallet.fetch_active_keyset().await.unwrap(); + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); - let premint_secrets = - PreMintSecrets::random(keyset.id, 100.into(), &SplitTarget::default()).unwrap(); + let premint_secrets = PreMintSecrets::random( + keyset.id, + 100.into(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .unwrap(); let client = HttpClient::new(MINT_URL.parse().unwrap(), None); @@ -469,9 +475,15 @@ async fn test_fake_mint_without_witness() { let http_client = HttpClient::new(MINT_URL.parse().unwrap(), None); let active_keyset_id = wallet.fetch_active_keyset().await.unwrap().id; + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); - let premint_secrets = - PreMintSecrets::random(active_keyset_id, 100.into(), &SplitTarget::default()).unwrap(); + let premint_secrets = PreMintSecrets::random( + active_keyset_id, + 100.into(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .unwrap(); let request = MintRequest { quote: mint_quote.id, @@ -513,9 +525,15 @@ async fn test_fake_mint_with_wrong_witness() { let http_client = HttpClient::new(MINT_URL.parse().unwrap(), None); let active_keyset_id = wallet.fetch_active_keyset().await.unwrap().id; + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); - let premint_secrets = - PreMintSecrets::random(active_keyset_id, 100.into(), &SplitTarget::default()).unwrap(); + let premint_secrets = PreMintSecrets::random( + active_keyset_id, + 100.into(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .unwrap(); let mut request = MintRequest { quote: mint_quote.id, @@ -561,9 +579,15 @@ async fn test_fake_mint_inflated() { .expect("no error"); let active_keyset_id = wallet.fetch_active_keyset().await.unwrap().id; + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); - let pre_mint = - PreMintSecrets::random(active_keyset_id, 500.into(), &SplitTarget::None).unwrap(); + let pre_mint = PreMintSecrets::random( + active_keyset_id, + 500.into(), + &SplitTarget::None, + &fee_and_amounts, + ) + .unwrap(); let quote_info = wallet .localstore @@ -623,8 +647,15 @@ async fn test_fake_mint_multiple_units() { .expect("no error"); let active_keyset_id = wallet.fetch_active_keyset().await.unwrap().id; + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); - let pre_mint = PreMintSecrets::random(active_keyset_id, 50.into(), &SplitTarget::None).unwrap(); + let pre_mint = PreMintSecrets::random( + active_keyset_id, + 50.into(), + &SplitTarget::None, + &fee_and_amounts, + ) + .unwrap(); let wallet_usd = Wallet::new( MINT_URL, @@ -637,8 +668,13 @@ async fn test_fake_mint_multiple_units() { let active_keyset_id = wallet_usd.fetch_active_keyset().await.unwrap().id; - let usd_pre_mint = - PreMintSecrets::random(active_keyset_id, 50.into(), &SplitTarget::None).unwrap(); + let usd_pre_mint = PreMintSecrets::random( + active_keyset_id, + 50.into(), + &SplitTarget::None, + &fee_and_amounts, + ) + .unwrap(); let quote_info = wallet .localstore @@ -727,6 +763,7 @@ async fn test_fake_mint_multiple_unit_swap() { .expect("no error"); let active_keyset_id = wallet.fetch_active_keyset().await.unwrap().id; + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); { let inputs: Proofs = vec![ @@ -738,6 +775,7 @@ async fn test_fake_mint_multiple_unit_swap() { active_keyset_id, inputs.total_amount().unwrap(), &SplitTarget::None, + &fee_and_amounts, ) .unwrap(); @@ -764,13 +802,23 @@ async fn test_fake_mint_multiple_unit_swap() { let inputs: Proofs = proofs.into_iter().take(2).collect(); let total_inputs = inputs.total_amount().unwrap(); + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); let half = total_inputs / 2.into(); - let usd_pre_mint = - PreMintSecrets::random(usd_active_keyset_id, half, &SplitTarget::None).unwrap(); - let pre_mint = - PreMintSecrets::random(active_keyset_id, total_inputs - half, &SplitTarget::None) - .unwrap(); + let usd_pre_mint = PreMintSecrets::random( + usd_active_keyset_id, + half, + &SplitTarget::None, + &fee_and_amounts, + ) + .unwrap(); + let pre_mint = PreMintSecrets::random( + active_keyset_id, + total_inputs - half, + &SplitTarget::None, + &fee_and_amounts, + ) + .unwrap(); let mut usd_outputs = usd_pre_mint.blinded_messages(); let mut sat_outputs = pre_mint.blinded_messages(); @@ -870,6 +918,7 @@ async fn test_fake_mint_multiple_unit_melt() { } { + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); let inputs: Proofs = vec![proofs.first().expect("There is a proof").clone()]; let input_amount: u64 = inputs.total_amount().unwrap().into(); @@ -882,10 +931,16 @@ async fn test_fake_mint_multiple_unit_melt() { usd_active_keyset_id, inputs.total_amount().unwrap() + 100.into(), &SplitTarget::None, + &fee_and_amounts, + ) + .unwrap(); + let pre_mint = PreMintSecrets::random( + active_keyset_id, + 100.into(), + &SplitTarget::None, + &fee_and_amounts, ) .unwrap(); - let pre_mint = - PreMintSecrets::random(active_keyset_id, 100.into(), &SplitTarget::None).unwrap(); let mut usd_outputs = usd_pre_mint.blinded_messages(); let mut sat_outputs = pre_mint.blinded_messages(); @@ -944,6 +999,7 @@ async fn test_fake_mint_input_output_mismatch() { ) .expect("failed to create new usd wallet"); let usd_active_keyset_id = wallet_usd.fetch_active_keyset().await.unwrap().id; + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); let inputs = proofs; @@ -951,6 +1007,7 @@ async fn test_fake_mint_input_output_mismatch() { usd_active_keyset_id, inputs.total_amount().unwrap(), &SplitTarget::None, + &fee_and_amounts, ) .unwrap(); @@ -985,6 +1042,7 @@ async fn test_fake_mint_swap_inflated() { let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); let mut proof_streams = wallet.proof_stream(mint_quote.clone(), SplitTarget::default(), None); + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); let proofs = proof_streams .next() @@ -993,8 +1051,13 @@ async fn test_fake_mint_swap_inflated() { .expect("no error"); let active_keyset_id = wallet.fetch_active_keyset().await.unwrap().id; - let pre_mint = - PreMintSecrets::random(active_keyset_id, 101.into(), &SplitTarget::None).unwrap(); + let pre_mint = PreMintSecrets::random( + active_keyset_id, + 101.into(), + &SplitTarget::None, + &fee_and_amounts, + ) + .unwrap(); let swap_request = SwapRequest::new(proofs, pre_mint.blinded_messages()); @@ -1037,9 +1100,15 @@ async fn test_fake_mint_swap_spend_after_fail() { .expect("no error"); let active_keyset_id = wallet.fetch_active_keyset().await.unwrap().id; + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); - let pre_mint = - PreMintSecrets::random(active_keyset_id, 100.into(), &SplitTarget::None).unwrap(); + let pre_mint = PreMintSecrets::random( + active_keyset_id, + 100.into(), + &SplitTarget::None, + &fee_and_amounts, + ) + .unwrap(); let swap_request = SwapRequest::new(proofs.clone(), pre_mint.blinded_messages()); @@ -1048,8 +1117,13 @@ async fn test_fake_mint_swap_spend_after_fail() { assert!(response.is_ok()); - let pre_mint = - PreMintSecrets::random(active_keyset_id, 101.into(), &SplitTarget::None).unwrap(); + let pre_mint = PreMintSecrets::random( + active_keyset_id, + 101.into(), + &SplitTarget::None, + &fee_and_amounts, + ) + .unwrap(); let swap_request = SwapRequest::new(proofs.clone(), pre_mint.blinded_messages()); @@ -1064,8 +1138,13 @@ async fn test_fake_mint_swap_spend_after_fail() { Ok(_) => panic!("Should not have allowed swap with unbalanced"), } - let pre_mint = - PreMintSecrets::random(active_keyset_id, 100.into(), &SplitTarget::None).unwrap(); + let pre_mint = PreMintSecrets::random( + active_keyset_id, + 100.into(), + &SplitTarget::None, + &fee_and_amounts, + ) + .unwrap(); let swap_request = SwapRequest::new(proofs, pre_mint.blinded_messages()); @@ -1108,9 +1187,15 @@ async fn test_fake_mint_melt_spend_after_fail() { .expect("no error"); let active_keyset_id = wallet.fetch_active_keyset().await.unwrap().id; + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); - let pre_mint = - PreMintSecrets::random(active_keyset_id, 100.into(), &SplitTarget::None).unwrap(); + let pre_mint = PreMintSecrets::random( + active_keyset_id, + 100.into(), + &SplitTarget::None, + &fee_and_amounts, + ) + .unwrap(); let swap_request = SwapRequest::new(proofs.clone(), pre_mint.blinded_messages()); @@ -1119,8 +1204,13 @@ async fn test_fake_mint_melt_spend_after_fail() { assert!(response.is_ok()); - let pre_mint = - PreMintSecrets::random(active_keyset_id, 101.into(), &SplitTarget::None).unwrap(); + let pre_mint = PreMintSecrets::random( + active_keyset_id, + 101.into(), + &SplitTarget::None, + &fee_and_amounts, + ) + .unwrap(); let swap_request = SwapRequest::new(proofs.clone(), pre_mint.blinded_messages()); @@ -1180,6 +1270,7 @@ async fn test_fake_mint_duplicate_proofs_swap() { .expect("no error"); let active_keyset_id = wallet.fetch_active_keyset().await.unwrap().id; + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); let inputs = vec![proofs[0].clone(), proofs[0].clone()]; @@ -1187,6 +1278,7 @@ async fn test_fake_mint_duplicate_proofs_swap() { active_keyset_id, inputs.total_amount().unwrap(), &SplitTarget::None, + &fee_and_amounts, ) .unwrap(); diff --git a/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs b/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs index ba2a06bd9..d0389b9a6 100644 --- a/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs +++ b/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs @@ -376,9 +376,15 @@ async fn test_fake_melt_change_in_quote() { let melt_quote = wallet.melt_quote(invoice.to_string(), None).await.unwrap(); let keyset = wallet.fetch_active_keyset().await.unwrap(); + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); - let premint_secrets = - PreMintSecrets::random(keyset.id, 100.into(), &SplitTarget::default()).unwrap(); + let premint_secrets = PreMintSecrets::random( + keyset.id, + 100.into(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .unwrap(); let client = HttpClient::new(get_mint_url_from_env().parse().unwrap(), None); diff --git a/crates/cdk-integration-tests/tests/integration_tests_pure.rs b/crates/cdk-integration-tests/tests/integration_tests_pure.rs index 8cb645e7c..9ab1fb003 100644 --- a/crates/cdk-integration-tests/tests/integration_tests_pure.rs +++ b/crates/cdk-integration-tests/tests/integration_tests_pure.rs @@ -243,11 +243,13 @@ async fn test_mint_double_spend() { let keys = mint_bob.pubkeys().keysets.first().unwrap().clone(); let keyset_id = keys.id; + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); let preswap = PreMintSecrets::random( keyset_id, proofs.total_amount().unwrap(), &SplitTarget::default(), + &fee_and_amounts, ) .unwrap(); @@ -260,6 +262,7 @@ async fn test_mint_double_spend() { keyset_id, proofs.total_amount().unwrap(), &SplitTarget::default(), + &fee_and_amounts, ) .unwrap(); @@ -300,14 +303,30 @@ async fn test_attempt_to_swap_by_overflowing() { let keys = mint_bob.pubkeys().keysets.first().unwrap().clone(); let keyset_id = keys.id; + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); - let pre_mint_amount = - PreMintSecrets::random(keyset_id, amount.into(), &SplitTarget::default()).unwrap(); - let pre_mint_amount_two = - PreMintSecrets::random(keyset_id, amount.into(), &SplitTarget::default()).unwrap(); + let pre_mint_amount = PreMintSecrets::random( + keyset_id, + amount.into(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .unwrap(); + let pre_mint_amount_two = PreMintSecrets::random( + keyset_id, + amount.into(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .unwrap(); - let mut pre_mint = - PreMintSecrets::random(keyset_id, 1.into(), &SplitTarget::default()).unwrap(); + let mut pre_mint = PreMintSecrets::random( + keyset_id, + 1.into(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .unwrap(); pre_mint.combine(pre_mint_amount); pre_mint.combine(pre_mint_amount_two); @@ -320,6 +339,7 @@ async fn test_attempt_to_swap_by_overflowing() { cdk::Error::NUT03(cdk::nuts::nut03::Error::Amount(_)) => (), cdk::Error::AmountOverflow => (), cdk::Error::AmountError(_) => (), + cdk::Error::TransactionUnbalanced(_, _, _) => (), _ => { panic!("Wrong error returned in swap overflow {:?}", err); } @@ -353,9 +373,16 @@ async fn test_swap_unbalanced() { let keyset_id = get_keyset_id(&mint_bob).await; + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); + // Try to swap for less than the input amount (95 < 100) - let preswap = PreMintSecrets::random(keyset_id, 95.into(), &SplitTarget::default()) - .expect("Failed to create preswap"); + let preswap = PreMintSecrets::random( + keyset_id, + 95.into(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .expect("Failed to create preswap"); let swap_request = SwapRequest::new(proofs.clone(), preswap.blinded_messages()); @@ -368,8 +395,13 @@ async fn test_swap_unbalanced() { } // Try to swap for more than the input amount (101 > 100) - let preswap = PreMintSecrets::random(keyset_id, 101.into(), &SplitTarget::default()) - .expect("Failed to create preswap"); + let preswap = PreMintSecrets::random( + keyset_id, + 101.into(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .expect("Failed to create preswap"); let swap_request = SwapRequest::new(proofs.clone(), preswap.blinded_messages()); @@ -407,12 +439,14 @@ pub async fn test_p2pk_swap() { let secret = SecretKey::generate(); let spending_conditions = SpendingConditions::new_p2pk(secret.public_key(), None); + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); let pre_swap = PreMintSecrets::with_conditions( keyset_id, 100.into(), &SplitTarget::default(), &spending_conditions, + &fee_and_amounts, ) .unwrap(); @@ -430,7 +464,13 @@ pub async fn test_p2pk_swap() { ) .unwrap(); - let pre_swap = PreMintSecrets::random(keyset_id, 100.into(), &SplitTarget::default()).unwrap(); + let pre_swap = PreMintSecrets::random( + keyset_id, + 100.into(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .unwrap(); let swap_request = SwapRequest::new(proofs.clone(), pre_swap.blinded_messages()); @@ -536,8 +576,15 @@ async fn test_swap_overpay_underpay_fee() { let keys = mint_bob.pubkeys().keysets.first().unwrap().clone().keys; let keyset_id = Id::v1_from_keys(&keys); + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); - let preswap = PreMintSecrets::random(keyset_id, 9998.into(), &SplitTarget::default()).unwrap(); + let preswap = PreMintSecrets::random( + keyset_id, + 9998.into(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .unwrap(); let swap_request = SwapRequest::new(proofs.clone(), preswap.blinded_messages()); @@ -553,7 +600,13 @@ async fn test_swap_overpay_underpay_fee() { }, } - let preswap = PreMintSecrets::random(keyset_id, 1000.into(), &SplitTarget::default()).unwrap(); + let preswap = PreMintSecrets::random( + keyset_id, + 1000.into(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .unwrap(); let swap_request = SwapRequest::new(proofs.clone(), preswap.blinded_messages()); @@ -602,10 +655,17 @@ async fn test_mint_enforce_fee() { let keys = mint_bob.pubkeys().keysets.first().unwrap().clone(); let keyset_id = keys.id; + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); let five_proofs: Vec<_> = proofs.drain(..5).collect(); - let preswap = PreMintSecrets::random(keyset_id, 5.into(), &SplitTarget::default()).unwrap(); + let preswap = PreMintSecrets::random( + keyset_id, + 5.into(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .unwrap(); let swap_request = SwapRequest::new(five_proofs.clone(), preswap.blinded_messages()); @@ -621,7 +681,13 @@ async fn test_mint_enforce_fee() { }, } - let preswap = PreMintSecrets::random(keyset_id, 4.into(), &SplitTarget::default()).unwrap(); + let preswap = PreMintSecrets::random( + keyset_id, + 4.into(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .unwrap(); let swap_request = SwapRequest::new(five_proofs.clone(), preswap.blinded_messages()); @@ -631,7 +697,13 @@ async fn test_mint_enforce_fee() { let thousnad_proofs: Vec<_> = proofs.drain(..1001).collect(); - let preswap = PreMintSecrets::random(keyset_id, 1000.into(), &SplitTarget::default()).unwrap(); + let preswap = PreMintSecrets::random( + keyset_id, + 1000.into(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .unwrap(); let swap_request = SwapRequest::new(thousnad_proofs.clone(), preswap.blinded_messages()); @@ -647,7 +719,13 @@ async fn test_mint_enforce_fee() { }, } - let preswap = PreMintSecrets::random(keyset_id, 999.into(), &SplitTarget::default()).unwrap(); + let preswap = PreMintSecrets::random( + keyset_id, + 999.into(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .unwrap(); let swap_request = SwapRequest::new(thousnad_proofs.clone(), preswap.blinded_messages()); @@ -721,18 +799,34 @@ async fn test_concurrent_double_spend_swap() { .expect("Could not get proofs"); let keyset_id = get_keyset_id(&mint_bob).await; + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); // Create 3 identical swap requests with the same proofs - let preswap1 = PreMintSecrets::random(keyset_id, 100.into(), &SplitTarget::default()) - .expect("Failed to create preswap"); + let preswap1 = PreMintSecrets::random( + keyset_id, + 100.into(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .expect("Failed to create preswap"); let swap_request1 = SwapRequest::new(proofs.clone(), preswap1.blinded_messages()); - let preswap2 = PreMintSecrets::random(keyset_id, 100.into(), &SplitTarget::default()) - .expect("Failed to create preswap"); + let preswap2 = PreMintSecrets::random( + keyset_id, + 100.into(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .expect("Failed to create preswap"); let swap_request2 = SwapRequest::new(proofs.clone(), preswap2.blinded_messages()); - let preswap3 = PreMintSecrets::random(keyset_id, 100.into(), &SplitTarget::default()) - .expect("Failed to create preswap"); + let preswap3 = PreMintSecrets::random( + keyset_id, + 100.into(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .expect("Failed to create preswap"); let swap_request3 = SwapRequest::new(proofs.clone(), preswap3.blinded_messages()); // Spawn 3 concurrent tasks to process the swap requests diff --git a/crates/cdk-integration-tests/tests/regtest.rs b/crates/cdk-integration-tests/tests/regtest.rs index e726ab253..ce0a73cd7 100644 --- a/crates/cdk-integration-tests/tests/regtest.rs +++ b/crates/cdk-integration-tests/tests/regtest.rs @@ -315,9 +315,15 @@ async fn test_cached_mint() { .expect("payment"); let active_keyset_id = wallet.fetch_active_keyset().await.unwrap().id; + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); let http_client = HttpClient::new(get_mint_url_from_env().parse().unwrap(), None); - let premint_secrets = - PreMintSecrets::random(active_keyset_id, 100.into(), &SplitTarget::default()).unwrap(); + let premint_secrets = PreMintSecrets::random( + active_keyset_id, + 100.into(), + &SplitTarget::default().to_owned(), + &fee_and_amounts, + ) + .unwrap(); let mut request = MintRequest { quote: quote.id, diff --git a/crates/cdk-signatory/src/proto/convert.rs b/crates/cdk-signatory/src/proto/convert.rs index 91692cd00..da5a3fddb 100644 --- a/crates/cdk-signatory/src/proto/convert.rs +++ b/crates/cdk-signatory/src/proto/convert.rs @@ -60,6 +60,7 @@ impl TryInto for KeySet { .map(|(amount, pk)| PublicKey::from_slice(&pk).map(|pk| (amount.into(), pk))) .collect::, _>>()?, ), + amounts: self.amounts, final_expiry: self.final_expiry, }) } @@ -80,6 +81,7 @@ impl From for KeySet { .collect(), }), final_expiry: keyset.final_expiry, + amounts: keyset.amounts, version: Default::default(), } } @@ -361,6 +363,7 @@ impl From for KeySet { input_fee_ppk: value.input_fee_ppk, keys: Default::default(), final_expiry: value.final_expiry, + amounts: vec![], version: Default::default(), } } diff --git a/crates/cdk-signatory/src/proto/signatory.proto b/crates/cdk-signatory/src/proto/signatory.proto index 5b82408a2..3da00f971 100644 --- a/crates/cdk-signatory/src/proto/signatory.proto +++ b/crates/cdk-signatory/src/proto/signatory.proto @@ -64,6 +64,7 @@ message KeySet { Keys keys = 5; optional uint64 final_expiry = 6; uint64 version = 7; + repeated uint64 amounts = 8; } message Keys { diff --git a/crates/cdk-signatory/src/signatory.rs b/crates/cdk-signatory/src/signatory.rs index 1b7e2257b..0b987a72f 100644 --- a/crates/cdk-signatory/src/signatory.rs +++ b/crates/cdk-signatory/src/signatory.rs @@ -71,6 +71,8 @@ pub struct SignatoryKeySet { pub active: bool, /// The list of public keys pub keys: Keys, + /// Amounts supported by the keyset + pub amounts: Vec, /// Information about the fee per public key pub input_fee_ppk: u64, /// Final expiry of the keyset (unix timestamp in the future) @@ -110,7 +112,7 @@ impl From for MintKeySetInfo { derivation_path: Default::default(), derivation_path_index: Default::default(), max_order: 0, - amounts: vec![], + amounts: val.amounts, final_expiry: val.final_expiry, valid_from: 0, } @@ -124,6 +126,7 @@ impl From<&(MintKeySetInfo, MintKeySet)> for SignatoryKeySet { unit: key.unit.clone(), active: info.active, input_fee_ppk: info.input_fee_ppk, + amounts: info.amounts.clone(), keys: key.keys.clone().into(), final_expiry: key.final_expiry, } diff --git a/crates/cdk/src/mint/melt.rs b/crates/cdk/src/mint/melt.rs index 6ceb9bb30..a226a0324 100644 --- a/crates/cdk/src/mint/melt.rs +++ b/crates/cdk/src/mint/melt.rs @@ -930,7 +930,24 @@ impl Mint { let change_target = inputs_amount - total_spent - inputs_fee; - let mut amounts = change_target.split(); + let fee_and_amounts = self + .keysets + .load() + .iter() + .filter_map(|keyset| { + if keyset.active && Some(keyset.id) == outputs.first().map(|x| x.keyset_id) + { + Some((keyset.input_fee_ppk, keyset.amounts.clone()).into()) + } else { + None + } + }) + .next() + .unwrap_or_else(|| { + (0, (0..32).map(|x| 2u64.pow(x)).collect::>()).into() + }); + + let mut amounts = change_target.split(&fee_and_amounts); if outputs.len().lt(&amounts.len()) { tracing::debug!( diff --git a/crates/cdk/src/wallet/auth/auth_wallet.rs b/crates/cdk/src/wallet/auth/auth_wallet.rs index d61f2bb5b..58e683e89 100644 --- a/crates/cdk/src/wallet/auth/auth_wallet.rs +++ b/crates/cdk/src/wallet/auth/auth_wallet.rs @@ -393,10 +393,33 @@ impl AuthWallet { } } - let active_keyset_id = self.fetch_active_keyset().await?.id; + let keysets = self + .load_mint_keysets() + .await? + .into_iter() + .map(|x| (x.id, x)) + .collect::>(); - let premint_secrets = - PreMintSecrets::random(active_keyset_id, amount, &SplitTarget::Value(1.into()))?; + let active_keyset_id = self.fetch_active_keyset().await?.id; + let fee_and_amounts = ( + keysets + .get(&active_keyset_id) + .map(|x| x.input_fee_ppk) + .unwrap_or_default(), + self.load_keyset_keys(active_keyset_id) + .await? + .iter() + .map(|(amount, _)| amount.to_u64()) + .collect::>(), + ) + .into(); + + let premint_secrets = PreMintSecrets::random( + active_keyset_id, + amount, + &SplitTarget::Value(1.into()), + &fee_and_amounts, + )?; let request = MintAuthRequest { outputs: premint_secrets.blinded_messages(), diff --git a/crates/cdk/src/wallet/issue/issue_bolt11.rs b/crates/cdk/src/wallet/issue/issue_bolt11.rs index dfe17a526..98ac37805 100644 --- a/crates/cdk/src/wallet/issue/issue_bolt11.rs +++ b/crates/cdk/src/wallet/issue/issue_bolt11.rs @@ -222,6 +222,9 @@ impl Wallet { } let active_keyset_id = self.fetch_active_keyset().await?.id; + let fee_and_amounts = self + .get_keyset_fees_and_amounts_by_id(active_keyset_id) + .await?; let premint_secrets = match &spending_conditions { Some(spending_conditions) => PreMintSecrets::with_conditions( @@ -229,10 +232,12 @@ impl Wallet { amount_mintable, &amount_split_target, spending_conditions, + &fee_and_amounts, )?, None => { // Calculate how many secrets we'll need - let amount_split = amount_mintable.split_targeted(&amount_split_target)?; + let amount_split = + amount_mintable.split_targeted(&amount_split_target, &fee_and_amounts)?; let num_secrets = amount_split.len() as u32; tracing::debug!( @@ -255,6 +260,7 @@ impl Wallet { &self.seed, amount_mintable, &amount_split_target, + &fee_and_amounts, )? } }; diff --git a/crates/cdk/src/wallet/issue/issue_bolt12.rs b/crates/cdk/src/wallet/issue/issue_bolt12.rs index 1673ac894..470f25827 100644 --- a/crates/cdk/src/wallet/issue/issue_bolt12.rs +++ b/crates/cdk/src/wallet/issue/issue_bolt12.rs @@ -100,6 +100,9 @@ impl Wallet { }; let active_keyset_id = self.fetch_active_keyset().await?.id; + let fee_and_amounts = self + .get_keyset_fees_and_amounts_by_id(active_keyset_id) + .await?; let amount = match amount { Some(amount) => amount, @@ -123,10 +126,11 @@ impl Wallet { amount, &amount_split_target, spending_conditions, + &fee_and_amounts, )?, None => { // Calculate how many secrets we'll need without generating them - let amount_split = amount.split_targeted(&amount_split_target)?; + let amount_split = amount.split_targeted(&amount_split_target, &fee_and_amounts)?; let num_secrets = amount_split.len() as u32; tracing::debug!( @@ -149,6 +153,7 @@ impl Wallet { &self.seed, amount, &amount_split_target, + &fee_and_amounts, )? } }; diff --git a/crates/cdk/src/wallet/keysets.rs b/crates/cdk/src/wallet/keysets.rs index 302b8e85d..47f088204 100644 --- a/crates/cdk/src/wallet/keysets.rs +++ b/crates/cdk/src/wallet/keysets.rs @@ -1,5 +1,6 @@ use std::collections::HashMap; +use cdk_common::amount::{FeeAndAmounts, KeysetFeeAndAmounts}; use cdk_common::nut02::{KeySetInfos, KeySetInfosMethods}; use tracing::instrument; @@ -139,12 +140,12 @@ impl Wallet { } } - /// Get keyset fees for mint from local database only - offline operation + /// Get keyset fees and amounts for mint from local database only - offline operation /// /// Returns a HashMap of keyset IDs to their input fee rates (per-proof-per-thousand) /// from cached keysets in the local database. This is an offline operation that does /// not contact the mint. If no keysets are found locally, returns an error. - pub async fn get_keyset_fees(&self) -> Result, Error> { + pub async fn get_keyset_fees_and_amounts(&self) -> Result { let keysets = self .localstore .get_mint_keysets(self.mint_url.clone()) @@ -153,19 +154,33 @@ impl Wallet { let mut fees = HashMap::new(); for keyset in keysets { - fees.insert(keyset.id, keyset.input_fee_ppk); + fees.insert( + keyset.id, + ( + keyset.input_fee_ppk, + self.load_keyset_keys(keyset.id) + .await? + .iter() + .map(|(amount, _)| amount.to_u64()) + .collect::>(), + ) + .into(), + ); } Ok(fees) } - /// Get keyset fees for mint by keyset id from local database only - offline operation + /// Get keyset fees and amounts for mint by keyset id from local database only - offline operation /// /// Returns the input fee rate (per-proof-per-thousand) for a specific keyset ID from /// cached keysets in the local database. This is an offline operation that does not /// contact the mint. If the keyset is not found locally, returns an error. - pub async fn get_keyset_fees_by_id(&self, keyset_id: Id) -> Result { - self.get_keyset_fees() + pub async fn get_keyset_fees_and_amounts_by_id( + &self, + keyset_id: Id, + ) -> Result { + self.get_keyset_fees_and_amounts() .await? .get(&keyset_id) .cloned() diff --git a/crates/cdk/src/wallet/melt/melt_bolt11.rs b/crates/cdk/src/wallet/melt/melt_bolt11.rs index 050f7a839..5583b763d 100644 --- a/crates/cdk/src/wallet/melt/melt_bolt11.rs +++ b/crates/cdk/src/wallet/melt/melt_bolt11.rs @@ -341,7 +341,7 @@ impl Wallet { .into_iter() .map(|k| k.id) .collect(); - let keyset_fees = self.get_keyset_fees().await?; + let keyset_fees = self.get_keyset_fees_and_amounts().await?; let (mut input_proofs, mut exchange) = Wallet::select_exact_proofs( inputs_needed_amount, available_proofs, diff --git a/crates/cdk/src/wallet/mod.rs b/crates/cdk/src/wallet/mod.rs index 43c738d02..c2adec46e 100644 --- a/crates/cdk/src/wallet/mod.rs +++ b/crates/cdk/src/wallet/mod.rs @@ -4,6 +4,7 @@ use std::collections::HashMap; use std::str::FromStr; use std::sync::Arc; +use cdk_common::amount::FeeAndAmounts; use cdk_common::database::{self, WalletDatabase}; use cdk_common::subscription::Params; use getrandom::getrandom; @@ -326,34 +327,36 @@ impl Wallet { /// Get amounts needed to refill proof state #[instrument(skip(self))] - pub async fn amounts_needed_for_state_target(&self) -> Result, Error> { + pub async fn amounts_needed_for_state_target( + &self, + fee_and_amounts: &FeeAndAmounts, + ) -> Result, Error> { let unspent_proofs = self.get_unspent_proofs().await?; - let amounts_count: HashMap = + let amounts_count: HashMap = unspent_proofs .iter() .fold(HashMap::new(), |mut acc, proof| { let amount = proof.amount; - let counter = acc.entry(u64::from(amount) as usize).or_insert(0); + let counter = acc.entry(u64::from(amount)).or_insert(0); *counter += 1; acc }); - let all_possible_amounts: Vec = (0..32).map(|i| 2usize.pow(i as u32)).collect(); - - let needed_amounts = all_possible_amounts - .iter() - .fold(Vec::new(), |mut acc, amount| { - let count_needed: usize = self - .target_proof_count - .saturating_sub(*amounts_count.get(amount).unwrap_or(&0)); + let needed_amounts = + fee_and_amounts + .amounts() + .iter() + .fold(Vec::new(), |mut acc, amount| { + let count_needed = (self.target_proof_count as u64) + .saturating_sub(*amounts_count.get(amount).unwrap_or(&0)); - for _i in 0..count_needed { - acc.push(Amount::from(*amount as u64)); - } + for _i in 0..count_needed { + acc.push(Amount::from(*amount)); + } - acc - }); + acc + }); Ok(needed_amounts) } @@ -362,8 +365,11 @@ impl Wallet { async fn determine_split_target_values( &self, change_amount: Amount, + fee_and_amounts: &FeeAndAmounts, ) -> Result { - let mut amounts_needed_refill = self.amounts_needed_for_state_target().await?; + let mut amounts_needed_refill = self + .amounts_needed_for_state_target(fee_and_amounts) + .await?; amounts_needed_refill.sort(); diff --git a/crates/cdk/src/wallet/proofs.rs b/crates/cdk/src/wallet/proofs.rs index 2fe0c9e67..c90488e60 100644 --- a/crates/cdk/src/wallet/proofs.rs +++ b/crates/cdk/src/wallet/proofs.rs @@ -1,5 +1,6 @@ use std::collections::{HashMap, HashSet}; +use cdk_common::amount::KeysetFeeAndAmounts; use cdk_common::wallet::TransactionId; use cdk_common::Id; use tracing::instrument; @@ -188,11 +189,16 @@ impl Wallet { amount: Amount, proofs: Proofs, active_keyset_ids: &Vec, - keyset_fees: &HashMap, + fees_and_keyset_amounts: &KeysetFeeAndAmounts, include_fees: bool, ) -> Result<(Proofs, Option<(Proof, Amount)>), Error> { - let mut input_proofs = - Self::select_proofs(amount, proofs, active_keyset_ids, keyset_fees, include_fees)?; + let mut input_proofs = Self::select_proofs( + amount, + proofs, + active_keyset_ids, + fees_and_keyset_amounts, + include_fees, + )?; let mut exchange = None; // How much amounts do we have selected in our proof sets? @@ -211,9 +217,9 @@ impl Wallet { input_proofs.sort_by(|a, b| a.amount.cmp(&b.amount)); if let Some(proof_to_exchange) = input_proofs.pop() { - let fee_ppk = keyset_fees + let fee_ppk = fees_and_keyset_amounts .get(&proof_to_exchange.keyset_id) - .cloned() + .map(|fee_and_amounts| fee_and_amounts.fee()) .unwrap_or_default() .into(); @@ -239,7 +245,7 @@ impl Wallet { amount: Amount, proofs: Proofs, active_keyset_ids: &Vec, - keyset_fees: &HashMap, + fees_and_keyset_amounts: &KeysetFeeAndAmounts, include_fees: bool, ) -> Result { tracing::debug!( @@ -256,9 +262,6 @@ impl Wallet { let mut proofs = proofs; proofs.sort_by(|a, b| a.cmp(b).reverse()); - // Split the amount into optimal amounts - let optimal_amounts = amount.split(); - // Track selected proofs and remaining amounts (include all inactive proofs first) let mut selected_proofs: HashSet = proofs .iter() @@ -295,10 +298,13 @@ impl Wallet { }; // Select proofs with the optimal amounts - for optimal_amount in optimal_amounts { - if !select_proof(&proofs, optimal_amount, true) { - // Add the remaining amount to the remaining amounts because proof with the optimal amount was not found - remaining_amounts.push(optimal_amount); + for (_, fee_and_amounts) in fees_and_keyset_amounts.iter() { + // Split the amount into optimal amounts + for optimal_amount in amount.split(fee_and_amounts) { + if !select_proof(&proofs, optimal_amount, true) { + // Add the remaining amount to the remaining amounts because proof with the optimal amount was not found + remaining_amounts.push(optimal_amount); + } } } @@ -311,7 +317,7 @@ impl Wallet { proofs, selected_proofs.into_iter().collect(), active_keyset_ids, - keyset_fees, + fees_and_keyset_amounts, ); } else { return Ok(selected_proofs.into_iter().collect()); @@ -373,7 +379,7 @@ impl Wallet { proofs, selected_proofs, active_keyset_ids, - keyset_fees, + fees_and_keyset_amounts, ); } @@ -429,11 +435,17 @@ impl Wallet { proofs: Proofs, mut selected_proofs: Proofs, active_keyset_ids: &Vec, - keyset_fees: &HashMap, + fees_and_keyset_amounts: &KeysetFeeAndAmounts, ) -> Result { tracing::debug!("Including fees"); - let fee = - calculate_fee(&selected_proofs.count_by_keyset(), keyset_fees).unwrap_or_default(); + let fee = calculate_fee( + &selected_proofs.count_by_keyset(), + &fees_and_keyset_amounts + .iter() + .map(|(key, values)| (*key, values.fee())) + .collect(), + ) + .unwrap_or_default(); let net_amount = selected_proofs.total_amount()? - fee; tracing::debug!( "Net amount={}, fee={}, total amount={}", @@ -503,17 +515,40 @@ mod tests { #[test] fn test_select_proofs_empty() { + let active_id = id(); + let mut keyset_fee_and_amounts = HashMap::new(); + keyset_fee_and_amounts.insert( + active_id, + (0, (0..32).map(|x| 2u64.pow(x)).collect::>()).into(), + ); let proofs = vec![]; - let selected_proofs = - Wallet::select_proofs(0.into(), proofs, &vec![id()], &HashMap::new(), false).unwrap(); + let selected_proofs = Wallet::select_proofs( + 0.into(), + proofs, + &vec![active_id], + &keyset_fee_and_amounts, + false, + ) + .unwrap(); assert_eq!(selected_proofs.len(), 0); } #[test] fn test_select_proofs_insufficient() { + let active_id = id(); + let mut keyset_fee_and_amounts = HashMap::new(); + keyset_fee_and_amounts.insert( + active_id, + (0, (0..32).map(|x| 2u64.pow(x)).collect::>()).into(), + ); let proofs = vec![proof(1), proof(2), proof(4)]; - let selected_proofs = - Wallet::select_proofs(8.into(), proofs, &vec![id()], &HashMap::new(), false); + let selected_proofs = Wallet::select_proofs( + 8.into(), + proofs, + &vec![active_id], + &keyset_fee_and_amounts, + false, + ); assert!(selected_proofs.is_err()); } @@ -528,8 +563,22 @@ mod tests { proof(32), proof(64), ]; - let mut selected_proofs = - Wallet::select_proofs(77.into(), proofs, &vec![id()], &HashMap::new(), false).unwrap(); + + let active_id = id(); + let mut keyset_fee_and_amounts = HashMap::new(); + keyset_fee_and_amounts.insert( + active_id, + (0, (0..32).map(|x| 2u64.pow(x)).collect::>()).into(), + ); + + let mut selected_proofs = Wallet::select_proofs( + 77.into(), + proofs, + &vec![active_id], + &keyset_fee_and_amounts, + false, + ) + .unwrap(); selected_proofs.sort(); assert_eq!(selected_proofs.len(), 4); assert_eq!(selected_proofs[0].amount, 1.into()); @@ -540,9 +589,21 @@ mod tests { #[test] fn test_select_proofs_over() { + let active_id = id(); + let mut keyset_fee_and_amounts = HashMap::new(); + keyset_fee_and_amounts.insert( + active_id, + (0, (0..32).map(|x| 2u64.pow(x)).collect::>()).into(), + ); let proofs = vec![proof(1), proof(2), proof(4), proof(8), proof(32), proof(64)]; - let selected_proofs = - Wallet::select_proofs(31.into(), proofs, &vec![id()], &HashMap::new(), false).unwrap(); + let selected_proofs = Wallet::select_proofs( + 31.into(), + proofs, + &vec![active_id], + &keyset_fee_and_amounts, + false, + ) + .unwrap(); assert_eq!(selected_proofs.len(), 1); assert_eq!(selected_proofs[0].amount, 32.into()); } @@ -550,8 +611,21 @@ mod tests { #[test] fn test_select_proofs_smaller_over() { let proofs = vec![proof(8), proof(16), proof(32)]; - let selected_proofs = - Wallet::select_proofs(23.into(), proofs, &vec![id()], &HashMap::new(), false).unwrap(); + let active_id = id(); + let mut keyset_fee_and_amounts = HashMap::new(); + keyset_fee_and_amounts.insert( + active_id, + (0, (0..32).map(|x| 2u64.pow(x)).collect::>()).into(), + ); + + let selected_proofs = Wallet::select_proofs( + 23.into(), + proofs, + &vec![active_id], + &keyset_fee_and_amounts, + false, + ) + .unwrap(); assert_eq!(selected_proofs.len(), 2); assert_eq!(selected_proofs[0].amount, 16.into()); assert_eq!(selected_proofs[1].amount, 8.into()); @@ -559,10 +633,21 @@ mod tests { #[test] fn test_select_proofs_many_ones() { + let active_id = id(); + let mut fee_and_keyset_amounts = HashMap::new(); + fee_and_keyset_amounts.insert( + active_id, + (0, (0..32).map(|x| 2u64.pow(x)).collect::>()).into(), + ); let proofs = (0..1024).map(|_| proof(1)).collect::>(); - let selected_proofs = - Wallet::select_proofs(1024.into(), proofs, &vec![id()], &HashMap::new(), false) - .unwrap(); + let selected_proofs = Wallet::select_proofs( + 1024.into(), + proofs, + &vec![active_id], + &fee_and_keyset_amounts, + false, + ) + .unwrap(); assert_eq!(selected_proofs.len(), 1024); selected_proofs .iter() @@ -571,10 +656,21 @@ mod tests { #[test] fn test_select_proof_change() { + let active_id = id(); + let mut keyset_fee_and_amounts = HashMap::new(); + keyset_fee_and_amounts.insert( + active_id, + (0, (0..32).map(|x| 2u64.pow(x)).collect::>()).into(), + ); let proofs = vec![proof(64), proof(4), proof(32)]; - let (selected_proofs, exchange) = - Wallet::select_exact_proofs(97.into(), proofs, &vec![id()], &HashMap::new(), false) - .unwrap(); + let (selected_proofs, exchange) = Wallet::select_exact_proofs( + 97.into(), + proofs, + &vec![active_id], + &keyset_fee_and_amounts, + false, + ) + .unwrap(); assert!(exchange.is_some()); let (proof_to_exchange, amount) = exchange.unwrap(); @@ -585,14 +681,20 @@ mod tests { #[test] fn test_select_proofs_huge_proofs() { + let active_id = id(); + let mut keyset_fee_and_amounts = HashMap::new(); + keyset_fee_and_amounts.insert( + active_id, + (0, (0..32).map(|x| 2u64.pow(x)).collect::>()).into(), + ); let proofs = (0..32) .flat_map(|i| (0..5).map(|_| proof(1 << i)).collect::>()) .collect::>(); let mut selected_proofs = Wallet::select_proofs( ((1u64 << 32) - 1).into(), proofs, - &vec![id()], - &HashMap::new(), + &vec![active_id], + &keyset_fee_and_amounts, false, ) .unwrap(); @@ -608,10 +710,16 @@ mod tests { #[test] fn test_select_proofs_with_fees() { let proofs = vec![proof(64), proof(4), proof(32)]; - let mut keyset_fees = HashMap::new(); - keyset_fees.insert(id(), 100); - let selected_proofs = - Wallet::select_proofs(10.into(), proofs, &vec![id()], &keyset_fees, false).unwrap(); + let mut keyset_fee_and_amounts = HashMap::new(); + keyset_fee_and_amounts.insert(id(), (100, (0..32).map(|x| 2u64.pow(x)).collect()).into()); + let selected_proofs = Wallet::select_proofs( + 10.into(), + proofs, + &vec![id()], + &keyset_fee_and_amounts, + false, + ) + .unwrap(); assert_eq!(selected_proofs.len(), 1); assert_eq!(selected_proofs[0].amount, 32.into()); } diff --git a/crates/cdk/src/wallet/send.rs b/crates/cdk/src/wallet/send.rs index 0bab22d7f..0f41f8e96 100644 --- a/crates/cdk/src/wallet/send.rs +++ b/crates/cdk/src/wallet/send.rs @@ -39,7 +39,7 @@ impl Wallet { } // Get keyset fees from localstore - let keyset_fees = self.get_keyset_fees().await?; + let keyset_fees = self.get_keyset_fees_and_amounts().await?; // Get available proofs matching conditions let mut available_proofs = self @@ -129,11 +129,13 @@ impl Wallet { force_swap: bool, ) -> Result { // Split amount with fee if necessary + let active_keyset_id = self.get_active_keyset().await?.id; + let fee_and_amounts = self + .get_keyset_fees_and_amounts_by_id(active_keyset_id) + .await?; let (send_amounts, send_fee) = if opts.include_fee { - let active_keyset_id = self.get_active_keyset().await?.id; - let keyset_fee_ppk = self.get_keyset_fees_by_id(active_keyset_id).await?; - tracing::debug!("Keyset fee per proof: {:?}", keyset_fee_ppk); - let send_split = amount.split_with_fee(keyset_fee_ppk)?; + tracing::debug!("Keyset fee per proof: {:?}", fee_and_amounts.fee()); + let send_split = amount.split_with_fee(&fee_and_amounts)?; let send_fee = self .get_proofs_fee_by_count( vec![(active_keyset_id, send_split.len() as u64)] @@ -143,7 +145,7 @@ impl Wallet { .await?; (send_split, send_fee) } else { - let send_split = amount.split(); + let send_split = amount.split(&fee_and_amounts); let send_fee = Amount::ZERO; (send_split, send_fee) }; @@ -265,7 +267,10 @@ impl PreparedSend { tracing::debug!("Active keyset ID: {:?}", active_keyset_id); // Get keyset fees - let keyset_fee_ppk = self.wallet.get_keyset_fees_by_id(active_keyset_id).await?; + let keyset_fee_ppk = self + .wallet + .get_keyset_fees_and_amounts_by_id(active_keyset_id) + .await?; tracing::debug!("Keyset fees: {:?}", keyset_fee_ppk); // Calculate total send amount diff --git a/crates/cdk/src/wallet/swap.rs b/crates/cdk/src/wallet/swap.rs index 8adfef6cc..6e52eeb7d 100644 --- a/crates/cdk/src/wallet/swap.rs +++ b/crates/cdk/src/wallet/swap.rs @@ -40,6 +40,9 @@ impl Wallet { let swap_response = self.client.post_swap(pre_swap.swap_request).await?; let active_keyset_id = pre_swap.pre_mint_secrets.keyset_id; + let fee_and_amounts = self + .get_keyset_fees_and_amounts_by_id(active_keyset_id) + .await?; let active_keys = self .localstore @@ -74,7 +77,8 @@ impl Wallet { let mut proofs_to_send = Proofs::new(); let mut proofs_to_keep = Proofs::new(); - let mut amount_split = amount.split_targeted(&amount_split_target)?; + let mut amount_split = + amount.split_targeted(&amount_split_target, &fee_and_amounts)?; for proof in all_proofs { if let Some(idx) = amount_split.iter().position(|&a| a == proof.amount) @@ -172,7 +176,7 @@ impl Wallet { .map(|k| k.id) .collect(); - let keyset_fees = self.get_keyset_fees().await?; + let keyset_fees = self.get_keyset_fees_and_amounts().await?; let proofs = Wallet::select_proofs( amount, available_proofs, @@ -224,11 +228,15 @@ impl Wallet { .checked_sub(total_to_subtract) .ok_or(Error::InsufficientFunds)?; + let fee_and_amounts = self + .get_keyset_fees_and_amounts_by_id(active_keyset_id) + .await?; + let (send_amount, change_amount) = match include_fees { true => { let split_count = amount .unwrap_or(Amount::ZERO) - .split_targeted(&SplitTarget::default()) + .split_targeted(&SplitTarget::default(), &fee_and_amounts) .unwrap() .len(); @@ -251,7 +259,10 @@ impl Wallet { // If a non None split target is passed use that // else use state refill let change_split_target = match amount_split_target { - SplitTarget::None => self.determine_split_target_values(change_amount).await?, + SplitTarget::None => { + self.determine_split_target_values(change_amount, &fee_and_amounts) + .await? + } s => s, }; @@ -261,15 +272,19 @@ impl Wallet { let total_secrets_needed = match spending_conditions { Some(_) => { // For spending conditions, we only need to count change secrets - change_amount.split_targeted(&change_split_target)?.len() as u32 + change_amount + .split_targeted(&change_split_target, &fee_and_amounts)? + .len() as u32 } None => { // For no spending conditions, count both send and change secrets let send_count = send_amount .unwrap_or(Amount::ZERO) - .split_targeted(&SplitTarget::default())? + .split_targeted(&SplitTarget::default(), &fee_and_amounts)? + .len() as u32; + let change_count = change_amount + .split_targeted(&change_split_target, &fee_and_amounts)? .len() as u32; - let change_count = change_amount.split_targeted(&change_split_target)?.len() as u32; send_count + change_count } }; @@ -302,6 +317,7 @@ impl Wallet { &self.seed, change_amount, &change_split_target, + &fee_and_amounts, )?; derived_secret_count = change_premint_secrets.len(); @@ -312,6 +328,7 @@ impl Wallet { send_amount.unwrap_or(Amount::ZERO), &SplitTarget::default(), &conditions, + &fee_and_amounts, )?, change_premint_secrets, ) @@ -323,6 +340,7 @@ impl Wallet { &self.seed, send_amount.unwrap_or(Amount::ZERO), &SplitTarget::default(), + &fee_and_amounts, )?; count += premint_secrets.len() as u32; @@ -333,6 +351,7 @@ impl Wallet { &self.seed, change_amount, &change_split_target, + &fee_and_amounts, )?; derived_secret_count = change_premint_secrets.len() + premint_secrets.len(); From f41ce0a3fbc7690cc873e8585a01afa8df5b8692 Mon Sep 17 00:00:00 2001 From: asmo Date: Wed, 24 Sep 2025 15:56:51 +0200 Subject: [PATCH 182/321] optional client identity in grpc payment processor (#1084) * fix: update TLS configuration to handle missing client certificates gracefully --- .../cdk-payment-processor/src/proto/client.rs | 33 +++++++------------ 1 file changed, 12 insertions(+), 21 deletions(-) diff --git a/crates/cdk-payment-processor/src/proto/client.rs b/crates/cdk-payment-processor/src/proto/client.rs index d88876af0..bd6482c39 100644 --- a/crates/cdk-payment-processor/src/proto/client.rs +++ b/crates/cdk-payment-processor/src/proto/client.rs @@ -47,32 +47,23 @@ impl PaymentProcessorClient { // Check for client.pem let client_pem_path = tls_dir.join("client.pem"); - if !client_pem_path.exists() { - let err_msg = format!( - "Client certificate file not found: {}", - client_pem_path.display() - ); - tracing::error!("{}", err_msg); - return Err(anyhow!(err_msg)); - } // Check for client.key let client_key_path = tls_dir.join("client.key"); - if !client_key_path.exists() { - let err_msg = format!("Client key file not found: {}", client_key_path.display()); - tracing::error!("{}", err_msg); - return Err(anyhow!(err_msg)); - } - + // check for ca cert let server_root_ca_cert = std::fs::read_to_string(&ca_pem_path)?; let server_root_ca_cert = Certificate::from_pem(server_root_ca_cert); - let client_cert = std::fs::read_to_string(&client_pem_path)?; - let client_key = std::fs::read_to_string(&client_key_path)?; - let client_identity = Identity::from_pem(client_cert, client_key); - let tls = ClientTlsConfig::new() - .ca_certificate(server_root_ca_cert) - .identity(client_identity); - + let tls: ClientTlsConfig = match client_pem_path.exists() && client_key_path.exists() { + true => { + let client_cert = std::fs::read_to_string(&client_pem_path)?; + let client_key = std::fs::read_to_string(&client_key_path)?; + let client_identity = Identity::from_pem(client_cert, client_key); + ClientTlsConfig::new() + .ca_certificate(server_root_ca_cert) + .identity(client_identity) + } + false => ClientTlsConfig::new().ca_certificate(server_root_ca_cert), + }; Channel::from_shared(addr)? .tls_config(tls)? .connect() From e07a9c8e1eebd16b772775d2d305983b62ef7149 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Thu, 25 Sep 2025 08:31:57 +0100 Subject: [PATCH 183/321] feat(cdk): add WebSocket authentication support (#1116) * 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 --- crates/cashu/src/nuts/auth/nut21.rs | 4 ++ crates/cdk-axum/src/router_handlers.rs | 17 +++++- .../src/bin/start_fake_auth_mint.rs | 1 + crates/cdk-mintd/src/config.rs | 3 + crates/cdk-mintd/src/env_vars/auth.rs | 10 ++++ crates/cdk-mintd/src/lib.rs | 6 ++ .../src/wallet/mint_connector/http_client.rs | 2 +- crates/cdk/src/wallet/subscription/ws.rs | 57 ++++++++++++++++++- 8 files changed, 95 insertions(+), 5 deletions(-) diff --git a/crates/cashu/src/nuts/auth/nut21.rs b/crates/cashu/src/nuts/auth/nut21.rs index 6392bd4ae..7ecc798b6 100644 --- a/crates/cashu/src/nuts/auth/nut21.rs +++ b/crates/cashu/src/nuts/auth/nut21.rs @@ -161,6 +161,10 @@ pub enum RoutePath { /// Bolt12 Quote #[serde(rename = "/v1/melt/bolt12")] MeltBolt12, + + /// WebSocket + #[serde(rename = "/v1/ws")] + Ws, } /// Returns [`RoutePath`]s that match regex diff --git a/crates/cdk-axum/src/router_handlers.rs b/crates/cdk-axum/src/router_handlers.rs index 207f34c74..ab70e9772 100644 --- a/crates/cdk-axum/src/router_handlers.rs +++ b/crates/cdk-axum/src/router_handlers.rs @@ -219,10 +219,23 @@ pub(crate) async fn get_check_mint_bolt11_quote( #[instrument(skip_all)] pub(crate) async fn ws_handler( + #[cfg(feature = "auth")] auth: AuthHeader, State(state): State, ws: WebSocketUpgrade, -) -> impl IntoResponse { - ws.on_upgrade(|ws| main_websocket(ws, state)) +) -> Result { + #[cfg(feature = "auth")] + { + state + .mint + .verify_auth( + auth.into(), + &ProtectedEndpoint::new(Method::Get, RoutePath::Ws), + ) + .await + .map_err(into_response)?; + } + + Ok(ws.on_upgrade(|ws| main_websocket(ws, state))) } /// Mint tokens by paying a BOLT11 Lightning invoice. diff --git a/crates/cdk-integration-tests/src/bin/start_fake_auth_mint.rs b/crates/cdk-integration-tests/src/bin/start_fake_auth_mint.rs index 43e5e4a8e..7d7dc8e1a 100644 --- a/crates/cdk-integration-tests/src/bin/start_fake_auth_mint.rs +++ b/crates/cdk-integration-tests/src/bin/start_fake_auth_mint.rs @@ -85,6 +85,7 @@ async fn start_fake_auth_mint( swap: AuthType::Blind, restore: AuthType::Blind, check_proof_state: AuthType::Blind, + websocket_auth: AuthType::Blind, }); // Set description for the mint diff --git a/crates/cdk-mintd/src/config.rs b/crates/cdk-mintd/src/config.rs index fa5bc6ff3..a5b2ed9e3 100644 --- a/crates/cdk-mintd/src/config.rs +++ b/crates/cdk-mintd/src/config.rs @@ -457,6 +457,9 @@ pub struct Auth { pub restore: AuthType, #[serde(default)] pub check_proof_state: AuthType, + /// Enable WebSocket authentication support + #[serde(default = "default_blind")] + pub websocket_auth: AuthType, } fn default_blind() -> AuthType { diff --git a/crates/cdk-mintd/src/env_vars/auth.rs b/crates/cdk-mintd/src/env_vars/auth.rs index 62d325977..c80e64755 100644 --- a/crates/cdk-mintd/src/env_vars/auth.rs +++ b/crates/cdk-mintd/src/env_vars/auth.rs @@ -17,6 +17,10 @@ pub const ENV_AUTH_CHECK_MELT_QUOTE: &str = "CDK_MINTD_AUTH_CHECK_MELT_QUOTE"; pub const ENV_AUTH_SWAP: &str = "CDK_MINTD_AUTH_SWAP"; pub const ENV_AUTH_RESTORE: &str = "CDK_MINTD_AUTH_RESTORE"; pub const ENV_AUTH_CHECK_PROOF_STATE: &str = "CDK_MINTD_AUTH_CHECK_PROOF_STATE"; +pub const ENV_AUTH_WEBSOCKET: &str = "CDK_MINTD_AUTH_WEBSOCKET"; +pub const ENV_AUTH_WS_MINT_QUOTE: &str = "CDK_MINTD_AUTH_WS_MINT_QUOTE"; +pub const ENV_AUTH_WS_MELT_QUOTE: &str = "CDK_MINTD_AUTH_WS_MELT_QUOTE"; +pub const ENV_AUTH_WS_PROOF_STATE: &str = "CDK_MINTD_AUTH_WS_PROOF_STATE"; impl Auth { pub fn from_env(mut self) -> Self { @@ -94,6 +98,12 @@ impl Auth { } } + if let Ok(ws_auth_str) = env::var(ENV_AUTH_WEBSOCKET) { + if let Ok(auth_type) = ws_auth_str.parse() { + self.websocket_auth = auth_type; + } + } + self } } diff --git a/crates/cdk-mintd/src/lib.rs b/crates/cdk-mintd/src/lib.rs index 2a058e950..34ed48339 100644 --- a/crates/cdk-mintd/src/lib.rs +++ b/crates/cdk-mintd/src/lib.rs @@ -792,6 +792,12 @@ async fn setup_authentication( add_endpoint(state_protected_endpoint, &auth_settings.check_proof_state); } + // Ws endpoint + { + let ws_protected_endpoint = ProtectedEndpoint::new(Method::Get, RoutePath::Ws); + add_endpoint(ws_protected_endpoint, &auth_settings.websocket_auth); + } + mint_builder = mint_builder.with_auth( auth_localstore.clone(), auth_settings.openid_discovery, diff --git a/crates/cdk/src/wallet/mint_connector/http_client.rs b/crates/cdk/src/wallet/mint_connector/http_client.rs index c2f29bc96..1a954a724 100644 --- a/crates/cdk/src/wallet/mint_connector/http_client.rs +++ b/crates/cdk/src/wallet/mint_connector/http_client.rs @@ -71,7 +71,7 @@ where /// Get auth token for a protected endpoint #[cfg(feature = "auth")] #[instrument(skip(self))] - async fn get_auth_token( + pub async fn get_auth_token( &self, method: Method, path: RoutePath, diff --git a/crates/cdk/src/wallet/subscription/ws.rs b/crates/cdk/src/wallet/subscription/ws.rs index d39fe2381..f0204a901 100644 --- a/crates/cdk/src/wallet/subscription/ws.rs +++ b/crates/cdk/src/wallet/subscription/ws.rs @@ -4,9 +4,12 @@ use std::sync::Arc; use cdk_common::subscription::Params; use cdk_common::ws::{WsMessageOrResponse, WsMethodRequest, WsRequest, WsUnsubscribeRequest}; +#[cfg(feature = "auth")] +use cdk_common::{Method, RoutePath}; use futures::{SinkExt, StreamExt}; use tokio::sync::{mpsc, RwLock}; use tokio_tungstenite::connect_async; +use tokio_tungstenite::tungstenite::client::IntoClientRequest; use tokio_tungstenite::tungstenite::Message; use super::http::http_main; @@ -37,14 +40,64 @@ pub async fn ws_main( url.set_scheme("ws").expect("Could not set scheme"); } - let url = url.to_string(); + let request = match url.to_string().into_client_request() { + Ok(req) => req, + Err(err) => { + tracing::error!("Failed to create client request: {:?}", err); + // Fallback to HTTP client if we can't create the WebSocket request + return http_main( + std::iter::empty(), + http_client, + subscriptions, + new_subscription_recv, + on_drop, + wallet, + ) + .await; + } + }; let mut active_subscriptions = HashMap::>::new(); let mut failure_count = 0; loop { + let mut request_clone = request.clone(); + #[cfg(feature = "auth")] + { + let auth_wallet = http_client.get_auth_wallet().await; + let token = match auth_wallet.as_ref() { + Some(auth_wallet) => { + let endpoint = cdk_common::ProtectedEndpoint::new(Method::Get, RoutePath::Ws); + match auth_wallet.get_auth_for_request(&endpoint).await { + Ok(token) => token, + Err(err) => { + tracing::warn!("Failed to get auth token: {:?}", err); + None + } + } + } + None => None, + }; + + if let Some(auth_token) = token { + let header_key = match &auth_token { + cdk_common::AuthToken::ClearAuth(_) => "Clear-auth", + cdk_common::AuthToken::BlindAuth(_) => "Blind-auth", + }; + + match auth_token.to_string().parse() { + Ok(header_value) => { + request_clone.headers_mut().insert(header_key, header_value); + } + Err(err) => { + tracing::warn!("Failed to parse auth token as header value: {:?}", err); + } + } + } + } + tracing::debug!("Connecting to {}", url); - let ws_stream = match connect_async(&url).await { + let ws_stream = match connect_async(request_clone.clone()).await { Ok((ws_stream, _)) => ws_stream, Err(err) => { failure_count += 1; From 9d4559a47af4b512a812adca6d1b56d00c66d657 Mon Sep 17 00:00:00 2001 From: gudnuf <108303703+gudnuf@users.noreply.github.com> Date: Thu, 25 Sep 2025 00:57:41 -0700 Subject: [PATCH 184/321] fix: only settle same unit quote internally (#1115) --- crates/cdk/src/mint/mod.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/crates/cdk/src/mint/mod.rs b/crates/cdk/src/mint/mod.rs index 45c11c399..3f99691cf 100644 --- a/crates/cdk/src/mint/mod.rs +++ b/crates/cdk/src/mint/mod.rs @@ -887,9 +887,9 @@ impl Mint { .get_mint_quote_by_request(&melt_quote.request.to_string()) .await { - Ok(Some(mint_quote)) => mint_quote, - // Not an internal melt -> mint - Ok(None) => return Ok(None), + Ok(Some(mint_quote)) if mint_quote.unit == melt_quote.unit => mint_quote, + // Not an internal melt -> mint or unit mismatch + Ok(_) => return Ok(None), Err(err) => { tracing::debug!("Error attempting to get mint quote: {}", err); return Err(Error::Internal); From caba6978e750946d5803f9a05e2edbdc7869dfd2 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Thu, 25 Sep 2025 16:18:37 +0100 Subject: [PATCH 185/321] refactor(cdk): simplify mint addition in MultiMintWallet (#1121) Remove unnecessary mint info fetching and keyset refresh during mint addition, and improve error propagation in token restoration flow --- crates/cdk/src/wallet/multi_mint_wallet.rs | 11 +---------- 1 file changed, 1 insertion(+), 10 deletions(-) diff --git a/crates/cdk/src/wallet/multi_mint_wallet.rs b/crates/cdk/src/wallet/multi_mint_wallet.rs index 6906f04db..ad34a4592 100644 --- a/crates/cdk/src/wallet/multi_mint_wallet.rs +++ b/crates/cdk/src/wallet/multi_mint_wallet.rs @@ -205,9 +205,6 @@ impl MultiMintWallet { )? }; - wallet.fetch_mint_info().await?; - wallet.refresh_keysets().await?; - let mut wallets = self.wallets.write().await; wallets.insert(mint_url, wallet); @@ -242,13 +239,7 @@ impl MultiMintWallet { if mint_has_proofs_for_unit { // Add mint to the MultiMintWallet if not already present if !self.has_mint(&mint_url).await { - if let Err(err) = self.add_mint(mint_url.clone(), None).await { - tracing::error!( - "Could not add {} to wallet {}.", - mint_url, - err.to_string() - ); - } + self.add_mint(mint_url.clone(), None).await? } } } From 500d162f6743251f2808ec6f73517ab03269b700 Mon Sep 17 00:00:00 2001 From: gudnuf <108303703+gudnuf@users.noreply.github.com> Date: Thu, 25 Sep 2025 10:57:54 -0700 Subject: [PATCH 186/321] fix: handle fiat melt amount conversions (#1109) * fix: handle fiat melt amount conversions * feat: add check that processor returns quote unit --------- Co-authored-by: thesimplekid --- crates/cdk-fake-wallet/src/lib.rs | 183 ++++++++++++++++++++++++++++-- crates/cdk/src/mint/melt.rs | 58 ++++++---- 2 files changed, 205 insertions(+), 36 deletions(-) diff --git a/crates/cdk-fake-wallet/src/lib.rs b/crates/cdk-fake-wallet/src/lib.rs index 58630d143..80e221ea4 100644 --- a/crates/cdk-fake-wallet/src/lib.rs +++ b/crates/cdk-fake-wallet/src/lib.rs @@ -18,6 +18,7 @@ use std::collections::{HashMap, HashSet, VecDeque}; use std::pin::Pin; use std::sync::atomic::{AtomicBool, Ordering}; use std::sync::Arc; +use std::time::{Duration, Instant}; use async_trait::async_trait; use bitcoin::hashes::{sha256, Hash}; @@ -50,6 +51,139 @@ pub mod error; /// Default maximum size for the secondary repayment queue const DEFAULT_REPAY_QUEUE_MAX_SIZE: usize = 100; +/// Cache duration for exchange rate (5 minutes) +const RATE_CACHE_DURATION: Duration = Duration::from_secs(300); + +/// Mempool.space prices API response structure +#[derive(Debug, Deserialize)] +struct MempoolPricesResponse { + #[serde(rename = "USD")] + usd: f64, + #[serde(rename = "EUR")] + eur: f64, +} + +/// Exchange rate cache with built-in fallback rates +#[derive(Debug, Clone)] +struct ExchangeRateCache { + rates: Arc>>, +} + +impl ExchangeRateCache { + fn new() -> Self { + Self { + rates: Arc::new(Mutex::new(None)), + } + } + + /// Get current BTC rate for the specified currency with caching and fallback + async fn get_btc_rate(&self, currency: &CurrencyUnit) -> Result { + // Return cached rate if still valid + { + let cached_rates = self.rates.lock().await; + if let Some((rates, timestamp)) = &*cached_rates { + if timestamp.elapsed() < RATE_CACHE_DURATION { + return Self::rate_for_currency(rates, currency); + } + } + } + + // Try to fetch fresh rates, fallback on error + match self.fetch_fresh_rate(currency).await { + Ok(rate) => Ok(rate), + Err(e) => { + tracing::warn!( + "Failed to fetch exchange rates, using fallback for {:?}: {}", + currency, + e + ); + Self::fallback_rate(currency) + } + } + } + + /// Fetch fresh rate and update cache + async fn fetch_fresh_rate(&self, currency: &CurrencyUnit) -> Result { + let url = "https://mempool.space/api/v1/prices"; + let response = reqwest::get(url) + .await + .map_err(|_| Error::UnknownInvoiceAmount)? + .json::() + .await + .map_err(|_| Error::UnknownInvoiceAmount)?; + + let rate = Self::rate_for_currency(&response, currency)?; + *self.rates.lock().await = Some((response, Instant::now())); + Ok(rate) + } + + fn rate_for_currency( + rates: &MempoolPricesResponse, + currency: &CurrencyUnit, + ) -> Result { + match currency { + CurrencyUnit::Usd => Ok(rates.usd), + CurrencyUnit::Eur => Ok(rates.eur), + _ => Err(Error::UnknownInvoiceAmount), + } + } + + fn fallback_rate(currency: &CurrencyUnit) -> Result { + match currency { + CurrencyUnit::Usd => Ok(110_000.0), // $110k per BTC + CurrencyUnit::Eur => Ok(95_000.0), // €95k per BTC + _ => Err(Error::UnknownInvoiceAmount), + } + } +} + +async fn convert_currency_amount( + amount: u64, + from_unit: &CurrencyUnit, + target_unit: &CurrencyUnit, + rate_cache: &ExchangeRateCache, +) -> Result { + use CurrencyUnit::*; + + // Try basic unit conversion first (handles SAT/MSAT and same-unit conversions) + if let Ok(converted) = to_unit(amount, from_unit, target_unit) { + return Ok(converted); + } + + // Handle fiat <-> bitcoin conversions that require exchange rates + match (from_unit, target_unit) { + // Fiat to Bitcoin conversions + (Usd | Eur, Sat) => { + let rate = rate_cache.get_btc_rate(from_unit).await?; + let fiat_amount = amount as f64 / 100.0; // cents to dollars/euros + Ok(Amount::from( + (fiat_amount / rate * 100_000_000.0).round() as u64 + )) // to sats + } + (Usd | Eur, Msat) => { + let rate = rate_cache.get_btc_rate(from_unit).await?; + let fiat_amount = amount as f64 / 100.0; // cents to dollars/euros + Ok(Amount::from( + (fiat_amount / rate * 100_000_000_000.0).round() as u64, + )) // to msats + } + + // Bitcoin to fiat conversions + (Sat, Usd | Eur) => { + let rate = rate_cache.get_btc_rate(target_unit).await?; + let btc_amount = amount as f64 / 100_000_000.0; // sats to BTC + Ok(Amount::from((btc_amount * rate * 100.0).round() as u64)) // to cents + } + (Msat, Usd | Eur) => { + let rate = rate_cache.get_btc_rate(target_unit).await?; + let btc_amount = amount as f64 / 100_000_000_000.0; // msats to BTC + Ok(Amount::from((btc_amount * rate * 100.0).round() as u64)) // to cents + } + + _ => Err(Error::UnknownInvoiceAmount), // Unsupported conversion + } +} + /// Secondary repayment queue manager for any-amount invoices #[derive(Debug, Clone)] struct SecondaryRepaymentQueue { @@ -201,6 +335,7 @@ pub struct FakeWallet { incoming_payments: Arc>>>, unit: CurrencyUnit, secondary_repayment_queue: SecondaryRepaymentQueue, + exchange_rate_cache: ExchangeRateCache, } impl FakeWallet { @@ -249,6 +384,7 @@ impl FakeWallet { incoming_payments, unit, secondary_repayment_queue, + exchange_rate_cache: ExchangeRateCache::new(), } } } @@ -376,7 +512,13 @@ impl MintPayment for FakeWallet { } }; - let amount = to_unit(amount_msat, &CurrencyUnit::Msat, unit)?; + let amount = convert_currency_amount( + amount_msat, + &CurrencyUnit::Msat, + unit, + &self.exchange_rate_cache, + ) + .await?; let relative_fee_reserve = (self.fee_reserve.percent_fee_reserve * u64::from(amount) as f32) as u64; @@ -441,7 +583,13 @@ impl MintPayment for FakeWallet { .ok_or(Error::UnknownInvoiceAmount)? }; - let total_spent = to_unit(amount_msat, &CurrencyUnit::Msat, unit)?; + let total_spent = convert_currency_amount( + amount_msat, + &CurrencyUnit::Msat, + unit, + &self.exchange_rate_cache, + ) + .await?; Ok(MakePaymentResponse { payment_proof: Some("".to_string()), @@ -466,7 +614,13 @@ impl MintPayment for FakeWallet { } }; - let total_spent = to_unit(amount_msat, &CurrencyUnit::Msat, unit)?; + let total_spent = convert_currency_amount( + amount_msat, + &CurrencyUnit::Msat, + unit, + &self.exchange_rate_cache, + ) + .await?; Ok(MakePaymentResponse { payment_proof: Some("".to_string()), @@ -499,7 +653,13 @@ impl MintPayment for FakeWallet { let offer_builder = match amount { Some(amount) => { - let amount_msat = to_unit(amount, unit, &CurrencyUnit::Msat)?; + let amount_msat = convert_currency_amount( + u64::from(amount), + unit, + &CurrencyUnit::Msat, + &self.exchange_rate_cache, + ) + .await?; offer_builder.amount_msats(amount_msat.into()) } None => offer_builder, @@ -519,13 +679,14 @@ impl MintPayment for FakeWallet { let amount = bolt11_options.amount; let expiry = bolt11_options.unix_expiry; - // For fake invoices, always use msats regardless of unit - let amount_msat = if unit == &CurrencyUnit::Sat { - u64::from(amount) * 1000 - } else { - // If unit is Msat, use as-is - u64::from(amount) - }; + let amount_msat = convert_currency_amount( + u64::from(amount), + unit, + &CurrencyUnit::Msat, + &self.exchange_rate_cache, + ) + .await? + .into(); let invoice = create_fake_invoice(amount_msat, description.clone()); let payment_hash = invoice.payment_hash(); diff --git a/crates/cdk/src/mint/melt.rs b/crates/cdk/src/mint/melt.rs index a226a0324..f237a7005 100644 --- a/crates/cdk/src/mint/melt.rs +++ b/crates/cdk/src/mint/melt.rs @@ -142,19 +142,6 @@ impl Mint { .. } = melt_request; - let amount_msats = melt_request.amount_msat()?; - - let amount_quote_unit = to_unit(amount_msats, &CurrencyUnit::Msat, unit)?; - - self.check_melt_request_acceptable( - amount_quote_unit, - unit.clone(), - PaymentMethod::Bolt11, - request.to_string(), - *options, - ) - .await?; - let ln = self .payment_processors .get(&PaymentProcessorKey::new( @@ -196,6 +183,20 @@ impl Mint { Error::UnsupportedUnit })?; + if &payment_quote.unit != unit { + return Err(Error::UnitMismatch); + } + + // Validate using processor quote amount for currency conversion + self.check_melt_request_acceptable( + payment_quote.amount, + unit.clone(), + PaymentMethod::Bolt11, + request.to_string(), + *options, + ) + .await?; + let melt_ttl = self.quote_ttl().await?.melt_ttl; let quote = MeltQuote::new( @@ -215,7 +216,7 @@ impl Mint { "New {} melt quote {} for {} {} with request id {:?}", quote.payment_method, quote.id, - amount_quote_unit, + payment_quote.amount, unit, payment_quote.request_lookup_id ); @@ -251,15 +252,6 @@ impl Mint { None => amount_for_offer(&offer, unit).map_err(|_| Error::UnsupportedUnit)?, }; - self.check_melt_request_acceptable( - amount, - unit.clone(), - PaymentMethod::Bolt12, - request.clone(), - *options, - ) - .await?; - let ln = self .payment_processors .get(&PaymentProcessorKey::new( @@ -297,6 +289,20 @@ impl Mint { Error::UnsupportedUnit })?; + if &payment_quote.unit != unit { + return Err(Error::UnitMismatch); + } + + // Validate using processor quote amount for currency conversion + self.check_melt_request_acceptable( + payment_quote.amount, + unit.clone(), + PaymentMethod::Bolt12, + request.clone(), + *options, + ) + .await?; + let payment_request = MeltPaymentRequest::Bolt12 { offer: Box::new(offer), }; @@ -506,8 +512,6 @@ impl Mint { unit: input_unit, } = input_verification; - ensure_cdk!(input_unit.is_some(), Error::UnsupportedUnit); - let mut proof_writer = ProofWriter::new(self.localstore.clone(), self.pubsub_manager.clone()); @@ -524,6 +528,10 @@ impl Mint { .update_melt_quote_state(melt_request.quote(), MeltQuoteState::Pending, None) .await?; + if input_unit != Some(quote.unit.clone()) { + return Err(Error::UnitMismatch); + } + match state { MeltQuoteState::Unpaid | MeltQuoteState::Failed => Ok(()), MeltQuoteState::Pending => Err(Error::PendingQuote), From f48660f344d5c5e6a6022daa8a7fe01d8e98304a Mon Sep 17 00:00:00 2001 From: David Caseria Date: Thu, 25 Sep 2025 13:59:01 -0400 Subject: [PATCH 187/321] Make Uniffi Records Codable in Swift (#1125) --- crates/cdk-ffi/uniffi.toml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/crates/cdk-ffi/uniffi.toml b/crates/cdk-ffi/uniffi.toml index 7b95d596a..31cb7cb44 100644 --- a/crates/cdk-ffi/uniffi.toml +++ b/crates/cdk-ffi/uniffi.toml @@ -8,3 +8,5 @@ cdylib_name = "cdk_ffi" [bindings.swift] module_name = "CashuDevKit" cdylib_name = "cdk_ffi" +generate_codable_conformance = true +generate_immutable_records = true From 05acb914feedbae2f0b5f8b2b4c5361339e17297 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Fri, 26 Sep 2025 14:37:43 +0100 Subject: [PATCH 188/321] feat: remove delete fns for quotes (#1122) --- crates/cdk-common/src/database/mint/mod.rs | 6 ++-- crates/cdk-sql-common/src/mint/mod.rs | 22 --------------- crates/cdk/src/mint/issue/mod.rs | 33 ---------------------- 3 files changed, 2 insertions(+), 59 deletions(-) diff --git a/crates/cdk-common/src/database/mint/mod.rs b/crates/cdk-common/src/database/mint/mod.rs index 922c9d29d..9c08734c3 100644 --- a/crates/cdk-common/src/database/mint/mod.rs +++ b/crates/cdk-common/src/database/mint/mod.rs @@ -170,8 +170,7 @@ pub trait QuotesTransaction<'a> { quote_id: &QuoteId, amount_issued: Amount, ) -> Result; - /// Remove [`MintMintQuote`] - async fn remove_mint_quote(&mut self, quote_id: &QuoteId) -> Result<(), Self::Err>; + /// Get [`mint::MeltQuote`] and lock it for update in this transaction async fn get_melt_quote( &mut self, @@ -196,8 +195,7 @@ pub trait QuotesTransaction<'a> { new_state: MeltQuoteState, payment_proof: Option, ) -> Result<(MeltQuoteState, mint::MeltQuote), Self::Err>; - /// Remove [`mint::MeltQuote`] - async fn remove_melt_quote(&mut self, quote_id: &QuoteId) -> Result<(), Self::Err>; + /// Get all [`MintMintQuote`]s and lock it for update in this transaction async fn get_mint_quote_by_request( &mut self, diff --git a/crates/cdk-sql-common/src/mint/mod.rs b/crates/cdk-sql-common/src/mint/mod.rs index 3bd0c4bfc..b3bef8d88 100644 --- a/crates/cdk-sql-common/src/mint/mod.rs +++ b/crates/cdk-sql-common/src/mint/mod.rs @@ -878,14 +878,6 @@ VALUES (:quote_id, :amount, :timestamp); Ok(()) } - async fn remove_mint_quote(&mut self, quote_id: &QuoteId) -> Result<(), Self::Err> { - query(r#"DELETE FROM mint_quote WHERE id=:id"#)? - .bind("id", quote_id.to_string()) - .execute(&self.inner) - .await?; - Ok(()) - } - async fn add_melt_quote(&mut self, quote: mint::MeltQuote) -> Result<(), Self::Err> { // Now insert the new quote query( @@ -1020,20 +1012,6 @@ VALUES (:quote_id, :amount, :timestamp); Ok((old_state, quote)) } - async fn remove_melt_quote(&mut self, quote_id: &QuoteId) -> Result<(), Self::Err> { - query( - r#" - DELETE FROM melt_quote - WHERE id=:id - "#, - )? - .bind("id", quote_id.to_string()) - .execute(&self.inner) - .await?; - - Ok(()) - } - async fn get_mint_quote(&mut self, quote_id: &QuoteId) -> Result, Self::Err> { let payments = get_mint_quote_payments(&self.inner, quote_id).await?; let issuance = get_mint_quote_issuance(&self.inner, quote_id).await?; diff --git a/crates/cdk/src/mint/issue/mod.rs b/crates/cdk/src/mint/issue/mod.rs index 45c0268e3..8104b2e3a 100644 --- a/crates/cdk/src/mint/issue/mod.rs +++ b/crates/cdk/src/mint/issue/mod.rs @@ -376,39 +376,6 @@ impl Mint { result } - /// Removes a mint quote from the database - /// - /// # Arguments - /// * `quote_id` - The UUID of the quote to remove - /// - /// # Returns - /// * `Ok(())` if removal was successful - /// * `Error` if the quote doesn't exist or removal fails - #[instrument(skip_all)] - pub async fn remove_mint_quote(&self, quote_id: &QuoteId) -> Result<(), Error> { - #[cfg(feature = "prometheus")] - METRICS.inc_in_flight_requests("remove_mint_quote"); - - let result = async { - let mut tx = self.localstore.begin_transaction().await?; - tx.remove_mint_quote(quote_id).await?; - tx.commit().await?; - Ok(()) - } - .await; - - #[cfg(feature = "prometheus")] - { - METRICS.dec_in_flight_requests("remove_mint_quote"); - METRICS.record_mint_operation("remove_mint_quote", result.is_ok()); - if result.is_err() { - METRICS.record_error(); - } - } - - result - } - /// Marks a mint quote as paid based on the payment request ID /// /// Looks up the mint quote by the payment request ID and marks it as paid From 676463f730c2da179b4d73497d9f7c046b44f4a9 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Fri, 26 Sep 2025 14:43:34 +0100 Subject: [PATCH 189/321] Revert "feat: remove redis cache (#1096)" (#1129) This reverts commit be7c83689d2444ba9028e39c9b4a0416eec13a99. --- .github/workflows/ci.yml | 7 +- crates/cdk-axum/Cargo.toml | 4 + crates/cdk-axum/src/cache/backend/mod.rs | 4 + crates/cdk-axum/src/cache/backend/redis.rs | 96 ++++++++++++++++++++++ crates/cdk-axum/src/cache/config.rs | 34 ++++++++ crates/cdk-axum/src/cache/mod.rs | 19 ++++- crates/cdk-mintd/Cargo.toml | 1 + crates/cdk-mintd/example.config.toml | 5 +- docker-compose.yaml | 26 +++++- 9 files changed, 190 insertions(+), 6 deletions(-) create mode 100644 crates/cdk-axum/src/cache/backend/redis.rs diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 649af8b84..ecec7efa5 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -103,7 +103,8 @@ jobs: # HTTP/API layer - consolidated -p cdk-axum, -p cdk-axum --no-default-features, - -p cdk-axum --no-default-features --features swagger, + -p cdk-axum --no-default-features --features redis, + -p cdk-axum --no-default-features --features "redis swagger", # Lightning backends -p cdk-cln, @@ -126,7 +127,7 @@ jobs: --bin cdk-cli --features sqlcipher, --bin cdk-cli --features redb, --bin cdk-mintd, - + --bin cdk-mintd --features redis, --bin cdk-mintd --features sqlcipher, --bin cdk-mintd --no-default-features --features lnd --features sqlite, --bin cdk-mintd --no-default-features --features cln --features postgres, @@ -337,7 +338,7 @@ jobs: -p cdk --no-default-features --features "wallet auth", -p cdk --no-default-features --features "http_subscription", -p cdk-axum, - + -p cdk-axum --no-default-features --features redis, -p cdk-lnbits, -p cdk-fake-wallet, -p cdk-cln, diff --git a/crates/cdk-axum/Cargo.toml b/crates/cdk-axum/Cargo.toml index 5f0a9c930..7ef7e1454 100644 --- a/crates/cdk-axum/Cargo.toml +++ b/crates/cdk-axum/Cargo.toml @@ -12,6 +12,7 @@ readme = "README.md" [features] default = ["auth"] +redis = ["dep:redis"] swagger = ["cdk/swagger", "dep:utoipa"] auth = ["cdk/auth"] prometheus = ["dep:cdk-prometheus"] @@ -33,6 +34,9 @@ paste = "1.0.15" serde.workspace = true uuid.workspace = true sha2 = "0.10.8" +redis = { version = "0.31.0", features = [ + "tokio-rustls-comp", +], optional = true } [target.'cfg(target_arch = "wasm32")'.dependencies] uuid = { workspace = true, features = ["js"] } diff --git a/crates/cdk-axum/src/cache/backend/mod.rs b/crates/cdk-axum/src/cache/backend/mod.rs index cc0e8ad66..511d156f9 100644 --- a/crates/cdk-axum/src/cache/backend/mod.rs +++ b/crates/cdk-axum/src/cache/backend/mod.rs @@ -1,3 +1,7 @@ mod memory; +#[cfg(feature = "redis")] +mod redis; pub use self::memory::InMemoryHttpCache; +#[cfg(feature = "redis")] +pub use self::redis::{Config as RedisConfig, HttpCacheRedis}; diff --git a/crates/cdk-axum/src/cache/backend/redis.rs b/crates/cdk-axum/src/cache/backend/redis.rs new file mode 100644 index 000000000..358350f6f --- /dev/null +++ b/crates/cdk-axum/src/cache/backend/redis.rs @@ -0,0 +1,96 @@ +use std::time::Duration; + +use redis::AsyncCommands; +use serde::{Deserialize, Serialize}; + +use crate::cache::{HttpCacheKey, HttpCacheStorage}; + +/// Redis cache storage for the HTTP cache. +/// +/// This cache storage backend uses Redis to store the cache. +pub struct HttpCacheRedis { + cache_ttl: Duration, + prefix: Option>, + client: redis::Client, +} + +/// Configuration for the Redis cache storage. +#[derive(Debug, Clone, Serialize, Deserialize, Default)] +pub struct Config { + /// Commong key prefix + pub key_prefix: Option, + + /// Connection string to the Redis server. + pub connection_string: String, +} + +impl HttpCacheRedis { + /// Create a new Redis cache. + pub fn new(client: redis::Client) -> Self { + Self { + client, + prefix: None, + cache_ttl: Duration::from_secs(60), + } + } + + /// Set a prefix for the cache keys. + /// + /// This is useful to have all the HTTP cache keys under a common prefix, + /// some sort of namespace, to make management of the database easier. + pub fn set_prefix(mut self, prefix: Vec) -> Self { + self.prefix = Some(prefix); + self + } +} + +#[async_trait::async_trait] +impl HttpCacheStorage for HttpCacheRedis { + fn set_expiration_times(&mut self, cache_ttl: Duration, _cache_tti: Duration) { + self.cache_ttl = cache_ttl; + } + + async fn get(&self, key: &HttpCacheKey) -> Option> { + let mut conn = self + .client + .get_multiplexed_tokio_connection() + .await + .map_err(|err| { + tracing::error!("Failed to get redis connection: {:?}", err); + err + }) + .ok()?; + + let mut db_key = self.prefix.clone().unwrap_or_default(); + db_key.extend(&**key); + + conn.get(db_key) + .await + .map_err(|err| { + tracing::error!("Failed to get value from redis: {:?}", err); + err + }) + .ok()? + } + + async fn set(&self, key: HttpCacheKey, value: Vec) { + let mut db_key = self.prefix.clone().unwrap_or_default(); + db_key.extend(&*key); + + let mut conn = match self.client.get_multiplexed_tokio_connection().await { + Ok(conn) => conn, + Err(err) => { + tracing::error!("Failed to get redis connection: {:?}", err); + return; + } + }; + + let _: Result<(), _> = conn + .set_ex(db_key, value, self.cache_ttl.as_secs()) + .await + .map_err(|err| { + tracing::error!("Failed to set value in redis: {:?}", err); + err + }); + } +} diff --git a/crates/cdk-axum/src/cache/config.rs b/crates/cdk-axum/src/cache/config.rs index c507764b2..f50551221 100644 --- a/crates/cdk-axum/src/cache/config.rs +++ b/crates/cdk-axum/src/cache/config.rs @@ -2,6 +2,11 @@ use serde::{Deserialize, Serialize}; pub const ENV_CDK_MINTD_CACHE_BACKEND: &str = "CDK_MINTD_CACHE_BACKEND"; +#[cfg(feature = "redis")] +pub const ENV_CDK_MINTD_CACHE_REDIS_URL: &str = "CDK_MINTD_CACHE_REDIS_URL"; +#[cfg(feature = "redis")] +pub const ENV_CDK_MINTD_CACHE_REDIS_KEY_PREFIX: &str = "CDK_MINTD_CACHE_REDIS_KEY_PREFIX"; + pub const ENV_CDK_MINTD_CACHE_TTI: &str = "CDK_MINTD_CACHE_TTI"; pub const ENV_CDK_MINTD_CACHE_TTL: &str = "CDK_MINTD_CACHE_TTL"; @@ -11,12 +16,27 @@ pub const ENV_CDK_MINTD_CACHE_TTL: &str = "CDK_MINTD_CACHE_TTL"; pub enum Backend { #[default] Memory, + #[cfg(feature = "redis")] + Redis(super::backend::RedisConfig), } impl Backend { pub fn from_env_str(backend_str: &str) -> Option { match backend_str.to_lowercase().as_str() { "memory" => Some(Self::Memory), + #[cfg(feature = "redis")] + "redis" => { + // Get Redis configuration from environment + let connection_string = std::env::var(ENV_CDK_MINTD_CACHE_REDIS_URL) + .unwrap_or_else(|_| "redis://127.0.0.1:6379".to_string()); + + let key_prefix = std::env::var(ENV_CDK_MINTD_CACHE_REDIS_KEY_PREFIX).ok(); + + Some(Self::Redis(super::backend::RedisConfig { + connection_string, + key_prefix, + })) + } _ => None, } } @@ -46,6 +66,20 @@ impl Config { if let Ok(backend_str) = env::var(ENV_CDK_MINTD_CACHE_BACKEND) { if let Some(backend) = Backend::from_env_str(&backend_str) { self.backend = backend; + + // If Redis backend is selected, parse Redis configuration + #[cfg(feature = "redis")] + if matches!(self.backend, Backend::Redis(_)) { + let connection_string = env::var(ENV_CDK_MINTD_CACHE_REDIS_URL) + .unwrap_or_else(|_| "redis://127.0.0.1:6379".to_string()); + + let key_prefix = env::var(ENV_CDK_MINTD_CACHE_REDIS_KEY_PREFIX).ok(); + + self.backend = Backend::Redis(super::backend::RedisConfig { + connection_string, + key_prefix, + }); + } } } diff --git a/crates/cdk-axum/src/cache/mod.rs b/crates/cdk-axum/src/cache/mod.rs index de56d6666..f07968d0e 100644 --- a/crates/cdk-axum/src/cache/mod.rs +++ b/crates/cdk-axum/src/cache/mod.rs @@ -7,7 +7,7 @@ //! idempotent operations. //! //! This mod also provides common backend implementations as well, such as In -//! Memory (default). +//! Memory (default) and Redis. use std::ops::Deref; use std::sync::Arc; use std::time::Duration; @@ -89,6 +89,23 @@ impl From for HttpCache { Duration::from_secs(config.tti.unwrap_or(DEFAULT_TTI_SECS)), None, ), + #[cfg(feature = "redis")] + config::Backend::Redis(redis_config) => { + let client = redis::Client::open(redis_config.connection_string) + .expect("Failed to create Redis client"); + let storage = HttpCacheRedis::new(client).set_prefix( + redis_config + .key_prefix + .unwrap_or_default() + .as_bytes() + .to_vec(), + ); + Self::new( + Duration::from_secs(config.ttl.unwrap_or(DEFAULT_TTL_SECS)), + Duration::from_secs(config.tti.unwrap_or(DEFAULT_TTI_SECS)), + Some(Box::new(storage)), + ) + } } } } diff --git a/crates/cdk-mintd/Cargo.toml b/crates/cdk-mintd/Cargo.toml index 85f231109..ae83b7515 100644 --- a/crates/cdk-mintd/Cargo.toml +++ b/crates/cdk-mintd/Cargo.toml @@ -26,6 +26,7 @@ grpc-processor = ["dep:cdk-payment-processor", "cdk-signatory/grpc"] sqlcipher = ["sqlite", "cdk-sqlite/sqlcipher"] # MSRV is not committed to with swagger enabled swagger = ["cdk-axum/swagger", "dep:utoipa", "dep:utoipa-swagger-ui"] +redis = ["cdk-axum/redis"] auth = ["cdk/auth", "cdk-axum/auth", "cdk-sqlite?/auth", "cdk-postgres?/auth"] prometheus = ["cdk/prometheus", "dep:cdk-prometheus", "cdk-sqlite?/prometheus", "cdk-axum/prometheus"] diff --git a/crates/cdk-mintd/example.config.toml b/crates/cdk-mintd/example.config.toml index 79e0f8675..c65105396 100644 --- a/crates/cdk-mintd/example.config.toml +++ b/crates/cdk-mintd/example.config.toml @@ -33,10 +33,13 @@ enabled = false #port = 9090 # [info.http_cache] -# backend type: memory (default) +# memory or redis backend = "memory" ttl = 60 tti = 60 +# `key_prefix` and `connection_string` required for redis +# key_prefix = "mintd" +# connection_string = "redis://localhost" # NOTE: If [mint_management_rpc] is enabled these values will only be used on first start up. # Further changes must be made through the rpc. diff --git a/docker-compose.yaml b/docker-compose.yaml index 9a9768948..b318835cc 100644 --- a/docker-compose.yaml +++ b/docker-compose.yaml @@ -58,6 +58,9 @@ services: # - CDK_MINTD_DATABASE_URL=postgresql://cdk_user:cdk_password@postgres:5432/cdk_mint # Cache configuration - CDK_MINTD_CACHE_BACKEND=memory + # For Redis cache (requires redis service, enable with: docker-compose --profile redis up): + # - CDK_MINTD_CACHE_REDIS_URL=redis://redis:6379 + # - CDK_MINTD_CACHE_REDIS_KEY_PREFIX=cdk-mintd - CDK_MINTD_PROMETHEUS_ENABLED=true - CDK_MINTD_PROMETHEUS_ADDRESS=0.0.0.0 - CDK_MINTD_PROMETHEUS_PORT=9000 @@ -131,13 +134,34 @@ services: # timeout: 5s # retries: 5 - + # Redis cache service (optional) + # Enable with: docker-compose --profile redis up +# redis: +# image: redis:7-alpine +# container_name: mint_redis +# restart: unless-stopped +# profiles: +# - redis +# ports: +# - "6379:6379" +# volumes: +# - redis_data:/data +# command: redis-server --save 60 1 --loglevel warning +# healthcheck: +# test: ["CMD", "redis-cli", "ping"] +# interval: 10s +# timeout: 3s +# retries: 5 volumes: postgres_data: driver: local ldk_node_data: driver: local +# redis_data: +# driver: local + + networks: cdk: From 6d0003a4fceb7738b0e4d0f8d76b8925bbf5fd6e Mon Sep 17 00:00:00 2001 From: lollerfirst <43107113+lollerfirst@users.noreply.github.com> Date: Fri, 26 Sep 2025 21:56:01 +0200 Subject: [PATCH 190/321] token: add spending-condition inspection helpers and token_secrets() (#1124) * token: add Token::token_secrets() and spending-condition helpers - New helpers on Token that do not require mint keysets: - spending_conditions() - p2pk_pubkeys() - p2pk_refund_pubkeys() - htlc_hashes() - locktimes() - Introduce token_secrets() to unify V3/V4 proof traversal and avoid duplication - Bypass short->long keyset-id mapping since only Secret is needed for conditions - Use &Secret for TryFrom to fix compile error --- crates/cashu/src/nuts/nut00/token.rs | 244 +++++++++++++++++- crates/cdk-ffi/src/lib.rs | 1 + crates/cdk-ffi/src/multi_mint_wallet.rs | 1 + crates/cdk-ffi/src/token.rs | 158 ++++++++++++ crates/cdk-ffi/src/types.rs | 93 +------ crates/cdk-ffi/src/wallet.rs | 1 + .../tests/ffi_minting_integration.rs | 2 +- crates/cdk-postgres/src/lib.rs | 5 +- 8 files changed, 407 insertions(+), 98 deletions(-) create mode 100644 crates/cdk-ffi/src/token.rs diff --git a/crates/cashu/src/nuts/nut00/token.rs b/crates/cashu/src/nuts/nut00/token.rs index f054875f7..a9d4bc40b 100644 --- a/crates/cashu/src/nuts/nut00/token.rs +++ b/crates/cashu/src/nuts/nut00/token.rs @@ -2,18 +2,20 @@ //! //! -use std::collections::HashMap; +use std::collections::{BTreeSet, HashMap, HashSet}; use std::fmt; use std::str::FromStr; use bitcoin::base64::engine::{general_purpose, GeneralPurpose}; use bitcoin::base64::{alphabet, Engine as _}; +use bitcoin::hashes::sha256; use serde::{Deserialize, Serialize}; use super::{Error, Proof, ProofV3, ProofV4, Proofs}; use crate::mint_url::MintUrl; use crate::nut02::ShortKeysetId; -use crate::nuts::{CurrencyUnit, Id}; +use crate::nuts::nut11::SpendingConditions; +use crate::nuts::{CurrencyUnit, Id, Kind, PublicKey}; use crate::{ensure_cdk, Amount, KeySetInfo}; /// Token Enum @@ -128,6 +130,90 @@ impl Token { Self::TokenV4(token) => token.to_raw_bytes(), } } + + /// Return all proof secrets in this token without keyset-id mapping, across V3/V4 + /// This is intended for spending-condition inspection where only the secret matters. + pub fn token_secrets(&self) -> Vec<&crate::secret::Secret> { + match self { + Token::TokenV3(t) => t + .token + .iter() + .flat_map(|kt| kt.proofs.iter().map(|p| &p.secret)) + .collect(), + Token::TokenV4(t) => t + .token + .iter() + .flat_map(|kt| kt.proofs.iter().map(|p| &p.secret)) + .collect(), + } + } + + /// Extract unique spending conditions across all proofs + pub fn spending_conditions(&self) -> Result, Error> { + let mut set = HashSet::new(); + for secret in self.token_secrets().into_iter() { + if let Ok(cond) = SpendingConditions::try_from(secret) { + set.insert(cond); + } + } + Ok(set) + } + + /// Collect pubkeys for P2PK-locked ecash + pub fn p2pk_pubkeys(&self) -> Result, Error> { + let mut keys: HashSet = HashSet::new(); + for secret in self.token_secrets().into_iter() { + if let Ok(cond) = SpendingConditions::try_from(secret) { + if cond.kind() == Kind::P2PK { + if let Some(ps) = cond.pubkeys() { + keys.extend(ps); + } + } + } + } + Ok(keys) + } + + /// Collect refund pubkeys from P2PK conditions + pub fn p2pk_refund_pubkeys(&self) -> Result, Error> { + let mut keys: HashSet = HashSet::new(); + for secret in self.token_secrets().into_iter() { + if let Ok(cond) = SpendingConditions::try_from(secret) { + if cond.kind() == Kind::P2PK { + if let Some(ps) = cond.refund_keys() { + keys.extend(ps); + } + } + } + } + Ok(keys) + } + + /// Collect HTLC hashes + pub fn htlc_hashes(&self) -> Result, Error> { + let mut hashes: HashSet = HashSet::new(); + for secret in self.token_secrets().into_iter() { + if let Ok(SpendingConditions::HTLCConditions { data, .. }) = + SpendingConditions::try_from(secret) + { + hashes.insert(data); + } + } + Ok(hashes) + } + + /// Collect unique locktimes from spending conditions + pub fn locktimes(&self) -> Result, Error> { + let mut set: BTreeSet = BTreeSet::new(); + for secret in self.token_secrets().into_iter() { + if let Ok(cond) = SpendingConditions::try_from(secret) { + if let Some(lt) = cond.locktime() { + set.insert(lt); + } + } + } + Ok(set) + } } impl FromStr for Token { @@ -535,10 +621,13 @@ mod tests { use std::str::FromStr; use bip39::rand::{self, RngCore}; + use bitcoin::hashes::sha256::Hash as Sha256Hash; + use bitcoin::hashes::Hash; use super::*; use crate::dhke::hash_to_curve; use crate::mint_url::MintUrl; + use crate::nuts::nut11::{Conditions, SigFlag, SpendingConditions}; use crate::secret::Secret; use crate::util::hex; @@ -826,4 +915,155 @@ mod tests { let proofs1 = token1.unwrap().proofs(&keysets_info); assert!(proofs1.is_err()); } + #[test] + fn test_token_spending_condition_helpers_p2pk_htlc_v4() { + let mint_url = MintUrl::from_str("https://example.com").unwrap(); + let keyset_id = Id::from_str("009a1f293253e41e").unwrap(); + + // P2PK: base pubkey plus an extra pubkey via tags, refund key, and locktime + let sk1 = crate::nuts::SecretKey::generate(); + let pk1 = sk1.public_key(); + let sk2 = crate::nuts::SecretKey::generate(); + let pk2 = sk2.public_key(); + let refund_sk = crate::nuts::SecretKey::generate(); + let refund_pk = refund_sk.public_key(); + + let cond_p2pk = Conditions { + locktime: Some(1_700_000_000), + pubkeys: Some(vec![pk2]), + refund_keys: Some(vec![refund_pk]), + num_sigs: Some(1), + sig_flag: SigFlag::SigInputs, + num_sigs_refund: None, + }; + + let nut10_p2pk = crate::nuts::Nut10Secret::new( + crate::nuts::Kind::P2PK, + pk1.to_string(), + Some(cond_p2pk.clone()), + ); + let secret_p2pk: Secret = nut10_p2pk.try_into().unwrap(); + + // HTLC: use a known preimage hash and its own locktime + let preimage = b"cdk-test-preimage"; + let htlc_hash = Sha256Hash::hash(preimage); + let cond_htlc = Conditions { + locktime: Some(1_800_000_000), + ..Default::default() + }; + let nut10_htlc = crate::nuts::Nut10Secret::new( + crate::nuts::Kind::HTLC, + htlc_hash.to_string(), + Some(cond_htlc.clone()), + ); + let secret_htlc: Secret = nut10_htlc.try_into().unwrap(); + + // Build two proofs (one P2PK, one HTLC) + let proof_p2pk = Proof::new(Amount::from(1), keyset_id, secret_p2pk.clone(), pk1); + let proof_htlc = Proof::new(Amount::from(2), keyset_id, secret_htlc.clone(), pk2); + let token = Token::new( + mint_url, + vec![proof_p2pk, proof_htlc].into_iter().collect(), + None, + CurrencyUnit::Sat, + ); + + // token_secrets should see both + assert_eq!(token.token_secrets().len(), 2); + + // spending_conditions should contain both kinds with their conditions + let sc = token.spending_conditions().unwrap(); + assert!(sc.contains(&SpendingConditions::P2PKConditions { + data: pk1, + conditions: Some(cond_p2pk.clone()) + })); + assert!(sc.contains(&SpendingConditions::HTLCConditions { + data: htlc_hash, + conditions: Some(cond_htlc.clone()) + })); + + // p2pk_pubkeys should include base pk1 and extra pk2 from tags (deduped) + let pks = token.p2pk_pubkeys().unwrap(); + assert!(pks.contains(&pk1)); + assert!(pks.contains(&pk2)); + assert_eq!(pks.len(), 2); + + // p2pk_refund_pubkeys should include refund_pk only + let refund = token.p2pk_refund_pubkeys().unwrap(); + assert!(refund.contains(&refund_pk)); + assert_eq!(refund.len(), 1); + + // htlc_hashes should include exactly our hash + let hashes = token.htlc_hashes().unwrap(); + assert!(hashes.contains(&htlc_hash)); + assert_eq!(hashes.len(), 1); + + // locktimes should include both unique locktimes + let lts = token.locktimes().unwrap(); + assert!(lts.contains(&1_700_000_000)); + assert!(lts.contains(&1_800_000_000)); + assert_eq!(lts.len(), 2); + } + + #[test] + fn test_token_spending_condition_helpers_dedup_and_v3() { + let mint_url = MintUrl::from_str("https://example.org").unwrap(); + let id = Id::from_str("00ad268c4d1f5826").unwrap(); + + // Same P2PK conditions duplicated across two proofs + let sk = crate::nuts::SecretKey::generate(); + let pk = sk.public_key(); + + let cond = Conditions { + locktime: Some(1_650_000_000), + pubkeys: Some(vec![pk]), // include itself to test dedup inside pubkeys() + refund_keys: Some(vec![pk]), // deliberate duplicate + num_sigs: Some(1), + sig_flag: SigFlag::SigInputs, + num_sigs_refund: None, + }; + + let nut10 = crate::nuts::Nut10Secret::new( + crate::nuts::Kind::P2PK, + pk.to_string(), + Some(cond.clone()), + ); + let secret: Secret = nut10.try_into().unwrap(); + + let p1 = Proof::new(Amount::from(1), id, secret.clone(), pk); + let p2 = Proof::new(Amount::from(2), id, secret.clone(), pk); + + // Build a V3 token explicitly and wrap into Token::TokenV3 + let token_v3 = TokenV3::new( + mint_url, + vec![p1, p2].into_iter().collect(), + None, + Some(CurrencyUnit::Sat), + ) + .unwrap(); + let token = Token::TokenV3(token_v3); + + // Helpers should dedup + let sc = token.spending_conditions().unwrap(); + assert_eq!(sc.len(), 1); // identical conditions across proofs + + let pks = token.p2pk_pubkeys().unwrap(); + assert!(pks.contains(&pk)); + assert_eq!(pks.len(), 1); // duplicates removed + + let refunds = token.p2pk_refund_pubkeys().unwrap(); + assert!(refunds.contains(&pk)); + assert_eq!(refunds.len(), 1); + + let lts = token.locktimes().unwrap(); + assert!(lts.contains(&1_650_000_000)); + assert_eq!(lts.len(), 1); + + // No HTLC here + let hashes = token.htlc_hashes().unwrap(); + assert!(hashes.is_empty()); + + // token_secrets length equals number of proofs even if conditions identical + assert_eq!(token.token_secrets().len(), 2); + } } diff --git a/crates/cdk-ffi/src/lib.rs b/crates/cdk-ffi/src/lib.rs index fe6ddabaf..beb5046fc 100644 --- a/crates/cdk-ffi/src/lib.rs +++ b/crates/cdk-ffi/src/lib.rs @@ -7,6 +7,7 @@ pub mod database; pub mod error; pub mod multi_mint_wallet; +pub mod token; pub mod types; pub mod wallet; diff --git a/crates/cdk-ffi/src/multi_mint_wallet.rs b/crates/cdk-ffi/src/multi_mint_wallet.rs index d8b807fb6..6fc72af93 100644 --- a/crates/cdk-ffi/src/multi_mint_wallet.rs +++ b/crates/cdk-ffi/src/multi_mint_wallet.rs @@ -12,6 +12,7 @@ use cdk::wallet::multi_mint_wallet::{ }; use crate::error::FfiError; +use crate::token::Token; use crate::types::*; /// FFI-compatible MultiMintWallet diff --git a/crates/cdk-ffi/src/token.rs b/crates/cdk-ffi/src/token.rs new file mode 100644 index 000000000..31a22e424 --- /dev/null +++ b/crates/cdk-ffi/src/token.rs @@ -0,0 +1,158 @@ +//! FFI token bindings + +use std::collections::BTreeSet; +use std::str::FromStr; + +use crate::error::FfiError; +use crate::{Amount, CurrencyUnit, MintUrl, Proofs}; + +/// FFI-compatible Token +#[derive(Debug, uniffi::Object)] +pub struct Token { + pub(crate) inner: cdk::nuts::Token, +} + +impl std::fmt::Display for Token { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + write!(f, "{}", self.inner) + } +} + +impl FromStr for Token { + type Err = FfiError; + + fn from_str(s: &str) -> Result { + let token = cdk::nuts::Token::from_str(s) + .map_err(|e| FfiError::InvalidToken { msg: e.to_string() })?; + Ok(Token { inner: token }) + } +} + +impl From for Token { + fn from(token: cdk::nuts::Token) -> Self { + Self { inner: token } + } +} + +impl From for cdk::nuts::Token { + fn from(token: Token) -> Self { + token.inner + } +} + +#[uniffi::export] +impl Token { + /// Create a new Token from string + #[uniffi::constructor] + pub fn from_string(encoded_token: String) -> Result { + let token = cdk::nuts::Token::from_str(&encoded_token) + .map_err(|e| FfiError::InvalidToken { msg: e.to_string() })?; + Ok(Token { inner: token }) + } + + /// Get the total value of the token + pub fn value(&self) -> Result { + Ok(self.inner.value()?.into()) + } + + /// Get the memo from the token + pub fn memo(&self) -> Option { + self.inner.memo().clone() + } + + /// Get the currency unit + pub fn unit(&self) -> Option { + self.inner.unit().map(Into::into) + } + + /// Get the mint URL + pub fn mint_url(&self) -> Result { + Ok(self.inner.mint_url()?.into()) + } + + /// Get proofs from the token (simplified - no keyset filtering for now) + pub fn proofs_simple(&self) -> Result { + // For now, return empty keysets to get all proofs + let empty_keysets = vec![]; + let proofs = self.inner.proofs(&empty_keysets)?; + Ok(proofs + .into_iter() + .map(|p| std::sync::Arc::new(p.into())) + .collect()) + } + + /// Convert token to raw bytes + pub fn to_raw_bytes(&self) -> Result, FfiError> { + Ok(self.inner.to_raw_bytes()?) + } + + /// Encode token to string representation + pub fn encode(&self) -> String { + self.to_string() + } + + /// Decode token from string representation + #[uniffi::constructor] + pub fn decode(encoded_token: String) -> Result { + encoded_token.parse() + } + + /// Return unique spending conditions across all proofs in this token + pub fn spending_conditions(&self) -> Vec { + self.inner + .spending_conditions() + .map(|set| set.into_iter().map(Into::into).collect()) + .unwrap_or_default() + } + + /// Return all P2PK pubkeys referenced by this token's spending conditions + pub fn p2pk_pubkeys(&self) -> Vec { + let set = self + .inner + .p2pk_pubkeys() + .map(|keys| { + keys.into_iter() + .map(|k| k.to_string()) + .collect::>() + }) + .unwrap_or_default(); + set.into_iter().collect() + } + + /// Return all refund pubkeys from P2PK spending conditions + pub fn p2pk_refund_pubkeys(&self) -> Vec { + let set = self + .inner + .p2pk_refund_pubkeys() + .map(|keys| { + keys.into_iter() + .map(|k| k.to_string()) + .collect::>() + }) + .unwrap_or_default(); + set.into_iter().collect() + } + + /// Return all HTLC hashes from spending conditions + pub fn htlc_hashes(&self) -> Vec { + let set = self + .inner + .htlc_hashes() + .map(|hashes| { + hashes + .into_iter() + .map(|h| h.to_string()) + .collect::>() + }) + .unwrap_or_default(); + set.into_iter().collect() + } + + /// Return all locktimes from spending conditions (sorted ascending) + pub fn locktimes(&self) -> Vec { + self.inner + .locktimes() + .map(|s| s.into_iter().collect()) + .unwrap_or_default() + } +} diff --git a/crates/cdk-ffi/src/types.rs b/crates/cdk-ffi/src/types.rs index 9d4b04488..1a6d1d4df 100644 --- a/crates/cdk-ffi/src/types.rs +++ b/crates/cdk-ffi/src/types.rs @@ -10,6 +10,7 @@ use cdk::Amount as CdkAmount; use serde::{Deserialize, Serialize}; use crate::error::FfiError; +use crate::token::Token; /// FFI-compatible Amount type #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, uniffi::Record)] @@ -200,98 +201,6 @@ impl From for CdkState { } } -/// FFI-compatible Token -#[derive(Debug, uniffi::Object)] -pub struct Token { - pub(crate) inner: cdk::nuts::Token, -} - -impl std::fmt::Display for Token { - fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { - write!(f, "{}", self.inner) - } -} - -impl FromStr for Token { - type Err = FfiError; - - fn from_str(s: &str) -> Result { - let token = cdk::nuts::Token::from_str(s) - .map_err(|e| FfiError::InvalidToken { msg: e.to_string() })?; - Ok(Token { inner: token }) - } -} - -impl From for Token { - fn from(token: cdk::nuts::Token) -> Self { - Self { inner: token } - } -} - -impl From for cdk::nuts::Token { - fn from(token: Token) -> Self { - token.inner - } -} - -#[uniffi::export] -impl Token { - /// Create a new Token from string - #[uniffi::constructor] - pub fn from_string(encoded_token: String) -> Result { - let token = cdk::nuts::Token::from_str(&encoded_token) - .map_err(|e| FfiError::InvalidToken { msg: e.to_string() })?; - Ok(Token { inner: token }) - } - - /// Get the total value of the token - pub fn value(&self) -> Result { - Ok(self.inner.value()?.into()) - } - - /// Get the memo from the token - pub fn memo(&self) -> Option { - self.inner.memo().clone() - } - - /// Get the currency unit - pub fn unit(&self) -> Option { - self.inner.unit().map(Into::into) - } - - /// Get the mint URL - pub fn mint_url(&self) -> Result { - Ok(self.inner.mint_url()?.into()) - } - - /// Get proofs from the token (simplified - no keyset filtering for now) - pub fn proofs_simple(&self) -> Result { - // For now, return empty keysets to get all proofs - let empty_keysets = vec![]; - let proofs = self.inner.proofs(&empty_keysets)?; - Ok(proofs - .into_iter() - .map(|p| std::sync::Arc::new(p.into())) - .collect()) - } - - /// Convert token to raw bytes - pub fn to_raw_bytes(&self) -> Result, FfiError> { - Ok(self.inner.to_raw_bytes()?) - } - - /// Encode token to string representation - pub fn encode(&self) -> String { - self.to_string() - } - - /// Decode token from string representation - #[uniffi::constructor] - pub fn decode(encoded_token: String) -> Result { - encoded_token.parse() - } -} - /// FFI-compatible SendMemo #[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] pub struct SendMemo { diff --git a/crates/cdk-ffi/src/wallet.rs b/crates/cdk-ffi/src/wallet.rs index b342e1427..802a873e3 100644 --- a/crates/cdk-ffi/src/wallet.rs +++ b/crates/cdk-ffi/src/wallet.rs @@ -7,6 +7,7 @@ use bip39::Mnemonic; use cdk::wallet::{Wallet as CdkWallet, WalletBuilder as CdkWalletBuilder}; use crate::error::FfiError; +use crate::token::Token; use crate::types::*; /// FFI-compatible Wallet diff --git a/crates/cdk-integration-tests/tests/ffi_minting_integration.rs b/crates/cdk-integration-tests/tests/ffi_minting_integration.rs index 44857b9c8..8d3b32043 100644 --- a/crates/cdk-integration-tests/tests/ffi_minting_integration.rs +++ b/crates/cdk-integration-tests/tests/ffi_minting_integration.rs @@ -214,7 +214,7 @@ async fn test_ffi_mint_quote_creation() { let quote = wallet .mint_quote(amount, Some(description.clone())) .await - .expect(&format!("Failed to create quote for {} sats", amount_value)); + .unwrap_or_else(|_| panic!("Failed to create quote for {} sats", amount_value)); // Verify quote properties assert_eq!(quote.amount, Some(amount)); diff --git a/crates/cdk-postgres/src/lib.rs b/crates/cdk-postgres/src/lib.rs index d0a60c426..0d89c06c6 100644 --- a/crates/cdk-postgres/src/lib.rs +++ b/crates/cdk-postgres/src/lib.rs @@ -335,10 +335,9 @@ mod test { let db_url = format!("{db_url} schema={test_id}"); - let db = MintPgDatabase::new(db_url.as_str()) + MintPgDatabase::new(db_url.as_str()) .await - .expect("database"); - db + .expect("database") } mint_db_test!(provide_db); From 4b04d10383d1beb733710b139f409ed5e0c3cfe8 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Sat, 27 Sep 2025 23:51:24 +0100 Subject: [PATCH 191/321] Check change unique (#1112) * fix(cdk): prevent duplicate blinded message processing with database constraints Add unique constraints on blinded_message column in both PostgreSQL and SQLite databases, and implement application-level checks to prevent duplicate blinded messages from being processed. Also ensure proper cleanup of melt requests after successful processing. * feat: db tests for unique * refactor(cdk-sql): consolidate blinded messages into blind signature table Migrate from separate blinded_messages table to unified blind_signature table. Add signed_time column and make c column nullable to track both pending blind messages (c=NULL) and completed signatures. Update insert/update logic to handle upsert scenarios for blind signature completion. * refactor(cdk-sql): remove unique constraint migration and filter queries for signed messages Remove database-level unique constraint on blinded_message and instead filter queries to only consider messages with signatures (c IS NOT NULL * refactor(database): improve blinded message duplicate detection using database constraints Replace manual duplicate checking with database constraint handling for better reliability and simplified code flow in melt request processing. * refactor(cdk-sql): optimize blind signature processing with batch queries Replace individual queries per blinded message with single batch query and HashMap lookup to eliminate N+1 query performance issue. * fix: signed time to swap sigs * refactor(cdk): split blinded message handling and improve duplicate detection - Split add_melt_request_and_blinded_messages into separate methods - Add blinded messages to database before signing in swap operations - Improve duplicate output detection with proper error handling - Make add_blinded_messages method accept optional quote_id for flexibility * refactor(cdk): add BlindedMessageWriter for improved transaction rollback - Add BlindedMessageWriter component for managing blinded message state - Implement proper rollback mechanisms in swap operations - Add delete_blinded_messages database interface for cleanup - Improve error handling with better state management --- .typos.toml | 3 +- crates/cdk-common/src/database/mint/mod.rs | 16 +- .../cdk-common/src/database/mint/test/mint.rs | 198 +++++++++++++- .../cdk-common/src/database/mint/test/mod.rs | 6 +- ...e_blinded_messages_to_blind_signatures.sql | 23 ++ ...e_blinded_messages_to_blind_signatures.sql | 40 +++ crates/cdk-sql-common/src/mint/mod.rs | 244 ++++++++++++++---- crates/cdk/src/mint/blinded_message_writer.rs | 152 +++++++++++ crates/cdk/src/mint/melt.rs | 12 +- crates/cdk/src/mint/mod.rs | 1 + crates/cdk/src/mint/swap.rs | 52 +++- 11 files changed, 692 insertions(+), 55 deletions(-) create mode 100644 crates/cdk-sql-common/src/mint/migrations/postgres/20250924215800_migrate_blinded_messages_to_blind_signatures.sql create mode 100644 crates/cdk-sql-common/src/mint/migrations/sqlite/20250924215800_migrate_blinded_messages_to_blind_signatures.sql create mode 100644 crates/cdk/src/mint/blinded_message_writer.rs diff --git a/.typos.toml b/.typos.toml index e3cc2980e..6a6405af2 100644 --- a/.typos.toml +++ b/.typos.toml @@ -6,5 +6,6 @@ extend-ignore-re = [ "casshuAeyJ0b2tlbiI6W3sibWludCI6Imh0dHBzOi8vODMzMy5zcGFjZTozMzM4IiwicHJvb2ZzIjpbeyJhbW91bnQiOjIsImlkIjoiMDA5YTFmMjkzMjUzZTQxZSIsInNlY3JldCI6IjQwNzkxNWJjMjEyYmU2MWE3N2UzZTZkMmFlYjRjNzI3OTgwYmRhNTFjZDA2YTZhZmMyOWUyODYxNzY4YTc4MzciLCJDIjoiMDJiYzkwOTc5OTdkODFhZmIyY2M3MzQ2YjVlNDM0NWE5MzQ2YmQyYTUwNmViNzk1ODU5OGE3MmYwY2Y4NTE2M2VhIn0seyJhbW91bnQiOjgsImlkIjoiMDA5YTFmMjkzMjUzZTQxZSIsInNlY3JldCI6ImZlMTUxMDkzMTRlNjFkNzc1NmIwZjhlZTBmMjNhNjI0YWNhYTNmNGUwNDJmNjE0MzNjNzI4YzcwNTdiOTMxYmUiLCJDIjoiMDI5ZThlNTA1MGI4OTBhN2Q2YzA5NjhkYjE2YmMxZDVkNWZhMDQwZWExZGUyODRmNmVjNjlkNjEyOTlmNjcxMDU5In1dfV0sInVuaXQiOiJzYXQiLCJtZW1vIjoiVGhhbmsgeW91LiJ9", "autheticator", "Gam", - "flate2" + "flate2", + "lnbc[A-Za-z0-9-_]+" ] diff --git a/crates/cdk-common/src/database/mint/mod.rs b/crates/cdk-common/src/database/mint/mod.rs index 9c08734c3..5ece68c47 100644 --- a/crates/cdk-common/src/database/mint/mod.rs +++ b/crates/cdk-common/src/database/mint/mod.rs @@ -132,15 +132,27 @@ pub trait QuotesTransaction<'a> { /// Mint Quotes Database Error type Err: Into + From; - /// Add melt_request with quote_id, inputs_amount, and blinded_messages - async fn add_melt_request_and_blinded_messages( + /// Add melt_request with quote_id, inputs_amount, and inputs_fee + async fn add_melt_request( &mut self, quote_id: &QuoteId, inputs_amount: Amount, inputs_fee: Amount, + ) -> Result<(), Self::Err>; + + /// Add blinded_messages for a quote_id + async fn add_blinded_messages( + &mut self, + quote_id: Option<&QuoteId>, blinded_messages: &[BlindedMessage], ) -> Result<(), Self::Err>; + /// Delete blinded_messages by their blinded secrets + async fn delete_blinded_messages( + &mut self, + blinded_secrets: &[PublicKey], + ) -> Result<(), Self::Err>; + /// Get melt_request and associated blinded_messages by quote_id async fn get_melt_request_and_blinded_messages( &mut self, diff --git a/crates/cdk-common/src/database/mint/test/mint.rs b/crates/cdk-common/src/database/mint/test/mint.rs index ee4641a15..531dc9245 100644 --- a/crates/cdk-common/src/database/mint/test/mint.rs +++ b/crates/cdk-common/src/database/mint/test/mint.rs @@ -1,8 +1,14 @@ //! Payments +use std::str::FromStr; + +use cashu::quote_id::QuoteId; +use cashu::{Amount, Id, SecretKey}; + use crate::database::mint::test::unique_string; use crate::database::mint::{Database, Error, KeysDatabase}; -use crate::mint::MintQuote; +use crate::database::MintSignaturesDatabase; +use crate::mint::{MeltPaymentRequest, MeltQuote, MintQuote}; use crate::payment::PaymentIdentifier; /// Add a mint quote @@ -404,3 +410,193 @@ where .await .is_err()); } +/// Successful melt with unique blinded messages +pub async fn add_melt_request_unique_blinded_messages(db: DB) +where + DB: Database + KeysDatabase + MintSignaturesDatabase, +{ + let inputs_amount = Amount::from(100u64); + let inputs_fee = Amount::from(1u64); + let keyset_id = Id::from_str("001711afb1de20cb").unwrap(); + + // Create a dummy blinded message + let blinded_secret = SecretKey::generate().public_key(); + let blinded_message = cashu::BlindedMessage { + blinded_secret, + keyset_id, + amount: Amount::from(100u64), + witness: None, + }; + let blinded_messages = vec![blinded_message]; + + let mut tx = Database::begin_transaction(&db).await.unwrap(); + let quote = MeltQuote::new(MeltPaymentRequest::Bolt11 { bolt11: "lnbc330n1p5d85skpp5344v3ktclujsjl3h09wgsfm7zytumr7h7zhrl857f5w8nv0a52zqdqqcqzzsxqyz5vqrzjqvueefmrckfdwyyu39m0lf24sqzcr9vcrmxrvgfn6empxz7phrjxvrttncqq0lcqqyqqqqlgqqqqqqgq2qsp5j3rrg8kvpemqxtf86j8tjm90wq77c7ende4e5qmrerq4xsg02vhq9qxpqysgqjltywgyk6uc5qcgwh8xnzmawl2tjlhz8d28tgp3yx8xwtz76x0jqkfh6mmq70hervjxs0keun7ur0spldgll29l0dnz3md50d65sfqqqwrwpsu".parse().unwrap() }, cashu::CurrencyUnit::Sat, 33.into(), Amount::ZERO, 0, None, None, cashu::PaymentMethod::Bolt11); + tx.add_melt_quote(quote.clone()).await.unwrap(); + tx.add_melt_request("e.id, inputs_amount, inputs_fee) + .await + .unwrap(); + tx.add_blinded_messages(Some("e.id), &blinded_messages) + .await + .unwrap(); + tx.commit().await.unwrap(); + + // Verify retrieval + let mut tx = Database::begin_transaction(&db).await.unwrap(); + let retrieved = tx + .get_melt_request_and_blinded_messages("e.id) + .await + .unwrap() + .unwrap(); + assert_eq!(retrieved.inputs_amount, inputs_amount); + assert_eq!(retrieved.inputs_fee, inputs_fee); + assert_eq!(retrieved.change_outputs.len(), 1); + assert_eq!(retrieved.change_outputs[0].amount, Amount::from(100u64)); + tx.commit().await.unwrap(); +} + +/// Reject melt with duplicate blinded message (already signed) +pub async fn reject_melt_duplicate_blinded_signature(db: DB) +where + DB: Database + KeysDatabase + MintSignaturesDatabase, +{ + let quote_id1 = QuoteId::new_uuid(); + let inputs_amount = Amount::from(100u64); + let inputs_fee = Amount::from(1u64); + let keyset_id = Id::from_str("001711afb1de20cb").unwrap(); + + // Create a dummy blinded message + let blinded_secret = SecretKey::generate().public_key(); + let blinded_message = cashu::BlindedMessage { + blinded_secret, + keyset_id, + amount: Amount::from(100u64), + witness: None, + }; + let blinded_messages = vec![blinded_message.clone()]; + + // First, "sign" it by adding to blind_signature (simulate successful mint) + let mut tx = Database::begin_transaction(&db).await.unwrap(); + let c = SecretKey::generate().public_key(); + let blind_sig = cashu::BlindSignature { + amount: Amount::from(100u64), + keyset_id, + c, + dleq: None, + }; + let blinded_secrets = vec![blinded_message.blinded_secret]; + tx.add_blind_signatures(&blinded_secrets, &[blind_sig], Some(quote_id1)) + .await + .unwrap(); + tx.commit().await.unwrap(); + + // Now try to add melt request with the same blinded message - should fail due to constraint + let mut tx = Database::begin_transaction(&db).await.unwrap(); + let quote2 = MeltQuote::new(MeltPaymentRequest::Bolt11 { bolt11: "lnbc330n1p5d85skpp5344v3ktclujsjl3h09wgsfm7zytumr7h7zhrl857f5w8nv0a52zqdqqcqzzsxqyz5vqrzjqvueefmrckfdwyyu39m0lf24sqzcr9vcrmxrvgfn6empxz7phrjxvrttncqq0lcqqyqqqqlgqqqqqqgq2qsp5j3rrg8kvpemqxtf86j8tjm90wq77c7ende4e5qmrerq4xsg02vhq9qxpqysgqjltywgyk6uc5qcgwh8xnzmawl2tjlhz8d28tgp3yx8xwtz76x0jqkfh6mmq70hervjxs0keun7ur0spldgll29l0dnz3md50d65sfqqqwrwpsu".parse().unwrap() }, cashu::CurrencyUnit::Sat, 33.into(), Amount::ZERO, 0, None, None, cashu::PaymentMethod::Bolt11); + tx.add_melt_quote(quote2.clone()).await.unwrap(); + tx.add_melt_request("e2.id, inputs_amount, inputs_fee) + .await + .unwrap(); + let result = tx + .add_blinded_messages(Some("e2.id), &blinded_messages) + .await; + assert!(result.is_err() && matches!(result.unwrap_err(), Error::Duplicate)); + tx.rollback().await.unwrap(); // Rollback to avoid partial state +} + +/// Reject duplicate blinded message insert via DB constraint (different quotes) +pub async fn reject_duplicate_blinded_message_db_constraint(db: DB) +where + DB: Database + KeysDatabase, +{ + let inputs_amount = Amount::from(100u64); + let inputs_fee = Amount::from(1u64); + let keyset_id = Id::from_str("001711afb1de20cb").unwrap(); + + // Create a dummy blinded message + let blinded_secret = SecretKey::generate().public_key(); + let blinded_message = cashu::BlindedMessage { + blinded_secret, + keyset_id, + amount: Amount::from(100u64), + witness: None, + }; + let blinded_messages = vec![blinded_message]; + + // First insert succeeds + let mut tx = Database::begin_transaction(&db).await.unwrap(); + let quote = MeltQuote::new(MeltPaymentRequest::Bolt11 { bolt11: "lnbc330n1p5d85skpp5344v3ktclujsjl3h09wgsfm7zytumr7h7zhrl857f5w8nv0a52zqdqqcqzzsxqyz5vqrzjqvueefmrckfdwyyu39m0lf24sqzcr9vcrmxrvgfn6empxz7phrjxvrttncqq0lcqqyqqqqlgqqqqqqgq2qsp5j3rrg8kvpemqxtf86j8tjm90wq77c7ende4e5qmrerq4xsg02vhq9qxpqysgqjltywgyk6uc5qcgwh8xnzmawl2tjlhz8d28tgp3yx8xwtz76x0jqkfh6mmq70hervjxs0keun7ur0spldgll29l0dnz3md50d65sfqqqwrwpsu".parse().unwrap() }, cashu::CurrencyUnit::Sat, 33.into(), Amount::ZERO, 0, None, None, cashu::PaymentMethod::Bolt11); + tx.add_melt_quote(quote.clone()).await.unwrap(); + tx.add_melt_request("e.id, inputs_amount, inputs_fee) + .await + .unwrap(); + assert!(tx + .add_blinded_messages(Some("e.id), &blinded_messages) + .await + .is_ok()); + tx.commit().await.unwrap(); + + // Second insert with same blinded_message but different quote_id should fail due to unique constraint on blinded_message + let mut tx = Database::begin_transaction(&db).await.unwrap(); + let quote = MeltQuote::new(MeltPaymentRequest::Bolt11 { bolt11: "lnbc330n1p5d85skpp5344v3ktclujsjl3h09wgsfm7zytumr7h7zhrl857f5w8nv0a52zqdqqcqzzsxqyz5vqrzjqvueefmrckfdwyyu39m0lf24sqzcr9vcrmxrvgfn6empxz7phrjxvrttncqq0lcqqyqqqqlgqqqqqqgq2qsp5j3rrg8kvpemqxtf86j8tjm90wq77c7ende4e5qmrerq4xsg02vhq9qxpqysgqjltywgyk6uc5qcgwh8xnzmawl2tjlhz8d28tgp3yx8xwtz76x0jqkfh6mmq70hervjxs0keun7ur0spldgll29l0dnz3md50d65sfqqqwrwpsu".parse().unwrap() }, cashu::CurrencyUnit::Sat, 33.into(), Amount::ZERO, 0, None, None, cashu::PaymentMethod::Bolt11); + tx.add_melt_quote(quote.clone()).await.unwrap(); + tx.add_melt_request("e.id, inputs_amount, inputs_fee) + .await + .unwrap(); + let result = tx + .add_blinded_messages(Some("e.id), &blinded_messages) + .await; + // Expect a database error due to unique violation + assert!(result.is_err()); // Specific error might be DB-specific, e.g., SqliteError or PostgresError + tx.rollback().await.unwrap(); +} + +/// Cleanup of melt request after processing +pub async fn cleanup_melt_request_after_processing(db: DB) +where + DB: Database + KeysDatabase, +{ + let inputs_amount = Amount::from(100u64); + let inputs_fee = Amount::from(1u64); + let keyset_id = Id::from_str("001711afb1de20cb").unwrap(); + + // Create dummy blinded message + let blinded_secret = SecretKey::generate().public_key(); + let blinded_message = cashu::BlindedMessage { + blinded_secret, + keyset_id, + amount: Amount::from(100u64), + witness: None, + }; + let blinded_messages = vec![blinded_message]; + + // Insert melt request + let mut tx1 = Database::begin_transaction(&db).await.unwrap(); + let quote = MeltQuote::new(MeltPaymentRequest::Bolt11 { bolt11: "lnbc330n1p5d85skpp5344v3ktclujsjl3h09wgsfm7zytumr7h7zhrl857f5w8nv0a52zqdqqcqzzsxqyz5vqrzjqvueefmrckfdwyyu39m0lf24sqzcr9vcrmxrvgfn6empxz7phrjxvrttncqq0lcqqyqqqqlgqqqqqqgq2qsp5j3rrg8kvpemqxtf86j8tjm90wq77c7ende4e5qmrerq4xsg02vhq9qxpqysgqjltywgyk6uc5qcgwh8xnzmawl2tjlhz8d28tgp3yx8xwtz76x0jqkfh6mmq70hervjxs0keun7ur0spldgll29l0dnz3md50d65sfqqqwrwpsu".parse().unwrap() }, cashu::CurrencyUnit::Sat, 33.into(), Amount::ZERO, 0, None, None, cashu::PaymentMethod::Bolt11); + tx1.add_melt_quote(quote.clone()).await.unwrap(); + tx1.add_melt_request("e.id, inputs_amount, inputs_fee) + .await + .unwrap(); + tx1.add_blinded_messages(Some("e.id), &blinded_messages) + .await + .unwrap(); + tx1.commit().await.unwrap(); + + // Simulate processing: get and delete + let mut tx2 = Database::begin_transaction(&db).await.unwrap(); + let _retrieved = tx2 + .get_melt_request_and_blinded_messages("e.id) + .await + .unwrap() + .unwrap(); + tx2.delete_melt_request("e.id).await.unwrap(); + tx2.commit().await.unwrap(); + + // Verify melt_request is deleted + let mut tx3 = Database::begin_transaction(&db).await.unwrap(); + let retrieved = tx3 + .get_melt_request_and_blinded_messages("e.id) + .await + .unwrap(); + assert!(retrieved.is_none()); + tx3.commit().await.unwrap(); +} diff --git a/crates/cdk-common/src/database/mint/test/mod.rs b/crates/cdk-common/src/database/mint/test/mod.rs index abc5d53ec..1bdfdf3c2 100644 --- a/crates/cdk-common/src/database/mint/test/mod.rs +++ b/crates/cdk-common/src/database/mint/test/mod.rs @@ -235,7 +235,11 @@ macro_rules! mint_db_test { reject_over_issue_same_tx, reject_over_issue_different_tx, reject_over_issue_with_payment, - reject_over_issue_with_payment_different_tx + reject_over_issue_with_payment_different_tx, + add_melt_request_unique_blinded_messages, + reject_melt_duplicate_blinded_signature, + reject_duplicate_blinded_message_db_constraint, + cleanup_melt_request_after_processing ); }; ($make_db_fn:ident, $($name:ident),+ $(,)?) => { diff --git a/crates/cdk-sql-common/src/mint/migrations/postgres/20250924215800_migrate_blinded_messages_to_blind_signatures.sql b/crates/cdk-sql-common/src/mint/migrations/postgres/20250924215800_migrate_blinded_messages_to_blind_signatures.sql new file mode 100644 index 000000000..8543cd492 --- /dev/null +++ b/crates/cdk-sql-common/src/mint/migrations/postgres/20250924215800_migrate_blinded_messages_to_blind_signatures.sql @@ -0,0 +1,23 @@ +-- Remove NOT NULL constraint from c column in blind_signature table +ALTER TABLE blind_signature ALTER COLUMN c DROP NOT NULL; + +-- Add signed_time column to blind_signature table +ALTER TABLE blind_signature ADD COLUMN signed_time INTEGER NULL; + +-- Update existing records to set signed_time equal to created_time for existing signatures +UPDATE blind_signature SET signed_time = created_time WHERE c IS NOT NULL; + +-- Insert data from blinded_messages table into blind_signature table with NULL c column +INSERT INTO blind_signature (blinded_message, amount, keyset_id, c, quote_id, created_time, signed_time) +SELECT blinded_message, amount, keyset_id, NULL as c, quote_id, 0 as created_time, NULL as signed_time +FROM blinded_messages +WHERE NOT EXISTS ( + SELECT 1 FROM blind_signature + WHERE blind_signature.blinded_message = blinded_messages.blinded_message +); + +-- Create index on quote_id if it does not exist +CREATE INDEX IF NOT EXISTS blind_signature_quote_id_index ON blind_signature(quote_id); + +-- Drop the blinded_messages table as data has been migrated +DROP TABLE IF EXISTS blinded_messages; diff --git a/crates/cdk-sql-common/src/mint/migrations/sqlite/20250924215800_migrate_blinded_messages_to_blind_signatures.sql b/crates/cdk-sql-common/src/mint/migrations/sqlite/20250924215800_migrate_blinded_messages_to_blind_signatures.sql new file mode 100644 index 000000000..42c0fc936 --- /dev/null +++ b/crates/cdk-sql-common/src/mint/migrations/sqlite/20250924215800_migrate_blinded_messages_to_blind_signatures.sql @@ -0,0 +1,40 @@ +-- Remove NOT NULL constraint from c column in blind_signature table +-- SQLite does not support ALTER COLUMN directly, so we need to recreate the table + +-- Step 1 - Create new table with nullable c column and signed_time column +CREATE TABLE blind_signature_new ( + blinded_message BLOB PRIMARY KEY, + amount INTEGER NOT NULL, + keyset_id TEXT NOT NULL, + c BLOB NULL, + dleq_e TEXT, + dleq_s TEXT, + quote_id TEXT, + created_time INTEGER NOT NULL DEFAULT 0, + signed_time INTEGER +); + +-- Step 2 - Copy existing data from old blind_signature table +INSERT INTO blind_signature_new (blinded_message, amount, keyset_id, c, dleq_e, dleq_s, quote_id, created_time) +SELECT blinded_message, amount, keyset_id, c, dleq_e, dleq_s, quote_id, created_time +FROM blind_signature; + +-- Step 3 - Insert data from blinded_messages table with NULL c column +INSERT INTO blind_signature_new (blinded_message, amount, keyset_id, c, quote_id, created_time) +SELECT blinded_message, amount, keyset_id, NULL as c, quote_id, 0 as created_time +FROM blinded_messages +WHERE NOT EXISTS ( + SELECT 1 FROM blind_signature_new + WHERE blind_signature_new.blinded_message = blinded_messages.blinded_message +); + +-- Step 4 - Drop old table and rename new table +DROP TABLE blind_signature; +ALTER TABLE blind_signature_new RENAME TO blind_signature; + +-- Step 5 - Recreate indexes +CREATE INDEX IF NOT EXISTS keyset_id_index ON blind_signature(keyset_id); +CREATE INDEX IF NOT EXISTS blind_signature_quote_id_index ON blind_signature(quote_id); + +-- Step 6 - Drop the blinded_messages table as data has been migrated +DROP TABLE IF EXISTS blinded_messages; diff --git a/crates/cdk-sql-common/src/mint/mod.rs b/crates/cdk-sql-common/src/mint/mod.rs index b3bef8d88..a1d7ed932 100644 --- a/crates/cdk-sql-common/src/mint/mod.rs +++ b/crates/cdk-sql-common/src/mint/mod.rs @@ -546,13 +546,13 @@ where { type Err = Error; - async fn add_melt_request_and_blinded_messages( + async fn add_melt_request( &mut self, quote_id: &QuoteId, inputs_amount: Amount, inputs_fee: Amount, - blinded_messages: &[BlindedMessage], ) -> Result<(), Self::Err> { + // Insert melt_request query( r#" INSERT INTO melt_request @@ -567,26 +567,79 @@ where .execute(&self.inner) .await?; + Ok(()) + } + + async fn add_blinded_messages( + &mut self, + quote_id: Option<&QuoteId>, + blinded_messages: &[BlindedMessage], + ) -> Result<(), Self::Err> { + let current_time = unix_time(); + + // Insert blinded_messages directly into blind_signature with c = NULL + // Let the database constraint handle duplicate detection for message in blinded_messages { - query( + match query( r#" - INSERT INTO blinded_messages - (quote_id, blinded_message, keyset_id, amount) + INSERT INTO blind_signature + (blinded_message, amount, keyset_id, c, quote_id, created_time) VALUES - (:quote_id, :blinded_message, :keyset_id, :amount) + (:blinded_message, :amount, :keyset_id, NULL, :quote_id, :created_time) "#, )? - .bind("quote_id", quote_id.to_string()) .bind( "blinded_message", message.blinded_secret.to_bytes().to_vec(), ) - .bind("keyset_id", message.keyset_id.to_string()) .bind("amount", message.amount.to_i64()) + .bind("keyset_id", message.keyset_id.to_string()) + .bind("quote_id", quote_id.map(|q| q.to_string())) + .bind("created_time", current_time as i64) .execute(&self.inner) - .await?; + .await + { + Ok(_) => continue, + Err(database::Error::Duplicate) => { + // Primary key constraint violation - blinded message already exists + // This could be either: + // 1. Already signed (c IS NOT NULL) - definitely an error + // 2. Already pending (c IS NULL) - also an error + return Err(database::Error::Duplicate); + } + Err(err) => return Err(err), + } + } + + Ok(()) + } + + async fn delete_blinded_messages( + &mut self, + blinded_secrets: &[PublicKey], + ) -> Result<(), Self::Err> { + if blinded_secrets.is_empty() { + return Ok(()); } + // Delete blinded messages from blind_signature table where c IS NULL + // (only delete unsigned blinded messages) + query( + r#" + DELETE FROM blind_signature + WHERE blinded_message IN (:blinded_secrets) AND c IS NULL + "#, + )? + .bind_vec( + "blinded_secrets", + blinded_secrets + .iter() + .map(|secret| secret.to_bytes().to_vec()) + .collect(), + ) + .execute(&self.inner) + .await?; + Ok(()) } @@ -610,11 +663,12 @@ where let inputs_amount: u64 = column_as_number!(row[0].clone()); let inputs_fee: u64 = column_as_number!(row[1].clone()); + // Get blinded messages from blind_signature table where c IS NULL let blinded_messages_rows = query( r#" SELECT blinded_message, keyset_id, amount - FROM blinded_messages - WHERE quote_id = :quote_id + FROM blind_signature + WHERE quote_id = :quote_id AND c IS NULL "#, )? .bind("quote_id", quote_id.to_string()) @@ -650,6 +704,7 @@ where } async fn delete_melt_request(&mut self, quote_id: &QuoteId) -> Result<(), Self::Err> { + // Delete from melt_request table query( r#" DELETE FROM melt_request @@ -660,6 +715,17 @@ where .execute(&self.inner) .await?; + // Also delete blinded messages (where c IS NULL) from blind_signature table + query( + r#" + DELETE FROM blind_signature + WHERE quote_id = :quote_id AND c IS NULL + "#, + )? + .bind("quote_id", quote_id.to_string()) + .execute(&self.inner) + .await?; + Ok(()) } @@ -1560,34 +1626,122 @@ where ) -> Result<(), Self::Err> { let current_time = unix_time(); + if blinded_messages.len() != blind_signatures.len() { + return Err(database::Error::Internal( + "Mismatched array lengths for blinded messages and blind signatures".to_string(), + )); + } + + // Select all existing rows for the given blinded messages at once + let mut existing_rows = query( + r#" + SELECT blinded_message, c, dleq_e, dleq_s + FROM blind_signature + WHERE blinded_message IN (:blinded_messages) + FOR UPDATE + "#, + )? + .bind_vec( + "blinded_messages", + blinded_messages + .iter() + .map(|message| message.to_bytes().to_vec()) + .collect(), + ) + .fetch_all(&self.inner) + .await? + .into_iter() + .map(|mut row| { + Ok(( + column_as_string!(&row.remove(0), PublicKey::from_hex, PublicKey::from_slice), + (row[0].clone(), row[1].clone(), row[2].clone()), + )) + }) + .collect::, Error>>()?; + + // Iterate over the provided blinded messages and signatures for (message, signature) in blinded_messages.iter().zip(blind_signatures) { - query( - r#" - INSERT INTO blind_signature - (blinded_message, amount, keyset_id, c, quote_id, dleq_e, dleq_s, created_time) - VALUES - (:blinded_message, :amount, :keyset_id, :c, :quote_id, :dleq_e, :dleq_s, :created_time) - "#, - )? - .bind("blinded_message", message.to_bytes().to_vec()) - .bind("amount", u64::from(signature.amount) as i64) - .bind("keyset_id", signature.keyset_id.to_string()) - .bind("c", signature.c.to_bytes().to_vec()) - .bind("quote_id", quote_id.as_ref().map(|q| match q { - QuoteId::BASE64(s) => s.to_string(), - QuoteId::UUID(u) => u.hyphenated().to_string(), - })) - .bind( - "dleq_e", - signature.dleq.as_ref().map(|dleq| dleq.e.to_secret_hex()), - ) - .bind( - "dleq_s", - signature.dleq.as_ref().map(|dleq| dleq.s.to_secret_hex()), - ) - .bind("created_time", current_time as i64) - .execute(&self.inner) - .await?; + match existing_rows.remove(message) { + None => { + // Unknown blind message: Insert new row with all columns + query( + r#" + INSERT INTO blind_signature + (blinded_message, amount, keyset_id, c, quote_id, dleq_e, dleq_s, created_time, signed_time) + VALUES + (:blinded_message, :amount, :keyset_id, :c, :quote_id, :dleq_e, :dleq_s, :created_time, :signed_time) + "#, + )? + .bind("blinded_message", message.to_bytes().to_vec()) + .bind("amount", u64::from(signature.amount) as i64) + .bind("keyset_id", signature.keyset_id.to_string()) + .bind("c", signature.c.to_bytes().to_vec()) + .bind("quote_id", quote_id.as_ref().map(|q| q.to_string())) + .bind( + "dleq_e", + signature.dleq.as_ref().map(|dleq| dleq.e.to_secret_hex()), + ) + .bind( + "dleq_s", + signature.dleq.as_ref().map(|dleq| dleq.s.to_secret_hex()), + ) + .bind("created_time", current_time as i64) + .bind("signed_time", current_time as i64) + .execute(&self.inner) + .await?; + } + Some((c, _dleq_e, _dleq_s)) => { + // Blind message exists: check if c is NULL + match c { + Column::Null => { + // Blind message with no c: Update with missing columns c, dleq_e, dleq_s + query( + r#" + UPDATE blind_signature + SET c = :c, dleq_e = :dleq_e, dleq_s = :dleq_s, signed_time = :signed_time, amount = :amount + WHERE blinded_message = :blinded_message + "#, + )? + .bind("c", signature.c.to_bytes().to_vec()) + .bind( + "dleq_e", + signature.dleq.as_ref().map(|dleq| dleq.e.to_secret_hex()), + ) + .bind( + "dleq_s", + signature.dleq.as_ref().map(|dleq| dleq.s.to_secret_hex()), + ) + .bind("blinded_message", message.to_bytes().to_vec()) + .bind("signed_time", current_time as i64) + .bind("amount", u64::from(signature.amount) as i64) + .execute(&self.inner) + .await?; + } + _ => { + // Blind message already has c: Error + tracing::error!( + "Attempting to add signature to message already signed {}", + message + ); + + return Err(database::Error::Duplicate); + } + } + } + } + } + + debug_assert!( + existing_rows.is_empty(), + "Unexpected existing rows remain: {:?}", + existing_rows.keys().collect::>() + ); + + if !existing_rows.is_empty() { + tracing::error!("Did not check all existing rows"); + return Err(Error::Internal( + "Did not check all existing rows".to_string(), + )); } Ok(()) @@ -1607,14 +1761,14 @@ where blinded_message FROM blind_signature - WHERE blinded_message IN (:y) + WHERE blinded_message IN (:b) AND c IS NOT NULL "#, )? .bind_vec( - "y", + "b", blinded_messages .iter() - .map(|y| y.to_bytes().to_vec()) + .map(|b| b.to_bytes().to_vec()) .collect(), ) .fetch_all(&self.inner) @@ -1660,11 +1814,11 @@ where blinded_message FROM blind_signature - WHERE blinded_message IN (:blinded_message) + WHERE blinded_message IN (:b) AND c IS NOT NULL "#, )? .bind_vec( - "blinded_message", + "b", blinded_messages .iter() .map(|b_| b_.to_bytes().to_vec()) @@ -1706,7 +1860,7 @@ where FROM blind_signature WHERE - keyset_id=:keyset_id + keyset_id=:keyset_id AND c IS NOT NULL "#, )? .bind("keyset_id", keyset_id.to_string()) @@ -1734,7 +1888,7 @@ where FROM blind_signature WHERE - quote_id=:quote_id + quote_id=:quote_id AND c IS NOT NULL "#, )? .bind("quote_id", quote_id.to_string()) diff --git a/crates/cdk/src/mint/blinded_message_writer.rs b/crates/cdk/src/mint/blinded_message_writer.rs new file mode 100644 index 000000000..c7f81751c --- /dev/null +++ b/crates/cdk/src/mint/blinded_message_writer.rs @@ -0,0 +1,152 @@ +//! Blinded message writer +use std::collections::HashSet; + +use cdk_common::database::{self, DynMintDatabase, MintTransaction}; +use cdk_common::nuts::BlindedMessage; +use cdk_common::{Error, PublicKey, QuoteId}; + +type Tx<'a, 'b> = Box + Send + Sync + 'b>; + +/// Blinded message writer +/// +/// This is a blinded message writer that emulates a database transaction but without holding the +/// transaction alive while waiting for external events to be fully committed to the database; +/// instead, it maintains a `pending` state. +/// +/// This struct allows for premature exit on error, enabling it to remove blinded messages that +/// were added during the operation. +/// +/// This struct is not fully ACID. If the process exits due to a panic, and the `Drop` function +/// cannot be run, the cleanup process should reset the state. +pub struct BlindedMessageWriter { + db: Option, + added_blinded_secrets: Option>, +} + +impl BlindedMessageWriter { + /// Creates a new BlindedMessageWriter on top of the database + pub fn new(db: DynMintDatabase) -> Self { + Self { + db: Some(db), + added_blinded_secrets: Some(Default::default()), + } + } + + /// The changes are permanent, consume the struct removing the database, so the Drop does + /// nothing + pub fn commit(mut self) { + self.db.take(); + self.added_blinded_secrets.take(); + } + + /// Add blinded messages + pub async fn add_blinded_messages( + &mut self, + tx: &mut Tx<'_, '_>, + quote_id: Option, + blinded_messages: &[BlindedMessage], + ) -> Result, Error> { + let added_secrets = if let Some(secrets) = self.added_blinded_secrets.as_mut() { + secrets + } else { + return Err(Error::Internal); + }; + + if let Some(err) = tx + .add_blinded_messages(quote_id.as_ref(), blinded_messages) + .await + .err() + { + return match err { + cdk_common::database::Error::Duplicate => Err(Error::DuplicateOutputs), + err => Err(Error::Database(err)), + }; + } + + let blinded_secrets: Vec = blinded_messages + .iter() + .map(|bm| bm.blinded_secret) + .collect(); + + for blinded_secret in &blinded_secrets { + added_secrets.insert(*blinded_secret); + } + + Ok(blinded_secrets) + } + + /// Rollback all changes in this BlindedMessageWriter consuming it. + pub async fn rollback(mut self) -> Result<(), Error> { + let db = if let Some(db) = self.db.take() { + db + } else { + return Ok(()); + }; + let mut tx = db.begin_transaction().await?; + let blinded_secrets: Vec = + if let Some(secrets) = self.added_blinded_secrets.take() { + secrets.into_iter().collect() + } else { + return Ok(()); + }; + + if !blinded_secrets.is_empty() { + tracing::info!("Rollback {} blinded messages", blinded_secrets.len(),); + + remove_blinded_messages(&mut tx, &blinded_secrets).await?; + } + + tx.commit().await?; + + Ok(()) + } +} + +/// Removes blinded messages from the database +#[inline(always)] +async fn remove_blinded_messages( + tx: &mut Tx<'_, '_>, + blinded_secrets: &[PublicKey], +) -> Result<(), Error> { + tx.delete_blinded_messages(blinded_secrets) + .await + .map_err(Error::Database) +} + +#[inline(always)] +async fn rollback_blinded_messages( + db: DynMintDatabase, + blinded_secrets: Vec, +) -> Result<(), Error> { + let mut tx = db.begin_transaction().await?; + remove_blinded_messages(&mut tx, &blinded_secrets).await?; + tx.commit().await?; + + Ok(()) +} + +impl Drop for BlindedMessageWriter { + fn drop(&mut self) { + let db = if let Some(db) = self.db.take() { + db + } else { + tracing::debug!("Blinded message writer dropped after commit, no need to rollback."); + return; + }; + let blinded_secrets: Vec = + if let Some(secrets) = self.added_blinded_secrets.take() { + secrets.into_iter().collect() + } else { + return; + }; + + if !blinded_secrets.is_empty() { + tracing::debug!("Blinded message writer dropper with messages attempting to remove."); + tokio::spawn(async move { + if let Err(err) = rollback_blinded_messages(db, blinded_secrets).await { + tracing::error!("Failed to rollback blinded messages in Drop: {}", err); + } + }); + } + } +} diff --git a/crates/cdk/src/mint/melt.rs b/crates/cdk/src/mint/melt.rs index f237a7005..166e554f3 100644 --- a/crates/cdk/src/mint/melt.rs +++ b/crates/cdk/src/mint/melt.rs @@ -636,10 +636,15 @@ impl Mint { let inputs_fee = self.get_proofs_fee(melt_request.inputs()).await?; - tx.add_melt_request_and_blinded_messages( + tx.add_melt_request( melt_request.quote_id(), melt_request.inputs_amount()?, inputs_fee, + ) + .await?; + + tx.add_blinded_messages( + Some(melt_request.quote_id()), melt_request.outputs().as_ref().unwrap_or(&Vec::new()), ) .await?; @@ -997,6 +1002,9 @@ impl Mint { change = Some(change_sigs); proof_writer.commit(); + + tx.delete_melt_request("e.id).await?; + tx.commit().await?; } else { tracing::info!( @@ -1006,11 +1014,13 @@ impl Mint { total_spent ); proof_writer.commit(); + tx.delete_melt_request("e.id).await?; tx.commit().await?; } } else { tracing::debug!("No change required for melt {}", quote.id); proof_writer.commit(); + tx.delete_melt_request("e.id).await?; tx.commit().await?; } diff --git a/crates/cdk/src/mint/mod.rs b/crates/cdk/src/mint/mod.rs index 3f99691cf..f93be3b65 100644 --- a/crates/cdk/src/mint/mod.rs +++ b/crates/cdk/src/mint/mod.rs @@ -34,6 +34,7 @@ use crate::{cdk_database, Amount}; #[cfg(feature = "auth")] pub(crate) mod auth; +mod blinded_message_writer; mod builder; mod check_spendable; mod issue; diff --git a/crates/cdk/src/mint/swap.rs b/crates/cdk/src/mint/swap.rs index 0cab12a31..8b3cc3711 100644 --- a/crates/cdk/src/mint/swap.rs +++ b/crates/cdk/src/mint/swap.rs @@ -2,6 +2,7 @@ use cdk_prometheus::METRICS; use tracing::instrument; +use super::blinded_message_writer::BlindedMessageWriter; use super::nut11::{enforce_sig_flag, EnforceSigFlag}; use super::proof_writer::ProofWriter; use super::{Mint, PublicKey, SigFlag, State, SwapRequest, SwapResponse}; @@ -21,11 +22,41 @@ impl Mint { swap_request.input_amount()?; swap_request.output_amount()?; + // We add blinded messages to db before attempting to sign + // this ensures that they are unique and have not been used before + let mut blinded_message_writer = BlindedMessageWriter::new(self.localstore.clone()); + let mut tx = self.localstore.begin_transaction().await?; + + match blinded_message_writer + .add_blinded_messages(&mut tx, None, swap_request.outputs()) + .await + { + Ok(_) => { + tx.commit().await?; + } + Err(err) => { + #[cfg(feature = "prometheus")] + { + METRICS.dec_in_flight_requests("process_swap_request"); + METRICS.record_mint_operation("process_swap_request", false); + METRICS.record_error(); + } + return Err(err); + } + } + let promises = self.blind_sign(swap_request.outputs().to_owned()).await?; let input_verification = self.verify_inputs(swap_request.inputs()) .await .map_err(|err| { + #[cfg(feature = "prometheus")] + { + METRICS.dec_in_flight_requests("process_swap_request"); + METRICS.record_mint_operation("process_swap_request", false); + METRICS.record_error(); + } + tracing::debug!("Input verification failed: {:?}", err); err })?; @@ -49,14 +80,21 @@ impl Mint { METRICS.record_error(); } + tx.rollback().await?; + blinded_message_writer.rollback().await?; + return Err(err); }; let validate_sig_result = self.validate_sig_flag(&swap_request).await; - if validate_sig_result.is_err() { + + if let Err(err) = validate_sig_result { + tx.rollback().await?; + blinded_message_writer.rollback().await?; + #[cfg(feature = "prometheus")] self.record_swap_failure("process_swap_request"); - return Err(validate_sig_result.err().unwrap()); + return Err(err); } let mut proof_writer = ProofWriter::new(self.localstore.clone(), self.pubsub_manager.clone()); @@ -72,6 +110,8 @@ impl Mint { METRICS.record_mint_operation("process_swap_request", false); METRICS.record_error(); } + tx.rollback().await?; + blinded_message_writer.rollback().await?; return Err(err); } }; @@ -80,10 +120,13 @@ impl Mint { .update_proofs_states(&mut tx, &input_ys, State::Spent) .await; - if update_proof_states_result.is_err() { + if let Err(err) = update_proof_states_result { #[cfg(feature = "prometheus")] self.record_swap_failure("process_swap_request"); - return Err(update_proof_states_result.err().unwrap()); + + tx.rollback().await?; + blinded_message_writer.rollback().await?; + return Err(err); } tx.add_blind_signatures( @@ -98,6 +141,7 @@ impl Mint { .await?; proof_writer.commit(); + blinded_message_writer.commit(); tx.commit().await?; let response = SwapResponse::new(promises); From f3235440409190338d81dddc85e22e9d2967c80e Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Sun, 28 Sep 2025 15:24:55 +0100 Subject: [PATCH 192/321] fix: lnbits msats error (#1134) * fix: lnbits msats error * fix: lnbits msats error --- crates/cdk-lnbits/src/lib.rs | 16 +++------------- 1 file changed, 3 insertions(+), 13 deletions(-) diff --git a/crates/cdk-lnbits/src/lib.rs b/crates/cdk-lnbits/src/lib.rs index 2f5f84bba..fec078c39 100644 --- a/crates/cdk-lnbits/src/lib.rs +++ b/crates/cdk-lnbits/src/lib.rs @@ -11,7 +11,7 @@ use std::sync::Arc; use anyhow::anyhow; use async_trait::async_trait; -use cdk_common::amount::{to_unit, Amount, MSAT_IN_SAT}; +use cdk_common::amount::{to_unit, Amount}; use cdk_common::common::FeeReserve; use cdk_common::nuts::{CurrencyUnit, MeltOptions, MeltQuoteState}; use cdk_common::payment::{ @@ -191,10 +191,6 @@ impl MintPayment for LNbits { unit: &CurrencyUnit, options: OutgoingPaymentOptions, ) -> Result { - if unit != &CurrencyUnit::Sat { - return Err(Self::Err::Anyhow(anyhow!("Unsupported unit"))); - } - match options { OutgoingPaymentOptions::Bolt11(bolt11_options) => { let amount_msat = match bolt11_options.melt_options { @@ -211,10 +207,8 @@ impl MintPayment for LNbits { .into(), }; - let amount = amount_msat / MSAT_IN_SAT.into(); - let relative_fee_reserve = - (self.fee_reserve.percent_fee_reserve * u64::from(amount) as f32) as u64; + (self.fee_reserve.percent_fee_reserve * u64::from(amount_msat) as f32) as u64; let absolute_fee_reserve: u64 = self.fee_reserve.min_fee_reserve.into(); @@ -224,7 +218,7 @@ impl MintPayment for LNbits { request_lookup_id: Some(PaymentIdentifier::PaymentHash( *bolt11_options.bolt11.payment_hash().as_ref(), )), - amount, + amount: to_unit(amount_msat, &CurrencyUnit::Msat, unit)?, fee: fee.into(), state: MeltQuoteState::Unpaid, unit: unit.clone(), @@ -302,10 +296,6 @@ impl MintPayment for LNbits { unit: &CurrencyUnit, options: IncomingPaymentOptions, ) -> Result { - if unit != &CurrencyUnit::Sat { - return Err(Self::Err::Anyhow(anyhow!("Unsupported unit"))); - } - match options { IncomingPaymentOptions::Bolt11(bolt11_options) => { let description = bolt11_options.description.unwrap_or_default(); From 5e93529398f4bdad17412b52dcd01b18f5409352 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Tue, 30 Sep 2025 09:12:29 +0100 Subject: [PATCH 193/321] fix: show ammounts (#1136) --- crates/cdk-cli/src/sub_commands/melt.rs | 143 +++++++++++++----------- crates/cdk-cli/src/sub_commands/send.rs | 102 +++++++++++------ 2 files changed, 143 insertions(+), 102 deletions(-) diff --git a/crates/cdk-cli/src/sub_commands/melt.rs b/crates/cdk-cli/src/sub_commands/melt.rs index a07db2ff9..39d7c867b 100644 --- a/crates/cdk-cli/src/sub_commands/melt.rs +++ b/crates/cdk-cli/src/sub_commands/melt.rs @@ -71,6 +71,50 @@ pub async fn pay( bail!("No funds available"); } + // Determine which mint to use for melting BEFORE processing payment (unless using MPP) + let selected_mint = if sub_command_args.mpp { + None // MPP mode handles mint selection differently + } else if let Some(mint_url) = &sub_command_args.mint_url { + Some(MintUrl::from_str(mint_url)?) + } else { + // Display all mints with their balances and let user select + let balances_map = multi_mint_wallet.get_balances().await?; + if balances_map.is_empty() { + bail!("No mints available in the wallet"); + } + + let balances_vec: Vec<(MintUrl, Amount)> = balances_map.into_iter().collect(); + + println!("\nAvailable mints and balances:"); + for (index, (mint_url, balance)) in balances_vec.iter().enumerate() { + println!( + " {}: {} - {} {}", + index, + mint_url, + balance, + multi_mint_wallet.unit() + ); + } + println!(" {}: Any mint (auto-select best)", balances_vec.len()); + + let selection = loop { + let selection: usize = + get_number_input("Enter mint number to melt from (or select Any)")?; + + if selection == balances_vec.len() { + break None; // "Any" option selected + } + + if let Some((mint_url, _)) = balances_vec.get(selection) { + break Some(mint_url.clone()); + } + + println!("Invalid selection, please try again."); + }; + + selection + }; + if sub_command_args.mpp { // Manual MPP - user specifies which mints and amounts to use if !matches!(sub_command_args.method, PaymentType::Bolt11) { @@ -180,12 +224,9 @@ pub async fn pay( let options = create_melt_options(available_funds, bolt11.amount_milli_satoshis(), &prompt)?; - // Use mint-specific functions or auto-select - let melted = if let Some(mint_url) = &sub_command_args.mint_url { - // User specified a mint - use the new mint-specific functions - let mint_url = MintUrl::from_str(mint_url)?; - - // Create a melt quote for the specific mint + // Use selected mint or auto-select + let melted = if let Some(mint_url) = selected_mint { + // User selected a specific mint - use the new mint-specific functions let quote = multi_mint_wallet .melt_quote(&mint_url, bolt11_str.clone(), options) .await?; @@ -200,7 +241,7 @@ pub async fn pay( .melt_with_mint(&mint_url, "e.id) .await? } else { - // Let the wallet automatically select the best mint + // User selected "Any" - let the wallet auto-select the best mint multi_mint_wallet.melt(&bolt11_str, options, None).await? }; @@ -227,41 +268,25 @@ pub async fn pay( let options = create_melt_options(available_funds, amount_msat, &prompt)?; - // Get wallet for BOLT12 - let wallet = if let Some(mint_url) = &sub_command_args.mint_url { - // User specified a mint - let mint_url = MintUrl::from_str(mint_url)?; - multi_mint_wallet - .get_wallet(&mint_url) - .await - .ok_or_else(|| anyhow::anyhow!("Mint {} not found", mint_url))? + // Get wallet for BOLT12 using the selected mint + let mint_url = if let Some(specific_mint) = selected_mint { + specific_mint } else { - // Show available mints and let user select + // User selected "Any" - just pick the first mint with any balance let balances = multi_mint_wallet.get_balances().await?; - println!("\nAvailable mints:"); - for (i, (mint_url, balance)) in balances.iter().enumerate() { - println!( - " {}: {} - {} {}", - i, - mint_url, - balance, - multi_mint_wallet.unit() - ); - } - - let mint_number: usize = get_number_input("Enter mint number to melt from")?; - let selected_mint = balances - .iter() - .nth(mint_number) - .map(|(url, _)| url) - .ok_or_else(|| anyhow::anyhow!("Invalid mint number"))?; - multi_mint_wallet - .get_wallet(selected_mint) - .await - .ok_or_else(|| anyhow::anyhow!("Mint {} not found", selected_mint))? + balances + .into_iter() + .find(|(_, balance)| *balance > Amount::ZERO) + .map(|(mint_url, _)| mint_url) + .ok_or_else(|| anyhow::anyhow!("No mint available for BOLT12 payment"))? }; + let wallet = multi_mint_wallet + .get_wallet(&mint_url) + .await + .ok_or_else(|| anyhow::anyhow!("Mint {} not found", mint_url))?; + // Get melt quote for BOLT12 let quote = wallet.melt_bolt12_quote(offer_str, options).await?; @@ -293,41 +318,25 @@ pub async fn pay( // BIP353 payments are always amountless for now let options = create_melt_options(available_funds, None, &prompt)?; - // Get wallet for BIP353 - let wallet = if let Some(mint_url) = &sub_command_args.mint_url { - // User specified a mint - let mint_url = MintUrl::from_str(mint_url)?; - multi_mint_wallet - .get_wallet(&mint_url) - .await - .ok_or_else(|| anyhow::anyhow!("Mint {} not found", mint_url))? + // Get wallet for BIP353 using the selected mint + let mint_url = if let Some(specific_mint) = selected_mint { + specific_mint } else { - // Show available mints and let user select + // User selected "Any" - just pick the first mint with any balance let balances = multi_mint_wallet.get_balances().await?; - println!("\nAvailable mints:"); - for (i, (mint_url, balance)) in balances.iter().enumerate() { - println!( - " {}: {} - {} {}", - i, - mint_url, - balance, - multi_mint_wallet.unit() - ); - } - - let mint_number: usize = get_number_input("Enter mint number to melt from")?; - let selected_mint = balances - .iter() - .nth(mint_number) - .map(|(url, _)| url) - .ok_or_else(|| anyhow::anyhow!("Invalid mint number"))?; - multi_mint_wallet - .get_wallet(selected_mint) - .await - .ok_or_else(|| anyhow::anyhow!("Mint {} not found", selected_mint))? + balances + .into_iter() + .find(|(_, balance)| *balance > Amount::ZERO) + .map(|(mint_url, _)| mint_url) + .ok_or_else(|| anyhow::anyhow!("No mint available for BIP353 payment"))? }; + let wallet = multi_mint_wallet + .get_wallet(&mint_url) + .await + .ok_or_else(|| anyhow::anyhow!("Mint {} not found", mint_url))?; + // Get melt quote for BIP353 address (internally resolves and gets BOLT12 quote) let quote = wallet .melt_bip353_quote( diff --git a/crates/cdk-cli/src/sub_commands/send.rs b/crates/cdk-cli/src/sub_commands/send.rs index 0c8fb61f2..8e2dc4af5 100644 --- a/crates/cdk-cli/src/sub_commands/send.rs +++ b/crates/cdk-cli/src/sub_commands/send.rs @@ -54,9 +54,7 @@ pub struct SendSubCommand { /// Maximum amount to transfer from other mints #[arg(long)] max_transfer_amount: Option, - /// Specific mints allowed for transfers (can be specified multiple times) - #[arg(long, action = clap::ArgAction::Append)] - allowed_mints: Vec, + /// Specific mints to exclude from transfers (can be specified multiple times) #[arg(long, action = clap::ArgAction::Append)] excluded_mints: Vec, @@ -66,6 +64,48 @@ pub async fn send( multi_mint_wallet: &MultiMintWallet, sub_command_args: &SendSubCommand, ) -> Result<()> { + // Determine which mint to use for sending BEFORE asking for amount + let selected_mint = if let Some(mint_url) = &sub_command_args.mint_url { + Some(MintUrl::from_str(mint_url)?) + } else { + // Display all mints with their balances and let user select + let balances_map = multi_mint_wallet.get_balances().await?; + if balances_map.is_empty() { + return Err(anyhow!("No mints available in the wallet")); + } + + let balances_vec: Vec<(MintUrl, Amount)> = balances_map.into_iter().collect(); + + println!("\nAvailable mints and balances:"); + for (index, (mint_url, balance)) in balances_vec.iter().enumerate() { + println!( + " {}: {} - {} {}", + index, + mint_url, + balance, + multi_mint_wallet.unit() + ); + } + println!(" {}: Any mint (auto-select best)", balances_vec.len()); + + let selection = loop { + let selection: usize = + get_number_input("Enter mint number to send from (or select Any)")?; + + if selection == balances_vec.len() { + break None; // "Any" option selected + } + + if let Some((mint_url, _)) = balances_vec.get(selection) { + break Some(mint_url.clone()); + } + + println!("Invalid selection, please try again."); + }; + + selection + }; + let token_amount = Amount::from(get_number_input::(&format!( "Enter value of token in {}", multi_mint_wallet.unit() @@ -214,14 +254,7 @@ pub async fn send( ..Default::default() }; - // Parse allowed and excluded mints from CLI arguments - let allowed_mints: Result, _> = sub_command_args - .allowed_mints - .iter() - .map(|url| MintUrl::from_str(url)) - .collect(); - let allowed_mints = allowed_mints?; - + // Parse excluded mints from CLI arguments let excluded_mints: Result, _> = sub_command_args .excluded_mints .iter() @@ -229,45 +262,44 @@ pub async fn send( .collect(); let excluded_mints = excluded_mints?; - // Create MultiMintSendOptions from CLI arguments - let multi_mint_options = cdk::wallet::multi_mint_wallet::MultiMintSendOptions { - allow_transfer: sub_command_args.allow_transfer, - max_transfer_amount: sub_command_args.max_transfer_amount.map(Amount::from), - allowed_mints, - excluded_mints, - send_options: send_options.clone(), - }; + // Prepare and confirm the send based on mint selection + let token = if let Some(specific_mint) = selected_mint { + // User selected a specific mint + let multi_mint_options = cdk::wallet::multi_mint_wallet::MultiMintSendOptions { + allow_transfer: sub_command_args.allow_transfer, + max_transfer_amount: sub_command_args.max_transfer_amount.map(Amount::from), + allowed_mints: vec![specific_mint.clone()], // Use selected mint as the only allowed mint + excluded_mints, + send_options: send_options.clone(), + }; - // Use the new unified interface - let token = if let Some(mint_url) = &sub_command_args.mint_url { - // User specified a mint, use that specific wallet - let mint_url = cdk::mint_url::MintUrl::from_str(mint_url)?; let prepared = multi_mint_wallet - .prepare_send(mint_url, token_amount, multi_mint_options) + .prepare_send(specific_mint, token_amount, multi_mint_options) .await?; - // Confirm the prepared send (single mint) let memo = send_options.memo.clone(); prepared.confirm(memo).await? } else { - // Let the wallet automatically select the best mint - // First, get balances to find a mint with sufficient funds + // User selected "Any" - find the first mint with sufficient balance let balances = multi_mint_wallet.get_balances().await?; - - // Find a mint with sufficient balance - let mint_url = balances + let best_mint = balances .into_iter() .find(|(_, balance)| *balance >= token_amount) .map(|(mint_url, _)| mint_url) - .ok_or_else(|| { - anyhow::anyhow!("No mint has sufficient balance for the requested amount") - })?; + .ok_or_else(|| anyhow!("No mint has sufficient balance for the requested amount"))?; + + let multi_mint_options = cdk::wallet::multi_mint_wallet::MultiMintSendOptions { + allow_transfer: sub_command_args.allow_transfer, + max_transfer_amount: sub_command_args.max_transfer_amount.map(Amount::from), + allowed_mints: vec![best_mint.clone()], // Use the best mint as the only allowed mint + excluded_mints, + send_options: send_options.clone(), + }; let prepared = multi_mint_wallet - .prepare_send(mint_url, token_amount, multi_mint_options) + .prepare_send(best_mint, token_amount, multi_mint_options) .await?; - // Confirm the prepared send (multi mint) let memo = send_options.memo.clone(); prepared.confirm(memo).await? }; From ddec3bb212d326e0a72003c96dba5eaa3bb0656b Mon Sep 17 00:00:00 2001 From: David Caseria Date: Tue, 30 Sep 2025 04:12:53 -0400 Subject: [PATCH 194/321] Update README with missing crates (#1140) --- README.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/README.md b/README.md index ae01fc79f..31ff04b14 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,7 @@ CDK is a collection of rust crates for [Cashu](https://github.com/cashubtc) wall The project is split up into several crates in the `crates/` directory: * Libraries: + * [**cashu**](./crates/cashu/): Core Cashu protocol implementation. * [**cdk**](./crates/cdk/): Rust implementation of Cashu protocol. * [**cdk-sqlite**](./crates/cdk-sqlite/): SQLite Storage backend. * [**cdk-postgres**](./crates/cdk-postgres/): PostgreSQL Storage backend. @@ -25,6 +26,13 @@ The project is split up into several crates in the `crates/` directory: * [**cdk-lnbits**](./crates/cdk-lnbits/): [LNbits](https://lnbits.com/) Lightning backend for mint. **Note: Only LNBits v1 API is supported.** * [**cdk-ldk-node**](./crates/cdk-ldk-node/): LDK Node Lightning backend for mint. * [**cdk-fake-wallet**](./crates/cdk-fake-wallet/): Fake Lightning backend for mint. To be used only for testing, quotes are automatically filled. + * [**cdk-common**](./crates/cdk-common/): Common utilities and shared code. + * [**cdk-sql-common**](./crates/cdk-sql-common/): Common SQL utilities for storage backends. + * [**cdk-signatory**](./crates/cdk-signatory/): Signing utilities and cryptographic operations. + * [**cdk-payment-processor**](./crates/cdk-payment-processor/): Payment processing functionality. + * [**cdk-prometheus**](./crates/cdk-prometheus/): Prometheus metrics integration. + * [**cdk-ffi**](./crates/cdk-ffi/): Foreign Function Interface bindings for other languages. + * [**cdk-integration-tests**](./crates/cdk-integration-tests/): Integration test suite. * [**cdk-mint-rpc**](./crates/cdk-mint-rpc/): Mint management gRPC server and cli. * Binaries: * [**cdk-cli**](./crates/cdk-cli/): Cashu wallet CLI. From cb2e534f81bdda30d9d59150c603b3c966ddc7bf Mon Sep 17 00:00:00 2001 From: asmo Date: Tue, 30 Sep 2025 15:14:28 +0200 Subject: [PATCH 195/321] feat: added postgres to ffi (#1117) * feat: added postgres to ffi --- crates/cdk-ffi/Cargo.toml | 6 + crates/cdk-ffi/src/database.rs | 406 +----------------- crates/cdk-ffi/src/lib.rs | 2 + crates/cdk-ffi/src/postgres.rs | 401 +++++++++++++++++ crates/cdk-ffi/src/sqlite.rs | 402 +++++++++++++++++ .../tests/ffi_minting_integration.rs | 2 +- crates/cdk-postgres/src/lib.rs | 8 +- .../postgres/20250729111701_keyset_v2_u32.sql | 11 + justfile | 4 +- 9 files changed, 853 insertions(+), 389 deletions(-) create mode 100644 crates/cdk-ffi/src/postgres.rs create mode 100644 crates/cdk-ffi/src/sqlite.rs create mode 100644 crates/cdk-sql-common/src/wallet/migrations/postgres/20250729111701_keyset_v2_u32.sql diff --git a/crates/cdk-ffi/Cargo.toml b/crates/cdk-ffi/Cargo.toml index 80382a084..b37b47b4a 100644 --- a/crates/cdk-ffi/Cargo.toml +++ b/crates/cdk-ffi/Cargo.toml @@ -17,6 +17,7 @@ async-trait = { workspace = true } bip39 = { workspace = true } cdk = { workspace = true, default-features = false, features = ["wallet", "auth", "bip353"] } cdk-sqlite = { workspace = true } +cdk-postgres = { workspace = true, optional = true } ctor = "0.2" futures = { workspace = true } once_cell = { workspace = true } @@ -30,6 +31,11 @@ url = { workspace = true } uuid = { workspace = true, features = ["v4"] } +[features] +default = ["postgres"] +# Enable Postgres-backed wallet database support in FFI +postgres = ["cdk-postgres"] + [dev-dependencies] [[bin]] diff --git a/crates/cdk-ffi/src/database.rs b/crates/cdk-ffi/src/database.rs index b1110aed6..578681b66 100644 --- a/crates/cdk-ffi/src/database.rs +++ b/crates/cdk-ffi/src/database.rs @@ -4,9 +4,10 @@ use std::collections::HashMap; use std::sync::Arc; use cdk::cdk_database::WalletDatabase as CdkWalletDatabase; -use cdk_sqlite::wallet::WalletSqliteDatabase as CdkWalletSqliteDatabase; use crate::error::FfiError; +use crate::postgres::WalletPostgresDatabase; +use crate::sqlite::WalletSqliteDatabase; use crate::types::*; /// FFI-compatible trait for wallet database operations @@ -171,7 +172,6 @@ impl CdkWalletDatabase for WalletDatabaseBridge { ) -> Result<(), Self::Err> { let ffi_mint_url = mint_url.into(); let ffi_mint_info = mint_info.map(Into::into); - self.ffi_db .add_mint(ffi_mint_url, ffi_mint_info) .await @@ -556,394 +556,30 @@ impl CdkWalletDatabase for WalletDatabaseBridge { } } -/// FFI-compatible WalletSqliteDatabase implementation that implements the WalletDatabase trait -#[derive(uniffi::Object)] -pub struct WalletSqliteDatabase { - inner: Arc, -} - -impl WalletSqliteDatabase { - // No additional methods needed beyond the trait implementation +/// FFI-safe wallet database backend selection +#[derive(uniffi::Enum)] +pub enum WalletDbBackend { + Sqlite { + path: String, + }, + #[cfg(feature = "postgres")] + Postgres { + url: String, + }, } +/// Factory helpers returning a CDK wallet database behind the FFI trait #[uniffi::export] -impl WalletSqliteDatabase { - /// Create a new WalletSqliteDatabase with the given work directory - #[uniffi::constructor] - pub fn new(file_path: String) -> Result, FfiError> { - let db = match tokio::runtime::Handle::try_current() { - Ok(handle) => tokio::task::block_in_place(|| { - handle - .block_on(async move { CdkWalletSqliteDatabase::new(file_path.as_str()).await }) - }), - Err(_) => { - // No current runtime, create a new one - tokio::runtime::Runtime::new() - .map_err(|e| FfiError::Database { - msg: format!("Failed to create runtime: {}", e), - })? - .block_on(async move { CdkWalletSqliteDatabase::new(file_path.as_str()).await }) - } +pub fn create_wallet_db(backend: WalletDbBackend) -> Result, FfiError> { + match backend { + WalletDbBackend::Sqlite { path } => { + let sqlite = WalletSqliteDatabase::new(path)?; + Ok(sqlite as Arc) } - .map_err(|e| FfiError::Database { msg: e.to_string() })?; - Ok(Arc::new(Self { - inner: Arc::new(db), - })) - } - - /// Create an in-memory database - #[uniffi::constructor] - pub fn new_in_memory() -> Result, FfiError> { - let db = match tokio::runtime::Handle::try_current() { - Ok(handle) => tokio::task::block_in_place(|| { - handle.block_on(async move { cdk_sqlite::wallet::memory::empty().await }) - }), - Err(_) => { - // No current runtime, create a new one - tokio::runtime::Runtime::new() - .map_err(|e| FfiError::Database { - msg: format!("Failed to create runtime: {}", e), - })? - .block_on(async move { cdk_sqlite::wallet::memory::empty().await }) - } + WalletDbBackend::Postgres { url } => { + let pg = WalletPostgresDatabase::new(url)?; + Ok(pg as Arc) } - .map_err(|e| FfiError::Database { msg: e.to_string() })?; - Ok(Arc::new(Self { - inner: Arc::new(db), - })) - } -} - -#[uniffi::export(async_runtime = "tokio")] -#[async_trait::async_trait] -impl WalletDatabase for WalletSqliteDatabase { - // Mint Management - async fn add_mint( - &self, - mint_url: MintUrl, - mint_info: Option, - ) -> Result<(), FfiError> { - let cdk_mint_url = mint_url.try_into()?; - let cdk_mint_info = mint_info.map(Into::into); - self.inner - .add_mint(cdk_mint_url, cdk_mint_info) - .await - .map_err(|e| FfiError::Database { msg: e.to_string() }) - } - - async fn remove_mint(&self, mint_url: MintUrl) -> Result<(), FfiError> { - let cdk_mint_url = mint_url.try_into()?; - self.inner - .remove_mint(cdk_mint_url) - .await - .map_err(|e| FfiError::Database { msg: e.to_string() }) - } - - async fn get_mint(&self, mint_url: MintUrl) -> Result, FfiError> { - let cdk_mint_url = mint_url.try_into()?; - let result = self - .inner - .get_mint(cdk_mint_url) - .await - .map_err(|e| FfiError::Database { msg: e.to_string() })?; - Ok(result.map(Into::into)) - } - - async fn get_mints(&self) -> Result>, FfiError> { - let result = self - .inner - .get_mints() - .await - .map_err(|e| FfiError::Database { msg: e.to_string() })?; - Ok(result - .into_iter() - .map(|(k, v)| (k.into(), v.map(Into::into))) - .collect()) - } - - async fn update_mint_url( - &self, - old_mint_url: MintUrl, - new_mint_url: MintUrl, - ) -> Result<(), FfiError> { - let cdk_old_mint_url = old_mint_url.try_into()?; - let cdk_new_mint_url = new_mint_url.try_into()?; - self.inner - .update_mint_url(cdk_old_mint_url, cdk_new_mint_url) - .await - .map_err(|e| FfiError::Database { msg: e.to_string() }) - } - - // Keyset Management - async fn add_mint_keysets( - &self, - mint_url: MintUrl, - keysets: Vec, - ) -> Result<(), FfiError> { - let cdk_mint_url = mint_url.try_into()?; - let cdk_keysets: Vec = keysets.into_iter().map(Into::into).collect(); - self.inner - .add_mint_keysets(cdk_mint_url, cdk_keysets) - .await - .map_err(|e| FfiError::Database { msg: e.to_string() }) - } - - async fn get_mint_keysets( - &self, - mint_url: MintUrl, - ) -> Result>, FfiError> { - let cdk_mint_url = mint_url.try_into()?; - let result = self - .inner - .get_mint_keysets(cdk_mint_url) - .await - .map_err(|e| FfiError::Database { msg: e.to_string() })?; - Ok(result.map(|keysets| keysets.into_iter().map(Into::into).collect())) - } - - async fn get_keyset_by_id(&self, keyset_id: Id) -> Result, FfiError> { - let cdk_id = keyset_id.into(); - let result = self - .inner - .get_keyset_by_id(&cdk_id) - .await - .map_err(|e| FfiError::Database { msg: e.to_string() })?; - Ok(result.map(Into::into)) - } - - // Mint Quote Management - async fn add_mint_quote(&self, quote: MintQuote) -> Result<(), FfiError> { - let cdk_quote = quote.try_into()?; - self.inner - .add_mint_quote(cdk_quote) - .await - .map_err(|e| FfiError::Database { msg: e.to_string() }) - } - - async fn get_mint_quote(&self, quote_id: String) -> Result, FfiError> { - let result = self - .inner - .get_mint_quote("e_id) - .await - .map_err(|e| FfiError::Database { msg: e.to_string() })?; - Ok(result.map(|q| q.into())) - } - - async fn get_mint_quotes(&self) -> Result, FfiError> { - let result = self - .inner - .get_mint_quotes() - .await - .map_err(|e| FfiError::Database { msg: e.to_string() })?; - Ok(result.into_iter().map(|q| q.into()).collect()) - } - - async fn remove_mint_quote(&self, quote_id: String) -> Result<(), FfiError> { - self.inner - .remove_mint_quote("e_id) - .await - .map_err(|e| FfiError::Database { msg: e.to_string() }) - } - - // Melt Quote Management - async fn add_melt_quote(&self, quote: MeltQuote) -> Result<(), FfiError> { - let cdk_quote = quote.try_into()?; - self.inner - .add_melt_quote(cdk_quote) - .await - .map_err(|e| FfiError::Database { msg: e.to_string() }) - } - - async fn get_melt_quote(&self, quote_id: String) -> Result, FfiError> { - let result = self - .inner - .get_melt_quote("e_id) - .await - .map_err(|e| FfiError::Database { msg: e.to_string() })?; - Ok(result.map(|q| q.into())) - } - - async fn get_melt_quotes(&self) -> Result, FfiError> { - let result = self - .inner - .get_melt_quotes() - .await - .map_err(|e| FfiError::Database { msg: e.to_string() })?; - Ok(result.into_iter().map(|q| q.into()).collect()) - } - - async fn remove_melt_quote(&self, quote_id: String) -> Result<(), FfiError> { - self.inner - .remove_melt_quote("e_id) - .await - .map_err(|e| FfiError::Database { msg: e.to_string() }) - } - - // Keys Management - async fn add_keys(&self, keyset: KeySet) -> Result<(), FfiError> { - // Convert FFI KeySet to cdk::nuts::KeySet - let cdk_keyset: cdk::nuts::KeySet = keyset.try_into()?; - self.inner - .add_keys(cdk_keyset) - .await - .map_err(|e| FfiError::Database { msg: e.to_string() }) - } - - async fn get_keys(&self, id: Id) -> Result, FfiError> { - let cdk_id = id.into(); - let result = self - .inner - .get_keys(&cdk_id) - .await - .map_err(|e| FfiError::Database { msg: e.to_string() })?; - Ok(result.map(Into::into)) - } - - async fn remove_keys(&self, id: Id) -> Result<(), FfiError> { - let cdk_id = id.into(); - self.inner - .remove_keys(&cdk_id) - .await - .map_err(|e| FfiError::Database { msg: e.to_string() }) - } - - // Proof Management - async fn update_proofs( - &self, - added: Vec, - removed_ys: Vec, - ) -> Result<(), FfiError> { - // Convert FFI types to CDK types - let cdk_added: Result, FfiError> = added - .into_iter() - .map(|info| { - Ok::(cdk::types::ProofInfo { - proof: info.proof.inner.clone(), - y: info.y.try_into()?, - mint_url: info.mint_url.try_into()?, - state: info.state.into(), - spending_condition: info - .spending_condition - .map(|sc| sc.try_into()) - .transpose()?, - unit: info.unit.into(), - }) - }) - .collect(); - let cdk_added = cdk_added?; - - let cdk_removed_ys: Result, FfiError> = - removed_ys.into_iter().map(|pk| pk.try_into()).collect(); - let cdk_removed_ys = cdk_removed_ys?; - - self.inner - .update_proofs(cdk_added, cdk_removed_ys) - .await - .map_err(|e| FfiError::Database { msg: e.to_string() }) - } - - async fn get_proofs( - &self, - mint_url: Option, - unit: Option, - state: Option>, - spending_conditions: Option>, - ) -> Result, FfiError> { - let cdk_mint_url = mint_url.map(|u| u.try_into()).transpose()?; - let cdk_unit = unit.map(Into::into); - let cdk_state = state.map(|s| s.into_iter().map(Into::into).collect()); - let cdk_spending_conditions: Option> = - spending_conditions - .map(|sc| { - sc.into_iter() - .map(|c| c.try_into()) - .collect::, FfiError>>() - }) - .transpose()?; - - let result = self - .inner - .get_proofs(cdk_mint_url, cdk_unit, cdk_state, cdk_spending_conditions) - .await - .map_err(|e| FfiError::Database { msg: e.to_string() })?; - - Ok(result.into_iter().map(Into::into).collect()) - } - - async fn update_proofs_state( - &self, - ys: Vec, - state: ProofState, - ) -> Result<(), FfiError> { - let cdk_ys: Result, FfiError> = - ys.into_iter().map(|pk| pk.try_into()).collect(); - let cdk_ys = cdk_ys?; - let cdk_state = state.into(); - - self.inner - .update_proofs_state(cdk_ys, cdk_state) - .await - .map_err(|e| FfiError::Database { msg: e.to_string() }) - } - - // Keyset Counter Management - async fn increment_keyset_counter(&self, keyset_id: Id, count: u32) -> Result { - let cdk_id = keyset_id.into(); - self.inner - .increment_keyset_counter(&cdk_id, count) - .await - .map_err(|e| FfiError::Database { msg: e.to_string() }) - } - - // Transaction Management - async fn add_transaction(&self, transaction: Transaction) -> Result<(), FfiError> { - // Convert FFI Transaction to CDK Transaction using TryFrom - let cdk_transaction: cdk::wallet::types::Transaction = transaction.try_into()?; - - self.inner - .add_transaction(cdk_transaction) - .await - .map_err(|e| FfiError::Database { msg: e.to_string() }) - } - - async fn get_transaction( - &self, - transaction_id: TransactionId, - ) -> Result, FfiError> { - let cdk_id = transaction_id.try_into()?; - let result = self - .inner - .get_transaction(cdk_id) - .await - .map_err(|e| FfiError::Database { msg: e.to_string() })?; - Ok(result.map(Into::into)) - } - - async fn list_transactions( - &self, - mint_url: Option, - direction: Option, - unit: Option, - ) -> Result, FfiError> { - let cdk_mint_url = mint_url.map(|u| u.try_into()).transpose()?; - let cdk_direction = direction.map(Into::into); - let cdk_unit = unit.map(Into::into); - - let result = self - .inner - .list_transactions(cdk_mint_url, cdk_direction, cdk_unit) - .await - .map_err(|e| FfiError::Database { msg: e.to_string() })?; - - Ok(result.into_iter().map(Into::into).collect()) - } - - async fn remove_transaction(&self, transaction_id: TransactionId) -> Result<(), FfiError> { - let cdk_id = transaction_id.try_into()?; - self.inner - .remove_transaction(cdk_id) - .await - .map_err(|e| FfiError::Database { msg: e.to_string() }) } } diff --git a/crates/cdk-ffi/src/lib.rs b/crates/cdk-ffi/src/lib.rs index beb5046fc..57dbb8b4c 100644 --- a/crates/cdk-ffi/src/lib.rs +++ b/crates/cdk-ffi/src/lib.rs @@ -7,6 +7,8 @@ pub mod database; pub mod error; pub mod multi_mint_wallet; +pub mod postgres; +pub mod sqlite; pub mod token; pub mod types; pub mod wallet; diff --git a/crates/cdk-ffi/src/postgres.rs b/crates/cdk-ffi/src/postgres.rs new file mode 100644 index 000000000..f128b53f1 --- /dev/null +++ b/crates/cdk-ffi/src/postgres.rs @@ -0,0 +1,401 @@ +use std::collections::HashMap; +use std::sync::Arc; + +// Bring the CDK wallet database trait into scope so trait methods resolve on the inner DB +use cdk::cdk_database::WalletDatabase as CdkWalletDatabase; +#[cfg(feature = "postgres")] +use cdk_postgres::WalletPgDatabase as CdkWalletPgDatabase; + +use crate::{ + CurrencyUnit, FfiError, Id, KeySet, KeySetInfo, Keys, MeltQuote, MintInfo, MintQuote, MintUrl, + ProofInfo, ProofState, PublicKey, SpendingConditions, Transaction, TransactionDirection, + TransactionId, WalletDatabase, +}; + +#[derive(uniffi::Object)] +pub struct WalletPostgresDatabase { + inner: Arc, +} + +// Keep a long-lived Tokio runtime for Postgres-created resources so that +// background tasks (e.g., tokio-postgres connection drivers spawned during +// construction) are not tied to a short-lived, ad-hoc runtime. +#[cfg(feature = "postgres")] +static PG_RUNTIME: once_cell::sync::OnceCell = + once_cell::sync::OnceCell::new(); + +#[cfg(feature = "postgres")] +fn pg_runtime() -> &'static tokio::runtime::Runtime { + PG_RUNTIME.get_or_init(|| { + tokio::runtime::Builder::new_multi_thread() + .enable_all() + .thread_name("cdk-ffi-pg") + .build() + .expect("failed to build pg runtime") + }) +} + +// Implement the local WalletDatabase trait (simple trait path required by uniffi) +#[uniffi::export(async_runtime = "tokio")] +#[async_trait::async_trait] +impl WalletDatabase for WalletPostgresDatabase { + // Forward all trait methods to inner CDK database via the bridge adapter + async fn add_mint( + &self, + mint_url: MintUrl, + mint_info: Option, + ) -> Result<(), FfiError> { + let cdk_mint_url = mint_url.try_into()?; + let cdk_mint_info = mint_info.map(Into::into); + println!("adding new mint"); + self.inner + .add_mint(cdk_mint_url, cdk_mint_info) + .await + .map_err(|e| { + println!("ffi error {:?}", e); + FfiError::Database { msg: e.to_string() } + }) + } + async fn remove_mint(&self, mint_url: MintUrl) -> Result<(), FfiError> { + let cdk_mint_url = mint_url.try_into()?; + self.inner + .remove_mint(cdk_mint_url) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + async fn get_mint(&self, mint_url: MintUrl) -> Result, FfiError> { + let cdk_mint_url = mint_url.try_into()?; + let result = self + .inner + .get_mint(cdk_mint_url) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + Ok(result.map(Into::into)) + } + async fn get_mints(&self) -> Result>, FfiError> { + let result = self + .inner + .get_mints() + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + Ok(result + .into_iter() + .map(|(k, v)| (k.into(), v.map(Into::into))) + .collect()) + } + async fn update_mint_url( + &self, + old_mint_url: MintUrl, + new_mint_url: MintUrl, + ) -> Result<(), FfiError> { + let cdk_old_mint_url = old_mint_url.try_into()?; + let cdk_new_mint_url = new_mint_url.try_into()?; + self.inner + .update_mint_url(cdk_old_mint_url, cdk_new_mint_url) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + async fn add_mint_keysets( + &self, + mint_url: MintUrl, + keysets: Vec, + ) -> Result<(), FfiError> { + let cdk_mint_url = mint_url.try_into()?; + let cdk_keysets: Vec = keysets.into_iter().map(Into::into).collect(); + self.inner + .add_mint_keysets(cdk_mint_url, cdk_keysets) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + async fn get_mint_keysets( + &self, + mint_url: MintUrl, + ) -> Result>, FfiError> { + let cdk_mint_url = mint_url.try_into()?; + let result = self + .inner + .get_mint_keysets(cdk_mint_url) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + Ok(result.map(|keysets| keysets.into_iter().map(Into::into).collect())) + } + + async fn get_keyset_by_id(&self, keyset_id: Id) -> Result, FfiError> { + let cdk_id = keyset_id.into(); + let result = self + .inner + .get_keyset_by_id(&cdk_id) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + Ok(result.map(Into::into)) + } + + // Mint Quote Management + async fn add_mint_quote(&self, quote: MintQuote) -> Result<(), FfiError> { + let cdk_quote = quote.try_into()?; + self.inner + .add_mint_quote(cdk_quote) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + async fn get_mint_quote(&self, quote_id: String) -> Result, FfiError> { + let result = self + .inner + .get_mint_quote("e_id) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + Ok(result.map(|q| q.into())) + } + + async fn get_mint_quotes(&self) -> Result, FfiError> { + let result = self + .inner + .get_mint_quotes() + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + Ok(result.into_iter().map(|q| q.into()).collect()) + } + + async fn remove_mint_quote(&self, quote_id: String) -> Result<(), FfiError> { + self.inner + .remove_mint_quote("e_id) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + // Melt Quote Management + async fn add_melt_quote(&self, quote: MeltQuote) -> Result<(), FfiError> { + let cdk_quote = quote.try_into()?; + self.inner + .add_melt_quote(cdk_quote) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + async fn get_melt_quote(&self, quote_id: String) -> Result, FfiError> { + let result = self + .inner + .get_melt_quote("e_id) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + Ok(result.map(|q| q.into())) + } + + async fn get_melt_quotes(&self) -> Result, FfiError> { + let result = self + .inner + .get_melt_quotes() + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + Ok(result.into_iter().map(|q| q.into()).collect()) + } + + async fn remove_melt_quote(&self, quote_id: String) -> Result<(), FfiError> { + self.inner + .remove_melt_quote("e_id) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + // Keys Management + async fn add_keys(&self, keyset: KeySet) -> Result<(), FfiError> { + // Convert FFI KeySet to cdk::nuts::KeySet + let cdk_keyset: cdk::nuts::KeySet = keyset.try_into()?; + self.inner + .add_keys(cdk_keyset) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + async fn get_keys(&self, id: Id) -> Result, FfiError> { + let cdk_id = id.into(); + let result = self + .inner + .get_keys(&cdk_id) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + Ok(result.map(Into::into)) + } + + async fn remove_keys(&self, id: Id) -> Result<(), FfiError> { + let cdk_id = id.into(); + self.inner + .remove_keys(&cdk_id) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + // Proof Management + async fn update_proofs( + &self, + added: Vec, + removed_ys: Vec, + ) -> Result<(), FfiError> { + // Convert FFI types to CDK types + let cdk_added: Result, FfiError> = added + .into_iter() + .map(|info| { + Ok::(cdk::types::ProofInfo { + proof: info.proof.inner.clone(), + y: info.y.try_into()?, + mint_url: info.mint_url.try_into()?, + state: info.state.into(), + spending_condition: info + .spending_condition + .map(|sc| sc.try_into()) + .transpose()?, + unit: info.unit.into(), + }) + }) + .collect(); + let cdk_added = cdk_added?; + + let cdk_removed_ys: Result, FfiError> = + removed_ys.into_iter().map(|pk| pk.try_into()).collect(); + let cdk_removed_ys = cdk_removed_ys?; + + self.inner + .update_proofs(cdk_added, cdk_removed_ys) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + async fn get_proofs( + &self, + mint_url: Option, + unit: Option, + state: Option>, + spending_conditions: Option>, + ) -> Result, FfiError> { + let cdk_mint_url = mint_url.map(|u| u.try_into()).transpose()?; + let cdk_unit = unit.map(Into::into); + let cdk_state = state.map(|s| s.into_iter().map(Into::into).collect()); + let cdk_spending_conditions: Option> = + spending_conditions + .map(|sc| { + sc.into_iter() + .map(|c| c.try_into()) + .collect::, FfiError>>() + }) + .transpose()?; + + let result = self + .inner + .get_proofs(cdk_mint_url, cdk_unit, cdk_state, cdk_spending_conditions) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + + Ok(result.into_iter().map(Into::into).collect()) + } + + async fn update_proofs_state( + &self, + ys: Vec, + state: ProofState, + ) -> Result<(), FfiError> { + let cdk_ys: Result, FfiError> = + ys.into_iter().map(|pk| pk.try_into()).collect(); + let cdk_ys = cdk_ys?; + let cdk_state = state.into(); + + self.inner + .update_proofs_state(cdk_ys, cdk_state) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + // Keyset Counter Management + async fn increment_keyset_counter(&self, keyset_id: Id, count: u32) -> Result { + let cdk_id = keyset_id.into(); + self.inner + .increment_keyset_counter(&cdk_id, count) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + // Transaction Management + async fn add_transaction(&self, transaction: Transaction) -> Result<(), FfiError> { + // Convert FFI Transaction to CDK Transaction using TryFrom + let cdk_transaction: cdk::wallet::types::Transaction = transaction.try_into()?; + + self.inner + .add_transaction(cdk_transaction) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + async fn get_transaction( + &self, + transaction_id: TransactionId, + ) -> Result, FfiError> { + let cdk_id = transaction_id.try_into()?; + let result = self + .inner + .get_transaction(cdk_id) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + Ok(result.map(Into::into)) + } + + async fn list_transactions( + &self, + mint_url: Option, + direction: Option, + unit: Option, + ) -> Result, FfiError> { + let cdk_mint_url = mint_url.map(|u| u.try_into()).transpose()?; + let cdk_direction = direction.map(Into::into); + let cdk_unit = unit.map(Into::into); + + let result = self + .inner + .list_transactions(cdk_mint_url, cdk_direction, cdk_unit) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + + Ok(result.into_iter().map(Into::into).collect()) + } + + async fn remove_transaction(&self, transaction_id: TransactionId) -> Result<(), FfiError> { + let cdk_id = transaction_id.try_into()?; + self.inner + .remove_transaction(cdk_id) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } +} + +#[uniffi::export] +impl WalletPostgresDatabase { + /// Create a new Postgres-backed wallet database + /// Requires cdk-ffi to be built with feature "postgres". + /// Example URL: + /// "host=localhost user=test password=test dbname=testdb port=5433 schema=wallet sslmode=prefer" + #[cfg(feature = "postgres")] + #[uniffi::constructor] + pub fn new(url: String) -> Result, FfiError> { + let inner = match tokio::runtime::Handle::try_current() { + Ok(handle) => tokio::task::block_in_place(|| { + handle.block_on( + async move { cdk_postgres::new_wallet_pg_database(url.as_str()).await }, + ) + }), + // Important: use a process-long runtime so background connection tasks stay alive. + Err(_) => pg_runtime() + .block_on(async move { cdk_postgres::new_wallet_pg_database(url.as_str()).await }), + } + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + Ok(Arc::new(WalletPostgresDatabase { + inner: Arc::new(inner), + })) + } + + fn clone_as_trait(&self) -> Arc { + // Safety: UniFFI objects are reference counted and Send+Sync via Arc + let obj: Arc = Arc::new(WalletPostgresDatabase { + inner: self.inner.clone(), + }); + obj + } +} diff --git a/crates/cdk-ffi/src/sqlite.rs b/crates/cdk-ffi/src/sqlite.rs new file mode 100644 index 000000000..8feae6e5b --- /dev/null +++ b/crates/cdk-ffi/src/sqlite.rs @@ -0,0 +1,402 @@ +use std::collections::HashMap; +use std::sync::Arc; + +use cdk_sqlite::wallet::WalletSqliteDatabase as CdkWalletSqliteDatabase; + +use crate::{ + CurrencyUnit, FfiError, Id, KeySet, KeySetInfo, Keys, MeltQuote, MintInfo, MintQuote, MintUrl, + ProofInfo, ProofState, PublicKey, SpendingConditions, Transaction, TransactionDirection, + TransactionId, WalletDatabase, +}; + +/// FFI-compatible WalletSqliteDatabase implementation that implements the WalletDatabase trait +#[derive(uniffi::Object)] +pub struct WalletSqliteDatabase { + inner: Arc, +} +use cdk::cdk_database::WalletDatabase as CdkWalletDatabase; + +impl WalletSqliteDatabase { + // No additional methods needed beyond the trait implementation +} + +#[uniffi::export] +impl WalletSqliteDatabase { + /// Create a new WalletSqliteDatabase with the given work directory + #[uniffi::constructor] + pub fn new(file_path: String) -> Result, FfiError> { + let db = match tokio::runtime::Handle::try_current() { + Ok(handle) => tokio::task::block_in_place(|| { + handle + .block_on(async move { CdkWalletSqliteDatabase::new(file_path.as_str()).await }) + }), + Err(_) => { + // No current runtime, create a new one + tokio::runtime::Runtime::new() + .map_err(|e| FfiError::Database { + msg: format!("Failed to create runtime: {}", e), + })? + .block_on(async move { CdkWalletSqliteDatabase::new(file_path.as_str()).await }) + } + } + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + Ok(Arc::new(Self { + inner: Arc::new(db), + })) + } + + /// Create an in-memory database + #[uniffi::constructor] + pub fn new_in_memory() -> Result, FfiError> { + let db = match tokio::runtime::Handle::try_current() { + Ok(handle) => tokio::task::block_in_place(|| { + handle.block_on(async move { cdk_sqlite::wallet::memory::empty().await }) + }), + Err(_) => { + // No current runtime, create a new one + tokio::runtime::Runtime::new() + .map_err(|e| FfiError::Database { + msg: format!("Failed to create runtime: {}", e), + })? + .block_on(async move { cdk_sqlite::wallet::memory::empty().await }) + } + } + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + Ok(Arc::new(Self { + inner: Arc::new(db), + })) + } +} + +#[uniffi::export(async_runtime = "tokio")] +#[async_trait::async_trait] +impl WalletDatabase for WalletSqliteDatabase { + // Mint Management + async fn add_mint( + &self, + mint_url: MintUrl, + mint_info: Option, + ) -> Result<(), FfiError> { + let cdk_mint_url = mint_url.try_into()?; + let cdk_mint_info = mint_info.map(Into::into); + self.inner + .add_mint(cdk_mint_url, cdk_mint_info) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + async fn remove_mint(&self, mint_url: MintUrl) -> Result<(), FfiError> { + let cdk_mint_url = mint_url.try_into()?; + self.inner + .remove_mint(cdk_mint_url) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + async fn get_mint(&self, mint_url: MintUrl) -> Result, FfiError> { + let cdk_mint_url = mint_url.try_into()?; + let result = self + .inner + .get_mint(cdk_mint_url) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + Ok(result.map(Into::into)) + } + + async fn get_mints(&self) -> Result>, FfiError> { + let result = self + .inner + .get_mints() + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + Ok(result + .into_iter() + .map(|(k, v)| (k.into(), v.map(Into::into))) + .collect()) + } + + async fn update_mint_url( + &self, + old_mint_url: MintUrl, + new_mint_url: MintUrl, + ) -> Result<(), FfiError> { + let cdk_old_mint_url = old_mint_url.try_into()?; + let cdk_new_mint_url = new_mint_url.try_into()?; + self.inner + .update_mint_url(cdk_old_mint_url, cdk_new_mint_url) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + // Keyset Management + async fn add_mint_keysets( + &self, + mint_url: MintUrl, + keysets: Vec, + ) -> Result<(), FfiError> { + let cdk_mint_url = mint_url.try_into()?; + let cdk_keysets: Vec = keysets.into_iter().map(Into::into).collect(); + self.inner + .add_mint_keysets(cdk_mint_url, cdk_keysets) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + async fn get_mint_keysets( + &self, + mint_url: MintUrl, + ) -> Result>, FfiError> { + let cdk_mint_url = mint_url.try_into()?; + let result = self + .inner + .get_mint_keysets(cdk_mint_url) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + Ok(result.map(|keysets| keysets.into_iter().map(Into::into).collect())) + } + + async fn get_keyset_by_id(&self, keyset_id: Id) -> Result, FfiError> { + let cdk_id = keyset_id.into(); + let result = self + .inner + .get_keyset_by_id(&cdk_id) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + Ok(result.map(Into::into)) + } + + // Mint Quote Management + async fn add_mint_quote(&self, quote: MintQuote) -> Result<(), FfiError> { + let cdk_quote = quote.try_into()?; + self.inner + .add_mint_quote(cdk_quote) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + async fn get_mint_quote(&self, quote_id: String) -> Result, FfiError> { + let result = self + .inner + .get_mint_quote("e_id) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + Ok(result.map(|q| q.into())) + } + + async fn get_mint_quotes(&self) -> Result, FfiError> { + let result = self + .inner + .get_mint_quotes() + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + Ok(result.into_iter().map(|q| q.into()).collect()) + } + + async fn remove_mint_quote(&self, quote_id: String) -> Result<(), FfiError> { + self.inner + .remove_mint_quote("e_id) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + // Melt Quote Management + async fn add_melt_quote(&self, quote: MeltQuote) -> Result<(), FfiError> { + let cdk_quote = quote.try_into()?; + self.inner + .add_melt_quote(cdk_quote) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + async fn get_melt_quote(&self, quote_id: String) -> Result, FfiError> { + let result = self + .inner + .get_melt_quote("e_id) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + Ok(result.map(|q| q.into())) + } + + async fn get_melt_quotes(&self) -> Result, FfiError> { + let result = self + .inner + .get_melt_quotes() + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + Ok(result.into_iter().map(|q| q.into()).collect()) + } + + async fn remove_melt_quote(&self, quote_id: String) -> Result<(), FfiError> { + self.inner + .remove_melt_quote("e_id) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + // Keys Management + async fn add_keys(&self, keyset: KeySet) -> Result<(), FfiError> { + // Convert FFI KeySet to cdk::nuts::KeySet + let cdk_keyset: cdk::nuts::KeySet = keyset.try_into()?; + self.inner + .add_keys(cdk_keyset) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + async fn get_keys(&self, id: Id) -> Result, FfiError> { + let cdk_id = id.into(); + let result = self + .inner + .get_keys(&cdk_id) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + Ok(result.map(Into::into)) + } + + async fn remove_keys(&self, id: Id) -> Result<(), FfiError> { + let cdk_id = id.into(); + self.inner + .remove_keys(&cdk_id) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + // Proof Management + async fn update_proofs( + &self, + added: Vec, + removed_ys: Vec, + ) -> Result<(), FfiError> { + // Convert FFI types to CDK types + let cdk_added: Result, FfiError> = added + .into_iter() + .map(|info| { + Ok::(cdk::types::ProofInfo { + proof: info.proof.inner.clone(), + y: info.y.try_into()?, + mint_url: info.mint_url.try_into()?, + state: info.state.into(), + spending_condition: info + .spending_condition + .map(|sc| sc.try_into()) + .transpose()?, + unit: info.unit.into(), + }) + }) + .collect(); + let cdk_added = cdk_added?; + + let cdk_removed_ys: Result, FfiError> = + removed_ys.into_iter().map(|pk| pk.try_into()).collect(); + let cdk_removed_ys = cdk_removed_ys?; + + self.inner + .update_proofs(cdk_added, cdk_removed_ys) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + async fn get_proofs( + &self, + mint_url: Option, + unit: Option, + state: Option>, + spending_conditions: Option>, + ) -> Result, FfiError> { + let cdk_mint_url = mint_url.map(|u| u.try_into()).transpose()?; + let cdk_unit = unit.map(Into::into); + let cdk_state = state.map(|s| s.into_iter().map(Into::into).collect()); + let cdk_spending_conditions: Option> = + spending_conditions + .map(|sc| { + sc.into_iter() + .map(|c| c.try_into()) + .collect::, FfiError>>() + }) + .transpose()?; + + let result = self + .inner + .get_proofs(cdk_mint_url, cdk_unit, cdk_state, cdk_spending_conditions) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + + Ok(result.into_iter().map(Into::into).collect()) + } + + async fn update_proofs_state( + &self, + ys: Vec, + state: ProofState, + ) -> Result<(), FfiError> { + let cdk_ys: Result, FfiError> = + ys.into_iter().map(|pk| pk.try_into()).collect(); + let cdk_ys = cdk_ys?; + let cdk_state = state.into(); + + self.inner + .update_proofs_state(cdk_ys, cdk_state) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + // Keyset Counter Management + async fn increment_keyset_counter(&self, keyset_id: Id, count: u32) -> Result { + let cdk_id = keyset_id.into(); + self.inner + .increment_keyset_counter(&cdk_id, count) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + // Transaction Management + async fn add_transaction(&self, transaction: Transaction) -> Result<(), FfiError> { + // Convert FFI Transaction to CDK Transaction using TryFrom + let cdk_transaction: cdk::wallet::types::Transaction = transaction.try_into()?; + + self.inner + .add_transaction(cdk_transaction) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + + async fn get_transaction( + &self, + transaction_id: TransactionId, + ) -> Result, FfiError> { + let cdk_id = transaction_id.try_into()?; + let result = self + .inner + .get_transaction(cdk_id) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + Ok(result.map(Into::into)) + } + + async fn list_transactions( + &self, + mint_url: Option, + direction: Option, + unit: Option, + ) -> Result, FfiError> { + let cdk_mint_url = mint_url.map(|u| u.try_into()).transpose()?; + let cdk_direction = direction.map(Into::into); + let cdk_unit = unit.map(Into::into); + + let result = self + .inner + .list_transactions(cdk_mint_url, cdk_direction, cdk_unit) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + + Ok(result.into_iter().map(Into::into).collect()) + } + + async fn remove_transaction(&self, transaction_id: TransactionId) -> Result<(), FfiError> { + let cdk_id = transaction_id.try_into()?; + self.inner + .remove_transaction(cdk_id) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } +} diff --git a/crates/cdk-integration-tests/tests/ffi_minting_integration.rs b/crates/cdk-integration-tests/tests/ffi_minting_integration.rs index 8d3b32043..71ade057f 100644 --- a/crates/cdk-integration-tests/tests/ffi_minting_integration.rs +++ b/crates/cdk-integration-tests/tests/ffi_minting_integration.rs @@ -17,7 +17,7 @@ use std::str::FromStr; use std::time::Duration; use bip39::Mnemonic; -use cdk_ffi::database::WalletSqliteDatabase; +use cdk_ffi::sqlite::WalletSqliteDatabase; use cdk_ffi::types::{Amount, CurrencyUnit, QuoteState, SplitTarget}; use cdk_ffi::wallet::Wallet as FfiWallet; use cdk_ffi::WalletConfig; diff --git a/crates/cdk-postgres/src/lib.rs b/crates/cdk-postgres/src/lib.rs index 0d89c06c6..bea6ac1f0 100644 --- a/crates/cdk-postgres/src/lib.rs +++ b/crates/cdk-postgres/src/lib.rs @@ -319,9 +319,15 @@ pub type MintPgDatabase = SQLMintDatabase; #[cfg(feature = "auth")] pub type MintPgAuthDatabase = SQLMintAuthDatabase; -/// Mint DB implementation with PostgresSQL +/// Wallet DB implementation with PostgreSQL pub type WalletPgDatabase = SQLWalletDatabase; +/// Convenience free functions (cannot add inherent impls for a foreign type). +/// These mirror the Mint patterns and call through to the generic constructors. +pub async fn new_wallet_pg_database(conn_str: &str) -> Result { + >::new(conn_str).await +} + #[cfg(test)] mod test { use cdk_common::mint_db_test; diff --git a/crates/cdk-sql-common/src/wallet/migrations/postgres/20250729111701_keyset_v2_u32.sql b/crates/cdk-sql-common/src/wallet/migrations/postgres/20250729111701_keyset_v2_u32.sql new file mode 100644 index 000000000..2192f415e --- /dev/null +++ b/crates/cdk-sql-common/src/wallet/migrations/postgres/20250729111701_keyset_v2_u32.sql @@ -0,0 +1,11 @@ +-- Add u32 representation column to key table with unique constraint +ALTER TABLE key ADD COLUMN keyset_u32 INTEGER; + +-- Add unique constraint on the new column +CREATE UNIQUE INDEX IF NOT EXISTS keyset_u32_unique ON key(keyset_u32); + +-- Add u32 representation column to keyset table with unique constraint +ALTER TABLE keyset ADD COLUMN keyset_u32 INTEGER; + +-- Add unique constraint on the new column +CREATE UNIQUE INDEX IF NOT EXISTS keyset_u32_unique_keyset ON keyset(keyset_u32); diff --git a/justfile b/justfile index 0a1f48288..2ed4316f5 100644 --- a/justfile +++ b/justfile @@ -429,7 +429,7 @@ _ffi-lib-ext: # Build the FFI library ffi-build *ARGS="--release": - cargo build {{ARGS}} --package cdk-ffi + cargo build {{ARGS}} --package cdk-ffi --features postgres # Generate bindings for a specific language ffi-generate LANGUAGE *ARGS="--release": ffi-build @@ -460,7 +460,7 @@ ffi-generate LANGUAGE *ARGS="--release": ffi-build BUILD_TYPE="release" else BUILD_TYPE="debug" - cargo build --package cdk-ffi + cargo build --package cdk-ffi --features postgres fi LIB_EXT=$(just _ffi-lib-ext) From 166c96ff8822d9bb3c49fc056c880652c508f93f Mon Sep 17 00:00:00 2001 From: stefanbitcr Date: Tue, 30 Sep 2025 15:49:52 +0200 Subject: [PATCH 196/321] Fix htlc witness deserialization (#1138) * Add prior signatures if they exist --- crates/cashu/src/nuts/nut00/mod.rs | 30 +++++++++++++++++++++++++++--- crates/cashu/src/nuts/nut14/mod.rs | 10 ++++++++-- 2 files changed, 35 insertions(+), 5 deletions(-) diff --git a/crates/cashu/src/nuts/nut00/mod.rs b/crates/cashu/src/nuts/nut00/mod.rs index bc30a8ec6..a3b3a4248 100644 --- a/crates/cashu/src/nuts/nut00/mod.rs +++ b/crates/cashu/src/nuts/nut00/mod.rs @@ -281,12 +281,12 @@ impl PartialOrd for BlindSignature { #[serde(untagged)] #[cfg_attr(feature = "swagger", derive(utoipa::ToSchema))] pub enum Witness { - /// P2PK Witness - #[serde(with = "serde_p2pk_witness")] - P2PKWitness(P2PKWitness), /// HTLC Witness #[serde(with = "serde_htlc_witness")] HTLCWitness(HTLCWitness), + /// P2PK Witness + #[serde(with = "serde_p2pk_witness")] + P2PKWitness(P2PKWitness), } impl From for Witness { @@ -1042,4 +1042,28 @@ mod tests { assert_eq!(method, deserialized); } } + + #[test] + fn test_witness_serialization() { + let htlc_witness = HTLCWitness { + preimage: "preimage".to_string(), + signatures: Some(vec!["sig1".to_string()]), + }; + let witness = Witness::HTLCWitness(htlc_witness); + + let serialized = serde_json::to_string(&witness).unwrap(); + let deserialized: Witness = serde_json::from_str(&serialized).unwrap(); + + assert!(matches!(deserialized, Witness::HTLCWitness(_))); + + let p2pk_witness = P2PKWitness { + signatures: vec!["sig1".to_string(), "sig2".to_string()], + }; + let witness = Witness::P2PKWitness(p2pk_witness); + + let serialized = serde_json::to_string(&witness).unwrap(); + let deserialized: Witness = serde_json::from_str(&serialized).unwrap(); + + assert!(matches!(deserialized, Witness::P2PKWitness(_))); + } } diff --git a/crates/cashu/src/nuts/nut14/mod.rs b/crates/cashu/src/nuts/nut14/mod.rs index fd52d9023..e647e7e08 100644 --- a/crates/cashu/src/nuts/nut14/mod.rs +++ b/crates/cashu/src/nuts/nut14/mod.rs @@ -55,7 +55,7 @@ pub enum Error { #[derive(Default, Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)] #[cfg_attr(feature = "swagger", derive(utoipa::ToSchema))] pub struct HTLCWitness { - /// Primage + /// Preimage pub preimage: String, /// Signatures #[serde(skip_serializing_if = "Option::is_none")] @@ -139,9 +139,15 @@ impl Proof { /// Add Preimage #[inline] pub fn add_preimage(&mut self, preimage: String) { + let signatures = self + .witness + .as_ref() + .map(|w| w.signatures()) + .unwrap_or_default(); + self.witness = Some(Witness::HTLCWitness(HTLCWitness { preimage, - signatures: None, + signatures, })) } } From 9ad52383231bb9bb4f8272239d7ba4ab2f718def Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Wed, 1 Oct 2025 10:08:46 +0100 Subject: [PATCH 197/321] chore: remove min deps after msrv (#1143) --- crates/cdk/Cargo.toml | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/crates/cdk/Cargo.toml b/crates/cdk/Cargo.toml index b2b4cfa0c..24e75cefe 100644 --- a/crates/cdk/Cargo.toml +++ b/crates/cdk/Cargo.toml @@ -24,6 +24,7 @@ http_subscription = [] prometheus = ["dep:cdk-prometheus"] [dependencies] +arc-swap = "1.7.1" cdk-common.workspace = true cbor-diag.workspace = true async-trait.workspace = true @@ -51,10 +52,6 @@ nostr-sdk = { optional = true, version = "0.43.0", default-features = false, fea ]} cdk-prometheus = {workspace = true, optional = true} web-time.workspace = true -# -Z minimal-versions -sync_wrapper = "0.1.2" -bech32 = "0.9.1" -arc-swap = "1.7.1" zeroize = "1" tokio-util.workspace = true From 144f1da6c5a4c6c5a1d9d273f4cace6b7d649f4e Mon Sep 17 00:00:00 2001 From: benthecarman <15256660+benthecarman@users.noreply.github.com> Date: Thu, 2 Oct 2025 04:11:08 -0500 Subject: [PATCH 198/321] Allow passing metadata to a melt (#1148) --- .../tests/happy_path_mint_wallet.rs | 19 ++++++- crates/cdk/src/wallet/melt/melt_bolt11.rs | 55 ++++++++++++++++++- 2 files changed, 70 insertions(+), 4 deletions(-) diff --git a/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs b/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs index d0389b9a6..8e3f77e85 100644 --- a/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs +++ b/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs @@ -9,6 +9,7 @@ //! whether to use real Lightning Network payments (regtest mode) or simulated payments. use core::panic; +use std::collections::HashMap; use std::env; use std::fmt::Debug; use std::path::PathBuf; @@ -161,9 +162,23 @@ async fn test_happy_mint_melt_round_trip() { assert_eq!(response_json, expected_json); - let melt_response = wallet.melt(&melt.id).await.unwrap(); + let mut metadata = HashMap::new(); + metadata.insert("test".to_string(), "value".to_string()); + + let melt_response = wallet + .melt_with_metadata(&melt.id, metadata.clone()) + .await + .unwrap(); assert!(melt_response.preimage.is_some()); - assert!(melt_response.state == MeltQuoteState::Paid); + assert_eq!(melt_response.state, MeltQuoteState::Paid); + + let txs = wallet.list_transactions(None).await.unwrap(); + let tx = txs + .into_iter() + .find(|tx| tx.quote_id == Some(melt.id.clone())) + .unwrap(); + assert_eq!(tx.amount, melt.amount); + assert_eq!(tx.metadata, metadata); let (sub_id, payload) = get_notification(&mut reader, Duration::from_millis(15000)).await; // first message is the current state diff --git a/crates/cdk/src/wallet/melt/melt_bolt11.rs b/crates/cdk/src/wallet/melt/melt_bolt11.rs index 5583b763d..96a3f12f9 100644 --- a/crates/cdk/src/wallet/melt/melt_bolt11.rs +++ b/crates/cdk/src/wallet/melt/melt_bolt11.rs @@ -129,6 +129,18 @@ impl Wallet { /// Melt specific proofs #[instrument(skip(self, proofs))] pub async fn melt_proofs(&self, quote_id: &str, proofs: Proofs) -> Result { + self.melt_proofs_with_metadata(quote_id, proofs, HashMap::new()) + .await + } + + /// Melt specific proofs + #[instrument(skip(self, proofs))] + pub async fn melt_proofs_with_metadata( + &self, + quote_id: &str, + proofs: Proofs, + metadata: HashMap, + ) -> Result { let quote_info = self .localstore .get_melt_quote(quote_id) @@ -284,7 +296,7 @@ impl Wallet { ys: proofs.ys()?, timestamp: unix_time(), memo: None, - metadata: HashMap::new(), + metadata, quote_id: Some(quote_id.to_string()), }) .await?; @@ -320,6 +332,44 @@ impl Wallet { /// } #[instrument(skip(self))] pub async fn melt(&self, quote_id: &str) -> Result { + self.melt_with_metadata(quote_id, HashMap::new()).await + } + + /// Melt with additional metadata to be saved locally with the transaction + /// # Synopsis + /// ```rust, no_run + /// use std::sync::Arc; + /// + /// use cdk_sqlite::wallet::memory; + /// use cdk::nuts::CurrencyUnit; + /// use cdk::wallet::Wallet; + /// use rand::random; + /// + /// #[tokio::main] + /// async fn main() -> anyhow::Result<()> { + /// let seed = random::<[u8; 64]>(); + /// let mint_url = "https://fake.thesimplekid.dev"; + /// let unit = CurrencyUnit::Sat; + /// + /// let localstore = memory::empty().await?; + /// let wallet = Wallet::new(mint_url, unit, Arc::new(localstore), seed, None).unwrap(); + /// let bolt11 = "lnbc100n1pnvpufspp5djn8hrq49r8cghwye9kqw752qjncwyfnrprhprpqk43mwcy4yfsqdq5g9kxy7fqd9h8vmmfvdjscqzzsxqyz5vqsp5uhpjt36rj75pl7jq2sshaukzfkt7uulj456s4mh7uy7l6vx7lvxs9qxpqysgqedwz08acmqwtk8g4vkwm2w78suwt2qyzz6jkkwcgrjm3r3hs6fskyhvud4fan3keru7emjm8ygqpcrwtlmhfjfmer3afs5hhwamgr4cqtactdq".to_string(); + /// let quote = wallet.melt_quote(bolt11, None).await?; + /// let quote_id = quote.id; + /// + /// let mut metadata = std::collections::HashMap::new(); + /// metadata.insert("my key".to_string(), "my value".to_string()); + /// + /// let _ = wallet.melt_with_metadata("e_id, metadata).await?; + /// + /// Ok(()) + /// } + #[instrument(skip(self))] + pub async fn melt_with_metadata( + &self, + quote_id: &str, + metadata: HashMap, + ) -> Result { let quote_info = self .localstore .get_melt_quote(quote_id) @@ -368,6 +418,7 @@ impl Wallet { input_proofs.extend_from_slice(&new_proofs); } - self.melt_proofs(quote_id, input_proofs).await + self.melt_proofs_with_metadata(quote_id, input_proofs, metadata) + .await } } From 6bffd782338f6f43c4c519a0388eb1f30029700f Mon Sep 17 00:00:00 2001 From: benthecarman <15256660+benthecarman@users.noreply.github.com> Date: Thu, 2 Oct 2025 04:11:47 -0500 Subject: [PATCH 199/321] Make sorting Transactions a stable sort (#1147) If you had 2 Transactions that had the same timestamp the sort could be unstable and could cause annoying issues. Now it will compare the ids if they are equal and should always have a stable sorting implementation now. --- crates/cdk-common/src/wallet.rs | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/crates/cdk-common/src/wallet.rs b/crates/cdk-common/src/wallet.rs index d350b9466..a03d48f25 100644 --- a/crates/cdk-common/src/wallet.rs +++ b/crates/cdk-common/src/wallet.rs @@ -246,7 +246,10 @@ impl PartialOrd for Transaction { impl Ord for Transaction { fn cmp(&self, other: &Self) -> std::cmp::Ordering { - self.timestamp.cmp(&other.timestamp).reverse() + self.timestamp + .cmp(&other.timestamp) + .reverse() + .then_with(|| self.id().cmp(&other.id())) } } From 81a47d5d12f99b1c2fa64698f28aacbff4f93471 Mon Sep 17 00:00:00 2001 From: C Date: Thu, 2 Oct 2025 06:12:17 -0300 Subject: [PATCH 200/321] Fix bug with websocket close (#1144) * Fix bug with websocket close Fixes #1111 * Do not connect to ws if there are no active subscription --- crates/cdk/src/wallet/subscription/ws.rs | 26 +++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/crates/cdk/src/wallet/subscription/ws.rs b/crates/cdk/src/wallet/subscription/ws.rs index f0204a901..0fbed7546 100644 --- a/crates/cdk/src/wallet/subscription/ws.rs +++ b/crates/cdk/src/wallet/subscription/ws.rs @@ -1,6 +1,7 @@ use std::collections::{HashMap, HashSet}; use std::sync::atomic::AtomicUsize; use std::sync::Arc; +use std::time::Duration; use cdk_common::subscription::Params; use cdk_common::ws::{WsMessageOrResponse, WsMethodRequest, WsRequest, WsUnsubscribeRequest}; @@ -8,6 +9,7 @@ use cdk_common::ws::{WsMessageOrResponse, WsMethodRequest, WsRequest, WsUnsubscr use cdk_common::{Method, RoutePath}; use futures::{SinkExt, StreamExt}; use tokio::sync::{mpsc, RwLock}; +use tokio::time::sleep; use tokio_tungstenite::connect_async; use tokio_tungstenite::tungstenite::client::IntoClientRequest; use tokio_tungstenite::tungstenite::Message; @@ -61,6 +63,12 @@ pub async fn ws_main( let mut failure_count = 0; loop { + if subscriptions.read().await.is_empty() { + // No active subscription + sleep(Duration::from_millis(100)).await; + continue; + } + let mut request_clone = request.clone(); #[cfg(feature = "auth")] { @@ -177,7 +185,12 @@ pub async fn ws_main( Some(msg) = read.next() => { let msg = match msg { Ok(msg) => msg, - Err(_) => break, + Err(_) => { + if let Err(err) = write.send(Message::Close(None)).await { + tracing::error!("Closing error {err:?}"); + } + break + }, }; let msg = match msg { Message::Text(msg) => msg, @@ -222,6 +235,10 @@ pub async fn ws_main( .await; } + if let Err(err) = write.send(Message::Close(None)).await { + tracing::error!("Closing error {err:?}"); + } + break; // break connection to force a reconnection, to attempt to recover form this error } } @@ -251,6 +268,13 @@ pub async fn ws_main( if let Some(json) = get_unsub_request(subid) { let _ = write.send(Message::Text(json.into())).await; } + + if subscription.is_empty() { + if let Err(err) = write.send(Message::Close(None)).await { + tracing::error!("Closing error {err:?}"); + } + break; + } } } } From ca3444939edddb9e57f480c0bc0bc8124d9f5aa1 Mon Sep 17 00:00:00 2001 From: David Caseria Date: Thu, 2 Oct 2025 07:24:36 -0400 Subject: [PATCH 201/321] Add MultiMintWallet check and wait for mint quotes (#1146) * Add MultiMintWallet check and wait for mint quotes --- crates/cdk-ffi/src/multi_mint_wallet.rs | 40 +++++++++++++++ crates/cdk/src/wallet/multi_mint_wallet.rs | 57 ++++++++++++++++++++++ 2 files changed, 97 insertions(+) diff --git a/crates/cdk-ffi/src/multi_mint_wallet.rs b/crates/cdk-ffi/src/multi_mint_wallet.rs index 6fc72af93..f63a56fee 100644 --- a/crates/cdk-ffi/src/multi_mint_wallet.rs +++ b/crates/cdk-ffi/src/multi_mint_wallet.rs @@ -227,6 +227,20 @@ impl MultiMintWallet { Ok(quote.into()) } + /// Check a specific mint quote status + pub async fn check_mint_quote( + &self, + mint_url: MintUrl, + quote_id: String, + ) -> Result { + let cdk_mint_url: cdk::mint_url::MintUrl = mint_url.try_into()?; + let quote = self + .inner + .check_mint_quote(&cdk_mint_url, "e_id) + .await?; + Ok(quote.into()) + } + /// Mint tokens at a specific mint pub async fn mint( &self, @@ -244,6 +258,32 @@ impl MultiMintWallet { Ok(proofs.into_iter().map(|p| Arc::new(p.into())).collect()) } + /// Wait for a mint quote to be paid and automatically mint the proofs + #[cfg(not(target_arch = "wasm32"))] + pub async fn wait_for_mint_quote( + &self, + mint_url: MintUrl, + quote_id: String, + split_target: SplitTarget, + spending_conditions: Option, + timeout_secs: u64, + ) -> Result { + let cdk_mint_url: cdk::mint_url::MintUrl = mint_url.try_into()?; + let conditions = spending_conditions.map(|sc| sc.try_into()).transpose()?; + + let proofs = self + .inner + .wait_for_mint_quote( + &cdk_mint_url, + "e_id, + split_target.into(), + conditions, + timeout_secs, + ) + .await?; + Ok(proofs.into_iter().map(|p| Arc::new(p.into())).collect()) + } + /// Get a melt quote from a specific mint pub async fn melt_quote( &self, diff --git a/crates/cdk/src/wallet/multi_mint_wallet.rs b/crates/cdk/src/wallet/multi_mint_wallet.rs index ad34a4592..125a4eb23 100644 --- a/crates/cdk/src/wallet/multi_mint_wallet.rs +++ b/crates/cdk/src/wallet/multi_mint_wallet.rs @@ -741,6 +741,32 @@ impl MultiMintWallet { wallet.mint_quote(amount, description).await } + /// Check a specific mint quote status + #[instrument(skip(self))] + pub async fn check_mint_quote( + &self, + mint_url: &MintUrl, + quote_id: &str, + ) -> Result { + let wallets = self.wallets.read().await; + let wallet = wallets.get(mint_url).ok_or(Error::UnknownMint { + mint_url: mint_url.to_string(), + })?; + + // Check the quote state from the mint + wallet.mint_quote_state(quote_id).await?; + + // Get the updated quote from local storage + let quote = wallet + .localstore + .get_mint_quote(quote_id) + .await + .map_err(Error::Database)? + .ok_or(Error::UnknownQuote)?; + + Ok(quote) + } + /// Check all mint quotes /// If quote is paid, wallet will mint #[instrument(skip(self))] @@ -784,6 +810,37 @@ impl MultiMintWallet { .await } + /// Wait for a mint quote to be paid and automatically mint the proofs + #[cfg(not(target_arch = "wasm32"))] + #[instrument(skip(self))] + pub async fn wait_for_mint_quote( + &self, + mint_url: &MintUrl, + quote_id: &str, + split_target: SplitTarget, + conditions: Option, + timeout_secs: u64, + ) -> Result { + let wallets = self.wallets.read().await; + let wallet = wallets.get(mint_url).ok_or(Error::UnknownMint { + mint_url: mint_url.to_string(), + })?; + + // Get the mint quote from local storage + let quote = wallet + .localstore + .get_mint_quote(quote_id) + .await + .map_err(Error::Database)? + .ok_or(Error::UnknownQuote)?; + + // Wait for the quote to be paid and mint the proofs + let timeout_duration = tokio::time::Duration::from_secs(timeout_secs); + wallet + .wait_and_mint_quote(quote, split_target, conditions, timeout_duration) + .await + } + /// Receive token with multi-mint options /// /// This method can: From b5dfa120a439f4034653301117bcf90753dd0874 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Thu, 2 Oct 2025 13:14:58 +0100 Subject: [PATCH 202/321] chore: update flake (#1150) --- flake.lock | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/flake.lock b/flake.lock index bb202710b..4926e6182 100644 --- a/flake.lock +++ b/flake.lock @@ -2,11 +2,11 @@ "nodes": { "crane": { "locked": { - "lastModified": 1755993354, - "narHash": "sha256-FCRRAzSaL/+umLIm3RU3O/+fJ2ssaPHseI2SSFL8yZU=", + "lastModified": 1758758545, + "narHash": "sha256-NU5WaEdfwF6i8faJ2Yh+jcK9vVFrofLcwlD/mP65JrI=", "owner": "ipetkov", "repo": "crane", - "rev": "25bd41b24426c7734278c2ff02e53258851db914", + "rev": "95d528a5f54eaba0d12102249ce42f4d01f4e364", "type": "github" }, "original": { @@ -23,11 +23,11 @@ "rust-analyzer-src": [] }, "locked": { - "lastModified": 1756622179, - "narHash": "sha256-K3CimrAcMhdDYkErd3oiWPZNaoyaGZEuvGrFuDPFMZY=", + "lastModified": 1759387261, + "narHash": "sha256-u/gfYBMDnwD1mSAlzHnRVg3jst3ML0w9b3tYONXRsW8=", "owner": "nix-community", "repo": "fenix", - "rev": "0abcb15ae6279dcb40a8ae7c1ed980705245cb79", + "rev": "c61e7ab9cfa38119d5ab9e2d1156d23c19e9b8a0", "type": "github" }, "original": { @@ -93,11 +93,11 @@ }, "nixpkgs": { "locked": { - "lastModified": 1756469547, - "narHash": "sha256-YvtD2E7MYsQ3r7K9K2G7nCslCKMPShoSEAtbjHLtH0k=", + "lastModified": 1759281824, + "narHash": "sha256-FIBE1qXv9TKvSNwst6FumyHwCRH3BlWDpfsnqRDCll0=", "owner": "NixOS", "repo": "nixpkgs", - "rev": "41d292bfc37309790f70f4c120b79280ce40af16", + "rev": "5b5be50345d4113d04ba58c444348849f5585b4a", "type": "github" }, "original": { @@ -109,11 +109,11 @@ }, "nixpkgs_2": { "locked": { - "lastModified": 1754340878, - "narHash": "sha256-lgmUyVQL9tSnvvIvBp7x1euhkkCho7n3TMzgjdvgPoU=", + "lastModified": 1758029226, + "narHash": "sha256-TjqVmbpoCqWywY9xIZLTf6ANFvDCXdctCjoYuYPYdMI=", "owner": "NixOS", "repo": "nixpkgs", - "rev": "cab778239e705082fe97bb4990e0d24c50924c04", + "rev": "08b8f92ac6354983f5382124fef6006cade4a1c1", "type": "github" }, "original": { @@ -130,11 +130,11 @@ "nixpkgs": "nixpkgs_2" }, "locked": { - "lastModified": 1755960406, - "narHash": "sha256-RF7j6C1TmSTK9tYWO6CdEMtg6XZaUKcvZwOCD2SICZs=", + "lastModified": 1758108966, + "narHash": "sha256-ytw7ROXaWZ7OfwHrQ9xvjpUWeGVm86pwnEd1QhzawIo=", "owner": "cachix", "repo": "pre-commit-hooks.nix", - "rev": "e891a93b193fcaf2fc8012d890dc7f0befe86ec2", + "rev": "54df955a695a84cd47d4a43e08e1feaf90b1fd9b", "type": "github" }, "original": { @@ -160,11 +160,11 @@ ] }, "locked": { - "lastModified": 1756607787, - "narHash": "sha256-ciwAdgtlAN1PCaidWK6RuWsTBL8DVuyDCGM+X3ein5Q=", + "lastModified": 1759372351, + "narHash": "sha256-kULiC2oMMuyaO92gPiu+6XBfeXuFcXaauwo0tXAwXdQ=", "owner": "oxalica", "repo": "rust-overlay", - "rev": "f46d294b87ebb9f7124f1ce13aa2a5f5acc0f3eb", + "rev": "7ef14552303de7128662666f9a71342099ffc725", "type": "github" }, "original": { From e581dcbf628c4503515367c3e1471c9d88e00cca Mon Sep 17 00:00:00 2001 From: lollerfirst <43107113+lollerfirst@users.noreply.github.com> Date: Fri, 3 Oct 2025 15:39:57 +0200 Subject: [PATCH 203/321] feat: tor isolated circuits (#1064) fixes + tor feature in cdk-cli fix: call `clone_with_prefs` to get a new isolation token format remove `new_isolated` from Transport trait fix: remove tor dependencies under wasm32, disallow compilation with tor feature and wasm32 tor_transport in its own file fixes fmt format tor: implement Transport::resolve_dns_txt for TorAsync using DoH over Tor; fix tor transport trait changes after rebase; remove unused as_str() call for TorToggle in cdk-cli. Ensure compilation with features: tor,bip353 format remove double reference format feat: circuits pool format tor_transport: deterministically select Tor client per request using index_for_request(endpoint path + query + payload)\n\n- Add index_for_request(&Url, Option<&[u8]>) using FNV-1a 64-bit (dependency-free)\n- Replace round-robin next_index() usage in request() with deterministic index\n- Adjust request() to accept Option> body to hash payload bytes\n- Update http_get/http_post/resolve_dns_txt to call new request signature\n- Keep next_index() as dead_code for potential fallback tor_transport: implement Default by bootstrapping with default pool size (blocking)\n\n- Default now attempts to use existing Tokio runtime handle, or creates a temporary runtime\n- Preserves previous behavior for async constructors (new/with_pool_size) tor_transport: fix Default to avoid nested runtime panic by initializing on a new thread when no Handle available\n\n- If a runtime is present, block_on via current handle\n- Otherwise, spawn a new OS thread and create a runtime inside it, then join tor_transport: rework Default to use block_in_place + background thread runtime to avoid nested block_on inside tokio\n\n- Always create runtime on a separate OS thread; if inside tokio, enter block_in_place first\n- Avoids 'Cannot start a runtime from within a runtime' panic fix more fixes tor_transport: lazy-initialize Tor client pool on first use via ensure_pool; make Default non-blocking and remove runtime gymnastics\n\n- Introduce Inner with OnceCell>> and configured size\n- Default/new/with_pool_size now cheap; actual arti bootstrap happens on first request\n- request() calls ensure_pool() and uses deterministic index with pool.len()\n- Keeps deterministic endpoint/method/body affinity and DoH TXT resolution\n\nThis avoids nested-runtime/block_in_place complexity and makes Default trivial. tor_transport: make DEFAULT_TOR_POOL_SIZE public and support custom pool sizes via TorAsync::with_pool_size() (lazy)} remove unneeded async add salt to keyed circuit selection --- crates/cdk-cli/Cargo.toml | 1 + crates/cdk-cli/src/main.rs | 46 ++- crates/cdk/Cargo.toml | 22 ++ crates/cdk/src/lib.rs | 4 + .../src/wallet/mint_connector/http_client.rs | 51 ++- crates/cdk/src/wallet/mint_connector/mod.rs | 5 +- .../src/wallet/mint_connector/transport.rs | 25 +- .../mint_connector/transport/tor_transport.rs | 330 ++++++++++++++++++ crates/cdk/src/wallet/mod.rs | 2 + crates/cdk/src/wallet/multi_mint_wallet.rs | 93 ++++- 10 files changed, 539 insertions(+), 40 deletions(-) create mode 100644 crates/cdk/src/wallet/mint_connector/transport/tor_transport.rs diff --git a/crates/cdk-cli/Cargo.toml b/crates/cdk-cli/Cargo.toml index 92eba990b..6597d31a6 100644 --- a/crates/cdk-cli/Cargo.toml +++ b/crates/cdk-cli/Cargo.toml @@ -15,6 +15,7 @@ default = [] sqlcipher = ["cdk-sqlite/sqlcipher"] # MSRV is not tracked with redb enabled redb = ["dep:cdk-redb"] +tor = ["cdk/tor"] [dependencies] anyhow.workspace = true diff --git a/crates/cdk-cli/src/main.rs b/crates/cdk-cli/src/main.rs index 2d3bbfa1b..01394a9e8 100644 --- a/crates/cdk-cli/src/main.rs +++ b/crates/cdk-cli/src/main.rs @@ -13,6 +13,8 @@ use cdk::wallet::MultiMintWallet; #[cfg(feature = "redb")] use cdk_redb::WalletRedbDatabase; use cdk_sqlite::WalletSqliteDatabase; +#[cfg(all(feature = "tor", not(target_arch = "wasm32")))] +use clap::ValueEnum; use clap::{Parser, Subcommand}; use tracing::Level; use tracing_subscriber::EnvFilter; @@ -27,11 +29,15 @@ const DEFAULT_WORK_DIR: &str = ".cdk-cli"; const CARGO_PKG_VERSION: Option<&'static str> = option_env!("CARGO_PKG_VERSION"); /// Simple CLI application to interact with cashu +#[cfg(all(feature = "tor", not(target_arch = "wasm32")))] +#[derive(Copy, Clone, Debug, ValueEnum)] +enum TorToggle { + On, + Off, +} + #[derive(Parser)] -#[command(name = "cdk-cli")] -#[command(author = "thesimplekid ")] -#[command(version = CARGO_PKG_VERSION.unwrap_or("Unknown"))] -#[command(author, version, about, long_about = None)] +#[command(name = "cdk-cli", author = "thesimplekid ", version = CARGO_PKG_VERSION.unwrap_or("Unknown"), about, long_about = None)] struct Cli { /// Database engine to use (sqlite/redb) #[arg(short, long, default_value = "sqlite")] @@ -52,6 +58,11 @@ struct Cli { /// Currency unit to use for the wallet #[arg(short, long, default_value = "sat")] unit: String, + /// Use Tor transport (only when built with --features tor). Defaults to 'on' when feature is enabled. + #[cfg(all(feature = "tor", not(target_arch = "wasm32")))] + #[arg(long = "tor", value_enum, default_value_t = TorToggle::On)] + transport: TorToggle, + /// Subcommand to run #[command(subcommand)] command: Commands, } @@ -120,8 +131,6 @@ async fn main() -> Result<()> { } }; - fs::create_dir_all(&work_dir)?; - let localstore: Arc + Send + Sync> = match args.engine.as_str() { "sqlite" => { @@ -181,7 +190,6 @@ async fn main() -> Result<()> { // The constructor will automatically load wallets for this currency unit let multi_mint_wallet = match &args.proxy { Some(proxy_url) => { - // Create MultiMintWallet with proxy configuration MultiMintWallet::new_with_proxy( localstore.clone(), seed, @@ -190,7 +198,29 @@ async fn main() -> Result<()> { ) .await? } - None => MultiMintWallet::new(localstore.clone(), seed, currency_unit.clone()).await?, + None => { + #[cfg(all(feature = "tor", not(target_arch = "wasm32")))] + { + match args.transport { + TorToggle::On => { + MultiMintWallet::new_with_tor( + localstore.clone(), + seed, + currency_unit.clone(), + ) + .await? + } + TorToggle::Off => { + MultiMintWallet::new(localstore.clone(), seed, currency_unit.clone()) + .await? + } + } + } + #[cfg(not(all(feature = "tor", not(target_arch = "wasm32"))))] + { + MultiMintWallet::new(localstore.clone(), seed, currency_unit.clone()).await? + } + } }; match &args.command { diff --git a/crates/cdk/Cargo.toml b/crates/cdk/Cargo.toml index 24e75cefe..c21dc59d9 100644 --- a/crates/cdk/Cargo.toml +++ b/crates/cdk/Cargo.toml @@ -21,6 +21,17 @@ bip353 = ["dep:hickory-resolver"] swagger = ["mint", "dep:utoipa", "cdk-common/swagger"] bench = [] http_subscription = [] +tor = [ + "wallet", + "dep:arti-client", + "dep:arti-hyper", + "dep:hyper", + "dep:http", + "dep:rustls", + "dep:tor-rtcompat", + "dep:tls-api", + "dep:tls-api-native-tls", +] prometheus = ["dep:cdk-prometheus"] [dependencies] @@ -40,6 +51,7 @@ serde_json.workspace = true serde_with.workspace = true tracing.workspace = true thiserror.workspace = true + futures = { workspace = true, optional = true, features = ["alloc"] } url.workspace = true utoipa = { workspace = true, optional = true } @@ -70,13 +82,23 @@ tokio-tungstenite = { workspace = true, features = [ "rustls-tls-native-roots", "connect" ] } +# Tor dependencies (optional; enabled by feature "tor") +hyper = { version = "0.14", optional = true, features = ["client", "http1", "http2"] } +http = { version = "0.2", optional = true } +arti-client = { version = "0.19.0", optional = true, default-features = false, features = ["tokio", "rustls"] } +arti-hyper = { version = "0.19.0", optional = true } rustls = { workspace = true, optional = true } +tor-rtcompat = { version = "0.19.0", optional = true, features = ["tokio", "rustls"] } +tls-api = { version = "0.9", optional = true } +tls-api-native-tls = { version = "0.9", optional = true } [target.'cfg(target_arch = "wasm32")'.dependencies] tokio = { workspace = true, features = ["rt", "macros", "sync", "time"] } cdk-signatory = { workspace = true, default-features = false } getrandom = { version = "0.2", features = ["js"] } ring = { version = "0.17.14", features = ["wasm32_unknown_unknown_js"] } +rustls = { workspace = true, optional = true } + uuid = { workspace = true, features = ["js"] } wasm-bindgen = "0.2" wasm-bindgen-futures = "0.4" diff --git a/crates/cdk/src/lib.rs b/crates/cdk/src/lib.rs index c1e89c7e2..d26076ebd 100644 --- a/crates/cdk/src/lib.rs +++ b/crates/cdk/src/lib.rs @@ -3,6 +3,10 @@ #![warn(missing_docs)] #![warn(rustdoc::bare_urls)] +// Disallow enabling `tor` feature on wasm32 with a clear error. +#[cfg(all(target_arch = "wasm32", feature = "tor"))] +compile_error!("The 'tor' feature is not supported on wasm32 targets (browser). Disable the 'tor' feature or use a non-wasm32 target."); + pub mod cdk_database { //! CDK Database pub use cdk_common::database::Error; diff --git a/crates/cdk/src/wallet/mint_connector/http_client.rs b/crates/cdk/src/wallet/mint_connector/http_client.rs index 1a954a724..3533417c9 100644 --- a/crates/cdk/src/wallet/mint_connector/http_client.rs +++ b/crates/cdk/src/wallet/mint_connector/http_client.rs @@ -47,6 +47,31 @@ impl HttpClient where T: Transport + Send + Sync + 'static, { + /// Create new [`HttpClient`] with a provided transport implementation. + #[cfg(feature = "auth")] + pub fn with_transport( + mint_url: MintUrl, + transport: T, + auth_wallet: Option, + ) -> Self { + Self { + transport: transport.into(), + mint_url, + auth_wallet: Arc::new(RwLock::new(auth_wallet)), + cache_support: Default::default(), + } + } + + /// Create new [`HttpClient`] with a provided transport implementation. + #[cfg(not(feature = "auth"))] + pub fn with_transport(mint_url: MintUrl, transport: T) -> Self { + Self { + transport: transport.into(), + mint_url, + cache_support: Default::default(), + } + } + /// Create new [`HttpClient`] #[cfg(feature = "auth")] pub fn new(mint_url: MintUrl, auth_wallet: Option) -> Self { @@ -137,22 +162,20 @@ where .map(Duration::from_secs) .unwrap_or_default(); + let transport = self.transport.clone(); loop { let url = self.mint_url.join_paths(&match path { nut19::Path::MintBolt11 => vec!["v1", "mint", "bolt11"], nut19::Path::MeltBolt11 => vec!["v1", "melt", "bolt11"], nut19::Path::MintBolt12 => vec!["v1", "mint", "bolt12"], + nut19::Path::MeltBolt12 => vec!["v1", "melt", "bolt12"], nut19::Path::Swap => vec!["v1", "swap"], })?; let result = match method { - nut19::Method::Get => self.transport.http_get(url, auth_token.clone()).await, - nut19::Method::Post => { - self.transport - .http_post(url, auth_token.clone(), payload) - .await - } + nut19::Method::Get => transport.http_get(url, auth_token.clone()).await, + nut19::Method::Post => transport.http_post(url, auth_token.clone(), payload).await, }; if result.is_ok() { @@ -197,12 +220,9 @@ where #[instrument(skip(self), fields(mint_url = %self.mint_url))] async fn get_mint_keys(&self) -> Result, Error> { let url = self.mint_url.join_paths(&["v1", "keys"])?; + let transport = self.transport.clone(); - Ok(self - .transport - .http_get::(url, None) - .await? - .keysets) + Ok(transport.http_get::(url, None).await?.keysets) } /// Get Keyset Keys [NUT-01] @@ -212,7 +232,8 @@ where .mint_url .join_paths(&["v1", "keys", &keyset_id.to_string()])?; - let keys_response = self.transport.http_get::(url, None).await?; + let transport = self.transport.clone(); + let keys_response = transport.http_get::(url, None).await?; Ok(keys_response.keysets.first().unwrap().clone()) } @@ -221,7 +242,8 @@ where #[instrument(skip(self), fields(mint_url = %self.mint_url))] async fn get_mint_keysets(&self) -> Result { let url = self.mint_url.join_paths(&["v1", "keysets"])?; - self.transport.http_get(url, None).await + let transport = self.transport.clone(); + transport.http_get(url, None).await } /// Mint Quote [NUT-04] @@ -368,7 +390,8 @@ where /// Helper to get mint info async fn get_mint_info(&self) -> Result { let url = self.mint_url.join_paths(&["v1", "info"])?; - let info: MintInfo = self.transport.http_get(url, None).await?; + let transport = self.transport.clone(); + let info: MintInfo = transport.http_get(url, None).await?; if let Ok(mut cache_support) = self.cache_support.write() { *cache_support = ( diff --git a/crates/cdk/src/wallet/mint_connector/mod.rs b/crates/cdk/src/wallet/mint_connector/mod.rs index 3b9a73ea3..e199bdde8 100644 --- a/crates/cdk/src/wallet/mint_connector/mod.rs +++ b/crates/cdk/src/wallet/mint_connector/mod.rs @@ -21,8 +21,11 @@ pub mod transport; /// Auth HTTP Client with async transport #[cfg(feature = "auth")] pub type AuthHttpClient = http_client::AuthHttpClient; -/// Http Client with async transport +/// Default Http Client with async transport (non-Tor) pub type HttpClient = http_client::HttpClient; +/// Tor Http Client with async transport (only when `tor` feature is enabled and not on wasm32) +#[cfg(all(feature = "tor", not(target_arch = "wasm32")))] +pub type TorHttpClient = http_client::HttpClient; /// Interface that connects a wallet to a mint. Typically represents an [HttpClient]. #[cfg_attr(target_arch = "wasm32", async_trait(?Send))] diff --git a/crates/cdk/src/wallet/mint_connector/transport.rs b/crates/cdk/src/wallet/mint_connector/transport.rs index 112ebc245..8238c9cec 100644 --- a/crates/cdk/src/wallet/mint_connector/transport.rs +++ b/crates/cdk/src/wallet/mint_connector/transport.rs @@ -27,26 +27,30 @@ pub trait Transport: Default + Send + Sync + Debug + Clone { /// Make the transport to use a given proxy fn with_proxy( &mut self, - proxy: Url, + proxy: url::Url, host_matcher: Option<&str>, accept_invalid_certs: bool, - ) -> Result<(), Error>; + ) -> Result<(), super::Error>; /// HTTP Get request - async fn http_get(&self, url: Url, auth: Option) -> Result + async fn http_get( + &self, + url: url::Url, + auth: Option, + ) -> Result where - R: DeserializeOwned; + R: serde::de::DeserializeOwned; /// HTTP Post request async fn http_post( &self, - url: Url, - auth_token: Option, + url: url::Url, + auth_token: Option, payload: &P, - ) -> Result + ) -> Result where - P: Serialize + ?Sized + Send + Sync, - R: DeserializeOwned; + P: serde::Serialize + ?Sized + Send + Sync, + R: serde::de::DeserializeOwned; } /// Async transport for Http @@ -212,3 +216,6 @@ impl Transport for Async { }) } } + +#[cfg(all(feature = "tor", not(target_arch = "wasm32")))] +pub mod tor_transport; diff --git a/crates/cdk/src/wallet/mint_connector/transport/tor_transport.rs b/crates/cdk/src/wallet/mint_connector/transport/tor_transport.rs new file mode 100644 index 000000000..4fb93710f --- /dev/null +++ b/crates/cdk/src/wallet/mint_connector/transport/tor_transport.rs @@ -0,0 +1,330 @@ +///! Tor transport implementation (non-wasm32 only) +use std::sync::Arc; + +use arti_client::{TorClient, TorClientConfig}; +use arti_hyper::ArtiHttpConnector; +use async_trait::async_trait; +use cdk_common::AuthToken; +use http::header::{self, HeaderName, HeaderValue}; +use hyper::http::{Method, Request, Uri}; +use hyper::{Body, Client}; +use serde::de::DeserializeOwned; +use tls_api::{TlsConnector as _, TlsConnectorBuilder as _}; +use tokio::sync::OnceCell; +use url::Url; + +use super::super::Error; +use crate::wallet::getrandom; +use crate::wallet::mint_connector::transport::{ErrorResponse, Transport}; + +/// Fixed-size pool size +pub const DEFAULT_TOR_POOL_SIZE: usize = 5; + +/// Tor transport that maintains a pool of isolated TorClient handles +#[derive(Clone)] +pub struct TorAsync { + salt: [u8; 4], + size: usize, + pool: Arc>>>, +} + +impl std::fmt::Debug for TorAsync { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + let pool_len = self.pool.get().map(|p| p.len()); + f.debug_struct("TorAsync") + .field("configured_pool_size", &self.size) + .field("initialized_pool_size", &pool_len) + .finish() + } +} + +// salt generator (sync, tiny, uses OS RNG) +#[inline] +fn gen_salt() -> [u8; 4] { + let mut s = [0u8; 4]; + getrandom(&mut s).expect("failed to obtain random bytes for TorAsync salt"); + s +} + +impl Default for TorAsync { + fn default() -> Self { + // Do NOT bootstrap here; keep Default cheap and non-blocking. + Self { + size: DEFAULT_TOR_POOL_SIZE, + pool: Arc::new(OnceCell::new()), + salt: gen_salt(), + } + } +} + +impl TorAsync { + /// Create a TorAsync with default pool size (lazy bootstrapping) + pub fn new() -> Self { + Self::default() + } + + /// Create a TorAsync with the given pool size (lazy bootstrapping) + pub fn with_pool_size(size: usize) -> Self { + let size = size.max(1); + Self { + size, + pool: Arc::new(OnceCell::new()), + salt: gen_salt(), + } + } + + /// Ensure the Tor client pool is initialized; build on first use. + async fn ensure_pool(&self) -> Result>, Error> { + let size = self.size; + let pool_ref = self + .pool + .get_or_try_init(|| async move { + let base = TorClient::create_bootstrapped(TorClientConfig::default()) + .await + .map_err(|e| Error::Custom(e.to_string()))?; + let mut clients = Vec::with_capacity(size); + for _ in 0..size { + clients.push(base.isolated_client()); + } + Ok::>, Error>(clients) + }) + .await?; + Ok(pool_ref.clone()) + } + + /// Choose client index deterministically based on authority (scheme, host, port), + /// HTTP method, path+query, and optionally a body fingerprint. + #[inline] + fn index_for_request( + &self, + method: &http::Method, + url: &Url, + body: Option<&[u8]>, + pool_len: usize, + ) -> usize { + // Tiny, dependency-free, stable hash (FNV-1a 64-bit) + const FNV_OFFSET: u64 = 0xcbf29ce484222325; + const FNV_PRIME: u64 = 0x0000_0100_0000_01B3; + fn fnv1a(mut h: u64, bytes: &[u8]) -> u64 { + for &b in bytes { + h ^= b as u64; + h = h.wrapping_mul(FNV_PRIME); + } + h + } + + let mut h = FNV_OFFSET; + + // Mix in salt first so it affects the entire hash space + h = fnv1a(h, &self.salt); + // Include scheme and authority + h = fnv1a(h, url.scheme().as_bytes()); + h = fnv1a(h, b"://"); + if let Some(host) = url.host_str() { + h = fnv1a(h, host.as_bytes()); + } + if let Some(port) = url.port() { + h = fnv1a(h, b":"); + let p = port.to_string(); + h = fnv1a(h, p.as_bytes()); + } + // Include HTTP method + h = fnv1a(h, method.as_str().as_bytes()); + h = fnv1a(h, b" "); + // Include path and query + h = fnv1a(h, url.path().as_bytes()); + if let Some(q) = url.query() { + h = fnv1a(h, b"?"); + h = fnv1a(h, q.as_bytes()); + } + // Optionally include body (full). Could be trimmed in the future if needed. + if let Some(b) = body { + h = fnv1a(h, b); + } + (h as usize) % pool_len.max(1) + } + + async fn request( + &self, + method: http::Method, + url: Url, + auth: Option, + mut body: Option>, + ) -> Result + where + R: DeserializeOwned, + { + let tls = tls_api_native_tls::TlsConnector::builder() + .map_err(|e| Error::Custom(format!("{e:?}")))? + .build() + .map_err(|e| Error::Custom(format!("{e:?}")))?; + + // Lazily initialize the pool and deterministically select a client + let pool = self.ensure_pool().await?; + let idx = self.index_for_request(&method, &url, body.as_deref(), pool.len()); + let client_for_request = pool[idx].clone(); + + let connector = ArtiHttpConnector::new(client_for_request, tls); + let client: Client<_> = Client::builder().build(connector); + + let uri: Uri = url + .as_str() + .parse::() + .map_err(|e| Error::Custom(e.to_string()))?; + + let mut builder = Request::builder().method(method).uri(uri); + builder = builder.header(header::ACCEPT, "application/json"); + + let mut req = if let Some(b) = body.take() { + builder + .header(http::header::CONTENT_TYPE, "application/json") + .body(Body::from(b)) + .map_err(|e| Error::Custom(e.to_string()))? + } else { + builder + .body(Body::empty()) + .map_err(|e| Error::Custom(e.to_string()))? + }; + + if let Some(auth) = auth { + let key = auth.header_key(); + let val = auth.to_string(); + req.headers_mut().insert( + HeaderName::from_bytes(key.as_bytes()).map_err(|e| Error::Custom(e.to_string()))?, + HeaderValue::from_str(&val).map_err(|e| Error::Custom(e.to_string()))?, + ); + } + + let resp = client + .request(req) + .await + .map_err(|e| Error::HttpError(None, e.to_string()))?; + + let status = resp.status().as_u16(); + let bytes = hyper::body::to_bytes(resp.into_body()) + .await + .map_err(|e| Error::HttpError(None, e.to_string()))?; + + if !(200..300).contains(&status) { + let text = String::from_utf8_lossy(&bytes).to_string(); + return Err(Error::HttpError(Some(status), text)); + } + + serde_json::from_slice::(&bytes).map_err(|err| { + let text = String::from_utf8_lossy(&bytes).to_string(); + tracing::warn!("Http Response error: {}", err); + match ErrorResponse::from_json(&text) { + Ok(ok) => >::into(ok), + Err(err) => err.into(), + } + }) + } +} + +#[async_trait] +impl Transport for TorAsync { + fn with_proxy( + &mut self, + _proxy: Url, + _host_matcher: Option<&str>, + _accept_invalid_certs: bool, + ) -> Result<(), Error> { + panic!("not supported with TorAsync transport"); + } + + async fn http_get( + &self, + url: url::Url, + auth: Option, + ) -> Result + where + R: serde::de::DeserializeOwned, + { + self.request::(Method::GET, url, auth, None).await + } + + async fn http_post( + &self, + url: url::Url, + auth_token: Option, + payload: &P, + ) -> Result + where + P: serde::Serialize + ?Sized + Send + Sync, + R: serde::de::DeserializeOwned, + { + let body = serde_json::to_vec(payload).map_err(|e| Error::Custom(e.to_string()))?; + self.request::(Method::POST, url, auth_token, Some(body)) + .await + } + + #[cfg(all(feature = "bip353", not(target_arch = "wasm32")))] + async fn resolve_dns_txt(&self, domain: &str) -> Result, Error> { + #[derive(serde::Deserialize)] + struct Answer { + #[serde(default)] + data: String, + #[allow(dead_code)] + #[serde(default)] + name: String, + #[allow(dead_code)] + #[serde(default)] + r#type: u32, + } + + #[allow(non_snake_case)] + #[derive(serde::Deserialize)] + struct DnsResp { + #[serde(default)] + Answer: Option>, + #[allow(dead_code)] + #[serde(default)] + Status: Option, + } + + fn dequote_txt(s: &str) -> String { + let mut result = String::new(); + let mut in_quote = false; + let mut buf = String::new(); + for ch in s.chars() { + if ch == '"' { + if in_quote { + result.push_str(&buf); + buf.clear(); + in_quote = false; + } else { + in_quote = true; + } + } else if in_quote { + buf.push(ch); + } + } + if !result.is_empty() { + result + } else { + s.trim_matches('"').to_string() + } + } + + let mut url = + Url::parse("https://dns.google/resolve").map_err(|e| Error::Custom(e.to_string()))?; + { + let mut qp = url.query_pairs_mut(); + qp.append_pair("name", domain); + qp.append_pair("type", "TXT"); + } + + let resp: DnsResp = self + .request::(Method::GET, url, None, None::>) + .await?; + + let answers = resp.Answer.unwrap_or_default(); + let txts = answers + .into_iter() + .filter(|a| !a.data.is_empty()) + .map(|a| dequote_txt(&a.data)) + .collect::>(); + + Ok(txts) + } +} diff --git a/crates/cdk/src/wallet/mod.rs b/crates/cdk/src/wallet/mod.rs index c2adec46e..5f2319f25 100644 --- a/crates/cdk/src/wallet/mod.rs +++ b/crates/cdk/src/wallet/mod.rs @@ -33,6 +33,8 @@ use crate::OidcClient; #[cfg(feature = "auth")] mod auth; +#[cfg(all(feature = "tor", not(target_arch = "wasm32")))] +pub use mint_connector::TorHttpClient; mod balance; mod builder; mod issue; diff --git a/crates/cdk/src/wallet/multi_mint_wallet.rs b/crates/cdk/src/wallet/multi_mint_wallet.rs index 125a4eb23..9534f1a13 100644 --- a/crates/cdk/src/wallet/multi_mint_wallet.rs +++ b/crates/cdk/src/wallet/multi_mint_wallet.rs @@ -25,6 +25,8 @@ use crate::nuts::nut00::ProofsMethods; use crate::nuts::nut23::QuoteState; use crate::nuts::{CurrencyUnit, MeltOptions, Proof, Proofs, SpendingConditions, Token}; use crate::types::Melted; +#[cfg(all(feature = "tor", not(target_arch = "wasm32")))] +use crate::wallet::mint_connector::transport::tor_transport::TorAsync; use crate::wallet::types::MintQuote; use crate::{Amount, Wallet}; @@ -114,6 +116,9 @@ pub struct MultiMintWallet { wallets: Arc>>, /// Proxy configuration for HTTP clients (optional) proxy_config: Option, + /// Shared Tor transport to be cloned into each TorHttpClient (if enabled) + #[cfg(all(feature = "tor", not(target_arch = "wasm32")))] + shared_tor_transport: Option, } impl MultiMintWallet { @@ -129,6 +134,8 @@ impl MultiMintWallet { unit, wallets: Arc::new(RwLock::new(BTreeMap::new())), proxy_config: None, + #[cfg(all(feature = "tor", not(target_arch = "wasm32")))] + shared_tor_transport: None, }; // Automatically load wallets from database for this currency unit @@ -153,6 +160,35 @@ impl MultiMintWallet { unit, wallets: Arc::new(RwLock::new(BTreeMap::new())), proxy_config: Some(proxy_url), + #[cfg(all(feature = "tor", not(target_arch = "wasm32")))] + shared_tor_transport: None, + }; + + // Automatically load wallets from database for this currency unit + wallet.load_wallets().await?; + + Ok(wallet) + } + + /// Create a new [MultiMintWallet] with Tor transport for all wallets + /// + /// When the `tor` feature is enabled (and not on wasm32), this constructor + /// creates a single Tor transport (TorAsync) that is cloned into each + /// TorHttpClient used by per-mint Wallets. This ensures only one Tor instance + /// is bootstrapped and shared across wallets. + #[cfg(all(feature = "tor", not(target_arch = "wasm32")))] + pub async fn new_with_tor( + localstore: Arc + Send + Sync>, + seed: [u8; 64], + unit: CurrencyUnit, + ) -> Result { + let wallet = Self { + localstore, + seed, + unit, + wallets: Arc::new(RwLock::new(BTreeMap::new())), + proxy_config: None, + shared_tor_transport: Some(TorAsync::new()), }; // Automatically load wallets from database for this currency unit @@ -195,14 +231,55 @@ impl MultiMintWallet { .client(client) .build()? } else { - // Create wallet with default client - Wallet::new( - &mint_url.to_string(), - self.unit.clone(), - self.localstore.clone(), - self.seed, - target_proof_count, - )? + #[cfg(all(feature = "tor", not(target_arch = "wasm32")))] + if let Some(tor) = &self.shared_tor_transport { + // Create wallet with Tor transport client, cloning the shared transport + let client = { + let transport = tor.clone(); + #[cfg(feature = "auth")] + { + crate::wallet::TorHttpClient::with_transport( + mint_url.clone(), + transport, + None, + ) + } + #[cfg(not(feature = "auth"))] + { + crate::wallet::TorHttpClient::with_transport(mint_url.clone(), transport) + } + }; + + WalletBuilder::new() + .mint_url(mint_url.clone()) + .unit(self.unit.clone()) + .localstore(self.localstore.clone()) + .seed(self.seed) + .target_proof_count(target_proof_count.unwrap_or(3)) + .client(client) + .build()? + } else { + // Create wallet with default client + Wallet::new( + &mint_url.to_string(), + self.unit.clone(), + self.localstore.clone(), + self.seed, + target_proof_count, + )? + } + + #[cfg(not(all(feature = "tor", not(target_arch = "wasm32"))))] + { + // Create wallet with default client + Wallet::new( + &mint_url.to_string(), + self.unit.clone(), + self.localstore.clone(), + self.seed, + target_proof_count, + )? + } }; let mut wallets = self.wallets.write().await; From a8c35dbef020471f896f95ceb3a4aa2cad397318 Mon Sep 17 00:00:00 2001 From: David Caseria Date: Sun, 5 Oct 2025 07:15:33 -0400 Subject: [PATCH 204/321] Split uniffi types into multiple mods (#1142) --- crates/cdk-ffi/src/types.rs | 2883 ---------------------- crates/cdk-ffi/src/types/amount.rs | 166 ++ crates/cdk-ffi/src/types/keys.rs | 258 ++ crates/cdk-ffi/src/types/mint.rs | 675 +++++ crates/cdk-ffi/src/types/mod.rs | 24 + crates/cdk-ffi/src/types/proof.rs | 509 ++++ crates/cdk-ffi/src/types/quote.rs | 430 ++++ crates/cdk-ffi/src/types/subscription.rs | 183 ++ crates/cdk-ffi/src/types/transaction.rs | 247 ++ crates/cdk-ffi/src/types/wallet.rs | 471 ++++ 10 files changed, 2963 insertions(+), 2883 deletions(-) delete mode 100644 crates/cdk-ffi/src/types.rs create mode 100644 crates/cdk-ffi/src/types/amount.rs create mode 100644 crates/cdk-ffi/src/types/keys.rs create mode 100644 crates/cdk-ffi/src/types/mint.rs create mode 100644 crates/cdk-ffi/src/types/mod.rs create mode 100644 crates/cdk-ffi/src/types/proof.rs create mode 100644 crates/cdk-ffi/src/types/quote.rs create mode 100644 crates/cdk-ffi/src/types/subscription.rs create mode 100644 crates/cdk-ffi/src/types/transaction.rs create mode 100644 crates/cdk-ffi/src/types/wallet.rs diff --git a/crates/cdk-ffi/src/types.rs b/crates/cdk-ffi/src/types.rs deleted file mode 100644 index 1a6d1d4df..000000000 --- a/crates/cdk-ffi/src/types.rs +++ /dev/null @@ -1,2883 +0,0 @@ -//! FFI-compatible types - -use std::collections::HashMap; -use std::str::FromStr; -use std::sync::Mutex; - -use cdk::nuts::{CurrencyUnit as CdkCurrencyUnit, State as CdkState}; -use cdk::pub_sub::SubId; -use cdk::Amount as CdkAmount; -use serde::{Deserialize, Serialize}; - -use crate::error::FfiError; -use crate::token::Token; - -/// FFI-compatible Amount type -#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, uniffi::Record)] -#[serde(transparent)] -pub struct Amount { - pub value: u64, -} - -impl Amount { - pub fn new(value: u64) -> Self { - Self { value } - } - - pub fn zero() -> Self { - Self { value: 0 } - } - - pub fn is_zero(&self) -> bool { - self.value == 0 - } - - pub fn convert_unit( - &self, - current_unit: CurrencyUnit, - target_unit: CurrencyUnit, - ) -> Result { - Ok(CdkAmount::from(self.value) - .convert_unit(¤t_unit.into(), &target_unit.into()) - .map(Into::into)?) - } - - pub fn add(&self, other: Amount) -> Result { - let self_amount = CdkAmount::from(self.value); - let other_amount = CdkAmount::from(other.value); - self_amount - .checked_add(other_amount) - .map(Into::into) - .ok_or(FfiError::AmountOverflow) - } - - pub fn subtract(&self, other: Amount) -> Result { - let self_amount = CdkAmount::from(self.value); - let other_amount = CdkAmount::from(other.value); - self_amount - .checked_sub(other_amount) - .map(Into::into) - .ok_or(FfiError::AmountOverflow) - } - - pub fn multiply(&self, factor: u64) -> Result { - let self_amount = CdkAmount::from(self.value); - let factor_amount = CdkAmount::from(factor); - self_amount - .checked_mul(factor_amount) - .map(Into::into) - .ok_or(FfiError::AmountOverflow) - } - - pub fn divide(&self, divisor: u64) -> Result { - if divisor == 0 { - return Err(FfiError::DivisionByZero); - } - let self_amount = CdkAmount::from(self.value); - let divisor_amount = CdkAmount::from(divisor); - self_amount - .checked_div(divisor_amount) - .map(Into::into) - .ok_or(FfiError::AmountOverflow) - } -} - -impl From for Amount { - fn from(amount: CdkAmount) -> Self { - Self { - value: u64::from(amount), - } - } -} - -impl From for CdkAmount { - fn from(amount: Amount) -> Self { - CdkAmount::from(amount.value) - } -} - -/// FFI-compatible Currency Unit -#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, uniffi::Enum)] -pub enum CurrencyUnit { - Sat, - Msat, - Usd, - Eur, - Auth, - Custom { unit: String }, -} - -impl From for CurrencyUnit { - fn from(unit: CdkCurrencyUnit) -> Self { - match unit { - CdkCurrencyUnit::Sat => CurrencyUnit::Sat, - CdkCurrencyUnit::Msat => CurrencyUnit::Msat, - CdkCurrencyUnit::Usd => CurrencyUnit::Usd, - CdkCurrencyUnit::Eur => CurrencyUnit::Eur, - CdkCurrencyUnit::Auth => CurrencyUnit::Auth, - CdkCurrencyUnit::Custom(s) => CurrencyUnit::Custom { unit: s }, - _ => CurrencyUnit::Sat, // Default for unknown units - } - } -} - -impl From for CdkCurrencyUnit { - fn from(unit: CurrencyUnit) -> Self { - match unit { - CurrencyUnit::Sat => CdkCurrencyUnit::Sat, - CurrencyUnit::Msat => CdkCurrencyUnit::Msat, - CurrencyUnit::Usd => CdkCurrencyUnit::Usd, - CurrencyUnit::Eur => CdkCurrencyUnit::Eur, - CurrencyUnit::Auth => CdkCurrencyUnit::Auth, - CurrencyUnit::Custom { unit } => CdkCurrencyUnit::Custom(unit), - } - } -} - -/// FFI-compatible Mint URL -#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize, uniffi::Record)] -#[serde(transparent)] -pub struct MintUrl { - pub url: String, -} - -impl MintUrl { - pub fn new(url: String) -> Result { - // Validate URL format - url::Url::parse(&url).map_err(|e| FfiError::InvalidUrl { msg: e.to_string() })?; - - Ok(Self { url }) - } -} - -impl From for MintUrl { - fn from(mint_url: cdk::mint_url::MintUrl) -> Self { - Self { - url: mint_url.to_string(), - } - } -} - -impl TryFrom for cdk::mint_url::MintUrl { - type Error = FfiError; - - fn try_from(mint_url: MintUrl) -> Result { - cdk::mint_url::MintUrl::from_str(&mint_url.url) - .map_err(|e| FfiError::InvalidUrl { msg: e.to_string() }) - } -} - -/// FFI-compatible Proof state -#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, uniffi::Enum)] -pub enum ProofState { - Unspent, - Pending, - Spent, - Reserved, - PendingSpent, -} - -impl From for ProofState { - fn from(state: CdkState) -> Self { - match state { - CdkState::Unspent => ProofState::Unspent, - CdkState::Pending => ProofState::Pending, - CdkState::Spent => ProofState::Spent, - CdkState::Reserved => ProofState::Reserved, - CdkState::PendingSpent => ProofState::PendingSpent, - } - } -} - -impl From for CdkState { - fn from(state: ProofState) -> Self { - match state { - ProofState::Unspent => CdkState::Unspent, - ProofState::Pending => CdkState::Pending, - ProofState::Spent => CdkState::Spent, - ProofState::Reserved => CdkState::Reserved, - ProofState::PendingSpent => CdkState::PendingSpent, - } - } -} - -/// FFI-compatible SendMemo -#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] -pub struct SendMemo { - /// Memo text - pub memo: String, - /// Include memo in token - pub include_memo: bool, -} - -impl From for cdk::wallet::SendMemo { - fn from(memo: SendMemo) -> Self { - cdk::wallet::SendMemo { - memo: memo.memo, - include_memo: memo.include_memo, - } - } -} - -impl From for SendMemo { - fn from(memo: cdk::wallet::SendMemo) -> Self { - Self { - memo: memo.memo, - include_memo: memo.include_memo, - } - } -} - -impl SendMemo { - /// Convert SendMemo to JSON string - pub fn to_json(&self) -> Result { - Ok(serde_json::to_string(self)?) - } -} - -/// Decode SendMemo from JSON string -#[uniffi::export] -pub fn decode_send_memo(json: String) -> Result { - Ok(serde_json::from_str(&json)?) -} - -/// Encode SendMemo to JSON string -#[uniffi::export] -pub fn encode_send_memo(memo: SendMemo) -> Result { - Ok(serde_json::to_string(&memo)?) -} - -/// FFI-compatible SplitTarget -#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Enum)] -pub enum SplitTarget { - /// Default target; least amount of proofs - None, - /// Target amount for wallet to have most proofs that add up to value - Value { amount: Amount }, - /// Specific amounts to split into (must equal amount being split) - Values { amounts: Vec }, -} - -impl From for cdk::amount::SplitTarget { - fn from(target: SplitTarget) -> Self { - match target { - SplitTarget::None => cdk::amount::SplitTarget::None, - SplitTarget::Value { amount } => cdk::amount::SplitTarget::Value(amount.into()), - SplitTarget::Values { amounts } => { - cdk::amount::SplitTarget::Values(amounts.into_iter().map(Into::into).collect()) - } - } - } -} - -impl From for SplitTarget { - fn from(target: cdk::amount::SplitTarget) -> Self { - match target { - cdk::amount::SplitTarget::None => SplitTarget::None, - cdk::amount::SplitTarget::Value(amount) => SplitTarget::Value { - amount: amount.into(), - }, - cdk::amount::SplitTarget::Values(amounts) => SplitTarget::Values { - amounts: amounts.into_iter().map(Into::into).collect(), - }, - } - } -} - -/// FFI-compatible SendKind -#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Enum)] -pub enum SendKind { - /// Allow online swap before send if wallet does not have exact amount - OnlineExact, - /// Prefer offline send if difference is less than tolerance - OnlineTolerance { tolerance: Amount }, - /// Wallet cannot do an online swap and selected proof must be exactly send amount - OfflineExact, - /// Wallet must remain offline but can over pay if below tolerance - OfflineTolerance { tolerance: Amount }, -} - -impl From for cdk::wallet::SendKind { - fn from(kind: SendKind) -> Self { - match kind { - SendKind::OnlineExact => cdk::wallet::SendKind::OnlineExact, - SendKind::OnlineTolerance { tolerance } => { - cdk::wallet::SendKind::OnlineTolerance(tolerance.into()) - } - SendKind::OfflineExact => cdk::wallet::SendKind::OfflineExact, - SendKind::OfflineTolerance { tolerance } => { - cdk::wallet::SendKind::OfflineTolerance(tolerance.into()) - } - } - } -} - -impl From for SendKind { - fn from(kind: cdk::wallet::SendKind) -> Self { - match kind { - cdk::wallet::SendKind::OnlineExact => SendKind::OnlineExact, - cdk::wallet::SendKind::OnlineTolerance(tolerance) => SendKind::OnlineTolerance { - tolerance: tolerance.into(), - }, - cdk::wallet::SendKind::OfflineExact => SendKind::OfflineExact, - cdk::wallet::SendKind::OfflineTolerance(tolerance) => SendKind::OfflineTolerance { - tolerance: tolerance.into(), - }, - } - } -} - -/// FFI-compatible Send options -#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] -pub struct SendOptions { - /// Memo - pub memo: Option, - /// Spending conditions - pub conditions: Option, - /// Amount split target - pub amount_split_target: SplitTarget, - /// Send kind - pub send_kind: SendKind, - /// Include fee - pub include_fee: bool, - /// Maximum number of proofs to include in the token - pub max_proofs: Option, - /// Metadata - pub metadata: HashMap, -} - -impl Default for SendOptions { - fn default() -> Self { - Self { - memo: None, - conditions: None, - amount_split_target: SplitTarget::None, - send_kind: SendKind::OnlineExact, - include_fee: false, - max_proofs: None, - metadata: HashMap::new(), - } - } -} - -impl From for cdk::wallet::SendOptions { - fn from(opts: SendOptions) -> Self { - cdk::wallet::SendOptions { - memo: opts.memo.map(Into::into), - conditions: opts.conditions.and_then(|c| c.try_into().ok()), - amount_split_target: opts.amount_split_target.into(), - send_kind: opts.send_kind.into(), - include_fee: opts.include_fee, - max_proofs: opts.max_proofs.map(|p| p as usize), - metadata: opts.metadata, - } - } -} - -impl From for SendOptions { - fn from(opts: cdk::wallet::SendOptions) -> Self { - Self { - memo: opts.memo.map(Into::into), - conditions: opts.conditions.map(Into::into), - amount_split_target: opts.amount_split_target.into(), - send_kind: opts.send_kind.into(), - include_fee: opts.include_fee, - max_proofs: opts.max_proofs.map(|p| p as u32), - metadata: opts.metadata, - } - } -} - -impl SendOptions { - /// Convert SendOptions to JSON string - pub fn to_json(&self) -> Result { - Ok(serde_json::to_string(self)?) - } -} - -/// Decode SendOptions from JSON string -#[uniffi::export] -pub fn decode_send_options(json: String) -> Result { - Ok(serde_json::from_str(&json)?) -} - -/// Encode SendOptions to JSON string -#[uniffi::export] -pub fn encode_send_options(options: SendOptions) -> Result { - Ok(serde_json::to_string(&options)?) -} - -/// FFI-compatible SecretKey -#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] -#[serde(transparent)] -pub struct SecretKey { - /// Hex-encoded secret key (64 characters) - pub hex: String, -} - -impl SecretKey { - /// Create a new SecretKey from hex string - pub fn from_hex(hex: String) -> Result { - // Validate hex string length (should be 64 characters for 32 bytes) - if hex.len() != 64 { - return Err(FfiError::InvalidHex { - msg: "Secret key hex must be exactly 64 characters (32 bytes)".to_string(), - }); - } - - // Validate hex format - if !hex.chars().all(|c| c.is_ascii_hexdigit()) { - return Err(FfiError::InvalidHex { - msg: "Secret key hex contains invalid characters".to_string(), - }); - } - - Ok(Self { hex }) - } - - /// Generate a random secret key - pub fn random() -> Self { - use cdk::nuts::SecretKey as CdkSecretKey; - let secret_key = CdkSecretKey::generate(); - Self { - hex: secret_key.to_secret_hex(), - } - } -} - -impl From for cdk::nuts::SecretKey { - fn from(key: SecretKey) -> Self { - // This will panic if hex is invalid, but we validate in from_hex() - cdk::nuts::SecretKey::from_hex(&key.hex).expect("Invalid secret key hex") - } -} - -impl From for SecretKey { - fn from(key: cdk::nuts::SecretKey) -> Self { - Self { - hex: key.to_secret_hex(), - } - } -} - -/// FFI-compatible Receive options -#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] -pub struct ReceiveOptions { - /// Amount split target - pub amount_split_target: SplitTarget, - /// P2PK signing keys - pub p2pk_signing_keys: Vec, - /// Preimages for HTLC conditions - pub preimages: Vec, - /// Metadata - pub metadata: HashMap, -} - -impl Default for ReceiveOptions { - fn default() -> Self { - Self { - amount_split_target: SplitTarget::None, - p2pk_signing_keys: Vec::new(), - preimages: Vec::new(), - metadata: HashMap::new(), - } - } -} - -impl From for cdk::wallet::ReceiveOptions { - fn from(opts: ReceiveOptions) -> Self { - cdk::wallet::ReceiveOptions { - amount_split_target: opts.amount_split_target.into(), - p2pk_signing_keys: opts.p2pk_signing_keys.into_iter().map(Into::into).collect(), - preimages: opts.preimages, - metadata: opts.metadata, - } - } -} - -impl From for ReceiveOptions { - fn from(opts: cdk::wallet::ReceiveOptions) -> Self { - Self { - amount_split_target: opts.amount_split_target.into(), - p2pk_signing_keys: opts.p2pk_signing_keys.into_iter().map(Into::into).collect(), - preimages: opts.preimages, - metadata: opts.metadata, - } - } -} - -impl ReceiveOptions { - /// Convert ReceiveOptions to JSON string - pub fn to_json(&self) -> Result { - Ok(serde_json::to_string(self)?) - } -} - -/// Decode ReceiveOptions from JSON string -#[uniffi::export] -pub fn decode_receive_options(json: String) -> Result { - Ok(serde_json::from_str(&json)?) -} - -/// Encode ReceiveOptions to JSON string -#[uniffi::export] -pub fn encode_receive_options(options: ReceiveOptions) -> Result { - Ok(serde_json::to_string(&options)?) -} - -/// FFI-compatible Proof -#[derive(Debug, uniffi::Object)] -pub struct Proof { - pub(crate) inner: cdk::nuts::Proof, -} - -impl From for Proof { - fn from(proof: cdk::nuts::Proof) -> Self { - Self { inner: proof } - } -} - -impl From for cdk::nuts::Proof { - fn from(proof: Proof) -> Self { - proof.inner - } -} - -#[uniffi::export] -impl Proof { - /// Get the amount - pub fn amount(&self) -> Amount { - self.inner.amount.into() - } - - /// Get the secret as string - pub fn secret(&self) -> String { - self.inner.secret.to_string() - } - - /// Get the unblinded signature (C) as string - pub fn c(&self) -> String { - self.inner.c.to_string() - } - - /// Get the keyset ID as string - pub fn keyset_id(&self) -> String { - self.inner.keyset_id.to_string() - } - - /// Get the witness - pub fn witness(&self) -> Option { - self.inner.witness.as_ref().map(|w| w.clone().into()) - } - - /// Check if proof is active with given keyset IDs - pub fn is_active(&self, active_keyset_ids: Vec) -> bool { - use cdk::nuts::Id; - let ids: Vec = active_keyset_ids - .into_iter() - .filter_map(|id| Id::from_str(&id).ok()) - .collect(); - self.inner.is_active(&ids) - } - - /// Get the Y value (hash_to_curve of secret) - pub fn y(&self) -> Result { - Ok(self.inner.y()?.to_string()) - } - - /// Get the DLEQ proof if present - pub fn dleq(&self) -> Option { - self.inner.dleq.as_ref().map(|d| d.clone().into()) - } - - /// Check if proof has DLEQ proof - pub fn has_dleq(&self) -> bool { - self.inner.dleq.is_some() - } -} - -/// FFI-compatible Proofs (vector of Proof) -pub type Proofs = Vec>; - -/// FFI-compatible DLEQ proof for proofs -#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] -pub struct ProofDleq { - /// e value (hex-encoded SecretKey) - pub e: String, - /// s value (hex-encoded SecretKey) - pub s: String, - /// r value - blinding factor (hex-encoded SecretKey) - pub r: String, -} - -/// FFI-compatible DLEQ proof for blind signatures -#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] -pub struct BlindSignatureDleq { - /// e value (hex-encoded SecretKey) - pub e: String, - /// s value (hex-encoded SecretKey) - pub s: String, -} - -impl From for ProofDleq { - fn from(dleq: cdk::nuts::ProofDleq) -> Self { - Self { - e: dleq.e.to_secret_hex(), - s: dleq.s.to_secret_hex(), - r: dleq.r.to_secret_hex(), - } - } -} - -impl From for cdk::nuts::ProofDleq { - fn from(dleq: ProofDleq) -> Self { - Self { - e: cdk::nuts::SecretKey::from_hex(&dleq.e).expect("Invalid e hex"), - s: cdk::nuts::SecretKey::from_hex(&dleq.s).expect("Invalid s hex"), - r: cdk::nuts::SecretKey::from_hex(&dleq.r).expect("Invalid r hex"), - } - } -} - -impl From for BlindSignatureDleq { - fn from(dleq: cdk::nuts::BlindSignatureDleq) -> Self { - Self { - e: dleq.e.to_secret_hex(), - s: dleq.s.to_secret_hex(), - } - } -} - -impl From for cdk::nuts::BlindSignatureDleq { - fn from(dleq: BlindSignatureDleq) -> Self { - Self { - e: cdk::nuts::SecretKey::from_hex(&dleq.e).expect("Invalid e hex"), - s: cdk::nuts::SecretKey::from_hex(&dleq.s).expect("Invalid s hex"), - } - } -} - -/// Helper functions for Proofs -pub fn proofs_total_amount(proofs: &Proofs) -> Result { - let cdk_proofs: Vec = proofs.iter().map(|p| p.inner.clone()).collect(); - use cdk::nuts::ProofsMethods; - Ok(cdk_proofs.total_amount()?.into()) -} - -/// FFI-compatible MintQuote -#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] -pub struct MintQuote { - /// Quote ID - pub id: String, - /// Quote amount - pub amount: Option, - /// Currency unit - pub unit: CurrencyUnit, - /// Payment request - pub request: String, - /// Quote state - pub state: QuoteState, - /// Expiry timestamp - pub expiry: u64, - /// Mint URL - pub mint_url: MintUrl, - /// Amount issued - pub amount_issued: Amount, - /// Amount paid - pub amount_paid: Amount, - /// Payment method - pub payment_method: PaymentMethod, - /// Secret key (optional, hex-encoded) - pub secret_key: Option, -} - -impl From for MintQuote { - fn from(quote: cdk::wallet::MintQuote) -> Self { - Self { - id: quote.id.clone(), - amount: quote.amount.map(Into::into), - unit: quote.unit.clone().into(), - request: quote.request.clone(), - state: quote.state.into(), - expiry: quote.expiry, - mint_url: quote.mint_url.clone().into(), - amount_issued: quote.amount_issued.into(), - amount_paid: quote.amount_paid.into(), - payment_method: quote.payment_method.into(), - secret_key: quote.secret_key.map(|sk| sk.to_secret_hex()), - } - } -} - -impl TryFrom for cdk::wallet::MintQuote { - type Error = FfiError; - - fn try_from(quote: MintQuote) -> Result { - let secret_key = quote - .secret_key - .map(|hex| cdk::nuts::SecretKey::from_hex(&hex)) - .transpose() - .map_err(|e| FfiError::InvalidCryptographicKey { msg: e.to_string() })?; - - Ok(Self { - id: quote.id, - amount: quote.amount.map(Into::into), - unit: quote.unit.into(), - request: quote.request, - state: quote.state.into(), - expiry: quote.expiry, - mint_url: quote.mint_url.try_into()?, - amount_issued: quote.amount_issued.into(), - amount_paid: quote.amount_paid.into(), - payment_method: quote.payment_method.into(), - secret_key, - }) - } -} - -impl MintQuote { - /// Get total amount (amount + fees) - pub fn total_amount(&self) -> Amount { - if let Some(amount) = self.amount { - Amount::new(amount.value + self.amount_paid.value - self.amount_issued.value) - } else { - Amount::zero() - } - } - - /// Check if quote is expired - pub fn is_expired(&self, current_time: u64) -> bool { - current_time > self.expiry - } - - /// Get amount that can be minted - pub fn amount_mintable(&self) -> Amount { - Amount::new(self.amount_paid.value - self.amount_issued.value) - } - - /// Convert MintQuote to JSON string - pub fn to_json(&self) -> Result { - Ok(serde_json::to_string(self)?) - } -} - -/// Decode MintQuote from JSON string -#[uniffi::export] -pub fn decode_mint_quote(json: String) -> Result { - let quote: cdk::wallet::MintQuote = serde_json::from_str(&json)?; - Ok(quote.into()) -} - -/// Encode MintQuote to JSON string -#[uniffi::export] -pub fn encode_mint_quote(quote: MintQuote) -> Result { - Ok(serde_json::to_string("e)?) -} - -/// FFI-compatible MintQuoteBolt11Response -#[derive(Debug, uniffi::Object)] -pub struct MintQuoteBolt11Response { - /// Quote ID - pub quote: String, - /// Request string - pub request: String, - /// State of the quote - pub state: QuoteState, - /// Expiry timestamp (optional) - pub expiry: Option, - /// Amount (optional) - pub amount: Option, - /// Unit (optional) - pub unit: Option, - /// Pubkey (optional) - pub pubkey: Option, -} - -impl From> for MintQuoteBolt11Response { - fn from(response: cdk::nuts::MintQuoteBolt11Response) -> Self { - Self { - quote: response.quote, - request: response.request, - state: response.state.into(), - expiry: response.expiry, - amount: response.amount.map(Into::into), - unit: response.unit.map(Into::into), - pubkey: response.pubkey.map(|p| p.to_string()), - } - } -} - -#[uniffi::export] -impl MintQuoteBolt11Response { - /// Get quote ID - pub fn quote(&self) -> String { - self.quote.clone() - } - - /// Get request string - pub fn request(&self) -> String { - self.request.clone() - } - - /// Get state - pub fn state(&self) -> QuoteState { - self.state.clone() - } - - /// Get expiry - pub fn expiry(&self) -> Option { - self.expiry - } - - /// Get amount - pub fn amount(&self) -> Option { - self.amount - } - - /// Get unit - pub fn unit(&self) -> Option { - self.unit.clone() - } - - /// Get pubkey - pub fn pubkey(&self) -> Option { - self.pubkey.clone() - } -} - -/// FFI-compatible MeltQuoteBolt11Response -#[derive(Debug, uniffi::Object)] -pub struct MeltQuoteBolt11Response { - /// Quote ID - pub quote: String, - /// Amount - pub amount: Amount, - /// Fee reserve - pub fee_reserve: Amount, - /// State of the quote - pub state: QuoteState, - /// Expiry timestamp - pub expiry: u64, - /// Payment preimage (optional) - pub payment_preimage: Option, - /// Request string (optional) - pub request: Option, - /// Unit (optional) - pub unit: Option, -} - -impl From> for MeltQuoteBolt11Response { - fn from(response: cdk::nuts::MeltQuoteBolt11Response) -> Self { - Self { - quote: response.quote, - amount: response.amount.into(), - fee_reserve: response.fee_reserve.into(), - state: response.state.into(), - expiry: response.expiry, - payment_preimage: response.payment_preimage, - request: response.request, - unit: response.unit.map(Into::into), - } - } -} - -#[uniffi::export] -impl MeltQuoteBolt11Response { - /// Get quote ID - pub fn quote(&self) -> String { - self.quote.clone() - } - - /// Get amount - pub fn amount(&self) -> Amount { - self.amount - } - - /// Get fee reserve - pub fn fee_reserve(&self) -> Amount { - self.fee_reserve - } - - /// Get state - pub fn state(&self) -> QuoteState { - self.state.clone() - } - - /// Get expiry - pub fn expiry(&self) -> u64 { - self.expiry - } - - /// Get payment preimage - pub fn payment_preimage(&self) -> Option { - self.payment_preimage.clone() - } - - /// Get request - pub fn request(&self) -> Option { - self.request.clone() - } - - /// Get unit - pub fn unit(&self) -> Option { - self.unit.clone() - } -} - -/// FFI-compatible PaymentMethod -#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, uniffi::Enum)] -pub enum PaymentMethod { - /// Bolt11 payment type - Bolt11, - /// Bolt12 payment type - Bolt12, - /// Custom payment type - Custom { method: String }, -} - -impl From for PaymentMethod { - fn from(method: cdk::nuts::PaymentMethod) -> Self { - match method { - cdk::nuts::PaymentMethod::Bolt11 => Self::Bolt11, - cdk::nuts::PaymentMethod::Bolt12 => Self::Bolt12, - cdk::nuts::PaymentMethod::Custom(s) => Self::Custom { method: s }, - } - } -} - -impl From for cdk::nuts::PaymentMethod { - fn from(method: PaymentMethod) -> Self { - match method { - PaymentMethod::Bolt11 => Self::Bolt11, - PaymentMethod::Bolt12 => Self::Bolt12, - PaymentMethod::Custom { method } => Self::Custom(method), - } - } -} - -/// FFI-compatible MeltQuote -#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] -pub struct MeltQuote { - /// Quote ID - pub id: String, - /// Quote amount - pub amount: Amount, - /// Currency unit - pub unit: CurrencyUnit, - /// Payment request - pub request: String, - /// Fee reserve - pub fee_reserve: Amount, - /// Quote state - pub state: QuoteState, - /// Expiry timestamp - pub expiry: u64, - /// Payment preimage - pub payment_preimage: Option, - /// Payment method - pub payment_method: PaymentMethod, -} - -impl From for MeltQuote { - fn from(quote: cdk::wallet::MeltQuote) -> Self { - Self { - id: quote.id.clone(), - amount: quote.amount.into(), - unit: quote.unit.clone().into(), - request: quote.request.clone(), - fee_reserve: quote.fee_reserve.into(), - state: quote.state.into(), - expiry: quote.expiry, - payment_preimage: quote.payment_preimage.clone(), - payment_method: quote.payment_method.into(), - } - } -} - -impl TryFrom for cdk::wallet::MeltQuote { - type Error = FfiError; - - fn try_from(quote: MeltQuote) -> Result { - Ok(Self { - id: quote.id, - amount: quote.amount.into(), - unit: quote.unit.into(), - request: quote.request, - fee_reserve: quote.fee_reserve.into(), - state: quote.state.into(), - expiry: quote.expiry, - payment_preimage: quote.payment_preimage, - payment_method: quote.payment_method.into(), - }) - } -} - -impl MeltQuote { - /// Convert MeltQuote to JSON string - pub fn to_json(&self) -> Result { - Ok(serde_json::to_string(self)?) - } -} - -/// Decode MeltQuote from JSON string -#[uniffi::export] -pub fn decode_melt_quote(json: String) -> Result { - let quote: cdk::wallet::MeltQuote = serde_json::from_str(&json)?; - Ok(quote.into()) -} - -/// Encode MeltQuote to JSON string -#[uniffi::export] -pub fn encode_melt_quote(quote: MeltQuote) -> Result { - Ok(serde_json::to_string("e)?) -} - -/// FFI-compatible QuoteState -#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, uniffi::Enum)] -pub enum QuoteState { - Unpaid, - Paid, - Pending, - Issued, -} - -impl From for QuoteState { - fn from(state: cdk::nuts::nut05::QuoteState) -> Self { - match state { - cdk::nuts::nut05::QuoteState::Unpaid => QuoteState::Unpaid, - cdk::nuts::nut05::QuoteState::Paid => QuoteState::Paid, - cdk::nuts::nut05::QuoteState::Pending => QuoteState::Pending, - cdk::nuts::nut05::QuoteState::Unknown => QuoteState::Unpaid, - cdk::nuts::nut05::QuoteState::Failed => QuoteState::Unpaid, - } - } -} - -impl From for cdk::nuts::nut05::QuoteState { - fn from(state: QuoteState) -> Self { - match state { - QuoteState::Unpaid => cdk::nuts::nut05::QuoteState::Unpaid, - QuoteState::Paid => cdk::nuts::nut05::QuoteState::Paid, - QuoteState::Pending => cdk::nuts::nut05::QuoteState::Pending, - QuoteState::Issued => cdk::nuts::nut05::QuoteState::Paid, // Map issued to paid for melt quotes - } - } -} - -impl From for QuoteState { - fn from(state: cdk::nuts::MintQuoteState) -> Self { - match state { - cdk::nuts::MintQuoteState::Unpaid => QuoteState::Unpaid, - cdk::nuts::MintQuoteState::Paid => QuoteState::Paid, - cdk::nuts::MintQuoteState::Issued => QuoteState::Issued, - } - } -} - -impl From for cdk::nuts::MintQuoteState { - fn from(state: QuoteState) -> Self { - match state { - QuoteState::Unpaid => cdk::nuts::MintQuoteState::Unpaid, - QuoteState::Paid => cdk::nuts::MintQuoteState::Paid, - QuoteState::Issued => cdk::nuts::MintQuoteState::Issued, - QuoteState::Pending => cdk::nuts::MintQuoteState::Paid, // Map pending to paid - } - } -} - -// Note: MeltQuoteState is the same as nut05::QuoteState, so we don't need a separate impl - -/// FFI-compatible PreparedSend -#[derive(Debug, uniffi::Object)] -pub struct PreparedSend { - inner: Mutex>, - id: String, - amount: Amount, - proofs: Proofs, -} - -impl From for PreparedSend { - fn from(prepared: cdk::wallet::PreparedSend) -> Self { - let id = format!("{:?}", prepared); // Use debug format as ID - let amount = prepared.amount().into(); - let proofs = prepared - .proofs() - .iter() - .cloned() - .map(|p| std::sync::Arc::new(p.into())) - .collect(); - Self { - inner: Mutex::new(Some(prepared)), - id, - amount, - proofs, - } - } -} - -#[uniffi::export(async_runtime = "tokio")] -impl PreparedSend { - /// Get the prepared send ID - pub fn id(&self) -> String { - self.id.clone() - } - - /// Get the amount to send - pub fn amount(&self) -> Amount { - self.amount - } - - /// Get the proofs that will be used - pub fn proofs(&self) -> Proofs { - self.proofs.clone() - } - - /// Get the total fee for this send operation - pub fn fee(&self) -> Amount { - if let Ok(guard) = self.inner.lock() { - if let Some(ref inner) = *guard { - inner.fee().into() - } else { - Amount::new(0) - } - } else { - Amount::new(0) - } - } - - /// Confirm the prepared send and create a token - pub async fn confirm( - self: std::sync::Arc, - memo: Option, - ) -> Result { - let inner = { - if let Ok(mut guard) = self.inner.lock() { - guard.take() - } else { - return Err(FfiError::Generic { - msg: "Failed to acquire lock on PreparedSend".to_string(), - }); - } - }; - - if let Some(inner) = inner { - let send_memo = memo.map(|m| cdk::wallet::SendMemo::for_token(&m)); - let token = inner.confirm(send_memo).await?; - Ok(token.into()) - } else { - Err(FfiError::Generic { - msg: "PreparedSend has already been consumed or cancelled".to_string(), - }) - } - } - - /// Cancel the prepared send operation - pub async fn cancel(self: std::sync::Arc) -> Result<(), FfiError> { - let inner = { - if let Ok(mut guard) = self.inner.lock() { - guard.take() - } else { - return Err(FfiError::Generic { - msg: "Failed to acquire lock on PreparedSend".to_string(), - }); - } - }; - - if let Some(inner) = inner { - inner.cancel().await?; - Ok(()) - } else { - Err(FfiError::Generic { - msg: "PreparedSend has already been consumed or cancelled".to_string(), - }) - } - } -} - -/// FFI-compatible Melted result -#[derive(Debug, Clone, uniffi::Record)] -pub struct Melted { - pub state: QuoteState, - pub preimage: Option, - pub change: Option, - pub amount: Amount, - pub fee_paid: Amount, -} - -// MeltQuoteState is just an alias for nut05::QuoteState, so we don't need a separate implementation - -impl From for Melted { - fn from(melted: cdk::types::Melted) -> Self { - Self { - state: melted.state.into(), - preimage: melted.preimage, - change: melted.change.map(|proofs| { - proofs - .into_iter() - .map(|p| std::sync::Arc::new(p.into())) - .collect() - }), - amount: melted.amount.into(), - fee_paid: melted.fee_paid.into(), - } - } -} - -/// FFI-compatible MeltOptions -#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Enum)] -pub enum MeltOptions { - /// MPP (Multi-Part Payments) options - Mpp { amount: Amount }, - /// Amountless options - Amountless { amount_msat: Amount }, -} - -impl From for cdk::nuts::MeltOptions { - fn from(opts: MeltOptions) -> Self { - match opts { - MeltOptions::Mpp { amount } => { - let cdk_amount: cdk::Amount = amount.into(); - cdk::nuts::MeltOptions::new_mpp(cdk_amount) - } - MeltOptions::Amountless { amount_msat } => { - let cdk_amount: cdk::Amount = amount_msat.into(); - cdk::nuts::MeltOptions::new_amountless(cdk_amount) - } - } - } -} - -impl From for MeltOptions { - fn from(opts: cdk::nuts::MeltOptions) -> Self { - match opts { - cdk::nuts::MeltOptions::Mpp { mpp } => MeltOptions::Mpp { - amount: mpp.amount.into(), - }, - cdk::nuts::MeltOptions::Amountless { amountless } => MeltOptions::Amountless { - amount_msat: amountless.amount_msat.into(), - }, - } - } -} - -/// FFI-compatible MintVersion -#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] -pub struct MintVersion { - /// Mint Software name - pub name: String, - /// Mint Version - pub version: String, -} - -impl From for MintVersion { - fn from(version: cdk::nuts::MintVersion) -> Self { - Self { - name: version.name, - version: version.version, - } - } -} - -impl From for cdk::nuts::MintVersion { - fn from(version: MintVersion) -> Self { - Self { - name: version.name, - version: version.version, - } - } -} - -impl MintVersion { - /// Convert MintVersion to JSON string - pub fn to_json(&self) -> Result { - Ok(serde_json::to_string(self)?) - } -} - -/// Decode MintVersion from JSON string -#[uniffi::export] -pub fn decode_mint_version(json: String) -> Result { - Ok(serde_json::from_str(&json)?) -} - -/// Encode MintVersion to JSON string -#[uniffi::export] -pub fn encode_mint_version(version: MintVersion) -> Result { - Ok(serde_json::to_string(&version)?) -} - -/// FFI-compatible ContactInfo -#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] -pub struct ContactInfo { - /// Contact Method i.e. nostr - pub method: String, - /// Contact info i.e. npub... - pub info: String, -} - -impl From for ContactInfo { - fn from(contact: cdk::nuts::ContactInfo) -> Self { - Self { - method: contact.method, - info: contact.info, - } - } -} - -impl From for cdk::nuts::ContactInfo { - fn from(contact: ContactInfo) -> Self { - Self { - method: contact.method, - info: contact.info, - } - } -} - -impl ContactInfo { - /// Convert ContactInfo to JSON string - pub fn to_json(&self) -> Result { - Ok(serde_json::to_string(self)?) - } -} - -/// Decode ContactInfo from JSON string -#[uniffi::export] -pub fn decode_contact_info(json: String) -> Result { - Ok(serde_json::from_str(&json)?) -} - -/// Encode ContactInfo to JSON string -#[uniffi::export] -pub fn encode_contact_info(info: ContactInfo) -> Result { - Ok(serde_json::to_string(&info)?) -} - -/// FFI-compatible SupportedSettings -#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] -#[serde(transparent)] -pub struct SupportedSettings { - /// Setting supported - pub supported: bool, -} - -impl From for SupportedSettings { - fn from(settings: cdk::nuts::nut06::SupportedSettings) -> Self { - Self { - supported: settings.supported, - } - } -} - -impl From for cdk::nuts::nut06::SupportedSettings { - fn from(settings: SupportedSettings) -> Self { - Self { - supported: settings.supported, - } - } -} - -// ----------------------------- -// NUT-04/05 FFI Types -// ----------------------------- - -/// FFI-compatible MintMethodSettings (NUT-04) -#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] -pub struct MintMethodSettings { - pub method: PaymentMethod, - pub unit: CurrencyUnit, - pub min_amount: Option, - pub max_amount: Option, - /// For bolt11, whether mint supports setting invoice description - pub description: Option, -} - -impl From for MintMethodSettings { - fn from(s: cdk::nuts::nut04::MintMethodSettings) -> Self { - let description = match s.options { - Some(cdk::nuts::nut04::MintMethodOptions::Bolt11 { description }) => Some(description), - _ => None, - }; - Self { - method: s.method.into(), - unit: s.unit.into(), - min_amount: s.min_amount.map(Into::into), - max_amount: s.max_amount.map(Into::into), - description, - } - } -} - -impl TryFrom for cdk::nuts::nut04::MintMethodSettings { - type Error = FfiError; - - fn try_from(s: MintMethodSettings) -> Result { - let options = match (s.method.clone(), s.description) { - (PaymentMethod::Bolt11, Some(description)) => { - Some(cdk::nuts::nut04::MintMethodOptions::Bolt11 { description }) - } - _ => None, - }; - Ok(Self { - method: s.method.into(), - unit: s.unit.into(), - min_amount: s.min_amount.map(Into::into), - max_amount: s.max_amount.map(Into::into), - options, - }) - } -} - -/// FFI-compatible Nut04 Settings -#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] -pub struct Nut04Settings { - pub methods: Vec, - pub disabled: bool, -} - -impl From for Nut04Settings { - fn from(s: cdk::nuts::nut04::Settings) -> Self { - Self { - methods: s.methods.into_iter().map(Into::into).collect(), - disabled: s.disabled, - } - } -} - -impl TryFrom for cdk::nuts::nut04::Settings { - type Error = FfiError; - - fn try_from(s: Nut04Settings) -> Result { - Ok(Self { - methods: s - .methods - .into_iter() - .map(TryInto::try_into) - .collect::>()?, - disabled: s.disabled, - }) - } -} - -/// FFI-compatible MeltMethodSettings (NUT-05) -#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] -pub struct MeltMethodSettings { - pub method: PaymentMethod, - pub unit: CurrencyUnit, - pub min_amount: Option, - pub max_amount: Option, - /// For bolt11, whether mint supports amountless invoices - pub amountless: Option, -} - -impl From for MeltMethodSettings { - fn from(s: cdk::nuts::nut05::MeltMethodSettings) -> Self { - let amountless = match s.options { - Some(cdk::nuts::nut05::MeltMethodOptions::Bolt11 { amountless }) => Some(amountless), - _ => None, - }; - Self { - method: s.method.into(), - unit: s.unit.into(), - min_amount: s.min_amount.map(Into::into), - max_amount: s.max_amount.map(Into::into), - amountless, - } - } -} - -impl TryFrom for cdk::nuts::nut05::MeltMethodSettings { - type Error = FfiError; - - fn try_from(s: MeltMethodSettings) -> Result { - let options = match (s.method.clone(), s.amountless) { - (PaymentMethod::Bolt11, Some(amountless)) => { - Some(cdk::nuts::nut05::MeltMethodOptions::Bolt11 { amountless }) - } - _ => None, - }; - Ok(Self { - method: s.method.into(), - unit: s.unit.into(), - min_amount: s.min_amount.map(Into::into), - max_amount: s.max_amount.map(Into::into), - options, - }) - } -} - -/// FFI-compatible Nut05 Settings -#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] -pub struct Nut05Settings { - pub methods: Vec, - pub disabled: bool, -} - -impl From for Nut05Settings { - fn from(s: cdk::nuts::nut05::Settings) -> Self { - Self { - methods: s.methods.into_iter().map(Into::into).collect(), - disabled: s.disabled, - } - } -} - -impl TryFrom for cdk::nuts::nut05::Settings { - type Error = FfiError; - - fn try_from(s: Nut05Settings) -> Result { - Ok(Self { - methods: s - .methods - .into_iter() - .map(TryInto::try_into) - .collect::>()?, - disabled: s.disabled, - }) - } -} - -/// FFI-compatible ProtectedEndpoint (for auth nuts) -#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] -pub struct ProtectedEndpoint { - /// HTTP method (GET, POST, etc.) - pub method: String, - /// Endpoint path - pub path: String, -} - -/// FFI-compatible ClearAuthSettings (NUT-21) -#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] -pub struct ClearAuthSettings { - /// OpenID Connect discovery URL - pub openid_discovery: String, - /// OAuth 2.0 client ID - pub client_id: String, - /// Protected endpoints requiring clear authentication - pub protected_endpoints: Vec, -} - -/// FFI-compatible BlindAuthSettings (NUT-22) -#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] -pub struct BlindAuthSettings { - /// Maximum number of blind auth tokens that can be minted per request - pub bat_max_mint: u64, - /// Protected endpoints requiring blind authentication - pub protected_endpoints: Vec, -} - -impl From for ClearAuthSettings { - fn from(settings: cdk::nuts::ClearAuthSettings) -> Self { - Self { - openid_discovery: settings.openid_discovery, - client_id: settings.client_id, - protected_endpoints: settings - .protected_endpoints - .into_iter() - .map(Into::into) - .collect(), - } - } -} - -impl TryFrom for cdk::nuts::ClearAuthSettings { - type Error = FfiError; - - fn try_from(settings: ClearAuthSettings) -> Result { - Ok(Self { - openid_discovery: settings.openid_discovery, - client_id: settings.client_id, - protected_endpoints: settings - .protected_endpoints - .into_iter() - .map(|e| e.try_into()) - .collect::, _>>()?, - }) - } -} - -impl From for BlindAuthSettings { - fn from(settings: cdk::nuts::BlindAuthSettings) -> Self { - Self { - bat_max_mint: settings.bat_max_mint, - protected_endpoints: settings - .protected_endpoints - .into_iter() - .map(Into::into) - .collect(), - } - } -} - -impl TryFrom for cdk::nuts::BlindAuthSettings { - type Error = FfiError; - - fn try_from(settings: BlindAuthSettings) -> Result { - Ok(Self { - bat_max_mint: settings.bat_max_mint, - protected_endpoints: settings - .protected_endpoints - .into_iter() - .map(|e| e.try_into()) - .collect::, _>>()?, - }) - } -} - -impl From for ProtectedEndpoint { - fn from(endpoint: cdk::nuts::ProtectedEndpoint) -> Self { - Self { - method: match endpoint.method { - cdk::nuts::Method::Get => "GET".to_string(), - cdk::nuts::Method::Post => "POST".to_string(), - }, - path: endpoint.path.to_string(), - } - } -} - -impl TryFrom for cdk::nuts::ProtectedEndpoint { - type Error = FfiError; - - fn try_from(endpoint: ProtectedEndpoint) -> Result { - let method = match endpoint.method.as_str() { - "GET" => cdk::nuts::Method::Get, - "POST" => cdk::nuts::Method::Post, - _ => { - return Err(FfiError::Generic { - msg: format!( - "Invalid HTTP method: {}. Only GET and POST are supported", - endpoint.method - ), - }) - } - }; - - // Convert path string to RoutePath by matching against known paths - let route_path = match endpoint.path.as_str() { - "/v1/mint/quote/bolt11" => cdk::nuts::RoutePath::MintQuoteBolt11, - "/v1/mint/bolt11" => cdk::nuts::RoutePath::MintBolt11, - "/v1/melt/quote/bolt11" => cdk::nuts::RoutePath::MeltQuoteBolt11, - "/v1/melt/bolt11" => cdk::nuts::RoutePath::MeltBolt11, - "/v1/swap" => cdk::nuts::RoutePath::Swap, - "/v1/checkstate" => cdk::nuts::RoutePath::Checkstate, - "/v1/restore" => cdk::nuts::RoutePath::Restore, - "/v1/auth/blind/mint" => cdk::nuts::RoutePath::MintBlindAuth, - "/v1/mint/quote/bolt12" => cdk::nuts::RoutePath::MintQuoteBolt12, - "/v1/mint/bolt12" => cdk::nuts::RoutePath::MintBolt12, - "/v1/melt/quote/bolt12" => cdk::nuts::RoutePath::MeltQuoteBolt12, - "/v1/melt/bolt12" => cdk::nuts::RoutePath::MeltBolt12, - _ => { - return Err(FfiError::Generic { - msg: format!("Unknown route path: {}", endpoint.path), - }) - } - }; - - Ok(cdk::nuts::ProtectedEndpoint::new(method, route_path)) - } -} - -/// FFI-compatible Nuts settings (extended to include NUT-04 and NUT-05 settings) -#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] -pub struct Nuts { - /// NUT04 Settings - pub nut04: Nut04Settings, - /// NUT05 Settings - pub nut05: Nut05Settings, - /// NUT07 Settings - Token state check - pub nut07_supported: bool, - /// NUT08 Settings - Lightning fee return - pub nut08_supported: bool, - /// NUT09 Settings - Restore signature - pub nut09_supported: bool, - /// NUT10 Settings - Spending conditions - pub nut10_supported: bool, - /// NUT11 Settings - Pay to Public Key Hash - pub nut11_supported: bool, - /// NUT12 Settings - DLEQ proofs - pub nut12_supported: bool, - /// NUT14 Settings - Hashed Time Locked Contracts - pub nut14_supported: bool, - /// NUT20 Settings - Web sockets - pub nut20_supported: bool, - /// NUT21 Settings - Clear authentication - pub nut21: Option, - /// NUT22 Settings - Blind authentication - pub nut22: Option, - /// Supported currency units for minting - pub mint_units: Vec, - /// Supported currency units for melting - pub melt_units: Vec, -} - -impl From for Nuts { - fn from(nuts: cdk::nuts::Nuts) -> Self { - let mint_units = nuts - .supported_mint_units() - .into_iter() - .map(|u| u.clone().into()) - .collect(); - let melt_units = nuts - .supported_melt_units() - .into_iter() - .map(|u| u.clone().into()) - .collect(); - - Self { - nut04: nuts.nut04.clone().into(), - nut05: nuts.nut05.clone().into(), - nut07_supported: nuts.nut07.supported, - nut08_supported: nuts.nut08.supported, - nut09_supported: nuts.nut09.supported, - nut10_supported: nuts.nut10.supported, - nut11_supported: nuts.nut11.supported, - nut12_supported: nuts.nut12.supported, - nut14_supported: nuts.nut14.supported, - nut20_supported: nuts.nut20.supported, - nut21: nuts.nut21.map(Into::into), - nut22: nuts.nut22.map(Into::into), - mint_units, - melt_units, - } - } -} - -impl TryFrom for cdk::nuts::Nuts { - type Error = FfiError; - - fn try_from(n: Nuts) -> Result { - Ok(Self { - nut04: n.nut04.try_into()?, - nut05: n.nut05.try_into()?, - nut07: cdk::nuts::nut06::SupportedSettings { - supported: n.nut07_supported, - }, - nut08: cdk::nuts::nut06::SupportedSettings { - supported: n.nut08_supported, - }, - nut09: cdk::nuts::nut06::SupportedSettings { - supported: n.nut09_supported, - }, - nut10: cdk::nuts::nut06::SupportedSettings { - supported: n.nut10_supported, - }, - nut11: cdk::nuts::nut06::SupportedSettings { - supported: n.nut11_supported, - }, - nut12: cdk::nuts::nut06::SupportedSettings { - supported: n.nut12_supported, - }, - nut14: cdk::nuts::nut06::SupportedSettings { - supported: n.nut14_supported, - }, - nut15: Default::default(), - nut17: Default::default(), - nut19: Default::default(), - nut20: cdk::nuts::nut06::SupportedSettings { - supported: n.nut20_supported, - }, - nut21: n.nut21.map(|s| s.try_into()).transpose()?, - nut22: n.nut22.map(|s| s.try_into()).transpose()?, - }) - } -} - -impl Nuts { - /// Convert Nuts to JSON string - pub fn to_json(&self) -> Result { - Ok(serde_json::to_string(self)?) - } -} - -/// Decode Nuts from JSON string -#[uniffi::export] -pub fn decode_nuts(json: String) -> Result { - Ok(serde_json::from_str(&json)?) -} - -/// Encode Nuts to JSON string -#[uniffi::export] -pub fn encode_nuts(nuts: Nuts) -> Result { - Ok(serde_json::to_string(&nuts)?) -} - -/// FFI-compatible MintInfo -#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] -pub struct MintInfo { - /// name of the mint and should be recognizable - pub name: Option, - /// hex pubkey of the mint - pub pubkey: Option, - /// implementation name and the version running - pub version: Option, - /// short description of the mint - pub description: Option, - /// long description - pub description_long: Option, - /// Contact info - pub contact: Option>, - /// shows which NUTs the mint supports - pub nuts: Nuts, - /// Mint's icon URL - pub icon_url: Option, - /// Mint's endpoint URLs - pub urls: Option>, - /// message of the day that the wallet must display to the user - pub motd: Option, - /// server unix timestamp - pub time: Option, - /// terms of url service of the mint - pub tos_url: Option, -} - -impl From for MintInfo { - fn from(info: cdk::nuts::MintInfo) -> Self { - Self { - name: info.name, - pubkey: info.pubkey.map(|p| p.to_string()), - version: info.version.map(Into::into), - description: info.description, - description_long: info.description_long, - contact: info - .contact - .map(|contacts| contacts.into_iter().map(Into::into).collect()), - nuts: info.nuts.into(), - icon_url: info.icon_url, - urls: info.urls, - motd: info.motd, - time: info.time, - tos_url: info.tos_url, - } - } -} - -impl From for cdk::nuts::MintInfo { - fn from(info: MintInfo) -> Self { - // Convert FFI Nuts back to cdk::nuts::Nuts (best-effort) - let nuts_cdk: cdk::nuts::Nuts = info.nuts.clone().try_into().unwrap_or_default(); - Self { - name: info.name, - pubkey: info.pubkey.and_then(|p| p.parse().ok()), - version: info.version.map(Into::into), - description: info.description, - description_long: info.description_long, - contact: info - .contact - .map(|contacts| contacts.into_iter().map(Into::into).collect()), - nuts: nuts_cdk, - icon_url: info.icon_url, - urls: info.urls, - motd: info.motd, - time: info.time, - tos_url: info.tos_url, - } - } -} - -impl MintInfo { - /// Convert MintInfo to JSON string - pub fn to_json(&self) -> Result { - Ok(serde_json::to_string(self)?) - } -} - -/// Decode MintInfo from JSON string -#[uniffi::export] -pub fn decode_mint_info(json: String) -> Result { - Ok(serde_json::from_str(&json)?) -} - -/// Encode MintInfo to JSON string -#[uniffi::export] -pub fn encode_mint_info(info: MintInfo) -> Result { - Ok(serde_json::to_string(&info)?) -} - -/// FFI-compatible Conditions (for spending conditions) -#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] -pub struct Conditions { - /// Unix locktime after which refund keys can be used - pub locktime: Option, - /// Additional Public keys (as hex strings) - pub pubkeys: Vec, - /// Refund keys (as hex strings) - pub refund_keys: Vec, - /// Number of signatures required (default 1) - pub num_sigs: Option, - /// Signature flag (0 = SigInputs, 1 = SigAll) - pub sig_flag: u8, - /// Number of refund signatures required (default 1) - pub num_sigs_refund: Option, -} - -impl From for Conditions { - fn from(conditions: cdk::nuts::nut11::Conditions) -> Self { - Self { - locktime: conditions.locktime, - pubkeys: conditions - .pubkeys - .unwrap_or_default() - .into_iter() - .map(|p| p.to_string()) - .collect(), - refund_keys: conditions - .refund_keys - .unwrap_or_default() - .into_iter() - .map(|p| p.to_string()) - .collect(), - num_sigs: conditions.num_sigs, - sig_flag: match conditions.sig_flag { - cdk::nuts::nut11::SigFlag::SigInputs => 0, - cdk::nuts::nut11::SigFlag::SigAll => 1, - }, - num_sigs_refund: conditions.num_sigs_refund, - } - } -} - -impl TryFrom for cdk::nuts::nut11::Conditions { - type Error = FfiError; - - fn try_from(conditions: Conditions) -> Result { - let pubkeys = if conditions.pubkeys.is_empty() { - None - } else { - Some( - conditions - .pubkeys - .into_iter() - .map(|s| { - s.parse().map_err(|e| FfiError::InvalidCryptographicKey { - msg: format!("Invalid pubkey: {}", e), - }) - }) - .collect::, _>>()?, - ) - }; - - let refund_keys = if conditions.refund_keys.is_empty() { - None - } else { - Some( - conditions - .refund_keys - .into_iter() - .map(|s| { - s.parse().map_err(|e| FfiError::InvalidCryptographicKey { - msg: format!("Invalid refund key: {}", e), - }) - }) - .collect::, _>>()?, - ) - }; - - let sig_flag = match conditions.sig_flag { - 0 => cdk::nuts::nut11::SigFlag::SigInputs, - 1 => cdk::nuts::nut11::SigFlag::SigAll, - _ => { - return Err(FfiError::Generic { - msg: "Invalid sig_flag value".to_string(), - }) - } - }; - - Ok(Self { - locktime: conditions.locktime, - pubkeys, - refund_keys, - num_sigs: conditions.num_sigs, - sig_flag, - num_sigs_refund: conditions.num_sigs_refund, - }) - } -} - -impl Conditions { - /// Convert Conditions to JSON string - pub fn to_json(&self) -> Result { - Ok(serde_json::to_string(self)?) - } -} - -/// Decode Conditions from JSON string -#[uniffi::export] -pub fn decode_conditions(json: String) -> Result { - Ok(serde_json::from_str(&json)?) -} - -/// Encode Conditions to JSON string -#[uniffi::export] -pub fn encode_conditions(conditions: Conditions) -> Result { - Ok(serde_json::to_string(&conditions)?) -} - -/// FFI-compatible Witness -#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Enum)] -pub enum Witness { - /// P2PK Witness - P2PK { - /// Signatures - signatures: Vec, - }, - /// HTLC Witness - HTLC { - /// Preimage - preimage: String, - /// Optional signatures - signatures: Option>, - }, -} - -impl From for Witness { - fn from(witness: cdk::nuts::Witness) -> Self { - match witness { - cdk::nuts::Witness::P2PKWitness(p2pk) => Self::P2PK { - signatures: p2pk.signatures, - }, - cdk::nuts::Witness::HTLCWitness(htlc) => Self::HTLC { - preimage: htlc.preimage, - signatures: htlc.signatures, - }, - } - } -} - -impl From for cdk::nuts::Witness { - fn from(witness: Witness) -> Self { - match witness { - Witness::P2PK { signatures } => { - Self::P2PKWitness(cdk::nuts::nut11::P2PKWitness { signatures }) - } - Witness::HTLC { - preimage, - signatures, - } => Self::HTLCWitness(cdk::nuts::nut14::HTLCWitness { - preimage, - signatures, - }), - } - } -} - -/// FFI-compatible SpendingConditions -#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Enum)] -pub enum SpendingConditions { - /// P2PK (Pay to Public Key) conditions - P2PK { - /// The public key (as hex string) - pubkey: String, - /// Additional conditions - conditions: Option, - }, - /// HTLC (Hash Time Locked Contract) conditions - HTLC { - /// Hash of the preimage (as hex string) - hash: String, - /// Additional conditions - conditions: Option, - }, -} - -impl From for SpendingConditions { - fn from(spending_conditions: cdk::nuts::SpendingConditions) -> Self { - match spending_conditions { - cdk::nuts::SpendingConditions::P2PKConditions { data, conditions } => Self::P2PK { - pubkey: data.to_string(), - conditions: conditions.map(Into::into), - }, - cdk::nuts::SpendingConditions::HTLCConditions { data, conditions } => Self::HTLC { - hash: data.to_string(), - conditions: conditions.map(Into::into), - }, - } - } -} - -/// FFI-compatible Transaction -#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] -pub struct Transaction { - /// Transaction ID - pub id: TransactionId, - /// Mint URL - pub mint_url: MintUrl, - /// Transaction direction - pub direction: TransactionDirection, - /// Amount - pub amount: Amount, - /// Fee - pub fee: Amount, - /// Currency Unit - pub unit: CurrencyUnit, - /// Proof Ys (Y values from proofs) - pub ys: Vec, - /// Unix timestamp - pub timestamp: u64, - /// Memo - pub memo: Option, - /// User-defined metadata - pub metadata: HashMap, - /// Quote ID if this is a mint or melt transaction - pub quote_id: Option, -} - -impl From for Transaction { - fn from(tx: cdk::wallet::types::Transaction) -> Self { - Self { - id: tx.id().into(), - mint_url: tx.mint_url.into(), - direction: tx.direction.into(), - amount: tx.amount.into(), - fee: tx.fee.into(), - unit: tx.unit.into(), - ys: tx.ys.into_iter().map(Into::into).collect(), - timestamp: tx.timestamp, - memo: tx.memo, - metadata: tx.metadata, - quote_id: tx.quote_id, - } - } -} - -/// Convert FFI Transaction to CDK Transaction -impl TryFrom for cdk::wallet::types::Transaction { - type Error = FfiError; - - fn try_from(tx: Transaction) -> Result { - let cdk_ys: Result, _> = - tx.ys.into_iter().map(|pk| pk.try_into()).collect(); - let cdk_ys = cdk_ys?; - - Ok(Self { - mint_url: tx.mint_url.try_into()?, - direction: tx.direction.into(), - amount: tx.amount.into(), - fee: tx.fee.into(), - unit: tx.unit.into(), - ys: cdk_ys, - timestamp: tx.timestamp, - memo: tx.memo, - metadata: tx.metadata, - quote_id: tx.quote_id, - }) - } -} - -impl Transaction { - /// Convert Transaction to JSON string - pub fn to_json(&self) -> Result { - Ok(serde_json::to_string(self)?) - } -} - -/// Decode Transaction from JSON string -#[uniffi::export] -pub fn decode_transaction(json: String) -> Result { - Ok(serde_json::from_str(&json)?) -} - -/// Encode Transaction to JSON string -#[uniffi::export] -pub fn encode_transaction(transaction: Transaction) -> Result { - Ok(serde_json::to_string(&transaction)?) -} - -/// FFI-compatible TransactionDirection -#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, uniffi::Enum)] -pub enum TransactionDirection { - /// Incoming transaction (i.e., receive or mint) - Incoming, - /// Outgoing transaction (i.e., send or melt) - Outgoing, -} - -impl From for TransactionDirection { - fn from(direction: cdk::wallet::types::TransactionDirection) -> Self { - match direction { - cdk::wallet::types::TransactionDirection::Incoming => TransactionDirection::Incoming, - cdk::wallet::types::TransactionDirection::Outgoing => TransactionDirection::Outgoing, - } - } -} - -impl From for cdk::wallet::types::TransactionDirection { - fn from(direction: TransactionDirection) -> Self { - match direction { - TransactionDirection::Incoming => cdk::wallet::types::TransactionDirection::Incoming, - TransactionDirection::Outgoing => cdk::wallet::types::TransactionDirection::Outgoing, - } - } -} - -/// FFI-compatible TransactionId -#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] -#[serde(transparent)] -pub struct TransactionId { - /// Hex-encoded transaction ID (64 characters) - pub hex: String, -} - -impl TransactionId { - /// Create a new TransactionId from hex string - pub fn from_hex(hex: String) -> Result { - // Validate hex string length (should be 64 characters for 32 bytes) - if hex.len() != 64 { - return Err(FfiError::InvalidHex { - msg: "Transaction ID hex must be exactly 64 characters (32 bytes)".to_string(), - }); - } - - // Validate hex format - if !hex.chars().all(|c| c.is_ascii_hexdigit()) { - return Err(FfiError::InvalidHex { - msg: "Transaction ID hex contains invalid characters".to_string(), - }); - } - - Ok(Self { hex }) - } - - /// Create from proofs - pub fn from_proofs(proofs: &Proofs) -> Result { - let cdk_proofs: Vec = proofs.iter().map(|p| p.inner.clone()).collect(); - let id = cdk::wallet::types::TransactionId::from_proofs(cdk_proofs)?; - Ok(Self { - hex: id.to_string(), - }) - } -} - -impl From for TransactionId { - fn from(id: cdk::wallet::types::TransactionId) -> Self { - Self { - hex: id.to_string(), - } - } -} - -impl TryFrom for cdk::wallet::types::TransactionId { - type Error = FfiError; - - fn try_from(id: TransactionId) -> Result { - cdk::wallet::types::TransactionId::from_hex(&id.hex) - .map_err(|e| FfiError::InvalidHex { msg: e.to_string() }) - } -} - -/// FFI-compatible AuthProof -#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] -pub struct AuthProof { - /// Keyset ID - pub keyset_id: String, - /// Secret message - pub secret: String, - /// Unblinded signature (C) - pub c: String, - /// Y value (hash_to_curve of secret) - pub y: String, -} - -impl From for AuthProof { - fn from(auth_proof: cdk::nuts::AuthProof) -> Self { - Self { - keyset_id: auth_proof.keyset_id.to_string(), - secret: auth_proof.secret.to_string(), - c: auth_proof.c.to_string(), - y: auth_proof - .y() - .map(|y| y.to_string()) - .unwrap_or_else(|_| "".to_string()), - } - } -} - -impl TryFrom for cdk::nuts::AuthProof { - type Error = FfiError; - - fn try_from(auth_proof: AuthProof) -> Result { - use std::str::FromStr; - Ok(Self { - keyset_id: cdk::nuts::Id::from_str(&auth_proof.keyset_id) - .map_err(|e| FfiError::Serialization { msg: e.to_string() })?, - secret: { - use std::str::FromStr; - cdk::secret::Secret::from_str(&auth_proof.secret) - .map_err(|e| FfiError::Serialization { msg: e.to_string() })? - }, - c: cdk::nuts::PublicKey::from_str(&auth_proof.c) - .map_err(|e| FfiError::InvalidCryptographicKey { msg: e.to_string() })?, - dleq: None, // FFI doesn't expose DLEQ proofs for simplicity - }) - } -} - -impl AuthProof { - /// Convert AuthProof to JSON string - pub fn to_json(&self) -> Result { - Ok(serde_json::to_string(self)?) - } -} - -/// Decode AuthProof from JSON string -#[uniffi::export] -pub fn decode_auth_proof(json: String) -> Result { - Ok(serde_json::from_str(&json)?) -} - -/// Encode AuthProof to JSON string -#[uniffi::export] -pub fn encode_auth_proof(proof: AuthProof) -> Result { - Ok(serde_json::to_string(&proof)?) -} - -impl TryFrom for cdk::nuts::SpendingConditions { - type Error = FfiError; - - fn try_from(spending_conditions: SpendingConditions) -> Result { - match spending_conditions { - SpendingConditions::P2PK { pubkey, conditions } => { - let pubkey = pubkey - .parse() - .map_err(|e| FfiError::InvalidCryptographicKey { - msg: format!("Invalid pubkey: {}", e), - })?; - let conditions = conditions.map(|c| c.try_into()).transpose()?; - Ok(Self::P2PKConditions { - data: pubkey, - conditions, - }) - } - SpendingConditions::HTLC { hash, conditions } => { - let hash = hash - .parse() - .map_err(|e| FfiError::InvalidCryptographicKey { - msg: format!("Invalid hash: {}", e), - })?; - let conditions = conditions.map(|c| c.try_into()).transpose()?; - Ok(Self::HTLCConditions { - data: hash, - conditions, - }) - } - } - } -} - -/// FFI-compatible SubscriptionKind -#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, uniffi::Enum)] -pub enum SubscriptionKind { - /// Bolt 11 Melt Quote - Bolt11MeltQuote, - /// Bolt 11 Mint Quote - Bolt11MintQuote, - /// Bolt 12 Mint Quote - Bolt12MintQuote, - /// Proof State - ProofState, -} - -impl From for cdk::nuts::nut17::Kind { - fn from(kind: SubscriptionKind) -> Self { - match kind { - SubscriptionKind::Bolt11MeltQuote => cdk::nuts::nut17::Kind::Bolt11MeltQuote, - SubscriptionKind::Bolt11MintQuote => cdk::nuts::nut17::Kind::Bolt11MintQuote, - SubscriptionKind::Bolt12MintQuote => cdk::nuts::nut17::Kind::Bolt12MintQuote, - SubscriptionKind::ProofState => cdk::nuts::nut17::Kind::ProofState, - } - } -} - -impl From for SubscriptionKind { - fn from(kind: cdk::nuts::nut17::Kind) -> Self { - match kind { - cdk::nuts::nut17::Kind::Bolt11MeltQuote => SubscriptionKind::Bolt11MeltQuote, - cdk::nuts::nut17::Kind::Bolt11MintQuote => SubscriptionKind::Bolt11MintQuote, - cdk::nuts::nut17::Kind::Bolt12MintQuote => SubscriptionKind::Bolt12MintQuote, - cdk::nuts::nut17::Kind::ProofState => SubscriptionKind::ProofState, - } - } -} - -/// FFI-compatible SubscribeParams -#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] -pub struct SubscribeParams { - /// Subscription kind - pub kind: SubscriptionKind, - /// Filters - pub filters: Vec, - /// Subscription ID (optional, will be generated if not provided) - pub id: Option, -} - -impl From for cdk::nuts::nut17::Params { - fn from(params: SubscribeParams) -> Self { - let sub_id = params - .id - .map(|id| SubId::from(id.as_str())) - .unwrap_or_else(|| { - // Generate a random ID - let uuid = uuid::Uuid::new_v4(); - SubId::from(uuid.to_string().as_str()) - }); - - cdk::nuts::nut17::Params { - kind: params.kind.into(), - filters: params.filters, - id: sub_id, - } - } -} - -impl SubscribeParams { - /// Convert SubscribeParams to JSON string - pub fn to_json(&self) -> Result { - Ok(serde_json::to_string(self)?) - } -} - -/// Decode SubscribeParams from JSON string -#[uniffi::export] -pub fn decode_subscribe_params(json: String) -> Result { - Ok(serde_json::from_str(&json)?) -} - -/// Encode SubscribeParams to JSON string -#[uniffi::export] -pub fn encode_subscribe_params(params: SubscribeParams) -> Result { - Ok(serde_json::to_string(¶ms)?) -} - -/// FFI-compatible ActiveSubscription -#[derive(uniffi::Object)] -pub struct ActiveSubscription { - inner: std::sync::Arc>, - pub sub_id: String, -} - -impl ActiveSubscription { - pub(crate) fn new( - inner: cdk::wallet::subscription::ActiveSubscription, - sub_id: String, - ) -> Self { - Self { - inner: std::sync::Arc::new(tokio::sync::Mutex::new(inner)), - sub_id, - } - } -} - -#[uniffi::export(async_runtime = "tokio")] -impl ActiveSubscription { - /// Get the subscription ID - pub fn id(&self) -> String { - self.sub_id.clone() - } - - /// Receive the next notification - pub async fn recv(&self) -> Result { - let mut guard = self.inner.lock().await; - guard - .recv() - .await - .ok_or(FfiError::Generic { - msg: "Subscription closed".to_string(), - }) - .map(Into::into) - } - - /// Try to receive a notification without blocking - pub async fn try_recv(&self) -> Result, FfiError> { - let mut guard = self.inner.lock().await; - guard - .try_recv() - .map(|opt| opt.map(Into::into)) - .map_err(|e| FfiError::Generic { - msg: format!("Failed to receive notification: {}", e), - }) - } -} - -/// FFI-compatible NotificationPayload -#[derive(Debug, Clone, uniffi::Enum)] -pub enum NotificationPayload { - /// Proof state update - ProofState { proof_states: Vec }, - /// Mint quote update - MintQuoteUpdate { - quote: std::sync::Arc, - }, - /// Melt quote update - MeltQuoteUpdate { - quote: std::sync::Arc, - }, -} - -impl From> for NotificationPayload { - fn from(payload: cdk::nuts::NotificationPayload) -> Self { - match payload { - cdk::nuts::NotificationPayload::ProofState(states) => NotificationPayload::ProofState { - proof_states: vec![states.into()], - }, - cdk::nuts::NotificationPayload::MintQuoteBolt11Response(quote_resp) => { - NotificationPayload::MintQuoteUpdate { - quote: std::sync::Arc::new(quote_resp.into()), - } - } - cdk::nuts::NotificationPayload::MeltQuoteBolt11Response(quote_resp) => { - NotificationPayload::MeltQuoteUpdate { - quote: std::sync::Arc::new(quote_resp.into()), - } - } - _ => { - // For now, handle other notification types as empty ProofState - NotificationPayload::ProofState { - proof_states: vec![], - } - } - } - } -} - -/// FFI-compatible ProofStateUpdate -#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] -pub struct ProofStateUpdate { - /// Y value (hash_to_curve of secret) - pub y: String, - /// Current state - pub state: ProofState, - /// Optional witness data - pub witness: Option, -} - -impl From for ProofStateUpdate { - fn from(proof_state: cdk::nuts::nut07::ProofState) -> Self { - Self { - y: proof_state.y.to_string(), - state: proof_state.state.into(), - witness: proof_state.witness.map(|w| format!("{:?}", w)), - } - } -} - -impl ProofStateUpdate { - /// Convert ProofStateUpdate to JSON string - pub fn to_json(&self) -> Result { - Ok(serde_json::to_string(self)?) - } -} - -/// Decode ProofStateUpdate from JSON string -#[uniffi::export] -pub fn decode_proof_state_update(json: String) -> Result { - Ok(serde_json::from_str(&json)?) -} - -/// Encode ProofStateUpdate to JSON string -#[uniffi::export] -pub fn encode_proof_state_update(update: ProofStateUpdate) -> Result { - Ok(serde_json::to_string(&update)?) -} - -/// FFI-compatible KeySetInfo -#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] -pub struct KeySetInfo { - pub id: String, - pub unit: CurrencyUnit, - pub active: bool, - /// Input fee per thousand (ppk) - pub input_fee_ppk: u64, -} - -impl From for KeySetInfo { - fn from(keyset: cdk::nuts::KeySetInfo) -> Self { - Self { - id: keyset.id.to_string(), - unit: keyset.unit.into(), - active: keyset.active, - input_fee_ppk: keyset.input_fee_ppk, - } - } -} - -impl From for cdk::nuts::KeySetInfo { - fn from(keyset: KeySetInfo) -> Self { - use std::str::FromStr; - Self { - id: cdk::nuts::Id::from_str(&keyset.id).unwrap(), - unit: keyset.unit.into(), - active: keyset.active, - final_expiry: None, - input_fee_ppk: keyset.input_fee_ppk, - } - } -} - -impl KeySetInfo { - /// Convert KeySetInfo to JSON string - pub fn to_json(&self) -> Result { - Ok(serde_json::to_string(self)?) - } -} - -/// Decode KeySetInfo from JSON string -#[uniffi::export] -pub fn decode_key_set_info(json: String) -> Result { - Ok(serde_json::from_str(&json)?) -} - -/// Encode KeySetInfo to JSON string -#[uniffi::export] -pub fn encode_key_set_info(info: KeySetInfo) -> Result { - Ok(serde_json::to_string(&info)?) -} - -/// FFI-compatible PublicKey -#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] -#[serde(transparent)] -pub struct PublicKey { - /// Hex-encoded public key - pub hex: String, -} - -impl From for PublicKey { - fn from(key: cdk::nuts::PublicKey) -> Self { - Self { - hex: key.to_string(), - } - } -} - -impl TryFrom for cdk::nuts::PublicKey { - type Error = FfiError; - - fn try_from(key: PublicKey) -> Result { - key.hex - .parse() - .map_err(|e| FfiError::InvalidCryptographicKey { - msg: format!("Invalid public key: {}", e), - }) - } -} - -/// FFI-compatible Keys (simplified - contains only essential info) -#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] -pub struct Keys { - /// Keyset ID - pub id: String, - /// Currency unit - pub unit: CurrencyUnit, - /// Map of amount to public key hex (simplified from BTreeMap) - pub keys: HashMap, -} - -impl From for Keys { - fn from(keys: cdk::nuts::Keys) -> Self { - // Keys doesn't have id and unit - we'll need to get these from context - // For now, use placeholder values - Self { - id: "unknown".to_string(), // This should come from KeySet - unit: CurrencyUnit::Sat, // This should come from KeySet - keys: keys - .keys() - .iter() - .map(|(amount, pubkey)| (u64::from(*amount), pubkey.to_string())) - .collect(), - } - } -} - -impl TryFrom for cdk::nuts::Keys { - type Error = FfiError; - - fn try_from(keys: Keys) -> Result { - use std::collections::BTreeMap; - use std::str::FromStr; - - // Convert the HashMap to BTreeMap with proper types - let mut keys_map = BTreeMap::new(); - for (amount_u64, pubkey_hex) in keys.keys { - let amount = cdk::Amount::from(amount_u64); - let pubkey = cdk::nuts::PublicKey::from_str(&pubkey_hex) - .map_err(|e| FfiError::InvalidCryptographicKey { msg: e.to_string() })?; - keys_map.insert(amount, pubkey); - } - - Ok(cdk::nuts::Keys::new(keys_map)) - } -} - -impl Keys { - /// Convert Keys to JSON string - pub fn to_json(&self) -> Result { - Ok(serde_json::to_string(self)?) - } -} - -/// Decode Keys from JSON string -#[uniffi::export] -pub fn decode_keys(json: String) -> Result { - Ok(serde_json::from_str(&json)?) -} - -/// Encode Keys to JSON string -#[uniffi::export] -pub fn encode_keys(keys: Keys) -> Result { - Ok(serde_json::to_string(&keys)?) -} - -/// FFI-compatible KeySet -#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] -pub struct KeySet { - /// Keyset ID - pub id: String, - /// Currency unit - pub unit: CurrencyUnit, - /// The keys (map of amount to public key hex) - pub keys: HashMap, - /// Optional expiry timestamp - pub final_expiry: Option, -} - -impl From for KeySet { - fn from(keyset: cdk::nuts::KeySet) -> Self { - Self { - id: keyset.id.to_string(), - unit: keyset.unit.into(), - keys: keyset - .keys - .keys() - .iter() - .map(|(amount, pubkey)| (u64::from(*amount), pubkey.to_string())) - .collect(), - final_expiry: keyset.final_expiry, - } - } -} - -impl TryFrom for cdk::nuts::KeySet { - type Error = FfiError; - - fn try_from(keyset: KeySet) -> Result { - use std::collections::BTreeMap; - use std::str::FromStr; - - // Convert id - let id = cdk::nuts::Id::from_str(&keyset.id) - .map_err(|e| FfiError::Serialization { msg: e.to_string() })?; - - // Convert unit - let unit: cdk::nuts::CurrencyUnit = keyset.unit.into(); - - // Convert keys - let mut keys_map = BTreeMap::new(); - for (amount_u64, pubkey_hex) in keyset.keys { - let amount = cdk::Amount::from(amount_u64); - let pubkey = cdk::nuts::PublicKey::from_str(&pubkey_hex) - .map_err(|e| FfiError::InvalidCryptographicKey { msg: e.to_string() })?; - keys_map.insert(amount, pubkey); - } - let keys = cdk::nuts::Keys::new(keys_map); - - Ok(cdk::nuts::KeySet { - id, - unit, - keys, - final_expiry: keyset.final_expiry, - }) - } -} - -impl KeySet { - /// Convert KeySet to JSON string - pub fn to_json(&self) -> Result { - Ok(serde_json::to_string(self)?) - } -} - -/// Decode KeySet from JSON string -#[uniffi::export] -pub fn decode_key_set(json: String) -> Result { - Ok(serde_json::from_str(&json)?) -} - -/// Encode KeySet to JSON string -#[uniffi::export] -pub fn encode_key_set(keyset: KeySet) -> Result { - Ok(serde_json::to_string(&keyset)?) -} - -/// FFI-compatible ProofInfo -#[derive(Debug, Clone, uniffi::Record)] -pub struct ProofInfo { - /// Proof - pub proof: std::sync::Arc, - /// Y value (hash_to_curve of secret) - pub y: PublicKey, - /// Mint URL - pub mint_url: MintUrl, - /// Proof state - pub state: ProofState, - /// Proof Spending Conditions - pub spending_condition: Option, - /// Currency unit - pub unit: CurrencyUnit, -} - -impl From for ProofInfo { - fn from(info: cdk::types::ProofInfo) -> Self { - Self { - proof: std::sync::Arc::new(info.proof.into()), - y: info.y.into(), - mint_url: info.mint_url.into(), - state: info.state.into(), - spending_condition: info.spending_condition.map(Into::into), - unit: info.unit.into(), - } - } -} - -/// Decode ProofInfo from JSON string -#[uniffi::export] -pub fn decode_proof_info(json: String) -> Result { - let info: cdk::types::ProofInfo = serde_json::from_str(&json)?; - Ok(info.into()) -} - -/// Encode ProofInfo to JSON string -#[uniffi::export] -pub fn encode_proof_info(info: ProofInfo) -> Result { - // Convert to cdk::types::ProofInfo for serialization - let cdk_info = cdk::types::ProofInfo { - proof: info.proof.inner.clone(), - y: info.y.try_into()?, - mint_url: info.mint_url.try_into()?, - state: info.state.into(), - spending_condition: info.spending_condition.and_then(|c| c.try_into().ok()), - unit: info.unit.into(), - }; - Ok(serde_json::to_string(&cdk_info)?) -} - -// State enum removed - using ProofState instead - -/// FFI-compatible Id (for keyset IDs) -#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] -#[serde(transparent)] -pub struct Id { - pub hex: String, -} - -impl From for Id { - fn from(id: cdk::nuts::Id) -> Self { - Self { - hex: id.to_string(), - } - } -} - -impl From for cdk::nuts::Id { - fn from(id: Id) -> Self { - use std::str::FromStr; - Self::from_str(&id.hex).unwrap() - } -} diff --git a/crates/cdk-ffi/src/types/amount.rs b/crates/cdk-ffi/src/types/amount.rs new file mode 100644 index 000000000..d0864d574 --- /dev/null +++ b/crates/cdk-ffi/src/types/amount.rs @@ -0,0 +1,166 @@ +//! Amount and currency related types + +use cdk::nuts::CurrencyUnit as CdkCurrencyUnit; +use cdk::Amount as CdkAmount; +use serde::{Deserialize, Serialize}; + +use crate::error::FfiError; + +/// FFI-compatible Amount type +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, uniffi::Record)] +#[serde(transparent)] +pub struct Amount { + pub value: u64, +} + +impl Amount { + pub fn new(value: u64) -> Self { + Self { value } + } + + pub fn zero() -> Self { + Self { value: 0 } + } + + pub fn is_zero(&self) -> bool { + self.value == 0 + } + + pub fn convert_unit( + &self, + current_unit: CurrencyUnit, + target_unit: CurrencyUnit, + ) -> Result { + Ok(CdkAmount::from(self.value) + .convert_unit(¤t_unit.into(), &target_unit.into()) + .map(Into::into)?) + } + + pub fn add(&self, other: Amount) -> Result { + let self_amount = CdkAmount::from(self.value); + let other_amount = CdkAmount::from(other.value); + self_amount + .checked_add(other_amount) + .map(Into::into) + .ok_or(FfiError::AmountOverflow) + } + + pub fn subtract(&self, other: Amount) -> Result { + let self_amount = CdkAmount::from(self.value); + let other_amount = CdkAmount::from(other.value); + self_amount + .checked_sub(other_amount) + .map(Into::into) + .ok_or(FfiError::AmountOverflow) + } + + pub fn multiply(&self, factor: u64) -> Result { + let self_amount = CdkAmount::from(self.value); + let factor_amount = CdkAmount::from(factor); + self_amount + .checked_mul(factor_amount) + .map(Into::into) + .ok_or(FfiError::AmountOverflow) + } + + pub fn divide(&self, divisor: u64) -> Result { + if divisor == 0 { + return Err(FfiError::DivisionByZero); + } + let self_amount = CdkAmount::from(self.value); + let divisor_amount = CdkAmount::from(divisor); + self_amount + .checked_div(divisor_amount) + .map(Into::into) + .ok_or(FfiError::AmountOverflow) + } +} + +impl From for Amount { + fn from(amount: CdkAmount) -> Self { + Self { + value: u64::from(amount), + } + } +} + +impl From for CdkAmount { + fn from(amount: Amount) -> Self { + CdkAmount::from(amount.value) + } +} + +/// FFI-compatible Currency Unit +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, uniffi::Enum)] +pub enum CurrencyUnit { + Sat, + Msat, + Usd, + Eur, + Auth, + Custom { unit: String }, +} + +impl From for CurrencyUnit { + fn from(unit: CdkCurrencyUnit) -> Self { + match unit { + CdkCurrencyUnit::Sat => CurrencyUnit::Sat, + CdkCurrencyUnit::Msat => CurrencyUnit::Msat, + CdkCurrencyUnit::Usd => CurrencyUnit::Usd, + CdkCurrencyUnit::Eur => CurrencyUnit::Eur, + CdkCurrencyUnit::Auth => CurrencyUnit::Auth, + CdkCurrencyUnit::Custom(s) => CurrencyUnit::Custom { unit: s }, + _ => CurrencyUnit::Sat, // Default for unknown units + } + } +} + +impl From for CdkCurrencyUnit { + fn from(unit: CurrencyUnit) -> Self { + match unit { + CurrencyUnit::Sat => CdkCurrencyUnit::Sat, + CurrencyUnit::Msat => CdkCurrencyUnit::Msat, + CurrencyUnit::Usd => CdkCurrencyUnit::Usd, + CurrencyUnit::Eur => CdkCurrencyUnit::Eur, + CurrencyUnit::Auth => CdkCurrencyUnit::Auth, + CurrencyUnit::Custom { unit } => CdkCurrencyUnit::Custom(unit), + } + } +} + +/// FFI-compatible SplitTarget +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Enum)] +pub enum SplitTarget { + /// Default target; least amount of proofs + None, + /// Target amount for wallet to have most proofs that add up to value + Value { amount: Amount }, + /// Specific amounts to split into (must equal amount being split) + Values { amounts: Vec }, +} + +impl From for cdk::amount::SplitTarget { + fn from(target: SplitTarget) -> Self { + match target { + SplitTarget::None => cdk::amount::SplitTarget::None, + SplitTarget::Value { amount } => cdk::amount::SplitTarget::Value(amount.into()), + SplitTarget::Values { amounts } => { + cdk::amount::SplitTarget::Values(amounts.into_iter().map(Into::into).collect()) + } + } + } +} + +impl From for SplitTarget { + fn from(target: cdk::amount::SplitTarget) -> Self { + match target { + cdk::amount::SplitTarget::None => SplitTarget::None, + cdk::amount::SplitTarget::Value(amount) => SplitTarget::Value { + amount: amount.into(), + }, + cdk::amount::SplitTarget::Values(amounts) => SplitTarget::Values { + amounts: amounts.into_iter().map(Into::into).collect(), + }, + } + } +} diff --git a/crates/cdk-ffi/src/types/keys.rs b/crates/cdk-ffi/src/types/keys.rs new file mode 100644 index 000000000..57ef47617 --- /dev/null +++ b/crates/cdk-ffi/src/types/keys.rs @@ -0,0 +1,258 @@ +//! Key-related FFI types + +use std::collections::HashMap; + +use serde::{Deserialize, Serialize}; + +use super::amount::CurrencyUnit; +use crate::error::FfiError; + +/// FFI-compatible KeySetInfo +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct KeySetInfo { + pub id: String, + pub unit: CurrencyUnit, + pub active: bool, + /// Input fee per thousand (ppk) + pub input_fee_ppk: u64, +} + +impl From for KeySetInfo { + fn from(keyset: cdk::nuts::KeySetInfo) -> Self { + Self { + id: keyset.id.to_string(), + unit: keyset.unit.into(), + active: keyset.active, + input_fee_ppk: keyset.input_fee_ppk, + } + } +} + +impl From for cdk::nuts::KeySetInfo { + fn from(keyset: KeySetInfo) -> Self { + use std::str::FromStr; + Self { + id: cdk::nuts::Id::from_str(&keyset.id).unwrap(), + unit: keyset.unit.into(), + active: keyset.active, + final_expiry: None, + input_fee_ppk: keyset.input_fee_ppk, + } + } +} + +impl KeySetInfo { + /// Convert KeySetInfo to JSON string + pub fn to_json(&self) -> Result { + Ok(serde_json::to_string(self)?) + } +} + +/// Decode KeySetInfo from JSON string +#[uniffi::export] +pub fn decode_key_set_info(json: String) -> Result { + Ok(serde_json::from_str(&json)?) +} + +/// Encode KeySetInfo to JSON string +#[uniffi::export] +pub fn encode_key_set_info(info: KeySetInfo) -> Result { + Ok(serde_json::to_string(&info)?) +} + +/// FFI-compatible PublicKey +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +#[serde(transparent)] +pub struct PublicKey { + /// Hex-encoded public key + pub hex: String, +} + +impl From for PublicKey { + fn from(key: cdk::nuts::PublicKey) -> Self { + Self { + hex: key.to_string(), + } + } +} + +impl TryFrom for cdk::nuts::PublicKey { + type Error = FfiError; + + fn try_from(key: PublicKey) -> Result { + key.hex + .parse() + .map_err(|e| FfiError::InvalidCryptographicKey { + msg: format!("Invalid public key: {}", e), + }) + } +} + +/// FFI-compatible Keys (simplified - contains only essential info) +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct Keys { + /// Keyset ID + pub id: String, + /// Currency unit + pub unit: CurrencyUnit, + /// Map of amount to public key hex (simplified from BTreeMap) + pub keys: HashMap, +} + +impl From for Keys { + fn from(keys: cdk::nuts::Keys) -> Self { + // Keys doesn't have id and unit - we'll need to get these from context + // For now, use placeholder values + Self { + id: "unknown".to_string(), // This should come from KeySet + unit: CurrencyUnit::Sat, // This should come from KeySet + keys: keys + .keys() + .iter() + .map(|(amount, pubkey)| (u64::from(*amount), pubkey.to_string())) + .collect(), + } + } +} + +impl TryFrom for cdk::nuts::Keys { + type Error = FfiError; + + fn try_from(keys: Keys) -> Result { + use std::collections::BTreeMap; + use std::str::FromStr; + + // Convert the HashMap to BTreeMap with proper types + let mut keys_map = BTreeMap::new(); + for (amount_u64, pubkey_hex) in keys.keys { + let amount = cdk::Amount::from(amount_u64); + let pubkey = cdk::nuts::PublicKey::from_str(&pubkey_hex) + .map_err(|e| FfiError::InvalidCryptographicKey { msg: e.to_string() })?; + keys_map.insert(amount, pubkey); + } + + Ok(cdk::nuts::Keys::new(keys_map)) + } +} + +impl Keys { + /// Convert Keys to JSON string + pub fn to_json(&self) -> Result { + Ok(serde_json::to_string(self)?) + } +} + +/// Decode Keys from JSON string +#[uniffi::export] +pub fn decode_keys(json: String) -> Result { + Ok(serde_json::from_str(&json)?) +} + +/// Encode Keys to JSON string +#[uniffi::export] +pub fn encode_keys(keys: Keys) -> Result { + Ok(serde_json::to_string(&keys)?) +} + +/// FFI-compatible KeySet +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct KeySet { + /// Keyset ID + pub id: String, + /// Currency unit + pub unit: CurrencyUnit, + /// The keys (map of amount to public key hex) + pub keys: HashMap, + /// Optional expiry timestamp + pub final_expiry: Option, +} + +impl From for KeySet { + fn from(keyset: cdk::nuts::KeySet) -> Self { + Self { + id: keyset.id.to_string(), + unit: keyset.unit.into(), + keys: keyset + .keys + .keys() + .iter() + .map(|(amount, pubkey)| (u64::from(*amount), pubkey.to_string())) + .collect(), + final_expiry: keyset.final_expiry, + } + } +} + +impl TryFrom for cdk::nuts::KeySet { + type Error = FfiError; + + fn try_from(keyset: KeySet) -> Result { + use std::collections::BTreeMap; + use std::str::FromStr; + + // Convert id + let id = cdk::nuts::Id::from_str(&keyset.id) + .map_err(|e| FfiError::Serialization { msg: e.to_string() })?; + + // Convert unit + let unit: cdk::nuts::CurrencyUnit = keyset.unit.into(); + + // Convert keys + let mut keys_map = BTreeMap::new(); + for (amount_u64, pubkey_hex) in keyset.keys { + let amount = cdk::Amount::from(amount_u64); + let pubkey = cdk::nuts::PublicKey::from_str(&pubkey_hex) + .map_err(|e| FfiError::InvalidCryptographicKey { msg: e.to_string() })?; + keys_map.insert(amount, pubkey); + } + let keys = cdk::nuts::Keys::new(keys_map); + + Ok(cdk::nuts::KeySet { + id, + unit, + keys, + final_expiry: keyset.final_expiry, + }) + } +} + +impl KeySet { + /// Convert KeySet to JSON string + pub fn to_json(&self) -> Result { + Ok(serde_json::to_string(self)?) + } +} + +/// Decode KeySet from JSON string +#[uniffi::export] +pub fn decode_key_set(json: String) -> Result { + Ok(serde_json::from_str(&json)?) +} + +/// Encode KeySet to JSON string +#[uniffi::export] +pub fn encode_key_set(keyset: KeySet) -> Result { + Ok(serde_json::to_string(&keyset)?) +} + +/// FFI-compatible Id (for keyset IDs) +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +#[serde(transparent)] +pub struct Id { + pub hex: String, +} + +impl From for Id { + fn from(id: cdk::nuts::Id) -> Self { + Self { + hex: id.to_string(), + } + } +} + +impl From for cdk::nuts::Id { + fn from(id: Id) -> Self { + use std::str::FromStr; + Self::from_str(&id.hex).unwrap() + } +} diff --git a/crates/cdk-ffi/src/types/mint.rs b/crates/cdk-ffi/src/types/mint.rs new file mode 100644 index 000000000..06236cbe3 --- /dev/null +++ b/crates/cdk-ffi/src/types/mint.rs @@ -0,0 +1,675 @@ +//! Mint-related FFI types + +use std::str::FromStr; + +use serde::{Deserialize, Serialize}; + +use super::amount::{Amount, CurrencyUnit}; +use super::quote::PaymentMethod; +use crate::error::FfiError; + +/// FFI-compatible Mint URL +#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize, uniffi::Record)] +#[serde(transparent)] +pub struct MintUrl { + pub url: String, +} + +impl MintUrl { + pub fn new(url: String) -> Result { + // Validate URL format + url::Url::parse(&url).map_err(|e| FfiError::InvalidUrl { msg: e.to_string() })?; + + Ok(Self { url }) + } +} + +impl From for MintUrl { + fn from(mint_url: cdk::mint_url::MintUrl) -> Self { + Self { + url: mint_url.to_string(), + } + } +} + +impl TryFrom for cdk::mint_url::MintUrl { + type Error = FfiError; + + fn try_from(mint_url: MintUrl) -> Result { + cdk::mint_url::MintUrl::from_str(&mint_url.url) + .map_err(|e| FfiError::InvalidUrl { msg: e.to_string() }) + } +} + +/// FFI-compatible MintVersion +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct MintVersion { + /// Mint Software name + pub name: String, + /// Mint Version + pub version: String, +} + +impl From for MintVersion { + fn from(version: cdk::nuts::MintVersion) -> Self { + Self { + name: version.name, + version: version.version, + } + } +} + +impl From for cdk::nuts::MintVersion { + fn from(version: MintVersion) -> Self { + Self { + name: version.name, + version: version.version, + } + } +} + +impl MintVersion { + /// Convert MintVersion to JSON string + pub fn to_json(&self) -> Result { + Ok(serde_json::to_string(self)?) + } +} + +/// Decode MintVersion from JSON string +#[uniffi::export] +pub fn decode_mint_version(json: String) -> Result { + Ok(serde_json::from_str(&json)?) +} + +/// Encode MintVersion to JSON string +#[uniffi::export] +pub fn encode_mint_version(version: MintVersion) -> Result { + Ok(serde_json::to_string(&version)?) +} + +/// FFI-compatible ContactInfo +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct ContactInfo { + /// Contact Method i.e. nostr + pub method: String, + /// Contact info i.e. npub... + pub info: String, +} + +impl From for ContactInfo { + fn from(contact: cdk::nuts::ContactInfo) -> Self { + Self { + method: contact.method, + info: contact.info, + } + } +} + +impl From for cdk::nuts::ContactInfo { + fn from(contact: ContactInfo) -> Self { + Self { + method: contact.method, + info: contact.info, + } + } +} + +impl ContactInfo { + /// Convert ContactInfo to JSON string + pub fn to_json(&self) -> Result { + Ok(serde_json::to_string(self)?) + } +} + +/// Decode ContactInfo from JSON string +#[uniffi::export] +pub fn decode_contact_info(json: String) -> Result { + Ok(serde_json::from_str(&json)?) +} + +/// Encode ContactInfo to JSON string +#[uniffi::export] +pub fn encode_contact_info(info: ContactInfo) -> Result { + Ok(serde_json::to_string(&info)?) +} + +/// FFI-compatible SupportedSettings +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +#[serde(transparent)] +pub struct SupportedSettings { + /// Setting supported + pub supported: bool, +} + +impl From for SupportedSettings { + fn from(settings: cdk::nuts::nut06::SupportedSettings) -> Self { + Self { + supported: settings.supported, + } + } +} + +impl From for cdk::nuts::nut06::SupportedSettings { + fn from(settings: SupportedSettings) -> Self { + Self { + supported: settings.supported, + } + } +} + +// ----------------------------- +// NUT-04/05 FFI Types +// ----------------------------- + +/// FFI-compatible MintMethodSettings (NUT-04) +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct MintMethodSettings { + pub method: PaymentMethod, + pub unit: CurrencyUnit, + pub min_amount: Option, + pub max_amount: Option, + /// For bolt11, whether mint supports setting invoice description + pub description: Option, +} + +impl From for MintMethodSettings { + fn from(s: cdk::nuts::nut04::MintMethodSettings) -> Self { + let description = match s.options { + Some(cdk::nuts::nut04::MintMethodOptions::Bolt11 { description }) => Some(description), + _ => None, + }; + Self { + method: s.method.into(), + unit: s.unit.into(), + min_amount: s.min_amount.map(Into::into), + max_amount: s.max_amount.map(Into::into), + description, + } + } +} + +impl TryFrom for cdk::nuts::nut04::MintMethodSettings { + type Error = FfiError; + + fn try_from(s: MintMethodSettings) -> Result { + let options = match (s.method.clone(), s.description) { + (PaymentMethod::Bolt11, Some(description)) => { + Some(cdk::nuts::nut04::MintMethodOptions::Bolt11 { description }) + } + _ => None, + }; + Ok(Self { + method: s.method.into(), + unit: s.unit.into(), + min_amount: s.min_amount.map(Into::into), + max_amount: s.max_amount.map(Into::into), + options, + }) + } +} + +/// FFI-compatible Nut04 Settings +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct Nut04Settings { + pub methods: Vec, + pub disabled: bool, +} + +impl From for Nut04Settings { + fn from(s: cdk::nuts::nut04::Settings) -> Self { + Self { + methods: s.methods.into_iter().map(Into::into).collect(), + disabled: s.disabled, + } + } +} + +impl TryFrom for cdk::nuts::nut04::Settings { + type Error = FfiError; + + fn try_from(s: Nut04Settings) -> Result { + Ok(Self { + methods: s + .methods + .into_iter() + .map(TryInto::try_into) + .collect::>()?, + disabled: s.disabled, + }) + } +} + +/// FFI-compatible MeltMethodSettings (NUT-05) +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct MeltMethodSettings { + pub method: PaymentMethod, + pub unit: CurrencyUnit, + pub min_amount: Option, + pub max_amount: Option, + /// For bolt11, whether mint supports amountless invoices + pub amountless: Option, +} + +impl From for MeltMethodSettings { + fn from(s: cdk::nuts::nut05::MeltMethodSettings) -> Self { + let amountless = match s.options { + Some(cdk::nuts::nut05::MeltMethodOptions::Bolt11 { amountless }) => Some(amountless), + _ => None, + }; + Self { + method: s.method.into(), + unit: s.unit.into(), + min_amount: s.min_amount.map(Into::into), + max_amount: s.max_amount.map(Into::into), + amountless, + } + } +} + +impl TryFrom for cdk::nuts::nut05::MeltMethodSettings { + type Error = FfiError; + + fn try_from(s: MeltMethodSettings) -> Result { + let options = match (s.method.clone(), s.amountless) { + (PaymentMethod::Bolt11, Some(amountless)) => { + Some(cdk::nuts::nut05::MeltMethodOptions::Bolt11 { amountless }) + } + _ => None, + }; + Ok(Self { + method: s.method.into(), + unit: s.unit.into(), + min_amount: s.min_amount.map(Into::into), + max_amount: s.max_amount.map(Into::into), + options, + }) + } +} + +/// FFI-compatible Nut05 Settings +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct Nut05Settings { + pub methods: Vec, + pub disabled: bool, +} + +impl From for Nut05Settings { + fn from(s: cdk::nuts::nut05::Settings) -> Self { + Self { + methods: s.methods.into_iter().map(Into::into).collect(), + disabled: s.disabled, + } + } +} + +impl TryFrom for cdk::nuts::nut05::Settings { + type Error = FfiError; + + fn try_from(s: Nut05Settings) -> Result { + Ok(Self { + methods: s + .methods + .into_iter() + .map(TryInto::try_into) + .collect::>()?, + disabled: s.disabled, + }) + } +} + +/// FFI-compatible ProtectedEndpoint (for auth nuts) +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct ProtectedEndpoint { + /// HTTP method (GET, POST, etc.) + pub method: String, + /// Endpoint path + pub path: String, +} + +/// FFI-compatible ClearAuthSettings (NUT-21) +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct ClearAuthSettings { + /// OpenID Connect discovery URL + pub openid_discovery: String, + /// OAuth 2.0 client ID + pub client_id: String, + /// Protected endpoints requiring clear authentication + pub protected_endpoints: Vec, +} + +/// FFI-compatible BlindAuthSettings (NUT-22) +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct BlindAuthSettings { + /// Maximum number of blind auth tokens that can be minted per request + pub bat_max_mint: u64, + /// Protected endpoints requiring blind authentication + pub protected_endpoints: Vec, +} + +impl From for ClearAuthSettings { + fn from(settings: cdk::nuts::ClearAuthSettings) -> Self { + Self { + openid_discovery: settings.openid_discovery, + client_id: settings.client_id, + protected_endpoints: settings + .protected_endpoints + .into_iter() + .map(Into::into) + .collect(), + } + } +} + +impl TryFrom for cdk::nuts::ClearAuthSettings { + type Error = FfiError; + + fn try_from(settings: ClearAuthSettings) -> Result { + Ok(Self { + openid_discovery: settings.openid_discovery, + client_id: settings.client_id, + protected_endpoints: settings + .protected_endpoints + .into_iter() + .map(|e| e.try_into()) + .collect::, _>>()?, + }) + } +} + +impl From for BlindAuthSettings { + fn from(settings: cdk::nuts::BlindAuthSettings) -> Self { + Self { + bat_max_mint: settings.bat_max_mint, + protected_endpoints: settings + .protected_endpoints + .into_iter() + .map(Into::into) + .collect(), + } + } +} + +impl TryFrom for cdk::nuts::BlindAuthSettings { + type Error = FfiError; + + fn try_from(settings: BlindAuthSettings) -> Result { + Ok(Self { + bat_max_mint: settings.bat_max_mint, + protected_endpoints: settings + .protected_endpoints + .into_iter() + .map(|e| e.try_into()) + .collect::, _>>()?, + }) + } +} + +impl From for ProtectedEndpoint { + fn from(endpoint: cdk::nuts::ProtectedEndpoint) -> Self { + Self { + method: match endpoint.method { + cdk::nuts::Method::Get => "GET".to_string(), + cdk::nuts::Method::Post => "POST".to_string(), + }, + path: endpoint.path.to_string(), + } + } +} + +impl TryFrom for cdk::nuts::ProtectedEndpoint { + type Error = FfiError; + + fn try_from(endpoint: ProtectedEndpoint) -> Result { + let method = match endpoint.method.as_str() { + "GET" => cdk::nuts::Method::Get, + "POST" => cdk::nuts::Method::Post, + _ => { + return Err(FfiError::Generic { + msg: format!( + "Invalid HTTP method: {}. Only GET and POST are supported", + endpoint.method + ), + }) + } + }; + + // Convert path string to RoutePath by matching against known paths + let route_path = match endpoint.path.as_str() { + "/v1/mint/quote/bolt11" => cdk::nuts::RoutePath::MintQuoteBolt11, + "/v1/mint/bolt11" => cdk::nuts::RoutePath::MintBolt11, + "/v1/melt/quote/bolt11" => cdk::nuts::RoutePath::MeltQuoteBolt11, + "/v1/melt/bolt11" => cdk::nuts::RoutePath::MeltBolt11, + "/v1/swap" => cdk::nuts::RoutePath::Swap, + "/v1/checkstate" => cdk::nuts::RoutePath::Checkstate, + "/v1/restore" => cdk::nuts::RoutePath::Restore, + "/v1/auth/blind/mint" => cdk::nuts::RoutePath::MintBlindAuth, + "/v1/mint/quote/bolt12" => cdk::nuts::RoutePath::MintQuoteBolt12, + "/v1/mint/bolt12" => cdk::nuts::RoutePath::MintBolt12, + "/v1/melt/quote/bolt12" => cdk::nuts::RoutePath::MeltQuoteBolt12, + "/v1/melt/bolt12" => cdk::nuts::RoutePath::MeltBolt12, + _ => { + return Err(FfiError::Generic { + msg: format!("Unknown route path: {}", endpoint.path), + }) + } + }; + + Ok(cdk::nuts::ProtectedEndpoint::new(method, route_path)) + } +} + +/// FFI-compatible Nuts settings (extended to include NUT-04 and NUT-05 settings) +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct Nuts { + /// NUT04 Settings + pub nut04: Nut04Settings, + /// NUT05 Settings + pub nut05: Nut05Settings, + /// NUT07 Settings - Token state check + pub nut07_supported: bool, + /// NUT08 Settings - Lightning fee return + pub nut08_supported: bool, + /// NUT09 Settings - Restore signature + pub nut09_supported: bool, + /// NUT10 Settings - Spending conditions + pub nut10_supported: bool, + /// NUT11 Settings - Pay to Public Key Hash + pub nut11_supported: bool, + /// NUT12 Settings - DLEQ proofs + pub nut12_supported: bool, + /// NUT14 Settings - Hashed Time Locked Contracts + pub nut14_supported: bool, + /// NUT20 Settings - Web sockets + pub nut20_supported: bool, + /// NUT21 Settings - Clear authentication + pub nut21: Option, + /// NUT22 Settings - Blind authentication + pub nut22: Option, + /// Supported currency units for minting + pub mint_units: Vec, + /// Supported currency units for melting + pub melt_units: Vec, +} + +impl From for Nuts { + fn from(nuts: cdk::nuts::Nuts) -> Self { + let mint_units = nuts + .supported_mint_units() + .into_iter() + .map(|u| u.clone().into()) + .collect(); + let melt_units = nuts + .supported_melt_units() + .into_iter() + .map(|u| u.clone().into()) + .collect(); + + Self { + nut04: nuts.nut04.clone().into(), + nut05: nuts.nut05.clone().into(), + nut07_supported: nuts.nut07.supported, + nut08_supported: nuts.nut08.supported, + nut09_supported: nuts.nut09.supported, + nut10_supported: nuts.nut10.supported, + nut11_supported: nuts.nut11.supported, + nut12_supported: nuts.nut12.supported, + nut14_supported: nuts.nut14.supported, + nut20_supported: nuts.nut20.supported, + nut21: nuts.nut21.map(Into::into), + nut22: nuts.nut22.map(Into::into), + mint_units, + melt_units, + } + } +} + +impl TryFrom for cdk::nuts::Nuts { + type Error = FfiError; + + fn try_from(n: Nuts) -> Result { + Ok(Self { + nut04: n.nut04.try_into()?, + nut05: n.nut05.try_into()?, + nut07: cdk::nuts::nut06::SupportedSettings { + supported: n.nut07_supported, + }, + nut08: cdk::nuts::nut06::SupportedSettings { + supported: n.nut08_supported, + }, + nut09: cdk::nuts::nut06::SupportedSettings { + supported: n.nut09_supported, + }, + nut10: cdk::nuts::nut06::SupportedSettings { + supported: n.nut10_supported, + }, + nut11: cdk::nuts::nut06::SupportedSettings { + supported: n.nut11_supported, + }, + nut12: cdk::nuts::nut06::SupportedSettings { + supported: n.nut12_supported, + }, + nut14: cdk::nuts::nut06::SupportedSettings { + supported: n.nut14_supported, + }, + nut15: Default::default(), + nut17: Default::default(), + nut19: Default::default(), + nut20: cdk::nuts::nut06::SupportedSettings { + supported: n.nut20_supported, + }, + nut21: n.nut21.map(|s| s.try_into()).transpose()?, + nut22: n.nut22.map(|s| s.try_into()).transpose()?, + }) + } +} + +impl Nuts { + /// Convert Nuts to JSON string + pub fn to_json(&self) -> Result { + Ok(serde_json::to_string(self)?) + } +} + +/// Decode Nuts from JSON string +#[uniffi::export] +pub fn decode_nuts(json: String) -> Result { + Ok(serde_json::from_str(&json)?) +} + +/// Encode Nuts to JSON string +#[uniffi::export] +pub fn encode_nuts(nuts: Nuts) -> Result { + Ok(serde_json::to_string(&nuts)?) +} + +/// FFI-compatible MintInfo +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct MintInfo { + /// name of the mint and should be recognizable + pub name: Option, + /// hex pubkey of the mint + pub pubkey: Option, + /// implementation name and the version running + pub version: Option, + /// short description of the mint + pub description: Option, + /// long description + pub description_long: Option, + /// Contact info + pub contact: Option>, + /// shows which NUTs the mint supports + pub nuts: Nuts, + /// Mint's icon URL + pub icon_url: Option, + /// Mint's endpoint URLs + pub urls: Option>, + /// message of the day that the wallet must display to the user + pub motd: Option, + /// server unix timestamp + pub time: Option, + /// terms of url service of the mint + pub tos_url: Option, +} + +impl From for MintInfo { + fn from(info: cdk::nuts::MintInfo) -> Self { + Self { + name: info.name, + pubkey: info.pubkey.map(|p| p.to_string()), + version: info.version.map(Into::into), + description: info.description, + description_long: info.description_long, + contact: info + .contact + .map(|contacts| contacts.into_iter().map(Into::into).collect()), + nuts: info.nuts.into(), + icon_url: info.icon_url, + urls: info.urls, + motd: info.motd, + time: info.time, + tos_url: info.tos_url, + } + } +} + +impl From for cdk::nuts::MintInfo { + fn from(info: MintInfo) -> Self { + // Convert FFI Nuts back to cdk::nuts::Nuts (best-effort) + let nuts_cdk: cdk::nuts::Nuts = info.nuts.clone().try_into().unwrap_or_default(); + Self { + name: info.name, + pubkey: info.pubkey.and_then(|p| p.parse().ok()), + version: info.version.map(Into::into), + description: info.description, + description_long: info.description_long, + contact: info + .contact + .map(|contacts| contacts.into_iter().map(Into::into).collect()), + nuts: nuts_cdk, + icon_url: info.icon_url, + urls: info.urls, + motd: info.motd, + time: info.time, + tos_url: info.tos_url, + } + } +} + +impl MintInfo { + /// Convert MintInfo to JSON string + pub fn to_json(&self) -> Result { + Ok(serde_json::to_string(self)?) + } +} + +/// Decode MintInfo from JSON string +#[uniffi::export] +pub fn decode_mint_info(json: String) -> Result { + Ok(serde_json::from_str(&json)?) +} + +/// Encode MintInfo to JSON string +#[uniffi::export] +pub fn encode_mint_info(info: MintInfo) -> Result { + Ok(serde_json::to_string(&info)?) +} diff --git a/crates/cdk-ffi/src/types/mod.rs b/crates/cdk-ffi/src/types/mod.rs new file mode 100644 index 000000000..3c4257186 --- /dev/null +++ b/crates/cdk-ffi/src/types/mod.rs @@ -0,0 +1,24 @@ +//! FFI-compatible types +//! +//! This module contains all the FFI types used by the UniFFI bindings. +//! Types are organized into logical submodules for better maintainability. + +// Module declarations +pub mod amount; +pub mod keys; +pub mod mint; +pub mod proof; +pub mod quote; +pub mod subscription; +pub mod transaction; +pub mod wallet; + +// Re-export all types for convenient access +pub use amount::*; +pub use keys::*; +pub use mint::*; +pub use proof::*; +pub use quote::*; +pub use subscription::*; +pub use transaction::*; +pub use wallet::*; diff --git a/crates/cdk-ffi/src/types/proof.rs b/crates/cdk-ffi/src/types/proof.rs new file mode 100644 index 000000000..e75e6c0ec --- /dev/null +++ b/crates/cdk-ffi/src/types/proof.rs @@ -0,0 +1,509 @@ +//! Proof-related FFI types + +use std::str::FromStr; + +use cdk::nuts::State as CdkState; +use serde::{Deserialize, Serialize}; + +use super::amount::{Amount, CurrencyUnit}; +use super::mint::MintUrl; +use crate::error::FfiError; + +/// FFI-compatible Proof state +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, uniffi::Enum)] +pub enum ProofState { + Unspent, + Pending, + Spent, + Reserved, + PendingSpent, +} + +impl From for ProofState { + fn from(state: CdkState) -> Self { + match state { + CdkState::Unspent => ProofState::Unspent, + CdkState::Pending => ProofState::Pending, + CdkState::Spent => ProofState::Spent, + CdkState::Reserved => ProofState::Reserved, + CdkState::PendingSpent => ProofState::PendingSpent, + } + } +} + +impl From for CdkState { + fn from(state: ProofState) -> Self { + match state { + ProofState::Unspent => CdkState::Unspent, + ProofState::Pending => CdkState::Pending, + ProofState::Spent => CdkState::Spent, + ProofState::Reserved => CdkState::Reserved, + ProofState::PendingSpent => CdkState::PendingSpent, + } + } +} + +/// FFI-compatible Proof +#[derive(Debug, uniffi::Object)] +pub struct Proof { + pub(crate) inner: cdk::nuts::Proof, +} + +impl From for Proof { + fn from(proof: cdk::nuts::Proof) -> Self { + Self { inner: proof } + } +} + +impl From for cdk::nuts::Proof { + fn from(proof: Proof) -> Self { + proof.inner + } +} + +#[uniffi::export] +impl Proof { + /// Get the amount + pub fn amount(&self) -> Amount { + self.inner.amount.into() + } + + /// Get the secret as string + pub fn secret(&self) -> String { + self.inner.secret.to_string() + } + + /// Get the unblinded signature (C) as string + pub fn c(&self) -> String { + self.inner.c.to_string() + } + + /// Get the keyset ID as string + pub fn keyset_id(&self) -> String { + self.inner.keyset_id.to_string() + } + + /// Get the witness + pub fn witness(&self) -> Option { + self.inner.witness.as_ref().map(|w| w.clone().into()) + } + + /// Check if proof is active with given keyset IDs + pub fn is_active(&self, active_keyset_ids: Vec) -> bool { + use cdk::nuts::Id; + let ids: Vec = active_keyset_ids + .into_iter() + .filter_map(|id| Id::from_str(&id).ok()) + .collect(); + self.inner.is_active(&ids) + } + + /// Get the Y value (hash_to_curve of secret) + pub fn y(&self) -> Result { + Ok(self.inner.y()?.to_string()) + } + + /// Get the DLEQ proof if present + pub fn dleq(&self) -> Option { + self.inner.dleq.as_ref().map(|d| d.clone().into()) + } + + /// Check if proof has DLEQ proof + pub fn has_dleq(&self) -> bool { + self.inner.dleq.is_some() + } +} + +/// FFI-compatible Proofs (vector of Proof) +pub type Proofs = Vec>; + +/// FFI-compatible DLEQ proof for proofs +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct ProofDleq { + /// e value (hex-encoded SecretKey) + pub e: String, + /// s value (hex-encoded SecretKey) + pub s: String, + /// r value - blinding factor (hex-encoded SecretKey) + pub r: String, +} + +/// FFI-compatible DLEQ proof for blind signatures +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct BlindSignatureDleq { + /// e value (hex-encoded SecretKey) + pub e: String, + /// s value (hex-encoded SecretKey) + pub s: String, +} + +impl From for ProofDleq { + fn from(dleq: cdk::nuts::ProofDleq) -> Self { + Self { + e: dleq.e.to_secret_hex(), + s: dleq.s.to_secret_hex(), + r: dleq.r.to_secret_hex(), + } + } +} + +impl From for cdk::nuts::ProofDleq { + fn from(dleq: ProofDleq) -> Self { + Self { + e: cdk::nuts::SecretKey::from_hex(&dleq.e).expect("Invalid e hex"), + s: cdk::nuts::SecretKey::from_hex(&dleq.s).expect("Invalid s hex"), + r: cdk::nuts::SecretKey::from_hex(&dleq.r).expect("Invalid r hex"), + } + } +} + +impl From for BlindSignatureDleq { + fn from(dleq: cdk::nuts::BlindSignatureDleq) -> Self { + Self { + e: dleq.e.to_secret_hex(), + s: dleq.s.to_secret_hex(), + } + } +} + +impl From for cdk::nuts::BlindSignatureDleq { + fn from(dleq: BlindSignatureDleq) -> Self { + Self { + e: cdk::nuts::SecretKey::from_hex(&dleq.e).expect("Invalid e hex"), + s: cdk::nuts::SecretKey::from_hex(&dleq.s).expect("Invalid s hex"), + } + } +} + +/// Helper functions for Proofs +pub fn proofs_total_amount(proofs: &Proofs) -> Result { + let cdk_proofs: Vec = proofs.iter().map(|p| p.inner.clone()).collect(); + use cdk::nuts::ProofsMethods; + Ok(cdk_proofs.total_amount()?.into()) +} + +/// FFI-compatible Conditions (for spending conditions) +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct Conditions { + /// Unix locktime after which refund keys can be used + pub locktime: Option, + /// Additional Public keys (as hex strings) + pub pubkeys: Vec, + /// Refund keys (as hex strings) + pub refund_keys: Vec, + /// Number of signatures required (default 1) + pub num_sigs: Option, + /// Signature flag (0 = SigInputs, 1 = SigAll) + pub sig_flag: u8, + /// Number of refund signatures required (default 1) + pub num_sigs_refund: Option, +} + +impl From for Conditions { + fn from(conditions: cdk::nuts::nut11::Conditions) -> Self { + Self { + locktime: conditions.locktime, + pubkeys: conditions + .pubkeys + .unwrap_or_default() + .into_iter() + .map(|p| p.to_string()) + .collect(), + refund_keys: conditions + .refund_keys + .unwrap_or_default() + .into_iter() + .map(|p| p.to_string()) + .collect(), + num_sigs: conditions.num_sigs, + sig_flag: match conditions.sig_flag { + cdk::nuts::nut11::SigFlag::SigInputs => 0, + cdk::nuts::nut11::SigFlag::SigAll => 1, + }, + num_sigs_refund: conditions.num_sigs_refund, + } + } +} + +impl TryFrom for cdk::nuts::nut11::Conditions { + type Error = FfiError; + + fn try_from(conditions: Conditions) -> Result { + let pubkeys = if conditions.pubkeys.is_empty() { + None + } else { + Some( + conditions + .pubkeys + .into_iter() + .map(|s| { + s.parse().map_err(|e| FfiError::InvalidCryptographicKey { + msg: format!("Invalid pubkey: {}", e), + }) + }) + .collect::, _>>()?, + ) + }; + + let refund_keys = if conditions.refund_keys.is_empty() { + None + } else { + Some( + conditions + .refund_keys + .into_iter() + .map(|s| { + s.parse().map_err(|e| FfiError::InvalidCryptographicKey { + msg: format!("Invalid refund key: {}", e), + }) + }) + .collect::, _>>()?, + ) + }; + + let sig_flag = match conditions.sig_flag { + 0 => cdk::nuts::nut11::SigFlag::SigInputs, + 1 => cdk::nuts::nut11::SigFlag::SigAll, + _ => { + return Err(FfiError::Generic { + msg: "Invalid sig_flag value".to_string(), + }) + } + }; + + Ok(Self { + locktime: conditions.locktime, + pubkeys, + refund_keys, + num_sigs: conditions.num_sigs, + sig_flag, + num_sigs_refund: conditions.num_sigs_refund, + }) + } +} + +impl Conditions { + /// Convert Conditions to JSON string + pub fn to_json(&self) -> Result { + Ok(serde_json::to_string(self)?) + } +} + +/// Decode Conditions from JSON string +#[uniffi::export] +pub fn decode_conditions(json: String) -> Result { + Ok(serde_json::from_str(&json)?) +} + +/// Encode Conditions to JSON string +#[uniffi::export] +pub fn encode_conditions(conditions: Conditions) -> Result { + Ok(serde_json::to_string(&conditions)?) +} + +/// FFI-compatible Witness +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Enum)] +pub enum Witness { + /// P2PK Witness + P2PK { + /// Signatures + signatures: Vec, + }, + /// HTLC Witness + HTLC { + /// Preimage + preimage: String, + /// Optional signatures + signatures: Option>, + }, +} + +impl From for Witness { + fn from(witness: cdk::nuts::Witness) -> Self { + match witness { + cdk::nuts::Witness::P2PKWitness(p2pk) => Self::P2PK { + signatures: p2pk.signatures, + }, + cdk::nuts::Witness::HTLCWitness(htlc) => Self::HTLC { + preimage: htlc.preimage, + signatures: htlc.signatures, + }, + } + } +} + +impl From for cdk::nuts::Witness { + fn from(witness: Witness) -> Self { + match witness { + Witness::P2PK { signatures } => { + Self::P2PKWitness(cdk::nuts::nut11::P2PKWitness { signatures }) + } + Witness::HTLC { + preimage, + signatures, + } => Self::HTLCWitness(cdk::nuts::nut14::HTLCWitness { + preimage, + signatures, + }), + } + } +} + +/// FFI-compatible SpendingConditions +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Enum)] +pub enum SpendingConditions { + /// P2PK (Pay to Public Key) conditions + P2PK { + /// The public key (as hex string) + pubkey: String, + /// Additional conditions + conditions: Option, + }, + /// HTLC (Hash Time Locked Contract) conditions + HTLC { + /// Hash of the preimage (as hex string) + hash: String, + /// Additional conditions + conditions: Option, + }, +} + +impl From for SpendingConditions { + fn from(spending_conditions: cdk::nuts::SpendingConditions) -> Self { + match spending_conditions { + cdk::nuts::SpendingConditions::P2PKConditions { data, conditions } => Self::P2PK { + pubkey: data.to_string(), + conditions: conditions.map(Into::into), + }, + cdk::nuts::SpendingConditions::HTLCConditions { data, conditions } => Self::HTLC { + hash: data.to_string(), + conditions: conditions.map(Into::into), + }, + } + } +} + +impl TryFrom for cdk::nuts::SpendingConditions { + type Error = FfiError; + + fn try_from(spending_conditions: SpendingConditions) -> Result { + match spending_conditions { + SpendingConditions::P2PK { pubkey, conditions } => { + let pubkey = pubkey + .parse() + .map_err(|e| FfiError::InvalidCryptographicKey { + msg: format!("Invalid pubkey: {}", e), + })?; + let conditions = conditions.map(|c| c.try_into()).transpose()?; + Ok(Self::P2PKConditions { + data: pubkey, + conditions, + }) + } + SpendingConditions::HTLC { hash, conditions } => { + let hash = hash + .parse() + .map_err(|e| FfiError::InvalidCryptographicKey { + msg: format!("Invalid hash: {}", e), + })?; + let conditions = conditions.map(|c| c.try_into()).transpose()?; + Ok(Self::HTLCConditions { + data: hash, + conditions, + }) + } + } + } +} + +/// FFI-compatible ProofInfo +#[derive(Debug, Clone, uniffi::Record)] +pub struct ProofInfo { + /// Proof + pub proof: std::sync::Arc, + /// Y value (hash_to_curve of secret) + pub y: super::keys::PublicKey, + /// Mint URL + pub mint_url: MintUrl, + /// Proof state + pub state: ProofState, + /// Proof Spending Conditions + pub spending_condition: Option, + /// Currency unit + pub unit: CurrencyUnit, +} + +impl From for ProofInfo { + fn from(info: cdk::types::ProofInfo) -> Self { + Self { + proof: std::sync::Arc::new(info.proof.into()), + y: info.y.into(), + mint_url: info.mint_url.into(), + state: info.state.into(), + spending_condition: info.spending_condition.map(Into::into), + unit: info.unit.into(), + } + } +} + +/// Decode ProofInfo from JSON string +#[uniffi::export] +pub fn decode_proof_info(json: String) -> Result { + let info: cdk::types::ProofInfo = serde_json::from_str(&json)?; + Ok(info.into()) +} + +/// Encode ProofInfo to JSON string +#[uniffi::export] +pub fn encode_proof_info(info: ProofInfo) -> Result { + // Convert to cdk::types::ProofInfo for serialization + let cdk_info = cdk::types::ProofInfo { + proof: info.proof.inner.clone(), + y: info.y.try_into()?, + mint_url: info.mint_url.try_into()?, + state: info.state.into(), + spending_condition: info.spending_condition.and_then(|c| c.try_into().ok()), + unit: info.unit.into(), + }; + Ok(serde_json::to_string(&cdk_info)?) +} + +/// FFI-compatible ProofStateUpdate +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct ProofStateUpdate { + /// Y value (hash_to_curve of secret) + pub y: String, + /// Current state + pub state: ProofState, + /// Optional witness data + pub witness: Option, +} + +impl From for ProofStateUpdate { + fn from(proof_state: cdk::nuts::nut07::ProofState) -> Self { + Self { + y: proof_state.y.to_string(), + state: proof_state.state.into(), + witness: proof_state.witness.map(|w| format!("{:?}", w)), + } + } +} + +impl ProofStateUpdate { + /// Convert ProofStateUpdate to JSON string + pub fn to_json(&self) -> Result { + Ok(serde_json::to_string(self)?) + } +} + +/// Decode ProofStateUpdate from JSON string +#[uniffi::export] +pub fn decode_proof_state_update(json: String) -> Result { + Ok(serde_json::from_str(&json)?) +} + +/// Encode ProofStateUpdate to JSON string +#[uniffi::export] +pub fn encode_proof_state_update(update: ProofStateUpdate) -> Result { + Ok(serde_json::to_string(&update)?) +} diff --git a/crates/cdk-ffi/src/types/quote.rs b/crates/cdk-ffi/src/types/quote.rs new file mode 100644 index 000000000..e931008a5 --- /dev/null +++ b/crates/cdk-ffi/src/types/quote.rs @@ -0,0 +1,430 @@ +//! Quote-related FFI types + +use serde::{Deserialize, Serialize}; + +use super::amount::{Amount, CurrencyUnit}; +use super::mint::MintUrl; +use crate::error::FfiError; + +/// FFI-compatible MintQuote +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct MintQuote { + /// Quote ID + pub id: String, + /// Quote amount + pub amount: Option, + /// Currency unit + pub unit: CurrencyUnit, + /// Payment request + pub request: String, + /// Quote state + pub state: QuoteState, + /// Expiry timestamp + pub expiry: u64, + /// Mint URL + pub mint_url: MintUrl, + /// Amount issued + pub amount_issued: Amount, + /// Amount paid + pub amount_paid: Amount, + /// Payment method + pub payment_method: PaymentMethod, + /// Secret key (optional, hex-encoded) + pub secret_key: Option, +} + +impl From for MintQuote { + fn from(quote: cdk::wallet::MintQuote) -> Self { + Self { + id: quote.id.clone(), + amount: quote.amount.map(Into::into), + unit: quote.unit.clone().into(), + request: quote.request.clone(), + state: quote.state.into(), + expiry: quote.expiry, + mint_url: quote.mint_url.clone().into(), + amount_issued: quote.amount_issued.into(), + amount_paid: quote.amount_paid.into(), + payment_method: quote.payment_method.into(), + secret_key: quote.secret_key.map(|sk| sk.to_secret_hex()), + } + } +} + +impl TryFrom for cdk::wallet::MintQuote { + type Error = FfiError; + + fn try_from(quote: MintQuote) -> Result { + let secret_key = quote + .secret_key + .map(|hex| cdk::nuts::SecretKey::from_hex(&hex)) + .transpose() + .map_err(|e| FfiError::InvalidCryptographicKey { msg: e.to_string() })?; + + Ok(Self { + id: quote.id, + amount: quote.amount.map(Into::into), + unit: quote.unit.into(), + request: quote.request, + state: quote.state.into(), + expiry: quote.expiry, + mint_url: quote.mint_url.try_into()?, + amount_issued: quote.amount_issued.into(), + amount_paid: quote.amount_paid.into(), + payment_method: quote.payment_method.into(), + secret_key, + }) + } +} + +impl MintQuote { + /// Get total amount (amount + fees) + pub fn total_amount(&self) -> Amount { + if let Some(amount) = self.amount { + Amount::new(amount.value + self.amount_paid.value - self.amount_issued.value) + } else { + Amount::zero() + } + } + + /// Check if quote is expired + pub fn is_expired(&self, current_time: u64) -> bool { + current_time > self.expiry + } + + /// Get amount that can be minted + pub fn amount_mintable(&self) -> Amount { + Amount::new(self.amount_paid.value - self.amount_issued.value) + } + + /// Convert MintQuote to JSON string + pub fn to_json(&self) -> Result { + Ok(serde_json::to_string(self)?) + } +} + +/// Decode MintQuote from JSON string +#[uniffi::export] +pub fn decode_mint_quote(json: String) -> Result { + let quote: cdk::wallet::MintQuote = serde_json::from_str(&json)?; + Ok(quote.into()) +} + +/// Encode MintQuote to JSON string +#[uniffi::export] +pub fn encode_mint_quote(quote: MintQuote) -> Result { + Ok(serde_json::to_string("e)?) +} + +/// FFI-compatible MintQuoteBolt11Response +#[derive(Debug, uniffi::Object)] +pub struct MintQuoteBolt11Response { + /// Quote ID + pub quote: String, + /// Request string + pub request: String, + /// State of the quote + pub state: QuoteState, + /// Expiry timestamp (optional) + pub expiry: Option, + /// Amount (optional) + pub amount: Option, + /// Unit (optional) + pub unit: Option, + /// Pubkey (optional) + pub pubkey: Option, +} + +impl From> for MintQuoteBolt11Response { + fn from(response: cdk::nuts::MintQuoteBolt11Response) -> Self { + Self { + quote: response.quote, + request: response.request, + state: response.state.into(), + expiry: response.expiry, + amount: response.amount.map(Into::into), + unit: response.unit.map(Into::into), + pubkey: response.pubkey.map(|p| p.to_string()), + } + } +} + +#[uniffi::export] +impl MintQuoteBolt11Response { + /// Get quote ID + pub fn quote(&self) -> String { + self.quote.clone() + } + + /// Get request string + pub fn request(&self) -> String { + self.request.clone() + } + + /// Get state + pub fn state(&self) -> QuoteState { + self.state.clone() + } + + /// Get expiry + pub fn expiry(&self) -> Option { + self.expiry + } + + /// Get amount + pub fn amount(&self) -> Option { + self.amount + } + + /// Get unit + pub fn unit(&self) -> Option { + self.unit.clone() + } + + /// Get pubkey + pub fn pubkey(&self) -> Option { + self.pubkey.clone() + } +} + +/// FFI-compatible MeltQuoteBolt11Response +#[derive(Debug, uniffi::Object)] +pub struct MeltQuoteBolt11Response { + /// Quote ID + pub quote: String, + /// Amount + pub amount: Amount, + /// Fee reserve + pub fee_reserve: Amount, + /// State of the quote + pub state: QuoteState, + /// Expiry timestamp + pub expiry: u64, + /// Payment preimage (optional) + pub payment_preimage: Option, + /// Request string (optional) + pub request: Option, + /// Unit (optional) + pub unit: Option, +} + +impl From> for MeltQuoteBolt11Response { + fn from(response: cdk::nuts::MeltQuoteBolt11Response) -> Self { + Self { + quote: response.quote, + amount: response.amount.into(), + fee_reserve: response.fee_reserve.into(), + state: response.state.into(), + expiry: response.expiry, + payment_preimage: response.payment_preimage, + request: response.request, + unit: response.unit.map(Into::into), + } + } +} + +#[uniffi::export] +impl MeltQuoteBolt11Response { + /// Get quote ID + pub fn quote(&self) -> String { + self.quote.clone() + } + + /// Get amount + pub fn amount(&self) -> Amount { + self.amount + } + + /// Get fee reserve + pub fn fee_reserve(&self) -> Amount { + self.fee_reserve + } + + /// Get state + pub fn state(&self) -> QuoteState { + self.state.clone() + } + + /// Get expiry + pub fn expiry(&self) -> u64 { + self.expiry + } + + /// Get payment preimage + pub fn payment_preimage(&self) -> Option { + self.payment_preimage.clone() + } + + /// Get request + pub fn request(&self) -> Option { + self.request.clone() + } + + /// Get unit + pub fn unit(&self) -> Option { + self.unit.clone() + } +} + +/// FFI-compatible PaymentMethod +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, uniffi::Enum)] +pub enum PaymentMethod { + /// Bolt11 payment type + Bolt11, + /// Bolt12 payment type + Bolt12, + /// Custom payment type + Custom { method: String }, +} + +impl From for PaymentMethod { + fn from(method: cdk::nuts::PaymentMethod) -> Self { + match method { + cdk::nuts::PaymentMethod::Bolt11 => Self::Bolt11, + cdk::nuts::PaymentMethod::Bolt12 => Self::Bolt12, + cdk::nuts::PaymentMethod::Custom(s) => Self::Custom { method: s }, + } + } +} + +impl From for cdk::nuts::PaymentMethod { + fn from(method: PaymentMethod) -> Self { + match method { + PaymentMethod::Bolt11 => Self::Bolt11, + PaymentMethod::Bolt12 => Self::Bolt12, + PaymentMethod::Custom { method } => Self::Custom(method), + } + } +} + +/// FFI-compatible MeltQuote +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct MeltQuote { + /// Quote ID + pub id: String, + /// Quote amount + pub amount: Amount, + /// Currency unit + pub unit: CurrencyUnit, + /// Payment request + pub request: String, + /// Fee reserve + pub fee_reserve: Amount, + /// Quote state + pub state: QuoteState, + /// Expiry timestamp + pub expiry: u64, + /// Payment preimage + pub payment_preimage: Option, + /// Payment method + pub payment_method: PaymentMethod, +} + +impl From for MeltQuote { + fn from(quote: cdk::wallet::MeltQuote) -> Self { + Self { + id: quote.id.clone(), + amount: quote.amount.into(), + unit: quote.unit.clone().into(), + request: quote.request.clone(), + fee_reserve: quote.fee_reserve.into(), + state: quote.state.into(), + expiry: quote.expiry, + payment_preimage: quote.payment_preimage.clone(), + payment_method: quote.payment_method.into(), + } + } +} + +impl TryFrom for cdk::wallet::MeltQuote { + type Error = FfiError; + + fn try_from(quote: MeltQuote) -> Result { + Ok(Self { + id: quote.id, + amount: quote.amount.into(), + unit: quote.unit.into(), + request: quote.request, + fee_reserve: quote.fee_reserve.into(), + state: quote.state.into(), + expiry: quote.expiry, + payment_preimage: quote.payment_preimage, + payment_method: quote.payment_method.into(), + }) + } +} + +impl MeltQuote { + /// Convert MeltQuote to JSON string + pub fn to_json(&self) -> Result { + Ok(serde_json::to_string(self)?) + } +} + +/// Decode MeltQuote from JSON string +#[uniffi::export] +pub fn decode_melt_quote(json: String) -> Result { + let quote: cdk::wallet::MeltQuote = serde_json::from_str(&json)?; + Ok(quote.into()) +} + +/// Encode MeltQuote to JSON string +#[uniffi::export] +pub fn encode_melt_quote(quote: MeltQuote) -> Result { + Ok(serde_json::to_string("e)?) +} + +/// FFI-compatible QuoteState +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, uniffi::Enum)] +pub enum QuoteState { + Unpaid, + Paid, + Pending, + Issued, +} + +impl From for QuoteState { + fn from(state: cdk::nuts::nut05::QuoteState) -> Self { + match state { + cdk::nuts::nut05::QuoteState::Unpaid => QuoteState::Unpaid, + cdk::nuts::nut05::QuoteState::Paid => QuoteState::Paid, + cdk::nuts::nut05::QuoteState::Pending => QuoteState::Pending, + cdk::nuts::nut05::QuoteState::Unknown => QuoteState::Unpaid, + cdk::nuts::nut05::QuoteState::Failed => QuoteState::Unpaid, + } + } +} + +impl From for cdk::nuts::nut05::QuoteState { + fn from(state: QuoteState) -> Self { + match state { + QuoteState::Unpaid => cdk::nuts::nut05::QuoteState::Unpaid, + QuoteState::Paid => cdk::nuts::nut05::QuoteState::Paid, + QuoteState::Pending => cdk::nuts::nut05::QuoteState::Pending, + QuoteState::Issued => cdk::nuts::nut05::QuoteState::Paid, // Map issued to paid for melt quotes + } + } +} + +impl From for QuoteState { + fn from(state: cdk::nuts::MintQuoteState) -> Self { + match state { + cdk::nuts::MintQuoteState::Unpaid => QuoteState::Unpaid, + cdk::nuts::MintQuoteState::Paid => QuoteState::Paid, + cdk::nuts::MintQuoteState::Issued => QuoteState::Issued, + } + } +} + +impl From for cdk::nuts::MintQuoteState { + fn from(state: QuoteState) -> Self { + match state { + QuoteState::Unpaid => cdk::nuts::MintQuoteState::Unpaid, + QuoteState::Paid => cdk::nuts::MintQuoteState::Paid, + QuoteState::Issued => cdk::nuts::MintQuoteState::Issued, + QuoteState::Pending => cdk::nuts::MintQuoteState::Paid, // Map pending to paid + } + } +} + +// Note: MeltQuoteState is the same as nut05::QuoteState, so we don't need a separate impl diff --git a/crates/cdk-ffi/src/types/subscription.rs b/crates/cdk-ffi/src/types/subscription.rs new file mode 100644 index 000000000..fb07389d9 --- /dev/null +++ b/crates/cdk-ffi/src/types/subscription.rs @@ -0,0 +1,183 @@ +//! Subscription-related FFI types + +use cdk::pub_sub::SubId; +use serde::{Deserialize, Serialize}; + +use super::proof::ProofStateUpdate; +use super::quote::{MeltQuoteBolt11Response, MintQuoteBolt11Response}; +use crate::error::FfiError; + +/// FFI-compatible SubscriptionKind +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, uniffi::Enum)] +pub enum SubscriptionKind { + /// Bolt 11 Melt Quote + Bolt11MeltQuote, + /// Bolt 11 Mint Quote + Bolt11MintQuote, + /// Bolt 12 Mint Quote + Bolt12MintQuote, + /// Proof State + ProofState, +} + +impl From for cdk::nuts::nut17::Kind { + fn from(kind: SubscriptionKind) -> Self { + match kind { + SubscriptionKind::Bolt11MeltQuote => cdk::nuts::nut17::Kind::Bolt11MeltQuote, + SubscriptionKind::Bolt11MintQuote => cdk::nuts::nut17::Kind::Bolt11MintQuote, + SubscriptionKind::Bolt12MintQuote => cdk::nuts::nut17::Kind::Bolt12MintQuote, + SubscriptionKind::ProofState => cdk::nuts::nut17::Kind::ProofState, + } + } +} + +impl From for SubscriptionKind { + fn from(kind: cdk::nuts::nut17::Kind) -> Self { + match kind { + cdk::nuts::nut17::Kind::Bolt11MeltQuote => SubscriptionKind::Bolt11MeltQuote, + cdk::nuts::nut17::Kind::Bolt11MintQuote => SubscriptionKind::Bolt11MintQuote, + cdk::nuts::nut17::Kind::Bolt12MintQuote => SubscriptionKind::Bolt12MintQuote, + cdk::nuts::nut17::Kind::ProofState => SubscriptionKind::ProofState, + } + } +} + +/// FFI-compatible SubscribeParams +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct SubscribeParams { + /// Subscription kind + pub kind: SubscriptionKind, + /// Filters + pub filters: Vec, + /// Subscription ID (optional, will be generated if not provided) + pub id: Option, +} + +impl From for cdk::nuts::nut17::Params { + fn from(params: SubscribeParams) -> Self { + let sub_id = params + .id + .map(|id| SubId::from(id.as_str())) + .unwrap_or_else(|| { + // Generate a random ID + let uuid = uuid::Uuid::new_v4(); + SubId::from(uuid.to_string().as_str()) + }); + + cdk::nuts::nut17::Params { + kind: params.kind.into(), + filters: params.filters, + id: sub_id, + } + } +} + +impl SubscribeParams { + /// Convert SubscribeParams to JSON string + pub fn to_json(&self) -> Result { + Ok(serde_json::to_string(self)?) + } +} + +/// Decode SubscribeParams from JSON string +#[uniffi::export] +pub fn decode_subscribe_params(json: String) -> Result { + Ok(serde_json::from_str(&json)?) +} + +/// Encode SubscribeParams to JSON string +#[uniffi::export] +pub fn encode_subscribe_params(params: SubscribeParams) -> Result { + Ok(serde_json::to_string(¶ms)?) +} + +/// FFI-compatible ActiveSubscription +#[derive(uniffi::Object)] +pub struct ActiveSubscription { + inner: std::sync::Arc>, + pub sub_id: String, +} + +impl ActiveSubscription { + pub(crate) fn new( + inner: cdk::wallet::subscription::ActiveSubscription, + sub_id: String, + ) -> Self { + Self { + inner: std::sync::Arc::new(tokio::sync::Mutex::new(inner)), + sub_id, + } + } +} + +#[uniffi::export(async_runtime = "tokio")] +impl ActiveSubscription { + /// Get the subscription ID + pub fn id(&self) -> String { + self.sub_id.clone() + } + + /// Receive the next notification + pub async fn recv(&self) -> Result { + let mut guard = self.inner.lock().await; + guard + .recv() + .await + .ok_or(FfiError::Generic { + msg: "Subscription closed".to_string(), + }) + .map(Into::into) + } + + /// Try to receive a notification without blocking + pub async fn try_recv(&self) -> Result, FfiError> { + let mut guard = self.inner.lock().await; + guard + .try_recv() + .map(|opt| opt.map(Into::into)) + .map_err(|e| FfiError::Generic { + msg: format!("Failed to receive notification: {}", e), + }) + } +} + +/// FFI-compatible NotificationPayload +#[derive(Debug, Clone, uniffi::Enum)] +pub enum NotificationPayload { + /// Proof state update + ProofState { proof_states: Vec }, + /// Mint quote update + MintQuoteUpdate { + quote: std::sync::Arc, + }, + /// Melt quote update + MeltQuoteUpdate { + quote: std::sync::Arc, + }, +} + +impl From> for NotificationPayload { + fn from(payload: cdk::nuts::NotificationPayload) -> Self { + match payload { + cdk::nuts::NotificationPayload::ProofState(states) => NotificationPayload::ProofState { + proof_states: vec![states.into()], + }, + cdk::nuts::NotificationPayload::MintQuoteBolt11Response(quote_resp) => { + NotificationPayload::MintQuoteUpdate { + quote: std::sync::Arc::new(quote_resp.into()), + } + } + cdk::nuts::NotificationPayload::MeltQuoteBolt11Response(quote_resp) => { + NotificationPayload::MeltQuoteUpdate { + quote: std::sync::Arc::new(quote_resp.into()), + } + } + _ => { + // For now, handle other notification types as empty ProofState + NotificationPayload::ProofState { + proof_states: vec![], + } + } + } + } +} diff --git a/crates/cdk-ffi/src/types/transaction.rs b/crates/cdk-ffi/src/types/transaction.rs new file mode 100644 index 000000000..9291c778f --- /dev/null +++ b/crates/cdk-ffi/src/types/transaction.rs @@ -0,0 +1,247 @@ +//! Transaction-related FFI types + +use std::collections::HashMap; + +use serde::{Deserialize, Serialize}; + +use super::amount::{Amount, CurrencyUnit}; +use super::keys::PublicKey; +use super::mint::MintUrl; +use super::proof::Proofs; +use crate::error::FfiError; + +/// FFI-compatible Transaction +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct Transaction { + /// Transaction ID + pub id: TransactionId, + /// Mint URL + pub mint_url: MintUrl, + /// Transaction direction + pub direction: TransactionDirection, + /// Amount + pub amount: Amount, + /// Fee + pub fee: Amount, + /// Currency Unit + pub unit: CurrencyUnit, + /// Proof Ys (Y values from proofs) + pub ys: Vec, + /// Unix timestamp + pub timestamp: u64, + /// Memo + pub memo: Option, + /// User-defined metadata + pub metadata: HashMap, + /// Quote ID if this is a mint or melt transaction + pub quote_id: Option, +} + +impl From for Transaction { + fn from(tx: cdk::wallet::types::Transaction) -> Self { + Self { + id: tx.id().into(), + mint_url: tx.mint_url.into(), + direction: tx.direction.into(), + amount: tx.amount.into(), + fee: tx.fee.into(), + unit: tx.unit.into(), + ys: tx.ys.into_iter().map(Into::into).collect(), + timestamp: tx.timestamp, + memo: tx.memo, + metadata: tx.metadata, + quote_id: tx.quote_id, + } + } +} + +/// Convert FFI Transaction to CDK Transaction +impl TryFrom for cdk::wallet::types::Transaction { + type Error = FfiError; + + fn try_from(tx: Transaction) -> Result { + let cdk_ys: Result, _> = + tx.ys.into_iter().map(|pk| pk.try_into()).collect(); + let cdk_ys = cdk_ys?; + + Ok(Self { + mint_url: tx.mint_url.try_into()?, + direction: tx.direction.into(), + amount: tx.amount.into(), + fee: tx.fee.into(), + unit: tx.unit.into(), + ys: cdk_ys, + timestamp: tx.timestamp, + memo: tx.memo, + metadata: tx.metadata, + quote_id: tx.quote_id, + }) + } +} + +impl Transaction { + /// Convert Transaction to JSON string + pub fn to_json(&self) -> Result { + Ok(serde_json::to_string(self)?) + } +} + +/// Decode Transaction from JSON string +#[uniffi::export] +pub fn decode_transaction(json: String) -> Result { + Ok(serde_json::from_str(&json)?) +} + +/// Encode Transaction to JSON string +#[uniffi::export] +pub fn encode_transaction(transaction: Transaction) -> Result { + Ok(serde_json::to_string(&transaction)?) +} + +/// FFI-compatible TransactionDirection +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, uniffi::Enum)] +pub enum TransactionDirection { + /// Incoming transaction (i.e., receive or mint) + Incoming, + /// Outgoing transaction (i.e., send or melt) + Outgoing, +} + +impl From for TransactionDirection { + fn from(direction: cdk::wallet::types::TransactionDirection) -> Self { + match direction { + cdk::wallet::types::TransactionDirection::Incoming => TransactionDirection::Incoming, + cdk::wallet::types::TransactionDirection::Outgoing => TransactionDirection::Outgoing, + } + } +} + +impl From for cdk::wallet::types::TransactionDirection { + fn from(direction: TransactionDirection) -> Self { + match direction { + TransactionDirection::Incoming => cdk::wallet::types::TransactionDirection::Incoming, + TransactionDirection::Outgoing => cdk::wallet::types::TransactionDirection::Outgoing, + } + } +} + +/// FFI-compatible TransactionId +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +#[serde(transparent)] +pub struct TransactionId { + /// Hex-encoded transaction ID (64 characters) + pub hex: String, +} + +impl TransactionId { + /// Create a new TransactionId from hex string + pub fn from_hex(hex: String) -> Result { + // Validate hex string length (should be 64 characters for 32 bytes) + if hex.len() != 64 { + return Err(FfiError::InvalidHex { + msg: "Transaction ID hex must be exactly 64 characters (32 bytes)".to_string(), + }); + } + + // Validate hex format + if !hex.chars().all(|c| c.is_ascii_hexdigit()) { + return Err(FfiError::InvalidHex { + msg: "Transaction ID hex contains invalid characters".to_string(), + }); + } + + Ok(Self { hex }) + } + + /// Create from proofs + pub fn from_proofs(proofs: &Proofs) -> Result { + let cdk_proofs: Vec = proofs.iter().map(|p| p.inner.clone()).collect(); + let id = cdk::wallet::types::TransactionId::from_proofs(cdk_proofs)?; + Ok(Self { + hex: id.to_string(), + }) + } +} + +impl From for TransactionId { + fn from(id: cdk::wallet::types::TransactionId) -> Self { + Self { + hex: id.to_string(), + } + } +} + +impl TryFrom for cdk::wallet::types::TransactionId { + type Error = FfiError; + + fn try_from(id: TransactionId) -> Result { + cdk::wallet::types::TransactionId::from_hex(&id.hex) + .map_err(|e| FfiError::InvalidHex { msg: e.to_string() }) + } +} + +/// FFI-compatible AuthProof +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct AuthProof { + /// Keyset ID + pub keyset_id: String, + /// Secret message + pub secret: String, + /// Unblinded signature (C) + pub c: String, + /// Y value (hash_to_curve of secret) + pub y: String, +} + +impl From for AuthProof { + fn from(auth_proof: cdk::nuts::AuthProof) -> Self { + Self { + keyset_id: auth_proof.keyset_id.to_string(), + secret: auth_proof.secret.to_string(), + c: auth_proof.c.to_string(), + y: auth_proof + .y() + .map(|y| y.to_string()) + .unwrap_or_else(|_| "".to_string()), + } + } +} + +impl TryFrom for cdk::nuts::AuthProof { + type Error = FfiError; + + fn try_from(auth_proof: AuthProof) -> Result { + use std::str::FromStr; + Ok(Self { + keyset_id: cdk::nuts::Id::from_str(&auth_proof.keyset_id) + .map_err(|e| FfiError::Serialization { msg: e.to_string() })?, + secret: { + use std::str::FromStr; + cdk::secret::Secret::from_str(&auth_proof.secret) + .map_err(|e| FfiError::Serialization { msg: e.to_string() })? + }, + c: cdk::nuts::PublicKey::from_str(&auth_proof.c) + .map_err(|e| FfiError::InvalidCryptographicKey { msg: e.to_string() })?, + dleq: None, // FFI doesn't expose DLEQ proofs for simplicity + }) + } +} + +impl AuthProof { + /// Convert AuthProof to JSON string + pub fn to_json(&self) -> Result { + Ok(serde_json::to_string(self)?) + } +} + +/// Decode AuthProof from JSON string +#[uniffi::export] +pub fn decode_auth_proof(json: String) -> Result { + Ok(serde_json::from_str(&json)?) +} + +/// Encode AuthProof to JSON string +#[uniffi::export] +pub fn encode_auth_proof(proof: AuthProof) -> Result { + Ok(serde_json::to_string(&proof)?) +} diff --git a/crates/cdk-ffi/src/types/wallet.rs b/crates/cdk-ffi/src/types/wallet.rs new file mode 100644 index 000000000..336ca7f51 --- /dev/null +++ b/crates/cdk-ffi/src/types/wallet.rs @@ -0,0 +1,471 @@ +//! Wallet-related FFI types + +use std::collections::HashMap; +use std::sync::Mutex; + +use serde::{Deserialize, Serialize}; + +use super::amount::{Amount, SplitTarget}; +use super::proof::{Proofs, SpendingConditions}; +use crate::error::FfiError; +use crate::token::Token; + +/// FFI-compatible SendMemo +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct SendMemo { + /// Memo text + pub memo: String, + /// Include memo in token + pub include_memo: bool, +} + +impl From for cdk::wallet::SendMemo { + fn from(memo: SendMemo) -> Self { + cdk::wallet::SendMemo { + memo: memo.memo, + include_memo: memo.include_memo, + } + } +} + +impl From for SendMemo { + fn from(memo: cdk::wallet::SendMemo) -> Self { + Self { + memo: memo.memo, + include_memo: memo.include_memo, + } + } +} + +impl SendMemo { + /// Convert SendMemo to JSON string + pub fn to_json(&self) -> Result { + Ok(serde_json::to_string(self)?) + } +} + +/// Decode SendMemo from JSON string +#[uniffi::export] +pub fn decode_send_memo(json: String) -> Result { + Ok(serde_json::from_str(&json)?) +} + +/// Encode SendMemo to JSON string +#[uniffi::export] +pub fn encode_send_memo(memo: SendMemo) -> Result { + Ok(serde_json::to_string(&memo)?) +} + +/// FFI-compatible SendKind +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Enum)] +pub enum SendKind { + /// Allow online swap before send if wallet does not have exact amount + OnlineExact, + /// Prefer offline send if difference is less than tolerance + OnlineTolerance { tolerance: Amount }, + /// Wallet cannot do an online swap and selected proof must be exactly send amount + OfflineExact, + /// Wallet must remain offline but can over pay if below tolerance + OfflineTolerance { tolerance: Amount }, +} + +impl From for cdk::wallet::SendKind { + fn from(kind: SendKind) -> Self { + match kind { + SendKind::OnlineExact => cdk::wallet::SendKind::OnlineExact, + SendKind::OnlineTolerance { tolerance } => { + cdk::wallet::SendKind::OnlineTolerance(tolerance.into()) + } + SendKind::OfflineExact => cdk::wallet::SendKind::OfflineExact, + SendKind::OfflineTolerance { tolerance } => { + cdk::wallet::SendKind::OfflineTolerance(tolerance.into()) + } + } + } +} + +impl From for SendKind { + fn from(kind: cdk::wallet::SendKind) -> Self { + match kind { + cdk::wallet::SendKind::OnlineExact => SendKind::OnlineExact, + cdk::wallet::SendKind::OnlineTolerance(tolerance) => SendKind::OnlineTolerance { + tolerance: tolerance.into(), + }, + cdk::wallet::SendKind::OfflineExact => SendKind::OfflineExact, + cdk::wallet::SendKind::OfflineTolerance(tolerance) => SendKind::OfflineTolerance { + tolerance: tolerance.into(), + }, + } + } +} + +/// FFI-compatible Send options +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct SendOptions { + /// Memo + pub memo: Option, + /// Spending conditions + pub conditions: Option, + /// Amount split target + pub amount_split_target: SplitTarget, + /// Send kind + pub send_kind: SendKind, + /// Include fee + pub include_fee: bool, + /// Maximum number of proofs to include in the token + pub max_proofs: Option, + /// Metadata + pub metadata: HashMap, +} + +impl Default for SendOptions { + fn default() -> Self { + Self { + memo: None, + conditions: None, + amount_split_target: SplitTarget::None, + send_kind: SendKind::OnlineExact, + include_fee: false, + max_proofs: None, + metadata: HashMap::new(), + } + } +} + +impl From for cdk::wallet::SendOptions { + fn from(opts: SendOptions) -> Self { + cdk::wallet::SendOptions { + memo: opts.memo.map(Into::into), + conditions: opts.conditions.and_then(|c| c.try_into().ok()), + amount_split_target: opts.amount_split_target.into(), + send_kind: opts.send_kind.into(), + include_fee: opts.include_fee, + max_proofs: opts.max_proofs.map(|p| p as usize), + metadata: opts.metadata, + } + } +} + +impl From for SendOptions { + fn from(opts: cdk::wallet::SendOptions) -> Self { + Self { + memo: opts.memo.map(Into::into), + conditions: opts.conditions.map(Into::into), + amount_split_target: opts.amount_split_target.into(), + send_kind: opts.send_kind.into(), + include_fee: opts.include_fee, + max_proofs: opts.max_proofs.map(|p| p as u32), + metadata: opts.metadata, + } + } +} + +impl SendOptions { + /// Convert SendOptions to JSON string + pub fn to_json(&self) -> Result { + Ok(serde_json::to_string(self)?) + } +} + +/// Decode SendOptions from JSON string +#[uniffi::export] +pub fn decode_send_options(json: String) -> Result { + Ok(serde_json::from_str(&json)?) +} + +/// Encode SendOptions to JSON string +#[uniffi::export] +pub fn encode_send_options(options: SendOptions) -> Result { + Ok(serde_json::to_string(&options)?) +} + +/// FFI-compatible SecretKey +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +#[serde(transparent)] +pub struct SecretKey { + /// Hex-encoded secret key (64 characters) + pub hex: String, +} + +impl SecretKey { + /// Create a new SecretKey from hex string + pub fn from_hex(hex: String) -> Result { + // Validate hex string length (should be 64 characters for 32 bytes) + if hex.len() != 64 { + return Err(FfiError::InvalidHex { + msg: "Secret key hex must be exactly 64 characters (32 bytes)".to_string(), + }); + } + + // Validate hex format + if !hex.chars().all(|c| c.is_ascii_hexdigit()) { + return Err(FfiError::InvalidHex { + msg: "Secret key hex contains invalid characters".to_string(), + }); + } + + Ok(Self { hex }) + } + + /// Generate a random secret key + pub fn random() -> Self { + use cdk::nuts::SecretKey as CdkSecretKey; + let secret_key = CdkSecretKey::generate(); + Self { + hex: secret_key.to_secret_hex(), + } + } +} + +impl From for cdk::nuts::SecretKey { + fn from(key: SecretKey) -> Self { + // This will panic if hex is invalid, but we validate in from_hex() + cdk::nuts::SecretKey::from_hex(&key.hex).expect("Invalid secret key hex") + } +} + +impl From for SecretKey { + fn from(key: cdk::nuts::SecretKey) -> Self { + Self { + hex: key.to_secret_hex(), + } + } +} + +/// FFI-compatible Receive options +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct ReceiveOptions { + /// Amount split target + pub amount_split_target: SplitTarget, + /// P2PK signing keys + pub p2pk_signing_keys: Vec, + /// Preimages for HTLC conditions + pub preimages: Vec, + /// Metadata + pub metadata: HashMap, +} + +impl Default for ReceiveOptions { + fn default() -> Self { + Self { + amount_split_target: SplitTarget::None, + p2pk_signing_keys: Vec::new(), + preimages: Vec::new(), + metadata: HashMap::new(), + } + } +} + +impl From for cdk::wallet::ReceiveOptions { + fn from(opts: ReceiveOptions) -> Self { + cdk::wallet::ReceiveOptions { + amount_split_target: opts.amount_split_target.into(), + p2pk_signing_keys: opts.p2pk_signing_keys.into_iter().map(Into::into).collect(), + preimages: opts.preimages, + metadata: opts.metadata, + } + } +} + +impl From for ReceiveOptions { + fn from(opts: cdk::wallet::ReceiveOptions) -> Self { + Self { + amount_split_target: opts.amount_split_target.into(), + p2pk_signing_keys: opts.p2pk_signing_keys.into_iter().map(Into::into).collect(), + preimages: opts.preimages, + metadata: opts.metadata, + } + } +} + +impl ReceiveOptions { + /// Convert ReceiveOptions to JSON string + pub fn to_json(&self) -> Result { + Ok(serde_json::to_string(self)?) + } +} + +/// Decode ReceiveOptions from JSON string +#[uniffi::export] +pub fn decode_receive_options(json: String) -> Result { + Ok(serde_json::from_str(&json)?) +} + +/// Encode ReceiveOptions to JSON string +#[uniffi::export] +pub fn encode_receive_options(options: ReceiveOptions) -> Result { + Ok(serde_json::to_string(&options)?) +} + +/// FFI-compatible PreparedSend +#[derive(Debug, uniffi::Object)] +pub struct PreparedSend { + inner: Mutex>, + id: String, + amount: Amount, + proofs: Proofs, +} + +impl From for PreparedSend { + fn from(prepared: cdk::wallet::PreparedSend) -> Self { + let id = format!("{:?}", prepared); // Use debug format as ID + let amount = prepared.amount().into(); + let proofs = prepared + .proofs() + .iter() + .cloned() + .map(|p| std::sync::Arc::new(p.into())) + .collect(); + Self { + inner: Mutex::new(Some(prepared)), + id, + amount, + proofs, + } + } +} + +#[uniffi::export(async_runtime = "tokio")] +impl PreparedSend { + /// Get the prepared send ID + pub fn id(&self) -> String { + self.id.clone() + } + + /// Get the amount to send + pub fn amount(&self) -> Amount { + self.amount + } + + /// Get the proofs that will be used + pub fn proofs(&self) -> Proofs { + self.proofs.clone() + } + + /// Get the total fee for this send operation + pub fn fee(&self) -> Amount { + if let Ok(guard) = self.inner.lock() { + if let Some(ref inner) = *guard { + inner.fee().into() + } else { + Amount::new(0) + } + } else { + Amount::new(0) + } + } + + /// Confirm the prepared send and create a token + pub async fn confirm( + self: std::sync::Arc, + memo: Option, + ) -> Result { + let inner = { + if let Ok(mut guard) = self.inner.lock() { + guard.take() + } else { + return Err(FfiError::Generic { + msg: "Failed to acquire lock on PreparedSend".to_string(), + }); + } + }; + + if let Some(inner) = inner { + let send_memo = memo.map(|m| cdk::wallet::SendMemo::for_token(&m)); + let token = inner.confirm(send_memo).await?; + Ok(token.into()) + } else { + Err(FfiError::Generic { + msg: "PreparedSend has already been consumed or cancelled".to_string(), + }) + } + } + + /// Cancel the prepared send operation + pub async fn cancel(self: std::sync::Arc) -> Result<(), FfiError> { + let inner = { + if let Ok(mut guard) = self.inner.lock() { + guard.take() + } else { + return Err(FfiError::Generic { + msg: "Failed to acquire lock on PreparedSend".to_string(), + }); + } + }; + + if let Some(inner) = inner { + inner.cancel().await?; + Ok(()) + } else { + Err(FfiError::Generic { + msg: "PreparedSend has already been consumed or cancelled".to_string(), + }) + } + } +} + +/// FFI-compatible Melted result +#[derive(Debug, Clone, uniffi::Record)] +pub struct Melted { + pub state: super::quote::QuoteState, + pub preimage: Option, + pub change: Option, + pub amount: Amount, + pub fee_paid: Amount, +} + +// MeltQuoteState is just an alias for nut05::QuoteState, so we don't need a separate implementation + +impl From for Melted { + fn from(melted: cdk::types::Melted) -> Self { + Self { + state: melted.state.into(), + preimage: melted.preimage, + change: melted.change.map(|proofs| { + proofs + .into_iter() + .map(|p| std::sync::Arc::new(p.into())) + .collect() + }), + amount: melted.amount.into(), + fee_paid: melted.fee_paid.into(), + } + } +} + +/// FFI-compatible MeltOptions +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Enum)] +pub enum MeltOptions { + /// MPP (Multi-Part Payments) options + Mpp { amount: Amount }, + /// Amountless options + Amountless { amount_msat: Amount }, +} + +impl From for cdk::nuts::MeltOptions { + fn from(opts: MeltOptions) -> Self { + match opts { + MeltOptions::Mpp { amount } => { + let cdk_amount: cdk::Amount = amount.into(); + cdk::nuts::MeltOptions::new_mpp(cdk_amount) + } + MeltOptions::Amountless { amount_msat } => { + let cdk_amount: cdk::Amount = amount_msat.into(); + cdk::nuts::MeltOptions::new_amountless(cdk_amount) + } + } + } +} + +impl From for MeltOptions { + fn from(opts: cdk::nuts::MeltOptions) -> Self { + match opts { + cdk::nuts::MeltOptions::Mpp { mpp } => MeltOptions::Mpp { + amount: mpp.amount.into(), + }, + cdk::nuts::MeltOptions::Amountless { amountless } => MeltOptions::Amountless { + amount_msat: amountless.amount_msat.into(), + }, + } + } +} From 1a493d61f821a044d1a82869a40f111413c61e8c Mon Sep 17 00:00:00 2001 From: vnprc <9425366+vnprc@users.noreply.github.com> Date: Mon, 6 Oct 2025 04:29:57 -0400 Subject: [PATCH 205/321] feat: optimize SQL balance calculation (#1152) * feat: optimize SQL balance calculation replace proof-fetching approach with SUM aggregation - add get_balance() method to Database trait - implement SQL SUM aggregation in cdk-sql-common - update total_balance() to use get_balance() instead of get_unspent_proofs() - redb impl maintains existing behavior --------- Co-authored-by: thesimplekid Co-authored-by: Cesar Rodas --- crates/cdk-common/src/database/wallet.rs | 7 +++ crates/cdk-ffi/src/database.rs | 24 +++++++++ crates/cdk-ffi/src/postgres.rs | 16 ++++++ crates/cdk-ffi/src/sqlite.rs | 16 ++++++ crates/cdk-redb/src/wallet/mod.rs | 12 +++++ crates/cdk-sql-common/src/wallet/mod.rs | 64 +++++++++++++++++++++++ crates/cdk/src/wallet/balance.rs | 12 ++++- crates/cdk/src/wallet/subscription/mod.rs | 1 - 8 files changed, 150 insertions(+), 2 deletions(-) diff --git a/crates/cdk-common/src/database/wallet.rs b/crates/cdk-common/src/database/wallet.rs index 0619ad386..8889b4710 100644 --- a/crates/cdk-common/src/database/wallet.rs +++ b/crates/cdk-common/src/database/wallet.rs @@ -96,6 +96,13 @@ pub trait Database: Debug { state: Option>, spending_conditions: Option>, ) -> Result, Self::Err>; + /// Get balance + async fn get_balance( + &self, + mint_url: Option, + unit: Option, + state: Option>, + ) -> Result; /// Update proofs state in storage async fn update_proofs_state(&self, ys: Vec, state: State) -> Result<(), Self::Err>; diff --git a/crates/cdk-ffi/src/database.rs b/crates/cdk-ffi/src/database.rs index 578681b66..cdf6eb572 100644 --- a/crates/cdk-ffi/src/database.rs +++ b/crates/cdk-ffi/src/database.rs @@ -109,6 +109,14 @@ pub trait WalletDatabase: Send + Sync { spending_conditions: Option>, ) -> Result, FfiError>; + /// Get balance efficiently using SQL aggregation + async fn get_balance( + &self, + mint_url: Option, + unit: Option, + state: Option>, + ) -> Result; + /// Update proofs state in storage async fn update_proofs_state( &self, @@ -465,6 +473,22 @@ impl CdkWalletDatabase for WalletDatabaseBridge { cdk_result } + async fn get_balance( + &self, + mint_url: Option, + unit: Option, + state: Option>, + ) -> Result { + let ffi_mint_url = mint_url.map(Into::into); + let ffi_unit = unit.map(Into::into); + let ffi_state = state.map(|s| s.into_iter().map(Into::into).collect()); + + self.ffi_db + .get_balance(ffi_mint_url, ffi_unit, ffi_state) + .await + .map_err(|e| cdk::cdk_database::Error::Database(e.to_string().into())) + } + async fn update_proofs_state( &self, ys: Vec, diff --git a/crates/cdk-ffi/src/postgres.rs b/crates/cdk-ffi/src/postgres.rs index f128b53f1..4c46a69bb 100644 --- a/crates/cdk-ffi/src/postgres.rs +++ b/crates/cdk-ffi/src/postgres.rs @@ -289,6 +289,22 @@ impl WalletDatabase for WalletPostgresDatabase { Ok(result.into_iter().map(Into::into).collect()) } + async fn get_balance( + &self, + mint_url: Option, + unit: Option, + state: Option>, + ) -> Result { + let cdk_mint_url = mint_url.map(|u| u.try_into()).transpose()?; + let cdk_unit = unit.map(Into::into); + let cdk_state = state.map(|s| s.into_iter().map(Into::into).collect()); + + self.inner + .get_balance(cdk_mint_url, cdk_unit, cdk_state) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + async fn update_proofs_state( &self, ys: Vec, diff --git a/crates/cdk-ffi/src/sqlite.rs b/crates/cdk-ffi/src/sqlite.rs index 8feae6e5b..b48bb36aa 100644 --- a/crates/cdk-ffi/src/sqlite.rs +++ b/crates/cdk-ffi/src/sqlite.rs @@ -324,6 +324,22 @@ impl WalletDatabase for WalletSqliteDatabase { Ok(result.into_iter().map(Into::into).collect()) } + async fn get_balance( + &self, + mint_url: Option, + unit: Option, + state: Option>, + ) -> Result { + let cdk_mint_url = mint_url.map(|u| u.try_into()).transpose()?; + let cdk_unit = unit.map(Into::into); + let cdk_state = state.map(|s| s.into_iter().map(Into::into).collect()); + + self.inner + .get_balance(cdk_mint_url, cdk_unit, cdk_state) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() }) + } + async fn update_proofs_state( &self, ys: Vec, diff --git a/crates/cdk-redb/src/wallet/mod.rs b/crates/cdk-redb/src/wallet/mod.rs index 37862fc2e..f25c712e2 100644 --- a/crates/cdk-redb/src/wallet/mod.rs +++ b/crates/cdk-redb/src/wallet/mod.rs @@ -721,6 +721,18 @@ impl WalletDatabase for WalletRedbDatabase { Ok(proofs) } + async fn get_balance( + &self, + mint_url: Option, + unit: Option, + state: Option>, + ) -> Result { + // For redb, we still need to fetch all proofs and sum them + // since redb doesn't have SQL aggregation + let proofs = self.get_proofs(mint_url, unit, state, None).await?; + Ok(proofs.iter().map(|p| u64::from(p.proof.amount)).sum()) + } + async fn update_proofs_state( &self, ys: Vec, diff --git a/crates/cdk-sql-common/src/wallet/mod.rs b/crates/cdk-sql-common/src/wallet/mod.rs index 8e2817d24..643716136 100644 --- a/crates/cdk-sql-common/src/wallet/mod.rs +++ b/crates/cdk-sql-common/src/wallet/mod.rs @@ -836,6 +836,70 @@ ON CONFLICT(id) DO UPDATE SET .collect::>()) } + async fn get_balance( + &self, + mint_url: Option, + unit: Option, + states: Option>, + ) -> Result { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; + + let mut query_str = "SELECT COALESCE(SUM(amount), 0) as total FROM proof".to_string(); + let mut where_clauses = Vec::new(); + let states = states + .unwrap_or_default() + .into_iter() + .map(|x| x.to_string()) + .collect::>(); + + if mint_url.is_some() { + where_clauses.push("mint_url = :mint_url"); + } + if unit.is_some() { + where_clauses.push("unit = :unit"); + } + if !states.is_empty() { + where_clauses.push("state IN (:states)"); + } + + if !where_clauses.is_empty() { + query_str.push_str(" WHERE "); + query_str.push_str(&where_clauses.join(" AND ")); + } + + let mut q = query(&query_str)?; + + if let Some(ref mint_url) = mint_url { + q = q.bind("mint_url", mint_url.to_string()); + } + if let Some(ref unit) = unit { + q = q.bind("unit", unit.to_string()); + } + + if !states.is_empty() { + q = q.bind_vec("states", states); + } + + let balance = q + .pluck(&*conn) + .await? + .map(|n| { + // SQLite SUM returns INTEGER which we need to convert to u64 + match n { + crate::stmt::Column::Integer(i) => Ok(i as u64), + crate::stmt::Column::Real(f) => Ok(f as u64), + _ => Err(Error::Database(Box::new(std::io::Error::new( + std::io::ErrorKind::InvalidData, + "Invalid balance type", + )))), + } + }) + .transpose()? + .unwrap_or(0); + + Ok(balance) + } + async fn update_proofs_state(&self, ys: Vec, state: State) -> Result<(), Self::Err> { let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; query("UPDATE proof SET state = :state WHERE y IN (:ys)")? diff --git a/crates/cdk/src/wallet/balance.rs b/crates/cdk/src/wallet/balance.rs index ce0951628..1f83002de 100644 --- a/crates/cdk/src/wallet/balance.rs +++ b/crates/cdk/src/wallet/balance.rs @@ -1,13 +1,23 @@ use tracing::instrument; use crate::nuts::nut00::ProofsMethods; +use crate::nuts::State; use crate::{Amount, Error, Wallet}; impl Wallet { /// Total unspent balance of wallet #[instrument(skip(self))] pub async fn total_balance(&self) -> Result { - Ok(self.get_unspent_proofs().await?.total_amount()?) + // Use the efficient balance query instead of fetching all proofs + let balance = self + .localstore + .get_balance( + Some(self.mint_url.clone()), + Some(self.unit.clone()), + Some(vec![State::Unspent]), + ) + .await?; + Ok(Amount::from(balance)) } /// Total pending balance diff --git a/crates/cdk/src/wallet/subscription/mod.rs b/crates/cdk/src/wallet/subscription/mod.rs index 692a6ad13..12143c382 100644 --- a/crates/cdk/src/wallet/subscription/mod.rs +++ b/crates/cdk/src/wallet/subscription/mod.rs @@ -12,7 +12,6 @@ use std::sync::Arc; use cdk_common::subscription::Params; use tokio::sync::{mpsc, RwLock}; use tokio::task::JoinHandle; -use tracing::error; #[cfg(target_arch = "wasm32")] use wasm_bindgen_futures; From c15a79f313317d21ce994721372f8250e1c37a32 Mon Sep 17 00:00:00 2001 From: tsk Date: Mon, 6 Oct 2025 10:40:16 +0200 Subject: [PATCH 206/321] chore: auto close stale (#1156) * chore: auto close stale issues and prs --- .github/workflows/autoclose.yml | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 .github/workflows/autoclose.yml diff --git a/.github/workflows/autoclose.yml b/.github/workflows/autoclose.yml new file mode 100644 index 000000000..9939fc97e --- /dev/null +++ b/.github/workflows/autoclose.yml @@ -0,0 +1,27 @@ +name: Close inactive issues and PRs +on: + schedule: + - cron: "30 1 * * *" + +jobs: + close-issues: + runs-on: ubuntu-latest + permissions: + issues: write + pull-requests: write + steps: + - uses: actions/stale@v10 + with: + days-before-issue-stale: 60 + days-before-issue-close: 21 + stale-issue-label: "stale" + stale-issue-message: "This issue is stale because it has been open for 60 days with no activity." + close-issue-message: "This issue was closed because it has been inactive for 21 days since being marked as stale." + days-before-pr-stale: 60 + days-before-pr-close: 21 + stale-pr-label: "stale" + stale-pr-message: "This PR is stale because it has been open for 60 days with no activity." + close-pr-message: "This PR was closed because it has been inactive for 21 days since being marked as stale." + exempt-issue-labels: "keep-open" + exempt-pr-labels: "keep-open" + repo-token: ${{ secrets.GITHUB_TOKEN }} From c5e5d71701a837418463a3b8fb04e02d57d0b13a Mon Sep 17 00:00:00 2001 From: tsk Date: Mon, 6 Oct 2025 14:40:21 +0200 Subject: [PATCH 207/321] feat(cdk): add payment request and proof to transaction records (#1155) Add payment_request and payment_proof fields to Transaction model to store Lightning invoice details and payment preimages. Update database migrations and all transaction creation points across wallet operations (mint, melt, send, receive) to populate these fields. --- crates/cdk-common/src/wallet.rs | 4 ++++ crates/cdk-ffi/src/types/transaction.rs | 8 +++++++ ...20000_add_payment_info_to_transactions.sql | 3 +++ ...20000_add_payment_info_to_transactions.sql | 3 +++ crates/cdk-sql-common/src/wallet/mod.rs | 24 ++++++++++++++----- crates/cdk/src/wallet/issue/issue_bolt11.rs | 2 ++ crates/cdk/src/wallet/issue/issue_bolt12.rs | 2 ++ crates/cdk/src/wallet/melt/melt_bolt11.rs | 6 ++++- crates/cdk/src/wallet/melt/mod.rs | 3 +++ crates/cdk/src/wallet/receive.rs | 4 +++- crates/cdk/src/wallet/send.rs | 4 +++- 11 files changed, 54 insertions(+), 9 deletions(-) create mode 100644 crates/cdk-sql-common/src/wallet/migrations/postgres/20251005120000_add_payment_info_to_transactions.sql create mode 100644 crates/cdk-sql-common/src/wallet/migrations/sqlite/20251005120000_add_payment_info_to_transactions.sql diff --git a/crates/cdk-common/src/wallet.rs b/crates/cdk-common/src/wallet.rs index a03d48f25..cf2a5a17f 100644 --- a/crates/cdk-common/src/wallet.rs +++ b/crates/cdk-common/src/wallet.rs @@ -204,6 +204,10 @@ pub struct Transaction { pub metadata: HashMap, /// Quote ID if this is a mint or melt transaction pub quote_id: Option, + /// Payment request (e.g., BOLT11 invoice, BOLT12 offer) + pub payment_request: Option, + /// Payment proof (e.g., preimage for Lightning melt transactions) + pub payment_proof: Option, } impl Transaction { diff --git a/crates/cdk-ffi/src/types/transaction.rs b/crates/cdk-ffi/src/types/transaction.rs index 9291c778f..9c70c35d9 100644 --- a/crates/cdk-ffi/src/types/transaction.rs +++ b/crates/cdk-ffi/src/types/transaction.rs @@ -35,6 +35,10 @@ pub struct Transaction { pub metadata: HashMap, /// Quote ID if this is a mint or melt transaction pub quote_id: Option, + /// Payment request (e.g., BOLT11 invoice, BOLT12 offer) + pub payment_request: Option, + /// Payment proof (e.g., preimage for Lightning melt transactions) + pub payment_proof: Option, } impl From for Transaction { @@ -51,6 +55,8 @@ impl From for Transaction { memo: tx.memo, metadata: tx.metadata, quote_id: tx.quote_id, + payment_request: tx.payment_request, + payment_proof: tx.payment_proof, } } } @@ -75,6 +81,8 @@ impl TryFrom for cdk::wallet::types::Transaction { memo: tx.memo, metadata: tx.metadata, quote_id: tx.quote_id, + payment_request: tx.payment_request, + payment_proof: tx.payment_proof, }) } } diff --git a/crates/cdk-sql-common/src/wallet/migrations/postgres/20251005120000_add_payment_info_to_transactions.sql b/crates/cdk-sql-common/src/wallet/migrations/postgres/20251005120000_add_payment_info_to_transactions.sql new file mode 100644 index 000000000..1b3b933de --- /dev/null +++ b/crates/cdk-sql-common/src/wallet/migrations/postgres/20251005120000_add_payment_info_to_transactions.sql @@ -0,0 +1,3 @@ +-- Add payment_request and payment_proof to transactions table +ALTER TABLE transactions ADD COLUMN payment_request TEXT; +ALTER TABLE transactions ADD COLUMN payment_proof TEXT; diff --git a/crates/cdk-sql-common/src/wallet/migrations/sqlite/20251005120000_add_payment_info_to_transactions.sql b/crates/cdk-sql-common/src/wallet/migrations/sqlite/20251005120000_add_payment_info_to_transactions.sql new file mode 100644 index 000000000..1b3b933de --- /dev/null +++ b/crates/cdk-sql-common/src/wallet/migrations/sqlite/20251005120000_add_payment_info_to_transactions.sql @@ -0,0 +1,3 @@ +-- Add payment_request and payment_proof to transactions table +ALTER TABLE transactions ADD COLUMN payment_request TEXT; +ALTER TABLE transactions ADD COLUMN payment_proof TEXT; diff --git a/crates/cdk-sql-common/src/wallet/mod.rs b/crates/cdk-sql-common/src/wallet/mod.rs index 643716136..fd91ea683 100644 --- a/crates/cdk-sql-common/src/wallet/mod.rs +++ b/crates/cdk-sql-common/src/wallet/mod.rs @@ -969,9 +969,9 @@ ON CONFLICT(id) DO UPDATE SET query( r#" INSERT INTO transactions -(id, mint_url, direction, unit, amount, fee, ys, timestamp, memo, metadata, quote_id) +(id, mint_url, direction, unit, amount, fee, ys, timestamp, memo, metadata, quote_id, payment_request, payment_proof) VALUES -(:id, :mint_url, :direction, :unit, :amount, :fee, :ys, :timestamp, :memo, :metadata, :quote_id) +(:id, :mint_url, :direction, :unit, :amount, :fee, :ys, :timestamp, :memo, :metadata, :quote_id, :payment_request, :payment_proof) ON CONFLICT(id) DO UPDATE SET mint_url = excluded.mint_url, direction = excluded.direction, @@ -982,7 +982,9 @@ ON CONFLICT(id) DO UPDATE SET timestamp = excluded.timestamp, memo = excluded.memo, metadata = excluded.metadata, - quote_id = excluded.quote_id + quote_id = excluded.quote_id, + payment_request = excluded.payment_request, + payment_proof = excluded.payment_proof ; "#, )? @@ -1000,6 +1002,8 @@ ON CONFLICT(id) DO UPDATE SET serde_json::to_string(&transaction.metadata).map_err(Error::from)?, ) .bind("quote_id", transaction.quote_id) + .bind("payment_request", transaction.payment_request) + .bind("payment_proof", transaction.payment_proof) .execute(&*conn) .await?; @@ -1024,7 +1028,9 @@ ON CONFLICT(id) DO UPDATE SET timestamp, memo, metadata, - quote_id + quote_id, + payment_request, + payment_proof FROM transactions WHERE @@ -1059,7 +1065,9 @@ ON CONFLICT(id) DO UPDATE SET timestamp, memo, metadata, - quote_id + quote_id, + payment_request, + payment_proof FROM transactions "#, @@ -1297,7 +1305,9 @@ fn sql_row_to_transaction(row: Vec) -> Result { timestamp, memo, metadata, - quote_id + quote_id, + payment_request, + payment_proof ) = row ); @@ -1321,5 +1331,7 @@ fn sql_row_to_transaction(row: Vec) -> Result { }) .unwrap_or_default(), quote_id: column_as_nullable_string!(quote_id), + payment_request: column_as_nullable_string!(payment_request), + payment_proof: column_as_nullable_string!(payment_proof), }) } diff --git a/crates/cdk/src/wallet/issue/issue_bolt11.rs b/crates/cdk/src/wallet/issue/issue_bolt11.rs index 98ac37805..935c7602d 100644 --- a/crates/cdk/src/wallet/issue/issue_bolt11.rs +++ b/crates/cdk/src/wallet/issue/issue_bolt11.rs @@ -329,6 +329,8 @@ impl Wallet { memo: None, metadata: HashMap::new(), quote_id: Some(quote_id.to_string()), + payment_request: Some(quote_info.request), + payment_proof: None, }) .await?; diff --git a/crates/cdk/src/wallet/issue/issue_bolt12.rs b/crates/cdk/src/wallet/issue/issue_bolt12.rs index 470f25827..fd8dc10f9 100644 --- a/crates/cdk/src/wallet/issue/issue_bolt12.rs +++ b/crates/cdk/src/wallet/issue/issue_bolt12.rs @@ -232,6 +232,8 @@ impl Wallet { memo: None, metadata: HashMap::new(), quote_id: Some(quote_id.to_string()), + payment_request: Some(quote_info.request), + payment_proof: None, }) .await?; diff --git a/crates/cdk/src/wallet/melt/melt_bolt11.rs b/crates/cdk/src/wallet/melt/melt_bolt11.rs index 96a3f12f9..58b23353a 100644 --- a/crates/cdk/src/wallet/melt/melt_bolt11.rs +++ b/crates/cdk/src/wallet/melt/melt_bolt11.rs @@ -54,7 +54,7 @@ impl Wallet { let invoice = Bolt11Invoice::from_str(&request)?; let quote_request = MeltQuoteBolt11Request { - request: Bolt11Invoice::from_str(&request)?, + request: invoice.clone(), unit: self.unit.clone(), options, }; @@ -248,6 +248,8 @@ impl Wallet { None => None, }; + let payment_preimage = melt_response.payment_preimage.clone(); + let melted = Melted::from_proofs( melt_response.state, melt_response.payment_preimage, @@ -298,6 +300,8 @@ impl Wallet { memo: None, metadata, quote_id: Some(quote_id.to_string()), + payment_request: Some(quote_info.request), + payment_proof: payment_preimage, }) .await?; diff --git a/crates/cdk/src/wallet/melt/mod.rs b/crates/cdk/src/wallet/melt/mod.rs index 24db4629b..c56d18eb4 100644 --- a/crates/cdk/src/wallet/melt/mod.rs +++ b/crates/cdk/src/wallet/melt/mod.rs @@ -60,6 +60,7 @@ impl Wallet { let pending_proofs = self.get_pending_proofs().await?; let proofs_total = pending_proofs.total_amount().unwrap_or_default(); let change_total = response.change_amount().unwrap_or_default(); + self.localstore .add_transaction(Transaction { mint_url: self.mint_url.clone(), @@ -75,6 +76,8 @@ impl Wallet { memo: None, metadata: HashMap::new(), quote_id: Some(quote.id.clone()), + payment_request: Some(quote.request.clone()), + payment_proof: response.payment_preimage.clone(), }) .await?; } diff --git a/crates/cdk/src/wallet/receive.rs b/crates/cdk/src/wallet/receive.rs index 2d0334b4f..b5fc2c8f9 100644 --- a/crates/cdk/src/wallet/receive.rs +++ b/crates/cdk/src/wallet/receive.rs @@ -167,7 +167,9 @@ impl Wallet { timestamp: unix_time(), memo, metadata: opts.metadata, - quote_id: None, // Receive transactions don't have a quote_id + quote_id: None, + payment_request: None, + payment_proof: None, }) .await?; diff --git a/crates/cdk/src/wallet/send.rs b/crates/cdk/src/wallet/send.rs index 0f41f8e96..6b4d41235 100644 --- a/crates/cdk/src/wallet/send.rs +++ b/crates/cdk/src/wallet/send.rs @@ -350,7 +350,9 @@ impl PreparedSend { timestamp: unix_time(), memo: memo.clone(), metadata: self.options.metadata, - quote_id: None, // Send transactions don't have a quote_id + quote_id: None, + payment_request: None, + payment_proof: None, }) .await?; From 03309da7c6b31a8b287c1fce98588cc1d14fe321 Mon Sep 17 00:00:00 2001 From: daywalker90 <8257956+daywalker90@users.noreply.github.com> Date: Mon, 6 Oct 2025 19:39:08 +0200 Subject: [PATCH 208/321] mintd: remove non-existent stdout logging from docs (#1159) --- crates/cdk-mintd/example.config.toml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/crates/cdk-mintd/example.config.toml b/crates/cdk-mintd/example.config.toml index c65105396..1dd627606 100644 --- a/crates/cdk-mintd/example.config.toml +++ b/crates/cdk-mintd/example.config.toml @@ -14,8 +14,7 @@ melt_ttl = 120 [info.logging] -# Where to output logs: "stdout", "file", or "both" (default: "both") -# Note: "stdout" actually outputs to stderr (standard error stream) +# Where to output logs: "stderr" (standard error stream), "file", or "both" (default: "both") # output = "both" # Log level for console output (default: "info") # console_level = "info" From b43d2ae26e2a09fdfbd0369ecafb934cfa2a7a7c Mon Sep 17 00:00:00 2001 From: tsk Date: Mon, 6 Oct 2025 19:39:48 +0200 Subject: [PATCH 209/321] chore: update ci to fail fast (#1157) --- .github/workflows/ci.yml | 26 ++++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ecec7efa5..6d1e848c0 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -43,6 +43,7 @@ jobs: timeout-minutes: 30 needs: pre-commit-checks strategy: + fail-fast: true matrix: build-args: [ @@ -72,6 +73,7 @@ jobs: timeout-minutes: 30 needs: pre-commit-checks strategy: + fail-fast: true matrix: build-args: [ @@ -165,8 +167,9 @@ jobs: name: "Integration regtest tests" runs-on: ubuntu-latest timeout-minutes: 30 - needs: [pre-commit-checks, clippy, pure-itest, fake-mint-itest] + needs: pre-commit-checks strategy: + fail-fast: true matrix: build-args: [ @@ -205,8 +208,9 @@ jobs: name: "Integration fake mint tests" runs-on: ubuntu-latest timeout-minutes: 30 - needs: [pre-commit-checks, clippy] + needs: pre-commit-checks strategy: + fail-fast: true matrix: build-args: [ @@ -246,8 +250,9 @@ jobs: name: "Integration fake wallet tests" runs-on: ubuntu-latest timeout-minutes: 30 - needs: [pre-commit-checks, clippy] + needs: pre-commit-checks strategy: + fail-fast: true matrix: database: [ @@ -288,8 +293,9 @@ jobs: name: "Payment processor tests" runs-on: ubuntu-latest timeout-minutes: 30 - needs: [pre-commit-checks, clippy, pure-itest, fake-mint-itest, regtest-itest] + needs: pre-commit-checks strategy: + fail-fast: true matrix: ln: [ @@ -325,8 +331,9 @@ jobs: name: "MSRV build" runs-on: ubuntu-latest timeout-minutes: 30 - needs: [pre-commit-checks, clippy] + needs: pre-commit-checks strategy: + fail-fast: true matrix: build-args: [ @@ -367,8 +374,9 @@ jobs: name: Check WASM runs-on: ubuntu-latest timeout-minutes: 30 - needs: [pre-commit-checks, clippy] + needs: pre-commit-checks strategy: + fail-fast: true matrix: rust: - stable @@ -399,8 +407,9 @@ jobs: name: Check WASM runs-on: ubuntu-latest timeout-minutes: 30 - needs: [pre-commit-checks, clippy, msrv-build] + needs: pre-commit-checks strategy: + fail-fast: true matrix: rust: - msrv @@ -430,8 +439,9 @@ jobs: name: "Integration fake mint auth tests" runs-on: ubuntu-latest timeout-minutes: 30 - needs: [pre-commit-checks, clippy, pure-itest, fake-mint-itest] + needs: pre-commit-checks strategy: + fail-fast: true matrix: database: [ From c30a078a12be3e9e2e6cb5906dc31c51851586ef Mon Sep 17 00:00:00 2001 From: tsk Date: Mon, 6 Oct 2025 20:21:48 +0200 Subject: [PATCH 210/321] fix(cashu): skip serializing empty NUT15 settings in mint info (#1158) Add is_empty method to nut15::Settings and configure skip_serializing_if attribute to prevent empty NUT15 objects from appearing in serialized mint info responses. --- crates/cashu/src/nuts/nut06.rs | 35 ++++++++++++++++++++++++++++++++++ crates/cashu/src/nuts/nut15.rs | 21 ++++++++++++++++++++ 2 files changed, 56 insertions(+) diff --git a/crates/cashu/src/nuts/nut06.rs b/crates/cashu/src/nuts/nut06.rs index 2ec993aa8..51e04d77f 100644 --- a/crates/cashu/src/nuts/nut06.rs +++ b/crates/cashu/src/nuts/nut06.rs @@ -313,6 +313,7 @@ pub struct Nuts { /// NUT15 Settings #[serde(default)] #[serde(rename = "15")] + #[serde(skip_serializing_if = "nut15::Settings::is_empty")] pub nut15: nut15::Settings, /// NUT17 Settings #[serde(default)] @@ -676,4 +677,38 @@ mod tests { assert_eq!(info, mint_info); } + + #[test] + fn test_nut15_not_serialized_when_empty() { + // Test with default (empty) NUT15 + let mint_info = MintInfo { + name: Some("Test Mint".to_string()), + nuts: Nuts::default(), + ..Default::default() + }; + + let json = serde_json::to_string(&mint_info).unwrap(); + let parsed: serde_json::Value = serde_json::from_str(&json).unwrap(); + + // NUT15 should not be present in the nuts object when methods is empty + assert!(parsed["nuts"]["15"].is_null()); + + // Test with non-empty NUT15 + let mint_info_with_nut15 = MintInfo { + name: Some("Test Mint".to_string()), + nuts: Nuts::default().nut15(vec![MppMethodSettings { + method: crate::PaymentMethod::Bolt11, + unit: crate::CurrencyUnit::Sat, + }]), + ..Default::default() + }; + + let json = serde_json::to_string(&mint_info_with_nut15).unwrap(); + let parsed: serde_json::Value = serde_json::from_str(&json).unwrap(); + + // NUT15 should be present when methods is not empty + assert!(!parsed["nuts"]["15"].is_null()); + assert!(parsed["nuts"]["15"]["methods"].is_array()); + assert_eq!(parsed["nuts"]["15"]["methods"].as_array().unwrap().len(), 1); + } } diff --git a/crates/cashu/src/nuts/nut15.rs b/crates/cashu/src/nuts/nut15.rs index d3fb5a825..b5b5c5508 100644 --- a/crates/cashu/src/nuts/nut15.rs +++ b/crates/cashu/src/nuts/nut15.rs @@ -34,6 +34,13 @@ pub struct Settings { pub methods: Vec, } +impl Settings { + /// Check if methods is empty + pub fn is_empty(&self) -> bool { + self.methods.is_empty() + } +} + // Custom deserialization to handle both array and object formats impl<'de> Deserialize<'de> for Settings { fn deserialize(deserializer: D) -> Result @@ -89,4 +96,18 @@ mod tests { let json = serde_json::to_string(&settings).unwrap(); assert_eq!(json, r#"{"methods":[{"method":"bolt11","unit":"sat"}]}"#); } + + #[test] + fn test_nut15_settings_empty() { + let settings = Settings { methods: vec![] }; + assert!(settings.is_empty()); + + let settings_with_data = Settings { + methods: vec![MppMethodSettings { + method: PaymentMethod::Bolt11, + unit: CurrencyUnit::Sat, + }], + }; + assert!(!settings_with_data.is_empty()); + } } From 6fe65553a309869f7c107847ef785abc4f96ae91 Mon Sep 17 00:00:00 2001 From: tsk Date: Tue, 7 Oct 2025 15:19:14 +0200 Subject: [PATCH 211/321] fix(database): add parent directory validation before database creation (#1161) - Add work directory creation check in cdk-cli main - Add parent directory existence validation in cdk-redb wallet database - Add parent directory check in cdk-sqlite connection manager - Add IO error variant to cdk-redb error types for better error handling --- crates/cdk-cli/src/main.rs | 5 +++++ crates/cdk-redb/src/error.rs | 3 +++ crates/cdk-redb/src/wallet/mod.rs | 20 ++++++++++++++++++++ crates/cdk-sqlite/src/common.rs | 9 +++++++++ 4 files changed, 37 insertions(+) diff --git a/crates/cdk-cli/src/main.rs b/crates/cdk-cli/src/main.rs index 01394a9e8..3cc75141d 100644 --- a/crates/cdk-cli/src/main.rs +++ b/crates/cdk-cli/src/main.rs @@ -131,6 +131,11 @@ async fn main() -> Result<()> { } }; + // Create work directory if it doesn't exist + if !work_dir.exists() { + fs::create_dir_all(&work_dir)?; + } + let localstore: Arc + Send + Sync> = match args.engine.as_str() { "sqlite" => { diff --git a/crates/cdk-redb/src/error.rs b/crates/cdk-redb/src/error.rs index 195e024bf..2964280f5 100644 --- a/crates/cdk-redb/src/error.rs +++ b/crates/cdk-redb/src/error.rs @@ -43,6 +43,9 @@ pub enum Error { /// CDK Error #[error(transparent)] CDK(#[from] cdk_common::error::Error), + /// IO Error + #[error(transparent)] + Io(#[from] std::io::Error), /// NUT00 Error #[error(transparent)] CDKNUT00(#[from] cdk_common::nuts::nut00::Error), diff --git a/crates/cdk-redb/src/wallet/mod.rs b/crates/cdk-redb/src/wallet/mod.rs index f25c712e2..44c4cce02 100644 --- a/crates/cdk-redb/src/wallet/mod.rs +++ b/crates/cdk-redb/src/wallet/mod.rs @@ -58,6 +58,16 @@ impl WalletRedbDatabase { /// Create new [`WalletRedbDatabase`] pub fn new(path: &Path) -> Result { { + // Check if parent directory exists before attempting to create database + if let Some(parent) = path.parent() { + if !parent.exists() { + return Err(Error::Io(std::io::Error::new( + std::io::ErrorKind::NotFound, + format!("Parent directory does not exist: {:?}", parent), + ))); + } + } + let db = Arc::new(Database::create(path)?); let db_version: Option; @@ -156,6 +166,16 @@ impl WalletRedbDatabase { drop(db); } + // Check parent directory again for final database creation + if let Some(parent) = path.parent() { + if !parent.exists() { + return Err(Error::Io(std::io::Error::new( + std::io::ErrorKind::NotFound, + format!("Parent directory does not exist: {:?}", parent), + ))); + } + } + let mut db = Database::create(path)?; db.upgrade()?; diff --git a/crates/cdk-sqlite/src/common.rs b/crates/cdk-sqlite/src/common.rs index d00bfaf6c..178f554ef 100644 --- a/crates/cdk-sqlite/src/common.rs +++ b/crates/cdk-sqlite/src/common.rs @@ -47,6 +47,15 @@ impl DatabasePool for SqliteConnectionManager { _timeout: Duration, ) -> Result> { let conn = if let Some(path) = config.path.as_ref() { + // Check if parent directory exists before attempting to open database + let path_buf = PathBuf::from(path); + if let Some(parent) = path_buf.parent() { + if !parent.exists() { + return Err(pool::Error::Resource(rusqlite::Error::InvalidPath( + path_buf.clone(), + ))); + } + } Connection::open(path)? } else { Connection::open_in_memory()? From cdd59359b927181ce2fc3472ed6e3d038a5656b7 Mon Sep 17 00:00:00 2001 From: C Date: Wed, 8 Oct 2025 05:33:45 -0300 Subject: [PATCH 212/321] Introduce a generic pubsub mod in `cdk-common` (#1098) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * pubsub: consolidate into Spec, adopt Arc, and wire through wallet/mint/WS/FFI Refactor the pub/sub engine to a single Spec trait, move Event alongside it, and propagate Arc-backed subscription IDs across the stack. This simplifies generics, clarifies responsibilities, and preserves coalescing + latest-on-subscribe semantics. - **Single source of truth:** `Spec` owns `Topic`, `Event`, `SubscriptionId`, `Context`, new_instance, and fetch_events. - **Lean & explicit API:** Remove Topic trait split; `Subscriber::send(Event)` carries sub-ID internally. - **Performance/ergonomics:** `Arc` avoids heavy clones and makes channel/task hops trivial. - Introduce `pub_sub/typ.rs` with: - trait `Spec` - trait `Event` colocated with Spec. - Remove `pub_sub/event.rs` fold `Event` into `typ.rs`. - Make `Pubsub` generic over `Spec` and store `Arc`. - The subscriber holds `Arc` and deduplicates the latest entry per subscription. - SubscriptionRequest: rename SubscriptionName → SubscriptionId; return `Arc<...>` from `subscription_name()`. - Remote consumer (Transport) now parameterized by `Spec`; control types updated: - `StreamCtrl`, `SubscribeMessage`, internal caches keyed by `S::Topic`. - Mint/wallet: - Mint: `MintPubSubSpec` (Context = `DynMintDatabase`), `PubSubManager(Pubsub)`. - Wallet: lightweight MintSubTopics Spec with `Context = ()`. - IDs go Arc end-to-end: - cdk-axum WS maps `HashMap, JoinHandle<()>>`, publisher sends `(Arc, NotificationPayload)`. - `subscription::{Params, WalletParams}` now use `Arc<...>`. - cdk-ffi conversions & wallet glue updated. - Integration tests updated for new types. - Coalescing unchanged: multiple local subs to the same topic are combined into a single remote sub. - Backfill via `Spec::fetch_events(topics, Subscriber)`; Subscriber enforces latest-only dedupe per subscription. **Result:** a slimmer, more maintainable pub/sub core that’s easier to embed across mint, wallet, transports, and FFI without sacrificing performance or semantics. --------- Co-authored-by: thesimplekid --- .github/workflows/ci.yml | 10 + Cargo.toml | 2 +- crates/cashu/Cargo.toml | 4 +- crates/cashu/src/lib.rs | 1 - crates/cashu/src/nuts/nut17/mod.rs | 50 +- crates/cashu/src/nuts/nut17/ws.rs | 5 +- crates/cdk-axum/src/ws/mod.rs | 7 +- crates/cdk-axum/src/ws/subscribe.rs | 10 +- crates/cdk-common/Cargo.toml | 6 + crates/cdk-common/src/lib.rs | 2 + crates/cdk-common/src/pub_sub/error.rs | 44 + crates/cdk-common/src/pub_sub/index.rs | 161 ---- crates/cdk-common/src/pub_sub/mod.rs | 227 +++-- crates/cdk-common/src/pub_sub/pubsub.rs | 185 ++++ .../cdk-common/src/pub_sub/remote_consumer.rs | 885 ++++++++++++++++++ crates/cdk-common/src/pub_sub/subscriber.rs | 159 ++++ crates/cdk-common/src/pub_sub/types.rs | 80 ++ crates/cdk-common/src/subscription.rs | 165 ++-- crates/cdk-common/src/ws.rs | 4 +- crates/cdk-ffi/Cargo.toml | 3 +- crates/cdk-ffi/src/types/subscription.rs | 32 +- crates/cdk-ffi/src/wallet.rs | 2 +- .../tests/integration_tests_pure.rs | 24 +- crates/cdk-integration-tests/tests/regtest.rs | 4 +- crates/cdk/Cargo.toml | 2 - crates/cdk/src/event.rs | 127 +++ crates/cdk/src/lib.rs | 17 +- crates/cdk/src/mint/issue/mod.rs | 4 +- crates/cdk/src/mint/mod.rs | 4 +- crates/cdk/src/mint/subscription.rs | 244 +++++ crates/cdk/src/mint/subscription/manager.rs | 292 ------ crates/cdk/src/mint/subscription/mod.rs | 12 - .../src/mint/subscription/on_subscription.rs | 119 --- crates/cdk/src/pub_sub.rs | 339 ------- crates/cdk/src/wallet/mod.rs | 42 +- crates/cdk/src/wallet/multi_mint_wallet.rs | 5 +- crates/cdk/src/wallet/streams/payment.rs | 5 +- crates/cdk/src/wallet/subscription/http.rs | 238 ----- crates/cdk/src/wallet/subscription/mod.rs | 501 +++++----- crates/cdk/src/wallet/subscription/ws.rs | 356 +++---- justfile | 4 +- 41 files changed, 2457 insertions(+), 1926 deletions(-) create mode 100644 crates/cdk-common/src/pub_sub/error.rs delete mode 100644 crates/cdk-common/src/pub_sub/index.rs create mode 100644 crates/cdk-common/src/pub_sub/pubsub.rs create mode 100644 crates/cdk-common/src/pub_sub/remote_consumer.rs create mode 100644 crates/cdk-common/src/pub_sub/subscriber.rs create mode 100644 crates/cdk-common/src/pub_sub/types.rs create mode 100644 crates/cdk/src/event.rs create mode 100644 crates/cdk/src/mint/subscription.rs delete mode 100644 crates/cdk/src/mint/subscription/manager.rs delete mode 100644 crates/cdk/src/mint/subscription/mod.rs delete mode 100644 crates/cdk/src/mint/subscription/on_subscription.rs delete mode 100644 crates/cdk/src/pub_sub.rs delete mode 100644 crates/cdk/src/wallet/subscription/http.rs diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6d1e848c0..b2ea54388 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -490,6 +490,16 @@ jobs: steps: - name: checkout uses: actions/checkout@v4 + - name: Free Disk Space (Ubuntu) + uses: jlumbroso/free-disk-space@main + with: + tool-cache: false + android: true + dotnet: true + haskell: true + large-packages: true + docker-images: true + swap-storage: true - name: Install Nix uses: DeterminateSystems/nix-installer-action@v17 - name: Nix Cache diff --git a/Cargo.toml b/Cargo.toml index 9b8a6afb3..d325d8516 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -70,7 +70,7 @@ futures = { version = "0.3.28", default-features = false, features = ["async-awa lightning-invoice = { version = "0.33.0", features = ["serde", "std"] } lightning = { version = "0.1.2", default-features = false, features = ["std"]} ldk-node = "0.6.2" -serde = { version = "1", features = ["derive"] } +serde = { version = "1", features = ["derive", "rc"] } serde_json = "1" thiserror = { version = "2" } tokio = { version = "1", default-features = false, features = ["rt", "macros", "test-util", "sync"] } diff --git a/crates/cashu/Cargo.toml b/crates/cashu/Cargo.toml index affd6f52f..830b39573 100644 --- a/crates/cashu/Cargo.toml +++ b/crates/cashu/Cargo.toml @@ -13,13 +13,13 @@ readme = "README.md" [features] default = ["mint", "wallet", "auth"] swagger = ["dep:utoipa"] -mint = ["dep:uuid"] +mint = [] wallet = [] auth = ["dep:strum", "dep:strum_macros", "dep:regex"] bench = [] [dependencies] -uuid = { workspace = true, optional = true } +uuid.workspace = true bitcoin.workspace = true cbor-diag.workspace = true ciborium.workspace = true diff --git a/crates/cashu/src/lib.rs b/crates/cashu/src/lib.rs index 4b1877c72..07733e523 100644 --- a/crates/cashu/src/lib.rs +++ b/crates/cashu/src/lib.rs @@ -16,7 +16,6 @@ pub use self::mint_url::MintUrl; pub use self::nuts::*; pub use self::util::SECP256K1; -#[cfg(feature = "mint")] pub mod quote_id; #[doc(hidden)] diff --git a/crates/cashu/src/nuts/nut17/mod.rs b/crates/cashu/src/nuts/nut17/mod.rs index d12960bc1..eb05926c5 100644 --- a/crates/cashu/src/nuts/nut17/mod.rs +++ b/crates/cashu/src/nuts/nut17/mod.rs @@ -2,13 +2,11 @@ use serde::de::DeserializeOwned; use serde::{Deserialize, Serialize}; -#[cfg(feature = "mint")] use super::PublicKey; use crate::nuts::{ CurrencyUnit, MeltQuoteBolt11Response, MintQuoteBolt11Response, PaymentMethod, ProofState, }; -#[cfg(feature = "mint")] -use crate::quote_id::{QuoteId, QuoteIdError}; +use crate::quote_id::QuoteIdError; use crate::MintQuoteBolt12Response; pub mod ws; @@ -109,7 +107,10 @@ pub enum WsCommand { ProofState, } -impl From> for NotificationPayload { +impl From> for NotificationPayload +where + T: Clone, +{ fn from(mint_quote: MintQuoteBolt12Response) -> NotificationPayload { NotificationPayload::MintQuoteBolt12Response(mint_quote) } @@ -119,7 +120,10 @@ impl From> for NotificationPayload { #[serde(bound = "T: Serialize + DeserializeOwned")] #[serde(untagged)] /// Subscription response -pub enum NotificationPayload { +pub enum NotificationPayload +where + T: Clone, +{ /// Proof State ProofState(ProofState), /// Melt Quote Bolt11 Response @@ -130,38 +134,23 @@ pub enum NotificationPayload { MintQuoteBolt12Response(MintQuoteBolt12Response), } -impl From for NotificationPayload { - fn from(proof_state: ProofState) -> NotificationPayload { - NotificationPayload::ProofState(proof_state) - } -} - -impl From> for NotificationPayload { - fn from(melt_quote: MeltQuoteBolt11Response) -> NotificationPayload { - NotificationPayload::MeltQuoteBolt11Response(melt_quote) - } -} - -impl From> for NotificationPayload { - fn from(mint_quote: MintQuoteBolt11Response) -> NotificationPayload { - NotificationPayload::MintQuoteBolt11Response(mint_quote) - } -} - -#[cfg(feature = "mint")] -#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)] +#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Deserialize, Hash, Serialize)] +#[serde(bound = "T: Serialize + DeserializeOwned")] /// A parsed notification -pub enum Notification { +pub enum NotificationId +where + T: Clone, +{ /// ProofState id is a Pubkey ProofState(PublicKey), /// MeltQuote id is an QuoteId - MeltQuoteBolt11(QuoteId), + MeltQuoteBolt11(T), /// MintQuote id is an QuoteId - MintQuoteBolt11(QuoteId), + MintQuoteBolt11(T), /// MintQuote id is an QuoteId - MintQuoteBolt12(QuoteId), + MintQuoteBolt12(T), /// MintQuote id is an QuoteId - MeltQuoteBolt12(QuoteId), + MeltQuoteBolt12(T), } /// Kind @@ -187,7 +176,6 @@ impl AsRef for Params { /// Parsing error #[derive(thiserror::Error, Debug)] pub enum Error { - #[cfg(feature = "mint")] #[error("Uuid Error: {0}")] /// Uuid Error QuoteId(#[from] QuoteIdError), diff --git a/crates/cashu/src/nuts/nut17/ws.rs b/crates/cashu/src/nuts/nut17/ws.rs index a15c52ffc..f248454c6 100644 --- a/crates/cashu/src/nuts/nut17/ws.rs +++ b/crates/cashu/src/nuts/nut17/ws.rs @@ -36,7 +36,10 @@ pub struct WsUnsubscribeResponse { /// subscription #[derive(Debug, Clone, Serialize, Deserialize)] #[serde(bound = "T: Serialize + DeserializeOwned, I: Serialize + DeserializeOwned")] -pub struct NotificationInner { +pub struct NotificationInner +where + T: Clone, +{ /// The subscription ID #[serde(rename = "subId")] pub sub_id: I, diff --git a/crates/cdk-axum/src/ws/mod.rs b/crates/cdk-axum/src/ws/mod.rs index 9ea30dc55..b5b0060cf 100644 --- a/crates/cdk-axum/src/ws/mod.rs +++ b/crates/cdk-axum/src/ws/mod.rs @@ -1,9 +1,10 @@ use std::collections::HashMap; +use std::sync::Arc; use axum::extract::ws::{CloseFrame, Message, WebSocket}; use cdk::mint::QuoteId; use cdk::nuts::nut17::NotificationPayload; -use cdk::pub_sub::SubId; +use cdk::subscription::SubId; use cdk::ws::{ notification_to_ws_message, NotificationInner, WsErrorBody, WsMessageOrResponse, WsMethodRequest, WsRequest, @@ -36,8 +37,8 @@ pub use error::WsError; pub struct WsContext { state: MintState, - subscriptions: HashMap>, - publisher: mpsc::Sender<(SubId, NotificationPayload)>, + subscriptions: HashMap, tokio::task::JoinHandle<()>>, + publisher: mpsc::Sender<(Arc, NotificationPayload)>, } /// Main function for websocket connections diff --git a/crates/cdk-axum/src/ws/subscribe.rs b/crates/cdk-axum/src/ws/subscribe.rs index fb8c9201e..94a0b2857 100644 --- a/crates/cdk-axum/src/ws/subscribe.rs +++ b/crates/cdk-axum/src/ws/subscribe.rs @@ -1,4 +1,4 @@ -use cdk::subscription::{IndexableParams, Params}; +use cdk::subscription::Params; use cdk::ws::{WsResponseResult, WsSubscribeResponse}; use super::{WsContext, WsError}; @@ -15,22 +15,20 @@ pub(crate) async fn handle( return Err(WsError::InvalidParams); } - let params: IndexableParams = params.into(); - let mut subscription = context .state .mint .pubsub_manager() - .try_subscribe(params) - .await + .subscribe(params) .map_err(|_| WsError::ParseError)?; let publisher = context.publisher.clone(); + let sub_id_for_sender = sub_id.clone(); context.subscriptions.insert( sub_id.clone(), tokio::spawn(async move { while let Some(response) = subscription.recv().await { - let _ = publisher.send(response).await; + let _ = publisher.try_send((sub_id_for_sender.clone(), response.into_inner())); } }), ); diff --git a/crates/cdk-common/Cargo.toml b/crates/cdk-common/Cargo.toml index 2ca99661a..5fb81bb91 100644 --- a/crates/cdk-common/Cargo.toml +++ b/crates/cdk-common/Cargo.toml @@ -40,10 +40,16 @@ anyhow.workspace = true serde_json.workspace = true serde_with.workspace = true web-time.workspace = true +tokio.workspace = true +parking_lot = "0.12.5" [target.'cfg(target_arch = "wasm32")'.dependencies] uuid = { workspace = true, features = ["js"], optional = true } +getrandom = { version = "0.2", features = ["js"] } +wasm-bindgen = "0.2" +wasm-bindgen-futures = "0.4" [dev-dependencies] rand.workspace = true bip39.workspace = true +wasm-bindgen-test = "0.3" diff --git a/crates/cdk-common/src/lib.rs b/crates/cdk-common/src/lib.rs index f30e082a8..9db301f55 100644 --- a/crates/cdk-common/src/lib.rs +++ b/crates/cdk-common/src/lib.rs @@ -33,3 +33,5 @@ pub use cashu::nuts::{self, *}; pub use cashu::quote_id::{self, *}; pub use cashu::{dhke, ensure_cdk, mint_url, secret, util, SECP256K1}; pub use error::Error; +/// Re-export parking_lot for reuse +pub use parking_lot; diff --git a/crates/cdk-common/src/pub_sub/error.rs b/crates/cdk-common/src/pub_sub/error.rs new file mode 100644 index 000000000..c4845d3f9 --- /dev/null +++ b/crates/cdk-common/src/pub_sub/error.rs @@ -0,0 +1,44 @@ +//! Error types for the pub-sub module. + +use tokio::sync::mpsc::error::TrySendError; + +#[derive(thiserror::Error, Debug)] +/// Error +pub enum Error { + /// No subscription found + #[error("Subscription not found")] + NoSubscription, + + /// Parsing error + #[error("Parsing Error {0}")] + ParsingError(String), + + /// Internal error + #[error("Internal")] + Internal(Box), + + /// Internal error + #[error("Internal error {0}")] + InternalStr(String), + + /// Not supported + #[error("Not supported")] + NotSupported, + + /// Channel is full + #[error("Channel is full")] + ChannelFull, + + /// Channel is closed + #[error("Channel is close")] + ChannelClosed, +} + +impl From> for Error { + fn from(value: TrySendError) -> Self { + match value { + TrySendError::Closed(_) => Error::ChannelClosed, + TrySendError::Full(_) => Error::ChannelFull, + } + } +} diff --git a/crates/cdk-common/src/pub_sub/index.rs b/crates/cdk-common/src/pub_sub/index.rs deleted file mode 100644 index 15b11b445..000000000 --- a/crates/cdk-common/src/pub_sub/index.rs +++ /dev/null @@ -1,161 +0,0 @@ -//! WS Index - -use std::fmt::Debug; -use std::ops::Deref; -use std::sync::atomic::{AtomicUsize, Ordering}; - -use super::SubId; - -/// Indexable trait -pub trait Indexable { - /// The type of the index, it is unknown and it is up to the Manager's - /// generic type - type Type: PartialOrd + Ord + Send + Sync + Debug; - - /// To indexes - fn to_indexes(&self) -> Vec>; -} - -#[derive(Debug, Ord, PartialOrd, PartialEq, Eq, Clone)] -/// Index -/// -/// The Index is a sorted structure that is used to quickly find matches -/// -/// The counter is used to make sure each Index is unique, even if the prefix -/// are the same, and also to make sure that earlier indexes matches first -pub struct Index -where - T: PartialOrd + Ord + Send + Sync + Debug, -{ - prefix: T, - counter: SubscriptionGlobalId, - id: super::SubId, -} - -impl From<&Index> for super::SubId -where - T: PartialOrd + Ord + Send + Sync + Debug, -{ - fn from(val: &Index) -> Self { - val.id.clone() - } -} - -impl Deref for Index -where - T: PartialOrd + Ord + Send + Sync + Debug, -{ - type Target = T; - - fn deref(&self) -> &Self::Target { - &self.prefix - } -} - -impl Index -where - T: PartialOrd + Ord + Send + Sync + Debug, -{ - /// Compare the - pub fn cmp_prefix(&self, other: &Index) -> std::cmp::Ordering { - self.prefix.cmp(&other.prefix) - } - - /// Returns a globally unique id for the Index - pub fn unique_id(&self) -> usize { - self.counter.0 - } -} - -impl From<(T, SubId, SubscriptionGlobalId)> for Index -where - T: PartialOrd + Ord + Send + Sync + Debug, -{ - fn from((prefix, id, counter): (T, SubId, SubscriptionGlobalId)) -> Self { - Self { - prefix, - id, - counter, - } - } -} - -impl From<(T, SubId)> for Index -where - T: PartialOrd + Ord + Send + Sync + Debug, -{ - fn from((prefix, id): (T, SubId)) -> Self { - Self { - prefix, - id, - counter: Default::default(), - } - } -} - -impl From for Index -where - T: PartialOrd + Ord + Send + Sync + Debug, -{ - fn from(prefix: T) -> Self { - Self { - prefix, - id: Default::default(), - counter: SubscriptionGlobalId(0), - } - } -} - -static COUNTER: AtomicUsize = AtomicUsize::new(0); - -/// Dummy type -/// -/// This is only use so each Index is unique, with the same prefix. -/// -/// The prefix is used to leverage the BTree to find things quickly, but each -/// entry/key must be unique, so we use this dummy type to make sure each Index -/// is unique. -/// -/// Unique is also used to make sure that the indexes are sorted by creation order -#[derive(Debug, Ord, PartialOrd, PartialEq, Eq, Clone, Copy)] -pub struct SubscriptionGlobalId(usize); - -impl Default for SubscriptionGlobalId { - fn default() -> Self { - Self(COUNTER.fetch_add(1, Ordering::Relaxed)) - } -} - -#[cfg(test)] -mod tests { - use super::*; - - #[test] - fn test_index_from_tuple() { - let sub_id = SubId::from("test_sub_id"); - let prefix = "test_prefix"; - let index: Index<&str> = Index::from((prefix, sub_id.clone())); - assert_eq!(index.prefix, "test_prefix"); - assert_eq!(index.id, sub_id); - } - - #[test] - fn test_index_cmp_prefix() { - let sub_id = SubId::from("test_sub_id"); - let index1: Index<&str> = Index::from(("a", sub_id.clone())); - let index2: Index<&str> = Index::from(("b", sub_id.clone())); - assert_eq!(index1.cmp_prefix(&index2), std::cmp::Ordering::Less); - } - - #[test] - fn test_sub_id_from_str() { - let sub_id = SubId::from("test_sub_id"); - assert_eq!(sub_id.0, "test_sub_id"); - } - - #[test] - fn test_sub_id_deref() { - let sub_id = SubId::from("test_sub_id"); - assert_eq!(&*sub_id, "test_sub_id"); - } -} diff --git a/crates/cdk-common/src/pub_sub/mod.rs b/crates/cdk-common/src/pub_sub/mod.rs index aef062b5b..7a0b0e08c 100644 --- a/crates/cdk-common/src/pub_sub/mod.rs +++ b/crates/cdk-common/src/pub_sub/mod.rs @@ -1,77 +1,180 @@ -//! Publish–subscribe pattern. +//! Publish/Subscribe core //! -//! This is a generic implementation for -//! [NUT-17]() with a type -//! agnostic Publish-subscribe manager. +//! This module defines the transport-agnostic pub/sub primitives used by both +//! mint and wallet components. The design prioritizes: //! -//! The manager has a method for subscribers to subscribe to events with a -//! generic type that must be converted to a vector of indexes. +//! - **Request coalescing**: multiple local subscribers to the same remote topic +//! result in a single upstream subscription, with local fan‑out. +//! - **Latest-on-subscribe** (NUT-17): on (re)subscription, the most recent event +//! is fetched and delivered before streaming new ones. +//! - **Backpressure-aware delivery**: bounded channels + drop policies prevent +//! a slow consumer from stalling the whole pipeline. +//! - **Resilience**: automatic reconnect with exponential backoff; WebSocket +//! streaming when available, HTTP long-poll fallback otherwise. //! -//! Events are also generic that should implement the `Indexable` trait. -use std::fmt::Debug; -use std::ops::Deref; -use std::str::FromStr; - -use serde::{Deserialize, Serialize}; - -pub mod index; - -/// Default size of the remove channel -pub const DEFAULT_REMOVE_SIZE: usize = 10_000; - -/// Default channel size for subscription buffering -pub const DEFAULT_CHANNEL_SIZE: usize = 10; - -#[async_trait::async_trait] -/// On New Subscription trait -/// -/// This trait is optional and it is used to notify the application when a new -/// subscription is created. This is useful when the application needs to send -/// the initial state to the subscriber upon subscription -pub trait OnNewSubscription { - /// Index type - type Index; - /// Subscription event type - type Event; - - /// Called when a new subscription is created - async fn on_new_subscription( - &self, - request: &[&Self::Index], - ) -> Result, String>; -} +//! Terms used throughout the module: +//! - **Event**: a domain object that maps to one or more `Topic`s via `Event::get_topics`. +//! - **Topic**: an index/type that defines storage and matching semantics. +//! - **SubscriptionRequest**: a domain-specific filter that can be converted into +//! low-level transport messages (e.g., WebSocket subscribe frames). +//! - **Spec**: type bundle tying `Event`, `Topic`, `SubscriptionId`, and serialization. + +mod error; +mod pubsub; +pub mod remote_consumer; +mod subscriber; +mod types; + +pub use self::error::Error; +pub use self::pubsub::Pubsub; +pub use self::subscriber::{Subscriber, SubscriptionRequest}; +pub use self::types::*; + +#[cfg(test)] +mod test { + use std::collections::HashMap; + use std::sync::{Arc, RwLock}; + + use serde::{Deserialize, Serialize}; -/// Subscription Id wrapper -/// -/// This is the place to add some sane default (like a max length) to the -/// subscription ID -#[derive(Debug, Clone, Default, Eq, PartialEq, Ord, PartialOrd, Hash, Serialize, Deserialize)] -pub struct SubId(String); + use super::subscriber::SubscriptionRequest; + use super::{Error, Event, Pubsub, Spec, Subscriber}; -impl From<&str> for SubId { - fn from(s: &str) -> Self { - Self(s.to_string()) + #[derive(Clone, Debug, Serialize, Eq, PartialEq, Deserialize)] + pub struct Message { + pub foo: u64, + pub bar: u64, } -} -impl From for SubId { - fn from(s: String) -> Self { - Self(s) + #[derive(Debug, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Deserialize, Serialize)] + pub enum IndexTest { + Foo(u64), + Bar(u64), } -} -impl FromStr for SubId { - type Err = (); + impl Event for Message { + type Topic = IndexTest; - fn from_str(s: &str) -> Result { - Ok(Self(s.to_string())) + fn get_topics(&self) -> Vec { + vec![IndexTest::Foo(self.foo), IndexTest::Bar(self.bar)] + } } -} -impl Deref for SubId { - type Target = String; + pub struct CustomPubSub { + pub storage: Arc>>, + } + + #[async_trait::async_trait] + impl Spec for CustomPubSub { + type Topic = IndexTest; + + type Event = Message; + + type SubscriptionId = String; + + type Context = (); + + fn new_instance(_context: Self::Context) -> Arc + where + Self: Sized, + { + Arc::new(Self { + storage: Default::default(), + }) + } + + async fn fetch_events( + self: &Arc, + topics: Vec<::Topic>, + reply_to: Subscriber, + ) where + Self: Sized, + { + let storage = self.storage.read().unwrap(); + + for index in topics { + if let Some(value) = storage.get(&index) { + let _ = reply_to.send(value.clone()); + } + } + } + } + + #[derive(Debug, Clone)] + pub enum SubscriptionReq { + Foo(u64), + Bar(u64), + } + + impl SubscriptionRequest for SubscriptionReq { + type Topic = IndexTest; + + type SubscriptionId = String; + + fn try_get_topics(&self) -> Result, Error> { + Ok(vec![match self { + SubscriptionReq::Bar(n) => IndexTest::Bar(*n), + SubscriptionReq::Foo(n) => IndexTest::Foo(*n), + }]) + } + + fn subscription_name(&self) -> Arc { + Arc::new("test".to_owned()) + } + } + + #[tokio::test] + async fn delivery_twice_realtime() { + let pubsub = Pubsub::new(CustomPubSub::new_instance(())); + + assert_eq!(pubsub.active_subscribers(), 0); + + let mut subscriber = pubsub.subscribe(SubscriptionReq::Foo(2)).unwrap(); + + assert_eq!(pubsub.active_subscribers(), 1); + + let _ = pubsub.publish_now(Message { foo: 2, bar: 1 }); + let _ = pubsub.publish_now(Message { foo: 2, bar: 2 }); + + assert_eq!(subscriber.recv().await.map(|x| x.bar), Some(1)); + assert_eq!(subscriber.recv().await.map(|x| x.bar), Some(2)); + assert!(subscriber.try_recv().is_none()); + + drop(subscriber); + + assert_eq!(pubsub.active_subscribers(), 0); + } + + #[tokio::test] + async fn read_from_storage() { + let x = CustomPubSub::new_instance(()); + let storage = x.storage.clone(); + + let pubsub = Pubsub::new(x); + + { + // set previous value + let mut s = storage.write().unwrap(); + s.insert(IndexTest::Bar(2), Message { foo: 3, bar: 2 }); + } + + let mut subscriber = pubsub.subscribe(SubscriptionReq::Bar(2)).unwrap(); + + // Just should receive the latest + assert_eq!(subscriber.recv().await.map(|x| x.foo), Some(3)); + + // realtime delivery test + let _ = pubsub.publish_now(Message { foo: 1, bar: 2 }); + assert_eq!(subscriber.recv().await.map(|x| x.foo), Some(1)); + + { + // set previous value + let mut s = storage.write().unwrap(); + s.insert(IndexTest::Bar(2), Message { foo: 1, bar: 2 }); + } - fn deref(&self) -> &Self::Target { - &self.0 + // new subscription should only get the latest state (it is up to the Topic trait) + let mut y = pubsub.subscribe(SubscriptionReq::Bar(2)).unwrap(); + assert_eq!(y.recv().await.map(|x| x.foo), Some(1)); } } diff --git a/crates/cdk-common/src/pub_sub/pubsub.rs b/crates/cdk-common/src/pub_sub/pubsub.rs new file mode 100644 index 000000000..fff71ef17 --- /dev/null +++ b/crates/cdk-common/src/pub_sub/pubsub.rs @@ -0,0 +1,185 @@ +//! Pub-sub producer + +use std::cmp::Ordering; +use std::collections::{BTreeMap, HashSet}; +use std::sync::atomic::AtomicUsize; +use std::sync::Arc; + +use parking_lot::RwLock; +use tokio::sync::mpsc; + +use super::subscriber::{ActiveSubscription, SubscriptionRequest}; +use super::{Error, Event, Spec, Subscriber}; + +/// Default channel size for subscription buffering +pub const DEFAULT_CHANNEL_SIZE: usize = 10_000; + +/// Subscriber Receiver +pub type SubReceiver = mpsc::Receiver<(Arc<::SubscriptionId>, ::Event)>; + +/// Internal Index Tree +pub type TopicTree = Arc< + RwLock< + BTreeMap< + // Index with a subscription unique ID + (::Topic, usize), + Subscriber, + >, + >, +>; + +/// Manager +pub struct Pubsub +where + S: Spec + 'static, +{ + inner: Arc, + listeners_topics: TopicTree, + unique_subscription_counter: AtomicUsize, + active_subscribers: Arc, +} + +impl Pubsub +where + S: Spec + 'static, +{ + /// Create a new instance + pub fn new(inner: Arc) -> Self { + Self { + inner, + listeners_topics: Default::default(), + unique_subscription_counter: 0.into(), + active_subscribers: Arc::new(0.into()), + } + } + + /// Total number of active subscribers, it is not the number of active topics being subscribed + pub fn active_subscribers(&self) -> usize { + self.active_subscribers + .load(std::sync::atomic::Ordering::Relaxed) + } + + /// Publish an event to all listenrs + #[inline(always)] + fn publish_internal(event: S::Event, listeners_index: &TopicTree) -> Result<(), Error> { + let index_storage = listeners_index.read(); + + let mut sent = HashSet::new(); + for topic in event.get_topics() { + for ((subscription_index, unique_id), sender) in + index_storage.range((topic.clone(), 0)..) + { + if subscription_index.cmp(&topic) != Ordering::Equal { + break; + } + if sent.contains(&unique_id) { + continue; + } + sent.insert(unique_id); + sender.send(event.clone()); + } + } + + Ok(()) + } + + /// Broadcast an event to all listeners + #[inline(always)] + pub fn publish(&self, event: E) + where + E: Into, + { + let topics = self.listeners_topics.clone(); + let event = event.into(); + + #[cfg(not(target_arch = "wasm32"))] + tokio::spawn(async move { + let _ = Self::publish_internal(event, &topics); + }); + + #[cfg(target_arch = "wasm32")] + wasm_bindgen_futures::spawn_local(async move { + let _ = Self::publish_internal(event, &topics); + }); + } + + /// Broadcast an event to all listeners right away, blocking the current thread + /// + /// This function takes an Arc to the storage struct, the event_id, the kind + /// and the vent to broadcast + #[inline(always)] + pub fn publish_now(&self, event: E) -> Result<(), Error> + where + E: Into, + { + let event = event.into(); + Self::publish_internal(event, &self.listeners_topics) + } + + /// Subscribe proving custom sender/receiver mpsc + #[inline(always)] + pub fn subscribe_with( + &self, + request: I, + sender: &mpsc::Sender<(Arc, S::Event)>, + receiver: Option>, + ) -> Result, Error> + where + I: SubscriptionRequest< + Topic = ::Topic, + SubscriptionId = S::SubscriptionId, + >, + { + let subscription_name = request.subscription_name(); + let sender = Subscriber::new(subscription_name.clone(), sender); + let mut index_storage = self.listeners_topics.write(); + let subscription_internal_id = self + .unique_subscription_counter + .fetch_add(1, std::sync::atomic::Ordering::Relaxed); + + self.active_subscribers + .fetch_add(1, std::sync::atomic::Ordering::Relaxed); + + let subscribed_to = request.try_get_topics()?; + + for index in subscribed_to.iter() { + index_storage.insert((index.clone(), subscription_internal_id), sender.clone()); + } + drop(index_storage); + + let inner = self.inner.clone(); + let subscribed_to_for_spawn = subscribed_to.clone(); + + #[cfg(not(target_arch = "wasm32"))] + tokio::spawn(async move { + // TODO: Ignore topics broadcasted from fetch_events _if_ any real time has been broadcasted already. + inner.fetch_events(subscribed_to_for_spawn, sender).await; + }); + + #[cfg(target_arch = "wasm32")] + wasm_bindgen_futures::spawn_local(async move { + inner.fetch_events(subscribed_to_for_spawn, sender).await; + }); + + Ok(ActiveSubscription::new( + subscription_internal_id, + subscription_name, + self.active_subscribers.clone(), + self.listeners_topics.clone(), + subscribed_to, + receiver, + )) + } + + /// Subscribe + pub fn subscribe(&self, request: I) -> Result, Error> + where + I: SubscriptionRequest< + Topic = ::Topic, + SubscriptionId = S::SubscriptionId, + >, + { + let (sender, receiver) = mpsc::channel(DEFAULT_CHANNEL_SIZE); + self.subscribe_with(request, &sender, Some(receiver)) + } +} diff --git a/crates/cdk-common/src/pub_sub/remote_consumer.rs b/crates/cdk-common/src/pub_sub/remote_consumer.rs new file mode 100644 index 000000000..b7ad9710d --- /dev/null +++ b/crates/cdk-common/src/pub_sub/remote_consumer.rs @@ -0,0 +1,885 @@ +//! Pub-sub consumer +//! +//! Consumers are designed to connect to a producer, through a transport, and subscribe to events. +use std::collections::{HashMap, VecDeque}; +use std::sync::atomic::AtomicBool; +use std::sync::Arc; +use std::time::Duration; + +use parking_lot::RwLock; +use tokio::sync::mpsc; +use tokio::time::{sleep, Instant}; + +use super::subscriber::{ActiveSubscription, SubscriptionRequest}; +use super::{Error, Event, Pubsub, Spec}; + +const STREAM_CONNECTION_BACKOFF: Duration = Duration::from_millis(2_000); + +const STREAM_CONNECTION_MAX_BACKOFF: Duration = Duration::from_millis(30_000); + +const INTERNAL_POLL_SIZE: usize = 1_000; + +const POLL_SLEEP: Duration = Duration::from_millis(2_000); + +#[cfg(target_arch = "wasm32")] +use wasm_bindgen_futures; + +struct UniqueSubscription +where + S: Spec, +{ + name: S::SubscriptionId, + total_subscribers: usize, +} + +type UniqueSubscriptions = RwLock::Topic, UniqueSubscription>>; + +type ActiveSubscriptions = + RwLock::SubscriptionId>, Vec<::Topic>>>; + +type CacheEvent = HashMap<<::Event as Event>::Topic, ::Event>; + +/// Subscription consumer +pub struct Consumer +where + T: Transport + 'static, +{ + transport: T, + inner_pubsub: Arc>, + remote_subscriptions: UniqueSubscriptions, + subscriptions: ActiveSubscriptions, + stream_ctrl: RwLock>>>, + still_running: AtomicBool, + prefer_polling: bool, + /// Cached events + /// + /// The cached events are useful to share events. The cache is automatically evicted it is + /// disconnected from the remote source, meaning the cache is only active while there is an + /// active subscription to the remote source, and it remembers the latest event. + cached_events: Arc>>, +} + +/// Remote consumer +pub struct RemoteActiveConsumer +where + T: Transport + 'static, +{ + inner: ActiveSubscription, + previous_messages: VecDeque<::Event>, + consumer: Arc>, +} + +impl RemoteActiveConsumer +where + T: Transport + 'static, +{ + /// Receives the next event + pub async fn recv(&mut self) -> Option<::Event> { + if let Some(event) = self.previous_messages.pop_front() { + Some(event) + } else { + self.inner.recv().await + } + } + + /// Try receive an event or return Noen right away + pub fn try_recv(&mut self) -> Option<::Event> { + if let Some(event) = self.previous_messages.pop_front() { + Some(event) + } else { + self.inner.try_recv() + } + } + + /// Get the subscription name + pub fn name(&self) -> &::SubscriptionId { + self.inner.name() + } +} + +impl Drop for RemoteActiveConsumer +where + T: Transport + 'static, +{ + fn drop(&mut self) { + let _ = self.consumer.unsubscribe(self.name().clone()); + } +} + +/// Struct to relay events from Poll and Streams from the external subscription to the local +/// subscribers +pub struct InternalRelay +where + S: Spec + 'static, +{ + inner: Arc>, + cached_events: Arc>>, +} + +impl InternalRelay +where + S: Spec + 'static, +{ + /// Relay a remote event locally + pub fn send(&self, event: X) + where + X: Into, + { + let event = event.into(); + let mut cached_events = self.cached_events.write(); + + for topic in event.get_topics() { + cached_events.insert(topic, event.clone()); + } + + self.inner.publish(event); + } +} + +impl Consumer +where + T: Transport + 'static, +{ + /// Creates a new instance + pub fn new( + transport: T, + prefer_polling: bool, + context: ::Context, + ) -> Arc { + let this = Arc::new(Self { + transport, + prefer_polling, + inner_pubsub: Arc::new(Pubsub::new(T::Spec::new_instance(context))), + subscriptions: Default::default(), + remote_subscriptions: Default::default(), + stream_ctrl: RwLock::new(None), + cached_events: Default::default(), + still_running: true.into(), + }); + + #[cfg(not(target_arch = "wasm32"))] + tokio::spawn(Self::stream(this.clone())); + + #[cfg(target_arch = "wasm32")] + wasm_bindgen_futures::spawn_local(Self::stream(this.clone())); + + this + } + + async fn stream(instance: Arc) { + let mut stream_supported = true; + let mut poll_supported = true; + + let mut backoff = STREAM_CONNECTION_BACKOFF; + let mut retry_at = None; + + loop { + if (!stream_supported && !poll_supported) + || !instance + .still_running + .load(std::sync::atomic::Ordering::Relaxed) + { + break; + } + + if instance.remote_subscriptions.read().is_empty() { + sleep(Duration::from_millis(100)).await; + continue; + } + + if stream_supported + && !instance.prefer_polling + && retry_at + .map(|retry_at| retry_at < Instant::now()) + .unwrap_or(true) + { + let (sender, receiver) = mpsc::channel(INTERNAL_POLL_SIZE); + + { + *instance.stream_ctrl.write() = Some(sender); + } + + let current_subscriptions = { + instance + .remote_subscriptions + .read() + .iter() + .map(|(key, name)| (name.name.clone(), key.clone())) + .collect::>() + }; + + if let Err(err) = instance + .transport + .stream( + receiver, + current_subscriptions, + InternalRelay { + inner: instance.inner_pubsub.clone(), + cached_events: instance.cached_events.clone(), + }, + ) + .await + { + retry_at = Some(Instant::now() + backoff); + backoff = + (backoff + STREAM_CONNECTION_BACKOFF).min(STREAM_CONNECTION_MAX_BACKOFF); + + if matches!(err, Error::NotSupported) { + stream_supported = false; + } + tracing::error!("Long connection failed with error {:?}", err); + } else { + backoff = STREAM_CONNECTION_BACKOFF; + } + + // remove sender to stream, as there is no stream + let _ = instance.stream_ctrl.write().take(); + } + + if poll_supported { + let current_subscriptions = { + instance + .remote_subscriptions + .read() + .iter() + .map(|(key, name)| (name.name.clone(), key.clone())) + .collect::>() + }; + + if let Err(err) = instance + .transport + .poll( + current_subscriptions, + InternalRelay { + inner: instance.inner_pubsub.clone(), + cached_events: instance.cached_events.clone(), + }, + ) + .await + { + if matches!(err, Error::NotSupported) { + poll_supported = false; + } + tracing::error!("Polling failed with error {:?}", err); + } + + sleep(POLL_SLEEP).await; + } + } + } + + /// Unsubscribe from a topic, this is called automatically when RemoteActiveSubscription goes + /// out of scope + fn unsubscribe( + self: &Arc, + subscription_name: ::SubscriptionId, + ) -> Result<(), Error> { + let topics = self + .subscriptions + .write() + .remove(&subscription_name) + .ok_or(Error::NoSubscription)?; + + let mut remote_subscriptions = self.remote_subscriptions.write(); + + for topic in topics { + let mut remote_subscription = + if let Some(remote_subscription) = remote_subscriptions.remove(&topic) { + remote_subscription + } else { + continue; + }; + + remote_subscription.total_subscribers = remote_subscription + .total_subscribers + .checked_sub(1) + .unwrap_or_default(); + + if remote_subscription.total_subscribers == 0 { + let mut cached_events = self.cached_events.write(); + + cached_events.remove(&topic); + + self.message_to_stream(StreamCtrl::Unsubscribe(remote_subscription.name.clone()))?; + } else { + remote_subscriptions.insert(topic, remote_subscription); + } + } + + if remote_subscriptions.is_empty() { + self.message_to_stream(StreamCtrl::Stop)?; + } + + Ok(()) + } + + #[inline(always)] + fn message_to_stream(&self, message: StreamCtrl) -> Result<(), Error> { + let to_stream = self.stream_ctrl.read(); + + if let Some(to_stream) = to_stream.as_ref() { + Ok(to_stream.try_send(message)?) + } else { + Ok(()) + } + } + + /// Creates a subscription + /// + /// The subscriptions have two parts: + /// + /// 1. Will create the subscription to the remote Pubsub service, Any events will be moved to + /// the internal pubsub + /// + /// 2. The internal subscription to the inner Pubsub. Because all subscriptions are going the + /// transport, once events matches subscriptions, the inner_pubsub will receive the message and + /// broadcasat the event. + pub fn subscribe(self: &Arc, request: I) -> Result, Error> + where + I: SubscriptionRequest< + Topic = ::Topic, + SubscriptionId = ::SubscriptionId, + >, + { + let subscription_name = request.subscription_name(); + let topics = request.try_get_topics()?; + + let mut remote_subscriptions = self.remote_subscriptions.write(); + let mut subscriptions = self.subscriptions.write(); + + if subscriptions.get(&subscription_name).is_some() { + return Err(Error::NoSubscription); + } + + let mut previous_messages = Vec::new(); + let cached_events = self.cached_events.read(); + + for topic in topics.iter() { + if let Some(subscription) = remote_subscriptions.get_mut(topic) { + subscription.total_subscribers += 1; + + if let Some(v) = cached_events.get(topic).cloned() { + previous_messages.push(v); + } + } else { + let internal_sub_name = self.transport.new_name(); + remote_subscriptions.insert( + topic.clone(), + UniqueSubscription { + total_subscribers: 1, + name: internal_sub_name.clone(), + }, + ); + + // new subscription is created, so the connection worker should be notified + self.message_to_stream(StreamCtrl::Subscribe((internal_sub_name, topic.clone())))?; + } + } + + subscriptions.insert(subscription_name, topics); + drop(subscriptions); + + Ok(RemoteActiveConsumer { + inner: self.inner_pubsub.subscribe(request)?, + previous_messages: previous_messages.into(), + consumer: self.clone(), + }) + } +} + +impl Drop for Consumer +where + T: Transport + 'static, +{ + fn drop(&mut self) { + self.still_running + .store(false, std::sync::atomic::Ordering::Release); + if let Some(to_stream) = self.stream_ctrl.read().as_ref() { + let _ = to_stream.try_send(StreamCtrl::Stop).inspect_err(|err| { + tracing::error!("Failed to send message LongPoll::Stop due to {err:?}") + }); + } + } +} + +/// Subscribe Message +pub type SubscribeMessage = (::SubscriptionId, ::Topic); + +/// Messages sent from the [`Consumer`] to the [`Transport`] background loop. +pub enum StreamCtrl +where + S: Spec + 'static, +{ + /// Add a subscription + Subscribe(SubscribeMessage), + /// Desuscribe + Unsubscribe(S::SubscriptionId), + /// Exit the loop + Stop, +} + +impl Clone for StreamCtrl +where + S: Spec + 'static, +{ + fn clone(&self) -> Self { + match self { + Self::Subscribe(s) => Self::Subscribe(s.clone()), + Self::Unsubscribe(u) => Self::Unsubscribe(u.clone()), + Self::Stop => Self::Stop, + } + } +} + +/// Transport abstracts how the consumer talks to the remote pubsub. +/// +/// Implement this on your HTTP/WebSocket client. The transport is responsible for: +/// - creating unique subscription names, +/// - keeping a long connection via `stream` **or** performing on-demand `poll`, +/// - forwarding remote events to `InternalRelay`. +/// +/// ```ignore +/// struct WsTransport { /* ... */ } +/// #[async_trait::async_trait] +/// impl Transport for WsTransport { +/// type Topic = MyTopic; +/// fn new_name(&self) -> ::SubscriptionName { 0 } +/// async fn stream(/* ... */) -> Result<(), Error> { Ok(()) } +/// async fn poll(/* ... */) -> Result<(), Error> { Ok(()) } +/// } +/// ``` +#[cfg_attr(target_arch = "wasm32", async_trait::async_trait(?Send))] +#[cfg_attr(not(target_arch = "wasm32"), async_trait::async_trait)] +pub trait Transport: Send + Sync { + /// Spec + type Spec: Spec; + + /// Create a new subscription name + fn new_name(&self) -> ::SubscriptionId; + + /// Opens a persistent connection and continuously streams events. + /// For protocols that support server push (e.g. WebSocket, SSE). + async fn stream( + &self, + subscribe_changes: mpsc::Receiver>, + topics: Vec>, + reply_to: InternalRelay, + ) -> Result<(), Error>; + + /// Performs a one-shot fetch of any currently available events. + /// Called repeatedly by the consumer when streaming is not available. + async fn poll( + &self, + topics: Vec>, + reply_to: InternalRelay, + ) -> Result<(), Error>; +} + +#[cfg(test)] +mod tests { + use std::sync::atomic::{AtomicUsize, Ordering}; + use std::sync::Arc; + + use tokio::sync::{mpsc, Mutex}; + use tokio::time::{timeout, Duration}; + + use super::{ + InternalRelay, RemoteActiveConsumer, StreamCtrl, SubscribeMessage, Transport, + INTERNAL_POLL_SIZE, + }; + use crate::pub_sub::remote_consumer::Consumer; + use crate::pub_sub::test::{CustomPubSub, IndexTest, Message}; + use crate::pub_sub::{Error, Spec, SubscriptionRequest}; + + // ===== Test Event/Topic types ===== + + #[derive(Clone, Debug)] + enum SubscriptionReq { + Foo(String, u64), + Bar(String, u64), + } + + impl SubscriptionRequest for SubscriptionReq { + type Topic = IndexTest; + + type SubscriptionId = String; + + fn try_get_topics(&self) -> Result, Error> { + Ok(vec![match self { + SubscriptionReq::Foo(_, n) => IndexTest::Foo(*n), + SubscriptionReq::Bar(_, n) => IndexTest::Bar(*n), + }]) + } + + fn subscription_name(&self) -> Arc { + Arc::new(match self { + SubscriptionReq::Foo(n, _) => n.to_string(), + SubscriptionReq::Bar(n, _) => n.to_string(), + }) + } + } + + // ===== A controllable in-memory Transport used by tests ===== + + /// TestTransport relays messages from a broadcast channel to the Consumer via `InternalRelay`. + /// It also forwards Subscribe/Unsubscribe/Stop signals to an observer channel so tests can assert them. + struct TestTransport { + name_ctr: AtomicUsize, + // We forward all transport-loop control messages here so tests can observe them. + observe_ctrl_tx: mpsc::Sender>, + // Whether stream / poll are supported. + support_long: bool, + support_poll: bool, + rx: Mutex>, + } + + impl TestTransport { + fn new( + support_long: bool, + support_poll: bool, + ) -> ( + Self, + mpsc::Sender, + mpsc::Receiver>, + ) { + let (events_tx, rx) = mpsc::channel::(INTERNAL_POLL_SIZE); + let (observe_ctrl_tx, observe_ctrl_rx) = + mpsc::channel::>(INTERNAL_POLL_SIZE); + + let t = TestTransport { + name_ctr: AtomicUsize::new(1), + rx: Mutex::new(rx), + observe_ctrl_tx, + support_long, + support_poll, + }; + + (t, events_tx, observe_ctrl_rx) + } + } + + #[async_trait::async_trait] + impl Transport for TestTransport { + type Spec = CustomPubSub; + + fn new_name(&self) -> ::SubscriptionId { + format!("sub-{}", self.name_ctr.fetch_add(1, Ordering::Relaxed)) + } + + async fn stream( + &self, + mut subscribe_changes: mpsc::Receiver>, + topics: Vec>, + reply_to: InternalRelay, + ) -> Result<(), Error> { + if !self.support_long { + return Err(Error::NotSupported); + } + + // Each invocation creates a fresh broadcast receiver + let mut rx = self.rx.lock().await; + let observe = self.observe_ctrl_tx.clone(); + + for topic in topics { + observe.try_send(StreamCtrl::Subscribe(topic)).unwrap(); + } + + loop { + tokio::select! { + // Forward any control (Subscribe/Unsubscribe/Stop) messages so the test can assert them. + Some(ctrl) = subscribe_changes.recv() => { + observe.try_send(ctrl.clone()).unwrap(); + if matches!(ctrl, StreamCtrl::Stop) { + break; + } + } + // Relay external events into the inner pubsub + Some(msg) = rx.recv() => { + reply_to.send(msg); + } + } + } + + Ok(()) + } + + async fn poll( + &self, + _topics: Vec>, + reply_to: InternalRelay, + ) -> Result<(), Error> { + if !self.support_poll { + return Err(Error::NotSupported); + } + + // On each poll call, drain anything currently pending and return. + // (The Consumer calls this repeatedly; first call happens immediately.) + let mut rx = self.rx.lock().await; + // Non-blocking drain pass: try a few times without sleeping to keep tests snappy + for _ in 0..32 { + match rx.try_recv() { + Ok(msg) => reply_to.send(msg), + Err(mpsc::error::TryRecvError::Empty) => continue, + Err(mpsc::error::TryRecvError::Disconnected) => break, + } + } + Ok(()) + } + } + + // ===== Helpers ===== + + async fn recv_next( + sub: &mut RemoteActiveConsumer, + dur_ms: u64, + ) -> Option<::Event> { + timeout(Duration::from_millis(dur_ms), sub.recv()) + .await + .ok() + .flatten() + } + + async fn expect_ctrl( + rx: &mut mpsc::Receiver>, + dur_ms: u64, + pred: impl Fn(&StreamCtrl) -> bool, + ) -> StreamCtrl { + timeout(Duration::from_millis(dur_ms), async { + loop { + if let Some(msg) = rx.recv().await { + if pred(&msg) { + break msg; + } + } + } + }) + .await + .expect("timed out waiting for control message") + } + + // ===== Tests ===== + + #[tokio::test] + async fn stream_delivery_and_unsubscribe_on_drop() { + // stream supported, poll supported (doesn't matter; prefer long) + let (transport, events_tx, mut ctrl_rx) = TestTransport::new(true, true); + + // prefer_polling = false so connection loop will try stream first. + let consumer = Consumer::new(transport, false, ()); + + // Subscribe to Foo(7) + let mut sub = consumer + .subscribe(SubscriptionReq::Foo("t".to_owned(), 7)) + .expect("subscribe ok"); + + // We should see a Subscribe(name, topic) forwarded to transport + let ctrl = expect_ctrl( + &mut ctrl_rx, + 1000, + |m| matches!(m, StreamCtrl::Subscribe((_, idx)) if *idx == IndexTest::Foo(7)), + ) + .await; + match ctrl { + StreamCtrl::Subscribe((name, idx)) => { + assert_ne!(name, "t".to_owned()); + assert_eq!(idx, IndexTest::Foo(7)); + } + _ => unreachable!(), + } + + // Send an event that matches Foo(7) + events_tx.send(Message { foo: 7, bar: 1 }).await.unwrap(); + let got = recv_next::(&mut sub, 1000) + .await + .expect("got event"); + assert_eq!(got, Message { foo: 7, bar: 1 }); + + // Dropping the RemoteActiveConsumer should trigger an Unsubscribe(name) + drop(sub); + let _ctrl = expect_ctrl(&mut ctrl_rx, 1000, |m| { + matches!(m, StreamCtrl::Unsubscribe(_)) + }) + .await; + + // Drop the Consumer -> Stop is sent so the transport loop exits cleanly + drop(consumer); + let _ = expect_ctrl(&mut ctrl_rx, 1000, |m| matches!(m, StreamCtrl::Stop)).await; + } + + #[tokio::test] + async fn test_cache_and_invalation() { + // stream supported, poll supported (doesn't matter; prefer long) + let (transport, events_tx, mut ctrl_rx) = TestTransport::new(true, true); + + // prefer_polling = false so connection loop will try stream first. + let consumer = Consumer::new(transport, false, ()); + + // Subscribe to Foo(7) + let mut sub_1 = consumer + .subscribe(SubscriptionReq::Foo("t".to_owned(), 7)) + .expect("subscribe ok"); + + // We should see a Subscribe(name, topic) forwarded to transport + let ctrl = expect_ctrl( + &mut ctrl_rx, + 1000, + |m| matches!(m, StreamCtrl::Subscribe((_, idx)) if *idx == IndexTest::Foo(7)), + ) + .await; + match ctrl { + StreamCtrl::Subscribe((name, idx)) => { + assert_ne!(name, "t1".to_owned()); + assert_eq!(idx, IndexTest::Foo(7)); + } + _ => unreachable!(), + } + + // Send an event that matches Foo(7) + events_tx.send(Message { foo: 7, bar: 1 }).await.unwrap(); + let got = recv_next::(&mut sub_1, 1000) + .await + .expect("got event"); + assert_eq!(got, Message { foo: 7, bar: 1 }); + + // Subscribe to Foo(7), should receive the latest message and future messages + let mut sub_2 = consumer + .subscribe(SubscriptionReq::Foo("t2".to_owned(), 7)) + .expect("subscribe ok"); + + let got = recv_next::(&mut sub_2, 1000) + .await + .expect("got event"); + assert_eq!(got, Message { foo: 7, bar: 1 }); + + // Dropping the RemoteActiveConsumer but not unsubscribe, since sub_2 is still active + drop(sub_1); + + // Subscribe to Foo(7), should receive the latest message and future messages + let mut sub_3 = consumer + .subscribe(SubscriptionReq::Foo("t3".to_owned(), 7)) + .expect("subscribe ok"); + + // receive cache message + let got = recv_next::(&mut sub_3, 1000) + .await + .expect("got event"); + assert_eq!(got, Message { foo: 7, bar: 1 }); + + // Send an event that matches Foo(7) + events_tx.send(Message { foo: 7, bar: 2 }).await.unwrap(); + + // receive new message + let got = recv_next::(&mut sub_2, 1000) + .await + .expect("got event"); + assert_eq!(got, Message { foo: 7, bar: 2 }); + + let got = recv_next::(&mut sub_3, 1000) + .await + .expect("got event"); + assert_eq!(got, Message { foo: 7, bar: 2 }); + + drop(sub_2); + drop(sub_3); + + let _ctrl = expect_ctrl(&mut ctrl_rx, 1000, |m| { + matches!(m, StreamCtrl::Unsubscribe(_)) + }) + .await; + + // The cache should be dropped, so no new messages + let mut sub_4 = consumer + .subscribe(SubscriptionReq::Foo("t4".to_owned(), 7)) + .expect("subscribe ok"); + + assert!( + recv_next::(&mut sub_4, 1000).await.is_none(), + "Should have not receive any update" + ); + + drop(sub_4); + + // Drop the Consumer -> Stop is sent so the transport loop exits cleanly + let _ = expect_ctrl(&mut ctrl_rx, 2000, |m| matches!(m, StreamCtrl::Stop)).await; + } + + #[tokio::test] + async fn falls_back_to_poll_when_stream_not_supported() { + // stream NOT supported, poll supported + let (transport, events_tx, _) = TestTransport::new(false, true); + // prefer_polling = true nudges the connection loop to poll first, but even if it + // tried stream, our transport returns NotSupported and the loop will use poll. + let consumer = Consumer::new(transport, true, ()); + + // Subscribe to Bar(5) + let mut sub = consumer + .subscribe(SubscriptionReq::Bar("t".to_owned(), 5)) + .expect("subscribe ok"); + + // Inject an event; the poll path should relay it on the first poll iteration + events_tx.send(Message { foo: 9, bar: 5 }).await.unwrap(); + let got = recv_next::(&mut sub, 1500) + .await + .expect("event relayed via polling"); + assert_eq!(got, Message { foo: 9, bar: 5 }); + } + + #[tokio::test] + async fn multiple_subscribers_share_single_remote_subscription() { + // This validates the "coalescing" behavior in Consumer::subscribe where multiple local + // subscribers to the same Topic should only create one remote subscription. + let (transport, events_tx, mut ctrl_rx) = TestTransport::new(true, true); + let consumer = Consumer::new(transport, false, ()); + + // Two local subscriptions to the SAME topic/name pair (different names) + let mut a = consumer + .subscribe(SubscriptionReq::Foo("t".to_owned(), 1)) + .expect("subscribe A"); + let _ = expect_ctrl( + &mut ctrl_rx, + 1000, + |m| matches!(m, StreamCtrl::Subscribe((_, idx)) if *idx == IndexTest::Foo(1)), + ) + .await; + + let mut b = consumer + .subscribe(SubscriptionReq::Foo("b".to_owned(), 1)) + .expect("subscribe B"); + + // No second Subscribe should be forwarded for the same topic (coalesced). + // Give a little time; if one appears, we'll fail explicitly. + if let Ok(Some(StreamCtrl::Subscribe((_, idx)))) = + timeout(Duration::from_millis(400), ctrl_rx.recv()).await + { + assert_ne!(idx, IndexTest::Foo(1), "should not resubscribe same topic"); + } + + // Send one event and ensure BOTH local subscribers receive it. + events_tx.send(Message { foo: 1, bar: 42 }).await.unwrap(); + let got_a = recv_next::(&mut a, 1000) + .await + .expect("A got"); + let got_b = recv_next::(&mut b, 1000) + .await + .expect("B got"); + assert_eq!(got_a, Message { foo: 1, bar: 42 }); + assert_eq!(got_b, Message { foo: 1, bar: 42 }); + + // Drop B: no Unsubscribe should be sent yet (still one local subscriber). + drop(b); + if let Ok(Some(StreamCtrl::Unsubscribe(_))) = + timeout(Duration::from_millis(400), ctrl_rx.recv()).await + { + panic!("Should NOT unsubscribe while another local subscriber exists"); + } + + // Drop A: now remote unsubscribe should occur. + drop(a); + let _ = expect_ctrl(&mut ctrl_rx, 1000, |m| { + matches!(m, StreamCtrl::Unsubscribe(_)) + }) + .await; + + let _ = expect_ctrl(&mut ctrl_rx, 1000, |m| matches!(m, StreamCtrl::Stop)).await; + } +} diff --git a/crates/cdk-common/src/pub_sub/subscriber.rs b/crates/cdk-common/src/pub_sub/subscriber.rs new file mode 100644 index 000000000..9c46e6aef --- /dev/null +++ b/crates/cdk-common/src/pub_sub/subscriber.rs @@ -0,0 +1,159 @@ +//! Active subscription +use std::fmt::Debug; +use std::sync::atomic::AtomicUsize; +use std::sync::{Arc, Mutex}; + +use tokio::sync::mpsc; + +use super::pubsub::{SubReceiver, TopicTree}; +use super::{Error, Spec}; + +/// Subscription request +pub trait SubscriptionRequest { + /// Topics + type Topic; + + /// Subscription Id + type SubscriptionId; + + /// Try to get topics from the request + fn try_get_topics(&self) -> Result, Error>; + + /// Get the subscription name + fn subscription_name(&self) -> Arc; +} + +/// Active Subscription +pub struct ActiveSubscription +where + S: Spec + 'static, +{ + id: usize, + name: Arc, + active_subscribers: Arc, + topics: TopicTree, + subscribed_to: Vec, + receiver: Option>, +} + +impl ActiveSubscription +where + S: Spec + 'static, +{ + /// Creates a new instance + pub fn new( + id: usize, + name: Arc, + active_subscribers: Arc, + topics: TopicTree, + subscribed_to: Vec, + receiver: Option>, + ) -> Self { + Self { + id, + name, + active_subscribers, + subscribed_to, + topics, + receiver, + } + } + + /// Receives the next event + pub async fn recv(&mut self) -> Option { + self.receiver.as_mut()?.recv().await.map(|(_, event)| event) + } + + /// Try receive an event or return Noen right away + pub fn try_recv(&mut self) -> Option { + self.receiver + .as_mut()? + .try_recv() + .ok() + .map(|(_, event)| event) + } + + /// Get the subscription name + pub fn name(&self) -> &S::SubscriptionId { + &self.name + } +} + +impl Drop for ActiveSubscription +where + S: Spec + 'static, +{ + fn drop(&mut self) { + // remove the listener + let mut topics = self.topics.write(); + for index in self.subscribed_to.drain(..) { + topics.remove(&(index, self.id)); + } + + // decrement the number of active subscribers + self.active_subscribers + .fetch_sub(1, std::sync::atomic::Ordering::Relaxed); + } +} + +/// Lightweight sink used by producers to send events to subscribers. +/// +/// You usually do not construct a `Subscriber` directly — it is provided to you in +/// the [`Spec::fetch_events`] callback so you can backfill a new subscription. +#[derive(Debug)] +pub struct Subscriber +where + S: Spec + 'static, +{ + subscription: Arc, + inner: mpsc::Sender<(Arc, S::Event)>, + latest: Arc>>, +} + +impl Clone for Subscriber +where + S: Spec + 'static, +{ + fn clone(&self) -> Self { + Self { + subscription: self.subscription.clone(), + inner: self.inner.clone(), + latest: self.latest.clone(), + } + } +} + +impl Subscriber +where + S: Spec + 'static, +{ + /// Create a new instance + pub fn new( + subscription: Arc, + inner: &mpsc::Sender<(Arc, S::Event)>, + ) -> Self { + Self { + inner: inner.clone(), + subscription, + latest: Arc::new(Mutex::new(None)), + } + } + + /// Send a message + pub fn send(&self, event: S::Event) { + let mut latest = if let Ok(reader) = self.latest.lock() { + reader + } else { + let _ = self.inner.try_send((self.subscription.to_owned(), event)); + return; + }; + + if let Some(last_event) = latest.replace(event.clone()) { + if last_event == event { + return; + } + } + + let _ = self.inner.try_send((self.subscription.to_owned(), event)); + } +} diff --git a/crates/cdk-common/src/pub_sub/types.rs b/crates/cdk-common/src/pub_sub/types.rs new file mode 100644 index 000000000..7ceb169a7 --- /dev/null +++ b/crates/cdk-common/src/pub_sub/types.rs @@ -0,0 +1,80 @@ +//! Pubsub Event definition +//! +//! The Pubsub Event defines the Topic struct and how an event can be converted to Topics. + +use std::hash::Hash; +use std::sync::Arc; + +use serde::de::DeserializeOwned; +use serde::Serialize; + +use super::Subscriber; + +/// Pubsub settings +#[async_trait::async_trait] +pub trait Spec: Send + Sync { + /// Topic + type Topic: Send + + Sync + + Clone + + Eq + + PartialEq + + Ord + + PartialOrd + + Hash + + Send + + Sync + + DeserializeOwned + + Serialize; + + /// Event + type Event: Event + + Send + + Sync + + Eq + + PartialEq + + DeserializeOwned + + Serialize; + + /// Subscription Id + type SubscriptionId: Clone + + Default + + Eq + + PartialEq + + Ord + + PartialOrd + + Hash + + Send + + Sync + + DeserializeOwned + + Serialize; + + /// Create a new context + type Context; + + /// Create a new instance from a given context + fn new_instance(context: Self::Context) -> Arc + where + Self: Sized; + + /// Callback function that is called on new subscriptions, to back-fill optionally the previous + /// events + async fn fetch_events( + self: &Arc, + topics: Vec<::Topic>, + reply_to: Subscriber, + ) where + Self: Sized; +} + +/// Event trait +pub trait Event: Clone + Send + Sync + Eq + PartialEq + DeserializeOwned + Serialize { + /// Generic Topic + /// + /// It should be serializable/deserializable to be stored in the database layer and it should + /// also be sorted in a BTree for in-memory matching + type Topic; + + /// To topics + fn get_topics(&self) -> Vec; +} diff --git a/crates/cdk-common/src/subscription.rs b/crates/cdk-common/src/subscription.rs index 01407de6d..3588beb2b 100644 --- a/crates/cdk-common/src/subscription.rs +++ b/crates/cdk-common/src/subscription.rs @@ -1,98 +1,115 @@ //! Subscription types and traits -#[cfg(feature = "mint")] +use std::ops::Deref; use std::str::FromStr; +use std::sync::Arc; -use cashu::nut17::{self}; -#[cfg(feature = "mint")] -use cashu::nut17::{Error, Kind, Notification}; -#[cfg(feature = "mint")] +use cashu::nut17::{self, Kind, NotificationId}; use cashu::quote_id::QuoteId; -#[cfg(feature = "mint")] -use cashu::{NotificationPayload, PublicKey}; -#[cfg(feature = "mint")] +use cashu::PublicKey; use serde::{Deserialize, Serialize}; -#[cfg(feature = "mint")] -use crate::pub_sub::index::{Index, Indexable, SubscriptionGlobalId}; -use crate::pub_sub::SubId; +use crate::pub_sub::{Error, SubscriptionRequest}; -/// Subscription parameters. +/// CDK/Mint Subscription parameters. /// /// This is a concrete type alias for `nut17::Params`. -pub type Params = nut17::Params; +pub type Params = nut17::Params>; -/// Wrapper around `nut17::Params` to implement `Indexable` for `Notification`. -#[cfg(feature = "mint")] -#[derive(Debug, Clone, Serialize, Deserialize)] -pub struct IndexableParams(Params); +impl SubscriptionRequest for Params { + type Topic = NotificationId; -#[cfg(feature = "mint")] -impl From for IndexableParams { - fn from(params: Params) -> Self { - Self(params) + type SubscriptionId = SubId; + + fn subscription_name(&self) -> Arc { + self.id.clone() + } + + fn try_get_topics(&self) -> Result, Error> { + self.filters + .iter() + .map(|filter| match self.kind { + Kind::Bolt11MeltQuote => QuoteId::from_str(filter) + .map(NotificationId::MeltQuoteBolt11) + .map_err(|_| Error::ParsingError(filter.to_owned())), + Kind::Bolt11MintQuote => QuoteId::from_str(filter) + .map(NotificationId::MintQuoteBolt11) + .map_err(|_| Error::ParsingError(filter.to_owned())), + Kind::ProofState => PublicKey::from_str(filter) + .map(NotificationId::ProofState) + .map_err(|_| Error::ParsingError(filter.to_owned())), + + Kind::Bolt12MintQuote => QuoteId::from_str(filter) + .map(NotificationId::MintQuoteBolt12) + .map_err(|_| Error::ParsingError(filter.to_owned())), + }) + .collect::, _>>() } } -#[cfg(feature = "mint")] -impl TryFrom for Vec> { - type Error = Error; - fn try_from(params: IndexableParams) -> Result { - let sub_id: SubscriptionGlobalId = Default::default(); - let params = params.0; - params - .filters - .into_iter() +/// Subscriptions parameters for the wallet +/// +/// This is because the Wallet can subscribe to non CDK quotes, where IDs are not constraint to +/// QuoteId +pub type WalletParams = nut17::Params>; + +impl SubscriptionRequest for WalletParams { + type Topic = NotificationId; + + type SubscriptionId = String; + + fn subscription_name(&self) -> Arc { + self.id.clone() + } + + fn try_get_topics(&self) -> Result, Error> { + self.filters + .iter() .map(|filter| { - let idx = match params.kind { - Kind::Bolt11MeltQuote => { - Notification::MeltQuoteBolt11(QuoteId::from_str(&filter)?) - } - Kind::Bolt11MintQuote => { - Notification::MintQuoteBolt11(QuoteId::from_str(&filter)?) - } - Kind::ProofState => Notification::ProofState(PublicKey::from_str(&filter)?), - Kind::Bolt12MintQuote => { - Notification::MintQuoteBolt12(QuoteId::from_str(&filter)?) - } - }; - - Ok(Index::from((idx, params.id.clone(), sub_id))) + Ok(match self.kind { + Kind::Bolt11MeltQuote => NotificationId::MeltQuoteBolt11(filter.to_owned()), + Kind::Bolt11MintQuote => NotificationId::MintQuoteBolt11(filter.to_owned()), + Kind::ProofState => PublicKey::from_str(filter) + .map(NotificationId::ProofState) + .map_err(|_| Error::ParsingError(filter.to_owned()))?, + + Kind::Bolt12MintQuote => NotificationId::MintQuoteBolt12(filter.to_owned()), + }) }) - .collect::>() + .collect::, _>>() + } +} + +/// Subscription Id wrapper +/// +/// This is the place to add some sane default (like a max length) to the +/// subscription ID +#[derive(Debug, Clone, Default, Eq, PartialEq, Ord, PartialOrd, Hash, Serialize, Deserialize)] +pub struct SubId(String); + +impl From<&str> for SubId { + fn from(s: &str) -> Self { + Self(s.to_string()) } } -#[cfg(feature = "mint")] -impl AsRef for IndexableParams { - fn as_ref(&self) -> &SubId { - &self.0.id +impl From for SubId { + fn from(s: String) -> Self { + Self(s) } } -#[cfg(feature = "mint")] -impl Indexable for NotificationPayload { - type Type = Notification; - - fn to_indexes(&self) -> Vec> { - match self { - NotificationPayload::ProofState(proof_state) => { - vec![Index::from(Notification::ProofState(proof_state.y))] - } - NotificationPayload::MeltQuoteBolt11Response(melt_quote) => { - vec![Index::from(Notification::MeltQuoteBolt11( - melt_quote.quote.clone(), - ))] - } - NotificationPayload::MintQuoteBolt11Response(mint_quote) => { - vec![Index::from(Notification::MintQuoteBolt11( - mint_quote.quote.clone(), - ))] - } - NotificationPayload::MintQuoteBolt12Response(mint_quote) => { - vec![Index::from(Notification::MintQuoteBolt12( - mint_quote.quote.clone(), - ))] - } - } +impl FromStr for SubId { + type Err = (); + + fn from_str(s: &str) -> Result { + Ok(Self(s.to_string())) + } +} + +impl Deref for SubId { + type Target = String; + + fn deref(&self) -> &Self::Target { + &self.0 } } diff --git a/crates/cdk-common/src/ws.rs b/crates/cdk-common/src/ws.rs index c471cc883..6c01f3274 100644 --- a/crates/cdk-common/src/ws.rs +++ b/crates/cdk-common/src/ws.rs @@ -2,6 +2,8 @@ //! //! This module extends the `cashu` crate with types and functions for the CDK, using the correct //! expected ID types. +use std::sync::Arc; + #[cfg(feature = "mint")] use cashu::nut17::ws::JSON_RPC_VERSION; use cashu::nut17::{self}; @@ -10,7 +12,7 @@ use cashu::quote_id::QuoteId; #[cfg(feature = "mint")] use cashu::NotificationPayload; -use crate::pub_sub::SubId; +type SubId = Arc; /// Request to unsubscribe from a websocket subscription pub type WsUnsubscribeRequest = nut17::ws::WsUnsubscribeRequest; diff --git a/crates/cdk-ffi/Cargo.toml b/crates/cdk-ffi/Cargo.toml index b37b47b4a..f71bf592a 100644 --- a/crates/cdk-ffi/Cargo.toml +++ b/crates/cdk-ffi/Cargo.toml @@ -22,7 +22,7 @@ ctor = "0.2" futures = { workspace = true } once_cell = { workspace = true } rand = { workspace = true } -serde = { workspace = true, features = ["derive"] } +serde = { workspace = true, features = ["derive", "rc"] } serde_json = { workspace = true } thiserror = { workspace = true } tokio = { workspace = true, features = ["sync", "rt", "rt-multi-thread"] } @@ -41,4 +41,3 @@ postgres = ["cdk-postgres"] [[bin]] name = "uniffi-bindgen" path = "src/bin/uniffi-bindgen.rs" - diff --git a/crates/cdk-ffi/src/types/subscription.rs b/crates/cdk-ffi/src/types/subscription.rs index fb07389d9..ccd036bfa 100644 --- a/crates/cdk-ffi/src/types/subscription.rs +++ b/crates/cdk-ffi/src/types/subscription.rs @@ -1,6 +1,7 @@ //! Subscription-related FFI types +use std::sync::Arc; -use cdk::pub_sub::SubId; +use cdk::event::MintEvent; use serde::{Deserialize, Serialize}; use super::proof::ProofStateUpdate; @@ -53,21 +54,17 @@ pub struct SubscribeParams { pub id: Option, } -impl From for cdk::nuts::nut17::Params { +impl From for cdk::nuts::nut17::Params> { fn from(params: SubscribeParams) -> Self { - let sub_id = params - .id - .map(|id| SubId::from(id.as_str())) - .unwrap_or_else(|| { - // Generate a random ID - let uuid = uuid::Uuid::new_v4(); - SubId::from(uuid.to_string().as_str()) - }); + let sub_id = params.id.unwrap_or_else(|| { + // Generate a random ID + uuid::Uuid::new_v4().to_string() + }); cdk::nuts::nut17::Params { kind: params.kind.into(), filters: params.filters, - id: sub_id, + id: Arc::new(sub_id), } } } @@ -132,12 +129,7 @@ impl ActiveSubscription { /// Try to receive a notification without blocking pub async fn try_recv(&self) -> Result, FfiError> { let mut guard = self.inner.lock().await; - guard - .try_recv() - .map(|opt| opt.map(Into::into)) - .map_err(|e| FfiError::Generic { - msg: format!("Failed to receive notification: {}", e), - }) + Ok(guard.try_recv().map(Into::into)) } } @@ -156,9 +148,9 @@ pub enum NotificationPayload { }, } -impl From> for NotificationPayload { - fn from(payload: cdk::nuts::NotificationPayload) -> Self { - match payload { +impl From> for NotificationPayload { + fn from(payload: MintEvent) -> Self { + match payload.into() { cdk::nuts::NotificationPayload::ProofState(states) => NotificationPayload::ProofState { proof_states: vec![states.into()], }, diff --git a/crates/cdk-ffi/src/wallet.rs b/crates/cdk-ffi/src/wallet.rs index 802a873e3..c144450fb 100644 --- a/crates/cdk-ffi/src/wallet.rs +++ b/crates/cdk-ffi/src/wallet.rs @@ -349,7 +349,7 @@ impl Wallet { &self, params: SubscribeParams, ) -> Result, FfiError> { - let cdk_params: cdk::nuts::nut17::Params = params.clone().into(); + let cdk_params: cdk::nuts::nut17::Params> = params.clone().into(); let sub_id = cdk_params.id.to_string(); let active_sub = self.inner.subscribe(cdk_params).await; Ok(std::sync::Arc::new(ActiveSubscription::new( diff --git a/crates/cdk-integration-tests/tests/integration_tests_pure.rs b/crates/cdk-integration-tests/tests/integration_tests_pure.rs index 9ab1fb003..599f86882 100644 --- a/crates/cdk-integration-tests/tests/integration_tests_pure.rs +++ b/crates/cdk-integration-tests/tests/integration_tests_pure.rs @@ -13,6 +13,7 @@ use std::assert_eq; use std::collections::{HashMap, HashSet}; use std::hash::RandomState; use std::str::FromStr; +use std::sync::Arc; use std::time::Duration; use cashu::amount::SplitTarget; @@ -24,7 +25,7 @@ use cashu::{ }; use cdk::mint::Mint; use cdk::nuts::nut00::ProofsMethods; -use cdk::subscription::{IndexableParams, Params}; +use cdk::subscription::Params; use cdk::wallet::types::{TransactionDirection, TransactionId}; use cdk::wallet::{ReceiveOptions, SendMemo, SendOptions}; use cdk::Amount; @@ -485,15 +486,11 @@ pub async fn test_p2pk_swap() { let mut listener = mint_bob .pubsub_manager() - .try_subscribe::( - Params { - kind: cdk::nuts::nut17::Kind::ProofState, - filters: public_keys_to_listen.clone(), - id: "test".into(), - } - .into(), - ) - .await + .subscribe(Params { + kind: cdk::nuts::nut17::Kind::ProofState, + filters: public_keys_to_listen.clone(), + id: Arc::new("test".into()), + }) .expect("valid subscription"); match mint_bob.process_swap_request(swap_request).await { @@ -520,9 +517,8 @@ pub async fn test_p2pk_swap() { sleep(Duration::from_secs(1)).await; let mut msgs = HashMap::new(); - while let Ok((sub_id, msg)) = listener.try_recv() { - assert_eq!(sub_id, "test".into()); - match msg { + while let Some(msg) = listener.try_recv() { + match msg.into_inner() { NotificationPayload::ProofState(ProofState { y, state, .. }) => { msgs.entry(y.to_string()) .or_insert_with(Vec::new) @@ -544,7 +540,7 @@ pub async fn test_p2pk_swap() { ); } - assert!(listener.try_recv().is_err(), "no other event is happening"); + assert!(listener.try_recv().is_none(), "no other event is happening"); assert!(msgs.is_empty(), "Only expected key events are received"); } diff --git a/crates/cdk-integration-tests/tests/regtest.rs b/crates/cdk-integration-tests/tests/regtest.rs index ce0a73cd7..98a764966 100644 --- a/crates/cdk-integration-tests/tests/regtest.rs +++ b/crates/cdk-integration-tests/tests/regtest.rs @@ -165,7 +165,7 @@ async fn test_websocket_connection() { .expect("timeout waiting for unpaid notification") .expect("No paid notification received"); - match msg { + match msg.into_inner() { NotificationPayload::MintQuoteBolt11Response(response) => { assert_eq!(response.quote.to_string(), mint_quote.id); assert_eq!(response.state, MintQuoteState::Unpaid); @@ -185,7 +185,7 @@ async fn test_websocket_connection() { .expect("timeout waiting for paid notification") .expect("No paid notification received"); - match msg { + match msg.into_inner() { NotificationPayload::MintQuoteBolt11Response(response) => { assert_eq!(response.quote.to_string(), mint_quote.id); assert_eq!(response.state, MintQuoteState::Paid); diff --git a/crates/cdk/Cargo.toml b/crates/cdk/Cargo.toml index c21dc59d9..c80ab32f7 100644 --- a/crates/cdk/Cargo.toml +++ b/crates/cdk/Cargo.toml @@ -100,8 +100,6 @@ ring = { version = "0.17.14", features = ["wasm32_unknown_unknown_js"] } rustls = { workspace = true, optional = true } uuid = { workspace = true, features = ["js"] } -wasm-bindgen = "0.2" -wasm-bindgen-futures = "0.4" gloo-timers = { version = "0.3", features = ["futures"] } [[example]] diff --git a/crates/cdk/src/event.rs b/crates/cdk/src/event.rs new file mode 100644 index 000000000..1c4fee676 --- /dev/null +++ b/crates/cdk/src/event.rs @@ -0,0 +1,127 @@ +//! Mint event types +use std::fmt::Debug; +use std::hash::Hash; +use std::ops::Deref; + +use cdk_common::nut17::NotificationId; +use cdk_common::pub_sub::Event; +use cdk_common::{ + MeltQuoteBolt11Response, MintQuoteBolt11Response, MintQuoteBolt12Response, NotificationPayload, + ProofState, +}; +use serde::de::DeserializeOwned; +use serde::{Deserialize, Serialize}; + +/// Simple wrapper over `NotificationPayload` which is a foreign type +#[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize)] +#[serde(bound = "T: Serialize + DeserializeOwned")] +pub struct MintEvent(NotificationPayload) +where + T: Clone + Eq + PartialEq; + +impl From> for NotificationPayload +where + T: Clone + Eq + PartialEq, +{ + fn from(value: MintEvent) -> Self { + value.0 + } +} + +impl Deref for MintEvent +where + T: Clone + Eq + PartialEq, +{ + type Target = NotificationPayload; + + fn deref(&self) -> &Self::Target { + &self.0 + } +} + +impl From for MintEvent +where + T: Clone + Eq + PartialEq, +{ + fn from(value: ProofState) -> Self { + Self(NotificationPayload::ProofState(value)) + } +} + +impl MintEvent +where + T: Clone + Eq + PartialEq, +{ + /// New instance + pub fn new(t: NotificationPayload) -> Self { + Self(t) + } + + /// Get inner + pub fn inner(&self) -> &NotificationPayload { + &self.0 + } + + /// Into inner + pub fn into_inner(self) -> NotificationPayload { + self.0 + } +} + +impl From> for MintEvent +where + T: Clone + Eq + PartialEq, +{ + fn from(value: NotificationPayload) -> Self { + Self(value) + } +} + +impl From> for MintEvent +where + T: Clone + Eq + PartialEq, +{ + fn from(value: MintQuoteBolt11Response) -> Self { + Self(NotificationPayload::MintQuoteBolt11Response(value)) + } +} + +impl From> for MintEvent +where + T: Clone + Eq + PartialEq, +{ + fn from(value: MeltQuoteBolt11Response) -> Self { + Self(NotificationPayload::MeltQuoteBolt11Response(value)) + } +} + +impl From> for MintEvent +where + T: Clone + Eq + PartialEq, +{ + fn from(value: MintQuoteBolt12Response) -> Self { + Self(NotificationPayload::MintQuoteBolt12Response(value)) + } +} + +impl Event for MintEvent +where + T: Clone + Serialize + DeserializeOwned + Debug + Ord + Hash + Send + Sync + Eq + PartialEq, +{ + type Topic = NotificationId; + + fn get_topics(&self) -> Vec { + vec![match &self.0 { + NotificationPayload::MeltQuoteBolt11Response(r) => { + NotificationId::MeltQuoteBolt11(r.quote.to_owned()) + } + NotificationPayload::MintQuoteBolt11Response(r) => { + NotificationId::MintQuoteBolt11(r.quote.to_owned()) + } + NotificationPayload::MintQuoteBolt12Response(r) => { + NotificationId::MintQuoteBolt12(r.quote.to_owned()) + } + NotificationPayload::ProofState(p) => NotificationId::ProofState(p.y.to_owned()), + }] + } +} diff --git a/crates/cdk/src/lib.rs b/crates/cdk/src/lib.rs index d26076ebd..58653d78c 100644 --- a/crates/cdk/src/lib.rs +++ b/crates/cdk/src/lib.rs @@ -32,11 +32,9 @@ mod bip353; #[cfg(all(any(feature = "wallet", feature = "mint"), feature = "auth"))] mod oidc_client; -#[cfg(all(any(feature = "wallet", feature = "mint"), feature = "auth"))] -pub use oidc_client::OidcClient; - -pub mod pub_sub; - +#[cfg(feature = "mint")] +#[doc(hidden)] +pub use cdk_common::payment as cdk_payment; /// Re-export amount type #[doc(hidden)] pub use cdk_common::{ @@ -44,10 +42,11 @@ pub use cdk_common::{ error::{self, Error}, lightning_invoice, mint_url, nuts, secret, util, ws, Amount, Bolt11Invoice, }; -#[cfg(feature = "mint")] -#[doc(hidden)] -pub use cdk_common::{payment as cdk_payment, subscription}; +#[cfg(all(any(feature = "wallet", feature = "mint"), feature = "auth"))] +pub use oidc_client::OidcClient; +#[cfg(any(feature = "wallet", feature = "mint"))] +pub mod event; pub mod fees; #[doc(hidden)] @@ -69,6 +68,8 @@ pub use self::wallet::HttpClient; #[doc(hidden)] pub type Result> = std::result::Result; +/// Re-export subscription +pub use cdk_common::subscription; /// Re-export futures::Stream #[cfg(any(feature = "wallet", feature = "mint"))] pub use futures::{Stream, StreamExt}; diff --git a/crates/cdk/src/mint/issue/mod.rs b/crates/cdk/src/mint/issue/mod.rs index 8104b2e3a..419abd3c6 100644 --- a/crates/cdk/src/mint/issue/mod.rs +++ b/crates/cdk/src/mint/issue/mod.rs @@ -322,12 +322,12 @@ impl Mint { PaymentMethod::Bolt11 => { let res: MintQuoteBolt11Response = quote.clone().into(); self.pubsub_manager - .broadcast(NotificationPayload::MintQuoteBolt11Response(res)); + .publish(NotificationPayload::MintQuoteBolt11Response(res)); } PaymentMethod::Bolt12 => { let res: MintQuoteBolt12Response = quote.clone().try_into()?; self.pubsub_manager - .broadcast(NotificationPayload::MintQuoteBolt12Response(res)); + .publish(NotificationPayload::MintQuoteBolt12Response(res)); } PaymentMethod::Custom(_) => {} } diff --git a/crates/cdk/src/mint/mod.rs b/crates/cdk/src/mint/mod.rs index f93be3b65..fbe7d6899 100644 --- a/crates/cdk/src/mint/mod.rs +++ b/crates/cdk/src/mint/mod.rs @@ -43,7 +43,7 @@ mod ln; mod melt; mod proof_writer; mod start_up_check; -pub mod subscription; +mod subscription; mod swap; mod verification; @@ -206,7 +206,7 @@ impl Mint { Ok(Self { signatory, - pubsub_manager: Arc::new(localstore.clone().into()), + pubsub_manager: PubSubManager::new(localstore.clone()), localstore, #[cfg(feature = "auth")] oidc_client: computed_info.nuts.nut21.as_ref().map(|nut21| { diff --git a/crates/cdk/src/mint/subscription.rs b/crates/cdk/src/mint/subscription.rs new file mode 100644 index 000000000..f60ebde97 --- /dev/null +++ b/crates/cdk/src/mint/subscription.rs @@ -0,0 +1,244 @@ +//! Specific Subscription for the cdk crate + +use std::ops::Deref; +use std::sync::Arc; + +use cdk_common::database::DynMintDatabase; +use cdk_common::mint::MintQuote; +use cdk_common::nut17::NotificationId; +use cdk_common::pub_sub::{Pubsub, Spec, Subscriber}; +use cdk_common::subscription::SubId; +use cdk_common::{ + Amount, BlindSignature, MeltQuoteBolt11Response, MeltQuoteState, MintQuoteBolt11Response, + MintQuoteBolt12Response, MintQuoteState, PaymentMethod, ProofState, PublicKey, QuoteId, +}; + +use crate::event::MintEvent; + +/// Mint subtopics +#[derive(Clone)] +pub struct MintPubSubSpec { + db: DynMintDatabase, +} + +impl MintPubSubSpec { + async fn get_events_from_db( + &self, + request: &[NotificationId], + ) -> Result>, String> { + let mut to_return = vec![]; + let mut public_keys: Vec = Vec::new(); + let mut melt_queries = Vec::new(); + let mut mint_queries = Vec::new(); + + for idx in request.iter() { + match idx { + NotificationId::ProofState(pk) => public_keys.push(*pk), + NotificationId::MeltQuoteBolt11(uuid) => { + melt_queries.push(self.db.get_melt_quote(uuid)) + } + NotificationId::MintQuoteBolt11(uuid) => { + mint_queries.push(self.db.get_mint_quote(uuid)) + } + NotificationId::MintQuoteBolt12(uuid) => { + mint_queries.push(self.db.get_mint_quote(uuid)) + } + NotificationId::MeltQuoteBolt12(uuid) => { + melt_queries.push(self.db.get_melt_quote(uuid)) + } + } + } + + if !melt_queries.is_empty() { + to_return.extend( + futures::future::try_join_all(melt_queries) + .await + .map(|quotes| { + quotes + .into_iter() + .filter_map(|quote| quote.map(|x| x.into())) + .map(|x: MeltQuoteBolt11Response| x.into()) + .collect::>() + }) + .map_err(|e| e.to_string())?, + ); + } + + if !mint_queries.is_empty() { + to_return.extend( + futures::future::try_join_all(mint_queries) + .await + .map(|quotes| { + quotes + .into_iter() + .filter_map(|quote| { + quote.and_then(|x| match x.payment_method { + PaymentMethod::Bolt11 => { + let response: MintQuoteBolt11Response = x.into(); + Some(response.into()) + } + PaymentMethod::Bolt12 => match x.try_into() { + Ok(response) => { + let response: MintQuoteBolt12Response = + response; + Some(response.into()) + } + Err(_) => None, + }, + PaymentMethod::Custom(_) => None, + }) + }) + .collect::>() + }) + .map_err(|e| e.to_string())?, + ); + } + + if !public_keys.is_empty() { + to_return.extend( + self.db + .get_proofs_states(public_keys.as_slice()) + .await + .map_err(|e| e.to_string())? + .into_iter() + .enumerate() + .filter_map(|(idx, state)| state.map(|state| (public_keys[idx], state).into())) + .map(|state: ProofState| state.into()), + ); + } + + Ok(to_return) + } +} + +#[async_trait::async_trait] +impl Spec for MintPubSubSpec { + type SubscriptionId = SubId; + + type Topic = NotificationId; + + type Event = MintEvent; + + type Context = DynMintDatabase; + + fn new_instance(context: Self::Context) -> Arc { + Arc::new(Self { db: context }) + } + + async fn fetch_events(self: &Arc, topics: Vec, reply_to: Subscriber) { + for event in self + .get_events_from_db(&topics) + .await + .inspect_err(|err| tracing::error!("Error reading events from db {err:?}")) + .unwrap_or_default() + { + let _ = reply_to.send(event); + } + } +} + +/// PubsubManager +pub struct PubSubManager(Pubsub); + +impl PubSubManager { + /// Create a new instance + pub fn new(db: DynMintDatabase) -> Arc { + Arc::new(Self(Pubsub::new(MintPubSubSpec::new_instance(db)))) + } + + /// Helper function to emit a ProofState status + pub fn proof_state>(&self, event: E) { + self.publish(event.into()); + } + + /// Helper function to publish even of a mint quote being paid + pub fn mint_quote_issue(&self, mint_quote: &MintQuote, total_issued: Amount) { + match mint_quote.payment_method { + PaymentMethod::Bolt11 => { + self.mint_quote_bolt11_status(mint_quote.clone(), MintQuoteState::Issued); + } + PaymentMethod::Bolt12 => { + self.mint_quote_bolt12_status( + mint_quote.clone(), + mint_quote.amount_paid(), + total_issued, + ); + } + _ => { + // We don't send ws updates for unknown methods + } + } + } + + /// Helper function to publish even of a mint quote being paid + pub fn mint_quote_payment(&self, mint_quote: &MintQuote, total_paid: Amount) { + match mint_quote.payment_method { + PaymentMethod::Bolt11 => { + self.mint_quote_bolt11_status(mint_quote.clone(), MintQuoteState::Paid); + } + PaymentMethod::Bolt12 => { + self.mint_quote_bolt12_status( + mint_quote.clone(), + total_paid, + mint_quote.amount_issued(), + ); + } + _ => { + // We don't send ws updates for unknown methods + } + } + } + + /// Helper function to emit a MintQuoteBolt11Response status + pub fn mint_quote_bolt11_status>>( + &self, + quote: E, + new_state: MintQuoteState, + ) { + let mut event = quote.into(); + event.state = new_state; + + self.publish(event); + } + + /// Helper function to emit a MintQuoteBolt11Response status + pub fn mint_quote_bolt12_status>>( + &self, + quote: E, + amount_paid: Amount, + amount_issued: Amount, + ) { + if let Ok(mut event) = quote.try_into() { + event.amount_paid = amount_paid; + event.amount_issued = amount_issued; + + self.publish(event); + } else { + tracing::warn!("Could not convert quote to MintQuoteResponse"); + } + } + + /// Helper function to emit a MeltQuoteBolt11Response status + pub fn melt_quote_status>>( + &self, + quote: E, + payment_preimage: Option, + change: Option>, + new_state: MeltQuoteState, + ) { + let mut quote = quote.into(); + quote.state = new_state; + quote.paid = Some(new_state == MeltQuoteState::Paid); + quote.payment_preimage = payment_preimage; + quote.change = change; + self.publish(quote); + } +} + +impl Deref for PubSubManager { + type Target = Pubsub; + + fn deref(&self) -> &Self::Target { + &self.0 + } +} diff --git a/crates/cdk/src/mint/subscription/manager.rs b/crates/cdk/src/mint/subscription/manager.rs deleted file mode 100644 index d4c3b9748..000000000 --- a/crates/cdk/src/mint/subscription/manager.rs +++ /dev/null @@ -1,292 +0,0 @@ -//! Specific Subscription for the cdk crate -use std::ops::Deref; - -use cdk_common::database::DynMintDatabase; -use cdk_common::mint::MintQuote; -use cdk_common::nut17::Notification; -use cdk_common::quote_id::QuoteId; -use cdk_common::{Amount, MintQuoteBolt12Response, NotificationPayload, PaymentMethod}; - -use super::OnSubscription; -use crate::nuts::{ - BlindSignature, MeltQuoteBolt11Response, MeltQuoteState, MintQuoteBolt11Response, - MintQuoteState, ProofState, -}; -use crate::pub_sub; - -/// Manager -/// Publish–subscribe manager -/// -/// Nut-17 implementation is system-wide and not only through the WebSocket, so -/// it is possible for another part of the system to subscribe to events. -pub struct PubSubManager( - pub_sub::Manager, Notification, OnSubscription>, -); - -#[allow(clippy::default_constructed_unit_structs)] -impl Default for PubSubManager { - fn default() -> Self { - PubSubManager(OnSubscription::default().into()) - } -} - -impl From for PubSubManager { - fn from(val: DynMintDatabase) -> Self { - PubSubManager(OnSubscription(Some(val)).into()) - } -} - -impl Deref for PubSubManager { - type Target = pub_sub::Manager, Notification, OnSubscription>; - - fn deref(&self) -> &Self::Target { - &self.0 - } -} - -impl PubSubManager { - /// Helper function to emit a ProofState status - pub fn proof_state>(&self, event: E) { - self.broadcast(event.into().into()); - } - - /// Helper function to publish even of a mint quote being paid - pub fn mint_quote_issue(&self, mint_quote: &MintQuote, total_issued: Amount) { - match mint_quote.payment_method { - PaymentMethod::Bolt11 => { - self.mint_quote_bolt11_status(mint_quote.clone(), MintQuoteState::Issued); - } - PaymentMethod::Bolt12 => { - self.mint_quote_bolt12_status( - mint_quote.clone(), - mint_quote.amount_paid(), - total_issued, - ); - } - _ => { - // We don't send ws updates for unknown methods - } - } - } - - /// Helper function to publish even of a mint quote being paid - pub fn mint_quote_payment(&self, mint_quote: &MintQuote, total_paid: Amount) { - match mint_quote.payment_method { - PaymentMethod::Bolt11 => { - self.mint_quote_bolt11_status(mint_quote.clone(), MintQuoteState::Paid); - } - PaymentMethod::Bolt12 => { - self.mint_quote_bolt12_status( - mint_quote.clone(), - total_paid, - mint_quote.amount_issued(), - ); - } - _ => { - // We don't send ws updates for unknown methods - } - } - } - - /// Helper function to emit a MintQuoteBolt11Response status - pub fn mint_quote_bolt11_status>>( - &self, - quote: E, - new_state: MintQuoteState, - ) { - let mut event = quote.into(); - event.state = new_state; - - self.broadcast(event.into()); - } - - /// Helper function to emit a MintQuoteBolt11Response status - pub fn mint_quote_bolt12_status>>( - &self, - quote: E, - amount_paid: Amount, - amount_issued: Amount, - ) { - if let Ok(mut event) = quote.try_into() { - event.amount_paid = amount_paid; - event.amount_issued = amount_issued; - - self.broadcast(event.into()); - } else { - tracing::warn!("Could not convert quote to MintQuoteResponse"); - } - } - - /// Helper function to emit a MeltQuoteBolt11Response status - pub fn melt_quote_status>>( - &self, - quote: E, - payment_preimage: Option, - change: Option>, - new_state: MeltQuoteState, - ) { - let mut quote = quote.into(); - quote.state = new_state; - quote.paid = Some(new_state == MeltQuoteState::Paid); - quote.payment_preimage = payment_preimage; - quote.change = change; - self.broadcast(quote.into()); - } -} - -#[cfg(test)] -mod test { - use std::time::Duration; - - use tokio::time::sleep; - - use super::*; - use crate::nuts::nut17::Kind; - use crate::nuts::{PublicKey, State}; - use crate::subscription::{IndexableParams, Params}; - - #[tokio::test] - async fn active_and_drop() { - let manager = PubSubManager::default(); - let params: IndexableParams = Params { - kind: Kind::ProofState, - filters: vec![ - "02a9acc1e48c25eeeb9289b5031cc57da9fe72f3fe2861d264bdc074209b107ba2".to_owned(), - ], - id: "uno".into(), - } - .into(); - - // Although the same param is used, two subscriptions are created, that - // is because each index is unique, thanks to `Unique`, it is the - // responsibility of the implementor to make sure that SubId are unique - // either globally or per client - let subscriptions = vec![ - manager - .try_subscribe(params.clone()) - .await - .expect("valid subscription"), - manager - .try_subscribe(params) - .await - .expect("valid subscription"), - ]; - assert_eq!(2, manager.active_subscriptions()); - drop(subscriptions); - - sleep(Duration::from_millis(10)).await; - - assert_eq!(0, manager.active_subscriptions()); - } - - #[tokio::test] - async fn broadcast() { - let manager = PubSubManager::default(); - let mut subscriptions = [ - manager - .try_subscribe::( - Params { - kind: Kind::ProofState, - filters: vec![ - "02194603ffa36356f4a56b7df9371fc3192472351453ec7398b8da8117e7c3e104" - .to_string(), - ], - id: "uno".into(), - } - .into(), - ) - .await - .expect("valid subscription"), - manager - .try_subscribe::( - Params { - kind: Kind::ProofState, - filters: vec![ - "02194603ffa36356f4a56b7df9371fc3192472351453ec7398b8da8117e7c3e104" - .to_string(), - ], - id: "dos".into(), - } - .into(), - ) - .await - .expect("valid subscription"), - ]; - - let event = ProofState { - y: PublicKey::from_hex( - "02194603ffa36356f4a56b7df9371fc3192472351453ec7398b8da8117e7c3e104", - ) - .expect("valid pk"), - state: State::Pending, - witness: None, - }; - - manager.broadcast(event.into()); - - sleep(Duration::from_millis(10)).await; - - let (sub1, _) = subscriptions[0].try_recv().expect("valid message"); - assert_eq!("uno", *sub1); - - let (sub1, _) = subscriptions[1].try_recv().expect("valid message"); - assert_eq!("dos", *sub1); - - assert!(subscriptions[0].try_recv().is_err()); - assert!(subscriptions[1].try_recv().is_err()); - } - - #[test] - fn parsing_request() { - let json = r#"{"kind":"proof_state","filters":["x"],"subId":"uno"}"#; - let params: Params = serde_json::from_str(json).expect("valid json"); - assert_eq!(params.kind, Kind::ProofState); - assert_eq!(params.filters, vec!["x"]); - assert_eq!(*params.id, "uno"); - } - - #[tokio::test] - async fn json_test() { - let manager = PubSubManager::default(); - let mut subscription = manager - .try_subscribe::( - serde_json::from_str(r#"{"kind":"proof_state","filters":["02194603ffa36356f4a56b7df9371fc3192472351453ec7398b8da8117e7c3e104"],"subId":"uno"}"#) - .expect("valid json"), - ) - .await.expect("valid subscription"); - - manager.broadcast( - ProofState { - y: PublicKey::from_hex( - "02194603ffa36356f4a56b7df9371fc3192472351453ec7398b8da8117e7c3e104", - ) - .expect("valid pk"), - state: State::Pending, - witness: None, - } - .into(), - ); - - // no one is listening for this event - manager.broadcast( - ProofState { - y: PublicKey::from_hex( - "020000000000000000000000000000000000000000000000000000000000000001", - ) - .expect("valid pk"), - state: State::Pending, - witness: None, - } - .into(), - ); - - sleep(Duration::from_millis(10)).await; - let (sub1, msg) = subscription.try_recv().expect("valid message"); - assert_eq!("uno", *sub1); - assert_eq!( - r#"{"Y":"02194603ffa36356f4a56b7df9371fc3192472351453ec7398b8da8117e7c3e104","state":"PENDING","witness":null}"#, - serde_json::to_string(&msg).expect("valid json") - ); - assert!(subscription.try_recv().is_err()); - } -} diff --git a/crates/cdk/src/mint/subscription/mod.rs b/crates/cdk/src/mint/subscription/mod.rs deleted file mode 100644 index 20216fab6..000000000 --- a/crates/cdk/src/mint/subscription/mod.rs +++ /dev/null @@ -1,12 +0,0 @@ -//! Specific Subscription for the cdk crate - -#[cfg(feature = "mint")] -mod manager; -#[cfg(feature = "mint")] -mod on_subscription; -#[cfg(feature = "mint")] -pub use manager::PubSubManager; -#[cfg(feature = "mint")] -pub use on_subscription::OnSubscription; - -pub use crate::pub_sub::SubId; diff --git a/crates/cdk/src/mint/subscription/on_subscription.rs b/crates/cdk/src/mint/subscription/on_subscription.rs deleted file mode 100644 index 1e331db48..000000000 --- a/crates/cdk/src/mint/subscription/on_subscription.rs +++ /dev/null @@ -1,119 +0,0 @@ -//! On Subscription -//! -//! This module contains the code that is triggered when a new subscription is created. - -use cdk_common::database::DynMintDatabase; -use cdk_common::nut17::Notification; -use cdk_common::pub_sub::OnNewSubscription; -use cdk_common::quote_id::QuoteId; -use cdk_common::{MintQuoteBolt12Response, NotificationPayload, PaymentMethod}; - -use crate::nuts::{MeltQuoteBolt11Response, MintQuoteBolt11Response, ProofState, PublicKey}; - -#[derive(Default)] -/// Subscription Init -/// -/// This struct triggers code when a new subscription is created. -/// -/// It is used to send the initial state of the subscription to the client. -pub struct OnSubscription(pub(crate) Option); - -#[async_trait::async_trait] -impl OnNewSubscription for OnSubscription { - type Event = NotificationPayload; - type Index = Notification; - - async fn on_new_subscription( - &self, - request: &[&Self::Index], - ) -> Result, String> { - let datastore = if let Some(localstore) = self.0.as_ref() { - localstore - } else { - return Ok(vec![]); - }; - - let mut to_return = vec![]; - let mut public_keys: Vec = Vec::new(); - let mut melt_queries = Vec::new(); - let mut mint_queries = Vec::new(); - - for idx in request.iter() { - match idx { - Notification::ProofState(pk) => public_keys.push(*pk), - Notification::MeltQuoteBolt11(uuid) => { - melt_queries.push(datastore.get_melt_quote(uuid)) - } - Notification::MintQuoteBolt11(uuid) => { - mint_queries.push(datastore.get_mint_quote(uuid)) - } - Notification::MintQuoteBolt12(uuid) => { - mint_queries.push(datastore.get_mint_quote(uuid)) - } - Notification::MeltQuoteBolt12(uuid) => { - melt_queries.push(datastore.get_melt_quote(uuid)) - } - } - } - - if !melt_queries.is_empty() { - to_return.extend( - futures::future::try_join_all(melt_queries) - .await - .map(|quotes| { - quotes - .into_iter() - .filter_map(|quote| quote.map(|x| x.into())) - .map(|x: MeltQuoteBolt11Response| x.into()) - .collect::>() - }) - .map_err(|e| e.to_string())?, - ); - } - - if !mint_queries.is_empty() { - to_return.extend( - futures::future::try_join_all(mint_queries) - .await - .map(|quotes| { - quotes - .into_iter() - .filter_map(|quote| { - quote.and_then(|x| match x.payment_method { - PaymentMethod::Bolt11 => { - let response: MintQuoteBolt11Response = x.into(); - Some(response.into()) - } - PaymentMethod::Bolt12 => match x.try_into() { - Ok(response) => { - let response: MintQuoteBolt12Response = - response; - Some(response.into()) - } - Err(_) => None, - }, - PaymentMethod::Custom(_) => None, - }) - }) - .collect::>() - }) - .map_err(|e| e.to_string())?, - ); - } - - if !public_keys.is_empty() { - to_return.extend( - datastore - .get_proofs_states(public_keys.as_slice()) - .await - .map_err(|e| e.to_string())? - .into_iter() - .enumerate() - .filter_map(|(idx, state)| state.map(|state| (public_keys[idx], state).into())) - .map(|state: ProofState| state.into()), - ); - } - - Ok(to_return) - } -} diff --git a/crates/cdk/src/pub_sub.rs b/crates/cdk/src/pub_sub.rs deleted file mode 100644 index f83655524..000000000 --- a/crates/cdk/src/pub_sub.rs +++ /dev/null @@ -1,339 +0,0 @@ -//! Publish–subscribe pattern. -//! -//! This is a generic implementation for -//! [NUT-17]() with a type -//! agnostic Publish-subscribe manager. -//! -//! The manager has a method for subscribers to subscribe to events with a -//! generic type that must be converted to a vector of indexes. -//! -//! Events are also generic that should implement the `Indexable` trait. -use std::cmp::Ordering; -use std::collections::{BTreeMap, HashSet}; -use std::fmt::Debug; -use std::ops::{Deref, DerefMut}; -use std::sync::atomic::{self, AtomicUsize}; -use std::sync::Arc; - -pub use cdk_common::pub_sub::index::{Index, Indexable, SubscriptionGlobalId}; -use cdk_common::pub_sub::OnNewSubscription; -pub use cdk_common::pub_sub::SubId; -use tokio::sync::{mpsc, RwLock}; -use tokio::task::JoinHandle; - -type IndexTree = Arc, mpsc::Sender<(SubId, T)>>>>; - -/// Default size of the remove channel -pub const DEFAULT_REMOVE_SIZE: usize = 10_000; - -/// Default channel size for subscription buffering -pub const DEFAULT_CHANNEL_SIZE: usize = 10; - -/// Subscription manager -/// -/// This object keep track of all subscription listener and it is also -/// responsible for broadcasting events to all listeners -/// -/// The content of the notification is not relevant to this scope and it is up -/// to the application, therefore the generic T is used instead of a specific -/// type -pub struct Manager -where - T: Indexable + Clone + Send + Sync + 'static, - I: PartialOrd + Clone + Debug + Ord + Send + Sync + 'static, - F: OnNewSubscription + Send + Sync + 'static, -{ - indexes: IndexTree, - on_new_subscription: Option>, - unsubscription_sender: mpsc::Sender<(SubId, Vec>)>, - active_subscriptions: Arc, - background_subscription_remover: Option>, -} - -impl Default for Manager -where - T: Indexable + Clone + Send + Sync + 'static, - I: PartialOrd + Clone + Debug + Ord + Send + Sync + 'static, - F: OnNewSubscription + Send + Sync + 'static, -{ - fn default() -> Self { - let (sender, receiver) = mpsc::channel(DEFAULT_REMOVE_SIZE); - let active_subscriptions: Arc = Default::default(); - let storage: IndexTree = Arc::new(Default::default()); - - Self { - background_subscription_remover: Some(tokio::spawn(Self::remove_subscription( - receiver, - storage.clone(), - active_subscriptions.clone(), - ))), - on_new_subscription: None, - unsubscription_sender: sender, - active_subscriptions, - indexes: storage, - } - } -} - -impl From for Manager -where - T: Indexable + Clone + Send + Sync + 'static, - I: PartialOrd + Clone + Debug + Ord + Send + Sync + 'static, - F: OnNewSubscription + Send + Sync + 'static, -{ - fn from(value: F) -> Self { - let mut manager: Self = Default::default(); - manager.on_new_subscription = Some(Arc::new(value)); - manager - } -} - -impl Manager -where - T: Indexable + Clone + Send + Sync + 'static, - I: PartialOrd + Clone + Debug + Ord + Send + Sync + 'static, - F: OnNewSubscription + Send + Sync + 'static, -{ - #[inline] - /// Broadcast an event to all listeners - /// - /// This function takes an Arc to the storage struct, the event_id, the kind - /// and the vent to broadcast - async fn broadcast_impl(storage: &IndexTree, event: T) { - let index_storage = storage.read().await; - let mut sent = HashSet::new(); - for index in event.to_indexes() { - for (key, sender) in index_storage.range(index.clone()..) { - if index.cmp_prefix(key) != Ordering::Equal { - break; - } - let sub_id = key.unique_id(); - if sent.contains(&sub_id) { - continue; - } - sent.insert(sub_id); - let _ = sender.try_send((key.into(), event.clone())); - } - } - } - - /// Broadcasts an event to all listeners - /// - /// This public method will not block the caller, it will spawn a new task - /// instead - pub fn broadcast(&self, event: T) { - let storage = self.indexes.clone(); - tokio::spawn(async move { - Self::broadcast_impl(&storage, event).await; - }); - } - - /// Broadcasts an event to all listeners - /// - /// This method is async and will await for the broadcast to be completed - pub async fn broadcast_async(&self, event: T) { - Self::broadcast_impl(&self.indexes, event).await; - } - - /// Specific of the subscription, this is the abstraction between `subscribe` and `try_subscribe` - #[inline(always)] - async fn subscribe_inner( - &self, - sub_id: SubId, - indexes: Vec>, - ) -> ActiveSubscription { - let (sender, receiver) = mpsc::channel(10); - - let mut index_storage = self.indexes.write().await; - // Subscribe to events as soon as possible - for index in indexes.clone() { - index_storage.insert(index, sender.clone()); - } - drop(index_storage); - - if let Some(on_new_subscription) = self.on_new_subscription.clone() { - // After we're subscribed already, fetch the current status of matching events. It is - // down in another thread to return right away - let indexes_for_worker = indexes.clone(); - let sub_id_for_worker = sub_id.clone(); - tokio::spawn(async move { - match on_new_subscription - .on_new_subscription( - &indexes_for_worker - .iter() - .map(|x| x.deref()) - .collect::>(), - ) - .await - { - Ok(events) => { - for event in events { - let _ = sender.try_send((sub_id_for_worker.clone(), event)); - } - } - Err(err) => { - tracing::info!( - "Failed to get initial state for subscription: {:?}, {}", - sub_id_for_worker, - err - ); - } - } - }); - } - - self.active_subscriptions - .fetch_add(1, atomic::Ordering::Relaxed); - - ActiveSubscription { - sub_id, - receiver, - indexes, - drop: self.unsubscription_sender.clone(), - } - } - - /// Try to subscribe to a specific event - pub async fn try_subscribe

    (&self, params: P) -> Result, P::Error> - where - P: AsRef + TryInto>>, - { - Ok(self - .subscribe_inner(params.as_ref().clone(), params.try_into()?) - .await) - } - - /// Subscribe to a specific event - pub async fn subscribe

    (&self, params: P) -> ActiveSubscription - where - P: AsRef + Into>>, - { - self.subscribe_inner(params.as_ref().clone(), params.into()) - .await - } - - /// Return number of active subscriptions - pub fn active_subscriptions(&self) -> usize { - self.active_subscriptions.load(atomic::Ordering::SeqCst) - } - - /// Task to remove dropped subscriptions from the storage struct - /// - /// This task will run in the background (and will be dropped when the [`Manager`] - /// is) and will remove subscriptions from the storage struct it is dropped. - async fn remove_subscription( - mut receiver: mpsc::Receiver<(SubId, Vec>)>, - storage: IndexTree, - active_subscriptions: Arc, - ) { - while let Some((sub_id, indexes)) = receiver.recv().await { - tracing::info!("Removing subscription: {}", *sub_id); - - active_subscriptions.fetch_sub(1, atomic::Ordering::AcqRel); - - let mut index_storage = storage.write().await; - for key in indexes { - index_storage.remove(&key); - } - drop(index_storage); - } - } -} - -/// Manager goes out of scope, stop all background tasks -impl Drop for Manager -where - T: Indexable + Clone + Send + Sync + 'static, - I: Clone + Debug + PartialOrd + Ord + Send + Sync + 'static, - F: OnNewSubscription + Send + Sync + 'static, -{ - fn drop(&mut self) { - if let Some(handler) = self.background_subscription_remover.take() { - handler.abort(); - } - } -} - -/// Active Subscription -/// -/// This struct is a wrapper around the `mpsc::Receiver` and it also used -/// to keep track of the subscription itself. When this struct goes out of -/// scope, it will notify the Manager about it, so it can be removed from the -/// list of active listeners -pub struct ActiveSubscription -where - T: Send + Sync, - I: Clone + Debug + PartialOrd + Ord + Send + Sync + 'static, -{ - /// The subscription ID - pub sub_id: SubId, - indexes: Vec>, - receiver: mpsc::Receiver<(SubId, T)>, - drop: mpsc::Sender<(SubId, Vec>)>, -} - -impl Deref for ActiveSubscription -where - T: Send + Sync, - I: Clone + Debug + PartialOrd + Ord + Send + Sync + 'static, -{ - type Target = mpsc::Receiver<(SubId, T)>; - - fn deref(&self) -> &Self::Target { - &self.receiver - } -} - -impl DerefMut for ActiveSubscription -where - T: Indexable + Clone + Send + Sync + 'static, - I: Clone + Debug + PartialOrd + Ord + Send + Sync + 'static, -{ - fn deref_mut(&mut self) -> &mut Self::Target { - &mut self.receiver - } -} - -/// The ActiveSubscription is Drop out of scope, notify the Manager about it, so -/// it can be removed from the list of active listeners -/// -/// Having this in place, we can avoid memory leaks and also makes it super -/// simple to implement the Unsubscribe method -impl Drop for ActiveSubscription -where - T: Send + Sync, - I: Clone + Debug + PartialOrd + Ord + Send + Sync + 'static, -{ - fn drop(&mut self) { - let _ = self - .drop - .try_send((self.sub_id.clone(), self.indexes.drain(..).collect())); - } -} - -#[cfg(test)] -mod test { - use tokio::sync::mpsc; - - use super::*; - - #[test] - fn test_active_subscription_drop() { - let (tx, rx) = mpsc::channel::<(SubId, ())>(10); - let sub_id = SubId::from("test_sub_id"); - let indexes: Vec> = vec![Index::from(("test".to_string(), sub_id.clone()))]; - let (drop_tx, mut drop_rx) = mpsc::channel(10); - - { - let _active_subscription = ActiveSubscription { - sub_id: sub_id.clone(), - indexes, - receiver: rx, - drop: drop_tx, - }; - // When it goes out of scope, it should notify - } - assert_eq!(drop_rx.try_recv().unwrap().0, sub_id); // it should have notified - assert!(tx.try_send(("foo".into(), ())).is_err()); // subscriber is dropped - } -} diff --git a/crates/cdk/src/wallet/mod.rs b/crates/cdk/src/wallet/mod.rs index 5f2319f25..6ac0f14db 100644 --- a/crates/cdk/src/wallet/mod.rs +++ b/crates/cdk/src/wallet/mod.rs @@ -6,7 +6,7 @@ use std::sync::Arc; use cdk_common::amount::FeeAndAmounts; use cdk_common::database::{self, WalletDatabase}; -use cdk_common::subscription::Params; +use cdk_common::subscription::WalletParams; use getrandom::getrandom; use subscription::{ActiveSubscription, SubscriptionManager}; #[cfg(feature = "auth")] @@ -108,40 +108,42 @@ pub enum WalletSubscription { Bolt12MintQuoteState(Vec), } -impl From for Params { +impl From for WalletParams { fn from(val: WalletSubscription) -> Self { let mut buffer = vec![0u8; 10]; getrandom(&mut buffer).expect("Failed to generate random bytes"); - let id = buffer - .iter() - .map(|&byte| { - let index = byte as usize % ALPHANUMERIC.len(); // 62 alphanumeric characters (A-Z, a-z, 0-9) - ALPHANUMERIC[index] as char - }) - .collect::(); + let id = Arc::new( + buffer + .iter() + .map(|&byte| { + let index = byte as usize % ALPHANUMERIC.len(); // 62 alphanumeric characters (A-Z, a-z, 0-9) + ALPHANUMERIC[index] as char + }) + .collect::(), + ); match val { - WalletSubscription::ProofState(filters) => Params { + WalletSubscription::ProofState(filters) => WalletParams { filters, kind: Kind::ProofState, - id: id.into(), + id, }, - WalletSubscription::Bolt11MintQuoteState(filters) => Params { + WalletSubscription::Bolt11MintQuoteState(filters) => WalletParams { filters, kind: Kind::Bolt11MintQuote, - id: id.into(), + id, }, - WalletSubscription::Bolt11MeltQuoteState(filters) => Params { + WalletSubscription::Bolt11MeltQuoteState(filters) => WalletParams { filters, kind: Kind::Bolt11MeltQuote, - id: id.into(), + id, }, - WalletSubscription::Bolt12MintQuoteState(filters) => Params { + WalletSubscription::Bolt12MintQuoteState(filters) => WalletParams { filters, kind: Kind::Bolt12MintQuote, - id: id.into(), + id, }, } } @@ -193,10 +195,10 @@ impl Wallet { } /// Subscribe to events - pub async fn subscribe>(&self, query: T) -> ActiveSubscription { + pub async fn subscribe>(&self, query: T) -> ActiveSubscription { self.subscription - .subscribe(self.mint_url.clone(), query.into(), Arc::new(self.clone())) - .await + .subscribe(self.mint_url.clone(), query.into()) + .expect("FIXME") } /// Fee required for proof set diff --git a/crates/cdk/src/wallet/multi_mint_wallet.rs b/crates/cdk/src/wallet/multi_mint_wallet.rs index 9534f1a13..1b5ec3f3b 100644 --- a/crates/cdk/src/wallet/multi_mint_wallet.rs +++ b/crates/cdk/src/wallet/multi_mint_wallet.rs @@ -4,6 +4,7 @@ //! pairs use std::collections::BTreeMap; +use std::ops::Deref; use std::str::FromStr; use std::sync::Arc; @@ -675,7 +676,7 @@ impl MultiMintWallet { // Check if this is a mint quote response with paid state if let crate::nuts::nut17::NotificationPayload::MintQuoteBolt11Response( quote_response, - ) = notification + ) = notification.deref() { if quote_response.state == QuoteState::Paid { // Quote is paid, now mint the tokens @@ -1264,7 +1265,7 @@ impl MultiMintWallet { /// Melt (pay invoice) with automatic wallet selection (deprecated, use specific mint functions for better control) /// /// Automatically selects the best wallet to pay from based on: - /// - Available balance + /// - Available balance /// - Fees /// /// # Examples diff --git a/crates/cdk/src/wallet/streams/payment.rs b/crates/cdk/src/wallet/streams/payment.rs index 8139570ae..354e0611c 100644 --- a/crates/cdk/src/wallet/streams/payment.rs +++ b/crates/cdk/src/wallet/streams/payment.rs @@ -13,10 +13,11 @@ use futures::{FutureExt, Stream, StreamExt}; use tokio_util::sync::CancellationToken; use super::RecvFuture; +use crate::event::MintEvent; use crate::wallet::subscription::ActiveSubscription; use crate::{Wallet, WalletSubscription}; -type SubscribeReceived = (Option>, Vec); +type SubscribeReceived = (Option>, Vec); type PaymentValue = (String, Option); /// PaymentWaiter @@ -145,7 +146,7 @@ impl<'a> PaymentStream<'a> { Poll::Ready(None) } Some(info) => { - match info { + match info.into_inner() { NotificationPayload::MintQuoteBolt11Response(info) => { if info.state == MintQuoteState::Paid { self.is_finalized = true; diff --git a/crates/cdk/src/wallet/subscription/http.rs b/crates/cdk/src/wallet/subscription/http.rs deleted file mode 100644 index bbf2021c8..000000000 --- a/crates/cdk/src/wallet/subscription/http.rs +++ /dev/null @@ -1,238 +0,0 @@ -use std::collections::HashMap; -use std::sync::Arc; - -use cdk_common::MintQuoteBolt12Response; -use tokio::sync::{mpsc, RwLock}; -#[cfg(not(target_arch = "wasm32"))] -use tokio::time; -use web_time::Duration; - -use super::WsSubscriptionBody; -use crate::nuts::nut17::Kind; -use crate::nuts::{nut01, nut05, nut07, nut23, CheckStateRequest, NotificationPayload}; -use crate::pub_sub::SubId; -use crate::wallet::MintConnector; -use crate::Wallet; - -#[derive(Debug, Hash, PartialEq, Eq)] -enum UrlType { - Mint(String), - MintBolt12(String), - Melt(String), - PublicKey(nut01::PublicKey), -} - -#[derive(Debug, Eq, PartialEq)] -enum AnyState { - MintQuoteState(nut23::QuoteState), - MintBolt12QuoteState(MintQuoteBolt12Response), - MeltQuoteState(nut05::QuoteState), - PublicKey(nut07::State), - Empty, -} - -type SubscribedTo = HashMap>, SubId, AnyState)>; - -async fn convert_subscription( - sub_id: SubId, - subscriptions: &Arc>>, - subscribed_to: &mut SubscribedTo, -) -> Option<()> { - let subscription = subscriptions.read().await; - let sub = subscription.get(&sub_id)?; - tracing::debug!("New subscription: {:?}", sub); - match sub.1.kind { - Kind::Bolt11MintQuote => { - for id in sub.1.filters.iter().map(|id| UrlType::Mint(id.clone())) { - subscribed_to.insert(id, (sub.0.clone(), sub.1.id.clone(), AnyState::Empty)); - } - } - Kind::Bolt11MeltQuote => { - for id in sub.1.filters.iter().map(|id| UrlType::Melt(id.clone())) { - subscribed_to.insert(id, (sub.0.clone(), sub.1.id.clone(), AnyState::Empty)); - } - } - Kind::ProofState => { - for id in sub - .1 - .filters - .iter() - .map(|id| nut01::PublicKey::from_hex(id).map(UrlType::PublicKey)) - { - match id { - Ok(id) => { - subscribed_to - .insert(id, (sub.0.clone(), sub.1.id.clone(), AnyState::Empty)); - } - Err(err) => { - tracing::error!("Error parsing public key: {:?}. Subscription ignored, will never yield any result", err); - } - } - } - } - Kind::Bolt12MintQuote => { - for id in sub - .1 - .filters - .iter() - .map(|id| UrlType::MintBolt12(id.clone())) - { - subscribed_to.insert(id, (sub.0.clone(), sub.1.id.clone(), AnyState::Empty)); - } - } - } - - Some(()) -} - -#[cfg(not(target_arch = "wasm32"))] -#[inline] -pub async fn http_main>( - initial_state: S, - http_client: Arc, - subscriptions: Arc>>, - mut new_subscription_recv: mpsc::Receiver, - mut on_drop: mpsc::Receiver, - _wallet: Arc, -) { - let mut interval = time::interval(Duration::from_secs(2)); - let mut subscribed_to = SubscribedTo::new(); - - for sub_id in initial_state { - convert_subscription(sub_id, &subscriptions, &mut subscribed_to).await; - } - - loop { - tokio::select! { - _ = interval.tick() => { - poll_subscriptions(&http_client, &mut subscribed_to).await; - } - Some(subid) = new_subscription_recv.recv() => { - convert_subscription(subid, &subscriptions, &mut subscribed_to).await; - } - Some(id) = on_drop.recv() => { - subscribed_to.retain(|_, (_, sub_id, _)| *sub_id != id); - } - } - } -} - -#[cfg(target_arch = "wasm32")] -#[inline] -pub async fn http_main>( - initial_state: S, - http_client: Arc, - subscriptions: Arc>>, - mut new_subscription_recv: mpsc::Receiver, - mut on_drop: mpsc::Receiver, - _wallet: Arc, -) { - let mut subscribed_to = SubscribedTo::new(); - - for sub_id in initial_state { - convert_subscription(sub_id, &subscriptions, &mut subscribed_to).await; - } - - loop { - tokio::select! { - _ = gloo_timers::future::sleep(Duration::from_secs(2)) => { - poll_subscriptions(&http_client, &mut subscribed_to).await; - } - subid = new_subscription_recv.recv() => { - match subid { - Some(subid) => { - convert_subscription(subid, &subscriptions, &mut subscribed_to).await; - } - None => { - // New subscription channel closed - SubscriptionClient was dropped, terminate worker - break; - } - } - } - id = on_drop.recv() => { - match id { - Some(id) => { - subscribed_to.retain(|_, (_, sub_id, _)| *sub_id != id); - } - None => { - // Drop notification channel closed - SubscriptionClient was dropped, terminate worker - break; - } - } - } - } - } -} - -async fn poll_subscriptions( - http_client: &Arc, - subscribed_to: &mut SubscribedTo, -) { - for (url, (sender, _, last_state)) in subscribed_to.iter_mut() { - tracing::debug!("Polling: {:?}", url); - match url { - UrlType::MintBolt12(id) => { - let response = http_client.get_mint_quote_bolt12_status(id).await; - if let Ok(response) = response { - if *last_state == AnyState::MintBolt12QuoteState(response.clone()) { - continue; - } - *last_state = AnyState::MintBolt12QuoteState(response.clone()); - if let Err(err) = - sender.try_send(NotificationPayload::MintQuoteBolt12Response(response)) - { - tracing::error!("Error sending mint quote response: {:?}", err); - } - } - } - UrlType::Mint(id) => { - let response = http_client.get_mint_quote_status(id).await; - if let Ok(response) = response { - if *last_state == AnyState::MintQuoteState(response.state) { - continue; - } - *last_state = AnyState::MintQuoteState(response.state); - if let Err(err) = - sender.try_send(NotificationPayload::MintQuoteBolt11Response(response)) - { - tracing::error!("Error sending mint quote response: {:?}", err); - } - } - } - UrlType::Melt(id) => { - let response = http_client.get_melt_quote_status(id).await; - if let Ok(response) = response { - if *last_state == AnyState::MeltQuoteState(response.state) { - continue; - } - *last_state = AnyState::MeltQuoteState(response.state); - if let Err(err) = - sender.try_send(NotificationPayload::MeltQuoteBolt11Response(response)) - { - tracing::error!("Error sending melt quote response: {:?}", err); - } - } - } - UrlType::PublicKey(id) => { - let responses = http_client - .post_check_state(CheckStateRequest { ys: vec![*id] }) - .await; - if let Ok(mut responses) = responses { - let response = if let Some(state) = responses.states.pop() { - state - } else { - continue; - }; - - if *last_state == AnyState::PublicKey(response.state) { - continue; - } - *last_state = AnyState::PublicKey(response.state); - if let Err(err) = sender.try_send(NotificationPayload::ProofState(response)) { - tracing::error!("Error sending proof state response: {:?}", err); - } - } - } - } - } -} diff --git a/crates/cdk/src/wallet/subscription/mod.rs b/crates/cdk/src/wallet/subscription/mod.rs index 12143c382..a367b05de 100644 --- a/crates/cdk/src/wallet/subscription/mod.rs +++ b/crates/cdk/src/wallet/subscription/mod.rs @@ -7,28 +7,33 @@ //! the HTTP client. use std::collections::HashMap; use std::fmt::Debug; +use std::sync::atomic::AtomicUsize; use std::sync::Arc; -use cdk_common::subscription::Params; -use tokio::sync::{mpsc, RwLock}; -use tokio::task::JoinHandle; -#[cfg(target_arch = "wasm32")] -use wasm_bindgen_futures; - -use super::Wallet; +use cdk_common::nut17::ws::{WsMethodRequest, WsRequest, WsUnsubscribeRequest}; +use cdk_common::nut17::{Kind, NotificationId}; +use cdk_common::parking_lot::RwLock; +use cdk_common::pub_sub::remote_consumer::{ + Consumer, InternalRelay, RemoteActiveConsumer, StreamCtrl, SubscribeMessage, Transport, +}; +use cdk_common::pub_sub::{Error as PubsubError, Spec, Subscriber}; +use cdk_common::subscription::WalletParams; +use cdk_common::CheckStateRequest; +use tokio::sync::mpsc; +use uuid::Uuid; + +use crate::event::MintEvent; use crate::mint_url::MintUrl; -use crate::pub_sub::SubId; use crate::wallet::MintConnector; -mod http; -#[cfg(all( - not(feature = "http_subscription"), - feature = "mint", - not(target_arch = "wasm32") -))] +#[cfg(not(target_arch = "wasm32"))] mod ws; -type WsSubscriptionBody = (mpsc::Sender, Params); +/// Notification Payload +pub type NotificationPayload = crate::nuts::NotificationPayload; + +/// Type alias +pub type ActiveSubscription = RemoteActiveConsumer; /// Subscription manager /// @@ -45,13 +50,27 @@ type WsSubscriptionBody = (mpsc::Sender, Params); /// The subscribers have a simple-to-use interface, receiving an /// ActiveSubscription struct, which can be used to receive updates and to /// unsubscribe from updates automatically on the drop. -#[derive(Debug, Clone)] +#[derive(Clone)] pub struct SubscriptionManager { - all_connections: Arc>>, + all_connections: Arc>>>>, http_client: Arc, prefer_http: bool, } +impl Debug for SubscriptionManager { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + write!( + f, + "Subscription Manager connected to {:?}", + self.all_connections + .write() + .keys() + .cloned() + .collect::>() + ) + } +} + impl SubscriptionManager { /// Create a new subscription manager pub fn new(http_client: Arc, prefer_http: bool) -> Self { @@ -63,291 +82,235 @@ impl SubscriptionManager { } /// Subscribe to updates from a mint server with a given filter - pub async fn subscribe( + pub fn subscribe( &self, mint_url: MintUrl, - filter: Params, - wallet: Arc, - ) -> ActiveSubscription { - let subscription_clients = self.all_connections.read().await; - let id = filter.id.clone(); - if let Some(subscription_client) = subscription_clients.get(&mint_url) { - let (on_drop_notif, receiver) = subscription_client.subscribe(filter).await; - ActiveSubscription::new(receiver, id, on_drop_notif) - } else { - drop(subscription_clients); - - #[cfg(all( - not(feature = "http_subscription"), - feature = "mint", - not(target_arch = "wasm32") - ))] - let is_ws_support = self - .http_client - .get_mint_info() - .await - .map(|info| !info.nuts.nut17.supported.is_empty()) - .unwrap_or_default(); - - #[cfg(any( - feature = "http_subscription", - not(feature = "mint"), - target_arch = "wasm32" - ))] - let is_ws_support = false; - - let is_ws_support = if self.prefer_http { - false - } else { - is_ws_support - }; - - tracing::debug!( - "Connect to {:?} to subscribe. WebSocket is supported ({})", - mint_url, - is_ws_support - ); - - let mut subscription_clients = self.all_connections.write().await; - let subscription_client = SubscriptionClient::new( - mint_url.clone(), - self.http_client.clone(), - is_ws_support, - wallet, - ); - let (on_drop_notif, receiver) = subscription_client.subscribe(filter).await; - subscription_clients.insert(mint_url, subscription_client); - - ActiveSubscription::new(receiver, id, on_drop_notif) - } + filter: WalletParams, + ) -> Result, PubsubError> { + self.all_connections + .write() + .entry(mint_url.clone()) + .or_insert_with(|| { + Consumer::new( + SubscriptionClient { + mint_url, + http_client: self.http_client.clone(), + req_id: 0.into(), + }, + self.prefer_http, + (), + ) + }) + .subscribe(filter) } } -/// Subscription client -/// -/// If the server supports WebSocket subscriptions, this client will be used, -/// otherwise the HTTP pool and pause will be used (which is the less efficient -/// method). -#[derive(Debug)] -pub struct SubscriptionClient { - new_subscription_notif: mpsc::Sender, - on_drop_notif: mpsc::Sender, - subscriptions: Arc>>, - worker: Option>, -} +/// MintSubTopics +#[derive(Clone, Default)] +pub struct MintSubTopics {} -type NotificationPayload = crate::nuts::NotificationPayload; +#[async_trait::async_trait] +impl Spec for MintSubTopics { + type SubscriptionId = String; -/// Active Subscription -pub struct ActiveSubscription { - sub_id: Option, - on_drop_notif: mpsc::Sender, - receiver: mpsc::Receiver, -} + type Event = MintEvent; -impl ActiveSubscription { - fn new( - receiver: mpsc::Receiver, - sub_id: SubId, - on_drop_notif: mpsc::Sender, - ) -> Self { - Self { - sub_id: Some(sub_id), - on_drop_notif, - receiver, - } - } + type Topic = NotificationId; - /// Try to receive a notification - pub fn try_recv(&mut self) -> Result, Error> { - match self.receiver.try_recv() { - Ok(payload) => Ok(Some(payload)), - Err(mpsc::error::TryRecvError::Empty) => Ok(None), - Err(mpsc::error::TryRecvError::Disconnected) => Err(Error::Disconnected), - } - } + type Context = (); - /// Receive a notification asynchronously - pub async fn recv(&mut self) -> Option { - self.receiver.recv().await + fn new_instance(_context: Self::Context) -> Arc + where + Self: Sized, + { + Arc::new(Self {}) } -} -impl Drop for ActiveSubscription { - fn drop(&mut self) { - if let Some(sub_id) = self.sub_id.take() { - let _ = self.on_drop_notif.try_send(sub_id); - } + async fn fetch_events(self: &Arc, _topics: Vec, _reply_to: Subscriber) + where + Self: Sized, + { } } -/// Subscription client error -#[derive(thiserror::Error, Debug)] -pub enum Error { - /// Url error - #[error("Could not join paths: {0}")] - Url(#[from] crate::mint_url::Error), - /// Disconnected from the notification channel - #[error("Disconnected from the notification channel")] - Disconnected, +/// Subscription client +/// +/// If the server supports WebSocket subscriptions, this client will be used, +/// otherwise the HTTP pool and pause will be used (which is the less efficient +/// method). +#[derive(Debug)] +#[allow(dead_code)] +pub struct SubscriptionClient { + http_client: Arc, + mint_url: MintUrl, + req_id: AtomicUsize, } +#[allow(dead_code)] impl SubscriptionClient { - /// Create new [`SubscriptionClient`] - pub fn new( - url: MintUrl, - http_client: Arc, - prefer_ws_method: bool, - wallet: Arc, - ) -> Self { - let subscriptions = Arc::new(RwLock::new(HashMap::new())); - let (new_subscription_notif, new_subscription_recv) = mpsc::channel(100); - let (on_drop_notif, on_drop_recv) = mpsc::channel(1000); + fn get_sub_request( + &self, + id: String, + params: NotificationId, + ) -> Option<(usize, String)> { + let (kind, filter) = match params { + NotificationId::ProofState(x) => (Kind::ProofState, x.to_string()), + NotificationId::MeltQuoteBolt11(q) | NotificationId::MeltQuoteBolt12(q) => { + (Kind::Bolt11MeltQuote, q) + } + NotificationId::MintQuoteBolt11(q) => (Kind::Bolt11MintQuote, q), + NotificationId::MintQuoteBolt12(q) => (Kind::Bolt12MintQuote, q), + }; + + let request: WsRequest<_> = ( + WsMethodRequest::Subscribe(WalletParams { + kind, + filters: vec![filter], + id: id.into(), + }), + self.req_id + .fetch_add(1, std::sync::atomic::Ordering::Relaxed), + ) + .into(); + + serde_json::to_string(&request) + .inspect_err(|err| { + tracing::error!("Could not serialize subscribe message: {:?}", err); + }) + .map(|json| (request.id, json)) + .ok() + } - Self { - new_subscription_notif, - on_drop_notif, - subscriptions: subscriptions.clone(), - worker: Self::start_worker( - prefer_ws_method, - http_client, - url, - subscriptions, - new_subscription_recv, - on_drop_recv, - wallet, - ), + fn get_unsub_request(&self, sub_id: String) -> Option { + let request: WsRequest<_> = ( + WsMethodRequest::Unsubscribe(WsUnsubscribeRequest { sub_id }), + self.req_id + .fetch_add(1, std::sync::atomic::Ordering::Relaxed), + ) + .into(); + + match serde_json::to_string(&request) { + Ok(json) => Some(json), + Err(err) => { + tracing::error!("Could not serialize unsubscribe message: {:?}", err); + None + } } } +} - #[allow(unused_variables)] - fn start_worker( - prefer_ws_method: bool, - http_client: Arc, - url: MintUrl, - subscriptions: Arc>>, - new_subscription_recv: mpsc::Receiver, - on_drop_recv: mpsc::Receiver, - wallet: Arc, - ) -> Option> { - #[cfg(any( - feature = "http_subscription", - not(feature = "mint"), - target_arch = "wasm32" - ))] - return Self::http_worker( - http_client, - subscriptions, - new_subscription_recv, - on_drop_recv, - wallet, - ); - - #[cfg(all( - not(feature = "http_subscription"), - feature = "mint", - not(target_arch = "wasm32") - ))] - if prefer_ws_method { - Self::ws_worker( - http_client, - url, - subscriptions, - new_subscription_recv, - on_drop_recv, - wallet, - ) - } else { - Self::http_worker( - http_client, - subscriptions, - new_subscription_recv, - on_drop_recv, - wallet, - ) - } +#[cfg_attr(target_arch = "wasm32", async_trait::async_trait(?Send))] +#[cfg_attr(not(target_arch = "wasm32"), async_trait::async_trait)] +impl Transport for SubscriptionClient { + type Spec = MintSubTopics; + + fn new_name(&self) -> ::SubscriptionId { + Uuid::new_v4().to_string() } - /// Subscribe to a WebSocket channel - pub async fn subscribe( + async fn stream( &self, - filter: Params, - ) -> (mpsc::Sender, mpsc::Receiver) { - let mut subscriptions = self.subscriptions.write().await; - let id = filter.id.clone(); + _ctrls: mpsc::Receiver>, + _topics: Vec>, + _reply_to: InternalRelay, + ) -> Result<(), PubsubError> { + #[cfg(not(target_arch = "wasm32"))] + let r = ws::stream_client(self, _ctrls, _topics, _reply_to).await; - let (sender, receiver) = mpsc::channel(10_000); - subscriptions.insert(id.clone(), (sender, filter)); - drop(subscriptions); + #[cfg(target_arch = "wasm32")] + let r = Err(PubsubError::NotSupported); - let _ = self.new_subscription_notif.send(id).await; - (self.on_drop_notif.clone(), receiver) + r } - /// HTTP subscription client - /// - /// This is a poll based subscription, where the client will poll the server - /// from time to time to get updates, notifying the subscribers on changes - fn http_worker( - http_client: Arc, - subscriptions: Arc>>, - new_subscription_recv: mpsc::Receiver, - on_drop: mpsc::Receiver, - wallet: Arc, - ) -> Option> { - let http_worker = http::http_main( - vec![], - http_client, - subscriptions, - new_subscription_recv, - on_drop, - wallet, - ); - - #[cfg(target_arch = "wasm32")] - { - wasm_bindgen_futures::spawn_local(http_worker); - None + /// Poll on demand + async fn poll( + &self, + topics: Vec>, + reply_to: InternalRelay, + ) -> Result<(), PubsubError> { + let proofs = topics + .iter() + .filter_map(|(_, x)| match &x { + NotificationId::ProofState(p) => Some(*p), + _ => None, + }) + .collect::>(); + + if !proofs.is_empty() { + for state in self + .http_client + .post_check_state(CheckStateRequest { ys: proofs }) + .await + .map_err(|e| PubsubError::Internal(Box::new(e)))? + .states + { + reply_to.send(MintEvent::new(NotificationPayload::ProofState(state))); + } } - #[cfg(not(target_arch = "wasm32"))] + for topic in topics + .into_iter() + .map(|(_, x)| x) + .filter(|x| !matches!(x, NotificationId::ProofState(_))) { - Some(tokio::spawn(http_worker)) + match topic { + NotificationId::MintQuoteBolt11(id) => { + let response = match self.http_client.get_mint_quote_status(&id).await { + Ok(success) => success, + Err(err) => { + tracing::error!("Error with MintBolt11 {} with {:?}", id, err); + continue; + } + }; + + reply_to.send(MintEvent::new( + NotificationPayload::MintQuoteBolt11Response(response.clone()), + )); + } + NotificationId::MeltQuoteBolt11(id) => { + let response = match self.http_client.get_melt_quote_status(&id).await { + Ok(success) => success, + Err(err) => { + tracing::error!("Error with MeltBolt11 {} with {:?}", id, err); + continue; + } + }; + + reply_to.send(MintEvent::new( + NotificationPayload::MeltQuoteBolt11Response(response), + )); + } + NotificationId::MintQuoteBolt12(id) => { + let response = match self.http_client.get_mint_quote_bolt12_status(&id).await { + Ok(success) => success, + Err(err) => { + tracing::error!("Error with MintBolt12 {} with {:?}", id, err); + continue; + } + }; + + reply_to.send(MintEvent::new( + NotificationPayload::MintQuoteBolt12Response(response), + )); + } + NotificationId::MeltQuoteBolt12(id) => { + let response = match self.http_client.get_melt_bolt12_quote_status(&id).await { + Ok(success) => success, + Err(err) => { + tracing::error!("Error with MeltBolt12 {} with {:?}", id, err); + continue; + } + }; + + reply_to.send(MintEvent::new( + NotificationPayload::MeltQuoteBolt11Response(response), + )); + } + _ => {} + } } - } - - /// WebSocket subscription client - /// - /// This is a WebSocket based subscription, where the client will connect to - /// the server and stay there idle waiting for server-side notifications - #[cfg(all( - not(feature = "http_subscription"), - feature = "mint", - not(target_arch = "wasm32") - ))] - fn ws_worker( - http_client: Arc, - url: MintUrl, - subscriptions: Arc>>, - new_subscription_recv: mpsc::Receiver, - on_drop: mpsc::Receiver, - wallet: Arc, - ) -> Option> { - Some(tokio::spawn(ws::ws_main( - http_client, - url, - subscriptions, - new_subscription_recv, - on_drop, - wallet, - ))) - } -} -impl Drop for SubscriptionClient { - fn drop(&mut self) { - if let Some(handle) = self.worker.take() { - handle.abort(); - } + Ok(()) } } diff --git a/crates/cdk/src/wallet/subscription/ws.rs b/crates/cdk/src/wallet/subscription/ws.rs index 0fbed7546..1c3198291 100644 --- a/crates/cdk/src/wallet/subscription/ws.rs +++ b/crates/cdk/src/wallet/subscription/ws.rs @@ -1,38 +1,25 @@ -use std::collections::{HashMap, HashSet}; -use std::sync::atomic::AtomicUsize; -use std::sync::Arc; -use std::time::Duration; - -use cdk_common::subscription::Params; -use cdk_common::ws::{WsMessageOrResponse, WsMethodRequest, WsRequest, WsUnsubscribeRequest}; +use cdk_common::nut17::ws::WsMessageOrResponse; +use cdk_common::pub_sub::remote_consumer::{InternalRelay, StreamCtrl, SubscribeMessage}; +use cdk_common::pub_sub::Error as PubsubError; #[cfg(feature = "auth")] use cdk_common::{Method, RoutePath}; use futures::{SinkExt, StreamExt}; -use tokio::sync::{mpsc, RwLock}; -use tokio::time::sleep; +use tokio::sync::mpsc; use tokio_tungstenite::connect_async; use tokio_tungstenite::tungstenite::client::IntoClientRequest; use tokio_tungstenite::tungstenite::Message; -use super::http::http_main; -use super::WsSubscriptionBody; -use crate::mint_url::MintUrl; -use crate::pub_sub::SubId; -use crate::wallet::MintConnector; -use crate::Wallet; - -const MAX_ATTEMPT_FALLBACK_HTTP: usize = 10; - -#[inline] -pub async fn ws_main( - http_client: Arc, - mint_url: MintUrl, - subscriptions: Arc>>, - mut new_subscription_recv: mpsc::Receiver, - mut on_drop: mpsc::Receiver, - wallet: Arc, -) { - let mut url = mint_url +use super::{MintSubTopics, SubscriptionClient}; + +#[inline(always)] +pub(crate) async fn stream_client( + client: &SubscriptionClient, + mut ctrl: mpsc::Receiver>, + topics: Vec>, + reply_to: InternalRelay, +) -> Result<(), PubsubError> { + let mut url = client + .mint_url .join_paths(&["v1", "ws"]) .expect("Could not join paths"); @@ -42,241 +29,140 @@ pub async fn ws_main( url.set_scheme("ws").expect("Could not set scheme"); } - let request = match url.to_string().into_client_request() { - Ok(req) => req, - Err(err) => { - tracing::error!("Failed to create client request: {:?}", err); - // Fallback to HTTP client if we can't create the WebSocket request - return http_main( - std::iter::empty(), - http_client, - subscriptions, - new_subscription_recv, - on_drop, - wallet, - ) - .await; - } - }; - - let mut active_subscriptions = HashMap::>::new(); - let mut failure_count = 0; - - loop { - if subscriptions.read().await.is_empty() { - // No active subscription - sleep(Duration::from_millis(100)).await; - continue; - } - - let mut request_clone = request.clone(); - #[cfg(feature = "auth")] - { - let auth_wallet = http_client.get_auth_wallet().await; - let token = match auth_wallet.as_ref() { - Some(auth_wallet) => { - let endpoint = cdk_common::ProtectedEndpoint::new(Method::Get, RoutePath::Ws); - match auth_wallet.get_auth_for_request(&endpoint).await { - Ok(token) => token, - Err(err) => { - tracing::warn!("Failed to get auth token: {:?}", err); - None - } - } - } - None => None, - }; - - if let Some(auth_token) = token { - let header_key = match &auth_token { - cdk_common::AuthToken::ClearAuth(_) => "Clear-auth", - cdk_common::AuthToken::BlindAuth(_) => "Blind-auth", - }; - - match auth_token.to_string().parse() { - Ok(header_value) => { - request_clone.headers_mut().insert(header_key, header_value); - } + #[cfg(not(feature = "auth"))] + let request = url.to_string().into_client_request().map_err(|err| { + tracing::error!("Failed to create client request: {:?}", err); + // Fallback to HTTP client if we can't create the WebSocket request + cdk_common::pub_sub::Error::NotSupported + })?; + + #[cfg(feature = "auth")] + let mut request = url.to_string().into_client_request().map_err(|err| { + tracing::error!("Failed to create client request: {:?}", err); + // Fallback to HTTP client if we can't create the WebSocket request + cdk_common::pub_sub::Error::NotSupported + })?; + + #[cfg(feature = "auth")] + { + let auth_wallet = client.http_client.get_auth_wallet().await; + let token = match auth_wallet.as_ref() { + Some(auth_wallet) => { + let endpoint = cdk_common::ProtectedEndpoint::new(Method::Get, RoutePath::Ws); + match auth_wallet.get_auth_for_request(&endpoint).await { + Ok(token) => token, Err(err) => { - tracing::warn!("Failed to parse auth token as header value: {:?}", err); + tracing::warn!("Failed to get auth token: {:?}", err); + None } } } - } - - tracing::debug!("Connecting to {}", url); - let ws_stream = match connect_async(request_clone.clone()).await { - Ok((ws_stream, _)) => ws_stream, - Err(err) => { - failure_count += 1; - tracing::error!("Could not connect to server: {:?}", err); - if failure_count > MAX_ATTEMPT_FALLBACK_HTTP { - tracing::error!( - "Could not connect to server after {MAX_ATTEMPT_FALLBACK_HTTP} attempts, falling back to HTTP-subscription client" - ); - - return http_main( - active_subscriptions.into_keys(), - http_client, - subscriptions, - new_subscription_recv, - on_drop, - wallet, - ) - .await; - } - continue; - } + None => None, }; - tracing::debug!("Connected to {}", url); - - let (mut write, mut read) = ws_stream.split(); - let req_id = AtomicUsize::new(0); - let get_sub_request = |params: Params| -> Option<(usize, String)> { - let request: WsRequest = ( - WsMethodRequest::Subscribe(params), - req_id.fetch_add(1, std::sync::atomic::Ordering::Relaxed), - ) - .into(); + if let Some(auth_token) = token { + let header_key = match &auth_token { + cdk_common::AuthToken::ClearAuth(_) => "Clear-auth", + cdk_common::AuthToken::BlindAuth(_) => "Blind-auth", + }; - match serde_json::to_string(&request) { - Ok(json) => Some((request.id, json)), - Err(err) => { - tracing::error!("Could not serialize subscribe message: {:?}", err); - None + match auth_token.to_string().parse() { + Ok(header_value) => { + request.headers_mut().insert(header_key, header_value); } - } - }; - - let get_unsub_request = |sub_id: SubId| -> Option { - let request: WsRequest = ( - WsMethodRequest::Unsubscribe(WsUnsubscribeRequest { sub_id }), - req_id.fetch_add(1, std::sync::atomic::Ordering::Relaxed), - ) - .into(); - - match serde_json::to_string(&request) { - Ok(json) => Some(json), Err(err) => { - tracing::error!("Could not serialize unsubscribe message: {:?}", err); - None + tracing::warn!("Failed to parse auth token as header value: {:?}", err); } } - }; - - // Websocket reconnected, restore all subscriptions - let mut subscription_requests = HashSet::new(); - - let read_subscriptions = subscriptions.read().await; - for (sub_id, _) in active_subscriptions.iter() { - if let Some(Some((req_id, req))) = read_subscriptions - .get(sub_id) - .map(|(_, params)| get_sub_request(params.clone())) - { - let _ = write.send(Message::Text(req.into())).await; - subscription_requests.insert(req_id); - } } - drop(read_subscriptions); - - loop { - tokio::select! { - Some(msg) = read.next() => { - let msg = match msg { - Ok(msg) => msg, - Err(_) => { - if let Err(err) = write.send(Message::Close(None)).await { - tracing::error!("Closing error {err:?}"); - } - break - }, - }; - let msg = match msg { - Message::Text(msg) => msg, - _ => continue, - }; - let msg = match serde_json::from_str::(&msg) { - Ok(msg) => msg, - Err(_) => continue, - }; + } - match msg { - WsMessageOrResponse::Notification(payload) => { - tracing::debug!("Received notification from server: {:?}", payload); - let _ = active_subscriptions.get(&payload.params.sub_id).map(|sender| { - let _ = sender.try_send(payload.params.payload); - }); - } - WsMessageOrResponse::Response(response) => { - tracing::debug!("Received response from server: {:?}", response); - subscription_requests.remove(&response.id); - // reset connection failure after a successful response from the serer - failure_count = 0; - } - WsMessageOrResponse::ErrorResponse(error) => { - tracing::error!("Received error from server: {:?}", error); + tracing::debug!("Connecting to {}", url); + let ws_stream = connect_async(request) + .await + .map(|(ws_stream, _)| ws_stream) + .map_err(|err| { + tracing::error!("Error connecting: {err:?}"); - if subscription_requests.contains(&error.id) { - failure_count += 1; - if failure_count > MAX_ATTEMPT_FALLBACK_HTTP { - tracing::error!( - "Falling back to HTTP client" - ); + cdk_common::pub_sub::Error::Internal(Box::new(err)) + })?; - return http_main( - active_subscriptions.into_keys(), - http_client, - subscriptions, - new_subscription_recv, - on_drop, - wallet, - ) - .await; - } + tracing::debug!("Connected to {}", url); + let (mut write, mut read) = ws_stream.split(); - if let Err(err) = write.send(Message::Close(None)).await { - tracing::error!("Closing error {err:?}"); - } + for (name, index) in topics { + let (_, req) = if let Some(req) = client.get_sub_request(name, index) { + req + } else { + continue; + }; - break; // break connection to force a reconnection, to attempt to recover form this error - } - } - } + let _ = write.send(Message::Text(req.into())).await; + } - } - Some(subid) = new_subscription_recv.recv() => { - let subscription = subscriptions.read().await; - let sub = if let Some(subscription) = subscription.get(&subid) { - subscription - } else { - continue - }; - tracing::debug!("Subscribing to {:?}", sub.1); - active_subscriptions.insert(subid, sub.0.clone()); - if let Some((req_id, json)) = get_sub_request(sub.1.clone()) { - let _ = write.send(Message::Text(json.into())).await; - subscription_requests.insert(req_id); + loop { + tokio::select! { + Some(msg) = ctrl.recv() => { + match msg { + StreamCtrl::Subscribe(msg) => { + let (_, req) = if let Some(req) = client.get_sub_request(msg.0, msg.1) { + req + } else { + continue; + }; + let _ = write.send(Message::Text(req.into())).await; } - }, - Some(subid) = on_drop.recv() => { - let mut subscription = subscriptions.write().await; - if let Some(sub) = subscription.remove(&subid) { - drop(sub); + StreamCtrl::Unsubscribe(msg) => { + let req = if let Some(req) = client.get_unsub_request(msg) { + req + } else { + continue; + }; + let _ = write.send(Message::Text(req.into())).await; } - tracing::debug!("Unsubscribing from {:?}", subid); - if let Some(json) = get_unsub_request(subid) { - let _ = write.send(Message::Text(json.into())).await; + StreamCtrl::Stop => { + if let Err(err) = write.send(Message::Close(None)).await { + tracing::error!("Closing error {err:?}"); + } + break; } - - if subscription.is_empty() { + }; + } + Some(msg) = read.next() => { + let msg = match msg { + Ok(msg) => msg, + Err(_) => { if let Err(err) = write.send(Message::Close(None)).await { tracing::error!("Closing error {err:?}"); } break; } + }; + let msg = match msg { + Message::Text(msg) => msg, + _ => continue, + }; + let msg = match serde_json::from_str::>(&msg) { + Ok(msg) => msg, + Err(_) => continue, + }; + + match msg { + WsMessageOrResponse::Notification(payload) => { + reply_to.send(payload.params.payload); + } + WsMessageOrResponse::Response(response) => { + tracing::debug!("Received response from server: {:?}", response); + } + WsMessageOrResponse::ErrorResponse(error) => { + tracing::debug!("Received an error from server: {:?}", error); + return Err(PubsubError::InternalStr(error.error.message)); + } } + } } } + + Ok(()) } diff --git a/justfile b/justfile index 2ed4316f5..c250fa583 100644 --- a/justfile +++ b/justfile @@ -66,14 +66,14 @@ test: # run doc tests -test-pure db="memory": build +test-pure db="memory": #!/usr/bin/env bash set -euo pipefail if [ ! -f Cargo.toml ]; then cd {{invocation_directory()}} fi - # Run pure integration tests + # Run pure integration tests (cargo test will only build what's needed for the test) CDK_TEST_DB_TYPE={{db}} cargo test -p cdk-integration-tests --test integration_tests_pure -- --test-threads 1 test-all db="memory": From 582ebc90f4f7fbbecd799ddde9ef619f9d46a34e Mon Sep 17 00:00:00 2001 From: Olexandr88 Date: Wed, 8 Oct 2025 14:47:52 +0300 Subject: [PATCH 213/321] Update README.md (#1169) --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 31ff04b14..3d41f77be 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ -> **Warning** +> [!Warning] > This project is in early development, it does however work with real sats! Always use amounts you don't mind losing. -[![crates.io](https://img.shields.io/crates/v/cdk.svg)](https://crates.io/crates/cdk) [![Documentation](https://docs.rs/cdk/badge.svg)](https://docs.rs/cdk) +[![crates.io](https://img.shields.io/crates/v/cdk.svg)](https://crates.io/crates/cdk) [![Documentation](https://docs.rs/cdk/badge.svg)](https://docs.rs/cdk) [![License](https://img.shields.io/github/license/cashubtc/cdk)](https://github.com/cashubtc/cdk/blob/main/LICENSE) # Cashu Development Kit From 2c2fce9612e3a9bf53cf52df41a4989c042d6221 Mon Sep 17 00:00:00 2001 From: tsk Date: Wed, 8 Oct 2025 16:18:06 +0200 Subject: [PATCH 214/321] chore: remove ctor (#1168) --- crates/cdk-ffi/Cargo.toml | 1 - 1 file changed, 1 deletion(-) diff --git a/crates/cdk-ffi/Cargo.toml b/crates/cdk-ffi/Cargo.toml index f71bf592a..dd9758b8b 100644 --- a/crates/cdk-ffi/Cargo.toml +++ b/crates/cdk-ffi/Cargo.toml @@ -18,7 +18,6 @@ bip39 = { workspace = true } cdk = { workspace = true, default-features = false, features = ["wallet", "auth", "bip353"] } cdk-sqlite = { workspace = true } cdk-postgres = { workspace = true, optional = true } -ctor = "0.2" futures = { workspace = true } once_cell = { workspace = true } rand = { workspace = true } From dab9281d5a97b7b8d67eaa0f8b97b96f07de2a4e Mon Sep 17 00:00:00 2001 From: tsk Date: Wed, 8 Oct 2025 16:23:42 +0200 Subject: [PATCH 215/321] chore: nostr-sdk as workspace dep (#1167) --- Cargo.toml | 5 +++++ crates/cdk-cli/Cargo.toml | 6 +----- crates/cdk/Cargo.toml | 6 +----- 3 files changed, 7 insertions(+), 10 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index d325d8516..24a04f55f 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -111,6 +111,11 @@ strum = "0.27.1" strum_macros = "0.27.1" rustls = { version = "0.23.27", default-features = false, features = ["ring"] } prometheus = { version = "0.13.4", features = ["process"], default-features = false } +nostr-sdk = { version = "0.43.0", default-features = false, features = [ + "nip04", + "nip44", + "nip59" +]} diff --git a/crates/cdk-cli/Cargo.toml b/crates/cdk-cli/Cargo.toml index 6597d31a6..e789e05d3 100644 --- a/crates/cdk-cli/Cargo.toml +++ b/crates/cdk-cli/Cargo.toml @@ -31,11 +31,7 @@ tokio.workspace = true tracing.workspace = true tracing-subscriber.workspace = true home.workspace = true -nostr-sdk = { version = "0.41.0", default-features = false, features = [ - "nip04", - "nip44", - "nip59" -]} +nostr-sdk = { workspace = true } reqwest.workspace = true url.workspace = true serde_with.workspace = true diff --git a/crates/cdk/Cargo.toml b/crates/cdk/Cargo.toml index c80ab32f7..3d7ebf740 100644 --- a/crates/cdk/Cargo.toml +++ b/crates/cdk/Cargo.toml @@ -57,11 +57,7 @@ url.workspace = true utoipa = { workspace = true, optional = true } uuid.workspace = true jsonwebtoken = { workspace = true, optional = true } -nostr-sdk = { optional = true, version = "0.43.0", default-features = false, features = [ - "nip04", - "nip44", - "nip59" -]} +nostr-sdk = { workspace = true, optional = true } cdk-prometheus = {workspace = true, optional = true} web-time.workspace = true zeroize = "1" From cae8768a875bb6840e87ea463552b3268e73d181 Mon Sep 17 00:00:00 2001 From: tsk Date: Wed, 8 Oct 2025 21:51:57 +0100 Subject: [PATCH 216/321] Fix cdk cli readme (#1165) * docs: update cli read me * docs: update postgres link --- crates/cdk-cli/README.md | 417 ++++++++++++++++++++++++++++++------- crates/cdk-mintd/README.md | 2 +- 2 files changed, 344 insertions(+), 75 deletions(-) diff --git a/crates/cdk-cli/README.md b/crates/cdk-cli/README.md index bdd21e5f3..0cea68bb2 100644 --- a/crates/cdk-cli/README.md +++ b/crates/cdk-cli/README.md @@ -11,11 +11,15 @@ A command-line Cashu wallet implementation built with the Cashu Development Kit ## Features -- **Multiple Mint Support**: Connect to and manage multiple Cashu mints +- **Multiple Mint Support**: Connect to and manage multiple Cashu mints simultaneously - **Token Operations**: Mint, melt, send, and receive Cashu tokens -- **Wallet Management**: Create and manage multiple wallets -- **Lightning Integration**: Pay Lightning invoices and receive payments -- **Token Storage**: Secure local storage of tokens and mint configurations +- **Lightning Integration**: Pay Lightning invoices (BOLT11, BOLT12, BIP353) and receive payments +- **Payment Requests**: Create and pay payment requests with various conditions (P2PK, HTLC) +- **Token Transfer**: Transfer tokens between different mints +- **Multi-Currency Support**: Support for different currency units (sat, usd, eur, etc.) +- **Database Options**: SQLite or Redb backend with optional encryption (SQLCipher) +- **Tor Support**: Built-in Tor transport support (when compiled with feature) +- **Secure Storage**: Local storage of tokens, mint configurations, and seed ## Installation @@ -30,141 +34,379 @@ cargo build --bin cdk-cli --release # Binary will be at ./target/release/cdk-cli ``` +### Build with Optional Features +```bash +# With Tor support +cargo build --bin cdk-cli --release --features tor + +# With SQLCipher encryption +cargo build --bin cdk-cli --release --features sqlcipher + +# With Redb database +cargo build --bin cdk-cli --release --features redb +``` + ## Quick Start -### 1. Add a Mint +### 1. Check Your Balance ```bash -# Add a mint (use a real mint URL or start your own with cdk-mintd) -cdk-cli wallet add-mint http://127.0.0.1:8085 +# View your current balance across all mints +cdk-cli balance ``` ### 2. Mint Tokens ```bash -# Create a mint quote for 100 sats -cdk-cli wallet mint-quote 100 +# Create and mint tokens from a mint (amount in sats) +cdk-cli mint http://127.0.0.1:8085 100 + +# Or with a description +cdk-cli mint http://127.0.0.1:8085 100 "My first mint" -# Pay the Lightning invoice shown, then mint the tokens -cdk-cli wallet mint +# The command will display a Lightning invoice to pay +# After payment, tokens are automatically minted ``` ### 3. Send Tokens ```bash -# Send 50 sats as a token -cdk-cli wallet send 50 +# Send tokens (you'll be prompted for amount and mint selection interactively) +cdk-cli send + +# Or specify options directly +cdk-cli send --mint-url http://127.0.0.1:8085 --memo "Payment for coffee" ``` ### 4. Receive Tokens ```bash # Receive a token from someone else -cdk-cli wallet receive +cdk-cli receive + +# Receive from untrusted mint with transfer to trusted mint +cdk-cli receive --allow-untrusted --transfer-to http://127.0.0.1:8085 ``` -### 5. Check Balance +## Global Options + +The CLI supports several global options that apply to all commands: + ```bash -# View your current balance -cdk-cli wallet balance +# Use a specific database engine +cdk-cli --engine sqlite balance +cdk-cli --engine redb balance + +# Set a custom work directory +cdk-cli --work-dir ~/my-wallet balance + +# Set logging level +cdk-cli --log-level info balance + +# Use a specific currency unit +cdk-cli --unit usd balance + +# Use NIP-98 Wallet Signing Proxy +cdk-cli --proxy https://proxy.example.com balance + +# Disable Tor (when built with Tor feature, it's on by default) +cdk-cli --tor off balance ``` -## Basic Usage +## Commands Reference + +### Balance Operations -### Wallet Operations ```bash -# List all wallets -cdk-cli wallet list +# Check balance across all mints +cdk-cli balance +``` -# Create a new wallet -cdk-cli wallet new --name my-wallet +### Minting Tokens -# Set default wallet -cdk-cli wallet set-default my-wallet +```bash +# Mint tokens with a Lightning invoice +cdk-cli mint -# Show wallet info -cdk-cli wallet info +# With options +cdk-cli mint http://127.0.0.1:8085 1000 \ + --method bolt11 + +# Using an existing quote +cdk-cli mint http://127.0.0.1:8085 --quote-id + +# Claim pending mint quotes that have been paid +cdk-cli mint-pending ``` -### Mint Management +### Sending & Receiving Tokens + +```bash +# Send tokens (interactive) +cdk-cli send + +# Send with specific options +cdk-cli send \ + --memo "Coffee payment" \ + --mint-url http://127.0.0.1:8085 \ + --include-fee \ + --offline + +# Send with P2PK lock +cdk-cli send --pubkey --required-sigs 1 + +# Send with HTLC (Hash Time Locked Contract) +cdk-cli send --hash --locktime + +# Send as V3 token +cdk-cli send --v3 + +# Send with automatic transfer from other mints if needed +cdk-cli send --allow-transfer --max-transfer-amount 1000 + +# Receive tokens +cdk-cli receive + +# Receive with signing key (for P2PK) +cdk-cli receive --signing-key + +# Receive with HTLC preimage +cdk-cli receive --preimage + +# Receive via Nostr +cdk-cli receive --nostr-key --relay wss://relay.example.com +``` + +### Lightning Payments + +```bash +# Pay a Lightning invoice (interactive - will prompt for invoice) +cdk-cli melt + +# Specify mint and payment method +cdk-cli melt --mint-url http://127.0.0.1:8085 --method bolt11 + +# Pay BOLT12 offer +cdk-cli melt --method bolt12 + +# Pay BIP353 address +cdk-cli melt --method bip353 + +# Multi-path payment +cdk-cli melt --mpp +``` + +### Payment Requests + +```bash +# Create a payment request (interactive via Nostr) +cdk-cli create-request + +# Create with specific amount +cdk-cli create-request --amount 1000 "Invoice for services" + +# Create with P2PK condition +cdk-cli create-request --amount 500 \ + --pubkey \ + --pubkey \ + --num-sigs 2 + +# Create with HTLC +cdk-cli create-request --amount 1000 --hash +# Or use preimage instead +cdk-cli create-request --amount 1000 --preimage + +# Create with HTTP transport +cdk-cli create-request --amount 1000 \ + --transport http \ + --http-url https://myserver.com/payment + +# Create without transport (just print the request) +cdk-cli create-request --amount 1000 --transport none + +# Pay a payment request +cdk-cli pay-request + +# Decode a payment request +cdk-cli decode-request +``` + +### Token Transfer Between Mints + ```bash -# List connected mints -cdk-cli wallet list-mints +# Transfer tokens between mints (interactive) +cdk-cli transfer + +# Transfer specific amount +cdk-cli transfer \ + --source-mint http://mint1.example.com \ + --target-mint http://mint2.example.com \ + --amount 1000 + +# Transfer full balance from one mint to another +cdk-cli transfer \ + --source-mint http://mint1.example.com \ + --target-mint http://mint2.example.com \ + --full-balance +``` -# Remove a mint -cdk-cli wallet remove-mint +### Mint Information & Management +```bash # Get mint information -cdk-cli wallet mint-info +cdk-cli mint-info + +# Update mint URL (if mint has migrated) +cdk-cli update-mint-url + +# List proofs from mint +cdk-cli list-mint-proofs ``` -### Payment Operations +### Token & Proof Management + ```bash -# Pay a Lightning invoice -cdk-cli wallet pay-invoice +# Decode a Cashu token +cdk-cli decode-token + +# Check pending proofs and reclaim if no longer pending +cdk-cli check-pending -# Create melt quote for an invoice -cdk-cli wallet melt-quote +# Burn spent tokens (cleanup) +cdk-cli burn -# Execute the melt -cdk-cli wallet melt +# Restore proofs from seed for a specific mint +cdk-cli restore ``` -### Token Management +### Advanced Features + +#### Blind Authentication (NUT-14) + ```bash -# List all tokens -cdk-cli wallet list-tokens +# Mint blind authentication proofs +cdk-cli mint-blind-auth --amount +``` -# Check token states -cdk-cli wallet check-tokens +#### CAT (Cashu Authentication Tokens) + +```bash +# Login with username/password +cdk-cli cat-login --username --password -# Restore wallet from seed -cdk-cli wallet restore --seed +# Login with device code flow (OAuth-style) +cdk-cli cat-device-login ``` ## Configuration +### Storage Location + The CLI stores its configuration and wallet data in: -- **Linux/macOS**: `~/.config/cdk-cli/` -- **Windows**: `%APPDATA%\cdk-cli\` +- **Linux/macOS**: `~/.cdk-cli/` +- **Windows**: `%USERPROFILE%\.cdk-cli\` + +You can override this with the `--work-dir` option. + +### Database Options + +The CLI supports multiple database backends: + +#### SQLite (default) +```bash +cdk-cli --engine sqlite balance +``` + +#### SQLCipher (encrypted SQLite) +```bash +# Requires building with --features sqlcipher +cdk-cli --engine sqlite --password mypassword balance +``` + +#### Redb +```bash +# Requires building with --features redb +cdk-cli --engine redb balance +``` + +### Seed Management + +The wallet seed is automatically generated and stored in `/seed` on first run. This seed is used to derive all keys and can be used to restore your wallet. + +**Important**: Back up your seed file securely. Anyone with access to the seed can spend your tokens. ## Examples ### Complete Workflow Example + ```bash # 1. Start a test mint (in another terminal) cdk-mintd -# 2. Add the mint -cdk-cli wallet add-mint http://127.0.0.1:8085 +# 2. Mint some tokens +cdk-cli mint http://127.0.0.1:8085 1000 "Initial mint" +# Pay the displayed Lightning invoice + +# 3. Check balance +cdk-cli balance -# 3. Create a mint quote -cdk-cli wallet mint-quote 1000 +# 4. Send some tokens +cdk-cli send +# Follow interactive prompts -# 4. Pay the Lightning invoice (if using real Lightning backend) -# or wait a few seconds if using fake wallet +# 5. The recipient can receive with: +cdk-cli receive + +# 6. Pay a Lightning invoice +cdk-cli melt +# Follow prompts to enter invoice +``` -# 5. Mint the tokens -cdk-cli wallet mint +### Multi-Mint Setup + +```bash +# Mint from multiple mints +cdk-cli mint http://mint1.example.com 5000 +cdk-cli mint http://mint2.example.com 3000 + +# Check balance (shows breakdown by mint) +cdk-cli balance + +# Transfer between mints +cdk-cli transfer \ + --source-mint http://mint1.example.com \ + --target-mint http://mint2.example.com \ + --amount 2000 +``` -# 6. Check balance -cdk-cli wallet balance +### Payment Request Workflow -# 7. Send some tokens -cdk-cli wallet send 100 +```bash +# Recipient creates a payment request +cdk-cli create-request --amount 1000 "Payment for services" +# Copy the payment request string + +# Sender pays the request +cdk-cli pay-request +``` + +### P2PK (Pay to Public Key) Usage + +```bash +# Send tokens locked to a public key +cdk-cli send --pubkey --required-sigs 1 -# 8. The recipient can receive with: -cdk-cli wallet receive +# Recipient receives with their private key +cdk-cli receive --signing-key ``` -### Working with Multiple Wallets +### HTLC (Hash Time Locked Contract) Usage + ```bash -# Create wallets for different purposes -cdk-cli wallet new --name savings -cdk-cli wallet new --name daily +# Create a preimage and hash (externally) +# hash = SHA256(preimage) -# Switch between wallets -cdk-cli wallet set-default savings -cdk-cli wallet balance +# Send with HTLC +cdk-cli send --hash --locktime 1700000000 -cdk-cli wallet set-default daily -cdk-cli wallet balance +# Recipient receives with preimage +cdk-cli receive --preimage ``` ## Help and Documentation @@ -174,8 +416,35 @@ cdk-cli wallet balance cdk-cli --help # Help for specific commands -cdk-cli wallet --help -cdk-cli wallet mint-quote --help +cdk-cli mint --help +cdk-cli send --help +cdk-cli receive --help +cdk-cli create-request --help +``` + +## Troubleshooting + +### Pending Tokens +If you have pending tokens (sent but not received, or mint quotes paid but not claimed): + +```bash +# Check and reclaim pending proofs +cdk-cli check-pending + +# Claim paid mint quotes +cdk-cli mint-pending +``` + +### Cleaning Up +```bash +# Remove spent tokens from database +cdk-cli burn +``` + +### Restore from Seed +```bash +# Restore proofs from a specific mint +cdk-cli restore ``` ## License diff --git a/crates/cdk-mintd/README.md b/crates/cdk-mintd/README.md index fcb189c79..4d9b39a3c 100644 --- a/crates/cdk-mintd/README.md +++ b/crates/cdk-mintd/README.md @@ -251,7 +251,7 @@ For complete configuration options, see the [example configuration file](./examp ## Documentation - **[Configuration Examples](./example.config.toml)** - Complete configuration reference -- **[PostgreSQL Setup Guide](../../POSTGRES.md)** - Database setup instructions +- **[PostgreSQL Setup Guide](../../docker-compose.postgres.yaml)** - Database setup with Docker Compose - **[Development Guide](../../DEVELOPMENT.md)** - Contributing and development setup ## License From 3075ac4e5937042dc53aa833a328cb6cbec39e31 Mon Sep 17 00:00:00 2001 From: C Date: Wed, 8 Oct 2025 17:52:40 -0300 Subject: [PATCH 217/321] Read the latest mint quote status in a transaction to avoid race conditions (#1166) * Read the latest mint quote status in a transaction to avoid race conditions Fixes #1162 * Reload quote for all cases * Exit on paid invoices only for bolt11 --- crates/cdk/src/mint/ln.rs | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/crates/cdk/src/mint/ln.rs b/crates/cdk/src/mint/ln.rs index 447b0e3ec..9e4b59618 100644 --- a/crates/cdk/src/mint/ln.rs +++ b/crates/cdk/src/mint/ln.rs @@ -45,6 +45,20 @@ impl Mint { let mut tx = self.localstore.begin_transaction().await?; + // reload the quote, as it state may have changed + *quote = tx + .get_mint_quote("e.id) + .await? + .ok_or(Error::UnknownQuote)?; + + let current_state = quote.state(); + + if quote.payment_method == PaymentMethod::Bolt11 + && (current_state == MintQuoteState::Issued || current_state == MintQuoteState::Paid) + { + return Ok(()); + } + for payment in ln_status { if !quote.payment_ids().contains(&&payment.payment_id) && payment.payment_amount > Amount::ZERO From 95aa64477a602d1977b5e6cc75802e0f51589e35 Mon Sep 17 00:00:00 2001 From: tsk Date: Thu, 9 Oct 2025 16:20:06 +0100 Subject: [PATCH 218/321] Improve add transaction (#1164) * fix(wallet): move transaction ID calculation before database operations * fix(sql): remove on ys from on conflict transaction insert Since the id is created from the ys we know that if there is a conflict the ys are the same and do not need to be updated. * feat: bench for transactio id * chore: fmt --- Cargo.toml | 1 + crates/cdk-common/Cargo.toml | 5 ++++ .../benches/transaction_id_benchmark.rs | 29 +++++++++++++++++++ crates/cdk-redb/src/wallet/mod.rs | 4 ++- crates/cdk-sql-common/src/wallet/mod.rs | 8 +++-- crates/cdk/Cargo.toml | 2 +- 6 files changed, 44 insertions(+), 5 deletions(-) create mode 100644 crates/cdk-common/benches/transaction_id_benchmark.rs diff --git a/Cargo.toml b/Cargo.toml index 24a04f55f..ecff12998 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -66,6 +66,7 @@ clap = { version = "4.5.31", features = ["derive"] } ciborium = { version = "0.2.2", default-features = false, features = ["std"] } cbor-diag = "0.1.12" config = { version = "0.15.11", features = ["toml"] } +criterion = "0.6.0" futures = { version = "0.3.28", default-features = false, features = ["async-await"] } lightning-invoice = { version = "0.33.0", features = ["serde", "std"] } lightning = { version = "0.1.2", default-features = false, features = ["std"]} diff --git a/crates/cdk-common/Cargo.toml b/crates/cdk-common/Cargo.toml index 5fb81bb91..8424d21a5 100644 --- a/crates/cdk-common/Cargo.toml +++ b/crates/cdk-common/Cargo.toml @@ -53,3 +53,8 @@ wasm-bindgen-futures = "0.4" rand.workspace = true bip39.workspace = true wasm-bindgen-test = "0.3" +criterion.workspace = true + +[[bench]] +name = "transaction_id_benchmark" +harness = false diff --git a/crates/cdk-common/benches/transaction_id_benchmark.rs b/crates/cdk-common/benches/transaction_id_benchmark.rs new file mode 100644 index 000000000..8242131d4 --- /dev/null +++ b/crates/cdk-common/benches/transaction_id_benchmark.rs @@ -0,0 +1,29 @@ +use cashu::nuts::nut01::SecretKey; +use cashu::PublicKey; +use cdk_common::wallet::TransactionId; +use criterion::{criterion_group, criterion_main, BenchmarkId, Criterion}; + +fn generate_public_keys(count: usize) -> Vec { + (0..count) + .map(|_| SecretKey::generate().public_key()) + .collect() +} + +fn bench_transaction_id(c: &mut Criterion) { + let mut group = c.benchmark_group("TransactionId::new"); + + let sizes = vec![1, 10, 50, 100, 500]; + + for size in sizes { + let public_keys = generate_public_keys(size); + + group.bench_with_input(BenchmarkId::from_parameter(size), &size, |b, _| { + b.iter(|| TransactionId::new(public_keys.clone())); + }); + } + + group.finish(); +} + +criterion_group!(benches, bench_transaction_id); +criterion_main!(benches); diff --git a/crates/cdk-redb/src/wallet/mod.rs b/crates/cdk-redb/src/wallet/mod.rs index 44c4cce02..e4484c2a8 100644 --- a/crates/cdk-redb/src/wallet/mod.rs +++ b/crates/cdk-redb/src/wallet/mod.rs @@ -827,6 +827,8 @@ impl WalletDatabase for WalletRedbDatabase { #[instrument(skip(self))] async fn add_transaction(&self, transaction: Transaction) -> Result<(), Self::Err> { + let id = transaction.id(); + let write_txn = self.db.begin_write().map_err(Error::from)?; { @@ -835,7 +837,7 @@ impl WalletDatabase for WalletRedbDatabase { .map_err(Error::from)?; table .insert( - transaction.id().as_slice(), + id.as_slice(), serde_json::to_string(&transaction) .map_err(Error::from)? .as_str(), diff --git a/crates/cdk-sql-common/src/wallet/mod.rs b/crates/cdk-sql-common/src/wallet/mod.rs index fd91ea683..e524776e4 100644 --- a/crates/cdk-sql-common/src/wallet/mod.rs +++ b/crates/cdk-sql-common/src/wallet/mod.rs @@ -954,7 +954,6 @@ ON CONFLICT(id) DO UPDATE SET #[instrument(skip(self))] async fn add_transaction(&self, transaction: Transaction) -> Result<(), Self::Err> { - let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; let mint_url = transaction.mint_url.to_string(); let direction = transaction.direction.to_string(); let unit = transaction.unit.to_string(); @@ -966,6 +965,10 @@ ON CONFLICT(id) DO UPDATE SET .flat_map(|y| y.to_bytes().to_vec()) .collect::>(); + let id = transaction.id(); + + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; + query( r#" INSERT INTO transactions @@ -978,7 +981,6 @@ ON CONFLICT(id) DO UPDATE SET unit = excluded.unit, amount = excluded.amount, fee = excluded.fee, - ys = excluded.ys, timestamp = excluded.timestamp, memo = excluded.memo, metadata = excluded.metadata, @@ -988,7 +990,7 @@ ON CONFLICT(id) DO UPDATE SET ; "#, )? - .bind("id", transaction.id().as_slice().to_vec()) + .bind("id", id.as_slice().to_vec()) .bind("mint_url", mint_url) .bind("direction", direction) .bind("unit", unit) diff --git a/crates/cdk/Cargo.toml b/crates/cdk/Cargo.toml index 3d7ebf740..bfc2f1396 100644 --- a/crates/cdk/Cargo.toml +++ b/crates/cdk/Cargo.toml @@ -143,7 +143,7 @@ rand.workspace = true cdk-sqlite.workspace = true bip39.workspace = true tracing-subscriber.workspace = true -criterion = "0.6.0" +criterion.workspace = true reqwest = { workspace = true } anyhow.workspace = true ureq = { version = "3.1.0", features = ["json"] } From 5ee760a5067278fde5a81eb988505e2e531b0659 Mon Sep 17 00:00:00 2001 From: C Date: Fri, 10 Oct 2025 06:14:28 -0300 Subject: [PATCH 219/321] Remove the `amounts` from amounts (#1179) --- crates/cdk-signatory/src/proto/convert.rs | 21 +++++++++---------- .../cdk-signatory/src/proto/signatory.proto | 1 - 2 files changed, 10 insertions(+), 12 deletions(-) diff --git a/crates/cdk-signatory/src/proto/convert.rs b/crates/cdk-signatory/src/proto/convert.rs index da5a3fddb..ba5b13c21 100644 --- a/crates/cdk-signatory/src/proto/convert.rs +++ b/crates/cdk-signatory/src/proto/convert.rs @@ -43,6 +43,14 @@ impl TryInto for KeySet { type Error = cdk_common::Error; fn try_into(self) -> Result { + let keys = self + .keys + .ok_or(cdk_common::Error::Custom(INTERNAL_ERROR.to_owned()))? + .keys + .into_iter() + .map(|(amount, pk)| PublicKey::from_slice(&pk).map(|pk| (amount.into(), pk))) + .collect::, _>>()?; + Ok(crate::signatory::SignatoryKeySet { id: Id::from_bytes(&self.id)?, unit: self @@ -52,15 +60,8 @@ impl TryInto for KeySet { .map_err(|_| cdk_common::Error::Custom("Invalid currency unit".to_owned()))?, active: self.active, input_fee_ppk: self.input_fee_ppk, - keys: cdk_common::Keys::new( - self.keys - .ok_or(cdk_common::Error::Custom(INTERNAL_ERROR.to_owned()))? - .keys - .into_iter() - .map(|(amount, pk)| PublicKey::from_slice(&pk).map(|pk| (amount.into(), pk))) - .collect::, _>>()?, - ), - amounts: self.amounts, + amounts: keys.keys().map(|x| x.to_u64()).collect::>(), + keys: cdk_common::Keys::new(keys), final_expiry: self.final_expiry, }) } @@ -81,7 +82,6 @@ impl From for KeySet { .collect(), }), final_expiry: keyset.final_expiry, - amounts: keyset.amounts, version: Default::default(), } } @@ -363,7 +363,6 @@ impl From for KeySet { input_fee_ppk: value.input_fee_ppk, keys: Default::default(), final_expiry: value.final_expiry, - amounts: vec![], version: Default::default(), } } diff --git a/crates/cdk-signatory/src/proto/signatory.proto b/crates/cdk-signatory/src/proto/signatory.proto index 3da00f971..5b82408a2 100644 --- a/crates/cdk-signatory/src/proto/signatory.proto +++ b/crates/cdk-signatory/src/proto/signatory.proto @@ -64,7 +64,6 @@ message KeySet { Keys keys = 5; optional uint64 final_expiry = 6; uint64 version = 7; - repeated uint64 amounts = 8; } message Keys { From 5fc38d59808a1d6a63389229392570ab44f3bbdd Mon Sep 17 00:00:00 2001 From: asmo Date: Fri, 10 Oct 2025 13:53:07 +0200 Subject: [PATCH 220/321] fi: add ws resource to ProtectedEndpoints (#1178) * feat: add ws resource to ProtectedEndpoints --- crates/cdk-ffi/src/types/mint.rs | 337 +++++++++++++++++++++++++++++++ 1 file changed, 337 insertions(+) diff --git a/crates/cdk-ffi/src/types/mint.rs b/crates/cdk-ffi/src/types/mint.rs index 06236cbe3..4e1eaef7c 100644 --- a/crates/cdk-ffi/src/types/mint.rs +++ b/crates/cdk-ffi/src/types/mint.rs @@ -440,6 +440,7 @@ impl TryFrom for cdk::nuts::ProtectedEndpoint { "/v1/melt/quote/bolt11" => cdk::nuts::RoutePath::MeltQuoteBolt11, "/v1/melt/bolt11" => cdk::nuts::RoutePath::MeltBolt11, "/v1/swap" => cdk::nuts::RoutePath::Swap, + "/v1/ws" => cdk::nuts::RoutePath::Ws, "/v1/checkstate" => cdk::nuts::RoutePath::Checkstate, "/v1/restore" => cdk::nuts::RoutePath::Restore, "/v1/auth/blind/mint" => cdk::nuts::RoutePath::MintBlindAuth, @@ -673,3 +674,339 @@ pub fn decode_mint_info(json: String) -> Result { pub fn encode_mint_info(info: MintInfo) -> Result { Ok(serde_json::to_string(&info)?) } +#[cfg(test)] +mod tests { + use super::*; + + /// Helper function to create a sample cdk::nuts::Nuts for testing + fn create_sample_cdk_nuts() -> cdk::nuts::Nuts { + cdk::nuts::Nuts { + nut04: cdk::nuts::nut04::Settings { + methods: vec![cdk::nuts::nut04::MintMethodSettings { + method: cdk::nuts::PaymentMethod::Bolt11, + unit: cdk::nuts::CurrencyUnit::Sat, + min_amount: Some(cdk::Amount::from(1)), + max_amount: Some(cdk::Amount::from(100000)), + options: Some(cdk::nuts::nut04::MintMethodOptions::Bolt11 { + description: true, + }), + }], + disabled: false, + }, + nut05: cdk::nuts::nut05::Settings { + methods: vec![cdk::nuts::nut05::MeltMethodSettings { + method: cdk::nuts::PaymentMethod::Bolt11, + unit: cdk::nuts::CurrencyUnit::Sat, + min_amount: Some(cdk::Amount::from(1)), + max_amount: Some(cdk::Amount::from(100000)), + options: Some(cdk::nuts::nut05::MeltMethodOptions::Bolt11 { amountless: true }), + }], + disabled: false, + }, + nut07: cdk::nuts::nut06::SupportedSettings { supported: true }, + nut08: cdk::nuts::nut06::SupportedSettings { supported: true }, + nut09: cdk::nuts::nut06::SupportedSettings { supported: false }, + nut10: cdk::nuts::nut06::SupportedSettings { supported: true }, + nut11: cdk::nuts::nut06::SupportedSettings { supported: true }, + nut12: cdk::nuts::nut06::SupportedSettings { supported: true }, + nut14: cdk::nuts::nut06::SupportedSettings { supported: false }, + nut15: Default::default(), + nut17: Default::default(), + nut19: Default::default(), + nut20: cdk::nuts::nut06::SupportedSettings { supported: true }, + nut21: Some(cdk::nuts::ClearAuthSettings { + openid_discovery: "https://example.com/.well-known/openid-configuration" + .to_string(), + client_id: "test-client".to_string(), + protected_endpoints: vec![cdk::nuts::ProtectedEndpoint::new( + cdk::nuts::Method::Post, + cdk::nuts::RoutePath::Swap, + )], + }), + nut22: Some(cdk::nuts::BlindAuthSettings { + bat_max_mint: 100, + protected_endpoints: vec![cdk::nuts::ProtectedEndpoint::new( + cdk::nuts::Method::Post, + cdk::nuts::RoutePath::MintBolt11, + )], + }), + } + } + + #[test] + fn test_nuts_from_cdk_to_ffi() { + let cdk_nuts = create_sample_cdk_nuts(); + let ffi_nuts: Nuts = cdk_nuts.clone().into(); + + // Verify NUT04 settings + assert_eq!(ffi_nuts.nut04.disabled, false); + assert_eq!(ffi_nuts.nut04.methods.len(), 1); + assert_eq!(ffi_nuts.nut04.methods[0].description, Some(true)); + + // Verify NUT05 settings + assert_eq!(ffi_nuts.nut05.disabled, false); + assert_eq!(ffi_nuts.nut05.methods.len(), 1); + assert_eq!(ffi_nuts.nut05.methods[0].amountless, Some(true)); + + // Verify supported flags + assert!(ffi_nuts.nut07_supported); + assert!(ffi_nuts.nut08_supported); + assert!(!ffi_nuts.nut09_supported); + assert!(ffi_nuts.nut10_supported); + assert!(ffi_nuts.nut11_supported); + assert!(ffi_nuts.nut12_supported); + assert!(!ffi_nuts.nut14_supported); + assert!(ffi_nuts.nut20_supported); + + // Verify auth settings + assert!(ffi_nuts.nut21.is_some()); + let nut21 = ffi_nuts.nut21.as_ref().unwrap(); + assert_eq!( + nut21.openid_discovery, + "https://example.com/.well-known/openid-configuration" + ); + assert_eq!(nut21.client_id, "test-client"); + assert_eq!(nut21.protected_endpoints.len(), 1); + + assert!(ffi_nuts.nut22.is_some()); + let nut22 = ffi_nuts.nut22.as_ref().unwrap(); + assert_eq!(nut22.bat_max_mint, 100); + assert_eq!(nut22.protected_endpoints.len(), 1); + + // Verify units + assert!(!ffi_nuts.mint_units.is_empty()); + assert!(!ffi_nuts.melt_units.is_empty()); + } + + #[test] + fn test_nuts_round_trip_conversion() { + let original_cdk_nuts = create_sample_cdk_nuts(); + + // Convert cdk -> ffi -> cdk + let ffi_nuts: Nuts = original_cdk_nuts.clone().into(); + let converted_back: cdk::nuts::Nuts = ffi_nuts.try_into().unwrap(); + + // Verify all supported flags match + assert_eq!( + original_cdk_nuts.nut07.supported, + converted_back.nut07.supported + ); + assert_eq!( + original_cdk_nuts.nut08.supported, + converted_back.nut08.supported + ); + assert_eq!( + original_cdk_nuts.nut09.supported, + converted_back.nut09.supported + ); + assert_eq!( + original_cdk_nuts.nut10.supported, + converted_back.nut10.supported + ); + assert_eq!( + original_cdk_nuts.nut11.supported, + converted_back.nut11.supported + ); + assert_eq!( + original_cdk_nuts.nut12.supported, + converted_back.nut12.supported + ); + assert_eq!( + original_cdk_nuts.nut14.supported, + converted_back.nut14.supported + ); + assert_eq!( + original_cdk_nuts.nut20.supported, + converted_back.nut20.supported + ); + + // Verify NUT04 settings + assert_eq!( + original_cdk_nuts.nut04.disabled, + converted_back.nut04.disabled + ); + assert_eq!( + original_cdk_nuts.nut04.methods.len(), + converted_back.nut04.methods.len() + ); + + // Verify NUT05 settings + assert_eq!( + original_cdk_nuts.nut05.disabled, + converted_back.nut05.disabled + ); + assert_eq!( + original_cdk_nuts.nut05.methods.len(), + converted_back.nut05.methods.len() + ); + + // Verify auth settings presence + assert_eq!( + original_cdk_nuts.nut21.is_some(), + converted_back.nut21.is_some() + ); + assert_eq!( + original_cdk_nuts.nut22.is_some(), + converted_back.nut22.is_some() + ); + } + + #[test] + fn test_nuts_without_auth() { + let cdk_nuts = cdk::nuts::Nuts { + nut04: Default::default(), + nut05: Default::default(), + nut07: cdk::nuts::nut06::SupportedSettings { supported: true }, + nut08: cdk::nuts::nut06::SupportedSettings { supported: false }, + nut09: cdk::nuts::nut06::SupportedSettings { supported: false }, + nut10: cdk::nuts::nut06::SupportedSettings { supported: false }, + nut11: cdk::nuts::nut06::SupportedSettings { supported: false }, + nut12: cdk::nuts::nut06::SupportedSettings { supported: false }, + nut14: cdk::nuts::nut06::SupportedSettings { supported: false }, + nut15: Default::default(), + nut17: Default::default(), + nut19: Default::default(), + nut20: cdk::nuts::nut06::SupportedSettings { supported: false }, + nut21: None, + nut22: None, + }; + + let ffi_nuts: Nuts = cdk_nuts.into(); + + assert!(ffi_nuts.nut21.is_none()); + assert!(ffi_nuts.nut22.is_none()); + assert!(ffi_nuts.nut07_supported); + assert!(!ffi_nuts.nut08_supported); + } + + #[test] + fn test_ffi_nuts_to_cdk_with_defaults() { + let ffi_nuts = Nuts { + nut04: Nut04Settings { + methods: vec![], + disabled: true, + }, + nut05: Nut05Settings { + methods: vec![], + disabled: true, + }, + nut07_supported: false, + nut08_supported: false, + nut09_supported: false, + nut10_supported: false, + nut11_supported: false, + nut12_supported: false, + nut14_supported: false, + nut20_supported: false, + nut21: None, + nut22: None, + mint_units: vec![], + melt_units: vec![], + }; + + let cdk_nuts: Result = ffi_nuts.try_into(); + assert!(cdk_nuts.is_ok()); + + let cdk_nuts = cdk_nuts.unwrap(); + assert!(!cdk_nuts.nut07.supported); + assert!(!cdk_nuts.nut08.supported); + assert!(cdk_nuts.nut21.is_none()); + assert!(cdk_nuts.nut22.is_none()); + + // Verify default values for nuts not included in FFI + assert_eq!(cdk_nuts.nut17.supported.len(), 0); + } + + #[test] + fn test_nuts_serialization() { + let cdk_nuts = create_sample_cdk_nuts(); + let ffi_nuts: Nuts = cdk_nuts.into(); + + // Test JSON serialization + let json = ffi_nuts.to_json(); + assert!(json.is_ok()); + + let json_str = json.unwrap(); + assert!(json_str.contains("nut04")); + assert!(json_str.contains("nut05")); + + // Test deserialization + let decoded: Result = serde_json::from_str(&json_str); + assert!(decoded.is_ok()); + + let decoded_nuts = decoded.unwrap(); + assert_eq!(decoded_nuts.nut07_supported, ffi_nuts.nut07_supported); + assert_eq!(decoded_nuts.nut08_supported, ffi_nuts.nut08_supported); + } + + #[test] + fn test_nuts_multiple_units() { + let mut cdk_nuts = create_sample_cdk_nuts(); + + // Add multiple payment methods to test unit collection + cdk_nuts + .nut04 + .methods + .push(cdk::nuts::nut04::MintMethodSettings { + method: cdk::nuts::PaymentMethod::Bolt11, + unit: cdk::nuts::CurrencyUnit::Msat, + min_amount: Some(cdk::Amount::from(1)), + max_amount: Some(cdk::Amount::from(100000)), + options: None, + }); + + cdk_nuts + .nut05 + .methods + .push(cdk::nuts::nut05::MeltMethodSettings { + method: cdk::nuts::PaymentMethod::Bolt11, + unit: cdk::nuts::CurrencyUnit::Usd, + min_amount: None, + max_amount: None, + options: None, + }); + + let ffi_nuts: Nuts = cdk_nuts.into(); + + // Should have collected multiple units + assert!(ffi_nuts.mint_units.len() >= 1); + assert!(ffi_nuts.melt_units.len() >= 1); + } + + #[test] + fn test_protected_endpoint_conversion() { + let cdk_endpoint = + cdk::nuts::ProtectedEndpoint::new(cdk::nuts::Method::Post, cdk::nuts::RoutePath::Swap); + + let ffi_endpoint: ProtectedEndpoint = cdk_endpoint.into(); + + assert_eq!(ffi_endpoint.method, "POST"); + assert_eq!(ffi_endpoint.path, "/v1/swap"); + + // Test round-trip + let converted_back: Result = ffi_endpoint.try_into(); + assert!(converted_back.is_ok()); + } + + #[test] + fn test_invalid_protected_endpoint_method() { + let invalid_endpoint = ProtectedEndpoint { + method: "INVALID".to_string(), + path: "/v1/swap".to_string(), + }; + + let result: Result = invalid_endpoint.try_into(); + assert!(result.is_err()); + } + + #[test] + fn test_invalid_protected_endpoint_path() { + let invalid_endpoint = ProtectedEndpoint { + method: "POST".to_string(), + path: "/invalid/path".to_string(), + }; + + let result: Result = invalid_endpoint.try_into(); + assert!(result.is_err()); + } +} From 7f17c027872d721f7be66e98612bc11dcc2b8320 Mon Sep 17 00:00:00 2001 From: tsk Date: Sun, 12 Oct 2025 21:09:01 +0100 Subject: [PATCH 221/321] feat: fake wallet store amount paid (#1185) * feat: fake wallet store amount paid --- crates/cdk-fake-wallet/src/lib.rs | 36 ++++++++++++++++++------------- 1 file changed, 21 insertions(+), 15 deletions(-) diff --git a/crates/cdk-fake-wallet/src/lib.rs b/crates/cdk-fake-wallet/src/lib.rs index 80e221ea4..aeb80790e 100644 --- a/crates/cdk-fake-wallet/src/lib.rs +++ b/crates/cdk-fake-wallet/src/lib.rs @@ -327,7 +327,7 @@ pub struct FakeWallet { fee_reserve: FeeReserve, sender: tokio::sync::mpsc::Sender, receiver: Arc>>>, - payment_states: Arc>>, + payment_states: Arc>>, failed_payment_check: Arc>>, payment_delay: u64, wait_invoice_cancel_token: CancellationToken, @@ -342,7 +342,7 @@ impl FakeWallet { /// Create new [`FakeWallet`] pub fn new( fee_reserve: FeeReserve, - payment_states: HashMap, + payment_states: HashMap, fail_payment_check: HashSet, payment_delay: u64, unit: CurrencyUnit, @@ -360,7 +360,7 @@ impl FakeWallet { /// Create new [`FakeWallet`] with custom secondary repayment queue size pub fn new_with_repay_queue_size( fee_reserve: FeeReserve, - payment_states: HashMap, + payment_states: HashMap, fail_payment_check: HashSet, payment_delay: u64, unit: CurrencyUnit, @@ -563,7 +563,22 @@ impl MintPayment for FakeWallet { .map(|s| s.check_payment_state) .unwrap_or(MeltQuoteState::Paid); - payment_states.insert(payment_hash.clone(), checkout_going_status); + let amount_msat: u64 = if let Some(melt_options) = bolt11_options.melt_options { + melt_options.amount_msat().into() + } else { + // Fall back to invoice amount + bolt11 + .amount_milli_satoshis() + .ok_or(Error::UnknownInvoiceAmount)? + }; + + let amount_spent = if checkout_going_status == MeltQuoteState::Paid { + amount_msat.into() + } else { + Amount::ZERO + }; + + payment_states.insert(payment_hash.clone(), (checkout_going_status, amount_spent)); if let Some(description) = status { if description.check_err { @@ -574,15 +589,6 @@ impl MintPayment for FakeWallet { ensure_cdk!(!description.pay_err, Error::UnknownInvoice.into()); } - let amount_msat: u64 = if let Some(melt_options) = bolt11_options.melt_options { - melt_options.amount_msat().into() - } else { - // Fall back to invoice amount - bolt11 - .amount_milli_satoshis() - .ok_or(Error::UnknownInvoiceAmount)? - }; - let total_spent = convert_currency_amount( amount_msat, &CurrencyUnit::Msat, @@ -784,7 +790,7 @@ impl MintPayment for FakeWallet { let states = self.payment_states.lock().await; let status = states.get(&request_lookup_id.to_string()).cloned(); - let status = status.unwrap_or(MeltQuoteState::Paid); + let (status, total_spent) = status.unwrap_or((MeltQuoteState::Unknown, Amount::default())); let fail_payments = self.failed_payment_check.lock().await; @@ -796,7 +802,7 @@ impl MintPayment for FakeWallet { payment_proof: Some("".to_string()), payment_lookup_id: request_lookup_id.clone(), status, - total_spent: Amount::ZERO, + total_spent, unit: CurrencyUnit::Msat, }) } From 69650c2ef9b75cd0867d729372a2f17bcb430fb1 Mon Sep 17 00:00:00 2001 From: tsk Date: Sun, 12 Oct 2025 23:16:52 +0100 Subject: [PATCH 222/321] feat: swap tests (#1187) --- .../tests/test_swap_flow.rs | 903 ++++++++++++++++++ justfile | 3 + 2 files changed, 906 insertions(+) create mode 100644 crates/cdk-integration-tests/tests/test_swap_flow.rs diff --git a/crates/cdk-integration-tests/tests/test_swap_flow.rs b/crates/cdk-integration-tests/tests/test_swap_flow.rs new file mode 100644 index 000000000..2d851e570 --- /dev/null +++ b/crates/cdk-integration-tests/tests/test_swap_flow.rs @@ -0,0 +1,903 @@ +//! Comprehensive tests for the current swap flow +//! +//! These tests validate the swap operation's behavior including: +//! - Happy path: successful token swaps +//! - Error handling: validation failures, rollback scenarios +//! - Edge cases: concurrent operations, double-spending +//! - State management: proof states, blinded message tracking +//! +//! The tests focus on the current implementation using ProofWriter and BlindedMessageWriter +//! patterns to ensure proper cleanup and rollback behavior. + +use std::collections::HashMap; +use std::sync::Arc; + +use cashu::amount::SplitTarget; +use cashu::dhke::construct_proofs; +use cashu::{CurrencyUnit, Id, PreMintSecrets, SecretKey, SpendingConditions, State, SwapRequest}; +use cdk::mint::Mint; +use cdk::nuts::nut00::ProofsMethods; +use cdk::Amount; +use cdk_integration_tests::init_pure_tests::*; + +/// Helper to get the active keyset ID from a mint +async fn get_keyset_id(mint: &Mint) -> Id { + let keys = mint.pubkeys().keysets.first().unwrap().clone(); + keys.verify_id() + .expect("Keyset ID generation is successful"); + keys.id +} + +/// Tests the complete happy path of a swap operation: +/// 1. Wallet is funded with tokens +/// 2. Blinded messages are added to database +/// 3. Outputs are signed by mint +/// 4. Input proofs are verified +/// 5. Transaction is balanced +/// 6. Proofs are added and marked as spent +/// 7. Blind signatures are saved +/// All steps should succeed and database should be in consistent state. +#[tokio::test(flavor = "multi_thread", worker_threads = 1)] +async fn test_swap_happy_path() { + setup_tracing(); + let mint = create_and_start_test_mint() + .await + .expect("Failed to create test mint"); + let wallet = create_test_wallet_for_mint(mint.clone()) + .await + .expect("Failed to create test wallet"); + + // Fund wallet with 100 sats + fund_wallet(wallet.clone(), 100, None) + .await + .expect("Failed to fund wallet"); + + let proofs = wallet + .get_unspent_proofs() + .await + .expect("Could not get proofs"); + + let keyset_id = get_keyset_id(&mint).await; + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); + + // Create swap request for same amount (100 sats) + let preswap = PreMintSecrets::random( + keyset_id, + 100.into(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .expect("Failed to create preswap"); + + let swap_request = SwapRequest::new(proofs.clone(), preswap.blinded_messages()); + + // Execute swap + let swap_response = mint + .process_swap_request(swap_request) + .await + .expect("Swap should succeed"); + + // Verify response contains correct number of signatures + assert_eq!( + swap_response.signatures.len(), + preswap.blinded_messages().len(), + "Should receive signature for each blinded message" + ); + + // Verify input proofs are marked as spent + let states = mint + .localstore() + .get_proofs_states(&proofs.iter().map(|p| p.y().unwrap()).collect::>()) + .await + .expect("Failed to get proof states"); + + for state in states { + assert_eq!( + State::Spent, + state.expect("State should be known"), + "All input proofs should be marked as spent" + ); + } + + // Verify blind signatures were saved + let saved_signatures = mint + .localstore() + .get_blind_signatures( + &preswap + .blinded_messages() + .iter() + .map(|bm| bm.blinded_secret) + .collect::>(), + ) + .await + .expect("Failed to get blind signatures"); + + assert_eq!( + saved_signatures.len(), + swap_response.signatures.len(), + "All signatures should be saved" + ); +} + +/// Tests that duplicate blinded messages are rejected: +/// 1. First swap with blinded messages succeeds +/// 2. Second swap attempt with same blinded messages fails +/// 3. BlindedMessageWriter should prevent reuse +#[tokio::test(flavor = "multi_thread", worker_threads = 1)] +async fn test_swap_duplicate_blinded_messages() { + setup_tracing(); + let mint = create_and_start_test_mint() + .await + .expect("Failed to create test mint"); + let wallet = create_test_wallet_for_mint(mint.clone()) + .await + .expect("Failed to create test wallet"); + + // Fund wallet with 200 sats (enough for two swaps) + fund_wallet(wallet.clone(), 200, None) + .await + .expect("Failed to fund wallet"); + + let all_proofs = wallet + .get_unspent_proofs() + .await + .expect("Could not get proofs"); + + // Split proofs into two sets + let mid = all_proofs.len() / 2; + let proofs1: Vec<_> = all_proofs.iter().take(mid).cloned().collect(); + let proofs2: Vec<_> = all_proofs.iter().skip(mid).cloned().collect(); + + let keyset_id = get_keyset_id(&mint).await; + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); + + // Create blinded messages for first swap + let preswap = PreMintSecrets::random( + keyset_id, + proofs1.total_amount().unwrap(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .expect("Failed to create preswap"); + + let blinded_messages = preswap.blinded_messages(); + + // First swap should succeed + let swap_request1 = SwapRequest::new(proofs1, blinded_messages.clone()); + mint.process_swap_request(swap_request1) + .await + .expect("First swap should succeed"); + + // Second swap with SAME blinded messages should fail + let swap_request2 = SwapRequest::new(proofs2, blinded_messages.clone()); + let result = mint.process_swap_request(swap_request2).await; + + assert!( + result.is_err(), + "Second swap with duplicate blinded messages should fail" + ); +} + +/// Tests that swap correctly rejects double-spending attempts: +/// 1. First swap with proofs succeeds +/// 2. Second swap with same proofs fails with TokenAlreadySpent +/// 3. ProofWriter should detect already-spent proofs +#[tokio::test(flavor = "multi_thread", worker_threads = 1)] +async fn test_swap_double_spend_detection() { + setup_tracing(); + let mint = create_and_start_test_mint() + .await + .expect("Failed to create test mint"); + let wallet = create_test_wallet_for_mint(mint.clone()) + .await + .expect("Failed to create test wallet"); + + // Fund wallet with 100 sats + fund_wallet(wallet.clone(), 100, None) + .await + .expect("Failed to fund wallet"); + + let proofs = wallet + .get_unspent_proofs() + .await + .expect("Could not get proofs"); + + let keyset_id = get_keyset_id(&mint).await; + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); + + // First swap + let preswap1 = PreMintSecrets::random( + keyset_id, + 100.into(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .expect("Failed to create preswap"); + + let swap_request1 = SwapRequest::new(proofs.clone(), preswap1.blinded_messages()); + mint.process_swap_request(swap_request1) + .await + .expect("First swap should succeed"); + + // Second swap with same proofs should fail + let preswap2 = PreMintSecrets::random( + keyset_id, + 100.into(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .expect("Failed to create preswap"); + + let swap_request2 = SwapRequest::new(proofs.clone(), preswap2.blinded_messages()); + let result = mint.process_swap_request(swap_request2).await; + + match result { + Err(cdk::Error::TokenAlreadySpent) => { + // Expected error + } + Err(err) => panic!("Wrong error type: {:?}", err), + Ok(_) => panic!("Double spend should not succeed"), + } +} + +/// Tests that unbalanced swap requests are rejected: +/// Case 1: Output amount < Input amount (trying to steal from mint) +/// Case 2: Output amount > Input amount (trying to create tokens) +/// Both should fail with TransactionUnbalanced error. +#[tokio::test(flavor = "multi_thread", worker_threads = 1)] +async fn test_swap_unbalanced_transaction_detection() { + setup_tracing(); + let mint = create_and_start_test_mint() + .await + .expect("Failed to create test mint"); + let wallet = create_test_wallet_for_mint(mint.clone()) + .await + .expect("Failed to create test wallet"); + + // Fund wallet with 100 sats + fund_wallet(wallet.clone(), 100, None) + .await + .expect("Failed to fund wallet"); + + let proofs = wallet + .get_unspent_proofs() + .await + .expect("Could not get proofs"); + + let keyset_id = get_keyset_id(&mint).await; + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); + + // Case 1: Try to swap for LESS (95 < 100) - underpaying + let preswap_less = PreMintSecrets::random( + keyset_id, + 95.into(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .expect("Failed to create preswap"); + + let swap_request_less = SwapRequest::new(proofs.clone(), preswap_less.blinded_messages()); + + match mint.process_swap_request(swap_request_less).await { + Err(cdk::Error::TransactionUnbalanced(_, _, _)) => { + // Expected error + } + Err(err) => panic!("Wrong error type for underpay: {:?}", err), + Ok(_) => panic!("Unbalanced swap (underpay) should not succeed"), + } + + // Case 2: Try to swap for MORE (105 > 100) - overpaying/creating tokens + let preswap_more = PreMintSecrets::random( + keyset_id, + 105.into(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .expect("Failed to create preswap"); + + let swap_request_more = SwapRequest::new(proofs.clone(), preswap_more.blinded_messages()); + + match mint.process_swap_request(swap_request_more).await { + Err(cdk::Error::TransactionUnbalanced(_, _, _)) => { + // Expected error + } + Err(err) => panic!("Wrong error type for overpay: {:?}", err), + Ok(_) => panic!("Unbalanced swap (overpay) should not succeed"), + } +} + +/// Tests P2PK (Pay-to-Public-Key) spending conditions: +/// 1. Create proofs locked to a public key +/// 2. Attempt swap without signature - should fail +/// 3. Attempt swap with valid signature - should succeed +/// Validates NUT-11 signature enforcement. +#[tokio::test(flavor = "multi_thread", worker_threads = 1)] +async fn test_swap_p2pk_signature_validation() { + setup_tracing(); + let mint = create_and_start_test_mint() + .await + .expect("Failed to create test mint"); + let wallet = create_test_wallet_for_mint(mint.clone()) + .await + .expect("Failed to create test wallet"); + + // Fund wallet with 100 sats + fund_wallet(wallet.clone(), 100, None) + .await + .expect("Failed to fund wallet"); + + let input_proofs = wallet + .get_unspent_proofs() + .await + .expect("Could not get proofs"); + + let keyset_id = get_keyset_id(&mint).await; + let secret_key = SecretKey::generate(); + + // Create P2PK locked outputs + let spending_conditions = SpendingConditions::new_p2pk(secret_key.public_key(), None); + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); + + let pre_swap = PreMintSecrets::with_conditions( + keyset_id, + 100.into(), + &SplitTarget::default(), + &spending_conditions, + &fee_and_amounts, + ) + .expect("Failed to create P2PK preswap"); + + let swap_request = SwapRequest::new(input_proofs.clone(), pre_swap.blinded_messages()); + + // First swap to get P2PK locked proofs + let keys = mint.pubkeys().keysets.first().cloned().unwrap().keys; + + let post_swap = mint + .process_swap_request(swap_request) + .await + .expect("Initial swap should succeed"); + + // Construct proofs from swap response + let mut p2pk_proofs = construct_proofs( + post_swap.signatures, + pre_swap.rs(), + pre_swap.secrets(), + &keys, + ) + .expect("Failed to construct proofs"); + + // Try to spend P2PK proofs WITHOUT signature - should fail + let preswap_unsigned = PreMintSecrets::random( + keyset_id, + 100.into(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .expect("Failed to create preswap"); + + let swap_request_unsigned = + SwapRequest::new(p2pk_proofs.clone(), preswap_unsigned.blinded_messages()); + + match mint.process_swap_request(swap_request_unsigned).await { + Err(cdk::Error::NUT11(cdk::nuts::nut11::Error::SignaturesNotProvided)) => { + // Expected error + } + Err(err) => panic!("Wrong error type: {:?}", err), + Ok(_) => panic!("Unsigned P2PK spend should fail"), + } + + // Sign the proofs with correct key + for proof in &mut p2pk_proofs { + proof + .sign_p2pk(secret_key.clone()) + .expect("Failed to sign proof"); + } + + // Try again WITH signature - should succeed + let preswap_signed = PreMintSecrets::random( + keyset_id, + 100.into(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .expect("Failed to create preswap"); + + let swap_request_signed = SwapRequest::new(p2pk_proofs, preswap_signed.blinded_messages()); + + mint.process_swap_request(swap_request_signed) + .await + .expect("Signed P2PK spend should succeed"); +} + +/// Tests rollback behavior when duplicate blinded messages are used: +/// This validates that the BlindedMessageWriter prevents reuse of blinded messages. +/// 1. First swap with blinded messages succeeds +/// 2. Second swap with same blinded messages fails +/// 3. The failure should happen early (during blinded message addition) +#[tokio::test(flavor = "multi_thread", worker_threads = 1)] +async fn test_swap_rollback_on_duplicate_blinded_message() { + setup_tracing(); + let mint = create_and_start_test_mint() + .await + .expect("Failed to create test mint"); + let wallet = create_test_wallet_for_mint(mint.clone()) + .await + .expect("Failed to create test wallet"); + + // Fund with enough for multiple swaps + fund_wallet(wallet.clone(), 200, None) + .await + .expect("Failed to fund wallet"); + + let all_proofs = wallet + .get_unspent_proofs() + .await + .expect("Could not get proofs"); + + let mid = all_proofs.len() / 2; + let proofs1: Vec<_> = all_proofs.iter().take(mid).cloned().collect(); + let proofs2: Vec<_> = all_proofs.iter().skip(mid).cloned().collect(); + + let keyset_id = get_keyset_id(&mint).await; + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); + + // Create shared blinded messages + let preswap = PreMintSecrets::random( + keyset_id, + proofs1.total_amount().unwrap(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .expect("Failed to create preswap"); + + let blinded_messages = preswap.blinded_messages(); + + // Extract proof2 ys before moving proofs2 + let proof2_ys: Vec<_> = proofs2.iter().map(|p| p.y().unwrap()).collect(); + + // First swap succeeds + let swap1 = SwapRequest::new(proofs1, blinded_messages.clone()); + mint.process_swap_request(swap1) + .await + .expect("First swap should succeed"); + + // Second swap with duplicate blinded messages should fail early + // The BlindedMessageWriter should detect duplicate and prevent the swap + let swap2 = SwapRequest::new(proofs2, blinded_messages.clone()); + let result = mint.process_swap_request(swap2).await; + + assert!( + result.is_err(), + "Duplicate blinded messages should cause failure" + ); + + // Verify the second set of proofs are NOT marked as spent + // (since the swap failed before processing them) + let states = mint + .localstore() + .get_proofs_states(&proof2_ys) + .await + .expect("Failed to get proof states"); + + for state in states { + assert!( + state.is_none(), + "Proofs from failed swap should not be marked as spent" + ); + } +} + +/// Tests concurrent swap attempts with same proofs: +/// Spawns 3 concurrent tasks trying to swap the same proofs. +/// Only one should succeed, others should fail with TokenAlreadySpent or TokenPending. +/// Validates that concurrent access is properly handled. +#[tokio::test(flavor = "multi_thread", worker_threads = 3)] +async fn test_swap_concurrent_double_spend_prevention() { + setup_tracing(); + let mint = create_and_start_test_mint() + .await + .expect("Failed to create test mint"); + let wallet = create_test_wallet_for_mint(mint.clone()) + .await + .expect("Failed to create test wallet"); + + // Fund wallet + fund_wallet(wallet.clone(), 100, None) + .await + .expect("Failed to fund wallet"); + + let proofs = wallet + .get_unspent_proofs() + .await + .expect("Could not get proofs"); + + let keyset_id = get_keyset_id(&mint).await; + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); + + // Create 3 different swap requests with SAME proofs but different outputs + let preswap1 = PreMintSecrets::random( + keyset_id, + 100.into(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .expect("Failed to create preswap 1"); + + let preswap2 = PreMintSecrets::random( + keyset_id, + 100.into(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .expect("Failed to create preswap 2"); + + let preswap3 = PreMintSecrets::random( + keyset_id, + 100.into(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .expect("Failed to create preswap 3"); + + let swap_request1 = SwapRequest::new(proofs.clone(), preswap1.blinded_messages()); + let swap_request2 = SwapRequest::new(proofs.clone(), preswap2.blinded_messages()); + let swap_request3 = SwapRequest::new(proofs.clone(), preswap3.blinded_messages()); + + // Spawn concurrent tasks + let mint1 = mint.clone(); + let mint2 = mint.clone(); + let mint3 = mint.clone(); + + let task1 = tokio::spawn(async move { mint1.process_swap_request(swap_request1).await }); + let task2 = tokio::spawn(async move { mint2.process_swap_request(swap_request2).await }); + let task3 = tokio::spawn(async move { mint3.process_swap_request(swap_request3).await }); + + // Wait for all tasks + let results = tokio::try_join!(task1, task2, task3).expect("Tasks should complete"); + + // Count successes and failures + let mut success_count = 0; + let mut failure_count = 0; + + for result in [results.0, results.1, results.2] { + match result { + Ok(_) => success_count += 1, + Err(cdk::Error::TokenAlreadySpent) | Err(cdk::Error::TokenPending) => { + failure_count += 1 + } + Err(err) => panic!("Unexpected error: {:?}", err), + } + } + + assert_eq!( + success_count, 1, + "Exactly one swap should succeed in concurrent scenario" + ); + assert_eq!( + failure_count, 2, + "Exactly two swaps should fail in concurrent scenario" + ); + + // Verify all proofs are marked as spent + let states = mint + .localstore() + .get_proofs_states(&proofs.iter().map(|p| p.y().unwrap()).collect::>()) + .await + .expect("Failed to get proof states"); + + for state in states { + assert_eq!( + State::Spent, + state.expect("State should be known"), + "All proofs should be marked as spent after concurrent attempts" + ); + } +} + +/// Tests swap with fees enabled: +/// 1. Create mint with keyset that has fees (1 sat per proof) +/// 2. Fund wallet with many small proofs +/// 3. Attempt swap without paying fee - should fail +/// 4. Attempt swap with correct fee deduction - should succeed +#[tokio::test(flavor = "multi_thread", worker_threads = 1)] +async fn test_swap_with_fees() { + setup_tracing(); + let mint = create_and_start_test_mint() + .await + .expect("Failed to create test mint"); + + let wallet = create_test_wallet_for_mint(mint.clone()) + .await + .expect("Failed to create test wallet"); + + // Rotate to keyset with 1 sat per proof fee + mint.rotate_keyset(CurrencyUnit::Sat, 32, 1) + .await + .expect("Failed to rotate keyset"); + + // Fund with 1000 sats as individual 1-sat proofs using the fee-based keyset + // Wait a bit for keyset to be available + tokio::time::sleep(std::time::Duration::from_millis(100)).await; + + fund_wallet(wallet.clone(), 1000, Some(SplitTarget::Value(Amount::ONE))) + .await + .expect("Failed to fund wallet"); + + let proofs = wallet + .get_unspent_proofs() + .await + .expect("Could not get proofs"); + + // Take 100 proofs (100 sats total, will need to pay fee) + let hundred_proofs: Vec<_> = proofs.iter().take(100).cloned().collect(); + + // Get the keyset ID from the proofs (which will be the fee-based keyset) + let keyset_id = hundred_proofs[0].keyset_id; + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); + + // Try to swap for 100 outputs (same as input) - should fail due to unpaid fee + let preswap_no_fee = PreMintSecrets::random( + keyset_id, + 100.into(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .expect("Failed to create preswap"); + + let swap_no_fee = SwapRequest::new(hundred_proofs.clone(), preswap_no_fee.blinded_messages()); + + match mint.process_swap_request(swap_no_fee).await { + Err(cdk::Error::TransactionUnbalanced(_, _, _)) => { + // Expected - didn't pay the fee + } + Err(err) => panic!("Wrong error type: {:?}", err), + Ok(_) => panic!("Should fail when fee not paid"), + } + + // Calculate correct fee (1 sat per input proof in this keyset) + let fee = hundred_proofs.len() as u64; // 1 sat per proof = 100 sats fee + let output_amount = 100 - fee; + + // Swap with correct fee deduction - should succeed if output_amount > 0 + if output_amount > 0 { + let preswap_with_fee = PreMintSecrets::random( + keyset_id, + output_amount.into(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .expect("Failed to create preswap with fee"); + + let swap_with_fee = + SwapRequest::new(hundred_proofs.clone(), preswap_with_fee.blinded_messages()); + + mint.process_swap_request(swap_with_fee) + .await + .expect("Swap with correct fee should succeed"); + } +} + +/// Tests that swap correctly handles amount overflow: +/// Attempts to create outputs that would overflow u64 when summed. +/// This should be rejected before any database operations occur. +#[tokio::test(flavor = "multi_thread", worker_threads = 1)] +async fn test_swap_amount_overflow_protection() { + setup_tracing(); + let mint = create_and_start_test_mint() + .await + .expect("Failed to create test mint"); + let wallet = create_test_wallet_for_mint(mint.clone()) + .await + .expect("Failed to create test wallet"); + + // Fund wallet + fund_wallet(wallet.clone(), 100, None) + .await + .expect("Failed to fund wallet"); + + let proofs = wallet + .get_unspent_proofs() + .await + .expect("Could not get proofs"); + + let keyset_id = get_keyset_id(&mint).await; + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); + + // Try to create outputs that would overflow + // 2^63 + 2^63 + small amount would overflow u64 + let large_amount = 2_u64.pow(63); + + let pre_mint1 = PreMintSecrets::random( + keyset_id, + large_amount.into(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .expect("Failed to create pre_mint1"); + + let pre_mint2 = PreMintSecrets::random( + keyset_id, + large_amount.into(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .expect("Failed to create pre_mint2"); + + let mut combined_pre_mint = PreMintSecrets::random( + keyset_id, + 1.into(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .expect("Failed to create combined_pre_mint"); + + combined_pre_mint.combine(pre_mint1); + combined_pre_mint.combine(pre_mint2); + + let swap_request = SwapRequest::new(proofs, combined_pre_mint.blinded_messages()); + + // Should fail with overflow/amount error + match mint.process_swap_request(swap_request).await { + Err(cdk::Error::NUT03(cdk::nuts::nut03::Error::Amount(_))) + | Err(cdk::Error::AmountOverflow) + | Err(cdk::Error::AmountError(_)) + | Err(cdk::Error::TransactionUnbalanced(_, _, _)) => { + // Any of these errors are acceptable for overflow + } + Err(err) => panic!("Unexpected error type: {:?}", err), + Ok(_) => panic!("Overflow swap should not succeed"), + } +} + +/// Tests swap state transitions through pubsub notifications: +/// 1. Subscribe to proof state changes +/// 2. Execute swap +/// 3. Verify Pending then Spent state transitions are received +/// Validates NUT-17 notification behavior. +#[tokio::test(flavor = "multi_thread", worker_threads = 1)] +async fn test_swap_state_transition_notifications() { + setup_tracing(); + let mint = create_and_start_test_mint() + .await + .expect("Failed to create test mint"); + let wallet = create_test_wallet_for_mint(mint.clone()) + .await + .expect("Failed to create test wallet"); + + // Fund wallet + fund_wallet(wallet.clone(), 100, None) + .await + .expect("Failed to fund wallet"); + + let proofs = wallet + .get_unspent_proofs() + .await + .expect("Could not get proofs"); + + let keyset_id = get_keyset_id(&mint).await; + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); + + let preswap = PreMintSecrets::random( + keyset_id, + 100.into(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .expect("Failed to create preswap"); + + let swap_request = SwapRequest::new(proofs.clone(), preswap.blinded_messages()); + + // Subscribe to proof state changes + let proof_ys: Vec = proofs.iter().map(|p| p.y().unwrap().to_string()).collect(); + + let mut listener = mint + .pubsub_manager() + .subscribe(cdk::subscription::Params { + kind: cdk::nuts::nut17::Kind::ProofState, + filters: proof_ys.clone(), + id: Arc::new("test_swap_notifications".into()), + }) + .expect("Should subscribe successfully"); + + // Execute swap + mint.process_swap_request(swap_request) + .await + .expect("Swap should succeed"); + + // Give pubsub time to deliver messages + tokio::time::sleep(std::time::Duration::from_millis(100)).await; + + // Collect all state transition notifications + let mut state_transitions: HashMap> = HashMap::new(); + + while let Some(msg) = listener.try_recv() { + match msg.into_inner() { + cashu::NotificationPayload::ProofState(cashu::ProofState { y, state, .. }) => { + state_transitions + .entry(y.to_string()) + .or_insert_with(Vec::new) + .push(state); + } + _ => panic!("Unexpected notification type"), + } + } + + // Verify each proof went through Pending -> Spent transition + for y in proof_ys { + let transitions = state_transitions + .get(&y) + .expect("Should have transitions for proof"); + + assert_eq!( + transitions, + &vec![State::Pending, State::Spent], + "Proof should transition from Pending to Spent" + ); + } +} + +/// Tests that swap fails gracefully when proof states cannot be updated: +/// This would test the rollback path where proofs are added but state update fails. +/// In the current implementation, this should trigger rollback of both proofs and blinded messages. +#[tokio::test(flavor = "multi_thread", worker_threads = 1)] +async fn test_swap_proof_state_consistency() { + setup_tracing(); + let mint = create_and_start_test_mint() + .await + .expect("Failed to create test mint"); + let wallet = create_test_wallet_for_mint(mint.clone()) + .await + .expect("Failed to create test wallet"); + + // Fund wallet + fund_wallet(wallet.clone(), 100, None) + .await + .expect("Failed to fund wallet"); + + let proofs = wallet + .get_unspent_proofs() + .await + .expect("Could not get proofs"); + + let keyset_id = get_keyset_id(&mint).await; + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); + + // Execute successful swap + let preswap = PreMintSecrets::random( + keyset_id, + 100.into(), + &SplitTarget::default(), + &fee_and_amounts, + ) + .expect("Failed to create preswap"); + + let swap_request = SwapRequest::new(proofs.clone(), preswap.blinded_messages()); + + mint.process_swap_request(swap_request) + .await + .expect("Swap should succeed"); + + // Verify all proofs have consistent state (Spent) + let proof_ys: Vec<_> = proofs.iter().map(|p| p.y().unwrap()).collect(); + + let states = mint + .localstore() + .get_proofs_states(&proof_ys) + .await + .expect("Failed to get proof states"); + + // All states should be Some(Spent) - none should be None or Pending + for (i, state) in states.iter().enumerate() { + match state { + Some(State::Spent) => { + // Expected state + } + Some(other_state) => { + panic!("Proof {} in unexpected state: {:?}", i, other_state) + } + None => { + panic!("Proof {} has no state (should be Spent)", i) + } + } + } +} diff --git a/justfile b/justfile index c250fa583..22d93fd14 100644 --- a/justfile +++ b/justfile @@ -75,6 +75,9 @@ test-pure db="memory": # Run pure integration tests (cargo test will only build what's needed for the test) CDK_TEST_DB_TYPE={{db}} cargo test -p cdk-integration-tests --test integration_tests_pure -- --test-threads 1 + + # Run swap flow tests (detailed testing of swap operation) + CDK_TEST_DB_TYPE={{db}} cargo test -p cdk-integration-tests --test test_swap_flow -- --test-threads 1 test-all db="memory": #!/usr/bin/env bash From f173b2da47e9514306f911a63e45e4f7a927ef06 Mon Sep 17 00:00:00 2001 From: tsk Date: Mon, 13 Oct 2025 09:21:12 +0100 Subject: [PATCH 223/321] feat(cdk): add melt quote state transition validation (#1188) Add state machine validation for melt quote transitions to prevent invalid state changes. Includes new error types and validation logic for Unpaid, Pending, Paid, and Failed states. --- crates/cdk-common/src/state.rs | 46 ++++++++++++++++++++++++++- crates/cdk-sql-common/src/mint/mod.rs | 4 ++- 2 files changed, 48 insertions(+), 2 deletions(-) diff --git a/crates/cdk-common/src/state.rs b/crates/cdk-common/src/state.rs index be080001e..de6d3cb4f 100644 --- a/crates/cdk-common/src/state.rs +++ b/crates/cdk-common/src/state.rs @@ -1,6 +1,6 @@ //! State transition rules -use cashu::State; +use cashu::{MeltQuoteState, State}; /// State transition Error #[derive(thiserror::Error, Debug)] @@ -14,6 +14,12 @@ pub enum Error { /// Invalid transition #[error("Invalid transition: From {0} to {1}")] InvalidTransition(State, State), + /// Already paid + #[error("Quote already paid")] + AlreadyPaid, + /// Invalid transition + #[error("Invalid melt quote state transition: From {0} to {1}")] + InvalidMeltQuoteTransition(MeltQuoteState, MeltQuoteState), } #[inline] @@ -37,3 +43,41 @@ pub fn check_state_transition(current_state: State, new_state: State) -> Result< Ok(()) } } + +#[inline] +/// Check if the melt quote state transition is allowed +/// +/// Valid transitions: +/// - Unpaid -> Pending, Failed +/// - Pending -> Unpaid, Paid, Failed +/// - Paid -> (no transitions allowed) +/// - Failed -> Pending +pub fn check_melt_quote_state_transition( + current_state: MeltQuoteState, + new_state: MeltQuoteState, +) -> Result<(), Error> { + let is_valid_transition = match current_state { + MeltQuoteState::Unpaid => { + matches!(new_state, MeltQuoteState::Pending | MeltQuoteState::Failed) + } + MeltQuoteState::Pending => matches!( + new_state, + MeltQuoteState::Unpaid | MeltQuoteState::Paid | MeltQuoteState::Failed + ), + MeltQuoteState::Failed => { + matches!(new_state, MeltQuoteState::Pending | MeltQuoteState::Unpaid) + } + MeltQuoteState::Paid => false, + MeltQuoteState::Unknown => true, + }; + + if !is_valid_transition { + Err(match current_state { + MeltQuoteState::Pending => Error::Pending, + MeltQuoteState::Paid => Error::AlreadyPaid, + _ => Error::InvalidMeltQuoteTransition(current_state, new_state), + }) + } else { + Ok(()) + } +} diff --git a/crates/cdk-sql-common/src/mint/mod.rs b/crates/cdk-sql-common/src/mint/mod.rs index a1d7ed932..8baf21709 100644 --- a/crates/cdk-sql-common/src/mint/mod.rs +++ b/crates/cdk-sql-common/src/mint/mod.rs @@ -28,7 +28,7 @@ use cdk_common::nut00::ProofsMethods; use cdk_common::payment::PaymentIdentifier; use cdk_common::quote_id::QuoteId; use cdk_common::secret::Secret; -use cdk_common::state::check_state_transition; +use cdk_common::state::{check_melt_quote_state_transition, check_state_transition}; use cdk_common::util::unix_time; use cdk_common::{ Amount, BlindSignature, BlindSignatureDleq, BlindedMessage, CurrencyUnit, Id, MeltQuoteState, @@ -1043,6 +1043,8 @@ VALUES (:quote_id, :amount, :timestamp); .transpose()? .ok_or(Error::QuoteNotFound)?; + check_melt_quote_state_transition(quote.state, state)?; + let rec = if state == MeltQuoteState::Paid { let current_time = unix_time(); query(r#"UPDATE melt_quote SET state = :state, paid_time = :paid_time, payment_preimage = :payment_preimage WHERE id = :id"#)? From 5caa7d58ed2000486cca38e30dd6f8a4aab6972f Mon Sep 17 00:00:00 2001 From: David Caseria Date: Mon, 13 Oct 2025 04:53:48 -0400 Subject: [PATCH 224/321] Configure internal Wallets of a MultiMintWallet (#1177) --- .../src/sub_commands/cat_device_login.rs | 18 +- crates/cdk-cli/src/sub_commands/cat_login.rs | 21 +- .../src/sub_commands/mint_blind_auth.rs | 43 +-- crates/cdk-cli/src/sub_commands/restore.rs | 2 +- crates/cdk-cli/src/utils.rs | 2 +- crates/cdk-ffi/src/multi_mint_wallet.rs | 75 ++++- crates/cdk/src/wallet/auth/mod.rs | 13 + crates/cdk/src/wallet/mod.rs | 14 + crates/cdk/src/wallet/multi_mint_wallet.rs | 310 ++++++++++++++++-- 9 files changed, 425 insertions(+), 73 deletions(-) diff --git a/crates/cdk-cli/src/sub_commands/cat_device_login.rs b/crates/cdk-cli/src/sub_commands/cat_device_login.rs index b2e6ded72..dacccc17c 100644 --- a/crates/cdk-cli/src/sub_commands/cat_device_login.rs +++ b/crates/cdk-cli/src/sub_commands/cat_device_login.rs @@ -29,19 +29,13 @@ pub async fn cat_device_login( ) -> Result<()> { let mint_url = sub_command_args.mint_url.clone(); - let wallet = match multi_mint_wallet.get_wallet(&mint_url).await { - Some(wallet) => wallet.clone(), - None => { - multi_mint_wallet.add_mint(mint_url.clone(), None).await?; - multi_mint_wallet - .get_wallet(&mint_url) - .await - .expect("Wallet should exist after adding mint") - } - }; + // Ensure the mint exists + if !multi_mint_wallet.has_mint(&mint_url).await { + multi_mint_wallet.add_mint(mint_url.clone()).await?; + } - let mint_info = wallet - .fetch_mint_info() + let mint_info = multi_mint_wallet + .fetch_mint_info(&mint_url) .await? .ok_or(anyhow!("Mint info not found"))?; diff --git a/crates/cdk-cli/src/sub_commands/cat_login.rs b/crates/cdk-cli/src/sub_commands/cat_login.rs index a25530836..adeab5cc5 100644 --- a/crates/cdk-cli/src/sub_commands/cat_login.rs +++ b/crates/cdk-cli/src/sub_commands/cat_login.rs @@ -31,20 +31,13 @@ pub async fn cat_login( ) -> Result<()> { let mint_url = sub_command_args.mint_url.clone(); - let wallet = match multi_mint_wallet.get_wallet(&mint_url).await { - Some(wallet) => wallet.clone(), - None => { - multi_mint_wallet.add_mint(mint_url.clone(), None).await?; - multi_mint_wallet - .get_wallet(&mint_url) - .await - .expect("Wallet should exist after adding mint") - .clone() - } - }; - - let mint_info = wallet - .fetch_mint_info() + // Ensure the mint exists + if !multi_mint_wallet.has_mint(&mint_url).await { + multi_mint_wallet.add_mint(mint_url.clone()).await?; + } + + let mint_info = multi_mint_wallet + .fetch_mint_info(&mint_url) .await? .ok_or(anyhow!("Mint info not found"))?; diff --git a/crates/cdk-cli/src/sub_commands/mint_blind_auth.rs b/crates/cdk-cli/src/sub_commands/mint_blind_auth.rs index 8e14341fe..f9a18df50 100644 --- a/crates/cdk-cli/src/sub_commands/mint_blind_auth.rs +++ b/crates/cdk-cli/src/sub_commands/mint_blind_auth.rs @@ -28,19 +28,12 @@ pub async fn mint_blind_auth( ) -> Result<()> { let mint_url = sub_command_args.mint_url.clone(); - let wallet = match multi_mint_wallet.get_wallet(&mint_url).await { - Some(wallet) => wallet.clone(), - None => { - multi_mint_wallet.add_mint(mint_url.clone(), None).await?; - multi_mint_wallet - .get_wallet(&mint_url) - .await - .expect("Wallet should exist after adding mint") - .clone() - } - }; + // Ensure the mint exists + if !multi_mint_wallet.has_mint(&mint_url).await { + multi_mint_wallet.add_mint(mint_url.clone()).await?; + } - wallet.fetch_mint_info().await?; + multi_mint_wallet.fetch_mint_info(&mint_url).await?; // Try to get the token from the provided argument or from the stored file let cat = match &sub_command_args.cat { @@ -68,7 +61,7 @@ pub async fn mint_blind_auth( }; // Try to set the access token - if let Err(err) = wallet.set_cat(cat.clone()).await { + if let Err(err) = multi_mint_wallet.set_cat(&mint_url, cat.clone()).await { tracing::error!("Could not set cat: {}", err); // Try to refresh the token if we have a refresh token @@ -76,7 +69,7 @@ pub async fn mint_blind_auth( println!("Attempting to refresh the access token..."); // Get the mint info to access OIDC configuration - if let Some(mint_info) = wallet.fetch_mint_info().await? { + if let Some(mint_info) = multi_mint_wallet.fetch_mint_info(&mint_url).await? { match refresh_access_token(&mint_info, &token_data.refresh_token).await { Ok((new_access_token, new_refresh_token)) => { println!("Successfully refreshed access token"); @@ -94,7 +87,9 @@ pub async fn mint_blind_auth( } // Try setting the new access token - if let Err(err) = wallet.set_cat(new_access_token).await { + if let Err(err) = + multi_mint_wallet.set_cat(&mint_url, new_access_token).await + { tracing::error!("Could not set refreshed cat: {}", err); return Err(anyhow::anyhow!( "Authentication failed even after token refresh" @@ -102,7 +97,9 @@ pub async fn mint_blind_auth( } // Set the refresh token - wallet.set_refresh_token(new_refresh_token).await?; + multi_mint_wallet + .set_refresh_token(&mint_url, new_refresh_token) + .await?; } Err(e) => { tracing::error!("Failed to refresh token: {}", e); @@ -119,8 +116,10 @@ pub async fn mint_blind_auth( // If we have a refresh token, set it if let Ok(Some(token_data)) = token_storage::get_token_for_mint(work_dir, &mint_url).await { tracing::info!("Attempting to use refresh access token to refresh auth token"); - wallet.set_refresh_token(token_data.refresh_token).await?; - wallet.refresh_access_token().await?; + multi_mint_wallet + .set_refresh_token(&mint_url, token_data.refresh_token) + .await?; + multi_mint_wallet.refresh_access_token(&mint_url).await?; } } @@ -129,8 +128,8 @@ pub async fn mint_blind_auth( let amount = match sub_command_args.amount { Some(amount) => amount, None => { - let mint_info = wallet - .fetch_mint_info() + let mint_info = multi_mint_wallet + .fetch_mint_info(&mint_url) .await? .ok_or(anyhow!("Unknown mint info"))?; mint_info @@ -139,7 +138,9 @@ pub async fn mint_blind_auth( } }; - let proofs = wallet.mint_blind_auth(Amount::from(amount)).await?; + let proofs = multi_mint_wallet + .mint_blind_auth(&mint_url, Amount::from(amount)) + .await?; println!("Received {} auth proofs for mint {mint_url}", proofs.len()); diff --git a/crates/cdk-cli/src/sub_commands/restore.rs b/crates/cdk-cli/src/sub_commands/restore.rs index 56247a4aa..1647660f9 100644 --- a/crates/cdk-cli/src/sub_commands/restore.rs +++ b/crates/cdk-cli/src/sub_commands/restore.rs @@ -18,7 +18,7 @@ pub async fn restore( let wallet = match multi_mint_wallet.get_wallet(&mint_url).await { Some(wallet) => wallet.clone(), None => { - multi_mint_wallet.add_mint(mint_url.clone(), None).await?; + multi_mint_wallet.add_mint(mint_url.clone()).await?; multi_mint_wallet .get_wallet(&mint_url) .await diff --git a/crates/cdk-cli/src/utils.rs b/crates/cdk-cli/src/utils.rs index 63396cc3f..06c3f3d22 100644 --- a/crates/cdk-cli/src/utils.rs +++ b/crates/cdk-cli/src/utils.rs @@ -34,7 +34,7 @@ pub async fn get_or_create_wallet( Some(wallet) => Ok(wallet.clone()), None => { tracing::debug!("Wallet does not exist creating.."); - multi_mint_wallet.add_mint(mint_url.clone(), None).await?; + multi_mint_wallet.add_mint(mint_url.clone()).await?; Ok(multi_mint_wallet .get_wallet(mint_url) .await diff --git a/crates/cdk-ffi/src/multi_mint_wallet.rs b/crates/cdk-ffi/src/multi_mint_wallet.rs index f63a56fee..06bf29745 100644 --- a/crates/cdk-ffi/src/multi_mint_wallet.rs +++ b/crates/cdk-ffi/src/multi_mint_wallet.rs @@ -118,9 +118,16 @@ impl MultiMintWallet { target_proof_count: Option, ) -> Result<(), FfiError> { let cdk_mint_url: cdk::mint_url::MintUrl = mint_url.try_into()?; - self.inner - .add_mint(cdk_mint_url, target_proof_count.map(|c| c as usize)) - .await?; + + if let Some(count) = target_proof_count { + let config = cdk::wallet::multi_mint_wallet::WalletConfig::new() + .with_target_proof_count(count as usize); + self.inner + .add_mint_with_config(cdk_mint_url, config) + .await?; + } else { + self.inner.add_mint(cdk_mint_url).await?; + } Ok(()) } @@ -380,6 +387,68 @@ impl MultiMintWallet { self.inner.verify_token_dleq(&cdk_token).await?; Ok(()) } + + /// Query mint for current mint information + pub async fn fetch_mint_info(&self, mint_url: MintUrl) -> Result, FfiError> { + let cdk_mint_url: cdk::mint_url::MintUrl = mint_url.try_into()?; + let mint_info = self.inner.fetch_mint_info(&cdk_mint_url).await?; + Ok(mint_info.map(Into::into)) + } +} + +/// Auth methods for MultiMintWallet +#[uniffi::export(async_runtime = "tokio")] +impl MultiMintWallet { + /// Set Clear Auth Token (CAT) for a specific mint + pub async fn set_cat(&self, mint_url: MintUrl, cat: String) -> Result<(), FfiError> { + let cdk_mint_url: cdk::mint_url::MintUrl = mint_url.try_into()?; + self.inner.set_cat(&cdk_mint_url, cat).await?; + Ok(()) + } + + /// Set refresh token for a specific mint + pub async fn set_refresh_token( + &self, + mint_url: MintUrl, + refresh_token: String, + ) -> Result<(), FfiError> { + let cdk_mint_url: cdk::mint_url::MintUrl = mint_url.try_into()?; + self.inner + .set_refresh_token(&cdk_mint_url, refresh_token) + .await?; + Ok(()) + } + + /// Refresh access token for a specific mint using the stored refresh token + pub async fn refresh_access_token(&self, mint_url: MintUrl) -> Result<(), FfiError> { + let cdk_mint_url: cdk::mint_url::MintUrl = mint_url.try_into()?; + self.inner.refresh_access_token(&cdk_mint_url).await?; + Ok(()) + } + + /// Mint blind auth tokens at a specific mint + pub async fn mint_blind_auth( + &self, + mint_url: MintUrl, + amount: Amount, + ) -> Result { + let cdk_mint_url: cdk::mint_url::MintUrl = mint_url.try_into()?; + let proofs = self + .inner + .mint_blind_auth(&cdk_mint_url, amount.into()) + .await?; + Ok(proofs.into_iter().map(|p| Arc::new(p.into())).collect()) + } + + /// Get unspent auth proofs for a specific mint + pub async fn get_unspent_auth_proofs( + &self, + mint_url: MintUrl, + ) -> Result, FfiError> { + let cdk_mint_url: cdk::mint_url::MintUrl = mint_url.try_into()?; + let auth_proofs = self.inner.get_unspent_auth_proofs(&cdk_mint_url).await?; + Ok(auth_proofs.into_iter().map(Into::into).collect()) + } } /// Transfer mode for mint-to-mint transfers diff --git a/crates/cdk/src/wallet/auth/mod.rs b/crates/cdk/src/wallet/auth/mod.rs index bb5abed2b..2cc432f91 100644 --- a/crates/cdk/src/wallet/auth/mod.rs +++ b/crates/cdk/src/wallet/auth/mod.rs @@ -65,4 +65,17 @@ impl Wallet { } Ok(()) } + + /// Set the auth client (AuthWallet) for this wallet + /// + /// This allows updating the auth wallet without recreating the wallet. + /// Also updates the client's auth wallet to keep them in sync. + #[instrument(skip_all)] + pub async fn set_auth_client(&self, auth_wallet: Option) { + let mut auth_wallet_guard = self.auth_wallet.write().await; + *auth_wallet_guard = auth_wallet.clone(); + + // Also update the client's auth wallet to keep them in sync + self.client.set_auth_wallet(auth_wallet).await; + } } diff --git a/crates/cdk/src/wallet/mod.rs b/crates/cdk/src/wallet/mod.rs index 6ac0f14db..999ff8753 100644 --- a/crates/cdk/src/wallet/mod.rs +++ b/crates/cdk/src/wallet/mod.rs @@ -673,6 +673,20 @@ impl Wallet { Ok(()) } + + /// Set the client (MintConnector) for this wallet + /// + /// This allows updating the connector without recreating the wallet. + pub fn set_client(&mut self, client: Arc) { + self.client = client; + } + + /// Set the target proof count for this wallet + /// + /// This controls how many proofs of each denomination the wallet tries to maintain. + pub fn set_target_proof_count(&mut self, count: usize) { + self.target_proof_count = count; + } } impl Drop for Wallet { diff --git a/crates/cdk/src/wallet/multi_mint_wallet.rs b/crates/cdk/src/wallet/multi_mint_wallet.rs index 1b5ec3f3b..d12066411 100644 --- a/crates/cdk/src/wallet/multi_mint_wallet.rs +++ b/crates/cdk/src/wallet/multi_mint_wallet.rs @@ -60,6 +60,50 @@ pub struct TransferResult { pub target_balance_after: Amount, } +/// Configuration for individual wallets within MultiMintWallet +#[derive(Clone, Default, Debug)] +pub struct WalletConfig { + /// Custom mint connector implementation + pub mint_connector: Option>, + /// Custom auth connector implementation + #[cfg(feature = "auth")] + pub auth_connector: Option>, + /// Target number of proofs to maintain at each denomination + pub target_proof_count: Option, +} + +impl WalletConfig { + /// Create a new empty WalletConfig + pub fn new() -> Self { + Self::default() + } + + /// Set custom mint connector + pub fn with_mint_connector( + mut self, + connector: Arc, + ) -> Self { + self.mint_connector = Some(connector); + self + } + + /// Set custom auth connector + #[cfg(feature = "auth")] + pub fn with_auth_connector( + mut self, + connector: Arc, + ) -> Self { + self.auth_connector = Some(connector); + self + } + + /// Set target proof count + pub fn with_target_proof_count(mut self, count: usize) -> Self { + self.target_proof_count = Some(count); + self + } +} + /// Multi Mint Wallet /// /// A wallet that manages multiple mints but supports only one currency unit. @@ -89,8 +133,8 @@ pub struct TransferResult { /// // Add mints to the wallet /// let mint_url1: MintUrl = "https://mint1.example.com".parse()?; /// let mint_url2: MintUrl = "https://mint2.example.com".parse()?; -/// wallet.add_mint(mint_url1.clone(), None).await?; -/// wallet.add_mint(mint_url2, None).await?; +/// wallet.add_mint(mint_url1.clone()).await?; +/// wallet.add_mint(mint_url2).await?; /// /// // Check total balance across all mints /// let balance = wallet.total_balance().await?; @@ -199,12 +243,149 @@ impl MultiMintWallet { } /// Adds a mint to this [MultiMintWallet] + /// + /// Creates a wallet for the specified mint using default or global settings. + /// For custom configuration, use `add_mint_with_config()`. #[instrument(skip(self))] - pub async fn add_mint( + pub async fn add_mint(&self, mint_url: MintUrl) -> Result<(), Error> { + // Create wallet with default settings + let wallet = self + .create_wallet_with_config(mint_url.clone(), None) + .await?; + + // Insert into wallets map + let mut wallets = self.wallets.write().await; + wallets.insert(mint_url, wallet); + + Ok(()) + } + + /// Adds a mint to this [MultiMintWallet] with custom configuration + /// + /// The provided configuration is used to create the wallet with custom connectors + /// and settings. Configuration is stored within the Wallet instance itself. + #[instrument(skip(self))] + pub async fn add_mint_with_config( + &self, + mint_url: MintUrl, + config: WalletConfig, + ) -> Result<(), Error> { + // Create wallet with the provided config + let wallet = self + .create_wallet_with_config(mint_url.clone(), Some(&config)) + .await?; + + // Insert into wallets map + let mut wallets = self.wallets.write().await; + wallets.insert(mint_url, wallet); + + Ok(()) + } + + /// Set or update configuration for a mint + /// + /// If the wallet already exists, it will be updated with the new config. + /// If the wallet doesn't exist, it will be created with the specified config. + #[instrument(skip(self))] + pub async fn set_mint_config( &self, mint_url: MintUrl, - target_proof_count: Option, + config: WalletConfig, ) -> Result<(), Error> { + // Check if wallet already exists + if self.has_mint(&mint_url).await { + // Update existing wallet in place + let mut wallets = self.wallets.write().await; + if let Some(wallet) = wallets.get_mut(&mint_url) { + // Update target_proof_count if provided + if let Some(count) = config.target_proof_count { + wallet.set_target_proof_count(count); + } + + // Update connector if provided + if let Some(connector) = config.mint_connector { + wallet.set_client(connector); + } + + // TODO: Handle auth_connector if provided + #[cfg(feature = "auth")] + if let Some(_auth_connector) = config.auth_connector { + // For now, we can't easily inject auth_connector into the wallet + // This would require additional work on the Wallet API + // We'll note this as a future enhancement + } + } + Ok(()) + } else { + // Wallet doesn't exist, create it with the provided config + self.add_mint_with_config(mint_url, config).await + } + } + + /// Set the auth client (AuthWallet) for a specific mint + /// + /// This allows updating the auth wallet for an existing mint wallet without recreating it. + #[cfg(feature = "auth")] + #[instrument(skip_all)] + pub async fn set_auth_client( + &self, + mint_url: &MintUrl, + auth_wallet: Option, + ) -> Result<(), Error> { + let wallets = self.wallets.read().await; + let wallet = wallets.get(mint_url).ok_or(Error::UnknownMint { + mint_url: mint_url.to_string(), + })?; + + wallet.set_auth_client(auth_wallet).await; + Ok(()) + } + + /// Remove mint from MultiMintWallet + #[instrument(skip(self))] + pub async fn remove_mint(&self, mint_url: &MintUrl) { + let mut wallets = self.wallets.write().await; + wallets.remove(mint_url); + } + + /// Internal: Create wallet with optional custom configuration + /// + /// Priority order for configuration: + /// 1. Custom connector from config (if provided) + /// 2. Global settings (proxy/Tor) + /// 3. Default HttpClient + async fn create_wallet_with_config( + &self, + mint_url: MintUrl, + config: Option<&WalletConfig>, + ) -> Result { + // Check if custom connector is provided in config + if let Some(cfg) = config { + if let Some(custom_connector) = &cfg.mint_connector { + // Use custom connector with WalletBuilder + let builder = WalletBuilder::new() + .mint_url(mint_url.clone()) + .unit(self.unit.clone()) + .localstore(self.localstore.clone()) + .seed(self.seed) + .target_proof_count(cfg.target_proof_count.unwrap_or(3)) + .shared_client(custom_connector.clone()); + + // TODO: Handle auth_connector if provided + #[cfg(feature = "auth")] + if let Some(_auth_connector) = &cfg.auth_connector { + // For now, we can't easily inject auth_connector into the wallet + // This would require additional work on the Wallet/WalletBuilder API + // We'll note this as a future enhancement + } + + return builder.build(); + } + } + + // Fall back to existing logic: proxy/Tor/default + let target_proof_count = config.and_then(|c| c.target_proof_count).unwrap_or(3); + let wallet = if let Some(proxy_url) = &self.proxy_config { // Create wallet with proxy-configured client let client = crate::wallet::HttpClient::with_proxy( @@ -228,7 +409,7 @@ impl MultiMintWallet { .unit(self.unit.clone()) .localstore(self.localstore.clone()) .seed(self.seed) - .target_proof_count(target_proof_count.unwrap_or(3)) + .target_proof_count(target_proof_count) .client(client) .build()? } else { @@ -256,7 +437,7 @@ impl MultiMintWallet { .unit(self.unit.clone()) .localstore(self.localstore.clone()) .seed(self.seed) - .target_proof_count(target_proof_count.unwrap_or(3)) + .target_proof_count(target_proof_count) .client(client) .build()? } else { @@ -266,7 +447,7 @@ impl MultiMintWallet { self.unit.clone(), self.localstore.clone(), self.seed, - target_proof_count, + Some(target_proof_count), )? } @@ -278,22 +459,12 @@ impl MultiMintWallet { self.unit.clone(), self.localstore.clone(), self.seed, - target_proof_count, + Some(target_proof_count), )? } }; - let mut wallets = self.wallets.write().await; - wallets.insert(mint_url, wallet); - - Ok(()) - } - - /// Remove mint from MultiMintWallet - #[instrument(skip(self))] - pub async fn remove_mint(&self, mint_url: &MintUrl) { - let mut wallets = self.wallets.write().await; - wallets.remove(mint_url); + Ok(wallet) } /// Load all wallets from database that have proofs for this currency unit @@ -317,7 +488,7 @@ impl MultiMintWallet { if mint_has_proofs_for_unit { // Add mint to the MultiMintWallet if not already present if !self.has_mint(&mint_url).await { - self.add_mint(mint_url.clone(), None).await? + self.add_mint(mint_url.clone()).await? } } } @@ -980,7 +1151,7 @@ impl MultiMintWallet { // Add the untrusted mint temporarily if needed if !is_trusted { - self.add_mint(mint_url.clone(), None).await?; + self.add_mint(mint_url.clone()).await?; } let wallets = self.wallets.read().await; @@ -1414,6 +1585,103 @@ impl MultiMintWallet { Ok(total_consolidated) } + + /// Mint blind auth tokens for a specific mint + /// + /// This is a convenience method that calls the underlying wallet's mint_blind_auth. + #[cfg(feature = "auth")] + #[instrument(skip_all)] + pub async fn mint_blind_auth( + &self, + mint_url: &MintUrl, + amount: Amount, + ) -> Result { + let wallets = self.wallets.read().await; + let wallet = wallets.get(mint_url).ok_or(Error::UnknownMint { + mint_url: mint_url.to_string(), + })?; + + wallet.mint_blind_auth(amount).await + } + + /// Get unspent auth proofs for a specific mint + /// + /// This is a convenience method that calls the underlying wallet's get_unspent_auth_proofs. + #[cfg(feature = "auth")] + #[instrument(skip_all)] + pub async fn get_unspent_auth_proofs( + &self, + mint_url: &MintUrl, + ) -> Result, Error> { + let wallets = self.wallets.read().await; + let wallet = wallets.get(mint_url).ok_or(Error::UnknownMint { + mint_url: mint_url.to_string(), + })?; + + wallet.get_unspent_auth_proofs().await + } + + /// Set Clear Auth Token (CAT) for authentication at a specific mint + /// + /// This is a convenience method that calls the underlying wallet's set_cat. + #[cfg(feature = "auth")] + #[instrument(skip_all)] + pub async fn set_cat(&self, mint_url: &MintUrl, cat: String) -> Result<(), Error> { + let wallets = self.wallets.read().await; + let wallet = wallets.get(mint_url).ok_or(Error::UnknownMint { + mint_url: mint_url.to_string(), + })?; + + wallet.set_cat(cat).await + } + + /// Set refresh token for authentication at a specific mint + /// + /// This is a convenience method that calls the underlying wallet's set_refresh_token. + #[cfg(feature = "auth")] + #[instrument(skip_all)] + pub async fn set_refresh_token( + &self, + mint_url: &MintUrl, + refresh_token: String, + ) -> Result<(), Error> { + let wallets = self.wallets.read().await; + let wallet = wallets.get(mint_url).ok_or(Error::UnknownMint { + mint_url: mint_url.to_string(), + })?; + + wallet.set_refresh_token(refresh_token).await + } + + /// Refresh CAT token for a specific mint + /// + /// This is a convenience method that calls the underlying wallet's refresh_access_token. + #[cfg(feature = "auth")] + #[instrument(skip(self))] + pub async fn refresh_access_token(&self, mint_url: &MintUrl) -> Result<(), Error> { + let wallets = self.wallets.read().await; + let wallet = wallets.get(mint_url).ok_or(Error::UnknownMint { + mint_url: mint_url.to_string(), + })?; + + wallet.refresh_access_token().await + } + + /// Query mint for current mint information + /// + /// This is a convenience method that calls the underlying wallet's fetch_mint_info. + #[instrument(skip(self))] + pub async fn fetch_mint_info( + &self, + mint_url: &MintUrl, + ) -> Result, Error> { + let wallets = self.wallets.read().await; + let wallet = wallets.get(mint_url).ok_or(Error::UnknownMint { + mint_url: mint_url.to_string(), + })?; + + wallet.fetch_mint_info().await + } } impl Drop for MultiMintWallet { From db2764c56627cf8f1b7cfcac8f2a9aa16c18bd72 Mon Sep 17 00:00:00 2001 From: Erik <78821053+swedishfrenchpress@users.noreply.github.com> Date: Wed, 15 Oct 2025 10:36:04 +0200 Subject: [PATCH 225/321] Redesign Lightning invoice creation and display with better UX and status handling (#1184) --------- Co-authored-by: thesimplekid --- .../src/web/handlers/dashboard.rs | 111 ++- .../cdk-ldk-node/src/web/handlers/invoices.rs | 193 +++-- .../src/web/handlers/lightning.rs | 155 ++-- .../cdk-ldk-node/src/web/handlers/onchain.rs | 86 +- .../cdk-ldk-node/src/web/handlers/payments.rs | 138 ++- .../src/web/templates/components.rs | 65 +- .../cdk-ldk-node/src/web/templates/layout.rs | 787 ++++++++++++++++-- .../src/web/templates/payments.rs | 1 + 8 files changed, 1180 insertions(+), 356 deletions(-) diff --git a/crates/cdk-ldk-node/src/web/handlers/dashboard.rs b/crates/cdk-ldk-node/src/web/handlers/dashboard.rs index 0b1471a5f..a24cab16d 100644 --- a/crates/cdk-ldk-node/src/web/handlers/dashboard.rs +++ b/crates/cdk-ldk-node/src/web/handlers/dashboard.rs @@ -140,8 +140,8 @@ pub async fn dashboard(State(state): State) -> Result, St // Balance Summary as metric cards div class="card" { - h2 { "Balance Summary" } - div class="metrics-container" { + h2 style="font-size: 0.875rem; font-weight: 600; text-transform: uppercase; letter-spacing: 0.05em; opacity: 0.5; padding-bottom: 1rem; border-bottom: 1px solid hsl(var(--border)); margin-bottom: 0;" { "Balance Summary" } + div class="metrics-container" style="margin-top: 1.5rem;" { div class="metric-card" { div class="metric-value" { (format_sats_as_btc(balances.total_lightning_balance_sats)) } div class="metric-label" { "Lightning Balance" } @@ -209,8 +209,8 @@ pub async fn dashboard(State(state): State) -> Result, St // Right side - Connections metrics aside class="node-metrics" { div class="card" { - h3 { "Connections" } - div class="metrics-container" { + h3 style="font-size: 0.875rem; font-weight: 600; text-transform: uppercase; letter-spacing: 0.05em; opacity: 0.5; padding-bottom: 1rem; border-bottom: 1px solid hsl(var(--border)); margin-bottom: 0;" { "Connections" } + div class="metrics-container" style="margin-top: 1.5rem;" { div class="metric-card" { div class="metric-value" { (format!("{}/{}", num_connected_peers, num_peers)) } div class="metric-label" { "Connected Peers" } @@ -224,51 +224,74 @@ pub async fn dashboard(State(state): State) -> Result, St } } - // Lightning Network Activity as metric cards + // Activity Sections - Side by Side Layout div class="card" { - h2 { "Lightning Network Activity" } - div class="metrics-container" { - div class="metric-card" { - div class="metric-value" { (format_sats_as_btc(metrics.lightning_inflow_24h)) } - div class="metric-label" { "24h LN Inflow" } - } - div class="metric-card" { - div class="metric-value" { (format_sats_as_btc(metrics.lightning_outflow_24h)) } - div class="metric-label" { "24h LN Outflow" } - } - div class="metric-card" { - div class="metric-value" { (format_sats_as_btc(metrics.lightning_inflow_all_time)) } - div class="metric-label" { "All-time LN Inflow" } - } - div class="metric-card" { - div class="metric-value" { (format_sats_as_btc(metrics.lightning_outflow_all_time)) } - div class="metric-label" { "All-time LN Outflow" } - } - } - } + h2 style="font-size: 0.875rem; font-weight: 600; text-transform: uppercase; letter-spacing: 0.05em; opacity: 0.5; padding-bottom: 1rem; margin-bottom: 0;" { "Activity Overview" } - // On-chain Activity as metric cards - div class="card" { - h2 { "On-chain Activity" } - div class="metrics-container" { - div class="metric-card" { - div class="metric-value" { (format_sats_as_btc(metrics.onchain_inflow_24h)) } - div class="metric-label" { "24h On-chain Inflow" } - } - div class="metric-card" { - div class="metric-value" { (format_sats_as_btc(metrics.onchain_outflow_24h)) } - div class="metric-label" { "24h On-chain Outflow" } - } - div class="metric-card" { - div class="metric-value" { (format_sats_as_btc(metrics.onchain_inflow_all_time)) } - div class="metric-label" { "All-time On-chain Inflow" } + div class="activity-grid" { + // Lightning Network Activity + div class="activity-section" { + div class="activity-header" { + div class="activity-icon-box" { + svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.25" stroke-linecap="round" stroke-linejoin="round" { + path d="M4 14a1 1 0 0 1-.78-1.63l9.9-10.2a.5.5 0 0 1 .86.46l-1.92 6.02A1 1 0 0 0 13 10h7a1 1 0 0 1 .78 1.63l-9.9 10.2a.5.5 0 0 1-.86-.46l1.92-6.02A1 1 0 0 0 11 14z" {} + } + } + h3 class="activity-title" { "Lightning Network Activity" } + } + + div class="activity-metrics" { + div class="activity-metric-card" { + div class="activity-metric-label" { "24h Inflow" } + div class="activity-metric-value" { (format_sats_as_btc(metrics.lightning_inflow_24h)) } + } + div class="activity-metric-card" { + div class="activity-metric-label" { "24h Outflow" } + div class="activity-metric-value" { (format_sats_as_btc(metrics.lightning_outflow_24h)) } + } + div class="activity-metric-card" { + div class="activity-metric-label" { "All-time Inflow" } + div class="activity-metric-value" { (format_sats_as_btc(metrics.lightning_inflow_all_time)) } + } + div class="activity-metric-card" { + div class="activity-metric-label" { "All-time Outflow" } + div class="activity-metric-value" { (format_sats_as_btc(metrics.lightning_outflow_all_time)) } + } + } } - div class="metric-card" { - div class="metric-value" { (format_sats_as_btc(metrics.onchain_outflow_all_time)) } - div class="metric-label" { "All-time On-chain Outflow" } + + // On-chain Activity + div class="activity-section" { + div class="activity-header" { + div class="activity-icon-box" { + svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.25" stroke-linecap="round" stroke-linejoin="round" { + path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71" {} + path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71" {} + } + } + h3 class="activity-title" { "On-chain Activity" } + } + + div class="activity-metrics" { + div class="activity-metric-card" { + div class="activity-metric-label" { "24h Inflow" } + div class="activity-metric-value" { (format_sats_as_btc(metrics.onchain_inflow_24h)) } + } + div class="activity-metric-card" { + div class="activity-metric-label" { "24h Outflow" } + div class="activity-metric-value" { (format_sats_as_btc(metrics.onchain_outflow_24h)) } + } + div class="activity-metric-card" { + div class="activity-metric-label" { "All-time Inflow" } + div class="activity-metric-value" { (format_sats_as_btc(metrics.onchain_inflow_all_time)) } + } + div class="activity-metric-card" { + div class="activity-metric-label" { "All-time Outflow" } + div class="activity-metric-value" { (format_sats_as_btc(metrics.onchain_outflow_all_time)) } + } + } } } - } }; diff --git a/crates/cdk-ldk-node/src/web/handlers/invoices.rs b/crates/cdk-ldk-node/src/web/handlers/invoices.rs index 7691e3838..931eb5c63 100644 --- a/crates/cdk-ldk-node/src/web/handlers/invoices.rs +++ b/crates/cdk-ldk-node/src/web/handlers/invoices.rs @@ -10,7 +10,7 @@ use serde::Deserialize; use crate::web::handlers::utils::{deserialize_optional_f64, deserialize_optional_u32}; use crate::web::handlers::AppState; use crate::web::templates::{ - error_message, form_card, format_sats_as_btc, info_card, is_node_running, layout_with_status, + error_message, format_sats_as_btc, invoice_display_card, is_node_running, layout_with_status, success_message, }; @@ -34,54 +34,101 @@ pub struct CreateBolt12Form { pub async fn invoices_page(State(state): State) -> Result, StatusCode> { let content = html! { h2 style="text-align: center; margin-bottom: 3rem;" { "Invoices" } - div class="grid" { - (form_card( - "Create BOLT11 Invoice", - html! { - form method="post" action="/invoices/bolt11" { - div class="form-group" { - label for="amount_btc" { "Amount" } - input type="number" id="amount_btc" name="amount_btc" required placeholder="₿0" step="0.00000001" {} - } - div class="form-group" { - label for="description" { "Description (optional)" } - input type="text" id="description" name="description" placeholder="Payment for..." {} - } - div class="form-group" { - label for="expiry_seconds" { "Expiry (seconds, optional)" } - input type="number" id="expiry_seconds" name="expiry_seconds" placeholder="3600" {} - } - button type="submit" { "Create BOLT11 Invoice" } + + div class="card" { + // Tab navigation + div class="payment-tabs" style="display: flex; gap: 0.5rem; margin-bottom: 1.5rem; border-bottom: 1px solid hsl(var(--border)); padding-bottom: 0;" { + button type="button" class="payment-tab active" onclick="switchInvoiceTab('bolt11')" data-tab="bolt11" { + "BOLT11 Invoice" + } + button type="button" class="payment-tab" onclick="switchInvoiceTab('bolt12')" data-tab="bolt12" { + "BOLT12 Offer" + } + } + + // BOLT11 tab content + div id="bolt11-content" class="tab-content active" { + form method="post" action="/invoices/bolt11" { + div class="form-group" { + label for="amount_btc_bolt11" { "Amount" } + input type="number" id="amount_btc_bolt11" name="amount_btc" required placeholder="₿0" step="0.00000001" {} + } + div class="form-group" { + label for="description_bolt11" { "Description (optional)" } + input type="text" id="description_bolt11" name="description" placeholder="Payment for..." {} + } + div class="form-group" { + label for="expiry_seconds_bolt11" { "Expiry (seconds, optional)" } + input type="number" id="expiry_seconds_bolt11" name="expiry_seconds" placeholder="3600" {} + } + div class="form-actions" { + a href="/balance" { button type="button" class="button-secondary" { "Cancel" } } + button type="submit" class="button-primary" { "Create BOLT11 Invoice" } } } - )) + } - (form_card( - "Create BOLT12 Offer", - html! { - form method="post" action="/invoices/bolt12" { - div class="form-group" { - label for="amount_btc" { "Amount (optional for variable amount)" } - input type="number" id="amount_btc" name="amount_btc" placeholder="₿0" step="0.00000001" {} - } - div class="form-group" { - label for="description" { "Description (optional)" } - input type="text" id="description" name="description" placeholder="Payment for..." {} + // BOLT12 tab content + div id="bolt12-content" class="tab-content" { + form method="post" action="/invoices/bolt12" { + div class="form-group" { + label for="amount_btc_bolt12" { "Amount (optional for variable amount)" } + input type="number" id="amount_btc_bolt12" name="amount_btc" placeholder="₿0" step="0.00000001" {} + p style="font-size: 0.8125rem; color: hsl(var(--muted-foreground)); margin-top: 0.5rem;" { + "Leave empty for variable amount offers, specify amount for fixed offers" } - div class="form-group" { - label for="expiry_seconds" { "Expiry (seconds, optional)" } - input type="number" id="expiry_seconds" name="expiry_seconds" placeholder="3600" {} - } - button type="submit" { "Create BOLT12 Offer" } + } + div class="form-group" { + label for="description_bolt12" { "Description (optional)" } + input type="text" id="description_bolt12" name="description" placeholder="Payment for..." {} + } + div class="form-group" { + label for="expiry_seconds_bolt12" { "Expiry (seconds, optional)" } + input type="number" id="expiry_seconds_bolt12" name="expiry_seconds" placeholder="3600" {} + } + div class="form-actions" { + a href="/balance" { button type="button" class="button-secondary" { "Cancel" } } + button type="submit" class="button-primary" { "Create BOLT12 Offer" } } } - )) + } + } + + // Tab switching script + script type="text/javascript" { + (maud::PreEscaped(r#" + function switchInvoiceTab(tabName) { + console.log('Switching to invoice tab:', tabName); + + // Hide all tab contents + const contents = document.querySelectorAll('.tab-content'); + contents.forEach(content => content.classList.remove('active')); + + // Remove active class from all tabs + const tabs = document.querySelectorAll('.payment-tab'); + tabs.forEach(tab => tab.classList.remove('active')); + + // Show selected tab content + const tabContent = document.getElementById(tabName + '-content'); + if (tabContent) { + tabContent.classList.add('active'); + console.log('Activated invoice tab content:', tabName); + } + + // Add active class to selected tab + const tabButton = document.querySelector('[data-tab="' + tabName + '"]'); + if (tabButton) { + tabButton.classList.add('active'); + console.log('Activated invoice tab button:', tabName); + } + } + "#)) } }; let is_running = is_node_running(&state.node.inner); Ok(Html( - layout_with_status("Create Invoices", content, is_running).into_string(), + layout_with_status("s", content, is_running).into_string(), )) } @@ -126,7 +173,7 @@ pub async fn post_create_bolt11( .status(StatusCode::BAD_REQUEST) .header("content-type", "text/html") .body(Body::from( - layout_with_status("Create Invoice Error", content, true).into_string(), + layout_with_status(" Error", content, true).into_string(), )) .unwrap()); } @@ -161,32 +208,25 @@ pub async fn post_create_bolt11( description_text.clone() }; + let invoice_details = vec![ + ("Payment Hash", invoice.payment_hash().to_string()), + ("Amount", format_sats_as_btc(form.amount_btc)), + ("Description", description_display), + ( + "Expires At", + format!("{}", current_time + expiry_seconds as u64), + ), + ]; + html! { (success_message("BOLT11 Invoice created successfully!")) - (info_card( - "Invoice Details", - vec![ - ("Payment Hash", invoice.payment_hash().to_string()), - ("Amount", format_sats_as_btc(form.amount_btc)), - ("Description", description_display), - ("Expires At", format!("{}", current_time + expiry_seconds as u64)), - ] - )) - div class="card" { - h3 { "Invoice (copy this to share)" } - textarea readonly style="width: 100%; height: 150px; font-family: monospace; font-size: 0.8rem;" { - (invoice.to_string()) - } - } - div class="card" { - a href="/invoices" { button { "← Create Another Invoice" } } - } + (invoice_display_card(&invoice.to_string(), &format_sats_as_btc(form.amount_btc), invoice_details, "/invoices")) } } Err(e) => { tracing::error!("Web interface: Failed to create BOLT11 invoice: {}", e); html! { - (error_message(&format!("Failed to create invoice: {e}"))) + (error_message(&format!("Failed to : {e}"))) div class="card" { a href="/invoices" { button { "← Try Again" } } } @@ -210,15 +250,15 @@ pub async fn post_create_bolt12( let description_text = form.description.unwrap_or_else(|| "".to_string()); tracing::info!( - "Web interface: Creating BOLT12 offer for amount={:?} btc, description={:?}, expiry={}s", + "Web interface: Creating BOLT12 offer for amount={:?} sats, description={:?}, expiry={}s", form.amount_btc, description_text, expiry_seconds ); let offer_result = if let Some(amount_btc) = form.amount_btc { - // Convert Bitcoin to millisatoshis (1 BTC = 100,000,000,000 msats) - let amount_msats = (amount_btc * 100_000_000_000.0) as u64; + // Convert satoshis to millisatoshis (1 sat = 1,000 msats) + let amount_msats = (amount_btc * 1_000.0) as u64; state.node.inner.bolt12_payment().receive( amount_msats, &description_text, @@ -246,7 +286,7 @@ pub async fn post_create_bolt12( let amount_display = form .amount_btc - .map(|a| format_sats_as_btc((a * 100_000_000.0) as u64)) + .map(|a| format_sats_as_btc(a as u64)) .unwrap_or_else(|| "Variable amount".to_string()); let description_display = if description_text.is_empty() { @@ -255,26 +295,19 @@ pub async fn post_create_bolt12( description_text }; + let offer_details = vec![ + ("Offer ID", offer.id().to_string()), + ("Amount", amount_display.clone()), + ("Description", description_display), + ( + "Expires At", + format!("{}", current_time + expiry_seconds as u64), + ), + ]; + html! { (success_message("BOLT12 Offer created successfully!")) - (info_card( - "Offer Details", - vec![ - ("Offer ID", offer.id().to_string()), - ("Amount", amount_display), - ("Description", description_display), - ("Expires At", format!("{}", current_time + expiry_seconds as u64)), - ] - )) - div class="card" { - h3 { "Offer (copy this to share)" } - textarea readonly style="width: 100%; height: 150px; font-family: monospace; font-size: 0.8rem;" { - (offer.to_string()) - } - } - div class="card" { - a href="/invoices" { button { "← Create Another Offer" } } - } + (invoice_display_card(&offer.to_string(), &amount_display, offer_details, "/invoices")) } } Err(e) => { diff --git a/crates/cdk-ldk-node/src/web/handlers/lightning.rs b/crates/cdk-ldk-node/src/web/handlers/lightning.rs index a5a0b9e7e..2782cb9d5 100644 --- a/crates/cdk-ldk-node/src/web/handlers/lightning.rs +++ b/crates/cdk-ldk-node/src/web/handlers/lightning.rs @@ -26,43 +26,33 @@ pub async fn balance_page(State(state): State) -> Result, html! { h2 style="text-align: center; margin-bottom: 3rem;" { "Lightning" } - // Quick Actions section - individual cards - div class="card" style="margin-bottom: 2rem;" { - h2 { "Quick Actions" } - div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); gap: 1.5rem; margin-top: 1.5rem;" { - // Open Channel Card - div class="quick-action-card" { - h3 style="font-size: 1.125rem; font-weight: 600; margin-bottom: 0.5rem; color: var(--text-primary);" { "Open Channel" } - p style="font-size: 0.875rem; color: var(--text-muted); margin-bottom: 1rem; line-height: 1.4;" { "Create a new Lightning Network channel to connect with another node." } - a href="/channels/open" style="text-decoration: none;" { - button class="button-outline" { "Open Channel" } - } + // Inactive channels warning (only show if > 0) + @if num_inactive_channels > 0 { + div class="card" style="background-color: #fef3c7; border: 1px solid #f59e0b; margin-bottom: 2rem;" { + h3 style="color: #92400e; margin-bottom: 0.5rem;" { "⚠️ Inactive Channels Detected" } + p style="color: #78350f; margin: 0;" { + "You have " (num_inactive_channels) " inactive channel(s). This may indicate a connectivity issue that requires attention." } + } + } - // Create Invoice Card - div class="quick-action-card" { - h3 style="font-size: 1.125rem; font-weight: 600; margin-bottom: 0.5rem; color: var(--text-primary);" { "Create Invoice" } - p style="font-size: 0.875rem; color: var(--text-muted); margin-bottom: 1rem; line-height: 1.4;" { "Generate a Lightning invoice to receive payments from other users or services." } - a href="/invoices" style="text-decoration: none;" { - button class="button-outline" { "Create Invoice" } + // Balance Information with action buttons in header + div class="card" { + div style="display: flex; justify-content: space-between; align-items: center; padding-bottom: 1rem; border-bottom: 1px solid hsl(var(--border)); margin-bottom: 0;" { + h2 style="font-size: 0.875rem; font-weight: 600; text-transform: uppercase; letter-spacing: 0.05em; opacity: 0.5; margin: 0;" { "Balance Information" } + div style="display: flex; gap: 0.5rem;" { + a href="/payments/send" style="text-decoration: none;" { + button class="button-outline" style="padding: 0.5rem 1rem; font-size: 0.875rem;" { "Send" } } - } - - // Make Payment Card - div class="quick-action-card" { - h3 style="font-size: 1.125rem; font-weight: 600; margin-bottom: 0.5rem; color: var(--text-primary);" { "Make Lightning Payment" } - p style="font-size: 0.875rem; color: var(--text-muted); margin-bottom: 1rem; line-height: 1.4;" { "Send Lightning payments to other users using invoices. BOLT 11 & 12 supported." } a href="/invoices" style="text-decoration: none;" { - button class="button-outline" { "Make Payment" } + button class="button-outline" style="padding: 0.5rem 1rem; font-size: 0.875rem;" { "Receive" } + } + a href="/channels/open" style="text-decoration: none;" { + button class="button-outline" style="padding: 0.5rem 1rem; font-size: 0.875rem;" { "Open Channel" } } } } - } - - // Balance Information as metric cards - div class="card" { - h2 { "Balance Information" } - div class="metrics-container" { + div class="metrics-container" style="margin-top: 1.5rem;" { div class="metric-card" { div class="metric-value" { (format_sats_as_btc(balances.total_lightning_balance_sats)) } div class="metric-label" { "Lightning Balance" } @@ -75,9 +65,11 @@ pub async fn balance_page(State(state): State) -> Result, div class="metric-value" { (format!("{}", num_active_channels)) } div class="metric-label" { "Active Channels" } } - div class="metric-card" { - div class="metric-value" { (format!("{}", num_inactive_channels)) } - div class="metric-label" { "Inactive Channels" } + @if num_inactive_channels > 0 { + div class="metric-card" { + div class="metric-value" style="color: #f59e0b;" { (format!("{}", num_inactive_channels)) } + div class="metric-label" { "Inactive Channels" } + } } } } @@ -90,43 +82,33 @@ pub async fn balance_page(State(state): State) -> Result, html! { h2 style="text-align: center; margin-bottom: 3rem;" { "Lightning" } - // Quick Actions section - individual cards - div class="card" style="margin-bottom: 2rem;" { - h2 { "Quick Actions" } - div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); gap: 1.5rem; margin-top: 1.5rem;" { - // Open Channel Card - div class="quick-action-card" { - h3 style="font-size: 1.125rem; font-weight: 600; margin-bottom: 0.5rem; color: var(--text-primary);" { "Open Channel" } - p style="font-size: 0.875rem; color: var(--text-muted); margin-bottom: 1rem; line-height: 1.4;" { "Create a new Lightning channel by connecting with another node." } - a href="/channels/open" style="text-decoration: none;" { - button class="button-outline" { "Open Channel" } - } + // Inactive channels warning (only show if > 0) + @if num_inactive_channels > 0 { + div class="card" style="background-color: #fef3c7; border: 1px solid #f59e0b; margin-bottom: 2rem;" { + h3 style="color: #92400e; margin-bottom: 0.5rem;" { "⚠️ Inactive Channels Detected" } + p style="color: #78350f; margin: 0;" { + "You have " (num_inactive_channels) " inactive channel(s). This may indicate a connectivity issue that requires attention." } + } + } - // Create Invoice Card - div class="quick-action-card" { - h3 style="font-size: 1.125rem; font-weight: 600; margin-bottom: 0.5rem; color: var(--text-primary);" { "Create Invoice" } - p style="font-size: 0.875rem; color: var(--text-muted); margin-bottom: 1rem; line-height: 1.4;" { "Generate a Lightning invoice to receive payments." } + // Balance Information with action buttons in header + div class="card" { + div style="display: flex; justify-content: space-between; align-items: center; padding-bottom: 1rem; border-bottom: 1px solid hsl(var(--border)); margin-bottom: 0;" { + h2 style="font-size: 0.875rem; font-weight: 600; text-transform: uppercase; letter-spacing: 0.05em; opacity: 0.5; margin: 0;" { "Balance Information" } + div style="display: flex; gap: 0.5rem;" { + a href="/payments/send" style="text-decoration: none;" { + button class="button-outline" style="padding: 0.5rem 1rem; font-size: 0.875rem;" { "Send" } + } a href="/invoices" style="text-decoration: none;" { - button class="button-outline" { "Create Invoice" } + button class="button-outline" style="padding: 0.5rem 1rem; font-size: 0.875rem;" { "Receive" } } - } - - // Make Payment Card - div class="quick-action-card" { - h3 style="font-size: 1.125rem; font-weight: 600; margin-bottom: 0.5rem; color: var(--text-primary);" { "Make Lightning Payment" } - p style="font-size: 0.875rem; color: var(--text-muted); margin-bottom: 1rem; line-height: 1.4;" { "Send Lightning payments to other users using invoices." } - a href="/payments/send" style="text-decoration: none;" { - button class="button-outline" { "Make Payment" } + a href="/channels/open" style="text-decoration: none;" { + button class="button-outline" style="padding: 0.5rem 1rem; font-size: 0.875rem;" { "Open Channel" } } } } - } - - // Balance Information as metric cards - div class="card" { - h2 { "Balance Information" } - div class="metrics-container" { + div class="metrics-container" style="margin-top: 1.5rem;" { div class="metric-card" { div class="metric-value" { (format_sats_as_btc(balances.total_lightning_balance_sats)) } div class="metric-label" { "Lightning Balance" } @@ -139,47 +121,48 @@ pub async fn balance_page(State(state): State) -> Result, div class="metric-value" { (format!("{}", num_active_channels)) } div class="metric-label" { "Active Channels" } } - div class="metric-card" { - div class="metric-value" { (format!("{}", num_inactive_channels)) } - div class="metric-label" { "Inactive Channels" } + @if num_inactive_channels > 0 { + div class="metric-card" { + div class="metric-value" style="color: #f59e0b;" { (format!("{}", num_inactive_channels)) } + div class="metric-label" { "Inactive Channels" } + } } } } // Channel Details header (outside card) - h2 class="section-header" { "Channel Details" } + h2 class="section-header" style="font-size: 0.875rem; font-weight: 600; text-transform: uppercase; letter-spacing: 0.05em; opacity: 0.5;" { "Channel Details" } - // Channels list - @for (index, channel) in channels.iter().enumerate() { + // Channels list + @for (index, channel) in channels.iter().enumerate() { @let node_id = channel.counterparty_node_id.to_string(); @let channel_number = index + 1; div class="channel-box" { - // Channel number as prominent header - div class="channel-alias" { (format!("Channel {}", channel_number)) } + // Channel header with number on left and status badge on right + div style="display: flex; justify-content: space-between; align-items: center; padding-bottom: 1rem; border-bottom: 1px solid hsl(var(--border)); margin-bottom: 1.5rem;" { + div class="channel-alias" style="font-size: 0.875rem; font-weight: 600; text-transform: uppercase; letter-spacing: 0.05em; opacity: 0.5; margin: 0;" { (format!("Channel {}", channel_number)) } + @if channel.is_usable { + span class="status-badge status-active" { "Active" } + } @else { + span class="status-badge status-inactive" { "Inactive" } + } + } - // Channel details in left-aligned format + // Channel details - ordered by label length div class="channel-details" { + div class="detail-row" { + span class="detail-label" { "Node ID" } + span class="detail-value" { (node_id) } + } div class="detail-row" { span class="detail-label" { "Channel ID" } - span class="detail-value-amount" { (channel.channel_id.to_string()) } + span class="detail-value" { (channel.channel_id.to_string()) } } @if let Some(short_channel_id) = channel.short_channel_id { div class="detail-row" { span class="detail-label" { "Short Channel ID" } - span class="detail-value-amount" { (short_channel_id.to_string()) } - } - } - div class="detail-row" { - span class="detail-label" { "Node ID" } - span class="detail-value-amount" { (node_id) } - } - div class="detail-row" { - span class="detail-label" { "Status" } - @if channel.is_usable { - span class="status-badge status-active" { "Active" } - } @else { - span class="status-badge status-inactive" { "Inactive" } + span class="detail-value" { (short_channel_id.to_string()) } } } } diff --git a/crates/cdk-ldk-node/src/web/handlers/onchain.rs b/crates/cdk-ldk-node/src/web/handlers/onchain.rs index 0a296fafd..2282001e8 100644 --- a/crates/cdk-ldk-node/src/web/handlers/onchain.rs +++ b/crates/cdk-ldk-node/src/web/handlers/onchain.rs @@ -33,33 +33,6 @@ pub struct ConfirmOnchainForm { confirmed: Option, } -fn quick_actions_section() -> maud::Markup { - html! { - div class="card" style="margin-bottom: 2rem;" { - h2 { "Quick Actions" } - div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); gap: 1.5rem; margin-top: 1.5rem;" { - // Receive Bitcoin Card - div class="quick-action-card" { - h3 style="font-size: 1.125rem; font-weight: 600; margin-bottom: 0.5rem; color: var(--text-primary);" { "Receive Bitcoin" } - p style="font-size: 0.875rem; color: var(--text-muted); margin-bottom: 1rem; line-height: 1.4;" { "Generate a new Bitcoin address to receive on-chain payments from other users or services." } - a href="/onchain?action=receive" style="text-decoration: none;" { - button class="button-outline" { "Receive Bitcoin" } - } - } - - // Send Bitcoin Card - div class="quick-action-card" { - h3 style="font-size: 1.125rem; font-weight: 600; margin-bottom: 0.5rem; color: var(--text-primary);" { "Send Bitcoin" } - p style="font-size: 0.875rem; color: var(--text-muted); margin-bottom: 1rem; line-height: 1.4;" { "Send Bitcoin to another address on the blockchain. Standard on-chain transactions." } - a href="/onchain?action=send" style="text-decoration: none;" { - button class="button-outline" { "Send Bitcoin" } - } - } - } - } - } -} - pub async fn get_new_address(State(state): State) -> Result, StatusCode> { let address_result = state.node.inner.onchain_payment().new_address(); @@ -67,8 +40,8 @@ pub async fn get_new_address(State(state): State) -> Result { html! { div class="card" { - h2 { "Bitcoin Address" } - div class="address-display" { + h2 style="font-size: 0.875rem; font-weight: 600; text-transform: uppercase; letter-spacing: 0.05em; opacity: 0.5; padding-bottom: 1rem; border-bottom: 1px solid hsl(var(--border)); margin-bottom: 0;" { "Bitcoin Address" } + div class="address-display" style="margin-top: 1.5rem;" { div class="address-container" { span class="address-text" { (address.to_string()) } } @@ -113,13 +86,20 @@ pub async fn onchain_page( let mut content = html! { h2 style="text-align: center; margin-bottom: 3rem;" { "On-chain" } - // Quick Actions section - only show on overview - (quick_actions_section()) - - // On-chain Balance as metric cards + // On-chain Balance with action buttons in header div class="card" { - h2 { "On-chain Balance" } - div class="metrics-container" { + div style="display: flex; justify-content: space-between; align-items: center; padding-bottom: 1rem; border-bottom: 1px solid hsl(var(--border)); margin-bottom: 0;" { + h2 style="font-size: 0.875rem; font-weight: 600; text-transform: uppercase; letter-spacing: 0.05em; opacity: 0.5; margin: 0;" { "On-chain Balance" } + div style="display: flex; gap: 0.5rem;" { + a href="/onchain?action=send" style="text-decoration: none;" { + button class="button-outline" style="padding: 0.5rem 1rem; font-size: 0.875rem;" { "Send" } + } + a href="/onchain?action=receive" style="text-decoration: none;" { + button class="button-outline" style="padding: 0.5rem 1rem; font-size: 0.875rem;" { "Receive" } + } + } + } + div class="metrics-container" style="margin-top: 1.5rem;" { div class="metric-card" { div class="metric-value" { (format_sats_as_btc(balances.total_onchain_balance_sats)) } div class="metric-label" { "Total Balance" } @@ -162,10 +142,20 @@ pub async fn onchain_page( } )) - // On-chain Balance as metric cards + // On-chain Balance with action buttons in header div class="card" { - h2 { "On-chain Balance" } - div class="metrics-container" { + div style="display: flex; justify-content: space-between; align-items: center; padding-bottom: 1rem; border-bottom: 1px solid hsl(var(--border)); margin-bottom: 0;" { + h2 style="font-size: 0.875rem; font-weight: 600; text-transform: uppercase; letter-spacing: 0.05em; opacity: 0.5; margin: 0;" { "On-chain Balance" } + div style="display: flex; gap: 0.5rem;" { + a href="/onchain?action=send" style="text-decoration: none;" { + button class="button-outline" style="padding: 0.5rem 1rem; font-size: 0.875rem;" { "Send" } + } + a href="/onchain?action=receive" style="text-decoration: none;" { + button class="button-outline" style="padding: 0.5rem 1rem; font-size: 0.875rem;" { "Receive" } + } + } + } + div class="metrics-container" style="margin-top: 1.5rem;" { div class="metric-card" { div class="metric-value" { (format_sats_as_btc(balances.total_onchain_balance_sats)) } div class="metric-label" { "Total Balance" } @@ -196,10 +186,20 @@ pub async fn onchain_page( } )) - // On-chain Balance as metric cards + // On-chain Balance with action buttons in header div class="card" { - h2 { "On-chain Balance" } - div class="metrics-container" { + div style="display: flex; justify-content: space-between; align-items: center; padding-bottom: 1rem; border-bottom: 1px solid hsl(var(--border)); margin-bottom: 0;" { + h2 style="font-size: 0.875rem; font-weight: 600; text-transform: uppercase; letter-spacing: 0.05em; opacity: 0.5; margin: 0;" { "On-chain Balance" } + div style="display: flex; gap: 0.5rem;" { + a href="/onchain?action=send" style="text-decoration: none;" { + button class="button-outline" style="padding: 0.5rem 1rem; font-size: 0.875rem;" { "Send" } + } + a href="/onchain?action=receive" style="text-decoration: none;" { + button class="button-outline" style="padding: 0.5rem 1rem; font-size: 0.875rem;" { "Receive" } + } + } + } + div class="metrics-container" style="margin-top: 1.5rem;" { div class="metric-card" { div class="metric-value" { (format_sats_as_btc(balances.total_onchain_balance_sats)) } div class="metric-label" { "Total Balance" } @@ -324,8 +324,8 @@ pub async fn onchain_confirm_page( // Transaction Details Card div class="card" { - h2 { "Transaction Details" } - div class="transaction-details" { + h2 style="font-size: 0.875rem; font-weight: 600; text-transform: uppercase; letter-spacing: 0.05em; opacity: 0.5; padding-bottom: 1rem; border-bottom: 1px solid hsl(var(--border)); margin-bottom: 0;" { "Transaction Details" } + div class="transaction-details" style="margin-top: 1.5rem;" { div class="detail-row" { span class="detail-label" { "Recipient Address:" } span class="detail-value" { (form.address.clone()) } diff --git a/crates/cdk-ldk-node/src/web/handlers/payments.rs b/crates/cdk-ldk-node/src/web/handlers/payments.rs index 6d0570220..3bcfbc43d 100644 --- a/crates/cdk-ldk-node/src/web/handlers/payments.rs +++ b/crates/cdk-ldk-node/src/web/handlers/payments.rs @@ -15,7 +15,7 @@ use serde::Deserialize; use crate::web::handlers::utils::{deserialize_optional_u64, get_paginated_payments_streaming}; use crate::web::handlers::AppState; use crate::web::templates::{ - error_message, form_card, format_msats_as_btc, format_sats_as_btc, info_card, is_node_running, + error_message, format_msats_as_btc, format_sats_as_btc, info_card, is_node_running, layout_with_status, payment_list_item, success_message, }; @@ -86,7 +86,7 @@ pub async fn payments_page( div class="card" { div class="payment-list-header" { div { - h2 { "Payment History" } + h2 style="font-size: 0.875rem; font-weight: 600; text-transform: uppercase; letter-spacing: 0.05em; opacity: 0.5; padding-bottom: 1rem; border-bottom: 1px solid hsl(var(--border)); margin-bottom: 0;" { "Payment History" } @if total_count > 0 { p style="margin: 0.25rem 0 0 0; color: #666; font-size: 0.9rem;" { "Showing " (start_index + 1) " to " (end_index) " of " (total_count) " payments" @@ -116,14 +116,6 @@ pub async fn payments_page( PaymentDirection::Outbound => "Outbound", }; - @let status_str = match payment.status { - PaymentStatus::Pending => "Pending", - PaymentStatus::Succeeded => "Succeeded", - PaymentStatus::Failed => "Failed", - }; - - @let amount_str = payment.amount_msat.map(format_msats_as_btc).unwrap_or_else(|| "Unknown".to_string()); - @let (payment_hash, description, payment_type, preimage) = match &payment.kind { PaymentKind::Bolt11 { hash, preimage, .. } => { (Some(hash.to_string()), None::, "BOLT11", preimage.map(|p| p.to_string())) @@ -147,6 +139,27 @@ pub async fn payments_page( }, }; + @let status_str = { + // Helper function to determine invoice status + fn get_invoice_status(status: PaymentStatus, direction: PaymentDirection, payment_type: &str) -> &'static str { + match status { + PaymentStatus::Succeeded => "Succeeded", + PaymentStatus::Failed => "Failed", + PaymentStatus::Pending => { + // For inbound BOLT11 payments, show "Unpaid" instead of "Pending" + if direction == PaymentDirection::Inbound && payment_type == "BOLT11" { + "Unpaid" + } else { + "Pending" + } + } + } + } + get_invoice_status(payment.status, payment.direction, payment_type) + }; + + @let amount_str = payment.amount_msat.map(format_msats_as_btc).unwrap_or_else(|| "Unknown".to_string()); + (payment_list_item( &payment.id.to_string(), direction_str, @@ -245,42 +258,91 @@ pub async fn payments_page( pub async fn send_payments_page(State(state): State) -> Result, StatusCode> { let content = html! { h2 style="text-align: center; margin-bottom: 3rem;" { "Send Payment" } - div class="grid" { - (form_card( - "Pay BOLT11 Invoice", - html! { - form method="post" action="/payments/bolt11" { - div class="form-group" { - label for="invoice" { "BOLT11 Invoice" } - textarea id="invoice" name="invoice" required placeholder="lnbc..." style="height: 120px;" {} - } - div class="form-group" { - label for="amount_btc" { "Amount Override (optional)" } - input type="number" id="amount_btc" name="amount_btc" placeholder="Leave empty to use invoice amount" step="1" {} + + div class="card" { + // Tab navigation + div class="payment-tabs" style="display: flex; gap: 0.5rem; margin-bottom: 1.5rem; border-bottom: 1px solid hsl(var(--border)); padding-bottom: 0;" { + button type="button" class="payment-tab active" onclick="switchTab('bolt11')" data-tab="bolt11" { + "BOLT11 Invoice" + } + button type="button" class="payment-tab" onclick="switchTab('bolt12')" data-tab="bolt12" { + "BOLT12 Offer" + } + } + + // BOLT11 tab content + div id="bolt11-content" class="tab-content active" { + form method="post" action="/payments/bolt11" { + div class="form-group" { + label for="invoice" { "BOLT11 Invoice" } + textarea id="invoice" name="invoice" required placeholder="lnbc..." rows="4" {} + } + div class="form-group" { + label for="amount_btc_bolt11" { "Amount Override (optional)" } + input type="number" id="amount_btc_bolt11" name="amount_btc" placeholder="Leave empty to use invoice amount" step="1" {} + p style="font-size: 0.8125rem; color: hsl(var(--muted-foreground)); margin-top: 0.5rem;" { + "Only specify an amount if you want to override the invoice amount" } - button type="submit" { "Pay BOLT11 Invoice" } + } + div class="form-actions" { + a href="/balance" { button type="button" class="button-secondary" { "Cancel" } } + button type="submit" class="button-primary" { "Pay Invoice" } } } - )) - - (form_card( - "Pay BOLT12 Offer", - html! { - form method="post" action="/payments/bolt12" { - div class="form-group" { - label for="offer" { "BOLT12 Offer" } - textarea id="offer" name="offer" required placeholder="lno..." style="height: 120px;" {} - } - div class="form-group" { - label for="amount_btc" { "Amount (required for variable amount offers)" } - input type="number" id="amount_btc" name="amount_btc" placeholder="Required for variable amount offers, ignored for fixed amount offers" step="1" {} + } + + // BOLT12 tab content + div id="bolt12-content" class="tab-content" { + form method="post" action="/payments/bolt12" { + div class="form-group" { + label for="offer" { "BOLT12 Offer" } + textarea id="offer" name="offer" required placeholder="lno..." rows="4" {} + } + div class="form-group" { + label for="amount_btc_bolt12" { "Amount" } + input type="number" id="amount_btc_bolt12" name="amount_btc" placeholder="Amount in satoshis" step="1" {} + p style="font-size: 0.8125rem; color: hsl(var(--muted-foreground)); margin-top: 0.5rem;" { + "Required for variable amount offers, ignored for fixed amount offers" } - button type="submit" { "Pay BOLT12 Offer" } + } + div class="form-actions" { + a href="/balance" { button type="button" class="button-secondary" { "Cancel" } } + button type="submit" class="button-primary" { "Pay Offer" } } } - )) + } } + // Tab switching script + script type="text/javascript" { + (maud::PreEscaped(r#" + function switchTab(tabName) { + console.log('Switching to tab:', tabName); + + // Hide all tab contents + const contents = document.querySelectorAll('.tab-content'); + contents.forEach(content => content.classList.remove('active')); + + // Remove active class from all tabs + const tabs = document.querySelectorAll('.payment-tab'); + tabs.forEach(tab => tab.classList.remove('active')); + + // Show selected tab content + const tabContent = document.getElementById(tabName + '-content'); + if (tabContent) { + tabContent.classList.add('active'); + console.log('Activated tab content:', tabName); + } + + // Add active class to selected tab + const tabButton = document.querySelector('[data-tab="' + tabName + '"]'); + if (tabButton) { + tabButton.classList.add('active'); + console.log('Activated tab button:', tabName); + } + } + "#)) + } }; let is_running = is_node_running(&state.node.inner); diff --git a/crates/cdk-ldk-node/src/web/templates/components.rs b/crates/cdk-ldk-node/src/web/templates/components.rs index bbada534a..6df325e65 100644 --- a/crates/cdk-ldk-node/src/web/templates/components.rs +++ b/crates/cdk-ldk-node/src/web/templates/components.rs @@ -3,11 +3,13 @@ use maud::{html, Markup}; pub fn info_card(title: &str, items: Vec<(&str, String)>) -> Markup { html! { div class="card" { - h2 { (title) } - @for (label, value) in items { - div class="info-item" { - span class="info-label" { (label) ":" } - span class="info-value" { (value) } + h2 style="font-size: 0.875rem; font-weight: 600; text-transform: uppercase; letter-spacing: 0.05em; opacity: 0.5; padding-bottom: 1rem; border-bottom: 1px solid hsl(var(--border)); margin-bottom: 0;" { (title) } + div style="margin-top: 1.5rem;" { + @for (label, value) in items { + div class="info-item" { + span class="info-label" { (label) ":" } + span class="info-value" { (value) } + } } } } @@ -17,8 +19,10 @@ pub fn info_card(title: &str, items: Vec<(&str, String)>) -> Markup { pub fn form_card(title: &str, form_content: Markup) -> Markup { html! { div class="card" { - h2 { (title) } - (form_content) + h2 style="font-size: 0.875rem; font-weight: 600; text-transform: uppercase; letter-spacing: 0.05em; opacity: 0.5; padding-bottom: 1rem; border-bottom: 1px solid hsl(var(--border)); margin-bottom: 0;" { (title) } + div style="margin-top: 1.5rem;" { + (form_content) + } } } } @@ -34,3 +38,50 @@ pub fn error_message(message: &str) -> Markup { div class="error" { (message) } } } + +pub fn invoice_display_card( + invoice_text: &str, + amount: &str, + details: Vec<(&str, String)>, + back_url: &str, +) -> Markup { + html! { + div class="card" { + div style="display: flex; justify-content: space-between; align-items: center; padding-bottom: 1rem; border-bottom: 1px solid hsl(var(--border)); margin-bottom: 1.5rem;" { + h3 style="font-size: 0.875rem; font-weight: 600; text-transform: uppercase; letter-spacing: 0.05em; opacity: 0.5; margin: 0;" { "Invoice Details" } + } + + // Amount highlight section at the top + div class="invoice-amount-section" { + div class="invoice-amount-label" { "Amount" } + div class="invoice-amount-value" { (amount) } + } + + // Invoice display section - under the amount + div class="invoice-display-section" { + div class="invoice-label" { "Invoice" } + div class="invoice-display-container" { + textarea readonly class="invoice-textarea" { (invoice_text) } + } + } + + // Invoice details section - after the invoice with increased spacing + div class="invoice-details-section" style="margin-top: 2.5rem;" { + h4 style="font-size: 0.875rem; font-weight: 600; text-transform: uppercase; letter-spacing: 0.05em; opacity: 0.5; margin: 0 0 1rem 0;" { "Details" } + @for (label, value) in details { + div class="info-item" { + span class="info-label" { (label) ":" } + span class="info-value" { (value) } + } + } + } + + // Back button at bottom left - no border lines + div style="margin-top: 2rem;" { + a href=(back_url) style="text-decoration: none;" { + button class="button-outline" style="padding: 0.5rem 1rem; font-size: 0.875rem;" { "Back" } + } + } + } + } +} diff --git a/crates/cdk-ldk-node/src/web/templates/layout.rs b/crates/cdk-ldk-node/src/web/templates/layout.rs index 76cc167d0..9e191a4bf 100644 --- a/crates/cdk-ldk-node/src/web/templates/layout.rs +++ b/crates/cdk-ldk-node/src/web/templates/layout.rs @@ -39,7 +39,7 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar --border: 214.3 31.8% 91.4%; --input: 214.3 31.8% 91.4%; --ring: 222.2 84% 4.9%; - --radius: 0.5rem; + --radius: 0; /* Typography scale */ --fs-title: 1.25rem; @@ -148,11 +148,16 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar } .detail-label { - color: var(--text-muted) !important; + color: hsl(var(--foreground)) !important; + opacity: 0.5 !important; } .detail-value, .detail-value-amount { - color: var(--text-secondary) !important; + color: hsl(var(--foreground)) !important; + } + + .info-value { + color: var(--text-primary) !important; } .metric-label, .balance-label { @@ -177,7 +182,7 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar .quick-action-card { background-color: rgba(255, 255, 255, 0.03) !important; border: none !important; - border-radius: 0.75rem !important; + border-radius: 0 !important; padding: 1.5rem !important; } @@ -219,7 +224,7 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar flex-shrink: 0; background-color: hsl(var(--muted) / 0.3); border: 1px solid hsl(var(--border)); - border-radius: var(--radius); + border-radius: 0; padding: 0.75rem; display: flex; align-items: center; @@ -231,7 +236,7 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar .header-avatar-image { width: 48px; height: 48px; - border-radius: calc(var(--radius) - 2px); + border-radius: 0; object-fit: cover; display: block; } @@ -282,9 +287,11 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar } .node-subtitle { - font-size: 0.875rem; - color: var(--header-subtitle); + font-size: 0.75rem; + color: var(--text-muted); font-weight: 500; + letter-spacing: 0.05em; + text-transform: uppercase; } .header-right { @@ -340,7 +347,7 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar } .node-subtitle { - font-size: 0.8125rem; + font-size: 0.6875rem; text-align: center; } @@ -436,10 +443,12 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar /* Hero section styling */ header { position: relative; - background-image: url('/static/images/bg.jpg?v=3'); - background-size: cover; - background-position: center; - background-repeat: no-repeat; + background-color: hsl(var(--background)); + background-image: + linear-gradient(hsl(var(--border)) 1px, transparent 1px), + linear-gradient(90deg, hsl(var(--border)) 1px, transparent 1px); + background-size: 40px 40px; + background-position: -1px -1px; border-bottom: 1px solid hsl(var(--border)); margin-bottom: 2rem; text-align: left; @@ -450,10 +459,34 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar justify-content: flex-start; } - /* Dark mode header background - using different image */ + /* Subtle diamond gradient fade on edges */ + header::before { + content: ''; + position: absolute; + top: 0; + left: 0; + right: 0; + bottom: 0; + background: + linear-gradient(90deg, hsl(var(--background)) 0%, transparent 15%, transparent 85%, hsl(var(--background)) 100%), + linear-gradient(180deg, hsl(var(--background)) 0%, transparent 15%, transparent 85%, hsl(var(--background)) 100%); + pointer-events: none; + z-index: 1; + } + + /* Dark mode header background - subtle grid with darker theme */ @media (prefers-color-scheme: dark) { header { - background-image: url('/static/images/bg-dark.jpg?v=3'); + background-color: rgb(18, 19, 21); + background-image: + linear-gradient(rgba(255, 255, 255, 0.03) 1px, transparent 1px), + linear-gradient(90deg, rgba(255, 255, 255, 0.03) 1px, transparent 1px); + } + + header::before { + background: + linear-gradient(90deg, rgb(18, 19, 21) 0%, transparent 15%, transparent 85%, rgb(18, 19, 21) 100%), + linear-gradient(180deg, rgb(18, 19, 21) 0%, transparent 15%, transparent 85%, rgb(18, 19, 21) 100%); } } @@ -501,6 +534,37 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar animation: fade-in 0.3s ease-out; } + /* Corner embellishments for angular design */ + .card::before, + .card::after { + content: ''; + position: absolute; + width: 16px; + height: 16px; + border: 1px solid hsl(var(--border)); + } + + .card::before { + top: -1px; + left: -1px; + border-right: none; + border-bottom: none; + } + + .card::after { + bottom: -1px; + right: -1px; + border-left: none; + border-top: none; + } + + @media (prefers-color-scheme: dark) { + .card::before, + .card::after { + border-color: rgba(255, 255, 255, 0.2); + } + } + /* Modern Navigation Bar Styling */ nav { background-color: hsl(var(--card)); @@ -544,7 +608,7 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar font-weight: 600; color: hsl(var(--muted-foreground)); padding: 1rem 1.5rem; - border-radius: calc(var(--radius) - 2px); + border-radius: 0; transition: all 200ms cubic-bezier(0.4, 0, 0.2, 1); position: relative; min-height: 3rem; @@ -575,12 +639,13 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar } .card { + position: relative; background-color: hsl(var(--card)); border: 1px solid hsl(var(--border)); - border-radius: var(--radius); + border-radius: 0; padding: 1.5rem; margin-bottom: 1.5rem; - box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.05); + box-shadow: none; } /* Metric cards styling - matching balance-item style */ @@ -592,15 +657,46 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar } .metric-card { + position: relative; flex: 1; min-width: 200px; text-align: center; padding: 1rem; background-color: hsl(var(--muted) / 0.3); - border-radius: calc(var(--radius) - 2px); + border-radius: 0; border: 1px solid hsl(var(--border)); } + .metric-card::before, + .metric-card::after { + content: ''; + position: absolute; + width: 12px; + height: 12px; + border: 1px solid hsl(var(--border)); + } + + .metric-card::before { + top: -1px; + left: -1px; + border-right: none; + border-bottom: none; + } + + .metric-card::after { + bottom: -1px; + right: -1px; + border-left: none; + border-top: none; + } + + @media (prefers-color-scheme: dark) { + .metric-card::before, + .metric-card::after { + border-color: rgba(255, 255, 255, 0.2); + } + } + .metric-value { font-size: 1.5rem; font-weight: 600; @@ -651,7 +747,7 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar flex: 1; background-color: hsl(var(--background)); border: 1px solid hsl(var(--input)); - border-radius: calc(var(--radius) - 2px); + border-radius: 0; padding: 0.5rem 0.75rem; font-size: 0.875rem; line-height: 1.25; @@ -672,6 +768,10 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar background-color: hsl(0 0% 10%); border-color: hsl(var(--ring)); } + + textarea { + color: var(--text-primary) !important; + } } input:focus, textarea:focus, select:focus { @@ -707,7 +807,7 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar .per-page-selector select { background-color: transparent; border: 1px solid hsl(var(--muted)); - border-radius: calc(var(--radius) - 2px); + border-radius: 0; padding: 0.25rem 0.5rem; font-size: 0.875rem; color: hsl(var(--muted-foreground)); @@ -759,7 +859,7 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar align-items: center; justify-content: center; white-space: nowrap; - border-radius: calc(var(--radius) - 2px); + border-radius: 0; font-size: 0.875rem; font-weight: 600; transition: all 150ms ease-in-out; @@ -820,14 +920,14 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar .button-sm { height: 2rem; - border-radius: calc(var(--radius) - 4px); + border-radius: 0; padding: 0 0.75rem; font-size: 0.75rem; } .button-lg { height: 2.75rem; - border-radius: var(--radius); + border-radius: 0; padding: 0 2rem; font-size: 1rem; } @@ -932,7 +1032,7 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar background-color: hsl(var(--secondary)); color: hsl(var(--secondary-foreground)); border: 1px solid hsl(var(--border)); - border-radius: calc(var(--radius) - 4px); + border-radius: 0; padding: 0.25rem 0.5rem; cursor: pointer; font-size: 0.75rem; @@ -949,6 +1049,186 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar border-color: hsl(var(--border)); } + /* Invoice details section */ + .invoice-details-section { + margin-bottom: 1.5rem; + padding-bottom: 1.5rem; + border-bottom: 1px solid hsl(var(--border)); + } + + /* Invoice amount section - prominent display */ + .invoice-amount-section { + text-align: center; + margin-bottom: 2rem; + padding: 1.5rem; + background-color: hsl(var(--muted) / 0.3); + border: 1px solid hsl(var(--border)); + position: relative; + } + + .invoice-amount-section::before, + .invoice-amount-section::after { + content: ''; + position: absolute; + width: 16px; + height: 16px; + border: 1px solid hsl(var(--border)); + } + + .invoice-amount-section::before { + top: -1px; + left: -1px; + border-right: none; + border-bottom: none; + } + + .invoice-amount-section::after { + bottom: -1px; + right: -1px; + border-left: none; + border-top: none; + } + + .invoice-amount-label { + font-size: 0.875rem; + font-weight: 500; + color: hsl(var(--muted-foreground)); + margin-bottom: 0.5rem; + text-transform: uppercase; + letter-spacing: 0.05em; + } + + .invoice-amount-value { + font-size: 2rem; + font-weight: 700; + font-family: 'SF Mono', 'Monaco', 'Inconsolata', 'Roboto Mono', 'Courier New', monospace; + color: hsl(var(--foreground)); + line-height: 1.2; + } + + /* Invoice display section */ + .invoice-display-section { + margin-top: 1rem; + } + + .invoice-label { + font-size: 0.875rem; + font-weight: 600; + color: hsl(var(--foreground)); + text-transform: uppercase; + letter-spacing: 0.05em; + margin-bottom: 0.75rem; + } + + .invoice-display-container { + background-color: hsl(var(--muted) / 0.3); + border: 1px solid hsl(var(--border)); + border-radius: 0; + padding: 1rem; + position: relative; + } + + .invoice-display-container::before, + .invoice-display-container::after { + content: ''; + position: absolute; + width: 12px; + height: 12px; + border: 1px solid hsl(var(--border)); + } + + .invoice-display-container::before { + top: -1px; + left: -1px; + border-right: none; + border-bottom: none; + } + + .invoice-display-container::after { + bottom: -1px; + right: -1px; + border-left: none; + border-top: none; + } + + .invoice-textarea { + width: 100%; + background-color: transparent !important; + border: none !important; + font-family: 'SF Mono', 'Monaco', 'Inconsolata', 'Roboto Mono', 'Courier New', monospace !important; + font-size: 0.875rem !important; + color: var(--fg-primary) !important; + padding: 0 !important; + margin: 0 !important; + outline: none !important; + word-break: break-all; + overflow-wrap: break-word; + hyphens: auto; + line-height: 1.5; + text-align: left; + resize: none; + min-height: 100px; + height: auto; + overflow: visible; + } + + .invoice-textarea:focus { + box-shadow: none !important; + border: none !important; + } + + /* Dark mode invoice display styling */ + @media (prefers-color-scheme: dark) { + .invoice-amount-section { + background-color: rgba(255, 255, 255, 0.03) !important; + border: none !important; + } + + .invoice-amount-section::before, + .invoice-amount-section::after { + border-color: rgba(255, 255, 255, 0.2); + } + + .invoice-amount-label { + color: var(--text-muted) !important; + } + + .invoice-amount-value { + color: var(--text-primary) !important; + } + + .invoice-label { + color: var(--text-primary) !important; + } + + .invoice-display-container { + background-color: rgba(255, 255, 255, 0.03) !important; + border: none !important; + } + + .invoice-display-container::before, + .invoice-display-container::after { + border-color: rgba(255, 255, 255, 0.2); + } + + .invoice-textarea { + color: var(--text-primary) !important; + } + } + + /* Responsive invoice display */ + @media (max-width: 640px) { + .invoice-amount-value { + font-size: 1.5rem; + } + + .invoice-textarea { + font-size: 0.75rem !important; + line-height: 1.4; + min-height: 80px; + } + } + .balance-item, .balance-item-container { padding: 1.25rem 0; @@ -998,7 +1278,7 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar .alert { border: 1px solid hsl(var(--border)); - border-radius: var(--radius); + border-radius: 0; padding: 1rem; margin-bottom: 1rem; } @@ -1027,7 +1307,7 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar background-color: hsl(142.1 70.6% 45.3% / 0.1); color: hsl(142.1 76.2% 36.3%); border: 1px solid hsl(142.1 76.2% 36.3%); - border-radius: var(--radius); + border-radius: 0; padding: 1rem; margin-bottom: 1rem; } @@ -1037,7 +1317,7 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar background-color: hsl(var(--destructive) / 0.1); color: hsl(var(--destructive)); border: 1px solid hsl(var(--destructive)); - border-radius: var(--radius); + border-radius: 0; padding: 1rem; margin-bottom: 1rem; } @@ -1110,13 +1390,44 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar } .channel-box { + position: relative; background-color: hsl(var(--card)); border: 1px solid hsl(var(--border)); - border-radius: var(--radius); + border-radius: 0; padding: 1.5rem; margin-bottom: 1.5rem; } + .channel-box::before, + .channel-box::after { + content: ''; + position: absolute; + width: 16px; + height: 16px; + border: 1px solid hsl(var(--border)); + } + + .channel-box::before { + top: -1px; + left: -1px; + border-right: none; + border-bottom: none; + } + + .channel-box::after { + bottom: -1px; + right: -1px; + border-left: none; + border-top: none; + } + + @media (prefers-color-scheme: dark) { + .channel-box::before, + .channel-box::after { + border-color: rgba(255, 255, 255, 0.2); + } + } + .section-header { font-size: 1.25rem; font-weight: 700; @@ -1139,9 +1450,10 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar .detail-row { display: flex; - align-items: baseline; - margin-bottom: 0.75rem; - gap: 1rem; + align-items: center; + margin-bottom: 1rem; + gap: 1.5rem; + padding: 0.75rem 0; } .detail-row:last-child { @@ -1150,27 +1462,36 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar .detail-label { font-weight: 500; - color: hsl(var(--muted-foreground)); - font-size: 0.875rem; - min-width: 120px; + color: hsl(var(--foreground)); + opacity: 0.5; + font-size: 0.8125rem; + min-width: 140px; flex-shrink: 0; + letter-spacing: 0.025em; + text-transform: uppercase; + text-align: right; } .detail-value { color: hsl(var(--foreground)); font-family: 'SF Mono', 'Monaco', 'Inconsolata', 'Roboto Mono', 'Courier New', monospace; font-size: 0.875rem; + font-weight: 400; word-break: break-all; flex: 1; min-width: 0; + letter-spacing: -0.01em; + line-height: 1.5; } .detail-value-amount { color: hsl(var(--foreground)); - font-size: 0.875rem; + font-size: 0.9375rem; + font-weight: 500; word-break: break-all; flex: 1; min-width: 0; + letter-spacing: 0; } .channel-actions { @@ -1212,13 +1533,44 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar } .balance-item { + position: relative; text-align: center; padding: 1rem; background-color: hsl(var(--muted) / 0.3); - border-radius: calc(var(--radius) - 2px); + border-radius: 0; border: 1px solid hsl(var(--border)); } + .balance-item::before, + .balance-item::after { + content: ''; + position: absolute; + width: 12px; + height: 12px; + border: 1px solid hsl(var(--border)); + } + + .balance-item::before { + top: -1px; + left: -1px; + border-right: none; + border-bottom: none; + } + + .balance-item::after { + bottom: -1px; + right: -1px; + border-left: none; + border-top: none; + } + + @media (prefers-color-scheme: dark) { + .balance-item::before, + .balance-item::after { + border-color: rgba(255, 255, 255, 0.2); + } + } + .balance-amount { font-weight: 600; font-size: 1.125rem; @@ -1230,13 +1582,44 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar .payment-item { + position: relative; background-color: hsl(var(--card)); border: 1px solid hsl(var(--border)); - border-radius: var(--radius); + border-radius: 0; padding: 1.5rem; margin-bottom: 1.5rem; } + .payment-item::before, + .payment-item::after { + content: ''; + position: absolute; + width: 16px; + height: 16px; + border: 1px solid hsl(var(--border)); + } + + .payment-item::before { + top: -1px; + left: -1px; + border-right: none; + border-bottom: none; + } + + .payment-item::after { + bottom: -1px; + right: -1px; + border-left: none; + border-top: none; + } + + @media (prefers-color-scheme: dark) { + .payment-item::before, + .payment-item::after { + border-color: rgba(255, 255, 255, 0.2); + } + } + /* Dark mode payment card improvements - match other cards */ @media (prefers-color-scheme: dark) { .payment-item { @@ -1307,18 +1690,23 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar } .payment-label { - font-weight: 500; - color: hsl(var(--muted-foreground)); - font-size: 0.875rem; + font-weight: 400; + color: var(--text-muted); + font-size: 0.75rem; flex-shrink: 0; + letter-spacing: 0.05em; + text-transform: uppercase; } .payment-value { - color: hsl(var(--foreground)); + color: var(--text-tertiary); font-family: 'SF Mono', 'Monaco', 'Inconsolata', 'Roboto Mono', 'Courier New', monospace; - font-size: 0.875rem; + font-size: 0.8125rem; + font-weight: 300; word-break: break-all; min-width: 0; + letter-spacing: -0.02em; + line-height: 1.7; } .payment-list-header { @@ -1353,7 +1741,7 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar padding: 0.5rem 1rem; border: 1px solid hsl(var(--border)); background-color: hsl(var(--background)); - border-radius: calc(var(--radius) - 2px); + border-radius: 0; text-decoration: none; color: hsl(var(--muted-foreground)); font-size: 0.875rem; @@ -1500,7 +1888,7 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar align-items: center; justify-content: center; white-space: nowrap; - border-radius: calc(var(--radius) - 2px); + border-radius: 0; font-size: 0.875rem; font-weight: 600; transition: all 150ms ease-in-out; @@ -1613,18 +2001,49 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar } .node-info-main-container { + position: relative; flex: 1; display: flex; flex-direction: column; gap: 1rem; background-color: hsl(var(--card)); border: 1px solid hsl(var(--border)); - border-radius: var(--radius); + border-radius: 0; padding: 1.5rem; - box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.05); + box-shadow: none; height: 100%; } + .node-info-main-container::before, + .node-info-main-container::after { + content: ''; + position: absolute; + width: 16px; + height: 16px; + border: 1px solid hsl(var(--border)); + } + + .node-info-main-container::before { + top: -1px; + left: -1px; + border-right: none; + border-bottom: none; + } + + .node-info-main-container::after { + bottom: -1px; + right: -1px; + border-left: none; + border-top: none; + } + + @media (prefers-color-scheme: dark) { + .node-info-main-container::before, + .node-info-main-container::after { + border-color: rgba(255, 255, 255, 0.2); + } + } + .node-info-left { display: flex; align-items: center; @@ -1636,7 +2055,7 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar flex-shrink: 0; background-color: hsl(var(--muted) / 0.3); border: 1px solid hsl(var(--border)); - border-radius: var(--radius); + border-radius: 0; padding: 0.75rem; display: flex; align-items: center; @@ -1648,7 +2067,7 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar .avatar-image { width: 48px; height: 48px; - border-radius: calc(var(--radius) - 2px); + border-radius: 0; object-fit: cover; display: block; } @@ -1670,8 +2089,11 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar } .node-address { - font-size: 0.875rem; - color: var(--fg-muted); + font-size: 0.75rem; + color: var(--text-muted); + font-weight: 500; + letter-spacing: 0.05em; + text-transform: uppercase; margin: 0; line-height: var(--lh-normal); } @@ -1679,7 +2101,7 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar .node-content-box { background-color: hsl(var(--muted) / 0.3); border: 1px solid hsl(var(--border)); - border-radius: var(--radius); + border-radius: 0; min-height: 200px; padding: 1rem; display: flex; @@ -1807,6 +2229,167 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar } } + /* Activity Grid Layout - Side by Side */ + .activity-grid { + display: grid; + grid-template-columns: 1fr 1fr; + gap: 0; + margin-top: 1.5rem; + } + + .activity-section { + padding: 2rem 1.5rem; + border-right: 1px solid hsl(var(--border)); + border-top: 1px solid hsl(var(--border)); + } + + .activity-section:last-child { + border-right: none; + } + + .activity-header { + display: flex; + align-items: center; + gap: 0.75rem; + margin-bottom: 2rem; + padding-bottom: 0; + border-bottom: none; + } + + .activity-icon-box { + flex-shrink: 0; + background-color: hsl(var(--muted) / 0.3); + border: 1px solid hsl(var(--border)); + border-radius: 0; + padding: 0.5rem; + display: flex; + align-items: center; + justify-content: center; + width: 36px; + height: 36px; + } + + .activity-icon-box svg { + color: hsl(var(--foreground)); + } + + .activity-title { + font-size: 1rem; + font-weight: 400; + color: hsl(var(--foreground)); + margin: 0; + text-transform: none; + letter-spacing: normal; + } + + .activity-metrics { + display: flex; + flex-direction: column; + gap: 1rem; + } + + .activity-metric-card { + position: relative; + text-align: left; + padding: 1rem; + background-color: hsl(var(--muted) / 0.3); + border-radius: 0; + border: 1px solid hsl(var(--border)); + } + + .activity-metric-card::before, + .activity-metric-card::after { + content: ''; + position: absolute; + width: 12px; + height: 12px; + border: 1px solid hsl(var(--border)); + } + + .activity-metric-card::before { + top: -1px; + left: -1px; + border-right: none; + border-bottom: none; + } + + .activity-metric-card::after { + bottom: -1px; + right: -1px; + border-left: none; + border-top: none; + } + + .activity-metric-label { + display: block; + margin-bottom: 0.5rem; + font-size: 0.875rem; + font-weight: 400; + color: hsl(var(--muted-foreground)); + text-transform: none; + letter-spacing: normal; + } + + .activity-metric-value { + display: block; + font-size: 1.5rem; + font-weight: 600; + color: hsl(var(--foreground)); + font-family: 'SF Mono', 'Monaco', 'Inconsolata', 'Roboto Mono', 'Courier New', monospace; + line-height: 1.2; + } + + /* Dark mode activity styling */ + @media (prefers-color-scheme: dark) { + .activity-icon-box { + background-color: rgba(255, 255, 255, 0.03) !important; + border: none !important; + } + + .activity-icon-box svg { + color: var(--text-primary); + } + + .activity-title { + color: var(--text-primary); + } + + .activity-metric-card { + background-color: rgba(255, 255, 255, 0.03) !important; + border: none !important; + } + + .activity-metric-card::before, + .activity-metric-card::after { + border-color: rgba(255, 255, 255, 0.2); + } + + .activity-metric-label { + color: var(--text-muted) !important; + } + + .activity-metric-value { + color: var(--text-primary) !important; + } + } + + /* Responsive activity grid */ + @media (max-width: 768px) { + .activity-grid { + grid-template-columns: 1fr; + } + + .activity-section { + border-right: none; + border-bottom: 1px solid hsl(var(--border)); + padding: 1.5rem 1rem; + } + + .activity-section:last-child { + border-bottom: none; + } + } + /* Responsive typography adjustments */ @media (max-width: 640px) { :root { @@ -1816,6 +2399,87 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar .node-name { font-size: 0.875rem; } + + .activity-metric-value { + font-size: 1.25rem; + } + } + + /* Payment tabs styling */ + .payment-tabs { + display: flex; + gap: 0.5rem; + margin-bottom: 1.5rem; + border-bottom: 1px solid hsl(var(--border)); + } + + .payment-tab { + display: inline-flex; + align-items: center; + justify-content: center; + white-space: nowrap; + padding: 0.75rem 1.5rem; + border: none; + border-bottom: 2px solid transparent; + background-color: transparent; + border-radius: 0; + text-decoration: none; + color: hsl(var(--muted-foreground)); + font-size: 0.9375rem; + font-weight: 600; + transition: all 200ms ease; + cursor: pointer; + position: relative; + margin-bottom: -1px; + } + + .payment-tab:hover { + color: hsl(var(--foreground)); + background-color: hsl(var(--muted) / 0.5); + } + + .payment-tab.active { + color: hsl(var(--foreground)); + border-bottom-color: hsl(var(--foreground)); + background-color: transparent; + } + + /* Dark mode tab styling */ + @media (prefers-color-scheme: dark) { + .payment-tab { + color: var(--text-muted); + } + + .payment-tab:hover { + color: var(--text-secondary); + background-color: rgba(255, 255, 255, 0.05); + } + + .payment-tab.active { + color: var(--text-primary); + border-bottom-color: var(--text-primary); + } + } + + /* Tab content */ + .tab-content { + display: none; + animation: fade-in 0.2s ease-out; + } + + .tab-content.active { + display: block; + } + + @keyframes fade-in { + from { + opacity: 0; + transform: translateY(4px); + } + to { + opacity: 1; + transform: translateY(0); + } } @media (max-width: 480px) { @@ -1893,27 +2557,33 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar } .transaction-details .detail-label { - font-weight: 500; - color: hsl(var(--muted-foreground)); - font-size: 0.875rem; + font-weight: 400; + color: var(--text-muted); + font-size: 0.75rem; min-width: 180px; flex-shrink: 0; + letter-spacing: 0.05em; + text-transform: uppercase; } .transaction-details .detail-value { - color: hsl(var(--foreground)); + color: var(--text-tertiary); font-family: 'SF Mono', 'Monaco', 'Inconsolata', 'Roboto Mono', 'Courier New', monospace; - font-size: 0.875rem; + font-size: 0.8125rem; + font-weight: 300; word-break: break-all; flex: 1; min-width: 0; + letter-spacing: -0.02em; + line-height: 1.7; } .transaction-details .detail-value-amount { - color: hsl(var(--foreground)); + color: var(--text-secondary); font-family: 'SF Mono', 'Monaco', 'Inconsolata', 'Roboto Mono', 'Courier New', monospace; font-size: 1rem; font-weight: 600; + letter-spacing: 0; flex: 1; min-width: 0; } @@ -2056,6 +2726,7 @@ pub fn layout_with_status(title: &str, content: Markup, is_running: bool) -> Mar } + } } } diff --git a/crates/cdk-ldk-node/src/web/templates/payments.rs b/crates/cdk-ldk-node/src/web/templates/payments.rs index 479d07643..50c518c4a 100644 --- a/crates/cdk-ldk-node/src/web/templates/payments.rs +++ b/crates/cdk-ldk-node/src/web/templates/payments.rs @@ -18,6 +18,7 @@ pub fn payment_list_item( "Succeeded" => "status-active", "Failed" => "status-inactive", "Pending" => "status-pending", + "Unpaid" => "status-pending", // Use pending styling for unpaid _ => "status-badge", }; From 33c206a31028f9dc044fb705594deefe9c4786fa Mon Sep 17 00:00:00 2001 From: tsk Date: Wed, 22 Oct 2025 08:30:33 -0500 Subject: [PATCH 226/321] Swap saga (#1183) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit # 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 --- crates/cdk-common/src/database/mint/mod.rs | 45 +- .../cdk-common/src/database/mint/test/mint.rs | 12 +- .../cdk-common/src/database/mint/test/mod.rs | 4 +- .../src/database/mint/test/proofs.rs | 33 +- crates/cdk-common/src/error.rs | 5 +- crates/cdk-common/src/mint.rs | 204 +- crates/cdk-mintd/src/lib.rs | 5 - crates/cdk-sql-common/Cargo.toml | 1 + .../20251010144317_add_saga_support.sql | 24 + .../20251010144317_add_saga_support.sql | 24 + crates/cdk-sql-common/src/mint/mod.rs | 205 +- crates/cdk-sqlite/src/mint/memory.rs | 8 +- crates/cdk/Cargo.toml | 2 + crates/cdk/src/lib.rs | 3 + crates/cdk/src/mint/blinded_message_writer.rs | 152 - crates/cdk/src/mint/issue/mod.rs | 6 +- crates/cdk/src/mint/melt.rs | 8 +- crates/cdk/src/mint/mod.rs | 17 +- crates/cdk/src/mint/proof_writer.rs | 8 +- crates/cdk/src/mint/start_up_check.rs | 66 + crates/cdk/src/mint/swap.rs | 173 - crates/cdk/src/mint/swap/mod.rs | 84 + .../src/mint/swap/swap_saga/compensation.rs | 61 + crates/cdk/src/mint/swap/swap_saga/mod.rs | 514 +++ crates/cdk/src/mint/swap/swap_saga/state.rs | 26 + crates/cdk/src/mint/swap/swap_saga/tests.rs | 2993 +++++++++++++++++ crates/cdk/src/test_helpers/mint.rs | 218 ++ crates/cdk/src/test_helpers/mod.rs | 10 + 28 files changed, 4550 insertions(+), 361 deletions(-) create mode 100644 crates/cdk-sql-common/src/mint/migrations/postgres/20251010144317_add_saga_support.sql create mode 100644 crates/cdk-sql-common/src/mint/migrations/sqlite/20251010144317_add_saga_support.sql delete mode 100644 crates/cdk/src/mint/blinded_message_writer.rs delete mode 100644 crates/cdk/src/mint/swap.rs create mode 100644 crates/cdk/src/mint/swap/mod.rs create mode 100644 crates/cdk/src/mint/swap/swap_saga/compensation.rs create mode 100644 crates/cdk/src/mint/swap/swap_saga/mod.rs create mode 100644 crates/cdk/src/mint/swap/swap_saga/state.rs create mode 100644 crates/cdk/src/mint/swap/swap_saga/tests.rs create mode 100644 crates/cdk/src/test_helpers/mint.rs create mode 100644 crates/cdk/src/test_helpers/mod.rs diff --git a/crates/cdk-common/src/database/mint/mod.rs b/crates/cdk-common/src/database/mint/mod.rs index 5ece68c47..501ed4496 100644 --- a/crates/cdk-common/src/database/mint/mod.rs +++ b/crates/cdk-common/src/database/mint/mod.rs @@ -7,7 +7,7 @@ use cashu::quote_id::QuoteId; use cashu::Amount; use super::Error; -use crate::mint::{self, MintKeySetInfo, MintQuote as MintMintQuote}; +use crate::mint::{self, MintKeySetInfo, MintQuote as MintMintQuote, Operation}; use crate::nuts::{ BlindSignature, BlindedMessage, CurrencyUnit, Id, MeltQuoteState, Proof, Proofs, PublicKey, State, @@ -145,6 +145,7 @@ pub trait QuotesTransaction<'a> { &mut self, quote_id: Option<&QuoteId>, blinded_messages: &[BlindedMessage], + operation: &Operation, ) -> Result<(), Self::Err>; /// Delete blinded_messages by their blinded secrets @@ -265,6 +266,7 @@ pub trait ProofsTransaction<'a> { &mut self, proof: Proofs, quote_id: Option, + operation: &Operation, ) -> Result<(), Self::Err>; /// Updates the proofs to a given states and return the previous states async fn update_proofs_states( @@ -353,6 +355,45 @@ pub trait SignaturesDatabase { ) -> Result, Self::Err>; } +#[async_trait] +/// Saga Transaction trait +pub trait SagaTransaction<'a> { + /// Saga Database Error + type Err: Into + From; + + /// Get saga by operation_id + async fn get_saga( + &mut self, + operation_id: &uuid::Uuid, + ) -> Result, Self::Err>; + + /// Add saga + async fn add_saga(&mut self, saga: &mint::Saga) -> Result<(), Self::Err>; + + /// Update saga state (only updates state and updated_at fields) + async fn update_saga( + &mut self, + operation_id: &uuid::Uuid, + new_state: mint::SagaStateEnum, + ) -> Result<(), Self::Err>; + + /// Delete saga + async fn delete_saga(&mut self, operation_id: &uuid::Uuid) -> Result<(), Self::Err>; +} + +#[async_trait] +/// Saga Database trait +pub trait SagaDatabase { + /// Saga Database Error + type Err: Into + From; + + /// Get all incomplete sagas for a given operation kind + async fn get_incomplete_sagas( + &self, + operation_kind: mint::OperationKind, + ) -> Result, Self::Err>; +} + #[async_trait] /// Commit and Rollback pub trait DbTransactionFinalizer { @@ -409,6 +450,7 @@ pub trait Transaction<'a, Error>: + SignaturesTransaction<'a, Err = Error> + ProofsTransaction<'a, Err = Error> + KVStoreTransaction<'a, Error> + + SagaTransaction<'a, Err = Error> { } @@ -453,6 +495,7 @@ pub trait Database: + QuotesDatabase + ProofsDatabase + SignaturesDatabase + + SagaDatabase { /// Beings a transaction async fn begin_transaction<'a>( diff --git a/crates/cdk-common/src/database/mint/test/mint.rs b/crates/cdk-common/src/database/mint/test/mint.rs index 531dc9245..b04713414 100644 --- a/crates/cdk-common/src/database/mint/test/mint.rs +++ b/crates/cdk-common/src/database/mint/test/mint.rs @@ -8,7 +8,7 @@ use cashu::{Amount, Id, SecretKey}; use crate::database::mint::test::unique_string; use crate::database::mint::{Database, Error, KeysDatabase}; use crate::database::MintSignaturesDatabase; -use crate::mint::{MeltPaymentRequest, MeltQuote, MintQuote}; +use crate::mint::{MeltPaymentRequest, MeltQuote, MintQuote, Operation}; use crate::payment::PaymentIdentifier; /// Add a mint quote @@ -435,7 +435,7 @@ where tx.add_melt_request("e.id, inputs_amount, inputs_fee) .await .unwrap(); - tx.add_blinded_messages(Some("e.id), &blinded_messages) + tx.add_blinded_messages(Some("e.id), &blinded_messages, &Operation::new_melt()) .await .unwrap(); tx.commit().await.unwrap(); @@ -497,7 +497,7 @@ where .await .unwrap(); let result = tx - .add_blinded_messages(Some("e2.id), &blinded_messages) + .add_blinded_messages(Some("e2.id), &blinded_messages, &Operation::new_melt()) .await; assert!(result.is_err() && matches!(result.unwrap_err(), Error::Duplicate)); tx.rollback().await.unwrap(); // Rollback to avoid partial state @@ -530,7 +530,7 @@ where .await .unwrap(); assert!(tx - .add_blinded_messages(Some("e.id), &blinded_messages) + .add_blinded_messages(Some("e.id), &blinded_messages, &Operation::new_melt()) .await .is_ok()); tx.commit().await.unwrap(); @@ -543,7 +543,7 @@ where .await .unwrap(); let result = tx - .add_blinded_messages(Some("e.id), &blinded_messages) + .add_blinded_messages(Some("e.id), &blinded_messages, &Operation::new_melt()) .await; // Expect a database error due to unique violation assert!(result.is_err()); // Specific error might be DB-specific, e.g., SqliteError or PostgresError @@ -576,7 +576,7 @@ where tx1.add_melt_request("e.id, inputs_amount, inputs_fee) .await .unwrap(); - tx1.add_blinded_messages(Some("e.id), &blinded_messages) + tx1.add_blinded_messages(Some("e.id), &blinded_messages, &Operation::new_melt()) .await .unwrap(); tx1.commit().await.unwrap(); diff --git a/crates/cdk-common/src/database/mint/test/mod.rs b/crates/cdk-common/src/database/mint/test/mod.rs index 1bdfdf3c2..c212a54ec 100644 --- a/crates/cdk-common/src/database/mint/test/mod.rs +++ b/crates/cdk-common/src/database/mint/test/mod.rs @@ -74,7 +74,9 @@ where // Add proofs to database let mut tx = Database::begin_transaction(&db).await.unwrap(); - tx.add_proofs(proofs.clone(), None).await.unwrap(); + tx.add_proofs(proofs.clone(), None, &Operation::new_swap()) + .await + .unwrap(); // Mark one proof as `pending` assert!(tx diff --git a/crates/cdk-common/src/database/mint/test/proofs.rs b/crates/cdk-common/src/database/mint/test/proofs.rs index ef29ca407..43154eb75 100644 --- a/crates/cdk-common/src/database/mint/test/proofs.rs +++ b/crates/cdk-common/src/database/mint/test/proofs.rs @@ -7,6 +7,7 @@ use cashu::{Amount, Id, SecretKey}; use crate::database::mint::test::setup_keyset; use crate::database::mint::{Database, Error, KeysDatabase, Proof, QuoteId}; +use crate::mint::Operation; /// Test get proofs by keyset id pub async fn get_proofs_by_keyset_id(db: DB) @@ -36,7 +37,9 @@ where // Add proofs to database let mut tx = Database::begin_transaction(&db).await.unwrap(); - tx.add_proofs(proofs, Some(quote_id)).await.unwrap(); + tx.add_proofs(proofs, Some(quote_id), &Operation::new_swap()) + .await + .unwrap(); assert!(tx.commit().await.is_ok()); let (proofs, states) = db.get_proofs_by_keyset_id(&keyset_id).await.unwrap(); @@ -88,9 +91,13 @@ where // Add proofs to database let mut tx = Database::begin_transaction(&db).await.unwrap(); - tx.add_proofs(proofs.clone(), Some(quote_id.clone())) - .await - .unwrap(); + tx.add_proofs( + proofs.clone(), + Some(quote_id.clone()), + &Operation::new_swap(), + ) + .await + .unwrap(); assert!(tx.commit().await.is_ok()); let proofs_from_db = db.get_proofs_by_ys(&[proofs[0].c, proofs[1].c]).await; @@ -132,13 +139,23 @@ where // Add proofs to database let mut tx = Database::begin_transaction(&db).await.unwrap(); - tx.add_proofs(proofs.clone(), Some(quote_id.clone())) - .await - .unwrap(); + tx.add_proofs( + proofs.clone(), + Some(quote_id.clone()), + &Operation::new_swap(), + ) + .await + .unwrap(); assert!(tx.commit().await.is_ok()); let mut tx = Database::begin_transaction(&db).await.unwrap(); - let result = tx.add_proofs(proofs.clone(), Some(quote_id.clone())).await; + let result = tx + .add_proofs( + proofs.clone(), + Some(quote_id.clone()), + &Operation::new_swap(), + ) + .await; assert!( matches!(result.unwrap_err(), Error::Duplicate), diff --git a/crates/cdk-common/src/error.rs b/crates/cdk-common/src/error.rs index dd29a1594..1a2ffbd0c 100644 --- a/crates/cdk-common/src/error.rs +++ b/crates/cdk-common/src/error.rs @@ -335,7 +335,10 @@ pub enum Error { /// Http transport error #[error("Http transport error {0:?}: {1}")] HttpError(Option, String), - #[cfg(feature = "wallet")] + /// Parse invoice error + #[cfg(feature = "mint")] + #[error(transparent)] + Uuid(#[from] uuid::Error), // Crate error conversions /// Cashu Url Error #[error(transparent)] diff --git a/crates/cdk-common/src/mint.rs b/crates/cdk-common/src/mint.rs index f75cf1205..0249bffdc 100644 --- a/crates/cdk-common/src/mint.rs +++ b/crates/cdk-common/src/mint.rs @@ -1,5 +1,8 @@ //! Mint types +use std::fmt; +use std::str::FromStr; + use bitcoin::bip32::DerivationPath; use cashu::quote_id::QuoteId; use cashu::util::unix_time; @@ -14,7 +17,206 @@ use uuid::Uuid; use crate::nuts::{MeltQuoteState, MintQuoteState}; use crate::payment::PaymentIdentifier; -use crate::{Amount, CurrencyUnit, Id, KeySetInfo, PublicKey}; +use crate::{Amount, CurrencyUnit, Error, Id, KeySetInfo, PublicKey}; + +/// Operation kind for saga persistence +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "lowercase")] +pub enum OperationKind { + /// Swap operation + Swap, + /// Mint operation + Mint, + /// Melt operation + Melt, +} + +impl fmt::Display for OperationKind { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + OperationKind::Swap => write!(f, "swap"), + OperationKind::Mint => write!(f, "mint"), + OperationKind::Melt => write!(f, "melt"), + } + } +} + +impl FromStr for OperationKind { + type Err = Error; + fn from_str(value: &str) -> Result { + let value = value.to_lowercase(); + match value.as_str() { + "swap" => Ok(OperationKind::Swap), + "mint" => Ok(OperationKind::Mint), + "melt" => Ok(OperationKind::Melt), + _ => Err(Error::Custom(format!("Invalid operation kind: {}", value))), + } + } +} + +/// States specific to swap saga +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum SwapSagaState { + /// Swap setup complete (proofs added, blinded messages added) + SetupComplete, + /// Outputs signed (signatures generated but not persisted) + Signed, +} + +impl fmt::Display for SwapSagaState { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + SwapSagaState::SetupComplete => write!(f, "setup_complete"), + SwapSagaState::Signed => write!(f, "signed"), + } + } +} + +impl FromStr for SwapSagaState { + type Err = Error; + fn from_str(value: &str) -> Result { + let value = value.to_lowercase(); + match value.as_str() { + "setup_complete" => Ok(SwapSagaState::SetupComplete), + "signed" => Ok(SwapSagaState::Signed), + _ => Err(Error::Custom(format!("Invalid swap saga state: {}", value))), + } + } +} + +/// Saga state for different operation types +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(tag = "type", rename_all = "snake_case")] +pub enum SagaStateEnum { + /// Swap saga states + Swap(SwapSagaState), + // Future: Mint saga states + // Mint(MintSagaState), + // Future: Melt saga states + // Melt(MeltSagaState), +} + +impl SagaStateEnum { + /// Create from string given operation kind + pub fn new(operation_kind: OperationKind, s: &str) -> Result { + match operation_kind { + OperationKind::Swap => Ok(SagaStateEnum::Swap(SwapSagaState::from_str(s)?)), + OperationKind::Mint => Err(Error::Custom("Mint saga not implemented yet".to_string())), + OperationKind::Melt => Err(Error::Custom("Melt saga not implemented yet".to_string())), + } + } + + /// Get string representation of the state + pub fn state(&self) -> &str { + match self { + SagaStateEnum::Swap(state) => match state { + SwapSagaState::SetupComplete => "setup_complete", + SwapSagaState::Signed => "signed", + }, + } + } +} + +/// Persisted saga for recovery +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct Saga { + /// Operation ID (correlation key) + pub operation_id: Uuid, + /// Operation kind (swap, mint, melt) + pub operation_kind: OperationKind, + /// Current saga state (operation-specific) + pub state: SagaStateEnum, + /// Blinded secrets (B values) from output blinded messages + pub blinded_secrets: Vec, + /// Y values (public keys) from input proofs + pub input_ys: Vec, + /// Unix timestamp when saga was created + pub created_at: u64, + /// Unix timestamp when saga was last updated + pub updated_at: u64, +} + +impl Saga { + /// Create new swap saga + pub fn new_swap( + operation_id: Uuid, + state: SwapSagaState, + blinded_secrets: Vec, + input_ys: Vec, + ) -> Self { + let now = unix_time(); + Self { + operation_id, + operation_kind: OperationKind::Swap, + state: SagaStateEnum::Swap(state), + blinded_secrets, + input_ys, + created_at: now, + updated_at: now, + } + } + + /// Update swap saga state + pub fn update_swap_state(&mut self, new_state: SwapSagaState) { + self.state = SagaStateEnum::Swap(new_state); + self.updated_at = unix_time(); + } +} + +/// Operation +pub enum Operation { + /// Mint + Mint(Uuid), + /// Melt + Melt(Uuid), + /// Swap + Swap(Uuid), +} + +impl Operation { + /// Mint + pub fn new_mint() -> Self { + Self::Mint(Uuid::new_v4()) + } + /// Melt + pub fn new_melt() -> Self { + Self::Melt(Uuid::new_v4()) + } + /// Swap + pub fn new_swap() -> Self { + Self::Swap(Uuid::new_v4()) + } + + /// Operation id + pub fn id(&self) -> &Uuid { + match self { + Operation::Mint(id) => id, + Operation::Melt(id) => id, + Operation::Swap(id) => id, + } + } + + /// Operation kind + pub fn kind(&self) -> &str { + match self { + Operation::Mint(_) => "mint", + Operation::Melt(_) => "melt", + Operation::Swap(_) => "swap", + } + } + + /// From kind and i + pub fn from_kind_and_id(kind: &str, id: &str) -> Result { + let uuid = Uuid::parse_str(id)?; + match kind { + "mint" => Ok(Self::Mint(uuid)), + "melt" => Ok(Self::Melt(uuid)), + "swap" => Ok(Self::Swap(uuid)), + _ => Err(Error::Custom(format!("Invalid operation kind: {}", kind))), + } + } +} /// Mint Quote Info #[derive(Debug, Clone, Hash, PartialEq, Eq, Serialize, Deserialize)] diff --git a/crates/cdk-mintd/src/lib.rs b/crates/cdk-mintd/src/lib.rs index 34ed48339..4366a3874 100644 --- a/crates/cdk-mintd/src/lib.rs +++ b/crates/cdk-mintd/src/lib.rs @@ -1183,11 +1183,6 @@ pub async fn run_mintd_with_shutdown( let mint = Arc::new(mint); - // Checks the status of all pending melt quotes - // Pending melt quotes where the payment has gone through inputs are burnt - // Pending melt quotes where the payment has **failed** inputs are reset to unspent - mint.check_pending_melt_quotes().await?; - start_services_with_shutdown( mint.clone(), settings, diff --git a/crates/cdk-sql-common/Cargo.toml b/crates/cdk-sql-common/Cargo.toml index c5b512cc1..0e6be4f2c 100644 --- a/crates/cdk-sql-common/Cargo.toml +++ b/crates/cdk-sql-common/Cargo.toml @@ -29,3 +29,4 @@ serde.workspace = true serde_json.workspace = true lightning-invoice.workspace = true once_cell.workspace = true +uuid.workspace = true diff --git a/crates/cdk-sql-common/src/mint/migrations/postgres/20251010144317_add_saga_support.sql b/crates/cdk-sql-common/src/mint/migrations/postgres/20251010144317_add_saga_support.sql new file mode 100644 index 000000000..8aba3ac30 --- /dev/null +++ b/crates/cdk-sql-common/src/mint/migrations/postgres/20251010144317_add_saga_support.sql @@ -0,0 +1,24 @@ +-- Add operation and operation_id columns to proof table +ALTER TABLE proof ADD COLUMN operation_kind TEXT; +ALTER TABLE proof ADD COLUMN operation_id TEXT; + +-- Add operation and operation_id columns to blind_signature table +ALTER TABLE blind_signature ADD COLUMN operation_kind TEXT; +ALTER TABLE blind_signature ADD COLUMN operation_id TEXT; + +CREATE INDEX idx_proof_state_operation ON proof(state, operation_kind); +CREATE INDEX idx_proof_operation_id ON proof(operation_kind, operation_id); +CREATE INDEX idx_blind_sig_operation_id ON blind_signature(operation_kind, operation_id); + +-- Add saga_state table for persisting saga state +CREATE TABLE IF NOT EXISTS saga_state ( + operation_id TEXT PRIMARY KEY, + operation_kind TEXT NOT NULL, + state TEXT NOT NULL, + blinded_secrets TEXT NOT NULL, + input_ys TEXT NOT NULL, + created_at BIGINT NOT NULL, + updated_at BIGINT NOT NULL +); + +CREATE INDEX IF NOT EXISTS idx_saga_state_operation_kind ON saga_state(operation_kind); diff --git a/crates/cdk-sql-common/src/mint/migrations/sqlite/20251010144317_add_saga_support.sql b/crates/cdk-sql-common/src/mint/migrations/sqlite/20251010144317_add_saga_support.sql new file mode 100644 index 000000000..e9c7217c9 --- /dev/null +++ b/crates/cdk-sql-common/src/mint/migrations/sqlite/20251010144317_add_saga_support.sql @@ -0,0 +1,24 @@ +-- Add operation and operation_id columns to proof table +ALTER TABLE proof ADD COLUMN operation_kind TEXT; +ALTER TABLE proof ADD COLUMN operation_id TEXT; + +-- Add operation and operation_id columns to blind_signature table +ALTER TABLE blind_signature ADD COLUMN operation_kind TEXT; +ALTER TABLE blind_signature ADD COLUMN operation_id TEXT; + +CREATE INDEX idx_proof_state_operation ON proof(state, operation_kind); +CREATE INDEX idx_proof_operation_id ON proof(operation_kind, operation_id); +CREATE INDEX idx_blind_sig_operation_id ON blind_signature(operation_kind, operation_id); + +-- Add saga_state table for persisting saga state +CREATE TABLE IF NOT EXISTS saga_state ( + operation_id TEXT PRIMARY KEY, + operation_kind TEXT NOT NULL, + state TEXT NOT NULL, + blinded_secrets TEXT NOT NULL, + input_ys TEXT NOT NULL, + created_at INTEGER NOT NULL, + updated_at INTEGER NOT NULL +); + +CREATE INDEX IF NOT EXISTS idx_saga_state_operation_kind ON saga_state(operation_kind); diff --git a/crates/cdk-sql-common/src/mint/mod.rs b/crates/cdk-sql-common/src/mint/mod.rs index 8baf21709..270436203 100644 --- a/crates/cdk-sql-common/src/mint/mod.rs +++ b/crates/cdk-sql-common/src/mint/mod.rs @@ -15,7 +15,7 @@ use std::sync::Arc; use async_trait::async_trait; use bitcoin::bip32::DerivationPath; -use cdk_common::database::mint::validate_kvstore_params; +use cdk_common::database::mint::{validate_kvstore_params, SagaDatabase, SagaTransaction}; use cdk_common::database::{ self, ConversionError, Error, MintDatabase, MintDbWriterFinalizer, MintKeyDatabaseTransaction, MintKeysDatabase, MintProofsDatabase, MintQuotesDatabase, MintQuotesTransaction, @@ -23,6 +23,7 @@ use cdk_common::database::{ }; use cdk_common::mint::{ self, IncomingPayment, Issuance, MeltPaymentRequest, MeltQuote, MintKeySetInfo, MintQuote, + Operation, }; use cdk_common::nut00::ProofsMethods; use cdk_common::payment::PaymentIdentifier; @@ -138,6 +139,7 @@ where &mut self, proofs: Proofs, quote_id: Option, + operation: &Operation, ) -> Result<(), Self::Err> { let current_time = unix_time(); @@ -165,9 +167,9 @@ where query( r#" INSERT INTO proof - (y, amount, keyset_id, secret, c, witness, state, quote_id, created_time) + (y, amount, keyset_id, secret, c, witness, state, quote_id, created_time, operation_kind, operation_id) VALUES - (:y, :amount, :keyset_id, :secret, :c, :witness, :state, :quote_id, :created_time) + (:y, :amount, :keyset_id, :secret, :c, :witness, :state, :quote_id, :created_time, :operation_kind, :operation_id) "#, )? .bind("y", proof.y()?.to_bytes().to_vec()) @@ -182,6 +184,8 @@ where .bind("state", "UNSPENT".to_string()) .bind("quote_id", quote_id.clone().map(|q| q.to_string())) .bind("created_time", current_time as i64) + .bind("operation_kind", operation.kind()) + .bind("operation_id", operation.id().to_string()) .execute(&self.inner) .await?; } @@ -574,6 +578,7 @@ where &mut self, quote_id: Option<&QuoteId>, blinded_messages: &[BlindedMessage], + operation: &Operation, ) -> Result<(), Self::Err> { let current_time = unix_time(); @@ -583,9 +588,9 @@ where match query( r#" INSERT INTO blind_signature - (blinded_message, amount, keyset_id, c, quote_id, created_time) + (blinded_message, amount, keyset_id, c, quote_id, created_time, operation_kind, operation_id) VALUES - (:blinded_message, :amount, :keyset_id, NULL, :quote_id, :created_time) + (:blinded_message, :amount, :keyset_id, NULL, :quote_id, :created_time, :operation_kind, :operation_id) "#, )? .bind( @@ -596,6 +601,8 @@ where .bind("keyset_id", message.keyset_id.to_string()) .bind("quote_id", quote_id.map(|q| q.to_string())) .bind("created_time", current_time as i64) + .bind("operation_kind", operation.kind()) + .bind("operation_id", operation.id().to_string()) .execute(&self.inner) .await { @@ -2120,6 +2127,147 @@ where } } +#[async_trait] +impl SagaTransaction<'_> for SQLTransaction +where + RM: DatabasePool + 'static, +{ + type Err = Error; + + async fn get_saga( + &mut self, + operation_id: &uuid::Uuid, + ) -> Result, Self::Err> { + Ok(query( + r#" + SELECT + operation_id, + operation_kind, + state, + blinded_secrets, + input_ys, + created_at, + updated_at + FROM + saga_state + WHERE + operation_id = :operation_id + FOR UPDATE + "#, + )? + .bind("operation_id", operation_id.to_string()) + .fetch_one(&self.inner) + .await? + .map(sql_row_to_saga) + .transpose()?) + } + + async fn add_saga(&mut self, saga: &mint::Saga) -> Result<(), Self::Err> { + let current_time = unix_time(); + + let blinded_secrets_json = serde_json::to_string(&saga.blinded_secrets) + .map_err(|e| Error::Internal(format!("Failed to serialize blinded_secrets: {}", e)))?; + + let input_ys_json = serde_json::to_string(&saga.input_ys) + .map_err(|e| Error::Internal(format!("Failed to serialize input_ys: {}", e)))?; + + query( + r#" + INSERT INTO saga_state + (operation_id, operation_kind, state, blinded_secrets, input_ys, created_at, updated_at) + VALUES + (:operation_id, :operation_kind, :state, :blinded_secrets, :input_ys, :created_at, :updated_at) + "#, + )? + .bind("operation_id", saga.operation_id.to_string()) + .bind("operation_kind", saga.operation_kind.to_string()) + .bind("state", saga.state.state()) + .bind("blinded_secrets", blinded_secrets_json) + .bind("input_ys", input_ys_json) + .bind("created_at", saga.created_at as i64) + .bind("updated_at", current_time as i64) + .execute(&self.inner) + .await?; + + Ok(()) + } + + async fn update_saga( + &mut self, + operation_id: &uuid::Uuid, + new_state: mint::SagaStateEnum, + ) -> Result<(), Self::Err> { + let current_time = unix_time(); + + query( + r#" + UPDATE saga_state + SET state = :state, updated_at = :updated_at + WHERE operation_id = :operation_id + "#, + )? + .bind("state", new_state.state()) + .bind("updated_at", current_time as i64) + .bind("operation_id", operation_id.to_string()) + .execute(&self.inner) + .await?; + + Ok(()) + } + + async fn delete_saga(&mut self, operation_id: &uuid::Uuid) -> Result<(), Self::Err> { + query( + r#" + DELETE FROM saga_state + WHERE operation_id = :operation_id + "#, + )? + .bind("operation_id", operation_id.to_string()) + .execute(&self.inner) + .await?; + + Ok(()) + } +} + +#[async_trait] +impl SagaDatabase for SQLMintDatabase +where + RM: DatabasePool + 'static, +{ + type Err = Error; + + async fn get_incomplete_sagas( + &self, + operation_kind: mint::OperationKind, + ) -> Result, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; + Ok(query( + r#" + SELECT + operation_id, + operation_kind, + state, + blinded_secrets, + input_ys, + created_at, + updated_at + FROM + saga_state + WHERE + operation_kind = :operation_kind + ORDER BY created_at ASC + "#, + )? + .bind("operation_kind", operation_kind.to_string()) + .fetch_all(&*conn) + .await? + .into_iter() + .map(sql_row_to_saga) + .collect::, _>>()?) + } +} + #[async_trait] impl MintDatabase for SQLMintDatabase where @@ -2383,6 +2531,53 @@ fn sql_row_to_blind_signature(row: Vec) -> Result }) } +fn sql_row_to_saga(row: Vec) -> Result { + unpack_into!( + let ( + operation_id, + operation_kind, + state, + blinded_secrets, + input_ys, + created_at, + updated_at + ) = row + ); + + let operation_id_str = column_as_string!(&operation_id); + let operation_id = uuid::Uuid::parse_str(&operation_id_str) + .map_err(|e| Error::Internal(format!("Invalid operation_id UUID: {}", e)))?; + + let operation_kind_str = column_as_string!(&operation_kind); + let operation_kind = mint::OperationKind::from_str(&operation_kind_str) + .map_err(|e| Error::Internal(format!("Invalid operation kind: {}", e)))?; + + let state_str = column_as_string!(&state); + let state = mint::SagaStateEnum::new(operation_kind, &state_str) + .map_err(|e| Error::Internal(format!("Invalid saga state: {}", e)))?; + + let blinded_secrets_str = column_as_string!(&blinded_secrets); + let blinded_secrets: Vec = serde_json::from_str(&blinded_secrets_str) + .map_err(|e| Error::Internal(format!("Failed to deserialize blinded_secrets: {}", e)))?; + + let input_ys_str = column_as_string!(&input_ys); + let input_ys: Vec = serde_json::from_str(&input_ys_str) + .map_err(|e| Error::Internal(format!("Failed to deserialize input_ys: {}", e)))?; + + let created_at: u64 = column_as_number!(created_at); + let updated_at: u64 = column_as_number!(updated_at); + + Ok(mint::Saga { + operation_id, + operation_kind, + state, + blinded_secrets, + input_ys, + created_at, + updated_at, + }) +} + #[cfg(test)] mod test { use super::*; diff --git a/crates/cdk-sqlite/src/mint/memory.rs b/crates/cdk-sqlite/src/mint/memory.rs index e99f6d1bf..b4c341c6d 100644 --- a/crates/cdk-sqlite/src/mint/memory.rs +++ b/crates/cdk-sqlite/src/mint/memory.rs @@ -2,7 +2,7 @@ use std::collections::HashMap; use cdk_common::database::{self, MintDatabase, MintKeysDatabase}; -use cdk_common::mint::{self, MintKeySetInfo, MintQuote}; +use cdk_common::mint::{self, MintKeySetInfo, MintQuote, Operation}; use cdk_common::nuts::{CurrencyUnit, Id, Proofs}; use cdk_common::MintInfo; @@ -56,8 +56,10 @@ pub async fn new_with_state( tx.add_melt_quote(quote).await?; } - tx.add_proofs(pending_proofs, None).await?; - tx.add_proofs(spent_proofs, None).await?; + tx.add_proofs(pending_proofs, None, &Operation::new_swap()) + .await?; + tx.add_proofs(spent_proofs, None, &Operation::new_swap()) + .await?; let mint_info_bytes = serde_json::to_vec(&mint_info)?; tx.kv_write( CDK_MINT_PRIMARY_NAMESPACE, diff --git a/crates/cdk/Cargo.toml b/crates/cdk/Cargo.toml index bfc2f1396..6f7c070c3 100644 --- a/crates/cdk/Cargo.toml +++ b/crates/cdk/Cargo.toml @@ -141,12 +141,14 @@ required-features = ["wallet"] [dev-dependencies] rand.workspace = true cdk-sqlite.workspace = true +cdk-fake-wallet.workspace = true bip39.workspace = true tracing-subscriber.workspace = true criterion.workspace = true reqwest = { workspace = true } anyhow.workspace = true ureq = { version = "3.1.0", features = ["json"] } +tokio = { workspace = true, features = ["full"] } [[bench]] diff --git a/crates/cdk/src/lib.rs b/crates/cdk/src/lib.rs index 58653d78c..4f5e55630 100644 --- a/crates/cdk/src/lib.rs +++ b/crates/cdk/src/lib.rs @@ -49,6 +49,9 @@ pub use oidc_client::OidcClient; pub mod event; pub mod fees; +#[cfg(test)] +pub mod test_helpers; + #[doc(hidden)] pub use bitcoin::secp256k1; #[cfg(feature = "mint")] diff --git a/crates/cdk/src/mint/blinded_message_writer.rs b/crates/cdk/src/mint/blinded_message_writer.rs deleted file mode 100644 index c7f81751c..000000000 --- a/crates/cdk/src/mint/blinded_message_writer.rs +++ /dev/null @@ -1,152 +0,0 @@ -//! Blinded message writer -use std::collections::HashSet; - -use cdk_common::database::{self, DynMintDatabase, MintTransaction}; -use cdk_common::nuts::BlindedMessage; -use cdk_common::{Error, PublicKey, QuoteId}; - -type Tx<'a, 'b> = Box + Send + Sync + 'b>; - -/// Blinded message writer -/// -/// This is a blinded message writer that emulates a database transaction but without holding the -/// transaction alive while waiting for external events to be fully committed to the database; -/// instead, it maintains a `pending` state. -/// -/// This struct allows for premature exit on error, enabling it to remove blinded messages that -/// were added during the operation. -/// -/// This struct is not fully ACID. If the process exits due to a panic, and the `Drop` function -/// cannot be run, the cleanup process should reset the state. -pub struct BlindedMessageWriter { - db: Option, - added_blinded_secrets: Option>, -} - -impl BlindedMessageWriter { - /// Creates a new BlindedMessageWriter on top of the database - pub fn new(db: DynMintDatabase) -> Self { - Self { - db: Some(db), - added_blinded_secrets: Some(Default::default()), - } - } - - /// The changes are permanent, consume the struct removing the database, so the Drop does - /// nothing - pub fn commit(mut self) { - self.db.take(); - self.added_blinded_secrets.take(); - } - - /// Add blinded messages - pub async fn add_blinded_messages( - &mut self, - tx: &mut Tx<'_, '_>, - quote_id: Option, - blinded_messages: &[BlindedMessage], - ) -> Result, Error> { - let added_secrets = if let Some(secrets) = self.added_blinded_secrets.as_mut() { - secrets - } else { - return Err(Error::Internal); - }; - - if let Some(err) = tx - .add_blinded_messages(quote_id.as_ref(), blinded_messages) - .await - .err() - { - return match err { - cdk_common::database::Error::Duplicate => Err(Error::DuplicateOutputs), - err => Err(Error::Database(err)), - }; - } - - let blinded_secrets: Vec = blinded_messages - .iter() - .map(|bm| bm.blinded_secret) - .collect(); - - for blinded_secret in &blinded_secrets { - added_secrets.insert(*blinded_secret); - } - - Ok(blinded_secrets) - } - - /// Rollback all changes in this BlindedMessageWriter consuming it. - pub async fn rollback(mut self) -> Result<(), Error> { - let db = if let Some(db) = self.db.take() { - db - } else { - return Ok(()); - }; - let mut tx = db.begin_transaction().await?; - let blinded_secrets: Vec = - if let Some(secrets) = self.added_blinded_secrets.take() { - secrets.into_iter().collect() - } else { - return Ok(()); - }; - - if !blinded_secrets.is_empty() { - tracing::info!("Rollback {} blinded messages", blinded_secrets.len(),); - - remove_blinded_messages(&mut tx, &blinded_secrets).await?; - } - - tx.commit().await?; - - Ok(()) - } -} - -/// Removes blinded messages from the database -#[inline(always)] -async fn remove_blinded_messages( - tx: &mut Tx<'_, '_>, - blinded_secrets: &[PublicKey], -) -> Result<(), Error> { - tx.delete_blinded_messages(blinded_secrets) - .await - .map_err(Error::Database) -} - -#[inline(always)] -async fn rollback_blinded_messages( - db: DynMintDatabase, - blinded_secrets: Vec, -) -> Result<(), Error> { - let mut tx = db.begin_transaction().await?; - remove_blinded_messages(&mut tx, &blinded_secrets).await?; - tx.commit().await?; - - Ok(()) -} - -impl Drop for BlindedMessageWriter { - fn drop(&mut self) { - let db = if let Some(db) = self.db.take() { - db - } else { - tracing::debug!("Blinded message writer dropped after commit, no need to rollback."); - return; - }; - let blinded_secrets: Vec = - if let Some(secrets) = self.added_blinded_secrets.take() { - secrets.into_iter().collect() - } else { - return; - }; - - if !blinded_secrets.is_empty() { - tracing::debug!("Blinded message writer dropper with messages attempting to remove."); - tokio::spawn(async move { - if let Err(err) = rollback_blinded_messages(db, blinded_secrets).await { - tracing::error!("Failed to rollback blinded messages in Drop: {}", err); - } - }); - } - } -} diff --git a/crates/cdk/src/mint/issue/mod.rs b/crates/cdk/src/mint/issue/mod.rs index 419abd3c6..a916d5098 100644 --- a/crates/cdk/src/mint/issue/mod.rs +++ b/crates/cdk/src/mint/issue/mod.rs @@ -1,4 +1,4 @@ -use cdk_common::mint::MintQuote; +use cdk_common::mint::{MintQuote, Operation}; use cdk_common::payment::{ Bolt11IncomingPaymentOptions, Bolt11Settings, Bolt12IncomingPaymentOptions, IncomingPaymentOptions, WaitPaymentResponse, @@ -657,6 +657,10 @@ impl Mint { let unit = unit.ok_or(Error::UnsupportedUnit).unwrap(); ensure_cdk!(unit == mint_quote.unit, Error::UnsupportedUnit); + let operation = Operation::new_mint(); + + tx.add_blinded_messages(Some(&mint_request.quote), &mint_request.outputs, &operation).await?; + tx.add_blind_signatures( &mint_request .outputs diff --git a/crates/cdk/src/mint/melt.rs b/crates/cdk/src/mint/melt.rs index 166e554f3..2f3a8d4b3 100644 --- a/crates/cdk/src/mint/melt.rs +++ b/crates/cdk/src/mint/melt.rs @@ -5,7 +5,7 @@ use cdk_common::amount::amount_for_offer; use cdk_common::database::mint::MeltRequestInfo; use cdk_common::database::{self, MintTransaction}; use cdk_common::melt::MeltQuoteRequest; -use cdk_common::mint::MeltPaymentRequest; +use cdk_common::mint::{MeltPaymentRequest, Operation}; use cdk_common::nut05::MeltMethodOptions; use cdk_common::payment::{ Bolt11OutgoingPaymentOptions, Bolt12OutgoingPaymentOptions, DynMintPayment, @@ -506,6 +506,7 @@ impl Mint { tx: &mut Box + Send + Sync + '_>, input_verification: Verification, melt_request: &MeltRequest, + operation: &Operation, ) -> Result<(ProofWriter, MeltQuote), Error> { let Verification { amount: input_amount, @@ -520,6 +521,7 @@ impl Mint { tx, melt_request.inputs(), Some(melt_request.quote_id().to_owned()), + operation, ) .await?; @@ -613,10 +615,11 @@ impl Mint { let verification = self.verify_inputs(melt_request.inputs()).await?; + let melt_operation = Operation::new_melt(); let mut tx = self.localstore.begin_transaction().await?; let (proof_writer, quote) = match self - .verify_melt_request(&mut tx, verification, melt_request) + .verify_melt_request(&mut tx, verification, melt_request, &melt_operation) .await { Ok(result) => result, @@ -646,6 +649,7 @@ impl Mint { tx.add_blinded_messages( Some(melt_request.quote_id()), melt_request.outputs().as_ref().unwrap_or(&Vec::new()), + &melt_operation, ) .await?; diff --git a/crates/cdk/src/mint/mod.rs b/crates/cdk/src/mint/mod.rs index fbe7d6899..800408340 100644 --- a/crates/cdk/src/mint/mod.rs +++ b/crates/cdk/src/mint/mod.rs @@ -34,7 +34,6 @@ use crate::{cdk_database, Amount}; #[cfg(feature = "auth")] pub(crate) mod auth; -mod blinded_message_writer; mod builder; mod check_spendable; mod issue; @@ -239,6 +238,15 @@ impl Mint { /// - Payment processor initialization and startup /// - Invoice payment monitoring across all configured payment processors pub async fn start(&self) -> Result<(), Error> { + // Checks the status of all pending melt quotes + // Pending melt quotes where the payment has gone through inputs are burnt + // Pending melt quotes where the payment has **failed** inputs are reset to unspent + self.check_pending_melt_quotes().await?; + + // Recover from incomplete swap sagas + // This cleans up incomplete swap operations using persisted saga state + self.recover_from_incomplete_sagas().await?; + let mut task_state = self.task_state.lock().await; // Prevent starting if already running @@ -813,6 +821,13 @@ impl Mint { &self, blinded_message: Vec, ) -> Result, Error> { + #[cfg(test)] + { + if crate::test_helpers::mint::should_fail_in_test() { + return Err(Error::SignatureMissingOrInvalid); + } + } + #[cfg(feature = "prometheus")] global::inc_in_flight_requests("blind_sign"); diff --git a/crates/cdk/src/mint/proof_writer.rs b/crates/cdk/src/mint/proof_writer.rs index 835fec7fc..65f35ab0c 100644 --- a/crates/cdk/src/mint/proof_writer.rs +++ b/crates/cdk/src/mint/proof_writer.rs @@ -3,6 +3,7 @@ use std::collections::{HashMap, HashSet}; use std::sync::Arc; use cdk_common::database::{self, DynMintDatabase, MintTransaction}; +use cdk_common::mint::Operation; use cdk_common::{Error, Proofs, ProofsMethods, PublicKey, QuoteId, State}; use super::subscription::PubSubManager; @@ -49,6 +50,7 @@ impl ProofWriter { tx: &mut Tx<'_, '_>, proofs: &Proofs, quote_id: Option, + operation_id: &Operation, ) -> Result, Error> { let proof_states = if let Some(proofs) = self.proof_original_states.as_mut() { proofs @@ -56,7 +58,11 @@ impl ProofWriter { return Err(Error::Internal); }; - if let Some(err) = tx.add_proofs(proofs.clone(), quote_id).await.err() { + if let Some(err) = tx + .add_proofs(proofs.clone(), quote_id, operation_id) + .await + .err() + { return match err { cdk_common::database::Error::Duplicate => Err(Error::TokenPending), cdk_common::database::Error::AttemptUpdateSpentProof => { diff --git a/crates/cdk/src/mint/start_up_check.rs b/crates/cdk/src/mint/start_up_check.rs index ed23318f5..140e5d803 100644 --- a/crates/cdk/src/mint/start_up_check.rs +++ b/crates/cdk/src/mint/start_up_check.rs @@ -3,7 +3,10 @@ //! These checks are need in the case the mint was offline and the lightning node was node. //! These ensure that the status of the mint or melt quote matches in the mint db and on the node. +use cdk_common::mint::OperationKind; + use super::{Error, Mint}; +use crate::mint::swap::swap_saga::compensation::{CompensatingAction, RemoveSwapSetup}; use crate::mint::{MeltQuote, MeltQuoteState, PaymentMethod}; use crate::types::PaymentProcessorKey; @@ -79,4 +82,67 @@ impl Mint { Ok(()) } + + /// Recover from incomplete swap sagas + /// + /// Checks all persisted sagas for swap operations and compensates + /// incomplete ones by removing both proofs and blinded messages. + pub async fn recover_from_incomplete_sagas(&self) -> Result<(), Error> { + let incomplete_sagas = self + .localstore + .get_incomplete_sagas(OperationKind::Swap) + .await?; + + if incomplete_sagas.is_empty() { + tracing::info!("No incomplete swap sagas found to recover."); + return Ok(()); + } + + let total_sagas = incomplete_sagas.len(); + tracing::info!("Found {} incomplete swap sagas to recover.", total_sagas); + + for saga in incomplete_sagas { + tracing::info!( + "Recovering saga {} in state '{}' (created: {}, updated: {})", + saga.operation_id, + saga.state.state(), + saga.created_at, + saga.updated_at + ); + + // Use the same compensation logic as in-process failures + let compensation = RemoveSwapSetup { + blinded_secrets: saga.blinded_secrets.clone(), + input_ys: saga.input_ys.clone(), + }; + + // Execute compensation + if let Err(e) = compensation.execute(&self.localstore).await { + tracing::error!( + "Failed to compensate saga {}: {}. Continuing...", + saga.operation_id, + e + ); + continue; + } + + // Delete saga after successful compensation + let mut tx = self.localstore.begin_transaction().await?; + if let Err(e) = tx.delete_saga(&saga.operation_id).await { + tracing::error!("Failed to delete saga for {}: {}", saga.operation_id, e); + tx.rollback().await?; + continue; + } + tx.commit().await?; + + tracing::info!("Successfully recovered saga {}", saga.operation_id); + } + + tracing::info!( + "Successfully recovered {} incomplete swap sagas.", + total_sagas + ); + + Ok(()) + } } diff --git a/crates/cdk/src/mint/swap.rs b/crates/cdk/src/mint/swap.rs deleted file mode 100644 index 8b3cc3711..000000000 --- a/crates/cdk/src/mint/swap.rs +++ /dev/null @@ -1,173 +0,0 @@ -#[cfg(feature = "prometheus")] -use cdk_prometheus::METRICS; -use tracing::instrument; - -use super::blinded_message_writer::BlindedMessageWriter; -use super::nut11::{enforce_sig_flag, EnforceSigFlag}; -use super::proof_writer::ProofWriter; -use super::{Mint, PublicKey, SigFlag, State, SwapRequest, SwapResponse}; -use crate::Error; - -impl Mint { - /// Process Swap - #[instrument(skip_all)] - pub async fn process_swap_request( - &self, - swap_request: SwapRequest, - ) -> Result { - #[cfg(feature = "prometheus")] - METRICS.inc_in_flight_requests("process_swap_request"); - // Do the external call before beginning the db transaction - // Check any overflow before talking to the signatory - swap_request.input_amount()?; - swap_request.output_amount()?; - - // We add blinded messages to db before attempting to sign - // this ensures that they are unique and have not been used before - let mut blinded_message_writer = BlindedMessageWriter::new(self.localstore.clone()); - let mut tx = self.localstore.begin_transaction().await?; - - match blinded_message_writer - .add_blinded_messages(&mut tx, None, swap_request.outputs()) - .await - { - Ok(_) => { - tx.commit().await?; - } - Err(err) => { - #[cfg(feature = "prometheus")] - { - METRICS.dec_in_flight_requests("process_swap_request"); - METRICS.record_mint_operation("process_swap_request", false); - METRICS.record_error(); - } - return Err(err); - } - } - - let promises = self.blind_sign(swap_request.outputs().to_owned()).await?; - let input_verification = - self.verify_inputs(swap_request.inputs()) - .await - .map_err(|err| { - #[cfg(feature = "prometheus")] - { - METRICS.dec_in_flight_requests("process_swap_request"); - METRICS.record_mint_operation("process_swap_request", false); - METRICS.record_error(); - } - - tracing::debug!("Input verification failed: {:?}", err); - err - })?; - let mut tx = self.localstore.begin_transaction().await?; - - if let Err(err) = self - .verify_transaction_balanced( - &mut tx, - input_verification, - swap_request.inputs(), - swap_request.outputs(), - ) - .await - { - tracing::debug!("Attempt to swap unbalanced transaction, aborting: {err}"); - - #[cfg(feature = "prometheus")] - { - METRICS.dec_in_flight_requests("process_swap_request"); - METRICS.record_mint_operation("process_swap_request", false); - METRICS.record_error(); - } - - tx.rollback().await?; - blinded_message_writer.rollback().await?; - - return Err(err); - }; - - let validate_sig_result = self.validate_sig_flag(&swap_request).await; - - if let Err(err) = validate_sig_result { - tx.rollback().await?; - blinded_message_writer.rollback().await?; - - #[cfg(feature = "prometheus")] - self.record_swap_failure("process_swap_request"); - return Err(err); - } - let mut proof_writer = - ProofWriter::new(self.localstore.clone(), self.pubsub_manager.clone()); - let input_ys = match proof_writer - .add_proofs(&mut tx, swap_request.inputs(), None) - .await - { - Ok(ys) => ys, - Err(err) => { - #[cfg(feature = "prometheus")] - { - METRICS.dec_in_flight_requests("process_swap_request"); - METRICS.record_mint_operation("process_swap_request", false); - METRICS.record_error(); - } - tx.rollback().await?; - blinded_message_writer.rollback().await?; - return Err(err); - } - }; - - let update_proof_states_result = proof_writer - .update_proofs_states(&mut tx, &input_ys, State::Spent) - .await; - - if let Err(err) = update_proof_states_result { - #[cfg(feature = "prometheus")] - self.record_swap_failure("process_swap_request"); - - tx.rollback().await?; - blinded_message_writer.rollback().await?; - return Err(err); - } - - tx.add_blind_signatures( - &swap_request - .outputs() - .iter() - .map(|o| o.blinded_secret) - .collect::>(), - &promises, - None, - ) - .await?; - - proof_writer.commit(); - blinded_message_writer.commit(); - tx.commit().await?; - - let response = SwapResponse::new(promises); - - #[cfg(feature = "prometheus")] - { - METRICS.dec_in_flight_requests("process_swap_request"); - METRICS.record_mint_operation("process_swap_request", true); - } - - Ok(response) - } - - async fn validate_sig_flag(&self, swap_request: &SwapRequest) -> Result<(), Error> { - let EnforceSigFlag { sig_flag, .. } = enforce_sig_flag(swap_request.inputs().clone()); - - if sig_flag == SigFlag::SigAll { - swap_request.verify_sig_all()?; - } - - Ok(()) - } - #[cfg(feature = "prometheus")] - fn record_swap_failure(&self, operation: &str) { - METRICS.dec_in_flight_requests(operation); - METRICS.record_mint_operation(operation, false); - METRICS.record_error(); - } -} diff --git a/crates/cdk/src/mint/swap/mod.rs b/crates/cdk/src/mint/swap/mod.rs new file mode 100644 index 000000000..e0368978c --- /dev/null +++ b/crates/cdk/src/mint/swap/mod.rs @@ -0,0 +1,84 @@ +#[cfg(feature = "prometheus")] +use cdk_prometheus::METRICS; +use swap_saga::SwapSaga; +use tracing::instrument; + +use super::nut11::{enforce_sig_flag, EnforceSigFlag}; +use super::{Mint, SigFlag, SwapRequest, SwapResponse}; +use crate::Error; + +pub mod swap_saga; + +impl Mint { + /// Process Swap + #[instrument(skip_all)] + pub async fn process_swap_request( + &self, + swap_request: SwapRequest, + ) -> Result { + #[cfg(feature = "prometheus")] + METRICS.inc_in_flight_requests("process_swap_request"); + + swap_request.input_amount()?; + swap_request.output_amount()?; + + // Verify inputs (cryptographic verification, no DB needed) + let input_verification = + self.verify_inputs(swap_request.inputs()) + .await + .map_err(|err| { + #[cfg(feature = "prometheus")] + self.record_swap_failure("process_swap_request"); + + tracing::debug!("Input verification failed: {:?}", err); + err + })?; + + // Verify signature flag (no DB needed) + self.validate_sig_flag(&swap_request).await?; + + // Step 1: Initialize the swap saga + let init_saga = SwapSaga::new(self, self.localstore.clone(), self.pubsub_manager.clone()); + + // Step 2: TX1 - Setup swap (verify balance + add inputs as pending + add output blinded messages) + let setup_saga = init_saga + .setup_swap( + swap_request.inputs(), + swap_request.outputs(), + None, + input_verification, + ) + .await?; + + // Step 3: Blind sign outputs (no DB transaction) + let signed_saga = setup_saga.sign_outputs().await?; + + // Step 4: TX2 - Finalize swap (add signatures + mark inputs spent) + let response = signed_saga.finalize().await?; + + #[cfg(feature = "prometheus")] + { + METRICS.dec_in_flight_requests("process_swap_request"); + METRICS.record_mint_operation("process_swap_request", true); + } + + Ok(response) + } + + async fn validate_sig_flag(&self, swap_request: &SwapRequest) -> Result<(), Error> { + let EnforceSigFlag { sig_flag, .. } = enforce_sig_flag(swap_request.inputs().clone()); + + if sig_flag == SigFlag::SigAll { + swap_request.verify_sig_all()?; + } + + Ok(()) + } + + #[cfg(feature = "prometheus")] + fn record_swap_failure(&self, operation: &str) { + METRICS.dec_in_flight_requests(operation); + METRICS.record_mint_operation(operation, false); + METRICS.record_error(); + } +} diff --git a/crates/cdk/src/mint/swap/swap_saga/compensation.rs b/crates/cdk/src/mint/swap/swap_saga/compensation.rs new file mode 100644 index 000000000..3f8cc3687 --- /dev/null +++ b/crates/cdk/src/mint/swap/swap_saga/compensation.rs @@ -0,0 +1,61 @@ +use async_trait::async_trait; +use cdk_common::database::DynMintDatabase; +use cdk_common::{Error, PublicKey}; +use tracing::instrument; + +#[async_trait] +pub trait CompensatingAction: Send + Sync { + async fn execute(&self, db: &DynMintDatabase) -> Result<(), Error>; + fn name(&self) -> &'static str; +} + +/// Compensation action to remove swap setup (both proofs and blinded messages). +/// +/// This compensation is used when blind signing fails or finalization fails after +/// the setup transaction has committed. It removes: +/// - Output blinded messages (identified by blinded_secrets) +/// - Input proofs (identified by input_ys) +/// +/// This restores the database to its pre-swap state. +pub struct RemoveSwapSetup { + /// Blinded secrets (B values) from the output blinded messages + pub blinded_secrets: Vec, + /// Y values (public keys) from the input proofs + pub input_ys: Vec, +} + +#[async_trait] +impl CompensatingAction for RemoveSwapSetup { + #[instrument(skip_all)] + async fn execute(&self, db: &DynMintDatabase) -> Result<(), Error> { + if self.blinded_secrets.is_empty() && self.input_ys.is_empty() { + return Ok(()); + } + + tracing::info!( + "Compensation: Removing swap setup ({} blinded messages, {} proofs)", + self.blinded_secrets.len(), + self.input_ys.len() + ); + + let mut tx = db.begin_transaction().await?; + + // Remove blinded messages (outputs) + if !self.blinded_secrets.is_empty() { + tx.delete_blinded_messages(&self.blinded_secrets).await?; + } + + // Remove proofs (inputs) + if !self.input_ys.is_empty() { + tx.remove_proofs(&self.input_ys, None).await?; + } + + tx.commit().await?; + + Ok(()) + } + + fn name(&self) -> &'static str { + "RemoveSwapSetup" + } +} diff --git a/crates/cdk/src/mint/swap/swap_saga/mod.rs b/crates/cdk/src/mint/swap/swap_saga/mod.rs new file mode 100644 index 000000000..8c08c56b2 --- /dev/null +++ b/crates/cdk/src/mint/swap/swap_saga/mod.rs @@ -0,0 +1,514 @@ +use std::collections::VecDeque; +use std::sync::Arc; + +use cdk_common::database::DynMintDatabase; +use cdk_common::mint::{Operation, Saga, SwapSagaState}; +use cdk_common::nuts::BlindedMessage; +use cdk_common::{database, Error, Proofs, ProofsMethods, PublicKey, QuoteId, State}; +use tokio::sync::Mutex; +use tracing::instrument; + +use self::compensation::{CompensatingAction, RemoveSwapSetup}; +use self::state::{Initial, SetupComplete, Signed}; +use crate::mint::subscription::PubSubManager; + +pub mod compensation; +mod state; + +#[cfg(test)] +mod tests; + +/// Saga pattern implementation for atomic swap operations. +/// +/// # Why Use the Saga Pattern? +/// +/// The swap operation consists of multiple steps that span database transactions +/// and non-transactional operations (blind signing). We need to ensure atomicity +/// across these heterogeneous steps while maintaining consistency in failure scenarios. +/// +/// Traditional ACID transactions cannot span: +/// 1. Multiple database transactions (TX1: setup, TX2: finalize) +/// 2. Non-database operations (blind signing of outputs) +/// +/// The saga pattern solves this by: +/// - Breaking the operation into discrete steps with clear state transitions +/// - Recording compensating actions for each forward step +/// - Automatically rolling back via compensations if any step fails +/// +/// # Transaction Boundaries +/// +/// - **TX1 (setup_swap)**: Atomically verifies balance, adds input proofs (pending), +/// adds output blinded messages, and persists saga state for crash recovery +/// - **Signing (sign_outputs)**: Non-transactional cryptographic operation +/// - **TX2 (finalize)**: Atomically adds signatures to outputs, marks inputs as spent, +/// and deletes saga state (best-effort, will be cleaned up on recovery if this fails) +/// +/// Saga state persistence is atomic with swap state changes, ensuring consistency +/// for crash recovery scenarios. +/// +/// # Expected Actions +/// +/// 1. **setup_swap**: Verifies the swap is balanced, reserves inputs, prepares outputs +/// - Compensation: Removes both inputs and outputs if later steps fail +/// 2. **sign_outputs**: Performs blind signing (no DB changes) +/// - Triggers compensation if signing fails +/// 3. **finalize**: Commits signatures and marks inputs spent +/// - Triggers compensation if finalization fails +/// - Clears compensations on success (swap complete) +/// +/// # Failure Handling +/// +/// If any step fails after setup_swap, all compensating actions are executed in reverse +/// order to restore the database to its pre-swap state. This ensures no partial swaps +/// leave the system in an inconsistent state. +/// +/// # Compensation Order (LIFO) +/// +/// Compensations are stored in a VecDeque and executed in LIFO (Last-In-First-Out) order +/// using `push_front` + iteration. This ensures that actions are undone in the reverse +/// order they were performed, which is critical for maintaining data consistency. +/// +/// Example: If we perform actions A → B → C in the forward path, compensations must +/// execute as C' → B' → A' to properly reverse the operations without violating +/// any invariants or constraints. +/// +/// # Typestate Pattern +/// +/// This saga uses the **typestate pattern** to enforce state transitions at compile-time. +/// Each state (Initial, SetupComplete, Signed) is a distinct type, and operations are +/// only available on the appropriate type: +/// +/// ```text +/// SwapSaga +/// └─> setup_swap() -> SwapSaga +/// └─> sign_outputs() -> SwapSaga +/// └─> finalize() -> SwapResponse +/// ``` +/// +/// **Benefits:** +/// - Invalid state transitions (e.g., `finalize()` before `sign_outputs()`) won't compile +/// - State-specific data (e.g., signatures) only exists in the appropriate state type +/// - No runtime state checks or `Option` unwrapping needed +/// - IDE autocomplete only shows valid operations for each state +pub struct SwapSaga<'a, S> { + mint: &'a super::Mint, + db: DynMintDatabase, + pubsub: Arc, + /// Compensating actions in LIFO order (most recent first) + compensations: Arc>>>, + operation: Operation, + state_data: S, +} + +impl<'a> SwapSaga<'a, Initial> { + pub fn new(mint: &'a super::Mint, db: DynMintDatabase, pubsub: Arc) -> Self { + Self { + mint, + db, + pubsub, + compensations: Arc::new(Mutex::new(VecDeque::new())), + operation: Operation::new_swap(), + state_data: Initial, + } + } + + /// Sets up the swap by atomically verifying balance and reserving inputs/outputs. + /// + /// This is the first transaction (TX1) in the saga and must complete before blind signing. + /// + /// # What This Does + /// + /// Within a single database transaction: + /// 1. Verifies the swap is balanced (input amount >= output amount + fees) + /// 2. Adds input proofs to the database + /// 3. Updates input proof states from Unspent to Pending + /// 4. Adds output blinded messages to the database + /// 5. Persists saga state for crash recovery (atomic with steps 1-4) + /// 6. Publishes proof state changes via pubsub + /// + /// # Compensation + /// + /// Registers a compensation action that will remove both the input proofs and output + /// blinded messages if any subsequent step (signing or finalization) fails. + /// + /// # Errors + /// + /// - `TokenPending`: Proofs are already pending or blinded messages are duplicates + /// - `TokenAlreadySpent`: Proofs have already been spent + /// - `DuplicateOutputs`: Output blinded messages already exist + #[instrument(skip_all)] + pub async fn setup_swap( + self, + input_proofs: &Proofs, + blinded_messages: &[BlindedMessage], + quote_id: Option, + input_verification: crate::mint::Verification, + ) -> Result, Error> { + tracing::info!("TX1: Setting up swap (verify + inputs + outputs)"); + + let mut tx = self.db.begin_transaction().await?; + + // Verify balance within the transaction + self.mint + .verify_transaction_balanced( + &mut tx, + input_verification, + input_proofs, + blinded_messages, + ) + .await?; + + // Add input proofs to DB + if let Err(err) = tx + .add_proofs(input_proofs.clone(), quote_id.clone(), &self.operation) + .await + { + tx.rollback().await?; + return Err(match err { + database::Error::Duplicate => Error::TokenPending, + database::Error::AttemptUpdateSpentProof => Error::TokenAlreadySpent, + _ => Error::Database(err), + }); + } + + let ys = match input_proofs.ys() { + Ok(ys) => ys, + Err(err) => return Err(Error::NUT00(err)), + }; + + // Update input proof states to Pending + let original_proof_states = match tx.update_proofs_states(&ys, State::Pending).await { + Ok(states) => states, + Err(database::Error::AttemptUpdateSpentProof) + | Err(database::Error::AttemptRemoveSpentProof) => { + tx.rollback().await?; + return Err(Error::TokenAlreadySpent); + } + Err(err) => { + tx.rollback().await?; + return Err(err.into()); + } + }; + + // Verify proofs weren't already pending or spent + if ys.len() != original_proof_states.len() { + tracing::error!("Mismatched proof states"); + tx.rollback().await?; + return Err(Error::Internal); + } + + let forbidden_states = [State::Pending, State::Spent]; + for original_state in original_proof_states.iter().flatten() { + if forbidden_states.contains(original_state) { + tx.rollback().await?; + return Err(if *original_state == State::Pending { + Error::TokenPending + } else { + Error::TokenAlreadySpent + }); + } + } + + // Add output blinded messages + if let Err(err) = tx + .add_blinded_messages(quote_id.as_ref(), blinded_messages, &self.operation) + .await + { + tx.rollback().await?; + return Err(match err { + database::Error::Duplicate => Error::DuplicateOutputs, + _ => Error::Database(err), + }); + } + + // Publish proof state changes + for pk in &ys { + self.pubsub.proof_state((*pk, State::Pending)); + } + + // Store data in saga struct (avoid duplication in state enum) + let blinded_messages_vec = blinded_messages.to_vec(); + let blinded_secrets: Vec = blinded_messages_vec + .iter() + .map(|bm| bm.blinded_secret) + .collect(); + + // Persist saga state for crash recovery (atomic with TX1) + let saga = Saga::new_swap( + *self.operation.id(), + SwapSagaState::SetupComplete, + blinded_secrets.clone(), + ys.clone(), + ); + + if let Err(err) = tx.add_saga(&saga).await { + tx.rollback().await?; + return Err(err.into()); + } + + tx.commit().await?; + + // Register compensation (uses LIFO via push_front) + let compensations = Arc::clone(&self.compensations); + compensations + .lock() + .await + .push_front(Box::new(RemoveSwapSetup { + blinded_secrets: blinded_secrets.clone(), + input_ys: ys.clone(), + })); + + // Transition to SetupComplete state + Ok(SwapSaga { + mint: self.mint, + db: self.db, + pubsub: self.pubsub, + compensations: self.compensations, + operation: self.operation, + state_data: SetupComplete { + blinded_messages: blinded_messages_vec, + ys, + }, + }) + } +} + +impl<'a> SwapSaga<'a, SetupComplete> { + /// Performs blind signing of output blinded messages. + /// + /// This is a non-transactional cryptographic operation that happens after `setup_swap` + /// and before `finalize`. No database changes occur in this step. + /// + /// # What This Does + /// + /// 1. Retrieves blinded messages from the state data + /// 2. Calls the mint's blind signing function to generate signatures + /// 3. Stores signatures and transitions to the Signed state + /// + /// # Failure Handling + /// + /// If blind signing fails, all registered compensations are executed to roll back + /// the setup transaction, removing both input proofs and output blinded messages. + /// + /// # Errors + /// + /// - Propagates any errors from the blind signing operation + #[instrument(skip_all)] + pub async fn sign_outputs(self) -> Result, Error> { + tracing::info!("Signing outputs (no DB)"); + + match self + .mint + .blind_sign(self.state_data.blinded_messages.clone()) + .await + { + Ok(signatures) => { + // Transition to Signed state + // Note: We don't update saga state here because the "signed" state + // is not used by recovery logic - saga state remains "SetupComplete" + // until the swap is finalized or compensated + Ok(SwapSaga { + mint: self.mint, + db: self.db, + pubsub: self.pubsub, + compensations: self.compensations, + operation: self.operation, + state_data: Signed { + blinded_messages: self.state_data.blinded_messages, + ys: self.state_data.ys, + signatures, + }, + }) + } + Err(err) => { + self.compensate_all().await?; + Err(err) + } + } + } +} + +impl SwapSaga<'_, Signed> { + /// Finalizes the swap by committing signatures and marking inputs as spent. + /// + /// This is the second and final transaction (TX2) in the saga and completes the swap. + /// + /// # What This Does + /// + /// Within a single database transaction: + /// 1. Adds the blind signatures to the output blinded messages + /// 2. Updates input proof states from Pending to Spent + /// 3. Deletes saga state (best-effort, won't fail swap if this fails) + /// 4. Publishes proof state changes via pubsub + /// 5. Clears all registered compensations (swap successfully completed) + /// + /// # Failure Handling + /// + /// If finalization fails, all registered compensations are executed to roll back + /// the setup transaction, removing both input proofs and output blinded messages. + /// The signatures are not persisted, so they are lost. + /// + /// # Success + /// + /// On success, compensations are cleared and the swap is complete. The client + /// can now use the returned signatures to construct valid proofs. If saga state + /// deletion fails, a warning is logged but the swap still succeeds (orphaned + /// saga state will be cleaned up on next recovery). + /// + /// # Errors + /// + /// - `TokenAlreadySpent`: Input proofs were already spent by another operation + /// - Propagates any database errors + #[instrument(skip_all)] + pub async fn finalize(self) -> Result { + tracing::info!("TX2: Finalizing swap (signatures + mark spent)"); + + let blinded_secrets: Vec = self + .state_data + .blinded_messages + .iter() + .map(|bm| bm.blinded_secret) + .collect(); + + let mut tx = self.db.begin_transaction().await?; + + // Add blind signatures to outputs + // TODO: WE should move the should fail to the db so the there is not this extra rollback. + // This would allow the error to be from the same place in test and prod + #[cfg(test)] + { + if crate::test_helpers::mint::should_fail_for("ADD_SIGNATURES") { + tx.rollback().await?; + self.compensate_all().await?; + return Err(Error::Database(database::Error::Database( + "Test failure: ADD_SIGNATURES".into(), + ))); + } + } + + if let Err(err) = tx + .add_blind_signatures(&blinded_secrets, &self.state_data.signatures, None) + .await + { + tx.rollback().await?; + self.compensate_all().await?; + return Err(err.into()); + } + + // Mark input proofs as spent + // TODO: WE should move the should fail to the db so the there is not this extra rollback. + // This would allow the error to be from the same place in test and prod + #[cfg(test)] + { + if crate::test_helpers::mint::should_fail_for("UPDATE_PROOFS") { + tx.rollback().await?; + self.compensate_all().await?; + return Err(Error::Database(database::Error::Database( + "Test failure: UPDATE_PROOFS".into(), + ))); + } + } + + match tx + .update_proofs_states(&self.state_data.ys, State::Spent) + .await + { + Ok(_) => {} + Err(database::Error::AttemptUpdateSpentProof) + | Err(database::Error::AttemptRemoveSpentProof) => { + tx.rollback().await?; + self.compensate_all().await?; + return Err(Error::TokenAlreadySpent); + } + Err(err) => { + tx.rollback().await?; + self.compensate_all().await?; + return Err(err.into()); + } + } + + // Publish proof state changes + for pk in &self.state_data.ys { + self.pubsub.proof_state((*pk, State::Spent)); + } + + // Delete saga - swap completed successfully (best-effort, atomic with TX2) + // Don't fail the swap if saga deletion fails - orphaned saga will be + // cleaned up on next recovery + if let Err(e) = tx.delete_saga(self.operation.id()).await { + tracing::warn!( + "Failed to delete saga in finalize (will be cleaned up on recovery): {}", + e + ); + // Don't rollback - swap succeeded, orphaned saga is harmless + } + + tx.commit().await?; + + // Clear compensations - swap is complete + self.compensations.lock().await.clear(); + + Ok(cdk_common::nuts::SwapResponse::new( + self.state_data.signatures, + )) + } +} + +impl SwapSaga<'_, S> { + /// Execute all compensating actions and consume the saga. + /// + /// This method takes ownership of self to ensure the saga cannot be used + /// after compensation has been triggered. + #[instrument(skip_all)] + async fn compensate_all(self) -> Result<(), Error> { + let mut compensations = self.compensations.lock().await; + + if compensations.is_empty() { + return Ok(()); + } + + #[cfg(feature = "prometheus")] + { + use cdk_prometheus::METRICS; + + self.mint.record_swap_failure("process_swap_request"); + METRICS.dec_in_flight_requests("process_swap_request"); + } + + tracing::warn!("Running {} compensating actions", compensations.len()); + + while let Some(compensation) = compensations.pop_front() { + tracing::debug!("Running compensation: {}", compensation.name()); + if let Err(e) = compensation.execute(&self.db).await { + tracing::error!( + "Compensation {} failed: {}. Continuing...", + compensation.name(), + e + ); + } + } + + // Delete saga - swap was compensated + // Use a separate transaction since compensations already ran + // Don't fail the compensation if saga cleanup fails (log only) + let mut tx = match self.db.begin_transaction().await { + Ok(tx) => tx, + Err(e) => { + tracing::error!( + "Failed to begin tx for saga cleanup after compensation: {}", + e + ); + return Ok(()); // Compensations already ran, don't fail now + } + }; + + if let Err(e) = tx.delete_saga(self.operation.id()).await { + tracing::warn!("Failed to delete saga after compensation: {}", e); + } else if let Err(e) = tx.commit().await { + tracing::error!("Failed to commit saga cleanup after compensation: {}", e); + } + // Always succeed - compensations are done, saga cleanup is best-effort + + Ok(()) + } +} diff --git a/crates/cdk/src/mint/swap/swap_saga/state.rs b/crates/cdk/src/mint/swap/swap_saga/state.rs new file mode 100644 index 000000000..5ddfffb69 --- /dev/null +++ b/crates/cdk/src/mint/swap/swap_saga/state.rs @@ -0,0 +1,26 @@ +use cdk_common::nuts::{BlindSignature, BlindedMessage}; +use cdk_common::PublicKey; + +/// Initial state - no data yet. +/// +/// The swap saga starts in this state. Only the `setup_swap` method is available. +pub struct Initial; + +/// Setup complete - has blinded messages and input Y values. +/// +/// After successful setup, the saga transitions to this state. +/// Only the `sign_outputs` method is available. +pub struct SetupComplete { + pub blinded_messages: Vec, + pub ys: Vec, +} + +/// Signed state - has everything including signatures. +/// +/// After successful signing, the saga transitions to this state. +/// Only the `finalize` method is available. +pub struct Signed { + pub blinded_messages: Vec, + pub ys: Vec, + pub signatures: Vec, +} diff --git a/crates/cdk/src/mint/swap/swap_saga/tests.rs b/crates/cdk/src/mint/swap/swap_saga/tests.rs new file mode 100644 index 000000000..3f398464b --- /dev/null +++ b/crates/cdk/src/mint/swap/swap_saga/tests.rs @@ -0,0 +1,2993 @@ +#![cfg(test)] +//! Unit tests for the swap saga implementation +//! +//! These tests verify the swap saga pattern using in-memory mints and databases, +//! without requiring external dependencies like Lightning nodes. + +use std::sync::Arc; + +use cdk_common::nuts::{Proofs, ProofsMethods}; +use cdk_common::{Amount, State}; + +use super::SwapSaga; +use crate::mint::swap::Mint; +use crate::mint::Verification; +use crate::test_helpers::mint::{create_test_blinded_messages, create_test_mint}; + +/// Helper to create a verification result for testing +fn create_verification(amount: Amount) -> Verification { + Verification { + amount, + unit: Some(cdk_common::nuts::CurrencyUnit::Sat), + } +} + +/// Helper to create test proofs for swapping using the mint's process +async fn create_swap_inputs(mint: &Mint, amount: Amount) -> (Proofs, Verification) { + let proofs = crate::test_helpers::mint::mint_test_proofs(mint, amount) + .await + .expect("Failed to create test proofs"); + + let verification = create_verification(amount); + + (proofs, verification) +} + +/// Tests that a SwapSaga can be created in the Initial state. +/// +/// # What This Tests +/// - SwapSaga::new() creates a saga in the Initial state +/// - The typestate pattern ensures only Initial state is accessible after creation +/// - No database operations occur during construction +/// +/// # Success Criteria +/// - Saga can be instantiated without errors +/// - Saga is in Initial state (enforced by type system) +#[tokio::test] +async fn test_swap_saga_initial_state_creation() { + let mint = create_test_mint().await.unwrap(); + let db = mint.localstore(); + let pubsub = mint.pubsub_manager(); + + let _saga = SwapSaga::new(&mint, db, pubsub); + + // If we can create the saga, we're in the Initial state + // This is verified by the type system - only SwapSaga can be created with new() +} + +/// Tests the complete happy path flow through all sagas. +/// +/// # What This Tests +/// - Initial -> SetupComplete -> Signed -> Response state transitions +/// - Database transactions commit successfully at each stage +/// - Input proofs are marked as Pending during setup, then Spent after finalization +/// - Output signatures are generated and returned correctly +/// - Compensations are cleared on successful completion +/// +/// # Flow +/// 1. Create saga in Initial state +/// 2. setup_swap: Transition to SetupComplete (TX1: add proofs + blinded messages) +/// 3. sign_outputs: Transition to Signed (blind signing, no DB operations) +/// 4. finalize: Complete saga (TX2: add signatures, mark proofs spent) +/// +/// # Success Criteria +/// - All state transitions succeed +/// - Response contains correct number of signatures +/// - All input proofs are marked as Spent +/// - No errors occur during the entire flow +#[tokio::test] +async fn test_swap_saga_full_flow_success() { + let mint = create_test_mint().await.unwrap(); + + let amount = Amount::from(100); + let (input_proofs, input_verification) = create_swap_inputs(&mint, amount).await; + + let (output_blinded_messages, _pre_mint) = + create_test_blinded_messages(&mint, amount).await.unwrap(); + + let db = mint.localstore(); + let pubsub = mint.pubsub_manager(); + + let saga = SwapSaga::new(&mint, db, pubsub); + + let saga = saga + .setup_swap( + &input_proofs, + &output_blinded_messages, + None, + input_verification, + ) + .await + .expect("Setup should succeed"); + + let saga = saga.sign_outputs().await.expect("Signing should succeed"); + + let response = saga.finalize().await.expect("Finalize should succeed"); + + assert_eq!( + response.signatures.len(), + output_blinded_messages.len(), + "Should have signatures for all outputs" + ); + + let ys = input_proofs.ys().unwrap(); + let states = mint + .localstore() + .get_proofs_states(&ys) + .await + .expect("Failed to get proof states"); + + for state in states { + assert_eq!( + state.unwrap(), + State::Spent, + "Input proofs should be marked as spent" + ); + } +} + +/// Tests the Initial -> SetupComplete state transition. +/// +/// # What This Tests +/// - setup_swap() successfully transitions saga from Initial to SetupComplete state +/// - State data contains blinded messages and input proof Y values +/// - Database transaction (TX1) commits successfully +/// - Input proofs are marked as Pending (not Spent) +/// - Compensation action is registered for potential rollback +/// +/// # Database Operations (TX1) +/// 1. Verify transaction is balanced +/// 2. Add input proofs to database +/// 3. Update proof states to Pending +/// 4. Add output blinded messages to database +/// 5. Commit transaction +/// +/// # Success Criteria +/// - Saga transitions to SetupComplete state +/// - State data correctly stores blinded messages and input Ys +/// - All input proofs have state = Pending in database +#[tokio::test] +async fn test_swap_saga_setup_transition() { + let mint = create_test_mint().await.unwrap(); + + let amount = Amount::from(64); + let (input_proofs, input_verification) = create_swap_inputs(&mint, amount).await; + + let (output_blinded_messages, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + + let db = mint.localstore(); + let pubsub = mint.pubsub_manager(); + + let saga = SwapSaga::new(&mint, db, pubsub); + + let saga = saga + .setup_swap( + &input_proofs, + &output_blinded_messages, + None, + input_verification, + ) + .await + .expect("Setup should succeed"); + + assert_eq!( + saga.state_data.blinded_messages.len(), + output_blinded_messages.len(), + "SetupComplete state should contain blinded messages" + ); + + assert_eq!( + saga.state_data.ys.len(), + input_proofs.len(), + "SetupComplete state should contain input ys" + ); + + let ys = input_proofs.ys().unwrap(); + let states = mint + .localstore() + .get_proofs_states(&ys) + .await + .expect("Failed to get proof states"); + + for state in states { + assert_eq!( + state.unwrap(), + State::Pending, + "Input proofs should be marked as pending after setup" + ); + } +} + +/// Tests the SetupComplete -> Signed state transition. +/// +/// # What This Tests +/// - sign_outputs() successfully transitions saga from SetupComplete to Signed state +/// - Blind signatures are generated for all output blinded messages +/// - No database operations occur during signing (cryptographic operation only) +/// - State data contains signatures matching the number of blinded messages +/// +/// # Operations +/// 1. Performs blind signing on blinded messages (non-transactional) +/// 2. Stores signatures in Signed state +/// 3. Preserves blinded messages and input Ys from previous state +/// +/// # Success Criteria +/// - Saga transitions to Signed state +/// - Number of signatures equals number of blinded messages +/// - Compensations are still registered (cleared only on finalize) +#[tokio::test] +async fn test_swap_saga_sign_outputs_transition() { + let mint = create_test_mint().await.unwrap(); + + let amount = Amount::from(128); + let (input_proofs, input_verification) = create_swap_inputs(&mint, amount).await; + + let (output_blinded_messages, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + + let db = mint.localstore(); + let pubsub = mint.pubsub_manager(); + + let saga = SwapSaga::new(&mint, db, pubsub); + + let saga = saga + .setup_swap( + &input_proofs, + &output_blinded_messages, + None, + input_verification, + ) + .await + .expect("Setup should succeed"); + + let saga = saga.sign_outputs().await.expect("Signing should succeed"); + + assert_eq!( + saga.state_data.signatures.len(), + output_blinded_messages.len(), + "Signed state should contain signatures for all outputs" + ); +} + +/// Tests that duplicate input proofs are rejected during setup. +/// +/// # What This Tests +/// - Database detects and rejects duplicate proof additions +/// - setup_swap() fails with appropriate error (TokenPending or duplicate error) +/// - Transaction is rolled back, leaving no partial state +/// +/// # Attack Vector +/// This prevents an attacker from trying to spend the same proof twice +/// within a single swap request. +/// +/// # Success Criteria +/// - setup_swap() returns an error +/// - Database remains unchanged (transaction rollback) +#[tokio::test] +async fn test_swap_saga_duplicate_inputs() { + let mint = create_test_mint().await.unwrap(); + + let amount = Amount::from(100); + let (mut input_proofs, input_verification) = create_swap_inputs(&mint, amount).await; + + input_proofs.push(input_proofs[0].clone()); + + let (output_blinded_messages, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + + let db = mint.localstore(); + let pubsub = mint.pubsub_manager(); + + let saga = SwapSaga::new(&mint, db, pubsub); + + let result = saga + .setup_swap( + &input_proofs, + &output_blinded_messages, + None, + input_verification, + ) + .await; + + assert!(result.is_err(), "Setup should fail with duplicate inputs"); +} + +/// Tests that duplicate output blinded messages are rejected during setup. +/// +/// # What This Tests +/// - Database detects and rejects duplicate blinded message additions +/// - setup_swap() fails with DuplicateOutputs error +/// - Transaction is rolled back, leaving no partial state +/// +/// # Attack Vector +/// This prevents reuse of blinded messages, which would allow an attacker +/// to receive the same blind signature multiple times. +/// +/// # Success Criteria +/// - setup_swap() returns an error +/// - Database remains unchanged (transaction rollback) +#[tokio::test] +async fn test_swap_saga_duplicate_outputs() { + let mint = create_test_mint().await.unwrap(); + + let amount = Amount::from(100); + let (input_proofs, input_verification) = create_swap_inputs(&mint, amount).await; + + let (mut output_blinded_messages, _) = + create_test_blinded_messages(&mint, amount).await.unwrap(); + + output_blinded_messages.push(output_blinded_messages[0].clone()); + + let db = mint.localstore(); + let pubsub = mint.pubsub_manager(); + + let saga = SwapSaga::new(&mint, db, pubsub); + + let result = saga + .setup_swap( + &input_proofs, + &output_blinded_messages, + None, + input_verification, + ) + .await; + + assert!(result.is_err(), "Setup should fail with duplicate outputs"); +} + +/// Tests that unbalanced swap requests are rejected (outputs > inputs). +/// +/// # What This Tests +/// - Balance verification detects when output amount exceeds input amount +/// - setup_swap() fails with TransactionUnbalanced error +/// - Transaction is rolled back before any database changes +/// +/// # Attack Vector +/// This prevents an attacker from creating value out of thin air by +/// requesting more outputs than they provided in inputs. +/// +/// # Success Criteria +/// - setup_swap() returns an error +/// - Database remains unchanged (no proofs or blinded messages added) +#[tokio::test] +async fn test_swap_saga_unbalanced_transaction_more_outputs() { + let mint = create_test_mint().await.unwrap(); + + let input_amount = Amount::from(100); + let (input_proofs, input_verification) = create_swap_inputs(&mint, input_amount).await; + + let output_amount = Amount::from(150); + let (output_blinded_messages, _) = create_test_blinded_messages(&mint, output_amount) + .await + .unwrap(); + + let db = mint.localstore(); + let pubsub = mint.pubsub_manager(); + + let saga = SwapSaga::new(&mint, db, pubsub); + + let result = saga + .setup_swap( + &input_proofs, + &output_blinded_messages, + None, + input_verification, + ) + .await; + + assert!( + result.is_err(), + "Setup should fail when outputs exceed inputs" + ); +} + +/// Tests that compensation actions are registered and cleared correctly. +/// +/// # What This Tests +/// - Compensations start empty +/// - setup_swap() registers one compensation action (RemoveSwapSetup) +/// - sign_outputs() preserves compensations (no change) +/// - finalize() clears all compensations on success +/// +/// # Saga Pattern +/// Compensations allow rollback if any step fails. They are cleared only +/// when the entire saga completes successfully. This test verifies the +/// lifecycle of compensation tracking. +/// +/// # Success Criteria +/// - 0 compensations initially +/// - 1 compensation after setup +/// - 1 compensation after signing +/// - Compensations cleared after successful finalize +#[tokio::test] +async fn test_swap_saga_compensation_clears_on_success() { + let mint = create_test_mint().await.unwrap(); + + let amount = Amount::from(100); + let (input_proofs, input_verification) = create_swap_inputs(&mint, amount).await; + + let (output_blinded_messages, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + + let db = mint.localstore(); + let pubsub = mint.pubsub_manager(); + + let saga = SwapSaga::new(&mint, db, pubsub); + + let compensations_before = saga.compensations.lock().await.len(); + + let saga = saga + .setup_swap( + &input_proofs, + &output_blinded_messages, + None, + input_verification, + ) + .await + .expect("Setup should succeed"); + + let compensations_after_setup = saga.compensations.lock().await.len(); + assert_eq!( + compensations_after_setup, 1, + "Should have one compensation after setup" + ); + + let saga = saga.sign_outputs().await.expect("Signing should succeed"); + + let compensations_after_sign = saga.compensations.lock().await.len(); + assert_eq!( + compensations_after_sign, 1, + "Should still have one compensation after signing" + ); + + let _response = saga.finalize().await.expect("Finalize should succeed"); + + assert_eq!( + compensations_before, 0, + "Should start with no compensations" + ); +} + +/// Tests that empty input proofs are rejected during setup. +/// +/// # What This Tests +/// - Swap with empty input proofs should fail gracefully +/// - No database changes should occur +/// +/// # Success Criteria +/// - setup_swap() returns an error (not panic) +/// - Database remains unchanged +/// +/// # Note +/// Empty inputs with non-empty outputs creates an unbalanced transaction +/// (trying to create value from nothing), which should be rejected by +/// the balance verification step. +#[tokio::test] +async fn test_swap_saga_empty_inputs() { + let mint = create_test_mint().await.unwrap(); + let amount = Amount::from(100); + + let empty_proofs = Proofs::new(); + let (output_blinded_messages, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + // Verification must match the actual input amount (zero for empty proofs) + let verification = create_verification(Amount::from(0)); + + let db = mint.localstore(); + let pubsub = mint.pubsub_manager(); + let saga = SwapSaga::new(&mint, db, pubsub); + + let result = saga + .setup_swap(&empty_proofs, &output_blinded_messages, None, verification) + .await; + + // This should fail because outputs (100) > inputs (0) + assert!( + result.is_err(), + "Empty inputs with non-empty outputs should be rejected (unbalanced)" + ); +} + +/// Tests that empty output blinded messages are rejected during setup. +/// +/// # What This Tests +/// - Swap with empty output blinded messages should fail gracefully +/// - No database changes should occur +/// +/// # Success Criteria +/// - setup_swap() returns an error (not panic) +/// - Database remains unchanged +#[tokio::test] +async fn test_swap_saga_empty_outputs() { + let mint = create_test_mint().await.unwrap(); + let amount = Amount::from(100); + let (input_proofs, input_verification) = create_swap_inputs(&mint, amount).await; + + let empty_blinded_messages = vec![]; + + let db = mint.localstore(); + let pubsub = mint.pubsub_manager(); + let saga = SwapSaga::new(&mint, db, pubsub); + + let result = saga + .setup_swap( + &input_proofs, + &empty_blinded_messages, + None, + input_verification, + ) + .await; + + assert!(result.is_err(), "Empty outputs should be rejected"); +} + +/// Tests that both empty inputs and outputs are rejected during setup. +/// +/// # What This Tests +/// - Swap with both empty inputs and outputs should fail gracefully +/// - No database changes should occur +/// +/// # Success Criteria +/// - setup_swap() returns an error (not panic) +/// - Database remains unchanged +#[tokio::test] +async fn test_swap_saga_both_empty() { + let mint = create_test_mint().await.unwrap(); + + let empty_proofs = Proofs::new(); + let empty_blinded_messages = vec![]; + let verification = create_verification(Amount::from(0)); + + let db = mint.localstore(); + let pubsub = mint.pubsub_manager(); + let saga = SwapSaga::new(&mint, db, pubsub); + + let result = saga + .setup_swap(&empty_proofs, &empty_blinded_messages, None, verification) + .await; + + assert!(result.is_err(), "Empty swap should be rejected"); +} + +/// Tests that a saga dropped without finalize does not auto-cleanup. +/// +/// # What This Tests +/// - When a saga is dropped after setup but before finalize: +/// - Proofs remain in Pending state (no automatic cleanup) +/// - Blinded messages remain in database +/// - No compensations run automatically on drop +/// +/// # Design Choice +/// This tests for resource leaks and documents expected behavior. +/// Cleanup requires explicit compensation or timeout mechanism. +/// +/// # Success Criteria +/// - After saga drop, proofs still Pending +/// - Blinded messages still exist in database +#[tokio::test] +async fn test_swap_saga_drop_without_finalize() { + let mint = create_test_mint().await.unwrap(); + let amount = Amount::from(100); + let (input_proofs, input_verification) = create_swap_inputs(&mint, amount).await; + let (output_blinded_messages, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + + let db = mint.localstore(); + let ys = input_proofs.ys().unwrap(); + + { + let pubsub = mint.pubsub_manager(); + let saga = SwapSaga::new(&mint, db.clone(), pubsub); + + let _saga = saga + .setup_swap( + &input_proofs, + &output_blinded_messages, + None, + input_verification, + ) + .await + .expect("Setup should succeed"); + + // Verify setup state + let states = db.get_proofs_states(&ys).await.unwrap(); + assert!(states.iter().all(|s| s == &Some(State::Pending))); + + // _saga is dropped here without calling finalize + } + + // Verify state is NOT automatically cleaned up + let states_after = db.get_proofs_states(&ys).await.unwrap(); + assert!( + states_after.iter().all(|s| s == &Some(State::Pending)), + "Proofs should remain Pending after saga drop (no auto-cleanup)" + ); + + // NOTE: This is expected behavior - compensations don't run on drop + // Cleanup requires either: + // 1. Explicit compensation call + // 2. Timeout mechanism to clean up stale Pending proofs + // 3. Manual intervention +} + +/// Tests that a saga dropped after signing loses signatures. +/// +/// # What This Tests +/// - When a saga is dropped after signing but before finalize: +/// - Proofs remain Pending +/// - Signatures are lost (not persisted) +/// - Demonstrates the importance of calling finalize +/// +/// # Success Criteria +/// - Proofs still Pending after drop +/// - No signatures in database (they were only in memory) +#[tokio::test] +async fn test_swap_saga_drop_after_signing() { + let mint = create_test_mint().await.unwrap(); + let amount = Amount::from(100); + let (input_proofs, input_verification) = create_swap_inputs(&mint, amount).await; + let (output_blinded_messages, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + + let db = mint.localstore(); + let ys = input_proofs.ys().unwrap(); + let _blinded_secrets: Vec<_> = output_blinded_messages + .iter() + .map(|bm| bm.blinded_secret) + .collect(); + + { + let pubsub = mint.pubsub_manager(); + let saga = SwapSaga::new(&mint, db.clone(), pubsub); + + let saga = saga + .setup_swap( + &input_proofs, + &output_blinded_messages, + None, + input_verification, + ) + .await + .expect("Setup should succeed"); + + let saga = saga.sign_outputs().await.expect("Signing should succeed"); + + // Verify we're in Signed state (has signatures) + assert_eq!( + saga.state_data.signatures.len(), + output_blinded_messages.len() + ); + + // saga is dropped here - signatures are lost! + } + + // Verify proofs still Pending + let states_after = db.get_proofs_states(&ys).await.unwrap(); + assert!(states_after.iter().all(|s| s == &Some(State::Pending))); + + // Verify signatures were NOT persisted (they were only in memory in the saga) + let signatures = db.get_blind_signatures(&_blinded_secrets).await.unwrap(); + assert!( + signatures.iter().all(|s| s.is_none()), + "Signatures should be lost when saga is dropped (never persisted)" + ); + + // This demonstrates why finalize() is critical - without it, the signatures + // generated during signing are lost and the swap cannot complete +} + +/// Tests that compensations execute when sign_outputs() fails. +/// +/// # What This Tests +/// - Verify that compensations execute when sign_outputs() fails +/// - Verify that proofs are removed from database (rollback of setup) +/// - Verify that blinded messages are removed from database +/// - Verify that proof states are cleared (no longer Pending) +/// +/// # Implementation +/// Uses TEST_FAIL environment variable to make blind_sign() fail +/// +/// # Success Criteria +/// - Signing fails with error +/// - Proofs are removed from database after failure +/// - Blinded messages are removed after failure +#[tokio::test] +async fn test_swap_saga_compensation_on_signing_failure() { + let mint = create_test_mint().await.unwrap(); + let amount = Amount::from(100); + let (input_proofs, input_verification) = create_swap_inputs(&mint, amount).await; + let (output_blinded_messages, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + + let db = mint.localstore(); + let pubsub = mint.pubsub_manager(); + let saga = SwapSaga::new(&mint, db.clone(), pubsub); + + // Setup should succeed + let saga = saga + .setup_swap( + &input_proofs, + &output_blinded_messages, + None, + input_verification, + ) + .await + .expect("Setup should succeed"); + + // Verify setup state + let ys = input_proofs.ys().unwrap(); + let states = db.get_proofs_states(&ys).await.unwrap(); + assert!(states.iter().all(|s| s == &Some(State::Pending))); + + // Enable test failure mode + std::env::set_var("TEST_FAIL", "1"); + + // Attempt signing (should fail due to TEST_FAIL) + let result = saga.sign_outputs().await; + + // Clean up environment variable immediately + std::env::remove_var("TEST_FAIL"); + + assert!(result.is_err(), "Signing should fail"); + + // Verify compensation executed - proofs removed + let states_after = db.get_proofs_states(&ys).await.unwrap(); + assert!( + states_after.iter().all(|s| s.is_none()), + "Proofs should be removed" + ); + + // Verify blinded messages removed (compensation removes blinded messages, not signatures) + // Since signatures are never created (only during finalize), we verify that + // if we query for them, we get None for all (they were never added) + let _blinded_secrets: Vec<_> = output_blinded_messages + .iter() + .map(|bm| bm.blinded_secret) + .collect(); + let signatures = db.get_blind_signatures(&_blinded_secrets).await.unwrap(); + assert!( + signatures.iter().all(|s| s.is_none()), + "No signatures should exist (never created)" + ); +} + +/// Tests that double-spend attempts are detected and rejected. +/// +/// # What This Tests +/// - First complete swap marks proofs as Spent +/// - Second swap attempt with same proofs fails immediately +/// - Database proof state prevents double-spending +/// +/// # Security +/// This is a critical security test. Double-spending would allow an +/// attacker to reuse the same ecash tokens multiple times. The database +/// must detect that proofs are already spent and reject the second swap. +/// +/// # Flow +/// 1. Complete first swap successfully (proofs marked Spent) +/// 2. Attempt second swap with same proofs +/// 3. Second setup_swap() fails with TokenAlreadySpent error +/// +/// # Success Criteria +/// - First swap completes successfully +/// - Second swap fails with error +/// - Proofs remain in Spent state +#[tokio::test] +async fn test_swap_saga_double_spend_detection() { + let mint = create_test_mint().await.unwrap(); + + let amount = Amount::from(100); + let (input_proofs, input_verification) = create_swap_inputs(&mint, amount).await; + + let (output_blinded_messages_1, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + let (output_blinded_messages_2, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + + let db = mint.localstore(); + let pubsub = mint.pubsub_manager(); + + let saga1 = SwapSaga::new(&mint, db.clone(), pubsub.clone()); + + let saga1 = saga1 + .setup_swap( + &input_proofs, + &output_blinded_messages_1, + None, + input_verification.clone(), + ) + .await + .expect("First setup should succeed"); + + let saga1 = saga1 + .sign_outputs() + .await + .expect("First signing should succeed"); + + let _response1 = saga1 + .finalize() + .await + .expect("First finalize should succeed"); + + let saga2 = SwapSaga::new(&mint, db, pubsub); + + let result = saga2 + .setup_swap( + &input_proofs, + &output_blinded_messages_2, + None, + input_verification, + ) + .await; + + assert!( + result.is_err(), + "Second setup should fail due to double-spend" + ); +} + +/// Tests that pending proofs are detected and rejected. +/// +/// # What This Tests +/// - First swap marks proofs as Pending during setup +/// - Second swap attempt with same proofs fails immediately +/// - Database proof state prevents concurrent use of same proofs +/// +/// # Concurrency Protection +/// When proofs are marked Pending, they are reserved for an in-progress +/// swap. No other swap should be able to use them until the first swap +/// completes or rolls back. +/// +/// # Flow +/// 1. Start first swap (proofs marked Pending) +/// 2. DO NOT finalize first swap +/// 3. Attempt second swap with same proofs +/// 4. Second setup_swap() fails with TokenPending error +/// +/// # Success Criteria +/// - First setup succeeds (proofs marked Pending) +/// - Second setup fails with error +/// - Proofs remain in Pending state +#[tokio::test] +async fn test_swap_saga_pending_proof_detection() { + let mint = create_test_mint().await.unwrap(); + + let amount = Amount::from(100); + let (input_proofs, input_verification) = create_swap_inputs(&mint, amount).await; + + let (output_blinded_messages_1, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + let (output_blinded_messages_2, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + + let db = mint.localstore(); + let pubsub = mint.pubsub_manager(); + + let saga1 = SwapSaga::new(&mint, db.clone(), pubsub.clone()); + + let saga1 = saga1 + .setup_swap( + &input_proofs, + &output_blinded_messages_1, + None, + input_verification.clone(), + ) + .await + .expect("First setup should succeed"); + + // Keep saga1 in scope to maintain pending proofs + drop(saga1); + + let saga2 = SwapSaga::new(&mint, db, pubsub); + + let result = saga2 + .setup_swap( + &input_proofs, + &output_blinded_messages_2, + None, + input_verification, + ) + .await; + + assert!( + result.is_err(), + "Second setup should fail because proofs are pending" + ); +} + +/// Tests concurrent swap attempts with the same proofs. +/// +/// # What This Tests +/// - Database serialization ensures only one concurrent swap succeeds +/// - Exactly one of N concurrent swaps with same proofs completes +/// - Other swaps fail with TokenPending or TokenAlreadySpent errors +/// - Final proof state is Spent (from the successful swap) +/// +/// # Race Condition Protection +/// This test verifies that the saga pattern combined with database +/// transactions provides proper serialization. Even with 3 tasks racing +/// to setup/sign/finalize, only one can succeed. +/// +/// # Flow +/// 1. Spawn 3 concurrent tasks, each trying to swap the same proofs +/// 2. Each task creates its own saga and attempts full flow +/// 3. Database ensures only one can mark proofs as Pending/Spent +/// 4. Count successes and failures +/// +/// # Success Criteria +/// - Exactly 1 swap succeeds +/// - Exactly 2 swaps fail +/// - All proofs end up in Spent state +#[tokio::test(flavor = "multi_thread", worker_threads = 3)] +async fn test_swap_saga_concurrent_swaps() { + let mint = Arc::new(create_test_mint().await.unwrap()); + + let amount = Amount::from(100); + let (input_proofs, input_verification) = create_swap_inputs(&mint, amount).await; + + let (output_blinded_messages_1, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + let (output_blinded_messages_2, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + let (output_blinded_messages_3, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + + let mint1 = Arc::clone(&mint); + let mint2 = Arc::clone(&mint); + let mint3 = Arc::clone(&mint); + + let proofs1 = input_proofs.clone(); + let proofs2 = input_proofs.clone(); + let proofs3 = input_proofs.clone(); + + let verification1 = input_verification.clone(); + let verification2 = input_verification.clone(); + let verification3 = input_verification.clone(); + + let task1 = tokio::spawn(async move { + let db = mint1.localstore(); + let pubsub = mint1.pubsub_manager(); + let saga = SwapSaga::new(&*mint1, db, pubsub); + + let saga = saga + .setup_swap(&proofs1, &output_blinded_messages_1, None, verification1) + .await?; + let saga = saga.sign_outputs().await?; + saga.finalize().await + }); + + let task2 = tokio::spawn(async move { + let db = mint2.localstore(); + let pubsub = mint2.pubsub_manager(); + let saga = SwapSaga::new(&*mint2, db, pubsub); + + let saga = saga + .setup_swap(&proofs2, &output_blinded_messages_2, None, verification2) + .await?; + let saga = saga.sign_outputs().await?; + saga.finalize().await + }); + + let task3 = tokio::spawn(async move { + let db = mint3.localstore(); + let pubsub = mint3.pubsub_manager(); + let saga = SwapSaga::new(&*mint3, db, pubsub); + + let saga = saga + .setup_swap(&proofs3, &output_blinded_messages_3, None, verification3) + .await?; + let saga = saga.sign_outputs().await?; + saga.finalize().await + }); + + let results = tokio::try_join!(task1, task2, task3).expect("Tasks should complete"); + + let mut success_count = 0; + let mut error_count = 0; + + for result in [results.0, results.1, results.2] { + match result { + Ok(_) => success_count += 1, + Err(_) => error_count += 1, + } + } + + assert_eq!(success_count, 1, "Only one concurrent swap should succeed"); + assert_eq!(error_count, 2, "Two concurrent swaps should fail"); + + let ys = input_proofs.ys().unwrap(); + let states = mint + .localstore() + .get_proofs_states(&ys) + .await + .expect("Failed to get proof states"); + + for state in states { + assert_eq!( + state.unwrap(), + State::Spent, + "Proofs should be marked as spent after successful swap" + ); + } +} + +/// Tests that compensations execute when finalize() fails during add_blind_signatures. +/// +/// # What This Tests +/// - Verify that compensations execute when finalize() fails at signature addition +/// - Verify that proofs are removed from database (compensation rollback) +/// - Verify that blinded messages are removed from database +/// - Verify that signatures are NOT persisted to database +/// - Transaction rollback + compensation cleanup both occur +/// +/// # Implementation +/// Uses TEST_FAIL_ADD_SIGNATURES environment variable to inject failure +/// at the signature addition step within the finalize transaction. +/// +/// # Success Criteria +/// - Finalize fails with error +/// - Proofs are removed from database after failure +/// - Blinded messages are removed after failure +/// - No signatures persisted to database +#[tokio::test] +async fn test_swap_saga_compensation_on_finalize_add_signatures_failure() { + let mint = create_test_mint().await.unwrap(); + let amount = Amount::from(100); + let (input_proofs, input_verification) = create_swap_inputs(&mint, amount).await; + let (output_blinded_messages, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + + let db = mint.localstore(); + let pubsub = mint.pubsub_manager(); + let saga = SwapSaga::new(&mint, db.clone(), pubsub); + + // Setup and sign should succeed + let saga = saga + .setup_swap( + &input_proofs, + &output_blinded_messages, + None, + input_verification, + ) + .await + .expect("Setup should succeed"); + + let saga = saga.sign_outputs().await.expect("Signing should succeed"); + + // Verify we're in Signed state + assert_eq!( + saga.state_data.signatures.len(), + output_blinded_messages.len() + ); + + // Enable test failure mode for ADD_SIGNATURES + std::env::set_var("TEST_FAIL_ADD_SIGNATURES", "1"); + + // Attempt finalize (should fail due to TEST_FAIL_ADD_SIGNATURES) + let result = saga.finalize().await; + + // Clean up environment variable immediately + std::env::remove_var("TEST_FAIL_ADD_SIGNATURES"); + + assert!(result.is_err(), "Finalize should fail"); + + // Verify compensation executed - proofs removed + let ys = input_proofs.ys().unwrap(); + let states_after = db.get_proofs_states(&ys).await.unwrap(); + assert!( + states_after.iter().all(|s| s.is_none()), + "Proofs should be removed by compensation" + ); + + // Verify signatures were NOT persisted (transaction rolled back) + let blinded_secrets: Vec<_> = output_blinded_messages + .iter() + .map(|bm| bm.blinded_secret) + .collect(); + let signatures = db.get_blind_signatures(&blinded_secrets).await.unwrap(); + assert!( + signatures.iter().all(|s| s.is_none()), + "Signatures should not be persisted after rollback" + ); +} + +/// Tests that compensations execute when finalize() fails during update_proofs_states. +/// +/// # What This Tests +/// - Verify that compensations execute when finalize() fails at proof state update +/// - Verify that proofs are removed from database (compensation rollback) +/// - Verify that blinded messages are removed from database +/// - Verify that signatures are NOT persisted to database +/// - Transaction rollback + compensation cleanup both occur +/// +/// # Implementation +/// Uses TEST_FAIL_UPDATE_PROOFS environment variable to inject failure +/// at the proof state update step within the finalize transaction. +/// +/// # Success Criteria +/// - Finalize fails with error +/// - Proofs are removed from database after failure +/// - Blinded messages are removed after failure +/// - No signatures persisted to database +#[tokio::test] +async fn test_swap_saga_compensation_on_finalize_update_proofs_failure() { + let mint = create_test_mint().await.unwrap(); + let amount = Amount::from(100); + let (input_proofs, input_verification) = create_swap_inputs(&mint, amount).await; + let (output_blinded_messages, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + + let db = mint.localstore(); + let pubsub = mint.pubsub_manager(); + let saga = SwapSaga::new(&mint, db.clone(), pubsub); + + // Setup and sign should succeed + let saga = saga + .setup_swap( + &input_proofs, + &output_blinded_messages, + None, + input_verification, + ) + .await + .expect("Setup should succeed"); + + let saga = saga.sign_outputs().await.expect("Signing should succeed"); + + // Verify we're in Signed state + assert_eq!( + saga.state_data.signatures.len(), + output_blinded_messages.len() + ); + + // Enable test failure mode for UPDATE_PROOFS + std::env::set_var("TEST_FAIL_UPDATE_PROOFS", "1"); + + // Attempt finalize (should fail due to TEST_FAIL_UPDATE_PROOFS) + let result = saga.finalize().await; + + // Clean up environment variable immediately + std::env::remove_var("TEST_FAIL_UPDATE_PROOFS"); + + assert!(result.is_err(), "Finalize should fail"); + + // Verify compensation executed - proofs removed + let ys = input_proofs.ys().unwrap(); + let states_after = db.get_proofs_states(&ys).await.unwrap(); + assert!( + states_after.iter().all(|s| s.is_none()), + "Proofs should be removed by compensation" + ); + + // Verify signatures were NOT persisted (transaction rolled back) + let blinded_secrets: Vec<_> = output_blinded_messages + .iter() + .map(|bm| bm.blinded_secret) + .collect(); + let signatures = db.get_blind_signatures(&blinded_secrets).await.unwrap(); + assert!( + signatures.iter().all(|s| s.is_none()), + "Signatures should not be persisted after rollback" + ); +} + +// ==================== PHASE 1: FOUNDATION TESTS ==================== +// These tests verify the basic saga persistence mechanism. + +/// Tests that saga is persisted to the database after setup. +/// +/// # What This Tests +/// - Saga is written to database during setup_swap() +/// - get_saga() can retrieve the persisted state +/// - State content is correct (operation_id, state, blinded_secrets, input_ys) +/// +/// # Success Criteria +/// - Saga exists in database after setup +/// - State matches SwapSagaState::SetupComplete +/// - All expected data is present and correct +#[tokio::test] +async fn test_saga_state_persistence_after_setup() { + let mint = create_test_mint().await.unwrap(); + let db = mint.localstore(); + + let amount = Amount::from(100); + let (input_proofs, verification) = create_swap_inputs(&mint, amount).await; + let (output_blinded_messages, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + + let pubsub = mint.pubsub_manager(); + let saga = SwapSaga::new(&mint, db.clone(), pubsub); + + let saga = saga + .setup_swap(&input_proofs, &output_blinded_messages, None, verification) + .await + .expect("Setup should succeed"); + + let operation_id = saga.operation.id(); + + // Verify saga exists in database + let saga = { + let mut tx = db.begin_transaction().await.unwrap(); + let result = tx.get_saga(operation_id).await.expect("Failed to get saga"); + tx.commit().await.unwrap(); + result.expect("Saga should exist after setup") + }; + + // Verify state is SetupComplete + use cdk_common::mint::{SagaStateEnum, SwapSagaState}; + assert_eq!( + saga.state, + SagaStateEnum::Swap(SwapSagaState::SetupComplete), + "Saga should be SetupComplete" + ); + + // Verify operation_id matches + assert_eq!(saga.operation_id, *operation_id); + + // Verify blinded_secrets are stored correctly + let expected_blinded_secrets: Vec<_> = output_blinded_messages + .iter() + .map(|bm| bm.blinded_secret) + .collect(); + assert_eq!(saga.blinded_secrets.len(), expected_blinded_secrets.len()); + for bs in &expected_blinded_secrets { + assert!( + saga.blinded_secrets.contains(bs), + "Blinded secret should be in saga" + ); + } + + // Verify input_ys are stored correctly + let expected_ys = input_proofs.ys().unwrap(); + assert_eq!(saga.input_ys.len(), expected_ys.len()); + for y in &expected_ys { + assert!(saga.input_ys.contains(y), "Input Y should be in saga"); + } +} + +/// Tests that saga is deleted after successful finalization. +/// +/// # What This Tests +/// - Saga exists after setup +/// - Saga still exists after signing +/// - Saga is DELETED after successful finalize +/// - get_incomplete_sagas() returns empty after success +/// +/// # Success Criteria +/// - Saga deleted from database +/// - No incomplete sagas remain +#[tokio::test] +async fn test_saga_deletion_on_success() { + let mint = create_test_mint().await.unwrap(); + let db = mint.localstore(); + + let amount = Amount::from(100); + let (input_proofs, verification) = create_swap_inputs(&mint, amount).await; + let (output_blinded_messages, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + + let pubsub = mint.pubsub_manager(); + let saga = SwapSaga::new(&mint, db.clone(), pubsub); + + let saga = saga + .setup_swap(&input_proofs, &output_blinded_messages, None, verification) + .await + .expect("Setup should succeed"); + + let operation_id = *saga.operation.id(); + + // Verify saga exists after setup + let saga_after_setup = { + let mut tx = db.begin_transaction().await.unwrap(); + let result = tx + .get_saga(&operation_id) + .await + .expect("Failed to get saga"); + tx.commit().await.unwrap(); + result + }; + assert!(saga_after_setup.is_some(), "Saga should exist after setup"); + + let saga = saga.sign_outputs().await.expect("Signing should succeed"); + + // Verify saga still exists after signing + let saga_after_sign = { + let mut tx = db.begin_transaction().await.unwrap(); + let result = tx + .get_saga(&operation_id) + .await + .expect("Failed to get saga"); + tx.commit().await.unwrap(); + result + }; + assert!( + saga_after_sign.is_some(), + "Saga should still exist after signing" + ); + + let _response = saga.finalize().await.expect("Finalize should succeed"); + + // CRITICAL: Verify saga is DELETED after success + let saga_after_finalize = { + let mut tx = db.begin_transaction().await.unwrap(); + let result = tx + .get_saga(&operation_id) + .await + .expect("Failed to get saga"); + tx.commit().await.unwrap(); + result + }; + assert!( + saga_after_finalize.is_none(), + "Saga should be deleted after successful finalization" + ); + + // Verify no incomplete sagas exist + use cdk_common::mint::OperationKind; + let incomplete = db + .get_incomplete_sagas(OperationKind::Swap) + .await + .expect("Failed to get incomplete sagas"); + assert_eq!(incomplete.len(), 0, "No incomplete sagas should exist"); +} + +/// Tests querying incomplete sagas. +/// +/// # What This Tests +/// - get_incomplete_sagas() returns saga after setup +/// - get_incomplete_sagas() still returns saga after signing +/// - get_incomplete_sagas() returns empty after finalize +/// - Multiple incomplete sagas can be queried +/// +/// # Success Criteria +/// - Incomplete saga appears in query results +/// - Completed saga does not appear in query results +#[tokio::test] +async fn test_get_incomplete_sagas_basic() { + let mint = create_test_mint().await.unwrap(); + let db = mint.localstore(); + + let amount = Amount::from(100); + let (input_proofs_1, verification_1) = create_swap_inputs(&mint, amount).await; + let (output_blinded_messages_1, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + + let (input_proofs_2, verification_2) = create_swap_inputs(&mint, amount).await; + let (output_blinded_messages_2, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + + use cdk_common::mint::OperationKind; + + // Initially no incomplete sagas + let incomplete_initial = db + .get_incomplete_sagas(OperationKind::Swap) + .await + .expect("Failed to get incomplete sagas"); + assert_eq!(incomplete_initial.len(), 0); + + let pubsub = mint.pubsub_manager(); + + // Setup first saga + let saga_1 = SwapSaga::new(&mint, db.clone(), pubsub.clone()); + let saga_1 = saga_1 + .setup_swap( + &input_proofs_1, + &output_blinded_messages_1, + None, + verification_1, + ) + .await + .expect("Setup should succeed"); + let op_id_1 = *saga_1.operation.id(); + + // Should have 1 incomplete saga + let incomplete_after_1 = db + .get_incomplete_sagas(OperationKind::Swap) + .await + .expect("Failed to get incomplete sagas"); + assert_eq!(incomplete_after_1.len(), 1); + assert_eq!(incomplete_after_1[0].operation_id, op_id_1); + + // Setup second saga + let saga_2 = SwapSaga::new(&mint, db.clone(), pubsub.clone()); + let saga_2 = saga_2 + .setup_swap( + &input_proofs_2, + &output_blinded_messages_2, + None, + verification_2, + ) + .await + .expect("Setup should succeed"); + let op_id_2 = *saga_2.operation.id(); + + // Should have 2 incomplete sagas + let incomplete_after_2 = db + .get_incomplete_sagas(OperationKind::Swap) + .await + .expect("Failed to get incomplete sagas"); + assert_eq!(incomplete_after_2.len(), 2); + + // Finalize first saga + let saga_1 = saga_1.sign_outputs().await.expect("Signing should succeed"); + let _response_1 = saga_1.finalize().await.expect("Finalize should succeed"); + + // Should have 1 incomplete saga (second one still incomplete) + let incomplete_after_finalize = db + .get_incomplete_sagas(OperationKind::Swap) + .await + .expect("Failed to get incomplete sagas"); + assert_eq!(incomplete_after_finalize.len(), 1); + assert_eq!(incomplete_after_finalize[0].operation_id, op_id_2); + + // Finalize second saga + let saga_2 = saga_2.sign_outputs().await.expect("Signing should succeed"); + let _response_2 = saga_2.finalize().await.expect("Finalize should succeed"); + + // Should have 0 incomplete sagas + let incomplete_final = db + .get_incomplete_sagas(OperationKind::Swap) + .await + .expect("Failed to get incomplete sagas"); + assert_eq!(incomplete_final.len(), 0); +} + +/// Tests detailed validation of saga content. +/// +/// # What This Tests +/// - Operation ID is correct +/// - Operation kind is correct +/// - State enum is correct +/// - Blinded secrets are all present +/// - Input Ys are all present +/// - Timestamps are reasonable (created_at, updated_at) +/// +/// # Success Criteria +/// - All fields match expected values +/// - Timestamps are within reasonable range +#[tokio::test] +async fn test_saga_content_validation() { + let mint = create_test_mint().await.unwrap(); + let db = mint.localstore(); + + let amount = Amount::from(100); + let (input_proofs, verification) = create_swap_inputs(&mint, amount).await; + let (output_blinded_messages, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + + let expected_ys: Vec<_> = input_proofs.ys().unwrap(); + let expected_blinded_secrets: Vec<_> = output_blinded_messages + .iter() + .map(|bm| bm.blinded_secret) + .collect(); + + let pubsub = mint.pubsub_manager(); + let saga = SwapSaga::new(&mint, db.clone(), pubsub); + + let saga = saga + .setup_swap(&input_proofs, &output_blinded_messages, None, verification) + .await + .expect("Setup should succeed"); + + let operation_id = *saga.operation.id(); + + // Query saga + let saga = { + let mut tx = db.begin_transaction().await.unwrap(); + let result = tx + .get_saga(&operation_id) + .await + .expect("Failed to get saga"); + tx.commit().await.unwrap(); + result.expect("Saga should exist after setup") + }; + + // Validate content + use cdk_common::mint::{OperationKind, SagaStateEnum, SwapSagaState}; + assert_eq!(saga.operation_id, operation_id); + assert_eq!(saga.operation_kind, OperationKind::Swap); + assert_eq!( + saga.state, + SagaStateEnum::Swap(SwapSagaState::SetupComplete) + ); + + // Validate blinded secrets + assert_eq!(saga.blinded_secrets.len(), expected_blinded_secrets.len()); + for bs in &expected_blinded_secrets { + assert!(saga.blinded_secrets.contains(bs)); + } + + // Validate input Ys + assert_eq!(saga.input_ys.len(), expected_ys.len()); + for y in &expected_ys { + assert!(saga.input_ys.contains(y)); + } + + // Validate timestamps + use cdk_common::util::unix_time; + let now = unix_time(); + assert!( + saga.created_at <= now, + "created_at should be <= current time" + ); + assert!( + saga.updated_at <= now, + "updated_at should be <= current time" + ); + assert!( + saga.created_at <= saga.updated_at, + "created_at should be <= updated_at" + ); +} + +/// Tests that saga updates are persisted correctly. +/// +/// # What This Tests +/// - Saga persisted after setup +/// - updated_at timestamp changes after state updates +/// - Other fields remain unchanged during updates +/// +/// # Note +/// Currently sign_outputs() does NOT update saga in the database +/// (the "signed" state is not persisted). This test documents that behavior. +/// +/// # Success Criteria +/// - State exists after setup +/// - If state is updated, updated_at increases +/// - Other fields remain consistent +#[tokio::test] +async fn test_saga_state_updates_persisted() { + let mint = create_test_mint().await.unwrap(); + let db = mint.localstore(); + + let amount = Amount::from(100); + let (input_proofs, verification) = create_swap_inputs(&mint, amount).await; + let (output_blinded_messages, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + + let pubsub = mint.pubsub_manager(); + let saga = SwapSaga::new(&mint, db.clone(), pubsub); + + let saga = saga + .setup_swap(&input_proofs, &output_blinded_messages, None, verification) + .await + .expect("Setup should succeed"); + + let operation_id = *saga.operation.id(); + + // Query saga + let state_after_setup = { + let mut tx = db.begin_transaction().await.unwrap(); + let result = tx + .get_saga(&operation_id) + .await + .expect("Failed to get saga"); + tx.commit().await.unwrap(); + result.expect("Saga should exist after setup") + }; + + use cdk_common::mint::{SagaStateEnum, SwapSagaState}; + assert_eq!( + state_after_setup.state, + SagaStateEnum::Swap(SwapSagaState::SetupComplete) + ); + let initial_created_at = state_after_setup.created_at; + let initial_updated_at = state_after_setup.updated_at; + + // Small delay to ensure timestamp would change if updated + tokio::time::sleep(std::time::Duration::from_millis(10)).await; + + let saga = saga.sign_outputs().await.expect("Signing should succeed"); + + // Query saga + let state_after_sign = { + let mut tx = db.begin_transaction().await.unwrap(); + let result = tx + .get_saga(&operation_id) + .await + .expect("Failed to get saga"); + tx.commit().await.unwrap(); + result.expect("Saga should exist after setup") + }; + + // State should still be SetupComplete (not updated to Signed) + assert_eq!( + state_after_sign.state, + SagaStateEnum::Swap(SwapSagaState::SetupComplete), + "Saga remains SetupComplete (signing doesn't update DB)" + ); + + // Verify other fields unchanged + assert_eq!(state_after_sign.operation_id, operation_id); + assert_eq!( + state_after_sign.blinded_secrets, + state_after_setup.blinded_secrets + ); + assert_eq!(state_after_sign.input_ys, state_after_setup.input_ys); + assert_eq!(state_after_sign.created_at, initial_created_at); + + // updated_at might not change since state wasn't updated + assert_eq!(state_after_sign.updated_at, initial_updated_at); + + // Finalize and verify state is deleted (not updated) + let _response = saga.finalize().await.expect("Finalize should succeed"); + + // Query saga + let state_after_finalize = { + let mut tx = db.begin_transaction().await.unwrap(); + let result = tx + .get_saga(&operation_id) + .await + .expect("Failed to get saga"); + tx.commit().await.unwrap(); + + result + }; + + assert!( + state_after_finalize.is_none(), + "Saga should be deleted after finalize" + ); +} + +// ==================== STARTUP RECOVERY TESTS ==================== +// These tests verify the `recover_from_bad_swaps()` startup check that +// cleans up orphaned swap state when the mint restarts. + +/// Tests startup recovery when saga is dropped before signing. +/// +/// # What This Tests +/// - Saga dropped after setup (proofs PENDING, no signatures) +/// - recover_from_bad_swaps() removes the proofs +/// - Blinded messages are removed +/// - Same proofs can be used in a new swap after recovery +/// +/// # Recovery Behavior +/// When no blind signatures exist for an operation_id: +/// - Proofs are removed from database +/// - Blinded messages are removed +/// - User can retry the swap with same proofs +/// +/// # Flow +/// 1. Setup swap (proofs marked PENDING) +/// 2. Drop saga without signing +/// 3. Call recover_from_bad_swaps() (simulates mint restart) +/// 4. Verify proofs removed +/// 5. Verify can use same proofs in new swap +/// +/// # Success Criteria +/// - Recovery removes proofs completely +/// - Blinded messages removed +/// - Second swap with same proofs succeeds +#[tokio::test] +async fn test_startup_recovery_saga_dropped_before_signing() { + let mint = create_test_mint().await.unwrap(); + let amount = Amount::from(100); + let (input_proofs, input_verification) = create_swap_inputs(&mint, amount).await; + let (output_blinded_messages, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + + let db = mint.localstore(); + let ys = input_proofs.ys().unwrap(); + + // Setup swap and drop without signing + { + let pubsub = mint.pubsub_manager(); + let saga = SwapSaga::new(&mint, db.clone(), pubsub); + + let _saga = saga + .setup_swap( + &input_proofs, + &output_blinded_messages, + None, + input_verification.clone(), + ) + .await + .expect("Setup should succeed"); + + // Verify proofs are PENDING + let states = db.get_proofs_states(&ys).await.unwrap(); + assert!(states.iter().all(|s| s == &Some(State::Pending))); + + // Saga dropped here without signing + } + + // Proofs still PENDING after drop (no auto-cleanup) + let states_before_recovery = db.get_proofs_states(&ys).await.unwrap(); + assert!(states_before_recovery + .iter() + .all(|s| s == &Some(State::Pending))); + + // Simulate mint restart - run recovery + mint.stop().await.expect("Recovery should succeed"); + mint.start().await.expect("Recovery should succeed"); + + // Verify proofs are REMOVED (not just state cleared) + let states_after_recovery = db.get_proofs_states(&ys).await.unwrap(); + assert!( + states_after_recovery.iter().all(|s| s.is_none()), + "Proofs should be removed after recovery (no signatures exist)" + ); + + // Verify we can now use the same proofs in a new swap + let (new_output_blinded_messages, _) = + create_test_blinded_messages(&mint, amount).await.unwrap(); + + let pubsub = mint.pubsub_manager(); + let new_saga = SwapSaga::new(&mint, db, pubsub); + + let new_saga = new_saga + .setup_swap( + &input_proofs, + &new_output_blinded_messages, + None, + input_verification, + ) + .await + .expect("Second swap should succeed after recovery"); + + let new_saga = new_saga + .sign_outputs() + .await + .expect("Signing should succeed"); + + let _response = new_saga.finalize().await.expect("Finalize should succeed"); + + // Verify proofs are now SPENT + let final_states = mint.localstore().get_proofs_states(&ys).await.unwrap(); + assert!(final_states.iter().all(|s| s == &Some(State::Spent))); +} + +/// Tests startup recovery when saga is dropped after signing. +/// +/// # What This Tests +/// - Saga dropped after signing but before finalize +/// - Signatures exist in memory but were never persisted to database +/// - recover_from_bad_swaps() removes the proofs (no signatures in DB) +/// - Same proofs can be used in a new swap after recovery +/// +/// # Recovery Behavior +/// When no blind signatures exist in database for an operation_id: +/// - Proofs are removed from database +/// - User can retry the swap +/// +/// Note: Signatures from sign_outputs() are in memory only. They're only +/// persisted during finalize(). So a dropped saga after signing has no +/// signatures in the database. +/// +/// # Flow +/// 1. Setup swap and sign outputs +/// 2. Drop saga without finalize (signatures lost) +/// 3. Call recover_from_bad_swaps() +/// 4. Verify proofs removed +/// 5. Verify can use same proofs in new swap +/// +/// # Success Criteria +/// - Recovery removes proofs completely +/// - No signatures in database (never persisted) +/// - Second swap with same proofs succeeds +#[tokio::test] +async fn test_startup_recovery_saga_dropped_after_signing() { + let mint = create_test_mint().await.unwrap(); + let amount = Amount::from(100); + let (input_proofs, input_verification) = create_swap_inputs(&mint, amount).await; + let (output_blinded_messages, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + + let db = mint.localstore(); + let ys = input_proofs.ys().unwrap(); + let blinded_secrets: Vec<_> = output_blinded_messages + .iter() + .map(|bm| bm.blinded_secret) + .collect(); + + // Setup swap, sign, and drop without finalize + { + let pubsub = mint.pubsub_manager(); + let saga = SwapSaga::new(&mint, db.clone(), pubsub); + + let saga = saga + .setup_swap( + &input_proofs, + &output_blinded_messages, + None, + input_verification.clone(), + ) + .await + .expect("Setup should succeed"); + + let _saga = saga.sign_outputs().await.expect("Signing should succeed"); + + // Saga dropped here - signatures were in memory only, never persisted + } + + // Verify proofs still PENDING + let states_before = db.get_proofs_states(&ys).await.unwrap(); + assert!(states_before.iter().all(|s| s == &Some(State::Pending))); + + // Verify no signatures in database (they were only in memory) + let sigs_before = db.get_blind_signatures(&blinded_secrets).await.unwrap(); + assert!(sigs_before.iter().all(|s| s.is_none())); + + // Simulate mint restart - run recovery + mint.stop().await.expect("Recovery should succeed"); + mint.start().await.expect("Recovery should succeed"); + + // Verify proofs are REMOVED + let states_after = db.get_proofs_states(&ys).await.unwrap(); + assert!( + states_after.iter().all(|s| s.is_none()), + "Proofs should be removed (no signatures in DB)" + ); + + // Verify we can use the same proofs in a new swap + let (new_output_blinded_messages, _) = + create_test_blinded_messages(&mint, amount).await.unwrap(); + + let pubsub = mint.pubsub_manager(); + let new_saga = SwapSaga::new(&mint, db, pubsub); + + let new_saga = new_saga + .setup_swap( + &input_proofs, + &new_output_blinded_messages, + None, + input_verification, + ) + .await + .expect("Second swap should succeed after recovery"); + + let new_saga = new_saga + .sign_outputs() + .await + .expect("Signing should succeed"); + + let _response = new_saga.finalize().await.expect("Finalize should succeed"); +} + +/// Tests startup recovery with multiple abandoned operations. +/// +/// # What This Tests +/// - Multiple swap operations in different states +/// - recover_from_bad_swaps() processes all operations correctly +/// - Each operation is handled according to its state +/// +/// # Test Scenario +/// - Operation A: Dropped after setup (no signatures) → proofs removed +/// - Operation B: Dropped after signing (signatures not persisted) → proofs removed +/// - Operation C: Completed successfully (has signatures, SPENT) → untouched +/// +/// # Success Criteria +/// - Operation A proofs removed +/// - Operation B proofs removed +/// - Operation C proofs remain SPENT +/// - All operations processed in single recovery call +#[tokio::test] +async fn test_startup_recovery_multiple_operations() { + let mint = create_test_mint().await.unwrap(); + let amount = Amount::from(100); + + // Create three separate sets of proofs for three operations + let (proofs_a, verification_a) = create_swap_inputs(&mint, amount).await; + let (proofs_b, verification_b) = create_swap_inputs(&mint, amount).await; + let (proofs_c, verification_c) = create_swap_inputs(&mint, amount).await; + + let (outputs_a, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + let (outputs_b, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + let (outputs_c, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + + let db = mint.localstore(); + let pubsub = mint.pubsub_manager(); + + let ys_a = proofs_a.ys().unwrap(); + let ys_b = proofs_b.ys().unwrap(); + let ys_c = proofs_c.ys().unwrap(); + + // Operation A: Setup only (dropped before signing) + { + let saga_a = SwapSaga::new(&mint, db.clone(), pubsub.clone()); + let _saga_a = saga_a + .setup_swap(&proofs_a, &outputs_a, None, verification_a) + .await + .expect("Operation A setup should succeed"); + // Dropped without signing + } + + // Operation B: Setup + Sign (dropped before finalize) + { + let saga_b = SwapSaga::new(&mint, db.clone(), pubsub.clone()); + let saga_b = saga_b + .setup_swap(&proofs_b, &outputs_b, None, verification_b) + .await + .expect("Operation B setup should succeed"); + let _saga_b = saga_b + .sign_outputs() + .await + .expect("Operation B signing should succeed"); + // Dropped without finalize + } + + // Operation C: Complete successfully + { + let saga_c = SwapSaga::new(&mint, db.clone(), pubsub.clone()); + let saga_c = saga_c + .setup_swap(&proofs_c, &outputs_c, None, verification_c) + .await + .expect("Operation C setup should succeed"); + let saga_c = saga_c + .sign_outputs() + .await + .expect("Operation C signing should succeed"); + let _response = saga_c + .finalize() + .await + .expect("Operation C finalize should succeed"); + } + + // Verify states before recovery + let states_a_before = db.get_proofs_states(&ys_a).await.unwrap(); + let states_b_before = db.get_proofs_states(&ys_b).await.unwrap(); + let states_c_before = db.get_proofs_states(&ys_c).await.unwrap(); + + assert!(states_a_before.iter().all(|s| s == &Some(State::Pending))); + assert!(states_b_before.iter().all(|s| s == &Some(State::Pending))); + assert!(states_c_before.iter().all(|s| s == &Some(State::Spent))); + + // Simulate mint restart - run recovery + mint.stop().await.expect("Recovery should succeed"); + mint.start().await.expect("Recovery should succeed"); + + // Verify states after recovery + let states_a_after = db.get_proofs_states(&ys_a).await.unwrap(); + let states_b_after = db.get_proofs_states(&ys_b).await.unwrap(); + let states_c_after = db.get_proofs_states(&ys_c).await.unwrap(); + + assert!( + states_a_after.iter().all(|s| s.is_none()), + "Operation A proofs should be removed (no signatures)" + ); + assert!( + states_b_after.iter().all(|s| s.is_none()), + "Operation B proofs should be removed (no signatures in DB)" + ); + assert!( + states_c_after.iter().all(|s| s == &Some(State::Spent)), + "Operation C proofs should remain SPENT (completed successfully)" + ); +} + +/// Tests startup recovery with operation ID uniqueness and tracking. +/// +/// # What This Tests +/// - Multiple concurrent swaps get unique operation_ids +/// - Proofs are correctly associated with their operation_ids +/// - Recovery can distinguish between different operations +/// - Each operation is tracked independently +/// +/// # Flow +/// 1. Create multiple swaps concurrently +/// 2. Drop all sagas without finalize +/// 3. Verify proofs are associated with different operations +/// 4. Run recovery +/// 5. Verify all operations cleaned up correctly +/// +/// # Success Criteria +/// - Each swap has unique operation_id +/// - Proofs correctly tracked per operation +/// - Recovery processes each operation independently +/// - All proofs removed after recovery +#[tokio::test] +async fn test_operation_id_uniqueness_and_tracking() { + let mint = Arc::new(create_test_mint().await.unwrap()); + let amount = Amount::from(100); + + // Create three separate sets of proofs + let (proofs_1, verification_1) = create_swap_inputs(&mint, amount).await; + let (proofs_2, verification_2) = create_swap_inputs(&mint, amount).await; + let (proofs_3, verification_3) = create_swap_inputs(&mint, amount).await; + + let (outputs_1, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + let (outputs_2, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + let (outputs_3, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + + let db = mint.localstore(); + + let ys_1 = proofs_1.ys().unwrap(); + let ys_2 = proofs_2.ys().unwrap(); + let ys_3 = proofs_3.ys().unwrap(); + + // Create all three swaps and drop without finalize + { + let pubsub = mint.pubsub_manager(); + + let saga_1 = SwapSaga::new(&*mint, db.clone(), pubsub.clone()); + let _saga_1 = saga_1 + .setup_swap(&proofs_1, &outputs_1, None, verification_1) + .await + .expect("Swap 1 setup should succeed"); + + let saga_2 = SwapSaga::new(&*mint, db.clone(), pubsub.clone()); + let _saga_2 = saga_2 + .setup_swap(&proofs_2, &outputs_2, None, verification_2) + .await + .expect("Swap 2 setup should succeed"); + + let saga_3 = SwapSaga::new(&*mint, db.clone(), pubsub.clone()); + let _saga_3 = saga_3 + .setup_swap(&proofs_3, &outputs_3, None, verification_3) + .await + .expect("Swap 3 setup should succeed"); + + // All sagas dropped without finalize + } + + // Verify all proofs are PENDING + let states_1 = db.get_proofs_states(&ys_1).await.unwrap(); + let states_2 = db.get_proofs_states(&ys_2).await.unwrap(); + let states_3 = db.get_proofs_states(&ys_3).await.unwrap(); + + assert!(states_1.iter().all(|s| s == &Some(State::Pending))); + assert!(states_2.iter().all(|s| s == &Some(State::Pending))); + assert!(states_3.iter().all(|s| s == &Some(State::Pending))); + + // Simulate mint restart - run recovery + mint.stop().await.expect("Recovery should succeed"); + mint.start().await.expect("Recovery should succeed"); + + // Verify all proofs removed + let states_1_after = db.get_proofs_states(&ys_1).await.unwrap(); + let states_2_after = db.get_proofs_states(&ys_2).await.unwrap(); + let states_3_after = db.get_proofs_states(&ys_3).await.unwrap(); + + assert!( + states_1_after.iter().all(|s| s.is_none()), + "Swap 1 proofs should be removed" + ); + assert!( + states_2_after.iter().all(|s| s.is_none()), + "Swap 2 proofs should be removed" + ); + assert!( + states_3_after.iter().all(|s| s.is_none()), + "Swap 3 proofs should be removed" + ); + + // Verify each set of proofs can now be used in new swaps + let (new_outputs_1, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + let verification = create_verification(amount); + + let pubsub = mint.pubsub_manager(); + let new_saga = SwapSaga::new(&*mint, db, pubsub); + + let result = new_saga + .setup_swap(&proofs_1, &new_outputs_1, None, verification) + .await; + + assert!( + result.is_ok(), + "Should be able to reuse proofs after recovery" + ); +} + +// ==================== PHASE 2: CRASH RECOVERY TESTS ==================== +// These tests verify crash recovery using saga persistence. + +/// Tests crash recovery without calling compensate_all(). +/// +/// # What This Tests +/// - Saga dropped WITHOUT calling compensate_all() (simulates process crash) +/// - Saga persists in database after crash +/// - Proofs remain PENDING after crash (not cleaned up) +/// - Recovery mechanism finds incomplete saga via get_incomplete_sagas() +/// - Recovery cleans up orphaned state (proofs, blinded messages, saga) +/// +/// # This Is The PRIMARY USE CASE for Saga Persistence +/// The in-memory compensation mechanism only works if the process stays alive. +/// When the process crashes, we lose in-memory compensations and must rely +/// on persisted saga to recover. +/// +/// # Success Criteria +/// - Saga exists after crash +/// - Proofs are PENDING after crash (compensation didn't run) +/// - Recovery removes proofs +/// - Recovery removes blinded messages +/// - Recovery deletes saga +#[tokio::test] +async fn test_crash_recovery_without_compensation() { + let mint = create_test_mint().await.unwrap(); + let db = mint.localstore(); + + let amount = Amount::from(100); + let (input_proofs, verification) = create_swap_inputs(&mint, amount).await; + let (output_blinded_messages, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + + let operation_id; + let ys = input_proofs.ys().unwrap(); + let _blinded_secrets: Vec<_> = output_blinded_messages + .iter() + .map(|bm| bm.blinded_secret) + .collect(); + + // Simulate crash: setup swap, then drop WITHOUT calling compensate_all() + { + let pubsub = mint.pubsub_manager(); + let saga = SwapSaga::new(&mint, db.clone(), pubsub); + + let saga = saga + .setup_swap(&input_proofs, &output_blinded_messages, None, verification) + .await + .expect("Setup should succeed"); + + operation_id = *saga.operation.id(); + + // CRITICAL: Drop saga WITHOUT calling compensate_all() + // This simulates a crash where in-memory compensations are lost + drop(saga); + } + + // Verify saga still exists in database (persisted during setup) + let saga = { + let mut tx = db.begin_transaction().await.unwrap(); + let result = tx + .get_saga(&operation_id) + .await + .expect("Failed to get saga"); + tx.commit().await.unwrap(); + result + }; + assert!(saga.is_some(), "Saga should persist after crash"); + + // Verify proofs are still Pending (compensation didn't run) + let states = db.get_proofs_states(&ys).await.unwrap(); + assert!( + states.iter().all(|s| s == &Some(State::Pending)), + "Proofs should still be Pending after crash (compensation didn't run)" + ); + + // Note: We cannot directly verify blinded messages exist (no query method) + // but the recovery process will delete them along with proofs + + // Simulate mint restart - run recovery + mint.stop().await.expect("Stop should succeed"); + mint.start().await.expect("Start should succeed"); + + // Verify recovery cleaned up: + // 1. Proofs removed from database + let states_after = db.get_proofs_states(&ys).await.unwrap(); + assert!( + states_after.iter().all(|s| s.is_none()), + "Recovery should remove proofs" + ); + + // 2. Blinded messages removed (implicitly - no query method available) + + // 3. Saga deleted + let saga_after = { + let mut tx = db.begin_transaction().await.unwrap(); + let result = tx + .get_saga(&operation_id) + .await + .expect("Failed to get saga"); + tx.commit().await.unwrap(); + result + }; + assert!(saga_after.is_none(), "Recovery should delete saga"); +} + +/// Tests crash recovery after setup only (before signing). +/// +/// # What This Tests +/// - Saga in SetupComplete state when crashed +/// - No signatures exist in database +/// - Recovery removes all swap state +/// +/// # Success Criteria +/// - Saga exists before recovery +/// - Proofs are Pending before recovery +/// - Everything cleaned up after recovery +#[tokio::test] +async fn test_crash_recovery_after_setup_only() { + let mint = create_test_mint().await.unwrap(); + let db = mint.localstore(); + + let amount = Amount::from(100); + let (input_proofs, verification) = create_swap_inputs(&mint, amount).await; + let (output_blinded_messages, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + + let operation_id; + let ys = input_proofs.ys().unwrap(); + let _blinded_secrets: Vec<_> = output_blinded_messages + .iter() + .map(|bm| bm.blinded_secret) + .collect(); + + // Setup and crash + { + let pubsub = mint.pubsub_manager(); + let saga = SwapSaga::new(&mint, db.clone(), pubsub); + + let saga = saga + .setup_swap(&input_proofs, &output_blinded_messages, None, verification) + .await + .expect("Setup should succeed"); + + operation_id = *saga.operation.id(); + + // Verify saga was persisted + let saga = { + let mut tx = db.begin_transaction().await.unwrap(); + let result = tx.get_saga(&operation_id).await.unwrap(); + tx.commit().await.unwrap(); + result + }; + assert!(saga.is_some()); + + // Drop without compensation (crash) + drop(saga); + } + + // Verify state before recovery + let saga_before = { + let mut tx = db.begin_transaction().await.unwrap(); + let result = tx.get_saga(&operation_id).await.unwrap(); + tx.commit().await.unwrap(); + result + }; + assert!(saga_before.is_some()); + + let states_before = db.get_proofs_states(&ys).await.unwrap(); + assert!(states_before.iter().all(|s| s == &Some(State::Pending))); + + // Run recovery + mint.stop().await.expect("Stop should succeed"); + mint.start().await.expect("Start should succeed"); + + // Verify cleanup + let saga_after = { + let mut tx = db.begin_transaction().await.unwrap(); + let result = tx.get_saga(&operation_id).await.unwrap(); + tx.commit().await.unwrap(); + result + }; + assert!(saga_after.is_none(), "Saga should be deleted"); + + let states_after = db.get_proofs_states(&ys).await.unwrap(); + assert!( + states_after.iter().all(|s| s.is_none()), + "Proofs should be removed" + ); + + // Blinded messages also removed by recovery (no query method to verify) +} + +/// Tests crash recovery after signing (before finalize). +/// +/// # What This Tests +/// - Saga crashed after sign_outputs() but before finalize() +/// - Signatures were in memory only (never persisted) +/// - Recovery treats this the same as crashed after setup +/// - All state is cleaned up +/// +/// # Success Criteria +/// - Saga exists before recovery +/// - No signatures in database (never persisted) +/// - Everything cleaned up after recovery +#[tokio::test] +async fn test_crash_recovery_after_signing() { + let mint = create_test_mint().await.unwrap(); + let db = mint.localstore(); + + let amount = Amount::from(100); + let (input_proofs, verification) = create_swap_inputs(&mint, amount).await; + let (output_blinded_messages, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + + let operation_id; + let ys = input_proofs.ys().unwrap(); + let blinded_secrets: Vec<_> = output_blinded_messages + .iter() + .map(|bm| bm.blinded_secret) + .collect(); + + // Setup, sign, and crash + { + let pubsub = mint.pubsub_manager(); + let saga = SwapSaga::new(&mint, db.clone(), pubsub); + + let saga = saga + .setup_swap(&input_proofs, &output_blinded_messages, None, verification) + .await + .expect("Setup should succeed"); + + operation_id = *saga.operation.id(); + + let saga = saga.sign_outputs().await.expect("Signing should succeed"); + + // Verify we have signatures in memory + assert_eq!( + saga.state_data.signatures.len(), + output_blinded_messages.len() + ); + + // Drop without finalize (crash) - signatures lost + drop(saga); + } + + // Verify state before recovery + let saga_before = { + let mut tx = db.begin_transaction().await.unwrap(); + let result = tx.get_saga(&operation_id).await.unwrap(); + tx.commit().await.unwrap(); + result + }; + assert!(saga_before.is_some()); + + // Verify no signatures in database (they were in memory only) + let sigs_before = db.get_blind_signatures(&blinded_secrets).await.unwrap(); + assert!( + sigs_before.iter().all(|s| s.is_none()), + "Signatures should not be in DB (never persisted)" + ); + + // Run recovery + mint.stop().await.expect("Stop should succeed"); + mint.start().await.expect("Start should succeed"); + + // Verify cleanup + let saga_after = { + let mut tx = db.begin_transaction().await.unwrap(); + let result = tx.get_saga(&operation_id).await.unwrap(); + tx.commit().await.unwrap(); + result + }; + assert!(saga_after.is_none(), "Saga should be deleted"); + + let states_after = db.get_proofs_states(&ys).await.unwrap(); + assert!( + states_after.iter().all(|s| s.is_none()), + "Proofs should be removed" + ); + + // Blinded messages also removed by recovery (no query method to verify) +} + +/// Tests recovery with multiple incomplete sagas in different states. +/// +/// # What This Tests +/// - Multiple sagas can be incomplete simultaneously +/// - Recovery processes all incomplete sagas +/// - Each saga is handled correctly based on its state +/// +/// # Test Scenario +/// - Saga A: Setup only (incomplete) +/// - Saga B: Setup + Sign (incomplete, signatures lost) +/// - Saga C: Completed (should NOT be affected by recovery) +/// +/// # Success Criteria +/// - Saga A cleaned up +/// - Saga B cleaned up +/// - Saga C unaffected +#[tokio::test] +async fn test_recovery_multiple_incomplete_sagas() { + let mint = create_test_mint().await.unwrap(); + let db = mint.localstore(); + + let amount = Amount::from(100); + + // Create three sets of inputs/outputs + let (proofs_a, verification_a) = create_swap_inputs(&mint, amount).await; + let (proofs_b, verification_b) = create_swap_inputs(&mint, amount).await; + let (proofs_c, verification_c) = create_swap_inputs(&mint, amount).await; + + let (outputs_a, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + let (outputs_b, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + let (outputs_c, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + + let ys_a = proofs_a.ys().unwrap(); + let ys_b = proofs_b.ys().unwrap(); + let ys_c = proofs_c.ys().unwrap(); + + let op_id_a; + let op_id_b; + let op_id_c; + + // Saga A: Setup only, then crash + { + let pubsub = mint.pubsub_manager(); + let saga = SwapSaga::new(&mint, db.clone(), pubsub); + let saga = saga + .setup_swap(&proofs_a, &outputs_a, None, verification_a) + .await + .expect("Setup A should succeed"); + op_id_a = *saga.operation.id(); + drop(saga); + } + + // Saga B: Setup + Sign, then crash + { + let pubsub = mint.pubsub_manager(); + let saga = SwapSaga::new(&mint, db.clone(), pubsub); + let saga = saga + .setup_swap(&proofs_b, &outputs_b, None, verification_b) + .await + .expect("Setup B should succeed"); + op_id_b = *saga.operation.id(); + let saga = saga.sign_outputs().await.expect("Sign B should succeed"); + drop(saga); + } + + // Saga C: Complete successfully + { + let pubsub = mint.pubsub_manager(); + let saga = SwapSaga::new(&mint, db.clone(), pubsub); + let saga = saga + .setup_swap(&proofs_c, &outputs_c, None, verification_c) + .await + .expect("Setup C should succeed"); + op_id_c = *saga.operation.id(); + let saga = saga.sign_outputs().await.expect("Sign C should succeed"); + let _response = saga.finalize().await.expect("Finalize C should succeed"); + } + + // Verify state before recovery + use cdk_common::mint::OperationKind; + let incomplete_before = db.get_incomplete_sagas(OperationKind::Swap).await.unwrap(); + assert_eq!( + incomplete_before.len(), + 2, + "Should have 2 incomplete sagas (A and B)" + ); + + let states_a_before = db.get_proofs_states(&ys_a).await.unwrap(); + let states_b_before = db.get_proofs_states(&ys_b).await.unwrap(); + let states_c_before = db.get_proofs_states(&ys_c).await.unwrap(); + + assert!(states_a_before.iter().all(|s| s == &Some(State::Pending))); + assert!(states_b_before.iter().all(|s| s == &Some(State::Pending))); + assert!(states_c_before.iter().all(|s| s == &Some(State::Spent))); + + // Run recovery + mint.stop().await.expect("Stop should succeed"); + mint.start().await.expect("Start should succeed"); + + // Verify cleanup + let incomplete_after = db.get_incomplete_sagas(OperationKind::Swap).await.unwrap(); + assert_eq!( + incomplete_after.len(), + 0, + "No incomplete sagas after recovery" + ); + + // Saga A cleaned up + let saga_a = { + let mut tx = db.begin_transaction().await.unwrap(); + let result = tx.get_saga(&op_id_a).await.unwrap(); + tx.commit().await.unwrap(); + result + }; + assert!(saga_a.is_none()); + let states_a_after = db.get_proofs_states(&ys_a).await.unwrap(); + assert!(states_a_after.iter().all(|s| s.is_none())); + + // Saga B cleaned up + let saga_b = { + let mut tx = db.begin_transaction().await.unwrap(); + let result = tx.get_saga(&op_id_b).await.unwrap(); + tx.commit().await.unwrap(); + result + }; + assert!(saga_b.is_none()); + let states_b_after = db.get_proofs_states(&ys_b).await.unwrap(); + assert!(states_b_after.iter().all(|s| s.is_none())); + + // Saga C unaffected (still spent, saga was already deleted) + let saga_c = { + let mut tx = db.begin_transaction().await.unwrap(); + let result = tx.get_saga(&op_id_c).await.unwrap(); + tx.commit().await.unwrap(); + result + }; + assert!(saga_c.is_none(), "Completed saga was deleted"); + let states_c_after = db.get_proofs_states(&ys_c).await.unwrap(); + assert!( + states_c_after.iter().all(|s| s == &Some(State::Spent)), + "Completed saga proofs remain spent" + ); +} + +/// Tests that recovery is idempotent (can be run multiple times safely). +/// +/// # What This Tests +/// - Recovery can be run multiple times without errors +/// - Second recovery run is a no-op +/// - State remains consistent after multiple recoveries +/// +/// # Success Criteria +/// - First recovery cleans up incomplete saga +/// - Second recovery succeeds (no incomplete sagas to process) +/// - State is consistent after both runs +#[tokio::test] +async fn test_recovery_idempotence() { + let mint = create_test_mint().await.unwrap(); + let db = mint.localstore(); + + let amount = Amount::from(100); + let (input_proofs, verification) = create_swap_inputs(&mint, amount).await; + let (output_blinded_messages, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + + let operation_id; + let ys = input_proofs.ys().unwrap(); + + // Create incomplete saga + { + let pubsub = mint.pubsub_manager(); + let saga = SwapSaga::new(&mint, db.clone(), pubsub); + let saga = saga + .setup_swap(&input_proofs, &output_blinded_messages, None, verification) + .await + .expect("Setup should succeed"); + operation_id = *saga.operation.id(); + drop(saga); + } + + // Verify incomplete saga exists + let saga_before = { + let mut tx = db.begin_transaction().await.unwrap(); + let result = tx.get_saga(&operation_id).await.unwrap(); + tx.commit().await.unwrap(); + result + }; + assert!(saga_before.is_some()); + + // First recovery + mint.stop().await.expect("First stop should succeed"); + mint.start().await.expect("First start should succeed"); + + // Verify cleanup + let saga_after_1 = { + let mut tx = db.begin_transaction().await.unwrap(); + let result = tx.get_saga(&operation_id).await.unwrap(); + tx.commit().await.unwrap(); + result + }; + assert!(saga_after_1.is_none()); + let states_after_1 = db.get_proofs_states(&ys).await.unwrap(); + assert!(states_after_1.iter().all(|s| s.is_none())); + + // Second recovery (should be idempotent - no work to do) + mint.stop().await.expect("Second stop should succeed"); + mint.start().await.expect("Second start should succeed"); + + // Verify state unchanged + let saga_after_2 = { + let mut tx = db.begin_transaction().await.unwrap(); + let result = tx.get_saga(&operation_id).await.unwrap(); + tx.commit().await.unwrap(); + result + }; + assert!(saga_after_2.is_none()); + let states_after_2 = db.get_proofs_states(&ys).await.unwrap(); + assert!(states_after_2.iter().all(|s| s.is_none())); + + // Third recovery for good measure + mint.stop().await.expect("Third stop should succeed"); + mint.start().await.expect("Third start should succeed"); + + let saga_after_3 = { + let mut tx = db.begin_transaction().await.unwrap(); + let result = tx.get_saga(&operation_id).await.unwrap(); + tx.commit().await.unwrap(); + result + }; + assert!(saga_after_3.is_none()); +} + +// ==================== PHASE 3: EDGE CASE TESTS ==================== +// These tests verify edge cases and error handling scenarios. + +/// Tests cleanup of orphaned saga (saga deletion fails but swap succeeds). +/// +/// # What This Tests +/// - Swap completes successfully (proofs marked SPENT) +/// - Saga deletion fails (simulated by test hook) +/// - Swap still succeeds (best-effort deletion) +/// - Saga remains orphaned in database +/// - Recovery detects orphaned saga (proofs already SPENT) +/// - Recovery deletes orphaned saga +/// +/// # Why This Matters +/// According to the implementation, saga deletion is best-effort. If it fails, +/// the swap should still succeed. The orphaned saga will be cleaned up +/// on next recovery. +/// +/// # Success Criteria +/// - Swap succeeds despite deletion failure +/// - Proofs are SPENT after swap +/// - Saga remains after swap (orphaned) +/// - Recovery cleans up orphaned saga +#[tokio::test] +async fn test_orphaned_saga_cleanup() { + let mint = create_test_mint().await.unwrap(); + let db = mint.localstore(); + + let amount = Amount::from(100); + let (input_proofs, verification) = create_swap_inputs(&mint, amount).await; + let (output_blinded_messages, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + + let pubsub = mint.pubsub_manager(); + let saga = SwapSaga::new(&mint, db.clone(), pubsub); + + let saga = saga + .setup_swap(&input_proofs, &output_blinded_messages, None, verification) + .await + .expect("Setup should succeed"); + + let operation_id = *saga.operation.id(); + let ys = input_proofs.ys().unwrap(); + + let saga = saga.sign_outputs().await.expect("Signing should succeed"); + + // Note: We cannot easily inject a failure for saga deletion within finalize + // because the deletion happens inside a database transaction and uses the + // transaction trait. For now, we'll test the recovery side: create a saga + // that completes, then manually verify recovery can handle scenarios where + // saga exists but proofs are already SPENT. + + let _response = saga.finalize().await.expect("Finalize should succeed"); + + // Verify swap succeeded (proofs SPENT) + let states = db.get_proofs_states(&ys).await.unwrap(); + assert!( + states.iter().all(|s| s == &Some(State::Spent)), + "Proofs should be SPENT after successful swap" + ); + + // In a real scenario with deletion failure, saga would remain. + // For this test, we'll verify that saga is properly deleted. + // TODO: Add failure injection for delete_saga to properly test this. + let saga = { + let mut tx = db.begin_transaction().await.unwrap(); + let result = tx.get_saga(&operation_id).await.unwrap(); + tx.commit().await.unwrap(); + result + }; + assert!( + saga.is_none(), + "Saga should be deleted after successful swap" + ); + + // If we had a way to inject deletion failure, we would: + // 1. Verify saga remains (orphaned) + // 2. Run recovery + // 3. Verify recovery detects proofs are SPENT + // 4. Verify recovery deletes orphaned saga +} + +/// Tests recovery with orphaned proofs (proofs without corresponding saga). +/// +/// # What This Tests +/// - Proofs exist in database without saga +/// - Recovery handles this gracefully (no crash) +/// - Proofs remain in their current state +/// +/// # Scenario +/// This could happen if: +/// - Manual database intervention removed saga but not proofs +/// - A bug caused saga deletion without proof cleanup +/// - Database corruption +/// +/// # Success Criteria +/// - Recovery runs without errors +/// - Proofs remain in database (recovery doesn't remove them without saga) +/// - No crashes or panics +#[tokio::test] +async fn test_recovery_with_orphaned_proofs() { + let mint = create_test_mint().await.unwrap(); + let db = mint.localstore(); + + let amount = Amount::from(100); + let (input_proofs, verification) = create_swap_inputs(&mint, amount).await; + let (output_blinded_messages, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + + let ys = input_proofs.ys().unwrap(); + + // Setup saga to get proofs into PENDING state + let operation_id = { + let pubsub = mint.pubsub_manager(); + let saga = SwapSaga::new(&mint, db.clone(), pubsub); + + let saga = saga + .setup_swap(&input_proofs, &output_blinded_messages, None, verification) + .await + .expect("Setup should succeed"); + + let op_id = *saga.operation.id(); + + // Drop saga (crash simulation) + drop(saga); + + op_id + }; + + // Verify proofs are PENDING and saga exists + let states_before = db.get_proofs_states(&ys).await.unwrap(); + assert!(states_before.iter().all(|s| s == &Some(State::Pending))); + + let saga_before = { + let mut tx = db.begin_transaction().await.unwrap(); + let result = tx.get_saga(&operation_id).await.unwrap(); + tx.commit().await.unwrap(); + result + }; + assert!(saga_before.is_some()); + + // Manually delete saga (simulating orphaned proofs scenario) + { + let mut tx = db.begin_transaction().await.unwrap(); + tx.delete_saga(&operation_id).await.unwrap(); + tx.commit().await.unwrap(); + } + + // Verify saga is gone but proofs remain + let saga_after_delete = { + let mut tx = db.begin_transaction().await.unwrap(); + let result = tx.get_saga(&operation_id).await.unwrap(); + tx.commit().await.unwrap(); + result + }; + assert!(saga_after_delete.is_none(), "Saga should be deleted"); + + let states_after_delete = db.get_proofs_states(&ys).await.unwrap(); + assert!( + states_after_delete + .iter() + .all(|s| s == &Some(State::Pending)), + "Proofs should still be PENDING (orphaned)" + ); + + // Run recovery - should handle gracefully + mint.stop().await.expect("Stop should succeed"); + mint.start().await.expect("Start should succeed"); + + // Verify recovery completed without errors + // Orphaned PENDING proofs without saga should remain (not cleaned up) + // This is by design - recovery only acts on incomplete sagas, not orphaned proofs + let states_after_recovery = db.get_proofs_states(&ys).await.unwrap(); + assert!( + states_after_recovery + .iter() + .all(|s| s == &Some(State::Pending)), + "Orphaned proofs remain PENDING (recovery doesn't clean up proofs without saga)" + ); + + // Note: In production, a separate cleanup mechanism (e.g., timeout-based) + // would be needed to handle such orphaned resources. Saga recovery only + // processes incomplete sagas that have saga. +} + +/// Tests recovery with partial state (missing blinded messages). +/// +/// # What This Tests +/// - Saga exists +/// - Proofs exist +/// - Blinded messages are missing (deleted manually) +/// - Recovery handles this gracefully +/// +/// # Scenario +/// This could occur due to: +/// - Partial transaction commit (unlikely with proper atomicity) +/// - Manual database intervention +/// - Database corruption +/// +/// # Success Criteria +/// - Recovery runs without errors +/// - Saga is cleaned up +/// - Proofs are removed +/// - No crashes due to missing blinded messages +#[tokio::test] +async fn test_recovery_with_partial_state() { + let mint = create_test_mint().await.unwrap(); + let db = mint.localstore(); + + let amount = Amount::from(100); + let (input_proofs, verification) = create_swap_inputs(&mint, amount).await; + let (output_blinded_messages, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + + let ys = input_proofs.ys().unwrap(); + let blinded_secrets: Vec<_> = output_blinded_messages + .iter() + .map(|bm| bm.blinded_secret) + .collect(); + + // Setup saga + let operation_id = { + let pubsub = mint.pubsub_manager(); + let saga = SwapSaga::new(&mint, db.clone(), pubsub); + + let saga = saga + .setup_swap(&input_proofs, &output_blinded_messages, None, verification) + .await + .expect("Setup should succeed"); + + let op_id = *saga.operation.id(); + + // Drop saga (crash simulation) + drop(saga); + + op_id + }; + + // Verify setup + let saga_before = { + let mut tx = db.begin_transaction().await.unwrap(); + let result = tx.get_saga(&operation_id).await.unwrap(); + tx.commit().await.unwrap(); + result + }; + assert!(saga_before.is_some()); + + let states_before = db.get_proofs_states(&ys).await.unwrap(); + assert!(states_before.iter().all(|s| s == &Some(State::Pending))); + + // Manually delete blinded messages (simulating partial state) + { + let mut tx = db.begin_transaction().await.unwrap(); + tx.delete_blinded_messages(&blinded_secrets).await.unwrap(); + tx.commit().await.unwrap(); + } + + // Verify blinded messages are gone but saga and proofs remain + // (Note: We can't directly query blinded messages to verify they're gone, + // but the recovery mechanism will attempt to delete them regardless) + + // Run recovery - should handle missing blinded messages gracefully + mint.stop().await.expect("Stop should succeed"); + mint.start().await.expect("Start should succeed"); + + // Verify recovery completed successfully + let saga_after = { + let mut tx = db.begin_transaction().await.unwrap(); + let result = tx.get_saga(&operation_id).await.unwrap(); + tx.commit().await.unwrap(); + result + }; + assert!(saga_after.is_none(), "Saga should be deleted"); + + let states_after = db.get_proofs_states(&ys).await.unwrap(); + assert!( + states_after.iter().all(|s| s.is_none()), + "Proofs should be removed" + ); + + // Recovery should succeed even if blinded messages were already gone +} + +/// Tests recovery when blinded messages are missing (but proofs and saga exist). +/// +/// # What This Tests +/// - Saga exists with blinded_secrets +/// - Proofs exist and are PENDING +/// - Blinded messages themselves are missing from database +/// - Recovery completes without errors +/// - Saga is cleaned up +/// - Proofs are removed +/// +/// # Success Criteria +/// - No errors when trying to delete missing blinded messages +/// - Recovery completes successfully +/// - All saga cleaned up +#[tokio::test] +async fn test_recovery_with_missing_blinded_messages() { + let mint = create_test_mint().await.unwrap(); + let db = mint.localstore(); + + let amount = Amount::from(100); + let (input_proofs, verification) = create_swap_inputs(&mint, amount).await; + let (output_blinded_messages, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + + let ys = input_proofs.ys().unwrap(); + let blinded_secrets: Vec<_> = output_blinded_messages + .iter() + .map(|bm| bm.blinded_secret) + .collect(); + + // Setup saga and crash + let operation_id = { + let pubsub = mint.pubsub_manager(); + let saga = SwapSaga::new(&mint, db.clone(), pubsub); + + let saga = saga + .setup_swap(&input_proofs, &output_blinded_messages, None, verification) + .await + .expect("Setup should succeed"); + + let op_id = *saga.operation.id(); + drop(saga); // Crash + + op_id + }; + + // Verify initial state + let saga = { + let mut tx = db.begin_transaction().await.unwrap(); + let result = tx.get_saga(&operation_id).await.unwrap(); + tx.commit().await.unwrap(); + result + }; + assert!(saga.is_some(), "Saga should exist"); + + // Manually delete blinded messages before recovery + { + let mut tx = db.begin_transaction().await.unwrap(); + tx.delete_blinded_messages(&blinded_secrets).await.unwrap(); + tx.commit().await.unwrap(); + } + + // Run recovery - should handle missing blinded messages gracefully + mint.stop().await.expect("Stop should succeed"); + mint.start() + .await + .expect("Start should succeed despite missing blinded messages"); + + // Verify cleanup + let saga_after = { + let mut tx = db.begin_transaction().await.unwrap(); + let result = tx.get_saga(&operation_id).await.unwrap(); + tx.commit().await.unwrap(); + result + }; + assert!(saga_after.is_none(), "Saga should be cleaned up"); + + let states_after = db.get_proofs_states(&ys).await.unwrap(); + assert!( + states_after.iter().all(|s| s.is_none()), + "Proofs should be removed" + ); +} + +/// Tests that saga deletion failure is handled gracefully during finalize. +/// +/// # What This Tests +/// - Swap completes successfully through finalize +/// - Even if saga deletion fails internally, swap succeeds +/// - Best-effort saga deletion doesn't fail the swap +/// +/// # Note +/// This test verifies the design decision that saga deletion is best-effort. +/// Currently we cannot easily inject deletion failures, so this test documents +/// the expected behavior and verifies normal deletion. +/// +/// # Success Criteria +/// - Swap completes successfully +/// - Saga is deleted (in normal case) +/// - If deletion fails (not testable yet), swap still succeeds +#[tokio::test] +async fn test_saga_deletion_failure_handling() { + let mint = create_test_mint().await.unwrap(); + let db = mint.localstore(); + + let amount = Amount::from(100); + let (input_proofs, verification) = create_swap_inputs(&mint, amount).await; + let (output_blinded_messages, _) = create_test_blinded_messages(&mint, amount).await.unwrap(); + + let pubsub = mint.pubsub_manager(); + let saga = SwapSaga::new(&mint, db.clone(), pubsub); + + let saga = saga + .setup_swap(&input_proofs, &output_blinded_messages, None, verification) + .await + .expect("Setup should succeed"); + + let operation_id = *saga.operation.id(); + let ys = input_proofs.ys().unwrap(); + + let saga = saga.sign_outputs().await.expect("Signing should succeed"); + + // In normal operation, deletion succeeds + let response = saga.finalize().await.expect("Finalize should succeed"); + + // Verify swap succeeded + assert_eq!( + response.signatures.len(), + output_blinded_messages.len(), + "Should have signatures for all outputs" + ); + + let states = db.get_proofs_states(&ys).await.unwrap(); + assert!( + states.iter().all(|s| s == &Some(State::Spent)), + "Proofs should be SPENT" + ); + + // Verify saga is deleted + let saga = { + let mut tx = db.begin_transaction().await.unwrap(); + let result = tx.get_saga(&operation_id).await.unwrap(); + tx.commit().await.unwrap(); + result + }; + assert!(saga.is_none(), "Saga should be deleted"); + + // TODO: Add test failure injection for delete_saga to verify that: + // 1. Swap still succeeds even if deletion fails + // 2. Orphaned saga remains + // 3. Recovery can clean it up later + // + // This would require adding a TEST_FAIL_DELETE_SAGA env var check in the + // database implementation's delete_saga method. +} diff --git a/crates/cdk/src/test_helpers/mint.rs b/crates/cdk/src/test_helpers/mint.rs new file mode 100644 index 000000000..37f7faba1 --- /dev/null +++ b/crates/cdk/src/test_helpers/mint.rs @@ -0,0 +1,218 @@ +#![cfg(test)] +//! Test helpers for creating test mints and related utilities + +use std::collections::{HashMap, HashSet}; +use std::str::FromStr; +use std::sync::Arc; +use std::time::Duration; + +use bip39::Mnemonic; +use cdk_common::amount::SplitTarget; +use cdk_common::dhke::construct_proofs; +use cdk_common::nuts::{BlindedMessage, CurrencyUnit, Id, PaymentMethod, PreMintSecrets, Proofs}; +use cdk_common::{ + Amount, MintQuoteBolt11Request, MintQuoteBolt11Response, MintQuoteState, MintRequest, +}; +use cdk_fake_wallet::FakeWallet; +use tokio::time::sleep; + +use crate::mint::{Mint, MintBuilder, MintMeltLimits}; +use crate::types::{FeeReserve, QuoteTTL}; +use crate::Error; + +#[cfg(test)] +pub(crate) fn should_fail_in_test() -> bool { + // Some condition that determines when to fail in tests + std::env::var("TEST_FAIL").is_ok() +} + +#[cfg(test)] +pub(crate) fn should_fail_for(operation: &str) -> bool { + // Check for specific failure modes using environment variables + // Format: TEST_FAIL_ + let var_name = format!("TEST_FAIL_{}", operation); + std::env::var(&var_name).is_ok() +} + +/// Creates and starts a test mint with in-memory storage and a fake Lightning backend. +/// +/// This mint can be used for unit tests without requiring external dependencies +/// like Lightning nodes or persistent databases. +/// +/// # Example +/// +/// ``` +/// use cdk::test_helpers::mint::create_test_mint; +/// +/// #[tokio::test] +/// async fn test_something() { +/// let mint = create_test_mint().await.unwrap(); +/// // Use the mint for testing +/// } +/// ``` +pub async fn create_test_mint() -> Result { + let db = Arc::new(cdk_sqlite::mint::memory::empty().await?); + + let mut mint_builder = MintBuilder::new(db.clone()); + + let fee_reserve = FeeReserve { + min_fee_reserve: 1.into(), + percent_fee_reserve: 1.0, + }; + + let ln_fake_backend = FakeWallet::new( + fee_reserve.clone(), + HashMap::default(), + HashSet::default(), + 2, + CurrencyUnit::Sat, + ); + + mint_builder + .add_payment_processor( + CurrencyUnit::Sat, + PaymentMethod::Bolt11, + MintMeltLimits::new(1, 10_000), + Arc::new(ln_fake_backend), + ) + .await?; + + let mnemonic = Mnemonic::generate(12).map_err(|e| Error::Custom(e.to_string()))?; + + mint_builder = mint_builder + .with_name("test mint".to_string()) + .with_description("test mint for unit tests".to_string()) + .with_urls(vec!["https://test-mint".to_string()]); + + let quote_ttl = QuoteTTL::new(10000, 10000); + + let mint = mint_builder + .build_with_seed(db.clone(), &mnemonic.to_seed_normalized("")) + .await?; + + mint.set_quote_ttl(quote_ttl).await?; + + mint.start().await?; + + Ok(mint) +} + +/// Creates test proofs by performing a mock mint operation. +/// +/// This helper creates valid proofs for the given amount by: +/// 1. Creating blinded messages +/// 2. Performing a swap to get signatures +/// 3. Constructing valid proofs from the signatures +/// +/// # Arguments +/// +/// * `mint` - The test mint to use for creating proofs +/// * `amount` - The total amount to create proofs for +pub async fn mint_test_proofs(mint: &Mint, amount: Amount) -> Result { + // Just use fund_mint_with_proofs which creates proofs via swap + let mint_quote: MintQuoteBolt11Response<_> = mint + .get_mint_quote( + MintQuoteBolt11Request { + amount, + unit: CurrencyUnit::Sat, + description: None, + pubkey: None, + } + .into(), + ) + .await? + .into(); + + loop { + let check: MintQuoteBolt11Response<_> = mint + .check_mint_quote(&cdk_common::QuoteId::from_str(&mint_quote.quote).unwrap()) + .await + .unwrap() + .into(); + + if check.state == MintQuoteState::Paid { + break; + } + + sleep(Duration::from_secs(1)).await; + } + + let keysets = mint + .get_active_keysets() + .get(&CurrencyUnit::Sat) + .unwrap() + .clone(); + + let keys = mint + .keyset_pubkeys(&keysets)? + .keysets + .first() + .unwrap() + .keys + .clone(); + + let fees: (u64, Vec) = ( + 0, + keys.iter().map(|a| a.0.to_u64()).collect::>().into(), + ); + + let premint_secrets = + PreMintSecrets::random(keysets, amount, &SplitTarget::None, &fees.into()).unwrap(); + + let request = MintRequest { + quote: mint_quote.quote, + outputs: premint_secrets.blinded_messages(), + signature: None, + }; + + let mint_res = mint + .process_mint_request(request.try_into().unwrap()) + .await?; + + Ok(construct_proofs( + mint_res.signatures, + premint_secrets.rs(), + premint_secrets.secrets(), + &keys, + )?) +} + +/// Creates test blinded messages for the given amount. +/// +/// This is useful for testing operations that require blinded messages as input. +/// +/// # Arguments +/// +/// * `mint` - The test mint (used to get the active keyset) +/// * `amount` - The total amount to create blinded messages for +/// +/// # Returns +/// +/// A tuple containing: +/// - Vector of blinded messages +/// - PreMintSecrets (needed to construct proofs later) +pub async fn create_test_blinded_messages( + mint: &Mint, + amount: Amount, +) -> Result<(Vec, PreMintSecrets), Error> { + let keyset_id = get_active_keyset_id(mint).await?; + let split_target = SplitTarget::default(); + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); + + let pre_mint = PreMintSecrets::random(keyset_id, amount, &split_target, &fee_and_amounts)?; + let blinded_messages = pre_mint.blinded_messages().to_vec(); + + Ok((blinded_messages, pre_mint)) +} + +/// Gets the active keyset ID from the mint. +pub async fn get_active_keyset_id(mint: &Mint) -> Result { + let keys = mint + .pubkeys() + .keysets + .first() + .ok_or(Error::Internal)? + .clone(); + keys.verify_id()?; + Ok(keys.id) +} diff --git a/crates/cdk/src/test_helpers/mod.rs b/crates/cdk/src/test_helpers/mod.rs new file mode 100644 index 000000000..08e0209a2 --- /dev/null +++ b/crates/cdk/src/test_helpers/mod.rs @@ -0,0 +1,10 @@ +#![cfg(test)] +//! Test helper utilities for CDK unit tests +//! +//! This module provides shared test utilities for creating test mints, wallets, +//! and test data without external dependencies (Lightning nodes, databases). +//! +//! These helpers are only compiled when running tests. + +#[cfg(feature = "mint")] +pub mod mint; From 344b81a69407c4e6f6ec466be7b3badcb39cf321 Mon Sep 17 00:00:00 2001 From: David Caseria Date: Fri, 24 Oct 2025 12:24:06 -0500 Subject: [PATCH 227/321] Update FFI Database Objects to Records (#1149) --- crates/cdk-ffi/src/database.rs | 4 +- crates/cdk-ffi/src/multi_mint_wallet.rs | 15 +- crates/cdk-ffi/src/postgres.rs | 2 +- crates/cdk-ffi/src/sqlite.rs | 2 +- crates/cdk-ffi/src/token.rs | 5 +- crates/cdk-ffi/src/types/proof.rs | 161 ++++++++++++------ crates/cdk-ffi/src/types/quote.rs | 125 +++----------- crates/cdk-ffi/src/types/subscription.rs | 12 +- crates/cdk-ffi/src/types/transaction.rs | 19 ++- crates/cdk-ffi/src/types/wallet.rs | 11 +- crates/cdk-ffi/src/wallet.rs | 51 +++--- .../tests/ffi_minting_integration.rs | 15 +- 12 files changed, 191 insertions(+), 231 deletions(-) diff --git a/crates/cdk-ffi/src/database.rs b/crates/cdk-ffi/src/database.rs index cdf6eb572..c87b1c554 100644 --- a/crates/cdk-ffi/src/database.rs +++ b/crates/cdk-ffi/src/database.rs @@ -450,7 +450,9 @@ impl CdkWalletDatabase for WalletDatabaseBridge { .into_iter() .map(|info| { Ok(cdk::types::ProofInfo { - proof: info.proof.inner.clone(), + proof: info.proof.try_into().map_err(|e: FfiError| { + cdk::cdk_database::Error::Database(e.to_string().into()) + })?, y: info.y.try_into().map_err(|e: FfiError| { cdk::cdk_database::Error::Database(e.to_string().into()) })?, diff --git a/crates/cdk-ffi/src/multi_mint_wallet.rs b/crates/cdk-ffi/src/multi_mint_wallet.rs index 06bf29745..0ca4eda56 100644 --- a/crates/cdk-ffi/src/multi_mint_wallet.rs +++ b/crates/cdk-ffi/src/multi_mint_wallet.rs @@ -175,10 +175,7 @@ impl MultiMintWallet { let proofs = self.inner.list_proofs().await?; let mut proofs_by_mint = HashMap::new(); for (mint_url, mint_proofs) in proofs { - let ffi_proofs: Vec> = mint_proofs - .into_iter() - .map(|p| Arc::new(p.into())) - .collect(); + let ffi_proofs: Vec = mint_proofs.into_iter().map(|p| p.into()).collect(); proofs_by_mint.insert(mint_url.to_string(), ffi_proofs); } Ok(proofs_by_mint) @@ -262,7 +259,7 @@ impl MultiMintWallet { .inner .mint(&cdk_mint_url, "e_id, conditions) .await?; - Ok(proofs.into_iter().map(|p| Arc::new(p.into())).collect()) + Ok(proofs.into_iter().map(|p| p.into()).collect()) } /// Wait for a mint quote to be paid and automatically mint the proofs @@ -288,7 +285,7 @@ impl MultiMintWallet { timeout_secs, ) .await?; - Ok(proofs.into_iter().map(|p| Arc::new(p.into())).collect()) + Ok(proofs.into_iter().map(|p| p.into()).collect()) } /// Get a melt quote from a specific mint @@ -346,7 +343,7 @@ impl MultiMintWallet { let result = self.inner.swap(amount.map(Into::into), conditions).await?; - Ok(result.map(|proofs| proofs.into_iter().map(|p| Arc::new(p.into())).collect())) + Ok(result.map(|proofs| proofs.into_iter().map(|p| p.into()).collect())) } /// List transactions from all mints @@ -437,7 +434,7 @@ impl MultiMintWallet { .inner .mint_blind_auth(&cdk_mint_url, amount.into()) .await?; - Ok(proofs.into_iter().map(|p| Arc::new(p.into())).collect()) + Ok(proofs.into_iter().map(|p| p.into()).collect()) } /// Get unspent auth proofs for a specific mint @@ -556,4 +553,4 @@ impl From for CdkMultiMintSendOptions { pub type BalanceMap = HashMap; /// Type alias for proofs by mint URL -pub type ProofsByMint = HashMap>>; +pub type ProofsByMint = HashMap>; diff --git a/crates/cdk-ffi/src/postgres.rs b/crates/cdk-ffi/src/postgres.rs index 4c46a69bb..975bd011d 100644 --- a/crates/cdk-ffi/src/postgres.rs +++ b/crates/cdk-ffi/src/postgres.rs @@ -237,7 +237,7 @@ impl WalletDatabase for WalletPostgresDatabase { .into_iter() .map(|info| { Ok::(cdk::types::ProofInfo { - proof: info.proof.inner.clone(), + proof: info.proof.try_into()?, y: info.y.try_into()?, mint_url: info.mint_url.try_into()?, state: info.state.into(), diff --git a/crates/cdk-ffi/src/sqlite.rs b/crates/cdk-ffi/src/sqlite.rs index b48bb36aa..945d0df31 100644 --- a/crates/cdk-ffi/src/sqlite.rs +++ b/crates/cdk-ffi/src/sqlite.rs @@ -272,7 +272,7 @@ impl WalletDatabase for WalletSqliteDatabase { .into_iter() .map(|info| { Ok::(cdk::types::ProofInfo { - proof: info.proof.inner.clone(), + proof: info.proof.try_into()?, y: info.y.try_into()?, mint_url: info.mint_url.try_into()?, state: info.state.into(), diff --git a/crates/cdk-ffi/src/token.rs b/crates/cdk-ffi/src/token.rs index 31a22e424..cce6ac7bb 100644 --- a/crates/cdk-ffi/src/token.rs +++ b/crates/cdk-ffi/src/token.rs @@ -75,10 +75,7 @@ impl Token { // For now, return empty keysets to get all proofs let empty_keysets = vec![]; let proofs = self.inner.proofs(&empty_keysets)?; - Ok(proofs - .into_iter() - .map(|p| std::sync::Arc::new(p.into())) - .collect()) + Ok(proofs.into_iter().map(|p| p.into()).collect()) } /// Convert token to raw bytes diff --git a/crates/cdk-ffi/src/types/proof.rs b/crates/cdk-ffi/src/types/proof.rs index e75e6c0ec..b5db3f97f 100644 --- a/crates/cdk-ffi/src/types/proof.rs +++ b/crates/cdk-ffi/src/types/proof.rs @@ -44,78 +44,126 @@ impl From for CdkState { } /// FFI-compatible Proof -#[derive(Debug, uniffi::Object)] +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] pub struct Proof { - pub(crate) inner: cdk::nuts::Proof, + /// Proof amount + pub amount: Amount, + /// Secret (as string) + pub secret: String, + /// Unblinded signature C (as hex string) + pub c: String, + /// Keyset ID (as hex string) + pub keyset_id: String, + /// Optional witness + pub witness: Option, + /// Optional DLEQ proof + pub dleq: Option, } impl From for Proof { fn from(proof: cdk::nuts::Proof) -> Self { - Self { inner: proof } + Self { + amount: proof.amount.into(), + secret: proof.secret.to_string(), + c: proof.c.to_string(), + keyset_id: proof.keyset_id.to_string(), + witness: proof.witness.map(|w| w.into()), + dleq: proof.dleq.map(|d| d.into()), + } } } -impl From for cdk::nuts::Proof { - fn from(proof: Proof) -> Self { - proof.inner - } -} +impl TryFrom for cdk::nuts::Proof { + type Error = FfiError; -#[uniffi::export] -impl Proof { - /// Get the amount - pub fn amount(&self) -> Amount { - self.inner.amount.into() - } + fn try_from(proof: Proof) -> Result { + use std::str::FromStr; - /// Get the secret as string - pub fn secret(&self) -> String { - self.inner.secret.to_string() - } + use cdk::nuts::Id; - /// Get the unblinded signature (C) as string - pub fn c(&self) -> String { - self.inner.c.to_string() + Ok(Self { + amount: proof.amount.into(), + secret: cdk::secret::Secret::from_str(&proof.secret) + .map_err(|e| FfiError::Serialization { msg: e.to_string() })?, + c: cdk::nuts::PublicKey::from_str(&proof.c) + .map_err(|e| FfiError::InvalidCryptographicKey { msg: e.to_string() })?, + keyset_id: Id::from_str(&proof.keyset_id) + .map_err(|e| FfiError::Serialization { msg: e.to_string() })?, + witness: proof.witness.map(|w| w.into()), + dleq: proof.dleq.map(|d| d.into()), + }) } +} - /// Get the keyset ID as string - pub fn keyset_id(&self) -> String { - self.inner.keyset_id.to_string() - } +/// Get the Y value (hash_to_curve of secret) for a proof +#[uniffi::export] +pub fn proof_y(proof: &Proof) -> Result { + // Convert to CDK proof to calculate Y + let cdk_proof: cdk::nuts::Proof = proof.clone().try_into()?; + Ok(cdk_proof.y()?.to_string()) +} - /// Get the witness - pub fn witness(&self) -> Option { - self.inner.witness.as_ref().map(|w| w.clone().into()) +/// Check if proof is active with given keyset IDs +#[uniffi::export] +pub fn proof_is_active(proof: &Proof, active_keyset_ids: Vec) -> bool { + use cdk::nuts::Id; + let ids: Vec = active_keyset_ids + .into_iter() + .filter_map(|id| Id::from_str(&id).ok()) + .collect(); + + // A proof is active if its keyset_id is in the active list + if let Ok(keyset_id) = Id::from_str(&proof.keyset_id) { + ids.contains(&keyset_id) + } else { + false } +} - /// Check if proof is active with given keyset IDs - pub fn is_active(&self, active_keyset_ids: Vec) -> bool { - use cdk::nuts::Id; - let ids: Vec = active_keyset_ids - .into_iter() - .filter_map(|id| Id::from_str(&id).ok()) - .collect(); - self.inner.is_active(&ids) - } +/// Check if proof has DLEQ proof +#[uniffi::export] +pub fn proof_has_dleq(proof: &Proof) -> bool { + proof.dleq.is_some() +} - /// Get the Y value (hash_to_curve of secret) - pub fn y(&self) -> Result { - Ok(self.inner.y()?.to_string()) - } +/// Verify HTLC witness on a proof +#[uniffi::export] +pub fn proof_verify_htlc(proof: &Proof) -> Result<(), FfiError> { + let cdk_proof: cdk::nuts::Proof = proof.clone().try_into()?; + cdk_proof + .verify_htlc() + .map_err(|e| FfiError::Generic { msg: e.to_string() }) +} - /// Get the DLEQ proof if present - pub fn dleq(&self) -> Option { - self.inner.dleq.as_ref().map(|d| d.clone().into()) - } +/// Verify DLEQ proof on a proof +#[uniffi::export] +pub fn proof_verify_dleq( + proof: &Proof, + mint_pubkey: super::keys::PublicKey, +) -> Result<(), FfiError> { + let cdk_proof: cdk::nuts::Proof = proof.clone().try_into()?; + let cdk_pubkey: cdk::nuts::PublicKey = mint_pubkey.try_into()?; + cdk_proof + .verify_dleq(cdk_pubkey) + .map_err(|e| FfiError::Generic { msg: e.to_string() }) +} + +/// Sign a P2PK proof with a secret key, returning a new signed proof +#[uniffi::export] +pub fn proof_sign_p2pk(proof: Proof, secret_key_hex: String) -> Result { + let mut cdk_proof: cdk::nuts::Proof = proof.try_into()?; + let secret_key = cdk::nuts::SecretKey::from_hex(&secret_key_hex) + .map_err(|e| FfiError::InvalidCryptographicKey { msg: e.to_string() })?; - /// Check if proof has DLEQ proof - pub fn has_dleq(&self) -> bool { - self.inner.dleq.is_some() - } + cdk_proof + .sign_p2pk(secret_key) + .map_err(|e| FfiError::Generic { msg: e.to_string() })?; + + Ok(cdk_proof.into()) } /// FFI-compatible Proofs (vector of Proof) -pub type Proofs = Vec>; +pub type Proofs = Vec; /// FFI-compatible DLEQ proof for proofs #[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] @@ -175,9 +223,12 @@ impl From for cdk::nuts::BlindSignatureDleq { } } -/// Helper functions for Proofs +/// Helper function to calculate total amount of proofs +#[uniffi::export] pub fn proofs_total_amount(proofs: &Proofs) -> Result { - let cdk_proofs: Vec = proofs.iter().map(|p| p.inner.clone()).collect(); + let cdk_proofs: Result, _> = + proofs.iter().map(|p| p.clone().try_into()).collect(); + let cdk_proofs = cdk_proofs?; use cdk::nuts::ProofsMethods; Ok(cdk_proofs.total_amount()?.into()) } @@ -420,7 +471,7 @@ impl TryFrom for cdk::nuts::SpendingConditions { #[derive(Debug, Clone, uniffi::Record)] pub struct ProofInfo { /// Proof - pub proof: std::sync::Arc, + pub proof: Proof, /// Y value (hash_to_curve of secret) pub y: super::keys::PublicKey, /// Mint URL @@ -436,7 +487,7 @@ pub struct ProofInfo { impl From for ProofInfo { fn from(info: cdk::types::ProofInfo) -> Self { Self { - proof: std::sync::Arc::new(info.proof.into()), + proof: info.proof.into(), y: info.y.into(), mint_url: info.mint_url.into(), state: info.state.into(), @@ -458,7 +509,7 @@ pub fn decode_proof_info(json: String) -> Result { pub fn encode_proof_info(info: ProofInfo) -> Result { // Convert to cdk::types::ProofInfo for serialization let cdk_info = cdk::types::ProofInfo { - proof: info.proof.inner.clone(), + proof: info.proof.try_into()?, y: info.y.try_into()?, mint_url: info.mint_url.try_into()?, state: info.state.into(), diff --git a/crates/cdk-ffi/src/types/quote.rs b/crates/cdk-ffi/src/types/quote.rs index e931008a5..7ee467094 100644 --- a/crates/cdk-ffi/src/types/quote.rs +++ b/crates/cdk-ffi/src/types/quote.rs @@ -77,30 +77,25 @@ impl TryFrom for cdk::wallet::MintQuote { } } -impl MintQuote { - /// Get total amount (amount + fees) - pub fn total_amount(&self) -> Amount { - if let Some(amount) = self.amount { - Amount::new(amount.value + self.amount_paid.value - self.amount_issued.value) - } else { - Amount::zero() - } - } - - /// Check if quote is expired - pub fn is_expired(&self, current_time: u64) -> bool { - current_time > self.expiry - } +/// Get total amount for a mint quote (amount paid) +#[uniffi::export] +pub fn mint_quote_total_amount(quote: &MintQuote) -> Result { + let cdk_quote: cdk::wallet::MintQuote = quote.clone().try_into()?; + Ok(cdk_quote.total_amount().into()) +} - /// Get amount that can be minted - pub fn amount_mintable(&self) -> Amount { - Amount::new(self.amount_paid.value - self.amount_issued.value) - } +/// Check if mint quote is expired +#[uniffi::export] +pub fn mint_quote_is_expired(quote: &MintQuote, current_time: u64) -> Result { + let cdk_quote: cdk::wallet::MintQuote = quote.clone().try_into()?; + Ok(cdk_quote.is_expired(current_time)) +} - /// Convert MintQuote to JSON string - pub fn to_json(&self) -> Result { - Ok(serde_json::to_string(self)?) - } +/// Get amount that can be minted from a mint quote +#[uniffi::export] +pub fn mint_quote_amount_mintable(quote: &MintQuote) -> Result { + let cdk_quote: cdk::wallet::MintQuote = quote.clone().try_into()?; + Ok(cdk_quote.amount_mintable().into()) } /// Decode MintQuote from JSON string @@ -117,7 +112,7 @@ pub fn encode_mint_quote(quote: MintQuote) -> Result { } /// FFI-compatible MintQuoteBolt11Response -#[derive(Debug, uniffi::Object)] +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] pub struct MintQuoteBolt11Response { /// Quote ID pub quote: String, @@ -149,46 +144,8 @@ impl From> for MintQuoteBolt11Respons } } -#[uniffi::export] -impl MintQuoteBolt11Response { - /// Get quote ID - pub fn quote(&self) -> String { - self.quote.clone() - } - - /// Get request string - pub fn request(&self) -> String { - self.request.clone() - } - - /// Get state - pub fn state(&self) -> QuoteState { - self.state.clone() - } - - /// Get expiry - pub fn expiry(&self) -> Option { - self.expiry - } - - /// Get amount - pub fn amount(&self) -> Option { - self.amount - } - - /// Get unit - pub fn unit(&self) -> Option { - self.unit.clone() - } - - /// Get pubkey - pub fn pubkey(&self) -> Option { - self.pubkey.clone() - } -} - /// FFI-compatible MeltQuoteBolt11Response -#[derive(Debug, uniffi::Object)] +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] pub struct MeltQuoteBolt11Response { /// Quote ID pub quote: String, @@ -222,50 +179,6 @@ impl From> for MeltQuoteBolt11Respons } } } - -#[uniffi::export] -impl MeltQuoteBolt11Response { - /// Get quote ID - pub fn quote(&self) -> String { - self.quote.clone() - } - - /// Get amount - pub fn amount(&self) -> Amount { - self.amount - } - - /// Get fee reserve - pub fn fee_reserve(&self) -> Amount { - self.fee_reserve - } - - /// Get state - pub fn state(&self) -> QuoteState { - self.state.clone() - } - - /// Get expiry - pub fn expiry(&self) -> u64 { - self.expiry - } - - /// Get payment preimage - pub fn payment_preimage(&self) -> Option { - self.payment_preimage.clone() - } - - /// Get request - pub fn request(&self) -> Option { - self.request.clone() - } - - /// Get unit - pub fn unit(&self) -> Option { - self.unit.clone() - } -} - /// FFI-compatible PaymentMethod #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, uniffi::Enum)] pub enum PaymentMethod { diff --git a/crates/cdk-ffi/src/types/subscription.rs b/crates/cdk-ffi/src/types/subscription.rs index ccd036bfa..b4a0aed9a 100644 --- a/crates/cdk-ffi/src/types/subscription.rs +++ b/crates/cdk-ffi/src/types/subscription.rs @@ -139,13 +139,9 @@ pub enum NotificationPayload { /// Proof state update ProofState { proof_states: Vec }, /// Mint quote update - MintQuoteUpdate { - quote: std::sync::Arc, - }, + MintQuoteUpdate { quote: MintQuoteBolt11Response }, /// Melt quote update - MeltQuoteUpdate { - quote: std::sync::Arc, - }, + MeltQuoteUpdate { quote: MeltQuoteBolt11Response }, } impl From> for NotificationPayload { @@ -156,12 +152,12 @@ impl From> for NotificationPayload { }, cdk::nuts::NotificationPayload::MintQuoteBolt11Response(quote_resp) => { NotificationPayload::MintQuoteUpdate { - quote: std::sync::Arc::new(quote_resp.into()), + quote: quote_resp.into(), } } cdk::nuts::NotificationPayload::MeltQuoteBolt11Response(quote_resp) => { NotificationPayload::MeltQuoteUpdate { - quote: std::sync::Arc::new(quote_resp.into()), + quote: quote_resp.into(), } } _ => { diff --git a/crates/cdk-ffi/src/types/transaction.rs b/crates/cdk-ffi/src/types/transaction.rs index 9c70c35d9..39c0aa216 100644 --- a/crates/cdk-ffi/src/types/transaction.rs +++ b/crates/cdk-ffi/src/types/transaction.rs @@ -106,6 +106,21 @@ pub fn encode_transaction(transaction: Transaction) -> Result Ok(serde_json::to_string(&transaction)?) } +/// Check if a transaction matches the given filter conditions +#[uniffi::export] +pub fn transaction_matches_conditions( + transaction: &Transaction, + mint_url: Option, + direction: Option, + unit: Option, +) -> Result { + let cdk_transaction: cdk::wallet::types::Transaction = transaction.clone().try_into()?; + let cdk_mint_url = mint_url.map(|url| url.try_into()).transpose()?; + let cdk_direction = direction.map(Into::into); + let cdk_unit = unit.map(Into::into); + Ok(cdk_transaction.matches_conditions(&cdk_mint_url, &cdk_direction, &cdk_unit)) +} + /// FFI-compatible TransactionDirection #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, uniffi::Enum)] pub enum TransactionDirection { @@ -163,7 +178,9 @@ impl TransactionId { /// Create from proofs pub fn from_proofs(proofs: &Proofs) -> Result { - let cdk_proofs: Vec = proofs.iter().map(|p| p.inner.clone()).collect(); + let cdk_proofs: Result, _> = + proofs.iter().map(|p| p.clone().try_into()).collect(); + let cdk_proofs = cdk_proofs?; let id = cdk::wallet::types::TransactionId::from_proofs(cdk_proofs)?; Ok(Self { hex: id.to_string(), diff --git a/crates/cdk-ffi/src/types/wallet.rs b/crates/cdk-ffi/src/types/wallet.rs index 336ca7f51..d9b6928a9 100644 --- a/crates/cdk-ffi/src/types/wallet.rs +++ b/crates/cdk-ffi/src/types/wallet.rs @@ -314,7 +314,7 @@ impl From for PreparedSend { .proofs() .iter() .cloned() - .map(|p| std::sync::Arc::new(p.into())) + .map(|p| p.into()) .collect(); Self { inner: Mutex::new(Some(prepared)), @@ -421,12 +421,9 @@ impl From for Melted { Self { state: melted.state.into(), preimage: melted.preimage, - change: melted.change.map(|proofs| { - proofs - .into_iter() - .map(|p| std::sync::Arc::new(p.into())) - .collect() - }), + change: melted + .change + .map(|proofs| proofs.into_iter().map(|p| p.into()).collect()), amount: melted.amount.into(), fee_paid: melted.fee_paid.into(), } diff --git a/crates/cdk-ffi/src/wallet.rs b/crates/cdk-ffi/src/wallet.rs index c144450fb..449aa950b 100644 --- a/crates/cdk-ffi/src/wallet.rs +++ b/crates/cdk-ffi/src/wallet.rs @@ -119,8 +119,9 @@ impl Wallet { options: ReceiveOptions, memo: Option, ) -> Result { - let cdk_proofs: Vec = - proofs.into_iter().map(|p| p.inner.clone()).collect(); + let cdk_proofs: Result, _> = + proofs.into_iter().map(|p| p.try_into()).collect(); + let cdk_proofs = cdk_proofs?; let amount = self .inner @@ -166,10 +167,7 @@ impl Wallet { .inner .mint("e_id, amount_split_target.into(), conditions) .await?; - Ok(proofs - .into_iter() - .map(|p| std::sync::Arc::new(p.into())) - .collect()) + Ok(proofs.into_iter().map(|p| p.into()).collect()) } /// Get a melt quote @@ -222,10 +220,7 @@ impl Wallet { ) .await?; - Ok(proofs - .into_iter() - .map(|p| std::sync::Arc::new(p.into())) - .collect()) + Ok(proofs.into_iter().map(|p| p.into()).collect()) } /// Get a quote for a bolt12 melt @@ -248,8 +243,9 @@ impl Wallet { spending_conditions: Option, include_fees: bool, ) -> Result, FfiError> { - let cdk_proofs: Vec = - input_proofs.into_iter().map(|p| p.inner.clone()).collect(); + let cdk_proofs: Result, _> = + input_proofs.into_iter().map(|p| p.try_into()).collect(); + let cdk_proofs = cdk_proofs?; // Convert spending conditions if provided let conditions = spending_conditions.map(|sc| sc.try_into()).transpose()?; @@ -265,12 +261,7 @@ impl Wallet { ) .await?; - Ok(result.map(|proofs| { - proofs - .into_iter() - .map(|p| std::sync::Arc::new(p.into())) - .collect() - })) + Ok(result.map(|proofs| proofs.into_iter().map(|p| p.into()).collect())) } /// Get proofs by states @@ -291,7 +282,7 @@ impl Wallet { }; for proof in proofs { - all_proofs.push(std::sync::Arc::new(proof.into())); + all_proofs.push(proof.into()); } } @@ -300,8 +291,9 @@ impl Wallet { /// Check if proofs are spent pub async fn check_proofs_spent(&self, proofs: Proofs) -> Result, FfiError> { - let cdk_proofs: Vec = - proofs.into_iter().map(|p| p.inner.clone()).collect(); + let cdk_proofs: Result, _> = + proofs.into_iter().map(|p| p.try_into()).collect(); + let cdk_proofs = cdk_proofs?; let proof_states = self.inner.check_proofs_spent(cdk_proofs).await?; // Convert ProofState to bool (spent = true, unspent = false) @@ -382,7 +374,9 @@ impl Wallet { /// Reclaim unspent proofs (mark them as unspent in the database) pub async fn reclaim_unspent(&self, proofs: Proofs) -> Result<(), FfiError> { - let cdk_proofs: Vec = proofs.iter().map(|p| p.inner.clone()).collect(); + let cdk_proofs: Result, _> = + proofs.iter().map(|p| p.clone().try_into()).collect(); + let cdk_proofs = cdk_proofs?; self.inner.reclaim_unspent(cdk_proofs).await?; Ok(()) } @@ -401,9 +395,11 @@ impl Wallet { ) -> Result { let id = cdk::nuts::Id::from_str(&keyset_id) .map_err(|e| FfiError::Generic { msg: e.to_string() })?; - let fee_and_amounts = self.inner.get_keyset_fees_and_amounts_by_id(id).await?; - let total_fee = (proof_count as u64 * fee_and_amounts.fee()) / 1000; // fee is per thousand - Ok(Amount::new(total_fee)) + let fee = self + .inner + .get_keyset_count_fee(&id, proof_count as u64) + .await?; + Ok(fee.into()) } } @@ -453,10 +449,7 @@ impl Wallet { /// Mint blind auth tokens pub async fn mint_blind_auth(&self, amount: Amount) -> Result { let proofs = self.inner.mint_blind_auth(amount.into()).await?; - Ok(proofs - .into_iter() - .map(|p| std::sync::Arc::new(p.into())) - .collect()) + Ok(proofs.into_iter().map(|p| p.into()).collect()) } /// Get unspent auth proofs diff --git a/crates/cdk-integration-tests/tests/ffi_minting_integration.rs b/crates/cdk-integration-tests/tests/ffi_minting_integration.rs index 71ade057f..81f4ee0ba 100644 --- a/crates/cdk-integration-tests/tests/ffi_minting_integration.rs +++ b/crates/cdk-integration-tests/tests/ffi_minting_integration.rs @@ -18,7 +18,7 @@ use std::time::Duration; use bip39::Mnemonic; use cdk_ffi::sqlite::WalletSqliteDatabase; -use cdk_ffi::types::{Amount, CurrencyUnit, QuoteState, SplitTarget}; +use cdk_ffi::types::{encode_mint_quote, Amount, CurrencyUnit, QuoteState, SplitTarget}; use cdk_ffi::wallet::Wallet as FfiWallet; use cdk_ffi::WalletConfig; use cdk_integration_tests::{get_mint_url_from_env, pay_if_regtest}; @@ -157,7 +157,7 @@ async fn test_ffi_full_minting_flow() { ); // Calculate total amount of minted proofs - let total_minted: u64 = mint_result.iter().map(|proof| proof.amount().value).sum(); + let total_minted: u64 = mint_result.iter().map(|proof| proof.amount.value).sum(); assert_eq!( total_minted, mint_amount.value, "Total minted amount should equal requested amount" @@ -166,14 +166,11 @@ async fn test_ffi_full_minting_flow() { // Verify each proof has valid properties for proof in &mint_result { assert!( - proof.amount().value > 0, + proof.amount.value > 0, "Each proof should have positive amount" ); - assert!( - !proof.secret().is_empty(), - "Each proof should have a secret" - ); - assert!(!proof.c().is_empty(), "Each proof should have a C value"); + assert!(!proof.secret.is_empty(), "Each proof should have a secret"); + assert!(!proof.c.is_empty(), "Each proof should have a C value"); } // Step 4: Verify wallet balance after minting @@ -235,7 +232,7 @@ async fn test_ffi_mint_quote_creation() { ); // Test quote JSON serialization (useful for bindings that need JSON) - let quote_json = quote.to_json().expect("Quote should serialize to JSON"); + let quote_json = encode_mint_quote(quote.clone()).expect("Quote should serialize to JSON"); assert!(!quote_json.is_empty(), "Quote JSON should not be empty"); println!( From 1604f8a937a86686c93e9f47764e5765b5a8abcb Mon Sep 17 00:00:00 2001 From: tsk Date: Fri, 24 Oct 2025 20:23:54 -0400 Subject: [PATCH 228/321] feat: update stable rust (#1207) --- .github/workflows/ci.yml | 104 +++++++++++++++++++++++---- .github/workflows/nutshell_itest.yml | 16 +++++ flake.lock | 36 +++++----- flake.nix | 4 +- rust-toolchain.toml | 2 +- 5 files changed, 129 insertions(+), 33 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b2ea54388..5ae04f89c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -19,14 +19,20 @@ jobs: steps: - name: checkout uses: actions/checkout@v4 + - name: Get flake hash + id: flake-hash + run: echo "hash=$(sha256sum flake.lock | cut -d' ' -f1 | cut -c1-8)" >> $GITHUB_OUTPUT - name: Install Nix uses: DeterminateSystems/nix-installer-action@v17 - name: Nix Cache uses: DeterminateSystems/magic-nix-cache-action@main + with: + diagnostic-endpoint: "" + use-flakehub: false - name: Rust Cache uses: Swatinem/rust-cache@v2 with: - shared-key: "nightly" + shared-key: "nightly-${{ steps.flake-hash.outputs.hash }}" - name: Cargo fmt run: | nix develop -i -L .#nightly --command bash -c ' @@ -56,14 +62,20 @@ jobs: steps: - name: checkout uses: actions/checkout@v4 + - name: Get flake hash + id: flake-hash + run: echo "hash=$(sha256sum flake.lock | cut -d' ' -f1 | cut -c1-8)" >> $GITHUB_OUTPUT - name: Install Nix uses: DeterminateSystems/nix-installer-action@v17 - name: Nix Cache uses: DeterminateSystems/magic-nix-cache-action@main + with: + diagnostic-endpoint: "" + use-flakehub: false - name: Rust Cache uses: Swatinem/rust-cache@v2 with: - shared-key: "stable" + shared-key: "stable-${{ steps.flake-hash.outputs.hash }}" - name: Run example run: nix develop -i -L .#stable --command cargo r --example ${{ matrix.build-args }} @@ -150,14 +162,20 @@ jobs: steps: - name: checkout uses: actions/checkout@v4 + - name: Get flake hash + id: flake-hash + run: echo "hash=$(sha256sum flake.lock | cut -d' ' -f1 | cut -c1-8)" >> $GITHUB_OUTPUT - name: Install Nix uses: DeterminateSystems/nix-installer-action@v17 - name: Nix Cache uses: DeterminateSystems/magic-nix-cache-action@main + with: + diagnostic-endpoint: "" + use-flakehub: false - name: Rust Cache uses: Swatinem/rust-cache@v2 with: - shared-key: "stable" + shared-key: "stable-${{ steps.flake-hash.outputs.hash }}" - name: Clippy run: nix develop -i -L .#stable --command cargo clippy ${{ matrix.build-args }} -- -D warnings - name: Test @@ -183,6 +201,9 @@ jobs: steps: - name: checkout uses: actions/checkout@v4 + - name: Get flake hash + id: flake-hash + run: echo "hash=$(sha256sum flake.lock | cut -d' ' -f1 | cut -c1-8)" >> $GITHUB_OUTPUT - name: Free Disk Space (Ubuntu) uses: jlumbroso/free-disk-space@main with: @@ -197,10 +218,13 @@ jobs: uses: DeterminateSystems/nix-installer-action@v17 - name: Nix Cache uses: DeterminateSystems/magic-nix-cache-action@main + with: + diagnostic-endpoint: "" + use-flakehub: false - name: Rust Cache uses: Swatinem/rust-cache@v2 with: - shared-key: "stable" + shared-key: "stable-${{ steps.flake-hash.outputs.hash }}" - name: Test run: nix develop -i -L .#stable --command just itest ${{ matrix.database }} @@ -223,6 +247,9 @@ jobs: steps: - name: checkout uses: actions/checkout@v4 + - name: Get flake hash + id: flake-hash + run: echo "hash=$(sha256sum flake.lock | cut -d' ' -f1 | cut -c1-8)" >> $GITHUB_OUTPUT - name: Free Disk Space (Ubuntu) uses: jlumbroso/free-disk-space@main with: @@ -237,10 +264,13 @@ jobs: uses: DeterminateSystems/nix-installer-action@v17 - name: Nix Cache uses: DeterminateSystems/magic-nix-cache-action@main + with: + diagnostic-endpoint: "" + use-flakehub: false - name: Rust Cache uses: Swatinem/rust-cache@v2 with: - shared-key: "stable" + shared-key: "stable-${{ steps.flake-hash.outputs.hash }}" - name: Clippy run: nix develop -i -L .#stable --command cargo clippy -- -D warnings - name: Test fake auth mint @@ -263,6 +293,9 @@ jobs: steps: - name: checkout uses: actions/checkout@v4 + - name: Get flake hash + id: flake-hash + run: echo "hash=$(sha256sum flake.lock | cut -d' ' -f1 | cut -c1-8)" >> $GITHUB_OUTPUT - name: Free Disk Space (Ubuntu) uses: jlumbroso/free-disk-space@main with: @@ -277,10 +310,13 @@ jobs: uses: DeterminateSystems/nix-installer-action@v17 - name: Nix Cache uses: DeterminateSystems/magic-nix-cache-action@main + with: + diagnostic-endpoint: "" + use-flakehub: false - name: Rust Cache uses: Swatinem/rust-cache@v2 with: - shared-key: "stable" + shared-key: "stable-${{ steps.flake-hash.outputs.hash }}" - name: Test fake mint run: nix develop -i -L .#stable --command just test-pure ${{ matrix.database }} - name: Install Postgres @@ -306,6 +342,9 @@ jobs: steps: - name: checkout uses: actions/checkout@v4 + - name: Get flake hash + id: flake-hash + run: echo "hash=$(sha256sum flake.lock | cut -d' ' -f1 | cut -c1-8)" >> $GITHUB_OUTPUT - name: Free Disk Space (Ubuntu) uses: jlumbroso/free-disk-space@main with: @@ -320,10 +359,13 @@ jobs: uses: DeterminateSystems/nix-installer-action@v17 - name: Nix Cache uses: DeterminateSystems/magic-nix-cache-action@main + with: + diagnostic-endpoint: "" + use-flakehub: false - name: Rust Cache uses: Swatinem/rust-cache@v2 with: - shared-key: "stable" + shared-key: "stable-${{ steps.flake-hash.outputs.hash }}" - name: Test run: nix develop -i -L .#stable --command just itest-payment-processor ${{matrix.ln}} @@ -358,14 +400,20 @@ jobs: steps: - name: checkout uses: actions/checkout@v4 + - name: Get flake hash + id: flake-hash + run: echo "hash=$(sha256sum flake.lock | cut -d' ' -f1 | cut -c1-8)" >> $GITHUB_OUTPUT - name: Install Nix uses: DeterminateSystems/nix-installer-action@v17 - name: Nix Cache uses: DeterminateSystems/magic-nix-cache-action@main + with: + diagnostic-endpoint: "" + use-flakehub: false - name: Rust Cache uses: Swatinem/rust-cache@v2 with: - shared-key: "msrv" + shared-key: "msrv-${{ steps.flake-hash.outputs.hash }}" - name: Build run: nix develop -i -L .#msrv --command cargo build ${{ matrix.build-args }} @@ -391,14 +439,20 @@ jobs: steps: - name: checkout uses: actions/checkout@v4 + - name: Get flake hash + id: flake-hash + run: echo "hash=$(sha256sum flake.lock | cut -d' ' -f1 | cut -c1-8)" >> $GITHUB_OUTPUT - name: Install Nix uses: DeterminateSystems/nix-installer-action@v17 - name: Nix Cache uses: DeterminateSystems/magic-nix-cache-action@main + with: + diagnostic-endpoint: "" + use-flakehub: false - name: Rust Cache uses: Swatinem/rust-cache@v2 with: - shared-key: "stable" + shared-key: "stable-${{ steps.flake-hash.outputs.hash }}" - name: Build cdk and binding run: nix develop -i -L ".#${{ matrix.rust }}" --command cargo build ${{ matrix.build-args }} --target ${{ matrix.target }} @@ -424,14 +478,20 @@ jobs: steps: - name: checkout uses: actions/checkout@v4 + - name: Get flake hash + id: flake-hash + run: echo "hash=$(sha256sum flake.lock | cut -d' ' -f1 | cut -c1-8)" >> $GITHUB_OUTPUT - name: Install Nix uses: DeterminateSystems/nix-installer-action@v17 - name: Nix Cache uses: DeterminateSystems/magic-nix-cache-action@main + with: + diagnostic-endpoint: "" + use-flakehub: false - name: Rust Cache uses: Swatinem/rust-cache@v2 with: - shared-key: "msrv" + shared-key: "msrv-${{ steps.flake-hash.outputs.hash }}" - name: Build cdk wasm run: nix develop -i -L ".#${{ matrix.rust }}" --command cargo build ${{ matrix.build-args }} --target ${{ matrix.target }} @@ -450,6 +510,9 @@ jobs: steps: - name: checkout uses: actions/checkout@v4 + - name: Get flake hash + id: flake-hash + run: echo "hash=$(sha256sum flake.lock | cut -d' ' -f1 | cut -c1-8)" >> $GITHUB_OUTPUT - name: Free Disk Space (Ubuntu) uses: jlumbroso/free-disk-space@main with: @@ -464,10 +527,13 @@ jobs: uses: DeterminateSystems/nix-installer-action@v17 - name: Nix Cache uses: DeterminateSystems/magic-nix-cache-action@main + with: + diagnostic-endpoint: "" + use-flakehub: false - name: Rust Cache uses: Swatinem/rust-cache@v2 with: - shared-key: "stable" + shared-key: "stable-${{ steps.flake-hash.outputs.hash }}" - name: Start Keycloak with Backup run: | docker compose -f misc/keycloak/docker-compose-recover.yml up -d @@ -490,6 +556,9 @@ jobs: steps: - name: checkout uses: actions/checkout@v4 + - name: Get flake hash + id: flake-hash + run: echo "hash=$(sha256sum flake.lock | cut -d' ' -f1 | cut -c1-8)" >> $GITHUB_OUTPUT - name: Free Disk Space (Ubuntu) uses: jlumbroso/free-disk-space@main with: @@ -504,10 +573,13 @@ jobs: uses: DeterminateSystems/nix-installer-action@v17 - name: Nix Cache uses: DeterminateSystems/magic-nix-cache-action@main + with: + diagnostic-endpoint: "" + use-flakehub: false - name: Rust Cache uses: Swatinem/rust-cache@v2 with: - shared-key: "stable" + shared-key: "stable-${{ steps.flake-hash.outputs.hash }}" - name: Run doc tests run: nix develop -i -L .#stable --command cargo test --doc @@ -519,13 +591,19 @@ jobs: steps: - name: checkout uses: actions/checkout@v4 + - name: Get flake hash + id: flake-hash + run: echo "hash=$(sha256sum flake.lock | cut -d' ' -f1 | cut -c1-8)" >> $GITHUB_OUTPUT - name: Install Nix uses: DeterminateSystems/nix-installer-action@v17 - name: Nix Cache uses: DeterminateSystems/magic-nix-cache-action@main + with: + diagnostic-endpoint: "" + use-flakehub: false - name: Rust Cache uses: Swatinem/rust-cache@v2 with: - shared-key: "stable" + shared-key: "stable-${{ steps.flake-hash.outputs.hash }}" - name: Check docs with strict warnings run: nix develop -i -L .#stable --command just docs-strict diff --git a/.github/workflows/nutshell_itest.yml b/.github/workflows/nutshell_itest.yml index bac6ae65d..d967837c1 100644 --- a/.github/workflows/nutshell_itest.yml +++ b/.github/workflows/nutshell_itest.yml @@ -10,6 +10,9 @@ jobs: steps: - name: checkout uses: actions/checkout@v4 + - name: Get flake hash + id: flake-hash + run: echo "hash=$(sha256sum flake.lock | cut -d' ' -f1 | cut -c1-8)" >> $GITHUB_OUTPUT - name: Free Disk Space (Ubuntu) uses: jlumbroso/free-disk-space@main with: @@ -24,8 +27,13 @@ jobs: uses: DeterminateSystems/nix-installer-action@v17 - name: Nix Cache uses: DeterminateSystems/magic-nix-cache-action@main + with: + diagnostic-endpoint: "" + use-flakehub: false - name: Rust Cache uses: Swatinem/rust-cache@v2 + with: + shared-key: "integration-${{ steps.flake-hash.outputs.hash }}" - name: Test Nutshell run: nix develop -i -L .#integration --command just test-nutshell - name: Show logs if tests fail @@ -39,6 +47,9 @@ jobs: steps: - name: checkout uses: actions/checkout@v4 + - name: Get flake hash + id: flake-hash + run: echo "hash=$(sha256sum flake.lock | cut -d' ' -f1 | cut -c1-8)" >> $GITHUB_OUTPUT - name: Free Disk Space (Ubuntu) uses: jlumbroso/free-disk-space@main with: @@ -55,8 +66,13 @@ jobs: uses: DeterminateSystems/nix-installer-action@v17 - name: Nix Cache uses: DeterminateSystems/magic-nix-cache-action@main + with: + diagnostic-endpoint: "" + use-flakehub: false - name: Rust Cache uses: Swatinem/rust-cache@v2 + with: + shared-key: "integration-${{ steps.flake-hash.outputs.hash }}" - name: Test Nutshell Wallet run: | nix develop -i -L .#integration --command just nutshell-wallet-itest diff --git a/flake.lock b/flake.lock index 4926e6182..186800f7b 100644 --- a/flake.lock +++ b/flake.lock @@ -2,11 +2,11 @@ "nodes": { "crane": { "locked": { - "lastModified": 1758758545, - "narHash": "sha256-NU5WaEdfwF6i8faJ2Yh+jcK9vVFrofLcwlD/mP65JrI=", + "lastModified": 1760924934, + "narHash": "sha256-tuuqY5aU7cUkR71sO2TraVKK2boYrdW3gCSXUkF4i44=", "owner": "ipetkov", "repo": "crane", - "rev": "95d528a5f54eaba0d12102249ce42f4d01f4e364", + "rev": "c6b4d5308293d0d04fcfeee92705017537cad02f", "type": "github" }, "original": { @@ -23,11 +23,11 @@ "rust-analyzer-src": [] }, "locked": { - "lastModified": 1759387261, - "narHash": "sha256-u/gfYBMDnwD1mSAlzHnRVg3jst3ML0w9b3tYONXRsW8=", + "lastModified": 1761287960, + "narHash": "sha256-DbGYVbF0TgoKTFNQv/3jqaUWql8OYzewl4v2gw6jmQs=", "owner": "nix-community", "repo": "fenix", - "rev": "c61e7ab9cfa38119d5ab9e2d1156d23c19e9b8a0", + "rev": "64cb168ed9ec61ef18e28f1e4ee9f44381d6ecd2", "type": "github" }, "original": { @@ -93,11 +93,11 @@ }, "nixpkgs": { "locked": { - "lastModified": 1759281824, - "narHash": "sha256-FIBE1qXv9TKvSNwst6FumyHwCRH3BlWDpfsnqRDCll0=", + "lastModified": 1761173472, + "narHash": "sha256-m9W0dYXflzeGgKNravKJvTMR4Qqa2MVD11AwlGMufeE=", "owner": "NixOS", "repo": "nixpkgs", - "rev": "5b5be50345d4113d04ba58c444348849f5585b4a", + "rev": "c8aa8cc00a5cb57fada0851a038d35c08a36a2bb", "type": "github" }, "original": { @@ -109,11 +109,11 @@ }, "nixpkgs_2": { "locked": { - "lastModified": 1758029226, - "narHash": "sha256-TjqVmbpoCqWywY9xIZLTf6ANFvDCXdctCjoYuYPYdMI=", + "lastModified": 1759070547, + "narHash": "sha256-JVZl8NaVRYb0+381nl7LvPE+A774/dRpif01FKLrYFQ=", "owner": "NixOS", "repo": "nixpkgs", - "rev": "08b8f92ac6354983f5382124fef6006cade4a1c1", + "rev": "647e5c14cbd5067f44ac86b74f014962df460840", "type": "github" }, "original": { @@ -130,11 +130,11 @@ "nixpkgs": "nixpkgs_2" }, "locked": { - "lastModified": 1758108966, - "narHash": "sha256-ytw7ROXaWZ7OfwHrQ9xvjpUWeGVm86pwnEd1QhzawIo=", + "lastModified": 1760663237, + "narHash": "sha256-BflA6U4AM1bzuRMR8QqzPXqh8sWVCNDzOdsxXEguJIc=", "owner": "cachix", "repo": "pre-commit-hooks.nix", - "rev": "54df955a695a84cd47d4a43e08e1feaf90b1fd9b", + "rev": "ca5b894d3e3e151ffc1db040b6ce4dcc75d31c37", "type": "github" }, "original": { @@ -160,11 +160,11 @@ ] }, "locked": { - "lastModified": 1759372351, - "narHash": "sha256-kULiC2oMMuyaO92gPiu+6XBfeXuFcXaauwo0tXAwXdQ=", + "lastModified": 1761273263, + "narHash": "sha256-6d6ojnu6A6sVxIjig8OL6E1T8Ge9st3YGgVwg5MOY+Q=", "owner": "oxalica", "repo": "rust-overlay", - "rev": "7ef14552303de7128662666f9a71342099ffc725", + "rev": "28405834d4fdd458d28e123fae4db148daecec6f", "type": "github" }, "original": { diff --git a/flake.nix b/flake.nix index fbcc431a0..46b1d3279 100644 --- a/flake.nix +++ b/flake.nix @@ -56,7 +56,7 @@ # Toolchains # latest stable - stable_toolchain = pkgs.rust-bin.stable."1.86.0".default.override { + stable_toolchain = pkgs.rust-bin.stable."1.90.0".default.override { targets = [ "wasm32-unknown-unknown" ]; # wasm extensions = [ "rustfmt" @@ -172,6 +172,8 @@ msrv = pkgs.mkShell ( { shellHook = " + cargo update + cargo update home --precise 0.5.11 ${_shellHook} "; buildInputs = buildInputs ++ [ msrv_toolchain ]; diff --git a/rust-toolchain.toml b/rust-toolchain.toml index b557f5a45..e34c54e64 100644 --- a/rust-toolchain.toml +++ b/rust-toolchain.toml @@ -1,4 +1,4 @@ [toolchain] -channel="1.86.0" +channel="1.90.0" components = ["rustfmt", "clippy", "rust-analyzer"] From ec6e1e2910f036f6c31638ce28f24503b613611a Mon Sep 17 00:00:00 2001 From: tsk Date: Sun, 26 Oct 2025 10:23:41 -0400 Subject: [PATCH 229/321] fix: improve Melted error handling and add debug logging (#1213) Replace .unwrap() with proper error handling using ? operator and add debug logging to help diagnose fee calculation issues in the melt flow. Changes: - Replace .unwrap() with ? for proper error propagation - Add tracing log for proofs amount, amount, and change amount feat: nut14-validation --- crates/cashu/src/nuts/nut11/mod.rs | 15 +++++++++++++-- crates/cashu/src/nuts/nut14/mod.rs | 19 +++++++++++++++++-- crates/cdk-common/src/common.rs | 10 ++++++++-- crates/cdk/src/mint/melt.rs | 4 ++++ 4 files changed, 42 insertions(+), 6 deletions(-) diff --git a/crates/cashu/src/nuts/nut11/mod.rs b/crates/cashu/src/nuts/nut11/mod.rs index abc6d2930..708f7d562 100644 --- a/crates/cashu/src/nuts/nut11/mod.rs +++ b/crates/cashu/src/nuts/nut11/mod.rs @@ -58,6 +58,9 @@ pub enum Error { /// HTLC hash invalid #[error("Invalid hash")] InvalidHash, + /// HTLC preimage too large + #[error("Preimage exceeds maximum size of 32 bytes (64 hex characters)")] + PreimageTooLarge, /// Witness Signatures not provided #[error("Witness signatures not provided")] SignaturesNotProvided, @@ -329,7 +332,15 @@ pub enum SpendingConditions { impl SpendingConditions { /// New HTLC [SpendingConditions] pub fn new_htlc(preimage: String, conditions: Option) -> Result { - let htlc = Sha256Hash::hash(&hex::decode(preimage)?); + const MAX_PREIMAGE_BYTES: usize = 32; + + let preimage_bytes = hex::decode(preimage)?; + + if preimage_bytes.len() != MAX_PREIMAGE_BYTES { + return Err(Error::PreimageTooLarge); + } + + let htlc = Sha256Hash::hash(&preimage_bytes); Ok(Self::HTLCConditions { data: htlc, @@ -2071,4 +2082,4 @@ mod tests { "Both signatures should verify" ); } -} // End of tests module +} diff --git a/crates/cashu/src/nuts/nut14/mod.rs b/crates/cashu/src/nuts/nut14/mod.rs index e647e7e08..4204545f5 100644 --- a/crates/cashu/src/nuts/nut14/mod.rs +++ b/crates/cashu/src/nuts/nut14/mod.rs @@ -15,7 +15,7 @@ use super::nut10::Secret; use super::nut11::valid_signatures; use super::{Conditions, Proof}; use crate::ensure_cdk; -use crate::util::unix_time; +use crate::util::{hex, unix_time}; pub mod serde_htlc_witness; @@ -37,6 +37,12 @@ pub enum Error { /// Preimage does not match #[error("Preimage does not match")] Preimage, + /// HTLC preimage must be valid hex encoding + #[error("Preimage must be valid hex encoding")] + InvalidHexPreimage, + /// HTLC preimage must be exactly 32 bytes + #[error("Preimage must be exactly 32 bytes (64 hex characters)")] + PreimageInvalidSize, /// Witness Signatures not provided #[error("Witness did not provide signatures")] SignaturesNotProvided, @@ -76,6 +82,15 @@ impl Proof { _ => return Err(Error::IncorrectSecretKind), }; + const REQUIRED_PREIMAGE_BYTES: usize = 32; + + let preimage_bytes = + hex::decode(&htlc_witness.preimage).map_err(|_| Error::InvalidHexPreimage)?; + + if preimage_bytes.len() != REQUIRED_PREIMAGE_BYTES { + return Err(Error::PreimageInvalidSize); + } + if let Some(conditions) = conditions { // Check locktime if let Some(locktime) = conditions.locktime { @@ -127,7 +142,7 @@ impl Proof { let hash_lock = Sha256Hash::from_str(secret.secret_data().data()).map_err(|_| Error::InvalidHash)?; - let preimage_hash = Sha256Hash::hash(htlc_witness.preimage.as_bytes()); + let preimage_hash = Sha256Hash::hash(&preimage_bytes); if hash_lock.ne(&preimage_hash) { return Err(Error::Preimage); diff --git a/crates/cdk-common/src/common.rs b/crates/cdk-common/src/common.rs index d86d5ce0f..97d370ec0 100644 --- a/crates/cdk-common/src/common.rs +++ b/crates/cdk-common/src/common.rs @@ -41,10 +41,16 @@ impl Melted { None => Amount::ZERO, }; + tracing::info!( + "Proofs amount: {} Amount: {} Change: {}", + proofs_amount, + amount, + change_amount + ); + let fee_paid = proofs_amount .checked_sub(amount + change_amount) - .ok_or(Error::AmountOverflow) - .unwrap(); + .ok_or(Error::AmountOverflow)?; Ok(Self { state, diff --git a/crates/cdk/src/mint/melt.rs b/crates/cdk/src/mint/melt.rs index 2f3a8d4b3..20e9b7b24 100644 --- a/crates/cdk/src/mint/melt.rs +++ b/crates/cdk/src/mint/melt.rs @@ -898,6 +898,10 @@ impl Mint { quote.id ); + if total_spent < quote.amount { + return Err(Error::AmountUndefined); + } + let update_proof_states_result = proof_writer .update_proofs_states(&mut tx, &input_ys, State::Spent) .await; From a40989b6b3c8848aec63c08328ea90915d0f4d7e Mon Sep 17 00:00:00 2001 From: Luke Date: Mon, 27 Oct 2025 16:06:55 -0400 Subject: [PATCH 230/321] Typo fix (#1217) --- crates/cdk-common/src/database/mint/mod.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/crates/cdk-common/src/database/mint/mod.rs b/crates/cdk-common/src/database/mint/mod.rs index 501ed4496..bf97eacbb 100644 --- a/crates/cdk-common/src/database/mint/mod.rs +++ b/crates/cdk-common/src/database/mint/mod.rs @@ -108,7 +108,7 @@ pub trait KeysDatabase { /// Mint Keys Database Error type Err: Into + From; - /// Beings a transaction + /// Begins a transaction async fn begin_transaction<'a>( &'a self, ) -> Result + Send + Sync + 'a>, Error>; @@ -479,7 +479,7 @@ pub trait KVStoreDatabase { /// Key-Value Store Database trait #[async_trait] pub trait KVStore: KVStoreDatabase { - /// Beings a KV transaction + /// Begins a KV transaction async fn begin_transaction<'a>( &'a self, ) -> Result + Send + Sync + 'a>, Error>; @@ -497,7 +497,7 @@ pub trait Database: + SignaturesDatabase + SagaDatabase { - /// Beings a transaction + /// Begins a transaction async fn begin_transaction<'a>( &'a self, ) -> Result + Send + Sync + 'a>, Error>; From d6824dd56f3ec93e199f2cb5432bbc462a90aa35 Mon Sep 17 00:00:00 2001 From: tsk Date: Mon, 27 Oct 2025 18:58:48 -0400 Subject: [PATCH 231/321] feat: add auto genrated meetings template (#1218) --- .github/scripts/generate-agenda.sh | 122 ++++++++++++++++++++ .github/workflows/weekly-meeting-agenda.yml | 62 ++++++++++ meetings/2025-04-02-agenda.md | 18 +++ meetings/2025-04-09-agenda.md | 24 ++++ meetings/2025-04-23-agenda.md | 12 ++ meetings/2025-06-04-agenda.md | 24 ++++ meetings/2025-06-11-agenda.md | 26 +++++ meetings/2025-06-25-agenda.md | 34 ++++++ meetings/2025-07-02-agenda.md | 41 +++++++ meetings/2025-07-09-agenda.md | 39 +++++++ meetings/2025-07-23-agenda.md | 51 ++++++++ meetings/2025-07-30-agenda.md | 26 +++++ meetings/2025-08-05-agenda.md | 20 ++++ meetings/2025-08-13-agenda.md | 35 ++++++ meetings/2025-08-20-agenda.md | 41 +++++++ meetings/2025-08-27-agenda.md | 40 +++++++ meetings/2025-09-03-agenda.md | 50 ++++++++ meetings/2025-09-10-agenda.md | 44 +++++++ meetings/2025-09-17-agenda.md | 47 ++++++++ meetings/2025-09-24-agenda.md | 49 ++++++++ meetings/2025-10-08-agenda.md | 45 ++++++++ meetings/2025-10-15-agenda.md | 39 +++++++ meetings/2025-10-27-agenda.md | 57 +++++++++ 23 files changed, 946 insertions(+) create mode 100755 .github/scripts/generate-agenda.sh create mode 100644 .github/workflows/weekly-meeting-agenda.yml create mode 100644 meetings/2025-04-02-agenda.md create mode 100644 meetings/2025-04-09-agenda.md create mode 100644 meetings/2025-04-23-agenda.md create mode 100644 meetings/2025-06-04-agenda.md create mode 100644 meetings/2025-06-11-agenda.md create mode 100644 meetings/2025-06-25-agenda.md create mode 100644 meetings/2025-07-02-agenda.md create mode 100644 meetings/2025-07-09-agenda.md create mode 100644 meetings/2025-07-23-agenda.md create mode 100644 meetings/2025-07-30-agenda.md create mode 100644 meetings/2025-08-05-agenda.md create mode 100644 meetings/2025-08-13-agenda.md create mode 100644 meetings/2025-08-20-agenda.md create mode 100644 meetings/2025-08-27-agenda.md create mode 100644 meetings/2025-09-03-agenda.md create mode 100644 meetings/2025-09-10-agenda.md create mode 100644 meetings/2025-09-17-agenda.md create mode 100644 meetings/2025-09-24-agenda.md create mode 100644 meetings/2025-10-08-agenda.md create mode 100644 meetings/2025-10-15-agenda.md create mode 100644 meetings/2025-10-27-agenda.md diff --git a/.github/scripts/generate-agenda.sh b/.github/scripts/generate-agenda.sh new file mode 100755 index 000000000..43d115e46 --- /dev/null +++ b/.github/scripts/generate-agenda.sh @@ -0,0 +1,122 @@ +#!/bin/bash +set -e + +# Configuration +REPO="${GITHUB_REPOSITORY:-cashubtc/cdk}" +DAYS_BACK="${DAYS_BACK:-7}" +MEETING_LINK="https://meet.fulmo.org/cdk-dev" +OUTPUT_DIR="meetings" + +# Calculate date range (last 7 days) +SINCE_DATE=$(date -d "$DAYS_BACK days ago" -u +"%Y-%m-%dT%H:%M:%SZ") +MEETING_DATE=$(date -u +"%b %d %Y %H:%M UTC") +FILE_DATE=$(date -u +"%Y-%m-%d") + +echo "Generating meeting agenda for $MEETING_DATE" +echo "Fetching data since $SINCE_DATE" + +# Function to format PR/issue list +format_list() { + local items="$1" + if [ -z "$items" ]; then + echo "- None" + else + echo "$items" | while IFS=$'\t' read -r number title url; do + echo "- [#$number]($url) - $title" + done + fi +} + +# Fetch merged PRs +echo "Fetching merged PRs..." +MERGED_PRS=$(gh pr list \ + --repo "$REPO" \ + --state merged \ + --search "merged:>=$SINCE_DATE" \ + --json number,title,url \ + --jq '.[] | [.number, .title, .url] | @tsv' \ + 2>/dev/null || echo "") + +# Fetch ongoing (open) PRs +echo "Fetching ongoing PRs..." +ONGOING_PRS=$(gh pr list \ + --repo "$REPO" \ + --state open \ + --json number,title,url,createdAt \ + --jq '.[] | select(.createdAt < "'$SINCE_DATE'") | [.number, .title, .url] | @tsv' \ + 2>/dev/null || echo "") + +# Fetch new PRs (opened in the last week) +echo "Fetching new PRs..." +NEW_PRS=$(gh pr list \ + --repo "$REPO" \ + --state open \ + --search "created:>=$SINCE_DATE" \ + --json number,title,url \ + --jq '.[] | [.number, .title, .url] | @tsv' \ + 2>/dev/null || echo "") + +# Fetch new issues +echo "Fetching new issues..." +NEW_ISSUES=$(gh issue list \ + --repo "$REPO" \ + --state open \ + --search "created:>=$SINCE_DATE" \ + --json number,title,url \ + --jq '.[] | [.number, .title, .url] | @tsv' \ + 2>/dev/null || echo "") + +# Generate markdown +AGENDA=$(cat < "$OUTPUT_FILE" + echo "Agenda saved to $OUTPUT_FILE" +fi + +# Create GitHub Discussion if requested +if [ "${CREATE_DISCUSSION:-false}" = "true" ]; then + echo "Creating GitHub discussion..." + DISCUSSION_TITLE="CDK Dev Meeting - $MEETING_DATE" + + # Note: gh CLI doesn't have direct discussion creation yet, so we'd need to use the API + # For now, we'll just output instructions + echo "To create discussion manually, use the GitHub web interface or API" + echo "Title: $DISCUSSION_TITLE" +fi + +# Output for GitHub Actions +if [ -n "$GITHUB_OUTPUT" ]; then + echo "agenda_file=$OUTPUT_FILE" >> "$GITHUB_OUTPUT" + echo "meeting_date=$MEETING_DATE" >> "$GITHUB_OUTPUT" +fi diff --git a/.github/workflows/weekly-meeting-agenda.yml b/.github/workflows/weekly-meeting-agenda.yml new file mode 100644 index 000000000..8ad991ce9 --- /dev/null +++ b/.github/workflows/weekly-meeting-agenda.yml @@ -0,0 +1,62 @@ +name: Weekly Meeting Agenda + +on: + schedule: + # Run every Wednesday at 12:00 UTC (3 hours before the 15:00 UTC meeting) + - cron: '0 12 * * 3' + workflow_dispatch: # Allow manual triggering for testing + +permissions: + contents: write + pull-requests: write + issues: read + +jobs: + generate-agenda: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Generate meeting agenda + id: generate + env: + GH_TOKEN: ${{ github.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + OUTPUT_TO_FILE: "true" + CREATE_DISCUSSION: "false" + DAYS_BACK: "7" + run: | + bash .github/scripts/generate-agenda.sh + + - name: Create Pull Request + env: + GH_TOKEN: ${{ github.token }} + run: | + MEETING_DATE=$(date -u +"%Y-%m-%d") + BRANCH_NAME="meeting-agenda-${MEETING_DATE}" + + git config --global user.name 'github-actions[bot]' + git config --global user.email 'github-actions[bot]@users.noreply.github.com' + + # Create and switch to new branch + git checkout -b "$BRANCH_NAME" + + # Add and commit the agenda file + git add meetings/*.md + if git diff --cached --quiet; then + echo "No changes to commit" + exit 0 + fi + + git commit -m "chore: add weekly meeting agenda for ${MEETING_DATE}" + + # Push the branch + git push origin "$BRANCH_NAME" + + # Create pull request + gh pr create \ + --title "Weekly Meeting Agenda - ${MEETING_DATE}" \ + --body "Automated weekly meeting agenda for CDK Development Meeting on ${MEETING_DATE}." \ + --base main \ + --head "$BRANCH_NAME" diff --git a/meetings/2025-04-02-agenda.md b/meetings/2025-04-02-agenda.md new file mode 100644 index 000000000..f000e21c9 --- /dev/null +++ b/meetings/2025-04-02-agenda.md @@ -0,0 +1,18 @@ +# CDK Dev Call 8 +April 2 2025 15:00 UTC + +Meeting Link: https://signal.link/call/#key=pqqn-xzqm-rtrt-khhq-xtgg-sxdk-fpkh-mftk + +# Agenda + +## Merged +- Test with Nutshell wallet [PR](https://github.com/cashubtc/cdk/pull/695) +- Test with Nutshell mint [PR](https://github.com/cashubtc/cdk/pull/691) +- Remove DLEQ from requests to mint [PR](https://github.com/cashubtc/cdk/pull/690) +- Refactor tests [PR](https://github.com/cashubtc/cdk/pull/685) +- Rust Docs [PR](https://github.com/cashubtc/cdk/pull/681) + +## Demo +- [cashudevkit.org](https://cashudevkit.org) +- Cashu Proxy [PR](https://github.com/thesimplekid/cashu-proxy) + diff --git a/meetings/2025-04-09-agenda.md b/meetings/2025-04-09-agenda.md new file mode 100644 index 000000000..3463b5aee --- /dev/null +++ b/meetings/2025-04-09-agenda.md @@ -0,0 +1,24 @@ +# CDK Dev Call 9 +April 9 2025 15:00 UTC + +Meeting Link: https://meet.fulmo.org/cdk-dev + +# Agenda + +## Merged +- Export DB traits [PR](https://github.com/cashubtc/cdk/pull/710) +- Time metadata for quotes, proofs and signatures [PR](https://github.com/cashubtc/cdk/pull/708) +- SQlite memory db fix [PR](https://github.com/cashubtc/cdk/pull/707) +- Melt to amountless [PR](https://github.com/cashubtc/cdk/pull/497) +- Fix Check of amountless settings [PR](https://github.com/cashubtc/cdk/pull/713) +- Fix mint pending get mint info [PR](https://github.com/cashubtc/cdk/pull/704) +- V0.9.0 [PR](https://github.com/cashubtc/cdk/pull/718) + + +## Discuss +- Prelude +- BOLT12 +- SQLite dep + + + diff --git a/meetings/2025-04-23-agenda.md b/meetings/2025-04-23-agenda.md new file mode 100644 index 000000000..c9739d89f --- /dev/null +++ b/meetings/2025-04-23-agenda.md @@ -0,0 +1,12 @@ +# CDK Dev Call 10 +April 23 2025 15:00 UTC + +Meeting Link: https://meet.fulmo.org/cdk-dev + +# Agenda + +## Merged +- Update lnbits [PR](https://github.com/cashubtc/cdk/pull/733) +- Mint proof state transition [PR](https://github.com/cashubtc/cdk/pull/730) + +## Discuss diff --git a/meetings/2025-06-04-agenda.md b/meetings/2025-06-04-agenda.md new file mode 100644 index 000000000..d910f8b7f --- /dev/null +++ b/meetings/2025-06-04-agenda.md @@ -0,0 +1,24 @@ +# CDK Dev Call 13 +June 4th 2025 15:00 UTC + +Meeting Link: https://meet.fulmo.org/cdk-dev + +# Agenda + +## Merged +- Remove redundant filter [PR](https://github.com/cashubtc/cdk/pull/784) +- Signatory loader [PR](https://github.com/cashubtc/cdk/pull/777/files) +- Signatory custom stream [PR](https://github.com/cashubtc/cdk/pull/776) +- Sqlite dep optional for signatory [PR](https://github.com/cashubtc/cdk/pull/775) +- Revert transaction [PR](https://github.com/cashubtc/cdk/pull/774) +- Docker build for arm [PR](https://github.com/cashubtc/cdk/pull/770) + +## Opened +- Migrate from sqlx [PR](https://github.com/cashubtc/cdk/pull/783) +- Remove pub properties [PR](https://github.com/cashubtc/cdk/pull/782) +- Refactor mintd main fn [PR](https://github.com/cashubtc/cdk/pull/778) + + +## Discuss + + diff --git a/meetings/2025-06-11-agenda.md b/meetings/2025-06-11-agenda.md new file mode 100644 index 000000000..810b05a66 --- /dev/null +++ b/meetings/2025-06-11-agenda.md @@ -0,0 +1,26 @@ +# CDK Dev Call 14 +June 11th 2025 15:00 UTC + +Meeting Link: https://meet.fulmo.org/cdk-dev + +# Agenda + +## Merged +- Docker arm release [PR](https://github.com/cashubtc/cdk/pull/805) +- Fix mint version [PR](https://github.com/cashubtc/cdk/pull/803) +- Bump version 10 [PR](https://github.com/cashubtc/cdk/pull/797) + +## Opened +- Update lnbits [PR](https://github.com/cashubtc/cdk/pull/802) +- Update test matrix [PR](https://github.com/cashubtc/cdk/pull/799) +- Remove redb [PR](https://github.com/cashubtc/cdk/pull/787) + +## Discuss +- Upcoming release plan + - v0.11.0 Sqlx + - sqlx -> rusqlite + - [#783](https://github.com/cashubtc/cdk/pull/783) - Migrate from `sqlx` to rusqlite + - redb -> sqlite conversion + - https://github.com/thesimplekid/cdk-convert-redb-to-sqlite + - v0.12.0 bolt12 + - remove redb diff --git a/meetings/2025-06-25-agenda.md b/meetings/2025-06-25-agenda.md new file mode 100644 index 000000000..b86a73ff3 --- /dev/null +++ b/meetings/2025-06-25-agenda.md @@ -0,0 +1,34 @@ +# CDK Dev Call 15 +June 25th 2025 15:00 UTC + +Meeting Link: https://meet.fulmo.org/cdk-dev + +# Agenda + +## Merged +- REDB conversion script [PR](https://github.com/cashubtc/cdk/pull/829) +- Remove fedimint tonic [PR](https://github.com/cashubtc/cdk/pull/831) +- CLN RPC remove mutex [PR](https://github.com/cashubtc/cdk/pull/832) +- Install crypto providers [PR](https://github.com/cashubtc/cdk/pull/836) +- Fix nonsat amounts on melt [PR](https://github.com/cashubtc/cdk/pull/839) +- Remove multiple on conflicts on sqlite [PR](https://github.com/cashubtc/cdk/pull/820) +- Fix cdk-cli create wallets for proper units [PR](https://github.com/cashubtc/cdk/pull/841) +- Keyset V2 [PR](https://github.com/cashubtc/cdk/pull/702) +- ARM override on release [PR](https://github.com/cashubtc/cdk/pull/825) +- Remove melt request table [PR](https://github.com/cashubtc/cdk/pull/819) + +## Opened +- DB transaction trait [PR](https://github.com/cashubtc/cdk/pull/826) + +## Discuss + +## Upcoming release plan +- v0.11.0 Sqlx + - Features: + - sqlx -> rusqlite + - [#783](https://github.com/cashubtc/cdk/pull/783) - Migrate from `sqlx` to rusqlite + - redb -> sqlite conversion + - https://github.com/thesimplekid/cdk-convert-redb-to-sqlite + - Blocking: + - [#826](https://github.com/cashubtc/cdk/pull/826) - Split the database trait into read and transactions. +- v0.12.0 bolt12 diff --git a/meetings/2025-07-02-agenda.md b/meetings/2025-07-02-agenda.md new file mode 100644 index 000000000..332f1f298 --- /dev/null +++ b/meetings/2025-07-02-agenda.md @@ -0,0 +1,41 @@ +# CDK Dev Call 16 +July 2nd 2025 15:00 UTC + +Meeting Link: https://meet.fulmo.org/cdk-dev + +# Agenda + +## Merged + + +- Correct name of blinded_messages on sig table [PR](https://github.com/cashubtc/cdk/pull/845) +- Limit send size of token [PR](https://github.com/cashubtc/cdk/pull/855) +- Mint error codes [PR](https://github.com/cashubtc/cdk/pull/858) +- Refund multi sig [PR](https://github.com/cashubtc/cdk/pull/860) +- Bump v0.11 [PR](https://github.com/cashubtc/cdk/pull/863) +- Check unpaid quotes on mint start up [PR](https://github.com/cashubtc/cdk/pull/844) +- Remove unused protos [PR](https://github.com/cashubtc/cdk/pull/842) +- cors headers on auth endpoints [PR](https://github.com/cashubtc/cdk/pull/866) +- glibc compatibility [PR](https://github.com/cashubtc/cdk/pull/864) + + + +## Opened + +- Sig all [PR](https://github.com/cashubtc/cdk/pull/862) + + +## Discuss + +## Next dev call + - outbox table + - outbox pattern by inserting a row into an "outbox" table that contains the message to be sent to the LNBackend. Another process will select pending entries from this outbox and dispatch the message to the LN API. Once the message is successfully delivered, we need to update the entry in the outbox table and set its state to completed or failed, depending on the outcome. + - Bolt12 PR review + - Sqlite -> postgresql migration + +## Upcoming release plan +- v0.12 + - Bolt12 support + - cdk-ldk? + - postgresql? + diff --git a/meetings/2025-07-09-agenda.md b/meetings/2025-07-09-agenda.md new file mode 100644 index 000000000..a9e678503 --- /dev/null +++ b/meetings/2025-07-09-agenda.md @@ -0,0 +1,39 @@ +# CDK Dev Call 17 +July 9th 2025 15:00 UTC + +Meeting Link: https://meet.fulmo.org/cdk-dev + +# Agenda + +## Merged +- Remove left in REDB file [PR](https://github.com/cashubtc/cdk/pull/872) +- Remove start up pending mint check [PR](https://github.com/cashubtc/cdk/pull/873) +- Remove rexie [PR](https://github.com/cashubtc/cdk/pull/875) +- Mprocs Regtest [PR](https://github.com/cashubtc/cdk/pull/876) + + + +## Opened + +- Postgresql [PR](https://github.com/cashubtc/cdk/pull/878) +- Add proof state on db add proof [PR](https://github.com/cashubtc/cdk/pull/867) + +## Stalled +- Sig all [PR](https://github.com/cashubtc/cdk/pull/862) + + + +## Discuss + - outbox table + - outbox pattern by inserting a row into an "outbox" table that contains the message to be sent to the LNBackend. Another process will select pending entries from this outbox and dispatch the message to the LN API. Once the message is successfully delivered, we need to update the entry in the outbox table and set its state to completed or failed, depending on the outcome. + - Bolt12 PR review + - Sqlite -> postgresql migration + +## Next dev call + + +## Upcoming release plan +- v0.12 + - Bolt12 support + - cdk-ldk? + - postgresql? diff --git a/meetings/2025-07-23-agenda.md b/meetings/2025-07-23-agenda.md new file mode 100644 index 000000000..3921a50b0 --- /dev/null +++ b/meetings/2025-07-23-agenda.md @@ -0,0 +1,51 @@ +# CDK Dev Call 18 +July 23th 2025 15:00 UTC + +Meeting Link: https://meet.fulmo.org/cdk-dev + +# Agenda + +## Merged +- Bolt12 [PR](https://github.com/cashubtc/cdk/pull/874) +- Correct error when fetching config [PR](https://github.com/cashubtc/cdk/pull/888) +- Refactor mintd main fn [PR](https://github.com/cashubtc/cdk/pull/778) +- Get active mint quotes [PR](https://github.com/cashubtc/cdk/pull/884) +- Check pending mint quote [PR](https://github.com/cashubtc/cdk/pull/895) +- Refactor mint builder [PR](https://github.com/cashubtc/cdk/pull/887) +- Fake wallet convent unit [PR](https://github.com/cashubtc/cdk/pull/899) +- Goose recipes [PR](https://github.com/cashubtc/cdk/pull/902) +- Refactor nut10 secret [PR](https://github.com/cashubtc/cdk/pull/900) +- Change in melt ws [PR](https://github.com/cashubtc/cdk/pull/889) + +## Opened +- Prometheus [PR](https://github.com/cashubtc/cdk/pull/883) +- Uuid version [PR](https://github.com/cashubtc/cdk/pull/891) +- Prepared send confirm [PR](https://github.com/cashubtc/cdk/pull/898) +- Increment keyset counter optimistically [PR](https://github.com/cashubtc/cdk/pull/885) +- fix: atomically increment keyset counter [PR](https://github.com/cashubtc/cdk/pull/897) +- Wallet event [PR](https://github.com/cashubtc/cdk/pull/806) +- cdk-sql-common [PR](https://github.com/cashubtc/cdk/pull/890) +- wallet keyset fns [PR](https://github.com/cashubtc/cdk/pull/901) +- add mint lifecycle management with start/stop methods [PR](https://github.com/cashubtc/cdk/pull/903) +- cdk-ldk-node [PR](https://github.com/cashubtc/cdk/pull/904) + +## Stalled +- Sig all [PR](https://github.com/cashubtc/cdk/pull/862) + + + +## Discuss +- bindings + - https://github.com/thesimplekid/cdk-ffi + - outbox table + - outbox pattern by inserting a row into an "outbox" table that contains the message to be sent to the LNBackend. Another process will select pending entries from this outbox and dispatch the message to the LN API. Once the message is successfully delivered, we need to update the entry in the outbox table and set its state to completed or failed, depending on the outcome. + - Sqlite -> postgresql migration + +## Next dev call + + +## Upcoming release plan +- v0.12 + - Bolt12 support + - cdk-ldk + - postgresql? diff --git a/meetings/2025-07-30-agenda.md b/meetings/2025-07-30-agenda.md new file mode 100644 index 000000000..1e53e8701 --- /dev/null +++ b/meetings/2025-07-30-agenda.md @@ -0,0 +1,26 @@ +# CDK Dev Call 19 +July 30th 2025 15:00 UTC + +Meeting Link: https://meet.fulmo.org/cdk-dev + +# Agenda + +## Merged +- Simplify flake [PR](https://github.com/cashubtc/cdk/pull/907) +- Mint stop start [PR](https://github.com/cashubtc/cdk/pull/903) +- Case of custom units [PR](https://github.com/cashubtc/cdk/pull/909) +- Nut19 wallet support [PR](https://github.com/cashubtc/cdk/pull/912) +- TransactionId panic [PR](https://github.com/cashubtc/cdk/pull/915) +- Get request by lookup id [PR](https://github.com/cashubtc/cdk/pull/917) +- Common sql [PR](https://github.com/cashubtc/cdk/pull/890) +- Payment parsing tests [PR](https://github.com/cashubtc/cdk/pull/920) + +## Opened +- Mintd as lib [PR](https://github.com/cashubtc/cdk/pull/914) +- RGLI [PR](https://github.com/cashubtc/cdk/pull/906) + +## In-progress +- cdk-ldk-node [PR](https://github.com/cashubtc/cdk/pull/904) (tsk) +- Prometheus crate [PR](https://github.com/cashubtc/cdk/pull/883) (asmo) +- Postgres [PR](https://github.com/cashubtc/cdk/pull/878) (crodas) +- wallet events [PR](https://github.com/cashubtc/cdk/pull/806) diff --git a/meetings/2025-08-05-agenda.md b/meetings/2025-08-05-agenda.md new file mode 100644 index 000000000..4cfaaab0d --- /dev/null +++ b/meetings/2025-08-05-agenda.md @@ -0,0 +1,20 @@ +# CDK Dev Call 20 +Aug 5th 2025 15:00 UTC + +Meeting Link: https://meet.fulmo.org/cdk-dev + +# Agenda +- DB Trait [PR](https://github.com/cashubtc/cdk/pull/931) +- FFI [PR](https://github.com/cashubtc/cdk/pull/932) + +## Merged +- Mintd as lib [PR](https://github.com/cashubtc/cdk/pull/914) + +## Opened + + +## In-progress +- cdk-ldk-node [PR](https://github.com/cashubtc/cdk/pull/904) (tsk) (done dealing with CI errors) +- Prometheus crate [PR](https://github.com/cashubtc/cdk/pull/883) (asmo) +- Postgres [PR](https://github.com/cashubtc/cdk/pull/878) (crodas) +- wallet events [PR](https://github.com/cashubtc/cdk/pull/806) diff --git a/meetings/2025-08-13-agenda.md b/meetings/2025-08-13-agenda.md new file mode 100644 index 000000000..d9f6c9642 --- /dev/null +++ b/meetings/2025-08-13-agenda.md @@ -0,0 +1,35 @@ +# CDK Dev Call 21 +Aug 13th 2025 15:00 UTC + +Meeting Link: https://meet.fulmo.org/cdk-dev + +# Agenda + +## Discuss + +- Better autoincrement for the wallet and the introduction of transactions all together, as the mint + + +## Merged +- External calls while db tx [PR](https://github.com/cashubtc/cdk/pull/954) +- Remove unused mint table [PR](https://github.com/cashubtc/cdk/pull/953) +- Counter at 0 [PR](https://github.com/cashubtc/cdk/pull/950) +- Nix cache [PR](https://github.com/cashubtc/cdk/pull/949) +- Explicit rollback [PR](https://github.com/cashubtc/cdk/pull/947) +- Run db [PR](https://github.com/cashubtc/cdk/pull/946) +- Empty db calls [PR](https://github.com/cashubtc/cdk/pull/943) + +## Opened +- Bump msrv [PR](https://github.com/cashubtc/cdk/pull/957) +- Fake mint multiple units [PR](https://github.com/cashubtc/cdk/pull/958) +- Wallet wait for invoice [Issue](https://github.com/cashubtc/cdk/issues/941) +- Wallet power of 2 [Issue](https://github.com/cashubtc/cdk/issues/955) +- Mint with description [Issue](https://github.com/cashubtc/cdk/issues/935) +- Wallet shouldn't retry on known error [Issue](https://github.com/cashubtc/cdk/issues/939) +- Atomic Keyset [PR](https://github.com/cashubtc/cdk/pull/944) + +## In-progress +- cdk-ldk-node [PR](https://github.com/cashubtc/cdk/pull/904) (tsk) (done dealing with CI errors) +- Prometheus crate [PR](https://github.com/cashubtc/cdk/pull/883) (asmo) +- Postgres [PR](https://github.com/cashubtc/cdk/pull/878) (crodas) +- wallet events [PR](https://github.com/cashubtc/cdk/pull/806) diff --git a/meetings/2025-08-20-agenda.md b/meetings/2025-08-20-agenda.md new file mode 100644 index 000000000..8ed7dc7d3 --- /dev/null +++ b/meetings/2025-08-20-agenda.md @@ -0,0 +1,41 @@ +# CDK Dev Call 22 +Aug 20th 2025 15:00 UTC + +Meeting Link: https://meet.fulmo.org/cdk-dev + +# Agenda + +## Discuss + +## Merged +- Bump msrv [PR](https://github.com/cashubtc/cdk/pull/957) +- Fake mint multiple units [PR](https://github.com/cashubtc/cdk/pull/958) +- Wallet wait for invoice [Issue](https://github.com/cashubtc/cdk/issues/941) +- Wallet shouldn't retry on known error [Issue](https://github.com/cashubtc/cdk/issues/939) +- Atomic Keyset [PR](https://github.com/cashubtc/cdk/pull/944) +- Postgres [PR](https://github.com/cashubtc/cdk/pull/878) (crodas) +- [#971](https://github.com/cashubtc/cdk/pull/971) - feat(cdk): allow minting less than paid amount for non-bolt11 payments +- [#967](https://github.com/cashubtc/cdk/pull/967) - feat: log to file +- [#971](https://github.com/cashubtc/cdk/pull/971) - feat(cdk): allow minting less than paid amount for non-bolt11 payments +- [#972](https://github.com/cashubtc/cdk/pull/972) - fix: bolt12 ws on mint +- [#974](https://github.com/cashubtc/cdk/pull/974) - feat: refresh keysets +- [#976](https://github.com/cashubtc/cdk/pull/976) - feat(cdk): add Bolt12 mint quote subscription support +- [#978](https://github.com/cashubtc/cdk/pull/978) - refactor(cdk): defer BOLT12 invoice fetching to payment execution + + +## Opened +- [#982](https://github.com/cashubtc/cdk/pull/982) - feat: cln as msats +- [#981](https://github.com/cashubtc/cdk/pull/981) - fix: lnbits payment check and units +- [#980](https://github.com/cashubtc/cdk/pull/980) - fix: reduce mmap_size to 5 MiB +- [#969](https://github.com/cashubtc/cdk/pull/969) - feat: bip353 +- [#965](https://github.com/cashubtc/cdk/pull/965) - chore(flake): add NIX_PATH for flake +- [#979](https://github.com/cashubtc/cdk/issues/979) - Secret Memory Leakage Due to Extensive Cloning + + +## In-progress +- cdk-ldk-node [PR](https://github.com/cashubtc/cdk/pull/904) (tsk) (done) +- Prometheus crate [PR](https://github.com/cashubtc/cdk/pull/883) (asmo) + +Next Milestone (0.12.0): + +https://github.com/cashubtc/cdk/milestone/14 diff --git a/meetings/2025-08-27-agenda.md b/meetings/2025-08-27-agenda.md new file mode 100644 index 000000000..a35d76284 --- /dev/null +++ b/meetings/2025-08-27-agenda.md @@ -0,0 +1,40 @@ +# CDK Dev Call 23 +Aug 27th 2025 15:00 UTC + +Meeting Link: https://meet.fulmo.org/cdk-dev + +# Agenda + +## Discuss + +## Merged +- [#982](https://github.com/cashubtc/cdk/pull/982) - feat: cln as msats +- [#981](https://github.com/cashubtc/cdk/pull/981) - fix: lnbits payment check and units +- [#980](https://github.com/cashubtc/cdk/pull/980) - fix: reduce mmap_size to 5 MiB +- [#969](https://github.com/cashubtc/cdk/pull/969) - feat: bip353 +- [#965](https://github.com/cashubtc/cdk/pull/965) - chore(flake): add NIX_PATH for flake +- [#979](https://github.com/cashubtc/cdk/issues/979) - Secret Memory Leakage Due to Extensive Cloning + - [#988](https://github.com/cashubtc/cdk/pull/988) - feat: zeroize cryptographic secrets on drop +- [#904](https://github.com/cashubtc/cdk/pull/904) - Cdk ldk node +- [#999](https://github.com/cashubtc/cdk/pull/999) - replace transports: Option> with just Vec +- [#998](https://github.com/cashubtc/cdk/pull/998) - feat: use trixie +- [#996](https://github.com/cashubtc/cdk/pull/996) - Fix p2pk +- [#991](https://github.com/cashubtc/cdk/pull/991) - fix: left-over `y` in blind_signatures table auth database +- [#989](https://github.com/cashubtc/cdk/pull/989) - Fixed bolt12 missing payments notifications +- [#987](https://github.com/cashubtc/cdk/pull/987) - refactor(cdk-lnbits): migrate to LNbits v1 websocket API and remove w… +- [#985](https://github.com/cashubtc/cdk/pull/985) - Introduce Future Streams for Payments and Minting Proofs +- https://github.com/cashubtc/cdk/milestone/14 + +## Opened +- [#984](https://github.com/cashubtc/cdk/pull/984) - compatibility for migrating Nutshell Mints +- [#995](https://github.com/cashubtc/cdk/pull/995) - onchain +- [#1005](https://github.com/cashubtc/cdk/pull/1005) - feat: redact secrets from Debug and Display impls +- [#1006](https://github.com/cashubtc/cdk/pull/1006) - Minor file organization +- [#1007](https://github.com/cashubtc/cdk/pull/1007) - Add support for Bolt12 notifications for HTTP subscription +- [#1002](https://github.com/cashubtc/cdk/pull/1002) - feat: add TLS support for PostgreSQL connections +- [#1003](https://github.com/cashubtc/cdk/pull/1003) - feat: LDK Lightning KVStore support with PostgreSQL integration +- [#1001](https://github.com/cashubtc/cdk/pull/1001) - MultiMintWallet Refactor +- [#1000](https://github.com/cashubtc/cdk/issues/1000) - Move most of this pay request logic to a cdk lib fn +- [#992](https://github.com/cashubtc/cdk/issues/992) - Emulate `NotificationPayload::MintQuoteBolt12Response` for http subscription + + diff --git a/meetings/2025-09-03-agenda.md b/meetings/2025-09-03-agenda.md new file mode 100644 index 000000000..936c5e4ed --- /dev/null +++ b/meetings/2025-09-03-agenda.md @@ -0,0 +1,50 @@ +# CDK Dev Call 24 +Sep 3th 2025 15:00 UTC + +Meeting Link: https://meet.fulmo.org/cdk-dev + +# Agenda + +## Discuss + +## Merged + +### Opened Last week +- [#984](https://github.com/cashubtc/cdk/pull/984) - compatibility for migrating Nutshell Mints +- [#1007](https://github.com/cashubtc/cdk/pull/1007) - Add support for Bolt12 notifications for HTTP subscription +- [#1002](https://github.com/cashubtc/cdk/pull/1002) - feat: add TLS support for PostgreSQL connections +- [#992](https://github.com/cashubtc/cdk/issues/992) - Emulate `NotificationPayload::MintQuoteBolt12Response` for http subscription + + +### New this week +- [#999](https://github.com/cashubtc/cdk/pull/999) - replace transports: Option> with just Vec +- [#1012](https://github.com/cashubtc/cdk/pull/1012) - Abstract the HTTP Transport +- [#1019](https://github.com/cashubtc/cdk/pull/1019) - refactor(payment): replace wait_any_incoming_payment with event +- [#1020](https://github.com/cashubtc/cdk/pull/1020) - fix: bolt12 is nut25 +- [#1021](https://github.com/cashubtc/cdk/pull/1021) - fix: cdk melt quote track payment method +- [#1023](https://github.com/cashubtc/cdk/pull/1023) - Fix missed events race when creating subscriptions +- [#1025](https://github.com/cashubtc/cdk/pull/1025) - fix: get all mint quotes +- [#1026](https://github.com/cashubtc/cdk/pull/1026) - refactor: use quote id to string + + +## Open + +### New +- [#1028](https://github.com/cashubtc/cdk/pull/1028) - chore: move `pay_request` logic into cdk lib +- [#1027](https://github.com/cashubtc/cdk/pull/1027) - UI rev4 +- [#1022](https://github.com/cashubtc/cdk/pull/1022) - feat(cdk): add generic key-value store functionality for mint databases +- [#1015](https://github.com/cashubtc/cdk/pull/1015) - add pubkey to mint info if not set +- [#1029](https://github.com/cashubtc/cdk/issues/1029) - Feature request cdk-wallet: store P2PK key and lookup automatically on token receive + +### Ongoing +- [#995](https://github.com/cashubtc/cdk/pull/995) - onchain +- [#1005](https://github.com/cashubtc/cdk/pull/1005) - feat: redact secrets from Debug and Display impls +- [#1006](https://github.com/cashubtc/cdk/pull/1006) - Minor file organization +- [#1003](https://github.com/cashubtc/cdk/pull/1003) - feat: LDK Lightning KVStore support with PostgreSQL integration + +- [#1000](https://github.com/cashubtc/cdk/issues/1000) - Move most of this pay request logic to a cdk lib fn + +## Needs Review +- [#1001](https://github.com/cashubtc/cdk/pull/1001) - MultiMintWallet Refactor + + diff --git a/meetings/2025-09-10-agenda.md b/meetings/2025-09-10-agenda.md new file mode 100644 index 000000000..8cc2379c0 --- /dev/null +++ b/meetings/2025-09-10-agenda.md @@ -0,0 +1,44 @@ +## Open + +### Merged + +- [#1027](https://github.com/cashubtc/cdk/pull/1027) - UI rev4 +- [#1022](https://github.com/cashubtc/cdk/pull/1022) - feat(cdk): add generic key-value store functionality for mint databases +- [#1015](https://github.com/cashubtc/cdk/pull/1015) - add pubkey to mint info if not set +- [#1061](https://github.com/cashubtc/cdk/pull/1061) - Do not fallback to HTTP on first error +- [#1059](https://github.com/cashubtc/cdk/pull/1059) - feat: remove unused ln_routers +- [#1058](https://github.com/cashubtc/cdk/pull/1058) - Fix Amount::split_with_fees +- [#1054](https://github.com/cashubtc/cdk/pull/1054) - fix: None `host_matcher` applies the proxy to all hosts +- [#1052](https://github.com/cashubtc/cdk/pull/1052) - feat: bolt12 ws +- [#1051](https://github.com/cashubtc/cdk/pull/1051) - fix: used check math +- [#1050](https://github.com/cashubtc/cdk/pull/1050) - Close websocket connections sooner +- [#1043](https://github.com/cashubtc/cdk/pull/1043) - Fix race conditions in minting tests +- [#1048](https://github.com/cashubtc/cdk/pull/1048) - Reorganize tests, add mint quote/payment coverage, and prevent over-issuing +- [#1041](https://github.com/cashubtc/cdk/pull/1041) - feat(cdk): add quote_id field to transactions for quote tracking +- [#1038](https://github.com/cashubtc/cdk/pull/1038) - fix: sig error code +- [#1037](https://github.com/cashubtc/cdk/pull/1037) - Fix postgres migration prefixes +- [#1032](https://github.com/cashubtc/cdk/pull/1032) - Update the signatory.proto file to match NUT-XXX +- [#932](https://github.com/cashubtc/cdk/pull/932) - FFI bindings for Wallet + + +### New +- [#1028](https://github.com/cashubtc/cdk/pull/1028) - chore: move `pay_request` logic into cdk lib +- [#1029](https://github.com/cashubtc/cdk/issues/1029) - Feature request cdk-wallet: store P2PK key and lookup automatically on token receive +- [#1064](https://github.com/cashubtc/cdk/pull/1064) - feat: per-request tor circuits with arti +- [#1060](https://github.com/cashubtc/cdk/pull/1060) - fix: replace std::time with web_time for wasm +- [#1055](https://github.com/cashubtc/cdk/pull/1055) - Include supported amounts instead of assuming the power of 2 +- [#1053](https://github.com/cashubtc/cdk/pull/1053) - feat: P2PK key storage and auto-sign on receive +- [#1045](https://github.com/cashubtc/cdk/pull/1045) - feat: store melt_request +- [#1031](https://github.com/cashubtc/cdk/pull/1031) - feat: prefer async melt + +### Ongoing +- [#995](https://github.com/cashubtc/cdk/pull/995) - onchain +- [#1005](https://github.com/cashubtc/cdk/pull/1005) - feat: redact secrets from Debug and Display impls +- [#1006](https://github.com/cashubtc/cdk/pull/1006) - Minor file organization +- [#1003](https://github.com/cashubtc/cdk/pull/1003) - feat: LDK Lightning KVStore support with PostgreSQL integration + + +- [#1000](https://github.com/cashubtc/cdk/issues/1000) - Move most of this pay request logic to a cdk lib fn + +## Needs Review +- [#1001](https://github.com/cashubtc/cdk/pull/1001) - MultiMintWallet Refactor diff --git a/meetings/2025-09-17-agenda.md b/meetings/2025-09-17-agenda.md new file mode 100644 index 000000000..304419fbc --- /dev/null +++ b/meetings/2025-09-17-agenda.md @@ -0,0 +1,47 @@ +Sep 17th 2025 15:00 UTC + +Meeting Link: https://meet.fulmo.org/cdk-dev + +### Merged +- [#1028](https://github.com/cashubtc/cdk/pull/1028) - chore: move `pay_request` logic into cdk lib +- [#1060](https://github.com/cashubtc/cdk/pull/1060) - fix: replace std::time with web_time for wasm +- [#1045](https://github.com/cashubtc/cdk/pull/1045) - feat: store melt_request +- [#1000](https://github.com/cashubtc/cdk/issues/1000) - Move most of this pay request logic to a cdk lib fn +- [#1079](https://github.com/cashubtc/cdk/pull/1079) - refactor: check mint request +- [#1078](https://github.com/cashubtc/cdk/pull/1078) - Fixed bug with postgres reconnection in the connection pool +- [#1077](https://github.com/cashubtc/cdk/pull/1077) - Store last pay index +- [#1075](https://github.com/cashubtc/cdk/pull/1075) - feat(cdk): add amount_mintable method and improve mint quote validation +- [#1073](https://github.com/cashubtc/cdk/pull/1073) - Improve web interface with dynamic status, navigation, and mobile support +- [#1071](https://github.com/cashubtc/cdk/pull/1071) - feat: update redb +- [#1070](https://github.com/cashubtc/cdk/pull/1070) - fix: keyset max order checked +- [#1069](https://github.com/cashubtc/cdk/pull/1069) - Fixed error with wrong placeholder +- [#1068](https://github.com/cashubtc/cdk/pull/1068) - Add `resolve_dns_txt` to HttpTransport and MintConnector +- [#1062](https://github.com/cashubtc/cdk/pull/1062) - fix: make http wallet subscriptions wasm compatible + +### Can merge +- [#1064](https://github.com/cashubtc/cdk/pull/1064) - feat: per-request tor circuits with arti +- [#1001](https://github.com/cashubtc/cdk/pull/1001) - MultiMintWallet Refactor + +## New +- [#1067](https://github.com/cashubtc/cdk/pull/1067) - Nutxx ohttp +- [#1076](https://github.com/cashubtc/cdk/pull/1076) - feat: balance for units cdk-cli +- [#1081](https://github.com/cashubtc/cdk/pull/1081) - fix: config overwrite on start up +- [#1084](https://github.com/cashubtc/cdk/pull/1084) - optional client identity in grpc payment processor +- [#1085](https://github.com/cashubtc/cdk/pull/1085) - Fix Async FFI Constructors + + +### Ongoing +- [#1055](https://github.com/cashubtc/cdk/pull/1055) - Include supported amounts instead of assuming the power of 2 +- [#1053](https://github.com/cashubtc/cdk/pull/1053) - feat: P2PK key storage and auto-sign on receive +- [#1031](https://github.com/cashubtc/cdk/pull/1031) - feat: prefer async melt + +### Discussion + +- Event based payment processor refactor (@thesimplekid) +- Event based wallet (@crodas / @thesimplekid) +- Web socket refactor (@crodas) + + + + +## Needs Review diff --git a/meetings/2025-09-24-agenda.md b/meetings/2025-09-24-agenda.md new file mode 100644 index 000000000..22194604b --- /dev/null +++ b/meetings/2025-09-24-agenda.md @@ -0,0 +1,49 @@ +Sep 24th 2025 15:00 UTC + +Meeting Link: https://meet.fulmo.org/cdk-dev + + + + +## Merged +- [#1067](https://github.com/cashubtc/cdk/pull/1067) - Nutxx ohttp +- [#1076](https://github.com/cashubtc/cdk/pull/1076) - feat: balance for units cdk-cli +- [#1081](https://github.com/cashubtc/cdk/pull/1081) - fix: config overwrite on start up +- [#1084](https://github.com/cashubtc/cdk/pull/1084) - optional client identity in grpc payment processor +- [#1085](https://github.com/cashubtc/cdk/pull/1085) - Fix Async FFI Constructors +- [#1055](https://github.com/cashubtc/cdk/pull/1055) - Include supported amounts instead of assuming the power of 2 +- [#1090](https://github.com/cashubtc/cdk/pull/1090) - fix: error response detail +- [#1091](https://github.com/cashubtc/cdk/pull/1091) - fix: add free space to auth test +- [#1095](https://github.com/cashubtc/cdk/pull/1095) - Psgl auth db +- [#1096](https://github.com/cashubtc/cdk/pull/1096) - feat: remove redis cache +- [#1097](https://github.com/cashubtc/cdk/pull/1097) - Remove generated files +- [#1099](https://github.com/cashubtc/cdk/pull/1099) - fix(cdk): improve error handling when adding mint to MultiMintWallet +- [#1101](https://github.com/cashubtc/cdk/pull/1101) - add FFI types for NUT-04 and NUT-05 +- [#1102](https://github.com/cashubtc/cdk/pull/1102) - Remove cashu ffi +- [#1103](https://github.com/cashubtc/cdk/pull/1103) - feat: remove features from auth +- [#1108](https://github.com/cashubtc/cdk/pull/1108) - feat(docker): add LDK Node mint service with dedicated Docker setup + +## Released +- https://github.com/cashubtc/cdk/releases/tag/v0.13.0 + + +### Updated +- [#1064](https://github.com/cashubtc/cdk/pull/1064) - feat: per-request tor circuits with arti + +### Ongoing + +- [#1053](https://github.com/cashubtc/cdk/pull/1053) - feat: P2PK key storage and auto-sign on receive +- [#1031](https://github.com/cashubtc/cdk/pull/1031) - feat: prefer async melt + + +### New +- [#1111](https://github.com/cashubtc/cdk/issues/1111) - cdk wallet not closing ws connections +- [#1105](https://github.com/cashubtc/cdk/issues/1105) - Workspace cashu dep should not have default features +- [#1104](https://github.com/cashubtc/cdk/issues/1104) - New websocket subscriptions should check mint quote states +- [#1082](https://github.com/cashubtc/cdk/issues/1082) - Broken Link for cdk-python in the cdk-ffi/ README -> goes to 404 +- [#1109](https://github.com/cashubtc/cdk/pull/1109) - fix: handle fiat melt amount conversions +- [#1098](https://github.com/cashubtc/cdk/pull/1098) - Introduce a generic pubsub mod in `cdk-common` +- [#1100](https://github.com/cashubtc/cdk/pull/1100) - NUT-XX: Cairo Spending Conditions implementation +- [#1110](https://github.com/cashubtc/cdk/pull/1110) - feat: optimize SQL balance calculation +- [#1112](https://github.com/cashubtc/cdk/pull/1112) - Check change unique + diff --git a/meetings/2025-10-08-agenda.md b/meetings/2025-10-08-agenda.md new file mode 100644 index 000000000..335c38713 --- /dev/null +++ b/meetings/2025-10-08-agenda.md @@ -0,0 +1,45 @@ +Oct 8th 2025 15:00 UTC + +Meeting Link: https://meet.fulmo.org/cdk-dev + +## Merged +- [#1064](https://github.com/cashubtc/cdk/pull/1064) - feat: per-request tor circuits with arti +- [#1111](https://github.com/cashubtc/cdk/issues/1111) - cdk wallet not closing ws connections +- [#1109](https://github.com/cashubtc/cdk/pull/1109) - fix: handle fiat melt amount conversions +- [#1098](https://github.com/cashubtc/cdk/pull/1098) - Introduce a generic pubsub mod in `cdk-common` +- [#1112](https://github.com/cashubtc/cdk/pull/1112) - Check change unique +- [#1142](https://github.com/cashubtc/cdk/pull/1142) - Split uniffi types into multiple mods +- [#1144](https://github.com/cashubtc/cdk/pull/1144) - Fix bug with websocket close +- [#1146](https://github.com/cashubtc/cdk/pull/1146) - Add MultiMintWallet check and wait for mint quotes +- [#1147](https://github.com/cashubtc/cdk/pull/1147) - Make sorting Transactions a stable sort +- [#1148](https://github.com/cashubtc/cdk/pull/1148) - Allow passing metadata to a melt +- [#1152](https://github.com/cashubtc/cdk/pull/1152) - feat: optimize SQL balance calculation +- [#1155](https://github.com/cashubtc/cdk/pull/1155) - feat(cdk): add payment request and proof to transaction records +- [#1158](https://github.com/cashubtc/cdk/pull/1158) - fix(cashu): skip serializing empty NUT15 settings in mint info +- [#1159](https://github.com/cashubtc/cdk/pull/1159) - mintd: remove non-existent stdout logging from docs +- [#1161](https://github.com/cashubtc/cdk/pull/1161) - fix(database): add parent directory validation before database creation +- [#1167](https://github.com/cashubtc/cdk/pull/1167) - chore: nostr-sdk as workspace dep +- [#1168](https://github.com/cashubtc/cdk/pull/1168) - chore: remove ctor + + +## Released +- https://github.com/cashubtc/cdk/releases/tag/v0.13.1 + + +### Updated + + +### Ongoing + +- [#1053](https://github.com/cashubtc/cdk/pull/1053) - feat: P2PK key storage and auto-sign on receive + +### New +- [#1166](https://github.com/cashubtc/cdk/pull/1166) - Read the latest mint quote status in a transaction to avoid race conditions +- [#1164](https://github.com/cashubtc/cdk/pull/1164) - Improve add transaction +- [#1127](https://github.com/cashubtc/cdk/pull/1127) - rename ln settings in toml configuration +- [#1118](https://github.com/cashubtc/cdk/pull/1118) - feat: uniffi bindings for golang +- [#1132](https://github.com/cashubtc/cdk/pull/1132) - Quote id as lookup +- [#1153](https://github.com/cashubtc/cdk/pull/1153) - Add cdk-mintd module and package +- [#1171](https://github.com/cashubtc/cdk/pull/1171) - Add Dart Bindings Support +- [#1173](https://github.com/cashubtc/cdk/pull/1173) - Prefer async + diff --git a/meetings/2025-10-15-agenda.md b/meetings/2025-10-15-agenda.md new file mode 100644 index 000000000..6b61ce2f7 --- /dev/null +++ b/meetings/2025-10-15-agenda.md @@ -0,0 +1,39 @@ +Oct 15th 2025 15:00 UTC + +Meeting Link: https://meet.fulmo.org/cdk-dev + +## Merged +- [#1166](https://github.com/cashubtc/cdk/pull/1166) - Read the latest mint quote status in a transaction to avoid race conditions +- [#1164](https://github.com/cashubtc/cdk/pull/1164) - Improve add transaction +- [#1177](https://github.com/cashubtc/cdk/pull/1177) - Configure internal Wallets of a MultiMintWallet +- [#1179](https://github.com/cashubtc/cdk/pull/1179) - Remove the `amounts` from amounts +- [#1187](https://github.com/cashubtc/cdk/pull/1187) - feat: swap tests +- [#1188](https://github.com/cashubtc/cdk/pull/1188) - feat(cdk): add melt quote state transition validation +- [#1166](https://github.com/cashubtc/cdk/pull/1166) - Read the latest mint quote status in a transaction to avoid race conditions + + +### Ongoing + +- [#1053](https://github.com/cashubtc/cdk/pull/1053) - feat: P2PK key storage and auto-sign on receive +- [#1127](https://github.com/cashubtc/cdk/pull/1127) - rename ln settings in toml configuration +- [#1118](https://github.com/cashubtc/cdk/pull/1118) - feat: uniffi bindings for golang +- [#1132](https://github.com/cashubtc/cdk/pull/1132) - Quote id as lookup +- [#1153](https://github.com/cashubtc/cdk/pull/1153) - Add cdk-mintd module and package +- [#1171](https://github.com/cashubtc/cdk/pull/1171) - Add Dart Bindings Support +- [#1149](https://github.com/cashubtc/cdk/pull/1149) - Update FFI Database Objects to Records + +### New +#### Issues +- [#1191](https://github.com/cashubtc/cdk/issues/1191) - mintd: Error: Internal Empty SQL > v0.11.1 +- [#1189](https://github.com/cashubtc/cdk/issues/1189) - wallet add db fn to get pending melt quotes +- [#1172](https://github.com/cashubtc/cdk/issues/1172) - cdk-cli: mint pending command maybe broken +- [#1180](https://github.com/cashubtc/cdk/issues/1180) - Stored proofs remain in pending state when melt fails due to mint's maximum proof limit +#### PRs +- [#1181](https://github.com/cashubtc/cdk/pull/1181) - Deterministic Currency Unit Derivation Paths +- [#1182](https://github.com/cashubtc/cdk/pull/1182) - ehash: add support for mining share mint quotes +- [#1190](https://github.com/cashubtc/cdk/pull/1190) - feat(cashu): add NUT-26 bech32m encoding for payment requests +- [#1183](https://github.com/cashubtc/cdk/pull/1183) - Swap saga +- [#1186](https://github.com/cashubtc/cdk/pull/1186) - Melt saga +- [#1192](https://github.com/cashubtc/cdk/pull/1192) - Melt async saga + + diff --git a/meetings/2025-10-27-agenda.md b/meetings/2025-10-27-agenda.md new file mode 100644 index 000000000..b1c7f029c --- /dev/null +++ b/meetings/2025-10-27-agenda.md @@ -0,0 +1,57 @@ +# CDK Development Meeting + +Oct 27 2025 19:58 UTC + +Meeting Link: https://meet.fulmo.org/cdk-dev + +## Merged + +- [#1213](https://github.com/cashubtc/cdk/pull/1213) - ffix: improve Melted error handling and add debug logging +- [#1207](https://github.com/cashubtc/cdk/pull/1207) - feat: update stable rust +- [#1183](https://github.com/cashubtc/cdk/pull/1183) - Swap saga +- [#1149](https://github.com/cashubtc/cdk/pull/1149) - Update FFI Database Objects to Records + +## Ongoing + +- [#1196](https://github.com/cashubtc/cdk/pull/1196) - feat(ci): add merge queue workflow and simplify clippy checks +- [#1192](https://github.com/cashubtc/cdk/pull/1192) - Melt async saga +- [#1190](https://github.com/cashubtc/cdk/pull/1190) - feat(cashu): add NUT-26 bech32m encoding for payment requests +- [#1186](https://github.com/cashubtc/cdk/pull/1186) - Melt saga +- [#1182](https://github.com/cashubtc/cdk/pull/1182) - ehash: add support for mining share mint quotes +- [#1181](https://github.com/cashubtc/cdk/pull/1181) - Deterministic Currency Unit Derivation Paths +- [#1173](https://github.com/cashubtc/cdk/pull/1173) - Prefer async +- [#1171](https://github.com/cashubtc/cdk/pull/1171) - Add Dart Bindings Support +- [#1153](https://github.com/cashubtc/cdk/pull/1153) - Add cdk-mintd module and package +- [#1132](https://github.com/cashubtc/cdk/pull/1132) - Quote id as lookup +- [#1127](https://github.com/cashubtc/cdk/pull/1127) - rename ln settings in toml configuration +- [#1118](https://github.com/cashubtc/cdk/pull/1118) - feat: uniffi bindings for golang +- [#1100](https://github.com/cashubtc/cdk/pull/1100) - NUT-XX: Cairo Spending Conditions implementation +- [#1067](https://github.com/cashubtc/cdk/pull/1067) - Nutxx ohttp +- [#1053](https://github.com/cashubtc/cdk/pull/1053) - feat: P2PK key storage and auto-sign on receive +- [#1049](https://github.com/cashubtc/cdk/pull/1049) - feat: ldk-node run mintd + +## New + +### Issues + +- [#1209](https://github.com/cashubtc/cdk/issues/1209) - Fix issue with websocket +- [#1205](https://github.com/cashubtc/cdk/issues/1205) - cdk-kotlin we need to check the page size is set correctly there is a change coming up to the google play store +- [#1203](https://github.com/cashubtc/cdk/issues/1203) - Update the Database trait for wallet and support for transactions +- [#1199](https://github.com/cashubtc/cdk/issues/1199) - Remove auth feature and just always include auth fns + +### PRs + +- [#1217](https://github.com/cashubtc/cdk/pull/1217) - Typo fix +- [#1216](https://github.com/cashubtc/cdk/pull/1216) - Add Spark SDK as a nodeless backend for CDK mints +- [#1215](https://github.com/cashubtc/cdk/pull/1215) - feat: backport bot +- [#1214](https://github.com/cashubtc/cdk/pull/1214) - feat(cdk-payment-processor): add currency unit parameter to make_payment +- [#1212](https://github.com/cashubtc/cdk/pull/1212) - Various mint fixes for swap. SIG_INPUTS+SIG_ALL, locktimes, P2PK+HTLC. Also updates the SIG_ALL message for amount-switching +- [#1211](https://github.com/cashubtc/cdk/pull/1211) - Regtest setup +- [#1210](https://github.com/cashubtc/cdk/pull/1210) - test: add mutation testing infrastructure +- [#1208](https://github.com/cashubtc/cdk/pull/1208) - Sig all fixes +- [#1206](https://github.com/cashubtc/cdk/pull/1206) - fix: sig_all_msg_to_sign +- [#1204](https://github.com/cashubtc/cdk/pull/1204) - Add database transaction trait for cdk wallet +- [#1202](https://github.com/cashubtc/cdk/pull/1202) - Onchain +- [#1201](https://github.com/cashubtc/cdk/pull/1201) - feat: npubcash +- [#1200](https://github.com/cashubtc/cdk/pull/1200) - feat: optimize pending mint quotes query performance +- [#1198](https://github.com/cashubtc/cdk/pull/1198) - fix: check the removed_ys argument before creating the delete query From 18a41e55af250089c34ea2c24843b522faa6d565 Mon Sep 17 00:00:00 2001 From: tsk Date: Mon, 27 Oct 2025 18:59:46 -0400 Subject: [PATCH 232/321] feat: backport bot (#1215) --- .backportrc.json | 7 ++ .github/templates/failed-backport-issue.md | 8 +++ .github/workflows/backport.yml | 68 +++++++++++++++++++ DEVELOPMENT.md | 79 ++++++++++++++++++++++ 4 files changed, 162 insertions(+) create mode 100644 .backportrc.json create mode 100644 .github/templates/failed-backport-issue.md create mode 100644 .github/workflows/backport.yml diff --git a/.backportrc.json b/.backportrc.json new file mode 100644 index 000000000..7978aa601 --- /dev/null +++ b/.backportrc.json @@ -0,0 +1,7 @@ +{ + "repoOwner": "cashubtc", + "repoName": "cdk", + "targetBranchChoices": ["v0.10.x", "v0.11.x", "v0.12.x", "v0.13.x"], + "autoMerge": false, + "autoMergeMethod": "merge" +} diff --git a/.github/templates/failed-backport-issue.md b/.github/templates/failed-backport-issue.md new file mode 100644 index 000000000..9e0b9c7af --- /dev/null +++ b/.github/templates/failed-backport-issue.md @@ -0,0 +1,8 @@ +--- +title: Backport PR `#{{ env.PR_NUMBER }}` {{ env.SHORT_PR_TITLE }} +labels: backport +--- +PR: #{{ env.PR_NUMBER }} +Title: {{ env.PR_TITLE }} + +The backport bot failed. Please open a PR to backport these changes. diff --git a/.github/workflows/backport.yml b/.github/workflows/backport.yml new file mode 100644 index 000000000..4ef28a002 --- /dev/null +++ b/.github/workflows/backport.yml @@ -0,0 +1,68 @@ +name: Backport merged pull request +on: + pull_request_target: + # Run on merge (close) or if label is added after merging + types: [closed, labeled] + +# Set concurrency limit to a single backport workflow per branch +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + backport: + permissions: + contents: write # so it can comment + pull-requests: write # so it can create pull requests + name: Backport pull request + runs-on: ubuntu-latest + + # Don't run on closed unmerged pull requests or if a non-backport label is added + if: | + github.event.pull_request.merged && + ( + github.event.action != 'labeled' || + contains(github.event.label.name, 'backport') + ) + + outputs: + was_successful: ${{ steps.create-pr.outputs.was_successful }} + + steps: + - uses: actions/checkout@v4 + - id: create-pr + name: Create backport pull requests + uses: korthout/backport-action@v3 + with: + repo-token: ${{ secrets.GITHUB_TOKEN }} + + open-issue: + permissions: + contents: read + issues: write + name: Open issue for failed backports + runs-on: ubuntu-latest + needs: backport + + # Open an issue only if the backport job failed + if: ${{ needs.backport.outputs.was_successful == 'false' }} + + steps: + - uses: actions/checkout@v4 + - name: Set SHORT_PR_TITLE env + run: | + SHORT_PR_TITLE=$( + echo '${{ github.event.pull_request.title }}' \ + | awk '{print (length($0) > 40) ? substr($0, 1, 40) "..." : $0}' + ) + echo "SHORT_PR_TITLE=$SHORT_PR_TITLE" >> "$GITHUB_ENV" + + - name: Create issue + uses: JasonEtco/create-an-issue@v2 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + PR_NUMBER: ${{ github.event.number }} + PR_TITLE: ${{ github.event.pull_request.title }} + SHORT_PR_TITLE: ${{ env.SHORT_PR_TITLE }} + with: + filename: .github/templates/failed-backport-issue.md diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 3ba67cd22..61db2d358 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -226,6 +226,85 @@ just final-check 4. Submit a pull request 5. Wait for review and address feedback +## Backporting Changes + +CDK uses an automated backport bot to help maintain stable release branches. This section explains how the backport process works. + +### How the Backport Bot Works + +The backport bot creates pull requests to backport merged changes from `main` to stable release branches. **You control which branches to backport to by adding labels to your PR.** + +**Available Target Branches:** +- `v0.10.x` +- `v0.11.x` +- `v0.12.x` +- `v0.13.x` + +### Using Backport Labels + +To backport a PR to specific stable branches, add labels to your PR **before or after merging**: + +**Label Format:** +- `backport v0.13.x` - backports to v0.13.x branch +- `backport v0.12.x` - backports to v0.12.x branch +- Add multiple labels to backport to multiple branches + +**Example Workflow:** +1. Create and merge your PR to `main` +2. Add label `backport v0.13.x` to the PR +3. The bot automatically creates a backport PR for the v0.13.x branch +4. Review and merge the backport PR +5. Repeat for other branches as needed + +**When to Add Labels:** +- Add labels before merging - backport PRs are created automatically on merge +- Add labels after merging - backport PRs are created when you add the label +- You can add multiple backport labels at once + +### When Backports Fail + +Sometimes the backport bot cannot automatically create a backport PR due to merge conflicts or other issues. When this happens: + +1. The bot automatically creates a GitHub issue labeled with `backport` +2. The issue will contain details about the original PR and which branch(es) failed +3. You'll need to manually create the backport PR for the failed branch + +**Manual Backporting Process:** +```bash +# Checkout the target stable branch +git checkout v0.13.x +git pull origin v0.13.x + +# Create a new branch for the backport +git checkout -b backport-pr-NUMBER-to-v0.13.x + +# Cherry-pick the commits from the original PR +git cherry-pick COMMIT_HASH + +# Resolve any conflicts if they occur +# Then push and create a PR +git push origin backport-pr-NUMBER-to-v0.13.x +``` + +### Best Practices for Backporting + +1. **Label Appropriately:** Only add backport labels for changes that should be in stable branches +2. **Keep PRs Focused:** Smaller, focused PRs are easier to backport automatically +3. **Review Backport PRs:** Always review automatically created backport PRs to ensure they're appropriate +4. **Test Backports:** Run tests on backport PRs just like regular PRs +5. **Address Conflicts Promptly:** If a backport fails, address it promptly or close the issue with an explanation + +### When NOT to Backport + +Not all changes should be backported to stable branches. **Don't add backport labels** for: +- Breaking API changes +- New features that aren't needed in older versions +- Changes that don't apply to older version branches +- Large refactorings +- Experimental or unstable features + +If a backport isn't appropriate, simply don't add the backport label to the PR. + ## Additional Resources - [Nix Documentation](https://nixos.org/manual/nix/stable/) From eb65e7603fecae9d1f4f3e0f8df98b32ec096014 Mon Sep 17 00:00:00 2001 From: tsk Date: Mon, 27 Oct 2025 19:07:06 -0400 Subject: [PATCH 233/321] fix: backport token (#1219) --- .github/workflows/backport.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/backport.yml b/.github/workflows/backport.yml index 4ef28a002..0b9729a58 100644 --- a/.github/workflows/backport.yml +++ b/.github/workflows/backport.yml @@ -34,7 +34,7 @@ jobs: name: Create backport pull requests uses: korthout/backport-action@v3 with: - repo-token: ${{ secrets.GITHUB_TOKEN }} + github_token: ${{ secrets.GITHUB_TOKEN }} open-issue: permissions: From 26b2688c3e9995f0dc1637cf517fc829390ffabf Mon Sep 17 00:00:00 2001 From: tsk Date: Mon, 27 Oct 2025 19:10:47 -0400 Subject: [PATCH 234/321] fix: con grup (#1220) --- .github/workflows/backport.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/backport.yml b/.github/workflows/backport.yml index 0b9729a58..2e36e2432 100644 --- a/.github/workflows/backport.yml +++ b/.github/workflows/backport.yml @@ -4,9 +4,9 @@ on: # Run on merge (close) or if label is added after merging types: [closed, labeled] -# Set concurrency limit to a single backport workflow per branch +# Set concurrency limit to a single backport workflow per PR concurrency: - group: ${{ github.workflow }}-${{ github.ref }} + group: ${{ github.workflow }}-${{ github.event.pull_request.number }} cancel-in-progress: true jobs: From 5b1e079e5fc5a3719bd44c405556b61af1958e4d Mon Sep 17 00:00:00 2001 From: tsk Date: Mon, 27 Oct 2025 19:25:32 -0400 Subject: [PATCH 235/321] feat: tests of backport prs (#1224) --- .github/workflows/ci.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5ae04f89c..96be7a9c6 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -4,7 +4,9 @@ on: push: branches: [main] pull_request: - branches: [main] + branches: + - main + - 'v[0-9]+.[0-9]+.x' # Match version branches like v0.13.x, v1.0.x, etc. release: types: [created] From c43ea9507ee29e9ccdb5623fd783cd97c1ef174f Mon Sep 17 00:00:00 2001 From: tsk Date: Tue, 28 Oct 2025 11:20:10 -0400 Subject: [PATCH 236/321] fix: use back port toekn (#1231) --- .github/workflows/backport.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/backport.yml b/.github/workflows/backport.yml index 2e36e2432..57e88a9f8 100644 --- a/.github/workflows/backport.yml +++ b/.github/workflows/backport.yml @@ -34,7 +34,7 @@ jobs: name: Create backport pull requests uses: korthout/backport-action@v3 with: - github_token: ${{ secrets.GITHUB_TOKEN }} + github_token: ${{ secrets.BACKPORT_TOKEN }} open-issue: permissions: From e44c83fb99d72224b0188ecfa36d8f5b623c5f63 Mon Sep 17 00:00:00 2001 From: gandlafbtc <123852829+gandlafbtc@users.noreply.github.com> Date: Wed, 29 Oct 2025 00:21:44 +0900 Subject: [PATCH 237/321] added missing env params in docker-compose.ldk-node.yaml (#1230) --- docker-compose.ldk-node.yaml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docker-compose.ldk-node.yaml b/docker-compose.ldk-node.yaml index c46430a47..6893b8b07 100644 --- a/docker-compose.ldk-node.yaml +++ b/docker-compose.ldk-node.yaml @@ -46,6 +46,7 @@ services: container_name: mint-ldk-node ports: - "8085:8085" + - "8091:8091" # LDK admin dashboard environment: - CDK_MINTD_URL=https://example.com - CDK_MINTD_LN_BACKEND=ldk-node @@ -69,6 +70,9 @@ services: - CDK_MINTD_LDK_NODE_NETWORK=testnet - CDK_MINTD_LDK_NODE_ESPLORA_URL=https://blockstream.info/testnet/api - CDK_MINTD_LDK_NODE_LISTENING_ADDRESSES=0.0.0.0:9735 + # LDK admin dashboard config + - CDK_MINTD_LDK_NODE_WEBSERVER_HOST=0.0.0.0 + # - CDK_MINTD_LDK_NODE_WEBSERVER_PORT= volumes: # Persist LDK node data - ldk_node_data:/usr/src/app/ldk_node_data From 3a99582c049b049a68060e08dee399455b3bfcf0 Mon Sep 17 00:00:00 2001 From: tsk Date: Tue, 28 Oct 2025 12:57:54 -0400 Subject: [PATCH 238/321] fix: branches for ci (#1233) --- .github/workflows/ci.yml | 2 +- .github/workflows/nutshell_itest.yml | 10 +++++++++- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 96be7a9c6..ae9be54c8 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -6,7 +6,7 @@ on: pull_request: branches: - main - - 'v[0-9]+.[0-9]+.x' # Match version branches like v0.13.x, v1.0.x, etc. + - 'v[0-9]*.[0-9]*.x' # Match version branches like v0.13.x, v1.0.x, etc. release: types: [created] diff --git a/.github/workflows/nutshell_itest.yml b/.github/workflows/nutshell_itest.yml index d967837c1..a572d2cff 100644 --- a/.github/workflows/nutshell_itest.yml +++ b/.github/workflows/nutshell_itest.yml @@ -1,6 +1,14 @@ name: Nutshell integration -on: [push, pull_request] +on: + push: + branches: [main] + pull_request: + branches: + - main + - 'v[0-9]*.[0-9]*.x' # Match version branches like v0.13.x, v1.0.x, etc. + release: + types: [created] jobs: nutshell-integration-tests: From ad4df779e3267c4875e58dc154cdbe921471f939 Mon Sep 17 00:00:00 2001 From: tsk Date: Tue, 28 Oct 2025 21:33:46 -0400 Subject: [PATCH 239/321] feat(cdk-lnbits): add websocket reconnection with exponential backoff (#1237) Implement automatic reconnection logic when LNbits websocket connection is lost, using exponential backoff strategy (1s to 30s max) with automatic resubscription --- crates/cdk-lnbits/Cargo.toml | 2 +- crates/cdk-lnbits/src/lib.rs | 64 +++++++++++++++++++++++++++--------- 2 files changed, 50 insertions(+), 16 deletions(-) diff --git a/crates/cdk-lnbits/Cargo.toml b/crates/cdk-lnbits/Cargo.toml index 5429a0377..9b0050bcf 100644 --- a/crates/cdk-lnbits/Cargo.toml +++ b/crates/cdk-lnbits/Cargo.toml @@ -20,6 +20,6 @@ tokio.workspace = true tokio-util.workspace = true tracing.workspace = true thiserror.workspace = true -lnbits-rs = "0.8.0" +lnbits-rs = "0.9.1" serde_json.workspace = true rustls.workspace = true diff --git a/crates/cdk-lnbits/src/lib.rs b/crates/cdk-lnbits/src/lib.rs index fec078c39..023246041 100644 --- a/crates/cdk-lnbits/src/lib.rs +++ b/crates/cdk-lnbits/src/lib.rs @@ -163,23 +163,57 @@ impl MintPayment for LNbits { let is_active = Arc::clone(&self.wait_invoice_is_active); Ok(Box::pin(futures::stream::unfold( - (api, cancel_token, is_active), - |(api, cancel_token, is_active)| async move { + (api, cancel_token, is_active, 0u32), + |(api, cancel_token, is_active, mut retry_count)| async move { is_active.store(true, Ordering::SeqCst); - let receiver = api.receiver(); - let mut receiver = receiver.lock().await; - - tokio::select! { - _ = cancel_token.cancelled() => { - is_active.store(false, Ordering::SeqCst); - tracing::info!("Waiting for lnbits invoice ending"); - None - } - msg_option = receiver.recv() => { - Self::process_message(msg_option, &api, &is_active) - .await - .map(|response| (Event::PaymentReceived(response), (api, cancel_token, is_active))) + loop { + tracing::debug!("LNbits: Starting wait loop, attempting to get receiver"); + let receiver = api.receiver(); + let mut receiver = receiver.lock().await; + tracing::debug!("LNbits: Got receiver lock, waiting for messages"); + + tokio::select! { + _ = cancel_token.cancelled() => { + is_active.store(false, Ordering::SeqCst); + tracing::info!("Waiting for lnbits invoice ending"); + return None; + } + msg_option = receiver.recv() => { + tracing::debug!("LNbits: Received message from websocket: {:?}", msg_option.as_ref().map(|_| "Some(message)")); + match msg_option { + Some(_) => { + // Successfully received a message, reset retry count + retry_count = 0; + let result = Self::process_message(msg_option, &api, &is_active).await; + return result.map(|response| { + (Event::PaymentReceived(response), (api, cancel_token, is_active, retry_count)) + }); + } + None => { + // Connection lost, need to reconnect + drop(receiver); // Drop the lock before reconnecting + + tracing::warn!("LNbits websocket connection lost (receiver returned None), attempting to reconnect..."); + + // Exponential backoff: 1s, 2s, 4s, 8s, max 10s + let backoff_secs = std::cmp::min(2u64.pow(retry_count), 10); + tracing::info!("Retrying in {} seconds (attempt {})", backoff_secs, retry_count + 1); + tokio::time::sleep(std::time::Duration::from_secs(backoff_secs)).await; + + // Attempt to resubscribe + if let Err(err) = api.subscribe_to_websocket().await { + tracing::error!("Failed to resubscribe to LNbits websocket: {:?}", err); + } else { + tracing::info!("Successfully reconnected to LNbits websocket"); + } + + retry_count += 1; + // Continue the loop to try again + continue; + } + } + } } } }, From cc1c7f1ada6a5fd0470db9595e066dbf138b2935 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 29 Oct 2025 15:36:26 -0400 Subject: [PATCH 240/321] chore: add weekly meeting agenda for 2025-10-29 (#1239) Co-authored-by: github-actions[bot] --- meetings/2025-10-29-agenda.md | 62 +++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 meetings/2025-10-29-agenda.md diff --git a/meetings/2025-10-29-agenda.md b/meetings/2025-10-29-agenda.md new file mode 100644 index 000000000..495338053 --- /dev/null +++ b/meetings/2025-10-29-agenda.md @@ -0,0 +1,62 @@ +# CDK Development Meeting + +Oct 29 2025 12:41 UTC + +Meeting Link: https://meet.fulmo.org/cdk-dev + +## Merged + +- [#1237](https://github.com/cashubtc/cdk/pull/1237) - feat(cdk-lnbits): add websocket reconnection with exponential backoff +- [#1230](https://github.com/cashubtc/cdk/pull/1230) - added missing env params in docker-compose.ldk-node.yaml +- [#1220](https://github.com/cashubtc/cdk/pull/1220) - fix: con group +- [#1219](https://github.com/cashubtc/cdk/pull/1219) - Backports +- [#1218](https://github.com/cashubtc/cdk/pull/1218) - feat: add auto generated meetings template +- [#1215](https://github.com/cashubtc/cdk/pull/1215) - feat: backport bot +- [#1213](https://github.com/cashubtc/cdk/pull/1213) - ffix: improve Melted error handling and add debug logging +- [#1207](https://github.com/cashubtc/cdk/pull/1207) - feat: update stable rust +- [#1183](https://github.com/cashubtc/cdk/pull/1183) - Swap saga +- [#1149](https://github.com/cashubtc/cdk/pull/1149) - Update FFI Database Objects to Records + +## Ongoing + +- [#1200](https://github.com/cashubtc/cdk/pull/1200) - feat: optimize pending mint quotes query performance +- [#1198](https://github.com/cashubtc/cdk/pull/1198) - fix: check the removed_ys argument before creating the delete query +- [#1196](https://github.com/cashubtc/cdk/pull/1196) - feat(ci): add merge queue workflow and simplify clippy checks +- [#1190](https://github.com/cashubtc/cdk/pull/1190) - feat(cashu): add NUT-26 bech32m encoding for payment requests +- [#1186](https://github.com/cashubtc/cdk/pull/1186) - Melt saga +- [#1182](https://github.com/cashubtc/cdk/pull/1182) - ehash: add support for mining share mint quotes +- [#1181](https://github.com/cashubtc/cdk/pull/1181) - Deterministic Currency Unit Derivation Paths +- [#1173](https://github.com/cashubtc/cdk/pull/1173) - Prefer async +- [#1171](https://github.com/cashubtc/cdk/pull/1171) - Add Dart Bindings Support +- [#1153](https://github.com/cashubtc/cdk/pull/1153) - Add cdk-mintd module and package +- [#1132](https://github.com/cashubtc/cdk/pull/1132) - Quote id as lookup +- [#1127](https://github.com/cashubtc/cdk/pull/1127) - rename ln settings in toml configuration +- [#1118](https://github.com/cashubtc/cdk/pull/1118) - feat: uniffi bindings for golang +- [#1067](https://github.com/cashubtc/cdk/pull/1067) - Nutxx ohttp +- [#1053](https://github.com/cashubtc/cdk/pull/1053) - feat: P2PK key storage and auto-sign on receive +- [#1049](https://github.com/cashubtc/cdk/pull/1049) - feat: ldk-node run mintd +- [#1011](https://github.com/cashubtc/cdk/pull/1011) - fix: migrate check_mint_quote_paid fn from ln.rs to mod.rs +- [#1010](https://github.com/cashubtc/cdk/pull/1010) - adding more LDK configuration settings + +## New + +### Issues + +- [#1209](https://github.com/cashubtc/cdk/issues/1209) - Fix issue with websocket +- [#1205](https://github.com/cashubtc/cdk/issues/1205) - cdk-kotlin we need to check the page size is set correctly there is a change coming up to the google play store +- [#1203](https://github.com/cashubtc/cdk/issues/1203) - Update the Database trait for wallet and support for transactions + +### PRs + +- [#1216](https://github.com/cashubtc/cdk/pull/1216) - Add Spark SDK as a nodeless backend for CDK mints +- [#1214](https://github.com/cashubtc/cdk/pull/1214) - feat(cdk-payment-processor): add currency unit parameter to make_payment +- [#1212](https://github.com/cashubtc/cdk/pull/1212) - Various mint fixes for swap (and now melt also). SIG_INPUTS+SIG_ALL, locktimes, P2PK+HTLC. Also updates the SIG_ALL message for amount-switching +- [#1211](https://github.com/cashubtc/cdk/pull/1211) - Regtest setup +- [#1210](https://github.com/cashubtc/cdk/pull/1210) - test: add mutation testing infrastructure +- [#1208](https://github.com/cashubtc/cdk/pull/1208) - Sig all fixes +- [#1204](https://github.com/cashubtc/cdk/pull/1204) - Add database transaction trait for cdk wallet +- [#1202](https://github.com/cashubtc/cdk/pull/1202) - Onchain +- [#1201](https://github.com/cashubtc/cdk/pull/1201) - feat: npubcash + +Template processor: https://github.com/thesimplekid/cdk-template-payment-processor +Spark payment processor: https://github.com/thesimplekid/cdk-spark-payment-prcoessor From fb07ec4b85a419e2129e54dce6d47b731997321d Mon Sep 17 00:00:00 2001 From: David Caseria Date: Thu, 30 Oct 2025 09:41:29 -0400 Subject: [PATCH 241/321] Include cargo config for cdk-ffi to enforce Android page sizes (#1241) --- crates/cdk-ffi/.cargo/config.toml | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 crates/cdk-ffi/.cargo/config.toml diff --git a/crates/cdk-ffi/.cargo/config.toml b/crates/cdk-ffi/.cargo/config.toml new file mode 100644 index 000000000..6adffde7d --- /dev/null +++ b/crates/cdk-ffi/.cargo/config.toml @@ -0,0 +1,7 @@ +[target.'cfg(target_os = "android")'] +rustflags = [ + "-C", "link-arg=-z", + "-C", "link-arg=max-page-size=16384", + "-C", "link-arg=-z", + "-C", "link-arg=common-page-size=16384", +] From 0c21cb59c6bc5090213a52cf25bbe0c827f5e9be Mon Sep 17 00:00:00 2001 From: gandlafbtc <123852829+gandlafbtc@users.noreply.github.com> Date: Fri, 31 Oct 2025 22:06:36 +0900 Subject: [PATCH 242/321] Ldk compose setup (#1242) * remove ldk mint from default docker compose * fix env var name for bitcoin network * add otional vars as comment in compose.ldk-node * better warning message and moved network definition to top --- docker-compose.ldk-node.yaml | 19 +++++++++++++++++-- docker-compose.yaml | 36 ------------------------------------ 2 files changed, 17 insertions(+), 38 deletions(-) diff --git a/docker-compose.ldk-node.yaml b/docker-compose.ldk-node.yaml index 6893b8b07..8f83386c6 100644 --- a/docker-compose.ldk-node.yaml +++ b/docker-compose.ldk-node.yaml @@ -46,7 +46,7 @@ services: container_name: mint-ldk-node ports: - "8085:8085" - - "8091:8091" # LDK admin dashboard + - "8091:8091" # LDK admin dashboard (WARNING!!! Do not expose to network! Doing so will leave LDK node funds accessible by whole network) environment: - CDK_MINTD_URL=https://example.com - CDK_MINTD_LN_BACKEND=ldk-node @@ -67,12 +67,27 @@ services: - CDK_MINTD_PROMETHEUS_ADDRESS=0.0.0.0 - CDK_MINTD_PROMETHEUS_PORT=9000 # LDK Node specific configuration - - CDK_MINTD_LDK_NODE_NETWORK=testnet + - CDK_MINTD_LDK_NODE_BITCOIN_NETWORK=testnet # or: testnet, signet, regtest - CDK_MINTD_LDK_NODE_ESPLORA_URL=https://blockstream.info/testnet/api - CDK_MINTD_LDK_NODE_LISTENING_ADDRESSES=0.0.0.0:9735 # LDK admin dashboard config - CDK_MINTD_LDK_NODE_WEBSERVER_HOST=0.0.0.0 + # Other Options # - CDK_MINTD_LDK_NODE_WEBSERVER_PORT= + # - CDK_MINTD_LDK_NODE_FEE_PERCENT= + # - CDK_MINTD_LDK_NODE_RESERVE_FEE_MIN= + # - CDK_MINTD_LDK_NODE_CHAIN_SOURCE_TYPE=esplora # or: bitcoinrpc + # if chain source is set to bitcoinrpc, the following RPC options need to be set instead + # - CDK_MINTD_LDK_NODE_BITCOIND_RPC_HOST= + # - CDK_MINTD_LDK_NODE_BITCOIND_RPC_PORT= + # - CDK_MINTD_LDK_NODE_BITCOIND_RPC_USER= + # - CDK_MINTD_LDK_NODE_BITCOIND_RPC_PASSWORD= + # - CDK_MINTD_LDK_NODE_STORAGE_DIR_PATH= + # - CDK_MINTD_LDK_NODE_LDK_NODE_HOST= + # - CDK_MINTD_LDK_NODE_LDK_NODE_PORT= + # - CDK_MINTD_LDK_NODE_GOSSIP_SOURCE_TYPE=rgs # or: p2p + # - CDK_MINTD_LDK_NODE_RGS_URL= + volumes: # Persist LDK node data - ldk_node_data:/usr/src/app/ldk_node_data diff --git a/docker-compose.yaml b/docker-compose.yaml index b318835cc..b364ad633 100644 --- a/docker-compose.yaml +++ b/docker-compose.yaml @@ -74,42 +74,6 @@ services: # depends_on: # - postgres - # LDK Node mint service - enable with: docker-compose --profile ldk-node up - mintd-ldk-node: - build: - context: . - dockerfile: Dockerfile.ldk-node - container_name: mint-ldk-node - profiles: - - ldk-node - ports: - - "8086:8085" # Different port to avoid conflict with main mint - environment: - - CDK_MINTD_URL=https://example.com - - CDK_MINTD_LN_BACKEND=ldk-node - - CDK_MINTD_LISTEN_HOST=0.0.0.0 - - CDK_MINTD_LISTEN_PORT=8085 - - CDK_MINTD_MNEMONIC= - # Database configuration - - CDK_MINTD_DATABASE=sqlite - # Cache configuration - - CDK_MINTD_CACHE_BACKEND=memory - - CDK_MINTD_PROMETHEUS_ENABLED=true - - CDK_MINTD_PROMETHEUS_ADDRESS=0.0.0.0 - - CDK_MINTD_PROMETHEUS_PORT=9000 - # LDK Node specific configuration - - CDK_MINTD_LDK_NODE_NETWORK=testnet - - CDK_MINTD_LDK_NODE_ESPLORA_URL=https://blockstream.info/testnet/api - - CDK_MINTD_LDK_NODE_LISTENING_ADDRESSES=0.0.0.0:9735 - volumes: - # Persist LDK node data - - ldk_node_data:/usr/src/app/ldk_node_data - command: ["cdk-mintd"] - depends_on: - - prometheus - - grafana - networks: - - cdk # PostgreSQL database service # Enable with: docker-compose --profile postgres up From dd3cb8a83af7d3b129bcfd6ee2865c22418d5535 Mon Sep 17 00:00:00 2001 From: tsk Date: Fri, 31 Oct 2025 12:20:44 -0400 Subject: [PATCH 243/321] fix: lnbits fee calc (#1243) * fix: lnbits fee calc --- crates/cdk-lnbits/src/lib.rs | 7 ++++--- crates/cdk-mintd/example.config.toml | 3 +++ 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/crates/cdk-lnbits/src/lib.rs b/crates/cdk-lnbits/src/lib.rs index 023246041..ec5a9c60e 100644 --- a/crates/cdk-lnbits/src/lib.rs +++ b/crates/cdk-lnbits/src/lib.rs @@ -11,7 +11,7 @@ use std::sync::Arc; use anyhow::anyhow; use async_trait::async_trait; -use cdk_common::amount::{to_unit, Amount}; +use cdk_common::amount::{to_unit, Amount, MSAT_IN_SAT}; use cdk_common::common::FeeReserve; use cdk_common::nuts::{CurrencyUnit, MeltOptions, MeltQuoteState}; use cdk_common::payment::{ @@ -244,7 +244,8 @@ impl MintPayment for LNbits { let relative_fee_reserve = (self.fee_reserve.percent_fee_reserve * u64::from(amount_msat) as f32) as u64; - let absolute_fee_reserve: u64 = self.fee_reserve.min_fee_reserve.into(); + let absolute_fee_reserve: u64 = + u64::from(self.fee_reserve.min_fee_reserve) * MSAT_IN_SAT; let fee = max(relative_fee_reserve, absolute_fee_reserve); @@ -253,7 +254,7 @@ impl MintPayment for LNbits { *bolt11_options.bolt11.payment_hash().as_ref(), )), amount: to_unit(amount_msat, &CurrencyUnit::Msat, unit)?, - fee: fee.into(), + fee: to_unit(fee, &CurrencyUnit::Msat, unit)?, state: MeltQuoteState::Unpaid, unit: unit.clone(), }) diff --git a/crates/cdk-mintd/example.config.toml b/crates/cdk-mintd/example.config.toml index 1dd627606..a7110ffdf 100644 --- a/crates/cdk-mintd/example.config.toml +++ b/crates/cdk-mintd/example.config.toml @@ -103,6 +103,9 @@ reserve_fee_min = 4 # admin_api_key = "" # invoice_api_key = "" # lnbits_api = "" +# fee_percent = 0.04 +# # Fee in sats +# reserve_fee_min = 4 # Note: Only LNBits v1 API is supported (websocket-based) # [lnd] From c6434b88d1498e66b3a43619612f836a2b383ada Mon Sep 17 00:00:00 2001 From: C Date: Sun, 2 Nov 2025 21:06:03 -0300 Subject: [PATCH 244/321] Fix websocket issues and mint quotes (#1246) * Fix websocket issues and mint quotes Fixes #1209 When checking with HTTP pulling, mint quotes would ping the ln backend if needed to get any payment that may not be included, so the mint uses this chance to correct its database. This check was missing for database subscriptions --- crates/cdk/src/mint/ln.rs | 37 ++++++++++++++++--- crates/cdk/src/mint/mod.rs | 10 +++-- crates/cdk/src/mint/subscription.rs | 57 ++++++++++++++++++++++++----- 3 files changed, 85 insertions(+), 19 deletions(-) diff --git a/crates/cdk/src/mint/ln.rs b/crates/cdk/src/mint/ln.rs index 9e4b59618..91cacaf82 100644 --- a/crates/cdk/src/mint/ln.rs +++ b/crates/cdk/src/mint/ln.rs @@ -1,17 +1,28 @@ +use std::collections::HashMap; +use std::sync::Arc; + use cdk_common::amount::to_unit; use cdk_common::common::PaymentProcessorKey; +use cdk_common::database::DynMintDatabase; use cdk_common::mint::MintQuote; +use cdk_common::payment::DynMintPayment; use cdk_common::util::unix_time; use cdk_common::{Amount, MintQuoteState, PaymentMethod}; use tracing::instrument; +use super::subscription::PubSubManager; use super::Mint; use crate::Error; impl Mint { - /// Check the status of an ln payment for a quote - #[instrument(skip_all)] - pub async fn check_mint_quote_paid(&self, quote: &mut MintQuote) -> Result<(), Error> { + /// Static implementation of check_mint_quote_paid to avoid circular dependency to the Mint + #[inline(always)] + pub(crate) async fn check_mint_quote_payments( + localstore: DynMintDatabase, + payment_processors: Arc>, + pubsub_manager: Option>, + quote: &mut MintQuote, + ) -> Result<(), Error> { let state = quote.state(); // We can just return here and do not need to check with ln node. @@ -23,7 +34,7 @@ impl Mint { return Ok(()); } - let ln = match self.payment_processors.get(&PaymentProcessorKey::new( + let ln = match payment_processors.get(&PaymentProcessorKey::new( quote.unit.clone(), quote.payment_method.clone(), )) { @@ -43,7 +54,7 @@ impl Mint { return Ok(()); } - let mut tx = self.localstore.begin_transaction().await?; + let mut tx = localstore.begin_transaction().await?; // reload the quote, as it state may have changed *quote = tx @@ -79,7 +90,9 @@ impl Mint { .increment_mint_quote_amount_paid("e.id, amount_paid, payment.payment_id) .await?; - self.pubsub_manager.mint_quote_payment(quote, total_paid); + if let Some(pubsub_manager) = pubsub_manager.as_ref() { + pubsub_manager.mint_quote_payment(quote, total_paid); + } } } @@ -87,4 +100,16 @@ impl Mint { Ok(()) } + + /// Check the status of an ln payment for a quote + #[instrument(skip_all)] + pub async fn check_mint_quote_paid(&self, quote: &mut MintQuote) -> Result<(), Error> { + Self::check_mint_quote_payments( + self.localstore.clone(), + self.payment_processors.clone(), + Some(self.pubsub_manager.clone()), + quote, + ) + .await + } } diff --git a/crates/cdk/src/mint/mod.rs b/crates/cdk/src/mint/mod.rs index 800408340..419e59c7e 100644 --- a/crates/cdk/src/mint/mod.rs +++ b/crates/cdk/src/mint/mod.rs @@ -69,7 +69,7 @@ pub struct Mint { #[cfg(feature = "auth")] auth_localstore: Option, /// Payment processors for mint - payment_processors: HashMap, + payment_processors: Arc>, /// Subscription manager pubsub_manager: Arc, #[cfg(feature = "auth")] @@ -203,9 +203,11 @@ impl Mint { } } + let payment_processors = Arc::new(payment_processors); + Ok(Self { signatory, - pubsub_manager: PubSubManager::new(localstore.clone()), + pubsub_manager: PubSubManager::new((localstore.clone(), payment_processors.clone())), localstore, #[cfg(feature = "auth")] oidc_client: computed_info.nuts.nut21.as_ref().map(|nut21| { @@ -257,7 +259,7 @@ impl Mint { // Start all payment processors first tracing::info!("Starting payment processors..."); let mut seen_processors = Vec::new(); - for (key, processor) in &self.payment_processors { + for (key, processor) in self.payment_processors.iter() { // Skip if we've already spawned a task for this processor instance if seen_processors.iter().any(|p| Arc::ptr_eq(p, processor)) { continue; @@ -369,7 +371,7 @@ impl Mint { tracing::info!("Stopping payment processors..."); let mut seen_processors = Vec::new(); - for (key, processor) in &self.payment_processors { + for (key, processor) in self.payment_processors.iter() { // Skip if we've already spawned a task for this processor instance if seen_processors.iter().any(|p| Arc::ptr_eq(p, processor)) { continue; diff --git a/crates/cdk/src/mint/subscription.rs b/crates/cdk/src/mint/subscription.rs index f60ebde97..48b0ecbc4 100644 --- a/crates/cdk/src/mint/subscription.rs +++ b/crates/cdk/src/mint/subscription.rs @@ -1,11 +1,14 @@ //! Specific Subscription for the cdk crate +use std::collections::HashMap; use std::ops::Deref; use std::sync::Arc; +use cdk_common::common::PaymentProcessorKey; use cdk_common::database::DynMintDatabase; use cdk_common::mint::MintQuote; use cdk_common::nut17::NotificationId; +use cdk_common::payment::DynMintPayment; use cdk_common::pub_sub::{Pubsub, Spec, Subscriber}; use cdk_common::subscription::SubId; use cdk_common::{ @@ -13,15 +16,39 @@ use cdk_common::{ MintQuoteBolt12Response, MintQuoteState, PaymentMethod, ProofState, PublicKey, QuoteId, }; +use super::Mint; use crate::event::MintEvent; /// Mint subtopics #[derive(Clone)] pub struct MintPubSubSpec { db: DynMintDatabase, + payment_processors: Arc>, } impl MintPubSubSpec { + /// Call Mint::check_mint_quote_payments to update the quote pinging the payment backend + async fn get_mint_quote( + &self, + quote_id: &QuoteId, + ) -> Result, cdk_common::Error> { + let mut quote = if let Some(quote) = self.db.get_mint_quote(quote_id).await? { + quote + } else { + return Ok(None); + }; + + Mint::check_mint_quote_payments( + self.db.clone(), + self.payment_processors.clone(), + None, + &mut quote, + ) + .await?; + + Ok(Some(quote)) + } + async fn get_events_from_db( &self, request: &[NotificationId], @@ -38,10 +65,10 @@ impl MintPubSubSpec { melt_queries.push(self.db.get_melt_quote(uuid)) } NotificationId::MintQuoteBolt11(uuid) => { - mint_queries.push(self.db.get_mint_quote(uuid)) + mint_queries.push(self.get_mint_quote(uuid)) } NotificationId::MintQuoteBolt12(uuid) => { - mint_queries.push(self.db.get_mint_quote(uuid)) + mint_queries.push(self.get_mint_quote(uuid)) } NotificationId::MeltQuoteBolt12(uuid) => { melt_queries.push(self.db.get_melt_quote(uuid)) @@ -72,12 +99,13 @@ impl MintPubSubSpec { quotes .into_iter() .filter_map(|quote| { - quote.and_then(|x| match x.payment_method { + quote.and_then(|mint_quotes| match mint_quotes.payment_method { PaymentMethod::Bolt11 => { - let response: MintQuoteBolt11Response = x.into(); + let response: MintQuoteBolt11Response = + mint_quotes.into(); Some(response.into()) } - PaymentMethod::Bolt12 => match x.try_into() { + PaymentMethod::Bolt12 => match mint_quotes.try_into() { Ok(response) => { let response: MintQuoteBolt12Response = response; @@ -119,10 +147,16 @@ impl Spec for MintPubSubSpec { type Event = MintEvent; - type Context = DynMintDatabase; + type Context = ( + DynMintDatabase, + Arc>, + ); fn new_instance(context: Self::Context) -> Arc { - Arc::new(Self { db: context }) + Arc::new(Self { + db: context.0, + payment_processors: context.1, + }) } async fn fetch_events(self: &Arc, topics: Vec, reply_to: Subscriber) { @@ -142,8 +176,13 @@ pub struct PubSubManager(Pubsub); impl PubSubManager { /// Create a new instance - pub fn new(db: DynMintDatabase) -> Arc { - Arc::new(Self(Pubsub::new(MintPubSubSpec::new_instance(db)))) + pub fn new( + context: ( + DynMintDatabase, + Arc>, + ), + ) -> Arc { + Arc::new(Self(Pubsub::new(MintPubSubSpec::new_instance(context)))) } /// Helper function to emit a ProofState status From c68c5288f2a124543bb15158c668d6fa05dbe58e Mon Sep 17 00:00:00 2001 From: codingpeanut157 Date: Mon, 3 Nov 2025 15:19:52 +0100 Subject: [PATCH 245/321] PreMintSecrets: fix `into_iter()` (#1244) extracting elements from the vector using `Vec::pop` returns the elements in the reverse order. This commits fixes the bug by using `Vec::remove(0)` --- crates/cashu/src/nuts/nut00/mod.rs | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/crates/cashu/src/nuts/nut00/mod.rs b/crates/cashu/src/nuts/nut00/mod.rs index a3b3a4248..5b4e76b45 100644 --- a/crates/cashu/src/nuts/nut00/mod.rs +++ b/crates/cashu/src/nuts/nut00/mod.rs @@ -930,7 +930,10 @@ impl Iterator for PreMintSecrets { fn next(&mut self) -> Option { // Use the iterator of the vector - self.secrets.pop() + if self.secrets.is_empty() { + return None; + } + Some(self.secrets.remove(0)) } } From aa8258d955a634564f7ad8ce7e4796d4652a9cc6 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Mon, 3 Nov 2025 10:36:25 -0500 Subject: [PATCH 246/321] fix: time of meeting --- .github/scripts/generate-agenda.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/scripts/generate-agenda.sh b/.github/scripts/generate-agenda.sh index 43d115e46..5416615d1 100755 --- a/.github/scripts/generate-agenda.sh +++ b/.github/scripts/generate-agenda.sh @@ -9,7 +9,7 @@ OUTPUT_DIR="meetings" # Calculate date range (last 7 days) SINCE_DATE=$(date -d "$DAYS_BACK days ago" -u +"%Y-%m-%dT%H:%M:%SZ") -MEETING_DATE=$(date -u +"%b %d %Y %H:%M UTC") +MEETING_DATE=$(date -u +"%b %d %Y 15:00 UTC") FILE_DATE=$(date -u +"%Y-%m-%d") echo "Generating meeting agenda for $MEETING_DATE" From d9e001bee69674cdd5905b39750ebb947640c2b4 Mon Sep 17 00:00:00 2001 From: tsk Date: Mon, 3 Nov 2025 11:40:21 -0500 Subject: [PATCH 247/321] refactor(cdk): implement saga pattern for melt operations (#1186) Restructure melt flow into a multi-step saga with compensation-based rollback. Remove ProofWriter in favor of explicit compensation actions for improved reliability and clarity in handling partial failures during melt operations. Breaks down monolithic change processing logic into smaller, focused methods: - process_change_outputs: orchestrates full change workflow - validate_change_outputs: checks for already-signed messages - calculate_change_fee_and_amounts: fetches keyset configuration - split_change_amount: splits change into denominations - prepare_blinded_messages_with_amounts: pairs amounts with blinded messages - store_change_signatures: handles TX2 database operations --- crates/cdk-common/src/common.rs | 8 +- crates/cdk-common/src/mint.rs | 72 +- .../tests/fake_wallet.rs | 30 +- .../20251010144317_add_saga_support.sql | 2 + .../20251010144317_add_saga_support.sql | 2 + crates/cdk-sql-common/src/mint/mod.rs | 21 +- crates/cdk/src/mint/melt.rs | 684 +----- .../src/mint/melt/melt_saga/compensation.rs | 65 + crates/cdk/src/mint/melt/melt_saga/mod.rs | 909 +++++++ crates/cdk/src/mint/melt/melt_saga/state.rs | 46 + crates/cdk/src/mint/melt/melt_saga/tests.rs | 2132 +++++++++++++++++ crates/cdk/src/mint/melt/shared.rs | 443 ++++ crates/cdk/src/mint/mod.rs | 96 +- crates/cdk/src/mint/proof_writer.rs | 237 -- crates/cdk/src/mint/start_up_check.rs | 505 +++- justfile | 2 +- 16 files changed, 4196 insertions(+), 1058 deletions(-) create mode 100644 crates/cdk/src/mint/melt/melt_saga/compensation.rs create mode 100644 crates/cdk/src/mint/melt/melt_saga/mod.rs create mode 100644 crates/cdk/src/mint/melt/melt_saga/state.rs create mode 100644 crates/cdk/src/mint/melt/melt_saga/tests.rs create mode 100644 crates/cdk/src/mint/melt/shared.rs delete mode 100644 crates/cdk/src/mint/proof_writer.rs diff --git a/crates/cdk-common/src/common.rs b/crates/cdk-common/src/common.rs index 97d370ec0..59edfffa8 100644 --- a/crates/cdk-common/src/common.rs +++ b/crates/cdk-common/src/common.rs @@ -31,7 +31,7 @@ impl Melted { pub fn from_proofs( state: MeltQuoteState, preimage: Option, - amount: Amount, + quote_amount: Amount, proofs: Proofs, change_proofs: Option, ) -> Result { @@ -44,19 +44,19 @@ impl Melted { tracing::info!( "Proofs amount: {} Amount: {} Change: {}", proofs_amount, - amount, + quote_amount, change_amount ); let fee_paid = proofs_amount - .checked_sub(amount + change_amount) + .checked_sub(quote_amount + change_amount) .ok_or(Error::AmountOverflow)?; Ok(Self { state, preimage, change: change_proofs, - amount, + amount: quote_amount, fee_paid, }) } diff --git a/crates/cdk-common/src/mint.rs b/crates/cdk-common/src/mint.rs index 0249bffdc..d5216edb7 100644 --- a/crates/cdk-common/src/mint.rs +++ b/crates/cdk-common/src/mint.rs @@ -85,16 +85,47 @@ impl FromStr for SwapSagaState { } } +/// States specific to melt saga +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum MeltSagaState { + /// Setup complete (proofs reserved, quote verified) + SetupComplete, + /// Payment sent to Lightning network + PaymentSent, +} + +impl fmt::Display for MeltSagaState { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + MeltSagaState::SetupComplete => write!(f, "setup_complete"), + MeltSagaState::PaymentSent => write!(f, "payment_sent"), + } + } +} + +impl FromStr for MeltSagaState { + type Err = Error; + fn from_str(value: &str) -> Result { + let value = value.to_lowercase(); + match value.as_str() { + "setup_complete" => Ok(MeltSagaState::SetupComplete), + "payment_sent" => Ok(MeltSagaState::PaymentSent), + _ => Err(Error::Custom(format!("Invalid melt saga state: {}", value))), + } + } +} + /// Saga state for different operation types #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] #[serde(tag = "type", rename_all = "snake_case")] pub enum SagaStateEnum { /// Swap saga states Swap(SwapSagaState), + /// Melt saga states + Melt(MeltSagaState), // Future: Mint saga states // Mint(MintSagaState), - // Future: Melt saga states - // Melt(MeltSagaState), } impl SagaStateEnum { @@ -102,8 +133,8 @@ impl SagaStateEnum { pub fn new(operation_kind: OperationKind, s: &str) -> Result { match operation_kind { OperationKind::Swap => Ok(SagaStateEnum::Swap(SwapSagaState::from_str(s)?)), + OperationKind::Melt => Ok(SagaStateEnum::Melt(MeltSagaState::from_str(s)?)), OperationKind::Mint => Err(Error::Custom("Mint saga not implemented yet".to_string())), - OperationKind::Melt => Err(Error::Custom("Melt saga not implemented yet".to_string())), } } @@ -114,6 +145,10 @@ impl SagaStateEnum { SwapSagaState::SetupComplete => "setup_complete", SwapSagaState::Signed => "signed", }, + SagaStateEnum::Melt(state) => match state { + MeltSagaState::SetupComplete => "setup_complete", + MeltSagaState::PaymentSent => "payment_sent", + }, } } } @@ -131,6 +166,9 @@ pub struct Saga { pub blinded_secrets: Vec, /// Y values (public keys) from input proofs pub input_ys: Vec, + /// Quote ID for melt operations (used for payment status lookup during recovery) + /// None for swap operations + pub quote_id: Option, /// Unix timestamp when saga was created pub created_at: u64, /// Unix timestamp when saga was last updated @@ -152,6 +190,7 @@ impl Saga { state: SagaStateEnum::Swap(state), blinded_secrets, input_ys, + quote_id: None, created_at: now, updated_at: now, } @@ -162,6 +201,33 @@ impl Saga { self.state = SagaStateEnum::Swap(new_state); self.updated_at = unix_time(); } + + /// Create new melt saga + pub fn new_melt( + operation_id: Uuid, + state: MeltSagaState, + input_ys: Vec, + blinded_secrets: Vec, + quote_id: String, + ) -> Self { + let now = unix_time(); + Self { + operation_id, + operation_kind: OperationKind::Melt, + state: SagaStateEnum::Melt(state), + blinded_secrets, + input_ys, + quote_id: Some(quote_id), + created_at: now, + updated_at: now, + } + } + + /// Update melt saga state + pub fn update_melt_state(&mut self, new_state: MeltSagaState) { + self.state = SagaStateEnum::Melt(new_state); + self.updated_at = unix_time(); + } } /// Operation diff --git a/crates/cdk-integration-tests/tests/fake_wallet.rs b/crates/cdk-integration-tests/tests/fake_wallet.rs index 7237c66f1..b6b271fea 100644 --- a/crates/cdk-integration-tests/tests/fake_wallet.rs +++ b/crates/cdk-integration-tests/tests/fake_wallet.rs @@ -134,7 +134,7 @@ async fn test_fake_melt_payment_fail() { } let wallet_bal = wallet.total_balance().await.unwrap(); - assert_eq!(wallet_bal, 100.into()); + assert_eq!(wallet_bal, 98.into()); } /// Tests that when both the pay_invoice and check_invoice both fail, @@ -222,6 +222,16 @@ async fn test_fake_melt_payment_return_fail_status() { let melt = wallet.melt(&melt_quote.id).await; assert!(melt.is_err()); + wallet.check_all_pending_proofs().await.unwrap(); + + let pending = wallet + .localstore + .get_proofs(None, None, Some(vec![State::Pending]), None) + .await + .unwrap(); + + assert!(pending.is_empty()); + let fake_description = FakeInvoiceDescription { pay_invoice_state: MeltQuoteState::Unknown, check_payment_state: MeltQuoteState::Unknown, @@ -237,13 +247,15 @@ async fn test_fake_melt_payment_return_fail_status() { let melt = wallet.melt(&melt_quote.id).await; assert!(melt.is_err()); + wallet.check_all_pending_proofs().await.unwrap(); + let pending = wallet .localstore .get_proofs(None, None, Some(vec![State::Pending]), None) .await .unwrap(); - assert!(pending.is_empty()); + assert!(!pending.is_empty()); } /// Tests that when the ln backend returns an error with unknown status, @@ -282,7 +294,7 @@ async fn test_fake_melt_payment_error_unknown() { // The melt should error at the payment invoice command let melt = wallet.melt(&melt_quote.id).await; - assert_eq!(melt.unwrap_err().to_string(), "Payment failed"); + assert!(melt.is_err()); let fake_description = FakeInvoiceDescription { pay_invoice_state: MeltQuoteState::Unknown, @@ -297,7 +309,9 @@ async fn test_fake_melt_payment_error_unknown() { // The melt should error at the payment invoice command let melt = wallet.melt(&melt_quote.id).await; - assert_eq!(melt.unwrap_err().to_string(), "Payment failed"); + assert!(melt.is_err()); + + wallet.check_all_pending_proofs().await.unwrap(); let pending = wallet .localstore @@ -305,7 +319,7 @@ async fn test_fake_melt_payment_error_unknown() { .await .unwrap(); - assert!(pending.is_empty()); + assert!(!pending.is_empty()); } /// Tests that when the ln backend returns an error but the second check returns paid, @@ -343,10 +357,10 @@ async fn test_fake_melt_payment_err_paid() { let melt_quote = wallet.melt_quote(invoice.to_string(), None).await.unwrap(); // The melt should error at the payment invoice command - let melt = wallet.melt(&melt_quote.id).await; - assert!(melt.is_err()); + let melt = wallet.melt(&melt_quote.id).await.unwrap(); - attempt_to_swap_pending(&wallet).await.unwrap(); + assert!(melt.fee_paid == Amount::ZERO); + assert!(melt.amount == Amount::from(7)); } /// Tests that change outputs in a melt quote are correctly handled diff --git a/crates/cdk-sql-common/src/mint/migrations/postgres/20251010144317_add_saga_support.sql b/crates/cdk-sql-common/src/mint/migrations/postgres/20251010144317_add_saga_support.sql index 8aba3ac30..114937f3b 100644 --- a/crates/cdk-sql-common/src/mint/migrations/postgres/20251010144317_add_saga_support.sql +++ b/crates/cdk-sql-common/src/mint/migrations/postgres/20251010144317_add_saga_support.sql @@ -17,8 +17,10 @@ CREATE TABLE IF NOT EXISTS saga_state ( state TEXT NOT NULL, blinded_secrets TEXT NOT NULL, input_ys TEXT NOT NULL, + quote_id TEXT, created_at BIGINT NOT NULL, updated_at BIGINT NOT NULL ); CREATE INDEX IF NOT EXISTS idx_saga_state_operation_kind ON saga_state(operation_kind); +CREATE INDEX IF NOT EXISTS idx_saga_state_quote_id ON saga_state(quote_id); diff --git a/crates/cdk-sql-common/src/mint/migrations/sqlite/20251010144317_add_saga_support.sql b/crates/cdk-sql-common/src/mint/migrations/sqlite/20251010144317_add_saga_support.sql index e9c7217c9..2ff0902f6 100644 --- a/crates/cdk-sql-common/src/mint/migrations/sqlite/20251010144317_add_saga_support.sql +++ b/crates/cdk-sql-common/src/mint/migrations/sqlite/20251010144317_add_saga_support.sql @@ -17,8 +17,10 @@ CREATE TABLE IF NOT EXISTS saga_state ( state TEXT NOT NULL, blinded_secrets TEXT NOT NULL, input_ys TEXT NOT NULL, + quote_id TEXT, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL ); CREATE INDEX IF NOT EXISTS idx_saga_state_operation_kind ON saga_state(operation_kind); +CREATE INDEX IF NOT EXISTS idx_saga_state_quote_id ON saga_state(quote_id); diff --git a/crates/cdk-sql-common/src/mint/mod.rs b/crates/cdk-sql-common/src/mint/mod.rs index 270436203..92b0a1495 100644 --- a/crates/cdk-sql-common/src/mint/mod.rs +++ b/crates/cdk-sql-common/src/mint/mod.rs @@ -2146,6 +2146,7 @@ where state, blinded_secrets, input_ys, + quote_id, created_at, updated_at FROM @@ -2174,9 +2175,9 @@ where query( r#" INSERT INTO saga_state - (operation_id, operation_kind, state, blinded_secrets, input_ys, created_at, updated_at) + (operation_id, operation_kind, state, blinded_secrets, input_ys, quote_id, created_at, updated_at) VALUES - (:operation_id, :operation_kind, :state, :blinded_secrets, :input_ys, :created_at, :updated_at) + (:operation_id, :operation_kind, :state, :blinded_secrets, :input_ys, :quote_id, :created_at, :updated_at) "#, )? .bind("operation_id", saga.operation_id.to_string()) @@ -2184,6 +2185,7 @@ where .bind("state", saga.state.state()) .bind("blinded_secrets", blinded_secrets_json) .bind("input_ys", input_ys_json) + .bind("quote_id", saga.quote_id.as_deref()) .bind("created_at", saga.created_at as i64) .bind("updated_at", current_time as i64) .execute(&self.inner) @@ -2250,6 +2252,7 @@ where state, blinded_secrets, input_ys, + quote_id, created_at, updated_at FROM @@ -2539,6 +2542,7 @@ fn sql_row_to_saga(row: Vec) -> Result { state, blinded_secrets, input_ys, + quote_id, created_at, updated_at ) = row @@ -2564,6 +2568,18 @@ fn sql_row_to_saga(row: Vec) -> Result { let input_ys: Vec = serde_json::from_str(&input_ys_str) .map_err(|e| Error::Internal(format!("Failed to deserialize input_ys: {}", e)))?; + let quote_id = match "e_id { + Column::Text(s) => { + if s.is_empty() { + None + } else { + Some(s.clone()) + } + } + Column::Null => None, + _ => None, + }; + let created_at: u64 = column_as_number!(created_at); let updated_at: u64 = column_as_number!(updated_at); @@ -2573,6 +2589,7 @@ fn sql_row_to_saga(row: Vec) -> Result { state, blinded_secrets, input_ys, + quote_id, created_at, updated_at, }) diff --git a/crates/cdk/src/mint/melt.rs b/crates/cdk/src/mint/melt.rs index 20e9b7b24..fa0fd74e2 100644 --- a/crates/cdk/src/mint/melt.rs +++ b/crates/cdk/src/mint/melt.rs @@ -1,15 +1,11 @@ use std::str::FromStr; -use anyhow::bail; use cdk_common::amount::amount_for_offer; -use cdk_common::database::mint::MeltRequestInfo; -use cdk_common::database::{self, MintTransaction}; use cdk_common::melt::MeltQuoteRequest; -use cdk_common::mint::{MeltPaymentRequest, Operation}; +use cdk_common::mint::MeltPaymentRequest; use cdk_common::nut05::MeltMethodOptions; use cdk_common::payment::{ - Bolt11OutgoingPaymentOptions, Bolt12OutgoingPaymentOptions, DynMintPayment, - OutgoingPaymentOptions, PaymentIdentifier, + Bolt11OutgoingPaymentOptions, Bolt12OutgoingPaymentOptions, OutgoingPaymentOptions, }; use cdk_common::quote_id::QuoteId; use cdk_common::{MeltOptions, MeltQuoteBolt12Request}; @@ -20,18 +16,18 @@ use tracing::instrument; use super::{ CurrencyUnit, MeltQuote, MeltQuoteBolt11Request, MeltQuoteBolt11Response, MeltRequest, Mint, - PaymentMethod, PublicKey, State, + PaymentMethod, }; use crate::amount::to_unit; -use crate::cdk_payment::MakePaymentResponse; -use crate::mint::proof_writer::ProofWriter; -use crate::mint::verification::Verification; -use crate::mint::SigFlag; -use crate::nuts::nut11::{enforce_sig_flag, EnforceSigFlag}; use crate::nuts::MeltQuoteState; use crate::types::PaymentProcessorKey; use crate::util::unix_time; -use crate::{cdk_payment, ensure_cdk, Amount, Error}; +use crate::{ensure_cdk, Amount, Error}; + +mod melt_saga; +pub(super) mod shared; + +use melt_saga::MeltSaga; impl Mint { #[instrument(skip_all)] @@ -418,663 +414,33 @@ impl Mint { Ok(quotes) } - /// Check melt has expected fees - #[instrument(skip_all)] - pub async fn check_melt_expected_ln_fees( - &self, - melt_quote: &MeltQuote, - melt_request: &MeltRequest, - ) -> Result, Error> { - let quote_msats = to_unit(melt_quote.amount, &melt_quote.unit, &CurrencyUnit::Msat) - .expect("Quote unit is checked above that it can convert to msat"); - - let invoice_amount_msats = match &melt_quote.request { - MeltPaymentRequest::Bolt11 { bolt11 } => match bolt11.amount_milli_satoshis() { - Some(amount) => amount.into(), - None => melt_quote - .options - .ok_or(Error::InvoiceAmountUndefined)? - .amount_msat(), - }, - MeltPaymentRequest::Bolt12 { offer } => match offer.amount() { - Some(amount) => { - let (amount, currency) = match amount { - lightning::offers::offer::Amount::Bitcoin { amount_msats } => { - (amount_msats, CurrencyUnit::Msat) - } - lightning::offers::offer::Amount::Currency { - iso4217_code, - amount, - } => ( - amount, - CurrencyUnit::from_str(&String::from_utf8(iso4217_code.to_vec())?)?, - ), - }; - - to_unit(amount, ¤cy, &CurrencyUnit::Msat) - .map_err(|_err| Error::UnsupportedUnit)? - } - None => melt_quote - .options - .ok_or(Error::InvoiceAmountUndefined)? - .amount_msat(), - }, - }; - - let partial_amount = match invoice_amount_msats > quote_msats { - true => Some( - to_unit(quote_msats, &CurrencyUnit::Msat, &melt_quote.unit) - .map_err(|_| Error::UnsupportedUnit)?, - ), - false => None, - }; - - let amount_to_pay = match partial_amount { - Some(amount_to_pay) => amount_to_pay, - None => to_unit(invoice_amount_msats, &CurrencyUnit::Msat, &melt_quote.unit) - .map_err(|_| Error::UnsupportedUnit)?, - }; - - let inputs_amount_quote_unit = melt_request.inputs_amount().map_err(|_| { - tracing::error!("Proof inputs in melt quote overflowed"); - Error::AmountOverflow - })?; - - if amount_to_pay + melt_quote.fee_reserve > inputs_amount_quote_unit { - tracing::debug!( - "Not enough inputs provided: {} {} needed {} {}", - inputs_amount_quote_unit, - melt_quote.unit, - amount_to_pay, - melt_quote.unit - ); - - return Err(Error::TransactionUnbalanced( - inputs_amount_quote_unit.into(), - amount_to_pay.into(), - melt_quote.fee_reserve.into(), - )); - } - - Ok(partial_amount) - } - - /// Verify melt request is valid - #[instrument(skip_all)] - pub async fn verify_melt_request( - &self, - tx: &mut Box + Send + Sync + '_>, - input_verification: Verification, - melt_request: &MeltRequest, - operation: &Operation, - ) -> Result<(ProofWriter, MeltQuote), Error> { - let Verification { - amount: input_amount, - unit: input_unit, - } = input_verification; - - let mut proof_writer = - ProofWriter::new(self.localstore.clone(), self.pubsub_manager.clone()); - - proof_writer - .add_proofs( - tx, - melt_request.inputs(), - Some(melt_request.quote_id().to_owned()), - operation, - ) - .await?; - - // Only after proof verification succeeds, proceed with quote state check - let (state, quote) = tx - .update_melt_quote_state(melt_request.quote(), MeltQuoteState::Pending, None) - .await?; - - if input_unit != Some(quote.unit.clone()) { - return Err(Error::UnitMismatch); - } - - match state { - MeltQuoteState::Unpaid | MeltQuoteState::Failed => Ok(()), - MeltQuoteState::Pending => Err(Error::PendingQuote), - MeltQuoteState::Paid => Err(Error::PaidQuote), - MeltQuoteState::Unknown => Err(Error::UnknownPaymentState), - }?; - - self.pubsub_manager - .melt_quote_status("e, None, None, MeltQuoteState::Pending); - - let fee = self.get_proofs_fee(melt_request.inputs()).await?; - - let required_total = quote.amount + quote.fee_reserve + fee; - - // Check that the inputs proofs are greater then total. - // Transaction does not need to be balanced as wallet may not want change. - if input_amount < required_total { - tracing::info!( - "Swap request unbalanced: {}, outputs {}, fee {}", - input_amount, - quote.amount, - fee - ); - return Err(Error::TransactionUnbalanced( - input_amount.into(), - quote.amount.into(), - (fee + quote.fee_reserve).into(), - )); - } - - let EnforceSigFlag { sig_flag, .. } = enforce_sig_flag(melt_request.inputs().clone()); - - if sig_flag == SigFlag::SigAll { - melt_request.verify_sig_all()?; - } - - if let Some(outputs) = &melt_request.outputs() { - if !outputs.is_empty() { - let Verification { - amount: _, - unit: output_unit, - } = self.verify_outputs(tx, outputs).await?; - - ensure_cdk!(input_unit == output_unit, Error::UnsupportedUnit); - } - } - - tracing::debug!("Verified melt quote: {}", melt_request.quote()); - Ok((proof_writer, quote)) - } - - /// Melt Bolt11 + /// Melt + /// + /// Uses MeltSaga typestate pattern for atomic transaction handling with automatic rollback on failure. #[instrument(skip_all)] pub async fn melt( &self, melt_request: &MeltRequest, ) -> Result, Error> { - #[cfg(feature = "prometheus")] - METRICS.inc_in_flight_requests("melt_bolt11"); - - use std::sync::Arc; - async fn check_payment_state( - ln: DynMintPayment, - lookup_id: &PaymentIdentifier, - ) -> anyhow::Result { - match ln.check_outgoing_payment(lookup_id).await { - Ok(response) => Ok(response), - Err(check_err) => { - // If we cannot check the status of the payment we keep the proofs stuck as pending. - tracing::error!( - "Could not check the status of payment for {},. Proofs stuck as pending", - lookup_id - ); - tracing::error!("Checking payment error: {}", check_err); - bail!("Could not check payment status") - } - } - } - let verification = self.verify_inputs(melt_request.inputs()).await?; - let melt_operation = Operation::new_melt(); - let mut tx = self.localstore.begin_transaction().await?; - - let (proof_writer, quote) = match self - .verify_melt_request(&mut tx, verification, melt_request, &melt_operation) - .await - { - Ok(result) => result, - Err(err) => { - tracing::debug!("Error attempting to verify melt quote: {}", err); - - #[cfg(feature = "prometheus")] - { - METRICS.dec_in_flight_requests("melt_bolt11"); - METRICS.record_mint_operation("melt_bolt11", false); - METRICS.record_error(); - } - - return Err(err); - } - }; - - let inputs_fee = self.get_proofs_fee(melt_request.inputs()).await?; - - tx.add_melt_request( - melt_request.quote_id(), - melt_request.inputs_amount()?, - inputs_fee, - ) - .await?; - - tx.add_blinded_messages( - Some(melt_request.quote_id()), - melt_request.outputs().as_ref().unwrap_or(&Vec::new()), - &melt_operation, - ) - .await?; - - let settled_internally_amount = match self - .handle_internal_melt_mint(&mut tx, "e, melt_request) - .await - { - Ok(amount) => amount, - Err(err) => { - tracing::error!("Attempting to settle internally failed: {}", err); - - #[cfg(feature = "prometheus")] - { - METRICS.dec_in_flight_requests("melt_bolt11"); - METRICS.record_mint_operation("melt_bolt11", false); - METRICS.record_error(); - } - - return Err(err); - } - }; - - let (tx, preimage, amount_spent_quote_unit, quote) = match settled_internally_amount { - Some(amount_spent) => (tx, None, amount_spent, quote), - - None => { - // If the quote unit is SAT or MSAT we can check that the expected fees are - // provided. We also check if the quote is less then the invoice - // amount in the case that it is a mmp However, if the quote is not - // of a bitcoin unit we cannot do these checks as the mint - // is unaware of a conversion rate. In this case it is assumed that the quote is - // correct and the mint should pay the full invoice amount if inputs - // > `then quote.amount` are included. This is checked in the - // `verify_melt` method. - let _partial_amount = match quote.unit { - CurrencyUnit::Sat | CurrencyUnit::Msat => { - match self.check_melt_expected_ln_fees("e, melt_request).await { - Ok(amount) => amount, - Err(err) => { - tracing::error!("Fee is not expected: {}", err); - return Err(Error::Internal); - } - } - } - _ => None, - }; - - let ln = match self.payment_processors.get(&PaymentProcessorKey::new( - quote.unit.clone(), - quote.payment_method.clone(), - )) { - Some(ln) => ln, - None => { - tracing::info!("Could not get ln backend for {}, bolt11 ", quote.unit); - return Err(Error::UnsupportedUnit); - } - }; - - // Commit before talking to the external call - tx.commit().await?; - - let pre = match ln - .make_payment("e.unit, quote.clone().try_into()?) - .await - { - Ok(pay) - if pay.status == MeltQuoteState::Unknown - || pay.status == MeltQuoteState::Failed => - { - tracing::warn!("Got {} status when paying melt quote {} for {} {}. Checking with backend...", pay.status, quote.id, quote.amount, quote.unit); - let check_response = if let Ok(ok) = - check_payment_state(Arc::clone(ln), &pay.payment_lookup_id).await - { - ok - } else { - return Err(Error::Internal); - }; - - if check_response.status == MeltQuoteState::Paid { - tracing::warn!("Pay invoice returned {} but check returned {}. Proofs stuck as pending", pay.status.to_string(), check_response.status.to_string()); - - proof_writer.commit(); - - return Err(Error::Internal); - } - - check_response - } - Ok(pay) => pay, - Err(err) => { - // If the error is that the invoice was already paid we do not want to hold - // hold the proofs as pending to we reset them and return an error. - if matches!(err, cdk_payment::Error::InvoiceAlreadyPaid) { - tracing::debug!("Invoice already paid, resetting melt quote"); - return Err(Error::RequestAlreadyPaid); - } - - tracing::error!("Error returned attempting to pay: {} {}", quote.id, err); - - let lookup_id = quote.request_lookup_id.as_ref().ok_or_else(|| { - tracing::error!( - "No payment id could not lookup payment for {} after error.", - quote.id - ); - Error::Internal - })?; - - let check_response = - if let Ok(ok) = check_payment_state(Arc::clone(ln), lookup_id).await { - ok - } else { - proof_writer.commit(); - return Err(Error::Internal); - }; - // If there error is something else we want to check the status of the payment ensure it is not pending or has been made. - if check_response.status == MeltQuoteState::Paid { - tracing::warn!("Pay invoice returned an error but check returned {}. Proofs stuck as pending", check_response.status.to_string()); - proof_writer.commit(); - return Err(Error::Internal); - } - check_response - } - }; - - match pre.status { - MeltQuoteState::Paid => (), - MeltQuoteState::Unpaid | MeltQuoteState::Unknown | MeltQuoteState::Failed => { - tracing::info!( - "Lightning payment for quote {} failed.", - melt_request.quote() - ); - proof_writer.rollback().await?; - - #[cfg(feature = "prometheus")] - { - METRICS.dec_in_flight_requests("melt_bolt11"); - METRICS.record_mint_operation("melt_bolt11", false); - METRICS.record_error(); - } - - return Err(Error::PaymentFailed); - } - MeltQuoteState::Pending => { - tracing::warn!( - "LN payment pending, proofs are stuck as pending for quote: {}", - melt_request.quote() - ); - proof_writer.commit(); - #[cfg(feature = "prometheus")] - { - METRICS.dec_in_flight_requests("melt_bolt11"); - METRICS.record_mint_operation("melt_bolt11", false); - METRICS.record_error(); - } - - return Err(Error::PendingQuote); - } - } - - // Convert from unit of backend to quote unit - // Note: this should never fail since these conversions happen earlier and would fail there. - // Since it will not fail and even if it does the ln payment has already been paid, proofs should still be burned - let amount_spent = - to_unit(pre.total_spent, &pre.unit, "e.unit).unwrap_or_default(); - - let payment_lookup_id = pre.payment_lookup_id; - let mut tx = self.localstore.begin_transaction().await?; - - if Some(payment_lookup_id.clone()).as_ref() != quote.request_lookup_id.as_ref() { - tracing::info!( - "Payment lookup id changed post payment from {:?} to {}", - "e.request_lookup_id, - payment_lookup_id - ); - - let mut melt_quote = quote; - melt_quote.request_lookup_id = Some(payment_lookup_id.clone()); - - if let Err(err) = tx - .update_melt_quote_request_lookup_id(&melt_quote.id, &payment_lookup_id) - .await - { - tracing::warn!("Could not update payment lookup id: {}", err); - } - - (tx, pre.payment_proof, amount_spent, melt_quote) - } else { - (tx, pre.payment_proof, amount_spent, quote) - } - } - }; - - // If we made it here the payment has been made. - // We process the melt burning the inputs and returning change - let res = match self - .process_melt_request(tx, proof_writer, quote, preimage, amount_spent_quote_unit) - .await - { - Ok(response) => response, - Err(err) => { - tracing::error!("Could not process melt request: {}", err); - - #[cfg(feature = "prometheus")] - { - METRICS.dec_in_flight_requests("melt_bolt11"); - METRICS.record_mint_operation("melt_bolt11", false); - METRICS.record_error(); - } - - return Err(err); - } - }; - - #[cfg(feature = "prometheus")] - { - METRICS.dec_in_flight_requests("melt_bolt11"); - METRICS.record_mint_operation("melt_bolt11", true); - } - - Ok(res) - } - - /// Process melt request marking proofs as spent - /// The melt request must be verified using [`Self::verify_melt_request`] - /// before calling [`Self::process_melt_request`] - #[instrument(skip_all)] - pub async fn process_melt_request( - &self, - mut tx: Box + Send + Sync + '_>, - mut proof_writer: ProofWriter, - quote: MeltQuote, - payment_preimage: Option, - total_spent: Amount, - ) -> Result, Error> { - #[cfg(feature = "prometheus")] - METRICS.inc_in_flight_requests("process_melt_request"); - - // Try to get input_ys from the stored melt request, fall back to original request if not found - let input_ys: Vec<_> = tx.get_proof_ys_by_quote_id("e.id).await?; - - assert!(!input_ys.is_empty()); - - tracing::debug!( - "Updating {} proof states to Spent for quote {}", - input_ys.len(), - quote.id + let init_saga = MeltSaga::new( + std::sync::Arc::new(self.clone()), + self.localstore.clone(), + std::sync::Arc::clone(&self.pubsub_manager), ); - if total_spent < quote.amount { - return Err(Error::AmountUndefined); - } - - let update_proof_states_result = proof_writer - .update_proofs_states(&mut tx, &input_ys, State::Spent) - .await; - - if update_proof_states_result.is_err() { - #[cfg(feature = "prometheus")] - self.record_melt_quote_failure("process_melt_request"); - return Err(update_proof_states_result.err().unwrap()); - } - tracing::debug!("Successfully updated proof states to Spent"); - - tx.update_melt_quote_state("e.id, MeltQuoteState::Paid, payment_preimage.clone()) - .await?; - - let mut change = None; - - let MeltRequestInfo { - inputs_amount, - inputs_fee, - change_outputs, - } = tx - .get_melt_request_and_blinded_messages("e.id) - .await? - .ok_or(Error::UnknownQuote)?; - - // Check if there is change to return - if inputs_amount > total_spent { - // Check if wallet provided change outputs - if !change_outputs.is_empty() { - let outputs = change_outputs; - - let blinded_messages: Vec = - outputs.iter().map(|b| b.blinded_secret).collect(); - - if tx - .get_blind_signatures(&blinded_messages) - .await? - .iter() - .flatten() - .next() - .is_some() - { - tracing::info!("Output has already been signed"); - - return Err(Error::BlindedMessageAlreadySigned); - } - - let change_target = inputs_amount - total_spent - inputs_fee; - - let fee_and_amounts = self - .keysets - .load() - .iter() - .filter_map(|keyset| { - if keyset.active && Some(keyset.id) == outputs.first().map(|x| x.keyset_id) - { - Some((keyset.input_fee_ppk, keyset.amounts.clone()).into()) - } else { - None - } - }) - .next() - .unwrap_or_else(|| { - (0, (0..32).map(|x| 2u64.pow(x)).collect::>()).into() - }); - - let mut amounts = change_target.split(&fee_and_amounts); - - if outputs.len().lt(&amounts.len()) { - tracing::debug!( - "Providing change requires {} blinded messages, but only {} provided", - amounts.len(), - outputs.len() - ); - - // In the case that not enough outputs are provided to return all change - // Reverse sort the amounts so that the most amount of change possible is - // returned. The rest is burnt - amounts.sort_by(|a, b| b.cmp(a)); - } - - let mut blinded_messages = vec![]; - - for (amount, mut blinded_message) in amounts.iter().zip(outputs.clone()) { - blinded_message.amount = *amount; - blinded_messages.push(blinded_message); - } - - // commit db transaction before calling the signatory - tx.commit().await?; - - let change_sigs = self.blind_sign(blinded_messages).await?; - - let mut tx = self.localstore.begin_transaction().await?; - - tx.add_blind_signatures( - &outputs[0..change_sigs.len()] - .iter() - .map(|o| o.blinded_secret) - .collect::>(), - &change_sigs, - Some(quote.id.clone()), - ) - .await?; - - change = Some(change_sigs); - - proof_writer.commit(); + // Step 1: Setup (TX1 - reserves inputs and outputs) + let setup_saga = init_saga.setup_melt(melt_request, verification).await?; - tx.delete_melt_request("e.id).await?; + // Step 2: Attempt internal settlement (returns saga + SettlementDecision) + // Note: Compensation is handled internally if this fails + let (setup_saga, settlement) = setup_saga.attempt_internal_settlement(melt_request).await?; - tx.commit().await?; - } else { - tracing::info!( - "Inputs for {} {} greater then spent on melt {} but change outputs not provided.", - quote.id, - inputs_amount, - total_spent - ); - proof_writer.commit(); - tx.delete_melt_request("e.id).await?; - tx.commit().await?; - } - } else { - tracing::debug!("No change required for melt {}", quote.id); - proof_writer.commit(); - tx.delete_melt_request("e.id).await?; - tx.commit().await?; - } - - self.pubsub_manager.melt_quote_status( - "e, - payment_preimage.clone(), - change.clone(), - MeltQuoteState::Paid, - ); - tracing::debug!( - "Melt for quote {} completed total spent {}, total inputs: {}, change given: {}", - quote.id, - total_spent, - inputs_amount, - change - .as_ref() - .map(|c| Amount::try_sum(c.iter().map(|a| a.amount)) - .expect("Change cannot overflow")) - .unwrap_or_default() - ); - let response = MeltQuoteBolt11Response { - amount: quote.amount, - paid: Some(true), - payment_preimage, - change, - quote: quote.id, - fee_reserve: quote.fee_reserve, - state: MeltQuoteState::Paid, - expiry: quote.expiry, - request: Some(quote.request.to_string()), - unit: Some(quote.unit.clone()), - }; - - #[cfg(feature = "prometheus")] - { - METRICS.dec_in_flight_requests("process_melt_request"); - METRICS.record_mint_operation("process_melt_request", true); - } - - Ok(response) - } + // Step 3: Make payment (internal or external) + let payment_saga = setup_saga.make_payment(settlement).await?; - #[cfg(feature = "prometheus")] - fn record_melt_quote_failure(&self, operation: &str) { - METRICS.dec_in_flight_requests(operation); - METRICS.record_mint_operation(operation, false); - METRICS.record_error(); + // Step 4: Finalize (TX2 - marks spent, issues change) + payment_saga.finalize().await } } diff --git a/crates/cdk/src/mint/melt/melt_saga/compensation.rs b/crates/cdk/src/mint/melt/melt_saga/compensation.rs new file mode 100644 index 000000000..560b71f7e --- /dev/null +++ b/crates/cdk/src/mint/melt/melt_saga/compensation.rs @@ -0,0 +1,65 @@ +//! Compensation actions for the melt saga pattern. +//! +//! When a saga step fails, compensating actions are executed in reverse order (LIFO) +//! to undo all completed steps and restore the database to its pre-saga state. + +use async_trait::async_trait; +use cdk_common::database::DynMintDatabase; +use cdk_common::{Error, PublicKey, QuoteId}; +use tracing::instrument; + +/// Trait for compensating actions in the saga pattern. +/// +/// Compensating actions are registered as steps complete and executed in reverse +/// order (LIFO) if the saga fails. Each action should be idempotent. +#[async_trait] +pub trait CompensatingAction: Send + Sync { + async fn execute(&self, db: &DynMintDatabase) -> Result<(), Error>; + fn name(&self) -> &'static str; +} + +/// Compensation action to remove melt setup and reset quote state. +/// +/// This compensation is used when payment fails or finalization fails after +/// the setup transaction has committed. It removes: +/// - Input proofs (identified by input_ys) +/// - Output blinded messages (identified by blinded_secrets) +/// - Melt request tracking record +/// +/// And resets: +/// - Quote state from Pending back to Unpaid +/// +/// This restores the database to its pre-melt state, allowing the user to retry. +pub struct RemoveMeltSetup { + /// Y values (public keys) from the input proofs + pub input_ys: Vec, + /// Blinded secrets (B values) from the change output blinded messages + pub blinded_secrets: Vec, + /// Quote ID to reset state + pub quote_id: QuoteId, +} + +#[async_trait] +impl CompensatingAction for RemoveMeltSetup { + #[instrument(skip_all)] + async fn execute(&self, db: &DynMintDatabase) -> Result<(), Error> { + tracing::info!( + "Compensation: Removing melt setup for quote {} ({} proofs, {} blinded messages)", + self.quote_id, + self.input_ys.len(), + self.blinded_secrets.len() + ); + + super::super::shared::rollback_melt_quote( + db, + &self.quote_id, + &self.input_ys, + &self.blinded_secrets, + ) + .await + } + + fn name(&self) -> &'static str { + "RemoveMeltSetup" + } +} diff --git a/crates/cdk/src/mint/melt/melt_saga/mod.rs b/crates/cdk/src/mint/melt/melt_saga/mod.rs new file mode 100644 index 000000000..2bd95aab8 --- /dev/null +++ b/crates/cdk/src/mint/melt/melt_saga/mod.rs @@ -0,0 +1,909 @@ +use std::collections::VecDeque; +use std::sync::Arc; + +use cdk_common::amount::to_unit; +use cdk_common::database::mint::MeltRequestInfo; +use cdk_common::database::DynMintDatabase; +use cdk_common::mint::{MeltSagaState, Operation, Saga}; +use cdk_common::nuts::MeltQuoteState; +use cdk_common::{Amount, Error, ProofsMethods, PublicKey, QuoteId, State}; +#[cfg(feature = "prometheus")] +use cdk_prometheus::METRICS; +use tokio::sync::Mutex; +use tracing::instrument; + +use self::compensation::{CompensatingAction, RemoveMeltSetup}; +use self::state::{Initial, PaymentConfirmed, SettlementDecision, SetupComplete}; +use crate::cdk_payment::MakePaymentResponse; +use crate::mint::subscription::PubSubManager; +use crate::mint::verification::Verification; +use crate::mint::{MeltQuoteBolt11Response, MeltRequest}; + +mod compensation; +mod state; + +#[cfg(test)] +mod tests; + +/// Saga pattern implementation for atomic melt operations. +/// +/// # Why Use the Saga Pattern for Melt? +/// +/// The melt operation is more complex than swap because it involves: +/// 1. Database transactions (setup and finalize) +/// 2. External payment operations (Lightning Network) +/// 3. Uncertain payment states (pending/unknown) +/// 4. Change calculation based on actual payment amount +/// +/// Traditional ACID transactions cannot span: +/// 1. Multiple database transactions (TX1: setup, TX2: finalize) +/// 2. External payment operations (LN backend calls) +/// 3. Asynchronous payment confirmation +/// +/// The saga pattern solves this by: +/// - Breaking the operation into discrete steps with clear state transitions +/// - Recording compensating actions for each forward step +/// - Automatically rolling back via compensations if any step fails +/// - Handling payment state uncertainty explicitly +/// +/// # Transaction Boundaries +/// +/// - **TX1 (setup_melt)**: Atomically verifies quote, adds input proofs (pending), +/// adds change output blinded messages, creates melt request tracking record +/// - **Payment (make_payment)**: Non-transactional external LN payment operation +/// - **TX2 (finalize)**: Atomically updates quote state, marks inputs spent, +/// signs change outputs, deletes tracking record +/// +/// # Expected Flow +/// +/// 1. **setup_melt**: Verifies and reserves inputs, prepares change outputs +/// - Compensation: Removes inputs, outputs, resets quote state if later steps fail +/// 2. **make_payment**: Calls LN backend to make payment +/// - Triggers compensation if payment fails +/// - Special handling for pending/unknown states +/// 3. **finalize**: Commits the melt, issues change, marks complete +/// - Triggers compensation if finalization fails +/// - Clears compensations on success (melt complete) +/// +/// # Failure Handling +/// +/// If any step fails after setup_melt, all compensating actions are executed in reverse +/// order to restore the database to its pre-melt state. This ensures no partial melts +/// leave the system in an inconsistent state. +/// +/// # Payment State Complexity +/// +/// Unlike swap, melt must handle uncertain payment states: +/// - **Paid**: Proceed to finalize +/// - **Failed/Unpaid**: Compensate and return error +/// - **Pending/Unknown**: Proofs remain pending, saga cannot complete +/// (current behavior: leave proofs pending, return error for manual intervention) +/// +/// # Typestate Pattern +/// +/// This saga uses the **typestate pattern** to enforce state transitions at compile-time. +/// Each state (Initial, SetupComplete, PaymentConfirmed) is a distinct type, and operations +/// are only available on the appropriate type: +/// +/// ```text +/// MeltSaga +/// └─> setup_melt() -> MeltSaga +/// ├─> attempt_internal_settlement() -> SettlementDecision (conditional) +/// └─> make_payment(SettlementDecision) -> MeltSaga +/// └─> finalize() -> MeltQuoteBolt11Response +/// ``` +/// +/// **Benefits:** +/// - Invalid state transitions (e.g., `finalize()` before `make_payment()`) won't compile +/// - State-specific data (e.g., payment_result) only exists in the appropriate state type +/// - No runtime state checks or `Option` unwrapping needed +/// - IDE autocomplete only shows valid operations for each state +pub struct MeltSaga { + mint: Arc, + db: DynMintDatabase, + pubsub: Arc, + /// Compensating actions in LIFO order (most recent first) + compensations: Arc>>>, + /// Operation for tracking + operation: Operation, + /// Tracks if metrics were incremented (for cleanup) + #[cfg(feature = "prometheus")] + metrics_incremented: bool, + /// State-specific data + state_data: S, +} + +impl MeltSaga { + pub fn new(mint: Arc, db: DynMintDatabase, pubsub: Arc) -> Self { + #[cfg(feature = "prometheus")] + METRICS.inc_in_flight_requests("melt_bolt11"); + + Self { + mint, + db, + pubsub, + compensations: Arc::new(Mutex::new(VecDeque::new())), + operation: Operation::new_melt(), + #[cfg(feature = "prometheus")] + metrics_incremented: true, + state_data: Initial, + } + } + + /// Sets up the melt by atomically verifying and reserving inputs/outputs. + /// + /// This is the first transaction (TX1) in the saga and must complete before payment. + /// + /// # What This Does + /// + /// Within a single database transaction: + /// 1. Verifies the melt request (inputs, quote state, balance) + /// 2. Adds input proofs to the database with Pending state + /// 3. Updates quote state from Unpaid/Failed to Pending + /// 4. Adds change output blinded messages to the database + /// 5. Creates melt request tracking record + /// 6. Publishes proof state changes via pubsub + /// + /// # Compensation + /// + /// Registers a compensation action that will: + /// - Remove input proofs + /// - Remove blinded messages + /// - Reset quote state from Pending to Unpaid + /// - Delete melt request tracking record + /// + /// This compensation runs if payment or finalization fails. + /// + /// # Errors + /// + /// - `PendingQuote`: Quote is already in Pending state + /// - `PaidQuote`: Quote has already been paid + /// - `TokenAlreadySpent`: Input proofs have already been spent + /// - `UnitMismatch`: Input unit doesn't match quote unit + #[instrument(skip_all)] + pub async fn setup_melt( + self, + melt_request: &MeltRequest, + input_verification: Verification, + ) -> Result, Error> { + tracing::info!("TX1: Setting up melt (verify + inputs + outputs)"); + + let Verification { + amount: input_amount, + unit: input_unit, + } = input_verification; + + let mut tx = self.db.begin_transaction().await?; + + // Add proofs to the database + if let Err(err) = tx + .add_proofs( + melt_request.inputs().clone(), + Some(melt_request.quote_id().to_owned()), + &self.operation, + ) + .await + { + tx.rollback().await?; + return Err(match err { + cdk_common::database::Error::Duplicate => Error::TokenPending, + cdk_common::database::Error::AttemptUpdateSpentProof => Error::TokenAlreadySpent, + err => Error::Database(err), + }); + } + + let input_ys = melt_request.inputs().ys()?; + + // Update proof states to Pending + let original_states = match tx.update_proofs_states(&input_ys, State::Pending).await { + Ok(states) => states, + Err(cdk_common::database::Error::AttemptUpdateSpentProof) + | Err(cdk_common::database::Error::AttemptRemoveSpentProof) => { + tx.rollback().await?; + return Err(Error::TokenAlreadySpent); + } + Err(err) => { + tx.rollback().await?; + return Err(err.into()); + } + }; + + // Check for forbidden states (Pending or Spent) + let has_forbidden_state = original_states + .iter() + .any(|state| matches!(state, Some(State::Pending) | Some(State::Spent))); + + if has_forbidden_state { + tx.rollback().await?; + return Err( + if original_states + .iter() + .any(|s| matches!(s, Some(State::Pending))) + { + Error::TokenPending + } else { + Error::TokenAlreadySpent + }, + ); + } + + // Publish proof state changes + for pk in input_ys.iter() { + self.pubsub.proof_state((*pk, State::Pending)); + } + + // Update quote state to Pending + let (state, quote) = tx + .update_melt_quote_state(melt_request.quote(), MeltQuoteState::Pending, None) + .await?; + + if input_unit != Some(quote.unit.clone()) { + tx.rollback().await?; + return Err(Error::UnitMismatch); + } + + match state { + MeltQuoteState::Unpaid | MeltQuoteState::Failed => {} + MeltQuoteState::Pending => { + tx.rollback().await?; + return Err(Error::PendingQuote); + } + MeltQuoteState::Paid => { + tx.rollback().await?; + return Err(Error::PaidQuote); + } + MeltQuoteState::Unknown => { + tx.rollback().await?; + return Err(Error::UnknownPaymentState); + } + } + + self.pubsub + .melt_quote_status("e, None, None, MeltQuoteState::Pending); + + let fee = self.mint.get_proofs_fee(melt_request.inputs()).await?; + + let required_total = quote.amount + quote.fee_reserve + fee; + + if input_amount < required_total { + tracing::info!( + "Melt request unbalanced: inputs {}, amount {}, fee {}", + input_amount, + quote.amount, + fee + ); + tx.rollback().await?; + return Err(Error::TransactionUnbalanced( + input_amount.into(), + quote.amount.into(), + (fee + quote.fee_reserve).into(), + )); + } + + // Verify outputs if provided + if let Some(outputs) = &melt_request.outputs() { + if !outputs.is_empty() { + let output_verification = match self.mint.verify_outputs(&mut tx, outputs).await { + Ok(verification) => verification, + Err(err) => { + tx.rollback().await?; + return Err(err); + } + }; + + if input_unit != output_verification.unit { + tx.rollback().await?; + return Err(Error::UnitMismatch); + } + } + } + + let inputs_fee = self.mint.get_proofs_fee(melt_request.inputs()).await?; + + // Add melt request tracking record + tx.add_melt_request( + melt_request.quote_id(), + melt_request.inputs_amount()?, + inputs_fee, + ) + .await?; + + // Add change output blinded messages + tx.add_blinded_messages( + Some(melt_request.quote_id()), + melt_request.outputs().as_ref().unwrap_or(&Vec::new()), + &self.operation, + ) + .await?; + + // Get blinded secrets for compensation + let blinded_secrets: Vec = melt_request + .outputs() + .as_ref() + .unwrap_or(&Vec::new()) + .iter() + .map(|bm| bm.blinded_secret) + .collect(); + + // Persist saga state for crash recovery (atomic with TX1) + let saga = Saga::new_melt( + *self.operation.id(), + MeltSagaState::SetupComplete, + input_ys.clone(), + blinded_secrets.clone(), + quote.id.to_string(), + ); + + if let Err(err) = tx.add_saga(&saga).await { + tx.rollback().await?; + return Err(err.into()); + } + + tx.commit().await?; + + // Store blinded messages for state + let blinded_messages_vec = melt_request.outputs().clone().unwrap_or_default(); + + // Register compensation (uses LIFO via push_front) + let compensations = Arc::clone(&self.compensations); + compensations + .lock() + .await + .push_front(Box::new(RemoveMeltSetup { + input_ys: input_ys.clone(), + blinded_secrets, + quote_id: quote.id.clone(), + })); + + // Transition to SetupComplete state + Ok(MeltSaga { + mint: self.mint, + db: self.db, + pubsub: self.pubsub, + compensations: self.compensations, + operation: self.operation, + #[cfg(feature = "prometheus")] + metrics_incremented: self.metrics_incremented, + state_data: SetupComplete { + quote, + input_ys, + blinded_messages: blinded_messages_vec, + }, + }) + } +} + +impl MeltSaga { + /// Attempts to settle the melt internally (melt-to-mint on same mint). + /// + /// This checks if the payment request corresponds to an existing mint quote + /// on the same mint, and if so, settles it atomically within a transaction. + /// + /// # What This Does + /// + /// Within a single database transaction: + /// 1. Checks if payment request matches a mint quote on this mint + /// 2. If not a match or different unit: returns (self, RequiresExternalPayment) + /// 3. If match found: validates quote state and amount + /// 4. Increments the mint quote's paid amount + /// 5. Publishes mint quote payment notification + /// 6. Returns (self, Internal{amount}) + /// + /// # Compensation + /// + /// If internal settlement fails, this method automatically calls compensate_all() + /// to roll back the setup_melt changes before returning the error. The saga is + /// consumed on error, so the caller cannot continue. + /// + /// # Returns + /// + /// - `Ok((self, Internal{amount}))`: Internal settlement succeeded, saga can continue + /// - `Ok((self, RequiresExternalPayment))`: Not an internal payment, saga can continue + /// - `Err(_)`: Internal settlement attempted but failed (compensations executed, saga consumed) + /// + /// # Errors + /// + /// - `RequestAlreadyPaid`: Mint quote already settled + /// - `InsufficientFunds`: Not enough input proofs for mint quote amount + /// - `Internal`: Database error during settlement + #[instrument(skip_all)] + pub async fn attempt_internal_settlement( + self, + melt_request: &MeltRequest, + ) -> Result<(Self, SettlementDecision), Error> { + tracing::info!("Checking for internal settlement opportunity"); + + let mut tx = self.db.begin_transaction().await?; + + let mint_quote = match tx + .get_mint_quote_by_request(&self.state_data.quote.request.to_string()) + .await + { + Ok(Some(mint_quote)) if mint_quote.unit == self.state_data.quote.unit => mint_quote, + Ok(_) => { + tx.rollback().await?; + tracing::debug!("Not an internal payment or unit mismatch"); + return Ok((self, SettlementDecision::RequiresExternalPayment)); + } + Err(err) => { + tx.rollback().await?; + tracing::debug!("Error checking for mint quote: {}", err); + self.compensate_all().await?; + return Err(Error::Internal); + } + }; + + // Mint quote has already been settled + if (mint_quote.state() == cdk_common::nuts::MintQuoteState::Issued + || mint_quote.state() == cdk_common::nuts::MintQuoteState::Paid) + && mint_quote.payment_method == crate::mint::PaymentMethod::Bolt11 + { + tx.rollback().await?; + self.compensate_all().await?; + return Err(Error::RequestAlreadyPaid); + } + + let inputs_amount_quote_unit = melt_request.inputs_amount().map_err(|_| { + tracing::error!("Proof inputs in melt quote overflowed"); + Error::AmountOverflow + })?; + + if let Some(amount) = mint_quote.amount { + if amount > inputs_amount_quote_unit { + tracing::debug!( + "Not enough inputs provided: {} needed {}", + inputs_amount_quote_unit, + amount + ); + tx.rollback().await?; + self.compensate_all().await?; + return Err(Error::InsufficientFunds); + } + } + + let amount = self.state_data.quote.amount; + + tracing::info!( + "Mint quote {} paid {} from internal payment.", + mint_quote.id, + amount + ); + + let total_paid = tx + .increment_mint_quote_amount_paid( + &mint_quote.id, + amount, + self.state_data.quote.id.to_string(), + ) + .await?; + + self.pubsub.mint_quote_payment(&mint_quote, total_paid); + + tracing::info!( + "Melt quote {} paid Mint quote {}", + self.state_data.quote.id, + mint_quote.id + ); + + tx.commit().await?; + + Ok((self, SettlementDecision::Internal { amount })) + } + + /// Makes payment via Lightning Network backend or internal settlement. + /// + /// This is an external operation that happens after `setup_melt` and before `finalize`. + /// No database changes occur in this step (except for internal settlement case). + /// + /// # What This Does + /// + /// 1. Takes a SettlementDecision from attempt_internal_settlement + /// 2. If Internal: creates payment result directly + /// 3. If RequiresExternalPayment: calls LN backend + /// 4. Handles payment result states with idempotent verification + /// 5. Transitions to PaymentConfirmed state on success + /// + /// # Idempotent Payment Verification + /// + /// Lightning payments are asynchronous, and the LN backend may return different + /// states for the same payment query due to: + /// - Network latency between payment initiation and confirmation + /// - Backend database replication lag + /// - HTLC settlement timing + /// + /// **Critical Principle**: If `check_payment_state()` confirms the payment as Paid, + /// we MUST proceed to finalize, regardless of what `make_payment()` initially returned. + /// This ensures the saga is idempotent with respect to payment confirmation. + /// + /// # Failure Handling + /// + /// If payment is confirmed as failed/unpaid, all registered compensations are + /// executed to roll back the setup transaction. + /// + /// # Errors + /// + /// - `PaymentFailed`: Payment confirmed as failed/unpaid + /// - `PendingQuote`: Payment is pending (will be resolved by startup check) + #[instrument(skip_all)] + pub async fn make_payment( + self, + settlement: SettlementDecision, + ) -> Result, Error> { + tracing::info!("Making payment (external LN operation or internal settlement)"); + + let payment_result = match settlement { + SettlementDecision::Internal { amount } => { + tracing::info!( + "Payment settled internally for {} {}", + amount, + self.state_data.quote.unit + ); + MakePaymentResponse { + status: MeltQuoteState::Paid, + total_spent: amount, + unit: self.state_data.quote.unit.clone(), + payment_proof: None, + payment_lookup_id: self + .state_data + .quote + .request_lookup_id + .clone() + .unwrap_or_else(|| { + cdk_common::payment::PaymentIdentifier::CustomId( + self.state_data.quote.id.to_string(), + ) + }), + } + } + SettlementDecision::RequiresExternalPayment => { + // Get LN payment processor + let ln = self + .mint + .payment_processors + .get(&crate::types::PaymentProcessorKey::new( + self.state_data.quote.unit.clone(), + self.state_data.quote.payment_method.clone(), + )) + .ok_or_else(|| { + tracing::info!( + "Could not get ln backend for {}, {}", + self.state_data.quote.unit, + self.state_data.quote.payment_method + ); + Error::UnsupportedUnit + })?; + + // Make payment with idempotent verification + let payment_response = match ln + .make_payment( + &self.state_data.quote.unit, + self.state_data.quote.clone().try_into()?, + ) + .await + { + Ok(pay) + if pay.status == MeltQuoteState::Unknown + || pay.status == MeltQuoteState::Failed => + { + tracing::warn!( + "Got {} status when paying melt quote {} for {} {}. Verifying with backend...", + pay.status, + self.state_data.quote.id, + self.state_data.quote.amount, + self.state_data.quote.unit + ); + + let check_response = self + .check_payment_state(Arc::clone(ln), &pay.payment_lookup_id) + .await?; + + if check_response.status == MeltQuoteState::Paid { + // Race condition: Payment succeeded during verification + tracing::info!( + "Payment initially returned {} but confirmed as Paid. Proceeding to finalize.", + pay.status + ); + check_response + } else { + check_response + } + } + Ok(pay) => pay, + Err(err) => { + if matches!(err, crate::cdk_payment::Error::InvoiceAlreadyPaid) { + tracing::info!("Invoice already paid, verifying payment status"); + } else { + // Other error - check if payment actually succeeded + tracing::error!( + "Error returned attempting to pay: {} {}", + self.state_data.quote.id, + err + ); + } + + let lookup_id = self + .state_data + .quote + .request_lookup_id + .as_ref() + .ok_or_else(|| { + tracing::error!( + "No payment id, cannot verify payment status for {} after error", + self.state_data.quote.id + ); + Error::Internal + })?; + + let check_response = + self.check_payment_state(Arc::clone(ln), lookup_id).await?; + + tracing::info!( + "Initial payment attempt for {} errored. Follow up check stateus: {}", + self.state_data.quote.id, + check_response.status + ); + + check_response + } + }; + + match payment_response.status { + MeltQuoteState::Paid => payment_response, + MeltQuoteState::Unpaid | MeltQuoteState::Failed => { + tracing::info!( + "Lightning payment for quote {} failed.", + self.state_data.quote.id + ); + self.compensate_all().await?; + return Err(Error::PaymentFailed); + } + MeltQuoteState::Unknown => { + tracing::warn!( + "LN payment unknown, proofs remain pending for quote: {}", + self.state_data.quote.id + ); + return Err(Error::PaymentFailed); + } + MeltQuoteState::Pending => { + tracing::warn!( + "LN payment pending, proofs remain pending for quote: {}", + self.state_data.quote.id + ); + return Err(Error::PendingQuote); + } + } + } + }; + + // TODO: Add total spent > quote check + + // Transition to PaymentConfirmed state + Ok(MeltSaga { + mint: self.mint, + db: self.db, + pubsub: self.pubsub, + compensations: self.compensations, + operation: self.operation, + #[cfg(feature = "prometheus")] + metrics_incremented: self.metrics_incremented, + state_data: PaymentConfirmed { + quote: self.state_data.quote, + input_ys: self.state_data.input_ys, + blinded_messages: self.state_data.blinded_messages, + payment_result, + }, + }) + } + + /// Helper to check payment state with LN backend + async fn check_payment_state( + &self, + ln: Arc< + dyn cdk_common::payment::MintPayment + Send + Sync, + >, + lookup_id: &cdk_common::payment::PaymentIdentifier, + ) -> Result { + match ln.check_outgoing_payment(lookup_id).await { + Ok(response) => Ok(response), + Err(check_err) => { + tracing::error!( + "Could not check the status of payment for {}. Proofs stuck as pending", + lookup_id + ); + tracing::error!("Checking payment error: {}", check_err); + Err(Error::Internal) + } + } + } +} + +impl MeltSaga { + /// Finalizes the melt by committing signatures and marking inputs as spent. + /// + /// This is the second and final transaction (TX2) in the saga and completes the melt. + /// + /// # What This Does + /// + /// Within a single database transaction: + /// 1. Updates quote state to Paid + /// 2. Updates payment lookup ID if changed + /// 3. Marks input proofs as Spent + /// 4. Calculates and signs change outputs (if applicable) + /// 5. Deletes melt request tracking record + /// 6. Publishes quote status changes via pubsub + /// 7. Clears all registered compensations (melt successfully completed) + /// + /// # Change Handling + /// + /// If inputs > total_spent: + /// - If change outputs were provided: sign them and return + /// - If no change outputs: change is burnt (logged as info) + /// + /// # Success + /// + /// On success, compensations are cleared and the melt is complete. + /// + /// # Errors + /// + /// - `TokenAlreadySpent`: Input proofs were already spent + /// - `BlindedMessageAlreadySigned`: Change outputs already signed + #[instrument(skip_all)] + pub async fn finalize(self) -> Result, Error> { + tracing::info!("TX2: Finalizing melt (mark spent + change)"); + + let total_spent = to_unit( + self.state_data.payment_result.total_spent, + &self.state_data.payment_result.unit, + &self.state_data.quote.unit, + ) + .unwrap_or_default(); + + let payment_preimage = self.state_data.payment_result.payment_proof.clone(); + let payment_lookup_id = &self.state_data.payment_result.payment_lookup_id; + + let mut tx = self.db.begin_transaction().await?; + + // Get melt request info first (needed for validation and change) + let MeltRequestInfo { + inputs_amount, + inputs_fee, + change_outputs, + } = tx + .get_melt_request_and_blinded_messages(&self.state_data.quote.id) + .await? + .ok_or(Error::UnknownQuote)?; + + // Use shared core finalization logic + if let Err(err) = super::shared::finalize_melt_core( + &mut tx, + &self.pubsub, + &self.state_data.quote, + &self.state_data.input_ys, + inputs_amount, + inputs_fee, + total_spent, + payment_preimage.clone(), + payment_lookup_id, + ) + .await + { + tx.rollback().await?; + self.compensate_all().await?; + return Err(err); + } + + let needs_change = inputs_amount > total_spent; + + // Handle change: either sign change outputs or just commit TX1 + let (change, mut tx) = if !needs_change { + // No change required - just commit TX1 + tracing::debug!("No change required for melt {}", self.state_data.quote.id); + (None, tx) + } else { + // We commit tx here as process_change can make external call to blind sign + // We do not want to hold db txs across external calls + tx.commit().await?; + super::shared::process_melt_change( + &self.mint, + &self.db, + &self.state_data.quote.id, + inputs_amount, + total_spent, + inputs_fee, + change_outputs, + ) + .await? + }; + + tx.delete_melt_request(&self.state_data.quote.id).await?; + + // Delete saga - melt completed successfully (best-effort) + if let Err(e) = tx.delete_saga(self.operation.id()).await { + tracing::warn!("Failed to delete saga in finalize: {}", e); + // Don't rollback - melt succeeded + } + + tx.commit().await?; + + self.pubsub.melt_quote_status( + &self.state_data.quote, + payment_preimage.clone(), + change.clone(), + MeltQuoteState::Paid, + ); + + tracing::debug!( + "Melt for quote {} completed total spent {}, total inputs: {}, change given: {}", + self.state_data.quote.id, + total_spent, + inputs_amount, + change + .as_ref() + .map(|c| Amount::try_sum(c.iter().map(|a| a.amount)) + .expect("Change cannot overflow")) + .unwrap_or_default() + ); + + self.compensations.lock().await.clear(); + + #[cfg(feature = "prometheus")] + if self.metrics_incremented { + METRICS.dec_in_flight_requests("melt_bolt11"); + METRICS.record_mint_operation("melt_bolt11", true); + } + + let response = MeltQuoteBolt11Response { + amount: self.state_data.quote.amount, + paid: Some(true), + payment_preimage, + change, + quote: self.state_data.quote.id, + fee_reserve: self.state_data.quote.fee_reserve, + state: MeltQuoteState::Paid, + expiry: self.state_data.quote.expiry, + request: Some(self.state_data.quote.request.to_string()), + unit: Some(self.state_data.quote.unit.clone()), + }; + + Ok(response) + } +} + +impl MeltSaga { + /// Execute all compensating actions and consume the saga. + /// + /// This method takes ownership of self to ensure the saga cannot be used + /// after compensation has been triggered. + /// + /// This is called internally by saga methods when they need to compensate. + #[instrument(skip_all)] + async fn compensate_all(self) -> Result<(), Error> { + let mut compensations = self.compensations.lock().await; + + if compensations.is_empty() { + return Ok(()); + } + + #[cfg(feature = "prometheus")] + if self.metrics_incremented { + METRICS.dec_in_flight_requests("melt_bolt11"); + METRICS.record_mint_operation("melt_bolt11", false); + METRICS.record_error(); + } + + tracing::warn!("Running {} compensating actions", compensations.len()); + + while let Some(compensation) = compensations.pop_front() { + tracing::debug!("Running compensation: {}", compensation.name()); + if let Err(e) = compensation.execute(&self.db).await { + tracing::error!( + "Compensation {} failed: {}. Continuing...", + compensation.name(), + e + ); + } + } + + Ok(()) + } +} diff --git a/crates/cdk/src/mint/melt/melt_saga/state.rs b/crates/cdk/src/mint/melt/melt_saga/state.rs new file mode 100644 index 000000000..b6ade7662 --- /dev/null +++ b/crates/cdk/src/mint/melt/melt_saga/state.rs @@ -0,0 +1,46 @@ +use cdk_common::nuts::BlindedMessage; +use cdk_common::{Amount, PublicKey}; + +use crate::cdk_payment::MakePaymentResponse; +use crate::mint::MeltQuote; + +/// Initial state - no data yet. +/// +/// The melt saga starts in this state. Only the `setup_melt` method is available. +pub struct Initial; + +/// Setup complete - has quote, input Ys, and blinded messages. +/// +/// After successful setup, the saga transitions to this state. +/// The `attempt_internal_settlement` and `make_payment` methods are available. +pub struct SetupComplete { + pub quote: MeltQuote, + pub input_ys: Vec, + pub blinded_messages: Vec, +} + +/// Payment confirmed - has everything including payment result. +/// +/// After successful payment (internal or external), the saga transitions to this state. +/// Only the `finalize` method is available. +pub struct PaymentConfirmed { + pub quote: MeltQuote, + pub input_ys: Vec, + #[allow(dead_code)] // Stored for completeness, accessed from DB in finalize + pub blinded_messages: Vec, + pub payment_result: MakePaymentResponse, +} + +/// Result of attempting internal settlement for a melt operation. +/// +/// This enum represents the decision point in the melt flow: +/// - Internal settlement succeeded → skip external Lightning payment +/// - External payment required → proceed with Lightning Network call +#[derive(Debug, Clone)] +pub enum SettlementDecision { + /// Payment was settled internally (melt-to-mint on the same mint). + /// Contains the amount that was settled. + Internal { amount: Amount }, + /// Payment requires external Lightning Network settlement. + RequiresExternalPayment, +} diff --git a/crates/cdk/src/mint/melt/melt_saga/tests.rs b/crates/cdk/src/mint/melt/melt_saga/tests.rs new file mode 100644 index 000000000..b92e0df95 --- /dev/null +++ b/crates/cdk/src/mint/melt/melt_saga/tests.rs @@ -0,0 +1,2132 @@ +//! Tests for melt saga pattern implementation +//! +//! This test module covers: +//! - Basic state transitions +//! - Crash recovery scenarios +//! - Saga persistence and deletion +//! - Compensation execution +//! - Concurrent operations +//! - Failure handling + +#![cfg(test)] + +use cdk_common::mint::{MeltSagaState, OperationKind, Saga}; +use cdk_common::nuts::MeltQuoteState; +use cdk_common::{Amount, ProofsMethods, State}; + +use crate::mint::melt::melt_saga::MeltSaga; +use crate::test_helpers::mint::{create_test_mint, mint_test_proofs}; + +// ============================================================================ +// Basic State Transition Tests +// ============================================================================ + +/// Test: Saga can be created in Initial state +#[tokio::test] +async fn test_melt_saga_initial_state_creation() { + let mint = create_test_mint().await.unwrap(); + let db = mint.localstore(); + let pubsub = mint.pubsub_manager(); + + let _saga = MeltSaga::new(std::sync::Arc::new(mint.clone()), db, pubsub); + // Type system enforces Initial state - if this compiles, test passes +} + +// ============================================================================ +// Saga Persistence Tests +// ============================================================================ + +/// Test: Saga state is persisted atomically with setup transaction +#[tokio::test] +async fn test_saga_state_persistence_after_setup() { + // STEP 1: Setup test environment + let mint = create_test_mint().await.unwrap(); + let proofs = mint_test_proofs(&mint, Amount::from(10_000)).await.unwrap(); + let quote = create_test_melt_quote(&mint, Amount::from(9_000)).await; + let melt_request = create_test_melt_request(&proofs, "e); + + // STEP 2: Setup melt saga + let verification = mint.verify_inputs(melt_request.inputs()).await.unwrap(); + let saga = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let setup_saga = saga.setup_melt(&melt_request, verification).await.unwrap(); + + let operation_id = *setup_saga.operation.id(); + + // STEP 3: Query database for saga + let sagas = mint + .localstore + .get_incomplete_sagas(OperationKind::Melt) + .await + .unwrap(); + + // STEP 4: Find our saga + let persisted_saga = sagas + .iter() + .find(|s| s.operation_id == operation_id) + .expect("Saga should be persisted"); + + // STEP 5: Validate saga content + assert_eq!( + persisted_saga.operation_id, operation_id, + "Operation ID should match" + ); + assert_eq!( + persisted_saga.operation_kind, + OperationKind::Melt, + "Operation kind should be Melt" + ); + + // Verify state is SetupComplete + match &persisted_saga.state { + cdk_common::mint::SagaStateEnum::Melt(state) => { + assert_eq!( + *state, + MeltSagaState::SetupComplete, + "State should be SetupComplete" + ); + } + _ => panic!("Expected Melt saga state"), + } + + // STEP 6: Verify input_ys are stored + let input_ys = proofs.ys().unwrap(); + assert_eq!( + persisted_saga.input_ys.len(), + input_ys.len(), + "Should store all input Ys" + ); + for y in &input_ys { + assert!( + persisted_saga.input_ys.contains(y), + "Input Y should be stored: {:?}", + y + ); + } + + // STEP 7: Verify timestamps are set + assert!( + persisted_saga.created_at > 0, + "Created timestamp should be set" + ); + assert!( + persisted_saga.updated_at > 0, + "Updated timestamp should be set" + ); + assert_eq!( + persisted_saga.created_at, persisted_saga.updated_at, + "Timestamps should match for new saga" + ); + + // STEP 8: Verify blinded_secrets is empty (not used for melt) + assert!( + persisted_saga.blinded_secrets.is_empty(), + "Melt saga should not store blinded_secrets" + ); + + // SUCCESS: Saga persisted correctly! +} + +/// Test: Saga is deleted after successful finalization +#[tokio::test] +async fn test_saga_deletion_on_success() { + // STEP 1: Setup test environment (FakeWallet handles payments automatically) + let mint = create_test_mint().await.unwrap(); + + // STEP 2: Create proofs and quote + let proofs = mint_test_proofs(&mint, Amount::from(10_000)).await.unwrap(); + let quote = create_test_melt_quote(&mint, Amount::from(9_000)).await; + let melt_request = create_test_melt_request(&proofs, "e); + + // STEP 3: Complete full melt flow + let verification = mint.verify_inputs(melt_request.inputs()).await.unwrap(); + let saga = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + + // Setup + let setup_saga = saga.setup_melt(&melt_request, verification).await.unwrap(); + let operation_id = *setup_saga.operation.id(); + + // Verify saga exists + assert_saga_exists(&mint, &operation_id).await; + + // Attempt internal settlement (will fail, go to external payment) + let (payment_saga, decision) = setup_saga + .attempt_internal_settlement(&melt_request) + .await + .unwrap(); + + // Make payment (FakeWallet will return success based on FakeInvoiceDescription) + let confirmed_saga = payment_saga.make_payment(decision).await.unwrap(); + + // Finalize + let _response = confirmed_saga.finalize().await.unwrap(); + + // STEP 4: Verify saga was deleted + assert_saga_not_exists(&mint, &operation_id).await; + + // STEP 5: Verify no incomplete sagas remain + let sagas = mint + .localstore + .get_incomplete_sagas(OperationKind::Melt) + .await + .unwrap(); + assert!(sagas.is_empty(), "Should have no incomplete melt sagas"); + + // SUCCESS: Saga cleaned up on success! +} + +/// Test: Saga remains in database if finalize fails +#[tokio::test] +async fn test_saga_persists_on_finalize_failure() { + // TODO: Implement this test + // 1. Setup melt saga successfully + // 2. Simulate finalize failure (e.g., database error) + // 3. Verify saga still exists in database + // 4. Verify state is still SetupComplete +} + +// ============================================================================ +// Crash Recovery Tests - SetupComplete State +// ============================================================================ + +/// Test: Recovery from crash after setup but before payment +/// +/// This is the primary crash recovery scenario. If the mint crashes after +/// setup_melt() completes but before payment is sent, the proofs should be +/// restored on restart. +#[tokio::test] +async fn test_crash_recovery_setup_complete() { + // STEP 1: Setup test environment + let mint = create_test_mint().await.unwrap(); + + // STEP 2: Create test proofs (10,000 millisats = 10 sats) + let proofs = mint_test_proofs(&mint, Amount::from(10_000)).await.unwrap(); + let input_ys = proofs.ys().unwrap(); + + // STEP 3: Create melt quote (9,000 millisats = 9 sats) + let quote = create_test_melt_quote(&mint, Amount::from(9_000)).await; + + // STEP 4: Create melt request + let melt_request = create_test_melt_request(&proofs, "e); + + // STEP 5: Setup melt saga (this persists saga to DB) + let verification = mint.verify_inputs(melt_request.inputs()).await.unwrap(); + let saga = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let setup_saga = saga + .setup_melt(&melt_request, verification) + .await + .expect("Setup should succeed"); + + // STEP 6: Verify proofs are PENDING + assert_proofs_state(&mint, &input_ys, Some(State::Pending)).await; + + // STEP 7: Verify saga was persisted + let operation_id = *setup_saga.operation.id(); + assert_saga_exists(&mint, &operation_id).await; + + // STEP 8: Simulate crash - drop saga without finalizing + drop(setup_saga); + + // STEP 9: Run recovery (simulating mint restart) + mint.recover_from_incomplete_melt_sagas() + .await + .expect("Recovery should succeed"); + + // STEP 10: Verify proofs were REMOVED (restored to client) + assert_proofs_state(&mint, &input_ys, None).await; + + // STEP 11: Verify saga was deleted + assert_saga_not_exists(&mint, &operation_id).await; + + // STEP 12: Verify quote state reset to UNPAID + let recovered_quote = mint + .localstore + .get_melt_quote("e.id) + .await + .unwrap() + .expect("Quote should still exist"); + assert_eq!( + recovered_quote.state, + MeltQuoteState::Unpaid, + "Quote state should be reset to Unpaid after recovery" + ); + + // SUCCESS: Crash recovery works! +} + +/// Test: Multiple incomplete sagas can be recovered +/// +/// This test validates that the recovery mechanism can handle multiple +/// incomplete sagas in a single recovery pass, ensuring batch operations work. +#[tokio::test] +async fn test_crash_recovery_multiple_sagas() { + // STEP 1: Setup test environment + let mint = create_test_mint().await.unwrap(); + + // STEP 2: Create multiple incomplete melt sagas (5 sagas) + let mut operation_ids = Vec::new(); + let mut proof_ys_list = Vec::new(); + let mut quote_ids = Vec::new(); + + for i in 0..5 { + // Use smaller amounts to fit within FakeWallet limits + let proofs = mint_test_proofs(&mint, Amount::from(5_000 + i * 100)) + .await + .unwrap(); + let input_ys = proofs.ys().unwrap(); + let quote = create_test_melt_quote(&mint, Amount::from(4_000 + i * 100)).await; + let melt_request = create_test_melt_request(&proofs, "e); + + let verification = mint.verify_inputs(melt_request.inputs()).await.unwrap(); + let saga = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let setup_saga = saga.setup_melt(&melt_request, verification).await.unwrap(); + + operation_ids.push(*setup_saga.operation.id()); + proof_ys_list.push(input_ys); + quote_ids.push(quote.id.clone()); + + // Drop saga to simulate crash + drop(setup_saga); + } + + // STEP 3: Verify all sagas exist before recovery + let sagas_before = mint + .localstore + .get_incomplete_sagas(OperationKind::Melt) + .await + .unwrap(); + + assert_eq!( + sagas_before.len(), + 5, + "Should have 5 incomplete sagas before recovery" + ); + + // Verify all our operation IDs are present + for operation_id in &operation_ids { + assert!( + sagas_before.iter().any(|s| s.operation_id == *operation_id), + "Saga {} should exist before recovery", + operation_id + ); + } + + // Verify all proofs are PENDING + for input_ys in &proof_ys_list { + assert_proofs_state(&mint, input_ys, Some(State::Pending)).await; + } + + // STEP 4: Run recovery (should handle all sagas) + mint.recover_from_incomplete_melt_sagas() + .await + .expect("Recovery should succeed"); + + // STEP 5: Verify all sagas were recovered and cleaned up + let sagas_after = mint + .localstore + .get_incomplete_sagas(OperationKind::Melt) + .await + .unwrap(); + + assert!( + sagas_after.is_empty(), + "All sagas should be deleted after recovery" + ); + + // Verify none of our operation IDs exist + for operation_id in &operation_ids { + assert_saga_not_exists(&mint, operation_id).await; + } + + // STEP 6: Verify all proofs were removed (returned to client) + for input_ys in &proof_ys_list { + assert_proofs_state(&mint, input_ys, None).await; + } + + // STEP 7: Verify all quotes were reset to UNPAID + for quote_id in "e_ids { + let recovered_quote = mint + .localstore + .get_melt_quote(quote_id) + .await + .unwrap() + .expect("Quote should still exist"); + + assert_eq!( + recovered_quote.state, + MeltQuoteState::Unpaid, + "Quote {} should be reset to Unpaid", + quote_id + ); + } + + // SUCCESS: Multiple sagas recovered successfully! +} + +/// Test: Recovery handles sagas gracefully even when data relationships exist +/// +/// This test verifies that recovery works correctly in a standard crash scenario +/// where all data is intact (saga, quote, proofs all exist). +#[tokio::test] +async fn test_crash_recovery_orphaned_saga() { + // STEP 1: Setup test environment + let mint = create_test_mint().await.unwrap(); + let proofs = mint_test_proofs(&mint, Amount::from(10_000)).await.unwrap(); + let quote = create_test_melt_quote(&mint, Amount::from(9_000)).await; + let melt_request = create_test_melt_request(&proofs, "e); + + // STEP 2: Create incomplete saga + let verification = mint.verify_inputs(melt_request.inputs()).await.unwrap(); + let saga = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let setup_saga = saga.setup_melt(&melt_request, verification).await.unwrap(); + + let operation_id = *setup_saga.operation.id(); + let input_ys = proofs.ys().unwrap(); + + // Drop saga (simulate crash) + drop(setup_saga); + + // Verify saga exists + assert_saga_exists(&mint, &operation_id).await; + assert_proofs_state(&mint, &input_ys, Some(State::Pending)).await; + + // STEP 3: Run recovery + // Recovery should handle the saga gracefully, cleaning up all state + mint.recover_from_incomplete_melt_sagas() + .await + .expect("Recovery should succeed"); + + // STEP 4: Verify saga was cleaned up + assert_saga_not_exists(&mint, &operation_id).await; + assert_proofs_state(&mint, &input_ys, None).await; + + // Verify quote was reset + let recovered_quote = mint + .localstore + .get_melt_quote("e.id) + .await + .unwrap() + .unwrap(); + assert_eq!(recovered_quote.state, MeltQuoteState::Unpaid); + + // SUCCESS: Recovery works correctly! +} + +/// Test: Recovery continues even if one saga fails +#[tokio::test] +async fn test_crash_recovery_partial_failure() { + // TODO: Implement this test + // 1. Create multiple incomplete sagas + // 2. Make one saga fail (e.g., corrupted data) + // 3. Run recovery + // 4. Verify other sagas were still recovered + // 5. Verify failed saga is logged but doesn't stop recovery +} + +// ============================================================================ +// Startup Integration Tests +// ============================================================================ + +/// Test: Startup recovery is called on mint.start() +#[tokio::test] +async fn test_startup_recovery_integration() { + // STEP 1: Setup test environment + let mint = create_test_mint().await.unwrap(); + + // STEP 2: Create incomplete saga + let proofs = mint_test_proofs(&mint, Amount::from(10_000)).await.unwrap(); + let quote = create_test_melt_quote(&mint, Amount::from(9_000)).await; + let melt_request = create_test_melt_request(&proofs, "e); + + let verification = mint.verify_inputs(melt_request.inputs()).await.unwrap(); + let saga = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let setup_saga = saga.setup_melt(&melt_request, verification).await.unwrap(); + + let operation_id = *setup_saga.operation.id(); + let input_ys = proofs.ys().unwrap(); + + // Drop saga (simulate crash) + drop(setup_saga); + + // Verify saga exists after setup + assert_saga_exists(&mint, &operation_id).await; + assert_proofs_state(&mint, &input_ys, Some(State::Pending)).await; + + // STEP 3: Manually trigger recovery (simulating restart behavior) + // Note: create_test_mint() already calls mint.start(), so recovery should + // have run on startup. However, since we created the saga AFTER startup, + // we need to manually trigger recovery to simulate a restart scenario. + mint.recover_from_incomplete_melt_sagas() + .await + .expect("Recovery should succeed"); + + // STEP 4: Verify recovery was executed + assert_saga_not_exists(&mint, &operation_id).await; + assert_proofs_state(&mint, &input_ys, None).await; + + // STEP 5: Verify mint is running normally + // (Can perform new melt operations) + let new_proofs = mint_test_proofs(&mint, Amount::from(5_000)).await.unwrap(); + let new_quote = create_test_melt_quote(&mint, Amount::from(4_000)).await; + let new_request = create_test_melt_request(&new_proofs, &new_quote); + + let new_verification = mint.verify_inputs(new_request.inputs()).await.unwrap(); + let new_saga = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let _new_setup = new_saga + .setup_melt(&new_request, new_verification) + .await + .unwrap(); + + // SUCCESS: Recovery runs on startup and mint works normally! +} + +/// Test: Startup never fails due to recovery errors +#[tokio::test] +async fn test_startup_resilient_to_recovery_errors() { + // TODO: Implement this test + // 1. Create corrupted saga data + // 2. Call mint.start() + // 3. Verify start() completes successfully + // 4. Verify error was logged +} + +// ============================================================================ +// Compensation Tests +// ============================================================================ + +/// Test: Compensation removes proofs from database +/// +/// This test validates that when compensation runs (during crash recovery), +/// the proofs are properly removed from the database and returned to the client. +#[tokio::test] +async fn test_compensation_removes_proofs() { + // STEP 1: Setup test environment + let mint = create_test_mint().await.unwrap(); + let proofs = mint_test_proofs(&mint, Amount::from(10_000)).await.unwrap(); + let input_ys = proofs.ys().unwrap(); + let quote = create_test_melt_quote(&mint, Amount::from(9_000)).await; + let melt_request = create_test_melt_request(&proofs, "e); + + // STEP 2: Setup melt saga (this marks proofs as PENDING) + let verification = mint.verify_inputs(melt_request.inputs()).await.unwrap(); + let saga = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let setup_saga = saga.setup_melt(&melt_request, verification).await.unwrap(); + + let operation_id = *setup_saga.operation.id(); + + // Verify proofs are PENDING + assert_proofs_state(&mint, &input_ys, Some(State::Pending)).await; + + // STEP 3: Simulate crash and trigger compensation via recovery + drop(setup_saga); + + // Run recovery which triggers compensation + mint.recover_from_incomplete_melt_sagas() + .await + .expect("Recovery should succeed"); + + // STEP 4: Verify proofs were removed from database (returned to client) + assert_proofs_state(&mint, &input_ys, None).await; + + // STEP 5: Verify saga was cleaned up + assert_saga_not_exists(&mint, &operation_id).await; + + // STEP 6: Verify proofs can be used again in a new melt operation + let new_quote = create_test_melt_quote(&mint, Amount::from(9_000)).await; + let new_request = create_test_melt_request(&proofs, &new_quote); + + let new_verification = mint.verify_inputs(new_request.inputs()).await.unwrap(); + let new_saga = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let new_setup = new_saga + .setup_melt(&new_request, new_verification) + .await + .expect("Should be able to reuse proofs after compensation"); + + // Verify new saga was created successfully + assert_saga_exists(&mint, new_setup.operation.id()).await; + + // SUCCESS: Compensation properly removed proofs and they can be reused! +} + +/// Test: Compensation removes change outputs +/// +/// This test validates that compensation properly removes blinded messages +/// (change outputs) from the database during rollback. +#[tokio::test] +async fn test_compensation_removes_change_outputs() { + use cdk_common::nuts::MeltRequest; + + use crate::test_helpers::mint::create_test_blinded_messages; + + // STEP 1: Setup test environment + let mint = create_test_mint().await.unwrap(); + + // Create input proofs (more than needed so we have change) + let proofs = mint_test_proofs(&mint, Amount::from(10_000)).await.unwrap(); + let quote = create_test_melt_quote(&mint, Amount::from(7_000)).await; + + // STEP 2: Create change outputs (blinded messages) + // Change = 10,000 - 7,000 - fee = ~3,000 sats + let (blinded_messages, _premint) = create_test_blinded_messages(&mint, Amount::from(3_000)) + .await + .unwrap(); + + let blinded_secrets: Vec<_> = blinded_messages + .iter() + .map(|bm| bm.blinded_secret) + .collect(); + + // STEP 3: Create melt request with change outputs + let melt_request = MeltRequest::new(quote.id.clone(), proofs.clone(), Some(blinded_messages)); + + // STEP 4: Setup melt saga (this stores blinded messages) + let verification = mint.verify_inputs(melt_request.inputs()).await.unwrap(); + let saga = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let setup_saga = saga.setup_melt(&melt_request, verification).await.unwrap(); + + let operation_id = *setup_saga.operation.id(); + + // STEP 5: Verify blinded messages are stored in database + let stored_info = { + let mut tx = mint.localstore.begin_transaction().await.unwrap(); + let info = tx + .get_melt_request_and_blinded_messages("e.id) + .await + .expect("Should be able to query melt request") + .expect("Melt request should exist"); + tx.rollback().await.unwrap(); + info + }; + + assert_eq!( + stored_info.change_outputs.len(), + blinded_secrets.len(), + "All blinded messages should be stored" + ); + + // STEP 6: Simulate crash and trigger compensation + drop(setup_saga); + + mint.recover_from_incomplete_melt_sagas() + .await + .expect("Recovery should succeed"); + + // STEP 7: Verify blinded messages were removed + let result = { + let mut tx = mint.localstore.begin_transaction().await.unwrap(); + let res = tx + .get_melt_request_and_blinded_messages("e.id) + .await + .expect("Query should succeed"); + tx.rollback().await.unwrap(); + res + }; + + assert!( + result.is_none(), + "Melt request and blinded messages should be deleted after compensation" + ); + + // STEP 8: Verify saga was cleaned up + assert_saga_not_exists(&mint, &operation_id).await; + + // SUCCESS: Compensation properly removed change outputs! +} + +/// Test: Compensation resets quote state +/// +/// This test validates that compensation properly resets the quote state +/// from PENDING back to UNPAID, allowing the quote to be used again. +#[tokio::test] +async fn test_compensation_resets_quote_state() { + // STEP 1: Setup test environment + let mint = create_test_mint().await.unwrap(); + let proofs = mint_test_proofs(&mint, Amount::from(10_000)).await.unwrap(); + let quote = create_test_melt_quote(&mint, Amount::from(9_000)).await; + + // Verify initial quote state is UNPAID + assert_eq!( + quote.state, + MeltQuoteState::Unpaid, + "Quote should start as Unpaid" + ); + + let melt_request = create_test_melt_request(&proofs, "e); + + // STEP 2: Setup melt saga (this changes quote state to PENDING) + let verification = mint.verify_inputs(melt_request.inputs()).await.unwrap(); + let saga = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let setup_saga = saga.setup_melt(&melt_request, verification).await.unwrap(); + + let operation_id = *setup_saga.operation.id(); + + // STEP 3: Verify quote state became PENDING + let pending_quote = mint + .localstore + .get_melt_quote("e.id) + .await + .unwrap() + .expect("Quote should exist"); + + assert_eq!( + pending_quote.state, + MeltQuoteState::Pending, + "Quote state should be Pending after setup" + ); + + // STEP 4: Simulate crash and trigger compensation + drop(setup_saga); + + mint.recover_from_incomplete_melt_sagas() + .await + .expect("Recovery should succeed"); + + // STEP 5: Verify quote state was reset to UNPAID + let recovered_quote = mint + .localstore + .get_melt_quote("e.id) + .await + .unwrap() + .expect("Quote should still exist after compensation"); + + assert_eq!( + recovered_quote.state, + MeltQuoteState::Unpaid, + "Quote state should be reset to Unpaid after compensation" + ); + + // STEP 6: Verify saga was cleaned up + assert_saga_not_exists(&mint, &operation_id).await; + + // STEP 7: Verify quote can be used again with new melt request + let new_proofs = mint_test_proofs(&mint, Amount::from(10_000)).await.unwrap(); + let new_request = create_test_melt_request(&new_proofs, &recovered_quote); + + let new_verification = mint.verify_inputs(new_request.inputs()).await.unwrap(); + let new_saga = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let _new_setup = new_saga + .setup_melt(&new_request, new_verification) + .await + .expect("Should be able to reuse quote after compensation"); + + // SUCCESS: Quote state properly reset and can be reused! +} + +/// Test: Compensation is idempotent +/// +/// This test validates that running compensation multiple times is safe +/// and produces consistent results. This is important because recovery +/// might be called multiple times during debugging or startup. +#[tokio::test] +async fn test_compensation_idempotent() { + // STEP 1: Setup test environment + let mint = create_test_mint().await.unwrap(); + let proofs = mint_test_proofs(&mint, Amount::from(10_000)).await.unwrap(); + let input_ys = proofs.ys().unwrap(); + let quote = create_test_melt_quote(&mint, Amount::from(9_000)).await; + let melt_request = create_test_melt_request(&proofs, "e); + + // STEP 2: Setup melt saga + let verification = mint.verify_inputs(melt_request.inputs()).await.unwrap(); + let saga = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let setup_saga = saga.setup_melt(&melt_request, verification).await.unwrap(); + + let operation_id = *setup_saga.operation.id(); + + // Verify initial state + assert_proofs_state(&mint, &input_ys, Some(State::Pending)).await; + assert_saga_exists(&mint, &operation_id).await; + + // STEP 3: Simulate crash + drop(setup_saga); + + // STEP 4: Run compensation first time + mint.recover_from_incomplete_melt_sagas() + .await + .expect("First recovery should succeed"); + + // Verify state after first compensation + assert_proofs_state(&mint, &input_ys, None).await; + assert_saga_not_exists(&mint, &operation_id).await; + + let quote_after_first = mint + .localstore + .get_melt_quote("e.id) + .await + .unwrap() + .expect("Quote should exist"); + assert_eq!(quote_after_first.state, MeltQuoteState::Unpaid); + + // STEP 5: Run compensation second time (should be idempotent) + mint.recover_from_incomplete_melt_sagas() + .await + .expect("Second recovery should succeed without errors"); + + // STEP 6: Verify state is unchanged after second compensation + assert_proofs_state(&mint, &input_ys, None).await; + assert_saga_not_exists(&mint, &operation_id).await; + + let quote_after_second = mint + .localstore + .get_melt_quote("e.id) + .await + .unwrap() + .expect("Quote should still exist"); + assert_eq!(quote_after_second.state, MeltQuoteState::Unpaid); + + // STEP 7: Verify both results are identical + assert_eq!( + quote_after_first.state, quote_after_second.state, + "Quote state should be identical after multiple compensations" + ); + + // STEP 8: Run third time to be extra sure + mint.recover_from_incomplete_melt_sagas() + .await + .expect("Third recovery should also succeed"); + + // SUCCESS: Compensation is idempotent and safe to run multiple times! +} + +// ============================================================================ +// Saga Content Validation Tests +// ============================================================================ + +/// Test: Persisted saga contains correct data +/// +/// This test validates that all saga fields are persisted correctly, +/// providing comprehensive validation beyond the basic persistence test. +#[tokio::test] +async fn test_saga_content_validation() { + // STEP 1: Setup test environment with known data + let mint = create_test_mint().await.unwrap(); + + // Create proofs with specific amount + let proof_amount = Amount::from(10_000); + let proofs = mint_test_proofs(&mint, proof_amount).await.unwrap(); + let input_ys = proofs.ys().unwrap(); + + // Create quote with specific amount + let quote_amount = Amount::from(9_000); + let quote = create_test_melt_quote(&mint, quote_amount).await; + + // Create melt request + let melt_request = create_test_melt_request(&proofs, "e); + + // STEP 2: Setup melt saga + let verification = mint.verify_inputs(melt_request.inputs()).await.unwrap(); + let saga = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let setup_saga = saga.setup_melt(&melt_request, verification).await.unwrap(); + + let operation_id = *setup_saga.operation.id(); + + // STEP 3: Retrieve saga from database + let persisted_saga = assert_saga_exists(&mint, &operation_id).await; + + // STEP 4: Verify operation_id matches exactly + assert_eq!( + persisted_saga.operation_id, operation_id, + "Operation ID should match exactly" + ); + + // STEP 5: Verify operation_kind is Melt + assert_eq!( + persisted_saga.operation_kind, + OperationKind::Melt, + "Operation kind must be Melt" + ); + + // STEP 6: Verify state is SetupComplete + match &persisted_saga.state { + cdk_common::mint::SagaStateEnum::Melt(state) => { + assert_eq!( + *state, + MeltSagaState::SetupComplete, + "State should be SetupComplete after setup" + ); + } + _ => panic!("Expected Melt saga state, got {:?}", persisted_saga.state), + } + + // STEP 7: Verify input_ys are stored correctly + assert_eq!( + persisted_saga.input_ys.len(), + input_ys.len(), + "Should store all input Ys" + ); + + // Verify each Y is present and in correct order + for (i, expected_y) in input_ys.iter().enumerate() { + assert!( + persisted_saga.input_ys.contains(expected_y), + "Input Y at index {} should be stored: {:?}", + i, + expected_y + ); + } + + // STEP 8: Verify timestamps are set and reasonable + let current_timestamp = std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .unwrap() + .as_secs(); + + assert!( + persisted_saga.created_at > 0, + "Created timestamp should be set" + ); + assert!( + persisted_saga.updated_at > 0, + "Updated timestamp should be set" + ); + + // Timestamps should be recent (within last hour) + assert!( + persisted_saga.created_at <= current_timestamp, + "Created timestamp should not be in the future" + ); + assert!( + persisted_saga.created_at > current_timestamp - 3600, + "Created timestamp should be recent (within last hour)" + ); + + // For new saga, created_at and updated_at should match + assert_eq!( + persisted_saga.created_at, persisted_saga.updated_at, + "Timestamps should match for newly created saga" + ); + + // STEP 9: Verify blinded_secrets is empty (not used for melt) + assert!( + persisted_saga.blinded_secrets.is_empty(), + "Melt saga should not use blinded_secrets field" + ); + + // SUCCESS: All saga content validated! +} + +/// Test: Saga timestamps remain consistent across retrievals +/// +/// Note: The melt saga doesn't have intermediate state updates that persist +/// to the database. It's created in SetupComplete state and then deleted on +/// finalize. This test validates that timestamps remain consistent when +/// retrieving the saga multiple times from the database. +#[tokio::test] +async fn test_saga_state_updates_timestamp() { + // STEP 1: Setup test environment + let mint = create_test_mint().await.unwrap(); + let proofs = mint_test_proofs(&mint, Amount::from(10_000)).await.unwrap(); + let quote = create_test_melt_quote(&mint, Amount::from(9_000)).await; + let melt_request = create_test_melt_request(&proofs, "e); + + // STEP 2: Setup melt saga and note timestamps + let verification = mint.verify_inputs(melt_request.inputs()).await.unwrap(); + let saga = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let setup_saga = saga.setup_melt(&melt_request, verification).await.unwrap(); + + let operation_id = *setup_saga.operation.id(); + + // STEP 3: Retrieve saga and note timestamps + let saga1 = assert_saga_exists(&mint, &operation_id).await; + let created_at_1 = saga1.created_at; + let updated_at_1 = saga1.updated_at; + + // STEP 4: Wait a brief moment + tokio::time::sleep(tokio::time::Duration::from_millis(10)).await; + + // STEP 5: Retrieve saga again + let saga2 = assert_saga_exists(&mint, &operation_id).await; + let created_at_2 = saga2.created_at; + let updated_at_2 = saga2.updated_at; + + // STEP 6: Verify timestamps remain unchanged across retrievals + assert_eq!( + created_at_1, created_at_2, + "Created timestamp should not change across retrievals" + ); + assert_eq!( + updated_at_1, updated_at_2, + "Updated timestamp should not change across retrievals" + ); + + // STEP 7: Verify timestamps are identical for new saga + assert_eq!( + created_at_1, updated_at_1, + "New saga should have matching created_at and updated_at" + ); + + // SUCCESS: Timestamps are consistent! +} + +// ============================================================================ +// Query Tests +// ============================================================================ + +/// Test: get_incomplete_sagas returns only melt sagas +/// +/// This test validates that the database query correctly filters sagas +/// by operation kind, only returning melt sagas when requested. +#[tokio::test] +async fn test_get_incomplete_sagas_filters_by_kind() { + use crate::mint::swap::swap_saga::SwapSaga; + use crate::test_helpers::mint::create_test_blinded_messages; + + // STEP 1: Setup test environment + let mint = create_test_mint().await.unwrap(); + + // STEP 2: Create a melt saga + let melt_proofs = mint_test_proofs(&mint, Amount::from(10_000)).await.unwrap(); + let melt_quote = create_test_melt_quote(&mint, Amount::from(9_000)).await; + let melt_request = create_test_melt_request(&melt_proofs, &melt_quote); + + let melt_verification = mint.verify_inputs(melt_request.inputs()).await.unwrap(); + let melt_saga = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let melt_setup = melt_saga + .setup_melt(&melt_request, melt_verification) + .await + .unwrap(); + + let melt_operation_id = *melt_setup.operation.id(); + + // STEP 3: Create a swap saga + let swap_proofs = mint_test_proofs(&mint, Amount::from(5_000)).await.unwrap(); + let swap_verification = crate::mint::Verification { + amount: Amount::from(5_000), + unit: Some(cdk_common::nuts::CurrencyUnit::Sat), + }; + + let (swap_outputs, _) = create_test_blinded_messages(&mint, Amount::from(5_000)) + .await + .unwrap(); + + let swap_saga = SwapSaga::new(&mint, mint.localstore(), mint.pubsub_manager()); + let _swap_setup = swap_saga + .setup_swap(&swap_proofs, &swap_outputs, None, swap_verification) + .await + .unwrap(); + + // STEP 4: Query for incomplete melt sagas + let melt_sagas = mint + .localstore + .get_incomplete_sagas(OperationKind::Melt) + .await + .unwrap(); + + // STEP 5: Verify only melt saga is returned + assert_eq!(melt_sagas.len(), 1, "Should return exactly one melt saga"); + + assert_eq!( + melt_sagas[0].operation_id, melt_operation_id, + "Returned saga should be the melt saga" + ); + + assert_eq!( + melt_sagas[0].operation_kind, + OperationKind::Melt, + "Returned saga should have Melt kind" + ); + + // STEP 6: Query for incomplete swap sagas + let swap_sagas = mint + .localstore + .get_incomplete_sagas(OperationKind::Swap) + .await + .unwrap(); + + // STEP 7: Verify only swap saga is returned + assert_eq!(swap_sagas.len(), 1, "Should return exactly one swap saga"); + + assert_eq!( + swap_sagas[0].operation_kind, + OperationKind::Swap, + "Returned saga should have Swap kind" + ); + + // SUCCESS: Query correctly filters by operation kind! +} + +/// Test: get_incomplete_sagas returns empty when none exist +#[tokio::test] +async fn test_get_incomplete_sagas_empty() { + let mint = create_test_mint().await.unwrap(); + + let sagas = mint + .localstore + .get_incomplete_sagas(OperationKind::Melt) + .await + .unwrap(); + + assert!(sagas.is_empty(), "Should have no incomplete melt sagas"); +} + +// ============================================================================ +// Concurrent Operation Tests +// ============================================================================ + +/// Test: Multiple concurrent melt operations don't interfere +#[tokio::test] +async fn test_concurrent_melt_operations() { + // STEP 1: Setup test environment + let mint = create_test_mint().await.unwrap(); + + // STEP 2: Create 5 sets of proofs and quotes concurrently + // Using same amount for each to avoid FakeWallet limit issues + let mut tasks = Vec::new(); + + for _ in 0..5 { + let mint_clone = mint.clone(); + let task = tokio::spawn(async move { + let proofs = mint_test_proofs(&mint_clone, Amount::from(10_000)) + .await + .unwrap(); + let quote = create_test_melt_quote(&mint_clone, Amount::from(9_000)).await; + (proofs, quote) + }); + tasks.push(task); + } + + let proof_quote_pairs: Vec<_> = futures::future::join_all(tasks) + .await + .into_iter() + .map(|r| r.unwrap()) + .collect(); + + // STEP 3: Setup all melt sagas concurrently + let mut setup_tasks = Vec::new(); + + for (proofs, quote) in proof_quote_pairs { + let mint_clone = mint.clone(); + let task = tokio::spawn(async move { + let melt_request = create_test_melt_request(&proofs, "e); + let verification = mint_clone + .verify_inputs(melt_request.inputs()) + .await + .unwrap(); + let saga = MeltSaga::new( + std::sync::Arc::new(mint_clone.clone()), + mint_clone.localstore(), + mint_clone.pubsub_manager(), + ); + let setup_saga = saga.setup_melt(&melt_request, verification).await.unwrap(); + let operation_id = *setup_saga.operation.id(); + // Drop setup_saga before returning to avoid lifetime issues + drop(setup_saga); + operation_id + }); + setup_tasks.push(task); + } + + let operation_ids: Vec<_> = futures::future::join_all(setup_tasks) + .await + .into_iter() + .map(|r| r.unwrap()) + .collect(); + + // STEP 4: Verify all operation_ids are unique + let unique_ids: std::collections::HashSet<_> = operation_ids.iter().collect(); + assert_eq!( + unique_ids.len(), + operation_ids.len(), + "All operation IDs should be unique" + ); + + // STEP 5: Verify all sagas exist in database + let sagas = mint + .localstore + .get_incomplete_sagas(OperationKind::Melt) + .await + .unwrap(); + assert!(sagas.len() >= 5, "Should have at least 5 incomplete sagas"); + + for operation_id in &operation_ids { + assert!( + sagas.iter().any(|s| s.operation_id == *operation_id), + "Saga {} should exist in database", + operation_id + ); + } + + // SUCCESS: Concurrent operations work without interference! +} + +/// Test: Concurrent recovery and new operations work together +#[tokio::test] +async fn test_concurrent_recovery_and_operations() { + // STEP 1: Setup test environment + let mint = create_test_mint().await.unwrap(); + + // STEP 2: Create incomplete saga + let proofs1 = mint_test_proofs(&mint, Amount::from(10_000)).await.unwrap(); + let quote1 = create_test_melt_quote(&mint, Amount::from(9_000)).await; + let melt_request1 = create_test_melt_request(&proofs1, "e1); + + let verification1 = mint.verify_inputs(melt_request1.inputs()).await.unwrap(); + let saga1 = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let setup_saga1 = saga1 + .setup_melt(&melt_request1, verification1) + .await + .unwrap(); + let incomplete_operation_id = *setup_saga1.operation.id(); + + // Drop saga to simulate crash + drop(setup_saga1); + + // Verify saga exists + assert_saga_exists(&mint, &incomplete_operation_id).await; + + // STEP 3: Create tasks for concurrent recovery and new operation + let mint_for_recovery = mint.clone(); + let recovery_task = tokio::spawn(async move { + mint_for_recovery + .recover_from_incomplete_melt_sagas() + .await + .expect("Recovery should succeed") + }); + + let mint_for_new_op = mint.clone(); + let new_operation_task = tokio::spawn(async move { + let proofs2 = mint_test_proofs(&mint_for_new_op, Amount::from(10_000)) + .await + .unwrap(); + let quote2 = create_test_melt_quote(&mint_for_new_op, Amount::from(9_000)).await; + let melt_request2 = create_test_melt_request(&proofs2, "e2); + + let verification2 = mint_for_new_op + .verify_inputs(melt_request2.inputs()) + .await + .unwrap(); + let saga2 = MeltSaga::new( + std::sync::Arc::new(mint_for_new_op.clone()), + mint_for_new_op.localstore(), + mint_for_new_op.pubsub_manager(), + ); + let setup_saga2 = saga2 + .setup_melt(&melt_request2, verification2) + .await + .unwrap(); + *setup_saga2.operation.id() + }); + + // STEP 4: Wait for both tasks to complete + let (recovery_result, new_op_result) = tokio::join!(recovery_task, new_operation_task); + + recovery_result.expect("Recovery task should complete"); + let new_operation_id = new_op_result.expect("New operation task should complete"); + + // STEP 5: Verify recovery completed + assert_saga_not_exists(&mint, &incomplete_operation_id).await; + + // STEP 6: Verify new operation succeeded + assert_saga_exists(&mint, &new_operation_id).await; + + // SUCCESS: Concurrent recovery and operations work together! +} + +// ============================================================================ +// Failure Scenario Tests +// ============================================================================ + +/// Test: Double-spend detection during setup +#[tokio::test] +async fn test_double_spend_detection() { + // STEP 1: Setup test environment + let mint = create_test_mint().await.unwrap(); + let proofs = mint_test_proofs(&mint, Amount::from(10_000)).await.unwrap(); + + // STEP 2: Setup first melt saga with proofs + let quote1 = create_test_melt_quote(&mint, Amount::from(9_000)).await; + let melt_request1 = create_test_melt_request(&proofs, "e1); + + let verification1 = mint.verify_inputs(melt_request1.inputs()).await.unwrap(); + let saga1 = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let _setup_saga1 = saga1 + .setup_melt(&melt_request1, verification1) + .await + .unwrap(); + + // Proofs should now be in PENDING state + let input_ys = proofs.ys().unwrap(); + assert_proofs_state(&mint, &input_ys, Some(State::Pending)).await; + + // STEP 3: Try to setup second saga with same proofs + let quote2 = create_test_melt_quote(&mint, Amount::from(8_000)).await; + let melt_request2 = create_test_melt_request(&proofs, "e2); + + // STEP 4: verify_inputs succeeds (only checks signatures) + // but setup_melt should fail (checks proof states) + let verification2 = mint.verify_inputs(melt_request2.inputs()).await.unwrap(); + let saga2 = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let setup_result2 = saga2.setup_melt(&melt_request2, verification2).await; + + // STEP 5: Verify second setup fails with appropriate error + assert!( + setup_result2.is_err(), + "Second melt with same proofs should fail during setup" + ); + + if let Err(error) = setup_result2 { + let error_msg = error.to_string().to_lowercase(); + assert!( + error_msg.contains("pending") + || error_msg.contains("spent") + || error_msg.contains("state"), + "Error should mention proof state issue, got: {}", + error + ); + } + + // STEP 6: Verify first saga is unaffected - proofs still pending + assert_proofs_state(&mint, &input_ys, Some(State::Pending)).await; + + // SUCCESS: Double-spend prevented! +} + +/// Test: Transaction balance validation +/// +/// Note: This test verifies that the mint properly validates transaction balance. +/// In the current implementation, balance checking happens during melt request +/// validation before saga setup. +#[tokio::test] +async fn test_insufficient_funds() { + // STEP 1: Setup test environment + let mint = create_test_mint().await.unwrap(); + + // STEP 2: Create proofs + let proofs = mint_test_proofs(&mint, Amount::from(10_000)).await.unwrap(); + let input_ys = proofs.ys().unwrap(); + + // STEP 3: Create quote + let quote = create_test_melt_quote(&mint, Amount::from(9_000)).await; + + // STEP 4: Setup a normal melt (this should succeed with sufficient funds) + let melt_request = create_test_melt_request(&proofs, "e); + let verification = mint.verify_inputs(melt_request.inputs()).await.unwrap(); + let saga = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let setup_result = saga.setup_melt(&melt_request, verification).await; + + // With 10000 msats input and 9000 msats quote, this should succeed + assert!( + setup_result.is_ok(), + "Setup should succeed with sufficient funds" + ); + + // Clean up + drop(setup_result); + + // Verify proofs are now marked pending (setup succeeded) + assert_proofs_state(&mint, &input_ys, Some(State::Pending)).await; + + // SUCCESS: Balance validation works correctly! + // Note: Testing actual insufficient funds would require creating a quote + // that costs more than the proofs, but that's prevented at quote creation time +} + +/// Test: Invalid quote ID rejection +#[tokio::test] +async fn test_invalid_quote_id() { + // STEP 1: Setup test environment + let mint = create_test_mint().await.unwrap(); + let proofs = mint_test_proofs(&mint, Amount::from(10_000)).await.unwrap(); + + // STEP 2: Create a melt request with non-existent quote ID + use cdk_common::nuts::MeltRequest; + use cdk_common::QuoteId; + + let fake_quote_id = QuoteId::new_uuid(); + let melt_request = MeltRequest::new(fake_quote_id.clone(), proofs.clone(), None); + + // STEP 3: Try to setup melt saga (should fail due to invalid quote) + let verification_result = mint.verify_inputs(melt_request.inputs()).await; + + // Verification might succeed (just checks signatures) or fail (if database issues) + if let Ok(verification) = verification_result { + let saga = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let setup_result = saga.setup_melt(&melt_request, verification).await; + + // STEP 4: Verify setup fails with unknown quote error + assert!( + setup_result.is_err(), + "Setup should fail with invalid quote ID" + ); + + if let Err(error) = setup_result { + let error_msg = error.to_string().to_lowercase(); + assert!( + error_msg.contains("quote") + || error_msg.contains("unknown") + || error_msg.contains("not found"), + "Error should mention quote issue, got: {}", + error + ); + } + + // Note: We don't query database state after a failed setup because + // the database may be in a transaction rollback state which can cause timeouts + } else { + // If verification fails due to database issues, that's also acceptable + // for this test (we're mainly testing quote validation) + eprintln!("Note: Verification failed (expected in some environments)"); + } + + // SUCCESS: Invalid quote ID handling works correctly! +} + +/// Test: Quote already paid rejection +#[tokio::test] +async fn test_quote_already_paid() { + // STEP 1: Setup test environment + let mint = create_test_mint().await.unwrap(); + + // STEP 2: Create and complete a full melt operation + let proofs1 = mint_test_proofs(&mint, Amount::from(10_000)).await.unwrap(); + let quote = create_test_melt_quote(&mint, Amount::from(9_000)).await; + let melt_request1 = create_test_melt_request(&proofs1, "e); + + // Complete the full melt flow + let verification1 = mint.verify_inputs(melt_request1.inputs()).await.unwrap(); + let saga1 = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let setup_saga1 = saga1 + .setup_melt(&melt_request1, verification1) + .await + .unwrap(); + + let (payment_saga, decision) = setup_saga1 + .attempt_internal_settlement(&melt_request1) + .await + .unwrap(); + + let confirmed_saga = payment_saga.make_payment(decision).await.unwrap(); + let _response = confirmed_saga.finalize().await.unwrap(); + + // Verify quote is now paid + let paid_quote = mint + .localstore + .get_melt_quote("e.id) + .await + .unwrap() + .unwrap(); + assert_eq!( + paid_quote.state, + MeltQuoteState::Paid, + "Quote should be paid" + ); + + // STEP 3: Try to setup new melt saga with the already-paid quote + let proofs2 = mint_test_proofs(&mint, Amount::from(10_000)).await.unwrap(); + let melt_request2 = create_test_melt_request(&proofs2, &paid_quote); + + let verification2 = mint.verify_inputs(melt_request2.inputs()).await.unwrap(); + let saga2 = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let setup_result2 = saga2.setup_melt(&melt_request2, verification2).await; + + // STEP 4: Verify setup fails + assert!( + setup_result2.is_err(), + "Setup should fail with already paid quote" + ); + + if let Err(error) = setup_result2 { + let error_msg = error.to_string().to_lowercase(); + assert!( + error_msg.contains("paid") + || error_msg.contains("quote") + || error_msg.contains("state"), + "Error should mention paid quote, got: {}", + error + ); + } + + // SUCCESS: Already paid quote rejected! +} + +/// Test: Quote already pending rejection +#[tokio::test] +async fn test_quote_already_pending() { + // STEP 1: Setup test environment + let mint = create_test_mint().await.unwrap(); + + // STEP 2: Setup first melt saga (this puts quote in PENDING state) + let proofs1 = mint_test_proofs(&mint, Amount::from(10_000)).await.unwrap(); + let quote = create_test_melt_quote(&mint, Amount::from(9_000)).await; + let melt_request1 = create_test_melt_request(&proofs1, "e); + + let verification1 = mint.verify_inputs(melt_request1.inputs()).await.unwrap(); + let saga1 = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let _setup_saga1 = saga1 + .setup_melt(&melt_request1, verification1) + .await + .unwrap(); + + // Verify quote is now pending + let pending_quote = mint + .localstore + .get_melt_quote("e.id) + .await + .unwrap() + .unwrap(); + assert_eq!( + pending_quote.state, + MeltQuoteState::Pending, + "Quote should be pending" + ); + + // STEP 3: Try to setup second saga with same quote (different proofs) + let proofs2 = mint_test_proofs(&mint, Amount::from(10_000)).await.unwrap(); + let melt_request2 = create_test_melt_request(&proofs2, &pending_quote); + + let verification2 = mint.verify_inputs(melt_request2.inputs()).await.unwrap(); + let saga2 = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let setup_result2 = saga2.setup_melt(&melt_request2, verification2).await; + + // STEP 4: Verify second setup fails + assert!( + setup_result2.is_err(), + "Setup should fail with pending quote" + ); + + if let Err(error) = setup_result2 { + let error_msg = error.to_string().to_lowercase(); + assert!( + error_msg.contains("pending") + || error_msg.contains("quote") + || error_msg.contains("state"), + "Error should mention pending quote, got: {}", + error + ); + } + + // SUCCESS: Concurrent quote use prevented! +} + +// ============================================================================ +// Edge Cases +// ============================================================================ + +/// Test: Empty input proofs +#[tokio::test] +async fn test_empty_inputs() { + // STEP 1: Setup test environment + let mint = create_test_mint().await.unwrap(); + + // STEP 2: Create a melt request with empty proofs + use cdk_common::nuts::{MeltRequest, Proofs}; + + let quote = create_test_melt_quote(&mint, Amount::from(9_000)).await; + let empty_proofs = Proofs::new(); + + let melt_request = MeltRequest::new(quote.id.clone(), empty_proofs, None); + + // STEP 3: Try to verify inputs (should fail with empty proofs) + let verification_result = mint.verify_inputs(melt_request.inputs()).await; + + // Verification should fail with empty inputs + assert!( + verification_result.is_err(), + "Verification should fail with empty proofs" + ); + + let error = verification_result.unwrap_err(); + let error_msg = error.to_string().to_lowercase(); + assert!( + error_msg.contains("empty") || error_msg.contains("no") || error_msg.contains("input"), + "Error should mention empty inputs, got: {}", + error + ); + + // STEP 4: Verify no saga persisted + let sagas = mint + .localstore + .get_incomplete_sagas(OperationKind::Melt) + .await + .unwrap(); + assert!(sagas.is_empty(), "No saga should be persisted"); + + // SUCCESS: Empty inputs rejected! +} + +/// Test: Recovery with empty input_ys in saga +#[tokio::test] +async fn test_recovery_empty_input_ys() { + // TODO: Implement this test + // 1. Manually create saga with empty input_ys + // 2. Run recovery + // 3. Verify saga is skipped gracefully + // 4. Verify logged warning +} + +/// Test: Saga with no change outputs (simple melt scenario) +/// +/// This test verifies that recovery works correctly when there are no +/// change outputs to clean up (e.g., when input amount exactly matches quote amount) +#[tokio::test] +async fn test_recovery_no_melt_request() { + // STEP 1: Setup test environment + let mint = create_test_mint().await.unwrap(); + + // Create proofs that exactly match the quote amount (no change needed) + let amount = Amount::from(10_000); + let proofs = mint_test_proofs(&mint, amount).await.unwrap(); + let quote = create_test_melt_quote(&mint, amount).await; + + // Create melt request without change outputs + let melt_request = create_test_melt_request(&proofs, "e); + assert!( + melt_request.outputs().is_none(), + "Should have no change outputs" + ); + + // STEP 2: Create incomplete saga + let verification = mint.verify_inputs(melt_request.inputs()).await.unwrap(); + let saga = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let setup_saga = saga.setup_melt(&melt_request, verification).await.unwrap(); + + let operation_id = *setup_saga.operation.id(); + let input_ys = proofs.ys().unwrap(); + + // Drop saga (simulate crash) + drop(setup_saga); + + // Verify saga exists + assert_saga_exists(&mint, &operation_id).await; + assert_proofs_state(&mint, &input_ys, Some(State::Pending)).await; + + // STEP 3: Run recovery + // Should handle gracefully even with no change outputs to clean up + mint.recover_from_incomplete_melt_sagas() + .await + .expect("Recovery should succeed without change outputs"); + + // STEP 4: Verify recovery completed successfully + assert_saga_not_exists(&mint, &operation_id).await; + assert_proofs_state(&mint, &input_ys, None).await; + + // SUCCESS: Recovery works even without change outputs! +} + +// ============================================================================ +// Integration with check_pending_melt_quotes +// ============================================================================ + +/// Test: Saga recovery runs before quote checking on startup +/// +/// This test verifies that saga recovery executes before quote checking, +/// preventing conflicts where both mechanisms might try to handle the same state. +#[tokio::test] +async fn test_recovery_order_on_startup() { + // STEP 1: Setup test environment + let mint = create_test_mint().await.unwrap(); + + // STEP 2: Create incomplete saga with a pending quote + let proofs = mint_test_proofs(&mint, Amount::from(10_000)).await.unwrap(); + let quote = create_test_melt_quote(&mint, Amount::from(9_000)).await; + let melt_request = create_test_melt_request(&proofs, "e); + + let verification = mint.verify_inputs(melt_request.inputs()).await.unwrap(); + let saga = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let setup_saga = saga.setup_melt(&melt_request, verification).await.unwrap(); + + let operation_id = *setup_saga.operation.id(); + let input_ys = proofs.ys().unwrap(); + + // Drop saga (simulate crash) - this leaves quote in PENDING state + drop(setup_saga); + + // Verify initial state: saga exists, quote is pending, proofs are pending + assert_saga_exists(&mint, &operation_id).await; + assert_proofs_state(&mint, &input_ys, Some(State::Pending)).await; + + let pending_quote = mint + .localstore + .get_melt_quote("e.id) + .await + .unwrap() + .unwrap(); + assert_eq!( + pending_quote.state, + MeltQuoteState::Pending, + "Quote should be pending" + ); + + // STEP 3: Manually trigger recovery (simulating startup) + // Note: In production, mint.start() calls this automatically + mint.recover_from_incomplete_melt_sagas() + .await + .expect("Recovery should succeed"); + + // STEP 4: Verify saga recovery completed correctly + // - Saga should be deleted + // - Proofs should be removed (returned to client) + // - Quote should be reset to UNPAID + assert_saga_not_exists(&mint, &operation_id).await; + assert_proofs_state(&mint, &input_ys, None).await; + + let recovered_quote = mint + .localstore + .get_melt_quote("e.id) + .await + .unwrap() + .unwrap(); + assert_eq!( + recovered_quote.state, + MeltQuoteState::Unpaid, + "Quote should be reset to unpaid" + ); + + // STEP 5: Verify no conflicts - system is in consistent state + // Quote can be used again with new proofs + let new_proofs = mint_test_proofs(&mint, Amount::from(10_000)).await.unwrap(); + let new_request = create_test_melt_request(&new_proofs, &recovered_quote); + + let new_verification = mint.verify_inputs(new_request.inputs()).await.unwrap(); + let new_saga = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let _new_setup = new_saga + .setup_melt(&new_request, new_verification) + .await + .unwrap(); + + // SUCCESS: Recovery order is correct, no conflicts! +} + +/// Test: Saga recovery and quote checking don't duplicate work +/// +/// This test verifies that compensation is idempotent - running recovery +/// multiple times doesn't cause errors or duplicate work. +#[tokio::test] +async fn test_no_duplicate_recovery() { + // STEP 1: Setup test environment + let mint = create_test_mint().await.unwrap(); + + // STEP 2: Create incomplete saga with pending quote + let proofs = mint_test_proofs(&mint, Amount::from(10_000)).await.unwrap(); + let quote = create_test_melt_quote(&mint, Amount::from(9_000)).await; + let melt_request = create_test_melt_request(&proofs, "e); + + let verification = mint.verify_inputs(melt_request.inputs()).await.unwrap(); + let saga = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let setup_saga = saga.setup_melt(&melt_request, verification).await.unwrap(); + + let operation_id = *setup_saga.operation.id(); + let input_ys = proofs.ys().unwrap(); + + // Drop saga (simulate crash) + drop(setup_saga); + + // Verify saga exists and proofs are pending + assert_saga_exists(&mint, &operation_id).await; + assert_proofs_state(&mint, &input_ys, Some(State::Pending)).await; + + // STEP 3: Run recovery first time + mint.recover_from_incomplete_melt_sagas() + .await + .expect("First recovery should succeed"); + + // Verify saga deleted and proofs removed + assert_saga_not_exists(&mint, &operation_id).await; + assert_proofs_state(&mint, &input_ys, None).await; + + let recovered_quote = mint + .localstore + .get_melt_quote("e.id) + .await + .unwrap() + .unwrap(); + assert_eq!(recovered_quote.state, MeltQuoteState::Unpaid); + + // STEP 4: Run recovery again (simulating duplicate execution) + // Should be idempotent - no errors even though saga is already cleaned up + mint.recover_from_incomplete_melt_sagas() + .await + .expect("Second recovery should succeed (idempotent)"); + + // STEP 5: Verify state unchanged - still consistent + assert_saga_not_exists(&mint, &operation_id).await; + assert_proofs_state(&mint, &input_ys, None).await; + + let still_recovered_quote = mint + .localstore + .get_melt_quote("e.id) + .await + .unwrap() + .unwrap(); + assert_eq!(still_recovered_quote.state, MeltQuoteState::Unpaid); + + // SUCCESS: Recovery is idempotent, no duplicate work or errors! +} + +// ============================================================================ +// Production Readiness Tests +// ============================================================================ + +/// Test: Operation ID uniqueness across multiple sagas +#[tokio::test] +async fn test_operation_id_uniqueness_and_tracking() { + // STEP 1: Setup test environment + let mint = create_test_mint().await.unwrap(); + + // STEP 2: Create 10 sagas and collect their operation IDs + // Using same amount for each to avoid FakeWallet limit issues + let mut operation_ids = Vec::new(); + + for _ in 0..10 { + let proofs = mint_test_proofs(&mint, Amount::from(10_000)).await.unwrap(); + let quote = create_test_melt_quote(&mint, Amount::from(9_000)).await; + let melt_request = create_test_melt_request(&proofs, "e); + + let verification = mint.verify_inputs(melt_request.inputs()).await.unwrap(); + let saga = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let setup_saga = saga.setup_melt(&melt_request, verification).await.unwrap(); + + let operation_id = *setup_saga.operation.id(); + operation_ids.push(operation_id); + + // Keep saga alive + drop(setup_saga); + } + + // STEP 3: Verify all operation IDs are unique + let unique_ids: std::collections::HashSet<_> = operation_ids.iter().collect(); + assert_eq!( + unique_ids.len(), + operation_ids.len(), + "All {} operation IDs should be unique", + operation_ids.len() + ); + + // STEP 4: Verify all sagas are trackable in database + let sagas = mint + .localstore + .get_incomplete_sagas(OperationKind::Melt) + .await + .unwrap(); + + for operation_id in &operation_ids { + assert!( + sagas.iter().any(|s| s.operation_id == *operation_id), + "Saga {} should be trackable in database", + operation_id + ); + } + + // SUCCESS: All operation IDs are unique and trackable! +} + +/// Test: Saga drop without finalize doesn't panic +#[tokio::test] +async fn test_saga_drop_without_finalize() { + // STEP 1: Setup test environment + let mint = create_test_mint().await.unwrap(); + let proofs = mint_test_proofs(&mint, Amount::from(10_000)).await.unwrap(); + let quote = create_test_melt_quote(&mint, Amount::from(9_000)).await; + let melt_request = create_test_melt_request(&proofs, "e); + + // STEP 2: Setup saga + let verification = mint.verify_inputs(melt_request.inputs()).await.unwrap(); + let saga = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let setup_saga = saga.setup_melt(&melt_request, verification).await.unwrap(); + let operation_id = *setup_saga.operation.id(); + + // STEP 3: Drop saga without finalizing (simulates crash) + drop(setup_saga); + + // STEP 4: Verify no panic occurred and saga remains in database + let saga_in_db = assert_saga_exists(&mint, &operation_id).await; + assert_eq!(saga_in_db.operation_id, operation_id); + + // SUCCESS: Drop without finalize doesn't panic! +} + +/// Test: Saga drop after payment is recoverable +#[tokio::test] +async fn test_saga_drop_after_payment() { + // STEP 1: Setup test environment + let mint = create_test_mint().await.unwrap(); + let proofs = mint_test_proofs(&mint, Amount::from(10_000)).await.unwrap(); + let quote = create_test_melt_quote(&mint, Amount::from(9_000)).await; + let melt_request = create_test_melt_request(&proofs, "e); + + // STEP 2: Setup saga and make payment + let verification = mint.verify_inputs(melt_request.inputs()).await.unwrap(); + let saga = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let setup_saga = saga.setup_melt(&melt_request, verification).await.unwrap(); + let operation_id = *setup_saga.operation.id(); + + // Attempt internal settlement + let (payment_saga, decision) = setup_saga + .attempt_internal_settlement(&melt_request) + .await + .unwrap(); + + // Make payment + let confirmed_saga = payment_saga.make_payment(decision).await.unwrap(); + + // STEP 3: Drop before finalize (simulates crash after payment) + drop(confirmed_saga); + + // STEP 4: Verify saga still exists (wasn't finalized) + let saga_in_db = assert_saga_exists(&mint, &operation_id).await; + assert_eq!(saga_in_db.operation_id, operation_id); + + // STEP 5: Run recovery to complete the operation + mint.recover_from_incomplete_melt_sagas() + .await + .expect("Recovery should succeed"); + + // STEP 6: Verify saga was recovered and cleaned up + assert_saga_not_exists(&mint, &operation_id).await; + + // SUCCESS: Drop after payment is recoverable! +} + +// ============================================================================ +// Test Helpers +// ============================================================================ + +/// Helper: Create a test melt quote +/// +/// # Arguments +/// * `mint` - Test mint instance +/// * `amount` - Amount in sats for the quote +/// +/// # Returns +/// A valid unpaid melt quote +/// +/// # How it works +/// Uses `create_fake_invoice()` from cdk-fake-wallet to generate a valid +/// bolt11 invoice that FakeWallet will process. The FakeInvoiceDescription +/// controls payment behavior (success/failure). +async fn create_test_melt_quote( + mint: &crate::mint::Mint, + amount: Amount, +) -> cdk_common::mint::MeltQuote { + use cdk_common::melt::MeltQuoteRequest; + use cdk_common::nuts::MeltQuoteBolt11Request; + use cdk_common::CurrencyUnit; + use cdk_fake_wallet::{create_fake_invoice, FakeInvoiceDescription}; + + // Create fake invoice description (controls payment behavior) + let fake_description = FakeInvoiceDescription { + pay_invoice_state: MeltQuoteState::Paid, // Payment will succeed + check_payment_state: MeltQuoteState::Paid, // Check will show paid + pay_err: false, // No payment error + check_err: false, // No check error + }; + + // Create valid bolt11 invoice (amount in millisats) + // Amount is already in millisats, just convert to u64 + let amount_msats: u64 = amount.into(); + let invoice = create_fake_invoice( + amount_msats, + serde_json::to_string(&fake_description).unwrap(), + ); + + // Create melt quote request + let bolt11_request = MeltQuoteBolt11Request { + request: invoice, + unit: CurrencyUnit::Sat, + options: None, + }; + + let request = MeltQuoteRequest::Bolt11(bolt11_request); + + // Get quote from mint + let quote_response = mint.get_melt_quote(request).await.unwrap(); + + // Retrieve the full quote from database + let quote = mint + .localstore + .get_melt_quote("e_response.quote) + .await + .unwrap() + .expect("Quote should exist in database"); + + quote +} + +/// Helper: Create a test melt request +/// +/// # Arguments +/// * `proofs` - Input proofs for the melt +/// * `quote` - Melt quote to use +/// +/// # Returns +/// A MeltRequest ready to be used with setup_melt() +fn create_test_melt_request( + proofs: &cdk_common::nuts::Proofs, + quote: &cdk_common::mint::MeltQuote, +) -> cdk_common::nuts::MeltRequest { + use cdk_common::nuts::MeltRequest; + + MeltRequest::new( + quote.id.clone(), + proofs.clone(), + None, // No change outputs for simplicity in tests + ) +} + +/// Helper: Verify saga exists in database +async fn assert_saga_exists(mint: &crate::mint::Mint, operation_id: &uuid::Uuid) -> Saga { + let sagas = mint + .localstore + .get_incomplete_sagas(OperationKind::Melt) + .await + .unwrap(); + + sagas + .into_iter() + .find(|s| s.operation_id == *operation_id) + .expect("Saga should exist in database") +} + +/// Helper: Verify saga does not exist in database +async fn assert_saga_not_exists(mint: &crate::mint::Mint, operation_id: &uuid::Uuid) { + let sagas = mint + .localstore + .get_incomplete_sagas(OperationKind::Melt) + .await + .unwrap(); + + assert!( + !sagas.iter().any(|s| s.operation_id == *operation_id), + "Saga should not exist in database" + ); +} + +/// Helper: Verify proofs are in expected state +async fn assert_proofs_state( + mint: &crate::mint::Mint, + ys: &[cdk_common::PublicKey], + expected_state: Option, +) { + let states = mint.localstore.get_proofs_states(ys).await.unwrap(); + + for state in states { + assert_eq!(state, expected_state, "Proof state mismatch"); + } +} diff --git a/crates/cdk/src/mint/melt/shared.rs b/crates/cdk/src/mint/melt/shared.rs new file mode 100644 index 000000000..870507773 --- /dev/null +++ b/crates/cdk/src/mint/melt/shared.rs @@ -0,0 +1,443 @@ +//! Shared logic for melt operations across saga and startup check. +//! +//! This module contains common functions used by both: +//! - `melt_saga`: Normal melt operation flow +//! - `start_up_check`: Recovery of interrupted melts during startup +//! +//! The functions here ensure consistency between these two code paths. + +use cdk_common::database::{self, DynMintDatabase}; +use cdk_common::nuts::{BlindSignature, BlindedMessage, MeltQuoteState, State}; +use cdk_common::{Amount, Error, PublicKey, QuoteId}; +use cdk_signatory::signatory::SignatoryKeySet; + +use crate::mint::subscription::PubSubManager; +use crate::mint::MeltQuote; + +/// Retrieves fee and amount configuration for the keyset matching the change outputs. +/// +/// Searches active keysets for one matching the first output's keyset_id. +/// Used during change calculation for melts. +/// +/// # Arguments +/// +/// * `keysets` - Arc reference to the loaded keysets +/// * `outputs` - Change output blinded messages +/// +/// # Returns +/// +/// Fee per thousand and allowed amounts for the keyset, or default if not found +pub fn get_keyset_fee_and_amounts( + keysets: &arc_swap::ArcSwap>, + outputs: &[BlindedMessage], +) -> cdk_common::amount::FeeAndAmounts { + keysets + .load() + .iter() + .filter_map(|keyset| { + if keyset.active && Some(keyset.id) == outputs.first().map(|x| x.keyset_id) { + Some((keyset.input_fee_ppk, keyset.amounts.clone()).into()) + } else { + None + } + }) + .next() + .unwrap_or_else(|| (0, (0..32).map(|x| 2u64.pow(x)).collect::>()).into()) +} + +/// Rolls back a melt quote by removing all setup artifacts and resetting state. +/// +/// This function is used by both: +/// - `melt_saga::compensation::RemoveMeltSetup` when saga fails +/// - `start_up_check::rollback_failed_melt_quote` when recovering failed payments +/// +/// # What This Does +/// +/// Within a single database transaction: +/// 1. Removes input proofs from database +/// 2. Removes change output blinded messages +/// 3. Resets quote state from Pending to Unpaid +/// 4. Deletes melt request tracking record +/// +/// This restores the database to its pre-melt state, allowing retry. +/// +/// # Arguments +/// +/// * `db` - Database connection +/// * `quote_id` - ID of the quote to rollback +/// * `input_ys` - Y values (public keys) from input proofs +/// * `blinded_secrets` - Blinded secrets from change outputs +/// +/// # Errors +/// +/// Returns database errors if transaction fails +pub async fn rollback_melt_quote( + db: &DynMintDatabase, + quote_id: &QuoteId, + input_ys: &[PublicKey], + blinded_secrets: &[PublicKey], +) -> Result<(), Error> { + if input_ys.is_empty() && blinded_secrets.is_empty() { + return Ok(()); + } + + tracing::info!( + "Rolling back melt quote {} ({} proofs, {} blinded messages)", + quote_id, + input_ys.len(), + blinded_secrets.len() + ); + + let mut tx = db.begin_transaction().await?; + + // Remove input proofs + if !input_ys.is_empty() { + tx.remove_proofs(input_ys, Some(quote_id.clone())).await?; + } + + // Remove blinded messages (change outputs) + if !blinded_secrets.is_empty() { + tx.delete_blinded_messages(blinded_secrets).await?; + } + + // Reset quote state from Pending to Unpaid + let (previous_state, _quote) = tx + .update_melt_quote_state(quote_id, MeltQuoteState::Unpaid, None) + .await?; + + if previous_state != MeltQuoteState::Pending { + tracing::warn!( + "Unexpected quote state during rollback: expected Pending, got {}", + previous_state + ); + } + + // Delete melt request tracking record + tx.delete_melt_request(quote_id).await?; + + tx.commit().await?; + + tracing::info!("Successfully rolled back melt quote {}", quote_id); + + Ok(()) +} + +/// Processes change for a melt operation. +/// +/// This function handles the complete change workflow: +/// 1. Calculate change target amount +/// 2. Split into denominations based on keyset configuration +/// 3. Sign change outputs (external call to blind_sign) +/// 4. Store signatures in database (new transaction) +/// +/// # Transaction Management +/// +/// This function expects that the caller has already committed or will rollback +/// their current transaction before calling. It will: +/// - Call blind_sign (external, no DB lock held) +/// - Open a new transaction to store signatures +/// - Return the new transaction for the caller to commit +/// +/// # Arguments +/// +/// * `mint` - Mint instance (for keysets and blind_sign) +/// * `db` - Database connection +/// * `quote_id` - Quote ID for associating signatures +/// * `inputs_amount` - Total amount from input proofs +/// * `total_spent` - Amount spent on payment +/// * `inputs_fee` - Fee paid for inputs +/// * `change_outputs` - Blinded messages for change +/// +/// # Returns +/// +/// Tuple of: +/// - `Option>` - Signed change outputs (if any) +/// - `Box` - New transaction with signatures stored +/// +/// # Errors +/// +/// Returns error if: +/// - Change calculation fails +/// - Blind signing fails +/// - Database operations fail +pub async fn process_melt_change<'a>( + mint: &super::super::Mint, + db: &'a DynMintDatabase, + quote_id: &QuoteId, + inputs_amount: Amount, + total_spent: Amount, + inputs_fee: Amount, + change_outputs: Vec, +) -> Result< + ( + Option>, + Box + Send + Sync + 'a>, + ), + Error, +> { + // Check if change is needed + let needs_change = inputs_amount > total_spent; + + if !needs_change || change_outputs.is_empty() { + // No change needed - open transaction and return empty result + let tx = db.begin_transaction().await?; + return Ok((None, tx)); + } + + let change_target = inputs_amount - total_spent - inputs_fee; + + // Get keyset configuration + let fee_and_amounts = get_keyset_fee_and_amounts(&mint.keysets, &change_outputs); + + // Split change into denominations + let mut amounts = change_target.split(&fee_and_amounts); + + if change_outputs.len() < amounts.len() { + tracing::debug!( + "Providing change requires {} blinded messages, but only {} provided", + amounts.len(), + change_outputs.len() + ); + amounts.sort_by(|a, b| b.cmp(a)); + } + + // Prepare blinded messages with amounts + let mut blinded_messages_to_sign = vec![]; + for (amount, mut blinded_message) in amounts.iter().zip(change_outputs.iter().cloned()) { + blinded_message.amount = *amount; + blinded_messages_to_sign.push(blinded_message); + } + + // External call: sign change outputs (no DB transaction held) + let change_sigs = mint.blind_sign(blinded_messages_to_sign.clone()).await?; + + // Open new transaction to store signatures + let mut tx = db.begin_transaction().await?; + + let blinded_secrets: Vec<_> = blinded_messages_to_sign + .iter() + .map(|bm| bm.blinded_secret) + .collect(); + + tx.add_blind_signatures(&blinded_secrets, &change_sigs, Some(quote_id.clone())) + .await?; + + Ok((Some(change_sigs), tx)) +} + +/// Finalizes a melt quote by updating proofs, quote state, and publishing changes. +/// +/// This function performs the core finalization operations that are common to both +/// the saga finalize step and startup check recovery: +/// 1. Validates amounts (total_spent vs quote amount, inputs vs total_spent) +/// 2. Marks input proofs as SPENT +/// 3. Publishes proof state changes +/// 4. Updates quote state to PAID +/// 5. Updates payment lookup ID if changed +/// 6. Deletes melt request tracking +/// +/// # Transaction Management +/// +/// This function expects an open transaction and will NOT commit it. +/// The caller is responsible for committing the transaction. +/// +/// # Arguments +/// +/// * `tx` - Open database transaction +/// * `pubsub` - Pubsub manager for state notifications +/// * `quote` - Melt quote being finalized +/// * `input_ys` - Y values of input proofs +/// * `inputs_amount` - Total amount from inputs +/// * `inputs_fee` - Fee for inputs +/// * `total_spent` - Amount spent on payment +/// * `payment_preimage` - Payment preimage (if any) +/// * `payment_lookup_id` - Payment lookup identifier +/// +/// # Returns +/// +/// `Ok(())` if finalization succeeds +/// +/// # Errors +/// +/// Returns error if: +/// - Amount validation fails +/// - Proofs are already spent +/// - Database operations fail +#[allow(clippy::too_many_arguments)] +pub async fn finalize_melt_core( + tx: &mut Box + Send + Sync + '_>, + pubsub: &PubSubManager, + quote: &MeltQuote, + input_ys: &[PublicKey], + inputs_amount: Amount, + inputs_fee: Amount, + total_spent: Amount, + payment_preimage: Option, + payment_lookup_id: &cdk_common::payment::PaymentIdentifier, +) -> Result<(), Error> { + // Validate quote amount vs payment amount + if quote.amount > total_spent { + tracing::error!( + "Payment amount {} is less than quote amount {} for quote {}", + total_spent, + quote.amount, + quote.id + ); + return Err(Error::IncorrectQuoteAmount); + } + + // Validate inputs amount + if inputs_amount - inputs_fee < total_spent { + tracing::error!("Over paid melt quote {}", quote.id); + return Err(Error::IncorrectQuoteAmount); + } + + // Update quote state to Paid + tx.update_melt_quote_state("e.id, MeltQuoteState::Paid, payment_preimage.clone()) + .await?; + + // Update payment lookup ID if changed + if quote.request_lookup_id.as_ref() != Some(payment_lookup_id) { + tracing::info!( + "Payment lookup id changed post payment from {:?} to {}", + "e.request_lookup_id, + payment_lookup_id + ); + + tx.update_melt_quote_request_lookup_id("e.id, payment_lookup_id) + .await?; + } + + // Mark input proofs as spent + match tx.update_proofs_states(input_ys, State::Spent).await { + Ok(_) => {} + Err(database::Error::AttemptUpdateSpentProof) => { + tracing::info!("Proofs for quote {} already marked as spent", quote.id); + return Ok(()); + } + Err(err) => { + return Err(err.into()); + } + } + + // Publish proof state changes + for pk in input_ys.iter() { + pubsub.proof_state((*pk, State::Spent)); + } + + Ok(()) +} + +/// High-level melt finalization that handles the complete workflow. +/// +/// This function orchestrates: +/// 1. Getting melt request info +/// 2. Getting input proof Y values +/// 3. Processing change (if needed) +/// 4. Core finalization operations +/// 5. Transaction commit +/// 6. Pubsub notification +/// +/// # Arguments +/// +/// * `mint` - Mint instance +/// * `db` - Database connection +/// * `pubsub` - Pubsub manager +/// * `quote` - Melt quote to finalize +/// * `total_spent` - Amount spent on payment +/// * `payment_preimage` - Payment preimage (if any) +/// * `payment_lookup_id` - Payment lookup identifier +/// +/// # Returns +/// +/// `Option>` - Change signatures (if any) +pub async fn finalize_melt_quote( + mint: &super::super::Mint, + db: &DynMintDatabase, + pubsub: &PubSubManager, + quote: &MeltQuote, + total_spent: Amount, + payment_preimage: Option, + payment_lookup_id: &cdk_common::payment::PaymentIdentifier, +) -> Result>, Error> { + use cdk_common::amount::to_unit; + + tracing::info!("Finalizing melt quote {}", quote.id); + + // Convert total_spent to quote unit + let total_spent = to_unit(total_spent, "e.unit, "e.unit).unwrap_or(total_spent); + + let mut tx = db.begin_transaction().await?; + + // Get melt request info + let melt_request_info = match tx.get_melt_request_and_blinded_messages("e.id).await? { + Some(info) => info, + None => { + tracing::warn!( + "No melt request found for quote {} - may have been completed already", + quote.id + ); + tx.rollback().await?; + return Ok(None); + } + }; + + // Get input proof Y values + let input_ys = tx.get_proof_ys_by_quote_id("e.id).await?; + + if input_ys.is_empty() { + tracing::warn!( + "No input proofs found for quote {} - may have been completed already", + quote.id + ); + tx.rollback().await?; + return Ok(None); + } + + // Core finalization (marks proofs spent, updates quote) + finalize_melt_core( + &mut tx, + pubsub, + quote, + &input_ys, + melt_request_info.inputs_amount, + melt_request_info.inputs_fee, + total_spent, + payment_preimage.clone(), + payment_lookup_id, + ) + .await?; + + // Close transaction before external call + tx.commit().await?; + + // Process change (if needed) - opens new transaction + let (change_sigs, mut tx) = process_melt_change( + mint, + db, + "e.id, + melt_request_info.inputs_amount, + total_spent, + melt_request_info.inputs_fee, + melt_request_info.change_outputs.clone(), + ) + .await?; + + // Delete melt request tracking + tx.delete_melt_request("e.id).await?; + + // Commit transaction + tx.commit().await?; + + // Publish quote status change + pubsub.melt_quote_status( + quote, + payment_preimage, + change_sigs.clone(), + MeltQuoteState::Paid, + ); + + tracing::info!("Successfully finalized melt quote {}", quote.id); + + Ok(change_sigs) +} diff --git a/crates/cdk/src/mint/mod.rs b/crates/cdk/src/mint/mod.rs index 419e59c7e..9633e82cd 100644 --- a/crates/cdk/src/mint/mod.rs +++ b/crates/cdk/src/mint/mod.rs @@ -9,7 +9,7 @@ use cdk_common::amount::to_unit; use cdk_common::common::{PaymentProcessorKey, QuoteTTL}; #[cfg(feature = "auth")] use cdk_common::database::DynMintAuthDatabase; -use cdk_common::database::{self, DynMintDatabase, MintTransaction}; +use cdk_common::database::{self, DynMintDatabase}; use cdk_common::nuts::{self, BlindSignature, BlindedMessage, CurrencyUnit, Id, Kind}; use cdk_common::payment::{DynMintPayment, WaitPaymentResponse}; pub use cdk_common::quote_id::QuoteId; @@ -28,9 +28,9 @@ use tracing::instrument; use crate::error::Error; use crate::fees::calculate_fee; use crate::nuts::*; +use crate::Amount; #[cfg(feature = "auth")] use crate::OidcClient; -use crate::{cdk_database, Amount}; #[cfg(feature = "auth")] pub(crate) mod auth; @@ -40,7 +40,6 @@ mod issue; mod keysets; mod ln; mod melt; -mod proof_writer; mod start_up_check; mod subscription; mod swap; @@ -240,14 +239,21 @@ impl Mint { /// - Payment processor initialization and startup /// - Invoice payment monitoring across all configured payment processors pub async fn start(&self) -> Result<(), Error> { - // Checks the status of all pending melt quotes - // Pending melt quotes where the payment has gone through inputs are burnt - // Pending melt quotes where the payment has **failed** inputs are reset to unspent - self.check_pending_melt_quotes().await?; - // Recover from incomplete swap sagas // This cleans up incomplete swap operations using persisted saga state - self.recover_from_incomplete_sagas().await?; + if let Err(e) = self.recover_from_incomplete_sagas().await { + tracing::error!("Failed to recover incomplete swap sagas: {}", e); + // Don't fail startup + } + + // Recover from incomplete melt sagas + // This cleans up incomplete melt operations using persisted saga state + // Now includes checking payment status with LN backend to determine + // whether to finalize (if paid) or compensate (if failed/unpaid) + if let Err(e) = self.recover_from_incomplete_melt_sagas().await { + tracing::error!("Failed to recover incomplete melt sagas: {}", e); + // Don't fail startup + } let mut task_state = self.task_state.lock().await; @@ -890,78 +896,6 @@ impl Mint { result } - /// Verify melt request is valid - /// Check to see if there is a corresponding mint quote for a melt. - /// In this case the mint can settle the payment internally and no ln payment is - /// needed - #[instrument(skip_all)] - pub async fn handle_internal_melt_mint( - &self, - tx: &mut Box + Send + Sync + '_>, - melt_quote: &MeltQuote, - melt_request: &MeltRequest, - ) -> Result, Error> { - let mint_quote = match tx - .get_mint_quote_by_request(&melt_quote.request.to_string()) - .await - { - Ok(Some(mint_quote)) if mint_quote.unit == melt_quote.unit => mint_quote, - // Not an internal melt -> mint or unit mismatch - Ok(_) => return Ok(None), - Err(err) => { - tracing::debug!("Error attempting to get mint quote: {}", err); - return Err(Error::Internal); - } - }; - - // Mint quote has already been settled, proofs should not be burned or held. - if (mint_quote.state() == MintQuoteState::Issued - || mint_quote.state() == MintQuoteState::Paid) - && mint_quote.payment_method == PaymentMethod::Bolt11 - { - return Err(Error::RequestAlreadyPaid); - } - - let inputs_amount_quote_unit = melt_request.inputs_amount().map_err(|_| { - tracing::error!("Proof inputs in melt quote overflowed"); - Error::AmountOverflow - })?; - - if let Some(amount) = mint_quote.amount { - if amount > inputs_amount_quote_unit { - tracing::debug!( - "Not enough inputs provided: {} needed {}", - inputs_amount_quote_unit, - amount - ); - return Err(Error::InsufficientFunds); - } - } - - let amount = melt_quote.amount; - - tracing::info!( - "Mint quote {} paid {} from internal payment.", - mint_quote.id, - amount - ); - - let total_paid = tx - .increment_mint_quote_amount_paid(&mint_quote.id, amount, melt_quote.id.to_string()) - .await?; - - self.pubsub_manager - .mint_quote_payment(&mint_quote, total_paid); - - tracing::info!( - "Melt quote {} paid Mint quote {}", - melt_quote.id, - mint_quote.id - ); - - Ok(Some(amount)) - } - /// Restore #[instrument(skip_all)] pub async fn restore(&self, request: RestoreRequest) -> Result { diff --git a/crates/cdk/src/mint/proof_writer.rs b/crates/cdk/src/mint/proof_writer.rs deleted file mode 100644 index 65f35ab0c..000000000 --- a/crates/cdk/src/mint/proof_writer.rs +++ /dev/null @@ -1,237 +0,0 @@ -//! Proof writer -use std::collections::{HashMap, HashSet}; -use std::sync::Arc; - -use cdk_common::database::{self, DynMintDatabase, MintTransaction}; -use cdk_common::mint::Operation; -use cdk_common::{Error, Proofs, ProofsMethods, PublicKey, QuoteId, State}; - -use super::subscription::PubSubManager; - -type Tx<'a, 'b> = Box + Send + Sync + 'b>; - -/// Proof writer -/// -/// This is a proof writer that emulates a database transaction but without holding the transaction -/// alive while waiting for external events to be fully committed to the database; instead, it -/// maintains a `pending` state. -/// -/// This struct allows for premature exit on error, enabling it to remove proofs or reset their -/// status. -/// -/// This struct is not fully ACID. If the process exits due to a panic, and the `Drop` function -/// cannot be run, the reset process should reset the state. -pub struct ProofWriter { - db: Option, - pubsub_manager: Arc, - proof_original_states: Option>>, -} - -impl ProofWriter { - /// Creates a new ProofWriter on top of the database - pub fn new(db: DynMintDatabase, pubsub_manager: Arc) -> Self { - Self { - db: Some(db), - pubsub_manager, - proof_original_states: Some(Default::default()), - } - } - - /// The changes are permanent, consume the struct removing the database, so the Drop does - /// nothing - pub fn commit(mut self) { - self.db.take(); - self.proof_original_states.take(); - } - - /// Add proofs - pub async fn add_proofs( - &mut self, - tx: &mut Tx<'_, '_>, - proofs: &Proofs, - quote_id: Option, - operation_id: &Operation, - ) -> Result, Error> { - let proof_states = if let Some(proofs) = self.proof_original_states.as_mut() { - proofs - } else { - return Err(Error::Internal); - }; - - if let Some(err) = tx - .add_proofs(proofs.clone(), quote_id, operation_id) - .await - .err() - { - return match err { - cdk_common::database::Error::Duplicate => Err(Error::TokenPending), - cdk_common::database::Error::AttemptUpdateSpentProof => { - Err(Error::TokenAlreadySpent) - } - err => Err(Error::Database(err)), - }; - } - - let ys = proofs.ys()?; - - for pk in ys.iter() { - proof_states.insert(*pk, None); - } - - self.update_proofs_states(tx, &ys, State::Pending).await?; - - Ok(ys) - } - - /// Update proof status - pub async fn update_proofs_states( - &mut self, - tx: &mut Tx<'_, '_>, - ys: &[PublicKey], - new_proof_state: State, - ) -> Result<(), Error> { - let proof_states = if let Some(proofs) = self.proof_original_states.as_mut() { - proofs - } else { - return Err(Error::Internal); - }; - - let original_proofs_state = match tx.update_proofs_states(ys, new_proof_state).await { - Ok(states) => states, - Err(database::Error::AttemptUpdateSpentProof) - | Err(database::Error::AttemptRemoveSpentProof) => { - return Err(Error::TokenAlreadySpent) - } - Err(err) => return Err(err.into()), - }; - - if ys.len() != original_proofs_state.len() { - return Err(Error::Internal); - } - - let proofs_state = original_proofs_state - .iter() - .flatten() - .map(|x| x.to_owned()) - .collect::>(); - - let forbidden_states = if new_proof_state == State::Pending { - // If the new state is `State::Pending` it cannot be pending already - vec![State::Pending, State::Spent] - } else { - // For other state it cannot be spent - vec![State::Spent] - }; - - for forbidden_state in forbidden_states.iter() { - if proofs_state.contains(forbidden_state) { - reset_proofs_to_original_state(tx, ys, original_proofs_state).await?; - - return Err(if proofs_state.contains(&State::Pending) { - Error::TokenPending - } else { - Error::TokenAlreadySpent - }); - } - } - - for (idx, ys) in ys.iter().enumerate() { - proof_states - .entry(*ys) - .or_insert(original_proofs_state[idx]); - } - - for pk in ys { - self.pubsub_manager.proof_state((*pk, new_proof_state)); - } - - Ok(()) - } - - /// Rollback all changes in this ProofWriter consuming it. - pub async fn rollback(mut self) -> Result<(), Error> { - let db = if let Some(db) = self.db.take() { - db - } else { - return Ok(()); - }; - let mut tx = db.begin_transaction().await?; - let (ys, original_states) = if let Some(proofs) = self.proof_original_states.take() { - proofs.into_iter().unzip::<_, _, Vec<_>, Vec<_>>() - } else { - return Ok(()); - }; - - tracing::info!( - "Rollback {} proofs to their original states {:?}", - ys.len(), - original_states - ); - - reset_proofs_to_original_state(&mut tx, &ys, original_states).await?; - tx.commit().await?; - - Ok(()) - } -} - -/// Resets proofs to their original states or removes them -#[inline(always)] -async fn reset_proofs_to_original_state( - tx: &mut Tx<'_, '_>, - ys: &[PublicKey], - original_states: Vec>, -) -> Result<(), Error> { - let mut ys_by_state = HashMap::new(); - let mut unknown_proofs = Vec::new(); - for (y, state) in ys.iter().zip(original_states) { - if let Some(state) = state { - // Skip attempting to update proofs that were originally spent - if state != State::Spent { - ys_by_state.entry(state).or_insert_with(Vec::new).push(*y); - } - } else { - unknown_proofs.push(*y); - } - } - - for (state, ys) in ys_by_state { - tx.update_proofs_states(&ys, state).await?; - } - - if !unknown_proofs.is_empty() { - tx.remove_proofs(&unknown_proofs, None).await?; - } - - Ok(()) -} - -#[inline(always)] -async fn rollback( - db: DynMintDatabase, - ys: Vec, - original_states: Vec>, -) -> Result<(), Error> { - let mut tx = db.begin_transaction().await?; - reset_proofs_to_original_state(&mut tx, &ys, original_states).await?; - tx.commit().await?; - - Ok(()) -} - -impl Drop for ProofWriter { - fn drop(&mut self) { - let db = if let Some(db) = self.db.take() { - db - } else { - return; - }; - let (ys, states) = if let Some(proofs) = self.proof_original_states.take() { - proofs.into_iter().unzip() - } else { - return; - }; - - tokio::spawn(rollback(db, ys, states)); - } -} diff --git a/crates/cdk/src/mint/start_up_check.rs b/crates/cdk/src/mint/start_up_check.rs index 140e5d803..c6e7eb770 100644 --- a/crates/cdk/src/mint/start_up_check.rs +++ b/crates/cdk/src/mint/start_up_check.rs @@ -3,88 +3,103 @@ //! These checks are need in the case the mint was offline and the lightning node was node. //! These ensure that the status of the mint or melt quote matches in the mint db and on the node. +use std::str::FromStr; + use cdk_common::mint::OperationKind; +use cdk_common::QuoteId; use super::{Error, Mint}; use crate::mint::swap::swap_saga::compensation::{CompensatingAction, RemoveSwapSetup}; -use crate::mint::{MeltQuote, MeltQuoteState, PaymentMethod}; +use crate::mint::{MeltQuote, MeltQuoteState}; use crate::types::PaymentProcessorKey; impl Mint { - /// Checks the states of melt quotes that are **PENDING** or **UNKNOWN** to the mint with the ln node - pub async fn check_pending_melt_quotes(&self) -> Result<(), Error> { - // TODO: We should have a db query to do this filtering - let melt_quotes = self.localstore.get_melt_quotes().await?; - let pending_quotes: Vec = melt_quotes - .into_iter() - .filter(|q| q.state == MeltQuoteState::Pending || q.state == MeltQuoteState::Unknown) - .collect(); - tracing::info!("There are {} pending melt quotes.", pending_quotes.len()); - - if pending_quotes.is_empty() { - return Ok(()); - } + /// Checks the payment status of a melt quote with the LN backend + /// + /// This is a helper function used by saga recovery to determine whether to + /// finalize or compensate an incomplete melt operation. + /// + /// # Returns + /// + /// - `Ok(MakePaymentResponse)`: Payment status successfully retrieved from backend + /// - `Err(Error)`: Failed to check payment status (backend unavailable, no lookup_id, etc.) + async fn check_melt_payment_status( + &self, + quote: &MeltQuote, + ) -> Result { + let ln_key = PaymentProcessorKey { + unit: quote.unit.clone(), + method: quote.payment_method.clone(), + }; - let mut tx = self.localstore.begin_transaction().await?; + let ln_backend = self.payment_processors.get(&ln_key).ok_or_else(|| { + tracing::warn!("No backend for ln key: {:?}", ln_key); + Error::UnsupportedUnit + })?; - for pending_quote in pending_quotes { - tracing::debug!("Checking status for melt quote {}.", pending_quote.id); + let lookup_id = quote.request_lookup_id.as_ref().ok_or_else(|| { + tracing::warn!( + "No lookup_id for melt quote {}, cannot check payment status", + quote.id + ); + Error::Internal + })?; - let ln_key = PaymentProcessorKey { - unit: pending_quote.unit, - method: PaymentMethod::Bolt11, - }; + // Check payment status with LN backend + let pay_invoice_response = + ln_backend + .check_outgoing_payment(lookup_id) + .await + .map_err(|err| { + tracing::error!( + "Failed to check payment status for quote {}: {}", + quote.id, + err + ); + Error::Internal + })?; - let ln_backend = match self.payment_processors.get(&ln_key) { - Some(ln_backend) => ln_backend, - None => { - tracing::warn!("No backend for ln key: {:?}", ln_key); - continue; - } - }; + tracing::info!( + "Payment status for melt quote {}: {}", + quote.id, + pay_invoice_response.status + ); - if let Some(lookup_id) = pending_quote.request_lookup_id { - let pay_invoice_response = ln_backend.check_outgoing_payment(&lookup_id).await?; + Ok(pay_invoice_response) + } - tracing::warn!( - "There is no stored melt request for pending melt quote: {}", - pending_quote.id - ); + /// Finalizes a paid melt quote during startup check + /// + /// Uses shared finalization logic from melt::shared module + async fn finalize_paid_melt_quote( + &self, + quote: &MeltQuote, + total_spent: cdk_common::Amount, + payment_preimage: Option, + payment_lookup_id: &cdk_common::payment::PaymentIdentifier, + ) -> Result<(), Error> { + tracing::info!("Finalizing paid melt quote {} during startup", quote.id); - let melt_quote_state = match pay_invoice_response.status { - MeltQuoteState::Unpaid => MeltQuoteState::Unpaid, - MeltQuoteState::Paid => MeltQuoteState::Paid, - MeltQuoteState::Pending => MeltQuoteState::Pending, - MeltQuoteState::Failed => MeltQuoteState::Unpaid, - MeltQuoteState::Unknown => MeltQuoteState::Unpaid, - }; - - if let Err(err) = tx - .update_melt_quote_state( - &pending_quote.id, - melt_quote_state, - pay_invoice_response.payment_proof, - ) - .await - { - tracing::error!( - "Could not update quote {} to state {}, current state {}, {}", - pending_quote.id, - melt_quote_state, - pending_quote.state, - err - ); - }; - } - } + // Use shared finalization + super::melt::shared::finalize_melt_quote( + self, + &self.localstore, + &self.pubsub_manager, + quote, + total_spent, + payment_preimage, + payment_lookup_id, + ) + .await?; - tx.commit().await?; + tracing::info!( + "Successfully finalized melt quote {} during startup check", + quote.id + ); Ok(()) } - /// Recover from incomplete swap sagas - /// /// Checks all persisted sagas for swap operations and compensates /// incomplete ones by removing both proofs and blinded messages. pub async fn recover_from_incomplete_sagas(&self) -> Result<(), Error> { @@ -145,4 +160,368 @@ impl Mint { Ok(()) } + + /// Recover from incomplete melt sagas + /// + /// Checks all persisted sagas for melt operations and determines whether to: + /// - **Finalize**: If payment was confirmed as PAID on LN backend + /// - **Compensate**: If payment was confirmed as UNPAID/FAILED or never sent + /// - **Skip**: If payment is PENDING/UNKNOWN (leave for check_pending_melt_quotes) + /// + /// This recovery handles SetupComplete state which means: + /// - Proofs were reserved (marked as PENDING) + /// - Change outputs were added + /// - Payment may or may not have been sent + /// + /// # Critical Bug Fix + /// + /// Previously, this function always compensated (rolled back) incomplete sagas without + /// checking if the payment actually succeeded on the LN backend. This could cause the + /// mint to lose funds if: + /// 1. Payment succeeded on LN backend + /// 2. Mint crashed before finalize() committed + /// 3. Recovery compensated (returned proofs) instead of finalizing + /// + /// Now we check the LN backend payment status before deciding whether to compensate or finalize. + pub async fn recover_from_incomplete_melt_sagas(&self) -> Result<(), Error> { + let incomplete_sagas = self + .localstore + .get_incomplete_sagas(OperationKind::Melt) + .await?; + + if incomplete_sagas.is_empty() { + tracing::info!("No incomplete melt sagas found to recover."); + return Ok(()); + } + + let total_sagas = incomplete_sagas.len(); + tracing::info!("Found {} incomplete melt sagas to recover.", total_sagas); + + for saga in incomplete_sagas { + tracing::info!( + "Recovering melt saga {} in state '{}' (created: {}, updated: {})", + saga.operation_id, + saga.state.state(), + saga.created_at, + saga.updated_at + ); + + // Get quote_id from saga (new field added for efficient lookup) + let quote_id = match saga.quote_id { + Some(ref qid) => qid.clone(), + None => { + tracing::warn!( + "Saga {} has no quote_id (old saga format) - attempting fallback lookup", + saga.operation_id + ); + + // Fallback: Find quote by matching input_ys (for backward compatibility) + let melt_quotes = match self.localstore.get_melt_quotes().await { + Ok(quotes) => quotes, + Err(e) => { + tracing::error!( + "Failed to get melt quotes for saga {}: {}", + saga.operation_id, + e + ); + continue; + } + }; + + let mut quote_id_found = None; + for quote in melt_quotes { + let tx = self.localstore.begin_transaction().await?; + let proof_ys = tx.get_proof_ys_by_quote_id("e.id).await?; + tx.rollback().await?; + + if !saga.input_ys.is_empty() + && !proof_ys.is_empty() + && saga.input_ys.iter().any(|y| proof_ys.contains(y)) + { + quote_id_found = Some(quote.id.clone()); + break; + } + } + + match quote_id_found { + Some(qid) => qid.to_string(), + None => { + tracing::warn!( + "Could not find quote_id for saga {} - may have been cleaned up already. Deleting orphaned saga.", + saga.operation_id + ); + + let mut delete_tx = self.localstore.begin_transaction().await?; + if let Err(e) = delete_tx.delete_saga(&saga.operation_id).await { + tracing::error!( + "Failed to delete orphaned saga {}: {}", + saga.operation_id, + e + ); + delete_tx.rollback().await?; + } else { + delete_tx.commit().await?; + } + continue; + } + } + } + }; + + // Get the quote from database + let quote_id_parsed = match QuoteId::from_str("e_id) { + Ok(id) => id, + Err(e) => { + tracing::error!( + "Failed to parse quote_id '{}' for saga {}: {:?}. Skipping saga.", + quote_id, + saga.operation_id, + e + ); + continue; + } + }; + + let quote = match self.localstore.get_melt_quote("e_id_parsed).await { + Ok(Some(q)) => q, + Ok(None) => { + tracing::warn!( + "Quote {} for saga {} not found - may have been cleaned up. Deleting orphaned saga.", + quote_id, + saga.operation_id + ); + + let mut delete_tx = self.localstore.begin_transaction().await?; + if let Err(e) = delete_tx.delete_saga(&saga.operation_id).await { + tracing::error!( + "Failed to delete orphaned saga {}: {}", + saga.operation_id, + e + ); + delete_tx.rollback().await?; + } else { + delete_tx.commit().await?; + } + continue; + } + Err(e) => { + tracing::error!( + "Failed to get quote {} for saga {}: {}. Skipping saga.", + quote_id, + saga.operation_id, + e + ); + continue; + } + }; + + // Check saga state to determine if payment was sent + // SetupComplete means setup transaction committed but payment NOT yet sent + let should_compensate = match &saga.state { + cdk_common::mint::SagaStateEnum::Melt(state) => { + match state { + cdk_common::mint::MeltSagaState::SetupComplete => { + // Setup complete but payment never sent - always compensate + tracing::info!( + "Saga {} in SetupComplete state - payment never sent, will compensate", + saga.operation_id + ); + true + } + _ => { + // Other states - should not happen in incomplete sagas, but check payment status anyway + false // Will check payment status below + } + } + } + _ => { + continue; // Skip non-melt sagas + } + }; + + let should_compensate = if should_compensate { + true + } else if quote.request_lookup_id.is_none() { + // Fallback: No request_lookup_id means payment likely never sent + tracing::info!( + "Saga {} for quote {} has no request_lookup_id - payment never sent, will compensate", + saga.operation_id, + quote_id + ); + true + } else { + // Payment was attempted - check LN backend status + tracing::info!( + "Saga {} for quote {} has request_lookup_id - checking payment status with LN backend", + saga.operation_id, + quote_id + ); + + match self.check_melt_payment_status("e).await { + Ok(payment_response) => { + match payment_response.status { + MeltQuoteState::Paid => { + // Payment succeeded - finalize instead of compensating + tracing::info!( + "Saga {} for quote {} - payment PAID on LN backend, will finalize", + saga.operation_id, + quote_id + ); + + if let Err(err) = self + .finalize_paid_melt_quote( + "e, + payment_response.total_spent, + payment_response.payment_proof, + &payment_response.payment_lookup_id, + ) + .await + { + tracing::error!( + "Failed to finalize paid melt saga {}: {}", + saga.operation_id, + err + ); + } + + // Delete saga after successful finalization + let mut tx = self.localstore.begin_transaction().await?; + if let Err(e) = tx.delete_saga(&saga.operation_id).await { + tracing::error!( + "Failed to delete saga for {}: {}", + saga.operation_id, + e + ); + tx.rollback().await?; + } else { + tx.commit().await?; + tracing::info!( + "Successfully recovered and finalized melt saga {}", + saga.operation_id + ); + } + + continue; // Skip compensation, saga handled + } + MeltQuoteState::Unpaid | MeltQuoteState::Failed => { + // Payment failed - compensate + tracing::info!( + "Saga {} for quote {} - payment {} on LN backend, will compensate", + saga.operation_id, + quote_id, + payment_response.status + ); + true + } + MeltQuoteState::Pending | MeltQuoteState::Unknown => { + // Payment still pending - skip for check_pending_melt_quotes + tracing::info!( + "Saga {} for quote {} - payment {} on LN backend, skipping (will be handled by check_pending_melt_quotes)", + saga.operation_id, + quote_id, + payment_response.status + ); + continue; // Skip this saga, don't compensate or finalize + } + } + } + Err(err) => { + // LN backend unavailable - skip this saga, will retry on next recovery cycle + tracing::warn!( + "Failed to check payment status for saga {} quote {}: {}. Skipping for now, will retry on next recovery cycle.", + saga.operation_id, + quote_id, + err + ); + continue; // Skip this saga + } + } + }; + + // Compensate if needed + if should_compensate { + // Use saga data directly for compensation (like swap does) + tracing::info!( + "Compensating melt saga {} (removing {} proofs, {} change outputs)", + saga.operation_id, + saga.input_ys.len(), + saga.blinded_secrets.len() + ); + + // Compensate using saga data only - don't rely on quote state + let mut tx = self.localstore.begin_transaction().await?; + + // Remove blinded messages (change outputs) + if !saga.blinded_secrets.is_empty() { + if let Err(e) = tx.delete_blinded_messages(&saga.blinded_secrets).await { + tracing::error!( + "Failed to delete blinded messages for saga {}: {}", + saga.operation_id, + e + ); + tx.rollback().await?; + continue; + } + } + + // Remove proofs (inputs) - use None for quote_id like swap does + if !saga.input_ys.is_empty() { + if let Err(e) = tx.remove_proofs(&saga.input_ys, None).await { + tracing::error!( + "Failed to remove proofs for saga {}: {}", + saga.operation_id, + e + ); + tx.rollback().await?; + continue; + } + } + + // Reset quote state to Unpaid (melt-specific, unlike swap) + if let Err(e) = tx + .update_melt_quote_state("e_id_parsed, MeltQuoteState::Unpaid, None) + .await + { + tracing::error!( + "Failed to reset quote state for saga {}: {}", + saga.operation_id, + e + ); + tx.rollback().await?; + continue; + } + + // Delete melt request tracking record + if let Err(e) = tx.delete_melt_request("e_id_parsed).await { + tracing::error!( + "Failed to delete melt request for saga {}: {}", + saga.operation_id, + e + ); + // Don't fail if melt request doesn't exist - it might not have been created yet + } + + // Delete saga after successful compensation + if let Err(e) = tx.delete_saga(&saga.operation_id).await { + tracing::error!("Failed to delete saga for {}: {}", saga.operation_id, e); + tx.rollback().await?; + continue; + } + + tx.commit().await?; + + tracing::info!( + "Successfully recovered and compensated melt saga {}", + saga.operation_id + ); + } + } + + tracing::info!( + "Successfully recovered {} incomplete melt sagas.", + total_sagas + ); + + Ok(()) + } } diff --git a/justfile b/justfile index 22d93fd14..381cbfe02 100644 --- a/justfile +++ b/justfile @@ -199,8 +199,8 @@ itest db: fake-mint-itest db: #!/usr/bin/env bash set -euo pipefail - ./misc/fake_itests.sh "{{db}}" external_signatory ./misc/fake_itests.sh "{{db}}" + ./misc/fake_itests.sh "{{db}}" external_signatory itest-payment-processor ln: #!/usr/bin/env bash From 4e0132875f21040e85391c06639d5fa3bba39193 Mon Sep 17 00:00:00 2001 From: C Date: Tue, 4 Nov 2025 22:40:31 -0300 Subject: [PATCH 248/321] fix: add proof recovery mechanism for failed wallet operations (#1250) * fix: add proof recovery mechanism for failed wallet operations This commit introduces a new `try_proof_operation` helper that wraps wallet operations (swap, melt) with automatic proof recovery in case of network or mint failures. When an operation fails, the wallet now attempts to recover by marking proofs as unspent and swapping them to prevent loss of funds. Fixes #1180 --- crates/cdk-integration-tests/src/lib.rs | 38 --- .../tests/fake_wallet.rs | 235 ++++++++++++++++-- crates/cdk/src/wallet/builder.rs | 1 + crates/cdk/src/wallet/melt/melt_bolt11.rs | 28 +-- crates/cdk/src/wallet/mod.rs | 3 + crates/cdk/src/wallet/reclaim.rs | 105 ++++++++ crates/cdk/src/wallet/swap.rs | 7 +- 7 files changed, 342 insertions(+), 75 deletions(-) create mode 100644 crates/cdk/src/wallet/reclaim.rs diff --git a/crates/cdk-integration-tests/src/lib.rs b/crates/cdk-integration-tests/src/lib.rs index cd5f45387..4331ac22b 100644 --- a/crates/cdk-integration-tests/src/lib.rs +++ b/crates/cdk-integration-tests/src/lib.rs @@ -23,7 +23,6 @@ use std::sync::Arc; use anyhow::{anyhow, bail, Result}; use cashu::Bolt11Invoice; use cdk::amount::{Amount, SplitTarget}; -use cdk::nuts::State; use cdk::{StreamExt, Wallet}; use cdk_fake_wallet::create_fake_invoice; use init_regtest::{get_lnd_dir, LND_RPC_ADDR}; @@ -65,43 +64,6 @@ pub fn get_second_mint_url_from_env() -> String { } } -// Get all pending from wallet and attempt to swap -// Will panic if there are no pending -// Will return Ok if swap fails as expected -pub async fn attempt_to_swap_pending(wallet: &Wallet) -> Result<()> { - let pending = wallet - .localstore - .get_proofs(None, None, Some(vec![State::Pending]), None) - .await?; - - assert!(!pending.is_empty()); - - let swap = wallet - .swap( - None, - SplitTarget::None, - pending.into_iter().map(|p| p.proof).collect(), - None, - false, - ) - .await; - - match swap { - Ok(_swap) => { - bail!("These proofs should be pending") - } - Err(err) => match err { - cdk::error::Error::TokenPending => (), - _ => { - println!("{err:?}"); - bail!("Wrong error") - } - }, - } - - Ok(()) -} - // This is the ln wallet we use to send/receive ln payements as the wallet pub async fn init_lnd_client(work_dir: &Path) -> LndClient { let lnd_dir = get_lnd_dir(work_dir, "one"); diff --git a/crates/cdk-integration-tests/tests/fake_wallet.rs b/crates/cdk-integration-tests/tests/fake_wallet.rs index b6b271fea..942f8ce6d 100644 --- a/crates/cdk-integration-tests/tests/fake_wallet.rs +++ b/crates/cdk-integration-tests/tests/fake_wallet.rs @@ -28,7 +28,6 @@ use cdk::wallet::types::TransactionDirection; use cdk::wallet::{HttpClient, MintConnector, Wallet}; use cdk::StreamExt; use cdk_fake_wallet::{create_fake_invoice, FakeInvoiceDescription}; -use cdk_integration_tests::attempt_to_swap_pending; use cdk_sqlite::wallet::memory; const MINT_URL: &str = "http://127.0.0.1:8086"; @@ -55,6 +54,8 @@ async fn test_fake_tokens_pending() { .expect("payment") .expect("no error"); + let old_balance = wallet.total_balance().await.expect("balance"); + let fake_description = FakeInvoiceDescription { pay_invoice_state: MeltQuoteState::Pending, check_payment_state: MeltQuoteState::Pending, @@ -70,7 +71,18 @@ async fn test_fake_tokens_pending() { assert!(melt.is_err()); - attempt_to_swap_pending(&wallet).await.unwrap(); + // melt failed, but there is new code to reclaim unspent proofs + assert_eq!( + old_balance, + wallet.total_balance().await.expect("new balance") + ); + + assert!(wallet + .localstore + .get_proofs(None, None, Some(vec![State::Pending]), None) + .await + .unwrap() + .is_empty()); } /// Tests that if the pay error fails and the check returns unknown or failed, @@ -126,15 +138,8 @@ async fn test_fake_melt_payment_fail() { let melt = wallet.melt(&melt_quote.id).await; assert!(melt.is_err()); - // The mint should have unset proofs from pending since payment failed - let all_proof = wallet.get_unspent_proofs().await.unwrap(); - let states = wallet.check_proofs_spent(all_proof).await.unwrap(); - for state in states { - assert!(state.state == State::Unspent); - } - let wallet_bal = wallet.total_balance().await.unwrap(); - assert_eq!(wallet_bal, 98.into()); + assert_eq!(wallet_bal, 100.into()); } /// Tests that when both the pay_invoice and check_invoice both fail, @@ -160,6 +165,8 @@ async fn test_fake_melt_payment_fail_and_check() { .expect("payment") .expect("no error"); + let old_balance = wallet.total_balance().await.expect("balance"); + let fake_description = FakeInvoiceDescription { pay_invoice_state: MeltQuoteState::Unknown, check_payment_state: MeltQuoteState::Unknown, @@ -175,13 +182,18 @@ async fn test_fake_melt_payment_fail_and_check() { let melt = wallet.melt(&melt_quote.id).await; assert!(melt.is_err()); - let pending = wallet + // melt failed, but there is new code to reclaim unspent proofs + assert_eq!( + old_balance, + wallet.total_balance().await.expect("new balance") + ); + + assert!(wallet .localstore .get_proofs(None, None, Some(vec![State::Pending]), None) .await - .unwrap(); - - assert!(!pending.is_empty()); + .unwrap() + .is_empty()); } /// Tests that when the ln backend returns a failed status but does not error, @@ -214,6 +226,8 @@ async fn test_fake_melt_payment_return_fail_status() { check_err: false, }; + let old_balance = wallet.total_balance().await.expect("balance"); + let invoice = create_fake_invoice(7000, serde_json::to_string(&fake_description).unwrap()); let melt_quote = wallet.melt_quote(invoice.to_string(), None).await.unwrap(); @@ -247,15 +261,19 @@ async fn test_fake_melt_payment_return_fail_status() { let melt = wallet.melt(&melt_quote.id).await; assert!(melt.is_err()); + assert_eq!( + old_balance, + wallet.total_balance().await.expect("new balance") + ); + wallet.check_all_pending_proofs().await.unwrap(); - let pending = wallet + assert!(wallet .localstore .get_proofs(None, None, Some(vec![State::Pending]), None) .await - .unwrap(); - - assert!(!pending.is_empty()); + .unwrap() + .is_empty()); } /// Tests that when the ln backend returns an error with unknown status, @@ -281,6 +299,8 @@ async fn test_fake_melt_payment_error_unknown() { .expect("payment") .expect("no error"); + let old_balance = wallet.total_balance().await.expect("balance"); + let fake_description = FakeInvoiceDescription { pay_invoice_state: MeltQuoteState::Failed, check_payment_state: MeltQuoteState::Unknown, @@ -313,13 +333,17 @@ async fn test_fake_melt_payment_error_unknown() { wallet.check_all_pending_proofs().await.unwrap(); - let pending = wallet + assert_eq!( + old_balance, + wallet.total_balance().await.expect("new balance") + ); + + assert!(wallet .localstore .get_proofs(None, None, Some(vec![State::Pending]), None) .await - .unwrap(); - - assert!(!pending.is_empty()); + .unwrap() + .is_empty()); } /// Tests that when the ln backend returns an error but the second check returns paid, @@ -345,6 +369,8 @@ async fn test_fake_melt_payment_err_paid() { .expect("payment") .expect("no error"); + let old_balance = wallet.total_balance().await.expect("balance"); + let fake_description = FakeInvoiceDescription { pay_invoice_state: MeltQuoteState::Failed, check_payment_state: MeltQuoteState::Paid, @@ -361,6 +387,19 @@ async fn test_fake_melt_payment_err_paid() { assert!(melt.fee_paid == Amount::ZERO); assert!(melt.amount == Amount::from(7)); + + // melt failed, but there is new code to reclaim unspent proofs + assert_eq!( + old_balance - melt.amount, + wallet.total_balance().await.expect("new balance") + ); + + assert!(wallet + .localstore + .get_proofs(None, None, Some(vec![State::Pending]), None) + .await + .unwrap() + .is_empty()); } /// Tests that change outputs in a melt quote are correctly handled @@ -1387,3 +1426,155 @@ async fn test_fake_mint_duplicate_proofs_melt() { } } } + +/// Tests that wallet automatically recovers proofs after a failed melt operation +/// by swapping them to new proofs, preventing loss of funds +#[tokio::test(flavor = "multi_thread", worker_threads = 1)] +async fn test_wallet_proof_recovery_after_failed_melt() { + let wallet = Wallet::new( + MINT_URL, + CurrencyUnit::Sat, + Arc::new(memory::empty().await.unwrap()), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), + None, + ) + .expect("failed to create new wallet"); + + // Mint 100 sats + let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); + let mut proof_streams = wallet.proof_stream(mint_quote.clone(), SplitTarget::default(), None); + let initial_proofs = proof_streams + .next() + .await + .expect("payment") + .expect("no error"); + + let initial_ys: Vec<_> = initial_proofs.iter().map(|p| p.y().unwrap()).collect(); + + assert_eq!(wallet.total_balance().await.unwrap(), Amount::from(100)); + + // Create a melt quote that will fail + let fake_description = FakeInvoiceDescription { + pay_invoice_state: MeltQuoteState::Unknown, + check_payment_state: MeltQuoteState::Unpaid, + pay_err: true, + check_err: false, + }; + + let invoice = create_fake_invoice(1000, serde_json::to_string(&fake_description).unwrap()); + let melt_quote = wallet.melt_quote(invoice.to_string(), None).await.unwrap(); + + // Attempt to melt - this should fail but trigger proof recovery + let melt_result = wallet.melt(&melt_quote.id).await; + assert!(melt_result.is_err(), "Melt should have failed"); + + // Verify wallet still has balance (proofs recovered) + assert_eq!( + wallet.total_balance().await.unwrap(), + Amount::from(100), + "Balance should be recovered" + ); + + // Verify the proofs were swapped (different Ys) + let recovered_proofs = wallet.get_unspent_proofs().await.unwrap(); + let recovered_ys: Vec<_> = recovered_proofs.iter().map(|p| p.y().unwrap()).collect(); + + // The Ys should be different (swapped to new proofs) + assert!( + initial_ys.iter().any(|y| !recovered_ys.contains(y)), + "Proofs should have been swapped to new ones" + ); + + // Verify we can still spend the recovered proofs + let valid_invoice = create_fake_invoice(7000, "".to_string()); + let valid_melt_quote = wallet + .melt_quote(valid_invoice.to_string(), None) + .await + .unwrap(); + + let successful_melt = wallet.melt(&valid_melt_quote.id).await; + assert!( + successful_melt.is_ok(), + "Should be able to spend recovered proofs" + ); +} + +/// Tests that wallet automatically recovers proofs after a failed swap operation +#[tokio::test(flavor = "multi_thread", worker_threads = 1)] +async fn test_wallet_proof_recovery_after_failed_swap() { + let wallet = Wallet::new( + MINT_URL, + CurrencyUnit::Sat, + Arc::new(memory::empty().await.unwrap()), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), + None, + ) + .expect("failed to create new wallet"); + + // Mint 100 sats + let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); + let mut proof_streams = wallet.proof_stream(mint_quote.clone(), SplitTarget::default(), None); + let initial_proofs = proof_streams + .next() + .await + .expect("payment") + .expect("no error"); + + let initial_ys: Vec<_> = initial_proofs.iter().map(|p| p.y().unwrap()).collect(); + + assert_eq!(wallet.total_balance().await.unwrap(), Amount::from(100)); + + let unspent_proofs = wallet.get_unspent_proofs().await.unwrap(); + + // Create an invalid swap by manually constructing a request that will fail + // We'll use the wallet's swap with invalid parameters to trigger a failure + let active_keyset_id = wallet.fetch_active_keyset().await.unwrap().id; + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); + + // Create invalid swap request (requesting more than we have) + let preswap = PreMintSecrets::random( + active_keyset_id, + 1000.into(), // More than the 100 we have + &SplitTarget::default(), + &fee_and_amounts, + ) + .unwrap(); + + let swap_request = SwapRequest::new(unspent_proofs.clone(), preswap.blinded_messages()); + + // Use HTTP client directly to bypass wallet's validation and trigger recovery + let http_client = HttpClient::new(MINT_URL.parse().unwrap(), None); + let response = http_client.post_swap(swap_request).await; + assert!(response.is_err(), "Swap should have failed"); + + // Note: The HTTP client doesn't trigger the wallet's try_proof_operation wrapper + // So we need to test through the wallet's own methods + // After the failed HTTP request, the proofs are still in the wallet's database + + // Verify balance is still available after the failed operation + assert_eq!( + wallet.total_balance().await.unwrap(), + Amount::from(100), + "Balance should still be available" + ); + + // Verify we can perform a successful swap operation + let successful_swap = wallet + .swap(None, SplitTarget::None, unspent_proofs, None, false) + .await; + + assert!( + successful_swap.is_ok(), + "Should be able to swap after failed operation" + ); + + // Verify the proofs were swapped to new ones + let final_proofs = wallet.get_unspent_proofs().await.unwrap(); + let final_ys: Vec<_> = final_proofs.iter().map(|p| p.y().unwrap()).collect(); + + // The Ys should be different after the successful swap + assert!( + initial_ys.iter().any(|y| !final_ys.contains(y)), + "Proofs should have been swapped to new ones" + ); +} diff --git a/crates/cdk/src/wallet/builder.rs b/crates/cdk/src/wallet/builder.rs index 500b77a4f..bcfc403e8 100644 --- a/crates/cdk/src/wallet/builder.rs +++ b/crates/cdk/src/wallet/builder.rs @@ -172,6 +172,7 @@ impl WalletBuilder { seed, client: client.clone(), subscription: SubscriptionManager::new(client, self.use_http_subscription), + in_error_swap_reverted_proofs: Arc::new(false.into()), }) } } diff --git a/crates/cdk/src/wallet/melt/melt_bolt11.rs b/crates/cdk/src/wallet/melt/melt_bolt11.rs index 58b23353a..78b2a773a 100644 --- a/crates/cdk/src/wallet/melt/melt_bolt11.rs +++ b/crates/cdk/src/wallet/melt/melt_bolt11.rs @@ -198,25 +198,25 @@ impl Wallet { ); let melt_response = match quote_info.payment_method { - cdk_common::PaymentMethod::Bolt11 => self.client.post_melt(request).await, - cdk_common::PaymentMethod::Bolt12 => self.client.post_melt_bolt12(request).await, + cdk_common::PaymentMethod::Bolt11 => { + self.try_proof_operation_or_reclaim( + request.inputs().clone(), + self.client.post_melt(request), + ) + .await? + } + cdk_common::PaymentMethod::Bolt12 => { + self.try_proof_operation_or_reclaim( + request.inputs().clone(), + self.client.post_melt_bolt12(request), + ) + .await? + } cdk_common::PaymentMethod::Custom(_) => { return Err(Error::UnsupportedPaymentMethod); } }; - let melt_response = match melt_response { - Ok(melt_response) => melt_response, - Err(err) => { - tracing::error!("Could not melt: {}", err); - tracing::info!("Checking status of input proofs."); - - self.reclaim_unspent(proofs).await?; - - return Err(err); - } - }; - let active_keys = self .localstore .get_keys(&active_keyset_id) diff --git a/crates/cdk/src/wallet/mod.rs b/crates/cdk/src/wallet/mod.rs index 999ff8753..4a9ed797e 100644 --- a/crates/cdk/src/wallet/mod.rs +++ b/crates/cdk/src/wallet/mod.rs @@ -2,6 +2,7 @@ use std::collections::HashMap; use std::str::FromStr; +use std::sync::atomic::AtomicBool; use std::sync::Arc; use cdk_common::amount::FeeAndAmounts; @@ -45,6 +46,7 @@ pub mod multi_mint_wallet; pub mod payment_request; mod proofs; mod receive; +mod reclaim; mod send; #[cfg(not(target_arch = "wasm32"))] mod streams; @@ -91,6 +93,7 @@ pub struct Wallet { seed: [u8; 64], client: Arc, subscription: SubscriptionManager, + in_error_swap_reverted_proofs: Arc, } const ALPHANUMERIC: &[u8] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"; diff --git a/crates/cdk/src/wallet/reclaim.rs b/crates/cdk/src/wallet/reclaim.rs new file mode 100644 index 000000000..648e022ef --- /dev/null +++ b/crates/cdk/src/wallet/reclaim.rs @@ -0,0 +1,105 @@ +use std::future::Future; + +use crate::nuts::{Proofs, State}; +use crate::{Error, Wallet}; + +#[cfg(not(target_arch = "wasm32"))] +type BoxFuture<'a, T> = futures::future::BoxFuture<'a, T>; + +/// +#[cfg(target_arch = "wasm32")] +type BoxFuture<'a, T> = futures::future::LocalBoxFuture<'a, T>; + +/// MaybeSend +/// +/// Which is Send for most platforms but WASM. +#[cfg(not(target_arch = "wasm32"))] +pub trait MaybeSend: Send {} + +#[cfg(target_arch = "wasm32")] +pub trait MaybeSend {} + +/// Autoimplement MaybeSend for T +#[cfg(not(target_arch = "wasm32"))] +impl MaybeSend for T {} + +#[cfg(target_arch = "wasm32")] +impl MaybeSend for T {} + +/// Size of proofs to send to avoid hitting the mint limit. +const BATCH_PROOF_SIZE: usize = 100; + +impl Wallet { + /// Perform an async task, which is assumed to be a foreign mint call that can fail. If fails, + /// the proofs used in the request are set as unspent, then they are swapped, as they are + /// believed to be already shown to the mint + #[inline(always)] + pub(crate) fn try_proof_operation_or_reclaim<'a, F, R>( + &'a self, + inputs: Proofs, + f: F, + ) -> BoxFuture<'a, F::Output> + where + F: Future> + MaybeSend + 'a, + R: MaybeSend + Sync + 'a, + { + Box::pin(async move { + match f.await { + Ok(r) => Ok(r), + Err(err) => { + tracing::error!( + "Http operation failed with \"{}\", revering {} proofs states to UNSPENT", + err, + inputs.len() + ); + + let swap_reverted_proofs = self + .in_error_swap_reverted_proofs + .compare_exchange( + false, + true, + std::sync::atomic::Ordering::SeqCst, + std::sync::atomic::Ordering::SeqCst, + ) + .is_ok(); + + if swap_reverted_proofs { + tracing::error!( + "Attempting to swap exposed {} proofs to new proofs", + inputs.len() + ); + for proofs in inputs.chunks(BATCH_PROOF_SIZE) { + if let Err(inner_err) = self.reclaim_unspent(proofs.to_owned()).await { + println!( + "Failed to swap exposed proofs ({}), updating local database instead", inner_err + ); + tracing::warn!( + "Failed to swap exposed proofs ({}), updating local database instead", inner_err + ); + + let _ = self + .localstore + .update_proofs_state( + proofs + .iter() + .map(|x| x.y()) + .collect::, _>>()?, + State::Unspent, + ) + .await + .inspect_err(|err| { + tracing::error!("Failed err update_proofs_state {}", err) + }); + } + } + + self.in_error_swap_reverted_proofs + .store(false, std::sync::atomic::Ordering::SeqCst); + } + + Err(err) + } + } + }) + } +} diff --git a/crates/cdk/src/wallet/swap.rs b/crates/cdk/src/wallet/swap.rs index 6e52eeb7d..71a538b5a 100644 --- a/crates/cdk/src/wallet/swap.rs +++ b/crates/cdk/src/wallet/swap.rs @@ -37,7 +37,12 @@ impl Wallet { ) .await?; - let swap_response = self.client.post_swap(pre_swap.swap_request).await?; + let swap_response = self + .try_proof_operation_or_reclaim( + pre_swap.swap_request.inputs().clone(), + self.client.post_swap(pre_swap.swap_request), + ) + .await?; let active_keyset_id = pre_swap.pre_mint_secrets.keyset_id; let fee_and_amounts = self From 82f25795ba591c16a41c4838130c1d2422b7f0d2 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 5 Nov 2025 21:08:13 -0500 Subject: [PATCH 249/321] chore: add weekly meeting agenda for 2025-11-05 (#1254) Co-authored-by: github-actions[bot] --- meetings/2025-11-05-agenda.md | 59 +++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 meetings/2025-11-05-agenda.md diff --git a/meetings/2025-11-05-agenda.md b/meetings/2025-11-05-agenda.md new file mode 100644 index 000000000..559505f40 --- /dev/null +++ b/meetings/2025-11-05-agenda.md @@ -0,0 +1,59 @@ +# CDK Development Meeting + +Nov 05 2025 15:00 UTC + +Meeting Link: https://meet.fulmo.org/cdk-dev + +## Merged + +- [#1250](https://github.com/cashubtc/cdk/pull/1250) - fix: add proof recovery mechanism for failed wallet operations +- [#1246](https://github.com/cashubtc/cdk/pull/1246) - Fix websocket issues and mint quotes +- [#1245](https://github.com/cashubtc/cdk/pull/1245) - [Backport v0.13.x] fix: lnbits fee calc +- [#1244](https://github.com/cashubtc/cdk/pull/1244) - PreMintSecrets: fix `into_iter()` +- [#1243](https://github.com/cashubtc/cdk/pull/1243) - fix: lnbits fee calc +- [#1242](https://github.com/cashubtc/cdk/pull/1242) - Ldk compose setup +- [#1241](https://github.com/cashubtc/cdk/pull/1241) - Include cargo config for cdk-ffi to enforce Android page sizes +- [#1239](https://github.com/cashubtc/cdk/pull/1239) - Weekly Meeting Agenda - 2025-10-29 +- [#1186](https://github.com/cashubtc/cdk/pull/1186) - Melt saga + +## Ongoing + +- [#1214](https://github.com/cashubtc/cdk/pull/1214) - feat(cdk-payment-processor): add currency unit parameter to make_payment +- [#1212](https://github.com/cashubtc/cdk/pull/1212) - Various mint fixes for swap (and now melt also). SIG_INPUTS+SIG_ALL, locktimes, P2PK+HTLC. Also updates the SIG_ALL message for amount-switching +- [#1211](https://github.com/cashubtc/cdk/pull/1211) - Regtest setup +- [#1210](https://github.com/cashubtc/cdk/pull/1210) - test: add mutation testing infrastructure +- [#1208](https://github.com/cashubtc/cdk/pull/1208) - Sig all fixes +- [#1204](https://github.com/cashubtc/cdk/pull/1204) - Add database transaction trait for cdk wallet +- [#1202](https://github.com/cashubtc/cdk/pull/1202) - Onchain +- [#1201](https://github.com/cashubtc/cdk/pull/1201) - feat: npubcash +- [#1200](https://github.com/cashubtc/cdk/pull/1200) - feat: optimize pending mint quotes query performance +- [#1198](https://github.com/cashubtc/cdk/pull/1198) - fix: check the removed_ys argument before creating the delete query +- [#1196](https://github.com/cashubtc/cdk/pull/1196) - feat(ci): add merge queue workflow and simplify clippy checks +- [#1190](https://github.com/cashubtc/cdk/pull/1190) - feat(cashu): add NUT-26 bech32m encoding for payment requests +- [#1182](https://github.com/cashubtc/cdk/pull/1182) - ehash: add support for mining share mint quotes +- [#1181](https://github.com/cashubtc/cdk/pull/1181) - Deterministic Currency Unit Derivation Paths +- [#1173](https://github.com/cashubtc/cdk/pull/1173) - Prefer async +- [#1171](https://github.com/cashubtc/cdk/pull/1171) - Add Dart Bindings Support +- [#1153](https://github.com/cashubtc/cdk/pull/1153) - Add cdk-mintd module and package +- [#1132](https://github.com/cashubtc/cdk/pull/1132) - Quote id as lookup +- [#1127](https://github.com/cashubtc/cdk/pull/1127) - rename ln settings in toml configuration +- [#1118](https://github.com/cashubtc/cdk/pull/1118) - feat: uniffi bindings for golang +- [#1100](https://github.com/cashubtc/cdk/pull/1100) - NUT-XX: Cairo Spending Conditions implementation +- [#1067](https://github.com/cashubtc/cdk/pull/1067) - Nutxx ohttp +- [#1053](https://github.com/cashubtc/cdk/pull/1053) - feat: P2PK key storage and auto-sign on receive +- [#1049](https://github.com/cashubtc/cdk/pull/1049) - feat: ldk-node run mintd +- [#1011](https://github.com/cashubtc/cdk/pull/1011) - fix: migrate check_mint_quote_paid fn from ln.rs to mod.rs + +## New + +### Issues + +- [#1249](https://github.com/cashubtc/cdk/issues/1249) - [feature] support CLN remote gRPC and/or REST (not just socket) + +### PRs + +- [#1253](https://github.com/cashubtc/cdk/pull/1253) - feat: P2BK +- [#1252](https://github.com/cashubtc/cdk/pull/1252) - Fix race condition when concurrent payments are processed for the same payment_id +- [#1251](https://github.com/cashubtc/cdk/pull/1251) - feat: custom axum router +- [#1247](https://github.com/cashubtc/cdk/pull/1247) - feat: add keyset_amounts table to track issued and redeemed amounts +- [#1240](https://github.com/cashubtc/cdk/pull/1240) - Introduce KeyManager for the wallet From 52d796e9fe2c0728621110b20dd07b120b862498 Mon Sep 17 00:00:00 2001 From: C Date: Fri, 7 Nov 2025 23:32:07 -0300 Subject: [PATCH 250/321] refactor: replace proof swap with state check in error recovery (#1256) * refactor: replace proof swap with state check in error recovery This commit improves the proof recovery mechanism by replacing the swap operation with a more efficient state check approach when recovering from failed operations. Fixes #1255 * refactor: sync all proof states with mint instead of assuming unspent This commit improves the proof state recovery mechanism to synchronize the actual state from the mint rather than assuming all failed proofs are unspent. * Update crates/cdk/src/wallet/reclaim.rs Co-authored-by: lollerfirst <43107113+lollerfirst@users.noreply.github.com> --- .../tests/fake_wallet.rs | 41 ++--------- crates/cdk/src/wallet/reclaim.rs | 70 ++++++++++++------- 2 files changed, 50 insertions(+), 61 deletions(-) diff --git a/crates/cdk-integration-tests/tests/fake_wallet.rs b/crates/cdk-integration-tests/tests/fake_wallet.rs index 942f8ce6d..31ad50270 100644 --- a/crates/cdk-integration-tests/tests/fake_wallet.rs +++ b/crates/cdk-integration-tests/tests/fake_wallet.rs @@ -54,8 +54,6 @@ async fn test_fake_tokens_pending() { .expect("payment") .expect("no error"); - let old_balance = wallet.total_balance().await.expect("balance"); - let fake_description = FakeInvoiceDescription { pay_invoice_state: MeltQuoteState::Pending, check_payment_state: MeltQuoteState::Pending, @@ -72,12 +70,7 @@ async fn test_fake_tokens_pending() { assert!(melt.is_err()); // melt failed, but there is new code to reclaim unspent proofs - assert_eq!( - old_balance, - wallet.total_balance().await.expect("new balance") - ); - - assert!(wallet + assert!(!wallet .localstore .get_proofs(None, None, Some(vec![State::Pending]), None) .await @@ -139,7 +132,7 @@ async fn test_fake_melt_payment_fail() { assert!(melt.is_err()); let wallet_bal = wallet.total_balance().await.unwrap(); - assert_eq!(wallet_bal, 100.into()); + assert_eq!(wallet_bal, 98.into()); } /// Tests that when both the pay_invoice and check_invoice both fail, @@ -165,8 +158,6 @@ async fn test_fake_melt_payment_fail_and_check() { .expect("payment") .expect("no error"); - let old_balance = wallet.total_balance().await.expect("balance"); - let fake_description = FakeInvoiceDescription { pay_invoice_state: MeltQuoteState::Unknown, check_payment_state: MeltQuoteState::Unknown, @@ -182,13 +173,7 @@ async fn test_fake_melt_payment_fail_and_check() { let melt = wallet.melt(&melt_quote.id).await; assert!(melt.is_err()); - // melt failed, but there is new code to reclaim unspent proofs - assert_eq!( - old_balance, - wallet.total_balance().await.expect("new balance") - ); - - assert!(wallet + assert!(!wallet .localstore .get_proofs(None, None, Some(vec![State::Pending]), None) .await @@ -226,8 +211,6 @@ async fn test_fake_melt_payment_return_fail_status() { check_err: false, }; - let old_balance = wallet.total_balance().await.expect("balance"); - let invoice = create_fake_invoice(7000, serde_json::to_string(&fake_description).unwrap()); let melt_quote = wallet.melt_quote(invoice.to_string(), None).await.unwrap(); @@ -261,14 +244,9 @@ async fn test_fake_melt_payment_return_fail_status() { let melt = wallet.melt(&melt_quote.id).await; assert!(melt.is_err()); - assert_eq!( - old_balance, - wallet.total_balance().await.expect("new balance") - ); - wallet.check_all_pending_proofs().await.unwrap(); - assert!(wallet + assert!(!wallet .localstore .get_proofs(None, None, Some(vec![State::Pending]), None) .await @@ -299,8 +277,6 @@ async fn test_fake_melt_payment_error_unknown() { .expect("payment") .expect("no error"); - let old_balance = wallet.total_balance().await.expect("balance"); - let fake_description = FakeInvoiceDescription { pay_invoice_state: MeltQuoteState::Failed, check_payment_state: MeltQuoteState::Unknown, @@ -331,14 +307,7 @@ async fn test_fake_melt_payment_error_unknown() { let melt = wallet.melt(&melt_quote.id).await; assert!(melt.is_err()); - wallet.check_all_pending_proofs().await.unwrap(); - - assert_eq!( - old_balance, - wallet.total_balance().await.expect("new balance") - ); - - assert!(wallet + assert!(!wallet .localstore .get_proofs(None, None, Some(vec![State::Pending]), None) .await diff --git a/crates/cdk/src/wallet/reclaim.rs b/crates/cdk/src/wallet/reclaim.rs index 648e022ef..8a3e8a75f 100644 --- a/crates/cdk/src/wallet/reclaim.rs +++ b/crates/cdk/src/wallet/reclaim.rs @@ -1,6 +1,10 @@ +use std::collections::HashMap; use std::future::Future; -use crate::nuts::{Proofs, State}; +use cdk_common::{CheckStateRequest, ProofsMethods}; +use tracing::instrument; + +use crate::nuts::Proofs; use crate::{Error, Wallet}; #[cfg(not(target_arch = "wasm32"))] @@ -30,9 +34,42 @@ impl MaybeSend for T {} const BATCH_PROOF_SIZE: usize = 100; impl Wallet { + /// Synchronizes the states with the mint + #[instrument(skip(self, proofs))] + pub async fn sync_proofs_state(&self, proofs: Proofs) -> Result<(), Error> { + let proof_ys = proofs.ys()?; + + let statuses = self + .client + .post_check_state(CheckStateRequest { ys: proof_ys }) + .await? + .states; + + for (state, unspent) in proofs + .into_iter() + .zip(statuses) + .map(|(p, s)| (s.state, p)) + .fold(HashMap::<_, Vec<_>>::new(), |mut acc, (cat, item)| { + acc.entry(cat).or_default().push(item); + acc + }) + { + self.localstore + .update_proofs_state( + unspent + .iter() + .map(|x| x.y()) + .collect::, _>>()?, + state, + ) + .await?; + } + + Ok(()) + } + /// Perform an async task, which is assumed to be a foreign mint call that can fail. If fails, - /// the proofs used in the request are set as unspent, then they are swapped, as they are - /// believed to be already shown to the mint + /// the proofs used in the request are synchronize with the mint and update it locally #[inline(always)] pub(crate) fn try_proof_operation_or_reclaim<'a, F, R>( &'a self, @@ -69,28 +106,11 @@ impl Wallet { inputs.len() ); for proofs in inputs.chunks(BATCH_PROOF_SIZE) { - if let Err(inner_err) = self.reclaim_unspent(proofs.to_owned()).await { - println!( - "Failed to swap exposed proofs ({}), updating local database instead", inner_err - ); - tracing::warn!( - "Failed to swap exposed proofs ({}), updating local database instead", inner_err - ); - - let _ = self - .localstore - .update_proofs_state( - proofs - .iter() - .map(|x| x.y()) - .collect::, _>>()?, - State::Unspent, - ) - .await - .inspect_err(|err| { - tracing::error!("Failed err update_proofs_state {}", err) - }); - } + let _ = self.sync_proofs_state(proofs.to_owned()).await.inspect_err( + |err| { + tracing::warn!("Failed to swap exposed proofs ({})", err); + }, + ); } self.in_error_swap_reverted_proofs From e14469a8fa698a0b0989a6caab631391c7b671ce Mon Sep 17 00:00:00 2001 From: C Date: Tue, 11 Nov 2025 13:39:06 -0300 Subject: [PATCH 251/321] feat: add keyset_amounts table to track issued and redeemed amounts (#1247) Fixes #1130 Introduces a materialized keyset_amounts table to track total issued and redeemed amounts per keyset. This replaces the O(n) approach of querying all proofs/signatures on every call with O(1) lookups. Implementation: - New keyset_amounts table with total_issued and total_redeemed columns - Incremental updates via INSERT...ON CONFLICT upserts for atomicity - Migration backfills existing data from proof and blind_signature tables - Added comprehensive tests for mint, melt, swap, and multi-keyset scenarios --- crates/cdk-common/src/database/mint/mod.rs | 9 + .../tests/integration_tests_pure.rs | 58 ++++ .../tests/test_swap_flow.rs | 299 ++++++++++++++++++ .../20251102000000_create_keyset_amounts.sql | 25 ++ .../20251102000000_create_keyset_amounts.sql | 30 ++ crates/cdk-sql-common/src/mint/mod.rs | 95 ++++++ crates/cdk/src/mint/mod.rs | 42 +-- 7 files changed, 527 insertions(+), 31 deletions(-) create mode 100644 crates/cdk-sql-common/src/mint/migrations/postgres/20251102000000_create_keyset_amounts.sql create mode 100644 crates/cdk-sql-common/src/mint/migrations/sqlite/20251102000000_create_keyset_amounts.sql diff --git a/crates/cdk-common/src/database/mint/mod.rs b/crates/cdk-common/src/database/mint/mod.rs index bf97eacbb..3cf85a1bc 100644 --- a/crates/cdk-common/src/database/mint/mod.rs +++ b/crates/cdk-common/src/database/mint/mod.rs @@ -304,11 +304,15 @@ pub trait ProofsDatabase { ) -> Result, Self::Err>; /// Get [`Proofs`] state async fn get_proofs_states(&self, ys: &[PublicKey]) -> Result>, Self::Err>; + /// Get [`Proofs`] by state async fn get_proofs_by_keyset_id( &self, keyset_id: &Id, ) -> Result<(Proofs, Vec>), Self::Err>; + + /// Get total proofs redeemed by keyset id + async fn get_total_redeemed(&self) -> Result, Self::Err>; } #[async_trait] @@ -343,16 +347,21 @@ pub trait SignaturesDatabase { &self, blinded_messages: &[PublicKey], ) -> Result>, Self::Err>; + /// Get [`BlindSignature`]s for keyset_id async fn get_blind_signatures_for_keyset( &self, keyset_id: &Id, ) -> Result, Self::Err>; + /// Get [`BlindSignature`]s for quote async fn get_blind_signatures_for_quote( &self, quote_id: &QuoteId, ) -> Result, Self::Err>; + + /// Get total amount issued by keyset id + async fn get_total_issued(&self) -> Result, Self::Err>; } #[async_trait] diff --git a/crates/cdk-integration-tests/tests/integration_tests_pure.rs b/crates/cdk-integration-tests/tests/integration_tests_pure.rs index 599f86882..40abf6e20 100644 --- a/crates/cdk-integration-tests/tests/integration_tests_pure.rs +++ b/crates/cdk-integration-tests/tests/integration_tests_pure.rs @@ -183,6 +183,19 @@ async fn test_mint_nut06() { .expect("Failed to get balance"); assert_eq!(Amount::from(64), balance_alice); + // Verify keyset amounts after minting + let keyset_id = mint_bob.pubkeys().keysets.first().unwrap().id; + let total_issued = mint_bob.total_issued().await.unwrap(); + let issued_amount = total_issued + .get(&keyset_id) + .copied() + .unwrap_or(Amount::ZERO); + assert_eq!( + issued_amount, + Amount::from(64), + "Should have issued 64 sats" + ); + let transaction = wallet_alice .list_transactions(None) .await @@ -753,6 +766,28 @@ async fn test_mint_change_with_fee_melt() { .await .expect("Failed to fund wallet"); + let keyset_id = mint_bob.pubkeys().keysets.first().unwrap().id; + + // Check amounts after minting + let total_issued = mint_bob.total_issued().await.unwrap(); + let total_redeemed = mint_bob.total_redeemed().await.unwrap(); + let initial_issued = total_issued.get(&keyset_id).copied().unwrap_or_default(); + let initial_redeemed = total_redeemed + .get(&keyset_id) + .copied() + .unwrap_or(Amount::ZERO); + assert_eq!( + initial_issued, + Amount::from(100), + "Should have issued 100 sats, got {:?}", + total_issued + ); + assert_eq!( + initial_redeemed, + Amount::ZERO, + "Should have redeemed 0 sats initially, " + ); + let proofs = wallet_alice .get_unspent_proofs() .await @@ -771,6 +806,29 @@ async fn test_mint_change_with_fee_melt() { .unwrap(); assert_eq!(w.change.unwrap().total_amount().unwrap(), 97.into()); + + // Check amounts after melting + // Melting redeems 100 sats and issues 97 sats as change + let total_issued = mint_bob.total_issued().await.unwrap(); + let total_redeemed = mint_bob.total_redeemed().await.unwrap(); + let after_issued = total_issued + .get(&keyset_id) + .copied() + .unwrap_or(Amount::ZERO); + let after_redeemed = total_redeemed + .get(&keyset_id) + .copied() + .unwrap_or(Amount::ZERO); + assert_eq!( + after_issued, + Amount::from(197), + "Should have issued 197 sats total (100 initial + 97 change)" + ); + assert_eq!( + after_redeemed, + Amount::from(100), + "Should have redeemed 100 sats from the melt" + ); } /// Tests concurrent double-spending attempts by trying to use the same proofs /// in 3 swap transactions simultaneously using tokio tasks diff --git a/crates/cdk-integration-tests/tests/test_swap_flow.rs b/crates/cdk-integration-tests/tests/test_swap_flow.rs index 2d851e570..8ff99a002 100644 --- a/crates/cdk-integration-tests/tests/test_swap_flow.rs +++ b/crates/cdk-integration-tests/tests/test_swap_flow.rs @@ -58,6 +58,29 @@ async fn test_swap_happy_path() { .expect("Could not get proofs"); let keyset_id = get_keyset_id(&mint).await; + + // Check initial amounts after minting + let total_issued = mint.total_issued().await.unwrap(); + let total_redeemed = mint.total_redeemed().await.unwrap(); + let initial_issued = total_issued + .get(&keyset_id) + .copied() + .unwrap_or(Amount::ZERO); + let initial_redeemed = total_redeemed + .get(&keyset_id) + .copied() + .unwrap_or(Amount::ZERO); + assert_eq!( + initial_issued, + Amount::from(100), + "Should have issued 100 sats" + ); + assert_eq!( + initial_redeemed, + Amount::ZERO, + "Should have redeemed 0 sats initially" + ); + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); // Create swap request for same amount (100 sats) @@ -117,6 +140,29 @@ async fn test_swap_happy_path() { swap_response.signatures.len(), "All signatures should be saved" ); + + // Check keyset amounts after swap + // Swap redeems old proofs (100 sats) and issues new proofs (100 sats) + let total_issued = mint.total_issued().await.unwrap(); + let total_redeemed = mint.total_redeemed().await.unwrap(); + let after_issued = total_issued + .get(&keyset_id) + .copied() + .unwrap_or(Amount::ZERO); + let after_redeemed = total_redeemed + .get(&keyset_id) + .copied() + .unwrap_or(Amount::ZERO); + assert_eq!( + after_issued, + Amount::from(200), + "Should have issued 200 sats total (initial 100 + swap 100)" + ); + assert_eq!( + after_redeemed, + Amount::from(100), + "Should have redeemed 100 sats from the swap" + ); } /// Tests that duplicate blinded messages are rejected: @@ -901,3 +947,256 @@ async fn test_swap_proof_state_consistency() { } } } + +/// Tests that wallet correctly increments keyset counters when receiving proofs +/// from multiple keysets and then performing operations with them. +/// +/// This test validates: +/// 1. Wallet can receive proofs from multiple different keysets +/// 2. Counter is correctly incremented for the target keyset during swap +/// 3. Database maintains separate counters for each keyset +#[tokio::test(flavor = "multi_thread", worker_threads = 1)] +async fn test_wallet_multi_keyset_counter_updates() { + setup_tracing(); + let mint = create_and_start_test_mint() + .await + .expect("Failed to create test mint"); + let wallet = create_test_wallet_for_mint(mint.clone()) + .await + .expect("Failed to create test wallet"); + + // Fund wallet with initial 100 sats using first keyset + fund_wallet(wallet.clone(), 100, None) + .await + .expect("Failed to fund wallet"); + + let first_keyset_id = get_keyset_id(&mint).await; + + // Rotate to a second keyset + mint.rotate_keyset(CurrencyUnit::Sat, 32, 0) + .await + .expect("Failed to rotate keyset"); + + // Wait for keyset rotation to propagate + tokio::time::sleep(std::time::Duration::from_millis(100)).await; + + // Refresh wallet keysets to know about the new keyset + wallet + .refresh_keysets() + .await + .expect("Failed to refresh wallet keysets"); + + // Fund wallet again with 100 sats using second keyset + fund_wallet(wallet.clone(), 100, None) + .await + .expect("Failed to fund wallet with second keyset"); + + let second_keyset_id = mint + .pubkeys() + .keysets + .iter() + .find(|k| k.id != first_keyset_id) + .expect("Should have second keyset") + .id; + + // Verify we now have proofs from two different keysets + let all_proofs = wallet + .get_unspent_proofs() + .await + .expect("Could not get proofs"); + + let keysets_in_use: std::collections::HashSet<_> = + all_proofs.iter().map(|p| p.keyset_id).collect(); + + assert_eq!( + keysets_in_use.len(), + 2, + "Should have proofs from 2 different keysets" + ); + assert!( + keysets_in_use.contains(&first_keyset_id), + "Should have proofs from first keyset" + ); + assert!( + keysets_in_use.contains(&second_keyset_id), + "Should have proofs from second keyset" + ); + + // Get initial total issued and redeemed for both keysets before swap + let total_issued_before = mint.total_issued().await.unwrap(); + let total_redeemed_before = mint.total_redeemed().await.unwrap(); + + let first_keyset_issued_before = total_issued_before + .get(&first_keyset_id) + .copied() + .unwrap_or(Amount::ZERO); + let first_keyset_redeemed_before = total_redeemed_before + .get(&first_keyset_id) + .copied() + .unwrap_or(Amount::ZERO); + + let second_keyset_issued_before = total_issued_before + .get(&second_keyset_id) + .copied() + .unwrap_or(Amount::ZERO); + let second_keyset_redeemed_before = total_redeemed_before + .get(&second_keyset_id) + .copied() + .unwrap_or(Amount::ZERO); + + tracing::info!( + "Before swap - First keyset: issued={}, redeemed={}", + first_keyset_issued_before, + first_keyset_redeemed_before + ); + tracing::info!( + "Before swap - Second keyset: issued={}, redeemed={}", + second_keyset_issued_before, + second_keyset_redeemed_before + ); + + // Both keysets should have issued 100 sats + assert_eq!( + first_keyset_issued_before, + Amount::from(100), + "First keyset should have issued 100 sats" + ); + assert_eq!( + second_keyset_issued_before, + Amount::from(100), + "Second keyset should have issued 100 sats" + ); + // Neither should have redeemed anything yet + assert_eq!( + first_keyset_redeemed_before, + Amount::ZERO, + "First keyset should have redeemed 0 sats before swap" + ); + assert_eq!( + second_keyset_redeemed_before, + Amount::ZERO, + "Second keyset should have redeemed 0 sats before swap" + ); + + // Now perform a swap with all proofs - this should only increment the counter + // for the active (second) keyset, not for the first keyset + let fee_and_amounts = (0, ((0..32).map(|x| 2u64.pow(x)).collect::>())).into(); + + let total_amount = all_proofs.total_amount().expect("Should get total amount"); + + // Create swap using the active (second) keyset + let preswap = PreMintSecrets::random( + second_keyset_id, + total_amount, + &SplitTarget::default(), + &fee_and_amounts, + ) + .expect("Failed to create preswap"); + + let swap_request = SwapRequest::new(all_proofs.clone(), preswap.blinded_messages()); + + // Execute the swap + let swap_response = mint + .process_swap_request(swap_request) + .await + .expect("Swap should succeed"); + + // Verify response + assert_eq!( + swap_response.signatures.len(), + preswap.blinded_messages().len(), + "Should receive signature for each blinded message" + ); + + // All the new proofs should be from the second (active) keyset + let keys = mint + .pubkeys() + .keysets + .iter() + .find(|k| k.id == second_keyset_id) + .expect("Should find second keyset") + .keys + .clone(); + + let new_proofs = construct_proofs( + swap_response.signatures, + preswap.rs(), + preswap.secrets(), + &keys, + ) + .expect("Failed to construct proofs"); + + // Verify all new proofs use the second keyset + for proof in &new_proofs { + assert_eq!( + proof.keyset_id, second_keyset_id, + "All new proofs should use the active (second) keyset" + ); + } + + // Verify total issued and redeemed after swap + let total_issued_after = mint.total_issued().await.unwrap(); + let total_redeemed_after = mint.total_redeemed().await.unwrap(); + + let first_keyset_issued_after = total_issued_after + .get(&first_keyset_id) + .copied() + .unwrap_or(Amount::ZERO); + let first_keyset_redeemed_after = total_redeemed_after + .get(&first_keyset_id) + .copied() + .unwrap_or(Amount::ZERO); + + let second_keyset_issued_after = total_issued_after + .get(&second_keyset_id) + .copied() + .unwrap_or(Amount::ZERO); + let second_keyset_redeemed_after = total_redeemed_after + .get(&second_keyset_id) + .copied() + .unwrap_or(Amount::ZERO); + + tracing::info!( + "After swap - First keyset: issued={}, redeemed={}", + first_keyset_issued_after, + first_keyset_redeemed_after + ); + tracing::info!( + "After swap - Second keyset: issued={}, redeemed={}", + second_keyset_issued_after, + second_keyset_redeemed_after + ); + + // After swap: + // - First keyset: issued stays 100, redeemed increases by 100 (all its proofs were spent in swap) + // - Second keyset: issued increases by 200 (original 100 + new 100 from swap output), + // redeemed increases by 100 (its proofs from first funding were spent) + assert_eq!( + first_keyset_issued_after, + Amount::from(100), + "First keyset issued should stay 100 sats (no new issuance)" + ); + assert_eq!( + first_keyset_redeemed_after, + Amount::from(100), + "First keyset should have redeemed 100 sats (all its proofs spent in swap)" + ); + + assert_eq!( + second_keyset_issued_after, + Amount::from(300), + "Second keyset should have issued 300 sats total (100 initial + 100 the second funding + 100 from swap output from the old keyset)" + ); + assert_eq!( + second_keyset_redeemed_after, + Amount::from(100), + "Second keyset should have redeemed 100 sats (its proofs from initial funding spent in swap)" + ); + + // The test verifies that: + // 1. We can have proofs from multiple keysets in a wallet + // 2. Swap operation processes inputs from any keyset but creates outputs using active keyset + // 3. The keyset_counter table correctly handles counters for different keysets independently + // 4. The database upsert logic in increment_keyset_counter works for multiple keysets + // 5. Total issued and redeemed are tracked correctly per keyset during multi-keyset swaps +} diff --git a/crates/cdk-sql-common/src/mint/migrations/postgres/20251102000000_create_keyset_amounts.sql b/crates/cdk-sql-common/src/mint/migrations/postgres/20251102000000_create_keyset_amounts.sql new file mode 100644 index 000000000..302d7149b --- /dev/null +++ b/crates/cdk-sql-common/src/mint/migrations/postgres/20251102000000_create_keyset_amounts.sql @@ -0,0 +1,25 @@ +-- Create keyset_amounts table with total_issued and total_redeemed columns +CREATE TABLE IF NOT EXISTS keyset_amounts ( + keyset_id TEXT PRIMARY KEY NOT NULL, + total_issued BIGINT NOT NULL DEFAULT 0, + total_redeemed BIGINT NOT NULL DEFAULT 0 +); + +-- Prefill with issued and redeemed amounts using FULL OUTER JOIN +INSERT INTO keyset_amounts (keyset_id, total_issued, total_redeemed) +SELECT + COALESCE(bs.keyset_id, p.keyset_id) as keyset_id, + COALESCE(bs.total_issued, 0) as total_issued, + COALESCE(p.total_redeemed, 0) as total_redeemed +FROM ( + SELECT keyset_id, SUM(amount) as total_issued + FROM blind_signature + WHERE c IS NOT NULL + GROUP BY keyset_id +) bs +FULL OUTER JOIN ( + SELECT keyset_id, SUM(amount) as total_redeemed + FROM proof + WHERE state = 'SPENT' + GROUP BY keyset_id +) p ON bs.keyset_id = p.keyset_id; diff --git a/crates/cdk-sql-common/src/mint/migrations/sqlite/20251102000000_create_keyset_amounts.sql b/crates/cdk-sql-common/src/mint/migrations/sqlite/20251102000000_create_keyset_amounts.sql new file mode 100644 index 000000000..64c631eca --- /dev/null +++ b/crates/cdk-sql-common/src/mint/migrations/sqlite/20251102000000_create_keyset_amounts.sql @@ -0,0 +1,30 @@ +-- Create keyset_amounts table with total_issued and total_redeemed columns +CREATE TABLE IF NOT EXISTS keyset_amounts ( + keyset_id TEXT PRIMARY KEY NOT NULL, + total_issued INTEGER NOT NULL DEFAULT 0, + total_redeemed INTEGER NOT NULL DEFAULT 0 +); + +-- Prefill with issued amounts +INSERT OR IGNORE INTO keyset_amounts (keyset_id, total_issued, total_redeemed) +SELECT keyset_id, SUM(amount) as total_issued, 0 as total_redeemed +FROM blind_signature +WHERE c IS NOT NULL +GROUP BY keyset_id; + +-- Update with redeemed amounts +UPDATE keyset_amounts +SET total_redeemed = ( + SELECT COALESCE(SUM(amount), 0) + FROM proof + WHERE proof.keyset_id = keyset_amounts.keyset_id + AND proof.state = 'SPENT' +); + +-- Insert keysets that only have redeemed amounts (no issued) +INSERT OR IGNORE INTO keyset_amounts (keyset_id, total_issued, total_redeemed) +SELECT keyset_id, 0 as total_issued, SUM(amount) as total_redeemed +FROM proof +WHERE state = 'SPENT' +AND keyset_id NOT IN (SELECT keyset_id FROM keyset_amounts) +GROUP BY keyset_id; diff --git a/crates/cdk-sql-common/src/mint/mod.rs b/crates/cdk-sql-common/src/mint/mod.rs index 92b0a1495..691e29ee8 100644 --- a/crates/cdk-sql-common/src/mint/mod.rs +++ b/crates/cdk-sql-common/src/mint/mod.rs @@ -219,6 +219,23 @@ where .execute(&self.inner) .await?; + if new_state == State::Spent { + query( + r#" + INSERT INTO keyset_amounts (keyset_id, total_issued, total_redeemed) + SELECT keyset_id, 0, COALESCE(SUM(amount), 0) + FROM proof + WHERE y IN (:ys) + GROUP BY keyset_id + ON CONFLICT (keyset_id) + DO UPDATE SET total_redeemed = keyset_amounts.total_redeemed + EXCLUDED.total_redeemed + "#, + )? + .bind_vec("ys", ys.iter().map(|y| y.to_bytes().to_vec()).collect()) + .execute(&self.inner) + .await?; + } + Ok(ys.iter().map(|y| current_states.remove(y)).collect()) } @@ -1618,6 +1635,25 @@ where .into_iter() .unzip()) } + + /// Get total proofs redeemed by keyset id + async fn get_total_redeemed(&self) -> Result, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; + query( + r#" + SELECT + keyset_id, + total_redeemed as amount + FROM + keyset_amounts + "#, + )? + .fetch_all(&*conn) + .await? + .into_iter() + .map(sql_row_to_hashmap_amount) + .collect() + } } #[async_trait] @@ -1698,6 +1734,19 @@ where .bind("signed_time", current_time as i64) .execute(&self.inner) .await?; + + query( + r#" + INSERT INTO keyset_amounts (keyset_id, total_issued, total_redeemed) + VALUES (:keyset_id, :amount, 0) + ON CONFLICT (keyset_id) + DO UPDATE SET total_issued = keyset_amounts.total_issued + EXCLUDED.total_issued + "#, + )? + .bind("amount", u64::from(signature.amount) as i64) + .bind("keyset_id", signature.keyset_id.to_string()) + .execute(&self.inner) + .await?; } Some((c, _dleq_e, _dleq_s)) => { // Blind message exists: check if c is NULL @@ -1725,6 +1774,19 @@ where .bind("amount", u64::from(signature.amount) as i64) .execute(&self.inner) .await?; + + query( + r#" + INSERT INTO keyset_amounts (keyset_id, total_issued, total_redeemed) + VALUES (:keyset_id, :amount, 0) + ON CONFLICT (keyset_id) + DO UPDATE SET total_issued = keyset_amounts.total_issued + EXCLUDED.total_issued + "#, + )? + .bind("amount", u64::from(signature.amount) as i64) + .bind("keyset_id", signature.keyset_id.to_string()) + .execute(&self.inner) + .await?; } _ => { // Blind message already has c: Error @@ -1907,6 +1969,25 @@ where .map(sql_row_to_blind_signature) .collect::, _>>()?) } + + /// Get total proofs redeemed by keyset id + async fn get_total_issued(&self) -> Result, Self::Err> { + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; + query( + r#" + SELECT + keyset_id, + total_issued as amount + FROM + keyset_amounts + "#, + )? + .fetch_all(&*conn) + .await? + .into_iter() + .map(sql_row_to_hashmap_amount) + .collect() + } } #[async_trait] @@ -2482,6 +2563,20 @@ fn sql_row_to_proof(row: Vec) -> Result { }) } +fn sql_row_to_hashmap_amount(row: Vec) -> Result<(Id, Amount), Error> { + unpack_into!( + let ( + keyset_id, amount + ) = row + ); + + let amount: u64 = column_as_number!(amount); + Ok(( + column_as_string!(keyset_id, Id::from_str, Id::from_bytes), + Amount::from(amount), + )) +} + fn sql_row_to_proof_with_state(row: Vec) -> Result<(Proof, Option), Error> { unpack_into!( let ( diff --git a/crates/cdk/src/mint/mod.rs b/crates/cdk/src/mint/mod.rs index 9633e82cd..626515083 100644 --- a/crates/cdk/src/mint/mod.rs +++ b/crates/cdk/src/mint/mod.rs @@ -951,21 +951,10 @@ impl Mint { global::inc_in_flight_requests("total_issued"); let result = async { - let keysets = self.keysets().keysets; - - let mut total_issued = HashMap::new(); - - for keyset in keysets { - let blinded = self - .localstore - .get_blind_signatures_for_keyset(&keyset.id) - .await?; - - let total = Amount::try_sum(blinded.iter().map(|b| b.amount))?; - - total_issued.insert(keyset.id, total); + let mut total_issued = self.localstore.get_total_issued().await?; + for keyset in self.keysets().keysets { + total_issued.entry(keyset.id).or_default(); } - Ok(total_issued) } .await; @@ -985,28 +974,19 @@ impl Mint { #[cfg(feature = "prometheus")] global::inc_in_flight_requests("total_redeemed"); - let keysets = self.signatory.keysets().await?; - - let mut total_redeemed = HashMap::new(); - - for keyset in keysets.keysets { - let (proofs, state) = self.localstore.get_proofs_by_keyset_id(&keyset.id).await?; - - let total_spent = - Amount::try_sum(proofs.iter().zip(state).filter_map(|(p, s)| { - match s == Some(State::Spent) { - true => Some(p.amount), - false => None, - } - }))?; - - total_redeemed.insert(keyset.id, total_spent); + let total_redeemed = async { + let mut total_redeemed = self.localstore.get_total_redeemed().await?; + for keyset in self.keysets().keysets { + total_redeemed.entry(keyset.id).or_default(); + } + Ok(total_redeemed) } + .await; #[cfg(feature = "prometheus")] global::dec_in_flight_requests("total_redeemed"); - Ok(total_redeemed) + total_redeemed } } From 4feed9f6c20294055bcb4599d8b728a63a754371 Mon Sep 17 00:00:00 2001 From: tsk Date: Wed, 12 Nov 2025 05:43:13 -0500 Subject: [PATCH 252/321] mint async melt (#1258) * feat: async melt https://github.com/cashubtc/nuts/pull/285 --- crates/cdk-axum/src/router_handlers.rs | 99 +++++++++++- .../cdk-integration-tests/tests/async_melt.rs | 146 ++++++++++++++++++ crates/cdk/src/mint/melt.rs | 98 ++++++++++++ misc/fake_itests.sh | 15 +- 4 files changed, 353 insertions(+), 5 deletions(-) create mode 100644 crates/cdk-integration-tests/tests/async_melt.rs diff --git a/crates/cdk-axum/src/router_handlers.rs b/crates/cdk-axum/src/router_handlers.rs index ab70e9772..78635a2f6 100644 --- a/crates/cdk-axum/src/router_handlers.rs +++ b/crates/cdk-axum/src/router_handlers.rs @@ -1,6 +1,7 @@ use anyhow::Result; use axum::extract::ws::WebSocketUpgrade; -use axum::extract::{Json, Path, State}; +use axum::extract::{FromRequestParts, Json, Path, State}; +use axum::http::request::Parts; use axum::http::StatusCode; use axum::response::{IntoResponse, Response}; use cdk::error::{ErrorCode, ErrorResponse}; @@ -22,6 +23,46 @@ use crate::auth::AuthHeader; use crate::ws::main_websocket; use crate::MintState; +const PREFER_HEADER_KEY: &str = "Prefer"; + +/// Header extractor for the Prefer header +/// +/// This extractor checks for the `Prefer: respond-async` header +/// to determine if the client wants asynchronous processing +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct PreferHeader { + pub respond_async: bool, +} + +impl FromRequestParts for PreferHeader +where + S: Send + Sync, +{ + type Rejection = (StatusCode, String); + + async fn from_request_parts(parts: &mut Parts, _state: &S) -> Result { + // Check for Prefer header + if let Some(prefer_value) = parts.headers.get(PREFER_HEADER_KEY) { + let value = prefer_value.to_str().map_err(|_| { + ( + StatusCode::BAD_REQUEST, + "Invalid Prefer header value".to_string(), + ) + })?; + + // Check if it contains "respond-async" + let respond_async = value.to_lowercase().contains("respond-async"); + + return Ok(PreferHeader { respond_async }); + } + + // No Prefer header found - default to synchronous processing + Ok(PreferHeader { + respond_async: false, + }) + } +} + /// Macro to add cache to endpoint #[macro_export] macro_rules! post_cache_wrapper { @@ -61,9 +102,50 @@ macro_rules! post_cache_wrapper { }; } +/// Macro to add cache to endpoint with prefer header support (for async operations) +#[macro_export] +macro_rules! post_cache_wrapper_with_prefer { + ($handler:ident, $request_type:ty, $response_type:ty) => { + paste! { + /// Cache wrapper function for $handler with PreferHeader support: + /// Wrap $handler into a function that caches responses using the request as key + pub async fn []( + #[cfg(feature = "auth")] auth: AuthHeader, + prefer: PreferHeader, + state: State, + payload: Json<$request_type> + ) -> Result, Response> { + use std::ops::Deref; + + let json_extracted_payload = payload.deref(); + let State(mint_state) = state.clone(); + let cache_key = match mint_state.cache.calculate_key(&json_extracted_payload) { + Some(key) => key, + None => { + // Could not calculate key, just return the handler result + #[cfg(feature = "auth")] + return $handler(auth, prefer, state, payload).await; + #[cfg(not(feature = "auth"))] + return $handler(prefer, state, payload).await; + } + }; + if let Some(cached_response) = mint_state.cache.get::<$response_type>(&cache_key).await { + return Ok(Json(cached_response)); + } + #[cfg(feature = "auth")] + let response = $handler(auth, prefer, state, payload).await?; + #[cfg(not(feature = "auth"))] + let response = $handler(prefer, state, payload).await?; + mint_state.cache.set(cache_key, &response.deref()).await; + Ok(response) + } + } + }; +} + post_cache_wrapper!(post_swap, SwapRequest, SwapResponse); post_cache_wrapper!(post_mint_bolt11, MintRequest, MintResponse); -post_cache_wrapper!( +post_cache_wrapper_with_prefer!( post_melt_bolt11, MeltRequest, MeltQuoteBolt11Response @@ -382,6 +464,7 @@ pub(crate) async fn get_check_melt_bolt11_quote( #[instrument(skip_all)] pub(crate) async fn post_melt_bolt11( #[cfg(feature = "auth")] auth: AuthHeader, + prefer: PreferHeader, State(state): State, Json(payload): Json>, ) -> Result>, Response> { @@ -397,7 +480,17 @@ pub(crate) async fn post_melt_bolt11( .map_err(into_response)?; } - let res = state.mint.melt(&payload).await.map_err(into_response)?; + let res = if prefer.respond_async { + // Asynchronous processing - return immediately after setup + state + .mint + .melt_async(&payload) + .await + .map_err(into_response)? + } else { + // Synchronous processing - wait for completion + state.mint.melt(&payload).await.map_err(into_response)? + }; Ok(Json(res)) } diff --git a/crates/cdk-integration-tests/tests/async_melt.rs b/crates/cdk-integration-tests/tests/async_melt.rs new file mode 100644 index 000000000..db6733940 --- /dev/null +++ b/crates/cdk-integration-tests/tests/async_melt.rs @@ -0,0 +1,146 @@ +//! Async Melt Integration Tests +//! +//! This file contains tests for async melt functionality using the Prefer: respond-async header. +//! +//! Test Scenarios: +//! - Async melt returns PENDING state immediately +//! - Synchronous melt still works correctly (backward compatibility) +//! - Background task completion +//! - Quote polling pattern + +use std::sync::Arc; + +use bip39::Mnemonic; +use cdk::amount::SplitTarget; +use cdk::nuts::{CurrencyUnit, MeltQuoteState}; +use cdk::wallet::Wallet; +use cdk::StreamExt; +use cdk_fake_wallet::{create_fake_invoice, FakeInvoiceDescription}; +use cdk_sqlite::wallet::memory; + +const MINT_URL: &str = "http://127.0.0.1:8086"; + +/// Test: Async melt returns PENDING state immediately +/// +/// This test validates that when calling melt with Prefer: respond-async header, +/// the mint returns immediately with PENDING state. +#[tokio::test(flavor = "multi_thread", worker_threads = 1)] +async fn test_async_melt_returns_pending() { + let wallet = Wallet::new( + MINT_URL, + CurrencyUnit::Sat, + Arc::new(memory::empty().await.unwrap()), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), + None, + ) + .expect("failed to create new wallet"); + + // Step 1: Mint some tokens + let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); + let mut proof_streams = wallet.proof_stream(mint_quote.clone(), SplitTarget::default(), None); + + let _proofs = proof_streams + .next() + .await + .expect("payment") + .expect("no error"); + + let balance = wallet.total_balance().await.unwrap(); + assert_eq!(balance, 100.into()); + + // Step 2: Create a melt quote + let fake_invoice_description = FakeInvoiceDescription { + pay_invoice_state: MeltQuoteState::Paid, + check_payment_state: MeltQuoteState::Paid, + pay_err: false, + check_err: false, + }; + + let invoice = create_fake_invoice( + 50_000, // 50 sats in millisats + serde_json::to_string(&fake_invoice_description).unwrap(), + ); + + let melt_quote = wallet.melt_quote(invoice.to_string(), None).await.unwrap(); + + // Step 3: Call melt (wallet handles proof selection internally) + let start_time = std::time::Instant::now(); + + // This should complete and return the final state + // TODO: Add Prefer: respond-async header support to wallet.melt() + let melt_response = wallet.melt(&melt_quote.id).await.unwrap(); + + let elapsed = start_time.elapsed(); + + // For now, this is synchronous, so it will take longer + println!("Melt took {:?}", elapsed); + + // Step 4: Verify the melt completed successfully + assert_eq!( + melt_response.state, + MeltQuoteState::Paid, + "Melt should complete with PAID state" + ); +} + +/// Test: Synchronous melt still works correctly +/// +/// This test ensures backward compatibility - melt without Prefer header +/// still blocks until completion and returns the final state. +#[tokio::test(flavor = "multi_thread", worker_threads = 1)] +async fn test_sync_melt_completes_fully() { + let wallet = Wallet::new( + MINT_URL, + CurrencyUnit::Sat, + Arc::new(memory::empty().await.unwrap()), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), + None, + ) + .expect("failed to create new wallet"); + + // Step 1: Mint some tokens + let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); + let mut proof_streams = wallet.proof_stream(mint_quote.clone(), SplitTarget::default(), None); + + let _proofs = proof_streams + .next() + .await + .expect("payment") + .expect("no error"); + + let balance = wallet.total_balance().await.unwrap(); + assert_eq!(balance, 100.into()); + + // Step 2: Create a melt quote + let fake_invoice_description = FakeInvoiceDescription { + pay_invoice_state: MeltQuoteState::Paid, + check_payment_state: MeltQuoteState::Paid, + pay_err: false, + check_err: false, + }; + + let invoice = create_fake_invoice( + 50_000, // 50 sats in millisats + serde_json::to_string(&fake_invoice_description).unwrap(), + ); + + let melt_quote = wallet.melt_quote(invoice.to_string(), None).await.unwrap(); + + // Step 3: Call synchronous melt + let melt_response = wallet.melt(&melt_quote.id).await.unwrap(); + + // Step 5: Verify response shows payment completed + assert_eq!( + melt_response.state, + MeltQuoteState::Paid, + "Synchronous melt should return PAID state" + ); + + // Step 6: Verify the quote is PAID in the mint + let quote_state = wallet.melt_quote_status(&melt_quote.id).await.unwrap(); + assert_eq!( + quote_state.state, + MeltQuoteState::Paid, + "Quote should be PAID" + ); +} diff --git a/crates/cdk/src/mint/melt.rs b/crates/cdk/src/mint/melt.rs index fa0fd74e2..5a7a88054 100644 --- a/crates/cdk/src/mint/melt.rs +++ b/crates/cdk/src/mint/melt.rs @@ -443,4 +443,102 @@ impl Mint { // Step 4: Finalize (TX2 - marks spent, issues change) payment_saga.finalize().await } + + /// Process melt asynchronously - returns immediately after setup with PENDING state + /// + /// This method is called when the client includes the `Prefer: respond-async` header. + /// It performs the setup phase (TX1) to validate and reserve proofs, then spawns a + /// background task to complete the payment and finalization phases. + pub async fn melt_async( + &self, + melt_request: &MeltRequest, + ) -> Result, Error> { + let verification = self.verify_inputs(melt_request.inputs()).await?; + + let init_saga = MeltSaga::new( + std::sync::Arc::new(self.clone()), + self.localstore.clone(), + std::sync::Arc::clone(&self.pubsub_manager), + ); + + let setup_saga = init_saga.setup_melt(melt_request, verification).await?; + + // Get the quote to return with PENDING state + let quote_id = melt_request.quote().clone(); + let quote = self + .localstore + .get_melt_quote("e_id) + .await? + .ok_or(Error::UnknownQuote)?; + + // Spawn background task to complete the melt operation + let melt_request_clone = melt_request.clone(); + let quote_id_clone = quote_id.clone(); + tokio::spawn(async move { + tracing::debug!( + "Starting background melt completion for quote: {}", + quote_id_clone + ); + + // Step 2: Attempt internal settlement + match setup_saga + .attempt_internal_settlement(&melt_request_clone) + .await + { + Ok((setup_saga, settlement)) => { + // Step 3: Make payment + match setup_saga.make_payment(settlement).await { + Ok(payment_saga) => { + // Step 4: Finalize + match payment_saga.finalize().await { + Ok(_) => { + tracing::info!( + "Background melt completed successfully for quote: {}", + quote_id_clone + ); + } + Err(e) => { + tracing::error!( + "Failed to finalize melt for quote {}: {}", + quote_id_clone, + e + ); + } + } + } + Err(e) => { + tracing::error!( + "Failed to make payment for quote {}: {}", + quote_id_clone, + e + ); + } + } + } + Err(e) => { + tracing::error!( + "Failed internal settlement for quote {}: {}", + quote_id_clone, + e + ); + } + } + }); + + debug_assert!(quote.state == MeltQuoteState::Pending); + + // Return immediately with the quote in PENDING state + Ok(MeltQuoteBolt11Response { + quote: quote_id, + amount: quote.amount, + fee_reserve: quote.fee_reserve, + state: quote.state, + paid: Some(false), + expiry: quote.expiry, + payment_preimage: None, + change: None, + request: Some(quote.request.to_string()), + unit: Some(quote.unit), + }) + } } diff --git a/misc/fake_itests.sh b/misc/fake_itests.sh index 0b19062bc..894b02530 100755 --- a/misc/fake_itests.sh +++ b/misc/fake_itests.sh @@ -189,12 +189,23 @@ echo "Running happy_path_mint_wallet test" cargo test -p cdk-integration-tests --test happy_path_mint_wallet status2=$? -# Exit with the status of the second test +# Exit if the second test failed if [ $status2 -ne 0 ]; then echo "Second test failed with status $status2, exiting" exit $status2 fi -# Both tests passed +# Run third test (async_melt) only if previous tests succeeded +echo "Running async_melt test" +cargo test -p cdk-integration-tests --test async_melt +status3=$? + +# Exit with the status of the third test +if [ $status3 -ne 0 ]; then + echo "Third test (async_melt) failed with status $status3, exiting" + exit $status3 +fi + +# All tests passed echo "All tests passed successfully" exit 0 From 9354c2c6989e44c540fec07bc74558e6bf7cc477 Mon Sep 17 00:00:00 2001 From: tsk Date: Wed, 12 Nov 2025 13:33:08 +0000 Subject: [PATCH 253/321] feat(ci): add nightly rustfmt automation with flexible formatting policy (#1260) * feat(ci): add nightly rustfmt automation with flexible formatting policy - Add automated nightly rustfmt workflow that runs daily at midnight UTC - Automatically creates PRs when nightly formatting changes are detected - Switch CI checks to use stable rustfmt to reduce contributor friction - Update DEVELOPMENT.md to document flexible formatting policy - Allow PRs formatted with either stable or nightly rustfmt --- .github/workflows/ci.yml | 11 +--- .github/workflows/nightly-rustfmt.yml | 57 +++++++++++++++++++ DEVELOPMENT.md | 37 ++++++++++++ crates/cdk-ffi/src/types/mint.rs | 8 +-- crates/cdk-integration-tests/tests/bolt12.rs | 2 +- .../tests/test_swap_flow.rs | 2 +- crates/cdk/src/mint/melt/melt_saga/tests.rs | 2 - crates/cdk/src/mint/swap/swap_saga/tests.rs | 15 +++-- crates/cdk/src/test_helpers/mint.rs | 11 +--- crates/cdk/src/test_helpers/mod.rs | 1 - flake.nix | 10 +++- justfile | 8 +-- 12 files changed, 125 insertions(+), 39 deletions(-) create mode 100644 .github/workflows/nightly-rustfmt.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ae9be54c8..199cd8980 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -34,16 +34,11 @@ jobs: - name: Rust Cache uses: Swatinem/rust-cache@v2 with: - shared-key: "nightly-${{ steps.flake-hash.outputs.hash }}" + shared-key: "stable-${{ steps.flake-hash.outputs.hash }}" - name: Cargo fmt - run: | - nix develop -i -L .#nightly --command bash -c ' - # Force use of Nix-provided rustfmt - export RUSTFMT=$(command -v rustfmt) - cargo fmt --check - ' + run: nix develop -i -L .#stable --command cargo fmt --check - name: typos - run: nix develop -i -L .#nightly --command typos + run: nix develop -i -L .#stable --command typos examples: name: "Run examples" diff --git a/.github/workflows/nightly-rustfmt.yml b/.github/workflows/nightly-rustfmt.yml new file mode 100644 index 000000000..bcf970930 --- /dev/null +++ b/.github/workflows/nightly-rustfmt.yml @@ -0,0 +1,57 @@ +name: Nightly rustfmt +on: + schedule: + - cron: "0 0 * * *" # runs daily at 00:00 UTC + workflow_dispatch: # allows manual triggering + +permissions: {} + +jobs: + format: + name: Nightly rustfmt + runs-on: ubuntu-latest + permissions: + contents: write + pull-requests: write + steps: + - uses: actions/checkout@v4 + with: + ref: main + persist-credentials: false + token: ${{ secrets.BACKPORT_TOKEN }} + - name: Get flake hash + id: flake-hash + run: echo "hash=$(sha256sum flake.lock | cut -d' ' -f1 | cut -c1-8)" >> $GITHUB_OUTPUT + - name: Install Nix + uses: DeterminateSystems/nix-installer-action@v17 + - name: Nix Cache + uses: DeterminateSystems/magic-nix-cache-action@main + with: + diagnostic-endpoint: "" + use-flakehub: false + - name: Rust Cache + uses: Swatinem/rust-cache@v2 + with: + shared-key: "nightly-${{ steps.flake-hash.outputs.hash }}" + - name: Run Nightly rustfmt + run: | + nix develop -i -L .#nightly --command bash -c ' + # Force use of Nix-provided rustfmt + export RUSTFMT=$(command -v rustfmt) + cargo +nightly fmt + ' + # Manually remove trailing whitespace + git ls-files -- '*.rs' -z | xargs -0 sed -E -i'' -e 's/[[:space:]]+$//' + - name: Get the current date + run: echo "date=$(date +'%Y-%m-%d')" >> $GITHUB_ENV + - name: Create Pull Request + uses: peter-evans/create-pull-request@271a8d0340265f705b14b6d32b9829c1cb33d45e # v7.0.8 + with: + token: ${{ secrets.BACKPORT_TOKEN }} + author: Fmt Bot + title: Automated nightly rustfmt (${{ env.date }}) + body: | + Automated nightly `rustfmt` changes by [create-pull-request](https://github.com/peter-evans/create-pull-request) GitHub action + commit-message: ${{ env.date }} automated rustfmt nightly + labels: rustfmt + branch: automated-rustfmt-${{ env.date }} diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 61db2d358..6f39f34a2 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -175,6 +175,43 @@ NOTE: if this command fails on macos change the nix channel to unstable (in the just format ``` +## Code Formatting + +CDK uses a flexible rustfmt policy to balance code quality with developer experience: + +### Formatting Requirements for PRs +Pull requests can be formatted with **either stable or nightly** rustfmt - both are accepted: + +- **Stable rustfmt:** Standard Rust formatting (less strict) +- **Nightly rustfmt:** More strict formatting with additional rules + +**Why both are accepted:** +- We prefer nightly rustfmt's stricter formatting +- We don't want to force contributors to install nightly Rust +- This reduces friction for developers using stable toolchains + +```bash +# Format with stable (default) +just format + +# Format with nightly (if you have it installed) +cargo +nightly fmt +``` + +The CI will check your PR with stable rustfmt, so as long as your code passes stable formatting, your PR will pass CI. + +### Automated Nightly Formatting +To keep the codebase consistently formatted with nightly rustfmt over time: + +- **Daily Check:** Every night at midnight UTC, a GitHub Action runs nightly rustfmt on the `main` branch +- **Automated PRs:** If nightly rustfmt produces formatting changes, a PR is automatically created with: + - Title: `Automated nightly rustfmt (YYYY-MM-DD)` + - Label: `rustfmt` + - Author: `Fmt Bot ` +- **Review Process:** These automated PRs are reviewed and merged to keep the codebase aligned with nightly formatting + +This approach ensures the codebase gradually adopts nightly formatting improvements without blocking contributors who use stable Rust. + ### Running Clippy ```bash diff --git a/crates/cdk-ffi/src/types/mint.rs b/crates/cdk-ffi/src/types/mint.rs index 4e1eaef7c..6287beeb2 100644 --- a/crates/cdk-ffi/src/types/mint.rs +++ b/crates/cdk-ffi/src/types/mint.rs @@ -739,12 +739,12 @@ mod tests { let ffi_nuts: Nuts = cdk_nuts.clone().into(); // Verify NUT04 settings - assert_eq!(ffi_nuts.nut04.disabled, false); + assert!(!ffi_nuts.nut04.disabled); assert_eq!(ffi_nuts.nut04.methods.len(), 1); assert_eq!(ffi_nuts.nut04.methods[0].description, Some(true)); // Verify NUT05 settings - assert_eq!(ffi_nuts.nut05.disabled, false); + assert!(!ffi_nuts.nut05.disabled); assert_eq!(ffi_nuts.nut05.methods.len(), 1); assert_eq!(ffi_nuts.nut05.methods[0].amountless, Some(true)); @@ -969,8 +969,8 @@ mod tests { let ffi_nuts: Nuts = cdk_nuts.into(); // Should have collected multiple units - assert!(ffi_nuts.mint_units.len() >= 1); - assert!(ffi_nuts.melt_units.len() >= 1); + assert!(!ffi_nuts.mint_units.is_empty()); + assert!(!ffi_nuts.melt_units.is_empty()); } #[test] diff --git a/crates/cdk-integration-tests/tests/bolt12.rs b/crates/cdk-integration-tests/tests/bolt12.rs index 76d7e8d1f..2c508e292 100644 --- a/crates/cdk-integration-tests/tests/bolt12.rs +++ b/crates/cdk-integration-tests/tests/bolt12.rs @@ -385,7 +385,7 @@ async fn test_regtest_bolt12_mint_extra() -> Result<()> { Err(err) => match err { cdk::Error::TransactionUnbalanced(_, _, _) => (), err => { - bail!("Wrong mint error returned: {}", err.to_string()); + bail!("Wrong mint error returned: {}", err); } }, Ok(_) => { diff --git a/crates/cdk-integration-tests/tests/test_swap_flow.rs b/crates/cdk-integration-tests/tests/test_swap_flow.rs index 8ff99a002..d6f90282d 100644 --- a/crates/cdk-integration-tests/tests/test_swap_flow.rs +++ b/crates/cdk-integration-tests/tests/test_swap_flow.rs @@ -861,7 +861,7 @@ async fn test_swap_state_transition_notifications() { cashu::NotificationPayload::ProofState(cashu::ProofState { y, state, .. }) => { state_transitions .entry(y.to_string()) - .or_insert_with(Vec::new) + .or_default() .push(state); } _ => panic!("Unexpected notification type"), diff --git a/crates/cdk/src/mint/melt/melt_saga/tests.rs b/crates/cdk/src/mint/melt/melt_saga/tests.rs index b92e0df95..8fb7e7c50 100644 --- a/crates/cdk/src/mint/melt/melt_saga/tests.rs +++ b/crates/cdk/src/mint/melt/melt_saga/tests.rs @@ -8,8 +8,6 @@ //! - Concurrent operations //! - Failure handling -#![cfg(test)] - use cdk_common::mint::{MeltSagaState, OperationKind, Saga}; use cdk_common::nuts::MeltQuoteState; use cdk_common::{Amount, ProofsMethods, State}; diff --git a/crates/cdk/src/mint/swap/swap_saga/tests.rs b/crates/cdk/src/mint/swap/swap_saga/tests.rs index 3f398464b..878c16e0b 100644 --- a/crates/cdk/src/mint/swap/swap_saga/tests.rs +++ b/crates/cdk/src/mint/swap/swap_saga/tests.rs @@ -1,4 +1,3 @@ -#![cfg(test)] //! Unit tests for the swap saga implementation //! //! These tests verify the swap saga pattern using in-memory mints and databases, @@ -933,7 +932,7 @@ async fn test_swap_saga_concurrent_swaps() { let task1 = tokio::spawn(async move { let db = mint1.localstore(); let pubsub = mint1.pubsub_manager(); - let saga = SwapSaga::new(&*mint1, db, pubsub); + let saga = SwapSaga::new(&mint1, db, pubsub); let saga = saga .setup_swap(&proofs1, &output_blinded_messages_1, None, verification1) @@ -945,7 +944,7 @@ async fn test_swap_saga_concurrent_swaps() { let task2 = tokio::spawn(async move { let db = mint2.localstore(); let pubsub = mint2.pubsub_manager(); - let saga = SwapSaga::new(&*mint2, db, pubsub); + let saga = SwapSaga::new(&mint2, db, pubsub); let saga = saga .setup_swap(&proofs2, &output_blinded_messages_2, None, verification2) @@ -957,7 +956,7 @@ async fn test_swap_saga_concurrent_swaps() { let task3 = tokio::spawn(async move { let db = mint3.localstore(); let pubsub = mint3.pubsub_manager(); - let saga = SwapSaga::new(&*mint3, db, pubsub); + let saga = SwapSaga::new(&mint3, db, pubsub); let saga = saga .setup_swap(&proofs3, &output_blinded_messages_3, None, verification3) @@ -1976,19 +1975,19 @@ async fn test_operation_id_uniqueness_and_tracking() { { let pubsub = mint.pubsub_manager(); - let saga_1 = SwapSaga::new(&*mint, db.clone(), pubsub.clone()); + let saga_1 = SwapSaga::new(&mint, db.clone(), pubsub.clone()); let _saga_1 = saga_1 .setup_swap(&proofs_1, &outputs_1, None, verification_1) .await .expect("Swap 1 setup should succeed"); - let saga_2 = SwapSaga::new(&*mint, db.clone(), pubsub.clone()); + let saga_2 = SwapSaga::new(&mint, db.clone(), pubsub.clone()); let _saga_2 = saga_2 .setup_swap(&proofs_2, &outputs_2, None, verification_2) .await .expect("Swap 2 setup should succeed"); - let saga_3 = SwapSaga::new(&*mint, db.clone(), pubsub.clone()); + let saga_3 = SwapSaga::new(&mint, db.clone(), pubsub.clone()); let _saga_3 = saga_3 .setup_swap(&proofs_3, &outputs_3, None, verification_3) .await @@ -2033,7 +2032,7 @@ async fn test_operation_id_uniqueness_and_tracking() { let verification = create_verification(amount); let pubsub = mint.pubsub_manager(); - let new_saga = SwapSaga::new(&*mint, db, pubsub); + let new_saga = SwapSaga::new(&mint, db, pubsub); let result = new_saga .setup_swap(&proofs_1, &new_outputs_1, None, verification) diff --git a/crates/cdk/src/test_helpers/mint.rs b/crates/cdk/src/test_helpers/mint.rs index 37f7faba1..17884044c 100644 --- a/crates/cdk/src/test_helpers/mint.rs +++ b/crates/cdk/src/test_helpers/mint.rs @@ -137,11 +137,7 @@ pub async fn mint_test_proofs(mint: &Mint, amount: Amount) -> Result Result) = ( - 0, - keys.iter().map(|a| a.0.to_u64()).collect::>().into(), - ); + let fees: (u64, Vec) = (0, keys.iter().map(|a| a.0.to_u64()).collect::>()); let premint_secrets = PreMintSecrets::random(keysets, amount, &SplitTarget::None, &fees.into()).unwrap(); diff --git a/crates/cdk/src/test_helpers/mod.rs b/crates/cdk/src/test_helpers/mod.rs index 08e0209a2..93eee043e 100644 --- a/crates/cdk/src/test_helpers/mod.rs +++ b/crates/cdk/src/test_helpers/mod.rs @@ -1,4 +1,3 @@ -#![cfg(test)] //! Test helper utilities for CDK unit tests //! //! This module provides shared test utilities for creating test mints, wallets, diff --git a/flake.nix b/flake.nix index 46b1d3279..e121e1eae 100644 --- a/flake.nix +++ b/flake.nix @@ -184,7 +184,15 @@ stable = pkgs.mkShell ( { - shellHook = ''${_shellHook}''; + shellHook = '' + ${_shellHook} + # Needed for github ci + export LD_LIBRARY_PATH=${ + pkgs.lib.makeLibraryPath [ + pkgs.zlib + ] + }:$LD_LIBRARY_PATH + ''; buildInputs = buildInputs ++ [ stable_toolchain ]; inherit nativeBuildInputs; diff --git a/justfile b/justfile index 381cbfe02..1e79e7913 100644 --- a/justfile +++ b/justfile @@ -59,7 +59,7 @@ test: if [ ! -f Cargo.toml ]; then cd {{invocation_directory()}} fi - cargo test --lib + cargo test --lib --workspace --exclude cdk-postgres # Run pure integration tests cargo test -p cdk-integration-tests --test mint @@ -155,11 +155,11 @@ test-nutshell: # run `cargo clippy` on everything -clippy *ARGS="--locked --offline --workspace --all-targets": - cargo clippy {{ARGS}} +clippy *ARGS="--workspace --all-targets": + cargo clippy {{ARGS}} -- -D warnings # run `cargo clippy --fix` on everything -clippy-fix *ARGS="--locked --offline --workspace --all-targets": +clippy-fix *ARGS="--workspace --all-targets": cargo clippy {{ARGS}} --fix typos: From 50cf1d83b99319589ec3a846118e3f33e1411894 Mon Sep 17 00:00:00 2001 From: tsk Date: Wed, 12 Nov 2025 14:04:00 +0000 Subject: [PATCH 254/321] chore: rust version workflow (#1262) --- .github/workflows/update-rust-version.yml | 96 +++++++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 .github/workflows/update-rust-version.yml diff --git a/.github/workflows/update-rust-version.yml b/.github/workflows/update-rust-version.yml new file mode 100644 index 000000000..268545304 --- /dev/null +++ b/.github/workflows/update-rust-version.yml @@ -0,0 +1,96 @@ +name: Update Rust Version + +on: + schedule: + # Run weekly on Monday at 9 AM UTC + - cron: '0 9 * * 1' + workflow_dispatch: # Allow manual triggering + +permissions: {} + +jobs: + check-rust-version: + name: Check and update Rust version + runs-on: ubuntu-latest + permissions: + contents: write + pull-requests: write + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + ref: main + persist-credentials: false + token: ${{ secrets.BACKPORT_TOKEN }} + + - name: Get latest stable Rust version + id: latest-rust + run: | + # Fetch the latest stable Rust version from GitHub releases API + LATEST_VERSION=$(curl -s https://api.github.com/repos/rust-lang/rust/releases | jq -r '[.[] | select(.prerelease == false and .draft == false)][0].tag_name') + echo "version=$LATEST_VERSION" >> $GITHUB_OUTPUT + echo "Latest stable Rust version: $LATEST_VERSION" + + - name: Get current Rust version + id: current-rust + run: | + # Extract current version from rust-toolchain.toml + CURRENT_VERSION=$(grep '^channel=' rust-toolchain.toml | sed 's/channel="\(.*\)"/\1/') + echo "version=$CURRENT_VERSION" >> $GITHUB_OUTPUT + echo "Current Rust version: $CURRENT_VERSION" + + - name: Compare versions + id: compare + run: | + if [ "${{ steps.latest-rust.outputs.version }}" != "${{ steps.current-rust.outputs.version }}" ]; then + echo "needs_update=true" >> $GITHUB_OUTPUT + echo "Rust version needs update: ${{ steps.current-rust.outputs.version }} -> ${{ steps.latest-rust.outputs.version }}" + else + echo "needs_update=false" >> $GITHUB_OUTPUT + echo "Rust version is up to date" + fi + + - name: Update rust-toolchain.toml + if: steps.compare.outputs.needs_update == 'true' + run: | + sed -i 's/channel="[0-9]*\.[0-9]*\.[0-9]*"/channel="${{ steps.latest-rust.outputs.version }}"/' rust-toolchain.toml + echo "Updated rust-toolchain.toml" + + - name: Update flake.nix + if: steps.compare.outputs.needs_update == 'true' + run: | + # Update stable_toolchain version in flake.nix + sed -i 's/stable_toolchain = pkgs\.rust-bin\.stable\."[0-9]*\.[0-9]*\.[0-9]*"\.default/stable_toolchain = pkgs.rust-bin.stable."${{ steps.latest-rust.outputs.version }}".default/' flake.nix + echo "Updated flake.nix" + + - name: Create Pull Request + if: steps.compare.outputs.needs_update == 'true' + uses: peter-evans/create-pull-request@271a8d0340265f705b14b6d32b9829c1cb33d45e # v7.0.8 + with: + token: ${{ secrets.BACKPORT_TOKEN }} + author: Rust Update Bot + title: "chore: update Rust to ${{ steps.latest-rust.outputs.version }}" + body: | + Automated Rust version update from **${{ steps.current-rust.outputs.version }}** to **${{ steps.latest-rust.outputs.version }}**. + + ## Changes + - Updated `rust-toolchain.toml` to use Rust ${{ steps.latest-rust.outputs.version }} + - Updated `flake.nix` stable_toolchain to use Rust ${{ steps.latest-rust.outputs.version }} + + ## Testing + The CI will run all tests with the new Rust version. Please review the test results before merging. + + ## Release Notes + Check the [Rust release notes](https://github.com/rust-lang/rust/blob/master/RELEASES.md) for details on what's new in this version. + + --- + 🤖 Automated changes by [create-pull-request](https://github.com/peter-evans/create-pull-request) GitHub action + commit-message: "chore: update Rust to ${{ steps.latest-rust.outputs.version }}" + labels: rust-version + branch: rust-update-${{ steps.latest-rust.outputs.version }} + + - name: No update needed + if: steps.compare.outputs.needs_update == 'false' + run: | + echo "✓ Rust version is already up to date (${{ steps.current-rust.outputs.version }})" From 5af6976da2a5db1b6b044e69caf1284f9f7dc276 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Wed, 12 Nov 2025 14:22:57 +0000 Subject: [PATCH 255/321] chore: rust version check open issue --- .github/workflows/update-rust-version.yml | 59 ++++++++--------------- 1 file changed, 20 insertions(+), 39 deletions(-) diff --git a/.github/workflows/update-rust-version.yml b/.github/workflows/update-rust-version.yml index 268545304..4af900d73 100644 --- a/.github/workflows/update-rust-version.yml +++ b/.github/workflows/update-rust-version.yml @@ -13,16 +13,11 @@ jobs: name: Check and update Rust version runs-on: ubuntu-latest permissions: - contents: write - pull-requests: write + issues: write steps: - name: Checkout repository uses: actions/checkout@v4 - with: - ref: main - persist-credentials: false - token: ${{ secrets.BACKPORT_TOKEN }} - name: Get latest stable Rust version id: latest-rust @@ -51,44 +46,30 @@ jobs: echo "Rust version is up to date" fi - - name: Update rust-toolchain.toml + - name: Create Issue if: steps.compare.outputs.needs_update == 'true' + env: + GH_TOKEN: ${{ github.token }} run: | - sed -i 's/channel="[0-9]*\.[0-9]*\.[0-9]*"/channel="${{ steps.latest-rust.outputs.version }}"/' rust-toolchain.toml - echo "Updated rust-toolchain.toml" + gh issue create \ + --title "Update Rust to ${{ steps.latest-rust.outputs.version }}" \ + --label "rust-version" \ + --assignee thesimplekid \ + --body "$(cat <<'EOF' + New Rust version **${{ steps.latest-rust.outputs.version }}** is available (currently on **${{ steps.current-rust.outputs.version }}**). - - name: Update flake.nix - if: steps.compare.outputs.needs_update == 'true' - run: | - # Update stable_toolchain version in flake.nix - sed -i 's/stable_toolchain = pkgs\.rust-bin\.stable\."[0-9]*\.[0-9]*\.[0-9]*"\.default/stable_toolchain = pkgs.rust-bin.stable."${{ steps.latest-rust.outputs.version }}".default/' flake.nix - echo "Updated flake.nix" - - - name: Create Pull Request - if: steps.compare.outputs.needs_update == 'true' - uses: peter-evans/create-pull-request@271a8d0340265f705b14b6d32b9829c1cb33d45e # v7.0.8 - with: - token: ${{ secrets.BACKPORT_TOKEN }} - author: Rust Update Bot - title: "chore: update Rust to ${{ steps.latest-rust.outputs.version }}" - body: | - Automated Rust version update from **${{ steps.current-rust.outputs.version }}** to **${{ steps.latest-rust.outputs.version }}**. - - ## Changes - - Updated `rust-toolchain.toml` to use Rust ${{ steps.latest-rust.outputs.version }} - - Updated `flake.nix` stable_toolchain to use Rust ${{ steps.latest-rust.outputs.version }} - - ## Testing - The CI will run all tests with the new Rust version. Please review the test results before merging. + ## Files to update + - \`rust-toolchain.toml\` - Update channel to \`${{ steps.latest-rust.outputs.version }}\` + - \`flake.nix\` - Update stable_toolchain to \`pkgs.rust-bin.stable."${{ steps.latest-rust.outputs.version }}".default\` + - Run \`nix flake update rust-overlay\` to update \`flake.lock\` - ## Release Notes - Check the [Rust release notes](https://github.com/rust-lang/rust/blob/master/RELEASES.md) for details on what's new in this version. + ## Release Notes + Check the [Rust release notes](https://github.com/rust-lang/rust/blob/master/RELEASES.md) for details on what's new in this version. - --- - 🤖 Automated changes by [create-pull-request](https://github.com/peter-evans/create-pull-request) GitHub action - commit-message: "chore: update Rust to ${{ steps.latest-rust.outputs.version }}" - labels: rust-version - branch: rust-update-${{ steps.latest-rust.outputs.version }} + --- + 🤖 Automated issue created by update-rust-version workflow + EOF + )" - name: No update needed if: steps.compare.outputs.needs_update == 'false' From 0f1f2fe5a0aa1aea545e84220bc24741b85642d0 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 12 Nov 2025 17:01:49 +0000 Subject: [PATCH 256/321] chore: add weekly meeting agenda for 2025-11-12 (#1261) Co-authored-by: github-actions[bot] --- meetings/2025-11-12-agenda.md | 54 +++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 meetings/2025-11-12-agenda.md diff --git a/meetings/2025-11-12-agenda.md b/meetings/2025-11-12-agenda.md new file mode 100644 index 000000000..3fd8494f6 --- /dev/null +++ b/meetings/2025-11-12-agenda.md @@ -0,0 +1,54 @@ +# CDK Development Meeting + +Nov 12 2025 15:00 UTC + +Meeting Link: https://meet.fulmo.org/cdk-dev + +## Merged + +- [#1258](https://github.com/cashubtc/cdk/pull/1258) - mint async melt +- [#1256](https://github.com/cashubtc/cdk/pull/1256) - refactor: replace proof swap with state check in error recovery +- [#1254](https://github.com/cashubtc/cdk/pull/1254) - Weekly Meeting Agenda - 2025-11-05 +- [#1247](https://github.com/cashubtc/cdk/pull/1247) - feat: add keyset_amounts table to track issued and redeemed amounts + +## Ongoing + +- [#1253](https://github.com/cashubtc/cdk/pull/1253) - feat: P2BK +- [#1252](https://github.com/cashubtc/cdk/pull/1252) - Fix race condition when concurrent payments are processed for the same payment_id +- [#1251](https://github.com/cashubtc/cdk/pull/1251) - feat: custom axum router +- [#1240](https://github.com/cashubtc/cdk/pull/1240) - Introduce MintMetadataCache for efficient key and metadata management +- [#1214](https://github.com/cashubtc/cdk/pull/1214) - feat(cdk-payment-processor): add currency unit parameter to make_payment +- [#1212](https://github.com/cashubtc/cdk/pull/1212) - Various mint bugfixes for swap and melt. SIG_INPUTS+SIG_ALL, locktimes, P2PK+HTLC. Also updates the SIG_ALL message for amount-switching +- [#1211](https://github.com/cashubtc/cdk/pull/1211) - Regtest setup +- [#1210](https://github.com/cashubtc/cdk/pull/1210) - test: add mutation testing infrastructure +- [#1208](https://github.com/cashubtc/cdk/pull/1208) - Sig all fixes +- [#1204](https://github.com/cashubtc/cdk/pull/1204) - Add database transaction trait for cdk wallet +- [#1202](https://github.com/cashubtc/cdk/pull/1202) - Onchain +- [#1201](https://github.com/cashubtc/cdk/pull/1201) - feat: npubcash +- [#1200](https://github.com/cashubtc/cdk/pull/1200) - feat: optimize pending mint quotes query performance +- [#1198](https://github.com/cashubtc/cdk/pull/1198) - fix: check the removed_ys argument before creating the delete query +- [#1196](https://github.com/cashubtc/cdk/pull/1196) - feat(ci): add merge queue workflow and simplify clippy checks +- [#1190](https://github.com/cashubtc/cdk/pull/1190) - feat(cashu): add NUT-26 bech32m encoding for payment requests +- [#1182](https://github.com/cashubtc/cdk/pull/1182) - ehash: add support for mining share mint quotes +- [#1181](https://github.com/cashubtc/cdk/pull/1181) - Deterministic Currency Unit Derivation Paths +- [#1171](https://github.com/cashubtc/cdk/pull/1171) - Add Dart Bindings Support +- [#1153](https://github.com/cashubtc/cdk/pull/1153) - Add cdk-mintd module and package +- [#1132](https://github.com/cashubtc/cdk/pull/1132) - Quote id as lookup +- [#1127](https://github.com/cashubtc/cdk/pull/1127) - rename ln settings in toml configuration +- [#1118](https://github.com/cashubtc/cdk/pull/1118) - feat: uniffi bindings for golang +- [#1100](https://github.com/cashubtc/cdk/pull/1100) - NUT-XX: Cairo Spending Conditions implementation +- [#1067](https://github.com/cashubtc/cdk/pull/1067) - Nutxx ohttp +- [#1053](https://github.com/cashubtc/cdk/pull/1053) - feat: P2PK key storage and auto-sign on receive +- [#1049](https://github.com/cashubtc/cdk/pull/1049) - feat: ldk-node run mintd +- [#1011](https://github.com/cashubtc/cdk/pull/1011) - fix: migrate check_mint_quote_paid fn from ln.rs to mod.rs + +## New + +### Issues + +- [#1259](https://github.com/cashubtc/cdk/issues/1259) - Suggested changes in the payment_processor.proto declaration + +### PRs + +- [#1260](https://github.com/cashubtc/cdk/pull/1260) - feat(ci): add nightly rustfmt automation with flexible formatting policy +- [#1257](https://github.com/cashubtc/cdk/pull/1257) - bring signatory up to date with the remote signer spec From f989fb784d7015abefceea972944e491de042cf5 Mon Sep 17 00:00:00 2001 From: tsk Date: Wed, 12 Nov 2025 17:02:04 +0000 Subject: [PATCH 257/321] chore: update stable rust to 1.91.1 (#1265) --- flake.lock | 36 ++++++++++++++++++------------------ flake.nix | 2 +- rust-toolchain.toml | 2 +- 3 files changed, 20 insertions(+), 20 deletions(-) diff --git a/flake.lock b/flake.lock index 186800f7b..5ce14f10a 100644 --- a/flake.lock +++ b/flake.lock @@ -2,11 +2,11 @@ "nodes": { "crane": { "locked": { - "lastModified": 1760924934, - "narHash": "sha256-tuuqY5aU7cUkR71sO2TraVKK2boYrdW3gCSXUkF4i44=", + "lastModified": 1762538466, + "narHash": "sha256-8zrIPl6J+wLm9MH5ksHcW7BUHo7jSNOu0/hA0ohOOaM=", "owner": "ipetkov", "repo": "crane", - "rev": "c6b4d5308293d0d04fcfeee92705017537cad02f", + "rev": "0cea393fffb39575c46b7a0318386467272182fe", "type": "github" }, "original": { @@ -23,11 +23,11 @@ "rust-analyzer-src": [] }, "locked": { - "lastModified": 1761287960, - "narHash": "sha256-DbGYVbF0TgoKTFNQv/3jqaUWql8OYzewl4v2gw6jmQs=", + "lastModified": 1762929886, + "narHash": "sha256-TQZ3Ugb1FoHpTSc8KLrzN4njIZU4FemAMHyS4M3mt6s=", "owner": "nix-community", "repo": "fenix", - "rev": "64cb168ed9ec61ef18e28f1e4ee9f44381d6ecd2", + "rev": "6998514dce2c365142a0a119a95ef95d89b84086", "type": "github" }, "original": { @@ -93,11 +93,11 @@ }, "nixpkgs": { "locked": { - "lastModified": 1761173472, - "narHash": "sha256-m9W0dYXflzeGgKNravKJvTMR4Qqa2MVD11AwlGMufeE=", + "lastModified": 1762756533, + "narHash": "sha256-HiRDeUOD1VLklHeOmaKDzf+8Hb7vSWPVFcWwaTrpm+U=", "owner": "NixOS", "repo": "nixpkgs", - "rev": "c8aa8cc00a5cb57fada0851a038d35c08a36a2bb", + "rev": "c2448301fb856e351aab33e64c33a3fc8bcf637d", "type": "github" }, "original": { @@ -109,11 +109,11 @@ }, "nixpkgs_2": { "locked": { - "lastModified": 1759070547, - "narHash": "sha256-JVZl8NaVRYb0+381nl7LvPE+A774/dRpif01FKLrYFQ=", + "lastModified": 1759417375, + "narHash": "sha256-O7eHcgkQXJNygY6AypkF9tFhsoDQjpNEojw3eFs73Ow=", "owner": "NixOS", "repo": "nixpkgs", - "rev": "647e5c14cbd5067f44ac86b74f014962df460840", + "rev": "dc704e6102e76aad573f63b74c742cd96f8f1e6c", "type": "github" }, "original": { @@ -130,11 +130,11 @@ "nixpkgs": "nixpkgs_2" }, "locked": { - "lastModified": 1760663237, - "narHash": "sha256-BflA6U4AM1bzuRMR8QqzPXqh8sWVCNDzOdsxXEguJIc=", + "lastModified": 1762868777, + "narHash": "sha256-QqS72GvguP56oKDNUckWUPNJHjsdeuXh5RyoKz0wJ+E=", "owner": "cachix", "repo": "pre-commit-hooks.nix", - "rev": "ca5b894d3e3e151ffc1db040b6ce4dcc75d31c37", + "rev": "c5c3147730384576196fb5da048a6e45dee10d56", "type": "github" }, "original": { @@ -160,11 +160,11 @@ ] }, "locked": { - "lastModified": 1761273263, - "narHash": "sha256-6d6ojnu6A6sVxIjig8OL6E1T8Ge9st3YGgVwg5MOY+Q=", + "lastModified": 1762915112, + "narHash": "sha256-d9j1g8nKmYDHy+/bIOPQTh9IwjRliqaTM0QLHMV92Ic=", "owner": "oxalica", "repo": "rust-overlay", - "rev": "28405834d4fdd458d28e123fae4db148daecec6f", + "rev": "aa1e85921cfa04de7b6914982a94621fbec5cc02", "type": "github" }, "original": { diff --git a/flake.nix b/flake.nix index e121e1eae..ce2cc72cb 100644 --- a/flake.nix +++ b/flake.nix @@ -56,7 +56,7 @@ # Toolchains # latest stable - stable_toolchain = pkgs.rust-bin.stable."1.90.0".default.override { + stable_toolchain = pkgs.rust-bin.stable."1.91.1".default.override { targets = [ "wasm32-unknown-unknown" ]; # wasm extensions = [ "rustfmt" diff --git a/rust-toolchain.toml b/rust-toolchain.toml index e34c54e64..b7b8acf2f 100644 --- a/rust-toolchain.toml +++ b/rust-toolchain.toml @@ -1,4 +1,4 @@ [toolchain] -channel="1.90.0" +channel="1.91.1" components = ["rustfmt", "clippy", "rust-analyzer"] From d002481eb67e7f2ffd44ce8dd7d75a6f00bac446 Mon Sep 17 00:00:00 2001 From: asmo Date: Wed, 12 Nov 2025 18:08:58 +0100 Subject: [PATCH 258/321] fix: check the removed_ys argument before creating the delete query (#1198) --- crates/cdk-sql-common/src/wallet/mod.rs | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/crates/cdk-sql-common/src/wallet/mod.rs b/crates/cdk-sql-common/src/wallet/mod.rs index e524776e4..6ce3fb87a 100644 --- a/crates/cdk-sql-common/src/wallet/mod.rs +++ b/crates/cdk-sql-common/src/wallet/mod.rs @@ -779,14 +779,15 @@ ON CONFLICT(id) DO UPDATE SET ) .execute(&tx).await?; } - - query(r#"DELETE FROM proof WHERE y IN (:ys)"#)? - .bind_vec( - "ys", - removed_ys.iter().map(|y| y.to_bytes().to_vec()).collect(), - ) - .execute(&tx) - .await?; + if !removed_ys.is_empty() { + query(r#"DELETE FROM proof WHERE y IN (:ys)"#)? + .bind_vec( + "ys", + removed_ys.iter().map(|y| y.to_bytes().to_vec()).collect(), + ) + .execute(&tx) + .await?; + } tx.commit().await?; From 2f0ff7fe9e3f0b4c25b25c3bf7290719eb47fc18 Mon Sep 17 00:00:00 2001 From: tsk Date: Wed, 12 Nov 2025 22:35:04 +0000 Subject: [PATCH 259/321] chore: meeting agenda fmt (#1266) --- .github/scripts/generate-agenda.sh | 44 ++++++++++++++++++++++++------ 1 file changed, 35 insertions(+), 9 deletions(-) diff --git a/.github/scripts/generate-agenda.sh b/.github/scripts/generate-agenda.sh index 5416615d1..432dd95f3 100755 --- a/.github/scripts/generate-agenda.sh +++ b/.github/scripts/generate-agenda.sh @@ -37,13 +37,14 @@ MERGED_PRS=$(gh pr list \ --jq '.[] | [.number, .title, .url] | @tsv' \ 2>/dev/null || echo "") -# Fetch ongoing (open) PRs -echo "Fetching ongoing PRs..." -ONGOING_PRS=$(gh pr list \ +# Fetch recently active PRs (updated in last week, but not newly created) +echo "Fetching recently active PRs..." +RECENTLY_ACTIVE_PRS=$(gh pr list \ --repo "$REPO" \ --state open \ - --json number,title,url,createdAt \ - --jq '.[] | select(.createdAt < "'$SINCE_DATE'") | [.number, .title, .url] | @tsv' \ + --search "updated:>=$SINCE_DATE -created:>=$SINCE_DATE" \ + --json number,title,url \ + --jq '.[] | [.number, .title, .url] | @tsv' \ 2>/dev/null || echo "") # Fetch new PRs (opened in the last week) @@ -66,6 +67,27 @@ NEW_ISSUES=$(gh issue list \ --jq '.[] | [.number, .title, .url] | @tsv' \ 2>/dev/null || echo "") +# Fetch discussion items (labeled with meeting-discussion) +echo "Fetching discussion items..." +DISCUSSION_PRS=$(gh pr list \ + --repo "$REPO" \ + --state open \ + --label "meeting-discussion" \ + --json number,title,url \ + --jq '.[] | [.number, .title, .url] | @tsv' \ + 2>/dev/null || echo "") + +DISCUSSION_ISSUES=$(gh issue list \ + --repo "$REPO" \ + --state open \ + --label "meeting-discussion" \ + --json number,title,url \ + --jq '.[] | [.number, .title, .url] | @tsv' \ + 2>/dev/null || echo "") + +# Combine discussion items (PRs and issues) +DISCUSSION_ITEMS=$(printf "%s\n%s" "$DISCUSSION_PRS" "$DISCUSSION_ISSUES" | grep -v '^$' || echo "") + # Generate markdown AGENDA=$(cat < Date: Thu, 13 Nov 2025 07:58:14 -0300 Subject: [PATCH 260/321] Introduce MintMetadataCache for efficient key and metadata management (#1240) This commit introduces a new MintMetadataCache subsystem that centralizes mint metadata (keys, keysets, and mint info) management with in-memory caching, deferred database persistence, and lock-free read access. This architectural change eliminates redundant database queries, reduces mint server load, and improves wallet performance. Previous Architecture Each wallet independently queried the database and mint server for keys: - Duplicate HTTP requests to mint servers - No coordination between wallets sharing the same mint - Blocking I/O on every key access New Architecture MintMetadataCache provides per-mint caching with: - Single source of truth for all mint metadata - Lock-free reads via ArcSwap (zero contention) - Deferred database writes (non-blocking) - Mutex-based fetch coordination (prevents duplicate HTTP requests) - Multi-database support (tracks sync status per storage instance) Key Design Decisions Pull-based loading instead of background workers: - load() - Returns cached data if available, fetches if not - load_from_mint() - Always fetches fresh data from mint server - load_auth() - Fetches blind auth keysets (when auth feature enabled) Deferred persistence: - Database writes spawn in background after cache update - Cache is source of truth, not database - Tracks which databases have been synced via pointer identity Fetch coordination: - Mutex ensures only one HTTP fetch runs at a time - Waiting threads check if cache was updated while waiting - Avoids redundant fetches when multiple callers request simultaneously Implementation Details - 327 lines added to new mint_metadata_cache.rs module - Updated Wallet methods to use new cache API - Removed synchronous polling patterns in favor of explicit load calls - Added per-wallet TTL configuration via set_metadata_cache_ttl() Benefits - Eliminates duplicate HTTP requests across wallets - Reduces database query load - Improves response time through in-memory caching - Better resource utilization (memory-efficient shared state) - Clearer separation between cache-first (load) and fetch-first (load_from_mint) semantics --- crates/cdk-common/src/lib.rs | 3 + crates/cdk-common/src/mint.rs | 6 +- crates/cdk-common/src/pub_sub/pubsub.rs | 17 +- .../cdk-common/src/pub_sub/remote_consumer.rs | 10 +- crates/cdk-common/src/task.rs | 25 + crates/cdk-redb/src/wallet/mod.rs | 4 +- crates/cdk-sql-common/build.rs | 5 +- crates/cdk-sql-common/src/mint/mod.rs | 14 +- crates/cdk-sql-common/src/stmt.rs | 12 + .../20251111000000_keyset_counter_table.sql | 15 + .../20251111000000_keyset_counter_table.sql | 36 + crates/cdk-sql-common/src/wallet/mod.rs | 19 +- crates/cdk/examples/proof-selection.rs | 2 +- crates/cdk/src/wallet/auth/auth_wallet.rs | 136 ++-- crates/cdk/src/wallet/builder.rs | 71 +- crates/cdk/src/wallet/issue/issue_bolt11.rs | 4 - crates/cdk/src/wallet/issue/issue_bolt12.rs | 4 - crates/cdk/src/wallet/keysets.rs | 207 +++--- crates/cdk/src/wallet/melt/melt_bolt11.rs | 4 +- crates/cdk/src/wallet/mint_metadata_cache.rs | 616 ++++++++++++++++++ crates/cdk/src/wallet/mod.rs | 32 +- crates/cdk/src/wallet/multi_mint_wallet.rs | 34 +- crates/cdk/src/wallet/receive.rs | 2 - crates/cdk/src/wallet/swap.rs | 16 +- misc/fake_itests.sh | 4 +- 25 files changed, 1008 insertions(+), 290 deletions(-) create mode 100644 crates/cdk-common/src/task.rs create mode 100644 crates/cdk-sql-common/src/wallet/migrations/postgres/20251111000000_keyset_counter_table.sql create mode 100644 crates/cdk-sql-common/src/wallet/migrations/sqlite/20251111000000_keyset_counter_table.sql create mode 100644 crates/cdk/src/wallet/mint_metadata_cache.rs diff --git a/crates/cdk-common/src/lib.rs b/crates/cdk-common/src/lib.rs index 9db301f55..dabc4f93b 100644 --- a/crates/cdk-common/src/lib.rs +++ b/crates/cdk-common/src/lib.rs @@ -8,6 +8,8 @@ #![warn(missing_docs)] #![warn(rustdoc::bare_urls)] +pub mod task; + pub mod common; pub mod database; pub mod error; @@ -24,6 +26,7 @@ pub mod subscription; #[cfg(feature = "wallet")] pub mod wallet; pub mod ws; + // re-exporting external crates pub use bitcoin; pub use cashu::amount::{self, Amount}; diff --git a/crates/cdk-common/src/mint.rs b/crates/cdk-common/src/mint.rs index d5216edb7..8225779c2 100644 --- a/crates/cdk-common/src/mint.rs +++ b/crates/cdk-common/src/mint.rs @@ -49,7 +49,7 @@ impl FromStr for OperationKind { "swap" => Ok(OperationKind::Swap), "mint" => Ok(OperationKind::Mint), "melt" => Ok(OperationKind::Melt), - _ => Err(Error::Custom(format!("Invalid operation kind: {}", value))), + _ => Err(Error::Custom(format!("Invalid operation kind: {value}"))), } } } @@ -80,7 +80,7 @@ impl FromStr for SwapSagaState { match value.as_str() { "setup_complete" => Ok(SwapSagaState::SetupComplete), "signed" => Ok(SwapSagaState::Signed), - _ => Err(Error::Custom(format!("Invalid swap saga state: {}", value))), + _ => Err(Error::Custom(format!("Invalid swap saga state: {value}"))), } } } @@ -279,7 +279,7 @@ impl Operation { "mint" => Ok(Self::Mint(uuid)), "melt" => Ok(Self::Melt(uuid)), "swap" => Ok(Self::Swap(uuid)), - _ => Err(Error::Custom(format!("Invalid operation kind: {}", kind))), + _ => Err(Error::Custom(format!("Invalid operation kind: {kind}"))), } } } diff --git a/crates/cdk-common/src/pub_sub/pubsub.rs b/crates/cdk-common/src/pub_sub/pubsub.rs index fff71ef17..45f81d55e 100644 --- a/crates/cdk-common/src/pub_sub/pubsub.rs +++ b/crates/cdk-common/src/pub_sub/pubsub.rs @@ -10,6 +10,7 @@ use tokio::sync::mpsc; use super::subscriber::{ActiveSubscription, SubscriptionRequest}; use super::{Error, Event, Spec, Subscriber}; +use crate::task::spawn; /// Default channel size for subscription buffering pub const DEFAULT_CHANNEL_SIZE: usize = 10_000; @@ -92,13 +93,7 @@ where let topics = self.listeners_topics.clone(); let event = event.into(); - #[cfg(not(target_arch = "wasm32"))] - tokio::spawn(async move { - let _ = Self::publish_internal(event, &topics); - }); - - #[cfg(target_arch = "wasm32")] - wasm_bindgen_futures::spawn_local(async move { + spawn(async move { let _ = Self::publish_internal(event, &topics); }); } @@ -150,17 +145,11 @@ where let inner = self.inner.clone(); let subscribed_to_for_spawn = subscribed_to.clone(); - #[cfg(not(target_arch = "wasm32"))] - tokio::spawn(async move { + spawn(async move { // TODO: Ignore topics broadcasted from fetch_events _if_ any real time has been broadcasted already. inner.fetch_events(subscribed_to_for_spawn, sender).await; }); - #[cfg(target_arch = "wasm32")] - wasm_bindgen_futures::spawn_local(async move { - inner.fetch_events(subscribed_to_for_spawn, sender).await; - }); - Ok(ActiveSubscription::new( subscription_internal_id, subscription_name, diff --git a/crates/cdk-common/src/pub_sub/remote_consumer.rs b/crates/cdk-common/src/pub_sub/remote_consumer.rs index b7ad9710d..597915ba5 100644 --- a/crates/cdk-common/src/pub_sub/remote_consumer.rs +++ b/crates/cdk-common/src/pub_sub/remote_consumer.rs @@ -12,6 +12,7 @@ use tokio::time::{sleep, Instant}; use super::subscriber::{ActiveSubscription, SubscriptionRequest}; use super::{Error, Event, Pubsub, Spec}; +use crate::task::spawn; const STREAM_CONNECTION_BACKOFF: Duration = Duration::from_millis(2_000); @@ -21,9 +22,6 @@ const INTERNAL_POLL_SIZE: usize = 1_000; const POLL_SLEEP: Duration = Duration::from_millis(2_000); -#[cfg(target_arch = "wasm32")] -use wasm_bindgen_futures; - struct UniqueSubscription where S: Spec, @@ -157,11 +155,7 @@ where still_running: true.into(), }); - #[cfg(not(target_arch = "wasm32"))] - tokio::spawn(Self::stream(this.clone())); - - #[cfg(target_arch = "wasm32")] - wasm_bindgen_futures::spawn_local(Self::stream(this.clone())); + spawn(Self::stream(this.clone())); this } diff --git a/crates/cdk-common/src/task.rs b/crates/cdk-common/src/task.rs new file mode 100644 index 000000000..8efe51324 --- /dev/null +++ b/crates/cdk-common/src/task.rs @@ -0,0 +1,25 @@ +//! Thin wrapper for spawn and spawn_local for native and wasm. + +use std::future::Future; + +use tokio::task::JoinHandle; + +/// Spawns a new asynchronous task returning nothing +#[cfg(not(target_arch = "wasm32"))] +pub fn spawn(future: F) -> JoinHandle +where + F: Future + Send + 'static, + F::Output: Send + 'static, +{ + tokio::spawn(future) +} + +/// Spawns a new asynchronous task returning nothing +#[cfg(target_arch = "wasm32")] +pub fn spawn(future: F) -> JoinHandle +where + F: Future + 'static, + F::Output: 'static, +{ + tokio::task::spawn_local(future) +} diff --git a/crates/cdk-redb/src/wallet/mod.rs b/crates/cdk-redb/src/wallet/mod.rs index e4484c2a8..40b7eb1f9 100644 --- a/crates/cdk-redb/src/wallet/mod.rs +++ b/crates/cdk-redb/src/wallet/mod.rs @@ -63,7 +63,7 @@ impl WalletRedbDatabase { if !parent.exists() { return Err(Error::Io(std::io::Error::new( std::io::ErrorKind::NotFound, - format!("Parent directory does not exist: {:?}", parent), + format!("Parent directory does not exist: {parent:?}"), ))); } } @@ -171,7 +171,7 @@ impl WalletRedbDatabase { if !parent.exists() { return Err(Error::Io(std::io::Error::new( std::io::ErrorKind::NotFound, - format!("Parent directory does not exist: {:?}", parent), + format!("Parent directory does not exist: {parent:?}"), ))); } } diff --git a/crates/cdk-sql-common/build.rs b/crates/cdk-sql-common/build.rs index 3a8890133..46fe78927 100644 --- a/crates/cdk-sql-common/build.rs +++ b/crates/cdk-sql-common/build.rs @@ -23,7 +23,7 @@ fn main() { .unwrap_or("default") .replace("/", "_") .replace("\\", "_"); - let dest_path = out_dir.join(format!("migrations_{}.rs", migration_name)); + let dest_path = out_dir.join(format!("migrations_{migration_name}.rs")); let mut out_file = File::create(&dest_path).expect("Failed to create migrations.rs"); let skip_name = migration_path.to_str().unwrap_or_default().len(); @@ -115,8 +115,7 @@ fn main() { let relative_to_out_dir = relative_path.to_str().unwrap().replace("\\", "/"); writeln!( out_file, - " (\"{prefix}\", \"{rel_name}\", include_str!(r#\"{}\"#)),", - relative_to_out_dir + " (\"{prefix}\", \"{rel_name}\", include_str!(r#\"{relative_to_out_dir}\"#))," ) .unwrap(); println!("cargo:rerun-if-changed={}", path.display()); diff --git a/crates/cdk-sql-common/src/mint/mod.rs b/crates/cdk-sql-common/src/mint/mod.rs index 691e29ee8..a587726c3 100644 --- a/crates/cdk-sql-common/src/mint/mod.rs +++ b/crates/cdk-sql-common/src/mint/mod.rs @@ -2248,10 +2248,10 @@ where let current_time = unix_time(); let blinded_secrets_json = serde_json::to_string(&saga.blinded_secrets) - .map_err(|e| Error::Internal(format!("Failed to serialize blinded_secrets: {}", e)))?; + .map_err(|e| Error::Internal(format!("Failed to serialize blinded_secrets: {e}")))?; let input_ys_json = serde_json::to_string(&saga.input_ys) - .map_err(|e| Error::Internal(format!("Failed to serialize input_ys: {}", e)))?; + .map_err(|e| Error::Internal(format!("Failed to serialize input_ys: {e}")))?; query( r#" @@ -2645,23 +2645,23 @@ fn sql_row_to_saga(row: Vec) -> Result { let operation_id_str = column_as_string!(&operation_id); let operation_id = uuid::Uuid::parse_str(&operation_id_str) - .map_err(|e| Error::Internal(format!("Invalid operation_id UUID: {}", e)))?; + .map_err(|e| Error::Internal(format!("Invalid operation_id UUID: {e}")))?; let operation_kind_str = column_as_string!(&operation_kind); let operation_kind = mint::OperationKind::from_str(&operation_kind_str) - .map_err(|e| Error::Internal(format!("Invalid operation kind: {}", e)))?; + .map_err(|e| Error::Internal(format!("Invalid operation kind: {e}")))?; let state_str = column_as_string!(&state); let state = mint::SagaStateEnum::new(operation_kind, &state_str) - .map_err(|e| Error::Internal(format!("Invalid saga state: {}", e)))?; + .map_err(|e| Error::Internal(format!("Invalid saga state: {e}")))?; let blinded_secrets_str = column_as_string!(&blinded_secrets); let blinded_secrets: Vec = serde_json::from_str(&blinded_secrets_str) - .map_err(|e| Error::Internal(format!("Failed to deserialize blinded_secrets: {}", e)))?; + .map_err(|e| Error::Internal(format!("Failed to deserialize blinded_secrets: {e}")))?; let input_ys_str = column_as_string!(&input_ys); let input_ys: Vec = serde_json::from_str(&input_ys_str) - .map_err(|e| Error::Internal(format!("Failed to deserialize input_ys: {}", e)))?; + .map_err(|e| Error::Internal(format!("Failed to deserialize input_ys: {e}")))?; let quote_id = match "e_id { Column::Text(s) => { diff --git a/crates/cdk-sql-common/src/stmt.rs b/crates/cdk-sql-common/src/stmt.rs index 9f686e542..6ad1d0947 100644 --- a/crates/cdk-sql-common/src/stmt.rs +++ b/crates/cdk-sql-common/src/stmt.rs @@ -104,6 +104,18 @@ pub fn split_sql_parts(input: &str) -> Result, SqlParseError> { } } + '-' => { + current.push(chars.next().unwrap()); + if chars.peek() == Some(&'-') { + while let Some(&next) = chars.peek() { + current.push(chars.next().unwrap()); + if next == '\n' { + break; + } + } + } + } + ':' => { // Flush current raw SQL if !current.is_empty() { diff --git a/crates/cdk-sql-common/src/wallet/migrations/postgres/20251111000000_keyset_counter_table.sql b/crates/cdk-sql-common/src/wallet/migrations/postgres/20251111000000_keyset_counter_table.sql new file mode 100644 index 000000000..d1fce3a55 --- /dev/null +++ b/crates/cdk-sql-common/src/wallet/migrations/postgres/20251111000000_keyset_counter_table.sql @@ -0,0 +1,15 @@ +-- Create dedicated keyset_counter table without foreign keys +-- This table tracks the counter for each keyset independently +CREATE TABLE IF NOT EXISTS keyset_counter ( + keyset_id TEXT PRIMARY KEY, + counter INTEGER NOT NULL DEFAULT 0 +); + +-- Migrate existing counter values from keyset table +INSERT INTO keyset_counter (keyset_id, counter) +SELECT id, counter +FROM keyset +WHERE counter > 0; + +-- Drop the counter column from keyset table +ALTER TABLE keyset DROP COLUMN counter; diff --git a/crates/cdk-sql-common/src/wallet/migrations/sqlite/20251111000000_keyset_counter_table.sql b/crates/cdk-sql-common/src/wallet/migrations/sqlite/20251111000000_keyset_counter_table.sql new file mode 100644 index 000000000..1a29dcf1c --- /dev/null +++ b/crates/cdk-sql-common/src/wallet/migrations/sqlite/20251111000000_keyset_counter_table.sql @@ -0,0 +1,36 @@ +-- Create dedicated keyset_counter table without foreign keys +-- This table tracks the counter for each keyset independently +CREATE TABLE IF NOT EXISTS keyset_counter ( + keyset_id TEXT PRIMARY KEY, + counter INTEGER NOT NULL DEFAULT 0 +); + +-- Migrate existing counter values from keyset table +INSERT INTO keyset_counter (keyset_id, counter) +SELECT id, counter +FROM keyset +WHERE counter > 0; + +-- Drop the counter column from keyset table (SQLite requires table recreation) +-- Step 1: Create new keyset table without counter column +CREATE TABLE keyset_new ( + id TEXT PRIMARY KEY, + mint_url TEXT NOT NULL, + keyset_u32 INTEGER, + unit TEXT NOT NULL, + active BOOL NOT NULL, + input_fee_ppk INTEGER, + final_expiry INTEGER DEFAULT NULL, + FOREIGN KEY(mint_url) REFERENCES mint(mint_url) ON UPDATE CASCADE ON DELETE CASCADE +); + +-- Step 2: Copy data from old keyset table (excluding counter) +INSERT INTO keyset_new (id, keyset_u32, mint_url, unit, active, input_fee_ppk, final_expiry) +SELECT id, keyset_u32, mint_url, unit, active, input_fee_ppk, final_expiry +FROM keyset; + +-- Step 3: Drop old keyset table +DROP TABLE keyset; + +-- Step 4: Rename new table to keyset +ALTER TABLE keyset_new RENAME TO keyset; diff --git a/crates/cdk-sql-common/src/wallet/mod.rs b/crates/cdk-sql-common/src/wallet/mod.rs index 6ce3fb87a..99987963e 100644 --- a/crates/cdk-sql-common/src/wallet/mod.rs +++ b/crates/cdk-sql-common/src/wallet/mod.rs @@ -917,16 +917,16 @@ ON CONFLICT(id) DO UPDATE SET let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; let tx = ConnectionWithTransaction::new(conn).await?; - // Lock the row and get current counter + // Lock the row and get current counter from keyset_counter table let current_counter = query( r#" SELECT counter - FROM keyset - WHERE id=:id + FROM keyset_counter + WHERE keyset_id=:keyset_id FOR UPDATE "#, )? - .bind("id", keyset_id.to_string()) + .bind("keyset_id", keyset_id.to_string()) .pluck(&tx) .await? .map(|n| Ok::<_, Error>(column_as_number!(n))) @@ -935,16 +935,17 @@ ON CONFLICT(id) DO UPDATE SET let new_counter = current_counter + count; - // Update with the new counter value + // Upsert the new counter value query( r#" - UPDATE keyset - SET counter=:new_counter - WHERE id=:id + INSERT INTO keyset_counter (keyset_id, counter) + VALUES (:keyset_id, :new_counter) + ON CONFLICT(keyset_id) DO UPDATE SET + counter = excluded.counter "#, )? + .bind("keyset_id", keyset_id.to_string()) .bind("new_counter", new_counter) - .bind("id", keyset_id.to_string()) .execute(&tx) .await?; diff --git a/crates/cdk/examples/proof-selection.rs b/crates/cdk/examples/proof-selection.rs index cc63e3bca..a0b106f34 100644 --- a/crates/cdk/examples/proof-selection.rs +++ b/crates/cdk/examples/proof-selection.rs @@ -52,7 +52,7 @@ async fn main() -> Result<(), Box> { // Select proofs to send let amount = Amount::from(64); let active_keyset_ids = wallet - .refresh_keysets() + .get_mint_keysets() .await? .active() .map(|keyset| keyset.id) diff --git a/crates/cdk/src/wallet/auth/auth_wallet.rs b/crates/cdk/src/wallet/auth/auth_wallet.rs index 58e683e89..9f843c9ad 100644 --- a/crates/cdk/src/wallet/auth/auth_wallet.rs +++ b/crates/cdk/src/wallet/auth/auth_wallet.rs @@ -3,7 +3,6 @@ use std::sync::Arc; use cdk_common::database::{self, WalletDatabase}; use cdk_common::mint_url::MintUrl; -use cdk_common::nut02::KeySetInfosMethods; use cdk_common::{AuthProof, Id, Keys, MintInfo}; use serde::{Deserialize, Serialize}; use tokio::sync::RwLock; @@ -19,6 +18,7 @@ use crate::nuts::{ }; use crate::types::ProofInfo; use crate::wallet::mint_connector::AuthHttpClient; +use crate::wallet::mint_metadata_cache::MintMetadataCache; use crate::{Amount, Error, OidcClient}; /// JWT Claims structure for decoding tokens @@ -40,11 +40,13 @@ pub struct AuthWallet { pub mint_url: MintUrl, /// Storage backend pub localstore: Arc + Send + Sync>, + /// Mint metadata cache (lock-free cached access to keys, keysets, and mint info) + pub metadata_cache: Arc, /// Protected methods pub protected_endpoints: Arc>>, /// Refresh token for auth refresh_token: Arc>>, - client: Arc, + auth_client: Arc, /// OIDC client for authentication oidc_client: Arc>>, } @@ -55,6 +57,7 @@ impl AuthWallet { mint_url: MintUrl, cat: Option, localstore: Arc + Send + Sync>, + metadata_cache: Arc, protected_endpoints: HashMap, oidc_client: Option, ) -> Self { @@ -62,9 +65,10 @@ impl AuthWallet { Self { mint_url, localstore, + metadata_cache, protected_endpoints: Arc::new(RwLock::new(protected_endpoints)), refresh_token: Arc::new(RwLock::new(None)), - client: http_client, + auth_client: http_client, oidc_client: Arc::new(RwLock::new(oidc_client)), } } @@ -72,7 +76,7 @@ impl AuthWallet { /// Get the current auth token #[instrument(skip(self))] pub async fn get_auth_token(&self) -> Result { - self.client.get_auth_token().await + self.auth_client.get_auth_token().await } /// Set a new auth token @@ -99,7 +103,7 @@ impl AuthWallet { if let Some(oidc) = self.oidc_client.read().await.as_ref() { oidc.verify_cat(clear_token).await?; } - self.client.set_auth_token(token).await + self.auth_client.set_auth_token(token).await } AuthToken::BlindAuth(_) => Err(Error::Custom( "Cannot set blind auth token directly".to_string(), @@ -165,94 +169,78 @@ impl AuthWallet { /// Query mint for current mint information #[instrument(skip(self))] pub async fn get_mint_info(&self) -> Result, Error> { - self.client.get_mint_info().await.map(Some).or(Ok(None)) + self.auth_client + .get_mint_info() + .await + .map(Some) + .or(Ok(None)) } /// Fetch keys for mint keyset /// - /// Returns keys from local database if they are already stored. - /// If keys are not found locally, goes online to query the mint for the keyset and stores the [`Keys`] in local database. + /// Returns keys from metadata cache if available, fetches from mint if not. #[instrument(skip(self))] pub async fn load_keyset_keys(&self, keyset_id: Id) -> Result { - let keys = if let Some(keys) = self.localstore.get_keys(&keyset_id).await? { - keys - } else { - let keys = self.client.get_mint_blind_auth_keyset(keyset_id).await?; - - keys.verify_id()?; - - self.localstore.add_keys(keys.clone()).await?; - - keys.keys - }; - - Ok(keys) + let metadata = self + .metadata_cache + .load_auth(&self.localstore, &self.auth_client) + .await?; + let active = metadata + .active_keysets + .iter() + .find(|x| x.unit == CurrencyUnit::Auth) + .cloned() + .ok_or(Error::NoActiveKeyset)?; + + metadata + .keys + .get(&active.id) + .map(|x| (*(x.clone())).clone()) + .ok_or(Error::NoActiveKeyset) } - /// Get blind auth keysets from local database or go online if missing + /// Get blind auth keysets from metadata cache /// - /// First checks the local database for cached blind auth keysets. If keysets are not found locally, - /// goes online to refresh keysets from the mint and updates the local database. + /// Checks the metadata cache for auth keysets. If cache is not populated, + /// fetches from the mint server and updates the cache. /// This is the main method for getting auth keysets in operations that can work offline /// but will fall back to online if needed. #[instrument(skip(self))] pub async fn load_mint_keysets(&self) -> Result, Error> { - match self - .localstore - .get_mint_keysets(self.mint_url.clone()) - .await? - { - Some(keysets_info) => { - let auth_keysets: Vec = - keysets_info.unit(CurrencyUnit::Sat).cloned().collect(); - if auth_keysets.is_empty() { - // If we don't have any auth keysets, fetch them from the mint - let keysets = self.refresh_keysets().await?; - Ok(keysets) + let metadata = self + .metadata_cache + .load_auth(&self.localstore, &self.auth_client) + .await?; + + let auth_keysets = metadata + .keysets + .iter() + .filter_map(|(_, k)| { + if k.unit == CurrencyUnit::Auth { + Some((*(k.clone())).clone()) } else { - Ok(auth_keysets) + None } - } - None => { - // If we don't have any keysets, fetch them from the mint - let keysets = self.refresh_keysets().await?; - Ok(keysets) - } + }) + .collect::>(); + + if !auth_keysets.is_empty() { + Ok(auth_keysets) + } else { + Err(Error::UnknownKeySet) } } - /// Refresh blind auth keysets by fetching the latest from mint - always goes online + /// Refresh blind auth keysets by fetching the latest from mint /// - /// This method always goes online to fetch the latest blind auth keyset information from the mint. - /// It updates the local database with the fetched keysets and ensures we have keys for all keysets. - /// Returns only the keysets with Auth currency unit. This is used when operations need the most - /// up-to-date keyset information and are willing to go online. + /// Fetches the latest blind auth keyset information from the mint server, + /// updating the metadata cache and database. Returns only the keysets with + /// Auth currency unit. Use this when you need the most up-to-date keyset information. #[instrument(skip(self))] pub async fn refresh_keysets(&self) -> Result, Error> { - let keysets_response = self.client.get_mint_blind_auth_keysets().await?; - let keysets = keysets_response.keysets; - - // Update local store with keysets - self.localstore - .add_mint_keysets(self.mint_url.clone(), keysets.clone()) - .await?; - - // Filter for auth keysets - let auth_keysets = keysets - .clone() - .into_iter() - .filter(|k| k.unit == CurrencyUnit::Auth) - .collect::>(); - - // Ensure we have keys for all auth keysets - for keyset in &auth_keysets { - if self.localstore.get_keys(&keyset.id).await?.is_none() { - tracing::debug!("Fetching missing keys for auth keyset {}", keyset.id); - self.load_keyset_keys(keyset.id).await?; - } - } + tracing::debug!("Refreshing auth keysets from mint"); - Ok(auth_keysets) + self.load_mint_keysets().await } /// Get the first active blind auth keyset - always goes online @@ -325,7 +313,7 @@ impl AuthWallet { Some(auth) => match auth { AuthRequired::Clear => { tracing::trace!("Clear auth needed for request."); - self.client.get_auth_token().await.map(Some) + self.auth_client.get_auth_token().await.map(Some) } AuthRequired::Blind => { tracing::trace!("Blind auth needed for request getting Auth proof."); @@ -359,7 +347,7 @@ impl AuthWallet { self.get_mint_info().await?; } - let auth_token = self.client.get_auth_token().await?; + let auth_token = self.auth_client.get_auth_token().await?; match &auth_token { AuthToken::ClearAuth(cat) => { @@ -425,7 +413,7 @@ impl AuthWallet { outputs: premint_secrets.blinded_messages(), }; - let mint_res = self.client.post_mint_blind_auth(request).await?; + let mint_res = self.auth_client.post_mint_blind_auth(request).await?; let keys = self.load_keyset_keys(active_keyset_id).await?; diff --git a/crates/cdk/src/wallet/builder.rs b/crates/cdk/src/wallet/builder.rs index bcfc403e8..41caededb 100644 --- a/crates/cdk/src/wallet/builder.rs +++ b/crates/cdk/src/wallet/builder.rs @@ -1,8 +1,9 @@ -#[cfg(feature = "auth")] use std::collections::HashMap; use std::sync::Arc; +use std::time::Duration; use cdk_common::database; +use cdk_common::parking_lot::Mutex; #[cfg(feature = "auth")] use cdk_common::AuthToken; #[cfg(feature = "auth")] @@ -14,10 +15,10 @@ use crate::mint_url::MintUrl; use crate::nuts::CurrencyUnit; #[cfg(feature = "auth")] use crate::wallet::auth::AuthWallet; +use crate::wallet::mint_metadata_cache::MintMetadataCache; use crate::wallet::{HttpClient, MintConnector, SubscriptionManager, Wallet}; /// Builder for creating a new [`Wallet`] -#[derive(Debug)] pub struct WalletBuilder { mint_url: Option, unit: Option, @@ -28,6 +29,9 @@ pub struct WalletBuilder { seed: Option<[u8; 64]>, use_http_subscription: bool, client: Option>, + metadata_cache_ttl: Option, + metadata_cache: Option>, + metadata_caches: HashMap>, } impl Default for WalletBuilder { @@ -41,7 +45,10 @@ impl Default for WalletBuilder { auth_wallet: None, seed: None, client: None, + metadata_cache_ttl: None, use_http_subscription: false, + metadata_cache: None, + metadata_caches: HashMap::new(), } } } @@ -58,6 +65,12 @@ impl WalletBuilder { self } + /// Set metadata_cache_ttl + pub fn set_metadata_cache_ttl(mut self, metadata_cache_ttl: Option) -> Self { + self.metadata_cache_ttl = metadata_cache_ttl; + self + } + /// If WS is preferred (with fallback to HTTP is it is not supported by the mint) for the wallet /// subscriptions to mint events pub fn prefer_ws_subscription(mut self) -> Self { @@ -117,13 +130,49 @@ impl WalletBuilder { self } + /// Set a shared MintMetadataCache + /// + /// This allows multiple wallets to share the same metadata cache instance for + /// optimal performance and memory usage. If not provided, a new cache + /// will be created for each wallet. + pub fn metadata_cache(mut self, metadata_cache: Arc) -> Self { + self.metadata_cache = Some(metadata_cache); + self + } + + /// Set a HashMap of MintMetadataCaches for reusing across multiple wallets + /// + /// This allows the builder to reuse existing cache instances or create new ones. + /// Useful when creating multiple wallets that share metadata caches. + pub fn metadata_caches( + mut self, + metadata_caches: HashMap>, + ) -> Self { + self.metadata_caches = metadata_caches; + self + } + /// Set auth CAT (Clear Auth Token) #[cfg(feature = "auth")] pub fn set_auth_cat(mut self, cat: String) -> Self { + let mint_url = self.mint_url.clone().expect("Mint URL required"); + let localstore = self.localstore.clone().expect("Localstore required"); + + let metadata_cache = self.metadata_cache.clone().unwrap_or_else(|| { + // Check if we already have a cache for this mint in the HashMap + if let Some(cache) = self.metadata_caches.get(&mint_url) { + cache.clone() + } else { + // Create a new one + Arc::new(MintMetadataCache::new(mint_url.clone())) + } + }); + self.auth_wallet = Some(AuthWallet::new( - self.mint_url.clone().expect("Mint URL required"), + mint_url, Some(AuthToken::ClearAuth(cat)), - self.localstore.clone().expect("Localstore required"), + localstore, + metadata_cache, HashMap::new(), None, )); @@ -162,10 +211,24 @@ impl WalletBuilder { } }; + let metadata_cache_ttl = self.metadata_cache_ttl; + + let metadata_cache = self.metadata_cache.unwrap_or_else(|| { + // Check if we already have a cache for this mint in the HashMap + if let Some(cache) = self.metadata_caches.get(&mint_url) { + cache.clone() + } else { + // Create a new one + Arc::new(MintMetadataCache::new(mint_url.clone())) + } + }); + Ok(Wallet { mint_url, unit, localstore, + metadata_cache, + metadata_cache_ttl: Arc::new(Mutex::new(metadata_cache_ttl)), target_proof_count: self.target_proof_count.unwrap_or(3), #[cfg(feature = "auth")] auth_wallet: Arc::new(RwLock::new(self.auth_wallet)), diff --git a/crates/cdk/src/wallet/issue/issue_bolt11.rs b/crates/cdk/src/wallet/issue/issue_bolt11.rs index 935c7602d..aada9ed81 100644 --- a/crates/cdk/src/wallet/issue/issue_bolt11.rs +++ b/crates/cdk/src/wallet/issue/issue_bolt11.rs @@ -52,8 +52,6 @@ impl Wallet { let mint_url = self.mint_url.clone(); let unit = self.unit.clone(); - self.refresh_keysets().await?; - // If we have a description, we check that the mint supports it. if description.is_some() { let settings = self @@ -196,8 +194,6 @@ impl Wallet { amount_split_target: SplitTarget, spending_conditions: Option, ) -> Result { - self.refresh_keysets().await?; - let quote_info = self .localstore .get_mint_quote(quote_id) diff --git a/crates/cdk/src/wallet/issue/issue_bolt12.rs b/crates/cdk/src/wallet/issue/issue_bolt12.rs index fd8dc10f9..d20a17017 100644 --- a/crates/cdk/src/wallet/issue/issue_bolt12.rs +++ b/crates/cdk/src/wallet/issue/issue_bolt12.rs @@ -29,8 +29,6 @@ impl Wallet { let mint_url = self.mint_url.clone(); let unit = &self.unit; - self.refresh_keysets().await?; - // If we have a description, we check that the mint supports it. if description.is_some() { let mint_method_settings = self @@ -85,8 +83,6 @@ impl Wallet { amount_split_target: SplitTarget, spending_conditions: Option, ) -> Result { - self.refresh_keysets().await?; - let quote_info = self.localstore.get_mint_quote(quote_id).await?; let quote_info = if let Some(quote) = quote_info { diff --git a/crates/cdk/src/wallet/keysets.rs b/crates/cdk/src/wallet/keysets.rs index 47f088204..a85161852 100644 --- a/crates/cdk/src/wallet/keysets.rs +++ b/crates/cdk/src/wallet/keysets.rs @@ -10,109 +10,102 @@ use crate::{Error, Wallet}; impl Wallet { /// Load keys for mint keyset /// - /// Returns keys from local database if they are already stored. - /// If keys are not found locally, goes online to query the mint for the keyset and stores the [`Keys`] in local database. + /// Returns keys from metadata cache if available. + /// If keys are not cached, fetches from mint server. #[instrument(skip(self))] pub async fn load_keyset_keys(&self, keyset_id: Id) -> Result { - let keys = if let Some(keys) = self.localstore.get_keys(&keyset_id).await? { - keys - } else { - tracing::debug!( - "Keyset {} not in db fetching from mint {}", - keyset_id, - self.mint_url - ); - - let keys = self.client.get_mint_keyset(keyset_id).await?; - - keys.verify_id()?; - - self.localstore.add_keys(keys.clone()).await?; - - keys.keys - }; - - Ok(keys) + self.metadata_cache + .load(&self.localstore, &self.client, { + let ttl = self.metadata_cache_ttl.lock(); + *ttl + }) + .await? + .keys + .get(&keyset_id) + .map(|x| (*x.clone()).clone()) + .ok_or(Error::UnknownKeySet) } - /// Get keysets from local database or go online if missing - /// - /// First checks the local database for cached keysets. If keysets are not found locally, - /// goes online to refresh keysets from the mint and updates the local database. - /// This is the main method for getting keysets in token operations that can work offline - /// but will fall back to online if needed. + /// Alias of get_mint_keysets, kept for backwards compatibility reasons #[instrument(skip(self))] pub async fn load_mint_keysets(&self) -> Result, Error> { - match self - .localstore - .get_mint_keysets(self.mint_url.clone()) - .await? - { - Some(keysets_info) => Ok(keysets_info), - None => { - // If we don't have any keysets, fetch them from the mint - let keysets = self.refresh_keysets().await?; - Ok(keysets) - } - } + self.get_mint_keysets().await } - /// Get keysets from local database only - pure offline operation + /// Get keysets from metadata cache (may fetch if not populated) /// - /// Only checks the local database for cached keysets. If keysets are not found locally, - /// returns an error without going online. This is used for operations that must remain - /// offline and rely on previously cached keyset data. + /// Checks the metadata cache for keysets. If cache is not populated, + /// fetches from mint and updates cache. Returns error if no active keysets found. #[instrument(skip(self))] + #[inline(always)] pub async fn get_mint_keysets(&self) -> Result, Error> { - match self - .localstore - .get_mint_keysets(self.mint_url.clone()) + let keysets = self + .metadata_cache + .load(&self.localstore, &self.client, { + let ttl = self.metadata_cache_ttl.lock(); + *ttl + }) .await? - { - Some(keysets_info) => Ok(keysets_info), - None => Err(Error::UnknownKeySet), + .keysets + .iter() + .filter_map(|(_, keyset)| { + if keyset.unit == self.unit && keyset.active { + Some((*keyset.clone()).clone()) + } else { + None + } + }) + .collect::>(); + + if !keysets.is_empty() { + Ok(keysets) + } else { + Err(Error::UnknownKeySet) } } - /// Refresh keysets by fetching the latest from mint - always goes online + /// Refresh keysets by fetching the latest from mint - always fetches fresh data /// - /// This method always goes online to fetch the latest keyset information from the mint. - /// It updates the local database with the fetched keysets and ensures we have keys - /// for all active keysets. This is used when operations need the most up-to-date - /// keyset information and are willing to go online. + /// Forces a fresh fetch of keyset information from the mint server, + /// updating the metadata cache and database. Use this when you need + /// the most up-to-date keyset information. #[instrument(skip(self))] pub async fn refresh_keysets(&self) -> Result { - tracing::debug!("Refreshing keysets and ensuring we have keys"); - let _ = self.fetch_mint_info().await?; + tracing::debug!("Refreshing keysets from mint"); - // Fetch all current keysets from mint - let keysets_response = self.client.get_mint_keysets().await?; - let all_keysets = keysets_response.keysets; - - // Update local storage with keyset info - self.localstore - .add_mint_keysets(self.mint_url.clone(), all_keysets.clone()) - .await?; - - // Filter for active keysets matching our unit - let keysets: KeySetInfos = all_keysets.unit(self.unit.clone()).cloned().collect(); - - // Ensure we have keys for all active keysets - for keyset in &keysets { - self.load_keyset_keys(keyset.id).await?; + let keysets = self + .metadata_cache + .load_from_mint(&self.localstore, &self.client, { + let ttl = self.metadata_cache_ttl.lock(); + *ttl + }) + .await? + .keysets + .iter() + .filter_map(|(_, keyset)| { + if keyset.unit == self.unit && keyset.active { + Some((*keyset.clone()).clone()) + } else { + None + } + }) + .collect::>(); + + if !keysets.is_empty() { + Ok(keysets) + } else { + Err(Error::UnknownKeySet) } - - Ok(keysets) } - /// Get the active keyset with the lowest fees - always goes online + /// Get the active keyset with the lowest fees - fetches fresh data from mint /// - /// This method always goes online to refresh keysets from the mint and then returns - /// the active keyset with the minimum input fees. Use this when you need the most - /// up-to-date keyset information for operations. + /// Forces a fresh fetch of keysets from the mint and returns the active keyset + /// with the minimum input fees. Use this when you need the most up-to-date + /// keyset information for operations. #[instrument(skip(self))] pub async fn fetch_active_keyset(&self) -> Result { - self.refresh_keysets() + self.get_mint_keysets() .await? .active() .min_by_key(|k| k.input_fee_ppk) @@ -120,47 +113,46 @@ impl Wallet { .ok_or(Error::NoActiveKeyset) } - /// Get the active keyset with the lowest fees from local database only - offline operation + /// Get the active keyset with the lowest fees from cache /// - /// Returns the active keyset with minimum input fees from cached keysets in the local database. - /// This is an offline operation that does not contact the mint. If no keysets are found locally, - /// returns an error. Use this for offline operations or when you want to avoid network calls. + /// Returns the active keyset with minimum input fees from the metadata cache. + /// Uses cached data if available, fetches from mint if cache not populated. #[instrument(skip(self))] pub async fn get_active_keyset(&self) -> Result { - match self - .localstore - .get_mint_keysets(self.mint_url.clone()) + self.metadata_cache + .load(&self.localstore, &self.client, { + let ttl = self.metadata_cache_ttl.lock(); + *ttl + }) .await? - { - Some(keysets_info) => keysets_info - .into_iter() - .min_by_key(|k| k.input_fee_ppk) - .ok_or(Error::NoActiveKeyset), - None => Err(Error::UnknownKeySet), - } + .active_keysets + .iter() + .min_by_key(|k| k.input_fee_ppk) + .map(|ks| (**ks).clone()) + .ok_or(Error::NoActiveKeyset) } - /// Get keyset fees and amounts for mint from local database only - offline operation + /// Get keyset fees and amounts for all keysets from metadata cache /// /// Returns a HashMap of keyset IDs to their input fee rates (per-proof-per-thousand) - /// from cached keysets in the local database. This is an offline operation that does - /// not contact the mint. If no keysets are found locally, returns an error. + /// and available amounts. Uses cached data if available, fetches from mint if not. pub async fn get_keyset_fees_and_amounts(&self) -> Result { - let keysets = self - .localstore - .get_mint_keysets(self.mint_url.clone()) - .await? - .ok_or(Error::UnknownKeySet)?; + let metadata = self + .metadata_cache + .load(&self.localstore, &self.client, { + let ttl = self.metadata_cache_ttl.lock(); + *ttl + }) + .await?; let mut fees = HashMap::new(); - for keyset in keysets { + for keyset in metadata.keysets.values() { + let keys = self.load_keyset_keys(keyset.id).await?; fees.insert( keyset.id, ( keyset.input_fee_ppk, - self.load_keyset_keys(keyset.id) - .await? - .iter() + keys.iter() .map(|(amount, _)| amount.to_u64()) .collect::>(), ) @@ -171,11 +163,10 @@ impl Wallet { Ok(fees) } - /// Get keyset fees and amounts for mint by keyset id from local database only - offline operation + /// Get keyset fees and amounts for a specific keyset ID /// - /// Returns the input fee rate (per-proof-per-thousand) for a specific keyset ID from - /// cached keysets in the local database. This is an offline operation that does not - /// contact the mint. If the keyset is not found locally, returns an error. + /// Returns the input fee rate (per-proof-per-thousand) and available amounts + /// for a specific keyset. Uses cached data if available, fetches from mint if not. pub async fn get_keyset_fees_and_amounts_by_id( &self, keyset_id: Id, diff --git a/crates/cdk/src/wallet/melt/melt_bolt11.rs b/crates/cdk/src/wallet/melt/melt_bolt11.rs index 78b2a773a..2924ec058 100644 --- a/crates/cdk/src/wallet/melt/melt_bolt11.rs +++ b/crates/cdk/src/wallet/melt/melt_bolt11.rs @@ -49,8 +49,6 @@ impl Wallet { request: String, options: Option, ) -> Result { - self.refresh_keysets().await?; - let invoice = Bolt11Invoice::from_str(&request)?; let quote_request = MeltQuoteBolt11Request { @@ -390,7 +388,7 @@ impl Wallet { let available_proofs = self.get_unspent_proofs().await?; let active_keyset_ids = self - .refresh_keysets() + .get_mint_keysets() .await? .into_iter() .map(|k| k.id) diff --git a/crates/cdk/src/wallet/mint_metadata_cache.rs b/crates/cdk/src/wallet/mint_metadata_cache.rs new file mode 100644 index 000000000..1519ff3a4 --- /dev/null +++ b/crates/cdk/src/wallet/mint_metadata_cache.rs @@ -0,0 +1,616 @@ +//! Per-mint cryptographic key and metadata cache +//! +//! Provides on-demand fetching and caching of mint metadata (info, keysets, and keys) +//! with atomic in-memory cache updates and deferred database persistence. +//! +//! # Architecture +//! +//! - **Pull-based loading**: Keys fetched on-demand from mint HTTP API +//! - **Atomic cache**: Single `MintMetadata` snapshot updated via `ArcSwap` +//! - **Deferred persistence**: Database writes happen asynchronously after cache update +//! - **Multi-database support**: Tracks sync status per storage instance via pointer identity +//! +//! # Usage +//! +//! ```ignore +//! // Create manager (cheap, no I/O) +//! let manager = Arc::new(MintMetadataCache::new(mint_url)); +//! +//! // Load metadata (returns cached if available, fetches if not) +//! let metadata = manager.load(&storage, &client).await?; +//! let keys = metadata.keys.get(&keyset_id).ok_or(Error::UnknownKeySet)?; +//! +//! // Force refresh from mint +//! let fresh = manager.load_from_mint(&storage, &client).await?; +//! ``` + +use std::collections::HashMap; +use std::fmt::Debug; +use std::sync::Arc; +use std::time::{Duration, Instant}; + +use arc_swap::ArcSwap; +use cdk_common::database::{self, WalletDatabase}; +use cdk_common::mint_url::MintUrl; +use cdk_common::nuts::{KeySetInfo, Keys}; +use cdk_common::parking_lot::RwLock; +use cdk_common::task::spawn; +use cdk_common::{KeySet, MintInfo}; +use tokio::sync::Mutex; + +use crate::nuts::Id; +use crate::wallet::MintConnector; +#[cfg(feature = "auth")] +use crate::wallet::{AuthMintConnector, AuthWallet}; +use crate::{Error, Wallet}; + +/// Metadata freshness and versioning information +/// +/// Tracks when data was last fetched and which version is currently cached. +/// Used to determine if cache is ready and if database sync is needed. +#[derive(Clone, Debug)] +pub struct FreshnessStatus { + /// Whether this data has been successfully fetched at least once + pub is_populated: bool, + + /// A future time when the cache would be considered as staled. + pub updated_at: Instant, + + /// Monotonically increasing version number (for database sync tracking) + version: usize, +} + +impl Default for FreshnessStatus { + fn default() -> Self { + Self { + is_populated: false, + updated_at: Instant::now(), + version: 0, + } + } +} + +/// Complete metadata snapshot for a single mint +/// +/// Contains all cryptographic keys, keyset metadata, and mint information +/// fetched from a mint server. This struct is atomically swapped as a whole +/// to ensure readers always see a consistent view. +/// +/// Cloning is cheap due to `Arc` wrapping of large data structures. +#[derive(Clone, Debug, Default)] +pub struct MintMetadata { + /// Mint server information (name, description, supported features, etc.) + pub mint_info: MintInfo, + + /// All keysets indexed by their ID (includes both active and inactive) + pub keysets: HashMap>, + + /// Cryptographic keys for each keyset, indexed by keyset ID + pub keys: HashMap>, + + /// Subset of keysets that are currently active (cached for convenience) + pub active_keysets: Vec>, + + /// Freshness tracking for regular (non-auth) mint data + status: FreshnessStatus, + + /// Freshness tracking for blind auth keysets (when `auth` feature enabled) + #[cfg(feature = "auth")] + auth_status: FreshnessStatus, +} + +/// On-demand mint metadata cache with deferred database persistence +/// +/// Manages a single mint's cryptographic keys and metadata. Fetches data from +/// the mint's HTTP API on-demand and caches it in memory. Database writes are +/// deferred to background tasks to avoid blocking operations. +/// +/// # Thread Safety +/// +/// All methods are safe to call concurrently. The cache uses `ArcSwap` for +/// lock-free reads and atomic updates. A `Mutex` ensures only one fetch +/// operation runs at a time, with other callers waiting and re-reading cache. +/// +/// # Cloning +/// +/// Cheap to clone - all data is behind `Arc`. Clones share the same cache. +#[derive(Clone)] +pub struct MintMetadataCache { + /// The mint server URL this cache manages + mint_url: MintUrl, + + /// Atomically-updated metadata snapshot (lock-free reads) + metadata: Arc>, + + /// Tracks which database instances have been synced to which cache version. + /// Key: pointer identity of storage Arc, Value: last synced cache version + db_sync_versions: Arc>>, + + /// Mutex to ensure only one fetch operation runs at a time + /// Other callers wait for the lock, then re-read the updated cache + fetch_lock: Arc>, +} + +impl std::fmt::Debug for MintMetadataCache { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.debug_struct("MintMetadataCache") + .field("mint_url", &self.mint_url) + .field("is_populated", &self.metadata.load().status.is_populated) + .field("keyset_count", &self.metadata.load().keysets.len()) + .finish() + } +} + +impl Wallet { + /// Sets the metadata cache TTL + pub fn set_metadata_cache_ttl(&self, ttl: Option) { + let mut guarded_ttl = self.metadata_cache_ttl.lock(); + *guarded_ttl = ttl; + } + + /// Get information about metadata cache info + pub fn get_metadata_cache_info(&self) -> FreshnessStatus { + self.metadata_cache.metadata.load().status.clone() + } +} + +#[cfg(feature = "auth")] +impl AuthWallet { + /// Get information about metadata cache info + pub fn get_metadata_cache_info(&self) -> FreshnessStatus { + self.metadata_cache.metadata.load().auth_status.clone() + } +} + +impl MintMetadataCache { + /// Compute a unique identifier for an Arc pointer + /// + /// Used to track which storage instances have been synced. We use pointer + /// identity rather than a counter because wallets may use multiple storage + /// backends simultaneously (e.g., different databases for different mints). + fn arc_pointer_id(arc: &Arc) -> usize + where + T: ?Sized, + { + Arc::as_ptr(arc) as *const () as usize + } + + /// Create a new metadata cache for the given mint + /// + /// This is a cheap operation that only allocates memory. No network or + /// database I/O occurs until `load()` or `load_from_mint()` is called. + /// + /// # Example + /// + /// ```ignore + /// let cache = MintMetadataCache::new(mint_url, None); + /// // No data loaded yet - call load() to fetch + /// ``` + pub fn new(mint_url: MintUrl) -> Self { + Self { + mint_url, + metadata: Arc::new(ArcSwap::default()), + db_sync_versions: Arc::new(Default::default()), + fetch_lock: Arc::new(Mutex::new(())), + } + } + + /// Load metadata from mint server and update cache + /// + /// Always performs an HTTP fetch from the mint server to get fresh data. + /// Updates the in-memory cache and spawns a background task to persist + /// to the database. + /// + /// Uses a mutex to ensure only one fetch runs at a time. If multiple + /// callers request a fetch simultaneously, only one performs the HTTP + /// request while others wait for the lock, then return the updated cache. + /// + /// Use this when you need guaranteed fresh data from the mint. + /// + /// # Arguments + /// + /// * `storage` - Database to persist metadata to (async background write) + /// * `client` - HTTP client for fetching from mint server + /// * `ttl` - Optional TTL, if not provided it is assumed that any cached data is good enough + /// + /// # Returns + /// + /// Fresh metadata from the mint server + /// + /// # Example + /// + /// ```ignore + /// // Force refresh from mint (ignores cache) + /// let fresh = cache.load_from_mint(&storage, &client).await?; + /// ``` + #[inline(always)] + pub async fn load_from_mint( + &self, + storage: &Arc + Send + Sync>, + client: &Arc, + ttl: Option, + ) -> Result, Error> { + // Acquire lock to ensure only one fetch at a time + let current_version = self.metadata.load().status.version; + let _guard = self.fetch_lock.lock().await; + + // Check if another caller already updated the cache while we waited + let current_metadata = self.metadata.load().clone(); + if current_metadata.status.is_populated + && ttl + .map(|ttl| current_metadata.status.updated_at + ttl > Instant::now()) + .unwrap_or(true) + && current_metadata.status.version > current_version + { + // Cache was just updated by another caller - return it + tracing::debug!( + "Cache was updated while waiting for fetch lock, returning cached data" + ); + return Ok(current_metadata); + } + + // Perform the fetch + #[cfg(feature = "auth")] + let metadata = self.fetch_from_http(Some(client), None).await?; + + #[cfg(not(feature = "auth"))] + let metadata = self.fetch_from_http(Some(client)).await?; + + // Spawn background task to persist to database (non-blocking) + self.spawn_database_sync(storage.clone(), metadata.clone()); + + Ok(metadata) + } + + /// Load metadata from cache or fetch if not available + /// + /// Returns cached metadata if available and it is still valid, otherwise fetches from the mint. + /// If cache is stale relative to the database, spawns a background sync task. + /// + /// This is the primary method for normal operations - it balances freshness + /// with performance by returning cached data when available. + /// + /// # Arguments + /// + /// * `storage` - Database to persist metadata to (if fetched or stale) + /// * `client` - HTTP client for fetching from mint (only if cache empty) + /// * `ttl` - Optional TTL, if not provided it is assumed that any cached data is good enough + /// + /// # Returns + /// + /// Metadata from cache if available, otherwise fresh from mint + /// + /// # Example + /// + /// ```ignore + /// // Use cached data if available, fetch if not + /// let metadata = cache.load(&storage, &client).await?; + /// ``` + #[inline(always)] + pub async fn load( + &self, + storage: &Arc + Send + Sync>, + client: &Arc, + ttl: Option, + ) -> Result, Error> { + let cached_metadata = self.metadata.load().clone(); + let storage_id = Self::arc_pointer_id(storage); + + // Check what version of cache this database has seen + let db_synced_version = self + .db_sync_versions + .read() + .get(&storage_id) + .cloned() + .unwrap_or_default(); + + if cached_metadata.status.is_populated + && ttl + .map(|ttl| cached_metadata.status.updated_at + ttl > Instant::now()) + .unwrap_or(true) + { + // Cache is ready - check if database needs updating + if db_synced_version != cached_metadata.status.version { + // Database is stale - sync in background + // We spawn rather than await to avoid blocking the caller + // and to prevent deadlocks with any existing transactions + self.spawn_database_sync(storage.clone(), cached_metadata.clone()); + } + return Ok(cached_metadata); + } + + // Cache not populated - fetch from mint + self.load_from_mint(storage, client, ttl).await + } + + /// Load auth keysets and keys (auth feature only) + /// + /// Fetches blind authentication keysets from the mint. Always performs + /// an HTTP fetch to get current auth keysets. + /// + /// # Arguments + /// + /// * `storage` - Database to persist metadata to + /// * `auth_client` - Auth-capable HTTP client for fetching blind auth keysets + /// + /// # Returns + /// + /// Metadata containing auth keysets and keys + #[cfg(feature = "auth")] + pub async fn load_auth( + &self, + storage: &Arc + Send + Sync>, + auth_client: &Arc, + ) -> Result, Error> { + let cached_metadata = self.metadata.load().clone(); + let storage_id = Self::arc_pointer_id(storage); + + let db_synced_version = self + .db_sync_versions + .read() + .get(&storage_id) + .cloned() + .unwrap_or_default(); + + // Check if auth data is populated in cache + if cached_metadata.auth_status.is_populated + && cached_metadata.auth_status.updated_at > Instant::now() + { + if db_synced_version != cached_metadata.status.version { + // Database needs updating - spawn background sync + self.spawn_database_sync(storage.clone(), cached_metadata.clone()); + } + return Ok(cached_metadata); + } + + // Acquire fetch lock to ensure only one auth fetch at a time + let _guard = self.fetch_lock.lock().await; + + // Re-check if auth data was updated while waiting for lock + let current_metadata = self.metadata.load().clone(); + if current_metadata.auth_status.is_populated + && current_metadata.auth_status.updated_at > Instant::now() + { + tracing::debug!( + "Auth cache was updated while waiting for fetch lock, returning cached data" + ); + return Ok(current_metadata); + } + + // Auth data not in cache - fetch from mint + let metadata = self.fetch_from_http(None, Some(auth_client)).await?; + + // Spawn background task to persist + self.spawn_database_sync(storage.clone(), metadata.clone()); + + Ok(metadata) + } + + /// Spawn a background task to sync metadata to database + /// + /// This is non-blocking and happens asynchronously. The task will: + /// 1. Check if this sync is still needed (version may be superseded) + /// 2. Save mint info, keysets, and keys to the database + /// 3. Update the sync tracking to record this storage has been updated + fn spawn_database_sync( + &self, + storage: Arc + Send + Sync>, + metadata: Arc, + ) { + let mint_url = self.mint_url.clone(); + let db_sync_versions = self.db_sync_versions.clone(); + + spawn(async move { + Self::persist_to_database(mint_url, storage, metadata, db_sync_versions).await + }); + } + + /// Persist metadata to database (called from background task) + /// + /// Saves mint info, keysets, and keys to the database. Checks version + /// before writing to avoid redundant work if a newer version has already + /// been persisted. + /// + /// # Arguments + /// + /// * `mint_url` - Mint URL for database keys + /// * `storage` - Database to write to + /// * `metadata` - Metadata to persist + /// * `db_sync_versions` - Shared version tracker + async fn persist_to_database( + mint_url: MintUrl, + storage: Arc + Send + Sync>, + metadata: Arc, + db_sync_versions: Arc>>, + ) { + let storage_id = Self::arc_pointer_id(&storage); + + // Check if this write is still needed + { + let mut versions = db_sync_versions.write(); + + let current_synced_version = versions.get(&storage_id).cloned().unwrap_or_default(); + + if metadata.status.version <= current_synced_version { + // A newer version has already been persisted - skip this write + return; + } + + // Mark this version as being synced + versions.insert(storage_id, metadata.status.version); + } + + // Save mint info + storage + .add_mint(mint_url.clone(), Some(metadata.mint_info.clone())) + .await + .inspect_err(|e| tracing::warn!("Failed to save mint info for {}: {}", mint_url, e)) + .ok(); + + // Save all keysets + let keysets: Vec<_> = metadata.keysets.values().map(|ks| (**ks).clone()).collect(); + + if !keysets.is_empty() { + storage + .add_mint_keysets(mint_url.clone(), keysets) + .await + .inspect_err(|e| tracing::warn!("Failed to save keysets for {}: {}", mint_url, e)) + .ok(); + } + + // Save keys for each keyset + for (keyset_id, keys) in &metadata.keys { + if let Some(keyset_info) = metadata.keysets.get(keyset_id) { + let keyset = KeySet { + id: *keyset_id, + unit: keyset_info.unit.clone(), + final_expiry: keyset_info.final_expiry, + keys: (**keys).clone(), + }; + + storage + .add_keys(keyset) + .await + .inspect_err(|e| { + tracing::warn!( + "Failed to save keys for keyset {} at {}: {}", + keyset_id, + mint_url, + e + ) + }) + .ok(); + } + } + } + + /// Fetch fresh metadata from mint HTTP API and update cache + /// + /// Performs the following steps: + /// 1. Fetches mint info from server + /// 2. Fetches list of all keysets + /// 3. Fetches cryptographic keys for each keyset + /// 4. Verifies keyset IDs match their keys + /// 5. Atomically updates in-memory cache + /// + /// # Arguments + /// + /// * `client` - Optional regular mint client (for non-auth operations) + /// * `auth_client` - Optional auth client (for blind auth keysets) + /// + /// # Returns + /// + /// Newly fetched and cached metadata + async fn fetch_from_http( + &self, + client: Option<&Arc>, + #[cfg(feature = "auth")] auth_client: Option<&Arc>, + ) -> Result, Error> { + tracing::debug!("Fetching mint metadata from HTTP for {}", self.mint_url); + + // Start with current cache to preserve data from other sources + let mut new_metadata = (*self.metadata.load().clone()).clone(); + let mut keysets_to_fetch = Vec::new(); + + // Fetch regular mint data + if let Some(client) = client.as_ref() { + // Get mint information + new_metadata.mint_info = client.get_mint_info().await.inspect_err(|err| { + tracing::error!("Failed to fetch mint info for {}: {}", self.mint_url, err); + })?; + + // Get list of keysets + keysets_to_fetch.extend( + client + .get_mint_keysets() + .await + .inspect_err(|err| { + tracing::error!("Failed to fetch keysets for {}: {}", self.mint_url, err); + })? + .keysets, + ); + } + + // Fetch auth keysets if auth client provided + #[cfg(feature = "auth")] + if let Some(auth_client) = auth_client.as_ref() { + keysets_to_fetch.extend(auth_client.get_mint_blind_auth_keysets().await?.keysets); + } + + tracing::debug!( + "Fetched {} keysets for {}", + keysets_to_fetch.len(), + self.mint_url + ); + + // Fetch keys for each keyset + for keyset_info in keysets_to_fetch { + let keyset_arc = Arc::new(keyset_info.clone()); + new_metadata + .keysets + .insert(keyset_info.id, keyset_arc.clone()); + + // Track active keysets separately for quick access + if keyset_info.active { + new_metadata.active_keysets.push(keyset_arc); + } + + // Only fetch keys if we don't already have them cached + if let std::collections::hash_map::Entry::Vacant(e) = + new_metadata.keys.entry(keyset_info.id) + { + let keyset = if let Some(client) = client.as_ref() { + client.get_mint_keyset(keyset_info.id).await? + } else { + #[cfg(feature = "auth")] + if let Some(auth_client) = auth_client.as_ref() { + auth_client + .get_mint_blind_auth_keyset(keyset_info.id) + .await? + } else { + return Err(Error::Internal); + } + + #[cfg(not(feature = "auth"))] + return Err(Error::Internal); + }; + + // Verify the keyset ID matches the keys + keyset.verify_id()?; + + e.insert(Arc::new(keyset.keys)); + } + } + + // Update freshness status based on what was fetched + if client.is_some() { + new_metadata.status.is_populated = true; + new_metadata.status.updated_at = Instant::now(); + new_metadata.status.version += 1; + } + + #[cfg(feature = "auth")] + if auth_client.is_some() { + new_metadata.auth_status.is_populated = true; + new_metadata.auth_status.updated_at = Instant::now(); + new_metadata.auth_status.version += 1; + } + + tracing::info!( + "Updated cache for {} with {} keysets (version {})", + self.mint_url, + new_metadata.keysets.len(), + new_metadata.status.version + ); + + // Atomically update cache + let metadata_arc = Arc::new(new_metadata); + self.metadata.store(metadata_arc.clone()); + Ok(metadata_arc) + } + + /// Get the mint URL this cache manages + pub fn mint_url(&self) -> &MintUrl { + &self.mint_url + } +} diff --git a/crates/cdk/src/wallet/mod.rs b/crates/cdk/src/wallet/mod.rs index 4a9ed797e..1ebef3f1a 100644 --- a/crates/cdk/src/wallet/mod.rs +++ b/crates/cdk/src/wallet/mod.rs @@ -1,12 +1,15 @@ #![doc = include_str!("./README.md")] use std::collections::HashMap; +use std::fmt::Debug; use std::str::FromStr; use std::sync::atomic::AtomicBool; use std::sync::Arc; +use std::time::Duration; use cdk_common::amount::FeeAndAmounts; use cdk_common::database::{self, WalletDatabase}; +use cdk_common::parking_lot::Mutex; use cdk_common::subscription::WalletParams; use getrandom::getrandom; use subscription::{ActiveSubscription, SubscriptionManager}; @@ -28,6 +31,7 @@ use crate::nuts::{ }; use crate::types::ProofInfo; use crate::util::unix_time; +use crate::wallet::mint_metadata_cache::MintMetadataCache; use crate::Amount; #[cfg(feature = "auth")] use crate::OidcClient; @@ -42,6 +46,7 @@ mod issue; mod keysets; mod melt; mod mint_connector; +mod mint_metadata_cache; pub mod multi_mint_wallet; pub mod payment_request; mod proofs; @@ -86,8 +91,11 @@ pub struct Wallet { pub unit: CurrencyUnit, /// Storage backend pub localstore: Arc + Send + Sync>, + /// Mint metadata cache for this mint (lock-free cached access to keys, keysets, and mint info) + pub metadata_cache: Arc, /// The targeted amount of proofs to have at each size pub target_proof_count: usize, + metadata_cache_ttl: Arc>>, #[cfg(feature = "auth")] auth_wallet: Arc>>, seed: [u8; 64], @@ -217,12 +225,18 @@ impl Wallet { proofs_per_keyset: HashMap, ) -> Result { let mut fee_per_keyset = HashMap::new(); + let metadata = self + .metadata_cache + .load(&self.localstore, &self.client, { + let ttl = self.metadata_cache_ttl.lock(); + *ttl + }) + .await?; for keyset_id in proofs_per_keyset.keys() { - let mint_keyset_info = self - .localstore - .get_keyset_by_id(keyset_id) - .await? + let mint_keyset_info = metadata + .keysets + .get(keyset_id) .ok_or(Error::UnknownKeySet)?; fee_per_keyset.insert(*keyset_id, mint_keyset_info.input_fee_ppk); } @@ -236,9 +250,14 @@ impl Wallet { #[instrument(skip_all)] pub async fn get_keyset_count_fee(&self, keyset_id: &Id, count: u64) -> Result { let input_fee_ppk = self - .localstore - .get_keyset_by_id(keyset_id) + .metadata_cache + .load(&self.localstore, &self.client, { + let ttl = self.metadata_cache_ttl.lock(); + *ttl + }) .await? + .keysets + .get(keyset_id) .ok_or(Error::UnknownKeySet)? .input_fee_ppk; @@ -307,6 +326,7 @@ impl Wallet { self.mint_url.clone(), None, self.localstore.clone(), + self.metadata_cache.clone(), mint_info.protected_endpoints(), oidc_client, ); diff --git a/crates/cdk/src/wallet/multi_mint_wallet.rs b/crates/cdk/src/wallet/multi_mint_wallet.rs index d12066411..1e98d37f7 100644 --- a/crates/cdk/src/wallet/multi_mint_wallet.rs +++ b/crates/cdk/src/wallet/multi_mint_wallet.rs @@ -11,6 +11,7 @@ use std::sync::Arc; use anyhow::Result; use cdk_common::database; use cdk_common::database::WalletDatabase; +use cdk_common::task::spawn; use cdk_common::wallet::{Transaction, TransactionDirection}; use tokio::sync::RwLock; use tracing::instrument; @@ -914,20 +915,7 @@ impl MultiMintWallet { let target_mint_url = target_mint_url.clone(); // Spawn parallel transfer task - #[cfg(not(target_arch = "wasm32"))] - let task = tokio::spawn(async move { - self_clone - .transfer( - &source_mint_url, - &target_mint_url, - TransferMode::ExactReceive(transfer_amount), - ) - .await - .map(|result| result.amount_received) - }); - - #[cfg(target_arch = "wasm32")] - let task = tokio::task::spawn_local(async move { + let task = spawn(async move { self_clone .transfer( &source_mint_url, @@ -1342,14 +1330,7 @@ impl MultiMintWallet { let amount_msat = u64::from(amount) * 1000; let options = Some(MeltOptions::new_mpp(amount_msat)); - #[cfg(not(target_arch = "wasm32"))] - let task = tokio::spawn(async move { - let quote = wallet.melt_quote(bolt11_clone, options).await; - (mint_url_clone, quote) - }); - - #[cfg(target_arch = "wasm32")] - let task = tokio::task::spawn_local(async move { + let task = spawn(async move { let quote = wallet.melt_quote(bolt11_clone, options).await; (mint_url_clone, quote) }); @@ -1398,14 +1379,7 @@ impl MultiMintWallet { let mint_url_clone = mint_url.clone(); - #[cfg(not(target_arch = "wasm32"))] - let task = tokio::spawn(async move { - let melted = wallet.melt("e_id).await; - (mint_url_clone, melted) - }); - - #[cfg(target_arch = "wasm32")] - let task = tokio::task::spawn_local(async move { + let task = spawn(async move { let melted = wallet.melt("e_id).await; (mint_url_clone, melted) }); diff --git a/crates/cdk/src/wallet/receive.rs b/crates/cdk/src/wallet/receive.rs index b5fc2c8f9..b738c9b72 100644 --- a/crates/cdk/src/wallet/receive.rs +++ b/crates/cdk/src/wallet/receive.rs @@ -28,8 +28,6 @@ impl Wallet { ) -> Result { let mint_url = &self.mint_url; - self.refresh_keysets().await?; - let active_keyset_id = self.fetch_active_keyset().await?.id; let keys = self.load_keyset_keys(active_keyset_id).await?; diff --git a/crates/cdk/src/wallet/swap.rs b/crates/cdk/src/wallet/swap.rs index 71a538b5a..d365b6f95 100644 --- a/crates/cdk/src/wallet/swap.rs +++ b/crates/cdk/src/wallet/swap.rs @@ -21,8 +21,6 @@ impl Wallet { spending_conditions: Option, include_fees: bool, ) -> Result, Error> { - self.refresh_keysets().await?; - tracing::info!("Swapping"); let mint_url = &self.mint_url; let unit = &self.unit; @@ -50,10 +48,16 @@ impl Wallet { .await?; let active_keys = self - .localstore - .get_keys(&active_keyset_id) + .metadata_cache + .load(&self.localstore, &self.client, { + let ttl = self.metadata_cache_ttl.lock(); + *ttl + }) .await? - .ok_or(Error::NoActiveKeyset)?; + .keys + .get(&active_keyset_id) + .ok_or(Error::UnknownKeySet)? + .clone(); let post_swap_proofs = construct_proofs( swap_response.signatures, @@ -175,7 +179,7 @@ impl Wallet { ensure_cdk!(proofs_sum >= amount, Error::InsufficientFunds); let active_keyset_ids = self - .refresh_keysets() + .get_mint_keysets() .await? .active() .map(|k| k.id) diff --git a/misc/fake_itests.sh b/misc/fake_itests.sh index 894b02530..a9caab5d0 100755 --- a/misc/fake_itests.sh +++ b/misc/fake_itests.sh @@ -175,7 +175,7 @@ done # Run first test echo "Running fake_wallet test" -cargo test -p cdk-integration-tests --test fake_wallet +cargo test -p cdk-integration-tests --test fake_wallet -- --nocapture status1=$? # Exit immediately if the first test failed @@ -186,7 +186,7 @@ fi # Run second test only if the first one succeeded echo "Running happy_path_mint_wallet test" -cargo test -p cdk-integration-tests --test happy_path_mint_wallet +cargo test -p cdk-integration-tests --test happy_path_mint_wallet -- --nocapture status2=$? # Exit if the second test failed From c859939289236c81cdab9125d8316a38b3b2a3fc Mon Sep 17 00:00:00 2001 From: tsk Date: Thu, 13 Nov 2025 14:07:43 +0000 Subject: [PATCH 261/321] fix: nut14 disabled in info (#1269) --- crates/cdk/src/mint/builder.rs | 50 ++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/crates/cdk/src/mint/builder.rs b/crates/cdk/src/mint/builder.rs index c1c0ee5fe..4d582c391 100644 --- a/crates/cdk/src/mint/builder.rs +++ b/crates/cdk/src/mint/builder.rs @@ -49,6 +49,7 @@ impl MintBuilder { .nut10(true) .nut11(true) .nut12(true) + .nut14(true) .nut20(true), ..Default::default() }; @@ -382,3 +383,52 @@ impl MintMeltLimits { } } } + +#[cfg(test)] +mod tests { + use std::sync::Arc; + + use cdk_sqlite::mint::memory; + + use super::*; + + #[tokio::test] + async fn test_mint_builder_default_nuts_support() { + let localstore = Arc::new(memory::empty().await.unwrap()); + let builder = MintBuilder::new(localstore); + let mint_info = builder.current_mint_info(); + + assert!( + mint_info.nuts.nut07.supported, + "NUT-07 should be supported by default" + ); + assert!( + mint_info.nuts.nut08.supported, + "NUT-08 should be supported by default" + ); + assert!( + mint_info.nuts.nut09.supported, + "NUT-09 should be supported by default" + ); + assert!( + mint_info.nuts.nut10.supported, + "NUT-10 should be supported by default" + ); + assert!( + mint_info.nuts.nut11.supported, + "NUT-11 should be supported by default" + ); + assert!( + mint_info.nuts.nut12.supported, + "NUT-12 should be supported by default" + ); + assert!( + mint_info.nuts.nut14.supported, + "NUT-14 (HTLC) should be supported by default" + ); + assert!( + mint_info.nuts.nut20.supported, + "NUT-20 should be supported by default" + ); + } +} From 2f9100ea4ff83b6f2a6b0a73fac9c74cfe9a6398 Mon Sep 17 00:00:00 2001 From: tsk Date: Thu, 13 Nov 2025 14:33:51 +0000 Subject: [PATCH 262/321] Metadata follow up (#1268) * feat: cache_ttl as RwLock instead of Mutex This is a read heavy workflow that is not held across await points. So we can use a RwLock instead of Mutex. * refactor: remove TTL check from load_from_mint for guaranteed fresh fetches Remove TTL parameter and check from load_from_mint() to ensure it always fetches fresh metadata from the mint as documented. The method now truly forces a refresh, while load() continues to handle TTL-based caching. --- crates/cdk/src/wallet/builder.rs | 8 ++++---- crates/cdk/src/wallet/keysets.rs | 13 +++++-------- crates/cdk/src/wallet/mint_metadata_cache.rs | 12 +++--------- crates/cdk/src/wallet/mod.rs | 12 ++++++------ crates/cdk/src/wallet/swap.rs | 2 +- 5 files changed, 19 insertions(+), 28 deletions(-) diff --git a/crates/cdk/src/wallet/builder.rs b/crates/cdk/src/wallet/builder.rs index 41caededb..557ace25a 100644 --- a/crates/cdk/src/wallet/builder.rs +++ b/crates/cdk/src/wallet/builder.rs @@ -3,11 +3,11 @@ use std::sync::Arc; use std::time::Duration; use cdk_common::database; -use cdk_common::parking_lot::Mutex; +use cdk_common::parking_lot::RwLock; #[cfg(feature = "auth")] use cdk_common::AuthToken; #[cfg(feature = "auth")] -use tokio::sync::RwLock; +use tokio::sync::RwLock as TokioRwLock; use crate::cdk_database::WalletDatabase; use crate::error::Error; @@ -228,10 +228,10 @@ impl WalletBuilder { unit, localstore, metadata_cache, - metadata_cache_ttl: Arc::new(Mutex::new(metadata_cache_ttl)), + metadata_cache_ttl: Arc::new(RwLock::new(metadata_cache_ttl)), target_proof_count: self.target_proof_count.unwrap_or(3), #[cfg(feature = "auth")] - auth_wallet: Arc::new(RwLock::new(self.auth_wallet)), + auth_wallet: Arc::new(TokioRwLock::new(self.auth_wallet)), seed, client: client.clone(), subscription: SubscriptionManager::new(client, self.use_http_subscription), diff --git a/crates/cdk/src/wallet/keysets.rs b/crates/cdk/src/wallet/keysets.rs index a85161852..2feb121c1 100644 --- a/crates/cdk/src/wallet/keysets.rs +++ b/crates/cdk/src/wallet/keysets.rs @@ -16,7 +16,7 @@ impl Wallet { pub async fn load_keyset_keys(&self, keyset_id: Id) -> Result { self.metadata_cache .load(&self.localstore, &self.client, { - let ttl = self.metadata_cache_ttl.lock(); + let ttl = self.metadata_cache_ttl.read(); *ttl }) .await? @@ -42,7 +42,7 @@ impl Wallet { let keysets = self .metadata_cache .load(&self.localstore, &self.client, { - let ttl = self.metadata_cache_ttl.lock(); + let ttl = self.metadata_cache_ttl.read(); *ttl }) .await? @@ -75,10 +75,7 @@ impl Wallet { let keysets = self .metadata_cache - .load_from_mint(&self.localstore, &self.client, { - let ttl = self.metadata_cache_ttl.lock(); - *ttl - }) + .load_from_mint(&self.localstore, &self.client) .await? .keysets .iter() @@ -121,7 +118,7 @@ impl Wallet { pub async fn get_active_keyset(&self) -> Result { self.metadata_cache .load(&self.localstore, &self.client, { - let ttl = self.metadata_cache_ttl.lock(); + let ttl = self.metadata_cache_ttl.read(); *ttl }) .await? @@ -140,7 +137,7 @@ impl Wallet { let metadata = self .metadata_cache .load(&self.localstore, &self.client, { - let ttl = self.metadata_cache_ttl.lock(); + let ttl = self.metadata_cache_ttl.read(); *ttl }) .await?; diff --git a/crates/cdk/src/wallet/mint_metadata_cache.rs b/crates/cdk/src/wallet/mint_metadata_cache.rs index 1519ff3a4..a83134b4a 100644 --- a/crates/cdk/src/wallet/mint_metadata_cache.rs +++ b/crates/cdk/src/wallet/mint_metadata_cache.rs @@ -144,7 +144,7 @@ impl std::fmt::Debug for MintMetadataCache { impl Wallet { /// Sets the metadata cache TTL pub fn set_metadata_cache_ttl(&self, ttl: Option) { - let mut guarded_ttl = self.metadata_cache_ttl.lock(); + let mut guarded_ttl = self.metadata_cache_ttl.write(); *guarded_ttl = ttl; } @@ -211,7 +211,6 @@ impl MintMetadataCache { /// /// * `storage` - Database to persist metadata to (async background write) /// * `client` - HTTP client for fetching from mint server - /// * `ttl` - Optional TTL, if not provided it is assumed that any cached data is good enough /// /// # Returns /// @@ -228,7 +227,6 @@ impl MintMetadataCache { &self, storage: &Arc + Send + Sync>, client: &Arc, - ttl: Option, ) -> Result, Error> { // Acquire lock to ensure only one fetch at a time let current_version = self.metadata.load().status.version; @@ -236,11 +234,7 @@ impl MintMetadataCache { // Check if another caller already updated the cache while we waited let current_metadata = self.metadata.load().clone(); - if current_metadata.status.is_populated - && ttl - .map(|ttl| current_metadata.status.updated_at + ttl > Instant::now()) - .unwrap_or(true) - && current_metadata.status.version > current_version + if current_metadata.status.is_populated && current_metadata.status.version > current_version { // Cache was just updated by another caller - return it tracing::debug!( @@ -320,7 +314,7 @@ impl MintMetadataCache { } // Cache not populated - fetch from mint - self.load_from_mint(storage, client, ttl).await + self.load_from_mint(storage, client).await } /// Load auth keysets and keys (auth feature only) diff --git a/crates/cdk/src/wallet/mod.rs b/crates/cdk/src/wallet/mod.rs index 1ebef3f1a..26fca287a 100644 --- a/crates/cdk/src/wallet/mod.rs +++ b/crates/cdk/src/wallet/mod.rs @@ -9,12 +9,12 @@ use std::time::Duration; use cdk_common::amount::FeeAndAmounts; use cdk_common::database::{self, WalletDatabase}; -use cdk_common::parking_lot::Mutex; +use cdk_common::parking_lot::RwLock; use cdk_common::subscription::WalletParams; use getrandom::getrandom; use subscription::{ActiveSubscription, SubscriptionManager}; #[cfg(feature = "auth")] -use tokio::sync::RwLock; +use tokio::sync::RwLock as TokioRwLock; use tracing::instrument; use zeroize::Zeroize; @@ -95,9 +95,9 @@ pub struct Wallet { pub metadata_cache: Arc, /// The targeted amount of proofs to have at each size pub target_proof_count: usize, - metadata_cache_ttl: Arc>>, + metadata_cache_ttl: Arc>>, #[cfg(feature = "auth")] - auth_wallet: Arc>>, + auth_wallet: Arc>>, seed: [u8; 64], client: Arc, subscription: SubscriptionManager, @@ -228,7 +228,7 @@ impl Wallet { let metadata = self .metadata_cache .load(&self.localstore, &self.client, { - let ttl = self.metadata_cache_ttl.lock(); + let ttl = self.metadata_cache_ttl.read(); *ttl }) .await?; @@ -252,7 +252,7 @@ impl Wallet { let input_fee_ppk = self .metadata_cache .load(&self.localstore, &self.client, { - let ttl = self.metadata_cache_ttl.lock(); + let ttl = self.metadata_cache_ttl.read(); *ttl }) .await? diff --git a/crates/cdk/src/wallet/swap.rs b/crates/cdk/src/wallet/swap.rs index d365b6f95..b78fad922 100644 --- a/crates/cdk/src/wallet/swap.rs +++ b/crates/cdk/src/wallet/swap.rs @@ -50,7 +50,7 @@ impl Wallet { let active_keys = self .metadata_cache .load(&self.localstore, &self.client, { - let ttl = self.metadata_cache_ttl.lock(); + let ttl = self.metadata_cache_ttl.read(); *ttl }) .await? From e5882dc2ebef3b964cbd4c473dc27af9b051e792 Mon Sep 17 00:00:00 2001 From: tsk Date: Fri, 14 Nov 2025 16:36:17 +0000 Subject: [PATCH 263/321] test: add mutation testing infrastructure and security-critical coverage (#1210) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mutation testing validates test quality by introducing code changes and checking if tests catch them. This is critical for security code where missing negative tests could allow bypasses. **Infrastructure:** - `.cargo/mutants.toml` - Configuration with timeout exclusions - `justfile` commands - `mutants-quick`, `mutants-check`, `mutants-diff` - GitHub Actions - Weekly mutation testing with issue creation **Security-Critical Tests:** - NUT12 (DLEQ): 5 tests ensuring signature verification (prevents token forgery) - NUT14 (HTLC): 6 tests ensuring spending conditions (prevents unauthorized spending) - Amount operations: Tests for subtraction, checked_add, try_sum (prevents infinite loops) - Mutations Caught: 301 → 308 (+7, +2.3%) - Mutations Missed: 281 → 274 (-7, -2.5%) - Mutation Coverage: 35.5% → 36.4% (+0.9%) - All critical verification functions: 100% coverage --- .cargo/mutants.toml | 39 +++ .github/ISSUE_TEMPLATE/mutation-testing.md | 58 ++++ .github/workflows/mutation-testing-weekly.yml | 83 +++++ .gitignore | 5 + DEVELOPMENT.md | 24 ++ crates/cashu/src/amount.rs | 209 +++++++++++++ crates/cashu/src/dhke.rs | 164 ++++++++++ crates/cashu/src/nuts/nut12.rs | 153 ++++++++++ crates/cashu/src/nuts/nut14/mod.rs | 283 ++++++++++++++++++ flake.nix | 4 +- justfile | 81 ++++- 11 files changed, 1101 insertions(+), 2 deletions(-) create mode 100644 .cargo/mutants.toml create mode 100644 .github/ISSUE_TEMPLATE/mutation-testing.md create mode 100644 .github/workflows/mutation-testing-weekly.yml diff --git a/.cargo/mutants.toml b/.cargo/mutants.toml new file mode 100644 index 000000000..3e0574508 --- /dev/null +++ b/.cargo/mutants.toml @@ -0,0 +1,39 @@ +# Mutation Testing Configuration for CDK +# Phase 1: Focus on cashu crate only + +# Start with cashu crate only - exclude other crates initially +exclude_globs = [ + "crates/cdk-*/**", # Exclude other crates initially + "**/tests/**", # Don't mutate test code + "**/benches/**", # Don't mutate benchmarks +] + +# Reasonable timeout to catch hangs (5 minutes minimum) +minimum_test_timeout = 300 + +# Skip specific mutations that cause infinite loops +# These mutations create scenarios where loops never terminate or recursive functions never return. +# Format: "file.rs:line.*pattern" +exclude_re = [ + # dhke.rs:61 - Mutating counter += to *= causes infinite loop (counter stays 0) + "crates/cashu/src/dhke.rs:61:.*replace \\+= with \\*=", + + # amount.rs:108 - Mutating % to / in split causes infinite loop + "crates/cashu/src/amount.rs:108:.*replace % with /", + + # amount.rs:100 - split() returning empty vec causes infinite loops + "crates/cashu/src/amount.rs:100:.*replace.*split.*with vec!\\[\\]", + "crates/cashu/src/amount.rs:100:.*replace.*split.*with vec!\\[Default", + + # amount.rs:203 - checked_add returning Some(Default/0) causes infinite increment loops + "crates/cashu/src/amount.rs:203:.*replace.*checked_add.*with Some\\(Default", + + # amount.rs:226 - try_sum returning Ok(Default/0) causes infinite loops + "crates/cashu/src/amount.rs:226:.*replace.*try_sum.*with Ok\\(Default", + + # amount.rs:288 - From returning Default/0 causes infinite loops + "crates/cashu/src/amount.rs:288:.*replace.*from.*with Default", + + # amount.rs:331 - Sub returning Default/0 causes infinite loops + "crates/cashu/src/amount.rs:331:.*replace.*sub.*with Default", +] diff --git a/.github/ISSUE_TEMPLATE/mutation-testing.md b/.github/ISSUE_TEMPLATE/mutation-testing.md new file mode 100644 index 000000000..53dea1444 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/mutation-testing.md @@ -0,0 +1,58 @@ +--- +name: Mutation Testing Improvement +about: Track improvements to mutation test coverage +title: '[Mutation] ' +labels: 'mutation-testing, enhancement' +assignees: '' + +--- + +## Mutation Details + +**File:** `crates/cashu/src/...` +**Line:** 123 +**Mutation:** replace foo() with bar() + +**Current Status:** MISSED + +## Why This Matters + + + +## Proposed Fix + + + +### Test Strategy + +- [ ] Add negative test case +- [ ] Add edge case test +- [ ] Add integration test +- [ ] Other: ___________ + +### Expected Test + +```rust +#[test] +fn test_() { + // Test that ensures this mutation would be caught +} +``` + +## Verification + +After implementing the fix: + +```bash +# Run mutation test on specific file +cargo mutants --file crates/cashu/src/... + +# Or run mutation test on the specific function +cargo mutants --file crates/cashu/src/... --re "function_name" +``` + +Expected result: Mutation should be **CAUGHT** ✅ + +## Related + + diff --git a/.github/workflows/mutation-testing-weekly.yml b/.github/workflows/mutation-testing-weekly.yml new file mode 100644 index 000000000..f69aacbff --- /dev/null +++ b/.github/workflows/mutation-testing-weekly.yml @@ -0,0 +1,83 @@ +name: Weekly Mutation Testing + +on: + # Run every Monday at 9 AM UTC + schedule: + - cron: '0 9 * * 1' + # Allow manual trigger + workflow_dispatch: + +env: + CARGO_TERM_COLOR: always + +jobs: + cargo-mutants: + runs-on: ubuntu-latest + permissions: + contents: read + issues: write + + steps: + - uses: actions/checkout@v4 + + - name: Install Rust + uses: dtolnay/rust-toolchain@stable + + - uses: taiki-e/install-action@v2 + with: + tool: cargo-mutants + + - name: Run mutation tests on cashu crate + run: cargo mutants --package cashu --in-place --no-shuffle + continue-on-error: true + + - name: Upload mutation results + uses: actions/upload-artifact@v4 + if: always() + with: + name: mutants.out + path: mutants.out + retention-days: 90 + + - name: Check for missed mutants and create issue + if: always() + run: | + if [ -s mutants.out/missed.txt ]; then + echo "Missed mutants found" + MUTANTS_VERSION=$(cargo mutants --version) + MISSED_COUNT=$(wc -l < mutants.out/missed.txt) + CAUGHT_COUNT=$(wc -l < mutants.out/caught.txt 2>/dev/null || echo "0") + + gh issue create \ + --title "🧬 Weekly Mutation Testing Report - $(date +%Y-%m-%d)" \ + --label "mutation-testing,weekly-report" \ + --body "$(cat < = vec![]; + let result = Amount::try_sum(empty).unwrap(); + assert_eq!(result, Amount::ZERO); + } + + /// Tests that try_sum returns error on overflow. + #[test] + fn test_try_sum_overflow() { + let amounts = vec![Amount::from(u64::MAX), Amount::from(1)]; + let result = Amount::try_sum(amounts); + assert!(result.is_err()); + } + + /// Tests that split returns a non-empty vec with actual values, not defaults. + /// + /// The split function is used in split_targeted's while loop (line 122). + /// If split returns an empty vec or vec with Amount::ZERO when it shouldn't, + /// the loop that extends parts with split results would never make progress, + /// causing an infinite loop. + /// + /// Mutant testing: Kills mutations that replace split with `vec![]` or + /// `vec![Default::default()]` which would cause infinite loops. + #[test] + fn test_split_returns_correct_values() { + let fee_and_amounts = (0, (0..32).map(|x| 2u64.pow(x)).collect::>()).into(); + + let amount = Amount::from(11); + let result = amount.split(&fee_and_amounts); + assert!(!result.is_empty()); + assert_eq!(Amount::try_sum(result.iter().copied()).unwrap(), amount); + + let amount = Amount::from(255); + let result = amount.split(&fee_and_amounts); + assert!(!result.is_empty()); + assert_eq!(Amount::try_sum(result.iter().copied()).unwrap(), amount); + + let amount = Amount::from(7); + let result = amount.split(&fee_and_amounts); + assert_eq!( + result, + vec![Amount::from(4), Amount::from(2), Amount::from(1)] + ); + for r in &result { + assert_ne!(*r, Amount::ZERO); + } + } + + /// Tests that the modulo operation in split works correctly. + /// + /// At line 108, split uses modulo (%) to compute the remainder. + /// If this is mutated to division (/), it would produce wrong results + /// that could cause infinite loops in code that depends on split. + /// + /// Mutant testing: Kills mutations that replace `%` with `/`. + #[test] + fn test_split_modulo_operation() { + let fee_and_amounts = (0, (0..32).map(|x| 2u64.pow(x)).collect::>()).into(); + + let amount = Amount::from(15); + let result = amount.split(&fee_and_amounts); + + assert_eq!( + result, + vec![ + Amount::from(8), + Amount::from(4), + Amount::from(2), + Amount::from(1) + ] + ); + + let total = Amount::try_sum(result.iter().copied()).unwrap(); + assert_eq!(total, amount); + } + + /// Tests that From correctly converts values to Amount. + /// + /// This conversion is used throughout the codebase including in loops and split operations. + /// If it returns Default::default() (Amount::ZERO) instead of the actual value, + /// it can cause infinite loops where amounts are being accumulated or compared. + /// + /// Mutant testing: Kills mutations that replace From with `Default::default()`. + #[test] + fn test_from_u64_returns_correct_value() { + let amount = Amount::from(100u64); + assert_eq!(amount, Amount(100)); + assert_ne!(amount, Amount::ZERO); + + let amount = Amount::from(1u64); + assert_eq!(amount, Amount(1)); + assert_eq!(amount, Amount::ONE); + + let amount = Amount::from(1337u64); + assert_eq!(amount.to_u64(), 1337); + } } diff --git a/crates/cashu/src/dhke.rs b/crates/cashu/src/dhke.rs index 4e3680492..52bd74fde 100644 --- a/crates/cashu/src/dhke.rs +++ b/crates/cashu/src/dhke.rs @@ -388,4 +388,168 @@ mod tests { assert!(verify_message(&bob_sec, unblinded, &message).is_ok()); } + + /// Tests that `verify_message` correctly rejects verification when using an incorrect key. + /// + /// This test ensures that the verification process fails when attempting to verify + /// a signature with a different key than the one used to create it. This is critical + /// for security - if this check didn't exist, tokens could be forged by anyone. + /// + /// Mutant testing: Catches mutations that remove or weaken the key comparison logic + /// in `verify_message`, such as always returning Ok or ignoring the key parameter. + #[test] + fn test_verify_message_wrong_key() { + // Test that verify_message fails with wrong key + let message = b"test message"; + let correct_key = + SecretKey::from_hex("0000000000000000000000000000000000000000000000000000000000000001") + .unwrap(); + let wrong_key = + SecretKey::from_hex("0000000000000000000000000000000000000000000000000000000000000002") + .unwrap(); + + let (blinded, r) = blind_message(message, None).unwrap(); + let signed = sign_message(&correct_key, &blinded).unwrap(); + let unblinded = unblind_message(&signed, &r, &correct_key.public_key()).unwrap(); + + // Should fail with wrong key + assert!(verify_message(&wrong_key, unblinded, message).is_err()); + } + + /// Tests that `verify_message` correctly rejects verification when the message doesn't match. + /// + /// This test ensures that attempting to verify a signature against a different message + /// than the one originally signed results in an error. This prevents message substitution + /// attacks where an attacker might try to claim a signature for one message is valid + /// for a different message. + /// + /// Mutant testing: Catches mutations that remove or weaken the message comparison logic, + /// such as skipping the hash_to_curve step or ignoring the message parameter entirely. + #[test] + fn test_verify_message_wrong_message() { + // Test that verify_message fails with wrong message + let message = b"test message"; + let wrong_message = b"wrong message"; + let key = + SecretKey::from_hex("0000000000000000000000000000000000000000000000000000000000000001") + .unwrap(); + + let (blinded, r) = blind_message(message, None).unwrap(); + let signed = sign_message(&key, &blinded).unwrap(); + let unblinded = unblind_message(&signed, &r, &key.public_key()).unwrap(); + + // Should fail with wrong message + assert!(verify_message(&key, unblinded, wrong_message).is_err()); + } + + /// Tests that `construct_proofs` returns an error when input vectors have mismatched lengths. + /// + /// This test verifies that the function properly validates that the `promises`, `rs`, and + /// `secrets` vectors all have the same length before processing. This is essential for + /// correctness - each proof requires exactly one promise, one blinding factor (r), and + /// one secret. Mismatched lengths would indicate a programming error or corrupted data. + /// + /// Mutant testing: Catches mutations that remove or weaken the length validation check + /// at the beginning of `construct_proofs`, such as changing `!=` to `==` or removing + /// the validation entirely, which could lead to panics or incorrect proof construction. + #[test] + fn test_construct_proofs_length_mismatch() { + use std::collections::BTreeMap; + + use crate::nuts::nut02::Id; + use crate::Amount; + + // Test that construct_proofs fails when lengths don't match + let mut keys_map = BTreeMap::new(); + keys_map.insert(Amount::from(1), SecretKey::generate().public_key()); + let keys = Keys::new(keys_map); + + // Mismatched promises and rs lengths + let promise = BlindSignature { + amount: Amount::from(1), + c: SecretKey::generate().public_key(), + keyset_id: Id::from_str("00deadbeef123456").unwrap(), + dleq: None, + }; + let promises = vec![promise]; + let rs = vec![SecretKey::generate(), SecretKey::generate()]; // Different length + let secrets = vec![Secret::from_str("test").unwrap()]; + + let result = construct_proofs(promises, rs, secrets, &keys); + assert!(result.is_err()); + } + + /// Tests that `construct_proofs` returns the correct number of proof objects. + /// + /// This test verifies that when given N valid inputs (promises, blinding factors, secrets), + /// the function returns exactly N proofs, not zero or any other count. This ensures that + /// the loop in `construct_proofs` actually processes all inputs and accumulates results + /// correctly. + /// + /// Mutant testing: Specifically designed to catch mutations that replace the function body + /// with `Ok(Default::default())` or similar shortcuts that would return an empty vector + /// instead of processing the inputs. This is a common mutation that could pass tests that + /// only check for success without verifying the actual results. + #[test] + fn test_construct_proofs_returns_correct_count() { + use std::collections::BTreeMap; + + use crate::nuts::nut02::Id; + use crate::Amount; + + // Test that construct_proofs returns the correct number of proofs + let secret_key = SecretKey::generate(); + let mut keys_map = BTreeMap::new(); + keys_map.insert(Amount::from(1), secret_key.public_key()); + let keys = Keys::new(keys_map); + + let secret = Secret::from_str("test").unwrap(); + let (blinded_message, r) = blind_message(secret.as_bytes(), None).unwrap(); + let signature = sign_message(&secret_key, &blinded_message).unwrap(); + + let promise = BlindSignature { + amount: Amount::from(1), + c: signature, + keyset_id: Id::from_str("00deadbeef123456").unwrap(), + dleq: None, + }; + + let promises = vec![promise.clone(), promise.clone()]; + let rs = vec![r.clone(), r]; + let secrets = vec![secret.clone(), secret]; + + let proofs = construct_proofs(promises, rs, secrets, &keys).unwrap(); + + // Should return 2 proofs, not 0 (kills the Ok(Default::default()) mutant) + assert_eq!(proofs.len(), 2); + } + + /// Tests that hash_to_curve properly increments the counter and terminates. + /// + /// The hash_to_curve function uses a counter that increments in a loop at line 61. + /// If the counter increment is mutated (e.g., to `counter *= 1`), the loop would + /// never progress and would run until the timeout. + /// + /// This test uses a message that requires multiple iterations to find a valid point, + /// ensuring the counter increment logic is working correctly. + /// + /// Mutant testing: Kills mutations that replace `counter += 1` with `counter *= 1` + /// or other operations that don't advance the counter. + #[test] + fn test_hash_to_curve_counter_increments() { + // This specific message is documented in test_hash_to_curve as taking + // "a few iterations of the loop before finding a valid point" + let secret = "0000000000000000000000000000000000000000000000000000000000000002"; + let sec_hex = hex::decode(secret).unwrap(); + + let result = hash_to_curve(&sec_hex); + assert!(result.is_ok(), "hash_to_curve should find a valid point"); + + let y = result.unwrap(); + let expected_y = PublicKey::from_hex( + "026cdbe15362df59cd1dd3c9c11de8aedac2106eca69236ecd9fbe117af897be4f", + ) + .unwrap(); + assert_eq!(y, expected_y); + } } diff --git a/crates/cashu/src/nuts/nut12.rs b/crates/cashu/src/nuts/nut12.rs index 232368b04..6e4dfec8e 100644 --- a/crates/cashu/src/nuts/nut12.rs +++ b/crates/cashu/src/nuts/nut12.rs @@ -265,4 +265,157 @@ mod tests { assert!(proof.verify_dleq(a).is_ok()); } + + /// Tests that verify_dleq correctly rejects verification with a wrong mint key. + /// + /// This test is critical for security - if the verification function doesn't properly + /// check the mint key, an attacker could forge proofs using any key. + /// + /// Mutant testing: Catches mutations that replace verify_dleq with Ok(()) or remove + /// the verification logic. + #[test] + fn test_proof_dleq_wrong_mint_key() { + let proof = r#"{"amount": 1,"id": "00882760bfa2eb41","secret": "daf4dd00a2b68a0858a80450f52c8a7d2ccf87d375e43e216e0c571f089f63e9","C": "024369d2d22a80ecf78f3937da9d5f30c1b9f74f0c32684d583cca0fa6a61cdcfc","dleq": {"e": "b31e58ac6527f34975ffab13e70a48b6d2b0d35abc4b03f0151f09ee1a9763d4","s": "8fbae004c59e754d71df67e392b6ae4e29293113ddc2ec86592a0431d16306d8","r": "a6d13fcd7a18442e6076f5e1e7c887ad5de40a019824bdfa9fe740d302e8d861"}}"#; + + let proof: Proof = serde_json::from_str(proof).unwrap(); + + // Wrong mint key - different from the one used to create the proof + let wrong_key: PublicKey = PublicKey::from_str( + "02c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5", + ) + .unwrap(); + + // Verification should fail with wrong key + assert!(proof.verify_dleq(wrong_key).is_err()); + } + + /// Tests that verify_dleq correctly rejects proofs with missing DLEQ data. + /// + /// This test ensures that proofs without DLEQ data are rejected when DLEQ + /// verification is required. + /// + /// Mutant testing: Catches mutations that replace verify_dleq with Ok(()) or + /// remove the None check. + #[test] + fn test_proof_dleq_missing() { + let proof = r#"{"amount": 1,"id": "00882760bfa2eb41","secret": "daf4dd00a2b68a0858a80450f52c8a7d2ccf87d375e43e216e0c571f089f63e9","C": "024369d2d22a80ecf78f3937da9d5f30c1b9f74f0c32684d583cca0fa6a61cdcfc"}"#; + + let proof: Proof = serde_json::from_str(proof).unwrap(); + + let a: PublicKey = PublicKey::from_str( + "0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798", + ) + .unwrap(); + + // Verification should fail when DLEQ is missing + let result = proof.verify_dleq(a); + assert!(result.is_err()); + assert!(matches!(result.unwrap_err(), Error::MissingDleqProof)); + } + + /// Tests that BlindSignature::verify_dleq correctly rejects verification with wrong mint key. + /// + /// This test ensures that blind signature DLEQ verification properly validates the mint key. + /// + /// Mutant testing: Catches mutations that replace BlindSignature::verify_dleq with Ok(()) + /// or remove the verification logic. + #[test] + fn test_blind_signature_dleq_wrong_key() { + let blinded_sig = r#"{"amount":8,"id":"00882760bfa2eb41","C_":"02a9acc1e48c25eeeb9289b5031cc57da9fe72f3fe2861d264bdc074209b107ba2","dleq":{"e":"9818e061ee51d5c8edc3342369a554998ff7b4381c8652d724cdf46429be73d9","s":"9818e061ee51d5c8edc3342369a554998ff7b4381c8652d724cdf46429be73da"}}"#; + + let blinded: BlindSignature = serde_json::from_str(blinded_sig).unwrap(); + + // Wrong secret key - different from the one used to create the signature + let wrong_key = + SecretKey::from_hex("0000000000000000000000000000000000000000000000000000000000000002") + .unwrap(); + + let blinded_secret = PublicKey::from_str( + "02a9acc1e48c25eeeb9289b5031cc57da9fe72f3fe2861d264bdc074209b107ba2", + ) + .unwrap(); + + // Verification should fail with wrong key + assert!(blinded + .verify_dleq(wrong_key.public_key(), blinded_secret) + .is_err()); + } + + /// Tests that BlindSignature::verify_dleq correctly rejects verification with tampered DLEQ data. + /// + /// This test ensures that tampering with the 'e' or 's' values in the DLEQ proof + /// causes verification to fail. + /// + /// Mutant testing: Catches mutations that replace verify_dleq with Ok(()) or + /// weaken the cryptographic checks. + #[test] + fn test_blind_signature_dleq_tampered() { + // Tampered DLEQ data - 'e' and 's' values have been modified to wrong (but valid) values + let tampered_sig = r#"{"amount":8,"id":"00882760bfa2eb41","C_":"02a9acc1e48c25eeeb9289b5031cc57da9fe72f3fe2861d264bdc074209b107ba2","dleq":{"e":"0000000000000000000000000000000000000000000000000000000000000001","s":"0000000000000000000000000000000000000000000000000000000000000002"}}"#; + + let blinded: BlindSignature = serde_json::from_str(tampered_sig).unwrap(); + + let secret_key = + SecretKey::from_hex("0000000000000000000000000000000000000000000000000000000000000001") + .unwrap(); + + let blinded_secret = PublicKey::from_str( + "02a9acc1e48c25eeeb9289b5031cc57da9fe72f3fe2861d264bdc074209b107ba2", + ) + .unwrap(); + + // Verification should fail with tampered data + assert!(blinded + .verify_dleq(secret_key.public_key(), blinded_secret) + .is_err()); + } + + /// Tests that BlindSignature::add_dleq_proof properly generates DLEQ data. + /// + /// This test ensures that add_dleq_proof actually adds the DLEQ proof and doesn't + /// just return Ok(()) without doing anything. + /// + /// Mutant testing: Catches mutations that replace add_dleq_proof with Ok(()) + /// without actually adding the proof. + #[test] + fn test_add_dleq_proof() { + use crate::nuts::nut02::Id; + + let secret_key = + SecretKey::from_hex("0000000000000000000000000000000000000000000000000000000000000001") + .unwrap(); + + let blinded_message = PublicKey::from_str( + "02a9acc1e48c25eeeb9289b5031cc57da9fe72f3fe2861d264bdc074209b107ba2", + ) + .unwrap(); + + let blinded_signature = PublicKey::from_str( + "02a9acc1e48c25eeeb9289b5031cc57da9fe72f3fe2861d264bdc074209b107ba2", + ) + .unwrap(); + + let mut blind_sig = BlindSignature { + amount: Amount::from(1), + keyset_id: Id::from_str("00882760bfa2eb41").unwrap(), + c: blinded_signature, + dleq: None, + }; + + // Initially, DLEQ should be None + assert!(blind_sig.dleq.is_none()); + + // Add DLEQ proof + blind_sig + .add_dleq_proof(&blinded_message, &secret_key) + .unwrap(); + + // After adding, DLEQ should be Some + assert!(blind_sig.dleq.is_some()); + + // Verify the added DLEQ is valid + assert!(blind_sig + .verify_dleq(secret_key.public_key(), blinded_message) + .is_ok()); + } } diff --git a/crates/cashu/src/nuts/nut14/mod.rs b/crates/cashu/src/nuts/nut14/mod.rs index 4204545f5..0c3c8ea1d 100644 --- a/crates/cashu/src/nuts/nut14/mod.rs +++ b/crates/cashu/src/nuts/nut14/mod.rs @@ -166,3 +166,286 @@ impl Proof { })) } } + +#[cfg(test)] +mod tests { + use super::*; + use crate::nuts::nut00::Witness; + use crate::nuts::nut10::Kind; + use crate::nuts::Nut10Secret; + use crate::secret::Secret as SecretString; + + /// Tests that verify_htlc correctly accepts a valid HTLC with the correct preimage. + /// + /// This test ensures that a properly formed HTLC proof with the correct preimage + /// passes verification. + /// + /// Mutant testing: Combined with negative tests, this catches mutations that + /// replace verify_htlc with Ok(()) since the negative tests will fail. + #[test] + fn test_verify_htlc_valid() { + // Create a valid HTLC secret with a known preimage (32 bytes) + let preimage_bytes = [42u8; 32]; // 32-byte preimage + let hash = Sha256Hash::hash(&preimage_bytes); + let hash_str = hash.to_string(); + + let nut10_secret = Nut10Secret::new(Kind::HTLC, hash_str, None::>>); + let secret: SecretString = nut10_secret.try_into().unwrap(); + + let htlc_witness = HTLCWitness { + preimage: hex::encode(&preimage_bytes), + signatures: None, + }; + + let proof = Proof { + amount: crate::Amount::from(1), + keyset_id: crate::nuts::nut02::Id::from_str("00deadbeef123456").unwrap(), + secret, + c: crate::nuts::nut01::PublicKey::from_hex( + "02a9acc1e48c25eeeb9289b5031cc57da9fe72f3fe2861d264bdc074209b107ba2", + ) + .unwrap(), + witness: Some(Witness::HTLCWitness(htlc_witness)), + dleq: None, + }; + + // Valid HTLC should verify successfully + assert!(proof.verify_htlc().is_ok()); + } + + /// Tests that verify_htlc correctly rejects an HTLC with a wrong preimage. + /// + /// This test is critical for security - if the verification function doesn't properly + /// check the preimage against the hash, an attacker could spend HTLC-locked funds + /// without knowing the correct preimage. + /// + /// Mutant testing: Catches mutations that replace verify_htlc with Ok(()) or remove + /// the preimage verification logic. + #[test] + fn test_verify_htlc_wrong_preimage() { + // Create an HTLC secret with a specific hash (32 bytes) + let correct_preimage_bytes = [42u8; 32]; + let hash = Sha256Hash::hash(&correct_preimage_bytes); + let hash_str = hash.to_string(); + + let nut10_secret = Nut10Secret::new(Kind::HTLC, hash_str, None::>>); + let secret: SecretString = nut10_secret.try_into().unwrap(); + + // Use a different preimage in the witness + let wrong_preimage_bytes = [99u8; 32]; // Different from correct preimage + let htlc_witness = HTLCWitness { + preimage: hex::encode(&wrong_preimage_bytes), + signatures: None, + }; + + let proof = Proof { + amount: crate::Amount::from(1), + keyset_id: crate::nuts::nut02::Id::from_str("00deadbeef123456").unwrap(), + secret, + c: crate::nuts::nut01::PublicKey::from_hex( + "02a9acc1e48c25eeeb9289b5031cc57da9fe72f3fe2861d264bdc074209b107ba2", + ) + .unwrap(), + witness: Some(Witness::HTLCWitness(htlc_witness)), + dleq: None, + }; + + // Verification should fail with wrong preimage + let result = proof.verify_htlc(); + assert!(result.is_err()); + assert!(matches!(result.unwrap_err(), Error::Preimage)); + } + + /// Tests that verify_htlc correctly rejects an HTLC with an invalid hash format. + /// + /// This test ensures that the verification function properly validates that the + /// hash in the secret data is a valid SHA256 hash. + /// + /// Mutant testing: Catches mutations that replace verify_htlc with Ok(()) or + /// remove the hash validation logic. + #[test] + fn test_verify_htlc_invalid_hash() { + // Create an HTLC secret with an invalid hash (not a valid hex string) + let invalid_hash = "not_a_valid_hash"; + + let nut10_secret = Nut10Secret::new( + Kind::HTLC, + invalid_hash.to_string(), + None::>>, + ); + let secret: SecretString = nut10_secret.try_into().unwrap(); + + let preimage_bytes = [42u8; 32]; // Valid 32-byte preimage + let htlc_witness = HTLCWitness { + preimage: hex::encode(&preimage_bytes), + signatures: None, + }; + + let proof = Proof { + amount: crate::Amount::from(1), + keyset_id: crate::nuts::nut02::Id::from_str("00deadbeef123456").unwrap(), + secret, + c: crate::nuts::nut01::PublicKey::from_hex( + "02a9acc1e48c25eeeb9289b5031cc57da9fe72f3fe2861d264bdc074209b107ba2", + ) + .unwrap(), + witness: Some(Witness::HTLCWitness(htlc_witness)), + dleq: None, + }; + + // Verification should fail with invalid hash + let result = proof.verify_htlc(); + assert!(result.is_err()); + assert!(matches!(result.unwrap_err(), Error::InvalidHash)); + } + + /// Tests that verify_htlc correctly rejects an HTLC with the wrong witness type. + /// + /// This test ensures that the verification function checks that the witness is + /// of the correct type (HTLCWitness) and not some other witness type. + /// + /// Mutant testing: Catches mutations that replace verify_htlc with Ok(()) or + /// remove the witness type check. + #[test] + fn test_verify_htlc_wrong_witness_type() { + // Create an HTLC secret + let preimage = "test_preimage"; + let hash = Sha256Hash::hash(preimage.as_bytes()); + let hash_str = hash.to_string(); + + let nut10_secret = Nut10Secret::new(Kind::HTLC, hash_str, None::>>); + let secret: SecretString = nut10_secret.try_into().unwrap(); + + // Create proof with wrong witness type (P2PKWitness instead of HTLCWitness) + let proof = Proof { + amount: crate::Amount::from(1), + keyset_id: crate::nuts::nut02::Id::from_str("00deadbeef123456").unwrap(), + secret, + c: crate::nuts::nut01::PublicKey::from_hex( + "02a9acc1e48c25eeeb9289b5031cc57da9fe72f3fe2861d264bdc074209b107ba2", + ) + .unwrap(), + witness: Some(Witness::P2PKWitness(super::super::nut11::P2PKWitness { + signatures: vec![], + })), + dleq: None, + }; + + // Verification should fail with wrong witness type + let result = proof.verify_htlc(); + assert!(result.is_err()); + assert!(matches!(result.unwrap_err(), Error::IncorrectSecretKind)); + } + + /// Tests that add_preimage correctly adds a preimage to the proof. + /// + /// This test ensures that add_preimage actually modifies the witness and doesn't + /// just return without doing anything. + /// + /// Mutant testing: Catches mutations that replace add_preimage with () without + /// actually adding the preimage. + #[test] + fn test_add_preimage() { + let preimage_bytes = [42u8; 32]; // 32-byte preimage + let hash = Sha256Hash::hash(&preimage_bytes); + let hash_str = hash.to_string(); + + let nut10_secret = Nut10Secret::new(Kind::HTLC, hash_str, None::>>); + let secret: SecretString = nut10_secret.try_into().unwrap(); + + let mut proof = Proof { + amount: crate::Amount::from(1), + keyset_id: crate::nuts::nut02::Id::from_str("00deadbeef123456").unwrap(), + secret, + c: crate::nuts::nut01::PublicKey::from_hex( + "02a9acc1e48c25eeeb9289b5031cc57da9fe72f3fe2861d264bdc074209b107ba2", + ) + .unwrap(), + witness: None, + dleq: None, + }; + + // Initially, witness should be None + assert!(proof.witness.is_none()); + + // Add preimage (hex-encoded) + let preimage_hex = hex::encode(&preimage_bytes); + proof.add_preimage(preimage_hex.clone()); + + // After adding, witness should be Some with HTLCWitness + assert!(proof.witness.is_some()); + if let Some(Witness::HTLCWitness(witness)) = &proof.witness { + assert_eq!(witness.preimage, preimage_hex); + } else { + panic!("Expected HTLCWitness"); + } + + // The proof with added preimage should verify successfully + assert!(proof.verify_htlc().is_ok()); + } + + /// Tests that verify_htlc requires BOTH locktime expired AND no refund keys for "anyone can spend". + /// + /// This test catches the mutation that replaces `&&` with `||` at line 83. + /// The logic should be: (locktime expired AND no refund keys) → anyone can spend. + /// If mutated to OR, it would allow spending when locktime passed even if refund keys exist. + /// + /// Mutant testing: Catches mutations that replace `&&` with `||` in the locktime check. + #[test] + fn test_htlc_locktime_and_refund_keys_logic() { + use crate::nuts::nut01::PublicKey; + use crate::nuts::nut11::Conditions; + + let preimage_bytes = [42u8; 32]; // 32-byte preimage + let hash = Sha256Hash::hash(&preimage_bytes); + let hash_str = hash.to_string(); + + // Test: Locktime has passed (locktime=1) but refund keys ARE present + // With correct logic (&&): Since refund_keys.is_none() is false, the "anyone can spend" + // path is NOT taken, so signature is required + // With mutation (||): Since locktime.lt(&unix_time()) is true, it WOULD take the + // "anyone can spend" path immediately - WRONG! + let refund_pubkey = PublicKey::from_hex( + "02a9acc1e48c25eeeb9289b5031cc57da9fe72f3fe2861d264bdc074209b107ba2", + ) + .unwrap(); + + let conditions_with_refund = Conditions { + locktime: Some(1), // Locktime in past (current time is much larger) + pubkeys: None, + refund_keys: Some(vec![refund_pubkey]), // Refund key present + num_sigs: None, + sig_flag: crate::nuts::nut11::SigFlag::default(), + num_sigs_refund: None, + }; + + let nut10_secret = Nut10Secret::new(Kind::HTLC, hash_str, Some(conditions_with_refund)); + let secret: SecretString = nut10_secret.try_into().unwrap(); + + let htlc_witness = HTLCWitness { + preimage: hex::encode(&preimage_bytes), + signatures: None, // No signature provided + }; + + let proof = Proof { + amount: crate::Amount::from(1), + keyset_id: crate::nuts::nut02::Id::from_str("00deadbeef123456").unwrap(), + secret, + c: crate::nuts::nut01::PublicKey::from_hex( + "02a9acc1e48c25eeeb9289b5031cc57da9fe72f3fe2861d264bdc074209b107ba2", + ) + .unwrap(), + witness: Some(Witness::HTLCWitness(htlc_witness)), + dleq: None, + }; + + // Should FAIL because even though locktime passed, refund keys are present + // so the "anyone can spend" shortcut shouldn't apply. A signature is required. + // With && this correctly fails. With || it would incorrectly pass. + let result = proof.verify_htlc(); + assert!( + result.is_err(), + "Should fail when locktime passed but refund keys present without signature" + ); + } +} diff --git a/flake.nix b/flake.nix index ce2cc72cb..38c7a2be2 100644 --- a/flake.nix +++ b/flake.nix @@ -109,9 +109,11 @@ clightning bitcoind sqlx-cli - cargo-outdated mprocs + cargo-outdated + cargo-mutants + # Needed for github ci libz ] diff --git a/justfile b/justfile index 1e79e7913..b52f0e5fc 100644 --- a/justfile +++ b/justfile @@ -87,10 +87,89 @@ test-all db="memory": ./misc/fake_itests.sh "{{db}}" external_signatory ./misc/fake_itests.sh "{{db}}" +# Mutation Testing Commands + +# Run mutation tests on a specific crate +# Usage: just mutants +# Example: just mutants cashu +mutants CRATE: + #!/usr/bin/env bash + set -euo pipefail + echo "Running mutation tests on crate: {{CRATE}}" + cargo mutants --package {{CRATE}} -vV + +# Run mutation tests on the cashu crate +mutants-cashu: + #!/usr/bin/env bash + set -euo pipefail + echo "Running mutation tests on cashu crate..." + cargo mutants --package cashu -vV + +# Run mutation tests on the cdk crate +mutants-cdk: + #!/usr/bin/env bash + set -euo pipefail + echo "Running mutation tests on cdk crate..." + cargo mutants --package cdk -vV + +# Run mutation tests on entire workspace (WARNING: very slow) +mutants-all: + #!/usr/bin/env bash + set -euo pipefail + echo "Running mutation tests on entire workspace..." + echo "WARNING: This may take a very long time!" + cargo mutants -vV + +# Quick mutation test for current work (alias for mutants-diff) +mutants-quick: + #!/usr/bin/env bash + set -euo pipefail + echo "Running mutations on changed files since HEAD..." + cargo mutants --in-diff HEAD -vV + +# Run mutation tests only on changed code since HEAD +mutants-diff: + #!/usr/bin/env bash + set -euo pipefail + echo "Running mutation tests on changed code..." + cargo mutants --in-diff HEAD -vV + +# Run mutation tests and save output to log file +# Usage: just mutants-log +# Example: just mutants-log cashu baseline +mutants-log CRATE SUFFIX: + #!/usr/bin/env bash + set -euo pipefail + if [ ! -f Cargo.toml ]; then + cd {{invocation_directory()}} + fi + LOG_FILE="mutants-{{CRATE}}-{{SUFFIX}}.log" + echo "Running mutation tests on {{CRATE}}, saving to $LOG_FILE..." + cargo mutants --package {{CRATE}} -vV 2>&1 | tee "$LOG_FILE" + echo "Results saved to $LOG_FILE" + +# Mutation test with baseline comparison +# Usage: just mutants-check +# Example: just mutants-check cashu +mutants-check CRATE: + #!/usr/bin/env bash + set -euo pipefail + BASELINE="mutants-{{CRATE}}-baseline.log" + if [ ! -f "$BASELINE" ]; then + echo "ERROR: No baseline found at $BASELINE" + echo "Run: just mutants-log {{CRATE}} baseline" + exit 1 + fi + cargo mutants --package {{CRATE}} -vV | tee mutants-{{CRATE}}-current.log + # Compare results + echo "=== Baseline vs Current ===" + diff <(grep "^CAUGHT\|^MISSED" "$BASELINE" | wc -l) \ + <(grep "^CAUGHT\|^MISSED" mutants-{{CRATE}}-current.log | wc -l) || true + test-nutshell: #!/usr/bin/env bash set -euo pipefail - + # Function to cleanup docker containers cleanup() { echo "Cleaning up docker containers..." From 9eaa6f1c02dac511b9f3a50516a7ce0ce6af1833 Mon Sep 17 00:00:00 2001 From: SatsAndSports Date: Fri, 14 Nov 2025 21:39:46 +0100 Subject: [PATCH 264/321] feat: update NUT-11 SIG_ALL message aggregation per spec Implements changes from cashubtc/nuts#302 which updates the SIG_ALL message aggregation scheme for spending condition verification. SIG_ALL Message Changes: - Update message format to: secret || C || amount || B_ - Initially added keyset_id to outputs (amount || keyset_id || B_) - Removed keyset_id per final spec (amount || B_) - Applied to both swap (NUT-03) and melt (NUT-05) operations Architecture Improvements: - Introduce NUT-10 SpendingConditionVerification trait for unified verification logic across swap and melt operations - Refactor NUT-11 (P2PK) and NUT-14 (HTLC) verification to share common code paths - Add helper functions for pubkey/signature extraction with proper locktime handling - Improve error handling with specific error types (PreimageNotSupportedInP2PK, SpendConditionsNotMet) - Deprecate old verify_sig_all methods in favor of unified trait Test Coverage: - Add comprehensive test vectors for P2PK + SIG_ALL combinations - Add comprehensive test vectors for HTLC + SIG_ALL combinations - Add test helpers for spending condition verification - Cover multisig, locktime, refund keys, and mixed scenarios - Test vectors aligned with other implementations (nutshell, cashu-ts) --------- Co-authored-by: Sats And Sports Co-authored-by: thesimplekid --- crates/cashu/src/nuts/mod.rs | 2 +- crates/cashu/src/nuts/nut00/mod.rs | 11 +- crates/cashu/src/nuts/nut03.rs | 26 + crates/cashu/src/nuts/nut05.rs | 40 +- crates/cashu/src/nuts/nut10.rs | 428 +++++ crates/cashu/src/nuts/nut11/mod.rs | 1080 +++++++----- crates/cashu/src/nuts/nut14/mod.rs | 156 +- crates/cdk-signatory/src/signatory.rs | 2 +- crates/cdk/src/lib.rs | 6 +- crates/cdk/src/mint/{melt.rs => melt/mod.rs} | 16 +- .../htlc_sigall_spending_conditions_tests.rs | 181 +++ .../tests/htlc_spending_conditions_tests.rs | 190 +++ .../locktime_spending_conditions_tests.rs | 277 ++++ crates/cdk/src/mint/melt/tests/mod.rs | 5 + .../p2pk_sigall_spending_conditions_tests.rs | 167 ++ .../tests/p2pk_spending_conditions_tests.rs | 135 ++ crates/cdk/src/mint/mod.rs | 36 +- crates/cdk/src/mint/swap/mod.rs | 27 +- .../htlc_sigall_spending_conditions_tests.rs | 389 +++++ .../tests/htlc_spending_conditions_tests.rs | 396 +++++ crates/cdk/src/mint/swap/tests/mod.rs | 4 + .../p2pk_sigall_spending_conditions_tests.rs | 1441 +++++++++++++++++ .../tests/p2pk_spending_conditions_tests.rs | 804 +++++++++ crates/cdk/src/test_helpers/mod.rs | 2 + crates/cdk/src/test_helpers/nut10.rs | 145 ++ 25 files changed, 5387 insertions(+), 579 deletions(-) rename crates/cdk/src/mint/{melt.rs => melt/mod.rs} (97%) create mode 100644 crates/cdk/src/mint/melt/tests/htlc_sigall_spending_conditions_tests.rs create mode 100644 crates/cdk/src/mint/melt/tests/htlc_spending_conditions_tests.rs create mode 100644 crates/cdk/src/mint/melt/tests/locktime_spending_conditions_tests.rs create mode 100644 crates/cdk/src/mint/melt/tests/mod.rs create mode 100644 crates/cdk/src/mint/melt/tests/p2pk_sigall_spending_conditions_tests.rs create mode 100644 crates/cdk/src/mint/melt/tests/p2pk_spending_conditions_tests.rs create mode 100644 crates/cdk/src/mint/swap/tests/htlc_sigall_spending_conditions_tests.rs create mode 100644 crates/cdk/src/mint/swap/tests/htlc_spending_conditions_tests.rs create mode 100644 crates/cdk/src/mint/swap/tests/mod.rs create mode 100644 crates/cdk/src/mint/swap/tests/p2pk_sigall_spending_conditions_tests.rs create mode 100644 crates/cdk/src/mint/swap/tests/p2pk_spending_conditions_tests.rs create mode 100644 crates/cdk/src/test_helpers/nut10.rs diff --git a/crates/cashu/src/nuts/mod.rs b/crates/cashu/src/nuts/mod.rs index 658887f5f..92ad1588d 100644 --- a/crates/cashu/src/nuts/mod.rs +++ b/crates/cashu/src/nuts/mod.rs @@ -54,7 +54,7 @@ pub use nut05::{ pub use nut06::{ContactInfo, MintInfo, MintVersion, Nuts}; pub use nut07::{CheckStateRequest, CheckStateResponse, ProofState, State}; pub use nut09::{RestoreRequest, RestoreResponse}; -pub use nut10::{Kind, Secret as Nut10Secret, SecretData}; +pub use nut10::{Kind, Secret as Nut10Secret, SecretData, SpendingConditionVerification}; pub use nut11::{Conditions, P2PKWitness, SigFlag, SpendingConditions}; pub use nut12::{BlindSignatureDleq, ProofDleq}; pub use nut14::HTLCWitness; diff --git a/crates/cashu/src/nuts/nut00/mod.rs b/crates/cashu/src/nuts/nut00/mod.rs index 5b4e76b45..f9364874c 100644 --- a/crates/cashu/src/nuts/nut00/mod.rs +++ b/crates/cashu/src/nuts/nut00/mod.rs @@ -306,13 +306,10 @@ impl Witness { pub fn add_signatures(&mut self, signatues: Vec) { match self { Self::P2PKWitness(p2pk_witness) => p2pk_witness.signatures.extend(signatues), - Self::HTLCWitness(htlc_witness) => { - htlc_witness.signatures = htlc_witness.signatures.clone().map(|sigs| { - let mut sigs = sigs; - sigs.extend(signatues); - sigs - }); - } + Self::HTLCWitness(htlc_witness) => match &mut htlc_witness.signatures { + Some(sigs) => sigs.extend(signatues), + None => htlc_witness.signatures = Some(signatues), + }, } } diff --git a/crates/cashu/src/nuts/nut03.rs b/crates/cashu/src/nuts/nut03.rs index 5dfa974ae..7c6fe44ea 100644 --- a/crates/cashu/src/nuts/nut03.rs +++ b/crates/cashu/src/nuts/nut03.rs @@ -91,6 +91,32 @@ impl SwapRequest { } } +impl super::nut10::SpendingConditionVerification for SwapRequest { + fn inputs(&self) -> &Proofs { + &self.inputs + } + + fn sig_all_msg_to_sign(&self) -> String { + let mut msg = String::new(); + + // Add all input secrets and C values in order + // msg = secret_0 || C_0 || ... || secret_n || C_n + for proof in &self.inputs { + msg.push_str(&proof.secret.to_string()); + msg.push_str(&proof.c.to_hex()); + } + + // Add all output amounts and B_ values in order + // msg = ... || amount_0 || B_0 || ... || amount_m || B_m + for output in &self.outputs { + msg.push_str(&output.amount.to_string()); + msg.push_str(&output.blinded_secret.to_hex()); + } + + msg + } +} + /// Split Response [NUT-06] #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] #[cfg_attr(feature = "swagger", derive(utoipa::ToSchema))] diff --git a/crates/cashu/src/nuts/nut05.rs b/crates/cashu/src/nuts/nut05.rs index 56fd3fdeb..e2b5b8d27 100644 --- a/crates/cashu/src/nuts/nut05.rs +++ b/crates/cashu/src/nuts/nut05.rs @@ -129,7 +129,10 @@ impl MeltRequest { } } -impl MeltRequest { +impl MeltRequest +where + Q: Serialize + DeserializeOwned, +{ /// Create new [`MeltRequest`] pub fn new(quote: Q, inputs: Proofs, outputs: Option>) -> Self { Self { @@ -151,6 +154,41 @@ impl MeltRequest { } } +impl super::nut10::SpendingConditionVerification for MeltRequest +where + Q: std::fmt::Display, +{ + fn inputs(&self) -> &Proofs { + &self.inputs + } + + fn sig_all_msg_to_sign(&self) -> String { + let mut msg = String::new(); + + // Add all input secrets and C values in order + // msg = secret_0 || C_0 || ... || secret_n || C_n + for proof in &self.inputs { + msg.push_str(&proof.secret.to_string()); + msg.push_str(&proof.c.to_hex()); + } + + // Add all output amounts and B_ values in order (if any) + // msg = ... || amount_0 || B_0 || ... || amount_m || B_m + if let Some(outputs) = &self.outputs { + for output in outputs { + msg.push_str(&output.amount.to_string()); + msg.push_str(&output.blinded_secret.to_hex()); + } + } + + // Add quote ID + // msg = ... || quote_id + msg.push_str(&self.quote.to_string()); + + msg + } +} + /// Melt Method Settings #[derive(Debug, Default, Clone, PartialEq, Eq, Hash)] #[cfg_attr(feature = "swagger", derive(utoipa::ToSchema))] diff --git a/crates/cashu/src/nuts/nut10.rs b/crates/cashu/src/nuts/nut10.rs index 783c31d5c..8b84c5820 100644 --- a/crates/cashu/src/nuts/nut10.rs +++ b/crates/cashu/src/nuts/nut10.rs @@ -10,6 +10,9 @@ use serde::ser::SerializeTuple; use serde::{Deserialize, Serialize, Serializer}; use thiserror::Error; +use super::nut01::PublicKey; +use super::Conditions; + /// NUT13 Error #[derive(Debug, Error)] pub enum Error { @@ -105,6 +108,431 @@ impl Secret { } } +/// Get the relevant public keys and required signature count for P2PK or HTLC verification +/// This is for NUT-11(P2PK) and NUT-14(HTLC) +/// +/// Takes into account locktime - if locktime has passed, returns refund keys, +/// otherwise returns primary pubkeys/hash path. +/// From NUT-11: "If the tag locktime is the unix time and the mint's local clock is greater than +/// locktime, the Proof becomes spendable by anyone, except [... if refund keys are specified]" +/// +/// Returns (preimage_needed, pubkeys, required_sigs). +/// For P2PK, preimage_needed is always false. +/// For HTLC, preimage_needed is true before locktime; From NUT-14: "if the current system time +/// is later than Secret.tag.locktime, the Proof can be spent if Proof.witness includes +/// a signature from the key in Secret.tags.refund." +pub(crate) fn get_pubkeys_and_required_sigs( + secret: &Secret, + current_time: u64, +) -> Result<(bool, Vec, u64), super::nut11::Error> { + debug_assert!( + secret.kind() == Kind::P2PK || secret.kind() == Kind::HTLC, + "get_pubkeys_and_required_sigs called with invalid kind - this is a bug" + ); + + let conditions: Conditions = secret + .secret_data() + .tags() + .cloned() + .unwrap_or_default() + .try_into()?; + + // Check if locktime has passed + let locktime_passed = conditions + .locktime + .map(|locktime| locktime < current_time) + .unwrap_or(false); + + // Determine which keys and signature count to use + if locktime_passed { + // After locktime: use refund path (no preimage needed) + if let Some(refund_keys) = &conditions.refund_keys { + // Locktime has passed and refund keys exist - use refund keys + let refund_sigs = conditions.num_sigs_refund.unwrap_or(1); + Ok((false, refund_keys.clone(), refund_sigs)) + } else { + // Locktime has passed with no refund keys - anyone can spend + Ok((false, vec![], 0)) + } + } else { + // Before locktime: logic differs between P2PK and HTLC + match secret.kind() { + Kind::P2PK => { + // P2PK: never needs preimage, use primary pubkeys + let mut primary_keys = vec![]; + + // Add the pubkey from secret.data + let data_pubkey = PublicKey::from_str(secret.secret_data().data())?; + primary_keys.push(data_pubkey); + + // Add any additional pubkeys from conditions + if let Some(additional_keys) = &conditions.pubkeys { + primary_keys.extend(additional_keys.clone()); + } + + let primary_num_sigs_required = conditions.num_sigs.unwrap_or(1); + Ok((false, primary_keys, primary_num_sigs_required)) + } + Kind::HTLC => { + // HTLC: needs preimage before locktime, pubkeys from conditions + // (data contains hash, not pubkey) + let pubkeys = conditions.pubkeys.clone().unwrap_or_default(); + let required_sigs = conditions.num_sigs.unwrap_or(1); + Ok((true, pubkeys, required_sigs)) + } + } + } +} + +use super::Proofs; + +/// Verify that a preimage matches the hash in the secret data +/// +/// The preimage should be a 64-character hex string representing 32 bytes. +/// We decode it from hex, hash it with SHA256, and compare to the hash in secret.data +pub fn verify_htlc_preimage( + witness: &super::nut14::HTLCWitness, + secret: &Secret, +) -> Result<(), super::nut14::Error> { + use bitcoin::hashes::sha256::Hash as Sha256Hash; + use bitcoin::hashes::Hash; + + // Get the hash lock from the secret data + let hash_lock = Sha256Hash::from_str(secret.secret_data().data()) + .map_err(|_| super::nut14::Error::InvalidHash)?; + + // Decode and validate the preimage (returns [u8; 32]) + let preimage_bytes = witness.preimage_data()?; + + // Hash the 32-byte preimage + let preimage_hash = Sha256Hash::hash(&preimage_bytes); + + // Compare with the hash lock + if hash_lock.ne(&preimage_hash) { + return Err(super::nut14::Error::Preimage); + } + + Ok(()) +} + +/// Trait for requests that spend proofs (SwapRequest, MeltRequest) +pub trait SpendingConditionVerification { + /// Get the input proofs + fn inputs(&self) -> &Proofs; + + /// Construct the message to sign for SIG_ALL verification + /// + /// This concatenates all relevant transaction data that must be signed. + /// For swap: input secrets + output blinded messages + /// For melt: input secrets + quote/payment request + fn sig_all_msg_to_sign(&self) -> String; + + /// Check if at least one proof in the set has SIG_ALL flag set + /// + /// SIG_ALL requires all proofs in the transaction to be signed. + /// If any proof has this flag, we need to verify signatures on all proofs. + fn has_at_least_one_sig_all(&self) -> Result { + for proof in self.inputs() { + // Try to extract spending conditions from the proof's secret + if let Ok(spending_conditions) = super::SpendingConditions::try_from(&proof.secret) { + // Check for SIG_ALL flag in either P2PK or HTLC conditions + let has_sig_all = match spending_conditions { + super::SpendingConditions::P2PKConditions { conditions, .. } => conditions + .map(|c| c.sig_flag == super::SigFlag::SigAll) + .unwrap_or(false), + super::SpendingConditions::HTLCConditions { conditions, .. } => conditions + .map(|c| c.sig_flag == super::SigFlag::SigAll) + .unwrap_or(false), + }; + + if has_sig_all { + return Ok(true); + } + } + } + + Ok(false) + } + + /// Verify all inputs meet SIG_ALL requirements per NUT-11 + /// + /// When any input has SIG_ALL, all inputs must have: + /// 1. Same kind (P2PK or HTLC) + /// 2. SIG_ALL flag set + /// 3. Same Secret.data + /// 4. Same Secret.tags + fn verify_all_inputs_match_for_sig_all(&self) -> Result<(), super::nut11::Error> { + let inputs = self.inputs(); + + if inputs.is_empty() { + return Err(super::nut11::Error::SpendConditionsNotMet); + } + + // Get first input's properties + let first_input = inputs.first().unwrap(); + let first_secret = Secret::try_from(&first_input.secret) + .map_err(|_| super::nut11::Error::IncorrectSecretKind)?; + let first_kind = first_secret.kind(); + let first_data = first_secret.secret_data().data(); + let first_tags = first_secret.secret_data().tags(); + + // Get first input's conditions to check SIG_ALL flag + let first_conditions = + super::Conditions::try_from(first_tags.cloned().unwrap_or_default())?; + + // Verify first input has SIG_ALL (it should, since we only call this function when SIG_ALL is detected) + if first_conditions.sig_flag != super::SigFlag::SigAll { + return Err(super::nut11::Error::SpendConditionsNotMet); + } + + // Verify all remaining inputs match + for proof in inputs.iter().skip(1) { + let secret = Secret::try_from(&proof.secret) + .map_err(|_| super::nut11::Error::IncorrectSecretKind)?; + + // Check kind matches + if secret.kind() != first_kind { + return Err(super::nut11::Error::SpendConditionsNotMet); + } + + // Check data matches + if secret.secret_data().data() != first_data { + return Err(super::nut11::Error::SpendConditionsNotMet); + } + + // Check tags match (this also ensures SIG_ALL flag matches, since sig_flag is part of tags) + if secret.secret_data().tags() != first_tags { + return Err(super::nut11::Error::SpendConditionsNotMet); + } + } + + Ok(()) + } + + /// Verify spending conditions for this transaction + /// + /// This is the main entry point for spending condition verification. + /// It checks if any input has SIG_ALL and dispatches to the appropriate verification path. + fn verify_spending_conditions(&self) -> Result<(), super::nut11::Error> { + // Check if any input has SIG_ALL flag + if self.has_at_least_one_sig_all()? { + // at least one input has SIG_ALL + self.verify_full_sig_all_check() + } else { + // none of the inputs are SIG_ALL, so we can simply check + // each independently and verify any spending conditions + // that may - or may not - be there. + self.verify_inputs_individually().map_err(|e| match e { + super::nut14::Error::NUT11(nut11_err) => nut11_err, + _ => super::nut11::Error::SpendConditionsNotMet, + }) + } + } + + /// Verify spending conditions when SIG_ALL is present + /// + /// When SIG_ALL is set, all proofs in the transaction must be signed together. + fn verify_full_sig_all_check(&self) -> Result<(), super::nut11::Error> { + debug_assert!( + self.has_at_least_one_sig_all()?, + "verify_full_sig_all_check() called on proofs without SIG_ALL. This shouldn't happen" + ); + // Verify all inputs meet SIG_ALL requirements per NUT-11: + // All inputs must have: (1) same kind, (2) SIG_ALL flag, (3) same data, (4) same tags + self.verify_all_inputs_match_for_sig_all()?; + + // Get the first input to determine the kind + let first_input = self + .inputs() + .first() + .ok_or(super::nut11::Error::SpendConditionsNotMet)?; + let first_secret = Secret::try_from(&first_input.secret) + .map_err(|_| super::nut11::Error::IncorrectSecretKind)?; + + // Dispatch based on secret kind + match first_secret.kind() { + Kind::P2PK => { + self.verify_sig_all_p2pk()?; + } + Kind::HTLC => { + self.verify_sig_all_htlc()?; + } + } + + Ok(()) + } + + /// Verify spending conditions for each input individually + /// + /// Handles SIG_INPUTS mode, non-NUT-10 secrets, and any other case where inputs + /// are verified independently rather than as a group. + /// This function will NOT be called if any input has SIG_ALL. + fn verify_inputs_individually(&self) -> Result<(), super::nut14::Error> { + debug_assert!( + !(self.has_at_least_one_sig_all()?), + "verify_inputs_individually() called on SIG_ALL. This shouldn't happen" + ); + for proof in self.inputs() { + // Check if secret is a nut10 secret with conditions + if let Ok(secret) = Secret::try_from(&proof.secret) { + // Verify this function isn't being called with SIG_ALL proofs (development check) + if let Ok(conditions) = super::Conditions::try_from( + secret.secret_data().tags().cloned().unwrap_or_default(), + ) { + debug_assert!( + conditions.sig_flag != super::SigFlag::SigAll, + "verify_inputs_individually called with SIG_ALL proof - this is a bug" + ); + } + + match secret.kind() { + Kind::P2PK => { + proof.verify_p2pk()?; + } + Kind::HTLC => { + proof.verify_htlc()?; + } + } + } + // If not a nut10 secret, skip verification (plain secret) + } + Ok(()) + } + + /// Verify P2PK SIG_ALL signatures + /// + /// Do NOT call this directly. This is called only from 'verify_full_sig_all_check', + /// which has already done many important SIG_ALL checks. This performs the final + /// signature verification for SIG_ALL+P2PK transactions. + fn verify_sig_all_p2pk(&self) -> Result<(), super::nut11::Error> { + // Get the first input, as it's the one with the signatures + let first_input = self + .inputs() + .first() + .ok_or(super::nut11::Error::SpendConditionsNotMet)?; + let first_secret = Secret::try_from(&first_input.secret) + .map_err(|_| super::nut11::Error::IncorrectSecretKind)?; + + // Record current time for locktime evaluation + let current_time = crate::util::unix_time(); + + // Get the relevant public keys and required signature count based on locktime + let (preimage_needed, pubkeys, required_sigs) = + get_pubkeys_and_required_sigs(&first_secret, current_time)?; + + debug_assert!(!preimage_needed, "P2PK should never require preimage"); + + // Handle "anyone can spend" case (locktime passed with no refund keys) + if required_sigs == 0 { + return Ok(()); + } + + // Construct the message that should be signed + let msg_to_sign = self.sig_all_msg_to_sign(); + + // Extract signatures from the first input's witness + let first_witness = first_input + .witness + .as_ref() + .ok_or(super::nut11::Error::SignaturesNotProvided)?; + + let witness_sigs = first_witness + .signatures() + .ok_or(super::nut11::Error::SignaturesNotProvided)?; + + // Convert witness strings to Signature objects + use std::str::FromStr; + let signatures: Vec = witness_sigs + .iter() + .map(|s| bitcoin::secp256k1::schnorr::Signature::from_str(s)) + .collect::, _>>() + .map_err(|_| super::nut11::Error::InvalidSignature)?; + + // Verify signatures using the existing valid_signatures function + let valid_sig_count = + super::nut11::valid_signatures(msg_to_sign.as_bytes(), &pubkeys, &signatures)?; + + // Check if we have enough valid signatures + if valid_sig_count < required_sigs { + return Err(super::nut11::Error::SpendConditionsNotMet); + } + + Ok(()) + } + + /// Verify HTLC SIG_ALL signatures + /// + /// Do NOT call this directly. This is called only from 'verify_full_sig_all_check', + /// which has already done many important SIG_ALL checks. This performs the final + /// signature verification for SIG_ALL+HTLC transactions. + fn verify_sig_all_htlc(&self) -> Result<(), super::nut11::Error> { + // Get the first input, as it's the one with the signatures + let first_input = self + .inputs() + .first() + .ok_or(super::nut11::Error::SpendConditionsNotMet)?; + let first_secret = Secret::try_from(&first_input.secret) + .map_err(|_| super::nut11::Error::IncorrectSecretKind)?; + + // Record current time for locktime evaluation + let current_time = crate::util::unix_time(); + + // Get the relevant public keys, required signature count, and whether preimage is needed + let (preimage_needed, pubkeys, required_sigs) = + get_pubkeys_and_required_sigs(&first_secret, current_time)?; + + // If preimage is needed (before locktime), verify it + if preimage_needed { + // Extract HTLC witness + let htlc_witness = match first_input.witness.as_ref() { + Some(super::Witness::HTLCWitness(witness)) => witness, + _ => return Err(super::nut11::Error::SignaturesNotProvided), + }; + + // Verify the preimage matches the hash in the secret + verify_htlc_preimage(htlc_witness, &first_secret) + .map_err(|_| super::nut11::Error::SpendConditionsNotMet)?; + } + + // Handle "anyone can spend" case (locktime passed with no refund keys) + if required_sigs == 0 { + return Ok(()); + } + + // Construct the message that should be signed + let msg_to_sign = self.sig_all_msg_to_sign(); + + // Extract signatures from the first input's witness + let first_witness = first_input + .witness + .as_ref() + .ok_or(super::nut11::Error::SignaturesNotProvided)?; + + let witness_sigs = first_witness + .signatures() + .ok_or(super::nut11::Error::SignaturesNotProvided)?; + + // Convert witness strings to Signature objects + use std::str::FromStr; + let signatures: Vec = witness_sigs + .iter() + .map(|s| bitcoin::secp256k1::schnorr::Signature::from_str(s)) + .collect::, _>>() + .map_err(|_| super::nut11::Error::InvalidSignature)?; + + // Verify signatures using the existing valid_signatures function + let valid_sig_count = + super::nut11::valid_signatures(msg_to_sign.as_bytes(), &pubkeys, &signatures)?; + + // Check if we have enough valid signatures + if valid_sig_count < required_sigs { + return Err(super::nut11::Error::SpendConditionsNotMet); + } + + Ok(()) + } +} + impl Serialize for Secret { fn serialize(&self, serializer: S) -> Result where diff --git a/crates/cashu/src/nuts/nut11/mod.rs b/crates/cashu/src/nuts/nut11/mod.rs index 708f7d562..8d137fb6a 100644 --- a/crates/cashu/src/nuts/nut11/mod.rs +++ b/crates/cashu/src/nuts/nut11/mod.rs @@ -17,6 +17,7 @@ use thiserror::Error; use super::nut00::Witness; use super::nut01::PublicKey; use super::nut05::MeltRequest; +use super::nut10::SpendingConditionVerification; use super::{Kind, Nut10Secret, Proof, Proofs, SecretKey}; use crate::nuts::nut00::BlindedMessage; use crate::secret::Secret; @@ -67,6 +68,12 @@ pub enum Error { /// Duplicate signature from same pubkey #[error("Duplicate signature from the same pubkey detected")] DuplicateSignature, + /// Preimage not supported in P2PK + #[error("P2PK does not support preimage requirements")] + PreimageNotSupportedInP2PK, + /// SIG_ALL not supported in this context + #[error("SIG_ALL proofs must be verified using a different method")] + SigAllNotSupportedHere, /// Parse Url Error #[error(transparent)] UrlParseError(#[from] url::ParseError), @@ -137,87 +144,53 @@ impl Proof { .cloned() .unwrap_or_default() .try_into()?; - let msg: &[u8] = self.secret.as_bytes(); - - let mut verified_pubkeys = HashSet::new(); - - let witness_signatures = match &self.witness { - Some(witness) => witness.signatures(), - None => None, - }; - let witness_signatures = witness_signatures.ok_or(Error::SignaturesNotProvided)?; + if spending_conditions.sig_flag == SigFlag::SigAll { + return Err(Error::SigAllNotSupportedHere); + } - let mut pubkeys = spending_conditions.pubkeys.clone().unwrap_or_default(); - // NUT-11 enforcement per spec: - // - If locktime has passed and refund keys are present, spend must be authorized by - // refund pubkeys (n_sigs_refund-of-refund). This supersedes normal pubkey enforcement - // after expiry. - // - If locktime has passed and no refund keys are present, proof becomes spendable - // without further key checks (anyone-can-spend behavior). - // - Otherwise (before locktime), enforce normal multisig on the set of authorized - // pubkeys: Secret.data plus optional `pubkeys` tag, requiring n_sigs unique signers. + if secret.kind() != Kind::P2PK { + return Err(Error::IncorrectSecretKind); + } + // Based on the current time, we must identify the relevant keys let now = unix_time(); + let (preimage_needed, relevant_pubkeys, relevant_num_sigs_required) = + super::nut10::get_pubkeys_and_required_sigs(&secret, now)?; - if let Some(locktime) = spending_conditions.locktime { - if now >= locktime { - if let Some(refund_keys) = spending_conditions.refund_keys.clone() { - let needed_refund_sigs = - spending_conditions.num_sigs_refund.unwrap_or(1) as usize; - let mut valid_pubkeys = HashSet::new(); - - // After locktime, require signatures from refund keys - for s in witness_signatures.iter() { - let sig = Signature::from_str(s).map_err(|_| Error::InvalidSignature)?; - for v in &refund_keys { - if v.verify(msg, &sig).is_ok() { - valid_pubkeys.insert(v); - if valid_pubkeys.len() >= needed_refund_sigs { - return Ok(()); - } - } - } - } - - // If locktime and refund keys were specified they must sign after locktime - return Err(Error::SpendConditionsNotMet); - } else { - // If only locktime is specified, consider it spendable after locktime - return Ok(()); - } - } + if preimage_needed { + return Err(Error::PreimageNotSupportedInP2PK); } - if secret.kind().eq(&Kind::P2PK) { - pubkeys.push(PublicKey::from_str(secret.secret_data().data())?); + // Handle "anyone can spend" case (locktime passed with no refund keys) + if relevant_num_sigs_required == 0 { + return Ok(()); } - for signature in witness_signatures.iter() { - for v in &pubkeys { - let sig = Signature::from_str(signature)?; - - if v.verify(msg, &sig).is_ok() { - // If the pubkey is already verified, return a duplicate signature error - if !verified_pubkeys.insert(*v) { - return Err(Error::DuplicateSignature); - } - } else { - tracing::debug!( - "Could not verify signature: {sig} on message: {}", - self.secret.to_string() - ) - } - } - } + // Extract witness signatures + let witness_signatures = match &self.witness { + Some(witness) => witness.signatures(), + None => None, + }; + let witness_signatures = witness_signatures.ok_or(Error::SignaturesNotProvided)?; - let valid_sigs = verified_pubkeys.len() as u64; + // Count valid signatures using relevant_pubkeys + let msg: &[u8] = self.secret.as_bytes(); + let valid_sig_count = valid_signatures( + msg, + &relevant_pubkeys, + &witness_signatures + .iter() + .map(|s| Signature::from_str(s)) + .collect::, _>>()?, + )?; - if valid_sigs >= spending_conditions.num_sigs.unwrap_or(1) { - return Ok(()); + // Check if we have enough valid signatures + if valid_sig_count >= relevant_num_sigs_required { + Ok(()) + } else { + Err(Error::SpendConditionsNotMet) } - - Err(Error::SpendConditionsNotMet) } } @@ -887,132 +860,8 @@ impl From for Vec { } impl SwapRequest { - /// Generate the message to sign for SIG_ALL validation - /// Concatenates all input secrets and output blinded messages in order - fn sig_all_msg_to_sign(&self) -> String { - let mut msg_to_sign = String::new(); - - // Add all input secrets in order - for proof in self.inputs() { - let secret = proof.secret.to_string(); - msg_to_sign.push_str(&secret); - } - - // Add all output blinded messages in order - for output in self.outputs() { - let message = output.blinded_secret.to_string(); - msg_to_sign.push_str(&message); - } - - msg_to_sign - } - - /// Get required signature count from first input's spending conditions - fn get_sig_all_required_sigs(&self) -> Result<(u64, SpendingConditions), Error> { - let first_input = self.inputs().first().ok_or(Error::SpendConditionsNotMet)?; - let first_conditions: SpendingConditions = - SpendingConditions::try_from(&first_input.secret)?; - - let required_sigs = match first_conditions.clone() { - SpendingConditions::P2PKConditions { conditions, .. } => { - let conditions = conditions.ok_or(Error::IncorrectSecretKind)?; - - if SigFlag::SigAll != conditions.sig_flag { - return Err(Error::IncorrectSecretKind); - } - - conditions.num_sigs.unwrap_or(1) - } - _ => return Err(Error::IncorrectSecretKind), - }; - - Ok((required_sigs, first_conditions)) - } - - /// Verify all inputs have matching secrets and tags - fn verify_matching_conditions(&self) -> Result<(), Error> { - let first_input = self.inputs().first().ok_or(Error::SpendConditionsNotMet)?; - let first_nut10: Nut10Secret = (&first_input.secret).try_into()?; - - for proof in self.inputs().iter().skip(1) { - let current_secret: Nut10Secret = proof.secret.clone().try_into()?; - - // Check data matches - if current_secret.secret_data().data() != first_nut10.secret_data().data() { - return Err(Error::SpendConditionsNotMet); - } - - // Check tags match - if current_secret.secret_data().tags() != first_nut10.secret_data().tags() { - return Err(Error::SpendConditionsNotMet); - } - } - Ok(()) - } - - /// Get validated signatures from first input's witness - fn get_valid_witness_signatures(&self) -> Result, Error> { - let first_input = self.inputs().first().ok_or(Error::SpendConditionsNotMet)?; - let first_witness = first_input - .witness - .as_ref() - .ok_or(Error::SignaturesNotProvided)?; - - let witness_sigs = first_witness - .signatures() - .ok_or(Error::SignaturesNotProvided)?; - - // Convert witness strings to signatures - witness_sigs - .iter() - .map(|s| Signature::from_str(s)) - .collect::, _>>() - .map_err(Error::from) - } - - /// Check if swap request can be signed with the given secret key - fn can_sign_sig_all( - &self, - secret_key: &SecretKey, - ) -> Result<(SpendingConditions, PublicKey), Error> { - // Get the first input since all must match for SIG_ALL - let first_input = self.inputs().first().ok_or(Error::SpendConditionsNotMet)?; - let first_conditions: SpendingConditions = - SpendingConditions::try_from(&first_input.secret)?; - - // Verify this is a P2PK condition with SIG_ALL - match first_conditions.clone() { - SpendingConditions::P2PKConditions { conditions, .. } => { - let conditions = conditions.ok_or(Error::IncorrectSecretKind)?; - if conditions.sig_flag != SigFlag::SigAll { - return Err(Error::IncorrectSecretKind); - } - conditions - } - _ => return Err(Error::IncorrectSecretKind), - }; - - // Get authorized keys and verify secret_key matches one - let pubkey = secret_key.public_key(); - let authorized_keys = first_conditions - .pubkeys() - .ok_or(Error::P2PKPubkeyRequired)?; - - if !authorized_keys.contains(&pubkey) { - return Err(Error::SpendConditionsNotMet); - } - - Ok((first_conditions, pubkey)) - } - - /// Sign swap request with SIG_ALL if conditions are met + /// Sign swap request with SIG_ALL pub fn sign_sig_all(&mut self, secret_key: SecretKey) -> Result<(), Error> { - // Verify we can sign and get conditions - let (_first_conditions, _) = self.can_sign_sig_all(&secret_key)?; - - // Verify all inputs have matching conditions - self.verify_matching_conditions()?; - // Get message to sign let msg = self.sig_all_msg_to_sign(); let signature = secret_key.sign(msg.as_bytes())?; @@ -1036,166 +885,14 @@ impl SwapRequest { Ok(()) } - - /// Validate SIG_ALL conditions and signatures for the swap request - pub fn verify_sig_all(&self) -> Result<(), Error> { - // Get required signatures and conditions from first input - let (required_sigs, first_conditions) = self.get_sig_all_required_sigs()?; - - // Verify all inputs have matching secrets - self.verify_matching_conditions()?; - - // Get and validate witness signatures - let signatures = self.get_valid_witness_signatures()?; - - // Get signing pubkeys - let verifying_pubkeys = first_conditions - .pubkeys() - .ok_or(Error::P2PKPubkeyRequired)?; - - // Get aggregated message and validate signatures - let msg = self.sig_all_msg_to_sign(); - let valid_sigs = valid_signatures(msg.as_bytes(), &verifying_pubkeys, &signatures)?; - - if valid_sigs >= required_sigs { - Ok(()) - } else { - Err(Error::SpendConditionsNotMet) - } - } } -impl MeltRequest { - /// Generate the message to sign for SIG_ALL validation - /// Concatenates all input secrets, blank outputs, and quote ID in order - fn sig_all_msg_to_sign(&self) -> String { - let mut msg_to_sign = String::new(); - - // Add all input secrets in order - for proof in self.inputs() { - let secret = proof.secret.to_string(); - msg_to_sign.push_str(&secret); - } - - // Add all blank outputs in order if they exist - if let Some(outputs) = self.outputs() { - for output in outputs { - msg_to_sign.push_str(&output.blinded_secret.to_hex()); - } - } - - // Add quote ID - msg_to_sign.push_str(&self.quote().to_string()); - - msg_to_sign - } - - /// Get required signature count from first input's spending conditions - fn get_sig_all_required_sigs(&self) -> Result<(u64, SpendingConditions), Error> { - let first_input = self.inputs().first().ok_or(Error::SpendConditionsNotMet)?; - let first_conditions: SpendingConditions = - SpendingConditions::try_from(&first_input.secret)?; - - let required_sigs = match first_conditions.clone() { - SpendingConditions::P2PKConditions { conditions, .. } => { - let conditions = conditions.ok_or(Error::IncorrectSecretKind)?; - - if SigFlag::SigAll != conditions.sig_flag { - return Err(Error::IncorrectSecretKind); - } - - conditions.num_sigs.unwrap_or(1) - } - _ => return Err(Error::IncorrectSecretKind), - }; - - Ok((required_sigs, first_conditions)) - } - - /// Verify all inputs have matching secrets and tags - fn verify_matching_conditions(&self) -> Result<(), Error> { - let first_input = self.inputs().first().ok_or(Error::SpendConditionsNotMet)?; - let first_nut10: Nut10Secret = (&first_input.secret).try_into()?; - - for proof in self.inputs().iter().skip(1) { - let current_secret: Nut10Secret = proof.secret.clone().try_into()?; - - // Check data matches - if current_secret.secret_data().data() != first_nut10.secret_data().data() { - return Err(Error::SpendConditionsNotMet); - } - - // Check tags match - if current_secret.secret_data().tags() != first_nut10.secret_data().tags() { - return Err(Error::SpendConditionsNotMet); - } - } - Ok(()) - } - - /// Get validated signatures from first input's witness - fn get_valid_witness_signatures(&self) -> Result, Error> { - let first_input = self.inputs().first().ok_or(Error::SpendConditionsNotMet)?; - let first_witness = first_input - .witness - .as_ref() - .ok_or(Error::SignaturesNotProvided)?; - - let witness_sigs = first_witness - .signatures() - .ok_or(Error::SignaturesNotProvided)?; - - // Convert witness strings to signatures - witness_sigs - .iter() - .map(|s| Signature::from_str(s)) - .collect::, _>>() - .map_err(Error::from) - } - - /// Check if melt request can be signed with the given secret key - fn can_sign_sig_all( - &self, - secret_key: &SecretKey, - ) -> Result<(SpendingConditions, PublicKey), Error> { - // Get the first input since all must match for SIG_ALL - let first_input = self.inputs().first().ok_or(Error::SpendConditionsNotMet)?; - let first_conditions: SpendingConditions = - SpendingConditions::try_from(&first_input.secret)?; - - // Verify this is a P2PK condition with SIG_ALL - match first_conditions.clone() { - SpendingConditions::P2PKConditions { conditions, .. } => { - let conditions = conditions.ok_or(Error::IncorrectSecretKind)?; - if conditions.sig_flag != SigFlag::SigAll { - return Err(Error::IncorrectSecretKind); - } - conditions - } - _ => return Err(Error::IncorrectSecretKind), - }; - - // Get authorized keys and verify secret_key matches one - let pubkey = secret_key.public_key(); - let authorized_keys = first_conditions - .pubkeys() - .ok_or(Error::P2PKPubkeyRequired)?; - - if !authorized_keys.contains(&pubkey) { - return Err(Error::SpendConditionsNotMet); - } - - Ok((first_conditions, pubkey)) - } - - /// Sign melt request with SIG_ALL if conditions are met +impl MeltRequest +where + Q: std::fmt::Display + Serialize + DeserializeOwned, +{ + /// Sign melt request with SIG_ALL pub fn sign_sig_all(&mut self, secret_key: SecretKey) -> Result<(), Error> { - // Verify we can sign and get conditions - let (_first_conditions, _) = self.can_sign_sig_all(&secret_key)?; - - // Verify all inputs have matching conditions - self.verify_matching_conditions()?; - // Get message to sign let msg = self.sig_all_msg_to_sign(); let signature = secret_key.sign(msg.as_bytes())?; @@ -1219,33 +916,6 @@ impl MeltRequest { Ok(()) } - - /// Validate SIG_ALL conditions and signatures for the melt request - pub fn verify_sig_all(&self) -> Result<(), Error> { - // Get required signatures and conditions from first input - let (required_sigs, first_conditions) = self.get_sig_all_required_sigs()?; - - // Verify all inputs have matching secrets - self.verify_matching_conditions()?; - - // Get and validate witness signatures - let signatures = self.get_valid_witness_signatures()?; - - // Get signing pubkeys - let verifying_pubkeys = first_conditions - .pubkeys() - .ok_or(Error::P2PKPubkeyRequired)?; - - // Get aggregated message and validate signatures - let msg = self.sig_all_msg_to_sign(); - let valid_sigs = valid_signatures(msg.as_bytes(), &verifying_pubkeys, &signatures)?; - - if valid_sigs >= required_sigs { - Ok(()) - } else { - Err(Error::SpendConditionsNotMet) - } - } } impl Serialize for Tag { @@ -1518,7 +1188,6 @@ mod tests { // Create conditions with SIG_ALL let conditions = Conditions { sig_flag: SigFlag::SigAll, - pubkeys: Some(vec![pubkey]), ..Default::default() }; @@ -1535,7 +1204,7 @@ mod tests { // Before signing, should fail verification assert!( - melt.verify_sig_all().is_err(), + melt.verify_spending_conditions().is_err(), "Unsigned melt request should fail verification" ); @@ -1547,7 +1216,7 @@ mod tests { // After signing, should pass verification assert!( - melt.verify_sig_all().is_ok(), + melt.verify_spending_conditions().is_ok(), "Signed melt request should pass verification" ); } @@ -1571,14 +1240,16 @@ mod tests { let mut melt = MeltRequest::new(Uuid::new_v4(), vec![proof], None); - // Try to sign with unauthorized key + // Sign with unauthorized key let unauthorized_key = SecretKey::from_str("0000000000000000000000000000000000000000000000000000000000000001") .unwrap(); + melt.sign_sig_all(unauthorized_key).unwrap(); + // Verification should fail (unauthorized signature) assert!( - melt.sign_sig_all(unauthorized_key).is_err(), - "Signing with unauthorized key should fail" + melt.verify_spending_conditions().is_err(), + "Verification should fail with unauthorized key signature" ); } @@ -1601,9 +1272,13 @@ mod tests { let mut melt = MeltRequest::new(Uuid::new_v4(), vec![proof], None); + // Signing + melt.sign_sig_all(secret_key).unwrap(); + + // Verification should fail (wrong flag - expected SIG_ALL) assert!( - melt.sign_sig_all(secret_key).is_err(), - "Signing with SIG_INPUTS flag should fail" + melt.verify_spending_conditions().is_err(), + "Verification should fail with SIG_INPUTS flag when expecting SIG_ALL" ); } @@ -1617,7 +1292,6 @@ mod tests { // Create conditions let conditions = Conditions { sig_flag: SigFlag::SigAll, - pubkeys: Some(vec![pubkey]), ..Default::default() }; @@ -1635,7 +1309,7 @@ mod tests { "Signing with multiple matching inputs should succeed" ); assert!( - melt.verify_sig_all().is_ok(), + melt.verify_spending_conditions().is_ok(), "Verification should succeed with multiple matching inputs" ); } @@ -1668,9 +1342,13 @@ mod tests { let mut melt = MeltRequest::new(Uuid::new_v4(), vec![proof1, proof2], None); + // Signing should succeed (no validation during signing) + melt.sign_sig_all(secret_key).unwrap(); + + // Verification should fail (catches mismatched inputs) assert!( - melt.sign_sig_all(secret_key).is_err(), - "Signing with mismatched input secrets should fail" + melt.verify_spending_conditions().is_err(), + "Verification should fail with mismatched input secrets" ); } @@ -1690,7 +1368,7 @@ mod tests { let conditions = Conditions { sig_flag: SigFlag::SigAll, num_sigs: Some(2), - pubkeys: Some(vec![pubkey1, pubkey2]), + pubkeys: Some(vec![pubkey2]), ..Default::default() }; @@ -1711,7 +1389,7 @@ mod tests { "First signature should succeed" ); assert!( - melt.verify_sig_all().is_err(), + melt.verify_spending_conditions().is_err(), "Single signature should not verify when two required" ); @@ -1722,7 +1400,7 @@ mod tests { ); assert!( - melt.verify_sig_all().is_ok(), + melt.verify_spending_conditions().is_ok(), "Both signatures should verify successfully" ); } @@ -1765,86 +1443,532 @@ mod tests { ); } + // "SIG_ALL Test Vectors", starting with swaps : https://github.com/cashubtc/nuts/blob/5b050c7960607cca0481c28517cab5cc091b5d2e/tests/11-test.md#sig_all-test-vectors #[test] fn test_sig_all_swap_single_sig() { // Valid SwapRequest with SIG_ALL signature - let valid_swap = r#"{"inputs":[{"amount":0,"id":"009a1f293253e41e","secret":"[\"P2PK\",{\"nonce\":\"fc14ca312b7442d05231239d0e3cdcb6b2335250defcb8bec7d2efe9e26c90a6\",\"data\":\"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a\",\"tags\":[[\"sigflag\",\"SIG_ALL\"]]}]","C":"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a","witness":"{\"signatures\":[\"aa6f3b3f112ec3e834aded446ea67a90cdb26b43e08cfed259e0bbd953395c4af11117c58ec0ec3de404f31076692426cde40d2c1602d9dd067a872cb11ac3c0\"]}"},{"amount":0,"id":"009a1f293253e41f","secret":"[\"P2PK\",{\"nonce\":\"fc14ca312b7442d05231239d0e3cdcb6b2335250defcb8bec7d2efe9e26c90a6\",\"data\":\"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a\",\"tags\":[[\"sigflag\",\"SIG_ALL\"]]}]","C":"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a"}],"outputs":[{"amount":0,"id":"009a1f293253e41e","B_":"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a"}]}"#; + let valid_swap = r#"{ + "inputs": [ + { + "amount": 2, + "id": "00bfa73302d12ffd", + "secret": "[\"P2PK\",{\"nonce\":\"c7f280eb55c1e8564e03db06973e94bc9b666d9e1ca42ad278408fe625950303\",\"data\":\"030d8acedfe072c9fa449a1efe0817157403fbec460d8e79f957966056e5dd76c1\",\"tags\":[[\"sigflag\",\"SIG_ALL\"]]}]", + "C": "02c97ee3d1db41cf0a3ddb601724be8711a032950811bf326f8219c50c4808d3cd", + "witness": "{\"signatures\":[\"ce017ca25b1b97df2f72e4b49f69ac26a240ce14b3690a8fe619d41ccc42d3c1282e073f85acd36dc50011638906f35b56615f24e4d03e8effe8257f6a808538\"]}" + } + ], + "outputs": [ + { + "amount": 2, + "id": "00bfa73302d12ffd", + "B_": "038ec853d65ae1b79b5cdbc2774150b2cb288d6d26e12958a16fb33c32d9a86c39" + } + ] +}"#; let valid_swap: SwapRequest = serde_json::from_str(valid_swap).unwrap(); + + // Verify the message format + let msg_to_sign = valid_swap.sig_all_msg_to_sign(); + assert_eq!( + msg_to_sign, + "[\"P2PK\",{\"nonce\":\"c7f280eb55c1e8564e03db06973e94bc9b666d9e1ca42ad278408fe625950303\",\"data\":\"030d8acedfe072c9fa449a1efe0817157403fbec460d8e79f957966056e5dd76c1\",\"tags\":[[\"sigflag\",\"SIG_ALL\"]]}]02c97ee3d1db41cf0a3ddb601724be8711a032950811bf326f8219c50c4808d3cd2038ec853d65ae1b79b5cdbc2774150b2cb288d6d26e12958a16fb33c32d9a86c39" + ); + + // Verify the SHA256 hash of the message + use bitcoin::hashes::{sha256, Hash}; + let msg_hash = sha256::Hash::hash(msg_to_sign.as_bytes()); + assert_eq!( + msg_hash.to_string(), + "de7f9e3ca0fcc5ed3258fcf83dbf1be7fa78a5ed6da7bf2aa60d61e9dc6eb09a" + ); + assert!( - valid_swap.verify_sig_all().is_ok(), + valid_swap.verify_spending_conditions().is_ok(), "Valid SIG_ALL swap request should verify" ); } + #[test] + fn test_sig_all_swap_single_sig_2() { + // The following is a SwapRequest with a valid sig_all signature. + let valid_swap = r#"{ + "inputs": [ + { + "amount": 2, + "id": "00bfa73302d12ffd", + "secret": "[\"P2PK\",{\"nonce\":\"c7f280eb55c1e8564e03db06973e94bc9b666d9e1ca42ad278408fe625950303\",\"data\":\"030d8acedfe072c9fa449a1efe0817157403fbec460d8e79f957966056e5dd76c1\",\"tags\":[[\"sigflag\",\"SIG_ALL\"]]}]", + "C": "02c97ee3d1db41cf0a3ddb601724be8711a032950811bf326f8219c50c4808d3cd", + "witness": "{\"signatures\":[\"ce017ca25b1b97df2f72e4b49f69ac26a240ce14b3690a8fe619d41ccc42d3c1282e073f85acd36dc50011638906f35b56615f24e4d03e8effe8257f6a808538\"]}" + } + ], + "outputs": [ + { + "amount": 2, + "id": "00bfa73302d12ffd", + "B_": "038ec853d65ae1b79b5cdbc2774150b2cb288d6d26e12958a16fb33c32d9a86c39" + } + ] +}"#; + + let valid_swap: SwapRequest = serde_json::from_str(valid_swap).unwrap(); + + assert!( + valid_swap.verify_spending_conditions().is_ok(), + "Valid SIG_ALL swap request should verify" + ); + } + + #[test] + fn test_sig_all_multiple_secrets() { + // The following is a SwapRequest that is invalid as there are multiple secrets. + let invalid_swap = r#"{ + "inputs": [ + { + "amount": 1, + "id": "00bfa73302d12ffd", + "secret": "[\"P2PK\",{\"nonce\":\"fa6dd3fac9086c153878dec90b9e37163d38ff2ecf8b37db6470e9d185abbbae\",\"data\":\"033b42b04e659fed13b669f8b16cdaffc3ee5738608810cf97a7631d09bd01399d\",\"tags\":[[\"sigflag\",\"SIG_ALL\"]]}]", + "C": "024d232312bab25af2e73f41d56864d378edca9109ae8f76e1030e02e585847786", + "witness": "{\"signatures\":[\"27b4d260a1186e3b62a26c0d14ffeab3b9f7c3889e78707b8fd3836b473a00601afbd53a2288ad20a624a8bbe3344453215ea075fc0ce479dd8666fd3d9162cc\"]}" + }, + { + "amount": 2, + "id": "00bfa73302d12ffd", + "secret": "[\"P2PK\",{\"nonce\":\"4007b21fc5f5b1d4920bc0a08b158d98fd0fb2b0b0262b57ff53c6c5d6c2ae8c\",\"data\":\"033b42b04e659fed13b669f8b16cdaffc3ee5738608810cf97a7631d09bd01399d\",\"tags\":[[\"locktime\",\"122222222222222\"],[\"sigflag\",\"SIG_ALL\"]]}]", + "C": "02417400f2af09772219c831501afcbab4efb3b2e75175635d5474069608deb641" + } + ], + "outputs": [ + { + "amount": 1, + "id": "00bfa73302d12ffd", + "B_": "038ec853d65ae1b79b5cdbc2774150b2cb288d6d26e12958a16fb33c32d9a86c39" + }, + { + "amount": 1, + "id": "00bfa73302d12ffd", + "B_": "03afe7c87e32d436f0957f1d70a2bca025822a84a8623e3a33aed0a167016e0ca5" + }, + { + "amount": 1, + "id": "00bfa73302d12ffd", + "B_": "02c0d4fce02a7a0f09e3f1bca952db910b17e81a7ebcbce62cd8dcfb127d21e37b" + } + ] +}"#; + + let invalid_swap: SwapRequest = serde_json::from_str(invalid_swap).unwrap(); + + assert!( + invalid_swap.verify_spending_conditions().is_err(), + "Invalid swap with multiple secrets shouldn't be accepted" + ); + } + + #[test] + fn test_sig_all_multiple_signatures_provided() { + // The following is a SwapRequest multiple valid signatures are provided and required. + let valid_swap = r#"{ + "inputs": [ + { + "amount": 2, + "id": "00bfa73302d12ffd", + "secret": "[\"P2PK\",{\"nonce\":\"04bfd885fc982d553711092d037fdceb7320fd8f96b0d4fd6d31a65b83b94272\",\"data\":\"0275e78025b558dbe6cb8fdd032a2e7613ca14fda5c1f4c4e3427f5077a7bd90e4\",\"tags\":[[\"pubkeys\",\"035163650bbd5ed4be7693f40f340346ba548b941074e9138b67ef6c42755f3449\",\"02817d22a8edc44c4141e192995a7976647c335092199f9e076a170c7336e2f5cc\"],[\"n_sigs\",\"2\"],[\"sigflag\",\"SIG_ALL\"]]}]", + "C": "03866a09946562482c576ca989d06371e412b221890804c7da8887d321380755be", + "witness": "{\"signatures\":[\"be1d72c5ca16a93c5a34f25ec63ce632ddc3176787dac363321af3fd0f55d1927e07451bc451ffe5c682d76688ea9925d7977dffbb15bd79763b527f474734b0\",\"669d6d10d7ed35395009f222f6c7bdc28a378a1ebb72ee43117be5754648501da3bedf2fd6ff0c7849ac92683538c60af0af504102e40f2d8daca8e08b1ca16b\"]}" + } + ], + "outputs": [ + { + "amount": 2, + "id": "00bfa73302d12ffd", + "B_": "038ec853d65ae1b79b5cdbc2774150b2cb288d6d26e12958a16fb33c32d9a86c39" + } + ] +}"#; + + let valid_swap: SwapRequest = serde_json::from_str(valid_swap).unwrap(); + + assert!( + valid_swap.verify_spending_conditions().is_ok(), + "Valid swap with multiple signatures should be accepted" + ); + } + + #[test] + fn test_sig_all_mixed_pubkeys_and_refund() { + // The following is an invalid SwapRequest with pubkeys and refund mixed. + let invalid_swap = r#"{ + "inputs": [ + { + "amount": 2, + "id": "00bfa73302d12ffd", + "secret": "[\"P2PK\",{\"nonce\":\"3e9253419a11f0a541dd6baeddecf8356fc864b5d061f12f05632bc3aee6b5c4\",\"data\":\"0343cca0e48ce9e3fdcddba4637ff8cdbf6f5ed9cfdf1873e63827e760f0ed4db5\",\"tags\":[[\"pubkeys\",\"0235e0a719f8b046cee90f55a59b1cdd6ca75ce23e49cbcd82c9e5b7310e21ebcd\",\"020443f98b356e021bae82bdfc05ff433cab21e27fca9ab7b0995aedb2e7aabc43\"],[\"locktime\",\"100\"],[\"n_sigs\",\"2\"],[\"refund\",\"026b432e62b041bf9cdae534203739c73fa506c9a2d6aa58a52bc601a1dec421e1\",\"02e3494a2e07e7f6e7d4567e0da7a563592bff1e121df2383667f15b83e9168a9e\"],[\"n_sigs_refund\",\"2\"],[\"sigflag\",\"SIG_ALL\"]]}]", + "C": "026c12ee3bffa5c617debcf823bf1af6a9b47145b699f2737bba3394f0893eb869", + "witness": "{\"signatures\":[\"bfe884145ce6512331324321c3946dfd812428a53656b108b59d26559a186ba2ab45e5be9ce94e2dff0d09078e25ccb82d06a8b3a63cd3dc67065b8f77292776\",\"236e5cc9c30f85a893a29a4302e41e6f2015caef4229f28fa65e2f5c9d55515cc9a1852093a81a5095055d85fd55bf4da124e55354b56e0a39e83b58b0afc197\"]}" + } + ], + "outputs": [ + { + "amount": 1, + "id": "00bfa73302d12ffd", + "B_": "038ec853d65ae1b79b5cdbc2774150b2cb288d6d26e12958a16fb33c32d9a86c39" + }, + { + "amount": 1, + "id": "00bfa73302d12ffd", + "B_": "03afe7c87e32d436f0957f1d70a2bca025822a84a8623e3a33aed0a167016e0ca5" + } + ] +}"#; + + let invalid_swap: SwapRequest = serde_json::from_str(invalid_swap).unwrap(); + + assert!( + invalid_swap.verify_spending_conditions().is_err(), + "Invalid swap with mixed refunds and pubkeys shouldn't be accepted" + ); + } + + #[test] + fn test_sig_all_locktime_passed_with_valid_refund_key_sigs() { + // The following is a SwapRequest with locktime passed and refund keys signatures are valid + let valid_swap = r#"{ + "inputs": [ + { + "amount": 2, + "id": "00bfa73302d12ffd", + "secret": "[\"P2PK\",{\"nonce\":\"9ea35553beb18d553d0a53120d0175a0991ca6109370338406eed007b26eacd1\",\"data\":\"02af21e09300af92e7b48c48afdb12e22933738cfb9bba67b27c00c679aae3ec25\",\"tags\":[[\"locktime\",\"1\"],[\"refund\",\"02637c19143c58b2c58bd378400a7b82bdc91d6dedaeb803b28640ef7d28a887ac\",\"0345c7fdf7ec7c8e746cca264bf27509eb4edb9ac421f8fbfab1dec64945a4d797\"],[\"n_sigs_refund\",\"2\"],[\"sigflag\",\"SIG_ALL\"]]}]", + "C": "03dd83536fbbcbb74ccb3c87147df26753fd499cc2c095f74367fff0fb459c312e", + "witness": "{\"signatures\":[\"23b58ef28cd22f3dff421121240ddd621deee83a3bc229fd67019c2e338d91e2c61577e081e1375dbab369307bba265e887857110ca3b4bd949211a0a298805f\",\"7e75948ef1513564fdcecfcbd389deac67c730f7004f8631ba90c0844d3e8c0cf470b656306877df5141f65fd3b7e85445a8452c3323ab273e6d0d44843817ed\"]}" + } + ], + "outputs": [ + { + "amount": 2, + "id": "00bfa73302d12ffd", + "B_": "038ec853d65ae1b79b5cdbc2774150b2cb288d6d26e12958a16fb33c32d9a86c39" + } + ] +}"#; + + let valid_swap: SwapRequest = serde_json::from_str(valid_swap).unwrap(); + + assert!( + valid_swap.verify_spending_conditions().is_ok(), + "Valid post-locktime swap with refund keys should be accepted" + ); + } + + #[test] + fn test_sig_all_htlc_and_pubkey() { + // The following is a valid `SwapRequest` with an HTLC also locked to a public key + let valid_swap = r#"{ + "inputs": [ + { + "amount": 2, + "id": "00bfa73302d12ffd", + "secret": "[\"HTLC\",{\"nonce\":\"d730dd70cd7ec6e687829857de8e70aab2b970712f4dbe288343eca20e63c28c\",\"data\":\"ec4916dd28fc4c10d78e287ca5d9cc51ee1ae73cbfde08c6b37324cbfaac8bc5\",\"tags\":[[\"pubkeys\",\"0350cda8a1d5257dbd6ba8401a9a27384b9ab699e636e986101172167799469b14\"],[\"sigflag\",\"SIG_ALL\"]]}]", + "C": "03ff6567e2e6c31db5cb7189dab2b5121930086791c93899e4eff3dda61cb57273", + "witness": "{\"preimage\":\"0000000000000000000000000000000000000000000000000000000000000001\",\"signatures\":[\"a4c00a9ad07f9936e404494fda99a9b935c82d7c053173b304b8663124c81d4b00f64a225f5acf41043ca52b06382722bd04ded0fbeb0fcc404eed3b24778b88\"]}" + } + ], + "outputs": [ + { + "amount": 2, + "id": "00bfa73302d12ffd", + "B_": "038ec853d65ae1b79b5cdbc2774150b2cb288d6d26e12958a16fb33c32d9a86c39" + } + ] +}"#; + + let valid_swap: SwapRequest = serde_json::from_str(valid_swap).unwrap(); + + assert!( + valid_swap.verify_spending_conditions().is_ok(), + "Valid swap with htlc and pubkey should be accepted" + ); + } + + #[test] + fn test_sig_all_enforce_locktime_with_only_refund_signed() { + // The following is an invalid SwapRequest with an HTLC also locked to a public key, locktime and refund key. locktime is not expired but proof is signed with refund key. + let invalid_swap = r#"{ + "inputs": [ + { + "amount": 2, + "id": "00bfa73302d12ffd", + "secret": "[\"HTLC\",{\"nonce\":\"512c4045f12fdfd6f55059669c189e040c37c1ce2f8be104ed6aec296acce4e9\",\"data\":\"ec4916dd28fc4c10d78e287ca5d9cc51ee1ae73cbfde08c6b37324cbfaac8bc5\",\"tags\":[[\"pubkeys\",\"03ba83defd31c63f8841d188f0d41b5bb3af1bb3c08d0ba46f8f1d26a4d45e8cad\"],[\"locktime\",\"4854185133\"],[\"refund\",\"032f1008a79c722e93a1b4b853f85f38283f9ef74ee4c5c91293eb1cc3c5e46e34\"],[\"sigflag\",\"SIG_ALL\"]]}]", + "C": "02207abeff828146f1fc3909c74613d5605bd057f16791994b3c91f045b39a6939", + "witness": "{\"preimage\":\"0000000000000000000000000000000000000000000000000000000000000001\",\"signatures\":[\"7816d57871bde5be2e4281065dbe5b15f641d8f1ed9437a3ae556464d6f9b8a0a2e6660337a915f2c26dce1453a416daf682b8fb593b67a0750fce071e0759b9\"]}" + } + ], + "outputs": [ + { + "amount": 1, + "id": "00bfa73302d12ffd", + "B_": "038ec853d65ae1b79b5cdbc2774150b2cb288d6d26e12958a16fb33c32d9a86c39" + }, + { + "amount": 1, + "id": "00bfa73302d12ffd", + "B_": "03afe7c87e32d436f0957f1d70a2bca025822a84a8623e3a33aed0a167016e0ca5" + } + ] +}"#; + + let invalid_swap: SwapRequest = serde_json::from_str(invalid_swap).unwrap(); + + assert!( + invalid_swap.verify_spending_conditions().is_err(), + "Invalid swap with pre-locktime conditions not met shouldn't be accepted" + ); + } + + #[test] + fn test_sig_all_htlc_post_locktime() { + // The following is a valid SwapRequest with a multisig HTLC also locked to locktime and refund keys. + let valid_swap = r#"{ + "inputs": [ + { + "amount": 2, + "id": "00bfa73302d12ffd", + "secret": "[\"HTLC\",{\"nonce\":\"c9b0fabb8007c0db4bef64d5d128cdcf3c79e8bb780c3294adf4c88e96c32647\",\"data\":\"ec4916dd28fc4c10d78e287ca5d9cc51ee1ae73cbfde08c6b37324cbfaac8bc5\",\"tags\":[[\"pubkeys\",\"039e6ec7e922abb4162235b3a42965eb11510b07b7461f6b1a17478b1c9c64d100\"],[\"locktime\",\"1\"],[\"refund\",\"02ce1bbd2c9a4be8029c9a6435ad601c45677f5cde81f8a7f0ed535e0039d0eb6c\",\"03c43c00ff57f63cfa9e732f0520c342123e21331d0121139f1b636921eeec095f\"],[\"n_sigs_refund\",\"2\"],[\"sigflag\",\"SIG_ALL\"]]}]", + "C": "0344b6f1471cf18a8cbae0e624018c816be5e3a9b04dcb7689f64173c1ae90a3a5", + "witness": "{\"preimage\":\"0000000000000000000000000000000000000000000000000000000000000001\",\"signatures\":[\"98e21672d409cc782c720f203d8284f0af0c8713f18167499f9f101b7050c3e657fb0e57478ebd8bd561c31aa6c30f4cd20ec38c73f5755b7b4ddee693bca5a5\",\"693f40129dbf905ed9c8008081c694f72a36de354f9f4fa7a61b389cf781f62a0ae0586612fb2eb504faaf897fefb6742309186117f4743bcebcb8e350e975e2\"]}" + } + ], + "outputs": [ + { + "amount": 2, + "id": "00bfa73302d12ffd", + "B_": "038ec853d65ae1b79b5cdbc2774150b2cb288d6d26e12958a16fb33c32d9a86c39" + } + ] +}"#; + + let valid_swap: SwapRequest = serde_json::from_str(valid_swap).unwrap(); + + assert!( + valid_swap.verify_spending_conditions().is_ok(), + "Valid post-locktime swap with htlc should be accepted" + ); + } + #[test] fn test_sig_all_swap_mismatched_inputs() { // Invalid SwapRequest - mismatched inputs with SIG_ALL let invalid_swap = r#"{ - "inputs": [{ - "amount": 1, - "secret": "[\"P2PK\",{\"nonce\":\"859d4935c4907062a6297cf4e663e2835d90d97ecdd510745d32f6816323a41f\",\"data\":\"0249098aa8b9d2fbec49ff8598feb17b592b986e62319a4fa488a3dc36387157a7\",\"tags\":[[\"sigflag\",\"SIG_ALL\"]]}]", - "C": "02698c4e2b5f9534cd0687d87513c759790cf829aa5739184a3e3735471fbda904", - "id": "009a1f293253e41e", - "witness": "{\"signatures\":[\"60f3c9b766770b46caac1d27e1ae6b77c8866ebaeba0b9489fe6a15a837eaa6fcd6eaa825499c72ac342983983fd3ba3a8a41f56677cc99ffd73da68b59e1383\"]}" - }, { - "amount": 1, - "secret": "[\"P2PK\",{\"nonce\":\"859d4935c4907062a6297cf4e663e2835d90d97ecdd510745d32f6816323a41f\",\"data\":\"02a60c27104cf6023581e790970fc33994a320abe36e7ceed16771b0f8d76f0666\",\"tags\":[[\"sigflag\",\"SIG_ALL\"]]}]", - "C": "02698c4e2b5f9534cd0687d87513c759790cf829aa5739184a3e3735471fbda904", - "id": "009a1f293253e41f", - "witness": "{\"signatures\":[\"60f3c9b766770b46caac1d27e1ae6b77c8866ebaeba0b9489fe6a15a837eaa6fcd6eaa825499c72ac342983983fd3ba3a8a41f56677cc99ffd73da68b59e1383\"]}" - }], - "outputs": [{ - "amount": 2, - "B_": "02698c4e2b5f9534cd0687d87513c759790cf829aa5739184a3e3735471fbda904", - "id": "009a1f293253e41e" - }] - }"#; + "inputs": [ + { + "amount": 1, + "id": "00bfa73302d12ffd", + "secret": "[\"P2PK\",{\"nonce\":\"e2a221fe361f19d95c5c3312ccff3ffa075b4fe37beec99de85a6ee70568385b\",\"data\":\"03dad7f9c588f4cbb55c2e1b7b802fa2bbc63a614d9e9ecdf56a8e7ee8ca65be86\",\"tags\":[[\"pubkeys\",\"025f2af63fd65ca97c3bde4070549683e72769d28def2f1cd3d63576cd9c2ffa6c\"],[\"n_sigs\",\"2\"],[\"sigflag\",\"SIG_ALL\"]]}]", + "C": "02a79c09b0605f4e7a21976b511cc7be01cdaeac54b29645258c84f2e74bff13f6", + "witness": "{\"signatures\":[\"b42c7af7e98ca4e3bba8b73702120970286196340b340c21299676dbc7b10cafaa7baeb243affc01afce3218616cf8b3f6b4baaf4414fedb31b0c6653912f769\",\"17781910e2d806cae464f8a692929ee31124c0cd7eaf1e0d94292c6cbc122da09076b649080b8de9201f87d83b99fe04e33d701817eb287d1cdd9c4d0410e625\"]}" + }, + { + "amount": 2, + "id": "00bfa73302d12ffd", + "secret": "[\"P2PK\",{\"nonce\":\"973c78b5e84c0986209dc14ba57682baf38fa4c1ea60c4c5f6834779a1a13e6d\",\"data\":\"02685df03c777837bc7155bd2d0d8e98eede7e956a4cd8a9edac84532584e68e0f\",\"tags\":[[\"pubkeys\",\"025f2af63fd65ca97c3bde4070549683e72769d28def2f1cd3d63576cd9c2ffa6c\"],[\"n_sigs\",\"2\"],[\"sigflag\",\"SIG_ALL\"]]}]", + "C": "02be48c564cf6a7b4d09fbaf3a78a153a79f687ac4623e48ce1788effc3fb1e024" + } + ], + "outputs": [ + { + "amount": 1, + "id": "00bfa73302d12ffd", + "B_": "038ec853d65ae1b79b5cdbc2774150b2cb288d6d26e12958a16fb33c32d9a86c39" + }, + { + "amount": 1, + "id": "00bfa73302d12ffd", + "B_": "03afe7c87e32d436f0957f1d70a2bca025822a84a8623e3a33aed0a167016e0ca5" + }, + { + "amount": 1, + "id": "00bfa73302d12ffd", + "B_": "02c0d4fce02a7a0f09e3f1bca952db910b17e81a7ebcbce62cd8dcfb127d21e37b" + } + ] + }"#; let invalid_swap: SwapRequest = serde_json::from_str(invalid_swap).unwrap(); assert!( - invalid_swap.verify_sig_all().is_err(), + invalid_swap.verify_spending_conditions().is_err(), "Invalid SIG_ALL swap request should fail verification" ); } #[test] - fn test_sig_all_swap_multi_sig() { - // SwapRequest with multi-sig SIG_ALL requiring 2 signatures - let multisig_swap = r#"{"inputs":[{"amount":0,"id":"009a1f293253e41e","secret":"[\"P2PK\",{\"nonce\":\"c537ea76c1ac9cfa44d15dac91a63315903a3b4afa8e4e20f868f87f65ff2d16\",\"data\":\"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a\",\"tags\":[[\"pubkeys\",\"03142715675faf8da1ecc4d51e0b9e539fa0d52fdd96ed60dbe99adb15d6b05ad9\"],[\"n_sigs\",\"2\"],[\"sigflag\",\"SIG_ALL\"]]}]","C":"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a","witness":"{\"signatures\":[\"c38cf7943f59206dc22734d39c17e342674a4025e6d3b424eb79d445a57257d57b45dd94fcd1b8dd8013e9240a4133bdef6523f64cd7288d890f3bbb8e3c6453\",\"f766dbb80e5c27de9a4770486e11e1bac0b1c4f782bf807a5189ea9c3e294559a3de4e217d3dfceafd4d9e8dcbfe4e9a188052d6dab9df07df7844224292de36\"]}"}],"outputs":[{"amount":0,"id":"009a1f293253e41e","B_":"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a"}]}"#; + fn test_sig_all_mixed_pubkeys_and_refund_pubkeys() { + // SwapRequest with mixed up signatures from pubkey and refund_pubkeys + let invalidsig_all_swap = r#"{ + "inputs": [ + { + "amount": 2, + "id": "00bfa73302d12ffd", + "secret": "[\"P2PK\",{\"nonce\":\"cc93775c74df53d7c97eb37f72018d166a45ce4f4c65f11c4014b19acd02bd2f\",\"data\":\"02f515ab63e973e0dadfc284bf2ef330b01aa99c3ff775d88272f9c17afa25568c\",\"tags\":[[\"pubkeys\",\"026925e5bb547a3ec6b2d9b8934e23b882f54f89b2a9f45300bf81fd1b311d9c97\"],[\"n_sigs\",\"2\"],[\"refund\",\"03c8cd46b7e6592c41df38bc54dce2555586e7adbb15cc80a02d1a05829677286d\"],[\"n_sigs_refund\",\"1\"],[\"sigflag\",\"SIG_ALL\"]]}]", + "C": "03f6d40d0ab11f4082ee7e977534a6fcd151394d647cde4ab122157e6d755410fd", + "witness": "{\"signatures\":[\"a9f61c2b7161a50839bf7f3e2e1cb9bd7bdacd2ce62c0d458a5969db44646dad409a282241b412e8b191cc7432bcfebf16ad72339a9fb966ca71c8bd971662cc\",\"aa778ec15fe9408e1989c712c823e833f33d45780b9a25555ea76004b05d495e99fd326914484f92e7e91f919ee575e79add26e9d4bbe4349d7333d7e0021af7\"]}" + } + ], + "outputs": [ + { + "amount": 1, + "id": "00bfa73302d12ffd", + "B_": "038ec853d65ae1b79b5cdbc2774150b2cb288d6d26e12958a16fb33c32d9a86c39" + }, + { + "amount": 1, + "id": "00bfa73302d12ffd", + "B_": "03afe7c87e32d436f0957f1d70a2bca025822a84a8623e3a33aed0a167016e0ca5" + } + ] +}"#; - let multisig_swap: SwapRequest = serde_json::from_str(multisig_swap).unwrap(); + let invalid_swap: SwapRequest = serde_json::from_str(invalidsig_all_swap).unwrap(); assert!( - multisig_swap.verify_sig_all().is_ok(), - "Multi-sig SIG_ALL swap request should verify with both signatures" + invalid_swap.verify_spending_conditions().is_err(), + "Invalid SIG_ALL swap request should fail verification" ); } #[test] - fn test_sig_all_swap_msg_to_sign() { - // SwapRequest with multi-sig SIG_ALL requiring 2 signatures - let multisig_swap = r#"{"inputs":[{"amount":0,"id":"009a1f293253e41e","secret":"[\"P2PK\",{\"nonce\":\"c537ea76c1ac9cfa44d15dac91a63315903a3b4afa8e4e20f868f87f65ff2d16\",\"data\":\"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a\",\"tags\":[[\"pubkeys\",\"03142715675faf8da1ecc4d51e0b9e539fa0d52fdd96ed60dbe99adb15d6b05ad9\"],[\"n_sigs\",\"2\"],[\"sigflag\",\"SIG_ALL\"]]}]","C":"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a","witness":"{\"signatures\":[\"c38cf7943f59206dc22734d39c17e342674a4025e6d3b424eb79d445a57257d57b45dd94fcd1b8dd8013e9240a4133bdef6523f64cd7288d890f3bbb8e3c6453\",\"f766dbb80e5c27de9a4770486e11e1bac0b1c4f782bf807a5189ea9c3e294559a3de4e217d3dfceafd4d9e8dcbfe4e9a188052d6dab9df07df7844224292de36\"]}"}],"outputs":[{"amount":0,"id":"009a1f293253e41e","B_":"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a"}]}"#; + fn test_sig_all_htlc_unexpired_timelock_refund_signature() { + // SwapRequest signed with refund_pubkey without expiration + let invalidsig_all_swap = r#"{ + "inputs": [ + { + "amount": 2, + "id": "00bfa73302d12ffd", + "secret": "[\"HTLC\",{\"nonce\":\"b6f0c59ea4084369d4196e1318477121c2451d59ae767060e083cb6846e6bbe0\",\"data\":\"ec4916dd28fc4c10d78e287ca5d9cc51ee1ae73cbfde08c6b37324cbfaac8bc5\",\"tags\":[[\"pubkeys\",\"0329fdfde4becf9ff871129653ff6464bb2c922fbcba442e6166a8b5849599604f\"],[\"locktime\",\"4854185133\"],[\"refund\",\"035fcf4a5393e4bdef0567aa0b8a9555edba36e5fcb283f3bbce52d86a687817d3\"],[\"sigflag\",\"SIG_ALL\"]]}]", + "C": "024fbbee3f3cc306a48841ba327435b64de20b8b172b98296a3e573c673d52562b", + "witness": "{\"preimage\":\"0000000000000000000000000000000000000000000000000000000000000001\",\"signatures\":[\"7526819070a291f731e77acfbe9da71ddc0f748fd2a3e6c2510bc83c61daaa656df345afa3832fe7cb94352c8835a4794ad499760729c0be29417387d1fc3cd1\"]}" + } + ], + "outputs": [ + { + "amount": 2, + "id": "00bfa73302d12ffd", + "B_": "038ec853d65ae1b79b5cdbc2774150b2cb288d6d26e12958a16fb33c32d9a86c39" + } + ] +}"#; - let multisig_swap: SwapRequest = serde_json::from_str(multisig_swap).unwrap(); + let invalid_swap: SwapRequest = serde_json::from_str(invalidsig_all_swap).unwrap(); + assert!( + invalid_swap.verify_spending_conditions().is_err(), + "Invalid SIG_ALL swap request should fail verification" + ); + } - let msg_to_sign = multisig_swap.sig_all_msg_to_sign(); + // Now the Melt examples at the end of 11-test.md + #[test] + fn test_sig_all_melt() { + // Valid MeltRequest with SIG_ALL signature + // Example MeltRequest: + let valid_melt = r#"{ + "quote": "cF8911fzT88aEi1d-6boZZkq5lYxbUSVs-HbJxK0", + "inputs": [ + { + "amount": 2, + "id": "00bfa73302d12ffd", + "secret": "[\"P2PK\",{\"nonce\":\"bbf9edf441d17097e39f5095a3313ba24d3055ab8a32f758ff41c10d45c4f3de\",\"data\":\"029116d32e7da635c8feeb9f1f4559eb3d9b42d400f9d22a64834d89cde0eb6835\",\"tags\":[[\"sigflag\",\"SIG_ALL\"]]}]", + "C": "02a9d461ff36448469dccf828fa143833ae71c689886ac51b62c8d61ddaa10028b", + "witness": "{\"signatures\":[\"478224fbe715e34f78cb33451db6fcf8ab948afb8bd04ff1a952c92e562ac0f7c1cb5e61809410635be0aa94d0448f7f7959bd5762cc3802b0a00ff58b2da747\"]}" + } + ], + "outputs": [ + { + "amount": 0, + "id": "00bfa73302d12ffd", + "B_": "038ec853d65ae1b79b5cdbc2774150b2cb288d6d26e12958a16fb33c32d9a86c39" + } + ] +}"#; - println!("{}", msg_to_sign); + let valid_melt: MeltRequest = serde_json::from_str(valid_melt).unwrap(); + // Verify the message format + let msg_to_sign = valid_melt.sig_all_msg_to_sign(); assert_eq!( msg_to_sign, - r#"["P2PK",{"nonce":"c537ea76c1ac9cfa44d15dac91a63315903a3b4afa8e4e20f868f87f65ff2d16","data":"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a","tags":[["pubkeys","03142715675faf8da1ecc4d51e0b9e539fa0d52fdd96ed60dbe99adb15d6b05ad9"],["n_sigs","2"],["sigflag","SIG_ALL"]]}]026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a"# - ) + r#"["P2PK",{"nonce":"bbf9edf441d17097e39f5095a3313ba24d3055ab8a32f758ff41c10d45c4f3de","data":"029116d32e7da635c8feeb9f1f4559eb3d9b42d400f9d22a64834d89cde0eb6835","tags":[["sigflag","SIG_ALL"]]}]02a9d461ff36448469dccf828fa143833ae71c689886ac51b62c8d61ddaa10028b0038ec853d65ae1b79b5cdbc2774150b2cb288d6d26e12958a16fb33c32d9a86c39cF8911fzT88aEi1d-6boZZkq5lYxbUSVs-HbJxK0"# + ); + + // Verify the SHA256 hash of the message + use bitcoin::hashes::{sha256, Hash}; + let msg_hash = sha256::Hash::hash(msg_to_sign.as_bytes()); + assert_eq!( + msg_hash.to_string(), + "9efa1067cc7dc870f4074f695115829c3cd817a6866c3b84e9814adf3c3cf262" + ); + + assert!( + valid_melt.verify_spending_conditions().is_ok(), + "Valid SIG_ALL melt request should verify" + ); } #[test] - fn test_sig_all_melt() { - // MeltRequest with valid SIG_ALL signature - let valid_melt = r#"{"quote":"0f983814-de91-46b8-8875-1b358a35298a","inputs":[{"amount":0,"id":"009a1f293253e41e","secret":"[\"P2PK\",{\"nonce\":\"600050bd36cccdc71dec82e97679fa3e7712c22ea33cf4fe69d4d78223757e57\",\"data\":\"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a\",\"tags\":[[\"pubkeys\",\"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a\"],[\"sigflag\",\"SIG_ALL\"]]}]","C":"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a","witness":"{\"signatures\":[\"b66c342654ccc95a62100f8f4a76afe1aea612c9c63383be3c7feb5110bb8eabe7ccaa9f117abd524be8c9a2e331e7d70248aeae337b9ce405625b3c49fc627d\"]}"}],"outputs":[{"amount":0,"id":"009a1f293253e41e","B_":"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a"}]}"#; + fn test_sig_all_valid_melt() { + // The following is a valid SIG_ALL MeltRequest. + let valid_melt = r#"{ + "quote": "cF8911fzT88aEi1d-6boZZkq5lYxbUSVs-HbJxK0", + "inputs": [ + { + "amount": 2, + "id": "00bfa73302d12ffd", + "secret": "[\"P2PK\",{\"nonce\":\"bbf9edf441d17097e39f5095a3313ba24d3055ab8a32f758ff41c10d45c4f3de\",\"data\":\"029116d32e7da635c8feeb9f1f4559eb3d9b42d400f9d22a64834d89cde0eb6835\",\"tags\":[[\"sigflag\",\"SIG_ALL\"]]}]", + "C": "02a9d461ff36448469dccf828fa143833ae71c689886ac51b62c8d61ddaa10028b", + "witness": "{\"signatures\":[\"478224fbe715e34f78cb33451db6fcf8ab948afb8bd04ff1a952c92e562ac0f7c1cb5e61809410635be0aa94d0448f7f7959bd5762cc3802b0a00ff58b2da747\"]}" + } + ], + "outputs": [ + { + "amount": 0, + "id": "00bfa73302d12ffd", + "B_": "038ec853d65ae1b79b5cdbc2774150b2cb288d6d26e12958a16fb33c32d9a86c39" + } + ] +}"#; + + let valid_melt: MeltRequest = serde_json::from_str(valid_melt).unwrap(); + + assert!( + valid_melt.verify_spending_conditions().is_ok(), + "Valid SIG_ALL melt request should verify" + ); + } + + #[test] + fn test_sig_all_valid_multisig_melt() { + // The following is a valid multi-sig SIG_ALL MeltRequest. + let valid_melt = r#"{ + "quote": "Db3qEMVwFN2tf_1JxbZp29aL5cVXpSMIwpYfyOVF", + "inputs": [ + { + "amount": 2, + "id": "00bfa73302d12ffd", + "secret": "[\"P2PK\",{\"nonce\":\"68d7822538740e4f9c9ebf5183ef6c4501c7a9bca4e509ce2e41e1d62e7b8a99\",\"data\":\"0394e841bd59aeadce16380df6174cb29c9fea83b0b65b226575e6d73cc5a1bd59\",\"tags\":[[\"pubkeys\",\"033d892d7ad2a7d53708b7a5a2af101cbcef69522bd368eacf55fcb4f1b0494058\"],[\"n_sigs\",\"2\"],[\"sigflag\",\"SIG_ALL\"]]}]", + "C": "03a70c42ec9d7192422c7f7a3ad017deda309fb4a2453fcf9357795ea706cc87a9", + "witness": "{\"signatures\":[\"ed739970d003f703da2f101a51767b63858f4894468cc334be04aa3befab1617a81e3eef093441afb499974152d279e59d9582a31dc68adbc17ffc22a2516086\",\"f9efe1c70eb61e7ad8bd615c50ff850410a4135ea73ba5fd8e12a734743ad045e575e9e76ea5c52c8e7908d3ad5c0eaae93337e5c11109e52848dc328d6757a2\"]}" + } + ], + "outputs": [ + { + "amount": 0, + "id": "00bfa73302d12ffd", + "B_": "038ec853d65ae1b79b5cdbc2774150b2cb288d6d26e12958a16fb33c32d9a86c39" + } + ] +}"#; let valid_melt: MeltRequest = serde_json::from_str(valid_melt).unwrap(); + assert!( - valid_melt.verify_sig_all().is_ok(), + valid_melt.verify_spending_conditions().is_ok(), "Valid SIG_ALL melt request should verify" ); } @@ -1866,33 +1990,76 @@ mod tests { let invalid_melt: MeltRequest = serde_json::from_str(invalid_melt).unwrap(); assert!( - invalid_melt.verify_sig_all().is_err(), + invalid_melt.verify_spending_conditions().is_err(), "Invalid SIG_ALL melt request should fail verification" ); } #[test] + #[ignore] fn test_sig_all_melt_msg_to_sign() { - let multisig_melt = r#"{"quote":"2fc40ad3-2f6a-4a7e-91fb-b8c2b5dc2bf7","inputs":[{"amount":0,"id":"009a1f293253e41e","secret":"[\"P2PK\",{\"nonce\":\"1d0db9cbd2aa7370a3d6e0e3ce5714758ed7a085e2f8da9814924100e1fc622e\",\"data\":\"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a\",\"tags\":[[\"pubkeys\",\"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a\",\"03142715675faf8da1ecc4d51e0b9e539fa0d52fdd96ed60dbe99adb15d6b05ad9\"],[\"n_sigs\",\"2\"],[\"sigflag\",\"SIG_ALL\"]]}]","C":"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a","witness":"{\"signatures\":[\"b2077717cfe43086582679ce3fbe1802f9b8652f93828c2e1a75b9e553c0ab66cd14b9c5f6c45a098375fe6583e106c7ccdb1421636daf893576e15815f3483f\",\"179f687c2236c3d0767f3b2af88478cad312e7f76183fb5781754494709334c578c7232dc57017d06b9130a406f8e3ece18245064cda4ef66808ed3ff68c933e\"]}"}],"outputs":[{"amount":0,"id":"009a1f293253e41e","B_":"028b708cfd03b38bdc0a561008119594106f0c563061ae3fbfc8981b5595fd4e2b"}]}"#; + let multisig_melt = r#"{ + "quote": "uHwJ-f6HFAC-lU2dMw0KOu6gd5S571FXQQHioYMD", + "inputs": [ + { + "amount": 4, + "id": "00bfa73302d12ffd", + "secret": "[\"P2PK\",{\"nonce\":\"f5c26c928fb4433131780105eac330338bb9c0af2b2fd29fad9e4f18c4a96d84\",\"data\":\"03c4840e19277822bfeecf104dcd3f38d95b33249983ac6fed755869f23484fb2a\",\"tags\":[[\"pubkeys\",\"0256dcc53d9330e0bc6e9b3d47c26287695aba9fe55cafdde6f46ef56e09582bfb\"],[\"n_sigs\",\"1\"],[\"sigflag\",\"SIG_ALL\"]]}]", + "C": "02174667f98114abeb741f4964bdc88a3b86efde0afa38f791094c1e07e5df3beb", + "witness": "{\"signatures\":[\"abeeceba92bc7d1c514844ddb354d1e88a9776dfb55d3cdc5c289240386e401c3d983b68371ce5530e86c8fc4ff90195982a262f83fa8a5335b43e75af5f5fc7\"]}" + } + ], + "outputs": [ + { + "amount": 0, + "id": "00bfa73302d12ffd", + "B_": "038ec853d65ae1b79b5cdbc2774150b2cb288d6d26e12958a16fb33c32d9a86c39" + } + ] +}"#; let multisig_melt: MeltRequest = serde_json::from_str(multisig_melt).unwrap(); + assert!( + multisig_melt.verify_spending_conditions().is_ok(), + "melt request with SIG_ALL should succeed" + ); + let msg_to_sign = multisig_melt.sig_all_msg_to_sign(); assert_eq!( msg_to_sign, - r#"["P2PK",{"nonce":"1d0db9cbd2aa7370a3d6e0e3ce5714758ed7a085e2f8da9814924100e1fc622e","data":"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a","tags":[["pubkeys","026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a","03142715675faf8da1ecc4d51e0b9e539fa0d52fdd96ed60dbe99adb15d6b05ad9"],["n_sigs","2"],["sigflag","SIG_ALL"]]}]028b708cfd03b38bdc0a561008119594106f0c563061ae3fbfc8981b5595fd4e2b2fc40ad3-2f6a-4a7e-91fb-b8c2b5dc2bf7"# + r#"["P2PK",{"nonce":"f5c26c928fb4433131780105eac330338bb9c0af2b2fd29fad9e4f18c4a96d84","data":"03c4840e19277822bfeecf104dcd3f38d95b33249983ac6fed755869f23484fb2a","tags":[["pubkeys","0256dcc53d9330e0bc6e9b3d47c26287695aba9fe55cafdde6f46ef56e09582bfb"],["n_sigs","1"],["sigflag","SIG_ALL"]]}]02174667f98114abeb741f4964bdc88a3b86efde0afa38f791094c1e07e5df3beb000bfa73302d12ffd038ec853d65ae1b79b5cdbc2774150b2cb288d6d26e12958a16fb33c32d9a86c39uHwJ-f6HFAC-lU2dMw0KOu6gd5S571FXQQHioYMD"# ); } #[test] + #[ignore] fn test_sig_all_melt_multi_sig() { // MeltRequest with multi-sig SIG_ALL requiring 2 signatures - let multisig_melt = r#"{"quote":"2fc40ad3-2f6a-4a7e-91fb-b8c2b5dc2bf7","inputs":[{"amount":0,"id":"009a1f293253e41e","secret":"[\"P2PK\",{\"nonce\":\"1d0db9cbd2aa7370a3d6e0e3ce5714758ed7a085e2f8da9814924100e1fc622e\",\"data\":\"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a\",\"tags\":[[\"pubkeys\",\"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a\",\"03142715675faf8da1ecc4d51e0b9e539fa0d52fdd96ed60dbe99adb15d6b05ad9\"],[\"n_sigs\",\"2\"],[\"sigflag\",\"SIG_ALL\"]]}]","C":"026f6a2b1d709dbca78124a9f30a742985f7eddd894e72f637f7085bf69b997b9a","witness":"{\"signatures\":[\"b2077717cfe43086582679ce3fbe1802f9b8652f93828c2e1a75b9e553c0ab66cd14b9c5f6c45a098375fe6583e106c7ccdb1421636daf893576e15815f3483f\",\"179f687c2236c3d0767f3b2af88478cad312e7f76183fb5781754494709334c578c7232dc57017d06b9130a406f8e3ece18245064cda4ef66808ed3ff68c933e\"]}"}],"outputs":[{"amount":0,"id":"009a1f293253e41e","B_":"028b708cfd03b38bdc0a561008119594106f0c563061ae3fbfc8981b5595fd4e2b"}]}"#; + let multisig_melt = r#"{ + "quote": "wYHbJm5S1GTL28tDHoUAwcvb-31vu5kfDhnLxV9D", + "inputs": [ + { + "amount": 4, + "id": "00bfa73302d12ffd", + "secret": "[\"P2PK\",{\"nonce\":\"1705e988054354b703bc9103472cc5646ec76ed557517410186fa827c19c444d\",\"data\":\"024c8b5ec0e560f1fc77d7872ab75dd10a00af73a8ba715b81093b800849cb21fb\",\"tags\":[[\"pubkeys\",\"028d32bc906b3724724244812c450f688c548020f5d5a8c1d6cd1075650933d1a3\"],[\"n_sigs\",\"2\"],[\"sigflag\",\"SIG_ALL\"]]}]", + "C": "02f2a0ff12c4dd95f2476662f1df49e5126f09a5ea1f3ce13b985db57661953072", + "witness": "{\"signatures\":[\"a98a2616716d7813394a54ddc82234e5c47f0ddbddb98ccd1cad25236758fa235c8ae64d9fccd15efbe0ad5eba52a3df8433e9f1c05bc50defcb9161a5bd4bc4\",\"dd418cbbb23276dab8d72632ee77de730b932a3c6e8e15bc8802cef13db0b346915fe6e04e7fae03c3b5af026e25f71a24dc05b28135f0a9b69bc6c7289b6b8d\"]}" + } + ], + "outputs": [ + { + "amount": 0, + "id": "00bfa73302d12ffd", + "B_": "038ec853d65ae1b79b5cdbc2774150b2cb288d6d26e12958a16fb33c32d9a86c39" + } + ] +}"#; let multisig_melt: MeltRequest = serde_json::from_str(multisig_melt).unwrap(); assert!( - multisig_melt.verify_sig_all().is_ok(), + multisig_melt.verify_spending_conditions().is_ok(), "Multi-sig SIG_ALL melt request should verify with both signatures" ); @@ -1912,7 +2079,7 @@ mod tests { let insufficient_sigs_melt: MeltRequest = serde_json::from_str(insufficient_sigs_melt).unwrap(); assert!( - insufficient_sigs_melt.verify_sig_all().is_err(), + insufficient_sigs_melt.verify_spending_conditions().is_err(), "Multi-sig SIG_ALL melt request should fail with insufficient signatures" ); } @@ -1944,7 +2111,7 @@ mod tests { // Test basic signing flow let mut swap = SwapRequest::new(vec![proof1, proof2], vec![blinded_msg]); assert!( - swap.verify_sig_all().is_err(), + swap.verify_spending_conditions().is_err(), "Unsigned swap should fail verification" ); @@ -1956,7 +2123,7 @@ mod tests { println!("{}", serde_json::to_string(&swap).unwrap()); assert!( - swap.verify_sig_all().is_ok(), + swap.verify_spending_conditions().is_ok(), "Signed swap should pass verification" ); } @@ -1980,9 +2147,14 @@ mod tests { .unwrap(); let mut swap = SwapRequest::new(vec![proof], vec![blinded_msg]); + + // Signing should succeed (no validation) + swap.sign_sig_all(unauthorized_key).unwrap(); + + // Verification should fail (unauthorized signature) assert!( - swap.sign_sig_all(unauthorized_key).is_err(), - "Signing with unauthorized key should fail" + swap.verify_spending_conditions().is_err(), + "Verification should fail with unauthorized key signature" ); } @@ -2012,9 +2184,14 @@ mod tests { let blinded_msg = create_test_blinded_msg(pubkey); let mut swap = SwapRequest::new(vec![proof1, proof2], vec![blinded_msg]); + + // Signing should succeed (no validation) + swap.sign_sig_all(secret_key).unwrap(); + + // Verification should fail (mismatched secrets) assert!( - swap.sign_sig_all(secret_key).is_err(), - "Signing with mismatched secrets should fail" + swap.verify_spending_conditions().is_err(), + "Verification should fail with mismatched secrets" ); } @@ -2033,9 +2210,14 @@ mod tests { let blinded_msg = create_test_blinded_msg(pubkey); let mut swap = SwapRequest::new(vec![proof], vec![blinded_msg]); + + // Signing should succeed (no validation) + swap.sign_sig_all(secret_key).unwrap(); + + // Verification should fail (wrong flag - has SIG_INPUTS but sign_sig_all expects SIG_ALL) assert!( - swap.sign_sig_all(secret_key).is_err(), - "Signing with SIG_INPUTS flag should fail" + swap.verify_spending_conditions().is_err(), + "Verification should fail with SIG_INPUTS flag when sign_sig_all was used" ); } @@ -2067,7 +2249,7 @@ mod tests { "First signature should succeed" ); assert!( - swap.verify_sig_all().is_err(), + swap.verify_spending_conditions().is_err(), "Single signature should not verify when two required" ); @@ -2078,7 +2260,7 @@ mod tests { ); assert!( - swap.verify_sig_all().is_ok(), + swap.verify_spending_conditions().is_ok(), "Both signatures should verify" ); } diff --git a/crates/cashu/src/nuts/nut14/mod.rs b/crates/cashu/src/nuts/nut14/mod.rs index 0c3c8ea1d..3a741b363 100644 --- a/crates/cashu/src/nuts/nut14/mod.rs +++ b/crates/cashu/src/nuts/nut14/mod.rs @@ -4,8 +4,6 @@ use std::str::FromStr; -use bitcoin::hashes::sha256::Hash as Sha256Hash; -use bitcoin::hashes::Hash; use bitcoin::secp256k1::schnorr::Signature; use serde::{Deserialize, Serialize}; use thiserror::Error; @@ -14,7 +12,6 @@ use super::nut00::Witness; use super::nut10::Secret; use super::nut11::valid_signatures; use super::{Conditions, Proof}; -use crate::ensure_cdk; use crate::util::{hex, unix_time}; pub mod serde_htlc_witness; @@ -46,6 +43,9 @@ pub enum Error { /// Witness Signatures not provided #[error("Witness did not provide signatures")] SignaturesNotProvided, + /// SIG_ALL not supported in this context + #[error("SIG_ALL proofs must be verified using a different method")] + SigAllNotSupportedHere, /// Secp256k1 error #[error(transparent)] Secp256k1(#[from] bitcoin::secp256k1::Error), @@ -68,87 +68,109 @@ pub struct HTLCWitness { pub signatures: Option>, } +impl HTLCWitness { + /// Decode the preimage from hex and verify it's exactly 32 bytes + /// + /// Returns the 32-byte preimage data if valid, or an error if: + /// - The hex decoding fails + /// - The decoded data is not exactly 32 bytes + pub fn preimage_data(&self) -> Result<[u8; 32], Error> { + const REQUIRED_PREIMAGE_BYTES: usize = 32; + + // Decode the 64-character hex string to bytes + let preimage_bytes = hex::decode(&self.preimage).map_err(|_| Error::InvalidHexPreimage)?; + + // Verify the preimage is exactly 32 bytes + if preimage_bytes.len() != REQUIRED_PREIMAGE_BYTES { + return Err(Error::PreimageInvalidSize); + } + + // Convert to fixed-size array + let mut array = [0u8; 32]; + array.copy_from_slice(&preimage_bytes); + Ok(array) + } +} + impl Proof { /// Verify HTLC pub fn verify_htlc(&self) -> Result<(), Error> { let secret: Secret = self.secret.clone().try_into()?; - let conditions: Option = secret + let spending_conditions: Conditions = secret .secret_data() .tags() - .and_then(|c| c.clone().try_into().ok()); - - let htlc_witness = match &self.witness { - Some(Witness::HTLCWitness(witness)) => witness, - _ => return Err(Error::IncorrectSecretKind), - }; + .cloned() + .unwrap_or_default() + .try_into()?; - const REQUIRED_PREIMAGE_BYTES: usize = 32; - - let preimage_bytes = - hex::decode(&htlc_witness.preimage).map_err(|_| Error::InvalidHexPreimage)?; + if spending_conditions.sig_flag == super::SigFlag::SigAll { + return Err(Error::SigAllNotSupportedHere); + } - if preimage_bytes.len() != REQUIRED_PREIMAGE_BYTES { - return Err(Error::PreimageInvalidSize); + if secret.kind() != super::Kind::HTLC { + return Err(Error::IncorrectSecretKind); } - if let Some(conditions) = conditions { - // Check locktime - if let Some(locktime) = conditions.locktime { - // If locktime is in passed and no refund keys provided anyone can spend - if locktime.lt(&unix_time()) && conditions.refund_keys.is_none() { - return Ok(()); - } - - // If refund keys are provided verify p2pk signatures - if let (Some(refund_key), Some(signatures)) = - (conditions.refund_keys, &self.witness) - { - let signatures = signatures - .signatures() - .ok_or(Error::SignaturesNotProvided)? - .iter() - .map(|s| Signature::from_str(s)) - .collect::, _>>()?; - - // If secret includes refund keys check that there is a valid signature - if valid_signatures(self.secret.as_bytes(), &refund_key, &signatures)?.ge(&1) { - return Ok(()); - } - } - } - // If pubkeys are present check there is a valid signature - if let Some(pubkey) = conditions.pubkeys { - let req_sigs = conditions.num_sigs.unwrap_or(1); - - let signatures = htlc_witness - .signatures - .as_ref() - .ok_or(Error::SignaturesNotProvided)?; - - let signatures = signatures - .iter() - .map(|s| Signature::from_str(s)) - .collect::, _>>()?; - - let valid_sigs = valid_signatures(self.secret.as_bytes(), &pubkey, &signatures)?; - ensure_cdk!(valid_sigs >= req_sigs, Error::IncorrectSecretKind); - } + // Get the appropriate spending conditions based on locktime + let now = unix_time(); + let (preimage_needed, relevant_pubkeys, relevant_num_sigs_required) = + super::nut10::get_pubkeys_and_required_sigs(&secret, now).map_err(Error::NUT11)?; + + // While a Witness is usually needed in a P2PK or HTLC proof, it's not + // always needed. If we are past the locktime, and there are no refund + // keys, then the proofs are anyone-can-spend: + // NUT-11: "If the tag locktime is the unix time and the mint's local + // clock is greater than locktime, the Proof becomes spendable + // by anyone, except if [there are no refund keys]" + // Therefore, this function should not extract any Witness unless it + // is needed to get a preimage or signatures. + + // If preimage is needed (before locktime), verify it + if preimage_needed { + // Extract HTLC witness + let htlc_witness = match &self.witness { + Some(Witness::HTLCWitness(witness)) => witness, + _ => return Err(Error::IncorrectSecretKind), + }; + + // Verify preimage using shared function + super::nut10::verify_htlc_preimage(htlc_witness, &secret)?; } - if secret.kind().ne(&super::Kind::HTLC) { - return Err(Error::IncorrectSecretKind); + if relevant_num_sigs_required == 0 { + return Ok(()); } - let hash_lock = - Sha256Hash::from_str(secret.secret_data().data()).map_err(|_| Error::InvalidHash)?; + // if we get here, the preimage check (if it was needed) has been done + // and we know that at least one signature is required. So, we extract + // the witness.signatures and count them: + + // Extract witness signatures + let htlc_witness = match &self.witness { + Some(Witness::HTLCWitness(witness)) => witness, + _ => return Err(Error::IncorrectSecretKind), + }; + let witness_signatures = htlc_witness + .signatures + .as_ref() + .ok_or(Error::SignaturesNotProvided)?; - let preimage_hash = Sha256Hash::hash(&preimage_bytes); + // Convert signatures from strings + let signatures: Vec = witness_signatures + .iter() + .map(|s| Signature::from_str(s)) + .collect::, _>>()?; - if hash_lock.ne(&preimage_hash) { - return Err(Error::Preimage); - } + // Count valid signatures using relevant_pubkeys + let msg: &[u8] = self.secret.as_bytes(); + let valid_sig_count = valid_signatures(msg, &relevant_pubkeys, &signatures)?; - Ok(()) + // Check if we have enough valid signatures + if valid_sig_count >= relevant_num_sigs_required { + Ok(()) + } else { + Err(Error::NUT11(super::nut11::Error::SpendConditionsNotMet)) + } } /// Add Preimage diff --git a/crates/cdk-signatory/src/signatory.rs b/crates/cdk-signatory/src/signatory.rs index 0b987a72f..27cf8fef4 100644 --- a/crates/cdk-signatory/src/signatory.rs +++ b/crates/cdk-signatory/src/signatory.rs @@ -148,7 +148,7 @@ pub trait Signatory { blinded_messages: Vec, ) -> Result, Error>; - /// Verify [`Proof`] meets conditions and is signed + /// Verify [`Proof`] meets conditions and is signed by the mint (ignores P2PK/HTLC signatures" async fn verify_proofs(&self, proofs: Vec) -> Result<(), Error>; /// Retrieve the list of all mint keysets diff --git a/crates/cdk/src/lib.rs b/crates/cdk/src/lib.rs index 4f5e55630..5cf104051 100644 --- a/crates/cdk/src/lib.rs +++ b/crates/cdk/src/lib.rs @@ -26,6 +26,9 @@ pub mod mint; #[cfg(feature = "wallet")] pub mod wallet; +#[cfg(test)] +mod test_helpers; + #[cfg(all(feature = "bip353", not(target_arch = "wasm32")))] mod bip353; @@ -49,9 +52,6 @@ pub use oidc_client::OidcClient; pub mod event; pub mod fees; -#[cfg(test)] -pub mod test_helpers; - #[doc(hidden)] pub use bitcoin::secp256k1; #[cfg(feature = "mint")] diff --git a/crates/cdk/src/mint/melt.rs b/crates/cdk/src/mint/melt/mod.rs similarity index 97% rename from crates/cdk/src/mint/melt.rs rename to crates/cdk/src/mint/melt/mod.rs index 5a7a88054..1ceae7e5a 100644 --- a/crates/cdk/src/mint/melt.rs +++ b/crates/cdk/src/mint/melt/mod.rs @@ -8,7 +8,7 @@ use cdk_common::payment::{ Bolt11OutgoingPaymentOptions, Bolt12OutgoingPaymentOptions, OutgoingPaymentOptions, }; use cdk_common::quote_id::QuoteId; -use cdk_common::{MeltOptions, MeltQuoteBolt12Request}; +use cdk_common::{MeltOptions, MeltQuoteBolt12Request, SpendingConditionVerification}; #[cfg(feature = "prometheus")] use cdk_prometheus::METRICS; use lightning::offers::offer::Offer; @@ -24,8 +24,11 @@ use crate::types::PaymentProcessorKey; use crate::util::unix_time; use crate::{ensure_cdk, Amount, Error}; -mod melt_saga; -pub(super) mod shared; +pub(crate) mod melt_saga; +pub(crate) mod shared; + +#[cfg(test)] +mod tests; use melt_saga::MeltSaga; @@ -422,6 +425,13 @@ impl Mint { &self, melt_request: &MeltRequest, ) -> Result, Error> { + // Verify spending conditions (NUT-10/NUT-11/NUT-14), i.e. P2PK + // and HTLC (including SIGALL) + melt_request.verify_spending_conditions()?; + + // We don't need to check P2PK or HTLC again. It has all been checked above + // and the code doesn't reach here unless such verifications were satisfactory + let verification = self.verify_inputs(melt_request.inputs()).await?; let init_saga = MeltSaga::new( diff --git a/crates/cdk/src/mint/melt/tests/htlc_sigall_spending_conditions_tests.rs b/crates/cdk/src/mint/melt/tests/htlc_sigall_spending_conditions_tests.rs new file mode 100644 index 000000000..fafaf309a --- /dev/null +++ b/crates/cdk/src/mint/melt/tests/htlc_sigall_spending_conditions_tests.rs @@ -0,0 +1,181 @@ +//! HTLC SIG_ALL tests for melt functionality +//! +//! These tests verify that the mint correctly enforces SIG_ALL flag behavior for HTLC +//! during melt operations. + +use std::str::FromStr; + +use cdk_common::dhke::construct_proofs; +use cdk_common::melt::MeltQuoteRequest; +use cdk_common::nuts::{Conditions, SigFlag, SpendingConditions}; +use cdk_common::Amount; +use cdk_common::SpendingConditionVerification; + +use crate::test_helpers::nut10::{ + create_test_hash_and_preimage, create_test_keypair, unzip3, TestMintHelper, +}; + +/// Test: HTLC SIG_ALL requiring preimage and one signature +/// +/// Creates HTLC-locked proofs with SIG_ALL flag and verifies: +/// 1. Melting with only preimage fails (signature required) +/// 2. Melting with only SIG_INPUTS signatures fails (SIG_ALL required) +/// 3. Melting with both preimage and SIG_ALL signature succeeds +#[tokio::test] +async fn test_htlc_sig_all_requiring_preimage_and_one_signature() { + let test_mint = TestMintHelper::new().await.unwrap(); + let mint = test_mint.mint(); + + // Generate keypair for Alice + let (alice_secret, alice_pubkey) = create_test_keypair(); + + // Create hash and preimage + let (hash, preimage) = create_test_hash_and_preimage(); + + println!("Alice pubkey: {}", alice_pubkey); + println!("Hash: {}", hash); + println!("Preimage: {}", preimage); + + // Step 1: Mint regular proofs (enough to cover invoice + fees) + let input_amount = Amount::from(20); + let input_proofs = test_mint.mint_proofs(input_amount).await.unwrap(); + + // Step 2: Create HTLC spending conditions with SIG_ALL flag (hash locked to Alice's key) + let spending_conditions = SpendingConditions::new_htlc_hash( + &hash, + Some(Conditions { + locktime: None, + pubkeys: Some(vec![alice_pubkey]), + refund_keys: None, + num_sigs: None, // Default (1) + sig_flag: SigFlag::SigAll, // <-- SIG_ALL flag + num_sigs_refund: None, + }), + ) + .unwrap(); + println!("Created HTLC spending conditions with SIG_ALL flag"); + + // Step 3: Create HTLC blinded messages (outputs) + let split_amounts = test_mint.split_amount(input_amount).unwrap(); + let split_display: Vec = split_amounts.iter().map(|a| a.to_string()).collect(); + println!("Split {} into [{}]", input_amount, split_display.join("+")); + + let (htlc_outputs, blinding_factors, secrets) = unzip3( + split_amounts + .iter() + .map(|&amt| test_mint.create_blinded_message(amt, &spending_conditions)) + .collect(), + ); + println!( + "Created {} HTLC outputs locked to alice with hash", + htlc_outputs.len() + ); + + // Step 4: Swap regular proofs for HTLC proofs (no signature needed on inputs) + let swap_request = cdk_common::SwapRequest::new(input_proofs.clone(), htlc_outputs.clone()); + let swap_response = mint + .process_swap_request(swap_request) + .await + .expect("Failed to swap for HTLC proofs"); + println!("Swap successful! Got BlindSignatures for our HTLC outputs"); + + // Step 5: Construct the HTLC proofs + let htlc_proofs = construct_proofs( + swap_response.signatures.clone(), + blinding_factors.clone(), + secrets.clone(), + &test_mint.public_keys_of_the_active_sat_keyset, + ) + .unwrap(); + + let proof_amounts: Vec = htlc_proofs.iter().map(|p| p.amount.to_string()).collect(); + println!( + "Constructed {} HTLC proof(s) [{}]", + htlc_proofs.len(), + proof_amounts.join("+") + ); + + // Step 6: Create a real melt quote that we'll use for all tests + let bolt11_str = "lnbc100n1pnvpufspp5djn8hrq49r8cghwye9kqw752qjncwyfnrprhprpqk43mwcy4yfsqdq5g9kxy7fqd9h8vmmfvdjscqzzsxqyz5vqsp5uhpjt36rj75pl7jq2sshaukzfkt7uulj456s4mh7uy7l6vx7lvxs9qxpqysgqedwz08acmqwtk8g4vkwm2w78suwt2qyzz6jkkwcgrjm3r3hs6fskyhvud4fan3keru7emjm8ygqpcrwtlmhfjfmer3afs5hhwamgr4cqtactdq"; + let bolt11 = cdk_common::Bolt11Invoice::from_str(bolt11_str).unwrap(); + + let melt_quote_request = cdk_common::MeltQuoteBolt11Request { + request: bolt11, + unit: cdk_common::CurrencyUnit::Sat, + options: None, + }; + + let melt_quote = mint + .get_melt_quote(MeltQuoteRequest::Bolt11(melt_quote_request)) + .await + .unwrap(); + println!("Created melt quote: {}", melt_quote.quote); + + // Step 7: Try to melt with only preimage (should fail - signature required) + let mut proofs_preimage_only = htlc_proofs.clone(); + // Add only preimage to first proof (no signature) + proofs_preimage_only[0].add_preimage(preimage.clone()); + + let melt_request_preimage_only = + cdk_common::MeltRequest::new(melt_quote.quote.clone(), proofs_preimage_only.into(), None); + + let result = melt_request_preimage_only.verify_spending_conditions(); + assert!( + result.is_err(), + "Should fail with only preimage (no signature)" + ); + println!("✓ Melting with ONLY preimage failed verification as expected"); + + let melt_result = mint.melt(&melt_request_preimage_only).await; + assert!( + melt_result.is_err(), + "Actual melt should also fail with only preimage" + ); + println!("✓ Actual melt with ONLY preimage also failed as expected"); + + // Step 8: Try to melt with SIG_INPUTS signatures (should fail - SIG_ALL required) + let mut melt_request_sig_inputs = + cdk_common::MeltRequest::new(melt_quote.quote.clone(), htlc_proofs.clone().into(), None); + + // Add preimage to first proof + melt_request_sig_inputs.inputs_mut()[0].add_preimage(preimage.clone()); + + // Sign each proof individually (SIG_INPUTS mode) - this should fail for SIG_ALL + for proof in melt_request_sig_inputs.inputs_mut() { + proof.sign_p2pk(alice_secret.clone()).unwrap(); + } + + let result = melt_request_sig_inputs.verify_spending_conditions(); + assert!( + result.is_err(), + "Should fail - SIG_INPUTS signatures not valid for SIG_ALL" + ); + println!("✓ Melting with SIG_INPUTS signatures failed verification as expected"); + + let melt_result = mint.melt(&melt_request_sig_inputs).await; + assert!( + melt_result.is_err(), + "Actual melt should also fail with SIG_INPUTS signatures" + ); + println!("✓ Actual melt with SIG_INPUTS signatures also failed as expected"); + + // Step 9: Now melt with correct preimage + SIG_ALL signature + let mut melt_request = + cdk_common::MeltRequest::new(melt_quote.quote.clone(), htlc_proofs.clone().into(), None); + + // Add preimage to first proof + melt_request.inputs_mut()[0].add_preimage(preimage.clone()); + + // Use sign_sig_all to sign the transaction (signature goes on first proof's witness) + melt_request.sign_sig_all(alice_secret.clone()).unwrap(); + + // Verify spending conditions pass + melt_request.verify_spending_conditions().unwrap(); + println!("✓ HTLC SIG_ALL spending conditions verified successfully"); + + // Perform the actual melt - this also verifies spending conditions internally + let melt_response = mint.melt(&melt_request).await.unwrap(); + println!("✓ Melt operation completed successfully!"); + println!(" Quote state: {:?}", melt_response.state); + assert_eq!(melt_response.quote, melt_quote.quote); +} diff --git a/crates/cdk/src/mint/melt/tests/htlc_spending_conditions_tests.rs b/crates/cdk/src/mint/melt/tests/htlc_spending_conditions_tests.rs new file mode 100644 index 000000000..8072187b3 --- /dev/null +++ b/crates/cdk/src/mint/melt/tests/htlc_spending_conditions_tests.rs @@ -0,0 +1,190 @@ +//! HTLC (NUT-14) tests for melt functionality +//! +//! These tests verify that the mint correctly validates HTLC spending conditions +//! during melt operations, including: +//! - Hash preimage verification +//! - Signature validation + +use cdk_common::dhke::construct_proofs; +use cdk_common::melt::MeltQuoteRequest; +use cdk_common::nuts::{Conditions, SigFlag, SpendingConditions}; +use cdk_common::Amount; + +use crate::test_helpers::nut10::{ + create_test_hash_and_preimage, create_test_keypair, unzip3, TestMintHelper, +}; + +/// Test: HTLC requiring preimage and one signature +/// +/// Creates HTLC-locked proofs and verifies: +/// 1. Melting with only preimage fails (signature required) +/// 2. Melting with only signature fails (preimage required) +/// 3. Melting with both preimage and signature succeeds +#[tokio::test] +async fn test_htlc_requiring_preimage_and_one_signature() { + let test_mint = TestMintHelper::new().await.unwrap(); + let mint = test_mint.mint(); + + // Generate keypair for Alice + let (alice_secret, alice_pubkey) = create_test_keypair(); + + // Create hash and preimage + let (hash, preimage) = create_test_hash_and_preimage(); + + println!("Alice pubkey: {}", alice_pubkey); + println!("Hash: {}", hash); + println!("Preimage: {}", preimage); + + // Step 1: Mint regular proofs (enough to cover the invoice amount + fees) + // Invoice is 10 sats, fee reserve is 100% (10 sats), so we need 20 sats total + let input_amount = Amount::from(20); + let input_proofs = test_mint.mint_proofs(input_amount).await.unwrap(); + + // Step 2: Create HTLC spending conditions (hash locked to Alice's key) + let spending_conditions = SpendingConditions::new_htlc_hash( + &hash, + Some(Conditions { + locktime: None, + pubkeys: Some(vec![alice_pubkey]), + refund_keys: None, + num_sigs: None, // Default (1) + sig_flag: SigFlag::default(), + num_sigs_refund: None, + }), + ) + .unwrap(); + println!("Created HTLC spending conditions"); + + // Step 3: Create HTLC blinded messages (outputs) + let split_amounts = test_mint.split_amount(input_amount).unwrap(); + let split_display: Vec = split_amounts.iter().map(|a| a.to_string()).collect(); + println!("Split {} into [{}]", input_amount, split_display.join("+")); + + let (htlc_outputs, blinding_factors, secrets) = unzip3( + split_amounts + .iter() + .map(|&amt| test_mint.create_blinded_message(amt, &spending_conditions)) + .collect(), + ); + println!( + "Created {} HTLC outputs locked to alice with hash", + htlc_outputs.len() + ); + + // Step 4: Swap regular proofs for HTLC proofs (no signature needed on inputs) + let swap_request = cdk_common::SwapRequest::new(input_proofs.clone(), htlc_outputs.clone()); + let swap_response = mint + .process_swap_request(swap_request) + .await + .expect("Failed to swap for HTLC proofs"); + println!("Swap successful! Got BlindSignatures for our HTLC outputs"); + + // Step 5: Construct the HTLC proofs + let htlc_proofs = construct_proofs( + swap_response.signatures.clone(), + blinding_factors.clone(), + secrets.clone(), + &test_mint.public_keys_of_the_active_sat_keyset, + ) + .unwrap(); + + let proof_amounts: Vec = htlc_proofs.iter().map(|p| p.amount.to_string()).collect(); + println!( + "Constructed {} HTLC proof(s) [{}]", + htlc_proofs.len(), + proof_amounts.join("+") + ); + + // Step 6: Create a real melt quote that we'll use for all tests + use cdk_common::SpendingConditionVerification; + use std::str::FromStr; + let bolt11_str = "lnbc100n1pnvpufspp5djn8hrq49r8cghwye9kqw752qjncwyfnrprhprpqk43mwcy4yfsqdq5g9kxy7fqd9h8vmmfvdjscqzzsxqyz5vqsp5uhpjt36rj75pl7jq2sshaukzfkt7uulj456s4mh7uy7l6vx7lvxs9qxpqysgqedwz08acmqwtk8g4vkwm2w78suwt2qyzz6jkkwcgrjm3r3hs6fskyhvud4fan3keru7emjm8ygqpcrwtlmhfjfmer3afs5hhwamgr4cqtactdq"; + let bolt11 = cdk_common::Bolt11Invoice::from_str(bolt11_str).unwrap(); + + let melt_quote_request = cdk_common::MeltQuoteBolt11Request { + request: bolt11, + unit: cdk_common::CurrencyUnit::Sat, + options: None, + }; + + let melt_quote = mint + .get_melt_quote(MeltQuoteRequest::Bolt11(melt_quote_request)) + .await + .unwrap(); + println!("Created melt quote: {}", melt_quote.quote); + + // Step 7: Try to melt with only preimage (should fail - signature required) + + let mut proofs_preimage_only = htlc_proofs.clone(); + + // Add only preimage (no signature) + for proof in proofs_preimage_only.iter_mut() { + proof.add_preimage(preimage.clone()); + } + + let melt_request_preimage_only = + cdk_common::MeltRequest::new(melt_quote.quote.clone(), proofs_preimage_only.into(), None); + + let result = melt_request_preimage_only.verify_spending_conditions(); + assert!( + result.is_err(), + "Should fail with only preimage (no signature)" + ); + println!("✓ Melting with ONLY preimage failed verification as expected"); + + // Also verify the actual melt fails + let melt_result = mint.melt(&melt_request_preimage_only).await; + assert!( + melt_result.is_err(), + "Actual melt should also fail with only preimage" + ); + println!("✓ Actual melt with ONLY preimage also failed as expected"); + + // Step 8: Try to melt with only signature (should fail - preimage required) + let mut proofs_signature_only = htlc_proofs.clone(); + + // Add only signature (no preimage) + for proof in proofs_signature_only.iter_mut() { + proof.sign_p2pk(alice_secret.clone()).unwrap(); + } + + let melt_request_signature_only = + cdk_common::MeltRequest::new(melt_quote.quote.clone(), proofs_signature_only.into(), None); + + let result = melt_request_signature_only.verify_spending_conditions(); + assert!( + result.is_err(), + "Should fail with only signature (no preimage)" + ); + println!("✓ Melting with ONLY signature failed verification as expected"); + + // Also verify the actual melt fails + let melt_result = mint.melt(&melt_request_signature_only).await; + assert!( + melt_result.is_err(), + "Actual melt should also fail with only signature" + ); + println!("✓ Actual melt with ONLY signature also failed as expected"); + + // Step 9: Now melt with correct preimage + signature + let mut proofs_both = htlc_proofs.clone(); + + // Add preimage and sign all proofs + for proof in proofs_both.iter_mut() { + proof.add_preimage(preimage.clone()); + proof.sign_p2pk(alice_secret.clone()).unwrap(); + } + + let melt_request = + cdk_common::MeltRequest::new(melt_quote.quote.clone(), proofs_both.into(), None); + + // Verify spending conditions pass + melt_request.verify_spending_conditions().unwrap(); + println!("✓ HTLC spending conditions verified successfully"); + + // Perform the actual melt - this also verifies spending conditions internally + let melt_response = mint.melt(&melt_request).await.unwrap(); + println!("✓ Melt operation completed successfully!"); + println!(" Quote state: {:?}", melt_response.state); + assert_eq!(melt_response.quote, melt_quote.quote); +} diff --git a/crates/cdk/src/mint/melt/tests/locktime_spending_conditions_tests.rs b/crates/cdk/src/mint/melt/tests/locktime_spending_conditions_tests.rs new file mode 100644 index 000000000..1fcfb524d --- /dev/null +++ b/crates/cdk/src/mint/melt/tests/locktime_spending_conditions_tests.rs @@ -0,0 +1,277 @@ +//! Locktime tests for melt functionality +//! +//! These tests verify that the mint correctly validates locktime spending conditions +//! during melt operations, including spending after locktime expiry. + +use std::str::FromStr; + +use cdk_common::dhke::construct_proofs; +use cdk_common::melt::MeltQuoteRequest; +use cdk_common::nuts::{Conditions, SigFlag, SpendingConditions}; +use cdk_common::Amount; +use cdk_common::SpendingConditionVerification; + +use crate::test_helpers::nut10::{create_test_keypair, unzip3, TestMintHelper}; +use crate::util::unix_time; + +/// Test: P2PK with locktime - spending after expiry +/// +/// Creates P2PK proofs with locktime and verifies: +/// 1. Melting before locktime with wrong key fails +/// 2. Melting after locktime with any key succeeds (anyone-can-spend) +#[tokio::test] +async fn test_p2pk_post_locktime_anyone_can_spend() { + let test_mint = TestMintHelper::new().await.unwrap(); + let mint = test_mint.mint(); + + // Generate keypairs + let (_alice_secret, alice_pubkey) = create_test_keypair(); + let (bob_secret, _bob_pubkey) = create_test_keypair(); + + println!("Alice pubkey: {}", alice_pubkey); + + // Step 1: Create regular unencumbered proofs + let input_amount = Amount::from(20); + let input_proofs = test_mint.mint_proofs(input_amount).await.unwrap(); + + // Step 2: Create P2PK spending conditions with locktime in the past (already expired) + // Locktime is 1 hour ago - so it's already expired + let locktime = unix_time() - 3600; + + let spending_conditions = SpendingConditions::new_p2pk( + alice_pubkey, + Some(Conditions { + locktime: Some(locktime), // Locktime in the past (expired) + pubkeys: None, // no additional pubkeys + refund_keys: None, // NO refund keys - anyone can spend! + num_sigs: None, // default (1) + sig_flag: SigFlag::SigInputs, // SIG_INPUTS flag + num_sigs_refund: None, // default (1) + }), + ); + println!( + "Created P2PK spending conditions with expired locktime: {}", + locktime + ); + + // Split the input amount + let split_amounts = test_mint.split_amount(input_amount).unwrap(); + let split_display: Vec = split_amounts.iter().map(|a| a.to_string()).collect(); + println!("Split {} into [{}]", input_amount, split_display.join("+")); + + // Create blinded messages + let (p2pk_outputs, blinding_factors, secrets) = unzip3( + split_amounts + .iter() + .map(|&amt| test_mint.create_blinded_message(amt, &spending_conditions)) + .collect(), + ); + println!("Created {} P2PK outputs with locktime", p2pk_outputs.len()); + + // Step 3: Swap for P2PK proofs + let swap_request = cdk_common::SwapRequest::new(input_proofs.clone(), p2pk_outputs.clone()); + let swap_response = mint + .process_swap_request(swap_request) + .await + .expect("Failed to swap for P2PK proofs"); + println!("Swap successful! Got BlindSignatures"); + + // Step 4: Construct the P2PK proofs + let p2pk_proofs = construct_proofs( + swap_response.signatures.clone(), + blinding_factors.clone(), + secrets.clone(), + &test_mint.public_keys_of_the_active_sat_keyset, + ) + .unwrap(); + + let proof_amounts: Vec = p2pk_proofs.iter().map(|p| p.amount.to_string()).collect(); + println!( + "Constructed {} P2PK proof(s) [{}]", + p2pk_proofs.len(), + proof_amounts.join("+") + ); + + // Step 5: Create a real melt quote + let bolt11_str = "lnbc100n1pnvpufspp5djn8hrq49r8cghwye9kqw752qjncwyfnrprhprpqk43mwcy4yfsqdq5g9kxy7fqd9h8vmmfvdjscqzzsxqyz5vqsp5uhpjt36rj75pl7jq2sshaukzfkt7uulj456s4mh7uy7l6vx7lvxs9qxpqysgqedwz08acmqwtk8g4vkwm2w78suwt2qyzz6jkkwcgrjm3r3hs6fskyhvud4fan3keru7emjm8ygqpcrwtlmhfjfmer3afs5hhwamgr4cqtactdq"; + let bolt11 = cdk_common::Bolt11Invoice::from_str(bolt11_str).unwrap(); + + let melt_quote_request = cdk_common::MeltQuoteBolt11Request { + request: bolt11, + unit: cdk_common::CurrencyUnit::Sat, + options: None, + }; + + let melt_quote = mint + .get_melt_quote(MeltQuoteRequest::Bolt11(melt_quote_request)) + .await + .unwrap(); + println!("Created melt quote: {}", melt_quote.quote); + + // Step 6: Try to melt with Bob's signature (wrong key, but locktime expired so should work) + let mut proofs_bob_signed = p2pk_proofs.clone(); + + // Sign with Bob's key (not Alice's) + for proof in proofs_bob_signed.iter_mut() { + proof.sign_p2pk(bob_secret.clone()).unwrap(); + } + + let melt_request_bob = + cdk_common::MeltRequest::new(melt_quote.quote.clone(), proofs_bob_signed.into(), None); + + // After locktime expiry, anyone can spend (signature verification is skipped) + melt_request_bob.verify_spending_conditions().unwrap(); + println!("✓ Post-locktime spending conditions verified successfully (anyone-can-spend)"); + + // Perform the actual melt + let melt_response = mint.melt(&melt_request_bob).await.unwrap(); + println!("✓ Melt operation completed successfully with Bob's key after locktime!"); + println!(" Quote state: {:?}", melt_response.state); + assert_eq!(melt_response.quote, melt_quote.quote); +} + +/// Test: P2PK with future locktime - must use correct key before expiry +/// +/// Creates P2PK proofs with future locktime and verifies: +/// 1. Melting with wrong key before locktime fails +/// 2. Melting with correct key before locktime succeeds +#[tokio::test] +async fn test_p2pk_before_locktime_requires_correct_key() { + let test_mint = TestMintHelper::new().await.unwrap(); + let mint = test_mint.mint(); + + // Generate keypairs + let (alice_secret, alice_pubkey) = create_test_keypair(); + let (bob_secret, _bob_pubkey) = create_test_keypair(); + + println!("Alice pubkey: {}", alice_pubkey); + + // Step 1: Create regular unencumbered proofs + let input_amount = Amount::from(20); + let input_proofs = test_mint.mint_proofs(input_amount).await.unwrap(); + + // Step 2: Create P2PK spending conditions with locktime FAR in the future + // Locktime is 1 year from now - definitely not expired yet + let locktime = unix_time() + 365 * 24 * 60 * 60; + + let spending_conditions = SpendingConditions::new_p2pk( + alice_pubkey, + Some( + Conditions::new( + Some(locktime), // Locktime in the future + None, // no additional pubkeys + None, // no refund keys + None, // default num_sigs (1) + Some(SigFlag::SigInputs), // SIG_INPUTS flag + None, // no num_sigs_refund + ) + .unwrap(), + ), + ); + println!( + "Created P2PK spending conditions with future locktime: {}", + locktime + ); + + // Split the input amount + let split_amounts = test_mint.split_amount(input_amount).unwrap(); + let split_display: Vec = split_amounts.iter().map(|a| a.to_string()).collect(); + println!("Split {} into [{}]", input_amount, split_display.join("+")); + + // Create blinded messages + let (p2pk_outputs, blinding_factors, secrets) = unzip3( + split_amounts + .iter() + .map(|&amt| test_mint.create_blinded_message(amt, &spending_conditions)) + .collect(), + ); + println!("Created {} P2PK outputs with locktime", p2pk_outputs.len()); + + // Step 3: Swap for P2PK proofs + let swap_request = cdk_common::SwapRequest::new(input_proofs.clone(), p2pk_outputs.clone()); + let swap_response = mint + .process_swap_request(swap_request) + .await + .expect("Failed to swap for P2PK proofs"); + println!("Swap successful! Got BlindSignatures"); + + // Step 4: Construct the P2PK proofs + let p2pk_proofs = construct_proofs( + swap_response.signatures.clone(), + blinding_factors.clone(), + secrets.clone(), + &test_mint.public_keys_of_the_active_sat_keyset, + ) + .unwrap(); + + let proof_amounts: Vec = p2pk_proofs.iter().map(|p| p.amount.to_string()).collect(); + println!( + "Constructed {} P2PK proof(s) [{}]", + p2pk_proofs.len(), + proof_amounts.join("+") + ); + + // Step 5: Create a real melt quote + let bolt11_str = "lnbc100n1pnvpufspp5djn8hrq49r8cghwye9kqw752qjncwyfnrprhprpqk43mwcy4yfsqdq5g9kxy7fqd9h8vmmfvdjscqzzsxqyz5vqsp5uhpjt36rj75pl7jq2sshaukzfkt7uulj456s4mh7uy7l6vx7lvxs9qxpqysgqedwz08acmqwtk8g4vkwm2w78suwt2qyzz6jkkwcgrjm3r3hs6fskyhvud4fan3keru7emjm8ygqpcrwtlmhfjfmer3afs5hhwamgr4cqtactdq"; + let bolt11 = cdk_common::Bolt11Invoice::from_str(bolt11_str).unwrap(); + + let melt_quote_request = cdk_common::MeltQuoteBolt11Request { + request: bolt11, + unit: cdk_common::CurrencyUnit::Sat, + options: None, + }; + + let melt_quote = mint + .get_melt_quote(MeltQuoteRequest::Bolt11(melt_quote_request)) + .await + .unwrap(); + println!("Created melt quote: {}", melt_quote.quote); + + // Step 6: Try to melt with Bob's signature (wrong key, locktime not expired) + let mut proofs_bob_signed = p2pk_proofs.clone(); + + // Sign with Bob's key (not Alice's) + for proof in proofs_bob_signed.iter_mut() { + proof.sign_p2pk(bob_secret.clone()).unwrap(); + } + + let melt_request_bob = + cdk_common::MeltRequest::new(melt_quote.quote.clone(), proofs_bob_signed.into(), None); + + // Before locktime expiry, wrong key should fail + let result = melt_request_bob.verify_spending_conditions(); + assert!( + result.is_err(), + "Should fail with wrong key before locktime" + ); + println!("✓ Melting with Bob's key before locktime failed verification as expected"); + + // Also verify the actual melt fails + let melt_result = mint.melt(&melt_request_bob).await; + assert!( + melt_result.is_err(), + "Actual melt should also fail with wrong key" + ); + println!("✓ Actual melt with Bob's key before locktime also failed as expected"); + + // Step 7: Now melt with Alice's signature (correct key) + let mut proofs_alice_signed = p2pk_proofs.clone(); + + // Sign with Alice's key (correct) + for proof in proofs_alice_signed.iter_mut() { + proof.sign_p2pk(alice_secret.clone()).unwrap(); + } + + let melt_request_alice = + cdk_common::MeltRequest::new(melt_quote.quote.clone(), proofs_alice_signed.into(), None); + + // Verify spending conditions pass + melt_request_alice.verify_spending_conditions().unwrap(); + println!("✓ Pre-locktime spending conditions verified successfully with Alice's key"); + + // Perform the actual melt + let melt_response = mint.melt(&melt_request_alice).await.unwrap(); + println!("✓ Melt operation completed successfully with Alice's key before locktime!"); + println!(" Quote state: {:?}", melt_response.state); + assert_eq!(melt_response.quote, melt_quote.quote); +} diff --git a/crates/cdk/src/mint/melt/tests/mod.rs b/crates/cdk/src/mint/melt/tests/mod.rs new file mode 100644 index 000000000..e3f8724c0 --- /dev/null +++ b/crates/cdk/src/mint/melt/tests/mod.rs @@ -0,0 +1,5 @@ +mod htlc_sigall_spending_conditions_tests; +mod htlc_spending_conditions_tests; +mod locktime_spending_conditions_tests; +mod p2pk_sigall_spending_conditions_tests; +mod p2pk_spending_conditions_tests; diff --git a/crates/cdk/src/mint/melt/tests/p2pk_sigall_spending_conditions_tests.rs b/crates/cdk/src/mint/melt/tests/p2pk_sigall_spending_conditions_tests.rs new file mode 100644 index 000000000..5cc2ef7e8 --- /dev/null +++ b/crates/cdk/src/mint/melt/tests/p2pk_sigall_spending_conditions_tests.rs @@ -0,0 +1,167 @@ +//! P2PK SIG_ALL tests for melt functionality +//! +//! These tests verify that the mint correctly enforces SIG_ALL flag behavior +//! during melt operations. + +use cdk_common::dhke::construct_proofs; +use cdk_common::melt::MeltQuoteRequest; +use cdk_common::nuts::{Conditions, SigFlag, SpendingConditions}; +use cdk_common::Amount; + +use crate::test_helpers::nut10::{create_test_keypair, unzip3, TestMintHelper}; + +/// Test: P2PK with SIG_ALL flag requires transaction signature +/// +/// Creates P2PK proofs with SIG_ALL flag and verifies: +/// 1. Melting without signature is rejected +/// 2. Melting with SIG_INPUTS signatures (individual proof signatures) is rejected +/// 3. Melting with SIG_ALL signature (transaction signature) succeeds +#[tokio::test] +async fn test_p2pk_sig_all_requires_transaction_signature() { + let test_mint = TestMintHelper::new().await.unwrap(); + let mint = test_mint.mint(); + + // Generate keypair for P2PK + let (alice_secret, alice_pubkey) = create_test_keypair(); + println!("Alice pubkey: {}", alice_pubkey); + + // Step 1: Create regular unencumbered proofs that we'll swap for P2PK proofs + // Invoice is 10 sats, fee reserve is 100% (10 sats), so we need 20 sats total + let input_amount = Amount::from(20); + let input_proofs = test_mint.mint_proofs(input_amount).await.unwrap(); + + // Step 2: Create P2PK blinded messages (outputs locked to alice_pubkey) with SIG_ALL + let spending_conditions = SpendingConditions::new_p2pk( + alice_pubkey, + Some( + Conditions::new( + None, // no locktime + None, // no additional pubkeys + None, // no refund keys + None, // default num_sigs (1) + Some(SigFlag::SigAll), // SIG_ALL flag + None, // no num_sigs_refund + ) + .unwrap(), + ), + ); + println!("Created P2PK spending conditions with SIG_ALL flag"); + + // Split the input amount into power-of-2 denominations + let split_amounts = test_mint.split_amount(input_amount).unwrap(); + let split_display: Vec = split_amounts.iter().map(|a| a.to_string()).collect(); + println!("Split {} into [{}]", input_amount, split_display.join("+")); + + // Create blinded messages for each split amount + let (p2pk_outputs, blinding_factors, secrets) = unzip3( + split_amounts + .iter() + .map(|&amt| test_mint.create_blinded_message(amt, &spending_conditions)) + .collect(), + ); + + println!( + "Created {} P2PK outputs locked to alice", + p2pk_outputs.len() + ); + + // Step 3: Swap regular proofs for P2PK proofs (no signature needed on inputs) + let swap_request = cdk_common::SwapRequest::new(input_proofs.clone(), p2pk_outputs.clone()); + let swap_response = mint + .process_swap_request(swap_request) + .await + .expect("Failed to swap for P2PK proofs"); + println!("Swap successful! Got BlindSignatures for our P2PK outputs"); + + // Step 4: Construct the P2PK proofs + let p2pk_proofs = construct_proofs( + swap_response.signatures.clone(), + blinding_factors.clone(), + secrets.clone(), + &test_mint.public_keys_of_the_active_sat_keyset, + ) + .unwrap(); + + let proof_amounts: Vec = p2pk_proofs.iter().map(|p| p.amount.to_string()).collect(); + println!( + "Constructed {} P2PK proof(s) [{}]", + p2pk_proofs.len(), + proof_amounts.join("+") + ); + + // Step 5: Create a real melt quote that we'll use for all tests + use cdk_common::SpendingConditionVerification; + use std::str::FromStr; + let bolt11_str = "lnbc100n1pnvpufspp5djn8hrq49r8cghwye9kqw752qjncwyfnrprhprpqk43mwcy4yfsqdq5g9kxy7fqd9h8vmmfvdjscqzzsxqyz5vqsp5uhpjt36rj75pl7jq2sshaukzfkt7uulj456s4mh7uy7l6vx7lvxs9qxpqysgqedwz08acmqwtk8g4vkwm2w78suwt2qyzz6jkkwcgrjm3r3hs6fskyhvud4fan3keru7emjm8ygqpcrwtlmhfjfmer3afs5hhwamgr4cqtactdq"; + let bolt11 = cdk_common::Bolt11Invoice::from_str(bolt11_str).unwrap(); + + let melt_quote_request = cdk_common::MeltQuoteBolt11Request { + request: bolt11, + unit: cdk_common::CurrencyUnit::Sat, + options: None, + }; + + let melt_quote = mint + .get_melt_quote(MeltQuoteRequest::Bolt11(melt_quote_request)) + .await + .unwrap(); + println!("Created melt quote: {}", melt_quote.quote); + + // Step 6: Try to melt P2PK proof WITHOUT signature (should fail) + + let melt_request_no_sig = + cdk_common::MeltRequest::new(melt_quote.quote.clone(), p2pk_proofs.clone().into(), None); + + let result = melt_request_no_sig.verify_spending_conditions(); + assert!(result.is_err(), "Should fail without signature"); + println!("✓ Melting WITHOUT signature failed verification as expected"); + + // Also verify the actual melt fails + let melt_result = mint.melt(&melt_request_no_sig).await; + assert!( + melt_result.is_err(), + "Actual melt should also fail without signature" + ); + println!("✓ Actual melt WITHOUT signature also failed as expected"); + + // Step 7: Sign all proofs individually (SIG_INPUTS way) - should fail for SIG_ALL + let mut melt_request_sig_inputs = + cdk_common::MeltRequest::new(melt_quote.quote.clone(), p2pk_proofs.clone().into(), None); + + // Sign each proof individually (SIG_INPUTS mode) + for proof in melt_request_sig_inputs.inputs_mut() { + proof.sign_p2pk(alice_secret.clone()).unwrap(); + } + + let result = melt_request_sig_inputs.verify_spending_conditions(); + assert!( + result.is_err(), + "Should fail - SIG_INPUTS signatures not valid for SIG_ALL" + ); + println!("✓ Melting with SIG_INPUTS signatures failed verification as expected"); + + // Also verify the actual melt fails + let melt_result = mint.melt(&melt_request_sig_inputs).await; + assert!( + melt_result.is_err(), + "Actual melt should also fail with SIG_INPUTS signatures" + ); + println!("✓ Actual melt with SIG_INPUTS signatures also failed as expected"); + + // Step 8: Sign the transaction with SIG_ALL and perform the melt + let mut melt_request = + cdk_common::MeltRequest::new(melt_quote.quote.clone(), p2pk_proofs.clone().into(), None); + + // Use sign_sig_all to sign the transaction (signature goes on first proof's witness) + melt_request.sign_sig_all(alice_secret.clone()).unwrap(); + + // Verify spending conditions pass + melt_request.verify_spending_conditions().unwrap(); + println!("✓ P2PK SIG_ALL spending conditions verified successfully"); + + // Perform the actual melt - this also verifies spending conditions internally + let melt_response = mint.melt(&melt_request).await.unwrap(); + println!("✓ Melt operation completed successfully!"); + println!(" Quote state: {:?}", melt_response.state); + assert_eq!(melt_response.quote, melt_quote.quote); +} diff --git a/crates/cdk/src/mint/melt/tests/p2pk_spending_conditions_tests.rs b/crates/cdk/src/mint/melt/tests/p2pk_spending_conditions_tests.rs new file mode 100644 index 000000000..0a8bc3c8e --- /dev/null +++ b/crates/cdk/src/mint/melt/tests/p2pk_spending_conditions_tests.rs @@ -0,0 +1,135 @@ +//! Basic P2PK tests for melt functionality (SIG_INPUTS mode) +//! +//! These tests verify that the mint correctly validates basic P2PK spending conditions +//! during melt operations. + +use std::str::FromStr; + +use cdk_common::dhke::construct_proofs; +use cdk_common::melt::MeltQuoteRequest; +use cdk_common::nuts::SpendingConditions; +use cdk_common::Amount; +use cdk_common::SpendingConditionVerification; + +use crate::test_helpers::nut10::{create_test_keypair, unzip3, TestMintHelper}; + +/// Test: Basic P2PK with SIG_INPUTS (default mode) +/// +/// Creates P2PK proofs with default SIG_INPUTS flag and verifies: +/// 1. Melting without signatures is rejected +/// 2. Melting with signatures on all proofs succeeds +#[tokio::test] +async fn test_p2pk_basic_sig_inputs() { + let test_mint = TestMintHelper::new().await.unwrap(); + let mint = test_mint.mint(); + + // Generate keypair for P2PK + let (alice_secret, alice_pubkey) = create_test_keypair(); + println!("Alice pubkey: {}", alice_pubkey); + + // Step 1: Create regular unencumbered proofs that we'll swap for P2PK proofs + let input_amount = Amount::from(20); + let input_proofs = test_mint.mint_proofs(input_amount).await.unwrap(); + + // Step 2: Create P2PK blinded messages (outputs locked to alice_pubkey) with default SIG_INPUTS + let spending_conditions = SpendingConditions::new_p2pk( + alice_pubkey, + None, // No additional conditions - uses default SIG_INPUTS + ); + println!("Created P2PK spending conditions with default SIG_INPUTS flag"); + + // Split the input amount into power-of-2 denominations + let split_amounts = test_mint.split_amount(input_amount).unwrap(); + let split_display: Vec = split_amounts.iter().map(|a| a.to_string()).collect(); + println!("Split {} into [{}]", input_amount, split_display.join("+")); + + // Create blinded messages for each split amount + let (p2pk_outputs, blinding_factors, secrets) = unzip3( + split_amounts + .iter() + .map(|&amt| test_mint.create_blinded_message(amt, &spending_conditions)) + .collect(), + ); + + println!( + "Created {} P2PK outputs locked to alice", + p2pk_outputs.len() + ); + + // Step 3: Swap regular proofs for P2PK proofs (no signature needed on inputs) + let swap_request = cdk_common::SwapRequest::new(input_proofs.clone(), p2pk_outputs.clone()); + let swap_response = mint + .process_swap_request(swap_request) + .await + .expect("Failed to swap for P2PK proofs"); + println!("Swap successful! Got BlindSignatures for our P2PK outputs"); + + // Step 4: Construct the P2PK proofs + let p2pk_proofs = construct_proofs( + swap_response.signatures.clone(), + blinding_factors.clone(), + secrets.clone(), + &test_mint.public_keys_of_the_active_sat_keyset, + ) + .unwrap(); + + let proof_amounts: Vec = p2pk_proofs.iter().map(|p| p.amount.to_string()).collect(); + println!( + "Constructed {} P2PK proof(s) [{}]", + p2pk_proofs.len(), + proof_amounts.join("+") + ); + + // Step 5: Create a real melt quote that we'll use for all tests + let bolt11_str = "lnbc100n1pnvpufspp5djn8hrq49r8cghwye9kqw752qjncwyfnrprhprpqk43mwcy4yfsqdq5g9kxy7fqd9h8vmmfvdjscqzzsxqyz5vqsp5uhpjt36rj75pl7jq2sshaukzfkt7uulj456s4mh7uy7l6vx7lvxs9qxpqysgqedwz08acmqwtk8g4vkwm2w78suwt2qyzz6jkkwcgrjm3r3hs6fskyhvud4fan3keru7emjm8ygqpcrwtlmhfjfmer3afs5hhwamgr4cqtactdq"; + let bolt11 = cdk_common::Bolt11Invoice::from_str(bolt11_str).unwrap(); + + let melt_quote_request = cdk_common::MeltQuoteBolt11Request { + request: bolt11, + unit: cdk_common::CurrencyUnit::Sat, + options: None, + }; + + let melt_quote = mint + .get_melt_quote(MeltQuoteRequest::Bolt11(melt_quote_request)) + .await + .unwrap(); + println!("Created melt quote: {}", melt_quote.quote); + + // Step 6: Try to melt P2PK proof WITHOUT signature (should fail) + let melt_request_no_sig = + cdk_common::MeltRequest::new(melt_quote.quote.clone(), p2pk_proofs.clone().into(), None); + + let result = melt_request_no_sig.verify_spending_conditions(); + assert!(result.is_err(), "Should fail without signature"); + println!("✓ Melting WITHOUT signature failed verification as expected"); + + // Also verify the actual melt fails + let melt_result = mint.melt(&melt_request_no_sig).await; + assert!( + melt_result.is_err(), + "Actual melt should also fail without signature" + ); + println!("✓ Actual melt WITHOUT signature also failed as expected"); + + // Step 7: Sign all proofs individually (SIG_INPUTS mode) and perform the melt + let mut proofs_signed = p2pk_proofs.clone(); + + // Sign each proof individually (SIG_INPUTS mode) + for proof in proofs_signed.iter_mut() { + proof.sign_p2pk(alice_secret.clone()).unwrap(); + } + + let melt_request = + cdk_common::MeltRequest::new(melt_quote.quote.clone(), proofs_signed.into(), None); + + // Verify spending conditions pass + melt_request.verify_spending_conditions().unwrap(); + println!("✓ P2PK SIG_INPUTS spending conditions verified successfully"); + + // Perform the actual melt - this also verifies spending conditions internally + let melt_response = mint.melt(&melt_request).await.unwrap(); + println!("✓ Melt operation completed successfully!"); + println!(" Quote state: {:?}", melt_response.state); + assert_eq!(melt_response.quote, melt_quote.quote); +} diff --git a/crates/cdk/src/mint/mod.rs b/crates/cdk/src/mint/mod.rs index 626515083..aac715e5c 100644 --- a/crates/cdk/src/mint/mod.rs +++ b/crates/cdk/src/mint/mod.rs @@ -10,10 +10,9 @@ use cdk_common::common::{PaymentProcessorKey, QuoteTTL}; #[cfg(feature = "auth")] use cdk_common::database::DynMintAuthDatabase; use cdk_common::database::{self, DynMintDatabase}; -use cdk_common::nuts::{self, BlindSignature, BlindedMessage, CurrencyUnit, Id, Kind}; +use cdk_common::nuts::{BlindSignature, BlindedMessage, CurrencyUnit, Id}; use cdk_common::payment::{DynMintPayment, WaitPaymentResponse}; pub use cdk_common::quote_id::QuoteId; -use cdk_common::secret; #[cfg(feature = "prometheus")] use cdk_prometheus::global; use cdk_signatory::signatory::{Signatory, SignatoryKeySet}; @@ -853,39 +852,12 @@ impl Mint { /// Verify [`Proof`] meets conditions and is signed #[tracing::instrument(skip_all)] pub async fn verify_proofs(&self, proofs: Proofs) -> Result<(), Error> { + // This ignore P2PK and HTLC, as all NUT-10 spending conditions are + // checked elsewhere. #[cfg(feature = "prometheus")] global::inc_in_flight_requests("verify_proofs"); - let result = async { - proofs - .iter() - .map(|proof| { - // Check if secret is a nut10 secret with conditions - if let Ok(secret) = - <&secret::Secret as TryInto>::try_into(&proof.secret) - { - // Checks and verifies known secret kinds. - // If it is an unknown secret kind it will be treated as a normal secret. - // Spending conditions will **not** be check. It is up to the wallet to ensure - // only supported secret kinds are used as there is no way for the mint to - // enforce only signing supported secrets as they are blinded at - // that point. - match secret.kind() { - Kind::P2PK => { - proof.verify_p2pk()?; - } - Kind::HTLC => { - proof.verify_htlc()?; - } - } - } - Ok(()) - }) - .collect::, Error>>()?; - - self.signatory.verify_proofs(proofs).await - } - .await; + let result = self.signatory.verify_proofs(proofs).await; #[cfg(feature = "prometheus")] { diff --git a/crates/cdk/src/mint/swap/mod.rs b/crates/cdk/src/mint/swap/mod.rs index e0368978c..073fbbebe 100644 --- a/crates/cdk/src/mint/swap/mod.rs +++ b/crates/cdk/src/mint/swap/mod.rs @@ -3,12 +3,15 @@ use cdk_prometheus::METRICS; use swap_saga::SwapSaga; use tracing::instrument; -use super::nut11::{enforce_sig_flag, EnforceSigFlag}; -use super::{Mint, SigFlag, SwapRequest, SwapResponse}; +use super::{Mint, SwapRequest, SwapResponse}; use crate::Error; +use cdk_common::SpendingConditionVerification; pub mod swap_saga; +#[cfg(test)] +mod tests; + impl Mint { /// Process Swap #[instrument(skip_all)] @@ -22,6 +25,13 @@ impl Mint { swap_request.input_amount()?; swap_request.output_amount()?; + // Verify spending conditions (NUT-10/NUT-11/NUT-14), i.e. P2PK + // and HTLC (including SIGALL) + swap_request.verify_spending_conditions()?; + + // We don't need to check P2PK or HTLC again. It has all been checked above + // and the code doesn't reach here unless such verifications were satisfactory + // Verify inputs (cryptographic verification, no DB needed) let input_verification = self.verify_inputs(swap_request.inputs()) @@ -34,9 +44,6 @@ impl Mint { err })?; - // Verify signature flag (no DB needed) - self.validate_sig_flag(&swap_request).await?; - // Step 1: Initialize the swap saga let init_saga = SwapSaga::new(self, self.localstore.clone(), self.pubsub_manager.clone()); @@ -65,16 +72,6 @@ impl Mint { Ok(response) } - async fn validate_sig_flag(&self, swap_request: &SwapRequest) -> Result<(), Error> { - let EnforceSigFlag { sig_flag, .. } = enforce_sig_flag(swap_request.inputs().clone()); - - if sig_flag == SigFlag::SigAll { - swap_request.verify_sig_all()?; - } - - Ok(()) - } - #[cfg(feature = "prometheus")] fn record_swap_failure(&self, operation: &str) { METRICS.dec_in_flight_requests(operation); diff --git a/crates/cdk/src/mint/swap/tests/htlc_sigall_spending_conditions_tests.rs b/crates/cdk/src/mint/swap/tests/htlc_sigall_spending_conditions_tests.rs new file mode 100644 index 000000000..7ff6fb4c8 --- /dev/null +++ b/crates/cdk/src/mint/swap/tests/htlc_sigall_spending_conditions_tests.rs @@ -0,0 +1,389 @@ +//! HTLC SIG_ALL tests for swap functionality +//! +//! These tests verify that the mint correctly enforces SIG_ALL flag behavior for HTLC + +use cdk_common::nuts::{Conditions, SigFlag, SpendingConditions}; +use cdk_common::Amount; + +use crate::test_helpers::nut10::{ + create_test_hash_and_preimage, create_test_keypair, unzip3, TestMintHelper, +}; + +/// Test: HTLC SIG_ALL requiring preimage and one signature +/// +/// Creates HTLC-locked proofs with SIG_ALL flag and verifies: +/// 1. Spending with only preimage fails (signature required) +/// 2. Spending with only signature fails (preimage required) +/// 3. Spending with both preimage and SIG_ALL signature succeeds +#[tokio::test] +async fn test_htlc_sig_all_requiring_preimage_and_one_signature() { + let test_mint = TestMintHelper::new().await.unwrap(); + let mint = test_mint.mint(); + + // Generate keypair for Alice + let (alice_secret, alice_pubkey) = create_test_keypair(); + + // Create hash and preimage + let (hash, preimage) = create_test_hash_and_preimage(); + + println!("Alice pubkey: {}", alice_pubkey); + println!("Hash: {}", hash); + println!("Preimage: {}", preimage); + + // Step 1: Mint regular proofs + let input_amount = Amount::from(10); + let input_proofs = test_mint.mint_proofs(input_amount).await.unwrap(); + + // Step 2: Create HTLC spending conditions with SIG_ALL flag (hash locked to Alice's key) + let spending_conditions = SpendingConditions::new_htlc_hash( + &hash, + Some(Conditions { + locktime: None, + pubkeys: Some(vec![alice_pubkey]), + refund_keys: None, + num_sigs: None, // Default (1) + sig_flag: SigFlag::SigAll, // <-- SIG_ALL flag + num_sigs_refund: None, + }), + ) + .unwrap(); + println!("Created HTLC spending conditions with SIG_ALL flag"); + + // Step 3: Create HTLC blinded messages (outputs) + let split_amounts = test_mint.split_amount(input_amount).unwrap(); + let split_display: Vec = split_amounts.iter().map(|a| a.to_string()).collect(); + println!("Split {} into [{}]", input_amount, split_display.join("+")); + + let (htlc_outputs, blinding_factors, secrets) = unzip3( + split_amounts + .iter() + .map(|&amt| test_mint.create_blinded_message(amt, &spending_conditions)) + .collect(), + ); + println!( + "Created {} HTLC outputs locked to alice with hash", + htlc_outputs.len() + ); + + // Step 4: Swap regular proofs for HTLC proofs (no signature needed on inputs) + let swap_request = + cdk_common::nuts::SwapRequest::new(input_proofs.clone(), htlc_outputs.clone()); + let swap_response = mint + .process_swap_request(swap_request) + .await + .expect("Failed to swap for HTLC proofs"); + println!("Swap successful! Got BlindSignatures for our HTLC outputs"); + + // Step 5: Construct the HTLC proofs + use cdk_common::dhke::construct_proofs; + let htlc_proofs = construct_proofs( + swap_response.signatures.clone(), + blinding_factors.clone(), + secrets.clone(), + &test_mint.public_keys_of_the_active_sat_keyset, + ) + .unwrap(); + + let proof_amounts: Vec = htlc_proofs.iter().map(|p| p.amount.to_string()).collect(); + println!( + "Constructed {} HTLC proof(s) [{}]", + htlc_proofs.len(), + proof_amounts.join("+") + ); + + // Step 6: Try to spend with only preimage (should fail - signature required) + use crate::test_helpers::mint::create_test_blinded_messages; + let (new_outputs, _) = create_test_blinded_messages(mint, input_amount) + .await + .unwrap(); + let mut swap_request_preimage_only = + cdk_common::nuts::SwapRequest::new(htlc_proofs.clone(), new_outputs.clone()); + + // Add only preimage to first proof (no signature) + swap_request_preimage_only.inputs_mut()[0].add_preimage(preimage.clone()); + + let result = mint.process_swap_request(swap_request_preimage_only).await; + assert!( + result.is_err(), + "Should fail with only preimage (no signature)" + ); + println!( + "✓ Spending with ONLY preimage failed as expected: {:?}", + result.err() + ); + + // Step 7: Try to spend with only signature (should fail - preimage required) + let mut swap_request_signature_only = + cdk_common::nuts::SwapRequest::new(htlc_proofs.clone(), new_outputs.clone()); + + // Add only SIG_ALL signature to first proof (no preimage) + // Note: Must create HTLCWitness first, otherwise sign_sig_all creates P2PKWitness + swap_request_signature_only.inputs_mut()[0].add_preimage(String::new()); // Empty preimage + swap_request_signature_only + .sign_sig_all(alice_secret.clone()) + .unwrap(); + + let result = mint.process_swap_request(swap_request_signature_only).await; + assert!( + result.is_err(), + "Should fail with only signature (no preimage)" + ); + println!( + "✓ Spending with ONLY signature failed as expected: {:?}", + result.err() + ); + + // Step 8: Now try to spend with both preimage and SIG_ALL signature + let mut swap_request_both = + cdk_common::nuts::SwapRequest::new(htlc_proofs.clone(), new_outputs.clone()); + + // Add preimage to first proof + swap_request_both.inputs_mut()[0].add_preimage(preimage.clone()); + // Add SIG_ALL signature + swap_request_both + .sign_sig_all(alice_secret.clone()) + .unwrap(); + + let result = mint.process_swap_request(swap_request_both).await; + assert!( + result.is_ok(), + "Should succeed with correct preimage and SIG_ALL signature: {:?}", + result.err() + ); + println!("✓ HTLC SIG_ALL spent successfully with correct preimage AND signature"); +} + +/// Test: HTLC SIG_ALL with wrong preimage +/// +/// Verifies that providing an incorrect preimage fails even with correct SIG_ALL signature +#[tokio::test] +async fn test_htlc_sig_all_wrong_preimage() { + let test_mint = TestMintHelper::new().await.unwrap(); + let mint = test_mint.mint(); + + let (alice_secret, alice_pubkey) = create_test_keypair(); + let (hash, _correct_preimage) = create_test_hash_and_preimage(); + + // Mint regular proofs and swap for HTLC SIG_ALL proofs + let input_amount = Amount::from(10); + let input_proofs = test_mint.mint_proofs(input_amount).await.unwrap(); + + let spending_conditions = SpendingConditions::new_htlc_hash( + &hash, + Some(Conditions { + locktime: None, + pubkeys: Some(vec![alice_pubkey]), + refund_keys: None, + num_sigs: None, + sig_flag: SigFlag::SigAll, + num_sigs_refund: None, + }), + ) + .unwrap(); + + let split_amounts = test_mint.split_amount(input_amount).unwrap(); + let (htlc_outputs, blinding_factors, secrets) = unzip3( + split_amounts + .iter() + .map(|&amt| test_mint.create_blinded_message(amt, &spending_conditions)) + .collect(), + ); + + let swap_request = + cdk_common::nuts::SwapRequest::new(input_proofs.clone(), htlc_outputs.clone()); + let swap_response = mint.process_swap_request(swap_request).await.unwrap(); + + use cdk_common::dhke::construct_proofs; + let htlc_proofs = construct_proofs( + swap_response.signatures.clone(), + blinding_factors.clone(), + secrets.clone(), + &test_mint.public_keys_of_the_active_sat_keyset, + ) + .unwrap(); + + // Try to spend with WRONG preimage (but correct SIG_ALL signature) + use crate::test_helpers::mint::create_test_blinded_messages; + let (new_outputs, _) = create_test_blinded_messages(mint, input_amount) + .await + .unwrap(); + let mut swap_request = + cdk_common::nuts::SwapRequest::new(htlc_proofs.clone(), new_outputs.clone()); + + let wrong_preimage = "this_is_the_wrong_preimage"; + swap_request.inputs_mut()[0].add_preimage(wrong_preimage.to_string()); + swap_request.sign_sig_all(alice_secret.clone()).unwrap(); + + let result = mint.process_swap_request(swap_request).await; + assert!(result.is_err(), "Should fail with wrong preimage"); + println!( + "✓ HTLC SIG_ALL with wrong preimage failed as expected: {:?}", + result.err() + ); +} + +/// Test: HTLC SIG_ALL locktime after expiry (refund path) +/// +/// Verifies that after locktime expires, refund keys can spend without preimage using SIG_ALL +#[tokio::test] +async fn test_htlc_sig_all_locktime_after_expiry() { + let test_mint = TestMintHelper::new().await.unwrap(); + let mint = test_mint.mint(); + + let (_alice_secret, alice_pubkey) = create_test_keypair(); + let (bob_secret, bob_pubkey) = create_test_keypair(); + let (hash, _preimage) = create_test_hash_and_preimage(); + + // Create HTLC with locktime in the PAST (already expired) and Bob as refund key + let past_locktime = cdk_common::util::unix_time() - 1000; + + let input_amount = Amount::from(10); + let input_proofs = test_mint.mint_proofs(input_amount).await.unwrap(); + + let spending_conditions = SpendingConditions::new_htlc_hash( + &hash, + Some(Conditions { + locktime: Some(past_locktime), + pubkeys: Some(vec![alice_pubkey]), + refund_keys: Some(vec![bob_pubkey]), + num_sigs: None, + sig_flag: SigFlag::SigAll, + num_sigs_refund: None, + }), + ) + .unwrap(); + + let split_amounts = test_mint.split_amount(input_amount).unwrap(); + let (htlc_outputs, blinding_factors, secrets) = unzip3( + split_amounts + .iter() + .map(|&amt| test_mint.create_blinded_message(amt, &spending_conditions)) + .collect(), + ); + + let swap_request = + cdk_common::nuts::SwapRequest::new(input_proofs.clone(), htlc_outputs.clone()); + let swap_response = mint.process_swap_request(swap_request).await.unwrap(); + + use cdk_common::dhke::construct_proofs; + let htlc_proofs = construct_proofs( + swap_response.signatures.clone(), + blinding_factors.clone(), + secrets.clone(), + &test_mint.public_keys_of_the_active_sat_keyset, + ) + .unwrap(); + + // After locktime, Bob (refund key) can spend WITHOUT preimage using SIG_ALL + use crate::test_helpers::mint::create_test_blinded_messages; + let (new_outputs, _) = create_test_blinded_messages(mint, input_amount) + .await + .unwrap(); + let mut swap_request = + cdk_common::nuts::SwapRequest::new(htlc_proofs.clone(), new_outputs.clone()); + + // Bob signs with SIG_ALL (no preimage needed after locktime) + // Note: Must call add_preimage first (even with empty string) to create HTLC witness + swap_request.inputs_mut()[0].add_preimage(String::new()); + swap_request.sign_sig_all(bob_secret.clone()).unwrap(); + + let result = mint.process_swap_request(swap_request).await; + assert!( + result.is_ok(), + "Bob should be able to spend after locktime without preimage: {:?}", + result.err() + ); + println!("✓ HTLC SIG_ALL spent by refund key after locktime (no preimage needed)"); +} + +/// Test: HTLC SIG_ALL with multisig (preimage + 2-of-3 signatures) +/// +/// Verifies that HTLC SIG_ALL can require preimage AND multiple signatures +#[tokio::test] +async fn test_htlc_sig_all_multisig_2of3() { + let test_mint = TestMintHelper::new().await.unwrap(); + let mint = test_mint.mint(); + + let (alice_secret, alice_pubkey) = create_test_keypair(); + let (bob_secret, bob_pubkey) = create_test_keypair(); + let (_charlie_secret, charlie_pubkey) = create_test_keypair(); + let (hash, preimage) = create_test_hash_and_preimage(); + + // Create HTLC requiring preimage + 2-of-3 signatures (Alice, Bob, Charlie) with SIG_ALL + let input_amount = Amount::from(10); + let input_proofs = test_mint.mint_proofs(input_amount).await.unwrap(); + + let spending_conditions = SpendingConditions::new_htlc_hash( + &hash, + Some(Conditions { + locktime: None, + pubkeys: Some(vec![alice_pubkey, bob_pubkey, charlie_pubkey]), + refund_keys: None, + num_sigs: Some(2), // Require 2 of 3 + sig_flag: SigFlag::SigAll, + num_sigs_refund: None, + }), + ) + .unwrap(); + + let split_amounts = test_mint.split_amount(input_amount).unwrap(); + let (htlc_outputs, blinding_factors, secrets) = unzip3( + split_amounts + .iter() + .map(|&amt| test_mint.create_blinded_message(amt, &spending_conditions)) + .collect(), + ); + + let swap_request = + cdk_common::nuts::SwapRequest::new(input_proofs.clone(), htlc_outputs.clone()); + let swap_response = mint.process_swap_request(swap_request).await.unwrap(); + + use cdk_common::dhke::construct_proofs; + let htlc_proofs = construct_proofs( + swap_response.signatures.clone(), + blinding_factors.clone(), + secrets.clone(), + &test_mint.public_keys_of_the_active_sat_keyset, + ) + .unwrap(); + + // Try with preimage + only 1 SIG_ALL signature (should fail - need 2) + use crate::test_helpers::mint::create_test_blinded_messages; + let (new_outputs, _) = create_test_blinded_messages(mint, input_amount) + .await + .unwrap(); + let mut swap_request_one_sig = + cdk_common::nuts::SwapRequest::new(htlc_proofs.clone(), new_outputs.clone()); + + swap_request_one_sig.inputs_mut()[0].add_preimage(preimage.clone()); + swap_request_one_sig + .sign_sig_all(alice_secret.clone()) + .unwrap(); // Only Alice signs + + let result = mint.process_swap_request(swap_request_one_sig).await; + assert!( + result.is_err(), + "Should fail with only 1 signature (need 2)" + ); + println!("✓ HTLC SIG_ALL with 1-of-3 signatures failed as expected"); + + // Now with preimage + 2 SIG_ALL signatures (Alice and Bob) - should succeed + let mut swap_request_two_sigs = + cdk_common::nuts::SwapRequest::new(htlc_proofs.clone(), new_outputs.clone()); + + swap_request_two_sigs.inputs_mut()[0].add_preimage(preimage.clone()); + swap_request_two_sigs + .sign_sig_all(alice_secret.clone()) + .unwrap(); + swap_request_two_sigs + .sign_sig_all(bob_secret.clone()) + .unwrap(); + + let result = mint.process_swap_request(swap_request_two_sigs).await; + assert!( + result.is_ok(), + "Should succeed with preimage + 2-of-3 SIG_ALL signatures: {:?}", + result.err() + ); + println!("✓ HTLC SIG_ALL spent with preimage + 2-of-3 signatures"); +} diff --git a/crates/cdk/src/mint/swap/tests/htlc_spending_conditions_tests.rs b/crates/cdk/src/mint/swap/tests/htlc_spending_conditions_tests.rs new file mode 100644 index 000000000..996948ab1 --- /dev/null +++ b/crates/cdk/src/mint/swap/tests/htlc_spending_conditions_tests.rs @@ -0,0 +1,396 @@ +//! HTLC (NUT-14) tests for swap functionality +//! +//! These tests verify that the mint correctly validates HTLC spending conditions +//! during swap operations, including: +//! - Hash preimage verification +//! - Locktime enforcement +//! - Refund keys +//! - Signature validation + +use cdk_common::nuts::{Conditions, SigFlag, SpendingConditions}; +use cdk_common::Amount; + +use crate::test_helpers::nut10::{ + create_test_hash_and_preimage, create_test_keypair, unzip3, TestMintHelper, +}; + +/// Test: HTLC requiring preimage and one signature +/// +/// Creates HTLC-locked proofs and verifies: +/// 1. Spending with only preimage fails (signature required) +/// 2. Spending with only signature fails (preimage required) +/// 3. Spending with both preimage and signature succeeds +#[tokio::test] +async fn test_htlc_requiring_preimage_and_one_signature() { + let test_mint = TestMintHelper::new().await.unwrap(); + let mint = test_mint.mint(); + + // Generate keypair for Alice + let (alice_secret, alice_pubkey) = create_test_keypair(); + + // Create hash and preimage + let (hash, preimage) = create_test_hash_and_preimage(); + + println!("Alice pubkey: {}", alice_pubkey); + println!("Hash: {}", hash); + println!("Preimage: {}", preimage); + + // Step 1: Mint regular proofs + let input_amount = Amount::from(10); + let input_proofs = test_mint.mint_proofs(input_amount).await.unwrap(); + + // Step 2: Create HTLC spending conditions (hash locked to Alice's key) + let spending_conditions = SpendingConditions::new_htlc_hash( + &hash, + Some(Conditions { + locktime: None, + pubkeys: Some(vec![alice_pubkey]), + refund_keys: None, + num_sigs: None, // Default (1) + sig_flag: SigFlag::default(), + num_sigs_refund: None, + }), + ) + .unwrap(); + println!("Created HTLC spending conditions"); + + // Step 3: Create HTLC blinded messages (outputs) + let split_amounts = test_mint.split_amount(input_amount).unwrap(); + let split_display: Vec = split_amounts.iter().map(|a| a.to_string()).collect(); + println!("Split {} into [{}]", input_amount, split_display.join("+")); + + let (htlc_outputs, blinding_factors, secrets) = unzip3( + split_amounts + .iter() + .map(|&amt| test_mint.create_blinded_message(amt, &spending_conditions)) + .collect(), + ); + println!( + "Created {} HTLC outputs locked to alice with hash", + htlc_outputs.len() + ); + + // Step 4: Swap regular proofs for HTLC proofs (no signature needed on inputs) + let swap_request = + cdk_common::nuts::SwapRequest::new(input_proofs.clone(), htlc_outputs.clone()); + let swap_response = mint + .process_swap_request(swap_request) + .await + .expect("Failed to swap for HTLC proofs"); + println!("Swap successful! Got BlindSignatures for our HTLC outputs"); + + // Step 5: Construct the HTLC proofs + use cdk_common::dhke::construct_proofs; + let htlc_proofs = construct_proofs( + swap_response.signatures.clone(), + blinding_factors.clone(), + secrets.clone(), + &test_mint.public_keys_of_the_active_sat_keyset, + ) + .unwrap(); + + let proof_amounts: Vec = htlc_proofs.iter().map(|p| p.amount.to_string()).collect(); + println!( + "Constructed {} HTLC proof(s) [{}]", + htlc_proofs.len(), + proof_amounts.join("+") + ); + + // Step 6: Try to spend with only preimage (should fail - signature required) + use crate::test_helpers::mint::create_test_blinded_messages; + let (new_outputs, _) = create_test_blinded_messages(mint, input_amount) + .await + .unwrap(); + let mut swap_request_preimage_only = + cdk_common::nuts::SwapRequest::new(htlc_proofs.clone(), new_outputs.clone()); + + // Add only preimage (no signature) + for proof in swap_request_preimage_only.inputs_mut() { + proof.add_preimage(preimage.clone()); + } + + let result = mint.process_swap_request(swap_request_preimage_only).await; + assert!( + result.is_err(), + "Should fail with only preimage (no signature)" + ); + println!( + "✓ Spending with ONLY preimage failed as expected: {:?}", + result.err() + ); + + // Step 7: Try to spend with only signature (should fail - preimage required) + let mut swap_request_signature_only = + cdk_common::nuts::SwapRequest::new(htlc_proofs.clone(), new_outputs.clone()); + + // Add only signature (no preimage) + for proof in swap_request_signature_only.inputs_mut() { + proof.sign_p2pk(alice_secret.clone()).unwrap(); + } + + let result = mint.process_swap_request(swap_request_signature_only).await; + assert!( + result.is_err(), + "Should fail with only signature (no preimage)" + ); + println!( + "✓ Spending with ONLY signature failed as expected: {:?}", + result.err() + ); + + // Step 8: Now try to spend the HTLC proofs with correct preimage + signature + let mut swap_request_both = + cdk_common::nuts::SwapRequest::new(htlc_proofs.clone(), new_outputs.clone()); + + // Add preimage and sign all proofs + for proof in swap_request_both.inputs_mut() { + proof.add_preimage(preimage.clone()); + proof.sign_p2pk(alice_secret.clone()).unwrap(); + } + + let result = mint.process_swap_request(swap_request_both).await; + assert!( + result.is_ok(), + "Should succeed with correct preimage and signature: {:?}", + result.err() + ); + println!("✓ HTLC spent successfully with correct preimage AND signature"); +} + +/// Test: HTLC with wrong preimage +/// +/// Verifies that providing an incorrect preimage fails even with correct signature +#[tokio::test] +async fn test_htlc_wrong_preimage() { + let test_mint = TestMintHelper::new().await.unwrap(); + let mint = test_mint.mint(); + + let (alice_secret, alice_pubkey) = create_test_keypair(); + let (hash, _correct_preimage) = create_test_hash_and_preimage(); + + // Mint regular proofs and swap for HTLC proofs + let input_amount = Amount::from(10); + let input_proofs = test_mint.mint_proofs(input_amount).await.unwrap(); + + let spending_conditions = SpendingConditions::new_htlc_hash( + &hash, + Some(Conditions { + locktime: None, + pubkeys: Some(vec![alice_pubkey]), + refund_keys: None, + num_sigs: None, + sig_flag: SigFlag::default(), + num_sigs_refund: None, + }), + ) + .unwrap(); + + let split_amounts = test_mint.split_amount(input_amount).unwrap(); + let (htlc_outputs, blinding_factors, secrets) = unzip3( + split_amounts + .iter() + .map(|&amt| test_mint.create_blinded_message(amt, &spending_conditions)) + .collect(), + ); + + let swap_request = + cdk_common::nuts::SwapRequest::new(input_proofs.clone(), htlc_outputs.clone()); + let swap_response = mint.process_swap_request(swap_request).await.unwrap(); + + use cdk_common::dhke::construct_proofs; + let htlc_proofs = construct_proofs( + swap_response.signatures.clone(), + blinding_factors.clone(), + secrets.clone(), + &test_mint.public_keys_of_the_active_sat_keyset, + ) + .unwrap(); + + // Try to spend with WRONG preimage (but correct signature) + use crate::test_helpers::mint::create_test_blinded_messages; + let (new_outputs, _) = create_test_blinded_messages(mint, input_amount) + .await + .unwrap(); + let mut swap_request = + cdk_common::nuts::SwapRequest::new(htlc_proofs.clone(), new_outputs.clone()); + + let wrong_preimage = "this_is_the_wrong_preimage"; + for proof in swap_request.inputs_mut() { + proof.add_preimage(wrong_preimage.to_string()); + proof.sign_p2pk(alice_secret.clone()).unwrap(); + } + + let result = mint.process_swap_request(swap_request).await; + assert!(result.is_err(), "Should fail with wrong preimage"); + println!( + "✓ HTLC with wrong preimage failed as expected: {:?}", + result.err() + ); +} + +/// Test: HTLC locktime after expiry (refund path) +/// +/// Verifies that after locktime expires, refund keys can spend without preimage +#[tokio::test] +async fn test_htlc_locktime_after_expiry() { + let test_mint = TestMintHelper::new().await.unwrap(); + let mint = test_mint.mint(); + + let (_alice_secret, alice_pubkey) = create_test_keypair(); + let (bob_secret, bob_pubkey) = create_test_keypair(); + let (hash, _preimage) = create_test_hash_and_preimage(); + + // Create HTLC with locktime in the PAST (already expired) and Bob as refund key + let past_locktime = cdk_common::util::unix_time() - 1000; + + let input_amount = Amount::from(10); + let input_proofs = test_mint.mint_proofs(input_amount).await.unwrap(); + + let spending_conditions = SpendingConditions::new_htlc_hash( + &hash, + Some(Conditions { + locktime: Some(past_locktime), + pubkeys: Some(vec![alice_pubkey]), + refund_keys: Some(vec![bob_pubkey]), + num_sigs: None, + sig_flag: SigFlag::default(), + num_sigs_refund: None, + }), + ) + .unwrap(); + + let split_amounts = test_mint.split_amount(input_amount).unwrap(); + let (htlc_outputs, blinding_factors, secrets) = unzip3( + split_amounts + .iter() + .map(|&amt| test_mint.create_blinded_message(amt, &spending_conditions)) + .collect(), + ); + + let swap_request = + cdk_common::nuts::SwapRequest::new(input_proofs.clone(), htlc_outputs.clone()); + let swap_response = mint.process_swap_request(swap_request).await.unwrap(); + + use cdk_common::dhke::construct_proofs; + let htlc_proofs = construct_proofs( + swap_response.signatures.clone(), + blinding_factors.clone(), + secrets.clone(), + &test_mint.public_keys_of_the_active_sat_keyset, + ) + .unwrap(); + + // After locktime, Bob (refund key) can spend WITHOUT preimage + use crate::test_helpers::mint::create_test_blinded_messages; + let (new_outputs, _) = create_test_blinded_messages(mint, input_amount) + .await + .unwrap(); + let mut swap_request = + cdk_common::nuts::SwapRequest::new(htlc_proofs.clone(), new_outputs.clone()); + + // Bob signs (no preimage needed after locktime) + // Note: Must call add_preimage first (even with empty string) to create HTLC witness, + // otherwise sign_p2pk creates P2PK witness instead + for proof in swap_request.inputs_mut() { + proof.add_preimage(String::new()); // Empty preimage for refund path + proof.sign_p2pk(bob_secret.clone()).unwrap(); + } + + let result = mint.process_swap_request(swap_request).await; + assert!( + result.is_ok(), + "Bob should be able to spend after locktime without preimage: {:?}", + result.err() + ); + println!("✓ HTLC spent by refund key after locktime (no preimage needed)"); +} + +/// Test: HTLC with multisig (preimage + 2-of-3 signatures) +/// +/// Verifies that HTLC can require preimage AND multiple signatures +#[tokio::test] +async fn test_htlc_multisig_2of3() { + let test_mint = TestMintHelper::new().await.unwrap(); + let mint = test_mint.mint(); + + let (alice_secret, alice_pubkey) = create_test_keypair(); + let (bob_secret, bob_pubkey) = create_test_keypair(); + let (_charlie_secret, charlie_pubkey) = create_test_keypair(); + let (hash, preimage) = create_test_hash_and_preimage(); + + // Create HTLC requiring preimage + 2-of-3 signatures (Alice, Bob, Charlie) + let input_amount = Amount::from(10); + let input_proofs = test_mint.mint_proofs(input_amount).await.unwrap(); + + let spending_conditions = SpendingConditions::new_htlc_hash( + &hash, + Some(Conditions { + locktime: None, + pubkeys: Some(vec![alice_pubkey, bob_pubkey, charlie_pubkey]), + refund_keys: None, + num_sigs: Some(2), // Require 2 of 3 + sig_flag: SigFlag::default(), + num_sigs_refund: None, + }), + ) + .unwrap(); + + let split_amounts = test_mint.split_amount(input_amount).unwrap(); + let (htlc_outputs, blinding_factors, secrets) = unzip3( + split_amounts + .iter() + .map(|&amt| test_mint.create_blinded_message(amt, &spending_conditions)) + .collect(), + ); + + let swap_request = + cdk_common::nuts::SwapRequest::new(input_proofs.clone(), htlc_outputs.clone()); + let swap_response = mint.process_swap_request(swap_request).await.unwrap(); + + use cdk_common::dhke::construct_proofs; + let htlc_proofs = construct_proofs( + swap_response.signatures.clone(), + blinding_factors.clone(), + secrets.clone(), + &test_mint.public_keys_of_the_active_sat_keyset, + ) + .unwrap(); + + // Try with preimage + only 1 signature (should fail - need 2) + use crate::test_helpers::mint::create_test_blinded_messages; + let (new_outputs, _) = create_test_blinded_messages(mint, input_amount) + .await + .unwrap(); + let mut swap_request_one_sig = + cdk_common::nuts::SwapRequest::new(htlc_proofs.clone(), new_outputs.clone()); + + for proof in swap_request_one_sig.inputs_mut() { + proof.add_preimage(preimage.clone()); + proof.sign_p2pk(alice_secret.clone()).unwrap(); // Only Alice signs + } + + let result = mint.process_swap_request(swap_request_one_sig).await; + assert!( + result.is_err(), + "Should fail with only 1 signature (need 2)" + ); + println!("✓ HTLC with 1-of-3 signatures failed as expected"); + + // Now with preimage + 2 signatures (Alice and Bob) - should succeed + let mut swap_request_two_sigs = + cdk_common::nuts::SwapRequest::new(htlc_proofs.clone(), new_outputs.clone()); + + for proof in swap_request_two_sigs.inputs_mut() { + proof.add_preimage(preimage.clone()); + proof.sign_p2pk(alice_secret.clone()).unwrap(); + proof.sign_p2pk(bob_secret.clone()).unwrap(); + } + + let result = mint.process_swap_request(swap_request_two_sigs).await; + assert!( + result.is_ok(), + "Should succeed with preimage + 2-of-3 signatures: {:?}", + result.err() + ); + println!("✓ HTLC spent with preimage + 2-of-3 signatures"); +} diff --git a/crates/cdk/src/mint/swap/tests/mod.rs b/crates/cdk/src/mint/swap/tests/mod.rs new file mode 100644 index 000000000..fa7e3558a --- /dev/null +++ b/crates/cdk/src/mint/swap/tests/mod.rs @@ -0,0 +1,4 @@ +mod htlc_sigall_spending_conditions_tests; +mod htlc_spending_conditions_tests; +mod p2pk_sigall_spending_conditions_tests; +mod p2pk_spending_conditions_tests; diff --git a/crates/cdk/src/mint/swap/tests/p2pk_sigall_spending_conditions_tests.rs b/crates/cdk/src/mint/swap/tests/p2pk_sigall_spending_conditions_tests.rs new file mode 100644 index 000000000..7a385af3d --- /dev/null +++ b/crates/cdk/src/mint/swap/tests/p2pk_sigall_spending_conditions_tests.rs @@ -0,0 +1,1441 @@ +//! P2PK SIG_ALL tests for swap functionality +//! +//! These tests verify that the mint correctly enforces SIG_ALL flag behavior + +use crate::util::unix_time; +use cdk_common::dhke::construct_proofs; +use cdk_common::nuts::{Conditions, SigFlag, SpendingConditions}; +use cdk_common::Amount; + +use crate::test_helpers::mint::create_test_blinded_messages; +use crate::test_helpers::nut10::{create_test_keypair, unzip3, TestMintHelper}; + +/// Test: P2PK with SIG_ALL flag requires transaction signature +/// +/// Creates P2PK proofs with SIG_ALL flag and verifies: +/// 1. Spending without signature is rejected +/// 2. Spending with SIG_INPUTS signatures (individual proof signatures) is rejected +/// 3. Spending with SIG_ALL signature (transaction signature) succeeds +#[tokio::test] +async fn test_p2pk_sig_all_requires_transaction_signature() { + let test_mint = TestMintHelper::new().await.unwrap(); + let mint = test_mint.mint(); + + // Generate keypair for P2PK + let (alice_secret, alice_pubkey) = create_test_keypair(); + println!("Alice pubkey: {}", alice_pubkey); + + // Step 1: Create regular unencumbered proofs that we'll swap for P2PK proofs + let input_amount = Amount::from(10); + let input_proofs = test_mint.mint_proofs(input_amount).await.unwrap(); + + // Step 2: Create P2PK blinded messages (outputs locked to alice_pubkey) with SIG_ALL + let spending_conditions = SpendingConditions::new_p2pk( + alice_pubkey, + Some( + Conditions::new( + None, // no locktime + None, // no additional pubkeys + None, // no refund keys + None, // default num_sigs (1) + Some(SigFlag::SigAll), // SIG_ALL flag + None, // no num_sigs_refund + ) + .unwrap(), + ), + ); + println!("Created P2PK spending conditions with SIG_ALL flag"); + + // Split the input amount into power-of-2 denominations + let split_amounts = test_mint.split_amount(input_amount).unwrap(); + let split_display: Vec = split_amounts.iter().map(|a| a.to_string()).collect(); + println!("Split {} into [{}]", input_amount, split_display.join("+")); + + // Create blinded messages for each split amount + let (p2pk_outputs, blinding_factors, secrets) = unzip3( + split_amounts + .iter() + .map(|&amt| test_mint.create_blinded_message(amt, &spending_conditions)) + .collect(), + ); + + println!( + "Created {} P2PK outputs locked to alice", + p2pk_outputs.len() + ); + + // Step 3: Swap regular proofs for P2PK proofs (no signature needed on inputs) + let swap_request = + cdk_common::nuts::SwapRequest::new(input_proofs.clone(), p2pk_outputs.clone()); + let swap_response = mint + .process_swap_request(swap_request) + .await + .expect("Failed to swap for P2PK proofs"); + println!("Swap successful! Got BlindSignatures for our P2PK outputs"); + + // Step 4: Construct the P2PK proofs + let p2pk_proofs = construct_proofs( + swap_response.signatures.clone(), + blinding_factors.clone(), + secrets.clone(), + &test_mint.public_keys_of_the_active_sat_keyset, + ) + .unwrap(); + + let proof_amounts: Vec = p2pk_proofs.iter().map(|p| p.amount.to_string()).collect(); + println!( + "Constructed {} P2PK proof(s) [{}]", + p2pk_proofs.len(), + proof_amounts.join("+") + ); + + // Step 5: Try to spend P2PK proof WITHOUT signature (should fail) + let (new_outputs, _) = create_test_blinded_messages(mint, input_amount) + .await + .unwrap(); + let swap_request_no_sig = + cdk_common::nuts::SwapRequest::new(p2pk_proofs.clone(), new_outputs.clone()); + + let result = mint.process_swap_request(swap_request_no_sig).await; + assert!(result.is_err(), "Should fail without signature"); + println!( + "✓ Spending WITHOUT signature failed as expected: {:?}", + result.err() + ); + + // Step 6: Sign all proofs individually (SIG_INPUTS way) - should fail for SIG_ALL + let mut swap_request_sig_inputs = + cdk_common::nuts::SwapRequest::new(p2pk_proofs.clone(), new_outputs.clone()); + + // Sign each proof individually (SIG_INPUTS mode) + for proof in swap_request_sig_inputs.inputs_mut() { + proof.sign_p2pk(alice_secret.clone()).unwrap(); + } + + let result = mint.process_swap_request(swap_request_sig_inputs).await; + assert!( + result.is_err(), + "Should fail - SIG_INPUTS signatures not valid for SIG_ALL" + ); + println!( + "✓ Spending with SIG_INPUTS signatures failed as expected: {:?}", + result.err() + ); + + // Step 7: Sign the transaction with SIG_ALL (should succeed) + let mut swap_request_with_sig = + cdk_common::nuts::SwapRequest::new(p2pk_proofs.clone(), new_outputs.clone()); + + // Use sign_sig_all to sign the transaction (signature goes on first proof's witness) + swap_request_with_sig + .sign_sig_all(alice_secret.clone()) + .unwrap(); + + let result = mint.process_swap_request(swap_request_with_sig).await; + assert!( + result.is_ok(), + "Should succeed with valid signature: {:?}", + result.err() + ); + println!("✓ Spending WITH ALL signatures (SIG_ALL) succeeded"); +} + +/// Test: P2PK multisig (2-of-3) with SIG_ALL +/// +/// Creates proofs requiring 2 signatures from a set of 3 public keys with SIG_ALL flag and verifies: +/// 1. Spending with only 1 signature fails (Alice only) +/// 2. Spending with 2 invalid signatures fails (wrong keys) +/// 3. Spending with 2 valid signatures succeeds (Alice + Bob) +#[tokio::test] +async fn test_p2pk_sig_all_multisig_2of3() { + let test_mint = TestMintHelper::new().await.unwrap(); + let mint = test_mint.mint(); + + // Generate 3 keypairs for the multisig + let (alice_secret, alice_pubkey) = create_test_keypair(); + let (bob_secret, bob_pubkey) = create_test_keypair(); + let (_carol_secret, carol_pubkey) = create_test_keypair(); + + // Generate 2 wrong keypairs (not in the multisig set) + let (dave_secret, _dave_pubkey) = create_test_keypair(); + let (eve_secret, _eve_pubkey) = create_test_keypair(); + + println!("Alice: {}", alice_pubkey); + println!("Bob: {}", bob_pubkey); + println!("Carol: {}", carol_pubkey); + + // Step 1: Mint regular proofs + let input_amount = Amount::from(10); + let input_proofs = test_mint.mint_proofs(input_amount).await.unwrap(); + + // Step 2: Create 2-of-3 multisig conditions with SIG_ALL + // Primary key: Alice + // Additional keys: Bob, Carol + // Requires 2 signatures total + let spending_conditions = SpendingConditions::new_p2pk( + alice_pubkey, + Some( + Conditions::new( + None, // no locktime + Some(vec![bob_pubkey, carol_pubkey]), // additional pubkeys + None, // no refund keys + Some(2), // require 2 signatures + Some(SigFlag::SigAll), // SIG_ALL flag + None, // no num_sigs_refund + ) + .unwrap(), + ), + ); + println!("Created 2-of-3 multisig spending conditions with SIG_ALL (Alice, Bob, Carol)"); + + // Step 3: Create P2PK blinded messages with multisig conditions + let split_amounts = test_mint.split_amount(input_amount).unwrap(); + let (p2pk_outputs, blinding_factors, secrets) = unzip3( + split_amounts + .iter() + .map(|&amt| test_mint.create_blinded_message(amt, &spending_conditions)) + .collect(), + ); + + // Step 4: Swap for P2PK multisig proofs + let swap_request = + cdk_common::nuts::SwapRequest::new(input_proofs.clone(), p2pk_outputs.clone()); + let swap_response = mint.process_swap_request(swap_request).await.unwrap(); + println!("Created P2PK multisig proofs (2-of-3) with SIG_ALL"); + + // Step 5: Construct the P2PK proofs + let p2pk_proofs = construct_proofs( + swap_response.signatures.clone(), + blinding_factors.clone(), + secrets.clone(), + &test_mint.public_keys_of_the_active_sat_keyset, + ) + .unwrap(); + + // Step 6: Try to spend with only 1 signature (Alice only - should fail) + let (new_outputs, _) = create_test_blinded_messages(mint, input_amount) + .await + .unwrap(); + let mut swap_request_one_sig = + cdk_common::nuts::SwapRequest::new(p2pk_proofs.clone(), new_outputs.clone()); + + // Sign with only Alice (SIG_ALL mode) + swap_request_one_sig + .sign_sig_all(alice_secret.clone()) + .unwrap(); + + let result = mint.process_swap_request(swap_request_one_sig).await; + assert!( + result.is_err(), + "Should fail with only 1 signature (need 2)" + ); + println!( + "✓ Spending with only 1 signature (Alice) failed as expected: {:?}", + result.err() + ); + + // Step 7: Try to spend with 2 invalid signatures (Dave + Eve - not in multisig set) + let mut swap_request_invalid_sigs = + cdk_common::nuts::SwapRequest::new(p2pk_proofs.clone(), new_outputs.clone()); + + // Sign with Dave and Eve (wrong keys!) - add signatures one at a time + swap_request_invalid_sigs + .sign_sig_all(dave_secret.clone()) + .unwrap(); + swap_request_invalid_sigs + .sign_sig_all(eve_secret.clone()) + .unwrap(); + + let result = mint.process_swap_request(swap_request_invalid_sigs).await; + assert!(result.is_err(), "Should fail with 2 invalid signatures"); + println!( + "✓ Spending with 2 INVALID signatures (Dave + Eve) failed as expected: {:?}", + result.err() + ); + + // Step 8: Spend with 2 valid signatures (Alice + Bob - should succeed) + let mut swap_request_valid_sigs = + cdk_common::nuts::SwapRequest::new(p2pk_proofs.clone(), new_outputs.clone()); + + // Sign with Alice and Bob - add signatures one at a time + swap_request_valid_sigs + .sign_sig_all(alice_secret.clone()) + .unwrap(); + swap_request_valid_sigs + .sign_sig_all(bob_secret.clone()) + .unwrap(); + + // print the json serializiation of this final swap. It should succeed + // as it has sufficient signatures + println!( + "{}", + serde_json::to_string_pretty(&swap_request_valid_sigs.clone()).unwrap() + ); + + let result = mint.process_swap_request(swap_request_valid_sigs).await; + assert!( + result.is_ok(), + "Should succeed with 2 valid signatures: {:?}", + result.err() + ); + println!("✓ Spending with 2 VALID signatures (Alice + Bob) succeeded"); +} + +/// Test: P2PK with SIG_ALL signed by wrong person is rejected +/// +/// Creates proofs locked to Alice's public key with SIG_ALL flag and verifies that +/// signing with Bob's key (wrong key) is rejected +#[tokio::test] +async fn test_p2pk_sig_all_signed_by_wrong_person() { + let test_mint = TestMintHelper::new().await.unwrap(); + let mint = test_mint.mint(); + + // Generate keypairs for Alice and Bob + let (_alice_secret, alice_pubkey) = create_test_keypair(); + let (bob_secret, _bob_pubkey) = create_test_keypair(); + println!("Alice pubkey: {}", alice_pubkey); + println!("Bob will try to spend Alice's proofs"); + + // Step 1: Mint regular proofs + let input_amount = Amount::from(10); + let input_proofs = test_mint.mint_proofs(input_amount).await.unwrap(); + + // Step 2: Create P2PK blinded messages locked to Alice's pubkey with SIG_ALL + let spending_conditions = SpendingConditions::new_p2pk( + alice_pubkey, + Some( + Conditions::new( + None, // no locktime + None, // no additional pubkeys + None, // no refund keys + None, // default num_sigs (1) + Some(SigFlag::SigAll), // SIG_ALL flag + None, // no num_sigs_refund + ) + .unwrap(), + ), + ); + let split_amounts = test_mint.split_amount(input_amount).unwrap(); + let (p2pk_outputs, blinding_factors, secrets) = unzip3( + split_amounts + .iter() + .map(|&amt| test_mint.create_blinded_message(amt, &spending_conditions)) + .collect(), + ); + + // Step 3: Swap for P2PK proofs locked to Alice + let swap_request = + cdk_common::nuts::SwapRequest::new(input_proofs.clone(), p2pk_outputs.clone()); + let swap_response = mint.process_swap_request(swap_request).await.unwrap(); + println!("Created P2PK proofs locked to Alice with SIG_ALL"); + + // Step 4: Construct the P2PK proofs + let p2pk_proofs = construct_proofs( + swap_response.signatures.clone(), + blinding_factors.clone(), + secrets.clone(), + &test_mint.public_keys_of_the_active_sat_keyset, + ) + .unwrap(); + + // Step 5: Try to spend Alice's proofs by signing with Bob's key (wrong key!) + let (new_outputs, _) = create_test_blinded_messages(mint, input_amount) + .await + .unwrap(); + let mut swap_request_wrong_sig = + cdk_common::nuts::SwapRequest::new(p2pk_proofs.clone(), new_outputs.clone()); + + // Sign with Bob's key instead of Alice's key (SIG_ALL mode) + swap_request_wrong_sig + .sign_sig_all(bob_secret.clone()) + .unwrap(); + + let result = mint.process_swap_request(swap_request_wrong_sig).await; + assert!(result.is_err(), "Should fail when signed with wrong key"); + println!( + "✓ Spending signed by wrong person failed as expected: {:?}", + result.err() + ); +} + +/// Test: Duplicate signatures are rejected (SIG_ALL) +/// +/// Verifies that using the same signature twice doesn't count as multiple signers +/// in a 2-of-2 multisig scenario with SIG_ALL flag +#[tokio::test] +async fn test_p2pk_sig_all_duplicate_signatures() { + let test_mint = TestMintHelper::new().await.unwrap(); + let mint = test_mint.mint(); + + let (alice_secret, alice_pubkey) = create_test_keypair(); + let (_bob_secret, bob_pubkey) = create_test_keypair(); + + println!("Alice: {}", alice_pubkey); + println!("Bob: {}", bob_pubkey); + + // Step 1: Mint regular proofs + let input_amount = Amount::from(10); + let input_proofs = test_mint.mint_proofs(input_amount).await.unwrap(); + + // Step 2: Create 2-of-2 multisig (Alice and Bob, need both) with SIG_ALL + let spending_conditions = SpendingConditions::new_p2pk( + alice_pubkey, + Some( + Conditions::new( + None, // no locktime + Some(vec![bob_pubkey]), // Bob is additional pubkey + None, // no refund keys + Some(2), // require 2 signatures (Alice + Bob) + Some(SigFlag::SigAll), // SIG_ALL flag + None, // no num_sigs_refund + ) + .unwrap(), + ), + ); + println!("Created 2-of-2 multisig (Alice, Bob) with SIG_ALL"); + + // Step 3: Create P2PK blinded messages + let split_amounts = test_mint.split_amount(input_amount).unwrap(); + let (p2pk_outputs, blinding_factors, secrets) = unzip3( + split_amounts + .iter() + .map(|&amt| test_mint.create_blinded_message(amt, &spending_conditions)) + .collect(), + ); + + // Step 4: Swap for P2PK proofs + let swap_request = + cdk_common::nuts::SwapRequest::new(input_proofs.clone(), p2pk_outputs.clone()); + let swap_response = mint.process_swap_request(swap_request).await.unwrap(); + + // Step 5: Construct the P2PK proofs + let p2pk_proofs = construct_proofs( + swap_response.signatures.clone(), + blinding_factors.clone(), + secrets.clone(), + &test_mint.public_keys_of_the_active_sat_keyset, + ) + .unwrap(); + + // Step 6: Try to spend with Alice's signature TWICE (should fail - need Alice + Bob, not Alice + Alice) + let (new_outputs, _) = create_test_blinded_messages(mint, input_amount) + .await + .unwrap(); + let mut swap_request_duplicate = + cdk_common::nuts::SwapRequest::new(p2pk_proofs.clone(), new_outputs.clone()); + + // Sign with Alice twice instead of Alice + Bob (SIG_ALL mode) + swap_request_duplicate + .sign_sig_all(alice_secret.clone()) + .unwrap(); + swap_request_duplicate + .sign_sig_all(alice_secret.clone()) + .unwrap(); // Duplicate! + + let result = mint.process_swap_request(swap_request_duplicate).await; + assert!( + result.is_err(), + "Should fail - duplicate signatures not allowed" + ); + println!( + "✓ Spending with duplicate signatures (Alice + Alice) failed as expected: {:?}", + result.err() + ); +} + +/// Test: P2PK with locktime (before expiry) - SIG_ALL +/// +/// Verifies that before locktime expires with SIG_ALL: +/// 1. Spending with primary key (Alice) succeeds +/// 2. Spending with refund key (Bob) fails +#[tokio::test] +async fn test_p2pk_sig_all_locktime_before_expiry() { + let test_mint = TestMintHelper::new().await.unwrap(); + let mint = test_mint.mint(); + + let (alice_secret, alice_pubkey) = create_test_keypair(); + let (bob_secret, bob_pubkey) = create_test_keypair(); + + // Set locktime 1 hour in the future + let locktime = unix_time() + 3600; + + println!("Alice (primary): {}", alice_pubkey); + println!("Bob (refund): {}", bob_pubkey); + println!("Current time: {}", unix_time()); + println!("Locktime: {} (expires in 1 hour)", locktime); + + // Step 1: Mint regular proofs + let input_amount = Amount::from(10); + let input_proofs = test_mint.mint_proofs(input_amount).await.unwrap(); + + // Step 2: Create conditions with Alice as primary and Bob as refund key with SIG_ALL + let spending_conditions = SpendingConditions::new_p2pk( + alice_pubkey, + Some( + Conditions::new( + Some(locktime), // locktime in the future + None, // no additional pubkeys + Some(vec![bob_pubkey]), // Bob is refund key + None, // default num_sigs (1) + Some(SigFlag::SigAll), // SIG_ALL flag + None, // default num_sigs_refund (1) + ) + .unwrap(), + ), + ); + println!("Created P2PK with locktime and refund key with SIG_ALL"); + + // Step 3: Create P2PK blinded messages + let split_amounts = test_mint.split_amount(input_amount).unwrap(); + let (p2pk_outputs, blinding_factors, secrets) = unzip3( + split_amounts + .iter() + .map(|&amt| test_mint.create_blinded_message(amt, &spending_conditions)) + .collect(), + ); + + // Step 4: Swap for P2PK proofs + let swap_request = + cdk_common::nuts::SwapRequest::new(input_proofs.clone(), p2pk_outputs.clone()); + let swap_response = mint.process_swap_request(swap_request).await.unwrap(); + + // Step 5: Construct the P2PK proofs + let p2pk_proofs = construct_proofs( + swap_response.signatures.clone(), + blinding_factors.clone(), + secrets.clone(), + &test_mint.public_keys_of_the_active_sat_keyset, + ) + .unwrap(); + + // Step 6: Try to spend with refund key (Bob) BEFORE locktime expires (should fail) + let (new_outputs, _) = create_test_blinded_messages(mint, input_amount) + .await + .unwrap(); + let mut swap_request_refund = + cdk_common::nuts::SwapRequest::new(p2pk_proofs.clone(), new_outputs.clone()); + + // Sign with Bob (refund key) using SIG_ALL + swap_request_refund + .sign_sig_all(bob_secret.clone()) + .unwrap(); + + let result = mint.process_swap_request(swap_request_refund).await; + assert!( + result.is_err(), + "Should fail - refund key cannot spend before locktime" + ); + println!( + "✓ Spending with refund key (Bob) BEFORE locktime failed as expected: {:?}", + result.err() + ); + + // Step 7: Spend with primary key (Alice) BEFORE locktime (should succeed) + let mut swap_request_primary = + cdk_common::nuts::SwapRequest::new(p2pk_proofs.clone(), new_outputs.clone()); + + // Sign with Alice (primary key) using SIG_ALL + swap_request_primary + .sign_sig_all(alice_secret.clone()) + .unwrap(); + + let result = mint.process_swap_request(swap_request_primary).await; + assert!( + result.is_ok(), + "Should succeed - primary key can spend before locktime: {:?}", + result.err() + ); + println!("✓ Spending with primary key (Alice) BEFORE locktime succeeded"); +} + +/// Test: P2PK with locktime (after expiry) - SIG_ALL +/// +/// Verifies that after locktime expires with SIG_ALL: +/// 1. Spending with primary key (Alice) fails +/// 2. Spending with refund key (Bob) succeeds +#[tokio::test] +async fn test_p2pk_sig_all_locktime_after_expiry() { + let test_mint = TestMintHelper::new().await.unwrap(); + let mint = test_mint.mint(); + + let (alice_secret, alice_pubkey) = create_test_keypair(); + let (bob_secret, bob_pubkey) = create_test_keypair(); + + // Set locktime in the past (already expired) + let locktime = unix_time() - 3600; + + println!("Alice (primary): {}", alice_pubkey); + println!("Bob (refund): {}", bob_pubkey); + println!("Current time: {}", unix_time()); + println!("Locktime: {} (expired 1 hour ago)", locktime); + + // Step 1: Mint regular proofs + let input_amount = Amount::from(10); + let input_proofs = test_mint.mint_proofs(input_amount).await.unwrap(); + + // Step 2: Create conditions with Alice as primary and Bob as refund key with SIG_ALL + let spending_conditions = SpendingConditions::new_p2pk( + alice_pubkey, + Some(Conditions { + locktime: Some(locktime), // locktime in the past (expired) + pubkeys: None, // no additional pubkeys + refund_keys: Some(vec![bob_pubkey]), // Bob is refund key + num_sigs: None, // default (1) + sig_flag: SigFlag::SigAll, // SIG_ALL flag + num_sigs_refund: None, // default (1) + }), + ); + println!("Created P2PK with expired locktime and refund key with SIG_ALL"); + + // Step 3: Create P2PK blinded messages + let split_amounts = test_mint.split_amount(input_amount).unwrap(); + let (p2pk_outputs, blinding_factors, secrets) = unzip3( + split_amounts + .iter() + .map(|&amt| test_mint.create_blinded_message(amt, &spending_conditions)) + .collect(), + ); + + // Step 4: Swap for P2PK proofs + let swap_request = + cdk_common::nuts::SwapRequest::new(input_proofs.clone(), p2pk_outputs.clone()); + let swap_response = mint.process_swap_request(swap_request).await.unwrap(); + + // Step 5: Construct the P2PK proofs + let p2pk_proofs = construct_proofs( + swap_response.signatures.clone(), + blinding_factors.clone(), + secrets.clone(), + &test_mint.public_keys_of_the_active_sat_keyset, + ) + .unwrap(); + + // Step 6: Try to spend with primary key (Alice) AFTER locktime expires (should fail) + let (new_outputs, _) = create_test_blinded_messages(mint, input_amount) + .await + .unwrap(); + let mut swap_request_primary = + cdk_common::nuts::SwapRequest::new(p2pk_proofs.clone(), new_outputs.clone()); + + // Sign with Alice (primary key) using SIG_ALL + swap_request_primary + .sign_sig_all(alice_secret.clone()) + .unwrap(); + + let result = mint.process_swap_request(swap_request_primary).await; + assert!( + result.is_err(), + "Should fail - primary key cannot spend after locktime expires" + ); + println!( + "✓ Spending with primary key (Alice) AFTER locktime failed as expected: {:?}", + result.err() + ); + + // Step 7: Spend with refund key (Bob) AFTER locktime (should succeed) + let mut swap_request_refund = + cdk_common::nuts::SwapRequest::new(p2pk_proofs.clone(), new_outputs.clone()); + + // Sign with Bob (refund key) using SIG_ALL + swap_request_refund + .sign_sig_all(bob_secret.clone()) + .unwrap(); + + let result = mint.process_swap_request(swap_request_refund).await; + assert!( + result.is_ok(), + "Should succeed - refund key can spend after locktime: {:?}", + result.err() + ); + println!("✓ Spending with refund key (Bob) AFTER locktime succeeded"); +} + +/// Test: P2PK with locktime after expiry, no refund keys (anyone can spend) - SIG_ALL +/// +/// Verifies that after locktime expires with NO refund keys configured and SIG_ALL, +/// anyone can spend the proofs without providing any signatures at all. +#[tokio::test] +async fn test_p2pk_sig_all_locktime_after_expiry_no_refund_anyone_can_spend() { + let test_mint = TestMintHelper::new().await.unwrap(); + let mint = test_mint.mint(); + + let (_alice_secret, alice_pubkey) = create_test_keypair(); + + // Set locktime in the past (already expired) + let locktime = unix_time() - 3600; + + println!("Alice (primary): {}", alice_pubkey); + println!("Current time: {}", unix_time()); + println!("Locktime: {} (expired 1 hour ago)", locktime); + println!("No refund keys configured - anyone can spend after locktime"); + + // Step 1: Mint regular proofs + let input_amount = Amount::from(10); + let input_proofs = test_mint.mint_proofs(input_amount).await.unwrap(); + + // Step 2: Create conditions with Alice as primary, NO refund keys, with SIG_ALL + let spending_conditions = SpendingConditions::new_p2pk( + alice_pubkey, + Some(Conditions { + locktime: Some(locktime), // locktime in the past (expired) + pubkeys: None, // no additional pubkeys + refund_keys: None, // NO refund keys - anyone can spend! + num_sigs: None, // default (1) + sig_flag: SigFlag::SigAll, // SIG_ALL flag + num_sigs_refund: None, // default (1) + }), + ); + println!("Created P2PK with expired locktime, NO refund keys, and SIG_ALL"); + + // Step 3: Create P2PK blinded messages + let split_amounts = test_mint.split_amount(input_amount).unwrap(); + let (p2pk_outputs, blinding_factors, secrets) = unzip3( + split_amounts + .iter() + .map(|&amt| test_mint.create_blinded_message(amt, &spending_conditions)) + .collect(), + ); + + // Step 4: Swap for P2PK proofs + let swap_request = + cdk_common::nuts::SwapRequest::new(input_proofs.clone(), p2pk_outputs.clone()); + let swap_response = mint.process_swap_request(swap_request).await.unwrap(); + + // Step 5: Construct the P2PK proofs + let p2pk_proofs = construct_proofs( + swap_response.signatures.clone(), + blinding_factors.clone(), + secrets.clone(), + &test_mint.public_keys_of_the_active_sat_keyset, + ) + .unwrap(); + + // Step 6: Spend WITHOUT any signatures (should succeed - anyone can spend!) + let (new_outputs, _) = create_test_blinded_messages(mint, input_amount) + .await + .unwrap(); + let swap_request_no_sig = + cdk_common::nuts::SwapRequest::new(p2pk_proofs.clone(), new_outputs.clone()); + + // No signatures added at all! + + let result = mint.process_swap_request(swap_request_no_sig).await; + assert!( + result.is_ok(), + "Should succeed - anyone can spend after locktime with no refund keys: {:?}", + result.err() + ); + println!("✓ Spending WITHOUT any signatures succeeded (anyone can spend)"); +} + +/// Test: P2PK multisig with locktime (2-of-3 before, 1-of-2 after) - SIG_ALL +/// +/// Complex scenario with SIG_ALL: Different multisig requirements before and after locktime +/// Before locktime: Need 2-of-3 from (Alice, Bob, Carol) +/// After locktime: Need 1-of-2 from (Dave, Eve) as refund keys +#[tokio::test] +async fn test_p2pk_sig_all_multisig_locktime() { + let test_mint = TestMintHelper::new().await.unwrap(); + let mint = test_mint.mint(); + + // Before locktime: Need 2-of-3 from (Alice, Bob, Carol) + let (alice_secret, alice_pubkey) = create_test_keypair(); + let (bob_secret, bob_pubkey) = create_test_keypair(); + let (_carol_secret, carol_pubkey) = create_test_keypair(); + + // After locktime: Need 1-of-2 from (Dave, Eve) as refund keys + let (dave_secret, dave_pubkey) = create_test_keypair(); + let (_eve_secret, eve_pubkey) = create_test_keypair(); + + let locktime = unix_time() - 100; // Already expired + + println!("Primary multisig: Alice, Bob, Carol (need 2-of-3)"); + println!("Refund multisig: Dave, Eve (need 1-of-2)"); + println!("Current time: {}", unix_time()); + println!("Locktime: {} (expired)", locktime); + + // Step 1: Mint regular proofs + let input_amount = Amount::from(10); + let input_proofs = test_mint.mint_proofs(input_amount).await.unwrap(); + + // Step 2: Create complex conditions with SIG_ALL + // Before locktime: 2-of-3 (Alice, Bob, Carol) + // After locktime: 1-of-2 (Dave, Eve) + let spending_conditions = SpendingConditions::new_p2pk( + alice_pubkey, + Some(Conditions { + locktime: Some(locktime), // Already expired + pubkeys: Some(vec![bob_pubkey, carol_pubkey]), // Bob and Carol (with Alice = 3 total) + refund_keys: Some(vec![dave_pubkey, eve_pubkey]), // Dave and Eve for refund + num_sigs: Some(2), // Need 2 signatures before locktime + sig_flag: SigFlag::SigAll, // SIG_ALL flag + num_sigs_refund: Some(1), // Need 1 signature after locktime + }), + ); + println!("Created complex P2PK with SIG_ALL: 2-of-3 before locktime, 1-of-2 after locktime"); + + // Step 3: Create P2PK blinded messages + let split_amounts = test_mint.split_amount(input_amount).unwrap(); + let (p2pk_outputs, blinding_factors, secrets) = unzip3( + split_amounts + .iter() + .map(|&amt| test_mint.create_blinded_message(amt, &spending_conditions)) + .collect(), + ); + + // Step 4: Swap for P2PK proofs + let swap_request = + cdk_common::nuts::SwapRequest::new(input_proofs.clone(), p2pk_outputs.clone()); + let swap_response = mint.process_swap_request(swap_request).await.unwrap(); + + // Step 5: Construct the P2PK proofs + let p2pk_proofs = construct_proofs( + swap_response.signatures.clone(), + blinding_factors.clone(), + secrets.clone(), + &test_mint.public_keys_of_the_active_sat_keyset, + ) + .unwrap(); + + // Step 6: Try to spend with primary keys (Alice + Bob) AFTER locktime (should fail) + let (new_outputs, _) = create_test_blinded_messages(mint, input_amount) + .await + .unwrap(); + let mut swap_request_primary = + cdk_common::nuts::SwapRequest::new(p2pk_proofs.clone(), new_outputs.clone()); + + // Sign with Alice + Bob (primary multisig) using SIG_ALL + swap_request_primary + .sign_sig_all(alice_secret.clone()) + .unwrap(); + swap_request_primary + .sign_sig_all(bob_secret.clone()) + .unwrap(); + + let result = mint.process_swap_request(swap_request_primary).await; + assert!( + result.is_err(), + "Should fail - locktime expired, only refund keys valid" + ); + println!( + "✓ Spending with primary keys (Alice + Bob) AFTER locktime failed as expected: {:?}", + result.err() + ); + + // Step 7: Spend with refund key (Dave) AFTER locktime (should succeed - only need 1-of-2) + let mut swap_request_refund = + cdk_common::nuts::SwapRequest::new(p2pk_proofs.clone(), new_outputs.clone()); + + // Sign with Dave only (refund key, need 1-of-2) using SIG_ALL + swap_request_refund + .sign_sig_all(dave_secret.clone()) + .unwrap(); + + let result = mint.process_swap_request(swap_request_refund).await; + assert!( + result.is_ok(), + "Should succeed - refund key can spend after locktime: {:?}", + result.err() + ); + println!("✓ Spending with refund key (Dave, 1-of-2) AFTER locktime succeeded"); +} + +/// Test: SIG_ALL with mixed proofs (different data) should fail +/// +/// Per NUT-11, when any proof has SIG_ALL, all proofs must have: +/// 1. Same kind, 2. SIG_ALL flag, 3. Same data, 4. Same tags +/// This test verifies that mixing proofs with different pubkeys (different data) is rejected. +#[tokio::test] +async fn test_p2pk_sig_all_mixed_proofs_different_data() { + let test_mint = TestMintHelper::new().await.unwrap(); + let mint = test_mint.mint(); + + // Create two different keypairs + let (alice_secret, alice_pubkey) = create_test_keypair(); + let (bob_secret, bob_pubkey) = create_test_keypair(); + + println!("Alice pubkey: {}", alice_pubkey); + println!("Bob pubkey: {}", bob_pubkey); + + // Step 1: Mint regular proofs for Alice + let alice_input_amount = Amount::from(10); + let alice_input_proofs = test_mint.mint_proofs(alice_input_amount).await.unwrap(); + + // Step 2: Create Alice's P2PK spending conditions with SIG_ALL + let alice_spending_conditions = SpendingConditions::new_p2pk( + alice_pubkey, + Some(Conditions { + locktime: None, + pubkeys: None, + refund_keys: None, + num_sigs: None, + sig_flag: SigFlag::SigAll, + num_sigs_refund: None, + }), + ); + + // Step 3: Swap for Alice's P2PK proofs + let alice_split_amounts = test_mint.split_amount(alice_input_amount).unwrap(); + let (alice_outputs, alice_blinding_factors, alice_secrets) = unzip3( + alice_split_amounts + .iter() + .map(|&amt| test_mint.create_blinded_message(amt, &alice_spending_conditions)) + .collect(), + ); + + let swap_request_alice = + cdk_common::nuts::SwapRequest::new(alice_input_proofs, alice_outputs.clone()); + let swap_response_alice = mint.process_swap_request(swap_request_alice).await.unwrap(); + + let alice_proofs = construct_proofs( + swap_response_alice.signatures.clone(), + alice_blinding_factors.clone(), + alice_secrets.clone(), + &test_mint.public_keys_of_the_active_sat_keyset, + ) + .unwrap(); + + println!( + "Created {} Alice proofs (locked to Alice with SIG_ALL)", + alice_proofs.len() + ); + + // Step 4: Mint regular proofs for Bob + let bob_input_amount = Amount::from(10); + let bob_input_proofs = test_mint.mint_proofs(bob_input_amount).await.unwrap(); + + // Step 5: Create Bob's P2PK spending conditions with SIG_ALL (different data!) + let bob_spending_conditions = SpendingConditions::new_p2pk( + bob_pubkey, + Some(Conditions { + locktime: None, + pubkeys: None, + refund_keys: None, + num_sigs: None, + sig_flag: SigFlag::SigAll, + num_sigs_refund: None, + }), + ); + + // Step 6: Swap for Bob's P2PK proofs + let bob_split_amounts = test_mint.split_amount(bob_input_amount).unwrap(); + let (bob_outputs, bob_blinding_factors, bob_secrets) = unzip3( + bob_split_amounts + .iter() + .map(|&amt| test_mint.create_blinded_message(amt, &bob_spending_conditions)) + .collect(), + ); + + let swap_request_bob = + cdk_common::nuts::SwapRequest::new(bob_input_proofs, bob_outputs.clone()); + let swap_response_bob = mint.process_swap_request(swap_request_bob).await.unwrap(); + + let bob_proofs = construct_proofs( + swap_response_bob.signatures.clone(), + bob_blinding_factors.clone(), + bob_secrets.clone(), + &test_mint.public_keys_of_the_active_sat_keyset, + ) + .unwrap(); + + println!( + "Created {} Bob proofs (locked to Bob with SIG_ALL)", + bob_proofs.len() + ); + + // Step 7: Try to spend Alice's and Bob's proofs together in one transaction (should FAIL!) + // This violates NUT-11 requirement that all SIG_ALL proofs must have same data + let total_amount = alice_input_amount + bob_input_amount; + let (new_outputs, _) = create_test_blinded_messages(mint, total_amount) + .await + .unwrap(); + + let mut mixed_proofs = alice_proofs.clone(); + mixed_proofs.extend(bob_proofs.clone()); + + let mut swap_request_mixed = + cdk_common::nuts::SwapRequest::new(mixed_proofs, new_outputs.clone()); + + // Sign with both Alice's and Bob's keys (no client-side validation, so this succeeds) + swap_request_mixed + .sign_sig_all(alice_secret.clone()) + .unwrap(); + swap_request_mixed.sign_sig_all(bob_secret.clone()).unwrap(); + + // But the mint should reject it due to mismatched data, even though both signed + let result = mint.process_swap_request(swap_request_mixed).await; + assert!(result.is_err(), "Should fail - cannot mix proofs with different data in SIG_ALL transaction, even with both signatures"); + + let error_msg = format!("{:?}", result.err().unwrap()); + println!( + "✓ Mixing Alice and Bob proofs in SIG_ALL transaction failed at mint verification: {}", + error_msg + ); + + // Step 8: Alice should be able to spend her proofs alone (should succeed) + let (alice_new_outputs, _) = create_test_blinded_messages(mint, alice_input_amount) + .await + .unwrap(); + let mut swap_request_alice_only = + cdk_common::nuts::SwapRequest::new(alice_proofs.clone(), alice_new_outputs.clone()); + swap_request_alice_only + .sign_sig_all(alice_secret.clone()) + .unwrap(); + + let result = mint.process_swap_request(swap_request_alice_only).await; + assert!( + result.is_ok(), + "Should succeed - Alice spending her own proofs: {:?}", + result.err() + ); + println!("✓ Alice successfully spent her own proofs separately"); + + // Step 9: Bob should be able to spend his proofs alone (should succeed) + let (bob_new_outputs, _) = create_test_blinded_messages(mint, bob_input_amount) + .await + .unwrap(); + let mut swap_request_bob_only = + cdk_common::nuts::SwapRequest::new(bob_proofs.clone(), bob_new_outputs.clone()); + swap_request_bob_only + .sign_sig_all(bob_secret.clone()) + .unwrap(); + + let result = mint.process_swap_request(swap_request_bob_only).await; + assert!( + result.is_ok(), + "Should succeed - Bob spending his own proofs: {:?}", + result.err() + ); + println!("✓ Bob successfully spent his own proofs separately"); +} + +/// Test: P2PK multisig BEFORE locktime expires (2-of-3) - SIG_ALL +/// +/// Tests that a 2-of-3 multisig with SIG_ALL works correctly BEFORE locktime expires. +/// This complements the existing test that verifies refund keys work AFTER locktime. +#[tokio::test] +async fn test_p2pk_sig_all_multisig_before_locktime() { + let test_mint = TestMintHelper::new().await.unwrap(); + let mint = test_mint.mint(); + + // Create 3 keypairs for primary multisig (Alice, Bob, Carol) + let (alice_secret, alice_pubkey) = create_test_keypair(); + let (bob_secret, bob_pubkey) = create_test_keypair(); + let (_carol_secret, carol_pubkey) = create_test_keypair(); + + // Create refund keys (Dave, Eve) - won't be used since we're before locktime + let (_dave_secret, dave_pubkey) = create_test_keypair(); + let (_eve_secret, eve_pubkey) = create_test_keypair(); + + let locktime = unix_time() + 3600; // Locktime is 1 hour in the future + + println!("Primary multisig: Alice, Bob, Carol (need 2-of-3)"); + println!("Refund multisig: Dave, Eve (need 1-of-2)"); + println!("Current time: {}", unix_time()); + println!("Locktime: {} (expires in 1 hour)", locktime); + + // Step 1: Mint regular proofs + let input_amount = Amount::from(10); + let input_proofs = test_mint.mint_proofs(input_amount).await.unwrap(); + + // Step 2: Create complex conditions with SIG_ALL + // Before locktime: 2-of-3 (Alice, Bob, Carol) + // After locktime: 1-of-2 (Dave, Eve) + let spending_conditions = SpendingConditions::new_p2pk( + alice_pubkey, + Some(Conditions { + locktime: Some(locktime), // 1 hour in the future + pubkeys: Some(vec![bob_pubkey, carol_pubkey]), // Bob and Carol (with Alice = 3 total) + refund_keys: Some(vec![dave_pubkey, eve_pubkey]), // Dave and Eve for refund + num_sigs: Some(2), // Need 2 signatures before locktime + sig_flag: SigFlag::SigAll, // SIG_ALL flag + num_sigs_refund: Some(1), // Need 1 signature after locktime + }), + ); + println!("Created complex P2PK with SIG_ALL: 2-of-3 before locktime, 1-of-2 after locktime"); + + // Step 3: Create P2PK blinded messages + let split_amounts = test_mint.split_amount(input_amount).unwrap(); + let (p2pk_outputs, blinding_factors, secrets) = unzip3( + split_amounts + .iter() + .map(|&amt| test_mint.create_blinded_message(amt, &spending_conditions)) + .collect(), + ); + + // Step 4: Swap for P2PK proofs + let swap_request = + cdk_common::nuts::SwapRequest::new(input_proofs.clone(), p2pk_outputs.clone()); + let swap_response = mint.process_swap_request(swap_request).await.unwrap(); + + // Step 5: Construct the P2PK proofs + let p2pk_proofs = construct_proofs( + swap_response.signatures.clone(), + blinding_factors.clone(), + secrets.clone(), + &test_mint.public_keys_of_the_active_sat_keyset, + ) + .unwrap(); + + // Step 6: Try to spend with only 1 signature (Alice) BEFORE locktime (should fail - need 2-of-3) + let (new_outputs, _) = create_test_blinded_messages(mint, input_amount) + .await + .unwrap(); + let mut swap_request_one_sig = + cdk_common::nuts::SwapRequest::new(p2pk_proofs.clone(), new_outputs.clone()); + + // Sign with Alice only (need 2-of-3) + swap_request_one_sig + .sign_sig_all(alice_secret.clone()) + .unwrap(); + + let result = mint.process_swap_request(swap_request_one_sig).await; + assert!( + result.is_err(), + "Should fail - need 2-of-3 signatures before locktime" + ); + println!( + "✓ Spending with only 1 signature (Alice) BEFORE locktime failed as expected: {:?}", + result.err() + ); + + // Step 7: Spend with 2 signatures (Alice + Bob) BEFORE locktime (should succeed - 2-of-3) + let mut swap_request_two_sigs = + cdk_common::nuts::SwapRequest::new(p2pk_proofs.clone(), new_outputs.clone()); + + // Sign with Alice + Bob (2-of-3, should succeed) + swap_request_two_sigs + .sign_sig_all(alice_secret.clone()) + .unwrap(); + swap_request_two_sigs + .sign_sig_all(bob_secret.clone()) + .unwrap(); + + let result = mint.process_swap_request(swap_request_two_sigs).await; + assert!( + result.is_ok(), + "Should succeed - 2-of-3 signatures before locktime: {:?}", + result.err() + ); + println!("✓ Spending with 2 signatures (Alice + Bob, 2-of-3) BEFORE locktime succeeded"); +} + +/// Test: P2PK with more signatures than required - SIG_ALL +/// +/// Tests that providing MORE valid signatures than required succeeds. +/// For example, 3 valid signatures for a 2-of-3 multisig should work fine. +#[tokio::test] +async fn test_p2pk_sig_all_more_signatures_than_required() { + let test_mint = TestMintHelper::new().await.unwrap(); + let mint = test_mint.mint(); + + // Create 3 keypairs for multisig (Alice, Bob, Carol) + let (alice_secret, alice_pubkey) = create_test_keypair(); + let (bob_secret, bob_pubkey) = create_test_keypair(); + let (carol_secret, carol_pubkey) = create_test_keypair(); + + println!("Multisig: Alice, Bob, Carol (need 2-of-3)"); + + // Step 1: Mint regular proofs + let input_amount = Amount::from(10); + let input_proofs = test_mint.mint_proofs(input_amount).await.unwrap(); + + // Step 2: Create 2-of-3 multisig conditions with SIG_ALL + let spending_conditions = SpendingConditions::new_p2pk( + alice_pubkey, + Some(Conditions { + locktime: None, + pubkeys: Some(vec![bob_pubkey, carol_pubkey]), // Bob and Carol (with Alice = 3 total) + refund_keys: None, + num_sigs: Some(2), // Need 2 signatures (but we'll provide 3) + sig_flag: SigFlag::SigAll, + num_sigs_refund: None, + }), + ); + println!("Created 2-of-3 multisig with SIG_ALL"); + + // Step 3: Create P2PK blinded messages + let split_amounts = test_mint.split_amount(input_amount).unwrap(); + let (p2pk_outputs, blinding_factors, secrets) = unzip3( + split_amounts + .iter() + .map(|&amt| test_mint.create_blinded_message(amt, &spending_conditions)) + .collect(), + ); + + // Step 4: Swap for P2PK proofs + let swap_request = + cdk_common::nuts::SwapRequest::new(input_proofs.clone(), p2pk_outputs.clone()); + let swap_response = mint.process_swap_request(swap_request).await.unwrap(); + + // Step 5: Construct the P2PK proofs + let p2pk_proofs = construct_proofs( + swap_response.signatures.clone(), + blinding_factors.clone(), + secrets.clone(), + &test_mint.public_keys_of_the_active_sat_keyset, + ) + .unwrap(); + + // Step 6: Spend with ALL 3 signatures (Alice + Bob + Carol) even though only 2 required + let (new_outputs, _) = create_test_blinded_messages(mint, input_amount) + .await + .unwrap(); + let mut swap_request_all_sigs = + cdk_common::nuts::SwapRequest::new(p2pk_proofs.clone(), new_outputs.clone()); + + // Sign with all 3 keys (more than the required 2-of-3) + swap_request_all_sigs + .sign_sig_all(alice_secret.clone()) + .unwrap(); + swap_request_all_sigs + .sign_sig_all(bob_secret.clone()) + .unwrap(); + swap_request_all_sigs + .sign_sig_all(carol_secret.clone()) + .unwrap(); + + let result = mint.process_swap_request(swap_request_all_sigs).await; + assert!( + result.is_ok(), + "Should succeed - 3 valid signatures when only 2-of-3 required: {:?}", + result.err() + ); + println!("✓ Spending with 3 signatures (all of Alice, Bob, Carol) when only 2-of-3 required succeeded"); +} + +/// Test: P2PK with 2-of-2 refund multisig after locktime - SIG_ALL +/// +/// Tests that after locktime expires, BOTH refund signatures are required (2-of-2). +/// Verifies that 1-of-2 fails and 2-of-2 succeeds. +#[tokio::test] +async fn test_p2pk_sig_all_refund_multisig_2of2() { + let test_mint = TestMintHelper::new().await.unwrap(); + let mint = test_mint.mint(); + + // Primary key (Alice) + let (_alice_secret, alice_pubkey) = create_test_keypair(); + + // Refund keys (Dave, Eve) - need both after locktime + let (dave_secret, dave_pubkey) = create_test_keypair(); + let (eve_secret, eve_pubkey) = create_test_keypair(); + + let locktime = unix_time() - 3600; // Already expired (1 hour ago) + + println!("Alice (primary)"); + println!("Dave, Eve (refund, need 2-of-2)"); + println!("Current time: {}", unix_time()); + println!("Locktime: {} (expired 1 hour ago)", locktime); + + // Step 1: Mint regular proofs + let input_amount = Amount::from(10); + let input_proofs = test_mint.mint_proofs(input_amount).await.unwrap(); + + // Step 2: Create conditions with 2-of-2 refund multisig and SIG_ALL + let spending_conditions = SpendingConditions::new_p2pk( + alice_pubkey, + Some(Conditions { + locktime: Some(locktime), // Already expired + pubkeys: None, + refund_keys: Some(vec![dave_pubkey, eve_pubkey]), // Dave and Eve for refund + num_sigs: None, // Default (1) for primary + sig_flag: SigFlag::SigAll, + num_sigs_refund: Some(2), // Need BOTH refund signatures (2-of-2) + }), + ); + println!("Created P2PK with SIG_ALL: 2-of-2 refund multisig after locktime"); + + // Step 3: Create P2PK blinded messages + let split_amounts = test_mint.split_amount(input_amount).unwrap(); + let (p2pk_outputs, blinding_factors, secrets) = unzip3( + split_amounts + .iter() + .map(|&amt| test_mint.create_blinded_message(amt, &spending_conditions)) + .collect(), + ); + + // Step 4: Swap for P2PK proofs + let swap_request = + cdk_common::nuts::SwapRequest::new(input_proofs.clone(), p2pk_outputs.clone()); + let swap_response = mint.process_swap_request(swap_request).await.unwrap(); + + // Step 5: Construct the P2PK proofs + let p2pk_proofs = construct_proofs( + swap_response.signatures.clone(), + blinding_factors.clone(), + secrets.clone(), + &test_mint.public_keys_of_the_active_sat_keyset, + ) + .unwrap(); + + // Step 6: Try to spend with only Dave's signature (1-of-2, should fail - need 2-of-2) + let (new_outputs, _) = create_test_blinded_messages(mint, input_amount) + .await + .unwrap(); + let mut swap_request_one_refund = + cdk_common::nuts::SwapRequest::new(p2pk_proofs.clone(), new_outputs.clone()); + + // Sign with Dave only (need both Dave and Eve) + swap_request_one_refund + .sign_sig_all(dave_secret.clone()) + .unwrap(); + + let result = mint.process_swap_request(swap_request_one_refund).await; + assert!( + result.is_err(), + "Should fail - need 2-of-2 refund signatures" + ); + println!( + "✓ Spending with only 1 refund signature (Dave) AFTER locktime failed as expected: {:?}", + result.err() + ); + + // Step 7: Spend with both Dave and Eve (2-of-2, should succeed) + let mut swap_request_both_refunds = + cdk_common::nuts::SwapRequest::new(p2pk_proofs.clone(), new_outputs.clone()); + + // Sign with both Dave and Eve (2-of-2 refund multisig) + swap_request_both_refunds + .sign_sig_all(dave_secret.clone()) + .unwrap(); + swap_request_both_refunds + .sign_sig_all(eve_secret.clone()) + .unwrap(); + + let result = mint.process_swap_request(swap_request_both_refunds).await; + assert!( + result.is_ok(), + "Should succeed - 2-of-2 refund signatures after locktime: {:?}", + result.err() + ); + println!("✓ Spending with 2-of-2 refund signatures (Dave + Eve) AFTER locktime succeeded"); +} + +/// Test: SIG_ALL should reject if output amounts are swapped +/// +/// Creates two P2PK proofs (8+2 sats) with SIG_ALL flag, swaps the output amounts +/// after signing, and verifies that the mint should reject this (but currently doesn't). +#[tokio::test] +async fn test_sig_all_should_reject_if_the_output_amounts_are_swapped() { + let test_mint = TestMintHelper::new().await.unwrap(); + let mint = test_mint.mint(); + + // Generate keypair for Alice + let (alice_secret, alice_pubkey) = create_test_keypair(); + println!("Alice pubkey: {}", alice_pubkey); + + // Step 1: Mint regular proofs (10 sats = 8+2) + let input_amount = Amount::from(10); + let input_proofs = test_mint.mint_proofs(input_amount).await.unwrap(); + println!("Minted {} sats", input_amount); + + // Step 2: Create P2PK spending conditions with SIG_ALL + let spending_conditions = SpendingConditions::new_p2pk( + alice_pubkey, + Some( + Conditions::new( + None, // no locktime + None, // no additional pubkeys + None, // no refund keys + None, // default num_sigs (1) + Some(SigFlag::SigAll), // SIG_ALL flag + None, // no num_sigs_refund + ) + .unwrap(), + ), + ); + + // Step 3: Swap for P2PK proofs with SIG_ALL + let split_amounts = vec![Amount::from(8), Amount::from(2)]; + let (p2pk_outputs, blinding_factors, secrets) = unzip3( + split_amounts + .iter() + .map(|&amt| test_mint.create_blinded_message(amt, &spending_conditions)) + .collect(), + ); + + let swap_request = cdk_common::nuts::SwapRequest::new(input_proofs, p2pk_outputs); + let swap_response = mint.process_swap_request(swap_request).await.unwrap(); + + // Step 4: Construct the P2PK proofs + let p2pk_proofs = construct_proofs( + swap_response.signatures, + blinding_factors, + secrets, + &test_mint.public_keys_of_the_active_sat_keyset, + ) + .unwrap(); + + println!("Created {} P2PK proofs with SIG_ALL", p2pk_proofs.len()); + assert_eq!(p2pk_proofs.len(), 2, "Should have 2 proofs (8+2)"); + + // Step 5: Create new swap request and sign with SIG_ALL + let (new_outputs, _) = create_test_blinded_messages(mint, input_amount) + .await + .unwrap(); + let mut swap_request = cdk_common::nuts::SwapRequest::new(p2pk_proofs, new_outputs); + + // Inspect the outputs + println!("Outputs in swap request:"); + for (i, output) in swap_request.outputs().iter().enumerate() { + println!( + " Output {}: amount={}, blinded_secret={}", + i, + output.amount, + output.blinded_secret.to_hex() + ); + } + + // Sign the transaction with SIG_ALL + swap_request.sign_sig_all(alice_secret).unwrap(); + + // Swap the amounts of the two outputs + let outputs = swap_request.outputs_mut(); + let temp_amount = outputs[0].amount; + outputs[0].amount = outputs[1].amount; + outputs[1].amount = temp_amount; + + // Print outputs after swapping amounts + println!("Outputs after swapping amounts:"); + for (i, output) in swap_request.outputs().iter().enumerate() { + println!( + " Output {}: amount={}, blinded_secret={}", + i, + output.amount, + output.blinded_secret.to_hex() + ); + } + + // Step 6: Try to execute the swap - should now FAIL because the signature is invalid + let result = mint.process_swap_request(swap_request.clone()).await; + assert!( + result.is_err(), + "Swap should fail - amounts were tampered with after signing" + ); + println!("✓ Swap correctly rejected after output amounts were swapped!"); + println!(" Error: {:?}", result.err()); + + // Step 7: Swap the amounts back to original and verify it succeeds + let outputs = swap_request.outputs_mut(); + let temp_amount = outputs[0].amount; + outputs[0].amount = outputs[1].amount; + outputs[1].amount = temp_amount; + + println!("Outputs after swapping back to original:"); + for (i, output) in swap_request.outputs().iter().enumerate() { + println!( + " Output {}: amount={}, blinded_secret={}", + i, + output.amount, + output.blinded_secret.to_hex() + ); + } + + let result = mint.process_swap_request(swap_request).await; + assert!( + result.is_ok(), + "Swap should succeed with original amounts: {:?}", + result.err() + ); + println!("✓ Swap succeeded after restoring original amounts!"); +} diff --git a/crates/cdk/src/mint/swap/tests/p2pk_spending_conditions_tests.rs b/crates/cdk/src/mint/swap/tests/p2pk_spending_conditions_tests.rs new file mode 100644 index 000000000..5c660a582 --- /dev/null +++ b/crates/cdk/src/mint/swap/tests/p2pk_spending_conditions_tests.rs @@ -0,0 +1,804 @@ +//! P2PK (NUT-11) tests for swap functionality +//! +//! These tests verify that the mint correctly validates P2PK spending conditions +//! during swap operations, including: +//! - Single signature P2PK +//! - Multisig (m-of-n) +//! - Locktime enforcement +//! - Refund keys +//! - Signature validation + +use crate::util::unix_time; +use cdk_common::dhke::construct_proofs; +use cdk_common::nuts::{Conditions, SigFlag, SpendingConditions}; +use cdk_common::Amount; + +use crate::test_helpers::mint::create_test_blinded_messages; +use crate::test_helpers::nut10::{create_test_keypair, unzip3, TestMintHelper}; + +/// Test: P2PK with single pubkey requires all proofs signed +/// +/// Creates proofs locked to a single public key and verifies: +/// 1. Spending without any signatures is rejected +/// 2. Spending with partial signatures (only some proofs signed) is rejected +/// 3. Spending with all proofs signed succeeds +#[tokio::test] +async fn test_p2pk_single_pubkey_requires_all_proofs_signed() { + let test_mint = TestMintHelper::new().await.unwrap(); + let mint = test_mint.mint(); + + // Generate keypair for P2PK + let (alice_secret, alice_pubkey) = create_test_keypair(); + println!("Alice pubkey: {}", alice_pubkey); + + // Step 1: Create regular unencumbered proofs that we'll swap for P2PK proofs + let input_amount = Amount::from(10); + let input_proofs = test_mint.mint_proofs(input_amount).await.unwrap(); + + // Step 2: Create P2PK blinded messages (outputs locked to alice_pubkey) + let spending_conditions = SpendingConditions::new_p2pk(alice_pubkey, None); + + // Split the input amount into power-of-2 denominations + let split_amounts = test_mint.split_amount(input_amount).unwrap(); + let split_display: Vec = split_amounts.iter().map(|a| a.to_string()).collect(); + println!("Split {} into [{}]", input_amount, split_display.join("+")); + + // Create blinded messages for each split amount + let (p2pk_outputs, blinding_factors, secrets) = unzip3( + split_amounts + .iter() + .map(|&amt| test_mint.create_blinded_message(amt, &spending_conditions)) + .collect(), + ); + + println!( + "Created {} P2PK outputs locked to alice", + p2pk_outputs.len() + ); + + // Step 3: Swap regular proofs for P2PK proofs (no signature needed on inputs) + let swap_request = + cdk_common::nuts::SwapRequest::new(input_proofs.clone(), p2pk_outputs.clone()); + let swap_response = mint + .process_swap_request(swap_request) + .await + .expect("Failed to swap for P2PK proofs"); + println!("Swap successful! Got BlindSignatures for our P2PK outputs"); + + // Step 4: Construct the P2PK proofs + let p2pk_proofs = construct_proofs( + swap_response.signatures.clone(), + blinding_factors.clone(), + secrets.clone(), + &test_mint.public_keys_of_the_active_sat_keyset, + ) + .unwrap(); + + let proof_amounts: Vec = p2pk_proofs.iter().map(|p| p.amount.to_string()).collect(); + println!( + "Constructed {} P2PK proof(s) [{}]", + p2pk_proofs.len(), + proof_amounts.join("+") + ); + + // Step 5: Try to spend P2PK proof WITHOUT signature (should fail) + let (new_outputs, _) = create_test_blinded_messages(mint, input_amount) + .await + .unwrap(); + let swap_request_no_sig = + cdk_common::nuts::SwapRequest::new(p2pk_proofs.clone(), new_outputs.clone()); + + let result = mint.process_swap_request(swap_request_no_sig).await; + assert!(result.is_err(), "Should fail without signature"); + println!( + "✓ Spending WITHOUT signature failed as expected: {:?}", + result.err() + ); + + // Step 6: Sign only ONE of the proofs and try (should fail - need all signatures) + let mut swap_request_partial_sig = + cdk_common::nuts::SwapRequest::new(p2pk_proofs.clone(), new_outputs.clone()); + + // Sign only the first proof + swap_request_partial_sig.inputs_mut()[0] + .sign_p2pk(alice_secret.clone()) + .unwrap(); + + let result = mint.process_swap_request(swap_request_partial_sig).await; + assert!(result.is_err(), "Should fail with only partial signatures"); + println!( + "✓ Spending with PARTIAL signatures failed as expected: {:?}", + result.err() + ); + + // Step 7: Now sign ALL the proofs and try again (should succeed) + let mut swap_request_with_sig = + cdk_common::nuts::SwapRequest::new(p2pk_proofs.clone(), new_outputs.clone()); + + // Sign all the P2PK proofs with Alice's key + for proof in swap_request_with_sig.inputs_mut() { + proof.sign_p2pk(alice_secret.clone()).unwrap(); + } + + let result = mint.process_swap_request(swap_request_with_sig).await; + assert!( + result.is_ok(), + "Should succeed with valid signature: {:?}", + result.err() + ); + println!("✓ Spending WITH ALL signatures succeeded"); +} + +/// Test: P2PK multisig (2-of-3) +/// +/// Creates proofs requiring 2 signatures from a set of 3 public keys and verifies: +/// 1. Spending with only 1 valid signature fails (Alice only) +/// 2. Spending with 2 invalid signatures fails (wrong keys) +/// 3. Spending with 2 valid signatures succeeds (Alice + Bob) +#[tokio::test] +async fn test_p2pk_multisig_2of3() { + let test_mint = TestMintHelper::new().await.unwrap(); + let mint = test_mint.mint(); + + // Generate 3 keypairs for the multisig + let (alice_secret, alice_pubkey) = create_test_keypair(); + let (bob_secret, bob_pubkey) = create_test_keypair(); + let (_carol_secret, carol_pubkey) = create_test_keypair(); + + // Generate 2 wrong keypairs (not in the multisig set) + let (dave_secret, _dave_pubkey) = create_test_keypair(); + let (eve_secret, _eve_pubkey) = create_test_keypair(); + + println!("Alice: {}", alice_pubkey); + println!("Bob: {}", bob_pubkey); + println!("Carol: {}", carol_pubkey); + + // Step 1: Mint regular proofs + let input_amount = Amount::from(10); + let input_proofs = test_mint.mint_proofs(input_amount).await.unwrap(); + + // Step 2: Create 2-of-3 multisig conditions + // Primary key: Alice + // Additional keys: Bob, Carol + // Requires 2 signatures total + let spending_conditions = SpendingConditions::new_p2pk( + alice_pubkey, + Some( + Conditions::new( + None, // no locktime + Some(vec![bob_pubkey, carol_pubkey]), // additional pubkeys + None, // no refund keys + Some(2), // require 2 signatures + None, // default sig_flag + None, // no num_sigs_refund + ) + .unwrap(), + ), + ); + println!("Created 2-of-3 multisig spending conditions (Alice, Bob, Carol)"); + + // Step 3: Create P2PK blinded messages with multisig conditions + let split_amounts = test_mint.split_amount(input_amount).unwrap(); + let (p2pk_outputs, blinding_factors, secrets) = unzip3( + split_amounts + .iter() + .map(|&amt| test_mint.create_blinded_message(amt, &spending_conditions)) + .collect(), + ); + + // Step 4: Swap for P2PK multisig proofs + let swap_request = + cdk_common::nuts::SwapRequest::new(input_proofs.clone(), p2pk_outputs.clone()); + let swap_response = mint.process_swap_request(swap_request).await.unwrap(); + println!("Created P2PK multisig proofs (2-of-3)"); + + // Step 5: Construct the P2PK proofs + let p2pk_proofs = construct_proofs( + swap_response.signatures.clone(), + blinding_factors.clone(), + secrets.clone(), + &test_mint.public_keys_of_the_active_sat_keyset, + ) + .unwrap(); + + // Step 6: Try to spend with only 1 signature (Alice only - should fail) + let (new_outputs, _) = create_test_blinded_messages(mint, input_amount) + .await + .unwrap(); + let mut swap_request_one_sig = + cdk_common::nuts::SwapRequest::new(p2pk_proofs.clone(), new_outputs.clone()); + + // Sign with only Alice + for proof in swap_request_one_sig.inputs_mut() { + proof.sign_p2pk(alice_secret.clone()).unwrap(); + } + + let result = mint.process_swap_request(swap_request_one_sig).await; + assert!( + result.is_err(), + "Should fail with only 1 signature (need 2)" + ); + println!( + "✓ Spending with only 1 signature (Alice) failed as expected: {:?}", + result.err() + ); + + // Step 7: Try to spend with 2 invalid signatures (Dave + Eve - not in multisig set) + let mut swap_request_invalid_sigs = + cdk_common::nuts::SwapRequest::new(p2pk_proofs.clone(), new_outputs.clone()); + + // Sign with Dave and Eve (wrong keys!) + for proof in swap_request_invalid_sigs.inputs_mut() { + proof.sign_p2pk(dave_secret.clone()).unwrap(); + proof.sign_p2pk(eve_secret.clone()).unwrap(); + } + + let result = mint.process_swap_request(swap_request_invalid_sigs).await; + assert!(result.is_err(), "Should fail with 2 invalid signatures"); + println!( + "✓ Spending with 2 INVALID signatures (Dave + Eve) failed as expected: {:?}", + result.err() + ); + + // Step 8: Spend with 2 valid signatures (Alice + Bob - should succeed) + let mut swap_request_valid_sigs = + cdk_common::nuts::SwapRequest::new(p2pk_proofs.clone(), new_outputs.clone()); + + // Sign with Alice and Bob + for proof in swap_request_valid_sigs.inputs_mut() { + proof.sign_p2pk(alice_secret.clone()).unwrap(); + proof.sign_p2pk(bob_secret.clone()).unwrap(); + } + + let result = mint.process_swap_request(swap_request_valid_sigs).await; + assert!( + result.is_ok(), + "Should succeed with 2 valid signatures: {:?}", + result.err() + ); + println!("✓ Spending with 2 VALID signatures (Alice + Bob) succeeded"); +} + +/// Test: P2PK with locktime (before expiry) +/// +/// Verifies that before locktime expires: +/// 1. Spending with primary key (Alice) succeeds +/// 2. Spending with refund key (Bob) fails +#[tokio::test] +async fn test_p2pk_locktime_before_expiry() { + let test_mint = TestMintHelper::new().await.unwrap(); + let mint = test_mint.mint(); + + let (alice_secret, alice_pubkey) = create_test_keypair(); + let (bob_secret, bob_pubkey) = create_test_keypair(); + + // Set locktime 1 hour in the future + let locktime = unix_time() + 3600; + + println!("Alice (primary): {}", alice_pubkey); + println!("Bob (refund): {}", bob_pubkey); + println!("Current time: {}", unix_time()); + println!("Locktime: {} (expires in 1 hour)", locktime); + + // Step 1: Mint regular proofs + let input_amount = Amount::from(10); + let input_proofs = test_mint.mint_proofs(input_amount).await.unwrap(); + + // Step 2: Create conditions with Alice as primary and Bob as refund key + let spending_conditions = SpendingConditions::new_p2pk( + alice_pubkey, + Some( + Conditions::new( + Some(locktime), // locktime in the future + None, // no additional pubkeys + Some(vec![bob_pubkey]), // Bob is refund key + None, // default num_sigs (1) + None, // default sig_flag + None, // default num_sigs_refund (1) + ) + .unwrap(), + ), + ); + println!("Created P2PK with locktime and refund key"); + + // Step 3: Create P2PK blinded messages + let split_amounts = test_mint.split_amount(input_amount).unwrap(); + let (p2pk_outputs, blinding_factors, secrets) = unzip3( + split_amounts + .iter() + .map(|&amt| test_mint.create_blinded_message(amt, &spending_conditions)) + .collect(), + ); + + // Step 4: Swap for P2PK proofs + let swap_request = + cdk_common::nuts::SwapRequest::new(input_proofs.clone(), p2pk_outputs.clone()); + let swap_response = mint.process_swap_request(swap_request).await.unwrap(); + + // Step 5: Construct the P2PK proofs + let p2pk_proofs = construct_proofs( + swap_response.signatures.clone(), + blinding_factors.clone(), + secrets.clone(), + &test_mint.public_keys_of_the_active_sat_keyset, + ) + .unwrap(); + + // Step 6: Try to spend with refund key (Bob) BEFORE locktime expires (should fail) + let (new_outputs, _) = create_test_blinded_messages(mint, input_amount) + .await + .unwrap(); + let mut swap_request_refund = + cdk_common::nuts::SwapRequest::new(p2pk_proofs.clone(), new_outputs.clone()); + + // Sign with Bob (refund key) + for proof in swap_request_refund.inputs_mut() { + proof.sign_p2pk(bob_secret.clone()).unwrap(); + } + + let result = mint.process_swap_request(swap_request_refund).await; + assert!( + result.is_err(), + "Should fail - refund key cannot spend before locktime" + ); + println!( + "✓ Spending with refund key (Bob) BEFORE locktime failed as expected: {:?}", + result.err() + ); + + // Step 7: Spend with primary key (Alice) BEFORE locktime (should succeed) + let mut swap_request_primary = + cdk_common::nuts::SwapRequest::new(p2pk_proofs.clone(), new_outputs.clone()); + + // Sign with Alice (primary key) + for proof in swap_request_primary.inputs_mut() { + proof.sign_p2pk(alice_secret.clone()).unwrap(); + } + + let result = mint.process_swap_request(swap_request_primary).await; + assert!( + result.is_ok(), + "Should succeed - primary key can spend before locktime: {:?}", + result.err() + ); + println!("✓ Spending with primary key (Alice) BEFORE locktime succeeded"); +} + +/// Test: P2PK with locktime (after expiry) +/// +/// Verifies that after locktime expires: +/// 1. Spending with refund key (Bob) succeeds +/// 2. Spending with primary key (Alice) fails +#[tokio::test] +async fn test_p2pk_locktime_after_expiry() { + let test_mint = TestMintHelper::new().await.unwrap(); + let mint = test_mint.mint(); + + let (alice_secret, alice_pubkey) = create_test_keypair(); + let (bob_secret, bob_pubkey) = create_test_keypair(); + + // Set locktime in the past (already expired) + let locktime = unix_time() - 3600; + + println!("Alice (primary): {}", alice_pubkey); + println!("Bob (refund): {}", bob_pubkey); + println!("Current time: {}", unix_time()); + println!("Locktime: {} (expired 1 hour ago)", locktime); + + // Step 1: Mint regular proofs + let input_amount = Amount::from(10); + let input_proofs = test_mint.mint_proofs(input_amount).await.unwrap(); + + // Step 2: Create conditions with Alice as primary and Bob as refund key + // Note: We create the Conditions struct directly to bypass the validation + // that rejects locktimes in the past (since we're testing the expired case) + let spending_conditions = SpendingConditions::new_p2pk( + alice_pubkey, + Some(Conditions { + locktime: Some(locktime), // locktime in the past (expired) + pubkeys: None, // no additional pubkeys + refund_keys: Some(vec![bob_pubkey]), // Bob is refund key + num_sigs: None, // default (1) + sig_flag: SigFlag::default(), + num_sigs_refund: None, // default (1) + }), + ); + println!("Created P2PK with expired locktime and refund key"); + + // Step 3: Create P2PK blinded messages + let split_amounts = test_mint.split_amount(input_amount).unwrap(); + let (p2pk_outputs, blinding_factors, secrets) = unzip3( + split_amounts + .iter() + .map(|&amt| test_mint.create_blinded_message(amt, &spending_conditions)) + .collect(), + ); + + // Step 4: Swap for P2PK proofs + let swap_request = + cdk_common::nuts::SwapRequest::new(input_proofs.clone(), p2pk_outputs.clone()); + let swap_response = mint.process_swap_request(swap_request).await.unwrap(); + + // Step 5: Construct the P2PK proofs + let p2pk_proofs = construct_proofs( + swap_response.signatures.clone(), + blinding_factors.clone(), + secrets.clone(), + &test_mint.public_keys_of_the_active_sat_keyset, + ) + .unwrap(); + + // Step 6: Try to spend with primary key (Alice) AFTER locktime expires (should fail) + let (new_outputs, _) = create_test_blinded_messages(mint, input_amount) + .await + .unwrap(); + let mut swap_request_primary = + cdk_common::nuts::SwapRequest::new(p2pk_proofs.clone(), new_outputs.clone()); + + // Sign with Alice (primary key) + for proof in swap_request_primary.inputs_mut() { + proof.sign_p2pk(alice_secret.clone()).unwrap(); + } + + let result = mint.process_swap_request(swap_request_primary).await; + assert!( + result.is_err(), + "Should fail - primary key cannot spend after locktime expires" + ); + println!( + "✓ Spending with primary key (Alice) AFTER locktime failed as expected: {:?}", + result.err() + ); + + // Step 7: Spend with refund key (Bob) AFTER locktime (should succeed) + let mut swap_request_refund = + cdk_common::nuts::SwapRequest::new(p2pk_proofs.clone(), new_outputs.clone()); + + // Sign with Bob (refund key) + for proof in swap_request_refund.inputs_mut() { + proof.sign_p2pk(bob_secret.clone()).unwrap(); + } + + let result = mint.process_swap_request(swap_request_refund).await; + assert!( + result.is_ok(), + "Should succeed - refund key can spend after locktime: {:?}", + result.err() + ); + println!("✓ Spending with refund key (Bob) AFTER locktime succeeded"); +} + +/// Test: P2PK with locktime after expiry, no refund keys (anyone can spend) +/// +/// Verifies that after locktime expires with NO refund keys configured, +/// anyone can spend the proofs without providing any signatures at all. +#[tokio::test] +async fn test_p2pk_locktime_after_expiry_no_refund_anyone_can_spend() { + let test_mint = TestMintHelper::new().await.unwrap(); + let mint = test_mint.mint(); + + let (_alice_secret, alice_pubkey) = create_test_keypair(); + + // Set locktime in the past (already expired) + let locktime = unix_time() - 3600; + + println!("Alice (primary): {}", alice_pubkey); + println!("Current time: {}", unix_time()); + println!("Locktime: {} (expired 1 hour ago)", locktime); + println!("No refund keys configured - anyone can spend after locktime"); + + // Step 1: Mint regular proofs + let input_amount = Amount::from(10); + let input_proofs = test_mint.mint_proofs(input_amount).await.unwrap(); + + // Step 2: Create conditions with Alice as primary, NO refund keys + let spending_conditions = SpendingConditions::new_p2pk( + alice_pubkey, + Some(Conditions { + locktime: Some(locktime), // locktime in the past (expired) + pubkeys: None, // no additional pubkeys + refund_keys: None, // NO refund keys - anyone can spend! + num_sigs: None, // default (1) + sig_flag: SigFlag::default(), + num_sigs_refund: None, // default (1) + }), + ); + println!("Created P2PK with expired locktime and NO refund keys"); + + // Step 3: Create P2PK blinded messages + let split_amounts = test_mint.split_amount(input_amount).unwrap(); + let (p2pk_outputs, blinding_factors, secrets) = unzip3( + split_amounts + .iter() + .map(|&amt| test_mint.create_blinded_message(amt, &spending_conditions)) + .collect(), + ); + + // Step 4: Swap for P2PK proofs + let swap_request = + cdk_common::nuts::SwapRequest::new(input_proofs.clone(), p2pk_outputs.clone()); + let swap_response = mint.process_swap_request(swap_request).await.unwrap(); + + // Step 5: Construct the P2PK proofs + let p2pk_proofs = construct_proofs( + swap_response.signatures.clone(), + blinding_factors.clone(), + secrets.clone(), + &test_mint.public_keys_of_the_active_sat_keyset, + ) + .unwrap(); + + // Step 6: Spend WITHOUT any signatures (should succeed - anyone can spend!) + let (new_outputs, _) = create_test_blinded_messages(mint, input_amount) + .await + .unwrap(); + let swap_request_no_sig = + cdk_common::nuts::SwapRequest::new(p2pk_proofs.clone(), new_outputs.clone()); + + // No signatures added at all! + + let result = mint.process_swap_request(swap_request_no_sig).await; + assert!( + result.is_ok(), + "Should succeed - anyone can spend after locktime with no refund keys: {:?}", + result.err() + ); + println!("✓ Spending WITHOUT any signatures succeeded (anyone can spend)"); +} + +/// Test: P2PK multisig with locktime (2-of-3 before, 1-of-2 after) +/// +/// Complex scenario: Different multisig requirements before and after locktime +/// Before locktime: Need 2-of-3 from (Alice, Bob, Carol) +/// After locktime: Need 1-of-2 from (Dave, Eve) as refund keys +#[tokio::test] +async fn test_p2pk_multisig_locktime() { + let test_mint = TestMintHelper::new().await.unwrap(); + let mint = test_mint.mint(); + + // Before locktime: Need 2-of-3 from (Alice, Bob, Carol) + let (alice_secret, alice_pubkey) = create_test_keypair(); + let (bob_secret, bob_pubkey) = create_test_keypair(); + let (_carol_secret, carol_pubkey) = create_test_keypair(); + + // After locktime: Need 1-of-2 from (Dave, Eve) as refund keys + let (dave_secret, dave_pubkey) = create_test_keypair(); + let (_eve_secret, eve_pubkey) = create_test_keypair(); + + let locktime = unix_time() - 100; // Already expired + + println!("Primary multisig: Alice, Bob, Carol (need 2-of-3)"); + println!("Refund multisig: Dave, Eve (need 1-of-2)"); + println!("Current time: {}", unix_time()); + println!("Locktime: {} (expired)", locktime); + + // Step 1: Mint regular proofs + let input_amount = Amount::from(10); + let input_proofs = test_mint.mint_proofs(input_amount).await.unwrap(); + + // Step 2: Create complex conditions + // Before locktime: 2-of-3 (Alice, Bob, Carol) + // After locktime: 1-of-2 (Dave, Eve) + let spending_conditions = SpendingConditions::new_p2pk( + alice_pubkey, + Some(Conditions { + locktime: Some(locktime), // Already expired + pubkeys: Some(vec![bob_pubkey, carol_pubkey]), // Bob and Carol (with Alice = 3 total) + refund_keys: Some(vec![dave_pubkey, eve_pubkey]), // Dave and Eve for refund + num_sigs: Some(2), // Need 2 signatures before locktime + sig_flag: SigFlag::default(), + num_sigs_refund: Some(1), // Need 1 signature after locktime + }), + ); + println!("Created complex P2PK: 2-of-3 before locktime, 1-of-2 after locktime"); + + // Step 3: Create P2PK blinded messages + let split_amounts = test_mint.split_amount(input_amount).unwrap(); + let (p2pk_outputs, blinding_factors, secrets) = unzip3( + split_amounts + .iter() + .map(|&amt| test_mint.create_blinded_message(amt, &spending_conditions)) + .collect(), + ); + + // Step 4: Swap for P2PK proofs + let swap_request = + cdk_common::nuts::SwapRequest::new(input_proofs.clone(), p2pk_outputs.clone()); + let swap_response = mint.process_swap_request(swap_request).await.unwrap(); + + // Step 5: Construct the P2PK proofs + let p2pk_proofs = construct_proofs( + swap_response.signatures.clone(), + blinding_factors.clone(), + secrets.clone(), + &test_mint.public_keys_of_the_active_sat_keyset, + ) + .unwrap(); + + // Step 6: Try to spend with primary keys (Alice + Bob) AFTER locktime (should fail) + let (new_outputs, _) = create_test_blinded_messages(mint, input_amount) + .await + .unwrap(); + let mut swap_request_primary = + cdk_common::nuts::SwapRequest::new(p2pk_proofs.clone(), new_outputs.clone()); + + // Sign with Alice + Bob (primary multisig) + for proof in swap_request_primary.inputs_mut() { + proof.sign_p2pk(alice_secret.clone()).unwrap(); + proof.sign_p2pk(bob_secret.clone()).unwrap(); + } + + let result = mint.process_swap_request(swap_request_primary).await; + assert!( + result.is_err(), + "Should fail - locktime expired, only refund keys valid" + ); + println!( + "✓ Spending with primary keys (Alice + Bob) AFTER locktime failed as expected: {:?}", + result.err() + ); + + // Step 7: Spend with refund key (Dave) AFTER locktime (should succeed - only need 1-of-2) + let mut swap_request_refund = + cdk_common::nuts::SwapRequest::new(p2pk_proofs.clone(), new_outputs.clone()); + + // Sign with Dave only (refund key, need 1-of-2) + for proof in swap_request_refund.inputs_mut() { + proof.sign_p2pk(dave_secret.clone()).unwrap(); + } + + let result = mint.process_swap_request(swap_request_refund).await; + assert!( + result.is_ok(), + "Should succeed - refund key can spend after locktime: {:?}", + result.err() + ); + println!("✓ Spending with refund key (Dave, 1-of-2) AFTER locktime succeeded"); +} + +/// Test: P2PK signed by wrong person is rejected +/// +/// Creates proofs locked to Alice's public key and verifies that +/// signing with Bob's key (wrong key) is rejected +#[tokio::test] +async fn test_p2pk_signed_by_wrong_person() { + let test_mint = TestMintHelper::new().await.unwrap(); + let mint = test_mint.mint(); + + // Generate keypairs for Alice and Bob + let (_alice_secret, alice_pubkey) = create_test_keypair(); + let (bob_secret, _bob_pubkey) = create_test_keypair(); + println!("Alice pubkey: {}", alice_pubkey); + println!("Bob will try to spend Alice's proofs"); + + // Step 1: Mint regular proofs + let input_amount = Amount::from(10); + let input_proofs = test_mint.mint_proofs(input_amount).await.unwrap(); + + // Step 2: Create P2PK blinded messages locked to Alice's pubkey + let spending_conditions = SpendingConditions::new_p2pk(alice_pubkey, None); + let split_amounts = test_mint.split_amount(input_amount).unwrap(); + let (p2pk_outputs, blinding_factors, secrets) = unzip3( + split_amounts + .iter() + .map(|&amt| test_mint.create_blinded_message(amt, &spending_conditions)) + .collect(), + ); + + // Step 3: Swap for P2PK proofs locked to Alice + let swap_request = + cdk_common::nuts::SwapRequest::new(input_proofs.clone(), p2pk_outputs.clone()); + let swap_response = mint.process_swap_request(swap_request).await.unwrap(); + println!("Created P2PK proofs locked to Alice"); + + // Step 4: Construct the P2PK proofs + let p2pk_proofs = construct_proofs( + swap_response.signatures.clone(), + blinding_factors.clone(), + secrets.clone(), + &test_mint.public_keys_of_the_active_sat_keyset, + ) + .unwrap(); + + // Step 5: Try to spend Alice's proofs by signing with Bob's key (wrong key!) + let (new_outputs, _) = create_test_blinded_messages(mint, input_amount) + .await + .unwrap(); + let mut swap_request_wrong_sig = + cdk_common::nuts::SwapRequest::new(p2pk_proofs.clone(), new_outputs.clone()); + + // Sign with Bob's key instead of Alice's key + for proof in swap_request_wrong_sig.inputs_mut() { + proof.sign_p2pk(bob_secret.clone()).unwrap(); + } + + let result = mint.process_swap_request(swap_request_wrong_sig).await; + assert!(result.is_err(), "Should fail when signed with wrong key"); + println!( + "✓ Spending signed by wrong person failed as expected: {:?}", + result.err() + ); +} + +/// Test: Duplicate signatures are rejected +/// +/// Verifies that using the same signature twice doesn't count as multiple signers +/// in a 2-of-2 multisig scenario +#[tokio::test] +async fn test_p2pk_duplicate_signatures() { + let test_mint = TestMintHelper::new().await.unwrap(); + let mint = test_mint.mint(); + + let (alice_secret, alice_pubkey) = create_test_keypair(); + let (_bob_secret, bob_pubkey) = create_test_keypair(); + + println!("Alice: {}", alice_pubkey); + println!("Bob: {}", bob_pubkey); + + // Step 1: Mint regular proofs + let input_amount = Amount::from(10); + let input_proofs = test_mint.mint_proofs(input_amount).await.unwrap(); + + // Step 2: Create 2-of-2 multisig (Alice and Bob, need both) + let spending_conditions = SpendingConditions::new_p2pk( + alice_pubkey, + Some( + Conditions::new( + None, // no locktime + Some(vec![bob_pubkey]), // Bob is additional pubkey + None, // no refund keys + Some(2), // require 2 signatures (Alice + Bob) + None, // default sig_flag + None, // no num_sigs_refund + ) + .unwrap(), + ), + ); + println!("Created 2-of-2 multisig (Alice, Bob)"); + + // Step 3: Create P2PK blinded messages + let split_amounts = test_mint.split_amount(input_amount).unwrap(); + let (p2pk_outputs, blinding_factors, secrets) = unzip3( + split_amounts + .iter() + .map(|&amt| test_mint.create_blinded_message(amt, &spending_conditions)) + .collect(), + ); + + // Step 4: Swap for P2PK proofs + let swap_request = + cdk_common::nuts::SwapRequest::new(input_proofs.clone(), p2pk_outputs.clone()); + let swap_response = mint.process_swap_request(swap_request).await.unwrap(); + + // Step 5: Construct the P2PK proofs + let p2pk_proofs = construct_proofs( + swap_response.signatures.clone(), + blinding_factors.clone(), + secrets.clone(), + &test_mint.public_keys_of_the_active_sat_keyset, + ) + .unwrap(); + + // Step 6: Try to spend with Alice's signature TWICE (should fail - need Alice + Bob, not Alice + Alice) + let (new_outputs, _) = create_test_blinded_messages(mint, input_amount) + .await + .unwrap(); + let mut swap_request_duplicate = + cdk_common::nuts::SwapRequest::new(p2pk_proofs.clone(), new_outputs.clone()); + + // Sign with Alice twice instead of Alice + Bob + for proof in swap_request_duplicate.inputs_mut() { + proof.sign_p2pk(alice_secret.clone()).unwrap(); + proof.sign_p2pk(alice_secret.clone()).unwrap(); // Duplicate! + } + + let result = mint.process_swap_request(swap_request_duplicate).await; + assert!( + result.is_err(), + "Should fail - duplicate signatures not allowed" + ); + println!( + "✓ Spending with duplicate signatures (Alice + Alice) failed as expected: {:?}", + result.err() + ); +} diff --git a/crates/cdk/src/test_helpers/mod.rs b/crates/cdk/src/test_helpers/mod.rs index 93eee043e..1b88d53cb 100644 --- a/crates/cdk/src/test_helpers/mod.rs +++ b/crates/cdk/src/test_helpers/mod.rs @@ -7,3 +7,5 @@ #[cfg(feature = "mint")] pub mod mint; +#[cfg(feature = "mint")] +pub mod nut10; diff --git a/crates/cdk/src/test_helpers/nut10.rs b/crates/cdk/src/test_helpers/nut10.rs new file mode 100644 index 000000000..dcc8cf21c --- /dev/null +++ b/crates/cdk/src/test_helpers/nut10.rs @@ -0,0 +1,145 @@ +#![cfg(test)] +//! Shared test helpers for spending condition tests (P2PK, HTLC, etc.) + +use crate::mint::Mint; +use crate::secret::Secret; +use crate::Error; +use cdk_common::dhke::blind_message; +use cdk_common::nuts::nut10::Secret as Nut10Secret; +use cdk_common::nuts::{ + BlindedMessage, CurrencyUnit, Id, Keys, PublicKey, SecretKey, SpendingConditions, +}; +use cdk_common::Amount; + +use crate::test_helpers::mint::{create_test_mint, mint_test_proofs}; + +/// Test mint wrapper with convenient access to common keyset info +pub struct TestMintHelper { + pub mint: Mint, + pub active_sat_keyset_id: Id, + pub public_keys_of_the_active_sat_keyset: Keys, + /// Available denominations sorted largest first (e.g., [2147483648, 1073741824, ..., 2, 1]) + pub available_amounts_sorted: Vec, +} + +impl TestMintHelper { + pub async fn new() -> Result { + let mint = create_test_mint().await?; + + // Get the active SAT keyset ID + let active_sat_keyset_id = mint + .get_active_keysets() + .get(&CurrencyUnit::Sat) + .cloned() + .ok_or(Error::Internal)?; + + // Get the active SAT keyset keys + let lookup_by_that_id = mint.keyset_pubkeys(&active_sat_keyset_id)?; + let active_sat_keyset = lookup_by_that_id.keysets.first().ok_or(Error::Internal)?; + assert_eq!( + active_sat_keyset.id, active_sat_keyset_id, + "Keyset ID mismatch" + ); + let public_keys_of_the_active_sat_keyset = active_sat_keyset.keys.clone(); + + // Get the available denominations from the keyset, sorted largest first + let mut available_amounts_sorted: Vec = public_keys_of_the_active_sat_keyset + .iter() + .map(|(amt, _)| amt.to_u64()) + .collect(); + available_amounts_sorted.sort_by(|a, b| b.cmp(a)); // Sort descending (largest first) + + Ok(TestMintHelper { + mint, + active_sat_keyset_id, + public_keys_of_the_active_sat_keyset, + available_amounts_sorted, + }) + } + + /// Get a reference to the underlying mint + pub fn mint(&self) -> &Mint { + &self.mint + } + + /// Split an amount into power-of-2 denominations + /// Returns the amounts that sum to the total (e.g., 10 -> [8, 2]) + pub fn split_amount(&self, amount: Amount) -> Result, Error> { + // Simple greedy algorithm: start from largest and work down + let mut result = Vec::new(); + let mut remaining = amount.to_u64(); + + for &amt in &self.available_amounts_sorted { + if remaining >= amt { + result.push(Amount::from(amt)); + remaining -= amt; + } + } + + if remaining != 0 { + return Err(Error::Internal); + } + + Ok(result) + } + + /// Mint proofs for the given amount + /// Prints a message like "Minted 10 sats [8+2]" + pub async fn mint_proofs(&self, amount: Amount) -> Result { + let proofs = mint_test_proofs(&self.mint, amount).await?; + + // Build the split display string (e.g., "8+2") + let split_amounts = self.split_amount(amount)?; + let split_display: Vec = split_amounts.iter().map(|a| a.to_string()).collect(); + println!("Minted {} sats [{}]", amount, split_display.join("+")); + + Ok(proofs) + } + + /// Create a single blinded message with spending conditions for the given amount + /// Returns (blinded_message, blinding_factor, secret) + pub fn create_blinded_message( + &self, + amount: Amount, + spending_conditions: &SpendingConditions, + ) -> (BlindedMessage, SecretKey, Secret) { + let nut10_secret: Nut10Secret = spending_conditions.clone().into(); + let secret: Secret = nut10_secret.try_into().unwrap(); + let (blinded_point, blinding_factor) = blind_message(&secret.to_bytes(), None).unwrap(); + let blinded_msg = BlindedMessage::new(amount, self.active_sat_keyset_id, blinded_point); + (blinded_msg, blinding_factor, secret) + } +} + +/// Helper: Create a keypair for testing +pub fn create_test_keypair() -> (SecretKey, PublicKey) { + let secret = SecretKey::generate(); + let pubkey = secret.public_key(); + (secret, pubkey) +} + +/// Helper: Create a hash and preimage for testing +/// Returns (hash_hex_string, preimage_hex_string) +pub fn create_test_hash_and_preimage() -> (String, String) { + use bitcoin::hashes::sha256::Hash as Sha256Hash; + use bitcoin::hashes::Hash; + + // Create a 32-byte preimage + let preimage_bytes = [0x42u8; 32]; + let hash = Sha256Hash::hash(&preimage_bytes); + // Return hex-encoded hash and hex-encoded preimage + (hash.to_string(), crate::util::hex::encode(preimage_bytes)) +} + +/// Helper: Unzip a vector of 3-tuples into 3 separate vectors +pub fn unzip3(vec: Vec<(A, B, C)>) -> (Vec, Vec, Vec) { + let mut vec_a = Vec::new(); + let mut vec_b = Vec::new(); + let mut vec_c = Vec::new(); + for (a, b, c) in vec { + vec_a.push(a); + vec_b.push(b); + vec_c.push(c); + } + (vec_a, vec_b, vec_c) +} From 836a50aaa34a0aec47e941f33ecb3c7725c0c56d Mon Sep 17 00:00:00 2001 From: tsk Date: Sat, 15 Nov 2025 11:32:11 +0000 Subject: [PATCH 265/321] fix: require 0 signatures for HTLC with no pubkeys specified (#1275) * fix: require 0 signatures for HTLC with no pubkeys specified Prior to this fix, HTLC verification incorrectly required 1 signature even when no pubkeys were specified in the spending conditions. This caused valid preimage-only HTLCs to fail verification. The issue occurred in get_pubkeys_and_required_sigs() for HTLC secrets before locktime: - Line 179: pubkeys defaults to empty vector [] when not specified - Line 180: required_sigs defaulted to 1 unconditionally - Result: impossible condition requiring 1 signature from 0 pubkeys * refactor(cashu): replace tuple with SpendingRequirements struct in nut10 Introduce SpendingRequirements struct to replace tuple return type in get_pubkeys_and_required_sigs function. This improves code clarity by using named fields (preimage_needed, pubkeys, required_sigs) instead of positional tuple elements across nut10, nut11, and nut14 modules --- crates/cashu/src/nuts/nut10.rs | 95 ++++++++++++++++++++++-------- crates/cashu/src/nuts/nut11/mod.rs | 11 ++-- crates/cashu/src/nuts/nut14/mod.rs | 13 ++-- 3 files changed, 83 insertions(+), 36 deletions(-) diff --git a/crates/cashu/src/nuts/nut10.rs b/crates/cashu/src/nuts/nut10.rs index 8b84c5820..df3739620 100644 --- a/crates/cashu/src/nuts/nut10.rs +++ b/crates/cashu/src/nuts/nut10.rs @@ -13,6 +13,20 @@ use thiserror::Error; use super::nut01::PublicKey; use super::Conditions; +/// Spending requirements for P2PK or HTLC verification +/// +/// Returned by `get_pubkeys_and_required_sigs` to indicate what conditions +/// must be met to spend a proof. +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct SpendingRequirements { + /// Whether a preimage is required (HTLC only, before locktime) + pub preimage_needed: bool, + /// Public keys that can provide valid signatures + pub pubkeys: Vec, + /// Minimum number of signatures required from the pubkeys + pub required_sigs: u64, +} + /// NUT13 Error #[derive(Debug, Error)] pub enum Error { @@ -116,15 +130,17 @@ impl Secret { /// From NUT-11: "If the tag locktime is the unix time and the mint's local clock is greater than /// locktime, the Proof becomes spendable by anyone, except [... if refund keys are specified]" /// -/// Returns (preimage_needed, pubkeys, required_sigs). -/// For P2PK, preimage_needed is always false. -/// For HTLC, preimage_needed is true before locktime; From NUT-14: "if the current system time -/// is later than Secret.tag.locktime, the Proof can be spent if Proof.witness includes -/// a signature from the key in Secret.tags.refund." +/// Returns `SpendingRequirements` containing: +/// - `preimage_needed`: For P2PK, always false. For HTLC, true before locktime. +/// - `pubkeys`: The public keys that can provide valid signatures +/// - `required_sigs`: The minimum number of signatures required +/// +/// From NUT-14: "if the current system time is later than Secret.tag.locktime, the Proof can +/// be spent if Proof.witness includes a signature from the key in Secret.tags.refund." pub(crate) fn get_pubkeys_and_required_sigs( secret: &Secret, current_time: u64, -) -> Result<(bool, Vec, u64), super::nut11::Error> { +) -> Result { debug_assert!( secret.kind() == Kind::P2PK || secret.kind() == Kind::HTLC, "get_pubkeys_and_required_sigs called with invalid kind - this is a bug" @@ -149,10 +165,18 @@ pub(crate) fn get_pubkeys_and_required_sigs( if let Some(refund_keys) = &conditions.refund_keys { // Locktime has passed and refund keys exist - use refund keys let refund_sigs = conditions.num_sigs_refund.unwrap_or(1); - Ok((false, refund_keys.clone(), refund_sigs)) + Ok(SpendingRequirements { + preimage_needed: false, + pubkeys: refund_keys.clone(), + required_sigs: refund_sigs, + }) } else { // Locktime has passed with no refund keys - anyone can spend - Ok((false, vec![], 0)) + Ok(SpendingRequirements { + preimage_needed: false, + pubkeys: vec![], + required_sigs: 0, + }) } } else { // Before locktime: logic differs between P2PK and HTLC @@ -171,14 +195,28 @@ pub(crate) fn get_pubkeys_and_required_sigs( } let primary_num_sigs_required = conditions.num_sigs.unwrap_or(1); - Ok((false, primary_keys, primary_num_sigs_required)) + Ok(SpendingRequirements { + preimage_needed: false, + pubkeys: primary_keys, + required_sigs: primary_num_sigs_required, + }) } Kind::HTLC => { // HTLC: needs preimage before locktime, pubkeys from conditions // (data contains hash, not pubkey) let pubkeys = conditions.pubkeys.clone().unwrap_or_default(); - let required_sigs = conditions.num_sigs.unwrap_or(1); - Ok((true, pubkeys, required_sigs)) + // If no pubkeys are specified, require 0 signatures (only preimage needed) + // Otherwise, default to requiring 1 signature + let required_sigs = if pubkeys.is_empty() { + 0 + } else { + conditions.num_sigs.unwrap_or(1) + }; + Ok(SpendingRequirements { + preimage_needed: true, + pubkeys, + required_sigs, + }) } } } @@ -417,13 +455,15 @@ pub trait SpendingConditionVerification { let current_time = crate::util::unix_time(); // Get the relevant public keys and required signature count based on locktime - let (preimage_needed, pubkeys, required_sigs) = - get_pubkeys_and_required_sigs(&first_secret, current_time)?; + let requirements = get_pubkeys_and_required_sigs(&first_secret, current_time)?; - debug_assert!(!preimage_needed, "P2PK should never require preimage"); + debug_assert!( + !requirements.preimage_needed, + "P2PK should never require preimage" + ); // Handle "anyone can spend" case (locktime passed with no refund keys) - if required_sigs == 0 { + if requirements.required_sigs == 0 { return Ok(()); } @@ -449,11 +489,14 @@ pub trait SpendingConditionVerification { .map_err(|_| super::nut11::Error::InvalidSignature)?; // Verify signatures using the existing valid_signatures function - let valid_sig_count = - super::nut11::valid_signatures(msg_to_sign.as_bytes(), &pubkeys, &signatures)?; + let valid_sig_count = super::nut11::valid_signatures( + msg_to_sign.as_bytes(), + &requirements.pubkeys, + &signatures, + )?; // Check if we have enough valid signatures - if valid_sig_count < required_sigs { + if valid_sig_count < requirements.required_sigs { return Err(super::nut11::Error::SpendConditionsNotMet); } @@ -478,11 +521,10 @@ pub trait SpendingConditionVerification { let current_time = crate::util::unix_time(); // Get the relevant public keys, required signature count, and whether preimage is needed - let (preimage_needed, pubkeys, required_sigs) = - get_pubkeys_and_required_sigs(&first_secret, current_time)?; + let requirements = get_pubkeys_and_required_sigs(&first_secret, current_time)?; // If preimage is needed (before locktime), verify it - if preimage_needed { + if requirements.preimage_needed { // Extract HTLC witness let htlc_witness = match first_input.witness.as_ref() { Some(super::Witness::HTLCWitness(witness)) => witness, @@ -495,7 +537,7 @@ pub trait SpendingConditionVerification { } // Handle "anyone can spend" case (locktime passed with no refund keys) - if required_sigs == 0 { + if requirements.required_sigs == 0 { return Ok(()); } @@ -521,11 +563,14 @@ pub trait SpendingConditionVerification { .map_err(|_| super::nut11::Error::InvalidSignature)?; // Verify signatures using the existing valid_signatures function - let valid_sig_count = - super::nut11::valid_signatures(msg_to_sign.as_bytes(), &pubkeys, &signatures)?; + let valid_sig_count = super::nut11::valid_signatures( + msg_to_sign.as_bytes(), + &requirements.pubkeys, + &signatures, + )?; // Check if we have enough valid signatures - if valid_sig_count < required_sigs { + if valid_sig_count < requirements.required_sigs { return Err(super::nut11::Error::SpendConditionsNotMet); } diff --git a/crates/cashu/src/nuts/nut11/mod.rs b/crates/cashu/src/nuts/nut11/mod.rs index 8d137fb6a..4a1d3c963 100644 --- a/crates/cashu/src/nuts/nut11/mod.rs +++ b/crates/cashu/src/nuts/nut11/mod.rs @@ -155,15 +155,14 @@ impl Proof { // Based on the current time, we must identify the relevant keys let now = unix_time(); - let (preimage_needed, relevant_pubkeys, relevant_num_sigs_required) = - super::nut10::get_pubkeys_and_required_sigs(&secret, now)?; + let requirements = super::nut10::get_pubkeys_and_required_sigs(&secret, now)?; - if preimage_needed { + if requirements.preimage_needed { return Err(Error::PreimageNotSupportedInP2PK); } // Handle "anyone can spend" case (locktime passed with no refund keys) - if relevant_num_sigs_required == 0 { + if requirements.required_sigs == 0 { return Ok(()); } @@ -178,7 +177,7 @@ impl Proof { let msg: &[u8] = self.secret.as_bytes(); let valid_sig_count = valid_signatures( msg, - &relevant_pubkeys, + &requirements.pubkeys, &witness_signatures .iter() .map(|s| Signature::from_str(s)) @@ -186,7 +185,7 @@ impl Proof { )?; // Check if we have enough valid signatures - if valid_sig_count >= relevant_num_sigs_required { + if valid_sig_count >= requirements.required_sigs { Ok(()) } else { Err(Error::SpendConditionsNotMet) diff --git a/crates/cashu/src/nuts/nut14/mod.rs b/crates/cashu/src/nuts/nut14/mod.rs index 3a741b363..57f170775 100644 --- a/crates/cashu/src/nuts/nut14/mod.rs +++ b/crates/cashu/src/nuts/nut14/mod.rs @@ -113,7 +113,7 @@ impl Proof { // Get the appropriate spending conditions based on locktime let now = unix_time(); - let (preimage_needed, relevant_pubkeys, relevant_num_sigs_required) = + let requirements = super::nut10::get_pubkeys_and_required_sigs(&secret, now).map_err(Error::NUT11)?; // While a Witness is usually needed in a P2PK or HTLC proof, it's not @@ -126,7 +126,7 @@ impl Proof { // is needed to get a preimage or signatures. // If preimage is needed (before locktime), verify it - if preimage_needed { + if requirements.preimage_needed { // Extract HTLC witness let htlc_witness = match &self.witness { Some(Witness::HTLCWitness(witness)) => witness, @@ -137,7 +137,7 @@ impl Proof { super::nut10::verify_htlc_preimage(htlc_witness, &secret)?; } - if relevant_num_sigs_required == 0 { + if requirements.required_sigs == 0 { return Ok(()); } @@ -163,10 +163,10 @@ impl Proof { // Count valid signatures using relevant_pubkeys let msg: &[u8] = self.secret.as_bytes(); - let valid_sig_count = valid_signatures(msg, &relevant_pubkeys, &signatures)?; + let valid_sig_count = valid_signatures(msg, &requirements.pubkeys, &signatures)?; // Check if we have enough valid signatures - if valid_sig_count >= relevant_num_sigs_required { + if valid_sig_count >= requirements.required_sigs { Ok(()) } else { Err(Error::NUT11(super::nut11::Error::SpendConditionsNotMet)) @@ -191,6 +191,9 @@ impl Proof { #[cfg(test)] mod tests { + use bitcoin::hashes::sha256::Hash as Sha256Hash; + use bitcoin::hashes::Hash; + use super::*; use crate::nuts::nut00::Witness; use crate::nuts::nut10::Kind; From 4723e328864812bc1a0516c8498c60dbffdd3b4b Mon Sep 17 00:00:00 2001 From: gudnuf <108303703+gudnuf@users.noreply.github.com> Date: Sat, 15 Nov 2025 07:28:02 -0800 Subject: [PATCH 266/321] fix: return actual error from get_payment_quote (#1274) --- crates/cdk/src/mint/melt/mod.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/cdk/src/mint/melt/mod.rs b/crates/cdk/src/mint/melt/mod.rs index 1ceae7e5a..3b92e809f 100644 --- a/crates/cdk/src/mint/melt/mod.rs +++ b/crates/cdk/src/mint/melt/mod.rs @@ -179,7 +179,7 @@ impl Mint { METRICS.record_mint_operation("get_melt_bolt11_quote", false); METRICS.record_error(); } - Error::UnsupportedUnit + err })?; if &payment_quote.unit != unit { @@ -285,7 +285,7 @@ impl Mint { err ); - Error::UnsupportedUnit + err })?; if &payment_quote.unit != unit { From 2dfac3425e6744d14202eb602a028e67bd2bb367 Mon Sep 17 00:00:00 2001 From: C Date: Sat, 15 Nov 2025 12:28:25 -0300 Subject: [PATCH 267/321] Update Wallet::fetch_mint_info (#1277) Make `fetch_mint_info` fetch the mint_info through the mint metadata cache instead of calling the Mint Connector directly. This will make sure to persist the data correctly in other instances and the database --- crates/cdk/src/wallet/mod.rs | 116 +++++++++++++++++------------------ 1 file changed, 55 insertions(+), 61 deletions(-) diff --git a/crates/cdk/src/wallet/mod.rs b/crates/cdk/src/wallet/mod.rs index 26fca287a..f08aa6a87 100644 --- a/crates/cdk/src/wallet/mod.rs +++ b/crates/cdk/src/wallet/mod.rs @@ -284,72 +284,66 @@ impl Wallet { /// Query mint for current mint information #[instrument(skip(self))] pub async fn fetch_mint_info(&self) -> Result, Error> { - match self.client.get_mint_info().await { - Ok(mint_info) => { - // If mint provides time make sure it is accurate - if let Some(mint_unix_time) = mint_info.time { - let current_unix_time = unix_time(); - if current_unix_time.abs_diff(mint_unix_time) > 30 { - tracing::warn!( - "Mint time does match wallet time. Mint: {}, Wallet: {}", - mint_unix_time, - current_unix_time - ); - return Err(Error::MintTimeExceedsTolerance); - } - } + let mint_info = self + .metadata_cache + .load_from_mint(&self.localstore, &self.client) + .await? + .mint_info + .clone(); + + // If mint provides time make sure it is accurate + if let Some(mint_unix_time) = mint_info.time { + let current_unix_time = unix_time(); + if current_unix_time.abs_diff(mint_unix_time) > 30 { + tracing::warn!( + "Mint time does match wallet time. Mint: {}, Wallet: {}", + mint_unix_time, + current_unix_time + ); + return Err(Error::MintTimeExceedsTolerance); + } + } - // Create or update auth wallet - #[cfg(feature = "auth")] - { - let mut auth_wallet = self.auth_wallet.write().await; - match &*auth_wallet { - Some(auth_wallet) => { - let mut protected_endpoints = - auth_wallet.protected_endpoints.write().await; - *protected_endpoints = mint_info.protected_endpoints(); - - if let Some(oidc_client) = mint_info - .openid_discovery() - .map(|url| OidcClient::new(url, None)) - { - auth_wallet.set_oidc_client(Some(oidc_client)).await; - } - } - None => { - tracing::info!("Mint has auth enabled creating auth wallet"); - - let oidc_client = mint_info - .openid_discovery() - .map(|url| OidcClient::new(url, None)); - let new_auth_wallet = AuthWallet::new( - self.mint_url.clone(), - None, - self.localstore.clone(), - self.metadata_cache.clone(), - mint_info.protected_endpoints(), - oidc_client, - ); - *auth_wallet = Some(new_auth_wallet.clone()); - - self.client.set_auth_wallet(Some(new_auth_wallet)).await; - } + // Create or update auth wallet + #[cfg(feature = "auth")] + { + let mut auth_wallet = self.auth_wallet.write().await; + match &*auth_wallet { + Some(auth_wallet) => { + let mut protected_endpoints = auth_wallet.protected_endpoints.write().await; + *protected_endpoints = mint_info.protected_endpoints(); + + if let Some(oidc_client) = mint_info + .openid_discovery() + .map(|url| OidcClient::new(url, None)) + { + auth_wallet.set_oidc_client(Some(oidc_client)).await; } } - - self.localstore - .add_mint(self.mint_url.clone(), Some(mint_info.clone())) - .await?; - - tracing::trace!("Mint info updated for {}", self.mint_url); - - Ok(Some(mint_info)) - } - Err(err) => { - tracing::warn!("Could not get mint info {}", err); - Ok(None) + None => { + tracing::info!("Mint has auth enabled creating auth wallet"); + + let oidc_client = mint_info + .openid_discovery() + .map(|url| OidcClient::new(url, None)); + let new_auth_wallet = AuthWallet::new( + self.mint_url.clone(), + None, + self.localstore.clone(), + self.metadata_cache.clone(), + mint_info.protected_endpoints(), + oidc_client, + ); + *auth_wallet = Some(new_auth_wallet.clone()); + + self.client.set_auth_wallet(Some(new_auth_wallet)).await; + } } } + + tracing::trace!("Mint info updated for {}", self.mint_url); + + Ok(Some(mint_info)) } /// Get amounts needed to refill proof state From 24d397d10be8bfb5b3382137d743c8601e63f75b Mon Sep 17 00:00:00 2001 From: C Date: Sat, 15 Nov 2025 12:29:03 -0300 Subject: [PATCH 268/321] Don't read keys from the database (#1280) Read the keys from `metadata_cache` --- crates/cdk/src/wallet/melt/melt_bolt11.rs | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/crates/cdk/src/wallet/melt/melt_bolt11.rs b/crates/cdk/src/wallet/melt/melt_bolt11.rs index 2924ec058..a91ae5c94 100644 --- a/crates/cdk/src/wallet/melt/melt_bolt11.rs +++ b/crates/cdk/src/wallet/melt/melt_bolt11.rs @@ -216,10 +216,16 @@ impl Wallet { }; let active_keys = self - .localstore - .get_keys(&active_keyset_id) + .metadata_cache + .load(&self.localstore, &self.client, { + let ttl = self.metadata_cache_ttl.read(); + *ttl + }) .await? - .ok_or(Error::NoActiveKeyset)?; + .keys + .get(&active_keyset_id) + .ok_or(Error::NoActiveKeyset)? + .clone(); let change_proofs = match melt_response.change { Some(change) => { From 501e72f7c7912f0e11c91bf982ab6952123bbd6c Mon Sep 17 00:00:00 2001 From: C Date: Sat, 15 Nov 2025 16:31:27 -0300 Subject: [PATCH 269/321] Fix missing try_proof_operation_or_reclaim wrapping of a swap (#1278) --- crates/cdk/src/wallet/receive.rs | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/crates/cdk/src/wallet/receive.rs b/crates/cdk/src/wallet/receive.rs index b738c9b72..cc7bf09bb 100644 --- a/crates/cdk/src/wallet/receive.rs +++ b/crates/cdk/src/wallet/receive.rs @@ -126,7 +126,12 @@ impl Wallet { } } - let swap_response = self.client.post_swap(pre_swap.swap_request).await?; + let swap_response = self + .try_proof_operation_or_reclaim( + pre_swap.swap_request.inputs().clone(), + self.client.post_swap(pre_swap.swap_request), + ) + .await?; // Proof to keep let recv_proofs = construct_proofs( From 66f7561680ac206df12e2e4820bd1b343cc332e8 Mon Sep 17 00:00:00 2001 From: tsk Date: Sun, 16 Nov 2025 21:16:05 +0000 Subject: [PATCH 270/321] ci: reduce ci jobs (#1284) --- .github/workflows/ci.yml | 96 ++++++---------------------------------- 1 file changed, 14 insertions(+), 82 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 199cd8980..2156e1413 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -376,61 +376,17 @@ jobs: matrix: build-args: [ - -p cashu --no-default-features --features "wallet mint", - -p cdk-common --no-default-features --features "wallet mint", - -p cdk-sql-common, - -p cdk, - -p cdk --no-default-features --features "mint auth", - -p cdk --no-default-features --features "wallet auth", - -p cdk --no-default-features --features "http_subscription", - -p cdk-axum, - -p cdk-axum --no-default-features --features redis, - -p cdk-lnbits, - -p cdk-fake-wallet, - -p cdk-cln, - -p cdk-lnd, - -p cdk-mint-rpc, - -p cdk-sqlite, - -p cdk-mintd, - -p cdk-payment-processor --no-default-features, - ] - steps: - - name: checkout - uses: actions/checkout@v4 - - name: Get flake hash - id: flake-hash - run: echo "hash=$(sha256sum flake.lock | cut -d' ' -f1 | cut -c1-8)" >> $GITHUB_OUTPUT - - name: Install Nix - uses: DeterminateSystems/nix-installer-action@v17 - - name: Nix Cache - uses: DeterminateSystems/magic-nix-cache-action@main - with: - diagnostic-endpoint: "" - use-flakehub: false - - name: Rust Cache - uses: Swatinem/rust-cache@v2 - with: - shared-key: "msrv-${{ steps.flake-hash.outputs.hash }}" - - name: Build - run: nix develop -i -L .#msrv --command cargo build ${{ matrix.build-args }} + # Core library - all features EXCEPT swagger (which breaks MSRV) + '-p cdk --features "mint,wallet,auth,nostr,bip353,tor,prometheus"', + # Mintd with all backends, databases, and features (no swagger) + # This also validates cdk-axum, all LN backends, all databases as dependencies + '-p cdk-mintd --no-default-features --features "cln,lnd,lnbits,fakewallet,ldk-node,grpc-processor,sqlite,postgres,auth,prometheus,redis,management-rpc"', - check-wasm: - name: Check WASM - runs-on: ubuntu-latest - timeout-minutes: 30 - needs: pre-commit-checks - strategy: - fail-fast: true - matrix: - rust: - - stable - target: - - wasm32-unknown-unknown - build-args: - [ - -p cdk, - -p cdk --no-default-features, + # CLI - default features (excludes redb which breaks MSRV) + -p cdk-cli, + + # Minimal builds to ensure no-default-features works -p cdk --no-default-features --features wallet, ] steps: @@ -449,10 +405,9 @@ jobs: - name: Rust Cache uses: Swatinem/rust-cache@v2 with: - shared-key: "stable-${{ steps.flake-hash.outputs.hash }}" - - name: Build cdk and binding - run: nix develop -i -L ".#${{ matrix.rust }}" --command cargo build ${{ matrix.build-args }} --target ${{ matrix.target }} - + shared-key: "msrv-${{ steps.flake-hash.outputs.hash }}" + - name: Build + run: nix develop -i -L .#msrv --command cargo build ${{ matrix.build-args }} check-wasm-msrv: name: Check WASM @@ -545,8 +500,8 @@ jobs: run: | docker compose -f misc/keycloak/docker-compose-recover.yml down - doc-tests: - name: "Documentation Tests" + docs: + name: "Documentation tests and checks" runs-on: ubuntu-latest timeout-minutes: 30 needs: pre-commit-checks @@ -579,28 +534,5 @@ jobs: shared-key: "stable-${{ steps.flake-hash.outputs.hash }}" - name: Run doc tests run: nix develop -i -L .#stable --command cargo test --doc - - strict-docs: - name: "Strict Documentation Check" - runs-on: ubuntu-latest - timeout-minutes: 30 - needs: doc-tests - steps: - - name: checkout - uses: actions/checkout@v4 - - name: Get flake hash - id: flake-hash - run: echo "hash=$(sha256sum flake.lock | cut -d' ' -f1 | cut -c1-8)" >> $GITHUB_OUTPUT - - name: Install Nix - uses: DeterminateSystems/nix-installer-action@v17 - - name: Nix Cache - uses: DeterminateSystems/magic-nix-cache-action@main - with: - diagnostic-endpoint: "" - use-flakehub: false - - name: Rust Cache - uses: Swatinem/rust-cache@v2 - with: - shared-key: "stable-${{ steps.flake-hash.outputs.hash }}" - name: Check docs with strict warnings run: nix develop -i -L .#stable --command just docs-strict From 0b95cbc3f69588636590114cf5effe1e481b48d4 Mon Sep 17 00:00:00 2001 From: black5box Date: Mon, 17 Nov 2025 17:20:28 +0800 Subject: [PATCH 271/321] chore: fix some minor issues in comments (#1287) Signed-off-by: black5box --- crates/cdk-integration-tests/src/lib.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/cdk-integration-tests/src/lib.rs b/crates/cdk-integration-tests/src/lib.rs index 4331ac22b..3660ffa92 100644 --- a/crates/cdk-integration-tests/src/lib.rs +++ b/crates/cdk-integration-tests/src/lib.rs @@ -64,7 +64,7 @@ pub fn get_second_mint_url_from_env() -> String { } } -// This is the ln wallet we use to send/receive ln payements as the wallet +// This is the ln wallet we use to send/receive ln payments as the wallet pub async fn init_lnd_client(work_dir: &Path) -> LndClient { let lnd_dir = get_lnd_dir(work_dir, "one"); let cert_file = lnd_dir.join("tls.cert"); @@ -133,7 +133,7 @@ pub async fn create_invoice_for_env(amount_sat: Option) -> Result { } } -// This is the ln wallet we use to send/receive ln payements as the wallet +// This is the ln wallet we use to send/receive ln payments as the wallet async fn _get_lnd_client() -> LndClient { let temp_dir = get_work_dir(); From df468139cb7219ab3316146b2935372b87ed18e8 Mon Sep 17 00:00:00 2001 From: tsk Date: Mon, 17 Nov 2025 09:31:06 +0000 Subject: [PATCH 272/321] fix: we use the nightly flake so we don't need +nightly (#1288) --- .github/workflows/nightly-rustfmt.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/nightly-rustfmt.yml b/.github/workflows/nightly-rustfmt.yml index bcf970930..b9ba334e1 100644 --- a/.github/workflows/nightly-rustfmt.yml +++ b/.github/workflows/nightly-rustfmt.yml @@ -38,7 +38,7 @@ jobs: nix develop -i -L .#nightly --command bash -c ' # Force use of Nix-provided rustfmt export RUSTFMT=$(command -v rustfmt) - cargo +nightly fmt + cargo fmt ' # Manually remove trailing whitespace git ls-files -- '*.rs' -z | xargs -0 sed -E -i'' -e 's/[[:space:]]+$//' From 023e7b97b687c05be00176e753402b4bc960fd06 Mon Sep 17 00:00:00 2001 From: tsk Date: Mon, 17 Nov 2025 09:38:03 +0000 Subject: [PATCH 273/321] chore: change mutation testing ci time (#1289) --- .github/workflows/mutation-testing-weekly.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/mutation-testing-weekly.yml b/.github/workflows/mutation-testing-weekly.yml index f69aacbff..73c8c2961 100644 --- a/.github/workflows/mutation-testing-weekly.yml +++ b/.github/workflows/mutation-testing-weekly.yml @@ -1,9 +1,9 @@ name: Weekly Mutation Testing on: - # Run every Monday at 9 AM UTC + # Run every Friday at 3 AM UTC schedule: - - cron: '0 9 * * 1' + - cron: '0 3 * * 5' # Allow manual trigger workflow_dispatch: From 3df35b4a38cc3254e236033791a3d5c2f6ce8118 Mon Sep 17 00:00:00 2001 From: tsk Date: Mon, 17 Nov 2025 15:23:30 +0000 Subject: [PATCH 274/321] fix: load keyset keys from database to prevent duplicate insertions (#1291) The wallet was failing on the second mint with "UNIQUE constraint failed: key.keyset_u32" because the MintMetadataCache never loaded keys from the database on startup. Every new process would re-fetch keys from the mint's HTTP API and try to insert them again, causing aconstraint violation. Fixed by loading existing keys from the database into the cache before fetching from HTTP (in both load_from_mint and load_auth). Checking if keys already exist before trying to insert them in persist_to_database. This eliminates the duplicate insertion errors and also saves bandwidth by not re-fetching keys we already have. --- crates/cdk/src/wallet/mint_metadata_cache.rs | 40 ++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/crates/cdk/src/wallet/mint_metadata_cache.rs b/crates/cdk/src/wallet/mint_metadata_cache.rs index a83134b4a..122f7f1d6 100644 --- a/crates/cdk/src/wallet/mint_metadata_cache.rs +++ b/crates/cdk/src/wallet/mint_metadata_cache.rs @@ -243,6 +243,20 @@ impl MintMetadataCache { return Ok(current_metadata); } + // Load keys from database before fetching from HTTP + // This prevents re-fetching keys we already have and avoids duplicate insertions + if let Some(keysets) = storage.get_mint_keysets(self.mint_url.clone()).await? { + let mut updated_metadata = (*self.metadata.load().clone()).clone(); + for keyset_info in keysets { + if let Some(keys) = storage.get_keys(&keyset_info.id).await? { + tracing::trace!("Loaded keys for keyset {} from database", keyset_info.id); + updated_metadata.keys.insert(keyset_info.id, Arc::new(keys)); + } + } + // Update cache with database keys before HTTP fetch + self.metadata.store(Arc::new(updated_metadata)); + } + // Perform the fetch #[cfg(feature = "auth")] let metadata = self.fetch_from_http(Some(client), None).await?; @@ -371,6 +385,23 @@ impl MintMetadataCache { return Ok(current_metadata); } + // Load keys from database before fetching from HTTP + // This prevents re-fetching keys we already have and avoids duplicate insertions + if let Some(keysets) = storage.get_mint_keysets(self.mint_url.clone()).await? { + let mut updated_metadata = (*self.metadata.load().clone()).clone(); + for keyset_info in keysets { + if let Some(keys) = storage.get_keys(&keyset_info.id).await? { + tracing::trace!( + "Loaded keys for keyset {} from database (auth)", + keyset_info.id + ); + updated_metadata.keys.insert(keyset_info.id, Arc::new(keys)); + } + } + // Update cache with database keys before HTTP fetch + self.metadata.store(Arc::new(updated_metadata)); + } + // Auth data not in cache - fetch from mint let metadata = self.fetch_from_http(None, Some(auth_client)).await?; @@ -455,6 +486,15 @@ impl MintMetadataCache { // Save keys for each keyset for (keyset_id, keys) in &metadata.keys { if let Some(keyset_info) = metadata.keysets.get(keyset_id) { + // Check if keys already exist in database to avoid duplicate insertion + if storage.get_keys(keyset_id).await.ok().flatten().is_some() { + tracing::trace!( + "Keys for keyset {} already in database, skipping insert", + keyset_id + ); + continue; + } + let keyset = KeySet { id: *keyset_id, unit: keyset_info.unit.clone(), From e7fe058188f5f3c118d118c006ddc0785b75881f Mon Sep 17 00:00:00 2001 From: tsk Date: Mon, 17 Nov 2025 16:19:54 +0000 Subject: [PATCH 275/321] feat: add test coverage for mutants caught in https://github.com/cashubtc/cdk/issues/1290 (#1293) --- .cargo-mutants.toml | 9 +++ crates/cashu/src/amount.rs | 136 +++++++++++++++++++++++++++++++++++++ 2 files changed, 145 insertions(+) create mode 100644 .cargo-mutants.toml diff --git a/.cargo-mutants.toml b/.cargo-mutants.toml new file mode 100644 index 000000000..fc9ec3ce1 --- /dev/null +++ b/.cargo-mutants.toml @@ -0,0 +1,9 @@ +# Cargo mutants configuration +# See: https://mutants.rs/ + +# Skip simple getters that are trivially correct and tested by integration tests +# These mutations would be caught by integration tests like test_split_with_fee +exclude_re = [ + "cashu/src/amount.rs.*FeeAndAmounts::fee", + "cashu/src/amount.rs.*FeeAndAmounts::amounts", +] diff --git a/crates/cashu/src/amount.rs b/crates/cashu/src/amount.rs index d0848c901..d2497f414 100644 --- a/crates/cashu/src/amount.rs +++ b/crates/cashu/src/amount.rs @@ -962,4 +962,140 @@ mod tests { let amount = Amount::from(1337u64); assert_eq!(amount.to_u64(), 1337); } + + /// Tests that checked_mul returns the correct product value. + /// + /// This is critical for any multiplication operations. If it returns None + /// or Some(Amount::ZERO) instead of the actual product, calculations will be wrong. + /// + /// Mutant testing: Kills mutations that replace checked_mul with None or Some(Default::default()). + #[test] + fn test_checked_mul_returns_correct_value() { + let amount1 = Amount::from(10); + let amount2 = Amount::from(5); + let result = amount1.checked_mul(amount2); + assert_eq!(result, Some(Amount::from(50))); + assert_ne!(result, None); + assert_ne!(result, Some(Amount::ZERO)); + + let amount1 = Amount::from(100); + let amount2 = Amount::from(20); + let result = amount1.checked_mul(amount2); + assert_eq!(result, Some(Amount::from(2000))); + assert_ne!(result, Some(Amount::ZERO)); + + let amount1 = Amount::from(7); + let amount2 = Amount::from(13); + let result = amount1.checked_mul(amount2); + assert_eq!(result, Some(Amount::from(91))); + + // Test multiplication by zero + let amount1 = Amount::from(100); + let amount2 = Amount::ZERO; + let result = amount1.checked_mul(amount2); + assert_eq!(result, Some(Amount::ZERO)); + + // Test multiplication by one + let amount1 = Amount::from(42); + let amount2 = Amount::ONE; + let result = amount1.checked_mul(amount2); + assert_eq!(result, Some(Amount::from(42))); + + // Test overflow + let amount1 = Amount::from(u64::MAX); + let amount2 = Amount::from(2); + let result = amount1.checked_mul(amount2); + assert!(result.is_none()); + } + + /// Tests that checked_div returns the correct quotient value. + /// + /// This is critical for division operations. If it returns None or + /// Some(Amount::ZERO) instead of the actual quotient, calculations will be wrong. + /// + /// Mutant testing: Kills mutations that replace checked_div with None or Some(Default::default()). + #[test] + fn test_checked_div_returns_correct_value() { + let amount1 = Amount::from(100); + let amount2 = Amount::from(5); + let result = amount1.checked_div(amount2); + assert_eq!(result, Some(Amount::from(20))); + assert_ne!(result, None); + assert_ne!(result, Some(Amount::ZERO)); + + let amount1 = Amount::from(1000); + let amount2 = Amount::from(10); + let result = amount1.checked_div(amount2); + assert_eq!(result, Some(Amount::from(100))); + assert_ne!(result, Some(Amount::ZERO)); + + let amount1 = Amount::from(91); + let amount2 = Amount::from(7); + let result = amount1.checked_div(amount2); + assert_eq!(result, Some(Amount::from(13))); + + // Test division by one + let amount1 = Amount::from(42); + let amount2 = Amount::ONE; + let result = amount1.checked_div(amount2); + assert_eq!(result, Some(Amount::from(42))); + + // Test integer division (truncation) + let amount1 = Amount::from(10); + let amount2 = Amount::from(3); + let result = amount1.checked_div(amount2); + assert_eq!(result, Some(Amount::from(3))); + + // Test division by zero + let amount1 = Amount::from(100); + let amount2 = Amount::ZERO; + let result = amount1.checked_div(amount2); + assert!(result.is_none()); + } + + /// Tests that Amount::convert_unit returns the correct converted value. + /// + /// This is critical for unit conversions. If it returns Ok(Amount::ZERO) + /// instead of the actual converted value, all conversions will be wrong. + /// + /// Mutant testing: Kills mutations that replace convert_unit with Ok(Default::default()). + #[test] + fn test_convert_unit_returns_correct_value() { + let amount = Amount::from(1000); + let result = amount + .convert_unit(&CurrencyUnit::Sat, &CurrencyUnit::Msat) + .unwrap(); + assert_eq!(result, Amount::from(1_000_000)); + assert_ne!(result, Amount::ZERO); + + let amount = Amount::from(5000); + let result = amount + .convert_unit(&CurrencyUnit::Msat, &CurrencyUnit::Sat) + .unwrap(); + assert_eq!(result, Amount::from(5)); + assert_ne!(result, Amount::ZERO); + + let amount = Amount::from(123); + let result = amount + .convert_unit(&CurrencyUnit::Sat, &CurrencyUnit::Sat) + .unwrap(); + assert_eq!(result, Amount::from(123)); + + let amount = Amount::from(456); + let result = amount + .convert_unit(&CurrencyUnit::Usd, &CurrencyUnit::Usd) + .unwrap(); + assert_eq!(result, Amount::from(456)); + + let amount = Amount::from(789); + let result = amount + .convert_unit(&CurrencyUnit::Eur, &CurrencyUnit::Eur) + .unwrap(); + assert_eq!(result, Amount::from(789)); + + // Test invalid conversion + let amount = Amount::from(100); + let result = amount.convert_unit(&CurrencyUnit::Sat, &CurrencyUnit::Eur); + assert!(result.is_err()); + } } From e1c18e51d43047968dca5b4d912bbe6c17c90289 Mon Sep 17 00:00:00 2001 From: tsk Date: Mon, 17 Nov 2025 17:28:04 +0000 Subject: [PATCH 276/321] fix: flaky test by using wait and pay (#1292) --- crates/cdk-integration-tests/tests/bolt12.rs | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/crates/cdk-integration-tests/tests/bolt12.rs b/crates/cdk-integration-tests/tests/bolt12.rs index 2c508e292..ce484ba71 100644 --- a/crates/cdk-integration-tests/tests/bolt12.rs +++ b/crates/cdk-integration-tests/tests/bolt12.rs @@ -79,12 +79,17 @@ async fn test_regtest_bolt12_mint() { .await .unwrap(); cln_client - .pay_bolt12_offer(None, mint_quote.request) + .pay_bolt12_offer(None, mint_quote.request.clone()) .await .unwrap(); let proofs = wallet - .mint_bolt12(&mint_quote.id, None, SplitTarget::default(), None) + .wait_and_mint_quote( + mint_quote.clone(), + SplitTarget::default(), + None, + tokio::time::Duration::from_secs(60), + ) .await .unwrap(); From c880ef70275a91eef4c476eec613c8fd09352a20 Mon Sep 17 00:00:00 2001 From: tsk Date: Mon, 17 Nov 2025 21:21:41 +0000 Subject: [PATCH 277/321] refactor(cdk/wallet): extract keyset key loading into helper method (#1296) Consolidate duplicate keyset key loading logic from melt_bolt11 and swap modules into reusable load_keyset_keys() helper method. Also add load_mint_info() helper for consistent metadata cache access. --- crates/cdk/src/wallet/melt/melt_bolt11.rs | 12 +----------- crates/cdk/src/wallet/mod.rs | 20 ++++++++++++++++++++ crates/cdk/src/wallet/swap.rs | 12 +----------- 3 files changed, 22 insertions(+), 22 deletions(-) diff --git a/crates/cdk/src/wallet/melt/melt_bolt11.rs b/crates/cdk/src/wallet/melt/melt_bolt11.rs index a91ae5c94..f779ee1c4 100644 --- a/crates/cdk/src/wallet/melt/melt_bolt11.rs +++ b/crates/cdk/src/wallet/melt/melt_bolt11.rs @@ -215,17 +215,7 @@ impl Wallet { } }; - let active_keys = self - .metadata_cache - .load(&self.localstore, &self.client, { - let ttl = self.metadata_cache_ttl.read(); - *ttl - }) - .await? - .keys - .get(&active_keyset_id) - .ok_or(Error::NoActiveKeyset)? - .clone(); + let active_keys = self.load_keyset_keys(active_keyset_id).await?; let change_proofs = match melt_response.change { Some(change) => { diff --git a/crates/cdk/src/wallet/mod.rs b/crates/cdk/src/wallet/mod.rs index f08aa6a87..deee8916c 100644 --- a/crates/cdk/src/wallet/mod.rs +++ b/crates/cdk/src/wallet/mod.rs @@ -346,6 +346,26 @@ impl Wallet { Ok(Some(mint_info)) } + /// Load mint info from cache + /// + /// This is a helper function that loads the mint info from the metadata cache + /// using the configured TTL. Unlike `fetch_mint_info()`, this does not make + /// a network call if the cache is fresh. + #[instrument(skip(self))] + pub async fn load_mint_info(&self) -> Result { + let mint_info = self + .metadata_cache + .load(&self.localstore, &self.client, { + let ttl = self.metadata_cache_ttl.read(); + *ttl + }) + .await? + .mint_info + .clone(); + + Ok(mint_info) + } + /// Get amounts needed to refill proof state #[instrument(skip(self))] pub async fn amounts_needed_for_state_target( diff --git a/crates/cdk/src/wallet/swap.rs b/crates/cdk/src/wallet/swap.rs index b78fad922..aa3ca39a2 100644 --- a/crates/cdk/src/wallet/swap.rs +++ b/crates/cdk/src/wallet/swap.rs @@ -47,17 +47,7 @@ impl Wallet { .get_keyset_fees_and_amounts_by_id(active_keyset_id) .await?; - let active_keys = self - .metadata_cache - .load(&self.localstore, &self.client, { - let ttl = self.metadata_cache_ttl.read(); - *ttl - }) - .await? - .keys - .get(&active_keyset_id) - .ok_or(Error::UnknownKeySet)? - .clone(); + let active_keys = self.load_keyset_keys(active_keyset_id).await?; let post_swap_proofs = construct_proofs( swap_response.signatures, From 15c315ea090de4f798b39ba5392911f26c9ef1d8 Mon Sep 17 00:00:00 2001 From: tsk Date: Mon, 17 Nov 2025 22:01:11 +0000 Subject: [PATCH 278/321] feat(cdk): add invoice decoding for bolt11 and bolt12 (#1294) * feat(cdk): add invoice decoding for bolt11 and bolt12 Add decode_invoice function to parse both bolt11 invoices and bolt12 offers, extracting amount, expiry, and description. Includes FFI bindings for cross-language support. --- crates/cdk-common/src/error.rs | 3 + crates/cdk-ffi/src/types/invoice.rs | 96 +++++++++++++ crates/cdk-ffi/src/types/mod.rs | 2 + crates/cdk/src/invoice.rs | 129 ++++++++++++++++++ crates/cdk/src/lib.rs | 1 + .../htlc_sigall_spending_conditions_tests.rs | 3 +- .../tests/htlc_spending_conditions_tests.rs | 3 +- .../locktime_spending_conditions_tests.rs | 3 +- .../p2pk_sigall_spending_conditions_tests.rs | 3 +- .../tests/p2pk_spending_conditions_tests.rs | 3 +- crates/cdk/src/mint/swap/mod.rs | 2 +- .../p2pk_sigall_spending_conditions_tests.rs | 2 +- .../tests/p2pk_spending_conditions_tests.rs | 2 +- crates/cdk/src/test_helpers/nut10.rs | 6 +- 14 files changed, 244 insertions(+), 14 deletions(-) create mode 100644 crates/cdk-ffi/src/types/invoice.rs create mode 100644 crates/cdk/src/invoice.rs diff --git a/crates/cdk-common/src/error.rs b/crates/cdk-common/src/error.rs index 1a2ffbd0c..8ef8f4e60 100644 --- a/crates/cdk-common/src/error.rs +++ b/crates/cdk-common/src/error.rs @@ -110,6 +110,9 @@ pub enum Error { /// Could not parse bolt12 #[error("Could not parse bolt12")] Bolt12parse, + /// Could not parse invoice (bolt11 or bolt12) + #[error("Could not parse invoice")] + InvalidInvoice, /// BIP353 address parsing error #[error("Failed to parse BIP353 address: {0}")] diff --git a/crates/cdk-ffi/src/types/invoice.rs b/crates/cdk-ffi/src/types/invoice.rs new file mode 100644 index 000000000..262cbebd1 --- /dev/null +++ b/crates/cdk-ffi/src/types/invoice.rs @@ -0,0 +1,96 @@ +//! Invoice decoding FFI types and functions + +use serde::{Deserialize, Serialize}; + +use crate::error::FfiError; + +/// Type of Lightning payment request +#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize, uniffi::Enum)] +pub enum PaymentType { + /// Bolt11 invoice + Bolt11, + /// Bolt12 offer + Bolt12, +} + +impl From for PaymentType { + fn from(payment_type: cdk::invoice::PaymentType) -> Self { + match payment_type { + cdk::invoice::PaymentType::Bolt11 => Self::Bolt11, + cdk::invoice::PaymentType::Bolt12 => Self::Bolt12, + } + } +} + +impl From for cdk::invoice::PaymentType { + fn from(payment_type: PaymentType) -> Self { + match payment_type { + PaymentType::Bolt11 => Self::Bolt11, + PaymentType::Bolt12 => Self::Bolt12, + } + } +} + +/// Decoded invoice or offer information +#[derive(Debug, Clone, Serialize, Deserialize, uniffi::Record)] +pub struct DecodedInvoice { + /// Type of payment request (Bolt11 or Bolt12) + pub payment_type: PaymentType, + /// Amount in millisatoshis, if specified + pub amount_msat: Option, + /// Expiry timestamp (Unix timestamp), if specified + pub expiry: Option, + /// Description or offer description, if specified + pub description: Option, +} + +impl From for DecodedInvoice { + fn from(decoded: cdk::invoice::DecodedInvoice) -> Self { + Self { + payment_type: decoded.payment_type.into(), + amount_msat: decoded.amount_msat, + expiry: decoded.expiry, + description: decoded.description, + } + } +} + +impl From for cdk::invoice::DecodedInvoice { + fn from(decoded: DecodedInvoice) -> Self { + Self { + payment_type: decoded.payment_type.into(), + amount_msat: decoded.amount_msat, + expiry: decoded.expiry, + description: decoded.description, + } + } +} + +/// Decode a bolt11 invoice or bolt12 offer from a string +/// +/// This function attempts to parse the input as a bolt11 invoice first, +/// then as a bolt12 offer if bolt11 parsing fails. +/// +/// # Arguments +/// +/// * `invoice_str` - The invoice or offer string to decode +/// +/// # Returns +/// +/// * `Ok(DecodedInvoice)` - Successfully decoded invoice/offer information +/// * `Err(FfiError)` - Failed to parse as either bolt11 or bolt12 +/// +/// # Example +/// +/// ```kotlin +/// val decoded = decodeInvoice("lnbc...") +/// when (decoded.paymentType) { +/// PaymentType.BOLT11 -> println("Bolt11 invoice") +/// PaymentType.BOLT12 -> println("Bolt12 offer") +/// } +/// ``` +#[uniffi::export] +pub fn decode_invoice(invoice_str: String) -> Result { + let decoded = cdk::invoice::decode_invoice(&invoice_str)?; + Ok(decoded.into()) +} diff --git a/crates/cdk-ffi/src/types/mod.rs b/crates/cdk-ffi/src/types/mod.rs index 3c4257186..e428b8fa2 100644 --- a/crates/cdk-ffi/src/types/mod.rs +++ b/crates/cdk-ffi/src/types/mod.rs @@ -5,6 +5,7 @@ // Module declarations pub mod amount; +pub mod invoice; pub mod keys; pub mod mint; pub mod proof; @@ -15,6 +16,7 @@ pub mod wallet; // Re-export all types for convenient access pub use amount::*; +pub use invoice::*; pub use keys::*; pub use mint::*; pub use proof::*; diff --git a/crates/cdk/src/invoice.rs b/crates/cdk/src/invoice.rs new file mode 100644 index 000000000..ff9e4badb --- /dev/null +++ b/crates/cdk/src/invoice.rs @@ -0,0 +1,129 @@ +//! Invoice and offer decoding utilities +//! +//! Provides standalone functions to decode bolt11 invoices and bolt12 offers +//! without requiring a wallet instance or creating melt quotes. + +use std::str::FromStr; + +use lightning::offers::offer::Offer; +use lightning_invoice::Bolt11Invoice; + +use crate::error::Error; + +/// Type of Lightning payment request +#[derive(Debug, Clone, PartialEq, Eq, Hash)] +pub enum PaymentType { + /// Bolt11 invoice + Bolt11, + /// Bolt12 offer + Bolt12, +} + +/// Decoded invoice or offer information +#[derive(Debug, Clone)] +pub struct DecodedInvoice { + /// Type of payment request (Bolt11 or Bolt12) + pub payment_type: PaymentType, + /// Amount in millisatoshis, if specified + pub amount_msat: Option, + /// Expiry timestamp (Unix timestamp), if specified + pub expiry: Option, + /// Description or offer description, if specified + pub description: Option, +} + +/// Decode a bolt11 invoice or bolt12 offer from a string +/// +/// This function attempts to parse the input as a bolt11 invoice first, +/// then as a bolt12 offer if bolt11 parsing fails. +/// +/// # Arguments +/// +/// * `invoice_str` - The invoice or offer string to decode +/// +/// # Returns +/// +/// * `Ok(DecodedInvoice)` - Successfully decoded invoice/offer information +/// * `Err(Error)` - Failed to parse as either bolt11 or bolt12 +/// +/// # Example +/// +/// ```ignore +/// let decoded = decode_invoice("lnbc...")?; +/// match decoded.payment_type { +/// PaymentType::Bolt11 => println!("Bolt11 invoice"), +/// PaymentType::Bolt12 => println!("Bolt12 offer"), +/// } +/// ``` +pub fn decode_invoice(invoice_str: &str) -> Result { + // Try to parse as Bolt11 first + if let Ok(invoice) = Bolt11Invoice::from_str(invoice_str) { + let amount_msat = invoice.amount_milli_satoshis(); + + let expiry = invoice.expires_at().map(|duration| duration.as_secs()); + + let description = match invoice.description() { + lightning_invoice::Bolt11InvoiceDescriptionRef::Direct(desc) => Some(desc.to_string()), + lightning_invoice::Bolt11InvoiceDescriptionRef::Hash(hash) => { + Some(format!("Hash: {}", hash.0)) + } + }; + + return Ok(DecodedInvoice { + payment_type: PaymentType::Bolt11, + amount_msat, + expiry, + description, + }); + } + + // Try to parse as Bolt12 + if let Ok(offer) = Offer::from_str(invoice_str) { + let amount_msat = offer.amount().and_then(|amount| { + // Bolt12 amounts can be in different currencies + // For now, we only extract if it's in Bitcoin (millisatoshis) + match amount { + lightning::offers::offer::Amount::Bitcoin { amount_msats } => Some(amount_msats), + _ => None, + } + }); + + let expiry = offer.absolute_expiry().map(|duration| duration.as_secs()); + + let description = offer.description().map(|d| d.to_string()); + + return Ok(DecodedInvoice { + payment_type: PaymentType::Bolt12, + amount_msat, + expiry, + description, + }); + } + + // If both parsing attempts failed + Err(Error::InvalidInvoice) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn test_decode_bolt11() { + // This is a valid bolt11 invoice for 100 sats + let bolt11 = "lnbc1u1p53kkd9pp5ve8pd9zr60yjyvs6tn77mndavzrl5lwd2gx5hk934f6q8jwguzgsdqqcqzzsxqyz5vqrzjqvueefmrckfdwyyu39m0lf24sqzcr9vcrmxrvgfn6empxz7phrjxvrttncqq0lcqqyqqqqlgqqqqqqgq2qsp5482y73fxmlvg4t66nupdaph93h7dcmfsg2ud72wajf0cpk3a96rq9qxpqysgqujexd0l89u5dutn8hxnsec0c7jrt8wz0z67rut0eah0g7p6zhycn2vff0ts5vwn2h93kx8zzqy3tzu4gfhkya2zpdmqelg0ceqnjztcqma65pr"; + + let result = decode_invoice(bolt11); + assert!(result.is_ok()); + + let decoded = result.unwrap(); + assert_eq!(decoded.payment_type, PaymentType::Bolt11); + assert_eq!(decoded.amount_msat, Some(100000)); + } + + #[test] + fn test_invalid_invoice() { + let result = decode_invoice("invalid_string"); + assert!(result.is_err()); + } +} diff --git a/crates/cdk/src/lib.rs b/crates/cdk/src/lib.rs index 5cf104051..7f60f2132 100644 --- a/crates/cdk/src/lib.rs +++ b/crates/cdk/src/lib.rs @@ -51,6 +51,7 @@ pub use oidc_client::OidcClient; #[cfg(any(feature = "wallet", feature = "mint"))] pub mod event; pub mod fees; +pub mod invoice; #[doc(hidden)] pub use bitcoin::secp256k1; diff --git a/crates/cdk/src/mint/melt/tests/htlc_sigall_spending_conditions_tests.rs b/crates/cdk/src/mint/melt/tests/htlc_sigall_spending_conditions_tests.rs index fafaf309a..9d5c49118 100644 --- a/crates/cdk/src/mint/melt/tests/htlc_sigall_spending_conditions_tests.rs +++ b/crates/cdk/src/mint/melt/tests/htlc_sigall_spending_conditions_tests.rs @@ -8,8 +8,7 @@ use std::str::FromStr; use cdk_common::dhke::construct_proofs; use cdk_common::melt::MeltQuoteRequest; use cdk_common::nuts::{Conditions, SigFlag, SpendingConditions}; -use cdk_common::Amount; -use cdk_common::SpendingConditionVerification; +use cdk_common::{Amount, SpendingConditionVerification}; use crate::test_helpers::nut10::{ create_test_hash_and_preimage, create_test_keypair, unzip3, TestMintHelper, diff --git a/crates/cdk/src/mint/melt/tests/htlc_spending_conditions_tests.rs b/crates/cdk/src/mint/melt/tests/htlc_spending_conditions_tests.rs index 8072187b3..85c54f362 100644 --- a/crates/cdk/src/mint/melt/tests/htlc_spending_conditions_tests.rs +++ b/crates/cdk/src/mint/melt/tests/htlc_spending_conditions_tests.rs @@ -96,8 +96,9 @@ async fn test_htlc_requiring_preimage_and_one_signature() { ); // Step 6: Create a real melt quote that we'll use for all tests - use cdk_common::SpendingConditionVerification; use std::str::FromStr; + + use cdk_common::SpendingConditionVerification; let bolt11_str = "lnbc100n1pnvpufspp5djn8hrq49r8cghwye9kqw752qjncwyfnrprhprpqk43mwcy4yfsqdq5g9kxy7fqd9h8vmmfvdjscqzzsxqyz5vqsp5uhpjt36rj75pl7jq2sshaukzfkt7uulj456s4mh7uy7l6vx7lvxs9qxpqysgqedwz08acmqwtk8g4vkwm2w78suwt2qyzz6jkkwcgrjm3r3hs6fskyhvud4fan3keru7emjm8ygqpcrwtlmhfjfmer3afs5hhwamgr4cqtactdq"; let bolt11 = cdk_common::Bolt11Invoice::from_str(bolt11_str).unwrap(); diff --git a/crates/cdk/src/mint/melt/tests/locktime_spending_conditions_tests.rs b/crates/cdk/src/mint/melt/tests/locktime_spending_conditions_tests.rs index 1fcfb524d..9e2a5e4b8 100644 --- a/crates/cdk/src/mint/melt/tests/locktime_spending_conditions_tests.rs +++ b/crates/cdk/src/mint/melt/tests/locktime_spending_conditions_tests.rs @@ -8,8 +8,7 @@ use std::str::FromStr; use cdk_common::dhke::construct_proofs; use cdk_common::melt::MeltQuoteRequest; use cdk_common::nuts::{Conditions, SigFlag, SpendingConditions}; -use cdk_common::Amount; -use cdk_common::SpendingConditionVerification; +use cdk_common::{Amount, SpendingConditionVerification}; use crate::test_helpers::nut10::{create_test_keypair, unzip3, TestMintHelper}; use crate::util::unix_time; diff --git a/crates/cdk/src/mint/melt/tests/p2pk_sigall_spending_conditions_tests.rs b/crates/cdk/src/mint/melt/tests/p2pk_sigall_spending_conditions_tests.rs index 5cc2ef7e8..670fde238 100644 --- a/crates/cdk/src/mint/melt/tests/p2pk_sigall_spending_conditions_tests.rs +++ b/crates/cdk/src/mint/melt/tests/p2pk_sigall_spending_conditions_tests.rs @@ -90,8 +90,9 @@ async fn test_p2pk_sig_all_requires_transaction_signature() { ); // Step 5: Create a real melt quote that we'll use for all tests - use cdk_common::SpendingConditionVerification; use std::str::FromStr; + + use cdk_common::SpendingConditionVerification; let bolt11_str = "lnbc100n1pnvpufspp5djn8hrq49r8cghwye9kqw752qjncwyfnrprhprpqk43mwcy4yfsqdq5g9kxy7fqd9h8vmmfvdjscqzzsxqyz5vqsp5uhpjt36rj75pl7jq2sshaukzfkt7uulj456s4mh7uy7l6vx7lvxs9qxpqysgqedwz08acmqwtk8g4vkwm2w78suwt2qyzz6jkkwcgrjm3r3hs6fskyhvud4fan3keru7emjm8ygqpcrwtlmhfjfmer3afs5hhwamgr4cqtactdq"; let bolt11 = cdk_common::Bolt11Invoice::from_str(bolt11_str).unwrap(); diff --git a/crates/cdk/src/mint/melt/tests/p2pk_spending_conditions_tests.rs b/crates/cdk/src/mint/melt/tests/p2pk_spending_conditions_tests.rs index 0a8bc3c8e..1065029c7 100644 --- a/crates/cdk/src/mint/melt/tests/p2pk_spending_conditions_tests.rs +++ b/crates/cdk/src/mint/melt/tests/p2pk_spending_conditions_tests.rs @@ -8,8 +8,7 @@ use std::str::FromStr; use cdk_common::dhke::construct_proofs; use cdk_common::melt::MeltQuoteRequest; use cdk_common::nuts::SpendingConditions; -use cdk_common::Amount; -use cdk_common::SpendingConditionVerification; +use cdk_common::{Amount, SpendingConditionVerification}; use crate::test_helpers::nut10::{create_test_keypair, unzip3, TestMintHelper}; diff --git a/crates/cdk/src/mint/swap/mod.rs b/crates/cdk/src/mint/swap/mod.rs index 073fbbebe..a1dd9f5b4 100644 --- a/crates/cdk/src/mint/swap/mod.rs +++ b/crates/cdk/src/mint/swap/mod.rs @@ -1,3 +1,4 @@ +use cdk_common::SpendingConditionVerification; #[cfg(feature = "prometheus")] use cdk_prometheus::METRICS; use swap_saga::SwapSaga; @@ -5,7 +6,6 @@ use tracing::instrument; use super::{Mint, SwapRequest, SwapResponse}; use crate::Error; -use cdk_common::SpendingConditionVerification; pub mod swap_saga; diff --git a/crates/cdk/src/mint/swap/tests/p2pk_sigall_spending_conditions_tests.rs b/crates/cdk/src/mint/swap/tests/p2pk_sigall_spending_conditions_tests.rs index 7a385af3d..ebb63969f 100644 --- a/crates/cdk/src/mint/swap/tests/p2pk_sigall_spending_conditions_tests.rs +++ b/crates/cdk/src/mint/swap/tests/p2pk_sigall_spending_conditions_tests.rs @@ -2,13 +2,13 @@ //! //! These tests verify that the mint correctly enforces SIG_ALL flag behavior -use crate::util::unix_time; use cdk_common::dhke::construct_proofs; use cdk_common::nuts::{Conditions, SigFlag, SpendingConditions}; use cdk_common::Amount; use crate::test_helpers::mint::create_test_blinded_messages; use crate::test_helpers::nut10::{create_test_keypair, unzip3, TestMintHelper}; +use crate::util::unix_time; /// Test: P2PK with SIG_ALL flag requires transaction signature /// diff --git a/crates/cdk/src/mint/swap/tests/p2pk_spending_conditions_tests.rs b/crates/cdk/src/mint/swap/tests/p2pk_spending_conditions_tests.rs index 5c660a582..c6d8741f1 100644 --- a/crates/cdk/src/mint/swap/tests/p2pk_spending_conditions_tests.rs +++ b/crates/cdk/src/mint/swap/tests/p2pk_spending_conditions_tests.rs @@ -8,13 +8,13 @@ //! - Refund keys //! - Signature validation -use crate::util::unix_time; use cdk_common::dhke::construct_proofs; use cdk_common::nuts::{Conditions, SigFlag, SpendingConditions}; use cdk_common::Amount; use crate::test_helpers::mint::create_test_blinded_messages; use crate::test_helpers::nut10::{create_test_keypair, unzip3, TestMintHelper}; +use crate::util::unix_time; /// Test: P2PK with single pubkey requires all proofs signed /// diff --git a/crates/cdk/src/test_helpers/nut10.rs b/crates/cdk/src/test_helpers/nut10.rs index dcc8cf21c..c4363096d 100644 --- a/crates/cdk/src/test_helpers/nut10.rs +++ b/crates/cdk/src/test_helpers/nut10.rs @@ -1,9 +1,6 @@ #![cfg(test)] //! Shared test helpers for spending condition tests (P2PK, HTLC, etc.) -use crate::mint::Mint; -use crate::secret::Secret; -use crate::Error; use cdk_common::dhke::blind_message; use cdk_common::nuts::nut10::Secret as Nut10Secret; use cdk_common::nuts::{ @@ -11,7 +8,10 @@ use cdk_common::nuts::{ }; use cdk_common::Amount; +use crate::mint::Mint; +use crate::secret::Secret; use crate::test_helpers::mint::{create_test_mint, mint_test_proofs}; +use crate::Error; /// Test mint wrapper with convenient access to common keyset info pub struct TestMintHelper { From ee910578ab458a2051b219ab25a4c351308a4441 Mon Sep 17 00:00:00 2001 From: tsk Date: Mon, 17 Nov 2025 22:23:29 +0000 Subject: [PATCH 279/321] fix: nightly ci (#1298) --- .github/workflows/nightly-rustfmt.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/nightly-rustfmt.yml b/.github/workflows/nightly-rustfmt.yml index b9ba334e1..c852930f6 100644 --- a/.github/workflows/nightly-rustfmt.yml +++ b/.github/workflows/nightly-rustfmt.yml @@ -41,7 +41,7 @@ jobs: cargo fmt ' # Manually remove trailing whitespace - git ls-files -- '*.rs' -z | xargs -0 sed -E -i'' -e 's/[[:space:]]+$//' + find . -name '*.rs' -type f -exec sed -E -i 's/[[:space:]]+$//' {} + - name: Get the current date run: echo "date=$(date +'%Y-%m-%d')" >> $GITHUB_ENV - name: Create Pull Request From ccb84efe6c42e5b32aed5240923d170b1223de9e Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Mon, 17 Nov 2025 23:21:01 +0000 Subject: [PATCH 280/321] chore: fix nightly pr --- .github/workflows/nightly-rustfmt.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/nightly-rustfmt.yml b/.github/workflows/nightly-rustfmt.yml index c852930f6..767232e7e 100644 --- a/.github/workflows/nightly-rustfmt.yml +++ b/.github/workflows/nightly-rustfmt.yml @@ -46,6 +46,8 @@ jobs: run: echo "date=$(date +'%Y-%m-%d')" >> $GITHUB_ENV - name: Create Pull Request uses: peter-evans/create-pull-request@271a8d0340265f705b14b6d32b9829c1cb33d45e # v7.0.8 + env: + PRE_COMMIT_ALLOW_NO_CONFIG: 1 with: token: ${{ secrets.BACKPORT_TOKEN }} author: Fmt Bot From 288be4a3779664a37159f8afe5c4618cf8daee78 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Mon, 17 Nov 2025 23:32:54 +0000 Subject: [PATCH 281/321] fix: nightly fmt pr --- .github/workflows/nightly-rustfmt.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/.github/workflows/nightly-rustfmt.yml b/.github/workflows/nightly-rustfmt.yml index 767232e7e..35b7020de 100644 --- a/.github/workflows/nightly-rustfmt.yml +++ b/.github/workflows/nightly-rustfmt.yml @@ -17,8 +17,6 @@ jobs: - uses: actions/checkout@v4 with: ref: main - persist-credentials: false - token: ${{ secrets.BACKPORT_TOKEN }} - name: Get flake hash id: flake-hash run: echo "hash=$(sha256sum flake.lock | cut -d' ' -f1 | cut -c1-8)" >> $GITHUB_OUTPUT From 36c6037442fd58c7af8aac10c3e5c133eb082797 Mon Sep 17 00:00:00 2001 From: tsk Date: Tue, 18 Nov 2025 09:37:29 +0000 Subject: [PATCH 282/321] fix: allow starting insecure man server (#1297) --- crates/cdk-mintd/src/lib.rs | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/crates/cdk-mintd/src/lib.rs b/crates/cdk-mintd/src/lib.rs index 4366a3874..8b7514c1a 100644 --- a/crates/cdk-mintd/src/lib.rs +++ b/crates/cdk-mintd/src/lib.rs @@ -886,12 +886,17 @@ async fn start_services_with_shutdown( let tls_dir = rpc_settings.tls_dir_path.unwrap_or(work_dir.join("tls")); - if !tls_dir.exists() { - tracing::error!("TLS directory does not exist: {}", tls_dir.display()); - bail!("Cannot start RPC server: TLS directory does not exist"); - } + let tls_dir = if tls_dir.exists() { + Some(tls_dir) + } else { + tracing::warn!( + "TLS directory does not exist: {}. Starting RPC server in INSECURE mode without TLS encryption", + tls_dir.display() + ); + None + }; - mint_rpc.start(Some(tls_dir)).await?; + mint_rpc.start(tls_dir).await?; rpc_server = Some(mint_rpc); From a12fd4dbeae83079e88c0f3cec776d7f44056792 Mon Sep 17 00:00:00 2001 From: C Date: Tue, 18 Nov 2025 07:12:19 -0300 Subject: [PATCH 283/321] Prevent database contention in metadata cache load operations (#1300) * refactor(cdk/wallet): prevent database contention in metadata cache load operations Refactors mint metadata cache to eliminate database reads during active transactions by extracting database loading into a separate `load_from_storage` method that runs independently at wallet initialization. Previously, `load()` would read from storage during transaction execution, causing database contention with concurrent wallet operations. The new approach: - Introduces `load_from_storage` method that loads mint info and keysets from storage upfront - Spawns an async task during wallet initialization to populate the cache from storage - Removes all storage reads from the `load()` and `load_auth()` methods - Ensures storage is only used to sync data back, never for reading during load operations This prevents transaction conflicts and improves concurrent operation performance by ensuring the metadata cache operates independently of ongoing database transactions. --- crates/cdk/src/wallet/builder.rs | 12 +++ crates/cdk/src/wallet/mint_metadata_cache.rs | 89 +++++++++++++------- 2 files changed, 70 insertions(+), 31 deletions(-) diff --git a/crates/cdk/src/wallet/builder.rs b/crates/cdk/src/wallet/builder.rs index 557ace25a..c3991b1ab 100644 --- a/crates/cdk/src/wallet/builder.rs +++ b/crates/cdk/src/wallet/builder.rs @@ -4,6 +4,7 @@ use std::time::Duration; use cdk_common::database; use cdk_common::parking_lot::RwLock; +use cdk_common::task::spawn; #[cfg(feature = "auth")] use cdk_common::AuthToken; #[cfg(feature = "auth")] @@ -223,6 +224,17 @@ impl WalletBuilder { } }); + let metadata_for_loader = metadata_cache.clone(); + let localstore_for_loader = localstore.clone(); + spawn(async move { + let _ = metadata_for_loader + .load_from_storage(&localstore_for_loader) + .await + .inspect_err(|err| { + tracing::warn!("Failed to load mint metadata from storage {err}"); + }); + }); + Ok(Wallet { mint_url, unit, diff --git a/crates/cdk/src/wallet/mint_metadata_cache.rs b/crates/cdk/src/wallet/mint_metadata_cache.rs index 122f7f1d6..34367968d 100644 --- a/crates/cdk/src/wallet/mint_metadata_cache.rs +++ b/crates/cdk/src/wallet/mint_metadata_cache.rs @@ -243,20 +243,6 @@ impl MintMetadataCache { return Ok(current_metadata); } - // Load keys from database before fetching from HTTP - // This prevents re-fetching keys we already have and avoids duplicate insertions - if let Some(keysets) = storage.get_mint_keysets(self.mint_url.clone()).await? { - let mut updated_metadata = (*self.metadata.load().clone()).clone(); - for keyset_info in keysets { - if let Some(keys) = storage.get_keys(&keyset_info.id).await? { - tracing::trace!("Loaded keys for keyset {} from database", keyset_info.id); - updated_metadata.keys.insert(keyset_info.id, Arc::new(keys)); - } - } - // Update cache with database keys before HTTP fetch - self.metadata.store(Arc::new(updated_metadata)); - } - // Perform the fetch #[cfg(feature = "auth")] let metadata = self.fetch_from_http(Some(client), None).await?; @@ -331,6 +317,64 @@ impl MintMetadataCache { self.load_from_mint(storage, client).await } + /// Load mint info and keys from storage. + /// + /// This function should be called without any competing transaction with the storage. + pub async fn load_from_storage( + &self, + storage: &Arc + Send + Sync>, + ) -> Result<(), Error> { + // Load keys from database before fetching from HTTP + // This prevents re-fetching keys we already have and avoids duplicate insertions + let mut updated_metadata = (*self.metadata.load().clone()).clone(); + + updated_metadata.mint_info = storage + .get_mint(self.mint_url.clone()) + .await? + .ok_or(Error::UnknownKeySet)?; + + let keysets = storage + .get_mint_keysets(self.mint_url.clone()) + .await? + .ok_or(Error::UnknownKeySet)? + .into_iter() + .map(Arc::new) + .collect::>(); + + for keyset_info in keysets.iter() { + if let Some(keys) = storage.get_keys(&keyset_info.id).await? { + tracing::trace!( + "Loaded keys for keyset {} from database (auth)", + keyset_info.id + ); + updated_metadata.keys.insert(keyset_info.id, Arc::new(keys)); + } + if keyset_info.active { + updated_metadata.active_keysets.push(keyset_info.clone()); + } + } + + updated_metadata.keysets = keysets + .into_iter() + .map(|keyset| (keyset.id, keyset)) + .collect(); + updated_metadata.status.is_populated = true; + updated_metadata.status.version += 1; + updated_metadata.status.updated_at = Instant::now(); + + #[cfg(feature = "auth")] + { + updated_metadata.auth_status.is_populated = true; + updated_metadata.auth_status.updated_at = Instant::now(); + updated_metadata.auth_status.version += 1; + } + + // Update cache with database keys before HTTP fetch + self.metadata.store(Arc::new(updated_metadata)); + + Ok(()) + } + /// Load auth keysets and keys (auth feature only) /// /// Fetches blind authentication keysets from the mint. Always performs @@ -385,23 +429,6 @@ impl MintMetadataCache { return Ok(current_metadata); } - // Load keys from database before fetching from HTTP - // This prevents re-fetching keys we already have and avoids duplicate insertions - if let Some(keysets) = storage.get_mint_keysets(self.mint_url.clone()).await? { - let mut updated_metadata = (*self.metadata.load().clone()).clone(); - for keyset_info in keysets { - if let Some(keys) = storage.get_keys(&keyset_info.id).await? { - tracing::trace!( - "Loaded keys for keyset {} from database (auth)", - keyset_info.id - ); - updated_metadata.keys.insert(keyset_info.id, Arc::new(keys)); - } - } - // Update cache with database keys before HTTP fetch - self.metadata.store(Arc::new(updated_metadata)); - } - // Auth data not in cache - fetch from mint let metadata = self.fetch_from_http(None, Some(auth_client)).await?; From 141e62a8dc124267f0c04128cc3441cdf8b0d211 Mon Sep 17 00:00:00 2001 From: tsk Date: Tue, 18 Nov 2025 12:27:00 +0000 Subject: [PATCH 284/321] feat(cdk): add Lightning address support with BIP353 fallback (#1295) * feat(cdk): add Lightning address support with BIP353 fallback Implements Lightning address (user@domain.com) resolution for melt operations with automatic fallback mechanism. When BIP353 DNS resolution fails, the wallet now falls back to LNURL-pay Lightning address resolution. Key additions: - New lightning_address module with LNURL-pay protocol implementation - melt_lightning_address and melt_human_readable_address methods - MintConnector trait methods for LNURL HTTP requests - BIP353 error variant for DNS resolution failures - Integration tests and FFI bindings --- crates/cdk-common/src/error.rs | 7 + crates/cdk-ffi/src/wallet.rs | 39 +++ .../src/init_pure_tests.rs | 14 + crates/cdk/Cargo.toml | 4 + crates/cdk/examples/human_readable_payment.rs | 300 ++++++++++++++++++ crates/cdk/src/lib.rs | 3 + crates/cdk/src/lightning_address.rs | 238 ++++++++++++++ .../src/wallet/melt/melt_lightning_address.rs | 90 ++++++ crates/cdk/src/wallet/melt/mod.rs | 63 ++++ .../src/wallet/mint_connector/http_client.rs | 22 ++ crates/cdk/src/wallet/mint_connector/mod.rs | 14 + crates/cdk/src/wallet/mod.rs | 2 +- 12 files changed, 795 insertions(+), 1 deletion(-) create mode 100644 crates/cdk/examples/human_readable_payment.rs create mode 100644 crates/cdk/src/lightning_address.rs create mode 100644 crates/cdk/src/wallet/melt/melt_lightning_address.rs diff --git a/crates/cdk-common/src/error.rs b/crates/cdk-common/src/error.rs index 8ef8f4e60..188a0c9ad 100644 --- a/crates/cdk-common/src/error.rs +++ b/crates/cdk-common/src/error.rs @@ -129,6 +129,13 @@ pub enum Error { #[error("No Lightning offer found in BIP353 payment instructions")] Bip353NoLightningOffer, + /// Lightning Address parsing error + #[error("Failed to parse Lightning address: {0}")] + LightningAddressParse(String), + /// Lightning Address request error + #[error("Failed to request invoice from Lightning address service: {0}")] + LightningAddressRequest(String), + /// Internal Error - Send error #[error("Internal send error: {0}")] SendError(String), diff --git a/crates/cdk-ffi/src/wallet.rs b/crates/cdk-ffi/src/wallet.rs index 449aa950b..4543a461a 100644 --- a/crates/cdk-ffi/src/wallet.rs +++ b/crates/cdk-ffi/src/wallet.rs @@ -423,6 +423,45 @@ impl Wallet { .await?; Ok(quote.into()) } + + /// Get a quote for a Lightning address melt + /// + /// This method resolves a Lightning address (e.g., "alice@example.com") to a Lightning invoice + /// and then creates a melt quote for that invoice. + pub async fn melt_lightning_address_quote( + &self, + lightning_address: String, + amount_msat: Amount, + ) -> Result { + let cdk_amount: cdk::Amount = amount_msat.into(); + let quote = self + .inner + .melt_lightning_address_quote(&lightning_address, cdk_amount) + .await?; + Ok(quote.into()) + } + + /// Get a quote for a human-readable address melt + /// + /// This method accepts a human-readable address that could be either a BIP353 address + /// or a Lightning address. It intelligently determines which to try based on mint support: + /// + /// 1. If the mint supports Bolt12, it tries BIP353 first + /// 2. Falls back to Lightning address only if BIP353 DNS resolution fails + /// 3. If BIP353 resolves but fails at the mint, it does NOT fall back to Lightning address + /// 4. If the mint doesn't support Bolt12, it tries Lightning address directly + pub async fn melt_human_readable( + &self, + address: String, + amount_msat: Amount, + ) -> Result { + let cdk_amount: cdk::Amount = amount_msat.into(); + let quote = self + .inner + .melt_human_readable_quote(&address, cdk_amount) + .await?; + Ok(quote.into()) + } } /// Auth methods for Wallet diff --git a/crates/cdk-integration-tests/src/init_pure_tests.rs b/crates/cdk-integration-tests/src/init_pure_tests.rs index 90c88fb37..fc76324e0 100644 --- a/crates/cdk-integration-tests/src/init_pure_tests.rs +++ b/crates/cdk-integration-tests/src/init_pure_tests.rs @@ -59,6 +59,20 @@ impl MintConnector for DirectMintConnection { panic!("Not implemented"); } + async fn fetch_lnurl_pay_request( + &self, + _url: &str, + ) -> Result { + unimplemented!("Lightning address not supported in DirectMintConnection") + } + + async fn fetch_lnurl_invoice( + &self, + _url: &str, + ) -> Result { + unimplemented!("Lightning address not supported in DirectMintConnection") + } + async fn get_mint_keys(&self) -> Result, Error> { Ok(self.mint.pubkeys().keysets) } diff --git a/crates/cdk/Cargo.toml b/crates/cdk/Cargo.toml index 6f7c070c3..c8a8d09e5 100644 --- a/crates/cdk/Cargo.toml +++ b/crates/cdk/Cargo.toml @@ -138,6 +138,10 @@ required-features = ["wallet"] name = "mint-token-bolt12" required-features = ["wallet"] +[[example]] +name = "human_readable_payment" +required-features = ["wallet", "bip353"] + [dev-dependencies] rand.workspace = true cdk-sqlite.workspace = true diff --git a/crates/cdk/examples/human_readable_payment.rs b/crates/cdk/examples/human_readable_payment.rs new file mode 100644 index 000000000..69446442c --- /dev/null +++ b/crates/cdk/examples/human_readable_payment.rs @@ -0,0 +1,300 @@ +//! # Human Readable Payment Example +//! +//! This example demonstrates how to use both BIP-353 and Lightning Address (LNURL-pay) +//! with the CDK wallet. Both allow users to share simple email-like addresses instead +//! of complex Bitcoin addresses or Lightning invoices. +//! +//! ## BIP-353 (Bitcoin URI Payment Instructions) +//! +//! BIP-353 uses DNS TXT records to resolve human-readable addresses to BOLT12 offers. +//! 1. Parse a human-readable address like `user@domain.com` +//! 2. Query DNS TXT records at `user.user._bitcoin-payment.domain.com` +//! 3. Extract Lightning offers (BOLT12) from the TXT records +//! 4. Use the offer to create a melt quote +//! +//! ## Lightning Address (LNURL-pay) +//! +//! Lightning Address uses HTTPS to fetch BOLT11 invoices. +//! 1. Parse a Lightning address like `user@domain.com` +//! 2. Query HTTPS endpoint at `https://domain.com/.well-known/lnurlp/user` +//! 3. Get callback URL and amount constraints +//! 4. Request BOLT11 invoice with the specified amount +//! +//! ## Unified API +//! +//! The `melt_human_readable_quote()` method automatically tries BIP-353 first +//! (if the mint supports BOLT12), then falls back to Lightning Address if needed. +//! +//! ## Usage +//! +//! ```bash +//! cargo run --example human_readable_payment --features="wallet bip353" +//! ``` + +use std::sync::Arc; +use std::time::Duration; + +use cdk::amount::SplitTarget; +use cdk::nuts::nut00::ProofsMethods; +use cdk::nuts::CurrencyUnit; +use cdk::wallet::Wallet; +use cdk::Amount; +use cdk_sqlite::wallet::memory; +use rand::random; + +#[tokio::main] +async fn main() -> anyhow::Result<()> { + println!("Human Readable Payment Example"); + println!("================================\n"); + + // Example addresses + let bip353_address = "tsk@thesimplekid.com"; + let lnurl_address = + "npub1qjgcmlpkeyl8mdkvp4s0xls4ytcux6my606tgfx9xttut907h0zs76lgjw@npubx.cash"; + + // Generate a random seed for the wallet + let seed = random::<[u8; 64]>(); + + // Mint URL and currency unit + let mint_url = "https://fake.thesimplekid.dev"; + let unit = CurrencyUnit::Sat; + let initial_amount = Amount::from(2000); // Start with 2000 sats (enough for both payments) + + // Initialize the memory store + let localstore = Arc::new(memory::empty().await?); + + // Create a new wallet + let wallet = Wallet::new(mint_url, unit, localstore, seed, None)?; + + println!("Step 1: Funding the wallet"); + println!("---------------------------"); + + // First, we need to fund the wallet + println!("Requesting mint quote for {} sats...", initial_amount); + let mint_quote = wallet.mint_quote(initial_amount, None).await?; + println!( + "Pay this invoice to fund the wallet:\n{}", + mint_quote.request + ); + println!("\nQuote ID: {}", mint_quote.id); + + // Wait for payment and mint tokens automatically + println!("\nWaiting for payment... (in real use, pay the above invoice)"); + let proofs = wallet + .wait_and_mint_quote( + mint_quote, + SplitTarget::default(), + None, + Duration::from_secs(300), // 5 minutes timeout + ) + .await?; + + let received_amount = proofs.total_amount()?; + println!("✓ Successfully minted {} sats\n", received_amount); + + // ============================================================================ + // Part 1: BIP-353 Payment + // ============================================================================ + + println!("\n╔════════════════════════════════════════════════════════════════╗"); + println!("║ Part 1: BIP-353 Payment (BOLT12 Offer via DNS) ║"); + println!("╚════════════════════════════════════════════════════════════════╝\n"); + + let bip353_amount_sats = 100; // Example: paying 100 sats + println!("BIP-353 Address: {}", bip353_address); + println!("Payment Amount: {} sats", bip353_amount_sats); + println!("\nHow BIP-353 works:"); + println!("1. Parse address into user@domain"); + println!("2. Query DNS TXT records at: tsk.user._bitcoin-payment.thesimplekid.com"); + println!("3. Extract BOLT12 offer from DNS records"); + println!("4. Create melt quote with the offer\n"); + + // Use the specific BIP353 method + println!("Attempting BIP-353 payment..."); + match wallet + .melt_bip353_quote(bip353_address, bip353_amount_sats * 1_000) + .await + { + Ok(melt_quote) => { + println!("✓ BIP-353 melt quote received:"); + println!(" Quote ID: {}", melt_quote.id); + println!(" Amount: {} sats", melt_quote.amount); + println!(" Fee Reserve: {} sats", melt_quote.fee_reserve); + println!(" State: {}", melt_quote.state); + println!(" Payment Method: {}", melt_quote.payment_method); + + // Execute the payment + println!("\nExecuting payment..."); + match wallet.melt(&melt_quote.id).await { + Ok(melt_result) => { + println!("✓ BIP-353 payment successful!"); + println!(" State: {}", melt_result.state); + println!(" Amount paid: {} sats", melt_result.amount); + println!(" Fee paid: {} sats", melt_result.fee_paid); + + if let Some(preimage) = melt_result.preimage { + println!(" Payment preimage: {}", preimage); + } + } + Err(e) => { + println!("✗ BIP-353 payment failed: {}", e); + } + } + } + Err(e) => { + println!("✗ Failed to get BIP-353 melt quote: {}", e); + println!("\nPossible reasons:"); + println!(" • DNS resolution failed or no DNS records found"); + println!(" • No Lightning offer (BOLT12) in DNS TXT records"); + println!(" • DNSSEC validation failed"); + println!(" • Mint doesn't support BOLT12"); + println!(" • Network connectivity issues"); + } + } + + // ============================================================================ + // Part 2: Lightning Address (LNURL-pay) Payment + // ============================================================================ + + println!("\n\n╔════════════════════════════════════════════════════════════════╗"); + println!("║ Part 2: Lightning Address Payment (BOLT11 via LNURL-pay) ║"); + println!("╚════════════════════════════════════════════════════════════════╝\n"); + + let lnurl_amount_sats = 100; // Example: paying 100 sats + println!("Lightning Address: {}", lnurl_address); + println!("Payment Amount: {} sats", lnurl_amount_sats); + println!("\nHow Lightning Address works:"); + println!("1. Parse address into user@domain"); + println!("2. Query HTTPS: https://npubx.cash/.well-known/lnurlp/npub1qj..."); + println!("3. Get callback URL and amount constraints"); + println!("4. Request BOLT11 invoice for the amount"); + println!("5. Create melt quote with the invoice\n"); + + // Use the specific Lightning Address method + println!("Attempting Lightning Address payment..."); + match wallet + .melt_lightning_address_quote(lnurl_address, lnurl_amount_sats * 1_000) + .await + { + Ok(melt_quote) => { + println!("✓ Lightning Address melt quote received:"); + println!(" Quote ID: {}", melt_quote.id); + println!(" Amount: {} sats", melt_quote.amount); + println!(" Fee Reserve: {} sats", melt_quote.fee_reserve); + println!(" State: {}", melt_quote.state); + println!(" Payment Method: {}", melt_quote.payment_method); + + // Execute the payment + println!("\nExecuting payment..."); + match wallet.melt(&melt_quote.id).await { + Ok(melt_result) => { + println!("✓ Lightning Address payment successful!"); + println!(" State: {}", melt_result.state); + println!(" Amount paid: {} sats", melt_result.amount); + println!(" Fee paid: {} sats", melt_result.fee_paid); + + if let Some(preimage) = melt_result.preimage { + println!(" Payment preimage: {}", preimage); + } + } + Err(e) => { + println!("✗ Lightning Address payment failed: {}", e); + } + } + } + Err(e) => { + println!("✗ Failed to get Lightning Address melt quote: {}", e); + println!("\nPossible reasons:"); + println!(" • HTTPS request to .well-known/lnurlp failed"); + println!(" • Invalid Lightning Address format"); + println!(" • Amount outside min/max constraints"); + println!(" • Service unavailable or network issues"); + } + } + + // ============================================================================ + // Part 3: Unified Human Readable API (Smart Fallback) + // ============================================================================ + + println!("\n\n╔════════════════════════════════════════════════════════════════╗"); + println!("║ Part 3: Unified API (Automatic BIP-353 → LNURL Fallback) ║"); + println!("╚════════════════════════════════════════════════════════════════╝\n"); + + println!("The `melt_human_readable_quote()` method intelligently chooses:"); + println!("1. If mint supports BOLT12 AND address has BIP-353 DNS: Use BIP-353"); + println!("2. If BIP-353 DNS fails OR address has no DNS: Fall back to LNURL"); + println!("3. If mint doesn't support BOLT12: Use LNURL directly\n"); + + // Test 1: Address with BIP-353 support (has DNS records) + let unified_amount_sats = 50; + println!("Test 1: Address with BIP-353 DNS support"); + println!("Address: {}", bip353_address); + println!("Payment Amount: {} sats", unified_amount_sats); + println!("Expected: BIP-353 (BOLT12) via DNS resolution\n"); + + println!("Attempting unified payment..."); + match wallet + .melt_human_readable_quote(bip353_address, unified_amount_sats * 1_000) + .await + { + Ok(melt_quote) => { + println!("✓ Unified melt quote received:"); + println!(" Quote ID: {}", melt_quote.id); + println!(" Amount: {} sats", melt_quote.amount); + println!(" Fee Reserve: {} sats", melt_quote.fee_reserve); + println!(" Payment Method: {}", melt_quote.payment_method); + + let method_str = melt_quote.payment_method.to_string().to_lowercase(); + let used_method = if method_str.contains("bolt12") { + "BIP-353 (BOLT12)" + } else if method_str.contains("bolt11") { + "Lightning Address (LNURL-pay)" + } else { + "Unknown method" + }; + println!("\n → Used: {}", used_method); + } + Err(e) => { + println!("✗ Failed to get unified melt quote: {}", e); + println!(" Both BIP-353 and Lightning Address resolution failed"); + } + } + + // Test 2: Address without BIP-353 support (LNURL only) + println!("\n\nTest 2: Address without BIP-353 (LNURL-only)"); + println!("Address: {}", lnurl_address); + println!("Payment Amount: {} sats", unified_amount_sats); + println!("Expected: Lightning Address (LNURL-pay) fallback\n"); + + println!("Attempting unified payment..."); + match wallet + .melt_human_readable_quote(lnurl_address, unified_amount_sats * 1_000) + .await + { + Ok(melt_quote) => { + println!("✓ Unified melt quote received:"); + println!(" Quote ID: {}", melt_quote.id); + println!(" Amount: {} sats", melt_quote.amount); + println!(" Fee Reserve: {} sats", melt_quote.fee_reserve); + println!(" Payment Method: {}", melt_quote.payment_method); + + let method_str = melt_quote.payment_method.to_string().to_lowercase(); + let used_method = if method_str.contains("bolt12") { + "BIP-353 (BOLT12)" + } else if method_str.contains("bolt11") { + "Lightning Address (LNURL-pay)" + } else { + "Unknown method" + }; + println!("\n → Used: {}", used_method); + println!("\n Note: This address doesn't have BIP-353 DNS records,"); + println!(" so it automatically fell back to LNURL-pay."); + } + Err(e) => { + println!("✗ Failed to get unified melt quote: {}", e); + println!(" Both BIP-353 and Lightning Address resolution failed"); + } + } + + Ok(()) +} diff --git a/crates/cdk/src/lib.rs b/crates/cdk/src/lib.rs index 7f60f2132..3493e74cf 100644 --- a/crates/cdk/src/lib.rs +++ b/crates/cdk/src/lib.rs @@ -32,6 +32,9 @@ mod test_helpers; #[cfg(all(feature = "bip353", not(target_arch = "wasm32")))] mod bip353; +#[cfg(feature = "wallet")] +mod lightning_address; + #[cfg(all(any(feature = "wallet", feature = "mint"), feature = "auth"))] mod oidc_client; diff --git a/crates/cdk/src/lightning_address.rs b/crates/cdk/src/lightning_address.rs new file mode 100644 index 000000000..8ec01b5b5 --- /dev/null +++ b/crates/cdk/src/lightning_address.rs @@ -0,0 +1,238 @@ +//! Lightning Address Implementation +//! +//! This module provides functionality for resolving Lightning addresses +//! to obtain Lightning invoices. Lightning addresses are user-friendly +//! identifiers that look like email addresses (e.g., user@domain.com). +//! +//! Lightning addresses are converted to LNURL-pay endpoints following the spec: +//! + +use std::str::FromStr; +use std::sync::Arc; + +use lightning_invoice::Bolt11Invoice; +use serde::{Deserialize, Serialize}; +use thiserror::Error; +use tracing::instrument; +use url::Url; + +use crate::wallet::MintConnector; +use crate::Amount; + +/// Lightning Address Error +#[derive(Debug, Error)] +pub enum Error { + /// Invalid Lightning address format + #[error("Invalid Lightning address format: {0}")] + InvalidFormat(String), + /// Invalid URL + #[error("Invalid URL: {0}")] + InvalidUrl(#[from] url::ParseError), + /// Failed to fetch pay request data + #[error("Failed to fetch pay request data: {0}")] + FetchPayRequest(#[from] crate::Error), + /// Lightning address service error + #[error("Lightning address service error: {0}")] + Service(String), + /// Amount below minimum + #[error("Amount {amount} msat is below minimum {min} msat")] + AmountBelowMinimum { amount: u64, min: u64 }, + /// Amount above maximum + #[error("Amount {amount} msat is above maximum {max} msat")] + AmountAboveMaximum { amount: u64, max: u64 }, + /// No invoice in response + #[error("No invoice in response")] + NoInvoice, + /// Failed to parse invoice + #[error("Failed to parse invoice: {0}")] + InvoiceParse(String), +} + +/// Lightning address - represents a user@domain.com address +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct LightningAddress { + /// The user part of the address (before @) + user: String, + /// The domain part of the address (after @) + domain: String, +} + +impl LightningAddress { + /// Convert the Lightning address to an HTTPS URL for the LNURL-pay endpoint + fn to_url(&self) -> Result { + // Lightning address spec: https://domain.com/.well-known/lnurlp/user + let url_str = format!("https://{}/.well-known/lnurlp/{}", self.domain, self.user); + Ok(Url::parse(&url_str)?) + } + + /// Fetch the LNURL-pay metadata from the service + #[instrument(skip(client))] + async fn fetch_pay_request_data( + &self, + client: &Arc, + ) -> Result { + let url = self.to_url()?; + + tracing::debug!("Fetching Lightning address pay data from: {}", url); + + // Make HTTP GET request to fetch the pay request data + let lnurl_response = client.fetch_lnurl_pay_request(url.as_str()).await?; + + // Validate the response + if let Some(ref reason) = lnurl_response.reason { + return Err(Error::Service(reason.clone())); + } + + Ok(lnurl_response) + } + + /// Request an invoice from the Lightning address service with a specific amount + #[instrument(skip(client))] + pub(crate) async fn request_invoice( + &self, + client: &Arc, + amount_msat: Amount, + ) -> Result { + let pay_data = self.fetch_pay_request_data(client).await?; + + // Validate amount is within acceptable range + let amount_msat_u64: u64 = amount_msat.into(); + if amount_msat_u64 < pay_data.min_sendable { + return Err(Error::AmountBelowMinimum { + amount: amount_msat_u64, + min: pay_data.min_sendable, + }); + } + if amount_msat_u64 > pay_data.max_sendable { + return Err(Error::AmountAboveMaximum { + amount: amount_msat_u64, + max: pay_data.max_sendable, + }); + } + + // Build callback URL with amount parameter + let mut callback_url = Url::parse(&pay_data.callback)?; + + callback_url + .query_pairs_mut() + .append_pair("amount", &amount_msat_u64.to_string()); + + tracing::debug!("Requesting invoice from callback: {}", callback_url); + + // Fetch the invoice + let invoice_response = client.fetch_lnurl_invoice(callback_url.as_str()).await?; + + // Check for errors + if let Some(ref reason) = invoice_response.reason { + return Err(Error::Service(reason.clone())); + } + + // Parse and return the invoice + let pr = invoice_response.pr.ok_or(Error::NoInvoice)?; + + Bolt11Invoice::from_str(&pr).map_err(|e| Error::InvoiceParse(e.to_string())) + } +} + +impl FromStr for LightningAddress { + type Err = Error; + + fn from_str(s: &str) -> Result { + let trimmed = s.trim(); + + // Parse Lightning address (user@domain) + if !trimmed.contains('@') { + return Err(Error::InvalidFormat("must contain '@'".to_string())); + } + + let parts: Vec<&str> = trimmed.split('@').collect(); + if parts.len() != 2 { + return Err(Error::InvalidFormat("must be user@domain".to_string())); + } + + let user = parts[0].trim(); + let domain = parts[1].trim(); + + if user.is_empty() || domain.is_empty() { + return Err(Error::InvalidFormat( + "user and domain must not be empty".to_string(), + )); + } + + Ok(LightningAddress { + user: user.to_string(), + domain: domain.to_string(), + }) + } +} + +impl std::fmt::Display for LightningAddress { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + write!(f, "{}@{}", self.user, self.domain) + } +} + +/// LNURL-pay response from the initial request +#[derive(Debug, Clone, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct LnurlPayResponse { + /// Callback URL for requesting invoice + pub callback: String, + /// Minimum amount in millisatoshis + #[serde(rename = "minSendable")] + pub min_sendable: u64, + /// Maximum amount in millisatoshis + #[serde(rename = "maxSendable")] + pub max_sendable: u64, + /// Metadata string (JSON stringified) + pub metadata: String, + /// Short description tag (should be "payRequest") + pub tag: Option, + /// Optional error reason + pub reason: Option, +} + +/// LNURL-pay invoice response from the callback +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct LnurlPayInvoiceResponse { + /// The BOLT11 payment request (invoice) + pub pr: Option, + /// Optional success action + pub success_action: Option, + /// Optional routes (deprecated) + pub routes: Option>, + /// Optional error reason + pub reason: Option, +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn test_lightning_address_parsing() { + let addr = LightningAddress::from_str("satoshi@bitcoin.org").unwrap(); + assert_eq!(addr.user, "satoshi"); + assert_eq!(addr.domain, "bitcoin.org"); + assert_eq!(addr.to_string(), "satoshi@bitcoin.org"); + } + + #[test] + fn test_lightning_address_to_url() { + let addr = LightningAddress { + user: "alice".to_string(), + domain: "example.com".to_string(), + }; + + let url = addr.to_url().unwrap(); + assert_eq!(url.as_str(), "https://example.com/.well-known/lnurlp/alice"); + } + + #[test] + fn test_invalid_lightning_address() { + assert!(LightningAddress::from_str("invalid").is_err()); + assert!(LightningAddress::from_str("@example.com").is_err()); + assert!(LightningAddress::from_str("user@").is_err()); + assert!(LightningAddress::from_str("user").is_err()); + } +} diff --git a/crates/cdk/src/wallet/melt/melt_lightning_address.rs b/crates/cdk/src/wallet/melt/melt_lightning_address.rs new file mode 100644 index 000000000..98a7c6023 --- /dev/null +++ b/crates/cdk/src/wallet/melt/melt_lightning_address.rs @@ -0,0 +1,90 @@ +//! Melt Lightning Address +//! +//! Implementation of melt functionality for Lightning addresses + +use std::str::FromStr; + +use cdk_common::wallet::MeltQuote; +use tracing::instrument; + +use crate::lightning_address::LightningAddress; +use crate::{Amount, Error, Wallet}; + +impl Wallet { + /// Melt Quote for Lightning address + /// + /// This method resolves a Lightning address (e.g., "alice@example.com") to a Lightning invoice + /// and then creates a melt quote for that invoice. + /// + /// # Arguments + /// + /// * `lightning_address` - Lightning address in the format "user@domain.com" + /// * `amount_msat` - Amount to pay in millisatoshis + /// + /// # Returns + /// + /// A `MeltQuote` that can be used to execute the payment + /// + /// # Errors + /// + /// This method will return an error if: + /// - The Lightning address format is invalid + /// - HTTP request to the Lightning address service fails + /// - The amount is outside the acceptable range + /// - The service returns an error + /// - The mint fails to provide a quote for the invoice + /// + /// # Example + /// + /// ```rust,no_run + /// use cdk::Amount; + /// # use cdk::Wallet; + /// # async fn example(wallet: Wallet) -> Result<(), cdk::Error> { + /// let quote = wallet + /// .melt_lightning_address_quote("alice@example.com", Amount::from(100_000)) // 100 sats in msat + /// .await?; + /// # Ok(()) + /// # } + /// ``` + #[instrument(skip(self, amount_msat), fields(lightning_address = %lightning_address))] + pub async fn melt_lightning_address_quote( + &self, + lightning_address: &str, + amount_msat: impl Into, + ) -> Result { + let amount = amount_msat.into(); + + // Parse the Lightning address + let ln_address = LightningAddress::from_str(lightning_address).map_err(|e| { + tracing::error!( + "Failed to parse Lightning address '{}': {}", + lightning_address, + e + ); + Error::LightningAddressParse(e.to_string()) + })?; + + tracing::debug!("Resolving Lightning address: {}", ln_address); + + // Request an invoice from the Lightning address service + let invoice = ln_address + .request_invoice(&self.client, amount) + .await + .map_err(|e| { + tracing::error!( + "Failed to get invoice from Lightning address service: {}", + e + ); + Error::LightningAddressRequest(e.to_string()) + })?; + + tracing::debug!( + "Received invoice from Lightning address service: {}", + invoice + ); + + // Create a melt quote for the invoice using the existing bolt11 functionality + // The invoice from LNURL already contains the amount, so we don't need amountless options + self.melt_quote(invoice.to_string(), None).await + } +} diff --git a/crates/cdk/src/wallet/melt/mod.rs b/crates/cdk/src/wallet/melt/mod.rs index c56d18eb4..037d5210c 100644 --- a/crates/cdk/src/wallet/melt/mod.rs +++ b/crates/cdk/src/wallet/melt/mod.rs @@ -11,6 +11,8 @@ use crate::Wallet; mod melt_bip353; mod melt_bolt11; mod melt_bolt12; +#[cfg(feature = "wallet")] +mod melt_lightning_address; impl Wallet { /// Check pending melt quotes @@ -84,4 +86,65 @@ impl Wallet { } Ok(()) } + + /// Get a melt quote for a human-readable address + /// + /// This method accepts a human-readable address that could be either a BIP353 address + /// or a Lightning address. It intelligently determines which to try based on mint support: + /// + /// 1. If the mint supports Bolt12, it tries BIP353 first + /// 2. Falls back to Lightning address only if BIP353 DNS resolution fails + /// 3. If BIP353 resolves but fails at the mint, it does NOT fall back to Lightning address + /// 4. If the mint doesn't support Bolt12, it tries Lightning address directly + #[cfg(all(feature = "bip353", feature = "wallet", not(target_arch = "wasm32")))] + pub async fn melt_human_readable_quote( + &self, + address: &str, + amount_msat: impl Into, + ) -> Result { + use cdk_common::nuts::PaymentMethod; + + let amount = amount_msat.into(); + + // Get mint info from cache to check bolt12 support (no network call) + let mint_info = &self + .metadata_cache + .load(&self.localstore, &self.client, { + let ttl = self.metadata_cache_ttl.read(); + *ttl + }) + .await? + .mint_info; + + // Check if mint supports bolt12 by looking at nut05 methods + let supports_bolt12 = mint_info + .nuts + .nut05 + .methods + .iter() + .any(|m| m.method == PaymentMethod::Bolt12); + + if supports_bolt12 { + // Mint supports bolt12, try BIP353 first + match self.melt_bip353_quote(address, amount).await { + Ok(quote) => Ok(quote), + Err(Error::Bip353Resolve(_)) => { + // DNS resolution failed, fall back to Lightning address + tracing::debug!( + "BIP353 DNS resolution failed for {}, trying Lightning address", + address + ); + return self.melt_lightning_address_quote(address, amount).await; + } + Err(e) => { + // BIP353 resolved but failed for another reason (e.g., mint error) + // Don't fall back to Lightning address + Err(e) + } + } + } else { + // Mint doesn't support bolt12, use Lightning address directly + self.melt_lightning_address_quote(address, amount).await + } + } } diff --git a/crates/cdk/src/wallet/mint_connector/http_client.rs b/crates/cdk/src/wallet/mint_connector/http_client.rs index 3533417c9..a9705c43c 100644 --- a/crates/cdk/src/wallet/mint_connector/http_client.rs +++ b/crates/cdk/src/wallet/mint_connector/http_client.rs @@ -216,6 +216,28 @@ where self.transport.resolve_dns_txt(domain).await } + /// Fetch Lightning address pay request data + #[instrument(skip(self))] + async fn fetch_lnurl_pay_request( + &self, + url: &str, + ) -> Result { + let parsed_url = + url::Url::parse(url).map_err(|e| Error::Custom(format!("Invalid URL: {}", e)))?; + self.transport.http_get(parsed_url, None).await + } + + /// Fetch invoice from Lightning address callback + #[instrument(skip(self))] + async fn fetch_lnurl_invoice( + &self, + url: &str, + ) -> Result { + let parsed_url = + url::Url::parse(url).map_err(|e| Error::Custom(format!("Invalid URL: {}", e)))?; + self.transport.http_get(parsed_url, None).await + } + /// Get Active Mint Keys [NUT-01] #[instrument(skip(self), fields(mint_url = %self.mint_url))] async fn get_mint_keys(&self) -> Result, Error> { diff --git a/crates/cdk/src/wallet/mint_connector/mod.rs b/crates/cdk/src/wallet/mint_connector/mod.rs index e199bdde8..6cfcc21c2 100644 --- a/crates/cdk/src/wallet/mint_connector/mod.rs +++ b/crates/cdk/src/wallet/mint_connector/mod.rs @@ -6,6 +6,8 @@ use async_trait::async_trait; use cdk_common::{MeltQuoteBolt12Request, MintQuoteBolt12Request, MintQuoteBolt12Response}; use super::Error; +// Re-export Lightning address types for trait implementers +pub use crate::lightning_address::{LnurlPayInvoiceResponse, LnurlPayResponse}; use crate::nuts::{ CheckStateRequest, CheckStateResponse, Id, KeySet, KeysetResponse, MeltQuoteBolt11Request, MeltQuoteBolt11Response, MeltRequest, MintInfo, MintQuoteBolt11Request, @@ -35,6 +37,18 @@ pub trait MintConnector: Debug { /// Resolve the DNS record getting the TXT value async fn resolve_dns_txt(&self, _domain: &str) -> Result, Error>; + /// Fetch Lightning address pay request data + async fn fetch_lnurl_pay_request( + &self, + url: &str, + ) -> Result; + + /// Fetch invoice from Lightning address callback + async fn fetch_lnurl_invoice( + &self, + url: &str, + ) -> Result; + /// Get Active Mint Keys [NUT-01] async fn get_mint_keys(&self) -> Result, Error>; /// Get Keyset Keys [NUT-01] diff --git a/crates/cdk/src/wallet/mod.rs b/crates/cdk/src/wallet/mod.rs index deee8916c..d6497b4fc 100644 --- a/crates/cdk/src/wallet/mod.rs +++ b/crates/cdk/src/wallet/mod.rs @@ -70,7 +70,7 @@ pub use mint_connector::http_client::HttpClient as BaseHttpClient; pub use mint_connector::transport::Transport as HttpTransport; #[cfg(feature = "auth")] pub use mint_connector::AuthHttpClient; -pub use mint_connector::{HttpClient, MintConnector}; +pub use mint_connector::{HttpClient, LnurlPayInvoiceResponse, LnurlPayResponse, MintConnector}; pub use multi_mint_wallet::{MultiMintReceiveOptions, MultiMintSendOptions, MultiMintWallet}; pub use receive::ReceiveOptions; pub use send::{PreparedSend, SendMemo, SendOptions}; From fd6f84812040dc86c25549a83fbd5e57cb87ef7d Mon Sep 17 00:00:00 2001 From: tsk Date: Tue, 18 Nov 2025 12:27:57 +0000 Subject: [PATCH 285/321] fix: Enable pure environment variable configuration for Lightning backends (#1299) * fix: Enable pure environment variable configuration for Lightning backends Removes premature validation that prevented configuring backends entirely through environment variables, enabling containerized deployments without requiring backend sections in config.toml. Changes: - Remove Stage 1 validation from Settings::new_from_default() that checked for backend config sections before environment variables were applied - Add comprehensive regression tests for all 6 Lightning backends (LND, CLN, LNbits, FakeWallet, GRPC Processor, LDK Node) validating env-var-only config - Consolidate tests into single test_env_var_only_config_all_backends() that runs sequentially to avoid environment variable interference The validation still occurs after environment variables are applied in Settings::from_env() and during backend initialization, ensuring proper configuration with clear error messages. Fixes environment variable configuration issue where users could not configure backends without uncommenting all fields in config.toml, which blocked container orchestration deployments that rely on dynamic service discovery. Fixes: https://github.com/cashubtc/cdk/issues/1281 Tests: cargo test -p cdk-mintd test_env_var_only_config_all_backends * feat(cdk-mintd): add config validation for Lightning backend connections Add validation checks for required connection fields in LND, LNbits, and CLN backend setup. Empty configuration values now produce clear error messages indicating which env vars or config fields are missing. Also improve GrpcProcessor and Lightning backend config structs with explicit Default implementations and serde defaults for better deserialization handling. * docs(mintd): add Lightning backend configuration documentation - Add comprehensive configuration guides for CLN, LND, and LNbits backends - Include both config file and environment variable examples - Update mintd README with links to backend-specific docs - Improve example.config.toml with clearer comments and consistent defaults - Standardize fee defaults to 2% with 2 sat minimum across all backends --- crates/cdk-cln/README.md | 37 ++ crates/cdk-lnbits/README.md | 45 +++ crates/cdk-lnd/README.md | 38 ++ crates/cdk-mintd/README.md | 18 +- crates/cdk-mintd/example.config.toml | 28 +- crates/cdk-mintd/src/config.rs | 501 ++++++++++++++++++++++++--- crates/cdk-mintd/src/setup.rs | 35 ++ 7 files changed, 638 insertions(+), 64 deletions(-) diff --git a/crates/cdk-cln/README.md b/crates/cdk-cln/README.md index 97e954888..fd80efbe4 100644 --- a/crates/cdk-cln/README.md +++ b/crates/cdk-cln/README.md @@ -17,4 +17,41 @@ Add this to your `Cargo.toml`: cdk-cln = "*" ``` +## Configuration for cdk-mintd + +### Config File + +```toml +[ln] +ln_backend = "cln" + +[cln] +rpc_path = "/path/to/.lightning/bitcoin/lightning-rpc" +bolt12 = true # Optional, defaults to true +fee_percent = 0.02 # Optional, defaults to 2% +reserve_fee_min = 2 # Optional, defaults to 2 sats +``` + +### Environment Variables + +All configuration can be set via environment variables: + +| Variable | Description | Required | +|----------|-------------|----------| +| `CDK_MINTD_LN_BACKEND` | Set to `cln` | Yes | +| `CDK_MINTD_CLN_RPC_PATH` | Path to CLN RPC socket | Yes | +| `CDK_MINTD_CLN_BOLT12` | Enable BOLT12 support (default: `true`) | No | +| `CDK_MINTD_CLN_FEE_PERCENT` | Fee percentage (default: `0.02`) | No | +| `CDK_MINTD_CLN_RESERVE_FEE_MIN` | Minimum fee in sats (default: `2`) | No | + +### Example + +```bash +export CDK_MINTD_LN_BACKEND=cln +export CDK_MINTD_CLN_RPC_PATH=/home/user/.lightning/bitcoin/lightning-rpc +cdk-mintd +``` + +## License + This project is licensed under the [MIT License](../../LICENSE). diff --git a/crates/cdk-lnbits/README.md b/crates/cdk-lnbits/README.md index 46cffe01d..b573a8532 100644 --- a/crates/cdk-lnbits/README.md +++ b/crates/cdk-lnbits/README.md @@ -19,6 +19,51 @@ Add this to your `Cargo.toml`: cdk-lnbits = "*" ``` +## Configuration for cdk-mintd + +### Config File + +```toml +[ln] +ln_backend = "lnbits" + +[lnbits] +admin_api_key = "your-admin-api-key" +invoice_api_key = "your-invoice-api-key" +lnbits_api = "https://your-lnbits-instance.com/api/v1" +fee_percent = 0.02 # Optional, defaults to 2% +reserve_fee_min = 2 # Optional, defaults to 2 sats +``` + +### Environment Variables + +All configuration can be set via environment variables: + +| Variable | Description | Required | +|----------|-------------|----------| +| `CDK_MINTD_LN_BACKEND` | Set to `lnbits` | Yes | +| `CDK_MINTD_LNBITS_ADMIN_API_KEY` | LNBits admin API key | Yes | +| `CDK_MINTD_LNBITS_INVOICE_API_KEY` | LNBits invoice API key | Yes | +| `CDK_MINTD_LNBITS_LNBITS_API` | LNBits API URL | Yes | +| `CDK_MINTD_LNBITS_FEE_PERCENT` | Fee percentage (default: `0.02`) | No | +| `CDK_MINTD_LNBITS_RESERVE_FEE_MIN` | Minimum fee in sats (default: `2`) | No | + +### Example + +```bash +export CDK_MINTD_LN_BACKEND=lnbits +export CDK_MINTD_LNBITS_ADMIN_API_KEY=your-admin-api-key +export CDK_MINTD_LNBITS_INVOICE_API_KEY=your-invoice-api-key +export CDK_MINTD_LNBITS_LNBITS_API=https://your-lnbits-instance.com/api/v1 +cdk-mintd +``` + +### Getting API Keys + +1. Log in to your LNBits instance +2. Go to your wallet +3. Click on "API Info" to find your admin and invoice API keys + ## License This project is licensed under the [MIT License](../../LICENSE). \ No newline at end of file diff --git a/crates/cdk-lnd/README.md b/crates/cdk-lnd/README.md index bdc2fb60e..562bb9ea8 100644 --- a/crates/cdk-lnd/README.md +++ b/crates/cdk-lnd/README.md @@ -17,6 +17,44 @@ Add this to your `Cargo.toml`: cdk-lnd = "*" ``` +## Configuration for cdk-mintd + +### Config File + +```toml +[ln] +ln_backend = "lnd" + +[lnd] +address = "https://localhost:10009" +cert_file = "/path/to/.lnd/tls.cert" +macaroon_file = "/path/to/.lnd/data/chain/bitcoin/mainnet/admin.macaroon" +fee_percent = 0.02 # Optional, defaults to 2% +reserve_fee_min = 2 # Optional, defaults to 2 sats +``` + +### Environment Variables + +All configuration can be set via environment variables: + +| Variable | Description | Required | +|----------|-------------|----------| +| `CDK_MINTD_LN_BACKEND` | Set to `lnd` | Yes | +| `CDK_MINTD_LND_ADDRESS` | LND gRPC address (e.g., `https://localhost:10009`) | Yes | +| `CDK_MINTD_LND_CERT_FILE` | Path to LND TLS certificate | Yes | +| `CDK_MINTD_LND_MACAROON_FILE` | Path to LND macaroon file | Yes | +| `CDK_MINTD_LND_FEE_PERCENT` | Fee percentage (default: `0.02`) | No | +| `CDK_MINTD_LND_RESERVE_FEE_MIN` | Minimum fee in sats (default: `2`) | No | + +### Example + +```bash +export CDK_MINTD_LN_BACKEND=lnd +export CDK_MINTD_LND_ADDRESS=https://127.0.0.1:10009 +export CDK_MINTD_LND_CERT_FILE=/home/user/.lnd/tls.cert +export CDK_MINTD_LND_MACAROON_FILE=/home/user/.lnd/data/chain/bitcoin/mainnet/admin.macaroon +cdk-mintd +``` ## Minimum Supported Rust Version (MSRV) diff --git a/crates/cdk-mintd/README.md b/crates/cdk-mintd/README.md index 4d9b39a3c..f42bf0847 100644 --- a/crates/cdk-mintd/README.md +++ b/crates/cdk-mintd/README.md @@ -12,11 +12,19 @@ Cashu mint daemon implementation for the Cashu Development Kit (CDK). This binar ## Features - **Multiple Database Backends**: SQLite, PostgreSQL, and ReDB -- **Lightning Network Integration**: Support for CLN, LND, LNbits, LDK Node, and test backends +- **Lightning Network Integration**: Support for CLN, LND, LNbits, LDK Node, and test backends - **Authentication**: Optional user authentication with OpenID Connect - **Management RPC**: gRPC interface for mint management - **Docker Support**: Ready-to-use Docker configurations +## Lightning Backend Documentation + +For detailed configuration of each Lightning backend, see: + +- **[LND](../cdk-lnd/README.md)** - Lightning Network Daemon +- **[CLN](../cdk-cln/README.md)** - Core Lightning +- **[LNbits](../cdk-lnbits/README.md)** - LNbits API integration + ## Installation ### Option 1: Download Pre-built Binary @@ -100,8 +108,8 @@ ln_backend = "cln" [cln] rpc_path = "/home/bitcoin/.lightning/bitcoin/lightning-rpc" -fee_percent = 0.01 -reserve_fee_min = 10 +# fee_percent = 0.02 # Optional, defaults to 2% +# reserve_fee_min = 2 # Optional, defaults to 2 sats ``` ### With LND Lightning Backend @@ -113,8 +121,8 @@ ln_backend = "lnd" address = "https://localhost:10009" macaroon_file = "/home/bitcoin/.lnd/data/chain/bitcoin/mainnet/admin.macaroon" cert_file = "/home/bitcoin/.lnd/tls.cert" -fee_percent = 0.01 -reserve_fee_min = 10 +# fee_percent = 0.02 # Optional, defaults to 2% +# reserve_fee_min = 2 # Optional, defaults to 2 sats ``` ### With PostgreSQL Database diff --git a/crates/cdk-mintd/example.config.toml b/crates/cdk-mintd/example.config.toml index a7110ffdf..0fcc86fef 100644 --- a/crates/cdk-mintd/example.config.toml +++ b/crates/cdk-mintd/example.config.toml @@ -94,30 +94,30 @@ ln_backend = "fakewallet" # min_melt=1 # max_melt=500000 -[cln] -rpc_path = "" -fee_percent = 0.04 -reserve_fee_min = 4 +# [cln] +# rpc_path = "/path/to/.lightning/bitcoin/lightning-rpc" +# bolt12 = true # Optional, defaults to true +# fee_percent = 0.02 # Optional, defaults to 2% +# reserve_fee_min = 2 # Optional, defaults to 2 sats # [lnbits] # admin_api_key = "" # invoice_api_key = "" # lnbits_api = "" -# fee_percent = 0.04 -# # Fee in sats -# reserve_fee_min = 4 +# fee_percent = 0.02 # Optional, defaults to 2% +# reserve_fee_min = 2 # Optional, defaults to 2 sats # Note: Only LNBits v1 API is supported (websocket-based) # [lnd] -# address = "https://domain:port" -# macaroon_file = "" -# cert_file = "" -# fee_percent=0.04 -# reserve_fee_min=4 +# address = "https://localhost:10009" +# cert_file = "/path/to/.lnd/tls.cert" +# macaroon_file = "/path/to/.lnd/data/chain/bitcoin/mainnet/admin.macaroon" +# fee_percent = 0.02 # Optional, defaults to 2% +# reserve_fee_min = 2 # Optional, defaults to 2 sats # [ldk_node] -# fee_percent = 0.04 -# reserve_fee_min = 4 +# fee_percent = 0.02 # Optional, defaults to 2% +# reserve_fee_min = 2 # Optional, defaults to 2 sats # bitcoin_network = "signet" # mainnet, testnet, signet, regtest # chain_source_type = "esplora" # esplora, bitcoinrpc # diff --git a/crates/cdk-mintd/src/config.rs b/crates/cdk-mintd/src/config.rs index a5b2ed9e3..b0d73dc46 100644 --- a/crates/cdk-mintd/src/config.rs +++ b/crates/cdk-mintd/src/config.rs @@ -186,35 +186,84 @@ impl Default for Ln { } #[cfg(feature = "lnbits")] -#[derive(Debug, Clone, Serialize, Deserialize, Default)] +#[derive(Debug, Clone, Serialize, Deserialize)] pub struct LNbits { pub admin_api_key: String, pub invoice_api_key: String, pub lnbits_api: String, + #[serde(default = "default_fee_percent")] pub fee_percent: f32, + #[serde(default = "default_reserve_fee_min")] pub reserve_fee_min: Amount, } +#[cfg(feature = "lnbits")] +impl Default for LNbits { + fn default() -> Self { + Self { + admin_api_key: String::new(), + invoice_api_key: String::new(), + lnbits_api: String::new(), + fee_percent: 0.02, + reserve_fee_min: 2.into(), + } + } +} + #[cfg(feature = "cln")] -#[derive(Debug, Clone, Serialize, Deserialize, Default)] +#[derive(Debug, Clone, Serialize, Deserialize)] pub struct Cln { pub rpc_path: PathBuf, - #[serde(default)] + #[serde(default = "default_cln_bolt12")] pub bolt12: bool, + #[serde(default = "default_fee_percent")] pub fee_percent: f32, + #[serde(default = "default_reserve_fee_min")] pub reserve_fee_min: Amount, } +#[cfg(feature = "cln")] +impl Default for Cln { + fn default() -> Self { + Self { + rpc_path: PathBuf::new(), + bolt12: true, + fee_percent: 0.02, + reserve_fee_min: 2.into(), + } + } +} + +#[cfg(feature = "cln")] +fn default_cln_bolt12() -> bool { + true +} + #[cfg(feature = "lnd")] -#[derive(Debug, Clone, Serialize, Deserialize, Default)] +#[derive(Debug, Clone, Serialize, Deserialize)] pub struct Lnd { pub address: String, pub cert_file: PathBuf, pub macaroon_file: PathBuf, + #[serde(default = "default_fee_percent")] pub fee_percent: f32, + #[serde(default = "default_reserve_fee_min")] pub reserve_fee_min: Amount, } +#[cfg(feature = "lnd")] +impl Default for Lnd { + fn default() -> Self { + Self { + address: String::new(), + cert_file: PathBuf::new(), + macaroon_file: PathBuf::new(), + fee_percent: 0.02, + reserve_fee_min: 2.into(), + } + } +} + #[cfg(feature = "ldk-node")] #[derive(Debug, Clone, Serialize, Deserialize)] pub struct LdkNode { @@ -323,6 +372,15 @@ impl Default for FakeWallet { } // Helper functions to provide default values +// Common fee defaults for all backends +fn default_fee_percent() -> f32 { + 0.02 +} + +fn default_reserve_fee_min() -> Amount { + 2.into() +} + #[cfg(feature = "fakewallet")] fn default_min_delay_time() -> u64 { 1 @@ -333,14 +391,37 @@ fn default_max_delay_time() -> u64 { 3 } -#[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Default)] +#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)] pub struct GrpcProcessor { + #[serde(default)] pub supported_units: Vec, + #[serde(default = "default_grpc_addr")] pub addr: String, + #[serde(default = "default_grpc_port")] pub port: u16, + #[serde(default)] pub tls_dir: Option, } +impl Default for GrpcProcessor { + fn default() -> Self { + Self { + supported_units: Vec::new(), + addr: default_grpc_addr(), + port: default_grpc_port(), + tls_dir: None, + } + } +} + +fn default_grpc_addr() -> String { + "127.0.0.1".to_string() +} + +fn default_grpc_port() -> u16 { + 50051 +} + #[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Default)] #[serde(rename_all = "lowercase")] pub enum DatabaseEngine { @@ -579,46 +660,6 @@ impl Settings { .build()?; let settings: Settings = config.try_deserialize()?; - match settings.ln.ln_backend { - LnBackend::None => panic!("Ln backend must be set"), - #[cfg(feature = "cln")] - LnBackend::Cln => assert!( - settings.cln.is_some(), - "CLN backend requires a valid config." - ), - #[cfg(feature = "lnbits")] - LnBackend::LNbits => assert!( - settings.lnbits.is_some(), - "LNbits backend requires a valid config" - ), - #[cfg(feature = "lnd")] - LnBackend::Lnd => { - assert!( - settings.lnd.is_some(), - "LND backend requires a valid config." - ) - } - #[cfg(feature = "ldk-node")] - LnBackend::LdkNode => { - assert!( - settings.ldk_node.is_some(), - "LDK Node backend requires a valid config." - ) - } - #[cfg(feature = "fakewallet")] - LnBackend::FakeWallet => assert!( - settings.fake_wallet.is_some(), - "FakeWallet backend requires a valid config." - ), - #[cfg(feature = "grpc-processor")] - LnBackend::GrpcProcessor => { - assert!( - settings.grpc_processor.is_some(), - "GRPC backend requires a valid config." - ) - } - } - Ok(settings) } } @@ -692,4 +733,374 @@ mod tests { assert!(!debug_output.contains("特殊字符 !@#$%^&*()")); assert!(debug_output.contains(" + Send + Sync>>, ) -> anyhow::Result { + // Validate required connection field + if self.rpc_path.as_os_str().is_empty() { + return Err(anyhow!( + "CLN rpc_path must be set via config or CDK_MINTD_CLN_RPC_PATH env var" + )); + } + let cln_socket = expand_path( self.rpc_path .to_str() @@ -83,6 +92,19 @@ impl LnBackendSetup for config::LNbits { _work_dir: &Path, _kv_store: Option + Send + Sync>>, ) -> anyhow::Result { + // Validate required connection fields + if self.admin_api_key.is_empty() { + bail!("LNbits admin_api_key must be set via config or CDK_MINTD_LNBITS_ADMIN_API_KEY env var"); + } + if self.invoice_api_key.is_empty() { + bail!("LNbits invoice_api_key must be set via config or CDK_MINTD_LNBITS_INVOICE_API_KEY env var"); + } + if self.lnbits_api.is_empty() { + bail!( + "LNbits lnbits_api must be set via config or CDK_MINTD_LNBITS_LNBITS_API env var" + ); + } + let admin_api_key = &self.admin_api_key; let invoice_api_key = &self.invoice_api_key; @@ -117,6 +139,19 @@ impl LnBackendSetup for config::Lnd { _work_dir: &Path, kv_store: Option + Send + Sync>>, ) -> anyhow::Result { + // Validate required connection fields + if self.address.is_empty() { + bail!("LND address must be set via config or CDK_MINTD_LND_ADDRESS env var"); + } + if self.cert_file.as_os_str().is_empty() { + bail!("LND cert_file must be set via config or CDK_MINTD_LND_CERT_FILE env var"); + } + if self.macaroon_file.as_os_str().is_empty() { + bail!( + "LND macaroon_file must be set via config or CDK_MINTD_LND_MACAROON_FILE env var" + ); + } + let address = &self.address; let cert_file = &self.cert_file; let macaroon_file = &self.macaroon_file; From 2fa92cb34472be6b875626ccfd16424182762a2a Mon Sep 17 00:00:00 2001 From: C Date: Wed, 19 Nov 2025 06:54:04 -0300 Subject: [PATCH 286/321] Fix race condition when concurrent payments are processed for the same payment_id (#1304) * fix race condition when concurrent payments are processed for the same payment_id --------- Co-authored-by: Dustin Dannenhauer --- crates/cdk-integration-tests/tests/mint.rs | 163 +++++++++++++++++++++ crates/cdk/src/mint/ln.rs | 34 +++-- crates/cdk/src/mint/mod.rs | 20 ++- 3 files changed, 203 insertions(+), 14 deletions(-) diff --git a/crates/cdk-integration-tests/tests/mint.rs b/crates/cdk-integration-tests/tests/mint.rs index 9aa76ad56..a84c05a96 100644 --- a/crates/cdk-integration-tests/tests/mint.rs +++ b/crates/cdk-integration-tests/tests/mint.rs @@ -98,3 +98,166 @@ async fn test_correct_keyset() { assert_ne!(new_keyset_info.id, keyset_info.id); } + +/// Test concurrent payment processing to verify race condition fix +/// +/// This test simulates the real-world race condition where multiple concurrent +/// payment notifications arrive for the same payment_id. Before the fix, this +/// would cause "Payment ID already exists" errors. After the fix, all but one +/// should gracefully handle the duplicate and return a Duplicate error. +#[tokio::test(flavor = "multi_thread", worker_threads = 4)] +async fn test_concurrent_duplicate_payment_handling() { + use cashu::PaymentMethod; + use cdk::cdk_database::{MintDatabase, MintQuotesDatabase}; + use cdk::mint::MintQuote; + use cdk::Amount; + use cdk_common::payment::PaymentIdentifier; + use tokio::task::JoinSet; + + // Create a test mint with in-memory database + let mnemonic = Mnemonic::generate(12).unwrap(); + let fee_reserve = FeeReserve { + min_fee_reserve: 1.into(), + percent_fee_reserve: 1.0, + }; + + let database = Arc::new(memory::empty().await.expect("valid db instance")); + + let fake_wallet = FakeWallet::new( + fee_reserve, + HashMap::default(), + HashSet::default(), + 0, + CurrencyUnit::Sat, + ); + + let mut mint_builder = MintBuilder::new(database.clone()); + + mint_builder = mint_builder + .with_name("concurrent test mint".to_string()) + .with_description("testing concurrent payment handling".to_string()); + + mint_builder + .add_payment_processor( + CurrencyUnit::Sat, + PaymentMethod::Bolt11, + MintMeltLimits::new(1, 5_000), + Arc::new(fake_wallet), + ) + .await + .unwrap(); + + let mint = mint_builder + .build_with_seed(database.clone(), &mnemonic.to_seed_normalized("")) + .await + .unwrap(); + + let quote_ttl = QuoteTTL::new(10000, 10000); + mint.set_quote_ttl(quote_ttl).await.unwrap(); + + // Create a mint quote + let current_time = cdk::util::unix_time(); + let mint_quote = MintQuote::new( + None, + "concurrent_test_invoice".to_string(), + CurrencyUnit::Sat, + Some(Amount::from(1000)), + current_time + 3600, // expires in 1 hour + PaymentIdentifier::CustomId("test_lookup_id".to_string()), + None, + Amount::ZERO, + Amount::ZERO, + PaymentMethod::Bolt11, + current_time, + vec![], + vec![], + ); + + // Add the quote to the database + { + let mut tx = MintDatabase::begin_transaction(&*database).await.unwrap(); + tx.add_mint_quote(mint_quote.clone()).await.unwrap(); + tx.commit().await.unwrap(); + } + + // Simulate 10 concurrent payment notifications with the SAME payment_id + let payment_id = "duplicate_payment_test_12345"; + let mut join_set = JoinSet::new(); + + for i in 0..10 { + let db_clone = database.clone(); + let quote_id = mint_quote.id.clone(); + let payment_id_clone = payment_id.to_string(); + + join_set.spawn(async move { + let mut tx = MintDatabase::begin_transaction(&*db_clone).await.unwrap(); + let result = tx + .increment_mint_quote_amount_paid("e_id, Amount::from(10), payment_id_clone) + .await; + + if result.is_ok() { + tx.commit().await.unwrap(); + } + + (i, result) + }); + } + + // Collect results + let mut success_count = 0; + let mut duplicate_errors = 0; + let mut other_errors = Vec::new(); + + while let Some(result) = join_set.join_next().await { + let (task_id, db_result) = result.unwrap(); + match db_result { + Ok(_) => success_count += 1, + Err(e) => { + let err_str = format!("{:?}", e); + if err_str.contains("Duplicate") { + duplicate_errors += 1; + } else { + other_errors.push((task_id, err_str)); + } + } + } + } + + // Verify results + assert_eq!( + success_count, 1, + "Exactly one task should successfully process the payment (got {})", + success_count + ); + assert_eq!( + duplicate_errors, 9, + "Nine tasks should receive Duplicate error (got {})", + duplicate_errors + ); + assert!( + other_errors.is_empty(), + "No unexpected errors should occur. Got: {:?}", + other_errors + ); + + // Verify the quote was incremented exactly once + let final_quote = MintQuotesDatabase::get_mint_quote(&*database, &mint_quote.id) + .await + .unwrap() + .expect("Quote should exist"); + + assert_eq!( + final_quote.amount_paid(), + Amount::from(10), + "Quote amount should be incremented exactly once" + ); + assert_eq!( + final_quote.payments.len(), + 1, + "Should have exactly one payment recorded" + ); + assert_eq!( + final_quote.payments[0].payment_id, payment_id, + "Payment ID should match" + ); +} diff --git a/crates/cdk/src/mint/ln.rs b/crates/cdk/src/mint/ln.rs index 91cacaf82..ec5a4046f 100644 --- a/crates/cdk/src/mint/ln.rs +++ b/crates/cdk/src/mint/ln.rs @@ -7,7 +7,7 @@ use cdk_common::database::DynMintDatabase; use cdk_common::mint::MintQuote; use cdk_common::payment::DynMintPayment; use cdk_common::util::unix_time; -use cdk_common::{Amount, MintQuoteState, PaymentMethod}; +use cdk_common::{database, Amount, MintQuoteState, PaymentMethod}; use tracing::instrument; use super::subscription::PubSubManager; @@ -83,15 +83,29 @@ impl Mint { let amount_paid = to_unit(payment.payment_amount, &payment.unit, "e.unit)?; - quote.increment_amount_paid(amount_paid)?; - quote.add_payment(amount_paid, payment.payment_id.clone(), unix_time())?; - - let total_paid = tx - .increment_mint_quote_amount_paid("e.id, amount_paid, payment.payment_id) - .await?; - - if let Some(pubsub_manager) = pubsub_manager.as_ref() { - pubsub_manager.mint_quote_payment(quote, total_paid); + match tx + .increment_mint_quote_amount_paid( + "e.id, + amount_paid, + payment.payment_id.clone(), + ) + .await + { + Ok(total_paid) => { + quote.increment_amount_paid(amount_paid)?; + quote.add_payment(amount_paid, payment.payment_id.clone(), unix_time())?; + if let Some(pubsub_manager) = pubsub_manager.as_ref() { + pubsub_manager.mint_quote_payment(quote, total_paid); + } + } + Err(database::Error::Duplicate) => { + tracing::debug!( + "Payment ID {} already processed (caught race condition in check_mint_quote_paid)", + payment.payment_id + ); + // This is fine - another concurrent request already processed this payment + } + Err(e) => return Err(e.into()), } } } diff --git a/crates/cdk/src/mint/mod.rs b/crates/cdk/src/mint/mod.rs index aac715e5c..7368e978c 100644 --- a/crates/cdk/src/mint/mod.rs +++ b/crates/cdk/src/mint/mod.rs @@ -749,14 +749,26 @@ impl Mint { payment_amount_quote_unit ); - let total_paid = tx + match tx .increment_mint_quote_amount_paid( &mint_quote.id, payment_amount_quote_unit, - wait_payment_response.payment_id, + wait_payment_response.payment_id.clone(), ) - .await?; - pubsub_manager.mint_quote_payment(mint_quote, total_paid); + .await + { + Ok(total_paid) => { + pubsub_manager.mint_quote_payment(mint_quote, total_paid); + } + Err(database::Error::Duplicate) => { + tracing::info!( + "Payment ID {} already processed (caught race condition)", + wait_payment_response.payment_id + ); + // This is fine - another concurrent request already processed this payment + } + Err(e) => return Err(e.into()), + } } } else { tracing::info!("Received payment notification for already seen payment."); From 139f7b2a823f503376900a5b015cbc9eebafbe7b Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 19 Nov 2025 16:24:40 +0000 Subject: [PATCH 287/321] Weekly Meeting Agenda - 2025-11-19 (#1305) * chore: add weekly meeting agenda for 2025-11-19 --------- Co-authored-by: github-actions[bot] Co-authored-by: thesimplekid --- meetings/2025-11-19-agenda.md | 77 +++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 meetings/2025-11-19-agenda.md diff --git a/meetings/2025-11-19-agenda.md b/meetings/2025-11-19-agenda.md new file mode 100644 index 000000000..076ed1561 --- /dev/null +++ b/meetings/2025-11-19-agenda.md @@ -0,0 +1,77 @@ +# CDK Development Meeting + +Nov 19 2025 15:00 UTC + +Meeting Link: https://meet.fulmo.org/cdk-dev + +## New + +### Issues + +- [#1276](https://github.com/cashubtc/cdk/issues/1276) - Add wallet-side validation to prevent impossible multisig configurations in `Conditions::new()` +- [#1273](https://github.com/cashubtc/cdk/issues/1273) - Add KV store wallet like we have for the mint +- [#1267](https://github.com/cashubtc/cdk/issues/1267) - Async melt for wallet + +### PRs + +- [#1303](https://github.com/cashubtc/cdk/pull/1303) - New get pending +- [#1302](https://github.com/cashubtc/cdk/pull/1302) - release v0.14.0 +- [#1301](https://github.com/cashubtc/cdk/pull/1301) - docs: Update cdk-mintd README to include prerequisites and system-wide install + +## Recently Active + +- [#1257](https://github.com/cashubtc/cdk/pull/1257) - bring signatory up to date with the remote signer spec +- [#1253](https://github.com/cashubtc/cdk/pull/1253) - feat: P2BK +- [#1251](https://github.com/cashubtc/cdk/pull/1251) - feat: custom axum router +- [#1211](https://github.com/cashubtc/cdk/pull/1211) - Regtest setup +- [#1204](https://github.com/cashubtc/cdk/pull/1204) - Add database transaction trait for cdk wallet +- [#1201](https://github.com/cashubtc/cdk/pull/1201) - feat: npubcash +- [#1181](https://github.com/cashubtc/cdk/pull/1181) - Deterministic Currency Unit Derivation Paths +- [#1171](https://github.com/cashubtc/cdk/pull/1171) - Add Dart Bindings Support +- [#1053](https://github.com/cashubtc/cdk/pull/1053) - feat: P2PK key storage and auto-sign on receive +- [#1011](https://github.com/cashubtc/cdk/pull/1011) - fix: migrate check_mint_quote_paid fn from ln.rs to mod.rs +- [#1010](https://github.com/cashubtc/cdk/pull/1010) - adding more LDK configuration settings + +## Merged + +- [#1304](https://github.com/cashubtc/cdk/pull/1304) - Fix race condition when concurrent payments are processed for the same payment_id +- [#1300](https://github.com/cashubtc/cdk/pull/1300) - Prevent database contention in metadata cache load operations +- [#1299](https://github.com/cashubtc/cdk/pull/1299) - fix: Enable pure environment variable configuration for Lightning backends +- [#1298](https://github.com/cashubtc/cdk/pull/1298) - fix: nightly ci +- [#1297](https://github.com/cashubtc/cdk/pull/1297) - fix: allow starting insecure man server +- [#1296](https://github.com/cashubtc/cdk/pull/1296) - refactor(cdk/wallet): extract keyset key loading into helper method +- [#1295](https://github.com/cashubtc/cdk/pull/1295) - feat(cdk): add Lightning address support with BIP353 fallback +- [#1294](https://github.com/cashubtc/cdk/pull/1294) - feat(cdk): add invoice decoding for bolt11 and bolt12 +- [#1293](https://github.com/cashubtc/cdk/pull/1293) - feat: add test coverage for mutants caught in https://github.com/cash… +- [#1292](https://github.com/cashubtc/cdk/pull/1292) - fix: flaky test by using wait and pay +- [#1291](https://github.com/cashubtc/cdk/pull/1291) - fix: load keyset keys from database to prevent duplicate insertions +- [#1289](https://github.com/cashubtc/cdk/pull/1289) - chore: change mutation testing ci time +- [#1288](https://github.com/cashubtc/cdk/pull/1288) - fix: we use the nightly flake so we don't need +nightly +- [#1287](https://github.com/cashubtc/cdk/pull/1287) - chore: fix some minor issues in comments +- [#1284](https://github.com/cashubtc/cdk/pull/1284) - ci: reduce ci jobs +- [#1280](https://github.com/cashubtc/cdk/pull/1280) - Don't read keys from the database +- [#1278](https://github.com/cashubtc/cdk/pull/1278) - Fix missing try_proof_operation_or_reclaim wrapping of a swap +- [#1277](https://github.com/cashubtc/cdk/pull/1277) - Update Wallet::fetch_mint_info +- [#1275](https://github.com/cashubtc/cdk/pull/1275) - fix: require 0 signatures for HTLC with no pubkeys specified +- [#1274](https://github.com/cashubtc/cdk/pull/1274) - fix: return actual error from get_payment_quote +- [#1269](https://github.com/cashubtc/cdk/pull/1269) - fix: nut14 disabled in info +- [#1268](https://github.com/cashubtc/cdk/pull/1268) - Metadata follow up +- [#1266](https://github.com/cashubtc/cdk/pull/1266) - chore: meeting agenda fmt +- [#1265](https://github.com/cashubtc/cdk/pull/1265) - chore: update stable rust to 1.91.1 +- [#1262](https://github.com/cashubtc/cdk/pull/1262) - chore: rust version workflow +- [#1261](https://github.com/cashubtc/cdk/pull/1261) - Weekly Meeting Agenda - 2025-11-12 +- [#1260](https://github.com/cashubtc/cdk/pull/1260) - feat(ci): add nightly rustfmt automation with flexible formatting policy +- [#1240](https://github.com/cashubtc/cdk/pull/1240) - Introduce MintMetadataCache for efficient key and metadata management +- [#1212](https://github.com/cashubtc/cdk/pull/1212) - Various mint bugfixes for swap and melt. SIG_INPUTS+SIG_ALL, locktimes, P2PK+HTLC. Also updates the SIG_ALL message for amount-switching +- [#1210](https://github.com/cashubtc/cdk/pull/1210) - test: add mutation testing infrastructure + +## Release + +- [#1302](https://github.com/cashubtc/cdk/pull/1302) - release v0.14.0 + +## Discussion + +- Mint management RPC +- Cashu Spillman channels +- Self hosted CI defined in nix - https://github.com/thesimplekid/cdk-infra + From 0b6cfe15cfb7effed68ef2272125f746a0165837 Mon Sep 17 00:00:00 2001 From: heatherm <218538013+heathermm55@users.noreply.github.com> Date: Thu, 20 Nov 2025 00:25:06 +0800 Subject: [PATCH 288/321] fix: add missing comma in get_mint_quotes (#1306) --- crates/cdk-sql-common/src/wallet/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/cdk-sql-common/src/wallet/mod.rs b/crates/cdk-sql-common/src/wallet/mod.rs index 99987963e..1d2af6f8a 100644 --- a/crates/cdk-sql-common/src/wallet/mod.rs +++ b/crates/cdk-sql-common/src/wallet/mod.rs @@ -553,7 +553,7 @@ ON CONFLICT(id) DO UPDATE SET request, state, expiry, - secret_key + secret_key, payment_method, amount_issued, amount_paid From c25f196c5bad662fb437e98786aff977fd6160c4 Mon Sep 17 00:00:00 2001 From: tsk Date: Wed, 19 Nov 2025 20:24:15 +0000 Subject: [PATCH 289/321] fix: remove use of unwrap or default in melt saga (#1309) fix: remove compensate in melt finalize --- crates/cdk-common/src/mint.rs | 10 +- crates/cdk/src/mint/melt/melt_saga/mod.rs | 95 ++++- crates/cdk/src/mint/melt/melt_saga/tests.rs | 382 +++++++++++++++++++- crates/cdk/src/mint/start_up_check.rs | 95 ++++- 4 files changed, 554 insertions(+), 28 deletions(-) diff --git a/crates/cdk-common/src/mint.rs b/crates/cdk-common/src/mint.rs index 8225779c2..d9d3d13f6 100644 --- a/crates/cdk-common/src/mint.rs +++ b/crates/cdk-common/src/mint.rs @@ -91,15 +91,15 @@ impl FromStr for SwapSagaState { pub enum MeltSagaState { /// Setup complete (proofs reserved, quote verified) SetupComplete, - /// Payment sent to Lightning network - PaymentSent, + /// Payment attempted to Lightning network (may or may not have succeeded) + PaymentAttempted, } impl fmt::Display for MeltSagaState { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { match self { MeltSagaState::SetupComplete => write!(f, "setup_complete"), - MeltSagaState::PaymentSent => write!(f, "payment_sent"), + MeltSagaState::PaymentAttempted => write!(f, "payment_attempted"), } } } @@ -110,7 +110,7 @@ impl FromStr for MeltSagaState { let value = value.to_lowercase(); match value.as_str() { "setup_complete" => Ok(MeltSagaState::SetupComplete), - "payment_sent" => Ok(MeltSagaState::PaymentSent), + "payment_attempted" => Ok(MeltSagaState::PaymentAttempted), _ => Err(Error::Custom(format!("Invalid melt saga state: {}", value))), } } @@ -147,7 +147,7 @@ impl SagaStateEnum { }, SagaStateEnum::Melt(state) => match state { MeltSagaState::SetupComplete => "setup_complete", - MeltSagaState::PaymentSent => "payment_sent", + MeltSagaState::PaymentAttempted => "payment_attempted", }, } } diff --git a/crates/cdk/src/mint/melt/melt_saga/mod.rs b/crates/cdk/src/mint/melt/melt_saga/mod.rs index 2bd95aab8..464581308 100644 --- a/crates/cdk/src/mint/melt/melt_saga/mod.rs +++ b/crates/cdk/src/mint/melt/melt_saga/mod.rs @@ -4,7 +4,7 @@ use std::sync::Arc; use cdk_common::amount::to_unit; use cdk_common::database::mint::MeltRequestInfo; use cdk_common::database::DynMintDatabase; -use cdk_common::mint::{MeltSagaState, Operation, Saga}; +use cdk_common::mint::{MeltSagaState, Operation, Saga, SagaStateEnum}; use cdk_common::nuts::MeltQuoteState; use cdk_common::{Amount, Error, ProofsMethods, PublicKey, QuoteId, State}; #[cfg(feature = "prometheus")] @@ -62,14 +62,27 @@ mod tests; /// - Triggers compensation if payment fails /// - Special handling for pending/unknown states /// 3. **finalize**: Commits the melt, issues change, marks complete -/// - Triggers compensation if finalization fails +/// - Does NOT compensate if finalization fails (payment already confirmed) +/// - Startup check will retry finalization on recovery /// - Clears compensations on success (melt complete) /// /// # Failure Handling /// -/// If any step fails after setup_melt, all compensating actions are executed in reverse -/// order to restore the database to its pre-melt state. This ensures no partial melts -/// leave the system in an inconsistent state. +/// Failure handling depends on whether payment was attempted: +/// +/// **Before payment attempt (SetupComplete state):** +/// - All compensating actions are executed in reverse order +/// - Database is restored to pre-melt state +/// - User can retry with same proofs +/// +/// **After payment attempt (PaymentAttempted state):** +/// - Compensation is NOT executed (would cause fund loss) +/// - Startup check will verify payment status with LN backend +/// - If payment succeeded: finalize is retried +/// - If payment failed: compensation runs +/// +/// This two-phase approach prevents fund loss where the mint pays the LN invoice +/// but returns the proofs to the user. /// /// # Payment State Complexity /// @@ -77,7 +90,17 @@ mod tests; /// - **Paid**: Proceed to finalize /// - **Failed/Unpaid**: Compensate and return error /// - **Pending/Unknown**: Proofs remain pending, saga cannot complete -/// (current behavior: leave proofs pending, return error for manual intervention) +/// (leave proofs pending for startup check to resolve) +/// +/// # Crash Recovery +/// +/// The saga persists its state for crash recovery: +/// - **SetupComplete**: Payment was never attempted → safe to compensate +/// - **PaymentAttempted**: Payment may have succeeded → must check LN backend +/// +/// On startup, the recovery process checks the persisted saga state and takes +/// appropriate action to either finalize (if payment succeeded) or compensate +/// (if payment was never sent or confirmed failed). /// /// # Typestate Pattern /// @@ -469,6 +492,14 @@ impl MeltSaga { amount ); + // Update saga state to PaymentAttempted BEFORE internal settlement commits + // This ensures crash recovery knows payment may have occurred + tx.update_saga( + self.operation.id(), + SagaStateEnum::Melt(MeltSagaState::PaymentAttempted), + ) + .await?; + let total_paid = tx .increment_mint_quote_amount_paid( &mint_quote.id, @@ -499,10 +530,21 @@ impl MeltSaga { /// /// 1. Takes a SettlementDecision from attempt_internal_settlement /// 2. If Internal: creates payment result directly - /// 3. If RequiresExternalPayment: calls LN backend + /// 3. If RequiresExternalPayment: + /// - Updates saga state to `PaymentAttempted` (for crash recovery) + /// - Calls LN backend to make payment /// 4. Handles payment result states with idempotent verification /// 5. Transitions to PaymentConfirmed state on success /// + /// # Crash Tolerance + /// + /// For external payments, the saga state is updated to `PaymentAttempted` BEFORE + /// calling the LN backend. This write-ahead logging ensures that if the process + /// crashes after payment but before finalize, the startup recovery will: + /// - See `PaymentAttempted` state + /// - Check with LN backend to determine if payment succeeded + /// - Finalize if paid, compensate if failed + /// /// # Idempotent Payment Verification /// /// Lightning payments are asynchronous, and the LN backend may return different @@ -573,6 +615,18 @@ impl MeltSaga { Error::UnsupportedUnit })?; + // Update saga state to PaymentAttempted BEFORE making payment + // This ensures crash recovery knows payment may have been attempted + { + let mut tx = self.db.begin_transaction().await?; + tx.update_saga( + self.operation.id(), + SagaStateEnum::Melt(MeltSagaState::PaymentAttempted), + ) + .await?; + tx.commit().await?; + } + // Make payment with idempotent verification let payment_response = match ln .make_payment( @@ -743,10 +797,23 @@ impl MeltSaga { /// /// On success, compensations are cleared and the melt is complete. /// + /// # Failure Handling + /// + /// **Critical**: If finalization fails, compensation is NOT executed because + /// payment was already confirmed as Paid. Compensating would return proofs to + /// the user while the mint has already paid the Lightning invoice, causing fund loss. + /// + /// Instead, the error is returned and the saga remains in the database with + /// `PaymentAttempted` state. On startup, the recovery process will: + /// 1. Find the incomplete saga + /// 2. Check the LN backend (which will confirm payment as Paid) + /// 3. Retry finalization + /// /// # Errors /// /// - `TokenAlreadySpent`: Input proofs were already spent /// - `BlindedMessageAlreadySigned`: Change outputs already signed + /// - `UnitMismatch`: Failed to convert payment amount to quote unit #[instrument(skip_all)] pub async fn finalize(self) -> Result, Error> { tracing::info!("TX2: Finalizing melt (mark spent + change)"); @@ -756,7 +823,10 @@ impl MeltSaga { &self.state_data.payment_result.unit, &self.state_data.quote.unit, ) - .unwrap_or_default(); + .map_err(|e| { + tracing::error!("Failed to convert total_spent to quote unit: {:?}", e); + Error::UnitMismatch + })?; let payment_preimage = self.state_data.payment_result.payment_proof.clone(); let payment_lookup_id = &self.state_data.payment_result.payment_lookup_id; @@ -787,8 +857,15 @@ impl MeltSaga { ) .await { + // Do NOT compensate here - payment was already confirmed as Paid + // Startup check will retry finalization on next recovery cycle + tracing::error!( + "Finalize failed for paid melt quote {} - will retry on startup: {}", + self.state_data.quote.id, + err + ); + tx.rollback().await?; - self.compensate_all().await?; return Err(err); } diff --git a/crates/cdk/src/mint/melt/melt_saga/tests.rs b/crates/cdk/src/mint/melt/melt_saga/tests.rs index 8fb7e7c50..e3cb99850 100644 --- a/crates/cdk/src/mint/melt/melt_saga/tests.rs +++ b/crates/cdk/src/mint/melt/melt_saga/tests.rs @@ -8,6 +8,8 @@ //! - Concurrent operations //! - Failure handling +use std::str::FromStr; + use cdk_common::mint::{MeltSagaState, OperationKind, Saga}; use cdk_common::nuts::MeltQuoteState; use cdk_common::{Amount, ProofsMethods, State}; @@ -440,6 +442,179 @@ async fn test_crash_recovery_partial_failure() { // 5. Verify failed saga is logged but doesn't stop recovery } +/// Test: Crash recovery after internal settlement commits but before finalize +/// +/// This test verifies that if the mint crashes after internal settlement +/// (melt-to-mint on same mint) commits but before finalize() completes, +/// recovery will correctly finalize the melt rather than compensating. +/// +/// This prevents fund loss where: +/// - The mint quote was credited (mint received funds) +/// - But proofs are returned to user (double-spend) +#[tokio::test] +async fn test_crash_recovery_internal_settlement() { + use cdk_common::nuts::MintQuoteState; + use cdk_common::MintQuoteBolt11Request; + + // STEP 1: Setup test environment + let mint = create_test_mint().await.unwrap(); + let proofs = mint_test_proofs(&mint, Amount::from(10_000)).await.unwrap(); + let input_ys = proofs.ys().unwrap(); + + // STEP 2: Create a mint quote that will be paid internally + // This creates a payment request (invoice) on this mint + // Note: We use a smaller amount (4000) because the test mint has 100% fee reserve, + // so required = amount + fee_reserve = 4000 + 4000 = 8000 < 10000 inputs + let mint_quote_response: cdk_common::MintQuoteBolt11Response<_> = mint + .get_mint_quote( + MintQuoteBolt11Request { + amount: Amount::from(4_000), + unit: cdk_common::CurrencyUnit::Sat, + description: None, + pubkey: None, + } + .into(), + ) + .await + .unwrap() + .into(); + + // Get the mint quote from database + let mint_quote_id = cdk_common::QuoteId::from_str(&mint_quote_response.quote).unwrap(); + let mint_quote = mint + .localstore + .get_mint_quote(&mint_quote_id) + .await + .unwrap() + .expect("Mint quote should exist"); + + // STEP 3: Create a melt quote that uses the mint quote's payment request + // This will trigger internal settlement since it's the same mint + use cdk_common::melt::MeltQuoteRequest; + use cdk_common::nuts::MeltQuoteBolt11Request; + + let melt_bolt11_request = MeltQuoteBolt11Request { + request: mint_quote.request.to_string().parse().unwrap(), + unit: cdk_common::CurrencyUnit::Sat, + options: None, + }; + let melt_quote_request = MeltQuoteRequest::Bolt11(melt_bolt11_request); + + let melt_quote_response = mint.get_melt_quote(melt_quote_request).await.unwrap(); + let melt_quote = mint + .localstore + .get_melt_quote(&melt_quote_response.quote) + .await + .unwrap() + .expect("Melt quote should exist"); + + // STEP 4: Create melt request and setup saga + let melt_request = create_test_melt_request(&proofs, &melt_quote); + let verification = mint.verify_inputs(melt_request.inputs()).await.unwrap(); + + let saga = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + + let setup_saga = saga.setup_melt(&melt_request, verification).await.unwrap(); + let operation_id = *setup_saga.operation.id(); + + // STEP 5: Attempt internal settlement - this will commit and update saga state + let (payment_saga, decision) = setup_saga + .attempt_internal_settlement(&melt_request) + .await + .unwrap(); + + // Verify internal settlement was detected + match decision { + crate::mint::melt::melt_saga::state::SettlementDecision::Internal { amount } => { + assert_eq!( + amount, + Amount::from(4_000), + "Internal settlement amount should match" + ); + } + _ => panic!("Expected internal settlement decision"), + } + + // STEP 6: Simulate crash - drop saga WITHOUT calling make_payment/finalize + drop(payment_saga); + + // STEP 7: Verify pre-recovery state + // Saga should exist in PaymentAttempted state (updated by internal settlement) + let persisted_saga = assert_saga_exists(&mint, &operation_id).await; + match &persisted_saga.state { + cdk_common::mint::SagaStateEnum::Melt(state) => { + assert_eq!( + *state, + MeltSagaState::PaymentAttempted, + "Saga should be in PaymentAttempted state after internal settlement" + ); + } + _ => panic!("Expected Melt saga state"), + } + + // Proofs should still be Pending + assert_proofs_state(&mint, &input_ys, Some(State::Pending)).await; + + // Mint quote should be paid (internal settlement committed) + let mint_quote_after = mint + .localstore + .get_mint_quote(&mint_quote_id) + .await + .unwrap() + .expect("Mint quote should exist"); + assert_eq!( + mint_quote_after.state(), + MintQuoteState::Paid, + "Mint quote should be paid after internal settlement" + ); + + // STEP 8: Run recovery + mint.recover_from_incomplete_melt_sagas() + .await + .expect("Recovery should succeed"); + + // STEP 9: Verify post-recovery state + // Saga should be deleted (successfully finalized) + assert_saga_not_exists(&mint, &operation_id).await; + + // CRITICAL: Proofs should be SPENT, not returned (None) + // This is the key assertion - if proofs were compensated, they'd be None + assert_proofs_state(&mint, &input_ys, Some(State::Spent)).await; + + // Melt quote should be Paid + let melt_quote_after = mint + .localstore + .get_melt_quote(&melt_quote.id) + .await + .unwrap() + .expect("Melt quote should exist"); + assert_eq!( + melt_quote_after.state, + MeltQuoteState::Paid, + "Melt quote should be paid after recovery" + ); + + // Mint quote should still be paid + let mint_quote_final = mint + .localstore + .get_mint_quote(&mint_quote_id) + .await + .unwrap() + .expect("Mint quote should exist"); + assert_eq!( + mint_quote_final.state(), + MintQuoteState::Paid, + "Mint quote should remain paid after recovery" + ); + + // SUCCESS: Recovery correctly finalized internal settlement! + // No fund loss - proofs spent and mint quote paid +} + // ============================================================================ // Startup Integration Tests // ============================================================================ @@ -1956,12 +2131,18 @@ async fn test_saga_drop_without_finalize() { // SUCCESS: Drop without finalize doesn't panic! } -/// Test: Saga drop after payment is recoverable +/// Test: Saga drop after payment is recoverable and finalizes correctly +/// +/// This test verifies that when a saga is dropped after payment but before finalize, +/// the recovery process correctly finalizes the melt (marks proofs as spent) rather +/// than compensating (returning proofs to user). This is critical for preventing +/// fund loss where the mint pays the LN invoice but returns the proofs. #[tokio::test] async fn test_saga_drop_after_payment() { // STEP 1: Setup test environment let mint = create_test_mint().await.unwrap(); let proofs = mint_test_proofs(&mint, Amount::from(10_000)).await.unwrap(); + let input_ys = proofs.ys().unwrap(); let quote = create_test_melt_quote(&mint, Amount::from(9_000)).await; let melt_request = create_test_melt_request(&proofs, "e); @@ -1975,6 +2156,9 @@ async fn test_saga_drop_after_payment() { let setup_saga = saga.setup_melt(&melt_request, verification).await.unwrap(); let operation_id = *setup_saga.operation.id(); + // Verify proofs are PENDING after setup + assert_proofs_state(&mint, &input_ys, Some(State::Pending)).await; + // Attempt internal settlement let (payment_saga, decision) = setup_saga .attempt_internal_settlement(&melt_request) @@ -1984,12 +2168,21 @@ async fn test_saga_drop_after_payment() { // Make payment let confirmed_saga = payment_saga.make_payment(decision).await.unwrap(); - // STEP 3: Drop before finalize (simulates crash after payment) - drop(confirmed_saga); - - // STEP 4: Verify saga still exists (wasn't finalized) + // STEP 3: Verify saga state is now PaymentAttempted (not SetupComplete) let saga_in_db = assert_saga_exists(&mint, &operation_id).await; - assert_eq!(saga_in_db.operation_id, operation_id); + match &saga_in_db.state { + cdk_common::mint::SagaStateEnum::Melt(state) => { + assert_eq!( + *state, + MeltSagaState::PaymentAttempted, + "Saga state should be PaymentAttempted after make_payment" + ); + } + _ => panic!("Expected Melt saga state"), + } + + // STEP 4: Drop before finalize (simulates crash after payment) + drop(confirmed_saga); // STEP 5: Run recovery to complete the operation mint.recover_from_incomplete_melt_sagas() @@ -1999,7 +2192,182 @@ async fn test_saga_drop_after_payment() { // STEP 6: Verify saga was recovered and cleaned up assert_saga_not_exists(&mint, &operation_id).await; - // SUCCESS: Drop after payment is recoverable! + // STEP 7: Verify proofs were marked SPENT (not returned to user) + // This is the critical check - if compensation ran instead of finalize, + // proofs would be None (returned) instead of Spent + assert_proofs_state(&mint, &input_ys, Some(State::Spent)).await; + + // STEP 8: Verify quote is marked as PAID + let final_quote = mint + .localstore + .get_melt_quote("e.id) + .await + .unwrap() + .expect("Quote should exist"); + assert_eq!( + final_quote.state, + MeltQuoteState::Paid, + "Quote should be marked as Paid after recovery finalization" + ); + + // SUCCESS: Drop after payment correctly finalizes (doesn't compensate)! +} + +/// Test: PaymentAttempted state triggers LN backend check during recovery +/// +/// This test verifies that when recovery finds a saga in PaymentAttempted state, +/// it checks the LN backend to determine whether to finalize or compensate, +/// rather than blindly compensating like SetupComplete state. +#[tokio::test] +async fn test_payment_attempted_state_triggers_ln_check() { + // STEP 1: Setup test environment + let mint = create_test_mint().await.unwrap(); + let proofs = mint_test_proofs(&mint, Amount::from(10_000)).await.unwrap(); + let input_ys = proofs.ys().unwrap(); + let quote = create_test_melt_quote(&mint, Amount::from(9_000)).await; + let melt_request = create_test_melt_request(&proofs, "e); + + // STEP 2: Setup saga and make payment + let verification = mint.verify_inputs(melt_request.inputs()).await.unwrap(); + let saga = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let setup_saga = saga.setup_melt(&melt_request, verification).await.unwrap(); + let operation_id = *setup_saga.operation.id(); + + // Check initial state is SetupComplete + let saga_before_payment = assert_saga_exists(&mint, &operation_id).await; + match &saga_before_payment.state { + cdk_common::mint::SagaStateEnum::Melt(state) => { + assert_eq!( + *state, + MeltSagaState::SetupComplete, + "Initial state should be SetupComplete" + ); + } + _ => panic!("Expected Melt saga state"), + } + + // Attempt internal settlement and make payment + let (payment_saga, decision) = setup_saga + .attempt_internal_settlement(&melt_request) + .await + .unwrap(); + let confirmed_saga = payment_saga.make_payment(decision).await.unwrap(); + + // STEP 3: Verify state transitioned to PaymentAttempted + let saga_after_payment = assert_saga_exists(&mint, &operation_id).await; + match &saga_after_payment.state { + cdk_common::mint::SagaStateEnum::Melt(state) => { + assert_eq!( + *state, + MeltSagaState::PaymentAttempted, + "State should be PaymentAttempted after make_payment" + ); + } + _ => panic!("Expected Melt saga state"), + } + + // STEP 4: Drop saga (simulate crash after payment but before finalize) + drop(confirmed_saga); + + // STEP 5: Run recovery - should check LN backend and finalize + mint.recover_from_incomplete_melt_sagas() + .await + .expect("Recovery should succeed"); + + // STEP 6: Verify correct outcome - finalized, not compensated + assert_saga_not_exists(&mint, &operation_id).await; + + // Proofs should be SPENT (finalized), not None (compensated) + assert_proofs_state(&mint, &input_ys, Some(State::Spent)).await; + + // Quote should be PAID + let final_quote = mint + .localstore + .get_melt_quote("e.id) + .await + .unwrap() + .expect("Quote should exist"); + assert_eq!( + final_quote.state, + MeltQuoteState::Paid, + "Quote should be Paid - LN backend check should have triggered finalization" + ); + + // SUCCESS: PaymentAttempted state correctly triggers LN check and finalizes! +} + +/// Test: SetupComplete state compensates without LN check +/// +/// This test verifies that when recovery finds a saga in SetupComplete state, +/// it compensates (returns proofs) without checking LN backend, because +/// payment was never sent. +#[tokio::test] +async fn test_setup_complete_state_compensates() { + // STEP 1: Setup test environment + let mint = create_test_mint().await.unwrap(); + let proofs = mint_test_proofs(&mint, Amount::from(10_000)).await.unwrap(); + let input_ys = proofs.ys().unwrap(); + let quote = create_test_melt_quote(&mint, Amount::from(9_000)).await; + let melt_request = create_test_melt_request(&proofs, "e); + + // STEP 2: Setup saga but don't make payment + let verification = mint.verify_inputs(melt_request.inputs()).await.unwrap(); + let saga = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let setup_saga = saga.setup_melt(&melt_request, verification).await.unwrap(); + let operation_id = *setup_saga.operation.id(); + + // Verify state is SetupComplete + let saga_in_db = assert_saga_exists(&mint, &operation_id).await; + match &saga_in_db.state { + cdk_common::mint::SagaStateEnum::Melt(state) => { + assert_eq!( + *state, + MeltSagaState::SetupComplete, + "State should be SetupComplete" + ); + } + _ => panic!("Expected Melt saga state"), + } + + // Verify proofs are PENDING + assert_proofs_state(&mint, &input_ys, Some(State::Pending)).await; + + // STEP 3: Drop saga (simulate crash before payment) + drop(setup_saga); + + // STEP 4: Run recovery - should compensate without LN check + mint.recover_from_incomplete_melt_sagas() + .await + .expect("Recovery should succeed"); + + // STEP 5: Verify correct outcome - compensated, not finalized + assert_saga_not_exists(&mint, &operation_id).await; + + // Proofs should be None (compensated/returned), not Spent + assert_proofs_state(&mint, &input_ys, None).await; + + // Quote should be UNPAID (reset) + let final_quote = mint + .localstore + .get_melt_quote("e.id) + .await + .unwrap() + .expect("Quote should exist"); + assert_eq!( + final_quote.state, + MeltQuoteState::Unpaid, + "Quote should be Unpaid - compensation should have reset it" + ); + + // SUCCESS: SetupComplete state correctly compensates! } // ============================================================================ diff --git a/crates/cdk/src/mint/start_up_check.rs b/crates/cdk/src/mint/start_up_check.rs index c6e7eb770..d6cd843b6 100644 --- a/crates/cdk/src/mint/start_up_check.rs +++ b/crates/cdk/src/mint/start_up_check.rs @@ -315,22 +315,103 @@ impl Mint { } }; - // Check saga state to determine if payment was sent - // SetupComplete means setup transaction committed but payment NOT yet sent + // Check saga state to determine if payment was attempted + // SetupComplete means setup transaction committed but payment NOT yet attempted + // PaymentAttempted means payment was attempted - must check LN backend let should_compensate = match &saga.state { cdk_common::mint::SagaStateEnum::Melt(state) => { match state { cdk_common::mint::MeltSagaState::SetupComplete => { - // Setup complete but payment never sent - always compensate + // Setup complete but payment never attempted - always compensate tracing::info!( - "Saga {} in SetupComplete state - payment never sent, will compensate", + "Saga {} in SetupComplete state - payment never attempted, will compensate", saga.operation_id ); true } - _ => { - // Other states - should not happen in incomplete sagas, but check payment status anyway - false // Will check payment status below + cdk_common::mint::MeltSagaState::PaymentAttempted => { + // Payment was attempted - check for internal settlement first, then LN backend + tracing::info!( + "Saga {} in PaymentAttempted state - checking for internal or external payment", + saga.operation_id + ); + + // Check if this was an internal settlement by looking for a mint quote + // that was paid by this melt quote + let is_internal_settlement = match self + .localstore + .get_mint_quote_by_request("e.request.to_string()) + .await + { + Ok(Some(mint_quote)) => { + // Check if this mint quote was paid by our melt quote + let melt_quote_id_str = quote.id.to_string(); + mint_quote.payment_ids().contains(&&melt_quote_id_str) + } + Ok(None) => false, + Err(e) => { + tracing::warn!( + "Error checking for internal settlement for saga {}: {}", + saga.operation_id, + e + ); + false + } + }; + + if is_internal_settlement { + // Internal settlement was completed - finalize directly + tracing::info!( + "Saga {} was internal settlement - will finalize directly", + saga.operation_id + ); + + // Get payment info for finalization + let total_spent = quote.amount; + let payment_lookup_id = + quote.request_lookup_id.clone().unwrap_or_else(|| { + cdk_common::payment::PaymentIdentifier::CustomId( + quote.id.to_string(), + ) + }); + + if let Err(err) = self + .finalize_paid_melt_quote( + "e, + total_spent, + None, // No preimage for internal settlement + &payment_lookup_id, + ) + .await + { + tracing::error!( + "Failed to finalize internal settlement saga {}: {}", + saga.operation_id, + err + ); + } + + // Delete saga after successful finalization + let mut tx = self.localstore.begin_transaction().await?; + if let Err(e) = tx.delete_saga(&saga.operation_id).await { + tracing::error!( + "Failed to delete saga for {}: {}", + saga.operation_id, + e + ); + tx.rollback().await?; + } else { + tx.commit().await?; + tracing::info!( + "Successfully recovered and finalized internal settlement saga {}", + saga.operation_id + ); + } + + continue; // Skip to next saga + } + + false // Will check LN payment status below } } } From eb798e90524f07a647481b5c496cdc445be0f9b7 Mon Sep 17 00:00:00 2001 From: tsk Date: Thu, 20 Nov 2025 09:54:01 +0000 Subject: [PATCH 290/321] release v0.14.0 (#1302) * docs: changelog * chore: bump 0.14.0 --- CHANGELOG.md | 105 +++++++++++++++++++++++++++++++++++++++++++++++++++ Cargo.toml | 40 ++++++++++---------- 2 files changed, 125 insertions(+), 20 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6a00a985e..aa460ef84 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,109 @@ + +## [0.14.0](https://github.com/cashubtc/cdk/releases/tag/v0.14.0) + +### Summary + +This release focuses on reliability and robustness improvements across the codebase. The mint now implements saga patterns for both melt and swap operations, providing better error recovery and state consistency during these critical operations. Async melt processing has been added for improved throughput. The wallet gains a new Tor mint connector with isolated circuits support for enhanced privacy when communicating with mints, along with a MintMetadataCache that delivers significant performance improvements for key and metadata management. A new proof recovery mechanism automatically handles failed wallet operations. MultiMintWallet receives improvements including the ability to check and wait for mint quotes and configure internal wallets. NUT-11 SIG_ALL message aggregation has been updated to match the latest specification. On the infrastructure side, a generic pubsub module has been introduced in cdk-common, and cdk-ffi adds postgres support. Additional highlights include keyset amount tracking and SQL balance calculation optimization for improved performance, wallet functions to pay human readable addresses (BIP353 and Lightning address), invoice decoding for BOLT11 and BOLT12 in the FFI bindings, and a mutation testing infrastructure to ensure security-critical code coverage. The release also brings numerous bug fixes addressing database contention, HTLC witness handling, and quote state management. + +### Added +- cdk: Add wallet functions to pay human readable addresses (BIP353 and Lightning address) ([thesimplekid]). +- cdk-ffi: Add invoice decoding for bolt11 and bolt12 ([thesimplekid]). +- cdk: Add keyset_amounts table to track issued and redeemed amounts for improved performance ([crodas]). +- cdk: Add melt quote state transition validation ([thesimplekid]). +- cdk: Add payment request and proof to transaction records ([thesimplekid]). +- cdk: Add WebSocket authentication support ([thesimplekid]). +- cdk: Add proof recovery mechanism for failed wallet operations ([crodas]). +- cdk-ffi: Added postgres support ([asmo]). +- cdk: Optimize SQL balance calculation ([vnprc]). +- cdk: Add tor mint connector for wallet with isolated circuits support ([lollerfirst]). +- cdk-common: Introduce a generic pubsub module ([crodas]). +- cdk: Add MultiMintWallet check and wait for mint quotes ([davidcaseria]). +- cdk: Allow passing metadata to a melt ([benthecarman]). +- cashu: Include supported amounts instead of assuming the power of 2 ([crodas]). +- test: Add mutation testing infrastructure and security-critical coverage ([thesimplekid]). + +### Changed +- cdk: Introduce MintMetadataCache for efficient key and metadata management ([crodas]). +- cdk: Implement saga pattern for melt operations ([thesimplekid]). +- cdk: Implement saga pattern for swap operations ([thesimplekid]). +- cdk: Async melt processing ([thesimplekid]). +- cdk: Extract keyset key loading into helper method ([thesimplekid]). +- cdk: Update Wallet::fetch_mint_info ([crodas]). +- cdk-ffi: Update FFI Database Objects to Records ([davidcaseria]). +- cdk: Redesign Lightning invoice creation and display with better UX and status handling ([erik]). +- cdk: Configure internal Wallets of a MultiMintWallet ([davidcaseria]). +- cdk-ffi: Split uniffi types into multiple mods ([davidcaseria]). +- cdk-ffi: Make Uniffi Records Codable in Swift ([davidcaseria]). +- cdk: Replace proof swap with state check in error recovery ([crodas]). +- cdk: Simplify mint addition in MultiMintWallet ([thesimplekid]). +- cdk: Update NUT-11 SIG_ALL message aggregation per spec ([SatsAndSports]). +- cdk: Remove delete functions for quotes ([thesimplekid]). + +### Fixed +- cdk: Enable pure environment variable configuration for Lightning backends ([thesimplekid]). +- cdk: Prevent database contention in metadata cache load operations ([crodas]). +- cdk: Allow starting insecure mint server ([thesimplekid]). +- cdk: Load keyset keys from database to prevent duplicate insertions ([thesimplekid]). +- cdk: Fix missing try_proof_operation_or_reclaim wrapping of a swap ([crodas]). +- cdk: Don't read keys from the database unnecessarily ([crodas]). +- cdk: Return actual error from get_payment_quote ([gudnuf]). +- cdk: Require 0 signatures for HTLC with no pubkeys specified ([thesimplekid]). +- cdk: Fix NUT-14 disabled in info ([thesimplekid]). +- cdk: Check the removed_ys argument before creating the delete query ([asmo]). +- cdk: Add parent directory validation before database creation ([thesimplekid]). +- cashu: Skip serializing empty NUT15 settings in mint info ([thesimplekid]). +- cdk: Fix bug with websocket close ([crodas]). +- cdk: Fix htlc witness deserialization ([stefanbitcr]). +- cdk-lnbits: Fix msats error handling ([thesimplekid]). +- cdk: Handle fiat melt amount conversions ([gudnuf]). +- cdk: Only settle same unit quote internally ([gudnuf]). +- cdk: Revert redis cache removal ([thesimplekid]). +- cdk: Improve add transaction handling ([thesimplekid]). +- cdk: Read the latest mint quote status in a transaction to avoid race conditions ([crodas]). +- cdk: Fix websocket issues and mint quotes ([crodas]). +- cashu: Fix PreMintSecrets into_iter() ([codingpeanut157]). + +## [0.13.4](https://github.com/cashubtc/cdk/releases/tag/v0.13.4) + +### Added +- cdk-lnbits: Update LNbits integration ([thesimplekid]). +- cdk: Clean witness data ([thesimplekid]). + +## [0.13.3](https://github.com/cashubtc/cdk/releases/tag/v0.13.3) + +### Fixed +- cdk-lnbits: Fix lnbits fee calc ([thesimplekid]). + +## [0.13.2](https://github.com/cashubtc/cdk/releases/tag/v0.13.2) + +### Added +- cashu: Add spending-condition inspection helpers and token_secrets() ([lollerfirst]). + +### Changed +- cdk: Make sorting Transactions a stable sort ([benthecarman]). +- Updated stable Rust to 1.85.0 ([thesimplekid]). + +### Fixed +- cdk-lnbits: Add websocket reconnection with exponential backoff ([thesimplekid]). +- cdk: Add parent directory validation before database creation ([thesimplekid]). +- cashu: Skip serializing empty NUT15 settings in mint info ([lollerfirst]). +- cdk: Improve Melted error handling and add debug logging ([thesimplekid]). +- cdk: Read the latest mint quote status in a transaction to avoid race conditions ([crodas]). + +## [0.13.1](https://github.com/cashubtc/cdk/releases/tag/v0.13.1) + +### Fixed +- cdk: Only settle same unit quote internally ([gudnuf]). +- cdk-cli: Show amounts correctly ([thesimplekid]). +- cdk-lnbits: Fix msats error handling ([thesimplekid]). + +### Changed +- cdk: Simplify mint addition in MultiMintWallet by removing unnecessary mint info fetching and keyset refresh ([thesimplekid]). +- cdk-ffi: Make UniFFI Records Codable in Swift ([davidcaseria]). + ## [0.13.0](https://github.com/cashubtc/cdk/releases/tag/v0.13.0) ### Summary @@ -571,3 +674,5 @@ Additionally, this release introduces a Mint binary cdk-mintd that uses the cdk- [gudnuf]: https://github.com/gudnuf [codingpeanut157]: https://github.com/codingpeanut157 [erik]: https://github.com/swedishfrenchpress +[SatsAndSports]: https://github.com/SatsAndSports +[stefanbitcr]: https://github.com/stefanbitcr diff --git a/Cargo.toml b/Cargo.toml index ecff12998..e39fbe736 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -33,7 +33,7 @@ rust-version = "1.85.0" license = "MIT" homepage = "https://github.com/cashubtc/cdk" repository = "https://github.com/cashubtc/cdk.git" -version = "0.13.0" +version = "0.14.0" readme = "README.md" [workspace.dependencies] @@ -43,25 +43,25 @@ axum = { version = "0.8.1", features = ["ws"] } bitcoin = { version = "0.32.2", features = ["base64", "serde", "rand", "rand-std"] } bip39 = { version = "2.0", features = ["rand"] } jsonwebtoken = "9.2.0" -cashu = { path = "./crates/cashu", version = "=0.13.0" } -cdk = { path = "./crates/cdk", default-features = false, version = "=0.13.0" } -cdk-common = { path = "./crates/cdk-common", default-features = false, version = "=0.13.0" } -cdk-axum = { path = "./crates/cdk-axum", default-features = false, version = "=0.13.0" } -cdk-cln = { path = "./crates/cdk-cln", version = "=0.13.0" } -cdk-lnbits = { path = "./crates/cdk-lnbits", version = "=0.13.0" } -cdk-lnd = { path = "./crates/cdk-lnd", version = "=0.13.0" } -cdk-ldk-node = { path = "./crates/cdk-ldk-node", version = "=0.13.0" } -cdk-fake-wallet = { path = "./crates/cdk-fake-wallet", version = "=0.13.0" } -cdk-ffi = { path = "./crates/cdk-ffi", version = "=0.13.0" } -cdk-payment-processor = { path = "./crates/cdk-payment-processor", default-features = true, version = "=0.13.0" } -cdk-mint-rpc = { path = "./crates/cdk-mint-rpc", version = "=0.13.0" } -cdk-redb = { path = "./crates/cdk-redb", default-features = true, version = "=0.13.0" } -cdk-sql-common = { path = "./crates/cdk-sql-common", default-features = true, version = "=0.13.0" } -cdk-sqlite = { path = "./crates/cdk-sqlite", default-features = true, version = "=0.13.0" } -cdk-postgres = { path = "./crates/cdk-postgres", default-features = true, version = "=0.13.0" } -cdk-signatory = { path = "./crates/cdk-signatory", version = "=0.13.0", default-features = false } -cdk-mintd = { path = "./crates/cdk-mintd", version = "=0.13.0", default-features = false } -cdk-prometheus = { path = "./crates/cdk-prometheus", version = "=0.13.0", default-features = false } +cashu = { path = "./crates/cashu", version = "=0.14.0" } +cdk = { path = "./crates/cdk", default-features = false, version = "=0.14.0" } +cdk-common = { path = "./crates/cdk-common", default-features = false, version = "=0.14.0" } +cdk-axum = { path = "./crates/cdk-axum", default-features = false, version = "=0.14.0" } +cdk-cln = { path = "./crates/cdk-cln", version = "=0.14.0" } +cdk-lnbits = { path = "./crates/cdk-lnbits", version = "=0.14.0" } +cdk-lnd = { path = "./crates/cdk-lnd", version = "=0.14.0" } +cdk-ldk-node = { path = "./crates/cdk-ldk-node", version = "=0.14.0" } +cdk-fake-wallet = { path = "./crates/cdk-fake-wallet", version = "=0.14.0" } +cdk-ffi = { path = "./crates/cdk-ffi", version = "=0.14.0" } +cdk-payment-processor = { path = "./crates/cdk-payment-processor", default-features = true, version = "=0.14.0" } +cdk-mint-rpc = { path = "./crates/cdk-mint-rpc", version = "=0.14.0" } +cdk-redb = { path = "./crates/cdk-redb", default-features = true, version = "=0.14.0" } +cdk-sql-common = { path = "./crates/cdk-sql-common", default-features = true, version = "=0.14.0" } +cdk-sqlite = { path = "./crates/cdk-sqlite", default-features = true, version = "=0.14.0" } +cdk-postgres = { path = "./crates/cdk-postgres", default-features = true, version = "=0.14.0" } +cdk-signatory = { path = "./crates/cdk-signatory", version = "=0.14.0", default-features = false } +cdk-mintd = { path = "./crates/cdk-mintd", version = "=0.14.0", default-features = false } +cdk-prometheus = { path = "./crates/cdk-prometheus", version = "=0.14.0", default-features = false } clap = { version = "4.5.31", features = ["derive"] } ciborium = { version = "0.2.2", default-features = false, features = ["std"] } cbor-diag = "0.1.12" From fd4557cca5d2a2cac8af81f560d7fef6d45b585c Mon Sep 17 00:00:00 2001 From: tsk Date: Thu, 20 Nov 2025 10:47:37 +0000 Subject: [PATCH 291/321] fix: ldk-node account for ln fee (#1312) --- crates/cdk-ldk-node/src/lib.rs | 6 ++++-- crates/cdk-ldk-node/src/web/handlers/payments.rs | 8 +++++++- 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/crates/cdk-ldk-node/src/lib.rs b/crates/cdk-ldk-node/src/lib.rs index 7f1e7805f..0a89a2fad 100644 --- a/crates/cdk-ldk-node/src/lib.rs +++ b/crates/cdk-ldk-node/src/lib.rs @@ -731,7 +731,8 @@ impl MintPayment for CdkLdkNode { let total_spent = payment_details .amount_msat - .ok_or(Error::CouldNotGetAmountSpent)?; + .ok_or(Error::CouldNotGetAmountSpent)? + + payment_details.fee_paid_msat.unwrap_or_default(); let total_spent = to_unit(total_spent, &CurrencyUnit::Msat, unit)?; @@ -805,7 +806,8 @@ impl MintPayment for CdkLdkNode { let total_spent = payment_details .amount_msat - .ok_or(Error::CouldNotGetAmountSpent)?; + .ok_or(Error::CouldNotGetAmountSpent)? + + payment_details.fee_paid_msat.unwrap_or_default(); let total_spent = to_unit(total_spent, &CurrencyUnit::Msat, unit)?; diff --git a/crates/cdk-ldk-node/src/web/handlers/payments.rs b/crates/cdk-ldk-node/src/web/handlers/payments.rs index 3bcfbc43d..46a838837 100644 --- a/crates/cdk-ldk-node/src/web/handlers/payments.rs +++ b/crates/cdk-ldk-node/src/web/handlers/payments.rs @@ -158,7 +158,13 @@ pub async fn payments_page( get_invoice_status(payment.status, payment.direction, payment_type) }; - @let amount_str = payment.amount_msat.map(format_msats_as_btc).unwrap_or_else(|| "Unknown".to_string()); + @let amount_str = { + match (payment.amount_msat, payment.fee_paid_msat) { + (Some(amount), Some(fee)) => format_msats_as_btc(amount + fee), + (Some(amount), None) => format_msats_as_btc(amount), + _ => "Unknown".to_string() + } + }; (payment_list_item( &payment.id.to_string(), From 590b428885a9781b2a1db1e2b74a5711d552a212 Mon Sep 17 00:00:00 2001 From: tsk Date: Fri, 21 Nov 2025 12:44:22 +0000 Subject: [PATCH 292/321] chore: release justfile (#1317) --- justfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/justfile b/justfile index b52f0e5fc..ba74dfeb9 100644 --- a/justfile +++ b/justfile @@ -411,6 +411,7 @@ release m="": "-p cdk-postgres" "-p cdk-redb" "-p cdk-signatory" + "-p cdk-fake-wallet" "-p cdk" "-p cdk-ffi" "-p cdk-axum" @@ -419,7 +420,6 @@ release m="": "-p cdk-lnd" "-p cdk-lnbits" "-p cdk-ldk-node" - "-p cdk-fake-wallet" "-p cdk-payment-processor" "-p cdk-cli" "-p cdk-mintd" From 94a326c5eaf6ec7b5162ec0ee7cf10a8de622f12 Mon Sep 17 00:00:00 2001 From: tsk Date: Fri, 21 Nov 2025 16:00:43 +0000 Subject: [PATCH 293/321] Revert "Prevent database contention in metadata cache load operations (#1300)" (#1320) This reverts commit a12fd4dbeae83079e88c0f3cec776d7f44056792. --- crates/cdk/src/wallet/builder.rs | 12 --- crates/cdk/src/wallet/mint_metadata_cache.rs | 89 +++++++------------- 2 files changed, 31 insertions(+), 70 deletions(-) diff --git a/crates/cdk/src/wallet/builder.rs b/crates/cdk/src/wallet/builder.rs index c3991b1ab..557ace25a 100644 --- a/crates/cdk/src/wallet/builder.rs +++ b/crates/cdk/src/wallet/builder.rs @@ -4,7 +4,6 @@ use std::time::Duration; use cdk_common::database; use cdk_common::parking_lot::RwLock; -use cdk_common::task::spawn; #[cfg(feature = "auth")] use cdk_common::AuthToken; #[cfg(feature = "auth")] @@ -224,17 +223,6 @@ impl WalletBuilder { } }); - let metadata_for_loader = metadata_cache.clone(); - let localstore_for_loader = localstore.clone(); - spawn(async move { - let _ = metadata_for_loader - .load_from_storage(&localstore_for_loader) - .await - .inspect_err(|err| { - tracing::warn!("Failed to load mint metadata from storage {err}"); - }); - }); - Ok(Wallet { mint_url, unit, diff --git a/crates/cdk/src/wallet/mint_metadata_cache.rs b/crates/cdk/src/wallet/mint_metadata_cache.rs index 34367968d..122f7f1d6 100644 --- a/crates/cdk/src/wallet/mint_metadata_cache.rs +++ b/crates/cdk/src/wallet/mint_metadata_cache.rs @@ -243,6 +243,20 @@ impl MintMetadataCache { return Ok(current_metadata); } + // Load keys from database before fetching from HTTP + // This prevents re-fetching keys we already have and avoids duplicate insertions + if let Some(keysets) = storage.get_mint_keysets(self.mint_url.clone()).await? { + let mut updated_metadata = (*self.metadata.load().clone()).clone(); + for keyset_info in keysets { + if let Some(keys) = storage.get_keys(&keyset_info.id).await? { + tracing::trace!("Loaded keys for keyset {} from database", keyset_info.id); + updated_metadata.keys.insert(keyset_info.id, Arc::new(keys)); + } + } + // Update cache with database keys before HTTP fetch + self.metadata.store(Arc::new(updated_metadata)); + } + // Perform the fetch #[cfg(feature = "auth")] let metadata = self.fetch_from_http(Some(client), None).await?; @@ -317,64 +331,6 @@ impl MintMetadataCache { self.load_from_mint(storage, client).await } - /// Load mint info and keys from storage. - /// - /// This function should be called without any competing transaction with the storage. - pub async fn load_from_storage( - &self, - storage: &Arc + Send + Sync>, - ) -> Result<(), Error> { - // Load keys from database before fetching from HTTP - // This prevents re-fetching keys we already have and avoids duplicate insertions - let mut updated_metadata = (*self.metadata.load().clone()).clone(); - - updated_metadata.mint_info = storage - .get_mint(self.mint_url.clone()) - .await? - .ok_or(Error::UnknownKeySet)?; - - let keysets = storage - .get_mint_keysets(self.mint_url.clone()) - .await? - .ok_or(Error::UnknownKeySet)? - .into_iter() - .map(Arc::new) - .collect::>(); - - for keyset_info in keysets.iter() { - if let Some(keys) = storage.get_keys(&keyset_info.id).await? { - tracing::trace!( - "Loaded keys for keyset {} from database (auth)", - keyset_info.id - ); - updated_metadata.keys.insert(keyset_info.id, Arc::new(keys)); - } - if keyset_info.active { - updated_metadata.active_keysets.push(keyset_info.clone()); - } - } - - updated_metadata.keysets = keysets - .into_iter() - .map(|keyset| (keyset.id, keyset)) - .collect(); - updated_metadata.status.is_populated = true; - updated_metadata.status.version += 1; - updated_metadata.status.updated_at = Instant::now(); - - #[cfg(feature = "auth")] - { - updated_metadata.auth_status.is_populated = true; - updated_metadata.auth_status.updated_at = Instant::now(); - updated_metadata.auth_status.version += 1; - } - - // Update cache with database keys before HTTP fetch - self.metadata.store(Arc::new(updated_metadata)); - - Ok(()) - } - /// Load auth keysets and keys (auth feature only) /// /// Fetches blind authentication keysets from the mint. Always performs @@ -429,6 +385,23 @@ impl MintMetadataCache { return Ok(current_metadata); } + // Load keys from database before fetching from HTTP + // This prevents re-fetching keys we already have and avoids duplicate insertions + if let Some(keysets) = storage.get_mint_keysets(self.mint_url.clone()).await? { + let mut updated_metadata = (*self.metadata.load().clone()).clone(); + for keyset_info in keysets { + if let Some(keys) = storage.get_keys(&keyset_info.id).await? { + tracing::trace!( + "Loaded keys for keyset {} from database (auth)", + keyset_info.id + ); + updated_metadata.keys.insert(keyset_info.id, Arc::new(keys)); + } + } + // Update cache with database keys before HTTP fetch + self.metadata.store(Arc::new(updated_metadata)); + } + // Auth data not in cache - fetch from mint let metadata = self.fetch_from_http(None, Some(auth_client)).await?; From 7c49717ff166b9841c0455f572f206cbfb15fd2b Mon Sep 17 00:00:00 2001 From: tsk Date: Fri, 21 Nov 2025 18:15:21 +0000 Subject: [PATCH 294/321] Cdk ffi psgl (#1321) * chore: release justfile * fix: cdk-ffi psgl feature --- .github/workflows/ci.yml | 3 ++- crates/cdk-ffi/src/database.rs | 2 ++ crates/cdk-ffi/src/lib.rs | 1 + 3 files changed, 5 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2156e1413..7a99299ea 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -132,7 +132,8 @@ jobs: # FFI bindings -p cdk-ffi, - + -p cdk-ffi --no-default-features, + # Binaries --bin cdk-cli, --bin cdk-cli --features sqlcipher, diff --git a/crates/cdk-ffi/src/database.rs b/crates/cdk-ffi/src/database.rs index c87b1c554..d78ce9c76 100644 --- a/crates/cdk-ffi/src/database.rs +++ b/crates/cdk-ffi/src/database.rs @@ -6,6 +6,7 @@ use std::sync::Arc; use cdk::cdk_database::WalletDatabase as CdkWalletDatabase; use crate::error::FfiError; +#[cfg(feature = "postgres")] use crate::postgres::WalletPostgresDatabase; use crate::sqlite::WalletSqliteDatabase; use crate::types::*; @@ -602,6 +603,7 @@ pub fn create_wallet_db(backend: WalletDbBackend) -> Result) } + #[cfg(feature = "postgres")] WalletDbBackend::Postgres { url } => { let pg = WalletPostgresDatabase::new(url)?; Ok(pg as Arc) diff --git a/crates/cdk-ffi/src/lib.rs b/crates/cdk-ffi/src/lib.rs index 57dbb8b4c..c60350b2f 100644 --- a/crates/cdk-ffi/src/lib.rs +++ b/crates/cdk-ffi/src/lib.rs @@ -7,6 +7,7 @@ pub mod database; pub mod error; pub mod multi_mint_wallet; +#[cfg(feature = "postgres")] pub mod postgres; pub mod sqlite; pub mod token; From 930704323e493ff8f3b71326ece57a15ab21f08b Mon Sep 17 00:00:00 2001 From: tsk Date: Sat, 22 Nov 2025 08:30:32 +0000 Subject: [PATCH 295/321] Load mint info (#1323) * refactor(wallet): ensure mint info is loaded before quote operations Load mint info upfront in issue_bolt11, issue_bolt12, and receive methods to ensure database has current mint information before processing quotes. * feat: load mint info in ffi * refactor(cdk): replace deferred database persistence with synchronous writes in mint metadata cache Changes background task spawning to direct async/await for database sync operations. Ensures database consistency by persisting metadata before returning from cache operations. * feat(cdk-ffi): add metadata cache TTL configuration methods Add methods to configure metadata cache time-to-live for both Wallet and MultiMintWallet: - set_metadata_cache_ttl for single wallet - set_metadata_cache_ttl_for_mint for specific mint in multi-mint wallet - set_metadata_cache_ttl_for_all_mints for all mints in multi-mint wallet --- crates/cdk-ffi/src/multi_mint_wallet.rs | 45 +++++++++++++++++++ crates/cdk-ffi/src/wallet.rs | 31 +++++++++++++ crates/cdk/src/wallet/issue/issue_bolt11.rs | 8 ++-- crates/cdk/src/wallet/issue/issue_bolt12.rs | 8 ++-- crates/cdk/src/wallet/mint_metadata_cache.rs | 46 +++++++++----------- crates/cdk/src/wallet/receive.rs | 4 ++ 6 files changed, 107 insertions(+), 35 deletions(-) diff --git a/crates/cdk-ffi/src/multi_mint_wallet.rs b/crates/cdk-ffi/src/multi_mint_wallet.rs index 0ca4eda56..cd6bb8299 100644 --- a/crates/cdk-ffi/src/multi_mint_wallet.rs +++ b/crates/cdk-ffi/src/multi_mint_wallet.rs @@ -111,6 +111,51 @@ impl MultiMintWallet { self.inner.unit().clone().into() } + /// Set metadata cache TTL (time-to-live) in seconds for a specific mint + /// + /// Controls how long cached mint metadata (keysets, keys, mint info) is considered fresh + /// before requiring a refresh from the mint server for a specific mint. + /// + /// # Arguments + /// + /// * `mint_url` - The mint URL to set the TTL for + /// * `ttl_secs` - Optional TTL in seconds. If None, cache never expires. + pub async fn set_metadata_cache_ttl_for_mint( + &self, + mint_url: MintUrl, + ttl_secs: Option, + ) -> Result<(), FfiError> { + let cdk_mint_url: cdk::mint_url::MintUrl = mint_url.try_into()?; + let wallets = self.inner.get_wallets().await; + + if let Some(wallet) = wallets.iter().find(|w| w.mint_url == cdk_mint_url) { + let ttl = ttl_secs.map(std::time::Duration::from_secs); + wallet.set_metadata_cache_ttl(ttl); + Ok(()) + } else { + Err(FfiError::Generic { + msg: format!("Mint not found: {}", cdk_mint_url), + }) + } + } + + /// Set metadata cache TTL (time-to-live) in seconds for all mints + /// + /// Controls how long cached mint metadata is considered fresh for all mints + /// in this MultiMintWallet. + /// + /// # Arguments + /// + /// * `ttl_secs` - Optional TTL in seconds. If None, cache never expires for any mint. + pub async fn set_metadata_cache_ttl_for_all_mints(&self, ttl_secs: Option) { + let wallets = self.inner.get_wallets().await; + let ttl = ttl_secs.map(std::time::Duration::from_secs); + + for wallet in wallets.iter() { + wallet.set_metadata_cache_ttl(ttl); + } + } + /// Add a mint to this MultiMintWallet pub async fn add_mint( &self, diff --git a/crates/cdk-ffi/src/wallet.rs b/crates/cdk-ffi/src/wallet.rs index 4543a461a..78f646060 100644 --- a/crates/cdk-ffi/src/wallet.rs +++ b/crates/cdk-ffi/src/wallet.rs @@ -62,6 +62,29 @@ impl Wallet { self.inner.unit.clone().into() } + /// Set metadata cache TTL (time-to-live) in seconds + /// + /// Controls how long cached mint metadata (keysets, keys, mint info) is considered fresh + /// before requiring a refresh from the mint server. + /// + /// # Arguments + /// + /// * `ttl_secs` - Optional TTL in seconds. If None, cache never expires and is always used. + /// + /// # Example + /// + /// ```ignore + /// // Cache expires after 5 minutes + /// wallet.set_metadata_cache_ttl(Some(300)); + /// + /// // Cache never expires (default) + /// wallet.set_metadata_cache_ttl(None); + /// ``` + pub fn set_metadata_cache_ttl(&self, ttl_secs: Option) { + let ttl = ttl_secs.map(std::time::Duration::from_secs); + self.inner.set_metadata_cache_ttl(ttl); + } + /// Get total balance pub async fn total_balance(&self) -> Result { let balance = self.inner.total_balance().await?; @@ -86,6 +109,14 @@ impl Wallet { Ok(info.map(Into::into)) } + /// Load mint info + /// + /// This will get mint info from cache if it is fresh + pub async fn load_mint_info(&self) -> Result { + let info = self.inner.load_mint_info().await?; + Ok(info.into()) + } + /// Receive tokens pub async fn receive( &self, diff --git a/crates/cdk/src/wallet/issue/issue_bolt11.rs b/crates/cdk/src/wallet/issue/issue_bolt11.rs index aada9ed81..bec70a623 100644 --- a/crates/cdk/src/wallet/issue/issue_bolt11.rs +++ b/crates/cdk/src/wallet/issue/issue_bolt11.rs @@ -49,16 +49,14 @@ impl Wallet { amount: Amount, description: Option, ) -> Result { + let mint_info = self.load_mint_info().await?; + let mint_url = self.mint_url.clone(); let unit = self.unit.clone(); // If we have a description, we check that the mint supports it. if description.is_some() { - let settings = self - .localstore - .get_mint(mint_url.clone()) - .await? - .ok_or(Error::IncorrectMint)? + let settings = mint_info .nuts .nut04 .get_settings(&unit, &crate::nuts::PaymentMethod::Bolt11) diff --git a/crates/cdk/src/wallet/issue/issue_bolt12.rs b/crates/cdk/src/wallet/issue/issue_bolt12.rs index d20a17017..6ecd657cb 100644 --- a/crates/cdk/src/wallet/issue/issue_bolt12.rs +++ b/crates/cdk/src/wallet/issue/issue_bolt12.rs @@ -26,16 +26,14 @@ impl Wallet { amount: Option, description: Option, ) -> Result { + let mint_info = self.load_mint_info().await?; + let mint_url = self.mint_url.clone(); let unit = &self.unit; // If we have a description, we check that the mint supports it. if description.is_some() { - let mint_method_settings = self - .localstore - .get_mint(mint_url.clone()) - .await? - .ok_or(Error::IncorrectMint)? + let mint_method_settings = mint_info .nuts .nut04 .get_settings(unit, &crate::nuts::PaymentMethod::Bolt12) diff --git a/crates/cdk/src/wallet/mint_metadata_cache.rs b/crates/cdk/src/wallet/mint_metadata_cache.rs index 122f7f1d6..44b5f3307 100644 --- a/crates/cdk/src/wallet/mint_metadata_cache.rs +++ b/crates/cdk/src/wallet/mint_metadata_cache.rs @@ -1,13 +1,13 @@ //! Per-mint cryptographic key and metadata cache //! //! Provides on-demand fetching and caching of mint metadata (info, keysets, and keys) -//! with atomic in-memory cache updates and deferred database persistence. +//! with atomic in-memory cache updates and database persistence. //! //! # Architecture //! //! - **Pull-based loading**: Keys fetched on-demand from mint HTTP API //! - **Atomic cache**: Single `MintMetadata` snapshot updated via `ArcSwap` -//! - **Deferred persistence**: Database writes happen asynchronously after cache update +//! - **Synchronous persistence**: Database writes happen after cache update //! - **Multi-database support**: Tracks sync status per storage instance via pointer identity //! //! # Usage @@ -34,7 +34,6 @@ use cdk_common::database::{self, WalletDatabase}; use cdk_common::mint_url::MintUrl; use cdk_common::nuts::{KeySetInfo, Keys}; use cdk_common::parking_lot::RwLock; -use cdk_common::task::spawn; use cdk_common::{KeySet, MintInfo}; use tokio::sync::Mutex; @@ -99,11 +98,11 @@ pub struct MintMetadata { auth_status: FreshnessStatus, } -/// On-demand mint metadata cache with deferred database persistence +/// On-demand mint metadata cache with database persistence /// /// Manages a single mint's cryptographic keys and metadata. Fetches data from -/// the mint's HTTP API on-demand and caches it in memory. Database writes are -/// deferred to background tasks to avoid blocking operations. +/// the mint's HTTP API on-demand and caches it in memory. Database writes +/// occur synchronously to ensure persistence. /// /// # Thread Safety /// @@ -198,8 +197,7 @@ impl MintMetadataCache { /// Load metadata from mint server and update cache /// /// Always performs an HTTP fetch from the mint server to get fresh data. - /// Updates the in-memory cache and spawns a background task to persist - /// to the database. + /// Updates the in-memory cache and persists to the database. /// /// Uses a mutex to ensure only one fetch runs at a time. If multiple /// callers request a fetch simultaneously, only one performs the HTTP @@ -264,8 +262,8 @@ impl MintMetadataCache { #[cfg(not(feature = "auth"))] let metadata = self.fetch_from_http(Some(client)).await?; - // Spawn background task to persist to database (non-blocking) - self.spawn_database_sync(storage.clone(), metadata.clone()); + // Persist to database + self.database_sync(storage.clone(), metadata.clone()).await; Ok(metadata) } @@ -319,10 +317,9 @@ impl MintMetadataCache { { // Cache is ready - check if database needs updating if db_synced_version != cached_metadata.status.version { - // Database is stale - sync in background - // We spawn rather than await to avoid blocking the caller - // and to prevent deadlocks with any existing transactions - self.spawn_database_sync(storage.clone(), cached_metadata.clone()); + // Database is stale - sync before returning + self.database_sync(storage.clone(), cached_metadata.clone()) + .await; } return Ok(cached_metadata); } @@ -365,8 +362,9 @@ impl MintMetadataCache { && cached_metadata.auth_status.updated_at > Instant::now() { if db_synced_version != cached_metadata.status.version { - // Database needs updating - spawn background sync - self.spawn_database_sync(storage.clone(), cached_metadata.clone()); + // Database needs updating - sync before returning + self.database_sync(storage.clone(), cached_metadata.clone()) + .await; } return Ok(cached_metadata); } @@ -405,19 +403,19 @@ impl MintMetadataCache { // Auth data not in cache - fetch from mint let metadata = self.fetch_from_http(None, Some(auth_client)).await?; - // Spawn background task to persist - self.spawn_database_sync(storage.clone(), metadata.clone()); + // Persist to database + self.database_sync(storage.clone(), metadata.clone()).await; Ok(metadata) } - /// Spawn a background task to sync metadata to database + /// Sync metadata to database /// - /// This is non-blocking and happens asynchronously. The task will: + /// This will: /// 1. Check if this sync is still needed (version may be superseded) /// 2. Save mint info, keysets, and keys to the database /// 3. Update the sync tracking to record this storage has been updated - fn spawn_database_sync( + async fn database_sync( &self, storage: Arc + Send + Sync>, metadata: Arc, @@ -425,12 +423,10 @@ impl MintMetadataCache { let mint_url = self.mint_url.clone(); let db_sync_versions = self.db_sync_versions.clone(); - spawn(async move { - Self::persist_to_database(mint_url, storage, metadata, db_sync_versions).await - }); + Self::persist_to_database(mint_url, storage, metadata, db_sync_versions).await } - /// Persist metadata to database (called from background task) + /// Persist metadata to database /// /// Saves mint info, keysets, and keys to the database. Checks version /// before writing to avoid redundant work if a newer version has already diff --git a/crates/cdk/src/wallet/receive.rs b/crates/cdk/src/wallet/receive.rs index cc7bf09bb..b53620a3a 100644 --- a/crates/cdk/src/wallet/receive.rs +++ b/crates/cdk/src/wallet/receive.rs @@ -26,6 +26,10 @@ impl Wallet { opts: ReceiveOptions, memo: Option, ) -> Result { + // Incase the wallet is getting ecash for the first time + // we want to get the mint info for our db + let _mint_info = self.load_mint_info().await?; + let mint_url = &self.mint_url; let active_keyset_id = self.fetch_active_keyset().await?.id; From 4cfc29532adb9ab95a7afcc8701a9cafca840699 Mon Sep 17 00:00:00 2001 From: tsk Date: Sat, 22 Nov 2025 10:55:45 +0000 Subject: [PATCH 296/321] feat(multi-mint-wallet): add human-readable address melt quote support (#1325) Add three new methods to MultiMintWallet for creating melt quotes from human-readable addresses: - melt_bip353_quote: resolves BIP353 addresses to Lightning offers - melt_lightning_address_quote: resolves Lightning addresses to invoices - melt_human_readable_quote: intelligently tries BIP353 or Lightning address based on mint Bolt12 support --- crates/cdk-ffi/src/multi_mint_wallet.rs | 82 +++++++++++++++++++ crates/cdk/src/wallet/multi_mint_wallet.rs | 92 ++++++++++++++++++++++ 2 files changed, 174 insertions(+) diff --git a/crates/cdk-ffi/src/multi_mint_wallet.rs b/crates/cdk-ffi/src/multi_mint_wallet.rs index cd6bb8299..c3114ae9e 100644 --- a/crates/cdk-ffi/src/multi_mint_wallet.rs +++ b/crates/cdk-ffi/src/multi_mint_wallet.rs @@ -349,6 +349,88 @@ impl MultiMintWallet { Ok(quote.into()) } + /// Get a melt quote for a BIP353 human-readable address + /// + /// This method resolves a BIP353 address (e.g., "alice@example.com") to a Lightning offer + /// and then creates a melt quote for that offer at the specified mint. + /// + /// # Arguments + /// + /// * `mint_url` - The mint to use for creating the melt quote + /// * `bip353_address` - Human-readable address in the format "user@domain.com" + /// * `amount_msat` - Amount to pay in millisatoshis + #[cfg(not(target_arch = "wasm32"))] + pub async fn melt_bip353_quote( + &self, + mint_url: MintUrl, + bip353_address: String, + amount_msat: u64, + ) -> Result { + let cdk_mint_url: cdk::mint_url::MintUrl = mint_url.try_into()?; + let cdk_amount = cdk::Amount::from(amount_msat); + let quote = self + .inner + .melt_bip353_quote(&cdk_mint_url, &bip353_address, cdk_amount) + .await?; + Ok(quote.into()) + } + + /// Get a melt quote for a Lightning address + /// + /// This method resolves a Lightning address (e.g., "alice@example.com") to a Lightning invoice + /// and then creates a melt quote for that invoice at the specified mint. + /// + /// # Arguments + /// + /// * `mint_url` - The mint to use for creating the melt quote + /// * `lightning_address` - Lightning address in the format "user@domain.com" + /// * `amount_msat` - Amount to pay in millisatoshis + pub async fn melt_lightning_address_quote( + &self, + mint_url: MintUrl, + lightning_address: String, + amount_msat: u64, + ) -> Result { + let cdk_mint_url: cdk::mint_url::MintUrl = mint_url.try_into()?; + let cdk_amount = cdk::Amount::from(amount_msat); + let quote = self + .inner + .melt_lightning_address_quote(&cdk_mint_url, &lightning_address, cdk_amount) + .await?; + Ok(quote.into()) + } + + /// Get a melt quote for a human-readable address + /// + /// This method accepts a human-readable address that could be either a BIP353 address + /// or a Lightning address. It intelligently determines which to try based on mint support: + /// + /// 1. If the mint supports Bolt12, it tries BIP353 first + /// 2. Falls back to Lightning address only if BIP353 DNS resolution fails + /// 3. If BIP353 resolves but fails at the mint, it does NOT fall back to Lightning address + /// 4. If the mint doesn't support Bolt12, it tries Lightning address directly + /// + /// # Arguments + /// + /// * `mint_url` - The mint to use for creating the melt quote + /// * `address` - Human-readable address (BIP353 or Lightning address) + /// * `amount_msat` - Amount to pay in millisatoshis + #[cfg(not(target_arch = "wasm32"))] + pub async fn melt_human_readable_quote( + &self, + mint_url: MintUrl, + address: String, + amount_msat: u64, + ) -> Result { + let cdk_mint_url: cdk::mint_url::MintUrl = mint_url.try_into()?; + let cdk_amount = cdk::Amount::from(amount_msat); + let quote = self + .inner + .melt_human_readable_quote(&cdk_mint_url, &address, cdk_amount) + .await?; + Ok(quote.into()) + } + /// Melt tokens (pay a bolt11 invoice) pub async fn melt( &self, diff --git a/crates/cdk/src/wallet/multi_mint_wallet.rs b/crates/cdk/src/wallet/multi_mint_wallet.rs index 1e98d37f7..a6e89d498 100644 --- a/crates/cdk/src/wallet/multi_mint_wallet.rs +++ b/crates/cdk/src/wallet/multi_mint_wallet.rs @@ -1656,6 +1656,98 @@ impl MultiMintWallet { wallet.fetch_mint_info().await } + + /// Melt Quote for BIP353 human-readable address + /// + /// This method resolves a BIP353 address (e.g., "alice@example.com") to a Lightning offer + /// and then creates a melt quote for that offer at the specified mint. + /// + /// # Arguments + /// + /// * `mint_url` - The mint to use for creating the melt quote + /// * `bip353_address` - Human-readable address in the format "user@domain.com" + /// * `amount_msat` - Amount to pay in millisatoshis + /// + /// # Returns + /// + /// A `MeltQuote` that can be used to execute the payment + #[cfg(all(feature = "bip353", not(target_arch = "wasm32")))] + #[instrument(skip(self, amount_msat))] + pub async fn melt_bip353_quote( + &self, + mint_url: &MintUrl, + bip353_address: &str, + amount_msat: impl Into, + ) -> Result { + let wallets = self.wallets.read().await; + let wallet = wallets.get(mint_url).ok_or(Error::UnknownMint { + mint_url: mint_url.to_string(), + })?; + + wallet.melt_bip353_quote(bip353_address, amount_msat).await + } + + /// Melt Quote for Lightning address + /// + /// This method resolves a Lightning address (e.g., "alice@example.com") to a Lightning invoice + /// and then creates a melt quote for that invoice at the specified mint. + /// + /// # Arguments + /// + /// * `mint_url` - The mint to use for creating the melt quote + /// * `lightning_address` - Lightning address in the format "user@domain.com" + /// * `amount_msat` - Amount to pay in millisatoshis + /// + /// # Returns + /// + /// A `MeltQuote` that can be used to execute the payment + #[instrument(skip(self, amount_msat))] + pub async fn melt_lightning_address_quote( + &self, + mint_url: &MintUrl, + lightning_address: &str, + amount_msat: impl Into, + ) -> Result { + let wallets = self.wallets.read().await; + let wallet = wallets.get(mint_url).ok_or(Error::UnknownMint { + mint_url: mint_url.to_string(), + })?; + + wallet + .melt_lightning_address_quote(lightning_address, amount_msat) + .await + } + + /// Get a melt quote for a human-readable address + /// + /// This method accepts a human-readable address that could be either a BIP353 address + /// or a Lightning address. It intelligently determines which to try based on mint support: + /// + /// 1. If the mint supports Bolt12, it tries BIP353 first + /// 2. Falls back to Lightning address only if BIP353 DNS resolution fails + /// 3. If BIP353 resolves but fails at the mint, it does NOT fall back to Lightning address + /// 4. If the mint doesn't support Bolt12, it tries Lightning address directly + /// + /// # Arguments + /// + /// * `mint_url` - The mint to use for creating the melt quote + /// * `address` - Human-readable address (BIP353 or Lightning address) + /// * `amount_msat` - Amount to pay in millisatoshis + #[cfg(all(feature = "bip353", feature = "wallet", not(target_arch = "wasm32")))] + #[instrument(skip(self, amount_msat))] + pub async fn melt_human_readable_quote( + &self, + mint_url: &MintUrl, + address: &str, + amount_msat: impl Into, + ) -> Result { + let wallets = self.wallets.read().await; + let wallet = wallets.get(mint_url).ok_or(Error::UnknownMint { + mint_url: mint_url.to_string(), + })?; + + wallet.melt_human_readable_quote(address, amount_msat).await + } } impl Drop for MultiMintWallet { From 303836c1824be0a0a976325414730db09e4b8113 Mon Sep 17 00:00:00 2001 From: C Date: Sun, 23 Nov 2025 15:35:03 -0300 Subject: [PATCH 297/321] Deduplicate mint quote database queries (#1314) Extract duplicate SQL query logic into generic inline helper functions that work with both database connections and transactions. This reduces code duplication and improves maintainability by centralizing query definitions. --- crates/cdk-sql-common/src/mint/mod.rs | 455 +++++++++++--------------- 1 file changed, 195 insertions(+), 260 deletions(-) diff --git a/crates/cdk-sql-common/src/mint/mod.rs b/crates/cdk-sql-common/src/mint/mod.rs index a587726c3..6546ca39f 100644 --- a/crates/cdk-sql-common/src/mint/mod.rs +++ b/crates/cdk-sql-common/src/mint/mod.rs @@ -393,6 +393,193 @@ WHERE quote_id=:quote_id .collect() } +// Inline helper functions that work with both connections and transactions +#[inline] +async fn get_mint_quote_inner( + executor: &T, + quote_id: &QuoteId, + for_update: bool, +) -> Result, Error> +where + T: DatabaseExecutor, +{ + let payments = get_mint_quote_payments(executor, quote_id).await?; + let issuance = get_mint_quote_issuance(executor, quote_id).await?; + + let for_update_clause = if for_update { "FOR UPDATE" } else { "" }; + let query_str = format!( + r#" + SELECT + id, + amount, + unit, + request, + expiry, + request_lookup_id, + pubkey, + created_time, + amount_paid, + amount_issued, + payment_method, + request_lookup_id_kind + FROM + mint_quote + WHERE id = :id + {for_update_clause} + "# + ); + + query(&query_str)? + .bind("id", quote_id.to_string()) + .fetch_one(executor) + .await? + .map(|row| sql_row_to_mint_quote(row, payments, issuance)) + .transpose() +} + +#[inline] +async fn get_mint_quote_by_request_inner( + executor: &T, + request: &str, + for_update: bool, +) -> Result, Error> +where + T: DatabaseExecutor, +{ + let for_update_clause = if for_update { "FOR UPDATE" } else { "" }; + let query_str = format!( + r#" + SELECT + id, + amount, + unit, + request, + expiry, + request_lookup_id, + pubkey, + created_time, + amount_paid, + amount_issued, + payment_method, + request_lookup_id_kind + FROM + mint_quote + WHERE request = :request + {for_update_clause} + "# + ); + + let mut mint_quote = query(&query_str)? + .bind("request", request.to_string()) + .fetch_one(executor) + .await? + .map(|row| sql_row_to_mint_quote(row, vec![], vec![])) + .transpose()?; + + if let Some(quote) = mint_quote.as_mut() { + let payments = get_mint_quote_payments(executor, "e.id).await?; + let issuance = get_mint_quote_issuance(executor, "e.id).await?; + quote.issuance = issuance; + quote.payments = payments; + } + + Ok(mint_quote) +} + +#[inline] +async fn get_mint_quote_by_request_lookup_id_inner( + executor: &T, + request_lookup_id: &PaymentIdentifier, + for_update: bool, +) -> Result, Error> +where + T: DatabaseExecutor, +{ + let for_update_clause = if for_update { "FOR UPDATE" } else { "" }; + let query_str = format!( + r#" + SELECT + id, + amount, + unit, + request, + expiry, + request_lookup_id, + pubkey, + created_time, + amount_paid, + amount_issued, + payment_method, + request_lookup_id_kind + FROM + mint_quote + WHERE request_lookup_id = :request_lookup_id + AND request_lookup_id_kind = :request_lookup_id_kind + {for_update_clause} + "# + ); + + let mut mint_quote = query(&query_str)? + .bind("request_lookup_id", request_lookup_id.to_string()) + .bind("request_lookup_id_kind", request_lookup_id.kind()) + .fetch_one(executor) + .await? + .map(|row| sql_row_to_mint_quote(row, vec![], vec![])) + .transpose()?; + + if let Some(quote) = mint_quote.as_mut() { + let payments = get_mint_quote_payments(executor, "e.id).await?; + let issuance = get_mint_quote_issuance(executor, "e.id).await?; + quote.issuance = issuance; + quote.payments = payments; + } + + Ok(mint_quote) +} + +#[inline] +async fn get_melt_quote_inner( + executor: &T, + quote_id: &QuoteId, + for_update: bool, +) -> Result, Error> +where + T: DatabaseExecutor, +{ + let for_update_clause = if for_update { "FOR UPDATE" } else { "" }; + let query_str = format!( + r#" + SELECT + id, + unit, + amount, + request, + fee_reserve, + expiry, + state, + payment_preimage, + request_lookup_id, + created_time, + paid_time, + payment_method, + options, + request_lookup_id_kind + FROM + melt_quote + WHERE + id=:id + {for_update_clause} + "# + ); + + query(&query_str)? + .bind("id", quote_id.to_string()) + .fetch_one(executor) + .await? + .map(sql_row_to_melt_quote) + .transpose() +} + #[async_trait] impl MintKeyDatabaseTransaction<'_, Error> for SQLTransaction where @@ -1105,153 +1292,28 @@ VALUES (:quote_id, :amount, :timestamp); } async fn get_mint_quote(&mut self, quote_id: &QuoteId) -> Result, Self::Err> { - let payments = get_mint_quote_payments(&self.inner, quote_id).await?; - let issuance = get_mint_quote_issuance(&self.inner, quote_id).await?; - - Ok(query( - r#" - SELECT - id, - amount, - unit, - request, - expiry, - request_lookup_id, - pubkey, - created_time, - amount_paid, - amount_issued, - payment_method, - request_lookup_id_kind - FROM - mint_quote - WHERE id = :id - FOR UPDATE - "#, - )? - .bind("id", quote_id.to_string()) - .fetch_one(&self.inner) - .await? - .map(|row| sql_row_to_mint_quote(row, payments, issuance)) - .transpose()?) + get_mint_quote_inner(&self.inner, quote_id, true).await } async fn get_melt_quote( &mut self, quote_id: &QuoteId, ) -> Result, Self::Err> { - Ok(query( - r#" - SELECT - id, - unit, - amount, - request, - fee_reserve, - expiry, - state, - payment_preimage, - request_lookup_id, - created_time, - paid_time, - payment_method, - options, - request_lookup_id - FROM - melt_quote - WHERE - id=:id - "#, - )? - .bind("id", quote_id.to_string()) - .fetch_one(&self.inner) - .await? - .map(sql_row_to_melt_quote) - .transpose()?) + get_melt_quote_inner(&self.inner, quote_id, true).await } async fn get_mint_quote_by_request( &mut self, request: &str, ) -> Result, Self::Err> { - let mut mint_quote = query( - r#" - SELECT - id, - amount, - unit, - request, - expiry, - request_lookup_id, - pubkey, - created_time, - amount_paid, - amount_issued, - payment_method, - request_lookup_id_kind - FROM - mint_quote - WHERE request = :request - FOR UPDATE - "#, - )? - .bind("request", request.to_string()) - .fetch_one(&self.inner) - .await? - .map(|row| sql_row_to_mint_quote(row, vec![], vec![])) - .transpose()?; - - if let Some(quote) = mint_quote.as_mut() { - let payments = get_mint_quote_payments(&self.inner, "e.id).await?; - let issuance = get_mint_quote_issuance(&self.inner, "e.id).await?; - quote.issuance = issuance; - quote.payments = payments; - } - - Ok(mint_quote) + get_mint_quote_by_request_inner(&self.inner, request, true).await } async fn get_mint_quote_by_request_lookup_id( &mut self, request_lookup_id: &PaymentIdentifier, ) -> Result, Self::Err> { - let mut mint_quote = query( - r#" - SELECT - id, - amount, - unit, - request, - expiry, - request_lookup_id, - pubkey, - created_time, - amount_paid, - amount_issued, - payment_method, - request_lookup_id_kind - FROM - mint_quote - WHERE request_lookup_id = :request_lookup_id - AND request_lookup_id_kind = :request_lookup_id_kind - FOR UPDATE - "#, - )? - .bind("request_lookup_id", request_lookup_id.to_string()) - .bind("request_lookup_id_kind", request_lookup_id.kind()) - .fetch_one(&self.inner) - .await? - .map(|row| sql_row_to_mint_quote(row, vec![], vec![])) - .transpose()?; - - if let Some(quote) = mint_quote.as_mut() { - let payments = get_mint_quote_payments(&self.inner, "e.id).await?; - let issuance = get_mint_quote_issuance(&self.inner, "e.id).await?; - quote.issuance = issuance; - quote.payments = payments; - } - - Ok(mint_quote) + get_mint_quote_by_request_lookup_id_inner(&self.inner, request_lookup_id, true).await } } @@ -1270,36 +1332,7 @@ where let start_time = std::time::Instant::now(); let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; - let result = async { - let payments = get_mint_quote_payments(&*conn, quote_id).await?; - let issuance = get_mint_quote_issuance(&*conn, quote_id).await?; - - query( - r#" - SELECT - id, - amount, - unit, - request, - expiry, - request_lookup_id, - pubkey, - created_time, - amount_paid, - amount_issued, - payment_method, - request_lookup_id_kind - FROM - mint_quote - WHERE id = :id"#, - )? - .bind("id", quote_id.to_string()) - .fetch_one(&*conn) - .await? - .map(|row| sql_row_to_mint_quote(row, payments, issuance)) - .transpose() - } - .await; + let result = get_mint_quote_inner(&*conn, quote_id, false).await; #[cfg(feature = "prometheus")] { @@ -1322,39 +1355,7 @@ where request: &str, ) -> Result, Self::Err> { let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; - let mut mint_quote = query( - r#" - SELECT - id, - amount, - unit, - request, - expiry, - request_lookup_id, - pubkey, - created_time, - amount_paid, - amount_issued, - payment_method, - request_lookup_id_kind - FROM - mint_quote - WHERE request = :request"#, - )? - .bind("request", request.to_owned()) - .fetch_one(&*conn) - .await? - .map(|row| sql_row_to_mint_quote(row, vec![], vec![])) - .transpose()?; - - if let Some(quote) = mint_quote.as_mut() { - let payments = get_mint_quote_payments(&*conn, "e.id).await?; - let issuance = get_mint_quote_issuance(&*conn, "e.id).await?; - quote.issuance = issuance; - quote.payments = payments; - } - - Ok(mint_quote) + get_mint_quote_by_request_inner(&*conn, request, false).await } async fn get_mint_quote_by_request_lookup_id( @@ -1362,43 +1363,7 @@ where request_lookup_id: &PaymentIdentifier, ) -> Result, Self::Err> { let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; - let mut mint_quote = query( - r#" - SELECT - id, - amount, - unit, - request, - expiry, - request_lookup_id, - pubkey, - created_time, - amount_paid, - amount_issued, - payment_method, - request_lookup_id_kind - FROM - mint_quote - WHERE request_lookup_id = :request_lookup_id - AND request_lookup_id_kind = :request_lookup_id_kind - "#, - )? - .bind("request_lookup_id", request_lookup_id.to_string()) - .bind("request_lookup_id_kind", request_lookup_id.kind()) - .fetch_one(&*conn) - .await? - .map(|row| sql_row_to_mint_quote(row, vec![], vec![])) - .transpose()?; - - // TODO: these should use an sql join so they can be done in one query - if let Some(quote) = mint_quote.as_mut() { - let payments = get_mint_quote_payments(&*conn, "e.id).await?; - let issuance = get_mint_quote_issuance(&*conn, "e.id).await?; - quote.issuance = issuance; - quote.payments = payments; - } - - Ok(mint_quote) + get_mint_quote_by_request_lookup_id_inner(&*conn, request_lookup_id, false).await } async fn get_mint_quotes(&self) -> Result, Self::Err> { @@ -1449,37 +1414,7 @@ where let start_time = std::time::Instant::now(); let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; - let result = async { - query( - r#" - SELECT - id, - unit, - amount, - request, - fee_reserve, - expiry, - state, - payment_preimage, - request_lookup_id, - created_time, - paid_time, - payment_method, - options, - request_lookup_id_kind - FROM - melt_quote - WHERE - id=:id - "#, - )? - .bind("id", quote_id.to_string()) - .fetch_one(&*conn) - .await? - .map(sql_row_to_melt_quote) - .transpose() - } - .await; + let result = get_melt_quote_inner(&*conn, quote_id, false).await; #[cfg(feature = "prometheus")] { From 98a3881993f8fdbbbc2054d26094c9e249d24228 Mon Sep 17 00:00:00 2001 From: C Date: Sun, 23 Nov 2025 19:31:30 -0300 Subject: [PATCH 298/321] Batch websocket notification reads in integration tests (#1330) Refactor the get_notification helper to get_notifications to read multiple websocket messages at once, improving test reliability when multiple notifications arrive in quick succession. --- .../tests/happy_path_mint_wallet.rs | 69 +++++++++++-------- 1 file changed, 39 insertions(+), 30 deletions(-) diff --git a/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs b/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs index 8e3f77e85..ef95cdfcf 100644 --- a/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs +++ b/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs @@ -40,36 +40,41 @@ fn get_test_temp_dir() -> PathBuf { } } -async fn get_notification> + Unpin, E: Debug>( +async fn get_notifications> + Unpin, E: Debug>( reader: &mut T, timeout_to_wait: Duration, -) -> (String, NotificationPayload) { - let msg = timeout(timeout_to_wait, reader.next()) - .await - .expect("timeout") - .unwrap() - .unwrap(); - - let mut response: serde_json::Value = - serde_json::from_str(msg.to_text().unwrap()).expect("valid json"); - - let mut params_raw = response - .as_object_mut() - .expect("object") - .remove("params") - .expect("valid params"); - - let params_map = params_raw.as_object_mut().expect("params is object"); - - ( - params_map - .remove("subId") + total: usize, +) -> Vec<(String, NotificationPayload)> { + let mut results = Vec::new(); + for _ in 0..total { + let msg = timeout(timeout_to_wait, reader.next()) + .await + .expect("timeout") .unwrap() - .as_str() - .unwrap() - .to_string(), - serde_json::from_value(params_map.remove("payload").unwrap()).unwrap(), - ) + .unwrap(); + + let mut response: serde_json::Value = + serde_json::from_str(msg.to_text().unwrap()).expect("valid json"); + + let mut params_raw = response + .as_object_mut() + .expect("object") + .remove("params") + .expect("valid params"); + + let params_map = params_raw.as_object_mut().expect("params is object"); + + results.push(( + params_map + .remove("subId") + .unwrap() + .as_str() + .unwrap() + .to_string(), + serde_json::from_value(params_map.remove("payload").unwrap()).unwrap(), + )) + } + results } /// Tests a complete mint-melt round trip with WebSocket notifications @@ -180,7 +185,11 @@ async fn test_happy_mint_melt_round_trip() { assert_eq!(tx.amount, melt.amount); assert_eq!(tx.metadata, metadata); - let (sub_id, payload) = get_notification(&mut reader, Duration::from_millis(15000)).await; + let mut notifications = get_notifications(&mut reader, Duration::from_millis(15000), 3).await; + notifications.reverse(); + + let (sub_id, payload) = notifications.pop().unwrap(); + // first message is the current state assert_eq!("test-sub", sub_id); let payload = match payload { @@ -193,7 +202,7 @@ async fn test_happy_mint_melt_round_trip() { assert_eq!(payload.state, MeltQuoteState::Unpaid); // get current state - let (sub_id, payload) = get_notification(&mut reader, Duration::from_millis(15000)).await; + let (sub_id, payload) = notifications.pop().unwrap(); assert_eq!("test-sub", sub_id); let payload = match payload { NotificationPayload::MeltQuoteBolt11Response(melt) => melt, @@ -203,7 +212,7 @@ async fn test_happy_mint_melt_round_trip() { assert_eq!(payload.state, MeltQuoteState::Pending); // get current state - let (sub_id, payload) = get_notification(&mut reader, Duration::from_millis(15000)).await; + let (sub_id, payload) = notifications.pop().unwrap(); assert_eq!("test-sub", sub_id); let payload = match payload { NotificationPayload::MeltQuoteBolt11Response(melt) => melt, From d00ad9d346b4a87c97c8b3e575a080effd38ecd5 Mon Sep 17 00:00:00 2001 From: tsk Date: Mon, 24 Nov 2025 12:21:53 +0000 Subject: [PATCH 299/321] feat: multimint_ffi melt with mint (#1332) --- crates/cdk-ffi/src/multi_mint_wallet.rs | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/crates/cdk-ffi/src/multi_mint_wallet.rs b/crates/cdk-ffi/src/multi_mint_wallet.rs index c3114ae9e..79ad82ca8 100644 --- a/crates/cdk-ffi/src/multi_mint_wallet.rs +++ b/crates/cdk-ffi/src/multi_mint_wallet.rs @@ -431,6 +431,17 @@ impl MultiMintWallet { Ok(quote.into()) } + /// Melt tokens + pub async fn melt_with_mint( + &self, + mint_url: MintUrl, + quote_id: String, + ) -> Result { + let cdk_mint_url: cdk::mint_url::MintUrl = mint_url.try_into()?; + let melted = self.inner.melt_with_mint(&cdk_mint_url, "e_id).await?; + Ok(melted.into()) + } + /// Melt tokens (pay a bolt11 invoice) pub async fn melt( &self, From eee20eaf527bc478c0c352bd3511661b05c57bbf Mon Sep 17 00:00:00 2001 From: tsk Date: Mon, 24 Nov 2025 13:03:00 +0000 Subject: [PATCH 300/321] feat: remove deprecated paid field (#1334) --- crates/cashu/src/nuts/nut23.rs | 107 +--------------------- crates/cdk-common/src/mint.rs | 3 - crates/cdk/src/mint/melt/melt_saga/mod.rs | 1 - crates/cdk/src/mint/melt/mod.rs | 2 - crates/cdk/src/mint/subscription.rs | 1 - 5 files changed, 3 insertions(+), 111 deletions(-) diff --git a/crates/cashu/src/nuts/nut23.rs b/crates/cashu/src/nuts/nut23.rs index 1ea87703b..452779a24 100644 --- a/crates/cashu/src/nuts/nut23.rs +++ b/crates/cashu/src/nuts/nut23.rs @@ -5,8 +5,7 @@ use std::str::FromStr; use lightning_invoice::Bolt11Invoice; use serde::de::DeserializeOwned; -use serde::{Deserialize, Deserializer, Serialize}; -use serde_json::Value; +use serde::{Deserialize, Serialize}; use thiserror::Error; use super::{BlindSignature, CurrencyUnit, MeltQuoteState, Mpp, PublicKey}; @@ -239,9 +238,9 @@ impl MeltQuoteBolt11Request { } /// Melt quote response [NUT-05] -#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] #[cfg_attr(feature = "swagger", derive(utoipa::ToSchema))] -#[serde(bound = "Q: Serialize")] +#[serde(bound = "Q: Serialize + DeserializeOwned")] pub struct MeltQuoteBolt11Response { /// Quote Id pub quote: Q, @@ -249,10 +248,6 @@ pub struct MeltQuoteBolt11Response { pub amount: Amount, /// The fee reserve that is required pub fee_reserve: Amount, - /// Whether the request haas be paid - // TODO: To be deprecated - /// Deprecated - pub paid: Option, /// Quote State pub state: MeltQuoteState, /// Unix timestamp until the quote is valid @@ -281,7 +276,6 @@ impl MeltQuoteBolt11Response { quote: self.quote.to_string(), amount: self.amount, fee_reserve: self.fee_reserve, - paid: self.paid, state: self.state, expiry: self.expiry, payment_preimage: self.payment_preimage, @@ -299,7 +293,6 @@ impl From> for MeltQuoteBolt11Response quote: value.quote.to_string(), amount: value.amount, fee_reserve: value.fee_reserve, - paid: value.paid, state: value.state, expiry: value.expiry, payment_preimage: value.payment_preimage, @@ -309,97 +302,3 @@ impl From> for MeltQuoteBolt11Response } } } - -// A custom deserializer is needed until all mints -// update some will return without the required state. -impl<'de, Q: DeserializeOwned> Deserialize<'de> for MeltQuoteBolt11Response { - fn deserialize(deserializer: D) -> Result - where - D: Deserializer<'de>, - { - let value = Value::deserialize(deserializer)?; - - let quote: Q = serde_json::from_value( - value - .get("quote") - .ok_or(serde::de::Error::missing_field("quote"))? - .clone(), - ) - .map_err(|_| serde::de::Error::custom("Invalid quote if string"))?; - - let amount = value - .get("amount") - .ok_or(serde::de::Error::missing_field("amount"))? - .as_u64() - .ok_or(serde::de::Error::missing_field("amount"))?; - let amount = Amount::from(amount); - - let fee_reserve = value - .get("fee_reserve") - .ok_or(serde::de::Error::missing_field("fee_reserve"))? - .as_u64() - .ok_or(serde::de::Error::missing_field("fee_reserve"))?; - - let fee_reserve = Amount::from(fee_reserve); - - let paid: Option = value.get("paid").and_then(|p| p.as_bool()); - - let state: Option = value - .get("state") - .and_then(|s| serde_json::from_value(s.clone()).ok()); - - let (state, paid) = match (state, paid) { - (None, None) => return Err(serde::de::Error::custom("State or paid must be defined")), - (Some(state), _) => { - let state: MeltQuoteState = MeltQuoteState::from_str(&state) - .map_err(|_| serde::de::Error::custom("Unknown state"))?; - let paid = state == MeltQuoteState::Paid; - - (state, paid) - } - (None, Some(paid)) => { - let state = if paid { - MeltQuoteState::Paid - } else { - MeltQuoteState::Unpaid - }; - (state, paid) - } - }; - - let expiry = value - .get("expiry") - .ok_or(serde::de::Error::missing_field("expiry"))? - .as_u64() - .ok_or(serde::de::Error::missing_field("expiry"))?; - - let payment_preimage: Option = value - .get("payment_preimage") - .and_then(|p| serde_json::from_value(p.clone()).ok()); - - let change: Option> = value - .get("change") - .and_then(|b| serde_json::from_value(b.clone()).ok()); - - let request: Option = value - .get("request") - .and_then(|r| serde_json::from_value(r.clone()).ok()); - - let unit: Option = value - .get("unit") - .and_then(|u| serde_json::from_value(u.clone()).ok()); - - Ok(Self { - quote, - amount, - fee_reserve, - paid: Some(paid), - state, - expiry, - payment_preimage, - change, - request, - unit, - }) - } -} diff --git a/crates/cdk-common/src/mint.rs b/crates/cdk-common/src/mint.rs index d9d3d13f6..12600047b 100644 --- a/crates/cdk-common/src/mint.rs +++ b/crates/cdk-common/src/mint.rs @@ -673,7 +673,6 @@ impl From<&MeltQuote> for MeltQuoteBolt11Response { payment_preimage: None, change: None, state: melt_quote.state, - paid: Some(melt_quote.state == MeltQuoteState::Paid), expiry: melt_quote.expiry, amount: melt_quote.amount, fee_reserve: melt_quote.fee_reserve, @@ -685,12 +684,10 @@ impl From<&MeltQuote> for MeltQuoteBolt11Response { impl From for MeltQuoteBolt11Response { fn from(melt_quote: MeltQuote) -> MeltQuoteBolt11Response { - let paid = melt_quote.state == MeltQuoteState::Paid; MeltQuoteBolt11Response { quote: melt_quote.id.clone(), amount: melt_quote.amount, fee_reserve: melt_quote.fee_reserve, - paid: Some(paid), state: melt_quote.state, expiry: melt_quote.expiry, payment_preimage: melt_quote.payment_preimage, diff --git a/crates/cdk/src/mint/melt/melt_saga/mod.rs b/crates/cdk/src/mint/melt/melt_saga/mod.rs index 464581308..8d85f5e4b 100644 --- a/crates/cdk/src/mint/melt/melt_saga/mod.rs +++ b/crates/cdk/src/mint/melt/melt_saga/mod.rs @@ -931,7 +931,6 @@ impl MeltSaga { let response = MeltQuoteBolt11Response { amount: self.state_data.quote.amount, - paid: Some(true), payment_preimage, change, quote: self.state_data.quote.id, diff --git a/crates/cdk/src/mint/melt/mod.rs b/crates/cdk/src/mint/melt/mod.rs index 3b92e809f..9d2917150 100644 --- a/crates/cdk/src/mint/melt/mod.rs +++ b/crates/cdk/src/mint/melt/mod.rs @@ -390,7 +390,6 @@ impl Mint { let response = MeltQuoteBolt11Response { quote: quote.id, - paid: Some(quote.state == MeltQuoteState::Paid), state: quote.state, expiry: quote.expiry, amount: quote.amount, @@ -543,7 +542,6 @@ impl Mint { amount: quote.amount, fee_reserve: quote.fee_reserve, state: quote.state, - paid: Some(false), expiry: quote.expiry, payment_preimage: None, change: None, diff --git a/crates/cdk/src/mint/subscription.rs b/crates/cdk/src/mint/subscription.rs index 48b0ecbc4..ada422cb9 100644 --- a/crates/cdk/src/mint/subscription.rs +++ b/crates/cdk/src/mint/subscription.rs @@ -267,7 +267,6 @@ impl PubSubManager { ) { let mut quote = quote.into(); quote.state = new_state; - quote.paid = Some(new_state == MeltQuoteState::Paid); quote.payment_preimage = payment_preimage; quote.change = change; self.publish(quote); From 24f9a508d53a2bae53d821c862caaf7e9e2f93da Mon Sep 17 00:00:00 2001 From: C Date: Tue, 25 Nov 2025 08:33:58 -0300 Subject: [PATCH 301/321] Remove max_order from keyset database schema (#1329) * Remove max_order from keyset database schema Fixes #1074 Remove the max_order column from the keyset table across the mint database layer, replacing it with the amounts field that was already being used. This simplifies the schema by eliminating redundant data. * Extract standard keyset amounts generation to reusable function Consolidates repeated pattern of `(0..32).map(|n| 2u64.pow(n)).collect()` into a single reusable helper function. This reduces code duplication and makes the keyset amount generation pattern more maintainable. --- .../cdk-common/src/database/mint/test/mod.rs | 9 +- crates/cdk-common/src/mint.rs | 2 - crates/cdk-integration-tests/src/lib.rs | 11 +++ .../tests/integration_tests_pure.rs | 18 +++- crates/cdk-integration-tests/tests/mint.rs | 16 +++- .../tests/test_swap_flow.rs | 20 ++-- .../subcommands/rotate_next_keyset.rs | 19 +++- .../cdk-mint-rpc/src/proto/cdk-mint-rpc.proto | 4 +- crates/cdk-mint-rpc/src/proto/server.rs | 14 +-- crates/cdk-signatory/src/common.rs | 1 - crates/cdk-signatory/src/signatory.rs | 1 - .../20251122000000_drop_max_order.sql | 2 + .../sqlite/20251122000000_drop_max_order.sql | 28 ++++++ crates/cdk-sql-common/src/mint/auth/mod.rs | 12 +-- .../20251122000000_drop_max_order.sql | 2 + .../sqlite/20251122000000_drop_max_order.sql | 30 ++++++ crates/cdk-sql-common/src/mint/mod.rs | 91 ++----------------- crates/cdk/src/mint/builder.rs | 2 +- crates/cdk/src/mint/keysets/mod.rs | 4 +- crates/cdk/src/mint/mod.rs | 2 +- 20 files changed, 166 insertions(+), 122 deletions(-) create mode 100644 crates/cdk-sql-common/src/mint/auth/migrations/postgres/20251122000000_drop_max_order.sql create mode 100644 crates/cdk-sql-common/src/mint/auth/migrations/sqlite/20251122000000_drop_max_order.sql create mode 100644 crates/cdk-sql-common/src/mint/migrations/postgres/20251122000000_drop_max_order.sql create mode 100644 crates/cdk-sql-common/src/mint/migrations/sqlite/20251122000000_drop_max_order.sql diff --git a/crates/cdk-common/src/database/mint/test/mod.rs b/crates/cdk-common/src/database/mint/test/mod.rs index c212a54ec..1b6b99334 100644 --- a/crates/cdk-common/src/database/mint/test/mod.rs +++ b/crates/cdk-common/src/database/mint/test/mod.rs @@ -22,6 +22,12 @@ mod proofs; pub use self::mint::*; pub use self::proofs::*; +/// Generate standard keyset amounts as powers of 2 +#[inline] +fn standard_keyset_amounts(max_order: u32) -> Vec { + (0..max_order).map(|n| 2u64.pow(n)).collect() +} + #[inline] async fn setup_keyset(db: &DB) -> Id where @@ -36,9 +42,8 @@ where final_expiry: None, derivation_path: DerivationPath::from_str("m/0'/0'/0'").unwrap(), derivation_path_index: Some(0), - max_order: 32, input_fee_ppk: 0, - amounts: vec![], + amounts: standard_keyset_amounts(32), }; let mut writer = db.begin_transaction().await.expect("db.begin()"); writer.add_keyset_info(keyset_info).await.unwrap(); diff --git a/crates/cdk-common/src/mint.rs b/crates/cdk-common/src/mint.rs index 12600047b..b0e5d5cc8 100644 --- a/crates/cdk-common/src/mint.rs +++ b/crates/cdk-common/src/mint.rs @@ -589,8 +589,6 @@ pub struct MintKeySetInfo { pub derivation_path: DerivationPath, /// DerivationPath index of Keyset pub derivation_path_index: Option, - /// Max order of keyset - pub max_order: u8, /// Supported amounts pub amounts: Vec, /// Input Fee ppk diff --git a/crates/cdk-integration-tests/src/lib.rs b/crates/cdk-integration-tests/src/lib.rs index 3660ffa92..65e274647 100644 --- a/crates/cdk-integration-tests/src/lib.rs +++ b/crates/cdk-integration-tests/src/lib.rs @@ -36,6 +36,17 @@ pub mod init_pure_tests; pub mod init_regtest; pub mod shared; +/// Generate standard keyset amounts as powers of 2 +/// +/// Returns a vector of amounts: [1, 2, 4, 8, 16, 32, ..., 2^(n-1)] +/// where n is the number of amounts to generate. +/// +/// # Arguments +/// * `max_order` - The maximum power of 2 (exclusive). For example, max_order=32 generates amounts up to 2^31 +pub fn standard_keyset_amounts(max_order: u32) -> Vec { + (0..max_order).map(|n| 2u64.pow(n)).collect() +} + pub async fn fund_wallet(wallet: Arc, amount: Amount) { let quote = wallet .mint_quote(amount, None) diff --git a/crates/cdk-integration-tests/tests/integration_tests_pure.rs b/crates/cdk-integration-tests/tests/integration_tests_pure.rs index 40abf6e20..52099fcb2 100644 --- a/crates/cdk-integration-tests/tests/integration_tests_pure.rs +++ b/crates/cdk-integration-tests/tests/integration_tests_pure.rs @@ -565,7 +565,11 @@ async fn test_swap_overpay_underpay_fee() { .expect("Failed to create test mint"); mint_bob - .rotate_keyset(CurrencyUnit::Sat, 32, 1) + .rotate_keyset( + CurrencyUnit::Sat, + cdk_integration_tests::standard_keyset_amounts(32), + 1, + ) .await .unwrap(); @@ -640,7 +644,11 @@ async fn test_mint_enforce_fee() { .expect("Failed to create test mint"); mint_bob - .rotate_keyset(CurrencyUnit::Sat, 32, 1) + .rotate_keyset( + CurrencyUnit::Sat, + cdk_integration_tests::standard_keyset_amounts(32), + 1, + ) .await .unwrap(); @@ -749,7 +757,11 @@ async fn test_mint_change_with_fee_melt() { .expect("Failed to create test mint"); mint_bob - .rotate_keyset(CurrencyUnit::Sat, 32, 1) + .rotate_keyset( + CurrencyUnit::Sat, + cdk_integration_tests::standard_keyset_amounts(32), + 1, + ) .await .unwrap(); diff --git a/crates/cdk-integration-tests/tests/mint.rs b/crates/cdk-integration-tests/tests/mint.rs index a84c05a96..5ec0ca963 100644 --- a/crates/cdk-integration-tests/tests/mint.rs +++ b/crates/cdk-integration-tests/tests/mint.rs @@ -74,7 +74,13 @@ async fn test_correct_keyset() { .expect("There is a keyset for unit"); let old_keyset_info = mint.get_keyset_info(active).expect("There is keyset"); - mint.rotate_keyset(CurrencyUnit::Sat, 32, 0).await.unwrap(); + mint.rotate_keyset( + CurrencyUnit::Sat, + cdk_integration_tests::standard_keyset_amounts(32), + 0, + ) + .await + .unwrap(); let active = mint.get_active_keysets(); @@ -86,7 +92,13 @@ async fn test_correct_keyset() { assert_ne!(keyset_info.id, old_keyset_info.id); - mint.rotate_keyset(CurrencyUnit::Sat, 32, 0).await.unwrap(); + mint.rotate_keyset( + CurrencyUnit::Sat, + cdk_integration_tests::standard_keyset_amounts(32), + 0, + ) + .await + .unwrap(); let active = mint.get_active_keysets(); diff --git a/crates/cdk-integration-tests/tests/test_swap_flow.rs b/crates/cdk-integration-tests/tests/test_swap_flow.rs index d6f90282d..38d9e3439 100644 --- a/crates/cdk-integration-tests/tests/test_swap_flow.rs +++ b/crates/cdk-integration-tests/tests/test_swap_flow.rs @@ -657,9 +657,13 @@ async fn test_swap_with_fees() { .expect("Failed to create test wallet"); // Rotate to keyset with 1 sat per proof fee - mint.rotate_keyset(CurrencyUnit::Sat, 32, 1) - .await - .expect("Failed to rotate keyset"); + mint.rotate_keyset( + CurrencyUnit::Sat, + cdk_integration_tests::standard_keyset_amounts(32), + 1, + ) + .await + .expect("Failed to rotate keyset"); // Fund with 1000 sats as individual 1-sat proofs using the fee-based keyset // Wait a bit for keyset to be available @@ -973,9 +977,13 @@ async fn test_wallet_multi_keyset_counter_updates() { let first_keyset_id = get_keyset_id(&mint).await; // Rotate to a second keyset - mint.rotate_keyset(CurrencyUnit::Sat, 32, 0) - .await - .expect("Failed to rotate keyset"); + mint.rotate_keyset( + CurrencyUnit::Sat, + cdk_integration_tests::standard_keyset_amounts(32), + 0, + ) + .await + .expect("Failed to rotate keyset"); // Wait for keyset rotation to propagate tokio::time::sleep(std::time::Duration::from_millis(100)).await; diff --git a/crates/cdk-mint-rpc/src/mint_rpc_cli/subcommands/rotate_next_keyset.rs b/crates/cdk-mint-rpc/src/mint_rpc_cli/subcommands/rotate_next_keyset.rs index 7e4137c6d..76661413c 100644 --- a/crates/cdk-mint-rpc/src/mint_rpc_cli/subcommands/rotate_next_keyset.rs +++ b/crates/cdk-mint-rpc/src/mint_rpc_cli/subcommands/rotate_next_keyset.rs @@ -16,9 +16,9 @@ pub struct RotateNextKeysetCommand { #[arg(short, long)] #[arg(default_value = "sat")] unit: String, - /// The maximum order (power of 2) for tokens that can be minted with this keyset + /// The amounts that can be minted with this keyset (e.g., "1,2,4,8,16") #[arg(short, long)] - max_order: Option, + amounts: Option, /// The input fee in parts per thousand to apply when minting with this keyset #[arg(short, long)] input_fee_ppk: Option, @@ -36,10 +36,19 @@ pub async fn rotate_next_keyset( client: &mut CdkMintClient, sub_command_args: &RotateNextKeysetCommand, ) -> Result<()> { + let amounts = if let Some(amounts_str) = &sub_command_args.amounts { + amounts_str + .split(',') + .map(|s| s.trim().parse::()) + .collect::, _>>()? + } else { + vec![] + }; + let response = client .rotate_next_keyset(Request::new(RotateNextKeysetRequest { unit: sub_command_args.unit.clone(), - max_order: sub_command_args.max_order.map(|m| m.into()), + amounts, input_fee_ppk: sub_command_args.input_fee_ppk, })) .await?; @@ -47,8 +56,8 @@ pub async fn rotate_next_keyset( let response = response.into_inner(); println!( - "Rotated to new keyset {} for unit {} with a max order of {} and fee of {}", - response.id, response.unit, response.max_order, response.input_fee_ppk + "Rotated to new keyset {} for unit {} with amounts {:?} and fee of {}", + response.id, response.unit, response.amounts, response.input_fee_ppk ); Ok(()) diff --git a/crates/cdk-mint-rpc/src/proto/cdk-mint-rpc.proto b/crates/cdk-mint-rpc/src/proto/cdk-mint-rpc.proto index 21b1e3f5c..32990637c 100644 --- a/crates/cdk-mint-rpc/src/proto/cdk-mint-rpc.proto +++ b/crates/cdk-mint-rpc/src/proto/cdk-mint-rpc.proto @@ -122,7 +122,7 @@ message UpdateNut04QuoteRequest { message RotateNextKeysetRequest { string unit = 1; - optional uint32 max_order = 2; + repeated uint64 amounts = 2; optional uint64 input_fee_ppk = 3; } @@ -130,6 +130,6 @@ message RotateNextKeysetRequest { message RotateNextKeysetResponse { string id = 1; string unit = 2; - uint32 max_order = 3; + repeated uint64 amounts = 3; uint64 input_fee_ppk = 4; } diff --git a/crates/cdk-mint-rpc/src/proto/server.rs b/crates/cdk-mint-rpc/src/proto/server.rs index c8c2d6b8f..fed764fac 100644 --- a/crates/cdk-mint-rpc/src/proto/server.rs +++ b/crates/cdk-mint-rpc/src/proto/server.rs @@ -730,20 +730,22 @@ impl CdkMint for MintRPCServer { let unit = CurrencyUnit::from_str(&request.unit) .map_err(|_| Status::invalid_argument("Invalid unit".to_string()))?; + let amounts = if request.amounts.is_empty() { + return Err(Status::invalid_argument("amounts cannot be empty")); + } else { + request.amounts + }; + let keyset_info = self .mint - .rotate_keyset( - unit, - request.max_order.map(|a| a as u8).unwrap_or(32), - request.input_fee_ppk.unwrap_or(0), - ) + .rotate_keyset(unit, amounts, request.input_fee_ppk.unwrap_or(0)) .await .map_err(|_| Status::invalid_argument("Could not rotate keyset".to_string()))?; Ok(Response::new(RotateNextKeysetResponse { id: keyset_info.id.to_string(), unit: keyset_info.unit.to_string(), - max_order: keyset_info.max_order.into(), + amounts: keyset_info.amounts, input_fee_ppk: keyset_info.input_fee_ppk, })) } diff --git a/crates/cdk-signatory/src/common.rs b/crates/cdk-signatory/src/common.rs index b6c39deed..bae0bc045 100644 --- a/crates/cdk-signatory/src/common.rs +++ b/crates/cdk-signatory/src/common.rs @@ -151,7 +151,6 @@ pub fn create_new_keyset( final_expiry: keyset.final_expiry, derivation_path, derivation_path_index, - max_order: 0, amounts: amounts.to_owned(), input_fee_ppk, }; diff --git a/crates/cdk-signatory/src/signatory.rs b/crates/cdk-signatory/src/signatory.rs index 27cf8fef4..dad64bf25 100644 --- a/crates/cdk-signatory/src/signatory.rs +++ b/crates/cdk-signatory/src/signatory.rs @@ -111,7 +111,6 @@ impl From for MintKeySetInfo { input_fee_ppk: val.input_fee_ppk, derivation_path: Default::default(), derivation_path_index: Default::default(), - max_order: 0, amounts: val.amounts, final_expiry: val.final_expiry, valid_from: 0, diff --git a/crates/cdk-sql-common/src/mint/auth/migrations/postgres/20251122000000_drop_max_order.sql b/crates/cdk-sql-common/src/mint/auth/migrations/postgres/20251122000000_drop_max_order.sql new file mode 100644 index 000000000..1d1ebbd39 --- /dev/null +++ b/crates/cdk-sql-common/src/mint/auth/migrations/postgres/20251122000000_drop_max_order.sql @@ -0,0 +1,2 @@ +-- Drop max_order column from keyset table +ALTER TABLE keyset DROP COLUMN IF EXISTS max_order; diff --git a/crates/cdk-sql-common/src/mint/auth/migrations/sqlite/20251122000000_drop_max_order.sql b/crates/cdk-sql-common/src/mint/auth/migrations/sqlite/20251122000000_drop_max_order.sql new file mode 100644 index 000000000..0e862638c --- /dev/null +++ b/crates/cdk-sql-common/src/mint/auth/migrations/sqlite/20251122000000_drop_max_order.sql @@ -0,0 +1,28 @@ +-- Drop max_order column from keyset table +-- SQLite doesn't support DROP COLUMN directly, so we need to recreate the table + +-- Create new table without max_order +CREATE TABLE keyset_new ( + id TEXT PRIMARY KEY, + unit TEXT NOT NULL, + active BOOL NOT NULL, + valid_from INTEGER NOT NULL, + valid_to INTEGER, + derivation_path TEXT NOT NULL, + derivation_path_index INTEGER NOT NULL +); + +-- Copy data from old table to new table +INSERT INTO keyset_new (id, unit, active, valid_from, valid_to, derivation_path, derivation_path_index) +SELECT id, unit, active, valid_from, valid_to, derivation_path, derivation_path_index +FROM keyset; + +-- Drop old table +DROP TABLE keyset; + +-- Rename new table to original name +ALTER TABLE keyset_new RENAME TO keyset; + +-- Recreate indexes +CREATE INDEX IF NOT EXISTS unit_index ON keyset(unit); +CREATE INDEX IF NOT EXISTS active_index ON keyset(active); diff --git a/crates/cdk-sql-common/src/mint/auth/mod.rs b/crates/cdk-sql-common/src/mint/auth/mod.rs index cd5739567..d998d3375 100644 --- a/crates/cdk-sql-common/src/mint/auth/mod.rs +++ b/crates/cdk-sql-common/src/mint/auth/mod.rs @@ -88,11 +88,11 @@ where INSERT INTO keyset ( id, unit, active, valid_from, valid_to, derivation_path, - max_order, derivation_path_index + amounts, input_fee_ppk, derivation_path_index ) VALUES ( :id, :unit, :active, :valid_from, :valid_to, :derivation_path, - :max_order, :derivation_path_index + :amounts, :input_fee_ppk, :derivation_path_index ) ON CONFLICT(id) DO UPDATE SET unit = excluded.unit, @@ -100,7 +100,8 @@ where valid_from = excluded.valid_from, valid_to = excluded.valid_to, derivation_path = excluded.derivation_path, - max_order = excluded.max_order, + amounts = excluded.amounts, + input_fee_ppk = excluded.input_fee_ppk, derivation_path_index = excluded.derivation_path_index "#, )? @@ -110,7 +111,8 @@ where .bind("valid_from", keyset.valid_from as i64) .bind("valid_to", keyset.final_expiry.map(|v| v as i64)) .bind("derivation_path", keyset.derivation_path.to_string()) - .bind("max_order", keyset.max_order) + .bind("amounts", serde_json::to_string(&keyset.amounts).ok()) + .bind("input_fee_ppk", keyset.input_fee_ppk as i64) .bind("derivation_path_index", keyset.derivation_path_index) .execute(&self.inner) .await?; @@ -286,7 +288,6 @@ where valid_to, derivation_path, derivation_path_index, - max_order, amounts, input_fee_ppk FROM @@ -311,7 +312,6 @@ where valid_to, derivation_path, derivation_path_index, - max_order, amounts, input_fee_ppk FROM diff --git a/crates/cdk-sql-common/src/mint/migrations/postgres/20251122000000_drop_max_order.sql b/crates/cdk-sql-common/src/mint/migrations/postgres/20251122000000_drop_max_order.sql new file mode 100644 index 000000000..1d1ebbd39 --- /dev/null +++ b/crates/cdk-sql-common/src/mint/migrations/postgres/20251122000000_drop_max_order.sql @@ -0,0 +1,2 @@ +-- Drop max_order column from keyset table +ALTER TABLE keyset DROP COLUMN IF EXISTS max_order; diff --git a/crates/cdk-sql-common/src/mint/migrations/sqlite/20251122000000_drop_max_order.sql b/crates/cdk-sql-common/src/mint/migrations/sqlite/20251122000000_drop_max_order.sql new file mode 100644 index 000000000..e03cdd7dc --- /dev/null +++ b/crates/cdk-sql-common/src/mint/migrations/sqlite/20251122000000_drop_max_order.sql @@ -0,0 +1,30 @@ +-- Drop max_order column from keyset table +-- SQLite doesn't support DROP COLUMN directly, so we need to recreate the table + +-- Create new table without max_order +CREATE TABLE keyset_new ( + id TEXT PRIMARY KEY, + unit TEXT NOT NULL, + active BOOL NOT NULL, + valid_from INTEGER NOT NULL, + valid_to INTEGER, + derivation_path TEXT NOT NULL, + input_fee_ppk INTEGER, + derivation_path_index INTEGER, + amounts TEXT +); + +-- Copy data from old table to new table +INSERT INTO keyset_new (id, unit, active, valid_from, valid_to, derivation_path, input_fee_ppk, derivation_path_index, amounts) +SELECT id, unit, active, valid_from, valid_to, derivation_path, input_fee_ppk, derivation_path_index, amounts +FROM keyset; + +-- Drop old table +DROP TABLE keyset; + +-- Rename new table to original name +ALTER TABLE keyset_new RENAME TO keyset; + +-- Recreate indexes +CREATE INDEX IF NOT EXISTS unit_index ON keyset(unit); +CREATE INDEX IF NOT EXISTS active_index ON keyset(active); diff --git a/crates/cdk-sql-common/src/mint/mod.rs b/crates/cdk-sql-common/src/mint/mod.rs index 6546ca39f..2fe165136 100644 --- a/crates/cdk-sql-common/src/mint/mod.rs +++ b/crates/cdk-sql-common/src/mint/mod.rs @@ -591,11 +591,11 @@ where INSERT INTO keyset ( id, unit, active, valid_from, valid_to, derivation_path, - max_order, amounts, input_fee_ppk, derivation_path_index + amounts, input_fee_ppk, derivation_path_index ) VALUES ( :id, :unit, :active, :valid_from, :valid_to, :derivation_path, - :max_order, :amounts, :input_fee_ppk, :derivation_path_index + :amounts, :input_fee_ppk, :derivation_path_index ) ON CONFLICT(id) DO UPDATE SET unit = excluded.unit, @@ -603,7 +603,6 @@ where valid_from = excluded.valid_from, valid_to = excluded.valid_to, derivation_path = excluded.derivation_path, - max_order = excluded.max_order, amounts = excluded.amounts, input_fee_ppk = excluded.input_fee_ppk, derivation_path_index = excluded.derivation_path_index @@ -615,7 +614,6 @@ where .bind("valid_from", keyset.valid_from as i64) .bind("valid_to", keyset.final_expiry.map(|v| v as i64)) .bind("derivation_path", keyset.derivation_path.to_string()) - .bind("max_order", keyset.max_order) .bind("amounts", serde_json::to_string(&keyset.amounts).ok()) .bind("input_fee_ppk", keyset.input_fee_ppk as i64) .bind("derivation_path_index", keyset.derivation_path_index) @@ -707,7 +705,6 @@ where valid_to, derivation_path, derivation_path_index, - max_order, amounts, input_fee_ppk FROM @@ -732,7 +729,6 @@ where valid_to, derivation_path, derivation_path_index, - max_order, amounts, input_fee_ppk FROM @@ -2316,16 +2312,14 @@ fn sql_row_to_keyset_info(row: Vec) -> Result { valid_to, derivation_path, derivation_path_index, - max_order, amounts, row_keyset_ppk ) = row ); - let max_order: u8 = column_as_number!(max_order); let amounts = column_as_nullable_string!(amounts) .and_then(|str| serde_json::from_str(&str).ok()) - .unwrap_or_else(|| (0..max_order).map(|m| 2u64.pow(m.into())).collect()); + .ok_or_else(|| Error::Database("amounts field is required".to_string().into()))?; Ok(MintKeySetInfo { id: column_as_string!(id, Id::from_str, Id::from_bytes), @@ -2334,7 +2328,6 @@ fn sql_row_to_keyset_info(row: Vec) -> Result { valid_from: column_as_number!(valid_from), derivation_path: column_as_string!(derivation_path, DerivationPath::from_str), derivation_path_index: column_as_nullable_number!(derivation_path_index), - max_order, amounts, input_fee_ppk: column_as_number!(row_keyset_ppk), final_expiry: column_as_nullable_number!(valid_to), @@ -2629,77 +2622,13 @@ fn sql_row_to_saga(row: Vec) -> Result { mod test { use super::*; - mod max_order_to_amounts_migrations { + mod keyset_amounts_tests { use super::*; #[test] - fn legacy_payload() { - let result = sql_row_to_keyset_info(vec![ - Column::Text("0083a60439303340".to_owned()), - Column::Text("sat".to_owned()), - Column::Integer(1), - Column::Integer(1749844864), - Column::Null, - Column::Text("0'/0'/0'".to_owned()), - Column::Integer(0), - Column::Integer(32), - Column::Null, - Column::Integer(0), - ]); - assert!(result.is_ok()); - } - - #[test] - fn migrated_payload() { - let legacy = sql_row_to_keyset_info(vec![ - Column::Text("0083a60439303340".to_owned()), - Column::Text("sat".to_owned()), - Column::Integer(1), - Column::Integer(1749844864), - Column::Null, - Column::Text("0'/0'/0'".to_owned()), - Column::Integer(0), - Column::Integer(32), - Column::Null, - Column::Integer(0), - ]); - assert!(legacy.is_ok()); - + fn keyset_with_amounts() { let amounts = (0..32).map(|x| 2u64.pow(x)).collect::>(); - let migrated = sql_row_to_keyset_info(vec![ - Column::Text("0083a60439303340".to_owned()), - Column::Text("sat".to_owned()), - Column::Integer(1), - Column::Integer(1749844864), - Column::Null, - Column::Text("0'/0'/0'".to_owned()), - Column::Integer(0), - Column::Integer(32), - Column::Text(serde_json::to_string(&amounts).expect("valid json")), - Column::Integer(0), - ]); - assert!(migrated.is_ok()); - assert_eq!(legacy.unwrap(), migrated.unwrap()); - } - - #[test] - fn amounts_over_max_order() { - let legacy = sql_row_to_keyset_info(vec![ - Column::Text("0083a60439303340".to_owned()), - Column::Text("sat".to_owned()), - Column::Integer(1), - Column::Integer(1749844864), - Column::Null, - Column::Text("0'/0'/0'".to_owned()), - Column::Integer(0), - Column::Integer(32), - Column::Null, - Column::Integer(0), - ]); - assert!(legacy.is_ok()); - - let amounts = (0..16).map(|x| 2u64.pow(x)).collect::>(); - let migrated = sql_row_to_keyset_info(vec![ + let result = sql_row_to_keyset_info(vec![ Column::Text("0083a60439303340".to_owned()), Column::Text("sat".to_owned()), Column::Integer(1), @@ -2707,14 +2636,12 @@ mod test { Column::Null, Column::Text("0'/0'/0'".to_owned()), Column::Integer(0), - Column::Integer(32), Column::Text(serde_json::to_string(&amounts).expect("valid json")), Column::Integer(0), ]); - assert!(migrated.is_ok()); - let migrated = migrated.unwrap(); - assert_ne!(legacy.unwrap(), migrated); - assert_eq!(migrated.amounts.len(), 16); + assert!(result.is_ok()); + let keyset = result.unwrap(); + assert_eq!(keyset.amounts.len(), 32); } } } diff --git a/crates/cdk/src/mint/builder.rs b/crates/cdk/src/mint/builder.rs index 4d582c391..a848c80a5 100644 --- a/crates/cdk/src/mint/builder.rs +++ b/crates/cdk/src/mint/builder.rs @@ -302,7 +302,7 @@ impl MintBuilder { /// /// The unit **MUST** already have been added with a ln backend pub fn set_unit_fee(&mut self, unit: &CurrencyUnit, input_fee_ppk: u64) -> Result<(), Error> { - let (input_fee, _max_order) = self + let (input_fee, _) = self .supported_units .get_mut(unit) .ok_or(Error::UnsupportedUnit)?; diff --git a/crates/cdk/src/mint/keysets/mod.rs b/crates/cdk/src/mint/keysets/mod.rs index bfe8c853b..1a61f42bc 100644 --- a/crates/cdk/src/mint/keysets/mod.rs +++ b/crates/cdk/src/mint/keysets/mod.rs @@ -75,14 +75,14 @@ impl Mint { pub async fn rotate_keyset( &self, unit: CurrencyUnit, - max_order: u8, + amounts: Vec, input_fee_ppk: u64, ) -> Result { let result = self .signatory .rotate_keyset(RotateKeyArguments { unit, - amounts: (0..max_order).map(|n| 2u64.pow(n.into())).collect(), + amounts, input_fee_ppk, }) .await?; diff --git a/crates/cdk/src/mint/mod.rs b/crates/cdk/src/mint/mod.rs index 7368e978c..63671960e 100644 --- a/crates/cdk/src/mint/mod.rs +++ b/crates/cdk/src/mint/mod.rs @@ -1071,7 +1071,7 @@ mod tests { let first_keyset_id = keysets.keysets[0].id; // set the first keyset to inactive and generate a new keyset - mint.rotate_keyset(CurrencyUnit::default(), 1, 1) + mint.rotate_keyset(CurrencyUnit::default(), vec![1], 1) .await .expect("test"); From 96e2282bce6ffeb20096caa9ef1d21dfc72efa2b Mon Sep 17 00:00:00 2001 From: tsk Date: Tue, 25 Nov 2025 16:53:52 +0000 Subject: [PATCH 302/321] feat: cdk-ffi get wallets (#1333) --- crates/cdk-ffi/src/multi_mint_wallet.rs | 18 ++++++++++++++++++ crates/cdk-ffi/src/wallet.rs | 7 +++++++ 2 files changed, 25 insertions(+) diff --git a/crates/cdk-ffi/src/multi_mint_wallet.rs b/crates/cdk-ffi/src/multi_mint_wallet.rs index 79ad82ca8..c70e1402d 100644 --- a/crates/cdk-ffi/src/multi_mint_wallet.rs +++ b/crates/cdk-ffi/src/multi_mint_wallet.rs @@ -516,6 +516,24 @@ impl MultiMintWallet { wallets.iter().map(|w| w.mint_url.to_string()).collect() } + /// Get all wallets from MultiMintWallet + pub async fn get_wallets(&self) -> Vec> { + let wallets = self.inner.get_wallets().await; + wallets + .into_iter() + .map(|w| Arc::new(crate::wallet::Wallet::from_inner(Arc::new(w)))) + .collect() + } + + /// Get a specific wallet from MultiMintWallet by mint URL + pub async fn get_wallet(&self, mint_url: MintUrl) -> Option> { + let cdk_mint_url: cdk::mint_url::MintUrl = mint_url.try_into().ok()?; + let wallet = self.inner.get_wallet(&cdk_mint_url).await?; + Some(Arc::new(crate::wallet::Wallet::from_inner(Arc::new( + wallet, + )))) + } + /// Verify token DLEQ proofs pub async fn verify_token_dleq(&self, token: Arc) -> Result<(), FfiError> { let cdk_token = token.inner.clone(); diff --git a/crates/cdk-ffi/src/wallet.rs b/crates/cdk-ffi/src/wallet.rs index 78f646060..f9fecadc5 100644 --- a/crates/cdk-ffi/src/wallet.rs +++ b/crates/cdk-ffi/src/wallet.rs @@ -16,6 +16,13 @@ pub struct Wallet { inner: Arc, } +impl Wallet { + /// Create a Wallet from an existing CDK wallet (internal use only) + pub(crate) fn from_inner(inner: Arc) -> Self { + Self { inner } + } +} + #[uniffi::export(async_runtime = "tokio")] impl Wallet { /// Create a new Wallet from mnemonic using WalletDatabase trait From 681f7082c3c248442420efffef0b724b1dff4cf1 Mon Sep 17 00:00:00 2001 From: tsk Date: Tue, 25 Nov 2025 17:08:42 +0000 Subject: [PATCH 303/321] fix: check melt quote in ffi (#1340) --- crates/cdk-ffi/src/multi_mint_wallet.rs | 14 +++++++++++ crates/cdk/src/wallet/multi_mint_wallet.rs | 28 +++++++++++++++++++++- 2 files changed, 41 insertions(+), 1 deletion(-) diff --git a/crates/cdk-ffi/src/multi_mint_wallet.rs b/crates/cdk-ffi/src/multi_mint_wallet.rs index c70e1402d..3ed6186ab 100644 --- a/crates/cdk-ffi/src/multi_mint_wallet.rs +++ b/crates/cdk-ffi/src/multi_mint_wallet.rs @@ -442,6 +442,20 @@ impl MultiMintWallet { Ok(melted.into()) } + /// Check melt quote status + pub async fn check_melt_quote( + &self, + mint_url: MintUrl, + quote_id: String, + ) -> Result { + let cdk_mint_url: cdk::mint_url::MintUrl = mint_url.try_into()?; + let melted = self + .inner + .check_melt_quote(&cdk_mint_url, "e_id) + .await?; + Ok(melted.into()) + } + /// Melt tokens (pay a bolt11 invoice) pub async fn melt( &self, diff --git a/crates/cdk/src/wallet/multi_mint_wallet.rs b/crates/cdk/src/wallet/multi_mint_wallet.rs index a6e89d498..6e3f6eedc 100644 --- a/crates/cdk/src/wallet/multi_mint_wallet.rs +++ b/crates/cdk/src/wallet/multi_mint_wallet.rs @@ -12,7 +12,7 @@ use anyhow::Result; use cdk_common::database; use cdk_common::database::WalletDatabase; use cdk_common::task::spawn; -use cdk_common::wallet::{Transaction, TransactionDirection}; +use cdk_common::wallet::{MeltQuote, Transaction, TransactionDirection}; use tokio::sync::RwLock; use tracing::instrument; use zeroize::Zeroize; @@ -1299,6 +1299,32 @@ impl MultiMintWallet { wallet.melt(quote_id).await } + /// Check a specific melt quote status + #[instrument(skip(self))] + pub async fn check_melt_quote( + &self, + mint_url: &MintUrl, + quote_id: &str, + ) -> Result { + let wallets = self.wallets.read().await; + let wallet = wallets.get(mint_url).ok_or(Error::UnknownMint { + mint_url: mint_url.to_string(), + })?; + + // Check the quote state from the mint + wallet.melt_quote_status(quote_id).await?; + + // Get the updated quote from local storage + let quote = wallet + .localstore + .get_melt_quote(quote_id) + .await + .map_err(Error::Database)? + .ok_or(Error::UnknownQuote)?; + + Ok(quote) + } + /// Create MPP (Multi-Path Payment) melt quotes from multiple mints /// /// This function allows manual specification of which mints and amounts to use for MPP. From 28890842548591efe81af56ed98f53ebdb1109a7 Mon Sep 17 00:00:00 2001 From: Leonardo Escuer <47948594+lescuer97@users.noreply.github.com> Date: Wed, 26 Nov 2025 10:30:54 +0100 Subject: [PATCH 304/321] fix: use the client id from mint configuration (#1343) * fix: use the client id from mint configuration --- .../src/sub_commands/cat_device_login.rs | 23 +++++++++++-------- crates/cdk-cli/src/sub_commands/cat_login.rs | 22 ++++++++---------- crates/cdk/examples/auth_wallet.rs | 7 +++++- 3 files changed, 30 insertions(+), 22 deletions(-) diff --git a/crates/cdk-cli/src/sub_commands/cat_device_login.rs b/crates/cdk-cli/src/sub_commands/cat_device_login.rs index dacccc17c..8f54b9fa7 100644 --- a/crates/cdk-cli/src/sub_commands/cat_device_login.rs +++ b/crates/cdk-cli/src/sub_commands/cat_device_login.rs @@ -16,10 +16,6 @@ use crate::token_storage; pub struct CatDeviceLoginSubCommand { /// Mint url mint_url: MintUrl, - /// Client ID for OIDC authentication - #[arg(default_value = "cashu-client")] - #[arg(long)] - client_id: String, } pub async fn cat_device_login( @@ -39,8 +35,7 @@ pub async fn cat_device_login( .await? .ok_or(anyhow!("Mint info not found"))?; - let (access_token, refresh_token) = - get_device_code_token(&mint_info, &sub_command_args.client_id).await; + let (access_token, refresh_token) = get_device_code_token(&mint_info).await; // Save tokens to file in work directory if let Err(e) = @@ -60,7 +55,7 @@ pub async fn cat_device_login( Ok(()) } -async fn get_device_code_token(mint_info: &MintInfo, client_id: &str) -> (String, String) { +async fn get_device_code_token(mint_info: &MintInfo) -> (String, String) { let openid_discovery = mint_info .nuts .nut21 @@ -68,6 +63,13 @@ async fn get_device_code_token(mint_info: &MintInfo, client_id: &str) -> (String .expect("Nut21 defined") .openid_discovery; + let client_id = mint_info + .nuts + .nut21 + .clone() + .expect("Nut21 defined") + .client_id; + let oidc_client = OidcClient::new(openid_discovery, None); // Get the OIDC configuration @@ -83,7 +85,10 @@ async fn get_device_code_token(mint_info: &MintInfo, client_id: &str) -> (String let client = reqwest::Client::new(); let device_code_response = client .post(device_auth_url) - .form(&[("client_id", client_id)]) + .form(&[ + ("client_id", client_id.clone().as_str()), + ("scope", "openid offline_access"), + ]) .send() .await .expect("Failed to send device code request"); @@ -129,7 +134,7 @@ async fn get_device_code_token(mint_info: &MintInfo, client_id: &str) -> (String .form(&[ ("grant_type", "urn:ietf:params:oauth:grant-type:device_code"), ("device_code", device_code), - ("client_id", client_id), + ("client_id", client_id.clone().as_str()), ]) .send() .await diff --git a/crates/cdk-cli/src/sub_commands/cat_login.rs b/crates/cdk-cli/src/sub_commands/cat_login.rs index adeab5cc5..7d6be5449 100644 --- a/crates/cdk-cli/src/sub_commands/cat_login.rs +++ b/crates/cdk-cli/src/sub_commands/cat_login.rs @@ -18,10 +18,6 @@ pub struct CatLoginSubCommand { username: String, /// Password password: String, - /// Client ID for OIDC authentication - #[arg(default_value = "cashu-client")] - #[arg(long)] - client_id: String, } pub async fn cat_login( @@ -43,7 +39,6 @@ pub async fn cat_login( let (access_token, refresh_token) = get_access_token( &mint_info, - &sub_command_args.client_id, &sub_command_args.username, &sub_command_args.password, ) @@ -66,12 +61,7 @@ pub async fn cat_login( Ok(()) } -async fn get_access_token( - mint_info: &MintInfo, - client_id: &str, - user: &str, - password: &str, -) -> (String, String) { +async fn get_access_token(mint_info: &MintInfo, user: &str, password: &str) -> (String, String) { let openid_discovery = mint_info .nuts .nut21 @@ -79,6 +69,13 @@ async fn get_access_token( .expect("Nut21 defined") .openid_discovery; + let client_id = mint_info + .nuts + .nut21 + .clone() + .expect("Nut21 defined") + .client_id; + let oidc_client = OidcClient::new(openid_discovery, None); // Get the token endpoint from the OIDC configuration @@ -91,7 +88,8 @@ async fn get_access_token( // Create the request parameters let params = [ ("grant_type", "password"), - ("client_id", client_id), + ("client_id", &client_id), + ("scope", "openid offline_access"), ("username", user), ("password", password), ]; diff --git a/crates/cdk/examples/auth_wallet.rs b/crates/cdk/examples/auth_wallet.rs index d6efe6bbb..203c92a03 100644 --- a/crates/cdk/examples/auth_wallet.rs +++ b/crates/cdk/examples/auth_wallet.rs @@ -105,11 +105,16 @@ async fn get_access_token(mint_info: &MintInfo) -> String { .await .expect("Failed to get OIDC config") .token_endpoint; + let client_id = oidc_client + .get_oidc_config() + .await + .expect("Failed to get OIDC config") + .token_endpoint; // Create the request parameters let params = [ ("grant_type", "password"), - ("client_id", "cashu-client"), + ("client_id", &client_id), ("username", TEST_USERNAME), ("password", TEST_PASSWORD), ]; From bcc68a790d4d7939c66722d1971a67ae283c7856 Mon Sep 17 00:00:00 2001 From: tsk Date: Wed, 26 Nov 2025 17:49:20 +0000 Subject: [PATCH 305/321] fix: proof selection with fees (#1345) When selecting proofs with fee inclusion, adding extra proofs to cover the fee shortfall also adds new fees. The previous single-pass approach could leave the net amount below the requested amount. This changes to an iterative loop that continues selecting additional proofs until the net amount (total - fees) meets or exceeds the target. refactor: remove swap before melt --- .../tests/fake_wallet.rs | 34 +- .../cdk-integration-tests/tests/test_fees.rs | 8 + crates/cdk/examples/p2pk.rs | 15 +- crates/cdk/src/fees.rs | 132 ++ crates/cdk/src/mint/melt/melt_saga/mod.rs | 6 +- crates/cdk/src/wallet/issue/issue_bolt11.rs | 15 +- crates/cdk/src/wallet/issue/issue_bolt12.rs | 15 +- crates/cdk/src/wallet/melt/melt_bolt11.rs | 22 +- crates/cdk/src/wallet/proofs.rs | 1539 ++++++++++++++++- crates/cdk/src/wallet/send.rs | 1292 +++++++++++++- crates/cdk/src/wallet/swap.rs | 10 - 11 files changed, 2940 insertions(+), 148 deletions(-) diff --git a/crates/cdk-integration-tests/tests/fake_wallet.rs b/crates/cdk-integration-tests/tests/fake_wallet.rs index 31ad50270..1b768ff69 100644 --- a/crates/cdk-integration-tests/tests/fake_wallet.rs +++ b/crates/cdk-integration-tests/tests/fake_wallet.rs @@ -15,6 +15,7 @@ //! - Duplicate proof detection use std::sync::Arc; +use std::time::Duration; use bip39::Mnemonic; use cashu::Amount; @@ -882,7 +883,7 @@ async fn test_fake_mint_multiple_unit_melt() { let mut proof_streams = wallet.proof_stream(mint_quote.clone(), SplitTarget::default(), None); - let proofs = proof_streams + let mut proofs = proof_streams .next() .await .expect("payment") @@ -905,12 +906,15 @@ async fn test_fake_mint_multiple_unit_melt() { let mut proof_streams = wallet_usd.proof_stream(mint_quote.clone(), SplitTarget::default(), None); - let usd_proofs = proof_streams + let mut usd_proofs = proof_streams .next() .await .expect("payment") .expect("no error"); + usd_proofs.reverse(); + proofs.reverse(); + { let inputs: Proofs = vec![ proofs.first().expect("There is a proof").clone(), @@ -1411,14 +1415,14 @@ async fn test_wallet_proof_recovery_after_failed_melt() { // Mint 100 sats let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); - let mut proof_streams = wallet.proof_stream(mint_quote.clone(), SplitTarget::default(), None); - let initial_proofs = proof_streams - .next() - .await - .expect("payment") - .expect("no error"); - - let initial_ys: Vec<_> = initial_proofs.iter().map(|p| p.y().unwrap()).collect(); + let _roof_streams = wallet + .wait_and_mint_quote( + mint_quote.clone(), + SplitTarget::default(), + None, + Duration::from_secs(1000), + ) + .await; assert_eq!(wallet.total_balance().await.unwrap(), Amount::from(100)); @@ -1444,16 +1448,6 @@ async fn test_wallet_proof_recovery_after_failed_melt() { "Balance should be recovered" ); - // Verify the proofs were swapped (different Ys) - let recovered_proofs = wallet.get_unspent_proofs().await.unwrap(); - let recovered_ys: Vec<_> = recovered_proofs.iter().map(|p| p.y().unwrap()).collect(); - - // The Ys should be different (swapped to new proofs) - assert!( - initial_ys.iter().any(|y| !recovered_ys.contains(y)), - "Proofs should have been swapped to new ones" - ); - // Verify we can still spend the recovered proofs let valid_invoice = create_fake_invoice(7000, "".to_string()); let valid_melt_quote = wallet diff --git a/crates/cdk-integration-tests/tests/test_fees.rs b/crates/cdk-integration-tests/tests/test_fees.rs index f63dbe063..1da698853 100644 --- a/crates/cdk-integration-tests/tests/test_fees.rs +++ b/crates/cdk-integration-tests/tests/test_fees.rs @@ -9,9 +9,15 @@ use cdk::wallet::{ReceiveOptions, SendKind, SendOptions, Wallet}; use cdk_integration_tests::init_regtest::get_temp_dir; use cdk_integration_tests::{create_invoice_for_env, get_mint_url_from_env, pay_if_regtest}; use cdk_sqlite::wallet::memory; +use tracing_subscriber::EnvFilter; #[tokio::test(flavor = "multi_thread", worker_threads = 1)] async fn test_swap() { + // Set up logging + let default_filter = "debug"; + let sqlx_filter = "sqlx=warn,hyper_util=warn,reqwest=warn,rustls=warn"; + let env_filter = EnvFilter::new(format!("{},{}", default_filter, sqlx_filter)); + tracing_subscriber::fmt().with_env_filter(env_filter).init(); let seed = Mnemonic::generate(12).unwrap().to_seed_normalized(""); let wallet = Wallet::new( &get_mint_url_from_env(), @@ -39,6 +45,8 @@ async fn test_swap() { println!("{:?}", proofs); + println!("{:?}", wallet.get_mint_keysets().await.unwrap()); + let send = wallet .prepare_send( 4.into(), diff --git a/crates/cdk/examples/p2pk.rs b/crates/cdk/examples/p2pk.rs index 9bf8ef53d..8e5a1985e 100644 --- a/crates/cdk/examples/p2pk.rs +++ b/crates/cdk/examples/p2pk.rs @@ -27,7 +27,8 @@ async fn main() -> Result<(), Error> { let seed = random::<[u8; 64]>(); // Define the mint URL and currency unit - let mint_url = "https://fake.thesimplekid.dev"; + // let mint_url = "https://fake.thesimplekid.dev"; + let mint_url = "https://testnut.cashu.space"; let unit = CurrencyUnit::Sat; let amount = Amount::from(100); @@ -60,10 +61,12 @@ async fn main() -> Result<(), Error> { let bal = wallet.total_balance().await?; println!("Total balance: {}", bal); + let token_amount_to_send = Amount::from(10); + // Send a token with the specified amount and spending conditions let prepared_send = wallet .prepare_send( - 10.into(), + token_amount_to_send, SendOptions { conditions: Some(spending_conditions), include_fee: true, @@ -71,7 +74,11 @@ async fn main() -> Result<(), Error> { }, ) .await?; - println!("Fee: {}", prepared_send.fee()); + + let swap_fee = prepared_send.swap_fee(); + + println!("Fee: {}", swap_fee); + let token = prepared_send.confirm(None).await?; println!("Created token locked to pubkey: {}", secret.public_key()); @@ -88,6 +95,8 @@ async fn main() -> Result<(), Error> { ) .await?; + assert!(amount == token_amount_to_send); + println!("Redeemed locked token worth: {}", u64::from(amount)); Ok(()) diff --git a/crates/cdk/src/fees.rs b/crates/cdk/src/fees.rs index 40d4a2395..5eadf57e6 100644 --- a/crates/cdk/src/fees.rs +++ b/crates/cdk/src/fees.rs @@ -82,4 +82,136 @@ mod tests { let sum_fee = calculate_fee(&proofs_count, &keyset_fees).unwrap(); assert_eq!(sum_fee, 8.into()); } + + #[test] + fn test_fee_calculation_with_ppk_200() { + let keyset_id = Id::from_str("001711afb1de20cb").unwrap(); + + let fee_ppk = 200; + + let mut keyset_fees = HashMap::new(); + keyset_fees.insert(keyset_id, fee_ppk); + + let mut proofs_count = HashMap::new(); + + proofs_count.insert(keyset_id, 1); + let sum_fee = calculate_fee(&proofs_count, &keyset_fees).unwrap(); + assert_eq!(sum_fee, 1.into(), "1 proof: ceil(200/1000) = 1 sat"); + + proofs_count.insert(keyset_id, 3); + let sum_fee = calculate_fee(&proofs_count, &keyset_fees).unwrap(); + assert_eq!(sum_fee, 1.into(), "3 proofs: ceil(600/1000) = 1 sat"); + + proofs_count.insert(keyset_id, 5); + let sum_fee = calculate_fee(&proofs_count, &keyset_fees).unwrap(); + assert_eq!(sum_fee, 1.into(), "5 proofs: ceil(1000/1000) = 1 sat"); + + proofs_count.insert(keyset_id, 6); + let sum_fee = calculate_fee(&proofs_count, &keyset_fees).unwrap(); + assert_eq!(sum_fee, 2.into(), "6 proofs: ceil(1200/1000) = 2 sats"); + } + + #[test] + fn test_fee_calculation_with_ppk_1000() { + let keyset_id = Id::from_str("001711afb1de20cb").unwrap(); + + let fee_ppk = 1000; + + let mut keyset_fees = HashMap::new(); + keyset_fees.insert(keyset_id, fee_ppk); + + let mut proofs_count = HashMap::new(); + + proofs_count.insert(keyset_id, 1); + let sum_fee = calculate_fee(&proofs_count, &keyset_fees).unwrap(); + assert_eq!(sum_fee, 1.into(), "1 proof at 1000 ppk = 1 sat"); + + proofs_count.insert(keyset_id, 2); + let sum_fee = calculate_fee(&proofs_count, &keyset_fees).unwrap(); + assert_eq!(sum_fee, 2.into(), "2 proofs at 1000 ppk = 2 sats"); + + proofs_count.insert(keyset_id, 10); + let sum_fee = calculate_fee(&proofs_count, &keyset_fees).unwrap(); + assert_eq!(sum_fee, 10.into(), "10 proofs at 1000 ppk = 10 sats"); + } + + #[test] + fn test_fee_calculation_zero_fee() { + let keyset_id = Id::from_str("001711afb1de20cb").unwrap(); + + let fee_ppk = 0; + + let mut keyset_fees = HashMap::new(); + keyset_fees.insert(keyset_id, fee_ppk); + + let mut proofs_count = HashMap::new(); + + proofs_count.insert(keyset_id, 100); + let sum_fee = calculate_fee(&proofs_count, &keyset_fees).unwrap(); + assert_eq!(sum_fee, 0.into(), "0 ppk means no fee: ceil(0/1000) = 0"); + } + + #[test] + fn test_fee_calculation_with_ppk_100() { + let keyset_id = Id::from_str("001711afb1de20cb").unwrap(); + + let fee_ppk = 100; + + let mut keyset_fees = HashMap::new(); + keyset_fees.insert(keyset_id, fee_ppk); + + let mut proofs_count = HashMap::new(); + + proofs_count.insert(keyset_id, 1); + let sum_fee = calculate_fee(&proofs_count, &keyset_fees).unwrap(); + assert_eq!(sum_fee, 1.into(), "1 proof: ceil(100/1000) = 1 sat"); + + proofs_count.insert(keyset_id, 10); + let sum_fee = calculate_fee(&proofs_count, &keyset_fees).unwrap(); + assert_eq!(sum_fee, 1.into(), "10 proofs: ceil(1000/1000) = 1 sat"); + + proofs_count.insert(keyset_id, 11); + let sum_fee = calculate_fee(&proofs_count, &keyset_fees).unwrap(); + assert_eq!(sum_fee, 2.into(), "11 proofs: ceil(1100/1000) = 2 sats"); + + proofs_count.insert(keyset_id, 91); + let sum_fee = calculate_fee(&proofs_count, &keyset_fees).unwrap(); + assert_eq!(sum_fee, 10.into(), "91 proofs: ceil(9100/1000) = 10 sats"); + } + + #[test] + fn test_fee_calculation_unknown_keyset() { + let keyset_id = Id::from_str("001711afb1de20cb").unwrap(); + let unknown_keyset_id = Id::from_str("001711afb1de20cc").unwrap(); + + let mut keyset_fees = HashMap::new(); + keyset_fees.insert(keyset_id, 100); + + let mut proofs_count = HashMap::new(); + proofs_count.insert(unknown_keyset_id, 1); + + let result = calculate_fee(&proofs_count, &keyset_fees); + assert!(result.is_err(), "Unknown keyset should return error"); + } + + #[test] + fn test_fee_calculation_multiple_keysets() { + let keyset_id_1 = Id::from_str("001711afb1de20cb").unwrap(); + let keyset_id_2 = Id::from_str("001711afb1de20cc").unwrap(); + + let mut keyset_fees = HashMap::new(); + keyset_fees.insert(keyset_id_1, 200); + keyset_fees.insert(keyset_id_2, 500); + + let mut proofs_count = HashMap::new(); + proofs_count.insert(keyset_id_1, 3); + proofs_count.insert(keyset_id_2, 2); + + let sum_fee = calculate_fee(&proofs_count, &keyset_fees).unwrap(); + assert_eq!( + sum_fee, + 2.into(), + "3*200 + 2*500 = 1600, ceil(1600/1000) = 2" + ); + } } diff --git a/crates/cdk/src/mint/melt/melt_saga/mod.rs b/crates/cdk/src/mint/melt/melt_saga/mod.rs index 8d85f5e4b..a98284e0e 100644 --- a/crates/cdk/src/mint/melt/melt_saga/mod.rs +++ b/crates/cdk/src/mint/melt/melt_saga/mod.rs @@ -290,10 +290,12 @@ impl MeltSaga { if input_amount < required_total { tracing::info!( - "Melt request unbalanced: inputs {}, amount {}, fee {}", + "Melt request unbalanced: inputs {}, amount {}, fee_reserve {}, input_fee {}, required {}", input_amount, quote.amount, - fee + quote.fee_reserve, + fee, + required_total ); tx.rollback().await?; return Err(Error::TransactionUnbalanced( diff --git a/crates/cdk/src/wallet/issue/issue_bolt11.rs b/crates/cdk/src/wallet/issue/issue_bolt11.rs index bec70a623..23361200e 100644 --- a/crates/cdk/src/wallet/issue/issue_bolt11.rs +++ b/crates/cdk/src/wallet/issue/issue_bolt11.rs @@ -220,18 +220,25 @@ impl Wallet { .get_keyset_fees_and_amounts_by_id(active_keyset_id) .await?; + let split_target = match amount_split_target { + SplitTarget::None => { + self.determine_split_target_values(amount_mintable, &fee_and_amounts) + .await? + } + s => s, + }; + let premint_secrets = match &spending_conditions { Some(spending_conditions) => PreMintSecrets::with_conditions( active_keyset_id, amount_mintable, - &amount_split_target, + &split_target, spending_conditions, &fee_and_amounts, )?, None => { - // Calculate how many secrets we'll need let amount_split = - amount_mintable.split_targeted(&amount_split_target, &fee_and_amounts)?; + amount_mintable.split_targeted(&split_target, &fee_and_amounts)?; let num_secrets = amount_split.len() as u32; tracing::debug!( @@ -253,7 +260,7 @@ impl Wallet { count, &self.seed, amount_mintable, - &amount_split_target, + &split_target, &fee_and_amounts, )? } diff --git a/crates/cdk/src/wallet/issue/issue_bolt12.rs b/crates/cdk/src/wallet/issue/issue_bolt12.rs index 6ecd657cb..7637f4420 100644 --- a/crates/cdk/src/wallet/issue/issue_bolt12.rs +++ b/crates/cdk/src/wallet/issue/issue_bolt12.rs @@ -114,17 +114,24 @@ impl Wallet { return Err(Error::UnpaidQuote); } + let split_target = match amount_split_target { + SplitTarget::None => { + self.determine_split_target_values(amount, &fee_and_amounts) + .await? + } + s => s, + }; + let premint_secrets = match &spending_conditions { Some(spending_conditions) => PreMintSecrets::with_conditions( active_keyset_id, amount, - &amount_split_target, + &split_target, spending_conditions, &fee_and_amounts, )?, None => { - // Calculate how many secrets we'll need without generating them - let amount_split = amount.split_targeted(&amount_split_target, &fee_and_amounts)?; + let amount_split = amount.split_targeted(&split_target, &fee_and_amounts)?; let num_secrets = amount_split.len() as u32; tracing::debug!( @@ -146,7 +153,7 @@ impl Wallet { count, &self.seed, amount, - &amount_split_target, + &split_target, &fee_and_amounts, )? } diff --git a/crates/cdk/src/wallet/melt/melt_bolt11.rs b/crates/cdk/src/wallet/melt/melt_bolt11.rs index f779ee1c4..202987263 100644 --- a/crates/cdk/src/wallet/melt/melt_bolt11.rs +++ b/crates/cdk/src/wallet/melt/melt_bolt11.rs @@ -1,7 +1,6 @@ use std::collections::HashMap; use std::str::FromStr; -use cdk_common::amount::SplitTarget; use cdk_common::wallet::{Transaction, TransactionDirection}; use cdk_common::PaymentMethod; use lightning_invoice::Bolt11Invoice; @@ -390,7 +389,8 @@ impl Wallet { .map(|k| k.id) .collect(); let keyset_fees = self.get_keyset_fees_and_amounts().await?; - let (mut input_proofs, mut exchange) = Wallet::select_exact_proofs( + + let input_proofs = Wallet::select_proofs( inputs_needed_amount, available_proofs, &active_keyset_ids, @@ -398,24 +398,6 @@ impl Wallet { true, )?; - if let Some((proof, exact_amount)) = exchange.take() { - let new_proofs = self - .swap( - Some(exact_amount), - SplitTarget::None, - vec![proof], - None, - false, - ) - .await? - .ok_or_else(|| { - tracing::error!("Received empty proofs"); - Error::Internal - })?; - - input_proofs.extend_from_slice(&new_proofs); - } - self.melt_proofs_with_metadata(quote_id, input_proofs, metadata) .await } diff --git a/crates/cdk/src/wallet/proofs.rs b/crates/cdk/src/wallet/proofs.rs index c90488e60..3026a5960 100644 --- a/crates/cdk/src/wallet/proofs.rs +++ b/crates/cdk/src/wallet/proofs.rs @@ -248,11 +248,6 @@ impl Wallet { fees_and_keyset_amounts: &KeysetFeeAndAmounts, include_fees: bool, ) -> Result { - tracing::debug!( - "amount={}, proofs={:?}", - amount, - proofs.iter().map(|p| p.amount.into()).collect::>() - ); if amount == Amount::ZERO { return Ok(vec![]); } @@ -263,14 +258,18 @@ impl Wallet { proofs.sort_by(|a, b| a.cmp(b).reverse()); // Track selected proofs and remaining amounts (include all inactive proofs first) - let mut selected_proofs: HashSet = proofs + let inactive_proofs: Proofs = proofs .iter() .filter(|p| !p.is_active(active_keyset_ids)) .cloned() .collect(); + let mut selected_proofs: HashSet = inactive_proofs.iter().cloned().collect(); if selected_proofs.total_amount()? >= amount { tracing::debug!("All inactive proofs are sufficient"); - return Ok(selected_proofs.into_iter().collect()); + // Still need to filter to minimum set, not return all of them + let mut inactive_selected = selected_proofs.into_iter().collect::>(); + inactive_selected.sort_by(|a, b| a.cmp(b).reverse()); + return Self::select_least_amount_over(inactive_selected, amount); } let mut remaining_amounts: Vec = Vec::new(); @@ -297,9 +296,15 @@ impl Wallet { } }; - // Select proofs with the optimal amounts - for (_, fee_and_amounts) in fees_and_keyset_amounts.iter() { - // Split the amount into optimal amounts + // Get fee_and_amounts for the first active keyset (use for optimal amount splitting) + // We only need to split once - iterating over all keysets would cause duplicate selections + let fee_and_amounts = active_keyset_ids + .iter() + .find_map(|id| fees_and_keyset_amounts.get(id)) + .or_else(|| fees_and_keyset_amounts.values().next()); + + // Select proofs with the optimal amounts (only split once, not per keyset) + if let Some(fee_and_amounts) = fee_and_amounts { for optimal_amount in amount.split(fee_and_amounts) { if !select_proof(&proofs, optimal_amount, true) { // Add the remaining amount to the remaining amounts because proof with the optimal amount was not found @@ -310,17 +315,22 @@ impl Wallet { // If all the optimal amounts are selected, return the selected proofs if remaining_amounts.is_empty() { - tracing::debug!("All optimal amounts are selected"); + let result: Proofs = selected_proofs.into_iter().collect(); + tracing::debug!( + "All optimal amounts are selected, returning {} proofs with total {}", + result.len(), + result.total_amount().unwrap_or_default() + ); if include_fees { return Self::include_fees( amount, proofs, - selected_proofs.into_iter().collect(), + result, active_keyset_ids, fees_and_keyset_amounts, ); } else { - return Ok(selected_proofs.into_iter().collect()); + return Ok(result); } } @@ -438,53 +448,63 @@ impl Wallet { fees_and_keyset_amounts: &KeysetFeeAndAmounts, ) -> Result { tracing::debug!("Including fees"); - let fee = calculate_fee( - &selected_proofs.count_by_keyset(), - &fees_and_keyset_amounts - .iter() - .map(|(key, values)| (*key, values.fee())) - .collect(), - ) - .unwrap_or_default(); - let net_amount = selected_proofs.total_amount()? - fee; - tracing::debug!( - "Net amount={}, fee={}, total amount={}", - net_amount, - fee, - selected_proofs.total_amount()? - ); - if net_amount >= amount { - tracing::debug!( - "Selected proofs: {:?}", - selected_proofs - .iter() - .map(|p| p.amount.into()) - .collect::>(), - ); - return Ok(selected_proofs); - } - tracing::debug!("Net amount is less than the required amount"); - let remaining_amount = amount - net_amount; - let remaining_proofs = proofs + let keyset_fees: HashMap = fees_and_keyset_amounts + .iter() + .map(|(key, values)| (*key, values.fee())) + .collect(); + + let mut remaining_proofs: Proofs = proofs .into_iter() .filter(|p| !selected_proofs.contains(p)) - .collect::(); - selected_proofs.extend(Wallet::select_proofs( - remaining_amount, - remaining_proofs, - active_keyset_ids, - &HashMap::new(), // Fees are already calculated - false, - )?); - tracing::debug!( - "Selected proofs: {:?}", - selected_proofs - .iter() - .map(|p| p.amount.into()) - .collect::>(), - ); - Ok(selected_proofs) + .collect(); + + loop { + let fee = + calculate_fee(&selected_proofs.count_by_keyset(), &keyset_fees).unwrap_or_default(); + let total = selected_proofs.total_amount()?; + let net_amount = total - fee; + + tracing::debug!( + "Net amount={}, fee={}, total amount={}", + net_amount, + fee, + total + ); + + if net_amount >= amount { + tracing::debug!( + "Selected proofs: {:?}", + selected_proofs + .iter() + .map(|p| p.amount.into()) + .collect::>(), + ); + return Ok(selected_proofs); + } + + if remaining_proofs.is_empty() { + return Err(Error::InsufficientFunds); + } + + let shortfall = amount - net_amount; + tracing::debug!("Net amount is less than required, shortfall={}", shortfall); + + let additional = Wallet::select_proofs( + shortfall, + remaining_proofs.clone(), + active_keyset_ids, + fees_and_keyset_amounts, + false, + )?; + + if additional.is_empty() { + return Err(Error::InsufficientFunds); + } + + remaining_proofs.retain(|p| !additional.contains(p)); + selected_proofs.extend(additional); + } } } @@ -723,4 +743,1409 @@ mod tests { assert_eq!(selected_proofs.len(), 1); assert_eq!(selected_proofs[0].amount, 32.into()); } + + #[test] + fn test_select_proofs_include_fees_accounts_for_additional_proof_fees() { + use cdk_common::nuts::nut00::ProofsMethods; + + use crate::fees::calculate_fee; + + let active_id = id(); + let mut keyset_fee_and_amounts = HashMap::new(); + keyset_fee_and_amounts.insert( + active_id, + (100, (0..32).map(|x| 2u64.pow(x)).collect()).into(), + ); + + let proofs = vec![ + proof(512), + proof(256), + proof(128), + proof(64), + proof(32), + proof(16), + proof(8), + proof(4), + proof(2), + proof(1), + ]; + + let amount: Amount = 1010.into(); + let selected_proofs = Wallet::select_proofs( + amount, + proofs, + &vec![active_id], + &keyset_fee_and_amounts, + true, + ) + .unwrap(); + + let total = selected_proofs.total_amount().unwrap(); + let fee = calculate_fee( + &selected_proofs.count_by_keyset(), + &keyset_fee_and_amounts + .iter() + .map(|(k, v)| (*k, v.fee())) + .collect(), + ) + .unwrap(); + let net = total - fee; + + assert!( + net >= amount, + "Net amount {} should be >= requested amount {} (total={}, fee={})", + net, + amount, + total, + fee + ); + } + + #[test] + fn test_select_proofs_include_fees_iterates_until_stable() { + use cdk_common::nuts::nut00::ProofsMethods; + + use crate::fees::calculate_fee; + + let active_id = id(); + let mut keyset_fee_and_amounts = HashMap::new(); + keyset_fee_and_amounts.insert( + active_id, + (100, (0..32).map(|x| 2u64.pow(x)).collect()).into(), + ); + + let mut proofs = Vec::new(); + for i in 0..10 { + proofs.push(proof(1 << i)); + } + proofs.push(proof(2)); + proofs.push(proof(4)); + + let amount: Amount = 1010.into(); + let selected_proofs = Wallet::select_proofs( + amount, + proofs, + &vec![active_id], + &keyset_fee_and_amounts, + true, + ) + .unwrap(); + + let total = selected_proofs.total_amount().unwrap(); + let fee = calculate_fee( + &selected_proofs.count_by_keyset(), + &keyset_fee_and_amounts + .iter() + .map(|(k, v)| (*k, v.fee())) + .collect(), + ) + .unwrap(); + let net = total - fee; + + assert!( + net >= amount, + "Net amount {} should be >= requested amount {} (total={}, fee={}, num_proofs={})", + net, + amount, + total, + fee, + selected_proofs.len() + ); + } + + // ======================================================================== + // Fee-Aware Proof Selection Tests (fee_ppk = 200) + // ======================================================================== + + fn keyset_fee_and_amounts_with_fee( + fee_ppk: u64, + ) -> HashMap { + let mut keyset_fee_and_amounts = HashMap::new(); + keyset_fee_and_amounts.insert( + id(), + (fee_ppk, (0..32).map(|x| 2u64.pow(x)).collect::>()).into(), + ); + keyset_fee_and_amounts + } + + fn standard_proofs() -> Vec { + vec![ + proof(1), + proof(2), + proof(4), + proof(8), + proof(16), + proof(32), + proof(64), + proof(128), + proof(256), + proof(512), + proof(1024), + proof(2048), + proof(4096), + ] + } + + fn fragmented_proofs() -> Vec { + let mut proofs = Vec::new(); + for _ in 0..10 { + proofs.push(proof(1)); + } + for _ in 0..8 { + proofs.push(proof(2)); + } + for _ in 0..6 { + proofs.push(proof(4)); + } + for _ in 0..5 { + proofs.push(proof(8)); + } + for _ in 0..4 { + proofs.push(proof(16)); + } + for _ in 0..3 { + proofs.push(proof(32)); + } + for _ in 0..2 { + proofs.push(proof(64)); + } + for _ in 0..2 { + proofs.push(proof(128)); + } + for _ in 0..2 { + proofs.push(proof(256)); + } + for _ in 0..2 { + proofs.push(proof(512)); + } + for _ in 0..2 { + proofs.push(proof(1024)); + } + for _ in 0..2 { + proofs.push(proof(2048)); + } + proofs + } + + fn large_proofs() -> Vec { + vec![ + proof(4096), + proof(2048), + proof(1024), + proof(512), + proof(256), + ] + } + + fn mixed_proofs() -> Vec { + vec![ + proof(4096), + proof(1024), + proof(256), + proof(256), + proof(128), + proof(64), + proof(32), + proof(16), + proof(8), + proof(4), + proof(2), + proof(1), + proof(1), + ] + } + + #[test] + fn test_select_proofs_with_fees_single_proof_exact() { + use cdk_common::nuts::nut00::ProofsMethods; + + use crate::fees::calculate_fee; + + let active_id = id(); + let keyset_fee_and_amounts = keyset_fee_and_amounts_with_fee(200); + + let proofs = vec![proof(4096)]; + let amount: Amount = 4095.into(); + + let selected_proofs = Wallet::select_proofs( + amount, + proofs, + &vec![active_id], + &keyset_fee_and_amounts, + true, + ) + .unwrap(); + + let total = selected_proofs.total_amount().unwrap(); + let fee = calculate_fee( + &selected_proofs.count_by_keyset(), + &keyset_fee_and_amounts + .iter() + .map(|(k, v)| (*k, v.fee())) + .collect(), + ) + .unwrap(); + let net = total - fee; + + assert_eq!(selected_proofs.len(), 1); + assert_eq!(selected_proofs[0].amount, 4096.into()); + assert!(net >= amount, "4096 - 1 (fee) = 4095 >= 4095"); + } + + #[test] + fn test_select_proofs_with_fees_single_proof_insufficient() { + let active_id = id(); + let keyset_fee_and_amounts = keyset_fee_and_amounts_with_fee(200); + + let proofs = vec![proof(4096)]; + let amount: Amount = 4096.into(); + + let result = Wallet::select_proofs( + amount, + proofs, + &vec![active_id], + &keyset_fee_and_amounts, + true, + ); + + assert!(result.is_err(), "4096 - 1 (fee) = 4095 < 4096, should fail"); + } + + #[test] + fn test_select_proofs_with_fees_two_proofs_fee_threshold() { + use cdk_common::nuts::nut00::ProofsMethods; + + use crate::fees::calculate_fee; + + let active_id = id(); + let keyset_fee_and_amounts = keyset_fee_and_amounts_with_fee(200); + + let proofs = vec![proof(4096), proof(1024)]; + let amount: Amount = 5000.into(); + + let selected_proofs = Wallet::select_proofs( + amount, + proofs, + &vec![active_id], + &keyset_fee_and_amounts, + true, + ) + .unwrap(); + + let total = selected_proofs.total_amount().unwrap(); + let fee = calculate_fee( + &selected_proofs.count_by_keyset(), + &keyset_fee_and_amounts + .iter() + .map(|(k, v)| (*k, v.fee())) + .collect(), + ) + .unwrap(); + let net = total - fee; + + assert!(net >= amount, "5120 - 1 = 5119 >= 5000"); + } + + #[test] + fn test_select_proofs_with_fees_iterative_fee_adjustment() { + use cdk_common::nuts::nut00::ProofsMethods; + + use crate::fees::calculate_fee; + + let active_id = id(); + let keyset_fee_and_amounts = keyset_fee_and_amounts_with_fee(200); + + let proofs = vec![ + proof(4096), + proof(1024), + proof(512), + proof(256), + proof(128), + proof(8), + ]; + let amount: Amount = 5000.into(); + + let selected_proofs = Wallet::select_proofs( + amount, + proofs, + &vec![active_id], + &keyset_fee_and_amounts, + true, + ) + .unwrap(); + + let total = selected_proofs.total_amount().unwrap(); + let fee = calculate_fee( + &selected_proofs.count_by_keyset(), + &keyset_fee_and_amounts + .iter() + .map(|(k, v)| (*k, v.fee())) + .collect(), + ) + .unwrap(); + let net = total - fee; + + assert!( + net >= amount, + "Net amount {} should be >= requested amount {} (total={}, fee={})", + net, + amount, + total, + fee + ); + } + + #[test] + fn test_select_proofs_with_fees_fee_increases_with_proofs() { + use cdk_common::nuts::nut00::ProofsMethods; + + use crate::fees::calculate_fee; + + let active_id = id(); + let keyset_fee_and_amounts = keyset_fee_and_amounts_with_fee(200); + + let proofs = vec![ + proof(1024), + proof(1024), + proof(1024), + proof(1024), + proof(1024), + ]; + let amount: Amount = 5000.into(); + + let selected_proofs = Wallet::select_proofs( + amount, + proofs, + &vec![active_id], + &keyset_fee_and_amounts, + true, + ) + .unwrap(); + + let total = selected_proofs.total_amount().unwrap(); + let fee = calculate_fee( + &selected_proofs.count_by_keyset(), + &keyset_fee_and_amounts + .iter() + .map(|(k, v)| (*k, v.fee())) + .collect(), + ) + .unwrap(); + let net = total - fee; + + assert!( + net >= amount, + "Net amount {} should be >= requested amount {}", + net, + amount + ); + } + + #[test] + fn test_select_proofs_with_fees_standard_proofs() { + use cdk_common::nuts::nut00::ProofsMethods; + + use crate::fees::calculate_fee; + + let active_id = id(); + let keyset_fee_and_amounts = keyset_fee_and_amounts_with_fee(200); + + let proofs = standard_proofs(); + let amount: Amount = 5000.into(); + + let selected_proofs = Wallet::select_proofs( + amount, + proofs, + &vec![active_id], + &keyset_fee_and_amounts, + true, + ) + .unwrap(); + + let total = selected_proofs.total_amount().unwrap(); + let fee = calculate_fee( + &selected_proofs.count_by_keyset(), + &keyset_fee_and_amounts + .iter() + .map(|(k, v)| (*k, v.fee())) + .collect(), + ) + .unwrap(); + let net = total - fee; + + assert!( + net >= amount, + "Standard proofs: net {} should be >= {} (total={}, fee={}, num_proofs={})", + net, + amount, + total, + fee, + selected_proofs.len() + ); + } + + #[test] + fn test_select_proofs_with_fees_mixed_proofs() { + use cdk_common::nuts::nut00::ProofsMethods; + + use crate::fees::calculate_fee; + + let active_id = id(); + let keyset_fee_and_amounts = keyset_fee_and_amounts_with_fee(200); + + let proofs = mixed_proofs(); + let amount: Amount = 5000.into(); + + let selected_proofs = Wallet::select_proofs( + amount, + proofs, + &vec![active_id], + &keyset_fee_and_amounts, + true, + ) + .unwrap(); + + let total = selected_proofs.total_amount().unwrap(); + let fee = calculate_fee( + &selected_proofs.count_by_keyset(), + &keyset_fee_and_amounts + .iter() + .map(|(k, v)| (*k, v.fee())) + .collect(), + ) + .unwrap(); + let net = total - fee; + + assert!( + net >= amount, + "Mixed proofs: net {} should be >= {} (total={}, fee={}, num_proofs={})", + net, + amount, + total, + fee, + selected_proofs.len() + ); + } + + // ======================================================================== + // High Fee Tests (fee_ppk = 1000, i.e., 1 sat per proof) + // ======================================================================== + + #[test] + fn test_select_proofs_high_fees_one_sat_per_proof() { + use cdk_common::nuts::nut00::ProofsMethods; + + use crate::fees::calculate_fee; + + let active_id = id(); + let keyset_fee_and_amounts = keyset_fee_and_amounts_with_fee(1000); + + let proofs = vec![ + proof(4096), + proof(4096), + proof(4096), + proof(4096), + proof(4096), + proof(4096), + proof(4096), + proof(4096), + proof(4096), + proof(4096), + proof(4096), + proof(512), + proof(1024), + proof(1024), + proof(1024), + proof(1024), + proof(1024), + proof(1024), + proof(1024), + proof(1024), + proof(512), + proof(512), + proof(512), + proof(512), + proof(512), + proof(512), + proof(256), + proof(256), + proof(256), + proof(256), + proof(256), + proof(256), + proof(128), + proof(128), + proof(128), + proof(128), + proof(128), + proof(128), + proof(128), + proof(8), + proof(8), + proof(8), + proof(8), + proof(8), + proof(8), + proof(8), + proof(4), + proof(4), + proof(4), + proof(4), + proof(4), + proof(4), + proof(4), + proof(2), + proof(2), + proof(2), + proof(2), + proof(2), + proof(2), + proof(1), + proof(1), + proof(1), + proof(1), + proof(1), + proof(4096), + ]; + let amount: Amount = 5000.into(); + + let selected_proofs = Wallet::select_proofs( + amount, + proofs, + &vec![active_id], + &keyset_fee_and_amounts, + true, + ) + .unwrap(); + + let total = selected_proofs.total_amount().unwrap(); + let fee = calculate_fee( + &selected_proofs.count_by_keyset(), + &keyset_fee_and_amounts + .iter() + .map(|(k, v)| (*k, v.fee())) + .collect(), + ) + .unwrap(); + + let net = total - fee; + + assert!( + net == amount, + "Selected proofs should cover amount after fees" + ); + assert!(fee == Amount::from(selected_proofs.len() as u64)); + assert!(fee > Amount::ZERO); + } + + #[test] + fn test_select_proofs_high_fees_prefers_larger_proofs() { + use cdk_common::nuts::nut00::ProofsMethods; + + use crate::fees::calculate_fee; + + let active_id = id(); + let keyset_fee_and_amounts = keyset_fee_and_amounts_with_fee(1000); + + let mut proofs = Vec::new(); + for _ in 0..100 { + proofs.push(proof(64)); + } + proofs.push(proof(4096)); + proofs.push(proof(1024)); + + let amount: Amount = 5000.into(); + + let selected_proofs = Wallet::select_proofs( + amount, + proofs, + &vec![active_id], + &keyset_fee_and_amounts, + true, + ) + .unwrap(); + + let total = selected_proofs.total_amount().unwrap(); + let fee = calculate_fee( + &selected_proofs.count_by_keyset(), + &keyset_fee_and_amounts + .iter() + .map(|(k, v)| (*k, v.fee())) + .collect(), + ) + .unwrap(); + let net = total - fee; + + assert!(net >= amount, "Net amount {} should be >= {}", net, amount); + } + + #[test] + fn test_select_proofs_high_fees_exact_with_fee() { + use cdk_common::nuts::nut00::ProofsMethods; + + use crate::fees::calculate_fee; + + let active_id = id(); + let keyset_fee_and_amounts = keyset_fee_and_amounts_with_fee(1000); + + let proofs = vec![proof(4096), proof(1024)]; + let amount: Amount = 5118.into(); + + let selected_proofs = Wallet::select_proofs( + amount, + proofs, + &vec![active_id], + &keyset_fee_and_amounts, + true, + ) + .unwrap(); + + let total = selected_proofs.total_amount().unwrap(); + let fee = calculate_fee( + &selected_proofs.count_by_keyset(), + &keyset_fee_and_amounts + .iter() + .map(|(k, v)| (*k, v.fee())) + .collect(), + ) + .unwrap(); + let net = total - fee; + + assert_eq!(selected_proofs.len(), 2); + assert_eq!(net, 5118.into(), "5120 - 2 = 5118"); + } + + #[test] + fn test_select_proofs_high_fees_large_proofs() { + use cdk_common::nuts::nut00::ProofsMethods; + + use crate::fees::calculate_fee; + + let active_id = id(); + let keyset_fee_and_amounts = keyset_fee_and_amounts_with_fee(1000); + + let proofs = large_proofs(); + let amount: Amount = 5000.into(); + + let selected_proofs = Wallet::select_proofs( + amount, + proofs, + &vec![active_id], + &keyset_fee_and_amounts, + true, + ) + .unwrap(); + + let total = selected_proofs.total_amount().unwrap(); + let fee = calculate_fee( + &selected_proofs.count_by_keyset(), + &keyset_fee_and_amounts + .iter() + .map(|(k, v)| (*k, v.fee())) + .collect(), + ) + .unwrap(); + let net = total - fee; + + assert!( + net >= amount, + "Large proofs: net {} should be >= {} (total={}, fee={}, num_proofs={})", + net, + amount, + total, + fee, + selected_proofs.len() + ); + } + + // ======================================================================== + // Edge Case Tests + // ======================================================================== + + #[test] + fn test_select_proofs_with_fees_zero_amount() { + let active_id = id(); + let keyset_fee_and_amounts = keyset_fee_and_amounts_with_fee(200); + + let proofs = standard_proofs(); + let amount: Amount = 0.into(); + + let selected_proofs = Wallet::select_proofs( + amount, + proofs, + &vec![active_id], + &keyset_fee_and_amounts, + true, + ) + .unwrap(); + + assert_eq!( + selected_proofs.len(), + 0, + "Zero amount should return empty selection" + ); + } + + #[test] + fn test_select_proofs_with_fees_empty_proofs() { + let active_id = id(); + let keyset_fee_and_amounts = keyset_fee_and_amounts_with_fee(200); + + let proofs: Vec = vec![]; + let amount: Amount = 5000.into(); + + let result = Wallet::select_proofs( + amount, + proofs, + &vec![active_id], + &keyset_fee_and_amounts, + true, + ); + + assert!( + result.is_err(), + "Empty proofs should return InsufficientFunds" + ); + } + + #[test] + fn test_select_proofs_with_fees_all_proofs_same_size() { + use cdk_common::nuts::nut00::ProofsMethods; + + use crate::fees::calculate_fee; + + let active_id = id(); + let keyset_fee_and_amounts = keyset_fee_and_amounts_with_fee(200); + + let proofs = vec![ + proof(1024), + proof(1024), + proof(1024), + proof(1024), + proof(1024), + proof(1024), + ]; + let amount: Amount = 5000.into(); + + let selected_proofs = Wallet::select_proofs( + amount, + proofs, + &vec![active_id], + &keyset_fee_and_amounts, + true, + ) + .unwrap(); + + let total = selected_proofs.total_amount().unwrap(); + let fee = calculate_fee( + &selected_proofs.count_by_keyset(), + &keyset_fee_and_amounts + .iter() + .map(|(k, v)| (*k, v.fee())) + .collect(), + ) + .unwrap(); + let net = total - fee; + + assert!(net >= amount, "Net {} should be >= {}", net, amount); + } + + #[test] + fn test_select_proofs_with_fees_fee_exceeds_small_proof() { + let active_id = id(); + let keyset_fee_and_amounts = keyset_fee_and_amounts_with_fee(1000); + + let proofs = vec![proof(1)]; + let amount: Amount = 1.into(); + + let result = Wallet::select_proofs( + amount, + proofs, + &vec![active_id], + &keyset_fee_and_amounts, + true, + ); + + assert!( + result.is_err(), + "1 sat proof with 1 sat fee is uneconomical" + ); + } + + #[test] + fn test_select_proofs_with_fees_barely_sufficient() { + use cdk_common::nuts::nut00::ProofsMethods; + + use crate::fees::calculate_fee; + + let active_id = id(); + let keyset_fee_and_amounts = keyset_fee_and_amounts_with_fee(200); + + let proofs = vec![ + proof(4096), + proof(1024), + proof(512), + proof(256), + proof(128), + proof(8), + proof(1), + ]; + let amount: Amount = 5000.into(); + + let selected_proofs = Wallet::select_proofs( + amount, + proofs, + &vec![active_id], + &keyset_fee_and_amounts, + true, + ) + .unwrap(); + + let total = selected_proofs.total_amount().unwrap(); + let fee = calculate_fee( + &selected_proofs.count_by_keyset(), + &keyset_fee_and_amounts + .iter() + .map(|(k, v)| (*k, v.fee())) + .collect(), + ) + .unwrap(); + let net = total - fee; + + assert!( + net >= amount, + "Barely sufficient: net {} should be >= {} (total={}, fee={})", + net, + amount, + total, + fee + ); + } + + // ======================================================================== + // Stress Tests + // ======================================================================== + + #[test] + fn test_select_proofs_many_small_proofs_with_fees() { + use cdk_common::nuts::nut00::ProofsMethods; + + use crate::fees::calculate_fee; + + let active_id = id(); + let keyset_fee_and_amounts = keyset_fee_and_amounts_with_fee(100); + + let mut proofs: Vec = (0..500).map(|_| proof(16)).collect(); + proofs.extend((0..200).map(|_| proof(8))); + proofs.extend((0..100).map(|_| proof(4))); + + let amount: Amount = 5000.into(); + + let selected_proofs = Wallet::select_proofs( + amount, + proofs, + &vec![active_id], + &keyset_fee_and_amounts, + true, + ) + .unwrap(); + + let total = selected_proofs.total_amount().unwrap(); + let fee = calculate_fee( + &selected_proofs.count_by_keyset(), + &keyset_fee_and_amounts + .iter() + .map(|(k, v)| (*k, v.fee())) + .collect(), + ) + .unwrap(); + let net = total - fee; + + assert!( + net >= amount, + "Net {} should be >= {} (total={}, fee={}, num_proofs={})", + net, + amount, + total, + fee, + selected_proofs.len() + ); + } + + #[test] + fn test_select_proofs_fee_convergence_with_many_proofs() { + use cdk_common::nuts::nut00::ProofsMethods; + + use crate::fees::calculate_fee; + + let active_id = id(); + let keyset_fee_and_amounts = keyset_fee_and_amounts_with_fee(100); + + let proofs: Vec = (0..600).map(|_| proof(16)).collect(); + let amount: Amount = 5000.into(); + + let selected_proofs = Wallet::select_proofs( + amount, + proofs, + &vec![active_id], + &keyset_fee_and_amounts, + true, + ) + .unwrap(); + + let total = selected_proofs.total_amount().unwrap(); + let fee = calculate_fee( + &selected_proofs.count_by_keyset(), + &keyset_fee_and_amounts + .iter() + .map(|(k, v)| (*k, v.fee())) + .collect(), + ) + .unwrap(); + let net = total - fee; + + assert!( + net >= amount, + "Fee convergence should work: net={}, amount={}, total={}, fee={}, proofs={}", + net, + amount, + total, + fee, + selected_proofs.len() + ); + } + + #[test] + fn test_select_proofs_fragmented_proofs_with_fees() { + use cdk_common::nuts::nut00::ProofsMethods; + + use crate::fees::calculate_fee; + + let active_id = id(); + let keyset_fee_and_amounts = keyset_fee_and_amounts_with_fee(200); + + let proofs = fragmented_proofs(); + let amount: Amount = 5000.into(); + + let selected_proofs = Wallet::select_proofs( + amount, + proofs, + &vec![active_id], + &keyset_fee_and_amounts, + true, + ) + .unwrap(); + + let total = selected_proofs.total_amount().unwrap(); + let fee = calculate_fee( + &selected_proofs.count_by_keyset(), + &keyset_fee_and_amounts + .iter() + .map(|(k, v)| (*k, v.fee())) + .collect(), + ) + .unwrap(); + let net = total - fee; + + assert!( + net >= amount, + "Fragmented proofs: net {} should be >= {} (total={}, fee={}, num_proofs={})", + net, + amount, + total, + fee, + selected_proofs.len() + ); + } + + // ======================================================================== + // Regression Tests + // ======================================================================== + + #[test] + fn test_regression_swap_insufficient_small_proof() { + use cdk_common::nuts::nut00::ProofsMethods; + + use crate::fees::calculate_fee; + + let active_id = id(); + let keyset_fee_and_amounts = keyset_fee_and_amounts_with_fee(200); + + let proofs = vec![ + proof(4096), + proof(1024), + proof(512), + proof(256), + proof(128), + proof(8), + ]; + let amount: Amount = 5000.into(); + + let selected_proofs = Wallet::select_proofs( + amount, + proofs, + &vec![active_id], + &keyset_fee_and_amounts, + true, + ) + .unwrap(); + + let total = selected_proofs.total_amount().unwrap(); + let fee = calculate_fee( + &selected_proofs.count_by_keyset(), + &keyset_fee_and_amounts + .iter() + .map(|(k, v)| (*k, v.fee())) + .collect(), + ) + .unwrap(); + let net = total - fee; + + assert!( + net >= amount, + "Regression: should handle small proofs correctly. Net={}, expected >= {}", + net, + amount + ); + } + + #[test] + fn test_regression_fragmented_proofs_with_fees() { + use cdk_common::nuts::nut00::ProofsMethods; + + use crate::fees::calculate_fee; + + let active_id = id(); + let keyset_fee_and_amounts = keyset_fee_and_amounts_with_fee(200); + + let mut proofs = Vec::new(); + for _ in 0..20 { + proofs.push(proof(1)); + } + for _ in 0..15 { + proofs.push(proof(2)); + } + for _ in 0..12 { + proofs.push(proof(4)); + } + for _ in 0..10 { + proofs.push(proof(8)); + } + for _ in 0..8 { + proofs.push(proof(16)); + } + for _ in 0..6 { + proofs.push(proof(32)); + } + for _ in 0..5 { + proofs.push(proof(64)); + } + for _ in 0..4 { + proofs.push(proof(128)); + } + for _ in 0..3 { + proofs.push(proof(256)); + } + for _ in 0..3 { + proofs.push(proof(512)); + } + for _ in 0..2 { + proofs.push(proof(1024)); + } + for _ in 0..2 { + proofs.push(proof(2048)); + } + + let amount: Amount = 5000.into(); + + let selected_proofs = Wallet::select_proofs( + amount, + proofs, + &vec![active_id], + &keyset_fee_and_amounts, + true, + ) + .unwrap(); + + let total = selected_proofs.total_amount().unwrap(); + let fee = calculate_fee( + &selected_proofs.count_by_keyset(), + &keyset_fee_and_amounts + .iter() + .map(|(k, v)| (*k, v.fee())) + .collect(), + ) + .unwrap(); + let net = total - fee; + + assert!( + net >= amount, + "Fragmented proofs should work: net={}, amount={}", + net, + amount + ); + } + + #[test] + fn test_regression_exact_amount_with_multiple_denominations() { + use cdk_common::nuts::nut00::ProofsMethods; + + use crate::fees::calculate_fee; + + let active_id = id(); + let keyset_fee_and_amounts = keyset_fee_and_amounts_with_fee(200); + + let proofs = vec![ + proof(4096), + proof(1024), + proof(512), + proof(256), + proof(128), + proof(8), + proof(4), + proof(2), + proof(1), + ]; + let amount: Amount = 5007.into(); + + let selected_proofs = Wallet::select_proofs( + amount, + proofs, + &vec![active_id], + &keyset_fee_and_amounts, + true, + ) + .unwrap(); + + let total = selected_proofs.total_amount().unwrap(); + let fee = calculate_fee( + &selected_proofs.count_by_keyset(), + &keyset_fee_and_amounts + .iter() + .map(|(k, v)| (*k, v.fee())) + .collect(), + ) + .unwrap(); + let net = total - fee; + + assert!( + net >= amount, + "Exact amount with multiple denominations: net {} should be >= {} (total={}, fee={})", + net, + amount, + total, + fee + ); + } + + // ======================================================================== + // Inactive Keyset Tests + // ======================================================================== + + fn inactive_id() -> Id { + Id::from_bytes(&[0x00, 1, 1, 1, 1, 1, 1, 1]).unwrap() + } + + fn proof_with_keyset(amount: u64, keyset_id: Id) -> Proof { + Proof::new( + Amount::from(amount), + keyset_id, + Secret::generate(), + PublicKey::from_hex( + "03deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef", + ) + .unwrap(), + ) + } + + #[test] + fn test_select_proofs_inactive_keyset_exact_amount() { + use cdk_common::nuts::nut00::ProofsMethods; + + let inactive = inactive_id(); + let active = id(); + + let mut keyset_fee_and_amounts = HashMap::new(); + keyset_fee_and_amounts.insert( + active, + (0, (0..32).map(|x| 2u64.pow(x)).collect::>()).into(), + ); + + let proofs = vec![ + proof_with_keyset(1, inactive), + proof_with_keyset(1, inactive), + proof_with_keyset(2, inactive), + proof_with_keyset(4, inactive), + proof_with_keyset(8, inactive), + proof_with_keyset(16, inactive), + ]; + + let selected_proofs = Wallet::select_proofs( + 4.into(), + proofs, + &vec![active], + &keyset_fee_and_amounts, + false, + ) + .unwrap(); + + let total = selected_proofs.total_amount().unwrap(); + assert_eq!( + total, + 4.into(), + "Should select exactly 4 sats worth of proofs from inactive keyset, got {}", + total + ); + } + + #[test] + fn test_select_proofs_inactive_keyset_minimum_over() { + use cdk_common::nuts::nut00::ProofsMethods; + + let inactive = inactive_id(); + let active = id(); + + let mut keyset_fee_and_amounts = HashMap::new(); + keyset_fee_and_amounts.insert( + active, + (0, (0..32).map(|x| 2u64.pow(x)).collect::>()).into(), + ); + + let proofs = vec![ + proof_with_keyset(8, inactive), + proof_with_keyset(16, inactive), + proof_with_keyset(32, inactive), + ]; + + let selected_proofs = Wallet::select_proofs( + 5.into(), + proofs, + &vec![active], + &keyset_fee_and_amounts, + false, + ) + .unwrap(); + + let total = selected_proofs.total_amount().unwrap(); + assert_eq!( + total, + 8.into(), + "Should select minimum amount (8) that covers 5 sats, got {}", + total + ); + assert_eq!(selected_proofs.len(), 1, "Should select only 1 proof"); + } + + #[test] + fn test_select_proofs_active_keyset_exact_4_sats_with_fee() { + use cdk_common::nuts::nut00::ProofsMethods; + + let active = id(); + + let mut keyset_fee_and_amounts = HashMap::new(); + keyset_fee_and_amounts.insert( + active, + (100, (0..32).map(|x| 2u64.pow(x)).collect::>()).into(), + ); + + let proofs = vec![ + proof(1), + proof(1), + proof(1), + proof(1), + proof(2), + proof(2), + proof(2), + proof(2), + proof(4), + proof(4), + proof(4), + proof(4), + proof(8), + proof(8), + proof(8), + proof(16), + proof(16), + proof(16), + ]; + + let selected_proofs = Wallet::select_proofs( + 4.into(), + proofs, + &vec![active], + &keyset_fee_and_amounts, + false, + ) + .unwrap(); + + let total = selected_proofs.total_amount().unwrap(); + assert_eq!( + total, + 4.into(), + "Should select exactly 4 sats worth of proofs, got {}", + total + ); + assert_eq!( + selected_proofs.len(), + 1, + "Should select only 1 proof (the 4-sat one)" + ); + } + + #[test] + fn test_select_proofs_multiple_keysets_does_not_double_select() { + use cdk_common::nuts::nut00::ProofsMethods; + + let active = id(); + let other_keyset = inactive_id(); + + let mut keyset_fee_and_amounts = HashMap::new(); + keyset_fee_and_amounts.insert( + active, + (100, (0..32).map(|x| 2u64.pow(x)).collect::>()).into(), + ); + keyset_fee_and_amounts.insert( + other_keyset, + (100, (0..32).map(|x| 2u64.pow(x)).collect::>()).into(), + ); + + let proofs = vec![ + proof(1), + proof(1), + proof(1), + proof(1), + proof(2), + proof(2), + proof(2), + proof(2), + proof(4), + proof(4), + proof(4), + proof(4), + proof(8), + proof(8), + proof(8), + proof(16), + proof(16), + proof(16), + ]; + + let selected_proofs = Wallet::select_proofs( + 4.into(), + proofs, + &vec![active], + &keyset_fee_and_amounts, + false, + ) + .unwrap(); + + let total = selected_proofs.total_amount().unwrap(); + assert_eq!( + total, + 4.into(), + "Should select exactly 4 sats worth even with multiple keysets in fee map, got {}", + total + ); + assert_eq!(selected_proofs.len(), 1, "Should select only 1 proof"); + } } diff --git a/crates/cdk/src/wallet/send.rs b/crates/cdk/src/wallet/send.rs index 6b4d41235..b34a40b5d 100644 --- a/crates/cdk/src/wallet/send.rs +++ b/crates/cdk/src/wallet/send.rs @@ -4,10 +4,12 @@ use std::fmt::Debug; use cdk_common::nut02::KeySetInfosMethods; use cdk_common::util::unix_time; use cdk_common::wallet::{Transaction, TransactionDirection}; +use cdk_common::Id; use tracing::instrument; use super::SendKind; use crate::amount::SplitTarget; +use crate::fees::calculate_fee; use crate::nuts::nut00::ProofsMethods; use crate::nuts::{Proofs, SpendingConditions, State, Token}; use crate::{Amount, Error, Wallet}; @@ -82,8 +84,34 @@ impl Wallet { .map(|k| k.id) .collect(); + // When including fees, we need to account for both: + // 1. Input fees (to spend the selected proofs) + // 2. Output fees (send_fee - fee to redeem the token we create) + // + // If proofs don't exactly match the desired denominations, a swap is needed. + // The swap consumes the input fee, and the outputs must cover amount + send_fee. + // So we select proofs for (amount + send_fee) to ensure the swap can succeed. + let active_keyset_id = self.get_active_keyset().await?.id; + let fee_and_amounts = self + .get_keyset_fees_and_amounts_by_id(active_keyset_id) + .await?; + + let selection_amount = if opts.include_fee { + let send_split = amount.split_with_fee(&fee_and_amounts)?; + let send_fee = self + .get_proofs_fee_by_count( + vec![(active_keyset_id, send_split.len() as u64)] + .into_iter() + .collect(), + ) + .await?; + amount + send_fee + } else { + amount + }; + let selected_proofs = Wallet::select_proofs( - amount, + selection_amount, available_proofs, &active_keyset_ids, &keyset_fees, @@ -163,39 +191,36 @@ impl Wallet { exact_proofs &= proofs.len() <= max_proofs; } - // Split proofs to swap and send - let mut proofs_to_swap = Proofs::new(); - let mut proofs_to_send = Proofs::new(); - if force_swap { - proofs_to_swap = proofs; - } else if exact_proofs || opts.send_kind.is_offline() || opts.send_kind.has_tolerance() { - proofs_to_send = proofs; - } else { - let mut remaining_send_amounts = send_amounts.clone(); - for proof in proofs { - if let Some(idx) = remaining_send_amounts - .iter() - .position(|a| a == &proof.amount) - { - proofs_to_send.push(proof); - remaining_send_amounts.remove(idx); - } else { - proofs_to_swap.push(proof); - } - } - } + // Determine if we should send all proofs directly + let is_exact_or_offline = + exact_proofs || opts.send_kind.is_offline() || opts.send_kind.has_tolerance(); + + // Get keyset fees for the split function + let keyset_fees_and_amounts = self.get_keyset_fees_and_amounts().await?; + let keyset_fees: HashMap = keyset_fees_and_amounts + .iter() + .map(|(key, values)| (*key, values.fee())) + .collect(); - // Calculate swap fee - let swap_fee = self.get_proofs_fee(&proofs_to_swap).await?; + // Split proofs between send and swap + let split_result = split_proofs_for_send( + proofs, + &send_amounts, + amount, + send_fee, + &keyset_fees, + force_swap, + is_exact_or_offline, + )?; // Return prepared send Ok(PreparedSend { wallet: self.clone(), amount, options: opts, - proofs_to_swap, - swap_fee, - proofs_to_send, + proofs_to_swap: split_result.proofs_to_swap, + swap_fee: split_result.swap_fee, + proofs_to_send: split_result.proofs_to_send, send_fee, }) } @@ -279,8 +304,11 @@ impl PreparedSend { // Swap proofs if necessary if !self.proofs_to_swap.is_empty() { - let swap_amount = total_send_amount - proofs_to_send.total_amount()?; + let swap_amount = total_send_amount + .checked_sub(proofs_to_send.total_amount()?) + .unwrap_or(Amount::ZERO); tracing::debug!("Swapping proofs; swap_amount={:?}", swap_amount); + if let Some(proofs) = self .wallet .swap( @@ -456,3 +484,1211 @@ impl SendMemo { } } } + +/// Result of splitting proofs for a send operation +#[derive(Debug, Clone)] +pub struct ProofSplitResult { + /// Proofs that can be sent directly (matching desired denominations) + pub proofs_to_send: Proofs, + /// Proofs that need to be swapped first + pub proofs_to_swap: Proofs, + /// Fee required for the swap operation + pub swap_fee: Amount, +} + +/// Split proofs between those to send directly and those requiring swap. +/// +/// This is a pure function that implements the core logic of `internal_prepare_send`: +/// 1. Match proofs to desired send amounts +/// 2. Ensure proofs_to_swap can cover swap fees plus needed output +/// 3. Move proofs from send to swap if needed to cover fees +/// +/// # Arguments +/// * `proofs` - All selected proofs to split +/// * `send_amounts` - Desired output denominations +/// * `amount` - Amount to send +/// * `send_fee` - Fee the recipient will pay to redeem +/// * `keyset_fees` - Map of keyset ID to fee_ppk +/// * `force_swap` - If true, all proofs go to swap +/// * `is_exact_or_offline` - If true (exact match or offline mode), all proofs go to send +pub fn split_proofs_for_send( + proofs: Proofs, + send_amounts: &[Amount], + amount: Amount, + send_fee: Amount, + keyset_fees: &HashMap, + force_swap: bool, + is_exact_or_offline: bool, +) -> Result { + let mut proofs_to_swap = Proofs::new(); + let mut proofs_to_send = Proofs::new(); + + if force_swap { + proofs_to_swap = proofs; + } else if is_exact_or_offline { + proofs_to_send = proofs; + } else { + let mut remaining_send_amounts: Vec = send_amounts.to_vec(); + for proof in proofs { + if let Some(idx) = remaining_send_amounts + .iter() + .position(|a| a == &proof.amount) + { + proofs_to_send.push(proof); + remaining_send_amounts.remove(idx); + } else { + proofs_to_swap.push(proof); + } + } + + // Check if swap is actually needed + if !proofs_to_swap.is_empty() { + let swap_output_needed = (amount + send_fee) + .checked_sub(proofs_to_send.total_amount()?) + .unwrap_or(Amount::ZERO); + + if swap_output_needed == Amount::ZERO { + // proofs_to_send already covers the full amount, no swap needed + // Clear proofs_to_swap - these are just leftover proofs that don't match + // any send denomination but aren't needed for the send + proofs_to_swap.clear(); + } else { + // Ensure proofs_to_swap can cover the swap's input fee plus the needed output + loop { + let swap_input_fee = + calculate_fee(&proofs_to_swap.count_by_keyset(), keyset_fees)?; + let swap_total = proofs_to_swap.total_amount()?; + + let swap_can_produce = swap_total.checked_sub(swap_input_fee); + + match swap_can_produce { + Some(can_produce) if can_produce >= swap_output_needed => { + break; + } + _ => { + if proofs_to_send.is_empty() { + return Err(Error::InsufficientFunds); + } + + // Move the smallest proof from send to swap + proofs_to_send.sort_by(|a, b| a.amount.cmp(&b.amount)); + let proof_to_move = proofs_to_send.remove(0); + proofs_to_swap.push(proof_to_move); + } + } + } + } + } + } + + let swap_fee = calculate_fee(&proofs_to_swap.count_by_keyset(), keyset_fees)?; + + Ok(ProofSplitResult { + proofs_to_send, + proofs_to_swap, + swap_fee, + }) +} + +#[cfg(test)] +mod tests { + use cdk_common::secret::Secret; + use cdk_common::{Amount, Id, Proof, PublicKey}; + + use super::*; + + fn id() -> Id { + Id::from_bytes(&[0; 8]).unwrap() + } + + fn proof(amount: u64) -> Proof { + Proof::new( + Amount::from(amount), + id(), + Secret::generate(), + PublicKey::from_hex( + "03deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef", + ) + .unwrap(), + ) + } + + fn proofs(amounts: &[u64]) -> Proofs { + amounts.iter().map(|&a| proof(a)).collect() + } + + fn keyset_fees_with_ppk(fee_ppk: u64) -> HashMap { + let mut fees = HashMap::new(); + fees.insert(id(), fee_ppk); + fees + } + + fn amounts(values: &[u64]) -> Vec { + values.iter().map(|&v| Amount::from(v)).collect() + } + + // ======================================================================== + // No Swap Needed (Exact Proofs) Tests + // ======================================================================== + + #[test] + fn test_split_exact_match_simple() { + let input_proofs = proofs(&[8, 2]); + let send_amounts = amounts(&[8, 2]); + let keyset_fees = keyset_fees_with_ppk(200); + + let result = split_proofs_for_send( + input_proofs, + &send_amounts, + Amount::from(10), + Amount::from(1), + &keyset_fees, + false, + true, // exact match + ) + .unwrap(); + + assert_eq!(result.proofs_to_send.len(), 2); + assert!(result.proofs_to_swap.is_empty()); + assert_eq!(result.swap_fee, Amount::ZERO); + } + + #[test] + fn test_split_exact_match_six_proofs() { + let input_proofs = proofs(&[2048, 1024, 512, 256, 128, 32]); + let send_amounts = amounts(&[2048, 1024, 512, 256, 128, 32]); + let keyset_fees = keyset_fees_with_ppk(200); + + let result = split_proofs_for_send( + input_proofs, + &send_amounts, + Amount::from(4000), + Amount::from(2), + &keyset_fees, + false, + true, + ) + .unwrap(); + + assert_eq!(result.proofs_to_send.len(), 6); + assert!(result.proofs_to_swap.is_empty()); + } + + #[test] + fn test_split_exact_match_ten_proofs() { + let input_proofs = proofs(&[4096, 2048, 1024, 512, 256, 128, 64, 32, 16, 8]); + let send_amounts = amounts(&[4096, 2048, 1024, 512, 256, 128, 64, 32, 16, 8]); + let keyset_fees = keyset_fees_with_ppk(200); + + let result = split_proofs_for_send( + input_proofs, + &send_amounts, + Amount::from(8000), + Amount::from(2), + &keyset_fees, + false, + true, + ) + .unwrap(); + + assert_eq!(result.proofs_to_send.len(), 10); + assert!(result.proofs_to_swap.is_empty()); + } + + #[test] + fn test_split_exact_match_powers_of_two() { + let input_proofs = proofs(&[4096, 512, 256, 128, 8]); + let send_amounts = amounts(&[4096, 512, 256, 128, 8]); + let keyset_fees = keyset_fees_with_ppk(200); + + let result = split_proofs_for_send( + input_proofs, + &send_amounts, + Amount::from(5000), + Amount::from(1), + &keyset_fees, + false, + true, + ) + .unwrap(); + + assert_eq!(result.proofs_to_send.len(), 5); + assert!(result.proofs_to_swap.is_empty()); + } + + // ======================================================================== + // Swap Required - Partial Match Tests + // ======================================================================== + + #[test] + fn test_split_single_mismatch() { + let input_proofs = proofs(&[8, 4, 2, 1]); + let send_amounts = amounts(&[8, 2]); + let keyset_fees = keyset_fees_with_ppk(200); + + let result = split_proofs_for_send( + input_proofs, + &send_amounts, + Amount::from(10), + Amount::from(1), + &keyset_fees, + false, + false, + ) + .unwrap(); + + let send_amounts_result: Vec = result + .proofs_to_send + .iter() + .map(|p| p.amount.into()) + .collect(); + let swap_amounts_result: Vec = result + .proofs_to_swap + .iter() + .map(|p| p.amount.into()) + .collect(); + + assert!(send_amounts_result.contains(&8)); + assert!(send_amounts_result.contains(&2)); + assert!(swap_amounts_result.contains(&4) || swap_amounts_result.contains(&1)); + } + + #[test] + fn test_split_multiple_mismatches() { + let input_proofs = proofs(&[4096, 1024, 512, 256, 64, 32, 16, 8]); + let send_amounts = amounts(&[4096, 512, 256, 128, 8]); + let keyset_fees = keyset_fees_with_ppk(200); + + let result = split_proofs_for_send( + input_proofs, + &send_amounts, + Amount::from(5000), + Amount::from(1), + &keyset_fees, + false, + false, + ) + .unwrap(); + + let send_amounts_result: Vec = result + .proofs_to_send + .iter() + .map(|p| p.amount.into()) + .collect(); + + // 4096, 512, 256, 8 should match; 128 not in input, 1024, 64, 32, 16 to swap + assert!(send_amounts_result.contains(&4096)); + assert!(send_amounts_result.contains(&512)); + assert!(send_amounts_result.contains(&256)); + assert!(send_amounts_result.contains(&8)); + assert!(!result.proofs_to_swap.is_empty()); + } + + #[test] + fn test_split_half_match() { + let input_proofs = proofs(&[2048, 2048, 1024, 512, 256, 128, 64, 32]); + let send_amounts = amounts(&[4096, 512, 256, 128, 8]); + let keyset_fees = keyset_fees_with_ppk(200); + + let result = split_proofs_for_send( + input_proofs, + &send_amounts, + Amount::from(5000), + Amount::from(1), + &keyset_fees, + false, + false, + ) + .unwrap(); + + let send_amounts_result: Vec = result + .proofs_to_send + .iter() + .map(|p| p.amount.into()) + .collect(); + + // Only 512, 256, 128 should match (no 4096 or 8 in input) + assert!(send_amounts_result.contains(&512)); + assert!(send_amounts_result.contains(&256)); + assert!(send_amounts_result.contains(&128)); + assert!(!result.proofs_to_swap.is_empty()); + } + + #[test] + fn test_split_large_swap_set() { + let input_proofs = proofs(&[1024, 1024, 1024, 1024, 1024, 512, 256, 128, 64, 32, 16, 8]); + let send_amounts = amounts(&[4096, 512, 256, 128, 8]); + let keyset_fees = keyset_fees_with_ppk(200); + + let result = split_proofs_for_send( + input_proofs, + &send_amounts, + Amount::from(5000), + Amount::from(1), + &keyset_fees, + false, + false, + ) + .unwrap(); + + let send_amounts_result: Vec = result + .proofs_to_send + .iter() + .map(|p| p.amount.into()) + .collect(); + + assert!(send_amounts_result.contains(&512)); + assert!(send_amounts_result.contains(&256)); + assert!(send_amounts_result.contains(&128)); + assert!(send_amounts_result.contains(&8)); + // All 1024s and 64, 32, 16 should be in swap + assert!(result.proofs_to_swap.len() >= 5); + } + + #[test] + fn test_split_dense_small_proofs() { + let input_proofs = proofs(&[ + 512, 256, 256, 128, 128, 128, 64, 64, 64, 64, 32, 32, 16, 16, 8, 8, 4, 4, 2, 2, + ]); + let send_amounts = amounts(&[1024, 256, 128, 64, 16, 8, 4]); + let keyset_fees = keyset_fees_with_ppk(200); + + let result = split_proofs_for_send( + input_proofs, + &send_amounts, + Amount::from(1500), + Amount::from(2), + &keyset_fees, + false, + false, + ) + .unwrap(); + + // No 1024 in input, so swap needed + assert!(!result.proofs_to_swap.is_empty()); + // Should have matched some proofs + let send_amounts_result: Vec = result + .proofs_to_send + .iter() + .map(|p| p.amount.into()) + .collect(); + assert!( + send_amounts_result.contains(&256) + || send_amounts_result.contains(&128) + || send_amounts_result.contains(&64) + ); + } + + // ======================================================================== + // Swap Required - No Match Tests + // ======================================================================== + + #[test] + fn test_split_fragmented_no_match() { + // 64×10, 32×5, 16×10, 8×5 = 640 + 160 + 160 + 40 = 1000 + let mut input_amounts = vec![]; + for _ in 0..10 { + input_amounts.push(64); + } + for _ in 0..5 { + input_amounts.push(32); + } + for _ in 0..10 { + input_amounts.push(16); + } + for _ in 0..5 { + input_amounts.push(8); + } + let input_proofs = proofs(&input_amounts); + let send_amounts = amounts(&[512, 256, 128, 64, 32, 8]); + let keyset_fees = keyset_fees_with_ppk(200); + + let result = split_proofs_for_send( + input_proofs, + &send_amounts, + Amount::from(1000), + Amount::from(2), + &keyset_fees, + false, + false, + ) + .unwrap(); + + // Some proofs should match (64, 32, 8 exist in input) + let send_amounts_result: Vec = result + .proofs_to_send + .iter() + .map(|p| p.amount.into()) + .collect(); + // 512, 256, 128 don't exist so need swap + assert!(!result.proofs_to_swap.is_empty()); + // But 64, 32, 8 should be in send + assert!( + send_amounts_result.contains(&64) + || send_amounts_result.contains(&32) + || send_amounts_result.contains(&8) + ); + } + + #[test] + fn test_split_large_fragmented() { + // 256×8, 128×4, 64×8, 32×4, 16×8, 8×4 = 2048 + 512 + 512 + 128 + 128 + 32 = 3360 + let mut input_amounts = vec![]; + for _ in 0..8 { + input_amounts.push(256); + } + for _ in 0..4 { + input_amounts.push(128); + } + for _ in 0..8 { + input_amounts.push(64); + } + for _ in 0..4 { + input_amounts.push(32); + } + for _ in 0..8 { + input_amounts.push(16); + } + for _ in 0..4 { + input_amounts.push(8); + } + let input_proofs = proofs(&input_amounts); + // Total = 8*256 + 4*128 + 8*64 + 4*32 + 8*16 + 4*8 = 2048+512+512+128+128+32 = 3360 + // Use send_amounts that DON'T all exist in input to force swap + let send_amounts = amounts(&[512, 256, 128, 64, 32, 8]); + let keyset_fees = keyset_fees_with_ppk(200); + + let result = split_proofs_for_send( + input_proofs, + &send_amounts, + Amount::from(1000), + Amount::from(2), + &keyset_fees, + false, + false, + ) + .unwrap(); + + // 256, 128, 64, 32, 8 exist in input but 512 doesn't + // proofs_to_send = [256, 128, 64, 32, 8] = 488 + // swap_output_needed = (1000 + 2) - 488 = 514 + let send_amounts_result: Vec = result + .proofs_to_send + .iter() + .map(|p| p.amount.into()) + .collect(); + assert!( + send_amounts_result.contains(&256) + || send_amounts_result.contains(&128) + || send_amounts_result.contains(&32) + ); + // Most proofs need swapping since we need to produce 514 from swap + assert!(result.proofs_to_swap.len() > 10); + } + + // ======================================================================== + // Swap Fee Adjustment Tests + // ======================================================================== + + #[test] + fn test_split_swap_sufficient() { + let input_proofs = proofs(&[4096, 512, 256, 128, 8, 64, 32]); + let send_amounts = amounts(&[4096, 512, 256, 128, 8]); + let keyset_fees = keyset_fees_with_ppk(200); + + let result = split_proofs_for_send( + input_proofs, + &send_amounts, + Amount::from(5000), + Amount::from(1), + &keyset_fees, + false, + false, + ) + .unwrap(); + + // 64, 32 go to swap (96 total), fee = 1, can produce 95 >= 0 needed + let swap_amounts: Vec = result + .proofs_to_swap + .iter() + .map(|p| p.amount.into()) + .collect(); + assert!(swap_amounts.contains(&64) || swap_amounts.contains(&32)); + } + + #[test] + fn test_split_swap_barely_sufficient() { + // Test where proofs_to_send doesn't fully cover amount+fee, requiring swap + let input_proofs = proofs(&[2048, 1024, 256, 128, 32, 16, 8, 4, 2, 1]); + // Note: removed 64 from input, so send_amounts won't fully match + let send_amounts = amounts(&[2048, 1024, 256, 128, 64]); + let keyset_fees = keyset_fees_with_ppk(200); + + let result = split_proofs_for_send( + input_proofs, + &send_amounts, + Amount::from(3520), + Amount::from(1), + &keyset_fees, + false, + false, + ) + .unwrap(); + + // proofs_to_send = [2048, 1024, 256, 128] = 3456 (no 64 in input) + // swap_output_needed = (3520 + 1) - 3456 = 65 + // proofs_to_swap = [32, 16, 8, 4, 2, 1] = 63, fee = 2, can produce 61 < 65 + // So swap needs more proofs moved from send + assert!(!result.proofs_to_swap.is_empty()); + + let swap_total: u64 = result + .proofs_to_swap + .iter() + .map(|p| u64::from(p.amount)) + .sum(); + let swap_fee: u64 = result.swap_fee.into(); + assert!(swap_total - swap_fee >= 65); + } + + #[test] + fn test_split_move_one_proof() { + // Scenario: to_send has [4096, 512, 256, 128, 64, 32], to_swap has [16, 8] + // swap_output_needed = 50, swap can produce 24-1=23 < 50 + // Need to move 32 to swap: 24+32=56, fee=1, can produce 55 >= 50 + let input_proofs = proofs(&[4096, 512, 256, 128, 64, 32, 16, 8]); + let send_amounts = amounts(&[4096, 512, 256, 128, 64, 32]); + let keyset_fees = keyset_fees_with_ppk(200); + + // We need swap to produce 50 sats + // send = 4096+512+256+128+64+32 = 5088, amount+fee = 5088+50 = 5138 + let result = split_proofs_for_send( + input_proofs, + &send_amounts, + Amount::from(5088), + Amount::from(50), + &keyset_fees, + false, + false, + ) + .unwrap(); + + // Should have moved 32 (smallest) from send to swap + let swap_total: u64 = result + .proofs_to_swap + .iter() + .map(|p| u64::from(p.amount)) + .sum(); + // 16 + 8 + 32 = 56, or some variation + assert!(swap_total >= 50); + } + + #[test] + fn test_split_move_multiple_proofs() { + let input_proofs = proofs(&[2048, 1024, 512, 256, 128, 64, 8, 4, 2, 1]); + let send_amounts = amounts(&[2048, 1024, 512, 256, 128, 64]); + let keyset_fees = keyset_fees_with_ppk(200); + + // swap has [8,4,2,1] = 15, need output of 100 + // fee = 1, can produce 14 < 100 + // Need to move proofs + let result = split_proofs_for_send( + input_proofs, + &send_amounts, + Amount::from(4032), + Amount::from(100), + &keyset_fees, + false, + false, + ) + .unwrap(); + + let swap_total: u64 = result + .proofs_to_swap + .iter() + .map(|p| u64::from(p.amount)) + .sum(); + let swap_fee: u64 = result.swap_fee.into(); + // Should have moved enough to cover 100 + assert!(swap_total - swap_fee >= 100); + } + + #[test] + fn test_split_high_fee_many_proofs() { + let input_proofs = proofs(&[1024, 512, 256, 128, 64, 32, 16, 8, 4, 4, 2, 2, 1, 1, 1, 1]); + let send_amounts = amounts(&[1024, 512, 256, 128, 64, 32, 16, 8]); + let keyset_fees = keyset_fees_with_ppk(1000); // 1 sat per proof + + // swap has [4,4,2,2,1,1,1,1] = 16, 8 proofs, fee = 8, can produce 8 + // Need to produce 10 + let result = split_proofs_for_send( + input_proofs, + &send_amounts, + Amount::from(2040), + Amount::from(10), + &keyset_fees, + false, + false, + ) + .unwrap(); + + let swap_total: u64 = result + .proofs_to_swap + .iter() + .map(|p| u64::from(p.amount)) + .sum(); + let swap_fee: u64 = result.swap_fee.into(); + assert!(swap_total - swap_fee >= 10); + } + + #[test] + fn test_split_fee_eats_small_proofs() { + let input_proofs = proofs(&[4096, 512, 256, 128, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]); + let send_amounts = amounts(&[4096, 512, 256, 128]); + let keyset_fees = keyset_fees_with_ppk(1000); // 1 sat per proof + + // swap has 10×1 = 10, fee = 10, can produce 0 + // Need to produce 5 + let result = split_proofs_for_send( + input_proofs, + &send_amounts, + Amount::from(4992), + Amount::from(5), + &keyset_fees, + false, + false, + ) + .unwrap(); + + let swap_total: u64 = result + .proofs_to_swap + .iter() + .map(|p| u64::from(p.amount)) + .sum(); + let swap_fee: u64 = result.swap_fee.into(); + // Must have moved a larger proof (128) to swap + assert!(swap_total - swap_fee >= 5); + assert!(swap_total > 10); // More than just the 1s + } + + #[test] + fn test_split_cascading_fee_increase() { + let input_proofs = proofs(&[2048, 1024, 512, 256, 128, 64, 32, 16, 8, 4, 2, 1]); + let send_amounts = amounts(&[2048, 1024, 512, 256, 128, 64]); + let keyset_fees = keyset_fees_with_ppk(500); // 0.5 sat per proof + + // swap has [32,16,8,4,2,1] = 63, 6 proofs, fee = 3, can produce 60 + // Need 80 + let result = split_proofs_for_send( + input_proofs, + &send_amounts, + Amount::from(4032), + Amount::from(80), + &keyset_fees, + false, + false, + ) + .unwrap(); + + let swap_total: u64 = result + .proofs_to_swap + .iter() + .map(|p| u64::from(p.amount)) + .sum(); + let swap_fee: u64 = result.swap_fee.into(); + assert!(swap_total - swap_fee >= 80); + } + + // ======================================================================== + // Complex Scenarios with Many Proofs + // ======================================================================== + + #[test] + fn test_split_20_proofs_mixed() { + // [2048, 1024, 512, 256×2, 128×2, 64×4, 32×4, 16×4] + // Count: 1 + 1 + 1 + 2 + 2 + 4 + 4 + 4 = 19 proofs. Need one more for 20. + let mut input_amounts = vec![2048, 1024, 512]; + input_amounts.extend(vec![256; 2]); + input_amounts.extend(vec![128; 2]); + input_amounts.extend(vec![64; 4]); + input_amounts.extend(vec![32; 4]); + input_amounts.extend(vec![16; 4]); + input_amounts.push(8); // Add one more to make 20 + let input_proofs = proofs(&input_amounts); + // Use send amounts that match proofs in input + let send_amounts = amounts(&[2048, 1024, 512, 256, 128]); + let keyset_fees = keyset_fees_with_ppk(200); + + let result = split_proofs_for_send( + input_proofs, + &send_amounts, + Amount::from(3968), // 2048+1024+512+256+128 = 3968 + Amount::from(1), + &keyset_fees, + false, + false, + ) + .unwrap(); + + // All send_amounts exist in input + let send_amounts_result: Vec = result + .proofs_to_send + .iter() + .map(|p| p.amount.into()) + .collect(); + // Check some proofs went to send + assert!( + send_amounts_result.contains(&2048) + || send_amounts_result.contains(&1024) + || send_amounts_result.contains(&512) + ); + // Some proofs to swap (the extras) + assert!(!result.proofs_to_swap.is_empty()); + // Total proofs preserved + assert_eq!( + result.proofs_to_send.len() + result.proofs_to_swap.len(), + 20 + ); + } + + #[test] + fn test_split_30_small_proofs() { + // [256×2, 128×4, 64×6, 32×6, 16×6, 8×6] + let mut input_amounts = vec![]; + input_amounts.extend(vec![256; 2]); + input_amounts.extend(vec![128; 4]); + input_amounts.extend(vec![64; 6]); + input_amounts.extend(vec![32; 6]); + input_amounts.extend(vec![16; 6]); + input_amounts.extend(vec![8; 6]); + let input_proofs = proofs(&input_amounts); + let send_amounts = amounts(&[1024, 512, 256, 128, 64, 8]); + let keyset_fees = keyset_fees_with_ppk(200); + + let result = split_proofs_for_send( + input_proofs, + &send_amounts, + Amount::from(2000), + Amount::from(6), // 30 proofs = 6 sat fee @ 200ppk + &keyset_fees, + false, + false, + ) + .unwrap(); + + assert_eq!( + result.proofs_to_send.len() + result.proofs_to_swap.len(), + 30 + ); + } + + #[test] + fn test_split_15_proofs_high_fee() { + // [4096, 1024×2, 512×2, 256×2, 128×2, 64×2, 32×2, 16×2] + let mut input_amounts = vec![4096]; + input_amounts.extend(vec![1024; 2]); + input_amounts.extend(vec![512; 2]); + input_amounts.extend(vec![256; 2]); + input_amounts.extend(vec![128; 2]); + input_amounts.extend(vec![64; 2]); + input_amounts.extend(vec![32; 2]); + input_amounts.extend(vec![16; 2]); + let input_proofs = proofs(&input_amounts); + let send_amounts = amounts(&[4096, 2048, 1024, 512, 256, 64]); + let keyset_fees = keyset_fees_with_ppk(500); + + let result = split_proofs_for_send( + input_proofs, + &send_amounts, + Amount::from(8000), + Amount::from(8), // 15 proofs = 8 sat fee @ 500ppk + &keyset_fees, + false, + false, + ) + .unwrap(); + + assert_eq!( + result.proofs_to_send.len() + result.proofs_to_swap.len(), + 15 + ); + } + + #[test] + fn test_split_uniform_25_proofs() { + let input_proofs = proofs(&[256; 25]); + let send_amounts = amounts(&[4096, 512, 256, 128, 8]); + let keyset_fees = keyset_fees_with_ppk(200); + + let result = split_proofs_for_send( + input_proofs, + &send_amounts, + Amount::from(5000), + Amount::from(1), + &keyset_fees, + false, + false, + ) + .unwrap(); + + // Only one 256 matches + let send_count = result.proofs_to_send.len(); + let swap_count = result.proofs_to_swap.len(); + assert_eq!(send_count + swap_count, 25); + assert_eq!(send_count, 1); // Only one 256 matches + } + + #[test] + fn test_split_tiered_18_proofs() { + // [4096, 2048, 1024×2, 512×2, 256×4, 128×4, 64×4] + let mut input_amounts = vec![4096, 2048]; + input_amounts.extend(vec![1024; 2]); + input_amounts.extend(vec![512; 2]); + input_amounts.extend(vec![256; 4]); + input_amounts.extend(vec![128; 4]); + input_amounts.extend(vec![64; 4]); + let input_proofs = proofs(&input_amounts); + let send_amounts = amounts(&[8192, 1024, 512, 256, 8]); + let keyset_fees = keyset_fees_with_ppk(200); + + let result = split_proofs_for_send( + input_proofs, + &send_amounts, + Amount::from(10000), + Amount::from(4), // 18 proofs = 4 sat fee @ 200ppk + &keyset_fees, + false, + false, + ) + .unwrap(); + + assert_eq!( + result.proofs_to_send.len() + result.proofs_to_swap.len(), + 18 + ); + } + + #[test] + fn test_split_dust_consolidation() { + // [16×50, 8×50, 4×50, 2×50, 1×50] = 250 proofs + let mut input_amounts = vec![]; + input_amounts.extend(vec![16; 50]); + input_amounts.extend(vec![8; 50]); + input_amounts.extend(vec![4; 50]); + input_amounts.extend(vec![2; 50]); + input_amounts.extend(vec![1; 50]); + let input_proofs = proofs(&input_amounts); + let send_amounts = amounts(&[1024, 256, 128, 64, 16, 8, 4]); + let keyset_fees = keyset_fees_with_ppk(100); + + let result = split_proofs_for_send( + input_proofs, + &send_amounts, + Amount::from(1500), + Amount::from(25), // 250 proofs = 25 sat fee @ 100ppk + &keyset_fees, + false, + false, + ) + .unwrap(); + + // 16, 8, 4 exist and match + let send_amounts_result: Vec = result + .proofs_to_send + .iter() + .map(|p| p.amount.into()) + .collect(); + assert!( + send_amounts_result.contains(&16) + || send_amounts_result.contains(&8) + || send_amounts_result.contains(&4) + ); + } + + // ======================================================================== + // Force Swap Scenarios + // ======================================================================== + + #[test] + fn test_split_force_swap_8_proofs() { + let input_proofs = proofs(&[2048, 1024, 512, 256, 128, 64, 32, 16]); + let send_amounts = amounts(&[2048, 1024, 512, 256, 128, 32]); + let keyset_fees = keyset_fees_with_ppk(200); + + let result = split_proofs_for_send( + input_proofs, + &send_amounts, + Amount::from(3000), + Amount::from(2), + &keyset_fees, + true, // force_swap + false, + ) + .unwrap(); + + assert!(result.proofs_to_send.is_empty()); + assert_eq!(result.proofs_to_swap.len(), 8); + } + + #[test] + fn test_split_force_swap_15_proofs() { + let mut input_amounts = vec![]; + input_amounts.extend(vec![1024; 5]); + input_amounts.extend(vec![512; 5]); + input_amounts.extend(vec![256; 5]); + let input_proofs = proofs(&input_amounts); + let send_amounts = amounts(&[8000]); + let keyset_fees = keyset_fees_with_ppk(200); + + let result = split_proofs_for_send( + input_proofs, + &send_amounts, + Amount::from(8000), + Amount::from(3), + &keyset_fees, + true, // force_swap + false, + ) + .unwrap(); + + assert!(result.proofs_to_send.is_empty()); + assert_eq!(result.proofs_to_swap.len(), 15); + } + + #[test] + fn test_split_force_swap_fragmented() { + // 64×10, 32×10, 16×10, 8×10 = 40 proofs + let mut input_amounts = vec![]; + input_amounts.extend(vec![64; 10]); + input_amounts.extend(vec![32; 10]); + input_amounts.extend(vec![16; 10]); + input_amounts.extend(vec![8; 10]); + let input_proofs = proofs(&input_amounts); + let send_amounts = amounts(&[2000]); + let keyset_fees = keyset_fees_with_ppk(200); + + let result = split_proofs_for_send( + input_proofs, + &send_amounts, + Amount::from(2000), + Amount::from(8), + &keyset_fees, + true, // force_swap + false, + ) + .unwrap(); + + assert!(result.proofs_to_send.is_empty()); + assert_eq!(result.proofs_to_swap.len(), 40); + } + + // ======================================================================== + // Edge Cases + // ======================================================================== + + #[test] + fn test_split_single_large_proof() { + let input_proofs = proofs(&[8192]); + let send_amounts = amounts(&[4096, 2048, 1024, 512, 256, 64]); + let keyset_fees = keyset_fees_with_ppk(200); + + let result = split_proofs_for_send( + input_proofs, + &send_amounts, + Amount::from(8000), + Amount::from(1), + &keyset_fees, + false, + false, + ) + .unwrap(); + + // 8192 doesn't match any send amount, goes to swap + assert!(result.proofs_to_send.is_empty()); + assert_eq!(result.proofs_to_swap.len(), 1); + } + + #[test] + fn test_split_many_1sat_proofs() { + let input_proofs = proofs(&[1; 100]); + let send_amounts = amounts(&[32, 16, 2]); + let keyset_fees = keyset_fees_with_ppk(200); + + let result = split_proofs_for_send( + input_proofs, + &send_amounts, + Amount::from(50), + Amount::from(20), // 100 proofs = 20 sat fee @ 200ppk + &keyset_fees, + false, + false, + ) + .unwrap(); + + // No proofs match (no 32, 16, or 2 individual proofs) + assert!(result.proofs_to_send.is_empty()); + assert_eq!(result.proofs_to_swap.len(), 100); + } + + #[test] + fn test_split_all_same_denomination() { + let input_proofs = proofs(&[512; 10]); + let send_amounts = amounts(&[4096, 512, 256, 128, 8]); + let keyset_fees = keyset_fees_with_ppk(200); + + let result = split_proofs_for_send( + input_proofs, + &send_amounts, + Amount::from(4000), + Amount::from(2), + &keyset_fees, + false, + false, + ) + .unwrap(); + + // Only one 512 matches + let send_count = result.proofs_to_send.len(); + assert_eq!(send_count, 1); + assert_eq!(result.proofs_to_swap.len(), 9); + } + + #[test] + fn test_split_alternating_sizes() { + let input_proofs = proofs(&[1024, 64, 1024, 64, 1024, 64, 1024, 64]); + let send_amounts = amounts(&[4096, 256, 128]); + let keyset_fees = keyset_fees_with_ppk(200); + + let result = split_proofs_for_send( + input_proofs, + &send_amounts, + Amount::from(4000), + Amount::from(2), + &keyset_fees, + false, + false, + ) + .unwrap(); + + // No proofs match exactly + assert!(result.proofs_to_send.is_empty()); + assert_eq!(result.proofs_to_swap.len(), 8); + } + + #[test] + fn test_split_power_of_two_boundary() { + let input_proofs = proofs(&[2048, 1024, 512, 256, 128, 64, 32, 16, 8, 4, 2, 1]); + let send_amounts = amounts(&[2048, 1024, 512, 256, 128, 64, 32, 16, 8, 4, 2, 1]); + let keyset_fees = keyset_fees_with_ppk(200); + + let result = split_proofs_for_send( + input_proofs, + &send_amounts, + Amount::from(4095), + Amount::from(3), // 12 proofs = 3 sat fee @ 200ppk + &keyset_fees, + false, + false, + ) + .unwrap(); + + // All proofs match + assert_eq!(result.proofs_to_send.len(), 12); + assert!(result.proofs_to_swap.is_empty()); + } + + #[test] + fn test_split_just_over_boundary() { + // Total = 2048+1024+512+256+128+64+32+16+8+4+2+1+1 = 4096 + // With an extra proof to give some buffer for fees + let input_proofs = proofs(&[2048, 1024, 512, 256, 128, 64, 32, 16, 8, 4, 2, 1, 1, 64]); + // Total now = 4160 + let send_amounts = amounts(&[2048, 1024, 512, 1]); + let keyset_fees = keyset_fees_with_ppk(200); + + let result = split_proofs_for_send( + input_proofs, + &send_amounts, + Amount::from(3585), // 2048+1024+512+1 = 3585 + Amount::from(3), // 14 proofs = 3 sat fee @ 200ppk + &keyset_fees, + false, + false, + ) + .unwrap(); + + // 2048, 1024, 512, 1 match + let send_amounts_result: Vec = result + .proofs_to_send + .iter() + .map(|p| p.amount.into()) + .collect(); + assert!(send_amounts_result.contains(&1) || send_amounts_result.contains(&2048)); + // Some proofs go to swap + assert!(!result.proofs_to_swap.is_empty()); + // Total proofs preserved + assert_eq!( + result.proofs_to_send.len() + result.proofs_to_swap.len(), + 14 + ); + } + + // ======================================================================== + // Regression Tests + // ======================================================================== + + #[test] + fn test_split_regression_insufficient_swap_fee() { + // Scenario where initial swap proofs can't cover their own fee + let input_proofs = proofs(&[4096, 512, 256, 128, 1, 1]); + let send_amounts = amounts(&[4096, 512, 256, 128]); + let keyset_fees = keyset_fees_with_ppk(1000); // 1 sat per proof + + // swap has [1,1] = 2, fee = 2, can produce 0 + let result = split_proofs_for_send( + input_proofs, + &send_amounts, + Amount::from(4992), + Amount::from(1), + &keyset_fees, + false, + false, + ) + .unwrap(); + + // Should have moved proofs to make swap viable + let swap_total: u64 = result + .proofs_to_swap + .iter() + .map(|p| u64::from(p.amount)) + .sum(); + let swap_fee: u64 = result.swap_fee.into(); + // Must be able to produce at least 1 + assert!(swap_total > swap_fee || result.proofs_to_swap.is_empty()); + } + + #[test] + fn test_split_regression_many_small_in_swap() { + // Many small proofs in swap that individually have high fee overhead + let mut input_amounts = vec![4096, 1024]; + input_amounts.extend(vec![1; 20]); + let input_proofs = proofs(&input_amounts); + let send_amounts = amounts(&[4096, 1024]); + let keyset_fees = keyset_fees_with_ppk(500); + + // swap has 20×1 = 20, fee = 10, can produce 10 + // Need to produce something for change + let result = split_proofs_for_send( + input_proofs, + &send_amounts, + Amount::from(5120), + Amount::from(5), + &keyset_fees, + false, + false, + ) + .unwrap(); + + // Should handle this gracefully + assert!(result.proofs_to_send.len() + result.proofs_to_swap.len() == 22); + } +} diff --git a/crates/cdk/src/wallet/swap.rs b/crates/cdk/src/wallet/swap.rs index aa3ca39a2..ace000a40 100644 --- a/crates/cdk/src/wallet/swap.rs +++ b/crates/cdk/src/wallet/swap.rs @@ -93,16 +93,6 @@ impl Wallet { } }; - let send_amount = proofs_to_send.total_amount()?; - - if send_amount.ne(&(amount + pre_swap.fee)) { - tracing::warn!( - "Send amount proofs is {:?} expected {:?}", - send_amount, - amount - ); - } - let send_proofs_info = proofs_to_send .clone() .into_iter() From fea41e48eac068feeab7ee8a929473be4771e3d7 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 26 Nov 2025 23:32:07 +0000 Subject: [PATCH 306/321] chore: add weekly meeting agenda for 2025-11-26 (#1348) Co-authored-by: github-actions[bot] --- meetings/2025-11-26-agenda.md | 68 +++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 meetings/2025-11-26-agenda.md diff --git a/meetings/2025-11-26-agenda.md b/meetings/2025-11-26-agenda.md new file mode 100644 index 000000000..a9ccd8a15 --- /dev/null +++ b/meetings/2025-11-26-agenda.md @@ -0,0 +1,68 @@ +# CDK Development Meeting + +Nov 26 2025 15:00 UTC + +Meeting Link: https://meet.fulmo.org/cdk-dev + +## Merged + +- [#1343](https://github.com/cashubtc/cdk/pull/1343) - fix: use the client id from mint configuration +- [#1341](https://github.com/cashubtc/cdk/pull/1341) - [Backport v0.14.x] fix: check melt quote in ffi +- [#1340](https://github.com/cashubtc/cdk/pull/1340) - fix: check melt quote in ffi +- [#1339](https://github.com/cashubtc/cdk/pull/1339) - [Backport v0.14.x] feat: cdk-ffi get wallets +- [#1335](https://github.com/cashubtc/cdk/pull/1335) - [Backport v0.14.x] feat: multimint_ffi melt with mint +- [#1334](https://github.com/cashubtc/cdk/pull/1334) - feat: remove deprecated paid field +- [#1333](https://github.com/cashubtc/cdk/pull/1333) - feat: cdk-ffi get wallets +- [#1332](https://github.com/cashubtc/cdk/pull/1332) - feat: multimint_ffi melt with mint +- [#1330](https://github.com/cashubtc/cdk/pull/1330) - Batch websocket notification reads in integration tests +- [#1329](https://github.com/cashubtc/cdk/pull/1329) - Remove max_order from keyset database schema +- [#1328](https://github.com/cashubtc/cdk/pull/1328) - [Backport v0.14.x] feat(multi-mint-wallet): add human-readable address melt quote support +- [#1326](https://github.com/cashubtc/cdk/pull/1326) - [Backport v0.14.x] Load mint info +- [#1325](https://github.com/cashubtc/cdk/pull/1325) - feat(multi-mint-wallet): add human-readable address melt quote support +- [#1324](https://github.com/cashubtc/cdk/pull/1324) - [Backport v0.14.x] Cdk ffi psgl +- [#1323](https://github.com/cashubtc/cdk/pull/1323) - Load mint info +- [#1322](https://github.com/cashubtc/cdk/pull/1322) - [Backport v0.14.x] Revert "Prevent database contention in metadata cache load operations… +- [#1321](https://github.com/cashubtc/cdk/pull/1321) - Cdk ffi psgl +- [#1320](https://github.com/cashubtc/cdk/pull/1320) - Revert "Prevent database contention in metadata cache load operations… +- [#1318](https://github.com/cashubtc/cdk/pull/1318) - [Backport v0.14.x] chore: release justfile +- [#1317](https://github.com/cashubtc/cdk/pull/1317) - chore: release justfile +- [#1314](https://github.com/cashubtc/cdk/pull/1314) - Deduplicate mint quote database queries +- [#1312](https://github.com/cashubtc/cdk/pull/1312) - fix: ldk-node account for ln fee +- [#1309](https://github.com/cashubtc/cdk/pull/1309) - fix: remove use of unwrap or default in melt saga +- [#1306](https://github.com/cashubtc/cdk/pull/1306) - fix: add missing comma in get_mint_quotes +- [#1305](https://github.com/cashubtc/cdk/pull/1305) - Weekly Meeting Agenda - 2025-11-19 +- [#1302](https://github.com/cashubtc/cdk/pull/1302) - release v0.14.0 + +## New + +### Issues + +- [#1338](https://github.com/cashubtc/cdk/issues/1338) - Update error codes to spec +- [#1336](https://github.com/cashubtc/cdk/issues/1336) - Expose fn to get quote state updates to bindings +- [#1331](https://github.com/cashubtc/cdk/issues/1331) - DLEQ deserialization error stops token from being decoded at all +- [#1319](https://github.com/cashubtc/cdk/issues/1319) - Error message when insufficant fee is unclear that its a fee issue +- [#1316](https://github.com/cashubtc/cdk/issues/1316) - 🧬 Weekly Mutation Testing Report - 2025-11-21 +- [#1310](https://github.com/cashubtc/cdk/issues/1310) - Consider removeing clone from Mint and Wallet structs +- [#1308](https://github.com/cashubtc/cdk/issues/1308) - PaymentRequest missing from the FFI crate +- [#1307](https://github.com/cashubtc/cdk/issues/1307) - Add transaction tracking to the mint + +### PRs + +- [#1347](https://github.com/cashubtc/cdk/pull/1347) - [Backport v0.14.x] fix: use the client id from mint configuration +- [#1345](https://github.com/cashubtc/cdk/pull/1345) - melt fees +- [#1337](https://github.com/cashubtc/cdk/pull/1337) - Simplify increment_issued_quote implementation +- [#1327](https://github.com/cashubtc/cdk/pull/1327) - Get proofs for tx +- [#1311](https://github.com/cashubtc/cdk/pull/1311) - feat: add operations table + +## Recently Active + +- [#1303](https://github.com/cashubtc/cdk/pull/1303) - New get pending +- [#1251](https://github.com/cashubtc/cdk/pull/1251) - feat: custom axum router +- [#1204](https://github.com/cashubtc/cdk/pull/1204) - Add database transaction trait for cdk wallet +- [#1100](https://github.com/cashubtc/cdk/pull/1100) - NUT-XX: Cairo Spending Conditions implementation +- [#1010](https://github.com/cashubtc/cdk/pull/1010) - adding more LDK configuration settings +- [#1003](https://github.com/cashubtc/cdk/pull/1003) - feat: LDK Lightning KVStore support with PostgreSQL integration + +## Discussion + +- None From 9770577d7d13aa652ab5c159af03bad05bc3ae6a Mon Sep 17 00:00:00 2001 From: tsk Date: Thu, 27 Nov 2025 09:17:14 +0000 Subject: [PATCH 307/321] fix: do not remove melt quote (#1349) --- .../tests/happy_path_mint_wallet.rs | 151 +++++++++++++++++- crates/cdk/src/wallet/melt/melt_bolt11.rs | 10 +- 2 files changed, 157 insertions(+), 4 deletions(-) diff --git a/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs b/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs index ef95cdfcf..af056531c 100644 --- a/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs +++ b/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs @@ -20,9 +20,10 @@ use std::time::Duration; use bip39::Mnemonic; use cashu::{MeltRequest, PreMintSecrets}; use cdk::amount::{Amount, SplitTarget}; +use cdk::mint_url::MintUrl; use cdk::nuts::nut00::ProofsMethods; use cdk::nuts::{CurrencyUnit, MeltQuoteState, NotificationPayload, State}; -use cdk::wallet::{HttpClient, MintConnector, Wallet}; +use cdk::wallet::{HttpClient, MintConnector, MultiMintWallet, Wallet}; use cdk_integration_tests::{create_invoice_for_env, get_mint_url_from_env, pay_if_regtest}; use cdk_sqlite::wallet::memory; use futures::{SinkExt, StreamExt}; @@ -356,6 +357,154 @@ async fn test_restore() { } } +/// Tests that the melt quote status can be checked after a melt has completed +/// +/// This test verifies: +/// 1. Mint tokens +/// 2. Create a melt quote and execute the melt +/// 3. Check the melt quote status via the wallet +/// 4. Verify the quote is in the Paid state +/// +/// This ensures the mint correctly reports the melt quote status after completion. +#[tokio::test(flavor = "multi_thread", worker_threads = 1)] +async fn test_melt_quote_status_after_melt() { + let wallet = Wallet::new( + &get_mint_url_from_env(), + CurrencyUnit::Sat, + Arc::new(memory::empty().await.unwrap()), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), + None, + ) + .expect("failed to create new wallet"); + + let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); + + let invoice = Bolt11Invoice::from_str(&mint_quote.request).unwrap(); + pay_if_regtest(&get_test_temp_dir(), &invoice) + .await + .unwrap(); + + let proofs = wallet + .wait_and_mint_quote( + mint_quote.clone(), + SplitTarget::default(), + None, + tokio::time::Duration::from_secs(60), + ) + .await + .expect("mint failed"); + + let mint_amount = proofs.total_amount().unwrap(); + assert_eq!(mint_amount, 100.into()); + + let invoice = create_invoice_for_env(Some(50)).await.unwrap(); + + let melt_quote = wallet.melt_quote(invoice, None).await.unwrap(); + + let melt_response = wallet.melt(&melt_quote.id).await.unwrap(); + assert_eq!(melt_response.state, MeltQuoteState::Paid); + + let quote_status = wallet.melt_quote_status(&melt_quote.id).await.unwrap(); + assert_eq!( + quote_status.state, + MeltQuoteState::Paid, + "Melt quote should be in Paid state after successful melt" + ); + + let db_quote = wallet + .localstore + .get_melt_quote(&melt_quote.id) + .await + .unwrap() + .unwrap(); + + assert_eq!( + db_quote.state, + MeltQuoteState::Paid, + "Melt quote should be in Paid state after successful melt" + ); +} + +/// Tests that the melt quote status can be checked via MultiMintWallet after a melt has completed +/// +/// This test verifies the same flow as test_melt_quote_status_after_melt but using +/// the MultiMintWallet abstraction: +/// 1. Create a MultiMintWallet and add a mint +/// 2. Mint tokens via the multi mint wallet +/// 3. Create a melt quote and execute the melt +/// 4. Check the melt quote status via check_melt_quote +/// 5. Verify the quote is in the Paid state +#[tokio::test(flavor = "multi_thread", worker_threads = 1)] +async fn test_melt_quote_status_after_melt_multi_mint_wallet() { + let seed = Mnemonic::generate(12).unwrap().to_seed_normalized(""); + let localstore = Arc::new(memory::empty().await.unwrap()); + + let multi_mint_wallet = MultiMintWallet::new(localstore.clone(), seed, CurrencyUnit::Sat) + .await + .expect("failed to create multi mint wallet"); + + let mint_url = MintUrl::from_str(&get_mint_url_from_env()).expect("invalid mint url"); + multi_mint_wallet + .add_mint(mint_url.clone()) + .await + .expect("failed to add mint"); + + let mint_quote = multi_mint_wallet + .mint_quote(&mint_url, 100.into(), None) + .await + .unwrap(); + + let invoice = Bolt11Invoice::from_str(&mint_quote.request).unwrap(); + pay_if_regtest(&get_test_temp_dir(), &invoice) + .await + .unwrap(); + + let _proofs = multi_mint_wallet + .wait_for_mint_quote(&mint_url, &mint_quote.id, SplitTarget::default(), None, 60) + .await + .expect("mint failed"); + + let balance = multi_mint_wallet.total_balance().await.unwrap(); + assert_eq!(balance, 100.into()); + + let invoice = create_invoice_for_env(Some(50)).await.unwrap(); + + let melt_quote = multi_mint_wallet + .melt_quote(&mint_url, invoice, None) + .await + .unwrap(); + + let melt_response = multi_mint_wallet + .melt_with_mint(&mint_url, &melt_quote.id) + .await + .unwrap(); + assert_eq!(melt_response.state, MeltQuoteState::Paid); + + let quote_status = multi_mint_wallet + .check_melt_quote(&mint_url, &melt_quote.id) + .await + .unwrap(); + assert_eq!( + quote_status.state, + MeltQuoteState::Paid, + "Melt quote should be in Paid state after successful melt (via MultiMintWallet)" + ); + + use cdk_common::database::WalletDatabase; + + let db_quote = localstore + .get_melt_quote(&melt_quote.id) + .await + .unwrap() + .unwrap(); + + assert_eq!( + db_quote.state, + MeltQuoteState::Paid, + "Melt quote should be in Paid state after successful melt" + ); +} + /// Tests that change outputs in a melt quote are correctly handled /// /// This test verifies the following workflow: diff --git a/crates/cdk/src/wallet/melt/melt_bolt11.rs b/crates/cdk/src/wallet/melt/melt_bolt11.rs index 202987263..13ae8b3e2 100644 --- a/crates/cdk/src/wallet/melt/melt_bolt11.rs +++ b/crates/cdk/src/wallet/melt/melt_bolt11.rs @@ -138,7 +138,7 @@ impl Wallet { proofs: Proofs, metadata: HashMap, ) -> Result { - let quote_info = self + let mut quote_info = self .localstore .get_melt_quote(quote_id) .await? @@ -273,7 +273,11 @@ impl Wallet { None => Vec::new(), }; - self.localstore.remove_melt_quote("e_info.id).await?; + quote_info.state = cdk_common::MeltQuoteState::Paid; + + let payment_request = quote_info.request.clone(); + + self.localstore.add_melt_quote(quote_info).await?; let deleted_ys = proofs.ys()?; self.localstore @@ -293,7 +297,7 @@ impl Wallet { memo: None, metadata, quote_id: Some(quote_id.to_string()), - payment_request: Some(quote_info.request), + payment_request: Some(payment_request), payment_proof: payment_preimage, }) .await?; From b1aa1da3866e484520309ee5fbb217ec3d749ff4 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Thu, 27 Nov 2025 20:52:19 +0000 Subject: [PATCH 308/321] chore: example use tsk mint --- crates/cdk/examples/p2pk.rs | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/crates/cdk/examples/p2pk.rs b/crates/cdk/examples/p2pk.rs index 8e5a1985e..702a1c927 100644 --- a/crates/cdk/examples/p2pk.rs +++ b/crates/cdk/examples/p2pk.rs @@ -27,8 +27,7 @@ async fn main() -> Result<(), Error> { let seed = random::<[u8; 64]>(); // Define the mint URL and currency unit - // let mint_url = "https://fake.thesimplekid.dev"; - let mint_url = "https://testnut.cashu.space"; + let mint_url = "https://fake.thesimplekid.dev"; let unit = CurrencyUnit::Sat; let amount = Amount::from(100); From 6af8636335b8a1a1b112b3faf5e231b0014bca95 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Thu, 27 Nov 2025 21:05:27 +0000 Subject: [PATCH 309/321] chore: typos --- meetings/2025-11-26-agenda.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/meetings/2025-11-26-agenda.md b/meetings/2025-11-26-agenda.md index a9ccd8a15..f92b7127b 100644 --- a/meetings/2025-11-26-agenda.md +++ b/meetings/2025-11-26-agenda.md @@ -40,9 +40,9 @@ Meeting Link: https://meet.fulmo.org/cdk-dev - [#1338](https://github.com/cashubtc/cdk/issues/1338) - Update error codes to spec - [#1336](https://github.com/cashubtc/cdk/issues/1336) - Expose fn to get quote state updates to bindings - [#1331](https://github.com/cashubtc/cdk/issues/1331) - DLEQ deserialization error stops token from being decoded at all -- [#1319](https://github.com/cashubtc/cdk/issues/1319) - Error message when insufficant fee is unclear that its a fee issue +- [#1319](https://github.com/cashubtc/cdk/issues/1319) - Error message when insufficient fee is unclear that its a fee issue - [#1316](https://github.com/cashubtc/cdk/issues/1316) - 🧬 Weekly Mutation Testing Report - 2025-11-21 -- [#1310](https://github.com/cashubtc/cdk/issues/1310) - Consider removeing clone from Mint and Wallet structs +- [#1310](https://github.com/cashubtc/cdk/issues/1310) - Consider removing clone from Mint and Wallet structs - [#1308](https://github.com/cashubtc/cdk/issues/1308) - PaymentRequest missing from the FFI crate - [#1307](https://github.com/cashubtc/cdk/issues/1307) - Add transaction tracking to the mint From 6530054d98e041d159dda99b4f29b0680bbf8527 Mon Sep 17 00:00:00 2001 From: tsk Date: Fri, 28 Nov 2025 09:16:46 +0000 Subject: [PATCH 310/321] Get proofs for wallet tx (#1327) * feat(cdk): add get_proofs_for_transaction method to multi-mint wallet Enables retrieving all proofs associated with a transaction ID across multiple mint wallets. The method searches all wallets to locate the transaction and returns its proofs from the correct wallet. --- crates/cdk-common/src/database/wallet.rs | 2 + crates/cdk-ffi/src/database.rs | 45 +++++++++++ crates/cdk-ffi/src/multi_mint_wallet.rs | 24 ++++++ crates/cdk-ffi/src/postgres.rs | 15 ++++ crates/cdk-ffi/src/sqlite.rs | 15 ++++ crates/cdk-ffi/src/wallet.rs | 13 ++++ crates/cdk-redb/src/wallet/mod.rs | 22 ++++++ crates/cdk-sql-common/src/wallet/mod.rs | 35 +++++++++ crates/cdk-sqlite/src/wallet/mod.rs | 89 ++++++++++++++++++++++ crates/cdk/src/wallet/multi_mint_wallet.rs | 46 ++++++++++- crates/cdk/src/wallet/transactions.rs | 23 ++++++ 11 files changed, 328 insertions(+), 1 deletion(-) diff --git a/crates/cdk-common/src/database/wallet.rs b/crates/cdk-common/src/database/wallet.rs index 8889b4710..af4f25dce 100644 --- a/crates/cdk-common/src/database/wallet.rs +++ b/crates/cdk-common/src/database/wallet.rs @@ -96,6 +96,8 @@ pub trait Database: Debug { state: Option>, spending_conditions: Option>, ) -> Result, Self::Err>; + /// Get proofs by Y values + async fn get_proofs_by_ys(&self, ys: Vec) -> Result, Self::Err>; /// Get balance async fn get_balance( &self, diff --git a/crates/cdk-ffi/src/database.rs b/crates/cdk-ffi/src/database.rs index d78ce9c76..ec1dadbd4 100644 --- a/crates/cdk-ffi/src/database.rs +++ b/crates/cdk-ffi/src/database.rs @@ -110,6 +110,9 @@ pub trait WalletDatabase: Send + Sync { spending_conditions: Option>, ) -> Result, FfiError>; + /// Get proofs by Y values + async fn get_proofs_by_ys(&self, ys: Vec) -> Result, FfiError>; + /// Get balance efficiently using SQL aggregation async fn get_balance( &self, @@ -476,6 +479,48 @@ impl CdkWalletDatabase for WalletDatabaseBridge { cdk_result } + async fn get_proofs_by_ys( + &self, + ys: Vec, + ) -> Result, Self::Err> { + let ffi_ys: Vec = ys.into_iter().map(Into::into).collect(); + + let result = self + .ffi_db + .get_proofs_by_ys(ffi_ys) + .await + .map_err(|e| cdk::cdk_database::Error::Database(e.to_string().into()))?; + + // Convert back to CDK ProofInfo + let cdk_result: Result, cdk::cdk_database::Error> = result + .into_iter() + .map(|info| { + Ok(cdk::types::ProofInfo { + proof: info.proof.try_into().map_err(|e: FfiError| { + cdk::cdk_database::Error::Database(e.to_string().into()) + })?, + y: info.y.try_into().map_err(|e: FfiError| { + cdk::cdk_database::Error::Database(e.to_string().into()) + })?, + mint_url: info.mint_url.try_into().map_err(|e: FfiError| { + cdk::cdk_database::Error::Database(e.to_string().into()) + })?, + state: info.state.into(), + spending_condition: info + .spending_condition + .map(|sc| sc.try_into()) + .transpose() + .map_err(|e: FfiError| { + cdk::cdk_database::Error::Database(e.to_string().into()) + })?, + unit: info.unit.into(), + }) + }) + .collect(); + + cdk_result + } + async fn get_balance( &self, mint_url: Option, diff --git a/crates/cdk-ffi/src/multi_mint_wallet.rs b/crates/cdk-ffi/src/multi_mint_wallet.rs index 3ed6186ab..b752a6edf 100644 --- a/crates/cdk-ffi/src/multi_mint_wallet.rs +++ b/crates/cdk-ffi/src/multi_mint_wallet.rs @@ -508,6 +508,30 @@ impl MultiMintWallet { Ok(transactions.into_iter().map(Into::into).collect()) } + /// Get proofs for a transaction by transaction ID + /// + /// This retrieves all proofs associated with a transaction. If `mint_url` is provided, + /// it will only check that specific mint's wallet. Otherwise, it searches across all + /// wallets to find which mint the transaction belongs to. + /// + /// # Arguments + /// + /// * `id` - The transaction ID + /// * `mint_url` - Optional mint URL to check directly, avoiding iteration over all wallets + pub async fn get_proofs_for_transaction( + &self, + id: TransactionId, + mint_url: Option, + ) -> Result, FfiError> { + let cdk_id = id.try_into()?; + let cdk_mint_url = mint_url.map(|url| url.try_into()).transpose()?; + let proofs = self + .inner + .get_proofs_for_transaction(cdk_id, cdk_mint_url) + .await?; + Ok(proofs.into_iter().map(Into::into).collect()) + } + /// Check all mint quotes and mint if paid pub async fn check_all_mint_quotes( &self, diff --git a/crates/cdk-ffi/src/postgres.rs b/crates/cdk-ffi/src/postgres.rs index 975bd011d..80ccf8fd4 100644 --- a/crates/cdk-ffi/src/postgres.rs +++ b/crates/cdk-ffi/src/postgres.rs @@ -289,6 +289,21 @@ impl WalletDatabase for WalletPostgresDatabase { Ok(result.into_iter().map(Into::into).collect()) } + async fn get_proofs_by_ys(&self, ys: Vec) -> Result, FfiError> { + let cdk_ys: Vec = ys + .into_iter() + .map(|y| y.try_into()) + .collect::, FfiError>>()?; + + let result = self + .inner + .get_proofs_by_ys(cdk_ys) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + + Ok(result.into_iter().map(Into::into).collect()) + } + async fn get_balance( &self, mint_url: Option, diff --git a/crates/cdk-ffi/src/sqlite.rs b/crates/cdk-ffi/src/sqlite.rs index 945d0df31..566783f83 100644 --- a/crates/cdk-ffi/src/sqlite.rs +++ b/crates/cdk-ffi/src/sqlite.rs @@ -324,6 +324,21 @@ impl WalletDatabase for WalletSqliteDatabase { Ok(result.into_iter().map(Into::into).collect()) } + async fn get_proofs_by_ys(&self, ys: Vec) -> Result, FfiError> { + let cdk_ys: Vec = ys + .into_iter() + .map(|y| y.try_into()) + .collect::, FfiError>>()?; + + let result = self + .inner + .get_proofs_by_ys(cdk_ys) + .await + .map_err(|e| FfiError::Database { msg: e.to_string() })?; + + Ok(result.into_iter().map(Into::into).collect()) + } + async fn get_balance( &self, mint_url: Option, diff --git a/crates/cdk-ffi/src/wallet.rs b/crates/cdk-ffi/src/wallet.rs index f9fecadc5..4d9afb647 100644 --- a/crates/cdk-ffi/src/wallet.rs +++ b/crates/cdk-ffi/src/wallet.rs @@ -367,6 +367,19 @@ impl Wallet { Ok(transaction.map(Into::into)) } + /// Get proofs for a transaction by transaction ID + /// + /// This retrieves all proofs associated with a transaction by looking up + /// the transaction's Y values and fetching the corresponding proofs. + pub async fn get_proofs_for_transaction( + &self, + id: TransactionId, + ) -> Result, FfiError> { + let cdk_id = id.try_into()?; + let proofs = self.inner.get_proofs_for_transaction(cdk_id).await?; + Ok(proofs.into_iter().map(Into::into).collect()) + } + /// Revert a transaction pub async fn revert_transaction(&self, id: TransactionId) -> Result<(), FfiError> { let cdk_id = id.try_into()?; diff --git a/crates/cdk-redb/src/wallet/mod.rs b/crates/cdk-redb/src/wallet/mod.rs index 40b7eb1f9..70b6af160 100644 --- a/crates/cdk-redb/src/wallet/mod.rs +++ b/crates/cdk-redb/src/wallet/mod.rs @@ -741,6 +741,28 @@ impl WalletDatabase for WalletRedbDatabase { Ok(proofs) } + #[instrument(skip(self, ys))] + async fn get_proofs_by_ys(&self, ys: Vec) -> Result, Self::Err> { + if ys.is_empty() { + return Ok(Vec::new()); + } + + let read_txn = self.db.begin_read().map_err(Error::from)?; + let table = read_txn.open_table(PROOFS_TABLE).map_err(Error::from)?; + + let mut proofs = Vec::new(); + + for y in ys { + if let Some(proof) = table.get(y.to_bytes().as_slice()).map_err(Error::from)? { + let proof_info = + serde_json::from_str::(proof.value()).map_err(Error::from)?; + proofs.push(proof_info); + } + } + + Ok(proofs) + } + async fn get_balance( &self, mint_url: Option, diff --git a/crates/cdk-sql-common/src/wallet/mod.rs b/crates/cdk-sql-common/src/wallet/mod.rs index 1d2af6f8a..b894713a8 100644 --- a/crates/cdk-sql-common/src/wallet/mod.rs +++ b/crates/cdk-sql-common/src/wallet/mod.rs @@ -837,6 +837,41 @@ ON CONFLICT(id) DO UPDATE SET .collect::>()) } + #[instrument(skip(self, ys))] + async fn get_proofs_by_ys(&self, ys: Vec) -> Result, Self::Err> { + if ys.is_empty() { + return Ok(Vec::new()); + } + + let conn = self.pool.get().map_err(|e| Error::Database(Box::new(e)))?; + Ok(query( + r#" + SELECT + amount, + unit, + keyset_id, + secret, + c, + witness, + dleq_e, + dleq_s, + dleq_r, + y, + mint_url, + state, + spending_condition + FROM proof + WHERE y IN (:ys) + "#, + )? + .bind_vec("ys", ys.iter().map(|y| y.to_bytes().to_vec()).collect()) + .fetch_all(&*conn) + .await? + .into_iter() + .filter_map(|row| sql_row_to_proof_info(row).ok()) + .collect::>()) + } + async fn get_balance( &self, mint_url: Option, diff --git a/crates/cdk-sqlite/src/wallet/mod.rs b/crates/cdk-sqlite/src/wallet/mod.rs index add3937ef..183e5170c 100644 --- a/crates/cdk-sqlite/src/wallet/mod.rs +++ b/crates/cdk-sqlite/src/wallet/mod.rs @@ -179,4 +179,93 @@ mod tests { assert_eq!(retrieved.amount_paid, Amount::from(0)); } } + + #[tokio::test] + async fn test_get_proofs_by_ys() { + use cdk_common::common::ProofInfo; + use cdk_common::mint_url::MintUrl; + use cdk_common::nuts::{CurrencyUnit, Id, Proof, SecretKey}; + use cdk_common::Amount; + + // Create a temporary database + let path = std::env::temp_dir().to_path_buf().join(format!( + "cdk-test-proofs-by-ys-{}.sqlite", + uuid::Uuid::new_v4() + )); + + #[cfg(feature = "sqlcipher")] + let db = WalletSqliteDatabase::new((path, "password".to_string())) + .await + .unwrap(); + + #[cfg(not(feature = "sqlcipher"))] + let db = WalletSqliteDatabase::new(path).await.unwrap(); + + // Create multiple proofs + let keyset_id = Id::from_str("00deadbeef123456").unwrap(); + let mint_url = MintUrl::from_str("https://example.com").unwrap(); + + let mut proof_infos = vec![]; + let mut expected_ys = vec![]; + + // Generate valid public keys using SecretKey + for _i in 0..5 { + let secret = Secret::generate(); + + // Generate a valid public key from a secret key + let secret_key = SecretKey::generate(); + let c = secret_key.public_key(); + + let proof = Proof::new(Amount::from(64), keyset_id, secret, c); + + let proof_info = + ProofInfo::new(proof, mint_url.clone(), State::Unspent, CurrencyUnit::Sat).unwrap(); + + expected_ys.push(proof_info.y); + proof_infos.push(proof_info); + } + + // Store all proofs in the database + db.update_proofs(proof_infos.clone(), vec![]).await.unwrap(); + + // Test 1: Retrieve all proofs by their Y values + let retrieved_proofs = db.get_proofs_by_ys(expected_ys.clone()).await.unwrap(); + + assert_eq!(retrieved_proofs.len(), 5); + for retrieved_proof in &retrieved_proofs { + assert!(expected_ys.contains(&retrieved_proof.y)); + } + + // Test 2: Retrieve subset of proofs (first 3) + let subset_ys = expected_ys[0..3].to_vec(); + let subset_proofs = db.get_proofs_by_ys(subset_ys.clone()).await.unwrap(); + + assert_eq!(subset_proofs.len(), 3); + for retrieved_proof in &subset_proofs { + assert!(subset_ys.contains(&retrieved_proof.y)); + } + + // Test 3: Retrieve with non-existent Y values + let non_existent_secret_key = SecretKey::generate(); + let non_existent_y = non_existent_secret_key.public_key(); + let mixed_ys = vec![expected_ys[0], non_existent_y, expected_ys[1]]; + let mixed_proofs = db.get_proofs_by_ys(mixed_ys).await.unwrap(); + + // Should only return the 2 that exist + assert_eq!(mixed_proofs.len(), 2); + + // Test 4: Empty input returns empty result + let empty_result = db.get_proofs_by_ys(vec![]).await.unwrap(); + assert_eq!(empty_result.len(), 0); + + // Test 5: Verify retrieved proof data matches original + let single_y = vec![expected_ys[2]]; + let single_proof = db.get_proofs_by_ys(single_y).await.unwrap(); + + assert_eq!(single_proof.len(), 1); + assert_eq!(single_proof[0].y, proof_infos[2].y); + assert_eq!(single_proof[0].proof.amount, proof_infos[2].proof.amount); + assert_eq!(single_proof[0].mint_url, proof_infos[2].mint_url); + assert_eq!(single_proof[0].state, proof_infos[2].state); + } } diff --git a/crates/cdk/src/wallet/multi_mint_wallet.rs b/crates/cdk/src/wallet/multi_mint_wallet.rs index 6e3f6eedc..c4caeb30e 100644 --- a/crates/cdk/src/wallet/multi_mint_wallet.rs +++ b/crates/cdk/src/wallet/multi_mint_wallet.rs @@ -12,7 +12,7 @@ use anyhow::Result; use cdk_common::database; use cdk_common::database::WalletDatabase; use cdk_common::task::spawn; -use cdk_common::wallet::{MeltQuote, Transaction, TransactionDirection}; +use cdk_common::wallet::{MeltQuote, Transaction, TransactionDirection, TransactionId}; use tokio::sync::RwLock; use tracing::instrument; use zeroize::Zeroize; @@ -563,6 +563,50 @@ impl MultiMintWallet { Ok(transactions) } + /// Get proofs for a transaction by transaction ID + /// + /// This retrieves all proofs associated with a transaction. If `mint_url` is provided, + /// it will only check that specific mint's wallet. Otherwise, it searches across all + /// wallets to find which mint the transaction belongs to. + /// + /// # Arguments + /// + /// * `id` - The transaction ID + /// * `mint_url` - Optional mint URL to check directly, avoiding iteration over all wallets + #[instrument(skip(self))] + pub async fn get_proofs_for_transaction( + &self, + id: TransactionId, + mint_url: Option, + ) -> Result { + let wallets = self.wallets.read().await; + + // If mint_url is provided, try that wallet directly + if let Some(mint_url) = mint_url { + if let Some(wallet) = wallets.get(&mint_url) { + // Verify the transaction exists in this wallet + if wallet.get_transaction(id).await?.is_some() { + return wallet.get_proofs_for_transaction(id).await; + } + } + // Transaction not found in specified mint + return Err(Error::TransactionNotFound); + } + + // No mint_url provided, search across all wallets + for (mint_url, wallet) in wallets.iter() { + if let Some(transaction) = wallet.get_transaction(id).await? { + // Verify the transaction belongs to this wallet's mint + if &transaction.mint_url == mint_url { + return wallet.get_proofs_for_transaction(id).await; + } + } + } + + // Transaction not found in any wallet + Err(Error::TransactionNotFound) + } + /// Get total balance across all wallets (since all wallets use the same currency unit) #[instrument(skip(self))] pub async fn total_balance(&self) -> Result { diff --git a/crates/cdk/src/wallet/transactions.rs b/crates/cdk/src/wallet/transactions.rs index 3a0f618b1..f609c01cf 100644 --- a/crates/cdk/src/wallet/transactions.rs +++ b/crates/cdk/src/wallet/transactions.rs @@ -1,4 +1,5 @@ use cdk_common::wallet::{Transaction, TransactionDirection, TransactionId}; +use cdk_common::Proofs; use crate::{Error, Wallet}; @@ -29,6 +30,28 @@ impl Wallet { Ok(transaction) } + /// Get proofs for a transaction by transaction ID + /// + /// This retrieves all proofs associated with a transaction by looking up + /// the transaction's Y values and fetching the corresponding proofs. + pub async fn get_proofs_for_transaction(&self, id: TransactionId) -> Result { + let transaction = self + .localstore + .get_transaction(id) + .await? + .ok_or(Error::TransactionNotFound)?; + + let proofs = self + .localstore + .get_proofs_by_ys(transaction.ys) + .await? + .into_iter() + .map(|p| p.proof) + .collect(); + + Ok(proofs) + } + /// Revert a transaction pub async fn revert_transaction(&self, id: TransactionId) -> Result<(), Error> { let tx = self From 90b0b907a45db26a097e7fc4bda65eb5ca50f9ba Mon Sep 17 00:00:00 2001 From: tsk Date: Sun, 30 Nov 2025 21:06:06 +0000 Subject: [PATCH 311/321] Melt external (#1357) Allows melting proofs that are not stored in the wallet's database, enabling external proof handling similar to receive_proofs. --- crates/cdk-ffi/src/multi_mint_wallet.rs | 33 +++++++ crates/cdk-ffi/src/wallet.rs | 23 +++++ .../tests/fake_wallet.rs | 89 +++++++++++++++++++ crates/cdk/src/wallet/melt/melt_bolt11.rs | 11 ++- crates/cdk/src/wallet/multi_mint_wallet.rs | 30 +++++++ 5 files changed, 182 insertions(+), 4 deletions(-) diff --git a/crates/cdk-ffi/src/multi_mint_wallet.rs b/crates/cdk-ffi/src/multi_mint_wallet.rs index b752a6edf..b2f34ebd2 100644 --- a/crates/cdk-ffi/src/multi_mint_wallet.rs +++ b/crates/cdk-ffi/src/multi_mint_wallet.rs @@ -442,6 +442,39 @@ impl MultiMintWallet { Ok(melted.into()) } + /// Melt specific proofs from a specific mint + /// + /// This method allows melting proofs that may not be in the wallet's database, + /// similar to how `receive_proofs` handles external proofs. The proofs will be + /// added to the database and used for the melt operation. + /// + /// # Arguments + /// + /// * `mint_url` - The mint to use for the melt operation + /// * `quote_id` - The melt quote ID (obtained from `melt_quote`) + /// * `proofs` - The proofs to melt (can be external proofs not in the wallet's database) + /// + /// # Returns + /// + /// A `Melted` result containing the payment details and any change proofs + pub async fn melt_proofs( + &self, + mint_url: MintUrl, + quote_id: String, + proofs: Proofs, + ) -> Result { + let cdk_mint_url: cdk::mint_url::MintUrl = mint_url.try_into()?; + let cdk_proofs: Result, _> = + proofs.into_iter().map(|p| p.try_into()).collect(); + let cdk_proofs = cdk_proofs?; + + let melted = self + .inner + .melt_proofs(&cdk_mint_url, "e_id, cdk_proofs) + .await?; + Ok(melted.into()) + } + /// Check melt quote status pub async fn check_melt_quote( &self, diff --git a/crates/cdk-ffi/src/wallet.rs b/crates/cdk-ffi/src/wallet.rs index 4d9afb647..e2549d8b2 100644 --- a/crates/cdk-ffi/src/wallet.rs +++ b/crates/cdk-ffi/src/wallet.rs @@ -225,6 +225,29 @@ impl Wallet { Ok(melted.into()) } + /// Melt specific proofs + /// + /// This method allows melting proofs that may not be in the wallet's database, + /// similar to how `receive_proofs` handles external proofs. The proofs will be + /// added to the database and used for the melt operation. + /// + /// # Arguments + /// + /// * `quote_id` - The melt quote ID (obtained from `melt_quote`) + /// * `proofs` - The proofs to melt (can be external proofs not in the wallet's database) + /// + /// # Returns + /// + /// A `Melted` result containing the payment details and any change proofs + pub async fn melt_proofs(&self, quote_id: String, proofs: Proofs) -> Result { + let cdk_proofs: Result, _> = + proofs.into_iter().map(|p| p.try_into()).collect(); + let cdk_proofs = cdk_proofs?; + + let melted = self.inner.melt_proofs("e_id, cdk_proofs).await?; + Ok(melted.into()) + } + /// Get a quote for a bolt12 mint pub async fn mint_bolt12_quote( &self, diff --git a/crates/cdk-integration-tests/tests/fake_wallet.rs b/crates/cdk-integration-tests/tests/fake_wallet.rs index 1b768ff69..b4d515322 100644 --- a/crates/cdk-integration-tests/tests/fake_wallet.rs +++ b/crates/cdk-integration-tests/tests/fake_wallet.rs @@ -1541,3 +1541,92 @@ async fn test_wallet_proof_recovery_after_failed_swap() { "Proofs should have been swapped to new ones" ); } + +/// Tests that melt_proofs works correctly with proofs that are not already in the wallet's database. +/// This is similar to the receive flow where proofs come from an external source. +/// +/// Flow: +/// 1. Wallet A mints proofs (proofs ARE in Wallet A's database) +/// 2. Wallet B creates a melt quote +/// 3. Wallet B calls melt_proofs with proofs from Wallet A (proofs are NOT in Wallet B's database) +#[tokio::test(flavor = "multi_thread", worker_threads = 1)] +async fn test_melt_proofs_external() { + // Create sender wallet (Wallet A) and mint some proofs + let wallet_sender = Wallet::new( + MINT_URL, + CurrencyUnit::Sat, + Arc::new(memory::empty().await.unwrap()), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), + None, + ) + .expect("failed to create sender wallet"); + + let mint_quote = wallet_sender.mint_quote(100.into(), None).await.unwrap(); + + let mut proof_streams = + wallet_sender.proof_stream(mint_quote.clone(), SplitTarget::default(), None); + + let proofs = proof_streams + .next() + .await + .expect("payment") + .expect("no error"); + + assert_eq!(proofs.total_amount().unwrap(), Amount::from(100)); + + // Create receiver/melter wallet (Wallet B) with a separate database + // These proofs are NOT in Wallet B's database + let wallet_melter = Wallet::new( + MINT_URL, + CurrencyUnit::Sat, + Arc::new(memory::empty().await.unwrap()), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), + None, + ) + .expect("failed to create melter wallet"); + + // Verify proofs are not in the melter wallet's database + let melter_proofs = wallet_melter.get_unspent_proofs().await.unwrap(); + assert!( + melter_proofs.is_empty(), + "Melter wallet should have no proofs initially" + ); + + // Create a fake invoice for melting + let fake_description = FakeInvoiceDescription::default(); + let invoice = create_fake_invoice(9000, serde_json::to_string(&fake_description).unwrap()); + + // Wallet B creates a melt quote + let melt_quote = wallet_melter + .melt_quote(invoice.to_string(), None) + .await + .unwrap(); + + // Wallet B calls melt_proofs with external proofs (from Wallet A) + // These proofs are NOT in wallet_melter's database + let melted = wallet_melter + .melt_proofs(&melt_quote.id, proofs.clone()) + .await + .unwrap(); + + // Verify the melt succeeded + assert_eq!(melted.amount, Amount::from(9)); + assert_eq!(melted.fee_paid, 1.into()); + + // Verify change was returned (100 input - 9 melt amount = 91 change, minus fee reserve) + assert!(melted.change.is_some()); + let change_amount = melted.change.unwrap().total_amount().unwrap(); + assert!(change_amount > Amount::ZERO, "Should have received change"); + + // Verify the melter wallet now has the change proofs + let melter_balance = wallet_melter.total_balance().await.unwrap(); + assert_eq!(melter_balance, change_amount); + + // Verify a transaction was recorded + let transactions = wallet_melter + .list_transactions(Some(TransactionDirection::Outgoing)) + .await + .unwrap(); + assert_eq!(transactions.len(), 1); + assert_eq!(transactions[0].amount, Amount::from(9)); +} diff --git a/crates/cdk/src/wallet/melt/melt_bolt11.rs b/crates/cdk/src/wallet/melt/melt_bolt11.rs index 13ae8b3e2..79b7c527b 100644 --- a/crates/cdk/src/wallet/melt/melt_bolt11.rs +++ b/crates/cdk/src/wallet/melt/melt_bolt11.rs @@ -154,10 +154,13 @@ impl Wallet { return Err(Error::InsufficientFunds); } - let ys = proofs.ys()?; - self.localstore - .update_proofs_state(ys, State::Pending) - .await?; + // Since the proofs may be external (not in our database), add them first + let proofs_info = proofs + .clone() + .into_iter() + .map(|p| ProofInfo::new(p, self.mint_url.clone(), State::Pending, self.unit.clone())) + .collect::, _>>()?; + self.localstore.update_proofs(proofs_info, vec![]).await?; let active_keyset_id = self.fetch_active_keyset().await?.id; diff --git a/crates/cdk/src/wallet/multi_mint_wallet.rs b/crates/cdk/src/wallet/multi_mint_wallet.rs index c4caeb30e..bd7547989 100644 --- a/crates/cdk/src/wallet/multi_mint_wallet.rs +++ b/crates/cdk/src/wallet/multi_mint_wallet.rs @@ -1343,6 +1343,36 @@ impl MultiMintWallet { wallet.melt(quote_id).await } + /// Melt specific proofs from a specific mint using a quote ID + /// + /// This method allows melting proofs that may not be in the wallet's database, + /// similar to how `receive_proofs` handles external proofs. The proofs will be + /// added to the database and used for the melt operation. + /// + /// # Arguments + /// + /// * `mint_url` - The mint to use for the melt operation + /// * `quote_id` - The melt quote ID (obtained from `melt_quote`) + /// * `proofs` - The proofs to melt (can be external proofs not in the wallet's database) + /// + /// # Returns + /// + /// A `Melted` result containing the payment details and any change proofs + #[instrument(skip(self, proofs))] + pub async fn melt_proofs( + &self, + mint_url: &MintUrl, + quote_id: &str, + proofs: Proofs, + ) -> Result { + let wallets = self.wallets.read().await; + let wallet = wallets.get(mint_url).ok_or(Error::UnknownMint { + mint_url: mint_url.to_string(), + })?; + + wallet.melt_proofs(quote_id, proofs).await + } + /// Check a specific melt quote status #[instrument(skip(self))] pub async fn check_melt_quote( From 977347cecb8b3a1366f4b69294e555579ad8ea2b Mon Sep 17 00:00:00 2001 From: tsk Date: Mon, 1 Dec 2025 11:02:00 +0000 Subject: [PATCH 312/321] feat: kill mutants nov 30 (#1359) --- .cargo/mutants.toml | 4 ++ crates/cashu/src/amount.rs | 84 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 88 insertions(+) diff --git a/.cargo/mutants.toml b/.cargo/mutants.toml index 3e0574508..c2a1160e7 100644 --- a/.cargo/mutants.toml +++ b/.cargo/mutants.toml @@ -36,4 +36,8 @@ exclude_re = [ # amount.rs:331 - Sub returning Default/0 causes infinite loops "crates/cashu/src/amount.rs:331:.*replace.*sub.*with Default", + + # Trivial getters - not worth testing + "FeeAndAmounts::fee", + "FeeAndAmounts::amounts", ] diff --git a/crates/cashu/src/amount.rs b/crates/cashu/src/amount.rs index d2497f414..e6fceaaf4 100644 --- a/crates/cashu/src/amount.rs +++ b/crates/cashu/src/amount.rs @@ -1098,4 +1098,88 @@ mod tests { let result = amount.convert_unit(&CurrencyUnit::Sat, &CurrencyUnit::Eur); assert!(result.is_err()); } + + /// Tests that Amount::to_i64() returns the correct value. + /// + /// Mutant testing: Kills mutations that replace the return value with: + /// - None + /// - Some(0) + /// - Some(1) + /// - Some(-1) + /// Also catches mutation that replaces <= with > in the comparison. + #[test] + fn test_amount_to_i64_returns_correct_value() { + // Test with value 100 (catches None, Some(0), Some(1), Some(-1) mutations) + let amount = Amount::from(100); + let result = amount.to_i64(); + assert_eq!(result, Some(100)); + assert!(result.is_some()); + assert_ne!(result, Some(0)); + assert_ne!(result, Some(1)); + assert_ne!(result, Some(-1)); + + // Test with value 1000 (catches all constant mutations) + let amount = Amount::from(1000); + let result = amount.to_i64(); + assert_eq!(result, Some(1000)); + assert_ne!(result, None); + assert_ne!(result, Some(0)); + assert_ne!(result, Some(1)); + assert_ne!(result, Some(-1)); + + // Test with value 2 (specifically catches Some(1) mutation) + let amount = Amount::from(2); + let result = amount.to_i64(); + assert_eq!(result, Some(2)); + assert_ne!(result, Some(1)); + + // Test with i64::MAX (should return Some(i64::MAX)) + // This catches the <= vs > mutation: if <= becomes >, this would return None + let amount = Amount::from(i64::MAX as u64); + let result = amount.to_i64(); + assert_eq!(result, Some(i64::MAX)); + assert!(result.is_some()); + + // Test with i64::MAX + 1 (should return None) + // This is the boundary case for the <= comparison + let amount = Amount::from(i64::MAX as u64 + 1); + let result = amount.to_i64(); + assert!(result.is_none()); + + // Test with u64::MAX (should return None) + let amount = Amount::from(u64::MAX); + let result = amount.to_i64(); + assert!(result.is_none()); + + // Edge case: 0 should return Some(0) + let amount = Amount::from(0); + let result = amount.to_i64(); + assert_eq!(result, Some(0)); + + // Edge case: 1 should return Some(1) + let amount = Amount::from(1); + let result = amount.to_i64(); + assert_eq!(result, Some(1)); + } + + /// Tests the boundary condition for Amount::to_i64() at i64::MAX. + /// + /// This specifically tests the <= vs > mutation in the condition + /// `if self.0 <= i64::MAX as u64`. + #[test] + fn test_amount_to_i64_boundary() { + // Exactly at i64::MAX - should succeed + let at_max = Amount::from(i64::MAX as u64); + assert!(at_max.to_i64().is_some()); + assert_eq!(at_max.to_i64().unwrap(), i64::MAX); + + // One above i64::MAX - should fail + let above_max = Amount::from(i64::MAX as u64 + 1); + assert!(above_max.to_i64().is_none()); + + // One below i64::MAX - should succeed + let below_max = Amount::from(i64::MAX as u64 - 1); + assert!(below_max.to_i64().is_some()); + assert_eq!(below_max.to_i64().unwrap(), i64::MAX - 1); + } } From 68099730b36bfb722f323c5eec49dcdcf6c2a7e3 Mon Sep 17 00:00:00 2001 From: tsk Date: Mon, 1 Dec 2025 14:30:11 +0000 Subject: [PATCH 313/321] Allow multiple melt quotes for a payment request (#1353) The duplicate melt quote check now happens during melt execution (when transitioning to PENDING state) rather than during quote creation. This allows wallets to create multiple quotes for the same invoice, which is useful for retry scenarios. The constraint that only one quote per request_lookup_id can be PENDING or PAID is still enforced, but at melt time via FOR UPDATE row locking. --- .../tests/fake_wallet.rs | 104 +++++ .../tests/happy_path_mint_wallet.rs | 25 +- ...allow_duplicate_melt_request_lookup_id.sql | 15 + ...allow_duplicate_melt_request_lookup_id.sql | 9 + crates/cdk-sql-common/src/mint/mod.rs | 43 +- crates/cdk/src/mint/melt/melt_saga/mod.rs | 17 +- crates/cdk/src/mint/melt/melt_saga/tests.rs | 368 ++++++++++++++++++ 7 files changed, 566 insertions(+), 15 deletions(-) create mode 100644 crates/cdk-sql-common/src/mint/migrations/postgres/20251127000000_allow_duplicate_melt_request_lookup_id.sql create mode 100644 crates/cdk-sql-common/src/mint/migrations/sqlite/20251127000000_allow_duplicate_melt_request_lookup_id.sql diff --git a/crates/cdk-integration-tests/tests/fake_wallet.rs b/crates/cdk-integration-tests/tests/fake_wallet.rs index b4d515322..f618ee950 100644 --- a/crates/cdk-integration-tests/tests/fake_wallet.rs +++ b/crates/cdk-integration-tests/tests/fake_wallet.rs @@ -1462,6 +1462,110 @@ async fn test_wallet_proof_recovery_after_failed_melt() { ); } +/// Tests that concurrent melt attempts for the same invoice result in exactly one success +/// +/// This test verifies the race condition protection: when multiple melt quotes exist for the +/// same invoice and all are attempted concurrently, only one should succeed due to +/// the FOR UPDATE locking on quotes with the same request_lookup_id. +#[tokio::test(flavor = "multi_thread", worker_threads = 4)] +async fn test_concurrent_melt_same_invoice() { + const NUM_WALLETS: usize = 4; + + // Create multiple wallets to simulate concurrent requests + let mut wallets = Vec::with_capacity(NUM_WALLETS); + for i in 0..NUM_WALLETS { + let wallet = Arc::new( + Wallet::new( + MINT_URL, + CurrencyUnit::Sat, + Arc::new(memory::empty().await.unwrap()), + Mnemonic::generate(12).unwrap().to_seed_normalized(""), + None, + ) + .expect(&format!("failed to create wallet {}", i)), + ); + wallets.push(wallet); + } + + // Mint proofs for all wallets + for (i, wallet) in wallets.iter().enumerate() { + let mint_quote = wallet.mint_quote(100.into(), None).await.unwrap(); + let mut proof_streams = + wallet.proof_stream(mint_quote.clone(), SplitTarget::default(), None); + proof_streams + .next() + .await + .expect(&format!("payment for wallet {}", i)) + .expect("no error"); + } + + // Create a single invoice that all wallets will try to pay + let fake_description = FakeInvoiceDescription::default(); + let invoice = create_fake_invoice(9000, serde_json::to_string(&fake_description).unwrap()); + + // All wallets create melt quotes for the same invoice + let mut melt_quotes = Vec::with_capacity(NUM_WALLETS); + for wallet in &wallets { + let melt_quote = wallet.melt_quote(invoice.to_string(), None).await.unwrap(); + melt_quotes.push(melt_quote); + } + + // Verify all quotes have the same request (same invoice = same lookup_id) + for quote in &melt_quotes[1..] { + assert_eq!( + melt_quotes[0].request, quote.request, + "All quotes should be for the same invoice" + ); + } + + // Attempt all melts concurrently + let mut handles = Vec::with_capacity(NUM_WALLETS); + for (wallet, quote) in wallets.iter().zip(melt_quotes.iter()) { + let wallet_clone = Arc::clone(wallet); + let quote_id = quote.id.clone(); + handles.push(tokio::spawn( + async move { wallet_clone.melt("e_id).await }, + )); + } + + // Collect results + let mut results = Vec::with_capacity(NUM_WALLETS); + for handle in handles { + results.push(handle.await.expect("task panicked")); + } + + // Count successes and failures + let success_count = results.iter().filter(|r| r.is_ok()).count(); + let failure_count = results.iter().filter(|r| r.is_err()).count(); + + assert_eq!( + success_count, 1, + "Expected exactly one successful melt, got {}. Results: {:?}", + success_count, results + ); + assert_eq!( + failure_count, + NUM_WALLETS - 1, + "Expected {} failed melts, got {}", + NUM_WALLETS - 1, + failure_count + ); + + // Verify all failures were due to duplicate detection + for result in &results { + if let Err(err) = result { + let err_str = err.to_string().to_lowercase(); + assert!( + err_str.contains("duplicate") + || err_str.contains("already paid") + || err_str.contains("pending"), + "Expected duplicate/already paid/pending error, got: {}", + err + ); + } + } +} + /// Tests that wallet automatically recovers proofs after a failed swap operation #[tokio::test(flavor = "multi_thread", worker_threads = 1)] async fn test_wallet_proof_recovery_after_failed_swap() { diff --git a/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs b/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs index af056531c..2612d13e9 100644 --- a/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs +++ b/crates/cdk-integration-tests/tests/happy_path_mint_wallet.rs @@ -628,17 +628,26 @@ async fn test_pay_invoice_twice() { let melt = wallet.melt(&melt_quote.id).await.unwrap(); - let melt_two = wallet.melt_quote(invoice, None).await; + // Creating a second quote for the same invoice is allowed + let melt_quote_two = wallet.melt_quote(invoice, None).await.unwrap(); + + // But attempting to melt (pay) the second quote should fail + // since the first quote with the same lookup_id is already paid + let melt_two = wallet.melt(&melt_quote_two.id).await; match melt_two { - Err(err) => match err { - cdk::Error::RequestAlreadyPaid => (), - err => { - if !err.to_string().contains("Duplicate entry") { - panic!("Wrong invoice already paid: {}", err.to_string()); - } + Err(err) => { + let err_str = err.to_string().to_lowercase(); + if !err_str.contains("duplicate") + && !err_str.contains("already paid") + && !err_str.contains("request already paid") + { + panic!( + "Expected duplicate/already paid error, got: {}", + err.to_string() + ); } - }, + } Ok(_) => { panic!("Should not have allowed second payment"); } diff --git a/crates/cdk-sql-common/src/mint/migrations/postgres/20251127000000_allow_duplicate_melt_request_lookup_id.sql b/crates/cdk-sql-common/src/mint/migrations/postgres/20251127000000_allow_duplicate_melt_request_lookup_id.sql new file mode 100644 index 000000000..e13332c70 --- /dev/null +++ b/crates/cdk-sql-common/src/mint/migrations/postgres/20251127000000_allow_duplicate_melt_request_lookup_id.sql @@ -0,0 +1,15 @@ +-- Remove unique constraint on request_lookup_id for melt_quote +-- This allows multiple melt quotes for the same payment request +-- The constraint that only one can be PENDING or PAID at a time is enforced by a partial unique index + +-- Drop the unique index on request_lookup_id +DROP INDEX IF EXISTS unique_request_lookup_id_melt; + +-- Create a non-unique index for lookup performance +CREATE INDEX IF NOT EXISTS idx_melt_quote_request_lookup_id ON melt_quote(request_lookup_id); + +-- Create a partial unique index to enforce that only one quote per lookup_id can be PENDING or PAID +-- This provides database-level enforcement of the constraint +CREATE UNIQUE INDEX IF NOT EXISTS unique_pending_paid_lookup_id +ON melt_quote(request_lookup_id) +WHERE state IN ('PENDING', 'PAID'); diff --git a/crates/cdk-sql-common/src/mint/migrations/sqlite/20251127000000_allow_duplicate_melt_request_lookup_id.sql b/crates/cdk-sql-common/src/mint/migrations/sqlite/20251127000000_allow_duplicate_melt_request_lookup_id.sql new file mode 100644 index 000000000..c50d1a260 --- /dev/null +++ b/crates/cdk-sql-common/src/mint/migrations/sqlite/20251127000000_allow_duplicate_melt_request_lookup_id.sql @@ -0,0 +1,9 @@ +-- Remove unique constraint on request_lookup_id for melt_quote +-- This allows multiple melt quotes for the same payment request +-- The constraint that only one can be pending at a time is enforced in application logic + +-- Drop the unique index on request_lookup_id +DROP INDEX IF EXISTS unique_request_lookup_id_melt; + +-- Create a non-unique index for lookup performance +CREATE INDEX IF NOT EXISTS idx_melt_quote_request_lookup_id ON melt_quote(request_lookup_id); diff --git a/crates/cdk-sql-common/src/mint/mod.rs b/crates/cdk-sql-common/src/mint/mod.rs index 2fe165136..ac0bd7513 100644 --- a/crates/cdk-sql-common/src/mint/mod.rs +++ b/crates/cdk-sql-common/src/mint/mod.rs @@ -1239,11 +1239,9 @@ VALUES (:quote_id, :amount, :timestamp); melt_quote WHERE id=:id - AND state != :state "#, )? .bind("id", quote_id.to_string()) - .bind("state", state.to_string()) .fetch_one(&self.inner) .await? .map(sql_row_to_melt_quote) @@ -1252,6 +1250,47 @@ VALUES (:quote_id, :amount, :timestamp); check_melt_quote_state_transition(quote.state, state)?; + // When transitioning to Pending, lock all quotes with the same lookup_id + // and check if any are already pending or paid + if state == MeltQuoteState::Pending { + if let Some(ref lookup_id) = quote.request_lookup_id { + // Lock all quotes with the same lookup_id to prevent race conditions + let locked_quotes: Vec<(String, String)> = query( + r#" + SELECT id, state + FROM melt_quote + WHERE request_lookup_id = :lookup_id + FOR UPDATE + "#, + )? + .bind("lookup_id", lookup_id.to_string()) + .fetch_all(&self.inner) + .await? + .into_iter() + .map(|row| { + unpack_into!(let (id, state) = row); + Ok((column_as_string!(id), column_as_string!(state))) + }) + .collect::, Error>>()?; + + // Check if any other quote with the same lookup_id is pending or paid + let has_conflict = locked_quotes.iter().any(|(id, state)| { + id != "e_id.to_string() + && (state == &MeltQuoteState::Pending.to_string() + || state == &MeltQuoteState::Paid.to_string()) + }); + + if has_conflict { + tracing::warn!( + "Cannot transition quote {} to Pending: another quote with lookup_id {} is already pending or paid", + quote_id, + lookup_id + ); + return Err(Error::Duplicate); + } + } + } + let rec = if state == MeltQuoteState::Paid { let current_time = unix_time(); query(r#"UPDATE melt_quote SET state = :state, paid_time = :paid_time, payment_preimage = :payment_preimage WHERE id = :id"#)? diff --git a/crates/cdk/src/mint/melt/melt_saga/mod.rs b/crates/cdk/src/mint/melt/melt_saga/mod.rs index a98284e0e..81190b7fa 100644 --- a/crates/cdk/src/mint/melt/melt_saga/mod.rs +++ b/crates/cdk/src/mint/melt/melt_saga/mod.rs @@ -250,16 +250,23 @@ impl MeltSaga { ); } + // Update quote state to Pending + let (state, quote) = match tx + .update_melt_quote_state(melt_request.quote(), MeltQuoteState::Pending, None) + .await + { + Ok(result) => result, + Err(err) => { + tx.rollback().await?; + return Err(err.into()); + } + }; + // Publish proof state changes for pk in input_ys.iter() { self.pubsub.proof_state((*pk, State::Pending)); } - // Update quote state to Pending - let (state, quote) = tx - .update_melt_quote_state(melt_request.quote(), MeltQuoteState::Pending, None) - .await?; - if input_unit != Some(quote.unit.clone()) { tx.rollback().await?; return Err(Error::UnitMismatch); diff --git a/crates/cdk/src/mint/melt/melt_saga/tests.rs b/crates/cdk/src/mint/melt/melt_saga/tests.rs index e3cb99850..67c24344f 100644 --- a/crates/cdk/src/mint/melt/melt_saga/tests.rs +++ b/crates/cdk/src/mint/melt/melt_saga/tests.rs @@ -2496,3 +2496,371 @@ async fn assert_proofs_state( assert_eq!(state, expected_state, "Proof state mismatch"); } } + +// ============================================================================ +// Duplicate request_lookup_id Constraint Tests +// ============================================================================ + +/// Test: Cannot set melt quote to pending if another quote with same lookup_id is already pending +/// +/// This test verifies that when two melt quotes share the same request_lookup_id, +/// only one can be in PENDING state at a time. +#[tokio::test] +async fn test_duplicate_lookup_id_prevents_second_pending() { + use cdk_common::melt::MeltQuoteRequest; + use cdk_common::nuts::MeltQuoteBolt11Request; + use cdk_common::CurrencyUnit; + use cdk_fake_wallet::{create_fake_invoice, FakeInvoiceDescription}; + + // STEP 1: Setup test environment + let mint = create_test_mint().await.unwrap(); + + // Create a fake invoice description + let fake_description = FakeInvoiceDescription { + pay_invoice_state: MeltQuoteState::Paid, + check_payment_state: MeltQuoteState::Paid, + pay_err: false, + check_err: false, + }; + + // Create a single invoice that will be used for both quotes + let amount_msats: u64 = 9000; + let invoice = create_fake_invoice( + amount_msats, + serde_json::to_string(&fake_description).unwrap(), + ); + + // STEP 2: Create two melt quotes for the same invoice (same request_lookup_id) + let bolt11_request1 = MeltQuoteBolt11Request { + request: invoice.clone(), + unit: CurrencyUnit::Sat, + options: None, + }; + let quote_response1 = mint + .get_melt_quote(MeltQuoteRequest::Bolt11(bolt11_request1)) + .await + .unwrap(); + + let bolt11_request2 = MeltQuoteBolt11Request { + request: invoice, + unit: CurrencyUnit::Sat, + options: None, + }; + let quote_response2 = mint + .get_melt_quote(MeltQuoteRequest::Bolt11(bolt11_request2)) + .await + .unwrap(); + + // Retrieve full quotes + let quote1 = mint + .localstore + .get_melt_quote("e_response1.quote) + .await + .unwrap() + .expect("Quote 1 should exist"); + let quote2 = mint + .localstore + .get_melt_quote("e_response2.quote) + .await + .unwrap() + .expect("Quote 2 should exist"); + + // Verify both quotes have the same lookup_id + assert_eq!( + quote1.request_lookup_id, quote2.request_lookup_id, + "Both quotes should have the same request_lookup_id" + ); + + // STEP 3: Setup first melt saga (puts quote1 in PENDING state) + let proofs1 = mint_test_proofs(&mint, Amount::from(10_000)).await.unwrap(); + let melt_request1 = create_test_melt_request(&proofs1, "e1); + + let verification1 = mint.verify_inputs(melt_request1.inputs()).await.unwrap(); + let saga1 = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let setup_saga1 = saga1 + .setup_melt(&melt_request1, verification1) + .await + .unwrap(); + + // Continue through the payment flow to release any transaction locks + // The quote will stay in PENDING state because FakeWallet returns Paid + // but we don't call finalize() + let (payment_saga1, decision1) = setup_saga1 + .attempt_internal_settlement(&melt_request1) + .await + .unwrap(); + + // Make payment but don't finalize - keeps quote in PENDING + let confirmed_saga1 = payment_saga1.make_payment(decision1).await.unwrap(); + + // Drop the saga to release resources (simulates crash before finalize) + drop(confirmed_saga1); + + // Verify quote1 is now pending + let pending_quote1 = mint + .localstore + .get_melt_quote("e1.id) + .await + .unwrap() + .unwrap(); + assert_eq!( + pending_quote1.state, + MeltQuoteState::Pending, + "Quote 1 should be pending" + ); + + // STEP 4: Try to setup second saga with quote2 (same lookup_id) + let proofs2 = mint_test_proofs(&mint, Amount::from(10_000)).await.unwrap(); + let melt_request2 = create_test_melt_request(&proofs2, "e2); + + let verification2 = mint.verify_inputs(melt_request2.inputs()).await.unwrap(); + let saga2 = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let setup_result2 = saga2.setup_melt(&melt_request2, verification2).await; + + // STEP 5: Verify second setup fails due to duplicate pending lookup_id + assert!( + setup_result2.is_err(), + "Setup should fail when another quote with same lookup_id is already pending" + ); + + if let Err(error) = setup_result2 { + let error_msg = error.to_string().to_lowercase(); + assert!( + error_msg.contains("duplicate") || error_msg.contains("pending"), + "Error should mention duplicate or pending, got: {}", + error + ); + } + + // Verify quote2 is still unpaid + let still_unpaid_quote2 = mint + .localstore + .get_melt_quote("e2.id) + .await + .unwrap() + .unwrap(); + assert_eq!( + still_unpaid_quote2.state, + MeltQuoteState::Unpaid, + "Quote 2 should still be unpaid" + ); + + // SUCCESS: Duplicate pending lookup_id prevented! +} + +/// Test: Cannot set melt quote to pending if another quote with same lookup_id is already paid +/// +/// This test verifies that once a melt quote with a specific request_lookup_id is paid, +/// no other quote with the same lookup_id can transition to pending. +#[tokio::test] +async fn test_paid_lookup_id_prevents_pending() { + use cdk_common::melt::MeltQuoteRequest; + use cdk_common::nuts::MeltQuoteBolt11Request; + use cdk_common::CurrencyUnit; + use cdk_fake_wallet::{create_fake_invoice, FakeInvoiceDescription}; + + // STEP 1: Setup test environment + let mint = create_test_mint().await.unwrap(); + + // Create a fake invoice description + let fake_description = FakeInvoiceDescription { + pay_invoice_state: MeltQuoteState::Paid, + check_payment_state: MeltQuoteState::Paid, + pay_err: false, + check_err: false, + }; + + // Create a single invoice that will be used for both quotes + let amount_msats: u64 = 9000; + let invoice = create_fake_invoice( + amount_msats, + serde_json::to_string(&fake_description).unwrap(), + ); + + // STEP 2: Create two melt quotes for the same invoice (same request_lookup_id) + let bolt11_request1 = MeltQuoteBolt11Request { + request: invoice.clone(), + unit: CurrencyUnit::Sat, + options: None, + }; + let quote_response1 = mint + .get_melt_quote(MeltQuoteRequest::Bolt11(bolt11_request1)) + .await + .unwrap(); + + let bolt11_request2 = MeltQuoteBolt11Request { + request: invoice, + unit: CurrencyUnit::Sat, + options: None, + }; + let quote_response2 = mint + .get_melt_quote(MeltQuoteRequest::Bolt11(bolt11_request2)) + .await + .unwrap(); + + // Retrieve full quotes + let quote1 = mint + .localstore + .get_melt_quote("e_response1.quote) + .await + .unwrap() + .expect("Quote 1 should exist"); + let quote2 = mint + .localstore + .get_melt_quote("e_response2.quote) + .await + .unwrap() + .expect("Quote 2 should exist"); + + // STEP 3: Complete the first melt (marks quote1 as PAID) + let proofs1 = mint_test_proofs(&mint, Amount::from(10_000)).await.unwrap(); + let melt_request1 = create_test_melt_request(&proofs1, "e1); + + let verification1 = mint.verify_inputs(melt_request1.inputs()).await.unwrap(); + let saga1 = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let setup_saga1 = saga1 + .setup_melt(&melt_request1, verification1) + .await + .unwrap(); + + // Complete the full melt flow for quote1 + let (payment_saga, decision) = setup_saga1 + .attempt_internal_settlement(&melt_request1) + .await + .unwrap(); + let confirmed_saga = payment_saga.make_payment(decision).await.unwrap(); + let _response = confirmed_saga.finalize().await.unwrap(); + + // Verify quote1 is now paid + let paid_quote1 = mint + .localstore + .get_melt_quote("e1.id) + .await + .unwrap() + .unwrap(); + assert_eq!( + paid_quote1.state, + MeltQuoteState::Paid, + "Quote 1 should be paid" + ); + + // STEP 4: Try to setup second saga with quote2 (same lookup_id as paid quote) + let proofs2 = mint_test_proofs(&mint, Amount::from(10_000)).await.unwrap(); + let melt_request2 = create_test_melt_request(&proofs2, "e2); + + let verification2 = mint.verify_inputs(melt_request2.inputs()).await.unwrap(); + let saga2 = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let setup_result2 = saga2.setup_melt(&melt_request2, verification2).await; + + // STEP 5: Verify second setup fails due to already paid lookup_id + assert!( + setup_result2.is_err(), + "Setup should fail when another quote with same lookup_id is already paid" + ); + + if let Err(error) = setup_result2 { + let error_msg = error.to_string().to_lowercase(); + assert!( + error_msg.contains("duplicate") + || error_msg.contains("paid") + || error_msg.contains("pending"), + "Error should mention duplicate or paid, got: {}", + error + ); + } + + // SUCCESS: Paid lookup_id prevents new pending! +} + +/// Test: Different lookup_ids allow concurrent pending quotes +/// +/// This test verifies that melt quotes with different request_lookup_ids +/// can both be in PENDING state simultaneously. +#[tokio::test] +async fn test_different_lookup_ids_allow_concurrent_pending() { + // STEP 1: Setup test environment + let mint = create_test_mint().await.unwrap(); + + // STEP 2: Create two quotes with different lookup_ids (different invoices) + let quote1 = create_test_melt_quote(&mint, Amount::from(9_000)).await; + let quote2 = create_test_melt_quote(&mint, Amount::from(8_000)).await; + + // Verify quotes have different lookup_ids + assert_ne!( + quote1.request_lookup_id, quote2.request_lookup_id, + "Quotes should have different request_lookup_ids" + ); + + // STEP 3: Setup first saga (puts quote1 in PENDING state) + let proofs1 = mint_test_proofs(&mint, Amount::from(10_000)).await.unwrap(); + let melt_request1 = create_test_melt_request(&proofs1, "e1); + + let verification1 = mint.verify_inputs(melt_request1.inputs()).await.unwrap(); + let saga1 = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let _setup_saga1 = saga1 + .setup_melt(&melt_request1, verification1) + .await + .unwrap(); + + // STEP 4: Setup second saga (puts quote2 in PENDING state) + let proofs2 = mint_test_proofs(&mint, Amount::from(10_000)).await.unwrap(); + let melt_request2 = create_test_melt_request(&proofs2, "e2); + + let verification2 = mint.verify_inputs(melt_request2.inputs()).await.unwrap(); + let saga2 = MeltSaga::new( + std::sync::Arc::new(mint.clone()), + mint.localstore(), + mint.pubsub_manager(), + ); + let _setup_saga2 = saga2 + .setup_melt(&melt_request2, verification2) + .await + .unwrap(); + + // STEP 5: Verify both quotes are pending + let pending_quote1 = mint + .localstore + .get_melt_quote("e1.id) + .await + .unwrap() + .unwrap(); + let pending_quote2 = mint + .localstore + .get_melt_quote("e2.id) + .await + .unwrap() + .unwrap(); + + assert_eq!( + pending_quote1.state, + MeltQuoteState::Pending, + "Quote 1 should be pending" + ); + assert_eq!( + pending_quote2.state, + MeltQuoteState::Pending, + "Quote 2 should be pending" + ); + + // SUCCESS: Different lookup_ids allow concurrent pending! +} From 1c5f6949cb8de2833720396637b9039de1ce4936 Mon Sep 17 00:00:00 2001 From: unldenis Date: Mon, 1 Dec 2025 16:12:53 +0100 Subject: [PATCH 314/321] feat: add portal wallet --- Cargo.toml | 1 + crates/cashu/src/amount.rs | 7 + crates/cashu/src/nuts/nut00/mod.rs | 8 + crates/cdk-cli/src/main.rs | 6 +- crates/cdk-cli/src/sub_commands/balance.rs | 38 ++- crates/cdk-cli/src/sub_commands/melt.rs | 11 +- crates/cdk-cli/src/sub_commands/send.rs | 8 +- crates/cdk-cli/src/sub_commands/transfer.rs | 5 +- crates/cdk-ffi/src/multi_mint_wallet.rs | 2 +- crates/cdk-integration-tests/Cargo.toml | 2 +- .../src/bin/start_regtest_mints.rs | 1 + crates/cdk-integration-tests/src/shared.rs | 3 + crates/cdk-mintd/Cargo.toml | 5 +- crates/cdk-mintd/src/config.rs | 12 + crates/cdk-mintd/src/env_vars/mod.rs | 16 +- .../cdk-mintd/src/env_vars/portal_wallet.rs | 27 ++ crates/cdk-mintd/src/lib.rs | 34 ++- crates/cdk-mintd/src/setup.rs | 21 +- crates/cdk-portal-wallet/Cargo.toml | 29 ++ crates/cdk-portal-wallet/README.md | 26 ++ crates/cdk-portal-wallet/src/error.rs | 21 ++ crates/cdk-portal-wallet/src/lib.rs | 247 ++++++++++++++++++ crates/cdk/src/wallet/multi_mint_wallet.rs | 4 +- portal-cmds.txt | 8 + 24 files changed, 505 insertions(+), 37 deletions(-) create mode 100644 crates/cdk-mintd/src/env_vars/portal_wallet.rs create mode 100644 crates/cdk-portal-wallet/Cargo.toml create mode 100644 crates/cdk-portal-wallet/README.md create mode 100644 crates/cdk-portal-wallet/src/error.rs create mode 100644 crates/cdk-portal-wallet/src/lib.rs create mode 100644 portal-cmds.txt diff --git a/Cargo.toml b/Cargo.toml index e39fbe736..5c01a5d36 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -119,6 +119,7 @@ nostr-sdk = { version = "0.43.0", default-features = false, features = [ ]} +cdk-portal-wallet = { path = "./crates/cdk-portal-wallet", version = "=0.14.0" } [workspace.metadata] diff --git a/crates/cashu/src/amount.rs b/crates/cashu/src/amount.rs index d2497f414..6cbc46214 100644 --- a/crates/cashu/src/amount.rs +++ b/crates/cashu/src/amount.rs @@ -415,6 +415,13 @@ where (CurrencyUnit::Msat, CurrencyUnit::Sat) => Ok((amount / MSAT_IN_SAT).into()), (CurrencyUnit::Usd, CurrencyUnit::Usd) => Ok(amount.into()), (CurrencyUnit::Eur, CurrencyUnit::Eur) => Ok(amount.into()), + (CurrencyUnit::Custom(from_unit), CurrencyUnit::Custom(to_unit)) => { + if from_unit == to_unit { + Ok(amount.into()) + } else { + Err(Error::CannotConvertUnits) + } + } _ => Err(Error::CannotConvertUnits), } } diff --git a/crates/cashu/src/nuts/nut00/mod.rs b/crates/cashu/src/nuts/nut00/mod.rs index f9364874c..c44a4bc91 100644 --- a/crates/cashu/src/nuts/nut00/mod.rs +++ b/crates/cashu/src/nuts/nut00/mod.rs @@ -582,6 +582,14 @@ impl CurrencyUnit { Self::Usd => Some(2), Self::Eur => Some(3), Self::Auth => Some(4), + Self::Custom(v) => { + use std::hash::DefaultHasher; + + let mut hasher = DefaultHasher::new(); + v.hash(&mut hasher); + let h = hasher.finish(); + Some((h as u32) & 0x7FFFFFFF) + } _ => None, } } diff --git a/crates/cdk-cli/src/main.rs b/crates/cdk-cli/src/main.rs index 3cc75141d..9cafe3a03 100644 --- a/crates/cdk-cli/src/main.rs +++ b/crates/cdk-cli/src/main.rs @@ -72,7 +72,7 @@ enum Commands { /// Decode a token DecodeToken(sub_commands::decode_token::DecodeTokenSubCommand), /// Balance - Balance, + Balance(sub_commands::balance::BalanceSubCommand), /// Pay bolt11 invoice Melt(sub_commands::melt::MeltSubCommand), /// Claim pending mint quotes that have been paid @@ -232,7 +232,9 @@ async fn main() -> Result<()> { Commands::DecodeToken(sub_command_args) => { sub_commands::decode_token::decode_token(sub_command_args) } - Commands::Balance => sub_commands::balance::balance(&multi_mint_wallet).await, + Commands::Balance(sub_command_args) => { + sub_commands::balance::balance(&multi_mint_wallet, sub_command_args).await + } Commands::Melt(sub_command_args) => { sub_commands::melt::pay(&multi_mint_wallet, sub_command_args).await } diff --git a/crates/cdk-cli/src/sub_commands/balance.rs b/crates/cdk-cli/src/sub_commands/balance.rs index 51241ff22..19561029a 100644 --- a/crates/cdk-cli/src/sub_commands/balance.rs +++ b/crates/cdk-cli/src/sub_commands/balance.rs @@ -5,20 +5,32 @@ use cdk::mint_url::MintUrl; use cdk::nuts::CurrencyUnit; use cdk::wallet::MultiMintWallet; use cdk::Amount; +use clap::Args; -pub async fn balance(multi_mint_wallet: &MultiMintWallet) -> Result<()> { +use std::str::FromStr; + +#[derive(Args)] +pub struct BalanceSubCommand { + /// Currency unit e.g. sat, msat, usd, eur + #[arg(short, long)] + pub unit: String, +} + +pub async fn balance( + multi_mint_wallet: &MultiMintWallet, + sub_command_args: &BalanceSubCommand, +) -> Result<()> { + println!("Balance for unit: {}", sub_command_args.unit); + + let unit = CurrencyUnit::from_str(&sub_command_args.unit)?; // Show individual mint balances - let mint_balances = mint_balances(multi_mint_wallet, multi_mint_wallet.unit()).await?; + let mint_balances = mint_balances(multi_mint_wallet).await?; // Show total balance using the new unified interface let total = multi_mint_wallet.total_balance().await?; if !mint_balances.is_empty() { println!(); - println!( - "Total balance across all wallets: {} {}", - total, - multi_mint_wallet.unit() - ); + println!("Total balance across all wallets: {} {}", total, unit); } Ok(()) @@ -26,20 +38,20 @@ pub async fn balance(multi_mint_wallet: &MultiMintWallet) -> Result<()> { pub async fn mint_balances( multi_mint_wallet: &MultiMintWallet, - unit: &CurrencyUnit, -) -> Result> { - let wallets: BTreeMap = multi_mint_wallet.get_balances().await?; +) -> Result> { + let wallets: BTreeMap = + multi_mint_wallet.get_balances().await?; let mut wallets_vec = Vec::with_capacity(wallets.len()); - for (i, (mint_url, amount)) in wallets + for (i, (mint_url, (amount, unit))) in wallets .iter() - .filter(|(_, a)| a > &&Amount::ZERO) + .filter(|(_, (a, _))| a > &&Amount::ZERO) .enumerate() { let mint_url = mint_url.clone(); println!("{i}: {mint_url} {amount} {unit}"); - wallets_vec.push((mint_url, *amount)) + wallets_vec.push((mint_url, (amount.clone(), unit.clone()))); } Ok(wallets_vec) } diff --git a/crates/cdk-cli/src/sub_commands/melt.rs b/crates/cdk-cli/src/sub_commands/melt.rs index 39d7c867b..96a2cb448 100644 --- a/crates/cdk-cli/src/sub_commands/melt.rs +++ b/crates/cdk-cli/src/sub_commands/melt.rs @@ -83,10 +83,11 @@ pub async fn pay( bail!("No mints available in the wallet"); } - let balances_vec: Vec<(MintUrl, Amount)> = balances_map.into_iter().collect(); + let balances_vec: Vec<(MintUrl, (Amount, CurrencyUnit))> = + balances_map.into_iter().collect(); println!("\nAvailable mints and balances:"); - for (index, (mint_url, balance)) in balances_vec.iter().enumerate() { + for (index, (mint_url, (balance, unit))) in balances_vec.iter().enumerate() { println!( " {}: {} - {} {}", index, @@ -127,7 +128,7 @@ pub async fn pay( // Show available mints and balances let balances = multi_mint_wallet.get_balances().await?; println!("\nAvailable mints and balances:"); - for (i, (mint_url, balance)) in balances.iter().enumerate() { + for (i, (mint_url, (balance, unit))) in balances.iter().enumerate() { println!( " {}: {} - {} {}", i, @@ -277,7 +278,7 @@ pub async fn pay( balances .into_iter() - .find(|(_, balance)| *balance > Amount::ZERO) + .find(|(_, (balance, _))| *balance > Amount::ZERO) .map(|(mint_url, _)| mint_url) .ok_or_else(|| anyhow::anyhow!("No mint available for BOLT12 payment"))? }; @@ -327,7 +328,7 @@ pub async fn pay( balances .into_iter() - .find(|(_, balance)| *balance > Amount::ZERO) + .find(|(_, (balance, _))| *balance > Amount::ZERO) .map(|(mint_url, _)| mint_url) .ok_or_else(|| anyhow::anyhow!("No mint available for BIP353 payment"))? }; diff --git a/crates/cdk-cli/src/sub_commands/send.rs b/crates/cdk-cli/src/sub_commands/send.rs index 8e2dc4af5..7f4ba1b57 100644 --- a/crates/cdk-cli/src/sub_commands/send.rs +++ b/crates/cdk-cli/src/sub_commands/send.rs @@ -9,6 +9,7 @@ use cdk::Amount; use clap::Args; use crate::utils::get_number_input; +use cdk::nuts::CurrencyUnit; #[derive(Args)] pub struct SendSubCommand { @@ -74,10 +75,11 @@ pub async fn send( return Err(anyhow!("No mints available in the wallet")); } - let balances_vec: Vec<(MintUrl, Amount)> = balances_map.into_iter().collect(); + let balances_vec: Vec<(MintUrl, (Amount, CurrencyUnit))> = + balances_map.into_iter().collect(); println!("\nAvailable mints and balances:"); - for (index, (mint_url, balance)) in balances_vec.iter().enumerate() { + for (index, (mint_url, (balance, unit))) in balances_vec.iter().enumerate() { println!( " {}: {} - {} {}", index, @@ -284,7 +286,7 @@ pub async fn send( let balances = multi_mint_wallet.get_balances().await?; let best_mint = balances .into_iter() - .find(|(_, balance)| *balance >= token_amount) + .find(|(_, (balance, _))| *balance >= token_amount) .map(|(mint_url, _)| mint_url) .ok_or_else(|| anyhow!("No mint has sufficient balance for the requested amount"))?; diff --git a/crates/cdk-cli/src/sub_commands/transfer.rs b/crates/cdk-cli/src/sub_commands/transfer.rs index e8042b29f..13adeb4e4 100644 --- a/crates/cdk-cli/src/sub_commands/transfer.rs +++ b/crates/cdk-cli/src/sub_commands/transfer.rs @@ -44,7 +44,7 @@ async fn select_mint( } println!("\nAvailable mints:"); - for (i, (mint_url, balance)) in available_mints.iter().enumerate() { + for (i, (mint_url, (balance, unit))) in available_mints.iter().enumerate() { println!( " {}: {} - {} {}", i, @@ -122,7 +122,8 @@ pub async fn transfer( let balances = multi_mint_wallet.get_balances().await?; let source_balance = balances .get(&source_mint_url) - .copied() + .map(|(balance, _)| balance) + .cloned() .unwrap_or(Amount::ZERO); if source_balance == Amount::ZERO { diff --git a/crates/cdk-ffi/src/multi_mint_wallet.rs b/crates/cdk-ffi/src/multi_mint_wallet.rs index 3ed6186ab..988f2db35 100644 --- a/crates/cdk-ffi/src/multi_mint_wallet.rs +++ b/crates/cdk-ffi/src/multi_mint_wallet.rs @@ -203,7 +203,7 @@ impl MultiMintWallet { pub async fn get_balances(&self) -> Result { let balances = self.inner.get_balances().await?; let mut balance_map = HashMap::new(); - for (mint_url, amount) in balances { + for (mint_url, (amount, unit)) in balances { balance_map.insert(mint_url.to_string(), amount.into()); } Ok(balance_map) diff --git a/crates/cdk-integration-tests/Cargo.toml b/crates/cdk-integration-tests/Cargo.toml index ed1828552..c2d7d8495 100644 --- a/crates/cdk-integration-tests/Cargo.toml +++ b/crates/cdk-integration-tests/Cargo.toml @@ -29,7 +29,7 @@ cdk-sqlite = { workspace = true } cdk-redb = { workspace = true } cdk-fake-wallet = { workspace = true } cdk-common = { workspace = true, features = ["mint", "wallet", "auth"] } -cdk-mintd = { workspace = true, features = ["cln", "lnd", "fakewallet", "grpc-processor", "auth", "lnbits", "management-rpc", "sqlite", "postgres", "ldk-node", "prometheus"] } +cdk-mintd = { workspace = true, features = ["cln", "lnd", "fakewallet", "grpc-processor", "auth", "lnbits", "management-rpc", "sqlite", "postgres", "ldk-node", "prometheus", "portalwallet"] } futures = { workspace = true, default-features = false, features = [ "executor", ] } diff --git a/crates/cdk-integration-tests/src/bin/start_regtest_mints.rs b/crates/cdk-integration-tests/src/bin/start_regtest_mints.rs index 154db6139..e9ab87dae 100644 --- a/crates/cdk-integration-tests/src/bin/start_regtest_mints.rs +++ b/crates/cdk-integration-tests/src/bin/start_regtest_mints.rs @@ -299,6 +299,7 @@ fn create_ldk_settings( mint_management_rpc: None, prometheus: None, auth: None, + portal_wallet: None, } } diff --git a/crates/cdk-integration-tests/src/shared.rs b/crates/cdk-integration-tests/src/shared.rs index fe9d0afe4..3bdee6e13 100644 --- a/crates/cdk-integration-tests/src/shared.rs +++ b/crates/cdk-integration-tests/src/shared.rs @@ -223,6 +223,7 @@ pub fn create_fake_wallet_settings( mint_management_rpc: None, auth: None, prometheus: Some(Default::default()), + portal_wallet: None, } } @@ -273,6 +274,7 @@ pub fn create_cln_settings( mint_management_rpc: None, auth: None, prometheus: Some(Default::default()), + portal_wallet: None, } } @@ -321,5 +323,6 @@ pub fn create_lnd_settings( mint_management_rpc: None, auth: None, prometheus: Some(Default::default()), + portal_wallet: None, } } diff --git a/crates/cdk-mintd/Cargo.toml b/crates/cdk-mintd/Cargo.toml index ae83b7515..2a54c71a4 100644 --- a/crates/cdk-mintd/Cargo.toml +++ b/crates/cdk-mintd/Cargo.toml @@ -11,7 +11,7 @@ rust-version.workspace = true readme = "README.md" [features] -default = ["management-rpc", "cln", "lnd", "lnbits", "fakewallet", "grpc-processor", "sqlite"] +default = ["management-rpc", "cln", "lnd", "lnbits", "fakewallet", "grpc-processor", "sqlite", "portalwallet"] # Database features - at least one must be enabled sqlite = ["dep:cdk-sqlite"] postgres = ["dep:cdk-postgres"] @@ -29,6 +29,7 @@ swagger = ["cdk-axum/swagger", "dep:utoipa", "dep:utoipa-swagger-ui"] redis = ["cdk-axum/redis"] auth = ["cdk/auth", "cdk-axum/auth", "cdk-sqlite?/auth", "cdk-postgres?/auth"] prometheus = ["cdk/prometheus", "dep:cdk-prometheus", "cdk-sqlite?/prometheus", "cdk-axum/prometheus"] +portalwallet = ["dep:cdk-portal-wallet"] [dependencies] anyhow.workspace = true @@ -69,4 +70,6 @@ home.workspace = true utoipa = { workspace = true, optional = true } utoipa-swagger-ui = { version = "9.0.0", features = ["axum"], optional = true } +cdk-portal-wallet = { workspace = true, optional = true } + [build-dependencies] diff --git a/crates/cdk-mintd/src/config.rs b/crates/cdk-mintd/src/config.rs index b0d73dc46..55a713978 100644 --- a/crates/cdk-mintd/src/config.rs +++ b/crates/cdk-mintd/src/config.rs @@ -138,6 +138,8 @@ pub enum LnBackend { LdkNode, #[cfg(feature = "grpc-processor")] GrpcProcessor, + #[cfg(feature = "portalwallet")] + PortalWallet, } impl std::str::FromStr for LnBackend { @@ -157,6 +159,8 @@ impl std::str::FromStr for LnBackend { "ldk-node" | "ldknode" => Ok(LnBackend::LdkNode), #[cfg(feature = "grpc-processor")] "grpcprocessor" => Ok(LnBackend::GrpcProcessor), + #[cfg(feature = "portalwallet")] + "portalwallet" => Ok(LnBackend::PortalWallet), _ => Err(format!("Unknown Lightning backend: {s}")), } } @@ -422,6 +426,12 @@ fn default_grpc_port() -> u16 { 50051 } +#[cfg(feature = "portalwallet")] +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct PortalWallet { + pub supported_units: Vec, +} + #[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Default)] #[serde(rename_all = "lowercase")] pub enum DatabaseEngine { @@ -572,6 +582,8 @@ pub struct Settings { pub auth: Option, #[cfg(feature = "prometheus")] pub prometheus: Option, + #[cfg(feature = "portalwallet")] + pub portal_wallet: Option, } #[derive(Debug, Clone, Serialize, Deserialize, Default)] diff --git a/crates/cdk-mintd/src/env_vars/mod.rs b/crates/cdk-mintd/src/env_vars/mod.rs index a3f4c5979..3c56364b4 100644 --- a/crates/cdk-mintd/src/env_vars/mod.rs +++ b/crates/cdk-mintd/src/env_vars/mod.rs @@ -25,12 +25,15 @@ mod lnbits; mod lnd; #[cfg(feature = "management-rpc")] mod management_rpc; +#[cfg(feature = "portalwallet")] +mod portal_wallet; #[cfg(feature = "prometheus")] mod prometheus; use std::env; use std::str::FromStr; +use crate::config::{DatabaseEngine, LnBackend, Settings}; use anyhow::{anyhow, bail, Result}; #[cfg(feature = "auth")] pub use auth::*; @@ -52,11 +55,11 @@ pub use lnd::*; #[cfg(feature = "management-rpc")] pub use management_rpc::*; pub use mint_info::*; +#[cfg(feature = "portalwallet")] +pub use portal_wallet::*; #[cfg(feature = "prometheus")] pub use prometheus::*; -use crate::config::{DatabaseEngine, LnBackend, Settings}; - impl Settings { pub fn from_env(&mut self) -> Result { if let Ok(database) = env::var(DATABASE_ENV_VAR) { @@ -148,6 +151,15 @@ impl Settings { self.grpc_processor = Some(self.grpc_processor.clone().unwrap_or_default().from_env()); } + #[cfg(feature = "portalwallet")] + LnBackend::PortalWallet => { + self.portal_wallet = Some( + self.portal_wallet + .clone() + .expect("Portal wallet config must be set") + .from_env(), + ); + } LnBackend::None => bail!("Ln backend must be set"), #[allow(unreachable_patterns)] _ => bail!("Selected Ln backend is not enabled in this build"), diff --git a/crates/cdk-mintd/src/env_vars/portal_wallet.rs b/crates/cdk-mintd/src/env_vars/portal_wallet.rs new file mode 100644 index 000000000..c75c1b9ff --- /dev/null +++ b/crates/cdk-mintd/src/env_vars/portal_wallet.rs @@ -0,0 +1,27 @@ +//! PortalWallet environment variables + +use std::env; + +use cdk::nuts::CurrencyUnit; + +use crate::config::PortalWallet; + +// Fake Wallet environment variables +pub const ENV_PORTAL_WALLET_SUPPORTED_UNITS: &str = "CDK_MINTD_PORTAL_WALLET_SUPPORTED_UNITS"; + +impl PortalWallet { + pub fn from_env(mut self) -> Self { + // Supported Units - expects comma-separated list + if let Ok(units_str) = env::var(ENV_PORTAL_WALLET_SUPPORTED_UNITS) { + if let Ok(units) = units_str + .split(',') + .map(|s| s.trim().parse()) + .collect::, _>>() + { + self.supported_units = units; + } + } + + self + } +} diff --git a/crates/cdk-mintd/src/lib.rs b/crates/cdk-mintd/src/lib.rs index 8b7514c1a..2b2c34fd8 100644 --- a/crates/cdk-mintd/src/lib.rs +++ b/crates/cdk-mintd/src/lib.rs @@ -21,7 +21,8 @@ use cdk::mint::{Mint, MintBuilder, MintMeltLimits}; feature = "lnd", feature = "ldk-node", feature = "fakewallet", - feature = "grpc-processor" + feature = "grpc-processor", + feature = "portalwallet" ))] use cdk::nuts::nut17::SupportedMethods; use cdk::nuts::nut19::{CachedEndpoint, Method as NUT19Method, Path as NUT19Path}; @@ -30,7 +31,8 @@ use cdk::nuts::nut19::{CachedEndpoint, Method as NUT19Method, Path as NUT19Path} feature = "lnbits", feature = "lnd", feature = "ldk-node", - feature = "fakewallet" + feature = "fakewallet", + feature = "portalwallet" ))] use cdk::nuts::CurrencyUnit; #[cfg(feature = "auth")] @@ -548,6 +550,31 @@ async fn configure_lightning_backend( ) .await?; } + #[cfg(feature = "portalwallet")] + LnBackend::PortalWallet => { + let portal_wallet = settings + .clone() + .portal_wallet + .expect("Portal wallet defined"); + tracing::info!("Using portal wallet: {:?}", portal_wallet); + + for unit in portal_wallet.clone().supported_units { + let portal = portal_wallet + .setup(settings, unit.clone(), None, work_dir, _kv_store.clone()) + .await?; + #[cfg(feature = "prometheus")] + let portal = MetricsMintPayment::new(portal); + + mint_builder = configure_backend_for_unit( + settings, + mint_builder, + unit.clone(), + mint_melt_limits, + Arc::new(portal), + ) + .await?; + } + } LnBackend::None => { tracing::error!( "Payment backend was not set or feature disabled. {:?}", @@ -605,7 +632,8 @@ async fn configure_backend_for_unit( feature = "lnd", feature = "fakewallet", feature = "grpc-processor", - feature = "ldk-node" + feature = "ldk-node", + feature = "portalwallet" ))] { let nut17_supported = SupportedMethods::default_bolt11(unit); diff --git a/crates/cdk-mintd/src/setup.rs b/crates/cdk-mintd/src/setup.rs index b85ef2aba..b707a1901 100644 --- a/crates/cdk-mintd/src/setup.rs +++ b/crates/cdk-mintd/src/setup.rs @@ -1,6 +1,6 @@ -#[cfg(feature = "fakewallet")] +#[cfg(any(feature = "fakewallet", feature = "portalwallet"))] use std::collections::HashMap; -#[cfg(feature = "fakewallet")] +#[cfg(any(feature = "fakewallet", feature = "portalwallet"))] use std::collections::HashSet; use std::path::Path; use std::sync::Arc; @@ -362,3 +362,20 @@ impl LnBackendSetup for config::LdkNode { Ok(ldk_node) } } + +#[cfg(feature = "portalwallet")] +#[async_trait] +impl LnBackendSetup for config::PortalWallet { + async fn setup( + &self, + _settings: &Settings, + unit: CurrencyUnit, + _runtime: Option>, + _work_dir: &Path, + _kv_store: Option + Send + Sync>>, + ) -> anyhow::Result { + let portal_wallet = cdk_portal_wallet::SimpleWallet::new(unit); + + Ok(portal_wallet) + } +} diff --git a/crates/cdk-portal-wallet/Cargo.toml b/crates/cdk-portal-wallet/Cargo.toml new file mode 100644 index 000000000..23c0c01b8 --- /dev/null +++ b/crates/cdk-portal-wallet/Cargo.toml @@ -0,0 +1,29 @@ +[package] +name = "cdk-portal-wallet" +version.workspace = true +edition.workspace = true +authors = ["CDK Developers"] +license.workspace = true +homepage = "https://github.com/cashubtc/cdk" +repository = "https://github.com/cashubtc/cdk.git" +rust-version.workspace = true # MSRV +description = "CDK portal wallet" +readme = "README.md" + +[dependencies] +async-trait.workspace = true +bitcoin.workspace = true +cdk-common = { workspace = true, features = ["mint"] } +futures.workspace = true +tokio.workspace = true +tokio-util.workspace = true +tracing.workspace = true +thiserror.workspace = true +serde.workspace = true +serde_json.workspace = true +lightning-invoice.workspace = true +lightning.workspace = true +tokio-stream.workspace = true +reqwest.workspace = true +uuid.workspace = true +rand.workspace = true diff --git a/crates/cdk-portal-wallet/README.md b/crates/cdk-portal-wallet/README.md new file mode 100644 index 000000000..cca6c6476 --- /dev/null +++ b/crates/cdk-portal-wallet/README.md @@ -0,0 +1,26 @@ +# CDK Fake Wallet + +[![crates.io](https://img.shields.io/crates/v/cdk-fake-wallet.svg)](https://crates.io/crates/cdk-fake-wallet) +[![Documentation](https://docs.rs/cdk-fake-wallet/badge.svg)](https://docs.rs/cdk-fake-wallet) +[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/cashubtc/cdk/blob/main/LICENSE) + +**ALPHA** This library is in early development, the API will change and should be used with caution. + +A fake Lightning wallet implementation for the Cashu Development Kit (CDK). This is intended for testing purposes only - quotes are automatically filled without actual Lightning Network interaction. + +## Installation + +Add this to your `Cargo.toml`: + +```toml +[dependencies] +cdk-fake-wallet = "*" +``` + +## Warning + +This is for testing purposes only. Do not use in production environments. + +## License + +This project is licensed under the [MIT License](../../LICENSE). diff --git a/crates/cdk-portal-wallet/src/error.rs b/crates/cdk-portal-wallet/src/error.rs new file mode 100644 index 000000000..9e77e9735 --- /dev/null +++ b/crates/cdk-portal-wallet/src/error.rs @@ -0,0 +1,21 @@ +//! Fake Wallet Error + +use thiserror::Error; + +/// Fake Wallet Error +#[derive(Debug, Error)] +pub enum Error { + /// Unsupported Bolt12 + #[error("Unsupported Bolt12")] + UnsupportedBolt12, + + /// Payment not found + #[error("Payment not found")] + PaymentNotFound, +} + +impl From for cdk_common::payment::Error { + fn from(e: Error) -> Self { + Self::Custom(e.to_string()) + } +} diff --git a/crates/cdk-portal-wallet/src/lib.rs b/crates/cdk-portal-wallet/src/lib.rs new file mode 100644 index 000000000..76a8dda52 --- /dev/null +++ b/crates/cdk-portal-wallet/src/lib.rs @@ -0,0 +1,247 @@ +//! CDK portal wallet + +pub mod error; + +use std::collections::HashMap; +use std::pin::Pin; +use std::sync::atomic::{AtomicBool, Ordering}; +use std::sync::Arc; + +use async_trait::async_trait; +use futures::Stream; +use futures::StreamExt; +use rand::Rng; +use tokio::sync::mpsc::{self, Receiver, Sender}; +use tokio::sync::Mutex; +use tokio_stream::wrappers::ReceiverStream; +use tokio_util::sync::CancellationToken; +use uuid::Uuid; + +use cdk_common::amount::Amount; +use cdk_common::nuts::{CurrencyUnit, MeltQuoteState}; +use cdk_common::payment::{ + self, Bolt11Settings, CreateIncomingPaymentResponse, Event, IncomingPaymentOptions, + MakePaymentResponse, MintPayment, OutgoingPaymentOptions, PaymentIdentifier, + PaymentQuoteResponse, WaitPaymentResponse, +}; +use serde_json::Value; + +pub struct SimpleWallet { + sender: Sender<[u8; 32]>, + receiver: Arc>>>, + invoices: Arc>>, // payment_hash -> (invoice_id, paid, amount, unit) + wait_invoice_cancel_token: CancellationToken, + wait_invoice_is_active: Arc, + settings: Bolt11Settings, +} + +impl SimpleWallet { + pub fn new(currency_unit: CurrencyUnit) -> Self { + let (sender, receiver) = mpsc::channel(32); + Self { + sender, + receiver: Arc::new(Mutex::new(Some(receiver))), + invoices: Arc::new(Mutex::new(HashMap::new())), + wait_invoice_cancel_token: CancellationToken::new(), + wait_invoice_is_active: Arc::new(AtomicBool::new(false)), + settings: Bolt11Settings { + mpp: false, + unit: currency_unit, + invoice_description: true, + amountless: false, + bolt12: false, + }, + } + } +} + +#[async_trait] +impl MintPayment for SimpleWallet { + type Err = payment::Error; + + async fn get_settings(&self) -> Result { + Ok(serde_json::to_value(&self.settings)?) + } + + fn is_wait_invoice_active(&self) -> bool { + self.wait_invoice_is_active.load(Ordering::SeqCst) + } + + fn cancel_wait_invoice(&self) { + self.wait_invoice_cancel_token.cancel() + } + + async fn wait_payment_event( + &self, + ) -> Result + Send>>, Self::Err> { + // Take the current receiver out. Only one consumer at a time! + let mut slot = self.receiver.lock().await; + let receiver = slot.take(); + let invoices = self.invoices.clone(); + + if let Some(receiver) = receiver { + let stream = ReceiverStream::new(receiver).filter_map(move |payment_hash| { + let invoices = invoices.clone(); + + async move { + let guard = invoices.lock().await; + if let Some((invoice_id, paid, amount, unit)) = guard.get(&payment_hash) { + if *paid { + Some(Event::PaymentReceived(WaitPaymentResponse { + payment_identifier: PaymentIdentifier::PaymentHash(payment_hash), + payment_amount: *amount, + unit: unit.clone(), + payment_id: invoice_id.clone(), + })) + } else { + None + } + } else { + None + } + } + }); + Ok(Box::pin(stream)) + } else { + // Already active + Ok(Box::pin(futures::stream::empty())) + } + } + + async fn get_payment_quote( + &self, + _unit: &CurrencyUnit, + options: OutgoingPaymentOptions, + ) -> Result { + let amount_msat = match options { + OutgoingPaymentOptions::Bolt11(ref bolt11_options) => { + match bolt11_options.melt_options { + Some(ref amt) => amt.amount_msat(), + None => bolt11_options + .bolt11 + .amount_milli_satoshis() + .ok_or(payment::Error::Custom("Unknown invoice amount".to_string()))? + .into(), + } + } + OutgoingPaymentOptions::Bolt12(_) => return Err(error::Error::UnsupportedBolt12.into()), + }; + let random_hash: [u8; 32] = rand::rng().random(); + Ok(PaymentQuoteResponse { + request_lookup_id: Some(PaymentIdentifier::PaymentHash(random_hash)), + amount: Amount::from(amount_msat), + fee: Amount::ZERO, + state: MeltQuoteState::Unpaid, + unit: CurrencyUnit::Msat, + }) + } + + async fn make_payment( + &self, + _unit: &CurrencyUnit, + options: OutgoingPaymentOptions, + ) -> Result { + let invoice_id = match options { + OutgoingPaymentOptions::Bolt11(ref bolt11_options) => bolt11_options.bolt11.to_string(), + OutgoingPaymentOptions::Bolt12(_) => return Err(error::Error::UnsupportedBolt12.into()), + }; + let mut invoices = self.invoices.lock().await; + if let Some((payment_hash, paid, amount, unit)) = + invoices + .iter_mut() + .find_map(|(hash, (id, paid, amount, unit))| { + (id == &invoice_id).then_some((hash, paid, amount, unit)) + }) + { + *paid = true; + // Optionally, you could do self.sender.send(*payment_hash).await, but we already auto-send. + Ok(MakePaymentResponse { + payment_lookup_id: PaymentIdentifier::PaymentHash(*payment_hash), + payment_proof: Some(invoice_id.clone()), + status: MeltQuoteState::Paid, + total_spent: *amount, + unit: unit.clone(), + }) + } else { + Err(error::Error::PaymentNotFound.into()) + } + } + + async fn create_incoming_payment_request( + &self, + unit: &CurrencyUnit, + options: IncomingPaymentOptions, + ) -> Result { + let (amount, _expiry) = match options { + IncomingPaymentOptions::Bolt11(ref bolt11_options) => { + (Some(bolt11_options.amount), bolt11_options.unix_expiry) + } + IncomingPaymentOptions::Bolt12(_) => return Err(error::Error::UnsupportedBolt12.into()), + }; + let invoice_id = Uuid::new_v4().to_string(); + let random_hash: [u8; 32] = rand::rng().random(); + let payment_amount = amount.unwrap_or(Amount::ZERO); + // Insert as paid at creation (auto-pay) + self.invoices.lock().await.insert( + random_hash, + (invoice_id.clone(), true, payment_amount, unit.clone()), + ); + + // Notify immediately + let _ = self.sender.send(random_hash).await; + + Ok(CreateIncomingPaymentResponse { + request_lookup_id: PaymentIdentifier::PaymentHash(random_hash), + request: invoice_id.clone(), + expiry: None, + }) + } + + async fn check_incoming_payment_status( + &self, + payment_identifier: &PaymentIdentifier, + ) -> Result, Self::Err> { + let payment_hash = match payment_identifier { + PaymentIdentifier::PaymentHash(hash) => hash, + _ => return Ok(vec![]), + }; + let guard = self.invoices.lock().await; + if let Some((invoice_id, paid, amount, unit)) = guard.get(payment_hash) { + if *paid { + return Ok(vec![WaitPaymentResponse { + payment_identifier: payment_identifier.clone(), + payment_amount: *amount, + unit: unit.clone(), + payment_id: invoice_id.clone(), + }]); + } + } + Ok(vec![]) + } + + async fn check_outgoing_payment( + &self, + payment_identifier: &PaymentIdentifier, + ) -> Result { + let payment_hash = match payment_identifier { + PaymentIdentifier::PaymentHash(hash) => hash, + _ => return Err(error::Error::PaymentNotFound.into()), + }; + let guard = self.invoices.lock().await; + if let Some((invoice_id, paid, amount, unit)) = guard.get(payment_hash) { + let status = if *paid { + MeltQuoteState::Paid + } else { + MeltQuoteState::Unpaid + }; + return Ok(MakePaymentResponse { + payment_lookup_id: payment_identifier.clone(), + payment_proof: Some(invoice_id.clone()), + status, + total_spent: *amount, + unit: unit.clone(), + }); + } + Err(error::Error::PaymentNotFound.into()) + } +} diff --git a/crates/cdk/src/wallet/multi_mint_wallet.rs b/crates/cdk/src/wallet/multi_mint_wallet.rs index 6e3f6eedc..2829276b1 100644 --- a/crates/cdk/src/wallet/multi_mint_wallet.rs +++ b/crates/cdk/src/wallet/multi_mint_wallet.rs @@ -522,12 +522,12 @@ impl MultiMintWallet { /// Get wallet balances for all mints #[instrument(skip(self))] - pub async fn get_balances(&self) -> Result, Error> { + pub async fn get_balances(&self) -> Result, Error> { let mut balances = BTreeMap::new(); for (mint_url, wallet) in self.wallets.read().await.iter() { let wallet_balance = wallet.total_balance().await?; - balances.insert(mint_url.clone(), wallet_balance); + balances.insert(mint_url.clone(), (wallet_balance, wallet.unit.clone())); } Ok(balances) diff --git a/portal-cmds.txt b/portal-cmds.txt new file mode 100644 index 000000000..36e0ce311 --- /dev/null +++ b/portal-cmds.txt @@ -0,0 +1,8 @@ + + +cargo run -p cdk-cli -- --unit casa balance --unit casa + +cargo run -p cdk-cli -- --unit casa mint "http://127.0.0.1:8085" 100 "my real mint" + +cargo run -p cdk-cli -- --unit casa send + From 808de438dc712ccd1410b0bfa9a08767d3bc92d2 Mon Sep 17 00:00:00 2001 From: tsk Date: Mon, 1 Dec 2025 15:47:56 +0000 Subject: [PATCH 315/321] fix: wasm use web_time (#1363) --- crates/cdk/src/wallet/mint_metadata_cache.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/crates/cdk/src/wallet/mint_metadata_cache.rs b/crates/cdk/src/wallet/mint_metadata_cache.rs index 44b5f3307..f27a2b5c6 100644 --- a/crates/cdk/src/wallet/mint_metadata_cache.rs +++ b/crates/cdk/src/wallet/mint_metadata_cache.rs @@ -27,7 +27,7 @@ use std::collections::HashMap; use std::fmt::Debug; use std::sync::Arc; -use std::time::{Duration, Instant}; +use std::time::Duration; use arc_swap::ArcSwap; use cdk_common::database::{self, WalletDatabase}; @@ -36,6 +36,7 @@ use cdk_common::nuts::{KeySetInfo, Keys}; use cdk_common::parking_lot::RwLock; use cdk_common::{KeySet, MintInfo}; use tokio::sync::Mutex; +use web_time::Instant; use crate::nuts::Id; use crate::wallet::MintConnector; From e95e13840c363985f959039e6073ac2acaf00bc1 Mon Sep 17 00:00:00 2001 From: unldenis Date: Mon, 1 Dec 2025 17:33:38 +0100 Subject: [PATCH 316/321] feat: add unit info to the mint --- crates/cdk-axum/Cargo.toml | 2 + crates/cdk-axum/src/lib.rs | 5 +- crates/cdk-axum/src/router_handlers.rs | 38 ++++++++++++ crates/cdk-common/src/common.rs | 11 ++++ crates/cdk-mintd/src/config.rs | 6 ++ .../cdk-mintd/src/env_vars/portal_wallet.rs | 62 +++++++++++++++++++ crates/cdk-mintd/src/lib.rs | 8 +++ crates/cdk/src/mint/builder.rs | 12 ++++ crates/cdk/src/mint/mod.rs | 17 ++++- 9 files changed, 158 insertions(+), 3 deletions(-) diff --git a/crates/cdk-axum/Cargo.toml b/crates/cdk-axum/Cargo.toml index 7ef7e1454..13ee55df3 100644 --- a/crates/cdk-axum/Cargo.toml +++ b/crates/cdk-axum/Cargo.toml @@ -38,5 +38,7 @@ redis = { version = "0.31.0", features = [ "tokio-rustls-comp", ], optional = true } +cdk-common = { workspace = true } + [target.'cfg(target_arch = "wasm32")'.dependencies] uuid = { workspace = true, features = ["js"] } diff --git a/crates/cdk-axum/src/lib.rs b/crates/cdk-axum/src/lib.rs index 3d72986d9..0d0be6b5f 100644 --- a/crates/cdk-axum/src/lib.rs +++ b/crates/cdk-axum/src/lib.rs @@ -306,7 +306,10 @@ pub async fn create_mint_router_with_custom_cache( .route("/melt/bolt11", post(cache_post_melt_bolt11)) .route("/checkstate", post(post_check)) .route("/info", get(get_mint_info)) - .route("/restore", post(post_restore)); + .route("/restore", post(post_restore)) + + .route("/unit/{unit}", get(get_unit_metadata)) + ; let mint_router = Router::new().nest("/v1", v1_router); diff --git a/crates/cdk-axum/src/router_handlers.rs b/crates/cdk-axum/src/router_handlers.rs index 78635a2f6..5316f7b0f 100644 --- a/crates/cdk-axum/src/router_handlers.rs +++ b/crates/cdk-axum/src/router_handlers.rs @@ -23,6 +23,10 @@ use crate::auth::AuthHeader; use crate::ws::main_websocket; use crate::MintState; +use cdk_common::common::UnitMetadata; +use cdk::nuts::CurrencyUnit; +use std::str::FromStr; + const PREFER_HEADER_KEY: &str = "Prefer"; /// Header extractor for the Prefer header @@ -684,3 +688,37 @@ where (status_code, Json(err_response)).into_response() } + + + +#[cfg_attr(feature = "swagger", utoipa::path( + get, + context_path = "/v1", + path = "/unit/{unit}", + params( + ("unit" = String, description = "The unit"), + ), + responses( + (status = 200, description = "Successful response", body = KeysResponse, content_type = "application/json"), + (status = 500, description = "Server error", body = ErrorResponse, content_type = "application/json") + ) +))] +/// Get the metadata of a specific keyset +/// +/// Get the metadata of the mint from a specific keyset ID. +#[instrument(skip_all, fields(unit = ?unit))] +pub(crate) async fn get_unit_metadata( + State(state): State, + Path(unit): Path, +) -> Result, Response> { + let unit = cdk::nuts::nut00::CurrencyUnit::from_str(&unit).map_err(|err| { + tracing::error!("Could not parse unit: {}", err); + into_response(cdk::Error::UnsupportedUnit) + })?; + let metadata = state.mint.get_unit_metadata(unit).ok_or_else(|| { + tracing::error!("Could not get unit metadata"); + into_response(cdk::Error::UnsupportedUnit) + })?; + Ok(Json(metadata)) + +} \ No newline at end of file diff --git a/crates/cdk-common/src/common.rs b/crates/cdk-common/src/common.rs index 59edfffa8..254a8d52b 100644 --- a/crates/cdk-common/src/common.rs +++ b/crates/cdk-common/src/common.rs @@ -193,6 +193,17 @@ impl Default for QuoteTTL { } } +/// Unit Metadata +#[derive(Debug, Default, Clone, Hash, PartialEq, Eq, Serialize, Deserialize)] +pub struct UnitMetadata { + /// Human readable description of the unit + pub description: String, + /// URL for more info + pub url: String, + /// Whether the unit is non-fungible + pub is_non_fungible: bool, +} + #[cfg(test)] mod tests { use std::str::FromStr; diff --git a/crates/cdk-mintd/src/config.rs b/crates/cdk-mintd/src/config.rs index 55a713978..42277dd2a 100644 --- a/crates/cdk-mintd/src/config.rs +++ b/crates/cdk-mintd/src/config.rs @@ -8,6 +8,11 @@ use cdk_common::common::QuoteTTL; use config::{Config, ConfigError, File}; use serde::{Deserialize, Serialize}; +#[cfg(feature = "portalwallet")] +use std::collections::HashMap; +#[cfg(feature = "portalwallet")] +use cdk_common::common::UnitMetadata; + #[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Default)] #[serde(rename_all = "lowercase")] pub enum LoggingOutput { @@ -430,6 +435,7 @@ fn default_grpc_port() -> u16 { #[derive(Debug, Clone, Serialize, Deserialize)] pub struct PortalWallet { pub supported_units: Vec, + pub unit_info: HashMap, } #[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Default)] diff --git a/crates/cdk-mintd/src/env_vars/portal_wallet.rs b/crates/cdk-mintd/src/env_vars/portal_wallet.rs index c75c1b9ff..1b0f4a273 100644 --- a/crates/cdk-mintd/src/env_vars/portal_wallet.rs +++ b/crates/cdk-mintd/src/env_vars/portal_wallet.rs @@ -6,8 +6,47 @@ use cdk::nuts::CurrencyUnit; use crate::config::PortalWallet; +use cdk_common::common::UnitMetadata; + // Fake Wallet environment variables pub const ENV_PORTAL_WALLET_SUPPORTED_UNITS: &str = "CDK_MINTD_PORTAL_WALLET_SUPPORTED_UNITS"; +pub const ENV_PORTAL_WALLET_UNIT_INFO: &str = "CDK_MINTD_PORTAL_WALLET_UNIT_INFO"; + +#[derive(Debug)] +struct UnitInfo { + unit: CurrencyUnit, + description: String, + url: String, + is_non_fungible: bool, +} + +impl core::str::FromStr for UnitInfo { + type Err = String; + + fn from_str(s: &str) -> Result { + let (unit, remaining) = s.split_once('=').ok_or("Invalid format")?; + let mut parts = remaining.split('\n'); + + let description = parts.next().ok_or("Invalid format")?; + let url = parts.next().ok_or("Invalid format")?; + + let is_non_fungible = parts + .next() + .ok_or("Invalid format")? + .parse() + .map_err(|_| "Invalid is_non_fungible")?; + + Ok(Self { + unit: unit.parse().map_err(|_| "Invalid unit")?, + description: description.to_string(), + url: url.to_string(), + is_non_fungible, + }) + + } + + +} impl PortalWallet { pub fn from_env(mut self) -> Self { @@ -22,6 +61,29 @@ impl PortalWallet { } } + // Unit Info - expects comma-separated list + if let Ok(unit_info_str) = env::var(ENV_PORTAL_WALLET_UNIT_INFO) { + if let Ok(unit_info) = unit_info_str + .split(',') + .map(|s| s.parse()) + .collect::, _>>() + { + self.unit_info = unit_info + .into_iter() + .map(|u| { + ( + u.unit, + UnitMetadata { + description: u.description, + url: u.url, + is_non_fungible: u.is_non_fungible, + }, + ) + }) + .collect(); + } + } + self } } diff --git a/crates/cdk-mintd/src/lib.rs b/crates/cdk-mintd/src/lib.rs index 2b2c34fd8..251b5065b 100644 --- a/crates/cdk-mintd/src/lib.rs +++ b/crates/cdk-mintd/src/lib.rs @@ -573,7 +573,15 @@ async fn configure_lightning_backend( Arc::new(portal), ) .await?; + + + if let Some(unit_metadata) = portal_wallet.unit_info.get(&unit) { + mint_builder = mint_builder.set_unit_metadata(&unit, unit_metadata.clone()); + } } + + + } LnBackend::None => { tracing::error!( diff --git a/crates/cdk/src/mint/builder.rs b/crates/cdk/src/mint/builder.rs index a848c80a5..b48d265fe 100644 --- a/crates/cdk/src/mint/builder.rs +++ b/crates/cdk/src/mint/builder.rs @@ -4,6 +4,7 @@ use std::collections::HashMap; use std::sync::Arc; use bitcoin::bip32::DerivationPath; +use cdk_common::common::UnitMetadata; use cdk_common::database::{DynMintDatabase, MintKeysDatabase}; use cdk_common::error::Error; use cdk_common::nut04::MintMethodOptions; @@ -36,6 +37,7 @@ pub struct MintBuilder { payment_processors: HashMap, supported_units: HashMap, custom_paths: HashMap, + keys_metadata: HashMap, } impl MintBuilder { @@ -62,6 +64,7 @@ impl MintBuilder { payment_processors: HashMap::new(), supported_units: HashMap::new(), custom_paths: HashMap::new(), + keys_metadata: HashMap::new(), } } @@ -312,6 +315,13 @@ impl MintBuilder { Ok(()) } + /// Set unit metadata + pub fn set_unit_metadata(mut self, unit: &CurrencyUnit, metadata: UnitMetadata) -> Self { + self.keys_metadata.insert(unit.clone(), metadata); + self + } + + /// Build the mint with the provided signatory pub async fn build_with_signatory( self, @@ -325,6 +335,7 @@ impl MintBuilder { self.localstore, auth_localstore, self.payment_processors, + self.keys_metadata, ) .await; } @@ -333,6 +344,7 @@ impl MintBuilder { signatory, self.localstore, self.payment_processors, + self.keys_metadata, ) .await } diff --git a/crates/cdk/src/mint/mod.rs b/crates/cdk/src/mint/mod.rs index 63671960e..0f7e801d5 100644 --- a/crates/cdk/src/mint/mod.rs +++ b/crates/cdk/src/mint/mod.rs @@ -6,7 +6,7 @@ use std::time::Duration; use arc_swap::ArcSwap; use cdk_common::amount::to_unit; -use cdk_common::common::{PaymentProcessorKey, QuoteTTL}; +use cdk_common::common::{PaymentProcessorKey, QuoteTTL, UnitMetadata}; #[cfg(feature = "auth")] use cdk_common::database::DynMintAuthDatabase; use cdk_common::database::{self, DynMintDatabase}; @@ -76,6 +76,7 @@ pub struct Mint { keysets: Arc>>, /// Background task management task_state: Arc>, + keys_metadata: Arc>, } /// State for managing background tasks @@ -94,6 +95,7 @@ impl Mint { signatory: Arc, localstore: DynMintDatabase, payment_processors: HashMap, + keys_metadata: HashMap, ) -> Result { Self::new_internal( mint_info, @@ -102,6 +104,7 @@ impl Mint { #[cfg(feature = "auth")] None, payment_processors, + keys_metadata, ) .await } @@ -114,6 +117,7 @@ impl Mint { localstore: DynMintDatabase, auth_localstore: DynMintAuthDatabase, payment_processors: HashMap, + keys_metadata: HashMap, ) -> Result { Self::new_internal( mint_info, @@ -121,6 +125,7 @@ impl Mint { localstore, Some(auth_localstore), payment_processors, + keys_metadata, ) .await } @@ -133,6 +138,7 @@ impl Mint { localstore: DynMintDatabase, #[cfg(feature = "auth")] auth_localstore: Option, payment_processors: HashMap, + keys_metadata: HashMap, ) -> Result { let keysets = signatory.keysets().await?; if !keysets @@ -219,6 +225,7 @@ impl Mint { auth_localstore, keysets: Arc::new(ArcSwap::new(keysets.keysets.into())), task_state: Arc::new(Mutex::new(TaskState::default())), + keys_metadata: Arc::new(keys_metadata), }) } @@ -972,6 +979,12 @@ impl Mint { total_redeemed } + + /// Get unit metadata + pub fn get_unit_metadata(&self, unit: CurrencyUnit) -> Option { + self.keys_metadata.get(&unit).cloned() + } + } #[cfg(test)] @@ -1022,7 +1035,7 @@ mod tests { .expect("Failed to create signatory"), ); - Mint::new(MintInfo::default(), signatory, localstore, HashMap::new()) + Mint::new(MintInfo::default(), signatory, localstore, HashMap::new(), HashMap::new()) .await .unwrap() } From 94e2adb20e1425af9e0cdbf50a7ba77e83c4e27e Mon Sep 17 00:00:00 2001 From: C Date: Mon, 1 Dec 2025 18:32:46 -0300 Subject: [PATCH 317/321] Fix connection pool resource initialization and path validation (#1367) Fixes two issues in SQLite connection handling: **Connection Pool Resource Initialization:** - Move resource creation before incrementing connection counter in pool.rs - Ensures counter is only incremented after successful resource creation - Prevents counter increment on resource creation failure - Fixes potential resource leak where counter could be incremented without a valid resource **Path Validation:** - Add empty string check before parent directory existence validation - Allows relative paths like "test.db" to work correctly - Prevents false negative errors for valid relative database paths - Only validates parent directory existence for non-empty paths **Test Coverage:** - Add test case `bug_opening_relative_path()` to verify relative path handling - Ensures databases can be created with simple filenames like "test.db" These changes fix issues where: 1. Connection pool counter could become inconsistent with actual connections 2. Relative database paths were incorrectly rejected --- crates/cdk-sql-common/src/pool.rs | 8 +++----- crates/cdk-sqlite/src/common.rs | 2 +- crates/cdk-sqlite/src/mint/mod.rs | 10 ++++++++++ 3 files changed, 14 insertions(+), 6 deletions(-) diff --git a/crates/cdk-sql-common/src/pool.rs b/crates/cdk-sql-common/src/pool.rs index 9315a081b..451772697 100644 --- a/crates/cdk-sql-common/src/pool.rs +++ b/crates/cdk-sql-common/src/pool.rs @@ -208,14 +208,12 @@ where if self.in_use.load(Ordering::Relaxed) < self.max_size { drop(resources); - self.increment_connection_counter(); let stale: Arc = Arc::new(false.into()); + let new_resource = RM::new_resource(&self.config, stale.clone(), timeout)?; + self.increment_connection_counter(); return Ok(PooledResource { - resource: Some(( - stale.clone(), - RM::new_resource(&self.config, stale, timeout)?, - )), + resource: Some((stale, new_resource)), pool: self.clone(), #[cfg(feature = "prometheus")] start_time: Instant::now(), diff --git a/crates/cdk-sqlite/src/common.rs b/crates/cdk-sqlite/src/common.rs index 178f554ef..6b0681ceb 100644 --- a/crates/cdk-sqlite/src/common.rs +++ b/crates/cdk-sqlite/src/common.rs @@ -50,7 +50,7 @@ impl DatabasePool for SqliteConnectionManager { // Check if parent directory exists before attempting to open database let path_buf = PathBuf::from(path); if let Some(parent) = path_buf.parent() { - if !parent.exists() { + if !parent.to_str().unwrap_or_default().is_empty() && !parent.exists() { return Err(pool::Error::Resource(rusqlite::Error::InvalidPath( path_buf.clone(), ))); diff --git a/crates/cdk-sqlite/src/mint/mod.rs b/crates/cdk-sqlite/src/mint/mod.rs index f95bd78fa..df0157ee6 100644 --- a/crates/cdk-sqlite/src/mint/mod.rs +++ b/crates/cdk-sqlite/src/mint/mod.rs @@ -31,6 +31,16 @@ mod test { mint_db_test!(provide_db); + #[tokio::test] + async fn bug_opening_relative_path() { + let config: Config = "test.db".into(); + + let pool = Pool::::new(config); + let db = pool.get(); + assert!(db.is_ok()); + let _ = remove_file("test.db"); + } + #[tokio::test] async fn open_legacy_and_migrate() { let file = format!( From 6e4ec9116f51f78a8ff140d1a3bd990fb578d2d8 Mon Sep 17 00:00:00 2001 From: C Date: Mon, 1 Dec 2025 18:33:44 -0300 Subject: [PATCH 318/321] Add Python wallet test suite with CI integration (#1362) * Add Python wallet test suite with CI integration Adds comprehensive Python test suite for CDK FFI wallet database operations with full CI/CD integration. Test Infrastructure: - Add 6 wallet operation tests covering core functionality: - Wallet creation with SQLite backend - Mint management (add/query/retrieve) - Keyset management (add/query by ID or mint) - Keyset counter operations (increment/read) - Quote operations (mint/melt queries) - Proof retrieval by Y values - Automatic path resolution and library loading from target/ directories - Isolated test execution with temporary SQLite databases - Proper cleanup with try/finally blocks Build Integration: - Add `just ffi-test` command for convenient test execution - Automatically generates Python bindings before running tests - Clear output with test progress and results summary CI Integration: - Add `ffi-tests` job to GitHub Actions workflow - Runs after pre-commit-checks with 30-minute timeout - Ubuntu runner with Python 3.11 - Nix development environment with caching - Rust cache for faster builds --- .github/workflows/ci.yml | 93 ++++--- crates/cdk-ffi/tests/README.md | 112 +++++++++ crates/cdk-ffi/tests/test_transactions.py | 280 ++++++++++++++++++++++ flake.nix | 1 + justfile | 8 + 5 files changed, 442 insertions(+), 52 deletions(-) create mode 100644 crates/cdk-ffi/tests/README.md create mode 100755 crates/cdk-ffi/tests/test_transactions.py diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 7a99299ea..bf915677d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -6,7 +6,7 @@ on: pull_request: branches: - main - - 'v[0-9]*.[0-9]*.x' # Match version branches like v0.13.x, v1.0.x, etc. + - "v[0-9]*.[0-9]*.x" # Match version branches like v0.13.x, v1.0.x, etc. release: types: [created] @@ -48,14 +48,7 @@ jobs: strategy: fail-fast: true matrix: - build-args: - [ - mint-token, - melt-token, - p2pk, - proof-selection, - wallet - ] + build-args: [mint-token, melt-token, p2pk, proof-selection, wallet] steps: - name: checkout uses: actions/checkout@v4 @@ -84,8 +77,7 @@ jobs: strategy: fail-fast: true matrix: - build-args: - [ + build-args: [ # Core crate testing -p cashu, -p cashu --no-default-features, @@ -105,18 +97,18 @@ jobs: -p cdk-sql-common, -p cdk-sql-common --no-default-features --features wallet, -p cdk-sql-common --no-default-features --features mint, - + # Database and infrastructure crates -p cdk-redb, -p cdk-sqlite, -p cdk-sqlite --features sqlcipher, - + # HTTP/API layer - consolidated -p cdk-axum, -p cdk-axum --no-default-features, -p cdk-axum --no-default-features --features redis, -p cdk-axum --no-default-features --features "redis swagger", - + # Lightning backends -p cdk-cln, -p cdk-lnd, @@ -124,12 +116,12 @@ jobs: -p cdk-fake-wallet, -p cdk-payment-processor, -p cdk-ldk-node, - + -p cdk-signatory, -p cdk-mint-rpc, -p cdk-prometheus, - + # FFI bindings -p cdk-ffi, -p cdk-ffi --no-default-features, @@ -187,15 +179,8 @@ jobs: strategy: fail-fast: true matrix: - build-args: - [ - -p cdk-integration-tests, - ] - database: - [ - SQLITE, - POSTGRES - ] + build-args: [-p cdk-integration-tests] + database: [SQLITE, POSTGRES] steps: - name: checkout uses: actions/checkout@v4 @@ -234,14 +219,8 @@ jobs: strategy: fail-fast: true matrix: - build-args: - [ - -p cdk-integration-tests, - ] - database: - [ - SQLITE, - ] + build-args: [-p cdk-integration-tests] + database: [SQLITE] steps: - name: checkout uses: actions/checkout@v4 @@ -282,12 +261,7 @@ jobs: strategy: fail-fast: true matrix: - database: - [ - memory, - sqlite, - redb - ] + database: [memory, sqlite, redb] steps: - name: checkout uses: actions/checkout@v4 @@ -322,7 +296,6 @@ jobs: - name: Test mint run: nix develop -i -L .#stable --command just test - payment-processor-itests: name: "Payment processor tests" runs-on: ubuntu-latest @@ -331,12 +304,7 @@ jobs: strategy: fail-fast: true matrix: - ln: - [ - FAKEWALLET, - CLN, - LND - ] + ln: [FAKEWALLET, CLN, LND] steps: - name: checkout uses: actions/checkout@v4 @@ -375,8 +343,7 @@ jobs: strategy: fail-fast: true matrix: - build-args: - [ + build-args: [ # Core library - all features EXCEPT swagger (which breaks MSRV) '-p cdk --features "mint,wallet,auth,nostr,bip353,tor,prometheus"', @@ -456,10 +423,7 @@ jobs: strategy: fail-fast: true matrix: - database: - [ - SQLITE, - ] + database: [SQLITE] steps: - name: checkout uses: actions/checkout@v4 @@ -537,3 +501,28 @@ jobs: run: nix develop -i -L .#stable --command cargo test --doc - name: Check docs with strict warnings run: nix develop -i -L .#stable --command just docs-strict + + ffi-tests: + name: "FFI Python tests" + runs-on: ubuntu-latest + timeout-minutes: 30 + needs: pre-commit-checks + steps: + - name: checkout + uses: actions/checkout@v4 + - name: Get flake hash + id: flake-hash + run: echo "hash=$(sha256sum flake.lock | cut -d' ' -f1 | cut -c1-8)" >> $GITHUB_OUTPUT + - name: Install Nix + uses: DeterminateSystems/nix-installer-action@v17 + - name: Nix Cache + uses: DeterminateSystems/magic-nix-cache-action@main + with: + diagnostic-endpoint: "" + use-flakehub: false + - name: Rust Cache + uses: Swatinem/rust-cache@v2 + with: + shared-key: "stable-${{ steps.flake-hash.outputs.hash }}" + - name: Run FFI tests + run: nix develop -i -L .#integration --command just ffi-test diff --git a/crates/cdk-ffi/tests/README.md b/crates/cdk-ffi/tests/README.md new file mode 100644 index 000000000..3db2c66df --- /dev/null +++ b/crates/cdk-ffi/tests/README.md @@ -0,0 +1,112 @@ +# CDK FFI Python Tests + +This directory contains Python tests for the CDK FFI (Foreign Function Interface) bindings, focusing on wallet database operations. + +## Running the Tests + +### Quick Start + +The easiest way to run all tests: + +```bash +# From the repository root +just ffi-test +``` + +This command will automatically: +1. Build the FFI bindings (if needed) +2. Run all Python tests +3. Report results + +Or run directly (assumes bindings are already built): + +```bash +# From the repository root +python3 crates/cdk-ffi/tests/test_transactions.py +``` + +### Prerequisites + +**Python 3.7+** is required. The `just ffi-test` command handles everything else automatically. + +## How It Works + +The test script automatically: +1. Locates the bindings in `target/bindings/python/` +2. Copies the shared library from `target/release/` to the bindings directory +3. Runs all wallet tests + +**No manual file copying required!** + +## Test Suite + +### Wallet Tests (test_transactions.py) + +Comprehensive tests for wallet database operations: + +1. **Wallet Creation** - Tests creating a wallet with SQLite backend +2. **Wallet Mint Management** - Tests adding and querying mints +3. **Wallet Keyset Management** - Tests adding and querying keysets +4. **Wallet Keyset Counter** - Tests keyset counter increment operations +5. **Wallet Quote Operations** - Tests querying mint and melt quotes +6. **Wallet Get Proofs by Y Values** - Tests retrieving proofs by Y values + +### Key Features Tested + +- ✅ **Wallet creation** - SQLite backend initialization +- ✅ **Mint management** - Add, query, and retrieve mint URLs +- ✅ **Keyset operations** - Add keysets and query by ID or mint +- ✅ **Counter operations** - Keyset counter increment/read +- ✅ **Quote queries** - Retrieve mint and melt quotes +- ✅ **Proof retrieval** - Get proofs by Y values +- ✅ **Foreign key constraints** - Proper referential integrity + +## Test Output + +Expected output for successful run: + +``` +Starting CDK FFI Wallet Tests +================================================== +... (test execution) ... +================================================== +Test Results: 6 passed, 0 failed +================================================== +``` + +## Troubleshooting + +### Import Errors + +If you see `ModuleNotFoundError: No module named 'cdk_ffi'`: +- Ensure FFI bindings are generated: `just ffi-generate python` +- Check that `target/bindings/python/cdk_ffi.py` exists + +### Library Not Found + +If you see errors about missing `.dylib` or `.so` files: +- Build the release version: `cargo build --release -p cdk-ffi` +- Check that the library exists in `target/release/` + +### Test Failures + +If tests fail: +- Ensure you're running from the repository root +- Check that the FFI bindings match the current code version +- Try rebuilding: `just ffi-generate python && cargo build --release -p cdk-ffi` + +## Development + +When adding new tests: + +1. Add test function with `async def test_*()` signature +2. Add test to the `tests` list in `main()` +3. Use temporary databases for isolation +4. Follow existing patterns for setup/teardown + +## Implementation Notes + +- All tests use temporary SQLite databases +- Each test is fully isolated with its own database +- Tests clean up automatically via `finally` blocks +- The script handles path resolution and library loading automatically diff --git a/crates/cdk-ffi/tests/test_transactions.py b/crates/cdk-ffi/tests/test_transactions.py new file mode 100755 index 000000000..00160d9b5 --- /dev/null +++ b/crates/cdk-ffi/tests/test_transactions.py @@ -0,0 +1,280 @@ +#!/usr/bin/env python3 +""" +Test suite for CDK FFI wallet operations +""" + +import asyncio +import os +import sys +import tempfile +from pathlib import Path + +# Setup paths before importing cdk_ffi +repo_root = Path(__file__).parent.parent.parent.parent +bindings_path = repo_root / "target" / "bindings" / "python" +lib_path = repo_root / "target" / "release" + +# Copy the library to the bindings directory so Python can find it +import shutil +lib_file = "libcdk_ffi.dylib" if sys.platform == "darwin" else "libcdk_ffi.so" +src_lib = lib_path / lib_file +dst_lib = bindings_path / lib_file + +if src_lib.exists() and not dst_lib.exists(): + shutil.copy2(src_lib, dst_lib) + +# Add target/bindings/python to path to load cdk_ffi module +sys.path.insert(0, str(bindings_path)) + +import cdk_ffi + + +async def test_wallet_creation(): + """Test creating a wallet with SQLite backend""" + print("\n=== Test: Wallet Creation ===") + + with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as tmp: + db_path = tmp.name + + try: + backend = cdk_ffi.WalletDbBackend.SQLITE(path=db_path) + db = cdk_ffi.create_wallet_db(backend) + print("✓ Wallet database created") + + # Verify database is accessible by querying quotes + mint_quotes = await db.get_mint_quotes() + assert isinstance(mint_quotes, list), "get_mint_quotes should return a list" + print("✓ Wallet database accessible") + + print("✓ Test passed: Wallet creation works") + + finally: + if os.path.exists(db_path): + os.unlink(db_path) + + +async def test_wallet_mint_management(): + """Test adding and querying mints""" + print("\n=== Test: Wallet Mint Management ===") + + with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as tmp: + db_path = tmp.name + + try: + backend = cdk_ffi.WalletDbBackend.SQLITE(path=db_path) + db = cdk_ffi.create_wallet_db(backend) + + mint_url = cdk_ffi.MintUrl(url="https://testmint.example.com") + + # Add mint + await db.add_mint(mint_url, None) + print("✓ Added mint to wallet") + + # Get specific mint (verifies it was added) + await db.get_mint(mint_url) + print("✓ Retrieved mint from database") + + # Remove mint + await db.remove_mint(mint_url) + print("✓ Removed mint from wallet") + + # Verify removal + mint_info_after = await db.get_mint(mint_url) + assert mint_info_after is None, "Mint should be removed" + print("✓ Verified mint removal") + + print("✓ Test passed: Mint management works") + + finally: + if os.path.exists(db_path): + os.unlink(db_path) + + +async def test_wallet_keyset_management(): + """Test adding and querying keysets""" + print("\n=== Test: Wallet Keyset Management ===") + + with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as tmp: + db_path = tmp.name + + try: + backend = cdk_ffi.WalletDbBackend.SQLITE(path=db_path) + db = cdk_ffi.create_wallet_db(backend) + + mint_url = cdk_ffi.MintUrl(url="https://testmint.example.com") + keyset_id = cdk_ffi.Id(hex="004146bdf4a9afab") + + # Add mint first (foreign key requirement) + await db.add_mint(mint_url, None) + print("✓ Added mint") + + # Add keyset + keyset_info = cdk_ffi.KeySetInfo( + id=keyset_id.hex, + unit=cdk_ffi.CurrencyUnit.SAT(), + active=True, + input_fee_ppk=0 + ) + await db.add_mint_keysets(mint_url, [keyset_info]) + print("✓ Added keyset") + + # Query keyset by ID + keyset = await db.get_keyset_by_id(keyset_id) + assert keyset is not None, "Keyset should exist" + assert keyset.id == keyset_id.hex, "Keyset ID should match" + print(f"✓ Retrieved keyset: {keyset.id}") + + # Query keysets for mint + keysets = await db.get_mint_keysets(mint_url) + assert keysets is not None and len(keysets) > 0, "Should have keysets for mint" + print(f"✓ Retrieved {len(keysets)} keyset(s) for mint") + + print("✓ Test passed: Keyset management works") + + finally: + if os.path.exists(db_path): + os.unlink(db_path) + + +async def test_wallet_keyset_counter(): + """Test keyset counter operations""" + print("\n=== Test: Wallet Keyset Counter ===") + + with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as tmp: + db_path = tmp.name + + try: + backend = cdk_ffi.WalletDbBackend.SQLITE(path=db_path) + db = cdk_ffi.create_wallet_db(backend) + + mint_url = cdk_ffi.MintUrl(url="https://testmint.example.com") + keyset_id = cdk_ffi.Id(hex="004146bdf4a9afab") + + # Setup mint and keyset + await db.add_mint(mint_url, None) + keyset_info = cdk_ffi.KeySetInfo( + id=keyset_id.hex, + unit=cdk_ffi.CurrencyUnit.SAT(), + active=True, + input_fee_ppk=0 + ) + await db.add_mint_keysets(mint_url, [keyset_info]) + print("✓ Setup complete") + + # Increment counter + counter1 = await db.increment_keyset_counter(keyset_id, 1) + print(f"✓ Counter after +1: {counter1}") + assert counter1 == 1, f"Expected counter 1, got {counter1}" + + # Increment again + counter2 = await db.increment_keyset_counter(keyset_id, 5) + print(f"✓ Counter after +5: {counter2}") + assert counter2 == 6, f"Expected counter 6, got {counter2}" + + # Read current value (increment by 0) + counter3 = await db.increment_keyset_counter(keyset_id, 0) + print(f"✓ Current counter: {counter3}") + assert counter3 == 6, f"Expected counter 6, got {counter3}" + + print("✓ Test passed: Keyset counter works") + + finally: + if os.path.exists(db_path): + os.unlink(db_path) + + +async def test_wallet_quotes(): + """Test mint and melt quote operations""" + print("\n=== Test: Wallet Quote Operations ===") + + with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as tmp: + db_path = tmp.name + + try: + backend = cdk_ffi.WalletDbBackend.SQLITE(path=db_path) + db = cdk_ffi.create_wallet_db(backend) + + mint_url = cdk_ffi.MintUrl(url="https://testmint.example.com") + + # Add mint first + await db.add_mint(mint_url, None) + print("✓ Added mint") + + # Query mint quotes (should be empty initially) + mint_quotes = await db.get_mint_quotes() + assert isinstance(mint_quotes, list), "get_mint_quotes should return a list" + print(f"✓ Retrieved {len(mint_quotes)} mint quote(s)") + + # Query melt quotes (should be empty initially) + melt_quotes = await db.get_melt_quotes() + assert isinstance(melt_quotes, list), "get_melt_quotes should return a list" + print(f"✓ Retrieved {len(melt_quotes)} melt quote(s)") + + print("✓ Test passed: Quote operations work") + + finally: + if os.path.exists(db_path): + os.unlink(db_path) + + +async def test_wallet_proofs_by_ys(): + """Test retrieving proofs by Y values""" + print("\n=== Test: Wallet Get Proofs by Y Values ===") + + with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as tmp: + db_path = tmp.name + + try: + backend = cdk_ffi.WalletDbBackend.SQLITE(path=db_path) + db = cdk_ffi.create_wallet_db(backend) + + # Test with empty list + proofs = await db.get_proofs_by_ys([]) + assert len(proofs) == 0, f"Expected 0 proofs, got {len(proofs)}" + print("✓ get_proofs_by_ys returns empty for empty input") + + print("✓ Test passed: get_proofs_by_ys works") + + finally: + if os.path.exists(db_path): + os.unlink(db_path) + + +async def main(): + """Run all tests""" + print("Starting CDK FFI Wallet Tests") + print("=" * 50) + + tests = [ + ("Wallet Creation", test_wallet_creation), + ("Wallet Mint Management", test_wallet_mint_management), + ("Wallet Keyset Management", test_wallet_keyset_management), + ("Wallet Keyset Counter", test_wallet_keyset_counter), + ("Wallet Quote Operations", test_wallet_quotes), + ("Wallet Get Proofs by Y Values", test_wallet_proofs_by_ys), + ] + + passed = 0 + failed = 0 + + for test_name, test_func in tests: + try: + await test_func() + passed += 1 + except Exception as e: + failed += 1 + print(f"\n✗ Test failed: {test_name}") + print(f"Error: {e}") + import traceback + traceback.print_exc() + + print("\n" + "=" * 50) + print(f"Test Results: {passed} passed, {failed} failed") + print("=" * 50) + + return 0 if failed == 0 else 1 + + +if __name__ == "__main__": + exit_code = asyncio.run(main()) + sys.exit(exit_code) diff --git a/flake.nix b/flake.nix index 38c7a2be2..346d0e3af 100644 --- a/flake.nix +++ b/flake.nix @@ -236,6 +236,7 @@ buildInputs = buildInputs ++ [ stable_toolchain pkgs.docker-client + pkgs.python311 ]; inherit nativeBuildInputs; } diff --git a/justfile b/justfile index ba74dfeb9..f350b924f 100644 --- a/justfile +++ b/justfile @@ -577,6 +577,14 @@ ffi-generate-all *ARGS="--release": ffi-build just ffi-generate kotlin {{ARGS}} @echo "✅ All bindings generated successfully!" +# Run Python FFI tests +ffi-test: ffi-generate-python + #!/usr/bin/env bash + set -euo pipefail + echo "🧪 Running Python FFI tests..." + python3 crates/cdk-ffi/tests/test_transactions.py + echo "✅ Tests completed!" + # Build debug version and generate Python bindings quickly (for development) ffi-dev-python: #!/usr/bin/env bash From 927df472daab944187ed4eb9387c6c2cabc46f04 Mon Sep 17 00:00:00 2001 From: tsk Date: Tue, 2 Dec 2025 10:09:58 +0000 Subject: [PATCH 319/321] feat(cdk): add get_token_data and get_mint_keysets to MultiMintWallet (#1361) * feat(cdk): add get_token_data and get_mint_keysets to MultiMintWallet Add methods to extract token data (mint URL, proofs, memo) and retrieve keysets for a specific mint. Includes FFI bindings and example usage --- crates/cdk-ffi/src/multi_mint_wallet.rs | 45 +++++- crates/cdk-ffi/src/token.rs | 9 +- crates/cdk/Cargo.toml | 4 + crates/cdk/examples/token-proofs.rs | 96 ++++++++++++ crates/cdk/src/wallet/multi_mint_wallet.rs | 162 ++++++++++++++++++++- 5 files changed, 313 insertions(+), 3 deletions(-) create mode 100644 crates/cdk/examples/token-proofs.rs diff --git a/crates/cdk-ffi/src/multi_mint_wallet.rs b/crates/cdk-ffi/src/multi_mint_wallet.rs index b2f34ebd2..fbeb65631 100644 --- a/crates/cdk-ffi/src/multi_mint_wallet.rs +++ b/crates/cdk-ffi/src/multi_mint_wallet.rs @@ -8,7 +8,8 @@ use bip39::Mnemonic; use cdk::wallet::multi_mint_wallet::{ MultiMintReceiveOptions as CdkMultiMintReceiveOptions, MultiMintSendOptions as CdkMultiMintSendOptions, MultiMintWallet as CdkMultiMintWallet, - TransferMode as CdkTransferMode, TransferResult as CdkTransferResult, + TokenData as CdkTokenData, TransferMode as CdkTransferMode, + TransferResult as CdkTransferResult, }; use crate::error::FfiError; @@ -199,6 +200,27 @@ impl MultiMintWallet { } } + pub async fn get_mint_keysets(&self, mint_url: MintUrl) -> Result, FfiError> { + let cdk_mint_url: cdk::mint_url::MintUrl = mint_url.try_into()?; + let keysets = self.inner.get_mint_keysets(&cdk_mint_url).await?; + + let keysets = keysets.into_iter().map(|k| k.into()).collect(); + + Ok(keysets) + } + + /// Get token data (mint URL and proofs) from a token + /// + /// This method extracts the mint URL and proofs from a token. It will automatically + /// fetch the keysets from the mint if needed to properly decode the proofs. + /// + /// The mint must already be added to the wallet. If the mint is not in the wallet, + /// use `add_mint` first. + pub async fn get_token_data(&self, token: Arc) -> Result { + let token_data = self.inner.get_token_data(&token.inner).await?; + Ok(token_data.into()) + } + /// Get wallet balances for all mints pub async fn get_balances(&self) -> Result { let balances = self.inner.get_balances().await?; @@ -720,6 +742,27 @@ impl From for TransferResult { } } +/// Data extracted from a token including mint URL, proofs, and memo +#[derive(Debug, Clone, uniffi::Record)] +pub struct TokenData { + /// The mint URL from the token + pub mint_url: MintUrl, + /// The proofs contained in the token + pub proofs: Proofs, + /// The memo from the token, if present + pub memo: Option, +} + +impl From for TokenData { + fn from(data: CdkTokenData) -> Self { + Self { + mint_url: data.mint_url.into(), + proofs: data.proofs.into_iter().map(|p| p.into()).collect(), + memo: data.memo, + } + } +} + /// Options for receiving tokens in multi-mint context #[derive(Debug, Clone, Default, uniffi::Record)] pub struct MultiMintReceiveOptions { diff --git a/crates/cdk-ffi/src/token.rs b/crates/cdk-ffi/src/token.rs index cce6ac7bb..a5c96f4e5 100644 --- a/crates/cdk-ffi/src/token.rs +++ b/crates/cdk-ffi/src/token.rs @@ -4,7 +4,7 @@ use std::collections::BTreeSet; use std::str::FromStr; use crate::error::FfiError; -use crate::{Amount, CurrencyUnit, MintUrl, Proofs}; +use crate::{Amount, CurrencyUnit, KeySetInfo, MintUrl, Proofs}; /// FFI-compatible Token #[derive(Debug, uniffi::Object)] @@ -78,6 +78,13 @@ impl Token { Ok(proofs.into_iter().map(|p| p.into()).collect()) } + /// Get proofs from the token + pub fn proofs(&self, mint_keysets: Vec) -> Result { + let mint_keysets: Vec<_> = mint_keysets.into_iter().map(|k| k.into()).collect(); + let proofs = self.inner.proofs(&mint_keysets)?; + Ok(proofs.into_iter().map(|p| p.into()).collect()) + } + /// Convert token to raw bytes pub fn to_raw_bytes(&self) -> Result, FfiError> { Ok(self.inner.to_raw_bytes()?) diff --git a/crates/cdk/Cargo.toml b/crates/cdk/Cargo.toml index c8a8d09e5..44c0bda5c 100644 --- a/crates/cdk/Cargo.toml +++ b/crates/cdk/Cargo.toml @@ -142,6 +142,10 @@ required-features = ["wallet"] name = "human_readable_payment" required-features = ["wallet", "bip353"] +[[example]] +name = "token-proofs" +required-features = ["wallet"] + [dev-dependencies] rand.workspace = true cdk-sqlite.workspace = true diff --git a/crates/cdk/examples/token-proofs.rs b/crates/cdk/examples/token-proofs.rs new file mode 100644 index 000000000..7ea1de5c7 --- /dev/null +++ b/crates/cdk/examples/token-proofs.rs @@ -0,0 +1,96 @@ +//! Example: Decoding a token and getting proofs using MultiMintWallet +//! +//! This example demonstrates how to: +//! 1. Create a MultiMintWallet +//! 2. Decode a cashu token +//! 3. Use `get_token_data` to extract mint URL and proofs in one call +//! 4. Alternatively, get keysets manually and extract proofs + +use std::str::FromStr; +use std::sync::Arc; + +use cdk::nuts::nut00::ProofsMethods; +use cdk::nuts::{CurrencyUnit, Token}; +use cdk::wallet::MultiMintWallet; +use cdk_sqlite::wallet::memory; +use rand::random; + +#[tokio::main] +async fn main() -> Result<(), Box> { + // Generate a random seed for the wallet + let seed = random::<[u8; 64]>(); + + // Initialize the memory store + let localstore = Arc::new(memory::empty().await?); + + // Create a new multi-mint wallet for satoshis + let wallet = MultiMintWallet::new(localstore, seed, CurrencyUnit::Sat).await?; + + // Example: A cashu token string (in practice, this would come from user input) + let token = Token::from_str("cashuBo2FteB1odHRwczovL2Zha2UudGhlc2ltcGxla2lkLmRldmF1Y3NhdGF0gaJhaUgAlNWndMQKMmFwg6RhYRkIAGFzeEAwYjk0ZjU5ZjU0OTBkNTkzMzI4ZTIwNDllZTNlZmFjYjM5NzljZjU5NzA5ZTM3N2U5YzBmMDQyNDBmZTUyZTVhYWNYIQNGQCYyf1j996pS-LuP_7VsUE-uzRpAm-K4rZiDEFFc1GFko2FlWCBbuMkhvz39ytCzm7xPaY5vdTbqxlxTzXOsks_8S3sf1GFzWCBg22l0CXH5-QLcfJtUJZ2lfylNfC6_o9FTfKClLzthaGFyWCCP2nJ6Qzd8mwLa_85cu8TrwRIprElVgrhqJeoHJwXmSKRhYRkCAGFzeEBhNmMyODliMjMwMTdlMDhjYTFhOTc4ZjAwNGRiNjI4ZDk1NWI5ZTlmNjMwMjY0MjNjZDc4OGExNDBhOWJiYjgxYWNYIQPMXkT68L8Y0a6royMbkoUTbvxOUgsyDwvRZRNTvwUsWWFko2FlWCCj9BFXexBOrlUyUiY_1qEIEHvd1YphWA2l3YhdFwVRh2FzWCBTNgyGeXvGSFtvYKj3MnJCXA8qjI9fzZHFsIw-F_OAGmFyWCDRHiDbVysUuQZucifYx5zMvOKyVIz7zvcJcfd01FoI3KRhYQhhc3hAMWJjOWQ1MjE5ZTZhYzNjZmZhNTM0NTRkY2JjMzE1YzZjZjY5MmM5MDEzYTUzYTA1YzIzN2YwZTBiOTViZTkwMWFjWCEDXd5sxFgxYgUHctpLENYStcr50UtJ4QRojy0g7mkdvWRhZKNhZVggZzSifCUG692E2sW4L6DT_FuKwLZdUFoMnds3tQyMlAdhc1ggtIo0BS2-6arws5fJx_w0phOiCZZcHIFknlrDXSh3C0NhclggM2dDF0kQyuRoOqrOOMHFrmNnvtGiXWxuvqtD7HidR8I")?; + + // Get the mint URL from the token + let mint_url = token.mint_url()?; + println!("Token mint URL: {}", mint_url); + + // Get token value + let value = token.value()?; + println!("Token value: {} sats", value); + + // Get token memo if present + if let Some(memo) = token.memo() { + println!("Token memo: {}", memo); + } + + // Add the mint to our wallet so we can fetch keysets + wallet.add_mint(mint_url.clone()).await?; + + // ========================================================================= + // Method 1: Use get_token_data() for a simple one-call approach + // ========================================================================= + println!("\n--- Using get_token_data() ---"); + + let token_data = wallet.get_token_data(&token).await?; + println!("Mint URL: {}", token_data.mint_url); + println!("Number of proofs: {}", token_data.proofs.len()); + + for (i, proof) in token_data.proofs.iter().enumerate() { + println!( + " Proof {}: {} sats, keyset: {}", + i + 1, + proof.amount, + proof.keyset_id + ); + } + + // ========================================================================= + // Method 2: Manual approach - get keysets first, then extract proofs + // ========================================================================= + println!("\n--- Using manual keyset lookup ---"); + + // Get the keysets for this mint + let keysets = wallet.get_mint_keysets(&mint_url).await?; + println!("Found {} keysets for mint", keysets.len()); + + for keyset in &keysets { + println!( + " - Keyset ID: {}, Unit: {:?}, Active: {}", + keyset.id, keyset.unit, keyset.active + ); + } + + // Extract proofs from the token using the keysets + let proofs = token.proofs(&keysets)?; + println!("\nToken contains {} proofs:", proofs.len()); + + // Calculate total amount from proofs + let total = proofs.total_amount()?; + println!("Total amount from proofs: {} sats", total); + + // Verify total matches token value + assert_eq!(total, value, "Proof total should match token value"); + + println!("\nSuccessfully decoded token and extracted proofs!"); + + Ok(()) +} diff --git a/crates/cdk/src/wallet/multi_mint_wallet.rs b/crates/cdk/src/wallet/multi_mint_wallet.rs index bd7547989..1ae9d4139 100644 --- a/crates/cdk/src/wallet/multi_mint_wallet.rs +++ b/crates/cdk/src/wallet/multi_mint_wallet.rs @@ -9,10 +9,10 @@ use std::str::FromStr; use std::sync::Arc; use anyhow::Result; -use cdk_common::database; use cdk_common::database::WalletDatabase; use cdk_common::task::spawn; use cdk_common::wallet::{MeltQuote, Transaction, TransactionDirection, TransactionId}; +use cdk_common::{database, KeySetInfo}; use tokio::sync::RwLock; use tracing::instrument; use zeroize::Zeroize; @@ -61,6 +61,17 @@ pub struct TransferResult { pub target_balance_after: Amount, } +/// Data extracted from a token including mint URL, proofs, and memo +#[derive(Debug, Clone)] +pub struct TokenData { + /// The mint URL from the token + pub mint_url: MintUrl, + /// The proofs contained in the token + pub proofs: Proofs, + /// The memo from the token, if present + pub memo: Option, +} + /// Configuration for individual wallets within MultiMintWallet #[derive(Clone, Default, Debug)] pub struct WalletConfig { @@ -520,6 +531,66 @@ impl MultiMintWallet { &self.unit } + /// Get keysets for a mint url + pub async fn get_mint_keysets(&self, mint_url: &MintUrl) -> Result, Error> { + let wallets = self.wallets.read().await; + let target_wallet = wallets.get(mint_url).ok_or(Error::UnknownMint { + mint_url: mint_url.to_string(), + })?; + + target_wallet.get_mint_keysets().await + } + + /// Get token data (mint URL and proofs) from a token + /// + /// This method extracts the mint URL and proofs from a token. It will automatically + /// fetch the keysets from the mint if needed to properly decode the proofs. + /// + /// The mint must already be added to the wallet. If the mint is not in the wallet, + /// use `add_mint` first or set `allow_untrusted` in receive options. + /// + /// # Arguments + /// + /// * `token` - The token to extract data from + /// + /// # Returns + /// + /// A `TokenData` struct containing the mint URL and proofs + /// + /// # Example + /// + /// ```no_run + /// # use cdk::wallet::MultiMintWallet; + /// # use cdk::nuts::Token; + /// # use std::str::FromStr; + /// # async fn example(wallet: &MultiMintWallet) -> Result<(), Box> { + /// let token = Token::from_str("cashuA...")?; + /// let token_data = wallet.get_token_data(&token).await?; + /// println!("Mint: {}", token_data.mint_url); + /// println!("Proofs: {} total", token_data.proofs.len()); + /// # Ok(()) + /// # } + /// ``` + #[instrument(skip(self, token))] + pub async fn get_token_data(&self, token: &Token) -> Result { + let mint_url = token.mint_url()?; + + // Get the keysets for this mint + let keysets = self.get_mint_keysets(&mint_url).await?; + + // Extract proofs using the keysets + let proofs = token.proofs(&keysets)?; + + // Get the memo + let memo = token.memo().clone(); + + Ok(TokenData { + mint_url, + proofs, + memo, + }) + } + /// Get wallet balances for all mints #[instrument(skip(self))] pub async fn get_balances(&self) -> Result, Error> { @@ -2037,4 +2108,93 @@ mod tests { assert_eq!(options.allowed_mints, vec![mint1, mint2]); assert_eq!(options.excluded_mints, vec![mint3]); } + + #[tokio::test] + async fn test_get_mint_keysets_unknown_mint() { + use std::str::FromStr; + + let multi_wallet = create_test_multi_wallet().await; + let mint_url = MintUrl::from_str("https://unknown-mint.example.com").unwrap(); + + // Should error when trying to get keysets for a mint that hasn't been added + let result = multi_wallet.get_mint_keysets(&mint_url).await; + assert!(result.is_err()); + + match result { + Err(Error::UnknownMint { mint_url: url }) => { + assert!(url.contains("unknown-mint.example.com")); + } + _ => panic!("Expected UnknownMint error"), + } + } + + #[tokio::test] + async fn test_multi_mint_receive_options() { + use std::str::FromStr; + + let mint_url = MintUrl::from_str("https://trusted.mint.example.com").unwrap(); + + // Test default options + let default_opts = MultiMintReceiveOptions::default(); + assert!(!default_opts.allow_untrusted); + assert!(default_opts.transfer_to_mint.is_none()); + + // Test builder pattern + let opts = MultiMintReceiveOptions::new() + .allow_untrusted(true) + .transfer_to_mint(Some(mint_url.clone())); + + assert!(opts.allow_untrusted); + assert_eq!(opts.transfer_to_mint, Some(mint_url)); + } + + #[tokio::test] + async fn test_get_token_data_unknown_mint() { + use std::str::FromStr; + + let multi_wallet = create_test_multi_wallet().await; + + // Create a token from a mint that isn't in the wallet + // This is a valid token structure pointing to an unknown mint + let token_str = "cashuBpGF0gaJhaUgArSaMTR9YJmFwgaNhYQFhc3hAOWE2ZGJiODQ3YmQyMzJiYTc2ZGIwZGYxOTcyMTZiMjlkM2I4Y2MxNDU1M2NkMjc4MjdmYzFjYzk0MmZlZGI0ZWFjWCEDhhhUP_trhpXfStS6vN6So0qWvc2X3O4NfM-Y1HISZ5JhZGlUaGFuayB5b3VhbXVodHRwOi8vbG9jYWxob3N0OjMzMzhhdWNzYXQ="; + let token = Token::from_str(token_str).unwrap(); + + // Should error because the mint (localhost:3338) hasn't been added + let result = multi_wallet.get_token_data(&token).await; + assert!(result.is_err()); + + match result { + Err(Error::UnknownMint { mint_url }) => { + assert!(mint_url.contains("localhost:3338")); + } + _ => panic!("Expected UnknownMint error"), + } + } + + #[test] + fn test_token_data_struct() { + use std::str::FromStr; + + let mint_url = MintUrl::from_str("https://example.mint.com").unwrap(); + let proofs = vec![]; + let memo = Some("Test memo".to_string()); + + let token_data = TokenData { + mint_url: mint_url.clone(), + proofs: proofs.clone(), + memo: memo.clone(), + }; + + assert_eq!(token_data.mint_url, mint_url); + assert_eq!(token_data.proofs.len(), 0); + assert_eq!(token_data.memo, memo); + + // Test with no memo + let token_data_no_memo = TokenData { + mint_url: mint_url.clone(), + proofs: vec![], + memo: None, + }; + assert!(token_data_no_memo.memo.is_none()); + } } From 1d528034d37b780031c280c65181ec85c975251f Mon Sep 17 00:00:00 2001 From: unldenis Date: Tue, 2 Dec 2025 17:21:55 +0100 Subject: [PATCH 320/321] feat: add support for static auth token --- crates/cdk-axum/src/router_handlers.rs | 2 +- crates/cdk-common/src/error.rs | 11 +++++++++++ .../src/bin/start_fake_auth_mint.rs | 1 + crates/cdk-mintd/Cargo.toml | 2 +- crates/cdk-mintd/src/config.rs | 2 ++ crates/cdk-mintd/src/lib.rs | 8 ++++++++ crates/cdk/src/mint/auth/mod.rs | 12 ++++++++++++ crates/cdk/src/mint/builder.rs | 17 +++++++++++++++-- crates/cdk/src/mint/mod.rs | 14 ++++++++++++-- portal-cmds.txt | 7 +++++++ 10 files changed, 70 insertions(+), 6 deletions(-) diff --git a/crates/cdk-axum/src/router_handlers.rs b/crates/cdk-axum/src/router_handlers.rs index 5316f7b0f..b18071a1f 100644 --- a/crates/cdk-axum/src/router_handlers.rs +++ b/crates/cdk-axum/src/router_handlers.rs @@ -680,7 +680,7 @@ where | ErrorCode::BlindAuthRequired => StatusCode::BAD_REQUEST, // Auth failures (401 Unauthorized) - ErrorCode::ClearAuthFailed | ErrorCode::BlindAuthFailed => StatusCode::UNAUTHORIZED, + ErrorCode::ClearAuthFailed | ErrorCode::StaticAuthTokenMismatch | ErrorCode::BlindAuthFailed => StatusCode::UNAUTHORIZED, // Lightning/payment errors and unknown errors (500 Internal Server Error) ErrorCode::LightningError | ErrorCode::Unknown(_) => StatusCode::INTERNAL_SERVER_ERROR, diff --git a/crates/cdk-common/src/error.rs b/crates/cdk-common/src/error.rs index 188a0c9ad..eddf5d341 100644 --- a/crates/cdk-common/src/error.rs +++ b/crates/cdk-common/src/error.rs @@ -68,6 +68,9 @@ pub enum Error { /// Clear Auth Failed #[error("Clear Auth Failed")] ClearAuthFailed, + /// Static Auth Token Mismatch + #[error("Static Auth Token Mismatch")] + StaticAuthTokenMismatch, /// Blind Auth Failed #[error("Blind Auth Failed")] BlindAuthFailed, @@ -543,6 +546,10 @@ impl From for ErrorResponse { code: ErrorCode::ClearAuthFailed, detail: Error::ClearAuthFailed.to_string(), }, + Error::StaticAuthTokenMismatch => ErrorResponse { + code: ErrorCode::StaticAuthTokenMismatch, + detail: Error::StaticAuthTokenMismatch.to_string(), + }, Error::BlindAuthRequired => ErrorResponse { code: ErrorCode::BlindAuthRequired, detail: Error::BlindAuthRequired.to_string(), @@ -706,6 +713,8 @@ pub enum ErrorCode { ClearAuthRequired, /// Clear Auth Failed ClearAuthFailed, + /// Static Auth Token Mismatch + StaticAuthTokenMismatch, /// Blind Auth Required BlindAuthRequired, /// Blind Auth Failed @@ -744,6 +753,7 @@ impl ErrorCode { 20009 => Self::DuplicateSignature, 30001 => Self::ClearAuthRequired, 30002 => Self::ClearAuthFailed, + 30003 => Self::StaticAuthTokenMismatch, 31001 => Self::BlindAuthRequired, 31002 => Self::BlindAuthFailed, _ => Self::Unknown(code), @@ -777,6 +787,7 @@ impl ErrorCode { Self::DuplicateSignature => 20009, Self::ClearAuthRequired => 30001, Self::ClearAuthFailed => 30002, + Self::StaticAuthTokenMismatch => 30003, Self::BlindAuthRequired => 31001, Self::BlindAuthFailed => 31002, Self::Unknown(code) => *code, diff --git a/crates/cdk-integration-tests/src/bin/start_fake_auth_mint.rs b/crates/cdk-integration-tests/src/bin/start_fake_auth_mint.rs index 7d7dc8e1a..032326093 100644 --- a/crates/cdk-integration-tests/src/bin/start_fake_auth_mint.rs +++ b/crates/cdk-integration-tests/src/bin/start_fake_auth_mint.rs @@ -86,6 +86,7 @@ async fn start_fake_auth_mint( restore: AuthType::Blind, check_proof_state: AuthType::Blind, websocket_auth: AuthType::Blind, + static_auth_token: None, }); // Set description for the mint diff --git a/crates/cdk-mintd/Cargo.toml b/crates/cdk-mintd/Cargo.toml index 2a54c71a4..bd0268353 100644 --- a/crates/cdk-mintd/Cargo.toml +++ b/crates/cdk-mintd/Cargo.toml @@ -11,7 +11,7 @@ rust-version.workspace = true readme = "README.md" [features] -default = ["management-rpc", "cln", "lnd", "lnbits", "fakewallet", "grpc-processor", "sqlite", "portalwallet"] +default = ["management-rpc", "cln", "lnd", "lnbits", "fakewallet", "grpc-processor", "sqlite", "portalwallet", "auth"] # Database features - at least one must be enabled sqlite = ["dep:cdk-sqlite"] postgres = ["dep:cdk-postgres"] diff --git a/crates/cdk-mintd/src/config.rs b/crates/cdk-mintd/src/config.rs index 42277dd2a..0740706fd 100644 --- a/crates/cdk-mintd/src/config.rs +++ b/crates/cdk-mintd/src/config.rs @@ -557,6 +557,8 @@ pub struct Auth { /// Enable WebSocket authentication support #[serde(default = "default_blind")] pub websocket_auth: AuthType, + /// Static auth token (if set, this token will be accepted for clear auth instead of OIDC) + pub static_auth_token: Option, } fn default_blind() -> AuthType { diff --git a/crates/cdk-mintd/src/lib.rs b/crates/cdk-mintd/src/lib.rs index 251b5065b..d53e92e61 100644 --- a/crates/cdk-mintd/src/lib.rs +++ b/crates/cdk-mintd/src/lib.rs @@ -250,6 +250,9 @@ pub fn load_settings(work_dir: &Path, config_path: Option) -> Result Result<(), Error> { + // Check static token first if configured + if let Some(static_token) = &self.static_auth_token { + if token == *static_token { + // tracing::debug!("Static auth token verified successfully"); + return Ok(()); + } + // If static token is set but doesn't match, fail + tracing::warn!("Static auth token mismatch"); + return Err(Error::StaticAuthTokenMismatch); + } + + // Fall back to OIDC verification Ok(self .oidc_client .as_ref() diff --git a/crates/cdk/src/mint/builder.rs b/crates/cdk/src/mint/builder.rs index b48d265fe..ecf201e8b 100644 --- a/crates/cdk/src/mint/builder.rs +++ b/crates/cdk/src/mint/builder.rs @@ -34,6 +34,8 @@ pub struct MintBuilder { localstore: DynMintDatabase, #[cfg(feature = "auth")] auth_localstore: Option, + #[cfg(feature = "auth")] + static_auth_token: Option, payment_processors: HashMap, supported_units: HashMap, custom_paths: HashMap, @@ -61,6 +63,8 @@ impl MintBuilder { localstore, #[cfg(feature = "auth")] auth_localstore: None, + #[cfg(feature = "auth")] + static_auth_token: None, payment_processors: HashMap::new(), supported_units: HashMap::new(), custom_paths: HashMap::new(), @@ -127,6 +131,14 @@ impl MintBuilder { self } + /// Set static auth token for clear auth verification + #[cfg(feature = "auth")] + pub fn with_static_auth_token(mut self, token: String) -> Self { + self.static_auth_token = Some(token); + self + } + + /// Set mint info pub fn with_mint_info(mut self, mint_info: MintInfo) -> Self { self.mint_info = mint_info; @@ -326,14 +338,15 @@ impl MintBuilder { pub async fn build_with_signatory( self, signatory: Arc, - ) -> Result { + ) -> Result { #[cfg(feature = "auth")] if let Some(auth_localstore) = self.auth_localstore { return Mint::new_with_auth( self.mint_info, signatory, self.localstore, - auth_localstore, + Some(auth_localstore), + self.static_auth_token, self.payment_processors, self.keys_metadata, ) diff --git a/crates/cdk/src/mint/mod.rs b/crates/cdk/src/mint/mod.rs index 0f7e801d5..dc2aee999 100644 --- a/crates/cdk/src/mint/mod.rs +++ b/crates/cdk/src/mint/mod.rs @@ -72,6 +72,9 @@ pub struct Mint { pubsub_manager: Arc, #[cfg(feature = "auth")] oidc_client: Option, + /// Static auth token (if set, this token will be accepted for clear auth) + #[cfg(feature = "auth")] + static_auth_token: Option, /// In-memory keyset keysets: Arc>>, /// Background task management @@ -103,6 +106,8 @@ impl Mint { localstore, #[cfg(feature = "auth")] None, + #[cfg(feature = "auth")] + None, payment_processors, keys_metadata, ) @@ -115,7 +120,8 @@ impl Mint { mint_info: MintInfo, signatory: Arc, localstore: DynMintDatabase, - auth_localstore: DynMintAuthDatabase, + auth_localstore: Option, + static_auth_token: Option, payment_processors: HashMap, keys_metadata: HashMap, ) -> Result { @@ -123,7 +129,8 @@ impl Mint { mint_info, signatory, localstore, - Some(auth_localstore), + auth_localstore, + static_auth_token, payment_processors, keys_metadata, ) @@ -137,6 +144,7 @@ impl Mint { signatory: Arc, localstore: DynMintDatabase, #[cfg(feature = "auth")] auth_localstore: Option, + #[cfg(feature = "auth")] static_auth_token: Option, payment_processors: HashMap, keys_metadata: HashMap, ) -> Result { @@ -220,6 +228,8 @@ impl Mint { Some(nut21.client_id.clone()), ) }), + #[cfg(feature = "auth")] + static_auth_token, payment_processors, #[cfg(feature = "auth")] auth_localstore, diff --git a/portal-cmds.txt b/portal-cmds.txt index 36e0ce311..f892e971d 100644 --- a/portal-cmds.txt +++ b/portal-cmds.txt @@ -6,3 +6,10 @@ cargo run -p cdk-cli -- --unit casa mint "http://127.0.0.1:8085" 100 "my real mi cargo run -p cdk-cli -- --unit casa send + + +curl -v -X POST "http://localhost:8085/v1/mint/quote/bolt11" -H "Content-Type: application/json" -H "Clear-auth: my-static-token" -d '{ "amount": 1000,"unit": "casa" }' + + + +curl -v -X POST "http://localhost:8085/v1/mint/quote/bolt11" -H "Content-Type: application/json" -H "Clear-auth: no-token" -d '{ "amount": 1000,"unit": "casa" }' From 0f23829c430b05ac372e31c8476106ccb284e494 Mon Sep 17 00:00:00 2001 From: unldenis Date: Wed, 3 Dec 2025 17:29:29 +0100 Subject: [PATCH 321/321] feat: Expose unit info --- .../src/wallet/mint_connector/http_client.rs | 13 ++++++++++ crates/cdk/src/wallet/mint_connector/mod.rs | 5 ++++ crates/cdk/src/wallet/mod.rs | 9 +++++++ crates/cdk/src/wallet/multi_mint_wallet.rs | 25 +++++++++++++++++++ 4 files changed, 52 insertions(+) diff --git a/crates/cdk/src/wallet/mint_connector/http_client.rs b/crates/cdk/src/wallet/mint_connector/http_client.rs index a9705c43c..1a4c5bb1a 100644 --- a/crates/cdk/src/wallet/mint_connector/http_client.rs +++ b/crates/cdk/src/wallet/mint_connector/http_client.rs @@ -4,6 +4,8 @@ use std::sync::{Arc, RwLock as StdRwLock}; use async_trait::async_trait; use cdk_common::{nut19, MeltQuoteBolt12Request, MintQuoteBolt12Request, MintQuoteBolt12Response}; +use cdk_common::common::UnitMetadata; +use crate::nuts::CurrencyUnit; #[cfg(feature = "auth")] use cdk_common::{Method, ProtectedEndpoint, RoutePath}; use serde::de::DeserializeOwned; @@ -573,6 +575,17 @@ where ) .await } + + /// Get Unit Metadata + #[instrument(skip(self), fields(mint_url = %self.mint_url))] + async fn get_unit_metadata(&self, unit: CurrencyUnit) -> Result { + let unit_str = unit.to_string(); + let url = self + .mint_url + .join_paths(&["v1", "unit", &unit_str])?; + + self.transport.http_get(url, None).await + } } /// Http Client diff --git a/crates/cdk/src/wallet/mint_connector/mod.rs b/crates/cdk/src/wallet/mint_connector/mod.rs index 6cfcc21c2..41514f4cf 100644 --- a/crates/cdk/src/wallet/mint_connector/mod.rs +++ b/crates/cdk/src/wallet/mint_connector/mod.rs @@ -14,6 +14,8 @@ use crate::nuts::{ MintQuoteBolt11Response, MintRequest, MintResponse, RestoreRequest, RestoreResponse, SwapRequest, SwapResponse, }; +use cdk_common::common::UnitMetadata; +use crate::nuts::CurrencyUnit; #[cfg(feature = "auth")] use crate::wallet::AuthWallet; @@ -127,4 +129,7 @@ pub trait MintConnector: Debug { &self, request: MeltRequest, ) -> Result, Error>; + + /// Get Unit Metadata + async fn get_unit_metadata(&self, unit: CurrencyUnit) -> Result; } diff --git a/crates/cdk/src/wallet/mod.rs b/crates/cdk/src/wallet/mod.rs index d6497b4fc..8313a3398 100644 --- a/crates/cdk/src/wallet/mod.rs +++ b/crates/cdk/src/wallet/mod.rs @@ -33,6 +33,7 @@ use crate::types::ProofInfo; use crate::util::unix_time; use crate::wallet::mint_metadata_cache::MintMetadataCache; use crate::Amount; +use cdk_common::common::UnitMetadata; #[cfg(feature = "auth")] use crate::OidcClient; @@ -724,6 +725,14 @@ impl Wallet { pub fn set_target_proof_count(&mut self, count: usize) { self.target_proof_count = count; } + + /// Get unit metadata from the mint + /// + /// Fetches the unit metadata for this wallet's currency unit from the mint's HTTP endpoint. + #[instrument(skip(self))] + pub async fn get_unit_metadata(&self) -> Result { + self.client.get_unit_metadata(self.unit.clone()).await + } } impl Drop for Wallet { diff --git a/crates/cdk/src/wallet/multi_mint_wallet.rs b/crates/cdk/src/wallet/multi_mint_wallet.rs index 074d4bdd1..05c8d261f 100644 --- a/crates/cdk/src/wallet/multi_mint_wallet.rs +++ b/crates/cdk/src/wallet/multi_mint_wallet.rs @@ -31,6 +31,7 @@ use crate::types::Melted; use crate::wallet::mint_connector::transport::tor_transport::TorAsync; use crate::wallet::types::MintQuote; use crate::{Amount, Wallet}; +use cdk_common::common::UnitMetadata; // Transfer timeout constants /// Total timeout for waiting for Lightning payment confirmation during transfers @@ -1919,6 +1920,30 @@ impl MultiMintWallet { wallet.melt_human_readable_quote(address, amount_msat).await } + + /// Get unit metadata for a specific mint + /// + /// Fetches the unit metadata from the mint's HTTP endpoint for this wallet's currency unit. + /// + /// # Arguments + /// + /// * `mint_url` - The mint to fetch unit metadata from + /// + /// # Returns + /// + /// The unit metadata for this wallet's currency unit + #[instrument(skip(self))] + pub async fn get_unit_metadata( + &self, + mint_url: &MintUrl, + ) -> Result { + let wallets = self.wallets.read().await; + let wallet = wallets.get(mint_url).ok_or(Error::UnknownMint { + mint_url: mint_url.to_string(), + })?; + + wallet.get_unit_metadata().await + } } impl Drop for MultiMintWallet {