@solana/instruction-plans 3.0.0-canary-20250808140605 → 3.0.0-canary-20250808141109

package/dist/types/transaction-plan-result.d.ts

@@ -0,0 +1,303 @@
+import { SolanaError } from '@solana/errors';
+import { BaseTransactionMessage, TransactionMessageWithFeePayer } from '@solana/transaction-messages';
+import { Transaction } from '@solana/transactions';
+/**
+ * The result of executing a transaction plan.
+ *
+ * This is structured as a recursive tree of results that mirrors the structure
+ * of the original transaction plan, capturing the execution status at each level.
+ *
+ * Namely, the following result types are supported:
+ * - {@link SingleTransactionPlanResult} - A result for a single transaction message
+ *   containing its execution status.
+ * - {@link ParallelTransactionPlanResult} - A result containing other results that
+ *   were executed in parallel.
+ * - {@link SequentialTransactionPlanResult} - A result containing other results that
+ *   were executed sequentially. It also retains the divisibility property from the
+ *   original plan.
+ *
+ * @template TContext - The type of the context object that may be passed along with successful results
+ *
+ * @see {@link SingleTransactionPlanResult}
+ * @see {@link ParallelTransactionPlanResult}
+ * @see {@link SequentialTransactionPlanResult}
+ * @see {@link TransactionPlanResultStatus}
+ */
+export type TransactionPlanResult<TContext extends TransactionPlanResultContext = TransactionPlanResultContext> = ParallelTransactionPlanResult<TContext> | SequentialTransactionPlanResult<TContext> | SingleTransactionPlanResult<TContext>;
+/** A context object that may be passed along with successful results. */
+export type TransactionPlanResultContext = Record<number | string | symbol, unknown>;
+/**
+ * A result for a sequential transaction plan.
+ *
+ * This represents the execution result of a {@link SequentialTransactionPlan} and
+ * contains child results that were executed sequentially. It also retains the
+ * divisibility property from the original plan.
+ *
+ * You may use the {@link sequentialTransactionPlanResult} and
+ * {@link nonDivisibleSequentialTransactionPlanResult} helpers to create objects of this type.
+ *
+ * @template TContext - The type of the context object that may be passed along with successful results
+ *
+ * @example
+ * ```ts
+ * const result = sequentialTransactionPlanResult([
+ *   singleResultA,
+ *   singleResultB,
+ * ]);
+ * result satisfies SequentialTransactionPlanResult;
+ * ```
+ *
+ * @example
+ * Non-divisible sequential result.
+ * ```ts
+ * const result = nonDivisibleSequentialTransactionPlanResult([
+ *   singleResultA,
+ *   singleResultB,
+ * ]);
+ * result satisfies SequentialTransactionPlanResult & { divisible: false };
+ * ```
+ *
+ * @see {@link sequentialTransactionPlanResult}
+ * @see {@link nonDivisibleSequentialTransactionPlanResult}
+ */
+export type SequentialTransactionPlanResult<TContext extends TransactionPlanResultContext = TransactionPlanResultContext> = Readonly<{
+    divisible: boolean;
+    kind: 'sequential';
+    plans: TransactionPlanResult<TContext>[];
+}>;
+/**
+ * A result for a parallel transaction plan.
+ *
+ * This represents the execution result of a {@link ParallelTransactionPlan} and
+ * contains child results that were executed in parallel.
+ *
+ * You may use the {@link parallelTransactionPlanResult} helper to create objects of this type.
+ *
+ * @template TContext - The type of the context object that may be passed along with successful results
+ *
+ * @example
+ * ```ts
+ * const result = parallelTransactionPlanResult([
+ *   singleResultA,
+ *   singleResultB,
+ * ]);
+ * result satisfies ParallelTransactionPlanResult;
+ * ```
+ *
+ * @see {@link parallelTransactionPlanResult}
+ */
+export type ParallelTransactionPlanResult<TContext extends TransactionPlanResultContext = TransactionPlanResultContext> = Readonly<{
+    kind: 'parallel';
+    plans: TransactionPlanResult<TContext>[];
+}>;
+/**
+ * A result for a single transaction plan.
+ *
+ * This represents the execution result of a {@link SingleTransactionPlan} and
+ * contains the original transaction message along with its execution status.
+ *
+ * You may use the {@link successfulSingleTransactionPlanResult},
+ * {@link failedSingleTransactionPlanResult}, or {@link canceledSingleTransactionPlanResult}
+ * helpers to create objects of this type.
+ *
+ * @template TContext - The type of the context object that may be passed along with successful results
+ * @template TTransactionMessage - The type of the transaction message
+ *
+ * @example
+ * Successful result with a transaction and context.
+ * ```ts
+ * const result = successfulSingleTransactionPlanResult(
+ *   transactionMessage,
+ *   transaction
+ * );
+ * result satisfies SingleTransactionPlanResult;
+ * ```
+ *
+ * @example
+ * Failed result with an error.
+ * ```ts
+ * const result = failedSingleTransactionPlanResult(
+ *   transactionMessage,
+ *   new SolanaError(SOLANA_ERROR__TRANSACTION_ERROR__INSUFFICIENT_FUNDS_FOR_FEE),
+ * );
+ * result satisfies SingleTransactionPlanResult;
+ * ```
+ *
+ * @example
+ * Canceled result.
+ * ```ts
+ * const result = canceledSingleTransactionPlanResult(transactionMessage);
+ * result satisfies SingleTransactionPlanResult;
+ * ```
+ *
+ * @see {@link successfulSingleTransactionPlanResult}
+ * @see {@link failedSingleTransactionPlanResult}
+ * @see {@link canceledSingleTransactionPlanResult}
+ */
+export type SingleTransactionPlanResult<TContext extends TransactionPlanResultContext = TransactionPlanResultContext, TTransactionMessage extends BaseTransactionMessage & TransactionMessageWithFeePayer = BaseTransactionMessage & TransactionMessageWithFeePayer> = Readonly<{
+    kind: 'single';
+    message: TTransactionMessage;
+    status: TransactionPlanResultStatus<TContext>;
+}>;
+/**
+ * The status of a single transaction plan execution.
+ *
+ * This represents the outcome of executing a single transaction message and can be one of:
+ * - `successful` - The transaction was successfully executed. Contains the transaction
+ *   and an optional context object.
+ * - `failed` - The transaction execution failed. Contains the error that caused the failure.
+ * - `canceled` - The transaction execution was canceled.
+ *
+ * @template TContext - The type of the context object that may be passed along with successful results
+ */
+export type TransactionPlanResultStatus<TContext extends TransactionPlanResultContext = TransactionPlanResultContext> = Readonly<{
+    context: TContext;
+    kind: 'successful';
+    transaction: Transaction;
+}> | Readonly<{
+    error: SolanaError;
+    kind: 'failed';
+}> | Readonly<{
+    kind: 'canceled';
+}>;
+/**
+ * Creates a divisible {@link SequentialTransactionPlanResult} from an array of nested results.
+ *
+ * This function creates a sequential result with the `divisible` property set to `true`,
+ * indicating that the nested plans were executed sequentially but could have been
+ * split into separate transactions or batches.
+ *
+ * @template TContext - The type of the context object that may be passed along with successful results
+ * @param plans - The child results that were executed sequentially
+ *
+ * @example
+ * ```ts
+ * const result = sequentialTransactionPlanResult([
+ *   singleResultA,
+ *   singleResultB,
+ * ]);
+ * result satisfies SequentialTransactionPlanResult & { divisible: true };
+ * ```
+ *
+ * @see {@link SequentialTransactionPlanResult}
+ */
+export declare function sequentialTransactionPlanResult<TContext extends TransactionPlanResultContext = TransactionPlanResultContext>(plans: TransactionPlanResult<TContext>[]): SequentialTransactionPlanResult<TContext> & {
+    divisible: true;
+};
+/**
+ * Creates a non-divisible {@link SequentialTransactionPlanResult} from an array of nested results.
+ *
+ * This function creates a sequential result with the `divisible` property set to `false`,
+ * indicating that the nested plans were executed sequentially and could not have been
+ * split into separate transactions or batches (e.g., they were executed as a transaction bundle).
+ *
+ * @template TContext - The type of the context object that may be passed along with successful results
+ * @param plans - The child results that were executed sequentially
+ *
+ * @example
+ * ```ts
+ * const result = nonDivisibleSequentialTransactionPlanResult([
+ *   singleResultA,
+ *   singleResultB,
+ * ]);
+ * result satisfies SequentialTransactionPlanResult & { divisible: false };
+ * ```
+ *
+ * @see {@link SequentialTransactionPlanResult}
+ */
+export declare function nonDivisibleSequentialTransactionPlanResult<TContext extends TransactionPlanResultContext = TransactionPlanResultContext>(plans: TransactionPlanResult<TContext>[]): SequentialTransactionPlanResult<TContext> & {
+    divisible: false;
+};
+/**
+ * Creates a {@link ParallelTransactionPlanResult} from an array of nested results.
+ *
+ * This function creates a parallel result indicating that the nested plans
+ * were executed in parallel.
+ *
+ * @template TContext - The type of the context object that may be passed along with successful results
+ * @param plans - The child results that were executed in parallel
+ *
+ * @example
+ * ```ts
+ * const result = parallelTransactionPlanResult([
+ *   singleResultA,
+ *   singleResultB,
+ * ]);
+ * result satisfies ParallelTransactionPlanResult;
+ * ```
+ *
+ * @see {@link ParallelTransactionPlanResult}
+ */
+export declare function parallelTransactionPlanResult<TContext extends TransactionPlanResultContext = TransactionPlanResultContext>(plans: TransactionPlanResult<TContext>[]): ParallelTransactionPlanResult<TContext>;
+/**
+ * Creates a successful {@link SingleTransactionPlanResult} from a transaction message and transaction.
+ *
+ * This function creates a single result with a 'successful' status, indicating that
+ * the transaction was successfully executed. It also includes the original transaction
+ * message, the executed transaction, and an optional context object.
+ *
+ * @template TContext - The type of the context object
+ * @template TTransactionMessage - The type of the transaction message
+ * @param transactionMessage - The original transaction message
+ * @param transaction - The successfully executed transaction
+ * @param context - Optional context object to be included with the result
+ *
+ * @example
+ * ```ts
+ * const result = successfulSingleTransactionPlanResult(
+ *   transactionMessage,
+ *   transaction
+ * );
+ * result satisfies SingleTransactionPlanResult;
+ * ```
+ *
+ * @see {@link SingleTransactionPlanResult}
+ */
+export declare function successfulSingleTransactionPlanResult<TContext extends TransactionPlanResultContext = TransactionPlanResultContext, TTransactionMessage extends BaseTransactionMessage & TransactionMessageWithFeePayer = BaseTransactionMessage & TransactionMessageWithFeePayer>(transactionMessage: TTransactionMessage, transaction: Transaction, context?: TContext): SingleTransactionPlanResult<TContext, TTransactionMessage>;
+/**
+ * Creates a failed {@link SingleTransactionPlanResult} from a transaction message and error.
+ *
+ * This function creates a single result with a 'failed' status, indicating that
+ * the transaction execution failed. It includes the original transaction message
+ * and the error that caused the failure.
+ *
+ * @template TContext - The type of the context object (not used in failed results)
+ * @template TTransactionMessage - The type of the transaction message
+ * @param transactionMessage - The original transaction message
+ * @param error - The error that caused the transaction to fail
+ *
+ * @example
+ * ```ts
+ * const result = failedSingleTransactionPlanResult(
+ *   transactionMessage,
+ *   new SolanaError({
+ *     code: 123,
+ *     message: 'Transaction simulation failed',
+ *   }),
+ * );
+ * result satisfies SingleTransactionPlanResult;
+ * ```
+ *
+ * @see {@link SingleTransactionPlanResult}
+ */
+export declare function failedSingleTransactionPlanResult<TContext extends TransactionPlanResultContext = TransactionPlanResultContext, TTransactionMessage extends BaseTransactionMessage & TransactionMessageWithFeePayer = BaseTransactionMessage & TransactionMessageWithFeePayer>(transactionMessage: TTransactionMessage, error: SolanaError): SingleTransactionPlanResult<TContext, TTransactionMessage>;
+/**
+ * Creates a canceled {@link SingleTransactionPlanResult} from a transaction message.
+ *
+ * This function creates a single result with a 'canceled' status, indicating that
+ * the transaction execution was canceled. It includes the original transaction message.
+ *
+ * @template TContext - The type of the context object (not used in canceled results)
+ * @template TTransactionMessage - The type of the transaction message
+ * @param transactionMessage - The original transaction message
+ *
+ * @example
+ * ```ts
+ * const result = canceledSingleTransactionPlanResult(transactionMessage);
+ * result satisfies SingleTransactionPlanResult;
+ * ```
+ *
+ * @see {@link SingleTransactionPlanResult}
+ */
+export declare function canceledSingleTransactionPlanResult<TContext extends TransactionPlanResultContext = TransactionPlanResultContext, TTransactionMessage extends BaseTransactionMessage & TransactionMessageWithFeePayer = BaseTransactionMessage & TransactionMessageWithFeePayer>(transactionMessage: TTransactionMessage): SingleTransactionPlanResult<TContext, TTransactionMessage>;
+//# sourceMappingURL=transaction-plan-result.d.ts.map

