Home GitHub Blog Explorer

JSON-RPC API

dApps can get account status, send transactions, and call other functions via zkLink API.

The zkLink API follows the JSON-RPC standard and is accessed via POST.

API OVERVIEW

JSON-RPC API METHODS

getSupportChains

Get the configuration of all supported chains.

Parameters

None

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "getSupportChains",
    "params": []
}

ChainResp

FieldTypeDescription

chainId

uint32

Defined by zkLink

chainType

uint8

Defined by zkLink {0:"EVM", 1:"STARKNET"}

layerOneChainId

uint32

The chain ID of L1 blockchains

mainContract

address(EVM|StarkNet)

The address of zkLink main contract that interacts with the rest module contracts

layerZeroContract

address(EVM|StarkNet)

The address of layerZero bridge that syncs L1 states

web3Url

string

The url of L1 RPC

feeCap

unit

The max transaction fee when L1 RPC send the transaction

gasTokenId

uint32

The id of the gas token, defined by zkLink

validator

address(EVM|StarkNet)

Validator address

getSupportTokens

Get the data of all tokens with on-chain contract addresses.

Parameters

None

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "getSupportTokens",
    "params": []
}

It returns a HashMap<TokenId,TokenResp>, which has a unique token id and is used for all token-related queries in the RPC service. Symbols are used only for display on the UI and do not promise uniqueness.

TokenResp

FieldDescription

id

Token id

symbol

Token symbol

usdPrice

Token price

chains

HashMap<ChainId,ChainTokenResp> that includes the contract addresses on each chain

ChainTokenResp

FieldDescription

chainId

Defined by zkLink

address

The on-chain contract address of the token

decimals

The decimals of the token on L1

fastWithdraw

Whether the token supports fast withdraw

The decimal is the accuracy of the token on L1, which is not always 18 (6 for USDC and 18 for ZKL), and varies on different chains for the same token (6 for USDC on Ethereum and 18 for USDC on BSC).

When a user deposits to zkLink from connected networks, the front-end needs to calculate the amount required for calling the contract according to the accuracy:

var amount_of_user_input = 1.0 // input from the user
var amount_to_call_contract = amount_of_user_input * 10 ** token.decimals // the parameter during calling the contract
// Example
// A user deposits 2 USDC, the parameter is 2 * 10^6
// A user deposits 5 ZKL, the parameter is 5 * 10^18

getLatestBlockNumber

Get the latest block height info.

Parameters

None

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "getLatestBlockNumber",
    "params": []
}

BlockNumberResp

FieldDescription

lastBlockNumber

The block height of the latest batch

timestamp

The timestamp of the last block

committed

The block height of the latest block committed to L1

verified

The block height of the latest block executed on L1

getBlockByNumber

Get the block info by block height.

Parameters

  • blockNumber: the block height, and returns the latest block height if null

  • includeTx : whether contains transaction details: returns transaction hash if false. only successful transactions will be included in a block. call getTransactionByHash to query the failed transactions.

  • includeUpdate: whether contains the state change by transactions; valid only when includeTx is true.

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "getBlockByNumber",
    "params": [
      123, 
      true, 
      true 
    ]
}

BlockResp

FieldDescription

number

The block height

commitment

The commitment of the block, similar to the block hash of Ethereum

rootHash

The root hash of the state tree

feeAccountId

The id of the fee account

blockSize

The maximum chunk number that a block can contain

opsCompositionNumber

The vk of generating ZKPs

timestamp

The block timestamp

transactions

Returns [BlockTxResp] when includeTx is false, TxResp when true; ordered by transaction execution: the ones executed first come first in the array

BlockTxResp

FieldDescription

txHash

The transaction hash

tx

ZkLinkTx

executedTimestamp

The unix timestamp of transaction execution

updates

[StateUpdateResp], ordered by updateId: the ones executed first come first in the array

StateUpdateResp

The success of transaction execution will lead to the change of the state tree:

  • AccountCreate: create a new account in the state tree

  • AccountChangePubkeyUpdate: change in pubkey and nonce

  • BalanceUpdate: change in account balance and nonce

  • OrderUpdate: change in account slot

AccountCreate

FieldDescription

type

AccountCreate

updateId

The position of the update in the block

accountId

The id of the new account

address

The account address

Example:

{
  "type": "AccountCreate",
  "updateId": 40,
  "accountId": 42,
  "address": "0xe4efc3d7b69a19d3ae574cbc2915ddf598efe43f"
}

Transactions that may generate AccountCreate include:

  • Deposit

  • Transfer

AccountChangePubkeyUpdate

FieldDescription

type

AccountChangePubkeyUpdate

updateId

The position of the update in the block

accountId

