Fee bumping Package

packages/caravan-fees/.eslintrc.js

@@ -0,0 +1,8 @@
+module.exports = {
+  root: true,
+  extends: ["@caravan/eslint-config/library.js"],
+  parser: "@typescript-eslint/parser",
+  parserOptions: {
+    project: true,
+  },
+};

packages/caravan-fees/jest.config.js

@@ -0,0 +1,8 @@
+module.exports = {
+  preset: "ts-jest",
+  testEnvironment: "node",
+  transform: {
+    "^.+\\.js$": "babel-jest",
+    "^.+\\.ts$": "ts-jest",
+  },
+};

packages/caravan-fees/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@caravan/fees",
+  "version": "0.0.0-beta",
+  "description": "Utility library for fee bumping bitcoin transactions",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "module": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "npm run build -- --watch",
+    "test": "jest src",
+    "test:watch": "jest --watch src"
+  },
+  "keywords": [
+    "bitcoin",
+    "cpfp",
+    "rbf",
+    "feebumping",
+    "blockchain"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@caravan/eslint-config": "*",
+    "tsconfig": "*"
+  },
+  "dependencies": {
+    "@caravan/bitcoin": "*"
+  }
+}

packages/caravan-fees/src/constants.ts

@@ -0,0 +1,14 @@
+import BigNumber from "bignumber.js";
+
+export const MIN_FEE_RATE = 1;
+export const MAX_FEE_RATE = 5000;
+export const DEFAULT_FEE_INCREASE_THRESHOLD = 1.1;
+export const MIN_DUST_AMOUNT = new BigNumber(546);
+export const SATS_PER_BTC = new BigNumber(100000000);
+export const DUST_THRESHOLD = 546; // in satoshis
+export const MAX_STANDARD_TX_WEIGHT = 400000; // in weight units
+export const MIN_RELAY_FEE_RATE = 1; // in satoshis per byte
+export const DEFAULT_DUST_THRESHOLD = 546; // in satoshis
+export const RBF_SEQUENCE = 0xffffffff - 2;
+export const DEFAULT_MAX_CHILD_TX_SIZE = 1000;
+export const DEFAULT_MAX_ADDITIONAL_INPUTS = 3;

packages/caravan-fees/src/cpfp.fixtures.ts

@@ -0,0 +1,37 @@
+import { PsbtV2 } from "@caravan/psbt";
+import { Network } from "@caravan/bitcoin";
+
+const parentPsbtFixture = new PsbtV2();
+parentPsbtFixture.addInput({
+  previousTxId:
+    "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
+  outputIndex: 0,
+  witnessUtxo: {
+    script: Buffer.from("0014000000000000000000000000000000000000", "hex"),
+    amount: 100000, // 0.001 BTC
+  },
+});
+parentPsbtFixture.addOutput({
+  script: Buffer.from("0014111111111111111111111111111111111111", "hex"),
+  amount: 90000, // 0.0009 BTC
+});
+
+const additionalUtxoFixture = {
+  txid: "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
+  vout: 0,
+  value: 50000, // 0.0005 BTC
+  script: Buffer.from("0014222222222222222222222222222222222222", "hex"),
+};
+
+const defaultOptions = {
+  parentPsbt: parentPsbtFixture,
+  spendableOutputs: [0],
+  destinationAddress: "bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4",
+  feeRate: { satoshisPerByte: 2 },
+  network: Network.MAINNET,
+  requiredSigners: 2,
+  totalSigners: 3,
+  addressType: "P2WSH",
+};
+
+export { parentPsbtFixture, additionalUtxoFixture, defaultOptions };

packages/caravan-fees/src/cpfp.test.ts

