Snapshot notice
These contracts target protocol version 29, commit 65234ab0.

[!NOTE] 🛠️ This is a development repository for interfaces only. If you're looking for contract implementations, see 👉 matter-labs/era-contracts

📦 Installation

To install with Foundry-ZKsync:

forge install matter-labs/zksync-contracts

Add the following to the remappings.txt file of your project:

@matterlabs/zksync-contracts/=lib/v2-testnet-contracts/

To install with Hardhat:

bun install @matterlabs/zksync-contracts

🚀 Quick start

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import {IPaymaster} from
    "@matterlabs/zksync-contracts/contracts/system-contracts/interfaces/IPaymaster.sol";

contract MyPaymaster is IPaymaster {
    // Your implementation here
}

See more examples in the official docs.

📖 Documentation

• API reference: https://docs.zksync.io
• Canonical source: matter-labs/era-contracts

🤝 Contributing

Bug fixes, new snapshots, and added ABIs are welcome! Open an issue before large changes and follow the standard PR workflow.

📜 License

Dual-licensed under MIT / Apache-2.0. See LICENSE-MIT and LICENSE-APACHE.

Installation

To install with Foundry-ZKsync:

forge install matter-labs/zksync-contracts

Add the following to the remappings.txt file of your project:

@matterlabs/zksync-contracts/=lib/v2-testnet-contracts/

To install with Hardhat:

bun install @matterlabs/zksync-contracts

Getting Started

1. Add the package

   # Hardhat / npm / bun
   npm add @matterlabs/zksync-contracts
   # or Foundry
   forge install matter-labs/zksync-contracts
   

2. Implement a contract

   // SPDX-License-Identifier: MIT
   pragma solidity ^0.8.20;
   
   import {IPaymaster} from
       "@matterlabs/zksync-contracts/contracts/system-contracts/interfaces/IPaymaster.sol";
   
   contract MyPaymaster is IPaymaster {
       // implement paymaster logic here
   }
   

3. Build & test

   • Hardhat npx hardhat compile
   • Foundry forge build

Contents

• bridge
• bridgehub
• common
• governance
• state-transition
• upgrades
• vendor

Contents

• asset-router
• interfaces
• ntv
• EthTransferFailed
• NativeTokenVaultAlreadySet
• WrongMsgLength
• ZeroAmountToTransfer
• WrongAmountTransferred
• EmptyToken
• ClaimFailedDepositFailed
• WrongL2Sender
• WrongCounterpart

Contents

• IAssetRouterBase
• IAssetRouterBase constants
• IL1AssetRouter
• IL2AssetRouter

IAssetRouterBase

Git Source

Author: Matter Labs

Note: security-contact: security@matterlabs.dev

Functions

BRIDGE_HUB

function BRIDGE_HUB() external view returns (IBridgehub);

setAssetHandlerAddressThisChain

Sets the asset handler address for a specified asset ID on the chain of the asset deployment tracker.

The caller of this function is encoded within the assetId, therefore, it should be invoked by the asset deployment tracker contract.

No access control on the caller, as msg.sender is encoded in the assetId.

Typically, for most tokens, ADT is the native token vault. However, custom tokens may have their own specific asset deployment trackers.

setAssetHandlerAddressOnCounterpart should be called on L1 to set asset handlers on L2 chains for a specific asset ID.

function setAssetHandlerAddressThisChain(
  bytes32 _assetRegistrationData,
  address _assetHandlerAddress
) external;

Parameters

assetHandlerAddress

function assetHandlerAddress(bytes32 _assetId) external view returns (address);

finalizeDeposit

Finalize the withdrawal and release funds.

We have both the legacy finalizeWithdrawal and the new finalizeDeposit functions, finalizeDeposit uses the new format. On the L2 we have finalizeDeposit with new and old formats both.

function finalizeDeposit(
  uint256 _chainId,
  bytes32 _assetId,
  bytes memory _transferData
) external payable;

Parameters

Events

BridgehubDepositBaseTokenInitiated

event BridgehubDepositBaseTokenInitiated(
  uint256 indexed chainId, address indexed from, bytes32 assetId, uint256 amount
);

BridgehubDepositInitiated

event BridgehubDepositInitiated(
  uint256 indexed chainId,
  bytes32 indexed txDataHash,
  address indexed from,
  bytes32 assetId,
  bytes bridgeMintCalldata
);

BridgehubWithdrawalInitiated

event BridgehubWithdrawalInitiated(
  uint256 chainId,
  address indexed sender,
  bytes32 indexed assetId,
  bytes32 assetDataHash
);

AssetDeploymentTrackerRegistered

event AssetDeploymentTrackerRegistered(
  bytes32 indexed assetId,
  bytes32 indexed additionalData,
  address assetDeploymentTracker
);

AssetHandlerRegistered

event AssetHandlerRegistered(
  bytes32 indexed assetId, address indexed _assetHandlerAddress
);

DepositFinalizedAssetRouter

event DepositFinalizedAssetRouter(
  uint256 indexed chainId, bytes32 indexed assetId, bytes assetData
);

Constants

Git Source

LEGACY_ENCODING_VERSION

The encoding version used for legacy txs.

bytes1 constant LEGACY_ENCODING_VERSION = 0x00;

NEW_ENCODING_VERSION

The encoding version used for new txs.

bytes1 constant NEW_ENCODING_VERSION = 0x01;

SET_ASSET_HANDLER_COUNTERPART_ENCODING_VERSION

The encoding version used for txs that set the asset handler on the counterpart contract.

bytes1 constant SET_ASSET_HANDLER_COUNTERPART_ENCODING_VERSION = 0x02;

IL1AssetRouter

Git Source

Inherits: IAssetRouterBase, IL1SharedBridgeLegacy

Author: Matter Labs

Note: security-contact: security@matterlabs.dev

Functions

depositLegacyErc20Bridge

Initiates a deposit by locking funds on the contract and sending the request of processing an L2 transaction where tokens would be minted.

If the token is bridged for the first time, the L2 token contract will be deployed. Note however, that the newly-deployed token does not support any custom logic, i.e. rebase tokens' functionality is not supported.

*If the L2 deposit finalization transaction fails, the _refundRecipient will receive the _l2Value. Please note, the contract may change the refund recipient's address to eliminate sending funds to addresses out of control.

• If _refundRecipient is a contract on L1, the refund will be sent to the aliased _refundRecipient.
• If _refundRecipient is set to address(0) and the sender has NO deployed bytecode on L1, the refund will be sent to the msg.sender address.
• If _refundRecipient is set to address(0) and the sender has deployed bytecode on L1, the refund will be sent to the aliased msg.sender address.*

The address aliasing of L1 contracts as refund recipient on L2 is necessary to guarantee that the funds are controllable through the Mailbox, since the Mailbox applies address aliasing to the from address for the L2 tx if the L1 msg.sender is a contract. Without address aliasing for L1 contracts as refund recipients they would not be able to make proper L2 tx requests through the Mailbox to use or withdraw the funds from L2, and the funds would be lost.

function depositLegacyErc20Bridge(
  address _originalCaller,
  address _l2Receiver,
  address _l1Token,
  uint256 _amount,
  uint256 _l2TxGasLimit,
  uint256 _l2TxGasPerPubdataByte,
  address _refundRecipient
) external payable returns (bytes32 txHash);

Parameters

Returns

L1_NULLIFIER

function L1_NULLIFIER() external view returns (IL1Nullifier);

L1_WETH_TOKEN

function L1_WETH_TOKEN() external view returns (address);

ETH_TOKEN_ASSET_ID

function ETH_TOKEN_ASSET_ID() external view returns (bytes32);

nativeTokenVault

function nativeTokenVault() external view returns (INativeTokenVault);

setAssetDeploymentTracker

function setAssetDeploymentTracker(
  bytes32 _assetRegistrationData,
  address _assetDeploymentTracker
) external;

setNativeTokenVault

function setNativeTokenVault(INativeTokenVault _nativeTokenVault) external;

setL1Erc20Bridge

function setL1Erc20Bridge(IL1ERC20Bridge _legacyBridge) external;

bridgeRecoverFailedTransfer

Withdraw funds from the initiated deposit, that failed when finalizing on L2.

Processes claims of failed deposit, whether they originated from the legacy bridge or the current system.

function bridgeRecoverFailedTransfer(
  uint256 _chainId,
  address _depositSender,
  bytes32 _assetId,
  bytes calldata _assetData
) external;

Parameters

bridgeRecoverFailedTransfer

Withdraw funds from the initiated deposit, that failed when finalizing on L2.

Processes claims of failed deposit, whether they originated from the legacy bridge or the current system.

function bridgeRecoverFailedTransfer(
  uint256 _chainId,
  address _depositSender,
  bytes32 _assetId,
  bytes memory _assetData,
  bytes32 _l2TxHash,
  uint256 _l2BatchNumber,
  uint256 _l2MessageIndex,
  uint16 _l2TxNumberInBatch,
  bytes32[] calldata _merkleProof
) external;

Parameters

transferFundsToNTV

Transfers funds to Native Token Vault, if the asset is registered with it. Does nothing for ETH or non-registered tokens.

assetId is not the padded address, but the correct encoded id (NTV stores respective format for IDs)

function transferFundsToNTV(
  bytes32 _assetId,
  uint256 _amount,
  address _originalCaller
) external returns (bool);

Parameters

finalizeWithdrawal

Finalize the withdrawal and release funds

function finalizeWithdrawal(
  uint256 _chainId,
  uint256 _l2BatchNumber,
  uint256 _l2MessageIndex,
  uint16 _l2TxNumberInBatch,
  bytes calldata _message,
  bytes32[] calldata _merkleProof
) external;

Parameters

bridgehubDeposit

Initiates a transfer transaction within Bridgehub, used by requestL2TransactionTwoBridges.

Data has the following abi encoding for legacy deposits: address _l1Token, uint256 _amount, address _l2Receiver for new deposits: bytes32 _assetId, bytes _transferData

function bridgehubDeposit(
  uint256 _chainId,
  address _originalCaller,
  uint256 _value,
  bytes calldata _data
) external payable returns (L2TransactionRequestTwoBridgesInner memory request);

Parameters

Returns

getDepositCalldata

Generates a calldata for calling the deposit finalization on the L2 native token contract.

function getDepositCalldata(
  address _sender,
  bytes32 _assetId,
  bytes memory _assetData
) external view returns (bytes memory);

Parameters

Returns

bridgehubDepositBaseToken

Allows bridgehub to acquire mintValue for L1->L2 transactions.

If the corresponding L2 transaction fails, refunds are issued to a refund recipient on L2.

function bridgehubDepositBaseToken(
  uint256 _chainId,
  bytes32 _assetId,
  address _originalCaller,
  uint256 _amount
) external payable;

Parameters

bridgehubConfirmL2Transaction

Routes the confirmation to nullifier for backward compatibility.

Confirms the acceptance of a transaction by the Mailbox, as part of the L2 transaction process within Bridgehub. This function is utilized by requestL2TransactionTwoBridges to validate the execution of a transaction.

function bridgehubConfirmL2Transaction(
  uint256 _chainId,
  bytes32 _txDataHash,
  bytes32 _txHash
) external;

Parameters

isWithdrawalFinalized

function isWithdrawalFinalized(
  uint256 _chainId,
  uint256 _l2BatchNumber,
  uint256 _l2MessageIndex
) external view returns (bool);

Events

BridgehubMintData

event BridgehubMintData(bytes bridgeMintData);

BridgehubDepositFinalized

event BridgehubDepositFinalized(
  uint256 indexed chainId,
  bytes32 indexed txDataHash,
  bytes32 indexed l2DepositTxHash
);

ClaimedFailedDepositAssetRouter

event ClaimedFailedDepositAssetRouter(
  uint256 indexed chainId, bytes32 indexed assetId, bytes assetData
);

AssetDeploymentTrackerSet

event AssetDeploymentTrackerSet(
  bytes32 indexed assetId,
  address indexed assetDeploymentTracker,
  bytes32 indexed additionalData
);

LegacyDepositInitiated

event LegacyDepositInitiated(
  uint256 indexed chainId,
  bytes32 indexed l2DepositTxHash,
  address indexed from,
  address to,
  address l1Token,
  uint256 amount
);

IL2AssetRouter

Git Source

Inherits: IAssetRouterBase

Author: Matter Labs

Note: security-contact: security@matterlabs.dev

Functions

withdraw

function withdraw(bytes32 _assetId, bytes calldata _transferData)
  external
  returns (bytes32);

L1_ASSET_ROUTER

function L1_ASSET_ROUTER() external view returns (address);

withdrawLegacyBridge

function withdrawLegacyBridge(
  address _l1Receiver,
  address _l2Token,
  uint256 _amount,
  address _sender
) external;

finalizeDepositLegacyBridge

function finalizeDepositLegacyBridge(
  address _l1Sender,
  address _l2Receiver,
  address _l1Token,
  uint256 _amount,
  bytes calldata _data
) external;

setAssetHandlerAddress

Used to set the assetHandlerAddress for a given assetId.

Will be used by ZK Gateway

function setAssetHandlerAddress(
  uint256 _originChainId,
  bytes32 _assetId,
  address _assetHandlerAddress
) external;

setLegacyTokenAssetHandler

Function that allows native token vault to register itself as the asset handler for a legacy asset.

function setLegacyTokenAssetHandler(bytes32 _assetId) external;

