flare-smart-accounts

Security & Safe Usage

This skill provides informational guidance only.

• It does NOT execute blockchain transactions
• It does NOT store or transmit signing keys
• All signing must occur in user-controlled wallets
• External data should be validated by the developer
• Users are responsible for secure key management

No executable code or automated financial actions are included.

Flare Smart Accounts

What Smart Accounts Are

Flare Smart Accounts provide account abstraction that allows XRPL users to perform actions on the Flare chain without owning any FLR token.

Each XRPL address receives a unique smart account on Flare that only that address can control.

Key benefits:

• No FLR required: Users interact with Flare using only their XRPL wallet
• Single transaction: All instructions are encoded in an XRPL Payment transaction
• Operator-managed gas: A relayer service handles transaction execution on Flare
• Proof-based security: Uses Flare Data Connector (FDC) for payment attestation and verification

How It Works

Flare Smart Accounts support two complementary flows:

Proof-based flow (payment reference)

1. XRPL Instruction: User sends a Payment to the operator's XRPL address, encoding a 32-byte instruction as the payment reference in the memo field.
2. Proof Generation: The operator requests a Payment attestation from the FDC.
3. On-Chain Execution: The operator calls executeInstruction (or reserveCollateral) on MasterAccountController, passing the FDC proof.

The contract verifies the proof, retrieves (or creates) the user's smart account, decodes the payment reference, and executes the requested action.

Direct-minting (memo) flow

1. User sends a Payment to the FAssets Core Vault XRPL address (per FAssets minting) that mints FXRP to the smart account, with the memo field carrying the instruction.
2. An executor calls executeDirectMinting; the FAssets AssetManager mints FXRP to MasterAccountController and calls back into handleMintedFAssets.
3. MasterAccountController routes FAssets to the user's PersonalAccount, optionally pays an executor fee, and dispatches any memo instruction (see Memo Opcodes).

Minting is FAssets minting, not a CRT instruction. User minting of FXRP no longer uses a Smart Accounts collateral-reservation (CRT) instruction. To mint, send an XRPL Payment to the Core Vault with a memo or destination tag as described in FAssets minting. The legacy CRT instructions (0x00, 0x10, 0x20 below) and their CLI encoders may still exist in older tooling but are not the recommended mint path. For mint-and-action in one payment, use a memo-field custom instruction.

Important: XRPL transactions targeting smart accounts must not use a destination tag. A destination tag forces FAssets direct minting to credit the tag-holder instead of the smart account.

Payment Reference Structure (32 Bytes)

All instructions follow this structure:

Instruction Types — Detailed Byte Formats

FXRP Instructions (Type 0x0_)

0x00 — Collateral Reservation (legacy CRT)

Reserve collateral for minting FXRP. Legacy: prefer FAssets minting (XRPL payment to the Core Vault). Documented here for older tooling and historical integrations.

Example: 0x0000000000000000000000010001000000000000000000000000000000000000

• Instruction: 00 (FXRP collateral reservation)
• Wallet ID: 00
• Value: 00000000000000000001 (1 lot)
• Agent Vault ID: 0001

0x01 — Transfer FXRP

Transfer FXRP to a Flare address.

Example: 0x01000000000000000000000af5488132432118596fa13800b68df4c0ff25131d

• Instruction: 01 (FXRP transfer)
• Value: 000000000000000000000a (10 FXRP)
• Recipient: 0xf5488132432118596fa13800b68df4c0ff25131d

0x02 — Redeem FXRP

Redeem FXRP back to XRP on XRPL.

Firelight Instructions (Type 0x1_)

Firelight is a vault protocol for stXRP yield.

0x10 — Collateral Reservation + Deposit (legacy CRT)

Combined mint FXRP and deposit to Firelight vault. Legacy: prefer FAssets minting then the 0x11 deposit instruction, or a memo-field custom instruction for mint-and-deposit in one payment.

0x11 — Deposit

Deposit existing FXRP to Firelight vault.

0x12 — Redeem (Initiate Withdrawal)

Begin withdrawal from Firelight vault.

0x13 — Claim Withdraw

Complete pending withdrawal from Firelight vault.

Upshift Instructions (Type 0x2_)

Upshift is another vault protocol with time-locked withdrawals.

0x20 — Collateral Reservation + Deposit (legacy CRT)

Combined mint FXRP and deposit to Upshift vault. Legacy: prefer FAssets minting then the 0x21 deposit instruction, or a memo-field custom instruction for mint-and-deposit in one payment.

