Skip to content

Commit 6d95442

Browse files
fasskofassko
committed
docs: enhance Flare Smart Accounts workflow with proof-based and direct-minting flows
1 parent 800c203 commit 6d95442

1 file changed

Lines changed: 93 additions & 157 deletions

File tree

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

Lines changed: 93 additions & 157 deletions
Original file line numberDiff line numberDiff line change
@@ -28,40 +28,86 @@ The Flare Smart Accounts are especially useful as a way of interacting with the
2828

2929
## Workflow
3030

31-
The workflow for Flare Smart Accounts is comprised of the following steps.
31+
Flare Smart Accounts support two complementary flows for turning an XRPL `Payment` into actions on Flare.
3232

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.
33+
### Proof-based flow (payment reference)
34+
35+
1. The XRPL user sends a `Payment` transaction to the operator's XRPL address with a 32-byte instruction encoded as the **payment reference**.
36+
2. The operator requests a [`Payment` attestation](/fdc/attestation-types/payment) from the [Flare Data Connector](/fdc/overview) and submits it to the `MasterAccountController`.
37+
3. The XRPL user's `PersonalAccount` performs the action encoded in the reference.
3738

3839
<ThemedImage
39-
alt="Flare smart accounts workflow"
40+
alt="Flare Smart Accounts proof-based flow"
4041
sources={{
4142
light: useBaseUrl("img/docs/smart-accounts/fsa-workflow-light.png"),
4243
dark: useBaseUrl("img/docs/smart-accounts/fsa-workflow-dark.png"),
4344
}}
4445
/>
4546

47+
<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).
50+
</p>
51+
52+
### Direct-minting (memo) flow
53+
54+
1. The XRPL user sends a `Payment` to an FAssets agent's XRPL address that mints FXRP directly to the smart account, with the [memo field](/smart-accounts/custom-instruction) carrying the instruction.
55+
2. The FAssets `AssetManager` mints FXRP to the `MasterAccountController` and calls back into [`mintedFAssets`](/smart-accounts/reference/IMasterAccountController#mintedfassets) on `MemoInstructionsFacet`.
56+
3. The facet routes the FAssets to the user's `PersonalAccount`, optionally pays an executor fee, and dispatches any memo instruction (`0xFF` execute UserOp, `0xE0` ignore memo, `0xE1` set nonce, `0xE2` replace fee, `0xD0`/`0xD1` set/remove executor).
57+
58+
```mermaid
59+
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
81+
```
82+
83+
<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).
88+
</p>
89+
4690
## 1. Instructions on XRPL
4791

4892
The Flare Smart Accounts allow XRPL users to perform actions on the Flare chain through instructions on the XRPL.
4993
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.
50-
The payment must transfer sufficient funds, as specified by the operator, and must include the proper payment receipt in the memo field.
94+
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).
5195

52-
The payment receipt is a `bytes32` value.
96+
The payment reference is a `bytes32` value.
5397
The first byte is reserved for the instruction code.
5498
The second byte is a wallet identifier;
5599
this is a number assigned to wallet providers by the Flare Foundation, and should otherwise be `0`.
56100
The remaining 30 bytes are the parameters for the chosen instruction.
57101

58-
In practice, the payment receipt should be prepared by a backend, through a web form.
102+
In practice, the payment reference should be prepared by a backend, through a web form.
59103

60104
The first, instruction code, byte is further subdivided into two half-bytes.
61105
The first nibble is the instruction type;
62106
this is either `FXRP`, `Firelight`, or `Upshift` (with corresponding type IDS `0`, `1`, and `2`).
63107
The second nibble is the instruction command; the available commands are different for each instruction type.
64108

109+
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.
110+
65111
<details>
66112
<summary>Table of instruction IDs and corresponding actions.</summary>
67113

@@ -71,181 +117,71 @@ Instructions for interacting with the `FXRP` token.
71117

72118
**Type ID:** `00`.
73119

