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

Networks

• getSupportChains: get the configuration of all supported chains.

• getSupportTokens: get the data of all tokens with on-chain contract addresses.

• getLatestBlockNumber: get the latest block height info.

• getTokenReserve: get the withdrawable limit of a token on a certain L1 chain.

Block

• getBlockByNumber: get the block info by block height.

• getBlockOnChainByNumber: get the transaction information in a block that is executed on L1 blockchains.

Account

• getAccount: get account info by address or account id.

• getAccountBalances: get the balance info of an account.

• getAccountOrderSlots: get the order slot of an account.

• getAccountSnapshot: get the account states of a certain block height, including the basic info, balance info, and order slot info.

Transaction

• getTransactionByHash: get transaction info.

• getAccountTransactionHistory: get account history in descending order of the transaction id in the database.

• getWithdrawTxs: get transaction info of fast_withdraw transactions.

• sendTransaction: submit L2 transaction and return transaction hash.

JSON-RPC API METHODS

getSupportChains

Get the configuration of all supported chains.

Request

Parameters

None

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

Response

Returns

ChainResp

{
    "jsonrpc": "2.0",
    "result": [
      {
        "chainId":1,
        "chainType": 0,
        "layerOneChainId":1001,
        "mainContract":"0x03855e8120691526f82085453AEefac3f6A484F1",
        "layerZeroContract": "0xcb45b54BA16fBdc7092E56938225a11799eb1124",
        "web3Url": "https://rpc-mumbai.maticvigil.com",
        "feeCap": 1000000000000000000,
        "gasTokenId": 33,
        "validator": "0x526212fbd41080b455ae81014b5b6bf859c30094"
      }
    ],
    "id": 1
}

ChainResp

Field	Type	Description
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.

Request

Parameters

None

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

Response

Returns

HashMap<TokenId,TokenResp>

{
    "jsonrpc": "2.0",
    "result": {
        "1": {
            "id": 1,
            "symbol": "ZKL",
          	"usdPrice": "12.1",
            "chains": {
                "1": {
                    "chainId": 1,
                    "address": "0x1aef2b4c06b83cdb2783d3458cdbf3886a6ae7d4",
                  	"decimals": 18,
                    "fastWithdraw": false
                },
                "2": {
                    "chainId": 2,
                    "address": "0xa684f63605ccdedbce7e2e7e3fa06441758da6d1",
                  	"decimals": 10,
                    "fastWithdraw": true
                }
            }
        }
    },
    "id": 1
}

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

Field	Description
id	Token id
symbol	Token symbol
usdPrice	Token price
chains	HashMap<ChainId,ChainTokenResp> that includes the contract addresses on each chain

ChainTokenResp

Field	Description
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.

Request

Parameters

None

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

Response

Returns

BlockNumberResp

{
    "jsonrpc": "2.0",
    "result": {
        "lastBlockNumber": 2,
        "timestamp": 1663488014,
        "committed": 1,
        "verified": 0 
    },
    "id": 1
}

BlockNumberResp

Field	Description
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.

Request

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

Response

Returns

BlockResp

