feat: custom axum router #1251

asmogo · 2025-11-03T15:40:11Z

Description

Add support for custom payment methods and custom Axum routes. Custom payment methods can be provided by gRPC payment processors using the SettingsResponse proto message.

Router Framework: Added CustomRouter and CustomHandlers in cdk-axum to enable pluggable payment method handlers with support for custom routes and business logic
Custom Payment Methods: Introduced NutCustom type definitions in the Cashu spec to formally define custom payment method schemas and request/response handling
Typed Settings Response: Migrated the settings endpoint to use a strongly-typed SettingsResponse for better type safety and validation across the mint
Auth & Payment Refactoring: Refactored authentication routes and custom payment method handling across all backend implementations (CLN, LDK, LNbits, fake-wallet) to work with the new router pattern
Rename NutCustom to CustomPaymentMethod
Update mintd to NOT load MintInfo from storage on start

Notes to the reviewers

Suggested CHANGELOG Updates

CHANGED

Payment Processor: Extended protobuf definitions and client/server logic for custom payment processing.

ADDED

Custom Router Implementation: Added custom_router.rs and custom_handlers.rs in cdk-axum to support custom Axum routing and handlers.

REMOVED

FIXED

Checklist

I followed the code style guidelines
I ran just final-check before committing

crates/cdk/src/wallet/receive.rs

asmogo · 2025-11-03T15:44:29Z

