Skip to content

Commit c049ad6

Browse files
fasskofassko
committed
feat(docs): add redemption queue guide
1 parent d06cf91 commit c049ad6

File tree

4 files changed

+166
-4
lines changed

4 files changed

+166
-4
lines changed

‎docs/fassets/developer-guides/11-fassets-redemption-queue.mdx‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
---
2+
title: Get Redemption Queue
3+
tags: [intermediate, fassets]
4+
slug: fassets-redemption-queue
5+
description: Learn how to get the redemption queue
6+
keywords: [fassets, flare-network]
7+
sidebar_position: 11
8+
---
9+
10+
import CodeBlock from "@theme/CodeBlock";
11+
import FAssetsGetRedemptionQueue from "!!raw-loader!/examples/developer-hub-javascript/fassets_get_redemption_queue.ts";
12+
import GetFXRPAssetManager from "./_get_fxrp_asset_manager.mdx";
13+
14+
## Overview
15+
16+
In this guide, you will learn about the redemption queue and how it functions.
17+
You will also learn how to get redemption tickets using the [IAssetManager](/fassets/reference/IAssetManager) smart contract.
18+
Finally, you will learn how to calculate the total value and the number of lots to redeem.
19+
20+
## Prerequisites
21+
22+
- Basic understanding of the [FAssets system](/fassets/overview).
23+
- [Flare Network Periphery Contracts](https://www.npmjs.com/package/@flarenetwork/flare-periphery-contracts) package.
24+
25+
## Redemption Queue
26+
27+
When a user mints FAssets, a [redemption ticket](/fassets/reference/IAssetManagerEvents#redemptionticketcreated) is created and added to the **redemption queue**.
28+
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.
29+
30+
The redemption queue is a **FIFO (First-In-First-Out)** queue that is shared globally across all agents.
31+
It consists of ticket entries, where each ticket represents lots minted with a particular agent.
32+
33+
## `maxRedeemedTickets` System Setting
34+
35+
The `maxRedeemedTickets` system setting defines the maximum number of tickets that can be redeemed in a single request.
36+
This setting is used to prevent high gas consumption and ensure the fairness of the redemption process.
37+
38+
To get the `maxRedeemedTickets` setting, you can use the [getSettings](/fassets/reference/IAssetManager#getsettings) function from the [IAssetManager](/fassets/reference/IAssetManager) smart contract.
39+
40+
## Fetch Redemption Queue Data
41+
42+
### Global Redemption Queue
43+
44+
The [`redemptionQueue`](/fassets/reference/IAssetManager#redemptionqueue) function returns the redemption queue in the form of an array of [`RedemptionTicketInfo`](https://github.com/flare-foundation/fassets/blob/main/contracts/userInterfaces/data/RedemptionTicketInfo.sol) structs.
45+
46+
Each `RedemptionTicketInfo` includes:
47+
48+
- `agentVault`: address of the backing agent.
49+
- `valueUBA`: value in underlying base amount.
50+
- `lots`: number of lots.
51+
- `createdAt`: creation timestamp.
52+
53+
### Agent's Redemption Queue
54+
55+
The [`agentRedemptionQueue`](/fassets/reference/IAssetManager#agentredemptionqueue) function returns the redemption queue for a specific agent in the form of an array of [`RedemptionTicketInfo`](https://github.com/flare-foundation/fassets/blob/main/contracts/userInterfaces/data/RedemptionTicketInfo.sol) structs.
56+
57+
## How It Ties Together
58+
59+
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.
60+
Once a ticket is consumed, it is removed from the queue, and the queue is updated accordingly.
61+
62+
## Example
63+
64+
The following example demonstrates how to get `maxRedeemedTickets`, the global redemption queue, and calculate the number of lots to redeem.
65+
66+
<CodeBlock language="typescript" title="scripts/fassets/getRedemptionQueue.ts">
67+
{FAssetsGetRedemptionQueue}
68+
</CodeBlock>
69+
70+
### Code Explanation
71+
72+
The script:
73+
74+
1. Import the function that gets the AssetManager XRP contract.
75+
2. Get the `AssetManager` contract instance by calling the `getAssetManagerFXRP` function.
76+
3. Get the settings from the AssetManager contract.
77+
4. Get the `maxRedeemedTickets` value from the system settings (maximum number of tickets that can be redeemed in a single request).
78+
The actual number of tickets returned may be less than `maxRedeemedTickets` if the queue is shorter.
79+
5. Get the lot size value from the settings (minimum quantity required for minting FAssets).
80+
6. Get the redemption queue by calling the contract method `redemptionQueue` starting from `0` and up to `maxRedeemedTickets`.
81+
You can paginate over the queue.
82+
7. Sum all ticket values in the redemption queue to calculate the total value in UBA (Underlying Asset Base Amount)
83+
8. Calculate the total lots in the redemption queue by dividing the total value by the lot size.
84+
85+
<GetFXRPAssetManager />
86+
87+
### Run the Script
88+
89+
To run the script, use the following command:
90+
91+
```bash
92+
yarn hardhat run scripts/fassets/getRedemptionQueue.ts --network coston2
93+
```
94+
95+
The script will output the redemption queue data for the FAssets system on the [Coston2](/network/overview) network:
96+
97+
```bash
98+
Total value in redemption queue (UBA): 4190000000
99+
100+
Total lots in redemption queue: 419
101+
```
102+
103+
## Summary
104+
105+
The guide covers:
106+
107+
- **Redemption Queue Mechanics**: How the queue works as a shared global system tracking redemption tickets.
108+
- `maxRedeemedTickets` **Setting**: Maximum number of tickets that can be redeemed in a single request.
109+
- **Queue Access Methods**: How to retrieve global and agent-specific queues using contract functions.
110+
- **Practical Implementation**: A TypeScript example showing how to get settings, retrieve the queue, and calculate total value and lots to redeem.
111+
112+
:::tip Next Steps
113+
To continue your FAssets development journey, you can:
114+
115+
- Learn how to [mint FXRP](/fassets/developer-guides/fassets-mint)
116+
- Understand how to [redeem FXRP](/fassets/developer-guides/fassets-redeem)
117+
- Explore [FAssets system settings](/fassets/operational-parameters)
118+
:::

‎docs/fassets/developer-guides/2-fassets-fxrp-address.mdx‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ import CodeBlock from "@theme/CodeBlock";
1111
import Remix from "@site/src/components/remix";
1212
import FAssetsGetFxrpScript from "!!raw-loader!/examples/developer-hub-javascript/fassets_get_fxrp.ts";
1313
import RedemptionProcessPrerequisites from "./_redemption_process_prerequisites.mdx";
14+
import GetFXRPAssetManager from "./_get_fxrp_asset_manager.mdx";
1415

1516
## Overview
1617

@@ -54,10 +55,7 @@ The script:
5455
2. Calls the [`fAsset`](/fassets/reference/IAssetManager#fasset) function to get the FXRP token address.
5556
3. Logs the address to the console.
5657

57-
:::info
58-
The `getFXRPAssetManagerAddress` function is a utility function that is included in the [Flare Hardhat Starter Kit](/network/guides/hardhat-foundry-starter-kit).
59-
It is used to get the FXRP Asset Manager address from the Flare Contract Registry.
60-
:::
58+
<GetFXRPAssetManager />
6159

6260
### Run the Script
6361

‎docs/fassets/developer-guides/_get_fxrp_asset_manager.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
:::info
2+
The `getFXRPAssetManager` function is a utility function that is included in the [Flare Hardhat Starter Kit](/network/guides/hardhat-foundry-starter-kit).
3+
It is used to get the FXRP Asset Manager address from the Flare Contract Registry.
4+
:::

‎examples/developer-hub-javascript/fassets_get_redemption_queue.ts‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
// 1. Import the function that gets the AssetManager XRP contract
2+
import { getAssetManagerFXRP } from "../utils/getters";
3+
4+
async function main() {
5+
// 2. Get the AssetManager contract
6+
const assetManager = await getAssetManagerFXRP();
7+
8+
// 3. Get the settings
9+
const settings = await assetManager.getSettings();
10+
11+
// 4. Get the max redeemed tickets
12+
const maxRedeemedTickets = settings.maxRedeemedTickets;
13+
14+
// 5. Get the lot size
15+
const lotSizeAMG = settings.lotSizeAMG;
16+
17+
// 6. Get the redemption queue
18+
const redemptionQueueResult = await assetManager.redemptionQueue(
19+
0,
20+
maxRedeemedTickets,
21+
);
22+
const redemptionQueue = redemptionQueueResult._queue;
23+
24+
// 7. Sum all ticket values in the redemption queue
25+
const totalValueUBA = redemptionQueue.reduce((sum, ticket) => {
26+
return sum + BigInt(ticket.ticketValueUBA);
27+
}, BigInt(0));
28+
29+
console.log(
30+
"\nTotal value in redemption queue (UBA):",
31+
totalValueUBA.toString(),
32+
);
33+
34+
// 8. Calculate total lots in the redemption queue
35+
const totalLots = totalValueUBA / BigInt(lotSizeAMG);
36+
console.log("\nTotal lots in redemption queue:", totalLots.toString());
37+
}
38+
39+
main().catch((error) => {
40+
console.error(error);
41+
process.exitCode = 1;
42+
});

0 commit comments

Comments
 (0)