satd Operator Manual

satd is a Bitcoin Core-compatible full node written in Rust. It is designed for the people who run node infrastructure: self-custodians on home servers and Raspberry Pis, downstream packagers (Umbrel, Start9, RaspiBlitz, MyNode), and integrators who build wallets, Lightning nodes, and explorers on a node they control.

This manual is the reference for operators, integrators, and packagers. It catalogs every shipped surface: observability and metrics, configuration and tuning, live reload, integrator APIs, the terminal UI, the native protocol surfaces (Esplora, Electrum, BIP 157-158), and the packaging contract.

One process, one store

Every API service in satd is a query layer over the same RocksDB store and chainstate the node itself uses. That covers JSON-RPC, Esplora, Electrum, BIP 157/158 filters, the streaming APIs, and MCP. The store is updated atomically inside block connection, so there is no second process and no second copy of the data. A satd deployment replaces the usual assembly of bitcoind, electrs, an Esplora indexer, and exporters with a single process that shares the node's storage across all surfaces.

This removes two failure modes of external indexers: the parallel block re-scan, and the reorg-window race where the indexer's view lags the node. Every surface reads one tip-consistent store.

The trade-off is disk. Serving Electrum, Esplora, getrawtransaction, and BIP 158 from one node makes satd's aggregate on-disk index larger than a standalone external index. See Disk Footprint & Indices for the byte-level accounting, and API Scaling & Runtimes for the scale-out trade-off.

How this manual is organized

• Operating: the day-to-day surfaces. Observability and metrics; configuration, tuning, and live reload; initial block download and AssumeUTXO fast sync; API scaling and the two-runtime model; authentication and authorization, covering Core-compatible credentials and the unified bearer-token layer; the JSON-RPC extensions; and the sat-tui terminal dashboard.
• Protocol Surfaces: the Esplora REST API and Electrum protocol references, the streaming consumption API, the silent-payments integrator guide, and the MCP server. Each runs as a native, shared-chainstate subsystem of satd itself rather than as a companion process. The Disk Footprint & Indices chapter covers what the single shared store costs and provides.
• Architecture: the guided code tour, a slide deck that walks the source module by module with verbatim snippets and Bitcoin Core comparisons.
• Packaging & Deployment: the authoritative packaging contract for downstream distributions. File layout, signals, ports, the release and signing pipeline, and reproducible builds.
• Reference: the Configuration Flag Reference. Every recognized config key, its default, its reload disposition, and whether it is Bitcoin Core-compatible or a satd extension.

Related documents (in the repository)

These live at the repository root rather than in this manual:

• CORE_DIFFERENCES.md: the catalog of intentional deviations from Bitcoin Core.
• STABILITY_POLICY.md: the tiered stability contract and deprecation policy.
• SECURITY.md: signing keys, verification commands, and vulnerability reporting.
• MANIFESTO.md: node sovereignty, the monoculture risk, and the conservative BIP policy.
• ROADMAP.md: upcoming operator features and research areas not yet shipped.
• docs/api/streaming.md: the wire-level specification of the streaming-consumption API. It is a protocol spec; this manual documents the shipped surface.
• docs/api/webhooks.md: the alert-webhook delivery contract — headers, signature (with test vectors), retry and drop semantics. Written for anyone building a receiver.

Observability & Metrics

satd ships three observability surfaces: a native terminal dashboard, a Prometheus endpoint, and structured logs. None of them needs an external exporter or a log-parsing sidecar.

Native TUI (sat-tui)

satd ships with a native Ratatui-based terminal interface that shows node progress in real time:

• IBD bitmap: block download and verification progress.
• Peer stats: connected peers, their latency, and block delivery rates.
• Mempool status: live mempool depth and fee percentiles.

The full sat-tui reference, with every view, panel, field, and keybinding, is in the Terminal UI chapter.

Prometheus Metrics Endpoint

The metrics and health server starts only when a port is set. Use --metricsport=<port> to enable it. --metricsbind=<addr> sets the bind address alone (default 127.0.0.1) and does not enable the server on its own. The listener binds <metricsbind>:<metricsport>.

Over TLS

The metrics listener speaks plain HTTP and has no authentication, which is right for loopback and wrong for a LAN. To scrape from another machine, add a TLS listener beside it on its own port:

satd --metricsport=9332 \
     --metricstlsbind=0.0.0.0:9336 \
     --metricstlscert=/path/fullchain.pem --metricstlskey=/path/server.key

It serves the same endpoints as the plain listener. The plain listener keeps running, so container healthchecks and local tools are unaffected, and --metricstlsbind refuses to start without --metricsport. Leave --metricsbind at 127.0.0.1 so the only way in from the network is the TLS port. A bad certificate path or a port that cannot be bound stops satd at startup. The certificate reloads on SIGUSR1, like satd's other TLS listeners.

TLS encrypts the scrape but does not decide who may scrape. For that, require a client certificate with --metricsmtls=1 and --metricsmtlsclientca=<ca.pem>, and optionally narrow it to named clients with --metricsmtlsclientallow=<cn>[,<cn>...].

Prometheus supports both directly:

scrape_configs:
  - job_name: satd
    scheme: https
    tls_config:
      ca_file: satd-ca.crt
      server_name: satd.local
      # With --metricsmtls=1:
      # cert_file: prometheus.crt
      # key_file: prometheus.key
    static_configs:
      - targets: ['satd.local:9336']

The TLS listener serves at most 64 connections at once, gives a client 10 seconds to finish the handshake and 30 seconds to send its request headers.

The GET /metrics endpoint serves native Prometheus metrics covering P2P traffic, block validation times, mempool depth, and RocksDB performance. P2P wire volume is exported as the satd_net_bytes_sent_total and satd_net_bytes_recv_total counters, and peer count as satd_peer_connections. The GET /healthz and GET /readyz endpoints exist for load balancer and orchestrator integration.

See the Packaging chapter for how to wire /healthz and /readyz to Docker HEALTHCHECK, Kubernetes probes, or a systemd ExecStartPost= poll.

For dashboards and alerting, scrape /metrics rather than polling RPC. The Bitcoin Core methods getnettotals (byte totals) and getpeerinfo (bytessent, bytesrecv, lastsend, lastrecv, and the per-message-type breakdowns bytessent_per_msg / bytesrecv_per_msg) are populated and accurate for steady-state traffic, but they exist for Core compatibility. The Prometheus endpoint is a counter model built for time-series tooling (rates, retention, labels) and does not consume an RPC worker on every scrape.

Note. The RPC byte counters cover post-handshake traffic only. The one-time handshake bytes are not included, so absolute socket totals read marginally lower than the kernel's.

The per-message tallies sum to bytessent / bytesrecv for the same peer once a message is fully accounted for. The peer total is bumped before the per-type tally, so a getpeerinfo that lands mid-message can observe the breakdown trailing the total by one message's bytes — during IBD, by as much as a block. Treat the equality as a resting invariant, not something to alert on. They are on-wire sizes for the transport in use, so the same message costs fewer bytes on a BIP 324 v2 link than on v1. Message types satd has no variant for, undecodable frames, and v2 decoy packets are all counted under *other*, matching Core.

Compact block relay

Each block that arrives as a BIP 152 compact block logs one line at info when it is reconstructed:

compact block reconstructed hash=… height=… peer=… prefilled=1 prefilled_bytes=… mempool=2841 mempool_bytes=… extra=0 extra_bytes=0 requested=3 fetched_bytes=… redundant_prefilled=0 round_trip=true elapsed_ms=…

prefilled, mempool, extra and requested count where the block's transactions came from: sent with the block, found in the mempool, found among recently replaced or policy-refused transactions (blockreconstructionextratxn), or requested with getblocktxn. round_trip=false means the block was built without asking the peer for anything. A reconstruction that is given up logs compact block abandoned with reason=merkle (the filled block failed its merkle check, so the full block was requested), reason=timeout or reason=invalid.

The same numbers are counters:

The share of blocks reconstructed without a round trip is direct / (direct + round_trip + fallback).

Stratum server

While the Stratum server runs, its counters are exported. A node with --stratum=0 exports none of these families.

There are no per-miner series. A worker name is whatever the miner sends, so a label on it would let a miner create series without limit; getstratuminfo lists each miner instead. A miner that stops hashing shows as satd_stratum_miners holding steady while the accepted-share rate falls to zero.

Status page

--statuspage=1 adds a browser page to the metrics listener, a simplified, single-page sat-tui: whether the node is syncing or ready, sync progress and its ETA, AssumeUTXO background validation, each index and whether a wallet can connect yet, the latest block, the mempool, fee estimates and peer counts. It is off by default, and it needs --metricsport, since that is the listener it is served on.

statuspage=1
metricsport=9332
statusadvertise=electrum=ssl://node.local:50002
statusadvertise=esplora=https://node.local:3001/api

Open http://<metricsbind>:<metricsport>/status. The page is complete as served and works with JavaScript off. With JavaScript on it refreshes itself from /status.json every 5 seconds, pauses while the tab is hidden, backs off when the node stops answering, and after about 12 seconds without an answer says stale instead of going on showing the last reading.

What the top line means:

The page says ready only when /readyz is 200. Sync progress is weighted by how much work each part of the chain takes, so it trails the plain height ratio for most of a mainnet sync, as the time does.

Connection strings come only from statusadvertise. The page never builds one from the request's Host header, which a client can set to anything and which names the proxy in front of the node rather than the port a wallet should dial. Set one per surface a user should connect to, as they should type it. Leave them out where the platform shows its own addresses.

It is unauthenticated, like /metrics, and safe that way. It carries no cookie, password, token or key, no peer or listen address, and no warning or error text, which can name host paths; warnings appear by id, and getwarnings has the detail. Peers appear as counts and client versions. Every value is escaped, and the page is served with a Content-Security-Policy that allows its own script and requests only. Building it takes no lock that block connection needs.

/status.json is internal to the page and unstable: any field may change in any release. Monitor with /metrics and /readyz.

Index readiness

Each DB-backed index exports whether it is switched on, whether it is ready to serve, and what its deferred backfill is doing. The silent-payment family:

The address and block-filter indexes export the same readiness shape — satd_addrindex_synced / satd_addrindex_backfill_state{state="…"} (alongside the existing satd_addrindex_enabled and row counters), and satd_filterindex_enabled / satd_filterindex_synced / satd_filterindex_backfill_state{state="…"}. synced matches the corresponding getsatdindexinfo predicate in each case: for the address index it means the Electrum / Esplora address surfaces will serve; for the filter index it means BIP 157 peers and getblockfilter will be served. A failed or stuck backfill on any of the three is alertable with the same rules shown below — substitute the family prefix.

Do not alert on the progress ratio alone. 0.0 is not an error signal: it covers an index that is switched off, one built inline from a genesis sync (which never needs a backfill and stays at 0.0 while being perfectly complete), a backfill that has only just started, and one that failed near taproot activation. Alert on the state series instead, which distinguishes them:

# The backfill failed.
satd_spindex_backfill_state{state="failed"} == 1
  and ignoring(state) satd_spindex_enabled == 1

# Enabled but never going to become ready on its own: no backfill was ever
# started. This is the state an existing datadir lands in when the index is
# switched on without running `backfillindex silentpayment`.
satd_spindex_backfill_state{state="idle"} == 1
  and ignoring(state) satd_spindex_enabled == 1
  and ignoring(state) satd_spindex_synced == 0

# Running, but not making progress — stuck rather than merely slow.
satd_spindex_backfill_state{state="running"} == 1
  and ignoring(state) satd_spindex_enabled == 1
  and ignoring(state) delta(satd_spindex_backfill_progress_ratio[30m]) == 0

Three things worth copying exactly rather than paraphrasing:

• The satd_spindex_enabled == 1 guard belongs on every one of them, including the failed rule. The state series is derived from the persisted cursor, which outlives the config: switch silentpaymentindex back off after a failed backfill and the node keeps exporting satd_spindex_backfill_state{state="failed"} 1 for ever, because the cursor stays on disk and is deliberately not auto-resumed. Without the guard that pages continuously for an index the operator has turned off.
• ignoring(state) is required. and matches on identical label sets, and satd_spindex_backfill_state{state="running"} == 1 carries a state label that satd_spindex_enabled does not. Plain and finds no matching series and the rule silently evaluates to nothing, for ever — it will sit at "0 active" in the Prometheus UI, which reads as healthy.
• delta(), not rate(). The ratio is a gauge. rate() treats the drop back to 0.0 when a backfill restarts as a counter reset and compensates for it, which is not what you want here.

Give the last two a for: of at least an hour in the alert rule. A backfill that has not committed its first 1000-block batch yet legitimately shows no progress.

All seven state series are always present, so a rule can reference state="failed" before it has ever fired — the same reason satd_alert_active pre-registers at 0 (see below).

Node-health alerts

Metrics tell you what the node is doing; health alerts tell you when it has stopped doing it. satd watches six conditions about itself and reports each one through three surfaces at once, so they can never disagree:

• a status event on the Streaming Consumption API (category bit 16 — see §7.8 of the wire spec),
• an entry in getwarnings (and therefore in getblockchaininfo.warnings and the TUI), which also fires the Core-compatible alertnotify hook,
• a satd_alert_active{kind="..."} gauge on /metrics.

One-shot events are the exception to the middle surface. ibd_complete and deep_reorg describe something that happened; there is no state for anything to later clear. They fire alertnotify and emit their status event, but they do not create a getwarnings entry. An entry nothing clears would sit in getblockchaininfo.warnings for the life of the process and hold the TUI's warning modal open — which on signet and testnet4, where reorgs several blocks deep are ordinary, would happen on the first one and never stop. The durable record of a reorg is the reorg log (getreorghistory), not the warnings set.

Because they have no standing condition to dedupe against, one-shot events are rate-limited on the alertnotify hook instead: one exec per minute per event id, reporting the worst occurrence in that window. A run of reorgs otherwise queues one shell exec each on a channel drained one at a time, which grows without bound and pushes the hook further and further behind real time. Keeping the first occurrence and counting the rest would be worse still — a depth-3 reorg would claim the window and a depth-200 reorg a second later would be reduced to an increment, so a script that halts trading on alertnotify would hear about the harmless one and not the serious one. So:

• the first occurrence pages immediately;
• an occurrence strictly deeper than anything already paged in the window escalates through at once, capped at one escalation per window;
• the rest are held, and the worst of them pages when the window closes, carrying a count and the window as measured — rolled back 41 blocks [3 more in the previous 74s];
• a burst that stops is drained by the detector poll, not left waiting for a next occurrence.

None of this touches the status event or getreorghistory, which carry every occurrence unthrottled. If you are building on reorg data, read those.

The warnings set itself is capped at 256 distinct ids, with anything past the cap counted in a single warnings.truncated row. Almost every id is a fixed string, but a few embed an identifier — a block whose stored data is unreadable gets one per block — and a storage fault across many blocks would otherwise fill getwarnings, the TUI modal, and the hook. Ids already active keep updating, and the node log carries every one in full.

Every standing condition raises once on entry and clears once on recovery — you get a pair of events, not a stream of repeats — and the gap between the raise and clear lines (a ratio, a hold time, or both) means a value sitting on the threshold does not flap your pager. ibd_complete and deep_reorg describe things that happened rather than states that persist, so they are one-shot: they never clear, and for the same reason they never enter getwarnings at all.

Thresholds are configured with the alert* keys in the Configuration Reference; all of them are hot-reloadable, and setting one to 0 disables that detector. Each event carries a details map with the numbers behind it (free bytes and the floor, seconds since the last block and the tip height, the reorg's true depth and fork height, the mempool's current mempoolminfee), so an alert is actionable without a follow-up query. The watched path is deliberately not in the event — it goes to every status subscriber and into push-notification bodies, and an absolute datadir path usually names the account it runs under. The node logs it instead.

Retuning a threshold always clears its own alert. The gap between each raise and clear line stops a value hovering at the threshold from flapping, but it would otherwise trap the operator who raises a threshold because the alert is firing: the unchanged reading lands between the new raise line and the new clear line, where neither fires. So a standing condition also clears when the threshold moves such that it would no longer raise. Without this, mempool_congested in particular was inescapable — alertmempoolfullpct clamps at 100 and the clear line is 75 % of the raise line, so past 75 % occupancy no setting could clear it.

alertreorgdepth defaults to 3 on mainnet, where a reorg that deep costs real hashrate and invalidates transactions merchants have started treating as settled. Signet, testnet and testnet4 default to 10: those chains are not economically secured, and reorgs a few blocks deep are an ordinary consequence of thin, volatile hashrate rather than an incident. Defaulting them to mainnet's sensitivity would run -alertnotify for the network working as designed, and an alert that fires during normal operation is one you learn to ignore — which costs you the mainnet alert too. It is raised rather than switched off because past the 6-confirmation convention a wallet has been told something false, and that is worth reporting on any chain. Regtest is off entirely; its test suites reorg deliberately. Set alertreorgdepth=3 explicitly if you want mainnet sensitivity on a test network.

alertpeerfloor defaults to 3 everywhere except regtest, where it is 0 (disabled) because running with no peers at all is a regtest node's normal operating state rather than a fault. Signet keeps the floor: it is a public network with real peers, and a detector defaulted off is indistinguishable from a healthy one — satd_alert_active{kind="peer_floor"} reads 0 either way. Set alertpeerfloor=0 explicitly on a deliberately isolated signet node.

Where the floor is active, a node that has never seen a peer gets a 90 s startup grace, and the ordinary hold begins when that grace expires or when the first peer arrives, whichever comes first. The grace defers the start of the hold rather than shortening it, so a node still dialing out does not page anyone on the way up.

Durability. Health events are not replayable: they carry no resume cursor, and a from_cursor reconnect never yields one. Instead the detectors re-evaluate from scratch on startup and re-raise anything still standing, so a consumer that was disconnected across a restart still learns about a live problem. A condition that both raised and cleared while nothing was listening is stale by definition and is not reconstructed. For the same reason, a subscriber that attaches after a condition raised will not see it until the condition changes — check getwarnings for current state on connect.

Two of the gauges are useful independently of alerting: satd_tip_last_connect_age_seconds (seconds since the last connected block) and satd_disk_free_bytes (free space on the watched directory). The latter is omitted rather than reported as zero when the filesystem cannot be interrogated.

Alert webhooks

The three surfaces above all require something to be watching the node. A webhook pushes instead: point alertfile=<path> at a TOML file and satd POSTs each matching event to your endpoint.

version = 1

[[webhook]]
id = "pager"                        # unique; appears in the X-Satd-Hook header and metric labels
url = "https://alerts.example/satd"
secret = "a-long-random-string"     # required — it signs every delivery
categories = ["status"]             # status | chain | mempool | heartbeat
kinds = ["tip_stall", "disk_low"]   # optional, status only
min_severity = "warning"            # optional, status only

[[webhook]]
id = "deadman"
url = "https://hc-ping.example/abc123"
secret = "another-long-random-string"
categories = ["heartbeat"]
heartbeat_interval_secs = 300       # one ping per 5 min, not the bus's 1 Hz

The file must be mode 0600 — it holds signing secrets, and satd refuses to read a group- or world-accessible one. Its contents are re-read on every SIGHUP, so hooks can be added, edited, or removed without a restart; the path is fixed at startup. A parse error on reload keeps the last-good hook set and logs why, because alerting that silently stopped after a typo is the worse failure.

categories is required — a hook without it would receive nothing, which is never what anyone meant to configure. It selects from the node's firehose:

kinds and min_severity narrow status and apply to nothing else; both are checked after the category, so kinds without "status" in categories matches nothing. The streaming API's tweaks category is rejected here rather than ignored — it is per-block bulk data and an HTTP receiver is the wrong consumer for it.

mempool is almost never the right choice for a webhook: it is the whole network's traffic, not yours. To be told about your transactions, use the streaming API's Watch stream, which matches on scripts, outpoints, txids and silent-payment scan keys. A webhook hook cannot filter that way and is not meant to — see Streaming.

The normative wire contract — every header, the signature scheme with test vectors, and the exact retry semantics — is docs/api/webhooks.md. What follows is the working summary.

What arrives

POST /your/endpoint HTTP/1.1
Content-Type: application/json
X-Satd-Signature: sha256=<hex HMAC-SHA256(secret, canonical string)>
X-Satd-Timestamp: 1753400000
X-Satd-Delivery: <node_id>-<instance_id>-<seq>
X-Satd-Hook: pager
X-Satd-Attempt: 1
X-Satd-Webhook-Version: 2

{"schema_version":1,"stamp":{...},"body":{"category":"status", ...}}

The body is byte-identical to the JSON a WebSocket subscriber receives for the same event, so a receiver parses webhook bodies and streaming frames with one code path. Delivery metadata rides in headers and never in the body — which is what makes the signature stable across retries.

Verifying a delivery

The signature covers a canonical string, not the bare body — five fields joined by newlines, with the raw body last:

"2" LF <X-Satd-Timestamp> LF <X-Satd-Delivery> LF <X-Satd-Hook> LF <raw body>

Signing only the body would leave X-Satd-Delivery unauthenticated and predictable, and that header is the one this page tells you to deduplicate on. One captured (body, signature) pair could then be replayed under forged future delivery ids, poisoning your dedup cache so the real alerts were discarded on arrival while satd counted them delivered. Binding the id, the hook, and a timestamp into the signed material closes that.

So a receiver must:

1. Read X-Satd-Timestamp and reject anything older than 600 seconds. This is not optional — it is what stops a captured delivery being a permanent replay token. A delivery still being retried after the window ages out by design; a 20-minute-old "disk is filling" alert is not worth acting on.
2. Rebuild the canonical string above from the raw body, before parsing it.
3. Compare the HMAC in constant time.
4. Deduplicate on X-Satd-Delivery — stable across retries of one event, and unique across restarts, so a retry and a genuine repeat are distinguishable.
5. Reply 2xx to acknowledge.

Upgrading from the pre-release v1 scheme. Earlier drafts signed the raw body alone and sent X-Satd-Webhook-Version: 1. The legacy reorgwebhook= keys still use exactly that, unchanged, and still report version 1 — branch on the version header rather than assuming one scheme.

The X-Satd-Delivery value is opaque; do not parse it. Deduplicate on the whole header: it is unique per event and stable across the retries of one delivery, so the only duplicate you can receive is a retry of something you already saw.

Delivery behavior

• Serial and in-order per hook — one request in flight at a time, so events arrive in the order the node produced them.

• Retried with backoff on 5xx, 408, 429, timeouts, and connection failures: 1 s doubling to a 5-minute ceiling — but not forever. A delivery is abandoned once it ages past the 600 s freshness window it was signed with, which lands somewhere around the tenth or eleventh attempt. That is deliberate: the signed timestamp is the only staleness signal a receiver checks, so a delivery that could no longer pass that check is not worth sending. The practical consequence is that a receiver down for longer than ten minutes — a relay redeploy, a restart that takes a while — loses the events raised during the outage. Alert on satd_alertwebhook_dropped_total if that matters to you; the detectors re-raise standing health conditions, so those recover on their own, but chain and mempool events do not. Any other 4xx is treated as permanent, counted, and skipped — a receiver answering 404 forever must not pin the queue and turn every later event into a drop. The skip is counted in satd_alertwebhook_dropped_total and logged.

• Redirects are not followed. A 3xx is a permanent drop. The URL in the alertfile is where the signed body goes; following a redirect would move it — signature, hook identity and all — to a host you never named, and the useful targets for that are exactly the ones you cannot see: a cloud metadata endpoint, an RFC1918 admin port, the node's own RPC. If your receiver moves, update the alertfile.

• Bounded queue. A hook that falls far enough behind drops events. They are counted in satd_alertwebhook_dropped_total and logged; nothing is held for later and nothing is inserted into the stream to tell the receiver.

• Nothing reaches consensus. Deliveries run on the isolated API runtime and the event fan-in never blocks, so a stalled endpoint cannot affect block connection. Measured on a regtest node connecting 20 blocks: 11.23 ms with no webhook configured, 11.24 ms with every event going to a receiver that accepts the connection and never answers.

• Best-effort, and that is the whole contract. Nothing is persisted. A webhook fires when something happens and is retried while your endpoint is briefly unreachable; that is all it promises. A node that was down did not deliver those events and will not go back for them — when it comes up, its hooks resume at the live head. Health alerts are the exception, and they get it for free: the detectors re-evaluate at startup and re-raise anything still true (see Durability above), so a standing problem still reaches you.

  If you need guaranteed delivery, resumability across downtime, or history, use the Streaming Consumption API. That is the recommended way to integrate with satd and it does all three properly — real cursors, backpressure, and a bounded RescanBlocks. Webhooks are for automation you are happy to miss occasionally: page me, poke a script, ping a dead-man's switch.

• chain alerts are suppressed during initial block download. A node syncing from scratch does not POST its entire block history. status, heartbeat and mempool keep flowing: health alerts stay live because "this node is unhealthy" is exactly as true mid-sync, and the heartbeat keeps flowing so an external dead-man's switch does not declare a syncing node dead. Note the consequence for mempool hooks — a mainnet mempool subscription is thousands of events a minute, and a multi-day sync does not quiet it. What was suppressed is counted in satd_alertwebhook_dropped_total. The suppression is latched on leaving IBD once, so a node whose tip later goes stale keeps alerting — which is the whole point of a stalled-tip alert.

Plaintext http:// is accepted for loopback and private-network targets. For a public host, use https:// or set allow_insecure_http = true on the hook.

Per-hook counters are exported: satd_alertwebhook_delivered_total, _failed_attempts_total, _dropped_total (events lost, not held — there is no dead-letter queue), _queue_depth, and _last_success_age_seconds, all labelled hook="<id>". Nothing is exported when no hook is configured.

Writing a receiver

A receiver is an HTTP endpoint that verifies the signature and acts. What it does with an alert — page someone, open a ticket, forward to a push service, or just log it — is yours to decide; satd's job ends at the delivery.

Two things are worth getting right, and both are covered with test vectors in the webhook reference:

1. Verify X-Satd-Signature over the raw body, in constant time, before parsing. Key order and whitespace are part of the signed bytes, so a re-serialized body will not verify — and parsing unauthenticated input is the thing to avoid.
2. Deduplicate on X-Satd-Delivery. satd retries, so the same id arrives again whenever a response is lost after you already acted on it. The id is inside the signature, so a forged one cannot poison your dedup window.

A condition and its later recovery share a collapse_id, so a receiver that surfaces alerts to a human can replace the alert with its recovery rather than stacking a second message beneath it.

Note. The older reorgwebhook= / reorgwebhooksecret= keys still work and are now served by this dispatcher, with their original ReorgRecord payload and v1 body-only signature unchanged.

One behavior did change: redirects are no longer followed. A receiver that answers 301/302 — an http→https proxy hop, a trailing-slash redirect, a load balancer that relocates — used to be chased and now classifies as a permanent drop. If your reorg endpoint relies on a redirect, point reorgwebhook= at the final URL; otherwise every reorg record is silently discarded. Everything else about the payload and signature is byte-identical, so a receiver on a stable URL needs no edits.

New deployments should prefer an alertfile hook with categories = ["chain"], which delivers the standard event envelope.

Structured JSON Logging

satd logs to stdout. Use --log-format=json to switch from the text format to structured, machine-parseable JSON in place of a traditional debug.log stream. The JSON output feeds Datadog, ELK, or custom log-alerting pipelines directly. Trace IDs let an operator follow a single block through prefetch, connect, and flush.

• Flag: --log-format=json|text

Reorg Notifications

satd records every reorg it performs, so exchanges and custodians can read reorg history from the node instead of reconstructing it externally.

• Persistent log. An append-only JSONL log at $datadir/<network>/reorg.log, the network-specific datadir subdirectory. The log sits directly under $datadir only on mainnet. It survives restarts and is backed by an in-memory 256-record ring.
• Query method. getreorghistory [since_secs] returns recent reorgs.
• Webhook. Use --reorg-webhook=<url> to send an HTTP POST on each reorg. Set --reorg-webhook-secret=<secret> to have satd sign the body with HMAC-SHA256 in an X-Satd-Signature: sha256=... header, which the receiver can use to verify integrity.

Difference from Bitcoin Core. Core's getchaintips reflects only the currently known tips; a reorg that happened yesterday leaves no record. satd persists reorg history natively.

Configuration, Tuning & Reload

satd reads Bitcoin Core's bitcoin.conf syntax and CLI flag names directly, so an existing Core config drops in and starts the node. Commonly used options are honored, with semantics pinned to Core v30. A recognized option that satd does not implement is skipped with a startup warning rather than aborting. See the Configuration Flag Reference for the exact disposition of every key.

On top of that compatibility, satd adds hardware-profile presets, a set of mempool policy options under direct operator control, and live reload of both configuration (SIGHUP) and TLS certificates (SIGUSR1).

Repeated options follow Core's rule, which differs by source: an option given twice on the command line takes the last value, while the same key repeated in bitcoin.conf takes the first. Core's own comment calls this asymmetry a backwards-compatibility quirk, but tooling depends on it — the command-line rule is what lets a wrapper append an override onto a base command line. Options that are genuinely repeatable (bind, connect, addnode, whitebind, rpcallowip, …) accumulate instead of overriding.

Related chapters: Observability & Metrics for the TUI, Prometheus, and structured logs; JSON-RPC Extensions for the satd-specific developer APIs; API Scaling & Runtimes for the two-runtime model and the --api-threads and admission-control options. The Configuration Flag Reference indexes every flag with its default, its reload disposition, and whether it is Core-compatible or a satd extension.

Configuration & Tuning

--profile Presets

The --profile=<preset> flag replaces manual tuning of -dbcache, -maxmempool, and connection limits with a single choice of hardware profile:

• archival: maximizes indexing and P2P serving. Disables pruning.
• pruned-home: fits Raspberry Pi and home servers. Enables pruning and bounds memory.
• mining: optimizes block template generation latency.
• regtest-dev: fast, isolated environment for local development.

Indexing & Protocol Flags

Mempool Policy Sovereignty

The operator decides what the node's hardware validates and relays. satd exposes these policies as ordinary options, where filtering spam or unwanted data with Bitcoin Core requires a patched fork such as Bitcoin Knots:

Live Config Reload (SIGHUP)

Edit bitcoin.conf, then send SIGHUP with kill -HUP <pid> or systemctl reload satd. satd re-reads the file and applies the hot-reloadable options without restarting. The P2P swarm and chainstate are untouched.

CLI flags remain authoritative across reloads. Only the config file is re-read, so a flag passed on the command line always wins over the same key in the file.

Difference from Bitcoin Core. Core uses SIGHUP to reopen debug.log for logrotate. satd has no debug.log: it logs to stdout and leaves rotation and retention to systemd-journald or the container runtime, so SIGHUP is repurposed for config reload. See CORE_DIFFERENCES.md.

