universe/e2e/dex/README.md

DEX boot/reset/upgrade e2e harness

Deterministic proof that a Lux net boots to a known-good, taggable spec: C-Chain up → 0x9999 DEX precompile active → a DEXFill settles → all validators converge. This is the GATE that replaces operator drift — a green run pins a node version + config that is reproducible, not hand-tuned live state.

The harness is two halves, kept separate:

Half	What	Where
Read gate (assertions)	dex_e2e_test.go — stdlib-only eth JSON-RPC. Never writes.	this dir
Write leg (a real fill)	the proven trader binary (trader prove)	~/work/lux/trader

boot.sh / reset.sh / upgrade.sh orchestrate a disposable localnet, drive a real fill with trader, then run the gate.

The gate — dex_e2e_test.go

Given LUX_RPC (one or more comma-separated C-Chain endpoints, one per validator) it asserts:

1. eth_chainId == LUX_CHAIN_ID (if set),
2. C-Chain booted past genesis (height > 0, building blocks),
3. eth_getCode(0x9999) == 0x01 — DEX precompile active and has settled (the one-byte vault marker is written only by a fill),
4. a DEXFill log was emitted (the DEX actually traded),
5. every endpoint reports an identical block hash at a common height — the convergence / determinism proof.

Skipped (not failed) when LUX_RPC is unset, so it is CI-safe.

# spec verification against any reachable v1.31.2 net (non-destructive, read-only)
LUX_RPC=https://api.lux-test.network/v1/chain/c LUX_CHAIN_ID=96368 ./verify.sh

# multi-validator convergence (e.g. 3 port-forwarded devnet pods)
LUX_RPC=http://127.0.0.1:19651/v1/chain/C/rpc,http://127.0.0.1:19652/v1/chain/C/rpc,http://127.0.0.1:19653/v1/chain/C/rpc \
  LUX_CHAIN_ID=96367 LUX_REQUIRE_FILL=1 ./verify.sh

Env: LUX_RPC (required), LUX_CHAIN_ID, LUX_FROM_BLOCK (DEXFill scan start, default 0), LUX_REQUIRE_FILL=1 (fail if no fill log; default: the 0x01 marker is sufficient settlement proof).

Boot / Reset / Upgrade on a disposable localnet

These need a v1.31.2 luxd binary (LUXD=) and the lux CLI. They wipe and write — never point them at a live net.

# BOOT: fresh genesis → 5 validators → real fill → gate
LUXD=~/work/lux/node/build/luxd N=5 ./boot.sh

# RESET: wipe + re-boot → same green result (determinism)
LUXD=~/work/lux/node/build/luxd ./reset.sh

# UPGRADE: boot on FROM, roll to TO, re-prove the fill survives the version roll
FROM_LUXD=~/.lux/bin/luxd/old/luxd TO_LUXD=~/work/lux/node/build/luxd ./upgrade.sh

Proven green (2026-06-28)

The read gate is green against the live v1.31.2 spec on all three nets:

Net	chainId	height	0x9999	DEXFill	convergence
devnet	96367	36	0x01 ✓	6 ✓	3 validators agree @ block 15 ✓
testnet	96368	11	0x01 ✓	1 ✓	(single ingress)
mainnet	96369	1,082,812	0x01 ✓	marker ✓	(single ingress)

chainId = 96367 ✓
C-Chain height = 36 (booted past genesis) ✓
0x9999 = 0x01 (DEX precompile active + has settled) ✓
DEXFill logs over [0,latest] = 6 (DEX has traded) ✓
all 3 validators converge on block 15 hash 0x211cde…71ef ✓
DEX is trading ✓

Full local BOOT/RESET/UPGRADE from genesis requires a v1.31.2 luxd binary for the host arch (the published image is linux/amd64); on a host without it the gate above is the spec proof and the scripts run green the moment a binary is present (e.g. an amd64 CI runner). See ../../RUNBOOK.md.