mainnet-js 0.4.34 → 0.4.35

package/package.json

@@ -8,7 +8,7 @@
     "url": "https://github.com/mainnet-cash/mainnet-js/issues"
   },
   "name": "mainnet-js",
-  "version": "0.4.34",
+  "version": "0.4.35",
   "homepage": "https://mainnet.cash",
   "main": "dist/main/index.js",
   "module": "dist/module/index.js",

package/src/transaction/Wif.ts

@@ -13,12 +13,14 @@ import {
   AuthenticationProgramStateBCH,
 } from "@bitauth/libauth";
 import { UtxoI } from "../interface";
+import { allocateFee } from "./allocateFee";
 
 import { DUST_UTXO_THRESHOLD } from "../constant";
 import { OpReturnData, SendRequest } from "../wallet/model";
 import { amountInSatoshi } from "../util/amountInSatoshi";
 import { sumSendRequestAmounts } from "../util/sumSendRequestAmounts";
 import { sumUtxoValue } from "../util/sumUtxoValue";
+import { FeePaidByEnum } from "../wallet/enum";
 
 // Build a transaction for a p2pkh transaction for a non HD wallet
 export async function buildP2pkhNonHdTransaction(
@@ -27,7 +29,8 @@ export async function buildP2pkhNonHdTransaction(
   signingKey: Uint8Array,
   fee: number = 0,
   discardChange = false,
-  slpOutputs: any[] = []
+  slpOutputs: any[] = [],
+  feePaidBy: FeePaidByEnum = FeePaidByEnum.change
 ) {
   if (!signingKey) {
     throw new Error("Missing signing key when building transaction");
@@ -42,6 +45,7 @@ export async function buildP2pkhNonHdTransaction(
 
   const compiler = await authenticationTemplateToCompilerBCH(template);
   const inputAmount = await sumUtxoValue(inputs);
+
   const sendAmount = await sumSendRequestAmounts(outputs);
 
   // Get the change locking bytecode
@@ -53,11 +57,13 @@ export async function buildP2pkhNonHdTransaction(
   }
 
   try {
+    const changeAmount = BigInt(inputAmount) - BigInt(sendAmount) - BigInt(fee);
+
+    outputs = allocateFee(outputs, fee, feePaidBy, changeAmount);
+
     let lockedOutputs = await prepareOutputs(outputs);
 
     if (discardChange !== true) {
-      const changeAmount =
-        BigInt(inputAmount) - BigInt(sendAmount) - BigInt(fee);
       if (changeAmount > DUST_UTXO_THRESHOLD) {
         lockedOutputs.push({
           lockingBytecode: changeLockingBytecode.bytecode,
@@ -188,7 +194,8 @@ export function prepareOpReturnOutput(request: OpReturnData) {
 export async function getSuitableUtxos(
   unspentOutputs: UtxoI[],
   amountRequired: BigInt | undefined,
-  bestHeight: number
+  bestHeight: number,
+  feePaidBy: FeePaidByEnum
 ): Promise<UtxoI[]> {
   let suitableUtxos: UtxoI[] = [];
   let amountAvailable = BigInt(0);
@@ -209,6 +216,11 @@ export async function getSuitableUtxos(
     }
   }
 
+  // if the fee is split with a feePaidBy option, skip checking change.
+  if (feePaidBy && feePaidBy != FeePaidByEnum.change) {
+    return suitableUtxos;
+  }
+
   // If the amount needed is met, or no amount is given, return
   if (typeof amountRequired === "undefined") {
     return suitableUtxos;
@@ -232,12 +244,14 @@ export async function getFeeAmount({
   privateKey,
   relayFeePerByteInSatoshi,
   slpOutputs,
+  feePaidBy,
 }: {
   utxos: UtxoI[];
   sendRequests: Array<SendRequest | OpReturnData>;
   privateKey: Uint8Array;
   relayFeePerByteInSatoshi: number;
   slpOutputs: any[];
+  feePaidBy: FeePaidByEnum;
 }) {
   // build transaction
   if (utxos) {
@@ -248,7 +262,8 @@ export async function getFeeAmount({
       privateKey,
       0, //DUST_UTXO_THRESHOLD
       false,
-      slpOutputs
+      slpOutputs,
+      feePaidBy
     );
 
     return draftTransaction.length * relayFeePerByteInSatoshi + 1;
@@ -266,7 +281,8 @@ export async function buildEncodedTransaction(
   privateKey: Uint8Array,
   fee: number = 0,
   discardChange = false,
-  slpOutputs: any[] = []
+  slpOutputs: any[] = [],
+  feePaidBy: FeePaidByEnum = FeePaidByEnum.change
 ) {
   let txn = await buildP2pkhNonHdTransaction(
     fundingUtxos,
@@ -274,7 +290,8 @@ export async function buildEncodedTransaction(
     privateKey,
     fee,
     discardChange,
-    slpOutputs
+    slpOutputs,
+    feePaidBy
   );
   // submit transaction
   if (txn.success) {

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/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.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);
 
@@ -950,6 +963,13 @@ export class Wallet extends BaseWallet {
       this._slpSemiAware = true;
     }
 
+    let feePaidBy;
+    if (options && options.feePaidBy) {
+      feePaidBy = options.feePaidBy;
+    } else {
+      feePaidBy = FeePaidByEnum.change;
+    }
+
     // get inputs from options or query all inputs
     let utxos: UtxoI[];
     if (options && options.utxoIds) {
@@ -977,12 +997,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 +1017,16 @@ 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
     );
 
     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",
+}