A reload that fails to parse, such as a typo or an invalid value, is logged and the running config is kept; satd never exits on a bad reload. A recognized-but-unsupported Core option is skipped with a warning, not an error. Every change is either applied live or logged as restart required; nothing is silently ignored. Secret-bearing keys (rpcuser, rpcpassword, rpcauth, torpassword, esplorauserpass, reorgwebhooksecret) report only that they changed. Their values are redacted in the log, never printed.

Hot-reloadable keys (applied live)

Note. logformat (json vs text) is not hot-reloadable; only verbosity is. Changing the format requires a restart.

Warning. Removing rpcuser/rpcpassword from a node started with a static user/pass (that is, without a cookie) leaves no credentials at all. The RPC interface then rejects everything until you restore a credential or restart; a restart regenerates the cookie. satd logs a warning when a reload lands in this state. The cookie file (rpccookiefile/rpccookieperms) and the rpcdisableauth mTLS option remain restart-only.

Restart required (reported, not applied)

The following are wired into long-lived state at startup, such as a bound socket, an opened database, or the chain identity. They cannot be swapped without restarting the relevant socket, engine, or process:

• network selection
• datadir and blocksdir
• all RPC, P2P, Esplora, and Electrum ports and binds
• the RPC cookie file (rpccookiefile/rpccookieperms) and rpcdisableauth
• TLS/mTLS paths and the mTLS CA (the cert and key contents reload via SIGUSR1; see below)
• dbcache, prune, storageprofile, and reindex
• index enable/disable (txindex/addressindex/blockfilterindex)
• DNS-seed bootstrap (dns/dnsseed/forcednsseed/fixedseeds/asmap)
• Tor (proxy/onion/torcontrol/listenonion)
• consensus
• assumevalid and stopatheight
• uacomment — the user agent is sent once per connection, in the version message, so a change reaches a peer only on a new connection

Live TLS Certificate Reload (SIGUSR1)

Send SIGUSR1 with kill -USR1 <pid> to reload the TLS server certificates from their already-configured paths (rpctlscert/rpctlskey, esploratlscert/esploratlskey, electrumtlscert/electrumtlskey) without restarting. Every TLS surface re-reads its leaf cert and key from disk and swaps them in atomically.

This exists for infrastructure that auto-rotates certificates on short TTLs: cert-manager, Vault, ACME sidecars. Point a renewal hook, or a systemd path unit watching the cert file, at kill -USR1.

• New handshakes use the new cert. In-flight connections keep theirs, so no connections drop and no socket rebinds.
• Only the leaf cert and key reload. Changing the cert or key paths, or rotating the mTLS client CA (rpcmtlsclientca and friends), still requires a restart. CAs are long-lived and do not rotate on the short TTLs this signal targets.
• A reload that fails, whether unreadable, malformed, or a cert/key pair that does not match, is logged per surface and the previous, still-valid certificate is kept. The listener is never left without a usable cert. Each surface reloads independently; one failure does not affect the others.
• Cert rotation is frequent and automation-driven, so it gets a dedicated signal distinct from SIGHUP. SIGUSR1 does not re-read bitcoin.conf and does not run the config diff/apply machinery.

Difference from Bitcoin Core. Core has no SIGUSR1 handler and no native TLS; its RPC is HTTP-only behind a sidecar. satd's native TLS makes in-place cert reload meaningful. See CORE_DIFFERENCES.md.

Transaction-Filtering Policy

satd ships an optional transaction-filtering policy language, total and statically cost-bounded. It lets an operator describe transaction shapes to withhold: from relay, from block templates, or both. It never changes what the node accepts as valid.

The principle to understand first: filtering cannot prevent confirmation; it can only decline to assist it.

Note. This chapter is for operators. For the architecture, the quarantine data model, the invariants, the cost and fuel system, and the reasoning behind the quarantine-only stance, see satd-policy/DESIGN.md.

A transaction shape with real economic demand will confirm through other relay paths or direct miner submission, whatever your policy says. Policy gives you a local, reversible, observable way to decline to help. The observability surfaces below let you watch filtered transactions confirm anyway, block after block, in your own data. That ceiling is what keeps filtering an operator preference rather than an illusion of control.

The quarantine model

There is no reject. Every verdict is quarantine (hold the transaction back along a scope) or allow (an explicit exemption). A transaction that matches no rule is acting: relayed and mineable, exactly as without a policy.

• Acting class: fully assisted. Relayed to peers, served on request, selected into block templates, and visible on every standard surface.
• Quarantine class: held in the same physical mempool but withheld along a scope:
  • relay: not announced, not served, not in BIP35 mempool replies, not rebroadcast. The transaction is still held, so it can be promoted later without loss.
  • template: not selected into block templates and not counted by fee estimation, but still relayed. This scope means "relay neutrally, decline to mine."
  • both: withheld from everything. A bare quarantine defaults to this.

Consensus is untouched by construction: quarantine changes relay and template assistance, never validity. A block containing a quarantined transaction still validates and connects normally.

Rules, first-match-wins, and infectious propagation

A policy file is a version 1 declaration followed by rules. Each rule is quarantine <name> [on <scope>] when <condition> or allow <name> when <condition>. Rules are evaluated top to bottom and the first match wins. Put exceptions first.

• allow shields a matching transaction from all later quarantine rules. Use it when the whole transaction is yours or trusted. For a narrow carve-out ("spare this one output class"), put a condition inside the matching expression instead; see the cookbook's dust-storm rule. allow is also capped to the standardness set: it can forgive standardness relay checks, never consensus.
• A transaction inherits the union of its quarantined in-mempool ancestors' scopes (infectious propagation): the node will not announce or mine a child whose parent it withholds. This is automatic.

Configuration and reload

Point the node at a policy file with the policyfile=/path/to/policy.txt config key or the -policyfile flag. The path must be absolute. On startup, a bad file is fatal. A file that trips the Lightning-enforcement danger gate (below) is also fatal, unless allowdangerousfilters=1.

The file is live-reloadable on SIGHUP. Every signal re-reads and recompiles the contents, even if the path is unchanged. The whole mempool is then re-placed synchronously (promote, demote, evict), and promoted transactions are re-announced on a bounded drain. A reload that fails to compile keeps the last-good ruleset and logs the error; there is never a partial apply. To drop the engine entirely and promote everything back to acting, remove policyfile= and reload. Re-placement changes only placement, never validity, so a reload is lossless apart from ordinary budget eviction.

The quarantine class has its own byte budget, the quarantinemempool=<MB> config key (megabytes, default 50). It is accounted and fee-rate-evicted separately from the acting mempool, so neither class can crowd the other out.

Lint a policy file offline before you deploy it:

sat-cli policylint /path/to/policy.txt          # parse, typecheck, cost report
sat-cli policylint --explain /path/to/policy.txt # plain-English rendering per rule

policylint reports L2 safety in two tiers. The advisory tier never blocks; silence it with --no-advisories. It flags rules that mention time-sensitive Lightning and L2 shapes: anchor outputs, witness-size caps, OP_CSV and OP_CLTV. The danger gate is stricter. It evaluates each rule against synthetic Lightning enforcement transactions and reports the rules that quarantine one. A rule that would withhold relay for an enforcement shape makes policylint exit non-zero (code 3) and makes the node refuse to load the policy. That refusal is the default. An on template match warns but does not block, because the transaction still relays.

The danger gate and allowdangerousfilters

The gate exists because a too-broad relay filter can degrade Lightning enforcement network-wide (E1, below), and that failure is silent for the user whose justice transaction never confirms. Detection mirrors the protocols. BOLT-3 legacy and anchor enforcement scripts are spec-mandated, so they are matched exactly. A taproot-channel key-path force-close is indistinguishable from any P2TR key-path spend, so a rule broad enough to catch generic P2TR keyspends is flagged as sweeping them. Taproot script-path enforcement reveals a recognizable tapleaf.

To run such a rule deliberately, set allowdangerousfilters=1 (config key or flag). The rule then loads with a loud warning instead of being refused. The gate does not make E1 go away: it cannot catch a rule that snags enforcement through an angle the probes do not model, so the network-scale critique below still stands. The gate removes the most common operator mistake. For a loaded policy, getpolicyinfo reports a danger section with the findings and whether they are allowed.

Cookbook

These examples span postures on purpose. They demonstrate the language; they are not a starter policy to deploy wholesale. They share one discipline: filter on a self-identifying protocol marker or a distinctive economic shape, never on a structural feature that legitimate traffic also has. Taproot script-path spends, OP_RETURN, large witnesses, and dust all have legitimate uses, and no rule below triggers on any of them alone.

version 1

# ── Permissive: my own submissions are never filtered (allow, posture 1) ──
allow own-submissions when tx.source == rpc or tx.source == mcp

# ── Resource protection: cheap, oversized generic OP_RETURN (posture 2) ──
# Not "OP_RETURN is bad": bulk data that does not pay its way. Small markers
# (OpenTimestamps ~40B) and well-paying data both pass freely.
quarantine cheap-bulk-opreturn when
    any output (out.script_type == op_return and out.op_return_size > 83)
    and tx.fee_rate < node.min_relay_fee * 3

# ── Resource protection: dust storms, with L2 anchors carved out IN-PLACE ─
# The `!= p2a` carve-out lives inside the expression, not in an `allow`, so a
# real inscription that merely *has* a P2A output is not exempted wholesale.
quarantine dust-storm when
    count outputs (out.is_dust and out.script_type != p2a) >= 5

# ── Mine-neutral (template-only) big witness (posture 3) ─────────────────
# Relays like everyone else; excluded only from blocks this node builds.
# Zero relay impact, so a false positive cannot degrade propagation.
quarantine no-mine-big-witness on template when
    tx.total_witness_size > 100kb

# ── Restrictive content quarantine: a self-identifying marker (posture 4) ─
# Keys on the protocol's own tapleaf marker, NOT on script-path spends in
# general, so Lightning/vault/MuSig tapscript spends are untouched.
quarantine ordinals when
    any input (in.leaf_script.contains_ops(script(OP_FALSE OP_IF push(0x6f7264))))

sat-cli policylint --explain renders each of these as a sentence. Use it to audit any ruleset handed to you.

The ceiling: what precise filtering cannot reach

• Secret-keyed obfuscation. A marker keyed by something not on-chain cannot be matched without the key; only structural and economic shape remains.
• Migration to standard output types. When a protocol moves to plain P2WSH, its transactions are byte-identical to legitimate P2WSH; filtering them means filtering all of it. A structural filter has to chase each move, and every move raises the collateral floor.
• Untagged anchors. Some anchors (zk-proof anchors, for example) expose no marker. The only handle is a structural template, whose precision equals its uniqueness.

Because every verdict is quarantine rather than reject, a too-broad rule is survivable. Watch it accumulate legitimate traffic in quarantine, then fix it losslessly with one SIGHUP. Hard rejection would have made every such judgment call irreversible and invisible.

Observability

The quarantine class exists to make policy consequences visible. The quarantine view appears only on the dedicated surfaces below. Every standard mempool surface (getrawmempool, getmempoolinfo, getmempoolentry, Electrum, Esplora, the standard MCP mempool tools) presents the acting class only. To a Core-compatible client, the node behaves exactly like one whose relay policy refused the transaction. Quarantine never leaks into a Core-compatible response.

Differential tests verify that the standard surfaces and the metrics page are byte-identical whether or not the quarantine class is occupied. A node with no policy is indistinguishable from the same node before this feature existed.

Node-local consequences

Quarantine-only filtering repairs most of the collateral damage filtering does to your own node. Not all of it:

• Compact-block relay is unaffected. Quarantined transactions stay in the one physical pool, so BIP 152 reconstruction finds them with no extra round trip. Only transactions evicted from the quarantine budget cost a getblocktxn, and that cost is bounded by the budget, not by how aggressive your rules are.
• Fee estimation is scope-correct. The smart-fee simulator counts the template class only, so a transaction you quarantine on template does not inflate the fees you quote to wallets.
• Bandwidth. Peers still INV you transactions you quarantine, because no wire protocol expresses arbitrary predicates. You download each once and hold it; there is no re-download churn. Only post-eviction re-announcements cost extra fetches.
• Your own transactions. A locally submitted transaction that draws a relay-scope verdict is refused at submission with the rule named, rather than held silently. You never have an invisible transaction of your own. To override and hold it anyway, pass allowquarantined=true on the submit call; getquarantineentry is then authoritative for it.

Network-scale effects

At the consensus layer this changes nothing. A filtering supermajority of nodes and miners still cannot orphan a block containing a filtered transaction; any valid transaction confirms eventually, so long as some hashrate accepts it. But Bitcoin's practical guarantees emerge from relay-layer behavior, and wide adoption of a filtering DSL changes three real things. We publish the strongest case against wide filtering alongside the tool:

• E1: propagation predictability is load-bearing for L2 security. Lightning enforcement (justice transactions, force-close plus anchor CPFP) assumes that a sufficiently-fee'd transaction percolates to hashrate before a timelock expires. That rests on relay-policy homogeneity. A popular copy-paste ruleset whose witness-size cap or anchor rule happens to match force-close or penalty transactions can silently degrade L2 enforcement network-wide. The user whose justice transaction never confirms does not learn why. This is the critique to take most seriously. The strict-by-default danger gate (above) is a partial mitigation: it refuses, by default, the rules whose match against Lightning enforcement traffic it can prove. It does not close E1. It cannot detect a rule that catches enforcement through an angle its probes do not model, and taproot key-path force-closes are indistinguishable from ordinary P2TR spends. The gate raises the floor; it is not a guarantee.
• E2: policy-change friction was an unintentional stabilizer. Today, a mass policy shift needs a Core release or an implementation switch. A DSL plus a viral gist converts policy into a fast, memetic equilibrium with less review than a Core PR. Zero-conf acceptance died through the full-RBF policy rollout, with no consensus change required.
• E3: effective filtering feeds the miner-direct-submission loop. Every shape that stops propagating over p2p creates demand for out-of-band channels (accelerators, direct miner APIs). That shifts power to identified, pressure-able miner endpoints: weaker censorship resistance where it binds, worse submission privacy, and a moat for large miners.

A caveat on the quarantine model: from peers' perspective, a quarantining node and a hard-rejecting node are indistinguishable, because neither propagates the transaction. E1 through E3 are therefore not softened by the quarantine-only design. What quarantine changes is the local picture: collateral damage to your node is repaired, and policy consequences become visible and reversible. The filtering capability itself is exactly as strong as a hard reject.

Two structural observations are acknowledged rather than disputed. The tool is asymmetric: quarantine is unbounded while allow is capped at standardness, so at scale it is a ratchet toward more restrictive relay, never more permissive. And shipped examples become defaults, which is why the cookbook above is posture-balanced rather than an anti-data starter kit.

Initial Block Download & Fast Sync

This chapter covers getting a satd node to the chain tip: AssumeUTXO fast sync, the assumevalid script-verification skip options, dual-engine shadow verification, and the IBD performance and storage tuning flags. Points that differ from Bitcoin Core are called out throughout.

For the per-key table of defaults, reload disposition, and Core-vs-satd status, see the Configuration Flag Reference. This chapter explains how the pieces work and when to use them.

How satd syncs: the IBD pipeline

satd does not download and verify blocks one at a time in lockstep. IBD is a pipeline that keeps the network, the disk, and the CPU busy at the same time.

• Parallel block download. satd fetches blocks from many peers at once, the way BitTorrent downloads pieces from a swarm. Download throughput scales with aggregate peer bandwidth instead of one peer's round-trip time. -maxahead bounds how far ahead of the connect tip downloaded blocks may be staged.
• Background prefetch workers. -prefetchworkers threads pre-read blocks from the flat files without holding the chainstate lock. They deserialize each block, compute txids, run the context-free transaction validation, and resolve the block's UTXO inputs into the coin cache. All of this happens off the connect thread. When the connect thread reaches a block, its inputs are already cached.
• Speculative script verification. Prefetch workers verify scripts ahead of connection and mark the transactions they verified. The connect thread does not verify them again. In assumevalid mode, the connect step can then go straight to applying UTXO changes for the trusted range.
• Asynchronous shadow verification. The second consensus engine (see below) runs on its own worker pool, never on the connect path. It adds almost no wall-clock cost.

Network I/O, block pre-processing, script verification, and chainstate writes overlap instead of running one after another.

AssumeUTXO fast sync

AssumeUTXO makes a node usable in minutes instead of days. The node loads a UTXO-set snapshot at a recent height and serves wallets and queries from it immediately. It validates the historical chain from genesis to the snapshot in the background. satd's implementation is shipped and Bitcoin Core-compatible.

Loading a snapshot

• loadtxoutset <path> (RPC) loads a UTXO snapshot file. The node then holds two chainstates. The snapshot chainstate becomes the active tip; wallets, Esplora, Electrum, and RPC serve from it immediately. A background chainstate validates from genesis up to the snapshot's anchor. When background validation completes, the snapshot is marked validated and the node is a normal fully-validated node.
• --fast-start=<url|path> (startup flag) automates the sequence. satd downloads the snapshot (or reads a local file), waits for header sync to reach the snapshot's anchor, and calls loadtxoutset itself. Remote sources must be https://; plain http:// is refused, and TLS certificates are verified. Use --fast-start-sha256=<hex> to pin the download's digest. Download progress appears in the pre-RPC startup TUI gauge.
• getchainstates (RPC, Core 27+ compatible) reports progress. A node with no snapshot reports a single fully-validated chainstate. After loadtxoutset it reports a second, background chainstate, and the snapshot entry carries snapshot_blockhash and validated: false until background validation finishes.
• dumptxoutset <path> (RPC) writes a Bitcoin Core-compatible UTXO snapshot from your own node.

Trust model

At load, satd verifies the snapshot file against a hardcoded anchor hash. A tampered or wrong-height snapshot is rejected no matter where it came from. satd hosts no snapshots and does no P2P snapshot fetch; the operator names a trusted https:// source or a local file. The historical chain is still fully validated in the background. AssumeUTXO shortens the time to a usable node; it does not skip validation.

Difference from Bitcoin Core. The RPCs (loadtxoutset, getchainstates, dumptxoutset) and the two-chainstate model match Core. The --fast-start download-verify-load flag and --fast-start-sha256 are satd extensions. Core requires a manual loadtxoutset against a file you fetched yourself.

Where to get a snapshot

satd hosts none, and does not name one for you. The anchors compiled into the binary decide which snapshots are loadable at all — currently mainnet heights 840,000, 880,000, 910,000 and 935,000, copied verbatim from Bitcoin Core's m_assumeutxo_data. Signet, testnet and regtest have no anchors, so fast-start is mainnet-only.

Several people publish the utxo-<height>.dat files Core's dumptxoutset produces; Jameson Lopp's mirror and https://bitcoin-snapshots.jaonoctus.dev/ are two that have been around a while. Any of them will do, because the host is trusted for availability only:

satd --fast-start=https://<host>/utxo-880000.dat \
     --fast-start-sha256=<sha256 of that file>

--fast-start-sha256 pins what you downloaded, so a truncated or swapped file fails before it is parsed. That check is a convenience; the one that matters is the anchor comparison above, which satd performs against a hash compiled into the binary and which no snapshot host can influence. A snapshot from a hostile mirror is rejected at load.

Pick the highest anchor height a published snapshot exists for: the higher the base, the less history the background validation has left to walk.

--fast-start-sha256 is the file's SHA-256, not the anchor hash. hash_serialized_3 in the anchor table is a hash over the UTXO set, not over the file; sha256sum utxo-880000.dat does not produce it. Take the file digest from the publisher, or compute it after downloading once.

Script-verification skip: assumevalid

-assumevalid controls how much script verification IBD performs. satd accepts three forms. The third is a satd extension.

Difference from Bitcoin Core. Core's -assumevalid takes a block hash or 0. satd adds the all keyword and -assumevalidage, which trust the deep chain and verify the last day without pinning a hash. This suits recurring fast re-syncs. assumevalid is independent of AssumeUTXO, which concerns the UTXO set rather than script verification; the two compose.

Consensus engine & shadow verification

satd ships two independent script-verification engines: the C++ libbitcoinconsensus FFI and a from-scratch Rust verifier. It can run both together and verify every script twice. Bitcoin Core has no equivalent.

Read a mode name as "which engine is the shadow". In <engine>-shadow, the named engine is the shadow, the non-authoritative one. The other engine is primary; its verdict is what the node acts on. The shadow re-verifies in the background and logs any disagreement. So:

• rust-shadow: the Rust engine is the shadow; C++ is primary.
• cpp-shadow: the C++ engine is the shadow; Rust is primary.

-consensus=<mode>:

The Rust engine passes Bitcoin Core's script test suite. Shadow verification against libbitcoinconsensus across the whole mainnet chain, genesis to about height 945,000, found zero divergence. The Rust engine is also usually faster than the C++ FFI: it avoids per-call FFI marshaling and uses a process-global, verification-only cached secp256k1 context. cpp-shadow (Rust primary, C++ shadow) is therefore the high-performance pairing.

rust-shadow (C++ primary) stays the default out of conservatism. Running two independently written engines against each other is satd's core safety property, and libbitcoinconsensus is the most widely deployed implementation. The plan is to promote the Rust engine to primary as it accumulates production mileage; cpp-shadow is that step. Treat the single-engine rust mode with care. The engine itself is proven, but either single-engine mode gives up the dual-engine cross-verification. satd prints a caution at startup when the single-engine rust mode is selected.

The shadow engine runs on a bounded background worker pool, so it consumes spare CPU without slowing block connection. Two flags tune it:

• -shadowworkers=<n> (default 4): background shadow-verification threads.
• -shadowqueuesize=<n> (default 4194304): shadow work-queue capacity. When the queue is full, shadow work is dropped, and an aggregated WARN is logged at most once per 5 s. The primary engine still verifies every script, so correctness is unaffected.

Difference from Bitcoin Core. Core has a single C++ engine and no shadow mode. satd's default runs both engines at once. -consensus, -shadowworkers, and -shadowqueuesize are satd-specific.

IBD performance & storage tuning

These flags bound or accelerate IBD. Full defaults and semantics are in the Configuration Flag Reference.

-dbcache, -prune, -txindex, -assumevalid, and -reindex keep Core's names and meanings. The rest of the table is satd-specific tuning with no Core equivalent.

Reindexing

• -reindex rebuilds both the block index and the chainstate from the block files on disk (Core-compatible).
• -reindex-chainstate rebuilds only the chainstate (the UTXO set) from the existing block files, and preserves the flat block files (Core-compatible). It is faster than a full -reindex when only the chainstate is suspect.

Both work against block files written by Bitcoin Core, including the XOR-obfuscated files Core v28.0+ produces by default. The key in blocks/xor.dat is picked up automatically (see blocksxor in the Configuration Flag Reference).

A reindex on a synced mainnet node runs for hours. The shipped systemd unit handles this without tripping the start timeout; see "Reindex resilience" in Packaging.

Driving a reorg by hand

invalidateblock and reconsiderblock work as in Bitcoin Core, and reach the node through sat-cli's raw-RPC passthrough:

sat-cli invalidateblock <blockhash>
sat-cli reconsiderblock <blockhash>

They are not listed in sat-cli --help — any method --help does not name is forwarded verbatim, which is how Core-compatible tooling keeps working. That makes them easy to miss when they are the tool you need.

Invalidating drives a reorg away from the named block and everything descended from it. reconsiderblock clears the mark and re-activates the best chain.

Startup integrity checks

Before serving RPC or connecting to peers, satd checks two things about the chain it is about to present.

The height→hash index is audited for gaps at or below the tip and rebuilt in place from the tip's ancestry. It is derived state, so this is a repair and startup continues. Heights whose rows disagree with the tip's ancestry are logged but never overwritten — correcting one means choosing between branches by chainwork.

The tip's ancestry is walked back one retarget period, and every block in it must be one this chainstate actually connected. This is not repaired. A block in the tip's ancestry that was never connected means the UTXO set is missing every output it created, and the only way to recover those is to replay the block. satd reports the affected heights and exits:

FATAL: this node's UTXO set does not agree with the chain its tip claims.

  * The tip stands on 8 block(s) that were never connected.
...
Refusing to start. Rebuild the UTXO set with -reindex-chainstate.

Serving in that state is worse than not starting: the tip is a real block on the real chain, the height is correct, and gettxout answers confidently and wrongly.

Two distinct faults can be reported, and they do not share a remedy. Blocks that were never connected mean the UTXO set is missing deltas, which -reindex-chainstate rebuilds. A broken parent pointer means the block index itself is wrong; -reindex-chainstate trusts that index, so only a full -reindex fixes it. Both can be present at once, and both are printed.

The exit status is 3, distinct from the 1 used for ordinary startup failures such as a bad config key, so supervision and alerting can tell "chainstate is damaged" from "the config file has a typo" without scraping stderr. Because this never heals by restarting, the shipped units set RestartPreventExitStatus=3 alongside Restart=always; without it the node would restart every few seconds forever and the unit would never settle into failed, so unit-state alerting would never fire. If you wrote your own unit, add that line.

After a -reindex or -reindex-chainstate, the audit runs again against what the replay actually rebuilt — a replay that stops short or reproduces the hole fails the same way, in the same run, rather than serving until the next restart.

On a pruned node none of these remedies can replay the missing blocks, because the block data is gone. satd says so rather than naming a remedy that cannot work: fetch the affected heights from a peer with getblockfrompeer and repair them, or resync.

On an AssumeUTXO node the history below the snapshot base is legitimately unvalidated until the background chainstate reaches it. That is recognised and logged at INFO, not treated as damage.

Auditing a suspect datadir offline

satd-chainstate-audit answers the question the startup checks cannot afford to: does the UTXO set actually agree with the blocks on the active chain? It walks the tip's ancestry, reads each block back from the flat files, and reports every disagreement — coins that should exist and do not, spent coins still present, height-index rows naming the wrong block, txindex rows pointing at the wrong block, cumulative transaction counts that do not follow from their parent.

satd-chainstate-audit --datadir /path/to/datadir
satd-chainstate-audit --datadir /path/to/datadir --window 20000 --verbose

It takes the RocksDB lock, so the node must be stopped.

It issues no writes of its own, but it is not non-mutating: opening the chainstate opens RocksDB read-write, so the WAL is replayed and truncated, memtables may flush and compact, the MANIFEST is rewritten, obsolete files are deleted, any missing column family is created, the legacy address-history column families are dropped, and the schema version is stamped — after which an older satd will no longer open that datadir. Opening the block files creates xor.dat if absent. If the datadir is evidence — which is the case this tool exists for — copy it and audit the copy. The tool prints this warning on every run.

Note also that it is not included in the release tarballs or the Docker image; build it from source (cargo build --release --bin satd-chainstate-audit).

Exit status is 0 when consistent, 1 when it could not run, 2 when it found inconsistencies, so it scripts cleanly.

It diagnoses and does not repair. A missing coin is recoverable only by replaying the block that created it: -reindex-chainstate, or satd-chainstate-repair for a single block's lost delta. A broken parent pointer is a block index fault and needs -reindex — -reindex-chainstate trusts the same block index and cannot fix it.

--window bounds the walk, and its cost is not only one block read per height: every output the window creates and every outpoint it spends is held in memory until the end, so the default already runs to roughly a gigabyte on mainnet and tens of thousands of blocks runs to many. Start at the default and widen only as far as the search needs.

There is no --txindex flag: the tool reads the answer out of the datadir. An absent txindex row counts as a fault only when the chainstate's own completeness marker says the index was fully built, which rules out both shapes that would otherwise produce a false alarm — a node that does not run -txindex at all (satd's default), and one where -txindex=1 was switched on after the chain had already synced without it, leaving every historical block without a row it was never going to have. In that second case the audit says the rows went unchecked rather than counting them clean, because "not looked at" and "looked at and fine" are different answers.

This used to be a flag, and it was wrong in both directions. It defaulted to true while satd's -txindex defaults to off, so the invocation the node itself prints reported every transaction in the window as a missing row and exited 2 against a perfectly healthy node; and passing false silently disabled the txindex checks altogether, so a genuinely broken index came back consistent. An auditor cannot be expected to know a stranger's -txindex setting, and now does not have to.

Two states are reported but are not faults. Blocks the node pruned are counted separately from blocks that could not be read: pruning deletes block data deliberately, and treating that as damage would fail every healthy pruned node — at the default window, for most of the range — and then recommend -reindex-chainstate, which a pruned node refuses outright. On an AssumeUTXO node the snapshot base is read from the background chainstate's marker, so history below it is reported as not-yet-validated rather than as a hole.

Where a block could not be read, for either reason, the coin checks are skipped at and below that height — its spends are unknown, so a coin it spent would otherwise look missing. The tool prints a note when this applies. Verdicts above that height are unaffected: the walk runs newest-first, and a coin created at height H can only be spent at or above H.

Differences from Bitcoin Core at a glance

• assumevalid=all with assumevalidage: verify-recent-only mode. Core takes a hash or 0.
• Dual-engine shadow verification (-consensus, -shadowworkers, -shadowqueuesize): the default runs the C++ and Rust engines together. Core has one engine.
• --fast-start / --fast-start-sha256: one-flag AssumeUTXO download-verify-load. Core requires a manual loadtxoutset.
• -dbcache=auto: adaptive cache sizing. Core's is static.
• satd-only IBD and storage options: -prefetchworkers, -maxahead, -storageprofile, -maxopenfiles, the -rocksdb* and -compaction* families, -ibdl0pauseat, and the stall watchdog.
• -par is accepted for config compatibility. It does not size the connect path, but a positive value feeds -shadowworkers when that flag is unset.

Disk Footprint & Indices

A fully-indexed satd node (-txindex=1 -addressindex=1 -blockfilterindex=basic) uses more disk for its indices than a bitcoind + electrs/Fulcrum + esplora stack uses in total. This is by design. This chapter explains where the bytes go and what they pay for.

If you only need a validating node, none of this applies. A consensus-only satd (-txindex=0 -addressindex=0, filters off) has a chainstate comparable to Core's and carries none of the index column families below.

Where the bytes go

satd keeps everything in one RocksDB with multiple column families (CFs). The indices are append-mostly: rows are added as blocks connect and removed only on disconnect during a reorg, so no tombstone debt accumulates over time.

The on-disk column is measured, not estimated. It comes from the per-CF SST totals of one fully-indexed mainnet node in August 2026, at height 963,000 with txindex, addressindex and silentpaymentindex all on. Your numbers track the chain's growth.

The three address/txid indices plus outpoint_spend are the bulk. Two rows often surprise operators. undo is not a rolling window: satd keeps the disconnect data for every block, so it grows with the chain. coins is the live UTXO set, which is served from the in-memory coin cache but still serializes to several GB.

