Skip to content

Commit 7b34b49

Browse files
fasskofassko
committed
feat(docs): add Firelight vault deposit, mint, and status guides
1 parent 5cafdfc commit 7b34b49

File tree

7 files changed

+752
-0
lines changed

7 files changed

+752
-0
lines changed

‎docs/fassets/firelight/deposit.mdx‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
---
2+
title: Deposit Assets into Firelight Vault
3+
tags: [intermediate, fassets]
4+
slug: firelight-vault-deposit
5+
description: Learn how to deposit assets into a Firelight vault
6+
keywords: [fassets, flare-network, fxrp, firelight, vault]
7+
sidebar_position: 2
8+
---
9+
10+
import CodeBlock from "@theme/CodeBlock";
11+
import FirelightDeposit from "!!raw-loader!/examples/developer-hub-javascript/firelight-deposit.ts";
12+
13+
## Overview
14+
15+
This guide demonstrates how to deposit assets into a Firelight vault.
16+
The Firelight vault implements the [ERC-4626](https://eips.ethereum.org/EIPS/eip-4626) standard, which allows users to deposit assets (e.g., FXRP) and receive vault shares in return.
17+
18+
Depositing assets is the process of transferring assets to the vault and receiving vault shares, which represent your proportional ownership of the vault's assets.
19+
20+
## Prerequisites
21+
22+
- [Flare Hardhat Starter Kit](/network/guides/hardhat-foundry-starter-kit).
23+
- [Flare Network Periphery Contracts](https://www.npmjs.com/package/@flarenetwork/flare-periphery-contracts).
24+
- Understanding of [FAssets](/fassets/overview).
25+
- Sufficient asset balance (e.g., FXRP) to deposit into the vault.
26+
27+
## Firelight Vault Deposit Script
28+
29+
The following script demonstrates how to deposit assets into the Firelight vault:
30+
31+
<CodeBlock language="typescript" title="scripts/firelight/deposit.ts">
32+
{FirelightDeposit}
33+
</CodeBlock>
34+
35+
## Script Breakdown
36+
37+
### 1. Script Setup
38+
39+
The script starts by defining constants and importing the required contract interfaces:
40+
41+
- `FIRELIGHT_VAULT_ADDRESS`: The address of the Firelight vault contract on the [Flare Testnet Coston2 network](/network/overview).
42+
- `DEPOSIT_AMOUNT`: The number of tokens to deposit (default: 1 token).
43+
- `IFirelightVault`: The interface for interacting with the Firelight vault contract.
44+
Taken from the Firelight GitHub [repository](https://github.com/firelight-protocol/firelight-core/blob/main/contracts/FirelightVault.sol).
45+
- `IERC20`: Standard [ERC-20](https://eips.ethereum.org/EIPS/eip-20) interface for token interactions.
46+
47+
### 2. Get Asset Information
48+
49+
The script retrieves the underlying asset information to format amounts and calculate the deposit amount from the vault:
50+
51+
- **Asset address**: The token address that the vault accepts (e.g., FXRP).
52+
- **Asset symbol**: The token symbol for display purposes.
53+
- **Asset decimals**: The number of decimals used by the token.
54+
55+
### 3. Calculate Deposit Amount
56+
57+
The script converts the desired deposit amount into the correct units:
58+
59+
```typescript
60+
const amount = DEPOSIT_AMOUNT * (10 ** assetDecimals);
61+
```
62+
63+
### 4. Check Maximum Deposit Capacity
64+
65+
Before depositing, the script checks if the requested amount exceeds the maximum allowed:
66+
67+
```typescript
68+
const maxDeposit = await vault.maxDeposit(account);
69+
```
70+
71+
The `maxDeposit` function returns the maximum amount of assets that the specified account can deposit.
72+
73+
If the requested amount exceeds the maximum, the script exits with an error to prevent a failed transaction.
74+
75+
### 5. Approve Token Transfer
76+
77+
Before depositing, the script must approve the vault to spend the deposit amount:
78+
79+
```typescript
80+
const approveTx = await assetToken.approve(vault.address, amount, { from: account });
81+
```
82+
83+
This approval is required because the vault needs to transfer assets from the user's account.
84+
The approval amount should match or exceed the `amount` value to be deposited.
85+
86+
### 6. Deposit Assets
87+
88+
Finally, the script deposits the assets:
89+
90+
```typescript
91+
const depositTx = await vault.deposit(amount, account, { from: account });
92+
```
93+
94+
The `deposit` function:
95+
- Takes the amount of assets to deposit (`amount`).
96+
- Specifies the recipient address (`account`).
97+
- Transfers the assets from the user to the vault.
98+
- Mints the corresponding number of shares to the recipient based on the current exchange rate.
99+
100+
## Running the Script
101+
102+
To run the Firelight vault deposit script:
103+
104+
1. Ensure you have the [Flare Hardhat Starter Kit](/network/guides/hardhat-foundry-starter-kit) set up.
105+
2. Update the `FIRELIGHT_VAULT_ADDRESS` constant with the correct vault address for your network.
106+
3. Adjust the `DEPOSIT_AMOUNT` constant to the desired number of tokens.
107+
4. Ensure your account has sufficient asset balance (e.g., FXRP) to cover the deposit.
108+
5. Run the script using Hardhat:
109+
110+
```bash
111+
npx hardhat run scripts/firelight/deposit.ts --network coston2
112+
```
113+
114+
## Output
115+
116+
The script outputs the following information:
117+
118+
```bash
119+
=== Deposit (ERC-4626) ===
120+
Sender: 0x0d09ff7630588E05E2449aBD3dDD1D8d146bc5c2
121+
Vault: 0x91Bfe6A68aB035DFebb6A770FFfB748C03C0E40B
122+
Asset: 0x0b6A3645c240605887a5532109323A3E12273dc7 (FTestXRP, decimals=6)
123+
Deposit amount: 1000000 (= 1 FTestXRP)
124+
Max deposit: 115792089237316195423570985008687907853269984665640564039457584007913129639935
125+
Approve tx: 0x87a36c1009575719fd3adb9a1bb2e3062a601bf910fc7fac3248da71891c39a4
126+
Deposit tx: 0x446b7a171859d676677fc870cff81c7e8c0d618fc3588e60665792da86b94c50
127+
```
128+
129+
## Difference Between Deposit and Mint
130+
131+
The Firelight vault provides two ways to add assets:
132+
133+
- **`deposit`**: You specify the amount of assets to deposit, and the vault calculates how many shares you'll receive based on the current exchange rate.
134+
- **`mint`**: You specify the number of shares you want, and the vault calculates how many assets you need to deposit.
135+
136+
Both functions follow the [ERC-4626](https://eips.ethereum.org/EIPS/eip-4626) standard and result in the same outcome: you deposit assets and receive vault shares.
137+
138+
## Summary
139+
140+
In this guide, you learned how to deposit assets into a Firelight vault by specifying the amount of assets to deposit.
141+
142+
:::tip[What's next]
143+
144+
To continue your Firelight development journey, you can:
145+
146+
- Learn how to [get Firelight vault status](/fassets/firelight/status) to monitor your position.
147+
- Learn how to [mint Firelight vault shares](/fassets/firelight/mint) by specifying the number of shares.
148+
- Explore the [FAssets system overview](/fassets/overview) to understand the broader ecosystem.
149+
150+
:::

‎docs/fassets/firelight/mint.mdx‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
---
2+
title: Mint Firelight Vault Shares
3+
tags: [intermediate, fassets]
4+
slug: firelight-vault-mint
5+
description: Learn how to mint Firelight vault shares
6+
keywords: [fassets, flare-network, fxrp, firelight, vault]
7+
sidebar_position: 3
8+
---
9+
10+
import CodeBlock from "@theme/CodeBlock";
11+
import FirelightMint from "!!raw-loader!/examples/developer-hub-javascript/firelight-mint.ts";
12+
13+
## Overview
14+
15+
This guide demonstrates how to mint vault shares in a Firelight vault by depositing assets.
16+
The Firelight vault implements the [ERC-4626](https://eips.ethereum.org/EIPS/eip-4626) standard, which allows users to deposit assets (e.g., FXRP) and receive vault shares in return.
17+
18+
Minting shares is the process of depositing assets into the vault and receiving vault shares, which represent your proportional ownership of the vault's assets.
19+
20+
## Prerequisites
21+
22+
- [Flare Hardhat Starter Kit](/network/guides/hardhat-foundry-starter-kit).
23+
- [Flare Network Periphery Contracts](https://www.npmjs.com/package/@flarenetwork/flare-periphery-contracts).
24+
- Understanding of [FAssets](/fassets/overview).
25+
- Sufficient asset balance (e.g., FXRP) to deposit into the vault.
26+
27+
## Firelight Vault Mint Script
28+
29+
The following script demonstrates how to mint vault shares by depositing assets into the Firelight vault:
30+
31+
<CodeBlock language="typescript" title="scripts/firelight/mint.ts">
32+
{FirelightMint}
33+
</CodeBlock>
34+
35+
## Script Breakdown
36+
37+
### 1. Script Setup
38+
39+
The script starts by defining constants and importing the required contract interfaces:
40+
41+
- `FIRELIGHT_VAULT_ADDRESS`: The address of the Firelight vault contract on the [Flare Testnet Coston2 network](/network/overview).
42+
- `SHARES_TO_MINT`: The number of shares to mint (default: 1 share).
43+
- `IFirelightVault`: The interface for interacting with the Firelight vault contract.
44+
Taken from the Firelight GitHub [repository](https://github.com/firelight-protocol/firelight-core/blob/main/contracts/FirelightVault.sol).
45+
- `IERC20`: Standard [ERC-20](https://eips.ethereum.org/EIPS/eip-20) interface for token interactions.
46+
47+
### 2. Get Asset Information
48+
49+
The script retrieves the underlying asset information to format amounts and calculate the required asset amount for minting shares from the vault:
50+
51+
- **Asset address**: The token address that the vault accepts (e.g., FXRP).
52+
- **Asset symbol**: The token symbol for display purposes.
53+
- **Asset decimals**: The number of decimals used by the token.
54+
55+
### 3. Calculate Shares to Mint
56+
57+
The script converts the desired number of shares to mint into the correct units:
58+
59+
```typescript
60+
const sharesToMint = SHARES_TO_MINT * (10 ** assetDecimalsNum);
61+
```
62+
63+
### 4. Check Maximum Mint Capacity
64+
65+
Before minting, the script checks if the requested amount exceeds the maximum allowed:
66+
67+
```typescript
68+
const maxMint = await vault.maxMint(account);
69+
```
70+
71+
The `maxMint` function returns the maximum number of shares that the specified account can mint.
72+
73+
If the requested amount exceeds the maximum, the script exits with an error to prevent a failed transaction.
74+
75+
### 5. Calculate Required Assets
76+
77+
The script uses the `previewMint` function to calculate how many assets are needed to mint the desired number of shares:
78+
79+
```typescript
80+
const assetsNeeded = await vault.previewMint(sharesToMint);
81+
```
82+
83+
The `previewMint` function is part of the [ERC-4626](https://eips.ethereum.org/EIPS/eip-4626) standard and returns the amount of assets required to mint a specific number of shares, accounting for the current exchange rate between assets and shares.
84+
85+
### 6. Approve Token Transfer
86+
87+
Before minting, the script must approve the vault to spend the required amount of assets:
88+
89+
```typescript
90+
const approveTx = await assetToken.approve(vault.address, assetsNeeded, { from: account });
91+
```
92+
93+
This approval is required because the vault needs to transfer assets from the user's account.
94+
The approval amount should match or exceed the `assetsNeeded` value calculated in the previous step.
95+
96+
### 7. Mint Vault Shares
97+
98+
Finally, the script mints the vault shares:
99+
100+
```typescript
101+
const mintTx = await vault.mint(sharesToMint, account, { from: account });
102+
```
103+
104+
The `mint` function:
105+
- Takes the number of shares to mint (`sharesToMint`).
106+
- Specifies the recipient address (`account`).
107+
- Transfers the required assets from the user to the vault.
108+
- Mints the corresponding number of shares to the recipient.
109+
110+
## Running the Script
111+
112+
To run the Firelight vault mint script:
113+
114+
1. Ensure you have the [Flare Hardhat Starter Kit](/network/guides/hardhat-foundry-starter-kit) set up.
115+
2. Update the `FIRELIGHT_VAULT_ADDRESS` constant with the correct vault address for your network.
116+
3. Adjust the `SHARES_TO_MINT` constant to the desired number of shares.
117+
4. Ensure your account has sufficient asset balance (e.g., FXRP) to cover the minting cost.
118+
5. Run the script using Hardhat:
119+
120+
```bash
121+
npx hardhat run scripts/firelight/mint.ts --network coston2
122+
```
123+
124+
## Output
125+
126+
The script outputs the following information:
127+
128+
```bash
129+
=== Mint vault shares (ERC-4626) ===
130+
Sender: 0x0d09ff7630588E05E2449aBD3dDD1D8d146bc5c2
131+
Vault: 0x91Bfe6A68aB035DFebb6A770FFfB748C03C0E40B
132+
Asset: 0x0b6A3645c240605887a5532109323A3E12273dc7 (FTestXRP, decimals=6)
133+
Shares to mint: 1000000 (= 1 share)
134+
Max mint: 115792089237316195423570985008687907853269984665640564039457584007913129639935
135+
Assets needed (from previewMint): 1000000
136+
Approve tx: 0xfe5683b82a4997df7d7b7c22c8c4dc416cdec8d1380dceeb996279c64c525460
137+
Mint tx: 0x14d1c7ffe4f3b6a9fa04315eb8592ff9c64f2ae80c7e6e3a6e1b9cf9478106c3
138+
```
139+
140+
## Difference Between Mint and Deposit
141+
142+
The Firelight vault provides two ways to add assets:
143+
144+
- **`mint`**: You specify the number of shares you want, and the vault calculates how many assets you need to deposit.
145+
- **`deposit`**: You specify the amount of assets to deposit, and the vault calculates how many shares you'll receive based on the current exchange rate.
146+
147+
Both functions follow the [ERC-4626](https://eips.ethereum.org/EIPS/eip-4626) standard and result in the same outcome: you deposit assets and receive vault shares.
148+
149+
## Summary
150+
151+
In this guide, you learned how to mint vault shares in a Firelight vault by specifying the number of shares you want.
152+
153+
:::tip[What's next]
154+
155+
To continue your Firelight development journey, you can:
156+
157+
- Learn how to [get Firelight vault status](/fassets/firelight/status) to monitor your position.
158+
- Learn how to [deposit assets into a Firelight vault](/fassets/firelight/deposit) by specifying the amount of assets to deposit.
159+
- Explore the [FAssets system overview](/fassets/overview) to understand the broader ecosystem.
160+
161+
:::

0 commit comments

Comments
 (0)