A tour of irondivi-cli

1Before you start

You need an IronDivi node running on testnet and synced to the tip. If you do not have one, Install IronDivi gets you there in about an hour, most of it waiting. To see wallet answers with real numbers in them, send the node's address some testnet coins first with Get testnet DIVI. Ours held 25,000 tDIVI from the faucet.

irondivi-cli does one thing: it sends a command to the node over the command port and prints the reply. It takes the same commands as the original divi-cli. Every line in this tour starts the same way, so save yourself the typing by giving it a short name for this terminal session:

cd ~/irondivi
alias dcli='./irondivi-x86_64-linux-musl/irondivi-cli --testnet'
dcli getblockcount

360224

On a Mac the folder is irondivi-aarch64-macos. The --testnet is not optional: it tells the tool to use the testnet command port, 51473, and the testnet folder, where it reads the name and password you put in irondivi.conf. Leave it off and it looks for a mainnet node on port 51471 and tells you it cannot connect.

2Ask about the node

The quickest overview is -getinfo, with a dash. It is not a node command; the tool builds it from several questions and prints a summary:

dcli -getinfo

Chain: test
Blocks: 360224
Headers: 360224
Verification: 100.0000%
Difficulty: 7947.002292563693

Network: /IronDivi:0.2.5/
Connections: 8 (in: 0, out: 0)

Wallet: wallet.dat
Balance: 25000.0

Blocks equal to Headers and Verification at 100% means you are at the tip. The in/out split after the connection count is not reliable in this version: ours read 0 and 0 with eight connections, and 0 and 8 on another day. Trust the first number. For the same facts as data, ask the node directly:

dcli getblockchaininfo

{
  "bestblockhash": "12a4ef4d98bd6fc66a5f80a9b20d862fa4d10fe7483959314d55c694d08f2d23",
  "blocks": 360224,
  "chain": "test",
  "chainwork": "000000000000000000000000000000000000000000000000a21de2ff8a58dc64",
  "difficulty": 7947.002292563693,
  "headers": 360224,
  "mediantime": 1792629079,
  "pruned": false,
  "verificationprogress": 1.0,
  "warnings": ""
}

Most answers come back like this, in JSON: a list of names and values inside curly brackets. verificationprogress of 1.0 is the same as 100%. mediantime is a time in seconds since 1970, the form every node uses; date -d @1792629079 on Linux turns it into a date.

Who the node is talking to:

dcli getconnectioncount
dcli getnetworkinfo
dcli getpeerinfo

getconnectioncount prints one number, 8 on our node. getnetworkinfo gives the node's own version ("subversion": "/IronDivi:0.2.5/", protocol 70920), which networks it can reach, and the lowest fee it will pass on, 0.0001 DIVI. getpeerinfo lists each connected node with its address and version. On our node every peer reported "subver": "/Divi Core:3.0.0/", the original node, which is what most of testnet runs. In this IronDivi version the byte and time counters inside getpeerinfo read 0; the totals in getnettotals are real (ours had received 199 MB since starting).

3Ask about the chain

Blocks are found by height (a number) or by hash (64 hex characters). getblockhash turns one into the other, and getblock reads the block:

dcli getblockcount
dcli getbestblockhash
dcli getblockhash 100000
dcli getblock 5d279fae6247c94f15cdf0721e846d61cb847890b7597cbd5010c84c4aa3702c

{
  "bits": "1b08d7d3",
  "chainwork": "00000000000000000000000000000000000000000000000029ae0920bdb3e760",
  "confirmations": 260225,
  "difficulty": 7410.893417009036,
  "hash": "5d279fae6247c94f15cdf0721e846d61cb847890b7597cbd5010c84c4aa3702c",
  "height": 100000,
  "mediantime": 1777177672,
  "merkleroot": "ff4be878c4999e21435b445b28e7b8975432d901b3ee49ccad07566acd5c8cb0",
  "nTx": 2,
  "nextblockhash": "2755519ed513529c98e6b6fdd037ee5fa462aa63a414b88edebdc4e8f32ceda6",
  "nonce": 0,
  "previousblockhash": "835d55f095573331a674ad994ed12392e229846d7248760e83943e1a737c49dc",
  "size": 553,
  "time": 1777178295,
  "tx": [
    "7d2bc02e0e8fc48800bab3483c24fe43965b641e4c78264f8baf259348dbd99b",
    "dd66f51b81d844836b1adb754a7713ae19873e3c5592dc29a071c16d04ff0adf"
  ],
  "version": 4
}

