aave
diff --git a/‎.github/pull_request_template.md‎
Lines changed: 11 additions & 0 deletions b/‎.github/pull_request_template.md‎
Lines changed: 11 additions & 0 deletions
diff --git a/‎.github/workflows/ipfs.yml‎
Lines changed: 0 additions & 125 deletions b/‎.github/workflows/ipfs.yml‎
Lines changed: 0 additions & 125 deletions
diff --git a/‎.github/workflows/test.yml‎
Lines changed: 2 additions & 11 deletions b/‎.github/workflows/test.yml‎
Lines changed: 2 additions & 11 deletions
diff --git a/‎.gitmodules‎
Lines changed: 4 additions & 1 deletion b/‎.gitmodules‎
Lines changed: 4 additions & 1 deletion
diff --git a/‎README.md‎
Lines changed: 102 additions & 59 deletions b/‎README.md‎
Lines changed: 102 additions & 59 deletions
@@ -0,0 +1,11 @@
+### Pre-review checklist:
+
+- [ ] I have run a spell check on the write-up and made sure no typos exist.
+- [ ] References to Snapshot/governance forum are correct on the AIP. If no snapshot exists, make sure no TODO's exist.
+- [ ] The specification on the writeup is aligned with the forum, snapshot, and the payload contract. If there are any changes, they are explicitly mentioned/communicated.
+- [ ] Minimal tests exist, and the snapshot diff report generated is the latest one and aligned with the payload.
+- [ ] If deploy scripts are manually updated from the generated ones, I have carefully validated that they are correct, including the deploy commands and the proposal-creation script.
+- [ ] If the aave-helpers submodule is updated, I have validated it is pointing to the latest version.
+- [ ] I have validated that no unused files and imports are being added.
+- [ ] For an asset listing, the write-up includes a detailed specification of the price feed used, CAPO adapters (with each CAPO layer described separately), and eModes (with tables) if changed.
+- [ ] Wherever possible, I have validated that addresses from the address book are used instead of raw addresses.
@@ -37,7 +37,7 @@ jobs:
       - name: Run Foundry setup
         uses: bgd-labs/github-workflows/.github/actions/foundry-setup@main
         with:
-          ZKSYNC: "true"
+          ZKSYNC: "false"
 
       - name: Run Forge tests
         id: test
@@ -46,21 +46,12 @@ jobs:
           MODE: "CHANGED"
           FOUNDRY_PROFILE: "test"
 
-      - name: Run ZK tests
-        id: zktest
-        uses: bgd-labs/github-workflows/.github/actions/foundry-test@main
-        with:
-          MODE: "CHANGED"
-          ZKSYNC: true
-          ROOT_DIR: "zksync"
-          FOUNDRY_PROFILE: "test"
-
       - name: Create comment
         uses: bgd-labs/github-workflows/.github/actions/comment-artifact@main
 
       # we let failing tests pass so we can log them in the comment, still we want the ci to fail
       - name: Post test result
-        if: ${{ steps.test.outputs.testStatus != 0 || steps.zktest.outputs.testStatus != 0 }}
+        if: ${{ steps.test.outputs.testStatus != 0 }}
         run: |
           echo "tests failed"
           exit 1
 
@@ -1,4 +1,7 @@
 [submodule "lib/aave-helpers"]
 	path = lib/aave-helpers
-	url = https://github.com/bgd-labs/aave-helpers
+	url = git@github.com:aave-dao/aave-helpers.git
 	branch = main
+[submodule "lib/aave-umbrella"]
+	path = lib/aave-umbrella
+	url = https://github.com/aave-dao/aave-umbrella
@@ -1,82 +1,99 @@
-# Aave proposals v3
+# 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.
 
-## Tooling
+## Architecture
 
-### Config engine
+![Governance Flow](./images/governance-flow.png)
 
