diff --git a/docs/infra/fassets/agent.md b/docs/infra/fassets/agent.md new file mode 100644 index 000000000..7de77dbc7 --- /dev/null +++ b/docs/infra/fassets/agent.md @@ -0,0 +1,168 @@ +# 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 test XRP Ledger network; +* 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 testnet XRP Ledger to the Flare test network and back. + +!!! 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" + +--8<-- "./include/fassets/setup-commandline.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. 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/). + +4. Whitelist the Flare account belonging to your agent owner (use `owner.management.address` from the `secrets.json` file) via the [FlareFAssetsBot Telegram channel](https://t.me/FlareFAssetsBot). + +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](../../dev/reference/network-config.md) and will be different for other networks. + +## 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 [0x746cBEAa5F4CAB057f70e10c2001b3137Ac223B7](https://coston-explorer.flare.network/address/0x746cBEAa5F4CAB057f70e10c2001b3137Ac223B7/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` file: + + ```console + yarn agent-bot --fasset FTestXRP 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, 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` field is the underlying testnet XRP Ledger account that pays the underlying chain's transaction fees. +Activate your underlying XRP Ledger account by sending at least 100 test-XRP to it by using one of the XRP Ledger testnet faucets: + + * [XRP Testnet Faucet](https://test.bithomp.com/faucet/) + * [XRP Ledger Faucet](https://faucet.tequ.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. + + ```console + yarn agent-bot --fasset FTestXRP 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`. + +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`: + +```console +yarn agent-bot depositCollaterals AGENT_ADDRESS LOTS --fasset FTestXRP +``` + +#### 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. + + ```console + yarn agent-bot depositVaultCollateral AGENT_ADDRESS AMOUNT --fasset FTestXRP + ``` + +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. + + ```console + yarn agent-bot buyPoolCollateral AGENT_ADDRESS CFLR_AMOUNT --fasset FTestXRP + ``` + +### 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: + + ```console + yarn agent-bot enter AGENT_ADDRESS --fasset FTestXRP + ``` + + !!! 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. + + ```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). + +## 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. + +!!! info + + Run the run-agent 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). + +## Related Docs + +* [Minting and Redeeming FAssets](../../user/fassets/minting-redeeming.md) +* [FAssets Open Beta](../../tech/fassets/open-beta.md) diff --git a/docs/infra/fassets/index.md b/docs/infra/fassets/index.md new file mode 100644 index 000000000..b258e29dc --- /dev/null +++ b/docs/infra/fassets/index.md @@ -0,0 +1,5 @@ +# FAssets + +The following guide explains how to set up and manage an [FAssets](../../tech/fassets/index.md) agent. + +* [Deploying an FAssets agent](./agent.md) diff --git a/docs/infra/index.md b/docs/infra/index.md index 375d040a9..f43674c67 100644 --- a/docs/infra/index.md +++ b/docs/infra/index.md @@ -5,6 +5,7 @@ This section contains step-by-step guides on how to deploy the different compone Select one of the topics below: * [Becoming an Attestation Provider](./attestation/index.md) +* [Deploying FAssets Agent](./fassets/index.md) * [FTSO Data Providers](./data/index.md) * [Observer Nodes](./observation/index.md) * [Validator Nodes](./validation/index.md) diff --git a/docs/tech/fassets/open-beta.md b/docs/tech/fassets/open-beta.md new file mode 100644 index 000000000..abffb79a3 --- /dev/null +++ b/docs/tech/fassets/open-beta.md @@ -0,0 +1,35 @@ +# 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. + +## 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). + 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 Docs + +* [Minting and Redeeming FAssets](../../user/fassets/minting-redeeming.md) +* [Deploying FAssets Agent](../../infra/fassets/agent.md) diff --git a/docs/user/fassets/index.md b/docs/user/fassets/index.md new file mode 100644 index 000000000..94cf4cc42 --- /dev/null +++ b/docs/user/fassets/index.md @@ -0,0 +1,5 @@ +# Fassets + +The following guide explains how to mint and redeem [FSssets](../../tech/fassets/index.md). + +* [Minting and Redeeming FAssets](./minting-redeeming.md) diff --git a/docs/user/fassets/minting-redeeming.md b/docs/user/fassets/minting-redeeming.md new file mode 100644 index 000000000..b950198a1 --- /dev/null +++ b/docs/user/fassets/minting-redeeming.md @@ -0,0 +1,114 @@ +# Minting and Redeeming 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 provides the following information: + +* How to set up the FAssets command-line tool. +* How to convert testnet XRP to FAssets (FXRP) on the Flare test network (minting). +* How to convert FAssets (FXRP) from Flare test network back to testnet XRP Ledger network (redemption). + +!!! 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" + +--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](../../dev/reference/network-config.md) 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 [state connector](../../tech/state-connector.md) proof, to execute redemption default. + +## Related Pages + +* [Deploying an FAssets Agent](../../infra//fassets//agent.md) +* [FAssets Open Beta](../../tech/fassets/open-beta.md) diff --git a/docs/user/index.md b/docs/user/index.md index 104b701fa..ef8b6262f 100644 --- a/docs/user/index.md +++ b/docs/user/index.md @@ -9,6 +9,7 @@ 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/minting-redeeming.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 new file mode 100644 index 000000000..30bcfd0da --- /dev/null +++ b/include/fassets/generate-keys-info.md @@ -0,0 +1,8 @@ +!!! info + + This command can only be executed once, after which all secret keys will be generated. + To set up a new agent or mint and redeem FAssets, use a separate directory per each setup. + +!!! warning + + To prevent serious security risks, avoid storing your addresses and private keys in the `secrets.json` file. Instead, transfer funds from your wallet to these generated addresses. \ No newline at end of file diff --git a/include/fassets/issue-collector.html b/include/fassets/issue-collector.html new file mode 100644 index 000000000..7c268b4e3 --- /dev/null +++ b/include/fassets/issue-collector.html @@ -0,0 +1,12 @@ + + + + + diff --git a/include/fassets/setup-commandline.md b/include/fassets/setup-commandline.md new file mode 100644 index 000000000..acd7d6853 --- /dev/null +++ b/include/fassets/setup-commandline.md @@ -0,0 +1,47 @@ +## Prerequisites + +To participate in the open beta, 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 will need knowledge of the following tools: + +* [Git](https://git-scm.com/) version control system; +* [Yarn](https://yarnpkg.com/) package manager; +* Command line terminal; +* Code editor. + +## Setting up the FAssets tools + +### Clone and Setup the Tools Repository + +!!! info + + If you set up an FAssets agent or user, please use a separate directory for each setup. + +1. Clone the repository and enter the working directory: + + ```console + git clone git@github.com:flare-labs-ltd/fasset-bots.git + cd fasset-bots + ``` + +2. Switch to the `open_beta` branch: + + ```console + git checkout open_beta + ``` + +3. Install dependencies and build the project: + + ```console + 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`: + + ```console + cp .env.template .env + ``` diff --git a/mkdocs.yml b/mkdocs.yml index ad2d172b1..66842cc29 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -174,6 +174,9 @@ nav: - user/wallets/safepal-s1-wallet.md - user/wallets/how-to-access-flare-network-with-a-trezor-device.md - user/wrapping-tokens.md + - FAssets: + - user/fassets/index.md + - user/fassets/minting-redeeming.md - FTSO Delegation: - user/delegation/index.md - Managing Delegations: user/delegation/managing-delegations.md @@ -341,6 +344,7 @@ nav: - tech/state-connector.md - FAssets: - tech/fassets/index.md + - tech/fassets/open-beta.md - tech/fassets/collateral.md - tech/fassets/minting.md - tech/fassets/redemption.md @@ -373,6 +377,9 @@ nav: - infra/data/managing-ecosystem/index.md - infra/data/managing-ecosystem/exploring-collusion.md - infra/data/managing-ecosystem/monitoring-price-history.md + - FAssets Agents: + - infra/fassets/index.md + - infra/fassets/agent.md - Observer Nodes: - infra/observation/index.md - infra/observation/deploying.md