@coffer_so/sdk 1.0.0

package/src/clients/versioned.ts

@@ -0,0 +1,80 @@
+import {
+  AddressLookupTableAccount,
+  Connection,
+  PublicKey,
+  TransactionInstruction,
+  TransactionMessage,
+  VersionedTransaction,
+} from "@solana/web3.js";
+import { PoolInfo } from "../types/pool";
+import { BuiltTx } from "../types/tx";
+import { SdkResult, err, ok } from "../types/result";
+
+/**
+ * Compile a set of instructions into a `VersionedTransaction` (v0),
+ * optionally using a per-pool Address Lookup Table to shrink the wire
+ * size below the 1232-byte legacy ceiling.
+ *
+ * ALT inclusion rules:
+ *   - If `lookupTable` is `PublicKey.default` (or undefined) → no ALT
+ *     is referenced; the tx is v0 but uses only static account keys.
+ *   - Otherwise → fetch the ALT via `connection.getAddressLookupTable`
+ *     and include it. If the fetch fails, the function returns an
+ *     `alt_fetch_failed` error rather than silently falling back.
+ *
+ * Wallets supporting the standard `signTransaction(Transaction |
+ * VersionedTransaction)` overload (Phantom, Solflare, Backpack, Glow,
+ * the wallet-adapter set since 2023) sign these without changes.
+ */
+export async function buildVersionedTx(
+  conn: Connection,
+  payer: PublicKey,
+  instructions: TransactionInstruction[],
+  lookupTable: PublicKey | undefined,
+): Promise<SdkResult<{ tx: VersionedTransaction; alts: AddressLookupTableAccount[] }>> {
+  const alts: AddressLookupTableAccount[] = [];
+
+  if (lookupTable && !lookupTable.equals(PublicKey.default)) {
+    try {
+      const res = await conn.getAddressLookupTable(lookupTable);
+      if (!res.value) {
+        return err(
+          "alt_fetch_failed",
+          `Lookup table ${lookupTable.toBase58()} not found on-chain. ` +
+            "The pool advertises an ALT but the account is missing — " +
+            "the ALT may have been closed or the RPC is stale.",
+        );
+      }
+      alts.push(res.value);
+    } catch (e) {
+      return err(
+        "alt_fetch_failed",
+        `Failed to fetch lookup table ${lookupTable.toBase58()}`,
+        e,
+      );
+    }
+  }
+
+  const { blockhash } = await conn.getLatestBlockhash("confirmed");
+  const msg = new TransactionMessage({
+    payerKey: payer,
+    recentBlockhash: blockhash,
+    instructions,
+  }).compileToV0Message(alts);
+
+  return ok({ tx: new VersionedTransaction(msg), alts });
+}
+
+/**
+ * Convenience: take a SDK-built `BuiltTx` and a pool snapshot, produce
+ * a signed-ready `VersionedTransaction`. Picks up `pool.lookupTable`
+ * automatically.
+ */
+export async function compileBuiltTx(
+  conn: Connection,
+  payer: PublicKey,
+  built: BuiltTx,
+  pool: Pick<PoolInfo, "lookupTable">,
+): Promise<SdkResult<{ tx: VersionedTransaction; alts: AddressLookupTableAccount[] }>> {
+  return buildVersionedTx(conn, payer, built.instructions, pool.lookupTable);
+}

package/src/config/index.ts

