Skip to content

Commit a318742

Browse files
fasskofassko
committed
fix(docs): refine Flare Smart Accounts overview for clarity and consistency
1 parent 22b597a commit a318742

1 file changed

Lines changed: 55 additions & 54 deletions

File tree

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

Lines changed: 55 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -6,14 +6,14 @@ authors: [nikerzetic]
66
description: The Flare Smart Accounts is an account abstraction that performs actions on behalf of XRPL users.
77
tags: [quickstart, ethereum, flare-smart-accounts]
88
keywords:
9-
[
9+
[
1010
flare-fdc,
1111
ethereum,
1212
flare-smart-accounts,
1313
evm,
1414
flare-network,
1515
account-abstraction,
16-
]
16+
]
1717
unlisted: false
1818
---
1919

@@ -22,9 +22,9 @@ import useBaseUrl from "@docusaurus/useBaseUrl";
2222
import YouTubeEmbed from "@site/src/components/YouTubeEmbed";
2323

2424
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, which only it can control.
25+
Each XRPL address is assigned a unique **smart account** on the Flare chain, which it can control alone.
2626
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.
27+
The Flare Smart Accounts are especially useful for interacting with the FAssets workflow.
2828

2929
## Workflow
3030

@@ -41,12 +41,12 @@ Flare Smart Accounts support two complementary flows for turning an XRPL `Paymen
4141
sources={{
4242
light: useBaseUrl("img/docs/smart-accounts/fsa-workflow-light.png"),
4343
dark: useBaseUrl("img/docs/smart-accounts/fsa-workflow-dark.png"),
44-
}}
44+
}}
4545
/>
4646

4747
<p style={{ textAlign: "center", fontStyle: "italic" }}>
48-
Proof-based flow: XRPL `Payment` (1) → operator backend (2) → FDC attestation
49-
(3, 4) → `MasterAccountController` (5) → `PersonalAccount` (6).
48+
Proof-based flow: XRPL `Payment` (1) → operator backend (2) → FDC attestation
49+
(3, 4) → `MasterAccountController` (5) → `PersonalAccount` (6).
5050
</p>
5151

5252
### Direct-minting (memo) flow
@@ -57,53 +57,53 @@ Flare Smart Accounts support two complementary flows for turning an XRPL `Paymen
5757

5858
```mermaid
5959
graph TB
60-
subgraph XRPL["XRPL"]
61-
User(["<b>user account</b>"])
62-
Agent(["<b>FAssets agent</b><br/><i>XRPL address</i>"])
63-
end
64-
65-
subgraph Flare["Flare"]
66-
Executor[("<b>Executor</b><br/><i>backend</i>")]
67-
AssetManager["<b>FAssets AssetManager</b><br/><i>contract</i>"]
68-
MAC["<b>MasterAccountController</b><br/><i>contract</i>"]
69-
PA["<b>PersonalAccount</b><br/><i>contract</i>"]
70-
end
71-
72-
User -- "1 - Payment + memo" --> Agent
73-
Agent -. "2 - observe payment" .-> Executor
74-
Executor -- "3 - executeMinting" --> AssetManager
75-
AssetManager == "4 - mint FXRP +<br/>mintedFAssets callback" ==> MAC
76-
MAC -- "5 - forward FXRP +<br/>dispatch memo instruction" --> PA
77-
User -. "controls" .-> PA
78-
79-
style Flare stroke-dasharray: 5 5
80-
style XRPL stroke-dasharray: 5 5
60+
subgraph XRPL["XRPL"]
61+
User(["<b>user account</b>"])
62+
Agent(["<b>FAssets agent</b><br/><i>XRPL address</i>"])
63+
end
64+
65+
subgraph Flare["Flare"]
66+
Executor[("<b>Executor</b><br/><i>backend</i>")]
67+
AssetManager["<b>FAssets AssetManager</b><br/><i>contract</i>"]
68+
MAC["<b>MasterAccountController</b><br/><i>contract</i>"]
69+
PA["<b>PersonalAccount</b><br/><i>contract</i>"]
70+
end
71+
72+
User -- "1 - Payment + memo" --> Agent
73+
Agent -. "2 - observe payment" .-> Executor
74+
Executor -- "3 - executeDirectMinting" --> AssetManager
75+
AssetManager == "4 - mint FXRP +<br/>mintedFAssets callback" ==> MAC
76+
MAC -- "5 - forward FXRP +<br/>dispatch memo instruction" --> PA
77+
User -. "controls" .-> PA
78+
79+
style Flare stroke-dasharray: 5 5
80+
style XRPL stroke-dasharray: 5 5
8181
```
8282

