@send-fun/sdk 1.1.0 → 2.0.0

package/src/nexus/generated/errors/sendNexus.ts

@@ -98,12 +98,16 @@ export const SEND_NEXUS_ERROR__USER_TOKEN_ACCOUNT_WRONG_MINT = 0x1b61; // 7009
 export const SEND_NEXUS_ERROR__USER_TOKEN_ACCOUNT_WRONG_AUTHORITY = 0x1b62; // 7010
 /** NothingToClaim: Nothing to claim */
 export const SEND_NEXUS_ERROR__NOTHING_TO_CLAIM = 0x1b63; // 7011
-/** InvalidCreatorId: Creator identity is not a decodable wallet address */
-export const SEND_NEXUS_ERROR__INVALID_CREATOR_ID = 0x1b64; // 7012
+/** Unused7012: Unused */
+export const SEND_NEXUS_ERROR__UNUSED7012 = 0x1b64; // 7012
 /** QuoteMintPriceUnset: Quote mint has no USDC price on its nexus reward state */
 export const SEND_NEXUS_ERROR__QUOTE_MINT_PRICE_UNSET = 0x1b65; // 7013
 /** TransferFeeNotSettleable: Token-2022 transfer fee schedule cannot settle the exact amount */
 export const SEND_NEXUS_ERROR__TRANSFER_FEE_NOT_SETTLEABLE = 0x1b66; // 7014
+/** CreatorFeeTooHigh: Creator fee exceeds the partner's maximum */
+export const SEND_NEXUS_ERROR__CREATOR_FEE_TOO_HIGH = 0x1b67; // 7015
+/** CreatorFeeModeNotAllowed: Creator fee mode is not allowed by the partner config */
+export const SEND_NEXUS_ERROR__CREATOR_FEE_MODE_NOT_ALLOWED = 0x1b68; // 7016
 /** InsufficientLiquidity: Insufficient liquidity */
 export const SEND_NEXUS_ERROR__INSUFFICIENT_LIQUIDITY = 0x1bbc; // 7100
 /** InvalidAmount: Invalid amount */
@@ -112,6 +116,8 @@ export const SEND_NEXUS_ERROR__INVALID_AMOUNT = 0x1bbd; // 7101
 export type SendNexusError =
 	| typeof SEND_NEXUS_ERROR__AMBIGUOUS_FEE_SOURCE
 	| typeof SEND_NEXUS_ERROR__ARITHMETIC_OVERFLOW
+	| typeof SEND_NEXUS_ERROR__CREATOR_FEE_MODE_NOT_ALLOWED
+	| typeof SEND_NEXUS_ERROR__CREATOR_FEE_TOO_HIGH
 	| typeof SEND_NEXUS_ERROR__DUPLICATE_AUTH_PLATFORM_NAME
 	| typeof SEND_NEXUS_ERROR__INSUFFICIENT_LIQUIDITY
 	| typeof SEND_NEXUS_ERROR__INSUFFICIENT_STAKE
@@ -119,7 +125,6 @@ export type SendNexusError =
 	| typeof SEND_NEXUS_ERROR__INVALID_AUTHORITY
 	| typeof SEND_NEXUS_ERROR__INVALID_AUTH_PLATFORM_INDEX
 	| typeof SEND_NEXUS_ERROR__INVALID_AUTH_PLATFORM_NAME
-	| typeof SEND_NEXUS_ERROR__INVALID_CREATOR_ID
 	| typeof SEND_NEXUS_ERROR__INVALID_DESTINATION
 	| typeof SEND_NEXUS_ERROR__INVALID_FEE_PRESET
 	| typeof SEND_NEXUS_ERROR__INVALID_MINT
@@ -153,6 +158,7 @@ export type SendNexusError =
 	| typeof SEND_NEXUS_ERROR__TOO_MANY_AUTH_PLATFORMS
 	| typeof SEND_NEXUS_ERROR__TRANSFER_FEE_NOT_SETTLEABLE
 	| typeof SEND_NEXUS_ERROR__UNAUTHORIZED
