Introduction

Retrieves the current number of blocks in the main chain — the longest chain known to this node.

Inputs:
None.

Outputs:
count— unsigned integer; total number of blocks in the blockchain, including genesis block at height zero.

Example

{
  "id": "0",
  "jsonrpc": "2.0",
  "result": {
    "count": 1535,
    "status": "OK"
  }
}

Obtains block hash by given block height.

Inputs:
Array of 1 unsigned integer; block height.

Outputs:
string; standard public address of the wallet.

Example

Get hash of the genesis block (height 0):

{
  "id": "0",
  "jsonrpc": "2.0",
  "result": "f1e0d823ee1a23a5dc6167f91e54c16a4b71cfd84d0d62753d77b93ff9af5051"
}

Creates a template for the next block.

Inputs:
wallet_address— string; miner address to receive newly generated coins.
extra_text— string (optional); additional text included into miner transaction. Cannot exceed 255 bytes.
pos_block— boolean (optional); Type of block template to be created: PoS (true) or PoW (false). Default: false.
stakeholder_address— string (optional); specify miner address to which the stake coins used in PoS block generation will be returned.
pos_amount— unsigned int (optional), amount of an output used as a stake.
pos_index— unsigned int (optional); global index of an output used as a stake.

Outputs:
blocktemplate_blob— string; hex-encoded serialized block template.
difficulty— unsigned int, difficulty for the block template.
height— unsigned int, height corresponding to the block template.

Examples

Simplest PoW

{
  "id": "0",
  "jsonrpc": "2.0",
  "result": {
    "blocktemplate_blob": "",
    "difficulty": 310675,
    "height": 211620,
    "status": "OK"
  }
}

PoS

{
  "id": "0",
  "jsonrpc": "2.0",
  "result": {
    "blocktemplate_blob": "",
    "difficulty": 5435821979022532,
    "height": 211639,
    "status": "OK"
  }
}

Submits the given block, i.e. adds it to the local blockchain and broadcasts it to the network.

Inputs:
array of a single string; block blob.

Outputs:
None.

Examples

Block is not accepted by the core(e.g. proof of work is not enough)

{
  "error": {
    "code": -7,
    "message": "Block not accepted"
  },
  "id": "0",
  "jsonrpc": "2.0"
}

Block was added as alternative

{
  "error": {
    "code": -13,
    "message": "Block added as alternative"
  },
  "id": "0",
  "jsonrpc": "2.0"
}

Block is accepted by the core

{
  "id": "0",
  "jsonrpc": "2.0",
  "result": {
    "status": "OK"
  }
}

Returns the header of the last block in the blockchain.

Inputs:
None.

Outputs:
block_header — object; a block header object for the last block.

block header object fields:

• depth— unsigned int; distance in blocks from the blockchain top. Always zero for this call.
• difficulty— unsigned int; block difficulty.
• hash— string; block identifier.
• prev_hash— string; identifier of the previous block.
• height— unsigned int; block height.
• major_version— unsigned int; major version of a block.
• minor_version— unsigned int; minor version of a block.
• nonce— unsigned int; block nonce.
• orphan_status— boolean; is this block orphan. Always false for this call.
• reward— unsigned int; how much money this block has generated.
• timestamp— unsigned int; block timestamp.

Example

{
  "id": "0",
  "jsonrpc": "2.0",
  "result": {
    "block_header": {
      "depth": 0,
      "difficulty": 310347,
      "hash": "6790b2288665efaf7879e971bf14c5a95b2f2c4a8386f9b8f416b7b94ac3b44e",
      "height": 212966,
      "major_version": 1,
      "minor_version": 0,
      "nonce": 3231486224,
      "orphan_status": false,
      "prev_hash": "9c0b37eafdefb27685722269f1eab795d1a7c8f3a9704db471c2614553a7342f",
      "reward": 389000000,
      "timestamp": 1534627476
    },
    "status": "OK"
  }
}

Returns a block header by the given hash identifier.

Inputs:
hash— string; hash identifier of a block.

Outputs:
block_header— object; a block header object for the requested block. See getlastblockheader for detailed fields description.

Examples

Requesting a non-existing block

{
  "error": {
    "code": -5,
    "message": "Internal error: can't get block by hash. Hash = 0000000000000000000000000000000000000000000000000000000000000000."
  },
  "id": "0",
  "jsonrpc": "2.0"
}

Requesting an existing block

{
  "id": "0",
  "jsonrpc": "2.0",
  "result": {
    "block_header": {
      "depth": 122,
      "difficulty": 310347,
      "hash": "6790b2288665efaf7879e971bf14c5a95b2f2c4a8386f9b8f416b7b94ac3b44e",
      "height": 212966,
      "major_version": 1,
      "minor_version": 0,
      "nonce": 3231486224,
      "orphan_status": false,
      "prev_hash": "9c0b37eafdefb27685722269f1eab795d1a7c8f3a9704db471c2614553a7342f",
      "reward": 389000000,
      "timestamp": 1534627476
    },
    "status": "OK"
  }
}

Returns a block header by the given block height.

Inputs:
height —unsigned int; height of a block.

Outputs:
block_header— object; a block header object for the requested block. See getlastblockheader for detailed fields description.

Examples

Requesting a non-existing block

{
  "error": {
    "code": -2,
    "message": "To big height: 999999, current blockchain size = 2094"
  },
  "id": "0",
  "jsonrpc": "2.0"
}

Requesting an existing block

