feat(docs): add guide for listing FAssets agents and update IAssetManager reference

Author: fassko

docs/fassets/developer-guides.mdx

@@ -102,11 +102,17 @@ Guides for reading and working with agent data.
 
 <DocCardList
   items={[
+    {
+      type: "link",
+      label: "List FAssets Agents",
+      href: "/fassets/developer-guides/fassets-list-agents",
+      docId: "fassets/developer-guides/fassets-list-agents",
+    },
     {
       type: "link",
       label: "Read FAssets Agent Details",
       href: "/fassets/developer-guides/fassets-agent-details",
       docId: "fassets/developer-guides/fassets-agent-details",
-    },
+    }
   ]}
 />

docs/fassets/developer-guides/fassets-list-agents.mdx

@@ -0,0 +1,107 @@
+---
+title: List FAssets Agents
+tags: [intermediate, fassets]
+slug: fassets-list-agents
+description: Learn how to get a list of FAssets agents
+keywords: [fassets, flare-network]
+---
+
+import CodeBlock from "@theme/CodeBlock";
+import FAssetsListAgents from "!!raw-loader!/examples/developer-hub-javascript/fassets_list_agents.ts";
+
+## Overview
+
+In this guide, you will learn how to list FAssets agents using the [AssetManager](/fassets/reference/IAssetManager) smart contract.
+
+## Prerequisites
+
+- Basic understanding of the [FAssets system](/fassets/overview).
+- [Flare Network Periphery Contracts](https://www.npmjs.com/package/@flarenetwork/flare-periphery-contracts) package.
+
+## List FAssets Agents
+
+The [AssetManager](/fassets/reference/IAssetManager) smart contract provides these functions to list FAssets agents:
+
+- [`getAllAgents`](/fassets/reference/IAssetManager#getallagents): Returns all agents in the system, including both available and unavailable agents, with basic information.
+- [`getAvailableAgentsList`](/fassets/reference/IAssetManager#getavailableagentslist): Returns only available agents (agents accepting new minting requests) with basic information.
+- [`getAvailableAgentsDetailedList`](/fassets/reference/IAssetManager#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 structures.
+- `_totalLength`: Total number of agents in the system (used for pagination).
+
+:::tip 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`](/fassets/reference/IAssetManager#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.
+
+<CodeBlock language="typescript" title="scripts/fassets/listAgents.ts">
+  {FAssetsListAgents}
+</CodeBlock>
+
+### 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`](/fassets/reference/IAssetManager#getallagents) and [`getAvailableAgentsDetailedList`](/fassets/reference/IAssetManager#getavailableagentsdetailedlist) functions.
+:::
+
+### Run the Script
+
+To run the script, use the following command:
+
+```bash
+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/overview) 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.
+
+:::tip Next Steps
+To continue your FAssets development journey, you can:
+
+- Learn how to [mint FXRP](/fassets/developer-guides/fassets-mint)
+- Understand how to [redeem FXRP](/fassets/developer-guides/fassets-redeem)
+- Explore [FAssets system settings](/fassets/operational-parameters)
+ :::

docs/fassets/reference/IAssetManager.mdx

@@ -57,11 +57,11 @@ Returns the collateral reservation fee amount.
 
 Parameters:
 
-- `_lots`: The number of lots for which to reserve collateral
+- `_lots`: The number of lots for which to reserve collateral.
 
 Returns:
 
-- `_reservationFeeNATWei`: The amount of reservation fee in NAT wei
+- `_reservationFeeNATWei`: The amount of reservation fee in NAT wei.
 
 ```solidity
 function collateralReservationFee(
@@ -76,7 +76,7 @@ Note: once the minting is executed or defaulted, the collateral reservation is d
 
 Parameters:
 
-- `_collateralReservationId`: The collateral reservation ID, as used for executing or defaulting the minting
+- `_collateralReservationId`: The collateral reservation ID, as used for executing or defaulting the minting.
 
 ```solidity
 function collateralReservationInfo(uint256 _collateralReservationId)
@@ -90,7 +90,7 @@ Returns the FAsset token contract (ERC-20) that is managed by this asset manager
 
 Returns:
 
-- `IERC20`: The address of the FAsset token contract
+- `IERC20`: The address of the FAsset token contract.
 
 ```solidity
 function fAsset()
@@ -100,19 +100,39 @@ function fAsset()
 
 ## Agents
 
+## `getAllAgents`
+
+Returns the list of all agents.
+
+Parameters:
+
+- `_start`: First index to return from the available agent's list.
+- `_end`: End index (one above last) to return from the available agent's list.
+
+Returns:
+
+- `_agents`: The list of all agents.
+- `_totalLength`: The total length of the all agents list.
+
+```solidity
+function getAllAgents(uint256 _start, uint256 _end)
+    external view
+    returns (address[] memory _agents, uint256 _totalLength);
+```
+
 ### `getAvailableAgentsList`
 
 Returns the list of available agents.
 
 Parameters:
 
-- `_start`: First index to return from the available agent's list
-- `_end`: End index (one above last) to return from the available agent's list
+- `_start`: First index to return from the available agent's list.
+- `_end`: End index (one above last) to return from the available agent's list.
 
 Returns:
 
-- `_agents`: The list of available agents
-- `_totalLength`: The total length of the available agents list
+- `_agents`: The list of available agents.
+- `_totalLength`: The total length of the available agents list.
 
 ```solidity
 function getAvailableAgentsList(uint256 _start, uint256 _end)
@@ -126,13 +146,13 @@ Returns the list of available agents with extra information about agents like fe
 
 Parameters:
 
-- `_start`: First index to return from the available agent's list
-- `_end`: End index (one above last) to return from the available agent's list
+- `_start`: First index to return from the available agent's list.
+- `_end`: End index (one above last) to return from the available agent's list.
 
 Returns:
 
-- `_agents`: The list of available agents with extra information
-- `_totalLength`: The total length of the available agents list
+- `_agents`: The list of available agents with extra information.
+- `_totalLength`: The total length of the available agents list.
 
 ```solidity
 function getAvailableAgentsDetailedList(uint256 _start, uint256 _end)
@@ -148,13 +168,13 @@ Returns the redemption queue in the form of an array of [`RedemptionTicketInfo`]
 
 Parameters:
 
-- `_firstRedemptionTicketId`: the ticket id to start listing from; if `0`, starts from the beginning
-- `_pageSize`: the maximum number of redemption tickets to return
+- `_firstRedemptionTicketId`: the ticket id to start listing from; if `0`, starts from the beginning.
+- `_pageSize`: the maximum number of redemption tickets to return.
 
 Returns:
 
-- `_queue`: the (part of) the redemption queue; maximum length is \_pageSize
-- `_nextRedemptionTicketId`: works as a cursor - if the `_pageSize` is reached and there are more tickets, it is the first ticket id not returned; if the end is reached, it is 0
+- `_queue`: the (part of) the redemption queue; maximum length is \_pageSize.
+- `_nextRedemptionTicketId`: works as a cursor - if the `_pageSize` is reached and there are more tickets, it is the first ticket id not returned; if the end is reached, it is 0.
 
 ```solidity
 function redemptionQueue(
@@ -170,14 +190,14 @@ Returns the redemption queue for specific agent in the form of an array of [`Red
 
 Parameters:
 
-- `_agentVault`: the agent vault address of the queried agent
-- `_firstRedemptionTicketId`: the ticket id to start listing from; if `0`, starts from the beginning
-- `_pageSize`: the maximum number of redemption tickets to return
+- `_agentVault`: the agent vault address of the queried agent.
+- `_firstRedemptionTicketId`: the ticket id to start listing from; if `0`, starts from the beginning.
+- `_pageSize`: the maximum number of redemption tickets to return.
 
 Returns:
 
-- `_queue`: the (part of) the redemption queue; maximum length is \_pageSize
-- `_nextRedemptionTicketId`: works as a cursor - if the` _pageSize` is reached and there are more tickets, it is the first ticket id not returned; if the end is reached, it is 0
+- `_queue`: the (part of) the redemption queue; maximum length is \_pageSize.
+- `_nextRedemptionTicketId`: works as a cursor - if the` _pageSize` is reached and there are more tickets, it is the first ticket id not returned; if the end is reached, it is 0.
 
 ```solidity
 function agentRedemptionQueue(
@@ -197,10 +217,10 @@ Before paying underlying assets for minting, the minter must reserve collateral
 
 Parameters:
 
-- `_agentVault`: Agent vault address
-- `_lots`: Number of lots for which to reserve collateral
-- `_maxMintingFeeBIPS`: Maximum minting fee (BIPS) that can be charged by the agent - best practice is to copy the current agent's published fee; used to prevent agent from front-running reservation request and increasing fee
-- `_executor`: Account that is allowed to execute minting (besides minter and agent)
+- `_agentVault`: Agent vault address.
+- `_lots`: Number of lots for which to reserve collateral.
+- `_maxMintingFeeBIPS`: Maximum minting fee (BIPS) that can be charged by the agent - best practice is to copy the current agent's published fee; used to prevent agent from front-running reservation request and increasing fee.
+- `_executor`: Account that is allowed to execute minting (besides minter and agent).
 
 ```solidity
 function reserveCollateral(
@@ -219,14 +239,14 @@ After obtaining proof of underlying payment, the minter calls this method to fin
 
 Note: May only be called by:
 
-- The minter (creator of the collateral reservation request)
-- The executor appointed by the minter
-- The agent owner (owner of the agent vault in the collateral reservation)
+- The minter (creator of the collateral reservation request).
+- The executor appointed by the minter.
+- The agent owner (owner of the agent vault in the collateral reservation).
 
 Parameters:
 
-- `_payment`: Proof of the underlying payment (must contain exact `value + fee` amount and correct payment reference)
-- `_collateralReservationId`: Collateral reservation ID
+- `_payment`: Proof of the underlying payment (must contain exact `value + fee` amount and correct payment reference).
+- `_collateralReservationId`: Collateral reservation ID.
 
 ```solidity
 function executeMinting(

examples/developer-hub-javascript/fassets_list_agents.ts

@@ -0,0 +1,50 @@
+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;
+});