01 — Event Bus

Companion to 00-overview. This is the authoritative, source-verified reference for every chase enumerator: payload, issuer sites, handler sites, and known discrepancies with the inline chase.hpp documentation.

Every fact below is grep-derived against master at a5173475. Methodology and queries are in §4 so any future change can be re-verified mechanically.

1. Subscriber model#

1.1 Storage#

event_subscriber_ : full_node                     // include/bitcoin/node/full_node.hpp:219
   = network::desubscriber<object_key, event_value>   // define.hpp:84

A desubscriber is the libbitcoin-network primitive that combines pub/sub with explicit unsubscription via a key. All subscribers share one bus.

1.2 Typed payloads#

event_value is a std::variant with one alternative per chase enumerator, declared in enum order in namespace chases (include/bitcoin/node/chase.hpp). Each payload struct carries a static constexpr chase id and zero or one field:

A static_assert(is_chase_ordered(...)) guarantees the variant index equals the enumerator, so to_chase(value) is static_cast<chase>(value.index()) and to_payload<chase::X>(value) is a std::get by that index.

Invariant (Bus-0). An event cannot carry the wrong payload type: the payload struct is the event. Handlers switch on to_chase(value) and read to_payload<chase::X>(value).field.

1.3 Subscribe protocol#

There are two subscribe APIs, both eventually owning state on the full_node strand:

Chaser subscription path (include/bitcoin/node/chasers/chaser.hpp:100-101, src/chasers/chaser.cpp:91-94):

chaser::subscribe_chase
  → full_node::subscribe_chase(handler)          // src/full_node.cpp:247-253
    → event_subscriber_.subscribe(handler, key)

Each chaser subscribes exactly once, in its start(), via SUBSCRIBE_CHASE(handle_chase, _1, _2) (chaser.hpp:166-167). The handle_chase body runs on the node strand and POSTs the work to the chaser's own strand.

Protocol subscription path (src/protocols/protocol.cpp:183-232):

protocol::subscribe_chase
  → session::subscribe_chase(handler, complete)  // src/sessions/session.cpp:114-118
    → full_node::subscribe_chase(handler, complete) // src/full_node.cpp:255-270
      → posts to strand → do_subscribe_chase
        → event_subscriber_.subscribe(handler, key)
        → complete(ec, key)   → protocol::handle_subscribe stores key_
                               → handle_subscribed posts subscribed() to channel strand

The async variant exists because a protocol is constructed on its channel strand, not the node strand, so it must hop across. Subscription is asynchronous, so a protocol may miss events emitted before it completes (the source notes this at every protocol subscription site).

1.4 Notify protocol#

chaser/protocol calls notify(ec, chases::X{...})
   → full_node::notify posts to strand           // src/full_node.cpp:217-222
     → do_notify on strand
        → event_subscriber_.notify(ec, value)     // :225-229
           → each subscriber's handle_chase runs here and POSTs to its own strand

notify_one(key, ...) (:231-245) delivers to a single subscriber by key; it is used for chase::split (targeting the slowest channel) and for chase::stop on unsubscribe.

1.5 Unsubscribe semantics#

full_node::unsubscribe_chase(key) does not remove the entry; it sends a single chases::stop to that subscriber only (src/full_node.cpp:272-275). The subscriber's handle_chase returns false on chase::stop, and the desubscriber interprets that as removal. So:

Invariant (Bus-1). A false return from handle_chase means "remove me". Every chaser returns false on chase::stop and when closed(); protocols return false when stopped().

Invariant (Bus-2). The bus is torn down only in full_node::do_close, which broadcasts chases::stop to all subscribers (src/full_node.cpp:154). After that point no further notify will deliver.

2. Verified event reference#

Notation:

• Issuer is every notify(... chases::X{...}) or notify_one(... chases::X{...}) call site that is not commented out. Direct self-calls of handle_chase (not through the bus) are listed as self.

• Handler is every case chase::X: arm that is not commented out.

• Discrepancies with the chase.hpp inline doc are flagged ⚠.

