@cubee_ee/sdk 0.1.0

package/src/types/tx.ts

@@ -0,0 +1,87 @@
+import { PublicKey, TransactionInstruction } from "@solana/web3.js";
+import BN from "bn.js";
+
+export interface SwapParams {
+  user: PublicKey;
+  tokenInIndex: number;
+  tokenOutIndex: number;
+  amountIn: BN;
+  /** Hundredths-bps; omit to use SDK config default. */
+  slippageHundredthsBps?: number;
+  /** Optional explicit minimum; overrides slippage-derived value. */
+  minAmountOut?: BN;
+}
+
+export interface SwapQuote {
+  tokenInIndex: number;
+  tokenOutIndex: number;
+  amountIn: BN;
+  amountOut: BN;
+  /** Spot-based upper bound on amountOut; useful for price-impact UI. */
+  spotOut: BN;
+  /** Absolute price impact in hundredths of basis point. */
+  priceImpactHbps: number;
+  feeAmount: BN;
+  protocolFeeAmount: BN;
+  /** Minimum amount_out to pass to the swap ix given the quoted slippage. */
+  minAmountOut: BN;
+}
+
+export interface AddLiquidityParams {
+  user: PublicKey;
+  tokenAmounts: BN[];
+  minimumBptAmount?: BN;
+}
+
+export interface RemoveLiquidityParams {
+  user: PublicKey;
+  bptAmount: BN;
+  minimumTokenAmounts?: BN[];
+}
+
+export interface SingleTokenDepositParams {
+  user: PublicKey;
+  tokenInIndex: number;
+  amountIn: BN;
+  slippageHundredthsBps?: number;
+  minimumBptAmount?: BN;
+}
+
+export interface SingleTokenDepositQuote {
+  tokenInIndex: number;
+  amountIn: BN;
+  /** Per-token allocations (sum = amountIn). */
+  allocations: BN[];
+  /** Per-leg expected swap out. `0` for sidelined tokens. */
+  expectedOuts: BN[];
+  /** Per-leg min_out derived from slippage. */
+  minOuts: BN[];
+  /** Amounts the helper will pass to add_liquidity after proportional capping. */
+  depositedAmounts: BN[];
+  /** Helper-held excess returned to the user after add_liquidity. */
+  refundAmounts: BN[];
+  /** Projected BPT to receive (ballpark, pre-CPI). */
+  estimatedBpt: BN;
+  /** Indices of tokens excluded from the deposit (actBal == 0). */
+  sidelinedTokenIndices: number[];
+}
+
+export interface BuiltTx {
+  instructions: TransactionInstruction[];
+  /** Accounts that should sign (user is implicit). */
+  extraSigners?: PublicKey[];
+  /** Suggested CU limit — caller decides whether to prepend ComputeBudget ix. */
+  suggestedCuLimit: number;
+}
+
+export interface DeployPoolParams {
+  payer: PublicKey;
+  configKey: PublicKey;
+  poolId: BN;
+  tokens: PublicKey[];
+  weightsBps: number[];
+  virtualBalances: BN[];
+  swapFeeRate: number;
+  /** SPL Token program to use for the BPT mint (classic SPL Token recommended). */
+  bptTokenProgram?: PublicKey;
+}

package/src/utils/errors.ts

