Go API

Types

Defines various types for zksync2-go.

Types are placed in three packages for different purposes:

  • types: Contains common and general types used to build basic features and other types.
  • eip712: Contains types used for EIP-712 implementation.
  • clients: Contains types that are meant to be used along with Client.
  • accounts: Contains types that are meant to be used along with an account. Many types are similar to those from the geth library, but the From or Signer fields are omitted because these fields are associated with account.

This section provides a list of various types used in the ZKsync Go SDK. These types are categorized based on their purposes and usage within the SDK.

AccountAbstractionVersion

Represents an enumeration of account abstraction versions.

type AccountAbstractionVersion uint8

const (
    None AccountAbstractionVersion = iota
    Version1
)

AccountNonceOrdering

Represents an enumeration of account nonce ordering formats.

type AccountNonceOrdering uint8

const (
    Sequential AccountNonceOrdering = iota
    Arbitrary
)

ApprovalBasedPaymasterInput

Contains approval-based paymaster input. It should be used if the user is required to set a certain allowance to a token for the paymaster to operate.

type ApprovalBasedPaymasterInput struct {
    Token common.Address // ERC20 token used to pay transaction fee.
    // Minimal allowance of Token towards the paymaster from the account that pays the fee with the token.
    MinimalAllowance *big.Int
    InnerInput       []byte // Additional payload that can be sent to the paymaster to implement any logic.
}

BatchDetails

Contains batch information.

type BatchDetails struct {
// Hashes of the base system contracts involved in the batch.
  BaseSystemContractsHashes struct {
    Bootloader common.Hash `json:"bootloader"`
    DefaultAa  common.Hash `json:"default_aa"`
  } `json:"baseSystemContractsHashes"`
  CommitTxHash   *common.Hash `json:"commitTxHash"`   // The transaction hash of the commit operation on L1.
  CommittedAt    time.Time    `json:"committedAt"`    // The timestamp when the block was committed on L1.
  ExecuteTxHash  *common.Hash `json:"executeTxHash"`  // The transaction hash of the execution on L1.
  ExecutedAt     time.Time    `json:"executedAt"`     // The timestamp when the block execution was completed on L1.
  L1GasPrice     *big.Int     `json:"l1GasPrice"`     // L1 gas price at the time of the block's execution.
  L1TxCount      uint64       `json:"l1TxCount"`      // The number of L1 transactions included in the batch.
  L2FairGasPrice *big.Int     `json:"l2FairGasPrice"` // Fair gas price on L2 at the time of the block's execution.
  L2TxCount      uint64       `json:"l2TxCount"`      // The number of L2 transactions associated with this batch.
  Number         *big.Int     `json:"number"`         // L1 batch number.
  ProveTxHash    *common.Hash `json:"proveTxHash"`    // The transaction hash of the proof submission on L1.
  ProvenAt       time.Time    `json:"provenAt"`       // The timestamp when the proof was submitted on L1.
  RootHash       *common.Hash `json:"rootHash"`       // Root hash of the state after processing the batch.
  Status         string       `json:"status"`         // Current status of the batch (e.g., verified).
  Timestamp      uint64       `json:"timestamp"`      // Unix timestamp when the batch was processed.
}

Block

Extends the types.Block definition with additional L1BatchNumber, L1BatchTimestamp fields.

type Block struct {
    Header           *types.Header
    Uncles           []*types.Header
    Transactions     []*TransactionResponse
    Withdrawals      types.Withdrawals
    Hash             common.Hash
    Size             *big.Int
    TotalDifficulty  *big.Int
    SealFields       []interface{}
    ReceivedAt       time.Time
    ReceivedFrom     interface{}
    L1BatchNumber    *big.Int
    L1BatchTimestamp *big.Int
}

BlockDetails

Contains block information.

