From ec33cd9fe890e52983e123f16b36f5fae4261d2d Mon Sep 17 00:00:00 2001 From: 0xcentur1on Date: Fri, 18 Aug 2023 17:39:24 -0300 Subject: [PATCH] docs: improve project's instructions --- vat_guide.md | 79 +++++++++++++++++++++++++++++++++------------------- 1 file changed, 51 insertions(+), 28 deletions(-) diff --git a/vat_guide.md b/vat_guide.md index 35fae30..995d57b 100644 --- a/vat_guide.md +++ b/vat_guide.md @@ -1,12 +1,8 @@ -# Maker DAO VAT Smart Contract +# Understanding Maker DAO VAT Smart Contract -Project to explain Maker DAO VAT Smart Contract and how to setup and interact with it. +Project to explain what is, how to setup, and interact with Maker DAO VAT Smart Contract. -## Minimal `Vat` setup - -In order to run this project to understand the Maker DAO VAT Smart Contract and its operation you need to perform the setup below. To reproduce an environment -very close to what we have in mainnet the original contracts Maker DAO VAT contracts are deploying using the project -[Rome DAO](https://github.com/dewiz-xyz/rome-dao). +## Enviroment Setup ### Setup localchain using GETH @@ -27,33 +23,43 @@ export FOUNDRY_ETH_PASSWORD_FILE=$ETH_PASSWORD ### Setup auxiliary tooling -Make sure you have node, shfmt and foundry installed. +Make sure you have **node.js**, **shfmt** and **foundry** installed. ## Deploying artifacts +In order to run this project to understand the Maker DAO VAT Smart Contract and its operations you need to deploy it and other Smart Contracts configure them. +Below are for instructions deployment and example scripts that will help you to do it and most importantly to help you to understand why these artifacts +are needed. + +Due changes in Solidity arithmetics from version 0.5.x to 0.8.x the Maker DAO's DSS Smart Contracts need to be compiled using 0.6.x version to avoid overflow +errors when `frob` method is called - you will see more details about it below. So, we split this example project in two. `Rome DAO` simulates Maker DAO very +close to what we have in mainnet and this project simulates an user operating it using the Solidity version 0.8.x + +Hence, when you see `from Rome DAO` instruction below please use scripts saved in `Rome DAO` project. Its URL is https://github.com/dewiz-xyz/rome-dao + ### Deploy your own "Dai" token `$DAI` from Rome DAO -Deploy an ERC-20 that you control +Deploy an ERC-20 to simulate `DAI` tokens. It will be managed by the protocol, Rome DAO, that simulates Maker DAO mechanisms. Example: ```bash -./scripts/forge-script.sh ./src/Cent.s.sol:CenturionDaiDeploy --fork-url=$RPC_URL --broadcast -vvvv +./scripts/forge-script.sh ./src/dai.s.sol:DaiDeploy --fork-url=$RPC_URL --broadcast -vvvv ``` ### Deploy `Vat` from Rome DAO -Deploy `Vat` from `vat.sol` +Deploy `Vat` from `vat.sol`. VAT is the main compoment of Maker DAO. It manages the DAI supply versus debts tokenized in different collaterals. Example: ```bash -./scripts/forge-script.sh ./src/SampleVat.s.sol:SampleVatDeploy --fork-url=$RPC_URL --broadcast -vvvv +./scripts/forge-script.sh ./src/vat.s.sol:VatDeploy --fork-url=$RPC_URL --broadcast -vvvv ``` ### Deploy your ERC-20 token `$DENARIUS` -Deploy an ERC-20 that you control +Deploy an ERC-20 that simulates a tokenized asset you want to be a collateral for Rome DAO's `DAI`. Example: @@ -63,7 +69,8 @@ Example: ### Deploy `GemJoin` from Rome DAO -Deploy a `GemJoin` contract from `join.sol` and allow it to spend your collateral +Deploy a `GemJoin` contract from `join.sol` and allow it to spend your collateral. `GemJoin` holds your collateral and `Vat` Smart Contract use it to manage +them. ```solidity GemJoin(address vat, bytes32 ilk, address gem); @@ -84,7 +91,7 @@ Example: ### Deploy `DaiJoin` from Rome DAO -Deploy a `DaiJoin` contract from `join.sol` +Deploy a `DaiJoin` contract from `join.sol`. `DaiJoin` holds `DAI` and `Vat` Smart Contract use it to manage them. ```solidity DaiJoin(address vat, address dai) @@ -101,7 +108,7 @@ Example: ./scripts/forge-script.sh ./src/DaiJoin.s.sol:DaiJoinDeploy --fork-url=$RPC_URL --broadcast -vvvv ``` -Then, using Rome DAO scripts: +Then, using `Rome DAO` scripts for: 1. Allow `DaiJoin` to **mint** `$DAI` 2. Allow `DaiJoin` to **burn** `$DAI` @@ -116,9 +123,9 @@ Example: ### `Vat` initialization from Rome DAO -Authorize the contracts on the `Vat`, initialize it, set the global debt ceiling, set collateral debt ceiling, and set collateral price +`Vat` needs to rely on (authorize) `GemJoin` and `DaiJoin` Smart Contracts, initialize it. Also it is needed to set the global debt ceiling, set collateral debt ceiling, and set the collateral price. -`rely` on both join contracts +See the sample code below: ```solidity vat.rely(); @@ -135,7 +142,7 @@ Example: ./scripts/forge-script.sh ./src/vat.s.sol:VatInitialize --fork-url=$RPC_URL --broadcast -vvvv ``` -### Below explanation about the debt/collateral definitions in `VAT` +### Detailed explanation about the debt/collateral definitions in `VAT` #### Set the global debt ceiling using `Line` (with capital `L`) @@ -145,6 +152,9 @@ vat.file('Line', 1_000_000 * 10**45); // RAD: 45 decimals #### Set collateral debt ceiling `line` (with lower `l`) +Pay attention that now you define a name for your collateral, in our case: `Denarius-A`. The collateral data is stored within a struct called `ilk`. There is a +mapping called `ilks` that allow the `Vat` supports several collaterals with different rate configurations. + ```solidity vat.file('Denarius-A', 'line', 1_000_000 * 10**45); // RAD: 45 decimals ``` @@ -181,12 +191,14 @@ This will add collateral to the system, but it will remain **unemcumbered** (not ``` - `dink`: how much collateral to lock(+ add ) or unlock(- sub) within `Vat`. It means the collateral is now **encumbered** (locked) into the system. -- `dart`: how much **normalized debt** to add(+)/remove(-). Remember that `debt = ilk.rate * urn.art` . To get the value for `dart`, divide the desired amount +- `dart`: how much **normalized debt** to add(+)/remove(-). Remembering `debt = ilk.rate * urn.art` . To get the value for `dart`, divide the desired amount by `ilk.rate` (this is a floating point division, which can be tricky). See the [RwaUrn](https://github.com/makerdao/rwa-toolkit/blob/8d30ed2cb657641253d45b57c894613e26b4ae1b/src/urns/RwaUrn.sol#L156-L178) component to understand how it can be done -- Recommendation: respect `dink = dart*2` when calling `vat.frob` for drawing to make the collateralization rate in 200%. +- Recommendation: to leave `dink = dart*2` when calling `vat.frob` for drawing to make the collateralization rate in 200%. ### Get ERC-20 `$DAI` +Now it is a great time. Calling the method below after `vat.frob` you are allowed to receive `$DAI` in your wallet. + ```solidity daiJoin.exit(, ); // with 10**18 precision ``` @@ -197,7 +209,7 @@ Example: ./scripts/forge-script.sh ./src/Operation.s.sol:Borrow --fork-url=$RPC_URL --broadcast -vvvv ``` -### Information about your positions in `Dai`, `$DENARIUS` and within the Rome DAO (simulating Maker) protocol +### Status Information about your Positions in `Dai`, `$DENARIUS` and within the Rome DAO (simulating Maker) protocol To know what is your actual positions in `Dai`, `$DENARIUS` and within the Rome DAO (simulating Maker) protocol there is a helper script that gives you these information reading the different smart contracts of the Protocol. Just call: @@ -216,11 +228,11 @@ daiJoin.join(, ); // with 10**18 precision This will burn ERC-20 `$DAI` and add it to `` internal balance on the `Vat`. -2. Repay internal `dai` in the `Vat` using `frob()`: +### Repay internal `dai` in the `Vat` using `frob()`: ```solidity vat.frob( - 'CENT-A', // ilk + 'Denarius-A', // ilk , , , // To keep it simple, use your address for both `u`, `v` and `w` @@ -233,7 +245,18 @@ vat.frob( - `dart`: how much **normalized debt** to remove. **MUST BE NEGATIVE**. Remember that `debt = ilk.rate * urn.art` . To get the value for `dart`, divide the desired amount by `ilk.rate` (this is a floating point division, which can be tricky) - See the [RwaUrn](https://github.com/makerdao/rwa-toolkit/blob/8d30ed2cb657641253d45b57c894613e26b4ae1b/src/urns/RwaUrn.sol#L156-L178) component to understand how it can be done -4. Get your `$CENT` back: - ```solidity - gemJoin.exit(, ); // with 10**18 precision - ``` +### Get your `$DENARIUS` back: + +```solidity +gemJoin.exit(, ); // with 10**18 precision +``` + +Example: + +```bash +./scripts/forge-script.sh ./src/Operation.s.sol:PayBack --fork-url=$RPC_URL --broadcast -vvvv +``` + +## Summary + +All the steps above have described how Maker DAO protocol manages DAI supply and its collaterals.