@cubee_ee/sdk 0.1.0

package/src/math/weightedMath.ts

@@ -0,0 +1,48 @@
+import { MAX_WEIGHT, MIN_WEIGHT, WEIGHT_SCALE } from "../config";
+
+/**
+ * Validate a weight vector. Must sum exactly to 10_000 (WEIGHT_SCALE) and
+ * every entry must be in [MIN_WEIGHT, MAX_WEIGHT].
+ */
+export function validateWeights(weights: number[]): void {
+  if (!Array.isArray(weights) || weights.length < 2) {
+    throw new Error("weightedMath: at least 2 weights required");
+  }
+  let sum = 0;
+  for (const w of weights) {
+    if (!Number.isInteger(w)) {
+      throw new Error("weightedMath: weights must be integers (bps)");
+    }
+    if (w < MIN_WEIGHT || w > MAX_WEIGHT) {
+      throw new Error(`weightedMath: weight ${w} out of [${MIN_WEIGHT}, ${MAX_WEIGHT}]`);
+    }
+    sum += w;
+  }
+  if (sum !== WEIGHT_SCALE) {
+    throw new Error(`weightedMath: weights sum to ${sum}, expected ${WEIGHT_SCALE}`);
+  }
+}
+
+/**
+ * Weighted spot price of token_out priced in token_in, normalised to 18
+ * decimals. Used only for display; on-chain quoting uses calcOutGivenIn.
+ */
+export function calcSpotPrice(params: {
+  balanceIn: bigint;
+  weightInBps: bigint;
+  balanceOut: bigint;
+  weightOutBps: bigint;
+  decimalsIn: number;
+  decimalsOut: number;
+}): bigint {
+  const { balanceIn, weightInBps, balanceOut, weightOutBps, decimalsIn, decimalsOut } = params;
+  const scaleIn = 10n ** BigInt(18 - decimalsIn);
+  const scaleOut = 10n ** BigInt(18 - decimalsOut);
+  const bI = balanceIn * scaleIn;
+  const bO = balanceOut * scaleOut;
+  if (bO === 0n || weightOutBps === 0n) return 0n;
+  // price = (bI / wI) / (bO / wO)
+  const numer = bI * weightOutBps * 10n ** 18n;
+  const denom = bO * weightInBps;
+  return numer / denom;
+}

package/src/parsers/borsh.ts

@@ -0,0 +1,80 @@
+import BN from "bn.js";
+import { PublicKey } from "@solana/web3.js";
+
+/**
+ * Minimal Borsh-compatible reader. Enough to decode the Cube contract
+ * event structs (Pubkey × N, u8/u16/u32/u64/i64, bool, Vec<u64>,
+ * Vec<Pubkey>). Avoids pulling a borsh dep into the SDK's hot path.
+ */
+export class BorshReader {
+  private offset = 0;
+  constructor(private readonly buf: Buffer) {}
+
+  remaining(): number {
+    return this.buf.length - this.offset;
+  }
+
+  skip(n: number): void {
+    this.offset += n;
+  }
+
+  u8(): number {
+    const v = this.buf.readUInt8(this.offset);
+    this.offset += 1;
+    return v;
+  }
+
+  u16(): number {
+    const v = this.buf.readUInt16LE(this.offset);
+    this.offset += 2;
+    return v;
+  }
+
+  u32(): number {
+    const v = this.buf.readUInt32LE(this.offset);
+    this.offset += 4;
+    return v;
+  }
+
+  u64(): BN {
+    const slice = this.buf.slice(this.offset, this.offset + 8);
+    this.offset += 8;
+    return new BN(slice, "le");
+  }
+
+  i64(): BN {
+    const slice = this.buf.slice(this.offset, this.offset + 8);
+    this.offset += 8;
+    // i64 is two's complement little-endian — treat as signed.
+    const bn = new BN(slice, "le");
+    if (slice[7] & 0x80) {
+      // top bit set → negative: subtract 2^64
+      return bn.sub(new BN(2).pow(new BN(64)));
+    }
+    return bn;
+  }
+
+  bool(): boolean {
+    return this.u8() !== 0;
+  }
+
+  pubkey(): PublicKey {
+    const slice = this.buf.slice(this.offset, this.offset + 32);
+    this.offset += 32;
+    return new PublicKey(slice);
+  }
+
+  vecU64(): BN[] {
+    const len = this.u32();
+    const out: BN[] = [];
+    for (let i = 0; i < len; i++) out.push(this.u64());
+    return out;
+  }
+
+  vecPubkey(): PublicKey[] {
+    const len = this.u32();
+    const out: PublicKey[] = [];
+    for (let i = 0; i < len; i++) out.push(this.pubkey());
+    return out;
+  }
+}