package/dist/types/transaction-plan-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction-plan-result.d.ts","sourceRoot":"","sources":["../../src/transaction-plan-result.ts"],"names":[],"mappings":"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"}

package/dist/types/transaction-plan.d.ts

@@ -0,0 +1,243 @@
+import { BaseTransactionMessage, TransactionMessageWithFeePayer } from '@solana/transaction-messages';
+/**
+ * A set of transaction messages with constraints on how they can be executed.
+ *
+ * This is structured as a recursive tree of plans to allow for
+ * parallel execution, sequential execution and combinations of both.
+ *
+ * Namely, the following plans are supported:
+ * - {@link SingleTransactionPlan} - A plan that contains a single transaction message.
+ *   This is the simplest leaf in this tree.
+ * - {@link ParallelTransactionPlan} - A plan that contains other plans that
+ *   can be executed in parallel.
+ * - {@link SequentialTransactionPlan} - A plan that contains other plans that
+ *   must be executed sequentially. It also defines whether the plan is divisible
+ *   meaning that transaction messages inside it can be split into separate batches.
+ *
+ * Helpers are provided for each of these plans to make it easier to create them.
+ *
+ * @example
+ * ```ts
+ * const myTransactionPlan: TransactionPlan = parallelTransactionPlan([
+ *   sequentialTransactionPlan([messageA, messageB]),
+ *   messageC,
+ * ]);
+ * ```
+ *
+ * @see {@link SingleTransactionPlan}
+ * @see {@link ParallelTransactionPlan}
+ * @see {@link SequentialTransactionPlan}
+ */
+export type TransactionPlan = ParallelTransactionPlan | SequentialTransactionPlan | SingleTransactionPlan;
+/**
+ * A plan wrapping other plans that must be executed sequentially.
+ *
+ * It also defines whether nested plans are divisible — meaning that
+ * the transaction messages inside them can be split into separate batches.
+ * When `divisible` is `false`, the transaction messages inside the plan should
+ * all be executed atomically — usually in a transaction bundle.
+ *
+ * You may use the {@link sequentialTransactionPlan} and {@link nonDivisibleSequentialTransactionPlan}
+ * helpers to create objects of this type.
+ *
+ * @example
+ * Simple sequential plan with two transaction messages.
+ * ```ts
+ * const plan = sequentialTransactionPlan([messageA, messageB]);
+ * plan satisfies SequentialTransactionPlan;
+ * ```
+ *
+ * @example
+ * Non-divisible sequential plan with two transaction messages.
+ * ```ts
+ * const plan = nonDivisibleSequentialTransactionPlan([messageA, messageB]);
+ * plan satisfies SequentialTransactionPlan & { divisible: false };
+ * ```
+ *
+ * @example
+ * Sequential plan with nested parallel plans.
+ * Here, messages A and B can be executed in parallel, but they must both be finalized
+ * before messages C and D can be sent — which can also be executed in parallel.
+ * ```ts
+ * const plan = sequentialTransactionPlan([
+ *   parallelTransactionPlan([messageA, messageB]),
+ *   parallelTransactionPlan([messageC, messageD]),
+ * ]);
+ * ```
+ *
+ * @see {@link sequentialTransactionPlan}
+ * @see {@link nonDivisibleSequentialTransactionPlan}
+ */
+export type SequentialTransactionPlan = Readonly<{
+    divisible: boolean;
+    kind: 'sequential';
+    plans: TransactionPlan[];
+}>;
+/**
+ * A plan wrapping other plans that can be executed in parallel.
+ *
+ * This means direct children of this plan can be executed in separate
+ * parallel transactions without causing any side effects.
+ * However, the children themselves can define additional constraints
+ * for that specific branch of the tree — such as the {@link SequentialTransactionPlan}.
+ *
+ * You may use the {@link parallelTransactionPlan} helper to create objects of this type.
+ *
+ * @example
+ * Simple parallel plan with two transaction messages.
+ * ```ts
+ * const plan = parallelTransactionPlan([messageA, messageB]);
+ * plan satisfies ParallelTransactionPlan;
+ * ```
+ *
+ * @example
+ * Parallel plan with nested sequential plans.
+ * Here, messages A and B must be executed sequentially and so must messages C and D,
+ * but both pairs can be executed in parallel.
+ * ```ts
+ * const plan = parallelTransactionPlan([
+ *   sequentialTransactionPlan([messageA, messageB]),
+ *   sequentialTransactionPlan([messageC, messageD]),
+ * ]);
+ * plan satisfies ParallelTransactionPlan;
+ * ```
+ *
+ * @see {@link parallelTransactionPlan}
+ */
+export type ParallelTransactionPlan = Readonly<{
+    kind: 'parallel';
+    plans: TransactionPlan[];
+}>;
+/**
+ * A plan that contains a single transaction message.
+ *
+ * This is a simple transaction message wrapper that transforms a message into a plan.
+ *
+ * You may use the {@link singleTransactionPlan} helper to create objects of this type.
+ *
+ * @example
+ * ```ts
+ * const plan = singleTransactionPlan(transactionMessage);
+ * plan satisfies SingleTransactionPlan;
+ * ```
+ *
+ * @see {@link singleTransactionPlan}
+ */
+export type SingleTransactionPlan<TTransactionMessage extends BaseTransactionMessage & TransactionMessageWithFeePayer = BaseTransactionMessage & TransactionMessageWithFeePayer> = Readonly<{
+    kind: 'single';
+    message: TTransactionMessage;
+}>;
+/**
+ * Creates a {@link ParallelTransactionPlan} from an array of nested plans.
+ *
+ * It can accept {@link TransactionMessage} objects directly, which will be wrapped
+ * in {@link SingleTransactionPlan | SingleTransactionPlans} automatically.
+ *
+ * @example
+ * Using explicit {@link SingleTransactionPlan | SingleTransactionPlans}.
+ * ```ts
+ * const plan = parallelTransactionPlan([
+ *   singleTransactionPlan(messageA),
+ *   singleTransactionPlan(messageB),
+ * ]);
+ * ```
+ *
+ * @example
+ * Using {@link TransactionMessage | TransactionMessages} directly.
+ * ```ts
+ * const plan = parallelTransactionPlan([messageA, messageB]);
+ * ```
+ *
+ * @see {@link ParallelTransactionPlan}
+ */
+export declare function parallelTransactionPlan(plans: (TransactionPlan | (BaseTransactionMessage & TransactionMessageWithFeePayer))[]): ParallelTransactionPlan;
+/**
+ * Creates a divisible {@link SequentialTransactionPlan} from an array of nested plans.
+ *
+ * It can accept {@link TransactionMessage} objects directly, which will be wrapped
+ * in {@link SingleTransactionPlan | SingleTransactionPlans} automatically.
+ *
+ * @example
+ * Using explicit {@link SingleTransactionPlan | SingleTransactionPlans}.
+ * ```ts
+ * const plan = sequentialTransactionPlan([
+ *   singleTransactionPlan(messageA),
+ *   singleTransactionPlan(messageB),
+ * ]);
+ * ```
+ *
+ * @example
+ * Using {@link TransactionMessage | TransactionMessages} directly.
+ * ```ts
+ * const plan = sequentialTransactionPlan([messageA, messageB]);
+ * ```
+ *
+ * @see {@link SequentialTransactionPlan}
+ */
+export declare function sequentialTransactionPlan(plans: (TransactionPlan | (BaseTransactionMessage & TransactionMessageWithFeePayer))[]): SequentialTransactionPlan & {
+    divisible: true;
+};
+/**
+ * Creates a non-divisible {@link SequentialTransactionPlan} from an array of nested plans.
+ *
+ * It can accept {@link TransactionMessage} objects directly, which will be wrapped
+ * in {@link SingleTransactionPlan | SingleTransactionPlans} automatically.
+ *
+ * @example
+ * Using explicit {@link SingleTransactionPlan | SingleTransactionPlans}.
+ * ```ts
+ * const plan = nonDivisibleSequentialTransactionPlan([
+ *   singleTransactionPlan(messageA),
+ *   singleTransactionPlan(messageB),
+ * ]);
+ * ```
+ *
+ * @example
+ * Using {@link TransactionMessage | TransactionMessages} directly.
+ * ```ts
+ * const plan = nonDivisibleSequentialTransactionPlan([messageA, messageB]);
+ * ```
+ *
+ * @see {@link SequentialTransactionPlan}
+ */
+export declare function nonDivisibleSequentialTransactionPlan(plans: (TransactionPlan | (BaseTransactionMessage & TransactionMessageWithFeePayer))[]): SequentialTransactionPlan & {
+    divisible: false;
+};
+/**
+ * Creates a {@link SingleTransactionPlan} from a {@link TransactionMessage} object.
+ *
+ * @example
+ * ```ts
+ * const plan = singleTransactionPlan(transactionMessage);
+ * plan satisfies SingleTransactionPlan;
+ * ```
+ *
+ * @see {@link SingleTransactionPlan}
+ */
+export declare function singleTransactionPlan<TTransactionMessage extends BaseTransactionMessage & TransactionMessageWithFeePayer = BaseTransactionMessage & TransactionMessageWithFeePayer>(transactionMessage: TTransactionMessage): SingleTransactionPlan<TTransactionMessage>;
+/**
+ * Retrieves all individual {@link SingleTransactionPlan} instances from a transaction plan tree.
+ *
+ * This function recursively traverses any nested structure of transaction plans and extracts
+ * all the single transaction plans they contain. It's useful when you need to access all
+ * the actual transaction messages that will be executed, regardless of their organization
+ * in the plan tree (parallel or sequential).
+ *
+ * @param transactionPlan - The transaction plan to extract single plans from
+ * @returns An array of all single transaction plans contained in the tree
+ *
+ * @example
+ * ```ts
+ * const plan = parallelTransactionPlan([
+ *   sequentialTransactionPlan([messageA, messageB]),
+ *   nonDivisibleSequentialTransactionPlan([messageC, messageD]),
+ *   messageE,
+ * ]);
+ *
+ * const singlePlans = getAllSingleTransactionPlans(plan);
+ * // Array of `SingleTransactionPlan` containing:
+ * // messageA, messageB, messageC and messageD.
+ * ```
+ */
+export declare function getAllSingleTransactionPlans(transactionPlan: TransactionPlan): SingleTransactionPlan[];
+//# sourceMappingURL=transaction-plan.d.ts.map

