Add fees and coin selection

.github/workflows/nutshell-integration.yml

@@ -8,7 +8,7 @@ jobs:
     steps:
       - name: Pull and start mint
         run: |
-          docker run -d -p 3338:3338 --name nutshell -e MINT_LIGHTNING_BACKEND=FakeWallet -e MINT_LISTEN_HOST=0.0.0.0 -e MINT_LISTEN_PORT=3338 -e MINT_PRIVATE_KEY=TEST_PRIVATE_KEY cashubtc/nutshell:0.16.0 poetry run mint
+          docker run -d -p 3338:3338 --name nutshell -e MINT_LIGHTNING_BACKEND=FakeWallet -e MINT_INPUT_FEE_PPK=100 -e MINT_LISTEN_HOST=0.0.0.0 -e MINT_LISTEN_PORT=3338 -e MINT_PRIVATE_KEY=TEST_PRIVATE_KEY cashubtc/nutshell:0.16.0 poetry run mint
 
       - name: Check running containers
         run: docker ps

README.md

@@ -63,11 +63,12 @@ import { CashuMint, CashuWallet, MintQuoteState } from '@cashu/cashu-ts';
 const mintUrl = 'http://localhost:3338'; // the mint URL
 const mint = new CashuMint(mintUrl);
 const wallet = new CashuWallet(mint);
+await wallet.loadMint(); // persist wallet.keys and wallet.keysets to avoid calling loadMint() in the future
 const mintQuote = await wallet.createMintQuote(64);
 // pay the invoice here before you continue...
 const mintQuoteChecked = await wallet.checkMintQuote(mintQuote.quote);
 if (mintQuoteChecked.state == MintQuoteState.PAID) {
-	const { proofs } = await wallet.mintTokens(64, mintQuote.quote);
+	const { proofs } = await wallet.mintProofs(64, mintQuote.quote);
 }
 ```
 
@@ -77,21 +78,36 @@ if (mintQuoteChecked.state == MintQuoteState.PAID) {
 import { CashuMint, CashuWallet } from '@cashu/cashu-ts';
 const mintUrl = 'http://localhost:3338'; // the mint URL
 const mint = new CashuMint(mintUrl);
-const wallet = new CashuWallet(mint);
+const wallet = new CashuWallet(mint); // load the keysets of the mint
 
 const invoice = 'lnbc......'; // Lightning invoice to pay
 const meltQuote = await wallet.createMeltQuote(invoice);
 const amountToSend = meltQuote.amount + meltQuote.fee_reserve;
 
-// in a real wallet, we would coin select the correct amount of proofs from the wallet's storage
-// instead of that, here we swap `proofs` with the mint to get the correct amount of proofs
-const { returnChange: proofsToKeep, send: proofsToSend } = await wallet.send(amountToSend, proofs);
+// CashuWallet.send performs coin selection and swaps the proofs with the mint
+// if no appropriate amount can be selected offline. We must include potential
+// ecash fees that the mint might require to melt the resulting proofsToSend later.
+const { keep: proofsToKeep, send: proofsToSend } = await wallet.send(amountToSend, proofs, {
+	includeFees: true
+});
 // store proofsToKeep in wallet ..
 
-const meltResponse = await wallet.meltTokens(meltQuote, proofsToSend);
+const meltResponse = await wallet.meltProofs(meltQuote, proofsToSend);
 // store meltResponse.change in wallet ..
 ```
 
+#### Create a token and receive it
+
+```typescript
+// we assume that `wallet` already minted `proofs`, as above
+const { keep, send } = await wallet.send(32, proofs);
+const token = getEncodedTokenV4({ token: [{ mint: mintUrl, proofs: send }] });
+console.log(token);
+
+const wallet2 = new CashuWallet(mint); // receiving wallet
+const receiveProofs = await wallet2.receive(token);
+```
+
 ## Contribute
 
 Contributions are very welcome.

migration-2.0.0.md

@@ -0,0 +1,42 @@
+# Version 2.0.0 Migration guide
+
+⚠️ Upgrading to version 2.0.0 will come with breaking changes! Please follow the migration guide for a smooth transition to the new version.
+
+## Breaking changes
+
+### `CashuWallet` interface changes
+
+#### removed `payLnInvoice` helper
+
+The helper function was removed. Instead users will have to manage a melt quote manually:
+
+```ts
+const quote = await wallet.createMeltQuote(invoice);
+const totalAmount = quote.fee_reserve + invoiceAmount;
+const { keep, send } = await wallet.send(totalAmount, proofs);
+const payRes = await wallet.meltProofs(quote, send);
+```
+
+---
+
+#### Preference for outputs are now passed as a object of simple arrays
+
+**`AmountPreference`** is not used anymore.
+
+`preference?: Array<AmountPreference>;` -> `outputAmounts?: OutputAmounts;`
+
+where
+
+```typescript
+export type OutputAmounts = {
+	sendAmounts: Array<number>;
+	keepAmounts?: Array<number>;
+};
+```
+
+#### renamed functions
+
+- in `SendResponse`, `returnChange` is now called `keep`
+- `CashuWallet.mintTokens()` is now called `CashuWallet.mintProofs()`
+- `CashuWallet.meltTokens()` is now called `CashuWallet.meltProofs()`
+- `CashuMint.split()` is now called `CashuMint.swap()`

src/CashuMint.ts

@@ -76,7 +76,7 @@ class CashuMint {
 	 * @param customRequest
 	 * @returns signed outputs
 	 */
-	public static async split(
+	public static async swap(
 		mintUrl: string,
 		swapPayload: SwapPayload,
 		customRequest?: typeof request
@@ -99,8 +99,8 @@ class CashuMint {
 	 * @param swapPayload payload containing inputs and outputs
 	 * @returns signed outputs
 	 */
-	async split(swapPayload: SwapPayload): Promise<SwapResponse> {
-		return CashuMint.split(this._mintUrl, swapPayload, this._customRequest);
+	async swap(swapPayload: SwapPayload): Promise<SwapResponse> {
+		return CashuMint.swap(this._mintUrl, swapPayload, this._customRequest);
 	}
 
 	/**