crates/cdk-payment-processor/src/proto/payment_processor.proto

 enum OutgoingPaymentOptionsType {
  OUTGOING_BOLT11 = 0;
  OUTGOING_BOLT12 = 1;
+  OUTGOING_PAYMENT_OPTIONS_TYPE_CUSTOM = 2;


This was prefixed to avoid collisions.
https://buf.build/docs/best-practices/style-guide/#enums
https://buf.build/docs/lint/rules/#enum_value_prefix

We might want to prefix all other enums as well.

This was prefixed to avoid collisions. https://buf.build/docs/best-practices/style-guide/#enums https://buf.build/docs/lint/rules/#enum_value_prefix

We might want to prefix all other enums as well.

50a77aa was necessary for this.

crates/cdk-lnd/src/lib.rs

crates/cdk-common/src/payment.rs

crates/cashu/src/nuts/auth/nut21.rs

crates/cdk-mintd/example.config.toml

…stom

crates/cdk-payment-processor/src/proto/client.rs

- Replace `custom_payment_methods` struct with dynamic retrieval from payment processors. - Update payment-related logic to support dynamic custom methods. - Simplify configuration by removing redundant custom payment method fields. - Adjust examples and tests accordingly.

- Replace `PaymentProcessorSettings` with `SettingsResponse` for strongly typed configuration. - Update all `get_settings` methods to return `SettingsResponse` instead of JSON. - Adjust payment-related logic and proto definitions to utilize the new structure. - Simplify serialization and removal of redundant type conversions.

thesimplekid

Nice work. Initial comments

crates/cashu/src/nuts/nut_custom.rs

crates/cdk-payment-processor/src/proto/client.rs

crates/cdk-mintd/example.config.toml

crates/cashu/src/nuts/auth/nut21.rs

crates/cashu/src/nuts/nut04.rs

thesimplekid · 2025-11-05T04:45:06Z

crates/cashu/src/nuts/nut_custom.rs

+    /// Optional description
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub description: Option<String>,


Think this is bolt11 specific and we shouldnt have it always defined if a payment type wants it they can put it on data.

thesimplekid · 2025-11-05T04:49:41Z

crates/cdk/src/mint/issue/mod.rs

+    /// Custom payment method request
+    Custom {
+        /// Payment method name (e.g., "paypal", "venmo")
+        method: String,


Our PaymentMethod enum has a custom variant should we use that?

thesimplekid · 2025-11-05T04:52:23Z

crates/cdk/src/mint/melt/mod.rs

+            payment_quote.fee,
+            unix_time() + melt_ttl,
+            payment_quote.request_lookup_id.clone(),
+            None, // Custom methods don't use options


Should they maybe there should be a custom variant on that?

callebtc · 2025-11-05T16:02:22Z

Love this PR! My questions / requests from the call:

Currently, you only iterate over gRPC payment processors to build custom routes, can't we also iterate through the in-memory ones the same way as gRPCs?
The bolt11 and bolt12 routes are hard-coded while the custom ones are dynamic. Can't we treat them the same way? I.e. iterate over all payment processors and add those routes?
We would probably have to check for uniqueness of (unit, method) pairs and error during startup to avoid collisions.
The bolt11 route decodes the request in the mint (before it reaches the bolt11 payment processor), can we move any Lightning-related code to the payment processor?

- Remove `bolt12_router` and related endpoint declarations. - Integrate BOLT12 handling directly into custom payment method logic. - Simplify `create_mint_router` by removing `include_bolt12` parameter. - Update routing and handlers for unified dynamic custom method processing. - Cleanup redundant code and references.

- Add `QuoteState` to `nut_custom` for enhanced quote handling. - Extend dynamic payment method handling with support for `bolt11`, `bolt12`, and custom methods. - Simplify `check_mint_quote_paid` by removing method-specific conditions. - Ensure consistent integration of custom payment logic across mint and melt operations. - Update NUT04 and NUT05 configurations to process new methods directly.

…stom payment support This commit completes the wallet-side payment method generalization migration: **Phase 1: Wallet Issue (Mint) Refactoring** - Rename issue_bolt11.rs and issue_bolt12.rs to bolt11.rs and bolt12.rs - Create unified router in issue/mod.rs with mint_quote_unified() and mint_unified() - Add custom.rs with custom payment method support for minting - Routes based on PaymentMethod enum (Known vs Custom variants) **Phase 2: Wallet Melt (Payment) Refactoring** - Rename melt_bolt11.rs and melt_bolt12.rs to bolt11.rs and bolt12.rs - Create unified router in melt/mod.rs with melt_quote_unified() - Add custom.rs with custom payment method support for melting - **CRITICAL FIX**: Remove UnsupportedPaymentMethod error for Custom payment methods in melt_proofs dispatcher (lines 200-210 in bolt11.rs) **Phase 3: HTTP Client Updates** - Add MintQuoteCustomRequest and MintQuoteCustomResponse imports - Add MeltQuoteCustomRequest import - Implement post_mint_custom_quote() in MintConnector trait and HttpClient - Implement post_melt_custom_quote() in MintConnector trait and HttpClient - Custom methods use /v1/mint/quote/{method} and /v1/melt/quote/{method} routes **Architecture Changes:** - Wallet now supports both Known (Bolt11, Bolt12) and Custom payment methods - Private bolt11/bolt12 modules handle method-specific logic - Public unified routers dispatch based on PaymentMethod variant - Custom payment methods can be processed through the same flows as Bolt11/Bolt12 This implementation follows the migration_plan.md specification and removes the critical blocker that prevented custom payment methods from working in the wallet.

…stom_router

Add post_mint_custom_quote() and post_melt_custom_quote() stub implementations to DirectMintConnection test mock to satisfy the MintConnector trait requirements. These methods return UnsupportedPaymentMethod error as custom payment methods are not yet implemented in the test infrastructure.

…stom_router

# Conflicts: # crates/cdk-sqlite/src/wallet/mod.rs # crates/cdk/src/wallet/melt/bolt11.rs # crates/cdk/src/wallet/melt/mod.rs

# Conflicts: # crates/cdk-common/src/mint.rs # crates/cdk/src/mint/ln.rs

thesimplekid

Nice work. We seem to be doing alot of matching on str when it would be better if we could use the enums I think for methods.

Cargo.lock

thesimplekid · 2025-12-30T11:02:19Z

crates/cashu/src/nuts/nut00/mod.rs

+impl Default for PaymentMethod {
+    fn default() -> Self {
+        Self::Known(KnownMethod::Bolt11)
+    }
+}


Should we have a default for this? I think maybe not.

thesimplekid · 2025-12-30T11:30:35Z

crates/cdk-mintd/src/lib.rs

            add_endpoint(ws_protected_endpoint, &auth_settings.websocket_auth);
        }

+        // Custom payment method endpoints will be added dynamically after the mint is built


Is this correct and in the right place? Does it refer to auth endpoints?

Yes, it does refer to the protected_endpoints in auth mint. These also have to be dynamically generated based on the provided payment processor methods here.

I'll update the comment to use the correct function name.

thesimplekid · 2025-12-30T11:33:33Z

crates/cdk-payment-processor/src/proto/payment_processor.proto

 message SettingsResponse {
-  string inner = 1;
+  string unit = 1;
+  Bolt11Settings bolt11 = 2;
+  Bolt12Settings bolt12 = 3;
+  map<string, string> custom = 4;
+}


We should maybe start versioning the proto file.

crates/cdk/src/mint/issue/mod.rs

crates/cdk/src/mint/builder.rs

thesimplekid

LGTM to me. One small nit but other then that nice work.

thesimplekid · 2026-01-03T15:41:12Z

crates/cdk/src/mint/builder.rs

+        // Handle bolt11 methods
+        if method.is_bolt11() {
+            if let Some(ref bolt11_settings) = settings.bolt11 {


A match would be better here then the if, else if else.

thesimplekid · 2026-01-03T15:56:32Z

crates/cashu/src/nuts/auth/nut21.rs

I think we need to update the matching route paths to account for the custom path otherwise they wont be projected by auth.

Have you tried custom paths with auth?

diff --git a/crates/cashu/src/nuts/auth/nut21.rs b/crates/cashu/src/nuts/auth/nut21.rs index 15557bdd..579d4b78 100644 --- a/crates/cashu/src/nuts/auth/nut21.rs +++ b/crates/cashu/src/nuts/auth/nut21.rs @@ -387,6 +387,16 @@ mod tests { assert!(matches!(result.unwrap_err(), Error::InvalidRegex(_))); } + #[test] + // #[ignore = "regex matching does not include custom payment methods"] + fn test_matching_route_paths_custom_payment_methods() { + let paths = matching_route_paths("^/v1/mint/.*").unwrap(); + + assert!(paths.contains(&RoutePath::Mint("bolt11".to_string()))); + assert!(paths.contains(&RoutePath::Mint("bolt12".to_string()))); + assert!(paths.contains(&RoutePath::Mint("paypal".to_string()))); + } + #[test] fn test_route_path_to_string() { // Test that to_string() returns the correct path strings

asmogo added 2 commits November 3, 2025 15:30

feat: custom axum router

0737c41

feat: fix auth routes

11ec9b7

asmogo commented Nov 3, 2025

View reviewed changes

fix: integration test

4ddd411

asmogo commented Nov 3, 2025

View reviewed changes

crates/cdk-mintd/example.config.toml Outdated Show resolved Hide resolved

asmogo added 2 commits November 3, 2025 17:38

docs: added missing documentation

8b7af1d

fix: remove unnecessary method decrleration from MeltQuoteRequest::Cu…

586686d

…stom

asmogo commented Nov 3, 2025

View reviewed changes

crates/cdk-payment-processor/src/proto/client.rs Outdated Show resolved Hide resolved

asmogo added 7 commits November 3, 2025 19:59

fix: merge master into feat/custom_router

cea2cfb

fix: test_route_path_serialization

d45df05

fix: reet toolchain

88d4d74

fix: correct request type mapping for custom payment options

df7292a

fix: remove unwanted stuff

f197f6c

asmogo marked this pull request as ready for review November 4, 2025 20:00

asmogo requested review from crodas and thesimplekid November 4, 2025 20:00

thesimplekid reviewed Nov 5, 2025

View reviewed changes

asmogo added 10 commits November 6, 2025 16:52

Merge branch 'main' into feat/custom_router

8e6403d

fix: test

23138ab

Merge remote-tracking branch 'origin/feat/custom_router' into feat/cu…

6f00eed

…stom_router

Merge remote-tracking branch 'origin/feat/custom_router' into feat/cu…

f010ea7

…stom_router

fix: comment + fmt

58474f6

Merge remote-tracking branch 'origin/feat/custom_router' into feat/cu…

37b234e

…stom_router

thesimplekid added this to the 0.15.0 milestone Dec 16, 2025

thesimplekid added this to CDK Dec 16, 2025

github-project-automation bot moved this to Backlog in CDK Dec 16, 2025

asmogo added 11 commits December 19, 2025 13:43

fix: extra json field

6b5fb95

Merge branch 'main' into feat/custom_router

27f81f8

# Conflicts: # crates/cdk-sqlite/src/wallet/mod.rs # crates/cdk/src/wallet/melt/bolt11.rs # crates/cdk/src/wallet/melt/mod.rs

fix: minor fixes

ccb9d87

fix: update ffi and wallet transactions

6b0f380

fix: update wallet

cf54b2a

fix: update cargo

126bdc1

fix: update melt extra json

6166de1

fix: extra son and bolt 12

66bfc4a

fix: PaymentMethod::Known

7fba4d1

chore: update lock

3ab5c33

chore: using enum

4b1e7c6

thesimplekid moved this from Backlog to In progress in CDK Dec 20, 2025

asmogo added 4 commits December 20, 2025 21:33

chore: auth flag

e0c7ab4

Merge branch 'main' into feat/custom_router

869261a

# Conflicts: # crates/cdk-common/src/mint.rs # crates/cdk/src/mint/ln.rs

fix: test

5dcba94

fix: enum types and cargo lock

b84fffb

thesimplekid reviewed Dec 30, 2025

View reviewed changes

asmogo added 7 commits January 3, 2026 10:37

Merge branch 'main' into feat/custom_router

edbfb9d

fix: reset lock

a1b7bcf

fix: remove string comparison for payment_methods

ba8ca1f

fix: remove default method, fix comment and unused import

b6097fa

fix: added default back in

207237e

fix: remove payment method default values

4786340

fix: proto to MeltQuoteState conversion

50a77aa

thesimplekid reviewed Jan 3, 2026

View reviewed changes

This was referenced Jan 4, 2026

Stricter clippy #1485

Open

feat: Generic unit on amount #1470

Open

feat: custom axum router #1251

Are you sure you want to change the base?

feat: custom axum router #1251

Uh oh!

Conversation

asmogo commented Nov 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Notes to the reviewers

Suggested CHANGELOG Updates

CHANGED

ADDED

REMOVED

FIXED

Checklist

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

thesimplekid left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

callebtc commented Nov 5, 2025

Uh oh!

thesimplekid left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

asmogo Jan 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

thesimplekid left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

asmogo commented Nov 3, 2025 •

edited

Loading

asmogo Jan 3, 2026 •

edited

Loading