{
  "jsonrpc": "2.0",
  "result": {
    "number": 14127,
    "commitment": "0x052fdba72bbb6fcc10940fc22dc76e459dda32604a17a920b8f2d2d0f0caff8f",
    "rootHash": "0x2a5bb557a7b39afc2480b84c56f230ac2be6148fc367edf5f9447e3521a0da56",
    "feeAccountId": 0,
    "blockSize": 20,
    "opsCompositionNumber": 401,
    "createdAt": "2023-02-04T04:41:35Z",
    "transactions": [
      {
        "txHash": "0x7c85b50664efb9672613b2b3ceafd6e1f9f47938053690b885f0a8071fac1ffa",
        "tx": {
          "type": "Deposit",
          "fromChainId": 2,
          "from": "0x3d809e414ba4893709c85f242ba3617481bc4126",
          "subAccountId": 0,
          "l1SourceToken": 18,
          "l2TargetToken": 18,
          "amount": "10000000000000000000",
          "to": "0xb92a8ba62ff1d141798c7133cccefb33d9073323",
          "serialId": 22,
          "ethHash": "0x6ac27ec5de06c51dc9f167aa13424d08026953c9706d39c72d64cabe59ad7266"
        },
        "executedTimestamp":1689731233,
        "updates": [
          {
            "type": "AccountCreate",
            "updateId": 15,
            "accountId": 4,
            "address": "0xb92a8ba62ff1d141798c7133cccefb33d9073323"
          },
          {
            "type": "BalanceUpdate",
            "updateId": 16,
            "accountId": 4,
            "subAccountId": 0,
            "coinId": 18,
            "oldBalance": "0",
            "newBalance": "10000000000000000000",
            "oldNonce": 0,
            "newNonce": 0
          },
          {
            "type": "BalanceUpdate",
            "updateId": 17,
            "accountId": 1,
            "subAccountId": 2,
            "coinId": 18,
            "oldBalance": "3030000000000000000000",
            "newBalance": "3040000000000000000000",
            "oldNonce": 0,
            "newNonce": 0
          }
        ]
      },
      {
        "txHash": "0x7aaf7535c5edecf19805b6395e92865c544f387c71d8f75648d0353100a821f6",
        "tx": {
          "type": "FullExit",
          "toChainId": 1,
          "accountId": 28,
          "subAccountId": 1,
          "exitAddress": "0xae08c2e27765faef5cb05908dbac12242caf91af",
          "l2SourceToken": 44,
          "l1TargetToken": 44,
          "serialId": 28,
          "ethHash": "0x57b1fda1f7dd3aac85af60dc69300e0209c0a6abadc047a8f88e0a894220ba82"
        },
        "executedTimestamp":1689731234,
        "updates": [
          {
            "type": "BalanceUpdate",
            "updateId": 0,
            "accountId": 28,
            "subAccountId": 1,
            "coinId": 44,
            "oldBalance": "1080000000000000000",
            "newBalance": "0",
            "oldNonce": 0,
            "newNonce": 0
          },
          {
            "type": "BalanceUpdate",
            "updateId": 1,
            "accountId": 1,
            "subAccountId": 1,
            "coinId": 44,
            "oldBalance": "1497300000000000000000",
            "newBalance": "1496220000000000000000",
            "oldNonce": 0,
            "newNonce": 0
          }
        ]
      },
      {
        "txHash": "0x7c2dab9dadc2f3471b71c5531bfa70d0a67d16df62cfd6ed43b5970b3dccf7ad",
        "tx": {
          "type": "ChangePubKey",
          "chainId": 2,
          "accountId": 2,
          "subAccountId": 0,
          "newPkHash": "0x870b67b523f93dad7a313f6b64b9608dedab3874",
          "feeToken": 18,
          "fee": "1000000000000000000",
          "nonce": 0,
          "signature": {
            "pubKey": "5f07954b65b5407a37ec0a2c54fb4647e2014475936057bb2f52a6faab938b02",
            "signature": "4ad95ddd573830c2e85065ee201e503b24fb56faeedc1790e8a35668805d7b00691cb8c78ce124fbe0c15ed903c72975750eb12f74a5c711b870fba3496f0402"
          },
          "ethAuthData": {
            "type": "EthECDSA",
            "ethSignature": "0xf8aa40b44c89e3be8a07fc25e90b9c069fde2f3fb01125f9a8683fba054b5b4961ccbc6e957fda303c64868d9f6bc3b0f8c55a38137195633f330573a813a5d31b"
          },
          "ts": 1677821209
        },
        "executedTimestamp":1689731235,
        "updates": [
          {
            "type": "AccountChangePubkeyUpdate",
            "updateId": 8,
            "accountId": 2,
            "oldPubkeyHash": "0x0000000000000000000000000000000000000000",
            "newPubkeyHash": "0x870b67b523f93dad7a313f6b64b9608dedab3874",
            "oldNonce": 0,
            "newNonce": 1
          },
          {
            "type": "BalanceUpdate",
            "updateId": 9,
            "accountId": 2,
            "subAccountId": 0,
            "coinId": 18,
            "oldBalance": "10000000000000000000",
            "newBalance": "9000000000000000000",
            "oldNonce": 1,
            "newNonce": 1
          },
          {
            "type": "BalanceUpdate",
            "updateId": 10,
            "accountId": 0,
            "subAccountId": 0,
            "coinId": 18,
            "oldBalance": "0",
            "newBalance": "1000000000000000000",
            "oldNonce": 0,
            "newNonce": 0
          }
        ]
      },
      {
        "txHash": "0xa2fa942af20e3ea1764158470a9f1f5609280dcd73cad5497ecf5ec20e8cad83",
        "tx": {
          "type": "Transfer",
          "accountId": 2,
          "fromSubAccountId": 0,
          "toSubAccountId": 1,
          "to": "0xdc9c9863167ee865edd5216964b8b99d43ee7a81",
          "token": 18,
          "amount": "1000000000000",
          "fee": "209000000000000",
          "nonce": 115,
          "signature": {
            "pubKey": "5f07954b65b5407a37ec0a2c54fb4647e2014475936057bb2f52a6faab938b02",
            "signature": "d6501c14f1ed8e3feeb4c3242697067dd60da0c56af544c8faeb2d055a21d3059c78c320008028f37fedc4d9578553782b2fd204610da670d1326a277dac2004"
          },
          "ts": 1677821506
        },
         "executedTimestamp":1689731236,
        "updates": [
          {
            "type": "BalanceUpdate",
            "updateId": 12,
            "accountId": 2,
            "subAccountId": 0,
            "coinId": 18,
            "oldBalance": "3018976060000000000000",
            "newBalance": "3018975850000000000000",
            "oldNonce": 115,
            "newNonce": 116
          },
          {
            "type": "BalanceUpdate",
            "updateId": 13,
            "accountId": 2,
            "subAccountId": 1,
            "coinId": 18,
            "oldBalance": "114000000000000",
            "newBalance": "115000000000000",
            "oldNonce": 115,
            "newNonce": 116
          },
          {
            "type": "BalanceUpdate",
            "updateId": 14,
            "accountId": 0,
            "subAccountId": 0,
            "coinId": 18,
            "oldBalance": "1023826000000000000",
            "newBalance": "1024035000000000000",
            "oldNonce": 0,
            "newNonce": 0
          }
        ]
      },
      {
        "txHash": "0x3b285c94d89ae17f7c288b10036a3dacff3460384601005afb440b1620bb538a",
        "tx": {
          "type": "Withdraw",
          "toChainId": 1,
          "accountId": 3,
          "subAccountId": 0,
          "to": "0x3d809e414ba4893709c85f242ba3617481bc4126",
          "l2SourceToken": 44,
          "l1TargetToken": 44,
          "amount": "1300000000000000000",
          "fee": "1531000000000000",
          "nonce": 81,
          "signature": {
            "pubKey": "b720c6110e673b55b5725dd0ff5778a8668ef4c7324718f78fa11def63081e85",
            "signature": "ec2c25aded9d1bbc85106178917a9da55a711449b4a49d0dbc01485290959225739ef0b3155498e96ba79cfbcb4a79a5f3ea4a179c6c210baca86820e8020b05"
          },
          "fastWithdraw": 1,
          "withdrawFeeRatio": 2000,
          "ts": 1677830493
        },
        "executedTimestamp":1689731237,
        "updates": [
          {
            "type": "BalanceUpdate",
            "updateId": 3,
            "accountId": 3,
            "subAccountId": 0,
            "coinId": 44,
            "oldBalance": "2993839561700000000000",
            "newBalance": "2992538030700000000000",
            "oldNonce": 81,
            "newNonce": 82
          },
          {
            "type": "BalanceUpdate",
            "updateId": 4,
            "accountId": 1,
            "subAccountId": 1,
            "coinId": 44,
            "oldBalance": "1500000000000000000000",
            "newBalance": "1498700000000000000000",
            "oldNonce": 0,
            "newNonce": 0
          },
          {
            "type": "BalanceUpdate",
            "updateId": 5,
            "accountId": 0,
            "subAccountId": 0,
            "coinId": 44,
            "oldBalance": "438300000000000",
            "newBalance": "1969300000000000",
            "oldNonce": 0,
            "newNonce": 0
          }
        ]
      },
      {
        "txHash": "0x8ada34680c8ba0e5cdbc14011e51c9989cab9339e0a7e679d14c14e7a587149d",
        "tx": {
          "type": "ForcedExit",
          "toChainId": 2,
          "initiatorAccountId": 3,
          "initiatorSubAccountId": 0,
          "target": "0x086cacda48e8a77680ba1e79177d1655f7130c95",
          "targetSubAccountId": 1,
          "l2SourceToken": 40,
          "l1TargetToken": 40,
          "fee": "19030000000000000",
          "feeToken": 18,
          "nonce": 178,
          "signature": {
            "pubKey": "b720c6110e673b55b5725dd0ff5778a8668ef4c7324718f78fa11def63081e85",
            "signature": "b119bd5971397b6abc499f6a2c09358b8c39d937be5bc96e3f186b4fc5026c80a933eea1b8f9c71cab8bb10ae554a2765008b937a724d026512f97cbeeacef05"
          },
          "ts": 1677836553
        },
        "executedTimestamp":1689731238,
        "updates": [
          {
            "type": "BalanceUpdate",
            "updateId": 20,
            "accountId": 3,
            "subAccountId": 0,
            "coinId": 18,
            "oldBalance": "2790050120799999999999",
            "newBalance": "2790031090799999999999",
            "oldNonce": 178,
            "newNonce": 179
          },
          {
            "type": "BalanceUpdate",
            "updateId": 21,
            "accountId": 15,
            "subAccountId": 1,
            "coinId": 40,
            "oldBalance": "2100000000000000000",
            "newBalance": "0",
            "oldNonce": 0,
            "newNonce": 0
          },
          {
            "type": "BalanceUpdate",
            "updateId": 22,
            "accountId": 1,
            "subAccountId": 2,
            "coinId": 40,
            "oldBalance": "4000001486590000000000000000",
            "newBalance": "4000001484490000000000000000",
            "oldNonce": 0,
            "newNonce": 0
          },
          {
            "type": "BalanceUpdate",
            "updateId": 23,
            "accountId": 0,
            "subAccountId": 0,
            "coinId": 18,
            "oldBalance": "7272586000000000000",
            "newBalance": "7291616000000000000",
            "oldNonce": 0,
            "newNonce": 0
          }
        ]
      },
      {
        "txHash": "0x640f38c6b09744d627b16e03339064d6edd39187cde8c4329fa19a2a60db8664",
        "tx": {
          "type": "OrderMatching",
          "accountId": 6,
          "subAccountId": 1,
          "taker": {
            "accountId": 13,
            "subAccountId": 1,
            "slotId": 163,
            "nonce": 0,
            "baseTokenId": 41,
            "quoteTokenId": 1,
            "amount": "1886200000000000000",
            "price": "1568210000000000000000",
            "isSell": 1,
            "feeRatio1": 5,
            "feeRatio2": 10,
            "signature": {
              "pubKey": "1aedae58e43fe6661db7f834ae438930443908d108fdf621bfd4741fedfcd82f",
              "signature": "57b7a0f06eb5d5dffbc8e8a6626ef7f9c472a8ac7761db36f8a0a2df2049988a9b43e8b3292a969b9b6cc5f689a5eecb8b05981ef1e3ca6e0de0da64ae6d6e01"
            }
          },
          "maker": {
            "accountId": 13,
            "subAccountId": 1,
            "slotId": 898,
            "nonce": 1,
            "baseTokenId": 41,
            "quoteTokenId": 1,
            "amount": "684900000000000000",
            "price": "1569150000000000000000",
            "isSell": 0,
            "feeRatio1": 5,
            "feeRatio2": 10,
            "signature": {
              "pubKey": "1aedae58e43fe6661db7f834ae438930443908d108fdf621bfd4741fedfcd82f",
              "signature": "b0aebe2bdd7a98a78d564d11c5f138cf428382628af55e85c250446b03dc0005f734e952819278d0b96fa970c6ab0018e33bb5bda7c55d69658551d2e606b904"
            }
          },
          "fee": "391000000000000",
          "feeToken": 1,
          "expectBaseAmount": "54800000000000000",
          "expectQuoteAmount": "85989420000000000000",
          "signature": {
            "pubKey": "84bf4edbe1f7056f079ba4c38359427f43d529fbab2e94e6d6b7a18efbf2fb87",
            "signature": "34e768dce60268f702b9a9ca68cb19d6785d2d1da8d7c799a29aa45e8c8bd9096c20cbf518c95fce2b2b58329492c35896162fe9cb1ff13f6e3a946b15bb2202"
          }
        },
        "executedTimestamp":1689731239,
        "updates": [
          {
            "type": "OrderUpdate",
            "updateId": 0,
            "accountId": 13,
            "subAccountId": 1,
            "slotId": 898,
            "oldTidyOrder": {
              "nonce": 1,
              "residue": "54800000000000000"
            },
            "newTidyOrder": {
              "nonce": 2,
              "residue": "0"
            }
          },
          {
            "type": "BalanceUpdate",
            "updateId": 1,
            "accountId": 13,
            "subAccountId": 1,
            "coinId": 1,
            "oldBalance": "200304228482442156994500000",
            "newBalance": "200304142493022156994500000",
            "oldNonce": 1,
            "newNonce": 1
          },
          {
            "type": "BalanceUpdate",
            "updateId": 2,
            "accountId": 13,
            "subAccountId": 1,
            "coinId": 41,
            "oldBalance": "199999971788889400000000000",
            "newBalance": "199999971843662000000000000",
            "oldNonce": 1,
            "newNonce": 1
          },
          {
            "type": "OrderUpdate",
            "updateId": 3,
            "accountId": 13,
            "subAccountId": 1,
            "slotId": 163,
            "oldTidyOrder": {
              "nonce": 0,
              "residue": "1467400000000000000"
            },
            "newTidyOrder": {
              "nonce": 0,
              "residue": "1412600000000000000"
            }
          },
          {
            "type": "BalanceUpdate",
            "updateId": 4,
            "accountId": 13,
            "subAccountId": 1,
            "coinId": 41,
            "oldBalance": "199999971843662000000000000",
            "newBalance": "199999971788862000000000000",
            "oldNonce": 1,
            "newNonce": 1
          },
          {
            "type": "BalanceUpdate",
            "updateId": 5,
            "accountId": 13,
            "subAccountId": 1,
            "coinId": 1,
            "oldBalance": "200304142493022156994500000",
            "newBalance": "200304228396452736994500000",
            "oldNonce": 1,
            "newNonce": 1
          },
          {
            "type": "BalanceUpdate",
            "updateId": 6,
            "accountId": 6,
            "subAccountId": 1,
            "coinId": 1,
            "oldBalance": "9999680162000000000000",
            "newBalance": "9999679771000000000000",
            "oldNonce": 224,
            "newNonce": 224
          },
          {
            "type": "BalanceUpdate",
            "updateId": 7,
            "accountId": 6,
            "subAccountId": 0,
            "coinId": 1,
            "oldBalance": "3529001244641983488661500000",
            "newBalance": "3529001244727972908661500000",
            "oldNonce": 224,
            "newNonce": 224
          },
          {
            "type": "BalanceUpdate",
            "updateId": 8,
            "accountId": 6,
            "subAccountId": 0,
            "coinId": 41,
            "oldBalance": "1594000000063937300000000000",
            "newBalance": "1594000000063964700000000000",
            "oldNonce": 224,
            "newNonce": 224
          },
          {
            "type": "BalanceUpdate",
            "updateId": 9,
            "accountId": 0,
            "subAccountId": 0,
            "coinId": 1,
            "oldBalance": "483683000000000000",
            "newBalance": "484074000000000000",
            "oldNonce": 0,
            "newNonce": 0
          }
        ]
      }
    ]
  },
  "id": 1
}

