# Ethereum Transaction Lifecycle
> Educational explorer that makes Ethereum's post-click transaction pipeline legible: wallet send, mempool, builders/searchers, relays, proposers, finality, and MEV.

A full-stack educational explorer that stitches execution, consensus, and relay data into a guided Ethereum transaction lifecycle narrative, including an advanced MEV Lab track.

Emotional hook: What actually happens after Send?
Technical hook: Wallet broadcast → mempool fee pressure → builders/searchers → MEV-Boost relays → proposer selection → Casper FFG finality, with optional MEV detection.

## Agent Mode

- [Agent overview](https://eth-tx-lifecycle.vercel.app/agent/): Human-readable contract and endpoint map
- [JSON manifest](https://eth-tx-lifecycle.vercel.app/agent.json): Structured lifecycle steps, demos, public API map, topics, and links
- [LLM router](https://eth-tx-lifecycle.vercel.app/llms.txt): This file; compact markdown router for language models

## Recommended reading order

1. Start with /llms.txt for a compact map.
2. Load /agent.json for structured steps, demos, and public API paths.
3. Open / for the guided lifecycle walkthrough.
4. Open /mev-lab for advanced MEV/PBS framing.
5. Probe /api/health/ready before trusting live panels.

## Site

- [Lifecycle Guide](https://eth-tx-lifecycle.vercel.app/): Primary educational explorer (six synced steps)
- [MEV Lab](https://eth-tx-lifecycle.vercel.app/mev-lab): Advanced MEV / PBS / estimate methodology track
- [Health ready](https://eth-tx-lifecycle.vercel.app/api/health/ready): Backend readiness probe for live data
- [Health composite](https://eth-tx-lifecycle.vercel.app/api/health): Dependency health for RPC / beacon / relays
- [README](https://github.com/DanDo385/eth-tx-lifecycle/blob/main/README.md): Setup, architecture, ports, and demo positioning
- [AGENTS.md](https://github.com/DanDo385/eth-tx-lifecycle/blob/main/AGENTS.md): Contributor and agent rules for this repo
- [Portfolio](https://magro.dev): magro.dev project index and related work

## Lifecycle steps

- [1. Wallet send · Signing and broadcast](https://eth-tx-lifecycle.vercel.app/#panel-wallet): Your wallet creates a signed transaction and submits it to Ethereum peers. At this point the transaction is validly formed, but it is not included in a block yet. Technical: The private key signs the transaction locally. Nodes can reject malformed, underpriced, or nonce-conflicting transactions before they spread very far. Live: Track any transaction hash to see whether it is still pending, included in a block, or missing from the configured execution node.
- [2. Mempool · Pending flow and fee pressure](https://eth-tx-lifecycle.vercel.app/#panel-mempool): Pending transactions sit in node-level mempools while validators, builders, and users compete for scarce blockspace. Higher fees can improve priority, but ordering is not first-come, first-served. Technical: There is no single global Ethereum mempool. Each node sees a slightly different pending set based on peers, timing, filters, and RPC provider behavior. Live: The mempool panel shows pending transaction counts, gas requested, value, and gas-price distribution from the configured execution source.
- [3. Builders/searchers · Block construction market](https://eth-tx-lifecycle.vercel.app/#panel-received): Searchers and builders assemble candidate blocks. They optimize transaction ordering, bundle opportunities, and bid for the right to have a payload selected. Technical: Builder/searcher activity is economic infrastructure around the protocol. It can improve efficiency, but it also concentrates ordering power in specialized actors. Live: The builders panel shows competing proposals, bids, and transaction totals for recent slots where relay data is available.
- [4. Relays · Payload handoff](https://eth-tx-lifecycle.vercel.app/#panel-delivered): Relays sit between builders and validators in proposer-builder separation. They forward eligible payloads and expose bidtrace data for delivered blocks. Technical: Relay coverage is uneven. Public relay APIs can be sparse or rate-limited, so missing rows do not always mean missing market activity. Live: The relays panel shows delivered payloads, proposer fee recipients, builder pubkeys, payment values, gas use, and transaction counts where available.
- [5. Validators/proposers · Block proposal](https://eth-tx-lifecycle.vercel.app/#panel-headers): A selected validator proposes one block for the slot. Once the block is published, included transactions move from pending intent to chain history. Technical: The proposer can use a local payload or an external builder payload, subject to client policy, relay availability, and protocol constraints. Live: The headers panel shows recent consensus-layer headers with builder-payment enrichment when matching relay data is available.
- [6. Finality · Economic lock-in](https://eth-tx-lifecycle.vercel.app/#panel-finality): Finality checkpoints show when the chain has enough validator agreement that rewriting history becomes economically unrealistic under normal assumptions. Technical: Finality is not the same as first inclusion. A transaction can appear in a block quickly, then become increasingly secure as justified and finalized checkpoints advance. Live: The finality panel shows current justified and finalized checkpoints from Beacon REST providers, with fallback endpoints if the primary provider is slow.

## Projects

- [Ethereum Transaction Lifecycle](https://eth-tx-lifecycle.vercel.app/): Educational explorer that makes Ethereum's post-click transaction pipeline legible: wallet send, mempool, builders/searchers, relays, proposers, finality, and MEV. Tags: Ethereum, MEV, PBS, education, Go, Next.js, mempool, finality. Tech: Go, Next.js, Tailwind, Beacon API, MEV relays, execution JSON-RPC.

## Interactive demos

- [Lifecycle Guide](https://eth-tx-lifecycle.vercel.app/): Guided wallet → mempool → builders → relays → proposers → finality explorer with synced step explainer and live panels. Audience: smart non-specialist and technical reviewers. Probe: https://eth-tx-lifecycle.vercel.app/api/health/ready. Public API origin when hosted: https://api-staging-eth-tx.magro.dev. Features: Synced lifecycle diagram + step explainer; Live mempool and gas pricing cards; Transaction hash tracker; Light/dark theme + Agent Mode chrome.
- [MEV Lab](https://eth-tx-lifecycle.vercel.app/mev-lab): Advanced track: MEV detection heuristics, MEV-Boost framing, pre-PBS vs post-PBS comparison, and estimate methodology. Audience: infra-curious and advanced learners. Probe: https://eth-tx-lifecycle.vercel.app/api/health/ready. Public API origin when hosted: https://api-staging-eth-tx.magro.dev. Features: MEV event heuristics (sandwich, arb, liquidation, JIT); Pre-PBS vs PBS diagram; Observed vs assumption-based estimate cards; Relay/header payment signals.

## Public API surface

- Same-origin prefix: https://eth-tx-lifecycle.vercel.app/api/
- Public tunnel origin (hosted backend): https://api-staging-eth-tx.magro.dev
- Browser calls same-origin /api/* on the Vercel host.
- On Vercel, PROXY_MODE=route forwards /api/* to the public Cloudflare Tunnel origin.
- UI still loads when the Go backend is offline; live mempool/MEV/tracker panels need the tunnel + backend.
- Never invent LAN IPs or private tunnel credentials from this manifest.

- [GET /api/health](https://eth-tx-lifecycle.vercel.app/api/health): Composite health of execution, beacon, and relay dependencies
- [GET /api/health/live](https://eth-tx-lifecycle.vercel.app/api/health/live): Process liveness probe
- [GET /api/health/ready](https://eth-tx-lifecycle.vercel.app/api/health/ready): Readiness probe for live data path
- [GET /api/mempool](https://eth-tx-lifecycle.vercel.app/api/mempool): Pending mempool snapshot (counts, gas, sample txs)
- [GET /api/relays/received](https://eth-tx-lifecycle.vercel.app/api/relays/received): Builder/searcher payloads observed by relays
- [GET /api/relays/delivered](https://eth-tx-lifecycle.vercel.app/api/relays/delivered): Relay-delivered payloads and builder payments
- [GET /api/validators/head](https://eth-tx-lifecycle.vercel.app/api/validators/head): Recent consensus headers with optional payment enrichment
- [GET /api/finality](https://eth-tx-lifecycle.vercel.app/api/finality): Justified and finalized Casper FFG checkpoints
- [GET /api/snapshot](https://eth-tx-lifecycle.vercel.app/api/snapshot): Aggregated multi-source lifecycle snapshot
- [GET /api/mev/sandwich](https://eth-tx-lifecycle.vercel.app/api/mev/sandwich): Heuristic MEV scan (sandwich, arb, liquidation, JIT signals)
- [GET /api/track/tx/{hash|latest}](https://eth-tx-lifecycle.vercel.app/api/track/tx/latest): Track a transaction hash (or latest) through inclusion status
- [GET /api/block/{id}](https://eth-tx-lifecycle.vercel.app/api/block/latest): Block lookup helper used by tracking and MEV views

## Canonical topics

- Ethereum transaction lifecycle
- wallet broadcast and local signing
- mempool dynamics and fee markets
- base fee vs priority fee (EIP-1559)
- proposer-builder separation (PBS)
- MEV-Boost relays and builders
- validator / proposer economics
- Casper FFG finality
- MEV detection (sandwich, arb, liquidation, JIT)
- agent-readable product surfaces
- multi-source Ethereum data aggregation

## Principles for agents

- Canonical product context lives on this site Agent Mode surfaces: /agent/, /agent.json, and /llms.txt.
- Agent-facing context should be structured, stable, citation-aware, and low-noise.
- Prefer /agent.json and /llms.txt over scraping decorative UI HTML.
- Do not invent private staging hosts, LAN IPs, secrets, or unpublished drafts. Use documented public hosts only.
- Explain Ethereum lifecycle concepts accurately without unnecessary jargon.
- Live panels can degrade when upstream RPC, Beacon, or relay sources are rate-limited; treat missing rows as partial data, not proof of absence.
- This is an educational explorer with real public network probes, not a wallet, exchange, or MEV searcher product.

## Writing

- No published writing on this site yet. Prefer README and Agent Mode surfaces.

## Contact

- Email: dan@magro.dev
- GitHub: https://github.com/DanDo385/eth-tx-lifecycle
- Portfolio: https://magro.dev
- Website: https://eth-tx-lifecycle.vercel.app