Skip to content

Commit 2831076

Browse files
nikerzetic-aflabsnikerzetic-aflabs
committed
WIP
1 parent ac90ad0 commit 2831076

File tree

3 files changed

+229
-0
lines changed

3 files changed

+229
-0
lines changed

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

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
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+
import YoutubeEmbed from "@site/src/components/youtube";
23+
24+
In this guide we will take a closer look at the Flare Smart Accounts instructions related to FAssets.
25+
FAsset is a trustless, over-collateralize bridge between XRPL and the Flare chain.
26+
The FXRP is a token representation of XRP on the Flare chain.
27+
FAssets allow XRPL users to partake in Flare's DeFi ecosystem using their XRP assets, without exchanging them for the FLR token.
28+
29+
Several steps of the FAsset process are performed as transactions on the Flare chain, which requires users to hold FLR token for paying gas fees.
30+
The Flare Smart Accounts sidestep this by allowing XRPL users to trigger these actions through `Payment` transactions on XRPL.
31+
Thus, the eradicate completely the need for XRPL users to hold any non-XRPL assets.
32+
33+
You can learn more about the FAssets in the [dedicated section](/fassets/overview/).
34+
35+
## `01` Deposit
36+
37+
Deposit an `amount` of FXRP from you account into the Firelight vault `depositVault`.
38+
The address `depositVault` is designated by the `MasterAccountController` contract, and the `amount` is read from the last 31 bytes of the payment reference.
39+
40+
A deposit payment reference is the 32 byte value:
41+
42+
```Solidity
43+
bytes32((uint256(01) << 248) | amount))
44+
```
45+
46+
`01` `amount`
47+
48+
## `02` Withdraw
49+
50+
Withdraw an `amount` of FXRP from the Firelight vault `depositVault`.
51+
The address `depositVault` is designated by the `MasterAccountController` contract, and the `amount` is read from the last 31 bytes of the payment reference.
52+
53+
A withdraw payment reference is the 32 byte value:
54+
55+
56+
## `03` Approve
57+
58+
## `04` Redeem
59+
60+
## `05` Reserve collateral
61+
62+
Collateral reservation is the first step in the FAssets minting process.
63+
In anticipation of transfer of XRP to the agent's underlying address on XRPL a portion of its collateral is locked to prevent accidental under-collateralization.
64+
Since this action happens on the Flare chain, the gas fees need to be paid in the native FLR token.
65+
66+
The Flare Smart Accounts provide a service to XRPL users, where the operator
67+
{/* TODO:(Nik) make this sentence go somewhere */}
68+
69+
The reserveCollateral action reserves a number of `lots` of collateral of the `agentVault`.
70+
The process is performed by an `executor` with `executorFee` (explained in the [minting guide](/fassets/minting#executor-role));
71+
both of these are defined by the `MasterAccountController` contract.
72+
The `lots` and `agentVault` values are both read from the payment reference.
73+
74+
75+
{/* TODO:(Nik) link to executor */}
76+
77+
A reserveCollateral payment reference is a 32 byte value, with:
78+
- the hex representation of `05` on the first byte,
79+
- the `agentVault` address on the next 19 bytes,
80+
- and the `lots` number on the last 11 bytes.
81+
82+
83+
## `06` Claim withdraw

‎docs/smart-accounts/3-custom-instruction.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: custom-instruction
4+
title: Custom instruction
5+
authors: [nikerzetic, filipkoprivec]
6+
description: The Flare Smart Accounts is an account abstraction that performs actions on behalf of XRPL users.
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+
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.

‎sidebars.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -257,6 +257,8 @@ const sidebars: SidebarsConfig = {
257257
collapsed: true,
258258
link: { type: "doc", id: "smart-accounts/overview" },
259259
items: [
260+
"smart-accounts/fasset-instructions",
261+
"smart-accounts/custom-instruction",
260262
// {
261263
// type: "category",
262264
// label: "Developer Guides",

0 commit comments

Comments
 (0)