@solana-program/compute-budget 0.7.0 → 0.8.0

package/dist/types/estimateComputeLimitInternal.d.ts

@@ -0,0 +1,87 @@
+import { Commitment, CompilableTransactionMessage, ITransactionMessageWithFeePayer, Rpc, SimulateTransactionApi, Slot, TransactionMessage } from '@solana/kit';
+export type EstimateComputeUnitLimitFactoryConfig = Readonly<{
+    /** An object that supports the {@link SimulateTransactionApi} of the Solana RPC API */
+    rpc: Rpc<SimulateTransactionApi>;
+}>;
+export type EstimateComputeUnitLimitFactoryFunction = (transactionMessage: CompilableTransactionMessage | (TransactionMessage & ITransactionMessageWithFeePayer), config?: EstimateComputeUnitLimitFactoryFunctionConfig) => Promise<number>;
+export type EstimateComputeUnitLimitFactoryFunctionConfig = {
+    abortSignal?: AbortSignal;
+    /**
+     * Compute the estimate as of the highest slot that has reached this level of commitment.
+     *
+     * @defaultValue Whichever default is applied by the underlying {@link RpcApi} in use. For
+     * example, when using an API created by a `createSolanaRpc*()` helper, the default commitment
+     * is `"confirmed"` unless configured otherwise. Unmitigated by an API layer on the client, the
+     * default commitment applied by the server is `"finalized"`.
+     */
+    commitment?: Commitment;
+    /**
+     * Prevents accessing stale data by enforcing that the RPC node has processed transactions up to
+     * this slot
+     */
+    minContextSlot?: Slot;
+};
+type EstimateComputeUnitLimitConfig = EstimateComputeUnitLimitFactoryFunctionConfig & Readonly<{
+    rpc: Rpc<SimulateTransactionApi>;
+    transactionMessage: CompilableTransactionMessage | (TransactionMessage & ITransactionMessageWithFeePayer);
+}>;
+/**
+ * Simulates a transaction message on the network and returns the number of compute units it
+ * consumed during simulation.
+ *
+ * The estimate this function returns can be used to set a compute unit limit on the transaction.
+ * Correctly budgeting a compute unit limit for your transaction message can increase the probability
+ * that your transaction will be accepted for processing.
+ *
+ * If you don't declare a compute unit limit on your transaction, validators will assume an upper
+ * limit of 200K compute units (CU) per instruction. Since validators have an incentive to pack as
+ * many transactions into each block as possible, they may choose to include transactions that they
+ * know will fit into the remaining compute budget for the current block over transactions that
+ * might not. For this reason, you should set a compute unit limit on each of your transaction
+ * messages, whenever possible.
+ *
+ * ## Example
+ *
+ * ```ts
+ * import { getSetComputeLimitInstruction } from '@solana-program/compute-budget';
+ * import { createSolanaRpc, getComputeUnitEstimateForTransactionMessageFactory, pipe } from '@solana/kit';
+ *
+ * // Create an estimator function.
+ * const rpc = createSolanaRpc('http://127.0.0.1:8899');
+ * const getComputeUnitEstimateForTransactionMessage =
+ *     getComputeUnitEstimateForTransactionMessageFactory({ rpc });
+ *
+ * // Create your transaction message.
+ * const transactionMessage = pipe(
+ *     createTransactionMessage({ version: 'legacy' }),
+ *     /* ... *\/
+ * );
+ *
+ * // Request an estimate of the actual compute units this message will consume.
+ * const computeUnitsEstimate =
+ *     await getComputeUnitEstimateForTransactionMessage(transactionMessage);
+ *
+ * // Set the transaction message's compute unit budget.
+ * const transactionMessageWithComputeUnitLimit = prependTransactionMessageInstruction(
+ *     getSetComputeLimitInstruction({ units: computeUnitsEstimate }),
+ *     transactionMessage,
+ * );
+ * ```
+ *
+ * > [!WARNING]
+ * > The compute unit estimate is just that &ndash; an estimate. The compute unit consumption of the
+ * > actual transaction might be higher or lower than what was observed in simulation. Unless you
+ * > are confident that your particular transaction message will consume the same or fewer compute
+ * > units as was estimated, you might like to augment the estimate by either a fixed number of CUs
+ * > or a multiplier.
+ *
+ * > [!NOTE]
+ * > If you are preparing an _unsigned_ transaction, destined to be signed and submitted to the
+ * > network by a wallet, you might like to leave it up to the wallet to determine the compute unit
+ * > limit. Consider that the wallet might have a more global view of how many compute units certain
+ * > types of transactions consume, and might be able to make better estimates of an appropriate
+ * > compute unit budget.
+ */
+export declare function estimateComputeUnitLimit({ transactionMessage, ...configs }: EstimateComputeUnitLimitConfig): Promise<number>;
+export {};
+//# sourceMappingURL=estimateComputeLimitInternal.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"estimateComputeLimitInternal.d.ts","sourceRoot":"","sources":["../../src/estimateComputeLimitInternal.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,4BAA4B,EAK5B,+BAA+B,EAE/B,GAAG,EACH,sBAAsB,EACtB,IAAI,EAKJ,kBAAkB,EACnB,MAAM,aAAa,CAAC;AAKrB,MAAM,MAAM,qCAAqC,GAAG,QAAQ,CAAC;IAC3D,uFAAuF;IACvF,GAAG,EAAE,GAAG,CAAC,sBAAsB,CAAC,CAAC;CAClC,CAAC,CAAC;AAEH,MAAM,MAAM,uCAAuC,GAAG,CACpD,kBAAkB,EACd,4BAA4B,GAC5B,CAAC,kBAAkB,GAAG,+BAA+B,CAAC,EAC1D,MAAM,CAAC,EAAE,6CAA6C,KACnD,OAAO,CAAC,MAAM,CAAC,CAAC;AAErB,MAAM,MAAM,6CAA6C,GAAG;IAC1D,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB;;;OAGG;IACH,cAAc,CAAC,EAAE,IAAI,CAAC;CACvB,CAAC;AAEF,KAAK,8BAA8B,GACjC,6CAA6C,GAC3C,QAAQ,CAAC;IACP,GAAG,EAAE,GAAG,CAAC,sBAAsB,CAAC,CAAC;IACjC,kBAAkB,EACd,4BAA4B,GAC5B,CAAC,kBAAkB,GAAG,+BAA+B,CAAC,CAAC;CAC5D,CAAC,CAAC;AAEP;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,wBAAsB,wBAAwB,CAAC,EAC7C,kBAAkB,EAClB,GAAG,OAAO,EACX,EAAE,8BAA8B,GAAG,OAAO,CAAC,MAAM,CAAC,CAelD"}

