Transaction Event Journal
The transaction-event/v1 contract gives Base components a common way to record business-level transaction events. Each producer appends newline-delimited JSON to a dedicated journal file rather than mixing these records into ordinary application output. The usual stdout/stderr path (and its Kubernetes-to-Datadog pipeline) is reserved for logs and must not double as this journal.
A Vector agent follows those JSONL files and forwards each record to audit-archiver. Because the audit ingest endpoint is collector-facing, it reads exactly one event object per line and does not accept a wrapped JSON batch.
Postgres Retention
Section titled “Postgres Retention”audit-archiver keeps the events it receives in Postgres so operators can query them. That copy is working storage, not the durable archive. Since #5519 the store is transaction_events_v2. It is split first by retention class (hot, warm, cold) and then into one partition per UTC day, named transaction_events_v2_{class}_YYYYMMDD. Instead of deleting individual rows, a background worker drops a whole day partition once it is older than its class window. The window depends on what kind of event the row holds:
| Default window | Event types |
|---|---|
| 3 days | Proxy and builder-decision events, which dominate the journal by volume |
| 7 days | Ingress and forwarding events |
| 30 days | Failures, drops, inclusion, and legacy flashblock events |
Two placements are worth spelling out. TXPOOL_SEND_RAW_TRANSACTION_VALIDITY ages out on the same schedule as TXPOOL_SEND_RAW_TRANSACTION, so both halves of the admission path leave Postgres together rather than one outliving the other. BUILDER_EXPIRED, along with the legacy BUILDER_DEFERRED, sits with the rest of the per-attempt builder decisions on the shortest window. Builder decisions are still the bulk of the journal. Since #5623, though, a parked transaction no longer writes a fresh deferral on every flashblock, so the volume tracks real decisions more closely.
Because expiry removes whole partitions, it no longer leaves dead tuples or index bloat behind for autovacuum to clean up. A partition is only dropped one hour after it passes its window, so an insert that lands right at the edge cannot race the drop.
Ingest also checks each event’s event_time before storing it. An event that is already older than its class window is refused, since its partition would be gone anyway. An event stamped one hour or more ahead of the server clock is refused too, because no partition exists for it yet (partitions are created three UTC days ahead). Refusing the single bad record keeps it from failing the rest of the insert batch.
The v2 primary key is (event_hour, retention_class, event_id), where event_hour is event_time cut down to the UTC hour. The old key started with event_id, a random hex string, so each insert hit a random page of the whole day’s index. Once that index grew past the buffer cache, inserts slowed down. Putting the hour first keeps writes inside the current hour’s slice of the key.
The dedupe window is narrower as a result. A re-sent event_id dedupes only when its event_time falls in the same UTC hour. A copy stamped in a different hour lands as a second row. Before v2 the window was the whole UTC day. tx_hash and block_hash are now stored only as 0x plus 64 lowercase hex digits, and a CHECK constraint enforces it.
Configuration Fields
Section titled “Configuration Fields”Rust producers are expected to surface the following settings, either at the top level or behind a producer-specific prefix:
| Field | Type | Meaning |
|---|---|---|
enabled | boolean | Enables transaction event journal writes. |
file_path | string | Dedicated JSONL file path tailed by Vector. |
queue_capacity | integer | Upper bound on the in-process event queue. Under backpressure a producer discards events rather than stalling its transaction-serving path. |
max_file_bytes | integer | Size ceiling for the live JSONL segment. Once it is crossed, the writer rolls over: the current file is renamed and a fresh segment takes its place. |
max_files | integer | How many JSONL segments are kept on disk at any one time, counting the segment currently being written. |
required | boolean | When true, startup fails if the writer cannot open the file. A failure to write at runtime stays non-fatal and is still surfaced for observability. |
producer | string | One of the producer identities below. |
network | string | Network label, for example base-mainnet or base-sepolia. |
Go and proxyd builds carry the identical field names in TOML:
[transaction_events]enabled = truefile_path = "/var/log/base/transaction-events.jsonl"queue_capacity = 16384max_file_bytes = 134217728max_files = 8required = falseproducer = "base-routing/proxyd"network = "base-mainnet"Envelope
Section titled “Envelope”Every line is a single JSON object:
{ "schema_version": "transaction-event/v1", "event_id": "0x7d5c4f...", "event_time": "2026-06-02T00:00:00.000000000Z", "producer": "base-reth-node", "event_type": "TXPOOL_PENDING", "network": "base-mainnet", "tx_hash": "0x1111111111111111111111111111111111111111111111111111111111111111", "block_hash": null, "block_number": null, "payload_id": null, "request_id": null, "data": { "pool": "pending" }}These fields are mandatory:
schema_versionevent_idevent_timeproducerevent_type
In normal operation at least one join key should be set — either tx_hash, the block_hash/block_number pair, or payload_id. The request_id field is not required but helps correlate records across proxies and ingress. Producers should avoid emitting journal records for aggregate operational states that cannot be attributed to one of those join keys: broadcast lag, for instance, stays in logs and metrics because the receiver only sees a skipped count, whereas INGRESS_METERING_SEND_DROPPED fires once per dropped transaction precisely because ingress still holds the original tx_hash.
Anything producer-specific goes inside data. Never journal raw transaction bytes, calldata, full request bodies, API keys, secrets, private keys, bearer tokens, authorization headers, raw forwarding headers, or raw client IP forwarding chains.
A collector sidecar may attach deployment-specific origin metadata under data.observability_source before handing events off to audit-archiver. The archiver persists that object alongside the rest of data, but the shared contract places no schema constraints on it.
On the Rust side, the TransactionEvent::validate helper rejects a mismatched schema version, an empty event_id, and a short, exact denylist of unsafe data keys — among them raw_tx, calldata, request_body, authorization, api_key, headers, and x-forwarded-for. Vector collector pipelines are expected to catch wider case and delimiter variants — such as rawTransaction, requestBody, secret_key, and privateKey — before anything is ingested.
Local Devnet Verification
Section titled “Local Devnet Verification”Journaling is split across two devnet layers. The core devnet — just devnet up or just devnet up-single — switches on durable node journals for base-client and base-builder, which write their JSONL under .devnet/transaction-events/. The tx-observability overlay then layers the collection side on top: a Vector shipper, a local Postgres, the audit-archiver ingest path, and the proxyd producer. That overlay never touches the node journal configuration — it only consumes what the core layer already emits.
just devnet tx-observabilityjust devnet tx-observability-smokeTo exercise proxyd transaction events before that code ships in the default proxyd image, point BASE_ROUTING_CONTEXT at a local protocols/base-routing checkout:
BASE_ROUTING_CONTEXT=/path/to/base-routing just devnet tx-observabilityjust devnet tx-observability-smokeThe smoke test pushes a single transaction through proxyd, waits for Vector to deliver the JSONL records from the proxyd, txpool-tracing, and builder producers, and then confirms audit-archiver can read the stored events back out of Postgres by transaction hash.
To keep an eye on the local shipper, alert on or inspect the component_discarded_events_total metric. Two transforms account for what it counts: parse_transaction_events sheds malformed JSONL lines, while validate_transaction_events discards already-parsed records whose data keys are flagged unsafe.
Producer Values
Section titled “Producer Values”base-reth-nodebase-builderbase-routing/proxydingress-rpc(retired; the value stays defined so archived events remain readable)
Nothing emits ingress-rpc any more. The service was removed on 2026-09-21, but its producer value and event types were deliberately left in the vocabulary, because audit-archiver rows written before that date still carry them and would otherwise fail to parse. Treat it as a value you may read and must never write.
Txpool Tracing Example
Section titled “Txpool Tracing Example”When --enable-transaction-event-journal and --transaction-event-journal-path are supplied, base-reth-node txpool tracing can route its existing live LRU events into the durable journal:
{"schema_version":"transaction-event/v1","event_id":"0x4d6d...","event_time":"2026-06-02T00:00:00Z","producer":"base-reth-node","event_type":"TXPOOL_PENDING","network":"base-mainnet","tx_hash":"0x1111111111111111111111111111111111111111111111111111111111111111","block_hash":null,"block_number":null,"payload_id":null,"request_id":null,"data":{"event_source":"txpool-tracing","txpool_event":"pending","event_index":0,"node_role":"mempool","pool":"pending"}}Event Vocabulary
Section titled “Event Vocabulary”Edge/proxy:
PROXY_RECEIVED(retired)PROXY_REJECTEDPROXY_VALIDATION_ACCEPTEDPROXY_VALIDATION_REJECTEDPROXY_ROUTED_TO_BACKENDPROXY_BACKEND_SUCCESSPROXY_BACKEND_FAILUREPROXY_INGRESS_RPC_ATTEMPT(retired)PROXY_INGRESS_RPC_SUCCESS(retired)PROXY_INGRESS_RPC_FAILURE(retired)
For each decoded eth_sendRawTransaction, proxyd now writes terminal events only. If the address check turns the transaction away, it writes PROXY_REJECTED. Otherwise each completed Backend.Forward call ends in exactly one PROXY_BACKEND_SUCCESS or PROXY_BACKEND_FAILURE, with data.attempt holding the backend index. A request that fails over across backends therefore leaves one event per backend it tried, and a batch whose deadline runs out before forwarding leaves none. PROXY_BACKEND_FAILURE covers transport errors and also backends that reply with a JSON-RPC error such as nonce too low or already known; those rows add rpc_error_code and rpc_error_message_class to data. Every terminal event also carries received_at in data: the Unix-millisecond time proxyd decoded that request’s transaction. Since that timestamp now rides on the terminal event, the separate PROXY_RECEIVED was retired (#6521). The type stays in the vocabulary so older rows still decode.
Ingress/audit (retired producer; the types are retained so historical events remain readable):
INGRESS_RECEIVEDSIMULATION_STARTEDSIMULATION_SUCCEEDEDSIMULATION_FAILEDINGRESS_METERING_SEND_ATTEMPTINGRESS_METERING_SEND_SUCCESSINGRESS_METERING_SEND_FAILUREINGRESS_METERING_SEND_DROPPED
Mempool/node:
TXPOOL_PENDINGTXPOOL_QUEUEDTXPOOL_PENDING_TO_QUEUEDTXPOOL_QUEUED_TO_PENDINGTXPOOL_DROPPEDTXPOOL_REPLACEDTXPOOL_TRACKING_OVERFLOWEDTXPOOL_SEND_RAW_TRANSACTIONTXPOOL_SEND_RAW_TRANSACTION_VALIDITY
Admission caveat: TXPOOL_SEND_RAW_TRANSACTION and TXPOOL_SEND_RAW_TRANSACTION_VALIDITY mark entry at the RPC boundary. Each distinct submit path emits its own event exactly once, written after the transaction is decoded but ahead of pool insertion or sequencer forwarding. That places both earlier in the lifecycle than TXPOOL_PENDING and TXPOOL_QUEUED, which instead report which subpool the transaction landed in. Only TXPOOL_SEND_RAW_TRANSACTION_VALIDITY carries data.validity_predicates — the serialized list of balance, nonce, storage, and block_number entries. A flashblock_index predicate is refused before this event is written. Public ingress accepts balance again since #5528, which reverted the short-lived rejection from #5463. Producers further down the chain are required not to echo it, and that rule binds BUILDER_EXPIRED, BUILDER_ACCEPTED, and BUILDER_INCLUDED alike, so recover the predicates by joining on tx_hash. Treat a replacement as an admission in its own right: it arrives with a separate tx_hash, a separate predicate list, or both, and TXPOOL_REPLACED.replacement_hash is what ties the departing transaction to the one taking its place. Submissions made through base_insertValidatedTransaction are journaled as TXPOOL_VALIDATED_INSERT_ACCEPTED / TXPOOL_VALIDATED_INSERT_REJECTED instead.
Forwarding:
TXPOOL_BUILDER_CONSUMED(retired)TXPOOL_BUILDER_FORWARD_ATTEMPTTXPOOL_BUILDER_FORWARD_SUCCESS(retired)TXPOOL_BUILDER_FORWARD_FAILURE(retired)TXPOOL_BUILDER_FORWARD_DROPPEDTXPOOL_VALIDATED_INSERT_ACCEPTEDTXPOOL_VALIDATED_INSERT_REJECTED
A mempool node sends every pending transaction to each configured builder. While the transaction stays pending, it sends it again every --tx-forwarding-resend-after-ms (default 4000, four seconds). A transaction with validity predicates is the exception: it is resent to a builder only after the earlier forward to that builder failed. Each destination has its own pool reader and queue, and the mempool node journals none of the hand-off: no TXPOOL_BUILDER_CONSUMED, no TXPOOL_BUILDER_FORWARD_SUCCESS, and no longer TXPOOL_BUILDER_FORWARD_FAILURE either. When a send reaches a builder, the builder records it as TXPOOL_VALIDATED_INSERT_ACCEPTED or TXPOOL_VALIDATED_INSERT_REJECTED, with its host in the event ID, and only the active sequencer’s builder keeps those rows (see leader gating below). Every builder gets every transaction, so a per-destination failure row on the mempool side only repeated the leader’s verdict and added verdicts from standby and canary builders that never decide inclusion. On Mainnet those made up 88% of the rows. Per-builder rejection counts remain in the forwarder metrics. A send that never reaches the builder is still journaled by the mempool node as TXPOOL_BUILDER_FORWARD_DROPPED, and TXPOOL_BUILDER_FORWARD_ATTEMPT appears only on RPC retries (data.attempt >= 1). Three details stay out of the journal on purpose: when a transaction was queued for each builder, where it sat in the pool iterator, and how many times it was resent. The reader and forwarder metrics show them in aggregate.
One builder verdict is deliberately unjournaled: the capacity discard. When one of the builder’s pool stores (validity, standard, or the Base Transaction sidecar) is full and evicts a newcomer on arrival (PoolErrorKind::DiscardedOnInsert), the insert RPC still returns the error but no TXPOOL_VALIDATED_INSERT_REJECTED is written, with or without validity predicates. A full pool discards on most inserts, and the aggregate is enough to tell that it is full:
txpool.builder_rpc.txs_rejected{reason="discarded_on_insert"}counts discards from all three stores (Datadog:base.reth_txpool_builder_rpc_txs_rejected.count).txpool.validity.evictedandtxpool.validity.pool_transactionsgive the validity pool’s evictions and occupancy (Datadog:base.reth_txpool_validity_evicted.countandbase.reth_txpool_validity_pool_transactions).
Every other pool rejection reason is still journaled. So a forwarded transaction with neither insert verdict from the leader did not necessarily fail to arrive. A capacity discard leaves no verdict, and neither does an insert the builder refuses before it reaches the pool (bytes that will not decode, extension or validity-signature policy, an oversized batch).
TXPOOL_BUILDER_FORWARD_DROPPED is reserved for transaction-scoped drops where the forwarding task still has the tx_hash in hand, such as a final RPC failure after the retries are exhausted. Broadcast lag is deliberately kept out of the journal and stays visible only through logs and metrics.
Builder:
BUILDER_ACCEPTEDBUILDER_REJECTEDBUILDER_EXPIREDBUILDER_INCLUDEDBUILDER_PAYLOAD_FINALIZEDBUILDER_FLASHBLOCK_STARTED(legacy)BUILDER_FLASHBLOCK_PUBLISHED(legacy)BUILDER_FLASHBLOCK_BUILD_STOPPED(legacy)BUILDER_DEFERRED(legacy)
The three BUILDER_FLASHBLOCK_* types come from the retired Flashblocks builder. No current builder writes them; they stay in the schema so historical journals still parse. BUILDER_DEFERRED is legacy in the same way. Older builders wrote it when they parked a validity transaction, with data.defer_reason set to validity_predicate_not_satisfied or predicate_eval_budget_exhausted.
Leader gating
Section titled “Leader gating”Each sequencer runs a builder, and each mempool node forwards every transaction to every builder. Without a gate, every builder would journal its own insert verdict for the same transaction, which came to five rows per transaction on Mainnet. Only the active sequencer builds blocks, so only its journal is kept, verdicts included.
- Set
--builder.transaction-events.consensus-url(for examplehttp://localhost:9545) and the builder polls the local consensus node’sadmin_sequencerActiveevery--builder.transaction-events.leader-poll-interval-ms(default 500). It journals nothing while the answer isfalse. - The unified
base sequencerbinary runs consensus in the same process and points the URL at that node’s own admin RPC (--rpc.addr/--rpc.port, which requires--rpc.enable-admin). It needs no URL, and its gate starts closed until the firsttrue. - A standalone builder journals until its first answer. A poll that fails or times out keeps the previous answer and increments
base_builder_sequencer_leadership_poll_errors_total.base_builder_sequencer_activeshows the answer in force, and withheld events count intransaction_events_gated_events.
Leadership is read live because it moves between sequencers without a redeploy. What this means for readers: a builder’s events start when it became leader, so a transaction it accepted while on standby can have BUILDER_* events with no earlier TXPOOL_VALIDATED_INSERT_ACCEPTED from that host. A rejection is journaled only when the leader’s pool rejects it. Around a leadership transfer, for one poll interval plus request latency, both sequencers or neither may journal.
Builder decisions
Section titled “Builder decisions”BUILDER_ACCEPTED, BUILDER_REJECTED, and BUILDER_EXPIRED fire once per payload-building attempt and carry payload_id and block_number, so one transaction can collect several decision events across build attempts. Since #5623 the builder does not write BUILDER_CONSIDERED. The native builder journals only candidates gated by validity predicates. If such a candidate passes its predicates but is then skipped (block limits, resource metering, coinbase tip, nonce, or EVM validation), it gets BUILDER_REJECTED.
A candidate the builder parks now gets no event at all, whether its predicate was not satisfied or the build had already used up its time budget for predicate evaluation. Parking is the most common builder decision and almost never comes before an inclusion, so it is only counted: base_builder_validity_predicate_evaluations_total with outcome="not_satisfied" or outcome="budget_exhausted". A validity transaction with no builder decision event may have been parked, skipped, or never reached in a build, and the journal cannot tell those apart. BUILDER_EXPIRED is the terminal discard, written once a window has closed for good, as when a bundle’s validity window or a position predicate has run out.
BUILDER_ACCEPTED reports three gas figures for the transaction it ran:
| Field | Meaning |
|---|---|
data.tx_gas_limit | The declared gas limit |
data.gas_used | The gas billed, which is also what the receipt reports |
data.metered_gas_used | The gas it would have been billed without gas-limit billing: gas spent less the EIP-3529-capped refund, raised to the EIP-7623 floor (for a Base Transaction, the sender’s gas raised to the sender’s floor, plus payer authentication) |
data.payer_auth_gas_reserved | Payer-authentication gas reserved on top of the sender’s limit; null for anything other than a Base Transaction |
Before gas-limit billing activates with Everest, metered_gas_used == gas_used. After it, gas_used equals tx_gas_limit for a standard transaction and tx_gas_limit + payer_auth_gas_reserved for a Base Transaction. The metered column runs straight across the activation, so tx_gas_limit / metered_gas_used compares limits with real consumption on both sides. The builder reads the metered value from the EVM right after execution. If the EVM published none, both metered fields are null rather than estimated. None of this changes a receipt, header, state root, or RPC response.
BUILDER_INCLUDED is recorded once the builder finalizes the payload it can serve through engine_getPayload, and it sets data.inclusion_signal = "builder_finalized_payload". Nonce and validation skips are recorded by the payload loop as BUILDER_REJECTED rather than fabricating replacement relationships. BUILDER_PAYLOAD_FINALIZED is written once for every built payload (even an empty one with no user transactions) and ties the payload_id to the builder’s block hash and number; it includes data.parent_hash, data.transaction_count, data.gas_used, data.gas_limit, and data.timestamp. In historical journals, the legacy BUILDER_FLASHBLOCK_STARTED, BUILDER_FLASHBLOCK_PUBLISHED, and BUILDER_FLASHBLOCK_BUILD_STOPPED rows are scoped to a payload/flashblock and carry top-level payload_id and block_number plus data.parent_hash, data.flashblock_index, and data.target_flashblock_count. Published rows also set top-level block_hash and data.transaction_count, data.byte_size, and data.build_duration_ms, and build-stopped rows use data.reason for control-flow stops, such as payload resolution winning the race before publish.
Canonicality caveat: builder events describe local payload construction, not canonical-chain or consensus-finality state. A builder event that carries block_hash means the builder computed or published that payload shape — it is not, on its own, evidence that the block became canonical. Tie records back to canonical history through canonical-state observers such as txpool tracing by matching block_hash, block_number, and transaction hashes.
Event ID Guidance
Section titled “Event ID Guidance”Prefer deterministic event_id values whenever the source has stable inputs. Reasonable components to combine include:
producerevent_type- source timestamp bucket or source sequence
tx_hashrequest_id- backend/node identifier when applicable
- attempt index when applicable
When a source genuinely cannot produce a deterministic ID, record the reason in the producer implementation and pack enough fields into data for audit-archiver to enforce uniqueness on the database side.
proxyd Examples
Section titled “proxyd Examples”A backend turned the transaction away with a JSON-RPC error:
{ "schema_version": "transaction-event/v1", "event_id": "0x1f3f...", "event_time": "2026-06-02T00:00:00.000000000Z", "producer": "base-routing/proxyd", "event_type": "PROXY_BACKEND_FAILURE", "network": "base-mainnet", "tx_hash": "0x2222222222222222222222222222222222222222222222222222222222222222", "block_hash": null, "block_number": null, "payload_id": null, "request_id": "req-abc", "data": { "rpc_method": "eth_sendRawTransaction", "received_at": 1780358399987, "backend_group": "main", "backend": "reth-mainnet-0", "attempt": 0, "latency_ms": 13, "rpc_error_code": -32000, "rpc_error_message_class": "nonce_too_low" }}Validation rejection:
{ "schema_version": "transaction-event/v1", "event_id": "0x2a4b...", "event_time": "2026-06-02T00:00:00.000000000Z", "producer": "base-routing/proxyd", "event_type": "PROXY_VALIDATION_REJECTED", "network": "base-mainnet", "tx_hash": "0x2222222222222222222222222222222222222222222222222222222222222222", "block_hash": null, "block_number": null, "payload_id": null, "request_id": "req-abc", "data": { "rpc_method": "eth_sendRawTransaction", "validation_service": "tx-validation", "fail_open": false }}Routed to node:
{ "schema_version": "transaction-event/v1", "event_id": "0x3b5c...", "event_time": "2026-06-02T00:00:00.000000000Z", "producer": "base-routing/proxyd", "event_type": "PROXY_ROUTED_TO_BACKEND", "network": "base-mainnet", "tx_hash": "0x2222222222222222222222222222222222222222222222222222222222222222", "block_hash": null, "block_number": null, "payload_id": null, "request_id": "req-abc", "data": { "backend": "reth-mainnet-0", "attempt_index": 0 }}Mempool and Builder Examples
Section titled “Mempool and Builder Examples”These three events show a validity transaction being admitted, a different one expiring in the builder, and the first one being accepted under gas-limit billing.
The admission event is the one place the predicate list appears in full. Every expiry, accept, and inclusion that follows must be tied back to it through tx_hash:
{ "schema_version": "transaction-event/v1", "event_id": "0x4c6d...", "event_time": "2026-06-02T00:00:00.000000000Z", "producer": "base-reth-node", "event_type": "TXPOOL_SEND_RAW_TRANSACTION_VALIDITY", "network": "base-mainnet", "tx_hash": "0x3333333333333333333333333333333333333333333333333333333333333333", "block_hash": null, "block_number": null, "payload_id": null, "request_id": null, "data": { "rpc_method": "base_sendRawTransactionValidity", "validity_predicates": [ { "type": "storage", "params": { "address": "0xabababababababababababababababababababab", "slot": "0x1", "mask": "0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff", "op": "=", "value": "0x1" } } ] }}Expiry is the builder’s terminal discard, written once no later attempt can satisfy the predicate:
{ "schema_version": "transaction-event/v1", "event_id": "0x6e8f...", "event_time": "2026-06-02T00:00:00.400000000Z", "producer": "base-builder", "event_type": "BUILDER_EXPIRED", "network": "base-mainnet", "tx_hash": "0x4444444444444444444444444444444444444444444444444444444444444444", "block_hash": null, "block_number": 123, "payload_id": "0x0102030405060708", "request_id": null, "data": { "builder_mode": "native", "source_queue": "txpool_best", "parent_hash": "0x5555555555555555555555555555555555555555555555555555555555555555", "expire_reason": "validity_predicate_expired", "expire_detail": "a validity predicate can no longer be satisfied at or after the current block" }}An accept under gas-limit billing. Here gas_used is the billed figure (the declared tx_gas_limit), metered_gas_used is what the transfer really consumed, and payer_auth_gas_reserved stays null because this is not a Base Transaction:
{ "schema_version": "transaction-event/v1", "event_id": "0x7f90...", "event_time": "2026-06-02T00:00:00.600000000Z", "producer": "base-builder", "event_type": "BUILDER_ACCEPTED", "network": "base-mainnet", "tx_hash": "0x3333333333333333333333333333333333333333333333333333333333333333", "block_hash": null, "block_number": 123, "payload_id": "0x0102030405060708", "request_id": null, "data": { "builder_mode": "native", "source_queue": "txpool_best", "parent_hash": "0x5555555555555555555555555555555555555555555555555555555555555555", "tx_gas_limit": 100000, "gas_used": 100000, "metered_gas_used": 21000, "payer_auth_gas_reserved": null }}TIPS S3/Postgres Parity Checklist
Section titled “TIPS S3/Postgres Parity Checklist”The journal feeds the audit-archiver/Postgres query path that backs the TIPS UI. Before an environment flips TIPS_UI_QUERY_BACKEND=audit, the Postgres route should return the same answers the existing S3-backed route does. Keep S3 serving traffic until the samples below match against audit-archiver, then cut over.
Sample inputs. Pick a representative set and reuse it across both backends:
- A recent block hash that includes at least one non-system transaction, plus that same block addressed by number.
- A transaction hash from that block carrying a
SIMULATION_SUCCEEDEDevent. - A bundle hash or bundle id drawn from that transaction’s event data.
- A rejected transaction from the trailing 31 days, if one exists.
Route comparisons. Run each sample through both backends and check that they line up:
- On
GET /api/block/<block-hash>, the two paths should agree on block hash, number, gas limits, the ordering of transactions, and the transaction hashes themselves. - Addressing the block by number via
GET /api/block/<block-number>should land on that same canonical block. - Per sampled non-system transaction, both backends should concur on whether simulation data is present; where it is, the bundle hash/id, state block number, total gas used, total execution time, and the per-transaction gas/time summaries should all match.
GET /api/txn/<tx-hash>should hand back a matching transaction hash along with at least one bundle id/hash join key.- Events from
GET /api/bundle/<bundle-id-or-hash>should arrive in event-time order, with the accepted simulation event for the sample among them. - Where a rejected sample exists,
GET /api/rejectedshould echo its transaction hash, block number, rejection reason, timestamp, and metering summary.
Operational checks:
- On
audit-archiver,TIPS_AUDIT_POSTGRES_URLis configured, and the audit service port answers both JSON-RPC and transaction-event HTTP ingest — that same port is where Vector delivers NDJSON, at/v1/transaction-events/batch. - On the UI side,
TIPS_UI_QUERY_BACKEND=auditis set withTIPS_UI_AUDIT_RPC_URLaimed at the audit service. - Writes to S3 keep flowing across the whole comparison window.
- Nothing in the rollout drops a Kafka, S3, or existing RPC persistence path.