Parameters

Events

WithdrawalInitiatedAssetRouter

event WithdrawalInitiatedAssetRouter(
  uint256 chainId,
  address indexed l2Sender,
  bytes32 indexed assetId,
  bytes assetData
);

Contents

• AssetHandlerModifiers
• IAssetHandler
• IBridgedStandardToken
• IL1AssetDeploymentTracker
• IL1AssetHandler
• IL1BaseTokenAssetHandler
• IL1ERC20Bridge
• FinalizeL1DepositParams
• IL1Nullifier
• IL1SharedBridgeLegacy
• IL2SharedBridgeLegacy
• IL2SharedBridgeLegacyFunctions
• IL2WrappedBaseToken
• IWETH9

IAssetHandler

Git Source

Author: Matter Labs

Used for any asset handler and called by the AssetRouter

Note: security-contact: security@matterlabs.dev

Functions

bridgeMint

Note, that while payable, this function will only receive base token on L2 chains, while L1 the provided msg.value is always 0. However, this may change in the future, so if your AssetHandler implementation relies on it, it is better to explicitly check it.

function bridgeMint(uint256 _chainId, bytes32 _assetId, bytes calldata _data)
  external
  payable;

Parameters

bridgeBurn

Burns bridged tokens and returns the calldata for L2 <-> L1 message.

In case of native token vault _data is the tuple of _depositAmount and _l2Receiver.

function bridgeBurn(
  uint256 _chainId,
  uint256 _msgValue,
  bytes32 _assetId,
  address _originalCaller,
  bytes calldata _data
) external payable returns (bytes memory _bridgeMintData);

Parameters

Returns

Events

BridgeMint

Emitted when a token is minted

event BridgeMint(
  uint256 indexed chainId,
  bytes32 indexed assetId,
  address receiver,
  uint256 amount
);

BridgeBurn

Emitted when a token is burned

event BridgeBurn(
  uint256 indexed chainId,
  bytes32 indexed assetId,
  address indexed sender,
  address receiver,
  uint256 amount
);

IBridgedStandardToken

Git Source

Functions

bridgeMint

function bridgeMint(address _account, uint256 _amount) external;

bridgeBurn

function bridgeBurn(address _account, uint256 _amount) external;

l1Address

function l1Address() external view returns (address);

originToken

function originToken() external view returns (address);

l2Bridge

function l2Bridge() external view returns (address);

assetId

function assetId() external view returns (bytes32);

nativeTokenVault

function nativeTokenVault() external view returns (address);

Events

BridgeInitialize

event BridgeInitialize(
  address indexed l1Token, string name, string symbol, uint8 decimals
);

BridgeMint

event BridgeMint(address indexed account, uint256 amount);

BridgeBurn

event BridgeBurn(address indexed account, uint256 amount);

IL1AssetDeploymentTracker

Git Source

Author: Matter Labs

Note: security-contact: security@matterlabs.dev

Functions

bridgeCheckCounterpartAddress

function bridgeCheckCounterpartAddress(
  uint256 _chainId,
  bytes32 _assetId,
  address _originalCaller,
  address _assetHandlerAddressOnCounterpart
) external view;

IL1AssetHandler

Git Source

Author: Matter Labs

Used for any asset handler and called by the L1AssetRouter

Note: security-contact: security@matterlabs.dev

Functions

bridgeRecoverFailedTransfer

function bridgeRecoverFailedTransfer(
  uint256 _chainId,
  bytes32 _assetId,
  address _depositSender,
  bytes calldata _data
) external payable;

Parameters

IL1BaseTokenAssetHandler

Git Source

Author: Matter Labs

Used for any asset handler and called by the L1AssetRouter

Note: security-contact: security@matterlabs.dev

Functions

tokenAddress

Used to get the token address of an assetId

function tokenAddress(bytes32 _assetId) external view returns (address);

IL1ERC20Bridge

Git Source

Author: Matter Labs

Legacy Bridge interface before ZK chain migration, used for backward compatibility with ZKsync Era

Note: security-contact: security@matterlabs.dev

Functions

isWithdrawalFinalized

function isWithdrawalFinalized(uint256 _l2BatchNumber, uint256 _l2MessageIndex)
  external
  view
  returns (bool);

deposit

function deposit(
  address _l2Receiver,
  address _l1Token,
  uint256 _amount,
  uint256 _l2TxGasLimit,
  uint256 _l2TxGasPerPubdataByte,
  address _refundRecipient
) external payable returns (bytes32 txHash);

deposit

function deposit(
  address _l2Receiver,
  address _l1Token,
  uint256 _amount,
  uint256 _l2TxGasLimit,
  uint256 _l2TxGasPerPubdataByte
) external payable returns (bytes32 txHash);

claimFailedDeposit

function claimFailedDeposit(
  address _depositSender,
  address _l1Token,
  bytes32 _l2TxHash,
  uint256 _l2BatchNumber,
  uint256 _l2MessageIndex,
  uint16 _l2TxNumberInBatch,
  bytes32[] calldata _merkleProof
) external;

finalizeWithdrawal

function finalizeWithdrawal(
  uint256 _l2BatchNumber,
  uint256 _l2MessageIndex,
  uint16 _l2TxNumberInBatch,
  bytes calldata _message,
  bytes32[] calldata _merkleProof
) external;

l2TokenAddress

function l2TokenAddress(address _l1Token) external view returns (address);

L1_NULLIFIER

function L1_NULLIFIER() external view returns (IL1Nullifier);

L1_ASSET_ROUTER

function L1_ASSET_ROUTER() external view returns (IL1AssetRouter);

L1_NATIVE_TOKEN_VAULT

function L1_NATIVE_TOKEN_VAULT() external view returns (IL1NativeTokenVault);

l2TokenBeacon

function l2TokenBeacon() external view returns (address);

l2Bridge

function l2Bridge() external view returns (address);

depositAmount

function depositAmount(
  address _account,
  address _l1Token,
  bytes32 _depositL2TxHash
) external view returns (uint256 amount);

Events

DepositInitiated

event DepositInitiated(
  bytes32 indexed l2DepositTxHash,
  address indexed from,
  address indexed to,
  address l1Token,
  uint256 amount
);

WithdrawalFinalized

event WithdrawalFinalized(
  address indexed to, address indexed l1Token, uint256 amount
);

ClaimedFailedDeposit

event ClaimedFailedDeposit(
  address indexed to, address indexed l1Token, uint256 amount
);

IL1Nullifier

Git Source

Author: Matter Labs

Note: security-contact: security@matterlabs.dev

Functions

isWithdrawalFinalized

function isWithdrawalFinalized(
  uint256 _chainId,
  uint256 _l2BatchNumber,
  uint256 _l2MessageIndex
) external view returns (bool);

claimFailedDepositLegacyErc20Bridge

function claimFailedDepositLegacyErc20Bridge(
  address _depositSender,
  address _l1Token,
  uint256 _amount,
  bytes32 _l2TxHash,
  uint256 _l2BatchNumber,
  uint256 _l2MessageIndex,
  uint16 _l2TxNumberInBatch,
  bytes32[] calldata _merkleProof
) external;

claimFailedDeposit

function claimFailedDeposit(
  uint256 _chainId,
  address _depositSender,
  address _l1Token,
  uint256 _amount,
  bytes32 _l2TxHash,
  uint256 _l2BatchNumber,
  uint256 _l2MessageIndex,
  uint16 _l2TxNumberInBatch,
  bytes32[] calldata _merkleProof
) external;

finalizeDeposit

function finalizeDeposit(
  FinalizeL1DepositParams calldata _finalizeWithdrawalParams
) external;

BRIDGE_HUB

function BRIDGE_HUB() external view returns (IBridgehub);

legacyBridge

function legacyBridge() external view returns (IL1ERC20Bridge);

depositHappened

function depositHappened(uint256 _chainId, bytes32 _l2TxHash)
  external
  view
  returns (bytes32);

bridgehubConfirmL2TransactionForwarded

function bridgehubConfirmL2TransactionForwarded(
  uint256 _chainId,
  bytes32 _txDataHash,
  bytes32 _txHash
) external;

l1NativeTokenVault

function l1NativeTokenVault() external view returns (IL1NativeTokenVault);

setL1NativeTokenVault

function setL1NativeTokenVault(IL1NativeTokenVault _nativeTokenVault) external;

setL1AssetRouter

function setL1AssetRouter(address _l1AssetRouter) external;

chainBalance

function chainBalance(uint256 _chainId, address _token)
  external
  view
  returns (uint256);

l2BridgeAddress

function l2BridgeAddress(uint256 _chainId) external view returns (address);

transferTokenToNTV

function transferTokenToNTV(address _token) external;

nullifyChainBalanceByNTV

function nullifyChainBalanceByNTV(uint256 _chainId, address _token) external;

bridgeRecoverFailedTransfer

Withdraw funds from the initiated deposit, that failed when finalizing on L2.

Processes claims of failed deposit, whether they originated from the legacy bridge or the current system.

function bridgeRecoverFailedTransfer(
  uint256 _chainId,
  address _depositSender,
  bytes32 _assetId,
  bytes memory _assetData,
  bytes32 _l2TxHash,
  uint256 _l2BatchNumber,
  uint256 _l2MessageIndex,
  uint16 _l2TxNumberInBatch,
  bytes32[] calldata _merkleProof
) external;

Parameters

finalizeWithdrawal

Legacy function to finalize withdrawal via the same interface as the old L1SharedBridge.

Note, that we need to keep this interface, since the L2AssetRouter will continue returning the previous address as the l1SharedBridge. The value returned by it is used in the SDK for finalizing withdrawals.

function finalizeWithdrawal(
  uint256 _chainId,
  uint256 _l2BatchNumber,
  uint256 _l2MessageIndex,
  uint16 _l2TxNumberInBatch,
  bytes calldata _message,
  bytes32[] calldata _merkleProof
) external;

Parameters

Events

BridgehubDepositFinalized

event BridgehubDepositFinalized(
  uint256 indexed chainId,
  bytes32 indexed txDataHash,
  bytes32 indexed l2DepositTxHash
);

IL1SharedBridgeLegacy

Git Source

Author: Matter Labs

Note: security-contact: security@matterlabs.dev

Functions

l2BridgeAddress

function l2BridgeAddress(uint256 _chainId) external view returns (address);

IL2SharedBridgeLegacy

Git Source

Author: Matter Labs

Note: security-contact: security@matterlabs.dev

Functions

l2TokenBeacon

function l2TokenBeacon() external returns (UpgradeableBeacon);

withdraw

function withdraw(address _l1Receiver, address _l2Token, uint256 _amount)
  external;

l1TokenAddress

function l1TokenAddress(address _l2Token) external view returns (address);

l2TokenAddress

function l2TokenAddress(address _l1Token) external view returns (address);

l1Bridge

function l1Bridge() external view returns (address);

l1SharedBridge

function l1SharedBridge() external view returns (address);

deployBeaconProxy

function deployBeaconProxy(bytes32 _salt) external returns (address);

sendMessageToL1

function sendMessageToL1(bytes calldata _message) external returns (bytes32);

Events

FinalizeDeposit

event FinalizeDeposit(
  address indexed l1Sender,
  address indexed l2Receiver,
  address indexed l2Token,
  uint256 amount
);

IL2SharedBridgeLegacyFunctions

Git Source

Author: Matter Labs

Functions

finalizeDeposit

function finalizeDeposit(
  address _l1Sender,
  address _l2Receiver,
  address _l1Token,
  uint256 _amount,
  bytes calldata _data
) external;

Events

FinalizeDeposit

event FinalizeDeposit(
  address indexed l1Sender,
  address indexed l2Receiver,
  address indexed l2Token,
  uint256 amount
);

WithdrawalInitiated

event WithdrawalInitiated(
  address indexed l2Sender,
  address indexed l1Receiver,
  address indexed l2Token,
  uint256 amount
);

IL2WrappedBaseToken

Git Source

Functions

deposit

function deposit() external payable;

withdraw

function withdraw(uint256 _amount) external;

depositTo

function depositTo(address _to) external payable;

withdrawTo

function withdrawTo(address _to, uint256 _amount) external;

Events

Initialize

event Initialize(string name, string symbol, uint8 decimals);

IWETH9

Git Source

Functions

deposit

function deposit() external payable;

withdraw

function withdraw(uint256 wad) external;

Contents

• IL1NativeTokenVault
• IL2NativeTokenVault
• INativeTokenVault

IL1NativeTokenVault

Git Source

Inherits: INativeTokenVault, IL1AssetDeploymentTracker

Author: Matter Labs

The NTV is an Asset Handler for the L1AssetRouter to handle native tokens

Note: security-contact: security@matterlabs.dev

Functions

L1_NULLIFIER

The L1Nullifier contract

function L1_NULLIFIER() external view returns (IL1Nullifier);

chainBalance

Returns the total number of specific tokens locked for some chain

function chainBalance(uint256 _chainId, bytes32 _assetId)
  external
  view
  returns (uint256);

registerEthToken

Registers ETH token

function registerEthToken() external;

Events

TokenBeaconUpdated

event TokenBeaconUpdated(address indexed l2TokenBeacon);

IL2NativeTokenVault

Git Source

Inherits: INativeTokenVault

Author: Matter Labs

Note: security-contact: security@matterlabs.dev

Functions

l2TokenAddress

function l2TokenAddress(address _l1Token) external view returns (address);

