fix: correct bundler JSON-RPC error mapping and getUserOperationByHash types by sherifahmed990 · Pull Request #219 · candidelabs/abstractionkit

sherifahmed990 · 2026-07-22T11:12:08Z

Three fixes to how Bundler translates JSON-RPC responses.

-32601 no longer misreported as INVALID_USEROPERATION_HASH: nothing assigns it that meaning — ERC-7769 defines no error code for invalid hashes, and Voltaire returns -32602 for a missing/invalid userOpHash. The mapping was shadowing the standard method-not-found error and misdirecting debugging toward hash issues. -32601 now always translates to METHOD_NOT_FOUND; INVALID_USEROPERATION_HASH stays in the BundlerErrorCode union for compatibility but is deprecated and never produced.
-32508 and -32603 mapped: -32508 (paymaster deposit/balance insufficient, actively raised by Voltaire's mempool manager) now maps to PAYMASTER_DEPOSIT_TOO_LOW, and bundler-side -32603 falls through to the standard INTERNAL_ERROR instead of UNKNOWN_ERROR.
getUserOperationByHash returned hex strings in bigint fields: only blockNumber was converted; nonce, gas limits, and fees kept wire-format hex strings despite the declared type, so nonce === 0n was silently always false and bigint arithmetic threw. Numeric fields are now converted, matching getUserOperationReceipt and estimateUserOperationGas.

Tests added in test/transport/Bundler.error-mapping.test.js and test/transport/Bundler.getUserOperationByHash.test.js; full offline suite passes.

Summary by CodeRabbit

Improvements
- User operation results now normalize numeric fields into a consistent BigInt representation, including for pending operations.
- Added support for additional UserOperation shapes in the getUserOperationByHash result.
Bug Fixes
- Corrected Bundler JSON-RPC error classification (method not found, internal errors, invalid fields).
- Added/updated paymaster deposit error mapping to more accurately reflect insufficient deposits.
Tests
- Expanded test coverage for user operation conversion, pending/unknown cases, and the updated error mappings.

Only blockNumber was converted; the returned userOperation kept the bundler's wire-format hex strings in fields the declared type promises as bigint (nonce, gas limits, fees), so comparisons like nonce === 0n were silently always false and bigint arithmetic threw. Convert the numeric fields like getUserOperationReceipt and estimateUserOperationGas already do. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

The BundlerErrorCodeDict translated -32601 to INVALID_USEROPERATION_HASH, but nothing assigns it that meaning: ERC-7769 defines no error code for invalid hashes on the lookup methods, and Voltaire returns -32602 (InvalidFields) with 'Missing/invalid userOpHash' — its only -32601 is the standard JSON-RPC method-not-found, which this mapping was shadowing and misdirecting debugging toward hash issues. -32601 now always translates to METHOD_NOT_FOUND; the INVALID_USEROPERATION_HASH code remains in the BundlerErrorCode union for compatibility but is marked deprecated and never produced. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…RROR BundlerErrorCodeDict covered ERC-7769 codes -32500..-32507 but omitted -32508 (paymaster balance insufficient for all mempool UserOperations), which Voltaire's mempool manager actively raises — it surfaced as inner UNKNOWN_ERROR. Bundler-side -32603 internal errors (raised by Voltaire's execution endpoint) likewise fell to UNKNOWN_ERROR because translateBundlerError only consulted the bundler dict; it now falls through to the standard INTERNAL_ERROR name, matching the -32601 METHOD_NOT_FOUND handling. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

coderabbitai · 2026-07-22T11:12:30Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: f807ddff-516f-4abd-b241-243a9c6e9f72

📥 Commits

Reviewing files that changed from the base of the PR and between 941ba26 and f6341f5.

📒 Files selected for processing (2)

src/Bundler.ts
src/types.ts

🚧 Files skipped from review as they are similar to previous changes (1)

src/Bundler.ts

📝 Walkthrough

Walkthrough

getUserOperationByHash now converts numeric wire-format fields to BigInt and supports V8/V9 result types. Bundler error translation distinguishes standard JSON-RPC errors and maps -32508 to PAYMASTER_DEPOSIT_TOO_LOW, with tests covering the updated behavior.

Changes

Bundler normalization

Layer / File(s)	Summary
User operation wire-format normalization `src/Bundler.ts`, `src/types.ts`, `test/transport/Bundler.getUserOperationByHash.test.js`	Numeric user operation fields are converted from wire-format values to `BigInt`; V8 and V9 result types are supported, while unknown hashes and pending metadata remain `null`.
Bundler error-code translation `src/Bundler.ts`, `src/errors.ts`, `test/transport/Bundler.error-mapping.test.js`	Standard errors `-32601` and `-32603` map to `METHOD_NOT_FOUND` and `INTERNAL_ERROR`; `-32508` maps to `PAYMASTER_DEPOSIT_TOO_LOW`, and `-32602` maps to `INVALID_FIELDS`.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

candidelabs/abstractionkit#193: Both modify Bundler error translation and error-code propagation.
candidelabs/abstractionkit#215: Both update user operation normalization and JSON-RPC error mappings.

Suggested reviewers: sednaoui

Poem

I’m a rabbit with bundles to mend,
Hex hops to BigInt at the end.
Errors find names, neat and clear,
Paymaster deposits now appear.
Tests thump softly—done, my dear!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main changes: Bundler error mapping fixes and getUserOperationByHash type updates.
Description check	✅ Passed	The description covers the summary and tests, and it addresses compatibility; the missing dedicated Risk / Compatibility heading is non-critical.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{Comment @coderabbitai help to get the list of available commands.}

Sednaoui · 2026-07-23T13:14:10Z

+			}
 			return {
 				...jsonRpcResult,
+				userOperation: userOperation as unknown as UserOperationV6 | UserOperationV7,


getUserOperationByHash() declares and casts its result as only V6/V7. See the types file as ell. should e include UserOperationV8 and UserOperationV9 in the result type?

The SDK submits EntryPoint v0.8/v0.9 operations, but the eth_getUserOperationByHash result typed userOperation as only V6 | V7, forcing an unsafe cast to reach fields like eip7702Auth. Widen the declared type and the internal cast to the full V6-V9 union, matching sendUserOperation and estimateUserOperationGas. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

sherifahmed990 and others added 3 commits July 22, 2026 12:39

Sednaoui requested changes Jul 23, 2026

View reviewed changes

sherifahmed990 and others added 2 commits July 25, 2026 19:16

Merge branch 'dev' into fix/bundler-error-mapping

e388fb6

sherifahmed990 requested a review from Sednaoui July 25, 2026 16:22

Sednaoui approved these changes Jul 26, 2026

View reviewed changes

Sednaoui merged commit eda085f into dev Jul 26, 2026
3 checks passed

Sednaoui deleted the fix/bundler-error-mapping branch July 26, 2026 11:35

coderabbitai Bot mentioned this pull request Jul 27, 2026

chore(release): 0.4.1 #227

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix: correct bundler JSON-RPC error mapping and getUserOperationByHash types - #219

fix: correct bundler JSON-RPC error mapping and getUserOperationByHash types#219
Sednaoui merged 5 commits into
devfrom
fix/bundler-error-mapping

sherifahmed990 commented Jul 22, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jul 22, 2026 •

edited

Loading

Walkthrough

Changes

Uh oh!

Sednaoui Jul 23, 2026

Uh oh!

sherifahmed990 Jul 25, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

sherifahmed990 commented Jul 22, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Uh oh!

Sednaoui Jul 23, 2026

Choose a reason for hiding this comment

Uh oh!

sherifahmed990 Jul 25, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

sherifahmed990 commented Jul 22, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jul 22, 2026 •

edited

Loading