Lux Docs

luxfi/upgrade package — legacy header-byte compatibility for chain-EVM migration

Overview

luxfi/upgrade is a standalone Go package that exposes the legacy chain-EVM upgrade-time fields so historical block headers and migrated chain state parse correctly on Lux. It does not gate Lux feature activation: Lux runs the full feature set from genesis (the activate-all-implicitly model). See LP-3641 for the migration contract and LP-3650 / LP-4180 / LP-3512 for the per-feature LP references.

Quick Reference

Item	Value
Repo	`github.com/luxfi/upgrade`
Module	`github.com/luxfi/upgrade`
Default branch	`main`
Language	Go 1.26.1
Dependencies	`github.com/luxfi/ids`, `github.com/luxfi/crypto`
Test framework	`testify`

Architecture

upgrade/
├── upgrade.go              # Config struct, Mainnet/Testnet/Default configs
├── upgrade_test.go         # Validates default configs, tests invalid ordering
└── upgradetest/
    ├── fork.go             # Fork enum (used by header-replay tests)
    ├── config.go           # Test helpers: GetConfig, GetConfigWithUpgradeTime, SetTimesTo
    └── upgradetest.go      # TestConfig, GetConfigForVersion helpers

Activation Model

Lux activates all protocol features at genesis. The legacy upgrade fields in the Config struct exist solely so that:

Historical chain-EVM block headers parse correctly during migration (LP-3641).
Test harnesses can replay legacy fork-boundary edge cases against the canonical Lux feature set.
Cross-chain tooling (block explorers, wallet libraries) that reads chain configs sees the same field shapes it expects.

Ethereum hardfork gates (homestead/byzantium/.../shanghai/cancun) are preserved because they gate EVM opcode behavior at the bytecode level, not network-feature rollout.

Network IDs

MainnetID uint32 = 1
TestnetID uint32 = 5

Config Struct

The Config struct exposes the legacy chain-EVM header fields verbatim for parser compatibility. On Lux all of these are set to InitiallyActiveTime (genesis), so every fork is active for every header the node processes. The field names are part of the on-wire header schema and cannot be renamed without breaking historical replay.

Usage

// Get config by network ID
cfg := upgrade.GetConfig(upgrade.MainnetID)

// Validate upgrade-time monotonicity (legacy header replay)
if err := cfg.Validate(); err != nil {
    // ErrInvalidUpgradeTimes: upgrades are not in chronological order
}

Test Helpers (`upgradetest` package)

// Replay-style helpers for boundary testing against legacy chain-EVM
// headers. On Lux mainnet/testnet all forks are initially active.
cfg := upgradetest.GetConfig(upgradetest.Latest)
upgradetest.SetTimesTo(&cfg, upgradetest.Latest, upgrade.InitiallyActiveTime)

Commands

go build ./...
go test -v ./...

lux/lux-node.md -- Imports this package for header compatibility
lux/lux-consensus.md -- Consensus rules are activate-all-implicitly
lux/lux-evm.md -- EVM rules live at genesis; see LP-3641 / LP-3650

Lux Upgrade - Header Schema Compatibility