feat: add simulate and estimate fee utility methods for outside execution (#1327)

PhilippeR26 · web-flow · commit 3668b01c4f63 · 2025-03-12T19:46:33.000+01:00
diff --git a/__tests__/account.outsideExecution.test.ts b/__tests__/account.outsideExecution.test.ts
@@ -10,16 +10,20 @@ import {
   constants,
   Contract,
   ec,
+  num,
   outsideExecution,
   OutsideExecutionVersion,
   Provider,
   src5,
   stark,
+  TransactionType,
   type Call,
   type Calldata,
+  type Invocations,
   type OutsideExecutionOptions,
   type OutsideTransaction,
   type TypedData,
+  type WeierstrassSignatureType,
 } from '../src';
 import { getSelectorFromName } from '../src/utils/hash';
 import { getDecimalString } from '../src/utils/num';
@@ -35,6 +39,25 @@ describe('Account and OutsideExecution', () => {
   // For ERC20 transfer outside call
   const recipientAccount = executorAccount;
   const ethContract = new Contract(contracts.Erc20OZ.sierra.abi, ethAddress, provider);
+  const call1: Call = {
+    contractAddress: ethAddress,
+    entrypoint: 'transfer',
+    calldata: {
+      recipient: recipientAccount.address,
+      amount: cairo.uint256(100),
+    },
+  };
+  const call2: Call = {
+    contractAddress: ethAddress,
+    entrypoint: 'transfer',
+    calldata: {
+      recipient: recipientAccount.address,
+      amount: cairo.uint256(200),
+    },
+  };
+  const now_seconds = Math.floor(Date.now() / 1000);
+  const hour_ago = (now_seconds - 3600).toString();
+  const hour_later = (now_seconds + 3600).toString();
 
   beforeAll(async () => {
     // Deploy the SNIP-9 signer account (ArgentX v 0.4.0, using SNIP-9 v2):
@@ -60,38 +83,22 @@ describe('Account and OutsideExecution', () => {
       entrypoint: 'transfer',
       calldata: {
         recipient: signerAccount.address,
-        amount: cairo.uint256(1000),
+        amount: cairo.uint256(1300),
       },
     };
     const { transaction_hash } = await executorAccount.execute(transferCall);
     await provider.waitForTransaction(transaction_hash);
   });
 
   test('getOutsideCall', async () => {
-    const call1: Call = {
-      contractAddress: '0x0123',
-      entrypoint: 'transfer',
-      calldata: {
-        recipient: '0xabcd',
-        amount: cairo.uint256(10),
-      },
-    };
     expect(outsideExecution.getOutsideCall(call1)).toEqual({
-      to: '0x0123',
+      to: ethAddress,
       selector: getSelectorFromName(call1.entrypoint),
-      calldata: ['43981', '10', '0'],
+      calldata: [num.hexToDecimalString(recipientAccount.address), '100', '0'],
     });
   });
 
   test('Build SNIP-9 v2 TypedData', async () => {
-    const call1: Call = {
-      contractAddress: '0x0123',
-      entrypoint: 'transfer',
-      calldata: {
-        recipient: '0xabcd',
-        amount: cairo.uint256(10),
-      },
-    };
     const callOptions: OutsideExecutionOptions = {
       caller: '0x1234',
       execute_after: 100,
@@ -115,9 +122,9 @@ describe('Account and OutsideExecution', () => {
         Caller: '0x1234',
         Calls: [
           {
-            Calldata: ['43981', '10', '0'],
-            Selector: '0x83afd3f4caedc6eebf44246fe54e38c95e3179a5ec9ea81740eca5b482d12e',
-            To: '0x0123',
+            Calldata: [num.hexToDecimalString(recipientAccount.address), '100', '0'],
+            Selector: getSelectorFromName(call1.entrypoint),
+            To: ethAddress,
           },
         ],
         'Execute After': 100,
@@ -216,6 +223,48 @@ describe('Account and OutsideExecution', () => {
     ]);
   });
 
+  test('buildExecuteFromOutsideCall', async () => {
+    const callOptions: OutsideExecutionOptions = {
+      caller: executorAccount.address,
+      execute_after: hour_ago,
+      execute_before: hour_later,
+    };
+    const outsideTransaction1: OutsideTransaction = await signerAccount.getOutsideTransaction(
+      callOptions,
+      [call1, call2]
+    );
+    const outsideExecutionCall: Call[] =
+      outsideExecution.buildExecuteFromOutsideCall(outsideTransaction1);
+    expect(outsideExecutionCall).toEqual([
+      {
+        calldata: [
+          num.hexToDecimalString(recipientAccount.address),
+          num.hexToDecimalString(outsideTransaction1.outsideExecution.nonce as string),
+          outsideTransaction1.outsideExecution.execute_after.toString(),
+          outsideTransaction1.outsideExecution.execute_before.toString(),
+          '2',
+          '2087021424722619777119509474943472645767659996348769578120564519014510906823',
+          '232670485425082704932579856502088130646006032362877466777181098476241604910',
+          '3',
+          num.hexToDecimalString(recipientAccount.address),
+          '100',
+          '0',
+          '2087021424722619777119509474943472645767659996348769578120564519014510906823',
+          '232670485425082704932579856502088130646006032362877466777181098476241604910',
+          '3',
+          num.hexToDecimalString(recipientAccount.address),
+          '200',
+          '0',
+          '2',
+          (outsideTransaction1.signature as WeierstrassSignatureType).r.toString(),
+          (outsideTransaction1.signature as WeierstrassSignatureType).s.toString(),
+        ],
+        contractAddress: signerAccount.address,
+        entrypoint: 'execute_from_outside_v2',
+      },
+    ]);
+  });
+
   test('Signer account should support SNIP-9 v2', async () => {
     expect(await signerAccount.getSnip9Version()).toBe(OutsideExecutionVersion.V2);
   });
@@ -227,9 +276,6 @@ describe('Account and OutsideExecution', () => {
   });
 
   test('should build and execute outside transactions', async () => {
-    const now_seconds = Math.floor(Date.now() / 1000);
-    const hour_ago = (now_seconds - 3600).toString();
-    const hour_later = (now_seconds + 3600).toString();
     const callOptions: OutsideExecutionOptions = {
       caller: executorAccount.address,
       execute_after: hour_ago,
@@ -239,22 +285,6 @@ describe('Account and OutsideExecution', () => {
       ...callOptions,
       caller: 'ANY_CALLER',
     };
-    const call1: Call = {
-      contractAddress: ethAddress,
-      entrypoint: 'transfer',
-      calldata: {
-        recipient: recipientAccount.address,
-        amount: cairo.uint256(100),
-      },
-    };
-    const call2: Call = {
-      contractAddress: ethAddress,
-      entrypoint: 'transfer',
-      calldata: {
-        recipient: recipientAccount.address,
-        amount: cairo.uint256(200),
-      },
-    };
     const call3: Call = {
       contractAddress: ethAddress,
       entrypoint: 'transfer',
@@ -328,6 +358,49 @@ describe('Account and OutsideExecution', () => {
     );
   });
 
+  test('estimate fees / simulate outsideExecution', async () => {
+    const callOptions: OutsideExecutionOptions = {
+      caller: executorAccount.address,
+      execute_after: hour_ago,
+      execute_before: hour_later,
+    };
+    const outsideTransaction: OutsideTransaction = await signerAccount.getOutsideTransaction(
+      callOptions,
+      [call1, call2]
+    );
+    const outsideExecutionCall: Call[] =
+      outsideExecution.buildExecuteFromOutsideCall(outsideTransaction);
+    const estimateFee = await executorAccount.estimateFee(outsideExecutionCall);
+    expect(Object.keys(estimateFee)).toEqual(
+      Object.keys({
+        overall_fee: 0,
+        gas_consumed: 0,
+        gas_price: 0,
+        unit: 0,
+        suggestedMaxFee: 0,
+        resourceBounds: 0,
+        data_gas_consumed: 0,
+        data_gas_price: 0,
+      })
+    );
+
+    const invocations: Invocations = [
+      {
+        type: TransactionType.INVOKE,
+        payload: outsideExecutionCall,
+      },
+    ];
+    const responseSimulate = await executorAccount.simulateTransaction(invocations);
+    expect(Object.keys(responseSimulate[0])).toEqual(
+      Object.keys({
+        transaction_trace: 0,
+        fee_estimation: 0,
+        suggestedMaxFee: 0,
+        resourceBounds: 0,
+      })
+    );
+  });
+
   test('ERC165 introspection', async () => {
     const isSNIP9 = await src5.supportsInterface(
       provider,
diff --git a/src/account/default.ts b/src/account/default.ts
@@ -59,7 +59,7 @@ import { calculateContractAddressFromHash } from '../utils/hash';
 import { isUndefined, isString } from '../utils/typed';
 import { isHex, toBigInt, toCairoBool, toHex } from '../utils/num';
 import {
-  buildExecuteFromOutsideCallData,
+  buildExecuteFromOutsideCall,
   getOutsideCall,
   getTypedData,
 } from '../utils/outsideExecution';
@@ -754,24 +754,7 @@ export class Account extends Provider implements AccountInterface {
     outsideTransaction: AllowArray<OutsideTransaction>,
     opts?: UniversalDetails
   ): Promise<InvokeFunctionResponse> {
-    const myOutsideTransactions = Array.isArray(outsideTransaction)
-      ? outsideTransaction
-      : [outsideTransaction];
-    const multiCall: Call[] = myOutsideTransactions.map((outsideTx: OutsideTransaction) => {
-      let entrypoint: string;
-      if (outsideTx.version === OutsideExecutionVersion.V1) {
-        entrypoint = 'execute_from_outside';
-      } else if (outsideTx.version === OutsideExecutionVersion.V2) {
-        entrypoint = 'execute_from_outside_v2';
-      } else {
-        throw new Error('Unsupported OutsideExecution version');
-      }
-      return {
-        contractAddress: toHex(outsideTx.signerAddress),
-        entrypoint,
-        calldata: buildExecuteFromOutsideCallData(outsideTx),
-      };
-    });
+    const multiCall = buildExecuteFromOutsideCall(outsideTransaction);
     return this.execute(multiCall, opts);
   }
 
diff --git a/src/utils/outsideExecution.ts b/src/utils/outsideExecution.ts
@@ -1,16 +1,17 @@
 import { CallData } from './calldata';
-import { Call, type BigNumberish, type Calldata } from '../types/lib';
+import { Call, type AllowArray, type BigNumberish, type Calldata } from '../types/lib';
 import {
   OutsideExecutionTypesV1,
   OutsideExecutionTypesV2,
-  type OutsideExecutionVersion,
+  OutsideExecutionVersion,
   type OutsideCall,
   type OutsideExecutionOptions,
   type OutsideTransaction,
   type TypedData,
 } from '../types';
 import { getSelectorFromName } from './hash/selector';
 import { formatSignature } from './stark';
+import { toHex } from './num';
 
 /**
  * Converts a Call object to an OutsideCall object that can be used for an Outside Execution.
@@ -136,7 +137,7 @@ export function getTypedData(
 }
 
 /**
- * Builds a CallData for the execute_from_outside() entrypoint.
+ * Builds a Calldata for the execute_from_outside() entrypoint.
  * @param {OutsideTransaction} outsideTransaction an object that contains all the data for a Outside Execution.
  * @returns {Calldata} The Calldata related to this Outside transaction
  * @example
@@ -167,3 +168,52 @@ export function buildExecuteFromOutsideCallData(outsideTransaction: OutsideTrans
     signature: formattedSignature,
   });
 }
+
+/**
+ * Builds a Call for execute(), estimateFee() and simulateTransaction() functions.
+ * @param {AllowArray<OutsideTransaction>} outsideTransaction an object that contains all the data for an Outside Execution.
+ * @returns {Call[]} The Call related to this Outside transaction
+ * @example
+ * ```typescript
+ * const outsideTransaction: OutsideTransaction = {
+ *     outsideExecution: {
+ *      caller: '0x64b48806902a367c8598f4f95c305e8c1a1acba5f082d294a43793113115691',
+ *      nonce: '0x7d0b4b4fce4b236e63d2bb5fc321935d52935cd3b268248cf9cf29c496bd0ae',
+ *      execute_after: 500, execute_before: 600,
+ *      calls: [{ to: '0x678', selector: '0x890', calldata: [12, 13] }],
+ *    },
+ *    signature: ['0x123', '0x456'],
+ *    signerAddress: '0x3b278ebae434f283f9340587a7f2dd4282658ac8e03cb9b0956db23a0a83657',
+ *    version: EOutsideExecutionVersion.V2,
+ *  };
+ *
+ *  const result: Call[] = outsideExecution.buildExecuteFromOutsideCall(outsideTransaction);
+ * // result = [{contractAddress: '0x64b48806902a367c8598f4f95c305e8c1a1acba5f082d294a43793113115691',
+ * //   entrypoint: 'execute_from_outside_v2',
+ * //   calldata: [ ... ],
+ * // }]
+ * ```
+ */
+export function buildExecuteFromOutsideCall(
+  outsideTransaction: AllowArray<OutsideTransaction>
+): Call[] {
+  const myOutsideTransactions = Array.isArray(outsideTransaction)
+    ? outsideTransaction
+    : [outsideTransaction];
+  const multiCall: Call[] = myOutsideTransactions.map((outsideTx: OutsideTransaction) => {
+    let entrypoint: string;
+    if (outsideTx.version === OutsideExecutionVersion.V1) {
+      entrypoint = 'execute_from_outside';
+    } else if (outsideTx.version === OutsideExecutionVersion.V2) {
+      entrypoint = 'execute_from_outside_v2';
+    } else {
+      throw new Error('Unsupported OutsideExecution version');
+    }
+    return {
+      contractAddress: toHex(outsideTx.signerAddress),
+      entrypoint,
+      calldata: buildExecuteFromOutsideCallData(outsideTx),
+    };
+  });
+  return multiCall;
+}
diff --git a/www/docs/guides/outsideExecution.md b/www/docs/guides/outsideExecution.md
@@ -269,3 +269,29 @@ The balances are finally :
 :::info
 The complete code of this example is available [here](https://github.com/PhilippeR26/starknet.js-workshop-typescript/blob/main/src/scripts/Starknet131/Starknet131-devnet/17.outsideExecuteLedger.ts).
 :::
+
+## Estimate fees for an outside execution:
+
+On executor side, if you want to estimate how many fees you will pay:
+
+```typescript
+const outsideExecutionCall: Call[] =
+  outsideExecution.buildExecuteFromOutsideCall(outsideTransaction1);
+const estimateFee = await executorAccount.estimateFee(outsideExecutionCall);
+```
+
+## Simulate an outside execution:
+
+On executor side, if you want to simulate the transaction:
+
+```typescript
+const outsideExecutionCall: Call[] =
+  outsideExecution.buildExecuteFromOutsideCall(outsideTransaction1);
+const invocations: Invocations = [
+  {
+    type: TransactionType.INVOKE,
+    payload: outsideExecutionCall,
+  },
+];
+const responseSimulate = await executorAccount.simulateTransaction(invocations);
+```
