Ledger API

To enable Ledger RPC API on the node, add "ledger" namespace in "PublicModules" in node_config.json

ledger_getAccountBlocks

Fetch a number of account blocks by address, token id, and (or) account block hash

• Parameters:

  • address: address Account address
  • startBlockHash: hash Hash of account block to start fetch from, optional. The results are in descending order by height. To start with the latest block, use null
  • tokenId: tokenId Search token id, optional. This parameter is used to filter the transactions by certain token. Use null to return all account blocks.
  • count: uint64 Number of account blocks to fetch. Maximum 1000.

• Return:

  • Array<AccountBlock> See AccountBlock

• Example:

ledger_getAccountBlockByHash

Fetch an account block by hash

• Parameters:

  • blockHash: hash Hash of account block

• Return:

  • AccountBlock

• Example:

ledger_getAccountBlockByHeight

Fetch an account block by block height

Note: The height is account block height, not snapshot block height.

• Parameters:

  • address: address Account address
  • height: uint64 string Height of account block

• Return:

  • AccountBlock

• Example:

ledger_getAccountBlocksByAddress

Fetch a number of account blocks by page. The result is in descending order by account block height.

• Parameters:

  • address: address Account address
  • pageIndex: uint64 Page index, starting with 0
  • pageSize: uint64 Page size. Maximum 1000.

• Return:

  • List<AccountBlock> See AccountBlock

• Example:

ledger_getAccountBlocksByHeightRange

Fetch a number of account blocks in descending order by height range

• Parameters:

  • address: address Account address
  • startHeight: uint64 Start height, inclusive
  • endHeight: uint64 End height, inclusive. It must hold $endHeight-StartHeight \le 1000$

• Return:

  • List<AccountBlock> See AccountBlock

• Example:

ledger_getCompleteBlockByHash

Fetch an RS block with the enclosing response block by account block hash.

Note: If the given account block is not RS block, the returned result will be the same with ledger_getAccountBlockByHash

• Parameters:

  • blockHash: hash Hash of RS block

• Return:

  • AccountBlock

• Example:

ledger_getLatestAccountBlock

Fetch the latest account block by address

• Parameters:

  • address: address Account address

• Return:

  • AccountBlock

• Example:

ledger_getSnapshotChainHeight

Get the current snapshot chain height

• Parameters: none

• Return:

  • height: uint64 string Current snapshot chain height

• Example:

ledger_getSnapshotBlockByHash

Fetch a snapshot block by snapshot block hash

• Parameters:

  • blockHash: hash Hash of snapshot block

• Returns:

  • SnapshotBlock

• Example:

ledger_getSnapshotBlockByHeight

Fetch a snapshot block by snapshot block height

• Parameters:

  • height: uint64 Height of snapshot block

• Returns:

  • SnapshotBlock

• Example:

ledger_getSnapshotBlocks

Fetch a number of snapshot blocks by start height and count in descending order

• Parameters:

  • height: uint64 string Start block height
  • count: uint64 Number of blocks to fetch. Maximum 1000.

• Returns:

  • List<SnapshotBlock> See SnapshotBlock

• Example:

ledger_getChunks

Fetch a number of snapshot blocks with snapshoted account blocks by height range

• Parameters:

  • startHeight: uint64 string Start height, inclusive
  • endHeight: uint64 string End height, inclusive. It must hold $\le StartHeight + 1000$

• Returns: List<SnapshotChunk>

  • SnapshotBlock See SnapshotBlock
  • List<AccountBlock> See AccountBlock

• Example:

ledger_getAccountInfoByAddress

Get account information by address

• Parameters:

  • address: address Account address

• Return:

  • AccountInfo

• Example:

ledger_getLatestSnapshotHash

Get the current snapshot block hash

• Parameters: none

• Return:

  • hash Hash of the current snapshot block

• Example:

ledger_sendRawTransaction

Send a raw transaction

Parameters: - block: AccountBlock Account block to send

