ZKs JSON-RPC API

Overview of the JSON-RPC API methods specific to ZKsync Era, detailing operations and functionalities within the ZKsync Era ecosystem.

ZKsync Era provides a suite of JSON-RPC API methods designed for seamless interaction with its ecosystem. These methods offer developers the tools needed to integrate their applications with ZKsync Era's features, enhancing the capability to perform transactions, query network data, and interact with smart contracts efficiently.

`zks_estimateFee`

Estimates the fee for a given call request.

Parameters

CallRequest - object

Returns

The method returns an object containing the estimated gas and fee details for the given call request.

gas_limit: QUANTITY, 32 bytes - The maximum amount of gas that can be used.
max_fee_per_gas: QUANTITY, 32 bytes - The maximum fee per unit of gas that the sender is willing to pay.
max_priority_fee_per_gas: QUANTITY, 32 bytes - The maximum priority fee per unit of gas to incentivize miners.
gas_per_pubdata_limit: QUANTITY, 32 bytes - The gas limit per unit of public data.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 2,
      "method": "zks_estimateFee",
      "params": [
        {
          "from": "0x1111111111111111111111111111111111111111",
          "to": "0x2222222222222222222222222222222222222222",
          "data": "0xffffffff"
        }
      ]
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": {
    "gas_limit": "0x1ea9a9",
    "max_fee_per_gas": "0x17d7840",
    "max_priority_fee_per_gas": "0x0",
    "gas_per_pubdata_limit": "0x5340"
  },
  "id": 2
}

`zks_estimateGasL1ToL2`

Estimates the gas required for an L1 to L2 transaction.

Parameters

CallRequest - object

Returns

QUANTITY, 32 bytes - The estimated gas amount in hexadecimal format, representing the number of gas units required.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 2,
      "method": "zks_estimateGasL1ToL2",
      "params": [
        {
          "from": "0x1111111111111111111111111111111111111111",
          "to": "0x2222222222222222222222222222222222222222",
          "data": "0xffffffff"
        }
      ]
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": "0x25f64db",
  "id": 2
}

`zks_getBridgehubContract`

Retrieves the bridge hub contract address.

Parameters

None

Returns

DATA, 20 bytes - a single string value representing the bridge hub contract address.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "zks_getBridgehubContract",
      "params": []
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": "0x303a465b659cbb0ab36ee643ea362c509eeb5213",
  "id": 1
}

`zks_getMainContract`

Retrieves the main contract address.

Parameters

None

Returns

DATA, 20 bytes - address of the main contract.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "zks_getMainContract",
      "params": []
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": "0x32400084c286cf3e17e7b677ea9583e60a000324",
  "id": 1
}

`zks_getTestnetPaymaster`

Retrieves the testnet paymaster address, specifically for interactions within the ZKsync Sepolia Testnet environment. Note: This method is only applicable for ZKsync Sepolia Testnet.

Parameters

None

Returns

DATA, 20 bytes - address of the testnet paymaster.

Example Request

curl --request POST \
  --url https://sepolia.era.zksync.dev \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "zks_getTestnetPaymaster",
      "params": []
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": "0x3cb2b87d10ac01736a65688f3e0fb1b070b3eea3",
  "id": 1
}

`zks_getBridgeContracts`

Retrieves the addresses of canonical bridge contracts for ZKsync Era.

Parameters

None

Returns

Object containing the addresses of bridge contracts.

l1Erc20DefaultBridge: DATA, 20 bytes - address of the default ERC-20 bridge on Layer 1.
l2Erc20DefaultBridge: DATA, 20 bytes - address of the default ERC-20 bridge on Layer 2.
l1WethBridge: DATA, 20 bytes - address of the Wrapped Ethereum (WETH) bridge on Layer 1.
l2WethBridge: DATA, 20 bytes - address of the Wrapped Ethereum (WETH) bridge on Layer 2.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "zks_getBridgeContracts",
      "params": []
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": {
    "l1Erc20DefaultBridge": "0x57891966931eb4bb6fb81430e6ce0a03aabde063",
    "l2Erc20DefaultBridge": "0x11f943b2c77b743ab90f4a0ae7d5a4e7fca3e102",
    "l1WethBridge": "0x0000000000000000000000000000000000000000",
    "l2WethBridge": "0x0000000000000000000000000000000000000000"
  },
  "id": 1
}

