This is a developer level guide to the Sai source layout and how the different objects relate to each other.
Sai is Simple-Dai, a simplification of the Dai Stablecoin System intended for field testing and refining Dai components. Sai has several features that distinguish it from Dai:
- trusted price feed
- single collateral type
- global settlement
- liquidations at fixed price (rather than auctions)
This document is an introduction to Sai, aimed at those seeking an understanding of the Solidity implementation. We assume knowledge of the white paper, a high level overview of Dai. A reading of the purple paper, the (in progress) detailed Dai technical specification and reference implementation is useful but not required.
XXX: include LL link?
There is ongoing work to specify Sai (and Dai) using Linear Logic, forming the teal paper. This is at a very early draft stage and is provided for interest. Eventually, this work aims to allow formal reasoning about system properties.
Blockchain applications are a constrained environment. This neccesitates constrained language. It is no accident that reading the Sai and Dai source feels like reading assembly at times.
The idiosyncratic terms used within are affectionately referred to as 'memes':
- four letter memes are typically used for functions that effect state transitions, and are referred to as 'acts'.
- three letter memes are used for variables, constants, and derived quantities.
Sai uses the following tokens:
gem: underlying collateral (wrapped ether, in practice)skr: abstracted collateral claimsai: stablecoinsin: anticoin, created and destroyed 1:1 withsai
Sai has the following core components:
jar: A token wrappertub: CDP record storetip: target price feedtap: liquidation mechanismtop: global settlement facilitator
TODO: jar, pot and pit vault info
TOOD: risk parameters
The jar is a token wrapper.
join: depositgemin return forskrexit: claimgemwith theirskr.
skr is a simple proportional claim on a collateral pool, with the
initial gem<->skr exchange ratio being 1:1. The essential reason
for this abstraction will be developed later, but for now it is
sufficient to see skr as a token with intrinsic value.
The gem/skr exchange rate is called per, and is calculated as the
total number of deposited gem divided by the total supply of SKR.
The reference price of gem (in practice, ETHUSD) is provided by the
pip, an external oracle. The pip is completely trusted.
The reference price of skr is then given by the dynamic tag, e.g.
the price of SKR in USD.
The tip is a simple oracle for the Sai target price, given in terms
of the reference unit, by par. For example, par == 2 with USD as
the reference unit implies a target price of 2 USD per Sai.
The target price can vary in time, at a rate given by way, which is
the multiplicative rate of change per second.
The tub is the CDP record system. An individual CDP is called a cup
(i.e. a small container), and has:
lad: an ownerink: locked SKR collateralart: debt
It is crucial to know whether a CDP is well collateralised or not:
safe(cup) returns a boolean indicating this.
safe aggregates price information from the tip and the jar and
compares the reference value of a CDPs debt and collateral.
The following tub acts are not possible if they would transition a CDP
to unsafe:
open: create a new CDPgive: transfer ownership (changeslad)
lock: deposit SKR collateral (increasesink)free: withdraw SKR collateral (decreasesink)
draw: create Sai (increasesart)wipe: return Sai (decreasesart)
shut: clear all CDP debt, unlock all collateral, and delete the record
bite: liquidate CDP (zerosart, decreasesink, transferssintopit)
Unsafe CDPs need to be liquidated. When a cup is not safe, anyone
can perform bite(cup), which takes on all CDP debt and confiscates
sufficient collateral to cover this, plus a buffer.
This returns the CDP to a safe state (possibly with zero collateral).
There are other possible implementations of bite, e.g. only taking
sufficient collateral to just transition the CDP to safe, but the
described implementation is chosen for simplicity.
bite transfers the sin associated with the CDP to the pit - the
liquidator vault.
The tap is a liquidator. It has three token balances that determine
its allowed behaviour:
joy: Sai balance, surplus transferred fromdripwoe: Sin balance, bad debt transferred frombitefog: SKR balance, collateral pending liquidation
and one derived price, s2s, which is the price of SKR in Sai. The
tap seeks to minimise all of its token balances. Recall that Sai can
be canceled out with Sin via heal.
The tap has two acts:
boom: sell Sai in return for SKR (decreasesjoyandwoe, decreases SKR supply)bust: sell SKR in return for Sai (decreasesfog, increasesjoyandwoe, can increase SKR supply)
boom is the simpler function and can be thought of as buy and burn.
Given a net Sai balance, sell the Sai in return for SKR, which is
burned.
bust is really two functions in one: collateral sell off, and
inflate and sell. When fog is non zero it is sold in return for Sai,
which is used to cancel out the bad debt, woe. If fog is zero but
the tap has a net Sin balance, then SKR is minted and sold in return
for Sai, up to the point that the net Sin balance is zero.
Through boom and bust we close the feedback loop on the price of
SKR. When there is surplus Sai, SKR is burned, decreasing the SKR supply
and increasing per, giving SKR holders more GEM per SKR. When there is
surplus Woe, SKR is inflated, increasing the SKR supply and decreasing
per, giving SKR holders less GEM per SKR.
The reason for wrapping GEM in the jar is now apparent: it provides a
way to socialise losses and gains incurred in the operation of the system.
Two features of this mechanism:
-
Whilst SKR can be inflated significantly, there is a finite limit on the amount of bad debt the system can absorb - given by the value of the underlying GEM collateral.
-
There is a negative feedback between
bustandbite: as SKR is inflated it becomes less valuable, reducing the safety level of CDPs. Some CDPs will become unsafe and be vulnerable to liquidation, creating more bad debt. In an active market, CDP holders will have to be vigilant about the potential for SKR inflation if they are holding tightly collateralised CDPs.
Other components need very little awareness of what top does.
top just needs authority to move balances from vaults.
This also serves as a useful frontend entrypoint to the system, as it links to all other components.
TODO: finish this
In a simpler system with no interest rates, we could denominate CDP debt,
the tab, directly in sin. However with non zero interest, tab is a
dynamic quantity, computed from art, a per CDP debt unit, and chi,
the price of this debt unit in sin.
tab(cdp) = cdp.art * chi
The internal debt price, chi, is dynamic and is updated by the drip
act, which also collects unprocessed revenue.
The chi abstraction allows us to compute the per CDP debt, and the
total unprocessed revenue, with varying tax, in constant time.
ds-auth is used, with no owners (XXX: check) and two authorities:
-
dad: ds-guard, used for internal authority -
mom: ds-roles, used for external authority
The auth setup looks as follows: sai-auth.jpeg [XXX: do this in graphviz]
drip== 1 (optimisation)authon all functions
authonly on admin functions- updated to latest dappsys
Scripts, scripts, scripts.. also see test setup.
Script output gist
per: gem per skrpar: ref per saitag: ref per skrpip: ref per gemprice: sai per gemfix: gem per sai aftercagefit: gem per skr aftercage
-
pip: trading pips -
jar: where collateral is kept -
tip: target price tip-off -
cup: small container for CDP info -
tub: larger container for cups -
tap: liquidity provider -
top: top-level system manager -
way: which way the target price is heading -
mat: -
hat: -
axe -
tax -
gap -
air -
fog -
joy: SKR holders are happy about this -
woe: SKR holders are sad about this -
pot: -
pit: where to put unwanted things