@@ -0,0 +1,111 @@
+import { Commitment, PublicKey } from "@solana/web3.js";
+import {
+  NETWORK_PROGRAMS,
+  NetworkPrograms,
+  Network,
+  DEFAULT_RPC_ENDPOINT,
+  DEFAULT_RPC_ENDPOINTS,
+  DEFAULT_RPC_TIMEOUT_MS,
+} from "./networks";
+import { TokenInfo } from "./tokens";
+
+export * from "./networks";
+export * from "./tokens";
+
+/**
+ * Root SDK configuration. Passed into every Client class at construction.
+ * Immutable after creation — rebuild if you need to switch networks.
+ */
+export interface CofferConfig {
+  network: Network;
+  programs: NetworkPrograms;
+  defaults: {
+    rpcEndpoint: string;
+    rpcEndpoints: string[];
+    rpcTimeoutMs: number;
+    rpcCommitment: Commitment;
+    /** Used by helpers that prepend a ComputeBudget instruction. */
+    cuLimit: number;
+    /**
+     * Default slippage budget when the caller doesn't pass one. Units:
+     * hundredths of a basis point (matches cubic-pool's `swap_fee_rate`
+     * scale). 50_000 = 5%.
+     */
+    slippageHundredthsBps: number;
+  };
+  /** Optional token registry keyed by mint pubkey string. */
+  tokens?: Record<string, TokenInfo>;
+  /** Optional backend endpoint; consumed by CofferBackendClient. */
+  backendEndpoint?: string;
+}
+
+export interface CofferConfigOverrides {
+  rpcEndpoint?: string;
+  rpcEndpoints?: string[];
+  rpcTimeoutMs?: number;
+  rpcCommitment?: Commitment;
+  cuLimit?: number;
+  slippageHundredthsBps?: number;
+  backendEndpoint?: string;
+  tokens?: Record<string, TokenInfo>;
+}
+
+/** Build a CofferConfig for the named network with optional overrides. */
+export function getConfig(network: Network, overrides: CofferConfigOverrides = {}): CofferConfig {
+  const rpcEndpoints = resolveRpcEndpoints(network, overrides);
+  return {
+    network,
+    programs: NETWORK_PROGRAMS[network],
+    defaults: {
+      rpcEndpoint: rpcEndpoints[0] ?? overrides.rpcEndpoint ?? DEFAULT_RPC_ENDPOINT[network],
+      rpcEndpoints,
+      rpcTimeoutMs: overrides.rpcTimeoutMs ?? DEFAULT_RPC_TIMEOUT_MS,
+      rpcCommitment: overrides.rpcCommitment ?? "confirmed",
+      cuLimit: overrides.cuLimit ?? 1_400_000,
+      slippageHundredthsBps: overrides.slippageHundredthsBps ?? 50_000,
+    },
+    tokens: overrides.tokens,
+    backendEndpoint: overrides.backendEndpoint,
+  };
+}
+
+function resolveRpcEndpoints(network: Network, overrides: CofferConfigOverrides): string[] {
+  if (overrides.rpcEndpoints && overrides.rpcEndpoints.length > 0) {
+    return dedupe(overrides.rpcEndpoints);
+  }
+  if (overrides.rpcEndpoint) {
+    return dedupe([overrides.rpcEndpoint, ...DEFAULT_RPC_ENDPOINTS[network]]);
+  }
+  return [...DEFAULT_RPC_ENDPOINTS[network]];
+}
+
+function dedupe(values: string[]): string[] {
+  return Array.from(new Set(values));
+}
+
+export const CUBIC_POOL_SEED = Buffer.from("cubic_pool");
+export const BPT_MINT_SEED = Buffer.from("bpt_mint");
+export const STLD_HELPER_SEED = Buffer.from("stld_helper");
+export const TREASURY_SEED = Buffer.from("treasury");
+
+/** Contract-level constants mirrored from Rust. */
+export const WEIGHT_SCALE = 10_000; // 100 %
+export const MIN_WEIGHT = 100; // 1 %
+export const MAX_WEIGHT = 9_900; // 99 %
+export const MIN_TOKENS = 2;
+export const MAX_TOKENS = 10;
+export const BPT_DECIMALS = 9;
+export const SWAP_FEE_PRECISION = 1_000_000; // 100 %
+export const PROTOCOL_FEE_PRECISION = 10_000; // 100 %
+export const PERCENT_SCALE = 10_000; // 100 % (max-selloff / surge-fee scale)
+export const MAX_SWAP_FEE_RATE = 100_000; // 10 %
+export const MAX_PROTOCOL_FEE_RATE = 5_000; // 50 %
+export const MINIMUM_INITIAL_BPT = 1_000n;
+export const SLIPPAGE_PRECISION = 1_000_000;
+export const MIN_SLIPPAGE_HBPS = 10; // 0.001 %
+
+export type ProgramIdKind = "cubicPool" | "singleTokenLiquidity" | "protocolAdmin";
+
+export function programId(cfg: CofferConfig, kind: ProgramIdKind): PublicKey {
+  return cfg.programs[kind];
+}

package/src/config/networks.ts