74-
<table>
75-
<thead>
76-
<tr>
77-
<td>&nbsp;**Command ID**</td>
78-
<td>**Action**&nbsp;</td>
79-
<td>**Description**&nbsp;</td>
80-
</tr>
81-
</thead>
82-
<tbody>
83-
<tr>
84-
<td>&nbsp;00</td>
85-
<td>&nbsp;collateralReservation</td>
86-
<td>
87-
&nbsp;Reserve a `value` of lots of collateral in the agent vault,
88-
registered with the `agentVaultId` with the `MasterAccountController`
89-
contract.
90-
</td>
91-
</tr>
92-
<tr>
93-
<td>&nbsp;01</td>
94-
<td>&nbsp;transfer</td>
95-
<td>
96-
&nbsp;Transfer a `value` (in drops) of FXRP to the `recipientAddress`.
97-
</td>
98-
</tr>
99-
<tr>
100-
<td>&nbsp;02</td>
101-
<td>&nbsp;redeem</td>
102-
<td>&nbsp;Redeem a `value` of lots of FXRP.</td>
103-
</tr>
104-
</tbody>
105-
</table>
106-
<p>&nbsp;</p>
120+
| Command ID | Action | Description |
121+
| ---------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
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. |
107125

108126
### Firelight
109127

110128
Instructions for interacting with a Firelight-type vault.
111129

112130
**Type ID:** `01`.
113131

114-
<table>
115-
<thead>
116-
<tr>
117-
<td>&nbsp;**Command ID**</td>
118-
<td>**Action**&nbsp;</td>
119-
<td>**Description**&nbsp;</td>
120-
</tr>
121-
</thead>
122-
<tr>
123-
<td>&nbsp;00</td>
124-
<td>&nbsp;collateralReservationAndDeposit</td>
125-
<td>
126-
&nbsp;Reserve a `value` of lots of collateral in the agent vault,
127-
registered with the `agentVaultId` with the `MasterAccountController`
128-
contract. After successful minting, deposit the FXRP into the Firelight
129-
type vault, registered with the `vaultId` with the
130-
`MasterAccountController` contract. Equivalent to sending a
131-
`collateralReservation` instruction and a Firelight `deposit` instruction.
132-
</td>
133-
</tr>
134-
<tbody>
135-
<tr>
136-
<td>&nbsp;01</td>
137-
<td>&nbsp;deposit</td>
138-
<td>
139-
&nbsp;Deposit a `value` of FXRP into the Firelight type vault,
140-
registered with the `vaultId` with the `MasterAccountController`
141-
contract.
142-
</td>
143-
</tr>
144-
<tr>
145-
<td>&nbsp;02</td>
146-
<td>&nbsp;redeem</td>
147-
<td>
148-
&nbsp;Start the withdrawal process for a `value` of FXRP from the
149-
Firelight type vault, registered with the `vaultId`, with the
150-
`MasterAccountController` contract.
151-
</td>
152-
</tr>
153-
<tr>
154-
<td>&nbsp;03</td>
155-
<td>&nbsp;claimWithdraw</td>
156-
<td>
157-
&nbsp;Withdraw the `FXRP`, requested in the `value` period, from
158-
Firelight type vault, registered with the `vaultId`, with the
159-
`MasterAccountController` contract.
160-
</td>
161-
</tr>
162-
</tbody>
163-
</table>
164-
<p>&nbsp;</p>
132+
| Command ID | Action | Description |
133+
| ---------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
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. |
165138

166139
### Upshift
167140

168141
Instructions for interacting with an Upshift-type vault.
169142

170143
**Type ID:** `02`.
171144

