feat: implement get method on BaseInvocationScope

apps/docs-snippets/src/guide/contracts/read-only-calls.test.ts

@@ -0,0 +1,48 @@
+import type { Provider } from 'fuels';
+import { Wallet, Contract } from 'fuels';
+
+import { DocSnippetProjectsEnum } from '../../../test/fixtures/forc-projects';
+import { createAndDeployContractFromProject } from '../../utils';
+
+/**
+ * @group node
+ */
+describe(__filename, () => {
+  let contract: Contract;
+  let provider: Provider;
+  beforeAll(async () => {
+    contract = await createAndDeployContractFromProject(DocSnippetProjectsEnum.ECHO_VALUES);
+    provider = contract.provider;
+  });
+
+  it('should successfully execute a read only call with get', async () => {
+    // #region read-only-calls-1
+    const { value } = await contract.functions.echo_u8(15).get();
+    // #endregion read-only-calls-1
+    expect(value).toEqual(15);
+  });
+
+  it('should successfully execute a contract call using an unfunded wallet', async () => {
+    // #region read-only-calls-2
+    const unfundedWallet = Wallet.generate({ provider });
+
+    contract.account = unfundedWallet;
+
+    const { value } = await contract.functions.echo_u8(15).get();
+    // #endregion read-only-calls-2
+    expect(value).toEqual(15);
+  });
+
+  it('should successfully execute a contract call without a wallet', async () => {
+    const abi = contract.interface;
+    const contractId = contract.id;
+
+    // #region read-only-calls-3
+    // contract instantiated without an account instance
+    const myContract = new Contract(contractId, abi, provider);
+
+    const { value } = await myContract.functions.echo_u8(15).get();
+    // #endregion read-only-calls-3
+    expect(value).toEqual(15);
+  });
+});

apps/docs/.vitepress/config.ts

@@ -267,6 +267,10 @@ export default defineConfig({
                 text: 'Managing Deployed Contracts',
                 link: '/guide/contracts/managing-deployed-contracts',
               },
+              {
+                text: 'Read Only Calls',
+                link: '/guide/contracts/read-only-calls',
+              },
               {
                 text: 'Simulate Transactions',
                 link: '/guide/contracts/simulate-transactions',

apps/docs/src/guide/contracts/read-only-calls.md

@@ -0,0 +1,23 @@
+# Read Only Calls
+
+When interacting with a contract, you may need to validate if a contract function behaves as intended without spending any real resources.
+
+The `get()` method can be used for this purpose.
+
+## Read-only Calls Using `get()`
+
+The `get` method allows you to dry-run a contract call to validate its intended behavior.
+
+It can be used to read a contract state or retrieve a returned value from a contract function without executing a real transaction.
+
+Here's an example of using the `get` method:
+
+<<< @/../../docs-snippets/src/guide/contracts/read-only-calls.test.ts#read-only-calls-1{ts:line-numbers}
+
+It can be used with a wallet that has no funds available:
+
+<<< @/../../docs-snippets/src/guide/contracts/read-only-calls.test.ts#read-only-calls-2{ts:line-numbers}
+
+The `get` method can also be used without a wallet to perform read-only calls.
+
+<<< @/../../docs-snippets/src/guide/contracts/read-only-calls.test.ts#read-only-calls-3{ts:line-numbers}

packages/fuel-gauge/src/contract.test.ts

@@ -1147,4 +1147,32 @@ describe('Contract', () => {
       new FuelError(ErrorCode.INVALID_TRANSFER_AMOUNT, 'Transfer amount must be a positive number.')
     );
   });
+
+  it('should ensure "get" can be used to execute a contract call without a wallet', async () => {
+    const contract = await setupContract();
+
+    // contract with no account set
+    const contractToCall = new Contract(contract.id, contract.interface, contract.provider);
+
+    const { value } = await contractToCall.functions.sum(10, 5).get();
+
+    expect(contractToCall.account).toBeNull();
+    expect(value.toNumber()).toBe(15);
+  });
+
+  it('should ensure "get" can be used to execute a contract call with an unfunded wallet', async () => {
+    const contract = await setupContract();
+
+    const unfundedWallet = Wallet.generate({ provider: contract.provider });
+
+    contract.account = unfundedWallet;
+
+    const balance = await contract.account.getBalance();
+    expect(balance.toNumber()).toBe(0);
+
+    const { value } = await contract.functions.sum(10, 20).get();
+
+    expect(contract.account).toBeDefined();
+    expect(value.toNumber()).toBe(30);
+  });
 });

packages/program/src/functions/base-invocation-scope.ts

@@ -1,7 +1,7 @@
 /* eslint-disable no-param-reassign */
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import type { InputValue } from '@fuel-ts/abi-coder';
-import type { BaseWalletUnlocked, Provider, CoinQuantity } from '@fuel-ts/account';
+import type { BaseWalletUnlocked, Provider, CoinQuantity, CallResult } from '@fuel-ts/account';
 import { ScriptTransactionRequest } from '@fuel-ts/account';
 import { Address } from '@fuel-ts/address';
 import { ErrorCode, FuelError } from '@fuel-ts/errors';
@@ -410,6 +410,20 @@ export class BaseInvocationScope<TReturn = any> {
     return InvocationCallResult.build<T>(this.functionInvocationScopes, response, this.isMultiCall);
   }
 
+  async get<T = TReturn>(): Promise<InvocationCallResult<T>> {
+    const { receipts } = await this.getTransactionCost();
+
+    const callResult: CallResult = {
+      receipts,
+    };
+
+    return InvocationCallResult.build<T>(
+      this.functionInvocationScopes,
+      callResult,
+      this.isMultiCall
+    );
+  }
+
   getProvider(): Provider {
     const provider = <Provider>this.program.provider;