flare-smart-accounts

name	flare-smart-accounts
description	Provides domain knowledge and guidance for Flare Smart Accounts—account abstraction that allows XRPL users to interact with Flare without owning FLR. Use when working with smart accounts, XRPL-to-Flare transactions, MasterAccountController, custom instructions, Firelight/Upshift vault interactions, or the smart-accounts CLI.

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:

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

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

3. 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:

1. ABI encodes the CustomCall[] array
2. Applies keccak256 hash
3. Masks to 30 bytes (removes first 2 bytes)

The MasterAccountController provides encodeCustomInstruction() helper function.

Registration Workflow

1. Encode calldata using abi.encodeWithSignature() or Viem's encodeFunctionData()
2. Register instruction by calling registerCustomInstruction(CustomCall[]) on MasterAccountController
3. Get call hash using encodeCustomInstruction(CustomCall[])
4. Build payment reference: 0xff + walletId (1 byte) + callHash (30 bytes)
5. 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.