@solana/instruction-plans 3.0.0-canary-20250726063714 → 3.0.0-canary-20250808140800

package/dist/index.browser.cjs

@@ -3,6 +3,7 @@
 var errors = require('@solana/errors');
 var transactionMessages = require('@solana/transaction-messages');
 var transactions = require('@solana/transactions');
+var promises = require('@solana/promises');
 
 // src/instruction-plan.ts
 function parallelInstructionPlan(plans) {
@@ -115,12 +116,393 @@ function getReallocMessagePackerInstructionPlan({
   return getMessagePackerInstructionPlanFromInstructions(instructions);
 }
 
+// src/transaction-plan-result.ts
+function sequentialTransactionPlanResult(plans) {
+  return Object.freeze({ divisible: true, kind: "sequential", plans });
+}
+function nonDivisibleSequentialTransactionPlanResult(plans) {
+  return Object.freeze({ divisible: false, kind: "sequential", plans });
+}
+function parallelTransactionPlanResult(plans) {
+  return Object.freeze({ kind: "parallel", plans });
+}
+function successfulSingleTransactionPlanResult(transactionMessage, transaction, context) {
+  return Object.freeze({
+    kind: "single",
+    message: transactionMessage,
+    status: Object.freeze({ context: context ?? {}, kind: "successful", transaction })
+  });
+}
+function failedSingleTransactionPlanResult(transactionMessage, error) {
+  return Object.freeze({
+    kind: "single",
+    message: transactionMessage,
+    status: Object.freeze({ error, kind: "failed" })
+  });
+}
+function canceledSingleTransactionPlanResult(transactionMessage) {
+  return Object.freeze({
+    kind: "single",
+    message: transactionMessage,
+    status: Object.freeze({ kind: "canceled" })
+  });
+}
+
+// src/transaction-plan-executor.ts
+function createTransactionPlanExecutor(config) {
+  return async (plan, { abortSignal } = {}) => {
+    const context = {
+      ...config,
+      abortSignal,
+      canceled: abortSignal?.aborted ?? false
+    };
+    const cancelHandler = () => {
+      context.canceled = true;
+    };
+    abortSignal?.addEventListener("abort", cancelHandler);
+    const transactionPlanResult = await traverse(plan, context);
+    abortSignal?.removeEventListener("abort", cancelHandler);
+    if (context.canceled) {
+      const abortReason = abortSignal?.aborted ? abortSignal.reason : void 0;
+      const context2 = { cause: findErrorFromTransactionPlanResult(transactionPlanResult) ?? abortReason };
+      Object.defineProperty(context2, "transactionPlanResult", {
+        configurable: false,
+        enumerable: false,
+        value: transactionPlanResult,
+        writable: false
+      });
+      throw new errors.SolanaError(errors.SOLANA_ERROR__INSTRUCTION_PLANS__FAILED_TO_EXECUTE_TRANSACTION_PLAN, context2);
+    }
+    return transactionPlanResult;
+  };
+}
+async function traverse(transactionPlan, context) {
+  const kind = transactionPlan.kind;
+  switch (kind) {
+    case "sequential":
+      return await traverseSequential(transactionPlan, context);
+    case "parallel":
+      return await traverseParallel(transactionPlan, context);
+    case "single":
+      return await traverseSingle(transactionPlan, context);
+    default:
+      throw new errors.SolanaError(errors.SOLANA_ERROR__INVARIANT_VIOLATION__INVALID_TRANSACTION_PLAN_KIND, { kind });
+  }
+}
+async function traverseSequential(transactionPlan, context) {
+  const results = [];
+  for (const subPlan of transactionPlan.plans) {
+    const result = await traverse(subPlan, context);
+    results.push(result);
+  }
+  return transactionPlan.divisible ? sequentialTransactionPlanResult(results) : nonDivisibleSequentialTransactionPlanResult(results);
+}
+async function traverseParallel(transactionPlan, context) {
+  const results = await Promise.all(transactionPlan.plans.map((plan) => traverse(plan, context)));
+  return parallelTransactionPlanResult(results);
+}
+async function traverseSingle(transactionPlan, context) {
+  if (context.canceled) {
+    return canceledSingleTransactionPlanResult(transactionPlan.message);
+  }
+  try {
+    const result = await promises.getAbortablePromise(
+      context.executeTransactionMessage(transactionPlan.message, { abortSignal: context.abortSignal }),
+      context.abortSignal
+    );
+    return successfulSingleTransactionPlanResult(transactionPlan.message, result.transaction, result.context);
+  } catch (error) {
+    context.canceled = true;
+    return failedSingleTransactionPlanResult(transactionPlan.message, error);
+  }
+}
+function findErrorFromTransactionPlanResult(result) {
+  if (result.kind === "single") {
+    return result.status.kind === "failed" ? result.status.error : void 0;
+  }
+  for (const plan of result.plans) {
+    const error = findErrorFromTransactionPlanResult(plan);
+    if (error) {
+      return error;
+    }
+  }
+}
+
+// src/transaction-plan.ts
+function parallelTransactionPlan(plans) {
+  return Object.freeze({ kind: "parallel", plans: parseSingleTransactionPlans(plans) });
+}
+function sequentialTransactionPlan(plans) {
+  return Object.freeze({ divisible: true, kind: "sequential", plans: parseSingleTransactionPlans(plans) });
+}
+function nonDivisibleSequentialTransactionPlan(plans) {
+  return Object.freeze({ divisible: false, kind: "sequential", plans: parseSingleTransactionPlans(plans) });
+}
+function singleTransactionPlan(transactionMessage) {
+  return Object.freeze({ kind: "single", message: transactionMessage });
+}
+function parseSingleTransactionPlans(plans) {
+  return plans.map((plan) => "kind" in plan ? plan : singleTransactionPlan(plan));
+}
+function getAllSingleTransactionPlans(transactionPlan) {
+  if (transactionPlan.kind === "single") {
+    return [transactionPlan];
+  }
+  return transactionPlan.plans.flatMap(getAllSingleTransactionPlans);
+}
+function createTransactionPlanner(config) {
+  return async (instructionPlan, { abortSignal } = {}) => {
+    const plan = await traverse2(instructionPlan, {
+      abortSignal,
+      createTransactionMessage: config.createTransactionMessage,
+      onTransactionMessageUpdated: config.onTransactionMessageUpdated ?? ((msg) => msg),
+      parent: null,
+      parentCandidates: []
+    });
+    if (!plan) {
+      throw new errors.SolanaError(errors.SOLANA_ERROR__INSTRUCTION_PLANS__EMPTY_INSTRUCTION_PLAN);
+    }
+    return freezeTransactionPlan(plan);
+  };
+}
+async function traverse2(instructionPlan, context) {
+  context.abortSignal?.throwIfAborted();
+  const kind = instructionPlan.kind;
+  switch (kind) {
+    case "sequential":
+      return await traverseSequential2(instructionPlan, context);
+    case "parallel":
+      return await traverseParallel2(instructionPlan, context);
+    case "single":
+      return await traverseSingle2(instructionPlan, context);
+    case "messagePacker":
+      return await traverseMessagePacker(instructionPlan, context);
+    default:
+      throw new errors.SolanaError(errors.SOLANA_ERROR__INVARIANT_VIOLATION__INVALID_INSTRUCTION_PLAN_KIND, { kind });
+  }
+}
+async function traverseSequential2(instructionPlan, context) {
+  let candidate = null;
+  const mustEntirelyFitInParentCandidate = context.parent && (context.parent.kind === "parallel" || !instructionPlan.divisible);
+  if (mustEntirelyFitInParentCandidate) {
+    const candidate2 = await selectAndMutateCandidate(
+      context,
+      context.parentCandidates,
+      (message) => fitEntirePlanInsideMessage(instructionPlan, message)
+    );
+    if (candidate2) {
+      return null;
+    }
+  } else {
+    candidate = context.parentCandidates.length > 0 ? context.parentCandidates[0] : null;
+  }
+  const transactionPlans = [];
+  for (const plan of instructionPlan.plans) {
+    const transactionPlan = await traverse2(plan, {
+      ...context,
+      parent: instructionPlan,
+      parentCandidates: candidate ? [candidate] : []
+    });
+    if (transactionPlan) {
+      candidate = getSequentialCandidate(transactionPlan);
+      const newPlans = transactionPlan.kind === "sequential" && (transactionPlan.divisible || !instructionPlan.divisible) ? transactionPlan.plans : [transactionPlan];
+      transactionPlans.push(...newPlans);
+    }
+  }
+  if (transactionPlans.length === 1) {
+    return transactionPlans[0];
+  }
+  if (transactionPlans.length === 0) {
+    return null;
+  }
+  return {
+    divisible: instructionPlan.divisible,
+    kind: "sequential",
+    plans: transactionPlans
+  };
+}
+async function traverseParallel2(instructionPlan, context) {
+  const candidates = [...context.parentCandidates];
+  const transactionPlans = [];
+  const sortedChildren = Array.from(instructionPlan.plans).sort(
+    (a, b) => Number(a.kind === "messagePacker") - Number(b.kind === "messagePacker")
+  );
+  for (const plan of sortedChildren) {
+    const transactionPlan = await traverse2(plan, {
+      ...context,
+      parent: instructionPlan,
+      parentCandidates: candidates
+    });
+    if (transactionPlan) {
+      candidates.push(...getParallelCandidates(transactionPlan));
+      const newPlans = transactionPlan.kind === "parallel" ? transactionPlan.plans : [transactionPlan];
+      transactionPlans.push(...newPlans);
+    }
+  }
+  if (transactionPlans.length === 1) {
+    return transactionPlans[0];
+  }
+  if (transactionPlans.length === 0) {
+    return null;
+  }
+  return { kind: "parallel", plans: transactionPlans };
+}
+async function traverseSingle2(instructionPlan, context) {
+  const predicate = (message2) => transactionMessages.appendTransactionMessageInstructions([instructionPlan.instruction], message2);
+  const candidate = await selectAndMutateCandidate(context, context.parentCandidates, predicate);
+  if (candidate) {
+    return null;
+  }
+  const message = await createNewMessage(context, predicate);
+  return { kind: "single", message };
+}
+async function traverseMessagePacker(instructionPlan, context) {
+  const messagePacker = instructionPlan.getMessagePacker();
+  const transactionPlans = [];
+  const candidates = [...context.parentCandidates];
+  while (!messagePacker.done()) {
+    const candidate = await selectAndMutateCandidate(context, candidates, messagePacker.packMessageToCapacity);
+    if (!candidate) {
+      const message = await createNewMessage(context, messagePacker.packMessageToCapacity);
+      const newPlan = { kind: "single", message };
+      transactionPlans.push(newPlan);
+    }
+  }
+  if (transactionPlans.length === 1) {
+    return transactionPlans[0];
+  }
+  if (transactionPlans.length === 0) {
+    return null;
+  }
+  if (context.parent?.kind === "parallel") {
+    return { kind: "parallel", plans: transactionPlans };
+  }
+  return {
+    divisible: context.parent?.kind === "sequential" ? context.parent.divisible : true,
+    kind: "sequential",
+    plans: transactionPlans
+  };
+}
+function getSequentialCandidate(latestPlan) {
+  if (latestPlan.kind === "single") {
+    return latestPlan;
+  }
+  if (latestPlan.kind === "sequential" && latestPlan.plans.length > 0) {
+    return getSequentialCandidate(latestPlan.plans[latestPlan.plans.length - 1]);
+  }
+  return null;
+}
+function getParallelCandidates(latestPlan) {
+  return getAllSingleTransactionPlans(latestPlan);
+}
+async function selectAndMutateCandidate(context, candidates, predicate) {
+  for (const candidate of candidates) {
+    try {
+      const message = await promises.getAbortablePromise(
+        Promise.resolve(
+          context.onTransactionMessageUpdated(predicate(candidate.message), {
+            abortSignal: context.abortSignal
+          })
+        ),
+        context.abortSignal
+      );
+      if (transactions.getTransactionMessageSize(message) <= transactions.TRANSACTION_SIZE_LIMIT) {
+        candidate.message = message;
+        return candidate;
+      }
+    } catch (error) {
+      if (errors.isSolanaError(error, errors.SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_CANNOT_ACCOMMODATE_PLAN)) ; else {
+        throw error;
+      }
+    }
+  }
+  return null;
+}
+async function createNewMessage(context, predicate) {
+  const newMessage = await promises.getAbortablePromise(
+    Promise.resolve(context.createTransactionMessage({ abortSignal: context.abortSignal })),
+    context.abortSignal
+  );
+  const updatedMessage = await promises.getAbortablePromise(
+    Promise.resolve(
+      context.onTransactionMessageUpdated(predicate(newMessage), { abortSignal: context.abortSignal })
+    ),
+    context.abortSignal
+  );
+  const updatedMessageSize = transactions.getTransactionMessageSize(updatedMessage);
+  if (updatedMessageSize > transactions.TRANSACTION_SIZE_LIMIT) {
+    const newMessageSize = transactions.getTransactionMessageSize(newMessage);
+    throw new errors.SolanaError(errors.SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_CANNOT_ACCOMMODATE_PLAN, {
+      numBytesRequired: updatedMessageSize - newMessageSize,
+      numFreeBytes: transactions.TRANSACTION_SIZE_LIMIT - newMessageSize
+    });
+  }
+  return updatedMessage;
+}
+function freezeTransactionPlan(plan) {
+  const kind = plan.kind;
+  switch (kind) {
+    case "single":
+      return singleTransactionPlan(plan.message);
+    case "sequential":
+      return plan.divisible ? sequentialTransactionPlan(plan.plans.map(freezeTransactionPlan)) : nonDivisibleSequentialTransactionPlan(plan.plans.map(freezeTransactionPlan));
+    case "parallel":
+      return parallelTransactionPlan(plan.plans.map(freezeTransactionPlan));
+    default:
+      throw new errors.SolanaError(errors.SOLANA_ERROR__INVARIANT_VIOLATION__INVALID_TRANSACTION_PLAN_KIND, { kind });
+  }
+}
+function fitEntirePlanInsideMessage(instructionPlan, message) {
+  let newMessage = message;
+  const kind = instructionPlan.kind;
+  switch (kind) {
+    case "sequential":
+    case "parallel":
+      for (const plan of instructionPlan.plans) {
+        newMessage = fitEntirePlanInsideMessage(plan, newMessage);
+      }
+      return newMessage;
+    case "single":
+      newMessage = transactionMessages.appendTransactionMessageInstructions([instructionPlan.instruction], message);
+      const newMessageSize = transactions.getTransactionMessageSize(newMessage);
+      if (newMessageSize > transactions.TRANSACTION_SIZE_LIMIT) {
+        const baseMessageSize = transactions.getTransactionMessageSize(message);
+        throw new errors.SolanaError(errors.SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_CANNOT_ACCOMMODATE_PLAN, {
+          numBytesRequired: newMessageSize - baseMessageSize,
+          numFreeBytes: transactions.TRANSACTION_SIZE_LIMIT - baseMessageSize
+        });
+      }
+      return newMessage;
+    case "messagePacker":
+      const messagePacker = instructionPlan.getMessagePacker();
+      while (!messagePacker.done()) {
+        newMessage = messagePacker.packMessageToCapacity(message);
+      }
+      return newMessage;
+    default:
+      throw new errors.SolanaError(errors.SOLANA_ERROR__INVARIANT_VIOLATION__INVALID_INSTRUCTION_PLAN_KIND, { kind });
+  }
+}
+
+exports.canceledSingleTransactionPlanResult = canceledSingleTransactionPlanResult;
+exports.createTransactionPlanExecutor = createTransactionPlanExecutor;
+exports.createTransactionPlanner = createTransactionPlanner;
+exports.failedSingleTransactionPlanResult = failedSingleTransactionPlanResult;
+exports.getAllSingleTransactionPlans = getAllSingleTransactionPlans;
 exports.getLinearMessagePackerInstructionPlan = getLinearMessagePackerInstructionPlan;
 exports.getMessagePackerInstructionPlanFromInstructions = getMessagePackerInstructionPlanFromInstructions;
 exports.getReallocMessagePackerInstructionPlan = getReallocMessagePackerInstructionPlan;
 exports.nonDivisibleSequentialInstructionPlan = nonDivisibleSequentialInstructionPlan;
+exports.nonDivisibleSequentialTransactionPlan = nonDivisibleSequentialTransactionPlan;
+exports.nonDivisibleSequentialTransactionPlanResult = nonDivisibleSequentialTransactionPlanResult;
 exports.parallelInstructionPlan = parallelInstructionPlan;
+exports.parallelTransactionPlan = parallelTransactionPlan;
+exports.parallelTransactionPlanResult = parallelTransactionPlanResult;
 exports.sequentialInstructionPlan = sequentialInstructionPlan;
+exports.sequentialTransactionPlan = sequentialTransactionPlan;
+exports.sequentialTransactionPlanResult = sequentialTransactionPlanResult;
 exports.singleInstructionPlan = singleInstructionPlan;
+exports.singleTransactionPlan = singleTransactionPlan;
+exports.successfulSingleTransactionPlanResult = successfulSingleTransactionPlanResult;
 //# sourceMappingURL=index.browser.cjs.map
 //# sourceMappingURL=index.browser.cjs.map