Node API Documentation - keplernetwork/kepler GitHub Wiki

Node API Documentation

Table of Contents

  1. Blocks Endpoint
    1. GET Blocks
  2. Headers Endpoint
    1. GET Headers
  3. Chain Endpoint
    1. GET Chain
    2. POST Chain Compact
    3. GET Chain Validate
    4. GET Chain Kernel by Commitment
    5. GET Chain Outputs by IDs
    6. GET Chain Outputs by Height
  4. Status Endpoint
    1. GET Status
  5. TxHashSet Endpoint
    1. GET TxHashSet Roots
    2. GET TxHashSet Last Outputs
    3. GET TxHashSet Last Range Proofs
    4. GET TxHashSet Last Kernels
    5. GET TxHashSet Outputs
    6. GET TxHashSet Merkle Proof
  6. Pool Endpoint
    1. GET Pool
    2. POST Pool Push
  7. Peers Endpoint
    1. POST Peers Ban
    2. POST Peers Unban
    3. GET Peers All
    4. GET Peers Connected
    5. GET Peers

Blocks Endpoint

GET Blocks

Returns data about a specific block given a hash, a height or an unspent commit.

Optionally, Merkle proofs can be excluded from the results by adding ?no_merkle_proof, rangeproofs can be included by adding ?include_proof or results can be returned as "compact blocks" by adding ?compact.

  • URL

    • /v1/blocks/hash
    • /v1/blocks/height
    • /v1/blocks/commit

  • Method:

    GET

  • URL Params

    Required: hash=[string] or height=[number] or commit=[string]

  • Data Params

    None

  • Success Response:

    • Code: 200

    • Content:

      Field Type Description
      header object The block header
      - hash string Hash of the current block
      - version number Version of the block
      - height number Height of this block since the genesis block (height 0)
      - previous string Hash of the block previous to this in the chain
      - prev_root string Root hash of the header MMR at the previous header
      - timestamp string RFC3339 timestamp at which the block was built
      - output_root string Merklish root of all the commitments in the TxHashSet
      - range_proof_root string Merklish root of all range proofs in the TxHashSet
      - kernel_root string Merklish root of all transaction kernels in the TxHashSet
      - nonce number Nonce increment used to mine this block
      - edge_bits number Size of the cuckoo graph (2_log of number of edges)
      - cuckoo_solution []number The Cuckoo solution for this block
      - total_difficulty number Total accumulated difficulty since genesis block
      - secondary_scaling number Variable difficulty scaling factor for secondary proof of work
      - total_kernel_offset string Total kernel offset since genesis block
      inputs []string Input transactions
      outputs []object Outputs transactions
      - output_type string The type of output Coinbase
      - commit string The homomorphic commitment representing the output's amount (as hex string)
      - spent bool Whether the output has been spent
      - proof string Rangeproof (as hex string)
      - proof_hash string Rangeproof hash (as hex string)
      - block_height number Block height at which the output is found
      - merkle_proof string Merkle proof
      kernels []object Transaction Kernels (a proof that a transaction sums to zero)
      - features object Options for a kernel's structure or use
      - bits number Representation of the features in bits
      - fee number Fee originally included in the transaction this proof is for
      - lock_height number The max lock_height of all inputs to this transaction
      - excess []number Remainder of the sum of all transaction commitments
      - excess_sig []number The signature proving the excess is a valid public key (signs the tx fee)

  • Error Response:

    • Code: 404 or 500
    • Content: failed to parse input: Not found.

  • Sample Call:

      $.ajax({
    url: "/v1/blocks/1",
    dataType: "json",
    type : "GET",
    success : function(r) {
      console.log(r);
    }
  });

Headers Endpoint

GET Headers

