Skip to content

feat(docs): add hash custom instructions and rearange guides #1400

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nikerzetic-aflabs merged 6 commits into from
May 21, 2026
Merged

feat(docs): add hash custom instructions and rearange guides #1400

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
6591206
refactor(docs): rename
nikerzetic-aflabs May 20, 2026
e1405d4
feat(docs): add hash custom instruction guides
nikerzetic-aflabs May 20, 2026
aab74ca
refactor(docs): make hash custom instruction the preferred one
nikerzetic-aflabs May 20, 2026
97970aa
fix(docs): sentence newline
nikerzetic-aflabs May 20, 2026
dddcfaf
fix(docs): apply suggested changes
nikerzetic-aflabs May 21, 2026
d0c9a6f
fix(docs): apply additional suggested changes
nikerzetic-aflabs May 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 33 additions & 16 deletions docs/smart-accounts/1-overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ Flare Smart Accounts support two complementary flows for turning an XRPL `Paymen
### Proof-based flow (payment reference)

1. The XRPL user sends a `Payment` transaction to the operator's XRPL address with a 32-byte instruction encoded as the **payment reference**.
2. The operator requests a [`Payment` attestation](/fdc/attestation-types/payment) from the [Flare Data Connector](/fdc/overview) and submits it to the `MasterAccountController`.
2. The operator requests a [`Payment` attestation](/fdc/attestation-types/payment) from the [Flare Data Connector (FDC)](/fdc/overview) and submits it to the `MasterAccountController`.
3. The XRPL user's `PersonalAccount` performs the action encoded in the reference.

<ThemedImage
Expand All @@ -51,9 +51,9 @@ Flare Smart Accounts support two complementary flows for turning an XRPL `Paymen