BlockResp

Field	Description
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

Field	Description
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

Field	Description
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

Field	Description
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

Field	Description
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

Field	Description
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

Field	Description
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.

Request

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

Response

Returns

Vec<BlockTxResp>: transactions that are executed but not batched yet, where those executed first come first. 100 transactions max. The max transaction time can be used as a parameter for the next round of query.

getBlockOnChainByNumber

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

Request

Parameters

• chain_id

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

Response

Returns

BlockOnChainResp

{
    "jsonrpc": "2.0",
    "result": {
        "committed": [
            {
                "chainId": 2,
                "txHash": "0x7264f1d95b5339f77f2b24939bada1cbca183c77110e514159bbcfad3aa303d2"
            },
            {
                "chainId": 1,
                "txHash": "0x3e30f9bed591ec0339278faaed08e6200f4a5ded4668e3038e7ed70512a68967"
            }
        ],
        "verified": [
            {
                "chainId": 2,
                "txHash": "0xaa0f1fed256b21d8b2fd4b91450418061674971bce452121229126aa35effc37"
            },
            {
                "chainId": 1,
                "txHash": "0xa9548f4fe6a8d3127fdfd221ee2c97149bee8ad82744d2c698440ef3774f1122"
            }
        ]
    },
    "id": 1
}

BlockOnChainResp

Field	Description
committed	Transaction info committed to L1, with type OnChainResp
verified	Transaction info executed on L1, with type OnChainResp

OnChainResp

Field	Description
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.

Request

Parameters

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

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

Response

Returns

AccountInfoResp

{
    "jsonrpc": "2.0",
    "result": {
        "id": 1,
        "address": "0x1aef2b4c06b83cdb2783d3458cdbf3886a6ae7d4",
        "nonce": 0,
        "pubKeyHash": "0x0000000000000000000000000000000000000000",
      	"subAccountNonces": {
          "1": 0,
          "2":13
        }
    },
    "id": 1
}

AccountInfoResp

Field	Description
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.

Request

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

Response

Returns

HashMap<SubAccountId,<TokenId,Balance>>

{
    "jsonrpc": "2.0",
    "result": {
        "0": {
           "18": "1498994167999999999973"
        }
    },
    "id": 1
}

getAccountOrderSlots

Get the order slot of an account.

Request

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

Response

Returns

HashMap<SubAccountId,<SlotId, TidyOrder>>

{
    "jsonrpc": "2.0",
    "result": {
      "0": {
        "3": {
          "nonce": 21,
          "residue": "348694029837858"
        }
      }
    },
    "id": 1
}

getTokenReserve

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