type BlockDetails struct {
  Number         *big.Int     `json:"number"`         // The number of the block.
  L1BatchNumber  *big.Int     `json:"l1BatchNumber"`  // Corresponding L1 batch number.
  Timestamp      uint64       `json:"timestamp"`      // Unix timestamp when the block was committed.
  L1TxCount      uint64       `json:"l1TxCount"`      // The number of L1 transactions included in the block.
  L2TxCount      uint64       `json:"l2TxCount"`      // The number of L2 transactions included in the block.
  RootHash       common.Hash  `json:"rootHash"`       // Root hash of the block's state after execution.
  Status         string       `json:"status"`         // Current status of the block (e.g., verified, executed).
  CommitTxHash   *common.Hash `json:"commitTxHash"`   // The transaction hash of the commit operation on L1.
  CommittedAt    time.Time    `json:"committedAt"`    // The timestamp when the block was committed on L1.
  ProveTxHash    *common.Hash `json:"proveTxHash"`    // The transaction hash of the proof submission on L1.
  ProvenAt       time.Time    `json:"provenAt"`       // The timestamp when the proof was submitted on L1.
  ExecuteTxHash  *common.Hash `json:"executeTxHash"`  // The transaction hash of the execution on L1.
  ExecutedAt     time.Time    `json:"executedAt"`     // The timestamp when the block execution was completed on L1.
  L1GasPrice     *big.Int     `json:"l1GasPrice"`     // L1 gas price at the time of the block's execution.
  L2FairGasPrice *big.Int     `json:"l2FairGasPrice"` // Fair gas price on L2 at the time of the block's execution.
  // A collection of hashes for the base system contracts involved in the block.
  BaseSystemContractsHashes struct {
    Bootloader common.Hash `json:"bootloader"`
    DefaultAa  common.Hash `json:"default_aa"`
  } `json:"baseSystemContractsHashes"`
  OperatorAddress common.Address `json:"operatorAddress"` // Address of the operator who committed the block.
  ProtocolVersion string         `json:"protocolVersion"` // Version of the ZKsync protocol the block was committed under.
}

BridgeContracts

Represents the addresses of default bridge contracts for both L1 and L2.

type BridgeContracts struct {
    L1Erc20Bridge  common.Address `json:"l1Erc20DefaultBridge"`  // Default L1Bridge contract address.
    L2Erc20Bridge  common.Address `json:"l2Erc20DefaultBridge"`  // Default L2Bridge contract address.
    L1WethBridge   common.Address `json:"l1WethBridge"`          // WETH L1Bridge contract address.
    L2WethBridge   common.Address `json:"l2WethBridge"`          // WETH L2Bridge contract address.
    L1SharedBridge common.Address `json:"l1SharedDefaultBridge"` // Default L1SharedBridge contract address.
    L2SharedBridge common.Address `json:"l2SharedDefaultBridge"` // Default L2SharedBridge contract address.
}

CallMsg

Contains parameters for contract call using L2 transaction.

type CallMsg struct {
    From      common.Address  // The sender of the 'transaction'.
    To        *common.Address // The destination contract (nil for contract creation).
    Gas       uint64          // If 0, the call executes with near-infinite gas.
    GasPrice  *big.Int        // Wei <-> gas exchange ratio
    GasFeeCap *big.Int        // EIP-1559 fee cap per gas.
    GasTipCap *big.Int        // EIP-1559 tip per gas.
    Value     *big.Int        // Amount of wei sent along with the call.
    Data      []byte          // Input data, usually an ABI-encoded contract method invocation.

    // GasPerPubdata denotes the maximum amount of gas the user is willing
    // to pay for a single byte of pubdata.
    GasPerPubdata *big.Int
    // CustomSignature is used for the cases in which the signer's account
    // is not an EOA.
    CustomSignature hexutil.Bytes
    // FactoryDeps is a non-empty array of bytes. For deployment transactions,
    // it should contain the bytecode of the contract being deployed.
    // If the contract is a factory contract, i.e. it can deploy other contracts,
    // the array should also contain the bytecodes of the contracts which it can deploy.
    FactoryDeps []hexutil.Bytes
    // PaymasterParams contains parameters for configuring the custom paymaster
    // for the transaction.
    PaymasterParams *PaymasterParams
}

Fee

Represents the transaction fee parameters.

type Fee struct {
    GasLimit *hexutil.Big `json:"gas_limit"` // Maximum amount of gas allowed for the transaction.
    // Maximum amount of gas the user is willing to pay for a single byte of pubdata.
    GasPerPubdataLimit   *hexutil.Big `json:"gas_per_pubdata_limit"`
    MaxFeePerGas         *hexutil.Big `json:"max_fee_per_gas"`          // EIP-1559 fee cap per gas.
    MaxPriorityFeePerGas *hexutil.Big `json:"max_priority_fee_per_gas"` // EIP-1559 tip per gas.
}

FeeParams

Represents the fee parameters configuration.

