Security
Key storage best practices
Wallet security is critical. A compromised key means permanent loss of funds.
Best Practices
- Never store mnemonics in plaintext -- Use encrypted storage or a hardware wallet
- Use hardware wallets for production -- Ledger devices keep keys offline
- Derive fresh addresses for each transaction -- Reduces exposure from address reuse
- Back up key material to KMS -- Use Lux KMS for encrypted backup
- Set file permissions -- Key files should be
0600(owner read/write only) - Use environment variables carefully --
LUX_MNEMONICandLUX_PRIVATE_KEYare convenient but visible in process listings
Key Storage Hierarchy
| Method | Security Level | Use Case |
|---|---|---|
| Hardware wallet (Ledger) | Highest | Production funds, validators |
| KMS-encrypted storage | High | Server-side automation |
CLI key management (lux key) | Medium | Development, testing |
| Environment variables | Low | CI/CD, scripts |
| Plaintext files | Unacceptable | Never |
Mnemonic Security
The BIP-39 mnemonic is the root of all derived keys. Losing or exposing it compromises everything:
- Write it on paper and store in a safe
- Never photograph or screenshot it
- Never send it over network (email, chat, etc.)
- Never commit it to git
- Consider using Shamir Secret Sharing to split across multiple locations
Validator Key Security
Validator staking keys have additional requirements:
| Key | File | Protection |
|---|---|---|
| TLS (staker.crt/key) | ~/.lux/keys/<name>/staking/ | Determines NodeID, cannot be changed |
| BLS (signer.key) | ~/.lux/keys/<name>/bls/ | Consensus participation, must match genesis |
| EC (secp256k1) | ~/.lux/keys/<name>/ec/ | Transaction signing |
Password Requirements
When using the CLI's encrypted key storage:
- Minimum 12 characters
- Passwords are hashed with Argon2 before use as encryption keys
- Key material is encrypted with AES-256-GCM at rest
MPC & Threshold Custody
For institutional and bridge custody, a key need never exist in one place. Lux custody is decomplected: one optional MPC custody module, plus an optional TEE custody extension, composed over a shared attestation verifier.
| Module | Tag | Role |
|---|---|---|
luxfi/mpc | v1.16.0 | Threshold MPC custody — CGGMP21 (secp256k1 ECDSA) and FROST (Schnorr / ed25519). t-of-n signing, DKG, resharing, refresh, and a policy engine. |
luxfi/tee | v0.1.0 | Optional TEE-backed threshold-signing custody extension (attested enclave). One-way dependency on the signing kernels; not required by the threshold core. |
luxfi/cc | v0.2.0 | One attestation verifier (six production CPU/GPU vendors: AMD SEV-SNP, Intel TDX, Intel SGX, NVIDIA nvtrust, AWS Nitro, ARM CCA) the custody modules call before releasing a key share into hardware. See Confidential Compute. |
The optional extension model: luxfi/mpc (MPC custody) and luxfi/tee (TEE
custody) are add-ons. The post-quantum consensus core depends on neither —
the permissionless chain runs dealerless without a TEE. Operators opt into MPC
or TEE custody for institutional key management; it is never a trust assumption
baked into the open validator set.
Policy engine
luxfi/mpc ships a Fireblocks/Utila-style policy engine for MPC wallets —
per-transaction rules (amount caps, allow-lists, approval quorums) gate every
signing request before the threshold ceremony runs. This is the in-house custody
policy layer; external custodian co-signing (Utila / Fireblocks / regulated
custodians) layers on top via the bridge cosigner flow.