Skip to content

Add helpers and a generic rejection error for custom message packers - #2073

Merged
lorisleiva merged 1 commit into
mainfrom
09-18-add_helpers_and_a_generic_rejection_error_for_custom_message_packers
Sep 22, 2026
Merged

lorisleiva merged 1 commit into
mainfrom
09-18-add_helpers_and_a_generic_rejection_error_for_custom_message_packers

Conversation

@lorisleiva

Copy link
Copy Markdown
Member

This PR makes it practical to write a custom MessagePacker without reimplementing the built-in packers' internals. Today a packer that wants to refuse a candidate message for a reason other than byte size (for example a per-transaction realloc budget) has to throw MESSAGE_CANNOT_ACCOMMODATE_PLAN with fabricated byte counts, and has to copy the instruction-count validation and the size arithmetic by hand.

Three helpers are now exported from @solana/instruction-plans: resolveMaxInstructionsPerTransaction validates and defaults the maxInstructions option, assertMaxInstructionsPerTransaction throws MAX_INSTRUCTIONS_PER_TRANSACTION_EXCEEDED when a message would hold too many instructions, and assertMessageCanAccommodateSize throws MESSAGE_CANNOT_ACCOMMODATE_PLAN with correctly computed byte counts from sizes the caller already has. The two built-in packers use them.

A new SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_REJECTED_BY_PACKER error with a free-text reason lets a packer refuse a message for any other constraint. The planner treats it like the existing capacity errors, so rejecting a candidate opens a new transaction message while rejecting a fresh message still propagates. The set of errors that mean "use a new candidate" is now exposed as isMessagePackerErrorThatRequiresNewCandidate, which the planner uses in place of its inline six-code chain.

packMessageToCapacity: (message, config) => {
    const maxInstructions = resolveMaxInstructionsPerTransaction(config?.maxInstructions);
    assertMaxInstructionsPerTransaction(message.instructions.length + 1, maxInstructions);
    if (budgetLeft(message) <= 0) {
        throw new SolanaError(SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_REJECTED_BY_PACKER, {
            reason: 'the account cannot grow any further in this transaction',
        });
    }
    const nextMessage = appendTransactionMessageInstruction(nextInstruction, message);
    assertMessageCanAccommodateSize({
        currentSize: getTransactionMessageSize(message),
        nextSize: getTransactionMessageSize(nextMessage),
        sizeLimit: getTransactionMessageSizeLimit(nextMessage),
    });
    return nextMessage;
};

@changeset-bot

changeset-bot Bot commented Sep 18, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: aa1cfe5

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

This PR includes changesets to release 48 packages
Name Type
@solana/errors Minor
@solana/instruction-plans Minor
@solana/accounts Minor
@solana/addresses Minor
@solana/assertions Minor
@solana/codecs-core Minor
@solana/codecs-data-structures Minor
@solana/codecs-numbers Minor
@solana/codecs-strings Minor
@solana/compat Minor
@solana/fixed-points Minor
@solana/instructions Minor
@solana/keys Minor
@solana/kit Minor
@solana/offchain-messages Minor
@solana/options Minor
@solana/program-client-core Minor
@solana/programs Minor
@solana/rpc-api Minor
@solana/rpc-spec-types Minor
@solana/rpc-spec Minor
@solana/rpc-subscriptions-channel-websocket Minor
@solana/rpc-subscriptions-spec Minor
@solana/rpc-subscriptions Minor
@solana/rpc-transformers Minor
@solana/rpc-transport-http Minor
@solana/rpc-types Minor
@solana/rpc Minor
@solana/signers Minor
@solana/subscribable Minor
@solana/sysvars Minor
@solana/transaction-confirmation Minor
@solana/transaction-introspection Minor
@solana/transaction-messages Minor
@solana/transactions Minor
@solana/wallet-account-signer Minor
@solana/plugin-interfaces Minor
@solana/rpc-graphql Minor
@solana/rpc-parsed-types Minor
@solana/rpc-subscriptions-api Minor
@solana/codecs Minor
@solana/react Minor
@solana/fast-stable-stringify Minor
@solana/functional Minor
@solana/nominal-types Minor
@solana/plugin-core Minor
@solana/promises Minor
@solana/webcrypto-ed25519-polyfill Minor

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

