feat(infra): local Blockscout explorer for the run anvil (#31) - #64
Merged
Conversation
Stock Blockscout pointed at the sim anvil as a thin config set in
infra/blockscout/ - official images pinned by tag, no source vendored
or patched. Follows the official docker-compose/anvil.yml layout
trimmed to db / redis / backend / frontend / nginx proxy (stats,
visualizer, sig-provider, user-ops-indexer and the NFT media handler
are spectator polish, not debugging, and are dropped).
- npm run explorer / explorer:down / explorer:reset / explorer:tag,
driven by explorer.sh; all knobs (RPC port, chain id, explorer port,
fork FIRST_BLOCK, image tags) live in explorer.env
- Chain-reset lifecycle: explorer:reset wipes the indexer postgres
volume and reindexes - a resetFork / snapshot-revert rewind is
something no indexer can follow, so the wipe is the supported path
- Arbitrum-fork caveat: ETHEREUM_JSONRPC_VARIANT=anvil fetches
receipts per transaction, never eth_getBlockReceipts (known-broken
on anvil Arbitrum forks here); archive balance fetching is disabled
for the ~1,050-block historical state depth, and FIRST_BLOCK is
mandatory in fork mode
- Agent wallet naming: explorer:tag reads agents[].{id,address} from a
run's summary.json and inserts Blockscout address tags (plus
env:deployer for anvil account 0) - config-level, wiped by reset
- Ads disabled (NEXT_PUBLIC_AD_*_PROVIDER=none): pointless third-party
egress on a local explorer
Verified end-to-end against a live anvil: indexing, frontend
rendering (browser), tag badges on address pages, and the reset flow.
Fork mode (42161) is configured but not yet exercised against a real
fork.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #31.
What
Stock Blockscout pointed at whichever sim anvil is running, as a thin config set in
infra/blockscout/— official images pinned by tag (blockscout:9.0.2/frontend:v2.3.5, ground-truthed against ghcr), no Blockscout source vendored or patched. The layout follows the officialdocker-compose/anvil.ymltrimmed to db (postgres 17) / redis / backend / frontend / nginx proxy; stats, visualizer, sig-provider, user-ops-indexer and the NFT media handler are spectator polish rather than debugging value and are dropped.All knobs (RPC port, chain id, explorer port, fork
FIRST_BLOCK, image tags) live ininfra/blockscout/explorer.env; defaults match local-deploy mode.explorer.shcross-checks the configured chain id against what the anvil actually reports and refuses to start on a mismatch.The three points from the issue
explorer:resetdrops the postgres volume and reindexes from scratch. A resetFork / snapshot-revert rewind is something no indexer can follow, so the wipe is the supported lifecycle, not a workaround. Reindexing a run-sized chain takes well under a minute.ETHEREUM_JSONRPC_VARIANT=anvilfetches receipts per transaction (eth_getTransactionReceipt), nevereth_getBlockReceipts(known-broken on anvil Arbitrum forks in this project). Archive balance fetching is disabled for the ~1,050-block historical state depth, andFIRST_BLOCKis mandatory in fork mode (without it the indexer walks all of Arbitrum history backwards from the head).explorer:tagreadsagents[].{id,address}from a run'ssummary.jsonand inserts Blockscout address tags (address_tags/address_to_tags; config-level, no Blockscout change), plusenv:deployerfor anvil account 0 so environment txs don't read as a participant's. Tags live in the indexer DB and are wiped byreset.Also disabled the stock frontend's third-party ads (
NEXT_PUBLIC_AD_*_PROVIDER=none) — pointless egress on a local explorer. The one remaining egress is contract verification through Blockscout's hosted eth-bytecode-db (names canonical bytecode like Uniswap V3 / Aave without a local verifier);MICROSERVICE_SC_VERIFIER_ENABLED=falseturns it off for fully offline use.Verified
End-to-end against a live anvil (chain 31337): compose up and indexing, frontend rendering checked in a real browser (homepage, tx list, address page), tag badges visible on address pages via API v2
public_tags, and the reset flow (DB wiped, reindexed to head, tags gone). The stale-mix failure mode the reset exists for was also reproduced and cleared byexplorer:reset.Not yet exercised live: fork mode (42161) against a real Arbitrum fork — the config for it is in place per the caveats above and documented in
infra/blockscout/README.md.🤖 Generated with Claude Code