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: An operator 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

solidity

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:

solidity

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

typescript

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 and sending XRPL transactions.

Installation

bash

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)

env

XRPL_SECRET=<your-xrpl-testnet-secret>
FLARE_PRIVATE_KEY=<your-flare-private-key>
COSTON2_RPC_URL=https://coston2-api.flare.network/ext/C/rpc
XRPL_RPC_URL=wss://s.altnet.rippletest.net:51233

Get XRPL testnet credentials from XRP Faucets.

Command Syntax

bash

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

ENCODE Commands

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

FXRP Operations

bash

# 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

bash

# 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

bash

# 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.

bash

# 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:

bash

./smart_accounts.py decode <encodedInstruction>

# Or from stdin
<encode_command> | ./smart_accounts.py decode -

Command Chaining (Piping)

Chain commands for complete workflows:

bash

# 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

bash

# 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)

bash

# 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)

Setup

typescript

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

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

Read Smart Account State

typescript

// 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

typescript

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: Only executes XRPL transactions.

Flare bridging is handled by the operator.

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.

Flare Smart Accounts

What Smart Accounts Are

How It Works

Payment Reference Structure (32 Bytes)

Instruction Types — Detailed Byte Formats

FXRP Instructions (Type 0x0_)

0x00 — Collateral Reservation

0x01 — Transfer FXRP

0x02 — Redeem FXRP

Firelight Instructions (Type 0x1_)

0x10 — Collateral Reservation + Deposit

0x11 — Deposit

0x12 — Redeem (Initiate Withdrawal)

0x13 — Claim Withdraw

Upshift Instructions (Type 0x2_)

0x20 — Collateral Reservation + Deposit

0x21 — Deposit

0x22 — Request Redeem

0x23 — Claim

Custom Instructions (Type 0xff)

Custom Instructions — Deep Dive

CustomCall Struct

Call Hash Generation

Registration Workflow

TypeScript Example

CLI Tool — Complete Reference

Installation

Environment Configuration (.env)

Command Syntax

ENCODE Commands

FXRP Operations

Firelight Operations

Upshift Operations

BRIDGE Commands

DECODE Command

Command Chaining (Piping)

Complete Workflow Examples

Example 1: Mint FXRP and Transfer to Another Address

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

Core Contract: MasterAccountController

TypeScript Integration (Viem)

Setup

Read Smart Account State

Send XRPL Payment with Instruction

Key Notes

When to Use This Skill

Additional Resources

FXRP Instructions (Type `0x0_`)

`0x00` — Collateral Reservation

`0x01` — Transfer FXRP

`0x02` — Redeem FXRP

Firelight Instructions (Type `0x1_`)

`0x10` — Collateral Reservation + Deposit

`0x11` — Deposit

`0x12` — Redeem (Initiate Withdrawal)

`0x13` — Claim Withdraw

Upshift Instructions (Type `0x2_`)

`0x20` — Collateral Reservation + Deposit

`0x21` — Deposit

`0x22` — Request Redeem

`0x23` — Claim

Custom Instructions (Type `0xff`)