Node methods

These methods are served by nulld on its --rpc-http listener. They cover the chain, blocks, transactions, the mempool, nullifiers and peers. The node holds no keys, so nothing here reveals an address, an amount or a memo. For those, use the wallet daemon.

The examples assume nulld run --rpc-http 127.0.0.1:18446 and TOKEN holding the node's token; see the overview. Parameters can be passed by position or by name.

RPCgetblockchaininfo

getblockchaininfo

The chain tip and the consensus parameters in force. Monitor branch, next_branch and upgrades: they tell you when a network upgrade is scheduled and when it activates.

No parameters.

Result

Name
network
Type
string
Description
main or test.
Name
height
Type
number
Description
Tip height.
Name
best_block_hash
Type
hex
Description
Tip hash.
Name
genesis_hash
Type
hex
Description
Genesis block hash.
Name
syncing
Type
boolean
Description
Whether a sync from a peer is in progress.
Name
branch
Type
string
Description
Branch id in force at the tip.
Name
next_branch
Type
string
Description
Branch id the next block must follow. Sign transactions for this one.
Name
genesis_branch
Type
string
Description
Branch id at genesis.
Name
upgrades
Type
array
Description
Scheduled upgrades, each {height, branch}. Empty when none is scheduled.
Name
block_interval
Type
number
Description
Target seconds between blocks.
Name
difficulty_window
Type
number
Description
Blocks the difficulty rule averages.
Name
anchor_max_age
Type
number
Description
How many blocks a commitment root stays usable as a transaction anchor.
Name
max_reorg_depth
Type
number
Description
Deepest reorganization the node accepts.
Name
max_future_seconds
Type
number
Description
How far a block timestamp may be ahead of the node's clock.
Name
pow_limit
Type
string
Description
Compact easiest target for the next block.
Name
pow_limit_change
Type
object | null
Description
A scheduled change of the limit, {height, limit}.
Name
equihash
Type
object
Description
Proof-of-work parameters {n, k}.
Name
fee_per_action
Type
string
Description
Fee per transaction action, in units.
Name
action_classes
Type
array
Description
Allowed transaction sizes in actions.
Name
max_actions
Type
number
Description
Most actions in one transaction.
Name
proof_lengths
Type
object
Description
Proof size in bytes per action class.
Name
max_block_transactions
Type
number
Description
Most transactions in one block.
Name
coinbase_maturity
Type
number
Description
Blocks before a coinbase reward is spendable.
Name
coin
Type
string
Description
Units in 1 NULL.
Name
max_money
Type
string
Description
Total supply limit, in units.
Name
premine
Type
string
Description
Development fund paid by the genesis coinbase, in units.

Request

RPC

getblockchaininfo

curl -s http://127.0.0.1:18446/ \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getblockchaininfo","params":[]}'

Response

{
  "jsonrpc": "2.0",
  "result": {
    "network": "main",
    "height": 6206,
    "best_block_hash": "00000fc8d37f816b43e79acbaba7d736adbbcbfdca48182361e0dd943a456273",
    "genesis_hash": "a47d659978361de625cfb4d84641b4f2de6f69ef04338e52612e5f8d95853c92",
    "syncing": false,
    "branch": "0x4d41494e",
    "next_branch": "0x4d41494e",
    "genesis_branch": "0x4d41494e",
    "upgrades": [],
    "block_interval": 120,
    "difficulty_window": 60,
    "anchor_max_age": 100,
    "max_reorg_depth": 200,
    "max_future_seconds": 7200,
    "pow_limit": "200fffff",
    "pow_limit_change": { "height": 11, "limit": "200fffff" },
    "equihash": { "n": 144, "k": 5 },
    "fee_per_action": "10000",
    "action_classes": [2, 4, 8, 16],
    "max_actions": 16,
    "proof_lengths": { "16": 49056, "2": 8736, "4": 14496, "8": 26016 },
    "max_block_transactions": 512,
    "coinbase_maturity": 100,
    "coin": "100000000",
    "max_money": "2100000000000000",
    "premine": "63000000000000"
  },
  "id": 1
}

RPCgetblockcount

getblockcount

The tip height. No parameters.

Request

RPC

getblockcount

curl -s http://127.0.0.1:18446/ \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getblockcount","params":[]}'

Response

{ "jsonrpc": "2.0", "result": 6206, "id": 1 }

RPCgetbestblockhash

getbestblockhash

The tip block hash. No parameters.

Request

RPC