The account id

oldPubkeyHash

The old pubkeyHash

newPubkeyHash

The new pubkeyHash

oldNonce

The old nonce

newNonce

The new nonce

Example:

{
  "type": "AccountChangePubkeyUpdate",
  "updateId": 10,
  "accountId": 39,
  "oldPubkeyHash": "0x0000000000000000000000000000000000000000",
  "newPubkeyHash": "0xbfb4f4a68dc9e49f7785082a8c12354ed663b6e0",
  "oldNonce": 0,
  "newNonce": 1
}

only ChangePubKey will generate AccountChangePubkeyUpdate

BalanceUpdate

FieldDescription

type

BalanceUpdate

updateId

The position of the update in the block

accountId

The account id

subAccountId

The id of the sub account

coinId

Token id

oldBalance

The balance of the sub account before change

newBalance

The balance of the sub account after change

oldNonce

The old nonce

newNonce

The new nonce

Example:

{
  "type": "BalanceUpdate",
  "updateId": 1,
  "accountId": 2,
  "subAccountId": 1,
  "coinId": 18,
  "oldBalance": "66517000000000000",
  "newBalance": "66518000000000000",
  "oldNonce": 66518,
  "newNonce": 66519
}

All ZkLinkTx will generate BalanceUpdate

OrderUpdate

FieldDescription

type

OrderUpdate

updateId

The position of the update in the block

accountId

The account id

subAccountId

The id of the sub account

coinId

Token id

oldTidyOrder

The TidyOrder before change

newTidyOrder

The TidyOrder after change

TidyOrder

FieldDescription

nonce

Slot nonce

residue

Slot residue

Example:

{
  "type": "OrderUpdate",
  "updateId": 30,
  "accountId": 11,
  "subAccountId": 1,
  "slotId": 27,
  "oldTidyOrder": {
    "nonce": 14,
    "residue": "4607200000000000000000"
  },
  "newTidyOrder": {
    "nonce": 14,
    "residue": "4233800000000000000000"
  }
}

Only OrderMatching will generate OrderUpdate

getPendingBlock

Get info of transactions waiting to be batched.

Parameters

  • transaction execution time, the timestamp in the return can only be bigger than it.

  • includeTx: whether to include transaction details. False: return transaction hash only. Only successful transactions will be batched in the block. Call getTransactionByHash to query failed transaction details.

  • includeUpdate: whether to include the state change by the transaction. Valid only when includeTx is true.

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "getPendingBlock",
    "params": [
      1689731233,
      true,
      true
    ]
}

getBlockOnChainByNumber

Get transaction information in a block executed on L1 blockchains. Every block will be submitted to and executed on every L1 chain.

Parameters

  • chain_id

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "getBlockOnChainByNumber",
    "params": [4906]
}

BlockOnChainResp

FieldDescription

committed

Transaction info committed to L1, with type OnChainResp

verified

Transaction info executed on L1, with type OnChainResp

OnChainResp

FieldDescription

chain_id

The chain id defined by zkLink

tx_hash

The hash of the transaction on L1 blockchains

Noted that since blocks are committed to and executed on L1 blockchains in batches, the on-chain data of blocks in the same batch is the same. For example, when blocks [4906, 4910] are in the same batch, their on-chain transaction info is the same.

Commitment and batching are asynchronous. For example, when the current block height is 1000, the committed block height can be 980, and the verified block height can be 950. The API caller should query the on-chain infor by the committed and verified block height via getLatestBlockNumber. For example, when the latest verified block height is 950, the return of the on-chain block info that is after 950 must be null.

getAccount

Get account info by address or account id.

Parameters

  • Address|AccountID - Address(20Bytes or 32Bytes) or integer account id.

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "getAccount",
    "params": [
        "0x1aef2b4c06b83cdb2783d3458cdbf3886a6ae7d4"
    ]
}

AccountInfoResp

FieldDescription

id

Account id

address

Account address

nonce

Account nonce

pubKeyHash

Account pubKeyHash

subAccountNonces

Nonce of the subaccount, HashMap<SubAccountId,Nonce>

pubKeyHash being 0x0000000000000000000000000000000000000000 means unactivated account.

getAccountBalances

Get the balance info of an account.

Parameters:

  • accountId: account id

  • subAccountId: optional, the id of the subaccount; null if the query requests the balance of all subaccounts.

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "getAccountBalances",
    "params": [
        1,
        0
    ]
}

getAccountOrderSlots

Get the order slot of an account.

Parameters

  • accountId: account id

  • subAccountId: optional, the id of the subaccount; null if the query requests the balance of all subaccounts.

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "getAccountOrderSlots",
    "params": [
        1,
        null
    ]
}