Oxen Core Node RPC

get_block

Full block information can be retrieved by either block height or hash, like with the above block header calls. For full block information, both lookups use the same method, but with different input parameters.

Parameters

• hash — The block's hash.
• height — A block height to look up; returned in block_header
• fill_pow_hash — Tell the daemon if it should fill out pow_hash field.

Returns

• status — General RPC status string. "OK" means everything looks good.
• block_header — Block header information for the requested height block
• tx_hashes — List of hashes of non-coinbase transactions in the block. If there are no other transactions, this will be an empty list.
• blob — Hexadecimal blob of block information.
• json — JSON formatted block details.

get_block_count

Look up how many blocks are in the longest chain known to the node.

Parameters

This endpoint takes no inputs. (An optional empty dict/object may be provided, but is not required.)

Returns

• status — General RPC status string. "OK" means everything looks good.
• count — Number of blocks in logest chain seen by the node.

get_block_hash

Look up one or more blocks' hashes by their height.

Parameters

• heights array of block heights of which to look up the block hashes. Accepts at most 1000 heights per request.

Returns

• status — General RPC status string. "OK" means everything looks good.
• height — the current blockchain height of this node
• "<height>" the block hash of the block with the given height. Note that each height key is the stringified integer value, e.g. "3456" rather than 3456.

Example Input

{ "heights": [42, 123456] }

Example Output

{
  "status": "OK",
  "height": 123456,
  "42": "b269367374fa87ec517405bf120f831e9b13b12c0ee6721dcca69d2c0fe73a0f",
  "123456": "aa1f3b566aba42e522f8097403a3c513069206286ff08c2ff2871757dbc3e436"
}

get_block_header_by_hash

Block header information can be retrieved using either a block's hash or height. This method includes a block's hash as an input parameter to retrieve basic information about the block.

Parameters

• hash — The block's hash.
• hashes — Request multiple blocks via an array of hashes
• fill_pow_hash — Tell the daemon if it should fill out pow_hash field.
• get_tx_hashes — If true (default false) then include the hashes of non-coinbase transactions

Returns

• status — General RPC status string. "OK" means everything looks good.
• block_header — Block header information for the requested hash block
• block_headers — Block header information for the requested hashes blocks

get_block_header_by_height

Similar to get_block_header_by_hash above, this method includes a block's height as an input parameter to retrieve basic information about the block.

Parameters

• height — A block height to look up; returned in block_header
• heights — Block heights to retrieve; returned in block_headers
• fill_pow_hash — Tell the daemon if it should fill out pow_hash field.
• get_tx_hashes — If true (default false) then include the hashes of non-coinbase transactions

Returns

• status — General RPC status string. "OK" means everything looks good.
• block_header — Block header information for the requested height block
• block_headers — Block header information for the requested heights blocks

get_block_headers_range

Similar to get_block_header_by_height above, but for a range of blocks. This method includes a starting block height and an ending block height as parameters to retrieve basic information about the range of blocks.

Parameters

• start_height — The starting block's height.
• end_height — The ending block's height.
• fill_pow_hash — Tell the daemon if it should fill out pow_hash field.
• get_tx_hashes — If true (default false) then include the hashes of non-coinbase transactions

Returns

• status — General RPC status string. "OK" means everything looks good.
• headers — Array of block_header (a structure containing block header information. See get_last_block_header).

get_checkpoints

Query hardcoded/service node checkpoints stored for the blockchain. Omit all arguments to retrieve the latest "count" checkpoints.

Parameters

• start_height — Optional: Get the first count checkpoints starting from this height. Specify both start and end to get the checkpoints inbetween.
• end_height — Optional: Get the first count checkpoints before end height. Specify both start and end to get the checkpoints inbetween.
• count — Optional: Number of checkpoints to query.

Returns

• status — generic RPC error code; "OK" means the request was successful.
• checkpoints — Array of requested checkpoints

get_fee_estimate

Gives an estimation of per-output + per-byte fees

Parameters

• grace_blocks — If specified, make sure that the fee is high enough to cover any fee increases in the next grace_blocks blocks.

Returns

• status — General RPC status string. "OK" means everything looks good.
• emission_amount — Amount of coinbase reward in atomic units.
• fee_amount — Amount of fees in atomic units.
• burn_amount — Amount of burnt oxen.
• fee_per_byte — Amount of fees estimated per byte in atomic units
• fee_per_output — Amount of fees per output generated by the tx (adds to the fee_per_byte per-byte value)
• blink_fee_per_byte — Value for sending a blink. The portion of the overall blink fee above the overall base fee is burned.
• blink_fee_per_output — Value for sending a blink. The portion of the overall blink fee above the overall base fee is burned.
• blink_fee_fixed — Fixed blink fee in addition to the per-output and per-byte amounts. The portion of the overall blink fee above the overall base fee is burned.
• quantization_mask

get_height

Get the node's current height.

Parameters

This endpoint takes no inputs. (An optional empty dict/object may be provided, but is not required.)

Returns

• height — The current blockchain height according to the queried daemon.
• status — Generic RPC error code. "OK" is the success value.
• hash — Hash of the block at the current height
• immutable_height — The latest height in the blockchain that cannot be reorganized because of a hardcoded checkpoint or 2 SN checkpoints. Omitted if not available.
• immutable_hash — Hash of the highest block in the chain that cannot be reorganized.

Example Output

{
  "hash": "3a9cb03c59945d5233c3dc59d8c6a7f2e93d5b09bf8d74a0216b51e87d32053d",
  "height": 946867,
  "immutable_hash": "1329cc4a2fe207c7853a44b98900f424eb23bd59c91354812e1610d40e393986",
  "immutable_height": 946860,
  "status": "OK",
  "untrusted": false
}

get_info

Retrieve general information about the state of the node and the network.

Parameters

This endpoint takes no inputs. (An optional empty dict/object may be provided, but is not required.)

Returns

• status — General RPC status string. "OK" means everything looks good.
• height — Current length of longest chain known to daemon.
• target_height — The height of the next block in the chain.
• immutable_height — The latest height in the blockchain that can not be reorganized (i.e. is backed by at least 2 Service Node, or 1 hardcoded checkpoint, 0 if N/A). Omitted if it cannot be determined (typically because the node is still syncing).
• pulse — will be true if the next expected block is a pulse block, false otherwise.
• pulse_ideal_timestamp — For pulse blocks this is the ideal timestamp of the next block, that is, the timestamp if the network was operating with perfect 2-minute blocks since the pulse hard fork.
• pulse_target_timestamp — For pulse blocks this is the target timestamp of the next block, which targets 2 minutes after the previous block but will be slightly faster/slower if the previous block is behind/ahead of the ideal timestamp.
• difficulty — Network mining difficulty; omitted when the network is expecting a pulse block.
• target — Current target for next proof of work.
• tx_count — Total number of non-coinbase transaction in the chain.
• tx_pool_size — Number of transactions that have been broadcast but not included in a block.
• mainnet — Indicates whether the node is on the main network (true) or not (false).
• testnet — Indicates that the node is on the test network (true). Will be omitted for non-testnet.
• devnet — Indicates that the node is on the dev network (true). Will be omitted for non-devnet.
• fakechain — States that the node is running in "fakechain" mode (true). Omitted otherwise.
• nettype — String value of the network type (mainnet, testnet, devnet, or fakechain).
• top_block_hash — Hash of the highest block in the chain. Will be hex for JSON requests, 32-byte binary value for bt requests.
• immutable_block_hash — Hash of the highest block in the chain that can not be reorganized. Hex string for json, bytes for bt.
• cumulative_difficulty — Cumulative difficulty of all blocks in the blockchain.
• block_size_limit — Maximum allowed block size.
• block_size_median — Median block size of latest 100 blocks.
• ons_counts — ONS registration counts, as a three-element list: [session, wallet, lokinet]
• offline — Indicates that the node is offline, if true. Omitted for online nodes.
• database_size — Current size of Blockchain data. Over public RPC this is rounded up to the next-largest GB value.
• version — Current version of this daemon, as a string. For a public node this will just be the major and minor version (e.g. "9"); for an admin rpc endpoint this will return the full version (e.g. "9.2.1").
• status_line — A short one-line summary string of the node (requires an admin/unrestricted connection for most details)