getbestblockhash

curl -s http://127.0.0.1:18446/ \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getbestblockhash","params":[]}'

Response

{
  "jsonrpc": "2.0",
  "result": "00000fc8d37f816b43e79acbaba7d736adbbcbfdca48182361e0dd943a456273",
  "id": 1
}

RPCgetblockhash

getblockhash

The hash of the main-chain block at a height.

Parameters

Name
height
Type
number
Description
Required. Block height.

Errors

-1 if there is no block at that height.

Request

RPC

getblockhash

curl -s http://127.0.0.1:18446/ \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getblockhash","params":[6200]}'

Response

{
  "jsonrpc": "2.0",
  "result": "0000041e3f6c9e069db217c9e40e047f0ef33e9113bb066fb106c1c83a7414f6",
  "id": 1
}

RPCgetblock

getblock

A block by height or by hash. A height always resolves on the main chain. A hash also finds a known side-chain block, reported with in_main_chain: false and confirmations: -1.

Parameters

Name
block
Type
number | hex
Description
Required. A height, or a block hash as a string.
Name
verbosity
Type
number
Description
Optional, default 1. 0 returns the serialized block as hex. 1 returns the decoded header with the txids in tx. 2 returns the same with each transaction decoded as in getrawtransaction.

Result (verbosity 1 and 2)

Name
hash
Type
hex
Description
Block hash.
Name
height
Type
number
Description
Block height.
Name
version
Type
number
Description
Block version.
Name
previousblockhash
Type
hex
Description
Parent hash.
Name
time
Type
number
Description
Header timestamp, Unix seconds.
Name
commitment_root
Type
hex
Description
Note commitment tree root after this block.
Name
tx_root
Type
hex
Description
Commitment to the block's transaction ids.
Name
target
Type
string
Description
Compact target.
Name
target_hex
Type
hex
Description
The full 256-bit target.
Name
nonce
Type
hex
Description
32-byte nonce.
Name
solution
Type
hex
Description
100-byte Equihash solution.
Name
size
Type
number
Description
Serialized block size in bytes.
Name
in_main_chain
Type
boolean
Description
Whether the block is on the main chain.
Name
confirmations
Type
number
Description
Blocks from this one to the tip, inclusive; -1 off the main chain.
Name
nextblockhash
Type
hex | null
Description
Next main-chain block; null at the tip or off the main chain.
Name
transaction_count
Type
number
Description
Number of transactions, coinbase included.
Name
tx
Type
array
Description
Txids at verbosity 1, decoded transactions at verbosity 2.

Errors

-1 if the block is unknown. -32602 if block is neither a height nor a 32-byte hex hash.

Request

RPC

getblock

curl -s http://127.0.0.1:18446/ \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getblock","params":[6200, 1]}'

Response

{
  "jsonrpc": "2.0",
  "result": {
    "hash": "0000041e3f6c9e069db217c9e40e047f0ef33e9113bb066fb106c1c83a7414f6",
    "height": 6200,
    "version": 1,
    "previousblockhash": "000002d35a21f50dcd68fce36aaab2d635d031dfc8a56c1a19880023c8e36130",
    "time": 1793000072,
    "commitment_root": "78fd364601e2bad0a815d1e0d92eee5befe521c3f39d680c84b59c1446ca2f2d",
    "tx_root": "c5fc4db714b5e62a5c0af46f0fcfce89f21ada75e4bc8785b0b31f8e658eecf5",
    "target": "1e11e4e5",
    "target_hex": "000011e4e5000000000000000000000000000000000000000000000000000000",
    "nonce": "0b4680cf54180000000000000000000000000000000000000000000000000000",
    "solution": "2b42312ca76542f1d8abc9d72888e6e6766551e177671aebfecfce2fbe37238ff3f83896a81475ef6c80814579639db044b4e5ed8ef0da2b3db0adad27365202ba36854d1dbccdeb11f7af2882be58218c6641d4527411776f0bc252180f752cb9fdfbe8",
    "size": 10851,
    "in_main_chain": true,
    "confirmations": 7,
    "nextblockhash": "0000034c502b7b5a47d3641de7729e242c3beb8f785b2dc9eb2d5c56476df4f0",
    "transaction_count": 1,
    "tx": [
      "f87f8316528ce4a5f39f977ed94dab3298287e3a9ed977c4039da97c637ed898"
    ]
  },
  "id": 1
}

RPCgetblockheader

getblockheader

The same fields as getblock at verbosity 1, without tx.

