@reflectmoney/stable.ts 1.0.0 → 1.0.1

package/README.md

@@ -1,9 +1,180 @@
-# Reflect SDK
+# Reflect Money Stable.ts SDK
 
-Typescript SDK for interacting with Reflect Protocol Delta-Neutral Program.
+A comprehensive TypeScript SDK for interacting with the Reflect Protocol Delta-Neutral Program on Solana. This SDK provides high-level abstractions for managing stablecoins, administrative operations, and protocol integrations.
 
-## Classes
-SDK provides three classes:
-- `Reflect` - general purpose class for user-level interactions. Mainly for `mint()` and `burn()` of stable.
-- `ReflectAdmin` - admin-level class, allowing for modification of the core protocol settings.
-- `ReflectCrank` - class used for cranking the protocol to capture spreads & funding.
+## Overview
+
+The Reflect Protocol SDK enables developers to interact with three main Reflect stablecoins:
+
+1. **USDC+ (Strategy 0)**: Stablecoin backed by USDC deployed in money markets
+2. **JLP Hedged (Strategy 1)**: Stablecoin backed by the JLP token, neutralised with perpetual hedging strategies
+3. **LST Delta-Neutral (Strategy 2)**: Stablecoin backed by hedged LSTs
+
+## Architecture
+
+The SDK is organized into several key components:
+
+### Core Classes
+
+#### `Stablecoin` (Abstract Base Class)
+The foundation for all stablecoin implementations. Provides common interface for:
+- minting,
+- redemption,
+- administrative operations.
+
+**Key Methods:**
+- `initialize()` - Initialize the stablecoin strategy (admin-only)
+- `mint()` - Create mint instructions
+- `redeem()` - Create redemption instructions
+- `rebalance()` - Create rebalancing instructions (admin-only)
+- `updateCap()` - Update supply cap (admin-only)
+- `updateRecipients()` - Update fee recipients (admin-only)
+
+#### `ReflectAdmin`
+Administrative client for protocol-level operations:
+- Protocol initialization
+- Role and permission management
+- Action freezing/unfreezing
+- Admin account creation
+
+**Key Methods:**
+- `initializeMain()` - Initialize the main program account
+- `freezeProtocolAction()` - Freeze/unfreeze protocol actions
+- `updateRoleHolderProtocol()` - Update protocol-level permissions
+- `createAdminAccount()` - Create new admin accounts
+
+#### `PdaClient`
+Utility class for deriving Program Derived Addresses (PDAs):
+- Main program accounts
+- Controller accounts
+- Permission accounts
+- External protocol integrations (Drift, Jupiter)
+
+#### `ReflectTokenisedBond`
+Client for tokenized bonds program, allowing for wrapping base stablecoins into yield-bearing receipts. Allows for:
+- Vault creation and management
+- Receipt token generation
+- Deposit and withdrawal operations
+
+### Stablecoin Implementations
+
+#### `UsdcStablecoin`
+Simple USDC-backed stablecoin implementation:
+- Strategy ID: 0
+- Collateral: USDC
+- Integrated with tokenised bonds program on the protocol level
+
+#### `JlpStablecoin`
+Jupiter LP token with perpetual hedging:
+- Strategy ID: 1
+- Collateral: JLP (Jupiter LP tokens)
+
+#### `LstStablecoin`
+Liquid staking token delta-neutral strategy:
+- Strategy ID: 2
+- Collateral: Various LSTs (mSOL, jitoSOL, etc.)
+
+## Installation
+
+```bash
+npm install @reflectmoney/stable.ts
+# or
+yarn add @reflectmoney/stable.ts
+```
+
+## Quick Start
+
+### Minting Stablecoins
+
+```typescript
+import { LstStablecoin } from '@reflectmoney/stable.ts';
+import { PublicKey } from '@solana/web3.js';
+import BN from 'bn.js';
+
+const lstStablecoin = new LstStablecoin(connection);
+
+// Load controller data
+await lstStablecoin.load(connection);
+
+// Mint stablecoins against LST collateral
+const mintInstructions = await lstStablecoin.mint(
+    userPublicKey,
+    new BN(1000000), // 1 USDC (6 decimals)
+    new BN(999000),  // Minimum received (slippage protection)
+    new PublicKey("<jitoSOL mint>") // LST mint address
+);
+```
+
+### Administrative Operations
+
+```typescript
+import { ReflectAdmin } from '@reflectmoney/stable.ts';
+
+const admin = new ReflectAdmin({
+    admin: adminPublicKey,
+    connection
+});
+
+// Freeze minting operations
+const freezeIx = await admin.freezeProtocolAction(true, Action.Mint);
+
+// Update supply cap
+const updateCapIx = await usdcStablecoin.updateCap(adminPublicKey, new BN(1000000000));
+```
+
+## Advanced Usage
+
+### Custom Stablecoin Implementation
+
+```typescript
+import { Stablecoin } from '@reflectmoney/stable.ts';
+
+class CustomStablecoin extends Stablecoin {
+    constructor(connection: Connection) {
+        super(3, "Custom Strategy", connection);
+        this.collaterals = [{ mint: customMint, oracle: customOracle }];
+    }
+
+    async initialize(signer: PublicKey, ...args: any[]): Promise<TransactionInstruction[]> {
+        // Custom initialization logic
+    }
+
+    async mint(signer: PublicKey, amount: BN, minimumReceived: BN, ...args: any[]): Promise<TransactionInstruction[]> {
+        // Custom minting logic
+    }
+
+    async redeem(signer: PublicKey, amount: BN, minimumReceived: BN, ...args: any[]): Promise<TransactionInstruction[]> {
+        // Custom redemption logic
+    }
+
+    async rebalance(signer: PublicKey): Promise<TransactionInstruction[]> {
+        // Custom rebalancing logic
+    }
+
+    async constructAccounts<T>(signer: PublicKey, ...args: any[]): Promise<T> {
+        // Custom account construction
+    }
+
+    async constructRemainingAccounts(): Promise<AccountMeta[]> {
+        // Custom remaining accounts
+    }
+}
+```
+
+### Integration with External Protocols
+
+The SDK is built in integration with:
+- **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
+
+## License
+
+This SDK is licensed under the 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)