Case 1

User Input:

Token: ZKL

Withdraw to: ETH

The maximum ZKL that the user can withdraw:

RPC-API tokenId: ZKL, false

Case 2

User Input:

Token: USDC

Withdraw to: ETH

The maximum USDC that the user can withdraw:

RPC-API tokenId: USDC, false

Case 3

User Input:

Token: USD

Withdraw to: ETH

Withdraw as: USDC

The maximum USDC that the user can withdraw:

RPC-API tokenId: USDC, true

Request

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

Response

Returns

HashMap<ChainId, Balance>

{
    "jsonrpc": "2.0",
    "result": {
			"0": "134",
			"1": "1000000000000000000000000000000000000000000000"
    },
    "id": 1
}

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.

Request

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

Response

Returns

AccountSnapshotResp

{
  "jsonrpc": "2.0",
  "result": {
    "id": 1,
    "address": "0x1aef2b4c06b83cdb2783d3458cdbf3886a6ae7d4",
    "nonce": 0,
    "pubKeyHash": "0x0000000000000000000000000000000000000000",
    "subAccountNonces": {
      "1": 0,
      "2":13
    }
    "balances": {
      "0": {
        "18": "1498994167999999999973"
      }
    },
    "orderSlots": {
      "0": {
        "3": {
          "nonce": 21,
          "residue": "348694029837858"
        }
      },
      "blockNumber": 103
    }
  },
  "id": 1
}

