Acceptance criteria vaults

docs/test-plan.tex

@@ -29,7 +29,7 @@ \section{Introduction}
 
 \section{Interactions}
 
-\subsection{Discover market prices (MVP version)}
+\subsection{Discover market prices}
 
 For the MVP version, we implement a simplified, centralized market price
 discovery mechanism.
@@ -108,7 +108,7 @@ \subsubsection{Price module: Read}
 % 
 % Admin/governance can update the list of price oracles accepted by the OSM.
 % 
-\subsection{Vault (TBD)}
+\subsection{Vault}
 
 \subsubsection{Collect vault information}
 
@@ -118,34 +118,90 @@ \subsubsection{Initialize vault}
 
 As a user, I can open a new vault.
 
+\todo{Do we want to make it possible to combine multiple transactions into one,
+to help users avoid gas fees?}
+
 \subsubsection{Deposit}
 
 As a user, I can deposit ADA into a vault, so that I may take out a loan of dUSD
 (see below).
 
 \subsubsection{Withdrawal}
 
-As a user, I can withdraw ADA from a vault.
+As a user, I can withdraw ADA from a vault, as long as my collateralization
+ratio is above the liquidation ratio.
+In the frontend, a "minimum collateralization ratio" will be built in that
+prevents users from transacting with their vault in such a way that their
+collateralization ratio drops below the minimum collateralization ratio.
+
+\todo{Do we want a minimum collateralization ratio built into the frontend, to
+protect our users?}
 
 \subsubsection{Take out loan}
 
-As a user, I can take out a loan in dUSD against the collateral I put into one
-of my vaults.
+As a user, I can take out a loan in dUSD if I have enough collateral.
+There is a minimum size for dUSD loans, called the ``debt floor''.
 
 \subsubsection{Pay back loan}
 
 As a user, I can pay back (part of) a loan in dUSD I created in one of my
-vaults. In doing so, I am paying a stability fee to the buffer.
+vaults.
+In doing so, I am paying a stability fee to the buffer.
 
 \subsubsection{Liquidate vault}
 
+A vault is considered in an unhealthy state if its collateralization ratio is
+below the liquidation ratio, both according to the current price and the price
+from one hour ago.
+The reason for this last part (using two prices) is that the vault owner should
+get an hour after a new price gets published to fix his vault before allowing
+liquidators to jump into action.
+In addition, if a vault becomes sick through a very temporary ADA crash, but
+recovers within an hour, there is no reason to liquidate. \\
+
 Any user can detect that a vault is in an unhealthy state, and buy part of the
-collateral in the vault at a discount (compared to market prices).
+collateral in the vault at an admin-set discount rate compared to the market
+prices of both ADA and dUSD.
+This discount rate is called the liquidation discount, and will initially be
+$3\%$.
+Let us go through an example to explain how liquidation works.
+When buying e.g. $100$ USD worth of ADA, the ADA is offered at a price of $97$
+USD worth of dUSD.
+Anyone can come in and buy a part of the ADA at this discounted exchange
+rate\footnote{
+  There are two reasons we allow liquidators to buy a part of the collateral,
+  rather than forcing them to buy all of it.
+  \begin{enumerate}
+    \item Not forcing liquidators to buy all collateral makes the system less
+      complex. Once a (possibly partial) liquidation has occured, the vault is
+      still just a vault. If the collateralization ratio is still too low, a
+      second person can come along and liquidate some more. If not, there's no
+      reason a second person should be able to liquidate further.
+    \item Forcing liquidators to buy all collateral would slow down liquidation
+      arbitrage, since it requires one liquidity arbitrageur to have enough dUSD
+      to buy all the collateral at once.
+      Liquidation arbitrage is something we want to stimulate.
+      It also unnecessarily assures punishing the vault owner very harshly.
+  \end{enumerate}
+}.
+
+As time goes on, there are two options:
+\begin{enumerate}
+  \item By selling collateral at a discount, the collateralization ratio rises
+    above the liquidation ratio, and the vault returns to a healthy state.
+  \item All the collateral is sold but some dUSD debt remains in the vault.
+    This is an exceptional situation to be avoided, since it endangers the idea
+    behind the protocol.
+    It that can only be caused by a significant ADA price drop where liquidators
+    don't act on time.
+    The solution is dissolving the vault, and thereby the dUSD debt.
+\end{enumerate}
 
