@rotateprotocol/sdk 1.0.0

package/src/index.ts

@@ -0,0 +1,1538 @@
+/**
+ * Rotate Protocol SDK
+ * 
+ * Non-custodial P2P payment protocol for Solana.
+ * Your keys, your money. We never touch your funds.
+ * 
+ * @packageDocumentation
+ */
+
+import {
+  Connection,
+  PublicKey,
+  TransactionInstruction,
+  SystemProgram,
+  LAMPORTS_PER_SOL,
+} from '@solana/web3.js';
+import {
+  TOKEN_PROGRAM_ID,
+  getAssociatedTokenAddress,
+} from '@solana/spl-token';
+import * as anchor from '@coral-xyz/anchor';
+import { BN } from '@coral-xyz/anchor';
+
+// Import IDL
+import IDL from './idl/rotate_connect.json';
+
+// ==================== CONSTANTS ====================
+
+/** Rotate Protocol Program ID */
+export const PROGRAM_ID = new PublicKey('ELBYdNeCGeMThC2ccckw3fyAt77SniV3gPTo1fuFcxDg');
+
+/** Protocol fee in basis points (3%) */
+export const PROTOCOL_FEE_BPS = 300;
+
+/** Maximum platform fee in basis points (6%) */
+export const MAX_PLATFORM_FEE_BPS = 600;
+
+/** Minimum payment in USD (micro-USD, 6 decimals) - $5.00 */
+export const MIN_PAYMENT_USD = 5_000_000;
+
+/** Minimum payment in lamports (~$5 at ~$100/SOL) */
+export const MIN_PAYMENT_LAMPORTS = 50_000_000;
+
+/** Minimum payment in tokens (USDC/USDT) - $5.00 */
+export const MIN_PAYMENT_TOKENS = 5_000_000;
+
+/** Basis points denominator */
+export const BPS = 10000;
+
+/** Solana Memo Program ID */
+export const MEMO_PROGRAM_ID = new PublicKey('MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr');
+
+/** 7-digit ID range for platforms and merchants (sequential starting at 1000000) */
+export const MIN_RANDOM_ID = 1000000;
+export const MAX_RANDOM_ID = 9999999;
+
+/** PDA Seeds */
+export const SEEDS = {
+  PROTOCOL: Buffer.from('protocol'),
+  PLATFORM: Buffer.from('platform'),
+  MERCHANT: Buffer.from('merchant'),
+  LINK: Buffer.from('link'),
+} as const;
+
+/** Token mint addresses by network */
+export const TOKEN_MINTS = {
+  devnet: {
+    USDC: new PublicKey('4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU'),
+    USDT: new PublicKey('EJwZgeZrdC8TXTQbQBoL6bfuAnFUUy1PVCMB4DYPzVaS'),
+  },
+  'mainnet-beta': {
+    USDC: new PublicKey('EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'),
+    USDT: new PublicKey('Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB'),
+  },
+} as const;
+
+// ==================== TYPES ====================
+
+export type Network = 'devnet' | 'mainnet-beta';
+export type PaymentCurrency = 'SOL' | 'USDC' | 'USDT';
+
+export interface RotateConfig {
+  /** Solana network */
+  network: Network;
+  /** Custom RPC endpoint (optional) */
+  rpcEndpoint?: string;
+  /** Program ID override (optional) */
+  programId?: PublicKey;
+  /** Custom payment page base URL (default: https://rotate.app) */
+  paymentBaseUrl?: string;
+  /** Custom price API URL for SOL/USD conversion (default: CoinGecko) */
+  priceApiUrl?: string;
+  /**
+   * Custom QR code API URL template (optional).
+   * Use `{url}` as placeholder for the encoded payment URL, and `{size}` for the pixel dimension.
+   * Default: `https://api.qrserver.com/v1/create-qr-code/?size={size}x{size}&data={url}`
+   */
+  qrApiUrl?: string;
+  /**
+   * Number of retry attempts for link creation when a PDA collision occurs
+   * due to concurrent sequential ID assignment. Each retry re-fetches the
+   * protocol to get the latest `link_count`. Default: 3.
+   */
+  linkCreationRetries?: number;
+}
+
+export interface Protocol {
+  authority: PublicKey;
+  treasury: PublicKey;
+  usdcMint: PublicKey;
+  usdtMint: PublicKey;
+  platformCount: number;
+  merchantCount: number;
+  linkCount: number;
+  bump: number;
+}
+
+export interface Platform {
+  id: number;
+  admin: PublicKey;
+  wallet: PublicKey;
+  feeBps: number;
+  active: boolean;
+  bump: number;
+}
+
+export interface Merchant {
+  id: number;
+  platformId: number;
+  wallet: PublicKey;
+  active: boolean;
+  bump: number;
+}
+
+export interface PaymentLink {
+  id: number;
+  merchantId: number;
+  tokenType: 'Sol' | 'Usdc' | 'Usdt' | 'Usd';
+  tokenMint: PublicKey;
+  status: 'Pending' | 'PartiallyPaid' | 'Paid' | 'Cancelled';
+  allowTips: boolean;
+  allowPartial: boolean;
+  amount: bigint;
+  amountPaid: bigint;
+  expiresAt: number;
+  orderRef: string;
+  bump: number;
+}
+
+export interface CreatePlatformParams {
+  /** Platform fee in basis points (max 600 = 6%) */
+  feeBps: number;
+  /** Platform wallet address */
+  wallet: PublicKey;
+}
+
+export interface CreateMerchantParams {
+  /** Platform ID the merchant belongs to */
+  platformId: number;
+  /** Merchant's wallet address */
+  wallet: PublicKey;
+}
+
+export interface CreateLinkParams {
+  merchantId: number;
+  platformId: number;
+  /** Amount in lamports (SOL) or micro-units (tokens/USD) */
+  amount: bigint;
+  /** Expiration timestamp (0 = no expiration) */
+  expiresAt?: number;
+  allowTips?: boolean;
+  allowPartial?: boolean;
+  orderRef?: string;
+  /** Optional description stored as a memo on-chain (recoverable after cache clear) */
+  description?: string;
+}
+
+export interface PayLinkParams {
+  linkId: number;
+  merchantId: number;
+  platformId: number;
+  amount: bigint;
+  tip?: bigint;
+}
+
+export interface DirectPayParams {
+  merchantId: number;
+  platformId: number;
+  /** Amount in lamports (SOL) or micro-units (tokens) */
+  amount: bigint;
+  /** Your order reference ID */
+  orderRef?: string;
+}
+
+export interface CreateLinkTokenParams extends CreateLinkParams {
+  /** Token currency for the link */
+  currency: 'USDC' | 'USDT';
+}
+
+export interface UpdatePlatformParams {
+  platformId: number;
+  feeBps: number;
+  active: boolean;
+  /** New wallet address for fee collection */
+  newWallet: PublicKey;
+}
+
+export interface UpdateMerchantParams {
+  merchantId: number;
+  platformId: number;
+  active: boolean;
+  /** New wallet address */
+  newWallet: PublicKey;
+}
+
+// ==================== PDA HELPERS ====================
+
+export function getProtocolPda(programId: PublicKey = PROGRAM_ID): [PublicKey, number] {
+  return PublicKey.findProgramAddressSync([SEEDS.PROTOCOL], programId);
+}
+
+export function getPlatformPda(platformId: number, programId: PublicKey = PROGRAM_ID): [PublicKey, number] {
+  const idBuffer = Buffer.alloc(4);
+  idBuffer.writeUInt32LE(platformId);
+  return PublicKey.findProgramAddressSync([SEEDS.PLATFORM, idBuffer], programId);
+}
+
+export function getMerchantPda(merchantId: number, programId: PublicKey = PROGRAM_ID): [PublicKey, number] {
+  const idBuffer = Buffer.alloc(4);
+  idBuffer.writeUInt32LE(merchantId);
+  return PublicKey.findProgramAddressSync([SEEDS.MERCHANT, idBuffer], programId);
+}
+
+export function getLinkPda(linkId: number, programId: PublicKey = PROGRAM_ID): [PublicKey, number] {
+  const idBuffer = Buffer.alloc(4);
+  idBuffer.writeUInt32LE(linkId);
+  return PublicKey.findProgramAddressSync([SEEDS.LINK, idBuffer], programId);
+}
+
+// ==================== ID GENERATION ====================
+
+/**
+ * Generate a sample 7-digit ID within the valid range.
+ * For testing and display only — on-chain IDs are assigned
+ * automatically and sequentially by the protocol.
+ */
+function generateSampleId(): number {
+  return Math.floor(Math.random() * (MAX_RANDOM_ID - MIN_RANDOM_ID + 1)) + MIN_RANDOM_ID;
+}
+
+/**
+ * Validate that an ID is within the valid 7-digit range
+ */
+function isValidId(id: number): boolean {
+  return id >= MIN_RANDOM_ID && id <= MAX_RANDOM_ID;
+}
+
+// ==================== MEMO HELPERS ====================
+
+/** Memo prefix used by Rotate for on-chain descriptions */
+export const MEMO_PREFIX = 'rotate:';
+
+/**
+ * Create a memo instruction with a Rotate-prefixed description.
+ * Used internally by createLink* methods when `description` is provided.
+ */
+export function createMemoInstruction(description: string, signer: PublicKey): TransactionInstruction {
+  return new TransactionInstruction({
+    keys: [{ pubkey: signer, isSigner: true, isWritable: false }],
+    programId: MEMO_PROGRAM_ID,
+    data: Buffer.from(MEMO_PREFIX + description, 'utf-8'),
+  });
+}
+
+/**
+ * Recover a link description from its creation transaction memo.
+ * Returns null if no memo found or if the transaction doesn't have a Rotate memo.
+ *
+ * @param connection - Solana RPC connection
+ * @param linkId - The payment link ID
+ * @param programId - Optional custom program ID (defaults to PROGRAM_ID)
+ */
+export async function getLinkDescription(
+  connection: Connection,
+  linkId: number,
+  programId: PublicKey = PROGRAM_ID,
+): Promise<string | null> {
+  try {
+    const [linkPda] = getLinkPda(linkId, programId);
+    const sigs = await connection.getSignaturesForAddress(linkPda, { limit: 5 });
+    if (sigs.length === 0) return null;
+
+    // Oldest signature is the creation tx
+    const creationSig = sigs[sigs.length - 1].signature;
+    const txData = await connection.getTransaction(creationSig, { maxSupportedTransactionVersion: 0 });
+    if (!txData?.transaction?.message) return null;
+
+    const msg = txData.transaction.message;
+    const accountKeys = (msg as any).staticAccountKeys || (msg as any).accountKeys || [];
+    const ixs = (msg as any).compiledInstructions || (msg as any).instructions || [];
+
+    for (const ix of ixs) {
+      const progKey = accountKeys[ix.programIdIndex];
+      if (progKey && progKey.toString() === MEMO_PROGRAM_ID.toString()) {
+        const memoBytes = ix.data instanceof Uint8Array
+          ? ix.data
+          : typeof ix.data === 'string'
+            ? Buffer.from(ix.data, 'base64')
+            : ix.data;
+        const memoText = new TextDecoder().decode(memoBytes);
+        if (memoText.startsWith(MEMO_PREFIX)) {
+          return memoText.slice(MEMO_PREFIX.length);
+        }
+      }
+    }
+  } catch {
+    // Memo recovery is best-effort
+  }
+  return null;
+}
+
+// ==================== FEE CALCULATION ====================
+
+/**
+ * Calculate fees for a payment.
+ * Fees are split 50/50 between buyer and seller.
+ *
+ * **Rounding note:** When `totalFees` is odd, integer division means the
+ * seller share rounds down and the buyer pays one extra micro-unit.
+ * At worst this is a fraction of a cent and matches standard financial
+ * rounding conventions.
+ *
+ * @param amount  - Payment amount in smallest unit (lamports or micro-USD/tokens).
+ * @param platformFeeBps - Platform fee in basis points (0-600).
+ */
+export function calculateFees(amount: number, platformFeeBps: number) {
+  const protocolFee = Math.floor((amount * PROTOCOL_FEE_BPS) / BPS);
+  const platformFee = Math.floor((amount * platformFeeBps) / BPS);
+  const totalFees = protocolFee + platformFee;
+  
+  // 50/50 split — seller share rounds down; buyer absorbs the extra micro-unit on odd totals
+  const sellerFeeShare = Math.floor(totalFees / 2);
+  const buyerFeeShare = totalFees - sellerFeeShare;
+  
+  return {
+    amount,
+    protocolFee,
+    platformFee,
+    totalFees,
+    buyerFeeShare,
+    sellerFeeShare,
+    buyerPays: amount + buyerFeeShare,
+    merchantReceives: amount - sellerFeeShare,
+  };
+}
+
+// ==================== MAIN SDK CLASS ====================
+
+export class RotateSDK {
+  private connection: Connection;
+  private programId: PublicKey;
+  private network: Network;
+  // Typed as `any` because the IDL is imported as JSON — Anchor can't infer
+  // account types without generated Program<RotateConnect> bindings.
+  // Generate types with `anchor idl type` for full type safety.
+  private program: any = null;
+  private paymentBaseUrl: string;
+  private priceApiUrl: string;
+  private qrApiUrl: string;
+  private linkCreationRetries: number;
+  
+  constructor(config: RotateConfig) {
+    this.network = config.network;
+    this.programId = config.programId || PROGRAM_ID;
+    this.paymentBaseUrl = config.paymentBaseUrl || 'https://rotate.app';
+    this.priceApiUrl = config.priceApiUrl || 'https://api.coingecko.com/api/v3/simple/price?ids=solana&vs_currencies=usd';
+    this.qrApiUrl = config.qrApiUrl || 'https://api.qrserver.com/v1/create-qr-code/?size={size}x{size}&data={url}';
+    this.linkCreationRetries = config.linkCreationRetries ?? 3;
+    
+    const endpoint = config.rpcEndpoint || 
+      (config.network === 'mainnet-beta' 
+        ? 'https://api.mainnet-beta.solana.com'
+        : 'https://api.devnet.solana.com');
+    
+    this.connection = new Connection(endpoint, 'confirmed');
+  }
+
+  /**
+   * Initialize with a wallet (required for transactions)
+   */
+  initWithWallet(wallet: anchor.Wallet): void {
+    const provider = new anchor.AnchorProvider(
+      this.connection,
+      wallet,
+      { commitment: 'confirmed' }
+    );
+    this.program = new anchor.Program(IDL as any, provider);
+  }
+
+  /**
+   * Get the Anchor program instance.
+   * Throws if `initWithWallet()` has not been called.
+   *
+   * Returns `any` because the IDL is loaded from JSON at runtime.
+   * For full type safety, generate types with `anchor idl type` and
+   * cast the return value to `Program<RotateConnect>`.
+   */
+  getProgram(): any {
+    if (!this.program) {
+      throw new Error('SDK not initialized with wallet. Call initWithWallet() first.');
+    }
+    return this.program;
+  }
+
+  /**
+   * Get connection
+   */
+  getConnection(): Connection {
+    return this.connection;
+  }
+  
+  // ==================== READ METHODS ====================
+  
+  /**
+   * Get protocol data
+   */
+  async getProtocol(): Promise<Protocol | null> {
+    try {
+      const [pda] = getProtocolPda(this.programId);
+      const account = await this.connection.getAccountInfo(pda);
+      if (!account) return null;
+      
+      return this.decodeProtocol(account.data);
+    } catch {
+      return null;
+    }
+  }
+  
+  /**
+   * Get platform data
+   */
+  async getPlatform(platformId: number): Promise<Platform | null> {
+    try {
+      const [pda] = getPlatformPda(platformId, this.programId);
+      const account = await this.connection.getAccountInfo(pda);
+      if (!account) return null;
+      
+      return this.decodePlatform(account.data);
+    } catch {
+      return null;
+    }
+  }
+  
+  /**
+   * Get merchant data
+   */
+  async getMerchant(merchantId: number): Promise<Merchant | null> {
+    try {
+      const [pda] = getMerchantPda(merchantId, this.programId);
+      const account = await this.connection.getAccountInfo(pda);
+      if (!account) return null;
+      
+      return this.decodeMerchant(account.data);
+    } catch {
+      return null;
+    }
+  }
+  
+  /**
+   * Get payment link data
+   */
+  async getPaymentLink(linkId: number): Promise<PaymentLink | null> {
+    try {
+      const [pda] = getLinkPda(linkId, this.programId);
+      const account = await this.connection.getAccountInfo(pda);
+      if (!account) return null;
+      
+      return this.decodePaymentLink(account.data);
+    } catch {
+      return null;
+    }
+  }
+  
+  /**
+   * Check if a payment link is paid
+   */
+  async isLinkPaid(linkId: number): Promise<boolean> {
+    const link = await this.getPaymentLink(linkId);
+    return link?.status === 'Paid';
+  }
+  
+  /**
+   * Poll for payment status
+   */
+  async waitForPayment(linkId: number, timeoutMs: number = 300000): Promise<PaymentLink | null> {
+    const startTime = Date.now();
+    
+    while (Date.now() - startTime < timeoutMs) {
+      const link = await this.getPaymentLink(linkId);
+      if (link?.status === 'Paid') {
+        return link;
+      }
+      
+      await new Promise(resolve => setTimeout(resolve, 2000));
+    }
+    
+    return null;
+  }
+
+  // ==================== WRITE METHODS ====================
+
+  /**
+   * Internal helper: retry a link-creation callback when a PDA collision
+   * occurs (e.g. two concurrent `createLink*` calls compute the same
+   * `nextLinkId`).  On each retry the protocol is re-fetched to pick up
+   * the incremented `link_count`.
+   */
+  private async _retryLinkCreation<T>(
+    fn: (nextLinkId: number) => Promise<T>,
+  ): Promise<T> {
+    let lastError: any;
+    for (let attempt = 0; attempt <= this.linkCreationRetries; attempt++) {
+      try {
+        const protocol = await this.getProtocol();
+        if (!protocol) throw new Error('Protocol not initialized');
+        const nextLinkId = protocol.linkCount + 1;
+        return await fn(nextLinkId);
+      } catch (err: any) {
+        lastError = err;
+        if (!RotateSDK._isPdaCollision(err) || attempt === this.linkCreationRetries) throw err;
+        // Exponential back-off before retry to let the previous tx confirm
+        await new Promise(r => setTimeout(r, 500 * 2 ** attempt));
+      }
+    }
+    throw lastError;
+  }
+
+  /**
+   * Detect whether an error is a PDA-collision ("account already in use").
+   *
+   * Checks multiple signals so the heuristic survives Anchor / runtime
+   * message changes:
+   *   1. Error message substrings (Anchor & system program phrasing).
+   *   2. Anchor structured error codes (`err.error.errorCode`).
+   *   3. Transaction logs emitted by the runtime.
+   *
+   * @internal
+   */
+  private static _isPdaCollision(err: any): boolean {
+    // 1. Message-based detection (covers most Anchor versions)
+    const msg: string = (err?.message || '') + ' ' + (err?.error?.errorMessage || '');
+    if (
+      msg.includes('already in use') ||
+      msg.includes('AccountAlreadyExists') ||
+      // 0x0 is the system-program error code for "account already exists"
+      // when surfaced through Anchor's error wrapper
+      msg.includes('0x0')
+    ) {
+      return true;
+    }
+
+    // 2. Anchor structured error code (numeric)
+    //    System program "AccountAlreadyExists" is code 0 in Anchor's mapping.
+    const code = err?.error?.errorCode?.number ?? err?.code;
+    if (code === 0) return true;
+
+    // 3. Transaction log inspection (runtime logs the system-program error)
+    const logs: string[] | undefined = err?.logs ?? err?.error?.logs;
+    if (Array.isArray(logs) && logs.some((l: string) => l.includes('already in use'))) {
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Create a new platform with a random 7-digit ID
+   * @returns Transaction signature and the generated platform ID
+   */
+  async createPlatform(params: CreatePlatformParams): Promise<{ tx: string; platformId: number }> {
+    const program = this.getProgram();
+    const protocol = await this.getProtocol();
+    if (!protocol) throw new Error('Protocol not initialized');
+
+    // 7-digit sequential ID: 1000000 + platform_count
+    const platformId = MIN_RANDOM_ID + protocol.platformCount;
+
+    const [platformPda] = getPlatformPda(platformId, this.programId);
+    const [protocolPda] = getProtocolPda(this.programId);
+
+    const tx = await program.methods
+      .createPlatform(params.feeBps)
+      .accounts({
+        protocol: protocolPda,
+        platform: platformPda,
+        wallet: params.wallet,
+        admin: program.provider.publicKey,
+        systemProgram: SystemProgram.programId,
+      })
+      .rpc();
+
+    return { tx, platformId };
+  }
+
+  /**
+   * Create a new merchant with a random 7-digit ID
+   * @returns Transaction signature and the generated merchant ID
+   */
+  async createMerchant(params: CreateMerchantParams): Promise<{ tx: string; merchantId: number }> {
+    const program = this.getProgram();
+    const protocol = await this.getProtocol();
+    if (!protocol) throw new Error('Protocol not initialized');
+
+    // 7-digit sequential ID: 1000000 + merchant_count
+    const merchantId = MIN_RANDOM_ID + protocol.merchantCount;
+
+    const [merchantPda] = getMerchantPda(merchantId, this.programId);
+    const [platformPda] = getPlatformPda(params.platformId, this.programId);
+    const [protocolPda] = getProtocolPda(this.programId);
+
+    const tx = await program.methods
+      .createMerchant()
+      .accounts({
+        protocol: protocolPda,
+        platform: platformPda,
+        merchant: merchantPda,
+        wallet: params.wallet,
+        payer: program.provider.publicKey,
+        systemProgram: SystemProgram.programId,
+      })
+      .rpc();
+
+    return { tx, merchantId };
+  }
+
+  /**
+   * Create a USD-denominated payment link.
+   *
+   * Automatically retries on PDA collision (concurrent link creation).
+   */
+  async createLinkUsd(params: CreateLinkParams): Promise<{ tx: string; linkId: number }> {
+    return this._retryLinkCreation(async (nextLinkId) => {
+      const program = this.getProgram();
+      const [linkPda] = getLinkPda(nextLinkId, this.programId);
+      const [platformPda] = getPlatformPda(params.platformId, this.programId);
+      const [merchantPda] = getMerchantPda(params.merchantId, this.programId);
+      const [protocolPda] = getProtocolPda(this.programId);
+
+      const builder = program.methods
+        .createLinkUsd(
+          new BN(params.amount.toString()),
+          new BN(params.expiresAt || 0),
+          params.allowTips ?? false,
+          params.allowPartial ?? false,
+          new BN(params.orderRef || Date.now().toString())
+        )
+        .accounts({
+          protocol: protocolPda,
+          platform: platformPda,
+          merchant: merchantPda,
+          link: linkPda,
+          creator: program.provider.publicKey,
+          systemProgram: SystemProgram.programId,
+        });
+
+      // Attach description as on-chain memo (recoverable after cache clear)
+      if (params.description) {
+        builder.postInstructions([createMemoInstruction(params.description, program.provider.publicKey!)]);
+      }
+
+      const tx = await builder.rpc();
+      return { tx, linkId: nextLinkId };
+    });
+  }
+
+  /**
+   * Create a SOL payment link.
+   *
+   * Automatically retries on PDA collision (concurrent link creation).
+   */
+  async createLinkSol(params: CreateLinkParams): Promise<{ tx: string; linkId: number }> {
+    return this._retryLinkCreation(async (nextLinkId) => {
+      const program = this.getProgram();
+      const [linkPda] = getLinkPda(nextLinkId, this.programId);
+      const [platformPda] = getPlatformPda(params.platformId, this.programId);
+      const [merchantPda] = getMerchantPda(params.merchantId, this.programId);
+      const [protocolPda] = getProtocolPda(this.programId);
+
+      const builder = program.methods
+        .createLinkSol(
+          new BN(params.amount.toString()),
+          new BN(params.expiresAt || 0),
+          params.allowTips ?? false,
+          params.allowPartial ?? false,
+          new BN(params.orderRef || Date.now().toString())
+        )
+        .accounts({
+          protocol: protocolPda,
+          platform: platformPda,
+          merchant: merchantPda,
+          link: linkPda,
+          creator: program.provider.publicKey,
+          systemProgram: SystemProgram.programId,
+        });
+
+      if (params.description) {
+        builder.postInstructions([createMemoInstruction(params.description, program.provider.publicKey!)]);
+      }
+
+      const tx = await builder.rpc();
+      return { tx, linkId: nextLinkId };
+    });
+  }
+
+  /**
+   * Pay a SOL link
+   */
+  async payLinkSol(params: PayLinkParams): Promise<string> {
+    const program = this.getProgram();
+    const protocol = await this.getProtocol();
+    if (!protocol) throw new Error('Protocol not initialized');
+
+    const merchant = await this.getMerchant(params.merchantId);
+    if (!merchant) throw new Error('Merchant not found');
+
+    const platform = await this.getPlatform(params.platformId);
+    if (!platform) throw new Error('Platform not found');
+
+    const [linkPda] = getLinkPda(params.linkId, this.programId);
+    const [platformPda] = getPlatformPda(params.platformId, this.programId);
+    const [merchantPda] = getMerchantPda(params.merchantId, this.programId);
+    const [protocolPda] = getProtocolPda(this.programId);
+
+    const tx = await program.methods
+      .payLinkSol(
+        new BN(params.amount.toString()),
+        new BN((params.tip || 0n).toString())
+      )
+      .accounts({
+        protocol: protocolPda,
+        platform: platformPda,
+        merchant: merchantPda,
+        link: linkPda,
+        merchantWallet: merchant.wallet,
+        platformWallet: platform.wallet,
+        treasury: protocol.treasury,
+        payer: program.provider.publicKey,
+        systemProgram: SystemProgram.programId,
+      })
+      .rpc();
+
+    return tx;
+  }
+
+  /**
+   * Pay a USD link with SOL
+   * 
+   * Includes on-chain price oracle slippage protection. If `expectedLamports` is provided,
+   * the contract validates that `lamportsAmount` is within 5% of the expected value.
+   * Pass 0n or omit to skip on-chain slippage validation (backwards-compatible).
+   */
+  async payLinkUsdSol(
+    params: PayLinkParams & { lamportsAmount: bigint; tipUsd?: bigint; tipLamports?: bigint; expectedLamports?: bigint }
+  ): Promise<string> {
+    const program = this.getProgram();
+    const protocol = await this.getProtocol();
+    if (!protocol) throw new Error('Protocol not initialized');
+
+    const merchant = await this.getMerchant(params.merchantId);
+    if (!merchant) throw new Error('Merchant not found');
+
+    const platform = await this.getPlatform(params.platformId);
+    if (!platform) throw new Error('Platform not found');
+
+    // If no expectedLamports provided, auto-fetch from oracle for slippage protection.
+    // If the price API is unavailable, we throw rather than silently skipping the
+    // on-chain slippage check — paying without price validation risks loss of funds.
+    let expectedLamports = params.expectedLamports || 0n;
+    if (expectedLamports === 0n) {
+      expectedLamports = await this.microUsdToLamports(params.amount);
+    }
+
+    const [linkPda] = getLinkPda(params.linkId, this.programId);
+    const [platformPda] = getPlatformPda(params.platformId, this.programId);
+    const [merchantPda] = getMerchantPda(params.merchantId, this.programId);
+    const [protocolPda] = getProtocolPda(this.programId);
+
+    const tx = await program.methods
+      .payLinkUsdSol(
+        new BN(params.amount.toString()), // usd_amount
+        new BN((params.tipUsd || 0n).toString()), // tip_usd
+        new BN(params.lamportsAmount.toString()), // lamports_amount
+        new BN((params.tipLamports || 0n).toString()), // tip_lamports
+        new BN(expectedLamports.toString()) // expected_lamports (oracle slippage check)
+      )
+      .accounts({
+        protocol: protocolPda,
+        platform: platformPda,
+        merchant: merchantPda,
+        link: linkPda,
+        merchantWallet: merchant.wallet,
+        platformWallet: platform.wallet,
+        treasury: protocol.treasury,
+        payer: program.provider.publicKey,
+        systemProgram: SystemProgram.programId,
+      })
+      .rpc();
+
+    return tx;
+  }
+
+  /**
+   * Pay a USD link with token (USDC/USDT)
+   */
+  async payLinkUsdToken(
+    params: PayLinkParams & { tipUsd?: bigint; currency: 'USDC' | 'USDT' }
+  ): Promise<string> {
+    const program = this.getProgram();
+    const protocol = await this.getProtocol();
+    if (!protocol) throw new Error('Protocol not initialized');
+
+    const merchant = await this.getMerchant(params.merchantId);
+    if (!merchant) throw new Error('Merchant not found');
+
+    const platform = await this.getPlatform(params.platformId);
+    if (!platform) throw new Error('Platform not found');
+
+    const mint = this.getTokenMint(params.currency);
+    
+    const payerAta = await getAssociatedTokenAddress(mint, program.provider.publicKey);
+    const merchantAta = await getAssociatedTokenAddress(mint, merchant.wallet);
+    const platformAta = await getAssociatedTokenAddress(mint, platform.wallet);
+    const treasuryAta = await getAssociatedTokenAddress(mint, protocol.treasury);
+
+    const [linkPda] = getLinkPda(params.linkId, this.programId);
+    const [platformPda] = getPlatformPda(params.platformId, this.programId);
+    const [merchantPda] = getMerchantPda(params.merchantId, this.programId);
+    const [protocolPda] = getProtocolPda(this.programId);
+
+    const tx = await program.methods
+      .payLinkUsdToken(
+        new BN(params.amount.toString()), // usd_amount
+        new BN((params.tipUsd || 0n).toString()) // tip_usd
+      )
+      .accounts({
+        protocol: protocolPda,
+        platform: platformPda,
+        merchant: merchantPda,
+        link: linkPda,
+        payerTokenAccount: payerAta,
+        merchantTokenAccount: merchantAta,
+        platformTokenAccount: platformAta,
+        treasuryTokenAccount: treasuryAta,
+        payer: program.provider.publicKey,
+        tokenProgram: TOKEN_PROGRAM_ID,
+      })
+      .rpc();
+
+    return tx;
+  }
+
+  /**
+   * Cancel a payment link
+   */
+  async cancelLink(linkId: number, merchantId: number): Promise<string> {
+    const program = this.getProgram();
+    
+    const merchant = await this.getMerchant(merchantId);
+    if (!merchant) throw new Error('Merchant not found');
+
+    const [linkPda] = getLinkPda(linkId, this.programId);
+    const [merchantPda] = getMerchantPda(merchantId, this.programId);
+    const [platformPda] = getPlatformPda(merchant.platformId, this.programId);
+
+    const tx = await program.methods
+      .cancelLink()
+      .accounts({
+        merchant: merchantPda,
+        platform: platformPda,
+        link: linkPda,
+        authority: program.provider.publicKey,
+      })
+      .rpc();
+
+    return tx;
+  }
+  
+  // ==================== BATCH READ METHODS ====================
+
+  /**
+   * Fetch all merchant accounts belonging to a specific platform using
+   * `getProgramAccounts` with a `memcmp` filter.
+   *
+   * This is **significantly** faster than iterating through every merchant
+   * ID sequentially, especially for platforms with many merchants.
+   *
+   * The filter matches the `platform_id` field at byte offset 12 inside
+   * the Merchant account data (8-byte discriminator + 4-byte `id`).
+   *
+   * @param platformId - The platform ID to filter by.
+   * @param activeOnly - If true, only return active merchants (default: false).
+   */
+  async getMerchantsByPlatform(platformId: number, activeOnly: boolean = false): Promise<Merchant[]> {
+    const platformIdBuf = Buffer.alloc(4);
+    platformIdBuf.writeUInt32LE(platformId);
+
+    const accounts = await this.connection.getProgramAccounts(this.programId, {
+      filters: [
+        { memcmp: { offset: 0, bytes: RotateSDK.DISCRIMINATORS.Merchant.toString('base64') } },
+        { memcmp: { offset: 12, bytes: platformIdBuf.toString('base64') } },
+      ],
+    });
+
+    const merchants: Merchant[] = [];
+    for (const { account } of accounts) {
+      try {
+        const merchant = this.decodeMerchant(account.data as Buffer);
+        if (activeOnly && !merchant.active) continue;
+        merchants.push(merchant);
+      } catch {
+        // Skip accounts that fail to decode
+      }
+    }
+
+    return merchants;
+  }
+
+  // ==================== PROTOCOL ADMIN ====================
+
+  /**
+   * Update the protocol treasury address (authority only).
+   * Only the original protocol authority can call this.
+   */
+  async updateProtocol(newTreasury: PublicKey): Promise<string> {
+    const program = this.getProgram();
+    const [protocolPda] = getProtocolPda(this.programId);
+
+    const tx = await program.methods
+      .updateProtocol()
+      .accounts({
+        protocol: protocolPda,
+        newTreasury,
+        authority: program.provider.publicKey,
+      })
+      .rpc();
+
+    return tx;
+  }
+
+  // ==================== RENT RECLAMATION ====================
+
+  /**
+   * Close a completed/cancelled link and reclaim rent SOL back to the merchant wallet.
+   * Only works on links with status Paid or Cancelled.
+   */
+  async closeLink(linkId: number, merchantId: number): Promise<string> {
+    const program = this.getProgram();
+
+    const [linkPda] = getLinkPda(linkId, this.programId);
+    const [merchantPda] = getMerchantPda(merchantId, this.programId);
+
+    const tx = await program.methods
+      .closeLink()
+      .accounts({
+        merchant: merchantPda,
+        link: linkPda,
+        authority: program.provider.publicKey,
+      })
+      .rpc();
+
+    return tx;
+  }
+
+  // ==================== TOKEN LINK METHODS ====================
+
+  /**
+   * Create a token (USDC/USDT) payment link.
+   *
+   * Automatically retries on PDA collision (concurrent link creation).
+   */
+  async createLinkToken(params: CreateLinkTokenParams): Promise<{ tx: string; linkId: number }> {
+    return this._retryLinkCreation(async (nextLinkId) => {
+      const program = this.getProgram();
+      const mint = this.getTokenMint(params.currency);
+      const [linkPda] = getLinkPda(nextLinkId, this.programId);
+      const [platformPda] = getPlatformPda(params.platformId, this.programId);
+      const [merchantPda] = getMerchantPda(params.merchantId, this.programId);
+      const [protocolPda] = getProtocolPda(this.programId);
+
+      const builder = program.methods
+        .createLinkToken(
+          new BN(params.amount.toString()),
+          new BN(params.expiresAt || 0),
+          params.allowTips ?? false,
+          params.allowPartial ?? false,
+          new BN(params.orderRef || Date.now().toString())
+        )
+        .accounts({
+          protocol: protocolPda,
+          platform: platformPda,
+          merchant: merchantPda,
+          link: linkPda,
+          tokenMint: mint,
+          creator: program.provider.publicKey,
+          systemProgram: SystemProgram.programId,
+        });
+
+      if (params.description) {
+        builder.postInstructions([createMemoInstruction(params.description, program.provider.publicKey!)]);
+      }
+
+      const tx = await builder.rpc();
+      return { tx, linkId: nextLinkId };
+    });
+  }
+
+  /**
+   * Pay a token (USDC/USDT) link
+   */
+  async payLinkToken(params: PayLinkParams & { currency: 'USDC' | 'USDT' }): Promise<string> {
+    const program = this.getProgram();
+    const protocol = await this.getProtocol();
+    if (!protocol) throw new Error('Protocol not initialized');
+
+    const merchant = await this.getMerchant(params.merchantId);
+    if (!merchant) throw new Error('Merchant not found');
+
+    const platform = await this.getPlatform(params.platformId);
+    if (!platform) throw new Error('Platform not found');
+
+    const mint = this.getTokenMint(params.currency);
+
+    const payerAta = await getAssociatedTokenAddress(mint, program.provider.publicKey);
+    const merchantAta = await getAssociatedTokenAddress(mint, merchant.wallet);
+    const platformAta = await getAssociatedTokenAddress(mint, platform.wallet);
+    const treasuryAta = await getAssociatedTokenAddress(mint, protocol.treasury);
+
+    const [linkPda] = getLinkPda(params.linkId, this.programId);
+    const [platformPda] = getPlatformPda(params.platformId, this.programId);
+    const [merchantPda] = getMerchantPda(params.merchantId, this.programId);
+    const [protocolPda] = getProtocolPda(this.programId);
+
+    const tx = await program.methods
+      .payLinkToken(
+        new BN(params.amount.toString()),
+        new BN((params.tip || 0n).toString())
+      )
+      .accounts({
+        protocol: protocolPda,
+        platform: platformPda,
+        merchant: merchantPda,
+        link: linkPda,
+        payerTokenAccount: payerAta,
+        merchantTokenAccount: merchantAta,
+        platformTokenAccount: platformAta,
+        treasuryTokenAccount: treasuryAta,
+        payer: program.provider.publicKey,
+        tokenProgram: TOKEN_PROGRAM_ID,
+      })
+      .rpc();
+
+    return tx;
+  }
+
+  // ==================== DIRECT PAYMENT METHODS ====================
+
+  /**
+   * Pay with SOL directly (no payment link)
+   */
+  async paySol(params: DirectPayParams): Promise<string> {
+    const program = this.getProgram();
+    const protocol = await this.getProtocol();
+    if (!protocol) throw new Error('Protocol not initialized');
+
+    const merchant = await this.getMerchant(params.merchantId);
+    if (!merchant) throw new Error('Merchant not found');
+
+    const platform = await this.getPlatform(params.platformId);
+    if (!platform) throw new Error('Platform not found');
+
+    const [platformPda] = getPlatformPda(params.platformId, this.programId);
+    const [merchantPda] = getMerchantPda(params.merchantId, this.programId);
+    const [protocolPda] = getProtocolPda(this.programId);
+
+    const tx = await program.methods
+      .paySol(
+        new BN(params.amount.toString()),
+        new BN(params.orderRef || Date.now().toString())
+      )
+      .accounts({
+        protocol: protocolPda,
+        platform: platformPda,
+        merchant: merchantPda,
+        merchantWallet: merchant.wallet,
+        platformWallet: platform.wallet,
+        treasury: protocol.treasury,
+        payer: program.provider.publicKey,
+        systemProgram: SystemProgram.programId,
+      })
+      .rpc();
+
+    return tx;
+  }
+
+  /**
+   * Pay with token (USDC/USDT) directly (no payment link)
+   */
+  async payToken(params: DirectPayParams & { currency: 'USDC' | 'USDT' }): Promise<string> {
+    const program = this.getProgram();
+    const protocol = await this.getProtocol();
+    if (!protocol) throw new Error('Protocol not initialized');
+
+    const merchant = await this.getMerchant(params.merchantId);
+    if (!merchant) throw new Error('Merchant not found');
+
+    const platform = await this.getPlatform(params.platformId);
+    if (!platform) throw new Error('Platform not found');
+
+    const mint = this.getTokenMint(params.currency);
+
+    const payerAta = await getAssociatedTokenAddress(mint, program.provider.publicKey);
+    const merchantAta = await getAssociatedTokenAddress(mint, merchant.wallet);
+    const platformAta = await getAssociatedTokenAddress(mint, platform.wallet);
+    const treasuryAta = await getAssociatedTokenAddress(mint, protocol.treasury);
+
+    const [platformPda] = getPlatformPda(params.platformId, this.programId);
+    const [merchantPda] = getMerchantPda(params.merchantId, this.programId);
+    const [protocolPda] = getProtocolPda(this.programId);
+
+    const tx = await program.methods
+      .payToken(
+        new BN(params.amount.toString()),
+        new BN(params.orderRef || Date.now().toString())
+      )
+      .accounts({
+        protocol: protocolPda,
+        platform: platformPda,
+        merchant: merchantPda,
+        payerTokenAccount: payerAta,
+        merchantTokenAccount: merchantAta,
+        platformTokenAccount: platformAta,
+        treasuryTokenAccount: treasuryAta,
+        payer: program.provider.publicKey,
+        tokenProgram: TOKEN_PROGRAM_ID,
+      })
+      .rpc();
+
+    return tx;
+  }
+
+  // ==================== UPDATE METHODS ====================
+
+  /**
+   * Update platform settings (admin only)
+   */
+  async updatePlatform(params: UpdatePlatformParams): Promise<string> {
+    const program = this.getProgram();
+
+    const [platformPda] = getPlatformPda(params.platformId, this.programId);
+
+    const tx = await program.methods
+      .updatePlatform(params.feeBps, params.active)
+      .accounts({
+        platform: platformPda,
+        newWallet: params.newWallet,
+        admin: program.provider.publicKey,
+      })
+      .rpc();
+
+    return tx;
+  }
+
+  /**
+   * Update merchant settings (wallet owner only)
+   */
+  async updateMerchant(params: UpdateMerchantParams): Promise<string> {
+    const program = this.getProgram();
+
+    const [merchantPda] = getMerchantPda(params.merchantId, this.programId);
+    const [platformPda] = getPlatformPda(params.platformId, this.programId);
+
+    const tx = await program.methods
+      .updateMerchant(params.active)
+      .accounts({
+        platform: platformPda,
+        merchant: merchantPda,
+        newWallet: params.newWallet,
+        authority: program.provider.publicKey,
+      })
+      .rpc();
+
+    return tx;
+  }
+
+  // ==================== PAYMENT URL GENERATION ====================
+  
+  /**
+   * Generate payment URL for a link.
+   * 
+   * URL format: `{base}/checkout/?link={id}&network={network}`
+   * 
+   * The checkout page reads query parameters to load payment data from on-chain.
+   * Merchant and platform IDs are resolved from the on-chain link automatically,
+   * but can be provided explicitly for faster loading.
+   * 
+   * @param linkId - The payment link ID.
+   * @param options - Optional overrides for base URL, merchant/platform IDs, and brand.
+   */
+  getPaymentUrl(linkId: number, baseUrl?: string): string {
+    const url = baseUrl || this.paymentBaseUrl;
+    const params = new URLSearchParams({ link: String(linkId), network: this.network });
+    return `${url}/checkout/?${params.toString()}`;
+  }
+  
+  /**
+   * Generate QR code URL for a payment link.
+   * Uses the configurable `qrApiUrl` template (default: api.qrserver.com).
+   */
+  getQRCodeUrl(linkId: number, baseUrl?: string, size: number = 300): string {
+    const paymentUrl = this.getPaymentUrl(linkId, baseUrl);
+    return this.qrApiUrl
+      .replace('{url}', encodeURIComponent(paymentUrl))
+      .replace(/\{size\}/g, String(size));
+  }
+  
+  // ==================== PRICE CONVERSION ====================
+  
+  /**
+   * Get current SOL price in USD.
+   * Uses the configurable `priceApiUrl` (defaults to CoinGecko).
+   *
+   * **Throws** if the price API is unreachable or returns an unexpected
+   * format, rather than silently falling back to a stale hardcoded value.
+   * Callers that need a fallback should catch the error themselves.
+   *
+   * @throws {Error} If the price API request fails or returns no price.
+   */
+  async getSolPrice(): Promise<number> {
+    const response = await fetch(this.priceApiUrl);
+    if (!response.ok) {
+      throw new Error(`SOL price API returned HTTP ${response.status}`);
+    }
+    const data = await response.json() as { solana?: { usd?: number } };
+    const price = data.solana?.usd;
+    if (typeof price !== 'number' || price <= 0) {
+      throw new Error(
+        'SOL price API returned an invalid or missing price. ' +
+        'Ensure the priceApiUrl returns { solana: { usd: <number> } }.'
+      );
+    }
+    return price;
+  }
+
+  /**
+   * Get current SOL price in USD, with a fallback value on failure.
+   *
+   * Use this when a best-effort price is acceptable (e.g. UI display).
+   * For payment-critical paths, prefer `getSolPrice()` which throws on
+   * failure so you can surface the error to the user.
+   *
+   * @param fallback - Price to return if the API call fails (default: 100).
+   */
+  async getSolPriceSafe(fallback: number = 100): Promise<number> {
+    try {
+      return await this.getSolPrice();
+    } catch {
+      return fallback;
+    }
+  }
+  
+  /**
+   * Convert USD to lamports.
+   *
+   * @throws {Error} If the SOL price cannot be fetched (propagated from `getSolPrice`).
+   */
+  async usdToLamports(usdAmount: number): Promise<bigint> {
+    const solPrice = await this.getSolPrice();
+    const solAmount = usdAmount / solPrice;
+    return BigInt(Math.floor(solAmount * LAMPORTS_PER_SOL));
+  }
+  
+  /**
+   * Convert micro-USD to lamports.
+   *
+   * @throws {Error} If the SOL price cannot be fetched (propagated from `getSolPrice`).
+   */
+  async microUsdToLamports(microUsd: bigint): Promise<bigint> {
+    const usdAmount = Number(microUsd) / 1_000_000;
+    return this.usdToLamports(usdAmount);
+  }
+  
+  // ==================== TOKEN HELPERS ====================
+  
+  /**
+   * Get token mint address for currency
+   */
+  getTokenMint(currency: 'USDC' | 'USDT'): PublicKey {
+    return TOKEN_MINTS[this.network][currency];
+  }
+  
+  /**
+   * Get token balance
+   */
+  async getTokenBalance(walletAddress: PublicKey, currency: 'USDC' | 'USDT'): Promise<number> {
+    try {
+      const mint = this.getTokenMint(currency);
+      const ata = await getAssociatedTokenAddress(mint, walletAddress);
+      const balance = await this.connection.getTokenAccountBalance(ata);
+      return Number(balance.value.uiAmount);
+    } catch {
+      return 0;
+    }
+  }
+  
+  // ==================== DECODE HELPERS ====================
+
+  /**
+   * Anchor account discriminators: `sha256("account:<Name>")[0..8]`.
+   * Used by `getProgramAccounts` filters and for decode-time validation.
+   *
+   * To regenerate:
+   * ```ts
+   * import { createHash } from 'crypto';
+   * createHash('sha256').update('account:Merchant').digest().slice(0, 8);
+   * ```
+   */
+  private static readonly DISCRIMINATORS = {
+    // sha256("account:Protocol")[0..8]
+    Protocol:    Buffer.from([0x2d, 0x27, 0x65, 0x2b, 0x73, 0x48, 0x83, 0x28]),
+    // sha256("account:Platform")[0..8]
+    Platform:    Buffer.from([0x4d, 0x5c, 0xcc, 0x3a, 0xbb, 0x62, 0x5b, 0x0c]),
+    // sha256("account:Merchant")[0..8]
+    Merchant:    Buffer.from([0x47, 0xeb, 0x1e, 0x28, 0xe7, 0x15, 0x20, 0x40]),
+    // sha256("account:PaymentLink")[0..8]
+    PaymentLink: Buffer.from([0xa9, 0xf7, 0x93, 0xbd, 0x27, 0xef, 0x0e, 0x26]),
+  } as const;
+
+  /** Expected on-chain account sizes (discriminator included). */
+  private static readonly ACCOUNT_SIZES = {
+    Protocol:    149, // 8 + 32 + 32 + 32 + 32 + 4 + 4 + 4 + 1
+    Platform:     80, // 8 + 4 + 32 + 32 + 2 + 1 + 1
+    Merchant:     50, // 8 + 4 + 4 + 32 + 1 + 1
+    PaymentLink:  85, // 8 + 4 + 4 + 1 + 32 + 1 + 1 + 1 + 8 + 8 + 8 + 8 + 1
+  } as const;
+
+  /** Validate buffer length and (optionally) discriminator before decoding. */
+  private static assertAccountData(
+    data: Buffer,
+    accountName: keyof typeof RotateSDK.DISCRIMINATORS,
+  ): void {
+    const minSize = RotateSDK.ACCOUNT_SIZES[accountName];
+    if (data.length < minSize) {
+      throw new Error(
+        `${accountName} account data too short: expected >= ${minSize} bytes, got ${data.length}`,
+      );
+    }
+    const expected = RotateSDK.DISCRIMINATORS[accountName];
+    const actual = data.slice(0, 8);
+    if (!actual.equals(expected)) {
+      throw new Error(
+        `${accountName} discriminator mismatch: expected ${expected.toString('hex')}, got ${actual.toString('hex')}`,
+      );
+    }
+  }
+
+  private decodeProtocol(data: Buffer): Protocol {
+    RotateSDK.assertAccountData(data, 'Protocol');
+    let offset = 8;
+    
+    const authority = new PublicKey(data.slice(offset, offset + 32));
+    offset += 32;
+    const treasury = new PublicKey(data.slice(offset, offset + 32));
+    offset += 32;
+    const usdcMint = new PublicKey(data.slice(offset, offset + 32));
+    offset += 32;
+    const usdtMint = new PublicKey(data.slice(offset, offset + 32));
+    offset += 32;
+    const platformCount = data.readUInt32LE(offset);
+    offset += 4;
+    const merchantCount = data.readUInt32LE(offset);
+    offset += 4;
+    const linkCount = data.readUInt32LE(offset);
+    offset += 4;
+    const bump = data.readUInt8(offset);
+    
+    return {
+      authority,
+      treasury,
+      usdcMint,
+      usdtMint,
+      platformCount,
+      merchantCount,
+      linkCount,
+      bump,
+    };
+  }
+  
+  private decodePlatform(data: Buffer): Platform {
+    RotateSDK.assertAccountData(data, 'Platform');
+    let offset = 8;
+    
+    const id = data.readUInt32LE(offset);
+    offset += 4;
+    const admin = new PublicKey(data.slice(offset, offset + 32));
+    offset += 32;
+    const wallet = new PublicKey(data.slice(offset, offset + 32));
+    offset += 32;
+    const feeBps = data.readUInt16LE(offset);
+    offset += 2;
+    const active = data.readUInt8(offset) === 1;
+    offset += 1;
+    const bump = data.readUInt8(offset);
+    
+    return { id, admin, wallet, feeBps, active, bump };
+  }
+  
+  private decodeMerchant(data: Buffer): Merchant {
+    RotateSDK.assertAccountData(data, 'Merchant');
+    let offset = 8;
+    
+    const id = data.readUInt32LE(offset);
+    offset += 4;
+    const platformId = data.readUInt32LE(offset);
+    offset += 4;
+    const wallet = new PublicKey(data.slice(offset, offset + 32));
+    offset += 32;
+    const active = data.readUInt8(offset) === 1;
+    offset += 1;
+    const bump = data.readUInt8(offset);
+    
+    return { id, platformId, wallet, active, bump };
+  }
+  
+  private decodePaymentLink(data: Buffer): PaymentLink {
+    RotateSDK.assertAccountData(data, 'PaymentLink');
+    let offset = 8;
+    
+    const id = data.readUInt32LE(offset);
+    offset += 4;
+    const merchantId = data.readUInt32LE(offset);
+    offset += 4;
+    
+    const tokenTypeValue = data.readUInt8(offset);
+    offset += 1;
+    const tokenType = ['Sol', 'Usdc', 'Usdt', 'Usd'][tokenTypeValue] as PaymentLink['tokenType'];
+    
+    const tokenMint = new PublicKey(data.slice(offset, offset + 32));
+    offset += 32;
+    
+    const statusValue = data.readUInt8(offset);
+    offset += 1;
+    const status = ['Pending', 'PartiallyPaid', 'Paid', 'Cancelled'][statusValue] as PaymentLink['status'];
+    
+    const allowTips = data.readUInt8(offset) === 1;
+    offset += 1;
+    const allowPartial = data.readUInt8(offset) === 1;
+    offset += 1;
+    
+    const amount = data.readBigUInt64LE(offset);
+    offset += 8;
+    const amountPaid = data.readBigUInt64LE(offset);
+    offset += 8;
+    const expiresAt = Number(data.readBigInt64LE(offset));
+    offset += 8;
+    const orderRef = data.readBigUInt64LE(offset).toString();
+    offset += 8;
+    const bump = data.readUInt8(offset);
+    
+    return {
+      id,
+      merchantId,
+      tokenType,
+      tokenMint,
+      status,
+      allowTips,
+      allowPartial,
+      amount,
+      amountPaid,
+      expiresAt,
+      orderRef,
+      bump,
+    };
+  }
+
+  // ==================== MEMO / DESCRIPTION ====================
+
+  /**
+   * Recover a payment link description from its on-chain memo.
+   * Returns null if no description was embedded.
+   */
+  async getLinkDescription(linkId: number): Promise<string | null> {
+    return getLinkDescription(this.connection, linkId, this.programId);
+  }
+}
+
+// ==================== EXPORTS ====================
+
+// Re-export store & marketplace classes and types
+export { RotateStore, RotateCart } from './store';
+export type {
+  Currency,
+  Product,
+  ProductInput,
+  LineItem,
+  Discount,
+  DiscountInput,
+  CartTotals,
+  CheckoutResult,
+  BatchLinkResult,
+  StoreConfig,
+} from './store';
+export { RotateMarketplace, MarketplaceCart } from './marketplace';
+export { RotatePlatformManager } from './platform';
+export type {
+  PlatformManagerConfig,
+  OnboardMerchantInput,
+  OnboardMerchantResult,
+  BulkOnboardResult,
+  MerchantInfo,
+  PlatformStats,
+} from './platform';
+export type {
+  Vendor,
+  VendorInput,
+  MarketplaceProduct,
+  MarketplaceProductInput,
+  MarketplaceLineItem,
+  VendorSubtotal,
+  MarketplaceCartTotals,
+  MarketplaceCheckoutResult,
+  MarketplaceConfig,
+} from './marketplace';
+
+export default RotateSDK;
+export { IDL, generateSampleId, isValidId };
+// Note: RotateConfig, Protocol, Platform, Merchant, PaymentLink, MEMO_PROGRAM_ID, MEMO_PREFIX,
+// createMemoInstruction, getLinkDescription, and all param types are already exported
+// at their definition sites (export function / export interface / export type).