type FeeParams struct {
    // Fee parameter configuration for the current version of the ZKsync protocol.
    V2 struct {
        // Settings related to transaction fee computation.
        Config struct {
            MinimalL2GasPrice   uint64 `json:"minimal_l2_gas_price"`  // Minimal gas price on L2.
            ComputeOverheadPart uint64 `json:"compute_overhead_part"` // Compute overhead part in fee calculation.
            PubdataOverheadPart uint64 `json:"pubdata_overhead_part"` // Public data overhead part in fee calculation.
            BatchOverheadL1Gas  uint64 `json:"batch_overhead_l1_gas"` // Overhead in L1 gas for a batch of transactions.
            MaxGasPerBatch      uint64 `json:"max_gas_per_batch"`     // Maximum gas allowed per batch.
            MaxPubdataPerBatch  uint64 `json:"max_pubdata_per_batch"` // Maximum amount of public data allowed per batch.
        } `json:"config"`
        L1GasPrice     uint64 `json:"l1_gas_price"`     // Current L1 gas price.
        L1PubdataPrice uint64 `json:"l1_pubdata_price"` // Price of storing public data on L1.
    } `json:"V2"`
}

GeneralPaymasterInput

Contains general paymaster input. It should be used if no prior actions are required from the user for the paymaster to operate.

type GeneralPaymasterInput []byte

L1BridgeContracts

Represents the L1 bridge contracts.

type L1BridgeContracts struct {
    Erc20  *l1bridge.IL1Bridge             // Default L1Bridge contract.
    Shared *l1sharedbridge.IL1SharedBridge // L1SharedBridge contract.
}

L2BridgeContracts

Represents the L2 bridge contracts.

type L2BridgeContracts struct {
    Erc20  *l2bridge.IL2Bridge // Default L2Bridge contract.
    Shared *l2bridge.IL2Bridge // Shared L2Bridge contract.
}

L2ToL1Log

Represents a layer 2 to layer 1 transaction log.

type L2ToL1Log struct {
    BlockNumber      *hexutil.Big   `json:"blockNumber"`
    BlockHash        common.Hash    `json:"blockHash"`
    L1BatchNumber    *hexutil.Big   `json:"l1BatchNumber"`
    TransactionIndex *hexutil.Uint  `json:"transactionIndex"`
    ShardId          *hexutil.Uint  `json:"shardId"`
    IsService        bool           `json:"isService"`
    Sender           common.Address `json:"sender"`
    Key              string         `json:"key"`
    Value            string         `json:"value"`
    TxHash           common.Hash    `json:"transactionHash"`
    Index            *hexutil.Uint  `json:"logIndex"`
}

Log

Extends the types.Log definition with additional L1BatchNumber field.

// Log represents a log entry.
type Log struct {
    types.Log
    L1BatchNumber *hexutil.Big `json:"l1BatchNumber"`
}

LogProof

Represents a log proof for an L2 to L1 transaction.

type LogProof struct {
  Id    int32         `json:"id"`    // Identifier of the log within the transaction.
  Proof []common.Hash `json:"proof"` // Each element represents a piece of the proof for the specified log.
  Root  common.Hash   `json:"root"`  // Root hash of the proof, anchoring it to a specific state in the blockchain.
}

MessageProof

Represents a message proof.

type MessageProof struct {
    Id    int32         `json:"id"`
    Proof []common.Hash `json:"proof"`
    Root  common.Hash   `json:"root"`
}

PaymasterParams

Contains parameters for configuring the custom paymaster for the transaction.

type PaymasterParams struct {
    Paymaster      common.Address `json:"paymaster"`      // address of the paymaster
    PaymasterInput []byte         `json:"paymasterInput"` // encoded input
}

PriorityOpConfirmation

Represents confirmation data that is part of L2->L1 message

type PriorityOpConfirmation struct {
    L1BatchNumber     *big.Int
    L2MessageIndex    int32
    L2TxNumberInBlock *big.Int
    Proof             []common.Hash
}

ProtocolVersion

Represents the protocol version.

type ProtocolVersion struct {
    VersionId uint8  `json:"version_id"` // Protocol version ID.
    Timestamp uint64 `json:"timestamp"`  // Unix timestamp of the version's activation.
    // Contains the hashes of various verification keys used in the protocol.
    VerificationKeysHashes struct {
        Params struct {
            RecursionNodeLevelVkHash    common.Hash `json:"recursion_node_level_vk_hash"`
            RecursionLeafLevelVkHash    common.Hash `json:"recursion_leaf_level_vk_hash"`
            RecursionCircuitsSetVksHash common.Hash `json:"recursion_circuits_set_vks_hash"`
        } `json:"params"`
        RecursionSchedulerLevelVkHash common.Hash `json:"recursion_scheduler_level_vk_hash"`
    } `json:"verification_keys_hashes"`
    // Hashes of the base system contracts.
    BaseSystemContracts struct {
        Bootloader common.Hash `json:"bootloader"`
        DefaultAa  common.Hash `json:"default_aa"`
    } `json:"base_system_contracts"`
    // Hash of the transaction used for the system upgrade, if any.
    L2SystemUpgradeTxHash *common.Hash `json:"l2_system_upgrade_tx_hash"`
}