package/src/parsers/events.ts

@@ -0,0 +1,172 @@
+import { PublicKey } from "@solana/web3.js";
+import { BorshReader } from "./borsh";
+import { CubicPoolEvent } from "../types/events";
+
+/**
+ * Anchor event log format (base64-encoded after `Program data:`):
+ *   [ 8-byte discriminator | borsh-encoded event struct ]
+ *
+ * Discriminators for cubic-pool and single-token-liquidity are hard-coded
+ * here from the generated IDL. Never guess from event name — the Anchor
+ * macro actually uses `sha256("event:<Name>")[0..8]`, but for robustness
+ * we pin the bytes.
+ */
+
+// Cubic-pool event discriminators (from target/idl/cubic_pool.json):
+const DISC = {
+  PoolInitialized:          Buffer.from([100, 118, 173, 87, 12, 198, 254, 229]),
+  Swap:                     Buffer.from([81, 108, 227, 190, 205, 208, 10, 196]),
+  LiquidityAdded:           Buffer.from([154, 26, 221, 108, 238, 64, 217, 161]),
+  LiquidityRemoved:         Buffer.from([225, 105, 216, 39, 124, 116, 169, 189]),
+  ProtocolFeesCollected:    Buffer.from([165, 34, 125, 155, 15, 86, 99, 191]),
+  SwapFeeRateUpdated:       Buffer.from([101, 132, 24, 255, 91, 253, 227, 101]),
+  ProtocolFeeRateUpdated:   Buffer.from([189, 56, 7, 65, 0, 95, 192, 6]),
+  PoolEnabledUpdated:       Buffer.from([101, 47, 3, 240, 197, 181, 236, 142]),
+  SwapsEnabledUpdated:      Buffer.from([55, 116, 118, 138, 102, 26, 227, 223]),
+  DebugLiquidityWithdrawn:  Buffer.from([174, 59, 149, 22, 135, 129, 129, 83]),
+  PoolStateLog:             Buffer.from([59, 254, 237, 111, 163, 10, 140, 224]),
+  PoolInfo:                 Buffer.from([207, 20, 87, 97, 251, 212, 234, 45]),
+  BannedExtensionsUpdated:  Buffer.from([107, 126, 13, 149, 182, 108, 139, 202]),
+  // Stld:
+  SingleTokenDeposit:       Buffer.from([215, 54, 137, 104, 219, 39, 164, 235]),
+};
+
+type DiscName = keyof typeof DISC;
+
+export function parseCubicPoolEvents(logs: string[]): CubicPoolEvent[] {
+  const out: CubicPoolEvent[] = [];
+  for (const line of logs) {
+    const m = line.match(/^Program data:\s+(.+)$/);
+    if (!m) continue;
+    const buf = Buffer.from(m[1], "base64");
+    if (buf.length < 8) continue;
+    const disc = buf.slice(0, 8);
+    const payload = buf.slice(8);
+    const name = matchDiscriminator(disc);
+    if (!name) {
+      out.push({ kind: "Unknown", name: "unknown", data: { disc: disc.toString("base64"), payload: payload.toString("base64") } });
+      continue;
+    }
+    try {
+      const ev = decodeEvent(name, payload);
+      if (ev) out.push(ev);
+    } catch (e) {
+      out.push({
+        kind: "Unknown",
+        name,
+        data: { error: String(e), payload: payload.toString("base64") },
+      });
+    }
+  }
+  return out;
+}
+
+function matchDiscriminator(d: Buffer): DiscName | null {
+  for (const [name, bytes] of Object.entries(DISC)) {
+    if (bytes.equals(d)) return name as DiscName;
+  }
+  return null;
+}
+
+function decodeEvent(name: DiscName, buf: Buffer): CubicPoolEvent | null {
+  const r = new BorshReader(buf);
+  switch (name) {
+    case "Swap": {
+      const pool = r.pubkey();
+      const user = r.pubkey();
+      const tokenIn = r.pubkey();
+      const tokenOut = r.pubkey();
+      const amountIn = r.u64();
+      const amountOut = r.u64();
+      const feeAmount = r.u64();
+      const protocolFeeAmount = r.u64();
+      const timestamp = r.i64().toNumber();
+      return { kind: "Swap", pool, user, tokenIn, tokenOut, amountIn, amountOut, feeAmount, protocolFeeAmount, timestamp };
+    }
+    case "LiquidityAdded": {
+      const pool = r.pubkey();
+      const user = r.pubkey();
+      const tokenAmounts = r.vecU64();
+      const bptAmount = r.u64();
+      const timestamp = r.i64().toNumber();
+      return { kind: "LiquidityAdded", pool, user, tokenAmounts, bptAmount, timestamp };
+    }
+    case "LiquidityRemoved": {
+      const pool = r.pubkey();
+      const user = r.pubkey();
+      const bptAmount = r.u64();
+      const tokenAmounts = r.vecU64();
+      const timestamp = r.i64().toNumber();
+      return { kind: "LiquidityRemoved", pool, user, bptAmount, tokenAmounts, timestamp };
+    }
+    case "ProtocolFeesCollected": {
+      const pool = r.pubkey();
+      const authority = r.pubkey();
+      const tokenAmounts = r.vecU64();
+      const timestamp = r.i64().toNumber();
+      return { kind: "ProtocolFeesCollected", pool, authority, tokenAmounts, timestamp };
+    }
+    case "PoolInitialized": {
+      const pool = r.pubkey();
+      const config = r.pubkey();
+      const tokenCount = r.u8();
+      const bptMint = r.pubkey();
+      const timestamp = r.i64().toNumber();
+      return { kind: "PoolInitialized", pool, config, tokenCount, bptMint, timestamp };
+    }
+    case "PoolEnabledUpdated": {
+      const pool = r.pubkey();
+      const authority = r.pubkey();
+      const oldValue = r.bool();
+      const newValue = r.bool();
+      const timestamp = r.i64().toNumber();
+      return { kind: "PoolEnabledUpdated", pool, authority, oldValue, newValue, timestamp };
+    }
+    case "SwapsEnabledUpdated": {
+      const pool = r.pubkey();
+      const authority = r.pubkey();
+      const oldValue = r.bool();
+      const newValue = r.bool();
+      const timestamp = r.i64().toNumber();
+      return { kind: "SwapsEnabledUpdated", pool, authority, oldValue, newValue, timestamp };
+    }
+    case "SingleTokenDeposit": {
+      const helper = r.pubkey();
+      const pool = r.pubkey();
+      const user = r.pubkey();
+      const tokenInIndex = r.u8();
+      const amountIn = r.u64();
+      const slippageHundredthsBps = r.u32();
+      const allocations = r.vecU64();
+      const depositedAmounts = r.vecU64();
+      const bptReceived = r.u64();
+      const dustRefunded = r.u64();
+      const timestamp = r.i64().toNumber();
+      return {
+        kind: "SingleTokenDeposit",
+        helper,
+        pool,
+        user,
+        tokenInIndex,
+        amountIn,
+        slippageHundredthsBps,
+        allocations,
+        depositedAmounts,
+        bptReceived,
+        dustRefunded,
+        timestamp,
+      };
+    }
+    // Events we don't yet surface as typed — decode as Unknown so the
+    // caller gets the discriminator name and can act on it.
+    case "SwapFeeRateUpdated":
+    case "ProtocolFeeRateUpdated":
+    case "BannedExtensionsUpdated":
+    case "DebugLiquidityWithdrawn":
+    case "PoolStateLog":
+    case "PoolInfo":
+      return { kind: "Unknown", name, data: { raw: buf.toString("base64") } };
+  }
+}
+
+void PublicKey; // keep import used by types above via type inference

