mainnet-js 0.4.32 → 0.4.36

package/src/transaction/allocateFee.test.ts

@@ -0,0 +1,309 @@
+import { allocateFee, sortSendRequests } from "./allocateFee";
+import { FeePaidByEnum } from "../wallet/enum";
+import { asSendRequestObject } from "../util/asSendRequestObject";
+import { SendRequest } from "..";
+import { RegTestWallet } from "../wallet/Wif";
+
+test("Should get the regtest wallet balance", async () => {
+  // Build Alice's wallet from Wallet Import Format string, send some sats
+  if (!process.env.ADDRESS) {
+    throw Error("Attempted to pass an empty address");
+  } else {
+    const funder = await RegTestWallet.fromId(
+      `wif:regtest:${process.env.PRIVATE_WIF!}`
+    );
+    const alice = await RegTestWallet.newRandom();
+    const bob = await RegTestWallet.newRandom();
+    const charlie = await RegTestWallet.newRandom();
+    const dave = await RegTestWallet.newRandom();
+    const edward = await RegTestWallet.newRandom();
+    await funder.send([
+      {
+        cashaddr: alice.cashaddr!,
+        value: 4500,
+        unit: "satoshis",
+      },
+    ]);
+    await alice.send(
+      [
+        {
+          cashaddr: bob.cashaddr!,
+          unit: "sat",
+          value: 549,
+        },
+        {
+          cashaddr: charlie.cashaddr!,
+          unit: "sat",
+          value: 550,
+        },
+        {
+          cashaddr: dave.cashaddr!,
+          unit: "sat",
+          value: 551,
+        },
+        {
+          cashaddr: edward.cashaddr!,
+          unit: "sat",
+          value: 2552,
+        },
+      ],
+      { feePaidBy: FeePaidByEnum.changeThenAny }
+    );
+    expect(await alice.getBalance("sat")).toBe(0);
+    expect(await bob.getBalance("sat")).toBe(0);
+    expect(await charlie.getBalance("sat")).toBe(550);
+    expect(await dave.getBalance("sat")).toBe(551);
+    expect(await edward.getBalance("sat")).toBe(2552);
+  }
+});
+
+test("Expect first in to subtract fee from first", async () => {
+  let to = [
+    ["alice", 2000, "sat"],
+    ["bob", 2000, "sat"],
+  ];
+  let fee = 1;
+  let requests = asSendRequestObject(to) as SendRequest[];
+  let allocatedInputs = await allocateFee(
+    requests,
+    fee,
+    FeePaidByEnum.first,
+    BigInt(0)
+  );
+  expect(allocatedInputs[0].value).toBeLessThan(2000);
+  expect(allocatedInputs[1].value).toBe(2000);
+});
+
+test("Expect last to subtract fee from last", async () => {
+  let to = [
+    ["alice", 2000, "sat"],
+    ["bob", 2000, "sat"],
+  ];
+  let fee = 1;
+  let requests = asSendRequestObject(to) as SendRequest[];
+  let allocatedInputs = allocateFee(
+    requests,
+    fee,
+    FeePaidByEnum.last,
+    BigInt(0)
+  );
+
+  expect(allocatedInputs[0].value).toBe(2000);
+  expect(allocatedInputs[1].value).toBeLessThan(2000);
+});
+
+test("Expect all to allocate fees equally", async () => {
+  let to = [
+    ["alice", 2000, "sat"],
+    ["bob", 2000, "sat"],
+    ["charlie", 2000, "sat"],
+  ];
+  let fee = 3;
+  let requests = asSendRequestObject(to) as SendRequest[];
+
+  let allocatedInputs = allocateFee(
+    requests,
+    fee,
+    FeePaidByEnum.any,
+    BigInt(0)
+  );
+
+  expect(allocatedInputs[0].value).toBe(1999);
+  expect(allocatedInputs[1].value).toBe(1999);
+  expect(allocatedInputs[2].value).toBe(1999);
+});
+
+test("Expect all to allocate fees equally, taking dust result", async () => {
+  let to = [
+    ["alice", 2000, "sat"],
+    ["bob", 547, "sat"],
+    ["charlie", 2000, "sat"],
+  ];
+  let fee = 300;
+  let requests = asSendRequestObject(to) as SendRequest[];
+
+  let allocatedInputs = allocateFee(
+    requests,
+    fee,
+    FeePaidByEnum.any,
+    BigInt(0)
+  );
+
+  expect(allocatedInputs[0].value).toBe(2000);
+  expect(allocatedInputs[1].value).toBe(2000);
+  expect(allocatedInputs.length).toBe(2);
+});
+
+test("Expect all to allocate fees equally, taking dust result output, dividing remainder", async () => {
+  let to = [
+    ["alice", 2000, "sat"],
+    ["bob", 547, "sat"],
+    ["charlie", 2000, "sat"],
+  ];
+  let fee = 647;
+  let requests = asSendRequestObject(to) as SendRequest[];
+
+  let allocatedInputs = allocateFee(
+    requests,
+    fee,
+    FeePaidByEnum.any,
+    BigInt(0)
+  );
+
+  expect(allocatedInputs[0].value).toBe(1950);
+  expect(allocatedInputs[1].value).toBe(1950);
+  expect(allocatedInputs.length).toBe(2);
+});
+
+test("Expect an odd fee to be applied to have remainder applied to first receipt", async () => {
+  let to = [
+    ["alice", 2000, "sat"],
+    ["bob", 2000, "sat"],
+    ["charlie", 2000, "sat"],
+  ];
+  let fee = 301;
+  let requests = asSendRequestObject(to) as SendRequest[];
+
+  let allocatedInputs = allocateFee(
+    requests,
+    fee,
+    FeePaidByEnum.any,
+    BigInt(0)
+  );
+
+  expect(allocatedInputs[0].value).toBe(1899);
+  expect(allocatedInputs[1].value).toBe(1900);
+  expect(allocatedInputs[2].value).toBe(1900);
+});
+
+test("Expect insufficient funds to error", async () => {
+  expect.assertions(1);
+  try {
+    let to = [
+      ["alice", 2000, "sat"],
+      ["bob", 2000, "sat"],
+      ["charlie", 2000, "sat"],
+    ];
+    let fee = 7000;
+    let requests = asSendRequestObject(to) as SendRequest[];
+    let allocatedInputs = allocateFee(
+      requests,
+      fee,
+      FeePaidByEnum.changeThenAny,
+      BigInt(999)
+    );
+  } catch (e: any) {
+    expect(e.message).toBe("Insufficient funds for transaction given fee");
+  }
+});
+
+test("Expect dust amounts to error", async () => {
+  expect.assertions(1);
+  try {
+    let to = [
+      ["alice", 2000, "sat"],
+      ["bob", 2000, "sat"],
+      ["charlie", 2000, "sat"],
+    ];
+    let fee = 1500;
+    let requests = asSendRequestObject(to) as SendRequest[];
+    let allocatedInputs = allocateFee(
+      requests,
+      fee,
+      FeePaidByEnum.first,
+      BigInt(0)
+    );
+  } catch (e: any) {
+    expect(e.message).toBe("Fee strategy would result in dust output");
+  }
+});
+
+test("Expect near-dust amounts not to error", async () => {
+  let to = [
+    ["alice", 1000, "sat"],
+    ["bob", 1000, "sat"],
+    ["charlie", 1000, "sat"],
+  ];
+  let fee = 1362;
+  let requests = asSendRequestObject(to) as SendRequest[];
+  let result = allocateFee(requests, fee, FeePaidByEnum.any, BigInt(0));
+  expect(result[0].value).toBe(546);
+  expect(result[1].value).toBe(546);
+  expect(result[2].value).toBe(546);
+});
+
+test("Expect `any` to not consume change", async () => {
+  let to = [
+    ["alice", 1000, "sat"],
+    ["bob", 1000, "sat"],
+    ["charlie", 1000, "sat"],
+  ];
+  let fee = 1362;
+  let requests = asSendRequestObject(to) as SendRequest[];
+  let result = allocateFee(requests, fee, FeePaidByEnum.any, BigInt(1362));
+  expect(result[0].value).toBe(546);
+  expect(result[1].value).toBe(546);
+  expect(result[2].value).toBe(546);
+});
+
+test("Expect `change,any` to consume only change", async () => {
+  let to = [
+    ["alice", 1000, "sat"],
+    ["bob", 1000, "sat"],
+    ["charlie", 1000, "sat"],
+  ];
+  let fee = 1362;
+  let requests = asSendRequestObject(to) as SendRequest[];
+  let result = allocateFee(
+    requests,
+    fee,
+    FeePaidByEnum.changeThenAny,
+    BigInt(1362)
+  );
+  expect(result[0].value).toBe(1000);
+  expect(result[1].value).toBe(1000);
+  expect(result[2].value).toBe(1000);
+});
+
+test("Expect `change,any` to use both", async () => {
+  let to = [
+    ["alice", 1000, "sat"],
+    ["bob", 1000, "sat"],
+    ["charlie", 1000, "sat"],
+  ];
+  let fee = 1362 * 2;
+  let requests = asSendRequestObject(to) as SendRequest[];
+  let result = allocateFee(
+    requests,
+    fee,
+    FeePaidByEnum.changeThenAny,
+    BigInt(1362)
+  );
+  expect(result[0].value).toBe(546);
+  expect(result[1].value).toBe(546);
+  expect(result[2].value).toBe(546);
+});
+
+test("Expect sortSendRequests to sort by lowest value first", async () => {
+  let to = [
+    ["alice", 2000, "sat"],
+    ["bob", 547, "sat"],
+    ["charlie", 1, "sat"],
+    ["dave", 4, "sat"],
+    ["edward", 6, "sat"],
+    ["fred", 2000, "sat"],
+    ["greg", 2000, "sat"],
+    ["harry", 2000, "sat"],
+  ];
+  let fee = 1;
+  let requests = asSendRequestObject(to) as SendRequest[];
+
+  let result = sortSendRequests(requests);
+  expect(result[0].value).toBe(1);
+  expect(result[1].value).toBe(4);
+  expect(result[2].value).toBe(6);
+  expect(result[3].value).toBe(547);
+  expect(result[4].value).toBe(2000);
+  expect(result[5].value).toBe(2000);
+  expect(result.length).toBe(8);
+});