package/dist/types/index.d.ts

@@ -1,2 +1,7 @@
 export * from './generated';
+export * from './constants';
+export * from './estimateAndSetComputeLimit';
+export * from './estimateComputeLimit';
+export * from './setComputeLimit';
+export * from './setComputePrice';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAE5B,cAAc,aAAa,CAAC;AAC5B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC"}

package/dist/types/internal.d.ts

@@ -0,0 +1,35 @@
+import { BaseTransactionMessage, IInstruction, MicroLamports } from '@solana/kit';
+import { SetComputeUnitLimitInstruction, SetComputeUnitPriceInstruction } from './generated';
+/**
+ * Finds the index of the first `SetComputeUnitLimit` instruction in a transaction message
+ * and its set limit, if any.
+ */
+export declare function getSetComputeUnitLimitInstructionIndexAndUnits(transactionMessage: BaseTransactionMessage): {
+    index: number;
+    units: number;
+} | null;
+/**
+ * Finds the index of the first `SetComputeUnitLimit` instruction in a transaction message, if any.
+ */
+export declare function getSetComputeUnitLimitInstructionIndex(transactionMessage: BaseTransactionMessage): number;
+/**
+ * Checks if the given instruction is a `SetComputeUnitLimit` instruction.
+ */
+export declare function isSetComputeUnitLimitInstruction(instruction: IInstruction): instruction is SetComputeUnitLimitInstruction;
+/**
+ * Finds the index of the first `SetComputeUnitPrice` instruction in a transaction message
+ * and its set micro-lamports, if any.
+ */
+export declare function getSetComputeUnitPriceInstructionIndexAndMicroLamports(transactionMessage: BaseTransactionMessage): {
+    index: number;
+    microLamports: MicroLamports;
+} | null;
+/**
+ * Finds the index of the first `SetComputeUnitPrice` instruction in a transaction message, if any.
+ */
+export declare function getSetComputeUnitPriceInstructionIndex(transactionMessage: BaseTransactionMessage): number;
+/**
+ * Checks if the given instruction is a `SetComputeUnitPrice` instruction.
+ */
+export declare function isSetComputeUnitPriceInstruction(instruction: IInstruction): instruction is SetComputeUnitPriceInstruction;
+//# sourceMappingURL=internal.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../../src/internal.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EAGtB,YAAY,EACZ,aAAa,EAEd,MAAM,aAAa,CAAC;AACrB,OAAO,EAIL,8BAA8B,EAC9B,8BAA8B,EAC/B,MAAM,aAAa,CAAC;AAErB;;;GAGG;AACH,wBAAgB,8CAA8C,CAC5D,kBAAkB,EAAE,sBAAsB,GACzC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAYzC;AAED;;GAEG;AACH,wBAAgB,sCAAsC,CACpD,kBAAkB,EAAE,sBAAsB,UAK3C;AAED;;GAEG;AACH,wBAAgB,gCAAgC,CAC9C,WAAW,EAAE,YAAY,GACxB,WAAW,IAAI,8BAA8B,CAM/C;AAED;;;GAGG;AACH,wBAAgB,sDAAsD,CACpE,kBAAkB,EAAE,sBAAsB,GACzC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,aAAa,CAAA;CAAE,GAAG,IAAI,CAYxD;AAED;;GAEG;AACH,wBAAgB,sCAAsC,CACpD,kBAAkB,EAAE,sBAAsB,UAK3C;AAED;;GAEG;AACH,wBAAgB,gCAAgC,CAC9C,WAAW,EAAE,YAAY,GACxB,WAAW,IAAI,8BAA8B,CAM/C"}

