feat: add function for splitting UTXOs and docs on maxOutputs

.changeset/rotten-chefs-shake.md

@@ -0,0 +1,5 @@
+---
+"@fuel-ts/utils": patch
+---
+
+feat: add function for splitting UTXOs and docs on `maxOutputs`

apps/docs/.vitepress/config.ts

@@ -425,6 +425,10 @@ export default defineConfig({
                 text: 'Combining UTXOs',
                 link: '/guide/cookbook/combining-utxos',
               },
+              {
+                text: 'Splitting UTXOs',
+                link: '/guide/cookbook/splitting-utxos',
+              },
             ],
           },
           {

apps/docs/spell-check-custom-words.txt

@@ -291,6 +291,7 @@ tsconfig
 TTL
 tuple's
 turbofish
+TxParameters
 TypeChain
 typeclass
 typedoc
@@ -321,6 +322,7 @@ Utils
 Utils
 UTXO
 UTXOs
+utxos
 validator
 validators
 vercel

apps/docs/src/guide/cookbook/combining-utxos.md

@@ -9,3 +9,9 @@ One way to avoid these errors is to combine your UTXOs. This can be done by perf
 > **Note:** You will not be able to have a single UTXO for the base asset after combining, as one output will be for the transfer, and you will have another for the fees.
 
 <<< @./snippets/combining-utxos.ts#combining-utxos{ts:line-numbers}
+
+## Max Inputs and Outputs
+
+It's also important to note that depending on the chain configuration, you may be limited on the number of inputs and/or outputs that you can have in a transaction. These amounts can be queried via the [TxParameters](https://docs.fuel.network/docs/graphql/reference/objects/#txparameters) GraphQL query
+
+<<< @./snippets/max-outputs.ts#max-outputs{ts:line-numbers}

apps/docs/src/guide/cookbook/snippets/max-outputs.ts

@@ -0,0 +1,13 @@
+// #region max-outputs
+import { Provider } from 'fuels';
+
+import { LOCAL_NETWORK_URL } from '../../../env';
+
+const provider = await Provider.create(LOCAL_NETWORK_URL);
+
+const { maxInputs, maxOutputs } =
+  provider.getChain().consensusParameters.txParameters;
+
+// #endregion max-outputs
+console.log('Max Inputs', maxInputs);
+console.log('Max Outputs', maxOutputs);

apps/docs/src/guide/cookbook/snippets/splitting-utxos.ts

@@ -0,0 +1,55 @@
+// #region splitting-utxos
+import { BN, Provider, Wallet, splitUTXOs } from 'fuels';
+
+import { LOCAL_NETWORK_URL, WALLET_PVT_KEY } from '../../../env';
+
+const provider = await Provider.create(LOCAL_NETWORK_URL);
+const fundingWallet = Wallet.fromPrivateKey(WALLET_PVT_KEY, provider);
+
+const wallet = Wallet.generate({ provider });
+
+// Let's fund the wallet with 1000 of the base asset
+const fundingTx = await fundingWallet.transfer(
+  wallet.address,
+  1000,
+  provider.getBaseAssetId()
+);
+await fundingTx.waitForResult();
+
+// We can fetch the coins to see how many UTXOs we have and confirm it is 1
+const { coins: initialCoins } = await wallet.getCoins(
+  provider.getBaseAssetId()
+);
+console.log('Initial Coins Length', initialCoins.length);
+// 1
+
+// Now we can split the UTXO into 5 UTXOs of 200 each
+const splitTx = splitUTXOs(
+  new BN(1000),
+  new BN(200),
+  provider.getBaseAssetId(),
+  wallet.address,
+  5
+);
+
+// We will also add some funds to the wallet to cover the fee
+const fundTx = await fundingWallet.transfer(
+  wallet.address,
+  500,
+  provider.getBaseAssetId()
+);
+await fundTx.waitForResult();
+
+console.log('Split UTXOs', splitTx);
+// [
+//   { amount: 200, assetId: '0x0', destination	: '0x...' },
+//   { amount: 200, assetId: '0x0', destination: '0x...' },
+//   { amount: 200, assetId: '0x0', destination: '0x...' },
+//   { amount: 200, assetId: '0x0', destination: '0x...' },
+//   { amount: 200, assetId: '0x0', destination: '0x...' }
+// ]
+
+// Then we can send the transactions using the batchTransfer function
+const batchTx = await wallet.batchTransfer(splitTx);
+await batchTx.waitForResult();
+// #endregion splitting-utxos

apps/docs/src/guide/cookbook/splitting-utxos.md

@@ -0,0 +1,7 @@
+# Splitting UTXOs
+
+There may be times when you want to split one large UTXO into multiple smaller UTXOs. This can be useful if you want to send multiple concurrent transactions without having to wait for them to be processed sequentially.
+
+To split a UTXO, you can use the `splitUTXOs` function. This will return an array of the number of UTXOs each with the specified amount, as long as the balance is greater than the amount.
+
+<<< @./snippets/splitting-utxos.ts#splitting-utxos{ts:line-numbers}

packages/utils/src/index.ts

@@ -14,6 +14,7 @@ export * from './utils/dataSlice';
 export * from './utils/toUtf8Bytes';
 export * from './utils/toUtf8String';
 export * from './utils/bytecode';
+export * from './utils/split-utxos';
 
 /**
  * Used to verify that a switch statement exhausts all variants.

packages/utils/src/utils/split-utxos.test.ts

@@ -0,0 +1,53 @@
+import { FuelError, ErrorCode } from '@fuel-ts/errors';
+import { expectToThrowFuelError } from '@fuel-ts/errors/test-utils';
+import type { AbstractAddress } from '@fuel-ts/interfaces';
+import { BN } from '@fuel-ts/math';
+
+import { splitUTXOs } from './split-utxos';
+
+/**
+ * @group node
+ * @group browser
+ */
+describe('splitUTXOs', () => {
+  it('should generate two UTXOs by default', () => {
+    // using unknown as AbstractAddress to avoid importing @fuel-ts/address as that's a circular dependency
+    const destination = '0x...' as unknown as AbstractAddress;
+
+    expect(splitUTXOs(new BN(100), new BN(10), '0x0', destination)).toEqual([
+      { amount: new BN(10), assetId: '0x0', destination },
+      { amount: new BN(10), assetId: '0x0', destination },
+    ]);
+  });
+
+  it('should throw an error if the balance is zero', async () => {
+    const destination = '0x...' as unknown as AbstractAddress;
+
+    await expectToThrowFuelError(
+      () => splitUTXOs(new BN(0), new BN(10), '0x0', destination),
+      new FuelError(ErrorCode.INVALID_DATA, 'Balance must be greater than zero')
+    );
+  });
+
+  it('should generate an exact number of UTXOs if specified', () => {
+    const destination = '0x...' as unknown as AbstractAddress;
+
+    expect(splitUTXOs(new BN(100), new BN(10), '0x0', destination, 3)).toEqual([
+      { amount: new BN(10), assetId: '0x0', destination },
+      { amount: new BN(10), assetId: '0x0', destination },
+      { amount: new BN(10), assetId: '0x0', destination },
+    ]);
+  });
+
+  it('should throw an error if the number of coins to split into is greater than the balance', async () => {
+    const destination = '0x...' as unknown as AbstractAddress;
+
+    await expectToThrowFuelError(
+      () => splitUTXOs(new BN(40), new BN(10), '0x0', destination, 5),
+      new FuelError(
+        ErrorCode.INVALID_DATA,
+        'The number of coins to split into is greater than the balance'
+      )
+    );
+  });
+});

packages/utils/src/utils/split-utxos.ts

@@ -0,0 +1,36 @@
+import { ErrorCode, FuelError } from '@fuel-ts/errors';
+import type { AbstractAddress } from '@fuel-ts/interfaces';
+import type { BN } from '@fuel-ts/math';
+
+/**
+ * This function allows a consumer to split a UTXO into multiple smaller UTXOs
+ * @param balance - The total balance that the user wants to split, this is equivalent of the amount you would like to send to the recipient
+ * @param amount - The amount of each UTXO
+ * @param assetId - The asset ID of the UTXOs
+ * @param destination - The destination address for the UTXOs
+ * @param number_of_coins - The number of UTXOs to split into, it defaults to 2
+ * @returns An array of the desired UTXOs with the amount, assetId, and destination address
+ */
+export function splitUTXOs(
+  balance: BN,
+  amount: BN,
+  assetId: string,
+  destination: AbstractAddress,
+  number_of_coins: number = 2
+): { amount: BN; assetId: string; destination: string }[] {
+  if (balance.lte(0)) {
+    throw new FuelError(ErrorCode.INVALID_DATA, 'Balance must be greater than zero');
+  }
+  if (balance.divRound(amount).lt(number_of_coins)) {
+    throw new FuelError(
+      ErrorCode.INVALID_DATA,
+      'The number of coins to split into is greater than the balance'
+    );
+  }
+
+  return new Array(number_of_coins).fill({
+    amount,
+    assetId,
+    destination,
+  });
+}