sat-tui

sat-tui is the operator dashboard for satd: a curses-style terminal UI that connects over JSON-RPC and shows what the node is doing. It is read-only. The TUI cannot change node state. Bitcoin Core ships no equivalent surface.

This document is the reference for what the TUI shows. It is not a walkthrough. For guidance on what to look at first, see Observability & Metrics.

Running

sat-tui is built as part of the workspace and ships in every release tarball alongside satd and sat-cli.

sat-tui                        # mainnet, default RPC port (8332)
sat-tui --regtest              # regtest, port 18443
sat-tui --testnet              # testnet, port 18332
sat-tui --signet               # signet, port 38332

Authentication

Same precedence as sat-cli:

1. --rpcuser + --rpcpassword if both provided.
2. Cookie file at --rpccookiefile if provided.
3. Auto-detected cookie under --datadir (default ~/.bitcoin) for the active network.

If the cookie rotates while the TUI is running, for example because satd restarted, the RPC client re-reads the cookie file and retries once. If the retry also fails, the TUI falls back to the "Connecting to satd…" splash.

Other CLI flags

The TUI exits cleanly on q or Ctrl-C and restores the terminal mode.

Connection states

Before any view is shown, sat-tui is in one of three connection states:

• "Connecting to satd…" (yellow, centered): RPC is unreachable, or has returned only failures so far. Common during cold start, satd restart, or misconfigured auth.
• Startup splash: satd is up but still starting (header scan, reindex, address-index backfill). The splash is sourced from satd's getstartupinfo RPC; see Startup splash below.
• Active view: getblockchaininfo succeeded and one of the four main views is rendered.

A red ✕ stale indicator in the title bar means the last successful poll is more than about 3 seconds old. It means RPC is degraded right now. The TUI recovers on its own when polling resumes.

Views

There are four main views, plus a startup splash and three modal overlays.

The active view is auto-selected from chain state (is_ibd): the IBD view during initial block download, the Steady view once synced. Press 1 / 2 / 3 / 4 to force a view. Press the same key again to return to auto-detect.

Startup splash

Shown while satd is in startup (header scan, reindex, address-index backfill). The splash is one panel:

ETAs cover one phase at a time because per-item costs differ sharply between phases. During a reindex, the header scan and the block replay proceed at unrelated rates, so a whole-startup estimate would mislead until the replay dominates.

IBD view (1)

Shown while the node is in initial block download. Five panels stacked vertically:

Title bar

Chain name, satd version, is_ibd indicator.

Progress block

• Blocks / target: connected blocks vs. the highest block any peer has advertised.
• blk/s: blocks connected per second, EMA-smoothed.
• hdr/s: headers received per second.
• ETA: server-side estimate from satd's getibdprogress RPC. Per-block validation cost varies about 50× across history, from early empty blocks to modern weight-bound blocks. A naive "blocks remaining ÷ blk/s" calculation is wildly wrong, especially in the first few hundred thousand blocks.
• Peers: connected peer count.

Block map

A bitmap of download state per block group (one cell ≈ many blocks):

A healthy IBD shows a leading wave of █ followed by ░, with a narrow ▓ band at the frontier. Long stretches of ▓ mean a peer is slow or unresponsive. Long stretches of · mean the node is bandwidth-bound or short on peers.

Sync rate + stats

Two sparklines (about 90 seconds of history):

• blk/s connected (yellow): rate of blocks fully validated.
• blk/s downloaded (cyan): rate of blocks pulled from peers, all peers summed.

Plus a stats panel: Headers, Connected, Stored, In-Flight, Remaining.

Peers table

Up / Down highlights a row.

Steady view (2)

Default view once is_ibd=false. Six stacked panels.

Title bar

Health dot, uptime.

Chain + Latest block (split)

Chain (left half):

• Height: current tip height.
• Difficulty: raw difficulty value.
• Hash Rate: network hashrate from getmininginfo (H/s).
• Last Block: seconds since the tip block's timestamp. More than an hour is unusual.

Latest block (right half):

• Hash: tip hash, truncated.
• Txs: transaction count.
• Size / Weight: bytes / weight units.
• Fees: total miner fees collected (BTC).
• Avg Rate: average effective fee rate across all txs (sat/vB).

Mempool + Fees (split)

Mempool (left half):

• Txs: unconfirmed transactions.
• Size: total bytes.
• Min Rate: current mempool minimum fee. 0.0 is the default, the min-relay floor of about 1 sat/vB. A non-zero value means the mempool is full and is evicting low-fee txs. New txs need at least this rate to enter.
• Tx Rate: recent tx-entry rate from getchaintxstats (tx/s).
• Size distribution: sparkline of vbyte buckets (0, 100, 250, 500, 1k, 5k, 10k, 50k+).

Fees (right half), fee tier estimates from estimatefees (mempool.space convention):

• High: next-block target (1-block confirmation).
• Medium: about 30 minutes (3-block target).
• Low: about 1 hour (6-block target).
• None: economy / min-relay floor.
• Mode: the estimator's data source: historical, mempool, or blend.
• Confidence: high (green) / medium (yellow) / low (red), for the High tier specifically.

UTXO + Network (split)

UTXO (left half):

