Aave Proposals v3

This repository contains various proposals targeting the Aave governance. In addition to the actual proposals this repository also contains tooling to standardize certain protocol tasks. The tooling documentation is co-located with the relevant smart contracts.

Architecture

Governance Process:

1. Forum Discussion (ARFC) → Community feedback
2. Snapshot Vote → Off-chain temperature check

This repository:

3. Proposal Generation → Generate proposal files (npm run generate)
4. Payload Deployment → Deploy to target chain (e.g., Arbitrum)
5. AIP Creation → Create on-chain proposal

On-chain Governance:

6. Voting & Execution → Community vote and on-chain execution

Repository Structure

aave-proposals-v3/
├── docs/              # Documentation
├── src/               # Proposal payloads (Solidity)
│   └── YYYYMMDD_*/    # Individual proposals (date-based)
├── zksync/            # zkSync-specific code
│   └── src/           # zkSync proposal payloads
├── generator/         # TypeScript CLI tool
├── diffs/             # Protocol state diffs (before/after)
└── lib/               # Foundry dependencies

Key Components

Proposal Payloads (src/)

Smart contracts that execute protocol changes on specific chains. Payloads inherit from base classes like AaveV3PayloadEthereum, AaveV3PayloadArbitrum, etc. Each proposal is stored in a date-based directory (YYYYMMDD_<Chain>_<Title>/).

Generator (generator/)

Interactive CLI tool to bootstrap proposal files. Runs npm run generate to create .sol (payload), .t.sol (tests), .s.sol (deployment scripts), .md (AIP documentation), and config.ts (reproducibility config) files based on interactive prompts for chains, features, and parameters.

See Generator Guide for detailed usage.

Config Engine (aave-v3-origin)

The AaveV3ConfigEngine (Docs) is a helper smart contract to abstract good practices when doing "admin" interactions with the Aave v3 protocol, but built on top, without touching the core contracts.

A less comprehensive version of the engine also exists for protocol v2.

Testing Infrastructure

Foundry (Forge) with fork testing, snapshot diffing, and comprehensive validation suite. See Testing Guide for details.

Quick Start

Setup

cp .env.example .env
forge install
npm i

Test

# You can use vanilla forge to customize your test
# https://book.getfoundry.sh/reference/forge/forge-test
forge test
make test-contract filter=ProposalName

See Testing Guide for more detailed information.

Proposal Creation

Generate required files:

npm run generate

See Generator Guide for detailed usage.

To create a proposal you have to do three things:

1. deploy the payload & register it on the payloadsController
2. create an AIP
3. create the mainnet proposal

While the first two steps can be performed in parallel, the final proposal creation relies on (1) and (2). Every step can in theory be performed by a different entity.

The address creating the mainnet proposal(3) requires 80k AAVE of proposition power.

1. Deploy payload

The payload is always deployed on the chain it affects. Deployment uses Foundry Forge with Ledger support and automatic Etherscan verification.

Commands:

# Deploy with Ledger
make deploy-ledger contract=<path/to/Script.s.sol:ScriptName> chain=<chainAlias>

# Dry run (simulation)
make deploy-ledger contract=<path/to/Script.s.sol:ScriptName> chain=<chainAlias> dry=true

Generated .s.sol files contain deployment commands in comments. Chain aliases defined in foundry.toml [rpc_endpoints] section.

2. Create an AIP

The aip can be co-located with the proposal code as a markdown file. This repository will manage the upload to IPFS automatically via GitHub Actions once a PR is merged to main.

Write the AIP documentation (analysis, rationale, specification) in the generated .md file.

3. Create proposal

The proposal requires at least one payload and the encodedHash.

Requires 80k AAVE proposition power. Command from command: comment in .s.sol file:

make deploy-ledger contract=<path/to/Script.s.sol:ScriptName> chain=mainnet

Troubleshooting Verification

If Etherscan verification fails:

1. Copy verify.example.json to verify.json
2. Add ETHERSCAN_API_KEY to .env
3. Replace chain with appropriate chainId
4. Replace hash with deployment transaction hash
5. Run FOUNDRY_PROFILE=<chainAlias> forge build --force
6. Run FOUNDRY_PROFILE=<chainAlias> npx catapulta-verify -b verify.json

Related Documentation

• Generator Guide - Creating proposals step-by-step
• Testing Guide - Testing proposals
• Glossary - Repository-specific terminology
• GHO Launch Guide - Helper contracts for GHO cross-chain deployment

License

MIT - see LICENSE