@@ -0,0 +1,78 @@
+import { SdkError, SdkErrorCode } from "../types/result";
+
+const CONTRACT_ERROR_MAP: Record<number, { code: SdkErrorCode; message: string }> = {
+  // cubic-pool error codes (see programs/cubic-pool/src/errors.rs)
+  6000: { code: "invalid_input", message: "Invalid token count" },
+  6001: { code: "invalid_input", message: "Invalid token index" },
+  6002: { code: "invalid_input", message: "Invalid weights — must sum to 10000" },
+  6003: { code: "invalid_input", message: "Invalid virtual balances" },
+  6004: { code: "insufficient_funds", message: "Insufficient pool liquidity" },
+  6005: { code: "slippage_exceeded", message: "Slippage tolerance exceeded" },
+  6006: { code: "invalid_input", message: "Invalid token amounts" },
+  6007: { code: "slippage_exceeded", message: "BPT received is below the minimum requested" },
+  6009: { code: "invalid_input", message: "Swap fee rate exceeds the allowed maximum" },
+  6011: { code: "math_overflow", message: "Math overflow" },
+  6012: { code: "math_overflow", message: "Math underflow" },
+  6022: { code: "pool_disabled", message: "Pool is disabled" },
+  6023: { code: "swaps_disabled", message: "Swaps are disabled on this pool" },
+  6025: { code: "invalid_input", message: "Zero amount" },
+};
+
+/**
+ * Convert a raw error (possibly from Anchor, web3.js, or fetch) into a
+ * cleanly-typed SdkError. Used by safeCall wrappers so callers always
+ * get structured errors, never exceptions.
+ */
+export function toSdkError(cause: unknown): SdkError {
+  // Anchor-encoded program errors
+  const msg = extractMessage(cause);
+  const code = extractErrorCode(msg);
+  if (code !== null && CONTRACT_ERROR_MAP[code]) {
+    return {
+      code: CONTRACT_ERROR_MAP[code].code,
+      humanMessage: CONTRACT_ERROR_MAP[code].message,
+      cause,
+    };
+  }
+  // Common network strings
+  if (/timed? ?out|ETIMEDOUT/i.test(msg)) {
+    return { code: "rpc_timeout", humanMessage: "RPC timed out", cause };
+  }
+  if (/429|rate limit/i.test(msg)) {
+    return { code: "rpc_rate_limited", humanMessage: "RPC rate-limited — slow down", cause };
+  }
+  if (/fetch failed|ECONNREFUSED|ENOTFOUND/i.test(msg)) {
+    return { code: "rpc_unavailable", humanMessage: "RPC endpoint unreachable", cause };
+  }
+  if (/Account does not exist|account not found/i.test(msg)) {
+    return { code: "account_not_found", humanMessage: "Account does not exist on-chain", cause };
+  }
+  if (/insufficient funds/i.test(msg)) {
+    return { code: "insufficient_funds", humanMessage: "Insufficient funds for this operation", cause };
+  }
+  return { code: "unknown", humanMessage: msg || "Unknown error", cause };
+}
+
+function extractMessage(e: unknown): string {
+  if (!e) return "";
+  if (typeof e === "string") return e;
+  if (e instanceof Error) return e.message;
+  if (typeof e === "object" && e !== null && "message" in e) {
+    return String((e as { message?: string }).message ?? "");
+  }
+  try {
+    return JSON.stringify(e);
+  } catch {
+    return String(e);
+  }
+}
+
+function extractErrorCode(msg: string): number | null {
+  // Anchor error format: "custom program error: 0x1774"
+  const hex = msg.match(/custom program error: 0x([0-9a-fA-F]+)/);
+  if (hex) return parseInt(hex[1], 16);
+  // Anchor SDK format: "Error Number: 6007"
+  const dec = msg.match(/Error Number:\s*(\d+)/);
+  if (dec) return parseInt(dec[1], 10);
+  return null;
+}

package/src/utils/index.ts

@@ -0,0 +1,3 @@
+export * from "./errors";
+export * from "./retry";
+export * from "./pda";

package/src/utils/pda.ts