• UTXOs: total unspent outputs.
• Total: sum of UTXO values (BTC).
• Supply: fraction of the 21M cap. Asymptotic; never reaches 100%.
• Age distribution: sparkline by UTXO age: <1h, 1h–1d, 1d–1w, 1w–1m, 1m–3m, 3m–1y, 1y–3y, 3y+.

Network (right half):

• Peers: inbound and outbound counts.

Peers table

Same controls as IBD's table; columns differ:

Services row

A single line summarizing satd's wallet-server surfaces, sourced from getserverstatus and getindexinfo:

addr-idx <state>   esplora <state>   electrum <state>

addr-idx states:

esplora and electrum states:

Footer

Keybindings hint, plus an unclean-shutdown indicator (⚠ unclean shutdown) if last_shutdown from getsysteminfo is dirty.

Mempool view (3)

Drill-down on unconfirmed transactions. Five panels.

Title bar

Health dot, uptime.

Summary strip

• Txs: unconfirmed transaction count.
• Bytes: total mempool bytes.
• Min / Max fees: feerate range across mempool entries.
• Δ last Ns: entries added and removed in the last polling window.

Feerate histogram

Bars per feerate bucket (1–2, 2–5, 5–10, 10–20, 20–50, 50–100, 100–200, 200–500, 500+ sat/vB) with vbyte counts. Bars are colored by fee tier, matching the Steady view's Fees panel.

Trend + Top-N (split)

Trend (left): sparklines for Bytes, Txs, MinFee over about 40 minutes.

Top-N (right): scrollable table of the top 50 unconfirmed txs by ancestor feerate.

Up / Down scroll.

Footer

Keybindings.

Chain view (4)

Long-horizon information that does not change every block. Three rows of two panels each.

Halvings | Retarget

Halvings:

• Subsidy epoch: index (0 = pre-first-halving).
• Subsidy: current block reward in BTC. Formula 50 >> halvings, saturates at 0 after halving 64.
• Halving in: blocks until the next halving.
• Halving ETA: estimated wall-clock time at the 10-minute target.
• Progress bar through the current 210,000-block subsidy era.

Retarget:

• Blocks to retarget: blocks until the next 2,016-block boundary.
• Retarget ETA: wall-clock estimate at the 10-minute target.
• Block time (epoch): observed average seconds per block within the current 2,016-block epoch. Empty at the start of an epoch.
• Δ Est: predicted difficulty adjustment at the next retarget, clamped to ±300% (Bitcoin's hard limit). A positive value means blocks arrive faster than the 10-minute target, so difficulty will rise.
• Progress bar through the current 2,016-block epoch.

Supply | Chain Security

Supply:

• Issued: BTC currently in the UTXO set.
• % issued: fraction of the 21M cap.
• Remaining: 21M − issued.
• Inflation: realized / forward: annualized issuance rate at the current subsidy and at the post-next-halving subsidy.

Chain Security:

• Chain work: cumulative work, in log₂(work) bits. Computed from the RPC's 256-bit chainwork hex string without materializing the full integer.
• Rewrite at hashrate: wall-clock seconds for the current network hashrate to redo the entire chain's work. Formula 2^(bits − log₂(hps)). This is a back-of-envelope rewrite cost; reorgs of any meaningful depth are economically and physically infeasible.
• Network hashrate: same number as the Steady view's Chain panel.

Peer clients | Trivia

Peer clients: distribution of peers by user-agent string. Top 5 agents, plus an "other" bucket. Useful for spotting an unusually homogeneous peer set or an unexpected dominant client.

Trivia: subsidy era name, halving date, next halving block height. Light reading.

Modal overlays

Modals are drawn over the active view. Esc or the toggle key closes them.

Help (h / ?)

Context-sensitive keybindings for the active view.

Reorg history (r)

Last 7 days of reorg events from getreorghistory. Up to 40 entries.

A persistent copy lives at $datadir/<network>/reorg.log, in the network-specific datadir subdirectory. On mainnet the file sits directly under $datadir. satd writes this log whether or not the TUI is running; the modal is a viewer of it.

Warnings

A centered overlay (80% × 70%) that appears automatically when getwarnings reports visible warnings. The border is red if any warning has Error severity, otherwise yellow.

Press a to acknowledge and dismiss every currently visible warning for this session. Press w to re-show everything previously dismissed.

Dismissal is per-session. If satd clears a warning ID and re-emits it, the modal reappears.

Keybindings

Polling and refresh

The TUI does not push commands to satd; it polls. The render loop runs every 250 ms regardless of polling state, so the UI stays responsive even when RPC is slow.

If a steady-state RPC has not returned within about 3 s, the title bar shows stale. The view continues to render; the indicator shows that the data on screen is older than the polling cadence implies.

Failure modes

The TUI does not panic on RPC errors. It shows them and keeps polling.

See also

• Observability & Metrics and Configuration, Tuning & Reload: the broader operator surfaces (CLI, RPC, observability, tuning).
• CORE_DIFFERENCES.md: what satd does differently from Bitcoin Core.
• Esplora REST API: Esplora REST endpoint reference.
• sat-cli help: every JSON-RPC method exposed by satd, including the ones the TUI uses.