The filter row is the one figure here that is still an estimate. The measured node does not run blockfilterindex.

Note. During a -reindex or -reindex-chainstate, RocksDB compaction falls behind the write rate, so tx_index in particular can read much larger than its settled size (uncompacted L0 SSTs, bloom filters, and index blocks). Measure the per-CF footprint after the node has idled and background compaction has drained; see Compaction.

Why it is larger than bitcoind + electrs + esplora

Three structural reasons.

1. satd stores the spend graph in both directions

Every spend writes two rows:

• addr_spending_v2, keyed by script (scripthash ‖ height ‖ …). It answers "show me everything address A spent."
• outpoint_spend, keyed by outpoint (prev_txid ‖ vout). It answers "what input spent this UTXO" in a single keyed read.

electrs and Fulcrum keep one spend representation and derive the other direction on demand. satd spends the disk to keep both materialized, so both queries are O(1). This duplication is internal and intentional, and it is the largest source of the overage.

2. satd indexes a superset of what any one external tool does

The often-quoted "30–180 GB" figure is the electrs/Fulcrum address index alone. satd's address index alone (addr_funding + addr_spending) already exceeds that range. satd also carries a Core-style tx_index, an outpoint_spend reverse index, and BIP 158 filters in the same database, because one binary serves Electrum, Esplora, getrawtransaction, and compact-filter clients. So compare satd's indices to electrs plus Core's txindex plus a spend index plus a filter index, fused into one store.

3. satd trades pointer compactness for self-containment

tx_index stores the full 32-byte block hash as its value, where Core's txindex stores an on-disk position (CDiskTxPos) of about 12 bytes. That costs about 20 extra bytes per transaction, roughly 24 GB across the chain, and one extra indirection on read. In exchange, the index is independent of block-file layout and survives block-file re-packing. satd's keys are also fixed-width binary tuned for prefix seeks rather than byte-minimal, which costs a little space and speeds up range scans.

What satd already does to keep the footprint down

The schema is close to the smallest encoding of what it indexes:

• 16-byte scripthash prefix, not 32. Address rows key on the first half of sha256(scriptPubKey), which halves the dominant field of every address row. Collisions are extremely unlikely and are resolved against the full script on read.
• Varint-packed UTXOs. The coins CF uses a compact varint encoding, about 28 B typical against about 43 B for a naive struct.
• Fixed-width keys, no delimiters. Heights are big-endian, so range scans return rows in chain order with no secondary sort.

The size is row_count × ~70 B, and row_count is every output and every spend in Bitcoin's history. The footprint is data, not per-row overhead.

What the disk buys you

The disk pays for consistency and a single process to operate. A read on any surface (Electrum, Esplora, JSON-RPC) can never observe an index out of sync with the chain tip, because there is no second copy to fall behind. To scale read throughput, run more nodes rather than more index processes; see API Scaling & Runtimes.

Choosing what to index

The indices are opt-in per surface. Match the disk to what you serve:

When a surface is off, its CF is never written and the disk is never spent.

Silent-payment index

sp_tweaks holds one BIP 352 public tweak per eligible transaction, grouped into one row per block. The silentpaymentindex option enables it, and it is off by default. Two surfaces read it: the streaming tweaks firehose and index-accelerated scan-key-watch rescans; the integrator guide for both is Silent Payments (BIP 352).

The index starts at taproot activation, not at genesis, because pre-taproot blocks carry no silent payments. Each indexed block writes a row even with no eligible transaction, so an empty row means "indexed, none" rather than "not indexed". Every row embeds the hash of the block it describes, so a reader authenticates it without the height-to-hash index.

A node that syncs from genesis with the option set builds the index inline. To add the index to an existing datadir, run a backfill:

sat-cli backfillindex silentpayment

The backfill walks from taproot activation to the snapshot height it pinned at start, and resumes across a restart. getsatdindexinfo reports a silentpayments section with the synced flag and the backfill progress, including a backfill.progress_ratio field. Progress is measured across that walked span, not from genesis, so it starts near zero rather than near the fraction of the chain that predates taproot — use the reported ratio rather than dividing cursor_height by snapshot_height, which measures from genesis.

estimated_remaining_seconds is reported only while a backfill is both enabled and running. A paused, cancelled, failed or disabled cursor reports 0 — its progress is frozen while elapsed wall-clock keeps growing, so any estimate derived from it would grow without bound for as long as the node stays up.

The estimate is measured over the current stint — the uninterrupted span since the running backfill last started walking blocks. It is not an average over the life of the job. Two consequences worth knowing:

• Time the backfill was not working is never counted. Pause it for two days and resume, or stop the daemon for a week and restart, and the estimate reflects the throughput it is achieving now, not the idle time in between.
• The estimate is unavailable for the first few seconds after a start, a resume, or a daemon restart, and reads 0 until the new stint has measured something. 0 here means "no estimate yet", not "nearly done"; the state and cursor_height fields are the ones to watch during that window.

This applies to all three backfills (address, basic block filter index, silentpayments) — they share one estimator.

Until a backfill completes, the tweak-serving surfaces refuse a request rather than return a partial result.

Size and backfill time

The figures here are measurements from a synced mainnet node, taken in August 2026 over heights 709,632 to 962,151. That span is 252,520 blocks, holding 187,015,795 tweak entries.

A transaction is eligible when it pays a taproot output and has at least one input whose public key the protocol can recover. Recoverable inputs are P2PKH, P2WPKH, P2SH-P2WPKH and key-path P2TR. A transaction funded only by P2WSH, bare multisig or script-path P2TR pays taproot and indexes nothing. Measured against the index, about 98% of taproot-paying transactions across the era are eligible.

The era mean is far above the recent rate. Blocks from the 2023 and 2024 inscription period average about a thousand eligible transactions, and the busiest carry several thousand. A return to that transaction pattern raises the growth rate again.

The backfill ran while the node stayed at the tip and served its other surfaces. It is bound by CPU rather than by disk. The walk does one elliptic curve multiplication per eligible transaction. Its measured throughput tracks the eligible-transaction count, not the block size, and roughly 70% of that 6 h 46 m was per-transaction work.

Note. A datadir where a backfill was interrupted and restarted can read larger than the figure above until compaction reclaims the superseded rows. The node measured here read about 15 GB for a 13 GB index for that reason.

Note. A tweak_dust_limit on a subscription drops entries whose largest taproot output is below the limit. It filters less than its name suggests. At 330 sat, the dust threshold for a taproot output, it removes nothing measurable. At 546 sat it removes about 10%, and at 0.001 BTC about two thirds. The limit reduces the bandwidth a subscription uses. It does not reduce the index on disk.

Repairing lost block data

Block bodies live in the flat files under blocks/ (blk*.dat), not in RocksDB. The block_index entry for a block records which file and offset its record starts at. Those are two independently buffered write streams, so it is possible — after a kernel panic or power loss, never after a clean shutdown or a plain process crash — to end up with an index entry that survived while the block bytes it points at did not.

The symptom is a single block that behaves as if it were pruned on a node that is not pruning:

$ sat-cli getblock 000000000000000000000b951399b504a52a3fdfa1d33bcde59ac6c019c4af1c 0
error code: -5: Block data not available

getblockheader still works and shows the block connected with a normal confirmation count, because consensus never re-reads the body: the UTXO delta was applied when the block connected. Nothing surfaces the hole until something walks history — an index backfill fails at that height, or a peer's request for the block cannot be served.

Fetch a fresh copy of just that block from a peer:

sat-cli getblockfrompeer <blockhash>          # satd picks a peer
sat-cli getblockfrompeer <blockhash> <peer_id>  # or name one from `getpeerinfo`

The call returns as soon as the request is sent; the repair happens when the block arrives. Re-run getblock to confirm, and check the log for Repaired block data from a peer-supplied copy.

The supplied block is authenticated before anything is written. Its hash must match a header already in the index — which is what carries the proof-of-work and difficulty checks made when that header was accepted — and its transactions must match the merkle root that hash commits to. Witnesses need their own chain, because the merkle root commits only to txids: when the coinbase carries a BIP 141 commitment it must hold exactly one 32-byte witness item and the commitment must verify; otherwise no transaction may carry witness data at all. Together those pin every byte, so a peer can only return the genuine block or be rejected. A peer whose reply fails is banned.

The same test decides whether there is anything to repair. A stored copy is left alone only if it is the canonical block, not merely one that parses — witness bytes are outside everything the block hash commits to, so a copy can deserialize and hash correctly while still carrying a padded, truncated or stripped witness. getblockfrompeer will replace such a copy; getblock on it succeeds, so nothing else would ever surface it.

Blocks that are pruned or marked invalid are refused: those states are deliberate, and repopulating them would contradict the decision that produced them. A block you hold only the header for is not repaired either — it is downloaded through the normal path, which applies the checkpoint and signet checks and connects it.

To find holes ahead of time rather than discovering them through a failed backfill, use the block-file audit:

sat-cli debug blockfile-audit

It reports unresolved_entries for index entries whose record falls past the end of its file, in one pass over the file metadata — as opposed to getblockstats across every height, which reads and deserializes every block body on the chain and cannot distinguish a data hole from an unknown block (both return -5).

Note. satd fsyncs a block's record before its index entry is committed on every write path, so the window above is closed for blocks written by current versions. Datadirs that predate this may still carry a hole from an earlier crash; nothing audits or migrates them on upgrade.

Compaction

RocksDB background compaction runs continuously. satd's bulk-load reindex mode does not disable it; only the WAL is disabled. When reindex writes stop, the background jobs drain the L0 backlog on their own, with no manual step. satd also force-compacts the coins CF on a timer (compaction_interval_secs, default 30 min, L0-triggered). There is no satd-level forced full compaction of the large index CFs; they rely on RocksDB auto-compaction.

The index CFs are append-mostly, with little deletion outside reorgs. Expect compaction to reclaim the reindex-era L0 and overlap debt: a moderate drop, not a collapse, because most of the footprint is index data. satd logs a per-CF pending-compaction-bytes diagnostic every compaction_diag_interval_secs (default 60 s). Let those settle toward zero before taking a size measurement.

API Scaling & Runtimes

satd is a single process: one RocksDB instance, one chainstate, and every API surface (JSON-RPC, Esplora, Electrum, the streaming APIs, MCP, metrics) in the same process as consensus. This chapter explains how that process is split into two runtimes so that API load cannot endanger consensus. It also covers the options that tune each runtime, and how to scale out when one node is not enough.

The design goal is to bound the remotely-consumed API surfaces so they can never starve or stall the consensus core. Default behavior is unchanged and Bitcoin Core-compatible; everything in this chapter is opt-in or a bounded default.

The two runtimes

satd runs two separate tokio runtimes. The split is structural, not a priority hint.

Core (consensus) runtime

This runtime carries everything that must never be starved: P2P, block connection, and mempool acceptance. It also carries:

• The main JSON-RPC listener (-rpcport, read and write). It serves the block-connecting control methods (generate*, submitblock, submitheader, preciousblock, loadtxoutset), which must originate on the core runtime to preserve address-index and SSE event ordering. Keeping JSON-RPC here also means public API load cannot starve the admin interface.
• The MCP server. It exposes block-connecting tools (generate_blocks) and broadcast, so it stays on the core runtime for the same reason.

Isolated API runtime (--api-threads)

A separate, bounded runtime carries the read and streaming surfaces, so a flood on any of them cannot contend with the threads that connect blocks:

• Esplora REST and SSE
• the Electrum protocol server
• the events gRPC and ZMQ sinks, and the streaming WS/SSE (streamws)
• the Prometheus /metrics, /healthz, and /readyz endpoints
• the opt-in read-only JSON-RPC listener (-rpcreadonlybind)

Use --api-threads to size this pool. The default is max(2, cores/4) worker threads, clamped to 1024. Because the isolation is structural, a flood on a consumption surface cannot starve block connection or mempool acceptance. SIGHUP and SIGUSR1 reload reach the relocated surfaces unchanged.

Admission control and tuning options

Every remotely-consumed surface bounds its concurrency and backlog, and sheds work that is over budget. Nothing queues without bound; an unbounded queue would let a consumer backpressure the node. Shedding runs ahead of authentication and request-body buffering, so a flood is bounded before it does work, authenticated or not. Each option is clamped to a ceiling, so a mistyped value cannot panic satd at boot.

-rpcthreads and -rpcworkqueue are recognized from Bitcoin Core, so a Core-shaped config that carries them loads. In-flight calls are capped at -rpcthreads, and the waiting backlog at -rpcthreads + -rpcworkqueue. Per-token rate limits and watch quotas layer on top of these per-surface caps; see Authentication & Authorization.

Scaling read RPC on one node: the read-only listener

-rpcreadonlybind adds a second JSON-RPC listener on the isolated API runtime. It dispatches only read methods and mempool submission (sendrawtransaction), and rejects block-connecting and node-control methods with JSON-RPC error -32001. The method filter fails closed: an unclassified method is rejected, never served. A release-safe invariant guard asserts that block connection never originates on the API runtime.

The read-only listener has its own bind address, source-IP allowlist (-rpcreadonlyallowip), admission budget (-rpcreadonlythreads / -rpcreadonlyworkqueue), and TLS/mTLS options (-rpcreadonlytlsbind / …tlscert / …tlskey / …mtls / …mtlsclientca / …mtlsclientallow). It reuses the main listener's authentication.

To scale read traffic, put this listener behind a load balancer and keep the core-runtime listener private. The write and admin methods never leave the private listener.

Scaling beyond one node

The vertical levers above (--api-threads, the per-surface admission caps, the read-only listener behind a load balancer) scale the API surfaces up to the capacity of a single node. satd is one process over one chainstate, so there is no in-process read-replica mode. You cannot add API capacity beyond what one node's API runtime can serve.

When you need more than that, run multiple independent satd nodes behind a load balancer. Each node is a full node with its own chainstate and mempool. Together they serve more aggregate read and stream traffic than any single node can.

Clients must tolerate transient divergence between nodes

Independent nodes are eventually consistent with each other. At any instant, two nodes can differ, and a load balancer can route consecutive requests to different backends. Design clients to expect:

• Tip skew. One node may be a block (briefly more) ahead of another. getblockcount and the chain-tip height can go backwards across two requests routed to different nodes.
• Mempool divergence. A newly broadcast transaction may be visible on the node that received it but not yet on others. Fee estimates and mempool contents differ between nodes.
• Reorg timing skew. Nodes can adopt a reorg at slightly different moments, so a transaction's confirmed status and its confirmations count can differ transiently.
• Per-node streaming cursors. A streaming cursor (seq, instance_id) is only meaningful against the node that issued it. Do not resume a cursor against a different backend.

Practical guidance:

• Do not assume monotonic or read-your-writes consistency across requests that may hit different backends. Where read-your-writes matters, pin a client or session to one backend with sticky sessions: for example, submit a transaction and poll for it on the same node.
• Choose where to broadcast. Send a transaction to one chosen node, or fan it out to all, then rely on P2P propagation. Do not assume every node already has a transaction another node accepted a moment ago.
• Use confirmation thresholds rather than single-node point reads for irreversibility decisions. Confirm across nodes if you need cross-node agreement.
• Health-gate the pool. Route only to nodes that pass /readyz and are near the network tip. Drop a node that has fallen behind so it does not serve stale reads.

This is the same operational model as running multiple Bitcoin Core nodes behind a balancer. The difference is that a single satd node already isolates its API surfaces from consensus, so multiple nodes are for horizontal throughput, not for protecting a node from its own API load.

Authentication & Authorization

satd has one authentication model shared by every API surface: JSON-RPC, Esplora, the streaming APIs (events gRPC and streamws), and the MCP server. It also keeps full backward compatibility with Bitcoin Core's cookie, rpcuser, and rpcauth credentials.

There are two layers:

1. Core-compatible operator auth: the cookie file, -rpcuser/-rpcpassword, and -rpcauth. This is the default and behaves exactly like Bitcoin Core. It is all-or-nothing: a valid operator credential has full access to everything.
2. The unified bearer-token layer (satd-auth): opt-in, capability-scoped bearer tokens loaded from an -authfile, each rate-limited and quota-bounded. Scoped tokens let you expose the node to partially trusted consumers, such as a BTCPay instance or a watchtower, without giving any of them operator credentials.

Note. The default is pure Bitcoin Core behavior. With no -authfile configured, the bearer layer is inert: the only credentials that work are the Core-compatible ones, and every authenticated request acts as the full-capability operator. Scoped tokens are opt-in, per surface. A surface with no bearer tokens enabled does not install the capability gate at all.

How the bearer layer differs from Core-style auth

Both layers coexist. On a bearer-enabled surface the operator (Basic) credential is tried first, so existing Core tooling is not affected. A Bearer token is consulted only when the request does not carry a valid operator Basic credential. A matching cookie, userpass, or rpcauth credential always resolves to the full-capability operator.

Capabilities

A bearer token carries a set of capabilities, and each surface enforces the capability it requires. Enforcement fails closed: an unknown method, or a request with no principal, requires the write capability, which a read-only token does not hold.

The operator and loopback-trust principals hold all capabilities.

The authfile

-authfile=<path> points at a TOML file of bearer tokens. The file stores only the SHA-256 digest of each token, never the plaintext.

version = 1

# Read-only integration: REST + Esplora reads, rate-capped.
[[token]]
id = "btcpay"                              # logging/accounting id, not the secret
hash = "sha256:<64-hex SHA-256 of the token>"
capabilities = ["rpc:read", "esplora:read"]
watch_quota = 50000                        # optional; omit for unlimited
rate_limit = "200/s"                       # optional; omit for unlimited

# Watchtower: streaming subscribe + watch registration, expires end-2026.
[[token]]
id = "watchtower"
hash = "sha256:<64-hex>"
capabilities = ["stream:subscribe", "stream:watch"]
watch_quota = 10000
expires = 2026-12-31T00:00:00Z             # unquoted RFC 3339 datetime, or unix seconds

# AI agent: full MCP tool access.
[[token]]
id = "agent"
hash = "sha256:<64-hex>"
capabilities = ["mcp:*"]

Rules:

• version = 1 is required. Each [[token]] needs a unique id and a hash of the form sha256:<64 hex>. capabilities defaults to empty; such a token can authenticate but is denied everything. watch_quota, rate_limit ("<n>/s"), and expires are optional. An omitted limit means unlimited.
• An unknown capability string, a duplicate id or hash, or a wrong version aborts the load with an error. Nothing is ignored silently.
• On Unix the file must have no group, world, or execute permission bits: 0600 or 0400, like a cookie file or an SSH private key. A 0644 or 0640 file is rejected.
• Generate a token and its hash with, for example:

  TOKEN=$(openssl rand -hex 32)        # the secret you give the client
  printf 'sha256:%s\n' "$(printf %s "$TOKEN" | sha256sum | cut -d' ' -f1)"
  

• Edit the file and send SIGHUP to reload it. The reload swaps the token table atomically, and removing a [[token]] revokes it immediately. A parse or permission error keeps the last-good table, so a bad reload never drops auth.

Presenting a token

Clients send the raw token in a standard header. The scheme is case-insensitive.

Authorization: Bearer <token>

The server computes SHA-256(token), looks the digest up in the loaded table with a constant-time guard, then checks expiry. A blank token can never authenticate.

Quotas & rate limits

• Rate limit. A per-token token bucket ("<n>/s", burst equal to the rate). Requests over budget are shed, never queued, so a slow or abusive consumer cannot backpressure the node. JSON-RPC, Esplora, and MCP return HTTP 429 with Retry-After; events gRPC returns RESOURCE_EXHAUSTED; streamws throttles at connection time.
• Watch quota. The streaming watch-set is metered in units. One scripthash costs one unit, and prefix watches are priced by coarseness. A token holds units through an RAII lease, so a disconnect releases its quota automatically. A watch add over quota is rejected without tearing down the subscription.

Operator and loopback principals are unlimited.

Per-surface enablement

Bearer support is opt-in per surface: the surface flag turns it on, and it requires -authfile. satd refuses to start if a surface flag is set without an authfile.

The read-only JSON-RPC listener (-rpcreadonlybind) does not honor bearer tokens. Client-certificate (mTLS) principals for the Electrum surface are planned but not yet implemented.

Exposing a surface remotely

Binding the streaming or MCP surfaces to a routable address requires auth; the node refuses an unauthenticated remote bind. The chain is:

-eventsgrpcallowremote  →  requires -eventsgrpcauth  →  requires -authfile
-streamwsallowremote    →  requires -streamwsauth    →  requires -authfile
-mcpallowremote         →  requires -mcpauth         →  requires -authfile

Where a bearer token is what authenticates a remote bind, the transport must also be encrypted — the token crosses the wire on every request, and so does everything the connection carries:

-eventsgrpcallowremote + -eventsgrpcauth  →  requires -eventsgrpctlscert / -eventsgrpctlskey
-mcpallowremote                           →  requires -mcpcert / -mcpkey

-eventsgrpcmtls satisfies the events-gRPC requirement on its own: it already requires the certificate and key, and it authenticates without a token.

MCP has one further requirement that is not an authentication gate: its transport validates the Host header against an allowlist that defaults to loopback, so a remote MCP bind also needs -mcpallowedhost naming every hostname clients use, or it answers 403 before auth runs. See MCP.

-streamwsallowremote is the exception, because that transport has no TLS of its own. A remote streamws bind sends its bearer token in cleartext unless a TLS-terminating proxy fronts it — prefer the loopback bind plus a proxy.

For a proxy-terminated or mTLS-terminated deployment, bind to loopback and omit the *-allow-remote flag. JSON-RPC remote exposure is governed by Core's existing -rpcbind/-rpcallowip; there is no separate allow-remote flag for it.

Transport TLS / mTLS

Native TLS and mutual TLS compose underneath this layer: mTLS gates the connection, and a bearer token presented over it further refines the principal's capabilities. satd terminates TLS natively on the RPC, Esplora, and Electrum surfaces, so no sidecar is required. The *tls*/*mtls* config keys are listed in the Configuration chapter.

JSON-RPC Extensions

satd preserves Bitcoin Core's JSON-RPC contract by default: the same method names, response field names, and types, so existing clients work unchanged. On top of that, satd adds opt-in extensions for developers and integrators. Each extension is either enabled by a server flag (and is therefore live-reloadable over SIGHUP) or exposed as an additional method or parameter. None of them alters the default Core-compatible wire shape. All are governed by the stability policy. The authoritative catalogue of where satd differs from Core is CORE_DIFFERENCES.md.

For the push-based event firehose and cursor-resumable watch subscriptions (gRPC, WebSocket, SSE, ZMQ), see the Streaming Consumption API chapter. That is a distinct surface from the extensions described here.

Note. JSON-RPC keeps Bitcoin Core's cookie / rpcuser / rpcauth credentials by default. Capability-scoped bearer tokens (-rpcauthbearer, rpc:read / rpc:write) are an opt-in addition. See Authentication & Authorization.

Satoshis-as-integers

Bitcoin Core emits every amount as an IEEE-754 double in whole BTC (0.00001000), which loses precision near dust and at the supply boundary. This is Core's long-standing #3249, open since 2013. satd can instead emit exact integer satoshis.

This is a server-wide default, --rpc-default-units=sats|btc (rpcdefaultunits as a config key), not a per-request flag. The default is btc, where output is byte-identical to Core: a fixed 8-decimal number, formatted from the integer satoshi value so it is exact. Set it to sats and amounts serialize as JSON integers everywhere. In that mode responses also carry a _units: "sats" tag so a client can confirm the shape it received. The tag is absent in the default btc mode, which stays byte-for-byte compatible. The option is live-reloadable. A per-request HTTP-header override is a planned follow-up.

Structured RPC errors

By default, error responses are byte-identical to Core's {code, message}. --rpc-extended-errors (rpcextendederrors; default off, live-reloadable) is a server-wide option. With it enabled, satd additionally populates the JSON-RPC data object with machine-actionable fields:

• category: a stable taxonomy string, for example mempool.policy.feerate, validation.consensus, storage.not_found.
• suggestion: a concrete remediation hint, when one applies.
• debug: arbitrary structured detail (field positions, computed values), when present.

Category names are stable once shipped in a release: new names can be added, and existing ones never change meaning. As with the units default, this is a server-wide option, since the common deployment pattern is satd driven only by satd-aware tooling. A per-request X-Satd-Extended-Errors header is a planned follow-up.

Fee estimation

Core's estimatesmartfee conf_target [estimate_mode] is kept with its exact response shape ({feerate, blocks, errors}) and is Core-compatible by default. The optional mode argument accepts Core's economical / conservative / unset vocabulary, all treated as the historical estimator. It also accepts satd's own historical / mempool / blend values.

satd also adds an estimatefees [targets] [mode] method (default mode blend, default targets [1, 3, 6, 12, 24]). It simulates the next N block templates from the current mempool, with ancestor-feerate (CPFP-aware) package sorting. It never hard-errors; it always returns a result. The response maps each target to a {feerate, confidence} pair, where confidence is high | medium | low, and includes a feerate histogram. This is the basis for Core's #11500.

Mempool subscription stream

subscribemempool is a JSON-RPC WebSocket subscription, paired with unsubscribemempool, that emits structured lifecycle events. Each event is tagged by a kind field:

• enter: a transaction was admitted to the mempool.
• leave_confirmed: it was confirmed in a block.
• leave_evicted: it was dropped, with an explicit reason (full_pool | expiry | block_conflict | policy | reorg).
• leave_replaced: it was RBF-replaced, carrying the replacing_txid.

Bitcoin Core requires polling getrawmempool or rebuilding this state from per-tx ZMQ frames. This stream carries explicit eviction reasons and RBF replacement linkage directly. For the richer firehose with cursor replay, see the Streaming Consumption API; subscribemempool is the lightweight JSON-RPC option.

Silent-payment block data

getsilentpaymentblockdata "blockhash" ( verbosity dust_limit ) returns the public BIP 352 tweak data for one block, from the tweak index (-silentpaymentindex=1, default off). It is the JSON-RPC fallback for the streaming tweaks category — the same bytes, for scripts, the reference-implementation differential, and integrators not yet on an SDK.

• verbosity 0 (default) → { "block_hash", "height", "tweaks": ["<33-byte hex>", …] }.
• verbosity 1 → each entry becomes { "txid", "tweak", "max_value" }.
• dust_limit (sats, default 0) drops entries whose largest taproot output value is below the floor.

Errors: -5 for an unknown or non-active block, -8 when the index is disabled, and -1 when the block is not yet indexed at that height (the row is absent — a height-by-height scanner cannot proceed past a gap, but unlike BIP 157 it cannot silently miss its own outputs either). The method is read-only. A light client runs one ECDH per returned tweak locally, so the scan key never reaches the node; for the streaming firehose with cursor replay, and the integrator guide to every silent-payment consumption mode, see Silent Payments (BIP 352).

Stratum

getstratuminfo reports the Stratum mining server. It takes no arguments, is read-only, and answers on a node with the server off too — with enabled: false, null listeners and zero counters — so a monitor can poll it unconditionally.

{
  "enabled": true,
  "listeners": { "v1": "127.0.0.1:3333", "v1_tls": null, "v2": "0.0.0.0:3336" },
  "authority_pubkey": "<32-byte x-only key, hex>",
  "job_declaration": false,
  "connections": 2,
  "channels": 3,
  "current_job": {
    "height": 912345,
    "job_id": "1a",
    "prev_hash": "<hex>",
    "template_txs": 3210,
    "template_fees": 12345678
  },
  "shares": { "accepted": 412, "rejected": 3, "stale": 1 },
  "blocks_found": 0,
  "last_block": null,
  "hashrate": 1210000000000.0,
  "miners": [
    {
      "protocol": "v1",
      "peer": "192.0.2.10:51234",
      "channel_id": null,
      "address": "bc1q…",
      "worker": "rig1",
      "device": "<user agent the firmware sent>",
      "difficulty": 10000,
      "connected_time": 1760000000,
      "shares": { "accepted": 208, "rejected": 1, "stale": 0 },
      "best_share_difficulty": 4812337.6,
      "last_share_time": 1760006280,
      "hashrate": 1210000000000.0
    }
  ]
}

• listeners are the bound addresses, with the real port when a bind used :0. authority_pubkey is null without a Stratum V2 listener.
• channels counts authorized Stratum V1 connections and open Stratum V2 channels.
• current_job is the work being handed out, or null while none is (during initial block download). job_id identifies the work within this server; the job ids a miner sees are per connection.
• shares count since startup. stale is a share for a job that is no longer current; rejected is every other refusal.
• blocks_found counts blocks found through the server that joined the active chain; last_block is { "height", "hash", "time" } for the most recent, or null.
• miners lists every miner connected now, oldest first: an authorized Stratum V1 connection, or a Stratum V2 channel (channel_id set). A miner leaves the list when it disconnects.
  • address is the payout address, or null when --stratumaddress pays; worker is the part of the username after the first ., reduced to printable ASCII and at most 64 characters.
  • device is the Stratum V1 user agent, or the Stratum V2 vendor, hardware version and firmware, reduced to printable ASCII; null if the miner sent none.
  • difficulty is the share difficulty the miner is set to now. connected_time and last_share_time (null before the first accepted share) are Unix times.
  • shares count this miner's shares, as the node-wide shares do. best_share_difficulty is the highest difficulty an accepted share's header achieved.
  • hashrate is an estimate in hashes per second, from the difficulty of the shares accepted over the last ten minutes (see Verifying a miner).
• The top-level hashrate is the sum over miners.

Client-side PSBT signing (no signing RPC)

There is no signing method: satd never handles private keys. Signing is a client-side sat-cli command.

sat-cli signpsbtwithkey reads a WIF private key or a BIP-32 xpriv from stdin, prompting without echo when stdin is a terminal. It signs the PSBT entirely locally, using only the prevout data already carried in the PSBT. It covers the common single-sig script types (Legacy, SegWit v0, nested SegWit, and Taproot key-path) and writes partial_sigs / tap_key_sig for the node's finalizepsbt to assemble, rather than finalizing itself. An xpriv is expanded over the standard BIP 44/49/84/86 paths, so it can sign PSBTs that carry no derivation metadata, including satd's own createpsbt output. The key never crosses the JSON-RPC boundary, so satd stays strictly keyless.

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 getsatdindexinfo:

addr-idx <state>   [sp-idx <state>]   esplora <state>   electrum <state>

The sp-idx column appears only when the silent-payment index is enabled, so nodes not using it keep the three-column row.

addr-idx states:

sp-idx states (BIP 352 tweak index, served via getsilentpaymentblockdata and the streaming tweaks category):

The silent-payment backfill is CPU-bound and can run for hours on mainnet; see Disk footprint for measured timings.

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.

satd Esplora REST API

