docs: update README (#981)

Author: yan-man

.env.example

@@ -1,10 +1,3 @@
-# Deployment via ledger
-MNEMONIC_INDEX=
-LEDGER_SENDER=
-
-# Deployment via private key
-PRIVATE_KEY=
-
 # Test rpc_endpoints
 RPC_MAINNET=https://eth.llamarpc.com
 RPC_AVALANCHE=https://api.avax.network/ext/bc/C/rpc

README.md

@@ -1,24 +1,151 @@
 # Aave V4
 
+[![codecov](https://codecov.io/gh/aave/aave-v4/graph/badge.svg?token=afC1P2GrDM)](https://codecov.io/gh/aave/aave-v4)
+
+A unified liquidity layer and modular architecture that enhances capital efficiency, scalability, and risk management.
+
+## Table of Contents
+
+- [Documentation](#documentation)
+- [Architecture](#architecture)
+- [Repository Structure](#repository-structure)
+- [Dependencies](#dependencies)
+- [Development](#development)
+- [Security](#security)
+
+## Documentation
+
+- [Aave V4 Overview](./docs/overview.md)
+
+## Architecture
+
+The Aave V4 architecture follows a modular **hub-and-spoke design** that separates liquidity management from user-facing operations and collateralization.
+
+## Repository Structure
+
+```
+aave-v4/
+├── src/                          # Main source code
+│   ├── hub/                      # Hub contracts and interfaces
+│   ├── spoke/                    # Spoke contracts and interfaces
+│   ├── position-manager/         # Position Managers, including gateway contracts
+│   ├── libraries/                # Shared libraries (math, types)
+│   ├── utils/                    # Utility contracts (Multicall, etc.)
+│   └── dependencies/             # Dependencies (Chainlink, OpenZeppelin, etc.)
+├── tests/                        # Test suite
+│   ├── unit/                     # Unit tests
+│   ├── gas/                      # Gas snapshot tests
+│   ├── invariant/                # Invariant tests
+│   ├── misc/                     # Symbolic tests, prototype development
+│   └── Base.t.sol                # Base test setup
+├── scripts/                      # Deployment scripts
+├── snapshots/                    # Gas snapshots
+└── lib/                          # Foundry dependencies
+```
+
 ## Dependencies
 
-- Foundry, [how-to install](https://book.getfoundry.sh/getting-started/installation) (we recommend also update to the last version with `foundryup`)
-- Node, [how-to install](https://nodejs.org/en/download)
-- Lcov
-  - Optional, only needed for coverage testing
-  - For Ubuntu, you can install via `apt install lcov`
-  - For Mac, you can install via `brew install lcov`
+### Required
+
+- **[Foundry](https://book.getfoundry.sh/getting-started/installation)** - Development framework
+  ```bash
+  curl -L https://foundry.paradigm.xyz | bash
+  foundryup  # Update to latest version
+  ```
+- **[Node.js](https://nodejs.org/en/download)** - For linting and tooling
+
+  ```bash
+  # Verify installation
+  node --version
+  yarn --version
+  # Install dependencies
+  yarn install
+  ```
+
+### Optional
+
+- **Lcov** - For coverage reports
+
+  ```bash
+  # Ubuntu
+  sudo apt install lcov
+
+  # macOS
+  brew install lcov
+  ```
+
+### Dependency Strategy
+
+Dependencies are located in the `src/dependencies` subfolder rather than managed through external package managers. This approach:
+
+- Mitigates supply chain attack vectors
+- Ensures dependency immutability
+- Minimizes installation overhead
+- Provides simplified version control and auditability
 
-## Setup
+## Quickstart
 
-```sh
+### 1. Clone the Repository
+
+```bash
+git clone https://github.com/aave/aave-v4.git
+cd aave-v4
+```
+
+### 2. Install Dependencies
+
+```bash
+# Copy environment template and populate
 cp .env.example .env
+
+# Install Foundry dependencies
 forge install
-# required for linting
+
+# Install Node.js dependencies (required for linting)
 yarn install
 ```
 
-## Tests
+### 3. Build Contracts
+
+```bash
+forge build
+```
+
+## Development
+
+### Testing
+
+- **Run full test suite**: `make test` or `forge test -vvv`
+- **Run specific test file**: `forge test --match-contract ...`
+- **Run with gas reporting**: `make gas-report`
+- **Generate coverage report**: `make coverage`
+
+### Code Quality
+
+- **Check contract sizes**: `forge build --sizes`
+- **Check linting**: `yarn lint`
+- **Fix linting issues**: `yarn lint:fix`
+- **Generate Rust bindings**: `yarn rs:generate`
+
+### Gas Snapshots
+
+Gas snapshots are automatically generated and stored in the `snapshots/` directory. To update snapshots:
+
+```bash
+make gas-report
+```
+
+Snapshot files generated:
+
+- `Hub.Operations.json`: Gas for Hub actions or treasury operations invoked by Spokes.
+- `Spoke.Operations.json`: Gas for user-facing Spoke operations.
+- `Spoke.Operations.ZeroRiskPremium.json`: Same scenarios as `Spoke.Operations.json` but with Collateral Risk set to 0, to show baseline gas excluding risk-premium computation.
+- `Spoke.Getters.json`: Gas for getters across different combinations of supplies/borrows.
+- `NativeTokenGateway.Operations.json`: Gas for native-asset (ETH) gateway flows.
+- `SignatureGateway.Operations.json`: Gas for EIP-712 meta-transactions.
+
+## Security
 
-- To run the full test suite: `make test`
-- To re-generate the coverage report: `make coverage`
+- **Audit Reports**: [TBD]
+- **Security Policy**: [TBD]
+- **Bug Bounty**: [TBD]

deploy.sh

@@ -1,7 +1,6 @@
 [profile.default]
 src = 'src'
 test = 'tests'
-script = 'scripts'
 out = 'out'
 libs = ['lib']
 fs_permissions = [{ access = "read", path = "tests/mocks/JsonBindings.sol" }]

foundry.toml

@@ -1,6 +1,6 @@
 {
   "name": "aave-v4",
-  "version": "1.0.0",
+  "version": "0.5.3",
   "scripts": {
     "lint": "prettier . --check",
     "lint:fix": "prettier . --write",
@@ -11,6 +11,11 @@
   },
   "keywords": [],
   "author": "Aave Labs",
+  "license": "UNLICENSED",
+  "bugs": {
+    "url": "https://github.com/aave/aave-v4/issues"
+  },
+  "homepage": "https://github.com/aave/aave-v4#readme",
   "devDependencies": {
     "husky": "9.1.7",
     "lint-staged": "16.2.3",

package.json

@@ -11,7 +11,10 @@ import {console2 as console} from 'forge-std/console2.sol';
 
 // dependencies
 import {AggregatorV3Interface} from 'src/dependencies/chainlink/AggregatorV3Interface.sol';
-import {TransparentUpgradeableProxy, ITransparentUpgradeableProxy} from 'src/dependencies/openzeppelin/TransparentUpgradeableProxy.sol';
+import {
+  TransparentUpgradeableProxy,
+  ITransparentUpgradeableProxy
+} from 'src/dependencies/openzeppelin/TransparentUpgradeableProxy.sol';
 import {IERC20Metadata} from 'src/dependencies/openzeppelin/IERC20Metadata.sol';
 import {SafeCast} from 'src/dependencies/openzeppelin/SafeCast.sol';
 import {IERC20Errors} from 'src/dependencies/openzeppelin/IERC20Errors.sol';
@@ -44,7 +47,11 @@ import {UnitPriceFeed} from 'src/misc/UnitPriceFeed.sol';
 import {HubConfigurator, IHubConfigurator} from 'src/hub/HubConfigurator.sol';
 import {Hub, IHub, IHubBase} from 'src/hub/Hub.sol';
 import {SharesMath} from 'src/hub/libraries/SharesMath.sol';
-import {AssetInterestRateStrategy, IAssetInterestRateStrategy, IBasicInterestRateStrategy} from 'src/hub/AssetInterestRateStrategy.sol';
+import {
+  AssetInterestRateStrategy,
+  IAssetInterestRateStrategy,
+  IBasicInterestRateStrategy
+} from 'src/hub/AssetInterestRateStrategy.sol';
 
 // spoke
 import {Spoke, ISpoke, ISpokeBase} from 'src/spoke/Spoke.sol';
@@ -74,7 +81,7 @@ import {MockPriceFeed} from 'tests/mocks/MockPriceFeed.sol';
 import {PositionStatusMapWrapper} from 'tests/mocks/PositionStatusMapWrapper.sol';
 import {RescuableWrapper} from 'tests/mocks/RescuableWrapper.sol';
 import {GatewayBaseWrapper} from 'tests/mocks/GatewayBaseWrapper.sol';
-import {NoncesKeyedMock} from 'tests/mocks/NoncesKeyedMock.sol';
+import {MockNoncesKeyed} from 'tests/mocks/MockNoncesKeyed.sol';
 import {MockSpoke} from 'tests/mocks/MockSpoke.sol';
 import {MockERC1271Wallet} from 'tests/mocks/MockERC1271Wallet.sol';
 import {MockSpokeInstance} from 'tests/mocks/MockSpokeInstance.sol';