feat(shadow-explorer): internal Shadow Explorer for evaluating release health - #80
Open
wbj-cb wants to merge 5 commits into
Open
feat(shadow-explorer): internal Shadow Explorer for evaluating release health#80wbj-cb wants to merge 5 commits into
wbj-cb wants to merge 5 commits into
Conversation
Internal-only explorer surface listing reorged-out shadow candidate blocks paired with the canonical block that replaced them, with gas and transaction deltas. Chain-aware API route proxies the shadow-metrics /shadow-blocks endpoint; offset-paginated to match upstream. Co-authored-by: OpenCode <opencode-noreply@coinbase.com>
…nal section
Move the shadow-blocks surface out of TIPS into a standalone, internal-only
Shadow Explorer section modeled for 1:N shadow chains per network:
- SHADOW_<NET>_CHAINS server-side registry (chain URLs never sent to client)
+ /api/shadow-explorer/{chains,shadow-blocks} route handlers and guard.
- Path routing /shadow-explorer/<network>/<chain>/shadow-blocks with network
+ shadow-chain selectors; top-level nav entry.
- deploy.config surface (internal-only) with middleware/llms/sitemap exclusion
and the CI public-build-excludes-internal check extended.
- Revert the TIPS ExplorerNav/config/client/types shadow additions.
- Guard listShadowBlocks against a missing upstream totalCount.
Co-authored-by: OpenCode <opencode-noreply@coinbase.com>
Make shadow block rows clickable and add a server-rendered block detail page
(/shadow-explorer/<network>/<chain>/block/<id>) that proxies the shadow-metrics
/blocks/{id} endpoint: overview + per-tx table.
Keep canonical block inspection in TIPS to avoid double duty: the Canonical
cell and the detail's canonical-replacement link point at /tips/block/<hash>,
and the block page redirects any non-reorged (canonical) hit to TIPS so
Shadow Explorer renders only reorged-out shadow candidates.
Co-authored-by: OpenCode <opencode-noreply@coinbase.com>
…reakdown in drilldown
Replace the per-metric columns (gas, gas delta, txns, fee inversions) with a
single server-computed Health X/N verdict per row; the banner now counts blocks
that failed one or more checks. The block drilldown fetches the single-block
summary (GET /shadow-blocks/{id}) and renders each check pass/fail with its
detail.
Co-authored-by: OpenCode <opencode-noreply@coinbase.com>
Validate the chain server-side (resolveShadowChainUrl) and notFound() when it is not configured, matching the overview and block-detail pages, instead of rendering chrome and a generic client fetch error. Co-authored-by: OpenCode <opencode-noreply@coinbase.com>
Collaborator
✅ Heimdall Review Status
|
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
jowparks
approved these changes
Aug 20, 2026
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
3 participants
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.
Summary
Adds Shadow Explorer as an internal-only section (same pattern as TIPS and Benchmark) for evaluating the health of a release. A release-candidate "canary" builder produces shadow candidate blocks that get reorged out; this surface pairs each with the canonical block that replaced it and shows a per-block release-health verdict. It consumes the shadow-metrics HTTP API (see the companion base/base PR).
Internal-only
Like TIPS and Benchmark, this ships to the internal target only. It's declared as an internal surface in
deploy.config.mjs, so it's unreachable in the public build: middleware 404s the route subtree, the API routes 404 via the section guard, the layout has anotFound()backstop, it's dropped from the sitemap/llms index, and thepublic-build-excludes-internalCI job is extended to assert its absence.What's added
/shadow-explorersection addressed by network × shadow chain in the path:/shadow-explorer/<network>/<chain>/shadow-blocks(list) and/shadow-explorer/<network>/<chain>/block/<hash>(drilldown), with an overview and network/chain selectors.SHADOW_<NET>_CHAINSJSON env (chain URLs never reach the client), surfaced viaGET /api/shadow-explorer/chains; the list is proxied through/api/shadow-explorer/shadow-blocksand the drilldown fetches server-side./tips/block/...), so this section stays shadow-only and doesn't duplicate the canonical explorer.Notes for reviewers
ExplorerNav; the net diff leaves TIPS unchanged.SHADOW_<NET>_CHAINSurl; the internal image is shipped via protocols/ui.Testing
vitestcovers query parsing, pagination math, and the missing-totalCountguard;tscand lint are clean.