RawBlockTransaction

Represents a raw block transaction.

type RawBlockTransaction struct {
    // General information about the L2 transaction.
    CommonData struct {
        L2 struct {
            Nonce uint64 `json:"nonce"`
            Fee   struct {
                GasLimit             hexutil.Big `json:"gas_limit"`
                MaxFeePerGas         hexutil.Big `json:"max_fee_per_gas"`
                MaxPriorityFeePerGas hexutil.Big `json:"max_priority_fee_per_gas"`
                GasPerPubdataLimit   hexutil.Big `json:"gas_per_pubdata_limit"`
            } `json:"fee"`
            InitiatorAddress common.Address `json:"initiatorAddress"`
            Signature        []byte         `json:"signature"`
            TransactionType  string         `json:"transactionType"`
            Input            struct {
                Hash common.Hash `json:"hash"`
                Data []uint64    `json:"data"`
            } `json:"input"`
            PaymasterParams struct {
                Paymaster      common.Address `json:"paymaster"`
                PaymasterInput []byte         `json:"paymasterInput"`
            } `json:"paymasterParams"`
        } `json:"L2"`
    } `json:"common_data"`
    // Details regarding the execution of the transaction.
    Execute struct {
        ContractAddress common.Address  `json:"contractAddress"`
        Calldata        hexutil.Bytes   `json:"calldata"`
        Value           hexutil.Big     `json:"value"`
        FactoryDeps     []hexutil.Bytes `json:"factoryDeps"`
    } `json:"execute"`
    // Timestamp when the transaction was received, in milliseconds.
    ReceivedTimestampMs uint64 `json:"received_timestamp_ms"`
    // Raw bytes of the transaction as a hexadecimal string.
    RawBytes hexutil.Bytes `json:"raw_bytes"`
}

Receipt

Extends the types.Receipt definition with additional From, To, EffectiveGasPrice, L1BatchNumber, L1BatchTxIndex, Logs, L2ToL1Logs fields.

type Receipt struct {
    types.Receipt

    From              common.Address `json:"from"`
    To                common.Address `json:"to"`
    EffectiveGasPrice *hexutil.Big   `json:"effectiveGasPrice"`
    L1BatchNumber     *hexutil.Big   `json:"l1BatchNumber"`
    L1BatchTxIndex    *hexutil.Big   `json:"l1BatchTxIndex"`
    Logs              []*Log         `json:"logs"`
    L2ToL1Logs        []*L2ToL1Log   `json:"l2ToL1Logs"`
}

StandardConfiguration

Represents the standard-json configuration generated as output of zksolc compiler.

type StandardConfiguration struct {
    Format       string `json:"_format"`
    ContractName string `json:"contractName"`
    SourceName   string `json:"sourceName"`
    Abi          []struct {
        Inputs []struct {
            InternalType string `json:"internalType"`
            Name         string `json:"name"`
            Type         string `json:"type"`
            Indexed      bool   `json:"indexed,omitempty"`
        } `json:"inputs"`
        StateMutability string `json:"stateMutability,omitempty"`
        Type            string `json:"type"`
        Anonymous       bool   `json:"anonymous,omitempty"`
        Name            string `json:"name,omitempty"`
        Outputs         []struct {
            InternalType string `json:"internalType"`
            Name         string `json:"name"`
            Type         string `json:"type"`
        } `json:"outputs,omitempty"`
    } `json:"abi"`
    Bytecode         string `json:"bytecode"`
    DeployedBytecode string `json:"deployedBytecode"`
    LinkReferences   struct {
    } `json:"linkReferences"`
    DeployedLinkReferences struct {
    } `json:"deployedLinkReferences"`
    FactoryDeps struct {
    } `json:"factoryDeps"`
}

StorageProof

Merkle proofs for one or more storage values at the specified account


type StorageProof struct {
    Address string `json:"address"`
    Proofs  []struct {
        Key   string   `json:"key"`
        Proof []string `json:"proof"`
        Value string   `json:"value"`
        Index int32      `json:"index"`
    } `json:"storageProof"`
}

Token

