feat: more production ready gateway batcher design by 0xOsiris · Pull Request #227 · worldcoin/world-id-protocol

0xOsiris · 2026-01-19T20:02:20Z

This PR is stacked on #210, and addresses #183

Merges the create handle, and ops batcher into a single batcher which prioritizes account creations. This is important in times when throughput (potentially) exceeds chain capacity.
Makes the batcher aware of world chains gas when determining batch sizes. Also updates batch sizing to be calculated in terms of gas per individual operation instead of just a general max operations.
Automatically retries failed batches at transaction submission until all ops are determined to be invalid, or valid operations are finally submitted.
- A failed batch (should) never cause a valid operation to fail with an invalid status. Right now I've only addressed for Ops not account creations.
Minor refactor, and cleaner abstractions over request validation and request id generation

cursor · 2026-01-19T20:02:24Z

You have run out of free Bugbot PR reviews for this billing cycle. This will reset on February 15.

To receive reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.

Copilot

Pull request overview

This pull request significantly refactors the World ID Gateway's batching architecture to make it more production-ready. The changes introduce an event-driven system with a global EventMultiplexer, adaptive gas-based batch sizing, operation retry logic, and improved monitoring capabilities.

Changes:

Introduces EventMultiplexer pattern for decoupled event handling with metrics, logging, and status tracking
Implements adaptive batch sizing based on chain conditions (gas policy and chain monitor)
Adds retry logic for operations that fail due to transient RPC errors
Refactors configuration to use a shared common crate for provider management
Adds comprehensive load testing infrastructure

Reviewed changes

Copilot reviewed 37 out of 38 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
services/gateway/src/batcher/	New unified batching system with gas policy, chain monitoring, and event-driven architecture
services/gateway/src/routes/middleware.rs	New validation and simulation middleware for operation routes
services/gateway/src/types.rs	Refactored app state to use EventMultiplexer and registry instance
services/gateway/src/routes.rs	Updated to build event bus and ops batcher with new architecture
services/common/	New shared crate for provider configuration and management
services/gateway/tests/load_test.rs	Comprehensive load testing suite
services/gateway/Cargo.toml	Added dependencies for metrics, OTLP, and event handling

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

services/gateway/src/routes/create_account.rs

services/gateway/src/types.rs

services/gateway/src/routes/middleware.rs

services/gateway/src/routes.rs

services/gateway/src/routes/is_valid_root.rs

Copilot · 2026-01-19T22:48:20Z

@0xOsiris I've opened a new pull request, #228, to work on those changes. Once the pull request is ready, I'll request review from you.

services/gateway/src/types.rs

aurel-fr · 2026-01-23T06:53:03Z

services/gateway/src/batcher/mod.rs

+    let mc = Multicall3::new(MULTICALL3, provider.clone());
+
+    loop {
+        // 1. Simulate with allowFailure=true to identify failing ops


does this add value? how often do we expect failing ops?

It adds value in that now a failing op can never nullify an entire batch which was the case previously. I don't have enough context to know how often we do or do not expect this, but generally this seems like the better design.

If we never encounter this, then it will have no affect on batching times, and if we do encounter failed ops frequently it will never affect failure rates.

aurel-fr · 2026-01-23T06:56:01Z

services/gateway/src/batcher/gas_policy.rs

+            block_gas_limit: 100_000_000,
+            max_base_fee: 400_000_000_000, // 4 gwei
+            target_base_fee: 1,
+            backlog_threshold: 2_000,


Perhaps lacking context, I would make these dynamic, retrievable from a chainconfig in aws appconfig

100% these defaults all need to be carefully considered.

alessandromazza98

left some comments. It's a bit complicated to understand everything deeply but I see the overall logic.

A bigger question that I have is: why not using tx-sitter for all these operations (at least the ones related to send a tx onchain) instead of re-creating a similar service? This way we could simplify a lot this code and lets tx-sitter (that we already have and maintain) take care of tx handling.

alessandromazza98 · 2026-01-23T09:29:19Z

services/gateway/src/batcher/mod.rs

+}
+
+// Re-export for backwards compatibility
+pub type BatcherHandle = Commands;


why not directly call it BatcherHandle instead of immediately creating a helper type?

services/gateway/src/batcher/mod.rs

alessandromazza98 · 2026-01-23T09:42:31Z

services/gateway/src/batcher/gas_policy.rs

+/// Trait for gas policy implementations.
+///
+/// Allows different gas strategies to be plugged into the batcher.
+pub trait GasPolicyTrait: Send + Sync + 'static {


is this trait needed? You're implementing it only for GasPolicy, you could probably remove it and directly use the concrete type

I think batch sizing is actually very nuanced. e.g. The policy determining batch sizes may need to change. This just makes changing the policy require minimal code changes.

Fine either way though

alessandromazza98 · 2026-01-23T09:44:41Z

services/gateway/src/batcher/gas_policy.rs

+
+        // Fee pressure is amplified by positive trend (fees rising)
+        // and dampened by negative trend (fees falling)
+        let trend_factor = 1.0 + 0.5 * chain.base_fee_trend;