Parameters

Name
block
Type
number | hex
Description
Required. A height, or a block hash as a string.

Errors

-1 if the block is unknown.

Request

RPC

getblockheader

curl -s http://127.0.0.1:18446/ \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getblockheader","params":{"block":"0000041e3f6c9e069db217c9e40e047f0ef33e9113bb066fb106c1c83a7414f6"}}'

Response

{
  "jsonrpc": "2.0",
  "result": {
    "hash": "0000041e3f6c9e069db217c9e40e047f0ef33e9113bb066fb106c1c83a7414f6",
    "height": 6200,
    "version": 1,
    "previousblockhash": "000002d35a21f50dcd68fce36aaab2d635d031dfc8a56c1a19880023c8e36130",
    "time": 1793000072,
    "commitment_root": "78fd364601e2bad0a815d1e0d92eee5befe521c3f39d680c84b59c1446ca2f2d",
    "tx_root": "c5fc4db714b5e62a5c0af46f0fcfce89f21ada75e4bc8785b0b31f8e658eecf5",
    "target": "1e11e4e5",
    "target_hex": "000011e4e5000000000000000000000000000000000000000000000000000000",
    "nonce": "0b4680cf54180000000000000000000000000000000000000000000000000000",
    "solution": "2b42312ca76542f1d8abc9d72888e6e6…",
    "size": 10851,
    "in_main_chain": true,
    "confirmations": 7,
    "nextblockhash": "0000034c502b7b5a47d3641de7729e242c3beb8f785b2dc9eb2d5c56476df4f0",
    "transaction_count": 1
  },
  "id": 1
}

RPCgetcompactblock

getcompactblock

The compact form of a main-chain block that light clients scan. It lists the actions whose note commitments the block appends to the tree, in tree order. Coinbase outputs enter the tree when they mature, so a maturing coinbase from an earlier block appears in the block where it matures, not where it was mined.

The result is hex of: height (LE32), block hash (32 bytes), action count (LE32), then per action the nullifier (32), note commitment cmx (32), ephemeral key (32) and the first 52 bytes of the note ciphertext.

Parameters

Name
height
Type
number
Description
Required. Block height.

Errors

-1 if there is no block at that height.

Request

RPC

getcompactblock

curl -s http://127.0.0.1:18446/ \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getcompactblock","params":[6200]}'

Response

{
  "jsonrpc": "2.0",
  "result": "381800000000041e3f6c9e069db217c9e40e047f0ef33e9113bb066fb106c1c83a7414f602000000…",
  "id": 1
}

RPCgetrawtransaction

getrawtransaction

A transaction from the main chain or the mempool. The decoded form shows only what the chain reveals: action commitments and nullifiers, the anchor, the fee and sizes. There are no addresses, amounts or memos.

Parameters

Name
txid
Type
hex
Description
Required. Transaction id.
Name
verbose
Type
boolean
Description
Optional, default false. false returns the serialized transaction as hex; true returns the decoded object.

Result (verbose)

Name
txid
Type
hex
Description
Transaction id.
Name
version
Type
number
Description
Transaction version.
Name
anchor
Type
hex
Description
The commitment tree root the spends prove against.
Name
action_count
Type
number
Description
Number of actions: 2, 4, 8 or 16.
Name
actions
Type
array
Description
Per action: nullifier, rk (randomized spend key), cmx (note commitment), cv_net (value commitment).
Name
fee
Type
string
Description
fee_per_action times action_count, in units.
Name
size
Type
number
Description
Serialized size in bytes.
Name
proof_size
Type
number
Description
Proof size in bytes.
Name
height
Type
number
Description
Block height. Only once mined.
Name
index
Type
number
Description
Position in the block, 0 for the coinbase. Only once mined.
Name
confirmations
Type
number
Description
0 while in the mempool.

Errors

-1 if the node knows no such transaction. -32602 if txid is not 32 bytes of hex.

Request

RPC

getrawtransaction

curl -s http://127.0.0.1:18446/ \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getrawtransaction","params":["f87f8316528ce4a5f39f977ed94dab3298287e3a9ed977c4039da97c637ed898", true]}'

Response

