applesauce-wallet 6.1.0 → 6.2.0

package/dist/actions/nutzaps.d.ts

@@ -1,9 +1,11 @@
-import { Token } from "@cashu/cashu-ts";
+import { Token, Wallet } from "@cashu/cashu-ts";
 import { Action } from "applesauce-actions";
 import { NostrEvent } from "applesauce-core/helpers/event";
 import { ProfilePointer } from "applesauce-core/helpers/pointers";
 import { Couch } from "../helpers/couch.js";
 import "../casts/__register__.js";
+/** A function that returns a loaded cashu {@link Wallet} for a mint url */
+type CashuWalletProvider = (mint: string) => Promise<Wallet>;
 /** Creates a NIP-61 nutzap event for an event with a token */
 export declare function NutzapEvent(event: NostrEvent, token: Token, options?: {
     comment?: string;
@@ -20,5 +22,7 @@ export declare function NutzapProfile(user: string | ProfilePointer, token: Toke
  * Supports nutzaps with different mints by grouping them by mint and redeeming each group separately
  * @param nutzaps single nutzap event or array of nutzap events
  * @param couch optional couch interface for temporarily storing tokens during the operation
+ * @param getCashuWallet optional provider returning a cached cashu Wallet for a mint
  */
-export declare function ReceiveNutzaps(nutzaps: NostrEvent | NostrEvent[], couch?: Couch): Action;
+export declare function ReceiveNutzaps(nutzaps: NostrEvent | NostrEvent[], couch?: Couch, getCashuWallet?: CashuWalletProvider): Action;
+export {};

package/dist/actions/nutzaps.js

@@ -4,11 +4,22 @@ import { bytesToHex } from "applesauce-core/helpers/event";
 import { WalletHistoryFactory } from "../factories/history.js";
 import { WalletTokenFactory } from "../factories/tokens.js";
 import { NutzapFactory } from "../factories/nutzap.js";
-import { verifyProofsLocked } from "../helpers/nutzap-info.js";
+import { getNutzapInfoMints, verifyProofsLocked } from "../helpers/nutzap-info.js";
 import { getNutzapMint, getNutzapProofs, isValidNutzap } from "../helpers/nutzap.js";
 import { getUnlockedWallet } from "./common.js";
 // Make sure the nutzap$ is registered on the user class
 import "../casts/__register__.js";
+/**
+ * Returns a loaded cashu {@link Wallet} for a mint url. Uses the `getCashuWallet` provider when given
+ * (so a caller can supply a cached, wallet-specific instance), otherwise creates and loads a fresh wallet.
+ */
+async function loadCashuWallet(mint, options) {
+    if (options?.getCashuWallet)
+        return options.getCashuWallet(mint);
+    const wallet = new Wallet(mint);
+    await wallet.loadMint();
+    return wallet;
+}
 /** Creates a NIP-61 nutzap event for an event with a token */
 export function NutzapEvent(event, token, options) {
     return async ({ events, signer, user, publish }) => {
@@ -22,17 +33,20 @@ export function NutzapEvent(event, token, options) {
             const info = await recipient.nutzap$.$first(5000, undefined);
             if (!info)
                 throw new Error("Nutzap info not found");
-            // Get the users wallet
-            const wallet = await getUnlockedWallet(user, signer);
+            // Ensure the user's wallet exists and is unlocked
+            await getUnlockedWallet(user, signer);
+            if (!getNutzapInfoMints(info.event).some(({ mint }) => mint === token.mint))
+                throw new Error("Token mint is not listed in the recipient's nutzap info");
             // Verify all tokens are p2pk locked
             verifyProofsLocked(token.proofs, info.event);
             // Create the nutzap event
             const nutzap = await NutzapFactory.forEvent(event, token, comment || token.memo).sign(signer);
             // Publish the nutzap event
-            await publish(nutzap, wallet.relays);
+            await publish(nutzap, info.relays);
+        }
+        finally {
+            await clearStoredToken?.();
         }
-        catch { }
-        await clearStoredToken?.();
     };
 }
 /** Creates a NIP-61 nutzap event to a users profile */
@@ -48,6 +62,8 @@ export function NutzapProfile(user, token, options) {
             const info = await recipient.nutzap$.$first(5000, undefined);
             if (!info)
                 throw new Error("Nutzap info not found");
+            if (!getNutzapInfoMints(info.event).some(({ mint }) => mint === token.mint))
+                throw new Error("Token mint is not listed in the recipient's nutzap info");
             // Verify all tokens are p2pk locked
             verifyProofsLocked(token.proofs, info.event);
             // Create the nutzap event
@@ -55,8 +71,9 @@ export function NutzapProfile(user, token, options) {
             // Publish the nutzap event
             await publish(nutzap, info.relays);
         }
-        catch { }
-        await clearStoredToken?.();
+        finally {
+            await clearStoredToken?.();
+        }
     };
 }
 /**
@@ -65,8 +82,9 @@ export function NutzapProfile(user, token, options) {
  * Supports nutzaps with different mints by grouping them by mint and redeeming each group separately
  * @param nutzaps single nutzap event or array of nutzap events
  * @param couch optional couch interface for temporarily storing tokens during the operation
+ * @param getCashuWallet optional provider returning a cached cashu Wallet for a mint
  */
-export function ReceiveNutzaps(nutzaps, couch) {
+export function ReceiveNutzaps(nutzaps, couch, getCashuWallet) {
     return async ({ signer, user, publish }) => {
         if (!signer)
             throw new Error("Missing signer");
@@ -113,8 +131,7 @@ export function ReceiveNutzaps(nutzaps, couch) {
                     unit: "sat",
                 };
                 // Use cashu-ts to receive/unlock the P2PK-locked token
-                const cashuWallet = new Wallet(mint);
-                await cashuWallet.loadMint();
+                const cashuWallet = await loadCashuWallet(mint, { getCashuWallet });
                 // Receive the token using the new wallet.ops API
                 // This will swap P2PK-locked proofs with unlocked proofs
                 let receivedProofs;
@@ -125,7 +142,7 @@ export function ReceiveNutzaps(nutzaps, couch) {
                     throw new Error(`Failed to receive token for mint ${mint}: ${error instanceof Error ? error.message : String(error)}`);
                 }
                 // Calculate total amount
-                const amount = sumProofs(receivedProofs);
+                const amount = sumProofs(receivedProofs).toNumber();
                 // Create token event with received unlocked proofs
                 const receivedToken = {
                     mint,

package/dist/actions/tokens.d.ts

@@ -1,8 +1,10 @@
-import { Proof, Token, Wallet } from "@cashu/cashu-ts";
+import { MintQuoteBolt11Response, Proof, ProofLike, Token, Wallet } from "@cashu/cashu-ts";
 import { Action } from "applesauce-actions";
 import { NostrEvent } from "applesauce-core/helpers/event";
 import { Couch } from "../helpers/couch.js";
 import "../casts/__register__.js";
+/** A function that returns a loaded cashu {@link Wallet} for a mint url */
+type CashuWalletProvider = (mint: string) => Promise<Wallet>;
 /**
  * Adds a cashu token to the wallet and creates a history event
  * @param token the cashu token to add
@@ -17,21 +19,102 @@ export declare function AddToken(token: Token, options?: {
 export declare function ReceiveToken(token: Token, options?: {
     addHistory?: boolean;
     couch?: Couch;
+    wallet?: Wallet;
+    getCashuWallet?: CashuWalletProvider;
 }): Action;
-/** An action that deletes old tokens and creates a new one but does not add a history event */
-export declare function RolloverTokens(tokens: NostrEvent[], token: Token): Action;
-/** An action that deletes old token events and adds a spend history item */
-export declare function CompleteSpend(spent: NostrEvent[], change: Token, couch?: Couch): Action;
-/** Combines all unlocked token events into a single event per mint */
+/**
+ * A method-agnostic action that mints new proofs from a paid mint quote and adds them to the wallet.
+ * The `mintProofs` callback performs the payment-method-specific mint call (bolt11, bolt12, onchain, …)
+ * against the loaded cashu {@link Wallet}; everything else (couch safety + token/history bookkeeping) is
+ * shared. {@link MintTokens} is the bolt11 wrapper over this action.
+ * @param mint the mint url to mint the proofs from
+ * @param mintProofs a callback that mints and returns the new proofs for the paid quote
+ * @param options.couch optional couch interface for temporarily storing the minted token
+ * @param options.wallet optional pre-loaded cashu Wallet for the mint
+ * @param options.getCashuWallet optional provider returning a cached cashu Wallet for a mint
+ */
+export declare function MintProofs(mint: string, mintProofs: (cashuWallet: Wallet) => Promise<Proof[]>, options?: {
+    couch?: Couch;
+    wallet?: Wallet;
+    getCashuWallet?: CashuWalletProvider;
+}): Action;
+/**
+ * Mints new proofs from an already-paid bolt11 mint quote and adds them to the wallet.
+ * A thin bolt11 wrapper over {@link MintProofs}.
+ * @param mint the mint url to mint the proofs from
+ * @param amount the amount of the paid mint quote in sats
+ * @param quote the paid mint quote id or response
+ * @param options.couch optional couch interface for temporarily storing the minted token
+ * @param options.wallet optional pre-loaded cashu Wallet for the mint
+ * @param options.getCashuWallet optional provider returning a cached cashu Wallet for a mint
+ */
+export declare function MintTokens(mint: string, amount: number, quote: string | MintQuoteBolt11Response, options?: {
+    couch?: Couch;
+    wallet?: Wallet;
+    getCashuWallet?: CashuWalletProvider;
+}): Action;
+/**
+ * An action that deletes old token events and adds a spend history item
+ * @param options.createDeleteEvents whether to publish a NIP-09 delete event for the spent token events
+ *   (default true). The change token event always references the spent ids in its `del` field, so the
+ *   wallet can reconcile its balance without the delete event; skipping it saves a signing operation at
+ *   the cost of leaving the spent token events on relays until {@link CleanupDeletedTokens}.
+ * @param options.couch optional couch interface for temporarily storing the change token
+ */
+export declare function CompleteSpend(spent: NostrEvent[], change: Token, options?: {
+    couch?: Couch;
+    createDeleteEvents?: boolean;
+}): Action;
+/**
+ * Combines all unlocked token events into a single event per mint
+ * @param options.createDeleteEvents whether to publish a single batched NIP-09 delete event for the old
+ *   token events (default true). The new token events always reference the old ids in their `del` field.
+ */
 export declare function ConsolidateTokens(options?: {
     unlockTokens?: boolean;
+    getCashuWallet?: CashuWalletProvider;
+    createDeleteEvents?: boolean;
+}): Action;
+/**
+ * Rolls every unlocked token over to a fresh cashu token. For each mint the proofs are swapped at the mint
+ * (rotating the secrets) and a single new token event is created whose `del` field references the
+ * rolled-over token events. Token events that another token has already marked as deleted are skipped so a
+ * repeated rollover does not try to swap already-spent proofs.
+ *
+ * To keep signer operations to a minimum, every new token event is published together with a *single*
+ * batched NIP-09 delete event covering the rolled-over token events across *all* mints — never one delete
+ * per mint.
+ *
+ * @param options.createDeleteEvents whether to publish the single batched NIP-09 delete event (default true).
+ *   The new token events always reference the old ids in their `del` field, so the wallet can reconcile its
+ *   balance without the delete event; skipping it leaves the spent token events on relays until
+ *   {@link CleanupDeletedTokens} removes them.
+ * @param options.couch optional couch used to keep each fresh token safe until its token event is published
+ */
+export declare function RolloverTokens(options?: {
+    unlockTokens?: boolean;
+    couch?: Couch;
+    getCashuWallet?: CashuWalletProvider;
+    createDeleteEvents?: boolean;
 }): Action;
 /**
- * Recovers tokens from a couch by checking if they exist in the wallet,
- * verifying they are unspent, and creating token events for any recoverable tokens
+ * Detects token events that have been marked as deleted by a newer token event's `del` field but are
+ * still present, and publishes a single NIP-09 delete event for them. Use this to clean up the old
+ * token events left behind when operations run with `createDeleteEvents: false`, batching what would
+ * otherwise be many per-operation delete events into a single signing operation.
+ */
+export declare function CleanupDeletedTokens(): Action;
+/**
+ * Recovers tokens from a couch by checking if they exist in the wallet, verifying they are unspent, and
+ * creating token events for any recoverable proofs. Once every token has been processed the couch is
+ * cleared, so tokens that are already in the wallet or have been spent are cleaned out too. Any token
+ * whose recovered token event failed to publish is left in the couch so it can be retried on a later run.
  * @param couch the couch interface to recover tokens from
+ * @param options.getCashuWallet optional provider returning a cached cashu Wallet for a mint
  */
-export declare function RecoverFromCouch(couch: Couch): Action;
+export declare function RecoverFromCouch(couch: Couch, options?: {
+    getCashuWallet?: CashuWalletProvider;
+}): Action;
 /**
  * Token selection function type that matches dumbTokenSelection signature.
  * Must return tokens from a single mint and ensure all selected tokens are from that mint.
@@ -39,7 +122,7 @@ export declare function RecoverFromCouch(couch: Couch): Action;
  */
 export type TokenSelectionFunction = (tokens: NostrEvent[], minAmount: number, mint?: string) => {
     events: NostrEvent[];
-    proofs: Proof[];
+    proofs: ProofLike[];
 };
 /**
  * A generic action that safely selects tokens, performs an async operation, and handles change.
@@ -75,7 +158,7 @@ export type TokenSelectionFunction = (tokens: NostrEvent[], minAmount: number, m
  * }, { couch, tokenSelection: myCustomSelectionFunction });
  */
 export declare function TokensOperation(minAmount: number, operation: (params: {
-    selectedProofs: Proof[];
+    selectedProofs: ProofLike[];
     mint: string;
     cashuWallet: Wallet;
 }) => Promise<{
@@ -84,4 +167,8 @@ export declare function TokensOperation(minAmount: number, operation: (params: {
     mint?: string;
     couch: Couch;
     tokenSelection?: TokenSelectionFunction;
+    wallet?: Wallet;
+    getCashuWallet?: CashuWalletProvider;
+    createDeleteEvents?: boolean;
 }): Action;
+export {};