Testnet block 100,000 holds two transactions, as most Divi blocks do: the first is an empty placeholder every staked block carries (one output, worth 0), the second is the stake that made the block, paying the staker's coins back with the reward on top. previousblockhash and nextblockhash let you walk the chain in either direction. The help text promises that getblock <hash> 2 puts the full transactions inside the answer, but version 0.2.5 prints the ids either way, so read each transaction with getrawtransaction as in step 5. getblockheader gives the same block without the tx list. The block before the first one is block 0, the genesis block, and getblockhash 0 prints its hash: on testnet it begins 00000f43b54b. What a block's fields mean is the subject of Read a block.

Three more chain questions worth knowing:

• getdifficulty: the current staking difficulty, one number.
• getchaintips: every chain end the node knows. One entry with "status": "active" and "branchlen": 0 is normal; extra entries are short dead branches the network abandoned.
• getmempoolinfo and getrawmempool: how many transactions are waiting for a block, and their ids. Testnet is quiet, so these are usually 0 and [].

4Ask about your wallet

dcli getwalletinfo

{
  "balance": 25000.0,
  "hdmasterkeyid": "95311a5c8807fc1bb96e4b7447fc9bb29ca595d0",
  "immature_balance": 0.0,
  "keypoololdest": 1792611688,
  "keypoolsize": 100,
  "paytxfee": 0.0001,
  "txcount": 1,
  "unconfirmed_balance": 0.0,
  "unlocked_until": 0,
  "walletname": "wallet.dat",
  "walletversion": 120200
}

balance is what you can spend now. immature_balance is staking rewards that are too new to spend yet, and unconfirmed_balance is money on its way in. getbalance prints the first number on its own. To receive coins, ask for an address; each call gives a fresh one, and the old ones keep working:

dcli getnewaddress

xyfXzHVXF7NaXBCRAJ48gFdFonruZidm2z

Testnet addresses start with x or y; mainnet addresses start with D. The original node lets you attach a label to an address; this IronDivi version accepts the label and ignores it, and getaddressesbylabel returns every address in the wallet whatever label you give. Its source says so: "labels not implemented".

What the wallet holds and how it got there:

dcli listunspent
dcli listtransactions

# listunspent: each coin you could spend
[
  {
    "address": "y3zoonAcqSPxpqvawM3sLTrdoL1PhiszqY",
    "amount": 25000.0,
    "confirmations": 295,
    "ischange": false,
    "scriptPubKey": "76a9144cf79447ee10bfb7aac7348ec4ee827eba0ec45c88ac",
    "solvable": true,
    "spendable": true,
    "txid": "fe8a49bb1501fede300216cb48af492763baca932420cf07a83a36103d442034",
    "vout": 1
  }
]

A wallet balance is really a list of unspent outputs, each one a txid plus an output number vout. Here there is one, the faucet's payment, 295 blocks deep. listtransactions shows the same payment from the history side, with "category": "receive" and the block height it landed in, 359930. gettransaction <txid> gives one entry in full, and getreceivedbyaddress <address> totals what one address has ever received.

To check an address, yours or anyone's:

dcli validateaddress y3zoonAcqSPxpqvawM3sLTrdoL1PhiszqY

{
  "account": "",
  "address": "y3zoonAcqSPxpqvawM3sLTrdoL1PhiszqY",
  "hdchainid": "1c0cea852bf5eef8335cb37cdbdd03f5b2e92a193480f8c631a806777772bee5",
  "hdkeypath": "m/44'/301'/0'/0/0",
  "iscompressed": true,
  "ismine": true,
  "isscript": false,
  "isvalid": true,
  "iswatchonly": false,
  "pubkey": "03e996e328449fe3542c3b4b3c415497b82be9a990a83317d9d8d622a4983d314c",
  "scriptPubKey": "76a9144cf79447ee10bfb7aac7348ec4ee827eba0ec45c88ac"
}

isvalid says whether it is a well formed Divi address at all; ismine whether this wallet holds its key. hdkeypath is where the key sits in the wallet's tree: 301 is Divi's number, and this is the first receiving key. getaddressinfo answers the same question with a shorter list.

5Follow a transaction

gettransaction only knows about transactions that touch your wallet. getrawtransaction decodes any transaction on the chain, provided the node keeps a transaction index: txindex = true in irondivi.conf, which both our test nodes had. The 1 at the end asks for the decoded form rather than raw hex:

dcli getrawtransaction fe8a49bb1501fede300216cb48af492763baca932420cf07a83a36103d442034 1

