Node API Reference
Usage
The JSON-RPC API can be consumed through different transports: TCP, HTTP and Websockets. The node operator can enable or disable the JSON-RPC service, as well as specify a different network address for each transport in the node's configuration file. By default, the tcp
port is set to be 21338, http
to 21339 and the ws
to 21340.
Sensitive methods
Sensitive methods are those that either use the node's master key or provide information that may compromise the node's public key or address, or even the node's private key itself.
Sensitive methods allow node operators to easily manage their own nodes from a command line interface within the same host or private network. By default, sensitive methods are enabled.
When exposing any of the JSON-RPC ports (tcp/21388, http/21339, ws/21340) to a public IP, ensure to disable sensitive methods first by setting enable_sensitive_methods = false
in your node's witnet.toml configuration file.
Public methods
Public methods provide information that do not compromise node's private information, like its private or public key, or address:
addPeers
Add one or more peer addresses to the list of available ones.
Parameters
Vec<SocketAddr>
Returns
true
Example
authorizeStake
Create a stake authorization for the given address.
Parameters
Returns
Example
clearPeers
Clear all peers from the list of available ones.
Parameters
None.
Returns
true
Example
createVRF
Create a VRF proof for the provided message with the stored key.
Parameters
Vec<u8>
Returns
Vec<u8>
Example
dataRequestReport
Show information about a data request.
Parameters
drTxHash
: Data request transaction hash.
Returns
Example
getBalance
Get the balance of a the pkh
.
Parameters
pkh
: The public key hash to get the balance from.simple?
: Distinguish between fetching a simple balance or fetching confirmed and unconfirmed balance. Defaults to `false`.
Returns
Example
getBlock
Get detailed information about a block being queried by its hash.
Parameters
blockHash
: The hash of the block must be provided as a hexadecimal string.metadata
: (Optional) If set to true, transactions metadata will be provided.
Returns
Example
getBlockChain
Get the list of all the known block hashes.
Parameters
epoch
: (Optional) First epoch for which to return block hashes. If the provided value is negative, it returns block hashes from the last n epochs. Default to 0.limit
: (Optional) Number of block hashes to return. If the provided value is negative, return the last n block hashes from this epoch range. If the value is zero, it's unlimited. Default to 0.
Returns
Vec<u32, Hash>
: An array of epochs and block hashes.
Example
getConsensusConstants
Get consensus constants used by the node.
Parameters
None
Returns
Example
getMempool
Get all the pending transactions.
Parameters
None
Returns
Example
getPublicKey
Get the public key of the node.
Parameters
None
Returns
[u8; 33]
Example
getPkh
Get public address of the node.
Parameters
None
Returns
String
Example
getReputation
Displays the reputation score associated with a given public address and its eligibility to mine a block.
Parameters
pkh
: The Witnet public address.
Returns
Example
getReputationAll
Get all the nodes active and their elegibility. It also lists the nodes with reputation grater than 0 but not active, if any.
Note that it is perfectly normal for a node to show 0 reputation for the first days of it being up. Please be patient, new identities in the system are subject to a slow start for critical security reasons.
Parameters
None.
Returns
Example
getSuperblock
Get the blocks that pertain to the superblock specified.
Parameters
Map including one only of these:
block_epoch
: Superblock epoch.superblock_index
: Superblock index.
Returns
Example
getSupplyInfo
Get supply information.
Parameters
None
Returns
Example
getTransaction
Get detailed information about a transaction being queried by its hash.
Parameters
txHash
: It should be provided as a hexadecimal string.
Returns
Example
getUtxoInfo
Get unspent transaction outputs belonging to given public address.
Parameters
pkh
: Public address.
Returns
Example
knownPeers
Get the list of peer addresses known to the node.
Parameters
None
Returns
A list with the address of the peer and the type which can be new
or tried
.
Vec<
AddrType
>
Example
initializePeers
Initialize all known peers present in witnet.toml#connections.
Parameters
None
Returns
true
Example
inventory
Make the node process, validate and potentially broadcast a new inventory entry.
Parameters
Accepts the JSON serialization of a well-formed Block or Transaction.
Returns
true
if no errors.
Example
nodeStats
Get stats info from node.
Parameters
None
Returns
Example
masterKeyExport
Export the private key associated with the node identity in XPRV format.
Parameters
None
Returns
String
: Private key in XPRV format.
Example
peers
List inbound and outbound connections currently established by the node. Outbound connections are those initiated on our side, and inbound connections are those that were initiated by peer nodes. A node that does not announce a public address (IP and port) will normally have no inbound connections, as there is no way for other nodes to discover a valid network route to it.
Parameters
None
Returns
Vec<
AddrType
>
Example
priority
Get priority and time-to-block estimations for different priority tiers.
Parameters
None
Returns
PriorityEstimate
: A map whose keys represent the different levels of priority for data requests transactions and value transfer transactions: stinky, low, medium, high and opulent. The value is a map which includes:
priority
: priority value in nanowits per weight unit.time_to_block
: average for your transaction to be included in a block in seconds.
Example
protocol
Get information about protocol versions and which version is currently being enforced.
Parameters
None
Returns
Option<ProtocolInfo>
Example
queryStakes
Query amount of nanowits staked by an address or get all stake entries in the network.
Parameters
Returns
Example
rewind
Delete the chain state until the specified epoch and resync from there.
Parameters
Epoch:
u32
Returns
true
Example
sendRequest
Create and broadcast a data request transaction to the Witnet Network.
Parameters
Returns
Example
sendValue
Create and broadcast a value transfer transaction. That is, send some amount of wit coins from the node's own balance into a different Witnet address.
Parameters
Returns
Example
sign
Sign a piece of data with the node's master key.
Parameters
[u8; 32]
Returns
Example
signalingInfo
Get consolidated and on-going upgrades of the Witnet network.
Parameters
None
Returns
Example
stake
Create and broadcast a stake transaction to the Witnet Network.
Parameters
Returns
Example
syncStatus
Get node synchronization status.
Parameters
None
Returns
SyncStatus
: Map with the chain beacon, the current epoch and the state of the node. Values of node state are:
WaitingConsensus
: waiting for reaching consensus between its peersSynchronizing
: synchronization process.AlmostSynced
: it has all the blocks in the chain and is ready to start consolidating block candidates in real time.Synced
: can consolidate block candidates, propose its own candidates (mining) and participate in resolving data requests (witnessing).
Example
tryRequest
Ask your node to resolve data request locally, without actually broadcasting it to the Witnet network.
Parameters
DataRequestOutput
: unsigned data request struct with retrievals'script
and filters'args
fields encoded as CBOR values serialized asVec<u8>
arrays.
Returns
Data request result stringified as a RadonTypes value.
Example
unstake
Create and broadcast an unstake transaction to the Witnet Network.
Parameters
Returns
Example
Last updated