feat!: add main arg support to Scripts

.changeset/rotten-dogs-pump.md

@@ -0,0 +1,9 @@
+---
+"@fuel-ts/abi-coder": minor
+"@fuel-ts/contract": minor
+"fuels": minor
+"@fuel-ts/providers": minor
+"@fuel-ts/script": minor
+---
+
+Add support for main args in scripts

docs/_guide/scripts/calling-a-script.md

@@ -4,4 +4,16 @@
 
 We will use the `script` instance created in the [previous section](./instantiating-a-script.md) to call the script.
 
-[@code:typescript](./packages/script/src/script.test.ts#typedoc:script-call)
+[@code:typescript](./packages/script/src/callScript.ts#typedoc:script-call)
+
+You can access this low-level helper using `import { callScript } from 'fuels';`.
+
+## Calling a script with a `main` function that takes arguments
+
+Suppose your Sway script `main` function is written using the arguments passed to the `main` function like so:
+
+[@code:rust](./packages/fuel-gauge/test-projects/script-main-args/src/main.sw#typedoc:script-with-main-args)
+
+You can still hand code out a solution wrapper using `callScript` utility to call your script with data. However, if you prefer to use the ABI generated from your script, you can use the `ScriptFactory` helper:
+
+[@code:typescript](./packages/fuel-gauge/src/script-main-args.test.ts#typedoc:script-call-factory)

packages/abi-coder/src/abi-coder.ts

@@ -169,6 +169,7 @@ export default class AbiCoder {
               types: types.length,
               nonEmptyTypes: nonEmptyTypes.length,
               values: bytes.length,
+              newOffset,
             },
             value: {
               types,

packages/abi-coder/src/interface.ts

@@ -129,7 +129,8 @@ export default class Interface {
   encodeFunctionData(
     functionFragment: FunctionFragment | string,
     values: Array<InputValue>,
-    offset = 0
+    offset = 0,
+    isMainArgs = false
   ): Uint8Array {
     const fragment =
       typeof functionFragment === 'string' ? this.getFunction(functionFragment) : functionFragment;
@@ -145,8 +146,12 @@ export default class Interface {
       return selector;
     }
 
-    const isRef = inputs.length > 1 || isReferenceType(inputs[0].type);
     const args = this.abiCoder.encode(inputs, values, offset);
+    if (isMainArgs) {
+      return args;
+    }
+
+    const isRef = inputs.length > 1 || isReferenceType(inputs[0].type);
     return concat([selector, new BooleanCoder().encode(isRef), args]);
   }
 

packages/contract/src/contracts/functions/invocation-results.ts

@@ -1,6 +1,5 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 /* eslint-disable max-classes-per-file */
-import { U64Coder } from '@fuel-ts/abi-coder';
 import type { BN } from '@fuel-ts/math';
 import { bn } from '@fuel-ts/math';
 import type {
@@ -9,6 +8,7 @@ import type {
   TransactionResponse,
   TransactionResultReceipt,
 } from '@fuel-ts/providers';
+import { getDecodedLogs } from '@fuel-ts/providers';
 import type { ReceiptScriptResult } from '@fuel-ts/transactions';
 import { ReceiptType } from '@fuel-ts/transactions';
 
@@ -57,19 +57,7 @@ export class InvocationResult<T = any> {
 
     const { contract } = this.functionScopes[0].getCallConfig();
 
-    return receipts.reduce((logs, r) => {
-      if (r.type === ReceiptType.LogData) {
-        return logs.concat(...contract.interface.decodeLog(r.data, r.val1.toNumber(), r.id));
-      }
-
-      if (r.type === ReceiptType.Log) {
-        return logs.concat(
-          ...contract.interface.decodeLog(new U64Coder().encode(r.val0), r.val1.toNumber(), r.id)
-        );
-      }
-
-      return logs;
-    }, []);
+    return getDecodedLogs(receipts, contract.interface);
   }
 }
 

packages/fuel-gauge/src/script-main-args.test.ts

@@ -0,0 +1,82 @@
+import { generateTestWallet } from '@fuel-ts/wallet/test-utils';
+import { readFileSync } from 'fs';
+import type { BigNumberish } from 'fuels';
+import { NativeAssetId, Provider, bn, ScriptFactory } from 'fuels';
+import { join } from 'path';
+
+import scriptAbi from '../test-projects/script-main-args/out/debug/script-main-args-abi.json';
+
+import { getScript } from './utils';
+
+const scriptBin = readFileSync(
+  join(__dirname, '../test-projects/script-main-args/out/debug/script-main-args.bin')
+);
+
+const setup = async () => {
+  const provider = new Provider('http://127.0.0.1:4000/graphql');
+
+  // Create wallet
+  const wallet = await generateTestWallet(provider, [[5_000_000, NativeAssetId]]);
+
+  return wallet;
+};
+
+type Baz = {
+  x: number;
+};
+
+describe('Script Coverage', () => {
+  it('can call script and use main arguments', async () => {
+    const wallet = await setup();
+    // #region typedoc:script-call-factory
+    const scriptInstance = new ScriptFactory<BigNumberish>(scriptBin, scriptAbi).script;
+    const foo = 33;
+
+    const { value, logs } = await wallet.callScript<BigNumberish[], BigNumberish>(scriptInstance, [
+      foo,
+    ]);
+    // #endregion
+
+    expect(value.toString()).toEqual(bn(foo).toString());
+    expect(logs).toEqual(['u8 foo', 33]);
+  });
+
+  it('can call script and use main arguments [two args, read logs]', async () => {
+    const wallet = await setup();
+    const scriptInstance = getScript<Baz>('script-main-two-args').script;
+    const foo = 33;
+    const bar: Baz = {
+      x: 12,
+    };
+
+    const { value, logs } = await wallet.callScript(scriptInstance, [foo, bar]);
+
+    expect(value.toString()).toEqual(bn(foo + bar.x).toString());
+    expect(logs).toEqual(['u8 foo', 33, 'u8 bar', 12, 'u8 bar', 12]);
+  });
+
+  it('can call script and use main arguments [two args, struct return]', async () => {
+    const wallet = await setup();
+    const scriptInstance = getScript<Baz>('script-main-return-struct').script;
+    const foo = 1;
+    const bar: Baz = {
+      x: 2,
+    };
+
+    const { value } = await wallet.callScript(scriptInstance, [foo, bar]);
+
+    expect(value).toEqual({
+      x: 3,
+    });
+  });
+
+  it('can call script and use main arguments [tx params]', async () => {
+    const wallet = await setup();
+    const scriptInstance = new ScriptFactory<BigNumberish>(scriptBin, scriptAbi).script;
+    const foo = 42;
+
+    expect(async () => {
+      await wallet.callScript(scriptInstance, [foo], { gasLimit: 1, gasPrice: 400 });
+    }).rejects.toThrow(/gasLimit\(1\) is lower than the required/);
+  });
+});

packages/fuel-gauge/src/utils.ts

@@ -1,7 +1,7 @@
 import { generateTestWallet } from '@fuel-ts/wallet/test-utils';
 import { readFileSync } from 'fs';
 import type { Interface, JsonAbi, Contract, BytesLike, WalletUnlocked } from 'fuels';
-import { NativeAssetId, Provider, ContractFactory } from 'fuels';
+import { ScriptFactory, NativeAssetId, Provider, ContractFactory } from 'fuels';
 import { join } from 'path';
 
 let contractInstance: Contract;
@@ -44,15 +44,25 @@ export const createSetupConfig =
       ...config,
     });
 
-const getFullPath = (
-  contractName: string,
-  next: (fullPath: string) => (config?: Partial<SetupConfig>) => Promise<Contract>
-) => next(join(__dirname, `../test-projects/${contractName}/out/debug/${contractName}`));
+const getFullPath = (contractName: string, next: (fullPath: string) => any) =>
+  next(join(__dirname, `../test-projects/${contractName}/out/debug/${contractName}`));
 
-export const getSetupContract = (contractName: string) =>
+export const getSetupContract = (
+  contractName: string
+): ((config?: Partial<SetupConfig>) => Promise<Contract>) =>
   getFullPath(contractName, (fullPath: string) =>
     createSetupConfig({
       contractBytecode: readFileSync(`${fullPath}.bin`),
       abi: JSON.parse(readFileSync(`${fullPath}-abi.json`, 'utf8')),
     })
   );
+
+export const getScript = <T>(scriptName: string): ScriptFactory<T> =>
+  getFullPath(
+    scriptName,
+    (fullPath: string) =>
+      new ScriptFactory(
+        readFileSync(`${fullPath}.bin`),
+        JSON.parse(readFileSync(`${fullPath}-abi.json`, 'utf8'))
+      )
+  );

packages/fuel-gauge/test-projects/script-main-args/Forc.toml

@@ -0,0 +1,5 @@
+[project]
+license = "Apache-2.0"
+name = "script-main-args"
+
+[dependencies]

packages/fuel-gauge/test-projects/script-main-args/src/main.sw

@@ -0,0 +1,11 @@
+// #region typedoc:script-with-main-args
+script;
+
+use std::logging::log;
+
+fn main(foo: u8) -> u8 {
+    log("u8 foo");
+    log(foo);
+    foo
+}
+// #endregion

packages/fuel-gauge/test-projects/script-main-return-struct/Forc.toml

@@ -0,0 +1,5 @@
+[project]
+license = "Apache-2.0"
+name = "script-main-return-struct"
+
+[dependencies]

packages/fuel-gauge/test-projects/script-main-return-struct/src/main.sw

@@ -0,0 +1,11 @@
+script;
+
+struct Baz {
+    x: u8,
+}
+
+fn main(foo: u8, bar: Baz) -> Baz {
+    Baz {
+        x: bar.x + foo
+    }
+}

packages/fuel-gauge/test-projects/script-main-two-args/Forc.toml

@@ -0,0 +1,5 @@
+[project]
+license = "Apache-2.0"
+name = "script-main-two-args"
+
+[dependencies]

packages/fuel-gauge/test-projects/script-main-two-args/src/main.sw

@@ -0,0 +1,17 @@
+script;
+
+use std::logging::log;
+
+struct Baz {
+    x: u8,
+}
+
+fn main(foo: u8, bar: Baz) -> u8 {
+    log("u8 foo");
+    log(foo);
+    log("u8 bar");
+    log(bar.x);
+    log("u8 bar");
+    log(bar.x);
+    foo + bar.x
+}

packages/fuels/src/index.ts

@@ -12,4 +12,4 @@ export * from '@fuel-ts/providers';
 export * from '@fuel-ts/signer';
 export * from '@fuel-ts/transactions';
 export * from '@fuel-ts/wallet';
-export { ScriptResultDecoderError } from '@fuel-ts/script';
+export { ScriptResultDecoderError, Script, callScript, ScriptFactory } from '@fuel-ts/script';

packages/interfaces/src/index.ts

@@ -4,9 +4,10 @@ export type Bech32Address = `fuel${string}`;
 // #endregion
 export type B256Address = string;
 
-export abstract class AbstractScript<T> {
+export abstract class AbstractScript<TData, TResult = any> {
   abstract bytes: Uint8Array;
-  abstract encodeScriptData: (data: T) => Uint8Array;
+  abstract encodeScriptData: (data: TData) => Uint8Array;
+  abstract decodeCallResult: (callResult: { receipts: any }, logs?: Array<any>) => TResult;
 }
 
 // #region typedoc:AbstractAddress

packages/providers/src/provider.ts

@@ -190,6 +190,10 @@ export type BuildPredicateOptions = {
   fundTransaction?: boolean;
 } & Pick<TransactionRequestLike, 'gasLimit' | 'gasPrice' | 'maturity'>;
 
+export type BuildScriptOptions = {
+  fundTransaction?: boolean;
+} & Pick<TransactionRequestLike, 'gasLimit' | 'gasPrice' | 'maturity'>;
+
 /**
  * Provider Call transaction params
  */

packages/providers/src/transaction-request/transaction-request.ts

@@ -59,6 +59,7 @@ export const returnZeroScript: AbstractScript<void> = {
   // TODO: Don't use hardcoded scripts: https://github.com/FuelLabs/fuels-ts/issues/281
   bytes: arrayify('0x24000000'),
   encodeScriptData: () => new Uint8Array(0),
+  decodeCallResult: () => null,
 };
 
 export const withdrawScript: AbstractScript<void> = {
@@ -75,6 +76,7 @@ export const withdrawScript: AbstractScript<void> = {
   // TODO: Don't use hardcoded scripts: https://github.com/FuelLabs/fuels-ts/issues/281
   bytes: arrayify('0x5040C0105D44C0064C40001124000000'),
   encodeScriptData: () => new Uint8Array(0),
+  decodeCallResult: () => null,
 };
 
 interface BaseTransactionRequestLike {

packages/providers/src/transaction-response/getDecodedLogs.ts

@@ -0,0 +1,24 @@
+import type { Interface } from '@fuel-ts/abi-coder';
+import { U64Coder } from '@fuel-ts/abi-coder';
+import { ReceiptType } from '@fuel-ts/transactions';
+
+import type { TransactionResultReceipt } from './transaction-response';
+
+export default function getDecodedLogs<T = any>(
+  receipts: Array<TransactionResultReceipt>,
+  abiInterface: Interface
+): T[] {
+  return receipts.reduce((logs, r) => {
+    if (r.type === ReceiptType.LogData) {
+      return logs.concat(...abiInterface.decodeLog(r.data, r.val1.toNumber(), r.id));
+    }
+
+    if (r.type === ReceiptType.Log) {
+      return logs.concat(
+        ...abiInterface.decodeLog(new U64Coder().encode(r.val0), r.val1.toNumber(), r.id)
+      );
+    }
+
+    return logs;
+  }, []);
+}

packages/providers/src/transaction-response/index.ts

@@ -1 +1,2 @@
 export * from './transaction-response';
+export { default as getDecodedLogs } from './getDecodedLogs';

packages/script/package.json

@@ -30,12 +30,14 @@
   },
   "dependencies": {
     "@ethersproject/bytes": "^5.7.0",
+    "@ethersproject/logger": "^5.7.0",
     "@fuel-ts/abi-coder": "workspace:*",
     "@fuel-ts/constants": "workspace:*",
     "@fuel-ts/math": "workspace:*",
     "@fuel-ts/providers": "workspace:*",
     "@fuel-ts/wallet": "workspace:*",
-    "@fuel-ts/transactions": "workspace:*"
+    "@fuel-ts/transactions": "workspace:*",
+    "@fuel-ts/versions": "workspace:*"
   },
   "devDependencies": {
     "forc-bin": "workspace:*"