@send-fun/sdk 1.1.0 → 1.2.0

package/src/launchpad/generated/accounts/rewardAccrual.ts

@@ -42,6 +42,7 @@ import {
 	type ReadonlyUint8Array,
 } from '@solana/kit';
 import { SEND_LAUNCHPAD_PROGRAM_ADDRESS } from '../programs/index.js';
+import { accountIsCreated } from '../shared/index.js';
 
 export const REWARD_ACCRUAL_DISCRIMINATOR: ReadonlyUint8Array = new Uint8Array([
 	158, 244, 116, 30, 227, 132, 105, 182,
@@ -109,9 +110,25 @@ export function getRewardAccrualCodec(): FixedSizeCodec<
 	return combineCodec(getRewardAccrualEncoder(), getRewardAccrualDecoder());
 }
 
+/**
+ * Decodes a `RewardAccrual` account, throwing when another program owns it or its discriminator
+ * does not match.
+ *
+ * Unlike {@link fetchMaybeRewardAccrual}, this throws for an address that only holds lamports rather
+ * than returning the non-existing variant: an account passed as existing must never come back as that
+ * variant typed as an `Account`. Apply {@link accountIsCreated} first to accounts fetched another way.
+ */
 export function decodeRewardAccrual<TAddress extends string = string>(
 	encodedAccount: EncodedAccount<TAddress>,
 ): Account<RewardAccrual, TAddress>;
+/**
+ * Decodes a `RewardAccrual` account, throwing when another program owns it or its discriminator
+ * does not match.
+ *
+ * Unlike {@link fetchMaybeRewardAccrual}, this throws for an address that only holds lamports rather
+ * than returning the non-existing variant: an account passed as existing must never come back as that
+ * variant typed as an `Account`. Apply {@link accountIsCreated} first to accounts fetched another way.
+ */
 export function decodeRewardAccrual<TAddress extends string = string>(
 	encodedAccount: MaybeEncodedAccount<TAddress>,
 ): MaybeAccount<RewardAccrual, TAddress>;
@@ -142,6 +159,7 @@ export function decodeRewardAccrual<TAddress extends string = string>(
 	);
 }
 
