Proto commits in ethpandaops/xatu

These commits are when the Protocol Buffers files have changed: (only the last 100 relevant commits are shown)

2026-11-06

feat(clickhouse): record graffiti on beacon_api_eth_v2_beacon_block (#944) * feat(clickhouse): record graffiti on beacon_api_eth_v2_beacon_block The sentry's v2 beacon block event already carries the block body. Store its graffiti (hex) and graffiti_text, decoded as canonical_beacon_block_graffiti does, so blocks have graffiti before finality, when cannon writes the canonical table. Migration 026 adds both columns as Nullable: rows written before the change stay NULL. Amp-Thread-ID: https://ampcode.com/threads/T-01a1a613-5e21-7546-b696-82566daaf71f Co-authored-by: Sam Calder-Mason <samcaldermason@gmail.com> * chore(clickhouse): regenerate pkg/proto/clickhouse, share graffiti decoding Regenerate beacon_api_eth_v2_beacon_block in pkg/proto/clickhouse with clickhouse-proto-gen 0.0.29 and protoc-gen-go v1.34.2 against the migrations. Head and canonical graffiti now decode through route.DecodeGraffiti so their graffiti_text can't drift apart. Amp-Thread-ID: https://ampcode.com/threads/T-01a1a613-5e21-7546-b696-82566daaf71f Co-authored-by: Sam Calder-Mason <samcaldermason@gmail.com> * test(clickhouse): name graffiti cases without repeating constants Amp-Thread-ID: https://ampcode.com/threads/T-01a1a613-5e21-7546-b696-82566daaf71f Co-authored-by: Sam Calder-Mason <samcaldermason@gmail.com> --------- Co-authored-by: Amp <amp@ampcode.com> Co-authored-by: Sam Calder-Mason <samcaldermason@gmail.com>

2026-10-30

feat(cannon): derive phase0 attestation and block rewards from beacon states (#933) * feat(cannon): derive phase0 attestation and block rewards from beacon states The Beacon API rewards endpoints only serve Altair onwards, so mainnet has no reward data for its first 74240 epochs. The new phase0Reward deriver computes them from the beacon state at the last slot of each epoch with the consensus spec's phase0 rules (zrnt's get_attestation_deltas), splitting the inclusion delay deltas into the attester's reward and the including proposer's share. It writes one row per eligible validator per epoch to canonical_beacon_phase0_attestation_reward (head, target, source, inclusion_delay, inactivity) and one row per block to canonical_beacon_phase0_block_reward (attestations, proposer_slashings, attester_slashings). Its iterator head stays at the epoch before Altair, so backfill walks down to genesis. Disabled by default. Tests check every component against the reference spec's deltas, and replay reference-spec chains to check each validator's balance change equals the computed rewards plus deposits and slashing penalties, to the gwei. Amp-Thread-ID: https://ampcode.com/threads/T-01a18d28-393c-77fe-a713-58824b2e7764 Co-authored-by: Sam Calder-Mason <samcaldermason@gmail.com> * test(cannon): fix lint in the phase0 reward tests Amp-Thread-ID: https://ampcode.com/threads/T-01a18d28-393c-77fe-a713-58824b2e7764 Co-authored-by: Sam Calder-Mason <samcaldermason@gmail.com> --------- Co-authored-by: Amp <amp@ampcode.com> Co-authored-by: Sam Calder-Mason <samcaldermason@gmail.com>

2026-10-26

fix(clickhouse): describe canonical_execution_transaction value as wei (#931) The value column comment said "in float64", but the column is a UInt256 loaded from cryo's exact decimal value_string, so it holds the exact transaction value in wei. A migration rewrites the comment on the local and distributed tables, and the generated proto comments match. Amp-Thread-ID: https://ampcode.com/threads/T-01a17699-4289-70c7-88ca-e56bd9f26135 Co-authored-by: Amp <amp@ampcode.com> Co-authored-by: Sam Calder-Mason <samcaldermason@gmail.com>

2026-10-20

fix(clickhouse): key structlog synthetic rows apart from their CALL row (#927) execution-processor adds a row after every CALL-family opcode whose target ran no code. It reuses the CALL's index, so it shared the full sorting key of canonical_execution_transaction_structlog with the CALL row and ReplacingMergeTree kept only one of the two. Migration 023 adds a Bool `synthetic` column and appends it to the sorting key in the same ALTER, which ClickHouse applies as a metadata-only change (no part rewrite, no mutation; the primary index stays on the old four columns). It also documents call_to_address for CREATE/CREATE2 rows.

fix(clickhouse): rebuild four_byte_counts keyed on signature and size (#925) Databases created before 85e461b0 still have canonical_execution_four_byte_counts_local ORDER BY (meta_network_name, block_number, transaction_hash): that commit put `signature` into the key by editing 001_init, which CREATE TABLE IF NOT EXISTS never applies to an existing table. ReplacingMergeTree keeps one row per transaction, so about 85% of cryo's rows are lost on every network (mainnet 25000000-25000009: 7753 cryo rows, 2085 FINAL). 001_init's key is not unique either: the 4byte tracer counts selector-and-calldata-size pairs, so a transaction can carry one selector at several sizes (hoodi 3800000-3800199: 6240 rows, 5776 distinct (tx, signature), 6240 distinct (tx, signature, size)). Migration 021 rebuilds the table keyed on (meta_network_name, block_number, transaction_hash, signature, size): it copies every row shard-locally into the new-key table, swaps it in with EXCHANGE TABLES, copies the last day of rows again to catch inserts that hit the old table during the bulk copy, and keeps the old table as canonical_execution_four_byte_counts_migrate_bak_local for verification and rollback. Rows the old key already collapsed need a cannon re-derive. pkg/proto/clickhouse is regenerated for the new key.

feat(cannon): attestation payload votes, EIP-7702 authorizations, execution block header parity (#918) * feat(cannon): store Gloas payload header, attestation payload votes and EIP-7702 authorizations - canonical_beacon_block: for Gloas blocks the beacon block deriver now fetches the block's payload envelope (shared, cached fetch) and fills the execution_payload_* columns, transaction stats, payload_present, execution_payload_slot_number and execution_payload_block_access_list_root (keccak256 of the RLP BAL, the value the EL header commits to). These were NULL for every Gloas row, and slot_number / BAL root / payload_present were never written for any fork. - canonical_beacon_elaborated_attestation: new payload_present column. From Gloas the attestation data index is the attester's payload vote; the deriver overwrote it with the committee index, so the vote was lost. - canonical_beacon_block_execution_transaction: new authorization_* arrays (chain id, delegate address, nonce, recovered authority) for EIP-7702 set code transactions, which were not stored anywhere. * fix(cannon): keep Gloas execution payload columns NULL on canonical_beacon_block The Gloas payload is no longer part of the beacon block, so the block row stays NULL for execution_payload_* (and transaction stats) instead of being filled from the envelope. payload_present is still set from whether the builder revealed the payload. * feat(cannon): store parent hash, state root and blob gas on canonical_execution_block With Gloas the execution payload no longer rides the beacon block, so canonical_beacon_block's execution_payload_* columns stay NULL from Gloas on. canonical_execution_block now carries the header fields it was missing (parent_hash, state_root, blob_gas_used, excess_blob_gas), so every fork has them in one place. cryo's blocks dataset has no blob gas columns, so the Dockerfile applies a small patch adding them; the new column list needs that patched cryo. * chore(migrations): renumber cannon block payload fields to 021 after #923 took 020

feat(clickhouse): document change-point structlog return_data (#923) return_data on canonical_execution_transaction_structlog is set only on the first opcode after a CALL/CREATE-family opcode returns, from execution-processor v0.3.0. The column comment now says so and how to recover each opcode's buffer.

feat(libp2p): capture gossipsub partial data column messages (#915) * feat(libp2p): gossipsub partial data column event contract Proto messages, event numbers and clmimicry payload types for capturing the gossipsub partial messages extension (cell-level PeerDAS column dissemination): - LIBP2P_TRACE_GOSSIPSUB_PARTIAL_DATA_COLUMN (146/134/267): one row per partial RPC part, either direction - LIBP2P_TRACE_DATA_COLUMN_COMPLETED (147/135/268): custody column became fully available, with the path that completed it - LIBP2P_TRACE_GOSSIPSUB_PARTIAL_DATA_COLUMN_OUTCOME (148/136/269): validation verdict per received partial - SubMeta/SubMetaItem requests_partial and supports_sending_partial * chore(proto): regenerate event_ingester vtproto with per-directory local plugins Matches the master generation style: only pkg/proto/xatu messages are local, so cross-package fields keep the interface-asserted marshal form and the diff against master is purely additive. * feat(clickhouse): partial data column tables and subscription partial flags Migration 019 adds libp2p_gossipsub_partial_data_column, libp2p_data_column_completed and libp2p_gossipsub_partial_data_column_outcome, and appends requests_partial / supports_sending_partial to libp2p_rpc_meta_subscription. * feat(consumoor): routes for partial data column events and subscription partial flags * feat(proto): generated clickhouse read types for partial data column tables * feat(server): accept partial data column, completion and outcome events * feat(clmimicry): route partial data column, outcome and completion events Each event has its own enable flag (default off) and shards as a Group B (topic only) event. Block slot, epoch and propagation are set only when the capture point resolved the slot. RPC meta subscriptions now carry the partial messages SubOpts flags, unset when the tracer cannot see them. * chore: tighten comments

2026-10-19

feat(cannon): beacon block graffiti deriver (#905) Adds BEACON_API_ETH_V2_BEACON_BLOCK_GRAFFITI: one event per canonical block carrying the proposer index and the raw 32 byte graffiti, written to the new canonical_beacon_block_graffiti table (migration 018) with graffiti_text decoded as UTF-8 (trailing nulls trimmed, invalid sequences replaced). It is a separate deriver rather than a column on canonical_beacon_block so it gets its own coordinator location and backfills history from phase0 without re-deriving the block table. Graffiti carries the client version codes most clients now append (e.g. GEa579PMfea2 = geth + prysm), which xatu otherwise has no source for on public networks. Generated code (route .gen.go, pkg/proto/clickhouse, pkg/proto/xatu) was produced with the repo's generators; pre-existing outputs regenerate byte-identically. The cannon smoke test now seeds and asserts the new table.

2026-10-08

Merge remote-tracking branch 'origin/master' into feat/fork-choice-v2 # Conflicts: # go.mod # go.sum

feat(sentry): follow the merged fork choice v2 spec Bump go-eth2-client to ethpandaops/go-eth2-client#60 as aligned with ethereum/beacon-APIs#615 as merged: - Nodes carry justified and finalized checkpoints. They are kept as the new ForkChoiceNodeV2 justified_checkpoint / finalized_checkpoint fields and, as before, as justified_epoch / finalized_epoch, and are round-tripped into extra_data for consumers of the v1 shape. - Weight and the PTC counts are always set. go-eth2-client now rejects v2 responses that do not follow the spec, which is every client today. Any v2 failure, not only an unsupported endpoint, now falls back to v1 for forkChoiceV2RetryInterval, so such nodes keep producing fork choice data without a warning on every fetch. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Merge remote-tracking branch 'origin/master' into feat/fork-choice-v2

chore(proto): regenerate pkg/proto/clickhouse with clickhouse-proto-gen 0.0.29 Picks up the column comments changed by migrations 016 and 017. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Merge remote-tracking branch 'origin/master' into feat/event-spec-fields

fix(proto): regenerate pkg/proto/clickhouse and check it in CI (#903) * fix(proto): regenerate pkg/proto/clickhouse and check it in CI The package was generated once (#886) and never again, so the 25 tables from the Gloas migrations had no protos and v2_beacon_block, canonical_beacon_block and canonical_beacon_block_withdrawal were missing their Gloas columns. Regenerated with clickhouse-proto-gen 0.0.29, which fixes the field naming that made a fresh regeneration fail to compile. The Makefile pins that generator version instead of :latest (0.0.28 did not support all_tables), and a new workflow regenerates from the migrations on every relevant PR and fails if the package drifts. * fix(proto): run the generator as the calling user On Linux the container wrote pkg/proto/clickhouse/clickhouse as root and buf generate could not open it.

fix(clickhouse): store self-built block builder_index as NULL Beacon nodes send BUILDER_INDEX_SELF_BUILD (UINT64_MAX) as builder_index for self-built payloads. Map it through route.NullableBuilderIndex like the other builder_index routes (migration 012), so it does not skew aggregates. Also moves the execution_optimistic snapshot assertions into their own test so the existing snapshot tests stay unchanged (goconst). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

feat: store spec event fields dropped on the way to ClickHouse - head, finalized_checkpoint, chain_reorg: execution_optimistic. The ClickHouse columns already existed but the routes hard-coded false, because neither go-eth2-client nor the protos carried the field. - block: builder_index and block_hash (beacon-APIs #641, Gloas onwards). New nullable columns. - fast_confirmation: current_slot (beacon-APIs #616). New nullable column. current_slot is excluded from the sentry duplicate hash: the event fires on every run, so the first run that confirms a block is kept and its current_slot gives the confirmation delay. Bumps go-eth2-client to ethpandaops/go-eth2-client#63, which decodes these fields. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

2026-10-07

feat(sentry): fetch Gloas-aware v2 debug fork choice The sentry now fetches GET /eth/v2/debug/fork_choice (ethereum/beacon-APIs#615), which returns one node per (block root, payload status) pair, and falls back to v1 for beacon nodes that do not serve it (retrying v2 hourly). Since Gloas, the v1 endpoint returns up to three indistinguishable nodes per block on some clients, and none of them report payload_status in extra_data, so ForkChoiceNodeV2's payload_status was never set. ForkChoiceNodeV2 gains the v2 fields: parent_payload_status and the Payload Timeliness Committee vote counts. ForkChoiceV2 gains the fork choice store's extra_data (e.g. the unrealized justified checkpoint), from both endpoints. All additive, so event names, Kafka topics and downstream routes are unchanged. Consumers converting to the go-eth2-client v1 shape still see the new fields in extra_data, and a node without extra data no longer panics that conversion. Bumps github.com/ethpandaops/go-eth2-client to the fork choice v2 branch (ethpandaops/go-eth2-client#60). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

feat(sentry): fetch Gloas-aware v2 debug fork choice The sentry now fetches GET /eth/v2/debug/fork_choice (ethereum/beacon-APIs#615), which returns one node per (block root, payload status) pair, and falls back to v1 for beacon nodes that do not serve it (retrying v2 hourly). Since Gloas, the v1 endpoint returns up to three indistinguishable nodes per block on some clients, and none of them report payload_status in extra_data, so ForkChoiceNodeV2's payload_status was never set. ForkChoiceNodeV2 gains the v2 fields: parent_payload_status and the Payload Timeliness Committee vote counts. ForkChoiceV2 gains the fork choice store's extra_data (e.g. the unrealized justified checkpoint), from both endpoints. All additive, so event names, Kafka topics and downstream routes are unchanged. Consumers converting to the go-eth2-client v1 shape still see the new fields in extra_data, and a node without extra data no longer panics that conversion. Bumps github.com/ethpandaops/go-eth2-client to the fork choice v2 branch (ethpandaops/go-eth2-client#60). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

2026-10-01

feat(cannon): add Gloas beacon state derivers (#895) Adds five Gloas cannon derivers that read the beacon state once per finalized epoch: the ordered payload timeliness committee from ptc_window, the builder registry, builder pending payments, builder pending withdrawals, and the execution payload availability bits. They share a single SSZ state download per epoch and write to new canonical_beacon_state_* tables (migration 015).

feat(cannon): Gloas builder execution requests and per-block BAL summary derivers (#894) * feat(cannon): derive gloas builder execution requests and per-block BAL summary Adds executionRequestBuilderDeposit, executionRequestBuilderExit and blockAccessListSummary cannon derivers (activate at Gloas) with proto events, migrations 013/014 and server wiring. ClickHouse route code follows in a later commit. * feat(clickhouse): consumoor routes and tests for builder requests and BAL summary Generated rows via chgo-rowgen from migrations 013/014, plus validated route flattening, deriver tests, config toggle tests and location round-trips.

2026-09-29

fix: keep master's released proto and migration numbering for gloas LIBP2P_TRACE_GOSSIPSUB_MESSAGE_PAYLOAD shipped on master as event 119, additional_data field 107 and data field 240, with ClickHouse migration 006. The devnet branch had reassigned those numbers to gloas entries, so payload goes back to its released slots and the displaced gloas entries take the devnet payload numbers (136/124/257). Gloas migrations move to 007-011; 012 is unchanged.

Merge remote-tracking branch 'origin/release/glamsterdam-devnet-11' into feat/gloas-to-master

2026-08-24

feat: add typed ClickHouse read package (pkg/proto/clickhouse) (#886) * feat: add typed ClickHouse read package (pkg/proto/clickhouse) Generate and commit a typed read surface for the xatu ClickHouse tables using clickhouse-proto-gen: per-table proto messages with typed filter requests, parameterized SQL query builders, and ClickHouse-scannable row structs with ToProto converters. Generation runs against a scratch ClickHouse built from the repo's own migrations (make proto-clickhouse), so the committed package always matches the schema at HEAD. Shard-local tables are excluded; the Distributed wrappers resolve their sorting keys through the underlying tables. Downstream consumers (e.g. dora) import this package for compile-time safe queries: a schema change that removes or retypes a column breaks their build at dependency bump time instead of failing at runtime. Claude-Session: https://claude.ai/code/session_01PqWvkAjYgCjjhtu83gJeXP * make proto regenerates the ClickHouse read package too Claude-Session: https://claude.ai/code/session_01PqWvkAjYgCjjhtu83gJeXP

2026-08-20

feat: add typed ClickHouse read package (pkg/proto/clickhouse) Generate and commit a typed read surface for the xatu ClickHouse tables using clickhouse-proto-gen: per-table proto messages with typed filter requests, parameterized SQL query builders, and ClickHouse-scannable row structs with ToProto converters. Generation runs against a scratch ClickHouse built from the repo's own migrations (make proto-clickhouse), so the committed package always matches the schema at HEAD. Shard-local tables are excluded; the Distributed wrappers resolve their sorting keys through the underlying tables. Downstream consumers (e.g. dora) import this package for compile-time safe queries: a schema change that removes or retypes a column breaks their build at dependency bump time instead of failing at runtime. Claude-Session: https://claude.ai/code/session_01PqWvkAjYgCjjhtu83gJeXP

2026-07-17

Merge master into release/glamsterdam-devnet-7: gossipsub message payload event Brings LIBP2P_TRACE_GOSSIPSUB_MESSAGE_PAYLOAD (#877) onto the devnet branch. Proto numbering reconciled: this branch had already assigned the numbers master used, so the event takes 136 (enum), 124 (ClientMeta oneof) and 257 (DecoratedEvent oneof) here, with notes for eventual convergence. Generated protos rebuilt; categorizer union of the ePBS and payload events. Claude-Session: https://claude.ai/code/session_01KDvdo7uVQpxKWgk2gLnWpE

feat: add gossipsub message payload event for raw wire-bytes capture (#877) * feat: add gossipsub message payload event for raw wire-bytes capture Adds LIBP2P_TRACE_GOSSIPSUB_MESSAGE_PAYLOAD end-to-end: proto event and payload messages, clmimicry handler (opt-in via gossipSubMessagePayloadEnabled, off by default), event-ingester registration, ClickHouse table libp2p_gossipsub_message_payload, and the consumoor route. The table's sorting key and distributed sharding key are content-derived (message IDs are content hashes), so identical messages captured by multiple vantage points deduplicate on merge. Payload bytes are stored exactly as received off the wire, so capture works for any topic without a decoder, including validation-rejected messages. Claude-Session: https://claude.ai/code/session_01KDvdo7uVQpxKWgk2gLnWpE * refactor: append validated payload route fields unconditionally validate() already rejects events missing the wallclock fields or message ID, so the sentinel-zero fallback branches were unreachable and read as if missing data could silently insert epoch-zero timestamps. Claude-Session: https://claude.ai/code/session_01KDvdo7uVQpxKWgk2gLnWpE * refactor: drop observation-scoped columns from payload table The table deduplicates by content-derived message ID across capture clients, so per-observation columns were nondeterministic: whichever row survived the merge won. peer_id_unique_key and reject_reason are dropped (peer attribution and reject reasons live in libp2p_deliver_message and libp2p_reject_message), and outcome moves into the sorting key so a message delivered by one client and rejected by another keeps one row per outcome instead of racing. Claude-Session: https://claude.ai/code/session_01KDvdo7uVQpxKWgk2gLnWpE * refactor: drop outcome column from payload table The table stores message content keyed by content-derived message ID; validation outcome is a fact about an observation, not the bytes, and lives per-vantage in libp2p_deliver_message and libp2p_reject_message. This also collapses fork-contested messages (delivered by some clients, rejected by others) to a single row. The proto event keeps outcome and reject_reason for stream consumers. Claude-Session: https://claude.ai/code/session_01KDvdo7uVQpxKWgk2gLnWpE * fix: accept empty message data in payload handler A nil Data slice is a legitimate zero-byte message, and rejecting it meant exactly that class of message was never archived. Also documents that dedup is best-effort for messages received across wallclock slot or partition boundaries. Claude-Session: https://claude.ai/code/session_01KDvdo7uVQpxKWgk2gLnWpE

The documentation is generated from this commit.

2026-07-16

feat: add gossipsub message payload event for raw wire-bytes capture Adds LIBP2P_TRACE_GOSSIPSUB_MESSAGE_PAYLOAD end-to-end: proto event and payload messages, clmimicry handler (opt-in via gossipSubMessagePayloadEnabled, off by default), event-ingester registration, ClickHouse table libp2p_gossipsub_message_payload, and the consumoor route. The table's sorting key and distributed sharding key are content-derived (message IDs are content hashes), so identical messages captured by multiple vantage points deduplicate on merge. Payload bytes are stored exactly as received off the wire, so capture works for any topic without a decoder, including validation-rejected messages. Claude-Session: https://claude.ai/code/session_01KDvdo7uVQpxKWgk2gLnWpE

The documentation is generated from this commit.

2026-07-12

feat(sentry): land the head_v2 SSE topic as HEAD_V3 into its own table Subscribes the sentry to the gloas head_v2 beacon-API topic (via the bumped beacon + go-eth2-client pins) and lands it as a new BEACON_API_ETH_V1_EVENTS_HEAD_V3 event in a new beacon_api_eth_v1_events_head_v2 table, rather than folding it into the v1 head pipeline: - head_v2 fires twice for the same head as payload_status transitions from empty to full, so the table's grain is head x payload status (payload_status is in the sorting key) — folding it into beacon_api_eth_v1_events_head would silently double rows per head and require an irreversible sort-key ALTER on that table everywhere. - Columns follow the spec: current_epoch_dependent_root / next_epoch_dependent_root (no previous_duty_dependent_root), payload_status, execution_optimistic. - V3 internally because BEACON_API_ETH_V1_EVENTS_HEAD_V2 is the schema rev of the v1 head topic. The topic is opt-in like the other gloas SSE topics: devnet sentries add head_v2 to their beaconSubscriptions to start collecting. Claude-Session: https://claude.ai/code/session_019cbhUv62kwFTKQD5aM8FGC

2026-07-08

feat(sentry): land execution_payload / _gossip SSE events (flat shape) (#868) The EIP-7732 execution_payload / _gossip beacon-API events carry a flat payload summary, not a full SignedExecutionPayloadEnvelope, so the sentry failed to parse them across all six CL clients and both tables stayed empty since the glamsterdam rollout. Repins go-eth2-client + beacon to decode the flat event, repoints proto + handlers + route, and adds migration 009 reshaping the (empty) tables (drop state_root/slot_number, add execution_optimistic to the non-gossip table). https://claude.ai/code/session_014KRVmYwRSsK5pFbghweigM

2026-07-02

feat(gloas): update to consensus-specs v1.7.0-alpha.11 (glamsterdam-devnet-6) Bump ethpandaops/go-eth2-client to v0.1.5 and adapt to the spec changes between devnet-4 (alpha.8) and devnet-6 (alpha.11): - ProposerPreferences.gas_limit renamed to target_gas_limit (consensus-specs #5235), through proto, conversions, ClickHouse columns and routes. - EIP-8282 builder execution requests (#5359): execution requests proto gains builder_deposits/builder_exits, converted from the gloas-local ExecutionRequests container now carried by ExecutionPayloadEnvelope and gloas blocks. - Execution request derivers adapted to the versioned VersionedExecutionRequests accessor API. - canonical_beacon_block_withdrawal route now writes withdrawal_type (validator|builder), which the deriver already populated. - canonical_beacon_block_access_list gains the standard meta_consensus_version_major/minor/patch columns.

Merge master into release/gloas Resolves the 48-commit drift between release/gloas and master: - proto enum/field renumbering: master's cannon-cryo and Fulu event IDs are frozen (deployed); all gloas ePBS/BAL event IDs, AdditionalData oneof fields, DecoratedEvent data oneof fields, CannonTypes and CannonLocation oneof fields move above master's ranges. Regenerated all .pb.go via buf. - gloas cannon derivers (block access list, payload attestation, execution payload bid) adapted to master's layer-grouped deriver config (Derivers.Consensus.*) and re-registered in cannon.go. - gloas migrations re-authored into the per-schema layout as xatu/006_gloas_bals_support and xatu/007_gloas_epbs_support, converted to the database-agnostic convention (no default. prefix, Distributed(..., currentDatabase(), ...)). - event categorizer test counts updated for the 7 gloas events on top of master's 27. - envelope cache wired to the nested Beacon.BlockCacheTTL config.

2026-06-25

cannon: scaffold proto + migrations + route codegen for 11 new types through Fulu Adds shared/generated artifacts for 11 new cannon event types (Electra execution requests, rewards endpoints, state metadata, Electra state queues): - event_ingester.proto: payload + Additional*Data messages, Event.Name enum values, ClientMeta.additional_data and DecoratedEvent.data oneof fields. - coordinator.proto: CannonType enum values, CannonLocation* messages, CannonLocation.Data oneof fields. - 11 ClickHouse migration pairs (005-015) under deploy/migrations/clickhouse/xatu. - 11 generated canonical_*.gen.go route batches plus compiling route + test scaffolds (empty event names; Phase B wires them in). Also fixes the route generator to read migrations from the xatu/ subdir (broken by the per-schema migration split) and fixes the route scaffold template's package-shadowing bug.

2026-06-24

cannon: scaffold proto + migrations + route codegen for 11 new types through Fulu Adds shared/generated artifacts for 11 new cannon event types (Electra execution requests, rewards endpoints, state metadata, Electra state queues): - event_ingester.proto: payload + Additional*Data messages, Event.Name enum values, ClientMeta.additional_data and DecoratedEvent.data oneof fields. - coordinator.proto: CannonType enum values, CannonLocation* messages, CannonLocation.Data oneof fields. - 11 ClickHouse migration pairs (005-015) under deploy/migrations/clickhouse/xatu. - 11 generated canonical_*.gen.go route batches plus compiling route + test scaffolds (empty event names; Phase B wires them in). Also fixes the route generator to read migrations from the xatu/ subdir (broken by the per-schema migration split) and fixes the route scaffold template's package-shadowing bug.

2026-06-22

feat(cannon)!: add execution-layer (EL) dimension via cryo Adds an execution-layer dimension to cannon that extracts canonical execution-layer datasets with the third-party `cryo` binary and writes them straight to ClickHouse, mirroring the per-deriver/per-cursor design of the consensus-layer cannon. Every cryo dataset flows proto DecoratedEvent -> ClickHouse route -> sink, reusing the existing sink layer (no bespoke pipeline). Datasets (16, all cryo-fed): block, transaction, logs, traces, native_transfers, erc20_transfers, erc721_transfers, contracts, balance_diffs, storage_diffs, nonce_diffs, balance_reads, storage_reads, nonce_reads, four_byte_counts, address_appearances. Key pieces: - pkg/cannon/execution/cryo: dataset-agnostic cryo runner (--hex, zstd, column projection) + typed parquet reader. - pkg/cannon/deriver/execution: one deriver per dataset, chunked repeated-payload events, shared internal_index stamping (legacy cumcount parity). - pkg/cannon/iterator/backfilling_block_iterator: CL-finality-gated block iterator (never iterates past the execution block of the CL-finalized beacon block); head walks up, backfill walks down to a floor. State-read datasets are floored to block >=1 (genesis is untraceable by cryo's state tracer). - pkg/clickhouse/route/execution: 16 columnar ClickHouse routes. - proto: 16 ExecutionCanonical* event types + CannonType + CannonLocation wrappers + BackfillingBlockMarker. - Dockerfile: build cryo from a pinned git commit (master exposes gas_limit; pinning gives reproducible builds + stable state-read semantics). Schema fix: canonical_execution_four_byte_counts ORDER BY now includes `signature` -- the prior key collapsed a tx's multiple selectors into one row under ReplacingMergeTree. Validated against the legacy (old-script) prod data across genesis->24M and all fork boundaries: 12/16 datasets byte-identical; the 3 state-reads capture more (newer cryo, desired); four_byte_counts fixed; remaining diffs are prod's known-missing data (the reason for this work) and a single DAO-fork balance_diffs.to_value edge. End-to-end run validated on mainnet (beacon + EL + coordinator + ClickHouse): CL-gating, per-dataset Postgres cursors, and the direct-to-ClickHouse sink all confirmed. Out of scope: transaction structlog (not cryo-fed the same way); extra_data_string for non-UTF8 blocks (proto3 string limit); range-sharded backfill (future). BREAKING CHANGE: the xatu-server output (type: xatu) is now rejected by cannon at config validation, for both CL and EL data -- cannon writes directly to ClickHouse. Existing cannon configs using a `type: xatu` output must switch to a `type: clickhouse` output. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-17

fix(libp2p): restore libp2p_join/leave by keying on local_peer_id (#848) * fix(libp2p): use local_peer_id for join/leave routing and dedup libp2p_join and libp2p_leave events come from go-libp2p-pubsub's RawTracer Join(topic)/Leave(topic) callbacks, which carry no remote peer. The clickhouse route validator required a non-empty peer id and dropped every join/leave event (visible as 'nil PeerId: invalid event' in consumoor), so neither table has received data since the clickhouse-raw cutover. Add a local_peer_id field to the join/leave client metadata, populated from the producer's own host ID, and key routing/dedup off it (peer_id_unique_key -> local_peer_id_unique_key). Migration 004 recreates the two tables with the renamed sorting-key column, preserving existing rows via a temporary backup. Pairs with the tysm tracer change that stamps the local host ID onto join/leave. Co-authored-by: original branch feat/libp2p-join-leave-local-peer-id * fix(migration,test): comment-safe migration splitting + goconst constants - Migration 004: remove semicolons from SQL comments. golang-migrate's x-multi-statement splitter is not comment-aware, so a ';' inside the leading comment produced a comment-only chunk and failed with 'code 62, Empty query'. - Tests: extract repeated column/topic literals into shared constants to satisfy goconst. * fix(migration): make 004 database-agnostic Drop hardcoded 'default.' table prefixes and use currentDatabase() in the Distributed engine database arg, matching the db-agnostic migration convention from the per-set migrations refactor. Unqualified table names resolve to the migrator connection's database.

2026-05-29

feat(event_ingester.pb.go): rename event constants and update proto types for consistency with the new API design This change modifies the event constant names and proto types, ensuring they align with the updated API structure. The changes improve clarity and foster easier integration and maintenance of the event ingestion system. refactor(proto): reorder fields in event_ingester.pb.go for improved organization and readability. This change enhances the maintainability of the code by establishing a more logical structure. refactor(proto): rename fields in Event message for clarity and consistency fix(proto): update method signatures in event_ingester_vtproto for renamed fields to match updated Event message structure

Merge branch 'master' into release/gloas * master: feat(sentry-logs): make the xatu sink buffer/concurrency/timeout env-tunable (#846) feat: add state size delta and trie depth (#722) Scope consumoor Kafka traces (#844) lowercase telemetry service names (#843)

2026-05-20

feat: add state size delta and trie depth (#722) Adds execution_state_size_delta and execution_mpt_depth end-to-end: new proto events (#90/#91), consumoor ClickHouse routes, server event-ingester handlers, migration 003_state_metrics, and sentry-logs Vector parsing for geth's statesize tracer output.

2026-05-19

feat(state-metrics): UInt64 counts, schema cleanup, smoke coverage Follow-ups to PR #722. All changes are scoped to the state-metrics work introduced there; the rest of the diff is regenerated artifacts. Proto - ExecutionStateSizeDelta: switched all count/byte wrapper fields from Int64Value to UInt64Value. Writes and deletes are non-negative counts in the upstream geth tracer; signed wrappers were over-permissive. Net delta remains signed in ClickHouse (see below). ClickHouse migration 003_state_metrics - Up: - CREATE TABLE → CREATE TABLE IF NOT EXISTS for idempotent re-runs. - Qualified all table refs with `default.`. - Count/byte columns Int64 → UInt64 to match the proto change. - MATERIALIZED net-delta columns wrap inputs in toInt64(...) before subtraction; UInt64 - UInt64 stays UInt64 in ClickHouse and would wrap on underflow, so the explicit cast is required to preserve negative deltas. - ZooKeeper path normalized to `tables/{shard}/{database}/{table}` to match the convention already used by migrations 001 and 002. - PARTITION BY leads with meta_network_name so per-network operations don't have to scan every block_number bucket. - ORDER BY reordered so meta_network_name precedes block_number; single-network range scans now hit a primary-key prefix lookup. - Down: - Qualified all DROPs with `default.` and added SYNC so the drop blocks until cluster-wide cleanup completes, avoiding a stale replica between migration cycles. Docs - docs/sentry-logs.md: corrected event IDs (88/89 → 90/91) to match the enum values actually allocated in the proto. Smoke test - .github/workflows/sentry-smoke-test.yaml: inject 5 "State metrics" log fixtures alongside the existing block-metrics ones, and add a verification step asserting both execution_state_size_delta and execution_mpt_depth receive rows. Sample queries include the derived account_delta MATERIALIZED column so the toInt64 cast is exercised end-to-end. Regen - pkg/proto/... regenerated against the updated proto. - pkg/clickhouse/route/.../*.gen.go regenerated. The substantive diffs are confined to execution_state_size_delta.gen.go picking up the new UInt64 column types; the remaining file changes are import-block formatting from the codegen toolchain. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-14

Merge branch 'master' into release/gloas Resolves enum + migration collision by shifting BAL+ePBS up by 1: - BEACON_API_ETH_V1_EVENTS_FAST_CONFIRMATION keeps event enum 89, oneof field 95, oneof data field 210, and migration 002. - BEACON_API_ETH_V2_BEACON_BLOCK_ACCESS_LIST moves 89 → 90 (oneof 96/211, migration 003). - All 15 ePBS enums shift up by 1 (90 → 91 ... 104 → 105) with matching oneof field renumbering. Accepts master's consumoor-only local stack (deletes vector-http-kafka.yaml and vector-kafka-clickhouse{,-libp2p}.yaml; adds xatu-consumoor service config + xatu-server direct kafka output with topicPattern "xatu-protobuf-${event-name}"). Bumps ethpandaops/beacon to release/gloas tip 81b9ef3 to pick up both ePBS SSE hooks (release/gloas) and OnFastConfirmation (merged in from master).

refactor(state_size_delta): emit writes/deletes; derive delta in ClickHouse The execution_state_size_delta table previously stored precomputed signed deltas (account_delta, account_bytes_delta, ...). That representation lost information: a block that updates one account looked the same as a block that adds and removes accounts whose totals cancel. This refactor splits each metric into a (writes, deletes) pair carrying the gross churn: - 20 stored Int64 columns covering 5 categories x {count, bytes} x {writes, deletes}: accounts, account trie nodes, contract code, storage slots, storage trie nodes. - 10 MATERIALIZED Int64 columns derived as (writes - deletes) preserve the original delta semantics for any query that wants the net change. An "update" counts as both a write of the new value and a delete of the prev value, so (writes - deletes) recovers the net delta for all three cases (create / update / delete). Contract code remains write-only in geth's state sizer (it is content-addressed and shared across accounts, so deletion would require reference counting). The contract_code_deletes / contract_code_delete_bytes columns are present for schema symmetry and stay 0 until upstream geth grows ref-counting; contract_code_delta therefore equals contract_code_writes. Touches the geth tracer (writes/deletes nested JSON instead of delta), the proto (renamed *_delta fields to *_writes and added *_deletes), the Vector transforms (sentry-logs normaliser + kafka-to-clickhouse VRL), and the ClickHouse migration. Verified end-to-end with the test-geth 1M-block mainnet import: 1,000,001 rows in each table, MATERIALIZED delta identity holds for every row.

populate state tables from logs

feat: capture fast_confirmation beacon-api event in sentry (#830) * feat: capture fast_confirmation beacon-api event end-to-end Wires the new fast_confirmation SSE event (beacon-APIs#598) all the way through xatu: adds the proto schema, the sentry decorator + dedup cache, the server-side ingester registration, a tap on the raw event stream that decorates fast_confirmation messages (since ethpandaops/beacon doesn't yet expose a typed OnFastConfirmation), the ClickHouse table + distributed view as a new 002 migration, the consumoor rowgen and flatten logic, and a cross-cutting TestCompletenessEveryEventNameHasRoute that asserts every Event_Name has a route or an allowlisted reason. The slot field on the event is the confirmed block's slot (typically in the past), so wallclock_slot/wallclock_epoch are also populated from the sentry's wall clock, mirroring voluntary_exit. Triggered by adding fast_confirmation to ethereum.beaconSubscriptions in the sentry config. Depends on ethpandaops/go-eth2-client#24 (currently pinned via pseudo-version; bump to a tag once that merges). * make fast_confirmation derived fields Nullable Epoch 0 is genuine genesis data, not 'missing'. Sentinel-zero on optional derived columns conflated the two. Switch propagation_slot_start_diff, epoch, epoch_start_date_time, wallclock_slot/epoch and their *_start_date_time to Nullable so a real null can mean 'unknown'. slot_start_date_time stays non-null because it's in ORDER BY. * silence goconst on shared column-key test literals * lint: trim unused nolint:goconst markers * bump ethpandaops/beacon to fast_confirmation-aware tip Pulls in ethpandaops/beacon#73 so the library handleEvent switch recognises fast_confirmation, eliminating per-event 'unknown event topic' errors when a sentry subscribes to the topic. * lint: function-level nolint:goconst for snapshot tests * sentry: use beacon.OnFastConfirmation typed handler * bump ethpandaops/beacon to v0.69.0

2026-05-13

feat: add OnPayloadAttestationProcessed observe hook

feat(fast_confirmation): add wallclock_slot and wallclock_epoch The slot field carries the *confirmed* block's slot, which is typically in the past. To know when the confirmation actually arrived at the sentry, mirror the voluntary_exit pattern and add wallclock_slot + wallclock_epoch (with their *_start_date_time siblings) into the ClientMeta additional data, the ClickHouse table, the rowgen, and the sentry decorator.

feat: capture fast_confirmation beacon-api event in sentry Wires the new fast_confirmation SSE event from beacon-APIs#598 through the sentry pipeline. Adds the proto schema (xatu.eth.v1.EventFastConfirmation + BEACON_API_ETH_V1_EVENTS_FAST_CONFIRMATION enum), the sentry decorator and dedup cache, the server-side ingester handler, and an OnEvent tap that filters the raw event stream for fast_confirmation (the beacon library doesn't yet expose a typed OnFastConfirmation publisher). Triggered by adding fast_confirmation to ethereum.beaconSubscriptions in the sentry config; no other config required.

feat: PTC vote three-state breakdown + EIP-7843 slot_number coverage

feat(epbs): wire 2 synthesized observability events from beacon-node internals Adds the producer + consumer side for `BEACON_SYNTHETIC_PAYLOAD_STATUS_RESOLVED` and `BEACON_SYNTHETIC_BUILDER_PENDING_PAYMENT_SETTLEMENT` — TYSM-instrumented events that observe ePBS internal state transitions on every beacon node (multi-witness, not gossip). Naming follows the LIBP2P_TRACE_SYNTHETIC_HEARTBEAT precedent — these are "synthesized" because they don't correspond to any beacon API SSE event; they're emitted from inside prysm via TYSM's hook system. Captured by every TYSM-patched beacon node, every slot / every epoch. What you get from these: - PayloadStatusResolved: empty-slot rate, envelope timing distributions, PTC participation rate, fork-choice latency, INVALID payload transitions. - BuilderPendingPaymentSettlement: builder payment success rate (SETTLED vs DROPPED), lost-revenue totals per builder, quorum-margin distributions, builder market concentration. Changes: - pkg/proto/eth/v1/beacon_synthetic.proto — new PayloadStatusResolved + BuilderPendingPaymentSettlement message types with PayloadStatus (PENDING/FULL/EMPTY/INVALID) and BuilderPendingPaymentOutcome (SETTLED/DROPPED) enums. - pkg/proto/xatu/event_ingester.proto — 2 new Event_Name enum values (102, 103), 2 new AdditionalData messages, 2 new oneof entries in DecoratedEvent (Additional* IDs 108/109, data IDs 223/224). - pkg/clmimicry/ — 2 TraceEvent payload structs, 2 New*Payload builders, 2 TraceEvent_* constants, dispatch map entries, case arms in handleHermesRPCEvent, 2 EventConfig toggles, 2 Group D categorizer registrations, 2 TraceEventTo* converters, 2 handle* methods + 2 deriveAdditionalDataFor* helpers in a new event_beacon_synthetic.go. - pkg/server/service/event-ingester/event/beacon/synthetic/ — 2 new server handler files in a new `synthetic` package (parallels `eth/v1/`); registered in the event router. - deploy/migrations/clickhouse/003_gloas_epbs_support.up.sql — 2 new tables appended (no new migration since 003 is greenfields, not yet deployed). Both use ReplicatedReplacingMergeTree with meta_client_name in the ORDER BY composite to preserve multi-witness records. - pkg/clickhouse/route/beacon/beacon_synthetic_*.go — 2 hand-written FlattenTo routes calling the existing extractBeaconSlotEpochPropagation helper. The matching .gen.go files come from `make clickhouse-routes`. - pkg/clickhouse/route/cmd/generate/manifest.go — 1-line addition registering the `beacon_synthetic_` prefix in the codegen prefix-route table so the generator emits the new files into pkg/clickhouse/route/beacon/. - Updated existing .gen.go files from re-running `make clickhouse-routes` (rowgen tool produces a tighter output than the last commit on a few fields — the regen is consistent with the schema, no functional change). Tests: - pkg/clmimicry/event_categorizer_test.go — counts updated 33→35 events, GroupD ≥10→≥12 (the 2 new synthetic events are Group D — no Topic, no MsgID, same shape as engine API events / custody probes). - pkg/clickhouse/route/beacon/beacon_synthetic_*_test.go — placeholder snapshot tests following the existing `TODO(epbs)` pattern; they currently fail with the standard `"nil … payload: invalid event"` message awaiting real Gloas devnet captures. Verification: - buf lint / buf build → clean - go build ./... → clean - go test -race ./pkg/clmimicry/... → ok - make proto + make clickhouse-routes → clean output Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-08

feat(libp2p): rename peer_id_unique_key to local_peer_id_unique_key on join/leave The shared TraceEventMetadata.peer_id field has overloaded semantics: for most libp2p events it carries the remote peer involved (deliver/graft/prune/gossipsub/etc), but for join/leave it described the local host that subscribed/unsubscribed — there is no remote peer for those callbacks. Reusing the same field name with two meanings made the schema confusing, and pubsub.RawTracer's Join(topic) / Leave(topic) signatures don't even hand producers a peer.ID, so the field was empty in practice and the route validator hard-rejected every event. * Add a dedicated `local_peer_id` string to AdditionalLibP2PTraceJoinData and AdditionalLibP2PTraceLeaveData. * Migration 002 renames the clickhouse column `peer_id_unique_key` to `local_peer_id_unique_key` on libp2p_join_local / libp2p_leave_local (and the Distributed parents). The column is in ORDER BY so RENAME COLUMN is not supported; the migration drops and recreates the tables. * Regenerate route .gen.go files via `make clickhouse-routes`. * Route handlers read only `local_peer_id`; no fallback to the legacy metadata.peer_id. Sentries that haven't been updated will fail validation, by design. * clmimicry.handleJoinEvent / handleLeaveEvent populate the new field from the inbound TraceEvent.PeerID. Pairs with a tysm change that populates TraceEvent.PeerID with the local host's peer.ID for Join/Leave (where the libp2p RawTracer interface provides no peer.ID at all).

feat: add payload_status to ForkChoiceNodeV2

2026-05-07

feat: wire ePBS SSE handlers + cannon derivers

feat(go.proto): add new Gloas beacon block body to handle ePBS and BALs fix(go.mod): update module dependencies including OffchainLabs/go-bitfield for gas price calculations test(eth): implement tests for gas price calculations that support new Gloas structure

migrate to ethpandaops/go-eth2-client; wire ePBS sourcing

2026-03-26

feat: ebps wiring wip

feat(epbs): add server event handlers, libp2p gossipsub types, and ePBS conditional block routing

feat: prepare epbs types

2026-03-25

feat(block_access_list): add support for "touched" event for accounts with no state changes to enhance parallel execution analysis feat(proto): update BlockAccessListChange to include "touched" in change_type options for better clarity on account status

feat(proto): introduce BlockAccessListStorageRead message for enhanced storage read tracking fix(conversion): adjust handling of storage reads to use new BlockAccessListStorageRead structure

feat(gloas): add BAL storage reads and bump deps to bal-devnet-3

2026-03-24

refactor: bals structure rlp decoded

2026-03-22

feat: gloas support

2026-02-23

refactor: trace_identify plumbing

2026-02-20

feat(proto): add LIBP2P_TRACE_IDENTIFY event type to event ingester

feat(proto): add Identify message to libp2p trace proto

refactor: remove deprecated blockprint support entirely (#758) Blockprint is fully deprecated and disconnected from all runtime code paths. Remove all remaining dead code across cannon, server, proto, and config layers to reduce maintenance burden.

2026-02-12

feat: Sentry Logs - Vector-based log collection for execution client metrics (#742) * feat(sentry-logs): add Vector-based client log collection for execution metrics Introduces sentry-logs, a Vector-based log collector that extracts structured metrics from Ethereum execution client logs and sends them to Xatu server. Key features: - Collects geth "Slow block" logs containing execution metrics (timing, cache stats, state I/O) - Multi-stage Vector pipeline: parse JSON → build metadata → route by type → transform → send - HTTP endpoint on xatu-server for receiving events via protojson format - ClickHouse table for execution_block_metrics with full metric breakdown - Docker image published as ethpandaops/xatu:sentry-logs-* Configuration: - Requires XATU_CLIENT_NAME, XATU_NETWORK_NAME, XATU_SERVER_URL, XATU_AUTH env vars - Sources configured via mounted YAML files in sources.d/ - Supports file, docker_logs, and journald source types Also includes: - HTTP ingester service for xatu-server with protojson support - E2E test in sentry smoke test workflow - Documentation at docs/sentry-logs.md * Fix HTTP ingester config fallback and JSON decoding * Ensure sentry-logs sources.d is present * refactor(sentry-logs): make Vector config more composable for multi-client support Restructure the Vector configuration to support multiple execution clients: - Add client detection stage that routes logs based on format patterns - Introduce normalizer pattern: client-specific transforms convert to common schema - Add clear architecture documentation for adding new clients - Handle double-encoded JSON (geth outputs structured events as JSON strings) - Separate concerns: parsing -> detection -> normalization -> event building To add a new client: 1. Add detection condition in `detect_client` route 2. Add normalizer transform (e.g., `normalize_<client>_block_metrics`) 3. Add normalizer to `route_normalized_events` inputs Tested end-to-end with Kurtosis devnet running geth:master with --debug.logslowblock=0, verified all 31 data fields populated in ClickHouse. * fix(sentry-logs): resolve VRL compilation errors for strict Vector validation The VRL compiler was failing with E651 (unnecessary error coalescing) and E103 (unhandled fallible assignment) errors. This was causing the sentry-logs container to fail to start in CI. Changes: - Extract fields into named variables before building the normalized object - Use explicit type coercion (string(), float(), int()) with ?? fallbacks - Handle all optional fields (state_reads, state_writes, cache) with get() * fix(http-ingester): check auth before parsing request body Move authentication check before body reading/parsing to prevent potential DDoS attacks via large payload decompression and parsing from unauthenticated clients. * fix(sentry-logs): update docs and add gzip compression support - Update event ID from 85 to 86 in docs (changed during rebase) - Add XATU_COMPRESSION env var support to Vector config (gzip default) * refactor(http-ingester): reuse services.eventIngester config HTTP ingester now directly uses services.eventIngester configuration instead of having its own nested eventIngester config. This eliminates config duplication and ensures both gRPC and HTTP ingesters share the same auth, outputs, and settings. * docs(server): add HTTP ingester documentation * docs: add httpIngester to example_server.yaml * chore: change httpIngester default port from 8081 to 8087 - Update default port to avoid conflicts with common services - Update all docs, examples, and configs to use new port - Update EXECUTION_BLOCK_METRICS event ID to 87 (bumped during rebase) * fix(filter): silently drop events without modules instead of erroring When an event has no module set and a filter requires specific modules, the filter should silently drop the event rather than returning an error. This allows events like EXECUTION_BLOCK_METRICS (from sentry-logs) to flow through sinks that don't explicitly filter for them, without causing HTTP 500 errors when they hit sinks with modules filters. * refactor(server): extract shared Pipeline from event ingesters Extract the shared event processing infrastructure into a Pipeline struct within the event-ingester package. Both gRPC and HTTP transports now use this Pipeline, eliminating duplicated code for: - Creating authorization - Creating handler and sinks - Starting/stopping sinks - Processing events and sending to sinks This reduces code duplication by ~140 lines and provides a single source of truth for event processing infrastructure.

2026-02-04

feat(cannon): add beacon block sync aggregate deriver Add new cannon type BEACON_API_ETH_V2_BEACON_BLOCK_SYNC_AGGREGATE that extracts sync aggregate data from beacon blocks. Includes: - New deriver for extracting sync committee bits and signature - ClickHouse migration for canonical_beacon_block_sync_aggregate table - Event ingester support for the new event type - Proto definitions for the new event type

fix proto

2026-01-30

feat(cannon): add sync committee deriver Add support for collecting sync committee validator assignments via /eth/v1/beacon/states/{state_id}/sync_committees endpoint. Key changes: - Add BeaconSyncCommitteeDeriver that fetches at period boundaries only (every EPOCHS_PER_SYNC_COMMITTEE_PERIOD epochs) to avoid redundant calls - Add BEACON_API_ETH_V1_BEACON_SYNC_COMMITTEE cannon type and event name - Add SyncCommittee/SyncCommitteeV2 proto messages for validator data - Add ClickHouse migration for canonical_beacon_sync_committee table - Uses Altair as activation fork (when sync committees were introduced)

2026-01-27

Merge master into feat/ethstats-per-node-credential-forwarding - Resolved conflicts in event_ingester.proto - Integrated BEACON_API_ETH_V1_BEACON_BLOB (84) from master - Renumbered ETHSTATS_* event types to 85-91 - Renumbered ethstats data fields to 207-213 (sequential after 206) - Regenerated proto files Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

feat(sentry): add blob sidecar fetching on block receipt (#739) * feat(migrations): add admin.cryo table to migration 049 Add the admin database and cryo table for tracking cryo extraction progress. This matches the platform repo's migration 049. * feat(sentry): add blob sidecar fetching on block receipt When enabled, proactively fetches blob sidecars when blocks are received to ensure blob data is captured even if gossip events are missed. - Add BlobSidecarConfig with enabled flag (default: false) - Add fetchAndEmitBlobSidecars method to fetch and emit blobs - Reuse existing duplicate cache to prevent re-emission - Add converter utility for BlobSidecar to BlobSidecarEvent * docs(example_sentry.yaml): remove redundant comments regarding blob sidecar configuration * refactor(sentry): remove unnecessary goroutine in OnBlock handler for blob fetching * feat(sentry): add BEACON_API_ETH_V1_BEACON_BLOB event type for PeerDAS Add new event type that stores blob metadata derived from block's blob_kzg_commitments. Unlike blob_sidecar which fetches full BlobSidecar with proofs, this stores only metadata including versioned_hash. The versioned_hash enables joining with execution_engine_get_blobs to determine which slot the EL was fetching blobs for - critical for PeerDAS/Fusaka analysis. Changes: - Add Blob message to blob.proto with versioned_hash field - Add BEACON_API_ETH_V1_BEACON_BLOB (84) event type - Add sentry event handler deriving blobs from KZG commitments - Add server event handler for ingestion - Add ClickHouse migration for beacon_blob table - Add Vector pipeline configuration for Kafka routing * refactor(sentry): remove BlobSidecar fetching, extract beacon blob to own file Remove the BlobSidecar fetching functionality that was superseded by the new BeaconBlob event type. Extract fetchAndEmitBeaconBlobs and extractKZGCommitments to their own file for better maintainability. Changes: - Remove BlobSidecarConfig from config.go - Remove fetchAndEmitBlobSidecars from sentry.go - Remove BlobSidecarToBlobSidecarEvent from ethereum/blob.go - Create beacon_blob.go with beacon blob emission logic

Merge master into feat/ethstats-per-node-credential-forwarding Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-23

Merge branch 'master' into ralph/horizon

2026-01-22

feat(proto): add returned_blob_indexes to ExecutionEngineGetBlobs (#733) Track which specific blobs were returned (non-null) in engine_getBlobs responses. This is especially useful for V3 which mandates partial responses. Uses Array(UInt8) for storage efficiency (1 byte per index) instead of duplicating hashes (66 bytes each).

2026-01-21

feat: US-018 - Create Horizon module skeleton and CLI command

feat(horizon): US-001 - Add HorizonLocation protobuf message Add HorizonType enum and HorizonLocation message to coordinator.proto for tracking HEAD and FILL slot positions in the Horizon module. Includes RPC methods GetHorizonLocation and UpsertHorizonLocation.

2026-01-20

Merge master into feat/ethstats-per-node-credential-forwarding - Resolved proto conflicts by merging both ExecutionEngine and Ethstats events - Renumbered Ethstats event enum values to avoid conflicts (84-90) - Added RPC_SNOOPER=10, ETHSTATS=11 to module enum - Regenerated proto files Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-15

feat: execution engine events (#728) * feat(clickhouse): improve table and column comments across all tables Adds a single migration (089) that systematically improves table and column comments for better documentation and query optimization: - beacon_api_eth_v1_events_* tables: Mention Sentry event-stream subscription - beacon_api non-event tables: Clarify API endpoint calls - canonical_beacon_* tables: Note finalized data and partition keys - libp2p_* tables: Describe deep instrumentation from forked CL clients - mempool_* tables: Note external data imports - mev_relay_* tables: Mention relay data API polling - node_record_* tables: Describe discv5 network crawling Key improvements: - Added partition key info to help users avoid table scans - Changed meta_client_name from "generated" to "collected the data" - Added context about what each row represents - Clarified timing units (milliseconds since slot start) * fix: remove meta_client_name comments from tables without that column Removes COMMENT COLUMN meta_client_name from: - libp2p_peer (lookup table) - mempool_dumpster_transaction (external import) - block_native_mempool_transaction (external import) * feat: Add Execution Engine tables * fix: use UInt32 for duration_ms and improve ORDER BY in execution engine tables - Change duration_ms from UInt64 to UInt32 (consistent with older tables) - Update execution_engine_new_payload ORDER BY to use block_number first * fix: partition execution_engine_new_payload by block_number Consistent with execution_transaction and the ORDER BY change. * add execution version * feat: add RPC_SNOOPER module for execution engine event source

feat: add RPC_SNOOPER module for execution engine event source

2026-01-14

feat: Add Execution Engine tables

2025-12-19

feat(ethstats): add ethstats CLI subcommand with per-node credential forwarding Add a new ethstats mode that acts as an ethstats server, receiving data from execution clients and forwarding it to configured output sinks. Key features: - WebSocket server compatible with standard ethstats protocol - Per-node credential forwarding: nodes connect with nodename:base64(user:pass) allowing multiple nodes to share credentials with unique display names - GeoIP enrichment support - Authorization system with user/group filtering - Protobuf event types for blocks, stats, pending, latency, and new payloads Also refactors auth and geoip packages to be shared across server components.

2025-12-09

chore: renaming

feat: add exec client impl + ver

feat: engine_get_blobs

2025-12-03

feat: engine_api_new_payload

2025-11-07

feat(sentry): Add new event EXECUTION_STATE_SIZE (#683) * Initial execution state size event * feat: Update event name to execution-state-size * test(execution): add comprehensive EL client version parsing tests - Add unit tests for all 5 EL implementations (Geth, Erigon, Nethermind, Besu, Reth) - Verify version parsing handles various formats (with/without 'v' prefix, different commit hash separators) - Update parseClientVersion documentation with real-world examples from production - All tests passing for current production EL clients * fix(vector): use standard event date_time parsing for execution_state_size - Remove unnecessary if exists() check - Remove fallback to now() which hides parsing errors - Use standard pattern consistent with other events - Properly propagate errors via .error field * revert(migrations): remove extraneous blank line - Remove accidental blank line added in 040_canonical_beacon_validators_split.up.sql - Restore file to previous formatting * refactor(types): align field spacing in DuplicateCache and event types for consistency * feat(db): add updated_date_time to execution_state_size table for better data management This change introduces an `updated_date_time` field in the Vector transform and ClickHouse table schema to track when records were last updated, enabling the use of `ReplicatedReplacingMergeTree` for deduplication based on this timestamp.

2025-10-20

feat(libp2p): Add rpc_custody_probe event (#674) * feat(libp2p): Add rpc_custody_probe event * custody probe fixes * update event name * refactor(event_rpc): use event timestamp instead of job start for request time calculation * fix(libp2p): Fix linting issues in custody probe event handling - Fix StartDateTime calculation for wallclock slots and epochs to use proper TimeWindow().Start() methods - Improve peer ID validation to check for nil before accessing value Co-authored-by: Sam Calder-Mason <samcm@users.noreply.github.com> * feat(proto): add JobStartTimestamp conversion to DataColumnCustodyProbe from trace event payload --------- Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com> Co-authored-by: Sam Calder-Mason <samcm@users.noreply.github.com>

2025-10-01

feat(metrics): add earliest_available_slot and custody_group_count to libp2p metrics This commit introduces two new fields to track more detailed peer RPC information: - `earliest_available_slot` in `Status` for RPC responses. - `custody_group_count` in `Metadata`. This requires updating Vector configuration, ClickHouse migrations (up/down), and the Go protobuf definitions to correctly ingest and store this new data.

Merge branch 'master' into feat/libp2p-handle-metadata-status-direction

2025-09-30

feat: replace kzg_commitments with kzg_commitments_count in data_column_sidecar Replace the large kzg_commitments array with a lightweight kzg_commitments_count field to reduce storage and bandwidth requirements. Changes: - Add migration 077 to remove kzg_commitments column and add kzg_commitments_count (UInt32) - Deprecate kzg_commitments field in EventDataColumnSidecar proto - Add kzg_commitments_count field to EventDataColumnSidecar proto - Update sentry to populate only kzg_commitments_count - Remove unused convertKZGCommitments helper method - Regenerate proto files

2025-09-29

feat(libp2p): Add direction

2025-09-24

feat: add block root field to libp2p gossipsub blob and data column sidecars - Add beacon_block_root column to ClickHouse tables for blob and data column sidecars - Update proto definitions to include block_root field in BlobSidecar and DataColumnSidecar - Update tests to handle new block_root field - Add .env file with ClickHouse version configuration

2025-08-25

feat(relay-monitor): Add persistence and backfill (#625) * feat(relaymonitor): add backfill functionality for historical slot data This commit introduces a new backfill feature that allows the relay monitor to fetch historical slot data from relays. This is useful for ensuring that all relevant data is captured, even if the monitor was not running during specific periods. The backfill functionality can be configured in the `relay_monitor.yaml` file, allowing users to specify: - Whether backfilling is enabled. - The target epoch or fork to backfill up to. - Rate limiting parameters such as requests per second, slots per request, and delay between relays. The `BackfillManager` has been added to handle the backfill process, including calculating the target slot, managing rate limiting, and iterating through historical slots to fetch data from each configured relay. * feat(config): add coordinator configuration and update backfill options Introduces configuration for a coordinator, enabling persistence and coordination with an xatu server. Also refactors backfill configuration to simplify options and improve clarity. Adds new database migrations for the `relay_monitor_location` table to support coordinator functionality. feat(proto): update coordinator proto with new types and fields This commit introduces several new types and fields to the coordinator proto definition, enhancing its capabilities for node status tracking, discovery, and coordination. Key changes include: - Added `RelayMonitorType` enum for distinguishing different relay monitoring types. - Introduced `RelayMonitorSlotMarker` to track current and backfill slots for relay monitoring. - Added `RelayMonitorLocationBidTrace` and `RelayMonitorLocationPayloadDelivered` for specific relay monitoring data. - Introduced `RelayMonitorLocation` to encapsulate various relay monitoring details, including network, client, relay names, type, and specific data. - Added `GetRelayMonitorLocationRequest`, `GetRelayMonitorLocationResponse`, `UpsertRelayMonitorLocationRequest`, and `UpsertRelayMonitorLocationResponse` for managing relay monitor locations. - Updated `ExecutionNodeStatus_Capability` and `ExecutionNodeStatus_ForkID` with more precise field definitions. - Refined existing message structures like `CannonLocation` and its associated types to include `BackfillingCheckpointMarker` and other relevant fields for improved backfilling and location tracking. - Added `GetCannonLocationRequest`, `GetCannonLocationResponse`, `UpsertCannonLocationRequest`, and `UpsertCannonLocationResponse` for managing cannon locations. - Updated proto generation information with new versions of `protoc-gen-go` and `protoc`. refactor(proto): update coordinator.pb.go with new proto definitions This commit updates the generated Go protobuf definitions for the coordinator service. The changes include: - Renaming the `port` variable to `PORT` for better semantic clarity and consistency with common Go practices. - Adding support for the `PORT` environment variable, allowing the server to be configured with a dynamic port. These changes improve the maintainability and flexibility of the server configuration. feat(proto): update coordinator proto definitions This commit updates the protobuf definitions for the coordinator service. The changes include: - Adding new message types for relay monitor locations and requests. - Expanding the `CannonLocation` enum with new types for various Ethereum beacon chain events. - Introducing the `RelayMonitorType` enum. - Updating existing message structures and field definitions. - Adjusting the service method signatures to accommodate new functionalities. refactor(proto): remove unused proto message exporters The `protoimpl.UnsafeEnabled` block containing message exporters was removed. These exporters are automatically generated by the protobuf compiler and are not needed for the functionality of the code. Removing them cleans up the generated code and reduces its size. feat(proto): add relay monitor location tracking to coordinator service feat(relaymonitor): implement backfill functionality using coordinator for location tracking feat(coordinator): add client and config for interacting with the coordinator service feat(persistence): add relay monitor location persistence layer feat(server): implement relay monitor location gRPC endpoints in the coordinator service * feat: refactor relay-monitor consistency system with shared rate limiting Major improvements to the relay-monitor consistency/backfill system: - Renamed "backfill" to "consistency" to better reflect dual functionality - Split into two independent processes: backfill (works backwards) and forward fill (catches up) - Implemented shared rate limiter per relay (no more wasted capacity) - Forward fill gets priority through shorter timeout on rate limiter - Removed burst configuration (hardcoded to 1 to prevent relay bans) - Added metrics for monitoring lag and current slot - Removed fallback logic that masked configuration errors - Support for sub-1 request/second rates (e.g., 0.5 = 1 req/2s) Breaking changes: - Configuration structure changed from "backfill" to "consistency" - Removed RateLimitBurst configuration (now hardcoded to 1) 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * fix(relay): improve error handling and logging for API requests This commit refactors the `GetProposerPayloadDelivered` and `GetValidatorRegistrations` functions to provide more robust error handling and logging. Specifically, it: - Ensures that API failures are consistently recorded by incrementing metrics before returning an error. - Adds more specific error messages to indicate the cause of failure (e.g., request execution, unexpected status code, response decoding). - Closes the response body in all error scenarios to prevent resource leaks. These changes aim to make it easier to diagnose and resolve issues related to API communication with the relay. * refactor: remove deprecated backfill_slot field from relay monitor The backfill_slot field in RelayMonitorSlotMarker was deprecated and no longer used after implementing process isolation via relay name suffixes. Both backfill and forward fill processes now use only the current_slot field with separate database records identified by ":backfill" and ":forward_fill" suffixes. This change: - Removes backfill_slot field from RelayMonitorSlotMarker proto message - Removes references to backfill_slot from both iterator implementations - Simplifies the code by removing unused compatibility fields 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: start forward fill from current wallclock slot When forward fill iterator has no existing location, it should start from the current wallclock slot instead of slot 0. This ensures forward fill begins processing from the most recent slots rather than unnecessarily starting from genesis. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * fix(relaymonitor): reduce default rate limit per relay to 0.5 and check every duration to 1s to prevent relay bans * fix: resolve linting issues for CI - Add nolint directives for nilnil errors (nil slot indicates no work) - Add nolint directives for gosec integer overflow warnings - Update deprecated golang.org/x/exp/rand to math/rand/v2 - Fix rand.Intn to rand.IntN for math/rand/v2 compatibility - Fix import formatting with goimports 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>

2025-08-21

feat(libp2p): heartbeat (#629) * feat(libp2p): heartbeat * feat(libp2p): rename heartbeat event to synthetic heartbeat Rename LIBP2P_TRACE_HEARTBEAT to LIBP2P_TRACE_SYNTHETIC_HEARTBEAT across the entire codebase to better reflect the nature of this synthetic event. Changes: - Updated proto definitions and regenerated protobuf files - Renamed trace_heartbeat.go to trace_synthetic_heartbeat.go - Updated SQL migration files and table names - Updated Docker Compose vector configurations - Updated all Go code references and type names 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * refactor(clickhouse): remove unique_key from libp2p_synthetic_heartbeat table and use a distributed key for better performance The `unique_key` column was redundant as it was generated using `seahash(.event.id)`. This change removes the `unique_key` column from the `libp2p_synthetic_heartbeat_local` table and updates the `libp2p_synthetic_heartbeat` distributed table to use a composite key based on relevant columns for sharding. This aims to improve query performance and reduce data redundancy. Additionally, the `libp2p-trace-heartbeat` service name in `docker-compose.yml` has been updated to `libp2p-trace-synthetic-heartbeat` to align with the table name change. * feat(event_catergorizer): add synthetic heartbeat event to categorizer This commit adds the `Event_LIBP2P_TRACE_SYNTHETIC_HEARTBEAT` event to the `EventCategorizer`. This event is important for monitoring the health and connectivity of the libp2p network. By categorizing this event, we can ensure that it is properly logged and analyzed, providing valuable insights into the network's performance. * refactor(event): rename HEARTBEAT to SYNTHETIC_HEARTBEAT for clarity * cook * refactor(vector): improve agent version parsing and storage for libp2p heartbeats This commit refactors the agent version parsing logic in the vector configuration and updates the ClickHouse schema to store more granular details about the remote agent. Previously, only a single `agent_version` string was stored. This change extracts and stores the agent's implementation, full version, major, minor, patch versions, and platform separately. This allows for more detailed analysis and filtering of peer data based on specific agent versions or implementations. The `log` statement in the vector transform was also removed as it was redundant. * test(event_categorizer_test.go): update expected event counts from 27 to 28 and group D minimum from 9 to 10 * test(event_categorizer_test.go): correct expected event count in assertion message from 27 to 28 test(event_categorizer_test.go): add missing synthetic heartbeat event to completeness check * ci(test.yaml): remove test annotation step and switch to verbose output - Replace JSON output with human-readable verbose test output - Comment out annotation action to simplify CI pipeline * ci(test.yaml): switch test output to JSON and re-enable annotations - Change `go test -v` to `go test -json` to produce machine-readable output. - Pipe results to `tee test.json` so the file is available for the annotation step. - Uncomment the Annotate tests step so failed tests are surfaced in the PR checks. --------- Co-authored-by: Sam Calder-Mason <sam@puritydev.io> Co-authored-by: Claude <noreply@anthropic.com>

2025-08-20

feat: remove deprecated Blockprint support from xatu-cannon (#628) Blockprint has been deprecated and is no longer supported. This commit removes all Blockprint-related code from xatu-cannon while maintaining proto backward compatibility. Changes: - Remove Blockprint deriver from xatu-cannon initialization - Remove Blockprint configuration from deriver config - Remove Blockprint event handler from xatu-server - Remove Blockprint from Vector kafka/clickhouse configurations - Remove Blockprint topic from docker-compose - Add deprecation comments to proto files (keeping definitions for compatibility) - ClickHouse tables remain unchanged (no data flow) BREAKING CHANGE: Blockprint events are no longer processed by xatu-cannon 🤖 Generated with [Claude Code](https://claude.ai/code) Co-authored-by: Claude <noreply@anthropic.com>

2025-08-07

add kzg count field

feat: add libp2p data column sidecar support - Add protobuf definitions for data column sidecar messages - Create database migration for data column sidecar table - Implement trace gossipsub data column sidecar event handler - Update vector configurations for data column sidecar processing

2025-07-31

feat: add sidecar module proto

2025-07-25

feat: update to go-ethereum v1.16.1 with ETH/69 protocol support - Update go-ethereum from v1.15.11 to v1.16.1 - Update ethcore to latest version supporting ETH/69 - Replace deprecated Status.Head with Status.LatestBlockHash - Mark total_difficulty field as deprecated in protobuf - Add testcontainers dependencies for integration tests