satd ships a native Esplora-compatible REST server, enabled by default and listening on 127.0.0.1:3000. Wire shapes match upstream blockstream/esplora and mempool.space byte-for-byte within the endpoint set listed below.

Like the Electrum server, the Esplora server is a query layer over satd's own chainstate and shared address-history index. There is no separate indexer process (electrs, esplora-electrs, Fulcrum) beside the node with its own copy of the data. One RocksDB store backs the node and every API surface, updated atomically inside the node's connect_block and disconnect_block path. A read can never observe an index out of sync with the tip. The combined index is larger on disk than a standalone electrs or Fulcrum index: the trade is disk for consistency and single-process operation. See Disk Footprint & Indices for the accounting.

This chapter covers what is implemented today. The implementation lives in the esplora-handlers/ workspace crate. Routes are registered in esplora-handlers/src/router.rs, and shape parity is locked behind the canary CI requirement in STABILITY_POLICY.md.

Last verified against routes: 2026-05-05.

Note. The Esplora surface defaults to unauthenticated loopback. For Basic auth (--esploraauth) or capability-scoped bearer tokens (--esploraauthbearer, esplora:read), see Authentication & Authorization.

Configuration

POST /tx has a fixed 1 MiB body limit at the route layer. A witness-heavy 400 KB raw transaction hex-encodes to about 800 KB, so 1 MiB leaves margin and stays well under any consensus block limit. There is no flag to change this.

Esplora requires --addressindex=1 (auto-enabled if not set; see the address-index docs) and --txindex=1 (auto-enabled by the reconciliation in satd/src/config.rs). Both flags are on by default.

Endpoints

Chain

Block

Transaction

Address & Scripthash

The address-string and scripthash endpoint families share handlers; only the parser differs. A scripthash is the 32-byte sha256 of the scriptPubKey, hex-encoded in natural byte order. It is not reversed; Esplora's scripthash format differs from Electrum's.

Wrong-network addresses return 400, as do malformed addresses and bad scripthash hex (non-hex characters or wrong length).

Mempool & Fee

Root

Live updates (Server-Sent Events)

Connections receive a :keep-alive heartbeat every 25 seconds, so idle streams survive intermediate proxy timeouts (Caddy defaults to 30 s, nginx to 60 s).

Per-scripthash subscriptions consume from the registry capped by --addrindexsubscriptions=N (default 10000). Over-cap subscribe attempts return 503.

Total open SSE streams across all three endpoints are capped by --esplorasseconns=N, which defaults to the --esploramaxconns value. Each stream holds a permit until the client disconnects. This cap is distinct from the request-handling cap, which does not bound long-lived streaming bodies. Over-cap connections receive 503 immediately at the SSE entry point.

A subscriber that lags the broadcast channel skips ahead: the broadcast never panics but can drop intermediate events. On reconnect, refresh state through the standard endpoints (/address/:addr or /blocks/tip/{hash,height}).

Wire-shape gotchas

• Hex byte order. Block hashes, txids, and merkle siblings are hex-encoded in display (reversed) byte order, the same as Bitcoin Core's getblockhash and getrawtransaction. Scripthash hex is the natural byte order of sha256(scriptPubKey), not reversed; this differs from Electrum's wire format.
• Pagination cursors. /address/:addr/txs/chain/:last_seen_txid starts the next page strictly after the cursor in the descending list. An unknown cursor returns an empty array, so clients with stale state get [] rather than 404.
• Combined /txs. Returns up to 50 mempool transactions followed by the first 25 confirmed, in that order. Mempool entries appear in the index's HashSet iteration order, not strictly time-ordered.
• fee field on tx JSON. null when at least one prevout cannot be resolved (for example, txindex disabled or the previous tx pruned). Some(0) for coinbase. Otherwise sum_inputs - sum_outputs.
• Mempool UTXOs in /utxo. Outputs created by mempool transactions appear with status.confirmed: false and no block fields. Outputs spent in the mempool are excluded.
• Confirmation status on outspends. Confirmed spends carry a full status with block_height, block_hash, and block_time. Mempool spends carry status: { confirmed: false }.

Auth

Warning. The default auth mode is none. Loopback-only deployments (--esplorabind=127.0.0.1:3000) are usually fine. Set an auth mode explicitly before binding to a non-loopback address such as 0.0.0.0:3000. POST /tx is a broadcast endpoint, and an unauthenticated public listener accepts any transaction submission.

Three auth modes are available via --esploraauth=<mode>:

1. none (default): no authentication. The listener accepts every request.

2. cookie: reuses the same .cookie file the JSON-RPC server creates. Clients pass it via HTTP Basic Auth as __cookie__:<token>, the form Bitcoin Core-compatible tooling generates. Use --esploracookiefile=<path> to override the cookie path.

   satd --esplora=1 --esploraauth=cookie
   

3. userpass: static credentials supplied via --esplorauserpass=<user>:<pass>. The comparison is constant-time, and the HTTP scheme is case-insensitive.

   satd --esplora=1 --esploraauth=userpass --esplorauserpass=admin:hunter2
   

In cookie and userpass modes, satd refuses to start if the auth source cannot be established (unreadable cookie file, or --esplorauserpass missing).

CORS

--esploracors=<origin> enables CORS for the listed origins; * allows any origin. Allowed methods: GET and POST. Allowed headers: Content-Type and Authorization. CORS does not bypass authentication; it only admits cross-origin browser requests.

Bench harness

scripts/run-esplora-bench.sh starts a regtest node, mines warmup blocks, then drives ESPLORA_BENCH_REQS requests (default 200) against each implemented endpoint. It reports p50, p90, and p99 latency per endpoint. See the script header for the environment variables. It is not a CI gate; use it as a local regression check.

Compatibility statement

The implemented endpoints aim for byte-for-byte parity with upstream blockstream.info and mempool.space within these constraints:

• Standard scripts only. scriptpubkey_type strings cover p2pk, p2pkh, p2sh, v0_p2wpkh, v0_p2wsh, v1_p2tr, op_return, multisig, and unknown, matching upstream. Non-standard scripts serialize with scriptpubkey_address: null.
• Mempool ordering. /address/:addr/txs/mempool returns entries in HashSet iteration order, not strictly time-ordered. Upstream's contract is "up to 50" with no order specified.
• Fee histogram bucketing uses fixed boundaries spanning realistic mainnet fee regimes: 1, 2, 3, 5, 8, 10, 15, 20, 30, 50, 75, 100, 150, 200, 300, 500, 1000 sat/vB.
• WebSocket subscriptions are not implemented; SSE is the supported live-updates transport. Most consumers (BDK, the mempool.space SDK) accept SSE as a drop-in replacement.
• High-history scripts. The address-history endpoints (/address/:addr, /address/:addr/txs/chain[/:cursor], /address/:addr/utxo, and the scripthash variants) load the full confirmed-history row set for the scripthash on every request and sort it in memory. For typical wallet-sized scripts this takes under a millisecond. For high-activity scripts (exchange hot wallets, mining pools, popular donation addresses) a request can cost multi-MB allocations and sub-second latency. --esploramaxconns and --esplorarequesttimeout bound the damage. For a public deployment that serves such scripts, put the listener behind a per-IP rate limiter at the reverse proxy. Cursor-paginated index reads are tracked as future work.
• Address prefix search (/address-prefix/:prefix) is not implemented; it would require a separate prefix index.

Electrum Protocol Server

satd ships a native Electrum protocol server (the electrum-proto crate), serving the JSON-RPC-over-TCP protocol that BlueWallet, Sparrow, Nunchuk, Electrum, and most hardware-wallet coordinators speak. It is a query layer over satd's own chainstate and address-history index, not a separate electrs or Fulcrum process with its own copy of the data. satd's combined index is larger on disk than a standalone electrs/Fulcrum index: the trade is disk for consistency and single-process operation. See Disk Footprint & Indices for the rationale behind the native, shared-chainstate design.

The server is off by default. Enable it with --electrum=1. It needs the address index for scripthash history (on by default) and --txindex=1 for the confirmed-transaction and merkle-proof methods (off by default). Startup fails if either index is disabled.

• Protocol version: 1.4, advertised as both protocol_min and protocol_max. satd serves a single protocol version.
• Transport: line-delimited JSON-RPC over plain TCP (default 127.0.0.1:50001) and/or TLS (default port 50002). Expose the server over Tor / .onion rather than directly on the LAN.

Note. Electrum is loopback by default. It supports native TLS and mutual TLS (--electrumtlsbind + --electrummtls…). The unified bearer-token layer does not gate Electrum; client-certificate principals are planned but not yet implemented. See Authentication & Authorization.

Configuration

The server runs on satd's isolated API runtime (--api-threads), so Electrum load cannot starve block connection.

Supported methods

A scripthash is the SHA-256 of an output scriptPubKey, reversed (hex), exactly as in the Electrum protocol.

Server / session

Headers & blocks

Scripthash (address) queries

Transactions

Fees

Silent payments

Subscriptions

Two long-lived push subscriptions are supported, both counted against --electrummaxsubsperconn:

• blockchain.headers.subscribe: a blockchain.headers.subscribe notification on every new tip.
• blockchain.scripthash.subscribe: a blockchain.scripthash.subscribe notification carrying the new status hash whenever a watched scripthash's history changes, in the mempool or confirmed. The index is updated inside the same connect_block / disconnect_block batch as the chainstate, so a subscriber can never observe a status out of sync with the tip.

blockchain.tweaks.subscribe also pushes notifications, but it is a bounded chunk rather than a standing subscription — it ends itself with {"message":"done"} — so it does not count against the per-connection cap.

A chunk serves at most 1000 heights, whatever count asks for; both known clients request the entire remaining chain in one call and resubscribe when the chunk ends, and the de-facto reference server clamps the same way. The cap is what makes the end marker unambiguous: clients disagree about what done means — Cake reads it as "this chunk ended, ask again from the last height key", kiss-bdk as "the range I requested was served in full" — and those readings only agree if the server finishes every range it accepts. satd therefore bounds the range up front rather than truncating an accepted one. If a chunk does stop early anyway (a height it cannot read, or the 60-second budget), it ends with {"message":"incomplete: …; resume from height <h>"} instead of done, so a client that reads the sentinel as completion is not told that unserved heights were scanned and empty. Only one runs per connection at a time: a second subscribe while one is still producing is refused rather than replacing it, because notifications the superseded stream had already queued cannot be recalled and would arrive after the new stream's first height.

Serving silent-payment tweaks

blockchain.tweaks.subscribe serves the BIP 352 per-transaction tweaks a wallet needs to scan for silent payments on the device — the node never sees a scan key. It requires the tweak index (-silentpaymentindex=1), and refuses in-band without it, or while the index is still backfilling: a partial index would answer the heights it has not reached with silence, and a scanning client cannot tell that from "no payments here". server.features.tweaks reports whether this node can serve it right now — index present and complete, the same test the subscribe itself makes — so a client can check before starting a scan rather than discovering hours of backfill the hard way.

It is a stream, not a call. The JSON-RPC result carries the first height only; every further height arrives as an unsolicited blockchain.tweaks.subscribe notification, and {"message":"done"} ends the chunk. A client that treats it as an ordinary request/response reads one block and believes it finished a scan. Params are [start_height, count, historical_mode], and one height looks like:

{"850000": {"<txid>": {"tweak": "<33-byte hex>",
                       "output_pubkeys": {"<vout>": ["<x-only hex>", 100000]}}}}

Carrying each transaction's taproot outputs alongside the tweak is what lets a client confirm a match without fetching the block — the difference between a scan that is CPU-bound and one that waits on network round-trips.

historical_mode is the same trade the streaming API's tweak_unspent_only makes, in reverse polarity: false (what Cake Wallet sends) cuts through coins that are already spent, true keeps them. A balance scan wants false; a wallet reconstructing transaction history must pass true, because a payment received and later spent is omitted entirely under cut-through. See Silent Payments for the full contract.

Heights below taproot activation are streamed as one notification carrying up to 1024 empty height keys, so a wallet restoring from an old height still sees its progress marker advance without the server writing ~700k lines. A chunk ends after 60 seconds of wall clock at a height boundary; clients resubscribe from the next unscanned height, which is what done is for.

The server name, and why it says electrs

satd reports satd-electrs-compatible/<version> from server.version and server.features.server_version.

Cake Wallet feature-detects by matching on that string rather than on server.features, and will not probe blockchain.tweaks.subscribe at all unless it contains the substring electrs — note electrs, not electrum; the two read the same to a person and only one matches. Carrying the token is what makes silent-payment support work out of the box for those clients.

The name leads with satd's own identity and states a claim about the protocol, in the same way every browser still sends Mozilla at the front of its user-agent long after that stopped saying anything about who wrote the browser. It is scoped to this surface: peers on the P2P network see satd's own user agent (/satd:<version>/, reported by getnetworkinfo as subversion), which this setting cannot change.

Override it if you would rather not advertise the token, or need a different one for another client:

electrumservername=satd/0.5.2

Keep an override from beginning with electrs. Several clients test that prefix rather than searching the whole string: BlueWallet uses it to decide a server needs request batching disabled, and a name starting with electrs would leave batching off permanently. Leading with satd- — identity first, compatibility token second — is what keeps the default matching Cake's substring test while matching nobody's prefix test. An empty value (electrumservername=) is ignored with a warning rather than advertising a nameless server.

Other tweak clients (for example kiss-bdk) do not need the substring — they identify the chain from server.features.genesis_hash. Nothing else about the server depends on the name.

Sparrow's silent-payment path is a different method (blockchain.silentpayments.subscribe), which uploads a scan key to the server. satd does not implement it. Sparrow still uses satd as an ordinary Electrum backend.

Notes & differences

• --txindex is required for blockchain.transaction.get, get_merkle, and id_from_pos. --addressindex (on by default) backs every scripthash.* method.
• satd advertises a single protocol version (protocol_min == protocol_max == 1.4); it does not negotiate a range.
• server.peers.subscribe returns an empty list: satd does not participate in Electrum peer gossip.
• The protocol layer is vendored from romanz/electrs (MIT; attribution in electrum-proto/vendor/electrs.MIT) and adapted to satd's AddressIndex trait over the shared RocksDB.

Stratum Mining Server

satd ships a Stratum V1 and Stratum V2 solo-mining server built into the node. A miner — a BitAxe, an NerdQAxe, any ASIC or firmware that speaks Stratum — connects to the node directly, receives work built from satd's own block template, and has any block it finds accepted, taken out of the mempool and relayed by the same process. There is no pool in between and no separate proxy to run.

It is a solo server, not a pool. The username a miner presents is the payout address: the coinbase of every block that miner finds pays that address the full subsidy plus fees. There is no share accounting, no payout splitting and no share database; shares exist only so the miner (and its operator) can see that it is hashing. This is the same model as ckpool -B solo mode.

The server is off by default. Enable it with --stratum=1; add --stratumv2bind for a Stratum V2 listener beside the V1 one.

Quick start

satd --stratum=1

Point the miner at stratum+tcp://<node-address>:3333, with the username <your-address>.<worker-name> and any password. The worker name after the first . is optional and appears only in the node's log.

The default listener is loopback only (127.0.0.1:3333), so the command above serves a miner on the same host. A miner on the network needs either the TLS listener (recommended, below) or an explicit plaintext bind:

satd --stratum=1 --stratumbind=0.0.0.0:3333 --stratumallowplaintextremote=1

Exposure posture

A Stratum V1 session is cleartext JSON. The payout address travels in the clear on every mining.authorize, and a device on the path between the miner and the node can rewrite it: the miner keeps hashing, and every block it finds pays someone else. Nothing on the miner shows that anything is wrong.

So satd refuses to start when --stratumbind is not a loopback address and no --stratumtlsbind is configured:

Error: --stratumbind=0.0.0.0:3333 is not a loopback address and no
--stratumtlsbind is configured. Miners on the network would receive work
and submit shares in cleartext. Set --stratumtlsbind (recommended) or
--stratumallowplaintextremote=1 to accept this.

--stratumallowplaintextremote=1 accepts the risk, and is reasonable on a network segment you control end to end. The TLS listener runs beside the plaintext one, not instead of it: loopback clients can keep using port 3333.

This is stricter than the Electrum server's defaults. The difference is what is at stake — an Electrum session leaks privacy, a Stratum session can be robbed.

TLS with real miners

Set --stratumtlsbind (the conventional port is 4333) with a certificate and key, and point the miner at stratum+tls://<node-address>:4333. Add --stratummtls=1 with --stratummtlsclientca to require a client certificate, and --stratummtlsclientallow to accept only listed certificate names.

A home node has no public certificate, so the miner has to trust a CA you create. Two things decide whether that works.

The certificate must name the address the miner dials. Miner firmware verifies the server certificate against the host in the pool URL. If the miner is pointed at stratum+tls://192.168.1.50:4333, the server certificate needs 192.168.1.50 as an IP subject alternative name; a hostname SAN alone fails.

The CA certificate must be small. ESP-Miner-based firmware (AxeOS, used by the BitAxe family) accepts a custom CA certificate in its pool settings, but copies it into a 512-byte buffer — at most 511 bytes of PEM. A longer certificate is truncated without an error message, and the TLS connection then never verifies. An RSA-2048 CA is about 1,100 bytes. Even an EC P-256 CA exceeds the limit once it carries the usual key-identifier extensions: the CA that contrib/stack/tls/mkca.sh issues for the other TLS surfaces is about 700 bytes and does not fit.

A P-256 CA with a short name and only the two extensions a CA needs fits, at 497 bytes:

openssl ecparam -name prime256v1 -genkey -noout -out ca.key
openssl req -x509 -new -config /dev/null -key ca.key -sha256 -days 3650 \
  -subj "/CN=satd" \
  -addext "basicConstraints=critical,CA:TRUE" \
  -addext "keyUsage=critical,keyCertSign" \
  -addext "subjectKeyIdentifier=none" \
  -out ca.crt

openssl ecparam -name prime256v1 -genkey -noout -out stratum.key
openssl req -new -key stratum.key -subj "/CN=satd-stratum" -out stratum.csr
printf 'subjectAltName=IP:192.168.1.50\nextendedKeyUsage=serverAuth\n' > stratum.ext
openssl x509 -req -in stratum.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
  -days 825 -sha256 -extfile stratum.ext -out stratum.crt
cat stratum.crt ca.crt > stratum-fullchain.crt
wc -c ca.crt    # must be 511 or less

Then run:

satd --stratum=1 \
  --stratumtlsbind=0.0.0.0:4333 \
  --stratumtlscert=stratum-fullchain.crt \
  --stratumtlskey=stratum.key

and paste the contents of ca.crt — not the full chain, not the server certificate — into the miner's custom-CA field.

At startup satd warns when the last certificate in --stratumtlscert (the CA, in a full-chain file) is larger than 511 bytes of PEM. It is a warning, not an error: firmware that uses a system CA bundle, or keeps a larger buffer, is not affected.

Stratum V2

Stratum V2 runs the mining protocol over a Noise-encrypted connection (Noise_NX_Secp256k1+EllSwift_ChaChaPoly_SHA256), authenticated by the server's authority key. Enable it with --stratumv2bind:

satd --stratum=1 --stratumv2bind=0.0.0.0:3336

Because the connection is encrypted and the server authenticated, the V2 listener may bind a network address without TLS; the plaintext refusal above applies only to the V1 listener. ESP-Miner-based firmware (AxeOS 2.14 and later) speaks Stratum V2 natively, using an extended channel by default.

The authority key. On first start satd creates the key at <datadir>/stratum_v2.key (override with --stratumv2key), readable only by its owner, and logs the public key in both forms the ecosystem uses:

Stratum V2 authority key ... created=true authority_pubkey=<64 hex characters> authority_pubkey_base58=<base58check>

A miner either trusts the key it sees on first connection or is configured with it in advance; either way it refuses a server that later presents a different one. Back the key file up with the rest of the datadir. Losing it means reconfiguring every miner that pinned the old key. A key file that exists but cannot be read, or does not hold a valid key, stops the node rather than being replaced. The base58check form — a little-endian key version of 1 followed by the 32-byte x-only key — is what AxeOS and most Stratum V2 tooling accept as the pool's authority public key.

Channels. Both channel types are served. An extended channel receives the coinbase split around an extranonce hole, the merkle path and an extranonce range, and rolls its own extranonce; this is what AxeOS uses. A standard channel receives a finished merkle root and rolls only the nonce, timestamp and version bits. --stratumv2maxchannels caps channels per connection. The user_identity a channel is opened with is the payout address, resolved exactly as a V1 username is; without a usable address the channel is refused with unknown-user.

Jobs. Each channel's first job on a tip is sent as a future job followed by the SetNewPrevHash that activates it; a new tip repeats that for every channel, and the 30-second refresh sends a job that is active at once. Vardiff changes are sent as SetTarget. Shares are judged exactly as V1 shares are; rejections carry the Stratum V2 codes stale-share, difficulty-too-low, duplicate-share, invalid-share, invalid-timestamp and invalid-channel-id.

A connection must complete the handshake within 10 seconds.

Job Declaration

With --stratumv2jd=1 the Stratum V2 listener also serves the Job Declaration Protocol, for a miner that wants to choose the transactions in its blocks. The miner runs a Job Declarator Client, which:

1. opens a Job Declaration connection to the same port and sends AllocateMiningJobToken with its payout address as the user identifier (the answer names the payout output its coinbase must include);
2. declares a coinbase and a list of transactions by wtxid (DeclareMiningJob);
3. on a mining connection opened with REQUIRES_WORK_SELECTION, sends SetCustomMiningJob on an extended channel with the token the declaration returned, and mines the job id it gets back. A block found on it is submitted with ordinary shares, or pushed with PushSolution.

This is solo-mining Job Declaration, so the checks are strict and nothing is fetched:

• Every declared transaction must already be in this node's mempool and eligible for a block template. A declaration naming anything else is refused with invalid-job-param-value-wtxid_list; the server never asks for missing transactions.
• A transaction that spends an unconfirmed parent must be listed after it, and the set must fit in a block.
• The coinbase must commit to the next height on the current tip, pay the address the token was issued for, claim no more than the subsidy plus the declared fees, and carry a witness commitment that matches the declared transactions.
• The custom job must name the current tip and difficulty, a merkle path that matches the declaration, a coinbase prefix of at most eight bytes starting with the height, and outputs that satisfy the same payout and value rules.

Refusals use the Stratum V2 codes invalid-mining-job-token and invalid-job-param-value-<field>, with a human-readable reason in DeclareMiningJobError's details. A token is good for one declaration and expires after ten minutes. Without --stratumv2jd, a Job Declaration connection is refused with unsupported-protocol, and a mining connection asking for work selection with unsupported-feature-flags.

Monitoring

getstratuminfo reports the listeners, the authority key, open connections and channels, share counters, blocks found, the current job, and every connected miner with its device, difficulty, share counts, best share and estimated hashrate. See JSON-RPC Extensions. The same counters are Prometheus metrics; see Observability.

Verifying a miner

For a quick check, sat-cli getstratuminfo lists each connected miner with its share counts, the time of its last accepted share and its estimated hashrate. The log has the history. Every miner gets these lines with no extra flags:

-debug=stratum adds the detail for a device that is not behaving. Like any -debug category it can go in the config file (debug=stratum), be switched on at runtime with sat-cli logging '["stratum"]' and off with sat-cli logging '[]' '["stratum"]', and a SIGHUP puts it back to what the config file says. -debugexclude=stratum keeps it out of -debug=all. With it on:

• Stratum miner subscribed names the user agent the firmware sent, and Stratum V2 SetupConnection the vendor, hardware version, firmware and device id.
• Stratum version rolling negotiated shows the mask the miner asked for and the mask it was granted, and Stratum miner suggested a difficulty shows a mining.suggest_difficulty and the difficulty adopted.
• Stratum share accepted for every share, with the worker, job, difficulty and share_difficulty. A share that is also a block is logged as a found block instead.
• A vardiff retarget line for every difficulty change.
• Stratum miner status every five minutes for each miner: shares accepted, rejected and stale since the last status line, the current difficulty, the estimated hashrate, and the seconds since the last accepted share.

-loglevel=stratum:trace also logs every job sent to a miner.

The hashrate is estimated from the shares the node accepted: a share at difficulty d takes d × 2^32 hashes on average, so the estimate is the sum of the accepted shares' difficulties over the last ten minutes (or since the miner connected, if that is shorter), times 2^32, divided by that span. At vardiff's one share every 30 seconds, ten minutes is about twenty shares, so expect the estimate to wander about a quarter either side of the device's rated hashrate. A status line early in a connection covers only a few shares.

What the lines point to:

• No authorized line. The miner is not reaching the listener, or its username is refused; the refusal is logged at warn.
• Authorized, then disconnected with reason="idle" and no shares. The device connected but is not submitting. Check that the node is issuing work: during initial block download it withholds work and says so once.
• Every share low difficulty, with share_difficulty far below difficulty. The miner is hashing a different header from the one the node rebuilds, so its shares are effectively random. Compare the granted version-rolling mask with what the firmware rolls. Real bad luck puts share_difficulty near difficulty, not orders of magnitude below it.
• Mostly stale or unknown job. The miner is slow to switch to new work, or its connection is lagging.
• A hashrate well below the device's rating over several status lines. The device is hashing slower than it should (thermal throttling, a failing hashboard), or losing work to rejects.
• Repeated disconnect lines. The device or its network is dropping the connection. connected_secs says how long each one lasted.

Configuration

Every Stratum key is restart-only.

The server runs on satd's isolated API runtime, and block submission runs on a blocking thread, so a found block does not stall the other API listeners. getserverstatus reports the bound stratum, stratum_tls and stratum_v2 listeners, including the real port when a bind used :0.

Payout address

The address is resolved on mining.authorize, in order:

1. The username, up to the first ., if it is a valid address for this network.
2. Otherwise --stratumaddress.
3. Otherwise authorize fails with [24, "Unauthorized worker: username is not a valid address for this network and no --stratumaddress is set", null].

"For this network" means mainnet versus the test networks. A mainnet address is refused on testnet and regtest, and a test address on mainnet; but testnet3, testnet4 and signet share an address encoding, so one test network's address is accepted on another. The log line for each authorize shows the address and script that will be paid.

Difficulty and vardiff

A connection starts at --stratumdifficulty (or the per-network default) and vardiff steers it toward one share every 30 seconds. Every 90 seconds the difficulty is scaled by how far the observed share rate is from that target, by at most a factor of four per step, and never above the network difficulty. A difficulty change is sent as mining.set_difficulty followed by a new job; shares for the previous job are still judged at the difficulty that job was issued with.

mining.suggest_difficulty sets the connection's difficulty and makes it the floor vardiff will not go below. It is clamped to [1, 2^48].

A ~1.2 TH/s BitAxe-class device at the mainnet default of 10,000 finds a share about every 35 seconds, so it starts close to the target rate.

Stratum V2 channels start at the same difficulty and are steered the same way; a channel's target also never exceeds the max_target the miner opened it with.

A share is checked against the easier of the share target and the block target. On regtest, where the block target is far easier than difficulty 1, that is what lets a block-winning header through.

Stratum V1 protocol

Methods served: mining.configure (BIP 310 version rolling, mask 1fffe000), mining.subscribe, mining.authorize, mining.suggest_difficulty, mining.submit, mining.extranonce.subscribe (accepted, no-op) and mining.ping. The server sends mining.notify and mining.set_difficulty.

• mining.subscribe returns a 4-byte extranonce1 unique to the connection and an extranonce2 size of 4 bytes.
• A new job is sent on every chain tip change (with clean_jobs set: earlier jobs are stale) and every 30 seconds otherwise, so new mempool transactions reach the miner.
• The last eight jobs per connection are kept. A share for any other job is [21, "Job not found", null]. Other rejections are [22, "Duplicate share", null], [23, "Low difficulty share", null], and [20, "Invalid ntime", null] for a timestamp below the median time past or more than two hours ahead of the node's clock.
• On testnet3 and testnet4, a block timestamped more than 20 minutes after its parent may use the minimum difficulty, so a job's difficulty holds only on one side of that moment. A share timestamped on the other side from the job is stale; the next refresh issues a job with the right difficulty.
• Lines are limited to 8 KiB, and a connection that sends nothing for 120 seconds is closed.

When work is withheld

During initial block download the server accepts connections and answers subscribe, configure and authorize, but sends no work: a block built on a tip days behind the network is worthless. It logs stratum: not issuing work during initial block download once and sends work as soon as the node catches up. Regtest is exempt, because a fresh regtest chain's genesis block is from 2011.

The server does not wait for peers. Outside regtest it logs a warning the first time it issues work with no peer connected, since a block found then cannot be relayed until one connects.

When a block is found

A share whose header meets the block target is assembled into a full block and submitted exactly as submitblock would: proof of work, then block acceptance. If the block joins the active chain its transactions leave the mempool and it is announced to peers; every miner receives a clean job for the new tip. The node logs:

Stratum miner found a block height=... hash=... address=... worker=...

The miner's submit is answered true whatever the outcome — the miner did its part. A block that is valid but does not join the active chain, or that is rejected, is logged at warn.

Networks

• mainnet, testnet3, testnet4, regtest: supported.
• signet: refused at startup with --stratum is not available on signet: signet blocks require the network's signing key. Signet blocks carry a signature from the network's signing key (BIP 325), which no block template here provides, so every block a miner found would be invalid.

Not supported

• Pool operation: multiple payout addresses per share stream, PPLNS or any other reward splitting, share accounting.
• The Stratum V2 Template Distribution Protocol (the TemplateProvider role), group channels, and fetching declared transactions this node does not already have (ProvideMissingTransactions).

Getting Started: Consuming Events

This chapter takes you from nothing to a durable, reconnect-surviving consumer of satd's Streaming Consumption API, one runnable step at a time. Each step names the concept, then links to the two reference chapters that own the detail:

• the Streaming Consumption API chapter: the wire protocol, transports, watch-sets, cursors, quotas, and operator limits;
• the Rust SDK (satd-events-client) chapter: every type and method, in isolation.

Read those when you need a full signature or an edge case.

The tutorial uses the Rust SDK throughout. Nothing here is Rust-specific at the protocol level: the Go SDK (satdevents) is a full-parity sibling and every step below maps onto it one-for-one (that chapter has the translation table), and WebSocket and SSE consumers follow the same sequence over the JSON rendering (see the Transports section).

Prerequisites

You need a running node with the events gRPC listener enabled (eventsgrpcbind = 127.0.0.1:50051) and a project that depends on satd-events-client. A loopback node needs no token. A remote node needs bearer auth or mTLS; Step 8 covers that.

Step 1: Choose a transport

The API has one schema and three transports: gRPC (the primary programmatic surface), JSON over WebSocket (GET /ws, with a control channel), and SSE (GET /sse, a read-only firehose for browsers and curl).

