@solana/plugin-interfaces 6.3.1 → 6.3.2-canary-20260313112147

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@solana/plugin-interfaces",
-  "version": "6.3.1",
+  "version": "6.3.2-canary-20260313112147",
   "description": "TypeScript interfaces for building pluggable Solana clients",
   "homepage": "https://www.solanakit.com/api#solanaplugin-interfaces",
   "types": "./dist/types/index.d.ts",
   "type": "commonjs",
   "files": [
-    "./dist/"
+    "./dist/",
+    "./src/"
   ],
   "sideEffects": false,
   "keywords": [
@@ -28,13 +29,13 @@
     "maintained node versions"
   ],
   "dependencies": {
-    "@solana/instruction-plans": "6.3.1",
-    "@solana/keys": "6.3.1",
-    "@solana/addresses": "6.3.1",
-    "@solana/rpc-spec": "6.3.1",
-    "@solana/rpc-subscriptions-spec": "6.3.1",
-    "@solana/rpc-types": "6.3.1",
-    "@solana/signers": "6.3.1"
+    "@solana/addresses": "6.3.2-canary-20260313112147",
+    "@solana/keys": "6.3.2-canary-20260313112147",
+    "@solana/rpc-spec": "6.3.2-canary-20260313112147",
+    "@solana/instruction-plans": "6.3.2-canary-20260313112147",
+    "@solana/rpc-subscriptions-spec": "6.3.2-canary-20260313112147",
+    "@solana/rpc-types": "6.3.2-canary-20260313112147",
+    "@solana/signers": "6.3.2-canary-20260313112147"
   },
   "peerDependencies": {
     "typescript": "^5.0.0"

package/src/airdrop.ts

@@ -0,0 +1,34 @@
+import { Address } from '@solana/addresses';
+import { Signature } from '@solana/keys';
+import { Lamports } from '@solana/rpc-types';
+
+/**
+ * Represents a client that can request airdrops of SOL to a specified address.
+ *
+ * The airdrop capability is typically available on test networks (devnet, testnet)
+ * and local validators. It allows funding accounts with SOL for testing purposes.
+ *
+ * @example
+ * ```ts
+ * async function fundAccount(client: ClientWithAirdrop, address: Address) {
+ *     const signature = await client.airdrop(address, lamports(1_000_000_000n));
+ *     console.log(`Airdrop confirmed: ${signature ?? '[no signature]'}`);
+ * }
+ * ```
+ */
+export type ClientWithAirdrop = {
+    /**
+     * Requests an airdrop of SOL to the specified address.
+     *
+     * The returned promise resolves when the airdrop succeeds and rejects on failure.
+     * Some implementations (e.g., LiteSVM) update account balances directly without
+     * sending a transaction, in which case no signature is returned.
+     *
+     * @param address - The address to receive the airdrop.
+     * @param amount - The amount of lamports to airdrop.
+     * @param abortSignal - An optional signal to abort the airdrop request.
+     * @returns A promise resolving to the transaction signature if the airdrop was
+     *          performed via a transaction, or `undefined` if no transaction was used.
+     */
+    airdrop: (address: Address, amount: Lamports, abortSignal?: AbortSignal) => Promise<Signature | undefined>;
+};

package/src/index.ts

@@ -0,0 +1,11 @@
+/**
+ * This package defines common TypeScript interfaces for features that Kit plugins
+ * can provide or require. It can be used standalone, but it is also exported as part
+ * of Kit [`@solana/kit`](https://github.com/anza-xyz/kit/tree/main/packages/kit).
+ *
+ * @packageDocumentation
+ */
+export * from './airdrop';
+export * from './instruction-plans';
+export * from './payer';
+export * from './rpc';

package/src/instruction-plans.ts

@@ -0,0 +1,118 @@
+import type {
+    InstructionPlanInput,
+    SingleTransactionPlan,
+    SuccessfulSingleTransactionPlanResult,
+    TransactionPlan,
+    TransactionPlanInput,
+    TransactionPlanResult,
+} from '@solana/instruction-plans';
+
+type Config = { abortSignal?: AbortSignal };
+
+/**
+ * Represents a client that can plan transactions from instruction inputs.
+ *
+ * Transaction planning converts high-level instruction plans into concrete
+ * transaction messages, handling concerns like blockhash fetching, transaction
+ * splitting for size limits, and instruction ordering.
+ *
+ * @example
+ * ```ts
+ * async function prepareTransfer(client: ClientWithTransactionPlanning) {
+ *     const instructions = [createTransferInstruction(...)];
+ *
+ *     // Plan a single transaction
+ *     const message = await client.planTransaction(instructions);
+ *
+ *     // Or plan potentially multiple transactions if needed
+ *     const plan = await client.planTransactions(instructions);
+ * }
+ * ```
+ */
+export type ClientWithTransactionPlanning = {
+    /**
+     * Plans a single transaction from the given instruction input.
+     *
+     * Use this when you expect all instructions to fit in a single transaction.
+     *
+     * @param input - The instruction plan input (instructions or instruction plans).
+     * @param config - Optional configuration including an abort signal.
+     * @returns A promise resolving to the planned transaction message.
+     *
+     * @see {@link InstructionPlanInput}
+     */
+    planTransaction: (input: InstructionPlanInput, config?: Config) => Promise<SingleTransactionPlan['message']>;
+
+    /**
+     * Plans one or more transactions from the given instruction input.
+     *
+     * Use this when instructions might need to be split across multiple
+     * transactions due to size limits.
+     *
+     * @param input - The instruction plan input (instructions or instruction plans).
+     * @param config - Optional configuration including an abort signal.
+     * @returns A promise resolving to the full transaction plan.
+     *
+     * @see {@link InstructionPlanInput}
+     */
+    planTransactions: (input: InstructionPlanInput, config?: Config) => Promise<TransactionPlan>;
+};
+
+/**
+ * Represents a client that can send transactions to the Solana network.
+ *
+ * Transaction sending handles signing, submission, and confirmation of
+ * transactions. It supports flexible input formats including instructions,
+ * instruction plans, transaction messages or transaction plans.
+ *
+ * @example
+ * ```ts
+ * async function executeTransfer(client: ClientWithTransactionSending) {
+ *     const instructions = [createTransferInstruction(...)];
+ *
+ *     // Send a single transaction
+ *     const result = await client.sendTransaction(instructions);
+ *     console.log(`Transaction confirmed: ${result.context.signature}`);
+ *
+ *     // Or send potentially multiple transactions
+ *     const results = await client.sendTransactions(instructions);
+ * }
+ * ```
+ */
+export type ClientWithTransactionSending = {
+    /**
+     * Sends a single transaction to the network.
+     *
+     * Accepts flexible input: instructions, instruction plans, a single
+     * transaction message or a single transaction plan.
+     *
+     * @param input - Instructions, a transaction plan, or a transaction message.
+     * @param config - Optional configuration including an abort signal.
+     * @returns A promise resolving to the successful transaction result.
+     *
+     * @see {@link InstructionPlanInput}
+     * @see {@link SingleTransactionPlan}
+     */
+    sendTransaction: (
+        input: InstructionPlanInput | SingleTransactionPlan | SingleTransactionPlan['message'],
+        config?: Config,
+    ) => Promise<SuccessfulSingleTransactionPlanResult>;
+
+    /**
+     * Sends one or more transactions to the network.
+     *
+     * Accepts flexible input: instructions, instruction plans, transaction messages
+     * or transaction plans.
+     *
+     * @param input - Any instruction or a transaction plan input.
+     * @param config - Optional configuration including an abort signal.
+     * @returns A promise resolving to the results for all transactions.
+     *
+     * @see {@link InstructionPlanInput}
+     * @see {@link TransactionPlanInput}
+     */
+    sendTransactions: (
+        input: InstructionPlanInput | TransactionPlanInput,
+        config?: Config,
+    ) => Promise<TransactionPlanResult>;
+};

package/src/payer.ts

@@ -0,0 +1,18 @@
+import { TransactionSigner } from '@solana/signers';
+
+/**
+ * Represents a client that provides a default transaction payer.
+ *
+ * The payer is a {@link TransactionSigner} used to sign and pay for transactions.
+ * Clients implementing this interface can automatically fund transactions
+ * without requiring callers to specify a fee payer explicitly.
+ *
+ * @example
+ * ```ts
+ * function createTransfer(client: ClientWithPayer, recipient: Address, amount: Lamports) {
+ *     const feePayer = client.payer;
+ *     // Use feePayer.address as the transaction fee payer
+ * }
+ * ```
+ */
+export type ClientWithPayer = { payer: TransactionSigner };

package/src/rpc.ts

@@ -0,0 +1,52 @@
+import type { Rpc } from '@solana/rpc-spec';
+import type { RpcSubscriptions } from '@solana/rpc-subscriptions-spec';
+
+/**
+ * Represents a client that provides access to a Solana RPC endpoint.
+ *
+ * The RPC interface allows making JSON-RPC calls to a Solana validator,
+ * such as fetching account data, sending transactions, and querying blockchain state.
+ *
+ * @typeParam TRpcMethods - The RPC methods available on this client. Use specific
+ *            method types from `@solana/rpc-api` for the Solana JSON-RPC API.
+ *
+ * @example
+ * ```ts
+ * import { SolanaRpcApi } from '@solana/rpc-api';
+ *
+ * async function getBalance(client: ClientWithRpc<SolanaRpcApi>, address: Address) {
+ *     const { value: balance } = await client.rpc.getBalance(address).send();
+ *     return balance;
+ * }
+ * ```
+ */
+export type ClientWithRpc<TRpcMethods> = { rpc: Rpc<TRpcMethods> };
+
+/**
+ * Represents a client that provides access to Solana RPC subscriptions.
+ *
+ * RPC subscriptions enable real-time notifications from the Solana validator,
+ * such as account changes, slot updates, and transaction confirmations.
+ *
+ * @typeParam TRpcSubscriptionsMethods - The subscription methods available on this client.
+ *            Use specific method types from `@solana/rpc-subscriptions-api` for the Solana
+ *            subscription API.
+ *
+ * @example
+ * ```ts
+ * import { SolanaRpcSubscriptionsApi } from '@solana/rpc-subscriptions-api';
+ *
+ * async function subscribeToAccount(
+ *     client: ClientWithRpcSubscriptions<SolanaRpcSubscriptionsApi>,
+ *     address: Address,
+ * ) {
+ *     const subscription = await client.rpcSubscriptions.accountNotifications(address).subscribe();
+ *     for await (const notification of subscription) {
+ *         console.log('Account changed:', notification);
+ *     }
+ * }
+ * ```
+ */
+export type ClientWithRpcSubscriptions<TRpcSubscriptionsMethods> = {
+    rpcSubscriptions: RpcSubscriptions<TRpcSubscriptionsMethods>;
+};