feat: support TX customization at BaseInvocationScope (#3875)

Author: Torres-ssf

.changeset/huge-stars-attend.md

@@ -0,0 +1,6 @@
+---
+"@fuel-ts/account": patch
+"@fuel-ts/program": patch
+---
+
+feat: support TX customization at BaseInvocationScope

apps/docs/.vitepress/config.ts

@@ -224,10 +224,6 @@ export default defineConfig({
                 text: 'Contract Balance',
                 link: '/guide/contracts/contract-balance',
               },
-              {
-                text: 'Cost Estimation',
-                link: '/guide/contracts/cost-estimation',
-              },
               {
                 text: 'Dependency Estimation',
                 link: '/guide/contracts/dependency-estimation',
@@ -268,6 +264,10 @@ export default defineConfig({
                 text: 'Configurable Constants',
                 link: '/guide/contracts/configurable-constants',
               },
+              {
+                text: 'Custom Contract Calls',
+                link: '/guide/contracts/custom-contract-calls',
+              },
               {
                 text: 'Minted Token Asset ID',
                 link: '/guide/contracts/minted-token-asset-id',

apps/docs/src/guide/contracts/call-parameters.md

@@ -20,7 +20,9 @@ The contract in use in this section has the following implementation:
 <!-- This section should explain the `forward` param -->
 <!-- forward:example:start -->
 
-The `forward` parameter allows the sending of a specific amount of coins to a contract when a function is called. This is useful when a contract function requires coins for its execution, such as paying fees or transferring funds. The forward parameter helps you control the resources allocated to the contract call and offers protection against potentially costly operations.
+The `forward` parameter allows the sending of a specific amount of coins to a contract when a function is called. This is useful when a contract function requires coins for its execution, such as transferring funds to another account or contract.
+
+The forward parameter helps you control the resources allocated to the contract call and offers protection against potentially costly operations.
 
 <!-- forward:example:end -->
 

apps/docs/src/guide/contracts/cost-estimation.md

@@ -0,0 +1,29 @@
+# Custom Contract Call
+
+In certain scenarios, your use case may require more control over how contract calls are prepared and submitted.
+
+For instance, imagine a liquidity pool contract where users can deposit a specific asset to receive some form of benefit. To enhance the experience and make it more attractive, one could use a predicate to cover the transaction fees. This way, users only need to provide the asset they wish to deposit without worrying about the fees.
+
+There are two main ways to customize a contract call:
+
+## Approach 1: Customize `assembleTx` Parameters
+
+In most cases, this isn’t necessary. However, if you need precise control, you can specify the parameters passed to `assembleTx`, which is used internally to estimate and fund the transaction.
+
+Here’s how it works:
+
+<<< @./snippets/custom-contract-calls/assemble-tx-parameters.ts#assemble-tx-parameters-1{ts:line-numbers}
+
+## Approach 2: Manually Call `assembleTx`
+
+You can also retrieve the transaction request from the invocation scope and manually call `assembleTx` on it. Just like the approach 1 this gives you full control over how the transaction is assembled and funded.
+
+<<< @./snippets/custom-contract-calls/call.ts#custom-contract-call-1{ts:line-numbers}
+
+There are 2 details here that there are essential in this flow
+
+1. `fromRequest`:
+   This sets the transaction request extracted from the invocation scope. It ensures that any manual changes you’ve applied persist and are used when the transaction is executed.
+
+1. `{ skipAssembleTx: true }` option:
+   It tells the SDK to skip the automatic `assembleTx` step during the `.call()` execution, since we’ve already manually assembled and funded the transaction using `provider.assembleTx()`. Skipping this step prevents the SDK from re-estimating the transaction and ensures the custom logic remains intact, such as using a predicate as the fee payer.

apps/docs/src/guide/contracts/custom-contract-calls.md

@@ -11,11 +11,12 @@ const { contract } = await deploy.waitForResult();
 
 // #region forward
 const amountToForward = 10;
+const baseAssetId = await provider.getBaseAssetId();
 
 const { waitForResult } = await contract.functions
   .return_context_amount()
   .callParams({
-    forward: [amountToForward, await provider.getBaseAssetId()],
+    forward: [amountToForward, baseAssetId],
   })
   .call();
 

apps/docs/src/guide/contracts/snippets/call-parameters/forward.ts

@@ -0,0 +1,57 @@
+import { Provider, Wallet } from 'fuels';
+import { TestAssetId } from 'fuels/test-utils';
+
+import { LOCAL_NETWORK_URL, WALLET_PVT_KEY } from '../../../../env';
+import {
+  LiquidityPool,
+  LiquidityPoolFactory,
+  ReturnTruePredicate,
+} from '../../../../typegend';
+
+const provider = new Provider(LOCAL_NETWORK_URL);
+const wallet = Wallet.fromPrivateKey(WALLET_PVT_KEY, provider);
+const predicate = new ReturnTruePredicate({ provider });
+
+const configurableConstants = {
+  TOKEN: { bits: TestAssetId.A.value },
+};
+
+const deploy = await LiquidityPoolFactory.deploy(wallet, {
+  configurableConstants,
+});
+
+const { contract } = await deploy.waitForResult();
+const contractId = contract.id.toB256();
+
+const res = await wallet.transfer(predicate.address, 500_000);
+await res.waitForResult();
+
+// #region assemble-tx-parameters-1
+// Create a new contract instance using the contract id
+const liquidityPoolContract = new LiquidityPool(contractId, wallet);
+
+// Execute the contract call manually specifying the assembleTx parameters
+const { waitForResult } = await liquidityPoolContract.functions
+  .deposit({ bits: wallet.address.toB256() })
+  .callParams({
+    forward: [1000, TestAssetId.A.value],
+  })
+  .assembleTxParams({
+    feePayerAccount: predicate, // Using predicate as fee payer
+    accountCoinQuantities: [
+      {
+        amount: 1000,
+        assetId: TestAssetId.A.value,
+        account: wallet,
+        changeOutputAccount: wallet,
+      },
+    ],
+  })
+  .call();
+
+const {
+  transactionResult: { isStatusSuccess },
+} = await waitForResult();
+
+// #endregion assemble-tx-parameters-1
+console.log('isStatusSuccess', isStatusSuccess);

apps/docs/src/guide/contracts/snippets/cost-estimation.ts

@@ -0,0 +1,69 @@
+import { Provider, Wallet } from 'fuels';
+import { TestAssetId } from 'fuels/test-utils';
+
+import { LOCAL_NETWORK_URL, WALLET_PVT_KEY } from '../../../../env';
+import {
+  LiquidityPool,
+  LiquidityPoolFactory,
+  ReturnTruePredicate,
+} from '../../../../typegend';
+
+const provider = new Provider(LOCAL_NETWORK_URL);
+const wallet = Wallet.fromPrivateKey(WALLET_PVT_KEY, provider);
+const predicate = new ReturnTruePredicate({ provider });
+
+const configurableConstants = {
+  TOKEN: { bits: TestAssetId.A.value },
+};
+
+const deploy = await LiquidityPoolFactory.deploy(wallet, {
+  configurableConstants,
+});
+
+const { contract } = await deploy.waitForResult();
+const contractId = contract.id.toB256();
+
+const res = await wallet.transfer(predicate.address, 500_000);
+await res.waitForResult();
+
+// #region custom-contract-call-1
+// Create a new contract instance using the contract id
+const liquidityPoolContract = new LiquidityPool(contractId, wallet);
+
+// Create invocation scope to call the deposit function
+const scope = liquidityPoolContract.functions
+  .deposit({ bits: wallet.address.toB256() })
+  .callParams({
+    forward: [1000, TestAssetId.A.value],
+  });
+
+// Get the transaction request
+const request = await scope.getTransactionRequest();
+
+/**
+ * Using "assembleTx" to estimate and fund the transaction.
+ */
+await provider.assembleTx({
+  request,
+  feePayerAccount: predicate, // Using predicate as fee payer
+  accountCoinQuantities: [
+    {
+      amount: 1000,
+      assetId: TestAssetId.A.value,
+      account: wallet,
+      changeOutputAccount: wallet,
+    },
+  ],
+});
+
+// Use the "call" method to submit the transaction, skipping the "assembleTx" step
+const response = await scope
+  .fromRequest(request)
+  .call({ skipAssembleTx: true });
+
+const {
+  transactionResult: { isStatusSuccess },
+} = await response.waitForResult();
+
+// #endregion custom-contract-call-1
+console.log('isStatusSuccess', isStatusSuccess);

apps/docs/src/guide/contracts/snippets/custom-contract-calls/assemble-tx-parameters.ts

@@ -18,9 +18,10 @@ const script = new ScriptSigning(signer);
 const witnessIndex = 0;
 
 // Creating the scope invocation to be used later
-const request = await script.functions
-  .main(signer.address.toB256(), witnessIndex)
-  .getTransactionRequest();
+const scope = script.functions.main(signer.address.toB256(), witnessIndex);
+
+// Creating the scope invocation to be used later
+const request = await scope.getTransactionRequest();
 
 // Signing the transaction request before estimation
 let signature = await signer.signTransaction(request);
@@ -44,10 +45,12 @@ signature = await signer.signTransaction(assembledRequest);
 assembledRequest.updateWitness(witnessIndex, signature);
 
 // Sending the transaction request
-const submit = await signer.sendTransaction(assembledRequest);
+const { waitForResult } = await scope.call({ skipAssembleTx: true });
 
 // Getting the result of the transaction
-const { isStatusSuccess } = await submit.waitForResult();
+const {
+  transactionResult: { isStatusSuccess },
+} = await waitForResult();
 // #endregion signature-script
 
 console.log('isStatusSuccess', isStatusSuccess);