Returns data about a block headers given either a hash or height or an output commit.

  • URL

    • /v1/headers/hash
    • /v1/headers/height
    • /v1/headers/commit

  • Method:

    GET

  • URL Params

    Required: hash=[string] or height=[number] or commit=[string]

  • Data Params

    None

  • Success Response:

    • Code: 200

    • Content:

      Field Type Description
      header object The block header
      - hash string Hash of the current block
      - version number Version of the block
      - height number Height of this block since the genesis block (height 0)
      - previous string Hash of the block previous to this in the chain
      - prev_root string Root hash of the header MMR at the previous header
      - timestamp string RFC3339 timestamp at which the block was built
      - output_root string Merklish root of all the commitments in the TxHashSet
      - range_proof_root string Merklish root of all range proofs in the TxHashSet
      - kernel_root string Merklish root of all transaction kernels in the TxHashSet
      - nonce number Nonce increment used to mine this block
      - edge_bits number Size of the cuckoo graph (2_log of number of edges)
      - cuckoo_solution []number The Cuckoo solution for this block
      - total_difficulty number Total accumulated difficulty since genesis block
      - total_kernel_offset string Total kernel offset since genesis block

  • Error Response:

    • Code: 404 or 500
    • Content: failed to parse input: Not found.

  • Sample Call:

      $.ajax({
    url: "/v1/headers/1",
    dataType: "json",
    type : "GET",
    success : function(r) {
      console.log(r);
    }
  });

Chain Endpoint

GET Chain

Retrieves details about the state of the current fork tip.

  • URL

    /v1/chain

  • Method:

    GET

  • URL Params

    None

  • Data Params

    None

  • Success Response:

    • Code: 200

    • Content:

      Field Type Description
      height number Height of the tip (max height of the fork)
      last_block_pushed string Last block pushed to the fork
      prev_block_to_last string Block previous to last
      total_difficulty number Total difficulty accumulated on that fork since genesis block

  • Error Response:

    • Code: 404 or 500
    • Content: failed to parse input: Not found.

  • Sample Call:

      $.ajax({
    url: "/v1/chain",
    dataType: "json",
    type : "GET",
    success : function(r) {
      console.log(r);
    }
  });

POST Chain Compact

Trigger a compaction of the chain state to regain storage space.

  • URL

    /v1/chain/compact

  • Method:

    POST

  • URL Params

    None

  • Data Params

    None

  • Success Response:

    • Code: 200

  • Error Response:

    • Code: 500

  • Sample Call:

      $.ajax({
    url: "/v1/chain/compact",
    dataType: "json",
    type : "POST",
    success : function(r) {
      console.log(r);
    }
  });

GET Chain Validate

Trigger a validation of the chain state.

  • URL

    /v1/chain/validate

  • Method:

    GET

  • URL Params

    None

  • Data Params

    None

  • Success Response:

    • Code: 200

  • Error Response:

    • Code: 500

  • Sample Call:

      $.ajax({
    url: "/v1/chain/validate",
    dataType: "json",
    type : "GET",
    success : function(r) {
      console.log(r);
    }
  });

GET Chain Kernel By Commitment

Look up an on-chain kernel and the height of the block it is included in. By default min_height is 0.

  • URL

    • /v1/chain/kernels/xxx?min_height=yyy&max_height=zzz

  • Method:

    GET

  • URL Params

    Required: commitment=[string]

    Optional: min_height=[number] max_height=[number]

  • Data Params

    None

  • Success Response:

    • Code: 200

    • Content:

      Field Type Description
      tx_kernel object Transaction Kernel
      - features object The type of output Coinbase
      - features object The kernel features. Can either be Plain, Coinbase or HeightLocked.
      - excess string The kernel excess also called commitment
      - excess_sig string The excess signature
      height string THe height of the block this kernel is included in
      mmr_height string Position in the MMR

  • Error Response:

    • Code: 404 or 500
    • Content: []

  • Sample Call:

      $.ajax({
    url: "/v1/chain/kernels/0939fe3dc6a35350da91c6288138b7a257e0c0322eae30bda3938229d649e2e642?max_height=324300",
    dataType: "json",
    type : "GET",
    success : function(r) {
      console.log(r);
    }
  });

GET Chain Outputs By IDs