172-
<table>
173-
<thead>
174-
<tr>
175-
<td>&nbsp;**Command ID**</td>
176-
<td>**Action**&nbsp;</td>
177-
<td>**Description**&nbsp;</td>
178-
</tr>
179-
</thead>
180-
<tr>
181-
<td>&nbsp;00</td>
182-
<td>&nbsp;collateralReservationAndDeposit</td>
183-
<td>
184-
&nbsp;Reserve a `value` of lots of collateral in the agent vault,
185-
registered with the `agentVaultId` with the `MasterAccountController`
186-
contract. After successful minting, deposit the FXRP into the Upshift
187-
type vault, registered with the `vaultId`, with the
188-
`MasterAccountController` contract. Equivalent to sending a
189-
`collateralReservation` instruction and a Upshift `deposit` instruction.
190-
</td>
191-
</tr>
192-
<tbody>
193-
<tr>
194-
<td>&nbsp;01</td>
195-
<td>&nbsp;deposit</td>
196-
<td>
197-
&nbsp;Deposit a `value` of FXRP into the Upshift type vault,
198-
registered with the `vaultId` with the `MasterAccountController`
199-
contract.
200-
</td>
201-
</tr>
202-
<tr>
203-
<td>&nbsp;02</td>
204-
<td>&nbsp;requestRedeem</td>
205-
<td>
206-
&nbsp;Start the withdrawal process for a `value` of FXRP from the
207-
Upshift type vault, registered with the `vaultId` with the
208-
`MasterAccountController` contract.
209-
</td>
210-
</tr>
211-
<tr>
212-
<td>&nbsp;03</td>
213-
<td>&nbsp;claim</td>
214-
<td>
215-
&nbsp;Withdraw the `FXRP`, requested in the `value` period, from
216-
Upshift type vault, registered with the `vaultId` with the
217-
`MasterAccountController` contract.
218-
</td>
219-
</tr>
220-
</tbody>
221-
</table>
222-
<p>&nbsp;</p>
145+
| Command ID | Action | Description |
146+
| ---------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
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. |
151+
223152
</details>
224153

225-
## 2. Payment proof on Flare
154+
## 2. Dispatch on Flare
155+
156+
### Proof-based flow
226157

227158
The operator monitors incoming transactions to the specified XRPL address.
228-
Upon receiving a payment, it makes a [`Payment` attestation request](/fdc/attestation-types/payment) to the FDC.
229-
The `Payment` proof and the user's XRPL address are passed to the `executeTransaction` function on the `MasterAccountController` smart contract on the Flare chain.
159+
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`:
160+
161+
- [`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).
163+
- [`executeDepositAfterMinting`](/smart-accounts/reference/IMasterAccountController#executedepositafterminting) — second leg of the Firelight/Upshift collateral-reservation-and-deposit instructions, after FAssets minting completes.
164+
- [`executeInstruction`](/smart-accounts/reference/IMasterAccountController#executeinstruction) — for all other reference-encoded instructions.
165+
166+
For the proof-bearing functions, the contract verifies the FDC proof and checks that:
230167

231-
The `MasterAccountController` contract first verifies the proof.
232-
It then performs several checks on the proof:
168+
- the receiving address matches the one configured for the operator,
169+
- 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`).
233171

234-
- receiving address matches the one specified by the operator,
235-
- the source address matches the XRPL address given to the function,
236-
- that the proof has not yet been used for the same actions.
172+
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.
237173

238-
Then, the `MasterAccountController` contract retrieves the XRPL user's smart account from a mapping.
239-
If the account does not yet exist, it is created at this point.
174+
### Direct-minting flow
240175

241-
The payment reference is decoded.
242-
Depending on the value of the leading byte, a different function on the smart account is called.
176+
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`.
177+
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`).
243178

244179
## 3. Actions on Flare
245180

246181
The XRPL user's smart account performs the actions in the instructions.
247182
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 ...
248-
Furthermore, custom instructions can be executed - instructions for making any function call on Flare -, thought that requires an additional step for it to work (see the [Custom Instruction guide](/smart-accounts/3-custom-instruction.mdx))
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.
184+
See the [Custom Instruction guide](/smart-accounts/custom-instruction) for the details.
249185

250186
## Video Tutorials
251187

0 commit comments

Comments
 (0)