pankajjagtapp · Sep 24, 2026 · Sep 23, 2026 · Sep 23, 2026 · Sep 23, 2026 · Sep 23, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -1,4 +1,4 @@
-# EtherFi Smart Contracts
+# ether.fi's Liquid Staking Protocol Contracts
 
 ## Build & Test
 
@@ -14,20 +14,26 @@ forge test --match-test <name> --fork-url $MAINNET_RPC_URL  # mainnet fork tests
 ## Project Layout
 
 ```
-src/                    # Core contracts
-  EtherFiNode.sol       # Per-validator-group contract, owns an EigenPod
-  EtherFiNodesManager.sol # Entry point for pod operations (0x8B71...6F)
-  LiquidityPool.sol     # Main ETH pool (0x3088...16)
-  EtherFiRestaker.sol   # Manages stETH restaking via EigenLayer (0x1B7a...Ff)
-  EtherFiRedemptionManager.sol # Instant redemptions with rate limiting (0xDadE...e0)
-  StakingManager.sol    # Validator lifecycle
-  WeETH.sol / EETH.sol  # Token contracts
-  eigenlayer-interfaces/ # EigenLayer interface definitions (no implementations)
+src/
+  core/                 # LiquidityPool (0x3088...16), EETH, WeETH
+  staking/              # StakingManager, EtherFiNodesManager (0x8B71...6F), EtherFiNode, AuctionManager
+  restaking/            # EtherFiRestaker (0x1B7a...Ff): stETH restaking via EigenLayer
+  deposits/             # DepositAdapter, Liquifier, LiquidRefer
+  withdrawals/          # WithdrawRequestNFT, PriorityWithdrawalQueue,
+                        # EtherFiRedemptionManager (0xDadE...e0), WeETHWithdrawAdapter
+  oracle/               # EtherFiOracle, EtherFiAdmin
+  rewards/              # EtherFiRewardsRouter, CumulativeMerkleRewardsDistributor
+  governance/           # RoleRegistry, EtherFiTimelock, Blacklister, rate-limiting/
+  helpers/              # AddressProvider, EtherFiViewer
+  interfaces/eigenlayer-interfaces/ # EigenLayer interface definitions (no implementations)
+  archive/              # Retired contracts kept for storage-layout reference
 test/
   TestSetup.sol         # Base test with initializeRealisticFork() / initializeTestingFork()
+  invariant/            # Stateful invariant fuzzing
   behaviour-tests/      # PreludeTest - validator lifecycle on mainnet fork
   integration-tests/    # Cross-contract integration tests on mainnet fork
   fork-tests/           # Additional fork-based tests
+certora/                # specs/ and config/ for formal verification
 script/
   operations/           # Operational tooling (Python + Solidity for Gnosis Safe txns)
   deploys/Deployed.s.sol # All mainnet deployed addresses as constants

diff --git a/README.md b/README.md
@@ -1,54 +1,120 @@
-# ether.fi Liquid Restaking Protocol
+# ether.fi's Liquid Staking Protocol Contracts
 
+Solidity contracts behind ether.fi's liquid staking on Ethereum mainnet. Users deposit ETH
+into the `LiquidityPool` and receive eETH, a rebasing token, or its non-rebasing wrapper weETH.
+The protocol runs validators whose withdrawal credentials point at EigenLayer EigenPods.
 
+[Docs](https://etherfi.gitbook.io/etherfi/) ·
+[Audits](audits/) ·
+[Deployed addresses](https://etherfi.gitbook.io/etherfi/developers/contracts-and-integrations/deployed-contracts) ·
+[weETH cross-chain](https://github.com/etherfi-protocol/weETH-cross-chain/)
 
-## Overview
+## Contracts
 
-The ether.fi Liquid Restaking Protocol represents the core infrastructure powering ether.fi's vision of becoming the most secure and efficient liquid staking solution in DeFi. This protocol enables:
+| Module | Path | Contracts |
+|--------|------|-----------|
+| Core | `src/core` | `LiquidityPool`, `EETH`, `WeETH` |
+| Staking | `src/staking` | `StakingManager`, `EtherFiNodesManager`, `EtherFiNode`, `AuctionManager`, `NodeOperatorManager` |
+| Restaking | `src/restaking` | `EtherFiRestaker`, `RestakingRewardsRouter` |
+| Deposits | `src/deposits` | `DepositAdapter`, `Liquifier`, `LiquidRefer` |
+| Withdrawals | `src/withdrawals` | `WithdrawRequestNFT`, `PriorityWithdrawalQueue`, `EtherFiRedemptionManager`, `WeETHWithdrawAdapter` |
+| Oracle | `src/oracle` | `EtherFiOracle`, `EtherFiAdmin` |
+| Rewards | `src/rewards` | `EtherFiRewardsRouter`, `CumulativeMerkleRewardsDistributor` |
+| Governance | `src/governance` | `RoleRegistry`, `EtherFiTimelock`, `Blacklister`, `RevokeAdmin`, rate limiting |
+| Helpers | `src/helpers` | `AddressProvider`, `EtherFiViewer` |
 
-- **Liquid Staking**: Seamless ETH staking with immediate liquidity through eETH
-- **Native Restaking**: Effortless & Secure restaking of staked ETH. Restaking & AVS management is strictly controlled by the Protocol via ether.fi's AVS operator contracts ([link](https://github.com/etherfi-protocol/etherfi-avs-operator)). Restaking rewards are distributed via KING ([link](https://github.com/orgs/King-Protocol/repositories))
-- **Massive Integration with DeFi**: Wide integration with DeFi protocols
-- **Cross-Chain Capabilities**: Native support for cross-chain staking & bridging of weETH ([link](https://github.com/etherfi-protocol/weETH-cross-chain/))
-- **Enterprise-Grade Security**: Rigorous security measures through audits, formal verification, and continuous monitoring
+`src/archive` holds retired contracts kept for storage-layout reference.
 
+Contract addresses live in the ether.fi docs under
+[Deployed Contracts](https://etherfi.gitbook.io/etherfi/developers/contracts-and-integrations/deployed-contracts).
 
-## 🔒 Security
+## Architecture
 
-Security is paramount at ether.fi. Our protocol undergoes:
+- Every contract sits behind a UUPS proxy. Upgrades go through the upgrade timelock; parameter
+  changes go through the operating timelock.
+- `RoleRegistry` owns all role checks. Contracts ask it before running privileged functions.
+- Each `EtherFiNode` owns one EigenPod. `EtherFiNodesManager` is the entry point for pod
+  operations: checkpoints, withdrawals, consolidations, and exits.
+- `EtherFiOracle` reports rewards and validator state. `EtherFiAdmin` applies those reports to
+  the `LiquidityPool` rebase and finalizes withdrawal requests.
+- `EtherFiRedemptionManager` handles instant redemptions under a bucket rate limiter.
+  `WithdrawRequestNFT` and `PriorityWithdrawalQueue` handle queued withdrawals.
 
-- Regular & Continuous audits by industry leaders
-- Formal verification through Certora
-- Continuous monitoring and testing
+## Getting started
 
+Requirements: [Foundry](https://book.getfoundry.sh/getting-started/installation) (CI pins
+v1.5.1) and a mainnet RPC URL for fork tests.
 
+```bash
+git clone https://github.com/etherfi-protocol/smart-contracts.git
+cd smart-contracts
+git submodule update --init --recursive
+forge build
+```
 
-## 🛠️ Development Setup
+The build uses Solidity 0.8.27 with 1500 optimizer runs.
 
+### Tests
 
 ```bash