`zks_L1ChainId`

Retrieves the L1 chain ID.

Parameters

None

Returns

QUANTITY, 8 bytes - The hexadecimal representation of the L1 chain ID.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "zks_L1ChainId",
      "params": []
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": "0x1",
  "id": 1
}

`zks_getBaseTokenL1Address`

Retrieves the L1 base token address.

Parameters

None

Returns

DATA, 20 bytes - Layer 1 Ethereum address of base token.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "zks_getBaseTokenL1Address",
      "params": []
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": "0x0000000000000000000000000000000000000001",
  "id": 1
}

`zks_getConfirmedTokens`

Lists confirmed tokens. Confirmed in the method name means any token bridged to ZKsync Era via the official bridge.

The tokens are returned in alphabetical order by their symbol. This means the token id is its position in an alphabetically sorted array of tokens.

Parameters

uint32 - token id from which to start.
uint8 - maximum number of tokens to list.

Returns

Array of token objects, each containing details about a specific confirmed token.

l1Address: DATA, 20 bytes - Layer 1 Ethereum address of the token.
l2Address: DATA, 20 bytes - Layer 2 ZKsync Era address of the token.
name: String - name of the token.
symbol: String - symbol of the token.
decimals: uint8 - number of decimals the token uses.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "zks_getConfirmedTokens",
      "params": [1, 3]
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": [
    {
      "l1Address": "0xb6ed7644c69416d67b522e20bc294a9a9b405b31",
      "l2Address": "0xfea352c0d005a1e4ac7e092ef14fca18b8e6c8fd",
      "name": "0xBitcoin Token",
      "symbol": "0xBTC",
      "decimals": 8
    },
    {
      "l1Address": "0x111111111117dc0aa78b770fa6a738034120c302",
      "l2Address": "0x3f0b8b206a7fbdb3ecfc08c9407ca83f5ab1ce59",
      "name": "1INCH Token",
      "symbol": "1INCH",
      "decimals": 18
    },
    {
      "l1Address": "0xb50721bcf8d664c30412cfbc6cf7a15145234ad1",
      "l2Address": "0xd5428b08b604727c43ba5a37eed25a289978d081",
      "name": "Arbitrum",
      "symbol": "ARB",
      "decimals": 18
    }
  ],
  "id": 1
}

`zks_getAllAccountBalances`

Gets all account balances for a given address.

Parameters

DATA, 20 bytes - account address.

Returns

The method returns an object with token addresses as keys and their corresponding balances as values. Each key-value pair represents the balance of a specific token held by the account.

<DATA, 20 bytes>: QUANTITY, 32 bytes - The token address is the key, and its value is the balance of that token held by the account, represented in the smallest unit of the token (e.g., wei for ETH).

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "zks_getAllAccountBalances",
      "params": ["0x98E9D288743839e96A8005a6B51C770Bbf7788C0"]
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": {
    "0x0000000000000000000000000000000000000000": "0x7c07ef5b520cb7d"
  },
  "id": 1
}

`zks_getL2ToL1MsgProof`

Retrieves the proof for an L2 to L1 message.

Parameters

uint32 - L2 block number.
DATA, 20 bytes - sender's address.
DATA, 32 bytes - message hash.
number - Optional. The log position in L2.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "zks_getL2ToL1MsgProof",
      "params": []
    }'

Example Response

...

`zks_getL2ToL1LogProof`

Retrieves the log proof for an L2 to L1 transaction.

Parameters

DATA, 32 bytes - transaction hash.
integer - Optional. Index of the log.

Returns

proof: Array of DATA, 32 bytes - array of strings, each representing a piece of the proof for the specified log.
id: integer - identifier of the log within the transaction.
root: DATA, 32 bytes - root hash of the proof, anchoring it to a specific state in the blockchain.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "zks_getL2ToL1LogProof",
      "params": [
        "0x2a1c6c74b184965c0cb015aae9ea134fd96215d2e4f4979cfec12563295f610e"
      ]
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": {
    "proof": [
      "0x8c48910df2ca7de509daf50b3182fcdf2dd6c422c6704054fd857d6c9516d6fc",
      "0xc5028885760b8b596c4fa11497c783752cb3a3fb3b8e6b52d7e54b9f1c63521e",
      "0xeb1f451eb8163723ee19940cf3a8f2a2afdf51100ce8ba25839bd94a057cda16",
      "0x7aabfd367dea2b5306b8071c246b99566dae551a1dbd40da791e66c4f696b236",
      "0xe4733f281f18ba3ea8775dd62d2fcd84011c8c938f16ea5790fd29a03bf8db89",
      "0x1798a1fd9c8fbb818c98cff190daa7cc10b6e5ac9716b4a2649f7c2ebcef2272",
      "0x66d7c5983afe44cf15ea8cf565b34c6c31ff0cb4dd744524f7842b942d08770d",
      "0xb04e5ee349086985f74b73971ce9dfe76bbed95c84906c5dffd96504e1e5396c",
      "0xac506ecb5465659b3a927143f6d724f91d8d9c4bdb2463aee111d9aa869874db"
    ],
    "id": 0,
    "root": "0x920c63cb0066a08da45f0a9bf934517141bd72d8e5a51421a94b517bf49a0d39"
  },
  "id": 1
}

`zks_L1BatchNumber`

Retrieves the current L1 batch number.

Parameters

None

Returns

QUANTITY, 8 bytes - hexadecimal representation of the current L1 batch number.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "zks_L1BatchNumber",
      "params": []
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": "0x72af2",
  "id": 1
}

`zks_getBlockDetails`

Retrieves details for a given block.

committed: The batch is closed and the state transition it creates exists on layer 1.
proven: The batch proof has been created, submitted, and accepted on layer 1.
executed: The batch state transition has been executed on L1; meaning the root state has been updated.

Parameters

The method requires a single parameter to specify the block whose details are to be retrieved.

uint32 - number of the block.

Returns

Object containing detailed information about the specified block.

number: uint32 - number of the block.
l1BatchNumber: uint32 - corresponding L1 batch number.
timestamp: uint32 - Unix timestamp when the block was committed.
l1TxCount: uint32 - number of L1 transactions included in the block.
l2TxCount: uint32 - number of L2 transactions included in the block.
rootHash: DATA, 32 bytes - root hash of the block's state after execution.
status: String - current status of the block (e.g., verified, executed).
commitTxHash: DATA, 32 bytes - transaction hash of the commit operation on L1.
committedAt: String - timestamp when the block was committed on L1.
proveTxHash: DATA, 32 bytes - transaction hash of the proof submission on L1.
provenAt: String - timestamp when the proof was submitted on L1.
executeTxHash: DATA, 32 bytes - transaction hash of the execution on L1.
executedAt: String - timestamp when the block execution was completed on L1.
l1GasPrice: uint64 - L1 gas price at the time of the block's execution.
l2FairGasPrice: uint64 - fair gas price on L2 at the time of the block's execution.
baseSystemContractsHashes: Object - A collection of hashes for the base system contracts.
operatorAddress: DATA, 20 bytes - address of the operator who committed the block.
protocolVersion: String - version of the ZKsync protocol the block was committed under.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "zks_getBlockDetails",
      "params": [140599]
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": {
    "number": 140599,
    "l1BatchNumber": 1617,
    "timestamp": 1679815038,
    "l1TxCount": 0,
    "l2TxCount": 20,
    "rootHash": "0xf1adac176fc939313eea4b72055db0622a10bbd9b7a83097286e84e471d2e7df",
    "status": "verified",
    "commitTxHash": "0xd045e3698f018cb233c3817eb53a41a4c5b28784ffe659da246aa33bda34350c",
    "committedAt": "2023-03-26T07:21:21.046817Z",
    "proveTxHash": "0x1591e9b16ff6eb029cc865614094b2e6dd872c8be40b15cc56164941ed723a1a",
    "provenAt": "2023-03-26T19:48:35.200565Z",
    "executeTxHash": "0xbb66aa75f437bb4255cf751badfc6b142e8d4d3a4e531c7b2e737a22870ff19e",
    "executedAt": "2023-03-27T07:44:52.187764Z",
    "l1GasPrice": 20690385511,
    "l2FairGasPrice": 250000000,
    "baseSystemContractsHashes": {
      "bootloader": "0x010007793a328ef16cc7086708f7f3292ff9b5eed9e7e539c184228f461bf4ef",
      "default_aa": "0x0100067d861e2f5717a12c3e869cfb657793b86bbb0caa05cc1421f16c5217bc"
    },
    "operatorAddress": "0xfeee860e7aae671124e9a4e61139f3a5085dfeee",
    "protocolVersion": "Version5"
  },
  "id": 1
}