2.1 Work shuffling#

Discrepancy notes:

• ⚠ bump: chase.hpp says issued by 'organize'. chaser_validate also issues it when a silent-payment bank drains, because the blocks of that bank may now be confirmable (chaser_validate_batch.cpp:396-397).

• ⚠ suspend is also issued by chaser_header after a disorganization (chaser_header.cpp:546-549), to reset all connections.

• ⚠ snap has no live issuer anywhere in this repo. Treat as dormant.

2.2 Candidate chain#

2.3 Check / Identify#

2.4 Accept / Connect#

2.5 Confirm (block)#

2.6 Confirm (chain) and Mining#

Discrepancies:

• ⚠ block: chase.hpp lists protocol_header/block_out/estimator. chaser_snapshot (one-shot prune trigger), session_outbound (connection count) and protocol_transaction_out_70013 (fee filter refresh) are also live consumers.

• ⚠ stale: chase.hpp lists protocol_transaction_out; session_outbound also consumes it.

2.7 Stop#

3. Verified issuer / handler diagram#

One node per actual source location rather than per chase.hpp comment.

chase::confirmable has no consumer and chase::snap / chase::template_ have no issuer, so they are omitted.

4. Methodology#

The tables above were generated by these greps from repo root:

# Issuers (all notify and notify_one sites)
grep -rn 'notify\(_one\)\?(' src include | grep 'chases::'

# Direct self-calls that bypass the bus
grep -rn 'handle_chase(.*chases::' src

# Handlers
grep -rn 'case chase::' src include | grep -v '////'

# Subscription sites
grep -rn 'SUBSCRIBE_CHASE\|subscribe_chase' src

To recheck after source changes, run the same set and diff against the tables here. Any new row must come with its source citation, and any deletion should be cross-referenced with this doc to ensure no downstream spec assumes the old behaviour.

5. Specification view#

A formal model can treat the bus as follows.

Processes. Each chaser and each event-subscribing protocol is a process P with:

• a single inbox typed (code, event_value)
• a private state space Σ_P
• a deterministic transition δ_P : Σ_P × (code, event_value) → Σ_P × Output_P
• where Output_P is a finite set of notify calls and outbound asynchronous actions (e.g. DB writes).

Bus. The bus is broadcast-with-filter: every notify(ec, v) is delivered to every subscriber, and each subscriber's handle_chase inspects to_chase(v) to decide whether to act. notify_one is a point-to-point exception used only for split and stop.

Invariants worth proving.

1. Liveness of stop: after full_node::do_close, every process eventually reaches a terminal state. (Follows from Bus-2 + the universal case chase::stop: return false;.)

2. Disorganize convergence: every chase::regressed/disorganized is eventually responded to by the consuming chasers' "rewind" branches (chaser_download.cpp:348-364, chaser_validate.cpp:170-177, chaser_confirm.cpp:129-132) before the next forward event is processed.

3. No spurious validation: chase::valid is emitted only from chaser_validate::notify_block (chaser_validate.cpp:366), after either full validation, bypass processing, or batch verification of the height.

4. Confirm uniqueness: chase::confirmable, unconfirmable, organized, reorganized, block, stale all have a single issuer (chaser_confirm). Confirmation is centralized.

5. Two archivers: chase::checked and chase::unchecked have exactly two issuers — the download protocol and the compact block fill in chaser_transaction — and both write the block association before emitting (docs 06 §5.6, 11 §3).

Dormant events (do not model as live).

• chase::snap — handler exists, no issuer.

• chase::template_ — handler is "miners" (external), no issuer in this repo.

• chase::report — issuer is the executor (external, libbitcoin-server).

• chase::confirmable — issued, no handler.

Cross-references#

• 00-overview §3 (concurrency model) and §4 (high-level event table).

• 02-chaser-header — the state machine that emits bump, regressed, disorganized, headers, suspend.

• 04-chaser-validate — the unique issuer of valid / unvalid.

• 11-chaser-transaction — the issuer of transaction and the second issuer of checked/unchecked.