Cashu wallet

doc/library-development/ADRs/wallet-cashu.md

@@ -0,0 +1,103 @@
+# 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:
+
+```dart
+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.

doc/usecases/cashu.md

@@ -0,0 +1,182 @@
+---
+icon: fiscal-host
+title: cashu - eCash
+---
+
+[!badge variant="primary" text="high level"]
+
+!!!danger experimental
+DO NOT USE IN PRODUCTION!
+!!!
+
+!!!
+no recovery option, if the user deletes the db (by resetting the app) funds are lost \
+This API is `experimental` you can try it and submit your feedback.
+!!!
+
+## When to use
+
+Cashu usecase can manage eCash (digital cash) within your application. It provides functionalities for funding, spending, and receiving eCash tokens.
+
+## Examples
+
+## add mint url
+
+!!!
+When you receive tokens or initiate funding, the mint gets added automatically
+!!!
+
+```dart
+/// adds to known mints
+ndk.cashu.addMintToKnownMints(mintUrl: "https://example.mint");
+
+/// stream [Set<CashuMintInfo>] of known mints
+ndk.cashu.knownMints;
+
+/// get [CashuMintInfo] without adding it to known mints
+ndk.cashu.getMintInfoNetwork(mintUrl: "https://example.mint");
+
+```
+
+## fund (mint)
+
+```dart
+    final initTransaction = await ndk.cashu.initiateFund(
+        mintUrl: "https://example.mint",
+        amount: "100",
+        unit: "sat",
+        method: "bolt11",
+        memo: "funding example",
+      );
+
+    /// pay the request (usually lnbc1...)
+    print(initTransaction.qoute!.request);
+
+    /// retrieve funds and listen for status
+    final resultStream =
+          ndk.cashu.retrieveFunds(draftTransaction: initTransaction);
+
+      await for (final result in resultStream) {
+        if (result.state == ndk_entities.WalletTransactionState.completed) {
+          /// transcation done
+          print(result.completionMsg);
+        } else if (result.state == ndk_entities.WalletTransactionState.pending) {
+          /// pending
+        }
+         else if (result.state == ndk_entities.WalletTransactionState.failed) {
+          /// transcation done
+          print(result.completionMsg);
+        }
+      }
+
+```
+
+## redeem (melt)
+
+```dart
+
+    final draftTransaction = await ndk.cashu.initiateRedeem(
+        mintUrl: "https://example.mint",
+        request: "lnbc1...",
+        unit: "sat"
+        method: "bolt11",
+    );
+
+    /// check if everything is ok (fees etc)
+    print(draftTransaction.qouteMelt.feeReserve);
+
+    /// redeem funds and listen for status
+    final resultStream =
+        ndk.cashu.redeem(draftTransaction: draftTransaction);
+
+    await for (final result in resultStream) {
+    if (result.state == ndk_entities.WalletTransactionState.completed) {
+        /// transcation done
+        print(result.completionMsg);
+    } else if (result.state == ndk_entities.WalletTransactionState.pending) {
+        /// pending
+    }
+    else if (result.state == ndk_entities.WalletTransactionState.failed) {
+        /// transcation done
+        print(result.completionMsg);
+    }
+    }
+
+
+```
+
+## spend
+
+```dart
+    final spendResult = await ndk.cashu.initiateSpend(
+        mintUrl: "https://example.mint",
+        amount: 5,
+        unit: "sat",
+        memo: "spending example",
+    );
+
+    print("token to spend: ${spendResult.token.toV4TokenString()}");
+    print("transaction id: ${spendResult.transaction}");
+
+    /// listen to pending transactions List<CashuWalletTransaction>
+    await for (final transaction in ndk.cashu.pendingTransactions) {
+      print("latest transaction: $transaction");
+    }
+
+    /// listen to recent transactinos List<CashuWalletTransaction>
+    await for (final transaction in ndk.cashu.latestTransactions) {
+      print("latest transaction: $transaction");
+    }
+
+
+```
+
+## receive
+
+```dart
+
+      final rcvResultStream = _ndk.cashu.receive(tokenString);
+
+      await for (final rcvResult in rcvResultStream) {
+        if (rcvResult.state == ndk_entities.WalletTransactionState.pending) {
+            /// pending
+        } else if (rcvResult.state ==
+            ndk_entities.WalletTransactionState.completed) {
+            /// completed
+        } else if (rcvResult.state ==
+            ndk_entities.WalletTransactionState.failed) {
+            /// failed
+            print(result.completionMsg);
+        }
+      }
+
+```
+
+!!!
+All transactions are also available via `pendingTransactions` and `latestTransactions` streams.\
+As well as in the `Wallets` usecase
+!!!
+
+## check balance
+
+```dart
+    /// balances for all mints [List<CashuMintBalance>]
+    final balances = await ndk.cashu.getBalances();
+    print(balances);
+
+    /// balance for one mint and unit [int]
+    final singleBalance = await getBalanceMintUnit(
+      mintUrl: "https://example.mint",
+      unit: "sat",
+    );
+
+    /// stream of [List<CashuMintBalance>]
+    ndk.cashu.balances;
+
+```
+
+!!!
+balances are also available via `Wallets` usecase
+!!!
+
+

doc/usecases/lists.md

@@ -18,7 +18,7 @@ icon: list-unordered
       print("set not found");
       return;
     }
-    print("recived a set with ${myset.elements.length} elements");
+    print("receive a set with ${myset.elements.length} elements");
 
 ```
 