`zks_getTransactionDetails`

Retrieves details for a given transaction.

Parameters

DATA, 32 bytes - hash of the transaction.

Returns

Object containing detailed information about the specified transaction.

isL1Originated: Boolean - Indicates whether the transaction originated on Layer 1.
status: String - current status of the transaction (e.g., verified).
fee: QUANTITY, 32 bytes - transaction fee.
gasPerPubdata: QUANTITY, 32 bytes - gas amount per unit of public data for this transaction.
initiatorAddress: DATA, 20 bytes - address of the transaction initiator.
receivedAt: String - timestamp when the transaction was received.
ethCommitTxHash: DATA, 32 bytes - transaction hash of the commit operation.
ethProveTxHash: DATA, 32 bytes - transaction hash of the proof submission.
ethExecuteTxHash: DATA, 32 bytes - transaction hash of the execution.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "zks_getTransactionDetails",
      "params": [
        "0x22de7debaa98758afdaee89f447ff43bab5da3de6acca7528b281cc2f1be2ee9"
      ]
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": {
    "isL1Originated": true,
    "status": "verified",
    "fee": "0x0",
    "gasPerPubdata": "0x320",
    "initiatorAddress": "0x87869cb87c4fa78ca278df358e890ff73b42a39e",
    "receivedAt": "2023-03-03T23:52:24.169Z",
    "ethCommitTxHash": "0x3da5b6eda357189c9243c41c5a33b1b2ed0169be172705d74681a25217702772",
    "ethProveTxHash": "0x2f482d3ea163f5be0c2aca7819d0beb80415be1a310e845a2d726fbc4ac54c80",
    "ethExecuteTxHash": "0xdaff5fd7ff91333b161de54534b4bb6a78e5325329959a0863bf0aae2b0fdcc6"
  },
  "id": 1
}

`zks_getRawBlockTransactions`

Lists transactions in a block without processing them.

Parameters

uint32 - number of the block.

Returns

Array of objects, each representing a raw transaction within the specified block. Each transaction object includes common data, execution details, a timestamp, and the raw transaction bytes.

common_data: Object - general information about the L2 transaction, such as nonce, fees, initiator address, signature, transaction type, input data, and paymaster parameters.
execute: Object - Details regarding the execution of the transaction, including the contract address, calldata, value, and any factory dependencies.
received_timestamp_ms: Number - timestamp when the transaction was received, in milliseconds.
raw_bytes: DATA, 32 bytes - raw bytes of the transaction as a hexadecimal string.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "zks_getRawBlockTransactions",
      "params": [30098049]
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": [
    {
      "common_data": {
        "L2": {
          "nonce": 117,
          "fee": {
            "gas_limit": "0xbadbc",
            "max_fee_per_gas": "0x202fbf0",
            "max_priority_fee_per_gas": "0x0",
            "gas_per_pubdata_limit": "0xc350"
          },
          "initiatorAddress": "0xe7734c4a8201af41db64da90eddb4c19bbf64710",
          "signature": [203, 118, 119, 63, 1, 54, 91, 252, 188, 23, 120, 51, 4, 28],
          "transactionType": "EIP1559Transaction",
          "input": {
            "hash": "0x970c9480960818b05832f7e5b76a0c46956003c34942e005672d7ddc537aaa59",
            "data": [2, 249, 1, 111, 1305, 187, 2, 170, 21, 166, 251, 255]
          },
          "paymasterParams": {
            "paymaster": "0x0000000000000000000000000000000000000000",
            "paymasterInput": []
          }
        }
      },
      "execute": {
        "contractAddress": "0x5155704bb41fde152ad3e1ae402e8e8b9ba335d3",
        "calldata": "0fa0x5155704bb41fde152ad3e1ae402e8e8b9ba335d3",
        "value": "0x0",
        "factoryDeps": null
      },
      "received_timestamp_ms": 1711649348872,
      "raw_bytes": "0x02f9016f8201447580840202fbf"
    }
    // Additional transactions
  ],
  "id": 1
}

`zks_getL1BatchDetails`

Retrieves details for a given L1 batch.

Parameters

