DHIVA LABS · LEARN

Appearance

Beginner guide ​

By the end of this guide poolwatch will be watching your node's mempool, and you will know what each number on the dashboard and the detail view means.

What you need ​

  • poolwatch installed. See Install.
  • A running node with RPC turned on: monerod, oxend, beldexd or bitcoind, usually on the same machine. The node's default RPC settings work for Monero, Oxen and Beldex. For Bitcoin, server=1 must be set in bitcoin.conf.
  • The example configuration file, poolwatch.example.toml, from the release archive or the source folder.

Write a configuration file ​

poolwatch reads its settings from a file named poolwatch.toml in the folder you start it from.

  1. Copy the example:

    bash
    cp poolwatch.example.toml poolwatch.toml

  2. Open poolwatch.toml in a text editor. It has a [general] section and four [[chain]] blocks: Monero, Oxen, Beldex and Bitcoin.

  3. Delete the [[chain]] blocks for nodes you do not run. For example, if you only run monerod, keep this block and delete the other three:

    toml
    [[chain]]
id = "monero-main"
display_name = "Monero"
ticker = "XMR"
family = "cryptonote"
rpc_url = "http://127.0.0.1:18081"
decimals = 12
fee_rate_unit = "pN/B"

    If your node listens on another address or port, change rpc_url.

  4. Leave [general] as it is. Save the file.

Keep the Bitcoin block only if bitcoind runs as the same user, so poolwatch can read its cookie file at ~/.bitcoin/.cookie. Otherwise see Bitcoin authentication.

Start poolwatch ​

  1. Run it from the folder that holds poolwatch.toml:

    bash
    ./poolwatch

    (or poolwatch if it is on your PATH). With the file somewhere else, add --config /path/to/poolwatch.toml.

  2. Read the top line: poolwatch dashboard.

  3. Read the chains table. Each node has one row. The first figures appear within a few seconds:

    ColumnMeaning
    ●Green: the node answers. Yellow: reduced data. Red: the node cannot be reached.
    CHAINThe display_name from your configuration.
    TXSTransactions in the mempool now.
    POOL SIZETotal size of those transactions.
    IN/MINNew transactions poolwatch saw in the last minute.
    MED FEE/BThe median fee rate, in the chain's own unit.
    INSTANTCount of Blink or Flash transactions, for Oxen and Beldex. — otherwise.
    HEIGHTThe node's current block height.

    A — in a cell means there is no data for it yet.

  4. Below the table, if the window is tall enough, tx count (last 15m) draws a small chart of each pool's transaction count.

  5. Read the two lines at the bottom. The first lists the keys. The second shows a problem with the selected chain, if there is one, in red or yellow.

TIP

IN/MIN is high for the first minute after you start poolwatch. Every transaction already in the pool counts as newly seen at start-up. It settles after a minute.

Open a chain's detail view ​

  1. Press 1 to open the first chain (or Enter for the highlighted one). The top line shows the chain name and ticker, such as poolwatch Monero (XMR).

  2. Read fee bands on the left. Each line is a percentile of fee rates across the pool, from p10 to p90, with a bar, the rate and the number of transactions in that band. p50 is the median.

  3. Read pool dynamics on the right: how long the median transaction has been waiting (median residency), how many transactions have left the pool since you started (departed (mined/dropped)), and the inflow rate over 1, 5 and 15 minutes.

  4. Read the transaction table at the bottom, titled for example Monero mempool (412/412). It lists each transaction's shortened ID, size, fee rate and age. Use ↑ and ↓ (or k and j) to move through it.

  5. Press t to sort by age, then f to sort by fee rate again. The active column has a ▼ next to its name.

  6. Press d or Esc to go back to the dashboard.

Press ? at any time for the list of keys, and q to quit.

Run a one-off report ​

For a quick check without the full-screen view, run:

bash
./poolwatch --once

poolwatch asks each node once and prints a short report per chain, then exits:

text
Monero (monero-main): OK
  txs: <count>
  pool size: <size>
  height: <height>
  top fee band: p90 <rate> pN/B (<count> tx)

A chain that cannot be reached prints ERROR - and the reason instead. The exit code is 0 if at least one chain answered and 1 if none did, so you can use it in scripts and monitoring checks.

What you learned ​

  • poolwatch reads poolwatch.toml, with one [[chain]] block per node.
  • The dashboard has one row per node; the dot shows whether the node answers.
  • 1 to 9 open a chain's detail view with fee bands, pool dynamics and the transaction list.
  • --once prints a report and exits.

Next steps ​