setLegacyTokenAssetId

function setLegacyTokenAssetId(address _l2TokenAddress) external;

Events

FinalizeDeposit

event FinalizeDeposit(
  address indexed l1Sender,
  address indexed l2Receiver,
  address indexed l2Token,
  uint256 amount
);

WithdrawalInitiated

event WithdrawalInitiated(
  address indexed l2Sender,
  address indexed l1Receiver,
  address indexed l2Token,
  uint256 amount
);

L2TokenBeaconUpdated

event L2TokenBeaconUpdated(
  address indexed l2TokenBeacon, bytes32 indexed l2TokenProxyBytecodeHash
);

INativeTokenVault

Git Source

Author: Matter Labs

The NTV is an Asset Handler for the L1AssetRouter to handle native tokens

Note: security-contact: security@matterlabs.dev

Functions

WETH_TOKEN

The Weth token address

function WETH_TOKEN() external view returns (address);

ASSET_ROUTER

The AssetRouter contract

function ASSET_ROUTER() external view returns (IAssetRouterBase);

L1_CHAIN_ID

The chain ID of the L1 chain

function L1_CHAIN_ID() external view returns (uint256);

originChainId

Returns the chain ID of the origin chain for a given asset ID

function originChainId(bytes32 assetId) external view returns (uint256);

registerToken

Registers tokens within the NTV.

Allows the bridge to register a token address for the vault.

No access control is ok, since the bridging of tokens should be permissionless. This requires permissionless registration.

The goal is to allow bridging native tokens automatically, by registering them on the fly.

function registerToken(address _l1Token) external;

ensureTokenIsRegistered

Ensures that the native token is registered with the NTV.

This function is used to ensure that the token is registered with the NTV.

function ensureTokenIsRegistered(address _nativeToken)
  external
  returns (bytes32);

getERC20Getters

Used to get the the ERC20 data for a token

function getERC20Getters(address _token, uint256 _originChainId)
  external
  view
  returns (bytes memory);

tokenAddress

Used to get the token address of an assetId

function tokenAddress(bytes32 assetId) external view returns (address);

assetId

Used to get the assetId of a token

function assetId(address token) external view returns (bytes32);

calculateCreate2TokenAddress

Used to get the expected bridged token address corresponding to its native counterpart

function calculateCreate2TokenAddress(
  uint256 _originChainId,
  address _originToken
) external view returns (address);

tryRegisterTokenFromBurnData

Tries to register a token from the provided _burnData and reverts if it is not possible.

function tryRegisterTokenFromBurnData(
  bytes calldata _burnData,
  bytes32 _expectedAssetId
) external;

Events

BridgedTokenBeaconUpdated

event BridgedTokenBeaconUpdated(
  address bridgedTokenBeacon, bytes32 bridgedTokenProxyBytecodeHash
);

Bridge Errors

EthTransferFailed

Git Source

error EthTransferFailed();

NativeTokenVaultAlreadySet

Git Source

error NativeTokenVaultAlreadySet();

WrongMsgLength

Git Source

error WrongMsgLength(uint256 expected, uint256 length);

ZeroAmountToTransfer

Git Source

error ZeroAmountToTransfer();

WrongAmountTransferred

Git Source

error WrongAmountTransferred(uint256 balance, uint256 nullifierChainBalance);

EmptyToken

Git Source

error EmptyToken();

ClaimFailedDepositFailed

Git Source

error ClaimFailedDepositFailed();

WrongL2Sender

Git Source

error WrongL2Sender(address providedL2Sender);

WrongCounterpart

Git Source

error WrongCounterpart();

Contents

• L2TransactionRequestDirect
• L2TransactionRequestTwoBridgesOuter
• L2TransactionRequestTwoBridgesInner
• BridgehubMintCTMAssetData
• BridgehubBurnCTMAssetData
• IBridgehub
• ICTMDeploymentTracker
• IChainAssetHandler
• IMessageRoot
• AlreadyCurrentSL
• ChainExists
• ChainIdAlreadyPresent
• ChainNotLegacy
• ChainNotPresentInCTM
• HyperchainNotRegistered
• IncorrectChainAssetId
• IncorrectSender
• MessageRootNotRegistered
• NoEthAllowed
• NotAssetRouter
• NotChainAssetHandler
• NotCurrentSL
• NotInGatewayMode
• NotL1
• NotOwner
• NotOwnerViaRouter
• NotRelayedSender
• OnlyBridgehub
• OnlyBridgehubOrChainAssetHandler
• OnlyChain
• SecondBridgeAddressTooLow
• SLNotWhitelisted
• WrongCounterPart

IBridgehub

Git Source

Author: Matter Labs

Note: security-contact: security@matterlabs.dev

Functions

setPendingAdmin

Starts the transfer of admin rights. Only the current admin or owner can propose a new pending one.

New admin can accept admin rights by calling acceptAdmin function.

function setPendingAdmin(address _newPendingAdmin) external;

Parameters

acceptAdmin

Accepts transfer of admin rights. Only pending admin can accept the role.

function acceptAdmin() external;

chainTypeManagerIsRegistered

Getters

function chainTypeManagerIsRegistered(address _chainTypeManager)
  external
  view
  returns (bool);

chainTypeManager

function chainTypeManager(uint256 _chainId) external view returns (address);

assetIdIsRegistered

function assetIdIsRegistered(bytes32 _baseTokenAssetId)
  external
  view
  returns (bool);

baseToken

function baseToken(uint256 _chainId) external view returns (address);

baseTokenAssetId

function baseTokenAssetId(uint256 _chainId) external view returns (bytes32);

messageRoot

function messageRoot() external view returns (IMessageRoot);

getZKChain

function getZKChain(uint256 _chainId) external view returns (address);

getAllZKChains

function getAllZKChains() external view returns (address[] memory);

getAllZKChainChainIDs

function getAllZKChainChainIDs() external view returns (uint256[] memory);

migrationPaused

function migrationPaused() external view returns (bool);

admin

function admin() external view returns (address);

assetRouter

function assetRouter() external view returns (address);

proveL2MessageInclusion

Mailbox forwarder

function proveL2MessageInclusion(
  uint256 _chainId,
  uint256 _batchNumber,
  uint256 _index,
  L2Message calldata _message,
  bytes32[] calldata _proof
) external view returns (bool);

proveL2LogInclusion

function proveL2LogInclusion(
  uint256 _chainId,
  uint256 _batchNumber,
  uint256 _index,
  L2Log memory _log,
  bytes32[] calldata _proof
) external view returns (bool);

proveL1ToL2TransactionStatus

function proveL1ToL2TransactionStatus(
  uint256 _chainId,
  bytes32 _l2TxHash,
  uint256 _l2BatchNumber,
  uint256 _l2MessageIndex,
  uint16 _l2TxNumberInBatch,
  bytes32[] calldata _merkleProof,
  TxStatus _status
) external view returns (bool);

requestL2TransactionDirect

function requestL2TransactionDirect(
  L2TransactionRequestDirect calldata _request
) external payable returns (bytes32 canonicalTxHash);

requestL2TransactionTwoBridges

function requestL2TransactionTwoBridges(
  L2TransactionRequestTwoBridgesOuter calldata _request
) external payable returns (bytes32 canonicalTxHash);

l2TransactionBaseCost

function l2TransactionBaseCost(
  uint256 _chainId,
  uint256 _gasPrice,
  uint256 _l2GasLimit,
  uint256 _l2GasPerPubdataByteLimit
) external view returns (uint256);

createNewChain

function createNewChain(
  uint256 _chainId,
  address _chainTypeManager,
  bytes32 _baseTokenAssetId,
  uint256 _salt,
  address _admin,
  bytes calldata _initData,
  bytes[] calldata _factoryDeps
) external returns (uint256 chainId);

addChainTypeManager

function addChainTypeManager(address _chainTypeManager) external;

removeChainTypeManager

function removeChainTypeManager(address _chainTypeManager) external;

addTokenAssetId

function addTokenAssetId(bytes32 _baseTokenAssetId) external;

setAddresses

function setAddresses(
  address _sharedBridge,
  ICTMDeploymentTracker _l1CtmDeployer,
  IMessageRoot _messageRoot,
  address _chainAssetHandler
) external;

setChainAssetHandler

function setChainAssetHandler(address _chainAssetHandler) external;

whitelistedSettlementLayers

function whitelistedSettlementLayers(uint256 _chainId)
  external
  view
  returns (bool);

registerSettlementLayer

function registerSettlementLayer(
  uint256 _newSettlementLayerChainId,
  bool _isWhitelisted
) external;

settlementLayer

function settlementLayer(uint256 _chainId) external view returns (uint256);

forwardTransactionOnGateway

function forwardTransactionOnGateway(
  uint256 _chainId,
  bytes32 _canonicalTxHash,
  uint64 _expirationTimestamp
) external;

ctmAssetIdFromChainId

function ctmAssetIdFromChainId(uint256 _chainId)
  external
  view
  returns (bytes32);

ctmAssetIdFromAddress

function ctmAssetIdFromAddress(address _ctmAddress)
  external
  view
  returns (bytes32);

l1CtmDeployer

function l1CtmDeployer() external view returns (ICTMDeploymentTracker);

ctmAssetIdToAddress

function ctmAssetIdToAddress(bytes32 _assetInfo)
  external
  view
  returns (address);

setCTMAssetAddress

function setCTMAssetAddress(bytes32 _additionalData, address _assetAddress)
  external;

L1_CHAIN_ID

function L1_CHAIN_ID() external view returns (uint256);

chainAssetHandler

function chainAssetHandler() external view returns (address);

registerAlreadyDeployedZKChain

function registerAlreadyDeployedZKChain(uint256 _chainId, address _hyperchain)
  external;

registerLegacyChain

function registerLegacyChain(uint256 _chainId) external;

pauseMigration

function pauseMigration() external;

unpauseMigration

function unpauseMigration() external;

forwardedBridgeBurnSetSettlementLayer

function forwardedBridgeBurnSetSettlementLayer(
  uint256 _chainId,
  uint256 _newSettlementLayerChainId
) external returns (address zkChain, address ctm);

forwardedBridgeMint

function forwardedBridgeMint(
  bytes32 _assetId,
  uint256 _chainId,
  bytes32 _baseTokenAssetId
) external returns (address zkChain, address ctm);

registerNewZKChain

function registerNewZKChain(
  uint256 _chainId,
  address _zkChain,
  bool _checkMaxNumberOfZKChains
) external;

forwardedBridgeRecoverFailedTransfer

function forwardedBridgeRecoverFailedTransfer(uint256 _chainId)
  external
  returns (address zkChain, address ctm);

Events

NewPendingAdmin

pendingAdmin is changed

Also emitted when new admin is accepted and in this case, newPendingAdmin would be zero address

event NewPendingAdmin(
  address indexed oldPendingAdmin, address indexed newPendingAdmin
);

NewAdmin

Admin changed

event NewAdmin(address indexed oldAdmin, address indexed newAdmin);

AssetRegistered

CTM asset registered

event AssetRegistered(
  bytes32 indexed assetInfo,
  address indexed _assetAddress,
  bytes32 indexed additionalData,
  address sender
);

SettlementLayerRegistered

event SettlementLayerRegistered(
  uint256 indexed chainId, bool indexed isWhitelisted
);

NewChain

event NewChain(
  uint256 indexed chainId,
  address chainTypeManager,
  address indexed chainGovernance
);

ChainTypeManagerAdded

event ChainTypeManagerAdded(address indexed chainTypeManager);

ChainTypeManagerRemoved

event ChainTypeManagerRemoved(address indexed chainTypeManager);

BaseTokenAssetIdRegistered

event BaseTokenAssetIdRegistered(bytes32 indexed assetId);

ICTMDeploymentTracker

Git Source

Inherits: IL1AssetDeploymentTracker

Author: Matter Labs

Note: security-contact: security@matterlabs.dev

Functions

bridgehubDeposit

function bridgehubDeposit(
  uint256 _chainId,
  address _originalCaller,
  uint256 _l2Value,
  bytes calldata _data
) external payable returns (L2TransactionRequestTwoBridgesInner memory request);

BRIDGE_HUB

function BRIDGE_HUB() external view returns (IBridgehub);

L1_ASSET_ROUTER

function L1_ASSET_ROUTER() external view returns (IAssetRouterBase);

registerCTMAssetOnL1

function registerCTMAssetOnL1(address _ctmAddress) external;

calculateAssetId

function calculateAssetId(address _l1CTM) external view returns (bytes32);

IMessageRoot

Git Source

Author: Matter Labs

MessageRoot contract is responsible for storing and aggregating the roots of the batches from different chains into the MessageRoot.

Note: security-contact: security@matterlabs.dev

Functions

BRIDGE_HUB

function BRIDGE_HUB() external view returns (IBridgehub);

addNewChain

function addNewChain(uint256 _chainId) external;

addChainBatchRoot

function addChainBatchRoot(
  uint256 _chainId,
  uint256 _batchNumber,
  bytes32 _chainBatchRoot
) external;

historicalRoot

function historicalRoot(uint256 _blockNumber) external view returns (bytes32);

IChainAssetHandler

Git Source

Inherits: IAssetHandler, IL1AssetHandler

Author: Matter Labs

Note: security-contact: security@matterlabs.dev

Events

MigrationStarted

Emitted when the bridging to the chain is started.

