FAssets Integration Guide

Last Updated: December 6, 2025
FAssets Version: v1.2 (Mainnet - September 2025)

Canonical Guide: This is the single authoritative FAssets integration guide for the Shield Finance protocol. For implementation code, see server/services/BridgeService.ts.

Overview

FAssets is Flare Network’s trustless, over-collateralized bridge connecting non-smart contract chains (XRP, BTC, DOGE) to Flare’s DeFi ecosystem. FXRP (wrapped XRP) was the first FAsset to launch on mainnet.

Key Features:

1:1 XRP backing with overcollateralization
Trustless bridging powered by Flare Data Connector (FDC)
ERC-20 compatible on Flare Network
Full redemption capability at any time
Audited by Zellic, Coinspect, Code4rena

Contract Addresses

Flare Mainnet (Chain ID: 14)

Contract	Address	Notes
FXRP Token	`0xAf7278D382323A865734f93B687b300005B8b60E`	✅ Verified on Flarescan
Flare Contract Registry	`0xaD67FE66660Fb8dFE9d6b1b4240d8650e30F6019`	Query for AssetManager address
AssetManager	Retrieved via Registry	Use `getContractAddressByName("AssetManager")`

Alternative FXRP Address: 0xAd552A648C74D49E10027AB8a618A3ad4901c5bE (verify on Flarescan)

Block Explorer: https://flarescan.com
RPC Endpoint: https://flare-api.flare.network/ext/C/rpc

Coston2 Testnet (Chain ID: 114)

Contract	Address	Notes
FXRP Token	`0xa3Bd00D652D0f28D2417339322A51d4Fbe2B22D3`	✅ Confirmed
Flare Contract Registry	`0xaD67FE66660Fb8dFE9d6b1b4240d8650e30F6019`	Same address across networks
AssetManager	Retrieved via Registry	Dynamic retrieval required

Block Explorer: https://coston2-explorer.flare.network
RPC Endpoint: https://coston2-api.flare.network/ext/C/rpc

Retrieving AssetManager Address

FAssets uses a dynamic contract registry system. Never hardcode AssetManager addresses.

import { ethers } from 'ethers';

const REGISTRY_ADDRESS = "0xaD67FE66660Fb8dFE9d6b1b4240d8650e30F6019";
const REGISTRY_ABI = [
  "function getContractAddressByName(string calldata) external view returns (address)"
];

const provider = new ethers.JsonRpcProvider("https://flare-api.flare.network/ext/C/rpc");
const registry = new ethers.Contract(REGISTRY_ADDRESS, REGISTRY_ABI, provider);

// Get AssetManager address
const assetManagerAddress = await registry.getContractAddressByName("AssetManager");
console.log("AssetManager:", assetManagerAddress);

Minting Resources

Official Minting dApps

AU Platform: https://fassets.au.cc/mint
Oracle Daemon: https://fasset.oracle-daemon.com/flare

Supported Wallets

Wallet	Flare Support	XRPL Support	Notes
Bifrost	✅	✅	Best for full minting flow
Ledger	✅	✅	Hardware wallet
Luminite	✅	✅	Integrated FAssets support
MetaMask	✅	❌	Flare-side only
Xaman	❌	✅	XRPL-side only

FAssets Minting Flow

Step-by-Step Process

sequenceDiagram
    participant User
    participant AssetManager
    participant Agent
    participant FDC as Flare Data Connector
    participant XRPL

    User->>AssetManager: 1. reserveCollateral(agent, lots, maxFee)
    AssetManager->>Agent: Lock collateral
    AssetManager-->>User: CollateralReserved event (paymentRef, agentAddress, deadline)
    
    User->>XRPL: 2. Send XRP with payment reference memo
    XRPL-->>Agent: XRP received
    
    User->>FDC: 3. Request payment proof
    FDC-->>User: Attestation proof
    
    User->>AssetManager: 4. executeMinting(attestationProof, reservationId)
    AssetManager->>User: Mint FXRP tokens (ERC-20)

1. Reserve Collateral

import { IAssetManager } from "@flarelabs/fasset/contracts/userInterfaces/IAssetManager.sol";

// Connect to AssetManager
const assetManager = new ethers.Contract(assetManagerAddress, IAssetManager.abi, signer);

// Reserve collateral with agent
const tx = await assetManager.reserveCollateral(
  agentVaultAddress,        // Selected agent
  lotsToMint,               // Amount in lots (e.g., 1 lot = 1 XRP)
  maxMintingFeeBIPS,        // Max fee in basis points (e.g., 250 = 2.5%)
  ethers.ZeroAddress,       // Executor address (or ZeroAddress)
  { value: collateralReservationFee }
);