-If after liquidating all the collateral, a vault has remaining debt, the vault
-is destroyed and the debt with it.
-This is an exceptional situation to be avoided, since it endangers the idea
-behind the protocol.
+In addition to the liquidation discount given to liquidators, the vault owner
+will be charged a liquidation fee for allowing his vault to become unhealthy.
+This means that only a part of the dUSD paid by the liquidators ($1 - $ the
+liquidation fee), is used to pay back debt, burning the rest.
+The liquidation fee is initially set to $10\%$.
 
 \subsection{Buffer (TBD)}
 
@@ -161,15 +217,11 @@ \subsubsection{Set liquidation fee}
 
 \subsubsection{Set liquidation ratio}
 
-\subsubsection{Set minimum collateralization ratio}
-
-\todo{Do we want to have an on-chain enforced minimum collateralization ratio?}
-
 \subsubsection{Set stability fee}
 
 \section{Acceptance criteria}
 
-\subsection{Price module (MVP)}
+\subsection{Price module}
 
 Off-chain and on-chain criteria:
 \begin{itemize}
@@ -214,114 +266,67 @@ \subsection{Price module (MVP)}
 %     exchanges from making the OSM's result crash and many vaults liquidate.)
 % \end{itemize}
 % 
-\subsection{Vaults (TBD)}
+\subsection{Vault}
 
 Each user should have access to a website at "www.ardana-vaults.com". This
 website must be able to connect to their wallet to find out who they are and
-allow them to set up vaults and interact with their existing vaults. \\
-
-Decisions to be made:
-\begin{itemize}
-  \item Do we want the interface to be a website or an app?
-  \item Which domain name will the website live at?
-\end{itemize}
-
-\subsubsection{Collect information on the user's vaults}
-
-The vault website looks up the requested information and displays it in an
-aesthetic and clear overview. \\
-
-Requested information: How many vaults does the user have, how much collateral
-and debt do they each have, what are their collateralization ratios, how
-dangerous is it to have that collateralization ratio? \\
-
-Decisions to be made:
-\begin{itemize}
-  \item Is the list of requested information correct? Anything to be added,
-    removed or updated?
-\end{itemize}
-
-\subsubsection{Initialize}
-
-The vault website should have a button to open a new vault.
-
-\subsubsection{Deposit}
-
-The vault website has a form that allows each user to pick one of their vaults
-and deposit ADA into it. \\
-
-Restrictions:
-\begin{itemize}
-  \item You have at least the amount of ADA in your wallet that you would like
-    to deposit.
-\end{itemize}
+allow them to set up vaults and interact with their existing vaults.
 
-Decisions to be made:
+Acceptance criteria:
 \begin{itemize}
-  \item Do we want to implement a maximum amount of collateral? MakerDAO has
-    this, not sure why.
-  \item Do we want to implement a mininum amount of collateral? If so, is this
-    in total per vault, or per deposit?
+  \item Anyone can create a vault, through a button on the website
+  \item Anyone can create multiple vaults
+  \item Vaults owned by the same person are independent, i.e. one of the
+    person's vaults being sick, doesn't influence his other vaults
+  \item There is a page that automatically connects to the user's wallet and
+    displays information about his vaults: How many vaults, and for each vault
+    the amount of collateral, debt, collateralization ratio, and how healthy the
+    vault is.
+  \item The vault overview is correct, clear and aesthetic
+  \item Users can deposit, withdraw, take out a loan and pay back a loan
+    (through forms on the website), as long as the collateralization ratio
+    doesn't drop below the liquidation ratio\footnote{
+      In the UX (frontend only!), the collateralization ratio is banned from
+      dropping under the minimum collateralization ratio.}
+  \item Users cannot withdraw or take out a loan that drops their
+    collateralization ratio below the liquidation ratio
+  \item When going through a sequence of transactions, stability fees are
+    calculated correctly
+  \item Only the owner of the vault can create transactions other than
+    liquidation
+  \item Anyone can liquidate a sick vault
+  \item Liquidation is possibly if and only if the vault is in an unhealthy
+    state
+  \item One can buy as much collateral as is needed to make the vault healthy
+    again, and not more
+  \item During liquidation, collateral is bought at discount compared to the
+    most current price from the price module, where the discount is the
+    liquidation discount (set by admin)
+  \item $10\%$ of the dUSD paid by the liquidator, is burnt rather than used to
+    pay back the debt. This liquidation fee is meant to disincentivize users
+    from allowing their vaults to become sick.
+  \item The amount of dUSD paid back (when paying back a loan) is smaller than
+    (or equal to) the loan
 \end{itemize}
 
-Questions:
-\begin{itemize}
-  \item How will we figure out from which UTXO in your wallet to take the ADA?
-\end{itemize}
+\todo{Which domain name will the website live at?}
 
-\subsubsection{Withdrawal}
+\todo{Is the list of requested information correct? Anything to be added,
+removed or updated?}
 
