EfficientCall

Author: Matter Labs

This library is used to perform ultra-efficient calls using zkEVM-specific features.

EVM calls always accept a memory slice as input and return a memory slice as output. Therefore, even if the user has a ready-made calldata slice, they still need to copy it to memory before calling. This is especially inefficient for large inputs (proxies, multi-calls, etc.). In turn, zkEVM operates over a fat pointer, which is a set of (memory page, offset, start, length) in the memory/calldata/returndata. This allows forwarding the calldata slice as is, without copying it to memory.

Fat pointer is not just an integer, it is an extended data type supported on the VM level. zkEVM creates the wellformed fat pointers for all the calldata/returndata regions, later the contract may manipulate the already created fat pointers to forward a slice of the data, but not to create new fat pointers!

*The allowed operation on fat pointers are:

ptr.add - Transforms ptr.offset into ptr.offset + u32(_value). If overflow happens then it panics.
ptr.sub - Transforms ptr.offset into ptr.offset - u32(_value). If underflow happens then it panics.
ptr.pack - Do the concatenation between the lowest 128 bits of the pointer itself and the highest 128 bits of _value. It is typically used to prepare the ABI for external calls.
ptr.shrink - Transforms ptr.length into ptr.length - u32(_shrink). If underflow happens then it panics.*

*The call opcodes accept the fat pointer and change it to its canonical form before passing it to the child call

ptr.start is transformed into ptr.offset + ptr.start
ptr.length is transformed into ptr.length - ptr.offset
ptr.offset is transformed into 0*

Note: security-contact: security@matterlabs.dev

Functions

keccak

Call the keccak256 without copying calldata to memory.

function keccak(bytes calldata _data) internal view returns (bytes32);

Parameters

Name	Type	Description
`_data`	`bytes`	The preimage data.

Returns

Name	Type	Description
`<none>`	`bytes32`	The `keccak256` hash.

sha

Call the sha256 precompile without copying calldata to memory.

function sha(bytes calldata _data) internal view returns (bytes32);

Parameters

Name	Type	Description
`_data`	`bytes`	The preimage data.

Returns

Name	Type	Description
`<none>`	`bytes32`	The `sha256` hash.

call

Perform a call without copying calldata to memory.

function call(
  uint256 _gas,
  address _address,
  uint256 _value,
  bytes calldata _data,
  bool _isSystem
) internal returns (bytes memory returnData);

Parameters

Name	Type	Description
`_gas`	`uint256`	The gas to use for the call.
`_address`	`address`	The address to call.
`_value`	`uint256`	The `msg.value` to send.
`_data`	`bytes`	The calldata to use for the call.
`_isSystem`	`bool`	Whether the call should contain the `isSystem` flag.

Returns

Name	Type	Description
`returnData`	`bytes`	The copied to memory return data.

staticCall

Perform a staticCall without copying calldata to memory.

function staticCall(uint256 _gas, address _address, bytes calldata _data)
  internal
  view
  returns (bytes memory returnData);

Parameters

Name	Type	Description
`_gas`	`uint256`	The gas to use for the call.
`_address`	`address`	The address to call.
`_data`	`bytes`	The calldata to use for the call.

Returns

Name	Type	Description
`returnData`	`bytes`	The copied to memory return data.

delegateCall

Perform a delegateCall without copying calldata to memory.

function delegateCall(uint256 _gas, address _address, bytes calldata _data)
  internal
  returns (bytes memory returnData);

Parameters

Name	Type	Description
`_gas`	`uint256`	The gas to use for the call.
`_address`	`address`	The address to call.
`_data`	`bytes`	The calldata to use for the call.

Returns

Name	Type	Description
`returnData`	`bytes`	The copied to memory return data.

mimicCall

Perform a mimicCall (a call with custom msg.sender) without copying calldata to memory.

function mimicCall(
  uint256 _gas,
  address _address,
  bytes calldata _data,
  address _whoToMimic,
  bool _isConstructor,
  bool _isSystem
) internal returns (bytes memory returnData);