package/src/parsers/index.ts

@@ -0,0 +1,4 @@
+export * from "./poolAccount";
+export * from "./mintAccount";
+export * from "./events";
+export * from "./borsh";

package/src/parsers/mintAccount.ts

@@ -0,0 +1,37 @@
+import { PublicKey } from "@solana/web3.js";
+import BN from "bn.js";
+
+/**
+ * SPL Token (or Token-2022) Mint parser. Reads the first 82 bytes; ignores
+ * Token-2022 extensions (we don't need them for BPT metadata).
+ *
+ * Layout:
+ *   0..36  COption<Pubkey>  mintAuthority  (4 bytes tag + 32 bytes pubkey)
+ *   36..44 u64              supply
+ *   44..45 u8               decimals
+ *   45..46 u8               isInitialized
+ *   46..82 COption<Pubkey>  freezeAuthority
+ */
+export interface RawMintAccount {
+  mintAuthority: PublicKey | null;
+  supply: BN;
+  decimals: number;
+  isInitialized: boolean;
+  freezeAuthority: PublicKey | null;
+}
+
+export function decodeMintAccount(data: Buffer): RawMintAccount {
+  if (data.length < 82) {
+    throw new Error(`decodeMintAccount: data too short (${data.length})`);
+  }
+  const mintAuthTag = data.readUInt32LE(0);
+  const mintAuthority =
+    mintAuthTag === 0 ? null : new PublicKey(data.slice(4, 36));
+  const supply = new BN(data.slice(36, 44), "le");
+  const decimals = data.readUInt8(44);
+  const isInitialized = data.readUInt8(45) !== 0;
+  const freezeTag = data.readUInt32LE(46);
+  const freezeAuthority =
+    freezeTag === 0 ? null : new PublicKey(data.slice(50, 82));
+  return { mintAuthority, supply, decimals, isInitialized, freezeAuthority };
+}