8383
<p style={{ textAlign: "center", fontStyle: "italic" }}>
84-
Direct-minting flow: XRPL `Payment` carrying a memo (1) → FAssets agent (2) →
85-
executor calls `AssetManager.executeMinting` (3) → `AssetManager` mints FXRP
86-
and calls back into `mintedFAssets` (4) → `MasterAccountController` forwards
87-
FXRP and dispatches the memo to the user's `PersonalAccount` (5).
84+
Direct-minting flow: XRPL `Payment` carrying a memo (1) → FAssets agent (2) →
85+
executor calls `AssetManager.executeDirectMinting` (3) → `AssetManager` mints
86+
FXRP and calls back into `mintedFAssets` (4) → `MasterAccountController`
87+
forwards FXRP and dispatches the memo to the user's `PersonalAccount` (5).
8888
</p>
8989

90-
## 1. Instructions on XRPL
90+
## Instructions on XRPL
9191

9292
The Flare Smart Accounts allow XRPL users to perform actions on the Flare chain through instructions on the XRPL.
9393
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.
9494
The payment must transfer sufficient funds, as specified by the operator, and must include the proper payment reference (proof-based flow) or memo (direct-minting flow).
9595

9696
The payment reference is a `bytes32` value.
9797
The first byte is reserved for the instruction code.
98-
The second byte is a wallet identifier;
99-
this is a number assigned to wallet providers by the Flare Foundation, and should otherwise be `0`.
98+
The second byte is a wallet identifier.
99+
This is a number assigned to wallet providers by the Flare Foundation, and should otherwise be `0`.
100100
The remaining 30 bytes are the parameters for the chosen instruction.
101101

102102
In practice, the payment reference should be prepared by a backend, through a web form.
103103

104104
The first, instruction code, byte is further subdivided into two half-bytes.
105-
The first nibble is the instruction type;
106-
this is either `FXRP`, `Firelight`, or `Upshift` (with corresponding type IDS `0`, `1`, and `2`).
105+
The first nibble is the instruction type.
106+
This is either `FXRP`, `Firelight`, or `Upshift` (with corresponding type IDS `0`, `1`, and `2`).
107107
The second nibble is the instruction command; the available commands are different for each instruction type.
108108

109109
For the direct-minting flow, the memo carries a different layout — see the [Custom Instruction guide](/smart-accounts/custom-instruction) for the `PackedUserOperation` format and the `0xFF`/`0xE0`/`0xE1`/`0xE2`/`0xD0`/`0xD1` instruction codes.
@@ -119,9 +119,9 @@ Instructions for interacting with the `FXRP` token.
119119

120120
| Command ID | Action | Description |
121121
| ---------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
122-
| `00` | `collateralReservation` | Reserve a `value` of lots of collateral in the agent vault, registered with the `agentVaultId` with the `MasterAccountController` contract. |
123-
| `01` | `transfer` | Transfer a `value` (in drops) of FXRP to the `recipientAddress`. |
124-
| `02` | `redeem` | Redeem a `value` of lots of FXRP. |
122+
| `00` | `collateralReservation` | Reserve a `value` of lots of collateral in the agent vault, registered with the `agentVaultId` with the `MasterAccountController` contract. |
123+
| `01` | `transfer` | Transfer a `value` (in drops) of FXRP to the `recipientAddress`. |
124+
| `02` | `redeem` | Redeem a `value` of lots of FXRP. |
125125

