@solana/instruction-plans 0.0.0 → 3.0.0-canary-20250718212840

package/dist/index.node.cjs

@@ -0,0 +1,126 @@
+'use strict';
+
+var errors = require('@solana/errors');
+var transactionMessages = require('@solana/transaction-messages');
+var transactions = require('@solana/transactions');
+
+// src/instruction-plan.ts
+function parallelInstructionPlan(plans) {
+  return Object.freeze({
+    kind: "parallel",
+    plans: parseSingleInstructionPlans(plans)
+  });
+}
+function sequentialInstructionPlan(plans) {
+  return Object.freeze({
+    divisible: true,
+    kind: "sequential",
+    plans: parseSingleInstructionPlans(plans)
+  });
+}
+function nonDivisibleSequentialInstructionPlan(plans) {
+  return Object.freeze({
+    divisible: false,
+    kind: "sequential",
+    plans: parseSingleInstructionPlans(plans)
+  });
+}
+function singleInstructionPlan(instruction) {
+  return Object.freeze({ instruction, kind: "single" });
+}
+function parseSingleInstructionPlans(plans) {
+  return plans.map((plan) => "kind" in plan ? plan : singleInstructionPlan(plan));
+}
+function getLinearMessagePackerInstructionPlan({
+  getInstruction,
+  totalLength: totalBytes
+}) {
+  return Object.freeze({
+    getMessagePacker: () => {
+      let offset = 0;
+      return Object.freeze({
+        done: () => offset >= totalBytes,
+        packMessageToCapacity: (message) => {
+          if (offset >= totalBytes) {
+            throw new errors.SolanaError(errors.SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_PACKER_ALREADY_COMPLETE);
+          }
+          const messageSizeWithBaseInstruction = transactions.getTransactionMessageSize(
+            transactionMessages.appendTransactionMessageInstruction(getInstruction(offset, 0), message)
+          );
+          const freeSpace = transactions.TRANSACTION_SIZE_LIMIT - messageSizeWithBaseInstruction - 1;
+          if (freeSpace <= 0) {
+            const messageSize = transactions.getTransactionMessageSize(message);
+            throw new errors.SolanaError(errors.SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_CANNOT_ACCOMMODATE_PLAN, {
+              // (+1) We need to pack at least one byte of data otherwise
+              // there is no point packing the base instruction alone.
+              numBytesRequired: messageSizeWithBaseInstruction - messageSize + 1,
+              // (-1) Leeway for shortU16 numbers in transaction headers.
+              numFreeBytes: transactions.TRANSACTION_SIZE_LIMIT - messageSize - 1
+            });
+          }
+          const length = Math.min(totalBytes - offset, freeSpace);
+          const instruction = getInstruction(offset, length);
+          offset += length;
+          return transactionMessages.appendTransactionMessageInstruction(instruction, message);
+        }
+      });
+    },
+    kind: "messagePacker"
+  });
+}
+function getMessagePackerInstructionPlanFromInstructions(instructions) {
+  return Object.freeze({
+    getMessagePacker: () => {
+      let instructionIndex = 0;
+      return Object.freeze({
+        done: () => instructionIndex >= instructions.length,
+        packMessageToCapacity: (message) => {
+          if (instructionIndex >= instructions.length) {
+            throw new errors.SolanaError(errors.SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_PACKER_ALREADY_COMPLETE);
+          }
+          const originalMessageSize = transactions.getTransactionMessageSize(message);
+          for (let index = instructionIndex; index < instructions.length; index++) {
+            message = transactionMessages.appendTransactionMessageInstruction(instructions[index], message);
+            const messageSize = transactions.getTransactionMessageSize(message);
+            if (messageSize > transactions.TRANSACTION_SIZE_LIMIT) {
+              if (index === instructionIndex) {
+                throw new errors.SolanaError(
+                  errors.SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_CANNOT_ACCOMMODATE_PLAN,
+                  {
+                    numBytesRequired: messageSize - originalMessageSize,
+                    numFreeBytes: transactions.TRANSACTION_SIZE_LIMIT - originalMessageSize
+                  }
+                );
+              }
+              instructionIndex = index;
+              return message;
+            }
+          }
+          instructionIndex = instructions.length;
+          return message;
+        }
+      });
+    },
+    kind: "messagePacker"
+  });
+}
+var REALLOC_LIMIT = 10240;
+function getReallocMessagePackerInstructionPlan({
+  getInstruction,
+  totalSize
+}) {
+  const numberOfInstructions = Math.ceil(totalSize / REALLOC_LIMIT);
+  const lastInstructionSize = totalSize % REALLOC_LIMIT;
+  const instructions = new Array(numberOfInstructions).fill(0).map((_, i) => getInstruction(i === numberOfInstructions - 1 ? lastInstructionSize : REALLOC_LIMIT));
+  return getMessagePackerInstructionPlanFromInstructions(instructions);
+}
+
+exports.getLinearMessagePackerInstructionPlan = getLinearMessagePackerInstructionPlan;
+exports.getMessagePackerInstructionPlanFromInstructions = getMessagePackerInstructionPlanFromInstructions;
+exports.getReallocMessagePackerInstructionPlan = getReallocMessagePackerInstructionPlan;
+exports.nonDivisibleSequentialInstructionPlan = nonDivisibleSequentialInstructionPlan;
+exports.parallelInstructionPlan = parallelInstructionPlan;
+exports.sequentialInstructionPlan = sequentialInstructionPlan;
+exports.singleInstructionPlan = singleInstructionPlan;
+//# sourceMappingURL=index.node.cjs.map
+//# sourceMappingURL=index.node.cjs.map

