PLT-459: Block-indexed tx→inclusion tracker

[bdchatham]

Implements PLT-459 (M1.3) — the submit→inclusion correlation that did not exist in sei-load.

What

• New stats/inclusion_tracker.go: per block, fetch the body once (O(blocks)), match tx hashes against a bounded in-flight registry, stamp LoadTx.InclusionTime. Reaps un-included txs.
• Retires lossy per-tx receipt polling (watchTransactions/waitForReceipt/sentTxs) + the contaminated receiptLatency metric. --track-receipts now enables the tracker.

Locked design decisions (cohort-reviewed)

• Clock: InclusionTime = wall-clock at the including block's newHead arrival (single-clock with IntendedSendTime; not header.Time, not fetch-completion). PLT-462's histogram builds on this.
• No backfill: startup inits lastSeen to first head; WS gaps degrade conservatively (unmatched → expired) and are surfaced via a block_gaps counter.
• Fetch endpoint: Endpoints[0] (no new flag); O(blocks) read load documented as accepted.

Conservation

registered == included + expired + inflight_at_shutdown, registered ⊆ succeeded (register only successful sends, at send-completion after OnComplete). dropped_at_cap tracked + excluded from the inclusion denominator (succeeded/txs_accepted). Asserting + concurrent -race tests.

Verify

make lint 0 issues · go build ./... · go test -race ./... green.

🤖 Generated with Claude Code

---

📐 Design: decision brief — PLT-459 · parent design

[cursor]

PR Summary

Medium Risk
Changes core load-test observability and RPC usage (WS heads + block bodies on Endpoints[0]); inclusion counts can undercount on gaps/fetch failures by design, but send path behavior is unchanged aside from removed receipt polling.

Overview
--track-receipts now turns on a block-indexed inclusion tracker instead of per-tx receipt polling. Successful sends are registered after OnComplete; the tracker matches txs against one block fetch per head, stamps LoadTx.InclusionTime, reaps stale entries, and reports included / expired / dropped-at-cap / inflight-at-shutdown.

Workers drop watchTransactions, sentTxs, and the receipt_latency metric. NewShardedSender takes an optional shared InclusionTracker; wiring is skipped for --dry-run. New --inclusion-reap-after (default 30s) and inclusionRegistryCap (TPS × reap window vs MaxInFlight) size the registry.

Adds OTel inclusion_* / block_gaps metrics and RunSummary inclusion fields; docs and tests cover conservation and worker register ordering.

^{Reviewed by Cursor Bugbot for commit 740eef6. Bugbot is set up for automated code reviews on this repo. Configure here.}

[amir-deris]

Blockers

1. Late register can miss one-shot block match

Successful sends are registered with the inclusion tracker after OnComplete and RecordTransaction, while each block is matched exactly once when its newHead is handled. If matchBlock for the including block runs before Register inserts the hash, that tx is never matched again and later reaps as expired.

Location: sender/worker.go (register after OnComplete)

Suggested fix: register immediately after a successful send, before OnComplete:

err = w.sendTransaction(ctx, client, tx)

if err == nil {

if t, ok := w.cfg.Inclusion.Get(); ok {

t.Register(tx)

}

}

if tx.OnComplete != nil {

tx.OnComplete(err)

}

Update TestRunTxSender_RegistersSuccessfulSend accordingly. registered ⊆ succeeded still holds because registration remains gated on err == nil.

---

2. Registry cap is undersized for sustained TPS

The inclusion registry cap is set from MaxInFlight × 4, but open-loop permits are released when each send finishes while entries stay registered until a block match or reapAfter (30s). Under sustained TPS, registry size scales roughly as:

TPS × inclusion_latency

not as MaxInFlight. Example: 2k TPS × 30s reap window → ~60k entries; default cap is 40k (10_000 × 4). Healthy txs can hit dropped_at_cap and never get matched — a silent inclusion undercount.

Location: main.go (MaxInFlight * maxInflightMultiple)

Suggested fix (pick one):

• Size cap from TPS × inclusionReapAfter (with a floor)
• Add --inclusion-max-inflight (default derived)
• Document that --track-receipts requires tuning max-in-flight for high-TPS runs and increase the multiplier substantially

At minimum, log a warning when dropped_at_cap > 0 at shutdown.

---

Non-blockers

Issue | Severity | Notes -- | -- | -- inclusion_latency in closed-loop | Nit | Histogram records arrival - IntendedSendTime, but in closed-loop IntendedSendTime is enqueue time, not schedule time. Fine if PLT-462 is open-loop-only; otherwise gate on RunSummary.ArrivalModel or use AttemptedSendTime. reapAfter hardcoded at 30s | Nit | Congested chains with >30s inclusion will inflate expired. Consider exposing as a flag or tying to expected block time × N. README stale | Nit | Still says --track-receipts tracks "transaction receipts"; behavior is now block-indexed inclusion. Fetch failure = permanent miss | Accepted | block_fetch_errors surfaces it; conservative undercount is documented. Reasonable tradeoff vs retry storm on a struggling SUT.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

There are 3 total unresolved issues (including 2 from previous reviews).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit b68dbf6. Configure here.}