If the endpoint is a restricted (i.e. admin) endpoint then the following fields are also included:

• alt_blocks_count — Number of alternative blocks to main chain.
• outgoing_connections_count — Number of peers that you are connected to and getting information from.
• incoming_connections_count — Number of peers connected to and pulling from your node.
• white_peerlist_size — White Peerlist Size
• grey_peerlist_size — Grey Peerlist Size
• service_node — Will be true if the node is running in --service-node mode.
• start_time — Start time of the daemon, as UNIX time.
• last_storage_server_ping — Last ping time of the storage server (0 if never or not running as a service node)
• last_lokinet_ping — Last ping time of lokinet (0 if never or not running as a service node)
• free_space — Available disk space on the node.

Example Output

{
  "block_size_limit": 600000,
  "block_size_median": 300000,
  "block_weight_limit": 600000,
  "block_weight_median": 300000,
  "cumulative_difficulty": 4556030616038589,
  "database_size": 17000000000,
  "devnet": false,
  "difficulty": 1000000,
  "height": 947084,
  "immutable_block_hash": "628923285c83aee8cf585d87acd59edebb5d41cc6433db894a3fb6d5c14bdde5",
  "immutable_height": 947076,
  "mainnet": true,
  "nettype": "mainnet",
  "offline": false,
  "ons_counts": [
    584,
    34,
    331
  ],
  "pulse_ideal_timestamp": 1639186221,
  "pulse_target_timestamp": 1639186221,
  "status": "OK",
  "status_line": "v9; Height: 947084",
  "target": 120,
  "target_height": 945528,
  "testnet": false,
  "top_block_hash": "24b9f97623ba08c33bfe30eaa49f69342e9ffd267a8b4657dcf61b8f8a90853a",
  "tx_count": 791186,
  "tx_pool_size": 0,
  "untrusted": false,
  "version": "9"
}

get_last_block_header

Block header information for the most recent block is easily retrieved with this method. No inputs are needed.

Parameters

• fill_pow_hash — Tell the daemon if it should fill out pow_hash field.
• get_tx_hashes — If true (default false) then include the hashes of non-coinbase transactions

Returns

• status — General RPC status string. "OK" means everything looks good.
• block_header — A dict containing block header information. Contains keys:
• major_version — The major version of the oxen protocol at this block height.
• minor_version — The minor version of the oxen protocol at this block height.
• timestamp — The unix time at which the block was recorded into the blockchain.
• prev_hash — The hash of the block immediately preceding this block in the chain.
• nonce — A cryptographic random one-time number used in mining a Loki block.
• orphan_status — Usually false. If true, this block is not part of the longest chain.
• height — The number of blocks preceding this block on the blockchain.
• depth — The number of blocks succeeding this block on the blockchain. A larger number means an older block.
• hash — The hash of this block.
• difficulty — The strength of the Loki network based on mining power.
• cumulative_difficulty — The cumulative strength of the Loki network based on mining power.
• reward — The amount of new generated in this block and rewarded to the miner, foundation and service Nodes. Note: 1 OXEN = 1e9 atomic units.
• miner_reward — The amount of new generated in this block and rewarded to the miner. Note: 1 OXEN = 1e9 atomic units.
• block_size — The block size in bytes.
• block_weight — The block weight in bytes.
• num_txes — Number of transactions in the block, not counting the coinbase tx.
• pow_hash — The hash of the block's proof of work (requires fill_pow_hash)
• long_term_weight — Long term weight of the block.
• miner_tx_hash — The TX hash of the miner transaction
• tx_hashes — The TX hashes of all non-coinbase transactions (requires get_tx_hashes)
• service_node_winner — Service node that received a reward for this block

get_output_histogram

Get a histogram of output amounts. For all amounts (possibly filtered by parameters), gives the number of outputs on the chain for that amount. RingCT outputs counts as 0 amount.

Parameters

• amounts — list of amounts in Atomic Units.
• min_count — The minimum amounts you are requesting.
• max_count — The maximum amounts you are requesting.
• unlocked — Look for locked only.
• recent_cutoff

Returns

• status — General RPC status string. "OK" means everything looks good.
• histogram — List of histogram entries. Each element is structured as follows:
• uint64_t — amount Output amount in atomic units.
• uint64_t — total_instances
• uint64_t — unlocked_instances
• uint64_t — recent_instances

get_outs

Retrieve transaction outputs

Parameters

• outputs — Array of output indices. For backwards compatibility these may also be passed as an array of {"amount":0,"index":n} dicts.
• get_txid — Request the TXID (i.e. hash) of the transaction as well.
• as_tuple — Requests the returned outs variable as a tuple of values rather than a dict.

Returns

• status — General RPC status string. "OK" means everything looks good.
• outs — List of outkey information; if as_tuple is not set then these are dicts containing keys:
• key — The public key of the output.
• mask
• unlocked — States if output is locked (false) or not (true).
• height — Block height of the output.
• txid — Transaction id; only present if requested via the get_txid parameter. Otherwise, when as_tuple is set, these are 4- or 5-element arrays (depending on whether get_txid is desired) containing the values in the order listed above.

get_quorum_state

Accesses the list of public keys of the nodes who are participating or being tested in a quorum.

Parameters

• start_height — (Optional): Start height, omit both start and end height to request the latest quorum. Note that "latest" means different heights for different types of quorums as not all quorums exist at every block heights.
• end_height — (Optional): End height, omit both start and end height to request the latest quorum
• quorum_type — (Optional): Set value to request a specific quorum, 0 = Obligation, 1 = Checkpointing, 2 = Blink, 3 = Pulse, 255 = all quorums, default is all quorums. For Pulse quorums, requesting the blockchain height (or latest) returns the primary pulse quorum responsible for the next block; for heights with blocks this returns the actual quorum, which may be a backup quorum if the primary quorum did not produce in time.

Returns

• status — General RPC status string. "OK" means everything looks good.
• quorums — An array of quorums associated with the requested height. Each element is structured with the following keys:
• service_node_pubkey — The public key of the Service Node, in hex (json) or binary (bt).
• height — The height the quorums are relevant for
• quorum_type — The quorum type
• quorum — Quorum of Service Nodes. Each element is structured with the following keys:
  • validators — List of service node public keys in the quorum. For obligations quorums these are the testing nodes; for checkpoint and blink these are the participating nodes (there are no workers); for Pulse blink quorums these are the block signers. This is hex encoded, even for bt-encoded requests.
  • workers — Public key of the quorum workers. For obligations quorums these are the nodes being tested; for Pulse quorums this is the block producer. Checkpoint and Blink quorums do not populate this field. This is hex encoded, even for bt-encoded requests.

get_service_node_blacklisted_key_images

Get information on blacklisted Service Node key images.

Parameters

This endpoint takes no inputs. (An optional empty dict/object may be provided, but is not required.)

Returns

• status — generic RPC error code; "OK" means the request was successful.
• blacklist — Array of blacklisted key images, i.e. unspendable transactions. Each entry contains
• key_image — The key image of the transaction that is blacklisted on the network.
• unlock_height — The height at which the key image is removed from the blacklist and becomes spendable.
• amount — The total amount of locked Loki in atomic units in this blacklisted stake.

get_service_nodes

Get information on some, all, or a random subset of Service Nodes.

Parameters

• fields — Set of fields to return; listed fields apply to both the top level (such as "height" or "block_hash") and to keys inside service_node_states. Fields should be provided as a list of field names to include. For backwards compatibility when making a json request field names can also be provided as a dictionary of {"field_name": true} pairs, but this usage is deprecated (and not supported for bt-encoded requests).

  The special field name "all" can be used to request all available fields; this is the default when no fields key are provided at all. Be careful when requesting all fields: the response can be very large.

  When providing a list you may prefix a field name with a - (e.g. "-funded") to remove the field from the list; this is mainly useful when following "all" to remove some fields from the returned results. (There is no equivalent mode when using the deprecated dict value).

• service_node_pubkeys — Array of public keys of registered service nodes to request information about. Omit to query all service nodes. For a JSON request pubkeys must be specified in hex; for a bt-encoded request pubkeys can be hex or bytes.