package/src/parsers/poolAccount.ts

@@ -0,0 +1,113 @@
+import { PublicKey } from "@solana/web3.js";
+import BN from "bn.js";
+
+/**
+ * Raw binary layout of CubicPool (see
+ * `contracts/programs/cubic-pool/src/state/cubic_pool.rs`). Borsh-serialised.
+ *
+ * We decode manually to avoid bundling an Anchor Program instance into the
+ * SDK: the SDK is consumed by both frontend and backend, where dragging a
+ * full Anchor runtime is heavy. The on-chain layout is stable (reserved[128]
+ * at the tail).
+ */
+export interface RawPoolAccount {
+  config: PublicKey;
+  bump: number;
+  tokenCount: number;
+  poolId: BN;
+  tokenMints: PublicKey[]; // length 10
+  tokenPrograms: PublicKey[]; // length 10
+  normalizedWeights: BN[]; // length 10
+  virtualBalances: BN[]; // length 10
+  actualBalances: BN[]; // length 10
+  swapFeeRate: number;
+  protocolFeeRate: number;
+  protocolFeesOwed: BN[]; // length 10
+  createdAt: BN;
+  poolEnabled: boolean;
+  swapsEnabled: boolean;
+}
+
+/** 8-byte anchor discriminator for CubicPool. */
+export const POOL_DISCRIMINATOR_LEN = 8;
+const MAX_TOKENS = 10;
+
+export function decodePoolAccount(data: Buffer): RawPoolAccount {
+  if (data.length < POOL_DISCRIMINATOR_LEN + 1000) {
+    throw new Error(`decodePoolAccount: data too short (${data.length} bytes)`);
+  }
+  let off = POOL_DISCRIMINATOR_LEN;
+
+  const config = new PublicKey(data.slice(off, off + 32));
+  off += 32;
+  const bump = data.readUInt8(off);
+  off += 1;
+  const tokenCount = data.readUInt8(off);
+  off += 1;
+  const poolId = readU64LE(data, off);
+  off += 8;
+
+  const tokenMints: PublicKey[] = [];
+  for (let i = 0; i < MAX_TOKENS; i++) {
+    tokenMints.push(new PublicKey(data.slice(off, off + 32)));
+    off += 32;
+  }
+  const tokenPrograms: PublicKey[] = [];
+  for (let i = 0; i < MAX_TOKENS; i++) {
+    tokenPrograms.push(new PublicKey(data.slice(off, off + 32)));
+    off += 32;
+  }
+  const normalizedWeights: BN[] = [];
+  for (let i = 0; i < MAX_TOKENS; i++) {
+    normalizedWeights.push(readU64LE(data, off));
+    off += 8;
+  }
+  const virtualBalances: BN[] = [];
+  for (let i = 0; i < MAX_TOKENS; i++) {
+    virtualBalances.push(readU64LE(data, off));
+    off += 8;
+  }
+  const actualBalances: BN[] = [];
+  for (let i = 0; i < MAX_TOKENS; i++) {
+    actualBalances.push(readU64LE(data, off));
+    off += 8;
+  }
+  const swapFeeRate = data.readUInt32LE(off);
+  off += 4;
+  const protocolFeeRate = data.readUInt16LE(off);
+  off += 2;
+  const protocolFeesOwed: BN[] = [];
+  for (let i = 0; i < MAX_TOKENS; i++) {
+    protocolFeesOwed.push(readU64LE(data, off));
+    off += 8;
+  }
+  const createdAt = readU64LE(data, off); // i64 — but Solana ts ≥ 0
+  off += 8;
+  const poolEnabled = data.readUInt8(off) !== 0;
+  off += 1;
+  const swapsEnabled = data.readUInt8(off) !== 0;
+  off += 1;
+  // reserved[128] trails — ignored.
+
+  return {
+    config,
+    bump,
+    tokenCount,
+    poolId,
+    tokenMints,
+    tokenPrograms,
+    normalizedWeights,
+    virtualBalances,
+    actualBalances,
+    swapFeeRate,
+    protocolFeeRate,
+    protocolFeesOwed,
+    createdAt,
+    poolEnabled,
+    swapsEnabled,
+  };
+}
+
+function readU64LE(data: Buffer, off: number): BN {
+  return new BN(data.slice(off, off + 8), "le");
+}

