Skip to content

Commit d7dfb3a

Browse files
fasskofassko
committed
feat(docs): add guides for redeeming and withdrawing assets from Firelight vault
1 parent 70cd311 commit d7dfb3a

File tree

4 files changed

+526
-0
lines changed

4 files changed

+526
-0
lines changed

‎docs/fassets/firelight/redeem.mdx‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
---
2+
title: Redeem Assets from Firelight Vault
3+
tags: [intermediate, fassets]
4+
slug: redeem
5+
description: Learn how to redeem assets from a Firelight vault
6+
keywords: [fassets, flare-network, fxrp, firelight, vault]
7+
sidebar_position: 5
8+
---
9+
10+
import CodeBlock from "@theme/CodeBlock";
11+
import FirelightRedeem from "!!raw-loader!/examples/developer-hub-javascript/firevault-redeem.ts";
12+
13+
## Overview
14+
15+
This guide demonstrates how to create a redemption request from a Firelight vault.
16+
The Firelight vault implements the [ERC-4626](https://eips.ethereum.org/EIPS/eip-4626) standard and uses a [period-based logic](https://docs.firelight.finance/technical-documents#period-based-logic) for redemptions.
17+
18+
Redeeming shares burns vault shares and allows assets to be withdrawn. Redemptions create a withdrawal request that is processed after the current period ends.
19+
The assets are not immediately transferred; they must be claimed once the period has ended.
20+
21+
## Prerequisites
22+
23+
- [Flare Hardhat Starter Kit](/network/guides/hardhat-foundry-starter-kit).
24+
- [Flare Network Periphery Contracts](https://www.npmjs.com/package/@flarenetwork/flare-periphery-contracts).
25+
- Understanding of [FAssets](/fassets/overview).
26+
- Vault shares in the Firelight vault to redeem.
27+
28+
## Firelight Vault Redeem Script
29+
30+
The following script demonstrates how to create a redemption request from the Firelight vault:
31+
32+
<CodeBlock language="typescript" title="scripts/firelight/redeem.ts">
33+
{FirelightRedeem}
34+
</CodeBlock>
35+
36+
## Script Breakdown
37+
38+
### 1. Script Setup
39+
40+
The script starts by defining constants and importing the required contract interfaces:
41+
42+
- `FIRELIGHT_VAULT_ADDRESS`: The address of the Firelight vault contract on the [Flare Testnet Coston2 network](/network/overview).
43+
- `SHARES_TO_REDEEM`: The number of shares to redeem (default: 1 share).
44+
- `IFirelightVault`: The interface for interacting with the Firelight vault contract.
45+
Taken from the Firelight GitHub [repository](https://github.com/firelight-protocol/firelight-core/blob/main/contracts/FirelightVault.sol).
46+
- `IERC20`: Standard [ERC-20](https://eips.ethereum.org/EIPS/eip-20) interface for token interactions.
47+
48+
### 2. Get Asset Information
49+
50+
The script retrieves the underlying asset information to format amounts and calculate the redemption amount from the vault:
51+
52+
- **Asset address**: The token address that the vault holds (e.g., FXRP).
53+
- **Asset symbol**: The token symbol for display purposes.
54+
- **Asset decimals**: The number of decimals used by the token.
55+
56+
### 3. Calculate Shares to Redeem
57+
58+
The script converts the desired number of shares to redeem into the correct units:
59+
60+
```typescript
61+
const sharesToRedeem = SHARES_TO_REDEEM * 10 ** assetDecimalsNum;
62+
```
63+
64+
### 4. Check Maximum Redemption Capacity
65+
66+
Before redeeming, the script checks if the requested amount exceeds the maximum allowed:
67+
68+
```typescript
69+
const maxRedeem = await vault.maxRedeem(account);
70+
```
71+
72+
The `maxRedeem` function returns the maximum number of shares that the specified account can redeem.
73+
If the requested amount exceeds the maximum, the script exits with an error to prevent a failed transaction.
74+
75+
### 5. Check User Balance
76+
77+
The script displays the user's current vault share balance and validates that they have sufficient shares:
78+
79+
```typescript
80+
const userBalance = await vault.balanceOf(account);
81+
```
82+
83+
The script then validates that the user has sufficient shares to cover the redemption request.
84+
This validation ensures the redemption will succeed before attempting the transaction.
85+
86+
### 6. Create Redemption Request
87+
88+
Finally, the script creates a redemption request:
89+
90+
```typescript
91+
const redeemTx = await vault.redeem(sharesToRedeem, account, account, {
92+
from: account,
93+
});
94+
```
95+
96+
The `redeem` function:
97+
98+
- Takes the number of shares to redeem (`sharesToRedeem`).
99+
- Specifies the owner address (first `account` parameter).
100+
- Specifies the recipient address (second `account` parameter).
101+
- Creates a redemption request for the current period.
102+
- Does not immediately transfer assets; the redemption must be claimed after the period ends.
103+
104+
## Understanding Redemption Process
105+
106+
The Firelight vault uses a period-based redemption system:
107+
108+
1. **Redemption Request**: When you call `redeem`, it creates a redemption request associated with the current period.
109+
2. **Period End**: The redemption is processed after the current period ends.
110+
3. **Claim Redemption**: Once the period has ended, you must claim the redemption to receive your assets.
111+
112+
This delayed redemption mechanism is part of the vault's [period-based logic](https://docs.firelight.finance/technical-documents#period-based-logic) and helps manage liquidity and ensure fair distribution of rewards.
113+
114+
## Running the Script
115+
116+
To run the Firelight vault redeem script:
117+
118+
1. Ensure you have the [Flare Hardhat Starter Kit](/network/guides/hardhat-foundry-starter-kit) set up.
119+
2. Update the `FIRELIGHT_VAULT_ADDRESS` constant with the correct vault address for your network.
120+
3. Adjust the `SHARES_TO_REDEEM` constant to the desired number of shares.
121+
4. Ensure your account has sufficient vault shares to cover the redemption.
122+
5. Run the script using Hardhat:
123+
124+
```bash
125+
npx hardhat run scripts/firelight/redeem.ts --network coston2
126+
```
127+
128+
## Output
129+
130+
The script outputs the following information:
131+
132+
```bash
133+
=== Redeem (ERC-4626) ===
134+
Sender: 0x0d09ff7630588E05E2449aBD3dDD1D8d146bc5c2
135+
Vault: 0x91Bfe6A68aB035DFebb6A770FFfB748C03C0E40B
136+
Asset: 0x0b6A3645c240605887a5532109323A3E12273dc7 (FTestXRP, decimals=6)
137+
Shares to redeem: 1000000 (= 1 share)
138+
Max redeem: 1000061
139+
User balance (shares): 1000061 (= 1.000061 shares)
140+
Redeem tx: 0x3f1bd8c766852d3b835bcde79f6d8e20afeeb227d737e0ed28d057dc0e6b2ba9
141+
```
142+
143+
## Difference Between Redeem and Withdraw
144+
145+
The Firelight vault provides two ways to remove assets:
146+
147+
- **`redeem`**: You specify the number of shares to redeem, and the vault calculates how many assets you'll receive.
148+
- **`withdraw`**: You specify the amount of assets to withdraw, and the vault calculates how many shares need to be burned based on the current exchange rate.
149+
150+
Both functions follow the [ERC-4626](https://eips.ethereum.org/EIPS/eip-4626) standard and create withdrawal requests that must be claimed after the period ends.
151+
152+
## Summary
153+
154+
In this guide, you learned how to create a redemption request from a Firelight vault by specifying the number of shares to redeem.
155+
Remember that redemptions are delayed and must be claimed after the current period ends.
156+
157+
:::tip[What's next]
158+
159+
To continue your Firelight development journey, you can:
160+
161+
- Learn how to [get Firelight vault status](/fassets/firelight/status) to monitor your redemption requests.
162+
- Learn how to [withdraw assets from a Firelight vault](/fassets/firelight/withdraw) by specifying the amount of assets.
163+
- Learn how to [deposit assets into a Firelight vault](/fassets/firelight/deposit).
164+
- Learn how to [mint Firelight vault shares](/fassets/firelight/mint) by specifying the number of shares.
165+
- Explore the [FAssets system overview](/fassets/overview) to understand the broader ecosystem.
166+
167+
:::

‎docs/fassets/firelight/withdraw.mdx‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
---
2+
title: Withdraw Assets from Firelight Vault
3+
tags: [intermediate, fassets]
4+
slug: withdraw
5+
description: Learn how to withdraw assets from a Firelight vault
6+
keywords: [fassets, flare-network, fxrp, firelight, vault]
7+
sidebar_position: 4
8+
---
9+
10+
import CodeBlock from "@theme/CodeBlock";
11+
import FirelightWithdraw from "!!raw-loader!/examples/developer-hub-javascript/firevault-withdraw.ts";
12+
13+
## Overview
14+
15+
This guide demonstrates how to create a withdrawal request from a Firelight vault.
16+
The Firelight vault implements the [ERC-4626](https://eips.ethereum.org/EIPS/eip-4626) standard and uses a [period-based logic](https://docs.firelight.finance/technical-documents#period-based-logic) for withdrawals.
17+
18+
Withdrawing assets creates a withdrawal request that is processed after the current period ends.
19+
The assets are not immediately transferred; they must be claimed once the period has ended.
20+
21+
## Prerequisites
22+
23+
- [Flare Hardhat Starter Kit](/network/guides/hardhat-foundry-starter-kit).
24+
- [Flare Network Periphery Contracts](https://www.npmjs.com/package/@flarenetwork/flare-periphery-contracts).
25+
- Understanding of [FAssets](/fassets/overview).
26+
- Vault shares in the Firelight vault to withdraw.
27+
28+
## Firelight Vault Withdraw Script
29+
30+
The following script demonstrates how to create a withdrawal request from the Firelight vault:
31+
32+
<CodeBlock language="typescript" title="scripts/firelight/withdraw.ts">
33+
{FirelightWithdraw}
34+
</CodeBlock>
35+
36+
## Script Breakdown
37+
38+
### 1. Script Setup
39+
40+
The script starts by defining constants and importing the required contract interfaces:
41+
42+
- `FIRELIGHT_VAULT_ADDRESS`: The address of the Firelight vault contract on the [Flare Testnet Coston2 network](/network/overview).
43+
- `WITHDRAW_AMOUNT`: The number of tokens to withdraw (default: 1 token).
44+
- `IFirelightVault`: The interface for interacting with the Firelight vault contract.
45+
Taken from the Firelight GitHub [repository](https://github.com/firelight-protocol/firelight-core/blob/main/contracts/FirelightVault.sol).
46+
- `IERC20`: Standard [ERC-20](https://eips.ethereum.org/EIPS/eip-20) interface for token interactions.
47+
48+
### 2. Get Asset Information
49+
50+
The script retrieves the underlying asset information to format amounts and calculate the withdrawal amount from the vault:
51+
52+
- **Asset address**: The token address that the vault holds (e.g., FXRP).
53+
- **Asset symbol**: The token symbol for display purposes.
54+
- **Asset decimals**: The number of decimals used by the token.
55+
56+
### 3. Calculate Withdrawal Amount
57+
58+
The script converts the desired withdrawal amount into the correct units:
59+
60+
```typescript
61+
const amount = WITHDRAW_AMOUNT * 10 ** assetDecimalsNum;
62+
```
63+
64+
### 4. Check Maximum Withdrawal Capacity
65+
66+
Before withdrawing, the script checks if the requested amount exceeds the maximum allowed:
67+
68+
```typescript
69+
const maxWithdraw = await vault.maxWithdraw(account);
70+
```
71+
72+
The `maxWithdraw` function returns the maximum amount of assets that the specified account can withdraw.
73+
74+
If the requested amount exceeds the maximum, the script exits with an error to prevent a failed transaction.
75+
76+
### 5. Check User Balance and Calculate Shares Needed
77+
78+
The script displays the user's current vault share balance and calculates how many shares are needed for the withdrawal:
79+
80+
```typescript
81+
const userBalance = await vault.balanceOf(account);
82+
const sharesNeeded = await vault.previewWithdraw(amount);
83+
```
84+
85+
The `previewWithdraw` function is part of the [ERC-4626](https://eips.ethereum.org/EIPS/eip-4626) standard and returns the number of shares required to withdraw a specific amount of assets, accounting for the current exchange rate between assets and shares.
86+
87+
The script then validates that the user has sufficient shares.
88+
This validation ensures the withdrawal will succeed before attempting the transaction.
89+
90+
### 6. Create Withdrawal Request
91+
92+
Finally, the script creates a withdrawal request:
93+
94+
```typescript
95+
const withdrawTx = await vault.withdraw(amount, account, account, {
96+
from: account,
97+
});
98+
```
99+
100+
The `withdraw` function:
101+
102+
- Takes the amount of assets to withdraw (`amount`).
103+
- Specifies the owner address (first `account` parameter).
104+
- Specifies the recipient address (second `account` parameter).
105+
- Creates a withdrawal request for the current period.
106+
- Does not immediately transfer assets; the withdrawal must be claimed after the period ends.
107+
108+
## Understanding Withdrawal Process
109+
110+
The Firelight vault uses a period-based withdrawal system:
111+
112+
1. **Withdrawal Request**: When you call `withdraw`, it creates a withdrawal request associated with the current period.
113+
2. **Period End**: The withdrawal is processed after the current period ends.
114+
3. **Claim Withdrawal**: Once the period has ended, you must claim the withdrawal to receive your assets.
115+
116+
This delayed withdrawal mechanism is part of the vault's [period-based logic](https://docs.firelight.finance/technical-documents#period-based-logic) and helps manage liquidity and ensure fair distribution of rewards.
117+
118+
## Running the Script
119+
120+
To run the Firelight vault withdraw script:
121+
122+
1. Ensure you have the [Flare Hardhat Starter Kit](/network/guides/hardhat-foundry-starter-kit) set up.
123+
2. Update the `FIRELIGHT_VAULT_ADDRESS` constant with the correct vault address for your network.
124+
3. Adjust the `WITHDRAW_AMOUNT` constant to the desired number of tokens.
125+
4. Ensure your account has sufficient vault shares to cover the withdrawal.
126+
5. Run the script using Hardhat:
127+
128+
```bash
129+
npx hardhat run scripts/firelight/withdraw.ts --network coston2
130+
```
131+
132+
## Output
133+
134+
The script outputs the following information:
135+
136+
```bash
137+
=== Withdraw (ERC-4626) ===
138+
Sender: 0x0d09ff7630588E05E2449aBD3dDD1D8d146bc5c2
139+
Vault: 0x91Bfe6A68aB035DFebb6A770FFfB748C03C0E40B
140+
Asset: 0x0b6A3645c240605887a5532109323A3E12273dc7 (FTestXRP, decimals=6)
141+
Withdraw amount: 1000000 (= 1 FTestXRP)
142+
Max withdraw: 2000061
143+
User balance (shares): 2000061 (= 2.000061 shares)
144+
Withdraw tx: 0x23d8f34b582ef9935d3e3686a15e7fff34417ac01f68f7f928b14e2b4ef10ba9
145+
```
146+
147+
## Difference Between Withdraw and Redeem
148+
149+
The Firelight vault provides two ways to remove assets:
150+
151+
- **`withdraw`**: You specify the amount of assets to withdraw, and the vault calculates how many shares need to be burned based on the current exchange rate.
152+
- **`redeem`**: You specify the number of shares to redeem, and the vault calculates how many assets you'll receive.
153+
154+
Both functions follow the [ERC-4626](https://eips.ethereum.org/EIPS/eip-4626) standard and create withdrawal requests that must be claimed after the period ends.
155+
156+
## Summary
157+
158+
In this guide, you learned how to create a withdrawal request from a Firelight vault by specifying the amount of assets to withdraw.
159+
Remember that withdrawals are delayed and must be claimed after the current period ends.
160+
161+
:::tip[What's next]
162+
163+
To continue your Firelight development journey, you can:
164+
165+
- Learn how to [get Firelight vault status](/fassets/firelight/status) to monitor your withdrawal requests.
166+
- Learn how to [deposit assets into a Firelight vault](/fassets/firelight/deposit).
167+
- Learn how to [mint Firelight vault shares](/fassets/firelight/mint) by specifying the number of shares.
168+
- Explore the [FAssets system overview](/fassets/overview) to understand the broader ecosystem.
169+
170+
:::

0 commit comments

Comments
 (0)