• active_only — If true then only return active service nodes.

• limit — If specified and non-zero then only return a random selection of this number of service nodes (in random order) from the result. If negative then no limiting is performed but the returned result is still shuffled.

• poll_block_hash — If specified then only return results if the current top block hash is different than the hash given here. This is intended to allow quick polling of results without needing to do anything if the block (and thus SN registrations) have not changed since the last request.

Returns

Output variables available are as follows (you can request which parameters are returned; see the request parameters description). Note that OXEN values are returned in atomic OXEN units, which are nano-OXEN (i.e. 1.000000000 OXEN will be returned as 1000000000).

• height — the height of the current top block. (Note that this is one less than the "blockchain height" as would be returned by the get_info endpoint).
• target_height — the target height of the blockchain; will be greater than height+1 if this node is still syncing the chain.
• block_hash — the hash of the most recent block
• hardfork — the current hardfork version of the daemon
• snode_revision — the current snode revision for non-hardfork, but mandatory, service node updates.
• status — generic RPC error code; "OK" means the request was successful.
• unchanged — when using poll_block_hash, this value is set to true and results are omitted if the current block hash has not changed from the requested polling block hash. If block hash has changed this is set to false (and results included). When not polling this value is omitted entirely.
• service_node_states — list of information about all known service nodes; each element is a dict containing the following keys (which fields are included/omitted can be controlled via the "fields" input parameter):
• service_node_pubkey — The public key of the Service Node, in hex (json) or binary (bt).
• registration_height — The height at which the registration for the Service Node arrived on the blockchain.
• registration_hf_version — The current hard fork at which the registration for the Service Node arrived on the blockchain.
• requested_unlock_height — If an unlock has been requested for this SN, this field contains the height at which the Service Node registration expires and contributions will be released.
• last_reward_block_height — The height that determines when this service node will next receive a reward. This field is somewhat misnamed for historic reasons: it is updated when receiving a reward, but is also updated when a SN is activated, recommissioned, or has an IP change position reset, and so does not strictly indicate when a reward was received.
• last_reward_transaction_index — When multiple Service Nodes register (or become active/reactivated) at the same height (i.e. have the same last_reward_block_height), this field contains the activating transaction position in the block which is used to break ties in determining which SN is next in the reward list.
• active — True if fully funded and not currently decommissioned (and so funded and not active implicitly defines decommissioned).
• funded — True if the required stakes have been submitted to activate this Service Node.
• state_height — Indicates the height at which the service node entered its current state:
  • If active is true: this is the height at which the service node last became active (i.e. became fully staked, or was last recommissioned);
  • If decommissioned (i.e. funded and not active): the decommissioning height;
  • If awaiting contributions (i.e. not funded): the height at which the last contribution (or registration) was processed.
• decommission_count — The number of times the Service Node has been decommissioned since registration
• last_decommission_reason_consensus_all — The reason for the last decommission as voted by the testing quorum SNs that decommissioned the node. This is a numeric bitfield made up of the sum of given reasons (multiple reasons may be given for a decommission). Values are included here if all quorum members agreed on the reasons:
  • 0x01 - Missing uptime proofs
  • 0x02 - Missed too many checkpoint votes
  • 0x04 - Missed too many pulse blocks
  • 0x08 - Storage server unreachable
  • 0x10 - oxend quorumnet unreachable for timesync checks
  • 0x20 - oxend system clock is too far off
  • 0x40 - Lokinet unreachable
  • other bit values are reserved for future use.
• last_decommission_reason_consensus_any — The reason for the last decommission as voted by any SNs. Reasons are set here if any quorum member gave a reason, even if not all quorum members agreed. Bit values are the same as last_decommission_reason_consensus_all.
• decomm_reasons — a gentler version of the last_decommission_reason_consensus_all/_any values: this is returned as a dict with two keys, "all" and "some", containing a list of short string identifiers of the reasons. "all" contains reasons that are agreed upon by all voting nodes; "some" contains reasons that were provided by some but not all nodes (and is included only if there are at least one such value). Note that, unlike last_decommission_reason_consensus_any, the "some" field only includes reasons that are not included in "all". Returned values in the lists are:
  • "uptime"
  • "checkpoints"
  • "pulse"
  • "storage"
  • "timecheck"
  • "timesync"
  • "lokinet"
  • other values are reserved for future use.
• earned_downtime_blocks — The number of blocks earned towards decommissioning (if currently active), or the number of blocks remaining until the service node is eligible for deregistration (if currently decommissioned).
• service_node_version — The three-element numeric version of the Service Node (as received in the last uptime proof). Omitted if we have never received a proof.
• lokinet_version — The major, minor, patch version of the Service Node's lokinet router (as received in the last uptime proof). Omitted if we have never received a proof.
• storage_server_version — The major, minor, patch version of the Service Node's storage server (as received in the last uptime proof). Omitted if we have never received a proof.
• contributors — Array of contributors, contributing to this Service Node. Each element is a dict containing:
  • amount — The total amount of OXEN staked by this contributor into this Service Node.
  • reserved — The amount of OXEN reserved by this contributor for this Service Node; this field will be included only if the contributor has unfilled, reserved space in the service node.
  • address — The wallet address of this contributor to which rewards are sent and from which contributions were made.
  • locked_contributions — Array of contributions from this contributor; this field (unlike the other fields inside contributors) is controlled by the fields input parameter. Each element contains:
  • key_image — The contribution's key image which is locked on the network.
  • key_image_pub_key — The contribution's key image, public key component.
  • amount — The amount of OXEN that is locked in this contribution.
• total_contributed — The total amount of OXEN contributed to this Service Node.
• total_reserved — The total amount of OXEN contributed or reserved for this Service Node. Only included in the response if there are still unfilled reservations (i.e. if it is greater than total_contributed).
• staking_requirement — The total OXEN staking requirement in that is/was required to be contributed for this Service Node.
• portions_for_operator — The operator fee to take from the service node reward, as a fraction of 18446744073709551612 (2^64 - 4) (that is, this number corresponds to 100%). Note that some JSON parsers may silently change this value while parsing as typical values do not fit into a double without loss of precision.
• operator_fee — The operator fee expressed in millionths (and rounded to the nearest integer value). That is, 1000000 corresponds to a 100% fee, 34567 corresponds to a 3.4567% fee. Note that this number is for human consumption; the actual value that matters for the blockchain is the precise portions_for_operator value.
• swarm_id — The numeric identifier of the Service Node's current swarm. Note that returned values can exceed the precision available in a double value, which can result in (changed) incorrect values by some JSON parsers. Consider using swarm instead if you are not sure your JSON parser supports 64-bit values.
• swarm — The swarm id, expressed in hexadecimal, such as "f4ffffffffffffff".
• operator_address — The wallet address of the Service Node operator.
• public_ip — The public ip address of the service node; omitted if we have not yet received a network proof containing this information from the service node.
• storage_port — The port number associated with the storage server; omitted if we have no uptime proof yet.
• storage_lmq_port — The port number associated with the storage server (oxenmq interface); omitted if we have no uptime proof yet.
• quorumnet_port — The port for direct SN-to-SN oxend communication (oxenmq interface). Omitted if we have no uptime proof yet.
• pubkey_ed25519 — The service node's ed25519 public key for auxiliary services. Omitted if we have no uptime proof yet. Note that for newer registrations this will be the same as the service_node_pubkey.
• pubkey_x25519 — The service node's x25519 public key for auxiliary services (mainly used for quorumnet_port and the storage_lmq_port OxenMQ encrypted connections).
• last_uptime_proof — The last time we received an uptime proof for this service node from the network, in unix epoch time. 0 if we have never received one.
• storage_server_reachable — True if this storage server is currently passing tests for the purposes of SN node testing: true if the last test passed, or if it has been unreachable for less than an hour; false if it has been failing tests for more than an hour (and thus is considered unreachable). This field is omitted if the queried oxend is not a service node.
• storage_server_first_unreachable — If the last test we received was a failure, this field contains the timestamp when failures started. Will be 0 if the last result was a success, and will be omitted if the node has not yet been tested since this oxend last restarted.
• storage_server_last_unreachable — The last time this service node's storage server failed a ping test (regardless of whether or not it is currently failing). Will be omitted if it has never failed a test since startup.
• storage_server_last_reachable — The last time we received a successful ping response for this storage server (whether or not it is currently failing). Will be omitted if we have never received a successful ping response since startup.
• lokinet_reachable — Same as storage_server_reachable, but for lokinet router testing.
• lokinet_first_unreachable — Same as storage_server_first_unreachable, but for lokinet router testing.
• lokinet_last_unreachable — Same as storage_server_last_unreachable, but for lokinet router testing.
• lokinet_last_reachable — Same as storage_server_last_reachable, but for lokinet router testing.
• checkpoint_votes — dict containing recent received checkpoint voting information for this service node. Service node tests will fail if too many recent pulse blocks are missed. Contains keys:
  • voted — list of blocks heights at which a required vote was received from this service node
  • missed — list of block heights at which a vote from this service node was required but not received.
