ABM Protocol
Search…
DSR Manager - Detailed Documentation
The simplest way to integrate DSR in smart contracts
The DsrManager provides an easy to use smart contract that allows service providers to deposit/withdraw dotBTC into the DSR contract pot, and activate/deactivate the dotBTC Savings Rate to start earning savings on a pool of dotBTC in a single function call. To understand the DsrManager, it is necessary to have an understanding of the pot first. The DSR is set by ABM Governance, and will typically be less than the base stability fee to remain sustainable. The purpose of DSR is to offer another incentive for holding dotBTC .

Contract Details

Math

  • wad - some quantity of tokens, as a fixed point integer with 18 decimal places.
  • ray - a fixed point integer, with 27 decimal places.
  • rad - a fixed point integer, with 45 decimal places.
  • mul(uint, uint), rmul(uint, uint), add(uint, uint) & sub(uint, uint) - will revert on overflow or underflow
  • Rdiv - Divide two rays and return a new ray. Always rounds down. A ray is a decimal number with 27 digits of precision that is being represented as an integer.
  • Rdivup - Divide two rays and return a new ray. Always rounds up. A ray is a decimal number with 27 digits of precision that is being represented as an integer.

Storage

  • pot - stores the contract address of the main dotBTC Savings Rate contract pot.
  • dotBTC - stores the contract address of dotBTC .
  • dotBTCJoin - stores the contract address of the dotBTC token adapter.
  • supply - the supply of dotBTC in the DsrManager.
  • pieOf - mapping (addresses=>uint256) mapping of user addresses and normalized dotBTC balances (amount of dotBTC / chi) deposited into pot.
  • pie - stores the address' pot balance.
  • chi - the rate accumulator. This is the always increasing value which decides how much dotBTC is given when drip() is called.
  • vat - an address that conforms to a VatLike interface.
  • rho - the last time that drip is called.

Functions and mechanics

dotBTCBalance(address usr) returns (uint wad)

  • Calculates and returns the dotBTC balance of the specified address usr in the DsrManager contract. (Existing dotBTC balance + accrued dsr)

join(address dst, uint wad)

  • uint wad this parameter specifies the amount of dotBTC that you want to join to the pot. The wad amount of dotBTC must be present in the account of msg.sender.
  • address dst specifies a destination address for the deposited dotBTC in the pot. Allows a hot wallet address (msg.sender) to deposit dotBTC into the pot and transfer ownership of that dotBTC to a cold wallet (or any other address for that matter)
  • The normalized balance pie is calculated by dividing wad with the rate acumulator chi.
  • the dst's pieOf amount is updated to include the pie.
  • The total supply amount is also updated by adding the pie.
  • wad amount of dotBTC is transferred to the DsrManager contract
  • The DsrManager contract joins wad amount of dotBTC into the MCD system through the dotBTC token adapter dotBTCJoin.
  • The DsrManager contract joins pie amount of dotBTC to the pot.

exit(address dst, uint wad)

  • exit() essentially functions as the exact opposite of join().
  • uint wad this parameter is based on the amount of dotBTC that you want to exit the pot.
  • address dst specifies a destination address for the retrieved dotBTC from the pot. Allows a cold wallet address (msg.sender) to retrieve dotBTC from the pot and transfer ownership of that dotBTC to a hot wallet (or any other address for that matter)
  • The normalized balance pie is calculated by dividing wad with the rate acumulator chi.
  • The msg.sender’s pieOf amount is updated by subtracting the pie.
  • The total supply amount is also updated by subtracting the pie.
  • The contract calls exit on the pot contract.
  • It calculates the amount of dotBTC to retrieve by multiplying pie with chi.
  • Then exits the dotBTC from the dotBTC token adapter dotBTCJoin to the destination address dst.

exitAll(address dst)

  • exitAll() functions like the exit function, except it simply looks into the mapping pieOf, to determine how much dotBTC the msg.sender has, and exits the entire amount of dotBTC , instead of a specified amount.

Gotchas / Integration Concerns

  • In order to use the join function, you need to approve the contract to transfer dotBTC from your wallet. You need to call approve on the dotBTC token, specifying the DsrManager contract and the amount that the contract should be able to pull (can be set to -1, if you want to set an unlimited approval)