package/dist/types/transaction-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction-plan.d.ts","sourceRoot":"","sources":["../../src/transaction-plan.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,8BAA8B,EAAE,MAAM,8BAA8B,CAAC;AAEtG;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,MAAM,eAAe,GAAG,uBAAuB,GAAG,yBAAyB,GAAG,qBAAqB,CAAC;AAE1G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,MAAM,yBAAyB,GAAG,QAAQ,CAAC;IAC7C,SAAS,EAAE,OAAO,CAAC;IACnB,IAAI,EAAE,YAAY,CAAC;IACnB,KAAK,EAAE,eAAe,EAAE,CAAC;CAC5B,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC3C,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,eAAe,EAAE,CAAC;CAC5B,CAAC,CAAC;AAEH;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,qBAAqB,CAC7B,mBAAmB,SAAS,sBAAsB,GAAG,8BAA8B,GAAG,sBAAsB,GACxG,8BAA8B,IAClC,QAAQ,CAAC;IACT,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,EAAE,mBAAmB,CAAC;CAChC,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,uBAAuB,CACnC,KAAK,EAAE,CAAC,eAAe,GAAG,CAAC,sBAAsB,GAAG,8BAA8B,CAAC,CAAC,EAAE,GACvF,uBAAuB,CAEzB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,yBAAyB,CACrC,KAAK,EAAE,CAAC,eAAe,GAAG,CAAC,sBAAsB,GAAG,8BAA8B,CAAC,CAAC,EAAE,GACvF,yBAAyB,GAAG;IAAE,SAAS,EAAE,IAAI,CAAA;CAAE,CAEjD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,qCAAqC,CACjD,KAAK,EAAE,CAAC,eAAe,GAAG,CAAC,sBAAsB,GAAG,8BAA8B,CAAC,CAAC,EAAE,GACvF,yBAAyB,GAAG;IAAE,SAAS,EAAE,KAAK,CAAA;CAAE,CAElD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACjC,mBAAmB,SAAS,sBAAsB,GAAG,8BAA8B,GAAG,sBAAsB,GACxG,8BAA8B,EACpC,kBAAkB,EAAE,mBAAmB,GAAG,qBAAqB,CAAC,mBAAmB,CAAC,CAErF;AAQD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,4BAA4B,CAAC,eAAe,EAAE,eAAe,GAAG,qBAAqB,EAAE,CAKtG"}

