@cubee_ee/sdk 0.1.0

package/src/clients/PoolFactoryClient.ts

@@ -0,0 +1,102 @@
+import { ComputeBudgetProgram, Keypair, PublicKey, TransactionInstruction } from "@solana/web3.js";
+import BN from "bn.js";
+import { CubeConfig } from "../config";
+import { SdkResult, err, ok } from "../types/result";
+import { BuiltTx, DeployPoolParams } from "../types/tx";
+import {
+  buildDeployPoolTx,
+  buildInitializeCubicPoolIx,
+  buildInitializeConfigIx,
+} from "./tx-builders";
+import { derivePoolPda } from "../utils/pda";
+
+export interface PoolFactoryClientParams {
+  config: CubeConfig;
+}
+
+export interface InitializeConfigParams {
+  payer: PublicKey;
+  defaultProtocolFeeRate: number;
+}
+
+/**
+ * Builds transactions for protocol governance / pool deployment. Consumed
+ * by the deploy-pool UI flow and by the backend's admin tools.
+ */
+export class PoolFactoryClient {
+  readonly config: CubeConfig;
+
+  constructor(params: PoolFactoryClientParams) {
+    this.config = params.config;
+  }
+
+  /**
+   * Deploy a new pool atop an existing `CubicPoolConfig`. Caller is
+   * responsible for funding `params.payer` with enough SOL to cover rent
+   * for the pool account and the BPT mint PDA.
+   *
+   * Returns the `pool` and `bptMint` pubkeys it WILL create (derived PDAs)
+   * plus the signable tx.
+   */
+  buildDeployPoolTx(params: DeployPoolParams): SdkResult<BuiltTx & { pool: PublicKey; bptMint: PublicKey }> {
+    if (params.tokens.length < 2 || params.tokens.length > 10) {
+      return err("invalid_input", "tokens.length must be in [2, 10]");
+    }
+    if (params.tokens.length !== params.weightsBps.length) {
+      return err("invalid_input", "tokens/weightsBps length mismatch");
+    }
+    if (params.tokens.length !== params.virtualBalances.length) {
+      return err("invalid_input", "tokens/virtualBalances length mismatch");
+    }
+    const sum = params.weightsBps.reduce((a, b) => a + b, 0);
+    if (sum !== 10_000) return err("invalid_input", `weights must sum to 10000 (got ${sum})`);
+    for (const vb of params.virtualBalances) {
+      if (vb.isZero()) return err("invalid_input", "virtualBalances must all be > 0");
+    }
+
+    const [pool] = derivePoolPda(this.config.programs.cubicPool, params.configKey, params.poolId);
+    const [bptMint] = PublicKey.findProgramAddressSync(
+      [Buffer.from("bpt_mint"), pool.toBuffer()],
+      this.config.programs.cubicPool
+    );
+    try {
+      const tx = buildDeployPoolTx(this.config, params);
+      return ok({ ...tx, pool, bptMint });
+    } catch (e) {
+      return err("tx_build_failed", "Failed to build deploy-pool tx", e);
+    }
+  }
+
+  /**
+   * Initialize a new CubicPoolConfig. The `config` signer must be freshly
+   * generated and paired with its keypair when signing the outer tx.
+   * Returns the tx + the config keypair the caller should sign with.
+   */
+  buildInitializeConfigTx(params: InitializeConfigParams): SdkResult<
+    BuiltTx & { configKeypair: Keypair }
+  > {
+    try {
+      const configKeypair = Keypair.generate();
+      const ix = buildInitializeConfigIx(this.config, {
+        config: configKeypair.publicKey,
+        payer: params.payer,
+        defaultProtocolFeeRate: params.defaultProtocolFeeRate,
+      });
+      return ok({
+        instructions: [ComputeBudgetProgram.setComputeUnitLimit({ units: 200_000 }), ix],
+        suggestedCuLimit: 200_000,
+        configKeypair,
+      });
+    } catch (e) {
+      return err("tx_build_failed", "Failed to build initialize_config tx", e);
+    }
+  }
+
+  /**
+   * Low-level: return the raw `initialize_cubic_pool` ix without a CU
+   * budget or wrapping. Useful for combining with other ixs in the same tx.
+   */
+  initializeCubicPoolIx(params: DeployPoolParams): TransactionInstruction {
+    return buildInitializeCubicPoolIx(this.config, params);
+  }
+}

package/src/clients/RpcClient.ts

