Skip to content

Commit cb6e0f3

Browse files
fasskofassko
authored
feat(docs): retrieve asset manager dynamically in FAssets developer guides (#814)
1 parent b444a95 commit cb6e0f3

16 files changed

+359
-474
lines changed

‎docs/fassets/developer-guides/1-fassets-get-asset-amanager-address-registry.mdx‎

Lines changed: 10 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,6 @@ keywords: [fassets, flare-network, fxrp, asset-manager]
77
sidebar_position: 1
88
---
99

10-
import CodeBlock from "@theme/CodeBlock";
11-
import Remix from "@site/src/components/remix";
12-
import AssetManagerRegistry from "!!raw-loader!/examples/developer-hub-solidity/FAssetsAssetManagerRegistry.sol";
1310
import ExploringAdditionalParameters from "./_exploring-additional-parameters.mdx";
1411

1512
## Overview
@@ -19,44 +16,20 @@ These addresses can change between Flare testnets and mainnet deployments, and r
1916

2017
Instead, you should dynamically fetch the FXRP Asset Manager address using the [Flare Contract Registry](/network/guides/flare-contracts-registry), the trusted source for obtaining contract addresses on any Flare network.
2118

22-
In this guide, you will learn:
19+
## Get the FXRP Asset Manager Address
2320

24-
- How to retrieve the [Asset Manager Controller](/fassets/reference/IAssetManagerController) using the Flare Contract Registry.
25-
- How to find the specific FXRP [Asset Manager](/fassets/reference/IAssetManager).
26-
- A sample Solidity contract that encapsulates this logic.
21+
To get the [FAssets asset manager](/fassets/reference/IAssetManager) address, you can use the [Flare Contract Registry](/network/guides/flare-contracts-registry) library.
22+
It is included in the [Flare Periphery Contracts package](https://www.npmjs.com/package/@flarenetwork/flare-periphery-contracts).
2723

28-
## Sample code
24+
The following example demonstrates how to get the FXRP Asset Manager address using the Flare Contract Registry library in a Solidity contract.
2925

30-
To get the [FAssets asset manager](/fassets/reference/IAssetManager) address, you can use the following smart contract that retrieves the [Asset Manager Controller](/fassets/reference/IAssetManagerController) address from the [Flare contract registry](/network/guides/flare-contracts-registry).
26+
```solidity
27+
import { ContractRegistry } from "@flarenetwork/flare-periphery-contracts/coston2/ContractRegistry.sol";
28+
import {IAssetManager} from "@flarenetwork/flare-periphery-contracts/coston2/IAssetManager.sol";
3129
32-
<CodeBlock language="solidity" title="contracts/AssetManagerRegistry.sol">
33-
{AssetManagerRegistry}
34-
</CodeBlock>
35-
36-
{/* prettier-ignore */}
37-
<Remix fileName="FAssetsAssetManagerRegistry.sol">Open in Remix</Remix>
38-
<br></br>
39-
40-
### Contract Breakdown
41-
42-
1. Imports the necessary interfaces and libraries from the [Flare Periphery Contracts package](https://www.npmjs.com/package/@flarenetwork/flare-periphery-contracts).
43-
2. Defines a constant `TXRP_HASH` that is the hash of the string `TXRP`.
44-
This is used to identify the FXRP asset manager.
45-
3. Implements a function `getFxrpAssetManager` that returns the FXRP [Asset Manager](/fassets/reference/IAssetManager) address.
46-
4. Uses the `ContractRegistry` library from the Flare Periphery Contracts package to get the [Asset Manager Controller](/fassets/reference/IAssetManagerController) address from the Flare contract registry.
47-
5. Uses the `IAssetManagerController` interface from the Flare Periphery Contracts package to get all the asset managers from the Asset Manager Controller.
48-
6. Iterates over the asset managers and returns the FXRP Asset Manager address.
49-
7. Gets the settings of the asset manager.
50-
8. Checks if the pool token suffix is `TXRP` and if true returns the FXRP Asset Manager address.
51-
52-
You can find out this sample code in the [Flare starter kit](/network/guides/hardhat-foundry-starter-kit).
53-
54-
:::tip Reusable Library
55-
56-
To reuse this code to get the FXRP Asset Manager address in other smart contracts, you can wrap it in a reusable library.
57-
This is useful if you want to use the FXRP Asset Manager address in multiple smart contracts and avoid repeating the same code.
58-
59-
:::
30+
// Get the FXRP Asset Manager address from the Flare contracts registry
31+
IAssetManager assetManager = ContractRegistry.getAssetManagerFXRP();
32+
```
6033

6134
## Next Steps
6235

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

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,6 @@ sidebar_position: 2
99

1010
import CodeBlock from "@theme/CodeBlock";
1111
import Remix from "@site/src/components/remix";
12-
import FAssetsSwapAndRedeemContract from "!!raw-loader!/examples/developer-hub-solidity/FAssetsSwapAndRedeem.sol";
1312
import FAssetsGetFxrpScript from "!!raw-loader!/examples/developer-hub-javascript/fassets_get_fxrp.ts";
1413
import RedemptionProcessPrerequisites from "./_redemption_process_prerequisites.mdx";
1514

@@ -55,6 +54,11 @@ The script:
5554
2. Calls the [`fAsset`](/fassets/reference/IAssetManager#fasset) function to get the FXRP token address.
5655
3. Logs the address to the console.
5756

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+
:::
61+
5862
### Run the Script
5963

6064
To run the script, use the following command:
@@ -81,7 +85,7 @@ Once you have the FXRP address, you can:
8185
2. Add it to your wallet to track FXRP balances
8286
3. Use it in DeFi protocols that support FXRP
8387

84-
:::tip Next Steps
88+
## Next Steps
8589

8690
In this guide, you learned how to get the FXRP address for the FAssets system by interacting with the `AssetManager` contract using the [`IAssetManager`](/fassets/reference/IAssetManager) interface.
8791

@@ -91,5 +95,3 @@ To continue your FAssets development journey, you can:
9195
- Understand how to [redeem FXRP](/fassets/developer-guides/fassets-redeem).
9296
- Explore [FAssets system settings](/fassets/operational-parameters).
9397
- Check the [lot size](/fassets/developer-guides/fassets-settings-node) for FXRP operations.
94-
95-
:::

‎docs/fassets/developer-guides/3-fassets-asset-manager-settings-solidity.mdx‎

Lines changed: 28 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -37,14 +37,17 @@ To get the FAsset lot size, you can use the following smart contract:
3737

3838
### Code Breakdown
3939

40-
1. Import the interface `IAssetManager` from the [Flare Periphery Contracts package](https://www.npmjs.com/package/@flarenetwork/flare-periphery-contracts), which provides access to the FAssets system.
41-
2. Create a contract called `FAssetsSettings` that will be used to fetch the FAssets settings from the asset manager.
42-
3. Value `assetManager` holds the address of the FAssets FXRP asset manager contract.
43-
The type `IAssetManager` comes from the Flare Periphery Contracts package.
44-
4. The constructor initializes the contract with the AsseFXRP asset managertManager address.
45-
5. The `getLotSize` function gets numbers from the FAssets FXRP asset manager settings using the [`getSettings`](/fassets/reference/IAssetManager#getsettings) function returns the complete asset manager settings that you can find in the [FAssets Operational Parameters](/fassets/operational-parameters/#asset-manager-operational-parameters) documentation:
46-
- `lotSizeAMG`: The smallest amount you can trade (in AMG units)
47-
- `assetDecimals`: How many decimal places the FAssets asset uses
40+
1. Import the [ContractRegistry library](/network/guides/flare-contracts-registry#contract-registry-library) to access the Flare Network contract registry.
41+
2. Import the interface `IAssetManager` from the [Flare Periphery Contracts package](https://www.npmjs.com/package/@flarenetwork/flare-periphery-contracts), which provides access to the FAssets system.
42+
3. Create a contract called `FAssetsSettings` that will be used to fetch the FAssets settings from the asset manager.
43+
4. Use the ContractRegistry to get the FAssets FXRP asset manager address.
44+
5. Use the `getLotSize` function to retrieve settings from the FAssets FXRP asset manager.
45+
The function calls [`getSettings`](/fassets/reference/IAssetManager#getsettings) which returns the complete asset manager settings that you can find in the [FAssets Operational Parameters](/fassets/operational-parameters/#asset-manager-operational-parameters) documentation:
46+
- `lotSizeAMG`: The smallest amount you can trade (in AMG units).
47+
- `assetDecimals`: How many decimal places the FAssets asset uses.
48+
6. The `getLotSize` function returns two values:
49+
- `lotSizeAMG`: The smallest amount you can trade (in AMG units).
50+
- `assetDecimals`: How many decimal places the FAssets asset uses.
4851

4952
:::info Flare Hardhat Starter Kit
5053
Using the [Flare Hardhat Starter Kit](/network/guides/hardhat-foundry-starter-kit) you can quickly deploy the contract and generate TypeChain bindings for seamless TypeScript integration.
@@ -56,34 +59,22 @@ It streamlines development by providing a ready-made project structure, preconfi
5659
Use the following TypeScript script to deploy the contract and fetch the FAsset settings using the Hardhat tool:
5760

5861
```typescript title="scripts/fassets/getLotSize.ts"
59-
import { ethers } from "hardhat";
60-
import { FAssetsSettingsContract } from "../../typechain-types";
62+
// yarn hardhat run scripts/fassets/getLotSize.ts --network coston2
6163

62-
// 1. AssetManager address on Songbird Testnet Coston network
63-
const ASSET_MANAGER_ADDRESS = "0x56728e46908fB6FcC5BCD2cc0c0F9BB91C3e4D34";
64+
// 1. Get the contract artifact
65+
const FAssetsSettings = artifacts.require("FAssetsSettings");
6466

6567
async function main() {
66-
console.log("Deploying FAssetsSettings...");
67-
68-
// 2. Get the contract factory
69-
const FAssetsSettings = (await ethers.getContractFactory(
70-
"FAssetsSettings",
71-
)) as FAssetsSettingsContract;
72-
73-
// 3. Deploy the contract
74-
const fAssetsSettings = await FAssetsSettings.deploy(ASSET_MANAGER_ADDRESS);
75-
await fAssetsSettings.waitForDeployment();
76-
console.log(
77-
"FAssetsSettings deployed to:",
78-
await fAssetsSettings.getAddress(),
79-
);
80-
81-
// 4. Call getSettings function
68+
// 2. Deploy the contract
69+
const fAssetsSettings = await FAssetsSettings.new();
70+
console.log("FAssetsSettings deployed to:", fAssetsSettings.address);
71+
72+
// 3. Call getSettings function
8273
const lotSize = await fAssetsSettings.getLotSize();
8374
console.log("Lot size:", lotSize[0]);
8475
console.log("Decimals:", lotSize[1]);
8576

86-
// 5. Convert lot size to XRP
77+
// 4. Convert lot size to XRP
8778
const lotSizeFXRP = Number(lotSize[0]) / Math.pow(10, Number(lotSize[1]));
8879
console.log("Lot size in XRP", lotSizeFXRP);
8980
}
@@ -96,18 +87,17 @@ main().catch((error) => {
9687
9788
### Code Explanation
9889
99-
1. Define the FAssets TXRP asset manager address on the Songbird Testnet Coston network.
100-
2. Use the Typescript smart contract `FAssetsSettings` type to interact with the contract.
101-
3. Deploy the `FAssetsSettings` on the network and get the contract address.
102-
4. Call the `getLotSize` function to get the lot size and asset decimals.
103-
5. Convert the lot size to XRP.
90+
1. Get the contract artifact `FAssetsSettings` from the Hardhat artifacts.
91+
2. Deploy the `FAssetsSettings` on the network and get the contract address.
92+
3. Call the `getLotSize` function to get the lot size and asset decimals.
93+
4. Convert the lot size to XRP.
10494
10595
## Run the Script
10696
10797
Now you can run the script using the Hardhat tool with the following command:
10898
10999
```bash
110-
npx hardhat run scripts/fassets/getLotSize.ts --network coston
100+
npx hardhat run scripts/fassets/getLotSize.ts --network coston2
111101
```
112102

113103
You should see the following output:
@@ -126,9 +116,9 @@ Lot size in XRP 20
126116
This script is included in the [Flare Hardhat Starter Kit](https://github.com/flare-foundation/flare-hardhat-starter).
127117

128118
:::
129-
Congratulations! You have now deployed a Solidity helper contract and used a TypeScript script to
119+
Congratulations! You have now deployed a Solidity helper contract and used a TypeScript script to:
130120

131-
- fetch FAsset FXRP lot size and decimals;
132-
- convert the value to a user-friendly format using decimal precision.
121+
- Fetch FAsset FXRP lot size and decimals
122+
- Convert the value to a user-friendly format using decimal precision.
133123

134124
<ExploringAdditionalParameters />

‎docs/fassets/developer-guides/5-fassets-minting.mdx‎

Lines changed: 18 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -47,21 +47,21 @@ The following code demonstrates how to reserve collateral by calling the [`reser
4747

4848
1. Define constants
4949

50-
- `ASSET_MANAGER_ADDRESS`: FXRP AssetManager address on Songbird Testnet (Coston).
5150
- `LOTS_TO_MINT`: Number of FAsset lots to reserve.
52-
- `UNDERLYING_ADDRESS`: Target XRP Ledger address for the minted asset.
5351
- `ZERO_ADDRESS`: Placeholder for `executor` (not used in this script).
5452

5553
2. Retrieve and filter agents with enough free collateral and select the agent with the lowest fee and normal status.
5654
3. Parse [`CollateralReserved`](/fassets/reference/IAssetManagerEvents#collateralreserved) event.
5755
4. Start the minting reservation process at the script's entry point.
5856
5. Call `findBestAgent` with the required number of lots.
59-
6. Fetch agent metadata from [`getAgentInfo`](/fassets/reference/IAssetManager#getagentinfo) to get the agent's `feeBIPS`, which is used to calculate the collateral reservation fee.
60-
7. Calculate the collateral reservation fee by calling [`collateralReservationFee`](/fassets/reference/IAssetManager#collateralreservationfee).
61-
8. Reserve collateral from agent by calling [`reserveCollateral`](/fassets/reference/IAssetManager#reservecollateral)
62-
9. Call `assetMintingDecimals` to determine the XRP token's decimal precision.
63-
10. Parse the [`CollateralReserved`](/fassets/reference/IAssetManagerEvents#collateralreserved) event.
64-
11. Calculate the total XRP value required for payment.
57+
6. Get the asset manager from the [Flare Contract Registry](/network/guides/flare-contracts-registry).
58+
7. Find the best agent with enough free collateral lots.
59+
8. Fetch agent metadata from [`getAgentInfo`](/fassets/reference/IAssetManager#getagentinfo) to get the agent's `feeBIPS`, which is used to calculate the collateral reservation fee.
60+
9. Calculate the collateral reservation fee by calling [`collateralReservationFee`](/fassets/reference/IAssetManager#collateralreservationfee).
61+
10. Reserve collateral from agent by calling [`reserveCollateral`](/fassets/reference/IAssetManager#reservecollateral)
62+
11. Call `assetMintingDecimals` to determine the XRP token's decimal precision.
63+
12. Parse the [`CollateralReserved`](/fassets/reference/IAssetManagerEvents#collateralreserved) event.
64+
13. Calculate the total XRP value required for payment.
6565

6666
## Send Payment on XRP Ledger
6767

@@ -100,16 +100,17 @@ This script demonstrates how to retrieve the FDC proof and execute minting.
100100
### Execute Minting Script Breakdown
101101

102102
1. Get environment variables.
103-
2. Declare the constant `ASSET_MANAGER_ADDRESS` pointing to the FXRP AssetManager on the Songbird Testnet (Coston network).
104-
105-
3. Set the collateral reservation ID to the previously reserved minting request.
106-
4. Set the Flare Data Connector (FDC) round ID to retrieve the proof.
107-
5. Prepare the FDC request payload data.
108-
6. Create a function to get the proof from the FDC.
103+
2. Set the collateral reservation ID to the previously reserved minting request.
104+
3. Set the FDC round ID to retrieve the proof.
105+
4. Provide the FDC request data.
106+
5. Import the Asset manager contract artifact.
107+
6. Define the function to prepare the FDC request.
108+
7. Create a function to get the proof from the FDC.
109109
It sends a POST request to the [Flare Data Availability Layer](/fdc/overview#data-availability-layer) and returns a Merkle proof and attestation response from FDC.
110-
7. Retrieve the FDC proof from the Data Availability Layer.
111-
8. Call the [`executeMinting`](/fassets/reference/IAssetManager#executeminting) function on the AssetManager contract and send a transaction to the Flare network to convert the attested XRP payment into FXRP (minting).
112-
9. On a successful transaction call `parseExecutemintingEvents` to extract and log events [`RedemptionTicketCreated`](/fassets/reference/IAssetManagerEvents#redemptionticketcreated) and [`MintingExecuted`](/fassets/reference/IAssetManagerEvents#mintingexecuted).
110+
8. Define the function to parse the events.
111+
9. Retrieve the FDC proof from the Data Availability Layer.
112+
10. Call the [`executeMinting`](/fassets/reference/IAssetManager#executeminting) function on the AssetManager contract and send a transaction to the Flare network to convert the attested XRP payment into FXRP (minting).
113+
11. On a successful transaction call `parseExecutemintingEvents` to extract and log events [`RedemptionTicketCreated`](/fassets/reference/IAssetManagerEvents#redemptionticketcreated) and [`MintingExecuted`](/fassets/reference/IAssetManagerEvents#mintingexecuted).
113114

114115
## Next Steps
115116

‎docs/fassets/developer-guides/6-fassets-minting-executor.mdx‎

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -57,24 +57,24 @@ The following code demonstrates how to reserve collateral by calling the [`reser
5757

5858
1. Define constants
5959

60-
- `ASSET_MANAGER_ADDRESS`: FXRP AssetManager address on Songbird Testnet (Coston).
6160
- `LOTS_TO_MINT`: Number of FAssets [lots](/fassets/minting#lots) to reserve.
62-
- `UNDERLYING_ADDRESS`: Target XRP Ledger address for the minted asset.
6361
- `EXECUTOR_ADDRESS`: Executor address that will execute the minting process and provide the proof of underlying asset payment.
6462

65-
2. Retrieve and filter agents with enough free collateral and select the agent with the lowest fee and normal status.
66-
3. Parse [`CollateralReserved`](/fassets/reference/IAssetManagerEvents#collateralreserved) event.
67-
4. Start the minting reservation process at the script's entry point.
68-
5. Call `findBestAgen` with the required number of lots.
69-
6. Fetch agent metadata from [`getAgentInfo`](/fassets/reference/IAssetManager#getagentinfo) to get the agent's `feeBIPS`, which is used to calculate the collateral reservation fee.
70-
7. Calculate the collateral reservation fee by calling [`collateralReservationFee`](/fassets/reference/IAssetManager#collateralreservationfee).
71-
8. Set the executor fee the same as the collateral reservation fee to make this example simpler.
72-
9. Reserve collateral from agent by calling [`reserveCollateral`](/fassets/reference/IAssetManager#reservecollateral) with the executor address.
73-
The executor fee is on top of the collateral reservation fee in native tokens.
74-
The fee is agreed between the minter and the executor.
75-
10. Call `assetMintingDecimals` to determine the XRP token's decimal precision.
76-
11. Parse the [`CollateralReserved`](/fassets/reference/IAssetManagerEvents#collateralreserved) event to get the collateral reservation ID and other important collateral reservation details.
77-
12. Calculate the total XRP value required for payment.
63+
2. Get the AssetManager artifact
64+
3. Retrieve and filter agents with enough free collateral and select the agent with the lowest fee and normal status.
65+
4. Parse [`CollateralReserved`](/fassets/reference/IAssetManagerEvents#collateralreserved) event.
66+
5. Start the minting reservation process at the script's entry point.
67+
6. Get the asset manager artifact.
68+
7. Call `findBestAgent` with the required number of lots.
69+
8. Fetch agent metadata from [`getAgentInfo`](/fassets/reference/IAssetManager#getagentinfo) to get the agent's `feeBIPS`, which is used to calculate the collateral reservation fee.
70+
9. Calculate the collateral reservation fee by calling [`collateralReservationFee`](/fassets/reference/IAssetManager#collateralreservationfee).
71+
10. Set the executor fee the same as the collateral reservation fee to make this example simpler.
72+
11. Reserve collateral from agent by calling [`reserveCollateral`](/fassets/reference/IAssetManager#reservecollateral) with the executor address.
73+
The executor fee is on top of the collateral reservation fee in native tokens.
74+
The fee is agreed between the minter and the executor.
75+
12. Call `assetMintingDecimals` to determine the XRP token's decimal precision.
76+
13. Parse the [`CollateralReserved`](/fassets/reference/IAssetManagerEvents#collateralreserved) event to get the collateral reservation ID and other important collateral reservation details.
77+
14. Calculate the total XRP value required for payment.
7878

7979
## Send Payment on XRP Ledger
8080

0 commit comments

Comments
 (0)