Skip to main content

Get Redemption Queue

Overview​

In this guide, you will learn about the redemption queue and how it functions. You will also learn how to get redemption tickets using the AssetManager smart contract. Finally, you will learn how to calculate the total value and the number of lots to redeem.

Prerequisites​

Redemption Queue​

When a user mints FAssets, a redemption ticket is created and added to the redemption queue. This queue determines the order in which redemptions are fulfilled and assigns the corresponding agents to return the underlying asset (e.g., XRP) to the redeemers.

The redemption queue is a FIFO (First-In-First-Out) queue that is shared globally across all agents. It consists of ticket entries, where each ticket represents lots minted with a particular agent.

maxRedeemedTickets System Setting​

The maxRedeemedTickets system setting defines the maximum number of tickets that can be redeemed in a single request. This setting is used to prevent high gas consumption and ensure the fairness of the redemption process.

To get the maxRedeemedTickets setting, you can use the getSettings function from the AssetManager smart contract.

Fetch Redemption Queue Data​

Global Redemption Queue​

The redemptionQueue function returns the redemption queue in the form of an array of RedemptionTicketInfo structs.

Each RedemptionTicketInfo includes:

  • agentVault: address of the backing agent.
  • valueUBA: value in underlying base amount.
  • lots: number of lots.
  • createdAt: creation timestamp.

Agent's Redemption Queue​

The agentRedemptionQueue function returns the redemption queue for a specific agent in the form of an array of RedemptionTicketInfo structs.

How It Ties Together​

The redemptionQueue function provides the global ticket order, where each ticket is linked to a specific agent. The agent associated with each ticket must fulfill their part of the redemption. Once a ticket is consumed, it is removed from the queue, and the queue is updated accordingly.

Example​

The following example demonstrates how to get maxRedeemedTickets, the global redemption queue, and calculate the number of lots to redeem.

scripts/fassets/getRedemptionQueue.ts
// 1. Import the function that gets the AssetManager XRP contract
import { getAssetManagerFXRP } from "../utils/getters";

async function main() {
  // 2. Get the AssetManager contract
  const assetManager = await getAssetManagerFXRP();

  // 3. Get the settings
  const settings = await assetManager.getSettings();

  // 4. Get the max redeemed tickets
  const maxRedeemedTickets = settings.maxRedeemedTickets;

  // 5. Get the lot size
  const lotSizeAMG = settings.lotSizeAMG;

  // 6. Get the redemption queue
  const redemptionQueueResult = await assetManager.redemptionQueue(
    0,
    maxRedeemedTickets,
  );
  const redemptionQueue = redemptionQueueResult._queue;

  // 7. Sum all ticket values in the redemption queue
  const totalValueUBA = redemptionQueue.reduce((sum, ticket) => {
    return sum + BigInt(ticket.ticketValueUBA);
  }, BigInt(0));

  console.log(
    "\nTotal value in redemption queue (UBA):",
    totalValueUBA.toString(),
  );

  // 8. Calculate total lots in the redemption queue
  const totalLots = totalValueUBA / BigInt(lotSizeAMG);
  console.log("\nTotal lots in redemption queue:", totalLots.toString());
}

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

Code Explanation​

The script:

  1. Import the function that gets the AssetManager XRP contract.
  2. Get the AssetManager contract instance by calling the getAssetManagerFXRP function.
  3. Get the settings from the AssetManager contract.
  4. Get the maxRedeemedTickets value from the system settings (maximum number of tickets that can be redeemed in a single request). The actual number of tickets returned may be less than maxRedeemedTickets if the queue is shorter.
  5. Get the lot size value from the settings (minimum quantity required for minting FAssets).
  6. Get the redemption queue by calling the contract method redemptionQueue starting from 0 and up to maxRedeemedTickets. You can paginate over the queue.
  7. Sum all ticket values in the redemption queue to calculate the total value in UBA (Underlying Asset Base Amount)
  8. Calculate the total lots in the redemption queue by dividing the total value by the lot size.
info

The getFXRPAssetManager function is a utility function that is included in the Flare Hardhat Starter Kit. It is used to get the FXRP Asset Manager address from the Flare Contract Registry.

Run the Script​

To run the script, use the following command:

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

The script will output the redemption queue data for the FAssets system on the Coston2 network:

Total value in redemption queue (UBA): 4190000000

Total lots in redemption queue: 419

Summary​

The guide covers:

  • Redemption Queue Mechanics: How the queue works as a shared global system tracking redemption tickets.
  • maxRedeemedTickets Setting: Maximum number of tickets that can be redeemed in a single request.
  • Queue Access Methods: How to retrieve global and agent-specific queues using contract functions.
  • Practical Implementation: A TypeScript example showing how to get settings, retrieve the queue, and calculate total value and lots to redeem.
Next Steps

To continue your FAssets development journey, you can: