Merge remote-tracking branch 'origin/feat--update-and-re-org-yETH' into pr/rossgalloway/33

Author: rossgalloway

docs/developers/addresses/v3-contracts.md

@@ -1,7 +1,9 @@
 # yVaults v3 Contract Addresses
 
+
 <AddressCheck contractType='v3'/>
 
+
 :::info
 
 Deployments are done using create2 factories and should be stable across all EVM chains the protocol has been deployed on.

docs/developers/addresses/veyfi-contracts.md

@@ -34,4 +34,5 @@
 | 13 | `yG-yvcrvUSD-2` | yGauge crvUSD-2 yVault | [`0x71c3223D6f836f84cAA7ab5a68AAb6ECe21A9f3b`](https://etherscan.io/address/0x71c3223D6f836f84cAA7ab5a68AAb6ECe21A9f3b) |
 | 14| `yG-yvUSDS-1` | yGauge USDS-1 yVault | [`0xd57aEa3686d623dA2dCEbc87010a4F2F38Ac7B15`](https://etherscan.io/address/0xd57aEa3686d623dA2dCEbc87010a4F2F38Ac7B15) |
 
+
 The above Gauges can be verified using the [YFI Gauge Registry](https://etherscan.io/address/0x1D0fdCb628b2f8c0e22354d45B3B2D4cE9936F8B#readContract) contract and querying the `gauges()` function with the index listed above.

docs/developers/addresses/ypools-contracts.md

@@ -0,0 +1,27 @@
+# yPools Contract Addresses
+
+A list of all the current yPool contract addresses.
+
+## yETH contract Addresses
+
+| Name                                             | Address                             |
+|--------------------------------------------------|-------------------------------------|
+| yETH                                             | [`0x1BED97CBC3c24A4fb5C069C6E311a967386131f7`](https://etherscan.io/address/0x1BED97CBC3c24A4fb5C069C6E311a967386131f7) |
+| st-yETH                                          | [`0x583019fF0f430721aDa9cfb4fac8F06cA104d0B4`](https://etherscan.io/address/0x583019fF0f430721aDa9cfb4fac8F06cA104d0B4) |
+| Pool                                             | [`0x2cced4ffA804ADbe1269cDFc22D7904471aBdE63`](https://etherscan.io/address/0x2cced4ffA804ADbe1269cDFc22D7904471aBdE63) |
+| | |
+| Management                                       | [`0xbBBBBbbB6B942883EAd4976882C99201108c784d`](https://etherscan.io/address/0xbBBBBbbB6B942883EAd4976882C99201108c784d) |
+| Guardian                                         | [`0xDC775e813cDB38a4f02c4BAd3942319088018eFA`](https://etherscan.io/address/0xDC775e813cDB38a4f02c4BAd3942319088018eFA) |
+| | |
+| Protocol Owned Liquidity                         | [`0x929401e30Aab6bd648dEf2d30FF44952BaB04478`](https://etherscan.io/address/0x929401e30Aab6bd648dEf2d30FF44952BaB04478) |
+| Bootstrap: Deposit, Vote, Claim Incentives       | [`0x41B994C192183793bB9cc35bAAb8bD9C6885c6bf`](https://etherscan.io/address/0x41B994C192183793bB9cc35bAAb8bD9C6885c6bf) |
+| Bootstrap: Claim st-yETH                         | [`0x7cf484D9d16BA26aB3bCdc8EC4a73aC50136d491`](https://etherscan.io/address/0x7cf484D9d16BA26aB3bCdc8EC4a73aC50136d491) |
+| Rate Providers                                   | [`0x4e322aeAf355dFf8fb9Fd5D18F3D87667E8f8316`](https://etherscan.io/address/0x4e322aeAf355dFf8fb9Fd5D18F3D87667E8f8316) |
+| | |
+| Inclusion Vote                                   | ['0x6bc0878939669339e82dbFa13d260c89230f2c31'](https://etherscan.io/address/0x6bc0878939669339e82dbFa13d260c89230f2c31) |
+| Executor                                         | ['0x71258Ee726644f1D52d6A9F5E11C21d1E38c2bF1'](https://etherscan.io/address/0x71258Ee726644f1D52d6A9F5E11C21d1E38c2bF1) |
+| GenericGovernor                                  | ['0xB7a528CF6D36F736Fa678A629b98A427d43E5ba5'](https://etherscan.io/address/0xB7a528CF6D36F736Fa678A629b98A427d43E5ba5) |
+
+> Due to a redeploy of st-yETH during the bootstrap process the first st-yETH contract has been deprecated, use the `Bootstrap: Claim st-yETH` contract to claim the new version if you participated in the bootstrap phase.
+
+Find more information about the yPools Roles, modes, and privileges [here](/developers/ypools/ypools-roles)

docs/developers/ypools/yeth/adding-assets.md

@@ -0,0 +1,29 @@
+# Adding Assets to yPools
+
+Follow these steps to enable the inclusion of new assets into yETH via governance proposal and voting.
+
+:::info[Pre-requisites]
+
+You will need access to the necessary governance contracts and a sufficient voting weight of at least 100 to create proposals. You can check your voting weight [here](https://etherscan.io/address/0x583019fF0f430721aDa9cfb4fac8F06cA104d0B4#readContract#F13).
+
+:::
+
+## Steps
+
+### Step 1: Check Inclusion Vote Status
+
+Since the adoption of [this](https://snapshot.org/#/ylsd.eth/proposal/0x139698bed7752b80a16bb6d2fc0d9e8c82b622916ded2f064022be3c46ec9bb4) proposal, inclusion voting is off by default and needs to be enabled for the next epoch
+
+### Step 2: Enable One-Off Inclusion Vote
+
+To enable a one-off inclusion vote, a governance call must be made to the set_enable_epoch(next_epoch) function on the [InclusionVote contract](https://etherscan.io/address/0x6bc0878939669339e82dbFa13d260c89230f2c31#code).
+
+This step requires crafting and approving a governance proposal. Follow the instructions [here](create-gov-proposal.md) to do that successfully.
+
+### Step 3: Eligible Tokens for Voting
+
+Any token that has applied for inclusion and has a rate provider set by Yearn will be eligible for this inclusion vote.
+
+### Step 4: Outcome
+
+Once the vote is complete, the winner (if any) will be included into yETH.

docs/developers/ypools/yeth/create-gov-proposal.md

@@ -0,0 +1,40 @@
+---
+rpcCalls:  
+  - name: 'yPools Inclusion'
+    chain: '1'
+    address: '0x6bc0878939669339e82dbFa13d260c89230f2c31'
+    abiName: 'yPoolsInclusionVoteABI'
+    methods:  
+      - 'epoch'
+---
+<!-- markdownlint-disable MD037 -->
+
+# Create a Governance Proposal
+
+:::info[Pre-requisites]
+
+You will need access to the necessary governance contracts and a sufficient voting weight of at least 100 to create proposals. You can check your voting weight [here](https://etherscan.io/address/0x583019fF0f430721aDa9cfb4fac8F06cA104d0B4#readContract#F13).
+
+:::
+
+## Step 1: Craft the Proposal Script
+
+1. Generate a script by calling the `script(_to, _data)` view function on the [Executor contract](https://etherscan.io/address/0x71258Ee726644f1D52d6A9F5E11C21d1E38c2bF1#readContract#F1).
+
+   In this case, set the `_to(address)` field to the [InclusionVote contract](../../addresses/ypools-contracts.md#yeth-contract-addresses) `0x6bc0878939669339e82dbFa13d260c89230f2c31` and use ABI-encoded data for the function set_enable_epoch(next_epoch) as the calldata (_data).
+
+   <AbiEncodingWidget defaultAbi='yPoolsInclusionVoteABI' defaultFunction='set_enable_epoch' functionArg='20'/>
+
+2. To enable multiple calls in a single proposal, concatenate the scripts together.
+
+## Step 2: Submit a Governance Proposal
+
+1. You can create the proposal via the [proposal page](https://yeth.yearn.fi/propose) or directly by calling the propose(ipfs_hash, script) function on the [GenericGovernor contract](https://etherscan.io/address/0xB7a528CF6D36F736Fa678A629b98A427d43E5ba5).
+2. The ipfs_hash should point to a document hosted on IPFS with details explaining the proposal and its rationale. You can host your own IPFS document or use a provider like [Piñata](https://pinata.cloud/).
+
+## Step 3: Proposal Approval and Execution
+
+Once the proposal is created, the governance process will need to:
+
+1. Approve the proposal.
+2. Execute the set_enable_epoch(next_epoch) function to enable the inclusion vote for the next epoch.

docs/developers/ypools/yeth/periphery-spec.md

@@ -0,0 +1,49 @@
+# Governance Specification
+
+Contracts for fully on-chain governance, consisting of multiple cooperating components. Each component can be swapped out in the future if our requirements change. The different concepts and contracts are as follows:
+
+```mermaid
+graph TD
+    classDef entity fill:#f9f,stroke:#red,stroke-width:5px;
+    classDef relationship fill:#bbf,stroke:#green,stroke-width:5px;
+
+yPoolsMultiSig -->|Manages| OwnershipProxy
+OwnershipProxy -->|Manages| Executor
+Executor -->|Manages| GenericGovernor
+Executor -->|Manages| PoolGovernor
+
+GenericGovernor -->|Uses| Measure
+PoolGovernor -->|Uses| Measure
+
+Measure -->|Types| LaunchMeasure
+Measure -->|Types| DelegateMeasure
+
+DelegateMeasure -->|Delegates Voting Power via| DelegatedStaking
+
+PoolGovernor -->|Uses| InclusionVote
+PoolGovernor -->|Uses| WeightVote
+
+InclusionVote -->|Interacts with| InclusionIncentives
+WeightVote -->|Interacts with| WeightIncentives
+```
+
+- The entire protocol defines a set of management roles, which have powers within the protocol to set variables, rates, add assets etc. With the transition to on-chain governance, the **OwnershipProxy** will become the new owner of all these management roles, including the ones descriped below (excluding the proxy's own). This contract is very simple and is able to execute arbitary contract calls. Note that this is not a delegatecall proxy!
+- The proxy has its own management, which will be the **Executor** and has permission to execute calls through the proxy. The executor maintains a list of governors, which are allowed to execute function calls through executor onto the proxy. In addition, the executor has the ability to enable a whitelist or blacklist for combination of address+selector. This allows us to define governors with only limited power.
+The executor is self-governing, meaning the proxy is supposed to fulfill its management role.
+The two-layer design of proxy and executor allows us to easily replace the executor if desired without having to move all the management permissions over one by one.
+- There are two governors: **GenericGovernor** and **PoolGovernor**. They both take governance actions based on on-chain voting procedures.
+- On-chain voting is based on 4 week long _epochs_. These coincide with Curve epochs, starting on a Thursday 00:00 GMT.
+All voting takes place on the last week of the epoch.
+- The voting power of governance participant is measured by a **Measure**. At launch, we used the **LaunchMeasure** on Snapshot (with **SnapshotToken**, which simply provides an ERC20 for the launch measure). The launch measure simply defines the vote weight as the user's st-yETH weight plus the user's share of the bootstrap st-yETH weight.
+- With the transition to on-chain governance, a new measure is introduced, the **DelegateMeasure**. By default this returns the same value as the launch measure. But management has the ability to delegate the voting power of an account that deposited into a **DelegatedStaking** contract to another account. This gives some of the st-yETH balance as voting power to the delegator.
+- In the first 3 weeks of the epoch, the **GenericGovernor** accepts proposals from anyone with sufficient voting weight. Proposals come in the form of a script, which will be executed on the executor if passed. In the final week of the epoch, users vote in favor or against each proposal. At the end of the epoch, all proposals that pass a threshold of relative votes in favor, will have passed. They become executable by anyone after a delay.
+The author of the proposal can retract their proposal, and management can cancel any before it is executed.
+- A second voting contract is **InclusionVote**. In the first three weeks, anyone can apply (upon paying a fee) for a token to be whitelisted for the vote.
+A special role, the operator, has the task of setting rate providers for each of the applicants. An application with a rate provider automatically becomes whitelisted, meaning they can be voted on.
+The voting takes place in the last week of the epoch. The asset with the largest number of votes will be added to the pool.
+One of the vote options is a 'blank' vote. If that option has the most votes, no new asset will be added to the pool this epoch.
+- Anyone can post incentives for any asset to be added to the pool in **InclusionIncentives**. If the asset wins the vote and is added, the incentives are paid out to everyone that voted. If the asset does not win, the incentives are refunded.
+- The third voting contract is **WeightVote**. This contract is used to vote on the existing assets in the pool, and a 'blank' option. At the end of the epoch, a certain percentage of all weight is redistributed according to the result of this vote.
+- The **WeightIncentives** contract is used to post incentives for voting on the assets. The incentives are distributed according to the voting weight dedicated by each user to that specific asset.
+- The inclusion voting and weight voting contracts are not governors, instead they are used by the **PoolGovernor**. After the end of the epoch, the pool governor first adds the winning asset (if any) to the pool with a very low weight, through the executor. Immediately after, it starts a weight ramp, redistributing weights according to the vote results, as well as increasing the weight of the new asset.
+The pool governor is operated by an operator, which is a role tasked with adding the asset to the pool while minimizing the arb opportunities. This is a trusted role, but has very limited powers as it cannot change weights at will or add arbitrary assets.

docs/developers/ypools/yeth/wp.md

@@ -0,0 +1,162 @@
+# yETH Weighted Stableswap
+
+## Author
+
+0xkorin - Yearn Finance (0xkorin@proton.me)
+
+---
+
+## Invariant Derivation
+
+### Constant Sum
+
+$$
+\sum_i x_i = c_1
+$$
+
+### Constant Weighted Product
+
+$$
+\prod_i x_i^{w_i} = c_2 \quad \text{with} \quad \sum_i w_i = 1
+$$
+
+Define:
+$$
+\frac{1}{f} \coloneqq \prod_i w_i^{w_i}, \quad v_i \coloneqq w_i^n
+$$
+
+### Balanced Pool
+
+$$
+x_i = w_i D \implies c_1 = D \sum_i w_i = D, \quad c_2 = D \prod_i w_i^{w_i} = \frac{D}{f}
+$$
+
+$$
+x_i = \frac{D}{f^{v_i}}
+$$
+
+---
+
+## Leveraged Invariant
+
+$$
+\chi D^{n-1} \sum_i x_i + \prod_i x_i^{v_i} = \chi D^n + \frac{D^n}{f^n}
+$$
+
+---
+
+## Dynamic Leverage
+
+$$
+\chi = A \prod_i x_i^{v_i} \frac{D^n}{f^n}
+$$
+
+---
+
+## Weighted Stableswap Invariant
+
+$$
+A f^n \sum_i x_i + D = A D f^n + \frac{D^{n+1}}{f^n \prod_i x_i^{v_i}}
+$$
+
+This reduces to the original stableswap invariant if we set equal weights $w_i = \frac{1}{n}$.
+
+Define:
+$$
+\sigma \coloneqq \sum_i x_i, \quad \pi \coloneqq \frac{D^n}{\prod_i w_i x_i^{v_i}}
+$$
+
+$$
+A f^n \sigma + D = A D f^n + D \pi \tag{1}
+$$
+
+---
+
+## Supply Calculation
+
+Given a pool with weights $\{w_i\}$ and virtual balances $\{x_i\}$, the equilibrium supply $D$ can be found by solving Equation (1) iteratively:
+
+$$
+D_{m+1} = \frac{A f^n \sigma - D_m \pi_m}{A f^n - 1}
+$$
+
+Where:
+$$
+\pi_m = \frac{D_m^n}{D_{m-1}^n} \pi_{m-1}
+$$
+
+Starting with:
+$$
+\pi_0 = \prod_i \frac{D_0 w_i x_i^{v_i}}{D_0}
+$$
+
+The iterative process begins with a good initial guess for $D_0$ (e.g., $\sigma$) and continues until the desired precision is achieved.
+
+---
+
+## Rate Update
+
+$$
+x_i = b_i r_i \rightarrow x_i' = b_i r_i'
+$$
+
+$$
+\sigma \rightarrow \sigma' = \sigma + b_i (r_i' - r_i)
+$$
+
+$$
+D \rightarrow D', \quad \pi \rightarrow \pi' = \frac{D'^n}{D^n} \frac{r_i}{r_i'} v_i \pi
+$$
+
+Equation (2) is used iteratively to find both $D'$ and $\pi'$, starting with $D'_0 = D$ and $\pi'_0 = \pi \frac{r_i}{r_i'} v_i$.
+
+---
+
+## Balance Calculation
+
+Given weights $\{w_i\}$, virtual balances $\{x_i\}_{i \neq j}$, and supply $D$, the balance of a specific asset $j$ can be found by solving Equation (1) for $y \coloneqq x_j$.
+
+Define intermediary variables:
+$$
+\tilde{\sigma} \coloneqq \sum_{i \neq j} x_i, \quad \tilde{\pi} \coloneqq \frac{D^n w_j^{v_j}}{\prod_{i \neq j} w_i x_i^{v_i}}
+$$
+
+Rewriting Equation (1):
+$$
+A f^n (\tilde{\sigma} + y) + D = A D f^n + D \tilde{\pi} y^{v_j}
+$$
+
+Rearranging:
+$$
+y^{v_j+1} + \tilde{\sigma} y^{v_j} - \frac{D}{A f^n} y - \frac{D}{A f^n} \tilde{\pi} = 0
+$$
+
+This root can be found using Newton's method.
+
+---
+
+## Swaps
+
+### Exact Input
+
+Find $\Delta b_l$ given $\Delta b_k$:
+$$
+\tilde{\sigma} = \sigma + \Delta b_k r_k - x_l, \quad \tilde{\pi} = \frac{x_k}{x_k'} v_k \frac{x_l^{v_l}}{\pi}
+$$
+
+$$
+\Delta b_l = \frac{x_l - x_l'}{r_l}
+$$
+
+---
+
+### Exact Output
+
+Find $\Delta b_k$ given $\Delta b_l$:
+$$
+\tilde{\sigma} = \sigma - x_k - \Delta b_l r_l, \quad \tilde{\pi} = \frac{x_k^{v_k}}{x_l x_l'} v_l \pi
+$$
+
+$$
+\Delta b_k = \frac{x_k' - x_k}{r_k}
+$$