• pulse_votes — dict containing recent pulse blocks in which this service node was supposed to have participated. Service node testing will fail if too many recent pulse blocks are missed. Contains keys:
  • voted — list of [<HEIGHT>, <ROUND>] pairs in which an expected pulse participation was recorded for this node. <ROUND> starts at 0 and increments for backup pulse quorums if a previous round does not broadcast a pulse block for the given height in time.
  • missed — list of [<HEIGHT>, <ROUND>] pairs in which pulse participation by this service node was expected but did not occur.
• quorumnet_tests — array containing the results of recent attempts to connect to the remote node's quorumnet port (while conducting timesync checks). The array contains two values: [<SUCCESSES>, <FAILURES>], where <SUCCESSES> is the number of recent successful connections and FAILURES is the number of recent connection and/or request timeouts. If there are two many failures then the service node will fail testing.
• timesync_tests — array containing the results of recent time synchronization checks of this service node. Contains [<SUCCESSES>, <FAILURES>] counts where <SUCCESSES> is the number of recent checks where the system clock was relatively close and FAILURES is the number of recent checks where we received a significantly out-of-sync timestamp response from the service node. A service node fails tests if there are too many recent out-of-sync responses.

get_service_nodes_state_changes

Query the number of service node state change transactions contained in a range of blocks.

Parameters

• start_height — The starting block's height.
• end_height — The ending block's height.

Returns

• status — Generic RPC error code. "OK" is the success value.
• total_deregister — the total number of service node deregistrations
• total_ip_change_penalty — the total number of IP change penalties
• total_decommission — the total number of service node decommissions
• total_recommission — the total number of service node recommissions
• total_unlock — the total number of service node unlock requests
• start_height — the start height of the given statistics
• end_height — the end height of the given statistics

get_staking_requirement

Get the required amount of Oxen to become a Service Node at the queried height. For devnet and testnet values, ensure the daemon is started with the --devnet or --testnet flags respectively.

Parameters

• height — The height to query the staking requirement for. 0 (or omitting) means current height.

Returns

• status — generic RPC error code; "OK" means the request was successful.
• staking_requirement — The staking requirement in Oxen, in atomic units.
• height — The height requested (or current height if 0 was requested)

get_transaction_pool_hashes

Get hashes from transaction pool.

Parameters

This endpoint takes no inputs. (An optional empty dict/object may be provided, but is not required.)

Returns

• status — General RPC status string. "OK" means everything looks good.
• tx_hashes — List of transaction hashes,

get_transaction_pool_stats

Get the transaction pool statistics.

Parameters

This endpoint takes no inputs. (An optional empty dict/object may be provided, but is not required.)

Returns