event MigrationStarted(
  uint256 indexed chainId,
  bytes32 indexed assetId,
  uint256 indexed settlementLayerChainId
);

Parameters

MigrationFinalized

Emitted when the bridging to the chain is complete.

event MigrationFinalized(
  uint256 indexed chainId, bytes32 indexed assetId, address indexed zkChain
);

Parameters

Contents

• interfaces
• l2-helpers
• libraries
• PriorityTreeCommitment
• ZKChainCommitment
• Config constants
• AccessToFallbackDenied
• AccessToFunctionDenied
• AddressAlreadySet
• AddressHasNoCode
• AddressMismatch
• AlreadyPermanentRollup
• AlreadyWhitelisted
• AmountMustBeGreaterThanZero
• AssetHandlerDoesNotExist
• AssetHandlerNotRegistered
• AssetIdAlreadyRegistered
• AssetIdMismatch
• AssetIdNotSupported
• AssetRouterAllowanceNotZero
• BaseTokenGasPriceDenominatorNotSet
• BatchHashMismatch
• BatchNotExecuted
• BatchNumberMismatch
• BridgeHubAlreadyRegistered
• BridgeMintNotImplemented
• BurningNativeWETHNotSupported
• BytecodeAlreadyPublished
• CallerNotTimerAdmin
• CallNotAllowed
• CanOnlyProcessOneBatch
• CantExecuteUnprovenBatches
• CantRevertExecutedBatch
• ChainAlreadyLive
• ChainIdAlreadyExists
• ChainIdCantBeCurrentChain
• ChainIdMismatch
• ChainIdNotRegistered
• ChainIdTooBig
• CTMAlreadyRegistered
• CTMNotRegistered
• DeadlineNotYetPassed
• DefaultAdminTransferNotAllowed
• DelegateCallFailed
• DenominatorIsZero
• DeployFailed
• DeployingBridgedTokenForNativeToken
• DepositDoesNotExist
• DepositExists
• DiamondAlreadyFrozen
• DiamondNotFrozen
• EmptyAddress
• EmptyAssetId
• EmptyBytes32
• EmptyData
• EmptyDeposit
• EmptyPrecommitData
• EmptyProofLength
• ETHDepositNotSupported
• FacetExists
• GasPerPubdataMismatch
• GenesisBatchCommitmentZero
• GenesisBatchHashZero
• GenesisIndexStorageZero
• GenesisUpgradeZero
• HashedLogIsDefault
• HashMismatch
• IncorrectBatchBounds
• IncorrectBridgeHubAddress
• IncorrectTokenAddressFromNTV
• InsufficientChainBalance
• InvalidBatchNumber
• InvalidCaller
• InvalidDAForPermanentRollup
• InvalidDelay
• InvalidLogSender
• InvalidMessageRoot
• InvalidNTVBurnData
• InvalidNumberOfBlobs
• InvalidPackedPrecommitmentLength
• InvalidProof
• InvalidProofLengthForFinalNode
• InvalidProtocolVersion
• InvalidPubdataPricingMode
• InvalidSelector
• InvalidSystemLogsLength
• InvalidUpgradeTxn
• L2TimestampTooBig
• L2WithdrawalMessageWrongLength
• LegacyBridgeNotSet
• LegacyBridgeUsesNonNativeToken
• LegacyEncodingUsedForNonL1Token
• LegacyMethodForNonL1Token
• LengthIsNotDivisibleBy32
• LogAlreadyProcessed
• MalformedBytecode
• MerkleIndexOrHeightMismatch
• MerkleIndexOutOfBounds
• MerkleNothingToProve
• MerklePathEmpty
• MerklePathLengthMismatch
• MerklePathOutOfBounds
• MerkleWrongIndex
• MerkleWrongLength
• MigrationPaused
• MigrationsNotPaused
• MissingSystemLogs
• MsgValueMismatch
• MsgValueTooLow
• NewDeadlineExceedsMaxDeadline
• NewDeadlineNotGreaterThanCurrent
• NoCallsProvided
• NoCTMForAssetId
• NoFunctionsForDiamondCut
• NoFundsTransferred
• NoLegacySharedBridge
• NonEmptyCalldata
• NonEmptyMsgValue
• NonIncreasingTimestamp
• NonSequentialBatch
• NonSequentialVersion
• NotAllowed
• NotARestriction
• NotAZKChain
• NotInitializedReentrancyGuard
• NotWhitelisted
• OnlyEraSupported
• OnlySelfAllowed
• OperationExists
• OperationMustBePending
• OperationMustBeReady
• OriginChainIdNotFound
• PrecommitmentMismatch
• PreviousOperationNotExecuted
• PriorityOperationsRollingHashMismatch
• PriorityTxPubdataExceedsMaxPubDataPerBatch
• ProtocolIdMismatch
• ProtocolIdNotGreater
• PubdataGreaterThanLimit
• QueueIsEmpty
• Reentrancy
• RemoveFunctionFacetAddressNotZero
• RemoveFunctionFacetAddressZero
• RemovingPermanentRestriction
• ReplaceFunctionFacetAddressZero
• RestrictionWasAlreadyPresent
• RestrictionWasNotPresent
• RevertedBatchNotAfterNewLastBatch
• RoleAccessDenied
• SelectorsMustAllHaveSameFreezability
• SettlementLayersMustSettleOnL1
• SharedBridgeNotSet
• SharedBridgeValueNotSet
• SlotOccupied
• SystemLogsSizeTooBig
• TimeNotReached
• TimerAlreadyStarted
• TimestampError
• TokenIsLegacy
• TokenNotLegacy
• TokenNotSupported
• TokensWithFeesNotSupported
• TooHighDeploymentNonce
• TooManyFactoryDeps
• TooMuchGas
• TransactionNotAllowed
• TxHashMismatch
• TxnBodyGasLimitNotEnoughGas
• UnallowedImplementation
• Unauthorized
• UndefinedDiamondCutAction
• UnexpectedSystemLog
• UnknownVerifierType
• UnsupportedCommitBatchEncoding
• UnsupportedEncodingVersion
• UnsupportedExecuteBatchEncoding
• UnsupportedProofBatchEncoding
• UpgradeBatchNumberIsNotZero
• ValidateTxnNotEnoughGas
• ValueMismatch
• VerifiedBatchesExceedsCommittedBatches
• WithdrawalAlreadyFinalized
• WithdrawFailed
• WrappedBaseTokenAlreadyRegistered
• WrongMagicValue
• ZeroAddress
• ZeroChainId
• ZKChainLimitReached
• SharedBridgeKey
• BytecodeError
• UpgradeTxVerifyParam
• TxStatus
• L2Log
• L2Message
• WritePriorityOpParams
• L2CanonicalTransaction
• BridgehubL2TransactionRequest
• InteropRoot

IL2ContractDeployer

Git Source

Author: Matter Labs

System smart contract that is responsible for deploying other smart contracts on a ZK chain.

Functions

allowedBytecodeTypesToDeploy

Returns what types of bytecode are allowed to be deployed on this chain

function allowedBytecodeTypesToDeploy()
  external
  view
  returns (AllowedBytecodeTypes mode);

forceDeployOnAddresses

This method is to be used only during an upgrade to set bytecodes on specific addresses.

function forceDeployOnAddresses(ForceDeployment[] calldata _deployParams)
  external;

create2

Deploys a contract with similar address derivation rules to the EVM's CREATE2 opcode.

function create2(bytes32 _salt, bytes32 _bytecodeHash, bytes calldata _input)
  external;

Parameters

setAllowedBytecodeTypesToDeploy

Changes what types of bytecodes are allowed to be deployed on the chain.

function setAllowedBytecodeTypesToDeploy(
  AllowedBytecodeTypes newAllowedBytecodeTypes
) external;

Parameters

Structs

ForceDeployment

A struct that describes a forced deployment on an address.

struct ForceDeployment {
  bytes32 bytecodeHash;
  address newAddress;
  bool callConstructor;
  uint256 value;
  bytes input;
}

Properties

IL2InteropRootStorage

Git Source

Author: Matter Labs

The interface of the L2 InteropRootStorage contract, responsible for storing the message roots of other chains on the L2.

Note: security-contact: security@matterlabs.dev

Functions

interopRoots

Mapping of chain ID to block or batch number to message root.

function interopRoots(uint256 chainId, uint256 blockOrBatchNumber)
  external
  view
  returns (bytes32);

IOwnable

Git Source

Author: Matter Labs

Note: security-contact: security@matterlabs.dev

Functions

owner

function owner() external view returns (address);

transferOwnership

function transferOwnership(address newOwner) external;

pendingOwner

function pendingOwner() external view returns (address);

acceptOwnership

function acceptOwnership() external;

L2Helpers

IL2ToL1Messenger

Git Source

Author: Matter Labs

The interface of the L1 Messenger contract, responsible for sending messages to L1.

by default ZkSync can send fixed-length messages on L1. A fixed length message has 4 parameters senderAddress, isService, key, value, the first one is taken from the context, the other three are chosen by the sender.

*To send a variable-length message we use this trick:

• This system contract accepts an arbitrary length message and sends a fixed length message with parameters senderAddress == this, isService == true, key == msg.sender, value == keccak256(message).
• The contract on L1 accepts all sent messages and if the message came from this system contract it requires the preimage of value to be provided.*

Note: security-contact: security@matterlabs.dev

Functions

sendToL1

Sends an arbitrary length message to L1.

function sendToL1(bytes calldata _message) external returns (bytes32);

Parameters

Returns

sendL2ToL1Log

Sends L2ToL1Log.

Can be called only by a system contract.

function sendL2ToL1Log(bool _isService, bytes32 _key, bytes32 _value)
  external
  returns (uint256 logIdInMerkleTree);

Parameters

requestBytecodeL1Publication

This function is expected to be called only by the KnownCodesStorage system contract

function requestBytecodeL1Publication(bytes32 _bytecodeHash) external;

Events

L1MessageSent

event L1MessageSent(
  address indexed _sender, bytes32 indexed _hash, bytes _message
);

L2ContractAddresses

L2ContractHelper

Git Source

Author: Matter Labs

Helper library for working with L2 contracts on L1.

Note: security-contact: security@matterlabs.dev

State Variables

CREATE2_PREFIX

The prefix used to create CREATE2 addresses.

bytes32 private constant CREATE2_PREFIX = keccak256("zksyncCreate2");

CREATE_PREFIX

Prefix used during derivation of account addresses using CREATE

keccak256("zksyncCreate")

bytes32 private constant CREATE_PREFIX =
  0x63bae3a9951d38e8a3fbb7b70909afc1200610fc5bc55ade242f815974674f23;

Functions

sendMessageToL1

Sends L2 -> L1 arbitrary-long message through the system contract messenger.

function sendMessageToL1(bytes memory _message) internal returns (bytes32);

Parameters

Returns

hashL2Bytecode

Validate the bytecode format and calculate its hash.

function hashL2Bytecode(bytes memory _bytecode)
  internal
  pure
  returns (bytes32 hashedBytecode);

Parameters

Returns

hashL2BytecodeCalldata

Validate the bytecode format and calculate its hash.

function hashL2BytecodeCalldata(bytes calldata _bytecode)
  internal
  pure
  returns (bytes32 hashedBytecode);

Parameters

Returns

validateBytecodeHash

Validates the format of the given bytecode hash.

Due to the specification of the L2 bytecode hash, not every 32 bytes could be a legit bytecode hash.

The function reverts on invalid bytecode hash format.

function validateBytecodeHash(bytes32 _bytecodeHash) internal pure;

Parameters

bytecodeLen

Returns the length of the bytecode associated with the given hash.

function bytecodeLen(bytes32 _bytecodeHash)
  internal
  pure
  returns (uint256 codeLengthInWords);

Parameters

Returns

computeCreate2Address

Computes the create2 address for a Layer 2 contract.

function computeCreate2Address(
  address _sender,
  bytes32 _salt,
  bytes32 _bytecodeHash,
  bytes32 _constructorInputHash
) internal pure returns (address);

Parameters

Returns

computeCreateAddress

Calculates the address of a deployed contract via create

function computeCreateAddress(address _sender, uint256 _senderNonce)
  internal
  pure
  returns (address);

Parameters

hashFactoryDeps

Hashes the L2 bytecodes and returns them in the format in which they are processed by the bootloader

function hashFactoryDeps(bytes[] memory _factoryDeps)
  internal
  pure
  returns (uint256[] memory hashedFactoryDeps);

Contents

• restriction
• Call
• IAccessControlRestriction
• IChainAdmin
• IChainAdminOwnable
• IGovernance
• IPermanentRestriction

Contents

• IRestriction
• IRestriction constants
• RestrictionValidator

IRestriction

Git Source

Author: Matter Labs

Note: security-contact: security@matterlabs.dev

Functions

getSupportsRestrictionMagic

A method used to check that the contract supports this interface.

function getSupportsRestrictionMagic() external view returns (bytes32);

Returns

validateCall

Ensures that the invoker has the required role to call the function.

function validateCall(Call calldata _call, address _invoker) external view;

Parameters

Constants

Git Source

RESTRICTION_MAGIC

The magic value that has to be returned by the getSupportsRestrictionMagic

bytes32 constant RESTRICTION_MAGIC = keccak256("Restriction");

IAccessControlRestriction

Git Source

Author: Matter Labs

Note: security-contact: security@matterlabs.dev

Events