Retrieves details about specifics outputs. Supports retrieval of multiple outputs in a single request.

  • URL

    • /v1/chain/outputs/byids?id=x
    • /v1/chain/outputs/byids?id=x,y,z
    • /v1/chain/outputs/byids?id=x&id=y&id=z

  • Method:

    GET

  • URL Params

    Required: id=[string]

  • Data Params

    None

  • Success Response:

    • Code: 200

    • Content:

      Field Type Description
      outputs []object Outputs
      - output_type string The type of output Coinbase
      - commit string The homomorphic commitment representing the output's amount (as hex string)
      - spent bool Whether the output has been spent
      - proof string Rangeproof (as hex string)
      - proof_hash string Rangeproof hash (as hex string)
      - block_height number Block height at which the output is found
      - merkle_proof string Merkle proof

  • Error Response:

    • Code: 404 or 500
    • Content: []

  • Sample Call:

      $.ajax({
    url: "/v1/chain/outputs/byids?id=0803516094a30830ed9fedff1c63251b51703ddffbb73f944d9e33e8fa5d17444f",
    dataType: "json",
    type : "GET",
    success : function(r) {
      console.log(r);
    }
  });

GET Chain Outputs By Height

Retrieves details about specifics outputs. Supports retrieval of multiple outputs in a single request.

  • URL

    /v1/chain/outputs/byheight?start_height=x&end_height=y

  • Method:

    GET

  • URL Params

    Required: start_height=[number] end_height=[number]

  • Data Params

    None

  • Success Response:

    • Code: 200

    • Content:

      Field Type Description
      header object The block header
      - hash string Hash of the current block
      - height number Height of this block since the genesis block (height 0)
      - previous string Hash of the block previous to this in the chain
      outputs []object Outputs
      - output_type string The type of output Coinbase
      - commit string The homomorphic commitment representing the output's amount (as hex string)
      - spent bool Whether the output has been spent
      - proof string Rangeproof (as hex string)
      - proof_hash string Rangeproof hash (as hex string)
      - block_height number Block height at which the output is found
      - merkle_proof string Merkle proof

  • Error Response:

    • Code: 404 or 500
    • Content: []

  • Sample Call:

      $.ajax({
    url: "/v1/chain/outputs/byheight?start_height=101&end_height=200",
    dataType: "json",
    type : "GET",
    success : function(r) {
      console.log(r);
    }
  });

Status Endpoint

GET Status

Returns various information about the node and the network

  • URL

    /v1/status

  • Method:

    GET

  • URL Params

    None

  • Data Params

    None

  • Success Response:

    • Code: 200

    • Content:

      Field Type Description
      protocol_version number The node protocol version
      user_agent number The node user agent
      connections number The current number of connections
      tip object The state of the current fork tip
      height number Height of the tip (max height of the fork)
      last_block_pushed string Last block pushed to the fork
      prev_block_to_last string Block previous to last
      total_difficulty number Total difficulty accumulated on that fork since genesis block
      sync_status string The current sync status
      sync_info object Additional sync information. This field is optional.

  • Error Response:

    • Code: 404 or 500
    • Content: failed to parse input: Not found.

  • Sample Call:

      $.ajax({
    url: "/v1/stats",
    dataType: "json",
    type : "GET",
    success : function(r) {
      console.log(r);
    }
  });

TxHashSet Endpoint

GET TxHashSet Roots

Retrieve the roots of the TxHashSet

  • URL

    /v1/txhashset/roots

  • Method:

    GET

  • URL Params

    None

  • Data Params

    None

  • Success Response:

    • Code: 200

    • Content:

      Field Type Description
      output_root_hash string Output root hash
      range_proof_root_hash string Rangeproof root hash
      kernel_root_hash string Kernel set root hash

  • Error Response:

    • Code: 500

  • Sample Call:

      $.ajax({
    url: "/v1/txhashset/roots",
    dataType: "json",
    type : "GET",
    success : function(r) {
      console.log(r);
    }
  });

GET TxHashSet Last Outputs

Retrieves the last n outputs inserted into the tree.

  • URL

    • /v1/txhashset/lastoutputs (gets last 10)
    • /v1/txhashset/lastoutputs?n=x

  • Method:

    GET

  • URL Params

    Required: n=[number]

  • Data Params

    None

  • Success Response:

    • Code: 200
    • Content:

    Array of

    Field Type Description
    hash string hash of the outputs

  • Error Response:

    • Code: 500

  • Sample Call:

      $.ajax({
    url: "/v1/txhashset/lastoutputs?n=20",
    dataType: "json",
    type : "GET",
    success : function(r) {
      console.log(r);
    }
  });