{
  "id": "0",
  "jsonrpc": "2.0",
  "result": {
    "block_header": {
      "depth": 213093,
      "difficulty": 1,
      "hash": "f1e0d823ee1a23a5dc6167f91e54c16a4b71cfd84d0d62753d77b93ff9af5051",
      "height": 0,
      "major_version": 1,
      "minor_version": 0,
      "nonce": 101010190,
      "orphan_status": false,
      "prev_hash": "0000000000000000000000000000000000000000000000000000000000000000",
      "reward": 10300000000000000,
      "timestamp": 0
    },
    "status": "OK"
  }

Returns alias details by alias name.

Inputs:
alias— string; alias name (without "@").

Outputs:
alias_details— object; an alias details block object for the requested alias.

Alias details object fields:

• address— string; public address associated with requested alias.
• comment— string; an arbitrary comment set by the owner. Can be empty.
• tracking_key— string; private view key for public address. Can be empty.

Examples

Requesting details for non-existing alias

{
  "id": "0",
  "jsonrpc": "2.0",
  "result": {
    "alias_details": {
      "address": "",
      "comment": "",
      "tracking_key": ""
    },
    "status": "NOT FOUND"
  }
}

Correct request

{
  "id": "0",
  "jsonrpc": "2.0",
  "result": {
    "alias_details": {
      "address": "Hc96ZyhKNA3iES8maQKLuz5rUBQ7cjJWq97qbJ8d2Hx7hZTDsQBuifAMFvuT5bUL8VeYgtdsf8shDKTUD8Yd7JXQCaW9BBm",
      "comment": "my miner test alias",
      "tracking_key": ""
    },
    "status": "OK"
  }
}

Returns alias name by address.

Inputs:
string; a public address associated with an alias.

Outputs:
alias— string; alias name for an address.

Example

Requesting a non-existing alias

{
  "id": "0",
  "jsonrpc": "2.0",
  "result": {
    "alias": "",
    "status": "NOT FOUND"
  }
}

Correct request

{
  "id": "0",
  "jsonrpc": "2.0",
  "result": {
    "alias": "minertest",
    "status": "OK"
  }
}

Clears the transaction pool.

Inputs:
None.

Outputs:
None.

Examples

{
  "id": "0",
  "jsonrpc": "2.0",
  "result": {
    "status": "OK"
  }
}

Correct request

{
  "id": "0",
  "jsonrpc": "2.0",
  "result": {
    "alias": "minertest",
    "status": "OK"
  }
}

Retrieves blocks not present on requesting side. Used for wallet synchronization.

Data structure:

template
struct COMMAND_RPC_GET_BLOCKS_FAST_T
{
  struct request
  {
    std::list block_ids;
  };

  struct response
  {
    std::list blocks;
    uint64_t    start_height;
    uint64_t    current_height;
    std::string status;
  };
};

typedef COMMAND_RPC_GET_BLOCKS_FAST_T COMMAND_RPC_GET_BLOCKS_FAST;

Inputs:
block_ids — list of block id’s representing a snapshot of the local blockchain. The first 10 block id’s appear in sequential order, the next IDs in pow(2,n) offsets (2, 4, 8, 16, 32, 64, etc.), while the last are always the genesis block id’s. See also tools::wallet2::get_short_chain_history().

Outputs:
blocks — list of block_complete_entry objects containing full information about each block.
start_height — height of the first block in blocks.
current_height — current total size of the blockchain.

Retrieves global output indexes by specified transaction ID.

Data structure:

struct COMMAND_RPC_GET_TX_GLOBAL_OUTPUTS_INDEXES
{
  struct request
  {
    crypto::hash txid;
  };

  struct response
  {
    std::vector o_indexes;
    std::string status;
  };
};

Inputs:
tx_id — transaction hash identifier.

Outputs:
o_indexes — vector of global indexes for each tx output.

Retrieves random outputs from the entire blockchain for specified amounts. Random outputs can be mixed with normal user's unspent outputs in a transaction to improve untraceability.

Data structure:

struct COMMAND_RPC_GET_RANDOM_OUTPUTS_FOR_AMOUNTS
{
  struct request
  {
    std::list amounts;
    uint64_t            outs_count;
    bool                use_forced_mix_outs;
  };

  struct out_entry
  {
    uint64_t global_amount_index;
    crypto::public_key out_key;
  };

  struct outs_for_amount
  {
    uint64_t amount;
    std::list outs;
  };

  struct response
  {
    std::vector outs;
    std::string status;
  };
};

Inputs:
amounts — list of denominations for which random mix-ins are required.
outs_count — number of random outputs needed for each amount.

Outputs:
outs — vector of outs_for_amount objects.
outs_for_amount::amount — specific amount for which random outputs were found.
outs_for_amount::outs — list of out_entry objects.
out_entry::global_amount_index — output index in the global outputs list.
out_entry::out_key — output public key.

Retrieves transaction pool.

Data structure:

struct COMMAND_RPC_GET_TX_POOL
{
  struct request
  {};

  struct response
  {
    std::list txs;
    std::string status;
 };
};

Inputs:
None.

Outputs:
txs — list of serialized transactions from the pool.

Checks specified key images for their spent status.

Data structure:

struct COMMAND_RPC_CHECK_KEYIMAGES
{
  struct request
  {
    std::list images;
  };

  struct response
  {
    std::list images_stat;  //true - unspent, false - spent
    std::string status;
 };
};

Inputs:
images — list of key images to be checked for spending.

Outputs:
images_stat — list of integers where 0 means that corresponding key image is spent and 1 means it is not spent.