uint32 - L1 batch number.

Returns

Object of details for L1 batch.

number: uint32 - L1 batch number.
timestamp: uint64 - Unix timestamp when the batch was processed.
l1TxCount: uint32 - number of L1 transactions included in the batch.
l2TxCount: uint32 - number of L2 transactions associated with this batch.
rootHash: DATA, 32 bytes - root hash of the state after processing the batch.
status: String - current status of the batch (e.g., verified).
commitTxHash: DATA, 32 bytes - Ethereum transaction hash for the commit operation.
committedAt: String - timestamp when the batch was committed on Ethereum.
proveTxHash: DATA, 32 bytes - Ethereum transaction hash for the proof submission.
provenAt: String - timestamp when the proof was submitted.
executeTxHash: DATA, 32 bytes - Ethereum transaction hash for the execution.
executedAt: String - timestamp when the execution was completed.
l1GasPrice: uint64 - gas price on L1 at the time of batch processing.
l2FairGasPrice: uint64 - fair gas price on L2 at the time of batch processing.
baseSystemContractsHashes: Object - Hashes of the base system contracts involved in the batch.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "zks_getL1BatchDetails",
      "params": [468355]
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": {
    "number": 468355,
    "timestamp": 1711649164,
    "l1TxCount": 1,
    "l2TxCount": 2363,
    "rootHash": "0x7b31ef880f09238f13b71a0f6bfea340b9c76d01bba0712af6aa0a4f224be167",
    "status": "verified",
    "commitTxHash": "0x5b2598bf1260d498c1c6a05326f7416ef2a602b8a1ac0f75b583cd6e08ae83cb",
    "committedAt": "2024-03-28T18:24:49.713730Z",
    "proveTxHash": "0xc02563331d0a83d634bc4190750e920fc26b57096ec72dd100af2ab037b43912",
    "provenAt": "2024-03-29T03:09:19.634524Z",
    "executeTxHash": "0xbe1ba1fdd17c2421cf2dabe2908fafa26ff4fa2190a7724d16295dd9df72b144",
    "executedAt": "2024-03-29T18:18:04.204270Z",
    "l1GasPrice": 47875552051,
    "l2FairGasPrice": 25000000,
    "baseSystemContractsHashes": {
      "bootloader": "0x010007ede999d096c84553fb514d3d6ca76fbf39789dda76bfeda9f3ae06236e",
      "default_aa": "0x0100055b041eb28aff6e3a6e0f37c31fd053fc9ef142683b05e5f0aee6934066"
    }
  },
  "id": 1
}

`zks_getBytecodeByHash`

Retrieves the bytecode of a transaction by its hash.

Parameters

DATA, 32 bytes - hash of the transaction.

Returns

Array of uint8 - array of the transaction's bytecode.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "zks_getBytecodeByHash",
      "params": ["0x0100067d861e2f5717a12c3e869cfb657793b86bbb0caa05cc1421f16c5217bc"]
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": [
    0,
    4,
    0,
    ...
  ],
  "id": 1
}

`zks_getL1BatchBlockRange`

Returns the range of blocks contained within a batch given by the batch number.

The range is provided by the beginning and end block numbers in hexadecimal.

Parameters

L1BatchNumber - the layer 1 batch number.

Returns

Array of Hex Strings - array containing the beginning and end block numbers in hexadecimal.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "zks_getL1BatchBlockRange",
      "params": [12345]
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": [
    "0x116fec",
    "0x117015"
  ],
  "id": 1
}

`zks_getL1GasPrice`

Retrieves the current L1 gas price.

Parameters

None

Returns

QUANTITY, 8 bytes - current L1 gas price in hexadecimal format, representing the amount of wei per unit of gas.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "zks_getL1GasPrice",
      "params": []
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": "0x11cccd9f58",
  "id": 1
}

`zks_getFeeParams`

Retrieves the current fee parameters.

Parameters

None

Returns

Object

