@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.jsHigh-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
| Surface | Purpose |
|---|---|
CubicPoolClient | Pool reads, cached quotes, builders, events |
CubeBackendClient | HTTP discovery, routing, statistics |
PoolFactoryClient | Deployment/configuration, not discovery |
SingleTokenDepositClient | Single-token deposit workflow |
AdminClient | Authorized protocol administration |
buildContractInstruction | Typed 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
| Quote | Transaction 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.