Skip to main content
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.

Run an Agent

Agents are integral to FAssets system, facilitating the use of tokens from blockchains that lack smart contract capabilities with smart contracts on the Flare blockchain.

This guide includes:

  1. Setting up the FAssets CLI.
  2. Configuring access keys for interaction with the Songbird Testnet Coston and the test XRP Ledger network.
  3. Establishing an FAssets agent and providing collateral.
  4. Operating the agent to enable FAssets system users to convert (mint and redeem) assets between the testnet XRP Ledger and Songbird Testnet Coston.

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 Songbird Testnet Coston.

ERC20 Test Tokens​

TokenAddress
testUSDC0xd20D9284E8b43C60365BcA90662C67B5A0B91dd6
testUSDT0x18bd7bE80F76055aeB4F1575A99d0c4d7893B8b5
testETH0x17c3E6318cb45B4267998940d7D65BA95A32954F

FAssets System Contracts​

ContractAddressDescription
AgentOwnerRegistry0xDb6c11b8D074D4488f5fFd0129AA5F91C4f00fb6Manages agent whitelisting and allows setting and retrieving details such as work and management addresses, name, description, and icon.
FTestXRP0x5905Df703221d4Ea311E85edEa860734b2072C7dThe FAsset-wrapped TestXRP token, ready for use on Songbird Testnet Coston.

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).

Registration​

Install repository​

  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 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 (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 --user --agent MANAGEMENT_WALLET_ADDRESS --other -o secrets.json

  3. Start the whitelisting process 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. Ensure this wallet has enough CFLR tokens to cover gas fees for smart contract calls.

  5. Change the permissions for the secrets.json file:

    chmod 600 secrets.json

  6. Fill the native_rpc, xrp_rpc and indexer fields in the secrets.json file with the following values:

    // Songbird Testnet Coston
    "native_rpc": "AavSehMLhcgz3crQHH5YJ3Rt8GMQGdV9aViGilADXGnTcjij",
    "xrp_rpc": "4tg3AxysaZodxTqsCtcMnBdBIEkR6KDKGTdqBEA8g9MKq4bH",
    "indexer": "123456",

Whitelist 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 open beta.

  1. Find your agent owner address, which is the owner.management.address value in secrets.json.

  2. Use the FlareFAssetsBot Telegram channel, specifically designed for registration, and provide the necessary information, including your agent name and description and, optionally, a link to your icon.

  3. Enter the information and confirm it. The Telegram bot will inform you about the successful process.

  4. Wait for Flare support engineers to approve registrations and issue test assets such as 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​

  1. Navigate to the AgentOwnerRegistry contract on the Coston Explorer and open the Read Contract tab:

    AgentOwnerRegistry: 0xDb6c11b8D074D4488f5fFd0129AA5F91C4f00fb6

  2. Execute the isWhitelisted function with the value of owner.management.address from secrets.json. This function returns a boolean: true of the address is whitelisted or false if it is not.

Setup​

Configure Native Address​

Configuring the native address links your agent's work address to the management address and grants access.

  1. Navigate to the AgentOwnerRegistry contract on the Coston Explorer and open the Write Contract tab:

    AgentOwnerRegistry: 0xDb6c11b8D074D4488f5fFd0129AA5F91C4f00fb6

  2. Connect the 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 secrets.json.

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:

    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. 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 XRPL account by sending at least 100 testnet XRP using either one of the faucets:

  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.

    yarn agent-bot --fasset FTestXRP create tmp.agent-settings.json

Deposit Collateral​

To make your newly created agent public, it must hold enough collateral to mint one lot. This means its agent vault contract needs to be funded with the two collateral assets (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.

There are two options:

  • Deposit vault and pool collateral together.

  • Deposit vault and pool collateral separately.

Deposit Vault and Pool Collateral Together​

To deposit both vault and pool collateral together and let the tool calculate the minimum required collateral 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:

yarn agent-bot depositCollaterals AGENT_ADDRESS LOTS --fasset FTestXRP

Deposit Vault and Pool 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.

    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.

    yarn agent-bot buyPoolCollateral AGENT_ADDRESS CFLR_AMOUNT --fasset FTestXRP

Register 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:

    yarn agent-bot enter AGENT_ADDRESS --fasset FTestXRP
    warning

    To prevent failures, ensure that your agent owner's Flare account has completed the whitelisting process via the FlareFAssetsBot Telegram channel.

  2. If you deposited enough collateral, you should see that your agent has at least one lot available by running the command.

    yarn user-bot agents --fasset FTestXRP

If you don't have available lots, check if the vault and pool collaterals are enough.

Run 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:

yarn run-agent

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

Maximize agent uptime​

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

  2. Modify the following variables in agent-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 agent-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 agent-bot

    To stop the service:

    sudo systemctl stop agent-bot

  6. Enable auto-start on boot:

    sudo systemctl enable agent-bot

  7. View service logs:

    Follow the console output live:

    sudo journalctl -fu agent-bot.service

    View past logs in less:

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

Verify contracts​

Ensuring the security and transparency of FAssets involves verifying the CollateralPool and CollateralPoolToken smart contracts on a block explorer. The following steps will guide you through the verification process on the Coston Explorer.

  1. Get the CollateralPool Contract Address:

    Execute the FAssets system information command to determine your CollateralPool contract address.

    yarn agent-bot info AGENT_ADDRESS --fasset FTestXRP

    Locate and copy the address from the Agent collateral pool field:

    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: <inf>  (minCR=1.4, mintingCR=1.6)
       Pool CR: <inf>  (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 fassets Repository:

    Clone the fassets repository and switch to the open_beta branch:

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

  3. Install dependencies and build the project:

    yarn && yarn c

  4. Verify the Contracts:

    Run the following command, using the collateral pool address obtained in step 1 as AGENT_POOL_ADDRESS:

    yarn verify-collateral-pool-coston AGENT_POOL_ADDRESS

    The verification process takes a few minutes. You should see an output indicating that the CollateralPool and CollateralPoolToken contracts have been verified:

    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 address on the Coston Explorer and check that the Code tab displays a green checkmark next to the verified contracts.