RToken
, or Reedemable Token, is an ERC20 token that is 1:1 redeemable to its
underlying ERC20 token. The underlying tokens are invested into interest
earning assets specified by the allocation strategy, for example into
Compound. Owners of the rTokens can use a
definition called hat to configure who is the beneficiary of the accumulated
interest. RToken can be used for community funds, charities, crowdfunding,
etc. It is also a building block for DApps that need to lock underlying tokens
while not losing their earning potentials.
+------+
+-----+ User +-------+
| +------+ |
| |
| | +-----------------------+
| | |compound.finance cToken|
+----+-----+ +-----------+-----------+ +-----------------------+
| Dapp | |ERC20 Compatible Wallet| ^
+----+-----+ +-----------+-----------+ |
| | +--------------------------+
| | |CompoundAllocationStrategy|
| | +--------------------------+
| | ^
| v |
| +----------------------------------+ |
| | RToken | |
| |----------------------------------| |
| | - ERC20 compatible | |
+--->| - Mint/Redeem/PayInterst | |
| - "Hat"/Beneficiary system | |
| - Changeable allocation strategy +--------------+
| - Configurable parameters | IAllocationStrategy interface
| - Admin role (human/DAO) |
+----------------------------------+
^
|
+--+--+
|Admin|
+-----+
As an example, let's pick DAI as our underlying token contract. As a result, the rToken instantiation is conveniently called rDAI in this example.
A hat defines who can keep the interest generated by the underlying DAI deposited by users. Every address can be configured with one and only one hat, but a hat can have multiple beneficiaries.
There are three kinds of hats:
-
Zero Hat
- It is the default hat for all addresses (even before they have a balance). Any interest generated by the DAI tokens locked by the owner are entitled to the owner himself. This kind of hat is subjected to the Hat Inheritance Rules -
Self Hat
- Similar to the Zero Hat, as the owner keeps all DAI tokens and generated interest. However in this case it is a deliberate choice by the owner, hence the Hat Inheritance Rules do not apply to this address. -
Other Hat
- This hat can be inherited or created by the user. The interest generated by the Hat can be withdrawn to the address of any recipient indicated in the hat definition. Hat Inheritance Rules do not apply to this address.
A hat is defined by a list of recipients, and their relative proportions for splitting the rDAI loans from the owner.
For example:
{
recipients: [A, B],
proportions: [90, 10]
}
defines that the DAI tokens will be loaned to address A and address B in the relative proportions of 90:10, effectively A receives 90% and B receives 10% of the generated interest.
The user first needs to approve the rDAI contract to use its DAI tokens, then the user can mint as much rDAI as they have DAI. One rDAI is always equal to one DAI.
As a result, the DAI tokens transferred in order to mint new rDAI tokens are invested automatically into the Saving Strategy, and the recipients indicated in the user's chosen hat can withdraw any generated interest.
Users may redeem the DAI tokens they deposited at any time by transferring back the rDAI tokens.
As a result, the invested DAI tokens are recollected from the recipients, and given back to the owner.
rDAI contract is ERC20 compliant, and one should use ERC20 transfer or approve functions to transfer the rDAI tokens between addresses.
As a result, the amount of DAI tokens loaned out by the source relevant to the transaction is recollected, and loaned to the new recipients according to the hat of the destination.
Recipients of loaned DAI tokens are entitled to the full amount of interest earned from them.
Anyone can call the payInterest function, which converts the earned interest to new rDAI tokens for the recipient. This mechanism allows contract addresses to also be recipients, despite not having implemented functions to call the payInterest function externally.
Unlike the mint processes, rDAI generated in this process does not loan equal amount of DAI tokens to any recipient. The owner may choose to loan them by using loanInterest, or transfer the rDAI to another address and trigger the hat switching process.
Interest payment rules may apply as per configuration (see Governance section).
In order to maximize the cause the hat owners choose, the following rules are stipulated in order to allow hats to spread to new users:
-
All addresses have the Zero Hat by default.
-
During the transfer process, DAI tokens are recollected and loaned to the new recipients. If the recipient has the Zero Hat, and if the source hat is not a Self Hat, the recipient will inherit the source's hat.
For example: Alice sets UNICEF France as recipients of her generated interest. Bob has never used rDAI, and thus has a Zero Hat. When Alice sends Bob 100 rDAI, Bob inherits Alice's hat, and UNICEF France keep accruing interest. Bob then sends the 100 rDAI along to Charlie. But Charlie already has a hat, so the underlying 100 DAI are now loaned to Charlie's chosen recipients.
As most contract addresses can't execute arbitrary functions, they can generally
only change hat once, from inheritance by the first user to send rDAI to the
contract address.
Because it is sometimes unclear who the owner of a contract is, the rToken
contract allows the admin to change the hat of any contract address.
the ownership by indisputable ownership of the private key, so even admin is not allowed to change that for them.
In order to avoid needing to use the admin, we advise buidlers who are looking to accept rDAI to set up their contracts correctly by:
- getting some rDAI for themselves
- selecting or creating a hat of their choosing
- transferring any amount of rDAI to their contracts
The IAllocationStrategy interface defines what RToken can integrate for investing the underlying assets in exchange for saving assets that earns interest.
It is changeable by admin. Per request, the rDai contract will redeem all underlying assets at once from old allocation strategy, and invest all into new allocation strategy.
CompoundAllocationStrategy is one implementation. In case of rDai, it is cDai.
While it is not possible to forbid admin from using risky strategy, and risk strategy could cause redeemability to fail if the strategy has heavy losses, it is up to the admin to make a sensible choice of what consists of a proper allocation strategy.
(TODO NOTE! The list is not final and some are to be implemented!)
The RToken
contract has an admin role who can:
- Change allocation strategy
- Change hat for any contract address
- Upgrade code
It is up to the rToken
instantiator to decide the degree of decentralization
of this admin. For maximum decentralization, the admin could be a DAO that is
implemented by a DAO framework such as Aragon, and the
hat change could be controlled by a arbitration process such as
(Kleros)(https://kleros.io/).
The project uses truffle as development framework, and the contracts are written in solidity.
The main contract is RToken
, and the interface of it is in IRToken
with more
comments aimed for users of the RToken
contract.
The project also employs the Universal Upgradeable Proxy Standard, or [EIP-1822]
(https://eips.ethereum.org/EIPS/eip-1822]). RTokenStorage
and RTokenStructs
are the storage contract as a result.
The allocation strategy is defined in the IAllocationStrategy
contract.
The compound implementation of it is in the CompoundAllocationStrategy
contract. Compound V2 contracts are pulled from the etherscan and stored under
the compound/contracts
directory. CErc20Interface
contract is used to
implement the CompoundAllocationStrategy
.
Each address has an RToken Account. The account data includes:
hatID
- the hat associated with the account,- internal accounting information,
- account statistics.
There are three types of assets are changing hands during different processes:
- underlying tokens,
rToken
,- saving assets (managed by allocation strategy).
The rules are:
- depositors of underlying token is given equivalent amount of
rToken
, - underlying tokens are "loaned" to the hat recipients as debt,
- underlying tokens are transferred to the allocation strategy and becomes saving assets that are owned by the hat recipients.
Another way to look at is that, hat recipients owes the donor the original
underlying assets as debt denominated in rToken
, while the underlying tokens
are converted to saving assets and owned by the hat recipients.
The related account data properties are:
rAmount
- Redeemable token balance for the account.rInterest
- Redeemable token balance portion that is from interest payment.lRecipients
- Mapping of recipients and their amount of debt.lDebt
- Loan debt amount for the account.sInternalAmount
- Saving asset amount internal.
When some underlying token is transferred to the rToken
contract:
- an equivalent
rAmount
ofrToken
is minted, - underlying tokens are distributed to the hat recipients,
lRecipients
records the amount of underlying tokens owed by each hat recipients,- each hat recipients also adds those amount to their
lDebt
accordingly, - the underlying tokens are transferred to the
AllocationStrategy
, andsInternalAmount
of saving assets are created and owned by the hat recipients.
When user (aka. redeemer) wants to redeem rToken
for underlying tokens:
- a portion of saving assets of each hat recipients are converted back to the
underlying token to cover exact same amount of
rToken
that is asked, - underlying tokens are given back to the redeemer,
- redeemer gets back its underlying tokens.
Ownership change logic is implemented by these two functions.
distributeLoans
- loan underlying tokens to hat recipients and convert them to saving assets.recollectLoans
- convert saving tokens back to underlying assets and pay back debt owned by the hat recipients.
The src
recollectLoans
from its hat recipients, transfers the underlying
tokens recollected to the dst
, then the dst
distributeLoans
to its hat
recipients
To become a allocation strategy, one would need to implement:
exchangeRateStored
- Calculates the exchange rate from the underlying to the saving assetsaccrueInterest
- Applies accrued interest to all savingsinvestUnderlying
- Sender supplies underlying assets into the market and receives saving assets in exchangeredeemUnderlying
- Sender redeems saving assets in exchange for a specified amount of underlying asset
Allocation strategy interface is largely derived from the compound v2 CToken
contract, hence the saving assets is directly denominated in cToken
amount
and the compound allocation strategy is mostly a proxy call to the cToken
contract.
(TODO! NOTE! This feature is still under development!)
RToken
has one saving strategy at a time, and all underlying assets are
transferred to and converted to saving assets that are expected to be liquid
and growing in value measured in underlying tokens.
RToken
allows the admin to switch the allocation strategy during the contract
life time.
When the switching happens, all saving assets are converted to underlying tokens
and then reinvested in new saving assets immediately. There is inevitably a
difference in the exchange rate of different saving assets, a internal property
savingAssetConversionRate
is used for the adjustment, in order to make this
equation true before and after the switching:
savingAssetOrignalAmount = sum(account.sInternalAmount /
savingAssetConversionRate
for all accounts)
- DAI: 0x5592EC0cfb4dbc12D3aB100b257153436a1f0FEa
- cDAI: 0x6d7f0754ffeb405d23c51ce938289d4835be3b14
- rDai (proxy): 0x6AA5c6aB94403Bdbbf74f21607D46Be631E6CcC5
v1
- DaiCompoundAllocationStrategy: 0xB603cd1bdAcaBd5Ca9341d8a44f6430a5e371b76
- rDAI Logic: 0xa401e671eCA4309BDdADA860d5B25C722118b5A1
- DAI: 0xbF7A7169562078c96f0eC1A8aFD6aE50f12e5A99
- cDAI: 0x0A1e4D0B5c71B955c0a5993023fc48bA6E380496
- rDAI (proxy): 0x3183683cEeAb01699722053A2cb6A945cE0D7CeC
v1
- DaiCompoundAllocationStrategy: 0xb4377efc05bd28be8e6510629538e54eba2d74e3
- rDAI Logic: 0xE21dAbb0ea711AF1AbeA2191180407277312f0fe
- DAI: 0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359
- cDAI: 0xf5dce57282a584d2746faf1593d3121fcac444dc
- rDai (proxy): 0xea8b224eDD3e342DEb514C4176c2E72Bcce6fFF9
ethberlin edition
- DaiCompoundAllocationStrategy: 0x21F090905D26073cb488440F98CcfbD8bF5aA9b3
- rDAI Logic: 0x09163bc9da7546ddA9D82Be98FE006a95C87E9B4
v1
- DaiCompoundAllocationStrategy: 0x594e15580468d21D447299F2033Bd203036475FA
- rDAI Logic: 0x2a3ba5E280F70A6C4C6FE4fA7b4d09D496f3296a
Here are some documentations on how one can integrate rDai in applications.
!TODO! embed plantuml sequence diagrams
-
How many addresses are using the hat?
IRToken.getHatStats(hatID).useCount
-
how much loans distributed through the hat currently?
IRToken.getHatStats(hatID).totalLoans
-
how much interest has been accumulated under the hat?
IRToken.getHatStats(hatID).totalSavings - getHatStats(hatID).totalLoans
-
how much loans distributed to the account?
IRToken.receivedLoanOf(owner)
-
how much savings distributed to the account?
IRToken.receivedSavingsOf(owner)
-
how much is cumulative interest generated for the account?
IRToken.getAccountStats(owner).cumulativeInterest
-
total supply
ERC20.totalSuppl
-
total savings amount
IRToken.getGlobalStats().totalSavingsAmount
These IRToken
events will help for indexing stats per account/hat:
- Mint
- Redeem
- LoansTransferred
- InterestPaid
- HatCreated
- HatChanged
For example for these metrics:
- hats sorting by on-chain stats
- monthly/daily active hats
- top interest generating address
- top beneficiaries
- global volumes
- global interest earned by period