package/dist/index.node.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/instruction-plan.ts"],"names":["SolanaError","SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_PACKER_ALREADY_COMPLETE","getTransactionMessageSize","appendTransactionMessageInstruction","TRANSACTION_SIZE_LIMIT","SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_CANNOT_ACCOMMODATE_PLAN"],"mappings":";;;;;;;AAkRO,SAAS,wBAAwB,KAAmE,EAAA;AACvG,EAAA,OAAO,OAAO,MAAO,CAAA;AAAA,IACjB,IAAM,EAAA,UAAA;AAAA,IACN,KAAA,EAAO,4BAA4B,KAAK;AAAA,GAC3C,CAAA;AACL;AAuBO,SAAS,0BACZ,KAC+C,EAAA;AAC/C,EAAA,OAAO,OAAO,MAAO,CAAA;AAAA,IACjB,SAAW,EAAA,IAAA;AAAA,IACX,IAAM,EAAA,YAAA;AAAA,IACN,KAAA,EAAO,4BAA4B,KAAK;AAAA,GAC3C,CAAA;AACL;AAuBO,SAAS,sCACZ,KACgD,EAAA;AAChD,EAAA,OAAO,OAAO,MAAO,CAAA;AAAA,IACjB,SAAW,EAAA,KAAA;AAAA,IACX,IAAM,EAAA,YAAA;AAAA,IACN,KAAA,EAAO,4BAA4B,KAAK;AAAA,GAC3C,CAAA;AACL;AAYO,SAAS,sBAAsB,WAAiD,EAAA;AACnF,EAAA,OAAO,OAAO,MAAO,CAAA,EAAE,WAAa,EAAA,IAAA,EAAM,UAAU,CAAA;AACxD;AAEA,SAAS,4BAA4B,KAA6D,EAAA;AAC9F,EAAO,OAAA,KAAA,CAAM,IAAI,CAAS,IAAA,KAAA,MAAA,IAAU,OAAO,IAAO,GAAA,qBAAA,CAAsB,IAAI,CAAE,CAAA;AAClF;AAiCO,SAAS,qCAAsC,CAAA;AAAA,EAClD,cAAA;AAAA,EACA,WAAa,EAAA;AACjB,CAGiC,EAAA;AAC7B,EAAA,OAAO,OAAO,MAAO,CAAA;AAAA,IACjB,kBAAkB,MAAM;AACpB,MAAA,IAAI,MAAS,GAAA,CAAA;AACb,MAAA,OAAO,OAAO,MAAO,CAAA;AAAA,QACjB,IAAA,EAAM,MAAM,MAAU,IAAA,UAAA;AAAA,QACtB,qBAAA,EAAuB,CAAC,OAAqE,KAAA;AACzF,UAAA,IAAI,UAAU,UAAY,EAAA;AACtB,YAAM,MAAA,IAAIA,mBAAYC,uEAAgE,CAAA;AAAA;AAG1F,UAAA,MAAM,8BAAiC,GAAAC,sCAAA;AAAA,YACnCC,uDAAoC,CAAA,cAAA,CAAe,MAAQ,EAAA,CAAC,GAAG,OAAO;AAAA,WAC1E;AACA,UAAM,MAAA,SAAA,GACFC,sCACA,8BACA,GAAA,CAAA;AAEJ,UAAA,IAAI,aAAa,CAAG,EAAA;AAChB,YAAM,MAAA,WAAA,GAAcF,uCAA0B,OAAO,CAAA;AACrD,YAAM,MAAA,IAAIF,mBAAYK,uEAAkE,EAAA;AAAA;AAAA;AAAA,cAGpF,gBAAA,EAAkB,iCAAiC,WAAc,GAAA,CAAA;AAAA;AAAA,cAEjE,YAAA,EAAcD,sCAAyB,WAAc,GAAA;AAAA,aACxD,CAAA;AAAA;AAGL,UAAA,MAAM,MAAS,GAAA,IAAA,CAAK,GAAI,CAAA,UAAA,GAAa,QAAQ,SAAS,CAAA;AACtD,UAAM,MAAA,WAAA,GAAc,cAAe,CAAA,MAAA,EAAQ,MAAM,CAAA;AACjD,UAAU,MAAA,IAAA,MAAA;AACV,UAAO,OAAAD,uDAAA,CAAoC,aAAa,OAAO,CAAA;AAAA;AACnE,OACH,CAAA;AAAA,KACL;AAAA,IACA,IAAM,EAAA;AAAA,GACT,CAAA;AACL;AA4BO,SAAS,gDACZ,YAC4B,EAAA;AAC5B,EAAA,OAAO,OAAO,MAAO,CAAA;AAAA,IACjB,kBAAkB,MAAM;AACpB,MAAA,IAAI,gBAAmB,GAAA,CAAA;AACvB,MAAA,OAAO,OAAO,MAAO,CAAA;AAAA,QACjB,IAAA,EAAM,MAAM,gBAAA,IAAoB,YAAa,CAAA,MAAA;AAAA,QAC7C,qBAAA,EAAuB,CAAC,OAAqE,KAAA;AACzF,UAAI,IAAA,gBAAA,IAAoB,aAAa,MAAQ,EAAA;AACzC,YAAM,MAAA,IAAIH,mBAAYC,uEAAgE,CAAA;AAAA;AAG1F,UAAM,MAAA,mBAAA,GAAsBC,uCAA0B,OAAO,CAAA;AAE7D,UAAA,KAAA,IAAS,KAAQ,GAAA,gBAAA,EAAkB,KAAQ,GAAA,YAAA,CAAa,QAAQ,KAAS,EAAA,EAAA;AACrE,YAAA,OAAA,GAAUC,uDAAoC,CAAA,YAAA,CAAa,KAAK,CAAA,EAAG,OAAO,CAAA;AAC1E,YAAM,MAAA,WAAA,GAAcD,uCAA0B,OAAO,CAAA;AAErD,YAAA,IAAI,cAAcE,mCAAwB,EAAA;AACtC,cAAA,IAAI,UAAU,gBAAkB,EAAA;AAC5B,gBAAA,MAAM,IAAIJ,kBAAA;AAAA,kBACNK,uEAAA;AAAA,kBACA;AAAA,oBACI,kBAAkB,WAAc,GAAA,mBAAA;AAAA,oBAChC,cAAcD,mCAAyB,GAAA;AAAA;AAC3C,iBACJ;AAAA;AAEJ,cAAmB,gBAAA,GAAA,KAAA;AACnB,cAAO,OAAA,OAAA;AAAA;AACX;AAGJ,UAAA,gBAAA,GAAmB,YAAa,CAAA,MAAA;AAChC,UAAO,OAAA,OAAA;AAAA;AACX,OACH,CAAA;AAAA,KACL;AAAA,IACA,IAAM,EAAA;AAAA,GACT,CAAA;AACL;AAEA,IAAM,aAAgB,GAAA,KAAA;AAkBf,SAAS,sCAAuC,CAAA;AAAA,EACnD,cAAA;AAAA,EACA;AACJ,CAGiC,EAAA;AAC7B,EAAA,MAAM,oBAAuB,GAAA,IAAA,CAAK,IAAK,CAAA,SAAA,GAAY,aAAa,CAAA;AAChE,EAAA,MAAM,sBAAsB,SAAY,GAAA,aAAA;AACxC,EAAA,MAAM,eAAe,IAAI,KAAA,CAAM,oBAAoB,CAC9C,CAAA,IAAA,CAAK,CAAC,CACN,CAAA,GAAA,CAAI,CAAC,CAAA,EAAG,MAAM,cAAe,CAAA,CAAA,KAAM,uBAAuB,CAAI,GAAA,mBAAA,GAAsB,aAAa,CAAC,CAAA;AAEvG,EAAA,OAAO,gDAAgD,YAAY,CAAA;AACvE","file":"index.node.cjs","sourcesContent":["import {\n    SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_CANNOT_ACCOMMODATE_PLAN,\n    SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_PACKER_ALREADY_COMPLETE,\n    SolanaError,\n} from '@solana/errors';\nimport { Instruction } from '@solana/instructions';\nimport {\n    appendTransactionMessageInstruction,\n    BaseTransactionMessage,\n    TransactionMessageWithFeePayer,\n} from '@solana/transaction-messages';\nimport { getTransactionMessageSize, TRANSACTION_SIZE_LIMIT } from '@solana/transactions';\n\n/**\n * A set of instructions with constraints on how they can be executed.\n *\n * This is structured as a recursive tree of plans in order to allow for\n * parallel execution, sequential execution and combinations of both.\n *\n * Namely the following plans are supported:\n * - {@link SingleInstructionPlan} - A plan that contains a single instruction.\n *   This is a simple instruction wrapper and the simplest leaf in this tree.\n * - {@link ParallelInstructionPlan} - A plan that contains other plans that\n *   can be executed in parallel.\n * - {@link SequentialInstructionPlan} - A plan that contains other plans that\n *   must be executed sequentially. It also defines whether the plan is divisible\n *   meaning that instructions inside it can be split into separate transactions.\n * - {@link MessagePackerInstructionPlan} - A plan that can dynamically pack\n *  instructions into transaction messages.\n *\n * Helpers are provided for each of these plans to make it easier to create them.\n *\n * @example\n * ```ts\n * const myInstructionPlan: InstructionPlan = parallelInstructionPlan([\n *    sequentialInstructionPlan([instructionA, instructionB]),\n *    instructionC,\n *    instructionD,\n * ]);\n * ```\n *\n * @see {@link SingleInstructionPlan}\n * @see {@link ParallelInstructionPlan}\n * @see {@link SequentialInstructionPlan}\n * @see {@link MessagePackerInstructionPlan}\n */\nexport type InstructionPlan =\n    | MessagePackerInstructionPlan\n    | ParallelInstructionPlan\n    | SequentialInstructionPlan\n    | SingleInstructionPlan;\n\n/**\n * A plan wrapping other plans that must be executed sequentially.\n *\n * It also defines whether nested plans are divisible — meaning that\n * the instructions inside them can be split into separate transactions.\n * When `divisible` is `false`, the instructions inside the plan should\n * all be executed atomicly — either in a single transaction or in a\n * transaction bundle.\n *\n * You may use the {@link sequentialInstructionPlan} and {@link nonDivisibleSequentialInstructionPlan}\n * helpers to create objects of this type.\n *\n * @example Simple sequential plan with two instructions.\n * ```ts\n * const plan = sequentialInstructionPlan([instructionA, instructionB]);\n * plan satisfies SequentialInstructionPlan;\n * ```\n *\n * @example Non-divisible sequential plan with two instructions.\n * ```ts\n * const plan = nonDivisibleSequentialInstructionPlan([instructionA, instructionB]);\n * plan satisfies SequentialInstructionPlan & { divisible: false };\n * ```\n *\n * @example Sequential plan with nested parallel plans.\n * Here, instructions A and B can be executed in parallel, but they must both be finalized\n * before instructions C and D can be sent — which can also be executed in parallel.\n * ```ts\n * const plan = sequentialInstructionPlan([\n *   parallelInstructionPlan([instructionA, instructionB]),\n *   parallelInstructionPlan([instructionC, instructionD]),\n * ]);\n * plan satisfies SequentialInstructionPlan & { divisible: false };\n * ```\n *\n * @see {@link sequentialInstructionPlan}\n * @see {@link nonDivisibleSequentialInstructionPlan}\n */\nexport type SequentialInstructionPlan = Readonly<{\n    divisible: boolean;\n    kind: 'sequential';\n    plans: InstructionPlan[];\n}>;\n\n/**\n * A plan wrapping other plans that can be executed in parallel.\n *\n * This means direct children of this plan can be executed in separate\n * parallel transactions without consequence.\n * However, the children themselves can define additional constraints\n * for that specific branch of the tree — such as the {@link SequentialInstructionPlan}.\n *\n * You may use the {@link parallelInstructionPlan} helper to create objects of this type.\n *\n * @example Simple parallel plan with two instructions.\n * ```ts\n * const plan = parallelInstructionPlan([instructionA, instructionB]);\n * plan satisfies ParallelInstructionPlan;\n * ```\n *\n * @example Parallel plan with nested sequential plans.\n * Here, instructions A and B must be executed sequentially and so must instructions C and D,\n * but both pairs can be executed in parallel.\n * ```ts\n * const plan = parallelInstructionPlan([\n *   sequentialInstructionPlan([instructionA, instructionB]),\n *   sequentialInstructionPlan([instructionC, instructionD]),\n * ]);\n * plan satisfies ParallelInstructionPlan;\n * ```\n *\n * @see {@link parallelInstructionPlan}\n */\nexport type ParallelInstructionPlan = Readonly<{\n    kind: 'parallel';\n    plans: InstructionPlan[];\n}>;\n\n/**\n * A plan that contains a single instruction.\n *\n * This is a simple instruction wrapper that transforms an instruction into a plan.\n *\n * You may use the {@link singleInstructionPlan} helper to create objects of this type.\n *\n * @example\n * ```ts\n * const plan = singleInstructionPlan(instructionA);\n * plan satisfies SingleInstructionPlan;\n * ```\n *\n * @see {@link singleInstructionPlan}\n */\nexport type SingleInstructionPlan<TInstruction extends Instruction = Instruction> = Readonly<{\n    instruction: TInstruction;\n    kind: 'single';\n}>;\n\n/**\n * A plan that can dynamically pack instructions into transaction messages.\n *\n * This plan provides a {@link MessagePacker} via the `getMessagePacker`\n * method, which enables instructions to be dynamically packed into the\n * provided transaction message until there are no more instructions to pack.\n * The returned {@link MessagePacker} offers a `packMessageToCapacity(message)`\n * method that packs the provided message — when possible — and a `done()` method\n * that checks whether there are more instructions to pack.\n *\n * Several helper functions are provided to create objects of this type such as\n * {@link getLinearMessagePackerInstructionPlan} or {@link getMessagePackerInstructionPlanFromInstructions}.\n *\n * @example An message packer plan for a write instruction that uses as many bytes as possible.\n * ```ts\n * const plan = getLinearMessagePackerInstructionPlan({\n *   totalLength: dataToWrite.length,\n *   getInstruction: (offset, length) =>\n *     getWriteInstruction({\n *       offset,\n *       data: dataToWrite.slice(offset, offset + length),\n *     }),\n * });\n * plan satisfies MessagePackerInstructionPlan;\n * ```\n *\n * @example A message packer plan for multiple realloc instructions.\n * ```ts\n * const plan = getReallocMessagePackerInstructionPlan({\n *   totalSize: additionalDataSize,\n *   getInstruction: (size) => getExtendInstruction({ length: size }),\n * });\n * plan satisfies MessagePackerInstructionPlan;\n * ```\n *\n * @example Using a message packer plan.\n * ```ts\n * let plan: MessagePackerInstructionPlan;\n * const messagePacker = plan.getMessagePacker();\n *\n * while (!messagePacker.done()) {\n *   try {\n *     transactionMessage = messagePacker.packMessageToCapacity(transactionMessage);\n *   } catch (error) {\n *     // The current transaction message cannot be used to pack this plan.\n *     // We should create a new one and try again.\n *   }\n * }\n * ```\n *\n * @see {@link getLinearMessagePackerInstructionPlan}\n * @see {@link getMessagePackerInstructionPlanFromInstructions}\n * @see {@link getReallocMessagePackerInstructionPlan}\n */\nexport type MessagePackerInstructionPlan = Readonly<{\n    getMessagePacker: () => MessagePacker;\n    kind: 'messagePacker';\n}>;\n\n/**\n * The message packer returned by the {@link MessagePackerInstructionPlan}.\n *\n * It offers a `packMessageToCapacity(transactionMessage)` method that packs as many instructions\n * as possible into the provided transaction message, while still being able to fit into the\n * transaction size limit. It returns the updated transaction message with the packed instructions\n * or throws an error if the current transaction message cannot accommodate this plan.\n *\n * The `done()` method checks whether there are more instructions to pack into\n * transaction messages.\n *\n * @example\n * ```ts\n * let plan: MessagePackerInstructionPlan;\n * const messagePacker = plan.getMessagePacker();\n *\n * while (!messagePacker.done()) {\n *   try {\n *     transactionMessage = messagePacker.packMessageToCapacity(transactionMessage);\n *   } catch (error) {\n *     // The current transaction message cannot be used to pack this plan.\n *     // We should create a new one and try again.\n *   }\n * }\n * ```\n *\n * @see {@link MessagePackerInstructionPlan}\n */\nexport type MessagePacker = Readonly<{\n    /** Checks whether the message packer has more instructions to pack into transaction messages. */\n    done: () => boolean;\n    /**\n     * Packs the provided transaction message with instructions or throws if not possible.\n     *\n     * @throws {@link SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_CANNOT_ACCOMMODATE_PLAN}\n     *   if the provided transaction message cannot be used to fill the next instructions.\n     * @throws {@link SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_PACKER_ALREADY_COMPLETE}\n     *   if the message packer is already done and no more instructions can be packed.\n     */\n    packMessageToCapacity: (\n        transactionMessage: BaseTransactionMessage & TransactionMessageWithFeePayer,\n    ) => BaseTransactionMessage & TransactionMessageWithFeePayer;\n}>;\n\n/**\n * Creates a {@link ParallelInstructionPlan} from an array of nested plans.\n *\n * It can accept {@link Instruction} objects directly, which will be wrapped\n * in {@link SingleInstructionPlan | SingleInstructionPlans} automatically.\n *\n * @example Using explicit {@link SingleInstructionPlan | SingleInstructionPlans}.\n * ```ts\n * const plan = parallelInstructionPlan([\n *   singleInstructionPlan(instructionA),\n *   singleInstructionPlan(instructionB),\n * ]);\n * ```\n *\n * @example Using {@link Instruction | Instructions} directly.\n * ```ts\n * const plan = parallelInstructionPlan([instructionA, instructionB]);\n * ```\n *\n * @see {@link ParallelInstructionPlan}\n */\nexport function parallelInstructionPlan(plans: (Instruction | InstructionPlan)[]): ParallelInstructionPlan {\n    return Object.freeze({\n        kind: 'parallel',\n        plans: parseSingleInstructionPlans(plans),\n    });\n}\n\n/**\n * Creates a divisible {@link SequentialInstructionPlan} from an array of nested plans.\n *\n * It can accept {@link Instruction} objects directly, which will be wrapped\n * in {@link SingleInstructionPlan | SingleInstructionPlans} automatically.\n *\n * @example Using explicit {@link SingleInstructionPlan | SingleInstructionPlans}.\n * ```ts\n * const plan = sequentialInstructionPlan([\n *   singleInstructionPlan(instructionA),\n *   singleInstructionPlan(instructionB),\n * ]);\n * ```\n *\n * @example Using {@link Instruction | Instructions} directly.\n * ```ts\n * const plan = sequentialInstructionPlan([instructionA, instructionB]);\n * ```\n *\n * @see {@link SequentialInstructionPlan}\n */\nexport function sequentialInstructionPlan(\n    plans: (Instruction | InstructionPlan)[],\n): SequentialInstructionPlan & { divisible: true } {\n    return Object.freeze({\n        divisible: true,\n        kind: 'sequential',\n        plans: parseSingleInstructionPlans(plans),\n    });\n}\n\n/**\n * Creates a non-divisible {@link SequentialInstructionPlan} from an array of nested plans.\n *\n * It can accept {@link Instruction} objects directly, which will be wrapped\n * in {@link SingleInstructionPlan | SingleInstructionPlans} automatically.\n *\n * @example Using explicit {@link SingleInstructionPlan | SingleInstructionPlans}.\n * ```ts\n * const plan = nonDivisibleSequentialInstructionPlan([\n *   singleInstructionPlan(instructionA),\n *   singleInstructionPlan(instructionB),\n * ]);\n * ```\n *\n * @example Using {@link Instruction | Instructions} directly.\n * ```ts\n * const plan = nonDivisibleSequentialInstructionPlan([instructionA, instructionB]);\n * ```\n *\n * @see {@link SequentialInstructionPlan}\n */\nexport function nonDivisibleSequentialInstructionPlan(\n    plans: (Instruction | InstructionPlan)[],\n): SequentialInstructionPlan & { divisible: false } {\n    return Object.freeze({\n        divisible: false,\n        kind: 'sequential',\n        plans: parseSingleInstructionPlans(plans),\n    });\n}\n\n/**\n * Creates a {@link SingleInstructionPlan} from an {@link Instruction} object.\n *\n * @example\n * ```ts\n * const plan = singleInstructionPlan(instructionA);\n * ```\n *\n * @see {@link SingleInstructionPlan}\n */\nexport function singleInstructionPlan(instruction: Instruction): SingleInstructionPlan {\n    return Object.freeze({ instruction, kind: 'single' });\n}\n\nfunction parseSingleInstructionPlans(plans: (Instruction | InstructionPlan)[]): InstructionPlan[] {\n    return plans.map(plan => ('kind' in plan ? plan : singleInstructionPlan(plan)));\n}\n\n/**\n * Creates a {@link MessagePackerInstructionPlan} that packs instructions\n * such that each instruction consumes as many bytes as possible from the given\n * `totalLength` while still being able to fit into the given transaction messages.\n *\n * This is particularly useful for instructions that write data to accounts and must\n * span multiple transactions due to their size limit.\n *\n * This message packer will first call `getInstruction` with a length of zero to\n * determine the base size of the instruction before figuring out how many\n * additional bytes can be packed into the transaction message. That remaining space\n * will then be used to call `getInstruction` again with the appropriate length.\n *\n * @param getInstruction - A function that returns an instruction for a given offset and length.\n * @param totalLength - The total length of the data to write, in bytes.\n *\n * @example\n * ```ts\n * const plan = getLinearMessagePackerInstructionPlan({\n *   totalLength: dataToWrite.length,\n *   getInstruction: (offset, length) =>\n *     getWriteInstruction({\n *       offset,\n *       data: dataToWrite.slice(offset, offset + length),\n *     }),\n * });\n * plan satisfies MessagePackerInstructionPlan;\n * ```\n *\n * @see {@link MessagePackerInstructionPlan}\n */\nexport function getLinearMessagePackerInstructionPlan({\n    getInstruction,\n    totalLength: totalBytes,\n}: {\n    getInstruction: (offset: number, length: number) => Instruction;\n    totalLength: number;\n}): MessagePackerInstructionPlan {\n    return Object.freeze({\n        getMessagePacker: () => {\n            let offset = 0;\n            return Object.freeze({\n                done: () => offset >= totalBytes,\n                packMessageToCapacity: (message: BaseTransactionMessage & TransactionMessageWithFeePayer) => {\n                    if (offset >= totalBytes) {\n                        throw new SolanaError(SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_PACKER_ALREADY_COMPLETE);\n                    }\n\n                    const messageSizeWithBaseInstruction = getTransactionMessageSize(\n                        appendTransactionMessageInstruction(getInstruction(offset, 0), message),\n                    );\n                    const freeSpace =\n                        TRANSACTION_SIZE_LIMIT -\n                        messageSizeWithBaseInstruction /* Includes the base instruction (length: 0). */ -\n                        1; /* Leeway for shortU16 numbers in transaction headers. */\n\n                    if (freeSpace <= 0) {\n                        const messageSize = getTransactionMessageSize(message);\n                        throw new SolanaError(SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_CANNOT_ACCOMMODATE_PLAN, {\n                            // (+1) We need to pack at least one byte of data otherwise\n                            // there is no point packing the base instruction alone.\n                            numBytesRequired: messageSizeWithBaseInstruction - messageSize + 1,\n                            // (-1) Leeway for shortU16 numbers in transaction headers.\n                            numFreeBytes: TRANSACTION_SIZE_LIMIT - messageSize - 1,\n                        });\n                    }\n\n                    const length = Math.min(totalBytes - offset, freeSpace);\n                    const instruction = getInstruction(offset, length);\n                    offset += length;\n                    return appendTransactionMessageInstruction(instruction, message);\n                },\n            });\n        },\n        kind: 'messagePacker',\n    });\n}\n\n/**\n * Creates a {@link MessagePackerInstructionPlan} from a list of instructions.\n *\n * This can be useful to prepare a set of instructions that can be iterated over\n * — e.g. to pack a list of instructions that gradually reallocate the size of an account\n * one `REALLOC_LIMIT` (10'240 bytes) at a time.\n *\n * @example\n * ```ts\n * const plan = getMessagePackerInstructionPlanFromInstructions([\n *   instructionA,\n *   instructionB,\n *   instructionC,\n * ]);\n *\n * const messagePacker = plan.getMessagePacker();\n * firstTransactionMessage = messagePacker.packMessageToCapacity(firstTransactionMessage);\n * // Contains instruction A and instruction B.\n * secondTransactionMessage = messagePacker.packMessageToCapacity(secondTransactionMessage);\n * // Contains instruction C.\n * messagePacker.done(); // true\n * ```\n *\n * @see {@link MessagePackerInstructionPlan}\n * @see {@link getReallocMessagePackerInstructionPlan}\n */\nexport function getMessagePackerInstructionPlanFromInstructions<TInstruction extends Instruction = Instruction>(\n    instructions: TInstruction[],\n): MessagePackerInstructionPlan {\n    return Object.freeze({\n        getMessagePacker: () => {\n            let instructionIndex = 0;\n            return Object.freeze({\n                done: () => instructionIndex >= instructions.length,\n                packMessageToCapacity: (message: BaseTransactionMessage & TransactionMessageWithFeePayer) => {\n                    if (instructionIndex >= instructions.length) {\n                        throw new SolanaError(SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_PACKER_ALREADY_COMPLETE);\n                    }\n\n                    const originalMessageSize = getTransactionMessageSize(message);\n\n                    for (let index = instructionIndex; index < instructions.length; index++) {\n                        message = appendTransactionMessageInstruction(instructions[index], message);\n                        const messageSize = getTransactionMessageSize(message);\n\n                        if (messageSize > TRANSACTION_SIZE_LIMIT) {\n                            if (index === instructionIndex) {\n                                throw new SolanaError(\n                                    SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_CANNOT_ACCOMMODATE_PLAN,\n                                    {\n                                        numBytesRequired: messageSize - originalMessageSize,\n                                        numFreeBytes: TRANSACTION_SIZE_LIMIT - originalMessageSize,\n                                    },\n                                );\n                            }\n                            instructionIndex = index;\n                            return message;\n                        }\n                    }\n\n                    instructionIndex = instructions.length;\n                    return message;\n                },\n            });\n        },\n        kind: 'messagePacker',\n    });\n}\n\nconst REALLOC_LIMIT = 10_240;\n\n/**\n * Creates a {@link MessagePackerInstructionPlan} that packs a list of realloc instructions.\n *\n * That is, it splits instruction by chunks of `REALLOC_LIMIT` (10'240) bytes until\n * the given total size is reached.\n *\n * @example\n * ```ts\n * const plan = getReallocMessagePackerInstructionPlan({\n *   totalSize: additionalDataSize,\n *   getInstruction: (size) => getExtendInstruction({ length: size }),\n * });\n * ```\n *\n * @see {@link MessagePackerInstructionPlan}\n */\nexport function getReallocMessagePackerInstructionPlan({\n    getInstruction,\n    totalSize,\n}: {\n    getInstruction: (size: number) => Instruction;\n    totalSize: number;\n}): MessagePackerInstructionPlan {\n    const numberOfInstructions = Math.ceil(totalSize / REALLOC_LIMIT);\n    const lastInstructionSize = totalSize % REALLOC_LIMIT;\n    const instructions = new Array(numberOfInstructions)\n        .fill(0)\n        .map((_, i) => getInstruction(i === numberOfInstructions - 1 ? lastInstructionSize : REALLOC_LIMIT));\n\n    return getMessagePackerInstructionPlanFromInstructions(instructions);\n}\n"]}

package/dist/index.node.mjs

@@ -0,0 +1,118 @@
+import { SolanaError, SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_PACKER_ALREADY_COMPLETE, SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_CANNOT_ACCOMMODATE_PLAN } from '@solana/errors';
+import { appendTransactionMessageInstruction } from '@solana/transaction-messages';
+import { getTransactionMessageSize, TRANSACTION_SIZE_LIMIT } from '@solana/transactions';
+
+// src/instruction-plan.ts
+function parallelInstructionPlan(plans) {
+  return Object.freeze({
+    kind: "parallel",
+    plans: parseSingleInstructionPlans(plans)
+  });
+}
+function sequentialInstructionPlan(plans) {
+  return Object.freeze({
+    divisible: true,
+    kind: "sequential",
+    plans: parseSingleInstructionPlans(plans)
+  });
+}
+function nonDivisibleSequentialInstructionPlan(plans) {
+  return Object.freeze({
+    divisible: false,
+    kind: "sequential",
+    plans: parseSingleInstructionPlans(plans)
+  });
+}
+function singleInstructionPlan(instruction) {
+  return Object.freeze({ instruction, kind: "single" });
+}
+function parseSingleInstructionPlans(plans) {
+  return plans.map((plan) => "kind" in plan ? plan : singleInstructionPlan(plan));
+}
+function getLinearMessagePackerInstructionPlan({
+  getInstruction,
+  totalLength: totalBytes
+}) {
+  return Object.freeze({
+    getMessagePacker: () => {
+      let offset = 0;
+      return Object.freeze({
+        done: () => offset >= totalBytes,
+        packMessageToCapacity: (message) => {
+          if (offset >= totalBytes) {
+            throw new SolanaError(SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_PACKER_ALREADY_COMPLETE);
+          }
+          const messageSizeWithBaseInstruction = getTransactionMessageSize(
+            appendTransactionMessageInstruction(getInstruction(offset, 0), message)
+          );
+          const freeSpace = TRANSACTION_SIZE_LIMIT - messageSizeWithBaseInstruction - 1;
+          if (freeSpace <= 0) {
+            const messageSize = getTransactionMessageSize(message);
+            throw new SolanaError(SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_CANNOT_ACCOMMODATE_PLAN, {
+              // (+1) We need to pack at least one byte of data otherwise
+              // there is no point packing the base instruction alone.
+              numBytesRequired: messageSizeWithBaseInstruction - messageSize + 1,
+              // (-1) Leeway for shortU16 numbers in transaction headers.
+              numFreeBytes: TRANSACTION_SIZE_LIMIT - messageSize - 1
+            });
+          }
+          const length = Math.min(totalBytes - offset, freeSpace);
+          const instruction = getInstruction(offset, length);
+          offset += length;
+          return appendTransactionMessageInstruction(instruction, message);
+        }
+      });
+    },
+    kind: "messagePacker"
+  });
+}
+function getMessagePackerInstructionPlanFromInstructions(instructions) {
+  return Object.freeze({
+    getMessagePacker: () => {
+      let instructionIndex = 0;
+      return Object.freeze({
+        done: () => instructionIndex >= instructions.length,
+        packMessageToCapacity: (message) => {
+          if (instructionIndex >= instructions.length) {
+            throw new SolanaError(SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_PACKER_ALREADY_COMPLETE);
+          }
+          const originalMessageSize = getTransactionMessageSize(message);
+          for (let index = instructionIndex; index < instructions.length; index++) {
+            message = appendTransactionMessageInstruction(instructions[index], message);
+            const messageSize = getTransactionMessageSize(message);
+            if (messageSize > TRANSACTION_SIZE_LIMIT) {
+              if (index === instructionIndex) {
+                throw new SolanaError(
+                  SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_CANNOT_ACCOMMODATE_PLAN,
+                  {
+                    numBytesRequired: messageSize - originalMessageSize,
+                    numFreeBytes: TRANSACTION_SIZE_LIMIT - originalMessageSize
+                  }
+                );
+              }
+              instructionIndex = index;
+              return message;
+            }
+          }
+          instructionIndex = instructions.length;
+          return message;
+        }
+      });
+    },
+    kind: "messagePacker"
+  });
+}
+var REALLOC_LIMIT = 10240;
+function getReallocMessagePackerInstructionPlan({
+  getInstruction,
+  totalSize
+}) {
+  const numberOfInstructions = Math.ceil(totalSize / REALLOC_LIMIT);
+  const lastInstructionSize = totalSize % REALLOC_LIMIT;
+  const instructions = new Array(numberOfInstructions).fill(0).map((_, i) => getInstruction(i === numberOfInstructions - 1 ? lastInstructionSize : REALLOC_LIMIT));
+  return getMessagePackerInstructionPlanFromInstructions(instructions);
+}
+
+export { getLinearMessagePackerInstructionPlan, getMessagePackerInstructionPlanFromInstructions, getReallocMessagePackerInstructionPlan, nonDivisibleSequentialInstructionPlan, parallelInstructionPlan, sequentialInstructionPlan, singleInstructionPlan };
+//# sourceMappingURL=index.node.mjs.map
+//# sourceMappingURL=index.node.mjs.map

package/dist/index.node.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/instruction-plan.ts"],"names":[],"mappings":"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","file":"index.node.mjs","sourcesContent":["import {\n    SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_CANNOT_ACCOMMODATE_PLAN,\n    SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_PACKER_ALREADY_COMPLETE,\n    SolanaError,\n} from '@solana/errors';\nimport { Instruction } from '@solana/instructions';\nimport {\n    appendTransactionMessageInstruction,\n    BaseTransactionMessage,\n    TransactionMessageWithFeePayer,\n} from '@solana/transaction-messages';\nimport { getTransactionMessageSize, TRANSACTION_SIZE_LIMIT } from '@solana/transactions';\n\n/**\n * A set of instructions with constraints on how they can be executed.\n *\n * This is structured as a recursive tree of plans in order to allow for\n * parallel execution, sequential execution and combinations of both.\n *\n * Namely the following plans are supported:\n * - {@link SingleInstructionPlan} - A plan that contains a single instruction.\n *   This is a simple instruction wrapper and the simplest leaf in this tree.\n * - {@link ParallelInstructionPlan} - A plan that contains other plans that\n *   can be executed in parallel.\n * - {@link SequentialInstructionPlan} - A plan that contains other plans that\n *   must be executed sequentially. It also defines whether the plan is divisible\n *   meaning that instructions inside it can be split into separate transactions.\n * - {@link MessagePackerInstructionPlan} - A plan that can dynamically pack\n *  instructions into transaction messages.\n *\n * Helpers are provided for each of these plans to make it easier to create them.\n *\n * @example\n * ```ts\n * const myInstructionPlan: InstructionPlan = parallelInstructionPlan([\n *    sequentialInstructionPlan([instructionA, instructionB]),\n *    instructionC,\n *    instructionD,\n * ]);\n * ```\n *\n * @see {@link SingleInstructionPlan}\n * @see {@link ParallelInstructionPlan}\n * @see {@link SequentialInstructionPlan}\n * @see {@link MessagePackerInstructionPlan}\n */\nexport type InstructionPlan =\n    | MessagePackerInstructionPlan\n    | ParallelInstructionPlan\n    | SequentialInstructionPlan\n    | SingleInstructionPlan;\n\n/**\n * A plan wrapping other plans that must be executed sequentially.\n *\n * It also defines whether nested plans are divisible — meaning that\n * the instructions inside them can be split into separate transactions.\n * When `divisible` is `false`, the instructions inside the plan should\n * all be executed atomicly — either in a single transaction or in a\n * transaction bundle.\n *\n * You may use the {@link sequentialInstructionPlan} and {@link nonDivisibleSequentialInstructionPlan}\n * helpers to create objects of this type.\n *\n * @example Simple sequential plan with two instructions.\n * ```ts\n * const plan = sequentialInstructionPlan([instructionA, instructionB]);\n * plan satisfies SequentialInstructionPlan;\n * ```\n *\n * @example Non-divisible sequential plan with two instructions.\n * ```ts\n * const plan = nonDivisibleSequentialInstructionPlan([instructionA, instructionB]);\n * plan satisfies SequentialInstructionPlan & { divisible: false };\n * ```\n *\n * @example Sequential plan with nested parallel plans.\n * Here, instructions A and B can be executed in parallel, but they must both be finalized\n * before instructions C and D can be sent — which can also be executed in parallel.\n * ```ts\n * const plan = sequentialInstructionPlan([\n *   parallelInstructionPlan([instructionA, instructionB]),\n *   parallelInstructionPlan([instructionC, instructionD]),\n * ]);\n * plan satisfies SequentialInstructionPlan & { divisible: false };\n * ```\n *\n * @see {@link sequentialInstructionPlan}\n * @see {@link nonDivisibleSequentialInstructionPlan}\n */\nexport type SequentialInstructionPlan = Readonly<{\n    divisible: boolean;\n    kind: 'sequential';\n    plans: InstructionPlan[];\n}>;\n\n/**\n * A plan wrapping other plans that can be executed in parallel.\n *\n * This means direct children of this plan can be executed in separate\n * parallel transactions without consequence.\n * However, the children themselves can define additional constraints\n * for that specific branch of the tree — such as the {@link SequentialInstructionPlan}.\n *\n * You may use the {@link parallelInstructionPlan} helper to create objects of this type.\n *\n * @example Simple parallel plan with two instructions.\n * ```ts\n * const plan = parallelInstructionPlan([instructionA, instructionB]);\n * plan satisfies ParallelInstructionPlan;\n * ```\n *\n * @example Parallel plan with nested sequential plans.\n * Here, instructions A and B must be executed sequentially and so must instructions C and D,\n * but both pairs can be executed in parallel.\n * ```ts\n * const plan = parallelInstructionPlan([\n *   sequentialInstructionPlan([instructionA, instructionB]),\n *   sequentialInstructionPlan([instructionC, instructionD]),\n * ]);\n * plan satisfies ParallelInstructionPlan;\n * ```\n *\n * @see {@link parallelInstructionPlan}\n */\nexport type ParallelInstructionPlan = Readonly<{\n    kind: 'parallel';\n    plans: InstructionPlan[];\n}>;\n\n/**\n * A plan that contains a single instruction.\n *\n * This is a simple instruction wrapper that transforms an instruction into a plan.\n *\n * You may use the {@link singleInstructionPlan} helper to create objects of this type.\n *\n * @example\n * ```ts\n * const plan = singleInstructionPlan(instructionA);\n * plan satisfies SingleInstructionPlan;\n * ```\n *\n * @see {@link singleInstructionPlan}\n */\nexport type SingleInstructionPlan<TInstruction extends Instruction = Instruction> = Readonly<{\n    instruction: TInstruction;\n    kind: 'single';\n}>;\n\n/**\n * A plan that can dynamically pack instructions into transaction messages.\n *\n * This plan provides a {@link MessagePacker} via the `getMessagePacker`\n * method, which enables instructions to be dynamically packed into the\n * provided transaction message until there are no more instructions to pack.\n * The returned {@link MessagePacker} offers a `packMessageToCapacity(message)`\n * method that packs the provided message — when possible — and a `done()` method\n * that checks whether there are more instructions to pack.\n *\n * Several helper functions are provided to create objects of this type such as\n * {@link getLinearMessagePackerInstructionPlan} or {@link getMessagePackerInstructionPlanFromInstructions}.\n *\n * @example An message packer plan for a write instruction that uses as many bytes as possible.\n * ```ts\n * const plan = getLinearMessagePackerInstructionPlan({\n *   totalLength: dataToWrite.length,\n *   getInstruction: (offset, length) =>\n *     getWriteInstruction({\n *       offset,\n *       data: dataToWrite.slice(offset, offset + length),\n *     }),\n * });\n * plan satisfies MessagePackerInstructionPlan;\n * ```\n *\n * @example A message packer plan for multiple realloc instructions.\n * ```ts\n * const plan = getReallocMessagePackerInstructionPlan({\n *   totalSize: additionalDataSize,\n *   getInstruction: (size) => getExtendInstruction({ length: size }),\n * });\n * plan satisfies MessagePackerInstructionPlan;\n * ```\n *\n * @example Using a message packer plan.\n * ```ts\n * let plan: MessagePackerInstructionPlan;\n * const messagePacker = plan.getMessagePacker();\n *\n * while (!messagePacker.done()) {\n *   try {\n *     transactionMessage = messagePacker.packMessageToCapacity(transactionMessage);\n *   } catch (error) {\n *     // The current transaction message cannot be used to pack this plan.\n *     // We should create a new one and try again.\n *   }\n * }\n * ```\n *\n * @see {@link getLinearMessagePackerInstructionPlan}\n * @see {@link getMessagePackerInstructionPlanFromInstructions}\n * @see {@link getReallocMessagePackerInstructionPlan}\n */\nexport type MessagePackerInstructionPlan = Readonly<{\n    getMessagePacker: () => MessagePacker;\n    kind: 'messagePacker';\n}>;\n\n/**\n * The message packer returned by the {@link MessagePackerInstructionPlan}.\n *\n * It offers a `packMessageToCapacity(transactionMessage)` method that packs as many instructions\n * as possible into the provided transaction message, while still being able to fit into the\n * transaction size limit. It returns the updated transaction message with the packed instructions\n * or throws an error if the current transaction message cannot accommodate this plan.\n *\n * The `done()` method checks whether there are more instructions to pack into\n * transaction messages.\n *\n * @example\n * ```ts\n * let plan: MessagePackerInstructionPlan;\n * const messagePacker = plan.getMessagePacker();\n *\n * while (!messagePacker.done()) {\n *   try {\n *     transactionMessage = messagePacker.packMessageToCapacity(transactionMessage);\n *   } catch (error) {\n *     // The current transaction message cannot be used to pack this plan.\n *     // We should create a new one and try again.\n *   }\n * }\n * ```\n *\n * @see {@link MessagePackerInstructionPlan}\n */\nexport type MessagePacker = Readonly<{\n    /** Checks whether the message packer has more instructions to pack into transaction messages. */\n    done: () => boolean;\n    /**\n     * Packs the provided transaction message with instructions or throws if not possible.\n     *\n     * @throws {@link SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_CANNOT_ACCOMMODATE_PLAN}\n     *   if the provided transaction message cannot be used to fill the next instructions.\n     * @throws {@link SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_PACKER_ALREADY_COMPLETE}\n     *   if the message packer is already done and no more instructions can be packed.\n     */\n    packMessageToCapacity: (\n        transactionMessage: BaseTransactionMessage & TransactionMessageWithFeePayer,\n    ) => BaseTransactionMessage & TransactionMessageWithFeePayer;\n}>;\n\n/**\n * Creates a {@link ParallelInstructionPlan} from an array of nested plans.\n *\n * It can accept {@link Instruction} objects directly, which will be wrapped\n * in {@link SingleInstructionPlan | SingleInstructionPlans} automatically.\n *\n * @example Using explicit {@link SingleInstructionPlan | SingleInstructionPlans}.\n * ```ts\n * const plan = parallelInstructionPlan([\n *   singleInstructionPlan(instructionA),\n *   singleInstructionPlan(instructionB),\n * ]);\n * ```\n *\n * @example Using {@link Instruction | Instructions} directly.\n * ```ts\n * const plan = parallelInstructionPlan([instructionA, instructionB]);\n * ```\n *\n * @see {@link ParallelInstructionPlan}\n */\nexport function parallelInstructionPlan(plans: (Instruction | InstructionPlan)[]): ParallelInstructionPlan {\n    return Object.freeze({\n        kind: 'parallel',\n        plans: parseSingleInstructionPlans(plans),\n    });\n}\n\n/**\n * Creates a divisible {@link SequentialInstructionPlan} from an array of nested plans.\n *\n * It can accept {@link Instruction} objects directly, which will be wrapped\n * in {@link SingleInstructionPlan | SingleInstructionPlans} automatically.\n *\n * @example Using explicit {@link SingleInstructionPlan | SingleInstructionPlans}.\n * ```ts\n * const plan = sequentialInstructionPlan([\n *   singleInstructionPlan(instructionA),\n *   singleInstructionPlan(instructionB),\n * ]);\n * ```\n *\n * @example Using {@link Instruction | Instructions} directly.\n * ```ts\n * const plan = sequentialInstructionPlan([instructionA, instructionB]);\n * ```\n *\n * @see {@link SequentialInstructionPlan}\n */\nexport function sequentialInstructionPlan(\n    plans: (Instruction | InstructionPlan)[],\n): SequentialInstructionPlan & { divisible: true } {\n    return Object.freeze({\n        divisible: true,\n        kind: 'sequential',\n        plans: parseSingleInstructionPlans(plans),\n    });\n}\n\n/**\n * Creates a non-divisible {@link SequentialInstructionPlan} from an array of nested plans.\n *\n * It can accept {@link Instruction} objects directly, which will be wrapped\n * in {@link SingleInstructionPlan | SingleInstructionPlans} automatically.\n *\n * @example Using explicit {@link SingleInstructionPlan | SingleInstructionPlans}.\n * ```ts\n * const plan = nonDivisibleSequentialInstructionPlan([\n *   singleInstructionPlan(instructionA),\n *   singleInstructionPlan(instructionB),\n * ]);\n * ```\n *\n * @example Using {@link Instruction | Instructions} directly.\n * ```ts\n * const plan = nonDivisibleSequentialInstructionPlan([instructionA, instructionB]);\n * ```\n *\n * @see {@link SequentialInstructionPlan}\n */\nexport function nonDivisibleSequentialInstructionPlan(\n    plans: (Instruction | InstructionPlan)[],\n): SequentialInstructionPlan & { divisible: false } {\n    return Object.freeze({\n        divisible: false,\n        kind: 'sequential',\n        plans: parseSingleInstructionPlans(plans),\n    });\n}\n\n/**\n * Creates a {@link SingleInstructionPlan} from an {@link Instruction} object.\n *\n * @example\n * ```ts\n * const plan = singleInstructionPlan(instructionA);\n * ```\n *\n * @see {@link SingleInstructionPlan}\n */\nexport function singleInstructionPlan(instruction: Instruction): SingleInstructionPlan {\n    return Object.freeze({ instruction, kind: 'single' });\n}\n\nfunction parseSingleInstructionPlans(plans: (Instruction | InstructionPlan)[]): InstructionPlan[] {\n    return plans.map(plan => ('kind' in plan ? plan : singleInstructionPlan(plan)));\n}\n\n/**\n * Creates a {@link MessagePackerInstructionPlan} that packs instructions\n * such that each instruction consumes as many bytes as possible from the given\n * `totalLength` while still being able to fit into the given transaction messages.\n *\n * This is particularly useful for instructions that write data to accounts and must\n * span multiple transactions due to their size limit.\n *\n * This message packer will first call `getInstruction` with a length of zero to\n * determine the base size of the instruction before figuring out how many\n * additional bytes can be packed into the transaction message. That remaining space\n * will then be used to call `getInstruction` again with the appropriate length.\n *\n * @param getInstruction - A function that returns an instruction for a given offset and length.\n * @param totalLength - The total length of the data to write, in bytes.\n *\n * @example\n * ```ts\n * const plan = getLinearMessagePackerInstructionPlan({\n *   totalLength: dataToWrite.length,\n *   getInstruction: (offset, length) =>\n *     getWriteInstruction({\n *       offset,\n *       data: dataToWrite.slice(offset, offset + length),\n *     }),\n * });\n * plan satisfies MessagePackerInstructionPlan;\n * ```\n *\n * @see {@link MessagePackerInstructionPlan}\n */\nexport function getLinearMessagePackerInstructionPlan({\n    getInstruction,\n    totalLength: totalBytes,\n}: {\n    getInstruction: (offset: number, length: number) => Instruction;\n    totalLength: number;\n}): MessagePackerInstructionPlan {\n    return Object.freeze({\n        getMessagePacker: () => {\n            let offset = 0;\n            return Object.freeze({\n                done: () => offset >= totalBytes,\n                packMessageToCapacity: (message: BaseTransactionMessage & TransactionMessageWithFeePayer) => {\n                    if (offset >= totalBytes) {\n                        throw new SolanaError(SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_PACKER_ALREADY_COMPLETE);\n                    }\n\n                    const messageSizeWithBaseInstruction = getTransactionMessageSize(\n                        appendTransactionMessageInstruction(getInstruction(offset, 0), message),\n                    );\n                    const freeSpace =\n                        TRANSACTION_SIZE_LIMIT -\n                        messageSizeWithBaseInstruction /* Includes the base instruction (length: 0). */ -\n                        1; /* Leeway for shortU16 numbers in transaction headers. */\n\n                    if (freeSpace <= 0) {\n                        const messageSize = getTransactionMessageSize(message);\n                        throw new SolanaError(SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_CANNOT_ACCOMMODATE_PLAN, {\n                            // (+1) We need to pack at least one byte of data otherwise\n                            // there is no point packing the base instruction alone.\n                            numBytesRequired: messageSizeWithBaseInstruction - messageSize + 1,\n                            // (-1) Leeway for shortU16 numbers in transaction headers.\n                            numFreeBytes: TRANSACTION_SIZE_LIMIT - messageSize - 1,\n                        });\n                    }\n\n                    const length = Math.min(totalBytes - offset, freeSpace);\n                    const instruction = getInstruction(offset, length);\n                    offset += length;\n                    return appendTransactionMessageInstruction(instruction, message);\n                },\n            });\n        },\n        kind: 'messagePacker',\n    });\n}\n\n/**\n * Creates a {@link MessagePackerInstructionPlan} from a list of instructions.\n *\n * This can be useful to prepare a set of instructions that can be iterated over\n * — e.g. to pack a list of instructions that gradually reallocate the size of an account\n * one `REALLOC_LIMIT` (10'240 bytes) at a time.\n *\n * @example\n * ```ts\n * const plan = getMessagePackerInstructionPlanFromInstructions([\n *   instructionA,\n *   instructionB,\n *   instructionC,\n * ]);\n *\n * const messagePacker = plan.getMessagePacker();\n * firstTransactionMessage = messagePacker.packMessageToCapacity(firstTransactionMessage);\n * // Contains instruction A and instruction B.\n * secondTransactionMessage = messagePacker.packMessageToCapacity(secondTransactionMessage);\n * // Contains instruction C.\n * messagePacker.done(); // true\n * ```\n *\n * @see {@link MessagePackerInstructionPlan}\n * @see {@link getReallocMessagePackerInstructionPlan}\n */\nexport function getMessagePackerInstructionPlanFromInstructions<TInstruction extends Instruction = Instruction>(\n    instructions: TInstruction[],\n): MessagePackerInstructionPlan {\n    return Object.freeze({\n        getMessagePacker: () => {\n            let instructionIndex = 0;\n            return Object.freeze({\n                done: () => instructionIndex >= instructions.length,\n                packMessageToCapacity: (message: BaseTransactionMessage & TransactionMessageWithFeePayer) => {\n                    if (instructionIndex >= instructions.length) {\n                        throw new SolanaError(SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_PACKER_ALREADY_COMPLETE);\n                    }\n\n                    const originalMessageSize = getTransactionMessageSize(message);\n\n                    for (let index = instructionIndex; index < instructions.length; index++) {\n                        message = appendTransactionMessageInstruction(instructions[index], message);\n                        const messageSize = getTransactionMessageSize(message);\n\n                        if (messageSize > TRANSACTION_SIZE_LIMIT) {\n                            if (index === instructionIndex) {\n                                throw new SolanaError(\n                                    SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_CANNOT_ACCOMMODATE_PLAN,\n                                    {\n                                        numBytesRequired: messageSize - originalMessageSize,\n                                        numFreeBytes: TRANSACTION_SIZE_LIMIT - originalMessageSize,\n                                    },\n                                );\n                            }\n                            instructionIndex = index;\n                            return message;\n                        }\n                    }\n\n                    instructionIndex = instructions.length;\n                    return message;\n                },\n            });\n        },\n        kind: 'messagePacker',\n    });\n}\n\nconst REALLOC_LIMIT = 10_240;\n\n/**\n * Creates a {@link MessagePackerInstructionPlan} that packs a list of realloc instructions.\n *\n * That is, it splits instruction by chunks of `REALLOC_LIMIT` (10'240) bytes until\n * the given total size is reached.\n *\n * @example\n * ```ts\n * const plan = getReallocMessagePackerInstructionPlan({\n *   totalSize: additionalDataSize,\n *   getInstruction: (size) => getExtendInstruction({ length: size }),\n * });\n * ```\n *\n * @see {@link MessagePackerInstructionPlan}\n */\nexport function getReallocMessagePackerInstructionPlan({\n    getInstruction,\n    totalSize,\n}: {\n    getInstruction: (size: number) => Instruction;\n    totalSize: number;\n}): MessagePackerInstructionPlan {\n    const numberOfInstructions = Math.ceil(totalSize / REALLOC_LIMIT);\n    const lastInstructionSize = totalSize % REALLOC_LIMIT;\n    const instructions = new Array(numberOfInstructions)\n        .fill(0)\n        .map((_, i) => getInstruction(i === numberOfInstructions - 1 ? lastInstructionSize : REALLOC_LIMIT));\n\n    return getMessagePackerInstructionPlanFromInstructions(instructions);\n}\n"]}

package/dist/types/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * TODO
+ *
+ * @packageDocumentation
+ */
+export * from './instruction-plan';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,cAAc,oBAAoB,CAAC"}