Illuvium Staking V3

Overview

Illuvium Staking V3 lets you stake ILV or ILV/WETH LP on Base and earn rewards. It’s upgradeable, battle‑tested, and simple. It also includes a StakingVaultFactory to deploy vault proxies consistently.

Features

• Stake ILV or LP: Two dedicated vaults
• Flexible locks: Choose a lock duration within configured bounds
• Upgrade friendly: UUPS proxies for future upgrades
• StakingVaultFactory (deprecated): Deploy vault proxies with a consistent setup (not used on mainnet/testnet)
• Automated distributions: Rewards flow via a distributor contract
• Safety first: Reentrancy guards, SafeERC20, and role‑based access

What’s inside

src/
├── Constants.sol
├── L2RevenueDistributorV3.sol
├── StakingVault.sol               # Vault implementation (UUPS)
├── StakingVaultFactory.sol        # Factory for vault proxies (deprecated; not used on mainnet/testnet)
└── interfaces/
    ├── IAerodromeFactory.sol
    ├── IAerodromePair.sol
    ├── IAerodromeRouter.sol
    └── IStakingVaultMinimal.sol   # Minimal vault interface for integrations

script/
├── Deployer.s.sol                 # Deploys impls + proxies, wires pools
└── HelperConfig.s.sol             # Network config, env overrides, mocks

test/
├── Base.t.sol
├── L2RevenueDistributorV3.t.sol
├── StakingVault.t.sol
├── StakingVaultFactory.t.sol
├── invariants/
│   ├── Properties.sol
│   ├── Setup.sol
│   ├── SystemCryticTester.sol
│   ├── SystemCryticToFoundry.t.sol
│   ├── TargetFunctions.sol
│   └── actors/
│       └── VaultUser.sol
└── utils/
    ├── MockAerodrome.sol
    └── MockERC20.sol

Quick start

git clone https://github.com/illuvium/staking-contracts-v3.git
cd staking-contracts-v3
forge install
forge build
forge test -vvv

Local deploy (optional)

anvil --fork-url $BASE_RPC_URL
forge script script/Deployer.s.sol \
  --rpc-url http://localhost:8545 \
  --sig "run(uint8)" 0 \
  --broadcast

Testing

Most flows are covered with straightforward unit tests. Run everything or target a file/test:

forge test -vvv
forge test --match-path test/StakingVault.t.sol -vvv
forge test --match-test testFuzz_Deposit_Succeeds_WhenValidParams -vvv

Invariants (Chimera-style) and property testing:

# All invariants
forge test --match-path test/invariants/** -vvv

# Deeper invariant exploration
forge test --match-path test/invariants/** --invariant-depth 128 -vvv

# (Optional) Echidna
echidna . --config echidna.yaml

Deployment

Set a few env vars, load your Foundry keystore, then run the deploy script against your network.

# Import or create a Foundry keystore entry (only once)
cast wallet import my-deployer --interactive
cast wallet list

# Export deployment context
export ADMIN=0x...
export OPERATOR=0x...
export L1_POOL_ADMIN=0x...
export DEPLOYER_ACCOUNT=my-deployer        # alias from cast wallet list
export DEPLOYER_SENDER=0x...               # address tied to the alias

# Testnet example (Base Sepolia)
forge script script/Deployer.s.sol \
  --rpc-url $BASE_SEPOLIA_RPC \
  --account $DEPLOYER_ACCOUNT \
  --sender $DEPLOYER_SENDER \
  --sig "run(uint8)" 1 \
  --broadcast --verify

# Mainnet example (Base)
forge script script/Deployer.s.sol \
  --rpc-url $BASE_RPC_URL \
  --account $DEPLOYER_ACCOUNT \
  --sender $DEPLOYER_SENDER \
  --sig "run(uint8)" 2 \
  --broadcast --verify --slow

November 2025 Base mainnet deployment

• ILV vault and distributor: Deployed on Base mainnet in November 2025 via script/Deployer.s.sol.
• LP vault and Aerodrome pool: LP vault 0xAcF7b71620008eF01e001BeaF639Ec060f9193DA uses LP token 0x5747e944eed9Bf2b6fbD14Df44211bAdbA36ce84 for the Aerodrome ILV/WETH pool.

Contract addresses

Base Mainnet (8453)

Contract	Address	Implementation
StakingVault (ILV)	0x88b5B7d27e5aE0926D31b0C9bc3516376C028cC8	0xB10ea2EeA6C0dbe2db76Fd7E09951753f2F0690B
StakingVault (LP)	0xAcF7b71620008eF01e001BeaF639Ec060f9193DA	0xB10ea2EeA6C0dbe2db76Fd7E09951753f2F0690B
L2RevenueDistributorV3	0xdd5ac0f8Bc0ad15dEAf17903F50E8c356aEcBBc2
StakingVaultFactory (deprecated)	TBD	TBD

Base Sepolia (84532)

Contract	Address	Implementation
StakingVault (ILV)	TBD	TBD
StakingVault (LP)	TBD	TBD
L2RevenueDistributorV3	TBD	TBD
StakingVaultFactory (deprecated)	TBD	TBD

License

MIT — see LICENSE.

---

Built with Foundry • Integrates with Aerodrome • Deployed on Base