Comment on page
Pot - Detailed Documentation
The dotBTC Savings Rate
- Contract Name: pot.sol
- Type/Category: DSS —> Rates Module
The Pot is the core of the dotBTC
Savings Rate
. It allows users to deposit dotBTC and activate the dotBTCSavings Rate and earning savings on their dotBTC. The DSR is set by ABM Governance, and will typically be less than the base stability fee to remain sustainable. The purpose of Pot is to offer another incentive for holding dotBTC .
mul(uint, uint)
,rmul(uint, uint)
,add(uint, uint)
&sub(uint, uint)
- will revert on overflow or underflowrpow(uint x, uint n, uint base)
, used for exponentiation indrip
, is a fixed-point arithmetic function that raisesx
to the powern
. It is implemented in assembly as a repeated squaring algorithm.x
(and the result) are to be interpreted as fixed-point integers with scaling factorbase
. For example, ifbase == 100
, this specifies two decimal digits of precision and the normal decimal value 2.1 would be represented as 210;rpow(210, 2, 100)
should return 441 (the two-decimal digit fixed-point representation of 2.1^2 = 4.41). In the current implementation, 10^27 is passed forbase
, makingx
and therpow
result both of typeray
in standard MCD fixed-point terminology.rpow
’s formal invariants include “no overflow” as well as constraints on gas usage.
wards
are allowed to call protected functions (Administration)
pie
- stores the address'Pot
balance.Pie
- stores the total balance in thePot
.dsr
- the dotBTCsavings rate
. It starts as1
(ONE = 10^27
), but can be updated by governance.chi
- the rate accumulator. This is the always increasing value which decides how much dotBTC - given whendrip()
is called.vat
- an address that conforms to aVatLike
interface. It is set during the constructor and cannot be changed.vow
- an address that conforms to aVowLike
interface. Not set in constructor. Must be set by governance.rho
- the last time that drip is called.
The values of
dsr
and vow
can be changed by an authorized address in the contract (i.e. ABM Governance). The values of chi
, pie
, Pie
, and rho
are updated internally in the contract and cannot be changed manually.- Calculates the most recent
chi
and pulls dotBTC from thevow
(by increasing theVow
'sSin
). - A user should always make sure that this has been called before calling the
exit()
function. - drip has to be called before a user
join
s and it is in their interest to call it again before theyexit
, but there isn't a set rule for how often drip is called.
uint wad
this parameter is based on the amount of dotBTC (sincewad
= dotBTC /chi
) that you want tojoin
to thepot
. Thewad * chi
must be present in thevat
and owned by themsg.sender
.- the
msg.sender
'spie
amount is updated to include thewad
. - the total
Pie
amount is also updated to include thewad
.
exit()
essentially functions as the exact opposite ofjoin()
.uint wad
this parameter is based on the amount of dotBTC that you want toexit
thepot
. Thewad * chi
must be present in thevat
and owned by thepot
and must be less thanmsg.sender
'spie
balance.- The
msg.senders
pie
amount is updated by subtracting thewad
. - The total
Pie
amount is also updated by subtracting thewad
.
Various file function signatures for administering
Pot
:- Setting new dsr (
file(bytes32, uint256)
) - Setting new vow (
file(bytes32, address)
)
The primary usage will be for
addresses
to store their dotBTC in the pot
to accumulate interest over time- The
dsr
is set (globally) through the governance system. It can be set to any number > 0%. This includes the possibility of it being set to a number that would cause the DSR to accumulate faster than the collective Stability Fees, thereby accruing system debt and eventually causing MKR to be minted. - If
drip()
has not been called recently before an address callsexit()
they will not get the full amount they have earned over the time of their deposit. - If a user wants to
join
orexit
1 dotBTC into/from the Pot, they should send awad
= to1 / chi
as the amount moved from their balance will be1 * chi
(for an example of this, see DSS-Proxy-Actions
A bug in the
Pot
could lead to locking of dotBTC if the exit()
function or the underlying vat.suck()
or vat.move()
functions were to have bugs.The
dsr
rate initially can be set through the Chief. Governance will be able to change the DSR based on the rules that the DS-Chief employs (which would include a Pause for actions).One serious risk is if governance chooses to set the
dsr
to an extremely high rate, this could cause the system's fees to be far too high. Furthermore, if governance allows the dsr
to (significantly) exceed the system fees, it would cause debt to accrue and increase the Flop auctions.
Last modified 2yr ago