@nosana/kit 2.3.1 → 2.4.0

package/dist/utils/packInstructions.d.ts

@@ -0,0 +1,79 @@
+import { type Address, type Instruction } from '@solana/kit';
+/**
+ * Maximum size, in bytes, of a serialized Solana transaction (the packet MTU limit).
+ * @group @nosana/kit
+ */
+export declare const TRANSACTION_SIZE_LIMIT = 1232;
+/**
+ * Maximum compute units a single Solana transaction may consume.
+ * @group @nosana/kit
+ */
+export declare const MAX_COMPUTE_UNITS = 1400000;
+/**
+ * Options for {@link packInstructions}.
+ * @group @nosana/kit
+ */
+export interface PackInstructionsOptions {
+    /**
+     * The fee payer address for the resulting transactions. Provided so that size
+     * measurement accounts for account deduplication accurately (the fee payer is
+     * shared across every instruction). Defaults to a placeholder address, which is
+     * slightly conservative.
+     */
+    feePayer?: Address;
+    /**
+     * Instructions that will be prepended to every transaction at send time (for
+     * example compute-budget or priority-fee instructions). They are charged against
+     * the size budget of each bucket but are NOT included in the returned buckets —
+     * the transaction builder adds the real ones when sending.
+     */
+    reservedInstructions?: Instruction[];
+    /**
+     * Maximum serialized transaction size in bytes. Defaults to
+     * {@link TRANSACTION_SIZE_LIMIT} (1232).
+     */
+    maxTransactionSize?: number;
+    /**
+     * Optional per-instruction compute-unit estimator. When provided, a bucket is
+     * also split whenever its cumulative estimated compute units would exceed
+     * {@link PackInstructionsOptions.maxComputeUnits}. When omitted, compute units
+     * are not considered and only transaction size bounds the packing.
+     */
+    computeUnits?: (instruction: Instruction) => number;
+    /**
+     * Maximum compute units per transaction. Only enforced when
+     * {@link PackInstructionsOptions.computeUnits} is provided. Defaults to
+     * {@link MAX_COMPUTE_UNITS} (1,400,000).
+     */
+    maxComputeUnits?: number;
+}
+/**
+ * Greedily pack instruction groups into the fewest transactions that each stay
+ * within Solana's transaction size limit.
+ *
+ * Each entry of `groups` is an *atomic group*: a single instruction, or an array
+ * of instructions that must land together in the same transaction (e.g. a
+ * create-account + initialize pair). A group is never split across transactions;
+ * groups are filled into a bucket in order until the next group would overflow the
+ * size limit, at which point a new bucket is started.
+ *
+ * A bucket is bounded by two constraints, and is split whenever the next group
+ * would exceed either one:
+ * - Transaction size: determined by compiling each candidate transaction
+ *   in-memory and measuring its serialized length, so shared accounts (program
+ *   ids, fee payer, sysvars) are correctly deduplicated — no static estimate and
+ *   no RPC call.
+ * - Compute units (optional): when a `computeUnits` estimator is provided, the
+ *   cumulative estimated compute units of a bucket may not exceed
+ *   `maxComputeUnits`.
+ *
+ * @param groups Atomic instruction groups to pack, in order.
+ * @param options Packing options (fee payer, reserved instructions, limits).
+ * @returns An array of buckets; each bucket is a flat array of instructions for
+ *          one transaction.
+ * @throws {NosanaError} If a single group cannot fit in one transaction (by size
+ *         or compute units), since it cannot be split.
+ * @group @nosana/kit
+ */
+export declare function packInstructions(groups: Array<Instruction | Instruction[]>, options?: PackInstructionsOptions): Instruction[][];
+//# sourceMappingURL=packInstructions.d.ts.map

package/dist/utils/packInstructions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"packInstructions.d.ts","sourceRoot":"","sources":["../../src/utils/packInstructions.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EAEZ,KAAK,WAAW,EASjB,MAAM,aAAa,CAAC;AAGrB;;;GAGG;AACH,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAE3C;;;GAGG;AACH,eAAO,MAAM,iBAAiB,UAAY,CAAC;AA+B3C;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,WAAW,EAAE,CAAC;IACrC;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,CAAC,WAAW,EAAE,WAAW,KAAK,MAAM,CAAC;IACpD;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,KAAK,CAAC,WAAW,GAAG,WAAW,EAAE,CAAC,EAC1C,OAAO,GAAE,uBAA4B,GACpC,WAAW,EAAE,EAAE,CA0DjB"}

package/dist/utils/packInstructions.js