package/src/transaction/allocateFee.ts

@@ -0,0 +1,132 @@
+import { OpReturnData, SendRequest } from "../wallet/model";
+import { FeePaidByEnum } from "../wallet/enum";
+import { DUST_UTXO_THRESHOLD } from "../constant";
+
+export function checkFeeForDust(value: number) {
+  if (value < DUST_UTXO_THRESHOLD) {
+    throw Error("Fee strategy would result in dust output");
+  }
+}
+
+export function checkSatsAvailable(
+  sendRequestArray: Array<SendRequest>,
+  fee: number
+) {
+  let amountAvailable = sendRequestArray.reduce(function (sum, r) {
+    return sum + (r.value - DUST_UTXO_THRESHOLD);
+  }, 0);
+  if (amountAvailable < fee) {
+    throw Error("Insufficient funds for transaction given fee");
+  }
+}
+
+export function checkForOpReturn(
+  output: SendRequest | OpReturnData
+): SendRequest {
+  if (output instanceof OpReturnData) {
+    throw Error("Cannot specify fee to be paid by OpReturnData");
+  }
+  return output;
+}
+
+export function sortSendRequests(sendRequestArray: Array<SendRequest>) {
+  return sendRequestArray.sort(
+    (a: SendRequest, b: SendRequest) => a.value - b.value
+  );
+}
+
+function distributeFees(requests: Array<SendRequest>, fee: number) {
+  checkSatsAvailable(requests, fee);
+  fee = Number(fee);
+  for (let r = 0; r < requests.length; r++) {
+    if (fee > 0) {
+      checkForOpReturn(requests[r]);
+      let perRequestFee = Math.floor(fee / (requests.length - r));
+      perRequestFee += fee % (requests.length - r);
+      if (requests[r].value - perRequestFee < DUST_UTXO_THRESHOLD) {
+        fee -= requests[r].value;
+        requests[r].value = 0;
+      } else {
+        fee -= perRequestFee;
+        requests[r].value -= perRequestFee;
+      }
+    }
+  }
+  return requests.filter((r) => r.value >= DUST_UTXO_THRESHOLD);
+}
+
+function firstPays(requests: Array<SendRequest | OpReturnData>, fee: number) {
+  let payer = requests.shift()!;
+  payer = checkForOpReturn(payer);
+  payer.value = payer.value! - fee;
+  checkFeeForDust(payer.value);
+  requests.unshift(payer);
+  return requests;
+}
+function lastPays(requests: Array<SendRequest | OpReturnData>, fee: number) {
+  let payer = requests.pop()!;
+  payer = checkForOpReturn(payer);
+  payer.value = payer.value! - fee;
+  checkFeeForDust(payer.value);
+  requests.push(payer);
+  return requests;
+}
+function anyPays(requests: Array<SendRequest | OpReturnData>, fee: number) {
+  for (let r of requests) {
+    checkForOpReturn(r);
+  }
+  requests = sortSendRequests(requests as Array<SendRequest>);
+  requests = distributeFees(requests as Array<SendRequest>, fee);
+  return requests;
+}
+
+function changeThenFallback(
+  requests: Array<SendRequest | OpReturnData>,
+  fee: number,
+  change: bigint,
+  fallbackFn: Function
+) {
+  if (BigInt(fee) > change) {
+    let outstandingFee = BigInt(fee) - change;
+    requests = fallbackFn(requests, outstandingFee);
+  }
+  return requests;
+}
+
+export function allocateFee(
+  requests: Array<SendRequest | OpReturnData>,
+  fee: number,
+  feePaidBy: FeePaidByEnum,
+  change: bigint
+): Array<SendRequest> {
+  if (requests.length > 0) {
+    switch (feePaidBy) {
+      case FeePaidByEnum.change:
+        // handled by default
+        break;
+      case FeePaidByEnum.changeThenFirst:
+        requests = changeThenFallback(requests, fee, change, firstPays);
+        break;
+      case FeePaidByEnum.changeThenLast:
+        requests = changeThenFallback(requests, fee, change, lastPays);
+        break;
+      case FeePaidByEnum.changeThenAny:
+        requests = changeThenFallback(requests, fee, change, anyPays);
+        break;
+      case FeePaidByEnum.first:
+        requests = firstPays(requests, fee);
+        break;
+      case FeePaidByEnum.last:
+        requests = lastPays(requests, fee);
+        break;
+      case FeePaidByEnum.any:
+        requests = anyPays(requests, fee);
+        break;
+      default:
+        throw Error("FeePaidBy option not recognized");
+    }
+    return requests as Array<SendRequest>;
+  } else {
+    throw Error("Attempted to specify feePaidBy on zero length SendRequest");
+  }
+}

