Add CDP Spec #328

rhuairahrighairidh · 2020-01-22T18:52:16Z

TODO

Notes:

The "Markdown Table Formatter" VSCode extension is useful for formatting tables for the events specs
This is a new branch with cherry-picked commits, old one was a git mess.

Proposal:

Add a broken url link checker to CI? It found a couple in the spec.

karzak

Looking good! Left a few comments regarding terms and concepts, then mostly typos/wording suggestions.

x/cdp/spec/01_concepts.md

karzak · 2020-01-22T19:01:42Z

x/cdp/spec/01_concepts.md

+
+In the event of a decrease in the price of the collateral, the total value of all collateral in CDPs may drop below the value of all the issued pegged asset. This undesirable event is countered through two mechanisms.
+
+**CDP Liquidations** Each CDP is monitored for ratio of collateral value to debt value. When this drops too low the collateral and debt is seized by the system. The collateral is sold off through an auction to bring in pegged asset which is burned against the seized debt.


Unclear use of 'pegged asset'. I think this could be confusing to outside readers. I would reccommend stable asset instead.

karzak · 2020-01-22T19:03:25Z

x/cdp/spec/02_state.md

+Listed here is the state stored by the module.
+For details see the types package. In particular `keys.go` describes how state is stored in the key-value store.
+<!--
+Store key structures are not listed here - they seem like an implementation detail best documented by code comments.


Remove comment. I'm fine with leaving the keys to code comments.

karzak · 2020-01-22T19:03:35Z

x/cdp/spec/02_state.md

+# State
+
+Listed here is the state stored by the module.
+For details see the types package. In particular `keys.go` describes how state is stored in the key-value store.


link to the file keys.go

karzak · 2020-01-22T19:49:43Z

x/cdp/spec/03_messages.md

+
+## DrawDebt
+
+DrawDebt creates debt in a CDP, minting new pegged asset which is sent to the sender.


Suggested change

DrawDebt creates debt in a CDP, minting new pegged asset which is sent to the sender.

DrawDebt creates debt in a CDP, minting new stable asset which is sent to the sender.

karzak · 2020-01-22T19:50:25Z

x/cdp/spec/03_messages.md

+## DrawDebt
+
+DrawDebt creates debt in a CDP, minting new pegged asset which is sent to the sender.
+<!-- TODO Can the sender own have same collateral multiple CDPs? if so how do they choose between them.  -->


Remove comment. Not sure what's being asked... clarify if you still have questions.

karzak · 2020-01-22T19:51:28Z

x/cdp/spec/03_messages.md

+
+- `Collateral` taken from depositor and sent to cdp module account
+- the depositor's `Deposit` struct is updated or a new one created
+- fees are updated (see below)


do we want to mention that the collateral index is updated? Same applies to other state changes.

I'd be in favour of leaving it out. I'd prefer not to describe too much details

karzak · 2020-01-22T19:54:01Z

x/cdp/spec/04_begin_block.md

+## Update Fees
+
+- The total fees accumulated since the last block across all CDPs are calculated.
+- An equal amount of debt coins are minted and sent to the system's liquidator module account.


Suggested change

- An equal amount of debt coins are minted and sent to the system's liquidator module account.

- An equal amount of debt coins are minted and sent to the system's cdp module account.

- An equal amount of stable asset coins are minted and sent to the system's liquidator module account

karzak · 2020-01-22T19:54:34Z

x/cdp/spec/04_begin_block.md

+
+## Net Out System Debt, Re-Balance
+
+- Burn the maximum possible equal amount of debt and pegged asset from the liquidator module account.


Suggested change

- Burn the maximum possible equal amount of debt and pegged asset from the liquidator module account.

- Burn the maximum possible equal amount of debt and stable asset from the liquidator module account.

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

karzak

A few final suggestions, LGTM after those changes.

x/cdp/spec/06_params.md

x/cdp/spec/README.md

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

* 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>

rhuairahrighairidh added 16 commits January 21, 2020 23:25

add overview and basic structure

ccea662

add state and params

6c39cba

add basic messages

4279b30

add state transitions

05bc9ef

add begin block state transitions

8c38df0

add missing titles

220cacd

add concepts

29a2fc7

add events

56be7ca

update state and concepts

3128d82

update for liquidator changes

2d64b0d

update events

4f3be98

mention module accounts

167d5ec

update begin block

cb3b4dd

update params

a85836c

update page numbering

f279aff

add fee descriptions

71ce814

rhuairahrighairidh mentioned this pull request Jan 22, 2020

WIP Add CDP Spec #286

Closed

6 tasks

rhuairahrighairidh added 3 commits January 22, 2020 19:53

add broken link linter

697019d

add broken link linter to CI

677440c

move link check to end of CI

eea24f0

rhuairahrighairidh added the R4R When a PR is ready for review label Jan 22, 2020

rhuairahrighairidh requested review from karzak and denalimarsh January 22, 2020 20:00

karzak requested changes Jan 22, 2020

View reviewed changes

rhuairahrighairidh and others added 2 commits January 22, 2020 21:57

update typo

2f642c7

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

address review comments

70308c2

rhuairahrighairidh requested a review from karzak January 23, 2020 14:27

karzak requested changes Jan 23, 2020

View reviewed changes

x/cdp/spec/06_params.md Outdated Show resolved Hide resolved

x/cdp/spec/README.md Outdated Show resolved Hide resolved

x/cdp/spec/README.md Outdated Show resolved Hide resolved

rhuairahrighairidh and others added 2 commits January 23, 2020 18:28

Update x/cdp/spec/06_params.md

988ff6d

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

Update x/cdp/spec/README.md

6f464ee

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

Update x/cdp/spec/README.md

e16d89e

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

karzak approved these changes Jan 23, 2020

View reviewed changes

karzak merged commit e11b298 into develop Jan 23, 2020

rhuairahrighairidh deleted the ro-add-cdp-module-spec branch January 24, 2020 00:41

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add CDP Spec #328

Add CDP Spec #328

rhuairahrighairidh commented Jan 22, 2020 •

edited

Loading

karzak left a comment

karzak Jan 22, 2020

karzak Jan 22, 2020

karzak Jan 22, 2020

karzak Jan 22, 2020

karzak Jan 22, 2020

karzak Jan 22, 2020

rhuairahrighairidh Jan 23, 2020

karzak Jan 22, 2020

karzak Jan 22, 2020

karzak left a comment


		In the event of a decrease in the price of the collateral, the total value of all collateral in CDPs may drop below the value of all the issued pegged asset. This undesirable event is countered through two mechanisms.

		CDP Liquidations Each CDP is monitored for ratio of collateral value to debt value. When this drops too low the collateral and debt is seized by the system. The collateral is sold off through an auction to bring in pegged asset which is burned against the seized debt.


		## DrawDebt

		DrawDebt creates debt in a CDP, minting new pegged asset which is sent to the sender.

	- An equal amount of debt coins are minted and sent to the system's liquidator module account.
	- An equal amount of debt coins are minted and sent to the system's cdp module account.
	- An equal amount of stable asset coins are minted and sent to the system's liquidator module account


		## Net Out System Debt, Re-Balance

		- Burn the maximum possible equal amount of debt and pegged asset from the liquidator module account.

Add CDP Spec #328

Add CDP Spec #328

Conversation

rhuairahrighairidh commented Jan 22, 2020 • edited Loading

karzak left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

karzak left a comment

Choose a reason for hiding this comment

rhuairahrighairidh commented Jan 22, 2020 •

edited

Loading