-# Install & Setup
-curl -L https://foundry.paradigm.xyz | bash
-git clone https://github.com/etherfi-protocol/smart-contracts.git && cd smart-contracts
-git submodule update --init --recursive
-forge build
+export MAINNET_RPC_URL=<your_rpc_url>
+
+forge test                                   # all tests
+forge test --match-test <name>               # one test
+forge test --match-path "test/invariant/*"   # invariant suite
+forge test --match-path "test/fork-tests/*" --fork-url $MAINNET_RPC_URL
+```
 
-# Testing
-forge test                                    # Run all tests
-forge test --fork-url <your_rpc_url>         # Fork testing
-certoraRun certora/conf/<contract-name>.conf # Formal verification
+| Directory | Contents |
+|-----------|----------|
+| `test/*.t.sol` | Unit tests per contract |
+| `test/invariant` | Stateful invariant fuzzing |
+| `test/integration-tests` | Cross-contract flows on a mainnet fork |
+| `test/fork-tests` | Upgrade and migration checks against live state |
+| `test/behaviour-tests` | Validator lifecycle on a mainnet fork |
+
+Fork tests run against the latest block, so assert deltas against the live state you read at
+setup instead of assuming zero balances.
+
+### Formal verification
+
+Certora specs live in `certora/specs` with run configs in `certora/config`:
+
+```bash
+certoraRun certora/config/LiquidityPoolPeg.conf
 ```
 
-## 📚 Documentation
+Configs cover `LiquidityPool` peg and share accounting, `EtherFiOracle`, and `RoleRegistry`
+authority.
+
+## Repository layout
+
+| Path | Purpose |
+|------|---------|
+| `src/` | Protocol contracts |
+| `test/` | Foundry tests |
+| `certora/` | Formal verification specs and configs |
+| `script/` | Deploy, upgrade, and operations scripts (Solidity and Python) |
+| `operations/`, `proposals/` | Gnosis Safe and timelock transaction batches |
+| `deployment/`, `release/` | Deployment artifacts and release records |
+| `audits/` | Audit reports |
+
+## Security
 
-- [Protocol Documentation](https://etherfi.gitbook.io/etherfi/)
+Certora, Zellic, Nethermind, Halborn, Omniscia, Decurity, Solidified, Paladin, CertiK, and
+Hats Finance have audited these contracts. Reports sit in [`audits/`](audits/); the most
+recent is the Certora 26Q2 Security Upgrade review (June 2026).
 
+CI runs the Forge test suite and a storage-layout check on pull requests into `master`, which
+catches upgrades that would shift proxy storage.
 
+Report vulnerabilities through the ether.fi bug bounty program. Do not open public issues for
+security bugs.
 
 ## 📄 License
 
 ether.fi is open-source and licensed under the [MIT License](LICENSE).
 
 ---
 
-<p align="center">Built with ❤️ by the ether.fi team</p>
+<p align="center">Built with ❤️ by the ether.fi team</p>
diff --git a/docs/book.css b/docs/book.css
diff --git a/docs/book.toml b/docs/book.toml
diff --git a/docs/solidity.min.js b/docs/solidity.min.js