SystemContractHelper
Author: Matter Labs
Library used for accessing zkEVM-specific opcodes, needed for the development of system contracts.
While this library will be eventually available to public, some of the provided methods won't work for non-system contracts and also breaking changes at short notice are possible. We do not recommend this library for external use.
Note: security-contact: security@matterlabs.dev
Functions
toL1
Send an L2Log to L1.
The meaning of all these parameters is context-dependent, but they have no intrinsic meaning per se.
function toL1(bool _isService, bytes32 _key, bytes32 _value) internal;
Parameters
Name | Type | Description |
---|---|---|
_isService | bool | The isService flag. |
_key | bytes32 | The key part of the L2Log. |
_value | bytes32 | The value part of the L2Log. |
getCodeAddress
Get address of the currently executed code.
This allows differentiating between call
and delegatecall
.
During the former this
and codeAddress
are the same, while
during the latter they are not.
function getCodeAddress() internal view returns (address addr);
loadCalldataIntoActivePtr
Provide a compiler hint, by placing calldata fat pointer into virtual ACTIVE_PTR
,
that can be manipulated by ptr.add
/ptr.sub
/ptr.pack
/ptr.shrink
later.
This allows making a call by forwarding calldata pointer to the child call. It is a much more efficient way to forward calldata, than standard EVM bytes copying.
function loadCalldataIntoActivePtr() internal view;
ptrPackIntoActivePtr
Compiler simulation of the ptr.pack
opcode for the virtual ACTIVE_PTR
pointer.
Do the concatenation between lowest part of ACTIVE_PTR
and highest part of _farCallAbi
forming packed fat pointer for a far call or ret ABI when necessary.
Note: Panics if the lowest 128 bits of _farCallAbi
are not zeroes.
function ptrPackIntoActivePtr(uint256 _farCallAbi) internal view;
ptrAddIntoActive
Compiler simulation of the ptr.add
opcode for the virtual ACTIVE_PTR
pointer.
Transforms ACTIVE_PTR.offset
into ACTIVE_PTR.offset + u32(_value)
. If overflow happens then it panics.
function ptrAddIntoActive(uint32 _value) internal view;
ptrShrinkIntoActive
Compiler simulation of the ptr.shrink
opcode for the virtual ACTIVE_PTR
pointer.
Transforms ACTIVE_PTR.length
into ACTIVE_PTR.length - u32(_shrink)
. If underflow happens then it panics.
function ptrShrinkIntoActive(uint32 _shrink) internal view;
packPrecompileParams
packs precompile parameters into one word
function packPrecompileParams(
uint32 _inputMemoryOffset,
uint32 _inputMemoryLength,
uint32 _outputMemoryOffset,
uint32 _outputMemoryLength,
uint64 _perPrecompileInterpreted
) internal pure returns (uint256 rawParams);
Parameters
Name | Type | Description |
---|---|---|
_inputMemoryOffset | uint32 | The memory offset in 32-byte words for the input data for calling the precompile. |
_inputMemoryLength | uint32 | The length of the input data in words. |
_outputMemoryOffset | uint32 | The memory offset in 32-byte words for the output data. |
_outputMemoryLength | uint32 | The length of the output data in words. |
_perPrecompileInterpreted | uint64 | The constant, the meaning of which is defined separately for each precompile. For information, please read the documentation of the precompilecall log in the VM. |
unsafePrecompileCall
Call precompile with given parameters.
The list of currently available precompiles sha256, keccak256, ecrecover.
NOTE: The precompile type depends on this
which calls precompile, which means that only
system contracts corresponding to the list of precompiles above can do precompileCall
.
If used not in the sha256
, keccak256
or ecrecover
contracts, it will just burn the gas provided.
This method is unsafe
because it does not check whether there is enough gas to burn.
function unsafePrecompileCall(
uint256 _rawParams,
uint32 _gasToBurn,
uint32 _pubdataToSpend
) internal view returns (bool success);
Parameters
Name | Type | Description |
---|---|---|
_rawParams | uint256 | The packed precompile params. They can be retrieved by the packPrecompileParams method. |
_gasToBurn | uint32 | The number of gas to burn during this call. |
_pubdataToSpend | uint32 | The number of pubdata bytes to burn during the call. |
Returns
Name | Type | Description |
---|---|---|
success | bool | Whether the call was successful. |
setValueForNextFarCall
Set msg.value
to next far call.
If called not in kernel mode, it will result in a revert (enforced by the VM)
function setValueForNextFarCall(uint128 _value) internal returns (bool success);
Parameters
Name | Type | Description |
---|---|---|
_value | uint128 | The msg.value that will be used for the next call. |
eventInitialize
Initialize a new event.
function eventInitialize(uint256 initializer, uint256 value1) internal;
Parameters
Name | Type | Description |
---|---|---|
initializer | uint256 | The event initializing value. |
value1 | uint256 | The first topic or data chunk. |
eventWrite
Continue writing the previously initialized event.
function eventWrite(uint256 value1, uint256 value2) internal;
Parameters
Name | Type | Description |
---|---|---|
value1 | uint256 | The first topic or data chunk. |
value2 | uint256 | The second topic or data chunk. |
getZkSyncMetaBytes
Get the packed representation of the ZkSyncMeta
from the current context.
NOTE: The behavior of this function will experience a breaking change in 2024.
The fields in ZkSyncMeta are NOT tightly packed, i.e. there is a special rule on how they are packed. For more information, please read the documentation on ZkSyncMeta.
function getZkSyncMetaBytes() internal view returns (uint256 meta);
Returns
Name | Type | Description |
---|---|---|
meta | uint256 | The packed representation of the ZkSyncMeta. |
extractNumberFromMeta
Returns the bits [offset..offset+size-1] of the meta.
function extractNumberFromMeta(uint256 meta, uint256 offset, uint256 size)
internal
pure
returns (uint256 result);
Parameters
Name | Type | Description |
---|---|---|
meta | uint256 | Packed representation of the ZkSyncMeta. |
offset | uint256 | The offset of the bits. |
size | uint256 | The size of the extracted number in bits. |
Returns
Name | Type | Description |
---|---|---|
result | uint256 | The extracted number. |
getPubdataPublishedFromMeta
Given the packed representation of ZkSyncMeta
, retrieves the number of pubdata
bytes published in the batch so far.
NOTE: The behavior of this function will experience a breaking change in 2024.
function getPubdataPublishedFromMeta(uint256 meta)
internal
pure
returns (uint32 pubdataPublished);
Parameters
Name | Type | Description |
---|---|---|
meta | uint256 | Packed representation of the ZkSyncMeta. |
Returns
Name | Type | Description |
---|---|---|
pubdataPublished | uint32 | The amount of pubdata published in the system so far. |
getHeapSizeFromMeta
Given the packed representation of ZkSyncMeta
, retrieves the number of the current size
of the heap in bytes.
The following expression: getHeapSizeFromMeta(getZkSyncMetaBytes()) is equivalent to the MSIZE in Solidity.
function getHeapSizeFromMeta(uint256 meta)
internal
pure
returns (uint32 heapSize);
Parameters
Name | Type | Description |
---|---|---|
meta | uint256 | Packed representation of the ZkSyncMeta. |
Returns
Name | Type | Description |
---|---|---|
heapSize | uint32 | The size of the memory in bytes byte. |
getAuxHeapSizeFromMeta
Given the packed representation of ZkSyncMeta
, retrieves the number of the current size
of the auxiliary heap in bytes.
You can read more on auxiliary memory in the VM1.2 documentation.
function getAuxHeapSizeFromMeta(uint256 meta)
internal
pure
returns (uint32 auxHeapSize);
Parameters
Name | Type | Description |
---|---|---|
meta | uint256 | Packed representation of the ZkSyncMeta. |
Returns
Name | Type | Description |
---|---|---|
auxHeapSize | uint32 | The size of the auxiliary memory in bytes byte. |
getShardIdFromMeta
Given the packed representation of ZkSyncMeta
, retrieves the shardId of this
.
Currently only shard 0 (zkRollup) is supported.
function getShardIdFromMeta(uint256 meta) internal pure returns (uint8 shardId);
Parameters
Name | Type | Description |
---|---|---|
meta | uint256 | Packed representation of the ZkSyncMeta. |
Returns
Name | Type | Description |
---|---|---|
shardId | uint8 | The shardId of this . |
getCallerShardIdFromMeta
Given the packed representation of ZkSyncMeta
, retrieves the shardId of
the msg.sender.
Currently only shard 0 (zkRollup) is supported.
function getCallerShardIdFromMeta(uint256 meta)
internal
pure
returns (uint8 callerShardId);
Parameters
Name | Type | Description |
---|---|---|
meta | uint256 | Packed representation of the ZkSyncMeta. |
Returns
Name | Type | Description |
---|---|---|
callerShardId | uint8 | The shardId of the msg.sender. |
getCodeShardIdFromMeta
Given the packed representation of ZkSyncMeta
, retrieves the shardId of
the currently executed code.
Currently only shard 0 (zkRollup) is supported.
function getCodeShardIdFromMeta(uint256 meta)
internal
pure
returns (uint8 codeShardId);
Parameters
Name | Type | Description |
---|---|---|
meta | uint256 | Packed representation of the ZkSyncMeta. |
Returns
Name | Type | Description |
---|---|---|
codeShardId | uint8 | The shardId of the currently executed code. |
getZkSyncMeta
Retrieves the ZkSyncMeta structure.
NOTE: The behavior of this function will experience a breaking change in 2024.
function getZkSyncMeta() internal view returns (ZkSyncMeta memory meta);
Returns
Name | Type | Description |
---|---|---|
meta | ZkSyncMeta | The ZkSyncMeta execution context parameters. |
getCallFlags
Returns the call flags for the current call.
Call flags is the value of the first register at the start of the call.
The zero bit of the callFlags indicates whether the call is a constructor call. The first bit of the callFlags indicates whether the call is a system one.
function getCallFlags() internal view returns (uint256 callFlags);
Returns
Name | Type | Description |
---|---|---|
callFlags | uint256 | The bitmask of the callflags. |
getCalldataPtr
Returns the current calldata pointer.
NOTE: This file is just an integer and it cannot be used to forward the calldata to the next calls in any way.
function getCalldataPtr() internal view returns (uint256 ptr);
Returns
Name | Type | Description |
---|---|---|
ptr | uint256 | The current calldata pointer. |
getExtraAbiData
Returns the N-th extraAbiParam for the current call.
It is equal to the value of the (N+2)-th register at the start of the call.
function getExtraAbiData(uint256 index)
internal
view
returns (uint256 extraAbiData);
Returns
Name | Type | Description |
---|---|---|
extraAbiData | uint256 | The value of the N-th extraAbiParam for this call. |
isSystemCall
Returns whether the current call is a system call.
function isSystemCall() internal view returns (bool);
Returns
Name | Type | Description |
---|---|---|
<none> | bool | true or false based on whether the current call is a system call. |
isSystemContract
Returns whether the address is a system contract.
function isSystemContract(address _address) internal pure returns (bool);
Parameters
Name | Type | Description |
---|---|---|
_address | address | The address to test |
Returns
Name | Type | Description |
---|---|---|
<none> | bool | true or false based on whether the _address is a system contract. |
isSystemCallFromEvmEmulator
Returns whether the current call is a system call from EVM emulator.
function isSystemCallFromEvmEmulator() internal view returns (bool);
Returns
Name | Type | Description |
---|---|---|
<none> | bool | true or false based on whether the current call is a system call from EVM emulator. |
burnGas
Method used for burning a certain amount of gas.
function burnGas(uint32 _gasToPay, uint32 _pubdataToSpend) internal view;
Parameters
Name | Type | Description |
---|---|---|
_gasToPay | uint32 | The number of gas to burn. |
_pubdataToSpend | uint32 | The number of pubdata bytes to burn during the call. |
mimicCall
Performs a mimicCall
to an address.
function mimicCall(address _to, address _whoToMimic, bytes memory _data)
internal
returns (bool success, bytes memory returndata);
Parameters
Name | Type | Description |
---|---|---|
_to | address | The address to call. |
_whoToMimic | address | The address to mimic. |
_data | bytes | The data to pass to the call. |
Returns
Name | Type | Description |
---|---|---|
success | bool | Whether the call was successful. |
returndata | bytes | The return data of the call. |
forceDeployNoConstructor
Force deploys some bytecode hash to an address without invoking the constructor.
function forceDeployNoConstructor(address _addr, bytes32 _bytecodeHash)
internal;
Parameters
Name | Type | Description |
---|---|---|
_addr | address | The address to force-deploy the bytecodehash to. |
_bytecodeHash | bytes32 | The bytecode hash to force-deploy. |
mimicCallWithPropagatedRevert
Performs a mimicCall
to an address, while ensuring that the call
was successful
function mimicCallWithPropagatedRevert(
address _to,
address _whoToMimic,
bytes memory _data
) internal;
Parameters
Name | Type | Description |
---|---|---|
_to | address | The address to call. |
_whoToMimic | address | The address to mimic. |
_data | bytes | The data to pass to the call. |