package/dist/types/internalMoveToKit.d.ts

@@ -0,0 +1,20 @@
+import { BaseTransactionMessage, TransactionMessageWithBlockhashLifetime, TransactionMessageWithDurableNonceLifetime } from '@solana/kit';
+/**
+ * An invalid blockhash lifetime constraint used as a placeholder for
+ * transaction messages that are not yet ready to be compiled.
+ *
+ * This enables various operations on the transaction message, such as
+ * simulating it or calculating its transaction size, whilst defering
+ * the actual blockhash to a later stage.
+ */
+export declare const PROVISORY_BLOCKHASH_LIFETIME_CONSTRAINT: TransactionMessageWithBlockhashLifetime['lifetimeConstraint'];
+/**
+ * Sets a provisory blockhash lifetime constraint on the transaction message
+ * if and only if it doesn't already have a lifetime constraint.
+ */
+export declare function fillMissingTransactionMessageLifetimeUsingProvisoryBlockhash<TTransactionMessage extends BaseTransactionMessage>(transactionMessage: TTransactionMessage): TTransactionMessage & (TransactionMessageWithBlockhashLifetime | TransactionMessageWithDurableNonceLifetime);
+/**
+ * Sets a provisory blockhash lifetime constraint on the transaction message.
+ */
+export declare function setTransactionMessageLifetimeUsingProvisoryBlockhash<TTransactionMessage extends BaseTransactionMessage>(transactionMessage: TTransactionMessage): TTransactionMessage & TransactionMessageWithBlockhashLifetime;
+//# sourceMappingURL=internalMoveToKit.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"internalMoveToKit.d.ts","sourceRoot":"","sources":["../../src/internalMoveToKit.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,sBAAsB,EAGtB,uCAAuC,EACvC,0CAA0C,EAC3C,MAAM,aAAa,CAAC;AAErB;;;;;;;GAOG;AACH,eAAO,MAAM,uCAAuC,EAAE,uCAAuC,CAAC,oBAAoB,CAI/G,CAAC;AAEJ;;;GAGG;AACH,wBAAgB,4DAA4D,CAC1E,mBAAmB,SAAS,sBAAsB,EAElD,kBAAkB,EAAE,mBAAmB,GACtC,mBAAmB,GACpB,CACI,uCAAuC,GACvC,0CAA0C,CAC7C,CAcF;AAED;;GAEG;AACH,wBAAgB,oDAAoD,CAClE,mBAAmB,SAAS,sBAAsB,EAElD,kBAAkB,EAAE,mBAAmB,GACtC,mBAAmB,GAAG,uCAAuC,CAK/D"}