0x21 — Deposit

Deposit existing FXRP to Upshift vault.

0x22 — Request Redeem

Request withdrawal from Upshift vault (starts waiting period).

0x23 — Claim

Complete withdrawal after waiting period expires.

Memo Opcodes (Direct-Minting Flow)

When minting FXRP directly to a smart account via the FAssets direct minting path, the XRPL memo carries one of these opcodes in its first byte:

Custom Instructions — Deep Dive

Custom instructions let an XRPL user execute arbitrary contract calls on Flare through an XRPL Payment. The personal account exposes an EIP-4337 style executeUserOp entry point.

Call Struct

struct Call {
    address target;   // Contract address to call
    uint256 value;    // FLR to send with the call
    bytes data;       // Encoded function calldata
}

PackedUserOperation

Custom instructions are packaged as an EIP-4337 PackedUserOperation. Only three fields are required:

• sender — must equal the personal account address (getPersonalAccount(xrplAddress))
• nonce — must equal the current memo nonce (getNonce(personalAccount))
• callData — abi.encodeCall(IPersonalAccount.executeUserOp, (calls))

Two Variants

Custom Instruction (0xFE) — recommended:

42-byte memo layout:

The user delivers the full PackedUserOperation bytes to an executor off-chain. The executor calls executeDirectMintingWithData(proof, data) on AssetManager with msg.value = sum(call.value). The controller verifies keccak256(_data) == userOpHash before executing. This keeps the XRPL memo constant at 42 bytes regardless of batch size.

executeDirectMintingWithData is fully atomic: it mints FXRP to the personal account and dispatches the user operation in one Flare transaction. If any step reverts (hash mismatch, bad nonce, an inner call failing, insufficient msg.value), the entire transaction rolls back — no FXRP is minted and no UserOperationExecuted event fires. See Failure Handling & Recovery.

Memo Field Custom Instruction (0xFF) — simpler, single-actor:

Memo layout (10-byte header + full payload):

The full PackedUserOperation is inline in the memo. Any indexer can relay via executeDirectMinting(proof). Subject to the XRPL 1024-byte memo cap.

TypeScript Example (Custom Instruction 0xFE)

Use 0xFE when: batch is large, call payload should stay private on XRPL, or you operate an executor. Use 0xFF when: call batch fits in ~1024 bytes and you don't want to coordinate with an executor.

See Custom Instruction Comparison for a detailed trade-off guide.

Moving ERC-20 balances without minting: fee-only custom instructions

A personal account can already hold ERC-20 balances (e.g. USDT0) unrelated to FXRP minting. To transfer or swap that balance, build a 0xFE custom instruction with netMintAmountXrp: 0 — the XRPL payment covers only the direct-minting fee and executor fee, so executeDirectMintingWithData dispatches the user operation without minting any FXRP:

The rest of the flow is the same three-step 0xFE protocol: encode the Call[] batch (e.g. USDT0.transfer(recipient, amount), or approve + SparkDEX exactInputSingle to swap USDT0 → FXRP), commit keccak256(PackedUserOperation) in the 42-byte memo, send the fee-only XRPL payment, then have the executor fetch an FDC proof and call executeDirectMintingWithData. See the Control USDT0 guide for the full runnable example (balance check, transfer, and swap scripts) built on the flare-viem-starter.

Failure Handling & Recovery

The 0xFE / 0xFF direct-minting-with-custom-instruction flow is atomic on the Flare side. When executeDirectMintingWithData (or executeDirectMinting for 0xFF) reverts, the whole Flare transaction rolls back:

• No FXRP is minted on Flare and no user operation runs — there is no UserOperationExecuted event.
• The XRPL payment is not reversed — the underlying XRP stays at the Core Vault until a successful direct mint finalizes it. It is not auto-refunded to the user's XRPL wallet.

The intended UX is mint + user operation in one atomic transaction (e.g. mint FXRP and withdraw to an EOA in a single call), so this failure path should be rare.

Common revert reasons

Any validation/execution failure inside handleMintedFAssets reverts the whole call:

• sender ≠ personal account → InvalidSender
• nonce ≠ current memo nonce (getNonce) → InvalidNonce
• memo length ≠ 42 bytes → InvalidMemoData; unknown instruction byte → InvalidInstructionId
• keccak256(_data) ≠ memo hash → CustomInstructionHashMismatch(expected, actual)
• executor msg.value < sum of inner call.value → inner CallFailed, whole tx reverts
• account has a pinned executor (getExecutor) and caller isn't it → WrongExecutor
• any inner call reverts → surfaced as CallFailed, whole tx reverts

