CDP Manager - Detailed Documentation
Managing Vaults to be transferred between users
Contract Name: cdpManager.sol
Type/Category: Vault Management
1. Introduction (Summary)
Summary: The DssCdpManager
(aka manager
) was created to enable a formalized process for Vaults to be transferred between owners, much like assets are transferred. It is recommended that all interactions with Vaults be done through the CDP Manager. Once unlocked collateral has been deposited into the Maker Protocol, users can make use of the following features:
Multi Vault ownership and numerical identification (users can own N number of Vaults)
Vault transferability
Note: The MCD system diagram above shows that the Vault user goes through the proxy in order to interact with the CDP Manager but it is also possible to directly use the CDP Manager contract.
2. Contract Details
Key Functionalities (as defined in the smart contract)
cdpAllow(uint cdp, address usr, uint ok)
: Allow/Disallow (ok
) ausr
address to manage thecdp
.urnAllow(address usr, uint ok)
: Allow/Disallow (ok
) ausr
address to interact with an urn for the purposes of either entering (src
) or quitting (dst).
open(bytes32 ilk, address usr)
: Opens a new Vault forusr
to be used for anilk
collateral type.give(uint cdp, address dst)
: Transferscdp
todst
.frob(uint cdp, int dink, int dart)
: Increments/decrements theink
amount of collateral locked and increments/decrements theart
amount of debt in thecdp
depositing the generated DAI or collateral freed in thecdp
address.frob(uint cdp, address dst, int dink, int dart)
: Increments/decrements theink
amount of collateral locked and increments/decrements theart
amount of debt in thecdp
depositing the generated DAI or collateral freed into a specifieddst
address.flux(bytes32 ilk, uint cdp, address dst, uint wad)
: Moveswad
(precision 18) amount of collateralilk
fromcdp
todst
.flux(uint cdp, address dst, uint wad)
: Moveswad
amount ofcdp
collateral fromcdp
todst
.move(uint cdp, address dst, uint rad)
: Movesrad
(precision 45) amount of DAI fromcdp
todst
.quit(uint cdp, address dst)
: Moves the collateral locked and debt generated fromcdp
todst
.
Note: dst
refers to the destination address.
Storage Layout
vat
: core contract address that holds the Vaults.cdpi
: Auto incremental id.urns
: MappingCDPId => UrnHandler
list
: MappingCDPId => Prev & Next CDPIds
(double linked list)owns
: MappingCDPId => Owner
ilks
: MappingCDPId => Ilk
(collateral type)first
: MappingOwner => First CDPId
last
: MappingOwner => Last CDPId
count
: MappingOwner => Amount of CDPs
allows
: MappingOwner => CDPId => Allowed Addr => True/False
3. Key Mechanisms & Concepts
Summary
The CDP Manager was created as a way to enable Vaults to be treated more like assets that can be exchanged. Originally, the dss core contracts did not have the functionality to enable transferring Vault positions. The CDP Manager was created to wrap this functionality and enable transferring between users.
High-level Purpose
The
manager
receives thevat
address in its creation and acts as an interface contract between it and the users.The
manager
keeps an internal registry ofid => owner
andid => urn
allowing for theowner
to executevat
functions for theirurn
via themanager
.The
manager
keeps a double linked list structure that allows the retrieval of all the Vaults that anowner
has via on-chain calls.In short, this is what the
GetCdps
is for. This contract is a helper contract that allows the fetching of all the Vaults in just one call.
CDP Manager Usage Example (common path):
A User executes
open
and gets aCDPId
in return.After this, the
CDPId
gets associated with anurn
withmanager.urns(cdpId)
and thenjoin
's collateral to it.The user can then execute
frob
to choose whichdst
address they want to use to send the generated DAI to.If the user executes
frob
withoutdst
then the generated DAI will remain in the Vault'surn
. In this case, the user canmove
it at a later point in time.Note that this is the same process for collateral that is freed after
frob
(for thefrob
function that doesn't require thedst
address). The user canflux
it to another address at a later time.
In the case where a user wants to abandon the
manager
, they can usequit
as a way to migrate their position of their Vault to anotherdst
address.
4. Gotchas (Potential source of user error)
For the developers who want to integrate with the
manager
, they will need to understand that the Vault actions are still in theurn
environment. Regardless of this, themanager
tries to abstract theurn
usage by aCDPId
. This means that developers will need to get theurn
(urn = manager.urns(cdpId)
) to allow thejoin
ing of collateral to that Vault.As the
manager
assigns a specificilk
perCDPId
and doesn't allow others to use it for theirs, there is a secondflux
function which expects anilk
parameter. This function has the simple purpose of taking out collateral that was wrongly sent to a Vault that can't handle it/is incompatible.Frob Function(s):
When you
frob
in the CDP manager, you generate new DAI in thevat
via the CDP manager which is then deposited in theurn
that the CDP manager manages. This process depends on whichfrob
function you use (there exist twofrob
functions). In short, one allows a destination address and the other doesn’t require it.If you use the
frob
function that has the destiny (dst
) address, you are saying that you can send any Dai generated or collateral that has been freed. The secondfrob
function is meant for leaving the collateral in theurn
address because theurn
is owned by the CDP manager. In this case, you would need to manually use theflux
ormove
functions to get the DAI or collateral out. These functions (flux
andmove
) may be more beneficial for a developer working with the proxy function, as it allows for more flexibility. For example, by using these functions you can move a specific amount of collateral and can use the other functions to do it. Overall, it can make working with it a little more flexible on specific developer needs.
As mentioned above in the summary, the dss core contracts originally did not have the functionality to enable the transfer of Vault positions. Since then, the core contracts have also implemented a native transfer functionality called
fork
which allows the transferring of a Vault to another address. However, there is a restriction, which is that the address owner that will be receiving the Vault needs to provide authorization that they do in fact want to receive it. This was created for the situation when a user is transferring the collateral that is locked as well as the debt generated. If you are simply moving collateral to another address, there is no issue but in the case that you are also transferring the debt generated, there is a chance of putting a perfectly safe Vault in a risky position. This makes the contract functionality a little more restrictive. Therefore, the CDP manager is a good option to keep a simple way of transferring Vaults and recognizing them via a numeric ID.
5. Failure Modes (Bounds on Operating Conditions & External Risk Factors)
Potential Issues around Chain Reorganization
When open
is executed, a new urn
is created and a cdpId
is assigned to it for a specific owner
. If the user uses join
to add collateral to the urn
immediately after the transaction is mined, there is a chance that a reorganization of the chain occurs. This would result in the user losing the ownership of that cdpId
/urn
pair, therefore losing their collateral. However, this issue can only arise when avoiding the use of the proxy functions via a profile proxy as the user will open
the cdp
and join
collateral in the same transaction.
Last updated