mirror of
https://github.com/luxfi/docs.git
synced 2026-09-24 00:25:32 +00:00
docs(reference): rip Avalanche-upgrade-name framing; fix MDX <URL> bug
lux-upgrade.mdx rewritten as "header-schema compatibility" tool; the Apricot/Banff/Cortina/Durango/Etna/Fortuna/Granite fork-history table is deleted because Lux activates every feature at genesis (LP-3641). The Config-struct field names are retained — they are the on-wire header schema and cannot be renamed without breaking historical replay. lux-precompile.mdx, lux-evm.mdx, lux-lps.mdx, cchain.mdx: drop "Durango+", "Etna activated", "ACP-181" framing. EVM hardfork gates (Shanghai/Cancun) stay — they gate opcode behavior. Side fix: 5 reference MDX files (corona/magnetar/proto/pulsar/quasar) had <https://github.com/luxfi/X> raw-autolink syntax that Turbopack's MDX parser was rejecting (Unexpected `/` before local name), failing the docs build entirely. Switched to [text](url) form. Docs site now builds (453 paths prerendered).
This commit is contained in:
@@ -26,7 +26,11 @@ The C-Chain uses standard EVM 18-decimal Wei denomination, matching Ethereum con
|
||||
|
||||
## Configuration
|
||||
|
||||
The C-Chain is configured via the EVM genesis embedded in the network genesis. Key parameters include EVM fork activation timestamps. For established chains, fork overrides can be applied via an `upgrade.json` file placed in the chain data directory:
|
||||
The C-Chain is configured via the EVM genesis embedded in the network
|
||||
genesis. Lux activates all C-Chain features at genesis
|
||||
(activate-all-implicitly). The legacy `networkUpgradeOverrides`
|
||||
timestamp fields exist for header-schema compatibility with migrated
|
||||
chain-EVM state (LP-3641) and are pinned to genesis (timestamp `0`):
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -39,7 +43,8 @@ The C-Chain is configured via the EVM genesis embedded in the network genesis. K
|
||||
}
|
||||
```
|
||||
|
||||
The C-Chain supports the Cancun blob schedule:
|
||||
EVM opcode hardfork gates (Shanghai, Cancun) are kept because they
|
||||
gate bytecode behavior; the C-Chain supports the Cancun blob schedule:
|
||||
|
||||
```json
|
||||
{
|
||||
|
||||
@@ -10,7 +10,7 @@ description: "Lux production fork of Boschini et al. (eprint 2024/1113). Sibling
|
||||
`R_q = Z_q[X]/(X^256 + 1)` with Ring-LWE hardness. Same protocol
|
||||
shape as Pulsar but on the R_q ring instead of the module-lattice.
|
||||
|
||||
- **Repo**: <https://github.com/luxfi/corona>
|
||||
- **Repo**: [github.com/luxfi/corona](https://github.com/luxfi/corona)
|
||||
- **Module path**: `github.com/luxfi/corona`
|
||||
- **Latest tag**: `v0.4.0`
|
||||
- **Standard**: Lux-original production fork
|
||||
|
||||
@@ -80,7 +80,7 @@ The default mode when running as part of the Lux primary network:
|
||||
|
||||
- **Atomic transactions** for cross-chain transfers between X-Chain and C-Chain via shared memory
|
||||
- **Integrated validator set** from P-Chain -- no separate staking
|
||||
- **Network-defined hard forks** (EVM, Durango, Etna, Fortuna, Granite)
|
||||
- **Activate-all-implicitly**: every Lux feature is live at genesis. Ethereum hardfork gates (Shanghai/Cancun) still control opcode behavior; Lux network features are not separately gated.
|
||||
- **Chain ID**: 96369 (mainnet), 96368 (testnet), 96370 (devnet)
|
||||
- **Warp address**: Legacy `0x0200000000000000000000000000000000000005` (also accessible at `0x16201`)
|
||||
|
||||
@@ -220,7 +220,7 @@ github.com/luxfi/evm
|
||||
│ ├── config.go -- ChainConfig (EVM forks, chain IDs)
|
||||
│ └── extras/ -- Lux-specific extensions
|
||||
│ ├── config.go -- FeeConfig, NetworkUpgrades, GenesisPrecompiles
|
||||
│ ├── network_upgrades.go -- EVM/Durango/Etna/Fortuna/Granite timestamps
|
||||
│ ├── network_upgrades.go -- Legacy header-schema timestamps (all set to genesis on Lux)
|
||||
│ ├── precompiles.go -- Precompile configuration
|
||||
│ ├── rules.go -- Chain rules per block
|
||||
│ └── state_upgrade.go -- State upgrade definitions
|
||||
@@ -273,16 +273,22 @@ Key interfaces defined in `consensus/consensus.go`:
|
||||
- `ChainReader`: Extends header reader with full block access
|
||||
- `Engine`: Author, VerifyHeader, VerifyUncles, Prepare, Finalize, FinalizeAndAssemble, CalcDifficulty, Close
|
||||
|
||||
### Network Upgrades (Fork Order)
|
||||
### Feature Activation
|
||||
|
||||
Timestamp-based fork activation in `params/extras/network_upgrades.go`:
|
||||
Lux runs the full feature set at genesis. The Ethereum hardfork gates
|
||||
that control EVM opcode behavior (Shanghai, Cancun) stay — they are
|
||||
bytecode-level rules. Lux-specific network features have no separate
|
||||
timestamp gate.
|
||||
|
||||
| Fork | Eth Equivalent | Notes |
|
||||
|------|---------------|-------|
|
||||
| **EVM** | Pre-Shanghai | Always active at genesis (timestamp 0) |
|
||||
| **Durango** | Shanghai | Warp messaging, EIP-3651/3855/3860/6049 (EIP-4895 excluded) |
|
||||
| **Etna** | Cancun | EIP-4844 blob schedule configuration required |
|
||||
| **Fortuna** | -- | Lux-specific, no direct EVM effect |
|
||||
| EVM gate | Effect |
|
||||
|----------|--------|
|
||||
| **Shanghai** | EIP-3651/3855/3860/6049 (EIP-4895 excluded — Lux has no PoS withdrawals) |
|
||||
| **Cancun** | EIP-4844 blob schedule configuration required |
|
||||
|
||||
The legacy `params/extras/network_upgrades.go` timestamp fields exist
|
||||
for header-byte compatibility with migrated chain-EVM state (LP-3641).
|
||||
On Lux all of these fields are set to genesis (`InitiallyActiveTime`)
|
||||
so every block sees the full ruleset.
|
||||
|
||||
### Built-in Stateful Precompiles
|
||||
|
||||
|
||||
@@ -510,8 +510,8 @@ Subjects describe knowledge. Chains describe deployment. An LP about FROST thres
|
||||
|
||||
## Important Conventions
|
||||
|
||||
- All LP files use `github.com/luxfi/*` import paths -- never go-ethereum or luxfi.
|
||||
- While some LPs adopt Lux ACP specifications, all Lux implementations use **LP naming** (LP-181, not ACP-181).
|
||||
- All LP files use `github.com/luxfi/*` import paths -- never go-ethereum or ava-labs.
|
||||
- All Lux implementations use **LP naming** (LP-181, not external aliases).
|
||||
- Go package names follow `lpNNN` convention (e.g., `lp176`, `lp226`).
|
||||
- Implementation imports: `github.com/luxfi/node/vms/evm/lp176`.
|
||||
- LP content is licensed under CC0 (public domain). Specifications are BSD 3-Clause. Specialized chain implementations use the Lux Ecosystem License.
|
||||
|
||||
@@ -9,7 +9,7 @@ description: "Research-stage threshold hash-based PQ signature primitive over FI
|
||||
— hash-based post-quantum signatures over FIPS 205 SLH-DSA, intended
|
||||
as the cross-family diversity leg of the Polaris cert profile.
|
||||
|
||||
- **Repo**: <https://github.com/luxfi/magnetar>
|
||||
- **Repo**: [github.com/luxfi/magnetar](https://github.com/luxfi/magnetar)
|
||||
- **Status**: **Research-stage**. No production implementation.
|
||||
Not part of any current NIST submission.
|
||||
- **Standard**: FIPS 205 SLH-DSA (single-party)
|
||||
|
||||
@@ -167,7 +167,7 @@ The AllowList abstraction (`precompile/allowlist/`) provides role-based access c
|
||||
| `NoRole` | 0 | No access |
|
||||
| `EnabledRole` | 1 | Can call the precompile |
|
||||
| `AdminRole` | 2 | Can modify the allowlist AND call |
|
||||
| `ManagerRole` | 3 | Can add/remove Enabled only (Durango+) |
|
||||
| `ManagerRole` | 3 | Can add/remove Enabled only |
|
||||
|
||||
ABI methods: `setAdmin(address)`, `setManager(address)`, `setEnabled(address)`, `setNone(address)`, `readAllowList(address)`.
|
||||
|
||||
@@ -176,7 +176,7 @@ Role modification rules:
|
||||
- Manager can only toggle between Enabled and NoRole
|
||||
- Enabled and NoRole cannot modify the list
|
||||
|
||||
Events are emitted on role changes (Durango+) with gas cost `AllowListEventGasCost`.
|
||||
Events are emitted on role changes with gas cost `AllowListEventGasCost`.
|
||||
|
||||
### Contract Deployer AllowList
|
||||
|
||||
|
||||
@@ -10,7 +10,7 @@ module — chain types (P-Chain, X-Chain UTXO), transaction codecs,
|
||||
block types, RPC API types, RPC database adapter, and Fx plugins
|
||||
(secp256k1fx, mldsafx, slhdsafx, ed25519fx, secp256r1fx).
|
||||
|
||||
- **Repo**: <https://github.com/luxfi/proto>
|
||||
- **Repo**: [github.com/luxfi/proto](https://github.com/luxfi/proto)
|
||||
- **Module path**: `github.com/luxfi/proto`
|
||||
- **Latest tag**: `v1.0.0`
|
||||
|
||||
|
||||
@@ -12,7 +12,7 @@ Targeting NIST MPTC Class **N1** (single-party-compatible threshold
|
||||
signing) + Class **N4** (multi-party key generation with public-key
|
||||
preservation across resharing).
|
||||
|
||||
- **Repo**: <https://github.com/luxfi/pulsar>
|
||||
- **Repo**: [github.com/luxfi/pulsar](https://github.com/luxfi/pulsar)
|
||||
- **Module path**: `github.com/luxfi/pulsar`
|
||||
- **Latest tag**: `v1.0.9`
|
||||
- **Cryptographer sign-off**: APPROVED WITH GATES (`CRYPTOGRAPHER-SIGN-OFF.md`)
|
||||
|
||||
@@ -9,7 +9,7 @@ description: "Umbrella spec + profile registry + cross-primitive composition pro
|
||||
`QuasarCert` wire format and the cert-profile registry that composes
|
||||
the underlying PQ primitives into per-round finality certificates.
|
||||
|
||||
- **Repo**: <https://github.com/luxfi/quasar>
|
||||
- **Repo**: [github.com/luxfi/quasar](https://github.com/luxfi/quasar)
|
||||
- **Role**: Brand-level spec + profile registry + composition proofs
|
||||
- **Not an implementation** — the consensus-engine binding lives at
|
||||
[`luxfi/consensus/protocol/quasar/`](https://github.com/luxfi/consensus/tree/main/protocol/quasar)
|
||||
|
||||
@@ -1,11 +1,17 @@
|
||||
---
|
||||
title: "Lux Upgrade - Network Upgrade Configuration"
|
||||
description: "Documentation for Lux Upgrade - Network Upgrade Configuration"
|
||||
title: "Lux Upgrade - Header Schema Compatibility"
|
||||
description: "luxfi/upgrade package — legacy header-byte compatibility for chain-EVM migration"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Lux Upgrade is a **standalone Go package** that defines all network upgrade schedules (fork activation times) for Lux mainnet, testnet, and default/local networks. It is imported by `luxd` and other node packages to determine which protocol rules are active at any given timestamp.
|
||||
`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
|
||||
|
||||
@@ -22,34 +28,29 @@ Lux Upgrade is a **standalone Go package** that defines all network upgrade sche
|
||||
|
||||
```
|
||||
upgrade/
|
||||
├── upgrade.go # Config struct, Mainnet/Testnet/Default configs, activation checks
|
||||
├── upgrade_test.go # Validates all default configs, tests invalid ordering
|
||||
├── upgrade.go # Config struct, Mainnet/Testnet/Default configs
|
||||
├── upgrade_test.go # Validates default configs, tests invalid ordering
|
||||
└── upgradetest/
|
||||
├── fork.go # Fork enum (NoUpgrades..Granite), String() method
|
||||
├── fork.go # Fork enum (used by header-replay tests)
|
||||
├── config.go # Test helpers: GetConfig, GetConfigWithUpgradeTime, SetTimesTo
|
||||
└── upgradetest.go # TestConfig, GetConfigForVersion helpers
|
||||
```
|
||||
|
||||
## Fork History
|
||||
## Activation Model
|
||||
|
||||
All named network upgrades in chronological order:
|
||||
Lux activates all protocol features at genesis. The legacy upgrade
|
||||
fields in the `Config` struct exist solely so that:
|
||||
|
||||
| Fork | Mainnet Activation | Testnet Activation |
|
||||
|------|-------------------|-------------------|
|
||||
| ApricotPhase1 | 2021-03-31 | 2021-03-26 |
|
||||
| ApricotPhase2 | 2021-05-10 | 2021-05-05 |
|
||||
| ApricotPhase3 | 2021-08-24 | 2021-08-16 |
|
||||
| ApricotPhase4 | 2021-09-22 | 2021-09-16 |
|
||||
| ApricotPhase5 | 2021-12-02 | 2021-11-24 |
|
||||
| ApricotPhasePre6 | 2022-09-05 | 2022-09-06 |
|
||||
| ApricotPhase6 | 2022-09-06 | 2022-09-06 |
|
||||
| ApricotPhasePost6 | 2022-09-07 | 2022-09-07 |
|
||||
| Banff | 2022-10-18 | 2022-10-03 |
|
||||
| Cortina | 2023-04-25 | 2023-04-06 |
|
||||
| Durango | 2025-03-06 | 2025-02-13 |
|
||||
| Etna | 2025-04-08 | 2025-03-13 |
|
||||
| Fortuna | 2025-12-16 | 2025-11-25 |
|
||||
| Granite | Unscheduled | Unscheduled |
|
||||
1. Historical chain-EVM block headers parse correctly during
|
||||
migration (LP-3641).
|
||||
2. Test harnesses can replay legacy fork-boundary edge cases against
|
||||
the canonical Lux feature set.
|
||||
3. 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
|
||||
|
||||
@@ -60,41 +61,20 @@ TestnetID uint32 = 5
|
||||
|
||||
## Config Struct
|
||||
|
||||
```go
|
||||
type Config struct {
|
||||
ApricotPhase1Time time.Time
|
||||
ApricotPhase2Time time.Time
|
||||
ApricotPhase3Time time.Time
|
||||
ApricotPhase4Time time.Time
|
||||
ApricotPhase4MinPChainHeight uint64
|
||||
ApricotPhase5Time time.Time
|
||||
ApricotPhasePre6Time time.Time
|
||||
ApricotPhase6Time time.Time
|
||||
ApricotPhasePost6Time time.Time
|
||||
BanffTime time.Time
|
||||
CortinaTime time.Time
|
||||
CortinaXChainStopVertexID ids.ID
|
||||
DurangoTime time.Time
|
||||
EtnaTime time.Time
|
||||
FortunaTime time.Time
|
||||
GraniteTime time.Time
|
||||
GraniteEpochDuration time.Duration
|
||||
}
|
||||
```
|
||||
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
|
||||
|
||||
```go
|
||||
|
||||
// Get config by network ID
|
||||
cfg := upgrade.GetConfig(upgrade.MainnetID)
|
||||
|
||||
// Check if a fork is active at a given time
|
||||
if cfg.IsFortunaActivated(time.Now()) {
|
||||
// Fortuna rules apply
|
||||
}
|
||||
|
||||
// Validate upgrade ordering
|
||||
// Validate upgrade-time monotonicity (legacy header replay)
|
||||
if err := cfg.Validate(); err != nil {
|
||||
// ErrInvalidUpgradeTimes: upgrades are not in chronological order
|
||||
}
|
||||
@@ -103,19 +83,10 @@ if err := cfg.Validate(); err != nil {
|
||||
## Test Helpers (`upgradetest` package)
|
||||
|
||||
```go
|
||||
|
||||
// Get config with all forks up to Etna activated, rest unscheduled
|
||||
cfg := upgradetest.GetConfig(upgradetest.Etna)
|
||||
|
||||
// Get config with custom activation time
|
||||
cfg := upgradetest.GetConfigWithUpgradeTime(upgradetest.Durango, time.Now().Add(time.Hour))
|
||||
|
||||
// Set fork times on existing config
|
||||
upgradetest.SetTimesTo(&cfg, upgradetest.Banff, upgrade.InitiallyActiveTime)
|
||||
|
||||
// Fork enum
|
||||
upgradetest.Latest // == Granite
|
||||
upgradetest.Fortuna.String() // "Fortuna"
|
||||
// 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
|
||||
@@ -127,6 +98,6 @@ go test -v ./...
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `lux/lux-node.md` -- Imports this package for fork scheduling
|
||||
- `lux/lux-consensus.md` -- Consensus rules change at fork boundaries
|
||||
- `lux/lux-evm.md` -- EVM rules activated per fork
|
||||
- `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
|
||||
|
||||
Reference in New Issue
Block a user