Two coupled knobs for differentiated cadence — co-located D-Chain/DEX (fast) vs public
C-Chain (standard):
1. MinBlkDelay was hardcoded to the 1s DefaultMinBlockDelay in chains/manager.go, ignoring
its own --proposervm-min-block-delay flag. Now wired node.Config → ManagerConfig →
proposervm.Config (0 ⇒ 1s default). High-throughput nets set it low.
2. Block timestamps were Truncate(time.Second) at 4 sites, quantizing cadence to 1s
regardless of WindowDuration — so a sub-second window inflated slot numbers without finer
time resolution and could NOT produce blocks faster than 1/s. Truncation now tracks
proposer.TimestampGranularity() = min(1s, WindowDuration): mainnet (>=1s) keeps exact
1-second block times; sub-second windows get matching sub-second timestamps.
Measured: 1s window/delay → ~95-104 TPS, byte-identical 5/5 finality (unchanged from before,
no regression). NOTE: true sub-second cadence additionally requires a slot-handoff fix — at
100ms the slot recomputed in buildChild from a drifted 'now' can differ from the slot
timeToBuild scheduled, causing errUnexpectedProposer verify drops; that + multi-sender
saturation is the next step. These knobs are the necessary foundation.
Co-authored-by: Hanzo Dev <dev@hanzo.ai>
Two changes, both node-local:
1. CADENCE — proposer.WindowDuration (the proposer-slot spacing, a validator's min build
delay = slot index x WindowDuration) was a hardcoded 5s const tuned for mainnet-scale
validator sets, flooring small/local block cadence at 5s per slot. It is now a
startup-configurable var (default 5s, unchanged for mainnet) set via the new
--proposervm-window-duration flag → node.Config → ManagerConfig → proposervm.Config →
proposer.SetWindowDuration at VM init. Read by both the windower delay math and
TimeToSlot, so they stay consistent. Measured on a 5-node strict-PQ net: 5s→1s took
sustained C-Chain from 44 TPS / 14s-per-block to 104 TPS / 3.8s-per-block, still 5/5
byte-identical finality.
2. SECURITY (cryptographer MEDIUM-1) — postForkCommonComponents.Verify now refuses a block
carrying a CLASSICAL secp256k1 proposer identity when the chain is strict-PQ
(StakingMLDSASigner set), UNCONDITIONALLY (before the consensusState==Ready gate, so it
also holds during bootstrap/state-sync). Fills the documented-but-unwired 'proposer'
SchemeGate site: the downgrade defense is now an explicit fail-closed in-perimeter gate,
not merely emergent from 20-byte NodeID collision-resistance + upstream enforcement.
Adds SignedBlock.HasClassicalProposer(). Mirrors contract.RefuseUnderStrictPQ.
Pins consensus v1.36.7 (consume-on-error build loop — kills the non-leader BuildBlock spin).
Block + proposervm VM tests green.
Co-authored-by: Hanzo Dev <dev@hanzo.ai>
config/flags.go + staking/kms.go: the StakingKMSSecretPath example string
referenced a brand-specific devnet path; replaced with the generic
/staking/devnet/node-0 form (lux surfaces carry no white-label brand
tokens). tools/go.sum: corrected the stale charmbracelet/x/ansi v0.9.2 h1
checksum to the canonical value (verified via go mod download).
pemBytesOrFile short-circuited when a *-content flag was set but empty
(v.IsSet true, value ""), returning empty bytes instead of consulting
the corresponding *-file path.
For strict-PQ staking keys (--staking-mldsa-key-file-content /
--staking-mldsa-key-file) this silently degraded a validator to a
classical ECDSA NodeID: StakingMLDSAPub stayed empty, IsStrictPQ() was
false, and the node booted with no error. The genesis validator set then
never matched the live NodeIDs and the P-chain produced 0 blocks -- the
strict-PQ activation outage (the #48 failure class).
Treat a set-but-empty content flag identically to an absent one and fall
through to the *-file path. The same helper backs the ML-KEM handshake
keys, so both paths are fixed.
Restore the regression guard
TestLoadStakingMLDSA_EmptyContentFallsThroughToPath (fails on main,
passes here) alongside the other loadStakingMLDSA cases.
Verified: CGO_ENABLED=0 go test ./config/
The asset-id var was already unified to UTXOAssetID; this finishes the
job by renaming resolveXAssetID -> resolveUTXOAssetID and
XAssetIDFromGenesisBytes -> UTXOAssetIDFromGenesisBytes (+ their tests).
X-Chain references (XChainID, XChainGenesis) are unchanged. UTXOAssetID
is the canonical name.
Co-authored-by: Hanzo Dev <dev@hanzo.ai>
ConfigSpec.JSON() exports the flag specification as JSON. Duration-typed
default values (e.g. consensus timeouts) need to render as integer
nanoseconds for v1-compatible consumers and so the embedded JSON
fixtures roundtrip. Pass jsonv1.FormatDurationAsNano(true) at the
Marshal site.
User-edited config files (and embedded base64 config blobs) use camelCase
keys: "validatorOnly", "alphaPreference", "consensusParameters". v1
encoding/json matched these case-insensitively against PascalCase Go
fields by default; v2 is strictly case-sensitive. Add
json.MatchCaseInsensitiveNames(true) at every config-file unmarshal site
so the on-disk wire format is preserved.
config_test.go: nil []byte round-trips through v2 as empty []byte{}
(v1 left it nil). reflect.DeepEqual treats nil != empty for slices, so
require.Equal fails on roundtrip. Add equalChainConfigs() helper using
bytes.Equal, which canonically treats nil == empty.
External (HTTP / JSON-RPC) is the only place JSON is legitimate. Every
existing encoding/json import in node/ moves to github.com/go-json-experiment/json
(v2 root, not the v1 sub-package). NewEncoder/NewDecoder rewrite to
MarshalWrite/UnmarshalRead. MarshalIndent rewrites to Marshal with
jsontext.WithIndent. json.RawMessage rewrites to jsontext.Value.
*json.SyntaxError rewrites to *jsontext.SyntacticError.
81 files migrated. LLM.md captures the rule + v1->v2 delta table.
Known v2 semantic deltas surfaced by existing tests (followups, not regressions):
- [N]byte fields with no MarshalJSON now marshal as base64 string (v1 marshalled
as JSON array of byte numbers). Affects vms/platformvm/txs/*_test.go fixtures
with embedded BLS proofOfPossession.
- time.Duration has no v2 default representation; configs that wire-format
Duration as nanoseconds (vms/{xvm,platformvm}/config, config/spec) need to
switch to string-form Duration or carry an explicit option. v2 root does not
re-export FormatDurationAsNano.
- v2 enforces strict UTF-8 (vms/chainadapter/messaging fixture has non-UTF-8).
- json.MarshalWrite does not append a trailing '\n' (v1 NewEncoder.Encode did);
service/auth/auth_test.go expectation updated.
- nil []byte round-trips to empty (not nil); config_test deep-equal fixtures
surface this.
All affected sites are at the API boundary; ZAP wire envelope already covers
the internal data paths (state, P2P, consensus, MPC, threshold). Internal
JSON sites that should move to ZAP next (separate work):
- vms/da/store.go (DA blob/cert storage as JSON)
- vms/platformvm/airdrop (airdrop claims as JSON in db)
- vms/chainadapter/appchain (SQLite materializer schema/data blobs)
- vms/chainadapter/messaging (conversation codec)
- staking/kms.go (KMS HTTP client — external technically, leave)
- utils/{bimap,ips} (small marshaler shims — low priority)
The cached `<dataDir>/genesis.bytes` file is written on first start to
hold hash stability across restarts. On a binary upgrade that adds
new codec types (multi-version v0+v1 dispatcher, etc.), the old
cached blob may carry type IDs the new binary doesn't recognise. The
existing code surfaced this as `resolve X-Chain asset ID from cached
genesis: unmarshal interface: unknown type ID N` and returned an
error — wedging the node in CrashLoop with no automatic recovery.
Drop the cache and rebuild from the `--genesis-file` instead. Hash
stability is forfeit for that single restart (intentional — the
alternative is a permanent outage on every binary bump that changes
codec types). Subsequent restarts re-establish stability against the
fresh cache.
Surfaced today on <tenant> testnet+mainnet bumping lqd v1.9.x →
v1.10.8: every pod hit "unknown type ID 29" on the stale v1.9.x
codec cache and CrashLoopBackOff'd.
The field is the primary network's UTXO fee asset (P+X), not
X-chain-specific. P-chain CreateChainTx / AddChainValidatorTx and
X-chain transfers all burn it for fees. Same number on P and X by
construction; the name should reflect the function, not the chain.
Renames applied across:
- wallet/chain/{p,x}/builder.Context.UTXOAssetID
- wallet/chain/x/builder.Backend.UTXOAssetID() trait method
- node/config: resolveUTXOAssetID + nodeConfig.UTXOAssetID
- vms/platformvm + vms/xvm + chains/manager consumers
- examples (deploy-chains, get-p-chain-balance, ...)
Includes local replaces for luxfi/{runtime,consensus} pending their
release tags landing. Drop after upstream tags ship.
Companion PRs: luxfi/runtime#2, luxfi/consensus#11. Downstream
consumers (sdk, cli, genesis, liquidity) follow.
config.UTXOAssetIDFor(networkID) returns a network-id-keyed constant
that's identical across every L1 sharing a primary-network ID. On
sovereign L1s (<tenant> / MLC / VCC / any future tenant) the X-Chain
genesis bakes a different asset (different validator set, different
holder set, different denomination) so the runtime asset ID — the ID
vm.initGenesis assigns to the first GenesisAsset.CreateAssetTx — does
not match the constant.
Every wallet builder that calls platform.getStakingAssetID to populate
pCTX.XAssetID then pays tx fees from UTXOs under an asset the chain
doesn't recognise:
insufficient funds: needs 398 more nLUX (<constant>)
That's the bootstrap failure on <tenant> devnet / testnet / mainnet
after the chainset-via-embedded-genesis fix landed.
Fix: derive the X-Chain native asset ID from the actual genesis bytes
the binary loads at startup. Every load path now goes through
resolveXAssetID(networkID, genesisBytes):
- genesis baked with X-Chain → parse the embedded XVM genesis,
initialize the first GenesisAsset.CreateAssetTx, return its tx.ID()
(the same value vm.initGenesis assigns at runtime).
- genesis is P-only (no X-Chain) → fall back to UTXOAssetIDFor.
Value is unused at runtime, kept for downstream-consumer shape.
- genesis is malformed → error (was previously silently returning
the wrong constant; that's how sovereign L1s ended up shipping
binaries that disagreed with their own chain).
Touched:
- vms/xvm/genesis.go: ParseGenesisBytes + AssetIDFromGenesisBytes.
- vms/xvm/genesis/lux.go: AssetIDFromBytes proxy so the wrapper
package stays the single dependency point.
- genesis/builder/builder.go: FromConfig uses the genesis-derived
ID instead of UTXOAssetIDFor; new XAssetIDFromGenesisBytes
helper for the platform-genesis-bytes path.
- config/config.go: getGenesisData's raw and cached paths now call
resolveXAssetID. FromConfig path inherits the fix automatically.
Tests:
- vms/xvm/genesis/lux_test.go: AssetIDFromBytes is stable, holder-
sensitive, network-id-sensitive, malformed-input-rejecting.
- genesis/builder/builder_p_only_test.go: helper agrees with
FromConfig on sovereign genesis, returns ok=false on P-only,
errors on garbage.
- config/config_test.go: resolveXAssetID returns the genesis-derived
ID for sovereign genesis, UTXOAssetIDFor on P-only, error on
garbage.
No network-id allow-list, no per-network branching, no env-var
overrides. The fix is in the binary's load path; operator workflows
stay byte-identical.
Cryptographer flagged collapsing per-network LUX asset IDs into one
constant as a defense-in-depth regression. constants v1.5.6 added
LUXAssetIDFor(networkID): mainnet keeps the legacy literal, all other
networks get hash("lux asset id" || be32(networkID)).
- genesis/builder/builder.go: xAssetID := constants.LUXAssetIDFor(config.NetworkID)
- config/config.go: replace extractXAssetID() callsites with
constants.LUXAssetIDFor(networkID); delete the now-dead helper.
Bundles dev agent's earlier X-Chain decomplect commit (7a379ec6) into
the same push: X-Chain is now opt-in via XChainGenesis, no longer
hardcoded as "always present".
Builds + tests green.
Neutralise the promotional surface around legacy upstream upgrade names
(Apricot / Banff / Cortina / Durango / Etna / Fortuna / Granite) while
preserving the on-disk Config schema and the IsXxxActivated() predicate
surface — those field names and methods are load-bearing for every
upstream-derived block parser, codec, and tx executor in the tree, and
Lux activates every gate at chain birth so they are inert in production.
Changes:
- upgrade/upgrade.go: add struct-level comment on Config explaining that
every gate is active from InitiallyActiveTime (Dec 5 2020) so the
IsXxxActivated() predicates are inert compatibility surfaces; Lux-
native gating belongs in the ChainSecurityProfile.
- upgrade/upgradetest/fork.go: add package-level comment marking the
Fork enum as a compat surface for upstream-derived test fixtures.
- vms/platformvm/docs/{block_formation_logic,chain_time_update}.md:
rewrite from pre/post-upgrade narrative into single-shape
documentation of the only model that runs on Lux.
- vms/platformvm/docs/validators_versioning.md, indexer/service.md,
config/config.md, vms/platformvm/warp/README.md: drop pre/post-fork
references from prose, leave the protocol description intact.
- vms/proposervm/proposer/windower.go, pre_fork_block.go,
vms/proposervm/block_test.go, vms/platformvm/warp/validator.go,
vms/platformvm/txs/executor/proposal_tx_executor.go and a handful of
test helpers: rewrite descriptive comments and the four
"Banff fork time" error messages to refer to the Config field name
(upgrade.Config.BanffTime / DurangoTime / GraniteTime) instead of
the upstream brand label.
- tests/granite_integration_test.go -> tests/lp181_integration_test.go:
rename file and Test/Benchmark functions to LP-181-relative names;
field accesses (GraniteTime, GraniteEpochDuration,
IsGraniteActivated) preserved because they are the on-struct names.
- network/network.go, network/peer/peer.go, chains/manager.go,
scripts/tests.upgrade.sh, .github/labels.yml: scrub stray
upstream-brand mentions from comments / labels.
What is intentionally preserved (compat shim policy, same logic as the
geth-config preservation rule for ~/work/lux/coreth /geth /genesis):
- upgrade.Config field names (ApricotPhaseNTime, BanffTime, ..., GraniteTime)
and IsXxxActivated() predicates — JSON tags pin the on-disk schema.
- upgradetest.Fork enum values (NoUpgrades..Granite) — referenced by
hundreds of upstream-derived test fixtures.
- Block-type identifiers (BanffStandardBlock, ApricotProposalBlock, ...)
— wire-format-load-bearing.
- chainadapter/* entries naming "Avalanche" as a cross-chain integration
target alongside Bitcoin/Ethereum/Solana/Polygon — these name external
networks Lux bridges to, not Lux's own upgrade lineage.
- RELEASES.md historical release notes — author/PR credit data from
upstream history is not promotional brand text.
Build verified: GOWORK=off go build ./... -> exit 0.
Operator owns the chainset. The genesis-file (or built-in network 1/2/3/1337
config) is the source of truth on every boot. No 'is this a standard network
ID? then guard against custom genesis' branching, no 'stored hash differs?
then refuse to boot unless you set this other flag' guard. Decomplect both:
- Genesis hash check (node/node.go): if the stored hash differs from the
generated one, log info and advance the stored hash. Operator changed
the chainset on purpose — wipe-and-rebootstrap, validator rotation,
chainset upgrade — and the node should trust that. The DB hash is a
tag, not a lock.
- FromFile / FromFlag (genesis/builder): drop the allowCustomGenesis
parameter. Caller-driven: if you pass a genesis file, we use it.
Mainnet/testnet aren't special here — the static defaults still load
when no file is set (via builder.GetConfig).
- Wire all the way out: flag definitions (config/flags.go, config/spec/flags.go),
key constants (config/keys.go), Node.Config struct field (config/node/config.go),
reader (config/config.go). Five layers, none of them earned their keep.
keyutil.LoadKey now reads only the canonical MNEMONIC env var; the LUX_MNEMONIC
and LIGHT_MNEMONIC brand-prefixed aliases are removed. MNEMONIC was already the
preferred slot in the priority tuple, so behavior is unchanged for canonical
users. Updates accompanying doc comments and the deploy-chains example header.
Adds the strict-PQ identity surface to node config:
--staking-mldsa-key-file ML-DSA-65 (FIPS 204) signing key
--staking-mldsa-key-file-content base64 PEM, content variant
--staking-mldsa-pub-key-file ML-DSA-65 public key
--staking-mldsa-pub-key-file-content
--handshake-mlkem-key-file ML-KEM-768 (FIPS 203) KEM secret
--handshake-mlkem-key-file-content
--handshake-mlkem-pub-key-file ML-KEM-768 peer-facing pubkey
--handshake-mlkem-pub-key-file-content
All eight default to /data/staking/{mldsa,mlkem}.{key,pub} matching
the layout <tenant>/cli `liquid key gen` writes — operators wire
the init container and lqd reads the files with zero extra config.
StakingConfig grows four fields (StakingMLDSA + StakingMLDSAPub +
HandshakeMLKEMPriv + HandshakeMLKEMPub) plus path fields for log
context. config.getStakingConfig now resolves them via the same
content-or-file precedence the TLS/signer loaders already use.
Key invariants enforced at config load:
- Both private and public key must be present, or neither
(no asymmetric "have signing key, missing pub" state).
- Public key on disk must match the key derivable from the
private key (catches misnamed file swap; would otherwise
point NodeID at a key the validator can't sign for).
- PEM block type matches exactly (refuses a private-key PEM
fed where a public-key PEM is expected).
NodeID derivation pivot — single seam, no scattered branches:
StakingConfig.IsStrictPQ() → len(StakingMLDSAPub) > 0
StakingConfig.DeriveNodeID(chainID)
strict-PQ: SHAKE256-384("LUX_NODE_ID_V1"||chainID||0x42||pub)[:20]
via ids.NodeIDSchemeMLDSA65.DeriveMLDSA
classical: ids.NodeIDFromCert(StakingTLSCert.Leaf)
StakingConfig.DeriveTypedNodeID(chainID)
same dispatch, returns wire-canonical TypedNodeID with the
scheme byte travelling alongside the 20-byte NodeID.
Callsites that currently call ids.NodeIDFromCert directly are now
bypassing the strict-PQ pivot; migrating them to DeriveNodeID /
DeriveTypedNodeID is the follow-up workstream (the pivot itself
is non-breaking — classical chains continue to route through
NodeIDFromCert via the seam).
Requires luxfi/ids v1.2.10+ for NodeIDSchemeMLDSA65 / DeriveMLDSA.
Two related fixes that make chain tracking explicit per-validator:
1. config/config.go: drop the silent default
`if TrackedChains == nil { TrackAllChains = true }`. That made any
node without an explicit --track-chains list try to spin up every
chain in P-chain state, including ones whose VM plugin wasn't
loaded. The setting was a footgun. Empty TrackedChains now means
"track only P/X (built-in)". TrackAllChains stays as an explicit
opt-in escape hatch.
2. chains/manager.go: when buildChain returns ErrNotFound (VM plugin
not registered for this chain's vmID), treat it as the validator's
"I don't validate this one" signal — log info, mark the slot
bootstrapped, and return WITHOUT registering a per-chain failing
health check. The chain stays in pending state for hot-load.
Previously this registered a permanent 503 on /ext/health for the
chain-alias, which made kubelet liveness probes kill any pod that
didn't ship plugins for every chain in the primary genesis. Now
validators participate per-plugin: load liquid-evm/dex/fhe → those
chains validate; don't load Lux's upstream EVM plugin → C-Chain
stays in pending without crashing the node.
Real failures (e.g. genesis decode error, db corruption) still register
the failing health check — those are operator misconfigurations, not
deliberate opt-outs.
Future: a Lux-signed featured-chains.json + --track-featured (default
true) would make this opt-in safer at scale — limits the DDoS surface
of unbounded chain creation while still letting validators earn yield
on the curated set out of the box.
The automine path embeds the C-Chain genesis bytes into the primary-
network genesis at boot. Until now that genesis was a hardcoded constant
(chainId 31337) — fine for stock lqd local dev, but downstream networks
(<tenant> at chainId 8675312, etc.) had no way to override without
patching the binary. The chain-config-dir scan happens AFTER the EVM
plugin has already initialised from the embedded bytes, so dropping a
genesis.json into configs/chains/C/ is silently ignored.
Adds LUX_AUTOMINE_CCHAIN_GENESIS_PATH: when set, lqd reads the JSON at
that path and embeds it as the C-Chain genesis. Unset → unchanged
behaviour (chainId 31337 default).
The saved AutomineNetworkConfig also mirrors the resolved value so the
on-disk record is true to what was embedded.
The field has always semantically been the X-Chain asset ID — the JSON
tag is already `xAssetID`. The Go name `LuxAssetID` was a holdover from
when "LUX" was the only asset name on the chain, which created confusion
when readers expected `XAssetID` to mirror `XChainID` / `CChainID` /
`DChainID` (all of which already used the chain-letter naming).
Renamed across config, node, vms/platformvm, vms/rpcchainvm/zap and the
static_service API request types. JSON tag and protobuf wire fields are
unchanged, so on-disk configs and inter-process plugin RPC are
backwards-compatible — only Go callers see the new name.
Pulls in:
* luxfi/constants v1.5.2 — LocalID/CustomID semantic split, IsCustom()
* luxfi/genesis v1.9.2 — same split mirrored at the configs layer
* luxfi/zwing v0.5.2 — full PQ secure channel (X-Wing + ML-DSA-65 +
ChaCha20-Poly1305) with cross-language
wire-byte interop verified against Rust /
Python / TypeScript ports
* luxfi/api v1.0.10 — zap.NewListener seam (used by zwing.ListenZAP)
* luxfi/netrunner v1.18.1 — PQ-mandatory zapwire control RPC + same
LocalID rename
* luxfi/geth v1.16.87 — verkle.Fr type fix (drop bandersnatch import)
* luxfi/consensus v1.23.1 — banderwagon path move tracked
Source-side rename in this repo: every constants.CustomID call was
"the local 1337 dev network", so they all become constants.LocalID
(both the upgrade-config validation switch and the test fixtures).
The old constants.CustomID literal is now 0 — used as the explicit
"this is a user-defined custom network" sentinel, separate from the
LocalID dev network.
Plus a clarifying comment on the upgrade-config switch noting which
network IDs are permitted to override their upgrade schedule (any
non-well-known ID, including DevnetID/UnitTestID and any genuinely
custom user-defined network ID).
Z-Wing dialer + tests still green; all network/dialer, config,
config/node, config/spec, and genesis/builder tests pass.
Remove unused bloom filter, test helpers, metrics scaffolding, and
linearizable VM wrapper. Trim stale go.sum entries. Add genesis builder
helpers and xvm FX/genesis initialization.