{
  "jsonrpc": "2.0",
  "result": {
    "txid": "f87f8316528ce4a5f39f977ed94dab3298287e3a9ed977c4039da97c637ed898",
    "version": 1,
    "anchor": "e61af95ed796f11411be2dd31158044962af7b186ae6f1585b2a3d14f411f1d9",
    "action_count": 2,
    "actions": [
      {
        "nullifier": "42e204a4dabab6093e6fdcffd20636ef8013e1d1bd17f68514b4eaa690c3d587",
        "rk": "839dea6e8fe73f7a8660cc0a738cd2282e50f022377c74580bb605c917bb8b81",
        "cmx": "fe9fb87336650198323ad6532d4cb8b71ca562ba3468155c24b8e57ed9f4101d",
        "cv_net": "0c3589d04c15e034ee8b4f8ecb45875b527bb3280a2b8208cdd71a25d23b347f"
      },
      {
        "nullifier": "d6573efcbca35126907b3534d31472a55832c0c723729cb22f0ea7043ea5376e",
        "rk": "1dfbb9228284d0e19d5a6d62f082c0716f53b86a5c0c991a6ba7a6b42f94fa2e",
        "cmx": "959d218b6100ef654c595681078f8b8e6f6ec5e0427383db819015f00520acfa",
        "cv_net": "b7c1f04e2a9d63850e1c7a4f92d8b3e6a05f1c2d7e8b9a0c3d4e5f60718293a4"
      }
    ],
    "fee": "20000",
    "size": 10602,
    "proof_size": 8736,
    "height": 6200,
    "index": 0,
    "confirmations": 7
  },
  "id": 1
}

RPCgettransactionstatus

gettransactionstatus

Where a transaction is: in the mempool, mined on the main chain, or unknown to this node. Use it to follow a transaction you broadcast with sendrawtransaction.

Parameters

Name
txid
Type
hex
Description
Required. Transaction id.

Result

Name
status
Type
string
Description
pooled, confirmed or unknown.
Name
height
Type
number
Description
Block height. Only when confirmed.
Name
index
Type
number
Description
Position in the block. Only when confirmed.
Name
confirmations
Type
number
Description
0 when pooled. Absent when unknown.

Request

RPC

gettransactionstatus

curl -s http://127.0.0.1:18446/ \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"gettransactionstatus","params":["f87f8316528ce4a5f39f977ed94dab3298287e3a9ed977c4039da97c637ed898"]}'

Confirmed

{
  "jsonrpc": "2.0",
  "result": { "status": "confirmed", "height": 6200, "index": 0, "confirmations": 7 },
  "id": 1
}

Pooled

{ "jsonrpc": "2.0", "result": { "status": "pooled", "confirmations": 0 }, "id": 1 }

Unknown

{ "jsonrpc": "2.0", "result": { "status": "unknown" }, "id": 1 }

RPCsendrawtransaction

sendrawtransaction

Submits a serialized transaction to the mempool and relays it. Returns its txid. Submitting a transaction that is already pooled returns its txid again. Most integrators send through the wallet daemon's sendmany instead, which builds, proves, broadcasts and rebroadcasts for you.

Parameters

Name
hex
Type
hex
Description
Required. The serialized transaction.

Errors

-32602 if the hex does not decode as a transaction. -2 (transaction not accepted) if the node refuses it, for example because it is invalid, already mined, or spends a note that is already spent. The node log has the detailed reason.

Request

RPC

sendrawtransaction

curl -s http://127.0.0.1:18446/ \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"sendrawtransaction","params":["01e61af95ed796f1…"]}'

Response

{
  "jsonrpc": "2.0",
  "result": "3c1e8f0a5d2b47e69a0f8c7d6b5e4a3f2e1d0c9b8a7f6e5d4c3b2a1908f7e6d5",
  "id": 1
}

RPCgetrawmempool

getrawmempool

The txids in the mempool, oldest first. No parameters.

Request

RPC

getrawmempool

curl -s http://127.0.0.1:18446/ \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getrawmempool","params":[]}'

Response

{
  "jsonrpc": "2.0",
  "result": [
    "3c1e8f0a5d2b47e69a0f8c7d6b5e4a3f2e1d0c9b8a7f6e5d4c3b2a1908f7e6d5"
  ],
  "id": 1
}

RPCgetmempoolinfo

getmempoolinfo

Mempool size and capacity. No parameters.

Result

Name
size
Type
number
Description
Transactions in the mempool.
Name
capacity
Type
number
Description
Most transactions the mempool holds (10,000).

Request

RPC

getmempoolinfo

curl -s http://127.0.0.1:18446/ \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getmempoolinfo","params":[]}'

Response

{ "jsonrpc": "2.0", "result": { "size": 1, "capacity": 10000 }, "id": 1 }

