Add JSON-RPC batch support for contract reads

[Lakes41]

Difficulty: Advanced

Type: Feature

Summary

Add support for batching compatible contract read calls into one JSON-RPC request. This helps integrations reduce RPC overhead when checking many wallets or guilds.

Current Behaviour

Each contract read sends a separate eth_call request. Applications that need multiple balances or owner lookups must manage batching themselves.

Expected Behaviour

The SDK should expose batch helpers for safe read-only contract calls and return ordered per-item results.

Suggested Implementation

Add methods such as getMembershipTokenBalancesBatch or a lower-level batchEthCall helper. Preserve input order, support partial failures, and avoid batching unsupported mutating operations.

Files or Areas Likely Affected

• src/contracts/contractClient.ts
• src/contracts/contract.types.ts
• tests/contracts.test.ts
• docs/api-reference.md
• docs/integration-guide.md

Acceptance Criteria

• Batch token balance reads preserve input order
• Batch guild owner reads preserve input order where applicable
• Partial RPC failures are reported per item
• Invalid inputs are rejected before the RPC request is built
• Tests cover success, partial failure, malformed RPC response, and ordering
• Documentation explains provider compatibility assumptions

Additional Notes

Assumption: this should use JSON-RPC batch requests only for read-only methods.

[MoscowDev]

I’d like to take this issue on. I’ve worked with JSON-RPC batching patterns and SDK-level abstraction layers before, especially around preserving ordering guarantees and safely handling partial failures, so this fits well within my experience.

My approach would be:

1. Core batching utility

• Add a low-level batchEthCall helper in contractClient.ts

• Use JSON-RPC batch request format for read-only eth_call

• Ensure:

  • Requests are sent in a single payload
  • Responses are mapped back using request order (not response order)

2. SDK-level batch methods

• Implement higher-level helpers such as:

  • getMembershipTokenBalancesBatch
  • getGuildOwnersBatch (or similar read patterns already in the SDK)

• Keep them thin wrappers over batchEthCall

3. Correct ordering guarantees

• Strictly preserve input order regardless of RPC response ordering
• Map results using index-based correlation, not IDs or assumptions

4. Partial failure handling

• If individual calls fail:

  • Return structured result per item:

    • { success: true, value } or { success: false, error }

• Never fail the entire batch unless the RPC request itself fails

5. Input validation

• Reject invalid inputs before request construction:

  • malformed addresses
  • unsupported method signatures
  • non-read-only methods (prevent accidental mutation calls)

6. Tests

Expand tests/contracts.test.ts to cover:

• Successful batch responses
• Partial RPC failures
• Malformed RPC response shapes
• Ordering correctness under shuffled RPC responses
• Validation failures before request execution

7. Documentation

Update:

• docs/api-reference.md:

  • batch API signatures
  • response format

• docs/integration-guide.md:

  • JSON-RPC batch behavior
  • provider compatibility notes (not all RPC providers support batching)

This will significantly reduce RPC overhead for multi-entity reads while keeping the API deterministic, safe, and integration-friendly.

[Nursca]

Hello I would like to work on this issue