Represents a token with addresses on both L1 and L2 chains.

type Token struct {
    L1Address common.Address `json:"l1Address"` // Token address on L1.
    L2Address common.Address `json:"l2Address"` // Token address on L2.
    Name      string         `json:"name"`      // Token name.
    Symbol    string         `json:"symbol"`    // Token symbol.
    Decimals  uint8          `json:"decimals"`  // Number of decimals for the token.
}

TxType

Represents a L2 transaction type.

const TxType = `0x71`

Transaction

Transaction provides support for ZKsync specific features such as account abstraction and paymasters. Smart contracts must be deployed with this transaction type.

type Transaction struct {
    Nonce     *big.Int        `json:"nonce"`     // Nonce to use for the transaction execution.
    GasTipCap *big.Int        `json:"gasTipCap"` // EIP-1559 tip per gas.
    GasFeeCap *big.Int        `json:"gasFeeCap"` // EIP-1559 fee cap per gas.
    Gas       *big.Int        `json:"gas"`       // Gas limit to set for the transaction execution.
    To        *common.Address `json:"to"`        // The address of the recipient.
    Value     *big.Int        `json:"value"`     // Funds to transfer along the transaction (nil = 0 = no funds).
    Data      hexutil.Bytes   `json:"data"`      // Input data, usually an ABI-encoded contract method invocation.

    ChainID *big.Int        `json:"chainID"` // Chain ID of the network.
    From    *common.Address `json:"from"`    // The address of the sender.

    // GasPerPubdata denotes the maximum amount of gas the user is willing
    // to pay for a single byte of pubdata.
    GasPerPubdata *big.Int `json:"gasPerPubdata"`
    // CustomSignature is used for the cases in which the signer's account
    // is not an EOA.
    CustomSignature hexutil.Bytes `json:"customSignature"`
    // FactoryDeps is a non-empty array of bytes. For deployment transactions,
    // it should contain the bytecode of the contract being deployed.
    // If the contract is a factory contract, i.e. it can deploy other contracts,
    // the array should also contain the bytecodes of the contracts which it can deploy.
    FactoryDeps []hexutil.Bytes `json:"factoryDeps"`
    // PaymasterParams contains parameters for configuring the custom paymaster
    // for the transaction.
    PaymasterParams *PaymasterParams `json:"paymasterParams"`
}

TransactionDetails

Contains transaction details.

type TransactionDetails struct {
    EthCommitTxHash  common.Hash    `json:"ethCommitTxHash"`
    EthExecuteTxHash common.Hash    `json:"ethExecuteTxHash"`
    EthProveTxHash   common.Hash    `json:"ethProveTxHash"`
    Fee              hexutil.Big    `json:"fee"`
    InitiatorAddress common.Address `json:"initiatorAddress"`
    IsL1Originated   bool           `json:"isL1Originated"`
    ReceivedAt       time.Time      `json:"receivedAt"`
    Status           string         `json:"status"`
}

TransactionResponse

Includes all properties of a transaction as well as several properties that are useful once it has been mined.

type TransactionResponse struct {
    BlockHash            *common.Hash   `json:"blockHash"`
    BlockNumber          *hexutil.Big   `json:"blockNumber"`
    ChainID              hexutil.Big    `json:"chainId"`
    From                 common.Address `json:"from"`
    Gas                  hexutil.Uint64 `json:"gas"`
    GasPrice             hexutil.Big    `json:"gasPrice"`
    Hash                 common.Hash    `json:"hash"`
    Data                 hexutil.Bytes  `json:"input"`
    L1BatchNumber        hexutil.Big    `json:"l1BatchNumber"`
    L1BatchTxIndex       hexutil.Big    `json:"l1BatchTxIndex"`
    MaxFeePerGas         hexutil.Big    `json:"maxFeePerGas"`
    MaxPriorityFeePerGas hexutil.Big    `json:"maxPriorityFeePerGas"`
    Nonce                hexutil.Uint64 `json:"nonce"`
    V                    *hexutil.Big   `json:"v"`
    R                    *hexutil.Big   `json:"r"`
    S                    *hexutil.Big   `json:"s"`
    To                   common.Address `json:"to"`
    TransactionIndex     hexutil.Uint   `json:"transactionIndex"`
    Type                 hexutil.Uint64 `json:"type"`
    Value                hexutil.Big    `json:"value"`
}

Paymaster Utilities

Essential utilities for using paymasters on ZKsync Era

Overview

An introduction to the zksync2-python and its features.

Made with ❤️ by the ZKsync Community