Lux Standard - Smart Contract Standards

Overview

Lux Standard (github.com/luxfi/standard) is the official Solidity smart contract library for the Lux Network ecosystem. It provides production-ready contracts across 40+ modules covering token standards (LRC20/721/1155), DeFi protocols (AMM, perps, lending, liquid staking), cross-chain bridges, post-quantum cryptography precompiles, FHE (Fully Homomorphic Encryption) confidential contracts, DAO governance, Safe multisig wallets, NFT marketplaces, account abstraction, prediction markets, privacy primitives, and yield strategies. Published as @luxfi/contracts on npm.

Why

Lux Standard is the canonical contract library for building on Lux C-Chain and subnet chains (Zoo, Hanzo/AI, SPC, Pars). It provides Lux-native naming (LRC20 instead of ERC20), native bridge token support (LRC20B), post-quantum signer modules for Safe wallets, FHE-encrypted token balances and governance via T-Chain, and unified deployment scripts for all Lux ecosystem chains. Every DeFi primitive needed to build on Lux is here in one audited monorepo.

Tech Stack

Key Dependencies

When to use

• Building any token (fungible, NFT, multi-token) on Lux C-Chain or subnet chains
• Deploying DeFi protocols (AMM, lending, perpetuals, liquid staking) on Lux
• Implementing cross-chain bridges using Lux Warp messaging
• Creating DAO governance with on-chain voting and timelocks
• Building Safe multisig wallets with post-quantum signer support
• Implementing FHE-encrypted balances, votes, or private computations on T-Chain
• Deploying NFT marketplaces with bonding curve pricing (LSSVM)
• Using ERC-4337 account abstraction on Lux
• Building prediction markets, insurance, or streaming payment contracts

Hard requirements

