fix(tokens): reduce balance correction RPC load

[tarrencev]

Summary

Reduces unnecessary ERC20/ERC1155 balance correction RPC calls in torii-tokens.

This PR has two parts:

• fixes the balance precheck to account for credits earlier in the same batch before deciding a sender balance is inconsistent
• adds a --disable-balance-tracking flag for high-volume/global token indexers that do not need ERC20/ERC1155 balance tables

Why

The token sinks currently fetch historical balanceOf values whenever a sender's locally computed balance would go negative. That is useful for genuinely missing history, but the precheck was only tracking pending debits inside the current batch. It did not apply credits from earlier transfers in the same batch before evaluating later debits.

For large block-range batches, this can create false positives. Example:

1. wallet receives 100 tokens in the batch
2. wallet sends 75 tokens later in the same batch
3. pre-batch stored balance is 0
4. old precheck sees the send as underfunded and schedules a historical balanceOf, even though the batch itself funds the send

On global token indexers this can become a very large number of unnecessary balance correction calls.

Behavior

Balance tracking enabled, default behavior:

• ERC20/ERC1155 balance prechecks now walk transfers in batch order and maintain running balances
• earlier in-batch credits can fund later in-batch debits
• genuinely underfunded senders still schedule balance correction requests

When --disable-balance-tracking is set:

• ERC20/ERC1155 transfer indexing remains enabled
• metadata pipelines remain enabled
• ownership indexing remains enabled
• ERC20/ERC1155 balance tracking and on-chain balance correction calls are skipped

The disable flag means balance tables / balance query accuracy should not be relied on for that run mode.

Tests

• cargo fmt --manifest-path /tmp/torii-core/Cargo.toml
• cargo test -p torii-erc20 balance_adjustment_check
• cargo test -p torii-erc1155 balance_adjustment_check
• cargo test -p torii-tokens concurrency_flags_parse
• cargo check -p torii-tokens

[github-actions]

📊 Synthetic Benchmark Results

Comparing against baseline: 20260608T145153Z

Performance Summary

Token Type	Duration (ms)	Blocks	Transactions	Events	Envelopes	Blocks/sec	Events/sec
erc721	12387	100	50000	50000	50000	8.07	4036.29
erc1155	10739	100	50000	50000	70000	9.31	4655.79
erc20	2873	100	50000	50000	50000	34.80	17398.24

Comparison with Baseline

Token Type	Metric	Baseline	Current	Change
erc721	Throughput (events/sec)	4036.29	4036.29	➡️ 0.0%
erc721	Duration (ms)	12387	12387	➡️ 0.0%
erc1155	Throughput (events/sec)	4655.79	4655.79	➡️ 0.0%
erc1155	Duration (ms)	10739	10739	➡️ 0.0%
erc20	Throughput (events/sec)	17398.24	17398.24	➡️ 0.0%
erc20	Duration (ms)	2873	2873	➡️ 0.0%

Legend:

• ✅ Improvement (faster)
• ⚠️ Regression (slower)
• 📈 Throughput increase
• 📉 Throughput decrease
• ➡️ No significant change (<5%)

Stage Latency Breakdown

Token Type	Extract (ms)	Decode (ms)	Sink (ms)	Commit (ms)
erc721	14.137903000000003	58.782621999999996	12234.203690999997	0.05761399999999998
erc1155	21.277822	82.964143	10552.688368000001	0.029280999999999995
erc20	11.672759999999995	50.593543000000025	2723.8275940000008	0.042872

---

Generated by Synthetic Benchmark CI