feat: add wallet trait by crodas · Pull Request #1581 · cashubtc/cdk

crodas · 2026-01-28T03:28:54Z

Description

Introduce a modular trait system for wallet implementations that enables flexible composition of wallet capabilities. This allows different wallet implementations to share a common interface while supporting selective trait implementation.

The trait hierarchy consists of:

WalletTypes: Base trait defining associated types (Amount, Proofs, etc.)
WalletBalance: Balance query operations
WalletMintInfo: Mint information and keyset operations
WalletMint: Minting operations (payment -> tokens)
WalletMelt: Melting operations (tokens -> payment)
WalletReceive: Token receiving
WalletProofs: Proof state management
Wallet: Super-trait combining all capabilities with blanket impl

Implements all traits for both cdk::Wallet and cdk-ffi::Wallet, enabling generic code that works with any wallet implementation.

Notes to the reviewers

Suggested CHANGELOG Updates

CHANGED

ADDED

REMOVED

FIXED

Checklist

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

crates/cdk/src/wallet/traits.rs

thesimplekid · 2026-02-24T12:24:00Z

@crodas Now that we have released 0.15 I think we should turn our attention back to this and get it merged. Looks like it needs a rebase is there anything else that is outstanding with it?

cc @ye0man

crodas · 2026-02-24T12:40:42Z

Rebasing, I am on it now.

crates/cdk/src/wallet/wallet_trait.rs

crates/cdk/src/wallet/balance.rs

crates/cdk/examples/auth_wallet.rs

Define the WalletTrait in cdk-common with default method implementations for mint, melt, send, receive, and balance operations across Bolt11, Bolt12, and custom payment methods. Implement the trait for the concrete Wallet type in cdk, moving public API methods from inherent impls into the trait so that consumers can program against the trait abstraction. Add cdk-ffi/src/wallet_trait.rs to expose WalletTrait methods through the FFI layer, and update all CLI commands, examples, and integration tests to import WalletTrait where needed.

…unused imports Refactor the WalletTrait implementation so each method delegates to an inherent method on Wallet rather than containing inline logic. This makes the trait a thin forwarding layer for the compiler contract while the real implementations live as regular methods on Wallet. Remove the now-unnecessary `use WalletTrait` import from 42 caller files across CLI, FFI, examples, and integration tests, since callers invoke inherent methods directly. Also remove section header comments (// === ... ===) added during the refactor.

thesimplekid

I think this is pretty close just rename and few things to make it more clear that the Trait is more for internal use and not the primary API for the wallet and the Wallet struct should still be used directly, we should also add doc comments to this effect.

thesimplekid · 2026-03-22T21:31:41Z

crates/cdk/src/wallet/mod.rs

 };
 pub use builder::WalletBuilder;
 pub use cdk_common::wallet as types;
+pub use cdk_common::wallet::{ReceiveOptions, SendMemo, SendOptions, Wallet as WalletTrait};


Suggested change

pub use cdk_common::wallet::{ReceiveOptions, SendMemo, SendOptions, Wallet as WalletTrait};

pub use cdk_common::wallet::{ReceiveOptions, SendMemo, SendOptions};

I don't think we should re-export and promote the trait to be used publicity. The trait should be used internally by use to keep the ffi inline but public use should not be encouraged.

thesimplekid · 2026-03-22T21:33:09Z

crates/cdk-common/src/wallet/mod.rs

+/// Data for a prepared send operation (owned, no lifetime)
+#[derive(Debug, Clone)]
+pub struct PreparedSendData {
+    /// Operation ID
+    pub operation_id: Uuid,
+    /// Amount to send
+    pub amount: Amount,
+    /// Send options
+    pub options: SendOptions,
+    /// Proofs that need swapping
+    pub proofs_to_swap: Proofs,
+    /// Proofs to send directly
+    pub proofs_to_send: Proofs,
+    /// Fee for swap
+    pub swap_fee: Amount,
+    /// Fee for send
+    pub send_fee: Amount,
+}
+
+/// Data for a prepared melt operation (owned, no lifetime)
+#[derive(Debug, Clone)]
+pub struct PreparedMeltData {
+    /// Operation ID
+    pub operation_id: Uuid,
+    /// Melt quote
+    pub quote: MeltQuote,
+    /// Proofs to melt
+    pub proofs: Proofs,
+    /// Proofs that need swapping
+    pub proofs_to_swap: Proofs,
+    /// Swap fee
+    pub swap_fee: Amount,
+    /// Input fee
+    pub input_fee: Amount,
+    /// Input fee without swap
+    pub input_fee_without_swap: Amount,
+    /// Metadata
+    pub metadata: HashMap<String, String>,
+}


Having these owned types is required for the trait and ffi but it has the downside of adding extra clones since we cannot borrow. This is one reason I suggest we dont encourage the public use of the trait and the Wallet should be used directly.

thesimplekid · 2026-03-22T21:34:24Z

crates/cdk-common/src/wallet/mod.rs