what's the formula / reason behind this opearation?

I should maybe write some better comments explaining the rationale here. But the constraint space we are working in is basically relieve back pressure as fast as possible while not making the base fee go exponential. There's two things we need to consider fee pressure (how expensive gas is) and queue pressure (how much pending work is backed up).

When gas is cheap and the queue is large, we target 90% block utilization. When gas is expensive, and the queue is short we target a 10% utilization. The trend of the base fee is taken into consideration as well. If the trend is an upward pressure on the base fee our target utilization should scale down accordingly.

Formulas:

fee_pressure = (base_fee - target_base_fee) / (max_base_fee - target_base_fee) [clamped 0-1] queue_pressure = queue_depth / backlog_threshold [clamped 0-1] trend_factor = 1.0 + (0.5 × base_fee_trend) adjusted_fee_pressure = fee_pressure × trend_factor [clamped 0-1] net_pressure = adjusted_fee_pressure - queue_pressure [range -1 to 1] target_utilization = 0.5 - (0.4 × net_pressure) [clamped 0.1-0.9] gas_budget = block_gas_limit × target_utilization

services/gateway/src/batcher/gas_policy.rs

alessandromazza98 · 2026-01-23T09:53:04Z

services/gateway/src/batcher/mod.rs

+    }
+}
+
+/// Submit createManyAccounts with retry.


I don't see the retry here

0xOsiris · 2026-01-23T20:55:11Z

left some comments. It's a bit complicated to understand everything deeply but I see the overall logic.

A bigger question that I have is: why not using tx-sitter for all these operations (at least the ones related to send a tx onchain) instead of re-creating a similar service? This way we could simplify a lot this code and lets tx-sitter (that we already have and maintain) take care of tx handling.

I think this is a valid take. I was simply increasing the robustness of the current implementation, but outsourcing transaction mining seems like a valid strategy. Generally my concern is that we are going to make the base fee go exponential without intelligent batch sizing, which this PR attempts to fix. Transaction mining however can be outsourced to tx-sitter you are correct. I would consider this out of scope for this PR though

0xOsiris added 9 commits January 15, 2026 15:39

wip: robust provider

abc994e

feat: global provider with concurrency safe provider

9a5ee42

fix: merge conflicts

80ad671

fix: merge conflicts

c39f317

try fix

6701536

merge main + cleanup

66b4c92

wip: fix tests

5855f59

wip: cleanup

a3faee3

fix: make backwards compatible

f7dd58e

0xOsiris changed the title ~~Osiris/gateway batcher~~ feat: more production ready gateway batcher design Jan 19, 2026

0xOsiris marked this pull request as draft January 19, 2026 21:12

0xOsiris requested review from alessandromazza98, Copilot and paolodamico January 19, 2026 21:57

Copilot started reviewing on behalf of 0xOsiris January 19, 2026 21:57 View session

Copilot AI reviewed Jan 19, 2026

View reviewed changes

Copilot AI mentioned this pull request Jan 19, 2026

[WIP] WIP Address feedback on gateway batcher design for production readiness #228

Merged

8 tasks

0xOsiris commented Jan 19, 2026

View reviewed changes

services/gateway/src/types.rs Show resolved Hide resolved

0xOsiris added 5 commits January 21, 2026 07:14

wip: seems to be working

8ea514b

chore: cleanup

35d30ba

chore: more cleanup

0c33e46

chore: cleanup

bbc706d

chore: rollback some changes

fd667f6

0xOsiris force-pushed the osiris/gateway-batcher branch from d5e3d23 to fd667f6 Compare January 21, 2026 16:19

0xOsiris added 3 commits January 21, 2026 08:24

chore: clippy

a644959

chore: merge main

2cd3888

chore: fmt

1c0a47d

0xOsiris marked this pull request as ready for review January 22, 2026 23:48

aurel-fr reviewed Jan 23, 2026

View reviewed changes

alessandromazza98 reviewed Jan 23, 2026

View reviewed changes

0xOsiris added 6 commits January 23, 2026 15:16

chore: merge main

42ee85e

chore: remove dead code

29a9449

chore: move ChainState into chain.rs

0343708

chore: more appropriate defaults

1d5cd80

test: add test for gas policy

35dd681

fix: gas policy defaults

c604ce8

0xOsiris mentioned this pull request Jan 24, 2026

feat: better request validation #263

Merged

Conversation

0xOsiris commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cursor bot commented Jan 19, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI commented Jan 19, 2026

Uh oh!

Uh oh!

aurel-fr Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

0xOsiris Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

aurel-fr Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

0xOsiris Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

alessandromazza98 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alessandromazza98 Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

alessandromazza98 Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

0xOsiris Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alessandromazza98 Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

0xOsiris Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

alessandromazza98 Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

0xOsiris commented Jan 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

0xOsiris commented Jan 19, 2026 •

edited

Loading

aurel-fr Jan 23, 2026 •

edited

Loading

aurel-fr Jan 23, 2026 •

edited

Loading

alessandromazza98 left a comment •

edited

Loading

0xOsiris Jan 23, 2026 •

edited

Loading