@send-fun/sdk 1.1.0 → 1.2.0

package/src/nexus/generated/accounts/stakingConfig.ts

@@ -44,6 +44,7 @@ import {
 	type ReadonlyUint8Array,
 } from '@solana/kit';
 import { SEND_NEXUS_PROGRAM_ADDRESS } from '../programs/index.js';
+import { accountIsCreated } from '../shared/index.js';
 
 export const STAKING_CONFIG_DISCRIMINATOR: ReadonlyUint8Array = new Uint8Array([
 	45, 134, 252, 82, 37, 57, 84, 25,
@@ -115,9 +116,25 @@ export function getStakingConfigCodec(): FixedSizeCodec<
 	return combineCodec(getStakingConfigEncoder(), getStakingConfigDecoder());
 }
 
+/**
+ * Decodes a `StakingConfig` account, throwing when another program owns it or its discriminator
+ * does not match.
+ *
+ * Unlike {@link fetchMaybeStakingConfig}, 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 decodeStakingConfig<TAddress extends string = string>(
 	encodedAccount: EncodedAccount<TAddress>,
 ): Account<StakingConfig, TAddress>;
+/**
+ * Decodes a `StakingConfig` account, throwing when another program owns it or its discriminator
+ * does not match.
+ *
+ * Unlike {@link fetchMaybeStakingConfig}, 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 decodeStakingConfig<TAddress extends string = string>(
 	encodedAccount: MaybeEncodedAccount<TAddress>,
 ): MaybeAccount<StakingConfig, TAddress>;
@@ -148,6 +165,7 @@ export function decodeStakingConfig<TAddress extends string = string>(
 	);
 }
 
+/** Fetches a `StakingConfig` account, throwing when it does not exist or only holds lamports. */
 export async function fetchStakingConfig<TAddress extends string = string>(
 	rpc: Parameters<typeof fetchEncodedAccount>[0],
 	address: Address<TAddress>,
@@ -158,15 +176,25 @@ export async function fetchStakingConfig<TAddress extends string = string>(
 	return maybeAccount;
 }
 
+/**
+ * Fetches a `StakingConfig` account, or the non-existing variant when the address holds no
+ * account or only lamports (see {@link accountIsCreated}).
+ * {@link decodeStakingConfig} throws for a lamports-only account instead.
+ */
 export async function fetchMaybeStakingConfig<TAddress extends string = string>(
 	rpc: Parameters<typeof fetchEncodedAccount>[0],
 	address: Address<TAddress>,
 	config?: FetchAccountConfig,
 ): Promise<MaybeAccount<StakingConfig, TAddress>> {
 	const maybeAccount = await fetchEncodedAccount(rpc, address, config);
-	return decodeStakingConfig(maybeAccount);
+	return decodeStakingConfig(
+		accountIsCreated(maybeAccount)
+			? maybeAccount
+			: { address, exists: false },
+	);
 }
 
+/** Fetches `StakingConfig` accounts, throwing when any does not exist or only holds lamports. */
 export async function fetchAllStakingConfig(
 	rpc: Parameters<typeof fetchEncodedAccounts>[0],
 	addresses: Array<Address>,
@@ -181,6 +209,11 @@ export async function fetchAllStakingConfig(
 	return maybeAccounts;
 }
 
+/**
+ * Fetches `StakingConfig` accounts, with the non-existing variant for each address that holds
+ * no account or only lamports (see {@link accountIsCreated}).
+ * {@link decodeStakingConfig} throws for a lamports-only account instead.
+ */
 export async function fetchAllMaybeStakingConfig(
 	rpc: Parameters<typeof fetchEncodedAccounts>[0],
 	addresses: Array<Address>,
@@ -188,7 +221,11 @@ export async function fetchAllMaybeStakingConfig(
 ): Promise<MaybeAccount<StakingConfig>[]> {
 	const maybeAccounts = await fetchEncodedAccounts(rpc, addresses, config);
 	return maybeAccounts.map((maybeAccount) =>
-		decodeStakingConfig(maybeAccount),
+		decodeStakingConfig(
+			accountIsCreated(maybeAccount)
+				? maybeAccount
+				: { address: maybeAccount.address, exists: false },
+		),
 	);
 }
 

package/src/nexus/generated/accounts/userRewardDebt.ts

@@ -44,6 +44,7 @@ import {
 	type ReadonlyUint8Array,
 } from '@solana/kit';
 import { SEND_NEXUS_PROGRAM_ADDRESS } from '../programs/index.js';
+import { accountIsCreated } from '../shared/index.js';
 
 export const USER_REWARD_DEBT_DISCRIMINATOR: ReadonlyUint8Array =
 	new Uint8Array([92, 166, 184, 23, 127, 201, 251, 148]);
@@ -133,9 +134,25 @@ export function getUserRewardDebtCodec(): FixedSizeCodec<
 	return combineCodec(getUserRewardDebtEncoder(), getUserRewardDebtDecoder());
 }
 
+/**
+ * Decodes a `UserRewardDebt` account, throwing when another program owns it or its discriminator
+ * does not match.
+ *
+ * Unlike {@link fetchMaybeUserRewardDebt}, 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 decodeUserRewardDebt<TAddress extends string = string>(
 	encodedAccount: EncodedAccount<TAddress>,
 ): Account<UserRewardDebt, TAddress>;
+/**
+ * Decodes a `UserRewardDebt` account, throwing when another program owns it or its discriminator
+ * does not match.
+ *
+ * Unlike {@link fetchMaybeUserRewardDebt}, 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 decodeUserRewardDebt<TAddress extends string = string>(
 	encodedAccount: MaybeEncodedAccount<TAddress>,
 ): MaybeAccount<UserRewardDebt, TAddress>;
@@ -170,6 +187,7 @@ export function decodeUserRewardDebt<TAddress extends string = string>(
 	);
 }
 
+/** Fetches a `UserRewardDebt` account, throwing when it does not exist or only holds lamports. */
 export async function fetchUserRewardDebt<TAddress extends string = string>(
 	rpc: Parameters<typeof fetchEncodedAccount>[0],
 	address: Address<TAddress>,
@@ -180,6 +198,11 @@ export async function fetchUserRewardDebt<TAddress extends string = string>(
 	return maybeAccount;
 }
 
+/**
+ * Fetches a `UserRewardDebt` account, or the non-existing variant when the address holds no
+ * account or only lamports (see {@link accountIsCreated}).
+ * {@link decodeUserRewardDebt} throws for a lamports-only account instead.
+ */
 export async function fetchMaybeUserRewardDebt<
 	TAddress extends string = string,
 >(
@@ -188,9 +211,14 @@ export async function fetchMaybeUserRewardDebt<
 	config?: FetchAccountConfig,
 ): Promise<MaybeAccount<UserRewardDebt, TAddress>> {
 	const maybeAccount = await fetchEncodedAccount(rpc, address, config);
-	return decodeUserRewardDebt(maybeAccount);
+	return decodeUserRewardDebt(
+		accountIsCreated(maybeAccount)
+			? maybeAccount
+			: { address, exists: false },
+	);
 }
 
+/** Fetches `UserRewardDebt` accounts, throwing when any does not exist or only holds lamports. */
 export async function fetchAllUserRewardDebt(
 	rpc: Parameters<typeof fetchEncodedAccounts>[0],
 	addresses: Array<Address>,
@@ -205,6 +233,11 @@ export async function fetchAllUserRewardDebt(
 	return maybeAccounts;
 }
 
+/**
+ * Fetches `UserRewardDebt` accounts, with the non-existing variant for each address that holds
+ * no account or only lamports (see {@link accountIsCreated}).
+ * {@link decodeUserRewardDebt} throws for a lamports-only account instead.
+ */
 export async function fetchAllMaybeUserRewardDebt(
 	rpc: Parameters<typeof fetchEncodedAccounts>[0],
 	addresses: Array<Address>,
@@ -212,7 +245,11 @@ export async function fetchAllMaybeUserRewardDebt(
 ): Promise<MaybeAccount<UserRewardDebt>[]> {
 	const maybeAccounts = await fetchEncodedAccounts(rpc, addresses, config);
 	return maybeAccounts.map((maybeAccount) =>
-		decodeUserRewardDebt(maybeAccount),
+		decodeUserRewardDebt(
+			accountIsCreated(maybeAccount)
+				? maybeAccount
+				: { address: maybeAccount.address, exists: false },
+		),
 	);
 }
 

package/src/nexus/generated/accounts/userStakePosition.ts

@@ -44,6 +44,7 @@ import {
 	type ReadonlyUint8Array,
 } from '@solana/kit';
 import { SEND_NEXUS_PROGRAM_ADDRESS } from '../programs/index.js';
+import { accountIsCreated } from '../shared/index.js';
 
 export const USER_STAKE_POSITION_DISCRIMINATOR: ReadonlyUint8Array =
 	new Uint8Array([123, 46, 248, 17, 240, 135, 201, 17]);
@@ -124,9 +125,25 @@ export function getUserStakePositionCodec(): FixedSizeCodec<
 	);
 }
 
+/**
+ * Decodes a `UserStakePosition` account, throwing when another program owns it or its discriminator
+ * does not match.
+ *
+ * Unlike {@link fetchMaybeUserStakePosition}, 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 decodeUserStakePosition<TAddress extends string = string>(
 	encodedAccount: EncodedAccount<TAddress>,
 ): Account<UserStakePosition, TAddress>;
+/**
+ * Decodes a `UserStakePosition` account, throwing when another program owns it or its discriminator
+ * does not match.
+ *
+ * Unlike {@link fetchMaybeUserStakePosition}, 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 decodeUserStakePosition<TAddress extends string = string>(
 	encodedAccount: MaybeEncodedAccount<TAddress>,
 ): MaybeAccount<UserStakePosition, TAddress>;
@@ -163,6 +180,7 @@ export function decodeUserStakePosition<TAddress extends string = string>(
 	);
 }
 
+/** Fetches a `UserStakePosition` account, throwing when it does not exist or only holds lamports. */
 export async function fetchUserStakePosition<TAddress extends string = string>(
 	rpc: Parameters<typeof fetchEncodedAccount>[0],
 	address: Address<TAddress>,
@@ -177,6 +195,11 @@ export async function fetchUserStakePosition<TAddress extends string = string>(
 	return maybeAccount;
 }
 
+/**
+ * Fetches a `UserStakePosition` account, or the non-existing variant when the address holds no
+ * account or only lamports (see {@link accountIsCreated}).
+ * {@link decodeUserStakePosition} throws for a lamports-only account instead.
+ */
 export async function fetchMaybeUserStakePosition<
 	TAddress extends string = string,
 >(
@@ -185,9 +208,14 @@ export async function fetchMaybeUserStakePosition<
 	config?: FetchAccountConfig,
 ): Promise<MaybeAccount<UserStakePosition, TAddress>> {
 	const maybeAccount = await fetchEncodedAccount(rpc, address, config);
-	return decodeUserStakePosition(maybeAccount);
+	return decodeUserStakePosition(
+		accountIsCreated(maybeAccount)
+			? maybeAccount
+			: { address, exists: false },
+	);
 }
 
+/** Fetches `UserStakePosition` accounts, throwing when any does not exist or only holds lamports. */
 export async function fetchAllUserStakePosition(
 	rpc: Parameters<typeof fetchEncodedAccounts>[0],
 	addresses: Array<Address>,
@@ -202,6 +230,11 @@ export async function fetchAllUserStakePosition(
 	return maybeAccounts;
 }
 
+/**
+ * Fetches `UserStakePosition` accounts, with the non-existing variant for each address that holds
+ * no account or only lamports (see {@link accountIsCreated}).
+ * {@link decodeUserStakePosition} throws for a lamports-only account instead.
+ */
 export async function fetchAllMaybeUserStakePosition(
 	rpc: Parameters<typeof fetchEncodedAccounts>[0],
 	addresses: Array<Address>,
@@ -209,7 +242,11 @@ export async function fetchAllMaybeUserStakePosition(
 ): Promise<MaybeAccount<UserStakePosition>[]> {
 	const maybeAccounts = await fetchEncodedAccounts(rpc, addresses, config);
 	return maybeAccounts.map((maybeAccount) =>
-		decodeUserStakePosition(maybeAccount),
+		decodeUserStakePosition(
+			accountIsCreated(maybeAccount)
+				? maybeAccount
+				: { address: maybeAccount.address, exists: false },
+		),
 	);
 }
 

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/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/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> {