V2: Object - fee parameter configuration for the current version of the ZKsync protocol.
config: Object - settings related to transaction fee computation.
minimal_l2_gas_price: uint64 - minimal gas price on L2.
compute_overhead_part: float64 - compute overhead part in fee calculation.
pubdata_overhead_part: float64 - public data overhead part in fee calculation.
batch_overhead_l1_gas: uint64 - overhead in L1 gas for a batch of transactions.
max_gas_per_batch: uint64 - maximum gas allowed per batch.
max_pubdata_per_batch: uint64 - maximum amount of public data allowed per batch.
l1_gas_price: uint64 - current L1 gas price.
l1_pubdata_price: uint64 - price of storing public data on L1.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "zks_getFeeParams",
      "params": []
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": {
    "V2": {
      "config": {
        "minimal_l2_gas_price": 25000000,
        "compute_overhead_part": 0,
        "pubdata_overhead_part": 1,
        "batch_overhead_l1_gas": 800000,
        "max_gas_per_batch": 200000000,
        "max_pubdata_per_batch": 240000
      },
      "l1_gas_price": 46226388803,
      "l1_pubdata_price": 100780475095
    }
  },
  "id": 1
}

`zks_getProtocolVersion`

Gets the protocol version.

Parameter

uint16 - Optional. Specific version ID.

Returns

Object

version_id: uint16 - protocol version ID.
timestamp: uint64 - Unix timestamp of the version's activation.
verification_keys_hashes: Object - Contains the hashes of various verification keys used in the protocol.
base_system_contracts: Object - Hashes of the base system contracts, like the bootloader and default account abstraction (AA).
l2_system_upgrade_tx_hash: DATA, 32 bytes - hash of the transaction used for the system upgrade, if any.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "zks_getProtocolVersion",
      "params": []
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": {
    "version_id": 22,
    "timestamp": 1710264138,
    "verification_keys_hashes": {
      "params": {
        "recursion_node_level_vk_hash": "0x5a3ef282b21e12fe1f4438e5bb158fc5060b160559c5158c6389d62d9fe3d080",
        "recursion_leaf_level_vk_hash": "0x400a4b532c6f072c00d1806ef299300d4c104f4ac55bd8698ade78894fcadc0a",
        "recursion_circuits_set_vks_hash": "0x0000000000000000000000000000000000000000000000000000000000000000"
      },
      "recursion_scheduler_level_vk_hash": "0x063c6fb5c70404c2867f413a8e35563ad3d040b1ad8c11786231bfdba7b472c7"
    },
    "base_system_contracts": {
      "bootloader": "0x010007ede999d096c84553fb514d3d6ca76fbf39789dda76bfeda9f3ae06236e",
      "default_aa": "0x0100055b041eb28aff6e3a6e0f37c31fd053fc9ef142683b05e5f0aee6934066"
    },
    "l2_system_upgrade_tx_hash": null
  },
  "id": 1
}

`zks_getProof`

This method generates Merkle proofs for one or more storage values associated with a specific account, accompanied by a proof of their authenticity. It verifies that these values remain unaltered.

Similar to Ethereum's eth_getProof, this method provides verification means under ZKsync Era's distinct Merkle tree architecture, noting several key differences:

The retrieval of values and their respective proofs is determined by an L1 batch number instead of a block number.
ZKsync Era employs a different Merkle tree structure, necessitating a unique approach to proof verification. Unlike Ethereum's two-level hexadecimal trie—where the top level maps to accounts and the bottom to account storage slots—Era uses a single-level, full binary tree with 256-bit keys.
In Ethereum, account-level values are mapped using specific combinations of account and storage keys. For example, to store the code hash for account address A, it uses account 0x0000000000000000000000000000000000008002 and a storage key generated by padding A's address. Conversely, ZKsync Era's Merkle tree specifics are as follows:

ZKsync Era Merkle Tree Details:

The tree is a one-level, full binary tree, supporting 256-bit keys and 40-byte values.
Keys are derived by reversing the output of reversed(blake2s256([0_u8; 12] ++ account_address ++ storage_key)), where account_address is the 20-byte address, and storage_key is a 32-byte key from the account's storage. The ++ operator denotes byte concatenation, and reversed inverts the byte sequence order.
Values are structured as big_endian(leaf_index) ++ storage_value, with leaf_index marking the 1-based index in entry order, and storage_value representing the 32-byte slot value.
Empty tree entries are marked with 40 zero bytes ([0_u8; 40]).
Leaf hashing utilizes blake2s256 without tags, treating vacant leaves as blake2s256([0_u8; 40]).
Internal node hashes are computed by concatenating the hashes of their child nodes, again using blake2s256 without tags: blake2s256(left_child_hash ++ right_child_hash)

