@reflectmoney/stable.ts 2.9.0 → 3.0.0

package/README.md

@@ -1,6 +1,6 @@
 # Reflect Money SDK
 
-A TypeScript SDK for interacting with the Reflect programs on Solana. This SDK provides high-level abstractions for minting, redeeming, and managing stablecoins, administrative operations, and protocol integrations.
+A TypeScript SDK for interacting with the Reflect protocol on Solana. The SDK provides high-level abstractions for minting, redeeming, and managing stablecoins.
 
 ## Installation
 
@@ -12,180 +12,311 @@ yarn add @reflectmoney/stable.ts
 
 ## Overview
 
-The Reflect SDK enables developers to interact with the protocol via three main Reflect stablecoins:
+The Reflect SDK enables developers to interact with the protocol's stablecoins:
 
-1. **USDC+ (Index 0)**: Stablecoin backed by USDC deployed in various money markets
-2. **JLP Hedged (Index 1)**: Stablecoin backed by the JLP token, neutralized with perpetual hedging strategies
-3. **LST Delta-Neutral (Index 2)**: Stablecoin backed by LSTs hedged by perpetual futures positions
+- **USDC+ (Index 0)**: Yield-bearing stablecoin backed by USDC deployed in money markets
 
 ## Architecture
 
-The SDK is organized into several key components:
-
 ### Core Classes
 
 #### `Stablecoin` (Abstract Base Class)
-The foundation for all stablecoin implementations. Provides abstract functions and a common interface for:
-- Minting
-- Redemption
-- Administrative operations
 
-**Key Methods:**
-- `mint()` - Create mint instructions
-- `redeem()` - Create redemption instructions
-- `rebalance()` - Create rebalance instructions (admin-only or permissionless, depending on the strategy)
+The foundation for all stablecoin implementations. Provides common interface for:
+
+- Minting stablecoins
+- Redemption operations
+- Administrative functions (cap updates, freezing)
+- Drift protocol integration
+
+**Key Properties:**
+- `controllerKey` - PDA for the stablecoin controller account
+- `stablecoinMint` - Address of the stablecoin token mint
+- `collaterals` - Array of supported collateral assets
+- `lookupTable` - Address lookup table for transaction optimization
+
+#### `UsdcPlusStablecoin`
+
+USDC+ implementation - a yield-bearing stablecoin backed by USDC in money markets.
+
+- **Strategy ID**: 0
+- **Collateral**: USDC
+- **Status**: Live on mainnet
 
 #### `ReflectKeeper`
-Administrative client for protocol-level operations (admin-only).
 
-#### `PdaClient`
-Utility class for deriving PDAs:
-- Configuration program accounts
-- Stablecoin controllers
-- Permission accounts
-- External protocol integrations (Drift, Jupiter, Tokenized Bond)
+Static utility class for protocol-level administrative operations:
 
-#### `ReflectTokenizedBond`
-Client for the tokenized bonds program used for wrapping base stablecoins into yield-bearing receipts. Allows for:
-- Vault creation and management
-- Receipt token generation
-- Deposit and withdrawal operations
+- `initializeMain()` - Initialize the main protocol account
+- Protocol configuration and management
 
-### Stablecoin Implementations
+#### `PdaClient`
 
-#### `UsdcPlusStablecoin`
-USDC+ is a stablecoin backed by USDC deployed in money markets. Implementation details:
-- Status: Live
-- Strategy ID: 0
-- Collateral: USDC
-- Integrated with the tokenized bonds program at the protocol level
-- Users only receive the yield-bearing stablecoin
-- Does not require rebalancing
-
-#### `UsdjStablecoin`
-Stablecoin backed by JLP neutralized with perpetual hedging:
-- Status: Coming soon
-- Strategy ID: 1
-- Collateral: JLP (Jupiter LP tokens)
-- Requires manual wrapping via the Tokenized Bonds program
-- Requires rebalancing, currently permissioned
-
-#### `LstStablecoin`
-Liquid staking token delta-neutral strategy:
-- Status: Live
-- Strategy ID: 2
-- Collateral: Various LSTs (mSOL, jitoSOL, etc.) - use `load()` functionality to fetch the currently supported list of collateral assets
-- Requires manual wrapping via the Tokenized Bonds program
-- Requires rebalancing, currently permissioned
+Utility class for deriving Program Derived Addresses:
+
+- `deriveMain()` - Main protocol configuration account
+- `deriveController(index)` - Stablecoin controller accounts
+- `derivePermissions(admin)` - Admin permission accounts
 
 ## Usage
 