GET TxHashSet Last Range Proofs

Retrieves the last n rangeproofs inserted in to the tree.

  • URL

    • /v1/txhashset/lastrangeproofs (gets last 10)
    • /v1/txhashset/lastrangeproofs?n=x

  • Method:

    GET

  • URL Params

    Required: n=[number]

  • Data Params

    None

  • Success Response:

    • Code: 200
    • Content:

    Array of

    Field Type Description
    hash string hash of the rangeproofs

  • Error Response:

    • Code: 500

  • Sample Call:

      $.ajax({
    url: "v1/txhashset/lastrangeproofs",
    dataType: "json",
    type : "GET",
    success : function(r) {
      console.log(r);
    }
  });

GET TxHashSet Last Kernels

Retrieves the last n kernels inserted in to the tree.

  • URL

    • /v1/txhashset/lastkernels (gets last 10)
    • /v1/txhashset/lastkernels?n=x

  • Method:

    GET

  • URL Params

    Required: n=[number]

  • Data Params

    None

  • Success Response:

    • Code: 200
    • Content:

    Array of

    Field Type Description
    hash string hash of the kernels

  • Error Response:

    • Code: 500

  • Sample Call:

      $.ajax({
    url: "/v1/txhashset/lastkernels?n=20",
    dataType: "json",
    type : "GET",
    success : function(r) {
      console.log(r);
    }
  });

GET TxHashSet Outputs

UTXO traversal. Retrieves last utxos since a start index until a max.

  • URL

    /v1/txhashset/outputs?start_index=x&max=y

  • Method:

    GET

  • URL Params

    Required: start_index=[number] max=[number]

  • Data Params

    None

  • Success Response:

    • Code: 200

    • Content:

      Field Type Description
      highest_index number The last available output index
      last_retrieved_index number The last insertion index retrieved
      outputs []object Outputs
      - output_type string The type of output Coinbase
      - commit string The homomorphic commitment representing the output's amount (as hex string)
      - spent bool Whether the output has been spent
      - proof string Rangeproof (as hex string)
      - proof_hash string Rangeproof hash (as hex string)
      - block_height number Block height at which the output is found
      - merkle_proof string Merkle proof
      kernels []object Transaction Kernels (a proof that a transaction sums to zero)
      - features object Options for a kernel's structure or use
      - bits number Representation of the features in bits
      - fee number Fee originally included in the transaction this proof is for
      - lock_height number The max lock_height of all inputs to this transaction
      - excess []number Remainder of the sum of all transaction commitments
      - excess_sig []number The signature proving the excess is a valid public key (signs the tx fee)

  • Error Response:

    • Code: 500

  • Sample Call:

      $.ajax({
    url: "/v1/txhashset/outputs?start_index=1&max=100",
    dataType: "json",
    type : "GET",
    success : function(r) {
      console.log(r);
    }
  });

GET TxHashSet Merkle Proof

Build a merkle proof for a given output id and return a dummy output with merkle proof for position filled out.

  • URL

    /v1/txhashset/merkleproof?id=x

  • Method:

    GET

  • URL Params

    Required: id=[string]

  • Data Params

    None

  • Success Response:

    • Code: 200

    • Content:

      Field Type Description
      outputs []object Outputs
      - output_type string The type of output Coinbase
      - commit string The homomorphic commitment representing the output's amount (as hex string)
      - spent bool Whether the output has been spent
      - proof string Rangeproof (as hex string)
      - proof_hash string Rangeproof hash (as hex string)
      - block_height number Block height at which the output is found
      - merkle_proof string Merkle proof

  • Error Response:

    • Code: 404 or 500

  • Sample Call:

      $.ajax({
    url: "/v1/txhashset/merkleproof?id=0803516094a30830ed9fedff1c63251b51703ddffbb73f944d9e33e8fa5d17444f",
    dataType: "json",
    type : "GET",
    success : function(r) {
      console.log(r);
    }
  });

Pool Endpoint

GET Pool

