Skip to content

feat(docs): add flare smart accounts overview #919

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nikerzetic-aflabs merged 10 commits into from
Sep 19, 2025
Merged

feat(docs): add flare smart accounts overview #919

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
24aaa1e
feat(docs): add flare smart accounts overview
nikerzetic-aflabs Sep 16, 2025
86ce19a
feat(docs): add fassets instructions
nikerzetic-aflabs Sep 17, 2025
68208f9
feat(docs): add custom instructions guide
nikerzetic-aflabs Sep 17, 2025
2c0ba4a
fix(docs): clean imports
nikerzetic-aflabs Sep 17, 2025
7339f68
fix(docs): grammar
nikerzetic-aflabs Sep 17, 2025
5719404
fix(docs): change article description
nikerzetic-aflabs Sep 17, 2025
b9d4a7b
feat(docs): add call hash code snippet
nikerzetic-aflabs Sep 17, 2025
13a9b6d
feat(docs): add fsa cli guide
nikerzetic-aflabs Sep 19, 2025
d30ce1f
feat(docs): add custom instructions dev guide
nikerzetic-aflabs Sep 19, 2025
5f601b3
fix(docs): broken link of future guide
nikerzetic-aflabs Sep 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
143 changes: 143 additions & 0 deletions docs/smart-accounts/1-overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,143 @@
---
sidebar_position: 1
slug: overview
title: Flare Smart Accounts
authors: [nikerzetic, filipkoprivec]
description: The Flare Smart Accounts is an account abstraction that performs actions on behalf of XRPL users.
tags: [quickstart, ethereum, flare-smart-accounts]
keywords:
[
flare-fdc,
ethereum,
flare-smart-accounts,
evm,
flare-network,
account-abstraction,
]
unlisted: false
---

import ThemedImage from "@theme/ThemedImage";
import useBaseUrl from "@docusaurus/useBaseUrl";

The Flare Smart Accounts is an account abstraction that allows XRPL users to perform actions on the Flare chain without owning any FLR token.
Each XRPL address is assigned a unique **smart account** on the Flare chain, which only it can control.
They do so through `Payment` transactions on the XRPL.
The Flare Smart Accounts are especially useful as a way of interacting with the FAssets workflow.

## Workflow

The workflow for Flare Smart Accounts is comprised of the following steps.

1. The XRPL user sends instructions as a `Payment` transaction to a specific XRPL address, with instructions encoded as the payment reference in the memo field.
2. The operator interacts with the [Flare Data Connector](/fdc/overview) to procure a `Payment` proof.
It then calls the `executeTransaction` function on the `MasterAccountController` contract, with the `Payment` proof and the XRPL address that made the transaction.
3. The XRPL user's smart account performs the actions given in the instructions.

## 1. Instructions on XRPL

The Flare Smart Accounts allow XRPL users to perform actions on the Flare chain through instructions on the XRPL.
This is done through a `Payment` to an XRPL address, designated by the operator - a backend monitoring incoming transactions and interacting with the Flare chain.
The payment must transfer sufficient funds, as specified by the operator, and must include the proper payment receipt in the memo field.

The payment receipt is a `bytes32` value.
The first byte is reserved for the instruction code, a byte representation of a two-digit number.
The remaining 31 bytes are the parameters for the chosen instruction.

In practice, the payment receipt should be prepared by a backend, through a web form.

<details>
<summary>Table of instruction IDs and corresponding actions.</summary>
<table>
<thead>
<tr>
<td>&nbsp;**Instruction ID**</td>
<td>**Action**&nbsp;</td>
<td>**Description**&nbsp;</td>
</tr>
</thead>
<tbody>
<tr>
<td>&nbsp;01</td>
<td>&nbsp;deposit</td>
<td>
&nbsp;Deposit an `amount` of FXRP into the Firelight vault, designated
by the `MasterAccountController` contract.
</td>
</tr>
<tr>
<td>&nbsp;02</td>
<td>&nbsp;withdraw</td>
<td>
&nbsp;Withdraw an `amount` of FXRP from the Firelight vault,
designated by the `MasterAccountController` contract.
</td>
</tr>
<tr>
<td>&nbsp;03</td>
<td>&nbsp;approve</td>
<td>
&nbsp;**Deprecated.** Approve the Firelight vault, designated by the
`MasterAccountController` contract, to spend an `amount` of FXRP from
your account.
</td>
</tr>
<tr>
<td>&nbsp;04</td>
<td>&nbsp;redeem</td>
<td>
&nbsp;Redeem `lots` of FXRP. The redemption will be handled by the
`executor`, specified by the `MasterAccountController` contract.
</td>
</tr>
<tr>
<td>&nbsp;05</td>
<td>&nbsp;reserveCollateral</td>
<td>
&nbsp;Reserve `lots` of collateral in the `agentVault`, specified by
the `MasterAccountController` contract. The collateral reservation
will be handled by the `executor`, also specified by the
`MasterAccountController` contract.
</td>
</tr>
<tr>
<td>&nbsp;06</td>
<td>&nbsp;claimWithdraw</td>
<td>&nbsp;Claim the withdrawal from the Firelight vault.</td>
</tr>
<tr>
<td>&nbsp;99</td>
<td>&nbsp;custom</td>
<td>
&nbsp;Execute a list of custom function calls. The custom instructions
need to be registered in advance, with the `MasterAccountController`
(`registerCustomInstruction` function).
</td>
</tr>
</tbody>
</table>
<p>&nbsp;</p>
</details>

