Smart accounts encoder

Smart Accounts Encoder is a TypeScript library designed to simplify the encoding and decoding of instructions used in the Flare smart accounts workflow. It provides a unified interface and strongly typed classes for constructing, encoding, and decoding instructions. This enables developers to work with human-readable data structures in their applications. The library ensures correct encoding and decoding of instructions that are sent as memo fields of XRPL Payment transactions.

Repository structure

smart-accounts-encoder
├── src                              # Source code for the library
│   ├── common                      # Shared logic and definitions
│   │   ├── types                   # Type definitions used across the codebase
│   │   │   └── common.types.ts     # Common TypeScript types for smart account structures
│   │   └── utils                   # Utility functions
│   │       ├── encoding.utils.test.ts  # Unit tests for encoding utilities
│   │       └── encoding.utils.ts       # Encoding helper functions
│   ├── instructions                # All smart account instruction definitions
│   │   ├── firelight               # Firelight instructions
│   │   ├── fxrp                    # FXRP instructions
│   │   ├── upshift                 # Upshift instructions
│   │   ├── base-instruction.ts     # Base class for smart account instructions
│   │   └── instructions.ts         # A registry of available instructions
│   └── index.ts                    # Main export file for the library
├── eslint.config.mjs               # ESLint configuration
├── package.json                    # Project metadata and dependencies
├── pnpm-lock.yaml                  # Lock file for reproducible installs with pnpm
├── README.md                       # This documentation file
├── tsconfig.build.json             # TypeScript configuration for publishing to npm
└── tsconfig.json                   # General TypeScript configuration

Installation

npm install smart-accounts-encoder
# or
pnpm install smart-accounts-encoder
# or
yarn add smart-accounts-encoder

Usage

Basic Example

The library provides classes for encoding and decoding smart account instructions. Each instruction can be created with input data, encoded to a hex string, and decoded back to an instruction instance. This allows for operating with human-readable data, while the library takes care of the encoding and decoding.

import { FXRPCollateralReservationInstruction } from "smart-accounts-encoder";

// Create an instruction
const instruction = new FXRPCollateralReservationInstruction({
  walletId: 42,
  value: 1,
  agentVaultId: 1,
});

// Encode to hex string
const hex = instruction.encode();
console.log(hex); // "0x002a0000000000000000010001..."

// Decode from hex string
const decoded = FXRPCollateralReservationInstruction.decode(hex);
console.log(decoded.data); // { walletId: 42, value: 1, agentVaultId: 1 }

Instruction Types

FXRP Instructions

• CollateralReservation: Reserve collateral for FXRP minting
• Transfer: Transfer FXRP tokens to another Flare account
• Redeem: Redeem FXRP tokens to XRP

import {
  FXRPCollateralReservationInstruction,
  FXRPTransferInstruction,
  FXRPRedeemInstruction,
} from "smart-accounts-encoder";

// Collateral Reservation
const collateral = new FXRPCollateralReservationInstruction({
  walletId: 42,
  value: 1,
  agentVaultId: 1,
});

// Transfer
const transfer = new FXRPTransferInstruction({
  walletId: 42,
  value: 1,
  recipientAddress: "f5488132432118596fa13800b68df4c0ff25131d",
});

// Redeem
const redeem = new FXRPRedeemInstruction({
  walletId: 42,
  value: 1,
});

Firelight Instructions

• CollateralReservationAndDeposit: Reserve collateral and deposit in one operation
• Deposit: Deposit FXRP to a Firelight vault
• Redeem: Start the redeem process from a Firelight vault
• ClaimWithdraw: Claim withdrawal of FXRP from a Firelight vault

import {
  FirelightCollateralReservationAndDepositInstruction,
  FirelightDepositInstruction,
  FirelightRedeemInstruction,
  FirelightClaimWithdrawInstruction,
} from "smart-accounts-encoder";

// Collateral Reservation and Deposit
const collateralDeposit = new FirelightCollateralReservationAndDepositInstruction({
  walletId: 42,
  value: 1,
  agentVaultId: 1,
  vaultId: 2,
});

// Deposit
const deposit = new FirelightDepositInstruction({
  walletId: 42,
  value: 1,
  agentVaultId: 1,
  vaultId: 2,
});

// Redeem
const redeem = new FirelightRedeemInstruction({
  walletId: 42,
  value: 1,
  agentVaultId: 1,
  vaultId: 2,
});

// Claim Withdraw
const claimWithdraw = new FirelightClaimWithdrawInstruction({
  walletId: 42,
  period: 1,
  agentVaultId: 1,
  vaultId: 2,
});

Upshift Instructions

• CollateralReservationAndDeposit: Reserve collateral and deposit in one operation
• Deposit: Deposit FXRP to an Upshift vault
• RequestRedeem: Start a redeem process from an Upshift vault
• Claim: Claim requested FXRP from an Upshift vault

import {
  UpshiftCollateralReservationAndDepositInstruction,
  UpshiftDepositInstruction,
  UpshiftRequestRedeemInstruction,
  UpshiftClaimInstruction,
} from "smart-accounts-encoder";

// Collateral Reservation and Deposit
const collateralDeposit = new UpshiftCollateralReservationAndDepositInstruction({
  walletId: 42,
  value: 1,
  agentVaultId: 1,
  vaultId: 2,
});

// Deposit
const deposit = new UpshiftDepositInstruction({
  walletId: 42,
  value: 1,
  agentVaultId: 1,
  vaultId: 2,
});

// Request Redeem
const requestRedeem = new UpshiftRequestRedeemInstruction({
  walletId: 42,
  value: 1,
  agentVaultId: 1,
  vaultId: 2,
});

// Claim
const claim = new UpshiftClaimInstruction({
  walletId: 42,
  date: { year: 2025, month: 12, day: 8 },
  agentVaultId: 1,
  vaultId: 2,
});

Encoding/Decoding Utilities

The library also exports utility functions for encoding and decoding:

import { toHex, fromHex, numberToBytes, bytesToNumber } from "smart-accounts-encoder";

// Convert number to bytes
const bytes = numberToBytes(42, 4); // Uint8Array of 4 bytes

// Convert bytes to number
const number = bytesToNumber(bytes); // 42

// Convert bytes to hex string
const hex = toHex(bytes); // "0x2a000000"

// Convert hex string to bytes
const bytesFromHex = fromHex(hex); // Uint8Array