Copy link
Copy Markdown
Member Author

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

@lorisleiva

Copy link
Copy Markdown
Member Author

@trevor-cortex

@bundlemon

bundlemon Bot commented Sep 18, 2026 •

Copy link
Copy Markdown

BundleMon

Files updated (10)
Status Path Size Limits
✅ @solana/kit production bundle
kit/dist/index.production.min.js
57.57KB (+121B +0.21%) -
✅ instruction-plans/dist/index.browser.mjs
7.37KB (+69B +0.92%) -
✅ instruction-plans/dist/index.native.mjs
7.37KB (+69B +0.92%) -
✅ instruction-plans/dist/index.node.mjs
7.37KB (+69B +0.92%) -
✅ errors/dist/index.native.mjs
22.19KB (+55B +0.24%) -
✅ errors/dist/index.browser.mjs
22.19KB (+54B +0.24%) -
✅ errors/dist/index.node.mjs
22.22KB (+54B +0.24%) -
✅ wallet-account-signer/dist/index.node.mjs
18.85KB (+43B +0.22%) -
✅ wallet-account-signer/dist/index.browser.mjs
18.83KB (+42B +0.22%) -
✅ wallet-account-signer/dist/index.native.mjs
18.84KB (+42B +0.22%) -
Unchanged files (140)
Status Path Size Limits
✅ rpc-graphql/dist/index.browser.mjs
18.87KB -
✅ rpc-graphql/dist/index.native.mjs
18.87KB -
✅ rpc-graphql/dist/index.node.mjs
18.86KB -
✅ transaction-messages/dist/index.browser.mjs
11.84KB -
✅ transaction-messages/dist/index.native.mjs
11.83KB -
✅ transaction-messages/dist/index.node.mjs
11.83KB -
✅ react/dist/index.browser.mjs
5.32KB -
✅ react/dist/index.native.mjs
5.32KB -
✅ react/dist/index.node.mjs
5.32KB -
✅ codecs-data-structures/dist/index.browser.mjs
5.31KB -
✅ codecs-data-structures/dist/index.native.mjs
5.31KB -
✅ codecs-data-structures/dist/index.node.mjs
5.31KB -
✅ offchain-messages/dist/index.browser.mjs
5.25KB -
✅ offchain-messages/dist/index.native.mjs
5.24KB -
✅ offchain-messages/dist/index.node.mjs
5.24KB -
✅ fixed-points/dist/index.browser.mjs
5.08KB -
✅ fixed-points/dist/index.native.mjs
5.07KB -
✅ fixed-points/dist/index.node.mjs
5.07KB -
✅ kit/dist/index.browser.mjs
4.69KB -
✅ kit/dist/index.native.mjs
4.69KB -
✅ kit/dist/index.node.mjs
4.69KB -
✅ transactions/dist/index.browser.mjs
4.05KB -
✅ transactions/dist/index.native.mjs
4.05KB -
✅ transactions/dist/index.node.mjs
4.05KB -
✅ codecs-core/dist/index.browser.mjs
3.81KB -
✅ codecs-core/dist/index.native.mjs
3.81KB -
✅ codecs-core/dist/index.node.mjs
3.81KB -
✅ webcrypto-ed25519-polyfill/dist/index.node.mj
s
3.61KB -
✅ webcrypto-ed25519-polyfill/dist/index.browser
.mjs
3.59KB -
✅ webcrypto-ed25519-polyfill/dist/index.native.
mjs
3.57KB -
✅ signers/dist/index.browser.mjs
3.5KB -
✅ signers/dist/index.native.mjs
3.5KB -
✅ signers/dist/index.node.mjs
3.5KB -
✅ rpc-subscriptions/dist/index.browser.mjs
3.37KB -
✅ rpc-subscriptions/dist/index.node.mjs
3.34KB -
✅ rpc-subscriptions/dist/index.native.mjs
3.31KB -
✅ codecs-strings/dist/index.browser.mjs
3.29KB -
✅ codecs-strings/dist/index.node.mjs
3.17KB -
✅ codecs-strings/dist/index.native.mjs
3.13KB -
✅ subscribable/dist/index.node.mjs
3.13KB -
✅ rpc-transformers/dist/index.browser.mjs
3.1KB -
✅ rpc-transformers/dist/index.native.mjs
3.1KB -
✅ rpc-transformers/dist/index.node.mjs
3.1KB -
✅ keys/dist/index.node.mjs
3.06KB -
✅ subscribable/dist/index.native.mjs
3.06KB -
✅ subscribable/dist/index.browser.mjs
3.05KB -
✅ addresses/dist/index.browser.mjs
2.93KB -
✅ addresses/dist/index.native.mjs
2.92KB -
✅ addresses/dist/index.node.mjs
2.92KB -
✅ keys/dist/index.browser.mjs
2.85KB -
✅ keys/dist/index.native.mjs
2.85KB -
✅ transaction-introspection/dist/index.browser.
mjs
2.73KB -
✅ transaction-introspection/dist/index.native.m
js
2.73KB -
✅ transaction-introspection/dist/index.node.mjs
2.73KB -
✅ transaction-confirmation/dist/index.node.mjs
2.42KB -
✅ transaction-confirmation/dist/index.native.mj
s
2.37KB -
✅ sysvars/dist/index.browser.mjs
2.37KB -
✅ sysvars/dist/index.native.mjs
2.37KB -
✅ sysvars/dist/index.node.mjs
2.37KB -
✅ transaction-confirmation/dist/index.browser.m
js
2.36KB -
✅ rpc-subscriptions-spec/dist/index.node.mjs
2.33KB -
✅ rpc-subscriptions-spec/dist/index.native.mjs
2.29KB -
✅ rpc-subscriptions-spec/dist/index.browser.mjs
2.29KB -
✅ codecs-numbers/dist/index.browser.mjs
2.18KB -
✅ codecs-numbers/dist/index.native.mjs
2.18KB -
✅ codecs-numbers/dist/index.node.mjs
2.18KB -
✅ rpc/dist/index.node.mjs
1.94KB -
✅ rpc-transport-http/dist/index.browser.mjs
1.9KB -
✅ rpc-types/dist/index.browser.mjs
1.9KB -
✅ rpc-types/dist/index.native.mjs
1.9KB -
✅ rpc-types/dist/index.node.mjs
1.9KB -
✅ rpc-transport-http/dist/index.native.mjs
1.9KB -
✅ rpc/dist/index.native.mjs
1.8KB -
✅ rpc/dist/index.browser.mjs
1.79KB -
✅ rpc-transport-http/dist/index.node.mjs
1.71KB -
✅ rpc-spec-types/dist/index.browser.mjs
1.54KB -
✅ rpc-spec-types/dist/index.native.mjs
1.54KB -
✅ rpc-spec-types/dist/index.node.mjs
1.54KB -
✅ program-client-core/dist/index.browser.mjs
1.39KB -
✅ program-client-core/dist/index.native.mjs
1.39KB -
✅ program-client-core/dist/index.node.mjs
1.39KB -
✅ rpc-subscriptions-channel-websocket/dist/inde
x.node.mjs
1.33KB -
✅ rpc-subscriptions-channel-websocket/dist/inde
x.native.mjs
1.27KB -
✅ rpc-subscriptions-channel-websocket/dist/inde
x.browser.mjs
1.26KB -
✅ plugin-core/dist/index.browser.mjs
1.18KB -
✅ plugin-core/dist/index.native.mjs
1.18KB -
✅ plugin-core/dist/index.node.mjs
1.18KB -
✅ options/dist/index.browser.mjs
1.18KB -
✅ options/dist/index.native.mjs
1.18KB -
✅ options/dist/index.node.mjs
1.17KB -
✅ accounts/dist/index.browser.mjs
1.17KB -
✅ accounts/dist/index.native.mjs
1.17KB -
✅ accounts/dist/index.node.mjs
1.16KB -
✅ rpc-api/dist/index.browser.mjs
1.08KB -
✅ rpc-api/dist/index.native.mjs
1.08KB -
✅ rpc-api/dist/index.node.mjs
1.08KB -
✅ compat/dist/index.browser.mjs
969B -
✅ compat/dist/index.native.mjs
968B -
✅ compat/dist/index.node.mjs
966B -
✅ rpc-spec/dist/index.browser.mjs
928B -
✅ rpc-spec/dist/index.native.mjs
928B -
✅ rpc-spec/dist/index.node.mjs
926B -
✅ promises/dist/index.native.mjs
841B -
✅ promises/dist/index.node.mjs
840B -
✅ promises/dist/index.browser.mjs
839B -
✅ rpc-subscriptions-api/dist/index.browser.mjs
810B -
✅ rpc-subscriptions-api/dist/index.native.mjs
808B -
✅ rpc-subscriptions-api/dist/index.node.mjs
807B -
✅ assertions/dist/index.browser.mjs
783B -
✅ instructions/dist/index.browser.mjs
771B -
✅ instructions/dist/index.native.mjs
770B -
✅ instructions/dist/index.node.mjs
768B -
✅ fast-stable-stringify/dist/index.browser.mjs
726B -
✅ fast-stable-stringify/dist/index.native.mjs
725B -
✅ assertions/dist/index.native.mjs
724B -
✅ fast-stable-stringify/dist/index.node.mjs
724B -
✅ assertions/dist/index.node.mjs
723B -
✅ programs/dist/index.browser.mjs
329B -
✅ programs/dist/index.native.mjs
327B -
✅ programs/dist/index.node.mjs
325B -
✅ fs-impl/dist/index.browser.mjs
245B -
✅ event-target-impl/dist/index.node.mjs
230B -
✅ functional/dist/index.browser.mjs
154B -
✅ functional/dist/index.native.mjs
152B -
✅ text-encoding-impl/dist/index.native.mjs
152B -
✅ functional/dist/index.node.mjs
151B -
✅ codecs/dist/index.browser.mjs
145B -
✅ codecs/dist/index.native.mjs
144B -
✅ codecs/dist/index.node.mjs
142B -
✅ event-target-impl/dist/index.browser.mjs
133B -
✅ ws-impl/dist/index.node.mjs
131B -
✅ text-encoding-impl/dist/index.browser.mjs
122B -
✅ fs-impl/dist/index.node.mjs
120B -
✅ text-encoding-impl/dist/index.node.mjs
119B -
✅ ws-impl/dist/index.browser.mjs
113B -
✅ crypto-impl/dist/index.node.mjs
111B -
✅ crypto-impl/dist/index.browser.mjs
109B -
✅ rpc-parsed-types/dist/index.browser.mjs
66B -
✅ rpc-parsed-types/dist/index.native.mjs
65B -
✅ rpc-parsed-types/dist/index.node.mjs
63B -