## 2. Payment proof on Flare

The operator monitors incoming transactions to the specified XRPL address.
Upon receiving a payment, it makes a [`Payment` attestation request](/fdc/attestation-types/payment) to the FDC.
The `Payment` proof and the user's XRPL address are passed to the `executeTransaction` function on the `MasterAccountController` smart contract on the Flare chain.

The `MasterAccountController` contract first verifies the proof.
It then performs several checks on the proof:

- receiving address matches the one specified by the operator,
- the source address matches the XRPL address given to the function,
- that the proof has not yet been used for the same actions.

Then, the `MasterAccountController` contract retrieves the XRPL user's smart account from a mapping.
If the account does not yet exist, it is created at this point.

The payment reference is decoded.
Depending on the value of the leading byte, a different function on the smart account is called.

## 3. Actions on Flare

The XRPL user's smart account performs the actions in the instructions.
218 changes: 218 additions & 0 deletions docs/smart-accounts/2-fasset-instructions.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,218 @@
---
sidebar_position: 1
slug: fasset-instructions
title: FAsset Instructions
authors: [nikerzetic, filipkoprivec]
description: Using Flare Smart Accounts in the FAssets workflow.
tags: [intermediate, ethereum, flare-smart-accounts]
keywords:
[
flare-fdc,
ethereum,
flare-smart-accounts,
evm,
flare-network,
account-abstraction,
]
unlisted: false
---

import ThemedImage from "@theme/ThemedImage";
import useBaseUrl from "@docusaurus/useBaseUrl";

In this guide, we will take a closer look at the Flare Smart Accounts instructions related to FAssets.
FAsset is a trustless, over-collateralized bridge between XRPL and the Flare chain.
The FXRP is a token representation of XRP on the Flare chain.
FAssets allow XRPL users to partake in Flare's DeFi ecosystem using their XRP assets, without exchanging them for the FLR token.

Several steps of the FAsset process are performed as transactions on the Flare chain, which requires users to hold FLR tokens for paying gas fees.
The Flare Smart Accounts sidestep this by allowing XRPL users to trigger these actions through `Payment` transactions on XRPL.
Thus, they eradicate completely the need for XRPL users to hold any non-XRPL assets.

You can learn more about the FAssets in the [dedicated section](/fassets/overview/).

## `01` Deposit

Deposit an `amount` of FXRP from your account into the Firelight vault `depositVault`.
The address `depositVault` is designated by the `MasterAccountController` contract, and the `amount` is read from the last 31 bytes of the payment reference.

A deposit payment reference is the 32-byte value:

- byte representation of `02` on the first byte,
- byte representation of the `amount` number on the other 31 bytes.

<div
style={{
width: "90%",
margin: "0 auto",
display: "flex",
justifyContent: "center",
}}
>
<ThemedImage
alt="Breakdown of bytes in payment reference for the deposit action"
style={{ width: "100%" }}
sources={{
light: useBaseUrl("img/smart-accounts/deposit_light.svg"),
dark: useBaseUrl("img/smart-accounts/deposit_dark.svg"),
}}
/>
</div>

## `02` Withdraw

The first part of the withdrawal process from a Firelight vault.

Initiate a withdrawal request of an `amount` of FXRP from the Firelight vault `depositVault`.
The address `depositVault` is designated by the `MasterAccountController` contract, and the `amount` is read from the last 31 bytes of the payment reference.

A withdraw payment reference is the 32-byte value:

