Skip to main content

List FAssets Agents

Overview​

In this guide, you will learn how to list FAssets agents using the AssetManager smart contract.

Prerequisites​

List FAssets Agents​

The AssetManager smart contract provides these functions to list FAssets agents:

  • getAllAgents: Returns all agents in the system, including both available and unavailable agents, with basic information.
  • getAvailableAgentsList: Returns only available agents (agents accepting new minting requests) with basic information.
  • getAvailableAgentsDetailedList: Returns only available agents with comprehensive details, including collateral ratios, fees, and vault status.

Function Parameters​

All of these functions take two parameters:

  • _start: First index to return from the agents list.
  • _end: End index to return from the agents list (exclusive).

And return two values:

  • _agents: Array of agent information structs.
  • _totalLength: Total number of agents in the system (used for pagination).
Index Parameters

All of these functions use array-like slicing:

  • start: Inclusive start index (0-based).
  • end: Exclusive end index.

For example, getAllAgents(0, 3) returns agents at indices 0, 1, and 2.

Example​

This example demonstrates how to use the getAvailableAgentsList function to list available agents in chunks. The chunking approach prevents RPC timeouts when dealing with many agents by fetching data in smaller, manageable batches.

scripts/fassets/listAgents.ts
import { getAssetManagerFXRP } from "../utils/getters";

/**
 * Script to list all available FAssets agents in chunks
 *
 * This script demonstrates how to iterate through all agents in the FAssets system
 * by fetching them in chunks to avoid overwhelming the RPC endpoint with large requests.
 *
 * Run with: yarn hardhat run scripts/fassets/listAgents.ts --network coston2
 */

async function main() {
  // 1. Get the FAssets FXRP asset manager contract instance
  const assetManager = await getAssetManagerFXRP();

  // 2. Define how many agents to fetch per request
  // Using smaller chunks (e.g., 3) helps avoid RPC timeout issues
  const chunkSize = 3;

  // 3. Fetch the first chunk and get the total count
  // The _totalLength property tells us how many agents exist in total
  console.log("Fetching first chunk with offset 0 and chunk size " + chunkSize);
  const firstChunk = await assetManager.getAvailableAgentsList(0, chunkSize);
  console.log(firstChunk._agents);

  const totalLength = Number(BigInt(firstChunk._totalLength).toString());
  console.log(`Total number of agents: ${totalLength}`);

  // 4. Iterate through remaining agents in chunks
  // The getAvailableAgentsDetailedList(start, end) function uses:
  // - start: inclusive start index (0-based)
  // - end: exclusive end index (like array slicing)
  // Example: (0, 3) returns agents at indices 0, 1, 2
  for (let offset = chunkSize; offset < totalLength; offset += chunkSize) {
    // Calculate end index, ensuring we don't exceed totalLength
    const endIndex = Math.min(offset + chunkSize, totalLength);
    console.log(
      `\n--- Fetching agents ${offset} to ${endIndex - 1} (end index ${endIndex} exclusive) ---`,
    );

    // Fetch the chunk of agents
    const agents = await assetManager.getAvailableAgentsList(offset, endIndex);
    console.log(agents._agents);
  }

  console.log(`\nCompleted processing all ${totalLength} agents`);
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

How the Code Works​

The script follows these steps:

  1. Get Asset Manager Contract: Retrieve the FAssets FXRP Asset Manager contract instance using the helper function getAssetManagerFXRP() from the Flare periphery contracts package.

  2. Define Chunk Size: Set chunkSize to 3, determining how many agents to fetch per request. Using smaller chunks helps avoid RPC timeout issues when dealing with many agents. You can adjust this value based on your network conditions and RPC provider limits.

  3. Fetch First Chunk: Call getAvailableAgentsList(0, chunkSize) which:

    • Returns the first three agents (indices 0, 1, 2).
    • Provides the _totalLength property showing the total number of agents in the system.

  4. Iterate Through Remaining Agents: Loop through the remaining agents in chunks:

    • Start from offset = chunkSize (3) and increment by chunkSize each iteration.
    • Calculate endIndex = Math.min(offset + chunkSize, totalLength) to ensure we do not exceed the total length.
    • Fetch each chunk using getAvailableAgentsList(offset, endIndex).
    • Display the agents in each chunk for processing or analysis.
info

A similar approach can be used to list all agents using the getAllAgents and getAvailableAgentsDetailedList functions.

Run the Script​

To run the script, use the following command:

yarn hardhat run scripts/fassets/listAgents.ts --network coston2

To use the script, replace coston2 with the network you are using. The script will output information about the available agents on the Coston2 network.

Summary​

This guide covered:

  • Agent List Functions: Three different methods to retrieve agent information with varying levels of detail.
  • Pagination Strategy: How to use chunking to retrieve large agent lists without overwhelming RPC endpoints efficiently.
  • Practical Implementation: A complete TypeScript example demonstrating agent list retrieval with proper pagination and error handling considerations.
Next Steps

To continue your FAssets development journey, you can: