genesis/CHANGELOG.md

# genesis CHANGELOG

## Unreleased

### Mnemonic env unification — one var, one way

The genesis mnemonic is now read from exactly one env var: `LUX_MNEMONIC`.
The previous two-env fallback chain (`MNEMONIC` then `LIGHT_MNEMONIC`)
is gone — there is one and only one canonical name.

- `pkg/genesis.MnemonicEnvVar` constant exposes the name (`"LUX_MNEMONIC"`).
- `getMnemonicEnv()` reads only `LUX_MNEMONIC`. No fallback.
- All CLI help, error messages and tests now reference `LUX_MNEMONIC`.
- `LightMnemonic` constant still holds the well-known dev seed value:
  pass it as the value of `LUX_MNEMONIC` to bootstrap a local network.

Per-env isolation comes from a DIFFERENT mnemonic per env (loaded from
KMS for production), not from the env-var name.

### Dead-code removal — vesting rot

The "50M free + 50M vesting at 1%/year over 100y from Jan 1 2020"
docstring was a lie: the canonical builder `buildConfigFromKeyInfos`
never wired the 100-period schedule (the prior code admits the schedule
"overflows zapdb batch limit"). Drop the unreachable plumbing:

- `StakingStartTime`, `UnlockInterval`, `VestingPeriods` constants
- `buildUnlockSchedule()` function (pkg/genesis/keys.go)
- `VestingConfig` struct + `DefaultVesting()` + `WithVesting()`
- vesting branches in `ChainAllocations.PChain()` / `PChainMap()`
- `GeneratePChainAllocationsWithVesting()` function
- `MainnetAllocations` no longer calls `WithVesting(DefaultVesting())`

The validator stake-lock (3-entry 5y/10y/20y schedule attached to the
validator's UTXO inside `buildConfigFromKeyInfos`) is unchanged — that
locked-stake bucket is the only `UnlockSchedule` in the canonical
genesis path and the ProtocolVM needs it.

`pkg/genesis/networks.go` adds the canonical primary-network-id table
(`MainnetID` 1, `TestnetID` 2, `DevnetID` 3, `LocalID` 1337) as the
single source of truth for "what envs exist".

### Breaking — HIP-0077 §"Identity" HD path alignment

`pkg/genesis/keys.go` now derives keys on the per-network hardened
branches mandated by HIP-0077:

| derived              | new path                          | curve / scheme | old path (removed)                  |
|----------------------|-----------------------------------|----------------|-------------------------------------|
| `device_pq_key[i]`   | `m/44'/9000'/nid'/0'/i'`          | ML-DSA-65      | n/a (was loaded from disk only)     |
| `device_lux_key[i]`  | `m/44'/9000'/nid'/1'/i'`          | secp256k1      | `m/44'/9000'/0'/0/i`                |

All five levels (`44'`, `9000'`, `nid'`, branch, index) are now hardened
on the secp256k1 branch. Per-network hardening (`nid'` at the account
level) means the same mnemonic on different network ids derives fully
independent keypairs.

The ML-DSA-65 keypair is generated by expanding the 32-byte BIP-32
child seed via `SHAKE-256("LUX/HIP-0077/mldsa65" || child_seed)` into
the 32-byte ξ that FIPS 204 §5.1 KeyGen consumes. The expansion is
domain-separated so future schemes sharing the same BIP-32 child seed
cannot collide.

#### Function signature changes

```
// before
LoadKeysFromMnemonic(mnemonic string, numAccounts int) ([]KeyInfo, error)
LoadKeysFromMnemonicEnv(numAccounts int)                ([]KeyInfo, error)
BuildWalletAllocations(numKeys int, amountPerKey uint64) ([]Allocation, error)
BuildWalletKeyHex(index int)                             (string, error)

// after — every public derivation entry point now takes the network id
LoadKeysFromMnemonic(mnemonic string, nid uint32, numAccounts int) ([]KeyInfo, error)
LoadKeysFromMnemonicEnv(nid uint32, numAccounts int)                ([]KeyInfo, error)
BuildWalletAllocations(nid uint32, numKeys int, amountPerKey uint64) ([]Allocation, error)
BuildWalletKeyHex(nid uint32, index int)                             (string, error)
```

`LoadKeysFromMnemonicEnvForNetwork(networkID, numAccounts)` keeps its
signature; it now passes `networkID` through as the `nid` for the
underlying derivation, preserving the F30 public-mnemonic guard.

`KeyInfo.MLDSAPublicKey` is now populated from the deterministic
mnemonic derivation. Old loads from `nodeDir/mldsa/public.key` still
work for keys-on-disk paths (`LoadKeysFromDir`).

#### Migration

Any address derived under the old `m/44'/9000'/0'/0/i` path will NOT
reproduce under the new layout. Specifically:

- Treasury and any other addresses pinned via the mnemonic (validator
  ETH/P-chain addresses, fee reserve keys, wallet allocations) must be
  re-derived after upgrading.
- If you need to keep the old addresses spendable, export their private
  keys (`BuildWalletKeyHex` on the old code) and load them via
  `KEYS_DIR` instead of `LUX_MNEMONIC` — `LoadKeysFromDir` is unchanged.

Per CLAUDE.md `no backwards compatibility, only forwards perfection`:
this is the correct break; clients deriving from the HIP-0077 spec
agree with `luxd` going forward, and nobody is left guessing which
historical path to use.

#### Library note

ML-DSA-65 keygen currently uses `github.com/cloudflare/circl/sign/mldsa/mldsa65`
because `github.com/luxfi/crypto/pq/mldsa` (v1.17.44) does not yet
expose a public `NewKeyFromSeed` entry point. Migration is tracked by
a `TODO(canonical)` at the import site in `pkg/genesis/keys.go`; the
canonical replacement MUST adopt the same
`SHAKE-256("LUX/HIP-0077/mldsa65" || child_seed)` expansion to preserve
determinism.