Coffer Docs
SDK

@coffer_so/sdk

Read pools, quote operations, and build Solana transactions

The TypeScript SDK provides reads, quotes, builders, and decoders. Pin a release compatible with your program and IDL.

Install

npm install @coffer_so/sdk @solana/web3.js bn.js
npm install --save-dev @types/bn.js

High-level amounts use BN; standalone math uses bigint, both in raw units. One six-decimal token is 1_000_000.

Quote and build a swap

This RPC example requires a funded input ATA and an existing output ATA:

import { CubicPoolClient, getConfig } from "@coffer_so/sdk";
import { PublicKey } from "@solana/web3.js";
import BN from "bn.js";

export async function prepareSwap(
  poolAddress: PublicKey,
  user: PublicKey,
  inputMint: PublicKey,
  outputMint: PublicKey,
  rawAmountIn: string,
) {
  const config = getConfig("mainnet", {
    slippageHundredthsBps: 5_000, // 0.5%; choose for your application
  });
  const client = new CubicPoolClient({ config, poolAddress });
  const synced = await client.sync();
  if (!synced.ok) throw new Error(synced.error.humanMessage);

  const pool = synced.data;
  const tokenInIndex = pool.tokens.findIndex(t => t.mint.equals(inputMint));
  const tokenOutIndex = pool.tokens.findIndex(t => t.mint.equals(outputMint));
  if (tokenInIndex < 0 || tokenOutIndex < 0) {
    throw new Error("Both mints must belong to this pool");
  }

  const amountIn = new BN(rawAmountIn, 10);
  const quote = client.quoteSwap(tokenInIndex, tokenOutIndex, amountIn);
  if (!quote.ok) throw new Error(quote.error.humanMessage);
  if (quote.data.minAmountOut.isZero()) {
    throw new Error("Amount is too small for a positive output minimum");
  }

  const built = client.buildSwapTx({
    user,
    tokenInIndex,
    tokenOutIndex,
    amountIn,
    minAmountOut: quote.data.minAmountOut,
  });
  if (!built.ok) throw new Error(built.error.humanMessage);

  return { pool, quote: quote.data, built: built.data };
}

For the SDK extension profile below, amountOut is net of surge; grossAmountOut is before surge. A program supporting token transfer fees also distinguishes vault payout from the recipient's net credit; do not use a quote from an SDK release that omits those fees for such a mint. feeAmount/protocolFeeAmount use input units; surgeFeeAmount uses output units.

compileBuiltTx(connection, user, built, pool) returns an SdkResult with an unsigned VersionedTransaction and fetched lookup tables. BuiltTx is an instruction bundle. The application handles ATAs, SOL wrapping, signing, submission, and confirmation; the swap builder creates no accounts.

Quote state and slippage

sync() fetches pool, mint metadata, LP supply, and Solana Clock. Synchronous quoteSwap uses that snapshot; optional nowSeconds changes its timestamp, not reserves. Refresh state and simulate the complete transaction.

Slippage uses scale 1_000_000: 5_000 = 0.5%. Select it explicitly:

minAmountOut = floor(expectedAmountOut × (1,000,000 − slippageHbps) / 1,000,000)

Retain the user's floor. See Math for fees and LP-owned reserve accounting.

Clients and transaction surfaces

SurfacePurpose
CubicPoolClientPool reads, cached quotes, builders, events
CubeBackendClientHTTP discovery, routing, statistics
PoolFactoryClientDeployment/configuration, not discovery
SingleTokenDepositClientSingle-token deposit workflow
AdminClientAuthorized protocol administration
buildContractInstructionTyped ABI instruction construction

The hosted backend's read endpoints are public; see the API reference. The client's apiKey option is the app's wallet session token (sent as Authorization: Bearer); it is not needed for the public endpoints.

High-level methods generally return { ok: true, data } or { ok: false, error }. Inspect error.code/humanMessage; retain cause. Raw builders, parsers, math, and some instruction methods can throw; getCached() returns ordinary values. sync() validates pool owner, discriminator, and mint ownership; not every helper does.

Liquidity builders

QuoteTransaction limits
quoteSeedDeposit(user, tokenAmounts, slippageHbps)Exact seed amounts; positive minimumBptAmount
quoteAddLiquidity(tokenAmounts, slippageHbps)Spend ceilings; positive minimumBptAmount
quoteRemove(bptAmount)Explicit per-token minimumTokenAmounts
quoteSingleTokenDeposit(...)Positive whole-route minimumBptAmount

Vectors use pool token order. Show estimated depositAmounts, not ceilings; proportional-join refundAmounts stay in the wallet. Exit effectiveBptIn can be smaller to preserve minimum supply.

Match liquidity rounding as well as instruction arguments. The current pool implementation rounds deposit reserve credits up and LP minted down; older SDK quotes can round the basket down. Use a compatible release and simulate the complete transaction before treating estimated token spends as exact.

buildDeployPoolTx creates pool/LP mint, not seed liquidity or vault ATAs. buildAddLiquidityTx creates the user's LP ATA; input accounts/vaults must exist. Single-token deposits need separate setup.

For application-side initialization from a decimal concentration factor, materialize CF = round(concentration_factor × 10^9), then compute V = floor(rawAmount × CF / 10^9) with integer multiplication. This conversion is application code, not an implicit SDK adjustment.

Token programs and account addresses

Derive ATAs using each mint's tokenProgram; read pool.bptTokenProgram for LP accounts. Creation defaults to classic SPL Token but supports bptTokenProgram. Use derivePoolPda, deriveBptMint, deriveHelperPda, and deriveAta; account derivations include exact seeds and programs.

Token-2022 extension limits

The SDK extension profile described here rejects TransferFeeConfig, TransferHook, NonTransferable, ConfidentialTransferFeeConfig, PausableConfig, and unknown extensions. This is narrower than the current pool instruction implementation's checked transfer support. Do not remove the SDK guard without matching its fee math, account construction, and event decoding to that program. Check the installed SDK release, extension policy, and target operation.

Network configuration

getConfig accepts mainnet, devnet, localnet. Overrides cover RPC endpoint/timeouts/commitment, compute limit, slippage, backend, and token metadata; its second argument cannot override program IDs. Backend HTTP does not replace Solana RPC.

On this page