Parameters

DATA, 20 bytes - account address to fetch storage values and proofs for.
Array of Data, 32 bytes - the keys in the account.
uint32 - Number of the L1 batch specifying the point in time at which the requested values are returned.

Returns

The method returns an object containing the account details and proofs for storage keys. The structure of the returned object is as follows:

address: account address associated with the storage proofs.
storageProof: array of objects, each representing a storage proof for the requested keys.
- key: DATA, 32 bytes - storage key for which the proof is provided.
- value: DATA, 32 bytes - value stored in the specified storage key at the time of the specified l1BatchNumber.
- index: uint64 - A 1-based index representing the position of the tree entry within the Merkle tree. This index is used to help reconstruct the Merkle path during verification.
- proof: Array of DATA, 32 bytes - An array of 32-byte hashes that constitute the Merkle path from the leaf node (representing the storage key-value pair) to the root of the Merkle tree. The path is ordered from the root to the leaf. The root hash itself is not included in this array because it is published on L1 as part of the L1 batch commit data. If the proof array contains fewer than 256 hashes, it means that some hashes corresponding to entirely empty subtrees are omitted starting from the end of the Merkle path. For instance, if there are 255 hashes in the proof, the single omitted hash is the hash of an empty subtree (empty_value_hash = blake2s256([0_u8; 40])). Further, omitted hashes are calculated progressively as hashes of the concatenated pair of the previous level's omitted hash (e.g., blake2s256(empty_value_hash ++ empty_value_hash)), and so on, indicating progressively higher levels of empty subtrees in the Merkle tree.

Using the information in each storageProof, one can reconstruct the Merkle tree's root hash for a given storage key and compare it to the reference root hash published on L1. If the two hashes match, it confirms the authenticity of the provided storage value for the given key.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "zks_getProof",
      "params": [
        "0x0000000000000000000000000000000000008003",
        [
          "0x8b65c0cf1012ea9f393197eb24619fd814379b298b238285649e14f936a5eb12"
        ],
        354895
      ]
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": {
    "address": "0x0000000000000000000000000000000000008003",
    "storageProof": [
      {
        "key": "0x8b65c0cf1012ea9f393197eb24619fd814379b298b238285649e14f936a5eb12",
        "proof": [
          "0xe3e8e49a998b3abf8926f62a5a832d829aadc1b7e059f1ea59ffbab8e11edfb7",
          ...
        ],
        "value": "0x0000000000000000000000000000000000000000000000000000000000000060",
        "index": 27900957
      }
    ]
  },
  "id": 1
}

`zks_sendRawTransactionWithDetailedOutput`

Executes a transaction and returns its hash, storage logs, and events that would have been generated if the transaction had already been included in the block. The API has a similar behaviour to eth_sendRawTransaction but with some extra data returned from it.

With this API Consumer apps can apply "optimistic" events in their applications instantly without having to wait for ZKsync block confirmation time.

It’s expected that the optimistic logs of two uncommitted transactions that modify the same state will not have causal relationships between each other.

Inputs

Parameter	Type	Description
`data`	`string`	The signed transaction. Typically, signed with a library such as ethers.js.

Example Request

curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"zks_sendRawTransactionWithDetailedOutput","params":["Signed Transaction"],"id":1}' \
"https://mainnet.era.zksync.io"

Example Response

