LP-0016Final

LP-016: Lux v1 Architecture Overview

Abstract

This LP locks in the v1 architecture of Lux Network and every sovereign L1

that spawns from it. v1 is the canonical surface: one primary network

hosting three coordination chains (P, X, C), an atomic spawn primitive

that materializes new sovereign L1s in a single transaction, and a

post-quantum consensus cert (Polaris) that composes three independently

auditable PQ primitives over a classical fast-path. Every future

implementation cites this LP and its five siblings (LP-017..021) as the

ground truth for what v1 is.

Motivation

A blockchain stack drifts when components carry their own narratives.

v1 cuts that drift by stating, in one document, exactly what the

canonical primary network is, exactly what spawning a sovereign L1

means, exactly which cryptographic primitives sit under consensus,

exactly which fields live in genesis, and which paths are operator-

only extensions sitting outside the default permissionless path.

The LP set freezes vocabulary, code paths, and version pins. Future

LPs that change v1 inherit it explicitly; they do not silently fork.

Specification

Primary network

Lux primary is one network, identified by an integer networkID

shared across all Lux-derived primary networks:

| Environment | networkID |

|---|---|

| mainnet | 1 |

| testnet | 2 |

| devnet | 3 |

The integer 8675xxx values that appear in this codebase are EVM

chain IDs on top of a primary network. They are NOT primary network

IDs. Setting networkID = 8675xxx is a wire-shape bug.

The primary network hosts three chains:

P-Chain — the validator + L1 registry. Bytes32 blockchainID.

Every other chain on the network registers here. The atomic spawn

primitive (LP-018) emits its registration tx against P-Chain.

X-Chain — the network-wide UTXO settlement chain. Reserved for

X-Chain-issued primary assets and atomic swaps with P-Chain.

C-Chain — the EVM for Lux primary network ONLY. No other

network uses C-Chain. Sovereign L1s spawn their own EVM chains

with their own chain IDs; they do not reuse C-Chain.

Sovereign L1s

Each sovereign L1 (Hanzo, Zoo, Pars, Spc, and any future tenant) is

spawned by an atomic transaction on Lux primary (LP-018). After the

spawn tx finalizes, the L1 runs independently: its own validators,

its own native asset, its own consensus instance, its own daemon

binary. It does NOT depend on Lux primary at runtime; the primary

network simply holds an immutable registration record.

Each sovereign L1 may host one or more chains. The atomic spawn lets

a tenant launch (for example) an EVM + DEX + FHE triple as a single

tx; the primary network records the chain manifest in one place.

Vocabulary lock

| Canonical name | What it identifies |

|---|---|

| chain | a blockchain (the noun) |

| L1 | a sovereign network (only when network level is the subject) |

| chainID (uint) | EVM chain id |

| blockchainID (bytes32) | P-Chain blockchain id |

| validator | a chain validator |

| evmAddr + utxoAddr | per-row address fields in genesis |

The pre-v1 word for an L1 (banned in v1 prose) is the word the

2026-05-31 project-wide scrub removed from

~/work/lux/{node,cli,operator,universe,sdk,wallet,netrunner,devops,genesis}.

That scrub is the canonical reference; code that reintroduces the

word is a v1 regression.

File paths to each canonical artifact

Lux primary genesis


~/work/lux/genesis/configs/mainnet/pchain.json
~/work/lux/genesis/configs/mainnet/xchain.json
~/work/lux/genesis/configs/mainnet/cchain.json
~/work/lux/genesis/configs/testnet/{pchain,xchain,cchain}.json
~/work/lux/genesis/configs/devnet/{pchain,xchain,cchain}.json

These are the ONLY pchain.json files in the tree. Sovereign L1s

do NOT carry one — they have their own genesis.json at

~/work/lux/genesis/configs/<tenant>-<env>/genesis.json. See LP-019.

Sovereign L1 genesis