- byte representation of `02` on the first byte,
- byte representation of the `amount` number on the other 31 bytes.

<div
style={{
width: "90%",
margin: "0 auto",
display: "flex",
justifyContent: "center",
}}
>
<ThemedImage
alt="Breakdown of bytes in payment reference for the withdraw action"
style={{ width: "100%" }}
sources={{
light: useBaseUrl("img/smart-accounts/withdraw_light.svg"),
dark: useBaseUrl("img/smart-accounts/withdraw_dark.svg"),
}}
/>
</div>

## `03` Approve (deprecated)

_Approval has been integrated into the deposit action and is now deprecated._

Approve the `depositVault` address to withdraw an `amount` of FXRP from your smart account.
The address `depositVault` is designated by the `MasterAccountController` contract, and the `amount` is read from the last 31 bytes of the payment reference.

A withdraw payment reference is the 32-byte value:

- byte representation of `03` on the first byte,
- byte representation of the `amount` number on the other 31 bytes.

<div
style={{
width: "90%",
margin: "0 auto",
display: "flex",
justifyContent: "center",
}}
>
<ThemedImage
alt="Breakdown of bytes in payment reference for the approve action"
style={{ width: "100%" }}
sources={{
light: useBaseUrl("img/smart-accounts/approve_light.svg"),
dark: useBaseUrl("img/smart-accounts/approve_dark.svg"),
}}
/>
</div>

## `04` Redeem

Redemption is the process of converting FXRP back to XRP.
A number of `lots` of FXRP are burned, and the same number of `lots` of XRP is returned to the user's XRPL account.

The process is performed by an `executor` with `executorFee` (explained in the [minting guide](/fassets/minting#executor-role));
both of these are defined by the `MasterAccountController` contract.
The `lots` and `agentVault` values are both read from the payment reference.

A redeem payment reference is the 32-byte value:

- byte representation of `04` on the first byte,
- 19 empty bytes,
- byte representation of the `lots` number on the last 11 bytes.

<div
style={{
width: "90%",
margin: "0 auto",
display: "flex",
justifyContent: "center",
}}
>
<ThemedImage
alt="Breakdown of bytes in payment reference for the redeem action"
style={{ width: "100%" }}
sources={{
light: useBaseUrl("img/smart-accounts/redeem_light.svg"),
dark: useBaseUrl("img/smart-accounts/redeem_dark.svg"),
}}
/>
</div>

## `05` Reserve collateral

Collateral reservation is the first step in the FAssets minting process.
In anticipation of the transfer of XRP to the agent's underlying address on XRPL, a portion of its collateral is locked to prevent accidental under-collateralization.
Since this action happens on the Flare chain, the gas fees need to be paid in the native FLR token.

The reserveCollateral action reserves a number of `lots` of collateral of the `agentVault`.
The process is performed by an `executor` with `executorFee` (explained in the [minting guide](/fassets/minting#executor-role));
both of these are defined by the `MasterAccountController` contract.
The `lots` and `agentVault` values are both read from the payment reference.

A reserveCollateral payment reference is a 32-byte value:

- byte representation of `05` on the first byte,
- `agentVault` address on the next 20 bytes,
- byte representation of the `lots` number on the last 11 bytes.

<div
style={{
width: "90%",
margin: "0 auto",
display: "flex",
justifyContent: "center",
}}
>
<ThemedImage
alt="Breakdown of bytes in payment reference for the reserve collateral action"
style={{ width: "100%" }}
sources={{
light: useBaseUrl("img/smart-accounts/reserve_collateral_light.svg"),
dark: useBaseUrl("img/smart-accounts/reserve_collateral_dark.svg"),
}}
/>
</div>

## `06` Claim withdraw

The second part of the withdrawal process from the Firelight vault.
Claim the pending withdrawal from the Firelight `depositVault`, specified by the `MasterAccountController` contract.
The assets are transferred to the user's smart account.
The action can only be performed after one full period has passed.

A reserveCollateral payment reference is a 32-byte value:

- byte representation of `06` on the first byte,
- 31 empty bytes.

<div
style={{
width: "90%",
margin: "0 auto",
display: "flex",
justifyContent: "center",
}}
>
<ThemedImage
alt="Breakdown of bytes in payment reference for the claim withdraw action"
style={{ width: "100%" }}
sources={{
light: useBaseUrl("img/smart-accounts/claim_withdraw_light.svg"),
dark: useBaseUrl("img/smart-accounts/claim_withdraw_dark.svg"),
}}
/>
</div>
Loading
Loading