Rework max fee options in TransactionBuilder & add max fee per byte

Author: rkalis

packages/cashscript/src/TransactionBuilder.ts

@@ -38,6 +38,8 @@ import { WcTransactionObject } from './walletconnect-utils.js';
 
 export interface TransactionBuilderOptions {
   provider: NetworkProvider;
+  maximumFeeSatoshis?: bigint;
+  maximumFeeSatsPerByte?: number;
 }
 
 const DEFAULT_SEQUENCE = 0xfffffffe;
@@ -48,10 +50,9 @@ export class TransactionBuilder {
   public outputs: Output[] = [];
 
   public locktime: number = 0;
-  public maxFee?: bigint;
 
   constructor(
-    options: TransactionBuilderOptions,
+    private options: TransactionBuilderOptions,
   ) {
     this.provider = options.provider;
   }
@@ -102,26 +103,26 @@ export class TransactionBuilder {
     return this;
   }
 
-  setMaxFee(maxFee: bigint): this {
-    this.maxFee = maxFee;
-    return this;
-  }
-
-  private checkMaxFee(): void {
-    if (!this.maxFee) return;
-
+  private checkMaxFee(transaction: LibauthTransaction): void {
     const totalInputAmount = this.inputs.reduce((total, input) => total + input.satoshis, 0n);
     const totalOutputAmount = this.outputs.reduce((total, output) => total + output.amount, 0n);
     const fee = totalInputAmount - totalOutputAmount;
 
-    if (fee > this.maxFee) {
-      throw new Error(`Transaction fee of ${fee} is higher than max fee of ${this.maxFee}`);
+    if (this.options.maximumFeeSatoshis && fee > this.options.maximumFeeSatoshis) {
+      throw new Error(`Transaction fee of ${fee} is higher than max fee of ${this.options.maximumFeeSatoshis}`);
+    }
+
+    if (this.options.maximumFeeSatsPerByte) {
+      const transactionSize = encodeTransaction(transaction).byteLength;
+      const feePerByte = Number(fee) / transactionSize;
+
+      if (feePerByte > this.options.maximumFeeSatsPerByte) {
+        throw new Error(`Transaction fee per byte of ${feePerByte} is higher than max fee per byte of ${this.options.maximumFeeSatsPerByte}`);
+      }
     }
   }
 
   buildLibauthTransaction(): LibauthTransaction {
-    this.checkMaxFee();
-
     const inputs: LibauthTransaction['inputs'] = this.inputs.map((utxo) => ({
       outpointIndex: utxo.vout,
       outpointTransactionHash: hexToBin(utxo.txid),
@@ -149,6 +150,8 @@ export class TransactionBuilder {
       transaction.inputs[i].unlockingBytecode = script;
     });
 
+    this.checkMaxFee(transaction);
+
     return transaction;
   }
 

packages/cashscript/test/TransactionBuilder.test.ts

@@ -80,9 +80,9 @@ describe('Transaction Builder', () => {
       expect(txOutputs).toEqual(expect.arrayContaining(outputs));
     });
 
-    it('should fail when fee is higher than maxFee', async () => {
+    it('should fail when fee is higher than maximumFeeSatoshis', async () => {
       const fee = 2000n;
-      const maxFee = 1000n;
+      const maximumFeeSatoshis = 1000n;
       const p2pkhUtxos = (await p2pkhInstance.getUtxos()).filter(isNonTokenUtxo).sort(utxoComparator).reverse();
 
       const amount = p2pkhUtxos[0].satoshis - fee;
@@ -93,17 +93,16 @@ describe('Transaction Builder', () => {
       }
 
       expect(() => {
-        new TransactionBuilder({ provider })
+        new TransactionBuilder({ provider, maximumFeeSatoshis })
           .addInput(p2pkhUtxos[0], p2pkhInstance.unlock.spend(carolPub, new SignatureTemplate(carolPriv)))
           .addOutput({ to: p2pkhInstance.address, amount })
-          .setMaxFee(maxFee)
           .build();
-      }).toThrow(`Transaction fee of ${fee} is higher than max fee of ${maxFee}`);
+      }).toThrow(`Transaction fee of ${fee} is higher than max fee of ${maximumFeeSatoshis}`);
     });
 
-    it('should succeed when fee is lower than maxFee', async () => {
+    it('should succeed when fee is lower than maximumFeeSatoshis', async () => {
       const fee = 1000n;
-      const maxFee = 2000n;
+      const maximumFeeSatoshis = 2000n;
       const p2pkhUtxos = (await p2pkhInstance.getUtxos()).filter(isNonTokenUtxo).sort(utxoComparator).reverse();
 
       const amount = p2pkhUtxos[0].satoshis - fee;
@@ -113,10 +112,49 @@ describe('Transaction Builder', () => {
         throw new Error('Not enough funds to send transaction');
       }
 
-      const tx = new TransactionBuilder({ provider })
+      const tx = new TransactionBuilder({ provider, maximumFeeSatoshis })
+        .addInput(p2pkhUtxos[0], p2pkhInstance.unlock.spend(carolPub, new SignatureTemplate(carolPriv)))
+        .addOutput({ to: p2pkhInstance.address, amount })
+        .build();
+
+      expect(tx).toBeDefined();
+    });
+
+    it('should fail when fee per byte is higher than maximumFeeSatsPerByte', async () => {
+      const fee = 2000n;
+      const maximumFeeSatsPerByte = 1.0;
+      const p2pkhUtxos = (await p2pkhInstance.getUtxos()).filter(isNonTokenUtxo).sort(utxoComparator).reverse();
+
+      const amount = p2pkhUtxos[0].satoshis - fee;
+      const dustAmount = calculateDust({ to: p2pkhInstance.address, amount });
+
+      if (amount < dustAmount) {
+        throw new Error('Not enough funds to send transaction');
+      }
+
+      expect(() => {
+        new TransactionBuilder({ provider, maximumFeeSatsPerByte })
+          .addInput(p2pkhUtxos[0], p2pkhInstance.unlock.spend(carolPub, new SignatureTemplate(carolPriv)))
+          .addOutput({ to: p2pkhInstance.address, amount })
+          .build();
+      }).toThrow(`Transaction fee per byte of 9.05 is higher than max fee per byte of ${maximumFeeSatsPerByte}`);
+    });
+
+    it('should succeed when fee per byte is lower than maximumFeeSatsPerByte', async () => {
+      const fee = 1000n;
+      const maximumFeeSatsPerByte = 10.0;
+      const p2pkhUtxos = (await p2pkhInstance.getUtxos()).filter(isNonTokenUtxo).sort(utxoComparator).reverse();
+
+      const amount = p2pkhUtxos[0].satoshis - fee;
+      const dustAmount = calculateDust({ to: p2pkhInstance.address, amount });
+
+      if (amount < dustAmount) {
+        throw new Error('Not enough funds to send transaction');
+      }
+
+      const tx = new TransactionBuilder({ provider, maximumFeeSatsPerByte })
         .addInput(p2pkhUtxos[0], p2pkhInstance.unlock.spend(carolPub, new SignatureTemplate(carolPriv)))
         .addOutput({ to: p2pkhInstance.address, amount })
-        .setMaxFee(maxFee)
         .build();
 
       expect(tx).toBeDefined();

website/docs/releases/release-notes.md

@@ -9,6 +9,8 @@ title: Release Notes
 - :boom: **BREAKING**: Make `provider` a required option in `Contract` constructor.
 - :boom: **BREAKING**: Remove deprecated "old" transaction builder (`contract.functions`).
 - :boom: **BREAKING**: No longer seed the MockNetworkProvider with any test UTXOs.
+- :boom: **BREAKING**: Replace `setMaxFee()` method on `TransactionBuilder` with `TransactionBuilderOptions` on the constructor.
+- :sparkles: Add `maximumFeeSatsPerByte` option to `TransactionBuilder` constructor.
 - :sparkles: Add a configurable `vmTarget` option to `MockNetworkProvider`.
 - :sparkles: Add support for ECDSA signatures in contract unlockers for `sig` and `datasig` parameters.
 - :sparkles: Add `signMessageHash()` method to `SignatureTemplate` to allow for signing of non-transaction messages.

website/docs/sdk/transaction-builder.md

@@ -13,15 +13,16 @@ Defining the inputs and outputs requires careful consideration because the diffe
 new TransactionBuilder(options: TransactionBuilderOptions)
 ```
 
-To start, you need to instantiate a transaction builder and pass in a `NetworkProvider` instance.
+To start, you need to instantiate a transaction builder and pass in a `NetworkProvider` instance and other options.
 
 ```ts
 interface TransactionBuilderOptions {
   provider: NetworkProvider;
+  maximumFeeSatoshis?: bigint;
+  maximumFeeSatsPerByte?: number;
 }
 ```
 
-
 #### Example
 ```ts
 import { ElectrumNetworkProvider, TransactionBuilder, Network } from 'cashscript';
@@ -30,6 +31,20 @@ const provider = new ElectrumNetworkProvider(Network.MAINNET);
 const transactionBuilder = new TransactionBuilder({ provider });
 ```
 
+### Constructor Options
+
+#### provider
+
+The `provider` option is used to specify the network provider to use when sending the transaction.
+
+#### maximumFeeSatoshis
+
+The `maximumFeeSatoshis` option is used to specify the maximum fee for the transaction in satoshis. If this fee is exceeded, an error will be thrown when building the transaction.
+
+#### maximumFeeSatsPerByte
+
+The `maximumFeeSatsPerByte` option is used to specify the maximum fee per byte for the transaction. If this fee is exceeded, an error will be thrown when building the transaction.
+
 ## Transaction Building
 
 ### addInput()
@@ -159,18 +174,6 @@ Sets the locktime for the transaction to set a transaction-level absolute timelo
 transactionBuilder.setLocktime(((Date.now() / 1000) + 24 * 60 * 60) * 1000);
 ```
 
-### setMaxFee()
-```ts
-transactionBuilder.setMaxFee(maxFee: bigint): this
-```
-
-Sets a max fee for the transaction. Because the transaction builder does not automatically add a change output, you can set a max fee as a safety measure to make sure you don't accidentally pay too much in fees. If the transaction fee exceeds the max fee, an error will be thrown when building the transaction.
-
-#### Example
-```ts
-transactionBuilder.setMaxFee(1000n);
-```
-
 ## Completing the Transaction
 ### send()
 ```ts