HomeGitHubBlogExplorer

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

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

ChainTokenResp

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

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

BlockTxResp

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

Example:

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

Transactions that may generate AccountCreate include:

  • Deposit

  • Transfer

AccountChangePubkeyUpdate

Example:

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

only ChangePubKey will generate AccountChangePubkeyUpdate

BalanceUpdate

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

TidyOrder

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

OnChainResp

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

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
    ]
}

getTokenReserve

Get the withdrawable limit of a token on a certain L1 chain. There are 3 cases:

Parameters

  • tokenId: tokenId

  • mapping: whether to query mapping, valid only when tokenId corresponds to USD stable.

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "getTokenReserve",
    "params": [
      17,
      true
    ]
}

getAccountSnapshot

In zkLink v0.4.0, transactions are executed before being batched, thus the APIs that request account states may not return the states in the latest block. The related APIs include:

  • getAccount

  • getAccountBalances

  • getAccountOrderSlots

  • getTokenReserve

getAccountSnapshot is introduced to request the account states of a certain block height, including the basic info, balance info, and order slot info.

Parameters:

  • accountAddress or accountId

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

  • blockNumber: optional, null to return the latest block snapshot

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "getAccountSnapshot",
    "params": [
      10,
      1,
      103
    ]
}

AccountSnapshotResp

getTransactionByHash

Get transaction info.

Parameters:

  • txHash

  • includeUpdate: whether to include the state change by the transaction

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "getTransactionByHash",
    "params": [
        "0x3210bb3d6719d730b30c4c9a0086d507040e25f83bea4ff4b8c2c91bf8e8c4f9",
      	true
    ]
}

TxResp

TxReceiptResp

getAccountTransactionHistory

Get account history in descending order of the transaction id in the database. Current only Deposit, Withdraw, and Transfer are supported.

Parameters

  • Deposit, Withdraw or Transfer

  • account address

  • the page index, starting from 0

  • the page size

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "getAccountTransactionHistory",
    "params": [
        "Deposit",
        "0xdc9c9863167ee865edd5216964b8b99d43ee7a81",
      	0,
        100
    ]
}

Page<ZkLinkTxHistory>

ZkLinkHistory

Deposit: returns the transaction history of which the account address equals to_address;

Withdraw: returns the transaction history of which the account address equals from_address;

Transfer: returns the transaction history of which the account address equals either to_address or from_address.

getWithdrawTxs

Get transaction info of withdraw transactions.

Parameters:

  • lastTxTimestamp: ISO 8601 standard with date, time, and time zone;

  • maxTxs: the max value of the number of Withdraw in the return.

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "getWithdrawTxs",
    "params": [
        "2023-02-03T16:41:10.744899Z",
        10
    ]
}

FastWithdrawTxResp

zkLink will scan the maxTxs number of executed withdraw transactions, and returns the fast_withdraw transactions among which; thus the number of returns might be less than maxTxs, even be 0.

In the first scan, lastTxTimestamp can be set as 0 to scan from the beginning. Then the executedTimestamp of the last record can be used as the lastTxTimestamp of the next scan.

getEthProperty

Get all the information about the Ethereum property.

GateWayInfo

TokenInfo

{
  "chainId": 4,
  "layerOneChainId": "0x1",
  "gateways": [
    {
      "chainId": 5,
      "l1GatewayContract": "0x3498f456645270ee003441df82c718b56c0e6666",
      "l2GatewayContract": "0x3498f456645270ee003441df82c718b56c0e6666",
      "tokens": [
        {
          "tokenId": 1,
          "tokenAddress":"0x3498f456645270ee003441df82c718b56c0e6666",
          "decimal": 6,
          "fastWithdraw": true
        },
        {
          "tokenId": 3,
          "tokenAddress":"0x3498f456645270ee003441df82c718b56c0e6666",
          "decimal": 7,
          "fastWithdraw": false
        }
      ]
    },
    {
      "chainId": 7,
      "l1GatewayContract": "0x3498f456645270ee003441df82c718b56c0e6666",
      "l2GatewayContract": "0x3498f456645270ee003441df82c718b56c0e6666",
      "tokens": [
        {
          "tokenId": 1,
          "tokenAddress":"0x3498f456645270ee003441df82c718b56c0e6666",
          "decimal": 6,
          "fastWithdraw": true
        },
        {
          "tokenId": 3,
          "tokenAddress":"0x3498f456645270ee003441df82c718b56c0e6666",
          "decimal": 6,
          "fastWithdraw": false
        }
      ]
    }
  ]
}

sendTransaction

Submit L2 transaction and return transaction hash.

Parameters:

  • ZkLinkTx: L2 transaction

  • Layer1Signature: layer1 signature with type Option<TxLayer1Signature>; required for Layer2 transactions apart from ChangePubKey or OrderMatching.

  • submitterSignature: Option<ZkLinkSignature>, required only when the transaction involves subaccounts (except #0 subaccount); submitterSignature is a zk signature to tx hash.

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "sendTransaction",
    "params": [
        {
            "accountId": 8,
            "fromSubAccountId": 3,
            "toSubAccountId": 3,
            "from": "0x3498F456645270eE003441df82C718b56c0e6666",
            "to": "0xbfDa941Bd2a0eddB57b10f8E8d3486A738B92cCC",
            "tokenId": 3,
            "amount": "998000000000000000",
            "fee": "3000000000000000",
            "ts": 1646101085,
            "nonce": 1,
            "type": "Transfer",
            "token": 3,
            "signature": {
                "pubKey": "0dd4f603531bd78bbecd005d9e7cc62a794dcfadceffe03e269fbb6b72e9c724",
                "signature": "892c622afac908201df54a3cfdecf8eba46d5411bdc29365f5536f024c195f2893d6313a6371fe1659830e2560c1eaedbafcc835837593d017cd557074f0bb03"
            }
        },
        {
            "type": "EthereumSignature",
            "signature": "0xc29d647a5e9e078c66594f04881c34d6b57e1085ab825f17ffb1d0fe233e9834191b374daaaf1e44e5749f6cf44f2143799373fc5e7e844d48fec5e6bc08f0651b"
        },
      	null
    ]
}

TxLayer1Signature

L1 signatures apply EIP-191 specification with zkLink Eth sig message.

Examples:

{
  "type": "EthereumSignature",
  "signature": "0xc29d647a5e9e078c66594f04881c34d6b57e1085ab825f17ffb1d0fe233e9834191b374daaaf1e44e5749f6cf44f2143799373fc5e7e844d48fec5e6bc08f0651b"
}
{
  "type": "EIP1271Signature",
  "signature": "0xc29d647a5e9e078c66594f04881c34d6b57e1085ab825f17ffb1d0fe233e9834191b374daaaf1e44e5749f6cf44f2143799373fc5e7e844d48fec5e6bc08f0651b"
}

ZkLinkSignature

Signatures for L2 transactions use zkLink Encode.

Example:

{
  "pubKey": "0x0dd4f603531bd78bbecd005d9e7cc62a794dcfadceffe03e269fbb6b72e9c724",
  "signature": "892c622afac908201df54a3cfdecf8eba46d5411bdc29365f5536f024c195f2893d6313a6371fe1659830e2560c1eaedbafcc835837593d017cd557074f0bb03"
}

version: 7df6cd1

PreviousJSON RPC & Websocket & KafkaNextJSON-RPC Errors

Last updated