A utility to estimate the compute unit consumption of a transaction message #2703

steveluscher · 2024-05-10T05:32:24Z

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

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

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

changeset-bot · 2024-05-10T05:32:27Z

🦋 Changeset detected

Latest commit: 2afc747

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 36 packages

Name	Type
@solana/web3.js-experimental	Patch
@solana/accounts	Patch
@solana/addresses	Patch
@solana/assertions	Patch
@solana/codecs-core	Patch
@solana/codecs-data-structures	Patch
@solana/codecs-numbers	Patch
@solana/codecs-strings	Patch
@solana/codecs	Patch
@solana/compat	Patch
@solana/errors	Patch
@solana/fast-stable-stringify	Patch
@solana/functional	Patch
@solana/instructions	Patch
@solana/keys	Patch
@solana/options	Patch
@solana/programs	Patch
@solana/rpc-api	Patch
@solana/rpc-graphql	Patch
@solana/rpc-parsed-types	Patch
@solana/rpc-spec-types	Patch
@solana/rpc-spec	Patch
@solana/rpc-subscriptions-api	Patch
@solana/rpc-subscriptions-spec	Patch
@solana/rpc-subscriptions-transport-websocket	Patch
@solana/rpc-subscriptions	Patch
@solana/rpc-transformers	Patch
@solana/rpc-transport-http	Patch
@solana/rpc-types	Patch
@solana/rpc	Patch
@solana/signers	Patch
@solana/sysvars	Patch
@solana/transaction-confirmation	Patch
@solana/transaction-messages	Patch
@solana/transactions	Patch
@solana/webcrypto-ed25519-polyfill	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

steveluscher · 2024-05-10T05:32:34Z

This stack of pull requests is managed by Graphite. Learn more about stacking.

Join @steveluscher and the rest of your teammates on Graphite

socket-security · 2024-05-10T05:35:48Z

👍 Dependency issues cleared. Learn more about Socket for GitHub ↗︎

This PR previously contained dependency changes with security issues that have been resolved, removed, or ignored.

View full report↗︎

steveluscher · 2024-05-10T05:36:11Z

packages/library/README.md

@@ -878,6 +878,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.


…validators will assume an upper limit of 200K compute units (CU) per instruction.

I didn't look this up. Is this true?

We looked into this a bit when we were looking at priority fees a while back. It's accurate, 200k per instruction (excluding those to compute budget program) with a 1.4M cap (which is the max CU allowed per transaction): https://github.com/solana-labs/solana/blob/4293f11cf13fc1e83f1baa2ca3bb2f8ea8f9a000/program-runtime/src/compute_budget.rs#L13

steveluscher · 2024-05-10T05:36:34Z

packages/library/README.md

+
+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.


cc/ @joncinque to check over.

Yep this is correct! It could even be more forceful, since validators will skip transactions that might go over the block limit in the default implementation.

For example, if there are 599k CUs left in the block, and the transaction has 3 top-level instructions, the validator gives it the default limit of 600k CUs, and will immediately skip it.

steveluscher · 2024-05-10T05:37:10Z

packages/library/README.md

+> 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.


Thoughts on this, @jordaaash?

Feel free to tag wallet folks.

steveluscher · 2024-05-10T05:39:22Z

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

+        if (unitsConsumed == null) {
+            // This should never be hit, because all RPCs should support `unitsConsumed` by now.
+            throw new SolanaError(SOLANA_ERROR__TRANSACTION__FAILED_TO_ESTIMATE_COMPUTE_LIMIT);
+        }


cc/ @joncinque

mcintyre94 · 2024-05-10T10:02:58Z

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

+     */
+    const existingSetComputeUnitLimitInstructionIndex =
+        transactionMessage.instructions.findIndex(isSetComputeLimitInstruction);
+    const maxComputeUnitLimitInstruction = createComputeUnitLimitInstruction(4294967295 /* U32::MAX */);


Speculative: this might increase the estimate because it's higher than the actual max allowed, which is 1.4M - so there might be CUs consumed normalising it to 1.4M that won't be consumed when it's set to a realistic value.

Oh nice catch! I tried this.

<1.4M u32::MAX

Same number of CUs. Looks like the min() gets called unconditionally, so takes the same amount?

https://github.com/anza-xyz/agave/blob/75cc70d3b6671362bf2605326b05e623b4a0e679/program-runtime/src/compute_budget_processor.rs#L128C9-L133

Bad: being wrong about this in the future

Also bad: hardcoding MAX_COMPUTE_UNIT_LIMIT into JS clients then not being able to take it back.

I think I'll leave it the way it is here.

Actually the absence of an effect here probably has more to do with this.

https://github.com/anza-xyz/agave/blob/d87e23d8d91c32d5f2be2bb3557c730bee1e9434/programs/compute-budget/src/lib.rs#L3

mcintyre94 · 2024-05-10T10:06:43Z

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

+            value: { unitsConsumed },
+        } = await rpc
+            .simulateTransaction(wireTransactionBytes, {
+                ...simulateConfig,


Since this is library and we can be opinionated, should we default the commitment to Confirmed instead of simulate's default of Finalized? It's most likely how they'll eventually send the transaction, and can still be explicitly set if needed.

We already do!

cb7702ca5#diff-7a402066b770e83587eb60550f8cd77d3cacaa6241250d312f639602a8eaf2e9R83

mcintyre94 · 2024-05-10T10:10:05Z

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

+        // FIXME: The simulation response returns compute units as a u64, but the `SetComputeLimit`
+        // instruction only accepts a u32. Until this changes, downcast it.
+        const downcastUnitsConsumed = unitsConsumed > 4294967295n ? 4294967295 : Number(unitsConsumed);
+        return downcastUnitsConsumed;


I'm not sure how much knowledge we want to bake in here, but in practice if this is >1.4M it's an error

I think I just want to let the server tell me, and if it tells me a wrong thing then oh well.

socket-security · 2024-05-10T17:28:21Z

New and removed dependencies detected. Learn more about Socket for GitHub ↗︎

Package	New capabilities	Transitives	Size	Publisher

🚮 Removed packages: npm/@types/node@18.19.33, npm/agadoo@3.0.0, npm/chalk@2.4.2, npm/dataloader@1.4.0, npm/eslint-config-turbo@1.13.3, npm/eslint-plugin-jest@27.9.0, npm/eslint-plugin-react-hooks@4.6.2, npm/eslint-plugin-simple-import-sort@10.0.0, npm/eslint-plugin-sort-keys-fix@1.1.2, npm/eslint-plugin-typescript-sort-keys@3.2.0, npm/eslint@8.57.0, npm/jest-environment-jsdom@30.0.0-alpha.3, npm/jest-runner-eslint@2.2.0, npm/jest-runner-prettier@1.0.0, npm/jest-watch-master@1.0.0, npm/jest-watch-select-projects@2.0.0, npm/jest-watch-typeahead@2.2.2, npm/jest@30.0.0-alpha.3, npm/node-fetch@2.7.0, npm/prettier@3.2.5, npm/rollup@3.29.4, npm/ts-node@10.9.2, npm/tsup@8.0.2, npm/turbo@1.13.3, npm/typescript@5.4.5, npm/undici-types@5.26.5

View full report↗︎

…essage

joncinque

This looks really great, thanks!

joncinque · 2024-05-16T10:51:20Z

packages/library/README.md

+
+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.


Yep this is correct! It could even be more forceful, since validators will skip transactions that might go over the block limit in the default implementation.

For example, if there are 599k CUs left in the block, and the transaction has 3 top-level instructions, the validator gives it the default limit of 600k CUs, and will immediately skip it.

joncinque · 2024-05-16T12:03:24Z

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

+function createComputeUnitLimitInstruction(units: number): IInstruction<typeof COMPUTE_BUDGET_PROGRAM_ADDRESS> {
+    const data = new Uint8Array(5);
+    data[0] = SET_COMPUTE_UNIT_LIMIT_INSTRUCTION_INDEX;
+    getU32Encoder().write(units, data, 1 /* offset */);
+    return Object.freeze({
+        data,
+        programAddress: COMPUTE_BUDGET_PROGRAM_ADDRESS,
+    });
+}


Unless it's exposed somewhere else, it might be nice to expose this too, and add an example of adding the compute unit limit instruction after getting the units consumed.

It's actually here:

https://github.com/solana-program/compute-budget/blob/f425ee62857b3154c85dc0f551898d5cfef67fa8/clients/js/src/generated/instructions/setComputeUnitLimit.ts#L78-L95

I would have used that actual function here, but unfortunately it would cause a circular dependency.

Gotcha, that works

This was referenced May 10, 2024

Convert tsx codeblocks in README to ts because there's no React code in here #2701

Merged

Update web3.js README for new TransactionMessage API #2702

Merged

steveluscher force-pushed the 05-09-a_utility_to_estimate_the_compute_unit_consumption_of_a_transaction_message branch from 2768f69 to 8ce397a Compare May 10, 2024 05:35

steveluscher requested a review from joncinque May 10, 2024 05:35

steveluscher commented May 10, 2024

View reviewed changes

steveluscher force-pushed the 05-09-a_utility_to_estimate_the_compute_unit_consumption_of_a_transaction_message branch from 8ce397a to efb8b95 Compare May 10, 2024 05:40

steveluscher force-pushed the 05-09-update_web3.js_readme_for_new_transactionmessage_api branch from 20e490a to 4852d1d Compare May 10, 2024 05:50

steveluscher force-pushed the 05-09-a_utility_to_estimate_the_compute_unit_consumption_of_a_transaction_message branch from efb8b95 to 6a74b53 Compare May 10, 2024 05:50

mcintyre94 approved these changes May 10, 2024

View reviewed changes

steveluscher force-pushed the 05-09-update_web3.js_readme_for_new_transactionmessage_api branch from 4852d1d to 6552499 Compare May 10, 2024 15:15

Base automatically changed from 05-09-update_web3.js_readme_for_new_transactionmessage_api to master May 10, 2024 15:16

steveluscher force-pushed the 05-09-a_utility_to_estimate_the_compute_unit_consumption_of_a_transaction_message branch from 6a74b53 to ab0cf40 Compare May 10, 2024 17:27

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

2afc747

…essage

steveluscher force-pushed the 05-09-a_utility_to_estimate_the_compute_unit_consumption_of_a_transaction_message branch from ab0cf40 to 2afc747 Compare May 10, 2024 18:03

steveluscher merged commit 0908628 into master May 14, 2024
11 checks passed

steveluscher deleted the 05-09-a_utility_to_estimate_the_compute_unit_consumption_of_a_transaction_message branch May 14, 2024 17:11

github-actions bot mentioned this pull request May 14, 2024

Version Packages (preview) #2574

Open

joncinque reviewed May 16, 2024

View reviewed changes

github-actions bot mentioned this pull request May 22, 2024

Version Packages (preview) ronnyhaase/solana-web3.js#1

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

A utility to estimate the compute unit consumption of a transaction message #2703

A utility to estimate the compute unit consumption of a transaction message #2703

steveluscher commented May 10, 2024

changeset-bot bot commented May 10, 2024 •

edited

steveluscher commented May 10, 2024 •

edited

socket-security bot commented May 10, 2024 •

edited

steveluscher May 10, 2024

mcintyre94 May 10, 2024

steveluscher May 10, 2024

joncinque May 16, 2024

steveluscher May 10, 2024

steveluscher May 10, 2024

steveluscher May 10, 2024

mcintyre94 May 10, 2024

steveluscher May 10, 2024 •

edited

steveluscher May 10, 2024

mcintyre94 May 10, 2024

steveluscher May 10, 2024

mcintyre94 May 10, 2024

steveluscher May 10, 2024

socket-security bot commented May 10, 2024 •

edited

joncinque left a comment

joncinque May 16, 2024

joncinque May 16, 2024

steveluscher May 17, 2024

joncinque May 17, 2024

A utility to estimate the compute unit consumption of a transaction message #2703

A utility to estimate the compute unit consumption of a transaction message #2703

Conversation

steveluscher commented May 10, 2024

Summary

Example

Notes

Test Plan

changeset-bot bot commented May 10, 2024 • edited

🦋 Changeset detected

steveluscher commented May 10, 2024 • edited

socket-security bot commented May 10, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

steveluscher May 10, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

socket-security bot commented May 10, 2024 • edited

joncinque left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

changeset-bot bot commented May 10, 2024 •

edited

steveluscher commented May 10, 2024 •

edited

socket-security bot commented May 10, 2024 •

edited

steveluscher May 10, 2024 •

edited

socket-security bot commented May 10, 2024 •

edited