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

The workflow consists of three steps:

XRPL Instruction: User sends a Payment transaction on XRPL to a designated operator address, encoding instructions in the memo field as a 32-byte payment reference.

Proof Generation: The operator monitors incoming XRPL transactions and requests a Payment attestation from the FDC.

On-Chain Execution: The operator calls executeTransaction on the MasterAccountController contract on Flare, passing the proof.

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

Payment Reference Structure (32 Bytes)

All instructions follow this structure:

Byte Position Field Description

Byte 1 Instruction ID First nibble = type (0-F), second nibble = command (0-F)

Byte 2 Wallet ID Operator-assigned wallet identifier (use 0 if unassigned)

Bytes 3-12 Value 10-byte encoded amount (lots of FXRP or XRP)

Bytes 13+ Parameters Instruction-specific data

Instruction Types — Detailed Byte Formats

FXRP Instructions (Type 0x0_ )

0x00 — Collateral Reservation

Reserve collateral for minting FXRP.

Bytes Field Description

1 0x00

Instruction ID

2 walletId Wallet identifier

3-12 value Number of lots to mint (10 bytes)

13-14 agentVaultId Agent vault identifier (2 bytes)

15-32 — Arbitrary (ignored)

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.

Bytes Field Description

1 0x01

Instruction ID

2 walletId Wallet identifier

3-12 value Amount of FXRP to transfer (10 bytes)

13-32 recipientAddress Destination Flare address (20 bytes)

Example: 0x01000000000000000000000af5488132432118596fa13800b68df4c0ff25131d

• Instruction: 01 (FXRP transfer)

• Value: 000000000000000000000a (10 FXRP)

• Recipient: 0xf5488132432118596fa13800b68df4c0ff25131d

0x02 — Redeem FXRP

Redeem FXRP back to XRP on XRPL.

Bytes Field Description

1 0x02

Instruction ID

2 walletId Wallet identifier

3-12 value Number of lots to redeem (10 bytes)

13-32 — Arbitrary (ignored)

Firelight Instructions (Type 0x1_ )

Firelight is a vault protocol for stXRP yield.

0x10 — Collateral Reservation + Deposit

Combined mint FXRP and deposit to Firelight vault.

Bytes Field Description

1 0x10

Instruction ID

2 walletId Wallet identifier

3-12 value Number of lots (10 bytes)

13-14 agentVaultId Agent vault identifier (2 bytes)

15-16 vaultId Firelight vault identifier (2 bytes)

17-32 — Arbitrary (ignored)

0x11 — Deposit

Deposit existing FXRP to Firelight vault.

Bytes Field Description

1 0x11

Instruction ID

2 walletId Wallet identifier

3-12 value FXRP amount to deposit (10 bytes)

13-14 — Arbitrary (ignored)

15-16 vaultId Firelight vault identifier (2 bytes)

17-32 — Arbitrary (ignored)

0x12 — Redeem (Initiate Withdrawal)

Begin withdrawal from Firelight vault.

Bytes Field Description

1 0x12

Instruction ID

2 walletId Wallet identifier

3-12 value Amount to withdraw (10 bytes)

13-14 — Arbitrary (ignored)

15-16 vaultId Firelight vault identifier (2 bytes)

17-32 — Arbitrary (ignored)

0x13 — Claim Withdraw

Complete pending withdrawal from Firelight vault.

Bytes Field Description

1 0x13

Instruction ID

2 walletId Wallet identifier

3-12 value Amount to claim (10 bytes)

13-14 — Arbitrary (ignored)

15-16 vaultId Firelight vault identifier (2 bytes)

17-32 — Arbitrary (ignored)

Upshift Instructions (Type 0x2_ )

Upshift is another vault protocol with time-locked withdrawals.

0x20 — Collateral Reservation + Deposit

Combined mint FXRP and deposit to Upshift vault.

Bytes Field Description

1 0x20

Instruction ID

2 walletId Wallet identifier

3-12 value Number of lots (10 bytes)

13-14 agentVaultId Agent vault identifier (2 bytes)

15-16 vaultId Upshift vault identifier (2 bytes)

17-32 — Arbitrary (ignored)

0x21 — Deposit

Deposit existing FXRP to Upshift vault.

Bytes Field Description

1 0x21

Instruction ID

2 walletId Wallet identifier

3-12 value FXRP amount to deposit (10 bytes)

13-14 — Arbitrary (ignored)

15-16 vaultId Upshift vault identifier (2 bytes)

17-32 — Arbitrary (ignored)

0x22 — Request Redeem

Request withdrawal from Upshift vault (starts waiting period).

Bytes Field Description

1 0x22

Instruction ID

2 walletId Wallet identifier

3-12 value Amount to withdraw (10 bytes)

13-14 — Arbitrary (ignored)

15-16 vaultId Upshift vault identifier (2 bytes)

17-32 — Arbitrary (ignored)

0x23 — Claim

Complete withdrawal after waiting period expires.

Bytes Field Description

1 0x23

Instruction ID

2 walletId Wallet identifier

