---
# System prepended metadata

title: '[RFC] Upgrade RTokens to Release 3.0.0'

---

# [RFC] Upgrade RTokens to Release 3.0.0

## Summary
This proposal suggests instructions for RToken governors to upgrade existing RTokens to release 3.0.0 of the Reserve Protocol. Detailed explanations of each RToken's upgrades are provided in each respective RTokens' section. 

## Motivation
The Reserve core team has deployed the 3.0.0 release of the Reserve Protocol to Ethereum mainnet, bringing a host of improvements, described in the [announcement post](https://blog.reserve.org/reserve-protocol-v1-3-0-0-release-9c539334f771). However, mere announcement of the release does not automatically produce change in production RTokens - governance action is required for that. The purpose of this proposal is to invite governors from the different RToken communities to enact on-chain upgrade proposals to take advantage of this release.

See [here](https://www.loom.com/share/8c47272036ce4e2d98b34133e67b0637) for a video Q&A between Reserve Protocol contributors Nevin Freemand and Patrick Mckelvy further explaining the impact & purpose of the 3.0.0 governance proposals

## Specification
Draft instructions have been provided for upgrading the most popular RTokens - eUSD, ETH+ and hyUSD:
https://gist.github.com/larrythecucumber321/8f17bfb2c0d9e7b3912bf782c1cb6b45

We describe in detail the changes being proposed below and we invite all propsective RToken governors to review the soundness of these suggestions in detail. These explanations will be grouped by RToken, as their upgrade paths to 3.0.0 all slightly differ.

Each row of the instructions represents a single function "call" being made to a Reserve-related smart contract as part of the upgrade process. 

### Common Upgrades/Calls
The first 15 and the last 7 suggested calls for each RToken are the same, and will be discussed together in this section. 

The first 11 calls involve upgrading existing component contracts to new implementation contracts (through the `upgradeTo` call on the proxy contract). These implementation contracts are the primary subject of the 3.0.0 release, featuring significant differences from their existing 2.1.0 counterparts. The full list of 3.0.0 implementation contracts can be viewed [here](https://github.com/reserve-protocol/protocol/blob/master/scripts/addresses/mainnet-3.0.0/1-tmp-deployments.json), which correspond with the provided instructions.

The next four calls involve calling `cacheComponents` on each of the BackingManager, Distributor, RSRTrader, and RTokenTrader contracts. These calls cache peer components on the target contracts to enable more efficient contract calls when interacting with each other.

The last seven suggested calls perform the following functions:
- Grant the `EXECUTOR` role on the Timelock contract to the Governor, and revoke it from the `0x0` address
- Initialize the `warmupPeriod` on the `BasketHandler`, enforcing a delay before protocol trades can occur
- Initialize the `RSRWithdrawalLeak` on `stRSR`, a gas savings mechanism for RSR stakers
- Set the implementation contracts for Batch and Dutch auctions on the `Broker` and set the auction length for the latter 

### <img src="https://hackmd.io/_uploads/ryX4uK7ga.png" alt="drawing" width="60"/> eUSD 

#### `register` Calls
Following the first 15 common calls, the next two calls involve registering [cUSDC](https://etherscan.io/address/0x50a9d529EA175CdE72525Eaa809f5C3c47dAA1bB) and [cUSDT](https://etherscan.io/address/0x5757fF814da66a2B4f9D11d48570d742e246CfD9) as new assets on the `AssetRegistry` contract. Assets are contracts which inform the protocol how to treat and price ERC20 tokens. The underlying ERC20s representing Compound positions has changed and so new Assets must be registered. Where cTokens could previously be directly deposited into RTokens, they have been wrapped in 3.0.0 so as to  minimize trust assumptions in collateral plugins during rewards claiming (all collateral assets which involve claiming rewards should be wrapped going forward).  

#### `swapRegistered` Calls

The next 11 calls involve swapping the currently registered Assets for existing ERC20 tokens registered on eUSD to upgraded Asset contracts. Specifically, the Asset contracts for the following tokens are swapped:
- saUSDC, saUSDT, RSR, TUSD, USDP, DAI, USDT, USDC, COMP, stkAAVE, eUSD  

#### Update Basket

Because the ERC20 tokens for cUSDC and cUSDT were changed (to wrapped versions), a new basket must be set on eUSD with `setPrimeBasket`. eUSD's basket will functionally remain the same.

The following `refreshBasket` call refreshes the existing basket and causes the new basket to take effect. 


### <img src="https://hackmd.io/_uploads/B11zttQeT.png" alt="drawing" width="60"/>  ETH+

#### `swapRegistered` Calls

Apart from the common calls discussed above, the only unique calls on ETH+ are for upgrading Asset references through `swapRegistered`. Specifically, new Assets are swapped in for WETH, wstETH, rETH, and ETH+. There is no need for new ERC20 tokens as with eUSD because rETH and wstETH are both appreciating assets without the need to claim rewards.

### <img src="https://hackmd.io/_uploads/HkIDdFmla.png" alt="drawing" width="60"/>  hyUSD

#### `register` Calls

The first unique calls on hyUSD are for registering new ERC20 collateral on the `AssetRegistry` contract. Improvements have been made to the existing Convex wrappers which necessitate ERC20 changes for staked eUSDFRAXBP and cvxMIM3Pool, resulting in the two `register` calls. 


#### `swapRegistered` Calls

The next 9 calls are for swapping to new Assets. Specifically, the Asset contracts for the following tokens are upgraded:
- RSR, USDC, USDT, USDP, CRV, CVX, hyUSD

#### Update Basket

Because of the upgraded wrappers for eUSDFRAXBP and cvxMIM3Pool, a new basket must be set on hyUSD with `setPrimeBasket`. hyUSD's basket will functionally remain the same

The following `refreshBasket` call refreshes the existing basket and causes the new basket to take effect. 

## Conclusion/Next Steps 
This proposal offers a comprehensive guide for RToken governors on the procedural steps to upgrade RTokens to the 3.0.0 release of the Reserve Protocol. Huge thanks to everyone who's read up to this point, showing your commitment to RToken decentralization. We now invite RToken governors to take the following actions:

**Review Upgrade**
Governors should meticulously review the proposed upgrades, ensuring understanding and agreement on each step.

**Discuss Proposal**
Express any concerns, queries, or suggestions related to this upgrade. Do not hesitate to contact myself or other team members (here or on [Discord](https://discord.gg/ZcYXqZjFCF)) for support or clarification.

**Use Upgrade Helper:**
If governors are in agreement with the proposed changes, governors may proceed to use the Upgrade Helper on Register, which has encoded the present instructions. ![](https://hackmd.io/_uploads/HkUVIR7gT.png)

## References

- [3.0.0 Changelog ](https://github.com/reserve-protocol/protocol/blob/master/CHANGELOG.md)
- [3.0.0 Announcement](https://blog.reserve.org/reserve-protocol-v1-3-0-0-release-9c539334f771)
- [3.0.0 Upgrade Instructions](https://gist.github.com/larrythecucumber321/8f17bfb2c0d9e7b3912bf782c1cb6b45)
- [Code4rena 3.0.0 Audit Report](https://github.com/reserve-protocol/protocol/blob/master/audits/Code4rena%20-%20Reserve%20Audit%20Report%20-%203.0.0%20Release.md)
- [Simulation of eUSD upgrade](https://www.tdly.co/shared/simulation/b7dbd5d8-1e7b-4f1a-a873-0e26f527844e)
- [Simulation of ETH+ upgrade](https://www.tdly.co/shared/simulation/f3baf2d2-68bc-471a-8dd9-d838a6c2e217)
- [Simulation of hyUSD upgrade](https://www.tdly.co/shared/simulation/4849832a-e8cf-4b7b-a3cb-c0d79ec4d83c)

