The zip front router mounted service reverse-proxies under /api/<prefix>; renamed
to /v1/<prefix> per convention (we never use a /api/ path prefix). Upstream
service-internal /api/v1/... paths (behind the proxy) are unchanged.
Make the explorer ONE Go binary fronted by github.com/hanzoai/zip (Fiber v3 /
fasthttp) that runs the Blockscout-rs Rust services IN-PROCESS via the existing
cgo FFI staticlib and reverse-proxies to each. Least-work: the Rust services are
not rewritten/ported — their real entrypoints run on Tokio threads inside the
process, keeping their own HTTP servers on loopback.
Front router (front.go): zip owns the public listener; routes in order
/api/<prefix>/* -> httputil.ReverseProxy -> 127.0.0.1:<svc_port> (prefix stripped)
/* -> the existing net/http explorer mux via zip.AdaptNetHTTP
Security headers + CORS become zip middleware (replaces withSecurity).
Config (services: block, ServicesConfig/resolveServices in config.go+services.go):
single source of truth for enabled services, loopback ports (base 8050,
HTTP=base+2n/gRPC=+1), URL prefixes, and per-service settings JSON; both the
proxy and the FFI launcher read it. startFFIServices now takes resolvedService
and feeds each service its server addr (+ DB url when set).
Status: sig-provider WIRED + PROVEN end-to-end — one process owns :8090 and
:8050, curl /api/sig/health -> {"status":"SERVING"} and the real REST API
/api/sig/api/v1/abi/function -> 200. visualizer + smart-contract-verifier are
stateless and ready to wire (recipe in ffi/README.md). stats +
multichain-aggregator stay DISABLED: blockscout-service-launcher's DB layer is
Postgres-only (initialize_postgres pins DatabaseBackend::Postgres) — no SQLite
without a Rust rewrite — and stats also needs a populated Blockscout indexer
Postgres. The Go side already passes database.url+migrations through, so they
enable with config alone once a Postgres exists.
Build: make single (cargo build ffi/ + go build -tags ffi) unchanged; default
go build ./... is the Go-native binary (ffi_off.go stub, no cgo). go build ./...
and go test ./... pass; make single links the sig-provider symbol and boots.
Make the explorer ONE binary that runs the Rust Blockscout-rs services
in-process via FFI — not by rewriting them in Go and not by exec'ing
subprocesses. The real Rust service entrypoints run on their own Tokio
runtime threads inside the Go binary.
- ffi/ — one C-ABI staticlib (crate-type=["staticlib"]) wrapping the
service crates by path (../../explorer-rs/<svc>). One staticlib = one
Rust std/panic runtime, no duplicate-symbol conflicts. A `service!`
macro is the single place that bridges a service: parse Settings JSON,
spawn a dedicated OS thread with a multi-thread Tokio runtime, run the
service's real entrypoint. Exports lux_explorer_start_<svc>() +
lux_explorer_start_all(). Disabled services still export their symbol
and return LUX_FFI_ERR_DISABLED so the Go side links identically.
sig-provider is wired and proven first (stateless, fastest to build);
the other four services' deps/features/service! blocks are written out
commented with confirmed entrypoint signatures for mechanical scale-out.
- ffi_on.go (//go:build ffi) — cgo preamble (-llux_explorer_ffi + the
darwin/linux system libs the Rust graph needs) + extern decls;
startFFIServices() launches the services at startup from main().
- ffi_off.go (//go:build !ffi) — no-op fallback so plain `go build ./...`
compiles WITHOUT the staticlib present.
- Makefile `make single` = cargo build --release in ffi/ then
go build -tags ffi. ffi/README.md documents the C ABI, the protoc /
protoc-gen-openapiv2 build-tool prereqs, the seeded Cargo.lock, and the
one-service-at-a-time scale-out recipe.
Verified: default `go build ./...` exits 0; ffi/ staticlib compiles with
sig-provider linked (.a 7.9MB shim -> 58MB with service); cgo -tags ffi
links it into the binary (symbols present via nm); the single binary boots
and logs `[ffi] start sig-provider -> ok (0)` with the service running
in-process. go vet clean under both build tags.
graph v1.2.6 reads ERC20 symbol/name/decimals for AMM Token entities
(was address-placeholder). supervisor.go runs graph's BackfillTokens at
startup when BACKFILL_TOKENS=1 to enrich existing placeholder rows in
place (≤3 eth_calls/token, no re-sync), before the live indexer loop.
The v1.3.1 image build reached the runner (lux-build works) but failed two
ways that the local build now proves fixed:
1. Dockerfile cloned private luxfi/{indexer,graph} over unauthenticated
https -> 'could not read Username'. Those clones were vestigial: explorer
has no replace directive, so under -mod=mod graph v1.2.3 + indexer v1.4.5
resolve from the module cache, not siblings. Drop the clones; add the
node-style BuildKit-secret git auth (ghtok) + GOPRIVATE/GONOSUMDB/GONOPROXY
before go mod download so private modules resolve.
2. GHCR push would be denied (repo-scoped GITHUB_TOKEN). Log in with the
cross-org PAT (GH_TOKEN/UNIVERSE_PAT) and stamp
org.opencontainers.image.source so the package stays linked.
Verified locally: docker buildx build --secret id=ghtok,... compiles the
unified FE+indexer+graph binary green (go mod download 74s, go build 98s,
image exported).
The classic-triple pool is serviced by fleet arcd hosts (dbc/evo/spark)
that are not reliably available — the v1.3.0 tag never produced an image and
recent builds sit queued. lux-build is the org-scoped autoscalingrunnerset
in lux-k8s (listener healthy 18d, scales 0->N on demand) that already
publishes the node image. Same one-line pool swap node/docker.yml uses.
graph v1.2.3 lands the native 0x9999 DEX indexing fix: dex/amm builtin
subgraphs, 0x9999-scoped Fill source (DEXFill log), keccak topic-hash
fixes, and re-genesis self-heal. The supervisor already wires
PoolManager(0x9999)+StartBlock into graphidx.NewWithConfig and mounts the
dex+amm subgraphs at /v1/graph/{slug}/{subgraph}/graphql; this bump makes
the engine those routes resolve against carry the fix.
Also replaces the unpushable phantom pin
indexer v1.4.5-0.20260526184203-3b72d71cc8fd (revision 3b72d71cc8fd never
existed on origin) with the real published indexer v1.4.5 tag (main HEAD
ac537780: server-side per-(token,holder) balances + log/transfer column
aliases). This unblocks the unified explorer Docker build, which resolves
graph+indexer from go.mod under -mod=mod.
Verified: go mod tidy clean; CGO build of the unified binary green;
go test ./... ok; graph dex_route_test confirms markets/fills resolve on
the dex schema from 0x9999 entities.
Replaces non-canonical scale-set / org-prefixed labels with the
existing labels every arcd host registers with. Matches evo for
amd64 and spark for arm64. No new labels added.
The Go binary is now a data-layer service only. The `/` catch-all that
served an embedded SPA shell is gone; v1.3.0 keeps just the endpoints
the FE depends on:
- /v1/* — indexer + blockscout-compat REST APIs
- /health — health probe
- /envs.js — runtime brand/chain config (window.ENV)
- /icon.svg, /logo.svg — per-host brand SVGs (overlay-friendly)
- /icon-{slug}.svg, /logo-{slug}.svg — extra named brand assets
Every other path returns 404 so the IngressRoute hands it off to the
per-brand Blockscout FE Deployment (ghcr.io/{brand-org}/explore-{env}).
Concrete deltas:
- frontend.go: drop handleSPA, writeIndex, f.index; replace with
handleNamedBrandAsset + brandAssetNames discovery
- frontend_test.go: TestFrontendNoSPA + TestFrontendBrandAssetsServed
replace the index-html overlay tests
- Dockerfile: drop Next.js frontend build stage; runtime image is just
the Go binary + brand SVGs (no embedded HTML)
- static/index.html: removed (60-byte placeholder)
The per-brand FE Deployments + IngressRoute patches that complete this
split live in the cluster (lux-mainnet + lux-testnet namespaces). Source
of the FE images: luxfi/explore via Dockerfile.branded.
Replace the default currency symbol + network ID
(8675312) defaults with Lux mainnet defaults (LUX, 96369). The
explorer binary white-labels per-tenant via runtime env, not via
-specific build defaults.
- BRAND is now a merge of SERVER_BRAND (chains.yaml-supplied) and
INFERRED_BRAND (host parser table). Server wins on name/coin/accent
when it's non-default; inferred fills in iconUrl/logoUrl when the
chain config doesn't carry per-brand SVG paths. Stops Zoo rendering
with the default Lux favicon when chains.yaml omits icon_url.
- networkFromHost now canonicalises "test"→"testnet", "dev"→"devnet"
so the dropdown label matches the server-side VITE_CURRENT_NETWORK.
The Go-side networksForHost was added in v1.2.20 but the deployed
image is still v1.2.18 (CI pool gap — lux-build AutoscalingRunnerSet
is missing from arc-system). The SPA now also parses location.host
client-side so the network switcher works when /envs.js doesn't ship
VITE_CURRENT_NETWORK / VITE_NETWORK_HOSTS.
Same shape rules as the Go side: explore.{brand}.{tld} (mainnet,
preserve tld), explorer.{brand}-test.network (testnet, .network is
canonical). Numeric and *.local hosts skip the dropdown.
This lets us ship the cross-network switcher via an EXPLORER_STATIC_DIR
overlay (ConfigMap-mounted SPA) without rebuilding the image.
handleEnvs now returns VITE_CURRENT_NETWORK + VITE_NETWORK_HOSTS so
the SPA can render a Network dropdown next to the Chain picker. When
the user picks "testnet" from explore.zoo.network the SPA redirects
to explorer.zoo-test.network (and vice-versa).
Sibling host derivation lives entirely in Go:
- parseBrandEnv extracts (brand, env, dotted, ok) from any of our
deployed host shapes — explore.{brand}.tld, explorer.{brand}-test.network,
explore-{brand}.lux.network, explore-{brand}-test.lux.network.
- networksForHost composes the sibling map. Mainnet TLD is preserved
when the user is on a brand-owned host (explore.hanzo.ai stays .ai);
testnet is always {brand}-test.network because that's the canonical
shape.
- isValidBrand rejects numeric stems so an IP host (10.0.0.1) doesn't
fall through to "explore.10.0.0.1" / "explorer.10-test.network".
SPA renders the dropdown above the chain picker; hidden when the host
yields fewer than two siblings (local dev, admin tooling).
Tests cover all four canonical surfaces (lux+zoo × mainnet+testnet),
hanzo's TLD asymmetry (.ai mainnet → .network testnet), the
explore-{slug}.lux.network prefix shape, and the unparseable-host
guards (IPs, in-cluster service names, localhost).
- host matcher now accepts explorer.* (alias of explore.*) and
{prefix}.{slug}-{env}.tld shapes — so explorer.zoo-test.network
resolves to the Zoo brand (was falling through to Lux default).
- new chainSlugForHost helper drives a default-chain promotion in
handleEnvs: when the host pins a chain, the SPA opens on that
chain instead of the config-default cchain. explore.zoo.network
now defaults to Zoo, not C-Chain.
- factored host matching into pure hostMatchesSlug predicate so
brand and slug paths share one ground truth.
- tests cover both regressions (explorer.zoo-test.network → Zoo,
explore.zoo.network → slug=zoo) plus the existing
cross-contamination guards (zoofoo must not match zoo).
luxfi/explorer + luxfi/graph + luxfi/explore now ship as ONE Deployment
per env on lux-k8s. CLAUDE.md describes the 2-container sidecar layout
(explorer Go + explore Next.js), image versions, manifests, and verified
public URLs across mainnet / testnet / devnet.
brandStruct only matched bare "{slug}" and "{slug}.tld" host shapes —
but the unified explorer ships behind IngressRoutes whose Host()
patterns are exclusively `explore-{slug}.lux.network` and
`api-explore-{slug}.lux.network` plus brand-owned roots like
`explore.hanzo.ai`, `explore.zoo.ngo`, `explore.pars.network`. With
the old matcher every per-chain host fell through to BrandDefault
("Lux Explorer"), so per-chain theming silently no-op'd in prod
(verified 2026-06-05: explore-hanzo.lux.network /envs.js returned
"VITE_BRAND":{"name":"Lux Explorer"} instead of Hanzo).
New matcher recognises the four prefix shapes the IngressRoutes
produce, both with and without an env suffix (-test / -dev):
- explore-{slug}.tld... UI host on lux.network
- api-explore-{slug}.tld... API host on lux.network
- explore-{slug}-{env}.tld... UI host for testnet / devnet variants
- api-explore-{slug}-{env}... API host for testnet / devnet variants
- explore.{slug}.tld... UI on brand-owned domain
- api-explore.{slug}.tld... API on brand-owned domain
Plus the prior bare-{slug} and {slug}-prefix shapes for backward
compat.
Test coverage: TestBrandStructHostMatching, 18 cases incl. the
explore-spcfoo cross-contamination guard ensuring partial-slug-
suffix matches don't bleed.
Two related changes that get the explorer SPA rendering real chain
data without waiting for upstream luxfi/explore to ship a Next.js
static export.
1. Runtime SPA overlay (config.go, frontend.go)
New cfg.StaticDir (also EXPLORER_STATIC_DIR env var). When set,
the frontend prefers the on-disk copy of any static asset over the
embedded FS — so a ConfigMap-mounted SPA shell replaces the
embedded 60-byte placeholder without rebuilding the binary. The
embedded FS remains the source of truth at build time and the
fallback when no overlay is configured.
handleSPA + serveBrandFile both check overlay > embedded. Tests
cover overlay-present, overlay-missing-file fallback, no-overlay,
and env-var-only configuration.
2. Substantive SPA shell (static/index.html)
Replaced the 60-byte stub (<div id="root"></div>) with a vanilla
JS SPA — ~7KB, zero dependencies, no React/Next.js. Reads
window.ENV from /envs.js, fetches /v1/indexer/{slug}/{stats,blocks,
transactions}, renders KPIs + Latest Blocks + Latest Transactions
with per-chain switching and brand color/title overrides. Polls
every 15s. Stores selected chain in URL hash + localStorage.
This is the explorer's default UI until upstream luxfi/explore
ships output: 'export' and the Dockerfile's optional pnpm-build
overlay activates.
Dockerfile: drop the leftover merge-conflict markers around the SPA
build stage, keep the explanatory comment.
Tests: 4 new in frontend_test.go covering overlay precedence + env-var
fallback. All existing tests (registry, realtime) still pass.
Pulls luxfi/indexer#9 — formatAddress + addrCounters now read
both the legacy `transactions_count` / `contract_code` and the
SQLite-backed `tx_count` / `code` column names, and coerce nil
counters to int64(0) so the Blockscout-derived SPA can call
.toLocaleString() without crashing.
Repros against rpc.dev..com:
GET /v1/indexer/evm/addresses/0x58a86aafb6cdd0989c799353c891e420fb530e0a
returned transactions_count: null + is_contract: false for a real
deployed AMM pool → now returns the actual tx count + is_contract: true.
The previous matrix did linux/amd64,linux/arm64 with arm64 via
docker/setup-qemu-action. QEMU-emulated builds of this image
(Next.js SPA + Go cgo-sqlite) ran for ~2 hours per tag — fast
enough to bottleneck every hotfix tag.
Drop arm64. Cluster runners are amd64; Mac devs already run native
arm64 under OrbStack with its own arm64 base story. If we ever
need an arm64 multi-arch index, the right path is a second matrix
entry on a native arm64 runner — not QEMU.
Two related fixes for running the explorer against a mainnet-fork
devnet:
1. Honor the per-chain `indexer.start_block` field from chains.yaml
when the indexer DB is fresh. Without this the indexer always
backfills from block 0, which on a mainnet fork is 25M+ blocks of
irrelevant pre-fork history. Now an operator can set:
chains:
- slug: evm
rpc: http://anvil:8545
indexer:
start_block: 25162000
and the indexer skips to that block on first run. Once any rows
exist in evm_blocks, start_block is ignored and indexing resumes
from MAX(number)+1 as before — backward-compatible for
fresh-genesis chains.
2. Default the bundled SPA's NETWORK_ID to 8675312 (the Liquid
devnet chain ID). The Dockerfile previously inherited
luxfi/explore's default of 8675311 — a stale leftover from before
the devnet chainId migration. Adds NETWORK_ID / NETWORK_NAME /
CURRENCY_SYMBOL as build-args so the same Dockerfile produces
correct images for devnet/testnet/mainnet.
Requires luxfi/indexer #8 (StartBlock field on evm.Config) — bumped
via `go mod edit` to the post-merge commit d5e65d4b50c1.
GCP HTTP/2 load balancers (and Traefik in some configs) return 502 to
clients when a HEAD response carries `Connection: keep-alive` plus a
streaming content-type — because they expect HEAD to be a closed-body
response, not an opened SSE stream.
Symptom: external `curl -I https://.../v1/base/realtime` → 502 even
though in-cluster `curl -I http://localhost:8090/v1/base/realtime` →
200 OK with full SSE headers. SPA's `fetch(..., {method:'HEAD'}).then(r => r.ok)`
gets false → live channel `disabled=true` → no live updates ever fire.
Fix: HEAD pre-flight returns ONLY `Content-Type: text/event-stream` +
200, without the streaming-only headers. The full SSE header set still
ships on the actual GET stream.
Applies to both the per-channel HandleSSE() and the multiplexed
HandleMultiplexedSSE() handlers.
The bundled SPA opens a single EventSource at /v1/base/realtime and
routes incoming frames via msg.event off a handler map — see
realtime_sse.go for the wire shape. Per-channel /blocks /transactions
etc. stay for external consumers; the SPA only uses this one path.
client.es.onmessage = o => {
const c = JSON.parse(o.data);
const d = this.handlers.get(c.event);
if (d) for (const m of d) m(c.data);
};
Wire:
- HandleMultiplexedSSE() attaches a wildcard sseClient (channel=`*`)
- Broadcast() now builds two SSE payloads per event:
perChannel: existing `event:<type>\ndata:<msg>\n\n` framing for
/blocks /transactions /etc.
wildcard: `data:{"event":<type>,"chain":<slug>,"data":<...>}\n\n`
for /v1/base/realtime — no `event:` line so SPA's
onmessage gets the JSON envelope and dispatches.
- sseRegistry.fanout dispatches both payloads to matching clients
based on channel ("*" → wildcard, "blocks" → perChannel)
- main.go mounts GET + HEAD /v1/base/realtime (HEAD is the SPA's
pre-flight to decide whether to disable the live channel).
Without this path the SPA's HEAD pre-flight got a 404 (the explorer
SSE-HEAD-silencer from #4) and the client set `disabled=true`, so
no live updates ever reached the home page.
dispatchIndexer's splitSlug peels off the first segment as a "slug" if
it matches the slug regex ([a-z0-9][a-z0-9-]{0,63}). When that segment
turns out NOT to be a registered chain, the previous code forwarded only
the REMAINDER to the default chain — so `/v1/indexer/main-page/blocks`
silently became `/v1/indexer/evm/blocks` server-side, a completely
different endpoint that returns a paginated envelope instead of the raw
array the SPA expects.
The SPA's home page widget does `data.slice(0, 8).map(...)` on the
result and threw "o.slice is not a function" against the envelope shape.
Fix: when the parsed slug isn't a registered chain, re-join it with
the rest before delegating so the original path is preserved under
the default chain (`/v1/indexer/main-page/blocks` → `/v1/indexer/evm/main-page/blocks`).
When ChainSupervisor.AttachRealtime is called (from main), each chain's
indexer.Subscriber.OnBroadcast is wired to push block events into the
RealtimeHub on the chain's slug. The hub then fans out to WebSocket
clients (existing path) and SSE subscribers (new in #5).
Requires luxfi/indexer v1.4.4 — pulls in the exported Subscriber()
accessor.
End-to-end chain:
evm.Indexer.indexBlock → Subscriber.BroadcastBlock → OnBroadcast →
RealtimeHub.Broadcast → ws.send + SSE fanout → SPA EventSource
Now /blocks, /transactions, /token-transfers, etc. on the explorer
host actually stream live events as blocks land instead of just
returning HEAD 200 with no payload.
* fix(frontend): 404 on HEAD for SPA-fallback paths
The bundled SPA opens EventSource (SSE) channels for live block / tx /
token streams and pre-flights each with HEAD:
fetch(url, {method: 'HEAD'}).then(r => r.ok ? openEventSource() : disable());
When the path doesn't match a real asset and falls through to index.html,
the HEAD returns 200 — so the SPA proceeds to open the EventSource. That
immediately aborts because the body is `text/html`, not
`text/event-stream`, and the browser logs:
EventSource's response has a MIME type ('text/html') that is not
'text/event-stream'. Aborting the connection.
…for every channel (blocks, internal-txs, tokens, token-transfers,
gas-tracker, stats, validators). Noisy; channel disabled anyway after
the abort.
Return 404 specifically for HEAD requests on the SPA-fallback path. Real
embedded assets still serve fine on HEAD; only the index.html fallback
gets the 404, which lets the SPA's HEAD pre-flight cleanly fail and the
channel disable itself silently. GET/POST/etc. on the same paths still
serve index.html for SPA client-side routing — no visible UX change.
* feat(realtime): add per-channel SSE endpoints for the bundled SPA
The bundled Vite SPA opens EventSource (Server-Sent Events) against
relative paths matching its channel list — `/blocks`,
`/transactions`, `/token-transfers`, `/internal-txs`, `/tokens`,
`/gas-tracker`, `/validators`, `/stats`. None of these existed on
the backend, so every channel pre-flight (`HEAD <path>`) fell
through to the SPA's static fallback, the SPA then opened the
EventSource, and the browser logged:
EventSource's response has a MIME type ("text/html") that is not
"text/event-stream". Aborting the connection.
…for each channel on every page load. PR #4 silenced this by 404-ing
the HEAD pre-flight for SPA-fallback paths. This PR goes further:
make the endpoints REAL so the SPA stays connected and receives
broadcasts from the existing RealtimeHub.
Adds:
* `realtime_sse.go` — `sseRegistry` (separate from the WebSocket
client map), `HandleSSE(channel)` factory returning a per-path
http.HandlerFunc. Each client gets a 64-deep bounded channel;
slow consumers drop messages rather than back-pressure the hub.
* `RealtimeHub.Broadcast` — now fans out to both WebSocket clients
(existing path, unchanged shape) AND SSE clients (new path).
Message payload is encoded once, wrapped in SSE framing only
when sending to the SSE registry.
* `main.go` — 8 path → channel mappings, registered on the mux with
explicit HEAD + GET so the SPA's HEAD pre-flight + EventSource
open both hit the same handler.
Special handling:
* HEAD requests return 200 + the SSE Content-Type, no body. The
SPA's `fetch(url, {method: HEAD}).then(r => r.ok)` check passes
and EventSource opens cleanly.
* `/stats` synthesizes an event every 5s from the hub's connection
count — useful liveness signal even before broadcasters are
wired up.
* Other channels stay open with 30s keep-alive comment lines
(`: ping\n\n`) and wait for hub.Broadcast() to fire. They emit
no events today (no production broadcasters), but the
infrastructure is in place — once the indexer is wired up to
push to the hub, live streaming "just works".
Verified locally:
* `go build .` → clean (34MB binary)
* `go test ./... -run 'Realtime|Hub|SSE'` → ok
* The existing WebSocket subscribe / broadcast flow is unchanged
(no breaking changes to RealtimeHub's public API or wire format).
---------
The bundled SPA opens EventSource (SSE) channels for live block / tx /
token streams and pre-flights each with HEAD:
fetch(url, {method: 'HEAD'}).then(r => r.ok ? openEventSource() : disable());
When the path doesn't match a real asset and falls through to index.html,
the HEAD returns 200 — so the SPA proceeds to open the EventSource. That
immediately aborts because the body is `text/html`, not
`text/event-stream`, and the browser logs:
EventSource's response has a MIME type ('text/html') that is not
'text/event-stream'. Aborting the connection.
…for every channel (blocks, internal-txs, tokens, token-transfers,
gas-tracker, stats, validators). Noisy; channel disabled anyway after
the abort.
Return 404 specifically for HEAD requests on the SPA-fallback path. Real
embedded assets still serve fine on HEAD; only the index.html fallback
gets the 404, which lets the SPA's HEAD pre-flight cleanly fail and the
channel disable itself silently. GET/POST/etc. on the same paths still
serve index.html for SPA client-side routing — no visible UX change.
Cross-org runs-on dispatch failure: hanzo-build-linux-amd64 scale set is
registered to github.com/hanzoai and silently rejects luxfi/* jobs.
Switch to lux-build (githubConfigUrl=github.com/luxfi, max 20).
Matches lux/graph + lux/indexer docker.yml. The unified explorer binary
bundles SPA + indexer + graph in one image, so this is the canonical
multi-arch artifact for the local stack and devnet.
zooqueen
zeekay