For direct-minting-side errors (rate limits, wrong recipient, unrecognized memo routing to the smart account manager), see the Minting Troubleshooting guide's Smart Account Path section.

"My XRPL transaction succeeded but the instruction never executed" — two common causes account for most of these:

• The personal account has no funds. A custom instruction that sends value out of the personal account (e.g. a LayerZero fee) reverts if that account's native balance is empty, even though the XRPL payment itself looks successful. Fund the personal account address (not the EOA) from the Coston2 faucet before running the script — see State Lookup for deriving that address.
• You're looking at the wrong transaction. MasterAccountController is the entry point, so the dispatched call runs as an internal transaction on the personal account, not a top-level transaction from your own EOA. Check the personal account's internal transactions on the block explorer, not just its top-level transaction list.

Recovery after a failed / stuck mint

If the mint reverted (or the executor never submitted the proof) and the stuck transaction ID is not yet used on-chain (isTransactionIdUsed returns false), the user recovers FXRP without running the original user operation:

1. Send an XRPL Payment with memo opcode 0xE0 (skip memo) targeting the stuck transaction ID. Its memo uses the same 42-byte header shape as 0xFE/0xFF: [0xE0 | walletId(1B) | executorFeeUBA(8B) | targetTxId(32B)]. This payment must carry a positive net mint amount (fee-only direct mints revert on-chain), so it mints a small amount of FXRP itself (e.g. 1 net XRP).
2. The executor calls executeDirectMintingWithData(recoveryProof, "0x") for the recovery payment, which emits IgnoreMemoSet on the personal account, tying it to the stuck transaction ID.
3. The executor re-submits executeDirectMintingWithData for the original stuck payment. Because the skip flag is set, the controller mints FXRP to the personal account without dispatching the original user operation. On retry, pass the original ABI-encoded PackedUserOperation bytes as _data for a 0xFE stuck payment; "0x" suffices for 0xFF.

The recovered FXRP can then be moved via standard FAssets instructions (0x02 redeem) or a fresh user operation using the current getNonce. Related recovery opcodes: 0xE1 (fast-forward nonce) and 0xE2 (replace executor fee for a stuck payment). See the Recover Stuck Mint Transaction guide.

Fast-forwarding a stuck nonce (0xE1)

0xE0 recovery mints FXRP from the stuck payment but deliberately skips the original user operation — the memo-instruction nonce stays where it was, still pointing at the abandoned PackedUserOperation. Use 0xE1 (fast-forward nonce) to jump getNonce forward past that abandoned slot before building a fresh 0xFE/0xFF instruction. Only do this after confirming the stuck payment is actually minted (isTransactionIdUsed == true) — if it isn't minted yet, run 0xE0 recovery first, not 0xE1.

1. Send an XRPL Payment with memo opcode 0xE1, same 42-byte header shape as the other recovery opcodes: [0xE1 | walletId(1B) | executorFeeUBA(8B) | newNonce(32B)]. Like 0xE0, this payment must carry a positive net mint amount — fee-only direct mints revert on-chain.
2. Validate newNonce client-side before sending: it must be strictly greater than the current getNonce, and the jump (newNonce - currentNonce) must not exceed type(uint32).max. On-chain, an invalid jump reverts with InvalidNonceIncrease.
3. The executor calls executeDirectMintingWithData(proof, "0x") for the 0xE1 payment — no _data is needed since no user operation runs. On success the receipt has a NonceIncreased(personalAccount, newNonce) event and no UserOperationExecuted event.
4. Build the next 0xFE/0xFF user operation with nonce == getNonce(personalAccount) (now newNonce).

See the Fast-Forward Nonce guide for the full runnable walkthrough, including the combined 0xFE (abandoned) → 0xE0 → 0xE1 recovery demo.

Avoiding duplicate-nonce failures

A common revert cause is submitting two XRPL payments in short succession, each embedding a different PackedUserOperation but both using the same getNonce value (e.g. two withdraw attempts built before either mint finalizes). Only one payment can consume a given nonce — whichever mint executes first succeeds and increments the nonce; the other reverts with InvalidNonce, leaving its XRP at the Core Vault until recovered. To avoid this:

• Read getNonce once per XRPL payment; do not reuse it across concurrent flows.
• Wait for the first mint to finalize — or confirm it reverted — before building another payment with a new user operation.
• Executors: if the AssetManager emits DirectMintingDelayed, wait until executionAllowedAt and re-call executeDirectMintingWithData. Do not treat a delayed mint as a hard failure and prompt the user to resend a duplicate-nonce payment.