package/src/util/index.ts

@@ -1,6 +1,7 @@
 export { amountInSatoshi } from "./amountInSatoshi";
 export { asSendRequestObject } from "./asSendRequestObject";
 export { atob, btoa } from "./base64";
+export { binToHex, hexToBin } from "@bitauth/libauth";
 export { convert, convertObject } from "./convert";
 export { delay } from "./delay";
 export { derivedNetwork } from "./deriveNetwork";

package/src/wallet/Slp.ts

@@ -53,6 +53,7 @@ import { GsppProvider } from "../slp/GsppProvider";
 import { delay } from "../util/delay";
 import { Util } from "./Util";
 import { Mainnet } from "../index";
+import { FeePaidByEnum } from "./enum";
 
 /**
  * Class to manage an slp enabled wallet.
@@ -680,6 +681,7 @@ export class Slp {
       privateKey: this.wallet.privateKey,
       relayFeePerByteInSatoshi: relayFeePerByteInSatoshi,
       slpOutputs: slpOutputsResult.SlpOutputs,
+      feePaidBy: FeePaidByEnum.change,
     });
 
     const bchSpendAmount = slpOutputsResult.BchSendRequests.map(
@@ -689,7 +691,8 @@ export class Slp {
     let fundingUtxos = await getSuitableUtxos(
       fundingBchUtxos,
       BigInt(bchSpendAmount) + BigInt(feeEstimate),
-      bestHeight
+      bestHeight,
+      FeePaidByEnum.change
     );
 
     if (fundingUtxos.length === 0) {
@@ -704,6 +707,7 @@ export class Slp {
       privateKey: this.wallet.privateKey,
       relayFeePerByteInSatoshi: relayFeePerByteInSatoshi,
       slpOutputs: slpOutputsResult.SlpOutputs,
+      feePaidBy: FeePaidByEnum.change,
     });
 
     const encodedTransaction = await buildEncodedTransaction(

package/src/wallet/Wif.test.ts

@@ -501,6 +501,26 @@ describe(`Watch only Wallets`, () => {
     }
   });
 
+  test("Should encode and submit a transaction", async () => {
+    const aliceWif = `wif:regtest:${process.env.PRIVATE_WIF!}`;
+    const aliceWallet = await RegTestWallet.fromId(aliceWif);
+    const bobWallet = await RegTestWallet.newRandom();
+
+    const encodedTransaction = await aliceWallet.encodeTransaction([
+      {
+        cashaddr: bobWallet.cashaddr!,
+        value: 2000,
+        unit: "satoshis",
+      },
+    ]);
+    expect(encodedTransaction.length).toBeGreaterThan(0);
+
+    const txId = await aliceWallet.submitTransaction(encodedTransaction, true);
+    expect(txId.length).toBeGreaterThan(0);
+
+    expect(await bobWallet.getBalance("sat")).toBe(2000);
+  });
+
   test("Should get last transaction", async () => {
     const aliceWif = `wif:regtest:${process.env.PRIVATE_WIF!}`;
     const aliceWallet = await RegTestWallet.fromId(aliceWif);

package/src/wallet/Wif.ts

@@ -31,7 +31,7 @@ import { networkPrefixMap } from "../enum";
 import { PrivateKeyI, UtxoI } from "../interface";
 
 import { BaseWallet } from "./Base";
-import { WalletTypeEnum } from "./enum";
+import { FeePaidByEnum, WalletTypeEnum } from "./enum";
 import {
   CancelWatchFn,
   SendRequestOptionsI,
@@ -764,6 +764,13 @@ export class Wallet extends BaseWallet {
       this._slpSemiAware = true;
     }
 
+    let feePaidBy;
+    if (params.options && params.options.feePaidBy) {
+      feePaidBy = params.options.feePaidBy;
+    } else {
+      feePaidBy = FeePaidByEnum.change;
+    }
+
     // get inputs
     let utxos: UtxoI[];
     if (params.options && params.options.utxoIds) {
@@ -787,7 +794,12 @@ export class Wallet extends BaseWallet {
       .fill(0)
       .map(() => sendRequest);
 
-    const fundingUtxos = await getSuitableUtxos(utxos, undefined, bestHeight);
+    const fundingUtxos = await getSuitableUtxos(
+      utxos,
+      undefined,
+      bestHeight,
+      feePaidBy
+    );
     const relayFeePerByteInSatoshi = await getRelayFeeCache(this.provider!);
     const fee = await getFeeAmount({
       utxos: fundingUtxos,
@@ -795,6 +807,7 @@ export class Wallet extends BaseWallet {
       privateKey: this.privateKey,
       relayFeePerByteInSatoshi: relayFeePerByteInSatoshi,
       slpOutputs: [],
+      feePaidBy: feePaidBy,
     });
     const spendableAmount = await sumUtxoValue(fundingUtxos);
 
@@ -917,7 +930,7 @@ export class Wallet extends BaseWallet {
   }
 
   /**
-   * encodeTransaction given a list of sendRequests, options and estimate fees.
+   * encodeTransaction Encode and sign a transaction given a list of sendRequests, options and estimate fees.
    * @param  {SendRequest[]} sendRequests SendRequests
    * @param  {boolean} discardChange=false
    * @param  {SendRequestOptionsI} options Options of the send requests
@@ -950,6 +963,20 @@ export class Wallet extends BaseWallet {
       this._slpSemiAware = true;
     }
 
+    let feePaidBy;
+    if (options && options.feePaidBy) {
+      feePaidBy = options.feePaidBy;
+    } else {
+      feePaidBy = FeePaidByEnum.change;
+    }
+
+    let changeAddress;
+    if (options && options.changeAddress) {
+      changeAddress = options.changeAddress;
+    } else {
+      changeAddress = "";
+    }
+
     // get inputs from options or query all inputs
     let utxos: UtxoI[];
     if (options && options.utxoIds) {
@@ -977,12 +1004,14 @@ export class Wallet extends BaseWallet {
       privateKey: this.privateKey,
       relayFeePerByteInSatoshi: relayFeePerByteInSatoshi,
       slpOutputs: [],
+      feePaidBy: feePaidBy,
     });
 
     const fundingUtxos = await getSuitableUtxos(
       utxos,
       BigInt(spendAmount) + BigInt(feeEstimate),
-      bestHeight
+      bestHeight,
+      feePaidBy
     );
     if (fundingUtxos.length === 0) {
       throw Error(
@@ -995,13 +1024,17 @@ export class Wallet extends BaseWallet {
       privateKey: this.privateKey,
       relayFeePerByteInSatoshi: relayFeePerByteInSatoshi,
       slpOutputs: [],
+      feePaidBy: feePaidBy,
     });
     const encodedTransaction = await buildEncodedTransaction(
       fundingUtxos,
       sendRequests,
       this.privateKey,
       fee,
-      discardChange
+      discardChange,
+      [],
+      feePaidBy,
+      changeAddress
     );
 
     return encodedTransaction;

package/src/wallet/enum.ts

@@ -5,3 +5,13 @@ export enum WalletTypeEnum {
   Watch = "watch",
   PrivateKey = "privkey",
 }
+
+export enum FeePaidByEnum {
+  change = "change",
+  first = "firstOutput",
+  any = "anyOutputs",
+  last = "lastOutput",
+  changeThenFirst = "changeThenFirst",
+  changeThenAny = "changeThenAny",
+  changeThenLast = "changeThenLast",
+}

package/src/wallet/interface.ts

@@ -1,4 +1,4 @@
-import { WalletTypeEnum } from "./enum";
+import { WalletTypeEnum, FeePaidByEnum } from "./enum";
 import { NetworkEnum } from "../enum";
 import { ImageI } from "../qr/interface";
 import { ElectrumRawTransaction } from "../network/interface";
@@ -50,6 +50,7 @@ export interface SendRequestOptionsI {
   slpSemiAware?: boolean; // a flag which requires an utxo to have more than 546 sats to be spendable and counted in the balance
   queryBalance?: boolean;
   awaitTransactionPropagation?: boolean;
+  feePaidBy?: FeePaidByEnum;
 }
 
 export interface MnemonicI {