Add FAssets operational parameters page

flare-foundation · Jun 21, 2024 · 2aa02c6 · 2aa02c6
1 parent 9a299cf
commit 2aa02c6
Show file tree

Hide file tree

Showing 7 changed files with 131 additions and 5 deletions.
diff --git a/docs/tech/fassets/collateral.md b/docs/tech/fassets/collateral.md
@@ -331,11 +331,13 @@ The following thresholds are set by the FAssets system's governance and are the
 
 * **Minimal CR**: The lowest collateral ratio the agent vault and the collateral pool must maintain so that enough collateral exists to insure the minted FAssets and to compensate for redemption payments that fail.
     The minimal CR can be different for each type of collateral.
+    { #minimal-cr }
 
     If an agent's CR remains below the minimal CR for longer than a governance-set amount of time, [liquidations](./liquidation.md) can start.
 
 * **Collateral call band CR (CCB CR)**: An agent's position is unhealthy when the agent's vault CR or pool CR fall below their minimal CR.
     However, as long as the CR remains above CCB CR, the CR can briefly fall below the minimal CR.
+    { #collateral-call-band-cr }
 
     During this time, the agent can either deposit more collateral or self-close some backed FAssets to improve the position.
 
@@ -354,6 +356,7 @@ The following thresholds are set by the FAssets system's governance and are the
 * **Safety CR**: If one or both of the collateral types fall below CCB CR or below the minimum CR for a longer period of time, liquidation occurs.
     When the offending collateral reaches a healthy CR again, the liquidation stops.
     To prevent the agent from immediately reverting into liquidation after a small price change, the CR must reach the safety CR before it can start operating normally again and liquidation stops.
+    { #safety-cr }
 
     Each of the collateral types, the agent's vault and the collateral pool, has its own unique safety CR.
 
@@ -363,13 +366,16 @@ The following thresholds are set by each agent according to their own preference
 
 * **Minting CR**: For each mint done by an agent, the maximum amount allowed to be minted is calculated so that the CR for the agent's vault and the CR for the agent's collateral pool after the mint remain higher than the minting CR for each collateral type.
     To reduce the threat of liquidation, agents should set the minting CR well above the minimal CR to accommodate price fluctuations that might occur before the CR falls below the minimal CR after the mint and minting is no longer possible.
+    { #minting-cr }
 
 * **Exit CR**: After a user redeems CPTs, the pool CR must be more than the exit CR.
     If the pool CR is already below the exit CR, redemption cannot occur.
     The exit CR is for the collateral pool only.
+    { #exit-cr }
 
 * **Top-up CR**: To incentivize healthy collateral pools, if the pool CR falls below the top-up CR, anyone can add collateral to the pool and receive [CPTs](#pool-collateral) at a reduced price.
     [This top-up mechanism](#top-up) decreases the likelihood of liquidations because of a low amount of pool collateral.
+    { #top-up-cr }
 
 ## Redemption of CPTs
 

diff --git a/docs/tech/fassets/index.md b/docs/tech/fassets/index.md
@@ -67,6 +67,7 @@ After the agent is verified, its management address is added to a list of allowe
 The **backing factor** is a system-wide setting that specifies how much of the kept assets must be locked, i.e., not freely used by agents.
 This factor is currently 100%, meaning that agents should not transfer out of their account any underlying that is backing FAssets, unless they receive a [redemption request](./redemption.md).
 Decreasing the underlying below the backing factor is an [illegal action](./liquidation.md#illegal-payments) and is reported by [challengers](#challengers).
+{ #backing-factor }
 
 ### Users
 
@@ -121,3 +122,4 @@ Select one of the following topics to continue learning about FAssets:
 * [The minting process](./minting.md)
 * [The redemption process](./redemption.md)
 * [Liquidation](./liquidation.md)
+* [Operational Parameters](./parameters.md)
diff --git a/docs/tech/fassets/minting.md b/docs/tech/fassets/minting.md
@@ -80,6 +80,7 @@ The following fees are paid to mint FAssets:
         The agent can use this balance freely.
     * **Pool's share**: This share is minted as FAssets and sent to the [collateral pool](./collateral.md#pool-collateral).
         The percentage of this share is defined by the agent and can be changed by the agent after a delay that provides time for minters to notice the change.
+        { #pool-share }
 
     The [Collateral page](./collateral.md#fasset-minting-fees-and-debt) contains more information about this fee.
 

diff --git a/docs/tech/fassets/open-beta.md b/docs/tech/fassets/open-beta.md
@@ -1,8 +1,16 @@
+---
+title: Open Beta
+search:
+  boost: 2
+---
+
 # FAssets Open Beta
 
 The FAssets system is currently in the open-beta period on the [Coston](../flare.md#flare-networks) test network.
 To ensure a seamless experience for open-beta participants, the FAssets codebase was updated based on the results of the closed-beta.
 
+Currently, the Open Beta period only supports minting of test `$XRP` assets, which produces `$FtestXRP` FAssets.
+
 ## FAssets Open Beta Objectives
 
 The objectives of the FAssets open beta are:

diff --git a/docs/tech/fassets/parameters.md b/docs/tech/fassets/parameters.md
@@ -0,0 +1,108 @@
+---
+title: Operational Parameters
+search:
+  boost: 2
+---
+
+# FAsset Operational Parameters
+
+This page lists the current values for the most important parameters of the [FAssets system](./index.md).
+
+Each listed parameter links to its documentation when available.
+Otherwise, it includes a description of the purpose of the parameter.
+
+!!! warning "Some of the values might be adjusted during the Beta phases."
+
+## Minting and Redeeming
+
+| Parameter                                                                    | Open Beta (Coston) |
+| ---------------------------------------------------------------------------- | ------------------ |
+| **Supported underlying assets**                                              | `$XRP`             |
+| **Minting cap** <br>Total amount of allowed FAssets in circulation. Once reached, no more FAssets can be minted until some are redeemed. This is intended as a security measure. In the final deployment this cap will be gradually increased and finally removed. | none |
+| [**Lot size**](./minting.md#lots)                                            | 20 XRP             |
+| [**Collateral reservation fee (CRF)**](./minting.md#crf)                     | 0.1%               |
+| [**Redemption fee**](./redemption.md#redemption-fee)                         | 0.1%               |
+| [**Redemption default premium**](./redemption.md#redemption-payment-failure) | 10%                |
+| **Redemption default premium source** <br>Where does the premium come from when an agent fails to pay the redeemer on time. | Solely from the agent's vault if the [vault CR](./collateral.md#the-collateral-ratio) > 1.1, the agent's vault and the collateral pool otherwise. |
+
+## Collateral Ratios
+
+| Parameter                                                                                   | Open Beta (Coston)                  |
+| ------------------------------------------------------------------------------------------- | ----------------------------------- |
+| [**Backing factor**](./index.md#backing-factor)                                             | 100%                                |
+| [**Vault collateral**](./collateral.md#vault-collateral)                                    |                                     |
+| &emsp;&bullet;&emsp; **Supported types**                                                    | `$USDC`, `$USDT`, simulated `$WETH` |
+| &emsp;&bullet;&emsp; [**Minimal CR**](./collateral.md#minimal-cr)                           | 1.4                                 |
+| &emsp;&bullet;&emsp; [**Collateral call band CR**](./collateral.md#collateral-call-band-cr) | 1.3                                 |
+| &emsp;&bullet;&emsp; [**Safety CR**](./collateral.md#safety-cr)                             | 1.5                                 |
+| [**Pool collateral**](./collateral.md#pool-collateral)                                      |                                     |
+| &emsp;&bullet;&emsp; **Supported types**                                                    | `$CFLR`                             |
+| &emsp;&bullet;&emsp; [**Minimal CR**](./collateral.md#minimal-cr)                           | 2.0                                 |
+| &emsp;&bullet;&emsp; [**Collateral call band CR**](./collateral.md#collateral-call-band-cr) | 1.9                                 |
+| &emsp;&bullet;&emsp; [**Safety CR**](./collateral.md#safety-cr)                             | 2.1                                 |
+| **Minting pool holdings required** <br>Minimum amount of pool tokens an agent must hold to be able to mint, as a percentage of the FAssets the agent is currently backing. Unlike pool and vault collateral ratios, if the agent's pool tokens go below this threshold, the agent does not go into liquidation, they just can't mint. | 50% |
+
+## Liquidation
+
+| Parameter                                                                                               | Open Beta (Coston)                       |
+| ------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| [**CCB time**][ccb-time] <br>Maximum time an agent can remain in CCB before liquidation starts.         | 180s                                     |
+| [**Liquidation premium**](./liquidation.md#liquidation-process) <br>Increases in steps, as time passes. | Step 1: 5%<br>Step 2: 10%<br>Step 3: 15% |
+| **Liquidation step time** <br>Elapsed time before the liquidation premium advances to the next step.    | 180s                                     |
+| **Liquidation source** <br>Where do the funds come from to pay for liquidations.                        |                                          |
+| &emsp;&bullet;&emsp; Liquidated value                                                                   | The agent's vault                        |
+| &emsp;&bullet;&emsp; Premium                                                                            | The collateral pool                      |
+
+[ccb-time]:./collateral.md#collateral-call-band-cr
+
+## Default Agent Settings
+
+These are the default values for [the agent bot provided by the Flare foundation](../../infra/fassets/agent.md#setting-up-the-agent).
+Agents are free to adjust these settings as they see fit.
+
+| Parameter                                    | Open Beta (Coston) |
+| -------------------------------------------- | ------------------ |
+| [**Minting fee**](./minting.md#minting-fee)  | 0.25%              |
+| [**Pool share**](./minting.md#pool-share)    | 40%                |
+| [**Minting CR**](./collateral.md#minting-cr) |                    |
+| &emsp;&bullet;&emsp; **Agent vault**         | 1.6                |
+| &emsp;&bullet;&emsp; **Collateral pool**     | 2.4                |
+| [**Exit CR**](./collateral.md#exit-cr)       | 2.6                |
+| [**Top-up CR**](./collateral.md#top-up-cr)   | 2.2                |
+| &emsp;&bullet;&emsp; **Top-up discount**     | 20%                |
+| [**Discount for agent self-close**](./liquidation.md#stopping-liquidations) <br>In self-close exit, the pool token holder burns FAssets to increase pool CR enough to enable exit. Normally, the burned FAssets are redeemed in the normal redemption process. However, if the closed amount is less than 1 lot, or on explicit request, the agent buys the underlying assets (at a discounted FTSO price, to compensate the agent for possible price fluctuations) and pays the exiting token holder in vault collateral.| 1% |
+
+## Rewarding
+
+| Parameter                             | Open Beta (Coston)                       |
+| ------------------------------------- | ---------------------------------------- |
+| [**Challenger reward**](./index.md#challengers) <br>After a successful challenge for an illegal operation, the agent goes into full liquidation and the challenger is paid this reward from the agent's vault. | 300 `$USD` converted to vault collateral |
+| [**Confirmation by others**](./redemption.md#edge-cases) <br>If an agent or redeemer becomes unresponsive, anybody can confirm payments and non-payments some time after the request was made, and get a reward from the agent's vault. | |
+| &emsp;&bullet;&emsp; **Minimum time** | 2 hours                                  |
+| &emsp;&bullet;&emsp; **Reward**       | 100 `$USD` converted to vault collateral |
+
+## Time locks
+
+These settings are far shorter in the Beta phases than in the final version, in order to be able to perform quick experiments.
+
+| Parameter | Open Beta (Coston) |
+| --------- | ------------------ |
+| **Agent withdrawal time lock** <br>Agent has to announce any collateral withdrawal or vault destruction and then wait this time before executing it. | 60 s |
+| **Maximum governance update frequency** <br>Minimum amount of time between updates of any governance setting. | 60s |
+| **Token invalidation time** <br>Time between the moment a token is deprecated by governance and it becomes invalid. Agents still using it as vault collateral get liquidated after this time. | 1 day |
+| **Agent exit available time lock** <br>The time the agent has to wait after announcing exit from the list of publicly available agents and executing the exit. | 60s |
+| **Agent fee change time lock** <br>The time the agent has to wait between announcing and changing the agent fee or the pool share. | 120s |
+| **Agent minting CR change time lock** <br>The time the agent has to wait between announcing and changing the minting CR (vault or pool). | 120s |
+| **Pool exit and top-up change time lock** <br>The time the agent has to wait between announcing and changing any pool exit and top-up settings. | 120s |
+| **Agent time-locked operation window** <br>Once the above time locks expire, agents have this amount of time to execute the requested operation. | 1 hour |
+| **Collateral pool token time lock** <br>Amount of seconds that a user entering the collateral pool must wait before spending (exit or transfer) the obtained pool tokens. | 60 s |
+
+<style>
+.md-typeset table:not([class]) td {
+    padding-bottom: 4px;
+    padding-top: 4px;
+}
+.md-typeset table:not([class]) tbody tr:hover {
+    background-color: var(--md-accent-fg-color--transparent);
+}
+</style>
diff --git a/docs/tech/fassets/redemption.md b/docs/tech/fassets/redemption.md
@@ -56,7 +56,7 @@ This is the summary of the redemption process:
 Agents have a limited time to pay the redeemer on the underlying chain.
 The amount of time is defined by the last block and the last timestamp on the underlying chain.
 If the payment is not made in time, the redeemer has to prove nonpayment to be compensated.
-After the redeemer presents the nonpayment proof, he is paid with the agent's collateral plus a premium.
+After the redeemer presents the nonpayment proof, he is paid with the agent's collateral plus a _redemption default premium_.
 The premium is intended to encourage the agent to complete redemptions by paying with the underlying asset instead of collateral.
 
 If a payment fails and the failed transaction is recorded on the underlying chain, the agent must submit a proof of failed payment.

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -174,9 +174,6 @@ nav:
       - user/wallets/safepal-s1-wallet.md
       - user/wallets/how-to-access-flare-network-with-a-trezor-device.md
     - user/wrapping-tokens.md
-    - FAssets:
-      - user/fassets/index.md
-      - user/fassets/minting-redeeming.md
     - FTSO Delegation:
       - user/delegation/index.md
       - Managing Delegations: user/delegation/managing-delegations.md
@@ -189,6 +186,9 @@ nav:
       - user/staking/staking-cli.md
     - user/claiming-the-flaredrop.md
     - user/automatic-claiming.md
+    - FAssets:
+      - user/fassets/index.md
+      - user/fassets/minting-redeeming.md
     - Governance:
       - user/governance/index.md
       - user/governance/voting.md
@@ -344,11 +344,12 @@ nav:
     - tech/state-connector.md
     - FAssets:
       - tech/fassets/index.md
-      - tech/fassets/open-beta.md
       - tech/fassets/collateral.md
       - tech/fassets/minting.md
       - tech/fassets/redemption.md
       - tech/fassets/liquidation.md
+      - tech/fassets/open-beta.md
+      - tech/fassets/parameters.md
     - tech/validators.md
     - tech/api-portal.md
   - Concepts: