A utility to estimate the compute unit consumption of a transaction m…

…essage (#2703)

# Summary

Correctly budgeting a compute unit limit for your transaction message can increase the probabilty 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.

This is a utility that helps you to estimate the actual compute unit cost of a given transaction message using the simulator.

## Example

```ts
import { getSetComputeLimitInstruction } from "@solana-program/compute-budget";
import {
  createSolanaRpc,
  getComputeUnitEstimateForTransactionMessageFactory,
  pipe,
} from "@solana/web3.js";

// 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
  );
```

## Notes

- The compute unit estimate is just that – 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.
- 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.

# Test Plan

```shell
cd packages/library
pnpm turbo test:unit:node test:unit:browser
```

.changeset/two-cougars-try.md

@@ -0,0 +1,5 @@
+---
+"@solana/web3.js-experimental": patch
+---
+
+Created a utility function to estimate the compute unit consumption of a transaction message

packages/errors/src/codes.ts

@@ -202,6 +202,7 @@ export const SOLANA_ERROR__TRANSACTION__INVALID_NONCE_TRANSACTION_FIRST_INSTRUCT
 export const SOLANA_ERROR__TRANSACTION__ADDRESSES_CANNOT_SIGN_TRANSACTION = 5663015 as const;
 export const SOLANA_ERROR__TRANSACTION__CANNOT_ENCODE_WITH_EMPTY_SIGNATURES = 5663016 as const;
 export const SOLANA_ERROR__TRANSACTION__MESSAGE_SIGNATURES_MISMATCH = 5663017 as const;
+export const SOLANA_ERROR__TRANSACTION__FAILED_TO_ESTIMATE_COMPUTE_LIMIT = 5663018 as const;
 
 // Transaction errors.
 // Reserve error codes starting with [7050000-7050999] for the Rust enum `TransactionError`.
@@ -484,6 +485,7 @@ export type SolanaErrorCode =
     | typeof SOLANA_ERROR__TRANSACTION__FAILED_TO_DECOMPILE_ADDRESS_LOOKUP_TABLE_INDEX_OUT_OF_RANGE
     | typeof SOLANA_ERROR__TRANSACTION__FAILED_TO_DECOMPILE_FEE_PAYER_MISSING
     | typeof SOLANA_ERROR__TRANSACTION__FAILED_TO_DECOMPILE_INSTRUCTION_PROGRAM_ADDRESS_NOT_FOUND
+    | typeof SOLANA_ERROR__TRANSACTION__FAILED_TO_ESTIMATE_COMPUTE_LIMIT
     | typeof SOLANA_ERROR__TRANSACTION__FEE_PAYER_MISSING
     | typeof SOLANA_ERROR__TRANSACTION__FEE_PAYER_SIGNATURE_MISSING
     | typeof SOLANA_ERROR__TRANSACTION__INVALID_NONCE_TRANSACTION_FIRST_INSTRUCTION_MUST_BE_ADVANCE_NONCE

packages/errors/src/messages.ts

@@ -171,6 +171,7 @@ import {
     SOLANA_ERROR__TRANSACTION__FAILED_TO_DECOMPILE_ADDRESS_LOOKUP_TABLE_INDEX_OUT_OF_RANGE,
     SOLANA_ERROR__TRANSACTION__FAILED_TO_DECOMPILE_FEE_PAYER_MISSING,
     SOLANA_ERROR__TRANSACTION__FAILED_TO_DECOMPILE_INSTRUCTION_PROGRAM_ADDRESS_NOT_FOUND,
+    SOLANA_ERROR__TRANSACTION__FAILED_TO_ESTIMATE_COMPUTE_LIMIT,
     SOLANA_ERROR__TRANSACTION__FEE_PAYER_MISSING,
     SOLANA_ERROR__TRANSACTION__FEE_PAYER_SIGNATURE_MISSING,
     SOLANA_ERROR__TRANSACTION__INVALID_NONCE_TRANSACTION_FIRST_INSTRUCTION_MUST_BE_ADVANCE_NONCE,
@@ -570,6 +571,10 @@ export const SolanaErrorMessages: Readonly<{
     [SOLANA_ERROR__TRANSACTION__FAILED_TO_DECOMPILE_FEE_PAYER_MISSING]: 'No fee payer set in CompiledTransaction',
     [SOLANA_ERROR__TRANSACTION__FAILED_TO_DECOMPILE_INSTRUCTION_PROGRAM_ADDRESS_NOT_FOUND]:
         'Could not find program address at index $index',
+    [SOLANA_ERROR__TRANSACTION__FAILED_TO_ESTIMATE_COMPUTE_LIMIT]:
+        'Failed to estimate the compute unit consumption for this transaction message. This is ' +
+        'likely because simulating the transaction failed. Inspect the `cause` property of this ' +
+        'error to learn more',
     [SOLANA_ERROR__TRANSACTION__FEE_PAYER_MISSING]: 'Transaction is missing a fee payer.',
     [SOLANA_ERROR__TRANSACTION__FEE_PAYER_SIGNATURE_MISSING]:
         "Could not determine this transaction's signature. Make sure that the transaction has " +

packages/library/README.md

@@ -880,6 +880,46 @@ const signedTransaction = await signTransaction([signer], transactionMessageWith
 // => "Property 'lifetimeConstraint' is missing in type"
 ```
 
+### Calibrating A Transaction Message's Compute Unit Budget
+
+Correctly budgeting a compute unit limit for your transaction message can increase the probabilty 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.
+
+Use this utility to estimate the actual compute unit cost of a given transaction message.
+
+```ts
+import { getSetComputeLimitInstruction } from '@solana-program/compute-budget';
+import { createSolanaRpc, getComputeUnitEstimateForTransactionMessageFactory, pipe } from '@solana/web3.js';
+
+// 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 – 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.
+
 ### Helpers For Building Transaction Messages
 
 Building transaction messages in this manner might feel different from what you’re used to. Also, we certainly wouldn’t want you to have to bind transformed transaction messages to a new variable at each step, so we have released a functional programming library dubbed `@solana/functional` that lets you build transaction messages in **pipelines**. Here’s how it can be used:

packages/library/src/__tests__/compute-limit-internal-test.ts

@@ -0,0 +1,261 @@
+import { Address } from '@solana/addresses';
+import {
+    SOLANA_ERROR__INSTRUCTION_ERROR__INSUFFICIENT_FUNDS,
+    SOLANA_ERROR__TRANSACTION__FAILED_TO_ESTIMATE_COMPUTE_LIMIT,
+    SolanaError,
+} from '@solana/errors';
+import { AccountRole } from '@solana/instructions';
+import { Rpc, SimulateTransactionApi } from '@solana/rpc';
+import { Blockhash } from '@solana/rpc-types';
+import { ITransactionMessageWithFeePayer, Nonce, TransactionMessage } from '@solana/transaction-messages';
+
+import { getComputeUnitEstimateForTransactionMessage_INTERNAL_ONLY_DO_NOT_EXPORT } from '../compute-limit-internal';
+
+const FOREVER_PROMISE = new Promise(() => {
+    /* never resolve */
+});
+
+const MOCK_BLOCKHASH_LIFETIME_CONSTRAINT = {
+    blockhash: 'GNtuHnNyW68wviopST3ki37Afv7LPphxfSwiHAkX5Q9H' as Blockhash,
+    lastValidBlockHeight: 0n,
+} as const;
+
+describe('getComputeUnitEstimateForTransactionMessage_INTERNAL_ONLY_DO_NOT_EXPORT', () => {
+    let sendSimulateTransactionRequest: jest.Mock;
+    let mockTransactionMessage: ITransactionMessageWithFeePayer & TransactionMessage;
+    let rpc: Rpc<SimulateTransactionApi>;
+    let simulateTransaction: jest.Mock;
+    beforeEach(() => {
+        mockTransactionMessage = {
+            feePayer: '7U8VWgTUucttJPt5Bbkt48WknWqRGBfstBt8qqLHnfPT' as Address,
+            instructions: [],
+            version: 0,
+        };
+        sendSimulateTransactionRequest = jest.fn().mockReturnValue(FOREVER_PROMISE);
+        simulateTransaction = jest.fn().mockReturnValue({ send: sendSimulateTransactionRequest });
+        rpc = {
+            simulateTransaction,
+        };
+    });
+    it('aborts the `simulateTransaction` request when aborted', () => {
+        const abortController = new AbortController();
+        getComputeUnitEstimateForTransactionMessage_INTERNAL_ONLY_DO_NOT_EXPORT({
+            abortSignal: abortController.signal,
+            rpc,
+            transactionMessage: {
+                ...mockTransactionMessage,
+                lifetimeConstraint: MOCK_BLOCKHASH_LIFETIME_CONSTRAINT,
+            },
+        });
+        expect(sendSimulateTransactionRequest).toHaveBeenCalledWith({
+            abortSignal: expect.objectContaining({ aborted: false }),
+        });
+        abortController.abort();
+        expect(sendSimulateTransactionRequest).toHaveBeenCalledWith({
+            abortSignal: expect.objectContaining({ aborted: true }),
+        });
+    });
+    it('passes the expected basic input to the simulation request', () => {
+        const transactionMessage = {
+            ...mockTransactionMessage,
+            lifetimeConstraint: MOCK_BLOCKHASH_LIFETIME_CONSTRAINT,
+        };
+        getComputeUnitEstimateForTransactionMessage_INTERNAL_ONLY_DO_NOT_EXPORT({
+            commitment: 'finalized',
+            minContextSlot: 42n,
+            rpc,
+            transactionMessage,
+        });
+        expect(simulateTransaction).toHaveBeenCalledWith(
+            expect.any(String),
+            expect.objectContaining({
+                commitment: 'finalized',
+                encoding: 'base64',
+                minContextSlot: 42n,
+                sigVerify: false,
+            }),
+        );
+    });
+    it('appends a set compute unit limit instruction when one does not exist', async () => {
+        expect.assertions(1);
+        await jest.isolateModulesAsync(async () => {
+            jest.mock('@solana/transactions');
+            const [
+                { compileTransaction },
+                { getComputeUnitEstimateForTransactionMessage_INTERNAL_ONLY_DO_NOT_EXPORT },
+            ] = await Promise.all([
+                // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+                // @ts-ignore
+                import('@solana/transactions'),
+                // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+                // @ts-ignore
+                import('../compute-limit-internal'),
+            ]);
+            const transactionMessage = {
+                ...mockTransactionMessage, // No `SetComputeUnitLimit` instruction
+                lifetimeConstraint: MOCK_BLOCKHASH_LIFETIME_CONSTRAINT,
+            };
+            getComputeUnitEstimateForTransactionMessage_INTERNAL_ONLY_DO_NOT_EXPORT({
+                rpc,
+                transactionMessage,
+            });
+            expect(compileTransaction).toHaveBeenCalledWith({
+                ...transactionMessage,
+                instructions: [
+                    ...transactionMessage.instructions,
+                    {
+                        data:
+                            // prettier-ignore
+                            new Uint8Array([
+                                0x02, // SetComputeUnitLimit instruction inde
+                                0xff, 0xff, 0xff, 0xff, // U32::MAX
+                            ]),
+                        programAddress: 'ComputeBudget111111111111111111111111111111',
+                    },
+                ],
+            });
+        });
+    });
+    it('replaces the existing set compute unit limit instruction when one exists', async () => {
+        expect.assertions(1);
+        await jest.isolateModulesAsync(async () => {
+            jest.mock('@solana/transactions');
+            const [
+                { compileTransaction },
+                { getComputeUnitEstimateForTransactionMessage_INTERNAL_ONLY_DO_NOT_EXPORT },
+            ] = await Promise.all([
+                // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+                // @ts-ignore
+                import('@solana/transactions'),
+                // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+                // @ts-ignore
+                import('../compute-limit-internal'),
+            ]);
+            const transactionMessage = {
+                ...mockTransactionMessage,
+                instructions: [
+                    { programAddress: '4Kk4nA3F2nWHCcuyT8nR6oF7HQUQHmmzAVD5k8FQPKB2' as Address },
+                    {
+                        data:
+                            // prettier-ignore
+                            new Uint8Array([
+                            0x02, // SetComputeUnitLimit instruction inde
+                            0x01, 0x02, 0x03, 0x04, // ComputeUnits(u32)
+                        ]),
+                        programAddress: 'ComputeBudget111111111111111111111111111111' as Address,
+                    },
+                    { programAddress: '4Kk4nA3F2nWHCcuyT8nR6oF7HQUQHmmzAVD5k8FQPKB2' as Address },
+                ],
+                lifetimeConstraint: MOCK_BLOCKHASH_LIFETIME_CONSTRAINT,
+            };
+            getComputeUnitEstimateForTransactionMessage_INTERNAL_ONLY_DO_NOT_EXPORT({
+                rpc,
+                transactionMessage,
+            });
+            expect(compileTransaction).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    instructions: [
+                        transactionMessage.instructions[0],
+                        {
+                            ...transactionMessage.instructions[1],
+                            data: new Uint8Array([0x02, 0xff, 0xff, 0xff, 0xff]), // Replaced with U32::MAX
+                        },
+                        transactionMessage.instructions[2],
+                    ],
+                }),
+            );
+        });
+    });
+    it('does not ask for a replacement blockhash when the transaction message is a durable nonce transaction', () => {
+        getComputeUnitEstimateForTransactionMessage_INTERNAL_ONLY_DO_NOT_EXPORT({
+            rpc,
+            transactionMessage: {
+                ...mockTransactionMessage,
+                instructions: [
+                    {
+                        accounts: [
+                            {
+                                address: '7wJFRFuAE9x5Ptnz2VoBWsfecTCfuuM2sQCpECGypnTU' as Address,
+                                role: AccountRole.WRITABLE,
+                            },
+                            {
+                                address: 'SysvarRecentB1ockHashes11111111111111111111' as Address,
+                                role: AccountRole.READONLY,
+                            },
+                            {
+                                address: 'HzMoc78z1VNNf9nwD4Czt6CDYEb9LVD8KsVGP46FEmyJ' as Address,
+                                role: AccountRole.READONLY_SIGNER,
+                            },
+                        ],
+                        data: new Uint8Array([4, 0, 0, 0]),
+                        programAddress: '11111111111111111111111111111111' as Address,
+                    },
+                ],
+                lifetimeConstraint: {
+                    nonce: 'BzAqD6382v5r1pcELoi8HWrBDV4dSL9NGemMn2JYAhxc' as Nonce,
+                },
+            },
+        });
+        expect(simulateTransaction).toHaveBeenCalledWith(
+            expect.anything(),
+            expect.objectContaining({ replaceRecentBlockhash: false }),
+        );
+    });
+    it('asks for a replacement blockhash even when the transaction message has a blockhash lifetime', () => {
+        getComputeUnitEstimateForTransactionMessage_INTERNAL_ONLY_DO_NOT_EXPORT({
+            rpc,
+            transactionMessage: {
+                ...mockTransactionMessage,
+                lifetimeConstraint: MOCK_BLOCKHASH_LIFETIME_CONSTRAINT,
+            },
+        });
+        expect(simulateTransaction).toHaveBeenCalledWith(
+            expect.anything(),
+            expect.objectContaining({ replaceRecentBlockhash: true }),
+        );
+    });
+    it('asks for a replacement blockhash when the transaction message has no lifetime', () => {
+        getComputeUnitEstimateForTransactionMessage_INTERNAL_ONLY_DO_NOT_EXPORT({
+            rpc,
+            transactionMessage: mockTransactionMessage,
+        });
+        expect(simulateTransaction).toHaveBeenCalledWith(
+            expect.anything(),
+            expect.objectContaining({ replaceRecentBlockhash: true }),
+        );
+    });
+    it('returns the estimated compute units on success', async () => {
+        expect.assertions(1);
+        sendSimulateTransactionRequest.mockResolvedValue({ value: { unitsConsumed: 42n } });
+        const estimatePromise = getComputeUnitEstimateForTransactionMessage_INTERNAL_ONLY_DO_NOT_EXPORT({
+            rpc,
+            transactionMessage: mockTransactionMessage,
+        });
+        await expect(estimatePromise).resolves.toBe(42);
+    });
+    it('caps the estimated compute units to U32::MAX', async () => {
+        expect.assertions(1);
+        sendSimulateTransactionRequest.mockResolvedValue({ value: { unitsConsumed: 4294967295n /* U32::MAX + 1 */ } });
+        const estimatePromise = getComputeUnitEstimateForTransactionMessage_INTERNAL_ONLY_DO_NOT_EXPORT({
+            rpc,
+            transactionMessage: mockTransactionMessage,
+        });
+        await expect(estimatePromise).resolves.toBe(4294967295 /* U32::MAX */);
+    });
+    it('throws with the cause when simulation fails', async () => {
+        expect.assertions(1);
+        const simulationError = new SolanaError(SOLANA_ERROR__INSTRUCTION_ERROR__INSUFFICIENT_FUNDS, {
+            index: 42,
+        });
+        sendSimulateTransactionRequest.mockRejectedValue(simulationError);
+        const estimatePromise = getComputeUnitEstimateForTransactionMessage_INTERNAL_ONLY_DO_NOT_EXPORT({
+            rpc,
+            transactionMessage: mockTransactionMessage,
+        });
+        await expect(estimatePromise).rejects.toThrow(
+            new SolanaError(SOLANA_ERROR__TRANSACTION__FAILED_TO_ESTIMATE_COMPUTE_LIMIT, {
+                cause: simulationError,
+            }),
+        );
+    });
+});