Skip to content

Commit 893b444

Browse files
nikerzetic-aflabsnikerzetic-aflabs
authored
feat(docs): add flare smart accounts overview (#919)
2 parents 6ede034 + 5f601b3 commit 893b444

21 files changed

+963
-0
lines changed

‎docs/smart-accounts/1-overview.mdx‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
---
2+
sidebar_position: 1
3+
slug: overview
4+
title: Flare Smart Accounts
5+
authors: [nikerzetic, filipkoprivec]
6+
description: The Flare Smart Accounts is an account abstraction that performs actions on behalf of XRPL users.
7+
tags: [quickstart, ethereum, flare-smart-accounts]
8+
keywords:
9+
[
10+
flare-fdc,
11+
ethereum,
12+
flare-smart-accounts,
13+
evm,
14+
flare-network,
15+
account-abstraction,
16+
]
17+
unlisted: false
18+
---
19+
20+
import ThemedImage from "@theme/ThemedImage";
21+
import useBaseUrl from "@docusaurus/useBaseUrl";
22+
23+
The Flare Smart Accounts is an account abstraction that allows XRPL users to perform actions on the Flare chain without owning any FLR token.
24+
Each XRPL address is assigned a unique **smart account** on the Flare chain, which only it can control.
25+
They do so through `Payment` transactions on the XRPL.
26+
The Flare Smart Accounts are especially useful as a way of interacting with the FAssets workflow.
27+
28+
## Workflow
29+
30+
The workflow for Flare Smart Accounts is comprised of the following steps.
31+
32+
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.
33+
2. The operator interacts with the [Flare Data Connector](/fdc/overview) to procure a `Payment` proof.
34+
It then calls the `executeTransaction` function on the `MasterAccountController` contract, with the `Payment` proof and the XRPL address that made the transaction.
35+
3. The XRPL user's smart account performs the actions given in the instructions.
36+
37+
## 1. Instructions on XRPL
38+
39+
The Flare Smart Accounts allow XRPL users to perform actions on the Flare chain through instructions on the XRPL.
40+
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.
41+
The payment must transfer sufficient funds, as specified by the operator, and must include the proper payment receipt in the memo field.
42+
43+
The payment receipt is a `bytes32` value.
44+
The first byte is reserved for the instruction code, a byte representation of a two-digit number.
45+
The remaining 31 bytes are the parameters for the chosen instruction.
46+
47+
In practice, the payment receipt should be prepared by a backend, through a web form.
48+
49+
<details>
50+
<summary>Table of instruction IDs and corresponding actions.</summary>
51+
<table>
52+
<thead>
53+
<tr>
54+
<td>&nbsp;**Instruction ID**</td>
55+
<td>**Action**&nbsp;</td>
56+
<td>**Description**&nbsp;</td>
57+
</tr>
58+
</thead>
59+
<tbody>
60+
<tr>
61+
<td>&nbsp;01</td>
62+
<td>&nbsp;deposit</td>
63+
<td>
64+
&nbsp;Deposit an `amount` of FXRP into the Firelight vault, designated
65+
by the `MasterAccountController` contract.
66+
</td>
67+
</tr>
68+
<tr>
69+
<td>&nbsp;02</td>
70+
<td>&nbsp;withdraw</td>
71+
<td>
72+
&nbsp;Withdraw an `amount` of FXRP from the Firelight vault,
73+
designated by the `MasterAccountController` contract.
74+
</td>
75+
</tr>
76+
<tr>
77+
<td>&nbsp;03</td>
78+
<td>&nbsp;approve</td>
79+
<td>
80+
&nbsp;**Deprecated.** Approve the Firelight vault, designated by the
81+
`MasterAccountController` contract, to spend an `amount` of FXRP from
82+
your account.
83+
</td>
84+
</tr>
85+
<tr>
86+
<td>&nbsp;04</td>
87+
<td>&nbsp;redeem</td>
88+
<td>
89+
&nbsp;Redeem `lots` of FXRP. The redemption will be handled by the
90+
`executor`, specified by the `MasterAccountController` contract.
91+
</td>
92+
</tr>
93+
<tr>
94+
<td>&nbsp;05</td>
95+
<td>&nbsp;reserveCollateral</td>
96+
<td>
97+
&nbsp;Reserve `lots` of collateral in the `agentVault`, specified by
98+
the `MasterAccountController` contract. The collateral reservation
99+
will be handled by the `executor`, also specified by the
100+
`MasterAccountController` contract.
101+
</td>
102+
</tr>
103+
<tr>
104+
<td>&nbsp;06</td>
105+
<td>&nbsp;claimWithdraw</td>
106+
<td>&nbsp;Claim the withdrawal from the Firelight vault.</td>
107+
</tr>
108+
<tr>
109+
<td>&nbsp;99</td>
110+
<td>&nbsp;custom</td>
111+
<td>
112+
&nbsp;Execute a list of custom function calls. The custom instructions
113+
need to be registered in advance, with the `MasterAccountController`
114+
(`registerCustomInstruction` function).
115+
</td>
116+
</tr>
117+
</tbody>
118+
</table>
119+
<p>&nbsp;</p>
120+
</details>
121+
122+
## 2. Payment proof on Flare
123+
124+
The operator monitors incoming transactions to the specified XRPL address.
125+
Upon receiving a payment, it makes a [`Payment` attestation request](/fdc/attestation-types/payment) to the FDC.
126+
The `Payment` proof and the user's XRPL address are passed to the `executeTransaction` function on the `MasterAccountController` smart contract on the Flare chain.
127+
128+
The `MasterAccountController` contract first verifies the proof.
129+
It then performs several checks on the proof:
130+
131+
- receiving address matches the one specified by the operator,
132+
- the source address matches the XRPL address given to the function,
133+
- that the proof has not yet been used for the same actions.
134+
135+
Then, the `MasterAccountController` contract retrieves the XRPL user's smart account from a mapping.
136+
If the account does not yet exist, it is created at this point.
137+
138+
The payment reference is decoded.
139+
Depending on the value of the leading byte, a different function on the smart account is called.
140+
141+
## 3. Actions on Flare
142+
143+
The XRPL user's smart account performs the actions in the instructions.

‎docs/smart-accounts/2-fasset-instructions.mdx‎

Lines changed: 218 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
---
2+
sidebar_position: 1
3+
slug: fasset-instructions
4+
title: FAsset Instructions
5+
authors: [nikerzetic, filipkoprivec]
6+
description: Using Flare Smart Accounts in the FAssets workflow.
7+
tags: [intermediate, ethereum, flare-smart-accounts]
8+
keywords:
9+
[
10+
flare-fdc,
11+
ethereum,
12+
flare-smart-accounts,
13+
evm,
14+
flare-network,
15+
account-abstraction,
16+
]
17+
unlisted: false
18+
---
19+
20+
import ThemedImage from "@theme/ThemedImage";
21+
import useBaseUrl from "@docusaurus/useBaseUrl";
22+
23+
In this guide, we will take a closer look at the Flare Smart Accounts instructions related to FAssets.
24+
FAsset is a trustless, over-collateralized bridge between XRPL and the Flare chain.
25+
The FXRP is a token representation of XRP on the Flare chain.
26+
FAssets allow XRPL users to partake in Flare's DeFi ecosystem using their XRP assets, without exchanging them for the FLR token.
27+
28+
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.
29+
The Flare Smart Accounts sidestep this by allowing XRPL users to trigger these actions through `Payment` transactions on XRPL.
30+
Thus, they eradicate completely the need for XRPL users to hold any non-XRPL assets.
31+
32+
You can learn more about the FAssets in the [dedicated section](/fassets/overview/).
33+
34+
## `01` Deposit
35+
36+
Deposit an `amount` of FXRP from your account into the Firelight vault `depositVault`.
37+
The address `depositVault` is designated by the `MasterAccountController` contract, and the `amount` is read from the last 31 bytes of the payment reference.
38+
39+
A deposit payment reference is the 32-byte value:
40+
41+
- byte representation of `02` on the first byte,
42+
- byte representation of the `amount` number on the other 31 bytes.
43+
44+
<div
45+
style={{
46+
width: "90%",
47+
margin: "0 auto",
48+
display: "flex",
49+
justifyContent: "center",
50+
}}
51+
>
52+
<ThemedImage
53+
alt="Breakdown of bytes in payment reference for the deposit action"
54+
style={{ width: "100%" }}
55+
sources={{
56+
light: useBaseUrl("img/smart-accounts/deposit_light.svg"),
57+
dark: useBaseUrl("img/smart-accounts/deposit_dark.svg"),
58+
}}
59+
/>
60+
</div>
61+
62+
## `02` Withdraw
63+
64+
The first part of the withdrawal process from a Firelight vault.
65+
66+
Initiate a withdrawal request of an `amount` of FXRP from the Firelight vault `depositVault`.
67+
The address `depositVault` is designated by the `MasterAccountController` contract, and the `amount` is read from the last 31 bytes of the payment reference.
68+
69+
A withdraw payment reference is the 32-byte value:
70+
71+
- byte representation of `02` on the first byte,
72+
- byte representation of the `amount` number on the other 31 bytes.
73+
74+
<div
75+
style={{
76+
width: "90%",
77+
margin: "0 auto",
78+
display: "flex",
79+
justifyContent: "center",
80+
}}
81+
>
82+
<ThemedImage
83+
alt="Breakdown of bytes in payment reference for the withdraw action"
84+
style={{ width: "100%" }}
85+
sources={{
86+
light: useBaseUrl("img/smart-accounts/withdraw_light.svg"),
87+
dark: useBaseUrl("img/smart-accounts/withdraw_dark.svg"),
88+
}}
89+
/>
90+
</div>
91+
92+
## `03` Approve (deprecated)
93+
94+
_Approval has been integrated into the deposit action and is now deprecated._
95+
96+
Approve the `depositVault` address to withdraw an `amount` of FXRP from your smart account.
97+
The address `depositVault` is designated by the `MasterAccountController` contract, and the `amount` is read from the last 31 bytes of the payment reference.
98+
99+
A withdraw payment reference is the 32-byte value:
100+
101+
- byte representation of `03` on the first byte,
102+
- byte representation of the `amount` number on the other 31 bytes.
103+
104+
<div
105+
style={{
106+
width: "90%",
107+
margin: "0 auto",
108+
display: "flex",
109+
justifyContent: "center",
110+
}}
111+
>
112+
<ThemedImage
113+
alt="Breakdown of bytes in payment reference for the approve action"
114+
style={{ width: "100%" }}
115+
sources={{
116+
light: useBaseUrl("img/smart-accounts/approve_light.svg"),
117+
dark: useBaseUrl("img/smart-accounts/approve_dark.svg"),
118+
}}
119+
/>
120+
</div>
121+
122+
## `04` Redeem
123+
124+
Redemption is the process of converting FXRP back to XRP.
125+
A number of `lots` of FXRP are burned, and the same number of `lots` of XRP is returned to the user's XRPL account.
126+
127+
The process is performed by an `executor` with `executorFee` (explained in the [minting guide](/fassets/minting#executor-role));
128+
both of these are defined by the `MasterAccountController` contract.
129+
The `lots` and `agentVault` values are both read from the payment reference.
130+
131+
A redeem payment reference is the 32-byte value:
132+
133+
- byte representation of `04` on the first byte,
134+
- 19 empty bytes,
135+
- byte representation of the `lots` number on the last 11 bytes.
136+
137+
<div
138+
style={{
139+
width: "90%",
140+
margin: "0 auto",
141+
display: "flex",
142+
justifyContent: "center",
143+
}}
144+
>
145+
<ThemedImage
146+
alt="Breakdown of bytes in payment reference for the redeem action"
147+
style={{ width: "100%" }}
148+
sources={{
149+
light: useBaseUrl("img/smart-accounts/redeem_light.svg"),
150+
dark: useBaseUrl("img/smart-accounts/redeem_dark.svg"),
151+
}}
152+
/>
153+
</div>
154+
155+
## `05` Reserve collateral
156+
157+
Collateral reservation is the first step in the FAssets minting process.
158+
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.
159+
Since this action happens on the Flare chain, the gas fees need to be paid in the native FLR token.
160+
161+
The reserveCollateral action reserves a number of `lots` of collateral of the `agentVault`.
162+
The process is performed by an `executor` with `executorFee` (explained in the [minting guide](/fassets/minting#executor-role));
163+
both of these are defined by the `MasterAccountController` contract.
164+
The `lots` and `agentVault` values are both read from the payment reference.
165+
166+
A reserveCollateral payment reference is a 32-byte value:
167+
168+
- byte representation of `05` on the first byte,
169+
- `agentVault` address on the next 20 bytes,
170+
- byte representation of the `lots` number on the last 11 bytes.
171+
172+
<div
173+
style={{
174+
width: "90%",
175+
margin: "0 auto",
176+
display: "flex",
177+
justifyContent: "center",
178+
}}
179+
>
180+
<ThemedImage
181+
alt="Breakdown of bytes in payment reference for the reserve collateral action"
182+
style={{ width: "100%" }}
183+
sources={{
184+
light: useBaseUrl("img/smart-accounts/reserve_collateral_light.svg"),
185+
dark: useBaseUrl("img/smart-accounts/reserve_collateral_dark.svg"),
186+
}}
187+
/>
188+
</div>
189+
190+
## `06` Claim withdraw
191+
192+
The second part of the withdrawal process from the Firelight vault.
193+
Claim the pending withdrawal from the Firelight `depositVault`, specified by the `MasterAccountController` contract.
194+
The assets are transferred to the user's smart account.
195+
The action can only be performed after one full period has passed.
196+
197+
A reserveCollateral payment reference is a 32-byte value:
198+
199+
- byte representation of `06` on the first byte,
200+
- 31 empty bytes.
201+
202+
<div
203+
style={{
204+
width: "90%",
205+
margin: "0 auto",
206+
display: "flex",
207+
justifyContent: "center",
208+
}}
209+
>
210+
<ThemedImage
211+
alt="Breakdown of bytes in payment reference for the claim withdraw action"
212+
style={{ width: "100%" }}
213+
sources={{
214+
light: useBaseUrl("img/smart-accounts/claim_withdraw_light.svg"),
215+
dark: useBaseUrl("img/smart-accounts/claim_withdraw_dark.svg"),
216+
}}
217+
/>
218+
</div>

0 commit comments

Comments
 (0)