docs: migration guide (aave-dao#52)

Makefile

@@ -35,4 +35,6 @@ coverage :; forge coverage --report lcov && \
 download :; cast etherscan-source --chain ${chain} -d src/etherscan/${chain}_${address} ${address}
 git-diff :
 	@mkdir -p diffs
-	@printf '%s\n%s\n%s\n' "\`\`\`diff" "$$(git diff --no-index --diff-algorithm=patience --ignore-space-at-eol ${before} ${after})" "\`\`\`" > diffs/${out}.md
+	@npx prettier --parser markdown ${before} ${after} --write
+	@printf '%s\n%s\n%s\n' "\`\`\`diff" "$$(git diff --no-index --ignore-space-at-eol ${before} ${after})" "\`\`\`" > diffs/${out}.md
+git-word-diff :; git diff --no-index --word-diff -- ${before} ${after} | tail +6  | sed 's/\[-/\~~/g;s/-]/\~~ /g;' | sed 's/{+/\**/g;s/+}/\**/g;' > diffs/${out}.md

changelog/3.2.md

@@ -0,0 +1,102 @@
+# Aave 3.2
+
+Aave 3.2 focuses on two main areas of the aave protocol:
+
+- the final deprecation of stable borrowing
+- improvements on the eModes
+
+## Stable Rate offboarding
+
+While previous upgrades allowed graceful offboarding of stable borrowing, now with no stable borrow positions being left the protcol can remove all the now obsolete stable rate related logic.
+
+### Migration guide
+
+The upgrade is 100% backwards compatible.
+There are no changes to any methods, nor are there changes to emitted events.
+Parameters emitted in events that relate to stable rate are nulled.
+
+## Emodes: Removal of the eMode oracle
+
+The eMode oracle has never been used and it's usefulnes is debatable.
+Therefore to allow for storage optimization within the eMode configuration and reduce unnecessary code paths - the eMode oracle was removed.
+
+#### Indexers
+
+For backwards compatibility the existing `EModeCategoryAdded` will be emitted, but with `oracle` being nullified.
+
+## Emodes: Liquid eModes
+
+The new Liquid eMode feature of Aave v3.2 removes the previous constraint: **an asset listed on Aave can be eligible for different eModes, and then it only depends on the user to choose which eMode he wants to enter to.**
+
+For example, with liquid eModes, a possible configuration not doable before would be:
+
+- eMode 1, with wstETH, weETH and WETH.
+- eMode 2, with wstETH and WETH.
+- eMode 3, with weETH and WETH.
+- eMode 4, with WETH and GHO.
+
+So then, user A holding the wstETH and weETH collaterals, could borrow WETH at high LTV.
+User B holding only wstETH could borrow WETH at high (but different) LTV.
+User C holding only weETH could similarly borrow WETH at a different LTV than the previous two eModes.
+User D could have a position with WETH collateral and GHO borrowings.
+
+This doesn’t stop there, as more sophisticated configuration strategies could be adopted, like:
+
+- eMode for only WETH and stablecoins.
+- eMode for onboarding less mature LSTs, without requiring them being together with all major LSTs.
+
+**For extra configuration flexibility, liquid eModes also allow now to flag an asset as only borrowable, only collateral, or both, in the context of an eMode.**
+For example, in a hypothetic eMode with only wstETH and WETH, the normal configuration would be wstETH as only collateral and WETH as only borrowable, fully focusing on the wstETH leverage use-case.
+
+### BREAKING CHANGES
+
+- DataTypes.EModeCategory will return the same data as now, but is flagged deprecated and will be removed at a later point.
+
+- the new version of `PoolDataProvider` no longer exposes `PoolDataProvider.getReserveEModeCategory(address asset)` as there no longer is a `1:1` relation between assets and eModes.
+- `reserveConfig.getEModeCategory()` will return the current eMode, but will no longer be updated and is flagged deprecated.
+
+### Migration guide
+
+For existing users, the upgrade is 100% backwards compatible and no migration or similar is required.
+Entering and leaving an eMode still works via `setUserEMode(categoryId)` and `getUserEMode(address user)` like in previous versions of the protocol.
+
+#### Indexers
+
+As collateral/borrowable flags are newly introduced, two new events are being emitted:
+
+- `event AssetCollateralInEModeChanged(address indexed asset, uint8 categoryId, bool collateral);`
+- `event AssetBorrowableInEModeChanged(address indexed asset, uint8 categoryId, bool borrowable);`
+
+#### Getters
+
+In aave 3.1 all eMode parameters were exposed via a single `getEModeCategoryData` getter.
+When checking existing integrations, we noticed that in most cases this approach is suboptimal, given that users only rely on a subset of the data.
+Therefore in addition to the **deprecated** `getEModeCategoryData` getter there are now independent getters for the respective values:
+
+- `getEModeCategoryCollateralConfig(categoryId)`, returning the eMode ltv,lt,lb
+- `getEModeCategoryLabel(categoryId)`, returning the eMode label
+- `getEModeCategoryCollateralBitmap(categoryId)`, returning the collateral bitmap
+- `getEModeCategoryBorrowableBitmap(categoryId)`, returning the borrowable bitmap
+
+#### Identifying eModes for an asset
+
+In the previous version of the eModes feature it was possible to query a reserve configration to receive it's unique eMode.
+The relevant bits on the reseve configuration have been nullified.
+
+To identify eModes of a selected asset, there is currently multiple options:
+
+- onchain one can iterate trough eModes and select the "correct one" based on your application specific needs.
+
+```sol
+for (uint8 i = 1; i < 256; i++) {
+    DataTypes.CollateralConfig memory cfg = pool.getEModeCategoryCollateralConfig(i);
+    // check if it is an active eMode
+    if (cfg.liquidationThreshold != 0) {
+        // check if it's an eMode you are interested in
+        EModeConfiguration.isCollateralAsset(pool.getEModeCategoryCollateralBitmap(i), someReserveIndex);
+        EModeConfiguration.isBorrowableAsset(pool.getEModeCategoryBorrowableBitmap(i), someReserveIndex);
+    }
+}
+```
+
+- an offchain system could listen to `AssetCollateralInEModeChanged` & `AssetBorrowableInEModeChanged` events and feed the onchain contract with an appropriate categoryId