@solana/program-client-core 6.3.1 → 6.3.2-canary-20260313143218

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solana/program-client-core",
-  "version": "6.3.1",
+  "version": "6.3.2-canary-20260313143218",
   "description": "Core utilities for building Solana program clients",
   "homepage": "https://www.solanakit.com/api#solanaprogram-client-core",
   "exports": {
@@ -33,7 +33,8 @@
   "types": "./dist/types/index.d.ts",
   "type": "commonjs",
   "files": [
-    "./dist/"
+    "./dist/",
+    "./src/"
   ],
   "sideEffects": false,
   "keywords": [
@@ -55,15 +56,15 @@
     "maintained node versions"
   ],
   "dependencies": {
-    "@solana/accounts": "6.3.1",
-    "@solana/addresses": "6.3.1",
-    "@solana/codecs-core": "6.3.1",
-    "@solana/errors": "6.3.1",
-    "@solana/instruction-plans": "6.3.1",
-    "@solana/instructions": "6.3.1",
-    "@solana/signers": "6.3.1",
-    "@solana/rpc-api": "6.3.1",
-    "@solana/plugin-interfaces": "6.3.1"
+    "@solana/accounts": "6.3.2-canary-20260313143218",
+    "@solana/codecs-core": "6.3.2-canary-20260313143218",
+    "@solana/addresses": "6.3.2-canary-20260313143218",
+    "@solana/errors": "6.3.2-canary-20260313143218",
+    "@solana/instruction-plans": "6.3.2-canary-20260313143218",
+    "@solana/instructions": "6.3.2-canary-20260313143218",
+    "@solana/signers": "6.3.2-canary-20260313143218",
+    "@solana/rpc-api": "6.3.2-canary-20260313143218",
+    "@solana/plugin-interfaces": "6.3.2-canary-20260313143218"
   },
   "peerDependencies": {
     "typescript": "^5.0.0"

package/src/index.ts

@@ -0,0 +1,11 @@
+/**
+ * This package contains types and utilities for building Solana program clients.
+ * This is mainly used by the JavaScript Codama renderer to generate
+ * Kit-compatible program clients.
+ *
+ * @packageDocumentation
+ */
+export * from './instruction-input-resolution';
+export * from './instructions';
+export * from './self-fetch-functions';
+export * from './self-plan-and-send-functions';

package/src/instruction-input-resolution.ts

@@ -0,0 +1,216 @@
+import { type Address, isProgramDerivedAddress, type ProgramDerivedAddress } from '@solana/addresses';
+import {
+    SOLANA_ERROR__PROGRAM_CLIENTS__RESOLVED_INSTRUCTION_INPUT_MUST_BE_NON_NULL,
+    SOLANA_ERROR__PROGRAM_CLIENTS__UNEXPECTED_RESOLVED_INSTRUCTION_INPUT_TYPE,
+    SolanaError,
+} from '@solana/errors';
+import { type AccountMeta, AccountRole, upgradeRoleToSigner } from '@solana/instructions';
+import { type AccountSignerMeta, isTransactionSigner, type TransactionSigner } from '@solana/signers';
+
+/**
+ * Ensures a resolved instruction input is not null or undefined.
+ *
+ * This function is used during instruction resolution to validate that
+ * required inputs have been properly resolved to a non-null value.
+ *
+ * @typeParam T - The expected type of the resolved input value.
+ *
+ * @param inputName - The name of the instruction input, used in error messages.
+ * @param value - The resolved value to validate.
+ * @returns The validated non-null value.
+ *
+ * @throws Throws a {@link SolanaError} if the value is null or undefined.
+ *
+ * @example
+ * ```ts
+ * const resolvedAuthority = getNonNullResolvedInstructionInput(
+ *   'authority',
+ *   maybeAuthority
+ * );
+ * // resolvedAuthority is guaranteed to be non-null here.
+ * ```
+ */
+export function getNonNullResolvedInstructionInput<T>(inputName: string, value: T | null | undefined): T {
+    if (value === null || value === undefined) {
+        throw new SolanaError(SOLANA_ERROR__PROGRAM_CLIENTS__RESOLVED_INSTRUCTION_INPUT_MUST_BE_NON_NULL, {
+            inputName,
+        });
+    }
+    return value;
+}
+
+/**
+ * Extracts the address from a resolved instruction account.
+ *
+ * A resolved instruction account can be an {@link Address}, a {@link ProgramDerivedAddress},
+ * or a {@link TransactionSigner}. This function extracts the underlying address from
+ * any of these types.
+ *
+ * @typeParam T - The address type, defaults to `string`.
+ *
+ * @param inputName - The name of the instruction input, used in error messages.
+ * @param value - The resolved account value to extract the address from.
+ * @returns The extracted address.
+ *
+ * @throws Throws a {@link SolanaError} if the value is null or undefined.
+ *
+ * @example
+ * ```ts
+ * const address = getAddressFromResolvedInstructionAccount('mint', resolvedMint);
+ * ```
+ */
+export function getAddressFromResolvedInstructionAccount<T extends string = string>(
+    inputName: string,
+    value: ResolvedInstructionAccount<T>['value'] | undefined,
+): Address<T> {
+    const nonNullValue = getNonNullResolvedInstructionInput(inputName, value);
+    if (typeof value === 'object' && 'address' in nonNullValue) {
+        return nonNullValue.address;
+    }
+    if (Array.isArray(nonNullValue)) {
+        return nonNullValue[0] as Address<T>;
+    }
+    return nonNullValue as Address<T>;
+}
+
+/**
+ * Extracts a {@link ProgramDerivedAddress} from a resolved instruction account.
+ *
+ * This function validates that the resolved account is a PDA and returns it.
+ * Use this when you need access to both the address and the bump seed of a PDA.
+ *
+ * @typeParam T - The address type, defaults to `string`.
+ *
+ * @param inputName - The name of the instruction input, used in error messages.
+ * @param value - The resolved account value expected to be a PDA.
+ * @returns The program-derived address.
+ *
+ * @throws Throws a {@link SolanaError} if the value is not a {@link ProgramDerivedAddress}.
+ *
+ * @example
+ * ```ts
+ * const pda = getResolvedInstructionAccountAsProgramDerivedAddress('metadata', resolvedMetadata);
+ * const [address, bump] = pda;
+ * ```
+ */
+export function getResolvedInstructionAccountAsProgramDerivedAddress<T extends string = string>(
+    inputName: string,
+    value: ResolvedInstructionAccount<T>['value'] | undefined,
+): ProgramDerivedAddress<T> {
+    if (!isProgramDerivedAddress(value)) {
+        throw new SolanaError(SOLANA_ERROR__PROGRAM_CLIENTS__UNEXPECTED_RESOLVED_INSTRUCTION_INPUT_TYPE, {
+            expectedType: 'ProgramDerivedAddress',
+            inputName,
+        });
+    }
+    return value;
+}
+
+/**
+ * Extracts a {@link TransactionSigner} from a resolved instruction account.
+ *
+ * This function validates that the resolved account is a transaction signer and returns it.
+ * Use this when you need the resolved account to be a signer.
+ *
+ * @typeParam T - The address type, defaults to `string`.
+ *
+ * @param inputName - The name of the instruction input, used in error messages.
+ * @param value - The resolved account value expected to be a signer.
+ * @returns The transaction signer.
+ *
+ * @throws Throws a {@link SolanaError} if the value is not a {@link TransactionSigner}.
+ *
+ * @example
+ * ```ts
+ * const signer = getResolvedInstructionAccountAsTransactionSigner('authority', resolvedAuthority);
+ * ```
+ */
+export function getResolvedInstructionAccountAsTransactionSigner<T extends string = string>(
+    inputName: string,
+    value: ResolvedInstructionAccount<T>['value'] | undefined,
+): TransactionSigner<T> {
+    if (!isResolvedInstructionAccountSigner(value)) {
+        throw new SolanaError(SOLANA_ERROR__PROGRAM_CLIENTS__UNEXPECTED_RESOLVED_INSTRUCTION_INPUT_TYPE, {
+            expectedType: 'TransactionSigner',
+            inputName,
+        });
+    }
+    return value;
+}
+
+/**
+ * Represents a resolved account input for an instruction.
+ *
+ * During instruction building, account inputs are resolved to this type which
+ * captures both the account value and whether it should be marked as writable.
+ * The value can be an {@link Address}, a {@link ProgramDerivedAddress}, a
+ * {@link TransactionSigner}, or `null` for optional accounts.
+ *
+ * @typeParam TAddress - The address type, defaults to `string`.
+ * @typeParam TValue - The type of the resolved value.
+ *
+ * @example
+ * ```ts
+ * const mintAccount: ResolvedInstructionAccount = {
+ *   value: mintAddress,
+ *   isWritable: true,
+ * };
+ * ```
+ */
+export type ResolvedInstructionAccount<
+    TAddress extends string = string,
+    TValue extends Address<TAddress> | ProgramDerivedAddress<TAddress> | TransactionSigner<TAddress> | null =
+        | Address<TAddress>
+        | ProgramDerivedAddress<TAddress>
+        | TransactionSigner<TAddress>
+        | null,
+> = {
+    isWritable: boolean;
+    value: TValue;
+};
+
+/**
+ * Creates a factory function that converts resolved instruction accounts to account metas.
+ *
+ * The factory handles the conversion of {@link ResolvedInstructionAccount} objects into
+ * {@link AccountMeta} or {@link AccountSignerMeta} objects suitable for building instructions.
+ * It also determines how to handle optional accounts based on the provided strategy.
+ *
+ * @param programAddress - The program address, used when optional accounts use the `programId` strategy.
+ * @param optionalAccountStrategy - How to handle null account values:
+ *   - `'omitted'`: Optional accounts are excluded from the instruction entirely.
+ *   - `'programId'`: Optional accounts are replaced with the program address as a read-only account.
+ * @returns A factory function that converts a resolved account to an account meta.
+ *
+ * @example
+ * ```ts
+ * const toAccountMeta = getAccountMetaFactory(programAddress, 'programId');
+ * const mintMeta = toAccountMeta('mint', resolvedMint);
+ * ```
+ */
+export function getAccountMetaFactory(programAddress: Address, optionalAccountStrategy: 'omitted' | 'programId') {
+    return (inputName: string, account: ResolvedInstructionAccount): AccountMeta | AccountSignerMeta | undefined => {
+        if (!account.value) {
+            if (optionalAccountStrategy === 'omitted') return;
+            return Object.freeze({ address: programAddress, role: AccountRole.READONLY });
+        }
+
+        const writableRole = account.isWritable ? AccountRole.WRITABLE : AccountRole.READONLY;
+        const isSigner = isResolvedInstructionAccountSigner(account.value);
+        return Object.freeze({
+            address: getAddressFromResolvedInstructionAccount(inputName, account.value),
+            role: isSigner ? upgradeRoleToSigner(writableRole) : writableRole,
+            ...(isSigner ? { signer: account.value } : {}),
+        });
+    };
+}
+
+function isResolvedInstructionAccountSigner(value: unknown): value is TransactionSigner {
+    return (
+        !!value &&
+        typeof value === 'object' &&
+        'address' in value &&
+        typeof value.address === 'string' &&
+        isTransactionSigner(value as { address: Address })
+    );
+}

package/src/instructions.ts

@@ -0,0 +1,11 @@
+/**
+ * An instruction that tracks how many bytes it adds or removes from on-chain accounts.
+ *
+ * The `byteDelta` indicates the net change in account storage size. A positive value
+ * means bytes are being allocated, while a negative value means bytes are being freed.
+ * This is useful for calculating how much balance a storage payer must have for a
+ * transaction to succeed.
+ */
+export type InstructionWithByteDelta = {
+    byteDelta: number;
+};

package/src/self-fetch-functions.ts

@@ -0,0 +1,156 @@
+import {
+    type Account,
+    assertAccountExists,
+    assertAccountsExist,
+    decodeAccount,
+    type FetchAccountConfig,
+    type FetchAccountsConfig,
+    fetchEncodedAccount,
+    fetchEncodedAccounts,
+    type MaybeAccount,
+} from '@solana/accounts';
+import type { Address } from '@solana/addresses';
+import type { Codec } from '@solana/codecs-core';
+import type { ClientWithRpc } from '@solana/plugin-interfaces';
+import type { GetAccountInfoApi, GetMultipleAccountsApi } from '@solana/rpc-api';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyObjectCodec = Codec<any, object>;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type InferTFrom<T> = T extends Codec<infer TFrom, any> ? TFrom : never;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type InferTTo<T> = T extends Codec<any, infer TTo> ? TTo : never;
+
+/**
+ * Methods that allow a codec to fetch and decode accounts directly.
+ *
+ * These methods are added to codec objects via {@link addSelfFetchFunctions},
+ * enabling a fluent API where you can call `.fetch()` directly on a codec
+ * to retrieve and decode accounts in one step.
+ *
+ * @typeParam TFrom - The type that the codec encodes from.
+ * @typeParam TTo - The type that the codec decodes to.
+ *
+ * @example
+ * Fetching a single account and asserting it exists.
+ * ```ts
+ * const account = await myAccountCodec.fetch(address);
+ * // account.data is of type TTo.
+ * ```
+ *
+ * @example
+ * Fetching a single account that may not exist.
+ * ```ts
+ * const maybeAccount = await myAccountCodec.fetchMaybe(address);
+ * if (maybeAccount.exists) {
+ *     // maybeAccount.data is of type TTo.
+ * }
+ * ```
+ *
+ * @example
+ * Fetching multiple accounts at once.
+ * ```ts
+ * const accounts = await myAccountCodec.fetchAll([addressA, addressB]);
+ * // All accounts exist.
+ * ```
+ *
+ * @see {@link addSelfFetchFunctions}
+ */
+export type SelfFetchFunctions<TFrom extends object, TTo extends TFrom> = {
+    /** Fetches and decodes a single account, throwing if it does not exist. */
+    readonly fetch: <TAddress extends string>(
+        address: Address<TAddress>,
+        config?: FetchAccountConfig,
+    ) => Promise<Account<TTo, TAddress>>;
+    /** Fetches and decodes multiple accounts, throwing if any do not exist. */
+    readonly fetchAll: (addresses: Address[], config?: FetchAccountsConfig) => Promise<Account<TTo>[]>;
+    /** Fetches and decodes multiple accounts, returning {@link MaybeAccount} for each. */
+    readonly fetchAllMaybe: (addresses: Address[], config?: FetchAccountsConfig) => Promise<MaybeAccount<TTo>[]>;
+    /** Fetches and decodes a single account, returning a {@link MaybeAccount}. */
+    readonly fetchMaybe: <TAddress extends string>(
+        address: Address<TAddress>,
+        config?: FetchAccountConfig,
+    ) => Promise<MaybeAccount<TTo, TAddress>>;
+};
+
+/**
+ * Adds self-fetching methods to a codec for retrieving and decoding accounts.
+ *
+ * This function augments the provided codec with methods that allow it to fetch
+ * accounts from the network and decode them in one step. It enables a fluent API
+ * where you can call methods like `.fetch()` directly on the codec.
+ *
+ * @typeParam TFrom - The type that the codec encodes from.
+ * @typeParam TTo - The type that the codec decodes to.
+ * @typeParam TCodec - The codec type being augmented.
+ *
+ * @param client - A client that provides RPC access for fetching accounts.
+ * @param codec - The codec to augment with self-fetch methods.
+ * @returns The codec augmented with {@link SelfFetchFunctions} methods.
+ *
+ * @example
+ * Adding self-fetch functions to an account codec.
+ * ```ts
+ * import { addSelfFetchFunctions } from '@solana/program-client-core';
+ *
+ * const myAccountCodec = addSelfFetchFunctions(client, getMyAccountCodec());
+ *
+ * // Fetch and decode an account in one step.
+ * const account = await myAccountCodec.fetch(accountAddress);
+ * ```
+ *
+ * @example
+ * Handling accounts that may not exist.
+ * ```ts
+ * const myAccountCodec = addSelfFetchFunctions(client, getMyAccountCodec());
+ *
+ * const maybeAccount = await myAccountCodec.fetchMaybe(accountAddress);
+ * if (maybeAccount.exists) {
+ *     console.log('Account data:', maybeAccount.data);
+ * } else {
+ *     console.log(`Account ${maybeAccount.address} does not exist`);
+ * }
+ * ```
+ *
+ * @example
+ * Fetching multiple accounts at once.
+ * ```ts
+ * const myAccountCodec = addSelfFetchFunctions(client, getMyAccountCodec());
+ *
+ * // Throws if any account does not exist.
+ * const accounts = await myAccountCodec.fetchAll([addressA, addressB, addressC]);
+ *
+ * // Returns MaybeAccount for each, allowing some to not exist.
+ * const maybeAccounts = await myAccountCodec.fetchAllMaybe([addressA, addressB]);
+ * ```
+ *
+ * @see {@link SelfFetchFunctions}
+ */
+export function addSelfFetchFunctions<TCodec extends AnyObjectCodec>(
+    client: ClientWithRpc<GetAccountInfoApi & GetMultipleAccountsApi>,
+    codec: TCodec,
+): SelfFetchFunctions<InferTFrom<TCodec>, InferTTo<TCodec>> & TCodec {
+    type Functions = SelfFetchFunctions<InferTFrom<TCodec>, InferTTo<TCodec>>;
+    type InferredCodec = Codec<InferTFrom<TCodec>, InferTTo<TCodec>>;
+    const fetchMaybe: Functions['fetchMaybe'] = async (address, config?) => {
+        const maybeAccount = await fetchEncodedAccount(client.rpc, address, config);
+        return decodeAccount(maybeAccount, codec as InferredCodec);
+    };
+    const fetchAllMaybe: Functions['fetchAllMaybe'] = async (addresses, config?) => {
+        const maybeAccounts = await fetchEncodedAccounts(client.rpc, addresses, config);
+        return maybeAccounts.map(maybeAccount => decodeAccount(maybeAccount, codec as InferredCodec));
+    };
+    const fetch: Functions['fetch'] = async (address, config?) => {
+        const maybeAccount = await fetchMaybe(address, config);
+        assertAccountExists(maybeAccount);
+        return maybeAccount;
+    };
+    const fetchAll: Functions['fetchAll'] = async (addresses, config?) => {
+        const maybeAccounts = await fetchAllMaybe(addresses, config);
+        assertAccountsExist(maybeAccounts);
+        return maybeAccounts;
+    };
+
+    const out = { ...codec, fetch, fetchAll, fetchAllMaybe, fetchMaybe };
+    return Object.freeze<typeof out>(out);
+}

package/src/self-plan-and-send-functions.ts

@@ -0,0 +1,118 @@
+import type { InstructionPlan } from '@solana/instruction-plans';
+import type { Instruction } from '@solana/instructions';
+import type { ClientWithTransactionPlanning, ClientWithTransactionSending } from '@solana/plugin-interfaces';
+
+type PlanTransaction = ClientWithTransactionPlanning['planTransaction'];
+type PlanTransactions = ClientWithTransactionPlanning['planTransactions'];
+type SendTransaction = ClientWithTransactionSending['sendTransaction'];
+type SendTransactions = ClientWithTransactionSending['sendTransactions'];
+
+/**
+ * Methods that allow an instruction or instruction plan to plan and send itself.
+ *
+ * These methods are added to instruction or instruction plan objects via
+ * {@link addSelfPlanAndSendFunctions}, enabling a fluent API where you can call
+ * `.sendTransaction()` directly on an instruction without passing it to a separate function.
+ *
+ * @example
+ * Sending a transfer instruction directly.
+ * ```ts
+ * const result = await getTransferInstruction({ source, destination, amount }).sendTransaction();
+ * ```
+ *
+ * @example
+ * Planning multiple transactions from an instruction plan.
+ * ```ts
+ * const plan = await getComplexInstructionPlan(/* ... *\/).planTransactions();
+ * ```
+ *
+ * @see {@link addSelfPlanAndSendFunctions}
+ */
+export type SelfPlanAndSendFunctions = {
+    /** Plans a single transaction. */
+    planTransaction: (config?: Parameters<PlanTransaction>[1]) => ReturnType<PlanTransaction>;
+    /** Plans one or more transactions. */
+    planTransactions: (config?: Parameters<PlanTransactions>[1]) => ReturnType<PlanTransactions>;
+    /** Sends a single transaction. */
+    sendTransaction: (config?: Parameters<SendTransaction>[1]) => ReturnType<SendTransaction>;
+    /** Sends one or more transactions. */
+    sendTransactions: (config?: Parameters<SendTransactions>[1]) => ReturnType<SendTransactions>;
+};
+
+/**
+ * Adds self-planning and self-sending methods to an instruction or instruction plan.
+ *
+ * This function augments the provided instruction or instruction plan with methods
+ * that allow it to plan and send itself using the provided client. It enables a fluent API
+ * where you can call methods like `.sendTransaction()` directly on the instruction.
+ *
+ * The function supports both synchronous inputs (instructions, instruction plans) and
+ * promise-like inputs, making it suitable for use with async instruction builders.
+ *
+ * @typeParam TItem - The type of the instruction, instruction plan, or a promise resolving to one.
+ *
+ * @param client - A client that provides transaction planning and sending capabilities.
+ * @param input - The instruction, instruction plan, or promise to augment with self-plan/send methods.
+ * @returns The input augmented with {@link SelfPlanAndSendFunctions} methods.
+ *
+ * @example
+ * Adding self-plan and send to a transfer instruction.
+ * ```ts
+ * import { addSelfPlanAndSendFunctions } from '@solana/program-client-core';
+ *
+ * const transferInstruction = addSelfPlanAndSendFunctions(
+ *     client,
+ *     getTransferInstruction({ payer, source, destination, amount })
+ * );
+ *
+ * // Now you can send directly from the instruction.
+ * const result = await transferInstruction.sendTransaction();
+ * ```
+ *
+ * @example
+ * Using with an async instruction builder.
+ * ```ts
+ * const asyncInstruction = addSelfPlanAndSendFunctions(
+ *     client,
+ *     fetchAndBuildInstruction(/* ... *\/)
+ * );
+ *
+ * // The promise is augmented with self-plan/send methods.
+ * const result = await asyncInstruction.sendTransaction();
+ * ```
+ *
+ * @see {@link SelfPlanAndSendFunctions}
+ */
+export function addSelfPlanAndSendFunctions<
+    TItem extends Instruction | InstructionPlan | PromiseLike<Instruction> | PromiseLike<InstructionPlan>,
+>(
+    client: ClientWithTransactionPlanning & ClientWithTransactionSending,
+    input: TItem,
+): SelfPlanAndSendFunctions & TItem {
+    if (isPromiseLike(input)) {
+        const newInput = input as SelfPlanAndSendFunctions & TItem;
+        newInput.planTransaction = async config => await client.planTransaction(await input, config);
+        newInput.planTransactions = async config => await client.planTransactions(await input, config);
+        newInput.sendTransaction = async config => await client.sendTransaction(await input, config);
+        newInput.sendTransactions = async config => await client.sendTransactions(await input, config);
+        return newInput;
+    }
+
+    return Object.freeze(<SelfPlanAndSendFunctions & (Instruction | InstructionPlan)>{
+        ...input,
+        planTransaction: config => client.planTransaction(input, config),
+        planTransactions: config => client.planTransactions(input, config),
+        sendTransaction: config => client.sendTransaction(input, config),
+        sendTransactions: config => client.sendTransactions(input, config),
+    }) as unknown as SelfPlanAndSendFunctions & TItem;
+}
+
+function isPromiseLike(
+    item: Instruction | InstructionPlan | PromiseLike<Instruction> | PromiseLike<InstructionPlan>,
+): item is PromiseLike<Instruction> | PromiseLike<InstructionPlan> {
+    return (
+        !!item &&
+        (typeof item === 'object' || typeof item === 'function') &&
+        typeof (item as PromiseLike<unknown>).then === 'function'
+    );
+}