• status — General RPC status string. "OK" means everything looks good.
• pool_stats — Dict of pool statistics:
• bytes_total — the total size (in bytes) of the transactions in the transaction pool.
• bytes_min — the size of the smallest transaction in the tx pool.
• bytes_max — the size of the largest transaction in the pool.
• bytes_med — the median transaction size in the pool.
• fee_total — the total fees of all transactions in the transaction pool.
• txs_total — the total number of transactions in the transaction pool
• num_failing — the number of failing transactions: that is, transactions that are in the mempool but are not currently eligible to be added to the blockchain.
• num_10m — the number of transactions received within the last ten minutes
• num_not_relayed — the number of transactions which are not being relayed to the network. Only included when the include_unrelayed request parameter is set to true.
• num_double_spends — the number of transactions in the mempool that are marked as double-spends of existing blockchain transactions.
• oldest — the unix timestamp of the oldest transaction in the pool.
• histo — pairs of [# txes, size of bytes] that form a histogram of transactions in the mempool, if there are at least two transactions in the mempool (and omitted entirely otherwise). When present, this field will contain 10 pairs:
  • When histo_max is given then histo consists of 10 equally-spaced bins from newest to oldest where the newest bin begins at age 0 and the oldest bin ends at age histo_max. For example, bin [3] contains statistics for transactions with ages between 3*histo_max/10 and 4*histo_max/10.
  • Otherwise histo_98pc will be present in which case histo contains 9 equally spaced bins from newest to oldest where the newest bin begins at age 0 and the oldest bin ends at age histo_98pc, and at least 98% of the mempool transactions will fall in these 9 bins. The 10th bin contains statistics for all transactions with ages greater than histo_98pc.
• histo_98pc — See histo for details.
• histo_max — See histo for details.

get_transactions

Look up one or more transactions by hash.

Parameters

• tx_hashes — List of transaction hashes to look up. (Will also be accepted as json input key "txs_hashes" for backwards compatibility). Exclusive of memory_pool.
• memory_pool — If true then return all transactions and spent key images currently in the memory pool. This field is exclusive of tx_hashes.
• tx_extra — If set to true then parse and return tx-extra information
• data — Controls whether the data (or pruned, if pruned) field containing raw tx data is included: if explicitly specified then the raw data will be included if true. Otherwise the raw data is included only when neither of split nor prune are set to true.
• split — If set to true then always split transactions into non-prunable and prunable parts in the response.
• prune — Like split, but also omits the prunable part of transactions from the response details.

Returns

• status — Generic RPC error code. "OK" is the success value.
• missed_tx — set of transaction hashes that were not found. If all were found then this field is omitted. There is no particular ordering of hashes in this list.
• txs — list of transaction details; each element is a dict containing:
• tx_hash — Transaction hash.
• size — Size of the transaction, in bytes. Note that if the transaction has been pruned this is the post-pruning size, not the original size.
• in_pool — Will be set to true if the transaction is in the transaction pool (true) and omitted if mined into a block.
• blink — True if this is an approved, blink transaction; this information is generally only available for approved in-pool transactions and txes in very recent blocks.
• fee — the transaction fee (in atomic OXEN) incurred in this transaction (not including any burned amount).
• burned — the amount of OXEN (in atomic units) burned by this transaction.
• block_height — Block height including the transaction. Omitted for tx pool transactions.
• block_timestamp — Unix time at which the block has been added to the blockchain. Omitted for tx pool transactions.
• output_indices — List of transaction indexes. Omitted for tx pool transactions.
• relayed — For in_pool transactions this field will be set to indicate whether the transaction has been relayed to the network.
• double_spend_seen — Will be set to true for tx pool transactions that are double-spends (and thus cannot be added to the blockchain). Omitted for mined transactions.
• received_timestamp — Timestamp transaction was received in the pool. Omitted for mined blocks.
• max_used_block — the hash of the highest block referenced by this transaction; only for mempool transactions.
• max_used_height — the height of the highest block referenced by this transaction; only for mempool transactions.
• last_failed_block — the hash of the last block where this transaction was attempted to be mined (but failed).
• max_used_height — the height of the last block where this transaction failed to be acceptable for a block.
• weight — the transaction "weight" which is the size of the transaction with padding removed. Only included for mempool transactions (for mined transactions the size and weight at the same and so only size is included).
• kept_by_block will be present and true if this is a mempool transaction that was added to the mempool after being popped off a block (e.g. because of a blockchain reorganization).
• last_relayed_time indicates the last time this block was relayed to the network; only for mempool transactions.
• do_not_relay — set to true for mempool blocks that are marked "do not relay"
• double_spend_seen — set to true if one or more outputs in this mempool transaction have already been spent (and thus the tx cannot currently be added to the blockchain).
• data — Full, unpruned transaction data. For a json request this is hex-encoded; for a bt-encoded request this is raw bytes. This field is omitted if any of decode_as_json, split, or prune is requested; or if the transaction has been pruned in the database.
• pruned — The non-prunable part of the transaction, encoded as hex (for json requests). Always included if split or prune are specified; without those options it will be included instead of data if the transaction has been pruned.
• prunable — The prunable part of the transaction. Only included when split is specified, the transaction is prunable, and the tx has not been pruned from the database.
• prunable_hash — The hash of the prunable part of the transaction. Will be provided if either: the tx has been pruned; or the tx is prunable and either of prune or split are specified.
• extra — Parsed "extra" transaction information; omitted unless specifically requested (via the tx_extra request parameter). This is a dict containing one or more of the following keys.
  • pubkey — The tx extra public key
  • burn_amount — The amount of OXEN that this transaction burns, if any.
  • extra_nonce — Optional extra nonce value (in hex); will be empty if nonce is recognized as a payment id
  • payment_id — The payment ID, if present. This is either a 16 hex character (8-byte) encrypted payment id, or a 64 hex character (32-byte) deprecated, unencrypted payment ID
  • mm_depth — (Merge-mining) the merge-mined depth
  • mm_root — (Merge-mining) the merge mining merkle root hash
  • additional_pubkeys — Additional public keys
  • sn_winner — Service node block reward winner public key
  • sn_pubkey — Service node public key (e.g. for registrations, stakes, unlocks)
  • sn_contributor — Service node contributor wallet address (for stakes)
  • tx_secret_key — The transaction secret key, included in registrations/stakes to decrypt transaction amounts and recipients
  • locked_key_images — Key image(s) locked by the transaction (for registrations, stakes)
  • key_image_unlock — A key image being unlocked in a stake unlock request (an unlock will be started for all key images locked in the same SN contributions).
  • sn_registration — Service node registration details; this is a dict containing:
  • fee the operator fee expressed in millionths (i.e. 234567 == 23.4567%)
  • expiry the unix timestamp at which the registration signature expires
  • contributors: dict of (wallet => portion) pairs indicating the staking portions reserved for the operator and any reserved contribution spots in the registration. Portion is expressed in millionths (i.e. 250000 = 25% staking portion).
  • sn_state_change — Information for a "state change" transaction such as a deregistration, decommission, recommission, or ip change reset transaction. This is a dict containing:
  • old_dereg will be set to true if this is an "old" deregistration transaction (before the Loki 4 hardfork), omitted for more modern state change txes.
  • type string indicating the state change type: "dereg", "decomm", "recomm", or "ip" for a deregistration, decommission, recommission, or ip change penalty transaction.
  • height the voting block height for the changing service node and voting service nodes that produced this state change transaction.
  • index the position of the affected node in the random list of tested nodes for this height.
  • voters the positions of validators in the testing quorum for this height who tested and voted for this state change. This typically contains the first 7 voters who voted for the state change (out of a possible set of 10).
  • reasons list of reported reasons for a decommission or deregistration as reported by the voting quorum. This contains any reasons that all 7+ voters agreed on, and contains one or more of:
    • "uptime" — the service node was missing uptime proofs
    • "checkpoints" — the service node missed too many recent checkpoint votes
    • "pulse" — the service node missed too many recent pulse votes
    • "storage" — the service node's storage server was unreachable for too long
    • "lokinet" — the service node's lokinet router was unreachable for too long
    • "timecheck" — the service node's oxend was not reachable for too many recent time synchronization checks. (This generally means oxend's quorumnet port is not reachable).
    • "timesync" — the service node's clock was too far out of sync The list is omitted entirely if there are no reasons at all or if there are no reasons that were agreed upon by all voting service nodes.
  • reasons_maybe list of reported reasons that some but not all service nodes provided for the deregistration/decommission. Possible values are identical to the above. This list is omitted entirely if it would be empty (i.e. there are no reasons at all, or all voting service nodes agreed on all given reasons).
  • ons — ONS registration or update transaction details. This contains keys:
  • buy — set to true if this is an ONS buy record; omitted otherwise.
  • update — set to true if this is an ONS record update; omitted otherwise.
  • renew — set to true if this is an ONS renewal; omitted otherwise.
  • type — the ONS request type string. For registrations: "lokinet", "session", "wallet"; for a record update: "update".
  • blocks — The registration length in blocks; omitted for registrations (such as Session/Wallets) that do not expire.
  • name_hash — The hashed name of the record being purchased/updated. Encoded in hex for json requests. Note that the actual name is not provided on the blockchain.
  • prev_txid — For an update this field is set to the txid of the previous ONS update or registration (i.e. the most recent transaction that this record is updating).
  • value — The encrypted value of the record (in hex for json requests) being set/updated. See ons_resolve for details on encryption/decryption.
  • owner — the owner of this record being set in a registration or update; this can be a primary wallet address, wallet subaddress, or a plain public key.
  • backup_owner — an optional backup owner who also has permission to edit the record.
• stake_amount — Set to the calculated transaction stake amount (only applicable if the transaction is a service node registration or stake).
• mempool_key_images — dict of spent key images of mempool transactions. Only included when memory_pool is set to true. Each key is the key image (in hex, for json requests) and each value is a list of transaction hashes that spend that key image (typically just one, but in the case of conflicting transactions there can be multiple).

get_version

Get current RPC protocol version.

Parameters

This endpoint takes no inputs. (An optional empty dict/object may be provided, but is not required.)

Returns

• status — General RPC status string. "OK" means everything looks good.
• version — RPC current version.

hard_fork_info

Parameters

• version — If specified, this is the hard fork (i.e. major block) version for the fork. Only one of version and height may be given; returns the current hard fork info if neither is given.
• height — Request hard fork info by querying a particular height. Only one of version and height may be given.

Returns

• status — General RPC status string. "OK" means everything looks good.
• version — The major block version for the fork.
• enabled — Indicates whether the hard fork is enforced on the blockchain (that is, whether the blockchain height is at or above the requested hardfork).
• earliest_height — Block height at which the hard fork will become enabled.
• last_height — The last block height at which this hard fork will be active; will be omitted if this oxend is not aware of any following hard fork.

is_key_image_spent

Queries whether outputs have been spent using the key image associated with the output.

Parameters

• key_images — list of key images to check. For json requests these must be hex or base64-encoded; for bt-requests they can be hex/base64 or raw bytes.

Returns

• status — General RPC status string. "OK" means everything looks good.
• spent_status — array of status codes returned in the same order as the key_images input. Each value is one of:
• 0 — the key image is unspent
• 1 — the key image is spent in a mined block
• 2 — the key image is spent in a transaction currently in the mempool
• 2 — the key image is spent in a transaction currently in the mempool

ons_owners_to_names

Get all the name mappings for the queried owner. The owner can be either a ed25519 public key or Monero style public key; by default purchases are owned by the spend public key of the purchasing wallet.

Parameters

• entries — List of owner's public keys to find all Oxen Name Service entries for.
• include_expired — Optional: if provided and true, include entries in the results even if they are expired

Returns

• status — Generic RPC error code. "OK" is the success value.
• entries — List of ONS names. Each element is structured as follows:
• request_index — (Deprecated) The index in request's entries array that was resolved via Loki Name Service.
• type — The category the Loki Name Service entry belongs to; currently 0 for Session, 1 for Wallet and 2 for Lokinet.
• name_hash — The hash of the name that the owner purchased via Loki Name Service in base64
• owner — The backup public key specified by the owner that purchased the Loki Name Service entry.
• backup_owner — The backup public key specified by the owner that purchased the Loki Name Service entry. Omitted if no backup owner.
• encrypted_value — The encrypted value that the name maps to, in hex. This value is encrypted using the name (not the hash) as the secret.
• update_height — The last height that this Loki Name Service entry was updated on the Blockchain.
• expiration_height — For records that expire, this will be set to the expiration block height.
• txid — The txid of the mapping's most recent update or purchase.

ons_resolve