+/** Fetches a `RewardAccrual` account, throwing when it does not exist or only holds lamports. */
 export async function fetchRewardAccrual<TAddress extends string = string>(
 	rpc: Parameters<typeof fetchEncodedAccount>[0],
 	address: Address<TAddress>,
@@ -152,15 +170,25 @@ export async function fetchRewardAccrual<TAddress extends string = string>(
 	return maybeAccount;
 }
 
+/**
+ * Fetches a `RewardAccrual` account, or the non-existing variant when the address holds no
+ * account or only lamports (see {@link accountIsCreated}).
+ * {@link decodeRewardAccrual} throws for a lamports-only account instead.
+ */
 export async function fetchMaybeRewardAccrual<TAddress extends string = string>(
 	rpc: Parameters<typeof fetchEncodedAccount>[0],
 	address: Address<TAddress>,
 	config?: FetchAccountConfig,
 ): Promise<MaybeAccount<RewardAccrual, TAddress>> {
 	const maybeAccount = await fetchEncodedAccount(rpc, address, config);
-	return decodeRewardAccrual(maybeAccount);
+	return decodeRewardAccrual(
+		accountIsCreated(maybeAccount)
+			? maybeAccount
+			: { address, exists: false },
+	);
 }
 
+/** Fetches `RewardAccrual` accounts, throwing when any does not exist or only holds lamports. */
 export async function fetchAllRewardAccrual(
 	rpc: Parameters<typeof fetchEncodedAccounts>[0],
 	addresses: Array<Address>,
@@ -175,6 +203,11 @@ export async function fetchAllRewardAccrual(
 	return maybeAccounts;
 }
 
+/**
+ * Fetches `RewardAccrual` accounts, with the non-existing variant for each address that holds
+ * no account or only lamports (see {@link accountIsCreated}).
+ * {@link decodeRewardAccrual} throws for a lamports-only account instead.
+ */
 export async function fetchAllMaybeRewardAccrual(
 	rpc: Parameters<typeof fetchEncodedAccounts>[0],
 	addresses: Array<Address>,
@@ -182,7 +215,11 @@ export async function fetchAllMaybeRewardAccrual(
 ): Promise<MaybeAccount<RewardAccrual>[]> {
 	const maybeAccounts = await fetchEncodedAccounts(rpc, addresses, config);
 	return maybeAccounts.map((maybeAccount) =>
-		decodeRewardAccrual(maybeAccount),
+		decodeRewardAccrual(
+			accountIsCreated(maybeAccount)
+				? maybeAccount
+				: { address: maybeAccount.address, exists: false },
+		),
 	);
 }
 

package/src/launchpad/generated/index.ts

@@ -13,4 +13,5 @@ export * from './instructions/index.js';
 export * from './pdas/index.js';
 export * from './plugins/index.js';
 export * from './programs/index.js';
+export * from './shared/index.js';
 export * from './types/index.js';

package/src/launchpad/generated/shared/index.ts

@@ -0,0 +1,52 @@
+/**
+ * This code was AUTOGENERATED using the Codama library.
+ * Please DO NOT EDIT THIS FILE, instead use visitors
+ * to add features, then rerun Codama to update it.
+ *
+ * @see https://github.com/codama-idl/codama
+ */
+
+import type { Address, EncodedAccount, MaybeEncodedAccount } from '@solana/kit';
+
+/** The System Program, which owns every address nobody has created an account at yet. */
+const SYSTEM_PROGRAM_ADDRESS =
+	'11111111111111111111111111111111' as Address<'11111111111111111111111111111111'>;
+
+/**
+ * Whether an encoded account was created on-chain, rather than merely sent lamports.
+ *
+ * Anyone can send lamports to an address before its account is created, which leaves it on-chain,
+ * owned by the System Program, with no data. This returns `false` for that shape, as it does for an
+ * account that does not exist. Any other existing account counts as created, whoever owns it; the
+ * `decode*` functions still check the owner.
+ *
+ * The generated `fetchMaybe*` and `fetchAllMaybe*` helpers apply this rule themselves. Apply it to
+ * accounts you fetch or receive another way (subscriptions, batch loaders, caches) before passing
+ * them to a `decode*` function, which throws for a lamports-only account: an account passed to it as
+ * existing must never come back as the non-existing variant typed as an `Account`.
+ *
+ * Only a `true` result narrows the type. A lamports-only account is still `exists: true` at runtime,
+ * so a `false` result leaves the type unchanged instead of narrowing it to the non-existing variant.
+ * The `uncreated` property in the narrowed type is never present; it exists only to prevent that.
+ *
+ * @example
+ * ```ts
+ * const maybeAccount = decodeMyAccount(
+ *   accountIsCreated(encodedAccount) ? encodedAccount : { address: encodedAccount.address, exists: false },
+ * );
+ * ```
+ */
+export function accountIsCreated<
+	TAccount extends EncodedAccount | MaybeEncodedAccount,
+>(
+	account: TAccount,
+): account is Exclude<TAccount, { readonly exists: false }> & {
+	readonly uncreated?: never;
+} {
+	const maybeAccount: EncodedAccount | MaybeEncodedAccount = account;
+	if ('exists' in maybeAccount && !maybeAccount.exists) return false;
+	return !(
+		maybeAccount.programAddress === SYSTEM_PROGRAM_ADDRESS &&
+		maybeAccount.data.length === 0
+	);
+}

package/src/launchpad/migrate.ts

@@ -9,7 +9,7 @@ export interface MigrateParams {
 	caller: TransactionSigner;
 	baseMint: Address;
 	quoteMint: Address;
-	/** `bondingCurve.creatorFeeConfig`; `migrate` rejects any other address. */
+	/** `bondingCurve.creatorFeeConfig`. `migrate` rejects any other address. */
 	creatorFeeConfig: Address;
 	quoteTokenProgram: Address;
 }

package/src/launchpad/trade.ts

@@ -19,7 +19,7 @@ export interface LaunchpadTradeParams {
 	partner: PartnerInput;
 	platformConfig: Address;
 	quoteTokenProgram: Address;
-	/** Token-2022 schedule for the epoch the trade lands in; stale or missing skews the slippage bounds. */
+	/** The quote mint's transfer fee for the epoch the trade lands in. A missing or old fee gives wrong slippage bounds. */
 	quoteFee?: MintFee;
 	baseFee?: MintFee;
 	/** {@inheritDoc LaunchpadInstructionParams.userQuoteAccount} */
@@ -40,16 +40,16 @@ export interface LaunchpadInstructionParams {
 	partner: PartnerInput;
 	platformConfig: Address;
 	quoteTokenProgram: Address;
-	/** Any user-owned quote-mint account. Defaults to the ATA, created mid-trade
-	 *  if missing (payer funds rent), which only rescues a sell. For WSOL,
-	 *  a throwaway `createAccountWithSeed` account is cheaper. */
+	/** Any quote-mint token account that `user` owns. Defaults to the user's ATA.
+	 *  The program creates a missing ATA, and `payer` pays the rent. */
 	userQuoteAccount?: Address;
-	/** Any user-owned base-mint account. Defaults to the ATA, created mid-trade
-	 *  if missing (payer funds rent), which only rescues a buy. */
+	/** Any base-mint token account that `user` owns. Defaults to the user's ATA.
+	 *  The program creates a missing ATA, and `payer` pays the rent. */
 	userBaseAccount?: Address;
 }
 
-/** `baseAmountOut` is net to the buyer: the program reads `amount` as `base_to_user`. */
+/** `baseAmountOut` is the base the buyer receives, after the base mint's transfer fee.
+ *  The buy is capped at the curve's supply left. Read the result from `quote.baseToUser`. */
 export async function buyExactOut(
 	params: LaunchpadBuyParams & { baseAmountOut: bigint },
 ): Promise<{ instruction: Instruction; quote: BuyQuote }> {
@@ -62,7 +62,7 @@ export async function buyExactOut(
 		baseFee: params.baseFee,
 		baseReserveCap: params.realBaseReserves,
 	});
-	// The cap is measured on the gross the buyer sends, quote transfer fee included.
+	// The program checks `maxAmountIn` against the gross the buyer sends, quote transfer fee included.
 	const maxQuoteIn = amm.calculateSlippageUp(
 		quote.quoteFromUser,
 		params.slippageBps,
@@ -70,7 +70,7 @@ export async function buyExactOut(
 	return {
 		instruction: await buildBuyExactOutInstruction({
 			...params,
-			// Capped at the supply left. The program reverts a short fill.
+			// Capped at the supply left. The program rejects a larger amount.
 			amountOut: quote.baseToUser,
 			maxAmountIn: maxQuoteIn,
 		}),
@@ -90,7 +90,7 @@ export async function buyExactIn(
 		baseFee: params.baseFee,
 		baseReserveCap: params.realBaseReserves,
 	});
-	// The floor is measured on the buyer's credit, not the vault's debit.
+	// The program checks `minAmountOut` against what the buyer receives, not the vault's debit.
 	const minBaseOut = amm.calculateSlippageDown(
 		quote.baseToUser,
 		params.slippageBps,
@@ -116,7 +116,7 @@ export async function sellExactIn(
 		quoteFee: params.quoteFee,
 		baseFee: params.baseFee,
 	});
-	// The floor is measured on the seller's credit, not what leaves the vault.
+	// The program checks `minAmountOut` against what the seller receives, not the vault's debit.
 	const minQuoteOut = amm.calculateSlippageDown(
 		quote.quoteToUser,
 		params.slippageBps,
@@ -131,7 +131,7 @@ export async function sellExactIn(
 	};
 }
 
-/** `quoteAmountOut` is net to the seller: the program reads `amount` as `quote_to_user`. */
+/** `quoteAmountOut` is the quote the seller receives, after the quote mint's transfer fee. */
 export async function sellExactOut(
 	params: LaunchpadTradeParams & { quoteAmountOut: bigint },
 ): Promise<{ instruction: Instruction; quote: SellQuote }> {
@@ -143,7 +143,7 @@ export async function sellExactOut(
 		quoteFee: params.quoteFee,
 		baseFee: params.baseFee,
 	});
-	// The cap is measured on the gross the seller sends, base transfer fee included.
+	// The program checks `maxAmountIn` against the gross the seller sends, base transfer fee included.
 	const maxBaseIn = amm.calculateSlippageUp(
 		quote.baseFromUser,
 		params.slippageBps,
@@ -214,7 +214,7 @@ export async function buildSellExactOutInstruction(
 	});
 }
 
-/** Percent of the curve's real base sold (0-100); 100 is the migration threshold. */
+/** Returns the percent of the curve's real base sold, from 0 to 100. At 100 the curve can migrate. */
 export function calculateBondingCurveProgress(params: {
 	realBaseReserves: bigint;
 	initialRealBase: bigint;
@@ -237,7 +237,7 @@ function resolveSharedAccounts(params: LaunchpadInstructionParams) {
 		partner: params.partner,
 		platformConfig: params.platformConfig,
 		quoteTokenProgram: params.quoteTokenProgram,
-		// Left undefined so the generated client derives the ATA itself.
+		// When omitted, the generated client derives the ATA.
 		...(params.userQuoteAccount !== undefined && {
 			userQuoteAccount: params.userQuoteAccount,
 		}),

package/src/math/amm.ts

@@ -4,7 +4,6 @@ const BPS_DIVISOR = 10_000n;
 
 const U64_MAX = 18_446_744_073_709_551_615n;
 
-/** Each call mirrors a `u64::try_from` in the Rust twin; drop one and an oversized leg fails in the encoder. */
 function assertU64(label: string, value: bigint): bigint {
 	if (value > U64_MAX) {
 		throw new RangeError(`${label}: overflows u64`);
@@ -12,15 +11,15 @@ function assertU64(label: string, value: bigint): bigint {
 	return value;
 }
 
-/** Token-2022 `TransferFeeConfig` for the epoch the trade lands in; a stale one misprices the trade. */
+/** A Token-2022 transfer fee for one epoch. Use the fee for the epoch the trade lands in. */
 export interface MintFee {
 	/** 0 to 10_000. */
 	bps: number;
-	/** Cap on the withheld amount, in the mint's raw units. */
+	/** Maximum fee per transfer, in the mint's raw units. */
 	maximumFee: bigint;
 }
 
-/** No transfer lands exactly the requested amount; approximating one hands the program a bound it rejects. */
+/** Thrown when no transfer delivers exactly `amount` after the transfer fee. */
 export class TransferFeeNotSettleableError extends RangeError {
 	readonly amount: bigint;
 	readonly mintFee: MintFee;
@@ -42,7 +41,8 @@ function assertMintFee(fee: MintFee): void {
 	}
 }
 
-/** Rounds up, then caps (SPL's order); swapping them lets a split booking over-credit. */
+/** Returns the transfer fee on `amount`. Rounds up, then caps at `maximumFee`, in SPL's order.
+ *  Returns 0 without `fee`. Throws `RangeError` if `fee` is out of range. */
 export function feeOn(amount: bigint, fee?: MintFee): bigint {
 	if (fee === undefined) return 0n;
 	assertMintFee(fee);
@@ -52,18 +52,18 @@ export function feeOn(amount: bigint, fee?: MintFee): bigint {
 	return raw < fee.maximumFee ? raw : fee.maximumFee;
 }
 
-/** What lands when `amount` is sent; use `grossUp` to land an exact amount. */
+/** Returns what the recipient receives when `amount` is sent. `grossUp` is the inverse. */
 export function amountAfterFee(amount: bigint, fee?: MintFee): bigint {
 	return amount - feeOn(amount, fee);
 }
 
-/** Line-for-line mirror of SPL's `TransferFee::calculate_pre_fee_amount`; `undefined` when no u64 answer exists. */
+/** Matches SPL `TransferFee::calculate_pre_fee_amount`. `undefined` if the result does not fit a u64. */
 function preFeeAmount(amount: bigint, fee: MintFee): bigint | undefined {
 	const bps = BigInt(fee.bps);
 	if (bps === 0n) return amount;
-	// Unreachable via `grossUp`; SPL has it, so the mirror keeps it.
+	// Unreachable from `grossUp`. Kept to match SPL.
 	if (amount === 0n) return 0n;
-	// 100%: only the cap can be settled.
+	// At 100%, the fee is always `maximumFee`.
 	if (bps === BPS_DIVISOR) {
 		const capped = amount + fee.maximumFee;
 		return capped > U64_MAX ? undefined : capped;
@@ -77,7 +77,8 @@ function preFeeAmount(amount: bigint, fee: MintFee): bigint | undefined {
 	return rawPreFee > U64_MAX ? undefined : rawPreFee;
 }
 
-/** What must be sent for exactly `amount` to land; throws {@link TransferFeeNotSettleableError} if none does. */
+/** Returns the amount to send so that exactly `amount` arrives. Returns `amount` without `fee`.
+ *  Throws {@link TransferFeeNotSettleableError} if no such amount exists. */
 export function grossUp(amount: bigint, fee?: MintFee): bigint {
 	if (fee === undefined) return amount;
 	assertMintFee(fee);
@@ -87,7 +88,7 @@ export function grossUp(amount: bigint, fee?: MintFee): bigint {
 	if (preFee === undefined)
 		throw new TransferFeeNotSettleableError(amount, fee);
 
-	// SPL's inverse is inexact (`feeOn(x) >= inverse(x - feeOn(x))`): re-derive forward and reject a mismatch.
+	// SPL's inverse is inexact (`feeOn(x) >= inverse(x - feeOn(x))`). Check it forward and reject a mismatch.
 	const impliedFee = feeOn(preFee, fee);
 	const gross = amount + impliedFee;
 	if (gross > U64_MAX || feeOn(gross, fee) !== impliedFee) {
@@ -96,8 +97,8 @@ export function grossUp(amount: bigint, fee?: MintFee): bigint {
 	return gross;
 }
 
-/** `baseAmount`/`quoteAmount` are the user's transfers, as in on-chain `TradeResult`. Read the net
- *  fields on {@link BuyQuote}/{@link SellQuote}; re-deriving them drifts from the program by a rounding step. */
+/** `baseAmount` and `quoteAmount` are the user's transfers.
+ *  Read the net amounts from the fields of {@link BuyQuote} and {@link SellQuote}. Do not calculate them again. */
 export interface TradeQuote {
 	/** Base sent: vault to user on a buy, user to vault on a sell. */
 	baseAmount: bigint;
@@ -110,20 +111,20 @@ export interface TradeQuote {
 }
 
 export interface BuyQuote extends TradeQuote {
-	/** Priced on the quote reaching the vault. */
+	/** Priced on the quote that reaches the vault. */
 	fee: bigint;
-	/** Base credited to the buyer, after the base mint's cut. */
+	/** Base the buyer receives, after the base mint's transfer fee. */
 	baseToUser: bigint;
 	/** Equals `quoteAmount`. */
 	quoteFromUser: bigint;
 }
 
 export interface SellQuote extends TradeQuote {
-	/** Priced on the quote leaving the vault. */
+	/** Priced on the AMM's quote output, before this fee. */
 	fee: bigint;
 	/** Equals `baseAmount`. */
 	baseFromUser: bigint;
-	/** Quote credited to the seller, after the quote mint's cut. */
+	/** Quote the seller receives, after the quote mint's transfer fee. */
 	quoteToUser: bigint;
 }
 
@@ -139,7 +140,8 @@ function sqrtBigInt(value: bigint): bigint {
 	return x;
 }
 
-/** Output rounds down (the new reserve rounds up), so `k` never shrinks. */
+/** Returns the constant-product output for `amountIn`, rounded down. Throws `RangeError` on a zero
+ *  reserve, a zero `amountIn`, a zero output, or an output past u64. */
 export function calculateOutput(
 	reserveIn: bigint,
 	reserveOut: bigint,
@@ -169,7 +171,8 @@ export function calculateOutput(
 	return assertU64('calculateOutput', amountOut);
 }
 
-/** Required input rounds up so the user pays enough. */
+/** Returns the input needed for `amountOut`, rounded up. Throws `RangeError` on a zero reserve, a zero
+ *  `amountOut`, an `amountOut` not below `reserveOut`, or an input past u64. */
 export function calculateInputForOutput(
 	reserveIn: bigint,
 	reserveOut: bigint,
@@ -207,7 +210,7 @@ interface BaseQuoteParams {
 	baseFee?: MintFee;
 }
 
-/** Launchpad only: `bondingCurve.realBaseReserves`. A DEX pool has no cap. */
+/** `baseReserveCap` is `bondingCurve.realBaseReserves`. A DEX pool has no cap. */
 interface BaseReserveCap {
 	baseReserveCap?: bigint;
 }
@@ -234,7 +237,7 @@ function ammBuyExactOut(
 		throw new RangeError('buyExactOut: invalid feeBps');
 	}
 
-	// A `feeBps` near 10_000 amplifies the leg up to 10_000x, so this can overflow u64.
+	// A `feeBps` near 10_000 multiplies the leg by up to 10_000, so this can pass u64.
 	const totalQuote = assertU64(
 		'buyExactOut',
 		ceilDiv(quoteBeforeFee * BPS_DIVISOR, divisor),
@@ -251,7 +254,7 @@ function ammBuyExactIn(
 	params: { reserveQuote: bigint; reserveBase: bigint; feeBps: number },
 	quoteAmountIn: bigint,
 ): AmmLegs {
-	// Fee comes off before the swap; the net rounds down, so the fee keeps the remainder.
+	// The fee comes off before the swap. The net rounds down, and the fee takes the remainder.
 	const netFactor = BPS_DIVISOR - BigInt(params.feeBps);
 	if (netFactor <= 0n) {
 		throw new RangeError('buyExactIn: invalid feeBps');
@@ -337,7 +340,9 @@ function buyQuote(
 	};
 }
 
-/** Guard with `calculateSlippageUp(quoteAmount, bps)`; it already carries the quote mint's cut. */
+/** Quotes a buy where the buyer receives `baseAmountOut`. With `baseReserveCap`, the vault sends at
+ *  most the cap. Guard with `calculateSlippageUp(quoteAmount, bps)`. `quoteAmount` includes the quote
+ *  mint's transfer fee. */
 export function buyExactOut(
 	params: BaseQuoteParams & BaseReserveCap & { baseAmountOut: bigint },
 ): BuyQuote {
@@ -352,7 +357,7 @@ export function buyExactOut(
 		cap !== undefined && baseOutOfVault > cap ? cap : baseOutOfVault;
 
 	const legs = ammBuyExactOut(params, baseAmount);
-	// The priced total must land, so the user is debited more than it.
+	// The priced total must reach the vault, so the user sends it grossed up.
 	const quoteFromUser = grossUp(legs.quoteAmount, params.quoteFee);
 
 	return buyQuote(
@@ -362,7 +367,8 @@ export function buyExactOut(
 	);
 }
 
-/** Guard with `calculateSlippageDown(baseToUser, bps)`, not `baseAmount`: the program bounds what the buyer nets. */
+/** Quotes a buy that spends `quoteAmountIn`. Guard with `calculateSlippageDown(baseToUser, bps)`, not
+ *  `baseAmount`. The program checks the minimum against what the buyer receives. */
 export function buyExactIn(
 	params: BaseQuoteParams & BaseReserveCap & { quoteAmountIn: bigint },
 ): BuyQuote {
@@ -371,7 +377,7 @@ export function buyExactIn(
 		throw new RangeError('buyExactIn: invalid amount');
 	}
 
-	// The AMM only ever prices what reaches the vault.
+	// The AMM prices only what reaches the vault.
 	const quoteIntoVault = amountAfterFee(
 		params.quoteAmountIn,
 		params.quoteFee,
@@ -382,7 +388,7 @@ export function buyExactIn(
 
 	const uncapped = ammBuyExactIn(params, quoteIntoVault);
 
-	// Capped: re-price exact-out at the cap and gross up; clamping the base output overstates the quote leg.
+	// Over the cap: price exact-out at the cap, then gross up. Clamping the base output alone overstates the quote leg.
 	const cap = params.baseReserveCap;
 	if (cap === undefined || uncapped.baseAmount <= cap) {
 		return buyQuote(
@@ -402,7 +408,7 @@ export function buyExactIn(
 	);
 }
 
-/** Guard with `calculateSlippageDown(quoteToUser, bps)`, not `quoteAmount`. */
+/** Quotes a sell of `baseAmountIn`. Guard with `calculateSlippageDown(quoteToUser, bps)`, not `quoteAmount`. */
 export function sellExactIn(
 	params: BaseQuoteParams & { baseAmountIn: bigint },
 ): SellQuote {
@@ -417,7 +423,7 @@ export function sellExactIn(
 	}
 
 	const legs = ammSellExactIn(params, baseIntoVault);
-	// `feeOn`, never `grossUp`: the AMM's output leaves the vault as priced.
+	// `feeOn`, not `grossUp`: the AMM's output leaves the vault as priced.
 	const quoteTransferFee = feeOn(legs.quoteAmount, params.quoteFee);
 
 	return {
@@ -431,7 +437,8 @@ export function sellExactIn(
 	};
 }
 
-/** Guard with `calculateSlippageUp(baseFromUser, bps)`, which already carries the base mint's cut. */
+/** Quotes a sell where the seller receives `quoteAmountOut`. Guard with
+ *  `calculateSlippageUp(baseFromUser, bps)`. `baseFromUser` includes the base mint's transfer fee. */
 export function sellExactOut(
 	params: BaseQuoteParams & { quoteAmountOut: bigint },
 ): SellQuote {
@@ -478,7 +485,7 @@ export function calculateSlippageDown(
 	);
 }
 
-/** Floors, as the program's `isqrt` does. */
+/** Returns `sqrt(quoteAmount * baseAmount)`, rounded down. */
 export function calculateInitialLp(
 	quoteAmount: bigint,
 	baseAmount: bigint,
@@ -486,7 +493,7 @@ export function calculateInitialLp(
 	return sqrtBigInt(quoteAmount * baseAmount);
 }
 
-/** Floating-point quote per base, for display only. */
+/** Returns the price of one base token in quote tokens, as a float. For display only. */
 export function calculatePrice(params: {
 	quoteReserves: bigint;
 	baseReserves: bigint;
@@ -499,7 +506,7 @@ export function calculatePrice(params: {
 	return rawRatio * 10 ** (baseDecimals - quoteDecimals);
 }
 
-/** Market cap in raw quote-token units. */
+/** Returns the market cap in raw quote units. */
 export function calculateMarketCap(params: {
 	quoteReserves: bigint;
 	baseReserves: bigint;

package/src/math/fee-decay.ts

@@ -1,6 +1,7 @@
 import { ceilDiv } from './internal.js';
 
-/** Premium in bps, rounded up. */
+/** Returns the fee decay premium in bps, rounded up. The premium falls quadratically from
+ *  `decayStartBps - standardFeeBps` at creation to 0 after `decaySeconds`. */
 export function calculateFeeDecayPremium(params: {
 	currentTimestamp: bigint;
 	createdAtTimestamp: bigint;
@@ -23,7 +24,7 @@ export function calculateFeeDecayPremium(params: {
 	const standardBps = BigInt(standardFeeBps);
 	const decaySecondsBig = BigInt(decaySeconds);
 
-	// Future creation timestamps pay the full premium, not a discount.
+	// A creation time in the future pays the full premium.
 	if (createdAtTimestamp > currentTimestamp) {
 		if (startBps <= standardBps) return 0n;
 		return startBps - standardBps;

package/src/math/fees.ts

@@ -10,11 +10,13 @@ export interface FeeSplit {
 	protocol: bigint;
 	lp: bigint;
 	creator: bigint;
-	/** Decay share already included in `protocol`, not a separate payout. */
+	/** The decay premium share. `protocol` includes it. It is not a separate payout. */
 	sniper: bigint;
 }
 
-/** LP/creator round down; protocol absorbs the decay premium and all remainders. */
+/** Splits `feeAmount` into protocol, LP and creator shares. LP and creator round down. Protocol gets
+ *  the decay premium and all remainders. Throws `RangeError` on a negative or non-integer input,
+ *  a zero total bps, or `protocolBps + lpBps` above `baseTotalBps`. */
 export function splitFeeAmount(args: FeeSplitArgs): FeeSplit {
 	const { feeAmount } = args;
 	const protocolBps = toBps(args.protocolBps, 'protocolBps');

package/src/math/internal.ts

@@ -2,7 +2,7 @@ export function floorDiv(a: bigint, b: bigint): bigint {
 	return a / b;
 }
 
-// Assumes non-negative inputs.
+// Inputs must be non-negative.
 export function ceilDiv(a: bigint, b: bigint): bigint {
 	return a / b + (a % b > 0n ? 1n : 0n);
 }

package/src/nexus/fee-helpers.ts

@@ -8,7 +8,8 @@ import { findPartnerConfigPda } from './generated/pdas/partnerConfig.js';
 import type { DexFees } from './generated/types/dexFees.js';
 import type { LaunchpadFees } from './generated/types/launchpadFees.js';
 
-/** Throws if the pair is unregistered. Take `platformConfig` from the market being priced: a partner's fees differ per platform. */
+/** Fetches the `PartnerConfig` of `partner` on `platformConfig`. Throws if it does not exist.
+ *  Use the `platformConfig` of the market you price. A partner's fees differ per platform. */
 export async function fetchPartnerFees(
 	rpc: Rpc<GetAccountInfoApi>,
 	partner: Address,
@@ -27,8 +28,9 @@ export async function fetchPartnerFees(
 	return maybeAccount.data;
 }
 
-/** The `feeBps` a trade pays: the standard rate plus the decay premium from the market's
- *  `createdAt`. Pass `fees.launchpad` for a curve, `fees.dex` for a pool; times in unix seconds. */
+/** Returns the `feeBps` a trade pays: the standard rate plus the decay premium. `schedule` is the
+ *  `PartnerConfig`'s `launchpad` for a curve or `dex` for a pool. `createdAt` is the curve's or
+ *  pool's `createdAt`. Both times are in unix seconds. */
 export function effectiveFeeBps(
 	schedule: LaunchpadFees | DexFees,
 	createdAt: bigint,