• Foundry installed (curl -L https://foundry.paradigm.xyz | bash && foundryup)
• Node.js 18+ for Hardhat/TypeChain workflows
• Use @luxfi/contracts import paths, never @openzeppelin directly for token bases (use LRC20 not ERC20)
• All tokens must use Lux naming: LRC20, LRC721, LRC1155 (not ERC20, ERC721, ERC1155)
• Solidity ^0.8.24 minimum for new contracts (0.8.28 recommended)
• Cancun EVM target (evmVersion = "cancun" in foundry.toml)
• via-IR compilation enabled for optimizer
• Optimizer runs: 200
• Remapping: @luxfi/contracts/=contracts/ in foundry.toml
• FHE contracts require T-Chain (ThresholdVM) -- will not work on plain C-Chain
• Post-quantum precompiles (ML-DSA, FROST, etc.) require Lux-specific EVM precompile addresses
• Never use EWOQ keys
• Private keys via .env file (never committed), loaded via dotenv

Quick reference

# Clone and setup
git clone https://github.com/luxfi/standard.git && cd standard
forge install && pnpm install

# Build
forge build                          # Foundry (recommended)
pnpm build:hardhat                   # Hardhat

# Test
forge test                           # All tests
forge test -vvv                      # Verbose
forge test --gas-report              # Gas report
forge coverage                       # Coverage
pnpm test:hardhat                    # Hardhat tests

# Format / Lint
forge fmt                            # Format
forge fmt --check                    # Lint

# Deploy
anvil --chain-id 96369 &             # Start local node
forge script script/DeployFullStack.s.sol --rpc-url localhost --broadcast

# Deploy to Lux Mainnet
forge script script/DeployFullStack.s.sol --rpc-url lux --broadcast --verify

# Generate TypeChain types
pnpm typechain

# Generate ABIs
cd contracts && pnpm build:abi

# Docs
forge doc --serve

Network Configuration

Explorers

npm Package

# Install published contracts
npm install @luxfi/contracts@1.6.0

# Foundry installation
forge install luxfi/standard
# Add to remappings.txt:
# @luxfi/contracts/=lib/standard/contracts/

One-file quickstart

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;


/// @title MyToken - A simple LRC20 token on Lux
contract MyToken is LRC20 {
    constructor() LRC20("My Token", "MTK") {
        _mint(msg.sender, 1_000_000 * 10 ** 18);
    }
}

Deploy with Foundry:

# Start local node
anvil --chain-id 96369 &

# Deploy
forge create src/MyToken.sol:MyToken --rpc-url http://127.0.0.1:8545 --private-key $PRIVATE_KEY

Core Concepts

Token Standards (LRC)

Lux uses LRC (Lux Request for Comment) naming for its token standards. These are ERC-compatible but carry Lux-specific extensions.

LRC20 - Fungible Tokens

LRC721 - Non-Fungible Tokens

LRC1155 - Multi-Tokens

LRC4626 - Tokenized Vaults

Platform Tokens

FHE Contracts (Fully Homomorphic Encryption)

FHE contracts run on the Lux T-Chain (Threshold Chain) powered by ThresholdVM. They enable encrypted computation where balances, votes, and values remain confidential on-chain.

Architecture: C-Chain Contract -> FHE precompile (0x0700...0080) -> T-Chain validators -> threshold decryption callback

Encrypted Types (defined in contracts/fhe/FHE.sol):

• ebool, euint8, euint16, euint32, euint64, euint128, euint256, eaddress, einput

Precompile Addresses:

• 0x0700...0080 - FHE operations (arithmetic, comparison)
• 0x0700...0081 - ACL (allow/deny ciphertext access)
• 0x0700...0082 - Input verifier (verify encrypted inputs)
• 0x0700...0083 - Gateway (decryption requests to T-Chain)

FHE Directory Structure (contracts/fhe/):

FHE Tokens (contracts/fhe/token/):

FHE Governance (contracts/fhe/governance/):

FHE Finance (contracts/fhe/finance/):

// Example: Confidential LRC20 token

contract PrivateToken is ConfidentialLRC20 {
    constructor() ConfidentialLRC20("Private Token", "PRIV") {
        // Balances are encrypted on-chain
    }
}

Governance

Core Governance (contracts/governance/):

Voting Strategies: VoteTrackerLRC20, VotingWeightLRC20, VotingWeightVLUX

Veto System: Sanction, Veto (hierarchical freeze protection)

DAO Framework (contracts/dao/): Full LIP-7001 compliant DAO with Safe integration, Hats Protocol roles, freeze guards, freeze voting, sub-DAO hierarchy (FractalModule), account abstraction paymaster, KYC verification, public sale, autonomous admin, and countersign modules.

// Create and vote on proposals
dao.propose(targets, values, calldatas, "Upgrade treasury");
dao.castVote(proposalId, 1); // 1 = For

Bridge and Cross-Chain

Core Bridge (contracts/bridge/):

Collateral Tokens: BTC, ETH, DAI, USDC, USDT bridges

Yield-Bearing Bridge Tokens (contracts/bridge/yield/): 20+ DeFi strategies (Aave V3, Compound V3, Lido, EigenLayer, Morpho, Pendle, Curve, Convex, Ethena, Euler V2, MakerDAO, Maple, Spark, Frax, Yearn V3, Babylon, RocketPool, plus L2/Solana/TON strategies)

// Teleport tokens cross-chain
teleport.send(destChainId, recipient, token, amount);

Liquid Protocol

Master yield vault and liquid staking with xLUX shares:

L-Tokens (bridged assets): LETH, LBTC, LUSD, LSOL, LTON, LBNB, LPOL, LLUX, LADA, LZOO, LPARS, and 30+ more

LiquidLUX vault = LiquidLUX(LIQUID_LUX_ADDRESS);
// Deposit WLUX, receive xLUX shares
uint256 shares = vault.deposit(amount, msg.sender);
// Withdraw - burns xLUX, returns WLUX
uint256 assets = vault.withdraw(shares, msg.sender, msg.sender);

Post-Quantum Cryptography

EVM precompile interfaces for quantum-resistant signatures (contracts/precompile/interfaces/):

// Verify post-quantum ML-DSA signature
bool valid = IMLDSA.verify(publicKey, message, signature);

Safe (Multi-Signature Wallets)

Post-quantum-ready multisig wallets (contracts/safe/):

AMM (Automated Market Maker)

Perps (Perpetual Trading)

Leveraged perpetual futures up to 50x (contracts/perps/):

Markets (Lending)

Morpho-style isolated lending markets (contracts/markets/):

LSSVM (NFT AMM)

NFT automated market maker with bonding curves (contracts/lssvm/):

Account Abstraction (ERC-4337)

Additional Modules

AI and Compute (contracts/ai/): AIToken, AIMining, ComputeMarket

Identity / DID (contracts/did/): Registry, IdentityNFT

Staking (contracts/staking/): sLUX (staked LUX)

Treasury (contracts/treasury/): Bond, LiquidBond, ValidatorVault, FeeGov, CollateralRegistry, ProtocolLiquidity, Vault, Router, Collect, Recall

NFT (contracts/nft/): GenesisNFTs, Market

Omnichain (contracts/omnichain/): OmnichainLP, OmnichainLPFactory, OmnichainLPRouter, Bridge

Oracle (contracts/oracle/): Oracle, OracleHub, DEXSource, TWAPSource, Finder, IdentifierWhitelist, Store

Privacy (contracts/privacy/): BulletproofVerifier, Poseidon2Commitments, PrivateBridge, PrivateTeleport, ShieldedTreasury, ZNote, ZNotePQ

Prediction Markets (contracts/prediction/): Oracle, Resolver, Claims, Hub, Bridge, Relay

DTF (contracts/dtf/): ReserveDTF (diversified token fund)

Insurance (contracts/insurance/): Cover

Streaming (contracts/streaming/): Streams

Options (contracts/options/): Options

Yield Strategies (contracts/yield/): 20+ strategies (Aave V3, Compound V3, Lido, EigenLayer, Morpho, Pendle, Curve, Convex, and more)

Project Structure

standard/
  contracts/              # All Solidity source (796 files)
    package.json          # @luxfi/contracts v1.6.0 (npm package)
    tokens/               # LRC20, LRC721, LRC1155, LRC4626, platform tokens
    fhe/                  # FHE confidential contracts (T-Chain)
    governance/           # DAO, Governor, vLUX, GaugeController
    dao/                  # Full LIP-7001 DAO framework
    bridge/               # Cross-chain bridges, Teleport, yield strategies
    liquid/               # LiquidLUX vault, L-tokens, teleport
    safe/                 # Multi-sig with post-quantum signers
    precompile/           # PQ crypto precompile interfaces
    amm/                  # V2/V3 AMM, StableSwap
    perps/                # Perpetual futures
    markets/              # Morpho-style lending
    lssvm/                # NFT AMM with bonding curves
    account/              # ERC-4337 account abstraction
    ai/                   # AI token, mining, compute market
    did/                  # DID registry
    staking/              # sLUX
    treasury/             # Bonds, vaults, fee distribution
    nft/                  # Genesis NFTs, marketplace
    omnichain/            # Cross-chain LP
    oracle/               # Oracle hub, TWAP, DEX sources
    privacy/              # Bulletproofs, ZNote, Poseidon2
    prediction/           # Prediction markets
    yield/                # 20+ yield strategies
  test/                   # Foundry tests (27 test files)
    foundry/              # forge test suites
    treasury/             # Treasury-specific tests
  script/                 # Deployment scripts (Foundry)
  scripts/                # Utility scripts (TypeScript)
  lib/                    # Foundry dependencies (forge install)
  deployments/            # Deployment artifacts and addresses
  foundry.toml            # Foundry config (solc 0.8.31, via-IR, Cancun)
  hardhat.config.ts       # Hardhat config (multi-compiler, multi-network)
  remappings.txt          # Foundry import remappings
  package.json            # Root dev dependencies (private)
  Makefile                # Build/test/deploy shortcuts

Deployed Contracts (Lux Mainnet, Chain ID 96369)

As of 2026-03-04, 20 core contracts deployed and verified:

Multi-network deployments across Zoo (200200), Hanzo (36963), SPC (36911), and Pars (494949) chains.

Troubleshooting

Build fails with "stack too deep" Enable via_ir = true in foundry.toml (already default). This enables the Yul IR pipeline which handles deep stacks.

Import resolution fails in Foundry Check remappings.txt and foundry.toml remappings match. Key mapping: @luxfi/contracts/=contracts/. Run forge remappings to debug.

FHE contracts fail to deploy FHE contracts require T-Chain (ThresholdVM) with FHE precompiles at 0x0700...0080-0083. They will revert on standard C-Chain or Hardhat local network. Use MockFheOps.sol for local testing.

Hardhat compilation errors with multiple Solidity versions The hardhat.config.ts includes compilers for 0.8.28, 0.8.24, 0.8.20, and 0.7.6. If a contract specifies a pragma not matching any compiler, add the version to the compilers array.

Gas estimation fails on Lux Lux C-Chain uses Cancun EVM. Set evmVersion = "cancun" in both foundry.toml and hardhat.config.ts.

Seaport contracts fail to compile with default profile Seaport requires solc 0.8.24 without via-IR. Build with: FOUNDRY_PROFILE=seaport forge build

TypeChain types not generating Run pnpm typechain from root. Requires @typechain/ethers-v6 and @typechain/hardhat packages.

Post-quantum precompile calls revert PQ precompiles (ML-DSA, FROST, etc.) are Lux-specific EVM extensions. They do not exist on Ethereum, Hardhat, or Anvil. Test against a real Lux node or devnet.

forge test fails on certain test files The foundry.toml sets script = "contracts/script" and test = "test". If tests reference contracts in unusual paths, check that remappings cover the import.

npm publish fails The npm package is at contracts/package.json (name: @luxfi/contracts). Publish from the contracts directory: npm publish ./contracts --access public

Related Skills

• lux-fhe - Lux FHE Go library and T-Chain cryptographic foundation
• lux-fhevm - FHE VM integration for encrypted EVM execution
• lux-crypto - Post-quantum cryptography primitives
• lux-safe - Safe multisig wallet deployment and management
• lux-bridge - Cross-chain bridge operations
• lux-governance - Governance and DAO patterns
• lux-tokens - Token deployment and management
• lux-liquid - Liquid staking protocol
• lux-deploy - Deployment tooling and scripts
• lux-precompile - EVM precompile development
• lux-oracle - Oracle integration
• lux-dao - Full DAO framework

Last Updated: 2026-03-13