From 752d4b50e5b131b622c74ed604034dab1fd24bd9 Mon Sep 17 00:00:00 2001 From: Kristaps Grinbergs Date: Fri, 20 Dec 2024 12:00:16 +0000 Subject: [PATCH] Removes FAssets, redirect to Dev Hub --- docs/index.md | 2 +- docs/infra/fassets/deploying-agent.md | 514 ------------------ docs/infra/fassets/index.md | 7 - docs/infra/fassets/liquidator.md | 72 --- docs/infra/fassets/managing-agent.md | 314 ----------- docs/infra/index.md | 4 - docs/products/index.md | 2 +- docs/tech/fassets/collateral.md | 429 --------------- docs/tech/fassets/index.md | 128 ----- docs/tech/fassets/liquidation.md | 340 ------------ docs/tech/fassets/minting.md | 258 --------- docs/tech/fassets/open-beta.md | 44 -- docs/tech/fassets/parameters.md | 134 ----- docs/tech/fassets/redemption.md | 127 ----- docs/tech/flare.md | 2 +- docs/tech/glossary.md | 2 +- docs/tech/index.md | 2 +- .../user/fassets/depositing-collateral-cli.md | 75 --- docs/user/fassets/index.md | 7 - docs/user/fassets/minting-redeeming-cli.md | 117 ---- docs/user/fassets/minting-redeeming-dapp.md | 214 -------- docs/user/index.md | 1 - include/fassets/generate-keys-info.md | 9 - include/fassets/issue-collector.html | 14 - include/fassets/open-beta.md | 8 - include/fassets/prerequisites-agent.md | 12 - include/fassets/prerequisites-user.md | 11 - include/fassets/setup-commandline.md | 53 -- include/fassets/setup-database.md | 159 ------ mkdocs.yml | 34 +- 30 files changed, 20 insertions(+), 3075 deletions(-) delete mode 100644 docs/infra/fassets/deploying-agent.md delete mode 100644 docs/infra/fassets/index.md delete mode 100644 docs/infra/fassets/liquidator.md delete mode 100644 docs/infra/fassets/managing-agent.md delete mode 100644 docs/tech/fassets/collateral.md delete mode 100644 docs/tech/fassets/index.md delete mode 100644 docs/tech/fassets/liquidation.md delete mode 100644 docs/tech/fassets/minting.md delete mode 100644 docs/tech/fassets/open-beta.md delete mode 100644 docs/tech/fassets/parameters.md delete mode 100644 docs/tech/fassets/redemption.md delete mode 100644 docs/user/fassets/depositing-collateral-cli.md delete mode 100644 docs/user/fassets/index.md delete mode 100644 docs/user/fassets/minting-redeeming-cli.md delete mode 100644 docs/user/fassets/minting-redeeming-dapp.md delete mode 100644 include/fassets/generate-keys-info.md delete mode 100644 include/fassets/issue-collector.html delete mode 100644 include/fassets/open-beta.md delete mode 100644 include/fassets/prerequisites-agent.md delete mode 100644 include/fassets/prerequisites-user.md delete mode 100644 include/fassets/setup-commandline.md delete mode 100644 include/fassets/setup-database.md diff --git a/docs/index.md b/docs/index.md index f1de3c2a2..265c05d91 100644 --- a/docs/index.md +++ b/docs/index.md @@ -52,7 +52,7 @@ Quick links: * [FTSO](https://dev.flare.network/ftso/overview) * [Flare Data Connector](./tech/data-connector.md) -* [FAssets](./tech/fassets/index.md) +* [FAssets](https://dev.flare.network/fassets/overview) diff --git a/docs/infra/fassets/deploying-agent.md b/docs/infra/fassets/deploying-agent.md deleted file mode 100644 index 9e44e3a6f..000000000 --- a/docs/infra/fassets/deploying-agent.md +++ /dev/null @@ -1,514 +0,0 @@ -# Deploying an FAssets Agent - -The [FAssets](./../../tech/fassets/index.md) agents play an essential role and help to run the system, allowing tokens on blockchains that do not support smart contracts to be used trustlessly with smart contracts on the Flare blockchain. - -This guide provides the following information: - -* How to set up the FAssets command line interface; -* How to set up access keys for interacting with the Flare test and FAssets underlying networks; -* How to set up an FAssets agent and provide collateral; -* How to run the agent so FAssets system users can convert (mint and redeem) assets from the underlying networks to the Flare test network and back. - ---8<-- "./include/fassets/open-beta.md" - -## Contract Addresses - -These are important FAssets smart contract addresses representing test tokens and notable system components, provided for your convenience during the Open Beta on the Coston test network. Please note that these addresses are exclusive to the Coston test network and unavailable on other Flare networks. - -### Test Tokens - -These are ERC-20 representations of test tokens to be used by the FAssets system: - -* `testUSDC`: [0xd20D9284E8b43C60365BcA90662C67B5A0B91dd6](https://coston-explorer.flare.network/address/0xd20D9284E8b43C60365BcA90662C67B5A0B91dd6) - -* `testUSDT`: [0x18bd7bE80F76055aeB4F1575A99d0c4d7893B8b5](https://coston-explorer.flare.network/address/0x18bd7bE80F76055aeB4F1575A99d0c4d7893B8b5) - -* `testETH`: [0x17c3E6318cb45B4267998940d7D65BA95A32954F](https://coston-explorer.flare.network/address/0x17c3E6318cb45B4267998940d7D65BA95A32954F) - -### FAssets System Contracts - -* `AgentOwnerRegistry`: [0xDb6c11b8D074D4488f5fFd0129AA5F91C4f00fb6](https://coston-explorer.flare.network/address/0xDb6c11b8D074D4488f5fFd0129AA5F91C4f00fb6) - - Allows whitelisting agents, and setting, and retrieving information like their work and management address, name, description and icon. - -* `FTestXRP`: [0x51B1ac96027e55c29Ece8a6fD99DdDdd01F22F6c](https://coston-explorer.flare.network/address/0x51B1ac96027e55c29Ece8a6fD99DdDdd01F22F6c) - - The FAsset-wrapped TestXRP token, ready to be used on Coston. - -* `FTestBTC`: [0xe01b2151b684b83C771449D8A6D1d1764f03829e](https://coston-explorer.flare.network/token/0xe01b2151b684b83C771449D8A6D1d1764f03829e) - - The FAsset-wrapped TextBTC token, ready to be used on Coston. - -* `FTestDOGE`: [0x353D20c6eB0C7bfcE3B828665C992DE995eF67bd](https://coston-explorer.flare.network/token/0x353D20c6eB0C7bfcE3B828665C992DE995eF67bd) - - The FAsset-wrapped TextDOGE token, ready to be used on Coston. - ---8<-- "./include/fassets/prerequisites-agent.md" ---8<-- "./include/fassets/setup-commandline.md" ---8<-- "./include/fassets/setup-database.md" - -### Configure the Access Keys - -The FAsset agents operate with multiple keys for the Flare and underlying network chains. You should generate these keys to make the agent operational. - -1. Create or use an existing management wallet that will be your agent's management address. Fund this wallet with some CFLR so you can pay the gas fees for various smart contract calls using the [Flare faucet](https://faucet.flare.network/). - -2. Generate the secrets using this command by replacing the `MANAGEMENT_WALLET_ADDRESS` with your cold wallet address: - - ```console - yarn key-gen generateSecrets --user --agent MANAGEMENT_WALLET_ADDRESS --other -o secrets.json - ``` - - --8<-- "./include/fassets/generate-keys-info.md" - -3. Follow [the whitelisting process](#whitelist-the-management-address) to grant your agent's management address access to the FAssets system. While waiting for approval, you can proceed to the next steps. - -4. The `secrets.json` file contains the `owner.native.address` field, representing the Flare account responsible for funding agent vaults and covering gas fees for smart contract calls. Please ensure this wallet has enough CFLR tokens to cover gas fees for smart contract calls. You can obtain CFLR tokens from the [Flare faucet](https://faucet.flare.network/). - -5. Prevent other users from reading the `secrets.json` file: - - ```console - chmod 600 secrets.json - ``` - -6. Fill the `native_rpc`, `xrp_rpc` and `indexer` fields in the `secrets.json` file with the following values: - - ```json - "native_rpc": "AavSehMLhcgz3crQHH5YJ3Rt8GMQGdV9aViGilADXGnTcjij", - "xrp_rpc": "4tg3AxysaZodxTqsCtcMnBdBIEkR6KDKGTdqBEA8g9MKq4bH", - "indexer": "123456", - ``` - !!! info - - These values apply only to the [Coston Testnet](https://dev.flare.network/network/overview) and will be different for other networks. - - -7. Fill in the `database` field in the `secrets.json` with the MySQL database username and password you created during setup. - -### MySQL Setup for Existing Agents - -Agents who have already configured `fasset-bots` to switch to MySQL or PostgreSQL should follow these steps: - -1. Install MySQL or PostgreSQL server. -2. [Create a user](#setting-up-database) in the MySQL or PostgreSQL database. -3. Modify the `FASSET_BOT_CONFIG` variable in the `.env` file located in the root of the repository. - - * MySQL database: - ```json - FASSET_BOT_CONFIG="./packages/fasset-bots-core/run-config/coston-bot-mysql.json" - ``` - - * PostgreSQL database: - ```json - FASSET_BOT_CONFIG="./packages/fasset-bots-core/run-config/coston-bot-postgresql.json" - ``` - -4. In the `secrets.json` file, add a new key, `database` which is an object with two keys `username` and `password` and fill with the values you used when creating the user in the MySQL or PostgreSQL database: - ```json - "database": { - "user": "fassetbot", - "password": "VerySafePassword" - } - ``` - -### Whitelist the Management Address - -To access the FAssets system during the open beta, you must be whitelisted for security reasons. -This ensures only authorized participants interact with the system, maintaining a secure and controlled environment for testing and platform improvement. -The whitelisting process will be removed after the opening beta. - -1. Find your agent owner address, which is the value from the `secrets.json` file in the `owner.management.address` field. -2. Use the [FlareFAssetsBot Telegram channel](https://t.me/FlareFAssetsBot), specifically designed for registration, and provide the necessary information, including your agent name, description, and a link to your icon. -3. Enter the information and confirm, and the Telegram bot will inform you about the successful process. -4. You need to wait for Flare support engineers to approve registrations and issue test assets such as Coston Flare (CFLR), testUSDC, testUSDT, and testETH assets, which will be sent to your `owner.management.address`. -While you wait, you can continue with the rest of this guide. -5. If the information you entered is correct, the Telegram Bot will notify you that you have been whitelisted for the FAssets Open Beta. - -#### Check Whitelist Status - -Checking if your agent's management address has been whitelisted is a straightforward process. Follow these steps: - -1. Navigate with the Coston block explorer to `AgentOwnerRegistry` smart contract on address [0xDb6c11b8D074D4488f5fFd0129AA5F91C4f00fb6](https://coston-explorer.flare.network/address/0xDb6c11b8D074D4488f5fFd0129AA5F91C4f00fb6/read-contract#address-tabs) and open the Read Contract tab. -2. Connect your wallet with any address to the block explorer so you can gain access to read functions from the smart contract. -3. Execute the `isWhitelisted` function with the value of `owner.management.address` from the `secrets.json` file. This function returns `bool`: `true` for whitelisted or `false` for not whitelisted. - -## Setting Up the Agent - -### Configure the Native Address - -Configuring the native address links your agent's work address to the management address and grants access. - -1. Navigate with the Coston block explorer to `AgentOwnerRegistry` smart contract on address [0xDb6c11b8D074D4488f5fFd0129AA5F91C4f00fb6](https://coston-explorer.flare.network/address/0xDb6c11b8D074D4488f5fFd0129AA5F91C4f00fb6/write-contract#address-tabs) and open the Write Contract tab. - -2. Connect the cold wallet you used to generate the access keys. - -3. Register the work address by executing the `setWorkAddress` function with the value of `owner.native.address` from the `secrets.json` file. - -### Configure the Agent - -You need to set up your agent's parameters like name, collateral, and fund with underlying assets. - -1. Prepare the agent settings `tmp.agent-settings.json` exchanging `FASSET` with `FTestXRP`, `FTestBTC` or `FTestDOGE` according to which underlying network you want to work on: - - ```console - yarn agent-bot --fasset FASSET create --prepare - ``` - -2. Choose a suffix for your agent's collateral pool and fill in the `poolTokenSuffix` field in the `tmp.agent-settings.json` file with it. -The `poolTokenSuffix` should only include uppercase letters, numbers, and the `-` symbol. -This suffix will be used for the [FAsset Collateral Pool Token](../../tech/fassets/collateral.md#pool-collateral). For example, for `FTestXRP`, if you use `MY-ALPHA-AGENT-1`, it would be `FCPT-TXRP-MY-ALPHA-AGENT-1`. - -3. Choose one of the stable tokens (`testUSDT` or `testUSDC`) or wrapped ETH in `vaultCollateralFtsoSymbol` to back up the agent vault collateral. - -4. In the `secrets.json` file, the `owner.testXRP.address`, `owner.testBTC.address`, and `owner.testDOGE.address` fields represent the underlying testnet accounts that will pay transaction fees for XRP, BTC, and DOGE, respectively. Ensure each account is activated by sending a minimum required amount of test cryptocurrency from the appropriate faucet. - * for XRP activate your underlying XRP Ledger account by sending at least 100 test-XRP using one of these XRP Ledger testnet faucets: - * [XRP Testnet Faucet](https://test.bithomp.com/faucet/) - * [XRP Ledger Faucet](https://faucet.tequ.dev/) - - * for BTC use the following faucet to receive testnet Bitcoin [TestBTC Faucet](https://bitcoinfaucet.uo1.net/) - - * for DOGE activate your Dogecoin account by sending test-DOGE using one of these faucets: - * [Doge Toys Faucet](https://faucet.doge.toys/) - * [Ruan's Dogecoin Faucet](https://dogecoin-faucet.ruan.dev/) - -5. Create the agent by specifying the FAsset and agent settings, noting that this operation can take up to 10 minutes because the FAssets verifies the underlying assets. -This command will print out your agent's address. -Exchange `FASSET` with `FTestXRP`, `FTestBTC` or `FTestDOGE` according to which underlying network you are creating the agent. - - ```console - yarn agent-bot --fasset FASSET create tmp.agent-settings.json - ``` - -### Deposit Collateral - -To make your newly created agent public, it must hold enough [collateral](../../tech/fassets/collateral.md) to mint one lot. -This means its agent vault contract needs to be funded with the two collaterals (CFLR and a stablecoin or wrapped ETH) held by your `owner.native.address`. -Flare support sends test assets to your `owner.management.address`, so remember to move these funds to the `owner.native.address`. - -You have two options: either deposit the vault collateral and buy pool collateral separately or use the system function to calculate the needed collateral for you. - -#### Deposit Collaterals Together - -To deposit both vault and pool collateral together and let the tool calculate the [minimum required collateral](../../tech/fassets/collateral.md#the-collateral-ratio) to back the lots, you can use the `depositCollateral` function to the agent, specifying your created agent address in the `AGENT_ADDRESS` and lot size in the `LOTS`, as well exchange `FASSET` with `FTestXRP`, `FTestBTC` or `FTestDOGE` according to which underlying network you are creating the agent: - -```console -yarn agent-bot depositCollaterals AGENT_ADDRESS LOTS --fasset FASSET -``` - -#### Deposit Collateral Separately - -1. Deposit enough vault collateral to the agent specifying your created agent address in the `AGENT_ADDRESS` and the amount of the stablecoin or wrapped ETH in the `AMOUNT` field, as well exchange `FASSET` with `FTestXRP`, `FTestBTC` or `FTestDOGE` according to which underlying network you are creating the agent. - - ```console - yarn agent-bot depositVaultCollateral AGENT_ADDRESS AMOUNT --fasset FASSET - ``` - -2. Buy enough pool collateral for the agent specifying your agent's address in the `AGENT_ADDRESS` and the amount of the CFLR in the `CFLR_AMOUNT` field, as well exchange `FASSET` with `FTestXRP`, `FTestBTC` or `FTestDOGE` according to which underlying network you are creating the agent. - - ```console - yarn agent-bot buyPoolCollateral AGENT_ADDRESS CFLR_AMOUNT --fasset FASSET - ``` - -### Register the Agent as Available - -You need to make your agent available to mint and redeem FAssets. - -1. Register your agent as available to the network by executing this command replacing the `AGENT_ADDRESS` with your agent address, as well exchange `FASSET` with `FTestXRP`, `FTestBTC` or `FTestDOGE` according to which underlying network you are entering the agent: - - ```console - yarn agent-bot enter AGENT_ADDRESS --fasset FASSET - ``` - - !!! info - - Note that your agent owner's Flare account has to be whitelisted via the [FlareFAssetsBot Telegram channel](https://t.me/FlareFAssetsBot). - Otherwise, it will fail. - -2. If you deposited enough collateral, you should see that your agent has at least one lot available by running the command replacing `FASSET` with `FTestXRP`, `FTestBTC` or `FTestDOGE` according to which underlying network you are running the agent. - - ```console - yarn user-bot agents --fasset FTestXRP - ``` - -If you don't have available lots, check if the vault and pool [collaterals are enough](../../tech/fassets/collateral.md#the-collateral-ratio). - -### Upgrade Your Agent to Support BTC - -1. Repeat the steps to [clone and set up the Tools repository](#clone-and-setup-the-tools-repository). -2. Generate a new `secrets.json` file using this command by replacing the `MANAGEMENT_WALLET_ADDRESS` with your cold wallet address: - - ```console - yarn key-gen generateSecrets --user --agent MANAGEMENT_WALLET_ADDRESS --other -o secrets.json - ``` - -3. Make a copy of your old `secrets.json` file, open it, and replace the owner and user testBTC addresses and private keys from the generated `secrets.json` in the previous step. - A new instance with your old `secrets.json` file that includes your BTC addresses is created. -4. In the [FlareFAssetsBot Telegram channel](https://t.me/FlareFAssetsBot), run `/register_btc_address ADDRESS`, where `ADDRESS` is your TestBTC address in the `secrets.json` file. - Your TestBTC address is registered, an amount of TestBTC is sent to the address, and your API key is returned. -5. In your `secrets.json` file, add the `btc_rpc` parameter to the `apiKey` section. -6. Prepare the agent for FTestBTC: - - ```console - yarn agent-bot --fasset FTestBTC create --prepare - ``` - -7. Choose a suffix for your agent's collateral pool and fill in the `poolTokenSuffix` field in the `tmp.agent-settings.json` file with it. - The `poolTokenSuffix` should only include uppercase letters, numbers, and the `-` symbol. - This suffix will be used for the [FAsset Collateral Pool Token](../../tech/fassets/collateral.md#pool-collateral). For example, if you use `MY-ALPHA-AGENT-1`, it would be `FCPT-TBTC-MY-ALPHA-AGENT-1`. - -8. If you need more TestBTC, request more from the [TestBTC faucet](https://bitcoinfaucet.uo1.net/). -9. Top up your `owner.testBTC` address from `secrets.json` with at least 0.5 TestBTC. -10. Create the agent by specifying the FAsset and agent settings, noting that this operation can take up to 10 minutes because the FAssets verifies the underlying assets. -This command will print out your agent's address. - - ```console - yarn agent-bot --fasset FTestBTC create tmp.agent-settings.json - ``` - -11. Deposit collaterals for your agent: - - ```console - yarn agent-bot depositCollaterals AGENT_ADDRESS LOTS --fasset FTestBTC - ``` - -12. Register your agent as available to the network by executing this command replacing the `AGENT_ADDRESS` with your agent address: - - ```console - yarn agent-bot enter AGENT_ADDRESS --fasset FTestBTC - ``` - -### Upgrade Your Agent to Support DOGE - -1. Repeat the steps to [clone and set up the Tools repository](#clone-and-setup-the-tools-repository). -2. Generate a new `secrets.json` file using this command by replacing the `MANAGEMENT_WALLET_ADDRESS` with your cold wallet address: - - ```console - yarn key-gen generateSecrets --user --agent MANAGEMENT_WALLET_ADDRESS --other -o secrets.json - ``` - -3. Make a copy of your old `secrets.json` file, open it, and replace the owner and user testDOGE addresses and private keys from the generated `secrets.json` in the previous step. - A new instance with your old `secrets.json` file that includes your DOGE addresses is created. -4. In the [FlareFAssetsBot Telegram channel](https://t.me/FlareFAssetsBot), run `/register_btc_address ADDRESS`, where `ADDRESS` is your TestBTC address in the `secrets.json` file. - Your TestBTC address is registered, an amount of TestBTC is sent to the address, and your API key is returned. -5. In your `secrets.json` file, add the `doge_rpc` parameter to the `apiKey` section. -6. Prepare the agent for `FTestDOGE`: - - ```console - yarn agent-bot --fasset FTestDOGE create --prepare - ``` - -7. Choose a suffix for your agent's collateral pool and fill in the `poolTokenSuffix` field in the `tmp.agent-settings.json` file with it. - The `poolTokenSuffix` should only include uppercase letters, numbers, and the `-` symbol. - This suffix will be used for the [FAsset Collateral Pool Token](../../tech/fassets/collateral.md#pool-collateral). For example, if you use `MY-ALPHA-AGENT-1`, it would be `FCPT-TDOGE-MY-ALPHA-AGENT-1`. - -8. If you need more TestDOGE, request more from the TestDOGE faucets: - * [https://faucet.doge.toys/](https://faucet.doge.toys/) - * [https://dogecoin-faucet.ruan.dev/](https://dogecoin-faucet.ruan.dev/) -1. Top up your `owner.testDOGE` address from `secrets.json`. -2. Create the agent by specifying the FAsset and agent settings, noting that this operation can take up to 10 minutes because the FAssets verifies the underlying assets. -This command will print out your agent's address. - - ```console - yarn agent-bot --fasset FTestDOGE create tmp.agent-settings.json - ``` - -1. Deposit collaterals for your agent: - - ```console - yarn agent-bot depositCollaterals AGENT_ADDRESS LOTS --fasset FTestDOGE - ``` - -2. Register your agent as available to the network by executing this command replacing the `AGENT_ADDRESS` with your agent address: - - ```console - yarn agent-bot enter AGENT_ADDRESS --fasset FTestDOGE - ``` - -## Running the Agent - -The agent bot responds to all requests made to the agent vaults you have created. -To run the agent bot, you need to run the following command: - -```console -yarn run-agent -``` - -When you want to stop the server, press Ctrl + C. - -To run the `run-agent` as a service to maximize uptime for production use, follow instructions for running the agent as a `system` service for [running the bot as a daemon](https://github.com/flare-labs-ltd/fasset-bots/blob/main/docs/systemd/systemd-service.md). - -!!! warning - - If you upgraded your agent code and see an error stating that `owner.testBTC.address` isn't defined when running the agent, you need to generate it using this command: - ```bash - yarn key-gen createAccount testBTC - ``` - - This command generates a test BTC account and displays the address and private key as follows: - - ```text - Address: tb1qtu86wueft8zafn3ppejsrq3c8z0rd2h9a8n6sa - Private key: cQ9tgyod95qw88LxwgAYXxnkJY9UWBauB1ejEHcJJsy3hHbchFbF - ``` - - Then, add this object under the `owner` and `user` sections in the `secrets.json` file, filling it out with the address and private key obtained when generating the test BTC account. - - ```json - "owner": { - - ... - - "testBTC": { - "address": "tb1qtu86wueft8zafn3ppejsrq3c8z0rd2h9a8n6sa", - "private_key": "cQ9tgyod95qw88LxwgAYXxnkJY9UWBauB1ejEHcJJsy3hHbchFbF" - } - }, - ... - "user" : { - - ... - - "testBTC": { - "address": "tb1qtu86wueft8zafn3ppejsrq3c8z0rd2h9a8n6sa", - "private_key": "cQ9tgyod95qw88LxwgAYXxnkJY9UWBauB1ejEHcJJsy3hHbchFbF" - } - } - ``` - -## Verifying Collateral Pool Smart Contracts - -Verification of a smart contract on a block explorer allows future users of the smart contract to inspect the Solidity source code instead of the bytecode, greatly improving the security and transparency of the ecosystem. -Follow these steps to upload the source code for the Collateral Pool and Collateral Pool Token smart contracts, verifying them on the block explorer. - -1. Execute the FAssets system information command to determine your collateral pool smart contract address. - - For XRP, run: - - ```bash - yarn agent-bot info AGENT_ADDRESS --fasset FTestXRP - ``` - - For BTC, run: - - ```bash - yarn agent-bot info AGENT_ADDRESS --fasset FTestBTC - ``` - - For DOGE, run: - - ```bash - yarn agent-bot info AGENT_ADDRESS --fasset FTestDOGE - ``` - - Look for the value of the **Agent collateral pool** field and copy the address, as shown in the following example for XRP. - - ```text hl_lines="30" - Tokens: - Native token: CFLR - Wrapped native token: WCFLR - FAsset token: FTestXRP - Underlying token: testXRP - Vault collateral token: testETH - Collateral pool token: FCPT-SIMX-KGR-25061612 - Network exchange rates: - CFLR/USD: 0.033 - testETH/USD: 3800 - testXRP/USD: 0.53 - Agent mint and collateral: - Status: healthy - Public: true - Free lots: 10 - Minted: 0 FTestXRP (0 lots) - Reserved: 0 FTestXRP (0 lots) - Redeeming: 0 FTestXRP (0 lots) - Vault CR: (minCR=1.4, mintingCR=1.6) - Pool CR: (minCR=2, mintingCR=2.4) - Free vault collateral: 0.046863112858734529 testETH (10 lots) - Free pool collateral: 8071.878095157464265083 WCFLR (10 lots) - Lots: - Lot size: 20 testXRP - Lot vault collateral: 0.004463157894736842 testETH - Lot pool collateral: 770.909090909090909091 CFLR - Agent address (vault): 0xa6d7dF2d68b4b687d7408Cd613192103DBdA1F33 - Balance: 0.046863112858734529 testETH - Balance: 8071.878095157464265083 FCPT-SIMX-KGR-25061612 - Agent collateral pool: 0x5Bf5cD267F5a5185d0d91567979CCa397A2E504a - Balance: 8071.878095157464265083 WCFLR - Collected fees: 0 FTestXRP - Agent vault underlying (testXRP) address: r4aiumSs3xrSeeeQ9frhrDkhJ6dL1Sr1iL - Actual balance: 10 testXRP - Tracked balance: 0 testXRP - Required balance: 0 testXRP - Free balance: 0 testXRP - Agent owner management address: 0x6827101103BE87eDadf77202F8973c5046245401 - Balance: 90.4216184475 CFLR - Balance: 0 testETH - Agent owner work address: 0xEfA4D9561fEc607eAe35D76a8034d9dBBe730449 - Balance: 4105.334310744331909805 CFLR (5 lots) - Balance: 0.042177240174410518 testETH (9 lots) - Agent owner underlying (testXRP) address: rndED5w8xQ2sVC2hT5J5e8GTfxouRcKfjR - Balance: 40.27988 testXRP - ``` - -2. Clone the FAsset repository in a new directory and enter it: - - ```console - git clone https://github.com/flare-labs-ltd/fassets.git - cd fassets - ``` - -3. Switch to the `open_beta` branch: - - ```console - git checkout open_beta - ``` - -4. Install dependencies and build the project: - - ```console - yarn && yarn c - ``` - - !!! info - - A fresh build can take more than 10 minutes, depending on if you have cached dependencies before. - -5. Verify the Collateral Pool and Collateral Pool Token smart contracts by running the following command and specifying the collateral pool address that you obtained in the first step as `AGENT_POOL_ADDRESS`: - - ```bash - yarn verify-collateral-pool-coston AGENT_POOL_ADDRESS - ``` - - Verifying the smart contract on the blockchain will take a minute or two, and you should get an output stating that Collateral Pool and Collateral Pool Token smart contracts have been verified. - It should be similar to this: - - ```text - Verifying CollateralPool at 0x5Bf5cD267F5a5185d0d91567979CCa397A2E504a - Successfully submitted source code for contract - contracts/fasset/implementation/CollateralPool.sol:CollateralPool at 0x5Bf5cD267F5a5185d0d91567979CCa397A2E504a - for verification on the block explorer. Waiting for verification result... - - Successfully verified contract CollateralPool on the block explorer. - https://coston-explorer.flare.network/address/0x5Bf5cD267F5a5185d0d91567979CCa397A2E504a#code - - Verifying CollateralPoolToken at 0x63937c0AD9506C61B2Fca6103E1828E2fcEf8a08 - Successfully submitted source code for contract - contracts/fasset/implementation/CollateralPoolToken.sol:CollateralPoolToken at 0x63937c0AD9506C61B2Fca6103E1828E2fcEf8a08 - for verification on the block explorer. Waiting for verification result... - - Successfully verified contract CollateralPoolToken on the block explorer. - https://coston-explorer.flare.network/address/0x63937c0AD9506C61B2Fca6103E1828E2fcEf8a08#code - ``` - - -Visit the original Flare block explorer at the address of the contract you just verified: - - https://coston-explorer.flare.network/address/{AGENT_POOL_ADDRESS} - -And check that the **Code** tab has a green checkmark next to it. - -## Related Pages - -* [Minting and Redeeming FAssets](../../user/fassets/index.md) -* [Setting up an FAssets Liquidator](./liquidator.md) -* [FAssets Open Beta](../../tech/fassets/open-beta.md) diff --git a/docs/infra/fassets/index.md b/docs/infra/fassets/index.md deleted file mode 100644 index d9a086216..000000000 --- a/docs/infra/fassets/index.md +++ /dev/null @@ -1,7 +0,0 @@ -# FAssets - -The following guide explains how to set up and manage an [FAssets](../../tech/fassets/index.md) agent. - -* [Deploying an FAssets Agent](./deploying-agent.md) -* [Managing an FAssets Agent with the FAssets Agent Admin Console](./managing-agent.md) -* [Setting up an FAssets Liquidator](./liquidator.md) diff --git a/docs/infra/fassets/liquidator.md b/docs/infra/fassets/liquidator.md deleted file mode 100644 index c3ff75154..000000000 --- a/docs/infra/fassets/liquidator.md +++ /dev/null @@ -1,72 +0,0 @@ -# Setting up an FAssets Liquidator - -As a critical component of the [FAssets](../../tech/fassets/index.md) system, [liquidators](../../tech/fassets/index.md#liquidators) oversee agents and ensure their self-sufficiency, contributing to the overall stability and efficiency of the system by carrying out [liquidation](../../tech/fassets/liquidation.md). -They initiate a process where FAssets are sent into the system in exchange for collateral plus a premium. -This process involves burning the FAssets, which effectively reduces the agent collateral requirement and allows them to earn rewards in the process. -Anyone can become a liquidator, supporting the FAssets system and earning rewards. - -This guide explains how to run a program called an FAssets bot that observes the FAssets system and reacts to its state. The bot must be running at all times and be constantly online to avoid the risk of missing liquidation opportunities and earning rewards. - ---8<-- "./include/fassets/open-beta.md" - ---8<-- "./include/fassets/prerequisites-agent.md" ---8<-- "./include/fassets/setup-commandline.md" - -## Configure the Access Keys - -The FAsset liquidators operate with an address for the Flare network chain. You must generate these keys to set up the liquidator. - -1. Create or use an existing management wallet that will be your liquidator's management address. Fund this wallet with some CFLR so you can pay the gas fees for various smart contract calls using the [Flare faucet](https://faucet.flare.network/). - -2. Generate the secrets using this command by replacing the `MANAGEMENT_WALLET_ADDRESS` with your cold wallet address: - - ```bash - yarn key-gen generateSecrets --other MANAGEMENT_WALLET_ADDRESS --other -o secrets.json - ``` - - --8<-- "./include/fassets/generate-keys-info.md" - -3. Prevent other users from reading the `secrets.json` file: - - ```bash - chmod 600 secrets.json - ``` - -4. The `native_rpc` is the API key used to connect to a public node on the Coston blockchain network. -This key is necessary for authenticating and enabling secure communication between your application and the blockchain network. -To configure your connection, you must fill the `native_rpc` field in the `secrets.json` file with the API key provided by the Flare team during the FAssets testing period. -Use this value in the `secrets.json` file: - - ```json - "native_rpc": "AavSehMLhcgz3crQHH5YJ3Rt8GMQGdV9aViGilADXGnTcjij", - ``` - -1. The `secrets.json` file contains the `liquidator.address` and `liquidator.private_key` fields, representing the Flare account responsible for running the liquidator and covering gas fees for the smart contract calls. Ensure this address has enough tokens to cover gas fees by transferring some CFLR to it. You can obtain CFLR tokens from the [Flare faucet](https://faucet.flare.network/). - -2. The `liquidator` account must hold enough FAssets to execute [liquidation tasks](../../tech/fassets/index.md#liquidators) and cover the liquidated agent FAssets amount. -Therefore, you must mint FAssets and move them to the `liquidator` account. -For a more detailed explanation, please refer to the [Minting and Redeeming](../../user/fassets/index.md) guide. - -## Running the Liquidator - -The liquidator observes the FAssets system and reacts to its state. -To run the liquidator, you need to run the following command: - -```console -yarn run-liquidator -``` - -When you want to stop the server, press Ctrl + C. - -### Running the Liquidator as System Service - -In production scenarios, run the `run-liquidator` command as a service to maximize uptime -Here, you have instructions to run the liquidator as a `systemd` service for [running the liquidator as a daemon](https://github.com/flare-labs-ltd/fasset-bots/blob/main/docs/systemd/systemd-service.md). -Using this guide, you must change the `agent-bot` to the `liquidator-bot`. - - -## Related Pages - -* [Minting and Redeeming FAssets](../../user/fassets/index.md) -* [Deploying an FAssets Agent](deploying-agent.md) -* [FAssets Open Beta](../../tech/fassets/open-beta.md) diff --git a/docs/infra/fassets/managing-agent.md b/docs/infra/fassets/managing-agent.md deleted file mode 100644 index 5851716bb..000000000 --- a/docs/infra/fassets/managing-agent.md +++ /dev/null @@ -1,314 +0,0 @@ ---- -title: Managing an Agent with the Admin Console ---- - -# Managing an FAssets Agent with the FAssets Agent Admin Console - -The FAssets Agent Admin Console (Admin Console) helps you manage agent tasks like depositing collateral and setting up alerts. - -Although managing the [agent bot](../../tech/fassets/index.md#agents) is simplified by the Admin Console UI, installation of both the agent bot and the Admin Console UI is done from the command line. - -The following procedures teach you how to configure the components required to use the Admin Console, including: - -* A backend that reads the state of the agent bot and makes it available to the UI -* The UI, which talks to the backend - -Afterward, these procedures explain how to use the Admin Console to manage agent tasks. - ---8<-- "./include/fassets/open-beta.md" - -## Prerequisites - -You need to [have deployed an agent bot and have it running](./deploying-agent.md). - -## Configuration Guide - -### Adding login password to secrets - -Agent UI uses a password login. The password is set in `secrets.json`, where you need to set the parameter `apiKey.agent_bot` with a password -that you will use to login to agent UI with. Example of `secrets.json` after adding the password: -```json - "apiKey": { - "agent_bot": "verySafePassword", - ... other secrets - } -``` - -### Configuring the Backend Bot - -After you have successfully deployed the agent bot and it is running, you can configure the backend that links it with the Admin Console UI. - -1. In the folder where you installed the agent bot (typically `fasset-bots`), navigate to `packages/fasset-bots-api`, and create an `.env` file. - This file is not the same file that you created when you deployed the bot. -2. Copy the following text, and paste it into the `.env` file you just created: - - ```ini - ## Path to config file for the agent bot (and other bots) for MYSQL - FASSET_BOT_CONFIG="../fasset-bots-core/run-config/coston-bot-mysql.json" - ## If you want to use SQLite (not recommended), uncomment the line below and comment on the line above - # FASSET_BOT_CONFIG="../fasset-bots-core/run-config/coston-bot.json" - - ## Path to secrets file for the agent bot (and other bots) - FASSET_BOT_SECRETS="../../secrets.json" - - ## Enable the following line on Windows to allow reading secrets, since - ## secrets file permission check does not work - # ALLOW_SECRETS_ON_WINDOWS=true - - ## (Optional) Path to config file for users, instead you can use `-c` - ## parameter - # FASSET_USER_CONFIG="../fasset-bots-core/run-config/coston-user.json" - - ## (Optional) Path to secrets json file for users, instead you can use `-s` - ## parameter. - # FASSET_USER_SECRETS="" - - ## (Optional) Path to directory, used for storing unexecuted minting - ## Defaults to `fasset` subdirectory in user's home directory - # FASSET_USER_DATA_DIR="" - - ## (Optional) Path to the database file for the bot (only needed if SQLite database) - # FASSET_BOT_SQLITE_DB="../../path-to-.db-file" - ``` - -3. If you are using SQLite (not recommended) choose one of the following options: - * If you already have [agent vaults](../../tech/fassets/collateral.md#vault-collateral): - 1. Navigate to the root of the `fasset-bots` repository, and locate the `.db` file. - The file name will be in the - `fasset-bots-coston.SOME_HEX_VALUE.db` format. - 2. Copy the file name of the `.db` file. - 3. Return to the `.env` file you created in step 1, and paste the file name of the `.db` file as the value for `FASSET_BOT_SQLITE_DB`. - For example, `FASSET_BOT_SQLITE_DB="../../fasset-bots-coston.43B835D3.db"`. - * If you do not have [agent vaults](../../tech/fassets/collateral.md#vault-collateral): - 1. Open the `.env` file you created when you deployed the agent bot, and add - `FASSET_BOT_SQLITE_DB ="./fasset-bots-coston.db"`. - 2. Open the `.env` file you created in step 1, and specify `../../fasset-bots-coston.db` as the value of `FASSET_BOT_SQLITE_DB`. - -### Enabling Alerts - -You can enable alerts to be sent to the backend and displayed in the frontend. - -1. In the root of the respository, create a file named `alerts.json`. -2. Copy the following text and paste it into the `alerts.json` file. - - ```json - { - "extends": "coston-bot-mysql.json", - "apiNotifierConfigs": [ - { - "apiKey": "myApiSecret", - "apiUrl": "http://localhost:1234/" - } - ] - } - ``` - Fill the `apiKey` parameter with some random string. This will be used as api key by the bot to send notifications to the backend. - Optionally (not recommended), if you use SQLite, change the `extends` value in the JSON to `coston-bot.json`. - -3. In `secrets.json` add add the same string to `apiKey.notifier_key`, which is used by the backend to accept alerts from the bot. For example - if your `alerts.json` file looks like this - ```json - { - "extends": "coston-bot-mysql.json", - "apiNotifierConfigs": [ - { - "apiKey": "myApiSecret", - "apiUrl": "http://localhost:1234/" - } - ] - } - ``` - - Then in the `secrets.json` you will have - ```json - "apiKey": { - "notifier_key": "myApiSecret", - ... other secrets - } - ``` - -4. Open the `.env` file in this same folder, and change the path specified for `FASSET_BOT_CONFIG` to the `alerts.json` file: - - ```ini - FASSET_BOT_CONFIG="./alerts.json" - ``` -Then move to the folder in `fasset-bots/packages/fasset-bots-api` and also change `FASSET_BOT_CONFIG` to the alerts.json file: - ```ini - FASSET_BOT_CONFIG="../../alerts.json" - ``` - -## Configure Existing Agents to Setup MySQL - -Agents that already have successfully configured `fasset-bots` backend need to do the following: - -1. Install the MySQL server. -2. Create a user in MySQL as stated above. -3. In the `.env` file located at the root of the repository, you should modify the `FASSET_BOT_CONFIG` variable: - ``` - FASSET_BOT_CONFIG="./packages/fasset-bots-core/run-config/coston-bot-mysql.json" - ``` -4. In the `secrets.json` file, fill the `database` field with the username and password you created in MySQL. -5. In the `.env` file located at `fasset-bots/packages/fasset-bots-api`, you must update the `FASSET_BOT_CONFIG` variable: - ``` - FASSET_BOT_CONFIG="../fasset-bots-core/run-config/coston-bot-mysql.json" - ``` -6. If you have enabled alerts, you need to change the `extends` parameter in `alerts.json`: - ``` - "extends": "coston-bot-mysql.json" - ``` - - -### Running the Admin Console Backend - -1. In the root of the repository, run the command: - - ```bash - yarn start_agent_api - ``` - or - ```bash - yarn start_agent_api_debug - ``` - -This command must continue to run for as long as you intend to use the UI. -When you are finished using the UI and want to stop the server, press Ctrl + C. - -!!! info - - Run `start_agent_api` or `start_agent_api_debug` as a service to maximize uptime for production use. Here, you have instructions to run the agent as a `systemd` service for [running the bot as a daemon](https://github.com/flare-labs-ltd/fasset-bots/blob/main/docs/systemd/systemd-service.md). - -### Setting Up the Admin Console - -1. Navigate outside of the `fasset-bots` folder. -2. Clone the UI repository and enter the `src` directory: - - ```bash - git clone https://github.com/flare-labs-ltd/fasset-agent-ui.git - cd fasset-agent-ui/src - ``` - -3. Create `.env` file, copy the following text, paste it in the `.env` file, and save it. - - ```ini - WALLETCONNECT_PROJECT_ID=44e7bd998ec5a65ca096ab99c9b71af8 - API_URL=http://localhost:1234/api - ``` - -### Running the Admin Console - -1. Ensure both the [agent bot](deploying-agent.md#running-the-agent) and the [backend](#run-the-fasset-bots-backend) are running. -2. Navigate to the `src` directory. -3. You can run the app locally or from Docker: - * To run the app locally: - 1. Run `npm install`. - 2. Run `npm run dev`. - 3. Open in a browser. - * To run the app from Docker: - 1. Run `docker-compose up -d --build`. - 2. Open in a browser. - - The Admin Console dashboard is displayed. - -
- ![Admin Console dashboard](fassets-admin-dashboard.png){ loading=lazy .allow-zoom } -
Admin Console dashboard.
-
- -## Usage Guide - -Ensure the [agent bot](deploying-agent.md#running-the-agent), the [backend](#run-the-fasset-bots-backend), and the [Admin Console](#running-the-admin-console) are running and that is open in a browser showing the Admin Console dashboard. - -The Admin Console dashboard shows: - -* The agent's management address, which you [configured in the `secrets.json` file](./deploying-agent.md#configure-the-access-keys) -* The [whitelist status](./deploying-agent.md#whitelist-the-management-address) of the management address -* One or more of the agent's bots, all of which are managed from the one management address, and the agents' vaults -* A list of alerts, if you [enabled them](#enabling-alerts), and notifications sent from Flare - -### Connecting to the Admin Console - -Some operations in the Admin Console can be done only by the management address, so you must connect using this address. - -1. On the Admin Console dashboard, click **Connect Wallet**, and sign in with your management address. - -### Adding Agent Vaults - -1. On the Admin Console dashboard, locate the agent bot for which you want to add a vault, and click the three dots icon in the **Actions** column. - The **Agent Bot Actions** menu is displayed. -2. Click **Add Vault**. -3. Specify values for required settings [**FASSET TYPE**](../../tech/fassets/index.md#fasset-type), [**VAULT COLLATERAL TOKEN**](../../tech/fassets/collateral.md#vault-collateral), and the [**POOL TOKEN SUFFIX**](../../tech/fassets/collateral.md#pool-collateral). - The suffix identifies your vault and is used to complete the name of the collateral pool token (CPT). - For example, `LBD`. -4. If necessary, adjust the default values for the other settings. -5. Click **Save and execute**, and then click **Confirm** to proceed. - -### Changing Agent Vault Settings - -1. In the **Vaults** section on the dashboard, locate the [agent vault](../../tech/fassets/collateral.md#vault-collateral) you want to modify, and click the three dots icon in the **Actions** column. - The **Vault options** menu is displayed. - -
- ![Vault Options](fassets-admin-vaults-menu.png){ loading=lazy .allow-zoom } -
Vault Options.
-
- -2. Under **Vault actions**, click **View Vault**. - The settings for the agent vault are displayed. - -
- ![Agent Vault Settings](fassets-admin-vaults-view.png){ loading=lazy .allow-zoom } -
Admin Vault Settings.
-
- -3. Click **Edit** at the top of the page. -4. Update your settings. - These settings always have [time locks](../../tech/fassets/parameters.md#time-locks) to minimize abuse. - During the Open Beta, the time-locks are further reduced so that you can try different configurations. - Before you save your updates, ensure you understand the [time-locks associated with settings](../../tech/fassets/parameters.md#time-locks) you are changing. -5. Click **Save and execute**. - -### Depositing Vault Collateral - -1. In the **Vaults** section on the dashboard, locate the [vault](../../tech/fassets/collateral.md#vault-collateral) you want to update, and click the three dots icon in the **Actions** column. - The **Vault options** menu is displayed. -2. In the **Agent Vault Operations** section, click **Deposit collateral**. - The **Deposit Collateral** window is displayed. -3. In the **AMOUNT** field, specify the amount of collateral to deposit into the vault. - You can deposit only the type of collateral that your vault was created to support. - For example, if you created a `testUSDC` vault, you can deposit only `testUSDC`. -4. Click **Deposit**. - A confirmation message is displayed. - -### Depositing Pool Collateral - -1. In the **Vaults** section on the dashboard, locate the [vault](../../tech/fassets/collateral.md#pool-collateral) you want to update, and click the three dots icon in the **Actions** column. - The **Vault options** menu is displayed. -2. In the **Agent Vault Operations** section, click **Deposit FLR in Pool**. - The **Deposit FLR in Pool** window is displayed. -3. In the **AMOUNT FLR** field, specify the amount of `$FLR` to deposit into the collateral pool. -4. Click **Deposit**. - A confirmation message is displayed. - -### Activating and Closing Vaults - -Activating a vault makes it publicly available for minting FAssets. -To be activated, a vault must contain at least 1 [lot](../../tech/fassets/minting.md#lots) for minting. - -Closing a vault makes it unavailable for minting FAssets. - -* To activate a vault: - 1. On the dashboard, locate the [vault](../../tech/fassets/collateral.md#vault-collateral) you want to activate, and click the three dots icon in the **Actions** column. - The **Vault options** menu is displayed. - 2. In the **Agent Vault Operations** section, click **Activate Vault (Enter)**. - The **Activate Vault** window is displayed. - 3. Read the message in the **Activate Vault** window about minting requirements, ensure your vault contains at least 1 lot to meet the requirement, and then click **Confirm** to activate the vault. - A confirmation message is displayed. - -* To close a vault: - - 1. On the dashboard, locate the [vault](../../tech/fassets/collateral.md#vault-collateral) you want to close, and click the three dots icon in the **Actions** column. - The **Vault options** menu is displayed. - 2. In the **Agent Vault Operations** section, click **Close Vault (Exit)**. - The **Deactivate Vault** window is displayed. - 3. Ensure you want to close the vault, and click **Confirm** to close it. - A confirmation message is displayed. diff --git a/docs/infra/index.md b/docs/infra/index.md index 806e6f874..a592660a9 100644 --- a/docs/infra/index.md +++ b/docs/infra/index.md @@ -1,7 +1,3 @@ # Infrastructure Guides This section contains step-by-step guides on how to deploy the different components that make up the Flare ecosystem, and be rewarded for it. - -Select one of the topics below: - -* [Deploying FAssets Agent](./fassets/index.md) diff --git a/docs/products/index.md b/docs/products/index.md index 9957a37c8..8067d2655 100644 --- a/docs/products/index.md +++ b/docs/products/index.md @@ -4,6 +4,6 @@ In this section you can read more about Flare's core protocols and products. * [FTSO](../tech/ftso/index.md) * [Flare Data connector](../tech/data-connector.md) -* [FAssets](../tech/fassets/index.md) +* [FAssets](https://dev.flare.network/fassets/overview) * [Validator nodes](../tech/validators.md) * [API Portal](../tech/api-portal.md) diff --git a/docs/tech/fassets/collateral.md b/docs/tech/fassets/collateral.md deleted file mode 100644 index 100f57802..000000000 --- a/docs/tech/fassets/collateral.md +++ /dev/null @@ -1,429 +0,0 @@ ---- -title: Collateral -mathjax: true -search: - boost: 2 ---- - -# FAssets Collateral - -[FAssets](./index.md) collateral is locked in contracts that ensure the minted FAssets can always be redeemed for the underlying assets they represent or compensated by collateral. - -Along with Flare's native token, `$FLR`, any governance-approved [ERC-20](glossary.md#erc20) token on the Flare blockchain can be used as collateral. - -## Collateral Types - -Two kinds of collateral secure FAssets: vault collateral and pool collateral. - -
- ![FAssets collateral types](fassets-collateral.png){ loading=lazy .allow-zoom } -
FAssets collateral types.
-
- -Vault collateral is provided exclusively by agents and ensures they perform their duties. -Pool collateral is provided by agents and `$FLR` holders who choose to contribute to the pool. -It is a safeguard when a sudden drop in the price of the vault collateral makes it insufficient to back the underlying assets. - -The two types of collateral are explained next. -Collateral pool tokens and minting fees are explained afterwards. - -### Vault Collateral - -Vault collateral consists of the types of collateral chosen by agents to store in [their vaults](./index.md#vault-and-collateral-pool). -Flare governance approves the valid types, which are generally [stablecoins](glossary.md#stablecoin), such as `$USDC`, `$USDT`, or other highly liquid tokens on the Flare network. - -Agents choose one of the types defined by FAssets governance and use it as collateral in their vaults. -Agents cannot switch to a different type after a vault is created, but they can create any number of vaults, with different types. - -Each collateral type defines an [ERC-20](glossary.md#erc20) token to use as collateral, a series of [collateral ratios](#the-collateral-ratio), and information to retrieve the asset's price from the FTSO system. -Governance reserves the right to add new types or deprecate existing types. -If governance deprecates a type, agents must switch to a supported type. - -Each vault is associated with a single, unique address on the underlying chain called the agent's underlying address. -It receives underlying assets when they are minted into FAssets and sends underlying assets to the redeemer's address when they are redeemed. - -When an agent creates a vault, the underlying address is checked for validity using the Flare Data Connector. -Otherwise, malicious agents could provide an address that systematically blocks payments and exploit the [minting process](./minting.md) to their advantage. - -### Pool Collateral - -When the price of the vault collateral changes in such a way that the vault collateral cannot fully back all the minted FAssets, a [liquidation](./liquidation.md) mechanism ensures enough FAssets are burned to restore balance. -The pool collateral provides an additional source of backing for situations when the price fluctuates too rapidly for liquidations to correct the imbalance. - -Pool collateral is always native `$FLR` tokens (or `$SGB` tokens on the [Songbird network](../flare.md#flare-networks)) and can be used as an additional source of collateral for [liquidations](./liquidation.md) and [failed redemptions](./redemption.md#redemption-payment-failure). - -Anyone can participate in the FAssets system by providing native tokens to this pool. -In return, providers receive **collateral pool tokens** (CPTs) as proof of the share of native tokens they provided to a specific pool from a specific agent. -CPTs are [ERC-20](glossary.md#erc20) tokens specific to both an agent and a pool. - -Providers can redeem their CPTs for `$FLR`, or even transfer or trade them, after a governance-defined time period has elapsed since they entered the pool. -This **time lock** is necessary to reduce [sandwiching](glossary.md#sandwiching) attacks. -{ #time-lock } - -Additionally, CPT holders are entitled to a share of any fee the agent earns from minting FAssets using this pool as explained in the next section. - -??? info "Formulas: CPT Conversion" - - The amount of collateral pool tokens a provider $p$ receives upon entering a pool is calculated as: - - $$ - received\_CPT_p = { added\_collateral_p \over collateral\_in\_pool } \times currently\_issued\_CPT - $$ - - where: - - * $added\_collateral_p$ is the amount of `$FLR` tokens that provider $p$ is adding to the pool. - * $collateral\_in\_pool$ is the amount of `$FLR` tokens in the pool before adding the new tokens. - * $currently\_issued\_CPT$ is the circulating amount of collateral pool tokens. - - When a pool is first created, $received\_CPT_p = added\_collateral_p$. - - The amount of `$FLR` collateral a provider receives when they redeem their CPT is calculated using the opposite formula: - - $$ - received\_collateral_p = collateral\_in\_pool \times { redeemed\_CPT_p \over currently\_issued\_CPT } - $$ - - where: - - * $redeemed\_CPT_p$ is the amount of CPT the provider is returning to the pool. - -
-??? example "Example: CPTs Conversion" - - | | | `$FLR` in pool | Issued CPTs | - | --- | ---------------------------------------------------------------------------------------- | -------------: | ----------: | - | 1. | An agent creates a new vault. The collateral pool is initially empty of `$FLR` and fees. | 0 | 0 | - | 2. | Alice deposits 100 `$FLR` and gets 100 CPTs in return. | 100 | 100 | - | 3. | Bob deposits 200 `$FLR` and gets 200 CPTs in return. | 300 | 300 | - | 4. | Alice redeems 50 CPTs and receives 50 `$FLR` in return. | 250 | 250 | - - Note that in general 1 FLR does not always correspond to 1 CPT, because of mechanisms like the [top-up](#top-up), for example. -
- -## FAsset-Minting Fees and Debt - -As part of the minting process, users pay a [minting fee](./minting.md#minting-fee) on the underlying chain. -The agent's share of this fee remains on the underlying chain, whereas the pool's share triggers the minting of an equivalent amount of FAssets on the Flare network. - -These FAssets coming from the minting fee are added to the collateral pool, where they are shared between collateral providers in proportion to the amount of CPTs that providers have. -At any time, providers can claim their due share of the fees in the pool. -When providers exit the collateral pool by redeeming their CPTs, any remaining unclaimed fee is automatically transferred to them. - -Providers are naturally only entitled to the minting fees accrued after they entered the pool. -Therefore, providers entering a pool with preexisting fees are assigned a **fee debt**. -The amount of fees a provider can actually withdraw from the pool is calculated by first subtracting their debt from the total amount of fees in the pool. -In this way, the amount of fees that a provider can withdraw upon entering a pool is exactly zero. -{ #debt-lock } - -A provider's fee debt: - -
-| Increases when the provider | Decreases when the provider | -| ------------------------------------------- | ---------------------------------------------- | -| Enters a pool which already has fees in it. | Exits the pool, partially or completely. | -| Withdraws FAsset fees. | Deposits FAssets, paying off part of the debt. | -
- -It is worth noting that: - -* When a provider withdraws fees, their debt increases by the same amount. -* Since CPTs are ERC-20 tokens, a secondary market for them is expected to develop. - If CPTs become more valuable than the FAsset fees they represent, returning the FAssets and paying off part of their fee debt might be more lucrative for providers. - -??? info "Formulas: Fee Entitlement" - - The following formulas consider all the above information to calculate each provider's due share of FAsset minting fees. - - The amount of debt a provider $p$ is assigned upon entering a pool is calculated as: - - $$ - fee\_debt_p = { added\_collateral_p \over collateral\_in\_pool } \times fees\_in\_pool - $$ - - where: - - * $added\_collateral_p$ is the amount of `$FLR` tokens that provider $p$ is adding to the pool. - * $collateral\_in\_pool$ is the amount of `$FLR` tokens in the pool before adding the new tokens. - * $fees\_in\_pool$ is the amount of FAsset minting fees currently in the pool. - - The following formulas are based on the concept of **virtual fees**, which are the fees that a provider would be entitled to if they had no fee debt. - - The **total virtual fees** is the sum of all provider's virtual fees and can be expressed as: - - $$ - total\_virtual\_fees = fees\_in\_pool + total\_fee\_debt - $$ - - where: - - * $total\_fee\_debt$ is the sum of the fee debt held by all providers $= \sum_p fee\_debt_p$ - - Then, the virtual fees due to a provider $p$, i.e., the amount of FAsset minting fees they would be entitled to if they had no debt, are: - - $$ - virtual\_fees_p = { CPT_p \over currently\_issued\_CPT } \times total\_virtual\_fees - $$ - - where: - - * $CPT_p$ is the amount of CPTs provider $p$ holds. - * $currently\_issued\_CPT$ is the circulating amount of CPTs. - - Finally, the amount of fees from the pool that a provider $p$ is free to withdraw at any given time is: - - $$ - free\_fees_p = virtual\_fees_p - fee\_debt_p - $$ - - where: - - * $fee\_debt_p$ is the amount of fee debt that provider $p$ holds. - -
-??? example "Example: Fee Entitlement" - - | | | `$FLR` in pool | Fees in pool | Total fee debt | Total virtual fees | - | --- | ------------------------------------------------------------------------ | -------------: | -----------: | -------------: | -----------------: | - | 1. | An agent creates a new vault. | 0 | 0 | 0 | 0 | - | 2. | Alice deposits 100 `$FLR` and gets 100 CPTs in return. | **100** | 0 | 0 | 0 | - | 3. | 10 FAssets of fees are added to the pool due to a mint. | 100 | **10** | 0 | **10** | - | 4. | Bob deposits 100 `$FLR` and gets 100s CPT in return. | **200** | 10 | **10** | **20** | - | 5. | 10 more FAssets of fees are added to the pool due to another mint. | 200 | **20** | 10 | **30** | - | 6. | Alice withdraws 10 FAssets of fees. | 200 | **10** | **20** | 30 | - | 7. | Bob exits the pool by returning the 100 CPTs and withdrawing 100 `$FLR`. | **100** | **5** | **10** | **15** | - - After step **4**, Bob is not entitled to any of the fees in the pool: - - * Bob is assigned an initial fee debt of 10 FAssets, according to the $fee\_debt_p$ formula in the box above. - * As a result, the total virtual fees are increased to 20 FAssets. 10 of them are in fees, and 10 of them are in debt. - * Each user now holds half the total CPTs, therefore they are allowed to withdraw half the virtual fees, this is, 10 FAssets each. - * Alice has no debt, so she can withdraw 10 FAssets, which is all the fees in the pool, because she was the only CPT holder when these fees were accrued. - * Conversely, Bob has 10 FAssets of debt, so he can't withdraw any of the fees. - - After step **5**, the new fees are shared between both users, and the previous 10 FAssets still belong to Alice: - - * The 10 FAssets in new fees increase the total virtual fees to 30. - * Both users are entitled to half of the total, which is 15 FAssets each. - * Alice has no debt, so she can withdraw 15 FAssets: the initial 10 plus half of the 10 that were added to the pool afterwards. - * Bob has 10 FAssets of debt, so he can only withdraw 5, this is, his entitlement (15) minus the debt (10). - - After step **6**: - - * The 10 FAssets that Alice has withdrawn have converted into debt for her. - * However, this action does not change the total virtual fees because the sum of fees in the pool and total debt remains constant. - * Therefore, both users are still entitled to 15 FAssets each. - * However, now Alice has 10 FAssets of debt, so she can withdraw only 5 more. - * Nothing has changed for Bob, who can still withdraw 5 FAssets. - - In step **7**: - - * Bob is returning 100 CPTs, which is 50% of the circulating CPTs, so he is entitled to half the total virtual fees, 15 FAssets. - * Because he is exiting the pool, all his debt, which is 10 FAssets, must be cancelled. - * He can withdraw the remaining 5 FAssets from the fees pool. - * After Bob withdraws his 5 FAssets, the pool contains only 5 FAssets, which correspond to the amount that Alice can withdraw. -
- -## Transferable and Locked CPTs - -CPTs can always be **redeemed** by exiting the pool, but only the portion of them above the fee debt can be **transferred** to another account. -Therefore, CPTs held by providers are divided into two types: - -* **Transferable**: Tokens whose [time lock](#time-lock) has expired and are also free of [fee debt](#debt-lock). - These tokens are fungible, and they can be transferred or traded just like any other ERC-20 token. -* **Locked**: The CPTs serve only as proof of ownership of some of the collateral in the pool, and they cannot be transferred nor traded. - - Locked CPTs are one of the following types: - - * **Time-locked**: Tokens whose [time lock](#time-lock) has not expired must wait to become transferable or redeemable. - * **Debt-locked**: Tokens corresponding to an amount of fees below the provider's fee debt cannot be transferred because they would need to carry the debt with them. - However, they can be [redeemed](#redemption-of-cpts). - - As new fees arrive in the pool, some previously debt-locked tokens become transferable. - - These CPTs can also become transferable by **adding** FAssets to the pool, which settles, either partially or completely, the fee debt. - -??? info "Formulas: Collateral Pool Token Transferability" - - The amount of CPTs that a given provider $p$ can transfer is calculated as: - - $$ - transferable\_CPT_p = { free\_fees_p \over virtual\_fees_p } \times CPT_p - $$ - - where: - - * $free\_fees_p$ is the amount of fees from the pool that a provider $p$ can withdraw, as defined in the previous formula box. - * $virtual\_fees_p$ is the amount of FAsset minting fees that provider $p$ would be entitled to if they had no debt, as defined in the previous formula box. - * $CPT_p$ is the amount of CPTs provider $p$ holds. - - Accordingly, the amount of CPT that is locked and cannot be transferred is calculated as: - - $$ - locked\_CPT_p = { fee\_debt_p \over virtual\_fees_p } \times CPT_p - $$ - - As new minting fees arrive in the pool, the $transferable\_CPT_p$ of all providers also increases. - - Conversely, when a provider withdraws fees from the pool, their debt increases in the same amount, and $total\_virtual\_fee$ remains the same. - Therefore, only that provider's $transferable\_CPT_p$ is reduced, without affecting the rest of the providers. - -
-??? example "Example: Collateral Pool Token Transferability" - - | | | Issued CPTs | Fees in pool | Total fee debt | Total virtual fees | - | --- | ------------------------------------------------------------------ | ----------: | -----------: | -------------: | -----------------: | - | 1. | An agent creates a new vault. | 0 | 0 | 0 | 0 | - | 2. | Alice deposits 100 `$FLR` and receives 100 CPTs. | **100** | 0 | 0 | 0 | - | 3. | 10 FAssets of fees are added to the pool due to a mint. | 100 | **10** | 0 | **10** | - | 4. | Alice withdraws 5 FAssets of fees. | 100 | **5** | **5** | 10 | - | 5. | 10 more FAssets of fees are added to the pool due to another mint. | 100 | **15** | 5 | **20** | - | 6. | Alice transfers 75 CPTs to Bob. | 100 | 15 | 5 | 20 | - | 7. | Alice exits the pool by returning her remaining 25 CPTs. | **75** | 15 | **0** | **15** | - - After step **2**, all of Alice's CPTs are transferable because she has no debt. - - After step **3**, all of Alice's CPTs continue to be transferable, and she is entitled to 100% of the fees in the pool. - If she transferred or traded his CPTs, the recipient of those CPTs would be entitled to the fees. - - After step **4**, only half of Alice's CPTs are transferable (50 CPTs). The other half is debt-locked. - - After step **5**, only 25% of Alice's CPTs remain locked (25 CPTs), which correspond to her 5 FAssets of debt. - - After step **6**: - - * Alice has 25 CPTs, which entitle her to 5 FAssets of virtual fees. - After subtracting her 5 FAssets of fees, her free fees are zero, which means she cannot withdraw any more fees. - * Bob has 75 CPTs and no debt, so he is entitled to 15 FAssets of fees, which are all the fees in the pool. - - In step **7**: - - * Alice is returning 25 CPTs, which is 25% of the circulating CPTs, so she is entitled to 25% of the total virtual fees, which is 5 FAssets. - * Because she is exiting the pool, all her debt, which is 5 FAssets, must be cancelled. - * Her $free\_fees_p$ are 0, so she cannot take any of the remaining fees in the pool. - * The 15 FAssets that remain in the fee pool now belong entirely to Bob, who holds 100% of all the issued CPTs, which is 75 CPTs. -
- -## The Collateral Ratio - -The collateral ratio (CR) is the ratio between the value of all the tokens used as collateral and the total value of the underlying assets held by an agent at any given time. -The agent's vault and the collateral pool each has its own unique collateral ratio, which is constantly changing as the value of the underlying assets and the collateral change. -These values are obtained using the [FTSO system](../ftso/index.md). - -!!! example "Example: Vault and Pool CR" - - Assume an amount of FAssets currently valued at $1000 USD, backed by $1500 worth of `$USDC` in vault collateral and $2000 worth of `$FLR` in pool collateral. - - The resulting vault CR is then $\$1500 \over \$1000$ = 1.5. - - The resulting pool CR is $\$2000 \over \$1000$ = 2. - -Several thresholds are defined for the collateral ratio, and they are used at different times during the FAsset operations. -Some are set by the system, and others are set by the agent: - -
- ![Collateral ratio thresholds](fassets-cr.png){ loading=lazy .allow-zoom } -
Collateral ratio thresholds.
-
- -### System-wide Thresholds - -The following thresholds are set by the FAssets system's governance and are the same for all agents: - -* **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. - -* **Liquidation 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 the Liquidation 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. - - However, if the CR falls below the Liquidation CR, [liquidations](./liquidation.md) can start immediately. - - The value of each Liquidation CR is approximately 10% less than the minimal CR. - - !!! example - Assume the **minimal CR** is 1.4 and the **Liquidation CR** is 1.3. - - If the agent's vault CR drops below 1.3, the agent's position can be liquidated immediately. - If the agent's vault CR drops below 1.4 but not below 1.3, the agent has some time to amend the position before it can be liquidated. - - Adjusted for the collateral pool's minimal CR, the same example applies to the collateral pool. - -* **Safety CR**: If one or both of the collateral types fall below Liquidation 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. - -### Agent Thresholds - -The following thresholds are set by each agent according to their own preferences: - -* **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 - -When collateral providers exit the pool by redeeming their CPTs, the FAssets system burns them and returns the appropriate share of the collateral plus the share of [FAsset-minting fees minus any FAsset-fee debt](#fasset-minting-fees-and-debt). - -Providers also have the option to exit the pool partially, by redeeming only some of their CPTs. -In this case, they can choose one of the following options to manage their due FAsset fees: withdraw the fees, reduce the fee debt, or both, keeping the current fee-to-debt-ratio. - -However, providers can exit, either fully or partially, only when the [collateral ratio (CR)](#the-collateral-ratio) is high enough. -After they exit, the **CR** must be higher than the **exit CR** to prevent their exit from reducing the **CR** to a dangerous level. - -Therefore, exits are impossible when the **CR** is below the **exit CR**. -In this case, if providers have enough FAssets, they can exit by **self-closing**, which burns enough of their FAssets, plus their fees, to release their collateral. - -Providers are mainly compensated in underlying assets for the burned FAssets, depending on [the number of lots](./minting.md#lots) of FAssets that need to be redeemed: - -* If more than 1 lot needs to be redeemed, the value of the burned FAssets is redeemed through the standard [redemption process](./redemption.md). -* If less than 1 lot needs to be redeemed, the agent buys the underlying funds from the user using vault collateral, at the price reported by the [FTSO system](../ftso/index.md) minus a percentage defined by the agent. - This purchase by the agent occurs because fees on underlying chains can be expensive, which makes redemption of small quantities too expensive for the agent. - - Providers can always request this option instead of receiving underlying tokens. - Also, if enough vault collateral is not available, pool collateral is used instead. - -!!! warning - In the case where the agent does not redeem in the underlying asset, the FAssets system pays the provider in collateral from the agent's vault because the pool collateral backing the redeemed FAssets is already withdrawn. - - When this type of redemption occurs, users might receive less collateral than they would have received if they had made a normal redemption. - -## Agent's Stake in the Collateral Pool - -Agents must have a stake in their collateral pools, which means they must hold the amount of CPTs proportional, by a system-defined constant, to the backed amount of FAssets. -The maximum amount of minting is limited by the amount of collateral pool tokens held by the agents. -The agents' tokens are locked, which means they cannot be redeemed or transferred, while agents back these FAssets. - -When the agent's portion of the collateral pool is below the threshold, new mintings are not allowed. -However, this situation does not trigger a liquidation because only the total pool stake matters when collateral needs to be redeemed or a liquidation payment needs to be made. - -If an agent's actions force a payment to be made from the collateral pool, the agent's CPTs, valued by the paid native tokens and recalculated by the collateral-pool-price formula, are burned. -These actions can cause the agent's CPTs to be burned: - -* When a redemption payment fails, when enough vault collateral to compensate the redeemer is not available, or when the system is set to automatically pay for redemption failures from the collateral pool. -* Liquidation because the CR of the vault collateral is too low. -* Full liquidation because of an [agent infraction](./redemption.md#redemption-payment-failure) during a transfer on an underlying chain. - -## Top-up - -To reduce the likelihood of liquidations because the pool collateral is too low, the pool can be topped up at a reduced price when the **CR** is above the **top-up CR**. - -A top-up mechanism for vault collateral is not available. -To prevent liquidation, agents can add vault collateral any time. diff --git a/docs/tech/fassets/index.md b/docs/tech/fassets/index.md deleted file mode 100644 index 2eb0e6ce6..000000000 --- a/docs/tech/fassets/index.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -og_image: assets/thumbnails/fassets-concept.png -og_description: The FAssets system allows tokens on blockchains that do not support smart contracts to be used trustlessly with smart contracts on the Flare blockchain. -search: - boost: 2 ---- - -# FAssets - -The FAssets system allows tokens on blockchains that do not support smart contracts to be used trustlessly with smart contracts on the Flare blockchain. - -The following diagram summarizes the relationship between the FAssets system, its users, and the networks involved: - -
- ![FAssets system](fassets-system-overview.png){ loading=lazy .allow-zoom } -
FAssets overview.
-
- -Anyone on the Flare blockchain can mint FAssets as wrapped versions of the original tokens from other blockchains, known as underlying networks. -The original tokens from these chains, such as `$BTC`, `$LTC`, `$DOGE`, and `$XRP`, are called underlying assets. -For example, the FAsset version of `$BTC` is `$FBTC`. -{ #fasset-type } - -You can then use these FAssets in smart contracts and decentralized applications on Flare, and at any time you can redeem them for the underlying asset. - -The system is enabled by these Flare protocols: - -* [FTSO](../ftso/index.md), whose contracts provide decentralized price feeds for multiple tokens. -* [Flare Data Connector](../data-connector.md), which brings payment data from any connected chain into Flare. - -FAssets are backed by collateral provided by entities in the following roles that maintain the infrastructure of the system and hold Flare's native assets. -All these entities are independent of the Flare Foundation. - -## Roles in the FAssets System - -The following roles participate in the FAssets system: - -- [FAssets](#fassets) - - [Roles in the FAssets System](#roles-in-the-fassets-system) - - [Agents](#agents) - - [Users](#users) - - [Collateral Providers](#collateral-providers) - - [Liquidators](#liquidators) - - [Challengers](#challengers) - -### Agents - -The main purpose of agents is to keep the underlying assets while the minted FAssets are circulating. -Agents are off-chain programs, or bots, that: - -* Manage the account that holds an underlying asset, like `$BTC`. -* Provide the main part of the [collateral](./collateral.md). -* Repay the underlying assets when users redeem them. - -Each agent has an owner, a person who controls the following addresses associated with the agent. -These addresses enable owners to manage their agents and run FAsset operations. - -* **Work address**: Used by programs permanently online to execute operations like paying for redemptions. - Because the private key for this address resides on a server, it is vulnerable to theft. - To keep it secure, owners should regularly change the private key and its corresponding work address. - It is also known as a [hot wallet](glossary.md#hot_wallet). -* **Management address**: Used when the owner wants to change the work address. - This address can never change and will typically be a [multisignature account](glossary.md#multisignature). - It is also known as a [cold wallet](glossary.md#cold_wallet). - -Before agents can participate in the FAssets system, they must be verified by governance. -To be verified by governance, owners submit the agent's management address and, during the initial stages, some sort of off-chain personal information for [KYC](glossary.md#kyc) purposes. -After the agent is verified, its management address is added to a list of allowed agents. - -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 - -Users interact with the FAssets system in the following ways: - -* [**Minting**](./minting.md): Depositing underlying assets to an agent's address in exchange for the equivalent amount of FAssets minus a minting fee. - The minting fee is split between the agent and the [collateral pool](./collateral.md#pool-collateral), which receives fees as FAssets. - During this operation, users are called minters. - -* [**Redeeming**](./redemption.md): Returning FAssets to the FAssets system in exchange for the equivalent amount of underlying assets, paid from an agent's address. - If the agent fails to pay the underlying assets in time, the FAssets system pays the redeemer from the vault or the collateral pool plus a premium. - To ensure redemption is always possible, even after fluctuating price changes, the total collateral is always higher than the value of the backed FAssets. - During this operation, users are called redeemers. - -No eligibility requirements apply. -Anyone can use the FAssets system to mint and redeem. -In the future, a mechanism might be implemented to allow agents to reject minting requests according to their respective countries' [KYC](glossary.md#kyc) laws. - -### Collateral Providers - -Anyone can participate in the FAssets system by providing native `$FLR` tokens to an agent's [collateral pool](./collateral.md#pool-collateral) and becoming a collateral provider. - -For as long as these tokens remain locked in the pool, the collateral provider receives a share of every fee produced by FAssets minted using that pool. - -### Liquidators - -When an agent's collateral falls below the required minimum, it enters the [liquidation state](./liquidation.md). -In this state, liquidators send FAssets into the system in exchange for collateral from the agent's vault and collateral pool. -The collateral they receive has the same value as the FAssets they send plus a premium. -The FAssets sent by liquidators are burned, which reduces the amount of FAssets that the agent's collateral needs to back. - -Once the agent's collateral is above a safety margin, the liquidation state ends. - -No eligibility requirements apply. -Anyone can be a liquidator, contribute to the health of the FAssets system, and earn rewards in the process. - -### Challengers - -Challengers monitor an agent's underlying address to detect illegal transactions that reduce the amount of underlying assets below the [backing factor](#agents). -When challengers detect an illegal transaction, they provide the proof to the FAssets system in exchange for a reward from the agent's vault. - -Then, the offending agent enters [full liquidation](./liquidation.md), and the agent's vault is permanently locked against new mintings. - -No eligibility requirements apply. -Anyone can be a challenger, contribute to the health of the FAssets system, and earn rewards in the process. - -## How the FAssets System Works - -Select one of the following topics to continue learning about FAssets: - -* [Collateral](./collateral.md) -* [The minting process](./minting.md) -* [The redemption process](./redemption.md) -* [Liquidation](./liquidation.md) -* [Operational Parameters](./parameters.md) diff --git a/docs/tech/fassets/liquidation.md b/docs/tech/fassets/liquidation.md deleted file mode 100644 index 82993d9a0..000000000 --- a/docs/tech/fassets/liquidation.md +++ /dev/null @@ -1,340 +0,0 @@ ---- -title: Liquidation -mathjax: true -search: - boost: 2 ---- - -# FAssets Liquidation - -Liquidation is the process of selling assets to bring the FAssets system back to health after an [agent](./index.md#agents) becomes undercollateralized. - -The following types of liquidation can occur: - -* **Unhealthy position liquidation**: Occurs when the [collateral ratio](./collateral.md#the-collateral-ratio) (CR) of either the agent's vault or collateral pool falls below its respective [minimal CR](./collateral.md#system-wide-thresholds). - In this case, the agent's position is liquidated until the collateral ratio reaches the [safety CR](./collateral.md#system-wide-thresholds) or all of the backed FAssets are liquidated. -* **Full liquidation**: Occurs when the agent makes an [illegal payment](#illegal-payments) from the underlying chain address. - In this case, all the FAssets backed by the agent are liquidated, and the liquidation cannot be stopped. - -In both cases, [liquidators](./index.md#liquidators), who can be anyone who holds FAssets, are encouraged to sell their FAssets back to the system. -They will be paid with the agent's collateral plus a premium, as a penalty against the agent for unhealthy positions or misconduct. - -## Liquidation Process - -When liquidation starts, any liquidator can send FAssets and get paid with a combination of vault collateral and pool collateral at the current asset price multiplied by a premium factor greater than 1. -The maximum amount of FAssets that is accepted is the amount required to make the agent's position healthy again, rounded up to the next lot. - -The premium is a system-defined percentage, and it can increase through the duration of the liquidation. -The premium is limited to the agent's combined collateral ratio, which is the sum of the current value of the vault collateral and pool collateral divided by the current value of the backed FAsset amount. -However, if this limit is reached, all the agent's backed FAssets are liquidated, and all the vault collateral and pool collateral are paid to the liquidators. -The liquidation-collateral payment is divided between the agent and the collateral pool. - -A fixed ratio (≥ 1.0) of the payment is paid from the agent's collateral, and the remainder is paid from the pool collateral. -If not enough of one type of collateral exists, more is paid from the other type. - -!!! info "Full Liquidations" - - Illegal payments trigger a full liquidation, which involves the following additional actions: - - * The liquidated agent's vault is locked so that it cannot be used to mint again. - If the agent wants to continue to mint FAssets, he must create a new agent vault with a new underlying address. - * Ongoing mintings against this agent's locked vault continue, but the minted FAssets are immediately added to the liquidation process. - * Ongoing redemptions continue. - New redemptions can start until all the agent's redemption tickets are liquidated. - Unfortunately, if the agent's underlying backing is unhealthy, redeemers are more likely to be paid in native tokens from the collateral pool. - - This liquidation process includes the time-increasing premium, and it only stops when all the agent's collateral is liquidated. - -## Stopping Liquidations - -After liquidation of an unhealthy position starts, it can be stopped by depositing enough collateral or self-closing FAssets to reach the [safety CR](./collateral.md#system-wide-thresholds). -Also, if a change in the price pushes the CR above the safety CR, anyone can stop the liquidation by notifying the FAssets system. - -To maintain a healthy account, agents should track positions and automatically top up or self-close FAssets when liquidation approaches. -Otherwise, the agent and the liquidators compete to try to stop the liquidation. -To stop a liquidation, the agent's vault must reach the [safety CR](./collateral.md#system-wide-thresholds), which is above the [minimal CR](./collateral.md#system-wide-thresholds) that triggered the liquidation. - -[The top-up mechanism](./collateral.md#top-up) can prevent liquidations caused by a low CR in the collateral pool, but full liquidations cannot be stopped. -However, an agent can still self-close positions to avoid paying a premium to liquidators. - -??? example "Example 1: Small Price Movement" - - Using `$BTC` as underlying and `$USDC` as collateral, an agent creates a vault to mint `$FBTC` FAssets. - - 1. Initial conditions: - - * The agent is backing 1 `$FBTC`, currently valued at $20K, according to the [FTSO system](../ftso/index.md). - * The minimal CR is **1.3** for the vault collateral and **2.5** for pool collateral. - * [The agent must hold 20% of the pool's minimal CR](./collateral.md#agents-stake-in-the-collateral-pool). - In this case, 20% of 2.5 times \$20K is **\$10K**. - * The underlying backing factor is 50%, so the agent needs to hold only **0.5** `$BTC`. - * The liquidation premium factor is 1.1, of which 1.0 is paid in vault collateral, and 0.1 is paid in pool collateral. - - At this point, the 1 `$FBTC` is backed by: - - * 0.5 `$BTC` underlying. - * $26K worth of `$USDC` vault collateral. - - The vault CR is $\$26K \over \$20K$ = 1.3, equal to the vault's minimal CR. - - * $60K worth of `$FLR` in pool collateral, of which $10K belongs to the agent. - - The pool CR is $\$60K \over \$20K$ = 3, above the pool's minimal CR. - - 2. Now the price of `$BTC` increases from $20K to $21K. - As a result: - - * The vault CR is $\$26K \over \$21K$ ≈ 1.24, **below the vault's 1.3 minimal CR**. - * The pool CR is $\$60K \over \$21K$ ≈ 2.86, still above the pool's 2.5 minimal CR. - - !!! warning "Liquidation Trigger" - Because one of the CRs is below the minimal CR, liquidation can start after a system-defined wait period. - - If any of the CRs go below the [Liquidation CR](./collateral.md#system-wide-thresholds), liquidations can start immediately. - - 3. A liquidator notices the CR levels and decides to liquidate $10K worth of FAssets by returning 0.48 `$FBTC` to the FAssets system. - - The liquidation premium factor is 1.1, so the liquidator receives $11K worth of assets: - - * $10K worth of `$USDC` from the agent's vault collateral. - * $1K worth of `$FLR` from the agent's portion of the collateral pool. - - The corresponding $1K worth of CPTs are burned, so their price is unaffected. - - At this point, the agent is backing 0.52 `$FBTC` with: - - * 0.5 `$BTC` underlying. - - The ratio is $0.5 \over 0.52$ ≈ 0.96, well above the 50% underlying backing factor. - - * $16K worth of `$USDC` vault collateral. - - The vault CR is $\$16K \over \$11K$ ≈ 1.45, now above the vault's minimal CR. - - * $59K worth of `$FLR` in pool collateral, of which $9K belong to the agent. - - The pool CR is $\$59K \over \$11K$ ≈ 5.36, still well above the pool's minimal CR. - - !!! question "Liquidation Finished?" - Both CRs are now above the minimal CR values, but liquidation does not stop until the CRs further increase up to the [safety CR](./collateral.md#system-wide-thresholds). - - In summary, as a result of the price increase and the liquidation, around 50% of the backed `$FBTC` was burned. - The actual amount of FAssets that need to be burned, though, depends on the safety CR setting. - -??? example "Example 2: Large Price Movement" - - The same setup and initial conditions as in Example 1 are used: - Using `$BTC` as underlying and `$USDC` as collateral, an agent creates a vault to mint `$FBTC` FAssets. - - 1. Initial conditions: - - * The agent is backing 1 `$FBTC`, currently valued at $20K, according to the [FTSO system](../ftso/index.md). - * The minimal CR is **1.3** for the vault collateral and **2.5** for pool collateral. - * [The agent must hold 20% of the pool's minimal CR](./collateral.md#agents-stake-in-the-collateral-pool). - In this case, 20% of 2.5 times \$20K is **\$10K**. - * The underlying backing factor is 50%, so the agent needs to hold only **0.5** `$BTC`. - * The liquidation premium factor is 1.1, of which 1.0 is paid in vault collateral, and 0.1 is paid in pool collateral. - - At this point, the 1 `$FBTC` is backed by: - - * 0.5 `$BTC` underlying. - * $26K worth of `$USDC` vault collateral. - - The vault CR is $\$26K \over \$20K$ = 1.3, equal to the vault's minimal CR. - - * $60K worth of `$FLR` in pool collateral, of which $10K belongs to the agent. - - The pool CR is $\$60K \over \$20K$ = 3, above the pool's minimal CR. - - 2. Now the price of `$BTC` increases from $20K to $30K. - As a result: - - * The vault CR is $\$26K \over \$30K$ ≈ 0.87, **way below the vault's 1.3 minimal CR**. - * The pool CR is $\$60K \over \$30K$ = 2, **below the vault's 2.5 minimal CR**. - - To comply with the vault's 1.3 minimal CR, the agent needs 1.3 * $30K = $39K of `$USDC` vault collateral, which he does not have. - - !!! warning "Full Liquidation" - - At this point, all the agent's FAssets backed by this vault must be liquidated. - - 3. A liquidator notices this situation and decides to liquidate 1 `$FBTC`, currently worth $30K. - - The liquidation premium factor is 1.1, so the liquidator receives $33K worth of assets: - - * $26K worth of `$USDC`, which is all of the collateral in the agent's vault. - * $7K worth of `$FLR`. - - Note that the portion of payment in `$FLR` is higher than in Example 1 because enough `$USDC` in collateral did not exist. - - At this point, the agent is backing 0 `$FBTC`, and the remaining collateral is: - - * 0.5 `$BTC` underlying. - * $0 worth of `$USDC` in vault collateral. - * $53K worth of `$FLR` in pool collateral, of which $3K belongs to the agent. - - All this collateral can be freely withdrawn by its owners. - Because this collateral is not backing any FAssets anymore, no part of it is [locked](./collateral.md#transferable-and-locked-cpt). - -??? example "Example 3: Very Large Price Movement" - - A price increment such that the vault plus the pool collateral is not enough to back the minted FAssets results in a combined CR lower than 1. - By design, liquidation payments will never exceed the combined CR times the liquidated amount, so, in this case, liquidation is not a profitable operation. - - Moreover, the collateral locked in the FAssets system might not be a strong enough deterrent for agents that want to dispose of the higher-valued underlying in [an illegal way](#illegal-payments). - -## Liquidation Triggers - -Some events related to liquidation are not detected automatically and must be triggered by entities external to the blockchain. -These entities are [liquidators](./index.md#liquidators) and [challengers](./index.md#challengers). - -Anyone can be a liquidator or a challenger and earn rewards for contributing to the correct working of the FAssets system. - -Some triggers put an agent in liquidation mode, and some others get agents out of liquidation mode. - -### Liquidation-Enabling Triggers - -* A valid liquidation request is submitted, triggering the liquidation automatically. -* A liquidator triggers a liquidation manually, but does not submit a liquidation request immediately, seeking a better premium, because the premium might increase as time passes. -* A liquidator detects that the CR is below the [CCB](./collateral.md#system-wide-thresholds) and sets the start time for an agent. - This operation does not immediately trigger the liquidation. - Instead, it starts a timer that enables the liquidation to be triggered after a system-defined time has elapsed. -* A [proof of illegal activity](#illegal-payments) is presented, which immediately triggers a full liquidation. - -### Liquidation-Disabling Triggers - -After an agent enters the liquidation state, it remains there until its CR exceeds the [safety CR](./collateral.md#system-wide-thresholds) again. - -The following operations can increase an agent's CR and can, therefore, potentially get the agent out of the liquidation state: - -* Redemptions. -* A liquidation improves the agent's position. -* The agent deposits more collateral. -* The agent self-closes a position. -* After the price has moved so that the agent's position is healthy again, the agent, or someone on the agent's behalf, manually sets the liquidation state to false. - -Exiting the liquidation state as soon as possible is in the agent's best interest, even if the agent might re-enter it again soon. -Premiums paid to liquidators might depend on how long the agent has been in liquidation, for example. -Also, exiting the liquidation state resets the CCB timer. - -## Tracking the Underlying Balance - -Agents are required to keep a certain percentage of underlying asset for each backed FAsset. -This percentage, called the [backing factor](./index.md#agents), is stored at an address on the underlying chain controlled by the agent. - -This requirement is enforced by balance-tracking in the FAsset contract. -To track balances, the system must receive reports for each payment sent and received at the agent's address: - -* Incoming payments are part of the [minting process](./minting.md) and are updated as the process occurs. -* Outgoing payments are either part of the [redemption process](./redemption.md) or illegal payments, which are penalized. - -[Challengers](./index.md#challengers) maintain the health of the FAssets system by monitoring the agent's underlying address to identify illegal operations that can make the agent's underlying backing too low. -Challengers that correctly report illegal operations receive rewards from the agent's vault collateral. - -The following subsections contain details about all the topics that must be considered when monitoring an agent's underlying balance. - -### Chain Fees - -Fees for gas on the underlying chain can create issues for the FAssets system, so part of tracking an agent's underlying balance involves tracking the amount spent on fees on the underlying chain. - -Expensive gas fees can cause an address to have fewer assets than it should have and trigger a liquidation. -Therefore, consider these actions: - -* **Cap the gas usage on underlying chains**: On smart-contract chains, the Flare Data Connector defines a cap on the gas amount to enable any simple transaction to pass. - If senders limit their gas amount to this cap and a transaction still fails due to insufficient gas, the failure is considered the receiver's fault, and the transaction is labeled as blocked. - - The gas cap is defined by the Flare Data Connector, not the FAssets system, because it is the Flare Data Connector that labels transactions as blocked. - -* **Maintain the underlying balance**: Agents must ensure that the payment plus the transaction fee for a redemption never reduce their balance to an amount lower than the amount required to back the FAssets. - Agents can ensure that redemptions do not reduce that balance in several ways: - - * They can honor redemptions from some other address. - On UTXO chains, they can also honor redemptions from a combination of addresses. - * They can top up the underlying address and then send proof of payment to update the tracked balance. - After a redemption begins, the agent has a limited time to comply, so topping-up is time-sensitive. - -### Underlying Withdrawals - -Agents might legally withdraw part of the funds on their underlying address in several ways: - -* **Minting fees**: A part of a minter's payment is the [mint fee](./minting.md#fees) in the underlying asset. -* **Failed redemptions**: When an address is backing assets and those assets were redeemed, but the agent [does not pay the redeemer](./redemption.md#redemption-payment-failure), the redeemer is paid with collateral, and the agent can withdraw the assets. -* **Liquidated assets**: If an agent's position was partially or fully liquidated, the agent can withdraw the assets. -* **Self-closed assets**: After an agent [self-closes](./minting.md#self-minting), the closed assets can be withdrawn. - -The FAssets system must keep track of the agent's underlying funds, so when performing the above legal withdrawals, agents must still adhere to the following process: - -1. Announce the withdrawal to the FAssets system and obtain a payment reference. -2. Perform the withdrawal, using the payment reference. -3. Use the [Flare Data Connector](../data-connector.md) to obtain a proof of payment. -4. Present the proof of payment to the FAssets system, which clears the announcement. - - If the agent does not present the proof of payment, anyone can present it after a while and receive a reward from the agent's vault. - Enabling nonagents to present this proof helps the FAssets system keep track of underlying balances. - -Only one withdrawal announcement can be active per agent at any time to prevent the agent from overwhelming the balance-tracking system with many simultaneous small withdrawals. - -### Illegal Payments - -Any challenger can report illegal payments from an underlying address and receive rewards in return. - -An illegal payment always triggers a full liquidation, which cannot be stopped. -An agent can still escape paying the liquidation premium by self-closing before liquidators submit their liquidation requests, but the agent's vault remains unusable and must be closed. -To resume operations, the agent must open a new vault with a different underlying address. - -The challenge system ensures that all minted FAssets are always backed by the assets on the agent's underlying address in the required percentage. -Malicious agents might try to remove those assets in different ways. -Therefore, challengers can report illegal activities by using these different _challenges_: - -#### Illegal Payment Challenge - -A payment from the agent's underlying address without a payment reference or with a payment reference that does not correspond to any open [redemption](./redemption.md) or [announced withdrawal](#underlying-withdrawals). - -This challenge is performed in the following way: - -1. The challenger obtains proof of the illegal payment using the Flare Data Connector. -2. The challenger presents the proof to the FAssets system, which triggers: - - * A vault collateral payment from the agent's vault to the challenger's address as a reward. - * The agent's state for the address is set to [full liquidation](#liquidation-process). - -#### Double Payment Challenge - -An agent might try to abuse a redemption request to pay to the redeemer and use the same payment reference to pay an amount to the agent's own address. -An agent might even try to pay the redeemer multiple times when he is redeeming against himself. - -This activity is easy to detect after the first payment is reported in [step 6 of the redemption process](./redemption.md#redemption-process), because then the request is deleted and the second payment becomes illegal. -However, a malicious agent might try to issue the second payment before reporting the completion of the first one. - -The double payment challenge catches this attempt as soon as the payments are finalized, regardless of whether they have been reported to the FAssets system. - -This challenge is performed in the following way: - -1. The challenger detects two seemingly legal payments from the same agent's underlying address and with equal payment reference, and obtains proofs for both using the Flare Data Connector. -2. The challenger presents the two proofs to the FAssets system and triggers the reward payment and full liquidation. - -#### Negative Balance Challenge - -One or more legal payments can make the balance on the agent's underlying address too small or equivalently make the free underlying balance negative. -This situation can happen because gas fees might be unknown when redemptions are approved. - -This situation would normally be detected after all payments are reported, but in this way it can be caught as soon as the payments are finalized on the underlying chain: - -1. The challenger detects one or more legal payments from the same agent's underlying address and the total outgoing amount exceeds the sum of all redemption values plus the total free balance. - The challenger obtains proofs for all of them using the State Connector. -2. The challenger presents all the proofs to the FAssets system, which checks that the transactions are from the agent's underlying address, that they have not been confirmed yet, and that their total really makes the free balance negative. - Then, it triggers reward payment and full liquidation. - -### Time Lock for Withdrawing Collateral - -The agent's collateral backs minted FAssets but also pays challenge fees and possibly illegal payment penalties. -Because finalization on some underlying chains takes a long time, challenges can sometimes be proved to be valid only after an agent's position is already closed and enough collateral to pay them is not available. - -For this reason, collateral withdrawals are locked for a certain amount of time before they become effective. -The amount of time varies depending on the underlying chain and the time frame required for achieving finality on that chain. - -For agents, any collateral withdrawals must be announced, and then the amount is locked for some time before it can be withdrawn. -The locked collateral is also ineligible for minting. - -Agents must announce the closing of their vaults. -They become unusable until the lock expires, and then they can be closed. diff --git a/docs/tech/fassets/minting.md b/docs/tech/fassets/minting.md deleted file mode 100644 index 9dc1f68de..000000000 --- a/docs/tech/fassets/minting.md +++ /dev/null @@ -1,258 +0,0 @@ ---- -title: Minting -search: - boost: 2 ---- - -# FAssets Minting - -Minting [FAssets](./index.md) is the process of wrapping underlying tokens from connected blockchains into FAssets to be used on the Flare blockchain. -Any [user](./index.md#users) can mint FAssets. - -## Minting Process - -This is the summary of the minting process: - -
- ![Minting process](fassets-minting.png){ loading=lazy .allow-zoom } -
Minting process.
-
- -1. The minter chooses an agent from the publicly available [agent list](./index.md#agents). - The choice is based on the minting fee or the amount of free collateral, which must be enough to back the amount to be minted. -2. The minter sends to the Asset Manager contract a collateral reservation transaction (CRT). The CRT includes: - - * The address of the chosen agent - * The amount to mint, which must be a whole number of [lots](#lots) - * The [collateral reservation fee (CRF)](#fees) to compensate for the locked collateral - -3. The Asset Manager contract locks the agent's collateral in the amount needed to back the whole minting until the underlying payment is proved or disproved. - The collateral reservation response is an event issued by the contract, which includes: - - * The agent's address to which the minter must send funds on the underlying chain. - * The amount to be paid on the underlying chain, which corresponds to the amount to be minted plus the agent's fee. - * The payment reference, which is a unique 32-byte number the minter must include as a memo in the payment on the underlying chain. - * The last underlying block and the last underlying timestamp to pay. - Valid payments occur either before the last block or before the last timestamp, both inclusive. - - The time to pay is measured both in the underlying chain's block numbers and block times because the underlying chain might halt for a long time. - In this situation, the block numbers do not increment but the block timestamps do. - -4. After this event is emitted, the minter must pay the full underlying amount plus the fee to the agent on the underlying chain in a certain amount of time. -5. Using the Flare Data Connector, the minter proves the payment on Flare. -6. After the payment is proved, the minter executes the minting process, which sends FAssets to the minter's account. - -When minting is executed, the [minting fee](#fees) is split between the agent and the pool: - -* The percentage split is set by the agent. -* The agent's share increases the free balance on the agent's underlying address. - The free balance is the part of the balance in an agent's underlying address that the agent can withdraw. - It is composed of minting fees, redemption fees, and self-closed FAssets. -* The pool share gets minted as FAssets and credited to the collateral pool contract. - -After minting is complete, the Asset Manager creates a [redemption ticket](#redemption-tickets-and-the-redemption-queue), which includes the mint amount and the name of the agent backing the minting. - -## Fees - -The following fees are paid to mint FAssets: - -* The **collateral reservation fee (CRF)** is paid in native tokens by the minter at the same time the [CRT](#minting-process) is made. - The CRF is defined by governance as a percentage of the minted value, and the same fee applies to all agents. - { #crf } - - When the minter does not pay on the underlying chain, this fee compensates the agent and the CPT holders for the time their collateral was locked while the mint processed. - If the minter pays on the underlying chain, the CRF is [burned](glossary.md#burn). - - For underlying chains on which proving payments takes a long time, the fee might be higher than the fee on chains that quickly prove payments. - -* The **minting fee** is paid by the minter with the underlying currency as a percentage of the minted amount, and each agent can declare a different fee value. - This fee is the main source of revenue for the agent and the CPT holders. - { #minting-fee } - - The minting fee is further divided in two shares: - -
- ![Minting fees](fassets-fees.png){ loading=lazy .allow-zoom } -
Minting fees.
-
- - * **Agent's share**: This share remains in the agent's underlying account but is not marked as being in use. - 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. - -## Payment Failure - -To finalize the minting, the minter must pay the agent on the underlying chain and prove the payment was received. -If the payment is not completed in the time frame defined by the underlying chain block and timestamp, the agent must prove nonpayment to release the locked collateral. -After nonpayment is proved, the agent's collateral that was reserved by the [CRT](#minting-process) is released, and the agent receives the [CRF](#crf). - -The [agent's registration process](./index.md#agents) verifies that the agent's underlying address does not purposefully block payments and illegally collects the CRF. - -!!! example "Example: Proof of Nonpayment" - The following example shows how the nonpayment proof works. - - The [Flare Connector](../data-connector.md)'s [payment nonexistence attestation type](https://gitlab.com/flarenetwork/state-connector-protocol/-/blob/main/specs/attestations/active-types/ReferencedPaymentNonexistence.md?ref_type=heads) proves nonpayment. - - 1. The minter sends a request to mint `$FBTC`. - At the time the request is received, the last mined block on the Bitcoin chain is number 92, with timestamp 09:00 AM. - - The Asset Manager answers with the following threshold settings to complete the payment: - - * Block 100 - * Timestamp 11:00 AM - - 3. Block 101 is mined with timestamp 10:59 AM. - At this point, the payment can still happen. - 4. Block 102 is mined with timestamp 11:04 AM. - Payment did not occur. - After this block is finalized, nonpayment can be proved. - - 5. Block 109 is mined. - In this case, 7 blocks on the Bitcoin blockchain are enough blocks to assume finality. - 6. The agent sends a nonpayment attestation request, which includes the payment reference, the underlying amount that was expected, the last block (100), and the last timestamp (11:00). - 7. Attestation providers attest to the following facts: - - * Block 102 is finalized and has both the number and timestamp larger than required. - * Until this block, the required payment either was not made or was not sufficient. - - Now, the mint-payment failure and the nonpayment proof can be submitted to the FAssets system. - -## Edge Cases - -* **Unresponsive minter**: After a successful payment, the minter might not provide the payment proof needed to complete the minting process. - In this case, the agent can present the payment proof and execute minting at any time. - FAssets are still transferred to the minter's account, and the agent's collateral becomes redeemable. - -* **Expired proof**: Proofs provided by the Flare Data Connector are available for only 24 hours, approximately. - If neither the minter nor the agent presents the proof of payment or nonpayment within 24 hours, the regular minting process cannot continue, and the agent's collateral could be locked indefinitely. - - In this case, the agent can still recover the collateral by buying it back with native tokens. - The recovery is accomplished with the following procedure: - - 1. Request the proof from the time when the deposit should have happened. - The Data Connector's answer will indicate that payments proofs are no longer available for that time. - 2. Provide the amount of `$FLR` collateral equivalent to the price of the underlying assets that should have been deposited. - 3. Present the proof. - - Because a successful deposit cannot be proven, the FAssets system burns the amount of collateral in native tokens provided by the agent. - After the burn is complete, the rest of the agent's collateral is released, both from his vault and the collateral pool. - - !!! warning - Note that this procedure should be used only in rare cases because providing timely payment or nonpayment proofs is always more advantageous for agents. - -## Duration of the Minting Process - -The duration of the minting process depends mainly on the speed of the underlying chain. -The maximum duration of the process is the sum of: - -* A system-defined maximum time for deposit. - It is either a few blocks on the underlying chain or a few minutes, whichever is longer. -* The underlying chain's finalization time. -* The Data Connector proof time, which is approximately 3 - 5 minutes, independent of the underlying chain. - -On fast chains like XRPL, the maximum total time is less than 10 minutes, while on Bitcoin it is approximately 1.5 hours. -For payment failures, the agent needs to wait the maximum time, as defined above, before the nonpayment proof can be retrieved. - -## Minting Payment Reference - -The system generates a unique payment reference at the time of the collateral reservation request. -The minter must include the payment reference in a memo field when the underlying payment transaction is made. - -The payment reference ensures the payment transaction cannot be used by another entity that might claim to have made the payment on the underlying chain and receive the minted FAssets in return. -Additionally, if the payment time expires before payment is done, the agent can prove that no payment with that reference was made. - -A similar payment reference for the same purposes is generated for [redemptions](./redemption.md). - -## Redemption Tickets and the Redemption Queue - -For every minting operation, a redemption ticket is created. -This ticket references the minted amount and the agent that is backing the minting. - -The redemption tickets are ordered in a queue that determines the next agent to be [redeemed](./redemption.md) against according to the first in, first out method (FIFO). -In other words, the first redemption ticket created will be the first redemption ticket processed. -The FIFO queue impartially ensures that all agents have the opportunity to fulfill the duties of their role. - -!!! example "Example: Redemption Queue" - The following example shows how the redemption queue works. - - 1. Bob mints 10 `$FXRP` with Agent 1. - 2. Alice mints 20 `$FXRP` with Agent 2. - 3. Charlie mints 5 `$FXRP` with Agent 1. - - After Bob, Alice, and Charlie have minted their FAssets, the redemption queue according to the FIFO method is: - - 1. Agent 1 with 10 `$FXRP`. - 2. Agent 2 with 20 `$FXRP`. - 3. Agent 1 with 5 `$FXRP`. - - 4. Dana redeems 25 `$FXRP`. - To redeem 25 `$FXRP`: - - 1. Agent 1 pays 10 `$FXRP`. - 2. Agent 2 pays 15 `$FXPR`. - - Now, the redemption queue according to the FIFO method is: - - 1. Agent 2 with 5 `$FXRP`. - 2. Agent 1 with 5 `$FXRP`. - -## Lots - -Every minting and redemption must be made in a whole number of lots. -Lots serve the following purposes: - -* They prevent underlying transaction fees from exceeding minting or redemption fees. -* They restrict large numbers of very small redemption tickets from being submitted, which would increase gas costs. - -Therefore, the amount of tokens in a lot (the _lot size_) varies for each underlying chain. -For example, on the XRPL chain, a lot can be as small as 10 `$XRP` because transaction fees are low. -On the other hand, on the Bitcoin chain, lots might need to be as big as 0.25 `$BTC` or more because transactions are far more expensive. - -Over time, the lot size can be updated to reflect price fluctuations of the underlying asset. -Only a governance call can update the lot size, and it can be updated only by a limited amount per day. - -!!! note "Dust" - - Some processes generate a fractional number of lots: - - * On minting, part of the minting fee is minted as the FAsset fee to the collateral pool. - This value is usually less than 1 lot. - * When the lot size is changed, redemptions close only a whole number of lots of each redemption ticket, which leaves the remainder unredeemed. - - These amounts, known as dust, cannot be redeemed directly because redemption requires a whole number of lots. - - In such cases, the generated dust is not included in any redemption ticket. - Instead, each agent's dust is accumulated until the dust amounts to a whole lot. - When that happens, another redemption ticket is automatically created. - - Therefore, the dust can be recovered or destroyed in the following ways: - - * If the dust exceeds 1 lot during minting, the part that is a whole multiple of a lot is automatically added to the created redemption ticket. - * If an agent does not mint any FAssets for a while but the lot size changes and several redemptions occur, enough dust might accumulate to more than 1 lot. - - In this case, the part that is a whole multiple of a lot can be converted to a redemption ticket by request. - To prevent an inactive agent making FAssets less fungible, this request can be made by any address. - - * [Self-closing](./redemption.md#self-closing) can work with fractional lots, so it can be used to remove dust. - * [Liquidation](./liquidation.md) can work with fractional lots too, so it can also be used to remove dust. - -## Self-Minting - -Agents can also act as minters and mint FAssets from their own vaults. -This process is called self-minting and is simpler than regular minting because neither the [CRT](#minting-process) nor the agent's fee are necessary. - -When an agent self-mints FAssets: - -* The agent still needs to pay the amount to mint on the underlying chain and execute the minting. -* The self-minting operation also adds a [ticket to the redemption queue](#redemption-tickets-and-the-redemption-queue), alongside tickets added by mints done by other users. - All tickets are processed by the FIFO queue. -* Only the [pool's share of the fee](#fees) must be paid. - -Because self-minting is done without a collateral reservation request, in some cases, a change between the underlying deposit and the execution, such as another collateral reservation, price change which reduces the amount of free [lots](#lots), or lot-size change, might prohibit the intended number of lots to be minted. -If one of these changes occurs, the agent can self-mint a smaller number of lots, even 0 lots, and the remainder of the deposited underlying assets is added to the free underlying balance. - -Additionally, when agents create a vault, they can choose not to make it public, so the vault can only be used to self-mint. diff --git a/docs/tech/fassets/open-beta.md b/docs/tech/fassets/open-beta.md deleted file mode 100644 index e62c88257..000000000 --- a/docs/tech/fassets/open-beta.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -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: - -* Test the FAssets system in a live environment. -* Gather feedback from users to improve the FAssets functionality and documentation. -* Continue the education of the various roles supporting FAssets, such as [agents](../../tech/fassets/index.md#agents), [liquidators](../../tech/fassets/index.md#liquidators), and [challengers](../../tech/fassets/index.md#challengers), so that they can get practical experience and prepare themselves for the general launch of the FAssets system. -* Identify and resolve any remaining inconsistencies to ensure the system is as robust as possible before adding real user funds. - -## FAssets Open Beta Phases - -This open-beta period consists of two phases: - -* **Phase One**: In this phase, agents will be onboarded. -Although other advanced users can join, they can interact with the FAssets system only via the command-line interface. -* **Phase Two**: In this phase, a graphical user interface will be released for everyone to use instead of the command line. - -!!! info "Open Beta" - - To participate, please begin by joining the [Telegram channel](https://t.me/FlareSupport) or contact [support@flarelabs.org](mailto:support@flarelabs.org). - Thank you for supporting the development of FAssets. - - --8<-- "./include/fassets/issue-collector.html" - -Following the Coston open beta, the next stage will launch on Songbird. - -## Related Pages - -* [Minting and Redeeming FAssets](../../user/fassets/index.md) -* [Deploying FAssets Agent](../../infra/fassets/deploying-agent.md) -* [Setting up an FAssets Liquidator](../../infra/fassets/liquidator.md) diff --git a/docs/tech/fassets/parameters.md b/docs/tech/fassets/parameters.md deleted file mode 100644 index 4e628d0da..000000000 --- a/docs/tech/fassets/parameters.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -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." - -## Open Beta (Coston) Parameter Values - -### Minting and Redeeming - -| Parameter | XRP | BTC | DOGE | | -|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------|----------------|----------------|----------------| -| **Minting cap**
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 | none | none | | -| [**Lot size**](./minting.md#lots) | 20 XRP | 0.0004 BTC | 100 DOGE | | -| [**Collateral reservation fee (CRF)**](./minting.md#crf) | 0.1% | 0.1% | 0.1% | | -| [**Redemption fee**](./redemption.md#redemption-fee) | 0.1% | 0.1% | 0.1% | | -| [**Redemption default premium**](./redemption.md#redemption-payment-failure) | 10% | 10% | 10% | | -| **Redemption default premium source**
Where does the premium come from when an agent fails to pay the redeemer on time?
If the [vault CR](./collateral.md#the-collateral-ratio) > 1.1, from the agent's vault. Otherwise, from the agent's vault and the collateral pool. | From the vault | From the vault | From the vault | - -### Minting and Redeeming Payment Times - -| Parameter | XRP | BTC | DOGE | -|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|------------|------------| -| **Underlying blocks for payment**
The number of underlying blocks during which the minter or agent can pay the underlying value. | 500 | 10 | 50 | -| **Underlying seconds for payment**
The minimum time allowed for an agent to pay for a redemption or a minter to pay for minting. | 15 minutes | 2 hours | 50 minutes | -| **Average block time**
The average time between two successive blocks on the underlying chain. | 2 seconds | 10 minutes | 1 minute | -| **Time of proof availability**
The amount of time that proofs of payment or nonpayment must be available on the Data Connector. | 1 day | 1 day | 1 day | -| **Amount of extra time per redemption**
The extra amount of time per redemption granted to an agent when many redemption requests occur in a short period of time. | 30 seconds | 60 seconds | 60 seconds | - -### Collateral Ratios - -| Parameter | XRP | BTC | DOGE | -|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------|-------------------------------------|-------------------------------------| -| [**Backing factor**](./index.md#backing-factor) | 100% | 95% | 100% | -| [**Vault collateral**](./collateral.md#vault-collateral) | | | | -|  •  **Supported types** | `$USDC`, `$USDT`, simulated `$WETH` | `$USDC`, `$USDT`, simulated `$WETH` | `$USDC`, `$USDT`, simulated `$WETH` | -|  •  [**Minimal CR**](./collateral.md#minimal-cr) | 1.4 | 1.4 | 1.4 | -|  •  [**Collateral call band CR**](./collateral.md#collateral-call-band-cr) | 1.3 | 1.3 | 1.3 | -|  •  [**Safety CR**](./collateral.md#safety-cr) | 1.5 | 1.5 | 1.5 | -| [**Pool collateral**](./collateral.md#pool-collateral) | | | | -|  •  **Supported types** | `$CFLR` | `$CFLR` | `$CFLR` | -|  •  [**Minimal CR**](./collateral.md#minimal-cr) | 2.0 | 2.0 | 2.0 | -|  •  [**Collateral call band CR**](./collateral.md#collateral-call-band-cr) | 1.9 | 1.9 | 1.9 | -|  •  [**Safety CR**](./collateral.md#safety-cr) | 2.1 | 2.1 | 2.1 | -| **Minting pool holdings required**
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% | 50% | 50% | - -### Liquidation - -| Parameter | XRP | BTC | DOGE | -|---------------------------------------------------------------------------------------------------------|------------------------------------------|------------------------------------------|------------------------------------------| -| [**CCB time**][ccb-time]
Maximum time an agent can remain in CCB before liquidation starts. | 180 seconds | 180 seconds | 180 seconds | -| [**Liquidation premium**](./liquidation.md#liquidation-process)
Increases in steps, as time passes. | Step 1: 5%
Step 2: 10%
Step 3: 15% | Step 1: 5%
Step 2: 10%
Step 3: 15% | Step 1: 5%
Step 2: 10%
Step 3: 15% | -| **Liquidation step time**
Elapsed time before the liquidation premium advances to the next step. | 180 seconds | 180 seconds | 180 seconds | -| **Liquidation source**
Where do the funds come from to pay for liquidations. | | | | -|  •  Liquidated value | The agent's vault | The agent's vault | The agent's vault | -|  •  Premium | The collateral pool | The collateral pool | 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/deploying-agent.md#setting-up-the-agent). -Agents are free to adjust these settings as they see fit. - -| Parameter | XRP | BTC | DOGE | -|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------|-------|-------| -| [**Minting fee**](./minting.md#minting-fee) | 0.25% | 0.25% | 0.25% | -| [**Pool share**](./minting.md#pool-share) | 40% | 40% | 40% | -| [**Minting CR**](./collateral.md#minting-cr) | | | | -|  •  **Agent vault** | 1.6 | 1.6 | 1.6 | -|  •  **Collateral pool** | 2.3 | 2.3 | 2.3 | -| [**Exit CR**](./collateral.md#exit-cr) | 2.3 | 2.3 | 2.3 | -| [**Top-up CR**](./collateral.md#top-up-cr) | 2.1 | 2.1 | 2.1 | -|  •  **Top-up discount** | 10% | 10% | 10% | -| [**Discount for agent self-close**](./liquidation.md#stopping-liquidations)
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% | 1% | 1% | - -### Rewarding - -| Parameter | XRP | BTC | DOGE | -|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------|------------------------------------------|------------------------------------------| -| [**Challenger reward**](./index.md#challengers)
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 | 300 `$USD` converted to vault collateral | 300 `$USD` converted to vault collateral | -| [**Confirmation by others**](./redemption.md#edge-cases)
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. | | | | -|  •  **Minimum time** | 2 hours | 4 hours | 4 hours | -|  •  **Reward** | 100 `$USD` converted to vault collateral | 100 `$USD` converted to vault collateral | 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 | XRP | BTC | DOGE | -|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|-------------|-------------| -| **Agent withdrawal time lock**
Agent has to announce any collateral withdrawal or vault destruction and then wait this time before executing it. | 60 seconds | 60 seconds | 60 seconds | -| **Maximum governance update frequency**
Minimum amount of time between updates of any governance setting. | 60 seconds | 60 seconds | 60 seconds | -| **Token invalidation time**
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 | 1 day | 1 day | -| **Agent exit available time lock**
The time the agent has to wait after announcing exit from the list of publicly available agents and executing the exit. | 60 seconds | 60 seconds | 60 seconds | -| **Agent fee change time lock**
The time the agent has to wait between announcing and changing the agent fee or the pool share. | 120 seconds | 120 seconds | 120 seconds | -| **Agent minting CR change time lock**
The time the agent has to wait between announcing and changing the minting CR (vault or pool). | 120 seconds | 120 seconds | 120 seconds | -| **Pool exit and top-up change time lock**
The time the agent has to wait between announcing and changing any pool exit and top-up settings. | 120 seconds | 120 seconds | 120 seconds | -| **Agent time-locked operation window**
Once the above time locks expire, agents have this amount of time to execute the requested operation. | 1 hour | 1 hour | 1 hour | -| **Collateral pool token time lock**
Amount of seconds that a user entering the collateral pool must wait before spending (exit or transfer) the obtained pool tokens. | 60 seconds | 60 seconds | 60 seconds | -| **Minimum diamond-cut time lock**
Amount of time that must elapse before the system performs a [diamond cut](https://eips.ethereum.org/EIPS/eip-2535). | 2 hours | 2 hours | 2 hours | - -### Emergency Pause - -| Parameter | XRP | BTC | DOGE | -|---------------------------------------------------------------------------------------------------------------------------------------------------------|--------|--------|--------| -| **Emergency pause**
The maximum time for a pause triggered by governance or some other entity. | 1 day | 1 day | 1 day | -| **Emergency pause reset**
The amount of time since the last emergency pause. After it has elapsed, the pause duration counter automatically resets. | 1 week | 1 week | 1 week | - -### FAssets Upgrade - -| Parameter | XRP | BTC | DOGE | -|--------------------------------------------------------------------------------------------------------------------------|------|------|------| -| **Buyback collateral premium**
The premium at which agents can buy back their collateral when f-asset is terminated. | 0.3% | 0.3% | 0.3% | -| **Burn collateral premium**
The premium at which agents can burn collateral to unstick a minting process. | 0% | 0% | 0% | - - diff --git a/docs/tech/fassets/redemption.md b/docs/tech/fassets/redemption.md deleted file mode 100644 index a1f4f039e..000000000 --- a/docs/tech/fassets/redemption.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: Redemption -search: - boost: 2 ---- - -# FAssets Redemption - -Any holder of [FAssets](./index.md) can redeem their FAssets for the underlying original asset. -To do so, these holders, known as redeemers, send FAssets to the Asset Manager smart contract, and the redeemed amount is paid with the underlying asset from an agent's address. - -## Redemption Process - -This is the summary of the redemption process: - -
- ![Minting](fassets-redeeming.png){ loading=lazy .allow-zoom } -
Minting.
-
- -1. The redeemer starts the redemption for a whole number of [lots](./minting.md#lots) by issuing a request to the Asset Manager smart contract. - - The FAssets system chooses one or more redemption tickets from the front of the [FIFO redemption queue](./minting.md#redemption-tickets-and-the-redemption-queue). - The number of chosen redemption tickets is capped to avoid high gas consumption. - If the redemption amount requires too many tickets, only a partial redemption is done. - -2. The system [burns](glossary.md#burn) FAssets from the redeemer’s account in the amount of the total of the selected redemption tickets. - If the redeemer's account does not contain enough FAssets, the redemption fails immediately. - -3. Each chosen ticket belongs to an agent. - For every agent participating in the redemption, the system issues an event with the following redemption payment information: - - * Redeemer’s underlying address. - - Agents can use the Flare Data Connector to ensure the validity of this address. - Otherwise, malicious redeemers could provide an address that systematically blocks payments and exploit the redeeming process to their advantage (See [Redemption Payment Failure](#redemption-payment-failure) below). - - * Amount to pay minus the fee that was already subtracted. - * [A payment reference](./minting.md#minting-payment-reference). - This payment reference is different for each agent and each redemption. - * The last underlying block and the last underlying timestamp to complete the payment. - -4. Every agent pays the redeemer on the underlying chain and includes the payment reference in the memo field of the payment transaction. - - Agents can pay the redemption from any address they control on the underlying chain. - It does not need to be the same address where they receive minting payments. - -5. After the payment is finalized, the agent uses the [Flare Data Connector](../data-connector.md) to prove the payment and obtain a payment proof. - -6. After the payment proof is presented to the FAssets system, the agent's vault collateral and pool collateral that were backing those FAssets are released. - - After the collateral is released, it can either back the minting of more FAssets or be withdrawn. - -## Redemption-Payment Failure - -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 _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. -In this way, the gas costs of the failed transaction can be accounted for by the FAssets system. -If the transaction was not recorded, then no gas was spent and reporting is not necessary. - -If the agent does not report the failed payment in time, anyone can report the failed payment and receive a reward from the agent's vault. - -!!! note "Blocked Payments" - - When payment fails because of the redeemer, the agent can obtain a proof of the failed payment from the Flare Data Connector and present it to the FAssets system. - The agent's obligation is then fulfilled, and he can keep both the collateral and the underlying. - - Two different proofs can be used: - - * Proof of invalid address, due to a wrong syntax or checksum, for example. - * Proof of blocked payment: Even if the address is valid, it might contain a contract that blocks the payment. - This can only happen on underlying networks supporting smart contracts. - - The agent must still try to pay and, if the payment is blocked, the agent can request this proof from the Flare Data Connector and present it to the FAssets system. - -During step 4 above, if any agent does not to pay on the underlying chain, the redeemer completes the following procedure separately for each nonpaying agent: - -1. The redeemer obtains a proof of nonpayment from the Flare Data Connector. -2. The redeemer presents the nonpayment proofs to the FAssets system, which triggers a redemption failure. -3. The redeemer is paid with collateral, according to the current price plus a premium. -4. FAssets are overcollateralized, so, even after paying the redeemer with a premium, a remainder is released. - This remainder is derived by the [system-wide collateral ratio settings](./collateral.md#system-wide-thresholds) specified by governance. -5. The underlying assets backing the redeemed FAssets are marked as free and can be withdrawn by the agent later. - -## Edge Cases - -* **Unresponsive redeemer**: After a redemption nonpayment, the redeemer might not report the failure for some reason. - In this case, the agent can present a nonpayment proof, and the redeemer receives collateral plus a premium. - After this operation, the underlying backing collateral and the remaining local collateral are released. -* **Unresponsive agent**: After a successful payment, the agent might not present the payment proof. - Because the agent has already paid, the redeemer is not affected. - However, the system still requires the payment proof to correctly track the agent's balance on the underlying chain. - After enough time for the agent to present the proof has elapsed, anyone can present the payment proof and receive collateral from the agent’s vault. -* **Expired proof**: Proofs provided by the Flare Data Connector are available for only 24 hours, approximately. - If neither the redeemer nor the agent presents the proof of payment or nonpayment within 24 hours, the regular redeeming process cannot continue, and the agent's collateral could be locked indefinitely. - - The procedure to recover this collateral is the same as the [procedure in the minting case](./minting.md#edge-cases). - -## Redemption Fee - -The redemption fee is the amount of the underlying asset that the agent can keep for doing the redemption. -This fee is meant only to cover the agent’s transaction fee on the underlying chain, so it is not shared with the collateral pool. -The fee percentage is defined by governance, is the same for all agents, and is typically smaller than the minting fee. - -Governance calculates the percentage so that the fee to redeem 1 lot pays for a typical transaction fee on the underlying chain. -Therefore, when larger amounts on a single address are redeemed, the agent accrues some extra fees because the underlying fee for small and large transactions is the same. -However, when underlying fees are very high, the agent might still lose funds when a redemption for a small amount, such as 1 lot, is made. -If this situation occurs frequently, governance will increase the redemption-fee percentage. - -## Self-redemption - -Agents can also act as users and redeem FAssets from their own vaults. -This process is called self-redemption or self-closing, and it is simplified because payment on the underlying chain is not required. - -As shown in the following process, agents can self-redeem for any reason, including to stop liquidations because it reduces the amount of FAssets the agent is backing. - -1. An agent sends FAssets to their account. -2. FAssets are burned. -3. The collateral that was backing those assets is released. -4. The underlying collateral is released and can be withdrawn from the underlying address later. - -The self-redeemed amount is not limited to a whole number of lots and can be less than 1 lot, which makes self-closing ideal for redeeming an agent's dust. diff --git a/docs/tech/flare.md b/docs/tech/flare.md index 191623d9b..35f1fa1af 100644 --- a/docs/tech/flare.md +++ b/docs/tech/flare.md @@ -23,7 +23,7 @@ Flare has the following native data acquisition protocols at these stages of dev * The **[Flare Time-Series Oracle (FTSO)](./ftso/index.md)** provides continuous estimations of changing data, such as [price pairs](glossary.md#price_pair). * The **[Flare Data Connector](./data-connector.md)** allows querying of verifiable, non-changing data from other chains and the internet. -* The **[FAssets](./fassets/index.md)** system is being developed by Flare Labs. It allows tokens on blockchains that do not support smart contracts to be used trustlessly with smart contracts on the Flare blockchain. +* The **[FAssets](https://dev.flare.network/fassets/overview)** system is being developed by Flare Labs. It allows tokens on blockchains that do not support smart contracts to be used trustlessly with smart contracts on the Flare blockchain. ## Developing on Flare diff --git a/docs/tech/glossary.md b/docs/tech/glossary.md index 1c3415355..ef910a30c 100644 --- a/docs/tech/glossary.md +++ b/docs/tech/glossary.md @@ -90,7 +90,7 @@ Executor { #executor } : Users who do not want to claim rewards themselves can set an executor to claim rewards for them and send them directly to their users' accounts. [Read more...](./automatic-claiming.md) FAssets { #fassets } -: Allows tokens on blockchains that do not support smart contracts to be used [trustlessly](#trustless) with [smart contracts](#smart_contract) on the Flare blockchain. [Read more...](./fassets/index.md) +: Allows tokens on blockchains that do not support smart contracts to be used [trustlessly](#trustless) with [smart contracts](#smart_contract) on the Flare blockchain. [Read more...](https://dev.flare.network/fassets/overview) Faucet { #faucet } : A [dapp](#dapp) that distributes test tokens to anyone that requests them. Used only on [test networks](#test_network), obviously. See the [Network Configuration](https://dev.flare.network/network/overview) page to learn about Flare's faucets. diff --git a/docs/tech/index.md b/docs/tech/index.md index c9a6d2dd7..29841b64f 100644 --- a/docs/tech/index.md +++ b/docs/tech/index.md @@ -11,7 +11,7 @@ Select one of the topics below: * [What Is Flare?](./flare.md) * [Automatic Claiming](./automatic-claiming.md) -* [FAssets](./fassets/index.md) +* [FAssets](https://dev.flare.network/fassets/overview) * [Flare API Portal](./api-portal.md) * [Flare Beta](./flare-beta.md) * [Flare Systems Protocol](./flare-systems-protocol.md) diff --git a/docs/user/fassets/depositing-collateral-cli.md b/docs/user/fassets/depositing-collateral-cli.md deleted file mode 100644 index dc9b2a7e7..000000000 --- a/docs/user/fassets/depositing-collateral-cli.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Depositing Collateral (CLI) ---- - -# Using the Command Line to Deposit Collateral - -As a user of the [FAssets](../../tech//fassets/index.md) system, you can deposit collateral into an agent's [collateral pool](../../tech/fassets/collateral.md#pool-collateral) to provide additional financial backing for the agent. -In exchange for your collateral, you will earn shares of the agent's fees. -Additionally, you will receive [collateral pool tokens](../../tech/fassets/collateral.md#pool-collateral), which you will be able to redeem, transfer, or trade. - -While the functionality to deposit collateral via a dapp is being developed, this guide is for users who have some experience using a terminal. -It provides the following information: - -* How to set up the FAssets command-line tool -* How to get a list of available agents -* How to deposit collateral into a selected agent's collateral pool - ---8<-- "./include/fassets/open-beta.md" - ---8<-- "./include/fassets/prerequisites-user.md" ---8<-- "./include/fassets/setup-commandline.md" - -### Configure User's Access Keys - -The FAsset user operates with multiple keys for the Flare and underlying network chains. - -1. Generate the user's secrets using this command: - - ```console - yarn key-gen generateSecrets --user -o secrets.json - ``` - - --8<-- "./include/fassets/generate-keys-info.md" - -2. Fund the user's FLR wallet with some CFLR to pay the gas fees. - You can find the user wallet's address in the `secrets.json` file under the `user.native.address` key. - You can get the CFLR tokens from the [Flare faucet](https://faucet.flare.network/). - -3. Prevent other users from reading the `secrets.json` file: - - ```console - chmod 600 secrets.json - ``` - -4. Fill the `indexer` field in the `secrets.json` file with the following values: - - ```json - "indexer": "123456", - ``` - - !!! info - - These values apply only to the [Coston Testnet](https://dev.flare.network/network/overview) and will be different for other networks. - -## Depositing Collateral into an Agent's Collateral Pool - -The collateral pool can contain only `$CFLR`, so ensure you funded your wallet with tokens from the faucet, as described in step 2 above. - -1. Use the command below to list all available agents: - - ```console - yarn user-bot --fasset FTestXRP agents - ``` - - A list of agents is displayed. - -2. Copy the address of an agent in the list. -3. Use the command below to send your collateral to the agent. - Replace `AGENT_ADDRESS` with the address you copied in the previous step, and replace `CFLR_AMOUNT` with a portion of the funds you received from the faucet. - - ```console - yarn agent-bot buyPoolCollateral AGENT_ADDRESS CFLR_AMOUNT --fasset FTestXRP - ``` - - A message indicates the amount of collateral you successfully provided to the selected agent's collateral pool. diff --git a/docs/user/fassets/index.md b/docs/user/fassets/index.md deleted file mode 100644 index 234c7c1ee..000000000 --- a/docs/user/fassets/index.md +++ /dev/null @@ -1,7 +0,0 @@ -# FAssets - -The following guides explains how to manage [FAssets](../../tech/fassets/index.md). - -* [Using the Command Line to Deposit Collateral](./depositing-collateral-cli.md) -* [Using the Command Line to Mint and Redeem FAssets](./minting-redeeming-cli.md) -* [Using the FAssets Demo Dapp to Mint and Redeem FAssets](./minting-redeeming-dapp.md) diff --git a/docs/user/fassets/minting-redeeming-cli.md b/docs/user/fassets/minting-redeeming-cli.md deleted file mode 100644 index 3d71000fe..000000000 --- a/docs/user/fassets/minting-redeeming-cli.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: Minting and Redeeming (CLI) ---- - -# Using the Command Line to Mint and Redeem FAssets - -Users of the [FAssets](../../tech//fassets/index.md) system can mint and redeem FAssets, allowing tokens on blockchains that do not support smart contracts to be used trustlessly with smart contracts on the Flare blockchain. - -This guide is for advanced users who having some experiencing using a terminal. -It provides the following information: - -* How to set up the FAssets command-line tool. -* How to convert testnet XRP to FAssets (FTestXRP) on the Flare test network (minting). -* How to convert FAssets (FTestXRP) from Flare test network back to testnet XRP Ledger network (redemption). - -Alternatively, you can [use the dapp to mint and redeem FAssets](./minting-redeeming-dapp.md). - ---8<-- "./include/fassets/open-beta.md" - ---8<-- "./include/fassets/prerequisites-user.md" ---8<-- "./include/fassets/setup-commandline.md" - -### Configure User's Access Keys - -The FAsset user operates with multiple keys for the Flare and underlying network chains. - -1. Generate the user's secrets using this command: - - ```console - yarn key-gen generateSecrets --user -o secrets.json - ``` - - Among other things, this command creates wallets on the XRP Ledger and Flare networks that you will use throughout the rest of this guide. - - --8<-- "./include/fassets/generate-keys-info.md" - -2. Fund the user's FLR wallet with some CFLR to pay the gas fees. You can find the user wallet's address in the `secrets.json` file under the `user.native.address` key. -You can get the CFLR tokens from the [Flare faucet](https://faucet.flare.network/). - -3. Prevent other users from reading the `secrets.json` file: - - ```console - chmod 600 secrets.json - ``` - -4. Fill the `native_rpc`, `xrp_rpc` and `indexer` fields in the `secrets.json` file with the following values: - - ```json - "native_rpc": "AavSehMLhcgz3crQHH5YJ3Rt8GMQGdV9aViGilADXGnTcjij", - "xrp_rpc": "4tg3AxysaZodxTqsCtcMnBdBIEkR6KDKGTdqBEA8g9MKq4bH", - "indexer": "123456", - ``` - - !!! info - - These values apply only to the [Coston Testnet](https://dev.flare.network/network/overview) and will be different for other networks. - -## Minting FAssets - -1. Use the command below to list all available agents and their minting fees. Then chose one. - - ```console - yarn user-bot --fasset FTestXRP agents - ``` - -2. Use this command to determine the FAssets [lot](../../tech/fassets/minting.md#lots) size, since you will need it next: - - ```console - yarn user-bot info -f FTestXRP - ``` - - You need to find the line in the command output that displays the lot size in this format: - - ```console - Lot size: 20 FTestXRP - ``` - -3. Find your generated XRP Ledger testnet wallet address in `user.testXRP.address` from the `secrets.json` file you created above, and fund it using one of the faucets: - - * [XRP Testnet Faucet](https://test.bithomp.com/faucet/) - * [XRP Ledger Faucet](https://faucet.tequ.dev/) - - !!! info - - The minimum amount of FAssets you can mint is one lot, determined by the previous command. - Furthermore, agents charge a fee, and you should pay for a transaction on the XRP network. - Once you have selected an agent and know its fee, request enough XRP from the faucet to pay for it, plus the transaction cost. - -4. Mint the FTestXRP FAssets by running the following command, replacing `AGENT_ADDRESS` with an agent address from the list obtained before, and `LOTS` with the number of [lots](../../tech/fassets/minting.md#lots) to mint: - - ```console - yarn user-bot mint -a AGENT_ADDRESS LOTS --fasset FTestXRP --secrets secrets.json - ``` - - Alternatively, you can rely on the FAssets system to automatically select the agent with the lowest fee by removing the `-a AGENT_ADDRESS` parameter from the previous command: - - ```console - yarn user-bot mint LOTS --fasset FTestXRP --secrets secrets.json - ``` - -## Redeeming FAssets - -Redeem the FTestXRP for the underlying asset obtained in the previous step by running the following command and replacing `LOTS` with the number of lots you want to redeem: - - ```console - yarn user-bot redeem LOTS --fasset FTestXRP --secrets secrets.json - ``` - -!!! info - - The [redemption](../../tech/fassets/redemption.md) may take an hour or more for the underlying funds to arrive at the user's address. If the agent pays immediately, redemption takes about 5 minutes. - However, if the agent delays, the redeemer must wait 500 testXRP blocks or 900 seconds, plus 5 minutes for [Flare Data connector](../../tech/data-connector.md) proof, to execute redemption default. - -## Related Pages - -* [Deploying an FAssets Agent](../../infra/fassets/deploying-agent.md) -* [FAssets Open Beta](../../tech/fassets/open-beta.md) diff --git a/docs/user/fassets/minting-redeeming-dapp.md b/docs/user/fassets/minting-redeeming-dapp.md deleted file mode 100644 index 3270ed6ff..000000000 --- a/docs/user/fassets/minting-redeeming-dapp.md +++ /dev/null @@ -1,214 +0,0 @@ ---- -title: Minting and Redeeming (Dapp) ---- - -# Using the FAssets Demo Dapp to Mint and Redeem FAssets - -Users of the [FAssets](../../tech//fassets/index.md) system can use the FAssets Demo Dapp with their [Bifrost wallet](https://bifrostwallet.com/?utm_source=flare_network&utm_medium=blog&utm_campaign=fasset_open_beta) to mint and redeem FAssets, which allow tokens on blockchains that do not support smart contracts to be used trustlessly with smart contracts on the Flare blockchain. -Alternatively, you can [use the command line to mint and redeem FAssets](./minting-redeeming-cli.md). - -In this guide you will deposit some test XRP tokens into an XRP account and use the FAssets system to mint them into FTestXRP FAsset tokens on the Coston network. -You will receive these tokens in a Coston account. - -!!! info "Open Beta" - - The FAssets system is currently in the [Open Beta](../../tech/fassets/open-beta.md) period. - During this phase, user-friendly tools are still being developed. - - --8<-- "./include/fassets/issue-collector.html" - - Alternatively, you can contact [support@flarelabs.org](mailto:support@flarelabs.org). - -## Prerequisites - -* A computer and a mobile device. -* The latest version of [Bifrost Wallet](https://bifrostwallet.com/?utm_source=flare_network&utm_medium=blog&utm_campaign=fasset_open_beta) installed on your mobile device and a wallet address created. -Be sure to store your seed phrase somewhere very safe. -For more information about securing your Flare experience, read this [summary](https://flare.network/a-quick-guide-to-secure-your-flare-experience/). - -## 1. Activate Developer Mode in Your Bifrost Wallet - -To access test networks in Bifrost Wallet, you need to activate **Developer Mode**. - -1. Open your wallet, and click the cog icon displayed in the bottom-right corner of the screen to open the **Settings** menu. -2. Click **Advanced**, then click the **Developer Mode** switch. - -
- ![Developer Mode](dapp-settings.png){ loading=lazy .allow-zoom } -
Developer Mode.
-
- -3. Click **Enable** to activate **Developer Mode**. - -## 2. Get Your Addresses for Testnet Tokens - -To mint FAssets on the Coston network, you will need testnet tokens. -Before you can use faucets to get the tokens, you must get from Bifrost the addresses of the accounts on the XRP and Coston networks that you will use later in this guide. - -1. Return to the **Settings** menu, click the upward arrow button, and then click **Receive**. - -
- ![Receive Token](dapp-receive.png){ loading=lazy .allow-zoom } -
Choose to Receive a Token.
-
- -2. In the **Search coin** field, type `XRP`, and select **XRP** in the results list. - -
- ![Receive XRP](dapp-receive-result.png){ loading=lazy .allow-zoom } -
Choose to Receive XRP.
-
- - Your XRPL testnet address is displayed as a QR code and a string of letters and numbers. - -3. Tap the string of letters and numbers below the QR code to copy your XRPL address, and paste it in a text file so that you can use it in later steps. - -
- ![XRPL Address](dapp-receive-address.png){ loading=lazy .allow-zoom } -
Copy Your XRPL Address.
-
- -4. Return to the **Receive** menu, type `CFLR` in the search field, and then select **Coston Flare** in the results list. - -
- ![Receive CFLR](dapp-receive-result-cflr.png){ loading=lazy .allow-zoom } -
Choose to Receive CFLR.
-
- - Your CFLR testnet address is displayed as a QR code and a string of letters and numbers. - -5. Tap the string of letters and numbers below the QR code to copy your CFLR address, and paste it in a text file so that you can use it in later steps. - -
- ![CFLR Address](dapp-receive-address-cflr.png){ loading=lazy .allow-zoom } -
Copy Your CFLR Address.
-
- -## 3. Get Testnet Tokens - -You will need the addresses you copied in the previous step to get the testnet tokens. -Testnet tokens are free and have no monetary value. - -1. On your computer, open the [FAssets Demo Dapp](https://fasset-beta-minting.flarelabs.org/). -2. On the home page, click **Get Your textXRP here**. - The **XRPL Testnet Faucet** page is displayed. -3. Copy the XRPL address that you saved in Step 3 above, and paste it in the **XRPL address** field on the faucet page. -The XRP address is the address that does not start with `0x`. -4. In the **XRP (Testnet)** field, select 1000 XRP. -5. Select the checkbox. -6. Click **Send me XRP**. - TestXRP tokens are sent to your Bifrost Wallet. - -
- ![XRPL Faucet](dapp-faucet-xrp.png){ loading=lazy .allow-zoom } -
XRP Testnet Faucet page.
-
- -7. Return to the FAssets Demo Dapp home page, and click **Get Your CFLR here**. - The **Official Flare Faucet** page is displayed. - -
- ![Flare Faucet](dapp-faucet-cflr.png){ loading=lazy .allow-zoom } -
Official Flare Faucet page.
-
- -8. Copy the CFLR address that you saved in Step 3 above, and paste it in the **Flare address** field on the faucet page. -The Coston address is the address that starts with `0x`. -9. Click **Request CFLR**. - 100 CFLR are sent to your Bifrost Wallet. - -10. In your Bifrost Wallet, review your updated balances of testXRP and CFLR. - -
- ![Token Balances](dapp-tokens-balances.png){ loading=lazy .allow-zoom } -
Testnet Token Balances.
-
- -## 4. Connect Your Bifrost Wallet to the FAssets Demo Dapp - -1. On your computer, open the FAssets Demo Dapp, click the **Connect Bifrost Wallet** button near the middle fo the page, and click **Wallet Connect**. - A QR code is displayed. -2. In Bifrost Wallet on your mobile device, click the blue arrow in the navigation bar, and select **Connect**. - -
- ![Connect Bifrost](dapp-bifrost-connect.png){ loading=lazy .allow-zoom } -
Connect Bifrost.
-
- - Your camera application is activated. - -3. In your camera application, align the QR code displayed in Step 1 until the application detects it. - Bifrost Wallet prompts you to connect. - -
- ![Confirm Connection](dapp-bifrost-confirm.png){ loading=lazy .allow-zoom } -
Confirm Connection.
-
- -4. Click **Connect**. - The dapp is connected to your Bifrost Wallet. - A confirmation dialog is displayed, and the FAssets Demo Dapp shows the balances of the two accounts. - -## 5. Mint FTestXRP - -1. In the FAssets Demo Dapp, locate the **FAssets** section on the page, and click **Mint** beside **FTestXRP**. - -
- ![Mint FTestXRP](dapp-ftestxrp-mint.png){ loading=lazy .allow-zoom } -
Mint FTestXRP.
-
- -2. In the [Lots](../../tech/fassets/minting.md#lots) field, specify how many lots of FTestXRP you want to mint. - To help the FAssets system, split the total into multiple transactions made over several days. - -
- ![Lots](dapp-ftestxrp-lots.png){ loading=lazy .allow-zoom } -
Lots.
-
- -3. Click **Next**. - The minting process begins. - In Bifrost Wallet, a confirmation prompt for the collateral reservation is displayed, which shows the number of lots you specified and the minting fee. - -
- ![Confirmation](dapp-ftestxrp-reserve.png){ loading=lazy .allow-zoom } -
Confirm the Collateral Reservation.
-
- -4. Click **Confirm** and input either your PIN or your biometrics, depending on the way you set up your wallet. - The collateral is reserved, the CFLR is sent to the `FAssets` contract, and another confirmation prompt is displayed ([Step 2 of this process](https://docs.flare.network/tech/fassets/minting/#minting-process)). - -
- ![Confirmation](dapp-ftestxrp-confirm.png){ loading=lazy .allow-zoom } -
Approve the Transaction.
-
- -5. Click **Confirm** and input either your PIN or your biometrics, depending on the way you set up your wallet. - The transaction is approved. - The [Data Connector](../../tech/data-connector.md) trustlessly proves that you, via the FAssets Demo Dapp, sent the right amount of testXRP to the correct address with the correct reference. - This process for the Data Connector to come to consensus and provide the FAssets system with a proof that this has occurred takes approximately 5 minutes. - Progress through the four stages of processing the mint is displayed. - -
- ![Mint Progress](dapp-ftestxrp-progress.png){ loading=lazy .allow-zoom } -
Example of a Mint Progress Window.
-
- - After the proof is received, the FTestXRP is minted, and the balance is displayed in your Bifrost Wallet. - -
- ![Mint Progress](dapp-ftestxrp-balance.png){ loading=lazy .allow-zoom } -
Example of a Mint Progress Window.
-
- -## 5. Redeem FTestXRP - -You can follow a similar process to redeem your FTestXRP and receive your original testXRP back in your wallet. -During this open beta phase, if you run out of testXRP or Coston Flare, you can always head back to the faucets to get more. -Each address can obtain a maximum of 1000 testXRP and 100 CFLR per day. - -FTestXRP is a regular [ERC-20](../../tech/glossary.md#erc20) token on the Coston network, so you can send it or receive it using standard tools, and the receiver can use the redeeming process described here to get the testXRP back. - -!!! warning - - Remember to keep a small amount of CFLR for gas. diff --git a/docs/user/index.md b/docs/user/index.md index cc9decac9..dfd64696f 100644 --- a/docs/user/index.md +++ b/docs/user/index.md @@ -8,7 +8,6 @@ Select one of the topics below: * [Claiming the FlareDrop](./claiming-the-flaredrop.md) * [FTSO Delegation](./delegation/index.md) * [Governance](./governance/index.md) -* [Minting and Redeeming FAssets](./fassets/index.md) * [Personal Delegation Accounts](./personal-delegation-account.md) * [Staking on Validators](./staking/index.md) * [Wallets](./wallets/index.md) diff --git a/include/fassets/generate-keys-info.md b/include/fassets/generate-keys-info.md deleted file mode 100644 index 340e9f375..000000000 --- a/include/fassets/generate-keys-info.md +++ /dev/null @@ -1,9 +0,0 @@ -!!! info - - This command can only be executed once, after which all secret keys will be generated. - You must use a separate directory for each role you want to perform: agent, bot, or minter and redeemer. - -!!! warning - - * The addresses in `secrets.json` are for hot wallets and should not hold large token amounts, as their private keys are on an always-online machine. Keep your main account in an offline wallet and transfer funds as needed. - * As soon as you create the `secrets.json` file, back it up, and remember to back it up again whenever you add new keys. Store the backup securely, preferably on an external drive in a physical vault, as unauthorized access can compromise the agent. You need to make regular backups only if you make changes. \ No newline at end of file diff --git a/include/fassets/issue-collector.html b/include/fassets/issue-collector.html deleted file mode 100644 index 772667bc3..000000000 --- a/include/fassets/issue-collector.html +++ /dev/null @@ -1,14 +0,0 @@ - - - - - - -*Some web browsers and ad blockers might prevent this functionality.* diff --git a/include/fassets/open-beta.md b/include/fassets/open-beta.md deleted file mode 100644 index 9669d8a13..000000000 --- a/include/fassets/open-beta.md +++ /dev/null @@ -1,8 +0,0 @@ -!!! info "Open Beta" - - The FAssets system is currently in the [Open Beta](../../tech/fassets/open-beta.md) period. - During this phase, user-friendly tools are still being developed. - - --8<-- "./include/fassets/issue-collector.html" - - Alternatively, you can contact [support@flarelabs.org](mailto:support@flarelabs.org). \ No newline at end of file diff --git a/include/fassets/prerequisites-agent.md b/include/fassets/prerequisites-agent.md deleted file mode 100644 index 587be5345..000000000 --- a/include/fassets/prerequisites-agent.md +++ /dev/null @@ -1,12 +0,0 @@ -## Prerequisites - -You need a server with at least a minimum of 2 CPUs and 4GB RAM, or 2GB if the database is on a separate server. - -You need knowledge of the following tools: - -* [Git](https://git-scm.com/) version control system -* [Yarn](https://yarnpkg.com/) package manager -* A [wallet](../../user/wallets/index.md) configured for [Flare networks](https://dev.flare.network/network/overview) -* Command-line terminal -* Code editor -* [MySQL](https://dev.mysql.com/doc/) or [PostgreSQL](https://www.postgresql.org/) server \ No newline at end of file diff --git a/include/fassets/prerequisites-user.md b/include/fassets/prerequisites-user.md deleted file mode 100644 index 9a563f021..000000000 --- a/include/fassets/prerequisites-user.md +++ /dev/null @@ -1,11 +0,0 @@ -## Prerequisites - -You need a server with at least a minimum of 2 CPUs and 4GB RAM, or 2GB if the database is on a separate server. - -You need knowledge of the following tools: - -* [Git](https://git-scm.com/) version control system -* [Yarn](https://yarnpkg.com/) package manager -* A [wallet](../../user/wallets/index.md) configured for [Flare networks](https://dev.flare.network/network/overview) -* Command-line terminal -* Code editor \ No newline at end of file diff --git a/include/fassets/setup-commandline.md b/include/fassets/setup-commandline.md deleted file mode 100644 index ff7c9499a..000000000 --- a/include/fassets/setup-commandline.md +++ /dev/null @@ -1,53 +0,0 @@ -!!! warning - - If you are using Windows, it is strongly recommended to use [Windows Subsystem for Linux, version 2](https://docs.microsoft.com/en-us/windows/wsl/about) (WSL 2). - -## Setting up the FAssets tools - -### Setting up After Testnet XRP Reset - -!!! info - - This section is only for users using FAssets before the testnet XRP reset, so please [read more](https://flare.network/important-update-xrp-testnet-reset-fassets-beta-reset/). - -Suppose you previously ran the FAssets agent before the XRP testnet reset. You will need to skip the whitelisting part but still need to: - -* pull the latest changes from the repository by `git pull`; -* build then with `yarn && yarn build`; -* installing the MySQL database and setting it up [following the guide](#setting-up-mysql-database) later in this document; -* create a new agent using the existing management address following the guide. - -### Clone and Setup the Tools Repository - -!!! info - - If you set up an FAssets agent, bot or user, please use a separate directory for each role. - -1. Clone the repository and enter the working directory: - - ```bash - git clone https://github.com/flare-labs-ltd/fasset-bots.git - cd fasset-bots - ``` - -2. Switch to the `open_beta` branch: - - ```bash - git checkout open_beta - ``` - -3. Install dependencies and build the project: - - ```bash - yarn && yarn build - ``` - - !!! info - - Fresh installation can take more than 10 minutes, depending on if you have cached dependencies before. - -4. Copy the environment file from a template `.env.template` to `.env`: - - ```bash - cp .env.template .env - ``` \ No newline at end of file diff --git a/include/fassets/setup-database.md b/include/fassets/setup-database.md deleted file mode 100644 index cf0a8dc00..000000000 --- a/include/fassets/setup-database.md +++ /dev/null @@ -1,159 +0,0 @@ -### Setting up Database for FAssets Agent - -To proceed with this process, you must set up a database, either [MySQL](#setting-up-mysql-database) or [PostgreSQL](#setting-up-postgresql-database). - -#### Setting up MySQL Database - -You have two options to set up a MySQL database: using Docker (preferred) or installing it manually. - -**Setting up MySQL Database with Docker** - -1. Download and install [Docker Desktop](https://www.docker.com/products/docker-desktop/). -2. Create a `docker-compose.yml` file in your directory, add the following lines, and change the value of `VerySafePassword` according to your security standards: - ```docker - services: - mysql: - image: mysql:8.0 - environment: - MYSQL_ROOT_PASSWORD: 'root' - MYSQL_DATABASE: 'fasset_bots' - MYSQL_USER: 'fassetbot' - MYSQL_PASSWORD: 'my1beta2password3' - volumes: - - mysql_data:/var/lib/mysql - - ./init.mysql.sql:/docker-entrypoint-initdb.d/init.mysql.sql - ports: - - "3306:3306" - healthcheck: - test: ['CMD', 'mysqladmin', 'ping', '-h', '127.0.0.1', '-u', 'root', '-p$MYSQL_ROOT_PASSWORD'] - timeout: 20s - retries: 10 - - volumes: - mysql_data: - ``` -3. Create a file named `init.mysql.sql` in the same directory, add the following lines, and change the value of `VerySafePassword` according to your security standards: - ```sql - CREATE USER IF NOT EXISTS 'fassetbot'@'%' IDENTIFIED BY 'my1beta2password3'; - GRANT ALL PRIVILEGES ON *.* TO 'fassetbot'@'%' WITH GRANT OPTION; - GRANT ALL PRIVILEGES ON fasset_bots.* TO 'fassetbot'@'%' WITH GRANT OPTION; - ``` -4. Start the MySQL server as a Docker container by running `docker-compose up -d`. After the MySQL database is started, it will continue to run in the background every time you run the agent. -5. In the `secrets.json` file, add this block to the list to set the database `user` and `password`, and change the value of `password` to the same password you have been using. - ``` - "database": { - "user": "fassetbot", - "password": "my1beta2password3" - } - ``` - -**Setting up MySQL Database Manually** - -To install the MySQL database manually, refer to the official [MySQL documentation](https://dev.mysql.com/doc/). - -The MySQL database connection parameters are listed in the file as the value for the variable `FASSET_BOT_CONFIG` in the `.env` file. - -Create a new user in MySQL that will be used by the `fasset-bots` to connect to the database. In this example, we will create a user with the username `fassetbot` and password `VerySafePassword`, which you must replace with a secure value. - -!!! warning - You only need to create the user in the database and grant privileges to that user. Do not create the database. - -1. Open your terminal or command prompt and login to MySQL database using the `mysql` command with the appropriate credentials: - -2. Create a new user `fassetbot` in MySQL database using the "CREATE USER" command with the password "VerySafePassword": - - ```sql - CREATE USER 'fassetbot'@'localhost' IDENTIFIED BY 'VerySafePassword'; - ``` - -3. Grant all privileges on all databases to the user by using the `GRANT` statement: - - ```sql - GRANT ALL PRIVILEGES ON *.* TO 'fassetbot'@'localhost' WITH GRANT OPTION; - ``` - -4. **Grant Privileges:** - After creating the user, you need to grant appropriate privileges to the user. Use the `GRANT` statement to give permissions to the user. For example, to grant all privileges on the `fasset_bots` database: - ```sql - GRANT ALL PRIVILEGES ON fasset_bots.* TO 'fassetbot'@'localhost' WITH GRANT OPTION; - ``` - -5. Exit the MySQL database prompt by typing: - - ```bash - exit; - ``` - -#### Setting up PostgreSQL Database - -To set up a PostgreSQL database, you have two options: using Docker (preferred) or installing it manually. - -**Setting up PostgreSQL Database with Docker** - -1. Download and install [Docker Desktop](https://www.docker.com/products/docker-desktop/). -2. Create a `docker-compose.yml` file in your directory, add the following lines, and change the value of `VerySafePassword` according to your security standards: - ```docker - services: - postgres: - image: postgres:15 - container_name: postgres_db - environment: - POSTGRES_USER: fassetbot - POSTGRES_PASSWORD: my1beta2password3 - POSTGRES_DB: fasset_bots - ports: - - "5432:5432" - volumes: - - pgdata:/var/lib/postgresql/data - - ./init.postgresql.sql:/docker-entrypoint-initdb.d/init.postgresql.sql - healthcheck: - test: ["CMD-SHELL", "pg_isready -U $POSTGRES_USER -d $POSTGRES_DB -h 127.0.0.1"] - timeout: 20s - retries: 10 - - volumes: - pgdata: - ``` - -3. Start the PostgreSQL server as a Docker container by running `docker-compose up -d`. After the PostgreSQL database is started, it will continue to run in the background every time you run the agent. -4. In the `secrets.json` file, add this block to the list to set the database `user` and `password`, and change the value of `password` to the same password you have been using. - ``` - "database": { - "user": "fassetbot", - "password": "my1beta2password3" - } - ``` -5. Modify the `FASSET_BOT_CONFIG variable` in the `.env` file located in the root of the repository. - ``` - FASSET_BOT_CONFIG="./packages/fasset-bots-core/run-config/coston-bot-postgresql.json" - ``` - -**Setting up PostgreSQL Database Manually** - -To install the PostgreSQL database manually, refer to the official [PostgreSQL documentation](https://www.postgresql.org/docs/current/index.html). - -You can find PostgreSQL database connection parameters in the file listed as the value for the variable `FASSET_BOT_CONFIG` in the `.env` file. - -Create a new user in PostgreSQL that will be used by the `fasset-bots` to connect to the database. In this example, we will create a user with the username `fassetbot` and password `VerySafePassword`, which you must replace with a secure value. - -!!! warning - You only need to create the user in the database and grant privileges to that user. Do not create the database. - -1. Open your terminal or command prompt and login to PostgreSQL database using the `psql` command with the appropriate credentials. - -2. Create a new user `fassetbot` in the PostgreSQL database command with the password "VerySafePassword" and grant the superuser privileges: - - ```pgsql - CREATE ROLE fassetbot WITH SUPERUSER LOGIN PASSWORD 'VerySafePassword'; - ``` - -3. Exit the PostgreSQL database prompt by typing: - - ```bash - exit; - ``` - -4. Modify the `FASSET_BOT_CONFIG variable` in the `.env` file located in the root of the repository. - ``` - FASSET_BOT_CONFIG="./packages/fasset-bots-core/run-config/coston-bot-postgresql.json" - ``` \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 0c384e940..d2c065526 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -249,7 +249,6 @@ plugins: 'user/delegation/reward-claiming.md': 'tech/ftso/index.md' 'user/delegation/reward-claiming-faq.md': 'tech/ftso/index.md' 'user/delegation/reward-claiming-in-detail.md': 'tech/ftso/index.md' - 'user/fassets/minting-redeeming.md': 'user/fassets/index.md' 'infra/data/operating.md': 'developer-hub.md' 'infra/validation/staking-cli.md': 'user/staking/staking-cli.md' 'infra/observation/faq.md': 'developer-hub.md' @@ -265,6 +264,21 @@ plugins: 'infra/data/managing-ecosystem/monitoring-price-history.md': 'developer-hub.md' 'tech/ftso/ftso-scaling.md': 'https://dev.flare.network/ftso/overview/' 'tech/ftso/ftso-fast-updates.md': 'https://dev.flare.network/ftso/overview/' + 'infra/fassets/index.md': 'https://dev.flare.network/category/fassets-guides' + 'infra/fassets/deploying-agent.md': 'https://dev.flare.network/fassets/guides/deploy-fassets-agent' + 'infra/fassets/managing-agent.md': 'https://dev.flare.network/fassets/guides/create-fasset-agent-ui' + 'infra/fassets/liquidator.md': 'https://dev.flare.network/fassets/guides/deploy-fassets-agent' + 'tech/fassets/index.md': 'https://dev.flare.network/fassets/overview' + 'tech/fassets/collateral.md': 'https://dev.flare.network/fassets/collateral' + 'tech/fassets/minting.md': 'https://dev.flare.network/fassets/minting' + 'tech/fassets/redemption.md': 'https://dev.flare.network/fassets/redemption' + 'tech/fassets/liquidation.md': 'https://dev.flare.network/fassets/liquidation' + 'tech/fassets/open-beta.md': 'https://dev.flare.network/fassets/songbird' + 'tech/fassets/parameters.md': 'https://dev.flare.network/fassets/operational-parameters' + 'user/fassets/index.md': 'developer-hub.md' + 'user/fassets/depositing-collateral-cli.md': 'developer-hub.md' + 'user/fassets/minting-redeeming-cli.md': 'developer-hub.md' + 'user/fassets/minting-redeeming-dapp.md': 'developer-hub.md' extra_css: - assets/stylesheets/extra.css @@ -331,11 +345,6 @@ nav: - user/staking/staking-cli.md - user/claiming-the-flaredrop.md - user/automatic-claiming.md - - FAssets: - - user/fassets/index.md - - user/fassets/depositing-collateral-cli.md - - user/fassets/minting-redeeming-cli.md - - user/fassets/minting-redeeming-dapp.md - Governance: - user/governance/index.md - user/governance/voting.md @@ -344,14 +353,6 @@ nav: - FTSO: - tech/ftso/index.md - tech/data-connector.md - - FAssets: - - tech/fassets/index.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/api-portal.md - Concepts: - tech/index.md @@ -371,8 +372,3 @@ nav: - Infrastructure: - infra/index.md - infra/connected-networks.md - - FAssets: - - infra/fassets/index.md - - infra/fassets/deploying-agent.md - - infra/fassets/managing-agent.md - - infra/fassets/liquidator.md