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. |