package/dist/types/transaction-planner.d.ts

@@ -0,0 +1,62 @@
+import { BaseTransactionMessage, TransactionMessageWithFeePayer } from '@solana/transaction-messages';
+import { InstructionPlan } from './instruction-plan';
+import { TransactionPlan } from './transaction-plan';
+/**
+ * Plans one or more transactions according to the provided instruction plan.
+ *
+ * @param instructionPlan - The instruction plan to be planned and executed.
+ * @param config - Optional configuration object that can include an `AbortSignal` to cancel the planning process.
+ *
+ * @see {@link InstructionPlan}
+ * @see {@link TransactionPlan}
+ */
+export type TransactionPlanner = (instructionPlan: InstructionPlan, config?: {
+    abortSignal?: AbortSignal;
+}) => Promise<TransactionPlan>;
+type CreateTransactionMessage = (config?: {
+    abortSignal?: AbortSignal;
+}) => Promise<BaseTransactionMessage & TransactionMessageWithFeePayer> | (BaseTransactionMessage & TransactionMessageWithFeePayer);
+type OnTransactionMessageUpdated = <TTransactionMessage extends BaseTransactionMessage & TransactionMessageWithFeePayer>(transactionMessage: TTransactionMessage, config?: {
+    abortSignal?: AbortSignal;
+}) => Promise<TTransactionMessage> | TTransactionMessage;
+/**
+ * Configuration object for creating a new transaction planner.
+ *
+ * @see {@link createTransactionPlanner}
+ */
+export type TransactionPlannerConfig = {
+    /** Called whenever a new transaction message is needed. */
+    createTransactionMessage: CreateTransactionMessage;
+    /**
+     * Called whenever a transaction message is updated — e.g. new instructions were added.
+     * This function must return the updated transaction message back — even if no changes were made.
+     */
+    onTransactionMessageUpdated?: OnTransactionMessageUpdated;
+};
+/**
+ * Creates a new transaction planner based on the provided configuration.
+ *
+ * At the very least, the `createTransactionMessage` function must be provided.
+ * This function is used to create new transaction messages whenever needed.
+ *
+ * Additionally, the `onTransactionMessageUpdated` function can be provided
+ * to update transaction messages during the planning process. This function will
+ * be called whenever a transaction message is updated, e.g. when new instructions
+ * are added to a transaction message. It accepts the updated transaction message
+ * and must return a transaction message back, even if no changes were made.
+ *
+ * @example
+ * ```ts
+ * const transactionPlanner = createTransactionPlanner({
+ *   createTransactionMessage: () => pipe(
+ *     createTransactionMessage({ version: 0 }),
+ *     message => setTransactionMessageFeePayerSigner(mySigner, message),
+ *   )
+ * });
+ * ```
+ *
+ * @see {@link TransactionPlannerConfig}
+ */
+export declare function createTransactionPlanner(config: TransactionPlannerConfig): TransactionPlanner;
+export {};
+//# sourceMappingURL=transaction-planner.d.ts.map

