Merge branch 'master' into dp/update-chain-config

FuelLabs · Dec 11, 2024 · e0134e6 · e0134e6
2 parents 5722fbc + a8af330
commit e0134e6
Show file tree

Hide file tree

Showing 114 changed files with 829 additions and 225 deletions.
diff --git a/.changeset/brown-scissors-search.md b/.changeset/brown-scissors-search.md
diff --git a/.changeset/calm-buttons-help.md b/.changeset/calm-buttons-help.md
diff --git a/.changeset/cyan-panthers-carry.md b/.changeset/cyan-panthers-carry.md
diff --git a/.changeset/itchy-forks-worry.md b/.changeset/itchy-forks-worry.md
diff --git a/.changeset/khaki-berries-divide.md b/.changeset/khaki-berries-divide.md
diff --git a/.changeset/khaki-teachers-study.md b/.changeset/khaki-teachers-study.md
diff --git a/.changeset/large-points-arrive.md b/.changeset/large-points-arrive.md
diff --git a/.changeset/late-pugs-carry.md b/.changeset/late-pugs-carry.md
diff --git a/.changeset/long-ducks-jump.md b/.changeset/long-ducks-jump.md
diff --git a/.changeset/polite-impalas-fetch.md b/.changeset/polite-impalas-fetch.md
diff --git a/.changeset/polite-mugs-stare.md b/.changeset/polite-mugs-stare.md
diff --git a/.changeset/polite-seas-taste.md b/.changeset/polite-seas-taste.md
diff --git a/.changeset/quiet-cups-turn.md b/.changeset/quiet-cups-turn.md
diff --git a/.changeset/rare-hornets-rush.md b/.changeset/rare-hornets-rush.md
@@ -0,0 +1,5 @@
+---
+"@fuel-ts/utils": patch
+---
+
+chore: integrate vitest matchers globally
diff --git a/.changeset/red-trainers-mix.md b/.changeset/red-trainers-mix.md
diff --git a/.changeset/rotten-chefs-shake.md b/.changeset/rotten-chefs-shake.md
@@ -0,0 +1,4 @@
+---
+---
+
+docs: add docs for splitting UTXOs, `maxOutputs` and `maxInputs`
diff --git a/.changeset/spicy-mails-sort.md b/.changeset/spicy-mails-sort.md
diff --git a/.changeset/tasty-pumas-approve.md b/.changeset/tasty-pumas-approve.md
diff --git a/.changeset/twenty-needles-buy.md b/.changeset/twenty-needles-buy.md
diff --git a/.changeset/wise-ladybugs-nail.md b/.changeset/wise-ladybugs-nail.md
diff --git a/apps/docs/.vitepress/config.ts b/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',
+              },
             ],
           },
           {

diff --git a/apps/docs/README.md b/apps/docs/README.md
@@ -8,6 +8,7 @@
 - [Table of contents](#table-of-contents)
   - [Building](#building)
   - [Testing](#testing)
+  - [Referencing snippets](#referencing-snippets)
 
 ## Building
 
@@ -42,3 +43,17 @@ If no environment is specified, it will run in the browser and node environments
 ```sh
 pnpm test
 ```
+
+## Referencing snippets
+
+To reference a snippet outside of the current directory, you need to use the following syntax (`<<< @/`):
+
+```md
+`<<< @/../../path/to/snippet.ts#snippet-name{language:line-numbers}
+```
+
+To reference a snippet in the current directory, you can use the following syntax (`<<< @./`):
+
+```md
+`<<< @./snippets/transaction-request/fetch-resources.ts#transaction-request-5{ts:line-numbers}
+```
diff --git a/apps/docs/spell-check-custom-words.txt b/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

diff --git a/apps/docs/src/guide/contracts/contract-balance.md b/apps/docs/src/guide/contracts/contract-balance.md
@@ -4,7 +4,7 @@ When working with contracts, it's crucial to be aware of the available contract
 
 ## The `getBalance` Method
 
-The [`Contract.getBalance`](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_program.Contract.html#getbalance) method retrieves the available balance of a specific asset on your contract. This method is particularly useful for determining the remaining balance after sending assets to a contract and executing contract calls.
+The [`Contract.getBalance`](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_program.Contract.html#getBalance) method retrieves the available balance of a specific asset on your contract. This method is particularly useful for determining the remaining balance after sending assets to a contract and executing contract calls.
 
 It is important to note that this method returns the total available contract balance, regardless of how often assets have been sent to it or spent.
 

diff --git a/apps/docs/src/guide/contracts/cost-estimation.md b/apps/docs/src/guide/contracts/cost-estimation.md
@@ -1,6 +1,6 @@
 # Estimating Contract Call Cost
 
-The [`FunctionInvocationScope.getTransactionCost`](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_program.FunctionInvocationScope.html#gettransactioncost) method allows you to estimate the cost of a specific contract call. The return type, `TransactionCost`, is an object containing relevant information for the estimation:
+The [`FunctionInvocationScope.getTransactionCost`](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_program.FunctionInvocationScope.html#getTransactionCost) method allows you to estimate the cost of a specific contract call. The return type, `TransactionCost`, is an object containing relevant information for the estimation:
 
 <<< @/../../../packages/account/src/providers/provider.ts#cost-estimation-1{ts:line-numbers}
 

diff --git a/apps/docs/src/guide/contracts/dependency-estimation.md b/apps/docs/src/guide/contracts/dependency-estimation.md
@@ -4,6 +4,6 @@ In [variable outputs](./variable-outputs.md), we mention that a contract call mi
 
 However, by default the SDK always automatically estimates these dependencies and double-checks if everything is in order whenever you invoke a contract function or attempt to send a transaction.
 
-The SDK uses the [Provider.estimateTxDependencies](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_account.Provider.html#estimatetxdependencies) method to set any missing dependencies identified during the estimation process. This requires simulating the transaction a few times in the background.
+The SDK uses the [Provider.estimateTxDependencies](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_account.Provider.html#estimateTxDependencies) method to set any missing dependencies identified during the estimation process. This requires simulating the transaction a few times in the background.
 
 While relying on the SDK's automatic estimation is a decent default behavior, we recommend manually specifying the dependencies if they are known in advance to avoid the performance impact of the estimation process.
diff --git a/apps/docs/src/guide/contracts/deploying-contracts.md b/apps/docs/src/guide/contracts/deploying-contracts.md
@@ -53,7 +53,7 @@ Now that the contract is deployed, you can interact with it by submitting a cont
 
 ## Deploying a Large Contract as Blobs
 
-In the above guide we use the recommended `deploy` method. If you are working with a contract that is too large to be deployed in a single transaction, then the SDK will chunk the contract for you and submit it as blobs, to then be accessed later by a create transaction. This process is handled by the [`ContractFactory.deployAsBlobTx`](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_contract.index.ContractFactory.html#deployasblobtx) method.
+In the above guide we use the recommended `deploy` method. If you are working with a contract that is too large to be deployed in a single transaction, then the SDK will chunk the contract for you and submit it as blobs, to then be accessed later by a create transaction. This process is handled by the [`ContractFactory.deployAsBlobTx`](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_contract.index.ContractFactory.html#deployAsBlobTx) method.
 
 <<< @./snippets/deploying-contracts/deployment.ts#blobs{ts:line-numbers}
 

diff --git a/apps/docs/src/guide/contracts/minted-token-asset-id.md b/apps/docs/src/guide/contracts/minted-token-asset-id.md
@@ -23,6 +23,6 @@ Since the asset ID depends on the contract ID, which is always dynamic (unlike t
 
 ## Create Asset Id
 
-The SDK provides a helper named `createAssetId` which takes the contract ID and sub ID as parameters. This helper internally calls `getMintedAssetId` and returns the Sway native parameter [AssetId](https://docs.fuel.network/docs/fuels-ts/interfaces/#assetid), ready to be used in a Sway program invocation:
+The SDK provides a helper named `createAssetId` which takes the contract ID and sub ID as parameters. This helper internally calls `getMintedAssetId` and returns the Sway native parameter [AssetId](https://fuels-ts-docs-api.vercel.app/types/_fuel_ts_interfaces.AssetId.html), ready to be used in a Sway program invocation:
 
 <<< @./snippets/utilities/create-asset-id.ts#create-asset-id-1{ts:line-numbers}
diff --git a/apps/docs/src/guide/cookbook/combining-utxos.md b/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}
diff --git a/apps/docs/src/guide/cookbook/snippets/max-outputs.ts b/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);
diff --git a/apps/docs/src/guide/cookbook/snippets/splitting-utxos.ts b/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
diff --git a/apps/docs/src/guide/cookbook/splitting-utxos.md b/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}
diff --git a/apps/docs/src/guide/predicates/methods.md b/apps/docs/src/guide/predicates/methods.md
@@ -1,6 +1,6 @@
 # Interacting With Predicates
 
-The `Predicate` class extends the [`Account`](https://docs.fuel.network/docs/fuels-ts/account/) class, inheriting all its methods. Therefore, there are multiple ways to interact with predicates, but broadly speaking, we can think about three:
+The `Predicate` class extends the [`Account`](https://fuels-ts-docs-api.vercel.app/modules/_fuel_ts_account.html) class, inheriting all its methods. Therefore, there are multiple ways to interact with predicates, but broadly speaking, we can think about three:
 
 - `Checking Balances`
 - `Transactions`

diff --git a/apps/docs/src/guide/provider/provider-options.md b/apps/docs/src/guide/provider/provider-options.md
@@ -1,6 +1,6 @@
 # Provider Options
 
-You can provide various [options](https://fuels-ts-docs-api.vercel.app/modules/_fuel_ts_account.html#provideroptions) on `Provider` instantiation to modify its behavior.
+You can provide various [options](https://fuels-ts-docs-api.vercel.app/types/_fuel_ts_account.ProviderOptions.html) on `Provider` instantiation to modify its behavior.
 
 ### `retryOptions`
 

diff --git a/apps/docs/src/guide/testing/launching-a-test-node.md b/apps/docs/src/guide/testing/launching-a-test-node.md
@@ -4,7 +4,7 @@ To simplify testing in isolation, we provide a utility called `launchTestNode`.
 
 It allows you to spin up a short-lived `fuel-core` node, set up a custom provider, wallets, deploy contracts, and much more in one go.
 
-For usage information for `launchTestNode` including it's inputs, outputs and options, please check the [API reference](https://fuels-ts-docs-api.vercel.app/modules/_fuel_ts_contract.test_utils.html#launchtestnode).
+For usage information for `launchTestNode` including it's inputs, outputs and options, please check the [API reference](https://fuels-ts-docs-api.vercel.app/functions/_fuel_ts_contract.test_utils.launchTestNode.html).
 
 ## Explicit Resource Management
 

diff --git a/apps/docs/src/guide/transactions/transaction-request.md b/apps/docs/src/guide/transactions/transaction-request.md
@@ -60,7 +60,7 @@ If needed, you can manually include specific coins or messages in the transactio
 
 Imagine that you have a Sway script that manually calls a contract:
 
-<<< @../../../../sway/script-call-contract/src/main.sw#transaction-request-7{rs:line-numbers}
+<<< @/../../docs/sway/script-call-contract/src/main.sw#transaction-request-7{rs:line-numbers}
 
 In those cases, you will need to add both an `InputContract` and `OutputContract` to the transaction request:
 

diff --git a/apps/docs/src/guide/utilities/using-assets.md b/apps/docs/src/guide/utilities/using-assets.md
@@ -1,6 +1,6 @@
 # Assets
 
-We export an array of [`Asset`](https://docs.fuel.network/docs/fuels-ts/account/#asset) objects, that can be useful when creating your dApp. The `Asset` object has useful metadata about the different assets that are available on blockchain networks (Fuel and Ethereum).
+We export an array of [`Asset`](https://fuels-ts-docs-api.vercel.app/types/_fuel_ts_account.Asset.html) objects, that can be useful when creating your dApp. The `Asset` object has useful metadata about the different assets that are available on blockchain networks (Fuel and Ethereum).
 
 Included assets such as:
 
@@ -9,6 +9,6 @@ Included assets such as:
 - USD Coin (USDC)
 - Wrapped ETH (WETH)
 
-The helper functions `getAssetFuel` and `getAssetEth` can be used to get an asset's details relative to each network. These return a combination of the asset, and network information (the return types are [`AssetFuel`](https://fuels-ts-docs-api.vercel.app/modules/_fuel_ts_account.html#assetfuel) and [`AssetEth`](https://fuels-ts-docs-api.vercel.app/modules/_fuel_ts_account.html#asseteth) respectively).
+The helper functions `getAssetFuel` and `getAssetEth` can be used to get an asset's details relative to each network. These return a combination of the asset, and network information (the return types are [`AssetFuel`](https://fuels-ts-docs-api.vercel.app/types/_fuel_ts_account.AssetFuel.html) and [`AssetEth`](https://fuels-ts-docs-api.vercel.app/types/_fuel_ts_account.AssetEth.html) respectively).
 
 <<< @./snippets/using-assets.ts#using-assets-1{ts:line-numbers}
diff --git a/apps/docs/src/guide/wallets/checking-balances.md b/apps/docs/src/guide/wallets/checking-balances.md
@@ -1,9 +1,9 @@
 # Checking balances
 
-To check the balance of a specific asset, you can use [`getBalance`](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_account.Account.html#getbalance) method. This function aggregates the amounts of all unspent coins of the given asset in your wallet.
+To check the balance of a specific asset, you can use [`getBalance`](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_account.Account.html#getBalance) method. This function aggregates the amounts of all unspent coins of the given asset in your wallet.
 
 <<< @./snippets/checking-balances.ts#checking-balances-1{ts:line-numbers}
 
-To retrieve the balances of all assets in your wallet, use the [`getBalances`](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_account.Account.html#getbalances) method, it returns an array of [`CoinQuantity`](https://fuels-ts-docs-api.vercel.app/modules/_fuel_ts_account.html#coinquantity). This is useful for getting a comprehensive view of your holdings.
+To retrieve the balances of all assets in your wallet, use the [`getBalances`](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_account.Account.html#getBalances) method, it returns an array of [`CoinQuantity`](https://fuels-ts-docs-api.vercel.app/types/_fuel_ts_account.CoinQuantity.html). This is useful for getting a comprehensive view of your holdings.
 
 <<< @./snippets/checking-balances-two.ts#checking-balances-2{ts:line-numbers}