package/src/types/events.ts

@@ -0,0 +1,100 @@
+import { PublicKey } from "@solana/web3.js";
+import BN from "bn.js";
+
+export type CubicPoolEvent =
+  | PoolInitializedEvent
+  | SwapEvent
+  | LiquidityAddedEvent
+  | LiquidityRemovedEvent
+  | ProtocolFeesCollectedEvent
+  | PoolEnabledUpdatedEvent
+  | SwapsEnabledUpdatedEvent
+  | SingleTokenDepositEvent
+  | UnknownEvent;
+
+export interface PoolInitializedEvent {
+  kind: "PoolInitialized";
+  pool: PublicKey;
+  config: PublicKey;
+  tokenCount: number;
+  bptMint: PublicKey;
+  timestamp: number;
+}
+
+export interface SwapEvent {
+  kind: "Swap";
+  pool: PublicKey;
+  user: PublicKey;
+  tokenIn: PublicKey;
+  tokenOut: PublicKey;
+  amountIn: BN;
+  amountOut: BN;
+  feeAmount: BN;
+  protocolFeeAmount: BN;
+  timestamp: number;
+}
+
+export interface LiquidityAddedEvent {
+  kind: "LiquidityAdded";
+  pool: PublicKey;
+  user: PublicKey;
+  tokenAmounts: BN[];
+  bptAmount: BN;
+  timestamp: number;
+}
+
+export interface LiquidityRemovedEvent {
+  kind: "LiquidityRemoved";
+  pool: PublicKey;
+  user: PublicKey;
+  bptAmount: BN;
+  tokenAmounts: BN[];
+  timestamp: number;
+}
+
+export interface ProtocolFeesCollectedEvent {
+  kind: "ProtocolFeesCollected";
+  pool: PublicKey;
+  authority: PublicKey;
+  tokenAmounts: BN[];
+  timestamp: number;
+}
+
+export interface PoolEnabledUpdatedEvent {
+  kind: "PoolEnabledUpdated";
+  pool: PublicKey;
+  authority: PublicKey;
+  oldValue: boolean;
+  newValue: boolean;
+  timestamp: number;
+}
+
+export interface SwapsEnabledUpdatedEvent {
+  kind: "SwapsEnabledUpdated";
+  pool: PublicKey;
+  authority: PublicKey;
+  oldValue: boolean;
+  newValue: boolean;
+  timestamp: number;
+}
+
+export interface SingleTokenDepositEvent {
+  kind: "SingleTokenDeposit";
+  helper: PublicKey;
+  pool: PublicKey;
+  user: PublicKey;
+  tokenInIndex: number;
+  amountIn: BN;
+  slippageHundredthsBps: number;
+  allocations: BN[];
+  depositedAmounts: BN[];
+  bptReceived: BN;
+  dustRefunded: BN;
+  timestamp: number;
+}
+
+export interface UnknownEvent {
+  kind: "Unknown";
+  name: string;
+  data: Record<string, unknown>;
+}

