caver.rpc.klay
caver.rpc.klay
provides JSON-RPC call with klay
name space.
caver.rpc.klay.accountCreated
Returns true
if the account associated with the address is created in the Klaytn blockchain platform. It returns false
otherwise.
Parameters
address
string
The address of the account you want to query to see if it has been created on the network.
blockNumber
number | string
(optional) A block number, or the string latest
or earliest
. If omitted, latest
will be used.
callback
function
(optional) Optional callback, returns an error object as the first parameter and the result as the second.
Return Value
Promise
returns boolean
boolean
The existence of an input address in the Klaytn.
Example
caver.rpc.klay.getAccount
Returns the account information of a given address in the Klaytn. For more details about the types of an account in Klaytn, please refer to Klaytn Account Types.
NOTE caver.rpc.klay.getAccount
returns the account that exists on the network, so null
is returned if the account matching the address does not exist on the actual blockchain network.
Parameters
address
string
The address of the account for which you want to get account information.
blockNumber
number | string
(optional) A block number, or the string latest
or earliest
. If omitted, latest
will be used.
callback
function
(optional) Optional callback, returns an error object as the first parameter and the result as the second.
Return Value
Promise
returns object
object
An object that contains the account information. Each account type has different attributes.
Example
caver.rpc.klay.getAccountKey
Returns AccountKey of a given address. If the account has AccountKeyLegacy or the account of the given address is a Smart Contract Account, it will return an empty key value. Please refer to Account Key for more details.
NOTE caver.rpc.klay.getAccountKey
returns an object that differs by each AccountKey type. If a Klaytn account matching the given address does not exist in the network, null
is returned.
Parameters
address
string
The address of Klaytn account from which you want to get an object of AccountKey information.
blockNumber
number | string
(optional) A block number, or the string latest
or earliest
. If omitted, latest
will be used.
callback
function
(optional) Optional callback, returns an error object as the first parameter and the result as the second.
Return Value
Promise
returns object
object
An object that contains AccountKey information. Each AccountKey type has different attributes.
Example
caver.rpc.klay.encodeAccountKey
Encodes an object that contains AccountKey information using the Recursive Length Prefix (RLP) encoding scheme. Also you can use account.getRLPEncodingAccountKey to get RLP-encoded AccountKey.
Parameters
accountKey
object
callback
function
(optional) Optional callback, returns an error object as the first parameter and the result as the second.
Return Value
Promise
returns string
string
A RLP-encoded AccountKey.
Example
caver.rpc.klay.decodeAccountKey
Decodes a RLP-encoded AccountKey. Also you can use caver.account.accountKey.decode to decode a RLP-encoded AccountKey.
Parameters
encodedKey
string
A RLP-encoded AccountKey.
callback
function
(optional) Optional callback, returns an error object as the first parameter and the result as the second.
Return Value
Promise
returns object
object
An object defines keyType
and key
inside.
Example
caver.rpc.klay.getBalance
Returns the balance of the account of the given address in Klaytn.
Parameters
address
string
The address of the account for which you want to get balance.
blockNumber
number | string
(optional) A block number, or the string latest
or earliest
. If omitted, latest
will be used.
callback
function
(optional) Optional callback, returns an error object as the first parameter and the result as the second.
Return Value
Promise
returns string
string
The current balance for the given address in peb.
Example
caver.rpc.klay.getCode
Returns code at a given address.
Parameters
address
string
The address to get the code from.
blockNumber
number | string
(optional) A block number, or the string latest
or earliest
. If omitted, latest
will be used.
callback
function
(optional) Optional callback, returns an error object as the first parameter and the result as the second.
Return Value
Promise
returns string
string
The code from the given address.
Example
caver.rpc.klay.getTransactionCount
Returns the total number of transactions sent from an address.
Parameters
address
string
The address to get the number of transactions from.
blockNumber
number | string
callback
function
(optional) Optional callback, returns an error object as the first parameter and the result as the second.
Return Value
Promise
returns string
string
The number of transactions sent from the given address in hex.
Example
caver.rpc.klay.isContractAccount
Returns true
if an input account has a non-empty codeHash at the time of a specific block number. It returns false
if the account is an EOA or a smart contract account which doesn't have codeHash. Please refer to Smart Contract Account for more details.
Parameters
address
string
The address you want to check for isContractAccount.
blockNumber
number | string
(optional) A block number, or the string latest
or earliest
. If omitted, latest
will be used.
callback
function
(optional) Optional callback, returns an error object as the first parameter and the result as the second.
Return Value
Promise
returns boolean
boolean
true means the input parameter is an existing smart contract address.
Example
caver.rpc.klay.sign
Generates signed data specific to the Klaytn. Refer to Klaytn Platform API - klay_sign to know how the signature is generated.
NOTE: This API provides the function to sign a message using an imported account in your Klaytn node. The imported account in your node must be unlocked to sign the message. To sign a transaction with imported account in your Klaytn node, use caver.rpc.klay.signTransaction.
Parameters
address
String
The address of the imported account to sign the message.
message
String
Message to sign.
blockNumber
number | string
(optional) A block number, or the string latest
or earliest
. If omitted, latest
will be used.
callback
function
(optional) Optional callback, returns an error object as the first parameter and the result as the second.
Return Value
Promise
returns string
string
The signature made from an imported account.
Example
caver.rpc.klay.getAccounts
Returns a list of addresses owned by the Klaytn Node.
Parameters
callback
function
(optional) Optional callback, returns an error object as the first parameter and the result as the second.
Return Value
Promise
returns Array
Array
An array of addresses owned by the Klaytn Node.
Example
caver.rpc.klay.getBlockNumber
Returns the number of the most recent block.
Parameters
callback
function
(optional) Optional callback, returns an error object as the first parameter and the result as the second.
Return Value
Promise
returns string
string
The number of the most recent block in hex.
Example
caver.rpc.klay.getHeader
Returns a block header by block hash or block number. If the user passes the block hash as a parameter, caver.rpc.klay.getHeaderByHash is called, and if the block number is called as a parameter, caver.rpc.klay.getHeaderByNumber is called.
Parameters
blockNumberOrHash
number | string
The block hash, number or the block tag string.
callback
function
(optional) Optional callback, returns an error object as the first parameter and the result as the second.
Return Value
Promise
returns object
object
Example
caver.rpc.klay.getHeaderByNumber
Returns a block header by block number.
Parameters
blockNumber
number | string
The block number or the block tag string.
callback
function
(optional) Optional callback, returns an error object as the first parameter and the result as the second.
Return Value
Promise
returns object
object
Example
caver.rpc.klay.getHeaderByHash
Returns the block number of the most recent block by using blockHash
.
Parameters
blockHash
string
The block hash.
callback
function
(optional) Optional callback, returns an error object as the first parameter and the result as the second.
Return Value
Promise
returns object
- An object includes the block header:
baseFeePerGas
string
The base fee per gas. This value is returned only when EthTxTypeCompatibleBlock is activated for that block number.
blockScore
string
The difficulty of mining in the blockchain network. The use of blockScore
differs from the consensus of the network. Always 1 in the BFT consensus engine.
extraData
string
The "extra data" field of this block.
gasUsed
string
The gas in total that was used by all transactions in this block.
governanceData
string
RLP encoded governance configuration
hash
string
Hash of the block. null
when it is a pending block.
logsBloom
string
The bloom filter for the logs of the block. null
when it is a pending block.
number
string
The block number. null
when it is a pending block.
parentHash
string
Hash of the parent block.
receiptsRoot
string
The root of the receipts trie of the block.
reward
string
The address of the beneficiary to whom the block rewards were given.
stateRoot
string
The root of the final state trie of the block.
timestamp
string
The unix timestamp for when the block was collated.
timestampFoS
string
The fraction of a second of the timestamp for when the block was collated.
transactionsRoot
string
The root of the transaction trie of the block.
Example
caver.rpc.klay.getBlock
Returns information about a block by block hash or block number. If the user passes the block hash as a parameter, caver.rpc.klay.getBlockByHash is called, and if the block number is called as a parameter, caver.rpc.klay.getBlockByNumber is called.
Parameters
blockNumberOrHash
number | string
The block hash, number or the block tag string.
returnTransactionObjects
boolean
(optional, default false
) If true
, the returned block will contain all transactions as objects, and if false
, it will only contain the transaction hashes.
callback
function
(optional) Optional callback, returns an error object as the first parameter and the result as the second.
Return Value
Promise
returns object
object
Example
caver.rpc.klay.getBlockByNumber
Returns information about a block by block number.
Parameters
blockNumber
number | string
The block number or the block which is tagged with a string (genesis
or latest
).
returnTransactionObjects
boolean
(optional, default false
) If true
, the returned block will contain all transactions as objects, and if false
, it will only contain the transaction hashes.
callback
function
(optional) Optional callback, returns an error object as the first parameter and the result as the second.
Return Value
Promise
returns object
object
Example
caver.rpc.klay.getBlockByHash
Returns the block number of the most recent block by using blockHash
.
Parameters
blockHash
string
The block hash.
returnTransactionObjects
boolean
(optional, default false
) If true
, the returned block will contain all transactions as objects, and if false
, it will only contain the transaction hashes.
callback
function
(optional) Optional callback, returns an error object as the first parameter and the result as the second.
Return Value
Promise
returns object
- An object includes block:
baseFeePerGas
string
The base fee per gas. This value is returned only when EthTxTypeCompatibleBlock is activated for that block number.
blockScore
string
The difficulty of mining in the blockchain network. The use of blockScore
differs from the consensus of the network. Always 1 in the BFT consensus engine.
extraData
string
The "extra data" field of this block.
gasUsed
string
The gas in total that was used by all transactions in this block.
governanceData
string
RLP encoded governance configuration
hash
string
Hash of the block. null
when it is a pending block.
logsBloom
string
The bloom filter for the logs of the block. null
when it is a pending block.
number
string
The block number. null
when it is a pending block.
parentHash
string
Hash of the parent block.
receiptsRoot
string
The root of the receipts trie of the block.
reward
string
The address of the beneficiary to whom the block rewards were given.
size
string
Integer the size of this block in bytes.
stateRoot
string
The root of the final state trie of the block.
timestamp
string
The unix timestamp for when the block was collated.
timestampFoS
string
The fraction of a second of the timestamp for when the block was collated.
totalBlockScore
string
Integer of the total blockScore of the chain until this block.
transactions
Array
Array of transaction objects, or 32-byte transaction hashes depending on the returnTransactionObjects
parameter.
transactionsRoot
string
The root of the transaction trie of the block.
voteData
string
RLP encoded governance vote of the proposer.
Example
caver.rpc.klay.getBlockReceipts
Returns receipts included in a block identified by block hash.
Parameters
blockHash
string
The block hash.
callback
function
(optional) Optional callback, returns an error object as the first parameter and the result as the second.
Return Value
Promise
returns Array
Array
Example
caver.rpc.klay.getBlockTransactionCountByNumber
Returns the number of transactions in a block matching the given block number.
Parameters
blockNumber
number | string
The block number or the block tag string (genesis
or latest
).
callback
function
(optional) Optional callback, returns an error object as the first parameter and the result as the second.
Return Value
Promise
returns string
string
The number of transactions in the given block in hex.
Example
caver.rpc.klay.getBlockTransactionCountByHash
Returns the number of transactions in a block matching the given block hash.
Parameters
blockHash
string
The block hash.
callback
function
(optional) Optional callback, returns an error object as the first parameter and the result as the second.
Return Value
Promise
returns string
string
The number of transactions in the given block in hex.
Example
caver.rpc.klay.getBlockWithConsensusInfoByNumber
Returns a block with consensus information matched by the given block number.
Parameters
blockNumber
number | string
The block number or the block tag string (genesis
or latest
).
callback
function
(optional) Optional callback, returns an error object as the first parameter and the result as the second.
Return Value
Promise
returns object
string
Example
caver.rpc.klay.getBlockWithConsensusInfoByHash
Returns a block with consensus information matched by the given hash.
Parameters
blockHash
string
The block hash.
callback
function
(optional) Optional callback, returns an error object as the first parameter and the result as the second.
Return Value
Promise
returns object
- A block object with consensus information (a proposer and a list of committee members), or null when no block was found:
blockScore
string
Former difficulty. Always 1 in the BFT consensus engine
committee
Array
Array of addresses of committee members of this block. The committee is a subset of validators who participated in the consensus protocol for this block.
extraData
string
The "extra data" field of this block.
gasUsed
string
The gas in total that was used by all transactions in this block.
governanceData
string
RLP encoded governance configuration
hash
string
Hash of the block. null
when it is a pending block.
logsBloom
string
The bloom filter for the logs of the block. null
when it is a pending block.
number
string
The block number. null
when it is a pending block.
originProposer
string
The proposal of 0 round at the same block number.
parentHash
string
Hash of the parent block.
proposer
string
The address of the block proposer.
receiptsRoot
string
The root of the receipts trie of the block.
reward
string
The address of the beneficiary to whom the block rewards were given.
round
number
The round number.
size
string
Integer the size of this block in bytes.
stateRoot
string
The root of the final state trie of the block.
timestamp
string
The unix timestamp for when the block was collated.
timestampFoS
string
The fraction of a second of the timestamp for when the block was collated.
totalBlockScore
string
Integer of the total blockScore of the chain until this block.
transactions
Array
Array of transaction objects.
transactionsRoot
string
The root of the transaction trie of the block.
voteData
string
RLP encoded governance vote of the proposer
Example
caver.rpc.klay.getCommittee
Returns a list of all validators in the committee at the specified block.
Parameters
blockNumber
number | string
(optional) A block number, or the string latest
or earliest
. If omitted, latest
will be used.
callback
function
(optional) Optional callback, returns an error object as the first parameter and the result as the second.
Return Value
Promise
returns Array
Array
Addresses of all validators in the committee at the given block.
Example
caver.rpc.klay.getCommitteeSize
Returns the size of the committee at the specified block.
Parameters
blockNumber
number | string
(optional) A block number, or the string latest
or earliest
. If omitted, latest
will be used.
callback
function
(optional) Optional callback, returns an error object as the first parameter and the result as the second.
Return Value
Promise
returns number
number
The size of the committee at the given block.
Example
caver.rpc.klay.getCouncil
Returns a list of all validators of the council at the specified block.
Parameters
blockNumber
number | string
(optional) A block number, or the string latest
or earliest
. If omitted, latest
will be used.
callback
function
(optional) Optional callback, returns an error object as the first parameter and the result as the second.
Return Value
Promise
returns Array
Array
An array of validator addresses of the council at the given block, or null when no council was found.
Example
caver.rpc.klay.getCouncilSize
Returns the size of the council at the specified block.
Parameters
blockNumber
number | string
(optional) A block number, or the string latest
or earliest
. If omitted, latest
will be used.
callback
function
(optional) Optional callback, returns an error object as the first parameter and the result as the second.
Return Value
Promise
returns number
number
The size of the council at the given block.
Example
caver.rpc.klay.getStorageAt
Returns the value from a storage position at a given address.
Parameters
address
string
The address to get the storage from.
position
number
blockNumber
number | string
(optional) A block number, or the string latest
or earliest
. If omitted, latest
will be used.
callback
function
(optional) Optional callback, returns an error object as the first parameter and the result as the second.
Return Value
Promise
returns string
string
The value at this storage position.
Example
caver.rpc.klay.isMinting
Returns true
if client is actively mining new blocks.
Parameters
callback
function
(optional) Optional callback, which returns an error object as the first parameter and the result as the second.
Return Value
Promise
returns boolean
- true
if the client is mining, otherwise false
.
Example
caver.rpc.klay.isSyncing
Returns an object with data about the sync status or false.
Parameters
callback
function
(optional) Optional callback, returns an error object as the first parameter and the result as the second.
Return Value
Promise
returns object|boolean
- false
if the Klaytn Node is not syncing. Otherwise, a sync object is returned:
startingBlock
string
The block number in hex where the sync started.
currentBlock
string
The block number in hex where the node currently synced to.
highestBlock
string
The estimated block number in hex to sync to.
knownStates
string
The estimated states in hex to download.
pulledStates
string
The already downloaded states in hex.
Example
caver.rpc.klay.call
Executes a new message call immediately without sending a transaction on the blockchain. It returns data or an error object of JSON RPC if an error occurs.
Parameters
callObject
object
A transaction call object. See the next table for the object's properties.
blockNumber
number | string
(optional) A block number, or the string latest
or earliest
. If omitted, latest
will be used.
callback
function
(optional) Optional callback, returns an error object as the first parameter and the result as the second.
callObject
has the following properties:
to
string
(optional when testing the deployment of a new contract) The address the transaction is directed to.
input
string
from
string
(optional) The address the transaction is sent from.
gas
string
(optional) The gas provided for the transaction execution. klay_call
consumes zero gas, but this parameter may be needed by some executions.
gasPrice
string
(optional) The gasPrice used for each paid gas.
value
string
(optional) The value sent with this transaction in peb
.
Return Value
Promise
returns string
string
The returned data of the call. e.g., the return value of a smart contract function.
Example