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
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.
JSON-RPC API METHODS
getSupportChains
Get the configuration of all supported chains.
Parameters
None
ChainResp
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
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
id
Token id
symbol
Token symbol
usdPrice
Token price
chains
HashMap<ChainId,ChainTokenResp> that includes the contract addresses on each chain
ChainTokenResp
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:
getLatestBlockNumber
Get the latest block height info.
Parameters
None
BlockNumberResp
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 nullincludeTx: whether contains transaction details: returns transaction hash if false. only successful transactions will be included in a block. callgetTransactionByHashto query the failed transactions.includeUpdate: whether contains the state change by transactions; valid only whenincludeTxis true.
BlockResp
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
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
type
AccountCreate
updateId
The position of the update in the block
accountId
The id of the new account
address
The account address
Example:
Transactions that may generate AccountCreate include:
Deposit
Transfer
AccountChangePubkeyUpdate
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:
only ChangePubKey will generate AccountChangePubkeyUpdate
BalanceUpdate
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:
All ZkLinkTx will generate BalanceUpdate
OrderUpdate
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
nonce
Slot nonce
residue
Slot residue
Example:
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. CallgetTransactionByHashto query failed transaction details.includeUpdate: whether to include the state change by the transaction. Valid only whenincludeTxis 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
BlockOnChainResp
committed
Transaction info committed to L1, with type OnChainResp
verified
Transaction info executed on L1, with type OnChainResp
OnChainResp
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.
AccountInfoResp
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 idsubAccountId: optional, the id of the subaccount; null if the query requests the balance of all subaccounts.
getAccountOrderSlots
Get the order slot of an account.
Parameters
accountId: account idsubAccountId: optional, the id of the subaccount; null if the query requests the balance of all subaccounts.
getTokenReserve
Get the withdrawable limit of a token on a certain L1 chain. There are 3 cases:
Parameters
tokenId: tokenIdmapping: whether to query mapping, valid only when tokenId corresponds to USD stable.
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:
accountAddressoraccountIdsubAccountId: 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
AccountSnapshotResp
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.
Parameters:
txHashincludeUpdate: whether to include the state change by the transaction
TxResp
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
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.
Parameters
Deposit,WithdraworTransferaccount address
the page index, starting from 0
the page size
Page<ZkLinkTxHistory>
totalPageNum
The number of pages
pageIndex
Index of the current page
pageSize
The size of the page
pageData
Page data[ZkLinkTxHistory]
ZkLinkHistory
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.
Parameters:
lastTxTimestamp: ISO 8601 standard with date, time, and time zone;maxTxs: the max value of the number of Withdraw in the return.
FastWithdrawTxResp
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.
chainId
Chain id defined by zkLink
layerOneChainId
The layer 1 chain id
gateways
The list of GateWayInfo
GateWayInfo
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
tokenId
The token id
tokenAddress
token address
decimal
the token amount decimal
fastWithdraw
support fast withdraw or not
sendTransaction
Submit L2 transaction and return transaction hash.
Parameters:
ZkLinkTx: L2 transactionLayer1Signature: layer1 signature with type Option<TxLayer1Signature>; required for Layer2 transactions apart from
ChangePubKeyorOrderMatching.submitterSignature:
Option<ZkLinkSignature>, required only when the transaction involves subaccounts (except #0 subaccount);submitterSignatureis a zk signature totxhash.
TxLayer1Signature
L1 signatures apply EIP-191 specification with zkLink Eth sig message.
type
The type of the signature
EthereumSignature: Ethereum ECDSA signature
signature
Signature output, a hex string
Examples:
ZkLinkSignature
Signatures for L2 transactions use zkLink Encode.
pubKey
The public key of ，a hex string with 0x prefix
signature
Signature output, a hex string without 0x prefix
Example:
version: 7df6cd1
Last updated
Was this helpful?