+	| typeof SEND_NEXUS_ERROR__UNUSED7012
 	| typeof SEND_NEXUS_ERROR__USER_TOKEN_ACCOUNT_INVALID
 	| typeof SEND_NEXUS_ERROR__USER_TOKEN_ACCOUNT_WRONG_AUTHORITY
 	| typeof SEND_NEXUS_ERROR__USER_TOKEN_ACCOUNT_WRONG_MINT
@@ -161,6 +167,8 @@ export type SendNexusError =
 export const sendNexusErrorMessages: Record<SendNexusError, string> = {
 	[SEND_NEXUS_ERROR__AMBIGUOUS_FEE_SOURCE]: `Cannot specify both fee_preset and custom_fees`,
 	[SEND_NEXUS_ERROR__ARITHMETIC_OVERFLOW]: `Arithmetic overflow`,
+	[SEND_NEXUS_ERROR__CREATOR_FEE_MODE_NOT_ALLOWED]: `Creator fee mode is not allowed by the partner config`,
+	[SEND_NEXUS_ERROR__CREATOR_FEE_TOO_HIGH]: `Creator fee exceeds the partner's maximum`,
 	[SEND_NEXUS_ERROR__DUPLICATE_AUTH_PLATFORM_NAME]: `Duplicate auth platform name`,
 	[SEND_NEXUS_ERROR__INSUFFICIENT_LIQUIDITY]: `Insufficient liquidity`,
 	[SEND_NEXUS_ERROR__INSUFFICIENT_STAKE]: `Insufficient stake balance`,
@@ -168,7 +176,6 @@ export const sendNexusErrorMessages: Record<SendNexusError, string> = {
 	[SEND_NEXUS_ERROR__INVALID_AUTHORITY]: `Invalid authority`,
 	[SEND_NEXUS_ERROR__INVALID_AUTH_PLATFORM_INDEX]: `Invalid auth platform index`,
 	[SEND_NEXUS_ERROR__INVALID_AUTH_PLATFORM_NAME]: `Invalid auth platform name`,
-	[SEND_NEXUS_ERROR__INVALID_CREATOR_ID]: `Creator identity is not a decodable wallet address`,
 	[SEND_NEXUS_ERROR__INVALID_DESTINATION]: `Invalid destination account`,
 	[SEND_NEXUS_ERROR__INVALID_FEE_PRESET]: `Invalid fee configuration`,
 	[SEND_NEXUS_ERROR__INVALID_MINT]: `Invalid mint`,
@@ -202,6 +209,7 @@ export const sendNexusErrorMessages: Record<SendNexusError, string> = {
 	[SEND_NEXUS_ERROR__TOO_MANY_AUTH_PLATFORMS]: `Too many auth platforms (max 255)`,
 	[SEND_NEXUS_ERROR__TRANSFER_FEE_NOT_SETTLEABLE]: `Token-2022 transfer fee schedule cannot settle the exact amount`,
 	[SEND_NEXUS_ERROR__UNAUTHORIZED]: `Unauthorized`,
+	[SEND_NEXUS_ERROR__UNUSED7012]: `Unused`,
 	[SEND_NEXUS_ERROR__USER_TOKEN_ACCOUNT_INVALID]: `User token account is not an initialized token account`,
 	[SEND_NEXUS_ERROR__USER_TOKEN_ACCOUNT_WRONG_AUTHORITY]: `User token account is not owned by the trading user`,
 	[SEND_NEXUS_ERROR__USER_TOKEN_ACCOUNT_WRONG_MINT]: `User token account mint does not match the trade`,

package/src/nexus/generated/index.ts

@@ -14,4 +14,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/nexus/generated/pdas/index.ts

@@ -7,7 +7,6 @@
  */
 
 export * from './altRegistry.js';
-export * from './creatorFeeConfig.js';
 export * from './defaultFeePreset.js';
 export * from './defaultPartner.js';
 export * from './defaultPartnerMetadata.js';

package/src/nexus/generated/plugins/sendNexus.ts

@@ -23,11 +23,9 @@ import {
 } from '@solana/kit/program-client-core';
 import {
 	fetchAllAltRegistry,
-	fetchAllCreatorFeeConfig,
 	fetchAllFeePreset,
 	fetchAllGlobalConfig,
 	fetchAllMaybeAltRegistry,
-	fetchAllMaybeCreatorFeeConfig,
 	fetchAllMaybeFeePreset,
 	fetchAllMaybeGlobalConfig,
 	fetchAllMaybePartnerConfig,
@@ -43,11 +41,9 @@ import {
 	fetchAllUserRewardDebt,
 	fetchAllUserStakePosition,
 	fetchAltRegistry,
-	fetchCreatorFeeConfig,
 	fetchFeePreset,
 	fetchGlobalConfig,
 	fetchMaybeAltRegistry,
-	fetchMaybeCreatorFeeConfig,
 	fetchMaybeFeePreset,
 	fetchMaybeGlobalConfig,
 	fetchMaybePartnerConfig,
@@ -63,7 +59,6 @@ import {
 	fetchUserRewardDebt,
 	fetchUserStakePosition,
 	getAltRegistryCodec,
-	getCreatorFeeConfigCodec,
 	getFeePresetCodec,
 	getGlobalConfigCodec,
 	getPartnerConfigCodec,
@@ -75,8 +70,6 @@ import {
 	identifySendNexusAccount,
 	type AltRegistry,
 	type AltRegistryArgs,
-	type CreatorFeeConfig,
-	type CreatorFeeConfigArgs,
 	type FeePreset,
 	type FeePresetArgs,
 	type GlobalConfig,
@@ -115,7 +108,6 @@ import {
 } from '../instructions/index.js';
 import {
 	findAltRegistryPda,
-	findCreatorFeeConfigPda,
 	findDefaultFeePresetPda,
 	findDefaultPartnerMetadataPda,
 	findDefaultPartnerPda,
@@ -143,8 +135,6 @@ export type SendNexusPlugin = {
 export type SendNexusPluginAccounts = {
 	altRegistry: ReturnType<typeof getAltRegistryCodec> &
 		SelfFetchFunctions<AltRegistryArgs, AltRegistry>;
-	creatorFeeConfig: ReturnType<typeof getCreatorFeeConfigCodec> &
-		SelfFetchFunctions<CreatorFeeConfigArgs, CreatorFeeConfig>;
 	feePreset: ReturnType<typeof getFeePresetCodec> &
 		SelfFetchFunctions<FeePresetArgs, FeePreset>;
 	globalConfig: ReturnType<typeof getGlobalConfigCodec> &
@@ -203,7 +193,6 @@ export type SendNexusPluginPdas = {
 	userStakePosition: typeof findUserStakePositionPda;
 	userRewardDebt: typeof findUserRewardDebtPda;
 	eventAuthority: typeof findEventAuthorityPda;
-	creatorFeeConfig: typeof findCreatorFeeConfigPda;
 	altRegistry: typeof findAltRegistryPda;
 };
 
@@ -236,29 +225,6 @@ export function sendNexusProgram() {
 						fetchMaybe: (address, config) =>
 							fetchMaybeAltRegistry(client.rpc, address, config),
 					}),
-					creatorFeeConfig: Object.freeze({
-						...getCreatorFeeConfigCodec(),
-						fetch: (address, config) =>
-							fetchCreatorFeeConfig(client.rpc, address, config),
-						fetchAll: (addresses, config) =>
-							fetchAllCreatorFeeConfig(
-								client.rpc,
-								addresses,
-								config,
-							),
-						fetchAllMaybe: (addresses, config) =>
-							fetchAllMaybeCreatorFeeConfig(
-								client.rpc,
-								addresses,
-								config,
-							),
-						fetchMaybe: (address, config) =>
-							fetchMaybeCreatorFeeConfig(
-								client.rpc,
-								address,
-								config,
-							),
-					}),
 					feePreset: Object.freeze({
 						...getFeePresetCodec(),
 						fetch: (address, config) =>
@@ -480,7 +446,6 @@ export function sendNexusProgram() {
 					userStakePosition: findUserStakePositionPda,
 					userRewardDebt: findUserRewardDebtPda,
 					eventAuthority: findEventAuthorityPda,
-					creatorFeeConfig: findCreatorFeeConfigPda,
 					altRegistry: findAltRegistryPda,
 				},
 				identifyAccount: identifySendNexusAccount,

package/src/nexus/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/nexus/generated/types/dexFees.ts

@@ -23,7 +23,7 @@ export type DexFees = {
 	creationFeeCents: bigint;
 	protocolFeeBps: number;
 	lpFeeBps: number;
-	creatorFeeBps: number;
+	maxCreatorFeeBps: number;
 	feeDecaySeconds: number;
 	feeDecayStartBps: number;
 };
@@ -32,7 +32,7 @@ export type DexFeesArgs = {
 	creationFeeCents: number | bigint;
 	protocolFeeBps: number;
 	lpFeeBps: number;
-	creatorFeeBps: number;
+	maxCreatorFeeBps: number;
 	feeDecaySeconds: number;
 	feeDecayStartBps: number;
 };
@@ -42,7 +42,7 @@ export function getDexFeesEncoder(): FixedSizeEncoder<DexFeesArgs> {
 		['creationFeeCents', getU64Encoder()],
 		['protocolFeeBps', getU16Encoder()],
 		['lpFeeBps', getU16Encoder()],
-		['creatorFeeBps', getU16Encoder()],
+		['maxCreatorFeeBps', getU16Encoder()],
 		['feeDecaySeconds', getU16Encoder()],
 		['feeDecayStartBps', getU16Encoder()],
 	]);
@@ -53,7 +53,7 @@ export function getDexFeesDecoder(): FixedSizeDecoder<DexFees> {
 		['creationFeeCents', getU64Decoder()],
 		['protocolFeeBps', getU16Decoder()],
 		['lpFeeBps', getU16Decoder()],
-		['creatorFeeBps', getU16Decoder()],
+		['maxCreatorFeeBps', getU16Decoder()],
 		['feeDecaySeconds', getU16Decoder()],
 		['feeDecayStartBps', getU16Decoder()],
 	]);

package/src/nexus/generated/types/index.ts

@@ -7,7 +7,6 @@
  */
 
 export * from './authPlatformEntry.js';
-export * from './callerType.js';
 export * from './dexFees.js';
 export * from './feeConfig.js';
 export * from './launchpadFees.js';

package/src/nexus/generated/types/launchpadFees.ts

@@ -22,7 +22,7 @@ import {
 export type LaunchpadFees = {
 	creationFeeCents: bigint;
 	protocolFeeBps: number;
-	creatorFeeBps: number;
+	maxCreatorFeeBps: number;
 	feeDecaySeconds: number;
 	feeDecayStartBps: number;
 };
@@ -30,7 +30,7 @@ export type LaunchpadFees = {
 export type LaunchpadFeesArgs = {
 	creationFeeCents: number | bigint;
 	protocolFeeBps: number;
-	creatorFeeBps: number;
+	maxCreatorFeeBps: number;
 	feeDecaySeconds: number;
 	feeDecayStartBps: number;
 };
@@ -39,7 +39,7 @@ export function getLaunchpadFeesEncoder(): FixedSizeEncoder<LaunchpadFeesArgs> {
 	return getStructEncoder([
 		['creationFeeCents', getU64Encoder()],
 		['protocolFeeBps', getU16Encoder()],
-		['creatorFeeBps', getU16Encoder()],
+		['maxCreatorFeeBps', getU16Encoder()],
 		['feeDecaySeconds', getU16Encoder()],
 		['feeDecayStartBps', getU16Encoder()],
 	]);
@@ -49,7 +49,7 @@ export function getLaunchpadFeesDecoder(): FixedSizeDecoder<LaunchpadFees> {
 	return getStructDecoder([
 		['creationFeeCents', getU64Decoder()],
 		['protocolFeeBps', getU16Decoder()],
-		['creatorFeeBps', getU16Decoder()],
+		['maxCreatorFeeBps', getU16Decoder()],
 		['feeDecaySeconds', getU16Decoder()],
 		['feeDecayStartBps', getU16Decoder()],
 	]);

package/src/nexus/staking.ts

@@ -17,6 +17,7 @@ import {
 } from '../constants.js';
 import { fetchInChunks } from '../utils/chunk.js';
 import { findAssociatedTokenPda } from '../utils/pda.js';
+import { accountIsCreated } from './generated/shared/index.js';
 import { fetchStakingConfig } from './generated/accounts/stakingConfig.js';
 import {
 	fetchMaybeUserStakePosition,
@@ -42,10 +43,10 @@ import { findRewardAccrualPda as findLaunchpadRewardAccrualPda } from '../launch
 import { getRewardAccrualDecoder } from '../launchpad/generated/accounts/rewardAccrual.js';
 import { findRewardAccrualPda as findDexRewardAccrualPda } from '../dex/generated/pdas/rewardAccrual.js';
 
-// 1e12 scale of `RewardAccrual.accPerToken` on both programs; must match send_shared `PRECISION`.
+// Fixed-point scale of `RewardAccrual.accPerToken` in both programs.
 const PRECISION = 1_000_000_000_000n;
 
-/** `getProgramAccounts` is optional: many providers restrict it and LiteSVM lacks it, so pass `rewardMints` there. */
+/** An RPC with `getAccountInfo` and, optionally, `getProgramAccounts`. Without `getProgramAccounts`, pass `rewardMints`. */
 export type RewardMintRpc = Rpc<GetAccountInfoApi> &
 	Partial<Rpc<GetProgramAccountsApi>>;
 
@@ -55,7 +56,7 @@ function hasProgramAccounts(
 	return typeof rpc.getProgramAccounts === 'function';
 }
 
-// On-chain body offsets + 8 for the discriminator; pinned by tests/staking.test.ts.
+// Field offsets, including the 8-byte discriminator. tests/staking.test.ts pins them.
 const REWARD_STATE_STAKING_CONFIG_OFFSET = 10n;
 const REWARD_STATE_REWARD_MINT_OFFSET = 42;
 
@@ -65,9 +66,8 @@ function compareAddresses(a: Address, b: Address): number {
 	return 0;
 }
 
-/** Registered reward mints, sorted by address. Includes disabled mints: their accrued balance is
- *  still owed and the settle gate still counts them. Throws when the sweep disagrees with
- *  `StakingConfig.rewardCount` rather than settle a short list. */
+/** Returns every registered reward mint, disabled mints included, sorted by address.
+ *  Throws if the count differs from `StakingConfig.rewardCount`. */
 export async function getRewardMints(
 	rpc: Rpc<GetAccountInfoApi> & Rpc<GetProgramAccountsApi>,
 ): Promise<readonly Address[]> {
@@ -98,7 +98,7 @@ export async function getRewardMints(
 	const mints: Address[] = [];
 	for (const { account } of accounts) {
 		const data = base64.encode(account.data[0]);
-		// Another nexus account of the same size could pass both filters.
+		// Another nexus account of the same size can pass both filters.
 		if (!containsBytes(data, REWARD_STATE_DISCRIMINATOR, 0)) continue;
 		mints.push(
 			addressDecoder.decode(data, REWARD_STATE_REWARD_MINT_OFFSET),
@@ -136,13 +136,14 @@ async function resolveRewardMints(
 }
 
 export interface SettleParams {
-	/** `settle` is permissionless: the user does not sign. */
+	/** Does not sign. `settle` is permissionless. */
 	user: Address;
 	payer: TransactionSigner;
 	stakingMint: Address;
 }
 
-/** One idempotent `settle` per mint; a partial mint list leaves `stake` and `unstake` failing `RewardsNotSettled`. */
+/** Builds one `settle` per reward mint. `source` is the mint list, or an RPC to read it from.
+ *  `settle` is idempotent. With a partial list, `stake` and `unstake` fail with `RewardsNotSettled`. */
 export async function buildSettleInstructions(
 	source: RewardMintSource,
 	params: SettleParams,
@@ -187,7 +188,7 @@ export async function fetchMissingUserRewardDebts(
 
 	const missingMints: Address[] = [];
 	for (const [index, rewardMint] of rewardMints.entries()) {
-		if (!encodedAccounts[index].exists) {
+		if (!accountIsCreated(encodedAccounts[index])) {
 			missingMints.push(rewardMint);
 		}
 	}
@@ -199,16 +200,17 @@ export interface PrepareStakingParams {
 	user: Address;
 	payer: TransactionSigner;
 	stakingMint: Address;
-	/** Must be the full registry when supplied; a subset leaves `stake` and `unstake` blocked. */
+	/** If given, must hold every registered mint. With a subset, `stake` and `unstake` fail. */
 	rewardMints?: readonly Address[];
 }
 
-/** Opens missing `UserRewardDebt`s, then settles every mint; the user never signs, so the stake or unstake after is one wallet prompt. */
+/** Builds a `create_user_reward_debt` for each missing `UserRewardDebt`, then a `settle` for every
+ *  reward mint. The user does not sign these instructions. */
 export async function buildStakingPreflightInstructions(
 	rpc: RewardMintRpc & Rpc<GetMultipleAccountsApi>,
 	params: PrepareStakingParams,
 ): Promise<Instruction[]> {
-	// One sweep for both halves: two sweeps can disagree.
+	// Read the mints once. Two reads can return different lists.
 	const rewardMints = await resolveRewardMints(rpc, params.rewardMints);
 
 	const missingMints = await fetchMissingUserRewardDebts(
@@ -234,7 +236,7 @@ export async function buildStakingPreflightInstructions(
 	return [...createIxs, ...settleIxs];
 }
 
-/** True once `stake` and `unstake` will pass the `settledCount == rewardCount` gate. */
+/** Returns true if `stake` and `unstake` pass the `settledCount == rewardCount` check. */
 export async function isFullySettled(
 	rpc: Rpc<GetAccountInfoApi>,
 	user: Address,
@@ -255,7 +257,8 @@ export interface StakeParams {
 	amount: bigint;
 }
 
-/** Fails `RewardsNotSettled` until every mint is settled at the current `stakeVersion`; run `buildStakingPreflightInstructions` first. */
+/** The instruction fails with `RewardsNotSettled` until every mint is settled at the current
+ *  `stakeVersion`. Run `buildStakingPreflightInstructions` first. */
 export async function buildStakeInstruction(
 	params: StakeParams,
 ): Promise<Instruction> {
@@ -274,8 +277,9 @@ export interface UnstakeParams {
 	amount: bigint;
 }
 
-/** Settle immediately before via `buildStakingPreflightInstructions`: the gate passes on a stale settle,
- *  and the window since it is then paid at the post-unstake amount, forfeiting accrual. */
+/** Run `buildStakingPreflightInstructions` immediately before. The check also passes on an older
+ *  settle. Rewards since that settle then accrue on the smaller post-unstake amount, and the
+ *  difference is lost. */
 export async function buildUnstakeInstruction(
 	params: UnstakeParams,
 ): Promise<Instruction> {
@@ -291,12 +295,12 @@ export interface ClaimRewardsParams {
 	user: TransactionSigner;
 	payer?: TransactionSigner;
 	stakingMint: Address;
-	/** Defaults to every registered mint; each claim settles its own mint, so a subset needs no preflight. */
+	/** Defaults to every registered mint. A subset needs no preflight: each `claim` settles its own mint. */
 	rewardMints?: readonly Address[];
 }
 
-/** One `claim` per mint, preceded by `create_user_reward_debt` where the debt is missing:
- *  `Claim` requires the account to exist, so one missing debt fails the whole transaction. */
+/** Builds one `claim` per reward mint. A `create_user_reward_debt` comes before each `claim` whose
+ *  `UserRewardDebt` is missing: `claim` fails without it. Throws if a mint has no `RewardState`. */
 export async function buildClaimRewardsInstructions(
 	rpc: RewardMintRpc & Rpc<GetMultipleAccountsApi>,
 	params: ClaimRewardsParams,
@@ -337,7 +341,7 @@ export async function buildClaimRewardsInstructions(
 	const perMint = await Promise.all(
 		rewardMints.map(async (rewardMint, index) => {
 			const encodedRewardState = fetched[index];
-			if (!encodedRewardState.exists) {
+			if (!accountIsCreated(encodedRewardState)) {
 				throw new Error(`RewardState not found for mint ${rewardMint}`);
 			}
 			const { vault } = rewardStateDecoder.decode(
@@ -356,8 +360,8 @@ export async function buildClaimRewardsInstructions(
 
 			const instructions: Instruction[] = [];
 
-			// Directly before its own `claim`, so slicing the list by mint keeps each pair together.
-			if (!fetched[rewardMints.length * 2 + index].exists) {
+			// Directly before its own `claim`, so a split of the list by mint keeps each pair together.
+			if (!accountIsCreated(fetched[rewardMints.length * 2 + index])) {
 				instructions.push(
 					await getCreateUserRewardDebtInstructionAsync({
 						user: params.user.address,
@@ -395,12 +399,13 @@ export interface WithdrawFeesAccounts {
 	tokenProgram: Address;
 }
 
-/** Accounts for one mint's `withdraw_fees`; call once per mint. */
+/** Returns the accounts of `withdraw_fees` for one reward mint. Without `tokenProgram`, reads it
+ *  from the mint account. Throws if that account does not exist. */
 export async function buildWithdrawFeesAccounts(
 	rpc: Rpc<GetAccountInfoApi>,
 	params: {
 		rewardMint: Address;
-		/** Wallet, not token account: its ATA is derived. */
+		/** A wallet, not a token account. The SDK derives its ATA. */
 		destination: Address;
 		tokenProgram?: Address;
 	},
@@ -467,13 +472,12 @@ export async function fetchUserStakePositionData(
 	return maybePosition.exists ? maybePosition.data : null;
 }
 
-/** Unbound reads as `Pubkey::default()` (the system program address), which `bind_staking_mint`
- *  can never store: it requires a token mint. */
+/** Returns false for the system program address, the value of an unbound staking mint. */
 export function isStakingMintBound(stakingMint: Address): boolean {
 	return stakingMint !== SYSTEM_PROGRAM_ADDRESS;
 }
 
-/** The staking mint is immutable once bound, so this result is safe to cache. */
+/** Returns the staking mint. Throws if no staking mint is bound. A bound staking mint cannot change. */
 export async function fetchSendMint(
 	rpc: Rpc<GetAccountInfoApi>,
 ): Promise<Address> {
@@ -488,13 +492,14 @@ export async function fetchSendMint(
 
 export interface PendingReward {
 	rewardMint: Address;
-	/** Base units of `rewardMint` debited at the vault (matches `ClaimEvent.amount`); a
-	 *  `TransferFeeConfig` mint delivers less -- net it with `transferFee.fetchMintFees`. */
+	/** Amount the vault sends, in raw units of `rewardMint`. Equals `ClaimEvent.amount`. A mint with a
+	 *  transfer fee delivers less. Get the fee with `transferFee.fetchMintFees`. */
 	pending: bigint;
 }
 
-/** One entry per reward mint, in `knownRewardMints` order, else sorted by address. Each amount is in
- *  its own mint's base units, so never sum them, and is the vault's debit, not the claimant's credit. */
+/** Returns one entry per reward mint, in `knownRewardMints` order, else sorted by address. Each amount
+ *  is in the raw units of its own mint. Do not add them together. Each amount is what the vault sends,
+ *  before the mint's transfer fee. */
 export async function fetchPendingRewards(
 	rpc: RewardMintRpc & Rpc<GetMultipleAccountsApi>,
 	user: Address,
@@ -541,33 +546,32 @@ export async function fetchPendingRewards(
 	);
 
 	const userRewardDebtDecoder = getUserRewardDebtDecoder();
-	// One decoder for both: the two `RewardAccrual` types share shape and discriminator.
+	// One decoder for both: the two `RewardAccrual` types have the same layout and discriminator.
 	const rewardAccrualDecoder = getRewardAccrualDecoder();
 
 	return pdas.map(({ rewardMint }, index) => {
 		const base = index * 3;
 
 		const encodedDebt = encodedAccounts[base];
-		// A missing debt is not zero owed: `create_user_reward_debt` opens it at
-		// `accSnapshot = 0`, `amountSnapshot = position.amount`, and the claim pays that.
-		const debt = encodedDebt.exists
+		// A missing debt is not zero owed. `create_user_reward_debt` opens it at
+		// `accSnapshot = 0` and `amountSnapshot = position.amount`, and the claim pays from there.
+		const debt = accountIsCreated(encodedDebt)
 			? userRewardDebtDecoder.decode(encodedDebt.data)
 			: { owed: 0n, accSnapshot: 0n, amountSnapshot: stakeAmount };
 
 		const encodedLaunchpadAccrual = encodedAccounts[base + 1];
-		const launchpadAcc = encodedLaunchpadAccrual.exists
+		const launchpadAcc = accountIsCreated(encodedLaunchpadAccrual)
 			? rewardAccrualDecoder.decode(encodedLaunchpadAccrual.data)
 					.accPerToken
 			: 0n;
 
 		const encodedDexAccrual = encodedAccounts[base + 2];
-		const dexAcc = encodedDexAccrual.exists
+		const dexAcc = accountIsCreated(encodedDexAccrual)
 			? rewardAccrualDecoder.decode(encodedDexAccrual.data).accPerToken
 			: 0n;
 
-		// Mirrors `settle_debt`: basis is the smaller amount (`amountSnapshot` alone over-quotes
-		// after an unstake), floored once over the summed accumulators. A negative delta quotes 0
-		// where the program would fail.
+		// Matches `settle`: the basis is the smaller amount, floored once over the summed
+		// accumulators. A negative delta quotes 0, where the program fails.
 		const basis =
 			debt.amountSnapshot < stakeAmount
 				? debt.amountSnapshot

package/src/platform.ts

@@ -2,10 +2,10 @@ import { getProgramDerivedAddress } from '@solana/kit';
 import type { ProgramDerivedAddress } from '@solana/kit';
 import { SEND_NEXUS_PROGRAM_ADDRESS } from './nexus/generated/programs/index.js';
 
-/** A platform is only a key, with no on-chain account; it is a PDA so a platform account can later `init` at it. */
+/** Seed of the platform PDA. A platform has no on-chain account. */
 export const PLATFORM_SEED = 'platform';
 
-/** The name is the platform's identity: renaming one orphans every market and partner config under the old key. */
+/** Derives the platform key for `name` under the nexus program. Each name gives a different platform. */
 export async function findPlatformAddress(
 	name: string,
 ): Promise<ProgramDerivedAddress> {