Merge branch 'master' into ps/feat/improved-sdk-wallet-communication

.changeset/fifty-seals-fetch.md

@@ -0,0 +1,5 @@
+---
+"@fuel-ts/account": patch
+---
+
+feat: consider `assetId` in check account utility

.changeset/real-schools-poke.md

@@ -0,0 +1,13 @@
+---
+"@fuel-ts/transactions": minor
+"@internal/fuel-core": minor
+"@fuel-ts/contract": minor
+"@fuel-ts/versions": minor
+"@fuel-ts/account": minor
+"@fuel-ts/program": minor
+"@fuel-ts/recipes": minor
+"@fuel-ts/errors": minor
+"@fuel-ts/utils": minor
+---
+
+chore!: upgrade `fuel-core` to `0.41.7`

.eslintrc.js

@@ -60,6 +60,7 @@ module.exports = {
     'import/prefer-default-export': 'off',
     'tsdoc/syntax': 'warn',
     'require-await': 'off',
+    'no-empty': ['error', { allowEmptyCatch: true }],
     '@typescript-eslint/require-await': 'error',
     '@typescript-eslint/no-floating-promises': 'error',
     '@typescript-eslint/no-unused-vars': [

apps/create-fuels-counter-guide/fuel-toolchain.toml

@@ -3,4 +3,4 @@ channel = "testnet"
 
 [components]
 forc = "0.66.7"
-fuel-core = "0.40.4"
+fuel-core = "0.41.7"

apps/demo-bun-fuels/src/bun.test.ts

@@ -81,8 +81,8 @@ describe('ExampleContract', () => {
     await expectToThrowFuelError(
       () => contractInstance.functions.return_input(1337).simulate(),
       new FuelError(
-        ErrorCode.NOT_ENOUGH_FUNDS,
-        `The account(s) sending the transaction don't have enough funds to cover the transaction.`
+        ErrorCode.INSUFFICIENT_FUNDS_OR_MAX_COINS,
+        `Insufficient funds or too many small value coins. Consider combining UTXOs.`
       )
     );
   });

apps/demo-fuels/src/index.test.ts

@@ -74,8 +74,8 @@ describe('ExampleContract', () => {
     await expectToThrowFuelError(
       () => contractInstance.functions.return_input(1337).simulate(),
       new FuelError(
-        ErrorCode.NOT_ENOUGH_FUNDS,
-        `The account(s) sending the transaction don't have enough funds to cover the transaction.`
+        ErrorCode.INSUFFICIENT_FUNDS_OR_MAX_COINS,
+        `Insufficient funds or too many small value coins. Consider combining UTXOs.`
       )
     );
   });

apps/demo-nextjs/package.json

@@ -10,7 +10,7 @@
     "pretest": "pnpm original:build"
   },
   "dependencies": {
-    "@fuels/vm-asm": "0.58.2",
+    "@fuels/vm-asm": "0.59.1",
     "@types/node": "22.13.5",
     "@types/react-dom": "19.0.4",
     "@types/react": "19.0.10",

apps/demo-react-cra/package.json

@@ -3,7 +3,7 @@
   "version": "0.1.29",
   "private": true,
   "dependencies": {
-    "@fuels/vm-asm": "0.58.2",
+    "@fuels/vm-asm": "0.59.1",
     "@testing-library/react": "16.2.0",
     "@types/node": "22.13.5",
     "@types/react": "19.0.10",

apps/demo-react-vite/package.json

@@ -11,7 +11,7 @@
     "pretest": "pnpm original:build"
   },
   "dependencies": {
-    "@fuels/vm-asm": "0.58.2",
+    "@fuels/vm-asm": "0.59.1",
     "fuels": "workspace:*",
     "react-dom": "19.0.0",
     "react": "19.0.0"

apps/demo-typegen/src/demo.test.ts

@@ -108,8 +108,8 @@ it('should throw when simulating via contract factory with wallet with no resour
   await expectToThrowFuelError(
     () => contractInstance.functions.return_input(1337).simulate(),
     new FuelError(
-      ErrorCode.NOT_ENOUGH_FUNDS,
-      `The account(s) sending the transaction don't have enough funds to cover the transaction.`
+      ErrorCode.INSUFFICIENT_FUNDS_OR_MAX_COINS,
+      `Insufficient funds or too many small value coins. Consider combining UTXOs.`
     )
   );
 });

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

@@ -1,6 +1,6 @@
 # Combining UTXOs
 
-When performing a funding operation or calling `getResourcesToSpend`, you may encounter the `MAX_COINS_REACHED` error if the number of coins fetched per asset exceeds the maximum limit allowed by the chain.
+When performing a funding operation or calling `getResourcesToSpend`, you may encounter the `INSUFFICIENT_FUNDS_OR_MAX_COINS` error if the number of coins fetched per asset exceeds the maximum limit allowed by the chain.
 
 You may also want to do this if you want to reduce the number of inputs in your transaction, which can be useful if you are trying to reduce the size of your transaction or you are receiving the `MAX_INPUTS_EXCEEDED` error.
 

apps/docs/src/guide/errors/index.md

@@ -276,11 +276,19 @@ When the Fuel Node info cache is empty; This is usually caused by not being conn
 
 Ensure that the provider has connected to a Fuel Node successfully.
 
-### `NOT_ENOUGH_FUNDS`
+### `INSUFFICIENT_FUNDS_OR_MAX_COINS`
 
-When the account sending the transaction does not have enough funds to cover the fee.
+This error can occur during a funding operation or when calling the `getResourcesToSpend` method. It indicates one of the following issues:
 
-Ensure that the account creating the transaction has been funded appropriately.
+`Insufficient Balance`: The specified account does not have enough balance to cover the required amount.
+
+`UTXO Limit Exceeded`: Although the account has enough total funds, the funds are spread across too many UTXOs (coins). The blockchain limits how many UTXOs can be used in a single transaction, and exceeding this limit prevents the transaction from being processed.
+
+First, to be sure what the real reason is, you can fetch the [balance](../wallets/checking-balances.md) of the `assetId` to ensure that the account has enough funds to cover the amount. After knowing the reason, to solve you can:
+
+`For Insufficient Balance`: Acquire additional funds in the required asset to meet the amount needed.
+
+`For UTXO Limit Exceeded`: Combine UTXOs to reduce their number and meet the network's requirements. You can follow [this guide](../cookbook/combining-utxos.md) to learn how to combine UTXOs effectively.
 
 ### `TIMEOUT_EXCEEDED`
 
@@ -331,9 +339,3 @@ When the number of transaction inputs exceeds the maximum limit allowed by the b
 ### `MAX_OUTPUTS_EXCEEDED`
 
 When the number of transaction outputs exceeds the maximum limit allowed by the blockchain.
-
-### `MAX_COINS_REACHED`
-
-When performing a funding operation, or calling `getResourcesToSpend`, this error can be thrown if the number of coins fetched per asset exceeds the maximum limit allowed by the blockchain.
-
-This can be avoided by paginating the results of the `getCoins` method to fund your transaction, or by reducing the number of UTXOs for your account. This can be done by performing a transfer that amalgamates your UTXOs, as demonstrated in [this cookbook](../cookbook/combining-utxos.md).

apps/docs/src/guide/predicates/snippets/cookbook/failure-not-enough-funds.ts

@@ -25,7 +25,7 @@ const { error } = await safeExec(async () =>
 );
 
 // #region send-and-spend-funds-from-predicates-6
-const errorMessage = `The account(s) sending the transaction don't have enough funds to cover the transaction.`;
+const errorMessage = `Insufficient funds or too many small value coins. Consider combining UTXOs.`;
 // #endregion send-and-spend-funds-from-predicates-6
 
 const actualErrorMessage = (<Error>error).message;

apps/docs/src/guide/transactions/adding-parameters.md

@@ -4,7 +4,7 @@ Transaction parameters allow you to configure various aspects of your blockchain
 
 All available parameters are shown below:
 
-<<< @./snippets/transaction-parameters.ts#transaction-parameters-6{ts:line-numbers}
+<<< @./snippets/transaction-parameters.ts#transaction-parameters-7{ts:line-numbers}
 
 ## Gas Limit
 
@@ -38,6 +38,12 @@ The maximum byte length allowed for the transaction witnesses array. For instanc
 
 <<< @./snippets/transaction-parameters.ts#transaction-parameters-5{ts:line-numbers}
 
+## Expiration
+
+The block number after which the transaction can no longer be included in the blockchain. For example, if you set the expiration block for your transaction to 200, and the transaction remains in the queue waiting to be processed when block 200 is created, the transaction will be rejected.
+
+<<< @./snippets/transaction-parameters.ts#transaction-parameters-6{ts:line-numbers}
+
 ## Variable Outputs
 
 The number of variable outputs that should be added to the transaction request. You can read more about it on this [guide](../contracts/variable-outputs.md)
@@ -48,11 +54,11 @@ The number of variable outputs that should be added to the transaction request.
 
 To set the transaction parameters, you have access to the `txParams` method on a transaction request.
 
-<<< @./snippets/transaction-parameters.ts#transaction-parameters-7{ts:line-numbers}
+<<< @./snippets/transaction-parameters.ts#transaction-parameters-8{ts:line-numbers}
 
 The same method is also accessible within a function invocation scope, so it can also be used when calling contract functions.
 
-<<< @./snippets/transaction-parameters.ts#transaction-parameters-8{ts:line-numbers}
+<<< @./snippets/transaction-parameters.ts#transaction-parameters-9{ts:line-numbers}
 
 > **Note:** When performing an action that results in a transaction (e.g. contract deployment, contract call with `.call()`, asset transfer), the SDK will automatically estimate the fee based on the gas limit and the transaction's byte size. This estimation is used when building the transaction. As a side effect, your wallet must own at least one coin of the base asset, regardless of the amount.
 

apps/docs/src/guide/transactions/adding-policies.md

@@ -18,6 +18,10 @@ The number of blocks that must pass before the transaction can be included in a
 
 The maximum amount you're willing to pay for the transaction using the base asset.
 
+### Expiration
+
+Block number after which the transaction can no longer be included in the blockchain.
+
 ## Setting Transaction Policies
 
 The following snippet shows which transaction parameters correspond to which policies:

apps/docs/src/guide/transactions/snippets/transaction-parameters.ts

@@ -13,7 +13,7 @@ const deploy = await CounterFactory.deploy(wallet);
 
 const { contract } = await deploy.waitForResult();
 
-// #region transaction-parameters-6
+// #region transaction-parameters-7
 const txParams: TxParams = {
   // #region transaction-parameters-1
   gasLimit: bn(70935),
@@ -30,17 +30,20 @@ const txParams: TxParams = {
   // #region transaction-parameters-5
   witnessLimit: bn(5000),
   // #endregion transaction-parameters-5
+  // #region transaction-parameters-6
+  expiration: 200,
+  // #endregion transaction-parameters-6
 };
-// #endregion transaction-parameters-6
+// #endregion transaction-parameters-7
 
-// #region transaction-parameters-7
+// #region transaction-parameters-8
 const transactionRequest = new ScriptTransactionRequest({
   script: ScriptSum.bytecode,
   gasLimit: 100,
 });
-// #endregion transaction-parameters-7
+// #endregion transaction-parameters-8
 
-// #region transaction-parameters-8
+// #region transaction-parameters-9
 const { waitForResult } = await contract.functions
   .increment_count(15) //
   .txParams(txParams)
@@ -55,5 +58,5 @@ console.log('Transaction request', transactionRequest);
 console.log('Transaction status', isStatusSuccess);
 console.log('Transaction value', value);
 
-// #endregion transaction-parameters-8
+// #endregion transaction-parameters-9
 // #endregion full

apps/docs/src/guide/transactions/snippets/transaction-policies/policies-from-response.ts

@@ -18,6 +18,7 @@ const transactionRequest = new ScriptTransactionRequest({
   tip: bn(10),
   witnessLimit: 900,
   maxFee: bn(2000),
+  expiration: 200,
 });
 
 // Set the script main function arguments

apps/docs/src/guide/transactions/snippets/transaction-policies/setting-policies.ts

@@ -6,6 +6,7 @@ const transactionRequest = new ScriptTransactionRequest({
   witnessLimit: bn(1), // Sets the witness limit policy
   maturity: 1, // Sets the maturity policy
   maxFee: bn(1), // Sets the max fee policy
+  expiration: 200, // Sets the block after which the transaction cannot be included.
 });
 // #endregion transaction-policies-1
 

internal/fuel-core/VERSION

@@ -1 +1 @@
-0.40.4
+0.41.7

packages/account/codegen.json

@@ -27,7 +27,9 @@
           "U16": "string",
           "U32": "string",
           "U64": "string",
-          "UtxoId": "string"
+          "U128": "string",
+          "UtxoId": "string",
+          "SubId": "string"
         },
         "useTypeImports": true,
         "dedupeOperationSuffix": true,

packages/account/package.json

@@ -58,7 +58,7 @@
     "@fuel-ts/transactions": "workspace:*",
     "@fuel-ts/utils": "workspace:*",
     "@fuel-ts/versions": "workspace:*",
-    "@fuels/vm-asm": "0.58.2",
+    "@fuels/vm-asm": "0.59.1",
     "@noble/curves": "1.8.1",
     "events": "3.3.0",
     "graphql": "16.10.0",

packages/account/src/account.test.ts

@@ -599,8 +599,8 @@ describe('Account', () => {
     await expectToThrowFuelError(
       () => user.getResourcesToSpend([[1, ASSET_A, 500_000]], { utxos: [assetAUTXO.id] }),
       new FuelError(
-        ErrorCode.NOT_ENOUGH_FUNDS,
-        `The account(s) sending the transaction don't have enough funds to cover the transaction.`
+        ErrorCode.INSUFFICIENT_FUNDS_OR_MAX_COINS,
+        `Insufficient funds or too many small value coins. Consider combining UTXOs.`
       )
     );
   });
@@ -977,9 +977,8 @@ describe('Account', () => {
     request.addCoinOutput(wallet.address, 30_000, await provider.getBaseAssetId());
 
     await expectToThrowFuelError(() => request.estimateAndFund(wallet), {
-      code: ErrorCode.MAX_COINS_REACHED,
-      message:
-        'The account retrieving coins has exceeded the maximum number of coins per asset. Please consider combining your coins into a single UTXO.',
+      code: ErrorCode.INSUFFICIENT_FUNDS_OR_MAX_COINS,
+      message: 'Insufficient funds or too many small value coins. Consider combining UTXOs.',
     });
   });
 

packages/account/src/account.ts

@@ -53,7 +53,7 @@ import { assembleTransferToContractScript } from './utils/formatTransferToContra
 
 export type TxParamsType = Pick<
   ScriptTransactionRequestLike,
-  'gasLimit' | 'tip' | 'maturity' | 'maxFee' | 'witnessLimit'
+  'gasLimit' | 'tip' | 'maturity' | 'maxFee' | 'witnessLimit' | 'expiration'
 >;
 
 export type TransferParams = {
@@ -308,7 +308,7 @@ export class Account extends AbstractAccount implements WithAddress {
     // If the transaction still needs to be funded after the maximum number of attempts
     if (needsToBeFunded) {
       throw new FuelError(
-        ErrorCode.NOT_ENOUGH_FUNDS,
+        ErrorCode.INSUFFICIENT_FUNDS_OR_MAX_COINS,
         `The account ${this.address} does not have enough base asset funds to cover the transaction execution.`
       );
     }