126126
### Firelight
127127

@@ -131,10 +131,10 @@ Instructions for interacting with a Firelight-type vault.
131131

132132
| Command ID | Action | Description |
133133
| ---------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
134-
| `00` | `collateralReservationAndDeposit` | Reserve a `value` of lots of collateral in the agent vault, registered with the `agentVaultId` with the `MasterAccountController` contract. After successful minting, deposit the FXRP into the Firelight type vault, registered with the `vaultId` with the `MasterAccountController` contract. Equivalent to sending a `collateralReservation` instruction and a Firelight `deposit` instruction. |
135-
| `01` | `deposit` | Deposit a `value` of FXRP into the Firelight type vault, registered with the `vaultId` with the `MasterAccountController` contract. |
136-
| `02` | `redeem` | Start the withdrawal process for a `value` of vault shares (in drops) from the Firelight type vault, registered with the `vaultId`, with the `MasterAccountController` contract. |
137-
| `03` | `claimWithdraw` | Withdraw the `FXRP`, requested in the `value` period, from Firelight type vault, registered with the `vaultId`, with the `MasterAccountController` contract. |
134+
| `00` | `collateralReservationAndDeposit` | Reserve a `value` of lots of collateral in the agent vault, registered with the `agentVaultId` with the `MasterAccountController` contract. After successful minting, deposit the FXRP into the Firelight type vault, registered with the `vaultId` with the `MasterAccountController` contract. Equivalent to sending a `collateralReservation` instruction and a Firelight `deposit` instruction. |
135+
| `01` | `deposit` | Deposit a `value` of FXRP into the Firelight type vault, registered with the `vaultId` with the `MasterAccountController` contract. |
136+
| `02` | `redeem` | Start the withdrawal process for a `value` of vault shares (in drops) from the Firelight type vault, registered with the `vaultId`, with the `MasterAccountController` contract. |
137+
| `03` | `claimWithdraw` | Withdraw the `FXRP`, requested in the `value` period, from the Firelight type vault, registered with the `vaultId`, with the `MasterAccountController` contract. |
138138

139139
### Upshift
140140

@@ -144,30 +144,30 @@ Instructions for interacting with an Upshift-type vault.
144144

145145
| Command ID | Action | Description |
146146
| ---------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
147-
| `00` | `collateralReservationAndDeposit` | Reserve a `value` of lots of collateral in the agent vault, registered with the `agentVaultId` with the `MasterAccountController` contract. After successful minting, deposit the FXRP into the Upshift type vault, registered with the `vaultId`, with the `MasterAccountController` contract. Equivalent to sending a `collateralReservation` instruction and a Upshift `deposit` instruction. |
148-
| `01` | `deposit` | Deposit a `value` of FXRP into the Upshift type vault, registered with the `vaultId` with the `MasterAccountController` contract. |
149-
| `02` | `requestRedeem` | Start the withdrawal process for a `value` of vault shares (in drops) from the Upshift type vault, registered with the `vaultId` with the `MasterAccountController` contract. |
150-
| `03` | `claim` | Withdraw the `FXRP` requested for the `value` date (encoded as `yyyymmdd`) from the Upshift type vault, registered with the `vaultId` with the `MasterAccountController` contract. |
147+
| `00` | `collateralReservationAndDeposit` | Reserve a `value` of lots of collateral in the agent vault, registered with the `agentVaultId` with the `MasterAccountController` contract. After successful minting, deposit the FXRP into the Upshift type vault, registered with the `vaultId`, with the `MasterAccountController` contract. Equivalent to sending a `collateralReservation` instruction and a Upshift `deposit` instruction. |
148+
| `01` | `deposit` | Deposit a `value` of FXRP into the Upshift type vault, registered with the `vaultId` with the `MasterAccountController` contract. |
149+
| `02` | `requestRedeem` | Start the withdrawal process for a `value` of vault shares (in drops) from the Upshift type vault, registered with the `vaultId` with the `MasterAccountController` contract. |
150+
| `03` | `claim` | Withdraw the `FXRP` requested for the `value` date (encoded as `yyyymmdd`) from the Upshift type vault, registered with the `vaultId` with the `MasterAccountController` contract. |
151151