// Parse the CollateralReserved event
const receipt = await tx.wait();
const event = receipt.logs.find(log => log.topics[0] === CollateralReservedEventTopic);
const {
  collateralReservationId,
  agentAddress,       // XRPL address to send XRP to
  amountUBA,         // Amount to pay in underlying asset (XRP drops)
  paymentReference,  // 32-byte hex to include in XRPL memo
  lastUnderlyingBlock,
  lastUnderlyingTimestamp
} = parseEvent(event);

2. Send XRP Payment

Send XRP to the agent’s XRPL address with the payment reference as a memo:

import { Client, Payment } from 'xrpl';

const client = new Client('wss://xrplcluster.com');
await client.connect();

const payment: Payment = {
  TransactionType: 'Payment',
  Account: userXrplAddress,
  Destination: agentAddress,
  Amount: amountUBA.toString(), // XRP in drops
  Memos: [{
    Memo: {
      MemoData: Buffer.from(paymentReference, 'hex').toString('hex'),
      MemoType: Buffer.from('fassets-payment', 'utf8').toString('hex')
    }
  }]
};

const prepared = await client.autofill(payment);
const signed = wallet.sign(prepared);
const result = await client.submitAndWait(signed.tx_blob);

3. Obtain Payment Proof (FDC)

Wait for XRPL transaction finality (~7 blocks), then obtain attestation proof from Flare Data Connector.

Finality Requirements:

XRPL: 7 blocks (~30-40 seconds)
Bitcoin: 6 blocks (~60 minutes)
Dogecoin: 60 blocks (~60 minutes)

4. Execute Minting

// Get attestation proof from FDC
const attestationProof = await getFdcProof(xrplTxHash);

// Execute minting
const mintTx = await assetManager.executeMinting(
  attestationProof,
  collateralReservationId
);

await mintTx.wait();
// FXRP tokens are now minted to your Flare address!

FAssets Redemption Flow

Redeem FXRP for XRP

// Approve FXRP spending
const fxrpToken = new ethers.Contract(fxrpAddress, ERC20_ABI, signer);
await fxrpToken.approve(assetManagerAddress, amountToRedeem);

// Initiate redemption
const redeemTx = await assetManager.redeem(
  lotsToRedeem,              // Amount in lots
  userXrplAddress,           // Your XRPL address to receive XRP
  ethers.ZeroAddress         // Executor (or ZeroAddress)
);

const receipt = await redeemTx.wait();
// RedemptionRequested event emitted

// Agent has 24 hours to send XRP to your XRPL address
// FXRP is burned immediately

Redemption Timeline:

FXRP burned immediately upon request
Agent must send XRP within 24 hours
If agent fails, collateral is released to you as compensation

Key Events

CollateralReserved Event

event CollateralReserved(
    address indexed minter,
    uint256 indexed collateralReservationId,
    address indexed agentVault,
    uint256 amountUBA,
    uint256 feeUBA,
    uint256 firstUnderlyingBlock,
    uint256 lastUnderlyingBlock,
    uint256 lastUnderlyingTimestamp,
    bytes32 paymentReference
);

MintingExecuted Event

event MintingExecuted(
    address indexed minter,
    uint256 indexed collateralReservationId,
    uint256 amountUBA,
    uint256 agentFeeUBA,
    uint256 poolFeeUBA
);

RedemptionRequested Event

event RedemptionRequested(
    address indexed redeemer,
    uint256 indexed requestId,
    address indexed agentVault,
    uint256 amountUBA,
    uint256 feeUBA,
    string paymentAddress
);

Fees & Economics

Minting Fees

Fee Type	Charged In	Amount	Purpose
Collateral Reservation Fee (CRF)	FLR	Governance-set %	Compensates agent for locked collateral time
Minting Fee	XRP	Agent-set %	Main revenue for agent & collateral pool
Executor Fee	FLR	Optional	Incentivizes bot execution

Typical Fees:

Collateral Reservation Fee: ~0.1-0.5% of minted value (in FLR)
Minting Fee: 0.25-1% (agent-specific, paid in XRP)

Redemption Fees

Redemption Fee: 0.1-0.5% (agent-specific, paid from XRP sent back)

Collateralization

Collateral Types

Agents must maintain collateral in two forms:

Vault Collateral (140% minimum):
- USDC, USDT, ETH, or other approved stablecoins
Pool Collateral (Community-provided):
- Native tokens (FLR on Flare, SGB on Songbird)

Example: To mint 100 FXRP (~$50 value):

Agent needs ~$70 in USDC + pool collateral
Total backing: 200%+ including pool

Collateral Ratios

Minimum CR: 140% (vault) + pool collateral
Safe CR: 160%+
Liquidation: Triggered if CR drops below minimum
Full Liquidation: If agent violates protocol rules

Gas Requirements

Flare Network Gas Costs

Mainnet Estimates:

Reserve Collateral: ~200,000 gas (~0.02 FLR)
Execute Minting: ~300,000 gas (~0.03 FLR)
Redeem: ~250,000 gas (~0.025 FLR)

Gas Price: Typically 25 gwei on Flare mainnet

XRPL Transaction Costs

Base transaction fee: 0.00001 XRP (10 drops)
Negligible compared to Flare gas costs

Bridging Timeframes

Minting (XRP → FXRP)

Reserve Collateral: Instant (Flare block time: ~2 seconds)
Send XRP Payment: 3-5 seconds (XRPL)
Wait for Finality: ~30-40 seconds (7 XRPL blocks)
FDC Attestation: ~1-2 minutes (proof generation + verification)
Execute Minting: ~2-5 seconds (Flare block)

Total Time: ~2-5 minutes

Redemption (FXRP → XRP)

Redeem Request: Instant (FXRP burned)
Agent Sends XRP: Up to 24 hours (typically <1 hour)
XRP Received: 3-5 seconds after agent sends

Total Time: Minutes to 24 hours (depends on agent responsiveness)

Core Vault System

What is Core Vault?

The Core Vault (CV) is a multisig XRPL account managed by Flare governance that holds XRP backing without requiring agent collateral.

Benefits:

Agents can deposit XRP to CV and free up collateral
Increased capital efficiency for agents
Improved redemption liquidity
Multisig security on XRPL side

Core Vault Address (XRPL): Governed multisig (check official docs for current address)

Integration Best Practices

1. Always Use Contract Registry

// ✅ GOOD: Dynamic retrieval
const assetManager = await getAssetManagerFromRegistry();

// ❌ BAD: Hardcoded address
const assetManager = "0x123..."; // Will break if upgraded

2. Handle Payment Reference Carefully

The 32-byte payment reference MUST be included in XRPL memo exactly as provided by CollateralReserved event.

// Store payment reference from event
const paymentRef = event.args.paymentReference;

// Include in XRPL memo as hex
Memos: [{
  Memo: {
    MemoData: paymentRef // Already in hex format
  }
}]

3. Wait for XRPL Finality

Do not request FDC proof until XRPL transaction has 7+ confirmations.

// Wait for finality
const finalizedTx = await client.request({
  command: 'tx',
  transaction: txHash,
  min_ledger: currentLedger + 7
});

4. Monitor Events

Listen for minting/redemption events to track status:

assetManager.on("MintingExecuted", (minter, reservationId, amount) => {
  console.log(`Minting complete! Amount: ${amount}`);
});

assetManager.on("RedemptionPerformed", (redeemer, requestId, amount) => {
  console.log(`XRP sent! Check XRPL for receipt.`);
});

Error Handling

Common Failure Scenarios

Error	Cause	Solution
`InsufficientCollateral`	Agent doesn’t have enough free collateral	Choose different agent or wait
`PaymentTimeout`	XRP payment not made within deadline	Request will expire; retry minting
`InvalidPaymentReference`	Wrong memo in XRPL tx	Double-check payment reference from event
`ProofTooEarly`	Requested FDC proof before finality	Wait for 7+ XRPL confirmations

Handling Failed Minting

If you fail to send XRP within the deadline:

Collateral reservation expires
Collateral Reservation Fee is lost
No FXRP minted
You can start over with new reservation

Official Resources

Developer Hub: https://dev.flare.network/fassets/overview
Minting Guide: https://dev.flare.network/fassets/developer-guides/fassets-mint
Redemption Guide: https://dev.flare.network/fassets/developer-guides/fassets-redeem
GitHub Repository: https://github.com/flare-foundation/fassets
Audits: https://code4rena.com/audits/2025-08-flare-fasset

Security Considerations

Audits

Zellic: Comprehensive smart contract audit (2024)
Coinspect: Security review and audit (2024)
Code4rena: Community audit competition (2025)
Hypernative: 24/7 monitoring

Risk Factors

Agent Counterparty Risk: Mitigated by overcollateralization
XRPL Bridge Risk: Mitigated by FDC cryptographic proofs
Price Oracle Risk: FTSO provides decentralized price feeds
Smart Contract Risk: Audited, but bugs always possible

Bug Bounty

Active bug bounty program via Immunefi for responsible disclosure.

Next Steps

✅ Review contract addresses and verify on block explorer
✅ Test minting flow on Coston2 testnet first
✅ Integrate AssetManager ABI from official repository
✅ Implement FDC proof retrieval (or use minting dApp APIs)
✅ Add event listeners for mint/redeem tracking
✅ Handle edge cases (timeouts, insufficient collateral)

For Your Project:

Integrate FXRP deposits into your shXRP vault
Accept FXRP as collateral for XRP-backed positions
Use FAssets bridge to enable XRP holders to access Flare DeFi