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",
+  "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,11 @@
+import BigNumber from "bignumber.js";
+
+export const DEFAULT_RBF_SEQUENCE = 0xfffffffd;
+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

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

@@ -0,0 +1,82 @@
+import { prepareCPFPTransaction } from "./cpfp";
+import { Transaction } from "bitcoinjs-lib-v5";
+import { Network, unsignedMultisigTransaction } from "@caravan/bitcoin";
+import BigNumber from "bignumber.js";
+import { CPFPOptions, UTXO } from "./types";
+
+jest.mock("@caravan/bitcoin");
+jest.mock("./utils");
+
+describe("CPFP", () => {
+  let mockParentTransaction: Transaction;
+  let mockUTXOs: UTXO[];
+  let mockOptions: CPFPOptions;
+
+  beforeEach(() => {
+    mockParentTransaction = {
+      getId: jest.fn().mockReturnValue("parentTxId"),
+      outs: [{ value: 100000, address: "address1" }],
+      virtualSize: jest.fn().mockReturnValue(200),
+      getAddressType: jest.fn().mockReturnValue("P2SH"),
+      getRequiredSigners: jest.fn().mockReturnValue(2),
+      getTotalSigners: jest.fn().mockReturnValue(3),
+    } as unknown as Transaction;
+    mockUTXOs = [
+      {
+        txid: "parentTxId",
+        vout: 0,
+        value: new BigNumber(100000),
+        address: "address1",
+        scriptPubKey: "script1",
+      },
+    ];
+    mockOptions = {
+      parentTransaction: mockParentTransaction,
+      newFeeRate: { satoshisPerByte: 10 },
+      availableUTXOs: mockUTXOs,
+      destinationAddress: "destinationAddress",
+      network: Network.TESTNET,
+    };
+
+    // Mock utility functions
+    jest.requireMock("./utils").estimateVirtualSize.mockReturnValue(200);
+    (unsignedMultisigTransaction as jest.Mock).mockReturnValue(
+      {} as Transaction
+    );
+  });
+
+  it("should prepare CPFP transaction", () => {
+    const result = prepareCPFPTransaction(mockOptions);
+    expect(result).toBeDefined();
+    expect(unsignedMultisigTransaction).toHaveBeenCalled();
+  });
+
+  it("should throw error if no suitable parent output found", () => {
+    mockOptions.availableUTXOs = [];
+    expect(() => prepareCPFPTransaction(mockOptions)).toThrow(
+      "No suitable output found in parent transaction for CPFP"
+    );
+  });
+
+  it("should throw error if CPFP transaction would create dust output", () => {
+    mockOptions.newFeeRate = { satoshisPerByte: 1000 }; // Unrealistically high fee to force dust output
+    expect(() => prepareCPFPTransaction(mockOptions)).toThrow(
+      "CPFP transaction would create a dust output"
+    );
+  });
+
+  it("should calculate correct fee for child transaction", () => {
+    prepareCPFPTransaction(mockOptions);
+    const expectedFee = new BigNumber(400).multipliedBy(10); // (200 + 200) * 10
+    expect(unsignedMultisigTransaction).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.anything(),
+      expect.arrayContaining([
+        expect.objectContaining({
+          amountSats: new BigNumber(100000).minus(expectedFee),
+        }),
+      ]),
+      true
+    );
+  });
+});

packages/caravan-fees/src/cpfp.ts

@@ -0,0 +1,105 @@
+import { Transaction } from "bitcoinjs-lib-v5";
+import { unsignedMultisigTransaction } from "@caravan/bitcoin";
+import BigNumber from "bignumber.js";
+import { CPFPOptions, UTXO } from "./types";
+import { estimateVirtualSize } from "./utils";
+
+/**
+ * Prepare a CPFP (Child-Pays-for-Parent) transaction.
+ * This function doesn't broadcast the transaction, it just prepares it.
+ * @param options CPFP options including the parent transaction and new fee rate
+ * @returns A new transaction ready for signing and broadcasting
+ */
+export function prepareCPFPTransaction(options: CPFPOptions): Transaction {
+  const {
+    parentTransaction,
+    newFeeRate,
+    availableUTXOs,
+    destinationAddress,
+    network,
+    multisigDetails,
+  } = options;
+
+  // Find suitable output from parent transaction to spend
+  const parentOutput = findSuitableParentOutput(
+    parentTransaction,
+    availableUTXOs
+  );
+  if (!parentOutput) {
+    throw new Error("No suitable output found in parent transaction for CPFP");
+  }
+
+  const childSize = estimateChildTransactionSize({
+    inputCount: 1, // We're spending one output from the parent
+    outputCount: 2, // Destination output and potentially change
+    addressType: multisigDetails.addressType,
+    requiredSigners: multisigDetails.requiredSigners,
+    totalSigners: multisigDetails.totalSigners,
+  });
+  // Calculate required fee for both transactions
+  const combinedSize = parentTransaction.virtualSize() + childSize;
+  const requiredFee = new BigNumber(combinedSize).multipliedBy(
+    newFeeRate.satoshisPerByte
+  );
+
+  // Calculate amount to send to destination
+  const outputAmount = new BigNumber(parentOutput.value).minus(requiredFee);
+
+  if (outputAmount.isLessThan(546)) {
+    // Check if output would be dust
+    throw new Error("CPFP transaction would create a dust output");
+  }
+
+  const inputs = [{ ...parentOutput, txid: parentTransaction.getId() }];
+  const outputs = [{ address: destinationAddress, amountSats: outputAmount }];
+
+  // Use Caravan's unsignedMultisigTransaction function to create the new transaction
+  return unsignedMultisigTransaction(network, inputs, outputs, true); // true to enable RBF
+}
+
+/**
+ * Find a suitable output from the parent transaction to use for CPFP.
+ * @param parentTransaction The parent transaction
+ * @param availableUTXOs Available UTXOs that can be spent
+ * @returns A suitable output or null if none found
+ */
+function findSuitableParentOutput(
+  parentTransaction: Transaction,
+  availableUTXOs: UTXO[]
+): { index: number; value: number } | null {
+  for (let i = 0; i < parentTransaction.outs.length; i++) {
+    const output = parentTransaction.outs[i];
+    if (
+      availableUTXOs.some(
+        (utxo) => utxo.txid === parentTransaction.getId() && utxo.vout === i
+      )
+    ) {
+      return { index: i, value: output.value };
+    }
+  }
+  return null;
+}
+
+function estimateChildTransactionSize(options: {
+  inputCount: number;
+  outputCount: number;
+  addressType: string;
+  requiredSigners: number;
+  totalSigners: number;
+}): number {
+  const {
+    inputCount,
+    outputCount,
+    addressType,
+    requiredSigners,
+    totalSigners,
+  } = options;
+
+  return estimateVirtualSize(
+    addressType,
+    inputCount,
+    outputCount,
+    requiredSigners,
+    totalSigners
+  );
+}

packages/caravan-fees/src/index.ts

@@ -0,0 +1,6 @@
+export * from "./types";
+export * from "./utils";
+export * from "./transactionAnalyzer";
+export * from "./rbf";
+export * from "./cpfp";
+export * from "./constants";

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

@@ -0,0 +1,86 @@
+import { prepareRBFTransaction } from "./rbf";
+import { Transaction } from "bitcoinjs-lib-v5";
+import { Network, unsignedMultisigTransaction } from "@caravan/bitcoin";
+import BigNumber from "bignumber.js";
+import { RBFOptions, UTXO } from "./types";
+
+jest.mock("@caravan/bitcoin");
+jest.mock("./utils");
+
+describe("RBF", () => {
+  let mockTransaction: Transaction;
+  let mockUTXOs: UTXO[];
+  let mockOptions: RBFOptions;
+
+  beforeEach(() => {
+    mockTransaction = {
+      ins: [{ sequence: 0xfffffffd }],
+      outs: [{ value: 90000, address: "address1" }],
+      getAddressType: jest.fn().mockReturnValue("P2SH"),
+      getRequiredSigners: jest.fn().mockReturnValue(2),
+      getTotalSigners: jest.fn().mockReturnValue(3),
+    } as unknown as Transaction;
+    mockUTXOs = [
+      {
+        txid: "txid1",
+        vout: 0,
+        value: new BigNumber(100000),
+        address: "address1",
+        scriptPubKey: "script1",
+      },
+    ];
+    mockOptions = {
+      transaction: mockTransaction,
+      newFeeRate: { satoshisPerByte: 10 },
+      utxos: mockUTXOs,
+      network: Network.TESTNET,
+    };
+
+    // Mock utility functions
+    jest.requireMock("./utils").isRBFSignaled.mockReturnValue(true);
+    jest.requireMock("./utils").estimateVirtualSize.mockReturnValue(200);
+    (unsignedMultisigTransaction as jest.Mock).mockReturnValue(
+      {} as Transaction
+    );
+  });
+
+  it("should prepare RBF transaction", () => {
+    const result = prepareRBFTransaction(mockOptions);
+    expect(result).toBeDefined();
+    expect(unsignedMultisigTransaction).toHaveBeenCalled();
+  });
+
+  it("should throw error if transaction is not RBF enabled", () => {
+    jest.requireMock("./utils").isRBFSignaled.mockReturnValue(false);
+    expect(() => prepareRBFTransaction(mockOptions)).toThrow(
+      "Original transaction is not signaling RBF"
+    );
+  });
+
+  it("should handle cancelTransaction option", () => {
+    mockOptions.cancelTransaction = true;
+    mockOptions.destinationAddress = "cancelAddress";
+    prepareRBFTransaction(mockOptions);
+    expect(unsignedMultisigTransaction).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.anything(),
+      expect.arrayContaining([
+        expect.objectContaining({ address: "cancelAddress" }),
+      ]),
+      true
+    );
+  });
+
+  it("should handle subtractFromOutput option", () => {
+    mockOptions.subtractFromOutput = true;
+    prepareRBFTransaction(mockOptions);
+    expect(unsignedMultisigTransaction).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.anything(),
+      expect.arrayContaining([
+        expect.objectContaining({ amountSats: expect.any(BigNumber) }),
+      ]),
+      true
+    );
+  });
+});