diff --git a/docs/assets/images/infra/fassets/fassets-admin-dashboard.png b/docs/assets/images/infra/fassets/fassets-admin-dashboard.png new file mode 100644 index 000000000..128ae7451 Binary files /dev/null and b/docs/assets/images/infra/fassets/fassets-admin-dashboard.png differ diff --git a/docs/assets/images/infra/fassets/fassets-admin-vaults-menu.png b/docs/assets/images/infra/fassets/fassets-admin-vaults-menu.png new file mode 100644 index 000000000..aafe4b774 Binary files /dev/null and b/docs/assets/images/infra/fassets/fassets-admin-vaults-menu.png differ diff --git a/docs/assets/images/infra/fassets/fassets-admin-vaults-view.png b/docs/assets/images/infra/fassets/fassets-admin-vaults-view.png new file mode 100644 index 000000000..96dd4dc8a Binary files /dev/null and b/docs/assets/images/infra/fassets/fassets-admin-vaults-view.png differ diff --git a/docs/assets/images/infra/fassets/fassets-admin-vaults.png b/docs/assets/images/infra/fassets/fassets-admin-vaults.png new file mode 100644 index 000000000..792fe6d8c Binary files /dev/null and b/docs/assets/images/infra/fassets/fassets-admin-vaults.png differ diff --git a/docs/infra/fassets/agent.md b/docs/infra/fassets/deploying-agent.md similarity index 100% rename from docs/infra/fassets/agent.md rename to docs/infra/fassets/deploying-agent.md diff --git a/docs/infra/fassets/index.md b/docs/infra/fassets/index.md index 16789404f..b8e7bfb6c 100644 --- a/docs/infra/fassets/index.md +++ b/docs/infra/fassets/index.md @@ -2,5 +2,6 @@ The following guide explains how to set up and manage an [FAssets](../../tech/fassets/index.md) agent. -* [Deploying an FAssets agent](./agent.md) +* [Deploying an FAssets Agent](./deploying-agent.md) +* [Manaing 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 index 7a4d89c6f..79e47a58f 100644 --- a/docs/infra/fassets/liquidator.md +++ b/docs/infra/fassets/liquidator.md @@ -67,5 +67,5 @@ 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](agent.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 new file mode 100644 index 000000000..c23e75d69 --- /dev/null +++ b/docs/infra/fassets/managing-agent.md @@ -0,0 +1,248 @@ +--- +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 + +### 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) + 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 database file for the bot. + FASSET_BOT_SQLITE_DB="../../path-to-.db-file" + ``` + +3. 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.json", + "apiNotifierConfigs": [ + { + "apiKey": "", + "apiUrl": "http://localhost:1234/" + } + ] + } + ``` + +3. 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" + ``` + +### Running the Admin Console Backend + +1. In the root of the repository, run the command: + + ```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_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/tech/fassets/index.md b/docs/tech/fassets/index.md index 426c7c935..e351d5192 100644 --- a/docs/tech/fassets/index.md +++ b/docs/tech/fassets/index.md @@ -19,6 +19,7 @@ The following diagram summarizes the relationship between the FAssets system, it 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. @@ -34,16 +35,18 @@ All these entities are independent of the Flare Foundation. The following roles participate in the FAssets system: -* [Agents](#agents) -* [Users](#users) -* [Collateral providers](#collateral-providers) -* [Liquidators](#liquidators) -* [Challengers](#challengers) +- [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, that: +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). diff --git a/docs/tech/fassets/open-beta.md b/docs/tech/fassets/open-beta.md index 331041351..e62c88257 100644 --- a/docs/tech/fassets/open-beta.md +++ b/docs/tech/fassets/open-beta.md @@ -40,5 +40,5 @@ 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/agent.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 index b7d07ea80..a4e321c78 100644 --- a/docs/tech/fassets/parameters.md +++ b/docs/tech/fassets/parameters.md @@ -57,7 +57,7 @@ Otherwise, it includes a description of the purpose of the parameter. ## Default Agent Settings -These are the default values for [the agent bot provided by the Flare foundation](../../infra/fassets/agent.md#setting-up-the-agent). +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 | Open Beta (Coston) | diff --git a/docs/user/fassets/minting-redeeming-cli.md b/docs/user/fassets/minting-redeeming-cli.md index 5f2b040db..445d6fdad 100644 --- a/docs/user/fassets/minting-redeeming-cli.md +++ b/docs/user/fassets/minting-redeeming-cli.md @@ -105,5 +105,5 @@ Redeem the FTestXRP for the underlying asset obtained in the previous step by ru ## Related Pages -* [Deploying an FAssets Agent](../../infra//fassets//agent.md) +* [Deploying an FAssets Agent](../../infra/fassets/deploying-agent.md) * [FAssets Open Beta](../../tech/fassets/open-beta.md) diff --git a/include/fassets/setup-commandline.md b/include/fassets/setup-commandline.md index 8ff8732f2..7a11900a0 100644 --- a/include/fassets/setup-commandline.md +++ b/include/fassets/setup-commandline.md @@ -4,10 +4,11 @@ To participate in the open beta, you need a server with at least a minimum of 2 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. +* [Git](https://git-scm.com/) version control system +* [Yarn](https://yarnpkg.com/) package manager +* A [wallet](../../user/wallets/index.md) configured for [Flare networks](../../dev/reference/network-config.md) +* Command-line terminal +* Code editor !!! warning diff --git a/mkdocs.yml b/mkdocs.yml index 0f614c936..9d39631be 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -383,7 +383,8 @@ nav: - infra/data/managing-ecosystem/monitoring-price-history.md - FAssets: - infra/fassets/index.md - - infra/fassets/agent.md + - infra/fassets/deploying-agent.md + - infra/fassets/managing-agent.md - infra/fassets/liquidator.md - Observer Nodes: - infra/observation/index.md