152152
</details>
153153

154-
## 2. Dispatch on Flare
154+
## Dispatch on Flare
155155

156156
### Proof-based flow
157157

158158
The operator monitors incoming transactions to the specified XRPL address.
159159
Upon receiving a payment, it requests a [`Payment` attestation](/fdc/attestation-types/payment) from the FDC and submits the proof together with the user's XRPL address to the appropriate facet on the `MasterAccountController`:
160160

161161
- [`reserveCollateral`](/smart-accounts/reference/IMasterAccountController#reservecollateral) — for command `00` of any instruction type.
162-
Takes the payment reference and XRPL transaction id (no FDC proof needed at this stage, the user has only committed to mint).
162+
Takes the payment reference and XRPL transaction ID (no FDC proof needed at this stage, the user has only committed to mint).
163163
- [`executeDepositAfterMinting`](/smart-accounts/reference/IMasterAccountController#executedepositafterminting) — second leg of the Firelight/Upshift collateral-reservation-and-deposit instructions, after FAssets minting completes.
164164
- [`executeInstruction`](/smart-accounts/reference/IMasterAccountController#executeinstruction) — for all other reference-encoded instructions.
165165

166166
For the proof-bearing functions, the contract verifies the FDC proof and checks that:
167167

168-
- the receiving address matches the one configured for the operator,
168+
- the receiving address matches one of the registered operator XRPL addresses,
169169
- the source address matches the XRPL address passed to the function,
170-
- the XRPL transaction id has not already been used (replay protection via `usedTransactionIds`).
170+
- the XRPL transaction ID has not already been used (replay protection via `usedTransactionIds`).
171171

172172
The contract then resolves the XRPL user's `PersonalAccount` from the address mapping, deploying it via `CREATE2` if it does not yet exist, and dispatches the instruction encoded in the payment reference.
173173

@@ -176,11 +176,12 @@ The contract then resolves the XRPL user's `PersonalAccount` from the address ma
176176
When the user mints FXRP directly to their smart account via [FAssets direct minting](/fassets/direct-minting), the FAssets `AssetManager` calls back into [`mintedFAssets`](/smart-accounts/reference/IMasterAccountController#mintedfassets) on `MemoInstructionsFacet`.
177177
The facet enforces that the caller is the `AssetManager`, resolves (or deploys) the user's `PersonalAccount`, pays an executor fee out of the minted FAssets, forwards the remainder to the personal account, and dispatches any memo instruction (`0xFF`, `0xE0`, `0xE1`, `0xE2`, `0xD0`, `0xD1`).
178178

179-
## 3. Actions on Flare
179+
## Actions on Flare
180180

181181
The XRPL user's smart account performs the actions in the instructions.
182182
This can be any of the instructions listed above, reserving collateral for minting FXRP, transferring FXRP to another address, redeeming FXRP, depositing it into a vault ...
183-
Furthermore, custom instructions (`0xFF`) can be executed — arbitrary function calls on Flare, signed as an EIP-4337 `PackedUserOperation` and replayed on-chain by the personal account.
183+
Furthermore, custom instructions (`0xFF`) can be executed — arbitrary function calls on Flare, encoded as an EIP-4337 `PackedUserOperation` carried in the XRPL memo and replayed on-chain by the personal account.
184+
Authorization comes from the XRPL `Payment` signature itself; the on-chain check only validates the `sender` and `nonce` fields of the `PackedUserOperation`.
184185
See the [Custom Instruction guide](/smart-accounts/custom-instruction) for the details.
185186

186187
## Video Tutorials

0 commit comments

Comments
 (0)