Parameters

Name	Type	Description
`_gas`	`uint256`	The gas to use for the call.
`_address`	`address`	The address to call.
`_data`	`bytes`	The calldata to use for the call.
`_whoToMimic`	`address`	The `msg.sender` for the next call.
`_isConstructor`	`bool`	Whether the call should contain the `isConstructor` flag.
`_isSystem`	`bool`	Whether the call should contain the `isSystem` flag.

Returns

Name	Type	Description
`returnData`	`bytes`	The copied to memory return data.

rawCall

Perform a call without copying calldata to memory.

function rawCall(
  uint256 _gas,
  address _address,
  uint256 _value,
  bytes calldata _data,
  bool _isSystem
) internal returns (bool success);

Parameters

Name	Type	Description
`_gas`	`uint256`	The gas to use for the call.
`_address`	`address`	The address to call.
`_value`	`uint256`	The `msg.value` to send.
`_data`	`bytes`	The calldata to use for the call.
`_isSystem`	`bool`	Whether the call should contain the `isSystem` flag.

Returns

Name	Type	Description
`success`	`bool`	whether the call was successful.

rawStaticCall

Perform a staticCall without copying calldata to memory.

function rawStaticCall(uint256 _gas, address _address, bytes calldata _data)
  internal
  view
  returns (bool success);

Parameters

Name	Type	Description
`_gas`	`uint256`	The gas to use for the call.
`_address`	`address`	The address to call.
`_data`	`bytes`	The calldata to use for the call.

Returns

Name	Type	Description
`success`	`bool`	whether the call was successful.

rawDelegateCall

Perform a delegatecall without copying calldata to memory.

function rawDelegateCall(uint256 _gas, address _address, bytes calldata _data)
  internal
  returns (bool success);

Parameters

Name	Type	Description
`_gas`	`uint256`	The gas to use for the call.
`_address`	`address`	The address to call.
`_data`	`bytes`	The calldata to use for the call.

Returns

Name	Type	Description
`success`	`bool`	whether the call was successful.

rawMimicCall

Perform a mimicCall (call with custom msg.sender) without copying calldata to memory.

If called not in kernel mode, it will result in a revert (enforced by the VM)

function rawMimicCall(
  uint256 _gas,
  address _address,
  bytes calldata _data,
  address _whoToMimic,
  bool _isConstructor,
  bool _isSystem
) internal returns (bool success);

Parameters

Name	Type	Description
`_gas`	`uint256`	The gas to use for the call.
`_address`	`address`	The address to call.
`_data`	`bytes`	The calldata to use for the call.
`_whoToMimic`	`address`	The `msg.sender` for the next call.
`_isConstructor`	`bool`	Whether the call should contain the `isConstructor` flag.
`_isSystem`	`bool`	Whether the call should contain the `isSystem` flag.

Returns

Name	Type	Description
`success`	`bool`	whether the call was successful.

_verifyCallResult

Verify that a low-level call was successful, and revert if it wasn't, by bubbling the revert reason.

function _verifyCallResult(bool _success)
  private
  pure
  returns (bytes memory returnData);

Parameters

Name	Type	Description
`_success`	`bool`	Whether the call was successful.

Returns

Name	Type	Description
`returnData`	`bytes`	The copied to memory return data.

propagateRevert

Propagate the revert reason from the current call to the caller.

function propagateRevert() internal pure;

_loadFarCallABIIntoActivePtr

Load the far call ABI into active ptr, that will be used for the next call by reference.

function _loadFarCallABIIntoActivePtr(
  uint256 _gas,
  bytes calldata _data,
  bool _isConstructor,
  bool _isSystem
) private view;

Parameters

Name	Type	Description
`_gas`	`uint256`	The gas to be passed to the call.
`_data`	`bytes`	The calldata to be passed to the call.
`_isConstructor`	`bool`	Whether the call is a constructor call.
`_isSystem`	`bool`	Whether the call is a system call.

ZKSync Contracts