CLI Tool — Complete Reference

The smart-accounts-cli is a Python tool for constructing XRPL transaction payloads and submitting XRPL payments for smart-account flows.

Installation

Environment Configuration (.env)

Copy .env.example to .env and fill in the values described in that file. These typically include local wallet credentials for test usage plus RPC endpoints for XRPL and Flare networks.

Security: Keep wallet credentials in secure, user-controlled tooling. Avoid pasting them into chat tools or unsecured automation. Get XRPL testnet tokens from XRP Faucets.

Command Syntax

ENCODE Commands

All encode commands accept --wallet-id (defaults to 0).

FXRP Operations

Legacy mint path. fxrp-cr (+ bridge mint-tx) encodes the deprecated collateral-reservation (CRT) flow and may still exist in smart_accounts.py, but it is not the recommended mint path. To mint FXRP, use FAssets minting (XRPL payment to the Core Vault) per the Mint FXRP guide; the CLI does not encode that payment. The fxrp-transfer and fxrp-redeem commands below remain current.

Firelight Operations

firelight-cr-deposit is legacy (CRT mint + deposit). Prefer FAssets minting then firelight-deposit, or a memo-field custom instruction for mint-and-deposit in one payment.

Upshift Operations

upshift-cr-deposit is legacy (CRT mint + deposit). Prefer FAssets minting then upshift-deposit, or a memo-field custom instruction for mint-and-deposit in one payment.

BRIDGE Commands

Execute XRPL transactions.

The operator service bridges to Flare.

DECODE Command

Reverse encode operation to inspect instruction:

Command Chaining (Piping)

Chain commands for complete workflows:

Complete Workflow Examples

Note on the mint steps below. The fxrp-cr / upshift-cr-deposit + bridge mint-tx steps use the legacy collateral-reservation (CRT) mint path. In current integrations, mint FXRP via FAssets minting (XRPL payment to the Core Vault, see Mint FXRP), then run the non-mint Smart Accounts instructions (transfer, deposit, redeem) shown here. The examples are retained to illustrate the CLI's instruction/bridge piping.

Example 1: Mint FXRP and Transfer to Another Address

Example 2: Full FAssets Cycle (Mint → Deposit → Withdraw → Redeem)

Core Contract: MasterAccountController

The MasterAccountController is the central contract for smart accounts.

TypeScript Integration (Viem)

Packages: viem, xrpl. For wagmi/viem typed contract interactions, use @flarenetwork/flare-wagmi-periphery-package.

Setup

Read Smart Account State

Send XRPL Payment with Instruction

Key Notes

• Lot size: 1 lot = 10 FXRP (check current lot size via AssetManager)

• Value encoding: For most instructions, value is in lots; for Upshift claim, it's a date (YYYYMMDD).

• Wallet ID: Use 0 if not assigned by Flare operator.

• Upshift withdrawals: Two-phase process (request-redeem → wait → claim).

• CLI execution: The CLI submits XRPL-side transactions only.

  Flare-side handling is performed by the relayer/operator service.

Security and usage considerations

This skill is reference documentation only. It does not execute transactions or hold keys. Use it to implement or debug smart-account flows; all financial execution remains the responsibility of the developer and end user.

Third-party data (payment memos, RPC state): Incoming XRPL payment memos and on-chain data from RPC endpoints (e.g. XRPL testnet, Coston2) are untrusted external inputs. Decode memos only according to the fixed 32-byte instruction format in this document and treat them as structured payloads rather than free-form text. Keep raw memo and transaction content out of free-form AI processing unless it has first been parsed into validated, typed values.

Financial operations and keys: Commands and code in this skill (CLI bridge commands, submitAndWait, etc.) can move funds. Keep wallet credentials in secure, user-controlled environments. Any execution of payments or bridge instructions should be explicitly user-initiated, with transaction details reviewed before submission.

When to Use This Skill

• Implementing XRPL-to-Flare interactions without requiring users to hold FLR
• Building dApps that let XRPL users mint FXRP or interact with Flare vaults
• Creating custom instructions for arbitrary contract calls from XRPL
• Debugging smart account flows, payment references, or instruction encoding
• Integrating with MasterAccountController or monitoring smart account events
• Using the smart-accounts-cli for testing or automation

Additional Resources

• Official docs and guides: reference.md
• Related skill: flare-fassets — for FAssets minting, redemption, and agent details.