diff --git a/docs/faq.md b/docs/faq.md index 0c7b368b..08cd8156 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -6,58 +6,78 @@ description: Frequently asked questions about Open Dollar ### What is Open Dollar? -OD is an ETH backed stable asset with a [managed float regime](https://en.wikipedia.org/wiki/Managed\_float\_regime). The ODUSD exchange rate is determined by supply and demand while the protocol that issues OD tries to stabilize its price by constantly de or revaluing it. +Open Dollar is the protocol that issues OD, a floating $1.00 pegged stablecoin backed by Liquid Staking Tokens with NFT controlled vaults that is built for Arbitrum. -The supply and demand mechanic plays out between two parties: SAFE users (those who generate OD with their ETH) and OD holders. +### How does OD stay stable? -Compared to protocols that try to defend a [fixed exchange rate](https://www.investopedia.com/terms/f/fixedexchangerate.asp) between their native stable asset (pegged coin) and fiat (DAI/USD, sUSD/USD etc), OD's monetary policy offers a couple of advantages: +OD is an overcollateralized stable asset with a [managed float regime](https://en.wikipedia.org/wiki/Managed\_float\_regime). The OD/USD exchange rate is determined by supply and demand while the protocol that issues OD tries to stabilize its price by constantly de- or revaluing it. + +The supply and demand mechanic plays out between two parties: vault users (those who generate OD with their collateral tokens) and OD holders. + +Compared to protocols that try to defend a [fixed exchange rate](https://www.investopedia.com/terms/f/fixedexchangerate.asp) between their native stable asset (pegged coin), OD's monetary policy offers a couple of advantages: + +* Flexibility: the protocol can devalue or revalue OD in response to changes in OD's market price. This process transfers value between vault users and OD holders and incentivizes both parties to bring the market price back to a target chosen by the protocol. The mechanism is similar to countries [devaluing](https://www.investopedia.com/terms/d/devaluation.asp) or [revaluing](https://www.investopedia.com/terms/r/revaluation.asp) their currencies in order to combat a trade imbalance. The "trade imbalance" in OD's case happens between OD and vault users -* Flexibility: the protocol can devalue or revalue OD in response to changes in OD's market price. This process transfers value between SAFE users and OD holders and incentivizes both parties to bring the market price back to a target chosen by the protocol. The mechanism is similar to countries [devaluing](https://www.investopedia.com/terms/d/devaluation.asp) or [revaluing](https://www.investopedia.com/terms/r/revaluation.asp) their currencies in order to combat a trade imbalance. The "trade imbalance" in OD's case happens between OD and SAFE users * Discretion: the protocol itself is free to change the target exchange rate to its own advantage. It can attract or repel capital whenever it wants. At the same time, a managed float can cause uncertainty due to the fact that the price varies day by day. -### What +### What types of collateral are used in Open Dollar? +Initially, popular Liquid Staking Tokens and some Arbitrum native assets can be used to borrow OD against: +- [wstETH](https://www.coingecko.com/en/coins/wrapped-steth) +- [rETH](https://www.coingecko.com/en/coins/rocket-pool-eth) +- [cbETH](https://www.coingecko.com/en/coins/coinbase-wrapped-staked-eth) +- [ARB](https://www.coingecko.com/en/coins/arbitrum) +- [MAGIC](https://www.coingecko.com/en/coins/magic) -### How does OD work/behave? +More assets will be added as the community sees fit. We aim to be extremely flexible and fast to adopt new LSTs and high quality collateral. -The long term price trajectory of OD is determined by the demand for ETH leverage. OD tends to appreciate if SAFE users deleverage and/or OD users long and it depreciates in case SAFE users leverage and/or OD users short. +### How can more collateral types be added? +A DAO controlled by Open Dollar Governance (ODG) token holders can add more types of collateral at any time through voting. -To better understand how OD behaves, we need to analyze its monetary policy which is made out of four elements: +### What does governance minimization mean? +Open Dollar is guided by the idea that to ensure the longevity and long term security of the protocol, as few parameters as possible should be governed by people and token holders. Instead, the system reacting to market rates should control nearly everything. The ODG holders can create new vault types with different kinds of collateral, change the system debt limit, decide where a portion of the fees but very few other things. -* Redemption price: this is the price that the protocol wants OD to have on the secondary market (e.g on Uniswap). The redemption price is used by SAFE users to mint OD against ETH and it is also used during Global Settlement in order to allow both SAFE and OD users to redeem collateral from the system. The redemption price almost always floats and it does not target any specific peg. -* Market price: this is the price that OD is traded at on the secondary market (on exchanges). -* Redemption rate: this is the rate at which OD is being devalued or revalued. The process of devaluing/revaluing OD consists in the redemption rate changing the redemption price. -* Global Settlement: settlement consists in shutting down the protocol and allowing both SAFE and OD users to redeem collateral from the system. Settlement uses the redemption (and not the market) price to calculate how much collateral can be redeemed by each user. +### How do NFVs (NFT Vaults) work? +Where other lending protocols in DeFi tie debt to a user's account, NFVs allow us to tie the debt and collateral to a particular Non-Fungible Token that is easy to transfer, view in a wallet, and buy or sell. There is 1 NFT for each vault and their IDs correspond. -Let's walk through an example of how OD is revalued in case of ETH capital inflow (aka people are bullish on ETH): +### What happens if I send my NFV to someone else? +The owner of a particular NFV owns both the debt and the collateral tokens for that particular vault. Be extremely cautious when transfering, buying, and selling NFVs, as the new owner is responsible for both the debt and the tokens inside. -* At time T1: ETH price is $500, OD's market and redemption prices are both $5 -* At time T2: ETH price surges to $1000. OD SAFE users suddenly have more borrowing power and generate more OD against their collateral. SAFE users sell OD on the secondary market (Uniswap), causing OD's market price to crash to $4. -* At time T3: ETH remains at $1000 and OD's market price is still $4. The system wants the market price to get close to the redemption price. In order to eliminate the imbalance between the market/redemption prices, the system starts to revalue OD. Revaluing consists in setting a positive redemption rate which makes the redemption price grow every second. -* At time T4: ETH remains at $1000. OD's redemption price is now $5.1. SAFE users are starting to realize that they can now borrow less OD per one ETH, they can redeem less ETH during Settlement (because OD is now more expensive) and that it will be more expensive to close their SAFE once the market price follows the redemption price. At the same time, OD holders are starting to realize that they can redeem more and more ETH during settlement -* At time T5: ETH remains at $1000. OD's redemption price is now $5.2. OD's market price surged to $5.2 as a result of SAFE users buying OD in order to close their positions as soon as possible instead of later on when OD is more expensive +### What is the advantage of NFVs? +You probably would never take out a 30 year loan to buy a house if you could not sell your house at some point during the life of the loan. But that is how lending mostly works in DeFi today. By making the ownership of vaults, debt, and collateral more easily tradable users can sell their positions easily without having to close them out first. Use cases could include market participants redeeming OD by buying NFVs to access high quality collateral, liquidation protection through selling NFVs with limit orders, and use of any existing NFT infrastructure. -When OD is devalued (in case of ETH capital outflow), the opposite thing happens: +### What happens to an NFV when a vault is liquidated? +Vaults are up for liquidation if the value of their collateral ever falls below the required collateralization for the amount of debt minted against it. Liquidated vaults still exist and so does the corresponding NFV. They just have 0 debt and 0 value of collateral in them after liquidation has completed. -* SAFE users realize that they can mint more OD against their ETH and that they will be able to buy cheap OD once the market price tanks -* Token holders realize that they can redeem less ETH during Settlement and they need to short OD +### Can I add more collateral to my vault? +Yes, you can add more collateral to your vault at any time. Depending on your collateralization ratio you can then also borrow more. -### Is OD a rebase token? +### How should I avoid liquidation? +Each type of vault has its own collateralization ratio that is required. The “collateralization ratio” is the ratio of the value of the collateral deposited in your vault to the value of the OD borrowed against it. When borrowing OD be sure to leave a margin that accounts for market volatility and top up your vault with more collateral as needed. -No. The protocol doesn't change the amount of tokens you have. Rather, it changes the target price that the protocol wants OD to have on exchanges. +### Where can I use my OD tokens? +OD is a standard ERC-20 token which can be used accross any bridge, DeFi protocols, exchanges, etc. that support it. Have an idea for an OD integration? Let us know in [discord](https://discord.opendollar.com/)! -### Why would I hold OD when the system devalues the token? +### What networks is Open Dollar deployed on? +Open Dollar is currently only deployed on Arbitrum. There's also a testnet version deployed on Arbtrium-Goerli. + +### Where can I trade my NFV? +You can trade your vaults on any NFT marketplace, like [OpenSea](https://opensea.io/) for example. Keep in mind that when you sell your Non-Fungible Vault you’re also selling all collateral and debt associated with it. Any app or tool which supports the ERC-721 token standard will also support Open Dollar NFVs. -This is exactly what the system wants you to ask yourself when it charges a negative redemption rate. The system is trying to incentivize OD holders to sell and bring the market price down and close to the redemption price. +### Is OD a rebase token that changes my balance over time? -### Isn't OD growth bounded by ETH growth? +No. The protocol doesn't change the amount of tokens you have. Rather, it changes the target price that the protocol wants OD to have on exchanges. This makes it easier to use OD throughout DeFi. -Short answer: yes. Nevertheless, we decided to build a pure ETH system for several reasons: +### How do fees work? +Open Dollar earns fees by charging a transparent and low interest rate on the amount of OD borrowed from the protocol. This is the stability fee. A portion of OD revenue is sent directly to the ODG governed DAO treasury, and a portion is auctioned off to buy and burn ODG tokens. -* Social scalability: we believe the most successful DeFi protocols will be the ones that act as a trust minimized operating system. You can build on top of them without the fear that the rules will drastically change and break your application. For this reason we also want to progressively remove control over OD. -* Simplicity: it is easier to explain OD's behaviour in contrast to ETH as opposed to a basket of assets. -* Proof of concept: a system backed by a single collateral type is easier to manage than a multi-collateral one. It allows us to test our hypotheses without layering extra risk and overhead +### What is the "Vault Facilitator"? +When you connect to Open Dollar’s app for the first time you are asked to create a Vault Facilitator. This Vault Facilitator is a DSProxy allows you to batch transactions, such as depositing collateral and borrowing OD, into one transaction. We use the same DSProxy as Maker, Balancer, and many other protocols, but renamed it to be easier to understand. + +### Isn't OD growth bounded by ETH and LST growth? + +Short answer: yes. Open Dollar can meet any demand and mint any amount of OD, so long as their is more value of collateral that participants are willing to borrow against. ### Can you summarize the behavior of the OD redemption rate? @@ -69,25 +89,58 @@ Short answer: yes. Nevertheless, we decided to build a pure ETH system for sever A system like OD has two types of rates: -* The borrow rate which is an interest rate charged on open SAFEs. The borrow rate will usually be fixed or bounded -* The redemption rate: this is the rate at which OD (or OD-like assets) are devalued or revalued +* The borrow rate which is an interest rate charged on open vaults. The borrow is fixed for different types of collateral and also has a max cap. + +* The redemption rate: this is the rate at which OD tokens are devalued or revalued in the system. ### Why would I want to mint OD? -* Getting paid for opening and managing SAFEs: when OD is devalued, SAFE users are "paid" because the value of their debt shrinks compared to the value of their collateral -* Capped borrow rate: in the long run, OD will have a capped (and small) borrow rate which makes the cost of maintaining a SAFE more predictable. Governance can, in theory, set the borrow rate to 0% although this prevents the system from accruing surplus that's [used to incentivize keepers](/system-contracts/sustainability-module/stability-fee-treasury) to update core components such as oracles and the PID. A 0% borrow rate would also prevent the protocol from building a surplus buffer meant to settle bad debt that couldn't be covered by collateral auctions -* Insurance for SAFEs: in the long run we can allow SAFE users to attach a wide variety of insurance contracts meant to protect their positions against liquidation +* Getting paid for opening and managing vaults: when OD is devalued, vault users are "paid" because the value of their debt shrinks compared to the value of their collateral + +* Capped borrow rate: in the long run, OD will have a capped (and small) borrow rate which makes the cost of maintaining a vault more predictable. Governance can, in theory, set the borrow rate to 0% although this prevents the system from accruing surplus that's used to incentivize to update core components such as oracles and the PID. + +* Insurance for vaults: in the long run we can allow SAFE users to attach a wide variety of insurance contracts meant to protect their positions against liquidation + * No exposure to assets with counterparty risk: OD will only be backed by ETH. Borrowers are not exposed to riskier crypto assets or real world collateral + * Superior collateral factors: as we improve the efficiency of our [collateral auctions](/system-contracts/auction-module/fixed-discount-collateral-auction-house) and add insurance contracts for SAFEs, we can lower the collateral requirements for borrowing OD -### What are OD's use-cases? +### Will OD always return to the same initial value/peg? -The following is a non-exhaustive list of use-cases we envision for OD: +OD is not designed to be pegged to anything, so it may never return to the exact same value it started at. Similar to many fiat currencies (EUR, USD, etc), OD's price will float, being influenced by market forces (supply & demand) and by the incentives that the PID controller offers to vault users and OD holders. Those incentives are designed to target a $1.00 market price but the actual price will fluctuate up or down. -* Portfolio diversification: OD offers dampened exposure to ETH's price moves -* DeFi collateral: OD can be used as an ETH supplement or alternative collateral in DeFi protocols due to the fact that it dampens ether's price moves and gives users more time to react to market shifts -* DAO reserve asset: DAOs can keep OD on their balance sheet and get exposure to ETH without being affected by its full market swings +### How does the OD price work/behave? -### Will OD always return to the same initial value/peg? +The long term price trajectory of OD is determined by the demand for leverage on the types of tokens Open Dollar allows as collateral. OD tends to appreciate if vault users deleverage and/or OD users long and it depreciates in case vault users leverage and/or OD users short. + +To better understand how OD behaves, we need to analyze its monetary policy which is made out of four elements: + +* Redemption price: this is the price that the protocol wants OD to have on the secondary market (e.g on Uniswap). The redemption price is used by SAFE users to mint OD against ETH and it is also used during Global Settlement in order to allow both SAFE and OD users to redeem collateral from the system. The redemption price almost always floats and it does not target any specific peg. + +* Market price: this is the price that OD is traded at on the secondary market (on exchanges). + +* Redemption rate: this is the rate at which OD is being devalued or revalued. The process of devaluing/revaluing OD consists in the redemption rate changing the redemption price. + +* Global Settlement: settlement consists in shutting down the protocol and allowing both SAFE and OD users to redeem collateral from the system. Settlement uses the redemption (and not the market) price to calculate how much collateral can be redeemed by each user. + +Let's walk through an example of how OD is revalued in case of capital inflow of some Liquid Staked Token that we can call lstETH (meaning people are bullish on lstETH ): + +* At time T1: lstETH price is $500, OD's market and redemption prices are both $1. + +* At time T2: lstETH price surges to $1000. Open Dollar vault users suddenly have more borrowing power and generate more OD against their collateral. Those users sell OD on the secondary market (like an exchange), causing OD's market price to drop to $0.95. Users might be selling to create leveraged long positions, or to access capital without having to sell their lstETH. + +* At time T3: lstETH remains at $1000 and OD's market price is still $0.95. The protocol wants the market price to get close to the redemption price. In order to eliminate the imbalance between the market/redemption prices, the system starts to revalue OD. Revaluing consists in setting a positive redemption rate which makes the redemption price grow every second. + +* At time T4: lstETH remains at $1000. OD's redemption price is now $1.05. SAFE users are starting to realize that they can now borrow less OD per one lstETH, they can redeem less lstETH during Settlement (because OD is now more expensive) and that it will be more expensive to close their SAFE once the market price follows the redemption price. At the same time, OD holders are starting to realize that they can redeem more and more ETH during settlement. + +* At time T5: lstETH remains at $1000. OD's redemption price is now $1.10. OD's market price surged to $1.01 as a result of SAFE users buying OD in order to close their positions as soon as possible instead of later on when OD is more expensive. + +When OD is devalued (in case of lstETH capital outflow), the opposite thing happens: + +* Vault users realize that they can mint more OD against their ETH and that they will be able to buy cheap OD once the market price goes down. + +* Token holders realize that they can redeem less lstETH during Settlement and they need to short OD. + +### Why would I hold OD when the system devalues the token? -OD is not designed to be pegged to anything, so it may never return to the same value it started at. Similar to many fiat currencies (EUR, GBP etc), OD will float around, being influenced by market forces (supply & demand) and by the incentives that the PID controller offers to SAFE users and OD holders. +This is exactly what the system wants you to ask yourself when it charges a negative redemption rate. The system is trying to incentivize OD holders to sell and bring the market price down and close to the redemption price. \ No newline at end of file diff --git a/docs/glossary.md b/docs/glossary.md new file mode 100644 index 00000000..4e09015e --- /dev/null +++ b/docs/glossary.md @@ -0,0 +1,83 @@ +--- +description: A glossary of terms that are requently used in these docs and in Open Dollar. +--- + +# Glossary + +## Non-Fungible Vault (NFV) +A Non-Fungible Vault is a Collateralized Debt Position (CDP) that is tied to and controlled by an NFT, thereby enabling the transfer or sale of the CDP without requiring debt to be paid back. + +## OD +OD is Open Dollar’s stablecoin, a floating $1.00 pegged stablecoin backed by Liquid Staking Tokens with NFT controlled vaults. + +## ODG +ODG is Open Dollar’s governance token which grants holders the ability to submit proposals and vote on the Open Dollar’s governance. + +## APR +APR, or annual percentage rate, represents the yearly rate charged for borrowing. + +## APY +APY, or annual percentage yield, refers to how much interest is earned and takes into account compound interest. + +## Arbitrage +Arbitrage is the act of seeking to exploit price differences between markets to make profit. Arbitrageurs are individuals who benefit from price discrepancies while helping to align pegged token prices. + +## Bridge +A bridge is a platform that allows for the transfer of blockchain assets from one network to another. For example, from mainnet Ethereum to the Arbitrum rollup. + +## CEX +Centralized Exchange. Binance and Coinbase are examples of CEXs. Acting as centralized authorities, as they take custody of a user’s funds on deposit. + +## Collateral +The assets that are deposited, such as wstETH or rETH, in order to borrow another asset, such as OD. + +## Collateralization Ratio +The collateralization ratio is the ratio between the value of the collateral in a vault and the value of its debt in OD. + +## Liquidation +Liquidation is when borrowed positions are forcefully closed if asset values fall below the minimum Collateralization Ratio, in order to pay back the loans. + +## Over-collateralized +Over-collateralization means the value of locked collateral exceeds the value of stablecoins minted. + +## Collateralized Debt Position (CDP) +A collateralized debt position refers to the assets deposited into a lending protocol as collateral in order to borrow stablecoins, such as OD. + +## Debt Amount +The number of borrowed tokens, for example OD, required to redeem the collateral in a vault. + +## DeFi +DeFi stands for Decentralized Finance, which refers to financial services and products that operate on public blockchains like Ethereum. + +## DEX +A DEX (decentralized exchange) is a cryptocurrency exchange that allows for peer-to-peer trading of digital assets and cryptocurrencies without the need for an intermediary or centralized authority. For example, Camelot or Uniswap + +## Governance +Governance refers to the democratic process of managing a project or ecosystem by a collective of stakeholders who hold governance tokens which grant the power to submit proposals and vote. + +## DAO +A Decentralized Autonomous Organization is a type of organization that is run on blockchain or peer-to-peer networks and governed by rules encoded into smart contracts. They allow for decentralized governance and coordination of pooled funds and resources, without central management. The rules are transparent and autonomous once launched on a blockchain. + +## Governance Token +A governance token gives holders voting rights to influence decisions in a decentralized protocol. Governance token holders can propose and vote on upgrades to the protocol. + +## Leverage +Leverage refers to the use of debt (borrowed funds) to amplify capital. People use leverage to multiply their buying power in the market. + +## Liquidation Penalty +The liquidation penalty is a fee rendered on the price of assets of the collateral when liquidators purchase it as part of the liquidation of a loan. This is paid by the vault owner. + +## Liquidation Price +The liquidation price of a vault is the collateral's price at which the position becomes subject to liquidation. This happens when the collateral value drops below the Minimum Collateral Ratio (MCR). + +## Liquidity +A measure of how much available circulating supply there is of an asset or currency, and the activity of that asset or currency in an exchange, economy, or network. A currency with low supply and/or circulation is said to be illiquid. + +## Liquid Staking Tokens (LSTs) +LSTs are tokens issued by liquid staking platforms, such as Lido or Rocketpool and given as a liquid receipt of staked ETH elsewhere. They are also sometimes known as Liquid Staking Derivatives (LSDs). + +## Loan-to-value (LTV) +The loan to value is the amount of stablecoins debt compared with the collateral deposited in the vault. + +## Redemption +The act of burning a token to repossess the underlying collateral asset. diff --git a/docs/helper-contracts/safe-manager.md b/docs/helper-contracts/safe-manager.md index c9f2131e..547b4191 100644 --- a/docs/helper-contracts/safe-manager.md +++ b/docs/helper-contracts/safe-manager.md @@ -8,7 +8,7 @@ description: A central hub for all SAFEs ## 1. Summary -`ODSafeManager` is an abstraction around the `SAFEEngine` that allows anyone to easily manage their GEB positions. Additionally, it is integrated with `Vault721`, which equates safe ownership to NFT-Vault ownership, making the transferrence of safes as easy as transferring an NFT. +`ODSafeManager` is an abstraction around the `SAFEEngine` that allows anyone to easily manage their GEB positions. Additionally, it is integrated with `Vault721`, which equates safe ownership to NFT-Vault ownership, making the transferrence of safes as easy as transferring an NFT; safes are only transferred via token transfers of NFT-Vaults called on Vault721. ## 2. Contract Variables & Functions @@ -38,7 +38,7 @@ description: A central hub for all SAFEs * `allowSAFE(safe: uint256`, `usr: address`, `ok: uint256)` - allow an address to interact with a SAFE with a specific id * `allowHandler(usr: address`, `ok: uint256)` - allow an address to interact with a SAFE handler * `openSAFE(collateralType: bytes32`, `usr: address)` - create a new SAFE id and handler, mint NFT-Vault where tokeId is safeId -* `transferSAFEOwnership(safe: uint256`, `dst: address)` - transfer a SAFE and NFT-Vault to another user's proxy and account, respectively +* `transferSAFEOwnership(safe: uint256`, `dst: address)` - transfer a SAFE and NFT-Vault to another user's proxy and account, respectively (access protected to Vault721 only, via token transfer of NFT-Vault) * `modifySAFECollateralization(safe: uint256`, `deltaCollateral: int256`, `deltaDebt:` `int256)` - add/remove collateral to and from a SAFE or generate/repay debt * `transferCollateral(safe: uint256`, `dst: address`, `wad: uint256)` - transfer collateral from a SAFE to another address * `transferInternalCoins(safe: uint256`, `dst: address`, `rad: uint256)` - transfer `SAFEEngine.coinBalance` system coins between addresses @@ -58,7 +58,7 @@ description: A central hub for all SAFEs * `sender` - the `msg.sender` * `usr` - the handler * `ok` - whether it is allowed or not -* `TransferSAFEOwnership` - emitted when `transferSAFEOwnership` is called. Contains: +* `TransferSAFEOwnership` - emitted when `transferSAFEOwnership` is called by Vault721 via token transfer of NFT-Vault. Contains: * `sender` - the `msg.sender` * `safe` - the SAFE id * `dst` - the new owner diff --git a/sidebars.js b/sidebars.js index 93d98e3f..bd9a0bc6 100644 --- a/sidebars.js +++ b/sidebars.js @@ -24,6 +24,7 @@ const sidebars = { items: [ "README", "faq", + "glossary", "community-resources" ], },