Skip to content

Commit

Permalink
docs: add readme
Browse files Browse the repository at this point in the history
  • Loading branch information
sakulstra committed Sep 19, 2023
1 parent 3b32c35 commit a2205f1
Showing 1 changed file with 57 additions and 30 deletions.
87 changes: 57 additions & 30 deletions README.md
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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.
```

0 comments on commit a2205f1

Please sign in to comment.