RoleSet

Emitted when the required role for a specific function is set.

event RoleSet(
  address indexed target, bytes4 indexed selector, bytes32 requiredRole
);

FallbackRoleSet

Emitted when the required role for a fallback function is set.

event FallbackRoleSet(address indexed target, bytes32 requiredRole);

IChainAdmin

Git Source

Author: Matter Labs

Note: security-contact: security@matterlabs.dev

Functions

getRestrictions

Returns the list of active restrictions.

function getRestrictions() external view returns (address[] memory);

isRestrictionActive

Checks if the restriction is active.

function isRestrictionActive(address _restriction) external view returns (bool);

Parameters

addRestriction

Adds a new restriction to the active restrictions set.

function addRestriction(address _restriction) external;

Parameters

removeRestriction

Removes a restriction from the active restrictions set.

Sometimes restrictions might need to enforce their permanence (e.g. if a chain should be a rollup forever).

function removeRestriction(address _restriction) external;

Parameters

multicall

Execute multiple calls as part of contract administration.

Intended for batch processing of contract interactions, managing gas efficiency and atomicity of operations.

Note, that this function lacks access control. It is expected that the access control is implemented in a separate restriction contract.

Even though all the validation from external modules is executed via staticcall, the function is marked as nonReentrant to prevent reentrancy attacks in case the staticcall restriction is lifted in the future.

function multicall(Call[] calldata _calls, bool _requireSuccess)
  external
  payable;

Parameters

Events

UpdateUpgradeTimestamp

Emitted when the expected upgrade timestamp for a specific protocol version is set.

event UpdateUpgradeTimestamp(
  uint256 indexed protocolVersion, uint256 upgradeTimestamp
);

CallExecuted

Emitted when the call is executed from the contract.

event CallExecuted(Call call, bool success, bytes returnData);

RestrictionAdded

Emitted when a new restriction is added.

event RestrictionAdded(address indexed restriction);

RestrictionRemoved

Emitted when a restriction is removed.

event RestrictionRemoved(address indexed restriction);

EnableEvmEmulator

The EVM emulator has been enabled

event EnableEvmEmulator();

IChainAdminOwnable

Git Source

Author: Matter Labs

Note: security-contact: security@matterlabs.dev

Functions

setTokenMultiplierSetter

function setTokenMultiplierSetter(address _tokenMultiplierSetter) external;

setUpgradeTimestamp

function setUpgradeTimestamp(
  uint256 _protocolVersion,
  uint256 _upgradeTimestamp
) external;

multicall

function multicall(Call[] calldata _calls, bool _requireSuccess)
  external
  payable;

setTokenMultiplier

function setTokenMultiplier(
  IAdmin _chainContract,
  uint128 _nominator,
  uint128 _denominator
) external;

Events

UpdateUpgradeTimestamp

Emitted when the expected upgrade timestamp for a specific protocol version is set.

event UpdateUpgradeTimestamp(
  uint256 indexed _protocolVersion, uint256 _upgradeTimestamp
);

CallExecuted

Emitted when the call is executed from the contract.

event CallExecuted(Call _call, bool _success, bytes _returnData);

NewTokenMultiplierSetter

Emitted when the new token multiplier address is set.

event NewTokenMultiplierSetter(
  address _oldTokenMultiplierSetter, address _newTokenMultiplierSetter
);

Structs

Call

Represents a call to be made during multicall.

struct Call {
  address target;
  uint256 value;
  bytes data;
}

Properties

IGovernance

Git Source

Author: Matter Labs

Note: security-contact: security@matterlabs.dev

Functions

isOperation

function isOperation(bytes32 _id) external view returns (bool);

isOperationPending

function isOperationPending(bytes32 _id) external view returns (bool);

isOperationReady

function isOperationReady(bytes32 _id) external view returns (bool);

isOperationDone

function isOperationDone(bytes32 _id) external view returns (bool);

getOperationState

function getOperationState(bytes32 _id) external view returns (OperationState);

scheduleTransparent

function scheduleTransparent(Operation calldata _operation, uint256 _delay)
  external;

scheduleShadow

function scheduleShadow(bytes32 _id, uint256 _delay) external;

cancel

function cancel(bytes32 _id) external;

execute

function execute(Operation calldata _operation) external payable;

executeInstant

function executeInstant(Operation calldata _operation) external payable;

hashOperation

function hashOperation(Operation calldata _operation)
  external
  pure
  returns (bytes32);

updateDelay

function updateDelay(uint256 _newDelay) external;

updateSecurityCouncil

function updateSecurityCouncil(address _newSecurityCouncil) external;

Events

TransparentOperationScheduled

Emitted when transparent operation is scheduled.

event TransparentOperationScheduled(
  bytes32 indexed _id, uint256 delay, Operation _operation
);

ShadowOperationScheduled

Emitted when shadow operation is scheduled.

event ShadowOperationScheduled(bytes32 indexed _id, uint256 delay);

OperationExecuted

Emitted when the operation is executed with delay or instantly.

event OperationExecuted(bytes32 indexed _id);

ChangeSecurityCouncil

Emitted when the security council address is changed.

event ChangeSecurityCouncil(
  address _securityCouncilBefore, address _securityCouncilAfter
);

ChangeMinDelay

Emitted when the minimum delay for future operations is modified.

event ChangeMinDelay(uint256 _delayBefore, uint256 _delayAfter);

OperationCancelled

Emitted when the operation with specified id is cancelled.

event OperationCancelled(bytes32 indexed _id);

Structs

Operation

Defines the structure of an operation that Governance executes.

struct Operation {
  Call[] calls;
  bytes32 predecessor;
  bytes32 salt;
}

Properties

Enums

OperationState

This enumeration includes the following states:

enum OperationState {
  Unset,
  Waiting,
  Ready,
  Done
}

IPermanentRestriction

Git Source

Author: Matter Labs

The interface for the permanent restriction contract.

Note: security-contact: security@matterlabs.dev

Events

AdminImplementationAllowed

Emitted when the implementation is allowed or disallowed.

event AdminImplementationAllowed(
  bytes32 indexed implementationHash, bool isAllowed
);

AllowedDataChanged

Emitted when a certain calldata is allowed or disallowed.

event AllowedDataChanged(bytes data, bool isAllowed);

SelectorValidationChanged

Emitted when the selector is labeled as validated or not.

event SelectorValidationChanged(bytes4 indexed selector, bool isValidated);

AllowL2Admin

Emitted when the L2 admin is whitelisted or not.

event AllowL2Admin(address indexed adminAddress);

Contents

• chain-deps
• chain-interfaces
• l2-deps
• libraries
• ChainTypeManagerInitializeData
• ChainCreationParams
• IChainTypeManager
• IValidatorTimelock
• AdminZero
• AlreadyMigrated
• BlobHashBlobCommitmentMismatchValue
• CommitBasedInteropNotSupported
• ContractNotDeployed
• DependencyRootsRollingHashMismatch
• ExecutedIsNotConsistentWithVerified
• InitialForceDeploymentMismatch
• InvalidBatchesDataLength
• InvalidChainId
• InvalidCommitment
• InvalidL2DAOutputHash
• InvalidNextLeafIndex
• InvalidNumberOfBatchHashes
• InvalidNumberOfBlobs
• InvalidPubdataHash
• InvalidPubdataSource
• InvalidStartIndex
• InvalidUnprocessedIndex
• L1DAValidatorAddressIsZero
• L1DAValidatorInvalidSender
• L2DAValidatorAddressIsZero
• LocalRootIsZero
• LocalRootMustBeZero
• MessageRootIsZero
• MismatchL2DAValidator
• MismatchNumberOfLayer1Txs
• NotAllBatchesExecuted
• NotChainAdmin
• NotHistoricalRoot
• NotHyperchain
• NotL1
• NotMigrated
• NotSettlementLayer
• OnlyOneBlobWithCalldataAllowed
• OperatorDAInputTooSmall
• OutdatedProtocolVersion
• ProtocolVersionNotUpToDate
• PubdataInputTooSmall
• PubdataLengthTooBig
• UnsupportedProofMetadataVersion
• ValL1DAWrongInputLength
• VerifiedIsNotConsistentWithCommitted

IValidatorTimelock

Git Source

Inherits: IExecutor

Author: Matter Labs

Note: security-contact: security@matterlabs.dev

Functions

PRECOMMITTER_ROLE

Role hash for addresses allowed to precommit batches on a chain.

function PRECOMMITTER_ROLE() external view returns (bytes32);

COMMITTER_ROLE

Role hash for addresses allowed to commit batches on a chain.

function COMMITTER_ROLE() external view returns (bytes32);

REVERTER_ROLE

Role hash for addresses allowed to revert batches on a chain.

function REVERTER_ROLE() external view returns (bytes32);

PROVER_ROLE

Role hash for addresses allowed to prove batches on a chain.

function PROVER_ROLE() external view returns (bytes32);

EXECUTOR_ROLE

Role hash for addresses allowed to execute batches on a chain.

function EXECUTOR_ROLE() external view returns (bytes32);

OPTIONAL_PRECOMMITTER_ADMIN_ROLE

Optional admin role hash for managing PRECOMMITTER_ROLE assignments.

Note, that it is optional, meaning that by default the admin role is held by the chain admin

function OPTIONAL_PRECOMMITTER_ADMIN_ROLE() external view returns (bytes32);

OPTIONAL_COMMITTER_ADMIN_ROLE

Optional admin role hash for managing COMMITTER_ROLE assignments.

Note, that it is optional, meaning that by default the admin role is held by the chain admin

function OPTIONAL_COMMITTER_ADMIN_ROLE() external view returns (bytes32);

OPTIONAL_REVERTER_ADMIN_ROLE

Optional admin role hash for managing REVERTER_ROLE assignments.

Note, that it is optional, meaning that by default the admin role is held by the chain admin

function OPTIONAL_REVERTER_ADMIN_ROLE() external view returns (bytes32);

OPTIONAL_PROVER_ADMIN_ROLE

Optional admin role hash for managing PROVER_ROLE assignments.

Note, that it is optional, meaning that by default the admin role is held by the chain admin

function OPTIONAL_PROVER_ADMIN_ROLE() external view returns (bytes32);

OPTIONAL_EXECUTOR_ADMIN_ROLE

Optional admin role hash for managing EXECUTOR_ROLE assignments.

Note, that it is optional, meaning that by default the admin role is held by the chain admin

function OPTIONAL_EXECUTOR_ADMIN_ROLE() external view returns (bytes32);

BRIDGE_HUB

The address of the bridgehub

function BRIDGE_HUB() external view returns (IBridgehub);

executionDelay

The delay between committing and executing batches.

function executionDelay() external view returns (uint32);

getName

Part of the IBase interface. Not used in this contract.

function getName() external pure returns (string memory);

initialize

Initializer for the contract.

Expected to be delegatecalled in the constructor of the TransparentUpgradeableProxy

function initialize(address _initialOwner, uint32 _initialExecutionDelay)
  external;

Parameters

setExecutionDelay

Set the delay between committing and executing batches.

function setExecutionDelay(uint32 _executionDelay) external;

getCommittedBatchTimestamp

Returns the timestamp when _l2BatchNumber was committed.

function getCommittedBatchTimestamp(
  address _chainAddress,
  uint256 _l2BatchNumber
) external view returns (uint256);

removeValidatorRoles

Revokes the specified validator roles for a given validator on the target chain.

Note that the access control is managed by the inner revokeRole functions.

function removeValidatorRoles(
  address _chainAddress,
  address _validator,
  ValidatorRotationParams memory params
) external;

Parameters

removeValidator

Convenience wrapper to revoke all validator roles for a given validator on the target chain.

function removeValidator(address _chainAddress, address _validator) external;

Parameters

removeValidatorForChainId

Convenience wrapper to revoke all validator roles for a given validator on the target chain.

function removeValidatorForChainId(uint256 _chainId, address _validator)
  external;

Parameters

addValidatorRoles

Grants the specified validator roles for a given validator on the target chain.

function addValidatorRoles(
  address _chainAddress,
  address _validator,
  ValidatorRotationParams memory params
) external;

Parameters

addValidator

Convenience wrapper to grant all validator roles for a given validator on the target chain.

function addValidator(address _chainAddress, address _validator) external;

Parameters

addValidatorForChainId

Convenience wrapper to grant all validator roles for a given validator on the target chain.

function addValidatorForChainId(uint256 _chainId, address _validator) external;

Parameters

hasRoleForChainId

Convenience wrapper to retrieve whether a certain address has a role for a chain.

function hasRoleForChainId(uint256 _chainId, bytes32 _role, address _address)
  external
  view
  returns (bool);

Parameters

precommitSharedBridge

Make a call to the zkChain diamond contract with the same calldata.

function precommitSharedBridge(
  address _chainAddress,
  uint256 _l2BlockNumber,
  bytes calldata _l2Block
) external;

commitBatchesSharedBridge

Records the timestamp for all provided committed batches and make a call to the zkChain diamond contract with the same calldata.

function commitBatchesSharedBridge(
  address _chainAddress,
  uint256 _processBatchFrom,
  uint256 _processBatchTo,
  bytes calldata _batchData
) external;

revertBatchesSharedBridge

Make a call to the zkChain diamond contract with the same calldata. Note: If the batch is reverted, it needs to be committed first before the execution. So it's safe to not override the committed batches.

function revertBatchesSharedBridge(address _chainAddress, uint256 _newLastBatch)
  external;

proveBatchesSharedBridge

Make a call to the zkChain diamond contract with the same calldata. Note: We don't track the time when batches are proven, since all information about the batch is known on the commit stage and the proved is not finalized (may be reverted).

function proveBatchesSharedBridge(
  address _chainAddress,
  uint256 _processBatchFrom,
  uint256 _processBatchTo,
  bytes calldata _proofData
) external;

executeBatchesSharedBridge

Check that batches were committed at least X time ago and make a call to the zkChain diamond contract with the same calldata.

function executeBatchesSharedBridge(
  address _chainAddress,
  uint256 _processBatchFrom,
  uint256 _processBatchTo,
  bytes calldata _batchData
) external;

Events

NewExecutionDelay

The delay between committing and executing batches is changed.

event NewExecutionDelay(uint256 _newExecutionDelay);

Structs

ValidatorRotationParams

Struct specifying which validator roles to grant or revoke in a single call.

struct ValidatorRotationParams {
  bool rotatePrecommitterRole;
  bool rotateCommitterRole;
  bool rotateReverterRole;
  bool rotateProverRole;
  bool rotateExecutorRole;
}

Properties

IChainTypeManager

Git Source

Functions

BRIDGE_HUB

function BRIDGE_HUB() external view returns (address);

setPendingAdmin

function setPendingAdmin(address _newPendingAdmin) external;

acceptAdmin

function acceptAdmin() external;

getZKChain

function getZKChain(uint256 _chainId) external view returns (address);

getHyperchain

function getHyperchain(uint256 _chainId) external view returns (address);

getZKChainLegacy

function getZKChainLegacy(uint256 _chainId) external view returns (address);

storedBatchZero

function storedBatchZero() external view returns (bytes32);

initialCutHash

function initialCutHash() external view returns (bytes32);

l1GenesisUpgrade

function l1GenesisUpgrade() external view returns (address);

upgradeCutHash

function upgradeCutHash(uint256 _protocolVersion)
  external
  view
  returns (bytes32);

protocolVersion

function protocolVersion() external view returns (uint256);

protocolVersionDeadline

function protocolVersionDeadline(uint256 _protocolVersion)
  external
  view
  returns (uint256);

protocolVersionIsActive

function protocolVersionIsActive(uint256 _protocolVersion)
  external
  view
  returns (bool);

getProtocolVersion

function getProtocolVersion(uint256 _chainId) external view returns (uint256);

initialize

function initialize(ChainTypeManagerInitializeData calldata _initializeData)
  external;

setLegacyValidatorTimelock

function setLegacyValidatorTimelock(address _validatorTimelock) external;

setValidatorTimelockPostV29

function setValidatorTimelockPostV29(address _validatorTimelockPostV29)
  external;

setChainCreationParams

function setChainCreationParams(
  ChainCreationParams calldata _chainCreationParams
) external;

getChainAdmin

function getChainAdmin(uint256 _chainId) external view returns (address);

createNewChain

function createNewChain(
  uint256 _chainId,
  bytes32 _baseTokenAssetId,
  address _admin,
  bytes calldata _initData,
  bytes[] calldata _factoryDeps
) external returns (address);

setNewVersionUpgrade

function setNewVersionUpgrade(
  Diamond.DiamondCutData calldata _cutData,
  uint256 _oldProtocolVersion,
  uint256 _oldProtocolVersionDeadline,
  uint256 _newProtocolVersion
) external;

setUpgradeDiamondCut

function setUpgradeDiamondCut(
  Diamond.DiamondCutData calldata _cutData,
  uint256 _oldProtocolVersion
) external;

executeUpgrade

function executeUpgrade(
  uint256 _chainId,
  Diamond.DiamondCutData calldata _diamondCut
) external;

setPriorityTxMaxGasLimit

function setPriorityTxMaxGasLimit(uint256 _chainId, uint256 _maxGasLimit)
  external;

freezeChain

function freezeChain(uint256 _chainId) external;

unfreezeChain

function unfreezeChain(uint256 _chainId) external;

setTokenMultiplier

function setTokenMultiplier(
  uint256 _chainId,
  uint128 _nominator,
  uint128 _denominator
) external;

changeFeeParams

function changeFeeParams(uint256 _chainId, FeeParams calldata _newFeeParams)
  external;

setValidator

function setValidator(uint256 _chainId, address _validator, bool _active)
  external;

setPorterAvailability

function setPorterAvailability(uint256 _chainId, bool _zkPorterIsAvailable)
  external;

upgradeChainFromVersion

function upgradeChainFromVersion(
  uint256 _chainId,
  uint256 _oldProtocolVersion,
  Diamond.DiamondCutData calldata _diamondCut
) external;

getSemverProtocolVersion

function getSemverProtocolVersion()
  external
  view
  returns (uint32, uint32, uint32);

forwardedBridgeBurn

function forwardedBridgeBurn(uint256 _chainId, bytes calldata _data)
  external
  returns (bytes memory _bridgeMintData);

forwardedBridgeMint

function forwardedBridgeMint(uint256 _chainId, bytes calldata _data)
  external
  returns (address);

forwardedBridgeRecoverFailedTransfer

function forwardedBridgeRecoverFailedTransfer(
  uint256 _chainId,
  bytes32 _assetInfo,
  address _depositSender,
  bytes calldata _ctmData
) external;

Events

NewZKChain

Emitted when a new ZKChain is added

event NewZKChain(uint256 indexed _chainId, address indexed _zkChainContract);

GenesisUpgrade

emitted when an chain registers and a GenesisUpgrade happens

event GenesisUpgrade(
  address indexed _zkChain,
  L2CanonicalTransaction _l2Transaction,
  uint256 indexed _protocolVersion
);

NewPendingAdmin

pendingAdmin is changed

Also emitted when new admin is accepted and in this case, newPendingAdmin would be zero address

event NewPendingAdmin(
  address indexed oldPendingAdmin, address indexed newPendingAdmin
);

NewAdmin

Admin changed

event NewAdmin(address indexed oldAdmin, address indexed newAdmin);

NewValidatorTimelock

ValidatorTimelock changed

event NewValidatorTimelock(
  address indexed oldValidatorTimelock, address indexed newValidatorTimelock
);

NewValidatorTimelockPostV29

ValidatorTimelockPostV29 changed

event NewValidatorTimelockPostV29(
  address indexed oldValidatorTimelockPostV29,
  address indexed newvalidatorTimelockPostV29
);

NewServerNotifier

ServerNotifier changed

event NewServerNotifier(
  address indexed oldServerNotifier, address indexed newServerNotifier
);

NewChainCreationParams

chain creation parameters changed

event NewChainCreationParams(
  address genesisUpgrade,
  bytes32 genesisBatchHash,
  uint64 genesisIndexRepeatedStorageChanges,
  bytes32 genesisBatchCommitment,
  Diamond.DiamondCutData newInitialCut,
  bytes32 newInitialCutHash,
  bytes forceDeploymentsData,
  bytes32 forceDeploymentHash
);

NewUpgradeCutHash

New UpgradeCutHash

event NewUpgradeCutHash(
  uint256 indexed protocolVersion, bytes32 indexed upgradeCutHash
);

NewUpgradeCutData

New UpgradeCutData

event NewUpgradeCutData(
  uint256 indexed protocolVersion, Diamond.DiamondCutData diamondCutData
);

NewProtocolVersion

New ProtocolVersion

event NewProtocolVersion(
  uint256 indexed oldProtocolVersion, uint256 indexed newProtocolVersion
);

UpdateProtocolVersionDeadline

Updated ProtocolVersion deadline

event UpdateProtocolVersionDeadline(
  uint256 indexed protocolVersion, uint256 deadline
);

L1StateTransitionErrors

Contents

• IAdmin
• InitializeData
• InitializeDataNewChain
• IDiamondInit
• SystemLogKey
• LogProcessingOutput
• IExecutor
• IExecutor constants
• IGetters
• PubdataSource
• L1DAValidatorOutput
• IL1DAValidator
• ILegacyGetters
• IMailbox
• IMailboxImpl
• IMessageVerification
• ITransactionFilterer
• VerifierParams
• IVerifier
• IVerifierV2
• IZKChain
• IZKChainBase

IAdmin

Git Source

Inherits: IZKChainBase

Author: Matter Labs

Note: security-contact: security@matterlabs.dev

Functions

setPendingAdmin

Starts the transfer of admin rights. Only the current admin can propose a new pending one.

New admin can accept admin rights by calling acceptAdmin function.

function setPendingAdmin(address _newPendingAdmin) external;

Parameters

acceptAdmin

Accepts transfer of admin rights. Only pending admin can accept the role.

function acceptAdmin() external;

setValidator

Change validator status (active or not active)

function setValidator(address _validator, bool _active) external;

Parameters

setPorterAvailability

Change zk porter availability

function setPorterAvailability(bool _zkPorterIsAvailable) external;

Parameters

setPriorityTxMaxGasLimit

Change the max L2 gas limit for L1 -> L2 transactions

function setPriorityTxMaxGasLimit(uint256 _newPriorityTxMaxGasLimit) external;

Parameters

changeFeeParams

Change the fee params for L1->L2 transactions

function changeFeeParams(FeeParams calldata _newFeeParams) external;

Parameters

setTokenMultiplier

Change the token multiplier for L1->L2 transactions

function setTokenMultiplier(uint128 _nominator, uint128 _denominator) external;

setPubdataPricingMode

Change the pubdata pricing mode before the first batch is processed

function setPubdataPricingMode(PubdataPricingMode _pricingMode) external;

Parameters

setTransactionFilterer

Set the transaction filterer

function setTransactionFilterer(address _transactionFilterer) external;

allowEvmEmulation

Allow EVM emulation on chain

function allowEvmEmulation() external returns (bytes32 canonicalTxHash);

upgradeChainFromVersion

Perform the upgrade from the current protocol version with the corresponding upgrade data

function upgradeChainFromVersion(
  uint256 _protocolVersion,
  Diamond.DiamondCutData calldata _cutData
) external;

Parameters

executeUpgrade

Executes a proposed governor upgrade

Only the ChainTypeManager contract can execute the upgrade

function executeUpgrade(Diamond.DiamondCutData calldata _diamondCut) external;

Parameters

freezeDiamond

Instantly pause the functionality of all freezable facets & their selectors

Only the governance mechanism may freeze Diamond Proxy

function freezeDiamond() external;

unfreezeDiamond

Unpause the functionality of all freezable facets & their selectors

Only the CTM can unfreeze Diamond Proxy

function unfreezeDiamond() external;

genesisUpgrade

function genesisUpgrade(
  address _l1GenesisUpgrade,
  address _ctmDeployer,
  bytes calldata _forceDeploymentData,
  bytes[] calldata _factoryDeps
) external;

getRollupDAManager

Returns address of the RollupDAManager of the ZK Chain.

function getRollupDAManager() external view returns (address);

setDAValidatorPair

Set the L1 DA validator address as well as the L2 DA validator address.

While in principle it is possible that updating only one of the addresses is needed, usually these should work in pair and L1 validator typically expects a specific input from the L2 Validator. That's why we change those together to prevent admins of chains from shooting themselves in the foot.

function setDAValidatorPair(address _l1DAValidator, address _l2DAValidator)
  external;

Parameters

makePermanentRollup

Makes the chain as permanent rollup.

This is a security feature needed for chains that should be trusted to keep their data available even if the chain admin becomes malicious and tries to set the DA validator pair to something which does not publish DA to Ethereum.

DANGEROUS: once activated, there is no way back!

function makePermanentRollup() external;

forwardedBridgeBurn

Similar to IL1AssetHandler interface, used to send chains.

function forwardedBridgeBurn(
  address _settlementLayer,
  address _originalCaller,
  bytes calldata _data
) external payable returns (bytes memory _bridgeMintData);

forwardedBridgeRecoverFailedTransfer

Similar to IL1AssetHandler interface, used to claim failed chain transfers.

function forwardedBridgeRecoverFailedTransfer(
  uint256 _chainId,
  bytes32 _assetInfo,
  address _originalCaller,
  bytes calldata _chainData
) external payable;

forwardedBridgeMint

Similar to IL1AssetHandler interface, used to receive chains.

function forwardedBridgeMint(
  bytes calldata _data,
  bool _contractAlreadyDeployed
) external payable;

prepareChainCommitment

function prepareChainCommitment()
  external
  view
  returns (ZKChainCommitment memory commitment);

Events

IsPorterAvailableStatusUpdate

Porter availability status changes

event IsPorterAvailableStatusUpdate(bool isPorterAvailable);

ValidatorStatusUpdate

Validator's status changed

event ValidatorStatusUpdate(address indexed validatorAddress, bool isActive);

NewPendingAdmin

pendingAdmin is changed

Also emitted when new admin is accepted and in this case, newPendingAdmin would be zero address

event NewPendingAdmin(
  address indexed oldPendingAdmin, address indexed newPendingAdmin
);

NewAdmin

Admin changed

event NewAdmin(address indexed oldAdmin, address indexed newAdmin);

NewPriorityTxMaxGasLimit

Priority transaction max L2 gas limit changed

event NewPriorityTxMaxGasLimit(
  uint256 oldPriorityTxMaxGasLimit, uint256 newPriorityTxMaxGasLimit
);

NewFeeParams

Fee params for L1->L2 transactions changed

event NewFeeParams(FeeParams oldFeeParams, FeeParams newFeeParams);

PubdataPricingModeUpdate

Validium mode status changed

event PubdataPricingModeUpdate(PubdataPricingMode validiumMode);

NewTransactionFilterer

The transaction filterer has been updated

event NewTransactionFilterer(
  address oldTransactionFilterer, address newTransactionFilterer
);

NewBaseTokenMultiplier

BaseToken multiplier for L1->L2 transactions changed

event NewBaseTokenMultiplier(
  uint128 oldNominator,
  uint128 oldDenominator,
  uint128 newNominator,
  uint128 newDenominator
);

ExecuteUpgrade

Emitted when an upgrade is executed.

event ExecuteUpgrade(Diamond.DiamondCutData diamondCut);

MigrationComplete

Emitted when the migration to the new settlement layer is complete.

event MigrationComplete();

Freeze

Emitted when the contract is frozen.

event Freeze();

Unfreeze

Emitted when the contract is unfrozen.

event Unfreeze();

EnableEvmEmulator

The EVM emulator has been enabled

event EnableEvmEmulator();

NewL2DAValidator

New pair of DA validators set

event NewL2DAValidator(
  address indexed oldL2DAValidator, address indexed newL2DAValidator
);

NewL1DAValidator

event NewL1DAValidator(
  address indexed oldL1DAValidator, address indexed newL1DAValidator
);

BridgeMint

event BridgeMint(address indexed _account, uint256 _amount);

IDiamondInit

Git Source

Functions

initialize

function initialize(InitializeData calldata _initData)
  external
  returns (bytes32);

IExecutor

Git Source

Inherits: IZKChainBase

Author: Matter Labs

Note: security-contact: security@matterlabs.dev

Functions

precommitSharedBridge

Precommits the status of all L2 transactions for the next batch on the shared bridge.

function precommitSharedBridge(
  address _chainAddress,
  uint256 _batchNumber,
  bytes calldata _precommitData
) external;

Parameters

commitBatchesSharedBridge

Function called by the operator to commit new batches. It is responsible for:

• Verifying the correctness of their timestamps.
• Processing their L2->L1 logs.
• Storing batch commitments.

function commitBatchesSharedBridge(
  address _chainAddress,
  uint256 _processFrom,
  uint256 _processTo,
  bytes calldata _commitData
) external;

Parameters

proveBatchesSharedBridge

Batches commitment verification.

Only verifies batch commitments without any other processing.

function proveBatchesSharedBridge(
  address _chainAddress,
  uint256 _processBatchFrom,
  uint256 _processBatchTo,
  bytes calldata _proofData
) external;

Parameters

executeBatchesSharedBridge

The function called by the operator to finalize (execute) batches. It is responsible for:

• Processing all pending operations (commpleting priority requests).
• Finalizing this batch (i.e. allowing to withdraw funds from the system)

function executeBatchesSharedBridge(
  address _chainAddress,
  uint256 _processFrom,
  uint256 _processTo,
  bytes calldata _executeData
) external;

Parameters

revertBatchesSharedBridge

Reverts unexecuted batches

When the _newLastBatch is equal to the number of committed batches, only the precommitment is erased. NOTE: Doesn't delete the stored data about batches, but only decreases counters that are responsible for the number of batches

function revertBatchesSharedBridge(address _chainAddress, uint256 _newLastBatch)
  external;

Parameters

Events

BlockCommit

Event emitted when a batch is committed

It has the name "BlockCommit" and not "BatchCommit" due to backward compatibility considerations

event BlockCommit(
  uint256 indexed batchNumber,
  bytes32 indexed batchHash,
  bytes32 indexed commitment
);

Parameters

BlocksVerification

Event emitted when batches are verified

It has the name "BlocksVerification" and not "BatchesVerification" due to backward compatibility considerations

event BlocksVerification(
  uint256 indexed previousLastVerifiedBatch,
  uint256 indexed currentLastVerifiedBatch
);

Parameters

BlockExecution

Event emitted when a batch is executed

It has the name "BlockExecution" and not "BatchExecution" due to backward compatibility considerations

event BlockExecution(
  uint256 indexed batchNumber,
  bytes32 indexed batchHash,
  bytes32 indexed commitment
);

Parameters

BlocksRevert

Event emitted when batches are reverted

It has the name "BlocksRevert" and not "BatchesRevert" due to backward compatibility considerations

event BlocksRevert(
  uint256 totalBatchesCommitted,
  uint256 totalBatchesVerified,
  uint256 totalBatchesExecuted
);

Parameters

BatchPrecommitmentSet

Emitted when a new precommitment is set for a batch.

event BatchPrecommitmentSet(
  uint256 indexed batchNumber,
  uint256 indexed untrustedLastL2BlockNumberHint,
  bytes32 precommitment
);

Parameters

Structs

StoredBatchInfo

Rollup batch stored data

struct StoredBatchInfo {
  uint64 batchNumber;
  bytes32 batchHash;
  uint64 indexRepeatedStorageChanges;
  uint256 numberOfLayer1Txs;
  bytes32 priorityOperationsHash;
  bytes32 dependencyRootsRollingHash;
  bytes32 l2LogsTreeRoot;
  uint256 timestamp;
  bytes32 commitment;
}

Properties

LegacyStoredBatchInfo

Legacy StoredBatchInfo struct

dependencyRootsRollingHash is not included in the struct

struct LegacyStoredBatchInfo {
  uint64 batchNumber;
  bytes32 batchHash;
  uint64 indexRepeatedStorageChanges;
  uint256 numberOfLayer1Txs;
  bytes32 priorityOperationsHash;
  bytes32 l2LogsTreeRoot;
  uint256 timestamp;
  bytes32 commitment;
}

CommitBatchInfo

Data needed to commit new batch

pubdataCommitments format: This will always start with a 1 byte pubdataSource flag. Current allowed values are 0 (calldata) or 1 (blobs) kzg: list of: opening point (16 bytes) || claimed value (32 bytes) || commitment (48 bytes) || proof (48 bytes) = 144 bytes calldata: pubdataCommitments.length - 1 - 32 bytes of pubdata and 32 bytes appended to serve as the blob commitment part for the aux output part of the batch commitment

For 2 blobs we will be sending 288 bytes of calldata instead of the full amount for pubdata.

When using calldata, we only need to send one blob commitment since the max number of bytes in calldata fits in a single blob and we can pull the linear hash from the system logs

struct CommitBatchInfo {
  uint64 batchNumber;
  uint64 timestamp;
  uint64 indexRepeatedStorageChanges;
  bytes32 newStateRoot;
  uint256 numberOfLayer1Txs;
  bytes32 priorityOperationsHash;
  bytes32 bootloaderHeapInitialContentsHash;
  bytes32 eventsQueueStateHash;
  bytes systemLogs;
  bytes operatorDAInput;
}

Properties

PrecommitInfo

Container for a list of transaction statuses to precommit.

struct PrecommitInfo {
  bytes packedTxsCommitments;
  uint256 untrustedLastL2BlockNumberHint;
}

Properties

Constants

Git Source

MAX_LOG_KEY

Maximal value that SystemLogKey variable can have.

uint256 constant MAX_LOG_KEY = uint256(type(SystemLogKey).max);

L2_LOG_ADDRESS_OFFSET

Offset used to pull Address From Log. Equal to 4 (bytes for shardId, isService and txNumberInBatch)

uint256 constant L2_LOG_ADDRESS_OFFSET = 4;

L2_LOG_KEY_OFFSET

Offset used to pull Key From Log. Equal to 4 (bytes for shardId, isService and txNumberInBatch) + 20 (bytes for address)

uint256 constant L2_LOG_KEY_OFFSET = 24;

L2_LOG_VALUE_OFFSET

Offset used to pull Value From Log. Equal to 4 (bytes for shardId, isService and txNumberInBatch) + 20 (bytes for address) + 32 (bytes for key)

uint256 constant L2_LOG_VALUE_OFFSET = 56;

MAX_NUMBER_OF_BLOBS

Max number of blobs currently supported

uint256 constant MAX_NUMBER_OF_BLOBS = 6;

TOTAL_BLOBS_IN_COMMITMENT

The number of blobs that must be present in the commitment to a batch. It represents the maximal number of blobs that circuits can support and can be larger than the maximal number of blobs supported by the contract (MAX_NUMBER_OF_BLOBS).

uint256 constant TOTAL_BLOBS_IN_COMMITMENT = 16;

IGetters

Git Source

Inherits: IZKChainBase

Author: Matter Labs

Most of the methods simply return the values that correspond to the current diamond proxy and possibly not to the ZK Chain as a whole. For example, if the chain is migrated to another settlement layer, the values returned by this facet will correspond to the values stored on this chain and possilbly not the canonical state of the chain.

Note: security-contact: security@matterlabs.dev

Functions

getVerifier

function getVerifier() external view returns (address);

Returns

getAdmin

function getAdmin() external view returns (address);

Returns

getPendingAdmin

function getPendingAdmin() external view returns (address);

Returns

getBridgehub

function getBridgehub() external view returns (address);

Returns

getChainTypeManager

function getChainTypeManager() external view returns (address);

Returns

getChainId

function getChainId() external view returns (uint256);

Returns

getBaseToken

function getBaseToken() external view returns (address);

Returns

getBaseTokenAssetId

function getBaseTokenAssetId() external view returns (bytes32);

Returns

getTotalBatchesCommitted

function getTotalBatchesCommitted() external view returns (uint256);

Returns

getTotalBatchesVerified

function getTotalBatchesVerified() external view returns (uint256);

Returns

getTotalBatchesExecuted

function getTotalBatchesExecuted() external view returns (uint256);

Returns

getTransactionFilterer

function getTransactionFilterer() external view returns (address);

getTotalPriorityTxs

function getTotalPriorityTxs() external view returns (uint256);

Returns

getPriorityTreeStartIndex

function getPriorityTreeStartIndex() external view returns (uint256);

Returns

getPriorityTreeRoot

function getPriorityTreeRoot() external view returns (bytes32);

Returns

isPriorityQueueActive

function isPriorityQueueActive() external view returns (bool);

Returns

getFirstUnprocessedPriorityTx

The function that returns the first unprocessed priority transaction.

Returns zero if and only if no operations were processed from the queue.

If all the transactions were processed, it will return the last processed index, so in case exactly unprocessed transactions are needed, one should check that getPriorityQueueSize() is greater than 0.

function getFirstUnprocessedPriorityTx() external view returns (uint256);

Returns

getPriorityQueueSize

function getPriorityQueueSize() external view returns (uint256);

Returns

isValidator

function isValidator(address _address) external view returns (bool);

Returns

l2LogsRootHash

function l2LogsRootHash(uint256 _batchNumber)
  external
  view
  returns (bytes32 merkleRoot);

Returns

storedBatchHash

For unfinalized (non executed) batches may change

returns zero for non-committed batches

function storedBatchHash(uint256 _batchNumber) external view returns (bytes32);

Returns

getL2BootloaderBytecodeHash

function getL2BootloaderBytecodeHash() external view returns (bytes32);

Returns

getL2DefaultAccountBytecodeHash

function getL2DefaultAccountBytecodeHash() external view returns (bytes32);

Returns

getL2EvmEmulatorBytecodeHash

function getL2EvmEmulatorBytecodeHash() external view returns (bytes32);

Returns

getVerifierParams

This function is deprecated and will soon be removed.

function getVerifierParams() external view returns (VerifierParams memory);

Returns

isDiamondStorageFrozen

function isDiamondStorageFrozen() external view returns (bool);

Returns

getProtocolVersion

function getProtocolVersion() external view returns (uint256);

Returns

getSemverProtocolVersion

function getSemverProtocolVersion()
  external
  view
  returns (uint32, uint32, uint32);

Returns

getL2SystemContractsUpgradeTxHash

function getL2SystemContractsUpgradeTxHash() external view returns (bytes32);

Returns

getL2SystemContractsUpgradeBatchNumber

*It is equal to 0 in the following two cases:

• No upgrade transaction has ever been processed.
• The upgrade transaction has been processed and the batch with such transaction has been executed (i.e. finalized).*

function getL2SystemContractsUpgradeBatchNumber()
  external
  view
  returns (uint256);

Returns

getPriorityTxMaxGasLimit

function getPriorityTxMaxGasLimit() external view returns (uint256);

Returns

isEthWithdrawalFinalized

function isEthWithdrawalFinalized(
  uint256 _l2BatchNumber,
  uint256 _l2MessageIndex
) external view returns (bool);

Parameters

Returns

getPubdataPricingMode

function getPubdataPricingMode() external view returns (PubdataPricingMode);

Returns

baseTokenGasPriceMultiplierNominator

function baseTokenGasPriceMultiplierNominator() external view returns (uint128);

Returns

baseTokenGasPriceMultiplierDenominator

function baseTokenGasPriceMultiplierDenominator()
  external
  view
  returns (uint128);

Returns

facets

function facets() external view returns (Facet[] memory);

Returns

facetFunctionSelectors

function facetFunctionSelectors(address _facet)
  external
  view
  returns (bytes4[] memory);

Returns

facetAddresses

function facetAddresses() external view returns (address[] memory facets);

Returns

facetAddress

function facetAddress(bytes4 _selector) external view returns (address facet);

Returns

isFunctionFreezable

function isFunctionFreezable(bytes4 _selector) external view returns (bool);

Returns

isFacetFreezable

function isFacetFreezable(address _facet)
  external
  view
  returns (bool isFreezable);

Returns

getSettlementLayer

function getSettlementLayer() external view returns (address);

Returns

Structs

Facet

Faсet structure compatible with the EIP-2535 diamond loupe

struct Facet {
  address addr;
  bytes4[] selectors;
}

Properties

IL1DAValidator

Git Source

Functions

checkDA

The function that checks the data availability for the given batch input.

function checkDA(
  uint256 _chainId,
  uint256 _batchNumber,
  bytes32 _l2DAValidatorOutputHash,
  bytes calldata _operatorDAInput,
  uint256 _maxBlobsSupported
) external returns (L1DAValidatorOutput memory output);

Parameters

ILegacyGetters

Git Source

Inherits: IZKChainBase

Author: Matter Labs

This interface contains getters for the ZKsync contract that should not be used, but still are kept for backward compatibility.

Note: security-contact: security@matterlabs.dev

Functions

getTotalBlocksCommitted

It is a deprecated method, please use getTotalBatchesCommitted instead

function getTotalBlocksCommitted() external view returns (uint256);

Returns

getTotalBlocksVerified

It is a deprecated method, please use getTotalBatchesVerified instead.

function getTotalBlocksVerified() external view returns (uint256);

Returns

getTotalBlocksExecuted

It is a deprecated method, please use getTotalBatchesExecuted instead.

function getTotalBlocksExecuted() external view returns (uint256);

Returns

storedBlockHash

For unfinalized (non executed) batches may change

It is a deprecated method, please use storedBatchHash instead.

returns zero for non-committed batches

function storedBlockHash(uint256 _batchNumber) external view returns (bytes32);

Returns

getL2SystemContractsUpgradeBlockNumber

It is a deprecated method, please use getL2SystemContractsUpgradeBatchNumber instead.

*It is equal to 0 in the following two cases:

• No upgrade transaction has ever been processed.
• The upgrade transaction has been processed and the batch with such transaction has been executed (i.e. finalized).*

function getL2SystemContractsUpgradeBlockNumber()
  external
  view
  returns (uint256);

Returns

IMailbox

Git Source

Inherits: IMessageVerification, IMailboxImpl

Author: Matter Labs

Note: security-contact: security@matterlabs.dev

ITransactionFilterer

Git Source

Author: Matter Labs

Note: security-contact: security@matterlabs.dev

Functions

isTransactionAllowed

Check if the transaction is allowed

function isTransactionAllowed(
  address sender,
  address contractL2,
  uint256 mintValue,
  uint256 l2Value,
  bytes memory l2Calldata,
  address refundRecipient
) external view returns (bool);

Parameters

Returns

IVerifier

Git Source

Author: Matter Labs

Note: security-contact: security@matterlabs.dev

Functions

verify

Verifies a zk-SNARK proof.

function verify(uint256[] calldata _publicInputs, uint256[] calldata _proof)
  external
  view
  returns (bool);

Returns

verificationKeyHash

Calculates a keccak256 hash of the runtime loaded verification keys.

function verificationKeyHash() external view returns (bytes32);

Returns

IVerifierV2

Git Source

Author: Matter Labs

Note: security-contact: security@matterlabs.dev

Functions

verify

Verifies a zk-SNARK proof.

function verify(uint256[] calldata _publicInputs, uint256[] calldata _proof)
  external
  view
  returns (bool);

Returns

verificationKeyHash

Calculates a keccak256 hash of the runtime loaded verification keys.

function verificationKeyHash() external view returns (bytes32);

Returns

IZKChain

Git Source

Inherits: IAdmin, IExecutor, IGetters, IMailbox

Events

ProposeTransparentUpgrade

event ProposeTransparentUpgrade(
  Diamond.DiamondCutData diamondCut,
  uint256 indexed proposalId,
  bytes32 proposalSalt
);

IZKChainBase

Git Source

Author: Matter Labs

Note: security-contact: security@matterlabs.dev

Functions

getName

function getName() external view returns (string memory);

Returns

IMailboxImpl

Git Source

Inherits: IZKChainBase

Author: Matter Labs

Note: security-contact: security@matterlabs.dev

Functions

proveL2MessageInclusion

Prove that a specific arbitrary-length message was sent in a specific L2 batch number.

function proveL2MessageInclusion(
  uint256 _batchNumber,
  uint256 _index,
  L2Message calldata _message,
  bytes32[] calldata _proof
) external view returns (bool);

Parameters

Returns

proveL2LogInclusion

Prove that a specific L2 log was sent in a specific L2 batch.

function proveL2LogInclusion(
  uint256 _batchNumber,
  uint256 _index,
  L2Log calldata _log,
  bytes32[] calldata _proof
) external view returns (bool);

Parameters

Returns

proveL1ToL2TransactionStatus

Prove that the L1 -> L2 transaction was processed with the specified status.

function proveL1ToL2TransactionStatus(
  bytes32 _l2TxHash,
  uint256 _l2BatchNumber,
  uint256 _l2MessageIndex,
  uint16 _l2TxNumberInBatch,
  bytes32[] calldata _merkleProof,
  TxStatus _status
) external view returns (bool);

Parameters

Returns

finalizeEthWithdrawal

Finalize the withdrawal and release funds.

function finalizeEthWithdrawal(
  uint256 _l2BatchNumber,
  uint256 _l2MessageIndex,
  uint16 _l2TxNumberInBatch,
  bytes calldata _message,
  bytes32[] calldata _merkleProof
) external;

Parameters

requestL2Transaction

Request execution of L2 transaction from L1.

*If the L2 deposit finalization transaction fails, the _refundRecipient will receive the _l2Value. Please note, the contract may change the refund recipient's address to eliminate sending funds to addresses out of control.

• If _refundRecipient is a contract on L1, the refund will be sent to the aliased _refundRecipient.
• If _refundRecipient is set to address(0) and the sender has NO deployed bytecode on L1, the refund will be sent to the msg.sender address.
• If _refundRecipient is set to address(0) and the sender has deployed bytecode on L1, the refund will be sent to the aliased msg.sender address.*

The address aliasing of L1 contracts as refund recipient on L2 is necessary to guarantee that the funds are controllable, since address aliasing to the from address for the L2 tx will be applied if the L1 msg.sender is a contract. Without address aliasing for L1 contracts as refund recipients they would not be able to make proper L2 tx requests through the Mailbox to use or withdraw the funds from L2, and the funds would be lost.

function requestL2Transaction(
  address _contractL2,
  uint256 _l2Value,
  bytes calldata _calldata,
  uint256 _l2GasLimit,
  uint256 _l2GasPerPubdataByteLimit,
  bytes[] calldata _factoryDeps,
  address _refundRecipient
) external payable returns (bytes32 canonicalTxHash);

Parameters

Returns

bridgehubRequestL2Transaction

Request execution of L2 transaction through the Bridgehub.

Only accessible from L1, this is getting checked in the Bridgehub.

function bridgehubRequestL2Transaction(
  BridgehubL2TransactionRequest calldata _request
) external returns (bytes32 canonicalTxHash);

Parameters

bridgehubRequestL2TransactionOnGateway

The chain's mailbox receives the tx from the Bridgehub on Gateway.

function bridgehubRequestL2TransactionOnGateway(
  bytes32 _canonicalTxHash,
  uint64 _expirationTimestamp
) external;

Parameters

requestL2ServiceTransaction

Request execution of service L2 transaction from L1.

Used for chain configuration. Can be called only by DiamondProxy itself.

function requestL2ServiceTransaction(
  address _contractL2,
  bytes calldata _l2Calldata
) external returns (bytes32 canonicalTxHash);

Parameters

requestL2TransactionToGatewayMailbox

On L1 we have to forward to the Gateway's mailbox which sends to the Bridgehub on the Gateway.

function requestL2TransactionToGatewayMailbox(
  uint256 _chainId,
  bytes32 _canonicalTxHash,
  uint64 _expirationTimestamp
) external returns (bytes32 canonicalTxHash);

Parameters

l2TransactionBaseCost

Estimates the cost in Ether of requesting execution of an L2 transaction from L1.

function l2TransactionBaseCost(
  uint256 _gasPrice,
  uint256 _l2GasLimit,
  uint256 _l2GasPerPubdataByteLimit
) external view returns (uint256);

Parameters

Returns

proveL2LeafInclusion

Proves that a certain leaf was included as part of the log merkle tree.

Warning: this function does not enforce any additional checks on the structure of the leaf. This means that it can accept intermediate nodes of the Merkle tree as a _leaf as well as the default "empty" leaves. It is the responsibility of the caller to ensure that the _leaf is a hash of a valid leaf.

function proveL2LeafInclusion(
  uint256 _batchNumber,
  uint256 _leafProofMask,
  bytes32 _leaf,
  bytes32[] calldata _proof
) external view returns (bool);

Parameters

Events

NewPriorityRequest

New priority request event. Emitted when a request is placed into the priority queue.

event NewPriorityRequest(
  uint256 txId,
  bytes32 txHash,
  uint64 expirationTimestamp,
  L2CanonicalTransaction transaction,
  bytes[] factoryDeps
);

Parameters

NewRelayedPriorityTransaction

New relayed priority request event. It is emitted on a chain that is deployed on top of the gateway when it receives a request relayed via the Bridgehub.

IMPORTANT: this event most likely will be removed in the future, so no one should rely on it for indexing purposes.

event NewRelayedPriorityTransaction(
  uint256 txId, bytes32 txHash, uint64 expirationTimestamp
);

Parameters

IMessageVerification

Git Source

Author: Matter Labs

Note: security-contact: security@matterlabs.dev

Functions

proveL2MessageInclusionShared

Prove that a specific arbitrary-length message was sent in a specific L2 batch/block number.

function proveL2MessageInclusionShared(
  uint256 _chainId,
  uint256 _blockOrBatchNumber,
  uint256 _index,
  L2Message calldata _message,
  bytes32[] calldata _proof
) external view returns (bool);

Parameters

Returns

proveL2LogInclusionShared

Prove that a specific L2 log was sent in a specific L2 batch.

function proveL2LogInclusionShared(
  uint256 _chainId,
  uint256 _blockOrBatchNumber,
  uint256 _index,
  L2Log calldata _log,
  bytes32[] calldata _proof
) external view returns (bool);

Parameters

Returns

proveL2LeafInclusionShared

Proves that a certain leaf was included as part of the log merkle tree.

Warning: this function does not enforce any additional checks on the structure of the leaf. This means that it can accept intermediate nodes of the Merkle tree as a _leaf as well as the default "empty" leaves. It is the responsibility of the caller to ensure that the _leaf is a hash of a valid leaf.

function proveL2LeafInclusionShared(
  uint256 _chainId,
  uint256 _blockOrBatchNumber,
  uint256 _leafProofMask,
  bytes32 _leaf,
  bytes32[] calldata _proof
) external view returns (bool);

Parameters

Contents

• IComplexUpgrader
• IL2GatewayUpgrade
• ForceDeployment
• ZKChainSpecificForceDeploymentsData
• FixedForceDeploymentsData
• IL2GenesisUpgrade
• ISystemContext

IComplexUpgrader

Git Source

Author: Matter Labs

Note: security-contact: security@matterlabs.dev

Functions

forceDeployAndUpgrade

function forceDeployAndUpgrade(
  IL2ContractDeployer.ForceDeployment[] calldata _forceDeployments,
  address _delegateTo,
  bytes calldata _calldata
) external payable;

upgrade

function upgrade(address _delegateTo, bytes calldata _calldata)
  external
  payable;

IL2GatewayUpgrade

Git Source

Functions

upgrade

function upgrade(
  IL2ContractDeployer.ForceDeployment[] calldata _forceDeployments,
  address _ctmDeployer,
  bytes calldata _fixedForceDeploymentsData,
  bytes calldata _additionalForceDeploymentsData
) external payable;

IL2GenesisUpgrade

Git Source

Author: Matter Labs

Note: security-contact: security@matterlabs.dev

Functions

genesisUpgrade

function genesisUpgrade(
  uint256 _chainId,
  address _ctmDeployer,
  bytes calldata _fixedForceDeploymentsData,
  bytes calldata _additionalForceDeploymentsData
) external payable;

Events

UpgradeComplete

event UpgradeComplete(uint256 _chainId);

ISystemContext

Git Source

Author: Matter Labs

Note: security-contact: security@matterlabs.dev

Functions

setChainId

function setChainId(uint256 _newChainId) external;

Contents

• AddressAliasHelper

AddressAliasHelper

Git Source

State Variables

offset

uint160 private constant offset =
  uint160(0x1111000000000000000000000000000000001111);

Functions

applyL1ToL2Alias

Utility function converts the address that submitted a tx to the inbox on L1 to the msg.sender viewed on L2

function applyL1ToL2Alias(address l1Address)
  internal
  pure
  returns (address l2Address);

Parameters

Returns

undoL1ToL2Alias

Utility function that converts the msg.sender viewed on L2 to the address that submitted a tx to the inbox on L1

function undoL1ToL2Alias(address l2Address)
  internal
  pure
  returns (address l1Address);

Parameters

Returns

actualRefundRecipient

Utility function used to calculate the correct refund recipient

function actualRefundRecipient(
  address _refundRecipient,
  address _originalCaller
) internal view returns (address _recipient);

Parameters

Returns