0g-chain/x/cdp/spec/02_state.md
Ruaridh e11b298c28 Add CDP Spec (#328)
* add overview and basic structure

* add state and params

* add basic messages

* add state transitions

* add begin block state transitions

* add missing titles

* add concepts

* add events

* update state and concepts

* update for liquidator changes

* update events

* mention module accounts

* update begin block

* update params

* update page numbering

* add fee descriptions

* add broken link linter

* add broken link linter to CI

* move link check to end of CI

* update typo

Co-Authored-By: Kevin Davis <karzak@users.noreply.github.com>

* address review comments

* Update x/cdp/spec/06_params.md

Co-Authored-By: Kevin Davis <karzak@users.noreply.github.com>

* Update x/cdp/spec/README.md

Co-Authored-By: Kevin Davis <karzak@users.noreply.github.com>

* Update x/cdp/spec/README.md

Co-Authored-By: Kevin Davis <karzak@users.noreply.github.com>

Co-authored-by: Kevin Davis <karzak@users.noreply.github.com>
2020-01-23 14:09:36 -05:00

68 lines
2.2 KiB
Markdown

# State
For detail on the state tracked by the cdp module see the types package. In particular [keys.go](../types/keys.go) describes how state is stored in the key-value store.
## Module Accounts
The cdp module account controls two module accounts:
**CDP Account:** Stores the deposited cdp collateral, and the debt coins for the debt in all the cdps.
**Liquidator Account:** Stores debt coins that have been seized by the system, and any stable asset that has been raised through auctions.
## CDP
A CDP is a struct representing a debt position owned by one address. It has one collateral type and records the debt that has been drawn and how much fees should be repaid.
Only an owner is authorized to draw or repay debt, but anyone can deposit collateral to a CDP. Deposits are scoped per address and are recorded separately in `Deposit` types. Depositors are free to withdraw their collateral provided it does not put the CDP below the liquidation ratio.
The CDP's collateral always equal to the total of the deposits.
```go
type CDP struct {
ID uint64
Owner sdk.AccAddress
Collateral sdk.Coins
Principal sdk.Coins
AccumulatedFees sdk.Coins
FeesUpdated time.Time
}
```
CDPs are stored with a couple of database indexes for faster lookup:
- by collateral ratio - to look up cdps that are close to the liquidation ratio
- by owner index - to look up cdps that an address is the owner of
## Deposit
A Deposit is a struct recording collateral added to a CDP by one address. The address only has authorization to change their deposited amount (provided it does not put the CDP below the liquidation ratio).
```go
type Deposit struct {
CdpID uint64
Depositor sdk.AccAddress
Amount sdk.Coins
}
```
## Params
Module parameters controlled by governance. See [Parameters](06_params.md) for details.
## NextCDPID
A global counter used to create unique CDP ids.
## DebtDenom
The name of the internal debt coin. Its value can be configured at genesis.
## Total Principle
Sum of all non seized debt plus accumulated fees. This is used to calculate the new debt created every block due to the fee interest rate.
## Previous Block Time
A record of the last block time used to calculate fees.