~/work/lux/genesis/configs/hanzo-{mainnet,testnet,devnet}/genesis.json
~/work/lux/genesis/configs/zoo-{mainnet,testnet,devnet}/genesis.json
~/work/lux/genesis/configs/pars-{mainnet,testnet,devnet}/genesis.json
~/work/lux/genesis/configs/spc-{mainnet,testnet,devnet}/genesis.json

Atomic spawn primitive


~/work/lux/node/vms/platformvm/txs/create_sovereign_l1_tx.go

Quasar consensus + Polaris cert


~/work/lux/consensus/protocol/quasar/quasar.go
~/work/lux/consensus/protocol/quasar/polaris.go
~/work/lux/consensus/protocol/quasar/wave_signer.go
~/work/lux/consensus/protocol/quasar/round_digest.go

PQ primitives


~/work/lux/magnetar/ref/go/pkg/magnetar/        (FIPS 205 SLH-DSA)
~/work/lux/pulsar/ref/go/pkg/pulsar/            (FIPS 204 ML-DSA threshold)
~/work/lux/corona/                              (Module-LWE Pedersen DKG, Ringtail-derived)
~/work/lux/threshold/protocols/{pulsar,corona}/ (threshold orchestration)

Operator CLI


~/work/lux/cli/cmd/l1cmd/         (L1 lifecycle)
~/work/lux/cli/cmd/chaincmd/      (per-chain ops)
~/work/lux/genesis/cmd/bootstrap-chain/  (genesis-aware bootstrap)
~/work/lux/genesis/cmd/genesis/   (genesis edit + verify)

Daemons


~/work/lux/node/                  (luxd — Lux primary)

Each sovereign L1's daemon is the same luxd binary started with

its tenant genesis blob. There is no per-tenant daemon — the tenant

binding is the genesis, not the binary.

Version pin: Lux v1.0.0

| Component | Version | Pinned in |

|---|---|---|

| node | v1.28.5 | ~/work/lux/node (tag) |

| consensus | v1.25.15 | ~/work/lux/node/go.mod:29 |

| threshold | v1.9.7 | ~/work/lux/node/go.mod:202 |

| pulsar | v1.1.2 | ~/work/lux/node/go.mod:199 |

| corona | v0.7.6 | ~/work/lux/node/go.mod:191 |

| magnetar | v1.2.0 | ~/work/lux/node/go.mod:195 |

The Magnetar paper rewrite that ships alongside this LP set lives at

~/work/lux/papers/lux-magnetar-pq/. It is the prose companion to

the magnetar v1.0.0 codebase; the paper is in LaTeX

(sections/01-introduction.tex through sections/10-conclusion.tex),

not markdown.

Cross-LP map

| LP | Owns |

|---|---|

| LP-016 (this) | The complete v1 picture; vocabulary lock; version pins |

| LP-017 | Quasar consensus + Polaris cert profile composition (Historical; cert composition rules preserved as internal-identifier reference) |

| LP-018 | The atomic spawn tx and the executor's atomicity contract |

| LP-019 | Genesis file shape: what lives where, by chain and env |

| LP-020 | TEE-only extensions for institutional MPC custody |

| LP-021 | THBS-SE — selected-element threshold SLH-DSA |

| LP-217 | Cert profile modes — operator-facing naming (PQ-off / PQ-fast / PQ-strict / PQ-heavy); canonical cert-mode selector that supersedes LP-017's codenames |

A reviewer reads LP-016 first, then descends into whichever sibling

their work touches.

Rationale

Why one primary network, multiple sovereign L1s

A single shared validator-set assumption across every L1 is a

weakness, not a feature. Each sovereign L1 picks its own validator

set sized to its own value-at-risk. The primary network's role is

to host the immutable spawn record and route asset transfers via

its UTXO chain; nothing else.

Why C-Chain is Lux primary's EVM only

Cross-pollinating C-Chain into non-Lux tenants conflates Lux

primary's settlement layer with the tenant's execution layer. The

LUX_DISABLE_CCHAIN=1 env knob in configs/configs.go makes the

non-Lux build of luxd refuse to spawn C-Chain. Tenants instead

spawn their own EVM as a sovereign L1 chain with their own

chainID.

Why version-pin everything at v1

Each release of node, consensus, threshold, pulsar, corona, and

magnetar ships its own ABI surface. A canonical version map is the

only way reviewers reading source against this LP can confirm they

are looking at v1 and not at a feature branch.

Backwards Compatibility

None. v1 is the lock-in. Migrations to future versions go in their

own LPs and inherit this one explicitly.

Test Cases

Per-area test gates that pin v1:

~/work/lux/node/vms/platformvm/txs/create_sovereign_l1_tx.go

ships syntactic-verify tests via the standard txs test suite

(LP-018).

~/work/lux/pulsar/ref/go/pkg/pulsar/wire_test.go::TestPulsar_Wire_FIPS204Verifiable

pins pulsar v1.1.2 wire byte-identity with FIPS 204.

~/work/lux/magnetar/ref/go/pkg/magnetar/wire_test.go::TestMagnetar_Wire_FIPS205Verifiable

pins magnetar v1.2.0 wire byte-identity with FIPS 205.

~/work/lux/magnetar/ref/go/pkg/magnetar/thbsse_test.go::TestThbsSE_Wire_FIPS205Verifiable

pins THBS-SE wire byte-identity with FIPS 205 (LP-021).

~/work/lux/genesis/configs/getgenesis_test.go pins the

evmAddr + utxoAddr field-naming invariant across every Lux

primary allocation entry.

Reference Implementation

Every claim in this LP grep-verifies against main of the

referenced repos as of 2026-05-31:

~/work/lux/node/vms/platformvm/txs/create_sovereign_l1_tx.go:48

declares the CreateSovereignL1Tx struct.

~/work/lux/node/version/constants.go:78-80 records the

default-version triple (1, 28, 0) whose ldflag-set patch value

is bumped per release tag.

~/work/lux/node/go.mod:29 pins github.com/luxfi/consensus v1.25.15.
~/work/lux/node/go.mod:191,199,202 pin corona v0.7.6, pulsar

v1.1.2, threshold v1.9.7 respectively.

~/work/lux/consensus/protocol/quasar/polaris.go:13 is the

Polaris profile composition declaration BLS ‖ Puls ‖ Cor ‖ Mag ‖ ZK

(internal identifier — operator-facing name is PQ-heavy per LP-217).

~/work/lux/magnetar/ref/go/pkg/magnetar/thbsse.go:6-117 is the

full THBS-SE construction, slot binding, and the v1.0 honest

open item statement.

~/work/lux/genesis/configs/mainnet/pchain.json is the canonical

Lux primary mainnet P-Chain genesis (networkID = 1).

~/work/lux/genesis/configs/getgenesis_test.go:29-30,101-102

asserts utxoAddr presence on every allocation.

Security Considerations

The vocabulary lock and version pin together prevent the most

common form of supply-chain drift in a multi-repo stack: a single

component referencing a stale primitive while the rest of the

stack has moved on. A reviewer comparing a v1 implementation

against LP-016 catches this in one read.

Sovereign L1 runtime independence (no Lux primary dependency

after spawn) is what makes a captured Lux primary survivable for

tenants. The tradeoff is that Lux primary is NOT the L1's

universal recovery layer; a captured tenant L1 cannot be unfrozen

by Lux primary action.

LP-016: Lux v1 Architecture Overview

Abstract

Motivation

Specification

Primary network

Sovereign L1s

Vocabulary lock

File paths to each canonical artifact

Lux primary genesis

Sovereign L1 genesis

Atomic spawn primitive

Quasar consensus + Polaris cert

PQ primitives

Operator CLI

Daemons

Version pin: Lux v1.0.0

Cross-LP map

Rationale

Why one primary network, multiple sovereign L1s

Why C-Chain is Lux primary's EVM only

Why version-pin everything at v1

Backwards Compatibility

Test Cases

Reference Implementation

Security Considerations

Copyright