@solana/instruction-plans 6.3.1 → 6.3.2-canary-20260313112147

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solana/instruction-plans",
-  "version": "6.3.1",
+  "version": "6.3.2-canary-20260313112147",
   "description": "Construct, plan and execute transactions from multiple instructions.",
   "homepage": "https://www.solanakit.com/api#solanainstruction-plans",
   "exports": {
@@ -33,7 +33,8 @@
   "types": "./dist/types/index.d.ts",
   "type": "commonjs",
   "files": [
-    "./dist/"
+    "./dist/",
+    "./src/"
   ],
   "sideEffects": false,
   "keywords": [
@@ -55,12 +56,12 @@
     "maintained node versions"
   ],
   "dependencies": {
-    "@solana/errors": "6.3.1",
-    "@solana/keys": "6.3.1",
-    "@solana/instructions": "6.3.1",
-    "@solana/promises": "6.3.1",
-    "@solana/transaction-messages": "6.3.1",
-    "@solana/transactions": "6.3.1"
+    "@solana/errors": "6.3.2-canary-20260313112147",
+    "@solana/instructions": "6.3.2-canary-20260313112147",
+    "@solana/keys": "6.3.2-canary-20260313112147",
+    "@solana/promises": "6.3.2-canary-20260313112147",
+    "@solana/transaction-messages": "6.3.2-canary-20260313112147",
+    "@solana/transactions": "6.3.2-canary-20260313112147"
   },
   "peerDependencies": {
     "typescript": "^5.0.0"

package/src/append-instruction-plan.ts

@@ -0,0 +1,90 @@
+import { SOLANA_ERROR__INVARIANT_VIOLATION__INVALID_INSTRUCTION_PLAN_KIND, SolanaError } from '@solana/errors';
+import { type Instruction } from '@solana/instructions';
+import {
+    appendTransactionMessageInstruction,
+    appendTransactionMessageInstructions,
+    TransactionMessage,
+    TransactionMessageWithFeePayer,
+} from '@solana/transaction-messages';
+
+import { flattenInstructionPlan, InstructionPlan } from './instruction-plan';
+
+/**
+ * A helper type to append instructions to a transaction message
+ * without losing type information about the current instructions.
+ */
+
+type AppendTransactionMessageInstructions<TTransactionMessage extends TransactionMessage> = ReturnType<
+    typeof appendTransactionMessageInstructions<TTransactionMessage, Instruction[]>
+>;
+
+/**
+ * Appends all instructions from an instruction plan to a transaction message.
+ *
+ * This function flattens the instruction plan into its leaf plans and sequentially
+ * appends each instruction to the provided transaction message. It handles both
+ * single instructions and message packer plans.
+ *
+ * Note that any {@link MessagePackerInstructionPlan} is assumed to only append
+ * instructions. If it modifies other properties of the transaction message, the
+ * type of the returned transaction message may not accurately reflect those changes.
+ *
+ * @typeParam TTransactionMessage - The type of transaction message being modified.
+ *
+ * @param transactionMessage - The transaction message to append instructions to.
+ * @param instructionPlan - The instruction plan containing the instructions to append.
+ * @returns The transaction message with all instructions from the plan appended.
+ *
+ * @example
+ * Appending a simple instruction plan to a transaction message.
+ * ```ts
+ * import { appendTransactionMessageInstructionPlan } from '@solana/instruction-plans';
+ * import { createTransactionMessage, setTransactionMessageFeePayer } from '@solana/transaction-messages';
+ *
+ * const message = setTransactionMessageFeePayer(feePayer, createTransactionMessage({ version: 0 }));
+ * const plan = singleInstructionPlan(myInstruction);
+ *
+ * const messageWithInstructions = appendTransactionMessageInstructionPlan(message, plan);
+ * ```
+ *
+ * @example
+ * Appending a sequential instruction plan.
+ * ```ts
+ * const plan = sequentialInstructionPlan([instructionA, instructionB, instructionC]);
+ * const messageWithInstructions = appendTransactionMessageInstructionPlan(message, plan);
+ * ```
+ *
+ * @see {@link InstructionPlan}
+ * @see {@link flattenInstructionPlan}
+ */
+export function appendTransactionMessageInstructionPlan<
+    TTransactionMessage extends TransactionMessage & TransactionMessageWithFeePayer,
+>(
+    instructionPlan: InstructionPlan,
+    transactionMessage: TTransactionMessage,
+): AppendTransactionMessageInstructions<TTransactionMessage> {
+    type Out = AppendTransactionMessageInstructions<TTransactionMessage>;
+
+    const leafInstructionPlans = flattenInstructionPlan(instructionPlan);
+
+    return leafInstructionPlans.reduce(
+        (messageSoFar, plan) => {
+            const kind = plan.kind;
+            if (kind === 'single') {
+                return appendTransactionMessageInstruction(plan.instruction, messageSoFar) as unknown as Out;
+            }
+            if (kind === 'messagePacker') {
+                const messagerPacker = plan.getMessagePacker();
+                let nextMessage: Out = messageSoFar;
+                while (!messagerPacker.done()) {
+                    nextMessage = messagerPacker.packMessageToCapacity(nextMessage) as Out;
+                }
+                return nextMessage;
+            }
+            throw new SolanaError(SOLANA_ERROR__INVARIANT_VIOLATION__INVALID_INSTRUCTION_PLAN_KIND, {
+                kind,
+            });
+        },
+        transactionMessage as unknown as Out,
+    );
+}

package/src/index.ts

@@ -0,0 +1,60 @@
+/**
+ * Instruction plans describe operations that go beyond a
+ * single instruction and may even span multiple transactions.
+ *
+ * They define a set of instructions that must be executed following a specific order.
+ * For instance, imagine we wanted to create an instruction plan for a simple escrow
+ * transfer between Alice and Bob. First, both would need to deposit their assets
+ * into a vault. This could happen in any order. Then and only then, the vault can be
+ * activated to switch the assets. Alice and Bob can now both withdraw each other’s assets
+ * (again, in any order). Here’s how we could describe an instruction plan for such an operation.
+ *
+ * ```typescript
+ * const instructionPlan = sequentialInstructionPlan([
+ *     parallelInstructionPlan([
+ *         depositFromAlice,
+ *         depositFromBob,
+ *     ]),
+ *     activateVault,
+ *     parallelInstructionPlan([
+ *         withdrawToAlice,
+ *         withdrawToBob,
+ *     ]),
+ * ]);
+ * ```
+ *
+ * As you can see, instruction plans don’t concern themselves with:
+ * - Adding structural instructions — e.g. compute budget limits and prices.
+ * - Building transaction messages from these instructions.
+ *   That is planning how many can fit into a single instruction, adding a fee payer, a lifetime, etc.
+ * - Compiling, signing and sending transactions to the network.
+ *
+ * Instead, they solely focus on describing operations and delegate
+ * all that to two components introduced in this package:
+ * - **Transaction planner**: builds transaction messages from an
+ *   instruction plan and returns an appropriate transaction plan.
+ * - **Transaction plan executor**: compiles, signs and sends
+ *   transaction plans and returns a detailed result of this operation.
+ *
+ * ```typescript
+ * // Plan instructions into transactions.
+ * const transactionPlan = await transactionPlanner(instructionPlan);
+ *
+ * // Execute transactions.
+ * const transactionPlanResult = await transactionPlanExecutor(transactionPlan);
+ * ```
+ *
+ * This separation of concerns not only improves the developer experience but also
+ * allows program maintainers to offer helper functions that go beyond a single instruction,
+ * while leaving their consumers to decide how they want these operations to materialise.
+ *
+ * @packageDocumentation
+ */
+export * from './append-instruction-plan';
+export * from './instruction-plan';
+export * from './instruction-plan-input';
+export * from './transaction-plan';
+export * from './transaction-plan-errors';
+export * from './transaction-plan-executor';
+export * from './transaction-plan-result';
+export * from './transaction-planner';

package/src/instruction-plan-input.ts

@@ -0,0 +1,258 @@
+import type { Instruction } from '@solana/instructions';
+
+import {
+    type InstructionPlan,
+    isInstructionPlan,
+    sequentialInstructionPlan,
+    singleInstructionPlan,
+} from './instruction-plan';
+import {
+    isTransactionPlan,
+    sequentialTransactionPlan,
+    SingleTransactionPlan,
+    singleTransactionPlan,
+    TransactionPlan,
+} from './transaction-plan';
+
+/**
+ * A flexible input type that can be used to create an {@link InstructionPlan}.
+ *
+ * This type accepts:
+ * - A single {@link Instruction}.
+ * - An existing {@link InstructionPlan}.
+ * - An array of instructions and/or instruction plans.
+ *
+ * Use the {@link parseInstructionPlanInput} function to convert this input
+ * into a proper {@link InstructionPlan}.
+ *
+ * @example
+ * Using a single instruction.
+ * ```ts
+ * const input: InstructionPlanInput = myInstruction;
+ * ```
+ *
+ * @example
+ * Use as argument type in a function that will parse it into an InstructionPlan.
+ * ```ts
+ * function myFunction(input: InstructionPlanInput) {
+ *   const plan = parseInstructionPlanInput(input);
+ *   // Use the plan...
+ * }
+ * ```
+ *
+ * @see {@link parseInstructionPlanInput}
+ * @see {@link InstructionPlan}
+ */
+export type InstructionPlanInput = Instruction | InstructionPlan | readonly (Instruction | InstructionPlan)[];
+
+/**
+ * Parses an {@link InstructionPlanInput} and returns an {@link InstructionPlan}.
+ *
+ * This function handles the following input types:
+ * - A single {@link Instruction} is wrapped in a {@link SingleInstructionPlan}.
+ * - An existing {@link InstructionPlan} is returned as-is.
+ * - An array with a single element is unwrapped and parsed recursively.
+ * - An array with multiple elements is wrapped in a divisible {@link SequentialInstructionPlan}.
+ *
+ * @param input - The input to parse into an instruction plan.
+ * @return The parsed instruction plan.
+ *
+ * @example
+ * Parsing a single instruction.
+ * ```ts
+ * const plan = parseInstructionPlanInput(myInstruction);
+ * // Equivalent to: singleInstructionPlan(myInstruction)
+ * ```
+ *
+ * @example
+ * Parsing an array of instructions.
+ * ```ts
+ * const plan = parseInstructionPlanInput([instructionA, instructionB]);
+ * // Equivalent to: sequentialInstructionPlan([instructionA, instructionB])
+ * ```
+ *
+ * @example
+ * Parsing a mixed array with nested plans.
+ * ```ts
+ * const plan = parseInstructionPlanInput([
+ *   instructionA,
+ *   parallelInstructionPlan([instructionB, instructionC]),
+ * ]);
+ * // Returns a sequential plan containing:
+ * // - A single instruction plan for instructionA.
+ * // - The parallel plan for instructionB and instructionC.
+ * ```
+ *
+ * @example
+ * Single-element arrays are unwrapped.
+ * ```ts
+ * const plan = parseInstructionPlanInput([myInstruction]);
+ * // Equivalent to: singleInstructionPlan(myInstruction)
+ * ```
+ *
+ * @see {@link InstructionPlanInput}
+ * @see {@link InstructionPlan}
+ */
+export function parseInstructionPlanInput(input: InstructionPlanInput): InstructionPlan {
+    if (Array.isArray(input) && input.length === 1) {
+        return parseInstructionPlanInput(input[0]);
+    }
+    if (Array.isArray(input)) {
+        return sequentialInstructionPlan(input.map(parseInstructionPlanInput));
+    }
+    return isInstructionPlan(input) ? input : singleInstructionPlan(input as Instruction);
+}
+
+/**
+ * A flexible input type that can be used to create a {@link TransactionPlan}.
+ *
+ * This type accepts:
+ * - A single {@link TransactionMessage} with a fee payer.
+ * - An existing {@link TransactionPlan}.
+ * - An array of transaction messages and/or transaction plans.
+ *
+ * Use the {@link parseTransactionPlanInput} function to convert this input
+ * into a proper {@link TransactionPlan}.
+ *
+ * @example
+ * Using a single transaction message.
+ * ```ts
+ * const input: TransactionPlanInput = myTransactionMessage;
+ * ```
+ *
+ * @example
+ * Use as argument type in a function that will parse it into a TransactionPlan.
+ * ```ts
+ * function myFunction(input: TransactionPlanInput) {
+ *   const plan = parseTransactionPlanInput(input);
+ *   // Use the plan...
+ * }
+ * ```
+ *
+ * @see {@link parseTransactionPlanInput}
+ * @see {@link TransactionPlan}
+ */
+export type TransactionPlanInput =
+    | SingleTransactionPlan['message']
+    | TransactionPlan
+    | readonly (SingleTransactionPlan['message'] | TransactionPlan)[];
+
+/**
+ * Parses a {@link TransactionPlanInput} and returns a {@link TransactionPlan}.
+ *
+ * This function handles the following input types:
+ * - A single {@link TransactionMessage} is wrapped in a {@link SingleTransactionPlan}.
+ * - An existing {@link TransactionPlan} is returned as-is.
+ * - An array with a single element is unwrapped and parsed recursively.
+ * - An array with multiple elements is wrapped in a divisible {@link SequentialTransactionPlan}.
+ *
+ * @param input - The input to parse into a transaction plan.
+ * @return The parsed transaction plan.
+ *
+ * @example
+ * Parsing a single transaction message.
+ * ```ts
+ * const plan = parseTransactionPlanInput(myTransactionMessage);
+ * // Equivalent to: singleTransactionPlan(myTransactionMessage)
+ * ```
+ *
+ * @example
+ * Parsing an array of transaction messages.
+ * ```ts
+ * const plan = parseTransactionPlanInput([messageA, messageB]);
+ * // Equivalent to: sequentialTransactionPlan([messageA, messageB])
+ * ```
+ *
+ * @example
+ * Parsing a mixed array with nested plans.
+ * ```ts
+ * const plan = parseTransactionPlanInput([
+ *   messageA,
+ *   parallelTransactionPlan([messageB, messageC]),
+ * ]);
+ * // Returns a sequential plan containing:
+ * // - A single transaction plan for messageA.
+ * // - The parallel plan for messageB and messageC.
+ * ```
+ *
+ * @example
+ * Single-element arrays are unwrapped.
+ * ```ts
+ * const plan = parseTransactionPlanInput([myTransactionMessage]);
+ * // Equivalent to: singleTransactionPlan(myTransactionMessage)
+ * ```
+ *
+ * @see {@link TransactionPlanInput}
+ * @see {@link TransactionPlan}
+ */
+export function parseTransactionPlanInput(input: TransactionPlanInput): TransactionPlan {
+    if (Array.isArray(input) && input.length === 1) {
+        return parseTransactionPlanInput(input[0]);
+    }
+    if (Array.isArray(input)) {
+        return sequentialTransactionPlan(input.map(item => parseTransactionPlanInput(item)));
+    }
+    return isTransactionPlan(input) ? input : singleTransactionPlan(input as SingleTransactionPlan['message']);
+}
+
+/**
+ * Parses an {@link InstructionPlanInput} or {@link TransactionPlanInput} and
+ * returns the appropriate plan type.
+ *
+ * This function automatically detects whether the input represents instructions
+ * or transactions and delegates to the appropriate parser:
+ * - If the input is a transaction message or transaction plan, it delegates
+ *   to {@link parseTransactionPlanInput}.
+ * - Otherwise, it delegates to {@link parseInstructionPlanInput}.
+ *
+ * @param input - The input to parse, which can be either an instruction-based
+ *   or transaction-based input.
+ * @returns The parsed plan, either an {@link InstructionPlan} or a {@link TransactionPlan}.
+ *
+ * @example
+ * Parsing an instruction input.
+ * ```ts
+ * const plan = parseInstructionOrTransactionPlanInput(myInstruction);
+ * // Returns an InstructionPlan
+ * ```
+ *
+ * @example
+ * Parsing a transaction message input.
+ * ```ts
+ * const plan = parseInstructionOrTransactionPlanInput(myTransactionMessage);
+ * // Returns a TransactionPlan
+ * ```
+ *
+ * @see {@link parseInstructionPlanInput}
+ * @see {@link parseTransactionPlanInput}
+ * @see {@link InstructionPlanInput}
+ * @see {@link TransactionPlanInput}
+ */
+export function parseInstructionOrTransactionPlanInput(
+    input: InstructionPlanInput | TransactionPlanInput,
+): InstructionPlan | TransactionPlan {
+    if (Array.isArray(input) && input.length === 0) {
+        return parseTransactionPlanInput(input);
+    }
+    if (Array.isArray(input) && isTransactionPlanInput(input[0])) {
+        return parseTransactionPlanInput(input as TransactionPlanInput);
+    }
+    if (isTransactionPlanInput(input)) {
+        return parseTransactionPlanInput(input as TransactionPlanInput);
+    }
+    return parseInstructionPlanInput(input as InstructionPlanInput);
+}
+
+function isTransactionPlanInput(value: unknown): value is SingleTransactionPlan['message'] | TransactionPlan {
+    return isTransactionPlan(value) || isTransactionMessage(value);
+}
+
+function isTransactionMessage(value: unknown): value is SingleTransactionPlan['message'] {
+    return (
+        typeof value === 'object' &&
+        value !== null &&
+        'instructions' in value &&
+        Array.isArray(value.instructions) &&
+        'version' in value
+    );
+}