The Lux primary network is a family of VM-specialized chains (C=EVM, X=UTXO,
D=DEX, P=platform, + A/B/Q/T/Z/G/K/O/R/I/M), mirrored from node/node/vms.go.
- configs/app/primaryChains.ts: single source of truth (PRIMARY_VMS, getPrimaryVm,
per-VM `view`, hasBespokeView, chainsAwaitingBespokeView). Decomplects the two
lists that duplicated this — ChainsPage + ChainDetailPage now consume it
(ChainDetailPage drops ~110 lines of copy).
- D-Chain (DexVM) renders the DEX order-book UI (ui/dex/DexPage) via view:'dex',
not a generic block list. C-Chain=EVM core, P-Chain=platform/validators,
X-Chain + the custom VMs render the generic detail fallback (info + indexer DAG
stats + validators) — graceful, never blank. chainsAwaitingBespokeView() FLAGS
the backlog: X-Chain (UTXO) + the 11 custom VMs still need a bespoke view.
- These VMs are Lux-primary, so the primary-VM surfaces (Chains/DEX/Bridge/AI
Compute nav + /chains, /chains/[slug], /dex pages) gate on
isPrimaryNetworkExplorer(). ui/shared/PrimaryNetworkGuard backstops direct-URL
access so the VMs never leak onto a brand explorer (Hanzo/Zoo/Pars).
- Tests: configs/app/primaryChains.spec.ts (26 cases) — registry, per-VM view,
bespoke-view flag, and the lux-only visibility keystone. 38/38 green with the
existing chainRegistry.spec.ts.
12 cases over simulated request hosts: lux primary lists every L1 incl Osage;
hanzo/zoo/pars/osage are registered L2s, never the primary explorer (no
lux-primary / cross-L1 leak), switcher own-only; pars chainId 7070; keystone —
unregistered white-label hosts are never the primary explorer.
- isPrimaryNetworkExplorer(): require !isWhiteLabelMode() so unregistered
white-label hosts (explore.zoo.network, explore.pars.network) stop rendering
the Lux primary-network panels + cross-L1 list (NetworkOverview). Decomplects
'is this the primary explorer' from 'is the current chain EVM'.
- register explore.zoo.network/.ngo + explore.pars.network as their own L2
hostnames -> own-scoped chain/network switcher, brand parity with hanzo.
- add Osage L1 (mainnet 1872 / testnet 1871 / devnet 1873) + OSAGE_BRANDING so
the universal Lux explorer lists it.
- Pars chainId -> deployed truth (env + backend chains.yaml): mainnet
494949->7070, devnet 494951->7072.
The FE connected realtime via Phoenix Channels (wss .../socket/v2), but the
Go backend serves no Phoenix endpoint — its realtime is SSE at
/v1/base/realtime (envelope {event,chain,data}). Result: repeating ws 404 ->
'Live updates temporarily delayed'.
lib/socket/sse.ts reimplements the slice of the Phoenix Socket/Channel API the
27 realtime consumers use, backed by one EventSource, behind the existing
SocketProvider/useSocketChannel/useSocketMessage seam — no consumer changes.
Envelope routes via an optional topic field or a hub-channel translation table
(blocks -> blocks:new_block/new_block today). CT harness becomes a tiny SSE
server with the same signatures. 12 vitest cases cover it.
Frontend-only; chain/indexer untouched. Data freshness remains gated on the
separate C-Chain-rollback/indexer-reorg owner items.
The /validators view fetched real validators (5, 2.5e18 weight) but rendered
white-on-white in light mode — data present in DOM, invisible to users. Set
text-[var(--color-text-primary)] on each of the three lux validator component
roots so all text inherits the theme-flipping color token. Also replace the
hardcoded "LUX" stake unit with config.chain.currency.symbol (AI on Hanzo),
matching NetworkStats. No decimals change (6dp is the codebase convention,
consistent with P-chain getMinStake).
When no stats microservice is configured (config.features.stats.isEnabled
false), don't fire the stats:lines request that can only fail — the Stats page
already renders the live Network Overview + an honest 'being indexed' note.
Avoids a wasted erroring query on every Stats page load.
Investor-grade data, no fabricated placeholders:
- pages/api/pchain.ts: derive node origin via new URL().origin instead of a
regex that only stripped /ext/bc/C/rpc. Non-C-chain brands (hanzo:
/ext/bc/hanzo/rpc) built a wrong URL -> HTML 404 -> JSON parse crash, so
Validators/Total Stake/Connected/Uptime all showed 0/-. Now the P-chain
proxy resolves correctly and the real validator set + stake render. Parse
upstream defensively with a clear error instead of an opaque message.
- lib/api/dchain/useDexData.ts: delete all hardcoded DEMO_* markets/orders/
trades/pools/overview. Return only real D-Chain (DexVM) data or honest-empty.
- ui/dex/DexPage.tsx: honest empty/error states per tab (no fake rows).
- stubs/stats.ts: neutralize STATS_COUNTER (title empty, value 0) so the
'Placeholder Counter 9.074M' stub can never surface as real data.
- ui/pages/Stats.tsx: gate indexer-backed counters/charts on
config.features.stats.isEnabled; always show the live chain-sourced Network
Overview, with an honest 'being indexed' note when no stats microservice.
- ui/snippets/navigation/horizontal/NavLinkGroup.tsx: popover Content defaulted
to overflow-hidden + tight py, clipping the last nav item (Verified
Contracts). Override to overflow-visible with padding; bottom-start placement.
The header logo is resolved by request Host via chainRegistry getCurrentChain()
-> branding.logoContent (real @hanzo blocky-H for hanzo.network; no hardcoded
triangle). Documents the 3 render spots, the L1/L2/L3 vm gating, the on-cluster
kaniko fan-out build (no GitHub builders), and the lux-mainnet explore-fe deploy
+ universe declared state.
The Tooltip/Popover (@luxfi/ui → @hanzogui/tooltip → @hanzogui/[email protected],
hard-pinned) crashed with 'Cannot read properties of undefined (reading
setReference)' (×189, every row) under React 19 → Next error boundary 500 once
real indexer data renders. Force the fixed 3.0.6 patch via pnpm override.
- Add explore.hanzo.network / explore.hanzo.ai (+ test/dev) to the Hanzo
chainRegistry hostnames so isWhiteLabelMode()==false on those hosts →
HANZO_BRANDING (real geometric-H logo) resolves and the network/chain
selectors enable (the dropdown was empty + showed the generic triangle).
- Hanzo testnet chainId 36964 → 36962 (LP-018; was duplicated with devnet).
- TopBar is desktop-only (hidden lg:block); HeaderMobile already block lg:hidden
→ exactly one header per breakpoint (was a double header < lg).
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.
After shipping the first createGui-only patch (7784eb5), the runtime error
changed from "Err0" → "Missing theme." The root cause:
useThemeState in @hanzogui/web throws if ThemeStateContext.Provider
isn't above the component (parentId === ""). Calling createGui populates
the global config, but the tree must also be wrapped in <GuiProvider>
which materialises the ThemeProvider + GuiRoot + ComponentContext chain.
Three deltas in this commit:
1. createGui now receives explicit light/dark themes and color/space/
size/radius/zIndex tokens. Empty {} no longer satisfies getThemes
Deduped + downstream theme spreads. The tokens are minimal but
non-empty; @luxfi/ui uses Tailwind for styling, so we only need
hanzogui's internals to accept the config.
2. Top of render tree now wraps everything in <GuiProvider config>.
GuiProvider renders ComponentContext → ThemeProvider → GuiRoot
(isRootRoot=true), giving useThemeState the parent context it
requires.
3. createGui call moved out of the typeof-window block — server and
client both need it (SSR also instantiates @luxfi/ui frames at
module load, even though component render is gated by hydration).
@luxfi/ui components (Badge, Button, Tooltip, etc.) call @hanzogui's
getConfig() at module init and throw "Err0" when no config exists.
The previous commit removed the createGui call to avoid an Object.keys
crash on undefined themes, but that broke component loading instead.
createGui crashes when configIn.themes is undefined (Object.keys(undefined)
in getThemesDeduped). Passing themes: {} routes through scanAllSheets
which returns safely. tokens: {} matches the noTokens guard at line 27.
Net effect: createGui completes, globalThis.__guiConfig is populated,
and downstream @hanzogui/* components find a non-null config.
The evo native runner has filesystem corruption — last 3 runs failed
at actions/checkout step ("Can't find action.yml under
/home/z/.arcd/runner/_work/_actions/actions/checkout/v4").
lux-build-linux-amd64 ARC pool on lux-k8s is healthy (listener idle,
0 runners, max 10). Per LLM.md cross-org rule, luxfi/* workflows must
target lux-build pool — never hanzo-build.
@luxfi/ui/provider's AppProvider invokes @hanzogui's createGui at
module-load time. createGui's getThemesDeduped(themesIn) crashes with
"Cannot convert undefined or null to object" when configIn.themes is
undefined — which is the case in our provider (settings-only config).
The crash blocks client hydration on all explore surfaces (lux/zoo/
hanzo/pars × mainnet/testnet). Components from @luxfi/ui are pure
tailwind/clsx; they don't depend on @hanzogui themes. We only need
QueryClientProvider — drop AppProvider and wire it directly.
Verified: chunk _app-4e3a5315a203fbdf.js line 5712 col 1285 maps to
@hanzogui/web's createGui → getThemesDeduped → Object.keys(themes).
The branded build now fans out into 8 (4 brands × mainnet+testnet)
production images:
ghcr.io/luxfi/explore-{mainnet,testnet}:v1.0.0
ghcr.io/zooai/explore-{mainnet,testnet}:v1.0.0
ghcr.io/hanzoai/explore-{mainnet,testnet}:v1.0.0
ghcr.io/parsdao/explore-{mainnet,testnet}:v1.0.0
Each image is a thin ENV overlay of ghcr.io/luxfi/explore (the Next.js
runtime) — brand identity is baked at build time via NEXT_PUBLIC_*
build-args. The brand's GHCR namespace owns the image per the workspace
container-registry rules (no cross-org mixing).
deploy/scripts/branded_build.sh is the source of truth for tuple -> env
mapping; the actual image fan-out is performed via crane mutate -e which
produces an instant ENV-only layer (no Kaniko, no tar of build context —
same hash blob mounts across namespaces).
The corresponding K8s manifests (per-brand Deployment + Service per
namespace, IngressRoute patches routing catch-all to FE) live in the
cluster directly.
ChainBranding gains a productName field (default "Explorer"). New helper
applyBrandEnvOverrides(b) layers NEXT_PUBLIC_BRAND_* env vars over the
bundled defaults so a deploy can rebrand any field — name, org, URLs,
logo SVG, favicon, product label — without rebuilding the bundle.
Operators set:
NEXT_PUBLIC_BRAND_NAME " Network"
NEXT_PUBLIC_BRAND_PRODUCT_NAME "Explorer"
NEXT_PUBLIC_BRAND_ORG_NAME " Labs"
NEXT_PUBLIC_BRAND_LOGO_CONTENT <inline svg>
...
to override; empty values fall through.
TopBar now reads chain.branding.productName instead of the hardcoded
"Lux Explorer" string. getCurrentChain() applies env overrides on every
read so a brand can be flipped at runtime via env / k8s ConfigMap.
The bundled LUX, ZOO, HANZO, SPC, PARS defaults stay as-is for OSS
shipping; the white-label "other" path keeps reading from
NEXT_PUBLIC_NETWORK_* (legacy keys) as well.
Per registry-separation rule (CLAUDE.md "Container Registries — NEVER
MIX"), luxfi/explore must only push the Lux brand. Other-brand images
(hanzoai/explore, zooai/explore, etc.) build from each brand's own
org repo, never from this one.
The source still supports white-label brand selection at runtime
(lib/white-label.ts inspects hostname or NEXT_PUBLIC_BRAND), so a
single Lux image can serve any brand at deploy time. Build-time brand
baking is reserved for per-org image variants — out of scope here.
Also drops the Lux-only frontend rollout list down to mainnet/testnet/
devnet — non-Lux deployments live in their own clusters.
Single-arch (amd64) brand matrix on lux-build-linux-amd64 — the only
ARC scale-set provisioned for luxfi org today. arm64 native runner is
pending; matrix is structured to add it back when the scale-set is
online (no QEMU per the no-emulation directive).
Manifest job dropped: with one arch, build-push-action publishes the
image directly under the canonical tag. Deploy job stays, switched
to lux-build-linux-amd64.
Build the same source four ways from one repo:
- ghcr.io/luxfi/explore (lux brand, default)
- ghcr.io/luxfi/explore-hanzo (hanzo brand)
- ghcr.io/luxfi/explore-zoo (zoo brand)
- ghcr.io/luxfi/explore-pars (pars brand)
Each is built for linux/amd64 + linux/arm64 in parallel on hanzo ARC
runners (no QEMU), then merged into a multi-arch manifest.
Brand selection at build time via NEXT_PUBLIC_BRAND, with all
brand-specific assets (logo, favicon, theme, IAM URL) loaded from
NEXT_PUBLIC_* env vars — no hardcoded brand strings in source.
External operators set NEXT_PUBLIC_BRAND=other and supply their own
NEXT_PUBLIC_* env vars (see .env.example.external). The repo carries
no third-party trademarks.
Files:
- lib/white-label.ts brand detection + helpers
- .env.example.{lux,hanzo,zoo,pars,external} deploy templates
- .github/workflows/build-lux.yml 4-brand × 2-arch matrix
- Dockerfile accept NEXT_PUBLIC_BRAND
- configs/app/chainRegistry.ts add SPC + Pars devnet,
chainId fields, white-label
chain builder
Remove Network chain entries (mainnet/testnet/devnet/localnet)
and LIQUIDITY_BRANDING constant from chainRegistry.ts. Lux explorer must
not register / hostnames. Replace "Liquid EVM Explorer"
top-bar tagline with "Lux Explorer".
Consolidating to single canonical ARC fleet. Killing duplicate lux-build
scale set. Build job → hanzo-build-linux-amd64 (max 30 on DO). Deploy
job → hanzo-deploy-linux-amd64 (max 20 on DO, correct runner class for
kubectl deploys).
No behavior change for this workflow.
Co-authored-by: Hanzo Dev <[email protected]>
The existing Next.js app (99 pages, 427 next/* imports, 177 files using
next/router, 154 using nextjs-routes types, 105 using getServerSideProps) is
far too coupled to rewrite in one pass. A full migration is ~2–4 weeks of
mechanical work.
This commit adds the scaffold only:
vite/package.json — Vite 8 + React 19.2 + wouter, no Next deps
vite/vite.config.ts — aliases at ../lib, ../ui, ../configs, … so source
migrates file-by-file instead of moving
vite/tsconfig.json — mirrors the aliases for TypeScript
vite/index.html — security headers as <meta> (was nextjs/headers.js)
vite/src/main.tsx — React 19 root bootstrap
vite/src/env.ts — runtime envs: window.__envs first, import.meta.env
fallback, maps NEXT_PUBLIC_API_HOST → VITE_API_BASE_URL
vite/src/redirects.ts — full port of nextjs/redirects.js (69 client rules)
vite/src/App.tsx — wouter router with CatchAll redirect resolver
vite/Dockerfile — 2-stage → ghcr.io/hanzoai/spa
vite/LLM.md — what's done, what's left, how to finish
The production Dockerfile at ../Dockerfile still builds the Next.js app. This
scaffold is independent; nothing in the existing tree is deleted or moved.
See vite/LLM.md for the full migration plan and 9 critical TODOs before this
can replace the Next.js build.
- Switch from registry cache to type=gha (no network overhead for DinD runners)
- Add concurrency group to cancel in-progress builds on same branch
- Merge build+deploy into single job (saves job startup overhead)
- Combine 7 tool installs into single RUN layer
- Add BuildKit cache mounts for pnpm store and Next.js .next/cache
- Combine sequential RUN commands in all 3 Dockerfile stages
- Disable Next.js telemetry during build and runtime
- Expand .dockerignore to exclude tests, docs, .github
- Fix token exchange endpoint to /api/login/oauth/access_token (IAM convention)
- Fix authorize URL to /login/oauth/authorize (consistent across components)
- Use lux-app-client-id (registered in IAM) instead of unregistered 'explore'
- Fetch user profile directly from IAM /api/userinfo endpoint
- Skip Blockscout auth_logout API call for OIDC provider
- Hide "scanning new transactions" warning (looks like error on low-traffic chains)
- Fix type error in useRedirectForInvalidAuthToken for OIDC error shape
envs.js is generated at container startup from environment variables.
Add Cache-Control: no-store header to ensure CDN/browser never serves
a stale version when config changes.
- Add Sign in button to TopBar with OIDC flow to lux.id
- Merge settings (color theme, identicon, address format) into user menu popover
- Remove duplicate user profile from HeroBanner
- Full-width stacked blocks/transactions layout on homepage
- Fix P-chain stats: CSP connect-src allows base origin for SDK calls
- Fix connected count: infer from uptime when field missing
- Fix dark mode popover background
- Enable OIDC in .env.production (lux.id, client: explore)
- Fixed TopBar.tsx: replaced chakra.svg with native svg element
- Fixed IconSvg.tsx: refactored to use native svg instead of chakra-wrapped SVG
- Changed Props interface to extend React.SVGAttributes instead of HTMLChakraProps
- Ensures SVG elements receive appropriate HTML attributes only
PascalCase enum values (PendingOutbound, OutboundMined, etc.) instead
of SCREAMING_SNAKE_CASE (PENDING_OUTBOUND, OUTBOUND_MINED, etc.) to
match the actual @luxfi/zetachain-cctx-types package exports.
zeekay