-The vault website has a form that allows each user to pick one of their vaults
-and withdraw ADA from it. \\
-
-Restrictions:
-\begin{itemize}
-  \item Withdrawing this amount of ADA from that vault doesn't sink its
-    collateralization ratio below the minimum collateralization ratio.
-\end{itemize}
+\todo{How much is the minimum loan (per vault, not per loan) and maximum amount
+of collateral?}
 
-\subsubsection{Take out loan}
+\todo{Do we want to put a ceiling on the amount of debt someone can take out on
+one vault, at MVP?
+There are reasons to do this (see ``debt ceiling'' in the comments in this
+document) for multi-collateral systems.}
 
-The vault website has a form that allows a user to pick one of their vaults and
-take out a dUSD loan in it, against his collateral. \\
+\todo{How will we figure out from which UTXO in your wallet to take the ADA?}
 
-Restrictions:
-\begin{itemize}
-  \item This transaction doesn't make the collateralization ratio drop below the
-    minimum collateralization ratio.
-\end{itemize}
+\todo{What should the liquidation ratio be?}
 
 \todo{What should the minimum collateralization ratio be?}
-\todo{Should the minimum collateralization ratio be different from the
-liquidation ratio??}
-\todo{What should the minimum amount be one can take out as a loan? Is this per
-vault or per loan transaction?}
-
-\subsubsection{Pay back loan}
-
-The vault website has a form that allows a user to pick one of their vaults and
-pay back a (part of a) dUSD loan in it. \\
-
-Restrictions:
-\begin{itemize}
-  \item The amount of dUSD paid back by the user is equal to or smaller than the
-    amount of dUSD debt in the vault.
-  \item The stability fee for the part of loan that is paid back, is sent to the
-    buffer as community profit
-\end{itemize}
-
-Design decisions:
-\begin{itemize}
-  \item What should the minimum collateralization ratio be?
-  \item Should the minimum collateralization ratio be different from the
-    liquidation ratio??
-  \item Should there be a minimum amount one can take out as a loan? If so, is
-    this per vault or per loan transaction?
-\end{itemize}
-
-\subsubsection{Liquidate someone else's vault}
-
-...
 
 \subsection{Buffer (TBD)}
 
@@ -354,7 +359,7 @@ \section{Implementation details}
 This section discusses what we need in order to implement the interactions
 mentioned above.
 
-\subsection{Price module (MVP, TBD)}
+\subsection{Price module (TBD)}
 
 The price module is a UTXO which can only be created by admin.
 It contains in its datum a map from timestamps (POSIX time) to the price value.
@@ -366,18 +371,19 @@ \subsection{Price module (MVP, TBD)}
 
 Off-chain bot:
 \begin{itemize}
-  \item Before collecting any price information, the script reads out the
-    relevant UTXO's datum and checks if it is time yet to submit an update. If
-    not, it will terminate (successfully) right away.
   \item Haskell script that collects information and submits a transaction
-  \item The script is ran through a systemd service, running it once every five
-    minutes
+  \item Before collecting any price information, the script reads out the
+    relevant UTXO's datum and checks if it has been updated in the last hour. If
+    so, the script terminates successfully right away.
+  \item The script is ran once every five minutes through a systemd service
 \end{itemize}
 
 Price module:
 \begin{itemize}
   \item The on-chain code will be written in Plutarch
   \item The off-chain code will be built as a PAB
+  \item The datum will contain a map from timestamps (in POSIX time) to price
+    values, and three admin public keys
 \end{itemize}
 
 Note: The off-chain bot will combine the price feeds through two operations:
@@ -417,13 +423,19 @@ \subsection{Price module (MVP, TBD)}
 % \todo{Should the price oracles and the OSM all be combined into one UTXO, or
 % be split into separate UTXOs?}
 % 
-\subsection{Vault}
+\subsection{Vault (TBD)}
+
+\todo{Fill in this section!}
+
+Collecting vault information on one person, as well as collecting vault
+information in general, are implemented as off-chain endpoint within the PAB, to
+avoid having to build a separate backend for the dUSD system. \\
 
-Liquidation only becomes allowed when both the current price and the price of an
-hour ago state that the current collateralization ratio is below the liquidation
+Liquidation only becomes allowed when the current price and the price of an hour
+ago both state that the current collateralization ratio is below the liquidation
 ratio.
-This is a measure taken to allow vault owners a chance to add collateral or pay
-back some of the debt whenever the price of the collateral dropped.
+This is a measure taken to allow vault owners a chance to make their vaults
+healthy whenever the price of the collateral dropped.
 
 \section{Tests}