npm package: @flarenetwork/smart-accounts-encoder
Description: Encode and decode instructions to be used in Flare smart account
Author: Flare Network
Latest version: 0.0.14

<!-- LOGO -->

<div align="center">
  <a href="https://flare.network/" target="blank">
    <img src="https://content.flare.network/Flare-2.svg" width="300" alt="Flare Logo" />
  </a>
  <br />
  A library for encoding instructions that are used in the Flare smart accounts workflow.
  <br />
  <a href="#PROJECT_NAME">About</a>
  ·
  <a href="CONTRIBUTING.md">Contributing</a>
  ·
  <a href="SECURITY.md">Security</a>
  ·
  <a href="CHANGELOG.md">Changelog</a>
</div>

# 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

```sh
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

```bash
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.

```typescript
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

```typescript
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

```typescript
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,
  vaultId: 2,
});

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

// Claim Withdraw
const claimWithdraw = new FirelightClaimWithdrawInstruction({
  walletId: 42,
  period: 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

```typescript
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,
  vaultId: 2,
});

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

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

### Encoding/Decoding Utilities

The library also exports utility functions for encoding and decoding:

```typescript
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
```