docs: improve contract muticall page (#3218)

apps/docs-snippets/src/guide/contracts/multicalls.test.ts

@@ -1,4 +1,4 @@
-import { BN } from 'fuels';
+import { bn, BN } from 'fuels';
 import { launchTestNode } from 'fuels/test-utils';
 
 import { CounterFactory, EchoValuesFactory, ReturnContextFactory } from '../../../test/typegen';
@@ -20,8 +20,8 @@ describe('Multicalls', () => {
     const {
       contracts: [counterContract],
     } = launched;
-    // #region multicall-1
 
+    // #region multicall-1
     const { waitForResult } = await counterContract
       .multiCall([
         counterContract.functions.get_count(),
@@ -32,12 +32,9 @@ describe('Multicalls', () => {
 
     const { value: results } = await waitForResult();
 
-    const initialValue = new BN(results[0]).toNumber();
-    const incrementedValue1 = new BN(results[1]).toNumber();
-    const incrementedValue2 = new BN(results[2]).toNumber();
-
-    expect(incrementedValue1).toEqual(initialValue + 2);
-    expect(incrementedValue2).toEqual(incrementedValue1 + 4);
+    expect(results[0].toNumber()).toBe(0);
+    expect(results[1].toNumber()).toBe(2);
+    expect(results[2].toNumber()).toBe(6);
     // #endregion multicall-1
   });
 
@@ -56,23 +53,21 @@ describe('Multicalls', () => {
     const {
       contracts: [echoContract, counterContract],
     } = launched;
-    // #region multicall-2
 
-    const chain = echoContract.multiCall([
-      echoContract.functions.echo_u8(17),
-      counterContract.functions.get_count(),
-      counterContract.functions.increment_counter(5),
-    ]);
+    // #region multicall-2
+    const { waitForResult } = await echoContract
+      .multiCall([
+        echoContract.functions.echo_u8(17),
+        counterContract.functions.get_count(),
+        counterContract.functions.increment_counter(5),
+      ])
+      .call();
 
-    const { waitForResult } = await chain.call();
     const { value: results } = await waitForResult();
 
-    const echoedValue = results[0];
-    const initialCounterValue = new BN(results[1]).toNumber();
-    const counterIncrementedValue = new BN(results[2]).toNumber();
-
-    expect(echoedValue).toEqual(17);
-    expect(counterIncrementedValue).toEqual(initialCounterValue + 5);
+    expect(results[0]).toEqual(17);
+    expect(results[1].toNumber()).toBe(0);
+    expect(results[2].toNumber()).toBe(5);
     // #endregion multicall-2
   });
 
@@ -92,8 +87,8 @@ describe('Multicalls', () => {
       contracts: [contextContract, echoContract],
       provider,
     } = launched;
-    // #region multicall-3
 
+    // #region multicall-3
     const { waitForResult } = await contextContract
       .multiCall([
         echoContract.functions.echo_u8(10),
@@ -112,4 +107,35 @@ describe('Multicalls', () => {
     expect(fowardedValue).toEqual(100);
     // #endregion multicall-3
   });
+
+  it('should successfully submit multiple read-only calls', async () => {
+    using launched = await launchTestNode({
+      contractsConfigs: [
+        {
+          factory: CounterFactory,
+        },
+        {
+          factory: EchoValuesFactory,
+        },
+      ],
+    });
+
+    const {
+      contracts: [counterContract, echoValuesContract],
+    } = launched;
+
+    // #region multicall-4
+    const { value: results } = await counterContract
+      .multiCall([
+        counterContract.functions.get_count(),
+        echoValuesContract.functions.echo_u8(10),
+        echoValuesContract.functions.echo_str('Fuel'),
+      ])
+      .get();
+
+    expect(results[0].toNumber()).toBe(bn(0).toNumber());
+    expect(results[1]).toBe(10);
+    expect(results[2]).toBe('Fuel');
+    // #endregion multicall-4
+  });
 });

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

@@ -7,7 +7,7 @@ You can execute multiple contract calls in a single transaction, either to the s
 
 <!-- calls:example:end -->
 
-## Same Contract multi calls
+## Same Contract Multi Calls
 
 <!-- This section should explain how make multiple calls with the SDK -->
 <!-- multicall:example:start -->
@@ -18,7 +18,7 @@ Use the `multiCall` method to call multiple functions on the same contract in a
 
 <<< @/../../docs-snippets/src/guide/contracts/multicalls.test.ts#multicall-1{ts:line-numbers}
 
-## Different contracts multi calls
+## Different Contracts Multi Calls
 
 The `multiCall` method also allows you to execute multiple contract calls to distinct contracts within a single transaction:
 
@@ -28,6 +28,10 @@ You can also chain supported contract call methods, like `callParams`, for each
 
 <<< @/../../docs-snippets/src/guide/contracts/multicalls.test.ts#multicall-3{ts:line-numbers}
 
-When chaining contract call methods within `multiCall`, avoid executing the contract functions themselves, such as `.call`, `.get`, and `.simulate`.
+When using `multiCall`, the contract calls are queued and executed only after invoking one of the following methods: `.get`, `.simulate`, or `.call`.
 
-The `multiCall` method creates a scope for all contract calls, which will only be executed after invoking the `.call` method.
+## Using `multiCall` for Read-Only Contract Calls
+
+When you need to read data from multiple contracts, the `multiCall` method can perform multiple [read-only](./methods.md#get) calls in a single transaction. This minimizes the number of requests sent to the network and consolidates data retrieval, making your dApp interactions more efficient.
+
+<<< @/../../docs-snippets/src/guide/contracts/multicalls.test.ts#multicall-4{ts:line-numbers}