+    async fn prepare_melt(
+        &self,
+        quote_id: &str,
+        metadata: HashMap<String, String>,
+    ) -> Result<Self::PreparedMelt, Self::Error>;
+
+    /// Prepare a melt operation with specific proofs
+    async fn prepare_melt_proofs(


Suggested change

async fn prepare_melt(

&self,

quote_id: &str,

metadata: HashMap<String, String>,

) -> Result<Self::PreparedMelt, Self::Error>;

/// Prepare a melt operation with specific proofs

async fn prepare_melt_proofs(

async fn prepare_melt_data(

&self,

quote_id: &str,

metadata: HashMap<String, String>,

) -> Result<Self::PreparedMelt, Self::Error>;

/// Prepare a melt operation with specific proofs

async fn prepare_melt_proofs_data(

We should name this fns so its clear they use the ones with the owned type and not the borrowed like the rust api can.

thesimplekid · 2026-03-22T21:35:25Z

crates/cdk-common/src/wallet/mod.rs

+    ) -> Result<Self::Amount, Self::Error>;
+
+    /// Prepare a send transaction
+    async fn prepare_send(


Suggested change

async fn prepare_send(

async fn prepare_send_data(

crodas requested review from davidcaseria and thesimplekid January 28, 2026 03:28

crodas self-assigned this Jan 28, 2026

github-project-automation bot added this to CDK Jan 28, 2026

github-project-automation bot moved this to Backlog in CDK Jan 28, 2026

crodas force-pushed the feature/wallet-trait branch from 497aa6d to 85ffb8b Compare January 28, 2026 04:33

crodas marked this pull request as ready for review January 28, 2026 05:28

thesimplekid reviewed Jan 28, 2026

View reviewed changes

crates/cdk/src/wallet/traits.rs Outdated Show resolved Hide resolved

crodas force-pushed the feature/wallet-trait branch 2 times, most recently from 1a2fd1f to b535f81 Compare January 30, 2026 06:23

ye0man moved this from Backlog to In Review in CDK Feb 4, 2026

crodas force-pushed the feature/wallet-trait branch from b535f81 to 84528dd Compare February 5, 2026 20:07

crodas marked this pull request as draft February 5, 2026 21:15

crodas force-pushed the feature/wallet-trait branch 4 times, most recently from 60280ad to ee94ebb Compare February 10, 2026 23:52

thesimplekid added this to the 0.16.0 milestone Feb 11, 2026

thesimplekid added wallet needs rebase labels Feb 24, 2026

thesimplekid changed the title ~~Add composable wallet trait system~~ Add wallet trait Mar 2, 2026

thesimplekid changed the title ~~Add wallet trait~~ feat: add wallet trait Mar 2, 2026

crodas force-pushed the feature/wallet-trait branch from ee94ebb to d30cce9 Compare March 17, 2026 23:26

crodas requested a review from thesimplekid March 18, 2026 10:06

thesimplekid requested changes Mar 18, 2026

View reviewed changes

github-project-automation bot moved this from In Review to In progress in CDK Mar 18, 2026

crodas force-pushed the feature/wallet-trait branch 2 times, most recently from 8f12b14 to b160bcc Compare March 20, 2026 10:16

crodas force-pushed the feature/wallet-trait branch 4 times, most recently from 0ac5cdb to 63705bd Compare March 21, 2026 19:38

crodas added 2 commits March 21, 2026 16:39

crodas force-pushed the feature/wallet-trait branch from 63705bd to 660cc55 Compare March 21, 2026 19:40

crodas marked this pull request as ready for review March 21, 2026 20:47

crodas requested a review from thesimplekid March 21, 2026 20:47

thesimplekid requested changes Mar 22, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add wallet trait#1581

feat: add wallet trait#1581
crodas wants to merge 2 commits intocashubtc:mainfrom
crodas:feature/wallet-trait

crodas commented Jan 28, 2026

Uh oh!

Uh oh!

thesimplekid commented Feb 24, 2026

Uh oh!

crodas commented Feb 24, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

thesimplekid left a comment

Uh oh!

thesimplekid Mar 22, 2026

Uh oh!

thesimplekid Mar 22, 2026

Uh oh!

thesimplekid Mar 22, 2026

Uh oh!

thesimplekid Mar 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	pub use cdk_common::wallet::{ReceiveOptions, SendMemo, SendOptions, Wallet as WalletTrait};
	pub use cdk_common::wallet::{ReceiveOptions, SendMemo, SendOptions};

Conversation

crodas commented Jan 28, 2026

Description

Notes to the reviewers

Suggested CHANGELOG Updates

CHANGED

ADDED

REMOVED

FIXED

Checklist

Uh oh!

Uh oh!

thesimplekid commented Feb 24, 2026

Uh oh!

crodas commented Feb 24, 2026

Uh oh!

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!

thesimplekid Mar 22, 2026

Choose a reason for hiding this comment

Uh oh!

thesimplekid Mar 22, 2026

Choose a reason for hiding this comment

Uh oh!

thesimplekid Mar 22, 2026

Choose a reason for hiding this comment

Uh oh!

thesimplekid Mar 22, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants