Add allowImplicitFungibleTokenBurn option to TransactionBuilder

Author: rkalis

packages/cashscript/src/TransactionBuilder.ts

@@ -40,6 +40,7 @@ export interface TransactionBuilderOptions {
   provider: NetworkProvider;
   maximumFeeSatoshis?: bigint;
   maximumFeeSatsPerByte?: number;
+  allowImplicitFungibleTokenBurn?: boolean;
 }
 
 const DEFAULT_SEQUENCE = 0xfffffffe;
@@ -50,11 +51,16 @@ export class TransactionBuilder {
   public outputs: Output[] = [];
 
   public locktime: number = 0;
+  public options: TransactionBuilderOptions;
 
   constructor(
-    private options: TransactionBuilderOptions,
+    options: TransactionBuilderOptions,
   ) {
     this.provider = options.provider;
+    this.options = {
+      allowImplicitFungibleTokenBurn: options.allowImplicitFungibleTokenBurn ?? false,
+      ...options,
+    };
   }
 
   addInput(utxo: Utxo, unlocker: Unlocker, options?: InputOptions): this {
@@ -114,15 +120,42 @@ export class TransactionBuilder {
 
     if (this.options.maximumFeeSatsPerByte) {
       const transactionSize = encodeTransaction(transaction).byteLength;
-      const feePerByte = Number(fee) / transactionSize;
+      const feePerByte = Number((Number(fee) / transactionSize).toFixed(2));
 
       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}`);
       }
     }
   }
 
+  private checkFungibleTokenBurn(): void {
+    if (this.options.allowImplicitFungibleTokenBurn) return;
+
+    const tokenInputAmounts: Record<string, bigint> = {};
+    const tokenOutputAmounts: Record<string, bigint> = {};
+
+    for (const input of this.inputs) {
+      if (input.token?.amount) {
+        tokenInputAmounts[input.token.category] = (tokenInputAmounts[input.token.category] || 0n) + input.token.amount;
+      }
+    }
+    for (const output of this.outputs) {
+      if (output.token?.amount) {
+        tokenOutputAmounts[output.token.category] = (tokenOutputAmounts[output.token.category] || 0n) + output.token.amount;
+      }
+    }
+
+    for (const [category, inputAmount] of Object.entries(tokenInputAmounts)) {
+      const outputAmount = tokenOutputAmounts[category] || 0n;
+      if (outputAmount < inputAmount) {
+        throw new Error(`Implicit burning of fungible tokens for category ${category} is not allowed (input amount: ${inputAmount}, output amount: ${outputAmount}). If this is intended, set allowImplicitFungibleTokenBurn to true.`);
+      }
+    }
+  }
+
   buildLibauthTransaction(): LibauthTransaction {
+    this.checkFungibleTokenBurn();
+
     const inputs: LibauthTransaction['inputs'] = this.inputs.map((utxo) => ({
       outpointIndex: utxo.vout,
       outpointTransactionHash: hexToBin(utxo.txid),

packages/cashscript/test/e2e/P2PKH-tokens.test.ts

@@ -195,24 +195,18 @@ describe('P2PKH-tokens', () => {
 
     it('should throw an error when trying to send a token the contract doesn\'t have', async () => {
       const contractUtxos = await p2pkhInstance.getUtxos();
-      const tokenUtxo = contractUtxos.find(isFungibleTokenUtxo);
       const nonTokenUtxos = contractUtxos.filter(isNonTokenUtxo);
 
-      if (!tokenUtxo) {
-        throw new Error('No token UTXO found with fungible tokens');
-      }
-
       const to = p2pkhInstance.tokenAddress;
       const amount = 1000n;
-      const token = { ...tokenUtxo.token!, category: '0000000000000000000000000000000000000000000000000000000000000000' };
+      const token = { category: '0000000000000000000000000000000000000000000000000000000000000000', amount: 100n };
       const fee = 1000n;
-      const fullBchBalance = nonTokenUtxos.reduce((total, utxo) => total + utxo.satoshis, 0n) + tokenUtxo.satoshis;
+      const fullBchBalance = nonTokenUtxos.reduce((total, utxo) => total + utxo.satoshis, 0n);
       const changeAmount = fullBchBalance - fee - amount;
 
       const unlocker = p2pkhInstance.unlock.spend(alicePub, new SignatureTemplate(alicePriv));
       const txPromise = new TransactionBuilder({ provider })
         .addInputs(nonTokenUtxos, unlocker)
-        .addInput(tokenUtxo, unlocker)
         .addOutput({ to, amount, token })
         .addOutput({ to, amount: changeAmount })
         .send();
@@ -251,8 +245,59 @@ describe('P2PKH-tokens', () => {
       );
     });
 
-    it.todo('cannot burn fungible tokens when allowImplicitFungibleTokenBurn is false (default)');
-    it.todo('can burn fungible tokens when allowImplicitFungibleTokenBurn is true');
+    it('cannot burn fungible tokens when allowImplicitFungibleTokenBurn is false (default)', async () => {
+      const contractUtxos = await p2pkhInstance.getUtxos();
+      const tokenUtxo = contractUtxos.find(isFungibleTokenUtxo);
+      const nonTokenUtxos = contractUtxos.filter(isNonTokenUtxo);
+
+      if (!tokenUtxo) {
+        throw new Error('No token UTXO found with fungible tokens');
+      }
+
+      const to = p2pkhInstance.tokenAddress;
+      const amount = 1000n;
+      const token = { ...tokenUtxo.token!, amount: tokenUtxo.token!.amount - 1n };
+      const fee = 1000n;
+      const fullBchBalance = nonTokenUtxos.reduce((total, utxo) => total + utxo.satoshis, 0n) + tokenUtxo.satoshis;
+      const changeAmount = fullBchBalance - fee - amount;
+
+      const unlocker = p2pkhInstance.unlock.spend(alicePub, new SignatureTemplate(alicePriv));
+      const txPromise = new TransactionBuilder({ provider })
+        .addInputs(nonTokenUtxos, unlocker)
+        .addInput(tokenUtxo, unlocker)
+        .addOutput({ to, amount, token })
+        .addOutput({ to, amount: changeAmount })
+        .send();
+
+      await expect(txPromise).rejects.toThrow('Implicit burning of fungible tokens for category');
+    });
+
+    it('can burn fungible tokens when allowImplicitFungibleTokenBurn is true', async () => {
+      const contractUtxos = await p2pkhInstance.getUtxos();
+      const tokenUtxo = contractUtxos.find(isFungibleTokenUtxo);
+      const nonTokenUtxos = contractUtxos.filter(isNonTokenUtxo);
+
+      if (!tokenUtxo) {
+        throw new Error('No token UTXO found with fungible tokens');
+      }
+
+      const to = p2pkhInstance.tokenAddress;
+      const amount = 1000n;
+      const token = { ...tokenUtxo.token!, amount: tokenUtxo.token!.amount - 1n };
+      const fee = 1000n;
+      const fullBchBalance = nonTokenUtxos.reduce((total, utxo) => total + utxo.satoshis, 0n) + tokenUtxo.satoshis;
+      const changeAmount = fullBchBalance - fee - amount;
+
+      const unlocker = p2pkhInstance.unlock.spend(alicePub, new SignatureTemplate(alicePriv));
+      const txPromise = new TransactionBuilder({ provider, allowImplicitFungibleTokenBurn: true })
+        .addInputs(nonTokenUtxos, unlocker)
+        .addInput(tokenUtxo, unlocker)
+        .addOutput({ to, amount, token })
+        .addOutput({ to, amount: changeAmount })
+        .send();
+
+      await expect(txPromise).resolves.toBeDefined();
+    });
   });
 });
 

website/docs/releases/release-notes.md

@@ -10,7 +10,7 @@ title: Release Notes
 - :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 `maximumFeeSatsPerByte` and `allowImplicitFungibleTokenBurn` options 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

@@ -45,6 +45,10 @@ The `maximumFeeSatoshis` option is used to specify the maximum fee for the trans
 
 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.
 
+#### allowImplicitFungibleTokenBurn
+
+The `allowImplicitFungibleTokenBurn` option is used to specify whether implicit burning of fungible tokens is allowed (default: `false`). If this is set to `true`, the transaction builder will not throw an error when burning fungible tokens.
+
 ## Transaction Building
 
 ### addInput()