@@ -0,0 +1,71 @@
+import { PublicKey } from "@solana/web3.js";
+
+export type Network = "mainnet" | "devnet" | "localnet";
+
+export interface NetworkPrograms {
+  cubicPool: PublicKey;
+  singleTokenLiquidity: PublicKey;
+  protocolAdmin: PublicKey;
+}
+
+export const NETWORK_PROGRAMS: Record<Network, NetworkPrograms> = {
+  mainnet: {
+    cubicPool: new PublicKey("8iQtGj9mcUfFUGaiCpPy89swC3s8YTC8FhVZWfgeZhwu"),
+    // TODO(mainnet): single_token_liquidity is NOT deployed on mainnet — this
+    // is the devnet program ID as a placeholder. Single-token deposit is
+    // disabled in the frontend. If/when stld ships on mainnet, replace this
+    // with the real mainnet program ID.
+    singleTokenLiquidity: new PublicKey(
+      "7BpdUH1tzTSXLuQNo6YpjJ8Eagw8AkrS6cnkxiJdCFS2",
+    ),
+    protocolAdmin: new PublicKey(
+      "3jiojHZbjJQ7QLMGSTjFwxVEmx4NtuRy34nLAmsJME81",
+    ),
+  },
+  devnet: {
+    // v5.1 (post-audit) copy deployed on devnet under our wallet. The original
+    // devnet CVKx/HJEi IDs are unusable: cubic_pool's was closed permanently
+    // and protocol_admin's has a non-ours upgrade authority.
+    //
+    // These binaries are built with devnet `declare_id`s AND a devnet
+    // `PROTOCOL_ADMIN_PROGRAM_ID` — cubic_pool pins that constant at compile
+    // time to derive the Treasury PDA, so a mainnet build would look for a
+    // Treasury that does not exist here.
+    cubicPool: new PublicKey("E6YAKuLAd8vBgJnXsVdPCFCdgUef6ZinfDst3JMxuhJJ"),
+    // stld IS deployed on devnet and shares its ID with mainnet, because its
+    // `declare_id` needed no devnet override.
+    singleTokenLiquidity: new PublicKey(
+      "7BpdUH1tzTSXLuQNo6YpjJ8Eagw8AkrS6cnkxiJdCFS2",
+    ),
+    protocolAdmin: new PublicKey(
+      "6bFDi7RrLJSbhBpJ2AjHAQfbzBiHGXQXND7no8gv8gux",
+    ),
+  },
+  localnet: {
+    cubicPool: new PublicKey("8iQtGj9mcUfFUGaiCpPy89swC3s8YTC8FhVZWfgeZhwu"),
+    singleTokenLiquidity: new PublicKey(
+      "7BpdUH1tzTSXLuQNo6YpjJ8Eagw8AkrS6cnkxiJdCFS2",
+    ),
+    protocolAdmin: new PublicKey(
+      "3jiojHZbjJQ7QLMGSTjFwxVEmx4NtuRy34nLAmsJME81",
+    ),
+  },
+};
+
+export const DEFAULT_RPC_ENDPOINT: Record<Network, string> = {
+  mainnet: "https://solana.drpc.org",
+  devnet: "https://api.devnet.solana.com",
+  localnet: "http://127.0.0.1:8899",
+};
+
+export const DEFAULT_RPC_ENDPOINTS: Record<Network, string[]> = {
+  mainnet: [
+    "https://solana.drpc.org",
+    "https://solana-rpc.publicnode.com",
+    "https://solana.api.pocket.network",
+  ],
+  devnet: ["https://api.devnet.solana.com"],
+  localnet: ["http://127.0.0.1:8899"],
+};
+
+export const DEFAULT_RPC_TIMEOUT_MS = 2_000;

package/src/config/tokens.ts

@@ -0,0 +1,52 @@
+import { PublicKey } from "@solana/web3.js";
+
+/** Metadata describing a token. Populated by backend or local registry. */
+export interface TokenInfo {
+  mint: PublicKey;
+  symbol: string;
+  name: string;
+  decimals: number;
+  logoUri?: string;
+  coingeckoId?: string;
+}
+
+/**
+ * Local fallback registry of well-known tokens. The backend registry takes
+ * precedence; this is used when the backend is unreachable.
+ */
+export const KNOWN_TOKENS: Record<string, Omit<TokenInfo, "mint"> & { mint: string }> = {
+  SOL: {
+    mint: "So11111111111111111111111111111111111111112",
+    symbol: "SOL",
+    name: "Wrapped SOL",
+    decimals: 9,
+    logoUri:
+      "https://raw.githubusercontent.com/solana-labs/token-list/main/assets/mainnet/So11111111111111111111111111111111111111112/logo.png",
+    coingeckoId: "solana",
+  },
+  USDC: {
+    mint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+    symbol: "USDC",
+    name: "USD Coin",
+    decimals: 6,
+    logoUri:
+      "https://raw.githubusercontent.com/solana-labs/token-list/main/assets/mainnet/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v/logo.png",
+    coingeckoId: "usd-coin",
+  },
+  USDT: {
+    mint: "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB",
+    symbol: "USDT",
+    name: "Tether USD",
+    decimals: 6,
+    coingeckoId: "tether",
+  },
+};
+
+export function resolveKnownToken(mint: string): TokenInfo | undefined {
+  for (const t of Object.values(KNOWN_TOKENS)) {
+    if (t.mint === mint) {
+      return { ...t, mint: new PublicKey(t.mint) };
+    }
+  }
+  return undefined;
+}