AccountSnapshotResp

Field	Description
id	Account id
address	Account address
nonce	Account nonce
pubKeyHash	Account pubKeyHash
subAccountNonces	Nonce of the subaccount, HashMap<SubAccountId,Nonce>
balances	HashMap<SubAccountId,<TokenId,Balance>>
orderSlots	HashMap<SubAccountId,<SlotId, TidyOrder>>
blockNumber	The block height of the snapshot

getTransactionByHash

Get transaction info.

Request

Parameters:

• txHash

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

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

Response

Returns

TxResp*since the transaction may fail, the TxResp will also include receipt.

{
    "jsonrpc": "2.0",
    "result": {
        "txHash": "0x4221afe405566e4b057d36060e6a5d33151a10a1b9b00da71705e534b6646f22",
        "tx": {
            "type": "Transfer",
            "accountId": 2,
            "fromSubAccountId": 0,
            "toSubAccountId": 1,
            "to": "0xdc9c9863167ee865edd5216964b8b99d43ee7a81",
            "token": 18,
            "amount": "1000000000000",
            "fee": "216000000000000",
            "nonce": 38192,
            "signature": {
                "pubKey": "5f07954b65b5407a37ec0a2c54fb4647e2014475936057bb2f52a6faab938b02",
                "signature": "79bdeaa739557a4be289ef2bf718253ce791adc3ce5fbcb7abcad4b0a2d6e203a9c38d68d987f96ffc7a391f2518f281874f33c7a5a7110d27591ad029b31005"
            },
            "ts": 1675406687
        },
        "receipt": {
            "executed": true,
                "executedTimestamp": 1689731233,
            "success": true,
            "failReason": null,
            "block": 3947,
          	"index": 1
        },
        "updates": [
            {
                "type": "BalanceUpdate",
                "updateId": 9,
                "accountId": 2,
                "subAccountId": 0,
                "coinId": 18,
                "oldBalance": "1941710093000000000000",
                "newBalance": "1941709876000000000000",
                "oldNonce": 38192,
                "newNonce": 38193
            },
            {
                "type": "BalanceUpdate",
                "updateId": 10,
                "accountId": 2,
                "subAccountId": 1,
                "coinId": 18,
                "oldBalance": "38191000000000000",
                "newBalance": "38192000000000000",
                "oldNonce": 38192,
                "newNonce": 38193
            }
        ]
    },
    "id": 1
}