doc/usecases/wallets.md

@@ -0,0 +1,92 @@
+---
+icon: credit-card
+---
+
+[!badge variant="primary" text="high level"]
+
+!!!danger experimental
+DO NOT USE IN PRODUCTION!
+!!!
+
+## When to use
+
+`Wallets` usecase manages combines multiple wallets (e.g., Cashu, NWC) within your application. It provides functionalities for creating, managing, and transacting.
+If you build a transaction history or other reporting, you are advised to use this use case. You can switch or use multiple wallets and still have a unified transaction history.
+
+## Examples
+
+### balances
+
+```dart
+/// balances of all wallets, split into walletId and unit
+/// returns Stream<List<WalletBalance>>
+final balances = await ndk.wallets.combinedBalances;
+
+/// get combined balance of all wallets in a specific unit
+/// returns int
+final combinedSat = ndk.wallets.getCombinedBalance("sat");
+```
+
+### transactions
+
+```dart
+/// get all pending transactions, fires immediately and on every change
+/// returns Stream<List<WalletTransaction>>
+final pendingTransactions = await ndk.wallets.combinedPendingTransactions;
+
+
+/// get all recent transactions, fires immediately and on every change
+/// returns Stream<List<WalletTransaction>>
+final recentTransactions = await ndk.wallets.combinedRecentTransactions;
+
+/// get all transactions, with pagination and filtering options
+/// returns Future<List<WalletTransaction>>
+final transactions = await ndk.wallets.combinedTransactions(
+  limit: 100, // optional
+  offset: 0, // optional, pagination
+   walletId: "mywalletId", // optional
+   unit: "sat", // optional
+   walletType: WalletType.cashu, // optional
+);
+```
+
+### wallets
+
+```dart
+
+/// get all wallets
+/// returns Stream<List<Wallet>>
+final wallets = ndk.wallets.walletsStream;
+
+/// get default wallet
+/// returns Wallet?
+final defaultWallet = ndk.wallets.defaultWallet;
+
+
+await ndk.wallets.addWallet(myWallet);
+
+setDefaultWallet("myWalletId");
+
+
+await ndk.wallets.removeWalet("myWalletId");
+
+/// get all wallets supporting a specific unit
+/// returns List<Wallet>
+final walletsSupportingSat = ndk.wallets.getWalletsForUnit("sat");
+
+```
+
+### actions
+
+The wallets usecase provides unified actions that work across different wallet types. (WIP)
+
+```dart
+
+///! WIP none of the params are final
+final zapResult = await ndk.wallets.zap(
+    pubkey: "pubkeyToZap",
+    amount: 10,
+    comment: "Hello World",
+  );
+
+```