Performs a simple ONS lookup of a BLAKE2b-hashed name. This RPC method is meant for simple, single-value resolutions that do not care about registration details, etc.; if you need more information use ONS_NAMES_TO_OWNERS instead.

Parameters

• type — The ONS type (mandatory); currently support values are: 0 for Session, 1 for wallet, and 2 for Lokinet.
• name_hash — The 32-byte BLAKE2b hash of the name to look up, encoded as 64 hex digits or 44/43 base64 characters (with/without padding). For bt-encoded requests this can also be the raw 32 bytes.

Returns

• encrypted_value — The encrypted ONS value, in hex. Will be omitted from the response if the given name_hash is not registered.
• nonce — The nonce value used for encryption, in hex. Will be omitted if the given name is not registered.

Technical details: the returned value is encrypted using the name itself so that neither this oxend responding to the RPC request nor any other blockchain observers can (easily) obtain the name of registered addresses or the registration details. Thus, from a client's point of view, resolving an ONS record involves:

1. Lower-case the name.
2. Calculate the name hash as a null-key, 32-byte BLAKE2b hash of the lower-case name.
3. Obtain the encrypted value and the nonce from this RPC call (or ONS_NAMES_TO_OWNERS); when using json encode the name hash using either hex or base64.
4. Calculate the decryption key as a 32-byte BLAKE2b keyed hash of the name using the (unkeyed) name hash calculated above (in step 2) as the hash key.
5. Decrypt (and verify) using XChaCha20-Poly1305 (for example libsodium's crypto_aead_xchacha20poly1305_ietf_decrypt) using the above decryption key and using the first 24 bytes of the name hash as the public nonce.

Examples

Input

To look up the lokinet address for blocks.loki, we first need to get the name hash. Using Python, for example:

>>> import hashlib
>>> import base64
>>> name_hash = hashlib.blake2b(b'blocks.loki', digest_size=32).digest()
>>> base64.b64encode(name_hash)
b'IeynFEjyxigd0Lcmo5FWYaGp/uVXsa5grK8Jml0ai3o='

Which then allows the RPC lookup:

{ "type": 2, "name_hash": "IeynFEjyxigd0Lcmo5FWYaGp/uVXsa5grK8Jml0ai3o=" }

Output

{
  "encrypted_value": "b52c088ae51171a9e2e44cc98c10006547e2981d4cbe196525c948fa2fa48a11e8712eccd0ba20e4b93fb3989361df8a",
  "nonce": "6e3e80c7927108612475a0eeddf472af6177c9776d6943ed"
}

To decrypt, again using Python for an example:

>>> import hashlib
>>> import base64
>>> import nacl.bindings
>>> import oxenc
>>> data = bytes.fromhex("b52c088ae51171a9e2e44cc98c10006547e2981d4cbe196525c948fa2fa48a11e8712eccd0ba20e4b93fb3989361df8a")
>>> nonce = bytes.fromhex("6e3e80c7927108612475a0eeddf472af6177c9776d6943ed")
>>> name_hash = hashlib.blake2b(b'blocks.loki', digest_size=32).digest()
>>> key = hashlib.blake2b(b'blocks.loki', key=name_hash, digest_size=32).digest()
>>> val = nacl.bindings.crypto_aead_xchacha20poly1305_ietf_decrypt(ciphertext=data, nonce=nonce, aad=b'', key=key)
>>> oxenc.to_base32z(val) + ".loki"
'kcpyawm9se7trdbzncimdi5t7st4p5mh9i1mg7gkpuubi4k4ku1y.loki'

which is the full lokinet address of the blocks.loki.

Input

For a Session lookup you follow exactly the same steps as the above example, but using the session ID instead of blocks.loki. For example for the Session ONS jagerman you would get the name_hash and then request:

{ "type": 0, "name_hash": "yB7mbm2q1MaczqNZCYguH+71z5jooEMeXA0sncfni+g=" }

Output

{
  "encrypted_value": "d9bca6752665f2254ec7522f98aa5f2dfb13c9fa1ad1e39cd3d7a89a0df04719e348da537bc310a53e3b59ca24639b9b42",
  "nonce": "73e8243f3fadd471be36c6df3d62f863f9bb3a9d1cc696c0"
}

Decryption here is exactly the same as the above example except for the last step:

>>> import hashlib
>>> import base64
>>> import nacl.bindings
>>> data = bytes.fromhex("d9bca6752665f2254ec7522f98aa5f2dfb13c9fa1ad1e39cd3d7a89a0df04719e348da537bc310a53e3b59ca24639b9b42")
>>> nonce = bytes.fromhex("73e8243f3fadd471be36c6df3d62f863f9bb3a9d1cc696c0")
>>> name_hash = hashlib.blake2b(b'jagerman', digest_size=32).digest()
>>> key = hashlib.blake2b(b'jagerman', key=name_hash, digest_size=32).digest()
>>> val = nacl.bindings.crypto_aead_xchacha20poly1305_ietf_decrypt(ciphertext=data, nonce=nonce, aad=b'', key=key)
>>> '05' + val.hex()
'0505fb466d312e1666ad1c84c4ee55b7e034151c0e366a313d95d11436a5f36e1e75'

which is jagerman's full Session ID.

submit_transaction

Submit a transaction to be broadcast to the network.

Parameters

• tx — the full transaction data itself. Can be hex- or base64-encoded for json requests; can also be those or raw bytes for bt-encoded requests. For backwards compatibility, hex-encoded data can also be passed in a json request via the parameter tx_as_hex but that is deprecated and will eventually be removed.
• blink — Should be set to true if this transaction is a blink transaction that should be submitted to a blink quorum rather than distributed through the mempool.

Returns

• status — General RPC status string. "OK" means everything looks good.
• reason — String containing additional information on why a transaction failed.
• blink_status — Set to the result of submitting this transaction to the Blink quorum. 1 means the quorum rejected the transaction; 2 means the quorum accepted it; 3 means there was a timeout connecting to or waiting for a response from the blink quorum. Note that a timeout response does not necessarily mean the transaction has not made it to the network.
• not_relayed — will be set to true if some problem with the transactions prevents it from being relayed to the network, omitted otherwise.
• reason_codes — If the transaction was rejected this will be set to a set of reason string codes indicating why the transaction failed:
• "failed" — general "bad transaction" code
• "altchain" — the transaction is spending outputs that exist on an altchain.
• "mixin" — the transaction has the wrong number of decoys
• "double_spend" — the transaction is spending outputs that are already spent
• "invalid_input" — one or more inputs in the transaction are invalid
• "invalid_output" — out or more outputs in the transaction are invalid
• "too_few_outputs" — the transaction does not create enough outputs (at least two are required, currently).
• "too_big" — the transaction is too large
• "overspend" — the transaction spends (via outputs + fees) more than the inputs
• "fee_too_low" — the transaction fee is insufficient
• "invalid_version" — the transaction version is invalid (the wallet likely needs an update).
• "invalid_type" — the transaction type is invalid
• "snode_locked" — one or more outputs are currently staked to a registred service node and thus are not currently spendable on the blockchain.
• "blacklisted" — the outputs are currently blacklisted (from being in the 30-day penalty period following a service node deregistration).
• "blink" — the blink transaction failed (see blink_status)

banned

Determine whether a given IP address is banned

This endpoint requires admin RPC access; it is not available on public RPC servers.

Parameters

• address — The IP address to check.

Returns

• status — General RPC status string. "OK" means everything looks good.
• banned — True if the given address is banned, false otherwise.
• seconds — The number of seconds remaining in the ban.

flush_cache

Clear TXs from the daemon cache, currently only the cache storing TX hashes that were previously verified bad by the daemon.

This endpoint requires admin RPC access; it is not available on public RPC servers.

Parameters

• bad_txs — Clear the cache storing TXs that failed verification.
• bad_blocks — Clear the cache storing blocks that failed verfication.

Returns

• status — Generic RPC error code. "OK" is the success value.

flush_txpool

Flush tx ids from transaction pool..

This endpoint requires admin RPC access; it is not available on public RPC servers.

Parameters

• txids — Optional, list of transactions IDs to flosh from pool (all tx ids flushed if empty)

Returns

• status — General RPC status string. "OK" means everything looks good.

get_alternative_chains

Display alternative chains seen by the node.

This endpoint requires admin RPC access; it is not available on public RPC servers.

Parameters

This endpoint takes no inputs. (An optional empty dict/object may be provided, but is not required.)

Returns

• status — General RPC status string. "OK" means everything looks good.
• chains — Array of Chains. Each element is contains the following keys:
• block_hash — The block hash of the first diverging block of this alternative chain.
• height — The block height of the first diverging block of this alternative chain.
• length — The length in blocks of this alternative chain, after divergence.
• difficulty — The cumulative difficulty of all blocks in the alternative chain.
• block_hashes — List containing hex block hashes
• main_chain_parent_block

get_bans

Get list of banned IPs.

This endpoint requires admin RPC access; it is not available on public RPC servers.

Parameters

This endpoint takes no inputs. (An optional empty dict/object may be provided, but is not required.)

Returns

• status — General RPC status string. "OK" means everything looks good.
• bans — List of banned nodes. Each element is a dict containing:
• host — Banned host (IP in A.B.C.D form).
• seconds — Unix timestamp when the ban expires

get_coinbase_tx_sum

Get the coinbase amount and the fees amount for n last blocks starting at particular height.

This endpoint requires admin RPC access; it is not available on public RPC servers.

Parameters

• height — Block height from which getting the amounts.
• count — Number of blocks to include in the sum.

Returns

• status — General RPC status string. "OK" means everything looks good.
• emission_amount — Amount of coinbase reward in atomic units.
• fee_amount — Amount of fees in atomic units.
• burn_amount — Amount of burnt oxen.

get_connections

Retrieve information about incoming and outgoing P2P connections to your node.

This endpoint requires admin RPC access; it is not available on public RPC servers.

Parameters

This endpoint takes no inputs. (An optional empty dict/object may be provided, but is not required.)

Returns

• status — General RPC status string. "OK" means everything looks good.
• connections — List of all connections and their info; each element is a dict containing:
• incoming — bool of whether this connection was established by the remote to us (true) or by us to the remove (false).
• ip — address of the remote peer
• port — the remote port of the peer connection
• address_type — 1/2/3/4 for ipv4/ipv6/i2p/tor, respectively.
• peer_id — a string that uniquely identifies a peer node
• recv_count — number of bytes of data received from this peer
• recv_idle_ms — number of milliseconds since we last received data from this peer
• send_count — number of bytes of data send to this peer
• send_idle_ms — number of milliseconds since we last sent data to this peer
• state — returns the current state of the connection with this peer as a string, one of:
  • "before_handshake" — the connection is still being established/negotiated
  • "synchronizing" — we are synchronizing the blockchain with this peer
  • "standby" — the peer is available for synchronizing but we are not currently using it
  • "normal" — this is a regular, synchronized peer
• live_ms — number of milliseconds since this connection was initiated
• avg_download — the average download speed from this peer in bytes per second
• current_download — the current (i.e. average over a very recent period) download speed from this peer in bytes per second.
• avg_upload — the average upload speed to this peer in bytes per second
• current_upload — the current upload speed to this peer in bytes per second
• connection_id — a unique random string identifying this connection
• height — the height of the peer
• host — the hostname for this peer; only included if not the same as ip
• localhost — set to true if the peer is a localhost connection; omitted otherwise.
• local_ip — set to true if the peer is a non-public, local network connection; omitted otherwise.

get_limit

Get daemon p2p bandwidth limits.

This endpoint requires admin RPC access; it is not available on public RPC servers.

Parameters

This endpoint takes no inputs. (An optional empty dict/object may be provided, but is not required.)

Returns

• status — General RPC status string. "OK" means everything looks good.
• limit_up — Upload limit in kiB/s
• limit_down — Download limit in kiB/s

get_net_stats

Retrieve general information about the state of the network.

This endpoint requires admin RPC access; it is not available on public RPC servers.

Parameters

This endpoint takes no inputs. (An optional empty dict/object may be provided, but is not required.)

Returns

• status — General RPC status string. "OK" means everything looks good.
• start_time — something.
• total_packets_in — something.
• total_bytes_in — something.
• total_packets_out — something.
• total_bytes_out — something.

get_peer_list

Get the list of current network peers known to this node.

This endpoint requires admin RPC access; it is not available on public RPC servers.

Parameters

This endpoint takes no inputs. (An optional empty dict/object may be provided, but is not required.)

Returns

• status — General RPC status string. "OK" means everything looks good.
• white_list — list of "whitelist" peers (see below), that is, peers that were recorded reachable the last time this node connected to them. Peers that are unreachable or not synchronized with the network are moved to the graylist.
• gray_list — list of peers (see below) that this node knows of but has not (recently) tried to connect to.

Each peer list is an array of dicts containing the following fields: - id — a unique integer locally identifying the peer - host — the peer's IP address (as a string) - port — the port on which the peer is reachable - last_seen — unix timestamp when this node last connected to the peer. Will be omitted if never connected (e.g. for a peer we received from another node but haven't yet tried).

