docs: add readme

README.md

@@ -1,24 +1,68 @@
-# BGD forge template
+# Aave StkABPTV1 -> Aave StkABPTV2 migration
 
-Basic template with prettier and rest configuration
+## About this repository
 
-To create a new project using this template run
+This repository consists out of 4 independent contracts:
 
-```shell
-$ forge init --template bgd-labs/bgd-forge-template my_new_project
-```
+### 1. [BalancerSharedPoolPriceProvider](./src/contracts/BalancerSharedPoolPriceProvider.sol)
+
+The `BalancerSharedPoolPriceProvider` is a price provider for balancer v1 pools.
+The price provider will return the price as arithmetic mean when the pool is in equilibrium and as weighted geometric mean when the pool is imbalanced. This calculation helps to determine a manipulation resistant fair market price.
+This price provider will provide the price for abpt shares determined in USD, based on the AaveOracle prices and is intended to be used to determine the fair market value of a users shares.
+
+### 2. [BalancerV2SharedPoolPriceProvider](./src/contracts/BalancerV2SharedPoolPriceProvider.sol)
+
+The `BalancerV2SharedPoolPriceProvider` is a price provider for balancer v2 pools.
+The price calculation is analog to `BalancerSharedPoolPriceProvider`.
+
+### 3. [StkABPTMigrator](./src/contracts/StkABPTMigrator.sol)
 
-## Recommended modules
+The `StkABPTMigrator` is a migration contract that allows migrating stkABPT to stkABPTv2.
+The contract offers a `migrateStkABPT` and a `migrateStkABPTWithPermit` external function that allows migrating funds within the safety module.
 
-[bgd-labs/solidity-utils](https://github.com/bgd-labs/solidity-utils) - common contracts we use everywhere, ie transparent proxy and around
+The contract call will:
+1. pull funds from stkABPT
+2. pull funds from abpt
+3. wrap weth into wstETH
+4. deposit into abptv2
+5. deposit into stkabptv2
 
-[bgd-labs/aave-address-book](https://github.com/bgd-labs/aave-address-book) - the best and only source about all deployed Aave ecosystem related contracts across all the chains
+These methods allow two types of migration:
+1. exact migration
+2. proportional migration
+
+In the exact migration path
+```solidity
+migrateStkABPT(
+    uint256 amount,
+    [0,0],
+    minAmountOut, // slippage control
+    true // all
+)
+```
+
+The amount is withdrawn from stkABPT and fully deposited into stkABPTv2. `minAmountOut` in this case acts as slippage control and should be calculated as `((amount * uint256(abptOracle.latestAnswer())) / uint256(abptv2Oracle.latestAnswer())) * slippage`. By making slippage sufficiently small (e.g. `0.01%`), the swap will revert if one of the pools is highly imbalanced. As long as the pools have reasonable liquidity, we expect this path to be preferrable as arbitrage bots will keep the pool close to equilibrium.
+
+In the proportional migration path:
+```solidity
+migrateStkABPT(
+    uint256 amount,
+    tokenOutAmountsMin,
+    minAmountOut, // slippage control
+    false // all
+)
+```
 
-[bgd-labs/aave-helpers](https://github.com/bgd-labs/aave-helpers) - useful utils for integration, and not only testing related to Aave ecosystem contracts
+The slippage control is on both the `tokenOutAmountsMin` and `minAmountsOut`. Instead of joining with the full balance withdrawn from v1, the join on v2 will be proportional to reach equlibrium. The remaining funds will be sent back to the sender.
 
-[Rari-Capital/solmate](https://github.com/Rari-Capital/solmate) - one of the best sources of base contracts for ERC20, ERC21, which will work with transparent proxy pattern out of the box
+### 4. [ProposalPayload](./src/contracts/ProposalPayload.sol)
 
-[OpenZeppelin/openzeppelin-contracts](https://github.com/OpenZeppelin/openzeppelin-contracts) - another very reputable and well organized source of base contracts for tokens, access control and many others
+This contract is intended to be used as the proposal payload to initiate the migration process.
+The payload does multiple actions:
+1. stop liquidity incentives on stkabptv1
+2. upgrade the token implementation to allow withdrawals without cooldown
+3. create the nem stkabptv2 sm
+4. start liquidity incentives on stkabptv2
 
 ## Development
 
@@ -36,21 +80,4 @@ forge install
 
 ```sh
 forge test
-```
-
-## Advanced features
-
-### Diffing
-
-For contracts upgrading implementations it's quite important to diff the implementation code to spot potential issues and ensure only the intended changes are included.
-Therefore the `Makefile` includes some commands to streamline the diffing process.
-
-#### Download
-
-You can `download` the current contract code of a deployed contract via `make download chain=polygon address=0x00`. This will download the contract source for specified address to `src/etherscan/chain_address`. This command works for all chains with a etherscan compatible block explorer.
-
-#### Git diff
-
-You can `git-diff` a downloaded contract against your src via `make git-diff before=./etherscan/chain_address after=./src out=filename`. This command will diff the two folders via git patience algorithm and write the output to `diffs/filename.md`.
-
-**Caveat**: If the onchain implementation was verified using flatten, for generating the diff you need to flatten the new contract via `forge flatten` and supply the flattened file instead fo the whole `./src` folder.
+```