TxResp

Field	Decription
txHash	The trasnaction hash
tx	ZkLinkTx
receipt	The execution receipt of the transaction
updates	[StateUpdateResp] that is ordered by updateId: the ones generated first come first in the array

TxReceiptResp

Field	Decription
executed	Whether the transaction is executed
executedTimestamp	The unix timestamp of exection time. Null if executed is false
success	The result of the transaction. If executed is false, it must be false
failReason	The reason of failure of the transaction. Null if success is True.
block	The block height of the transaction. 0 if success is False.
index	The index of the transaction in the block. 0 if success is False.

getAccountTransactionHistory

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

Request

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

Response

Returns

Page<ZkLinkTxHistory>

{
    "jsonrpc": "2.0",
    "result": {
        "totalPageNum": 20,
        "pageIndex": 0,
        "pageSize": 2,
        "pageData": [
            {
                "chainId": 0,
                "fromAccount": "0x3498f456645270ee003441df82c718b56c0e6666",
                "toAccount": "0xbfda941bd2a0eddb57b10f8e8d3486a738b92ccc",
                "amount": "10000000000000000000000000",
                "nonce": 262,
                "tx": {
                    "type": "Transfer",
                    "accountId": 4,
                    "fromSubAccountId": 0,
                    "toSubAccountId": 1,
                    "to": "0xbfda941bd2a0eddb57b10f8e8d3486a738b92ccc",
                    "token": 47,
                    "amount": "10000000000000000000000000",
                    "fee": "4290000000000",
                    "nonce": 262,
                    "signature": {
                        "pubKey": "84bf4edbe1f7056f079ba4c38359427f43d529fbab2e94e6d6b7a18efbf2fb87",
                        "signature": "a5389ea55bfb88a9457eadba7ef1821d1cc7a51d29ab1fe17b64b7294ea8160acde7ece1fd3c8028b92a1071f41f567e11b27fa30b39959c744f8ccd04052003"
                    },
                    "ts": 1675442473
                },
                "txHash": "0x741b9b668430c78f87c8a9fb6b257f93a151f1101160bcc681536536f982c5b5",
                "txReceipt": {
                    "executed": true,
                    "success": true,
                    "failReason": null,
                    "block": 9991,
                    "index": 3
                },
                "createdAt": "2023-02-03T16:41:13.501848Z"
            },
            {
                "chainId": 0,
                "fromAccount": "0x3498f456645270ee003441df82c718b56c0e6666",
                "toAccount": "0xbfda941bd2a0eddb57b10f8e8d3486a738b92ccc",
                "amount": "10000000000000000000000000",
                "nonce": 261,
                "tx": {
                    "type": "Transfer",
                    "accountId": 4,
                    "fromSubAccountId": 0,
                    "toSubAccountId": 1,
                    "to": "0xbfda941bd2a0eddb57b10f8e8d3486a738b92ccc",
                    "token": 46,
                    "amount": "10000000000000000000000000",
                    "fee": "1270000000000000",
                    "nonce": 261,
                    "signature": {
                        "pubKey": "84bf4edbe1f7056f079ba4c38359427f43d529fbab2e94e6d6b7a18efbf2fb87",
                        "signature": "df5b57a04d907bf2a4639cb4b405320da69416e45516c3d2d4346058fa8a538498d8ca7ec4c84d11fa58f71395d8c5f45adffa4e2ff418038dd0dbc3cf4e7a00"
                    },
                    "ts": 1675442469
                },
                "txHash": "0xb4e12570be6c01a49cfd6c14e7021b7e482ea938804242b41680acd09ffe59d8",
                "txReceipt": {
                    "executed": true,
                    "success": true,
                    "failReason": null,
                    "block": 9989,
                    "index": 6
                },
                "createdAt": "2023-02-03T16:41:10.744899Z"
            }
        ]
    },
    "id": 1
}

