@send-fun/sdk 1.1.0 → 1.2.0

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,