package/dist/types/setComputeLimit.d.ts

@@ -0,0 +1,36 @@
+import { BaseTransactionMessage } from '@solana/kit';
+/**
+ * Appends a `SetComputeUnitLimit` instruction with a provisory
+ * compute unit limit to a given transaction message
+ * if and only if it does not already have one.
+ *
+ * @example
+ * ```ts
+ * const transactionMessage = pipe(
+ *   createTransactionMessage({ version: 0 }),
+ *   fillProvisorySetComputeUnitLimitInstruction,
+ *   // ...
+ * );
+ * ```
+ */
+export declare function fillProvisorySetComputeUnitLimitInstruction<TTransactionMessage extends BaseTransactionMessage>(transactionMessage: TTransactionMessage): TTransactionMessage;
+/**
+ * Updates the first `SetComputeUnitLimit` instruction in a transaction message
+ * with the given units, or appends a new instruction if none exists.
+ * A function of the current value can be provided instead of a static value.
+ *
+ * @param units - The new compute unit limit, or a function that takes the previous
+ *                compute unit limit and returns the new limit.
+ * @param transactionMessage - The transaction message to update.
+ *
+ * @example
+ * ```ts
+ * const updatedTransactionMessage = updateOrAppendSetComputeUnitLimitInstruction(
+ *   // E.g. Keep the current limit if it is set, otherwise set it to the maximum.
+ *   (currentUnits) => currentUnits === null ? MAX_COMPUTE_UNIT_LIMIT : currentUnits,
+ *   transactionMessage,
+ * );
+ * ```
+ */
+export declare function updateOrAppendSetComputeUnitLimitInstruction<TTransactionMessage extends BaseTransactionMessage>(units: number | ((previousUnits: number | null) => number), transactionMessage: TTransactionMessage): TTransactionMessage;
+//# sourceMappingURL=setComputeLimit.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"setComputeLimit.d.ts","sourceRoot":"","sources":["../../src/setComputeLimit.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,sBAAsB,EACvB,MAAM,aAAa,CAAC;AAKrB;;;;;;;;;;;;;GAaG;AACH,wBAAgB,2CAA2C,CACzD,mBAAmB,SAAS,sBAAsB,EAClD,kBAAkB,EAAE,mBAAmB,uBAMxC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,4CAA4C,CAC1D,mBAAmB,SAAS,sBAAsB,EAElD,KAAK,EAAE,MAAM,GAAG,CAAC,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,KAAK,MAAM,CAAC,EAC1D,kBAAkB,EAAE,mBAAmB,GACtC,mBAAmB,CA0BrB"}

package/dist/types/setComputePrice.d.ts

