Skip to content

Commit 7f0223b

Browse files
nikerzetic-aflabsnikerzetic-aflabs
committed
feat(docs): add flare smart accounts overview
1 parent 2cc6d42 commit 7f0223b

File tree

3 files changed

+191
-0
lines changed

3 files changed

+191
-0
lines changed

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

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

‎docs/tags.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,3 +38,5 @@ evm:
3838
label: evm
3939
infrastructure:
4040
label: infrastructure
41+
flare-smart-accounts:
42+
label: flare-smart-accounts

‎sidebars.ts‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -251,6 +251,51 @@ const sidebars: SidebarsConfig = {
251251
},
252252
],
253253
},
254+
{
255+
type: "category",
256+
label: "Flare Smart Accounts",
257+
collapsed: true,
258+
link: { type: "doc", id: "smart-accounts/overview" },
259+
items: [
260+
// {
261+
// type: "category",
262+
// label: "Developer Guides",
263+
// collapsed: true,
264+
// link: {
265+
// slug: "/smart-accounts/developer-guides",
266+
// type: "generated-index",
267+
// },
268+
// items: [
269+
// {
270+
// type: "autogenerated",
271+
// dirName: "smart-accounts/developer-guides",
272+
// },
273+
// ],
274+
// },
275+
// {
276+
// type: "category",
277+
// label: "Infrastructure Guides",
278+
// collapsed: true,
279+
// link: {
280+
// slug: "/smart-accounts/guides",
281+
// type: "generated-index",
282+
// },
283+
// items: [{ type: "autogenerated", dirName: "smart-accounts/guides" }],
284+
// },
285+
// {
286+
// type: "category",
287+
// label: "Flare Smart Accounts Reference",
288+
// collapsed: true,
289+
// link: {
290+
// type: "doc",
291+
// id: "smart-accounts/reference",
292+
// },
293+
// items: [
294+
// { type: "autogenerated", dirName: "smart-accounts/reference" },
295+
// ],
296+
// },
297+
],
298+
},
254299
{
255300
type: "category",
256301
label: "Run a Node",

0 commit comments

Comments
 (0)