Skip to main content

Run a Liquidator

Liquidators are a critical component of the FAssets system, overseeing agents and ensuring their self-sufficiency. They contribute to the overall stability and efficiency of the system by executing liquidations.

Liquidators initiate a process where FAssets are sent into the system in exchange for collateral plus a premium. This involves burning the FAssets, which reduces the agent's collateral requirement and allows liquidators to earn rewards. Anyone can become a liquidator, supporting the FAssets system while earning rewards.

This guide explains how to run an FAssets bot that monitors the FAssets system and responds to its state. The bot must be running continuously and be constantly online to avoid missing liquidation opportunities and earning rewards.

Prerequisites​

Minimum hardware requirements:

  • CPU: 2 cores
  • RAM: 4 GB
  • Disk: 50 GB SSD

Tooling:

note

If you are using Windows, it is strongly recommended to use Windows Subsystem for Linux (WSL v2).

Setup​

info

If you set up an FAssets agent, bot or user, please use a separate directory for each role.

  1. Clone the fasset-bots repository and switch to the open_beta branch:

    git clone https://github.com/flare-labs-ltd/fasset-bots.git
    cd fasset-bots
    git checkout open_beta

  2. Install the dependencies and build the project:

    yarn && yarn build

  3. Copy the environment file from .env.example to .env:

    cp .env.example .env

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 (cold) wallet that will be your agent's management address. Fund this wallet with some CFLR for gas using the Coston Faucet.

  2. Generate secrets using the following command, replace MANAGEMENT_WALLET_ADDRESS with your wallet address:

    yarn key-gen generateSecrets --other MANAGEMENT_WALLET_ADDRESS --other -o secrets.json
    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.

    :::

  3. Prevent other users from reading the secrets.json file:

    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:

    "native_rpc": "AavSehMLhcgz3crQHH5YJ3Rt8GMQGdV9aViGilADXGnTcjij",

  5. 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 Coston Faucet.

  6. The liquidator account must hold enough FAssets to execute liquidation tasks and cover the liquidated agent FAssets amount. Therefore, you must mint FAssets and move them to the liquidator account.

Run the Liquidator​

The liquidator observes the FAssets system and reacts to its state. To run the liquidator, you need to run the following command:

yarn run-liquidator

When you want to stop the server, press Ctrl + C.

Maximize liquidator uptime​

  1. Download the example liquidator-bot.service from the repository.

  2. Modify the following variables in liquidator-bot.service:

    • WorkingDirectory: Set this to your fasset-bots checkout directory.
    • User, Group: Set these to the user under which the service should run.
    • ExecStart: If required, change the path to node.

  3. Copy the modified service file to systemd directory:

    sudo cp liquidator-bot.service /etc/systemd/system/

  4. Reload the systemd daemon to recognize the new service:

    sudo systemctl daemon-reload

  5. Manage the service:

    To start the service:

    sudo systemctl start liquidator-bot

    To stop the service:

    sudo systemctl stop liquidator-bot

  6. Enable auto-start on boot:

    sudo systemctl enable liquidator-bot

  7. View service logs:

    Follow the console output live:

    sudo journalctl -fu liquidator-bot.service

    View past logs in less:

    sudo journalctl -eu liquidator-bot.service
tip
  • Always verify the paths and user permissions when setting up the service to avoid common issues.
  • Use sudo systemctl status liquidator-bot to check the status and troubleshoot any problems with the service.