@@ -0,0 +1,34 @@
+import { BaseTransactionMessage, MicroLamports } from '@solana/kit';
+/**
+ * Sets the compute unit price of a transaction message in micro-Lamports.
+ *
+ * @example
+ * ```ts
+ * const transactionMessage = pipe(
+ *   createTransactionMessage({ version: 0 }),
+ *   (m) => setTransactionMessageComputeUnitPrice(10_000, m),
+ *   // ...
+ * );
+ * ```
+ */
+export declare function setTransactionMessageComputeUnitPrice<TTransactionMessage extends BaseTransactionMessage>(microLamports: number | bigint, transactionMessage: TTransactionMessage): TTransactionMessage;
+/**
+ * Updates the first `SetComputeUnitPrice` instruction in a transaction message
+ * with the given micro-Lamports, or appends a new instruction if none exists.
+ * A function of the current value can be provided instead of a static value.
+ *
+ * @param microLamports - The new compute unit price, or a function that
+ *                        takes the previous price and returns the new one.
+ * @param transactionMessage - The transaction message to update.
+ *
+ * @example
+ * ```ts
+ * const updatedTransactionMessage = updateOrAppendSetComputeUnitPriceInstruction(
+ *   // E.g. double the current price or set it to 10_000 if it isn't set.
+ *   (currentPrice) => currentPrice === null ? 10_000 : currentPrice * 2,
+ *   transactionMessage,
+ * );
+ * ```
+ */
+export declare function updateOrAppendSetComputeUnitPriceInstruction<TTransactionMessage extends BaseTransactionMessage>(microLamports: MicroLamports | ((previousMicroLamports: MicroLamports | null) => MicroLamports), transactionMessage: TTransactionMessage): TTransactionMessage;
+//# sourceMappingURL=setComputePrice.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"setComputePrice.d.ts","sourceRoot":"","sources":["../../src/setComputePrice.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,sBAAsB,EACtB,aAAa,EACd,MAAM,aAAa,CAAC;AAIrB;;;;;;;;;;;GAWG;AACH,wBAAgB,qCAAqC,CACnD,mBAAmB,SAAS,sBAAsB,EAClD,aAAa,EAAE,MAAM,GAAG,MAAM,EAAE,kBAAkB,EAAE,mBAAmB,uBAKxE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,4CAA4C,CAC1D,mBAAmB,SAAS,sBAAsB,EAElD,aAAa,EACT,aAAa,GACb,CAAC,CAAC,qBAAqB,EAAE,aAAa,GAAG,IAAI,KAAK,aAAa,CAAC,EACpE,kBAAkB,EAAE,mBAAmB,GACtC,mBAAmB,CAkCrB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solana-program/compute-budget",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "JavaScript client for the Compute Budget program",
   "sideEffects": false,
   "module": "./dist/src/index.mjs",
@@ -35,35 +35,24 @@
     "@solana/kit": "^2.1.0"
   },
   "devDependencies": {
-    "@ava/typescript": "^4.1.0",
     "@solana/eslint-config-solana": "^3.0.3",
     "@solana/kit": "^2.1.0",
     "@types/node": "^20",
     "@typescript-eslint/eslint-plugin": "^7.16.1",
     "@typescript-eslint/parser": "^7.16.1",
-    "ava": "^6.1.3",
     "eslint": "^8.57.0",
     "prettier": "^3.3.3",
     "rimraf": "^5.0.5",
     "tsup": "^8.1.2",
     "typedoc": "^0.25.12",
-    "typescript": "^5.5.3"
-  },
-  "ava": {
-    "nodeArguments": [
-      "--no-warnings"
-    ],
-    "typescript": {
-      "compile": false,
-      "rewritePaths": {
-        "test/": "dist/test/"
-      }
-    }
+    "typescript": "^5.5.3",
+    "vitest": "^3.1.3"
   },
   "scripts": {
     "build": "rimraf dist && tsup && tsc -p ./tsconfig.declarations.json",
     "build:docs": "typedoc",
-    "test": "ava",
+    "dev": "vitest",
+    "test": "vitest run",
     "lint": "eslint --ext js,ts,tsx src",
     "lint:fix": "eslint --fix --ext js,ts,tsx src",
     "format": "prettier --check src test",