FCT_Lib_MultiCallV2

FCT_Lib_MultiCallV2 adds the ability to aggregate calls with flow control and variable arguments. It allows to retrieve the status of each call, and the data returned by each call. It also supports dry runs, where the calls are executed, return data is retrieved, but the state is not changed.

Functions structure

function <name>(
    <call type>[] calldata calls,
    uint256 first,
    uint256 last,
    bool dryrun
) external returns (bytes memory returnedData)

Calls

Calls struct array holds the meta and data of each call.

Calls struct is the only parameter that differs between the following functions.

First

The call index (starts with 1) of the starting point for the calls.

Last

The call index (starts with 1) of the ending point for the calls.

Dryrun

A boolean that sets the dry-run mode, which reverts the function call even when all calls succeed.

Dry-run is very useful for simulating set of calls on-chain as part of the transaction, getting the results and acting upon them.

Returned Data

Returns the status of each call, and the data returned by each call.

The return structure match solidity reverts structure (selector<bytes4> + data<abi encoded>).

Returning the same structure when reverting or success function calls, giving the calling contact the ability to handle the results the same way, regardless of successful execution or not.

On a successful execution the return selector holds bytes4(0), making it easy to detect if the call was reverted or not, directly from the returned data.

When dry-run is being used or calls should revert (according to flow), a custom revert is returned, holding status and data for all calls.

When there is fail in the multi call itself, due to wrong inputs, standard revert is returned holding error message. No status of data of calls is returned in this case.

Returned Data As Variables

Returned inner calls data are variables that are created automatically when executing FCT. This variables holds all the returned values from previous called functions of the current FCT execution.

How to use

The returned inner calls data are kept in bytes format for each call. That means that in order to use a variable there is a need to tell the MultiCallV2 function from what call and with what offset the value exist.

Usage

0xEF000....TTTTTTLLLL LLLL holds the call number (starting with 1) TTTTTT holds the offset in bytes inside the call

0xEF00000000000000000000000000000000600003 means the 64-96 bytes of the returned data from the third call on the FCT will be used

Because the returned data is held in bytes type, the returned calls data starts at the 32 bytes offset (0x20)

0xEF0000....TTTTTTLLLL LLLL holds the call number (starting with 1) TTTTTT holds the reverse offset (backwards) in bytes inside the call

0xEE00000000000000000000000000000000000003 means the last 32 bytes of the returned data from the third call on the FCT will be used

Inner returned data variable use four range of values: For address types: 0xEF00000000000000000000000000000000000001 ... 0xEF0000000000000000000000000000ffffffffff and 0xEE00000000000000000000000000000000000001 ... 0xEE0000000000000000000000000000ffffffffff For uint256 and bytes32 types:

0xEF00000000000000000000000000000000000000000000000000000000000001 ... 0xEF0000000000000000000000000000000000000000000000000000ffffffffff and 0xEE00000000000000000000000000000000000000000000000000000000000001 ... 0xEE0000000000000000000000000000000000000000000000000000ffffffffff

Call number must be smaller than the current running call

Function: multiCallFlowControlled

function multiCallFlowControlled(
    CallWithFlow[] calldata calls,
    uint256 first,
    uint256 last,
    bool dryrun
) external returns (bytes memory returnedData)

Executes a batch of calls, with flow control and variable arguments.

Calls array holds meta and data of each call as follows:

target

Destination of the call. A smart contract address in case of calling a contract, or any address in case of sending ETH.

call_type

FCT supports three types of calls: call, staticcall and delegatecall

flow_control is defined using human readable string, so the user can easily see the call type.

EIP712 String	Value	Meaning
"action"	0	Executing the call using the low level "call" function. The contract being called can change blockchain state and sees the FCT_Runner as the calling entity.
"view only"	1	Executing the call using the low level "staticcall" function. The contract being called is not allowed to change the blockchain state and sees the FCT_Runner as the calling entity.

value

The native token value that will be sent with the call.

method

The name of the function to be called followed by type-names, in parentheses, without any spaces. This is used in order to calculate the function signature and selector. See more info here

ERC20 transfer method interface looks like this: "transfer(address,uint256)"

flow

FCT supports if/then functionality via the flow_control field combined with the "jump on" fields.

flow_control is defined using human readable string, so the user can easily see the flow condition.

EIP712 String	Value	Meaning
"continue on success, revert on fail"	0	If call reverts, revert the whole FCT, otherwise, continue to the next call according to the jump_on_success field
"continue on success, stop on fail"	1	If call reverts, stop FCT execution (previous calls are not reverted), otherwise, continue to the next call according to the jump_on_success field
"continue on success, continue on fail"	2	Whether call reverts or not, continue to the next call according to the jump_on_success and jump_on_fail fields respectively
"revert on success, continue on fail"	3	If call reverts, continue to the next call according to the jump_on_fail field, otherwise, revert the whole FCT
"revert on success, stop on fail"	4	If call reverts, stop FCT execution (previous calls are not reverted), otherwise, revert the whole FCT
"stop on success, continue on fail"	5	If call reverts, continue to the next call according to the jump_on_fail field, otherwise, stop FCT execution (previous calls are not reverted)
"stop on success, revert on fail"	6	If call reverts, revert the whole FCT, otherwise, stop FCT execution (previous calls are not reverted)
"stop on success, stop on fail"	7	Whether call reverts or not, stop FCT execution (previous calls are not reverted)

if/then blocks can be achieved by using one of the "cont" flow controls and setting the "jump_on" values

falseMeanFail

Some functions returns false rather than reverting. When this boolean field is set to true, returning false from the calling contract's function will be considered as a revert of that function.

jumpOnSuccess

Part of the flow control. Specify the amount of calls to jump over when current call succeed. When setting to 0 and the current call succeed, the adjacent call will be executed.

This value is ignored when "stop on success" or "revert on success" is being used

jumpOnFail

Part of the flow control. Specify the amount of calls to jump over when current call fails. When setting to 0 and the current call fails, the adjacent call will be executed.

This value is ignored when "stop on fail" or "revert on fail" is being used

varArgsStart

Specify the starting point (offset), in bytes, for the FCT engine's variables searcher.

Both variable_arguments start and end, gives a hint to the FCT engine where, in function call data, variable values might be used.

Set both to 0, if no variables are being used in function call data, in order to save gas.

varArgsEnd

Specify the ending point (not including), in bytes, for the FCT engine's variables searcher.

data

The abi encoded arguments of a function call.

Function: multiCall

function multiCall(
    Call[] calldata calls,
    uint256 first,
    uint256 last,
    bool dryrun
) external returns (bytes memory returnedData)

Executes a batch of calls, with variable arguments.

Calls array holds meta and data of each call as follows:

target

Destination of the call. A smart contract address in case of calling a contract, or any address in case of sending ETH.

call_type

FCT supports three types of calls: call, staticcall and delegatecall

flow_control is defined using human readable string, so the user can easily see the call type.

EIP712 String	Value	Meaning
"action"	0	Executing the call using the low level "call" function. The contract being called can change blockchain state and sees the FCT_Runner as the calling entity.
"view only"	1	Executing the call using the low level "staticcall" function. The contract being called is not allowed to change the blockchain state and sees the FCT_Runner as the calling entity.

value

The native token value that will be sent with the call.

method

The name of the function to be called followed by type-names, in parentheses, without any spaces. This is used in order to calculate the function signature and selector. See more info here

ERC20 transfer method interface looks like this: "transfer(address,uint256)"

varArgsStart

Specify the starting point (offset), in bytes, for the FCT engine's variables searcher.

Both variable_arguments start and end, gives a hint to the FCT engine where, in function call data, variable values might be used.

Set both to 0, if no variables are being used in function call data, in order to save gas.

varArgsEnd

Specify the ending point (not including), in bytes, for the FCT engine's variables searcher.

data

The abi encoded arguments of a function call.

Function: multiCallSimple

function multiCallSimple(
    CallSimple[] calldata calls,
    uint256 first,
    uint256 last,
    bool dryrun
) external returns (bytes memory returnedData)

Executes a batch of calls.

Calls array holds meta and data of each call as follows:

target

Destination of the call. A smart contract address in case of calling a contract, or any address in case of sending ETH.

call_type

FCT supports three types of calls: call, staticcall and delegatecall

flow_control is defined using human readable string, so the user can easily see the call type.

EIP712 String	Value	Meaning
"action"	0	Executing the call using the low level "call" function. The contract being called can change blockchain state and sees the FCT_Runner as the calling entity.
"view only"	1	Executing the call using the low level "staticcall" function. The contract being called is not allowed to change the blockchain state and sees the FCT_Runner as the calling entity.

value

The native token value that will be sent with the call.

method

The name of the function to be called followed by type-names, in parentheses, without any spaces. This is used in order to calculate the function signature and selector. See more info here

ERC20 transfer method interface looks like this: "transfer(address,uint256)"

data

The abi encoded arguments of a function call.