get_service_keys

Get the service public keys of the queried daemon, encoded in hex. All three keys are used when running as a service node; when running as a regular node only the x25519 key is regularly used for some RPC and and node-to-SN communication requests.

This endpoint requires admin RPC access; it is not available on public RPC servers.

Parameters

This endpoint takes no inputs. (An optional empty dict/object may be provided, but is not required.)

Returns

• status — General RPC status string. "OK" means everything looks good.
• service_node_pubkey — The queried daemon's service node public key. Will be empty if not running as a service node.
• service_node_ed25519_pubkey — The daemon's ed25519 auxiliary public key.
• service_node_x25519_pubkey — The daemon's x25519 auxiliary public key.

get_service_node_registration_cmd_raw

Returns the command that should be run to prepare a service node, includes correct parameters and service node ids formatted ready for cut and paste into daemon console.

This endpoint requires admin RPC access; it is not available on public RPC servers.

Parameters

• check — Instead of running check if the blockchain has already been pruned.
• args — (Developer) The list of arguments used in raw registration, i.e. portions
• make_friendly — Provide information about how to use the command in the result.
• staking_requirement — The staking requirement to become a Service Node the registration command will be generated upon

Returns

• status — General RPC status string. "OK" means everything looks good.
• registration_cmd — The command to execute in the wallet CLI to register the queried daemon as a Service Node.

get_service_node_status

Retrieves information on the current daemon's Service Node state. The returned information is the same as what would be returned by "get_service_nodes" when passed this service node's public key.

This endpoint requires admin RPC access; it is not available on public RPC servers.

Parameters

This endpoint takes no inputs. (An optional empty dict/object may be provided, but is not required.)

Returns

• service_node_state — if this is a registered service node then all available fields for this service node. See get_service_nodes for the list of fields. Note that some fields (such as remote testing results) will not be available (through this call or get_service_nodes) because a service node is incapable of testing itself for remote connectivity. If this daemon is running in service node mode but not registered then only SN pubkey, ip, and port fields are returned.
• height — current top block height at the time of the request (note that this is generally one less than the "blockchain height").
• block_hash — current top block hash at the time of the request
• status — generic RPC error code; "OK" means the request was successful.

get_service_privkeys

Get the service private keys of the queried daemon, encoded in hex. Do not ever share these keys: they would allow someone to impersonate your service node. All three keys are used when running as a service node; when running as a regular node only the x25519 key is regularly used for some RPC and and node-to-SN communication requests.

This endpoint requires admin RPC access; it is not available on public RPC servers.

Parameters

This endpoint takes no inputs. (An optional empty dict/object may be provided, but is not required.)

Returns

• status — General RPC status string. "OK" means everything looks good.
• service_node_privkey — The queried daemon's service node private key. Will be empty if not running as a service node.
• service_node_ed25519_privkey — The daemon's ed25519 private key (note that this is in sodium's format, which consists of the private and public keys concatenated together)
• service_node_x25519_privkey — The daemon's x25519 private key.

in_peers

Limit number of Incoming peers.

This endpoint requires admin RPC access; it is not available on public RPC servers.

Parameters