Retrieves basic information about the transaction pool.

  • URL

    /v1/pool

  • Method:

    GET

  • URL Params

    None

  • Data Params

    None

  • Success Response:

    • Code: 200

    • Content:

      Field Type Description
      pool_size number Number of transactions in the memory pool

  • Error Response:

    • Code: 500

  • Sample Call:

      $.ajax({
    url: "/v1/pool",
    dataType: "json",
    type : "GET",
    success : function(r) {
      console.log(r);
    }
  });

POST Pool Push

Push new transaction to our local transaction pool. Add ?fluff at the end of the URL to bypass Dandelion relay.

  • URL

    /v1/pool/push

  • Method:

    POST

  • URL Params

    None

  • Data Params

    file=[string] (hex encoded transaction)

  • Success Response:

    • Code: 200

  • Error Response:

    • Code: 500

  • Sample Call:

      $.ajax({
    url: "/v1/pool/push",
    dataType: "json",
    type : "POST",
    data: {
      file: tx
    },
    success : function(r) {
      console.log(r);
    }
  });

Peers Endpoint

POST Peers Ban

Ban a specific peer.

  • URL

    /v1/peers/a.b.c.d:p/ban

  • Method:

    POST

  • URL Params

    a.b.c.d:p=[string]

  • Data Params

    None

  • Success Response:

    • Code: 200

  • Error Response:

    • Code: 400

  • Sample Call:

      $.ajax({
    url: "/v1/peers/192.168.1.1:13414/ban",
    dataType: "json",
    type : "POST",
    success : function(r) {
      console.log(r);
    }
  });

POST Peers Unban

Unban a specific peer.

  • URL

    /v1/a.b.c.d:p/unban

  • Method:

    POST

  • URL Params

    a.b.c.d:p=[string]

  • Data Params

    None

  • Success Response:

    • Code: 200

  • Error Response:

    • Code: 400

  • Sample Call:

      $.ajax({
    url: "/v1/192.168.1.1:13414/unban",
    dataType: "json",
    type : "POST",
    success : function(r) {
      console.log(r);
    }
  });

GET Peers All

Retrieves all peers in db.

  • URL

    /v1/peers/all

  • Method:

    GET

  • URL Params

    None

  • Data Params

    None

  • Success Response:

    • Code: 200
    • Content:

    Array of

    Field Type Description
    addr string Network address of the peer
    capabilities object What capabilities the peer advertises
    - bits number Representation of the capabilities in bits
    user_agent string The peer user agent
    flags string State the peer has been detected with.
    last_banned number The time the peer was last banned
    ban_reason string The reason for the ban

  • Error Response:

    • Code: 500

  • Sample Call:

      $.ajax({
    url: "/v1/peers/all",
    dataType: "json",
    type : "GET",
    success : function(r) {
      console.log(r);
    }
  });

GET Peers Connected

Retrieves all connected peers

  • URL

    /v1/peers/connected

  • Method:

    GET

  • URL Params

    None

  • Data Params

    None

  • Success Response:

    • Code: 200
    • Content:

    Array of

    Field Type Description
    capabilities object What capabilities the peer advertises
    - bits number Representation of the capabilities in bits
    user_agent string The peer user agent
    version number Software version of the peer
    addr string Network address of the peer
    total_difficulty number Total of difficulty of the peer
    height number Height of the peer
    direction string Direction of the connection (Inbound

  • Error Response:

    • Code: 500

  • Sample Call:

      $.ajax({
    url: "/v1/peers/connected",
    dataType: "json",
    type : "GET",
    success : function(r) {
      console.log(r);
    }
  });

GET Peers

Retrieves information about a specific peer.

  • URL

    /v1/peers/a.b.c.d

  • Method:

    GET

  • URL Params

    a.b.c.d=[string]

  • Data Params

    None

  • Success Response:

    • Code: 200

    • Content:

      Field Type Description
      addr string Network address of the peer
      capabilities object What capabilities the peer advertises
      - bits number Representation of the capabilities in bits
      user_agent string The peer user agent
      flags string State the peer has been detected with.
      last_banned number The time the peer was last banned
      ban_reason string The reason for the ban

  • Error Response:

    • Code: 404 or 500

  • Sample Call:

      $.ajax({
    url: "/v1/peers/192.168.1.2",
    dataType: "json",
    type : "GET",
    success : function(r) {
      console.log(r);
    }
  });