@send-fun/sdk 1.0.1 → 1.2.0

package/src/nexus/generated/instructions/settle.ts

@@ -40,7 +40,7 @@ import {
 	getAccountMetaFactory,
 	getAddressFromResolvedInstructionAccount,
 	type ResolvedInstructionAccount,
-} from '@solana/program-client-core';
+} from '@solana/kit/program-client-core';
 import {
 	findUserRewardDebtPda,
 	findUserStakePositionPda,

package/src/nexus/generated/instructions/stake.ts

@@ -44,7 +44,7 @@ import {
 	getAccountMetaFactory,
 	getAddressFromResolvedInstructionAccount,
 	type ResolvedInstructionAccount,
-} from '@solana/program-client-core';
+} from '@solana/kit/program-client-core';
 import {
 	EVENT_AUTHORITY_PDA_ADDRESS,
 	findUserStakePositionPda,

package/src/nexus/generated/instructions/unstake.ts

@@ -44,7 +44,7 @@ import {
 	getAccountMetaFactory,
 	getAddressFromResolvedInstructionAccount,
 	type ResolvedInstructionAccount,
-} from '@solana/program-client-core';
+} from '@solana/kit/program-client-core';
 import {
 	EVENT_AUTHORITY_PDA_ADDRESS,
 	findUserStakePositionPda,

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

@@ -20,7 +20,7 @@ import {
 	addSelfPlanAndSendFunctions,
 	type SelfFetchFunctions,
 	type SelfPlanAndSendFunctions,
-} from '@solana/program-client-core';
+} from '@solana/kit/program-client-core';
 import {
 	fetchAllAltRegistry,
 	fetchAllCreatorFeeConfig,

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

package/src/transfer-fee.ts

@@ -1,5 +1,5 @@
-// Hand-parsed so consumers don't inherit `@solana-program/token-2022`. The programs
-// price every leg on what lands after the mint's cut; a quote without it fails slippage.
+// Parses Token-2022 mint data by hand. The SDK does not depend on
+// `@solana-program/token-2022`.
 
 import {
 	getAddressDecoder,
@@ -20,8 +20,8 @@ import { fetchInChunks } from './utils/chunk.js';
 
 const MINT_BASE_LENGTH = 82;
 
-// Token-2022 pads the base mint to the 165-byte token-account length so the two
-// never share a prefix, then stamps the type byte; TLV entries follow it.
+// Token-2022 pads the base mint to 165 bytes, the token-account length. The
+// account-type byte follows, then the TLV entries.
 const ACCOUNT_TYPE_OFFSET = 165;
 
 const ACCOUNT_TYPE_MINT = 1;
@@ -58,7 +58,7 @@ export interface TransferFeeEntry {
 }
 
 export interface TransferFeeConfig {
-	/** `undefined` when the authority is unset: the schedule is frozen forever. */
+	/** `undefined` if the config has no authority. Then the schedule cannot change. */
 	readonly authority: Address | undefined;
 	readonly older: TransferFeeEntry;
 	readonly newer: TransferFeeEntry;
@@ -80,13 +80,14 @@ function readEntry(view: DataView, start: number): TransferFeeEntry {
 	};
 }
 
-/** `owner` is the account's program. `undefined` means no fee extension; anything
- *  unparseable throws `RangeError` rather than pricing a charging mint free. */
+/** Decodes the `TransferFeeConfig` extension of a mint. `owner` is the program that owns the account.
+ *  Returns `undefined` if the mint has no such extension. Throws `RangeError` if `owner` is not a
+ *  token program or `data` is not a valid mint. */
 export function decodeTransferFeeConfig(
 	data: Uint8Array,
 	owner: Address,
 ): TransferFeeConfig | undefined {
-	// Classic SPL can never gain an extension, so this result is permanent.
+	// Classic SPL mints have no extensions.
 	if (owner === TOKEN_PROGRAM_ADDRESS) return undefined;
 	if (owner !== TOKEN_2022_PROGRAM_ADDRESS) {
 		throw new RangeError(
@@ -94,14 +95,14 @@ export function decodeTransferFeeConfig(
 		);
 	}
 
-	// Token-2022 leaves a mint with no extensions unpadded at 82 bytes.
+	// A Token-2022 mint with no extensions is 82 bytes.
 	if (data.length === MINT_BASE_LENGTH) return undefined;
 	if (data.length < TLV_START) {
 		throw new RangeError(
 			`decodeTransferFeeConfig: a Token-2022 mint holds ${data.length} bytes, expected ${MINT_BASE_LENGTH} or at least ${TLV_START}`,
 		);
 	}
-	// Token accounts share this TLV layout with different extension types.
+	// Token accounts use the same TLV layout.
 	if (data[ACCOUNT_TYPE_OFFSET] !== ACCOUNT_TYPE_MINT) {
 		throw new RangeError(
 			`decodeTransferFeeConfig: account type ${data[ACCOUNT_TYPE_OFFSET]} is not a mint`,
@@ -112,7 +113,7 @@ export function decodeTransferFeeConfig(
 
 	let offset = TLV_START;
 	while (offset < data.length) {
-		// Too short for a type, or a zero type: trailing slack, as SPL reads it.
+		// SPL reads a tail too short for a type, or a zero type, as the end of the list.
 		if (offset + TLV_TYPE > data.length) return undefined;
 		const extensionType = view.getUint16(offset, true);
 		if (extensionType === UNINITIALIZED_TYPE) return undefined;
@@ -133,7 +134,7 @@ export function decodeTransferFeeConfig(
 		}
 
 		if (extensionType === TRANSFER_FEE_CONFIG_TYPE) {
-			// Exactly 108 or throw: the extension never writes a wider config.
+			// The extension is always 108 bytes.
 			if (length !== TRANSFER_FEE_CONFIG_LENGTH) {
 				throw new RangeError(
 					`decodeTransferFeeConfig: TransferFeeConfig holds ${length} bytes, expected ${TRANSFER_FEE_CONFIG_LENGTH}`,
@@ -152,7 +153,7 @@ export function decodeTransferFeeConfig(
 	return undefined;
 }
 
-/** Mirrors SPL `get_epoch_fee`: the newer entry is live from its own epoch on. */
+/** Returns the fee for `epoch`, as SPL `get_epoch_fee` does. The newer entry applies from its own epoch on. */
 export function transferFeeAtEpoch(
 	config: TransferFeeConfig,
 	epoch: bigint,
@@ -170,8 +171,8 @@ export function mintFeeAtEpoch(
 	return config === undefined ? undefined : transferFeeAtEpoch(config, epoch);
 }
 
-// Omit the config, never `{ commitment: undefined }`: Kit strips the falsy key and
-// the server's `finalized` wins, where an absent key gets the client's default.
+// Omit the config, not `{ commitment: undefined }`. Kit deletes an undefined key, so the
+// server default `finalized` applies. With no config, the client default applies.
 function currentEpoch(
 	rpc: Rpc<GetEpochInfoApi>,
 	commitment: Commitment | undefined,
@@ -182,8 +183,9 @@ function currentEpoch(
 		.then((info) => info.epoch);
 }
 
-/** A missing account throws, never reads as fee-free. Valid only for `epoch`, which defaults to
- *  the cluster's (a second call). */
+/** Reads the transfer fee of each mint for `epoch`. The result is valid only for that epoch.
+ *  `epoch` defaults to the current cluster epoch, read with `getEpochInfo`. A mint without a
+ *  transfer fee maps to `undefined`. Throws if a mint account is missing or does not decode. */
 export async function fetchMintFees(
 	rpc: Rpc<GetMultipleAccountsApi & GetEpochInfoApi>,
 	mints: readonly Address[],

package/src/utils/chunk.ts

@@ -3,7 +3,7 @@ import type { Address } from '@solana/kit';
 /** RPCs reject a `getMultipleAccounts` call past this many addresses. */
 const MAX_ACCOUNTS_PER_REQUEST = 100;
 
-/** Splits a multi-account read into 100-address calls; results follow `addresses` order. */
+/** Calls `read` once per 100 addresses. Results follow `addresses` order. */
 export async function fetchInChunks<T>(
 	addresses: readonly Address[],
 	read: (chunk: Address[]) => Promise<readonly T[]>,

package/src/utils/creator-hash.ts

@@ -3,7 +3,8 @@ import type { Address, ReadonlyUint8Array } from '@solana/kit';
 
 const MAX_CREATOR_PLATFORM_LEN = 32;
 
-/** SHA-256 of the LE-u32-length-prefixed platform and id. Frozen: it seeds live PDAs. */
+/** Returns the SHA-256 of `creatorPlatform` and `creatorId`, each prefixed with its byte length as a
+ *  little-endian u32. Throws `RangeError` if `creatorPlatform` is more than 32 bytes. */
 export async function creatorHashFromId(
 	creatorPlatform: string,
 	creatorId: string,
@@ -34,7 +35,8 @@ export async function creatorHashFromId(
 	return addressDecoder.decode(hash);
 }
 
-/** NUL-pads `text` to `length` bytes, the on-chain `CreatorFeeConfig.platformId` form; throws RangeError if longer. */
+/** Pads `text` with NUL bytes to `length` bytes, the form of `CreatorFeeConfig.platformId`.
+ *  Throws `RangeError` if `text` is longer. */
 export function encodeCreatorId(text: string, length: number): Uint8Array {
 	const bytes = new TextEncoder().encode(text);
 	if (bytes.length > length) {
@@ -47,7 +49,8 @@ export function encodeCreatorId(text: string, length: number): Uint8Array {
 	return out;
 }
 
-/** Strips NUL padding. Pass this, never the padded array, to {@link creatorHashFromId}: the hash is length-prefixed. */
+/** Removes the trailing NUL bytes and decodes the rest as UTF-8. Pass the result, not the padded
+ *  bytes, to {@link creatorHashFromId}. */
 export function decodeCreatorId(bytes: ReadonlyUint8Array): string {
 	let end = bytes.length;
 	while (end > 0 && bytes[end - 1] === 0) {

package/src/utils/index.ts

@@ -1,3 +1,5 @@
+// The three programs generate the same function.
+export { accountIsCreated } from '../nexus/generated/shared/index.js';
 export {
 	creatorHashFromId,
 	decodeCreatorId,

package/src/utils/mint-info.ts

@@ -1,5 +1,4 @@
-// Read off the mint, never tabulated: a stale `tokenProgram` derives an ATA the
-// transfer cannot reach.
+// Reads the token program from the mint account. Do not hard-code it.
 import {
 	getBase64Encoder,
 	type Address,
@@ -15,14 +14,14 @@ import {
 } from '../constants.js';
 import { fetchInChunks } from './chunk.js';
 
-// Both token programs share the base mint: 36-byte `COption<Pubkey>` authority,
+// Both token programs use the same base mint: 36-byte `COption<Pubkey>` authority,
 // u64 supply, then decimals.
 const MINT_BASE_LENGTH = 82;
 const MINT_DECIMALS_OFFSET = 44;
 
 export interface QuoteMintInfo {
 	mint: Address;
-	/** Immutable: safe to cache. */
+	/** Cannot change after the mint is created. */
 	decimals: number;
 	/** The account's owner: `TOKEN_PROGRAM_ADDRESS` or `TOKEN_2022_PROGRAM_ADDRESS`. */
 	tokenProgram: Address;
@@ -41,7 +40,7 @@ function decodeMintInfo(
 			`fetchQuoteMintInfo: ${mint} is owned by ${owner}, which is not a token program`,
 		);
 	}
-	// A floor, not an equality: Token-2022 mints with extensions run longer.
+	// A minimum: Token-2022 mints with extensions are longer.
 	if (data.length < MINT_BASE_LENGTH) {
 		throw new Error(
 			`fetchQuoteMintInfo: ${mint} holds ${data.length} bytes, too short for a mint`,
@@ -50,7 +49,8 @@ function decodeMintInfo(
 	return { mint, decimals: data[MINT_DECIMALS_OFFSET], tokenProgram: owner };
 }
 
-/** Throws when the mint does not exist or is not owned by a token program. */
+/** Reads the decimals and token program of `mint`. Throws if the account does not exist, a token
+ *  program does not own it, or it is too short for a mint. */
 export async function fetchQuoteMintInfo(
 	rpc: Rpc<GetAccountInfoApi>,
 	mint: Address,
@@ -71,7 +71,8 @@ export async function fetchQuoteMintInfo(
 	return decodeMintInfo(mint, data, value.owner);
 }
 
-/** One round trip per 100 mints; results follow `mints` order. */
+/** Reads the decimals and token program of each mint. Results follow `mints` order. Throws as
+ *  {@link fetchQuoteMintInfo} does. */
 export async function fetchQuoteMintInfos(
 	rpc: Rpc<GetMultipleAccountsApi>,
 	mints: readonly Address[],

package/src/utils/partner.ts

@@ -1,5 +1,5 @@
 import type { TransactionSigner } from '@solana/kit';
 import type { DEFAULT_PARTNER } from '../constants.js';
 
-/** Non-default partners must sign; only `DEFAULT_PARTNER` is valid as a bare address. */
+/** A partner signer, or `DEFAULT_PARTNER` as a bare address. Any other partner must sign. */
 export type PartnerInput = TransactionSigner | typeof DEFAULT_PARTNER;

package/src/utils/pda.ts

@@ -7,7 +7,7 @@ import {
 
 const addressEncoder = getAddressEncoder();
 
-/** Seed order is [wallet, tokenProgram, mint], not the parameter order. */
+/** Derives the associated token account of `wallet` for `mint` under `tokenProgram`. */
 export async function findAssociatedTokenPda(
 	wallet: Address,
 	mint: Address,