package/dist/types/transaction-planner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction-planner.d.ts","sourceRoot":"","sources":["../../src/transaction-planner.ts"],"names":[],"mappings":"AASA,OAAO,EAEH,sBAAsB,EACtB,8BAA8B,EACjC,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EACH,eAAe,EAKlB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAOH,eAAe,EAClB,MAAM,oBAAoB,CAAC;AAE5B;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAC7B,eAAe,EAAE,eAAe,EAChC,MAAM,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,WAAW,CAAA;CAAE,KACrC,OAAO,CAAC,eAAe,CAAC,CAAC;AAI9B,KAAK,wBAAwB,GAAG,CAAC,MAAM,CAAC,EAAE;IACtC,WAAW,CAAC,EAAE,WAAW,CAAC;CAC7B,KACK,OAAO,CAAC,sBAAsB,GAAG,8BAA8B,CAAC,GAChE,CAAC,sBAAsB,GAAG,8BAA8B,CAAC,CAAC;AAEhE,KAAK,2BAA2B,GAAG,CAC/B,mBAAmB,SAAS,sBAAsB,GAAG,8BAA8B,EAEnF,kBAAkB,EAAE,mBAAmB,EACvC,MAAM,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,WAAW,CAAA;CAAE,KACrC,OAAO,CAAC,mBAAmB,CAAC,GAAG,mBAAmB,CAAC;AAExD;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACnC,2DAA2D;IAC3D,wBAAwB,EAAE,wBAAwB,CAAC;IACnD;;;OAGG;IACH,2BAA2B,CAAC,EAAE,2BAA2B,CAAC;CAC7D,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,wBAAwB,GAAG,kBAAkB,CAgB7F"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solana/instruction-plans",
-  "version": "3.0.0-canary-20250808140605",
+  "version": "3.0.0-canary-20250808141109",
   "description": "Construct, plan and execute transactions from multiple instructions.",
   "exports": {
     "edge-light": {
@@ -54,11 +54,11 @@
     "maintained node versions"
   ],
   "dependencies": {
-    "@solana/errors": "3.0.0-canary-20250808140605",
-    "@solana/instructions": "3.0.0-canary-20250808140605",
-    "@solana/promises": "3.0.0-canary-20250808140605",
-    "@solana/transaction-messages": "3.0.0-canary-20250808140605",
-    "@solana/transactions": "3.0.0-canary-20250808140605"
+    "@solana/errors": "3.0.0-canary-20250808141109",
+    "@solana/instructions": "3.0.0-canary-20250808141109",
+    "@solana/promises": "3.0.0-canary-20250808141109",
+    "@solana/transactions": "3.0.0-canary-20250808141109",
+    "@solana/transaction-messages": "3.0.0-canary-20250808141109"
   },
   "peerDependencies": {
     "typescript": ">=5.3.3"