Page<ZkLinkTxHistory>

Field	Description
totalPageNum	The number of pages
pageIndex	Index of the current page
pageSize	The size of the page
pageData	Page data[ZkLinkTxHistory]

ZkLinkHistory

Field	Description
chainId	Chain id defined by zkLink Deposit: the chain that the deposit is from Transfer and Withdraw: no specific meaning
fromAccount	Address of from_account Deposit: the L1 address that the deposit is from Transfer: the from_address of the transfer Withdraw: the from_address of the withdraw
toAccount	Address of to_account Deposit: L2 address that the deposit is to Transfer: the to_address of the transfer Withdraw: the L1 address that the withdraw is to
amount	The amount of the transaction Deposit: the amount of the deposit Transfer: the amount of the transfer Withdraw: the amount of the withdraw
nonce	The nonce of the transaction Deposit: the serialId of L1 event Transfer and Withdraw: the nonce of the transaction
tx	ZkLinkTx
txHash	The hash of the transaction
txReceipt	TxReceiptResp
createdAt	The time that the transaction is received by zkLink

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.

Request

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

Response

Returns

Vec<FastWithdrawTxResp>

{
  "jsonrpc": "2.0",
  "result": [
    {
      "txHash": "0xb4e12570be6c01a49cfd6c14e7021b7e482ea938804242b41680acd09ffe59d8",
      "tx": {
        "type": "Withdraw",
        "toChainId": 1,
        "accountId": 7,
        "subAccountId": 2,
        "to": "0x3498f456645270ee003441df82c718b56c0e6666",
        "l2SourceToken": 1,
        "l1TargetToken": 17,
        "amount": "995900000000000000",
        "fee": "4100000000000000",
        "withdrawFeeRatio": 50,
        "fastWithdraw": 1,
        "ts": 1646102148,
        "nonce": 0, // subaccount nonce
        "signature": {
          "pubKey": "0dd4f603531bd78bbecd005d9e7cc62a794dcfadceffe03e269fbb6b72e9c724",
          "signature": "a8719d0f771f34a177bbf199ab7b0decd03b5db29edf173ed980d19c7864c5a3761111620ab1982ef1bb7459d5a919727e51b895799e2706ddd5a5328146eb01"
        }
      },
      "executedTimestamp": "2023-02-03T16:41:10.744899Z"
    }
  ],
  "id": 1
}

FastWithdrawTxResp

Field	Description
txHash	Transaction hash on zkLink
tx	zkLink transaction
executedTimestamp	The execution timestamp of the transaction

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.

Field	Description
chainId	Chain id defined by zkLink
layerOneChainId	The layer 1 chain id
gateways	The list of GateWayInfo

GateWayInfo

Field	Description
chainId	the chain id
chainId	the chain id
l1GatewayContract	the layer 1 gateway contract address
l2GatewayContract	the layer 2 gateway contract address
tokens	the list that all the TokenInfo on the gateway

TokenInfo

Field	Description
tokenId	The token id
tokenAddress	token address
decimal	the token amount decimal
fastWithdraw	support fast withdraw or not

{
  "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.

Request

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

Response

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

TxLayer1Signature

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

Field	Description
type	The type of the signature EthereumSignature: Ethereum ECDSA signature EIP1271Signature: Ethereum EIP1271 signature
signature	Signature output, a hex string

Examples:

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

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

ZkLinkSignature

Signatures for L2 transactions use zkLink Encode.

Field	Description
pubKey	The public key of ，a hex string with 0x prefix
signature	Signature output, a hex string without 0x prefix

Example:

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

version: 7df6cd1