# BIP-37: Basin Integration

- Space: [Beanstalk DAO](https://snapshot.box/s:beanstalkdao.eth.md)
- Author: 0x47a473Eb2bDfe6599dac638FFFE0D427d8Ad6888
- State: Passed
- Voting type: Basic
- Start: 2023-08-23 16:00 UTC
- End: 2023-08-30 16:00 UTC
- Votes: 223
- Open in Snapshot: https://snapshot.box/#/s:beanstalkdao.eth/proposal/0x98fbf0e9a3fe3054679fefb544fd57cd4df1f85b03edeecd1a06ccefdd4d1def

## Results

- For: 65,647,475.65 voting power, 100.0%
- Against: 0 voting power, 0.0%
- Abstain: 0 voting power, 0.0%

## Proposal

## Proposer

Brendan Sanderson, Ben Weintraub, Beanstalk Farms

Proposer Wallet: [0xf9d183af486a973b7921ceb5fdc9908d12aab440](https://etherscan.io/verifySig/22706)

## Summary

* Provide infrastructure for any Well LP token from the [Basin DEX](https://basin.exchange/basin.pdf) to be integrated into Beanstalk;
* Add the BEAN:ETH Constant Product Well LP token (BEANETH) to the Deposit Whitelist with 1 Stalk per BDV and 4.5 Seeds per BDV;
    * Support Conversions from Beans to BEANETH above peg and vice versa below peg; and
    * Add the BEANETH Well to the Oracle Whitelist;
* Change the Bean and BEAN:3CRV Curve LP token (BEAN3CRV) Seeds per BDV to 3 Seeds and 3.25 Seeds, respectively;
* Add view functions for getting account level BDV and last Mowed Stems to the Silo;
* Upgrade the Depot Facet to use [Pipeline v1.0.1](https://github.com/BeanstalkFarms/Pipeline#v101-current);
* Use the BEANETH Well to calculate the award for successfully calling the `gm` function;
* Update the Flood implementation to reflect the removal of the Withdrawal Freeze;
* Update the [Beanstalk DAO Disclosures](https://bean.money/disclosures) to reflect the state of Beanstalk and its risks; and
* Update the list of Beanstalk Farms Multisig (BFM) signers and Beanstalk Immunefi Committee (BIC) members.

## Links

* [BIP-37 GitHub PR](https://github.com/BeanstalkFarms/Beanstalk/pull/378)
* GitHub Commit Hash: [76a188233917afc1db103ca64b02dab8c5280b35](https://github.com/BeanstalkFarms/Beanstalk/tree/76a188233917afc1db103ca64b02dab8c5280b35)
* [Safe Transaction](https://app.safe.global/transactions/tx?safe=eth:0xa9bA2C40b263843C04d344727b954A545c81D043&id=multisig_0xa9bA2C40b263843C04d344727b954A545c81D043_0x7ac542c48b5e020bc5c26667651861a4542d49150b4be3a2f8b4e011b7feb5db)

## Problem

### Basin Integration

Basin is a composable EVM-native decentralized exchange protocol. Currently there is no generalized way for [Wells](https://basin.exchange/basin.pdf#subsection.3.1) (pools of the Basin DEX) to be easily integrated into the Silo (*i.e.*, the Deposit, Convert and Oracle Whitelists).

### Whitelist BEANETH

Currently Beans only trade against 3CRV, which is a significant centralization vector for Beanstalk. Additionally, the BEAN:3CRV pool, which is currently the sole oracle for calculating the Bean price, is not multi-block MEV manipulation resistant.

### Seeds per BDV Changes

The Seeds per BDV of Bean and BEAN3CRV can be optimized given (1) the new option for providing Bean liquidity via the BEANETH Well and (2) that Unripe Depositors had accumulated Grown Stalk for about a year from Replant to the commitment of Silo V3. As a result of (2), the average Grown Stalk per BDV is excessively high for older Deposits, compared to newer ones.

### Silo V3 Getters

Currently there is no way to get the total Deposited BDV or the last Mowed Stems for a particular Farmer.

### Pipeline Upgrade 

Pipeline v1.0.0 is unable to receive transfers of Ether, which makes it difficult to unwrap WETH as a part of a Pipeline function call. Pipeline v1.0.1 fixes this issue, but currently the Depot Facet uses Pipeline v1.0.0. 

### `gm` Incentive Reward Oracle

Currently Beanstalk uses the ratio between the USDC:ETH Uniswap V3 and BEAN:3CRV Curve pools to calculate the cost of executing the `gm` function in Beans. Both pools are subject to multi-block MEV manipulation and calculating the ratio between two pools is gas-inefficient. 

### Flood Update

Currently the implementation of Flood is not functional after the removal of the Withdrawal Freeze in [BIP-36](https://arweave.net/Zj-OCFwtOxRewDN1RK3tELz_0xyjjBKisL1arwJ3klk).

### Disclosures

The Beanstalk DAO Disclosures can be updated to reflect the current state of Beanstalk and its risks.

## Proposed Solution

### Basin Integration

Provide the infrastructure for any Well LP token to be integrated into Beanstalk:
* Add a Well LP token BDV function (`wellBdv`) that permits any Well LP token to be added to the Deposit Whitelist. Implemented in `BDVFacet` and `LibWellBdv`.
* Upgrade the Deposit Whitelist to include an `encodeType`, which allows for BDV functions with different function signatures to be properly encoded. Currently, `function(uint256)` (`encodeType` = 0) and `function(address, uint256)` (`encodeType` = 1) are supported. The generalized Well BDV function uses `encodeType = 1`.
* Add the `convertLPToBeans` and `convertBeansToLP` functions to Convert to peg from Beans to any whitelisted Well LP token and vice versa in `LibWellConvert`. Also, add the `BEANS_TO_WELL_LP` and `WELL_LP_TO_BEANS`  Convert types to access the new Convert methods.
* Add a generalized Well minting oracle to capture the time weighted average deltaB in a Well containing Beans in `LibWellMinting`.

Move `enrootDeposit(s)` from `ConvertFacet` to a separate `EnrootFacet`.

Split up `ConvertFacet` into `ConvertFacet` and `ConvertGettersFacet`.

### Whitelist BEANETH

Add BEANETH to the Deposit Whitelist with 1 Stalk per BDV and 4.5 Seeds per BDV. Also, support Conversions from Beans to BEANETH above peg and from BEANETH to Beans below peg.

In order for Beanstalk to calculate deltaB in the BEANETH Well, it must compare the manipulation resistant BEAN:ETH price in the Well with a manipulation resistant ETH:USD price.

Pumps are the generalized oracle component of Basin. [Multi Flow](https://basin.exchange/multi-flow-pump.pdf) is the Pump that is attached to the BEANETH Well and provides a multi-block MEV manipulation resistant BEAN:ETH price.

`LibEthUsdOracle` contains functionalty to fetch a manipulation resistant ETH:USD price. `LibEthUsdOracle` uses a greedy algorithm to return a gas efficient average price of (1) the current price returned by the ETH/USD Chainlink data feed and (2) either the ETH:USDC Uniswap V3 pool or the ETH:USDT Uniswap V3 pool depending on which is closer to (1). If the ETH:USDC Uniswap V3 price is sufficiently close (0.3%) to the Chainlink data feed price, then the oracle will not check the ETH:USDT Uniswap V3 price to save gas (*i.e.*, be greedy). The oracle only returns a value if the price difference between the ETH/USD Chainlink data feed and either Uniswap V3 pool is less than 1%.

The BEANETH Well is added to the Oracle Whitelist by including the Well in the `stepOracle` and `totalDeltaB` functions in `SeasonFacet/Oracle.sol`.

Minting based on the BEANETH Well is subject to the 1% deltaB cap implemented in [EBIP-2](https://bean.money/ebip-2). With 2 pools on the Oracle Whitelist, the maximum amount that the Bean supply can increase each Season is 2% per the peg maintenance mechanism.

Update `MetadataImage` to include the BEANETH token and add the `name` and `symbol` functions to `MetadataFacet` to integrate Deposits with OpenSea.

### Seeds per BDV Changes

Set the Seeds per BDV for Bean and BEAN3CRV to 3 Seeds and 3.25 Seeds, respectively.

After the commitment of this upgrade, the Deposit Whitelist would be the following:

| Whitelisted asset    | Stalk per BDV    | Seeds per BDV    |
|:---------------------|:-----------------|:-----------------|
| Bean                 | 1                | 3                |
| BEAN:3CRV Curve LP   | 1                | 3.25             |
| BEAN:ETH Well LP     | 1                | 4.5              |
| Unripe Bean          | 1                | 0                |
| Unripe BEAN:3CRV LP  | 1                | 0                |

### Silo V3 Getters

Add the following functions to the Silo Facet that return Deposited BDV and last Mowed Stem data for a given Farmer:
* `balanceOfDepositedBDV`;
* `getLastMowedStem`; and
* `getMowStatus`.

### Pipeline Upgrade 

Upgrade the Depot Facet to use Pipeline v1.0.1 ([`0xb1bE0000C6B3C62749b5F0c92480146452D15423`](https://etherscan.io/address/0xb1bE0000C6B3C62749b5F0c92480146452D15423)). All updates were reviewed by Halborn.

#### Pipeline v1.0.1 Changelog
- Add `receive` function fallback; and
- Add `version` function.

### `gm` Incentive Reward Oracle

Upgrade the `gm` incentive reward oracle to calculate the cost to execute the `gm` function in Beans using the BEANETH Well.

Use `getBeanEthWellPrice` in `LibBeanEthWellOracle` to calculate the price of Ether in Beans. Remove the `getBeanUsdPrice` and `getEthUsdcPrice` functions in `LibIncentive` that were previously used to calculate the price of Ether in Beans using the ratio of the two return values.

### Flood Update

Update `handleRain` in `SeasonFacet/Weather.sol` to reflect the removal of the Withdrawal Freeze. Beanstalk waits 1 Season after it starts Raining before Flooding.

### Disclosures

The following is a list of proposed changes to the Beanstalk DAO Disclosures:

* Add disclosures about Beanstalk assuming the security of:
    * Basin and its components;
    * Uniswap V3; and 
    * Pipeline;
* Update the disclosure about Beanstalk requiring trustless and reliable access to a manipulation resistant oracle for a dollar; and
* Update the disclosure about Beanstalk not being a finished protocol and requiring development.

See the [Arweave upload of BIP-37](https://arweave.net/JbV3AEWRzf1MDuXcsH-alviR2O5N5qbP9UU6iZH5ijY) to read this section in full.

The updated Beanstalk DAO Disclosures can be read [here](https://arweave.net/zaOThrkaNCQ2zkkas8pyVQkFSkAKXfU7JahilBaqXRs).

### BFM Signers and BIC Members

We propose the following signers for the BFM:
- Michael Montoya
- Brean **(new signer)**
- guy
- sweetredbeans
- mod323
- aloceros
- Cujo

We propose the following members for the BIC:
- Brendan Sanderson
- mod323
- pizzaman1337 **(new member)**
- Brean
- funderberker
- malteasy

## Technical Rationale

### Basin Integration

Integrating Basin and its components into Beanstalk in a generalized fashion makes it easier for future developers to propose BIPs that whitelist Wells.

### Silo V3 Getters

Providing a way to get an individual Farmer's BDV per whitelisted token increases the composability of Beanstalk and enables protocols like Root to integrate with Silo V3.

### Pipeline Upgrade 

Supporting a version of Pipeline that can receive transfers of Ether improves the composability supported by the `farm` function.

### `gm` Incentive Reward Oracle

Querying a single liquidity pool to calculate the price of Ether in Beans reduces the cost of calling the `gm` function, and thus the reward that Beanstalk pays to incentive it.

### Flood Update

The Flood implementation must be updated in order to function properly.

## Economic Rationale

### Whitelist BEANETH

Beans currently only trade against 3CRV which is a significant centralization vector for Beanstalk. Ether is the most decentralized, censorship resistant and liquid asset on the Ethereum network. Thus, a relatively high Seeds per BDV for LP tokens of Beans paired with Ether is justified.

The Multi Flow Pump is the first Ethereum-native oracle for Ethereum-native data that offers multi-block MEV manipulation resistance in a post-Merge environment. Using Multi Flow, Beanstalk can calculate a multi-block MEV manipulation resistant BEAN:ETH price. 

Uniswap V3 pools are not multi-block MEV manipulation resistant but are on-chain and permissionless. Chainlink data feeds are multi-block MEV manipulation resistant because they are off-chain and permissioned. The ETH/USD data feed is the only Chainlink feed secured by staking. Using an average of the Chainlink feed and one of the Uniswap V3 pools, Beanstalk can calculate a multi-block MEV manipulation resistant ETH:USD price at the cost of some centralization.

Therefore, Beanstalk calculates deltaB in the BEANETH Well in a manipulation resistant fashion.

### Seeds per BDV Changes

**Rewarding more Seeds to LP tokens than Beans**

Providing liquidity for Beans is more useful to Beanstalk than Depositing Beans in the Silo, so Beanstalk should continue rewarding more Seeds to LP token Deposits than Bean Deposits. The delta in Seeds per BDV between LP tokens and Beans also minimizes upside volatility (and therefore excessive minting) as Farmers are incentivized to Convert their Deposited Beans to Deposited LP tokens above peg.

Therefore, LP tokens continue to receive more Seeds per BDV upon Deposit than Beans.

**Rewarding more Seeds to BEANETH than BEAN3CRV Deposits**

Prior to the April 2022 exploit, BEAN3CRV and BEANETH Deposits were both rewarded 4 Seeds per BDV. During this time, BEAN3CRV liquidity was growing rapidly and surpassed the amount of BEANETH liquidity. This is not ideal as Beanstalk should incentivize providing liquidity for Beans against decentralized assets.

Therefore, BEANETH should receive more Seeds per BDV than BEAN3CRV.

**Increasing Seeds for Bean and BEANETH Deposits**

Unripe Depositors had accumulated Grown Stalk for about a year from Replant to the commitment of Silo V3. As a result, the average Grown Stalk per BDV is excessively high. Increasing the Seeds per BDV for Bean and BEANETH allows for new Depositors to catch up to the average Grown Stalk per BDV faster. 

With 4.5 Seeds per BDV for BEANETH Deposits, a new BEANETH Depositor would catch up to the average Grown Stalk per BDV in about 6 months. With 3 Seeds per BDV for Bean Deposits, a new Bean Depositor would catch up to the average Grown Stalk per BDV in about 9 months. A function to evaluate Seeds per BDV and time to catch up to average can be evaluated here: https://www.desmos.com/calculator/hevziu8k9y.

Additionally, decreasing the ratio of LP token to Bean Seeds per BDV reduces the incentive to not Convert from LP tokens to Beans below peg.

Therefore, the Seeds per BDV for Bean, BEAN3CRV and BEANETH are set to 3 Seeds, 3.25 Seeds and 4.5 Seeds, respectively.

### `gm` Incentive Reward Oracle

Changing the oracle for calculating the cost to execute the `gm` function in Beans to the BEANETH Well that uses the Multi Flow Pump improves the censorship resistance of Beanstalk due to its multi-block MEV manipulation resistance.

### Flood Update

Flood is an essential peg maintenance tool for Beanstalk.

## Contract Changes

See the [Arweave upload of BIP-37](https://arweave.net/JbV3AEWRzf1MDuXcsH-alviR2O5N5qbP9UU6iZH5ijY) to read this section in full.

## Beans Minted 

None.

## Audit

### Basin Integration

The commit hash of this BIP is [76a188233917afc1db103ca64b02dab8c5280b35](https://github.com/BeanstalkFarms/Beanstalk/tree/76a188233917afc1db103ca64b02dab8c5280b35).

Halborn has performed an audit of this BIP up to commit hash [78d7045a4e6900dfbdc5f1119b202b4f30ff6ab8](https://github.com/BeanstalkFarms/Beanstalk/tree/78d7045a4e6900dfbdc5f1119b202b4f30ff6ab8). You can view the final audit report [here](https://arweave.net/qD2rZqlJgjBj-VatwoDmNgwdXd8Omc1Bt9RTkPsvK8k). 

Beanstalk contract changes between the two commits:
- Updated the Pipeline address in `DepotFacet`;
- Added metadata for BEANETH to the `MetadataFacet`;
- Changed the `stem` type in the `RemoveDeposit` event signature in `EnrootFacet` from `int128` to `int96`;
- Added the `InitBipBasinIntegration` contract that calls `whitelistToken` on BEANETH and sets the new Seeds per BDV for Bean, BEAN3CRV and BEANETH;
- Split up `ConvertFacet` into `ConvertFacet` and `ConvertGettersFacet`;
- Updated the Flood implementation (see `handleRain`) to reflect the removal of the Withdrawal Freeze;
- Added the `name` and `symbol` functions to `MetadataFacet`; 
- Updated Uniswap V3 pool calls in the ETH:USD oracle to handle failure gracefully; and
- Updated the ETH:USD oracle parameters.

### Basin

Halborn and Cyfrin performed an audit of Basin up to commit hash [e5441fc78f0fd4b77a898812d0fd22cb43a0af55](https://github.com/BeanstalkFarms/Basin/tree/e5441fc78f0fd4b77a898812d0fd22cb43a0af55). You can view the final audit report from Halborn [here](https://arweave.net/1IKi4iqRvu3qu_GdcLY4f3u9PgvOMvuRltU7AIXAEyA) and the final audit report from Cyfrin [here](https://arweave.net/usT3ClfjHwpX32OXnh5De1aH79csX1PMoXJCghXBaps). 

[Code4rena](https://code4rena.com/contests/2023-07-basin) performed an audit of Basin up to commit hash [8f6709ee1eeb36a452a08c591ebd3a340ea9b8c4](https://github.com/BeanstalkFarms/Basin/tree/8f6709ee1eeb36a452a08c591ebd3a340ea9b8c4), which included all remediations from the previous two audits. 

The formal audit report from Code4rena is forthcoming, but all issues were either acknowledged or remediated by commit hash [ea51be32047cbb6625232cb63b180ecfb3fd0b71](https://github.com/BeanstalkFarms/Basin/tree/ea51be32047cbb6625232cb63b180ecfb3fd0b71), which is the commit hash of Basin code deployed on Ethereum mainnet. The changelog can be read [here](https://github.com/BeanstalkFarms/Basin/pull/122). All updates were reviewed by Cyfrin.

## Effective

Immediately upon commitment.

---

To vote or create proposals from an AI assistant, connect the Snapshot MCP at https://mcp.snapshot.box

