Feature/json rpc api improvements by renatomaia · Pull Request #793 · cartesi/rollups-node

renatomaia · 2026-07-30T13:51:18Z

JSON-RPC API Improvements

This PR implements nine improvements identified as F1 to F9 as described here, and other improvements described in review here.

Divergences from Proposed Fixes

H1 requires empty batches and batches over 100 entries to return error code -32600. The implementation instead defines and returns -32040 as suggested here to indicate invalid batch request.
Y5 in the review requested true one-round-trip implementation, however the proposed fix was not possible because the repository queries still return COUNT(*) rather than ErrNotFound for an unknown application.
Y7 in the review explicitly requested moving single-request path logging the client-controlled method name from Info level to Debug level, but the original behavior was kept because one Info line was allowed per batch in the description of feature F1.
F2 and F6 describe the use of error codes -32001 for missing resources and -32002 for unknown applications from the original implementation. But such codes were replaced by -31001 and -31002 to avoid reserved server error codes as suggested here.

Commit relation to Features and Improvements

The table below lists the commits, and column ID indicates which improvement is introduced.

ID	Commit	Change	Component	Description
F1	`7bc850b`	feat	jsonrpc	add support for JSON-RPC 2.0 batch requests
H6	`20ec98f`	feat	jsonrpc	impose the same response size budget of batch requests to single requests
	`5718758`	refactor	jsonrcp	remove unused field 'data' from error reponses
F2	`cee9563`	feat	jsonrpc	add operation to get epoch by a virtual contiguous index
F3	`ac7e215`	feat	jsonrpc	add operation to get Node info like its chain ID, version, and default block
F4	`a61f0d9`	feat	jsonrpc	add inclusive index ranges to list epochs, inputs, outputs, and reports
F5	`cb05376`	feat	jsonrpc	allows to filter output by execution and multiple selectors
H2	`19cfead`	perf	repository	add DB index to improve filter output by execution
	`420f006`	feat	cli	allows to filter output by execution and multiple selectors
F6	`0979416`	feat	jsonrpc	add methods to get the count of executed and pending outputs
F7	`9026422`	feat	jsonrpc	support listing epochs with multiple statuses
	`5587ddb`	feat	cli	support listing epochs with multiple statuses
F8	`1c0906c`	fix	jsonrpc	report 256-bit integer fields in OpenRPC specification
F9	`0bcdab2`	refactor	jsonrpc	rename cartesi_getMatchAdvanced as cartesi_getMatchAdvance
	`bc292ee`	test	jsonrpc	add tests for positional decoding of parameters
Y1	`e937248`	fix	repository	avoid invalid SQL when listing outputs with empty type list
Y6	`e67bea3`	test	jsonrpc	add tests for some use cases of listing operations
Y7#5	`c54337c`	perf	jsonrpc	parse JSON-RPC API spec on service initialization
Y7#7	`b0b83f2`	docs	repository	add comment to clarify expected behavior of module API
H1	`da23670`	docs	jsonrpc	add warnings and recommendations on how to use the API
H4	`64d36c6`	docs	jsonrpc	improve documentation on response size limit
	`755a277`	fix	jsonrpc	skip ignored fields on positional decoding of parameters
Y6	`1a635e7`	test	jsonrpc	add more tests on parsing parameters
Y7#8	`e14b1e6`	style	cli	avoid line length violation
Y7#9	`7743ea0`	test	jsonrpc	add test to enforce log of method call
H6	`0b7c0c8`	feat	jsonrpc	impose the same listed items limit for all requests in a batch

Copilot

Pull request overview

Expands the JSON-RPC API with batching, additional queries, richer filtering, updated schemas, and corresponding CLI support.

Changes:

Adds batch dispatching with response budgeting and centralized error handling.
Adds node information, virtual epoch lookup, output counts, ranges, and multi-value filters.
Updates OpenRPC documentation, CLI commands, repository queries, and tests.

Reviewed changes

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

Show a summary per file

File	Description
`internal/repository/repotest/report_test_cases.go`	Tests report index ranges.
`internal/repository/repotest/output_test_cases.go`	Tests output ranges and filters.
`internal/repository/repotest/input_test_cases.go`	Tests input index ranges.
`internal/repository/repotest/epoch_test_cases.go`	Tests epoch index ranges.
`internal/repository/repository.go`	Extends repository filters.
`internal/repository/postgres/report.go`	Implements report range filtering.
`internal/repository/postgres/output.go`	Implements output filtering and counts.
`internal/repository/postgres/input.go`	Implements input range filtering.
`internal/repository/postgres/epoch.go`	Implements epoch range filtering.
`internal/jsonrpc/util_test.go`	Closes test repositories.
`internal/jsonrpc/types.go`	Refactors JSON-RPC response encoding.
`internal/jsonrpc/limitedwriter.go`	Adds batch response budgeting.
`internal/jsonrpc/jsonrpc.go`	Adds methods, filters, and batch dispatch.
`internal/jsonrpc/jsonrpc-discover.json`	Updates the OpenRPC specification.
`internal/jsonrpc/jsonrpc_test.go`	Tests new API behavior.
`internal/jsonrpc/batchcalls_test.go`	Tests batch request handling.
`internal/jsonrpc/api/response.go`	Defines node information responses.
`internal/jsonrpc/api/params.go`	Adds parameters and positional decoding.
`internal/jsonrpc/api/params_test.go`	Tests parameter decoding.
`cmd/cartesi-rollups-cli/root/read/service/types.go`	Updates read-service parameter types.
`cmd/cartesi-rollups-cli/root/read/service/repository.go`	Supports multi-value repository filters.
`cmd/cartesi-rollups-cli/root/read/service/jsonrpc.go`	Updates JSON-RPC client validation.
`cmd/cartesi-rollups-cli/root/read/outputs/outputs.go`	Adds output filter flags.
`cmd/cartesi-rollups-cli/root/read/matchadvances/matchadvances.go`	Uses renamed match-advance parameters.
`cmd/cartesi-rollups-cli/root/read/epochs/epochs.go`	Adds repeated status filters.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