Total files change +618B +0.11%

Final result: ✅

View report in BundleMon website ➡️


Current branch size history | Target branch size history

@trevor-cortex trevor-cortex left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: LGTM — approving in spirit (this account can't formally approve on the repo). Nits below are all non-blocking.

Summary

Extracts the instruction-count / size validation that the built-in packers relied on into a public message-packer-errors.ts module (resolveMaxInstructionsPerTransaction, assertMaxInstructionsPerTransaction, assertMessageCanAccommodateSize), adds a new SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_REJECTED_BY_PACKER error with a free-text reason, and replaces the planner's inline six-code isSolanaError chain with an exported isMessagePackerErrorThatRequiresNewCandidate guard that also covers the new code. max-instructions.ts is folded into the new module.

I traced the refactors and they're behaviour-preserving:

  • resolveMaxInstructionsPerTransaction = old assertValid… + resolveMaxInstructions fused. The planner now resolves once up front and TraverseContext.maxInstructionsPerTransaction becomes a plain number, which removes the repeated resolveMaxInstructions(...) calls at every assertion site. Same semantics, less noise.
  • In getMessagePackerInstructionPlanFromInstructions, the restructured if (index === instructionIndex) assert… else if (nextSize > sizeLimit) … is equivalent to the old nested check, and numBytesRequired / numFreeBytes compute to the same values (nextSize - originalMessageSize, sizeLimit - originalMessageSize).
  • max-instructions.ts was never re-exported from index.ts, so dropping DEFAULT_MAX_INSTRUCTIONS_PER_TRANSACTION's export isn't a public break.
  • Rejection semantics in the planner check out: selectAndMutateCandidate swallows MESSAGE_REJECTED_BY_PACKER and moves on (covering both the traverseMessagePacker predicate and the fitEntirePlanInsideMessage path for non-divisible / parallel-nested packers), while createNewMessage doesn't catch, so a fresh-message rejection propagates. Both planner tests exercise exactly those two outcomes.

Nits (non-blocking)

  • MessagePackerInstructionPlan docblock example is now inconsistent. The MessagePacker type's example was updated to add the if (!isMessagePackerErrorThatRequiresNewCandidate(error)) throw error; guard, but the near-identical "Using a message packer plan" example in the MessagePackerInstructionPlan docblock (instruction-plan.ts ~L205–215, unchanged) still has a bare catch with just comments. Worth mirroring the guard there too so the two examples don't teach different things.
  • Consider exporting MessagePackerErrorThatRequiresNewCandidate. See inline.
  • Error message wording. See inline on messages.ts.
  • Test gap (optional): the planner tests cover traverseMessagePacker, but not the fitEntirePlanInsideMessage route where a rejection is swallowed and the plan falls back to normal traversal. Something like sequentialInstructionPlan([A, nonDivisibleSequentialInstructionPlan([rejectingPacker([B])])]) → expect sequential([Tx: A], [Tx: B]) would pin that down, since it's the path most likely to regress if someone later narrows the catch in selectAndMutateCandidate.

Notes for subsequent reviewers

  • No README change needed here — the package README just links to solanakit.com docs, and per CLAUDE.md docs can't reference unpublished types, so the docs follow-up has to land post-release.
  • The changeset bumps @solana/errors and @solana/instruction-plans as minor, which matches new-feature precedent.
  • The linear packer only adopted the max-instructions helpers, not assertMessageCanAccommodateSize — that's correct, its size math has the +1/-1 shortU16 leeway adjustments that don't map onto the generic helper.

Comment thread packages/errors/src/messages.ts Resolved
This PR makes it practical to write a custom `MessagePacker` without reimplementing the built-in packers' internals. Today a packer that wants to refuse a candidate message for a reason other than byte size (for example a per-transaction realloc budget) has to throw `MESSAGE_CANNOT_ACCOMMODATE_PLAN` with fabricated byte counts, and has to copy the instruction-count validation and the size arithmetic by hand.

Three helpers are now exported from `@solana/instruction-plans`: `resolveMaxInstructionsPerTransaction` validates and defaults the `maxInstructions` option, `assertMaxInstructionsPerTransaction` throws `MAX_INSTRUCTIONS_PER_TRANSACTION_EXCEEDED` when a message would hold too many instructions, and `assertMessageCanAccommodateSize` throws `MESSAGE_CANNOT_ACCOMMODATE_PLAN` with correctly computed byte counts from sizes the caller already has. The two built-in packers use them.

A new `SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_REJECTED_BY_PACKER` error with a free-text `reason` lets a packer refuse a message for any other constraint. The planner treats it like the existing capacity errors, so rejecting a candidate opens a new transaction message while rejecting a fresh message still propagates. The set of errors that mean "use a new candidate" is now exposed as `isMessagePackerErrorThatRequiresNewCandidate`, which the planner uses in place of its inline six-code chain.

```ts
packMessageToCapacity: (message, config) => {
    const maxInstructions = resolveMaxInstructionsPerTransaction(config?.maxInstructions);
    assertMaxInstructionsPerTransaction(message.instructions.length + 1, maxInstructions);
    if (budgetLeft(message) <= 0) {
        throw new SolanaError(SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_REJECTED_BY_PACKER, {
            reason: 'the account cannot grow any further in this transaction',
        });
    }
    const nextMessage = appendTransactionMessageInstruction(nextInstruction, message);
    assertMessageCanAccommodateSize({
        currentSize: getTransactionMessageSize(message),
        nextSize: getTransactionMessageSize(nextMessage),
        sizeLimit: getTransactionMessageSizeLimit(nextMessage),
    });
    return nextMessage;
};
```
@lorisleiva
lorisleiva force-pushed the 09-18-add_helpers_and_a_generic_rejection_error_for_custom_message_packers branch from c3defa8 to aa1cfe5 Compare September 18, 2026 13:37

@trevor-cortex trevor-cortex left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-review: LGTM, nothing further — approving in spirit (this account can't formally approve on the repo).

All four points from the previous pass are addressed in the current head:

  • Error message trimmed to 'The message packer rejected the provided transaction message: $reason.' — no more misleading "pack into a new message" advice at the point where a fresh message was already rejected.
  • MessagePackerErrorThatRequiresNewCandidate is now exported with a docblock that enumerates each code in the union and what it means. The guard's return type narrows to it.
  • MessagePackerInstructionPlan docblock example now carries the same if (!isMessagePackerErrorThatRequiresNewCandidate(error)) throw error; guard as the MessagePacker one, and the MessagePacker type docblock gained a paragraph pointing custom packers at the three helpers and the new error.
  • fitEntirePlanInsideMessage path is now covered by the new "falls back to a new transaction message when a message packer rejects the parent candidate of a non-divisible plan" test (sequential([A, nonDivSeq([rejectingPacker([B])])]) → sequential([Tx: A], [Tx: B])). That pins down the selectAndMutateCandidate catch for the nested route, which was the one most likely to regress silently.

Re-checked the rest of the diff (transaction-planner.ts, __setup__.ts, codes.ts, context.ts, changeset) — unchanged from the prior pass, no regressions. Planner tests now cover all three outcomes: reject-candidate-via-traverseMessagePacker, reject-candidate-via-fitEntirePlanInsideMessage, and reject-fresh-message propagates.

Good to merge from my side.

@lorisleiva
lorisleiva marked this pull request as ready for review September 18, 2026 13:44

@mcintyre94 mcintyre94 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! I found these helpers a little odd because they're just comparing two numbers and throwing an error, but I think they make it much more straightforward to write a packer and it wouldn't make sense to pass any other input (like the transaction message or something). So I think this makes sense!

@lorisleiva
lorisleiva added this pull request to the merge queue Sep 22, 2026
Merged via the queue into main with commit 5be269c Sep 22, 2026
16 checks passed
@lorisleiva
lorisleiva deleted the 09-18-add_helpers_and_a_generic_rejection_error_for_custom_message_packers branch September 22, 2026 15:13
@github-actions

Copy link
Copy Markdown
Contributor

🔎💬 Inkeep AI search and chat service is syncing content for source 'Solana Kit Docs'

This was referenced Sep 22, 2026
@github-actions

github-actions Bot commented Oct 7, 2026

Copy link
Copy Markdown
Contributor

Because there has been no activity on this PR for 14 days since it was merged, it has been automatically locked. Please open a new issue if it requires a follow up.

@github-actions github-actions Bot locked as resolved and limited conversation to collaborators Oct 7, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants