docs: add docs for splitting UTXOs, maxOutputs and maxInputs (#3435)

* docs: add max outputs documentation to combining UTXO docs

* docs: add changeset

* docs: updated spelling

* docs: linting fixes

* docs: add max inputs and outputs snippet

* feat: add function for splitting UTXOs and docs on maxOutputs

* docs: update changeset

* build: update lockfile

* build: update spellcheck

* test: add environment to tests

* fix: update return type from splitting utxos function

* docs: add vitepress config for docs

* test: cover fees

* docs: update title

Co-authored-by: Daniel Bate <[email protected]>

* docs: update grammatical issues

Co-authored-by: Daniel Bate <[email protected]>

* docs: update grammar

Co-authored-by: Daniel Bate <[email protected]>

* docs: remove unnecessary fullstop

Co-authored-by: Daniel Bate <[email protected]>

* docs: update snippets comment

Co-authored-by: Sérgio Torres <[email protected]>

* docs: update snippet formatting

Co-authored-by: Sérgio Torres <[email protected]>

* fix: adjust tests and documentation errors

* docs: update JS docs

* docs: adjust grammatical issue in max inputs/outputs

* docs: add full stop

Co-authored-by: Dhaiwat <[email protected]>

* docs: update docs

* docs: update changeset

* mend

---------

Co-authored-by: Daniel Bate <[email protected]>
Co-authored-by: Sérgio Torres <[email protected]>
Co-authored-by: Dhaiwat <[email protected]>

.changeset/rotten-chefs-shake.md

@@ -0,0 +1,4 @@
+---
+---
+
+docs: add docs for splitting UTXOs, `maxOutputs` and `maxInputs`

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,59 @@
+// #region splitting-utxos
+import { Provider, Wallet } from 'fuels';
+
+import { LOCAL_NETWORK_URL, WALLET_PVT_KEY } from '../../../env';
+
+const provider = await Provider.create(LOCAL_NETWORK_URL);
+// This is the wallet that will fund the sending wallet
+const fundingWallet = Wallet.fromPrivateKey(WALLET_PVT_KEY, provider);
+
+// This is the wallet that will send the funds
+const wallet = Wallet.generate({ provider });
+// This is the wallet that will receive the funds
+const destinationWallet = Wallet.generate({ provider });
+
+// Let's fund the sending 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 large 1000 UTXO into 5 UTXOs of 200 each,
+// Including the address to send the funds to and the assetId we want to send
+const splitTxns = new Array(5).fill({
+  amount: 200,
+  assetId: provider.getBaseAssetId(),
+  destination: destinationWallet.address,
+});
+
+// We will also need add some funds to the wallet to cover the fee
+// We could have also spent less than 200 for each UTXO, but this is just an example
+const fundTx = await fundingWallet.transfer(
+  wallet.address,
+  500,
+  provider.getBaseAssetId()
+);
+await fundTx.waitForResult();
+
+console.log('Split UTXOs', splitTxns);
+// [
+//   { 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(splitTxns);
+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.
+
+> **Note:** Depending on how many smaller UTXOs you want to create, you may need to fund the wallet with additional funds to cover the fees. As we see in the example below, we fund the sending wallet with 500 to cover the fees for the batch transfer.
+
+<<< @./snippets/splitting-utxos.ts#splitting-utxos{ts:line-numbers}