[RFC] Upgrade RTokens to Release 3.0.0

[RFC] Upgrade RTokens to Release 3.0.0


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.


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. 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 for a video Q&A between Reserve Protocol contributors Nevin Freeman and Patrick Mckelvy further explaining the impact & purpose of the 3.0.0 governance proposals


Draft instructions have been provided for upgrading the most popular RTokens - eUSD, ETH+ and hyUSD:

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, 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

drawing eUSD

register Calls

Following the first 15 common calls, the next two calls involve registering cUSDC and cUSDT 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:


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.

drawing 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.

drawing 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:


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) 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 (soon to be live), which encodes the present instructions.