If you are writing a service, use gRPC. It is the only transport with the full bidirectional watch-set control channel. The transport details and the port model are in the Transports section. The rest of this tutorial uses gRPC.

Step 2: Connect

use satd_events_client::{StreamClient, SubscribeOptions, Categories, Event};

let mut client = StreamClient::builder("http://127.0.0.1:50051")
    .keepalive_default()
    .connect()
    .await?;

This opens a plaintext loopback connection, which is fine for a node on the same host. TLS, mTLS, and bearer tokens are one builder call each; see Connecting and Step 8.

Step 3: Tail the firehose

Before you watch anything specific, prove the pipe works. Tail the raw event firehose, every block and mempool transition the node sees:

let mut events = client.subscribe(SubscribeOptions {
    categories: Categories::MEMPOOL | Categories::CHAIN,
    from_cursor: None,   // forward-only for now; Step 5 makes it durable
    since_seq:   None,
}).await?;

while let Some(event) = events.message().await? {
    match event {
        Event::BlockConnected { height, .. } => println!("block {height}"),
        Event::MempoolEnter { txid, .. }      => println!("mempool {txid}"),
        _ => {}
    }
}

Event is a flat enum, so you match on it instead of unwrapping nested options. The full firehose semantics (categories, the captured Cursor, lag notices) are under the subscribe reference.

Step 4: Watch something and react

The firehose is the wrong tool for tracking your own scripts; that is a watch-set. Open the bidirectional watch stream, register interest, and react to matches:

let (watch, mut events) = client.watch().await?;

// A direct script watch, with an optional per-script value floor (sat).
watch.add_scripts([(scripthash, Some(100_000))]).await?;

// Or a whole wallet from its exported descriptor: the server expands the
// gap-limit window and derives the scripts for you (keyless: public-key-only).
watch.add_descriptor(descriptor, /*gap*/ 20, /*start*/ 0).await?;

while let Some(event) = events.message().await? {
    if let Event::ScriptMatched { txid, descriptors, .. } = event {
        // `descriptors` maps a descriptor-derived hit back to its descriptor
        // and exact (branch, derivation_index); it is empty for a direct
        // watch. A multi-wallet consumer routes the hit with no reverse index.
        println!("hit {txid} ({} descriptor attributions)", descriptors.len());
    }
}

Outpoint, txid-lifecycle, and confirmation-depth watches all take the same shape. Every watch kind, and the edge cases the typed helpers handle, are under the watch reference.

Step 5: Make it survive a reconnect

The watch stream above loses its watch-set and its place in the stream the moment the connection drops. resilient_watch fixes both. It re-registers the watch-set on every reconnect and resumes from a persisted cursor, so a network blip or a process restart is invisible to your logic.

use satd_events_client::{ResilientWatchConfig, FileCursorStore, Event, AutoClose};
use std::sync::Arc;

let config = ResilientWatchConfig::new()
    .cursor_store(Arc::new(FileCursorStore::new("/var/lib/app/watch.cursor")));
let mut watch = client.resilient_watch(config);

// Registered once; replayed automatically across every reconnect.
watch.add_scripts([(scripthash, None)]).await?;
watch.add_tx_lifecycle([txid], AutoClose::AtDepth(6)).await?;

loop {
    match watch.next().await? {
        Event::ScriptMatched { txid, .. } => { /* your logic */ }
        _ => {}
    }
}

Kill the node's listener and bring it back: the wrapper reconnects with backoff, re-registers the set, and re-anchors the cursor. Re-anchoring is deterministic, driven by the in-band CursorAccepted/CursorRejected result. Use this wrapper as the default for any long-lived consumer. See the resilient_watch reference.

Step 6: Bind the watch-set to your source of truth

The mirror resilient_watch keeps is authoritative only if you build the set once and never change it. Real consumers have a durable source of truth, such as a database table of watched addresses, and it changes while the process runs.

Give the wrapper a watch_set_loader. The wrapper then rebuilds the canonical set from that truth on every reconnect, and on a fresh start it rehydrates from truth, not from an empty mirror:

let config = ResilientWatchConfig::new()
    .cursor_store(Arc::new(FileCursorStore::new("/var/lib/app/watch.cursor")))
    .watch_set_loader({
        let db = db.clone();
        move |builder| {
            let db = db.clone();
            async move {
                for row in db.load_watched_scripts().await? {
                    builder.add_scripts([(row.scripthash, row.min_value)]);
                }
                Ok(())
            }
        }
    });

When the truth changes while the stream is up, after a bulk import for example, call watch.reload().await?. It re-runs the loader and pushes the whole desired set as a single atomic SetWatchSet. The server reconciles the set by effective coverage under its lock and answers deterministically: WatchSetReplaced, or WatchSetRejected { reason, .. } with QuotaExceeded, CapExceeded, or Malformed. No client-computed delta can strand coverage. The full semantics are in the loader and reload() subsections of the resilient_watch reference.

Step 7: Watch privately with a script prefix

Every step so far tells the node exactly which scripts you care about. For a custodian, an exchange, or a privacy-sensitive wallet, that interest set is itself sensitive: the node operator learns exactly whom you watch. A prefix watch breaks that link.

You register only a coarse bits-bit prefix of sha256(scriptPubKey). The server delivers every transaction that falls in that 2^-bits bucket, so it learns only the bucket, never your exact script. You filter the decoys out locally. PrefixWatcher (behind the bitcoin feature) computes the buckets to register and does the local filtering:

use satd_events_client::{PrefixWatcher, Event};

let mut watcher = PrefixWatcher::new();
watcher.watch_script(&my_script_pubkey);          // add each real script locally

let (watch, mut events) = client.watch().await?;
watch.add_script_prefixes(watcher.prefixes(16)).await?;   // register 16-bit buckets

while let Some(event) = events.message().await? {
    if let Event::PrefixMatched(m) = event {
        let hits = watcher.filter(&m)?;           // recomputes sha256(spk), drops decoys
        for f in &hits.funding  { /* a genuine funding match */ }
        for s in &hits.spending { /* a genuine spend match  */ }
        if hits.has_unresolved() {
            // A spend-side prevout the server did not retain (mempool below
            // the `full` tier). Resolve the outpoint yourself before you
            // conclude non-match; do not treat "absent" as "not mine".
        }
    }
}

bits sets the privacy/bandwidth trade-off. Fewer bits means a larger bucket, more decoy traffic, and a weaker link between you and any one script. filter never issues a precise follow-up fetch, because that would re-leak the interest the bucket exists to hide. The streamprevoutmeta option governs spend-side retention; the retention tiers and the full mechanism are in Prefix watches and the Streaming API chapter.

Step 8: Go remote safely

Every step above assumed a loopback node. A remote bind must be encrypted and authenticated: over plaintext http://, the bearer token and the entire event stream travel in the clear. Add TLS (a public CA or a pinned self-signed CA) and a token, or mutual TLS, with one builder call each:

let mut client = StreamClient::builder("https://node.example:50051")
    .tls()                       // or .tls_ca_pem(std::fs::read("node-ca.pem")?)
    .bearer_token(token)
    .keepalive_default()
    .connect()
    .await?;

The node-side options (eventsgrpctlscert, eventsgrpcmtls, eventsgrpcallowremote) are in the Transport encryption section. The client-side builder options, including the mTLS client identity, are under TLS / mTLS.

Where to next

The tutorial covered the full sequence: connect, tail the firehose, register a watch-set, make it durable, bind it to your source of truth, watch privately, and go remote. The reference chapters cover what this tutorial deferred:

• Quotas and error handling. The watch quota, the rate limits, and which StreamErrors are retryable: Errors and the Authentication & quotas section.
• Cursors and replay. Exact confirmed-side replay, best-effort mempool replay, and the replay-truncation ReplayGap: Cursors & replay.
• Runnable examples. firehose_tail, resilient_tail, watch_outpoints, descriptor_wallet, lifecycle_alarms, prefix_privacy, tls_tail, and mtls_tail, in satd-events-client/examples/.

Streaming Consumption API

The Streaming Consumption API is satd's push-based surface for downstream consumers: wallets, Lightning nodes, exchanges, watchtowers, explorers, and other L2 projects. It pairs a real-time event firehose of blocks and mempool transitions with live, cursor-resumable watch subscriptions keyed on outpoints, scripts, descriptors, and transaction ids.

The incumbent ways to consume a node all leave the same gaps: descriptor lifecycle, outpoint-level subscriptions, and cursor-based event replay. Consumers end up rebuilding each of these themselves. satd serves all three natively and in-process, as consensus ground truth, with no reconstruction from a ZMQ side channel.

This chapter is the integrator guide. The authoritative wire-level protocol specification (the satd.events.v1 protobuf, frame formats, and cursor semantics) is docs/api/streaming.md. For a step-by-step onramp before this reference, start with Getting Started: Consuming Events.

The base primitive: outpoint subscription

Outpoint subscription is the base primitive. Lightning channel-close detection, watchtower triggers, exchange deposit confirmation, and theft monitoring all reduce to one request: report when this outpoint is spent. Address watching is outpoint watching with a derivation rule on top. The API builds down to outpoints, and layers script, descriptor, and transaction-id watches over the same matcher.

Transports

One schema serves three transports. The satd.events.v1 protobuf definition is the source of truth.

1. gRPC (satd.events.v1, tonic). The primary transport for programmatic consumers. It offers a server-streaming Subscribe (the firehose) and a bidirectional Watch (the firehose plus a managed watch-set).
2. JSON over WebSocket (GET /ws). A hand-mapped JSON rendering of the same tagged unions, with a client-to-server control channel that mirrors Watch.
3. Server-Sent Events (GET /sse). A read-only JSON firehose with no control channel, for browser and curl consumers.

A Core-compatible ZMQ PUB sink remains for legacy parity. It carries the firehose bodies only, not per-subscriber watch matches, and uses Core's per-topic sequence numbers.

WebSocket and SSE bind a dedicated --streamws port; they do not upgrade on the Core-compatible JSON-RPC port. The stream stays a distinct service on a distinct port. Every streaming listener (--streamws and the gRPC NodeEventStream) runs on the isolated API tokio runtime (--api-threads), never on the core block-connecting runtime. A flood of streaming clients therefore cannot contend with the threads that connect blocks and accept mempool transactions. See API Scaling & Runtimes for the runtime split, the admission caps, and how to scale beyond one node.

Subscriptions and watch-sets

The gRPC service offers the server-streaming Subscribe (the firehose, with cursor replay) and a bidirectional Watch. The client-to-server Watch messages are a tagged union: SetCursor, SetCategories, Add/Remove for scripts, outpoints, transactions, script prefixes, and descriptors, and SetWatchSet. SetWatchSet is an atomic whole-set replace: the client sends the complete desired watch-set in one message, and the server reconciles it under its lock by effective coverage, replying with a deterministic WatchSetResult. New subscription kinds can be added without protocol breakage.

Match events delivered on the per-subscriber Watch channel include:

• OutpointSpent. An outpoint was spent, in the mempool or in a connected block.
• ScriptMatched. A script was funded or spent (both sides). For a descriptor-derived script it carries descriptor_matches: which descriptor matched, and the exact (branch, derivation_index) the script was derived at. The field is empty for a directly watched script. A multi-descriptor consumer can route a hit without keeping its own reverse index. The event also carries the matched value (amount/has_amount, at parity with SpentPrevout), so an exact-script consumer can skip the per-match getrawtransaction enrichment call. With SetWatchOptions{include_raw_tx} set (per connection, off by default) it also carries the full consensus-serialized matching transaction in raw_tx.
• TxidMatched / TxidReplaced / TxidEvicted / TxidUnconfirmed / TxidDepthReached / TxidFinalized. Transaction lifecycle and confirmation-depth alarms.
• PrefixMatched. A privacy-preserving script-prefix match.
• SilentPaymentMatched. A BIP 352 silent payment paid one of your registered scan keys. See the scan-key watch below.

The matcher is decoupled from the consensus path. A dedicated task subscribes to the existing chain and mempool broadcasts, re-reads blocks and accepted transactions the node already holds, scans the watch-set, and delivers matches. A node with no subscribers pays nothing; a lock-free has_watchers() gate skips the work. A slow client's matches are dropped with notice. The matcher never stalls and never blocks consensus.

Descriptor convenience layer

AddDescriptor takes a public-key-only descriptor that rust-miniscript can parse, plus a gap_limit window. The server expands the descriptor over [start, start + gap_limit), derives the watch scripts, and registers them with the matcher.

A BIP-389 multipath descriptor (.../<0;1>/*, the canonical export form of Core, Sparrow, and BDK wallets) is split into its branches, and each branch is expanded over the same window. The descriptor therefore yields up to branches × gap_limit scripts and costs that many watch units. The branch count is capped at 2; more branches are rejected.

Expansion is bounded per branch: MAX_DESCRIPTOR_WINDOW = 1000, so a 2-branch descriptor yields at most 2000 scripts. Any secret-bearing descriptor is rejected at the type level. No signing material can be submitted, and the node stays keyless.

The server retains the descriptor-to-scripthash membership for the connection, so a window can be slid or dropped cleanly. Re-sending AddDescriptor with an advanced start reconciles the slid window server-side: scripts that leave the window are released, and scripts that enter it are added. RemoveDescriptor drops the whole window. A scripthash shared with a direct add or with another descriptor is held until its last owner is removed.

A connection may retain up to 256 distinct descriptors (MAX_DESCRIPTORS_PER_CONNECTION). At the cap, drop a descriptor with RemoveDescriptor before adding a new one. Re-asserting an existing descriptor to slide its window is always allowed.

Gap-limit advancement stays a client concern. The server manages the window it is told to manage; it does not track derivation progress and does not prompt the client to extend. The client decides when to advance start or send RemoveDescriptor.

Silent-payment scan-key watch (BIP 352, Tier 2)

This section is the Tier 2 watch reference. The dedicated Silent Payments (BIP 352) chapter compares all three consumption tiers and walks through an integration in each mode.

For clients that would rather not run a per-block scan themselves, Watch accepts BIP 352 scan-key targets. AddSilentPayments (or an atomic SetWatchSet.silent_payments replace) registers up to 16 targets per connection (MAX_SP_TARGETS_PER_CONNECTION); each is a (scan_secret b_scan, spend_pubkey B_spend) pair plus optional label integers. The node then matches every silent-payment output that pays a registered target and emits a SilentPaymentMatched carrying the output key and value, the transaction's public tweak T, and the output counter k — enough for the wallet to re-derive the full output key, and therefore its spending key, offline from its own b_scan. Targets are removed by their identity b_scan·G (RemoveSilentPayments), which the client derives locally; each costs one watch-quota unit. Matching recomputes from the block and its undo data with the same kernel the index uses, so it needs no silentpaymentindex and does zero extra work on a block when no target is registered.

A fresh wallet cold-syncs its history by registering its scan key and then issuing a bounded RescanBlocks over the taproot-activation-to-tip window. That rescan produces exactly the confirmed matches the live path would; when silentpaymentindex is enabled and fully synced it also runs faster, reading each block's tweaks from the index instead of recomputing them (verified per block against the stored row's block hash, falling back to recompute on any mismatch). The index only changes rescan speed, never which payments are found.

A match fires in two phases, like the ScriptMatched watch. When a paying transaction is accepted into the mempool the node emits the match with confirmed = false; when it later lands in a block it re-emits the same match with confirmed = true and a resume cursor. The unconfirmed phase is best-effort: a scan key registered after a transaction was already admitted matches it only once it confirms, and a replaced or evicted transaction never reaches the confirmed re-emit. Mempool matching needs each spent prevout's script to classify inputs, which the default event path does not retain — so while any scan key is registered the node keeps those scripts on each mempool entry (paid for by that watch), and drops back to retaining nothing the moment the last scan key goes away.

Operator-trust trade. A scan key lets the node run the ECDH match, so the operator — and anyone who compromises the node — learns which outputs are yours. It is not a spending key: B_spend's private half never leaves the client, so no party but you can ever spend them. The node treats the secret accordingly: scan secrets live in memory for the connection's lifetime only, are wrapped in a zeroize-on-drop buffer, and are never written to disk, a cursor, a status RPC, or a log line. A routable events bind still requires auth or mTLS, the same as every other watch kind. The zero-custody alternative is Tier 1 client-side scanning (see the streaming API reference), where the scan key never leaves the device.

Cursors & replay

Reconnect-with-cursor is the one replay mechanism for every subscription type. It subsumes Electrum's subscribe-then-get-history sequence and Esplora's per-address pagination.

• Confirmed-side replay is exact. The cursor is (height, tx_index), and replay reads straight from the block index with no extra log.
• Mempool-side replay is best-effort within a bounded in-memory window, because the mempool is not durable. Only the high-water seq is persisted.
• A process restart is detected through Cursor.instance_id. The per-publisher seq resets on restart; it is the mempool-side watermark only, never a durable confirmed-side cursor.

Reorgs are not a separate event type. ChainEvent carries a Reorg marker, followed by the per-block disconnect and connect sequence.

Authentication & quotas

The streaming API adds no new authentication surface. It reuses the unified auth layer; see Authentication & Authorization for the details. With no token store configured, the transports are open under loopback trust, matching the existing events-gRPC behavior. A remote bind requires a token store (-streamwsauth / -eventsgrpcauth, backed by -authfile).

The quota unit is one watched item; N items cost N units. Each item holds an RAII WatchLease, so Remove* returns its unit immediately, and a long-lived client can rotate a sliding watch-set without exhausting quota. Over-quota adds are rejected (RESOURCE_EXHAUSTED on gRPC, 429 on WebSocket) without tearing down the subscription.

Transport encryption (events gRPC TLS / mTLS)

Bearer auth controls who may subscribe. Over a plaintext http:// bind, the token and the event stream still travel in the clear. The events gRPC listener can terminate TLS in-process, sharing the same certificate and mTLS plumbing as the RPC, Electrum, and Esplora surfaces.

Set a certificate and key to upgrade the existing eventsgrpcbind listener to TLS. There is no separate plaintext-plus-TLS bind:

eventsgrpcbind = 0.0.0.0:50051
eventsgrpctlscert = /etc/satd/events-cert.pem
eventsgrpctlskey  = /etc/satd/events-key.pem

With mutual TLS, every client must present a certificate signed by a CA you control. Add the CA bundle and, optionally, an allowlist of accepted certificate subjects (CN or DNS-SAN). An empty allowlist accepts any certificate the CA signed:

eventsgrpcmtls          = 1
eventsgrpcmtlsclientca  = /etc/satd/clients-ca.pem
eventsgrpcmtlsclientallow = alice,bob       # optional

A remote bind must be authenticated: eventsgrpcallowremote requires either bearer auth (eventsgrpcauth) or mTLS (eventsgrpcmtls). mTLS satisfies the requirement on its own, since every client must present a CA-signed certificate. satd checks the certificate, key, and CA at startup, so a misconfiguration fails startup immediately instead of failing per-connection. The handshake timeout (eventsgrpctlshandshaketimeout, default 30s) bounds slow or probing clients. Certificates hot-reload from the same paths on SIGUSR1, like the other TLS surfaces. TLS uses the workspace ring provider exclusively.

A remote bind must also be encrypted when bearer auth is what authenticates it: eventsgrpcallowremote together with eventsgrpcauth requires eventsgrpctlscert and eventsgrpctlskey. A bearer token is sent on every RPC, and the stream can carry BIP 352 scan keys, so a routable plaintext listener puts both on the wire for every host on the path. mTLS needs no separate flag here — it already requires the certificate and key.

If a TLS-terminating reverse proxy fronts the node, keep the loopback bind and leave these options unset.

Operator limits

Every remote-facing streaming surface is bounded, so it cannot be driven to file-descriptor, memory, or task exhaustion. All of these options are restart-classified; 0 means unlimited.

Admission shedding runs before authentication and request-body buffering. A connection flood, authenticated or not, is bounded before it does any work.

Consensus-safety invariants

These guarantees are structural, not policy:

• The event bus is publish-only out of connect_block and accept_tx. The matcher only reads data the node already holds. It adds no code to the consensus path and takes no lock on it.
• A slow client never backpressures the publisher. Degradation is drop-with-notice: the broadcast send is non-blocking and lossy, and per-subscriber delivery uses a non-blocking try_send.
• Streaming listeners run on the API runtime only, never on the core block-connecting runtime.

Silent Payments (BIP 352)

A BIP 352 silent-payment address (sp1…) is a reusable, static address that produces a unique, unlinkable taproot output on chain for every payment it receives. Nothing on chain connects two payments to the same address, and nothing identifies an output as a silent payment at all. The cost of that privacy falls on the receiver: finding your own payments means running an ECDH computation against candidate transactions, because there is no address string to look up.

satd implements the receive side: a tweak index, a streaming tweak firehose with cursor replay, mempool-time detection, and an optional server-side scan-key matcher, with typed support in both SDKs. The matching kernel is tested for parity against the BIP 352 reference vectors. Everything is opt-in; a node that enables none of it behaves exactly as before.

This chapter is the integrator guide: what each consumption mode gives you, how to pick one, and how to operate the index behind them. The wire-level contract lives in the streaming API specification (§7.7).

In the node, not beside it

Silent-payment support follows the same one-process, one-store model as satd's Electrum and Esplora surfaces: the tweak index is written inside block connection, atomically with the chainstate, and the serving and matching layers read it in-process from the same RocksDB store the node validates against. There is no companion indexer to keep in sync and no window where an external index's view lags the node across a reorg — rows are removed in the same batch that disconnects the block, and tweak events carry the block's own hash so a client re-anchors from the (block_hash, height) it already holds.

For context: Bitcoin Core has no silent-payment support in any released version as of this writing (August 2026), so receiving against a stock node means running a separate tweak-indexing daemon and serving layer beside it, each with its own sync state and reorg handling. satd's index produces the same per-block public tweak data such stacks do, served over the streaming API and a JSON-RPC method instead of a sidecar's own protocol.

The trade-off, as with every satd index, is local disk — measured in Disk Footprint & Indices.

Choosing a tier

Three consumption modes ride on the streaming surface. They differ in who runs the ECDH scan, and therefore in who ever sees your scan key.

Tier 1 is the recommended, zero-custody mode. The node streams each block's public tweak data (BlockTweaks, category bit 8 — explicitly requested, never part of the categories = 0 default); the wallet runs one ECDH per tweak locally. The scan key never leaves the device, and the node learns nothing about which outputs are yours. Because every stored row embeds the hash of the block it describes, tweaks-only replay is exempt from the usual MAX_REPLAY_BLOCKS clamp: a fresh wallet cold-syncs the entire taproot era in one from_cursor subscription, paged and backpressured server-side.

Tier 1.5 is Tier 1 at mempool latency. Setting mempool_tweaks = true alongside bit 8 additionally delivers a MempoolTweak at each eligible transaction's admission — the same 33-byte tweak its later BlockTweaks entry will carry, plus the transaction's taproot outputs so a match is confirmed in-band without a getrawtransaction race. It is best-effort like the mempool itself: no durable cursor, no replay, no retraction on RBF (dedup by txid; the confirmed record at connect stays authoritative). A payment missed while offline is simply caught at confirmation.

Tier 2 moves the scan to the node. Register up to 16 (scan_secret, spend_pubkey) targets per connection and the node emits a SilentPaymentMatched for every output paying you — at mempool admission with confirmed = false, then again at confirmation with confirmed = true and a resume cursor. Each match carries the transaction's public tweak T and output counter k, which is exactly enough for the wallet to re-derive the output's full spending key offline from its own b_scan and b_spend. This mode works on any satd node: matching recomputes from the block and its undo data with the same kernel the index uses, so it needs no silentpaymentindex and costs the node nothing while no target is registered.

The trust trade is explicit: a scan key lets the node — and anyone who compromises it — learn which outputs are yours. It is not a spending key; b_spend's private half never leaves the client, so no one else can ever spend them. The node treats the secret accordingly: scan secrets live in memory for the connection's lifetime only, wrapped in a zeroize-on-drop buffer, never written to disk, a cursor, a status RPC, or a log line. Both SDKs refuse to send one over a plaintext transport that carries a bearer token, and a routable events bind requires auth or mTLS like every other watch kind. Pointing a thin client at your own node keeps the disclosure inside your trust boundary; pointing it at someone else's node is a choice to extend that boundary to them.

The tweak index

Tier 1 and 1.5 serve from the sp_tweaks index: one row per block from taproot activation upward (height 709,632 on mainnet — earlier blocks cannot carry silent payments), holding the public tweak T = input_hash · A for every eligible transaction. Rows are written inside block connection, removed on disconnect, and rebuilt by -reindex-chainstate. A row is present even for a block with no eligible transactions, so row presence distinguishes "indexed, none" from "not indexed", and every row embeds its block's hash, so readers authenticate it without trusting the height-to-hash index.

Enable it with:

# bitcoin.conf — default off, restart to change
silentpaymentindex=1

A node that syncs from genesis with the flag set builds the index inline. To add it to an existing datadir, run the deferred backfill:

sat-cli backfillindex silentpayment

The backfill walks from taproot activation to the snapshot height pinned at start, resumes across daemon restarts, and answers to the generic index controls (pauseindex / resumeindex / cancelindex silentpayment). It refuses to start with less than 6 GiB of free disk. Progress is visible three ways, all reporting the same walk-relative ratio:

• getsatdindexinfo → the silentpayments section: enabled, synced, and a backfill object with state, cursor_height, snapshot_height, progress_ratio, and estimated_remaining_seconds. Use the reported progress_ratio, not cursor_height / snapshot_height — the latter measures from genesis and overstates a mainnet backfill from its first block.
• sat-tui → the services row's sp-idx column.
• Prometheus → the satd_spindex_* family; see Observability & Metrics.

Until the backfill completes, the tweak-serving surfaces refuse rather than return a partial result: a from_cursor tweak replay is rejected in-band so a light client can never silently miss payments below the backfill frontier.

What it costs, measured on a synced mainnet node (August 2026): ~13 GB for the full taproot era, growing ~1 GB/year at the recent eligible-transaction rate, with a mainnet backfill taking 6 h 46 m. The full accounting, including the estimator's stint semantics and the row format, is in Disk Footprint & Indices.

Serving tweaks (Tier 1 on the wire)

With the index enabled and synced, a gRPC Subscribe with category bit 8 streams one BlockTweaks per connected block, shaped by five per-subscription knobs:

• tweak_dust_limit — drop entries whose largest eligible output is below the floor (in sats). At 546 sat this trims roughly 10% of mainnet entries.
• tweaks_only — strip txid and max_value, leaving the 33-byte tweak alone: the leanest form for bulk cold-sync.
• mempool_tweaks — additionally stream MempoolTweak at admission (Tier 1.5).
• tweak_outputs — include each entry's taproot outputs, re-derived at serve time, so matches confirm in-band. Off by default because it makes replay read each block; MempoolTweak always carries its outputs regardless.
• tweak_unspent_only — cut-through: drop entries whose taproot outputs are all already spent. Entries that survive carry their full output set. The biggest single saving on a cold sync, and the one knob with a correctness caveat, below.

Cut-through is a balance scan, not a restore. tweak_unspent_only asks the node "is this coin still there?", answered against the UTXO set at the moment the event is served — not against the chain as of that height. A payment received at height H and spent at H+100 is therefore absent from a scan of H that runs today. A wallet that wants a current balance loses nothing and skips the ECDH for every coin that no longer exists; a wallet reconstructing its transaction history must leave the flag off, or the history will omit everything it has already spent. Entries dropped this way set the block's filtered flag, so an empty block is never mistaken for one with no eligible transactions.

Spentness decides only whether an entry survives — never which outputs a surviving entry carries. Scanning walks k = 0, 1, 2, … and stops at the first k with no match among the outputs it was given, so an entry trimmed to just its unspent outputs would cut the walk short and hide a live coin at a higher k. An entry with one spent and one live output therefore arrives carrying both. Like tweak_outputs, it re-derives outputs from the block, so it needs a block source and reads one block per event. It never applies to MempoolTweak — an unconfirmed output is in no confirmed UTXO set.

The firehose serves on gRPC only — the WebSocket/SSE transports do not carry the tweaks category. For scripts and integrators not on an SDK, getsilentpaymentblockdata "blockhash" ( verbosity dust_limit ) returns the same per-block bytes over JSON-RPC; see JSON-RPC Extensions.

Serving tweaks to existing wallets (Electrum)

The streaming API is the better protocol — durable cursors, mempool-time tweaks, reorg anchors — but no third-party wallet speaks it yet. The wallets that do scan silent payments today speak blockchain.tweaks.subscribe on the Electrum port, so satd serves that method too, from the same index and with the same tweaks:

electrum=1
silentpaymentindex=1

It is a stream rather than a call (the JSON-RPC result is the first height, the rest arrive as notifications, {"message":"done"} ends the chunk), and its historical_mode parameter is the cut-through trade described above with the polarity flipped: false cuts spent coins, true keeps them for a restore. The Electrum chapter has the wire shape and the per-network behaviour. Nothing here needs an operator decision: Cake Wallet probes the method only when the advertised server name contains electrs, and satd's default name does, so enabling the index above is enough.

Walkthrough: a zero-custody light wallet (Tier 1)

The shipped SDK examples are the reference implementations — sp_light_scan.rs (Rust) and sp_light_scan (Go) — each a complete scanner in one file: subscribe, ECDH, label handling, in-band output confirmation, and a restart-durable resume cursor. The shape, in Rust:

let opts = SubscribeOptions {
    categories: Categories::TWEAKS,   // bit 8 — never implied by "all"
    mempool_tweaks: true,             // Tier 1.5: detect at admission
    tweak_outputs: true,              // confirm matches in-band
    // Cold-start anchor, used only when the cursor file is empty. A cursor
    // names the last height already done, so `activation - 1` scans the
    // activation block itself.
    from_cursor: Some(Cursor { height: 709_631, ..Default::default() }),
    ..Default::default()
};
let mut sub = client.resilient_subscribe(
    opts,
    ResilientConfig::new().cursor_store(Arc::new(FileCursorStore::new(path))),
);
loop {
    // Propagate, never `while let Ok(..)`: `next()` returns `Err` on every
    // PERMANENT failure — a corrupt cursor file, a rejected subscribe (an index
    // still backfilling answers `FAILED_PRECONDITION`), retries exhausted.
    // Swallowing that exits the loop silently and the wallet reports a zero
    // balance it never actually scanned for.
    let event = sub.next().await?;
    // scan, then poll again — the next poll commits this event's cursor
}

For each TweakEntry, the wallet computes locally, per BIP 352:

ecdh  = b_scan · T                                  // one point multiply per entry
t_k   = hash("BIP0352/SharedSecret", ecdh ‖ k)      // k = 0, 1, … per candidate output
P_k   = B_spend + t_k · G                           // expected output key

and compares P_k's x-only form against the transaction's taproot outputs — carried in the event itself under tweak_outputs, so no follow-up RPC is needed. A payment to a labeled address (BIP 352 §5) shifts P_k by the label tweak; scan with each of your labels, and include label 0 even if you issue none, because label 0 is how your own change comes back. On a match, the spending key is b_spend + t_k (plus the label tweak if any) — derived entirely on the device.

Cold-sync is the same subscription with a from_cursor at taproot activation; the replay is unclamped, index-backed, and ends in-band on any storage error rather than skipping a height.

The resume anchor to persist is the cursor of the last event you have finished scanning, not the last one delivered — a cursor written ahead of the work it stands for turns a crash into a silently skipped block, and for a scanner a skipped block is a missed payment. Both SDKs get this right for you: a ResilientSubscription with a CursorStore commits on poll, writing an event's cursor only when you come back for the next one, so an interrupted scan replays its last block instead of stepping over it. Use that rather than hand-rolling persistence around the raw stream; both reference examples do (sp_light_scan.rs, sp_light_scan). The mirror-image slip — persisting the previous event's cursor — costs only a repeated scan, and has shipped in a production wallet (cake_wallet#3574).

Walkthrough: a thin client with a registered scan key (Tier 2)

The reference implementations are sp_wallet.rs and sp_wallet. The shape, in Go:

target := satdevents.SilentPaymentTarget{
    ScanSecret:  bScan,          // disclosed to the node: a watch credential, not a spend key
    SpendPubkey: spendPubkey,    // public half only; b_spend never leaves the client
    Labels:      []uint32{0},    // label 0 catches your own change
}
handle.AddSilentPayments(ctx, []satdevents.SilentPaymentTarget{target})

From here the node does the scanning. Each SilentPaymentMatched arrives twice — once at mempool admission (confirmed = false, best-effort) and once at confirmation (confirmed = true, with a resume cursor) — and carries the output key and value plus the public tweak T and counter k, from which the client re-derives the full spending key offline exactly as in Tier 1. Targets are removed by their identity b_scan · G, which the client derives locally; each target costs one watch-quota unit.

A fresh wallet cold-syncs by registering its targets and issuing a RescanBlocks over the taproot-activation-to-tip window. The rescan produces exactly the matches the live path would have; on a node whose tweak index is enabled and complete it also runs faster, reading each block's tweaks from the index (verified per block against the stored row's embedded hash) instead of recomputing them. The index changes rescan speed, never results.

Both SDKs' ResilientWatch re-registers scan-key targets automatically on reconnect, so a dropped connection never silently stops the watch; see the Rust SDK and Go SDK chapters for the reconnect-and-resume contract and the TLS posture around scan secrets.

Rust SDK (satd-events-client)

satd-events-client is the async Rust client for the Streaming Consumption API. The gRPC contract is fully specified and a generated tonic client exists, but the generated client is raw. Every consumer otherwise hand-writes the same channel wiring, authorization metadata injection, cursor capture and persistence, lag recovery, reconnect with backoff, and, for prefix watches, local re-filtering. The SDK absorbs all of that behind a small typed surface. A consumer can watch outpoints in ten lines instead of a hundred.

It is the recommended way to consume the streaming API from Rust. Go consumers have a full-parity sibling in the Go SDK (satdevents); every other language uses the gRPC/WebSocket surface directly against the .proto contract.

Note. Getting Started: Consuming Events walks the whole sequence, from connect through firehose, durable watch, and prefix privacy, one runnable step at a time. This chapter is the per-method reference it links back to.

Crate layout

The wire types are generated once in satd-events-proto, a thin tonic/prost crate shared by the node's server and this client. The SDK therefore pulls in no server glue: no node crate, no RocksDB. On top of the proto crate, satd-events-client depends on tonic, prost, tokio, tokio-stream, thiserror, tracing, and an optional bitcoin.

[dependencies]
satd-events-client = "0.6"

Note. The crate is not yet on crates.io. Until the published release lands, depend on it via git and read its API docs locally:

satd-events-client = { git = "https://github.com/epochbtc/satd", branch = "master" }

cargo doc -p satd-events-client --no-deps --all-features --open

The default build includes the bitcoin feature, which provides the prefix-watch re-filter and the scripthash helpers. For a minimal dependency tree that hands you raw bytes to filter yourself:

satd-events-client = { version = "0.6", default-features = false }

Note that this also drops the default-on tls feature, which is not merely a smaller dependency tree — it is a plaintext-only client. Keep tls unless the node is genuinely reachable over loopback only:

satd-events-client = { version = "0.6", default-features = false, features = ["tls"] }

Connecting

use satd_events_client::{StreamClient, SubscribeOptions, Categories, Event};

let mut client = StreamClient::builder("https://node:50051")
    .tls()
    .bearer_token(token)     // sent as `authorization: Bearer …` on every call
    .keepalive_default()     // http2 keepalive matching the server (30s/20s)
    .connect()
    .await?;

The bearer token is honored only when the server enforces auth (-eventsgrpcauth). The client's Debug impl redacts the token and never prints TLS key material.

A token requires an encrypted endpoint

connect() returns StreamError::InsecureCredential for a bearer token combined with a non-https:// endpoint, rather than putting the credential on the wire in the clear. Anyone who captures the token can subscribe to the firehose and register watches; on a Tier 2 scan-key watch the same stream also carries BIP 352 scan secrets, which disclose which outputs belong to the receiver.

tonic selects TLS from the URI scheme alone, so https:// is the thing that decides — a scheme-less node:50051 is plaintext even with .tls() called (and is rejected for that separately).

For loopback and test harnesses, insecure_bearer_token(token) is the same thing with the risk accepted explicitly. It is a separate method rather than a flag so the unsafe choice has to be named at the call site, and so that switching back to bearer_token cannot silently leave the waiver behind.

TLS / mTLS

The default tls feature encrypts the transport, so neither the token nor the event stream crosses the network in the clear. The node terminates TLS natively (eventsgrpctlscert/eventsgrpctlskey; see the Streaming chapter).

// Public-CA server: trust the bundled Mozilla roots.
let client = StreamClient::builder("https://node.example:50051")
    .tls()
    .bearer_token(token)
    .connect()
    .await?;

// satd node with its own (self-signed) CA: pin it.
let ca = std::fs::read("node-ca.pem")?;
let client = StreamClient::builder("https://10.0.0.5:50051")
    .tls_ca_pem(ca)
    .tls_domain("node.example")          // when connecting by IP / through a proxy
    .bearer_token(token)
    .connect()
    .await?;

// Mutual TLS (server set with `eventsgrpcmtls=1`): present a client certificate.
let client = StreamClient::builder("https://node.example:50051")
    .tls_ca_pem(std::fs::read("node-ca.pem")?)
    .tls_client_identity(std::fs::read("client-cert.pem")?, std::fs::read("client-key.pem")?)
    .connect()
    .await?;

tls_ca_pem pins exactly that authority; the bundled public roots are then not used. Plain tls() uses the public roots. TLS uses the ring rustls provider. For a plaintext-only minimal build, depend with default-features = false.

In a build without the tls feature, no endpoint is encrypted — including an https:// one. tonic gates its own https handling behind its tls feature, so without it an https:// URI opens a plain TCP connection and speaks cleartext h2c rather than failing. bearer_token() therefore refuses every endpoint in such a build; if you need a token, keep the tls feature.

Firehose: subscribe

let mut events = client.subscribe(SubscribeOptions {
    categories: Categories::MEMPOOL | Categories::CHAIN,
    from_cursor: persisted_cursor, // durable replay anchor; None = forward-only
    since_seq:   None,             // forward-only dedup within the broadcast window
}).await?;

while let Some(event) = events.message().await? {
    match event {
        Event::BlockConnected { height, .. } => println!("block {height}"),
        Event::MempoolEnter { txid, fee, vsize, .. } => { /* … */ }
        Event::Lagged { resume_cursor, .. } => { /* reconnect from resume_cursor */ }
        _ => {}
    }
}

Event is a flat enum mirroring the proto oneof body, so you match instead of unwrapping nested Options. As confirmed events flow, the stream captures their durable Cursor, and events.cursor() returns the latest. Persist it and present it again as from_cursor to resume exactly where you left off — persist the cursor of the last event you have finished processing, since anything written ahead of the work it stands for is skipped outright after a crash. resilient_subscribe (below) does that sequencing for you.

Durable firehose: resilient_subscribe

For a long-lived consumer, resilient_subscribe wraps the firehose in a ResilientSubscription that handles the failure modes:

use std::sync::Arc;
use satd_events_client::{ResilientConfig, FileCursorStore, Event};

let config = ResilientConfig::new()
    .cursor_store(Arc::new(FileCursorStore::new("/var/lib/app/satd.cursor")));

let mut sub = client.resilient_subscribe(opts, config);
loop {
    match sub.next().await? {
        Event::ReplayGap { resume_height, first_height } => {
            // replay was clamped: blocks (resume_height, first_height) were
            // skipped; full-resync them from another source
        }
        event => handle(event),
    }
}

What it absorbs:

• Reconnect with backoff. Transport errors and clean server closes trigger an exponential-backoff reconnect (Backoff, capped, optionally bounded by max_retries). next() returns Err only on a permanent failure or exhausted retries.
• Cursor persistence, committed on poll. Confirmed cursors are written to a CursorStore. The default is NoopCursorStore; use FileCursorStore for restart-durable resume, or your own impl over a database. A reconnect and a process restart both resume from the stored anchor. A delivered event's cursor is persisted only when you call next() again — an implicit ack — so the store never advances past an event you have not finished handling, and a crash mid-processing replays it. That makes delivery at-least-once, not at-most-once: dedup on your side if you need exactly-once. commit() writes the pending anchor before a clean shutdown, so the last event handled is not replayed on the next start.
• Lag recovery. Under the default LagPolicy::AutoResume, a Lagged notice becomes a reconnect from its resume_cursor. LagPolicy::Surface hands the notice to you instead.
• Replay-truncation detection. The server clamps a far-behind cursor's replay to the most recent MAX_REPLAY_BLOCKS (10,000) blocks. When that happens, the SDK emits a synthetic Event::ReplayGap before the first replayed block, naming the skipped range, so you can full-resync it rather than silently receiving a gap.
• instance_id handling. The full cursor replays verbatim. On a restart mismatch the server discards a stale mempool_seq; confirmed (height) replay is unaffected.

Watches: watch

watch opens the bidirectional stream and returns a WatchHandle plus the event stream. The handle has a typed helper for every watch kind. Empty inputs are no-ops, and dropping the handle tears the stream down.

let (watch, mut events) = client.watch().await?;

watch.add_scripts([(scripthash, Some(100_000))]).await?;  // per-script min_value floor (sat)
watch.add_outpoints([(txid, vout)]).await?;
watch.add_tx_lifecycle([txid], AutoClose::AtDepth(6)).await?;
watch.add_depth_alarms([txid], [1, 3]).await?;            // cross product txids × depths
watch.add_descriptor(descriptor, /*gap*/ 20, /*start*/ 0).await?;  // multipath <0;1> ⇒ 2×gap scripts
watch.add_script_prefixes([(prefix_bytes, 16)]).await?;   // privacy-preserving prefix
watch.set_categories(mask).await?;
watch.set_cursor(cursor).await?;                          // mid-stream re-anchor (best-effort)
watch.remove_scripts([scripthash]).await?;                // releases quota immediately

The helpers absorb some sharp edges of the wire protocol:

• Depth alarms versus lifecycle. add_tx_lifecycle sends an empty min_depths, which the server reads as a lifecycle add. add_depth_alarms sends the depths and filters out depth < 1 client-side, so an all-invalid call is a true no-op rather than an accidental lifecycle add.
• min_value floors. The floors run parallel to the scripthashes. A None floor delivers everything, a floor of 0 also delivers everything, and a non-zero floor suppresses matches below it server-side, symmetric across funding and spend sides.
• set_cursor reports its outcome in-band. Ok(()) means the re-anchor was sent, not that it ran. The server answers on the event stream with exactly one Event::CursorAccepted { clamped, earliest_replayed, .. } (admitted and replaying; clamped flags an authoritative replay-window gap) or Event::CursorRejected { reason, .. } with reason RateLimited, ConcurrentReanchor, EmptyCursor, or NoSource. Drive your catch-up off those events rather than treating Ok(()) as success, or use resilient_watch (below), which does this for you.

Durable watch: resilient_watch

watch gives you the raw bidirectional stream; resilient_watch wraps it the way resilient_subscribe wraps the firehose, plus the extra work the Watch stream needs. The watch-set is per-connection: when the stream drops, the server discards your watch-set and quota leases, so a bare reconnect comes back blind.

ResilientWatch closes that gap:

• Watch-set mirror. It records every add_* / remove_* / set_categories you make and re-registers the whole set on each reconnect. You keep calling the same typed helpers, now on ResilientWatch.
• Re-anchor off the deterministic result. After re-registering, it set_cursors to the persisted high-water mark and drives catch-up off the in-band ack. A transient CursorRejected (RateLimited / ConcurrentReanchor) is backed off and retried in place. A CursorAccepted { clamped: true, .. } or a terminal reject (NoSource) is surfaced so you can resnapshot; that path is the exception, not the everyday fallback.
• Cursor persistence and backoff. It reuses the same CursorStore and Backoff as resilient_subscribe, committing confirmed cursors on poll.

use satd_events_client::{ResilientWatchConfig, FileCursorStore, Event, AutoClose};
use std::sync::Arc;

let config = ResilientWatchConfig::new()
    .cursor_store(Arc::new(FileCursorStore::new("/var/lib/app/watch.cursor")));
let mut watch = client.resilient_watch(config);

// Register interest once; it is replayed automatically across reconnects.
watch.add_scripts([(scripthash, None)]).await?;
watch.add_tx_lifecycle([txid], AutoClose::AtDepth(6)).await?;

loop {
    match watch.next().await? {
        // `descriptors` attributes a descriptor-derived hit back to its
        // descriptor + (branch, derivation_index) (empty for a direct watch).
        Event::ScriptMatched { txid, descriptors, .. } => { let _ = descriptors; }
        Event::CursorAccepted { clamped: true, earliest_replayed, .. } => {
            // Authoritative gap: full-resync confirmed history below
            // `earliest_replayed` from another source.
        }
        Event::CursorRejected { reason, .. } => { /* escalate to a resnapshot */ }
        _ => {}
    }
}

It is single-task, like ResilientSubscription: interleave watch-set edits with next() calls from one task, reacting to a match and then adjusting the watch-set. A descriptor replays from its latest (gap_limit, start), so advance start to slide the window across reconnects; the server reconciles the slid window. remove_descriptor(descriptor) drops the descriptor and releases every scripthash whose last owner it was. A script shared with a direct add or another descriptor stays.

Watch-set loader

The mirror above is authoritative only when you build the watch-set once at startup and never change it during the process lifetime. Often the watch-set has a durable source of truth outside the wrapper: a database table, a config file, an upstream service. The mirror is then a cache of that truth, and two gaps open. A process restart starts with an empty mirror, so there is nothing to replay. And a change to the truth while the stream is down (an entity added, removed, or rekeyed through your own API) leaves the mirror stale until the next in-process edit happens to touch it.

watch_set_loader closes both gaps. It runs once after every (re)connect, before the event stream resumes, and rebuilds the canonical set from your truth into a fresh WatchSetBuilder. The first events after a reconnect land on a fully populated subscription, and a restart rehydrates from truth instead of from an empty mirror:

use satd_events_client::{ResilientWatchConfig, FileCursorStore, WatchSetBuilder};
use std::sync::Arc;

let db = Arc::new(my_watch_db());
let config = ResilientWatchConfig::new()
    .cursor_store(Arc::new(FileCursorStore::new("/var/lib/app/watch.cursor")))
    .watch_set_loader({
        let db = db.clone();
        move |builder: WatchSetBuilder| {
            let db = db.clone();
            async move {
                // Query the source-of-truth and declare the canonical set.
                for row in db.load_watched_scripts().await? {
                    builder.add_scripts([(row.scripthash, row.min_value)]);
                }
                Ok(())
            }
        }
    });
let mut watch = client.resilient_watch(config);

Semantics:

• Canonical on every connect. The loaded set replaces the mirror. You can still call add_* / remove_* for live edits within the current connection, but the next reconnect re-derives the set from the loader. Your truth, not the accumulated in-process edits, is the record across reconnects. Persist a hot-add to your truth and the loader picks it up on the next connect.
• The cursor is independent. Resume still comes from the CursorStore / from_cursor. The re-anchor runs after the loaded set is registered, exactly as without a loader.
• Loader errors are transient. A failure maps to StreamError::WatchSetLoader and is backed off and retried on the next connect. A momentary outage of your source of truth must not crash an at-least-once consumer.

WatchSetBuilder exposes the declarative add_* / set_categories surface. There is no remove_*, because you are building a complete set into an empty mirror. Omit the loader and behavior is exactly the mirror replay described above.

Reloading mid-stream: reload()

The loader fires on every reconnect. Sometimes the durable truth changes while the stream is up: a bulk import writes rows outside your hot-add path, an admin rotates keys, or an operator wants the wire to match truth now. reload() re-runs the loader and pushes the freshly loaded set as a single atomic SetWatchSet:

let summary = watch.reload().await?;   // ReloadSummary { added, removed, unchanged, applied }
tracing::info!(?summary, "watch-set realigned with truth");

• One atomic replace, server-reconciled. reload() sends the whole desired set in one SetWatchSet message. The server reconciles it under its watch-set lock, by effective scripthash coverage (descriptors expanded). The client never sends a computed Add*/Remove* delta, so no message ordering can strand coverage or over-charge at quota. An item watched in both the old and new set is kept without a re-registration, even if its mechanism changes (a direct script becoming descriptor-covered, or the reverse), so the matcher sees no gap. Quota is all-or-nothing on the whole target.
• Deterministic result. The outcome arrives in-band on next() as Event::WatchSetReplaced { added, removed, unchanged } with the server's authoritative counts, or Event::WatchSetRejected { reason, required, quota }. reason is QuotaExceeded (the target does not fit quota; shed and retry), CapExceeded (more entries than the per-connection cap, which applies even with no quota; shed and retry), or Malformed (the server could not parse an element of the snapshot; this is a client bug, and retrying the same set will not help). In every case the live set is left unchanged. The ReloadSummary returned by reload() carries advisory client-side counts; the Event is the source of truth.
• Atomic with respect to your task. &mut self serializes reload() against your add_* / next() on the single task.
• Disconnected defers, never errors. With the stream down there is nothing to apply now. The mirror is still updated, and the next reconnect's loader re-registers it. ReloadSummary::applied tells you which happened.
• Returns ReloadError::NoLoader if no loader is configured, or ReloadError::Loader if the loader itself fails. A loader failure is surfaced, not retried; you decide whether to call again.

reload() reuses the wrapper's backoff, cursor re-anchor, and loader plumbing, so there is no need to drop and rebuild the wrapper to force a full re-push.

Prefix watches (privacy-preserving)

A prefix watch registers a coarse bits-bit prefix of sha256(scriptPubKey). The server delivers every transaction in that 2^-bits bucket, so it learns only the bucket, never your exact script. You filter the decoys out locally. PrefixWatcher (the bitcoin feature) is that filter:

use satd_events_client::{PrefixWatcher, Event};

let mut watcher = PrefixWatcher::new();
watcher.watch_script(&my_script_pubkey);

let (watch, mut events) = client.watch().await?;
watch.add_script_prefixes(watcher.prefixes(16)).await?;   // dedup'd bucket set

while let Some(event) = events.message().await? {
    if let Event::PrefixMatched(m) = event {
        let hits = watcher.filter(&m)?;     // decodes raw_tx, recomputes sha256(spk)
        for f in &hits.funding { /* true output match */ }
        for s in &hits.spending { /* true spend match */ }
        if hits.has_unresolved() {
            // spend-side prevout the server didn't retain (mempool below the
            // `full` tier): resolve the outpoint yourself before concluding
            // non-match; never treat absent as zero
        }
    }
}

prefixes(bits) derives the deduplicated bucket set to register; scripts sharing a bucket collapse to one. filter returns only genuine matches plus the outpoints it could not resolve locally. It never issues a precise follow-up fetch, which would re-leak the interest the bucket exists to hide. See the Streaming API chapter for the streamprevoutmeta retention tiers, which govern what the spend side carries.

Errors

StreamError classifies the conditions that stop forward progress. The Lagged notice is not among them; it is a normal, recoverable Event. Use StreamError::is_retryable() to decide whether to back off and retry (Connect, transient transport codes, QuotaExhausted) or give up (PermissionDenied, a bad URL or token, client-side argument errors). Unauthenticated is reported non-retryable: re-auth and reconnect rather than blind-retrying the same token. QuotaExhausted is treated as retryable because its common causes, the subscription cap and the per-principal rate limit, are transient. A full watch quota is not transient, so inspect the boxed status message before retrying a watch-add forever.

Stability & versioning

The crate's version is the satd version it was released with (it inherits the workspace version), and it follows semver. Pick an SDK whose minor version is at or below your node's: satd-events-client 0.6 is built for satd 0.6 and works unchanged against 0.7, 0.8 and later nodes, which only add fields and event kinds within schema_version 1.

Each time subscribe or watch opens a stream, the SDK reads the version the node advertises in its satd-version response header and compares it with its own:

A node older than 0.6.0 sends no header and counts as 0.5. The warning means "upgrade the node": features added after the node's release are unavailable, and request fields it does not recognise are ignored. For a rolling upgrade where clients go first, StreamClient::builder(..).allow_old_node() turns NodeTooOld into the same warning. Nothing bypasses a schema mismatch. Both errors are non-retryable, so the resilient layers surface them instead of reconnecting. StreamClient::node_version() returns what the node last advertised. The full rule is in STABILITY_POLICY.md.

The generated wire types are re-exported under proto, so you can pin to the schema directly when a typed helper does not yet cover your case. The minimum supported Rust version (MSRV) is 1.93; an MSRV bump is treated as a minor-version change. The underlying gRPC contract is the streaming spec.

Examples

Runnable examples live in satd-events-client/examples/: firehose_tail, resilient_tail, resilient_watch, watch_outpoints, descriptor_wallet, lifecycle_alarms, prefix_privacy, health_watch, plus tls_tail and mtls_tail over an encrypted transport.

health_watch is the alerting shape: subscribe with Categories::STATUS, track raise/clear pairs to hold "what is wrong right now", and route by severity so a condition your build predates still reaches the right place.

cargo run -p satd-events-client --example resilient_tail -- http://127.0.0.1:50051 /tmp/satd.cursor
cargo run -p satd-events-client --example resilient_watch -- http://127.0.0.1:50051 /tmp/satd-watch.cursor
cargo run -p satd-events-client --example tls_tail -- https://node.example:50051 ./node-ca.pem
cargo run -p satd-events-client --example health_watch -- http://127.0.0.1:50051

Go SDK (satdevents)

satdevents is the Go client for the Streaming Consumption API. It is a full-parity sibling of the Rust SDK — same surface, same guarantees, expressed in Go idiom rather than transliterated from Rust.

It lives in the satd repository at clients/go/, as an independently versioned Go module:

go get github.com/epochbtc/satd/clients/go

import satdevents "github.com/epochbtc/satd/clients/go"

Only Go is needed — no Rust toolchain, no protoc. The protobuf bindings are committed, and CI regenerates them on every PR and fails on a diff, so they cannot drift from the .proto.

Note. Getting Started: Consuming Events walks the whole sequence — connect, firehose, durable watch, prefix privacy — one step at a time. It is written against the Rust SDK, but the sequence and the concepts are identical here; the mapping table below is the translation key.

Module layout & dependencies

The published SDK's dependency graph is gRPC and protobuf, and nothing else. That is a deliberate constraint, not an accident of being small: a client library that drags a Bitcoin stack or a secp256k1 implementation into every consumer forces version bumps on applications that already have their own. So:

• Script and txid parameters are []byte and [32]byte with helpers, never library-specific types. Bring whatever Bitcoin library you already use, or none.
• Silent-payment scan-key validation is an in-tree on-curve check rather than a curve dependency.
• Code generators, linters, the E2E suite, and the examples each live in their own nested module, so what they need never reaches a consumer.

The go directive tracks one release behind the latest stable Go, covering Go's two-release support window.

Rust → Go mapping

Where the two languages' idioms diverge, the Go shape wins. Nothing is dropped; this table is the translation key.

Connecting

client, err := satdevents.Dial(ctx, "node:50051",
    satdevents.WithTLSCAPem(caPEM),
    satdevents.WithBearerToken(token), // sent as `authorization: Bearer …`
)
defer client.Close()

Dial accepts host:port, optionally with an http:// or https:// scheme (stripped, for symmetry with the Rust client and the -eventsgrpcbind documentation). It does not block on the connection coming up — gRPC connects lazily, and the first Subscribe or Watch surfaces a connection failure.

Keepalive matching the server (30s/20s) is on by default; WithoutKeepalive and WithKeepalive override it.

The bearer token is honored only when the server enforces auth (-eventsgrpcauth).

A token requires an encrypted connection

Dial returns a KindInsecureCredential error (errors.Is(err, ErrInsecureCredential)) for a bearer token combined with an insecure transport, rather than putting the credential on the wire in the clear. Anyone who captures the token can subscribe to the firehose and register watches; on a Tier 2 scan-key watch the same stream also carries BIP 352 scan secrets, which disclose which outputs belong to the receiver.

gRPC-Go's own safety net does not cover this. It refuses to attach a PerRPCCredentials whose RequireTransportSecurity() reports true to an insecure channel, but this SDK attaches the token with metadata.AppendToOutgoingContext, which that check never sees.

Any WithTLS* option satisfies the requirement, as does an https:// target. For loopback and test harnesses, WithInsecureBearerToken(token) is the same thing with the risk accepted explicitly. It is a separate option rather than a flag so the unsafe choice has to be named at the call site, and so that switching back to WithBearerToken cannot silently leave the waiver behind.

TLS / mTLS

// Pin a satd node's own (self-signed) CA — the usual case.
client, err := satdevents.Dial(ctx, "node.example:50051",
    satdevents.WithTLSCAPem(caPEM),
    satdevents.WithBearerToken(token),
)

// Publicly trusted certificate: the system roots.
client, err := satdevents.Dial(ctx, "node.example:50051", satdevents.WithTLS())

// Mutual TLS, against a node with `eventsgrpcmtls=1`.
client, err := satdevents.Dial(ctx, "node.example:50051",
    satdevents.WithTLSCAPem(caPEM),
    satdevents.WithMTLS(certPEM, keyPEM),
)

WithTLSServerName overrides the verified name, for dialing by IP or through a tunnel.

Requesting TLS against an explicit http:// target is refused, not silently downgraded. That combination can only be a mistake, and connecting in cleartext would leak the token and the whole event stream while the caller believed the link was encrypted.

Firehose: Subscribe

stream, err := client.Subscribe(ctx, satdevents.SubscribeOptions{
    Categories: satdevents.CategoryMempool | satdevents.CategoryChain,
})

for {
    ev, err := stream.Recv()
    if err != nil {
        if errors.Is(err, io.EOF) { break }
        return err
    }
    switch e := ev.(type) {
    case *satdevents.BlockConnected:
        log.Printf("block %d %s", e.Height, satdevents.DisplayHex(e.Hash))
    case *satdevents.MempoolEnter:
        log.Printf("tx %s fee=%d", satdevents.DisplayHex(e.Txid), e.Fee)
    }
}

CategoryAll (zero, the default) means every category except CategoryTweaks and CategoryStatus, which are explicit-request only. That exclusion is what keeps a client written against an older node from suddenly receiving a body it has no parser for after the node is upgraded — so if you want status or tweak events, ask for them by name.

stream.Cursor() returns the latest durable resume position. Persist it to resume later.

Durable firehose: ResilientSubscribe

sub := client.ResilientSubscribe(ctx,
    satdevents.SubscribeOptions{Categories: satdevents.CategoryChain},
    satdevents.ResilientConfig{
        CursorStore: satdevents.NewFileCursorStore("/var/lib/app/satd.cursor"),
    })
defer sub.Close()

for {
    ev, err := sub.Next(ctx)   // reconnects and replays underneath
    if err != nil { return err }
    // ...
}

Next returns an error only on a permanent failure (bad endpoint or token, PERMISSION_DENIED, a failed cursor write), when retries are exhausted, or when ctx is done. An ordinary disconnect is not an error — it is handled.

The zero ResilientConfig is valid: default backoff (500 ms doubling to a 30 s ceiling, retrying forever), auto-resume on lag, and no persistence. Set a CursorStore; without one, a restart resumes forward-only and silently skips everything that happened while the process was down.

CursorStore is an interface — FileCursorStore is provided, and a database or key-value implementation is a two-method type.

Watches: Watch

handle, stream, err := client.Watch(ctx)
defer handle.Close()

err = handle.AddScripts(ctx, []satdevents.ScriptWatch{
    {Scripthash: satdevents.ScripthashOf(scriptPubKey)},
})
err = handle.AddOutpoints(ctx, []satdevents.OutpointRef{{Txid: txid, Vout: 0}})
err = handle.AddTxLifecycle(ctx, [][32]byte{txid}, satdevents.AutoCloseAtDepth(6))
err = handle.AddDepthAlarms(ctx, [][32]byte{txid}, []uint32{1, 3})
err = handle.AddDescriptor(ctx, descriptor, 20 /*gap*/, 0 /*start*/)
err = handle.AddSilentPayments(ctx, []satdevents.SilentPaymentTarget{target})
err = handle.AddScriptPrefixes(ctx, watcher.Prefixes(16))

The WatchHandle is safe for concurrent use — sends are serialized internally, since a gRPC stream permits only one send at a time. Every Add has a matching Remove, and SendControl is the escape hatch for anything the typed helpers do not wrap yet.

The watch-set is per-connection. The server holds no principal-keyed state, so when the stream drops, the watch-set and its quota leases go with it and a fresh stream starts blank. That is why the durable variant below exists.

Some registrations are outcome-in-band rather than outcome-on-return: SetCursor and SetWatchSet return nil once the request reaches the control stream, and the actual outcome arrives on the event stream as exactly one CursorAccepted/CursorRejected or WatchSetReplaced/WatchSetRejected. Drive catch-up off those events, not off the return value.

Durable watch: ResilientWatch

watch := client.ResilientWatch(ctx, satdevents.ResilientWatchConfig{
    CursorStore: satdevents.NewFileCursorStore("/var/lib/app/watch.cursor"),
    WatchSetLoader: func(ctx context.Context, set *satdevents.WatchSet) error {
        rows, err := db.WatchedScripts(ctx)   // your durable truth
        if err != nil { return err }
        for _, r := range rows {
            set.AddScripts(satdevents.ScriptWatch{Scripthash: r.Scripthash})
        }
        return nil
    },
})
defer watch.Close()

for {
    ev, err := watch.Next(ctx)
    if err != nil { return err }
    // ...
}

Without a loader, ResilientWatch re-registers its in-memory mirror of the Add/Remove calls made through it. That is correct for a watch-set built once at startup — but the mirror is empty after a process restart, and goes stale if the truth changes while the stream is down.

With a loader, the mirror becomes a cache of your truth:

• the loader runs after every successful (re)connect, before any event is pumped, so the first events after a reconnect already land on a fully populated subscription;
• the loaded set replaces the mirror, so the next reconnect re-derives from the loader rather than from accumulated in-process edits;
• a loader error is transient — backed off and retried on the next connect, not surfaced. A momentary outage of your database must not kill a consumer whose contract is at-least-once. A permanently broken loader is indistinguishable from a transient one and retries forever; set Backoff.MaxRetries if you need a terminal error instead.

Reload(ctx) realigns a live stream with the loader's truth on demand, and returns a ReloadSummary (Added, Removed, Unchanged, Applied). Use it after adding an address, so a later reconnect's loader agrees with what this process registered.

Cancel safety

ResilientSubscription.Next and ResilientWatch.Next take a ctx, and cancelling it never consumes an event. (Stream.Recv on the non-resilient surfaces takes no ctx; it is unblocked by cancelling the context passed to Subscribe/Watch, and that surfaces as a gRPC CANCELED status rather than context.Canceled — check ctx.Err(), not errors.Is(err, context.Canceled).)

The reconnect state machine runs on its own goroutine and hands events over an unbuffered channel, so it is never more than one event ahead of the caller. Returning on ctx.Done() therefore cannot drop an event in flight: the handoff only completes when the caller actually receives. Cancel Next freely — in a select against a command channel, or under a per-call deadline — and call it again.

This is the Go equivalent of the Rust SDK's explicit cancel-safe state machine. The language does the work here, because a gRPC Recv cannot be abandoned mid-flight without losing the message.

Prefix watches (privacy-preserving)

Register a coarse bits-wide bucket of sha256(scriptPubKey); the node learns only the bucket and delivers everything in it, and the client filters locally.

watcher := satdevents.NewPrefixWatcherWithScripts(script1, script2)
err = handle.AddScriptPrefixes(ctx, watcher.Prefixes(16))

// on each *satdevents.PrefixMatched:
hits, err := watcher.Filter(m)
for _, f := range hits.Funding { /* f.Vout, f.Value */ }
for _, s := range hits.Spending { /* s.Outpoint */ }
if hits.HasUnresolved() {
    // The server did not retain these prevout scripts. They are UNKNOWN, not
    // misses — resolve the outpoints yourself before concluding otherwise.
}

Distinct scripts sharing a bucket collapse into a single registration, which is the point: the node cannot tell how many of your scripts a bucket covers. Bits below the bucket width are masked before deduplicating, so a coarse bucket really does collapse — at 1 bit, any number of scripts registers at most two buckets. MaxPrefixBits (32) is where the server's mask saturates; a wider registration cannot be more selective and is rejected client-side rather than silently dropped by the server.

A server may lower the ceiling further via streamprefixmaxbits. That bound is not advertised over the wire, so an over-precise (but ≤ 32) prefix can still be dropped server-side with no client-side signal.

Errors

Every SDK error is an *Error carrying a Kind, and each kind has a sentinel that errors.Is matches:

if errors.Is(err, satdevents.ErrPermissionDenied) { /* fix the token's caps */ }
if satdevents.Retryable(err) { /* back off and retry */ }

var serr *satdevents.Error
if errors.As(err, &serr) && serr.Status != nil {
    log.Print(serr.Status.Code(), serr.Status.Message())  // server detail survives
}

A Lagged notice is deliberately not an error: it is a normal, recoverable event carrying a resume cursor. ErrUnauthenticated is reported non-retryable on purpose — a blind retry with the same token will not help.

Delivery guarantees

Cursors commit on poll: a delivered event's cursor is persisted only once the caller comes back for the following event, which is an implicit ack. The store therefore never advances past an event you have not received, so a crash mid-processing replays that event. This is at-least-once, not at-most-once; dedup on your side, keyed by what you process, if you need exactly-once.

The exception is ReplayGap. It means the persisted cursor fell outside the server's replay window: the blocks it names were never delivered and never will be. Full-resync that range from another source — logging it and moving on loses transactions.

Stability & versioning

The SDK is versioned with the node: clients/go/vX.Y.Z is cut at the node's vX.Y.Z, even when no Go code changed, and satdevents.Version names it. A unit test pins Version to the workspace version, so the two cannot drift. Pick an SDK whose minor version is at or below your node's. Newer nodes only add: an event kind this build predates decodes to *UnknownEvent, and an unknown enum value is preserved with Known() == false, so a Status from a newer node still routes correctly on Severity and Message.

Each time Subscribe or Watch opens a stream, the SDK reads the version the node advertises in its satd-version response header and compares it with its own:

A node older than 0.6.0 sends no header and counts as 0.5. The warning means "upgrade the node": features added after the node's release are unavailable, and request fields it does not recognise are ignored. For a rolling upgrade where clients go first, WithAllowOldNode() turns ErrNodeTooOld into the same warning. Nothing bypasses a schema mismatch. Both errors are non-retryable, so the resilient layers return them from Next instead of reconnecting. Client.NodeVersion() returns what the node last advertised. The full rule is in STABILITY_POLICY.md.

Watch waits for the node's response headers before returning, as Subscribe already did. satd sends them as soon as the stream is set up, so a quiet watch-set does not hold it up.

The first tag under this scheme is clients/go/v0.6.0; the previous tag was clients/go/v0.1.0, shipped with node 0.5.0. Because there is no go.mod at the repository root, the node's own vX.Y.Z tags do not collide, and the module proxy serves consumers a zip of the module subtree only — importing this SDK does not pull the Rust tree.

The module stays within v0/v1: Go's semantic import versioning makes v2+ a breaking import-path change (.../go/v2), so the bar for declaring v1 is "we can live with this API".

How parity is verified

The Go SDK is not a best-effort port kept in sync by hand. Every satd PR runs:

1. the Go unit tests, including a protobuf-reflection test that fails when a new event variant is added to the .proto without a Go decoder;
2. a build of all thirteen examples, so a renamed method cannot rot in a file whose whole job is to be copied;
3. the Go E2E suite against the same freshly built satd binary the Rust E2E suite uses;
4. a differential parity harness — one node, two clients, byte-identical watch spec. The Go SDK and the Rust satd-events-client each render every event they receive to canonical JSON, and the two dumps are diffed line by line. A field one SDK decodes differently, or a variant one of them cannot decode at all, fails the PR.

The harness normalizes exactly two things, and no more: it drops the publisher's per-process instance_id (which differs per connection by definition), and it sorts by cursor rather than arrival order (two connections are served by independent tasks, so interleaving is server scheduling, not a parity property). It therefore proves the two SDKs see the same events with the same field values — not that they see them in the same order.

Examples

Thirteen runnable programs live in clients/go/examples/, one per usage shape:

cd clients/go/examples
go run ./firehose_tail   -endpoint 127.0.0.1:50051
go run ./resilient_tail  -endpoint 127.0.0.1:50051 -cursor /tmp/satd.cursor
go run ./health_watch    -endpoint 127.0.0.1:50051
go run ./tls_tail        -endpoint node.example:50051 -ca ./node-ca.pem

health_watch is the alerting shape worth reading in full: it subscribes to heartbeats and enforces a deadline on them, because a wedged publisher on a live connection produces silence, and silence otherwise reads as "nothing is wrong". It also documents what a status stream structurally cannot tell you — status events are not replayable, so getwarnings over JSON-RPC remains the authoritative answer to "what is wrong right now".

MCP Server

satd ships a native Model Context Protocol server (the mcp crate, built on rmcp). It exposes the node's query, ops, and transaction-construction surfaces as MCP tools for AI agents and other MCP clients. An LLM-driven client can inspect chain, mempool, and peer state, estimate fees, decode and build transactions, and run operator actions through a typed tool interface rather than raw JSON-RPC.

The server is off by default. Enable it with --mcp plus --mcpport.

Transport

MCP is served over a single Streamable HTTP listener, which also serves legacy SSE clients. The MCP server is part of the running satd process, so clients attach to a running node over the network.

The listener runs on satd's core (consensus) tokio runtime, not the isolated API runtime, because MCP exposes block-connecting and broadcast tools. See Posture.

Transport security (TLS)

The MCP listener serves plaintext HTTP only when bound to loopback. Setting --mcpcert and --mcpkey switches the listener to HTTPS. TLS is mandatory for any non-loopback bind, so a bearer token is never sent in cleartext over the network. satd refuses to start a routable MCP listener without TLS.

TLS uses the same tls_config layer as the RPC, Esplora, and Electrum surfaces, and reloads on SIGUSR1.

For mutual TLS, add --mcpmtls --mcpmtlsclientca <ca.pem>. Clients without a certificate that chains to the CA are rejected at the handshake. To narrow further, use --mcpmtlsclientallow <CN> (repeatable or comma-separated). mTLS is additive: the --mcpauth bearer layer still runs on top.

Authentication

MCP uses the unified auth system:

• Loopback default. With --mcpauth off, the server performs no per-request auth check. This mode is valid only for a loopback bind.
• Bearer. --mcpauth (which requires --authfile) demands Authorization: Bearer <token> resolving to a principal that holds the mcp:* capability. Otherwise the server returns 401 with WWW-Authenticate: Bearer. The token's rate limit applies; a throttled request gets 429 with Retry-After.
• Remote exposure is gated. A non-loopback --mcpbind requires --mcpallowremote (which in turn requires --mcpauth and --authfile) and TLS (--mcpcert/--mcpkey). satd refuses to start a routable MCP listener that lacks either auth or TLS.
• The Host header is validated. The transport accepts only the names in its allowlist, which is loopback (localhost, 127.0.0.1, ::1) plus whatever --mcpallowedhost adds; anything else gets 403 before auth runs. This is a DNS-rebinding defence, and TLS does not substitute for it: a browser induced to resolve an attacker's name to this address completes a perfectly valid handshake, and Host is what still names that domain. A listener reached by hostname needs --mcpallowedhost or every request is refused. The option is additive — loopback stays allowed, and no value empties the list.

A single capability, mcp:*, gates all of MCP. There is no read-only versus mutating split, so any token with mcp:* can call every tool.

Posture: MCP is not read-only

MCP exposes state-changing tools: send_transaction broadcasts to the network, generate_blocks mines and connects blocks on regtest, and manage_peer disconnects, bans, unbans, or adds peers. The transaction construction and signing tools also mutate what the client can do with funds.

Treat an mcp:* token as a privileged credential. Keep the listener loopback-bound unless both auth and TLS are in front of it.

Connecting a client

Enable the listener on the node, then point the client at the URL.

Enable the listener

In bitcoin.conf:

mcp=1
mcpport=18888
# mcpbind=127.0.0.1   # default: loopback only

or on the command line:

satd --datadir=/path/to/node --mcp --mcpport=18888

The server is then reachable at http://127.0.0.1:18888/.

For remote use, add TLS and auth, and issue a token that holds the mcp:* capability:

satd --datadir=/path/to/node --mcp --mcpport=18888 \
  --mcpbind=0.0.0.0 --mcpallowremote \
  --mcpauth --authfile=/etc/satd/auth.toml \
  --mcpcert=/etc/satd/mcp.crt --mcpkey=/etc/satd/mcp.key \
  --mcpallowedhost=NODE_HOST

The server is then reachable at https://NODE_HOST:18888/. Clients authenticate with an Authorization: Bearer <token> header.

--mcpallowedhost must name every hostname clients put in the URL — the name in the certificate is not consulted, and neither is the machine's own hostname. Repeat the option, or give it a comma-separated list, for more than one. An entry may be a bare host (any port) or a host:port authority (that port only). Without it, every request to https://NODE_HOST:18888/ is answered 403 Forbidden. See Authentication and Transport security.

Claude Code

# Loopback node, no auth:
claude mcp add --transport http satd http://127.0.0.1:18888/

# Authenticated TLS node: pass the bearer token as a header.
claude mcp add --transport http satd https://NODE_HOST:18888/ \
  --header "Authorization: Bearer YOUR_TOKEN"

Append --scope project to write a shared, committable .mcp.json instead of your personal config. Inspect with claude mcp list and the in-session /mcp. The equivalent .mcp.json entry:

{
  "mcpServers": {
    "satd": {
      "type": "http",
      "url": "https://NODE_HOST:18888/",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

Codex CLI

Add to ~/.codex/config.toml (or .codex/config.toml in a trusted project):

[mcp_servers.satd]
url = "https://NODE_HOST:18888/"
# Authenticated node: supply the bearer token.
http_headers = { Authorization = "Bearer YOUR_TOKEN" }

Note. If you terminate TLS with a self-signed certificate, configure the client to trust it, or front satd with a reverse proxy holding a CA-issued certificate. mTLS clients additionally present their own certificate and key per their MCP-client documentation.

Tools

The server registers the following tools. Each returns a text result.

Node status / ops

• get_node_status: chain height, sync progress, mempool summary, peers, difficulty, uptime.
• get_system_info: process RSS, UTXO-cache stats, DB info.
• get_config: effective post-merge config (secrets redacted).
• get_metrics_snapshot: current Prometheus metrics as text.
• get_health / get_readiness: liveness and readiness (mirror /healthz and /readyz).
• get_reorg_history: persisted reorg events. Param: since_secs (default 86400).

Blockchain / block

• get_block: block by hash or height. Params: identifier, verbosity (summary/full/raw).
• get_block_header: header by hash or height. Params: identifier, raw.
• get_block_stats: fees, sizes, tx counts, UTXO/SegWit stats. Param: identifier.
• get_chain_info: tips, tx rate over a window, difficulty. Param: window (default 30).
• search_block_range: headers for a range (max 100). Params: start_height, end_height.

Transaction (query / decode)

• get_transaction: lookup by txid (chain and mempool); optional blockhash hint.
• decode_raw_transaction: decode a hex tx to JSON. Param: hex_tx.
• decode_script: decode a hex script (opcodes, type, addresses). Param: hex_script.

Mempool

• get_mempool_overview: size, byte usage, fee histogram, policy.
• list_mempool_transactions: list with sort_by (fee_rate/time/size), limit (up to 100), min_fee_rate.
• get_mempool_entry: one tx; optional include_relatives (ancestors and descendants).
• get_mempool_entries_bulk: detail for many txids (missing entries return null).
• get_mempool_history: windowed snapshots. Param: since_secs (default 3600).
• subscribe_mempool_snapshot: most recent mempool events. Param: limit (up to 50).

Fees

• estimate_fee: rates for multiple targets (default [1,3,6,12,25]), in BTC/kvB and sat/vB.

Network / peers

• get_peer_info: connected peers. Param: summary (default true).
• manage_peer: mutating; add / disconnect / ban / unban. Params: action, address.
• get_ban_list: banned peers with timestamps and reasons.

Transaction construction (mutating)

• create_transaction: build an unsigned raw tx. Params: inputs, outputs, locktime.
• sign_transaction: sign with WIF keys client-side. Params: hex_tx, private_keys, prevtxs, sighash.
• send_transaction: broadcast a signed raw tx. Param: hex_tx.
• psbt_workflow: PSBT create/decode/analyze/combine/finalize/update/convert/join.

Mining

• get_mining_info: difficulty, network hashrate, height.
• generate_blocks: mine blocks (regtest only). Params: count, address.
• get_block_template: mining template.

UTXO / address

• get_utxo: single UTXO by txid/vout (null if spent).
• get_utxo_set_stats: total UTXOs, total value, best block.
• validate_address: parse and classify an address (P2PKH/P2SH/P2WPKH/P2WSH/P2TR); returns script hex and witness info.

Core Functional-Test Conformance

satd runs Bitcoin Core's own functional test suite, unmodified, against itself. Every test file in the pinned Core release is accounted for: it either runs, or it carries a reason it does not. This page is the scoreboard.

It is deliberately a different kind of evidence from satd's other conformance work. The ported fixture corpora check that satd agrees with Core on specific inputs, and the live block-acceptance differential checks that satd and bitcoind accept the same blocks from the real network. This suite checks something neither of those can: that Core's own idea of how a Bitcoin node behaves — written by Core's developers, in Core's terms, exercising Core's RPC surface, P2P behaviour and startup semantics — holds when pointed at satd.

Scoreboard

The current numbers come from the harness itself:

contrib/core-functional/check_inventory.py --summary

The harness is in contrib/core-functional/; its README.md documents the rules that keep the number honest, the most important being that a test flips to run only in the pull request that makes it pass. The count moves when behaviour changes, never because a batch of rows was re-labelled.

At the time this harness landed the run-set was deliberately tiny: two tests. That number is not a measure of how Core-compatible satd is — it is a measure of how much of Core's test framework satd can currently drive. The framework leans on test-only facilities that satd had no reason to implement until the harness needed them — setmocktime, syncwithvalidationinterfacequeue and a periodic P2P ping, all of which have since landed. Clearing one rarely turns a row green on its own: the blockers are layered, and a test that gets past the framework's setup then stops on whatever its body needs next. Every skip records what actually blocked it when it was last measured, so the queue of work is explicit rather than a guess; contrib/core-functional/README.md ranks it.

How to read a skip

A skip is not an admission that satd fails a test. Most are statements about what satd deliberately is:

The two buckets worth watching are rpc-missing and feature-missing: those are the ones that represent work, and the harness refuses to accept such a row unless it names what will retire it.

Where satd already matched Core, and where it did not

Standing the harness up was itself a conformance test, because Core's framework is an exacting client: it drives the node the way Core's own developers assume a node behaves. Several places where satd had drifted only became visible once that client was pointed at it — most of them affecting real Core-compatible software, not just tests:

• Content-Type: application/json. satd answered RPC with application/json; charset=utf-8. The parameter is redundant (RFC 8259 fixes JSON's encoding), but Core-derived clients compare the header for equality rather than parsing it, so the suffix reads as a non-JSON response. Core's own test client rejected every satd reply without reading the body.
• -28 RPC in warmup during startup. While coming up, Core answers every RPC with -28 and a status line; that is how a client learns "alive, retry shortly". satd's startup listener answered -32601 Method not found for anything but its own progress method, which a Core-compatible client reads as a permanent failure.
• Core options on the command line. satd skipped recognized-but-unsupported Core options in bitcoin.conf with a warning, but the same option passed as a flag aborted startup. Core treats the two as one namespace; satd now does too, while still rejecting genuine typos.
• Single-dash spelling for satd's own flags. Core spells every option with a single dash. satd's compatibility table had drifted from its parser, so 56 flags — including Core's own -blockfilterindex and -peerblockfilters — were reachable only as --double-dash. The set is now derived from the parser, so a new flag cannot fall out of reach.
• -version and unknown-argument errors. satd's -version output did not contain the word "version", and a bad flag was not reported in Core's wording.
• Core's fee-rate units. Core denominates -minrelaytxfee and -dustrelayfee in BTC/kvB (0.00001); satd documents them in sat/kvB (1000) — the same rate, written differently. satd now takes both. An unparseable value used to be silently discarded in bitcoin.conf, leaving the node relaying at a default the operator never chose; it is now an error.
• -blockfilterindex with no value, which Core accepts as basic.
• A panic on an unparseable -bind. satd joined -bind to -port and unwrapped, so a value it could not parse aborted on a stack trace rather than an error. Underneath that, IPv6 literals were never bracketed, so -bind=::1 could not have worked at all.

None of these were consensus defects, and none would have shown up in satd's own test suite — they are exactly the class of difference that only an outside-in client finds.

Running it yourself

cd contrib/core-functional
./fetch-core.sh          # fetch the pinned Core tree
cargo build --release --bin satd --bin sat-cli   # from the repo root
./run.sh                 # run the inventory's run-set
./run.sh --candidate <test.py>   # measure a still-skipped test after a fix

Nothing in the harness assumes a particular machine: the satd binaries, the Core checkout location, the scratch directory and the job count are all environment overrides, documented in contrib/core-functional/README.md.

In CI

The run set gates every pull request. The build is the only slow part of it, and it is shared: the core-functional job downloads the same release binaries the third-party canary fleet uses, so the suite adds about a minute and sits off the critical path. A red run set blocks the merge.

A second, nightly run pays for its own build and is where the run set gets widened and where a --candidate measurement runs unattended.

Both run on GitHub-hosted runners, as does every other job in this repository.

The split matters: for a while the suite ran only nightly, so a test could be marked run in one pull request and quietly stop passing in the next, with the published scoreboard still claiming it. That is not hypothetical -- it is how the count came to read 30 while four of those thirty were failing.

Guided Code Tour

The guided code tour is a slide deck that walks the satd source module by module. Each subsystem gets an introduction, verbatim source snippets with file:line references, the design trade-offs, and a comparison to the equivalent Bitcoin Core implementation.

Open the code tour

The tour opens as a full-page deck outside the manual layout. Navigate with the arrow keys. Press t for the table of contents. Use the manual link in the footer to return here.

What it covers

Nine parts, 42 slides:

1. Orientation: the compatibility thesis, the workspace crate map, and the architecture at a glance.
2. Storage: the Store trait, the RocksDB column-family schema, the coin cache, flat block files, and undo data.
3. Chain and validation: ChainState, the connect pipeline, reorg atomicity, the dual script engines, parallel IBD, and AssumeUTXO.
4. P2P networking: the peer-manager actor model, BIP 324 transport, the swarm IBD scheduler, addrman, compact blocks, and Tor.
5. Mempool and mining: the two-class mempool, fee estimation, block templates, the policy language, and the Lightning danger gate.
6. RPC and surfaces: the middleware stack, Core compatibility machinery, authentication, Esplora, and Electrum.
7. Indexes: the shared write batch, the address index schema, BIP 158 filters, the BIP 352 tweak index, and deferred backfill.
8. Streaming and ops: the event envelope, watch streams, the Rust and Go SDKs, alerts, and the operator tooling.
9. satd vs Core: default differences, intentional exclusions, how parity is proven, and migration.

Snapshot provenance

The deck is a snapshot. Every snippet and file:line reference was taken from master at commit 4874b537 (2026-08-19). The code moves; the commit pins where each snippet came from. To read a referenced file at that exact state, run:

git show 4874b537:node/src/chain/state.rs

Packaging satd

This document is the authoritative reference for downstream packagers (Umbrel, Start9, RaspiBlitz, MyNode, BTCPay, Debian/Fedora/Alpine, Homebrew, Nix). It describes file layout, signals, ports, config surface, runtime model, and the contract satd offers a packager.

The user-facing operator surfaces are documented elsewhere in this manual. See Observability & Metrics and Configuration, Tuning & Reload. The catalog of intentional deviations from Bitcoin Core is CORE_DIFFERENCES.md. Ecosystem and packaging work that has not shipped is tracked in ROADMAP.md.

Document status

This is PACKAGING.md v1. It covers the surfaces shipped today: the container image, the Type=notify systemd unit, the OpenRC and runit equivalents, the on-disk layout, the operational surface, the release pipeline, signing on all three surfaces, the reproducible build via Nix, CycloneDX SBOMs per binary, and the cargo-deny supply-chain gate.

Updated: 2026-05-07.

Binaries

satd ships two binaries:

A third binary, sat-tui, is a curses-style operator dashboard. It is optional; packagers can omit it.

There are no separate sat-electrum or sat-esplora companion binaries. Both protocols are subsystems of satd, enabled with the --electrum=1 and --esplora=1 flags. satd runs as one process with one RocksDB instance, one log stream, and one PID. Disk Footprint & Indices covers the disk cost of the shared store.

File layout

$DATADIR/                         # default: $HOME/.bitcoin (Core-compat)
└── <network>/                    # one of: <empty for mainnet>, testnet3, signet, regtest
    ├── blocks/
    │   ├── blk00000.dat          # flat-file block storage (state)
    │   ├── blk00001.dat
    │   ├── ...
    │   └── xor.dat               # 8-byte obfuscation key (Core v28+ compat; all-zero = plaintext)
    ├── chainstate/               # RocksDB instance (state)
    │   ├── *.sst                 # SST files (the bulk of disk usage)
    │   ├── CURRENT, MANIFEST-*   # RocksDB metadata
    │   └── ...
    ├── .cookie                   # RPC cookie auth (auto-generated, mode 0600)
    ├── mempool_history.log       # rolling mempool snapshot (state, derived-OK)
    ├── reorg.log                 # persistent reorg ledger (state, append-only)
    ├── bitcoin.conf              # optional config file (Core-compat name)
    └── satd.conf                 # alternative config name (also accepted)

Three paths hold state and must be backed up to preserve consensus history: blocks/, chainstate/, and reorg.log.

The derived files are safe to delete. Everything inside chainstate/ (the RocksDB instance), mempool_history.log, and the *.complete index marker files inside chainstate/ regenerate from blocks/ with --reindex or --reindex-chainstate. There is no debug.log: satd logs to stdout.

Difference from Bitcoin Core. satd does not keep separate databases for the txindex, address index, or BIP 158 filter index. They are column families inside the one RocksDB instance, written atomically with each connect_block batch.

Consequences of the single instance:

• Backup is one directory.
• An index update is never visible without the matching tip update. The whole WriteBatch commits, or none of it does.
• --reindex-chainstate rebuilds everything in chainstate (UTXO set and indexes) and preserves the flat files.

Process model

• One process. The PID file is whatever the supervisor records; satd does not write its own PID file by default.
• tokio async runtime; many tasks on a fixed-size worker pool.
• rayon for script verification (CPU-bound parallelism).
• RocksDB keeps many SST files mmapped. Budget LimitNOFILE=65536 at minimum. The systemd unit and the Docker image both pre-set this.

Signals

Difference from Bitcoin Core. Core reopens debug.log on SIGHUP. satd logs to stdout and repurposes SIGHUP for config reload.

Give the container supervisor a stop grace period of at least 10 minutes: --stop-timeout=600 for docker run, terminationGracePeriodSeconds: 600 on Kubernetes. The systemd unit ships TimeoutStopSec=10min for the same reason.

Network ports (defaults)

Esplora REST (--esplora), Electrum (--electrum), and the metrics and health endpoint (--metricsport) have no per-network default port. Each is off by default on every network. Pick a port per deployment, for example 3000 for Esplora, 50001 for Electrum, and 9332 for metrics.

The default RPC bind is loopback.

Health and readiness

When --metricsport=<port> is configured, satd exposes three unauthenticated HTTP endpoints on that port (default bind 127.0.0.1):

The two are not interchangeable, and the difference matters most where it is easiest to get wrong. /readyz returns 503 until the tip is within six blocks of the headers tip — on a fresh mainnet node, days — so it answers "should clients be sent here yet", not "is this process healthy". Wire it to a Kubernetes readiness probe or a load-balancer pool check, where 503 means "route elsewhere for now".

Do not wire /readyz to a Docker HEALTHCHECK, a Kubernetes liveness probe, or anything that restarts or alarms on a failure: a syncing node will sit unhealthy for the entire initial sync and be killed or reported as broken while it is working correctly. Use /healthz, or the image's own satd-healthcheck, which probes JSON-RPC liveness by default and is what every deployment in contrib/ uses.

The shipped Type=notify unit (see the systemd section) signals startup with sd_notify(READY=1). Supervisors without notify support can poll /healthz.

Configuration

Two files are accepted, both in Bitcoin Core's key=value / [network] syntax:

• bitcoin.conf: the Core-compatible name. Same shape, same precedence.
• satd.conf: identical syntax. Preferred when running next to a Core install.

Resolution order: --conf=<path> if given, else <datadir>/bitcoin.conf, else <datadir>/satd.conf. Command-line flags always win over file values.

The full option matrix is in Configuration, Tuning & Reload. The container ships a mainnet-loopback default; every value can be overridden with -e SATD_* environment variables. See the Container section.

Ready-made deployments

Before packaging satd yourself, note that the repository ships three finished ones, described in Appliance & Reference Stack: a docker-compose reference stack (contrib/stack/), a bootable appliance image (contrib/appliance/), and sources for Umbrel and StartOS packages (contrib/packaging/).

They share one node configuration and one certificate scheme, and the container image below carries the first-run tooling all three use (satd-init, satd-mkca), so a package built on that image gets the same behaviour without reimplementing it.

Container

The repository ships a multi-stage Dockerfile at the repo root. Build:

docker build -t satd:dev .

Properties of the image:

• Base: debian:bookworm-slim.
• Runtime user: satd, UID/GID 2121. A non-1000 UID avoids a bind-mount clash with the usual host operator UID.
• Binaries: satd, sat-cli and sat-tui, so docker exec -it satd sat-tui works against a running container.
• First-run tooling: satd-mkca (issues the install's CA and server certificate) and satd-init (renders bitcoin.conf, mints the MCP token), plus openssl. These are in the image so a deployment that cannot mount repository files — an Umbrel app, a StartOS package — behaves identically to contrib/stack.
• HEALTHCHECK: satd-healthcheck, which probes JSON-RPC liveness. Point SATD_HEALTH_URL at an HTTP endpoint to gate on that instead — but not at /readyz, for the reason in Health and readiness.
• PID 1: tini, so SIGTERM forwards to satd cleanly.
• Datadir: /var/lib/satd, declared as a VOLUME.
• Exposed ports: 8333 (P2P) and 8332 (RPC). Map other ports with -p per deployment.

An example mainnet run with persistent state, RPC on loopback, and metrics on loopback:

docker volume create satd-data
docker run -d --name satd \
  --restart unless-stopped \
  --stop-timeout 600 \
  -v satd-data:/var/lib/satd \
  -p 8333:8333 \
  -p 127.0.0.1:8332:8332 \
  -p 127.0.0.1:9332:9332 \
  satd:dev \
    --rpcbind=0.0.0.0 --rpcallowip=127.0.0.0/8 \
    --metricsport=9332 --metricsbind=0.0.0.0

CLI:

docker exec satd sat-cli getblockchaininfo

Tag-triggered releases publish linux/amd64 and linux/arm64 images to ghcr.io/epochbtc/satd via the workflow at .github/workflows/release.yml. Tags follow docker/metadata-action defaults: <MAJOR>.<MINOR>.<PATCH>, <MAJOR>.<MINOR>, and latest on every release.

docker pull ghcr.io/epochbtc/satd:0.1.0
docker pull ghcr.io/epochbtc/satd:latest

The images are signed with cosign keyless OIDC and attested to the Rekor transparency log. The verifier command is under Signed releases below.

systemd

The repository ships contrib/systemd/satd.service. Install:

sudo install -Dm644 contrib/systemd/satd.service /etc/systemd/system/satd.service
sudo install -Dm755 target/release/satd /usr/local/bin/satd
sudo install -Dm755 target/release/sat-cli /usr/local/bin/sat-cli
sudo useradd --system --home /var/lib/satd --shell /usr/sbin/nologin satd
sudo systemctl daemon-reload
sudo systemctl enable --now satd

The unit ships restrictive hardening: read-only root, private /tmp, a syscall filter, and no new privileges. To relax any of these, for example to write to a datadir outside /var/lib/satd, use a drop-in:

# /etc/systemd/system/satd.service.d/datadir.conf
[Service]
ExecStart=
ExecStart=/usr/local/bin/satd --datadir=/srv/bitcoin
ReadWritePaths=
ReadWritePaths=/srv/bitcoin

The unit is Type=notify. satd calls sd_notify(READY=1) after every listener is bound: RPC, P2P, and the optional Esplora, Electrum, MCP, and events surfaces. Units that depend on satd, such as a Tor onion service pointing at the RPC port or a monitoring agent, start once the listeners exist instead of racing the bind sequence.

Reindex resilience

--reindex-chainstate on a fully-synced mainnet node runs for hours. satd handles this without help from the operator:

• The unit sets a finite TimeoutStartSec=3min, not infinity. That is long enough for the first heartbeat, at 30 s, to land and push the deadline out. It is short enough that a wedge before the first heartbeat is killed in bounded time. EXTEND_TIMEOUT_USEC only works against a finite TimeoutStartSec; an infinite startup timeout would let a wedged process hang before READY=1.
• Every 30 s during the pre-bind phase, satd emits sd_notify(EXTEND_TIMEOUT_USEC=120000000, STATUS=...). EXTEND_TIMEOUT_USEC resets systemd's internal kill deadline. The STATUS line shows the live phase and progress in systemctl status satd.
• The heartbeat doubles as the liveness check. If satd sends nothing for more than 120 s, systemd kills the unit and the on-failure restart loop takes over.

$ systemctl status satd
● satd.service - Bitcoin full node
     Loaded: loaded (/etc/systemd/system/satd.service; enabled)
     Active: activating (start) since Wed 2026-05-07 18:44:19 UTC
     Status: "Replaying blocks (350000/800000, 43%)"
   Main PID: 12345 (satd)

Bitcoin Core's bitcoind.service has behaved the same way since v22.

Running multiple networks side by side

There is no satd@.service template unit yet. To run signet, regtest, and mainnet on the same host, copy the unit under different names and add per-instance drop-ins:

# Mainnet: the default unit installed above (satd.service).

# Signet on the same host:
sudo cp contrib/systemd/satd.service \
        /etc/systemd/system/satd-signet.service

# /etc/systemd/system/satd-signet.service.d/instance.conf
sudo install -Dm644 /dev/stdin \
        /etc/systemd/system/satd-signet.service.d/instance.conf <<'EOF'
[Service]
ExecStart=
ExecStart=/usr/local/bin/satd --signet --datadir=/var/lib/satd-signet
StateDirectory=
StateDirectory=satd-signet
ReadWritePaths=
ReadWritePaths=/var/lib/satd-signet
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now satd-signet

Use the same pattern for --regtest. Give each instance its own datadir and its own RPC port (--rpcport=<n> in the drop-in). Each instance can have its own satd-<network> user or share the satd user.

A native satd@.service template unit (systemctl start satd@signet) is a candidate for v0.1.x if the drop-in pattern proves insufficient.

OpenRC

For Alpine, Gentoo with the openrc profile, Artix, and other OpenRC distributions, the repository ships contrib/openrc/init.d/satd.

sudo install -Dm755 contrib/openrc/init.d/satd /etc/init.d/satd
sudo install -Dm755 target/release/satd /usr/local/bin/satd
sudo install -Dm755 target/release/sat-cli /usr/local/bin/sat-cli
sudo adduser -S -H -h /var/lib/satd -s /sbin/nologin satd
sudo install -d -m 0750 -o satd -g satd /var/lib/satd
sudo rc-update add satd default
sudo rc-service satd start

OpenRC has no notify protocol. It marks the service started once satd backgrounds via start-stop-daemon, so reindex never contends with a startup timeout. The service reads as running for the whole reindex.

Set per-instance options in /etc/conf.d/satd:

# /etc/conf.d/satd
satd_args="--prune=550 --txindex=0"

runit

For Void Linux, Artix-runit, and any s6-rc-compatible setup, the repository ships contrib/runit/satd/run and a log helper at contrib/runit/satd/log/run.

sudo install -Dm755 contrib/runit/satd/run     /etc/sv/satd/run
sudo install -Dm755 contrib/runit/satd/log/run /etc/sv/satd/log/run
sudo install -Dm755 target/release/satd        /usr/local/bin/satd
sudo install -Dm755 target/release/sat-cli     /usr/local/bin/sat-cli
sudo useradd --system --home /var/lib/satd --shell /sbin/nologin satd
sudo install -d -m 0750 -o satd -g satd /var/lib/satd
sudo ln -s /etc/sv/satd /var/service/satd

runit supervises foreground processes, so satd never daemonizes. There is no readiness gate and no startup timeout; reindex runs as long as it needs to.

Resource budget

Mainnet, fresh IBD, no optional indexes:

Each optional index (--txindex, --addressindex, --blockfilterindex) adds disk and a one-time backfill cost. Enabling an index on a synced node runs an online backfill; there is no stop-and-reindex step. The backfill cursors are in node/src/index/<index>/backfill.rs.

Pruning

--prune=<MiB> has the same shape as in Bitcoin Core. The minimum is 550 MiB, and the node prunes to that budget on its own.

--prune=1 is Core's spelling for manual pruning: prune mode is on, but nothing is deleted until pruneblockchain <height> asks for it. The RPC deletes block data at or below that height and returns the height of the last block pruned; the height may be given as a Unix timestamp instead, and a request that reaches into the most recent 288 blocks is clamped to them. A manual pruner reports automatic_pruning: false and no prune_target_size in getblockchaininfo.

Indexes that scan historical blocks (--txindex, --addressindex, --blockfilterindex) require unpruned blocks. satd refuses to start with a conflicting combination, as Core does.

Reproducible build via Nix

The repository ships a Nix flake at flake.nix. It produces deterministic satd and sat-cli binaries on x86_64-linux and aarch64-linux.

Quickstart, for a packager who already has Nix with flakes enabled:

# Build (produces ./result/bin/{satd, sat-cli})
nix build .#satd

# Hash the built binaries
sha256sum result/bin/satd result/bin/sat-cli

# Drop into a dev shell with the full toolchain (clang, libclang,
# cmake, openssl, rustc, cargo, rustfmt, clippy, cargo-watch,
# cargo-nextest)
nix develop

The toolchain pin at rust-toolchain.toml is authoritative. Both rustup and the flake read it; there is no second place to update.

What "reproducible" means in v1

• Two nix build invocations of the same commit on two hosts produce a byte-identical result/bin/satd. CI proves this on every PR that touches flake.nix, flake.lock, rust-toolchain.toml, or Cargo.lock, via .github/workflows/nix.yml: a two-runner pair build plus a compare job that asserts SHA256 equality.
• Local reproduction is one command: contrib/repro/diff-build.sh /path/to/clone-A /path/to/clone-B. It runs nix build in each clone, hashes the outputs, and falls back to diffoscope when they diverge.
• Out of scope for v1: matching the rustup-stable tarball binary (the one .github/workflows/release.yml ships) byte for byte. That requires aligning linker, debug-info, and build-id behaviour across two different build drivers. It is tractable, but it is a separate PR.

Determinism hazards addressed

Gating policy

The Nix workflow runs on tag pushes (v*), on workflow_dispatch, and on PRs that change flake-specific files: the flake itself, rust-toolchain.toml, the workflow, and the repro helper under contrib/repro/. It does not trigger on Cargo.lock or Cargo.toml edits. Every dependency bump touches those files, and the runs would burn hosted-runner minutes for little signal.

The Nix and Release workflows fire in parallel at tag-cut time and do not gate each other. If the Nix side fails, the released tarball cannot claim Nix-rebuilt provenance for that tag, and the fix goes out forward.

Reconsider the trigger scope and a hard Release-gates-on-Nix dependency once the repo flips public and Actions minutes are free.

flake.lock

The first PR that lands the flake does not commit flake.lock, because the maintainer who lands it does not have Nix on their workstation. The CI workflow is gated to workflow_dispatch, to flake-touching PRs, and to tag pushes. The first workflow_dispatch run by a Nix-capable maintainer, or from a CI runner, generates the lock. Commit the lock at that point and update the PR description. Subsequent PRs run against the committed lock.

Renovate, or a manual cadence, bumps the lock weekly. A bump that changes flake.lock re-triggers the repro check. If reproducibility breaks under a new input revision, revert the bump and investigate the hazard.

What's intentionally not in this flake

• macOS reproducibility (aarch64-darwin): deferred. The release workflow ships an Apple Silicon tarball, but the flake does not yet verify it reproducibly.
• musl reproducibility: deferred for rocksdb-sys and musl cross-toolchain reasons. The release workflow ships both musl tarballs; the flake covers only the glibc Linux targets.
• A NixOS module or Home Manager output: packagers write their own service definitions, with the contract in this document as the input.
• A maintainer-owned binary cache (Cachix): it adds a key-custody surface not yet taken on. CI uses the ephemeral magic-nix-cache action for speed only.

Bitcoin Core uses Guix. satd targets Nix as the primary reproducible build because the workspace is pure Cargo and a Nix integration is much shorter to specify. A Guix manifest may follow if a downstream packager needs it.

Release artifacts

Tag-triggered (v*) releases run .github/workflows/release.yml on hosted GitHub runners and produce, per tag:

• satd-<version>-<target>.tar.zst for the targets currently shipped:

  • x86_64-unknown-linux-gnu
  • aarch64-unknown-linux-gnu
  • x86_64-unknown-linux-musl (statically-linked musl)
  • aarch64-unknown-linux-musl (statically-linked musl)
  • aarch64-apple-darwin (macOS Apple Silicon)

  x86_64-apple-darwin is not built in the standard release matrix. GitHub is deprecating macos-13 runners, and Apple Silicon is the targeted macOS surface. To get an x86_64 darwin build, cross-compile from an arm64 darwin host (cargo build --release --target=x86_64-apple-darwin).

  Each tarball contains stripped satd and sat-cli binaries, the authoritative reference docs (README.md, PACKAGING.md, CORE_DIFFERENCES.md, STABILITY_POLICY.md), and a MANIFEST file pinning the build commit, target triple, Rust toolchain version, and build timestamp.

• A per-tarball *.sha256 file alongside each artifact, plus an aggregate SHA256SUMS covering the tarballs and the SBOMs.

• A multi-arch container at ghcr.io/epochbtc/satd:<version> covering linux/amd64 and linux/arm64.

• CycloneDX 1.5 JSON SBOMs for each shipped binary:

  • satd-v<version>.cdx.json
  • sat-cli-v<version>.cdx.json

  Each ships with a *.sha256 next to it (already in SHA256SUMS) and a *.minisig produced by the same maintainer-side contrib/release/sign-tarballs.sh flow that signs the tarballs.

The release workflow triggers on tag pushes (v*) and on workflow_dispatch, and builds the binary, container, and SBOM artifacts in parallel.

Signed releases

satd signs three independent surfaces. Verifier commands and key custody details live in SECURITY.md.

• Tarballs (minisign Ed25519). Each .tar.zst ships with a detached .minisig. The public keys, primary and cold spare, are in SECURITY.md. The maintainer signs offline; the passphrases sit behind 1Password with YubiKey 2FA, and the signing key is never present in CI. The maintainer runbook is contrib/release/sign-tarballs.sh <tag>.

• Container image (cosign keyless OIDC). No signing key in custody. The merge-manifest CI job mints a short-lived certificate from GitHub Actions OIDC, and the attestation is logged to Rekor. Verify with:

  cosign verify ghcr.io/epochbtc/satd:<version> \
    --certificate-identity-regexp \
      'https://github.com/epochbtc/satd/.github/workflows/release.yml@refs/tags/v.*' \
    --certificate-oidc-issuer https://token.actions.githubusercontent.com
  

• Git tags (SSH signatures). Annotated tags are signed with the maintainer's SSH key. The source of truth for the trusted pubkey set is https://github.com/bkeroack.keys; delegating to GitHub avoids a stale pinned file as machines rotate. Verify with the bundled helper:

  contrib/release/verify-tag.sh v0.1.0
  

Software Bill of Materials

Each release ships a CycloneDX 1.5 JSON SBOM per binary:

# Authenticate the SBOM (same key + recipe as the tarballs)
minisign -Vm satd-v0.1.0.cdx.json \
  -P RWQeP6MczCgPh6tU03GEMm4HsnGbXte3VT2Bc52TBSR7Q+X7WnL5vfQ3

# Enumerate dependencies: name, version, license
jq -r '.components[] | "\(.name) \(.version) \(.licenses[0].license.id // .licenses[0].license.name // "?")"' \
  satd-v0.1.0.cdx.json | sort

The SBOM is generated from the same Cargo.lock that produced the released binary. The cargo cyclonedx invocation lives in the sbom job in .github/workflows/release.yml. The dependency graph is identical across the gnu-linux release targets currently shipped (x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu), so a single SBOM per binary covers both tarballs.

musl and macOS targets can resolve different platform-specific dependencies, for example libc shim crates or security-framework on darwin. A release that adds them needs the workflow to emit a per-target SBOM, and the artifact filenames gain a target-triple suffix. Track this when re-enabling the deferred targets in the release matrix.

Supply-chain policy

deny.toml at the repo root encodes the supply-chain policy enforced by cargo-deny:

• Advisories. Every RustSec advisory against any dependency in the workspace fails CI by default. Exceptions are documented in [advisories.ignore] with a reason field naming the rationale.
• Licenses. Permissive only: the MIT / Apache-2.0 / BSD / ISC / Unicode / CC0 / Zlib / Unlicense / MPL-2.0 family. GPL-* and AGPL-* are denied implicitly.
• Bans. Wildcard versions on crates.io dependencies are denied. Workspace-internal path = "../foo" dependencies are allowed via allow-wildcard-paths, since every workspace crate is publish = false.
• Sources. Only https://github.com/rust-lang/crates.io-index. Git dependencies require an explicit allowlist entry.

The policy runs as a hard gate in two places:

• .github/workflows/deny.yml, on every PR that touches Cargo.toml, Cargo.lock, deny.toml, or the workflow itself.
• The supply-chain-gate job inside .github/workflows/release.yml. Every release artifact (tarballs, SBOMs, container) needs: it, so a new RustSec advisory that lands during a quiet period between merges cannot ship in a release.

Known deferred items

• cargo-auditable: embed the dependency manifest in the compiled binaries for better runtime supply-chain verification.

Stability contract

The shipped surfaces (RPC method shapes, CLI flag shape, bitcoin.conf syntax, the file layout described above) are governed by STABILITY_POLICY.md. Tier 1, the Core-compatible surface, is the strongest: a breaking change requires a scoped proposal with a demonstrated migration story for downstreams.

Packaging contacts

To request a contract change for an ecosystem package (Umbrel, Start9, Debian, Nix, Homebrew, and so on), file an issue tagged packaging against the epochbtc/satd repo. Packaging breakage is treated as a P1.

Versioning

This document is versioned alongside satd. Changes that shift the contract (file layout, signals, default ports) are called out in the release notes for the version that ships them.

Appliance & Reference Stack

satd ships three ways to run it beyond a bare binary: a docker-compose reference stack, a downloadable appliance image, and packages for the Umbrel and StartOS app stores. They share one configuration and one certificate scheme, so what you learn from any of them applies to the others.

The appliance image and the stack's overlays bundle third-party software (wallets, Lightning, ecash, and others) so you can try satd end to end. That software is included on a best-effort basis for evaluation and testing. It is not a production deployment: we do not track its security advisories in real time, and a critical fix in a bundled component may not appear in an appliance image until the next scheduled build. satd itself in this image is the same supported release as our tarballs and container image. For production, run satd from a release artifact or an app store package and operate the other components yourself.

The Umbrel and StartOS packages carry no such notice: they contain only satd.

Both store packages have been installed on a real server and driven through every interface they export — see What is checked, and how below for what that covered. Both on x86_64, and the StartOS package on aarch64 as well: built and installed on an arm64 machine, with every interface answering as it does on x86_64, and the binaries in the image genuinely aarch64 rather than emulated. Nothing there failed for a reason to do with the architecture.

The Umbrel package has not been installed on aarch64, which is why the table still qualifies that one. The arm64 half of the container image is exercised by the reference stack's own test suite on an arm64 host, but umbrelOS ships aarch64 only as a Raspberry Pi image, with no supported path to a VM.

Installing from an app store

Umbrel

satd is in a community app store rather than Umbrel's own:

1. In umbrelOS, open the App Store, then ⋯ → Community App Stores.
2. Add https://github.com/epochbtc/umbrel-apps.
3. Open the satd store and install satd.

The app takes its own host ports, clear of every other app in the Umbrel store, so it installs alongside Bitcoin Node, Fulcrum and Ride The Lightning:

Opening the app shows satd's status page: sync progress, whether a wallet can connect yet, and the connection strings to use.

Point a wallet at umbrel.local:50012 over SSL. Sparrow and Electrum pin the certificate on first use; a client that verifies against a CA needs the install's, and the MCP token lives beside it. The status page never shows either, since it carries nothing secret, so reading them takes SSH:

sudo cat ~/umbrel/app-data/epochbtc-satd/data/tls/ca.crt
sudo cat ~/umbrel/app-data/epochbtc-satd/data/secrets/mcp-token

See Trusting it for importing the CA. Other apps on the device reach JSON-RPC in plain text on the app network, as epochbtc-satd_server_1:8332 with the cookie at APP_SATD_RPC_COOKIE_FILE, which is how they reach Bitcoin Node too.

Earlier builds of the package used 8333, 50002, 3001, 8336 and 8339. A client configured against those needs the new port.

Umbrel backups leave out the chain and chainstate, which the node downloads again on its own, and keep the CA and the MCP token.

StartOS

satd is not yet listed in Start9's community registry. Until it is, build the package and sideload it as contrib/packaging/startos/README.md describes. Its Instructions tab covers the interfaces, the actions and what the package does not do.

The reference stack

cd contrib/stack
cp .env.example .env
docker compose up -d

That runs satd on signet with JSON-RPC, Electrum, Esplora and the metrics endpoint all enabled, each TLS-terminated by a certificate the install issues for itself on first start.

Overlays add third-party software, combined with repeated -f:

docker compose -f compose.yml -f compose.lightning.yml -f compose.proxy.yml up -d

Overlays that need a secret have no default and refuse to start without one, rather than shipping a value every deployment would share:

echo "RTL_PASSWORD=$(openssl rand -hex 24)" >> .env
echo "MINT_PRIVATE_KEY=$(openssl rand -hex 32)" >> .env
echo "POSTGRES_PASSWORD=$(openssl rand -hex 24)" >> .env
echo "ARK_POSTGRES_PASSWORD=$(openssl rand -hex 24)" >> .env

RTL_PASSWORD is the login for Ride The Lightning, which fronts LND's admin macaroon. Left unset, RTL generates a configuration whose password is the literal string password, so this one is required rather than defaulted.

satd-appliance enable <overlay> generates each of these into /var/lib/satd-appliance/overlay.env on first use, so the appliance needs none of this by hand.

Which ports are published

Plain RPC, Electrum, Esplora and metrics listeners bind the compose network and are not published. They exist because the overlay containers cannot be taught to trust a private CA. What leaves the host is TLS only:

BTCPay's own HTTP port binds 127.0.0.1 and RTL and the mint are not published at all, so the proxy is the only route to a web UI from another machine. A docker-published port is also not filtered by the appliance's inbound firewall chain, which is the second reason those bindings matter.

The internal RPC port is 8332 on every network so that overlays, the proxy and the store packages address one fixed port. The cost is that sat-cli inside the container needs -rpcport=8332 on any network but mainnet, since it derives its default from the chain:

docker compose exec satd sat-cli -rpcport=8332 getblockchaininfo
docker compose exec -it satd sat-tui -rpcport=8332

No pruning, anywhere

Electrum and Esplora both require txindex, and satd rejects txindex together with prune. So every deliverable here runs a fully indexed node. On mainnet that is the whole chain plus the address, spend and transaction indices — see Disk Footprint & Indices, and budget a 2 TB volume. Initial Block Download & Fast Sync covers loading an AssumeUTXO snapshot so the node is usable in hours rather than days.

signet is the default everywhere for this reason: it is the only network on which the whole stack is a one-evening exercise.

TLS

contrib/stack/tls/mkca.sh is the one certificate script. The compose stack's satd-init, the appliance's first boot, and both store packages run it, so all four produce the same material and the client instructions are identical everywhere.

It creates a CA for that install only, then issues one server certificate that every satd surface presents. That is why there are two certificates and not one self-signed: clients import the CA once, and every later reissue — after a hostname change, a new address, or a year — is signed by a CA they already trust, with nothing to accept again.

The certificate covers localhost, 127.0.0.1, ::1, the hostname, <hostname>.local, and the machine's non-bridge addresses. Prefer the mDNS name. A DHCP change invalidates an address in the SAN list; the name survives it.

Reissue happens automatically when the certificate expires within 30 days or the machine's names or addresses have changed. The CA is never rotated automatically — that would invalidate trust every client has established. Rotating it is a deliberate act: delete the CA files and re-run.

Trusting it

# compose
docker compose exec satd cat /var/lib/satd/tls/ca.crt > satd-ca.crt
# appliance
satd-appliance tls export-ca > satd-ca.crt

Then:

-rpccacert wants the certificate that issued the one the server presents. For a self-signed node certificate that is the certificate itself; it is not the leaf of a chain, which cannot anchor its own path.

What TLS does not cover

Bearer tokens from an authfile still gate MCP, streaming and Esplora writes; the plain loopback RPC listener is cookie-authenticated. The local CA authenticates the appliance to clients, not clients to the appliance — every surface supports mTLS if you turn it on, but none requires it by default.

The metrics endpoint has native TLS from satd 0.6.0 on, on 9336 beside the plain listener; see Observability. The streaming WebSocket has none. It stays on loopback or the container network, and compose.proxy.yml fronts it.

The appliance image

A bootable VM: core is headless, desktop adds XFCE with Sparrow, Electrum and Liana already pointed at the node. On arm64 the desktop has Sparrow alone, because Electrum and Liana publish no arm64 build. Each bundled wallet is installed from its project's own release, with the download checked against a signature from a pinned key; the build fails rather than installing anything that does not verify.

Downloading a built image

Images are attached to the GitHub release for each version, alongside the tarballs, and are signed with the same minisign key:

Both architectures are published. Pick arm64 on Apple Silicon and on an arm64 server; amd64 on an Intel or AMD host. Running an image under emulation works but is slow enough to be unpleasant for a syncing node.

# core is headless and ~600 MB; desktop is ~1.4 GB.
ver=0.5.2
arch=arm64   # or amd64
base="https://github.com/epochbtc/satd/releases/download/v$ver"
curl -fLO "$base/satd-appliance-$ver-core-$arch.qcow2"
curl -fLO "$base/satd-appliance-$ver-core-$arch.qcow2.minisig"

minisign -Vm "satd-appliance-$ver-core-$arch.qcow2" \
  -P RWQeP6MczCgPh6tU03GEMm4HsnGbXte3VT2Bc52TBSR7Q+X7WnL5vfQ3

An arm64 guest is UEFI-only — there is no BIOS to fall back on — so give it a UEFI firmware. UTM on macOS does this for you; with plain QEMU, pass -machine virt and an AAVMF_CODE.fd in pflash.

The .qcow2 boots under QEMU/libvirt as it is — qemu-img already compressed it, so there is nothing to unpack. The .ova that accompanies the desktop flavour imports into VirtualBox or VMware.

The satd inside a released image is the same signed tarball published on that release, verified against the key above during the build — not a rebuild. Images you build yourself install the binaries from your working tree instead, and say so on the console.

Building one yourself

contrib/appliance/build-in-docker.sh --flavor core --out out/

No root, no KVM and no Packer: the image is built with mmdebstrap and a GRUB install onto a loop device, which runs in a container and on a hosted CI runner in minutes. contrib/appliance/README.md has the details.

First boot creates everything that must be unique to an install — the disk size, the console password, the CA and certificate, the MCP token — because an image that shipped any of those would be an image where every download shared them. The build asserts none of them exist in the artifact and refuses to finish otherwise.

Day-to-day operation goes through one command:

satd-appliance status
satd-appliance tls export-ca
sudo satd-appliance set-network mainnet    # refuses below 1.5 TB free
sudo satd-appliance enable lightning
satd-appliance logs satd

satd runs natively under systemd; the overlays run as containers from /opt/satd/stack, which is contrib/stack's overlay files unmodified.

The status page is at https://satd.local:9336/status from another machine, once the CA is imported, and http://127.0.0.1:9332/status on the appliance itself.

The firewall is default-deny inbound, and sshd is off until satd-appliance ssh enable.

Why LND runs in Neutrino mode

LND's bitcoind backend requires Bitcoin Core's raw ZMQ topics (zmqpubrawblock / zmqpubrawtx). satd does not implement them and rejects those settings; see CORE_DIFFERENCES.md. Neutrino needs no ZMQ — it pulls BIP 157/158 filter headers and filters over P2P, which satd serves because every deliverable here sets peerblockfilters=1.

Core Lightning is unaffected: its bcli plugin polls JSON-RPC, so it runs as an ordinary full-node client.

Ark

compose.ark.yml runs an Ark server against satd. Experimental — Ark is young, and every setting in that overlay was established by running the binary rather than read from a specification, so expect it to need attention on a version bump.

The chain is:

satd  ->  NBXplorer  ->  arkd-wallet  ->  arkd

arkd v0.9 splits the wallet into its own service, and that wallet's chain backend is NBXplorer — not Esplora, and not Core's ZMQ. Two things follow. satd implements no raw ZMQ topics, so a backend that needed them would have ruled Ark out entirely; and NBXplorer against satd is already a PR-gating canary in this repository, so the single link in that chain which touches satd is the link that is continuously tested.

First run is two steps, because arkd will not start without a signer key and its wallet must then be created and unlocked:

docker compose -f compose.yml -f compose.ark.yml run --rm ark-init   # prints the key
# add ARKD_SIGNER_KEY=... to .env
docker compose -f compose.yml -f compose.ark.yml up -d
docker compose -f compose.yml -f compose.ark.yml run --rm ark-init   # creates the wallet

Both the signer key and the wallet password are generated per install into the data volume. Neither is shipped.

What is checked, and how

Each bundled application is a compatibility claim, so each is exercised rather than asserted:

• contrib/stack/tests/mkca-test.sh — the certificate script, including that it does not reissue a healthy certificate or rotate the CA.
• contrib/stack/tests/smoke.sh — the stack on regtest, with every TLS listener probed from outside the container against the generated CA, LND syncing to the node's tip over Neutrino, and RTL served through the proxy.
• contrib/appliance/tests/boot-test.sh — the built image booted under QEMU, checked through the guest agent and through forwarded ports.
• contrib/stack/tests/compose-test.sh — static invariants of the compose files, including that the Umbrel package's ports are its own and mapped 1:1, and that its backup exclusions match the StartOS package's.
• contrib/packaging/startos/test/ — the StartOS package's type check and unit tests, run by the app-store packages CI job. Two of them exist because a typecheck cannot see the defects they guard: a store read that made the Network action a no-op, and a ready gate pointed at /readyz, which is 503 for the whole of a sync.

The store packages were additionally installed and driven by hand — on StartOS 0.4.0.1 and on umbrelOS on x86_64, and on StartOS 0.4.0.1 again on aarch64. That is where those two defects were found, along with an image pin that named a tag predating satd-init: none of the three was visible to any static check, and the /readyz gate had passed an earlier spot check only because the node under it was minutes old. A fourth came out of the aarch64 install and was not about the architecture at all — MCP refused every request that arrived by hostname, because satd had left the transport's Host allowlist at its loopback-only default. See MCP. What was covered: satd-init producing this install's CA, certificate, MCP token and config; both health checks; Esplora and Electrum answering through the OS proxy against the server's root CA with Verify return code: 0 (ok); MCP refusing an unauthenticated call and completing an initialize with the token the package prints; switching a running node between chains; and satd returning by itself after a reboot. Not yet covered: aarch64 on Umbrel, and StartOS backup/restore.

Every probe that verifies a certificate is paired with the negative control that the same handshake without the CA must fail. A probe that would pass unverified proves nothing about the certificate.

Configuration Flag Reference

This chapter is the complete reference for every config key satd recognizes: what it does, its default, whether it reloads live on SIGHUP, and whether it is Bitcoin Core-compatible or a satd extension.

For how configuration is sourced and how live reload works, see Configuration, Tuning & Reload. This chapter is the flat per-key index. The auth keys (authfile, *authbearer/*auth, *allowremote, cookie/rpcuser/rpcauth) are explained in context in Authentication & Authorization. The sync, consensus, and storage-tuning keys (assumevalid, consensus, shadow*, dbcache, prefetchworkers, maxahead, storageprofile, the rocksdb* / compaction* family, reindex) are covered in Initial Block Download & Fast Sync.

How satd reads configuration

The goal is that an existing Bitcoin Core bitcoin.conf drops in and works. satd reads Core's configuration surface directly: the same bitcoin.conf / satd.conf key=value and [network] section syntax, and the same flag names (-datadir, -rpcport, …). Supported names and semantics track Bitcoin Core v30.

• Resolution order. -conf=<path> if given, else <datadir>/bitcoin.conf, else <datadir>/satd.conf. Flags override file values.
• Key disposition. Each config-file key gets one of four treatments:
  1. Honored. satd implements it. This is the common case.
  2. Skipped with a warning. A recognized Core v30 option satd does not implement but that is safe to skip. The node still starts, and a WARN line names the ignored key and the satd equivalent, if any. This is what lets a real bitcoin.conf boot unedited.
  3. Rejected at load. A small set where skipping would mislead you about the node's security, exposure, or privacy posture (see Unsupported Core keys). satd fails closed with guidance.
  4. Rejected as a typo. A key that is neither a satd option nor a known Core v30 option. Rejection stops a mistyped security option such as rpcusser= from silently disabling auth.
• No key is silently ignored. Skipped keys always warn; nothing a config asks for is dropped without a log line.
• -profile=<preset> seeds a hardware/role profile (archival, pruned-home, mining, regtest-dev, signet-watchtower). Explicit flags override the profile's values.