… to single requests

…ion, and default block

…puts, and reports Changes include: - Added optional from and to JSON-RPC parameters. - Added IndexRange *Range to all four repository filters. - Added index-backed >= from and <= to PostgreSQL predicates shared by COUNT(*) and list queries. - Added shared hex-bound parsing and from <= to validation returning -32602 (invalid params). - Preserved positional-parameter compatibility by appending new fields after existing parameters. - Updated the OpenRPC specification. - Added repository tests confirming range composition with total count, descending order, offset, and limit. - Added no-database tests for reversed and malformed bounds.

…ctors Changes: - Added optional executed *bool to ListOutputsParams. - output_type now accepts either one selector string or a non-empty selector array. - Empty arrays return -32602 (invalid paramters). - Changed OutputFilter.OutputType to a selector slice and added Executed. - PostgreSQL now uses IN for selector OR semantics. - Extracted shared execution and selector predicates reused by GetNumberOfPendingExecutableOutputs. - Updated OpenRPC with string-or-array schema and executed. - Added tests for: - Single-selector compatibility - Selector arrays - Empty-array rejection - Executed tri-state decoding - Combined selector/execution filtering - Unchanged nil-filter behavior required by validator claim generation Targeted tests, package compilation, OpenRPC validation, and git diff --check pass. Validator compilation remains blocked by the environment’s missing Cartesi machine C header.

- Added flag '--executed' to `read outputs` - '--executed' filters for executed outputs. - '--executed=false' filters for unexecuted outputs. - Omitting the flag leaves execution status unfiltered. - Updated the CLI example. - Flag '--output-type' now can be repeated multiple times. - All selectors are forwarded in request order. - The help example and flag description were updated.

…utputs Methods added: - cartesi_getExecutedOutputCount - cartesi_getPendingExecutableOutputCount Each method: - Accepts an application parameter. - Returns {"data":"0x..."}. - Explicitly checks application existence before querying the aggregate. - Returns -32002 (application not found) for unknown applications. - Is registered in the dispatch table. Also updated the OpenRPC specification with the requested descriptions and added tests distinguishing unknown applications from existing applications with zero outputs.

- 'status' now accepts either a string or string array. - Every status is validated through 'EpochStatus.Scan'. - Invalid values return -32602 (invalid params) and identify the bad value. - An explicit empty array returns -32602 with Invalid epoch status: expected at least one status. - Added coverage for scalar/list decoding, multiple-status filtering, invalid list elements, and empty arrays. - Documents 'status' as 'oneOf': a single EpochStatus or a non-empty array of EpochStatus. - Documents omission as no filter and rejects empty arrays. - Documents the non-terminal watch set. - Clarifies terminal statuses never regress, preventing settled epochs from being re-read.

- '--status' now uses a repeatable string-array flag. - Multiple values are sent as StringOrList. - Updated help text and example.

Added 'UnsignedInteger256' schema for uint256 reference it in field 'Voucher.value'. Updated these 'EvmAdvance' uint256 fields to reference 'UnsignedInteger256': - chain_id - block_number - block_timestamp - prev_randao Kept 'EvmAdvance.index' and other genuine uint64 indexes on 'UnsignedInteger'.

…hAdvance - Renamed handler to handleGetMatchAdvance. - Renamed params struct to GetMatchAdvanceParams across node and CLI. - Updated OpenRPC discovery and JSON-RPC tests. - Normalized the parsed parent hash before repository lookup. - Added a mixed-case parent-hash regression test.

Tests covers all structs declared in `params.go`, comparing positional decoding against equivalent named decoding.

…pe list

- Added 'executed' plus multiple 'output_type' selector coverage for 'cartesi_listOutputs'. - Added inclusive 'from'/'to' DB-fixture requests for epochs, inputs, outputs, and reports. - Updated count fixture to execute two vouchers, asserting executed 2 and pending 0.

- Warns at both cartesi_listOutputs and its executed parameter that executions occur out of index order. - Explicitly rejects output indexes, offsets, and counts as resume cursors. - Documents the complete count → bounded pending-set query → diff workflow. - Repeats the workflow on both output-count methods. - Notes that a race-free cursor belongs to a future ingestion API.

- Documented budgetWriter and limitedWriter behavior, including: - Shared batch budget. - Atomic response buffering. - Exact-budget boundary behavior. - Poison-on-overflow semantics. - No budget consumption by the overflowing response. - Updated constant documentation to cover both single and batch requests. - Updated the OpenRPC description to document the 10 MB limit, -31003, retry guidance, and poison semantics.

- Omitted params - Top-level params: null - Empty positional arrays - Positional over-arity - Struct fields marked json:"-"

… a batch The JSON-RPC server now: - Calculates 'sum(limit)' for every list operation before dispatching a batch. - Normalizes limits consistently with handlers: - Omitted or zero → 50 - Above 10,000 → 10,000 - Allows a cumulative limit of exactly 10,000. - Rejects totals above 10,000 before any handler or database query runs. - Returns one batch-level -31003 error: Batch list item limit exceeded. - Supports both named and positional parameters across every list method. - Includes a registry coverage test so future list methods cannot silently bypass the budget. The client contract is documented in 'jsonrpc-discover.json', and operator guidance—including the residual unbounded 'COUNT(*)' cost—is documented in 'docs/http-posture.md'.

renatomaia requested review from mpolitzer and vfusco July 30, 2026 13:51

renatomaia force-pushed the feature/JsonRpcApiImprovements branch from 13bd7c4 to 31e82e1 Compare July 30, 2026 13:55

renatomaia self-assigned this Aug 3, 2026

brunomenezes mentioned this pull request Aug 4, 2026

feat: Add new JSONRPC API changes cartesi/rollups-ts#148

Closed

renatomaia force-pushed the feature/JsonRpcApiImprovements branch from 31e82e1 to fc36dae Compare August 11, 2026 14:36

vfusco requested a balanced review from Copilot August 11, 2026 19:48

vfusco added this to Rollups SDK Aug 11, 2026

vfusco added this to the 2.0.0 milestone Aug 11, 2026

github-project-automation Bot moved this to Todo in Rollups SDK Aug 11, 2026

Copilot started reviewing on behalf of vfusco August 11, 2026 19:48 View session

Copilot AI reviewed Aug 11, 2026

View reviewed changes

renatomaia force-pushed the feature/JsonRpcApiImprovements branch 3 times, most recently from 0f77172 to ea9ccde Compare August 14, 2026 01:22

tuler mentioned this pull request Aug 14, 2026

feat: track the rollups-node JSON-RPC API changes cartesi/rollups-ts#161

Draft

renatomaia added 14 commits August 14, 2026 20:38

feat(jsonrpc): add support for JSON-RPC 2.0 batch requests

7bc850b

feat(jsonrpc): impose the same response size budget of batch requests…

20ec98f

… to single requests

refactor(jsonrcp): remove unused field 'data' from error reponses

5718758

feat(jsonrpc): add operation to get epoch by a virtual contiguous index

cee9563

feat(jsonrpc): add operation to get Node info like its chain ID, vers…

ac7e215

…ion, and default block

perf(repository): add DB index to improve filter output by execution

19cfead

feat(cli): support listing epochs with multiple statuses

5587ddb

- '--status' now uses a repeatable string-array flag. - Multiple values are sent as StringOrList. - Updated help text and example.

renatomaia added 8 commits August 14, 2026 20:42

test(jsonrpc): add tests for positional decoding of parameters

bc292ee

Tests covers all structs declared in `params.go`, comparing positional decoding against equivalent named decoding.

fix(repository): avoid invalid SQL when listing outputs with empty ty…

e937248

…pe list

perf(jsonrpc): parse JSON-RPC API spec on service initialization

c54337c

docs(repository): add comment to clarify expected behavior of module API

b0b83f2

fix(jsonrpc): skip ignored fields on positional decoding of parameters

755a277

renatomaia force-pushed the feature/JsonRpcApiImprovements branch from ea9ccde to a5d2cef Compare August 15, 2026 02:06

renatomaia added 4 commits August 15, 2026 00:30

test(jsonrpc): add more tests on parsing parameters

1a635e7

- Omitted params - Top-level params: null - Empty positional arrays - Positional over-arity - Struct fields marked json:"-"

style(cli): avoid line length violation

e14b1e6

test(jsonrpc): add test to enforce log of method call

7743ea0

renatomaia force-pushed the feature/JsonRpcApiImprovements branch from a5d2cef to 0b7c0c8 Compare August 15, 2026 03:31

Navigation Menu

Uh oh!

Feature/json rpc api improvements - #793

Feature/json rpc api improvements#793
renatomaia wants to merge 26 commits into
next/2.0from
feature/JsonRpcApiImprovements

renatomaia commented Jul 30, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

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

Uh oh!

JSON-RPC API Improvements

Divergences from Proposed Fixes

Commit relation to Features and Improvements

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

renatomaia commented Jul 30, 2026 •

edited

Loading