• set — If true, set the number of incoming peers, otherwise the response returns the current limit of incoming peers. (Defaults to true)
• in_peers — Max number of incoming peers

Returns

• status — General RPC status string. "OK" means everything looks good.
• in_peers — The current limit set for incoming peers.

lokinet_ping

Endpoint to receive an uptime ping from the connected lokinet server. This is used to record whether lokinet is ready before the service node starts sending uptime proofs. This is usually called internally from Lokinet and this endpoint is mostly available for testing purposes.

This endpoint requires admin RPC access; it is not available on public RPC servers.

Parameters

• version — Lokinet version

Returns

• status — generic RPC error code; "OK" means the request was successful.

mining_status

Get the mining status of the daemon.

This endpoint requires admin RPC access; it is not available on public RPC servers.

Parameters

This endpoint takes no inputs. (An optional empty dict/object may be provided, but is not required.)

Returns

• status — General RPC status string. "OK" means everything looks good.
• active — States if mining is enabled (true) or disabled (false).
• speed — Mining power in hashes per seconds.
• threads_count — Number of running mining threads.
• address — Account address daemon is mining to. Empty if not mining.
• pow_algorithm — Current hashing algorithm name
• block_target — The expected time to solve per block, i.e. TARGET_BLOCK_TIME
• block_reward — Block reward for the current block being mined.
• difficulty — The difficulty for the current block being mined.

out_peers

Limit number of Outgoing peers.

This endpoint requires admin RPC access; it is not available on public RPC servers.

Parameters

• set — If true, set the number of outgoing peers, otherwise the response returns the current limit of outgoing peers. (Defaults to true)
• out_peers — Max number of outgoing peers

Returns

• status — General RPC status string. "OK" means everything looks good.
• out_peers — The current limit set for outgoing peers.

pop_blocks

Pop blocks off the main chain

This endpoint requires admin RPC access; it is not available on public RPC servers.

Parameters

• nblocks — Number of blocks in that span.

Returns

• status — General RPC status string. "OK" means everything looks good.
• height — Height of the blockchain after blocks have been popped.

prune_blockchain

Pruning is the process of removing non-critical blockchain information from local storage. Full nodes keep an entire copy of everything that is stored on the blockchain, including data that is not very useful anymore. Pruned nodes remove much of this less relevant information to have a lighter footprint. Of course, running a full node is always better; however, pruned nodes have most of the important information and can still support the network.

This endpoint requires admin RPC access; it is not available on public RPC servers.

Parameters

• check — Instead of running check if the blockchain has already been pruned.

Returns

• status — General RPC status string. "OK" means everything looks good.
• pruned — Bool returning whether the blockchain was pruned or not.
• pruning_seed — The seed that determined how the blockchain was to be pruned.

relay_tx

Relay a list of transaction IDs.

This endpoint requires admin RPC access; it is not available on public RPC servers.

Parameters

• txids — List of transactions IDs to relay from pool.

Returns

• status — General RPC status string. "OK" means everything looks good.

save_bc

Save the blockchain. The blockchain does not need saving and is always saved when modified, however it does a sync to flush the filesystem cache onto the disk for safety purposes, against Operating System or Hardware crashes.

This endpoint requires admin RPC access; it is not available on public RPC servers.

Parameters

This endpoint takes no inputs. (An optional empty dict/object may be provided, but is not required.)

Returns

• status — General RPC status string. "OK" means everything looks good.

set_bans

Ban another node by IP.

This endpoint requires admin RPC access; it is not available on public RPC servers.

Parameters

• host — Banned host (IP in A.B.C.D form).
• ip — Banned IP address, in Int format.
• seconds — Local Unix time that IP is banned until, or Number of seconds to ban node
• ban — Set true to ban.

Returns

• status — General RPC status string. "OK" means everything looks good.

set_limit

Set daemon p2p bandwidth limits.

This endpoint requires admin RPC access; it is not available on public RPC servers.

Parameters

• limit_down — Download limit in kBytes per second. -1 means reset to default; 0 (or omitted) means don't change the current limit
• limit_up — Upload limit in kBytes per second. -1 means reset to default; 0 (or omitted) means don't change the current limit

Returns

• status — General RPC status string. "OK" means everything looks good.
• limit_up — The new (or existing, if unchanged) upload limit in kiB/s
• limit_down — The new (or existing, if unchanged) download limit in kiB/s

set_log_categories

Set the daemon log categories for debugging purposes.

Categories are represented as a comma separated list of <Category>:<level>, where <Category> is is one of the various internal debugging categories defined in the oxen source code, or * to refer to all logging categories.

Level is one of the following: FATAL, ERROR, WARNING, INFO, DEBUG, TRACE.

You can append to the current the log level for updating just one or more categories while leaving other log levels unchanged by specifying one or more ":" pairs preceded by a "+", for example "+difficulty:DEBUG,net:WARNING".

This endpoint requires admin RPC access; it is not available on public RPC servers.

Parameters

• categories — Optional, daemon log categores to enable

Returns

• status — General RPC status string. "OK" means everything looks good.
• categories — Daemon log enabled categories

set_log_level

Set the daemon log level. By default, log level is set to 0. For more fine-tuned logging control set the set_log_categories command instead.

This endpoint requires admin RPC access; it is not available on public RPC servers.

Parameters

• level — Daemon log level to set from 0 (less verbose) to 4 (most verbose)

Returns

• status — General RPC status string. "OK" means everything looks good.

start_mining

Start mining on the daemon

This endpoint requires admin RPC access; it is not available on public RPC servers.

Parameters

• miner_address — Account address to mine to.
• threads_count — Number of mining threads to run. Defaults to 1 thread if omitted or 0.
• num_blocks — Mine until the blockchain has this many new blocks, then stop (no limit if 0, the default).
• slow_mining — Do slow mining (i.e. don't allocate RandomX cache); primarily intended for testing.

Returns

status — General RPC status string. "OK" means everything looks good.

stop_daemon

Stop the daemon.

This endpoint requires admin RPC access; it is not available on public RPC servers.

Parameters

This endpoint takes no inputs. (An optional empty dict/object may be provided, but is not required.)

Returns

• status — General RPC status string. "OK" means everything looks good.

stop_mining

Stop mining on the daemon.

This endpoint requires admin RPC access; it is not available on public RPC servers.

Parameters

This endpoint takes no inputs. (An optional empty dict/object may be provided, but is not required.)

Returns

status — General RPC status string. "OK" means everything looks good.

storage_server_ping

Endpoint to receive an uptime ping from the connected storage server. This is used to record whether the storage server is ready before the service node starts sending uptime proofs. This is usually called internally from the storage server and this endpoint is mostly available for testing purposes.

This endpoint requires admin RPC access; it is not available on public RPC servers.

Parameters

• version — Storage server version
• https_port — Storage server https port to include in uptime proofs.
• omq_port — Storage server oxenmq port to include in uptime proofs.

Returns

• status — generic RPC error code; "OK" means the request was successful.

sync_info

Get node synchronisation information. This returns information on the node's syncing "spans" which are block segments being downloaded from peers while syncing; spans are generally downloaded out of order from multiple peers, and so these spans reflect in-progress downloaded blocks that have not yet been added to the block chain: typically because the spans is not yet complete, or because the span is for future blocks that are dependent on intermediate blocks (likely in another span) being added to the chain first.

This endpoint requires admin RPC access; it is not available on public RPC servers.

Parameters

This endpoint takes no inputs. (An optional empty dict/object may be provided, but is not required.)

Returns

• status — General RPC status string. "OK" means everything looks good.
• height — Current block height
• target_height — If the node is currently syncing then this is the target height the node wants to reach. If fully synced then this field is omitted.
• peers — dict of connection information about peers. The key is the peer connection_id; the value is identical to the values of the connections field of the get_connections endpoint.
• span — array of span information of current in progress synchronization. Each element contains:
• start_block_height — Block height of the first block in the span
• nblocks — the number of blocks in the span
• connection_id — the connection_id of the connection from which we are downloading the span
• rate — the most recent connection speed measurement
• speed — the average connection speed over recent downloaded blocks
• size — total number of block and transaction data stored in the span
• overview — a string containing a one-line ascii-art depiction of the current sync status