@@ -0,0 +1,58 @@
+import { PublicKey } from "@solana/web3.js";
+import BN from "bn.js";
+import { ASSOCIATED_TOKEN_PROGRAM_ID } from "@solana/spl-token";
+import {
+  BPT_MINT_SEED,
+  CUBIC_POOL_SEED,
+  STLD_HELPER_SEED,
+  TREASURY_SEED,
+} from "../config";
+
+export function derivePoolPda(
+  programId: PublicKey,
+  config: PublicKey,
+  poolId: BN
+): [PublicKey, number] {
+  return PublicKey.findProgramAddressSync(
+    [CUBIC_POOL_SEED, config.toBuffer(), poolId.toArrayLike(Buffer, "le", 8)],
+    programId
+  );
+}
+
+export function deriveBptMint(
+  cubicPoolProgramId: PublicKey,
+  pool: PublicKey
+): [PublicKey, number] {
+  return PublicKey.findProgramAddressSync(
+    [BPT_MINT_SEED, pool.toBuffer()],
+    cubicPoolProgramId
+  );
+}
+
+export function deriveHelperPda(
+  stldProgramId: PublicKey,
+  pool: PublicKey
+): [PublicKey, number] {
+  return PublicKey.findProgramAddressSync(
+    [STLD_HELPER_SEED, pool.toBuffer()],
+    stldProgramId
+  );
+}
+
+export function deriveTreasuryPda(
+  protocolFeesProgramId: PublicKey
+): [PublicKey, number] {
+  return PublicKey.findProgramAddressSync([TREASURY_SEED], protocolFeesProgramId);
+}
+
+export function deriveAta(
+  owner: PublicKey,
+  mint: PublicKey,
+  tokenProgram: PublicKey
+): PublicKey {
+  const [ata] = PublicKey.findProgramAddressSync(
+    [owner.toBuffer(), tokenProgram.toBuffer(), mint.toBuffer()],
+    ASSOCIATED_TOKEN_PROGRAM_ID
+  );
+  return ata;
+}

package/src/utils/retry.ts

@@ -0,0 +1,85 @@
+import { SdkResult, err, ok } from "../types/result";
+import { toSdkError } from "./errors";
+
+export interface RetryOptions {
+  /** Number of attempts total (1 = no retry). */
+  attempts?: number;
+  /** Per-attempt timeout (ms). */
+  timeoutMs?: number;
+  /** Backoff schedule (ms) between attempts. */
+  backoffMs?: number[];
+  /** Additional predicate: return `false` to stop retrying early. */
+  shouldRetry?: (error: unknown) => boolean;
+}
+
+const DEFAULT_BACKOFF_MS = [200, 500, 1500];
+
+/**
+ * Retry-wrapped helper. Returns a SdkResult<T>. Never throws. Use for any
+ * I/O: RPC calls, backend fetches, CPI simulations.
+ *
+ * ```ts
+ * const res = await safeCall(() => connection.getAccountInfo(pk), { attempts: 3 });
+ * if (!res.ok) showToast(res.error.humanMessage);
+ * ```
+ */
+export async function safeCall<T>(
+  operation: () => Promise<T>,
+  opts: RetryOptions = {}
+): Promise<SdkResult<T>> {
+  const attempts = opts.attempts ?? 3;
+  const backoff = opts.backoffMs ?? DEFAULT_BACKOFF_MS;
+  const timeoutMs = opts.timeoutMs ?? 15_000;
+  const shouldRetry = opts.shouldRetry ?? defaultShouldRetry;
+
+  let lastError: unknown;
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    try {
+      const raced = await withTimeout(operation(), timeoutMs);
+      return ok(raced);
+    } catch (e) {
+      lastError = e;
+      if (!shouldRetry(e)) break;
+      if (attempt < attempts - 1) {
+        const delayIdx = Math.min(attempt, backoff.length - 1);
+        await sleep(backoff[delayIdx]);
+      }
+    }
+  }
+  return err(
+    toSdkError(lastError).code,
+    toSdkError(lastError).humanMessage,
+    lastError
+  );
+}
+
+function defaultShouldRetry(e: unknown): boolean {
+  const err = toSdkError(e);
+  // Retry on transient network / rate-limit errors, stop on structural ones.
+  return (
+    err.code === "rpc_timeout" ||
+    err.code === "rpc_unavailable" ||
+    err.code === "rpc_rate_limited" ||
+    err.code === "backend_unavailable"
+  );
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+function withTimeout<T>(p: Promise<T>, ms: number): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const h = setTimeout(() => reject(new Error(`timed out after ${ms}ms`)), ms);
+    p.then(
+      (v) => {
+        clearTimeout(h);
+        resolve(v);
+      },
+      (e) => {
+        clearTimeout(h);
+        reject(e);
+      }
+    );
+  });
+}