Add fees and coin selection

[callebtc]

Introduces support for fees for spending ecash with the mint. Fees are published in the /v1/keysets response (see NUT-02). Also introduces a new input coinselection algorithm to minimize fees when spending coins and an output selection, to maintain a diverse set of amounts in the user's wallet, increasing the chance for being able to make offline transactions in the future.

Changes

Automatic input selection

There is a rather sophisticated coinselection algorithm now that will select with fees in mind. The library will automatically fetch the keyset of the mint in order to determine the fees during selection. The implementor can decide to use includeFees = true in various class methods in order to include fees in the selection so that the selection can be spent. This can be used in situations where the sender pays the fees instead of the receiver (and the receiver can receive a predictable amount). It is necessary to use if we perform coin selection to pay a Lightning invoice afterwards:

const { keep: proofsToKeep, send: proofsToSend } = await wallet.send(amountToSend, proofs, {
	includeFees: true
});
const meltResponse = await wallet.meltProofs(meltQuote, proofsToSend);

Output amounts

AmountPreference is removed, use OutputAmounts now, which can be used to define sendAmounts and keepAmounts which are now both simple arrays of numbers. Previously we could only define amounts to send through AmountPreference.

Automatic output amount selection

Users can use proofsWeHave to specify in various methods which proofs are present in the wallet. This will make the library to choose output amounts to refill the wallet with missing denominations:

const { keep: proofsToKeep, send: proofsToSend } = await wallet.send(amountToSend, proofs, {
            proofsWeHave: proofs
});

The target defaults to DEFAULT_DENOMINATION_TARGET = 3; but can be defined in the constructor of the CashuWallet class.

Renaming

• in SendResponse, returnChange is now called keep
• mintTokens is now called mintProofs
• meltTokens is now called meltProofs
• CashuMint.split is now called CashuMint.swap

Legacy code

I suggest we get rid of all functions a la PayLNInvoice and force the implementor to understand how to use the library themselves instead of hiding crucial details. This should be done in a separate PR after merging this.

PR Tasks

• Open PR
• run npm run test --> no failing unit tests
• run npm run format

[gandlafbtc]

Yuge PR! thanks.

There are a lot of new functions. Please make sure that functions in the CashuWallet class that should not be used externally are marked private

Also, please add the minimal docs to the functions that are accessible to the implementoors

I didn't mark all as comments, please go through it (CashuWallet) again and add where required

[callebtc]

@gandlafbtc you're the best. thank you for doing all that work

[callebtc]

@Egge21M @gandlafbtc @gudnuf all changes applied. Please review again.

Thanks a lot again to @gandlafbtc for the fantastic work.

[gandlafbtc]

LGTM! Nice work!

[Egge21M]

LGTM! Thank you again for this @callebtc !