{
  "jsonrpc": "2.0",
  "result": {
    "transactionHash": "0xd586a9381ac33a70d1c34704664209242ee90316878fc1695aa8e4cf553c8595",
    "storageLogs": [
      {
        "address": "0x000000000000000000000000000000000000800b",
        "key": "0x7",
        "writtenValue": "0x40000000000000000000000006641f961"
      },
      {
        "address": "0x000000000000000000000000000000000000800b",
        "key": "0x6",
        "writtenValue": "0x5f5e100"
      },
      {
        "address": "0x000000000000000000000000000000000000800b",
        "key": "0x9",
        "writtenValue": "0xc0000000000000000000000006641f961"
      },
      {
        "address": "0x000000000000000000000000000000000000800b",
        "key": "0x16",
        "writtenValue": "0xe1ef29fc6c51f74bbdef5bc1406e3c9925d89c5b1f79215648b82ac15419bcbe"
      },
      {
        "address": "0x000000000000000000000000000000000000800b",
        "key": "0xa",
        "writtenValue": "0x0"
      },
      {
        "address": "0x000000000000000000000000000000000000800b",
        "key": "0x10c",
        "writtenValue": "0xc0000000000000000000000006641f961"
      },
      {
        "address": "0x000000000000000000000000000000000000800b",
        "key": "0xa",
        "writtenValue": "0xe3ed371c32f62f3b3a28d51b909b2668e293c6cbfa4b4fd549c8f00a9a93a296"
      },
      {
        "address": "0x000000000000000000000000000000000000800b",
        "key": "0x110",
        "writtenValue": "0x0"
      },
      {
        "address": "0x000000000000000000000000000000000000800b",
        "key": "0x10f",
        "writtenValue": "0x88"
      },
      {
        "address": "0x000000000000000000000000000000000000800b",
        "key": "0x1",
        "writtenValue": "0x8001"
      },
      {
        "address": "0x000000000000000000000000000000000000800b",
        "key": "0x2",
        "writtenValue": "0x5f5e100"
      },
      {
        "address": "0x0000000000000000000000000000000000008003",
        "key": "0xeaa2b2fbf0b42c559059e5e9510edc15755f1c1883f0e41d5ba5f9aea4ac201a",
        "writtenValue": "0x4"
      },
      {
        "address": "0x000000000000000000000000000000000000800a",
        "key": "0xeaa2b2fbf0b42c559059e5e9510edc15755f1c1883f0e41d5ba5f9aea4ac201a",
        "writtenValue": "0x55ce6fa97340"
      },
      {
        "address": "0x000000000000000000000000000000000000800a",
        "key": "0x31b66141c575a054316a84da9cf4aa6fe0abd373cab1bf4ac029ffc061aae0da",
        "writtenValue": "0xb9b031bf400"
      },
      {
        "address": "0x000000000000000000000000000000000000800b",
        "key": "0x1",
        "writtenValue": "0x36615cf349d7f6344891b1e7ca7c72883f5dc049"
      },
      {
        "address": "0x000000000000000000000000000000000000800b",
        "key": "0x1",
        "writtenValue": "0x8001"
      },
      {
        "address": "0x000000000000000000000000000000000000800a",
        "key": "0x31b66141c575a054316a84da9cf4aa6fe0abd373cab1bf4ac029ffc061aae0da",
        "writtenValue": "0xa7557c54f00"
      },
      {
        "address": "0x000000000000000000000000000000000000800a",
        "key": "0xeaa2b2fbf0b42c559059e5e9510edc15755f1c1883f0e41d5ba5f9aea4ac201a",
        "writtenValue": "0x56f41b001840"
      }
    ],
    "events": [
      {
        "address": "0x000000000000000000000000000000000000800a",
        "topics": [
          "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
          "0x00000000000000000000000036615cf349d7f6344891b1e7ca7c72883f5dc049",
          "0x0000000000000000000000000000000000000000000000000000000000008001"
        ],
        "data": "0x00000000000000000000000000000000000000000000000000000b9b031bf400",
        "blockHash": null,
        "blockNumber": null,
        "l1BatchNumber": "0x4",
        "transactionHash": "0xd586a9381ac33a70d1c34704664209242ee90316878fc1695aa8e4cf553c8595",
        "transactionIndex": "0x0",
        "logIndex": null,
        "transactionLogIndex": null,
        "logType": null,
        "removed": false
      },
      {
        "address": "0x000000000000000000000000000000000000800a",
        "topics": [
          "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
          "0x0000000000000000000000000000000000000000000000000000000000008001",
          "0x00000000000000000000000036615cf349d7f6344891b1e7ca7c72883f5dc049"
        ],
        "data": "0x00000000000000000000000000000000000000000000000000000125ab56a500",
        "blockHash": null,
        "blockNumber": null,
        "l1BatchNumber": "0x4",
        "transactionHash": "0xd586a9381ac33a70d1c34704664209242ee90316878fc1695aa8e4cf553c8595",
        "transactionIndex": "0x0",
        "logIndex": null,
        "transactionLogIndex": null,
        "logType": null,
        "removed": false
      }
    ]
  },
  "id": 1
}

Conventions

Formatting conventions and references for use with ZKsync Era API docs.

Debug JSON-RPC API

Methods useful for debugging purposes with ZKsync Era.