-Follow the snippets below to mint and redeem Reflect stablecoins. All Stablecoin subclasses expose methods following the same schema, so the code below works interchangeably with minor changes - simply change between the three:
+### Setup
 
 ```typescript
-const stablecoin = new UsdcPlusStablecoin(connection);
-const stablecoin = new UsdjStablecoin(connection);
-const stablecoin = new LstStablecoin(connection);
+import { createSolanaRpc } from "@solana/kit";
+import { UsdcPlusStablecoin } from "@reflectmoney/stable.ts";
+
+// Create RPC connection
+const rpc = createSolanaRpc("https://api.mainnet-beta.solana.com");
+
+// Initialize the stablecoin client
+const usdcPlus = new UsdcPlusStablecoin(rpc);
+
+// Load on-chain state (fetches controller data, mint, exchange rate)
+await usdcPlus.load();
 ```
 
 ### Minting Stablecoins
 
 ```typescript
-import { UsdcPlusStablecoin } from '@reflectmoney/stable.ts';
-import { PublicKey, Keypair, Connection, TransactionMessage, VersionedTransaction } from '@solana/web3.js';
-import BN from 'bn.js';
-
-// Use an actual user's public key, read from wallet adapter or local environment.
-const user = Keypair.generate();
-const stablecoin = new UsdcPlusStablecoin(connection);
-
-// Load controller data for the most up-to-date stablecoin setup.
-await stablecoin.load(connection);
-
-// Mint stablecoins against USDC collateral
-const instructions = await stablecoin.mint(
-    user.publicKey,
-    new BN(1000 * 1_000_000), // Deposit collateral of 1,000 USDC (6 decimals)
-    new BN(999 * 1_000_000),  // Minimum received USDC+ (0.1% slippage protection)
+import { 
+    createSolanaRpc,
+    pipe,
+    createTransactionMessage,
+    setTransactionMessageFeePayer,
+    setTransactionMessageLifetimeUsingBlockhash,
+    appendTransactionMessageInstructions,
+    signTransactionMessageWithSigners,
+    sendAndConfirmTransactionFactory,
+} from "@solana/kit";
+import { UsdcPlusStablecoin } from "@reflectmoney/stable.ts";
+
+// Your wallet signer (from wallet adapter or keypair)
+const user = /* your signer */;
+
+// Initialize and load stablecoin state
+const rpc = createSolanaRpc("https://api.mainnet-beta.solana.com");
+const usdcPlus = new UsdcPlusStablecoin(rpc);
+await usdcPlus.load();
+
+// Create mint instruction
+// Deposit 1,000 USDC, expect minimum 999 USDC+ (0.1% slippage)
+const instructions = await usdcPlus.mint(
+    user,
+    BigInt(1000_000_000),  // 1,000 USDC (6 decimals)
+    BigInt(999_000_000),   // Minimum USDC+ to receive
 );
 
-const { blockhash } = await connection.getLatestBlockhash();
+// Build and send transaction
+const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();
 
-const {
-    value: lookupTable
-} = await connection.getAddressLookupTable(
-    stablecoin.lookupTable
+const transactionMessage = pipe(
+    createTransactionMessage({ version: 0 }),
+    tx => setTransactionMessageFeePayer(user.address, tx),
+    tx => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, tx),
+    tx => appendTransactionMessageInstructions(instructions, tx),
 );
 
-const message = new TransactionMessage({
-    instructions,
-    payerKey: user.publicKey,
-    recentBlockhash: blockhash
-}).compileToV0Message([lookupTable]);
-
-const transaction = new VersionedTransaction(message);
+const signedTransaction = await signTransactionMessageWithSigners(transactionMessage);
+const sendAndConfirm = sendAndConfirmTransactionFactory({ rpc });
+const signature = await sendAndConfirm(signedTransaction, { commitment: "confirmed" });
 
-// Transaction signature and confirmation logic, adjust for your needs.
-transaction.sign([user]);
-await connection.sendRawTransaction(transaction.serialize());
+console.log("Mint transaction:", signature);
 ```
 
 ### Redeeming Stablecoins
 
 ```typescript
-import { UsdcPlusStablecoin } from '@reflectmoney/stable.ts';
-import { PublicKey, Keypair, Connection, TransactionMessage, VersionedTransaction } from '@solana/web3.js';
-import BN from 'bn.js';
-
-// Use an actual user's public key, read from wallet adapter or local environment.
-const user = Keypair.generate();
-const stablecoin = new UsdcPlusStablecoin(connection);
-
-// Load controller data for the most up-to-date stablecoin setup.
-await stablecoin.load(connection);
-
-// Redeem USDC+ into USDC
-const instructions = await stablecoin.redeem(
-    user.publicKey,
-    new BN(999 * 1_000_000), // Burn 999 of USDC+
-    new BN(1_000 * 1_000_000),  // Minimum received USDC (USDC+ is yield bearing, so you'll receive more USDC over time)
+import { 
+    createSolanaRpc,
+    pipe,
+    createTransactionMessage,
+    setTransactionMessageFeePayer,
+    setTransactionMessageLifetimeUsingBlockhash,
+    appendTransactionMessageInstructions,
+    signTransactionMessageWithSigners,
+    sendAndConfirmTransactionFactory,
+} from "@solana/kit";
+import { UsdcPlusStablecoin } from "@reflectmoney/stable.ts";
+
+const user = /* your signer */;
+
+const rpc = createSolanaRpc("https://api.mainnet-beta.solana.com");
+const usdcPlus = new UsdcPlusStablecoin(rpc);
+await usdcPlus.load();
+
+// Create redeem instruction
+// Burn 999 USDC+, expect minimum 1,000 USDC (USDC+ accrues yield)
+const instructions = await usdcPlus.redeem(
+    user,
+    BigInt(999_000_000),   // USDC+ to burn
+    BigInt(1000_000_000),  // Minimum USDC to receive
 );
 
-const { blockhash } = await connection.getLatestBlockhash();
+// Build and send transaction
+const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();
 
-const {
-    value: lookupTable
-} = await connection.getAddressLookupTable(
-    stablecoin.lookupTable
+const transactionMessage = pipe(
+    createTransactionMessage({ version: 0 }),
+    tx => setTransactionMessageFeePayer(user.address, tx),
+    tx => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, tx),
+    tx => appendTransactionMessageInstructions(instructions, tx),
 );
 
-const message = new TransactionMessage({
-    instructions,
-    payerKey: user.publicKey,
-    recentBlockhash: blockhash
-}).compileToV0Message([lookupTable]);
+const signedTransaction = await signTransactionMessageWithSigners(transactionMessage);
+const sendAndConfirm = sendAndConfirmTransactionFactory({ rpc });
+const signature = await sendAndConfirm(signedTransaction, { commitment: "confirmed" });
+
+console.log("Redeem transaction:", signature);
+```
+
+### Getting Exchange Rate
+
+```typescript
+import { createSolanaRpc } from "@solana/kit";
+import { UsdcPlusStablecoin } from "@reflectmoney/stable.ts";
+
+const rpc = createSolanaRpc("https://api.mainnet-beta.solana.com");
+const usdcPlus = new UsdcPlusStablecoin(rpc);
+await usdcPlus.load();
+
+// Get current exchange rate (USDC per USDC+)
+const exchangeRate = await usdcPlus.getExchangeRate();
+console.log(`1 USDC+ = ${exchangeRate} USDC`);
+```
+
+### PDA Derivation
+
+```typescript
+import { PdaClient } from "@reflectmoney/stable.ts";
+
+// Derive main protocol account
+const mainPda = await PdaClient.deriveMain();
+
+// Derive controller for strategy index 0 (USDC+)
+const controllerPda = await PdaClient.deriveController(0);
+
+// Derive permissions account for an admin
+const permissionsPda = await PdaClient.derivePermissions(adminAddress);
+```
+
+### Administrative Operations
+
+```typescript
+import { UsdcPlusStablecoin, ReflectKeeper } from "@reflectmoney/stable.ts";
+
+const admin = /* admin signer */;
 
-const transaction = new VersionedTransaction(message);
+// Initialize main protocol (one-time setup)
+const initMainIx = await ReflectKeeper.initializeMain(admin);
 
-// Transaction signature and confirmation logic, adjust for your needs.
-transaction.sign([user]);
-await connection.sendRawTransaction(transaction.serialize());
+// Update supply cap
+const usdcPlus = new UsdcPlusStablecoin(rpc);
+await usdcPlus.load();
+const updateCapIx = await usdcPlus.updateCap(
+    admin,
+    BigInt(1_000_000_000_000_000) // New cap
+);
+
+// Freeze/unfreeze minting
+const freezeIx = await usdcPlus.freeze(admin, true, 0);  // Freeze action 0
+const unfreezeIx = await usdcPlus.freeze(admin, false, 0); // Unfreeze
+```
+
+## API Reference
+
+### UsdcPlusStablecoin
+
+#### Constructor
+
+```typescript
+constructor(rpc: Rpc<SolanaRpcApi>, mint?: Address)
+```
+
+- `rpc` - Solana RPC client
+- `mint` - Optional stablecoin mint address (auto-loaded if not provided)
+
+#### Methods
+
+| Method | Description | Returns |
+|--------|-------------|---------|
+| `load()` | Load on-chain state (controller, mint, exchange rate) | `Promise<void>` |
+| `initializeKeys()` | Initialize PDA keys without fetching on-chain data | `Promise<void>` |
+| `mint(user, amount, minReceived)` | Create mint instruction | `Promise<Instruction[]>` |
+| `redeem(user, amount, minReceived)` | Create redeem instruction | `Promise<Instruction[]>` |
+| `getExchangeRate()` | Get current USDC/USDC+ exchange rate | `Promise<number>` |
+| `updateCap(admin, newCap)` | Update supply cap (admin) | `Promise<Instruction>` |
+| `freeze(admin, freeze, action)` | Freeze/unfreeze actions (admin) | `Promise<Instruction>` |
+
+### PdaClient
+
+#### Static Methods
+
+| Method | Description | Returns |
+|--------|-------------|---------|
+| `deriveMain(devnet?)` | Derive main protocol PDA | `Promise<Address>` |
+| `deriveController(index, devnet?)` | Derive controller PDA for strategy | `Promise<Address>` |
+| `derivePermissions(admin, devnet?)` | Derive admin permissions PDA | `Promise<Address>` |
+
+### ReflectKeeper
+
+#### Static Methods
+
+| Method | Description | Returns |
+|--------|-------------|---------|
+| `initializeMain(admin)` | Initialize main protocol account | `Promise<Instruction>` |
+
+## Types
+
+```typescript
+// Collateral asset configuration
+interface Collateral {
+    mint: Address;
+    oracle: string;
+    decimals: number;
+}
+
+// Stablecoin metadata
+interface StablecoinMetadata {
+    name: string;
+    ticker: string;
+    uri: string;
+}
+```
+
+## Integration Notes
+
+### Drift Protocol
+
+The SDK integrates with Drift Protocol for perpetual futures positions. Admin operations for Drift account management:
+
+```typescript
+// Initialize Drift stats account for the controller
+const driftStatsIx = await usdcPlus.initializeStablecoinDriftStatsAccount(admin);
+
+// Initialize Drift sub-account
+const driftAccountIx = await usdcPlus.initializeStablecoinDriftAccount(admin);
+```
+
+### Address Lookup Tables
+
+For transaction optimization, use the stablecoin's lookup table:
+
+```typescript
+const lookupTableAddress = usdcPlus.lookupTable;
+// Fetch and use in versioned transactions for reduced transaction size
 ```
 