Field	Type	Description
blockType	Mandatory	See AccountBlock
height	Mandatory	See AccountBlock
hash	Mandatory	See AccountBlock
previousHash	Mandatory	See AccountBlock
address	Mandatory	See AccountBlock
publicKey	Mandatory	See AccountBlock
signature	Mandatory	See AccountBlock
difficulty	Mandatory for using PoW	See AccountBlock
nonce	Mandatory for using PoW	See AccountBlock
sendBlockHash	Mandatory for response	See AccountBlock
toAddress	Mandatory for request	See AccountBlock
tokenId	Mandatory for request	See AccountBlock
amount	Mandatory for request	See AccountBlock
fee	Mandatory for request	Use "10000000000000000000" (10 VITE) for deploying a contract. For other cases, use "0"
data	Optional	A base64 encoding string used as comment/memo or encoded function call/result of a smart contract

• Returns: none

• Example:

ledger_getUnreceivedBlocksByAddress

Fetch a number of unreceived blocks by address

• Parameters:

  • address: address Account address
  • pageIndex: uint64 Page index, starting with 0
  • pageSize: uint64 Page size. Maximum 1000

• Return:

  • List<AccountBlock> See AccountBlock

• Example:

ledger_getUnreceivedBlocksInBatch

Fetch unreceived blocks in batch

• Parameters: Array<PagingQueryBatch>

  • address: address Account address
  • pageIndex: uint64 Page index, starting with 0
  • pageSize: uint64 Page size. Maximum 1000

• Return:

  • map<Address, List<AccountBlock>> See AccountBlock

• Example:

ledger_getUnreceivedTransactionSummaryByAddress

Get unreceived transaction summary by address

• Parameters:

  • address: address Account address

• Return:

  • AccountInfo

• Example:

ledger_getUnreceivedTransactionSummaryInBatch

Get unreceived transaction summary in batch

• Parameters:

  • addressList: Array<address> An array of account address

• Return:

  • Array<AccountInfo> See AccountInfo

• Example:

ledger_getVmLogs

Get event logs by account block hash

• Parameters:

  • blockHash: hash Hash of account block

• Return:

  • Array<VmLog> See VmLog

• Example:

ledger_getVmLogListByHash

Get event logs by log hash

• Parameters:

  • logHash: hash Log hash

• Return:

  • Array<VmLog> See VmLog

• Example:

ledger_getVmLogsByFilter

Get event logs by account address, account block height range and topics

• Parameters: FilterParam

  • addressHeightRange: map[address]Range A map of contract address and height range. At least one address must be specified.
    • fromHeight: uint64 string Start height. 0 means starting from the latest account block
    • toHeight: uint64 string End height. 0 means fetching till the latest account block (no ending height)
  • topics: <Array<Array<hash>> Event topics, optional. See here for details
  • pageIndex: uint64 page index.
  • pageSize: uint64 page size. Maximum 1000

• Returns:

  • Array<Logs> See Logs

ledger_getPoWDifficulty

Get PoW difficulty for sending the transaction

Note: This method will calculate the required amount of quota according to transaction parameters, and check whether the account has enough quota. If not, it returns the difficulty for the transaction, otherwise returns an empty string.

Can NOT use PoW twice in one snapshot block

If the method returns with error, usually it is because the transaction data is too long, or the transaction cannot obtain quota through PoW. For example, if PoW was once used for a previous transaction, the account is not allowed to use PoW twice within the same snapshot block.

• Parameters: GetPoWDifficultyParams

  • address: address Address of account
  • previousHash: hash Hash of the previous account block
  • blockType: byte Block type
  • toAddress: address Address of recipient, required for request transaction
  • data: base64 Additional block data

• Returns: GetPoWDifficultyResult

  • requiredQuota: uint64 string Raw quota required for sending the transaction
  • difficulty: bigint string PoW difficulty. Returns empty string if sending the transaction does not need PoW
  • qc: bigint string Congestion factor. In 18 decimals
  • isCongestion: bool true means sending the transaction will consume more quota

• Example:

ledger_getRequiredQuota

Calculate quota required for sending the transaction

• Parameters: GetPoWDifficultyParams

  • address: address Address of account
  • previousHash: hash Hash of the previous account block
  • blockType: byte Block type
  • toAddress: address Address of recipient, required for request transaction
  • data: base64 Additional block data

• Returns:

  • requiredQuota: uint64 string Raw quota required for sending the transaction

• Example:

ledger_getSeed

Get random seed in the snapshot block according to seed hash

• Parameters:

  • snapshotHash: hash Snapshot block hash
  • seedHash: hash Seed hash

• Returns:

  • uint64 Random seed contained in the snapshot block

• Example: