Architecture Decision Record: Wallet Cashu API

Title: Wallet Cashu - api design

status

completed

Updated on 03-09-2025

contributors

• Main contributor(s): leo-lox

• Reviewer(s): frnandu, nogringo

• Final decision made by: frnandu, leo-lox, nogringo

Context and Problem Statement

We want to introduce a wallet use-case. To support multiple types of wallets like NWC and Cashu, we need different implementations. Depending on the specific needs of a wallet, the capabilities are different. How can we achieve a wallet design for the Cashu wallet that works for our users as well as for the generic wallet use-case?

Main Proposal

Give the users methods to start a action like [spend, mint, melt] and notify about pending transactions via BehaviorSubjects. The objects, by the behavior subjects then have methods to confirm or cancel where appropriate. This is needed so the end-user can check the fees (transaction summary) before making a transaction.

A pseudocode flow would look like this:

main(){
  BehaviorSubject<Transaction> pendingTransactions = BehaviorSubject<Transaction>();


  /// initiate a transaction
  void spend(Unit 'sat', Reciever receiver) {
    /// ...wallet implementation
  }

  /// user code listen to pending transactions
  pendingTransactions.listen((transaction) {

    /// tbd if we have a stauts pending or a diffrent subscription for done (sucessfull, err) transactions
    if (transaction.type == TransactionType.spend && transaction.status == TransactionStatus.pending) {

        /// display transaction summary to user
        displayTransactionSummary(transaction.details);

        // User confirms the transaction
        if (userConfirms()) {
         transaction.confirm()
        } else {
        transaction.cancel()
        }
    }

    if(transaction.status == TransactionStatus.done) {
        /// display result to user [sucess, error]
        displayTransactionResult(transaction);
    }

  });
}

Flow:

1. Listen to pending transaction
2. Initiate the transaction by calling a function.
3. React to pending transactions and confirm/decline them
4. React to transaction completed

Consequences

The reactive nature of transactions makes it necessary to use some form of subscriptions. Using this approach, the available options to the user/dev are quite clear.

• Pros

  • Clear separations of what options are available at a given time.
  • Data is directly available; no need to call a getter
  • Setup for the user/dev is structured
  • Clear separation between pending and final.
  • Does not necessarily require cashu/implementation knowledge

• Cons

  • Requires subscription management for the user/dev
  • More complex to implement (for us)
  • less control for the user/dev, although we can expose methods if more control is needed.

Alternative proposals

Use functions for each transaction step and user/dev uses them manualy. pro: - a lot more control con: - more complex, requires cashu knolege

Final Notes

13-08-2025 Proposal dismissed Proceeding with a simpler method-based approach in combination with transaction streams.