3-12 value Date in YYYYMMDD format (e.g., 20251218 for Dec 18, 2025)

13-14 — Arbitrary (ignored)

15-16 vaultId Upshift vault identifier (2 bytes)

17-32 — Arbitrary (ignored)

Custom Instructions (Type 0xff )

Execute arbitrary contract calls on Flare.

Bytes Field Description

1 0xff

Custom instruction marker

2 walletId Wallet identifier

3-32 callHash 30-byte truncated keccak256 hash of encoded CustomCall array

Custom Instructions — Deep Dive

CustomCall Struct

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

Call Hash Generation

The call hash is computed as:

bytes32(uint256(keccak256(abi.encode(_customInstruction))) & ((1 << 240) - 1))

This process:

• ABI encodes the CustomCall[] array

• Applies keccak256 hash

• Masks to 30 bytes (removes first 2 bytes)

The MasterAccountController provides encodeCustomInstruction() helper function.

Registration Workflow

• Encode calldata using abi.encodeWithSignature() or Viem's encodeFunctionData()

• Register instruction by calling registerCustomInstruction(CustomCall[]) on MasterAccountController

• Get call hash using encodeCustomInstruction(CustomCall[])

• Build payment reference: 0xff

• walletId (1 byte) + callHash (30 bytes)

• Send XRPL Payment with the payment reference in the memo field

TypeScript Example

import { encodeFunctionData, toHex } from "viem";

type CustomInstruction = { targetContract: Address; value: bigint; data: 0x${string}; };

// Build custom instructions const customInstructions: CustomInstruction[] = [ { targetContract: checkpointAddress, value: BigInt(0), data: encodeFunctionData({ abi: checkpointAbi, functionName: "passCheckpoint", args: [], }), }, { targetContract: piggyBankAddress, value: BigInt(depositAmount), data: encodeFunctionData({ abi: piggyBankAbi, functionName: "deposit", args: [], }), }, ];

// Register with MasterAccountController const { request } = await publicClient.simulateContract({ account: account, address: MASTER_ACCOUNT_CONTROLLER_ADDRESS, abi: masterAccountControllerAbi, functionName: "registerCustomInstruction", args: [customInstructions], }); await walletClient.writeContract(request);

// Get encoded instruction for XRPL payment const encodedInstruction = await publicClient.readContract({ address: MASTER_ACCOUNT_CONTROLLER_ADDRESS, abi: masterAccountControllerAbi, functionName: "encodeCustomInstruction", args: [customInstructions], });

// Build final payment reference const walletId = 0; const paymentReference = ("0xff" + toHex(walletId, { size: 1 }).slice(2) + encodedInstruction.slice(6)) as 0x${string};

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

git clone https://github.com/flare-foundation/smart-accounts-cli.git cd smart-accounts-cli pip install -r requirements.txt cp .env.example .env

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

./smart_accounts.py <command> <subcommand> [options]

ENCODE Commands

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

FXRP Operations

Collateral reservation for minting

./smart_accounts.py encode fxrp-cr --wallet-id 0 --value 1 --agent-vault-id 1

Transfer FXRP to address

./smart_accounts.py encode fxrp-transfer --wallet-id 0 --value 10
--recipient-address "0xf5488132432118596fa13800b68df4c0ff25131d"

Redeem FXRP to XRP

./smart_accounts.py encode fxrp-redeem --wallet-id 0 --value 1

Firelight Operations

Reserve collateral and deposit to vault

./smart_accounts.py encode firelight-cr-deposit --wallet-id 0 --value 1
--agent-vault-id 1 --vault-id 1

Deposit FXRP to vault

./smart_accounts.py encode firelight-deposit --wallet-id 0 --value 10 --vault-id 1

Initiate withdrawal

./smart_accounts.py encode firelight-redeem --wallet-id 0 --value 10 --vault-id 1

Claim completed withdrawal

./smart_accounts.py encode firelight-claim-withdraw --wallet-id 0 --value 10 --vault-id 1

Upshift Operations

Reserve collateral and deposit to vault

./smart_accounts.py encode upshift-cr-deposit --wallet-id 0 --value 1
--agent-vault-id 1 --vault-id 2

Deposit FXRP to vault

./smart_accounts.py encode upshift-deposit --wallet-id 0 --value 10 --vault-id 2

Request withdrawal (starts waiting period)

./smart_accounts.py encode upshift-request-redeem --wallet-id 0 --value 10 --vault-id 2

Claim after waiting period (value = date YYYYMMDD)

./smart_accounts.py encode upshift-claim --wallet-id 0 --value 20251218 --vault-id 2

BRIDGE Commands

Execute XRPL transactions.

The operator service bridges to Flare.

Send encoded instruction as XRPL Payment

./smart_accounts.py bridge instruction <encodedInstruction>

Or read from stdin

<encode_command> | ./smart_accounts.py bridge instruction -

Send XRP to agent vault for minting (after collateral reservation)

./smart_accounts.py bridge mint-tx <transactionHash>

With --wait flag to wait for confirmation

