refactor: replace raw bigint with Amount VO on Proof and BlindedMessage

docs-src/usage/melt_token.md

@@ -45,7 +45,8 @@ const { send: proofsToSend } = await wallet.send(amountToSend, proofs, {
 
 const meltPreview = await wallet.prepareMelt('bolt11', meltQuote, proofsToSend);
 
-await saveMeltPreview(meltPreview);
+// Persist an app-defined snapshot here.
+// Do not call JSON.stringify(meltPreview) directly; preview objects contain non-JSON-safe values.
 const meltResponse = await wallet.completeMelt(meltPreview);
 ```
 

docs-src/usage/mint_token.md

@@ -39,12 +39,13 @@ if (mintQuoteChecked.state !== MintQuoteState.PAID) {
   throw new Error('Mint quote is not paid yet');
 }
 
-const preview = await wallet.prepareMint('bolt11', 64, mintQuote.quote, undefined, {
+const preview = await wallet.prepareMint('bolt11', 64, mintQuoteChecked, undefined, {
   type: 'deterministic',
   counter: 0,
 });
 
-// Persist `preview` here if you want to retry safely later.
+// Persist an app-defined snapshot here if you want to retry safely later.
+// Do not call JSON.stringify(preview) directly; preview objects contain non-JSON-safe values.
 const proofs = await wallet.completeMint(preview);
 ```
 

docs-src/usage/nut19.md

@@ -95,12 +95,16 @@ operations that create blinded outputs.
 ### Mint
 
 ```ts
-const mintPreview = await wallet.prepareMint('bolt11', 64, quoteId, undefined, {
+const mintQuote = await wallet.checkMintQuoteBolt11(quoteId);
+
+const mintPreview = await wallet.prepareMint('bolt11', 64, mintQuote, undefined, {
   type: 'deterministic',
   counter: 0,
 });
 
-await saveMintPreview(mintPreview); // your save function
+// Persist an app-defined snapshot here.
+// Do not call JSON.stringify(mintPreview) directly; preview objects contain
+// Amount, bigint, Uint8Array, and class instances that need explicit rehydration.
 const proofs = await wallet.completeMint(mintPreview);
 ```
 
@@ -111,7 +115,9 @@ const meltPreview = await wallet.prepareMelt('bolt11', meltQuote, proofsToSend,
   includeFees: true,
 });
 
-await saveMeltPreview(meltPreview); // your save function
+// Persist an app-defined serialized snapshot here.
+// Do not call JSON.stringify(meltPreview) directly; preview objects contain
+// Amount, bigint, Uint8Array, and class instances that need explicit rehydration.
 const result = await wallet.completeMelt(meltPreview);
 ```
 

etc/cashu-ts.api.md

@@ -47,7 +47,7 @@ export class Amount {
     // (undocumented)
     static sum(values: Iterable<AmountLike>): Amount;
     toBigInt(): bigint;
-    toJSON(): number | string;
+    toJSON(): string;
     toNumber(): number;
     toNumberUnsafe(): number;
     toString(): string;
@@ -60,7 +60,7 @@ export class AmountError extends Error {
     constructor(message: string);
 }
 
-// @public (undocumented)
+// @public
 export type AmountLike = number | bigint | string | Amount;
 
 // @public
@@ -644,7 +644,7 @@ export const meetsSignerThreshold: (signatures: string[], message: string, pubke
 
 // @public
 export class MeltBuilder<TQuote extends Pick<MeltQuoteBaseResponse, 'amount' | 'quote'> = MeltQuoteBolt11Response> {
-    constructor(wallet: Wallet, method: string, quote: TQuote, proofs: Proof[]);
+    constructor(wallet: Wallet, method: string, quote: TQuote, proofs: ProofLike[]);
     asCustom(data: OutputDataLike[]): this;
     asDeterministic(counter?: number, denoms?: AmountLike[]): this;
     asFactory(factory: OutputDataFactory, denoms?: AmountLike[]): this;
@@ -828,7 +828,7 @@ export class MintBuilder<M extends MintMethod, HasPrivKey extends boolean = M ex
     onCountersReserved(cb: OnCountersReserved): this;
     prepare(this: MintBuilder<M, true>): Promise<M extends 'bolt11' ? MintPreview<MintQuoteBolt11Response> : MintPreview<MintQuoteBolt12Response>>;
     privkey(k: string): MintBuilder<M, true>;
-    proofsWeHave(p: Array<Pick<Proof, 'amount'>>): this;
+    proofsWeHave(p: Array<Pick<ProofLike, 'amount'>>): this;
     run(this: MintBuilder<M, true>): Promise<Proof[]>;
 }
 
@@ -1004,7 +1004,7 @@ export interface MintPreview<TQuote extends Pick<MintQuoteBaseResponse, 'quote'>
 export type MintProofsConfig = {
     keysetId?: string;
     privkey?: string | string[];
-    proofsWeHave?: Array<Pick<Proof, 'amount'>>;
+    proofsWeHave?: Array<Pick<ProofLike, 'amount'>>;
     onCountersReserved?: OnCountersReserved;
 };
 
@@ -1408,7 +1408,7 @@ export type PrivKey = Uint8Array | string;
 // @public
 export type Proof = {
     id: string;
-    amount: bigint;
+    amount: Amount;
     secret: string;
     C: string;
     dleq?: SerializedDLEQ;
@@ -1475,7 +1475,7 @@ export type RawTransport = {
 
 // @public
 export class ReceiveBuilder {
-    constructor(wallet: Wallet, token: Token | string | Proof[]);
+    constructor(wallet: Wallet, token: Token | string | ProofLike[]);
     asCustom(data: OutputDataLike[]): this;
     asDeterministic(counter?: number, denoms?: AmountLike[]): this;
     asFactory(factory: OutputDataFactory, denoms?: AmountLike[]): this;
@@ -1485,7 +1485,7 @@ export class ReceiveBuilder {
     onCountersReserved(cb: OnCountersReserved): this;
     prepare(): Promise<SwapPreview>;
     privkey(k: string | string[]): this;
-    proofsWeHave(p: Array<Pick<Proof, 'amount'>>): this;
+    proofsWeHave(p: Array<Pick<ProofLike, 'amount'>>): this;
     requireDleq(on?: boolean): this;
     run(): Promise<Proof[]>;
 }
@@ -1495,7 +1495,7 @@ export type ReceiveConfig = {
     keysetId?: string;
     privkey?: string | string[];
     requireDleq?: boolean;
-    proofsWeHave?: Array<Pick<Proof, 'amount'>>;
+    proofsWeHave?: Array<Pick<ProofLike, 'amount'>>;
     onCountersReserved?: OnCountersReserved;
 };
 
@@ -1563,14 +1563,14 @@ export type SecretKind = 'P2PK' | 'HTLC' | (string & {});
 export type SecretsPolicy = 'auto' | 'deterministic' | 'random';
 
 // @public (undocumented)
-export type SelectProofs = (proofs: Proof[], amountToSelect: AmountLike, keyChain: KeyChain, includeFees?: boolean, exactMatch?: boolean, logger?: Logger) => SendResponse;
+export type SelectProofs = (proofs: ProofLike[], amountToSelect: AmountLike, keyChain: KeyChain, includeFees?: boolean, exactMatch?: boolean, logger?: Logger) => SendResponse;
 
 // @public (undocumented)
-export function selectProofsRGLI(proofs: Proof[], amountToSelect: AmountLike, keyChain: KeyChain, includeFees?: boolean, exactMatch?: boolean, _logger?: Logger): SendResponse;
+export function selectProofsRGLI(proofs: ProofLike[], amountToSelect: AmountLike, keyChain: KeyChain, includeFees?: boolean, exactMatch?: boolean, _logger?: Logger): SendResponse;
 
 // @public
 export class SendBuilder {
-    constructor(wallet: Wallet, amount: AmountLike, proofs: Proof[]);
+    constructor(wallet: Wallet, amount: AmountLike, proofs: ProofLike[]);
     asCustom(data: OutputDataLike[]): this;
     asDeterministic(counter?: number, denoms?: AmountLike[]): this;
     asFactory(factory: OutputDataFactory, denoms?: AmountLike[]): this;
@@ -1588,7 +1588,7 @@ export class SendBuilder {
     onCountersReserved(cb: OnCountersReserved): this;
     prepare(): Promise<SwapPreview>;
     privkey(k: string | string[]): this;
-    proofsWeHave(p: Array<Pick<Proof, 'amount'>>): this;
+    proofsWeHave(p: Array<Pick<ProofLike, 'amount'>>): this;
     run(): Promise<SendResponse>;
 }
 
@@ -1597,7 +1597,7 @@ export type SendConfig = {
     keysetId?: string;
     privkey?: string | string[];
     includeFees?: boolean;
-    proofsWeHave?: Array<Pick<Proof, 'amount'>>;
+    proofsWeHave?: Array<Pick<ProofLike, 'amount'>>;
     onCountersReserved?: OnCountersReserved;
 };
 
@@ -1620,7 +1620,7 @@ export type SendResponse = {
 
 // @public
 export type SerializedBlindedMessage = {
-    amount: bigint;
+    amount: Amount;
     B_: string;
     id: string;
 };
@@ -1735,7 +1735,7 @@ export type SubscribeOpts = {
 export type SubscriptionCanceller = () => void;
 
 // @public
-export function sumProofs(proofs: Array<Pick<Proof, 'amount'>>): Amount;
+export function sumProofs(proofs: Array<Pick<ProofLike, 'amount'>>): Amount;
 
 // @public
 export type SwapMethod = {
@@ -1752,8 +1752,8 @@ export type SwapMethod = {
 
 // @public
 export type SwapPreview = {
-    amount: AmountLike;
-    fees: AmountLike;
+    amount: Amount;
+    fees: Amount;
     keysetId: string;
     inputs: Proof[];
     sendOutputs?: OutputDataLike[];
@@ -1909,9 +1909,9 @@ export class Wallet {
     loadMintFromCache(mintInfo: GetInfoResponse, cache: KeyChainCache): void;
     // (undocumented)
     get logger(): Logger;
-    meltProofs<TQuote extends Pick<MeltQuoteBaseResponse, 'amount' | 'quote'>>(method: string, meltQuote: TQuote, proofsToSend: Proof[], config?: MeltProofsConfig, outputType?: OutputType): Promise<MeltProofsResponse<TQuote>>;
-    meltProofsBolt11(meltQuote: MeltQuoteBolt11Response, proofsToSend: Proof[], config?: MeltProofsConfig, outputType?: OutputType): Promise<MeltProofsResponse<MeltQuoteBolt11Response>>;
-    meltProofsBolt12(meltQuote: MeltQuoteBolt12Response, proofsToSend: Proof[], config?: MeltProofsConfig, outputType?: OutputType): Promise<MeltProofsResponse<MeltQuoteBolt12Response>>;
+    meltProofs<TQuote extends Pick<MeltQuoteBaseResponse, 'amount' | 'quote'>>(method: string, meltQuote: TQuote, proofsToSend: ProofLike[], config?: MeltProofsConfig, outputType?: OutputType): Promise<MeltProofsResponse<TQuote>>;
+    meltProofsBolt11(meltQuote: MeltQuoteBolt11Response, proofsToSend: ProofLike[], config?: MeltProofsConfig, outputType?: OutputType): Promise<MeltProofsResponse<MeltQuoteBolt11Response>>;
+    meltProofsBolt12(meltQuote: MeltQuoteBolt12Response, proofsToSend: ProofLike[], config?: MeltProofsConfig, outputType?: OutputType): Promise<MeltProofsResponse<MeltQuoteBolt12Response>>;
     readonly mint: Mint;
     mintProofs<TQuote extends Pick<MintQuoteBaseResponse, 'quote'>>(method: string, amount: AmountLike, quote: TQuote, config?: MintProofsConfig, outputType?: OutputType): Promise<Proof[]>;
     mintProofsBolt11(amount: AmountLike, quote: string | MintQuoteBolt11Response, config?: MintProofsConfig, outputType?: OutputType): Promise<Proof[]>;
@@ -1924,19 +1924,19 @@ export class Wallet {
         amount: AmountLike;
         quote: TQuote;
     }>, config?: MintProofsConfig, outputType?: OutputType): Promise<BatchMintPreview<TQuote>>;
-    prepareMelt<TQuote extends Pick<MeltQuoteBaseResponse, 'amount' | 'quote'>>(method: string, meltQuote: TQuote, proofsToSend: Proof[], config?: MeltProofsConfig, outputType?: OutputType): Promise<MeltPreview<TQuote>>;
+    prepareMelt<TQuote extends Pick<MeltQuoteBaseResponse, 'amount' | 'quote'>>(method: string, meltQuote: TQuote, proofsToSend: ProofLike[], config?: MeltProofsConfig, outputType?: OutputType): Promise<MeltPreview<TQuote>>;
     prepareMint<TQuote extends Pick<MintQuoteBaseResponse, 'quote'>>(method: string, amount: AmountLike, quote: TQuote, config?: MintProofsConfig, outputType?: OutputType): Promise<MintPreview<TQuote>>;
-    prepareSwapToReceive(token: Token | string | Proof[], config?: ReceiveConfig, outputType?: OutputType): Promise<SwapPreview>;
-    prepareSwapToSend(amount: AmountLike, proofs: Proof[], config?: SendConfig, outputConfig?: OutputConfig): Promise<SwapPreview>;
-    receive(token: Token | string | Proof[], config?: ReceiveConfig, outputType?: OutputType): Promise<Proof[]>;
+    prepareSwapToReceive(token: Token | string | ProofLike[], config?: ReceiveConfig, outputType?: OutputType): Promise<SwapPreview>;
+    prepareSwapToSend(amount: AmountLike, proofs: ProofLike[], config?: SendConfig, outputConfig?: OutputConfig): Promise<SwapPreview>;
+    receive(token: Token | string | ProofLike[], config?: ReceiveConfig, outputType?: OutputType): Promise<Proof[]>;
     restore(start: number, count: number, config?: RestoreConfig): Promise<{
         proofs: Proof[];
         lastCounterWithSignature?: number;
     }>;
     selectProofsToSend(proofs: Proof[], amountToSend: AmountLike, includeFees?: boolean, exactMatch?: boolean): SendResponse;
-    send(amount: AmountLike, proofs: Proof[], config?: SendConfig, outputConfig?: OutputConfig): Promise<SendResponse>;
-    sendOffline(amount: AmountLike, proofs: Proof[], config?: SendOfflineConfig): SendResponse;
-    signP2PKProofs(proofs: Proof[], privkey: string | string[], outputData?: OutputDataLike[], quoteId?: string): Proof[];
+    send(amount: AmountLike, proofs: ProofLike[], config?: SendConfig, outputConfig?: OutputConfig): Promise<SendResponse>;
+    sendOffline(amount: AmountLike, proofs: ProofLike[], config?: SendOfflineConfig): SendResponse;
+    signP2PKProofs(proofs: ProofLike[], privkey: string | string[], outputData?: OutputDataLike[], quoteId?: string): Proof[];
     get unit(): string;
     withKeyset(id: string, opts?: {
         counterSource?: CounterSource;
@@ -1995,17 +1995,17 @@ export class WalletEvents {
 export class WalletOps {
     constructor(wallet: Wallet);
     // (undocumented)
-    meltBolt11(quote: MeltQuoteBolt11Response, proofs: Proof[]): MeltBuilder<MeltQuoteBolt11Response>;
+    meltBolt11(quote: MeltQuoteBolt11Response, proofs: ProofLike[]): MeltBuilder<MeltQuoteBolt11Response>;
     // (undocumented)
-    meltBolt12(quote: MeltQuoteBolt12Response, proofs: Proof[]): MeltBuilder<MeltQuoteBolt11Response>;
+    meltBolt12(quote: MeltQuoteBolt12Response, proofs: ProofLike[]): MeltBuilder<MeltQuoteBolt11Response>;
     // (undocumented)
     mintBolt11(amount: AmountLike, quote: MintQuoteFor<'bolt11'>): MintBuilder<"bolt11", true>;
     // (undocumented)
     mintBolt12(amount: AmountLike, quote: MintQuoteFor<'bolt12'>): MintBuilder<"bolt12", false>;
     // (undocumented)
-    receive(token: Token | string | Proof[]): ReceiveBuilder;
+    receive(token: Token | string | ProofLike[]): ReceiveBuilder;
     // (undocumented)
-    send(amount: AmountLike, proofs: Proof[]): SendBuilder;
+    send(amount: AmountLike, proofs: ProofLike[]): SendBuilder;
 }
 
 // @public

examples/auth_mint/auth_device_example.ts

@@ -82,7 +82,7 @@ async function main() {
   const proofs = await wallet.mintProofsBolt11(100, request);
   console.log(
     '\nMinted 100 sats.',
-    proofs.map((p) => p.amount),
+    proofs.map((p) => p.amount.toString()),
   );
   console.log(`\nMinted BATs in pool: ${auth.exportPool().length}`);
 
@@ -94,7 +94,7 @@ async function main() {
   const response = await wallet.receive(encoded);
   console.log(
     '\nReceived 10 sats.',
-    response.map((p) => p.amount),
+    response.map((p) => p.amount.toString()),
   );
   console.log(`\nMinted BATs in pool: ${auth.exportPool().length}`);
 

examples/auth_mint/auth_password_example.ts

@@ -73,7 +73,7 @@ async function main() {
   const proofs = await wallet.mintProofsBolt11(100, request);
   console.log(
     '\nMinted 100 sats.',
-    proofs.map((p) => p.amount),
+    proofs.map((p) => p.amount.toString()),
   );
   console.log(`\nMinted BATs in pool: ${auth.exportPool().length}`);
 
@@ -85,7 +85,7 @@ async function main() {
   const response = await wallet.receive(encoded);
   console.log(
     '\nReceived 10 sats.',
-    response.map((p) => p.amount),
+    response.map((p) => p.amount.toString()),
   );
   console.log(`\nMinted BATs in pool: ${auth.exportPool().length}`);
 

examples/auth_mint/auth_pkce_example.ts

@@ -97,7 +97,7 @@ async function main() {
   const proofs = await wallet.mintProofsBolt11(100, request);
   console.log(
     '\nMinted 100 sats.',
-    proofs.map((p) => p.amount),
+    proofs.map((p) => p.amount.toString()),
   );
   console.log(`\nMinted BATs in pool: ${auth.exportPool().length}`);
 
@@ -110,7 +110,7 @@ async function main() {
   const response = await wallet.receive(encoded);
   console.log(
     '\nReceived 10 sats.',
-    response.map((p) => p.amount),
+    response.map((p) => p.amount.toString()),
   );
   console.log(`\nMinted BATs in pool: ${auth.exportPool().length}`);
 

examples/bolt12Wallet_example.ts

@@ -55,7 +55,7 @@ const runBolt12WalletExample = async () => {
         const newProofs = await mintFromBolt12Quote(wallet, bolt12MintQuote);
         proofs.push(...newProofs);
 
-        console.log(`💰 Balance: ${sumProofs(proofs)} sats\n`);
+        console.log(`💰 Balance: ${sumProofs(proofs).toString()} sats\n`);
 
         if (cycle < PAYMENT_CYCLES) {
           await new Promise((resolve) => setTimeout(resolve, 1000));
@@ -69,8 +69,8 @@ const runBolt12WalletExample = async () => {
     // Final summary
     console.log('🎯 Summary');
     console.log('==========');
-    console.log(`💰 Final balance: ${sumProofs(proofs)} sats`);
-    console.log(`📤 Total sent: ${totalSent} sats`);
+    console.log(`💰 Final balance: ${sumProofs(proofs).toString()} sats`);
+    console.log(`📤 Total sent: ${totalSent.toString()} sats`);
     console.log(`✅ BOLT12 example completed!`);
   } catch (error) {
     console.error('❌ Error:', error);
@@ -101,7 +101,7 @@ const mintInitialProofs = async (wallet: Wallet): Promise<Proof[]> => {
   console.log(`Pay this invoice: ${bolt11Quote.request}`);
 
   const proofs = await waitForMintQuote(wallet, bolt11Quote.quote);
-  console.log(`✅ Minted ${sumProofs(proofs)} sats`);
+  console.log(`✅ Minted ${sumProofs(proofs).toString()} sats`);
 
   return proofs;
 };
@@ -117,14 +117,18 @@ const payBolt12Offer = async (
   const totalNeeded = meltQuote.amount.add(meltQuote.fee_reserve);
 
   if (sumProofs(proofs).lessThan(totalNeeded)) {
-    throw new Error(`Insufficient balance: need ${totalNeeded}, have ${sumProofs(proofs)}`);
+    throw new Error(
+      `Insufficient balance: need ${totalNeeded.toString()}, have ${sumProofs(proofs).toString()}`,
+    );
   }
 
   // Send payment
   const { keep, send } = await wallet.send(totalNeeded, proofs, { includeFees: true });
   const { change } = await wallet.meltProofsBolt12(meltQuote, send);
 
-  console.log(`💸 Paid ${amount} sats to BOLT12 offer (fee: ${meltQuote.fee_reserve} sats)`);
+  console.log(
+    `💸 Paid ${amount} sats to BOLT12 offer (fee: ${meltQuote.fee_reserve.toString()} sats)`,
+  );
 
   return {
     remainingProofs: [...keep, ...change],

examples/paymentApi_example.js

@@ -58,7 +58,7 @@ export const ecashPayment = onRequest(async (req, res) => {
     res.json({
       success: false,
       error: 'wrong_amount',
-      message: `Wrong amount, must be ${waitedAmount} satoshi`,
+      message: `Wrong amount, must be ${waitedAmount.toString()} satoshi`,
     });
     return;
   }

examples/simpleWallet_example.ts

@@ -70,7 +70,7 @@ const runWalletExample = async () => {
         if (quote.state === MintQuoteState.PAID) {
           //if the quote was paid, we can ask the mint to issue the signatures for the ecash
           const response = await wallet.mintProofsBolt11(mintAmount, quote.quote);
-          console.log(`minted proofs: ${response.map((p) => p.amount).join(', ')} sats`);
+          console.log(`minted proofs: ${response.map((p) => p.amount.toString()).join(', ')} sats`);
 
           // let's store the proofs in the storage we previously created
           proofs = response;
@@ -153,9 +153,9 @@ const runWalletExample = async () => {
       // After creating the melt quote, we can initiate the melting process.
       const amountToMelt = quote.amount.add(quote.fee_reserve);
 
-      console.log(`quote amount: ${quote.amount}`);
-      console.log(`fee reserve proofs: ${quote.fee_reserve}`);
-      console.log(`Total quote amount: ${amountToMelt}`);
+      console.log(`quote amount: ${quote.amount.toString()}`);
+      console.log(`fee reserve proofs: ${quote.fee_reserve.toString()}`);
+      console.log(`Total quote amount: ${amountToMelt.toString()}`);
 
       // in order to get the correct amount of proofs for the melt request, we can use the `send` function we used before
       const { keep, send } = await wallet.send(amountToMelt, proofs, {