# shortened: the hex and the two inputs are left out
{
  "txid": "fe8a49bb1501fede300216cb48af492763baca932420cf07a83a36103d442034",
  "height": 359930,
  "confirmations": 295,
  "size": 373,
  "vin": [ … two inputs, each a txid and vout the faucet spent … ],
  "vout": [
    {
      "n": 0,
      "scriptPubKey": {
        "addresses": [ "DMyx2wSN9C6gMHvTmZo85TyqQv8Gvq1pJL" ],
        "type": "pubkeyhash"
      },
      "value": 11612.5780876
    },
    {
      "n": 1,
      "scriptPubKey": {
        "addresses": [ "DCA4UwgDSmtTgbj9Gck8UoBtCLvaG8U5TU" ],
        "hex": "76a9144cf79447ee10bfb7aac7348ec4ee827eba0ec45c88ac",
        "type": "pubkeyhash"
      },
      "value": 25000.0
    }
  ]
}

The faucet spent two of its coins (vin) and made two outputs (vout): 25,000 to us as output 1, and 11,612.58 of change back to itself as output 0. The difference between what went in and what came out is the fee.

To ask whether an output is still unspent, give its txid and output number to gettxout. It prints the output, or nothing at all if it has been spent:

dcli gettxout fe8a49bb1501fede300216cb48af492763baca932420cf07a83a36103d442034 1

6Check staking

dcli getstakingstatus

{
  "enoughcoins": true,
  "haveconnections": true,
  "mintablecoins": false,
  "mnsync": true,
  "staking status": "Staking Disabled",
  "staking_balance": 25000.0,
  "validtime": true,
  "walletunlocked": true
}

Each line is one condition for staking, and the node stakes only when all of them are true. Ours says Staking Disabled because the settings file has staking = false; a node you only use to read the chain has no reason to stake. enoughcoins checks the balance is at least the minimum stake; mintablecoins is whether the wallet has coins eligible to stake right now. setstaking true turns staking on without a restart, and the status changes to Staking Active at once; setstaking false turns it off again. What staking earns and how long coins must wait is in Staking returns.

7Sign and verify a message

You can prove that you hold an address without spending anything from it. The node signs a text with the address's private key, and anyone with the address, the text and the signature can check it, with any Divi node, no wallet needed:

dcli signmessage y3zoonAcqSPxpqvawM3sLTrdoL1PhiszqY "hello from the tutorial"

H91LwSvgiYkCnnAfRG5+keD9LNDUvSJU8PauRS+/wBjHEtynq+iychhqPNLJK2hchffC7oPQuzZLoMg+JYdTg88=

dcli verifymessage y3zoonAcqSPxpqvawM3sLTrdoL1PhiszqY "H91LwSvgiYkCnnAfRG5+keD9LNDUvSJU8PauRS+/wBjHEtynq+iychhqPNLJK2hchffC7oPQuzZLoMg+JYdTg88=" "hello from the tutorial"

true

Change one letter of the text and the same check prints false. That is the whole trick: the signature is tied to this exact text and this exact address.

8Help, errors and stopping

help on its own lists every command the node knows, 145 lines in groups: Blockchain, Address Index, Generating, Network, Wallet, Util, Rawtransactions, Staking, Lite Wallet, Masternode, Spork, Vault, Logging, Control. help followed by a command explains that one:

dcli help getblock

getblock "blockhash" ( verbosity )

If verbosity is 0, returns hex-encoded data.
If verbosity is 1 (default), returns a JSON object.
If verbosity is 2, returns JSON object with transaction data.

Things in brackets are optional. The help text in this version is short; the original node's help for the same commands is longer and still applies, because the answers have the same fields.

When a command goes wrong the node says why, with a code. Three you will meet:

dcli uptime
error code: -32601: Method not found: uptime
dcli getblock notahash
error code: -32602: Invalid hash: notahash - invalid hex: Invalid character 'n' at position 0
./irondivi-x86_64-linux-musl/irondivi-cli --testnet --rpcport 53699 getblockcount
error: couldn't connect to server: error sending request for url (http://127.0.0.1:53699/)

-32601 means the node has no such command; it is the answer for a typo and also for the handful of original-node commands this version does not have yet, like uptime. -32602 means the command exists but an argument is wrong. "couldn't connect" means nothing is listening on that port: the node is not running, or you have the wrong port or forgot --testnet. A reply of HTTP 401 Unauthorized means something is listening but the name and password did not match, usually because the tool read a different irondivi.conf than the node did.

There is a stop command, but on IronDivi 0.2.5 it only answers; the node keeps running:

dcli stop

Divi server stopping

To really stop the node, send the program the stop signal and check it has gone. Our synced testnet node exited 2 seconds after kill:

pgrep -a irondivid      # on a Mac: pgrep -l irondivid
kill 890008             # the number pgrep printed
pgrep irondivid         # prints nothing once it has gone

That is enough to find your way around. Where IronDivi's answers differ from the original node's, and which commands only one of them has, is in IronDivi vs the C++ node. Every setting the node takes is in Config files explained.

If something goes wrong

Still stuck? Ask the Divi chatbot, or see all tutorials.