Reference
Every option, key and configuration setting in poolwatch 0.1.0.
Command line
poolwatch [--config PATH] [--chain ID]... [--interval SECS] [--once]| Option | Default | What it does |
|---|---|---|
--config PATH | poolwatch.toml | The configuration file to read. A relative path is relative to the current folder. |
--chain ID | every chain | Watch only the chain with this id. Repeat it to pick several. |
--interval SECS | from the file | Replaces poll_interval_secs for this run. Whole seconds. |
--once | off | Fetch one snapshot per chain, print a text report, and exit. No full-screen view. |
--version, -V | Print poolwatch 0.1.0 and exit. | |
--help, -h | Print the usage text and exit. |
Exit codes
| Code | Meaning |
|---|---|
0 | Normal exit. With --once: at least one chain answered. |
1 | With --once: no chain answered. Also any start-up error, such as a missing or invalid configuration file. |
2 | Unknown option or bad option value. |
With --once, each chain gets up to 10 seconds to answer. The report lists the chains sorted by id.
Key bindings
| Key | Action |
|---|---|
| q | Quit. Ctrl + C also quits, even while typing a filter. |
| d | Go to the dashboard. |
| 1 to 9 | Open the detail view of chain 1 to 9, in configuration file order. |
| Enter | Open the detail view of the highlighted chain. |
| Tab | Open the next chain's detail view, wrapping round. |
| Esc | From the detail view, back to the dashboard. Also closes help, and clears a filter while you type it. |
| ↑ ↓ or k j | Dashboard: highlight a chain. Detail view: move through the transaction table. |
| f | Detail view: sort transactions by fee rate, highest first. |
| s | Detail view: sort by size, largest first. |
| t | Detail view: sort by age, oldest first. |
| / | Detail view: filter the transaction table by transaction ID prefix. |
| p | Pause or resume polling. |
| ? | Show or hide the help overlay. |
While typing a filter: characters are added to it, Backspace deletes one, Enter keeps the filter, and Esc clears it. While help is open, only ?, Esc and q work.
Configuration file
TOML format. A [general] table and at least one [[chain]] table. Keys not listed here are ignored and noted in the log.
[general]
| Key | Required | Default | What it sets |
|---|---|---|---|
poll_interval_secs | Yes | Seconds between full pool fetches, per chain. The example uses 5. | |
stats_interval_secs | Yes | Seconds between summary (count and size) fetches, per chain. The example uses 2. | |
log_file | Yes | Log file path. ~ is expanded. Missing folders are created. | |
max_pool_response_mb | No | 64 | Largest full-pool reply accepted from a cryptonote chain, in MB. Above it the chain switches to stats-only. |
[[chain]]
| Key | Required | Applies to | What it sets |
|---|---|---|---|
id | Yes | all | A unique name for the chain, used by --chain. Duplicates are an error. |
display_name | Yes | all | The name shown in the views. |
ticker | Yes | all | The short symbol shown in the detail view title, such as XMR. |
family | Yes | all | cryptonote (monerod, oxend, beldexd and forks) or bitcoind (bitcoind and forks). |
rpc_url | Yes | all | The node's RPC address, such as http://127.0.0.1:18081. |
decimals | Yes | all | Decimal places of the coin's smallest unit: 12 for Monero, 9 for Oxen and Beldex, 8 for Bitcoin. |
fee_rate_unit | No | all | Label shown after fee rates. Default au/B for cryptonote, sat/vB for bitcoind. |
instant_tx | No | cryptonote | blink (Oxen) or flash (Beldex): mark those transactions with ⚡. |
rpc_login | No | cryptonote | user:pass for a node started with --rpc-login. |
rpc_cookie_file | One of these two | bitcoind | Path to the node's .cookie file. ~ is expanded. |
rpc_user, rpc_password | One of these two | bitcoind | User name and password. Both must be set together. |
A bitcoind chain needs either rpc_cookie_file or rpc_user with rpc_password, never both. Setting a bitcoind-only key on a cryptonote chain, or the reverse, stops poolwatch with an error that names the chain.
On Windows, ~ expands to your user profile folder. Write Windows paths as TOML literal strings in single quotes, for example rpc_cookie_file = 'C:\Users\you\AppData\Roaming\Bitcoin\.cookie'.
Default node RPC ports
| Node | Default rpc_url in the example | Notes |
|---|---|---|
monerod | http://127.0.0.1:18081 | Default RPC works. Add rpc_login if you use --rpc-login. |
oxend | http://127.0.0.1:22023 | Set instant_tx = "blink". |
beldexd | http://127.0.0.1:19091 | Set instant_tx = "flash". |
bitcoind | http://127.0.0.1:8332 | Needs server=1 in bitcoin.conf. |
RPC calls
poolwatch only reads. These are the calls it makes:
| Family | Calls |
|---|---|
cryptonote | /get_transaction_pool, /get_transaction_pool_stats, and get_info through /json_rpc |
bitcoind | getrawmempool (verbose), getmempoolinfo, getblockchaininfo, getnetworkinfo |
Each request has a 10-second connection timeout and a 30-second overall timeout.
Timings and limits
| Item | Value |
|---|---|
| Retry after a failed request | 1 s, doubling each time, at most 60 s |
| Retry after a too-large or unsupported full-pool fetch | 12 × poll_interval_secs |
| Full-pool size limit | max_pool_response_mb for cryptonote (default 64 MB); fixed 64 MB for bitcoind |
| Charts | Last 15 minutes |
| Fee bands | p10, p25, p50, p75, p90 |
| Screen redraw | Every 250 ms |
| Recommended terminal size | 80 × 24 or larger |
Logging
poolwatch writes its log to log_file, never to the terminal. The default level is info. Set the RUST_LOG environment variable for more detail, for example RUST_LOG=debug poolwatch.