### Direct-minting (memo) flow

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.
2. The FAssets `AssetManager` mints FXRP to the `MasterAccountController` and calls back into [`mintedFAssets`](/smart-accounts/reference/IMasterAccountController#mintedfassets) on `MemoInstructionsFacet`.
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).
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-comparison) carrying the instruction.
2. The FAssets `AssetManager` mints FXRP to the `MasterAccountController` and calls back into [`handleMintedFAssets`](/smart-accounts/reference/IMasterAccountController#handlemintedfassets).
3. The `MasterAccountController` routes the FAssets to the user's `PersonalAccount`, optionally pays an executor fee, and dispatches any [memo instruction](#memo-opcodes-direct-minting-flow).

```mermaid
graph TB
Expand All @@ -65,16 +65,16 @@ graph TB
subgraph Flare["Flare"]
Executor[("<b>Executor</b><br/><i>backend</i>")]
AssetManager["<b>FAssets AssetManager</b><br/><i>contract</i>"]
MAC["<b>MasterAccountController</b><br/><i>contract</i>"]
PA["<b>PersonalAccount</b><br/><i>contract</i>"]
MasterAccountController["<b>MasterAccountController</b><br/><i>contract</i>"]
PersonalAccount["<b>PersonalAccount</b><br/><i>contract</i>"]
end

User -- "1 - Payment + memo" --> Agent
Agent -. "2 - observe payment" .-> Executor
Executor -- "3 - executeDirectMinting" --> AssetManager
AssetManager == "4 - mint FXRP +<br/>mintedFAssets callback" ==> MAC
MAC -- "5 - forward FXRP +<br/>dispatch memo instruction" --> PA
User -. "controls" .-> PA
AssetManager == "4 - mint FXRP +<br/>handleMintedFAssets callback" ==> MasterAccountController
MasterAccountController -- "5 - forward FXRP +<br/>dispatch memo instruction" --> PersonalAccount
User -. "controls" .-> PersonalAccount

style Flare stroke-dasharray: 5 5
style XRPL stroke-dasharray: 5 5
Expand All @@ -83,7 +83,7 @@ graph TB
<p style={{ textAlign: "center", fontStyle: "italic" }}>
Direct-minting flow: XRPL `Payment` carrying a memo (1) → FAssets agent (2) →
executor calls `AssetManager.executeDirectMinting` (3) → `AssetManager` mints
FXRP and calls back into `mintedFAssets` (4) → `MasterAccountController`
FXRP and calls back into `handleMintedFAssets` (4) → `MasterAccountController`
forwards FXRP and dispatches the memo to the user's `PersonalAccount` (5).
</p>

Expand All @@ -106,7 +106,7 @@ The first nibble is the instruction type.
This is either `FXRP`, `Firelight`, or `Upshift` (with corresponding type IDS `0`, `1`, and `2`).
The second nibble is the instruction command; the available commands are different for each instruction type.

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.
For the direct-minting flow, the memo carries a different layout; the first byte selects one of the [memo opcodes](#memo-opcodes-direct-minting-flow) listed below.

<details>
<summary>Table of instruction IDs and corresponding actions.</summary>
Expand Down Expand Up @@ -151,12 +151,28 @@ Instructions for interacting with an Upshift-type vault.

</details>

### Memo opcodes (direct-minting flow)

The XRPL memo for the direct-minting flow selects one of the following opcodes in its first byte:

| Memo opcode | Action | Description |
| ----------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `0xFE` | Custom Instruction | Carry `keccak256(PackedUserOperation)` in the memo; the bytes are delivered off-chain by an executor. See [Custom Instruction](/smart-accounts/custom-instruction). |
| `0xFF` | Raw Custom Instruction | Carry the full ABI-encoded `PackedUserOperation` inline in the memo. See [Raw Custom Instruction](/smart-accounts/raw-custom-instruction). |
| `0xE0` | Skip memo | Mark a target XRPL transaction's memo to be skipped on its next direct mint. |
| `0xE1` | Fast-forward nonce | Advance the personal account's memo-instruction nonce. |
| `0xE2` | Replace executor fee | Set a replacement executor fee for a stuck XRPL transaction. |
| `0xD0` | Pin executor | Pin a specific executor address to the personal account. |
| `0xD1` | Unpin executor | Unpin the executor from the personal account. |

The [Custom Instruction Comparison](/smart-accounts/custom-instruction-comparison) covers when to choose `0xFE` over `0xFF`.

## Dispatch on Flare

### Proof-based flow

The operator monitors incoming transactions to the specified XRPL address.
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`:
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 function on the `MasterAccountController`:

- [`reserveCollateral`](/smart-accounts/reference/IMasterAccountController#reservecollateral) — for command `00` of any instruction type.
Takes the payment reference and XRPL transaction ID (no FDC proof needed at this stage, the user has only committed to mint).
Expand All @@ -173,16 +189,17 @@ The contract then resolves the XRPL user's `PersonalAccount` from the address ma

### Direct-minting flow

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`.
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`).
When the user mints FXRP directly to their smart account via [FAssets direct minting](/fassets/direct-minting), the FAssets `AssetManager` calls back into [`handleMintedFAssets`](/smart-accounts/reference/IMasterAccountController#handlemintedfassets) on the `MasterAccountController`.
It 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](#memo-opcodes-direct-minting-flow).

## Actions on Flare

The XRPL user's smart account performs the actions in the instructions.
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 ...
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.
Furthermore, custom instructions can be executed - arbitrary function calls on Flare, encoded as an [EIP-4337](https://eips.ethereum.org/EIPS/eip-4337) `PackedUserOperation` and replayed on-chain by the personal account.
The user operation can be committed to as a 32-byte hash with the bytes delivered to Flare by an off-chain executor (opcode `0xFE`, see the [Custom Instruction guide](/smart-accounts/custom-instruction)), or carried in the XRPL memo in full (opcode `0xFF`, see the [Raw Custom Instruction guide](/smart-accounts/raw-custom-instruction)).
Authorization comes from the XRPL `Payment` signature itself; the on-chain check only validates the `sender` and `nonce` fields of the `PackedUserOperation`.
See the [Custom Instruction guide](/smart-accounts/custom-instruction) for the details.
The [Custom Instruction Comparison](/smart-accounts/custom-instruction-comparison) covers when to pick each.

## Video Tutorials

Expand Down
Loading
Loading