./smart_accounts.py bridge mint-tx --wait -

DECODE Command

Reverse encode operation to inspect instruction:

./smart_accounts.py decode <encodedInstruction>

Or from stdin

<encode_command> | ./smart_accounts.py decode -

Command Chaining (Piping)

Chain commands for complete workflows:

Mint FXRP (reserve + pay in one pipeline)

./smart_accounts.py encode fxrp-cr --wallet-id 0 --value 1 --agent-vault-id 1
| ./smart_accounts.py bridge instruction -
| ./smart_accounts.py bridge mint-tx --wait -

Mint and deposit to Upshift vault

./smart_accounts.py encode upshift-cr-deposit --wallet-id 0 --value 1
--agent-vault-id 1 --vault-id 2
| ./smart_accounts.py bridge instruction -
| ./smart_accounts.py bridge mint-tx --wait -

Complete Workflow Examples

Example 1: Mint FXRP and Transfer to Another Address

Step 1: Mint 1 lot of FXRP

./smart_accounts.py encode fxrp-cr --wallet-id 0 --value 1 --agent-vault-id 1
| ./smart_accounts.py bridge instruction -
| ./smart_accounts.py bridge mint-tx --wait -

Output: sent bridge instruction transaction: 08C2DD9E...

sent mint tx: CD15241A...

Step 2: Transfer 10 FXRP to recipient

./smart_accounts.py encode fxrp-transfer --wallet-id 0 --value 10
--recipient-address "0xf5488132432118596fa13800b68df4c0ff25131d"
| ./smart_accounts.py bridge instruction -

Output: sent bridge instruction transaction: 9D5420C6...

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

Step 1: Mint and deposit to Upshift vault

./smart_accounts.py encode upshift-cr-deposit --wallet-id 0 --value 1
--agent-vault-id 1 --vault-id 2
| ./smart_accounts.py bridge instruction -
| ./smart_accounts.py bridge mint-tx --wait -

Output: sent bridge instruction transaction: 77539CDE...

sent mint tx: 3C65E10D...

Step 2: Request withdrawal from vault

./smart_accounts.py encode upshift-request-redeem --wallet-id 0 --value 10 --vault-id 2
| ./smart_accounts.py bridge instruction -

Output: sent bridge instruction transaction: 33B08253...

Step 3: Claim withdrawal after waiting period (use correct date)

./smart_accounts.py encode upshift-claim --wallet-id 0 --value 20251218 --vault-id 2
| ./smart_accounts.py bridge instruction -

Output: sent bridge instruction transaction: 8D81F5A2...

Step 4: Redeem FXRP back to XRP

./smart_accounts.py encode fxrp-redeem --wallet-id 0 --value 1
| ./smart_accounts.py bridge instruction -

Output: sent bridge instruction transaction: FE9D0039...

Core Contract: MasterAccountController

The MasterAccountController is the central contract for smart accounts.

Function Purpose

getPersonalAccount(xrplAddress)

Get user's smart account address on Flare

getXrplProviderWallets()

Get operator XRPL addresses for payments

getVaults()

List registered vault addresses and types

getAgentVaults()

List FAssets agent vaults

registerCustomInstruction(calls)

Register custom instruction for later execution

encodeCustomInstruction(calls)

Get encoded hash for custom instruction

executeTransaction(proof, xrplAddress)

Execute instruction with FDC proof

TypeScript Integration (Viem)

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

Setup

import { createPublicClient, http } from "viem"; import { flareTestnet } from "viem/chains";

const publicClient = createPublicClient({ chain: flareTestnet, transport: http(), });

Read Smart Account State

// Get user's smart account address const personalAccount = await publicClient.readContract({ address: MASTER_ACCOUNT_CONTROLLER_ADDRESS, abi: masterAccountControllerAbi, functionName: "getPersonalAccount", args: [xrplAddress], });

// Get operator XRPL addresses const operatorAddresses = await publicClient.readContract({ address: MASTER_ACCOUNT_CONTROLLER_ADDRESS, abi: masterAccountControllerAbi, functionName: "getXrplProviderWallets", args: [], });

// Get registered vaults const vaults = await publicClient.readContract({ address: MASTER_ACCOUNT_CONTROLLER_ADDRESS, abi: masterAccountControllerAbi, functionName: "getVaults", args: [], });

// Get FXRP balance const fxrpBalance = await publicClient.readContract({ address: fxrpAddress, abi: erc20Abi, functionName: "balanceOf", args: [personalAccount], });

Send XRPL Payment with Instruction

import { Client, Wallet } from "xrpl";

async function sendInstruction(encodedInstruction: 0x${string}) { const operatorAddress = (await getOperatorXrplAddresses())[0]; const instructionFee = await getInstructionFee(encodedInstruction);

const payment = { TransactionType: "Payment", Destination: operatorAddress, Amount: instructionFee, Memos: [{ Memo: { MemoData: encodedInstruction.slice(2) } }], };

return await xrplClient.submitAndWait(payment, { wallet: xrplWallet }); }

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.