@@ -0,0 +1,227 @@
+import { CPFPTransaction, prepareCPFPTransaction } from "./cpfp";
+import { PsbtV2 } from "@caravan/psbt";
+import { Network } from "@caravan/bitcoin";
+import {
+  parentPsbtFixture,
+  additionalUtxoFixture,
+  defaultOptions,
+} from "./cpfp.fixtures";
+
+describe("CPFPTransaction", () => {
+  describe("constructor", () => {
+    it("should initialize with valid options", () => {
+      const cpfpTx = new CPFPTransaction(defaultOptions);
+      expect(cpfpTx).toBeDefined();
+    });
+
+    it("should throw an error if parent PSBT has no inputs", () => {
+      const invalidPsbt = new PsbtV2();
+      expect(
+        () =>
+          new CPFPTransaction({ ...defaultOptions, parentPsbt: invalidPsbt }),
+      ).toThrow("Parent PSBT has no inputs.");
+    });
+
+    it("should throw an error if no spendable outputs are provided", () => {
+      expect(
+        () => new CPFPTransaction({ ...defaultOptions, spendableOutputs: [] }),
+      ).toThrow("No spendable outputs provided.");
+    });
+  });
+
+  describe("prepareCPFP", () => {
+    it("should create a valid child transaction", () => {
+      const cpfpTx = new CPFPTransaction(defaultOptions);
+      const childPsbt = cpfpTx.prepareCPFP();
+      expect(childPsbt).toBeInstanceOf(PsbtV2);
+      expect(childPsbt.PSBT_GLOBAL_INPUT_COUNT).toBe(1);
+      expect(childPsbt.PSBT_GLOBAL_OUTPUT_COUNT).toBe(1);
+    });
+
+    it("should increase the fee rate", () => {
+      const cpfpTx = new CPFPTransaction(defaultOptions);
+      const combinedFee = cpfpTx.getCombinedFee();
+      const parentFee = cpfpTx.getParentFee();
+      expect(combinedFee.isGreaterThan(parentFee)).toBe(true);
+    });
+
+    it("should handle high urgency", () => {
+      const highUrgencyOptions = {
+        ...defaultOptions,
+        urgency: "high" as const,
+      };
+      const cpfpTx = new CPFPTransaction(highUrgencyOptions);
+      const combinedFee = cpfpTx.getCombinedFee();
+      const parentFee = cpfpTx.getParentFee();
+      expect(combinedFee.minus(parentFee).isGreaterThan(parentFee)).toBe(true);
+    });
+
+    it("should add additional inputs when necessary", () => {
+      const lowValueParentPsbt = new PsbtV2();
+      lowValueParentPsbt.addInput({
+        previousTxId:
+          "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
+        outputIndex: 0,
+        witnessUtxo: {
+          script: Buffer.from(
+            "0014000000000000000000000000000000000000",
+            "hex",
+          ),
+          amount: 10000, // 0.0001 BTC
+        },
+      });
+      lowValueParentPsbt.addOutput({
+        script: Buffer.from("0014111111111111111111111111111111111111", "hex"),
+        amount: 9000, // 0.00009 BTC
+      });
+
+      const optionsWithAdditionalUtxo = {
+        ...defaultOptions,
+        parentPsbt: lowValueParentPsbt,
+        additionalUtxos: [additionalUtxoFixture],
+      };
+
+      const cpfpTx = new CPFPTransaction(optionsWithAdditionalUtxo);
+      const childPsbt = cpfpTx.prepareCPFP();
+      expect(childPsbt.PSBT_GLOBAL_INPUT_COUNT).toBe(2);
+    });
+
+    it("should throw an error if resulting output would be dust", () => {
+      const tinyValueParentPsbt = new PsbtV2();
+      tinyValueParentPsbt.addInput({
+        previousTxId:
+          "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
+        outputIndex: 0,
+        witnessUtxo: {
+          script: Buffer.from(
+            "0014000000000000000000000000000000000000",
+            "hex",
+          ),
+          amount: 600, // 600 satoshis
+        },
+      });
+      tinyValueParentPsbt.addOutput({
+        script: Buffer.from("0014111111111111111111111111111111111111", "hex"),
+        amount: 550, // 550 satoshis
+      });
+
+      const optionsWithTinyValue = {
+        ...defaultOptions,
+        parentPsbt: tinyValueParentPsbt,
+      };
+
+      const cpfpTx = new CPFPTransaction(optionsWithTinyValue);
+      expect(() => cpfpTx.prepareCPFP()).toThrow(
+        "CPFP transaction would create a dust output",
+      );
+    });
+  });
+
+  describe("fee calculations", () => {
+    it("should correctly calculate child fee", () => {
+      const cpfpTx = new CPFPTransaction(defaultOptions);
+      cpfpTx.prepareCPFP();
+      const childFee = cpfpTx.getChildFee();
+      expect(childFee.isGreaterThan(0)).toBe(true);
+    });
+
+    it("should correctly calculate parent fee", () => {
+      const cpfpTx = new CPFPTransaction(defaultOptions);
+      const parentFee = cpfpTx.getParentFee();
+      expect(parentFee.toNumber()).toBe(10000); // 0.001 BTC - 0.0009 BTC
+    });
+
+    it("should correctly calculate combined fee", () => {
+      const cpfpTx = new CPFPTransaction(defaultOptions);
+      cpfpTx.prepareCPFP();
+      const combinedFee = cpfpTx.getCombinedFee();
+      const childFee = cpfpTx.getChildFee();
+      const parentFee = cpfpTx.getParentFee();
+      expect(
+        combinedFee.minus(childFee.plus(parentFee)).abs().isLessThan(1),
+      ).toBe(true);
+    });
+  });
+
+  describe("prepareCPFPTransaction function", () => {
+    it("should return a valid PsbtV2 instance", () => {
+      const childPsbt = prepareCPFPTransaction(defaultOptions);
+      expect(childPsbt).toBeInstanceOf(PsbtV2);
+    });
+
+    it("should throw an error with invalid options", () => {
+      const invalidOptions = { ...defaultOptions, parentPsbt: new PsbtV2() };
+      expect(() => prepareCPFPTransaction(invalidOptions)).toThrow(
+        "Parent PSBT has no inputs.",
+      );
+    });
+  });
+
+  describe("edge cases", () => {
+    it("should handle maximum number of additional inputs", () => {
+      const manyAdditionalUtxos = Array(10).fill(additionalUtxoFixture);
+      const optionsWithManyUtxos = {
+        ...defaultOptions,
+        maxAdditionalInputs: 5,
+        additionalUtxos: manyAdditionalUtxos,
+      };
+
+      const cpfpTx = new CPFPTransaction(optionsWithManyUtxos);
+      const childPsbt = cpfpTx.prepareCPFP();
+      expect(childPsbt.PSBT_GLOBAL_INPUT_COUNT).toBeLessThanOrEqual(6); // 1 parent output + 5 additional
+    });
+
+    it("should handle custom urgency multipliers", () => {
+      const customUrgencyOptions = {
+        ...defaultOptions,
+        urgency: "high" as const,
+        urgencyMultipliers: { low: 1.1, medium: 1.3, high: 1.8 },
+      };
+
+      const cpfpTx = new CPFPTransaction(customUrgencyOptions);
+      const combinedFee = cpfpTx.getCombinedFee();
+      const parentFee = cpfpTx.getParentFee();
+      const feeIncrease = combinedFee.minus(parentFee);
+      expect(feeIncrease.dividedBy(parentFee).isGreaterThan(0.7)).toBe(true);
+    });
+
+    it("should respect max child transaction size", () => {
+      const manyAdditionalUtxos = Array(100).fill(additionalUtxoFixture);
+      const optionsWithManyUtxos = {
+        ...defaultOptions,
+        maxChildTxSize: 5,
+        additionalUtxos: manyAdditionalUtxos,
+      };
+
+      const cpfpTx = new CPFPTransaction(optionsWithManyUtxos);
+      const childPsbt = cpfpTx.prepareCPFP();
+      expect(childPsbt.PSBT_GLOBAL_INPUT_COUNT).toBeLessThanOrEqual(5);
+    });
+  });
+
+  describe("different address types", () => {
+    const addressTypes = ["P2SH", "P2WSH", "P2SH-P2WSH"];
+
+    addressTypes.forEach((addressType) => {
+      it(`should handle ${addressType} addresses`, () => {
+        const options = { ...defaultOptions, addressType };
+        const cpfpTx = new CPFPTransaction(options);
+        const childPsbt = cpfpTx.prepareCPFP();
+        expect(childPsbt).toBeInstanceOf(PsbtV2);
+      });
+    });
+  });
+
+  describe("different networks", () => {
+    it("should handle testnet", () => {
+      const testnetOptions = {
+        ...defaultOptions,
+        network: Network.TESTNET,
+        destinationAddress: "tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kxpjzsx",
+      };
+      const cpfpTx = new CPFPTransaction(testnetOptions);
+      const childPsbt = cpfpTx.prepareCPFP();
+      expect(childPsbt).toBeInstanceOf(PsbtV2);
+    });
+  });
+});