satd

/// Abstract storage backend for block index, UTXO set, and metadata.
pub trait Store: Send + Sync {
    fn get_block_index(&self, hash: &BlockHash) -> Option<BlockIndexEntry>;
    fn get_coin(&self, outpoint: &OutPoint) -> Option<Coin>;
    fn has_coin(&self, outpoint: &OutPoint) -> bool;
    fn get_tip(&self) -> Option<BlockHash>;
    fn get_block_hash_by_height(&self, height: u32) -> Option<BlockHash>;
    fn write_batch(&self, batch: StoreBatch) -> Result<(), StoreError>;
    /// Write with the given durability mode. Default delegates to
    /// `write_batch` (ignoring the mode) — concrete backends that can honor
    /// `BulkLoad` should override.
    fn write_batch_mode(&self, batch: StoreBatch, _mode: WriteMode) -> Result<(), StoreError> {
        self.write_batch(batch)
    }

/// **Remove-wins contract:** if the same key appears in both a family's
/// puts and removes within one batch, the key must end ABSENT. Both
/// emitters rely on this: `connect_block` carries a put+remove pair for
/// an output created and spent within the same block, and
/// `disconnect_block` carries the mirror pair (undo-restore put +
/// created-output remove) — in both shapes the correct final state is
/// absent. Implementations must apply puts before removes (or net the
/// pairs); regression tests pin this for `RocksDbStore` and
/// `InMemoryStore`.
#[derive(Default)]
pub struct StoreBatch {
    pub block_index_puts: Vec<(BlockHash, BlockIndexEntry)>,
    pub coin_puts: Vec<(OutPoint, Coin)>,
    /// (outpoint, spent_amount, spent_height) — carried for O(1) counter/histogram updates.
    pub coin_removes: Vec<(OutPoint, u64, u32)>,
    pub tip: Option<BlockHash>,
    pub height_hash_puts: Vec<(u32, BlockHash)>,

/// Every column family this store can create, plus RocksDB's default CF.
/// `flush_durable` flushes exactly this list (filtered to the CFs that
/// exist on the open DB), so a CF missing here would silently lose its
/// WAL-less (BulkLoad) writes on process exit. `open()` asserts every
/// descriptor it creates is listed — add new CFs HERE first.
const ALL_CFS: &[&str] = &[
    "default",
    CF_COINS, CF_BLOCK_INDEX, CF_HEIGHT_INDEX, CF_UNDO,
    CF_TX_INDEX, CF_METADATA, CF_CHAIN_TX,
    CF_ADDR_FUNDING_V2, CF_ADDR_SPENDING_V2, CF_OUTPOINT_SPEND,
    #[cfg(feature = "block-filter-index")] CF_FILTER,
    #[cfg(feature = "block-filter-index")] CF_FILTER_HEADER,
    CF_ADDR_BACKFILL_TEMP, CF_SP_TWEAKS,
];

/// Dirty coin entry — must be flushed to backing store before eviction.
enum DirtyEntry {
    /// Coin exists in backing store and was modified/added. `fresh` = true means
    /// the coin was created in this flush window (never written to backing store).
    Present { coin: Coin, fresh: bool },
    /// Coin was spent. Carries (amount, height) for counter/histogram updates.
    /// If `fresh` = true, the coin was created and spent in the same flush window
    /// and can be discarded without touching the backing store.
    Spent { amount: u64, height: u32, fresh: bool },
}

/// Flush dirty coins to the backing store. Caller must hold the
/// flush-exclusion lock (via `flush` or `FlushExclusion`).
///
/// Optimizations:
/// - **FRESH elision**: coins created and spent in the same flush window never
///   touch the backing store (Core PR #17487 insight).
/// - **Move semantics**: flushed coins are moved (not cloned) to the clean LRU,
///   avoiding the allocation burst that caused glibc malloc fragmentation.
fn flush_inner(&self) -> Result<(), StoreError> {

/// Discard every uncommitted (un-flushed) cache mutation, returning the
/// cache to exactly the last-flushed on-disk state held by the inner
/// store. Does NOT touch the inner store.
///
/// This is the rollback primitive for the atomic-reorg path (issue
/// #262). The reorg driver flushes the pre-reorg active chain to the
/// inner store first, then applies the whole reorg (disconnect +
/// reconnect + triggering connect) to this cache *only*. On any failure
/// it calls this to drop the partial reorg wholesale — no block-body
/// replay, and it cannot itself fail.

/// XOR `data` in place against the repeating 8-byte `key`, where `data[0]`
/// sits at absolute file offset `offset`. No-op for the zero key, so the
/// plaintext path costs one comparison. Processes 8 bytes per step via a
/// phase-rotated `u64` so full-file de-obfuscation during `-reindex` runs at
/// memory bandwidth rather than byte-at-a-time.
pub(crate) fn xor_in_place(data: &mut [u8], key: &[u8; 8], offset: u64) {
    if *key == ZERO_XOR_KEY {
        return;
    }

//! On-disk format: an 8-byte magic, a 1-byte version, a varint count,
//! then back-to-back `Coin::serialize_compact` records. The outpoint
//! for each spend is recoverable from the block's tx inputs (the
//! connect-order invariant guarantees `undo.spent_coins[i]` belongs to
//! the i-th non-coinbase input), so we don't store it. Per-spend cost
//! is ~28 bytes for typical P2WPKH.

/// Central chain state manager.
pub struct ChainState {
    store: std::sync::Arc<CoinCache>,
    flat_files: Arc<Mutex<FlatFileManager>>,
    /// Path to the blocks directory, for mutex-free reads.
    blocks_dir: PathBuf,
    tip: RwLock<ChainTip>,
    pub network: Network,
    script_verifier: Arc<dyn ScriptVerifier>,
    assumevalid: AssumeValid,
    checkpoints: Vec<Checkpoint>,
    /// Lock-free monotonic counter bumped on every successful connect.
    /// Read by the stall watchdog to detect connector wedges without
    /// taking the `tip` RwLock, which is precisely the lock the wedge
    /// might be holding.
    connect_heartbeat: AtomicU64,

/// **Every mutator must hold it, including the connector.** The
/// original lock covered `accept_block` and the two height-row commits
/// but not `connect_stored_block` / `connect_preprocessed_block`, on
/// the reasoning that the connector *is* the single P2P writer. That is
/// true of the P2P side and false of the whole system: an
/// `invalidateblock` reorg is a second writer, and issue #567 is what
/// the two of them did to a mainnet UTXO set. "Single writer by
/// construction" is not an invariant unless something enforces it.
accept_lock: std::sync::Arc<Mutex<()>>,

#[repr(u8)]
pub enum ConnectPhase {
    Idle = 0,
    EnterConnect = 1,
    PreResolveCoins = 2,
    PerTxValidate = 3,
    VerifyDispatch = 4,
    VerifyJoin = 5,
    ShadowDispatch = 6,
    PostVerifyChecks = 7,
    WriteBatch = 8,
    TipWrite = 9,
    /// block_processor: no header yet for next_height; waiting on
    /// connect_signal condvar (1s timeout).
    WaitingForHeader = 10,
    WaitingForBlockData = 11,
    CondvarWait = 12,
    FlushingCoinCache = 13,
    FlushDurable = 14,
    WaitingForAcceptLock = 15,
}

let queue_ref = &verify_queue;
let chunk_size = verify_queue.len().div_ceil(num_threads);
mark(crate::chain::connect_phase::ConnectPhase::VerifyDispatch);
let errors: Vec<ConnectError> = std::thread::scope(|s| {
    // ... one worker per chunk ...
    // Joining the scope-spawned workers is the most common
    // wedge site we've seen in practice (issue #178). Mark
    // the phase transition before .join() so a stalled
    // dump definitively pins the wedge to this step.
    mark(crate::chain::connect_phase::ConnectPhase::VerifyJoin);

// Atomic-reorg durable checkpoint (#262): flush the pre-reorg chain so
// it is the exact rollback target, then hold the flush-exclusion for
// the whole reorg so no external flush can persist a partial state.
let excl = self.store.lock_flush_exclusion();
excl.flush()?;
let mut reorg_excl = Some(excl);

// Disconnect from current tip down to the fork point.
let disconnect_info = match self.perform_reorg(&fork_entry, current_tip) {
    Ok(info) => info,
    Err(e) => {
        self.abort_reorg(reorg_excl.as_ref(), current_tip, tip_entry.height, &e, None);
        return Err(e);
    }
};

/// A reorg needs to roll back and the coin cache cannot be attributed to
/// it. Stop the process without writing anything.
///
/// There is no safe continuation. Discarding would destroy whatever the
/// other writer committed — that is issue #567, and the whole reason this
/// check exists. Not discarding leaves the cache holding a half-applied
/// reorg mixed with someone else's blocks, under a tip that belongs to
/// neither; continuing from there writes that to disk at the next flush.
///
/// So: abort. ... `abort()` rather than `exit()` is deliberate: no
/// destructor runs, no shutdown flush gets the chance to persist the
/// poisoned cache. The node restarts onto a consistent state and redoes
/// the work.
fn fail_stop_on_unsafe_discard(&self, reason: &str, ...) -> ! {

/// Shadow verifier: runs the primary engine synchronously in the hot path,
/// dispatches shadow verification to a background thread pool asynchronously.
///
/// The connect thread never blocks on shadow results. Mismatches are logged
/// by the background workers. This makes shadow mode essentially free in
/// wall-clock terms — shadow uses spare CPU but doesn't slow block connection.
pub struct ShadowVerifier {
    primary: Box<dyn ScriptVerifier>,
    shadow_tx: crossbeam_channel::Sender<ShadowWork>,
    queue_size: usize,
    _workers: Vec<std::thread::JoinHandle<()>>,
    /// Counts shadow txs dropped because the queue was full. Rate-limited
    /// reporter (see `report_drop`) consumes this and logs an aggregated
    /// WARN at most once per 5s — a per-drop WARN at IBD verify rates can
    /// burn tens of percent of wall-clock on tracing+stdout alone.
    dropped: std::sync::atomic::AtomicU64,

/// Identifies which concrete verifier backs the authoritative (primary)
/// decision path. Used so components like the prefetch pipeline can match
/// whichever engine the user's config selected as primary — otherwise a
/// prefetch worker's "script OK" say-so (which lets the connect thread
/// skip primary verify) would override the user's chosen authority.
pub enum PrimaryEngine { Cpp, Rust }

/// This is Bitcoin Core's `CheckBlock` (structure, merkle root, CVE-2012-2459
/// mutation, weight) plus the witness half of `ContextualCheckBlock`
/// ([`check_witness_rules`]). Core splits the two because it reaches them at
/// different points; satd keeps them together so that *every* caller which
/// validates a block gets both halves.
///
/// The witness rules are gated on segwit activation exactly as Core gates them
/// on `DEPLOYMENT_SEGWIT`, which is why this is not context-free: it needs
/// `network` and `height` to decide. Threading them through the signature
/// rather than reading them from an optional argument is deliberate — the
/// compiler makes a new caller supply the context instead of silently
/// inheriting the laxer, context-free behaviour.
pub fn check_block(block: &Block, network: Network, height: u32)
    -> Result<(), ValidationError> {

/// Calculate expected difficulty bits for mainnet.
///
/// Fails closed (`BadDifficulty`) if the retarget-period seed block cannot be
/// found: a missing seed means we cannot compute the expected difficulty, so we
/// must reject rather than substitute `prev`'s bits (which would let an
/// under-difficulty block through at a retarget boundary on a damaged index).
fn calculate_next_bits<F>(

/// A block that has been pre-read, deserialized, and partially validated
/// by a background prefetch worker.
pub struct PreprocessedBlock {
    pub height: u32,
    pub hash: BlockHash,
    pub block: Block,
    pub mtp: u32,
    /// Pre-computed txids (one per transaction in the block).
    pub txids: Vec<Txid>,
    /// Tx indices where all inputs were speculatively resolved AND scripts
    /// were pre-verified successfully. Only populated in assumevalid mode.
    pub script_verified_txs: HashSet<usize>,
    /// `validation::block::check_block` already ran on `block`, off the connect
    /// thread. Consumers must run it themselves when this is false — the
    /// conservative default for anything not produced by a prefetch worker.
    pub context_free_checked: bool,
}

/// The single implementation behind every MTP the connect path uses. `plan` is
/// `Some` only during a chainstate reindex, where the store's height→hash index
/// must not be consulted: it is derived state that has been observed polluted
/// with a fork block (#322), it describes the *pre-reindex* chain rather than
/// the branch being replayed ... MTP gates BIP113 locktimes and BIP68 time-based
/// sequence locks, so resolving it against the wrong branch is a consensus
/// decision made about a chain the node is not building.

//! That is not hypothetical. On a synced mainnet node the persisted tip was
//! eight blocks above the last block it had actually connected ... Every output
//! created in that eight-block window was absent from the UTXO set. The node
//! reported a healthy synced tip on a real canonical block,
//! `getblockchaininfo` was self-consistent, and `/healthz` stayed green for
//! five and a half hours. Nothing detected it ...
//!
//! This pass is the detector that was missing. It answers wrong rather than
//! not at all: a node that fails it is refusing to serve, not quietly serving
//! a truncated UTXO set.

//! It exists because reasoning did not settle the mainnet incident behind #567
//! and reading the on-disk artifacts did. Four independent artifacts —
//! `coins`, `height_hash`, `undo`, `chain_tx` — each said something the others
//! did not, and the fourth reversed the conclusion drawn from the first three.
//! An assertion that "the tip is fine" is worth very little; an assertion that
//! names the outpoint, the height and the artifact is worth a great deal.

// Split connection into read/write halves to avoid cancel-safety issues.
// read_exact is not cancel-safe — if tokio::select! drops a recv() future
// mid-read, consumed bytes are lost and the stream becomes misaligned.
// By running the reader in a dedicated task, it is never cancelled.
let (mut reader, mut writer) = conn.split();

/// BIP 324 leaves v1/v2 detection to the responder: read the first
/// bytes and, if they are the network magic, the peer is speaking
/// plaintext v1 (a `version` message starts with the magic); otherwise
/// treat the bytes as the front of the peer's ElligatorSwift key and
/// run the v2 handshake. The detection bytes are consumed off the
/// socket and replayed into whichever transport is built.
async fn accept_transport(self: &Arc<Self>, mut stream: TcpStream) -> Result<Connection, String> {
    // ...
    if first == expected {
        if self.v2_only() {
            return Err("v2only: rejecting inbound v1 peer".to_string());
        }
        Ok(Connection::v1_with_leading(stream, magic, first.to_vec()))
    } else {

/// satd-specific `-v2only`: refuse peers that don't speak BIP 324 v2.
/// Inbound v1 peers are dropped at detection; outbound v2 failures are
/// not downgraded. Implies `v2_transport`. Defaults to false.
v2_only: std::sync::atomic::AtomicBool,
/// Outbound destinations whose v2 handshake failed this session, so we
/// connect them straight as v1 instead of wasting a v2 round trip on
/// every reconnect. Keyed by socket address (direct peers only).
v2_downgraded: RwLock<HashSet<SocketAddr>>,

/// BitTorrent-style download coordinator for parallel IBD.
///
/// Assigns random blocks from across the chain to many peers simultaneously,
/// maximizing download parallelism and avoiding the "slow peer bottleneck"
/// that sequential range assignment creates.
pub struct IbdScheduler {
    phase: IbdPhase,
    target_height: u32,
    /// Global pool of block heights still needing download, shuffled randomly.
    pending: VecDeque<u32>,
    /// Heights currently assigned to a peer (in-flight).
    in_flight: HashMap<u32, PeerId>,
    /// Max blocks in-flight per peer.
    per_peer_limit: u32,
    /// Max total blocks downloaded ahead of connect cursor.
    max_ahead: u32,

// Match Bitcoin Core's MAX_BLOCKS_IN_TRANSIT_PER_PEER (16). The
// previous limit (128) packed our getdata to peers with batches
// 8x larger than what stock peers expect to process. On the
// mainnet 2026-05-13 wedge run, peers consistently disconnected
// us after ~60s with most of their assignment unfulfilled — the
// smaller batch lets peers cycle through requests faster and
// reduces wasted in-flight assignments when a peer drops.
per_peer_limit: 16,

/// Per-(height, peer) cooldown timestamp. When a height is released from
/// a peer (timeout or notfound), that peer is barred from being re-issued
/// the same height until `cooldown_until > now`. Prevents the "silent
/// peer keeps getting re-assigned the same height" wedge observed at
/// height 785197 on the 2026-05-13 mainnet IBD run, where the 15s
/// near-cursor timeout released a stuck height back to pending and the
/// same peer immediately re-claimed it via its priority-zone scan.
height_peer_cooldown: HashMap<u32, HashMap<PeerId, Instant>>,

// A short ID is only 6 bytes, so two distinct mempool transactions can
// hash to the same short ID (crafted, or ~1-in-2^48 by chance). Using
// either one to fill a slot would be a guess: if it is the wrong tx the
// reconstructed block fails its merkle check and the honest relayer is
// banned, with no `getblocktxn` fallback. So a short ID that matches more
// than one mempool tx is marked ambiguous (`None`) and treated as
// unavailable — the slot is requested instead. This mirrors Bitcoin Core's
// `PartiallyDownloadedBlock::InitData`, which resets a slot when a second
// mempool tx collides on its short ID.

#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct QuarantineScope {
    pub relay: bool,
    pub template: bool,
}

impl QuarantineScope {
    /// Acting entry — withheld from nothing.
    pub const fn acting() -> Self {
        QuarantineScope { relay: false, template: false }
    }
    /// True for an acting (non-quarantined) entry.
    pub fn is_acting(self) -> bool { !self.relay && !self.template }

pub fn accept_transaction(
    &self,
    tx: Transaction,
    chain_state: &ChainState,
    script_verifier: &dyn ScriptVerifier,
    source: TxSource,
    allow_quarantined: bool,
) -> Result<Txid, MempoolError> {
    let txid = tx.compute_txid();

    // Snapshot the live policy once so the entire acceptance is judged
    // against a single config version. A concurrent SIGHUP reload can swap
    // `self.config` between calls but never mid-transaction.
    let cfg = self.config.read().clone();

//! Mempool-based smart fee estimation.
//!
//! Simulates the next N block templates from the current mempool snapshot.
//! For each simulated block we record the lowest admitted *ancestor
//! feerate* — that is the fee level a new tx needs to land in block k.
//! Ancestor feerate aggregation handles CPFP correctly: a low-fee parent
//! + high-fee child are admitted together at the child's pull rate.
//!
//! This complements the historical-block `FeeEstimator` in `fee.rs`:
//! historical data reacts to what miners *did* (slow to respond to sudden
//! congestion), while mempool simulation reacts to what's queued *now*.
//!
//! The simulator is intentionally a pure function over an owned snapshot
//! of `MempoolEntry`s — it does not hold any mempool locks while running.

/// Taking the running minimum is what makes the estimate **monotonically
/// non-increasing** in `target`: confirming within N+k blocks can never
/// cost more than confirming within N. A single per-block floor is *not*
/// monotone — greedy packing under the weight/sigop caps can defer a
/// high-feerate package past block 1, leaving a later block with a higher
/// admission floor than an earlier one. Reading one block per target then
/// produces a nonsensical ladder (e.g. next-block < ~30-min). The running
/// minimum collapses that to the honest answer: if a cheap tx made it into
/// an early block, every deeper target is at least as cheap.

// Resolve every input against the UTXO set, not mempool
// membership: a parent evicted after this child was admitted
// (expiry, RBF, block-connect conflict) is in neither the
// mempool nor the UTXO set, and treating "not in mempool" as
// "confirmed" would mine the orphaned child →
// bad-txns-inputs-missingorspent. An input creates one of
// four cases: already included in this template (the coin is
// born at `height`), a confirmed coin, a mempool parent that
// may still be included (defer to a later pass), or nothing
// anywhere (drop — unminable).
let bip68_enforced = (entry.tx.version.0 as u32) >= 2;
let mut awaits_parent = false;
let mut minable = true;
for input in &entry.tx.input {
    let parent = input.previous_output.txid;
    let prev_height = if included.contains(&parent) {
        height
    } else if let Some(coin) = chain_state.get_coin(&input.previous_output) {
        coin.height
    } else if in_mempool.contains(&parent) {
        awaits_parent = true;
        continue;
    } else {
        minable = false;
        break;
    };

# Exception first: my own submissions are never filtered.
allow own-submissions when tx.source == rpc or tx.source == mcp

# Ordinals / BRC-20 inscriptions.
quarantine ordinals on relay,template
    when any inputs (in.leaf_script.contains_ops(script(OP_FALSE OP_IF push(0x6f7264))))

# Cheap, oversized generic OP_RETURN.
quarantine cheap-bulk-opreturn
    when any outputs (out.script_type == op_return and out.op_return_size > 83)
         and tx.fee_rate < node.min_relay_fee * 3

# Mine-neutral big-witness: relay it, just don't mine it.
quarantine no-mine-big-witness on template when tx.total_witness_size > 100kb

pub fn evaluate<'a>(&'a self, tx: &'a TxView<'a>, ctx: &Ctx) -> Verdict {
    let mut fuel = DEFAULT_FUEL;
    for rule in &self.rules {
        let out = rule.cond.eval_metered(tx, ctx, fuel);
        if out.fuel_exhausted {
            return Verdict::fuel();
        }
        fuel = out.fuel_remaining;
        if out.value.as_bool() {
            return match rule.action {
                Action::Quarantine => Verdict::Quarantine {
                    rule: rule.name.clone(),
                    scope: rule.scope,
                },
                Action::Allow => Verdict::Allow { rule: rule.name.clone() },
            };
        }
    }
    Verdict::Pass
}

//! Detectability splits exactly as the protocols do:
//! - **BOLT-3 (legacy / anchor)** enforcement scripts are spec-mandated, so a
//!   faithful vector is an exact probe: commitment (force-close) with its anchor
//!   outputs, the breach-remedy **justice** transaction (the time-critical E1
//!   case) spending a revoked `to_local`, and second-stage HTLC timeout/success.
//! - **Taproot-channel key-path force-closes** are *indistinguishable* from any
//!   other P2TR key-path spend, so they cannot be detected directly. The probe
//!   is instead a generic, healthy P2TR key-path spend: a rule that quarantines
//!   it is structurally over-broad and necessarily sweeps TR force-closes with
//!   it.
//! - **Taproot-channel script-path enforcement** (justice / HTLC) reveals a
//!   tapleaf and is partially recognizable.
//!
//! `allow` rules are never dangerous: they only widen relay, never withhold.

Err(format!(
    "refusing policy: rule(s) [{}] would withhold relay for Lightning \
     enforcement transactions, degrading L2 enforcement network-wide (E1). \
     Narrow them, scope them `on template`, or set allowdangerousfilters=1 \
     to override.", relay_rules.join(", ")))

// AdmissionLayer is outermost so an over-budget request is shed (429)
// before any auth/compat work. AuthLayer is next so an unauthenticated
// request is rejected before the compat layer buffers its body;
// JsonRpcCompatLayer then normalizes Core-style (`jsonrpc` 1.0/1.1/
// absent) requests to 2.0 so jsonrpsee accepts them (see `compat.rs`).
let capability_filter = bearer.as_ref().map(|_| CapabilityLayer::new());
let tls_middleware = tower::ServiceBuilder::new()
    .layer(AdmissionLayer::new(admission))
    .layer(AuthLayer::new(auth, bearer))
    .layer(JsonRpcCompatLayer::new());
let rpc_svc = ServerBuilder::new()
    .set_config(server_cfg)
    .set_http_middleware(tls_middleware)
    .set_rpc_middleware(
        RpcServiceBuilder::new()
            .option_layer(rpc_filter)
            .option_layer(capability_filter),
    )
    .to_service_builder()
    .build(methods, stop_handle.clone());

//! The read-only listener runs on the same separate, bounded tokio runtime
//! as the high-volume read surfaces (Esplora/Electrum/gRPC) so a flood of
//! consumer RPC traffic can never starve block connection or mempool
//! acceptance. But that isolation comes with a hard correctness constraint
//! discovered while moving surfaces off the core runtime:
//!
//! > A surface that **connects blocks** must not run on the API runtime.
//! > `connect_block` writes the address index inline and *then* broadcasts
//! > `ChainEvent::BlockConnected`; the address-index status notifier is an
//! > independent core-runtime consumer of that broadcast. When the
//! > broadcast originates from the API runtime, the cross-runtime wakeup
//! > can reorder the notifier ahead of the inline index write becoming
//! > visible, delivering a stale all-zeros status to SSE/Electrum
//! > subscribers.

//! Every Core-ecosystem client built on the canonical libraries sends
//! the 1.0 form. NBitcoin (and therefore NBXplorer and BTCPayServer)
//! sends `"jsonrpc":"1.0"`; `python-bitcoinrpc`, many shell scripts, and
//! older tooling omit the member entirely. Against an unpatched
//! jsonrpsee, *every* call from those clients fails — which is exactly
//! the failure the NBXplorer compatibility canary surfaced (the indexer
//! could open a P2P connection but every `getblockchaininfo` RPC came
//! back `Invalid request`, so it never synced).
//!
//! This HTTP-level tower layer runs *before* jsonrpsee parses the body.

/// Format an integer satoshi amount as a Bitcoin-Core-exact fixed
/// 8-decimal BTC value (`<whole>.<8-digit frac>`) emitted as a JSON number
/// literal. Integer arithmetic only — no `f64`, so exact for all amounts.
fn btc_fixed_8dp(sats: u64) -> Value {
    let whole = sats / 100_000_000;
    let frac = sats % 100_000_000;
    let literal = format!("{whole}.{frac:08}");
    // Under `arbitrary_precision`, `Number: FromStr` preserves the exact
    // source text, so this serializes as `0.00001000`, not `0.00001`.
    Value::Number(literal.parse()
        .expect("fixed 8-decimal literal is always a valid JSON number"))
}

/// A structured RPC error. When rendered to a jsonrpsee `ErrorObjectOwned`:
/// - With extended-errors disabled (default): emits only `code` + `message`
///   (byte-identical to Bitcoin Core).
/// - With extended-errors enabled: also populates `data` with
///   `category`, `suggestion`, and `debug` when present.
#[derive(Debug, Clone)]
pub struct RpcError {
    pub code: i32,
    pub message: String,
    /// Stable dashboard-friendly taxonomy. Examples:
    /// - `mempool.policy.feerate`, `mempool.conflicts`
    /// - `validation.consensus`, `rpc.input.parse`
    /// - `storage.not_found`, `node.shutting_down`
    pub category: &'static str,
    pub suggestion: Option<String>,
    pub debug: Option<Value>,
}

/// The capability a method requires. Read-classified methods need `rpc:read`;
/// everything else — mempool-submit, control, block-connecting, AND unclassified
/// (unknown) methods — needs `rpc:write`. Fail-closed: an unknown method can
/// never be reached by a read-only token.
fn required_capability(method: &str) -> Capability {
    match classify(method) {
        Some(RpcAccess::Read) => Capability::RpcRead,
        _ => Capability::RpcWrite,
    }
}

batch.coin_removes.push((outpoint, coin.amount, coin.height));

// Address-history index: spending row, atomic with the
// chainstate update via the same StoreBatch. No-op when
// the index is disabled.
crate::index::address::emit_spending(
    &mut batch, address_index, height, txid,
    in_idx as u32, &coin, outpoint,
);

// outpoint_spend index: keyed by the consumed outpoint
// so Esplora outspend / gettxspendingprevout can answer
// in O(1). Same flag, same atomic batch.
crate::index::outpoint_spend::emit::emit_spend(
    &mut batch, address_index, height, txid,
    in_idx as u32, outpoint,
);

// BIP 158 filter index. Filter blob and chained filter header
// ride the same atomic batch as the chainstate update, so a
// crash mid-write rolls everything back together — protocol
// handlers can never observe a filter row whose chain segment
// is partially committed. Empty-batch fast-path skips both CFs.

addr_funding_v2  key: scripthash_prefix[16] || height_be[4] || txid[32] || vout_be[4]  (56 bytes)
                 value: amount_sat_be[8]                                               (8 bytes)

addr_spending_v2 key: scripthash_prefix[16] || height_be[4] || txid[32] || vin_be[4]   (56 bytes)
                 value: prev_outpoint_txid[32] || prev_outpoint_vout_be[4]             (36 bytes)

//! ## Collision posture
//!
//! Scripthashes are `sha256(scriptPubKey)`. A 16-byte prefix gives
//! 2^128 codomain; birthday collision probability at 2^32 entries is
//! ~2^-64 — vanishingly small for honest workloads. A deliberate
//! collision is feasible at ~2^64 hashing work, but the attack outcome
//! is "querying scripthash X also returns events for scripthash Y" —
//! both X and Y are public on-chain data, so no privacy or correctness
//! violation results for the address-index use case.

/// Compute the public tweak `T = input_hash · A` for a transaction, or
/// `None` if it is not silent-payment eligible / must be skipped.
///
/// Skip conditions (facts 1–5): coinbase; no taproot output; spends a
/// future-SegWit output; no contributing inputs; input pubkey sum is the
/// point at infinity; `input_hash` is zero or ≥ the curve order.
pub fn compute_tweak(tx: &Transaction, prevout_spks: &[ScriptBuf]) -> Option<TweakEntry> {

//! The embedded `block_hash` makes each row **self-authenticating**: any
//! reader (the D4 rescan fast path, streaming replay, the fallback RPC)
//! verifies the row describes the block it expects without consulting the
//! height→hash index — which this codebase has learned never to treat as
//! truth (the #322 accept_header clobber, the testnet4 MTP wedge). A
//! mid-read reorg surfaces as a hash mismatch and the reader falls back
//! or rejects rather than trusting height alone.

//! ## Concurrency with live `connect_block`
//!
//! - Backfill writes addr-CF rows for heights ≤ snapshot
//! - Live writes addr-CF rows for heights > snapshot
//! - Disjoint height prefixes → no key collisions; an exact-key
//!   duplicate via reorg-disconnect→reconnect at h ≤ snapshot is
//!   caught by the per-batch reorg check above and aborts the run.

//! ## Why nothing is persisted
//!
//! #546 suggested persisting an `elapsed_working_seconds` (or a resume
//! height) in the cursor. This deliberately does not: an accumulator has
//! to be flushed periodically or a `kill -9` loses it, and a persisted
//! anchor goes stale across exactly the crash-and-restart case the fix
//! exists for ... An in-memory anchor cannot survive the downtime by
//! construction. The cost is a few seconds of "no estimate" after a
//! restart while the new stint accumulates.

/// `#[must_use]` because binding it to `_` instead of a named `_stint`
/// drops it immediately, clearing the anchor before the first block is
/// walked and silently disabling every ETA. That is a one-character
/// mistake with no other symptom.
#[must_use = "the stint ends the moment this guard is dropped; bind it for the \
              duration of the walk (`let _stint = ...`), not to `_`"]
pub struct StintGuard(Arc<StintMeter>);

message Cursor {
  uint32 height      = 1; // block height of the last delivered confirmed item
  uint32 tx_index    = 2; // index within that block of the last delivered tx
  uint64 mempool_seq = 3; // best-effort mempool high-water (advisory)
  // Per-process epoch nonce of the issuing publisher. node_id is stable
  // across restarts, but mempool_seq resets to 0 each daemon start; on a
  // from_cursor resume the server discards mempool_seq when this differs
  // from the live instance (daemon restarted since the cursor was issued).
  // Confirmed (height) replay is instance-independent and unaffected.
  uint64 instance_id = 4;
}

// Per-event identity stamp applied at the publisher's bridge layer.
message EdgeStamp {
  bytes node_id = 1;          // 16 raw bytes (UUIDv4)
  string region = 2;          // up to 8 ASCII bytes; empty = unset
  uint64 edge_seen_at_ns = 3; // monotonic since publisher start
  uint64 edge_wall_ns = 4;    // wall-clock ns since Unix epoch
  uint64 seq = 5;             // monotonic per publisher, starts at 1
}

/// Categories excluded from the `categories = 0` ("all") default: opt-in,
/// high-volume, or custody-adjacent streams a legacy subscriber must not begin
/// receiving after a node upgrade.
pub const EXPLICIT_ONLY_CATEGORIES: u32 = CATEGORY_TWEAKS | CATEGORY_STATUS;

/// Registry of per-subscriber outpoint/script watch-sets with O(1)
/// matching. Cheap to consult when empty (a single atomic load).
pub struct WatchRegistry {
    inner: RwLock<Inner>,
    next_id: AtomicU64,
    /// Lock-free count of registered watch *items* (outpoints + scripts)
    /// across all subscribers. The matcher checks this before re-reading a
    /// block, so a node with no watchers does zero extra work.
    watch_items: AtomicUsize,
    /// Lock-free count of registered *script* items only. Gates the
    /// input-side script match: the matcher fetches a block's undo data (to
    /// recover spent prevout scriptPubKeys) only when some script is watched,
    /// so an outpoint-only watch-set pays nothing extra.
    script_items: AtomicUsize,

//! [`ResilientSubscription`](crate::ResilientSubscription) wraps the one-way
//! `Subscribe` firehose; [`ResilientWatch`] is its twin for the bidirectional
//! `Watch` stream. It exists because the two recovery stories differ:
//!
//! - **The watch-set is per-connection.** The server holds no principal-keyed
//!   state — when a `Watch` stream drops, its server-side watch-set and quota
//!   leases are torn down with it. A reconnect therefore starts blank, so the
//!   SDK has to **mirror** every add/remove the caller makes and **re-register**
//!   the whole set on the new stream before anything matches again.
//! - **Re-anchor is in-band and deterministic (#439/#441).** Once the watch-set
//!   is back, a single `set_cursor` replays confirmed history; the server
//!   answers with exactly one [`Event::CursorAccepted`] ... or
//!   [`Event::CursorRejected`]. [`ResilientWatch`] drives its catch-up off those
//!   deterministic results instead of inferring a gap from the event flow.

// Wait for the server's response headers before handing the stream back.
//
// grpc-go starts a server-streaming call without waiting for the server to
// accept it, so without this Subscribe returns before the node has
// registered the subscription - and anything the caller triggers in that
// window (mining a block, broadcasting a transaction) is simply not on the
// stream. That silent race is a bad default for an event API: "subscribe,
// then do the thing" has to work.
if _, err := sc.Header(); err != nil {

/// No block connected for longer than the configured window. Clears when
/// the next block connects.
///
/// Deliberately *not* suppressed during initial block download:
/// `is_initial_block_download()` compares the tip header's timestamp
/// against the wall clock rather than tracking sync progress, so a node
/// that was caught up and then wedged re-enters it exactly when the
/// operator most needs paging. A node that is genuinely syncing connects
/// blocks continuously and never crosses the threshold on its own.
TipStall,

/// One configured webhook.
///
/// `Debug` is hand-written: a derived one renders `secret` in full, and a
/// single `tracing::debug!(?hook)` added later would put a signing key in the
/// log. The crate already takes this posture for watch-set scan keys.
#[derive(Clone, PartialEq, Eq)]
pub struct Hook {

//! Two dedicated `std::thread`s — deliberately not tokio tasks. During the
//! 2026-05 mainnet IBD wedge the entire tokio runtime parked itself (every
//! worker in `futex_do_wait`, no progress for nine hours, RPC accept queue
//! piled up to 3084 backlogged connections). A watchdog scheduled on the
//! same runtime that froze would have frozen with it, so this module spawns
//! its own OS threads.