JSON-RPC overview

NULL exposes two JSON-RPC 2.0 services over HTTP: the node, nulld, for chain, mempool and mining data, and the wallet daemon, null-wallet-rpc, for addresses, balances, deposits and withdrawals. This page covers what they have in common. The method pages list every call.

A shielded-only chain

Integration guides for Bitcoin-like coins assume things that are not true here. Read this before you design a deposit or payout system.

• The chain shows no addresses and no amounts. Every output is encrypted. No call returns the balance of an address or the transactions sent to an address. Deposits are found by trial-decrypting outputs with a viewing key, and the wallet daemon does that for you. That is why there are two services: the node holds no keys, and the wallet daemon holds the keys of one wallet.
• Sending takes seconds. Every payment carries a zero-knowledge proof. Proving takes about a second for a small transaction and about five seconds for a 16-action one. Send calls (sendmany, consolidate) return an operation id at once, and you poll the operation until it is confirmed.
• The node builds the coinbase. The coinbase is a shielded transaction with its own proof, so a pool cannot assemble it from a script. getblocktemplate takes your payout address, builds and proves the coinbase, and returns the exact header bytes to grind.
• One key, many addresses. A wallet derives as many diversified addresses as you need from one key, and its viewing key detects payments to all of them. Give every customer their own deposit address; you never manage per-customer keys.
• Batching is built in. A transaction holds up to 16 actions at a fixed fee of 10,000 units per action. One withdrawal can pay up to 15 recipients plus change.
• Every output has a memo. A 512-byte encrypted memo travels with each output, readable only by the recipient and the sender.

Coinbase rewards mature after 100 blocks on mainnet. The network refuses reorganizations deeper than 200 blocks. See Exchanges and Mining pools for walk-throughs.

The two services

Both binaries ship in the release archives at github.com/NullNetProtocol/null-chain/releases.

Enable the node RPC

The node's JSON-RPC listener is off until you pass --rpc-http. It has no default address; these docs use 127.0.0.1:18446.

nulld run --network main --rpc-http 127.0.0.1:18446

The listener uses the same token as the control socket. Pass it with --rpc-token or the NULL_RPC_TOKEN variable. If you give none, the node generates one and writes it to rpc.token in its data directory. The default data directory is <user data>/main/chain/, where <user data> is ~/.local/share/null on Linux, ~/Library/Application Support/Null on macOS and %LOCALAPPDATA%\Null on Windows. With --datadir the token is written there instead. The node prints the token location at startup.

TOKEN=$(cat ~/.local/share/null/main/chain/rpc.token)

--blocknotify '<command>' runs a shell command on every new main-chain tip, with %s replaced by the block hash. See Run a node for the other flags.

Enable the wallet daemon

Create the wallet file first with nulld create (see Command line), then start the daemon:

export NULL_WALLET_PASSPHRASE='the wallet passphrase'
null-wallet-rpc --wallet /srv/hot/hot.redb --network main \
  --node 127.0.0.1:18444 \
  --node-token-file ~/.local/share/null/main/chain/rpc.token \
  --listen 127.0.0.1:18447
WALLET_TOKEN=$(cat /srv/hot/wallet-rpc.token)

The wallet passphrase comes from NULL_WALLET_PASSPHRASE or an interactive prompt.

Transport and conventions

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

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

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

[
  { "jsonrpc": "2.0", "result": 6206, "id": "a" },
  {
    "jsonrpc": "2.0",
    "error": { "code": -32601, "message": "unknown method nosuchmethod" },
    "id": "b"
  }
]

Errors

{
  "jsonrpc": "2.0",
  "error": {
    "code": -1,
    "message": "block not found"
  },
  "id": 1
}

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32001,
    "message": "unauthorized"
  },
  "id": null
}

Method index

• Node methods: getblockchaininfo, getblockcount, getbestblockhash, getblockhash, getblock, getblockheader, getcompactblock, getrawtransaction, gettransactionstatus, sendrawtransaction, getrawmempool, getmempoolinfo, getnullifierstatus, getpeerinfo, getnetworkinfo, getconnectioncount, uptime, stop, help.
• Mining methods: getmininginfo, getblocktemplate, submitblock.
• Wallet methods: getwalletinfo, getnewaddress, listaddresses, getaddressinfo, validateaddress, exportviewingkey, getbalance, listunspent, listreceived, gettransaction, rescan, estimatefee, quotepayment, sendmany, getoperationstatus, listoperations, canceloperation, quoteconsolidation, consolidate, help.
• Selective disclosure: getpaymentdisclosure and answerchallenge on the wallet daemon, verifypaymentdisclosure and createchallenge on the node.