-### Integration with External Protocols
+## Network Support
 
-The SDK is built with integration for:
-- **Drift Protocol**: For perpetual futures and spot trading
-- **Jupiter Protocol**: For LP token operations and swaps
-- **Pyth Network**: For price oracle data
-- **Tokenized Bonds**: For yield generation
+- **Mainnet**: Default configuration
+- **Devnet**: Pass `devnet: true` to constructor or use devnet RPC
 
 ## License
 
-This SDK is licensed under the MIT License.
+MIT License
 
 ## Support
 
-For support and questions:
 - Documentation: [docs.reflect.money](https://docs.reflect.money)
-- GitHub Issues: [github.com/palindrome-eng/reflect-delta-neutral](https://github.com/palindrome-eng/reflect-delta-neutral)
+- GitHub: [github.com/palindrome-eng/reflect-delta-neutral](https://github.com/palindrome-eng/reflect-delta-neutral)

package/dist/classes/Migration.d.ts

@@ -0,0 +1,66 @@
+import { Address, TransactionSigner, Rpc, SolanaRpcApi, Instruction } from "@solana/kit";
+/**
+ * Migration handler for the Reflect protocol.
+ * Provides functionality for migrating program state and accounts to new versions.
+ *
+ * This class is used by protocol administrators to execute migration instructions
+ * when upgrading the program to a new version.
+ *
+ * Environment handling:
+ * - devnet=true → Uses devnet program
+ * - devnet=false, mock=true → Uses mock program on mainnet
+ * - devnet=false, mock=false → Uses production mainnet program
+ */
+export declare class Migration {
+    /** Solana RPC instance for communication */
+    private rpc;
+    /** Address of the main program account */
+    private main;
+    /** Whether to use devnet program */
+    private devnet;
+    /** Whether to use mock program on mainnet (only applies when devnet=false) */
+    private mock;
+    /**
+     * Creates a new Migration instance.
+     *
+     * @param rpc - Solana RPC instance
+     * @param devnet - Whether to use devnet program
+     * @param mock - Whether to use mock program on mainnet (only applies when devnet=false)
+     */
+    constructor({ rpc, devnet, mock, }: {
+        rpc: Rpc<SolanaRpcApi>;
+        devnet?: boolean;
+        mock?: boolean;
+    });
+    /**
+     * Initialize the migration client by deriving necessary PDAs.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Get the program address based on network configuration.
+     * - devnet=true → devnet program
+     * - devnet=false, mock=true → mock program on mainnet
+     * - devnet=false, mock=false → production mainnet program
+     */
+    get programAddress(): Address;
+    /**
+     * Migrates the USDC+ Strategy 1 controller to the new program version.
+     *
+     * This instruction updates the USDC controller account structure to be
+     * compatible with the new program version. It should be called by an admin
+     * after the program has been upgraded.
+     *
+     * @param admin - TransactionSigner of the admin executing the migration
+     * @returns Promise resolving to the migration instruction
+     *
+     * @example
+     * ```typescript
+     * const migration = new Migration({ rpc, devnet: false });
+     * await migration.initialize();
+     *
+     * const ix = await migration.migrateStrategy1(adminSigner);
+     * // Add ix to a transaction and send
+     * ```
+     */
+    migrateStrategy1(admin: TransactionSigner): Promise<Instruction>;
+}

package/dist/classes/Migration.js

@@ -0,0 +1,95 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Migration = void 0;
+const reflect_main_1 = require("../generated/reflect_main");
+const getProgramAddress_1 = require("../utils/getProgramAddress");
+const PdaClient_1 = require("./PdaClient");
+/**
+ * Migration handler for the Reflect protocol.
+ * Provides functionality for migrating program state and accounts to new versions.
+ *
+ * This class is used by protocol administrators to execute migration instructions
+ * when upgrading the program to a new version.
+ *
+ * Environment handling:
+ * - devnet=true → Uses devnet program
+ * - devnet=false, mock=true → Uses mock program on mainnet
+ * - devnet=false, mock=false → Uses production mainnet program
+ */
+class Migration {
+    /**
+     * Creates a new Migration instance.
+     *
+     * @param rpc - Solana RPC instance
+     * @param devnet - Whether to use devnet program
+     * @param mock - Whether to use mock program on mainnet (only applies when devnet=false)
+     */
+    constructor({ rpc, devnet = false, mock = false, }) {
+        /** Address of the main program account */
+        this.main = null;
+        this.rpc = rpc;
+        this.devnet = devnet;
+        this.mock = mock;
+    }
+    /**
+     * Initialize the migration client by deriving necessary PDAs.
+     */
+    initialize() {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.main = yield PdaClient_1.PdaClient.deriveMain(this.devnet, this.mock);
+        });
+    }
+    /**
+     * Get the program address based on network configuration.
+     * - devnet=true → devnet program
+     * - devnet=false, mock=true → mock program on mainnet
+     * - devnet=false, mock=false → production mainnet program
+     */
+    get programAddress() {
+        return (0, getProgramAddress_1.getProgramAddress)({ devnet: this.devnet, mock: this.mock });
+    }
+    /**
+     * Migrates the USDC+ Strategy 1 controller to the new program version.
+     *
+     * This instruction updates the USDC controller account structure to be
+     * compatible with the new program version. It should be called by an admin
+     * after the program has been upgraded.
+     *
+     * @param admin - TransactionSigner of the admin executing the migration
+     * @returns Promise resolving to the migration instruction
+     *
+     * @example
+     * ```typescript
+     * const migration = new Migration({ rpc, devnet: false });
+     * await migration.initialize();
+     *
+     * const ix = await migration.migrateStrategy1(adminSigner);
+     * // Add ix to a transaction and send
+     * ```
+     */
+    migrateStrategy1(admin) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.main)
+                yield this.initialize();
+            const adminPermissions = yield PdaClient_1.PdaClient.derivePermissions(admin.address, this.devnet, this.mock);
+            const usdcController = yield PdaClient_1.PdaClient.deriveController(0, this.devnet, this.mock);
+            const ix = (0, reflect_main_1.getMigrateS1Instruction)({
+                usdcController,
+                main: this.main,
+                adminPermissions,
+                admin,
+            }, { programAddress: this.programAddress });
+            return ix;
+        });
+    }
+}
+exports.Migration = Migration;