SystemContractHelper

Git Source

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

NameTypeDescription
_isServiceboolThe isService flag.
_keybytes32The key part of the L2Log.
_valuebytes32The 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

NameTypeDescription
_inputMemoryOffsetuint32The memory offset in 32-byte words for the input data for calling the precompile.
_inputMemoryLengthuint32The length of the input data in words.
_outputMemoryOffsetuint32The memory offset in 32-byte words for the output data.
_outputMemoryLengthuint32The length of the output data in words.
_perPrecompileInterpreteduint64The 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

NameTypeDescription
_rawParamsuint256The packed precompile params. They can be retrieved by the packPrecompileParams method.
_gasToBurnuint32The number of gas to burn during this call.
_pubdataToSpenduint32The number of pubdata bytes to burn during the call.

Returns

NameTypeDescription
successboolWhether 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

NameTypeDescription
_valueuint128The msg.value that will be used for the next call.

eventInitialize

Initialize a new event.

function eventInitialize(uint256 initializer, uint256 value1) internal;

Parameters

NameTypeDescription
initializeruint256The event initializing value.
value1uint256The first topic or data chunk.

eventWrite

Continue writing the previously initialized event.

function eventWrite(uint256 value1, uint256 value2) internal;

Parameters

NameTypeDescription
value1uint256The first topic or data chunk.
value2uint256The 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

NameTypeDescription
metauint256The 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

NameTypeDescription
metauint256Packed representation of the ZkSyncMeta.
offsetuint256The offset of the bits.
sizeuint256The size of the extracted number in bits.

Returns

NameTypeDescription
resultuint256The 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

NameTypeDescription
metauint256Packed representation of the ZkSyncMeta.

Returns

NameTypeDescription
pubdataPublisheduint32The 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

NameTypeDescription
metauint256Packed representation of the ZkSyncMeta.

Returns

NameTypeDescription
heapSizeuint32The 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

NameTypeDescription
metauint256Packed representation of the ZkSyncMeta.

Returns

NameTypeDescription
auxHeapSizeuint32The 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

NameTypeDescription
metauint256Packed representation of the ZkSyncMeta.

Returns

NameTypeDescription
shardIduint8The 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

NameTypeDescription
metauint256Packed representation of the ZkSyncMeta.

Returns

NameTypeDescription
callerShardIduint8The 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

NameTypeDescription
metauint256Packed representation of the ZkSyncMeta.

Returns

NameTypeDescription
codeShardIduint8The 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

NameTypeDescription
metaZkSyncMetaThe 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

NameTypeDescription
callFlagsuint256The 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

NameTypeDescription
ptruint256The 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

NameTypeDescription
extraAbiDatauint256The 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

NameTypeDescription
<none>booltrue 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

NameTypeDescription
_addressaddressThe address to test

Returns

NameTypeDescription
<none>booltrue 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

NameTypeDescription
<none>booltrue 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

NameTypeDescription
_gasToPayuint32The number of gas to burn.
_pubdataToSpenduint32The 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

NameTypeDescription
_toaddressThe address to call.
_whoToMimicaddressThe address to mimic.
_databytesThe data to pass to the call.

Returns

NameTypeDescription
successboolWhether the call was successful.
returndatabytesThe 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

NameTypeDescription
_addraddressThe address to force-deploy the bytecodehash to.
_bytecodeHashbytes32The 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

NameTypeDescription
_toaddressThe address to call.
_whoToMimicaddressThe address to mimic.
_databytesThe data to pass to the call.