package/dist/classes/PdaClient.d.ts

@@ -1,19 +1,131 @@
 import { PublicKey } from "@solana/web3.js";
+/**
+ * Utility class for deriving Program Derived Addresses (PDAs) used throughout the Reflect protocol.
+ * Provides static methods to generate deterministic addresses for various program accounts
+ * including main program accounts, controllers, permissions, and external protocol integrations.
+ */
 export declare class PdaClient {
+    /**
+     * Derives the main program account address.
+     * This is the primary account that stores global protocol state.
+     *
+     * @returns PublicKey of the main program account
+     */
     static deriveMain(): PublicKey;
+    /**
+     * Derives the permissions account address for a specific user.
+     * This account stores the user's role-based permissions within the protocol.
+     *
+     * @param user - Public key of the user
+     * @returns PublicKey of the user's permissions account
+     */
     static derivePermissions(user: PublicKey): PublicKey;
+    /**
+     * Derives the controller account address for a specific strategy.
+     * Each stablecoin strategy has its own controller account.
+     *
+     * @param strategy - Strategy index (0: USDC+, 1: JLP, 2: LST)
+     * @returns PublicKey of the strategy controller account
+     */
     static deriveController(strategy: number): PublicKey;
+    /**
+     * Derives the controller account address with bump seed for a specific strategy.
+     * Returns both the public key and the bump seed.
+     *
+     * @param strategy - Strategy index (0: USDC+, 1: JLP, 2: LST)
+     * @returns Array containing [PublicKey, number] where number is the bump seed
+     */
     static deriveControllerWithBump(strategy: number): [PublicKey, number];
+    /**
+     * Derives the rebalance details account address for a specific strategy.
+     * This account stores information about rebalancing operations.
+     *
+     * @param strategy - Strategy index (0: USDC+, 1: JLP, 2: LST)
+     * @returns PublicKey of the rebalance details account
+     */
     static deriveRebalanceDetails(strategy: number): PublicKey;
+    /**
+     * Derives the Jupiter Perpetuals program account address.
+     * Used for integration with Jupiter's perpetuals protocol.
+     *
+     * @returns PublicKey of the Jupiter Perpetuals account
+     */
     static deriveJupiterPerpetuals(): PublicKey;
+    /**
+     * Derives the Jupiter LP pool account address.
+     * Used for JLP (Jupiter LP) token operations.
+     *
+     * @returns PublicKey of the JLP pool account
+     */
     static deriveJlpPool(): PublicKey;
+    /**
+     * Derives the Jupiter event authority account address.
+     * Used for event emission in Jupiter protocol interactions.
+     *
+     * @returns PublicKey of the Jupiter event authority account
+     */
     static deriveEventAuthority(): PublicKey;
+    /**
+     * Derives the Jupiter transfer authority account address.
+     * Used for token transfer operations in Jupiter protocol.
+     *
+     * @returns PublicKey of the Jupiter transfer authority account
+     */
     static deriveTransferAuthority(): PublicKey;
+    /**
+     * Gets the Drift vault address for a specific mint.
+     * Looks up the market index for the mint and derives the corresponding vault address.
+     *
+     * @param mint - Public key of the token mint
+     * @returns Promise resolving to the PublicKey of the Drift vault account
+     */
     static getDriftVaultFromMint(mint: PublicKey): Promise<PublicKey>;
+    /**
+     * Derives the token metadata account address for a mint.
+     * Used for storing token metadata information.
+     *
+     * @param mint - Public key of the token mint
+     * @returns PublicKey of the metadata account
+     */
     static deriveMetadataAccount(mint: PublicKey): PublicKey;
+    /**
+     * Derives the custody account address for a pool and token combination.
+     * Used in Jupiter protocol for token custody management.
+     *
+     * @param pool - Public key of the pool
+     * @param token - Public key of the token
+     * @returns PublicKey of the custody account
+     */
     static deriveCustody(pool: PublicKey, token: PublicKey): PublicKey;
+    /**
+     * Derives the LP config account address.
+     * Used for tokenized bonds program configuration.
+     *
+     * @returns PublicKey of the LP config account
+     */
     static deriveLpConfig(): PublicKey;
+    /**
+     * Derives the LP admin account address for a specific admin.
+     * Used for tokenized bonds program administration.
+     *
+     * @param admin - Public key of the admin
+     * @returns PublicKey of the LP admin account
+     */
     static deriveLpAdmin(admin: PublicKey): PublicKey;
+    /**
+     * Derives the LP vault account address for a specific vault ID.
+     * Used for tokenized bonds vault management.
+     *
+     * @param vaultId - Numeric identifier for the vault
+     * @returns PublicKey of the LP vault account
+     */
     static deriveLpVault(vaultId: number): PublicKey;
+    /**
+     * Derives the LP vault pool account address for a specific vault ID.
+     * Used for tokenized bonds vault pool management.
+     *
+     * @param vaultId - Numeric identifier for the vault
+     * @returns PublicKey of the LP vault pool account
+     */
     static deriveLpVaultPool(vaultId: number): PublicKey;
 }

package/dist/classes/PdaClient.js

@@ -20,11 +20,29 @@ const constants_1 = require("../constants");
 const bn_js_1 = __importDefault(require("bn.js"));
 const sdk_1 = require("@drift-labs/sdk");
 const mpl_token_metadata_1 = require("@metaplex-foundation/mpl-token-metadata");
+/**
+ * Utility class for deriving Program Derived Addresses (PDAs) used throughout the Reflect protocol.
+ * Provides static methods to generate deterministic addresses for various program accounts
+ * including main program accounts, controllers, permissions, and external protocol integrations.
+ */
 class PdaClient {
+    /**
+     * Derives the main program account address.
+     * This is the primary account that stores global protocol state.
+     *
+     * @returns PublicKey of the main program account
+     */
     static deriveMain() {
         const [main] = web3_js_1.PublicKey.findProgramAddressSync([Buffer.from("main")], reflect_main_1.PROGRAM_ID);
         return main;
     }
+    /**
+     * Derives the permissions account address for a specific user.
+     * This account stores the user's role-based permissions within the protocol.
+     *
+     * @param user - Public key of the user
+     * @returns PublicKey of the user's permissions account
+     */
     static derivePermissions(user) {
         const [permissions] = web3_js_1.PublicKey.findProgramAddressSync([
             Buffer.from("user_permission"),
@@ -32,6 +50,13 @@ class PdaClient {
         ], reflect_main_1.PROGRAM_ID);
         return permissions;
     }
+    /**
+     * Derives the controller account address for a specific strategy.
+     * Each stablecoin strategy has its own controller account.
+     *
+     * @param strategy - Strategy index (0: USDC+, 1: JLP, 2: LST)
+     * @returns PublicKey of the strategy controller account
+     */
     static deriveController(strategy) {
         const [controller] = web3_js_1.PublicKey.findProgramAddressSync([
             Buffer.from("dex_controller"),
@@ -39,12 +64,26 @@ class PdaClient {
         ], reflect_main_1.PROGRAM_ID);
         return controller;
     }
+    /**
+     * Derives the controller account address with bump seed for a specific strategy.
+     * Returns both the public key and the bump seed.
+     *
+     * @param strategy - Strategy index (0: USDC+, 1: JLP, 2: LST)
+     * @returns Array containing [PublicKey, number] where number is the bump seed
+     */
     static deriveControllerWithBump(strategy) {
         return web3_js_1.PublicKey.findProgramAddressSync([
             Buffer.from("dex_controller"),
             Buffer.from([strategy])
         ], reflect_main_1.PROGRAM_ID);
     }
+    /**
+     * Derives the rebalance details account address for a specific strategy.
+     * This account stores information about rebalancing operations.
+     *
+     * @param strategy - Strategy index (0: USDC+, 1: JLP, 2: LST)
+     * @returns PublicKey of the rebalance details account
+     */
     static deriveRebalanceDetails(strategy) {
         const [rebalanceDetails] = web3_js_1.PublicKey.findProgramAddressSync([
             Buffer.from("rebalance_details"),
@@ -52,12 +91,24 @@ class PdaClient {
         ], reflect_main_1.PROGRAM_ID);
         return rebalanceDetails;
     }
+    /**
+     * Derives the Jupiter Perpetuals program account address.
+     * Used for integration with Jupiter's perpetuals protocol.
+     *
+     * @returns PublicKey of the Jupiter Perpetuals account
+     */
     static deriveJupiterPerpetuals() {
         const [perpetuals] = web3_js_1.PublicKey.findProgramAddressSync([
             Buffer.from("perpetuals")
         ], constants_1.JUPITER_PROGRAM_ID);
         return perpetuals;
     }
+    /**
+     * Derives the Jupiter LP pool account address.
+     * Used for JLP (Jupiter LP) token operations.
+     *
+     * @returns PublicKey of the JLP pool account
+     */
     static deriveJlpPool() {
         const [jlpPool] = web3_js_1.PublicKey.findProgramAddressSync([
             Buffer.from("pool"),
@@ -65,18 +116,37 @@ class PdaClient {
         ], constants_1.JUPITER_PROGRAM_ID);
         return jlpPool;
     }
+    /**
+     * Derives the Jupiter event authority account address.
+     * Used for event emission in Jupiter protocol interactions.
+     *
+     * @returns PublicKey of the Jupiter event authority account
+     */
     static deriveEventAuthority() {
         const [eventAuthority] = web3_js_1.PublicKey.findProgramAddressSync([
             Buffer.from("__event_authority"),
         ], constants_1.JUPITER_PROGRAM_ID);
         return eventAuthority;
     }
+    /**
+     * Derives the Jupiter transfer authority account address.
+     * Used for token transfer operations in Jupiter protocol.
+     *
+     * @returns PublicKey of the Jupiter transfer authority account
+     */
     static deriveTransferAuthority() {
         const [transferAuthority] = web3_js_1.PublicKey.findProgramAddressSync([
             Buffer.from("transfer_authority"),
         ], constants_1.JUPITER_PROGRAM_ID);
         return transferAuthority;
     }
+    /**
+     * Gets the Drift vault address for a specific mint.
+     * Looks up the market index for the mint and derives the corresponding vault address.
+     *
+     * @param mint - Public key of the token mint
+     * @returns Promise resolving to the PublicKey of the Drift vault account
+     */
     static getDriftVaultFromMint(mint) {
         return __awaiter(this, void 0, void 0, function* () {
             const { marketIndex } = sdk_1.SpotMarkets["mainnet-beta"]
@@ -84,6 +154,13 @@ class PdaClient {
             return yield (0, sdk_1.getSpotMarketVaultPublicKey)(constants_1.DRIFT_PROGRAM_ID, marketIndex);
         });
     }
+    /**
+     * Derives the token metadata account address for a mint.
+     * Used for storing token metadata information.
+     *
+     * @param mint - Public key of the token mint
+     * @returns PublicKey of the metadata account
+     */
     static deriveMetadataAccount(mint) {
         const [metadata] = web3_js_1.PublicKey.findProgramAddressSync([
             Buffer.from("metadata"),
@@ -92,6 +169,14 @@ class PdaClient {
         ], mpl_token_metadata_1.PROGRAM_ID);
         return metadata;
     }
+    /**
+     * Derives the custody account address for a pool and token combination.
+     * Used in Jupiter protocol for token custody management.
+     *
+     * @param pool - Public key of the pool
+     * @param token - Public key of the token
+     * @returns PublicKey of the custody account
+     */
     static deriveCustody(pool, token) {
         const [custody] = web3_js_1.PublicKey.findProgramAddressSync([
             Buffer.from("custody"),
@@ -100,12 +185,25 @@ class PdaClient {
         ], constants_1.JUPITER_PROGRAM_ID);
         return custody;
     }
+    /**
+     * Derives the LP config account address.
+     * Used for tokenized bonds program configuration.
+     *
+     * @returns PublicKey of the LP config account
+     */
     static deriveLpConfig() {
         const [config] = web3_js_1.PublicKey.findProgramAddressSync([
             Buffer.from("config")
         ], reflect_tokenised_bonds_1.PROGRAM_ID);
         return config;
     }
+    /**
+     * Derives the LP admin account address for a specific admin.
+     * Used for tokenized bonds program administration.
+     *
+     * @param admin - Public key of the admin
+     * @returns PublicKey of the LP admin account
+     */
     static deriveLpAdmin(admin) {
         const [adminPda] = web3_js_1.PublicKey.findProgramAddressSync([
             Buffer.from("admin"),
@@ -113,6 +211,13 @@ class PdaClient {
         ], reflect_tokenised_bonds_1.PROGRAM_ID);
         return adminPda;
     }
+    /**
+     * Derives the LP vault account address for a specific vault ID.
+     * Used for tokenized bonds vault management.
+     *
+     * @param vaultId - Numeric identifier for the vault
+     * @returns PublicKey of the LP vault account
+     */
     static deriveLpVault(vaultId) {
         const [vault] = web3_js_1.PublicKey.findProgramAddressSync([
             Buffer.from("vault"),
@@ -120,6 +225,13 @@ class PdaClient {
         ], reflect_tokenised_bonds_1.PROGRAM_ID);
         return vault;
     }
+    /**
+     * Derives the LP vault pool account address for a specific vault ID.
+     * Used for tokenized bonds vault pool management.
+     *
+     * @param vaultId - Numeric identifier for the vault
+     * @returns PublicKey of the LP vault pool account
+     */
     static deriveLpVaultPool(vaultId) {
         const [pool] = web3_js_1.PublicKey.findProgramAddressSync([
             Buffer.from("vault_pool"),

package/dist/classes/ReflectAdmin.d.ts

@@ -1,19 +1,104 @@
 import { Connection, PublicKey } from "@solana/web3.js";
 import { Action, Role, Update } from "../generated/reflect_main";
+/**
+ * Administrative client for the Reflect protocol.
+ * Provides functionality for protocol-level administration including:
+ * - Protocol initialization and setup
+ * - Role and permission management
+ * - Action freezing/unfreezing
+ * - Admin account creation and management
+ *
+ * This class is used by protocol administrators to manage global settings,
+ * user permissions, and protocol-wide configurations.
+ */
 export declare class ReflectAdmin {
+    /** Public key of the admin user */
     private admin;
+    /** Public key of the main program account */
     private main;
+    /** Solana connection instance for RPC communication */
     private connection;
+    /**
+     * Creates a new ReflectAdmin instance.
+     *
+     * @param admin - Public key of the admin user
+     * @param connection - Solana connection instance
+     */
     constructor({ admin, connection }: {
         admin: PublicKey;
         connection: Connection;
     });
+    /**
+     * Creates the main program account. This is the initial step of protocol setup.
+     *
+     * @param admin - Public key of the initial admin
+     * @returns TransactionInstruction for initializing the main account
+     */
     static initializeMain(admin: PublicKey): import("@solana/web3.js").TransactionInstruction;
+    /**
+     * Freezes or unfreezes a specific protocol action.
+     *
+     * @param freeze - Whether to freeze (true) or unfreeze (false) the action
+     * @param action - The action to freeze/unfreeze
+     * @returns Promise resolving to a TransactionInstruction
+     */
     freezeProtocolAction(freeze: boolean, action: Action): Promise<import("@solana/web3.js").TransactionInstruction>;
-    freezeDex(freeze: boolean, programIndex: number): Promise<void>;
+    /**
+     * Freezes or unfreezes a specific DEX program.
+     *
+     * @param freeze - Whether to freeze (true) or unfreeze (false) the program
+     * @param programIndex - Index of the program to freeze/unfreeze
+     * @returns Promise resolving to a TransactionInstruction
+     */
+    freezeDex(freeze: boolean, programIndex: number): Promise<import("@solana/web3.js").TransactionInstruction>;
+    /**
+     * Creates a new admin account with specified permissions.
+     *
+     * @param signer - Public key of the caller (must be existing admin)
+     * @param newAdmin - Public key of the new admin to create
+     * @returns Promise resolving to a TransactionInstruction
+     */
     createAdminAccount(signer: PublicKey, newAdmin: PublicKey): Promise<import("@solana/web3.js").TransactionInstruction>;
+    /**
+     * Updates role holder permissions at the protocol level.
+     *
+     * @param signer - Public key of the admin signer
+     * @param adminToUpdate - Public key of the admin whose permissions are being updated
+     * @param affectedRole - The role being modified
+     * @param update - The type of update (Grant or Revoke)
+     * @returns Promise resolving to a TransactionInstruction
+     */
     updateRoleHolderProtocol(signer: PublicKey, adminToUpdate: PublicKey, affectedRole: Role, update: Update): Promise<import("@solana/web3.js").TransactionInstruction>;
+    /**
+     * Updates role holder permissions for a specific strategy.
+     *
+     * @param signer - Public key of the admin signer
+     * @param strategyId - ID of the strategy to update permissions for
+     * @param adminToUpdate - Public key of the admin whose permissions are being updated
+     * @param affectedRole - The role being modified
+     * @param update - The type of update (Grant or Revoke)
+     * @returns Promise resolving to a TransactionInstruction
+     */
     updateRoleHolderStrategy(signer: PublicKey, strategyId: number, adminToUpdate: PublicKey, affectedRole: Role, update: Update): Promise<import("@solana/web3.js").TransactionInstruction>;
-    updateActionRoleStrategy(signer: PublicKey, strategyId: number, action: Action, affectedRole: Role, update: Update): Promise<void>;
+    /**
+     * Updates action role permissions for a specific strategy.
+     *
+     * @param signer - Public key of the admin signer
+     * @param strategyId - ID of the strategy to update permissions for
+     * @param action - The action being modified
+     * @param affectedRole - The role being modified
+     * @param update - The type of update (Grant or Revoke)
+     * @returns Promise resolving to a TransactionInstruction
+     */
+    updateActionRoleStrategy(signer: PublicKey, strategyId: number, action: Action, affectedRole: Role, update: Update): Promise<import("@solana/web3.js").TransactionInstruction>;
+    /**
+     * Updates action role permissions at the protocol level.
+     *
+     * @param signer - Public key of the admin signer
+     * @param action - The action being modified
+     * @param affectedRole - The role being modified
+     * @param update - The type of update (Grant or Revoke)
+     * @returns Promise resolving to a TransactionInstruction
+     */
     updateActionRoleProtocol(signer: PublicKey, action: Action, affectedRole: Role, update: Update): Promise<import("@solana/web3.js").TransactionInstruction>;
 }