@@ -0,0 +1,110 @@
+import { address, appendTransactionMessageInstructions, compileTransaction, createTransactionMessage, getTransactionEncoder, pipe, setTransactionMessageFeePayer, setTransactionMessageLifetimeUsingBlockhash, } from '@solana/kit';
+import { ErrorCodes, NosanaError } from '../errors/NosanaError.js';
+/**
+ * Maximum size, in bytes, of a serialized Solana transaction (the packet MTU limit).
+ * @group @nosana/kit
+ */
+export const TRANSACTION_SIZE_LIMIT = 1232;
+/**
+ * Maximum compute units a single Solana transaction may consume.
+ * @group @nosana/kit
+ */
+export const MAX_COMPUTE_UNITS = 1400000;
+// Placeholder fee payer and blockhash used purely to measure a transaction's
+// serialized size locally (no RPC). Neither value affects the byte length: a fee
+// payer is always one 32-byte account and a blockhash is always 32 bytes, so the
+// measurement is size-accurate. Using a placeholder fee payer that does not appear
+// in any instruction is the conservative choice — it can only ever over-count by a
+// single account, never under-count.
+const PLACEHOLDER_FEE_PAYER = address('11111111111111111111111111111112');
+const PLACEHOLDER_BLOCKHASH = {
+    blockhash: '11111111111111111111111111111111',
+    lastValidBlockHeight: 0n,
+};
+const transactionEncoder = getTransactionEncoder();
+/**
+ * Measure the serialized byte size of a transaction built from the given
+ * instructions. Compiles the message in-memory using placeholder fee payer and
+ * blockhash values — no network access and no signing required.
+ */
+function measureTransactionSize(instructions, feePayer) {
+    const message = pipe(createTransactionMessage({ version: 0 }), (tx) => setTransactionMessageFeePayer(feePayer, tx), (tx) => setTransactionMessageLifetimeUsingBlockhash(PLACEHOLDER_BLOCKHASH, tx), (tx) => appendTransactionMessageInstructions(instructions, tx));
+    return transactionEncoder.encode(compileTransaction(message)).length;
+}
+/**
+ * Greedily pack instruction groups into the fewest transactions that each stay
+ * within Solana's transaction size limit.
+ *
+ * Each entry of `groups` is an *atomic group*: a single instruction, or an array
+ * of instructions that must land together in the same transaction (e.g. a
+ * create-account + initialize pair). A group is never split across transactions;
+ * groups are filled into a bucket in order until the next group would overflow the
+ * size limit, at which point a new bucket is started.
+ *
+ * A bucket is bounded by two constraints, and is split whenever the next group
+ * would exceed either one:
+ * - Transaction size: determined by compiling each candidate transaction
+ *   in-memory and measuring its serialized length, so shared accounts (program
+ *   ids, fee payer, sysvars) are correctly deduplicated — no static estimate and
+ *   no RPC call.
+ * - Compute units (optional): when a `computeUnits` estimator is provided, the
+ *   cumulative estimated compute units of a bucket may not exceed
+ *   `maxComputeUnits`.
+ *
+ * @param groups Atomic instruction groups to pack, in order.
+ * @param options Packing options (fee payer, reserved instructions, limits).
+ * @returns An array of buckets; each bucket is a flat array of instructions for
+ *          one transaction.
+ * @throws {NosanaError} If a single group cannot fit in one transaction (by size
+ *         or compute units), since it cannot be split.
+ * @group @nosana/kit
+ */
+export function packInstructions(groups, options = {}) {
+    const feePayer = options.feePayer ?? PLACEHOLDER_FEE_PAYER;
+    const reserved = options.reservedInstructions ?? [];
+    const maxSize = options.maxTransactionSize ?? TRANSACTION_SIZE_LIMIT;
+    const computeUnitsOf = options.computeUnits;
+    const maxCU = options.maxComputeUnits ?? MAX_COMPUTE_UNITS;
+    const groupComputeUnits = (ixs) => computeUnitsOf ? ixs.reduce((sum, ix) => sum + computeUnitsOf(ix), 0) : 0;
+    const buckets = [];
+    let current = [];
+    let currentCU = 0;
+    const tooLargeToSplit = (groupSize, constraint) => {
+        const limit = constraint === 'size' ? `${maxSize} bytes` : `${maxCU} compute units`;
+        throw new NosanaError(`An atomic group of ${groupSize} instruction(s) exceeds the maximum transaction ` +
+            `${constraint} (${limit}) and cannot be split across transactions`, ErrorCodes.TRANSACTION_ERROR);
+    };
+    for (const group of groups) {
+        const groupIxs = Array.isArray(group) ? group : [group];
+        if (groupIxs.length === 0)
+            continue;
+        const groupCU = groupComputeUnits(groupIxs);
+        const withGroup = [...current, ...groupIxs];
+        const sizeFits = measureTransactionSize([...reserved, ...withGroup], feePayer) <= maxSize;
+        const computeFits = !computeUnitsOf || currentCU + groupCU <= maxCU;
+        if (sizeFits && computeFits) {
+            current = withGroup;
+            currentCU += groupCU;
+            continue;
+        }
+        // The group does not fit alongside the current bucket's contents.
+        if (current.length === 0) {
+            // Nothing to flush — the group cannot fit even on its own.
+            tooLargeToSplit(groupIxs.length, sizeFits ? 'compute units' : 'size');
+        }
+        // Flush the current bucket and place the group into a fresh one.
+        buckets.push(current);
+        if (measureTransactionSize([...reserved, ...groupIxs], feePayer) > maxSize) {
+            tooLargeToSplit(groupIxs.length, 'size');
+        }
+        if (computeUnitsOf && groupCU > maxCU) {
+            tooLargeToSplit(groupIxs.length, 'compute units');
+        }
+        current = [...groupIxs];
+        currentCU = groupCU;
+    }
+    if (current.length > 0)
+        buckets.push(current);
+    return buckets;
+}
+//# sourceMappingURL=packInstructions.js.map

package/dist/utils/packInstructions.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nosana/kit",
-  "version": "2.3.1",
+  "version": "2.4.0",
   "description": "Nosana KIT",
   "type": "module",
   "main": "dist/index.js",
@@ -71,5 +71,5 @@
     "package.json",
     "README.md"
   ],
-  "gitHead": "f0557eb71c17043450f159a72d67967a6045c74a"
+  "gitHead": "727e525c44bdb61ec109d23d0f850475e1e0cc55"
 }