-The AaveV3ConfigEngine ([Docs](https://github.com/bgd-labs/aave-helpers/tree/master/src/v3-config-engine#how-to-use-the-engine)) 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.
+**Governance Process**:
 
-A less comprehensive version of the engine also exists for [protocol v2](https://github.com/bgd-labs/aave-helpers/tree/master/src/v2-config-engine).
+1. **Forum Discussion (ARFC)** → Community feedback
+2. **Snapshot Vote** → Off-chain temperature check
 
-## Development
+**This repository**:
 
-This project uses [Foundry](https://getfoundry.sh). See the [book](https://book.getfoundry.sh/getting-started/installation.html) for detailed instructions on how to install and use Foundry.
-The template ships with sensible default so you can use default `foundry` commands without resorting to `MakeFile`.
+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
 
-### Setup
+**On-chain Governance**:
 
-```sh
-cp .env.example .env
-forge install
-npm i
+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
 ```
 
-### Create an aip
+## 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>/`).
 
-This repository includes a generator to help you bootstrap the required files for an `AIP`.
-To generate a proposal you need to run: `npm run generate`
+### Generator (`generator/`)
 
-To get a full list of available commands run `npm run generate -- --help`
+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](./generator/README.md) for detailed usage.
+
+### Config Engine (`aave-v3-origin`)
+
+The AaveV3ConfigEngine ([Docs](https://github.com/aave-dao/aave-helpers/tree/master/src/v3-config-engine#how-to-use-the-engine)) 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](https://github.com/aave-dao/aave-helpers/tree/master/src/v2-config-engine).
+
+### Testing Infrastructure
+
+Foundry (Forge) with fork testing, snapshot diffing, and comprehensive validation suite. See [Testing Guide](./docs/TESTING_GUIDE.md) for details.
+
+## Quick Start
+
+### Setup
 
 ```sh
-npm run generate -- --help
-$ tsx generator/cli --help
-Usage: proposal-generator [options]
-
-CLI to generate aave proposals
-
-Options:
-  -V, --version              output the version number
-  -f, --force                force creation (might overwrite existing files)
-  -p, --pools <pools...>      (choices: "AaveV2Ethereum", "AaveV2EthereumAMM", "AaveV2Polygon", "AaveV2Avalanche",
-                             "AaveV3Ethereum", "AaveV3Polygon", "AaveV3Avalanche", "AaveV3Optimism",
-                             "AaveV3Arbitrum", "AaveV3Metis", "AaveV3Base")
-  -t, --title <string>       aip title
-  -a, --author <string>      author
-  -d, --discussion <string>  forum link
-  -s, --snapshot <string>    snapshot link
-  -c, --configFile <string>  path to config file
-  -h, --help                 display help for command
+cp .env.example .env
+forge install
+npm i
 ```
 
-If you have any feedback regarding the generator (bugs, improvements, features), don't hesitate to create an issue. We'd `<3` to see contributions.
-
 ### Test
 
 ```sh
 # You can use vanilla forge to customize your test
 # https://book.getfoundry.sh/reference/forge/forge-test
 forge test
-# We also provide a script with sensible defaults to just test a single contract matching a filter
-make test-contract filter=ENS
+make test-contract filter=ProposalName
 ```
 
-### Deploy
+See [Testing Guide](./docs/TESTING_GUIDE.md) for more detailed information.
+
+## Proposal Creation
+
+Generate required files:
 
-The makefile contains some generic templates for proposal deployments.
-To deploy a contract you can run `make deploy-ledger contract=pathToContract:Contract chain=chainAlias`.
-The generator will inline exact instructions on the generated scripts.
+```sh
+npm run generate
+```
 
-## Proposal creation
+See [Generator Guide](./generator/README.md) 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
+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).
@@ -86,29 +103,55 @@ The address creating the mainnet proposal(3) requires 80k AAVE of proposition po
 
 ### 1. Deploy payload
 
-The payload is always deployed on the chain it affects.
-Therefore you need to adjust the relevant script accordingly.
-The generated scripts include exact instrauctions on what to execute.
+The payload is always deployed on the chain it affects. Deployment uses Foundry Forge with Ledger support and automatic Etherscan verification.
+
+**Commands**:
+
+```bash
+# 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](foundry.toml) `[rpc_endpoints]` section.
 
-### 2. Create an aip
+### 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 once a pr is merged to `main`.
+This repository will manage the upload to IPFS automatically via [GitHub Actions](.github/workflows/ipfs.yml) 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`.
 
-:tada:
+Requires 80k AAVE proposition power. Command from `command:` comment in `.s.sol` file:
+
+```sh
+make deploy-ledger contract=<path/to/Script.s.sol:ScriptName> chain=mainnet
+```
 
 ## Troubleshooting Verification
 
-If for whatever reason verification fails, there's a good chance the error is on the foundry side, not in our tooling.
-To retry a specific verification you can follow the following steps:
+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](./generator/README.md) - Creating proposals step-by-step
+- [Testing Guide](./docs/TESTING_GUIDE.md) - Testing proposals
+- [Glossary](./docs/GLOSSARY.md) - Repository-specific terminology
+- [GHO Launch Guide](./src/helpers/gho-launch/README.md) - Helper contracts for GHO cross-chain deployment
+
+## License
 
-1. copy verify.example.json to verify.json
-2. enter an `ETHERSCAN_API_KEY` in your `.env`
-3. replace the `chain` with the appropriate chainId
-4. replace the `hash` with the transaction hash of the deployment transaction (make sure it's the deployment transaction, not the one registering the payload on the payloadscontroller)
-5. run `FOUNDRY_PROFILE=<chainAlias> forge build --force`
-6. run `FOUNDRY_PROFILE=<chainAlias> npx catapulta-verify -b verify.json`
+MIT - see [LICENSE](./LICENSE)