@@ -0,0 +1,78 @@
+import { Commitment, Connection, PublicKey } from "@solana/web3.js";
+import { SdkResult } from "../types/result";
+import { safeCall, RetryOptions } from "../utils/retry";
+
+export interface RpcClientParams {
+  endpoint: string;
+  apiKey?: string;
+  commitment?: Commitment;
+  /** Optional headers (e.g. for Helius/Triton auth). */
+  headers?: Record<string, string>;
+}
+
+/**
+ * Thin wrapper around `@solana/web3.js` Connection with built-in retry +
+ * human-readable error mapping. Every public method returns a SdkResult<T>.
+ */
+export class RpcClient {
+  readonly connection: Connection;
+  private readonly defaultCommitment: Commitment;
+
+  constructor(params: RpcClientParams) {
+    const endpoint = params.apiKey
+      ? appendApiKey(params.endpoint, params.apiKey)
+      : params.endpoint;
+    this.defaultCommitment = params.commitment ?? "confirmed";
+    this.connection = new Connection(endpoint, {
+      commitment: this.defaultCommitment,
+      httpHeaders: params.headers,
+    });
+  }
+
+  call<T>(
+    fn: (conn: Connection) => Promise<T>,
+    retry: RetryOptions = {}
+  ): Promise<SdkResult<T>> {
+    return safeCall(() => fn(this.connection), retry);
+  }
+
+  getAccountInfo(
+    pk: PublicKey,
+    retry: RetryOptions = {}
+  ): Promise<SdkResult<{ data: Buffer; owner: PublicKey; lamports: number } | null>> {
+    return safeCall(async () => {
+      const info = await this.connection.getAccountInfo(pk, this.defaultCommitment);
+      if (!info) return null;
+      return {
+        data: info.data,
+        owner: info.owner,
+        lamports: info.lamports,
+      };
+    }, retry);
+  }
+
+  getMultipleAccountsInfo(
+    pks: PublicKey[],
+    retry: RetryOptions = {}
+  ): Promise<SdkResult<(Buffer | null)[]>> {
+    return safeCall(async () => {
+      const infos = await this.connection.getMultipleAccountsInfo(pks, this.defaultCommitment);
+      return infos.map((i) => (i ? i.data : null));
+    }, retry);
+  }
+
+  getSlot(retry: RetryOptions = {}): Promise<SdkResult<number>> {
+    return safeCall(() => this.connection.getSlot(this.defaultCommitment), retry);
+  }
+}
+
+function appendApiKey(endpoint: string, apiKey: string): string {
+  try {
+    const u = new URL(endpoint);
+    u.searchParams.set("api-key", apiKey);
+    return u.toString();
+  } catch {
+    const sep = endpoint.includes("?") ? "&" : "?";
+    return `${endpoint}${sep}api-key=${encodeURIComponent(apiKey)}`;
+  }
+}

package/src/clients/SingleTokenDepositClient.ts

@@ -0,0 +1,91 @@
+import { Commitment, PublicKey } from "@solana/web3.js";
+import BN from "bn.js";
+import { CubeConfig } from "../config";
+import { PoolInfo } from "../types/pool";
+import { SdkResult, err, ok } from "../types/result";
+import {
+  BuiltTx,
+  SingleTokenDepositParams,
+  SingleTokenDepositQuote,
+} from "../types/tx";
+import { deriveHelperPda } from "../utils/pda";
+import { buildSingleTokenDepositTx } from "./tx-builders";
+import { RpcClient } from "./RpcClient";
+import { CubicPoolClient } from "./CubicPoolClient";
+
+export interface SingleTokenDepositClientParams {
+  config: CubeConfig;
+  poolAddress: PublicKey;
+  /** Optional — reuses an existing one if provided. */
+  rpc?: RpcClient | { endpoint: string; apiKey?: string; commitment?: Commitment };
+  /**
+   * Optional parent pool client — lets the deposit client reuse an already
+   * synced PoolInfo instead of making a fresh RPC round-trip.
+   */
+  poolClient?: CubicPoolClient;
+}
+
+/**
+ * Convenience class that wraps the single-token deposit flow end-to-end:
+ * quoting, transaction building, and helper-PDA derivation.
+ *
+ * Most consumers don't need to instantiate this directly — they can call
+ * `CubicPoolClient.singleTokenDeposit.*` which proxies here.
+ */
+export class SingleTokenDepositClient {
+  readonly config: CubeConfig;
+  readonly poolAddress: PublicKey;
+  private readonly poolClient: CubicPoolClient;
+
+  constructor(params: SingleTokenDepositClientParams) {
+    this.config = params.config;
+    this.poolAddress = params.poolAddress;
+    this.poolClient =
+      params.poolClient ??
+      new CubicPoolClient({
+        config: params.config,
+        poolAddress: params.poolAddress,
+        rpc:
+          params.rpc ??
+          {
+            endpoint: params.config.defaults.rpcEndpoint,
+            commitment: params.config.defaults.rpcCommitment,
+          },
+      });
+  }
+
+  /** Derived helper PDA for this pool. */
+  helperPda(): PublicKey {
+    return deriveHelperPda(this.config.programs.singleTokenLiquidity, this.poolAddress)[0];
+  }
+
+  /** Ensure pool state is loaded; populates the underlying CubicPoolClient cache. */
+  async sync(): Promise<SdkResult<PoolInfo>> {
+    return this.poolClient.sync();
+  }
+
+  /** Off-chain estimate of the deposit outcome. */
+  quote(
+    tokenInIndex: number,
+    amountIn: BN,
+    slippageHundredthsBps?: number
+  ): SdkResult<SingleTokenDepositQuote> {
+    return this.poolClient.quoteSingleTokenDeposit(tokenInIndex, amountIn, slippageHundredthsBps);
+  }
+
+  /** Build a ready-to-sign transaction. Includes idempotent helper-ATA creates. */
+  buildTx(params: SingleTokenDepositParams): SdkResult<BuiltTx> {
+    const pool = this.poolClient.getCached();
+    if (!pool) return err("invalid_input", "Call sync() first to populate pool state");
+    if (params.tokenInIndex < 0 || params.tokenInIndex >= pool.tokenCount) {
+      return err("invalid_input", "Invalid tokenInIndex");
+    }
+    if (params.amountIn.lten(0)) return err("invalid_input", "amountIn must be > 0");
+    try {
+      const tx = buildSingleTokenDepositTx(this.config, pool, params);
+      return ok(tx);
+    } catch (e) {
+      return err("tx_build_failed", "Failed to build single-token deposit tx", e);
+    }
+  }
+}

package/src/clients/index.ts

@@ -0,0 +1,7 @@
+export * from "./RpcClient";
+export * from "./CubeBackendClient";
+export * from "./CubicPoolClient";
+export * from "./tx-builders";
+export * from "./SingleTokenDepositClient";
+export * from "./PoolFactoryClient";
+export * from "./AdminClient";