Skip to content

Commit 4373d08

Browse files
nikerzetic-aflabsnikerzetic-aflabs
committed
feat(docs): add fsa cli guide
1 parent b9d4a7b commit 4373d08

File tree

2 files changed

+179
-25
lines changed

2 files changed

+179
-25
lines changed

‎docs/smart-accounts/guides/01-fsa-cli.mdx‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
---
2+
sidebar_position: 1
3+
slug: fsa-cli
4+
title: Flare Smart Accounts CLI
5+
authors: [nikerzetic, filipkoprivec]
6+
description: Introduction to the Flare Smart Accounts CLI.
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+
The [Flare Smart Accounts CLI](https://github.com/flare-foundation/smart-accounts-cli) is a tool written in Python that streamlines the Flare Smart Accounts process by properly structuring and sending XRPL transactions/instructions.
24+
It has commands corresponding to each Flare Smart Accounts action ([table of instructions](/smart-accounts/overview#1-instructions-on-xrpl)), as well as other useful debugging features.
25+
26+
:::note
27+
The CLI executes **only** the transaction on XRPL.
28+
It does not bridge the instructions to Flare.
29+
That is done by the operator - a service that Flare runs.
30+
:::
31+
32+
To use the CLI, first clone [the repository](https://github.com/flare-foundation/smart-accounts-cli) and install the necessary dependencies:
33+
34+
```sh
35+
git clone https://github.com/flare-foundation/smart-accounts-cli.git
36+
cd smart-accounts-cli
37+
pip install -r requirements.txt
38+
```
39+
40+
Copy the `.env.example` file to the `.env` file, and fill in the missing values in the latter.
41+
42+
```sh
43+
cp .env.example .env
44+
```
45+
46+
The missing values are an XRPL testnet account secret value, a Flare address private key, and the RPC URLs for both Flare's Coston2 and XRPL testnet.
47+
You can create a new secret string through the [XRP faucets](https://xrpl.org/resources/dev-tools/xrp-faucets).
48+
49+
You can then run the script with the command:
50+
51+
```sh
52+
smart_accounts [-h] [--version] {bridge,debug} ...
53+
```
54+
55+
## `bridge` command
56+
57+
{/* TODO:(Nik) check if the second sentence is still true */}
58+
The `bridge` command executes an XRPL transaction with instructions for one of the actions, determined by the positional argument provided.
59+
A payment transaction with the appropriate memo field value is sent to the operator's XRPL address from the XRPL address specified in the `.env` file.
60+
61+
What follows is a list of possible positional arguments, what they do, and the additional parameters of each.
62+
63+
### `deposit`
64+
65+
Deposit an `amount` of FXRP from the smart account belonging to the XRPL address to the Firelight vault, designated by the `MasterAccountController` contract.
66+
67+
```sh
68+
./smart_accounts.py bridge deposit -a <amount>
69+
```
70+
71+
### `withdraw`
72+
73+
Begin the withdrawal process from the Firelight vault.
74+
An `amount` of FXRP is marked to be withdrawn from the Firelight vault to the user's smart account.
75+
76+
```sh
77+
./smart_accounts.py bridge withdraw -a <amount>
78+
```
79+
80+
### `redeem`
81+
82+
Redeem a `lots` amount of FXRP.
83+
That number of lots of FXRP are burned from the user's smart account, and the same amount of XRP is sent to the user's address on XRPL.
84+
85+
```sh
86+
./smart_accounts.py bridge redeem -l <lots>
87+
```
88+
89+
### `mint`
90+
91+
Mints a number of `lots` of FXRP to the user's smart account.
92+
The script first reserves collateral with the agent with the `address`, by sending a `reserveCollateral` instruction.
93+
It then sends a `lots` amount of XRP to the agent's underlying address.
94+
An executor, determined by the `MasterAccountController`, will complete the minting process, and `lots` of FXRP will be minted to the user's smart account.
95+
96+
```sh
97+
./smart_accounts.py bridge mint -a <address> -l <lots>
98+
```
99+
100+
### `claim-withdraw`
101+
102+
Complete the withdrawal process from the Firelight vault by claiming the funds.
103+
After the withdrawal process has been started, the funds are locked for a certain amount of time.
104+
Once that period has passed, they can be transferred back to the user's smart account.
105+
106+
```sh
107+
./smart_accounts.py bridge claim-withdraw
108+
```
109+
110+
### `custom`
111+
112+
Execute a custom action on the Flare chain.
113+
Make a transaction to the `address`, paying the `value`, and attaching the `calldata`.
114+
The `calldata` is the encoding of a function and its argument values, on the smart contract at the `address.
115+
116+
```sh
117+
./smart_accounts.py bridge deposit -a <address> -v <value> -d <calldata>
118+
```
119+
120+
Before making a transaction on XRPL with the necessary instructions, this command performs an additional step.
121+
It first packs the three provided values (`address`, `value`, and `calldata`) into a `IMasterAccountController.CustomInstruction` struct.
122+
Then, it calls the `registerCustomInstruction` function of the `MasterAccountController` contract, with the former as an argument.
123+
124+
Thus, it both registers a custom instruction with the `MasterAccountController` contract and retrieves the required `callHash`, which it can then send to the operator's XRPL address as instructions.
125+
126+
## `debug` command
127+
128+
The `debug` command offers some utility options for running the CLI.
129+
It allows three positional arguments: `mock-custom`, `check-status`, and `simulation`.
130+
131+
### `mock-custom`
132+
133+
Simulate a custom instruction with the mock `MasterAccountController` contract.
134+
Instead of sending the instructions as a transaction on XRPL and bridging them to Flare, the custom instructions are sent to the `MasterAccountController` contract directly.
135+
This is explained in more detail in the [Custom instructions guide](/smart-accounts/guides/custom-instruction).
136+
137+
The `address`, `value`, and `data` parameters are the same as for the [custom](/smart-accounts/guides/fsa-cli#custom) positional argument.
138+
The `seed` is a string representing an XRPL account.
139+
140+
```sh
141+
./smart_accounts.py debug mock-custom -s <seed> -a <address> -v <value> -d <calldata>
142+
```
143+
144+
### `check-status`
145+
146+
Check the status of the XRPL transaction with the `xrpl_hash`.
147+
148+
```sh
149+
./smart_accounts.py debug check-status <xrpl_hash>
150+
```
151+
152+
### `simulation`
153+
154+
Run the simulation of the [FAsset cycle](/smart-accounts/guides/fassets-cycle).
155+
It converts `mint` lots of XRP to FXRP, deposits `deposit` FXRP into the Firelight vault, withdraws `deposit` FXRP back to the smart account, and finally redeems `mint` FXRP back to XRP.
156+
157+
```sh
158+
./smart_accounts.py debug simulations -a <address> -m <mint> -d <deposit>
159+
```
160+
161+
This is equivalent to running the following commands:
162+
163+
```sh
164+
./smart_accounts.py bridge mint -a <address> -l <mint>
165+
./smart_accounts.py bridge deposit -a <deposit>
166+
./smart_accounts.py bridge withdraw -a <deposit>
167+
./smart_accounts.py bridge claim-withdraw
168+
./smart_accounts.py bridge redeem -l <mint>
169+
```

‎sidebars.ts‎

Lines changed: 10 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -259,31 +259,16 @@ const sidebars: SidebarsConfig = {
259259
items: [
260260
"smart-accounts/fasset-instructions",
261261
"smart-accounts/custom-instruction",
262-
// {
263-
// type: "category",
264-
// label: "Developer Guides",
265-
// collapsed: true,
266-
// link: {
267-
// slug: "/smart-accounts/developer-guides",
268-
// type: "generated-index",
269-
// },
270-
// items: [
271-
// {
272-
// type: "autogenerated",
273-
// dirName: "smart-accounts/developer-guides",
274-
// },
275-
// ],
276-
// },
277-
// {
278-
// type: "category",
279-
// label: "Infrastructure Guides",
280-
// collapsed: true,
281-
// link: {
282-
// slug: "/smart-accounts/guides",
283-
// type: "generated-index",
284-
// },
285-
// items: [{ type: "autogenerated", dirName: "smart-accounts/guides" }],
286-
// },
262+
{
263+
type: "category",
264+
label: "Developer Guides",
265+
collapsed: true,
266+
link: {
267+
slug: "/smart-accounts/guides",
268+
type: "generated-index",
269+
},
270+
items: [{ type: "autogenerated", dirName: "smart-accounts/guides" }],
271+
},
287272
// {
288273
// type: "category",
289274
// label: "Flare Smart Accounts Reference",

0 commit comments

Comments
 (0)