package/src/types/index.ts

@@ -0,0 +1,4 @@
+export * from "./result";
+export * from "./pool";
+export * from "./tx";
+export * from "./events";

package/src/types/pool.ts

@@ -0,0 +1,64 @@
+import { PublicKey } from "@solana/web3.js";
+import BN from "bn.js";
+import { TokenInfo } from "../config/tokens";
+
+/**
+ * A single token slot inside a Cubic Pool, enriched with off-chain metadata
+ * (ticker, logo, coingeckoId) when available.
+ */
+export interface PoolTokenInfo {
+  index: number;
+  mint: PublicKey;
+  tokenProgram: PublicKey;
+  decimals: number;
+  /** Basis points, sum across all tokens == 10_000. */
+  weightBps: number;
+  /** In native token units (u64). */
+  virtualBalance: BN;
+  actualBalance: BN;
+  protocolFeesOwed: BN;
+  /** PDA: ATA(pool, mint, tokenProgram). */
+  vault: PublicKey;
+  /** Cached off-chain metadata; `undefined` if no registry hit. */
+  metadata?: TokenInfo;
+  /** factBalance / virtBalance as a float, for display/math. */
+  concentration: number;
+}
+
+/**
+ * Fully parsed pool state. Returned by `CubicPoolClient.sync()`.
+ * All raw on-chain numerics plus a few convenience derivations.
+ */
+export interface PoolInfo {
+  /** Pool PDA address. */
+  address: PublicKey;
+  /** Pool config account referenced by the pool. */
+  config: PublicKey;
+  /** `Account<CubicPool>.bump`. */
+  bump: number;
+  /** Integer identifier salt. Pools under the same config differ by pool_id. */
+  poolId: BN;
+  tokenCount: number;
+  tokens: PoolTokenInfo[];
+  bptMint: PublicKey;
+  /** Total supply of BPT tokens at snapshot time. */
+  bptTotalSupply: BN;
+  /** Hundredths-of-basis-point units (1_000_000 == 100 %). */
+  swapFeeRate: number;
+  /** Basis points (10_000 == 100 %). */
+  protocolFeeRate: number;
+  poolEnabled: boolean;
+  swapsEnabled: boolean;
+  createdAt: number;
+  /** Unix timestamp (ms) when sync() ran. Useful for staleness checks. */
+  syncedAt: number;
+}
+
+export interface PoolSummary {
+  address: string;
+  tvlUsd?: number;
+  volume24hUsd?: number;
+  feeApr7d?: number;
+  poolEnabled: boolean;
+  tokens: Array<{ mint: string; symbol?: string; weightBps: number }>;
+}

package/src/types/result.ts

@@ -0,0 +1,45 @@
+/**
+ * Every public SDK method returns a SdkResult<T>. Callers never need try/catch.
+ * Use `if (res.ok) { ... } else { ... }` to branch.
+ */
+export type SdkResult<T> =
+  | { ok: true; data: T }
+  | { ok: false; error: SdkError };
+
+export interface SdkError {
+  /** Stable machine-readable code. */
+  code: SdkErrorCode;
+  /** Human-readable message, safe to show to end users. */
+  humanMessage: string;
+  /** Original error for debugging; never render this to end users. */
+  cause?: unknown;
+}
+
+export type SdkErrorCode =
+  | "rpc_unavailable"
+  | "rpc_timeout"
+  | "rpc_rate_limited"
+  | "account_not_found"
+  | "invalid_input"
+  | "math_overflow"
+  | "parse_failure"
+  | "backend_unavailable"
+  | "backend_invalid_response"
+  | "insufficient_funds"
+  | "pool_disabled"
+  | "swaps_disabled"
+  | "unsupported_pool_state"
+  | "slippage_exceeded"
+  | "simulation_failed"
+  | "tx_build_failed"
+  | "unknown";
+
+export const ok = <T>(data: T): SdkResult<T> => ({ ok: true, data });
+export const err = (
+  code: SdkErrorCode,
+  humanMessage: string,
+  cause?: unknown
+): SdkResult<never> => ({
+  ok: false,
+  error: { code, humanMessage, cause },
+});