RPCgetnullifierstatus

getnullifierstatus

Whether a nullifier has been revealed on the main chain, which means the note it belongs to is spent. Every nullifier of every mined transaction counts, including the dummy spends that pad a coinbase.

Parameters

Name
nullifier
Type
hex
Description
Required. 32-byte nullifier.

Result

Name
spent
Type
boolean
Description
Whether the nullifier is on the main chain.

Errors

-32602 if the value is not a valid 32-byte nullifier.

Request

RPC

getnullifierstatus

curl -s http://127.0.0.1:18446/ \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getnullifierstatus","params":["42e204a4dabab6093e6fdcffd20636ef8013e1d1bd17f68514b4eaa690c3d587"]}'

Response

{ "jsonrpc": "2.0", "result": { "spent": true }, "id": 1 }

RPCgetpeerinfo

getpeerinfo

One entry per connected or handshaking peer. No parameters.

Result

Name
id
Type
number
Description
Connection id.
Name
addr
Type
string
Description
Remote socket address; the proxy's when one is used.
Name
target
Type
string
Description
What was dialed, or the remote address for inbound peers.
Name
direction
Type
string
Description
inbound or outbound.
Name
ready
Type
boolean
Description
Whether the version handshake is complete.
Name
version
Type
number | null
Description
The peer's protocol version, once known.
Name
best_height
Type
number | null
Description
The peer's tip height at handshake, once known.
Name
score
Type
number
Description
Misbehaviour score.

Request

RPC

getpeerinfo

curl -s http://127.0.0.1:18446/ \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getpeerinfo","params":[]}'

Response

{
  "jsonrpc": "2.0",
  "result": [
    {
      "id": 3,
      "addr": "203.0.113.24:19000",
      "target": "seed1.nullnet.sh:19000",
      "direction": "outbound",
      "ready": true,
      "version": 1,
      "best_height": 6204,
      "score": 0
    }
  ],
  "id": 1
}

RPCgetnetworkinfo

getnetworkinfo

Network name, protocol version and connection counts. No parameters.

Result

Name
network
Type
string
Description
main or test.
Name
protocol_version
Type
number
Description
Peer-to-peer protocol version.
Name
connections
Type
number
Description
Peers past the handshake.
Name
connections_in
Type
number
Description
Of those, inbound.
Name
connections_out
Type
number
Description
Of those, outbound.
Name
handshaking
Type
number
Description
Peers still in the handshake.

Request

RPC

getnetworkinfo

curl -s http://127.0.0.1:18446/ \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getnetworkinfo","params":[]}'

Response

{
  "jsonrpc": "2.0",
  "result": {
    "network": "main",
    "protocol_version": 1,
    "connections": 8,
    "connections_in": 0,
    "connections_out": 8,
    "handshaking": 1
  },
  "id": 1
}

RPCgetconnectioncount

getconnectioncount

The number of peers past the handshake. No parameters.

Request

RPC

getconnectioncount

curl -s http://127.0.0.1:18446/ \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getconnectioncount","params":[]}'

Response

{ "jsonrpc": "2.0", "result": 8, "id": 1 }

RPCuptime

uptime

Seconds since the node started. No parameters.

Request

RPC

uptime

curl -s http://127.0.0.1:18446/ \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"uptime","params":[]}'

Response

{ "jsonrpc": "2.0", "result": 86412, "id": 1 }

RPCstop

stop

Shuts the node down. It answers "stopping" and then exits. No parameters.

Request

RPC

stop

curl -s http://127.0.0.1:18446/ \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"stop","params":[]}'

Response

{ "jsonrpc": "2.0", "result": "stopping", "id": 1 }

RPChelp

help

The names of every node method, mining and disclosure methods included. No parameters.

Request

RPC

help

curl -s http://127.0.0.1:18446/ \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"help","params":[]}'

Response

{
  "jsonrpc": "2.0",
  "result": [
    "getblockchaininfo", "getblockcount", "getbestblockhash", "getblockhash",
    "getblock", "getblockheader", "getrawtransaction", "gettransactionstatus",
    "sendrawtransaction", "getrawmempool", "getmempoolinfo", "getnullifierstatus",
    "getcompactblock", "getpeerinfo", "getnetworkinfo", "getconnectioncount",
    "uptime", "stop", "help", "getmininginfo", "getblocktemplate", "submitblock",
    "verifypaymentdisclosure", "createchallenge"
  ],
  "id": 1
}