-
Notifications
You must be signed in to change notification settings - Fork 73
Description
Context / Problem
Today the CLI read subcommands query the node state directly from the database via the repository package. This is great for local development and for admin-style workflows where the CLI also performs node management tasks that require DB access.
However, developers and operators may want to run the CLI against a remote node (or a hosted service) and fetch the same read data through the JSON-RPC API instead of requiring direct DB connectivity.
We need a clean way to choose the datasource per invocation while keeping the current DB behavior as the default.
Proposed change
Introduce a datasource abstraction for the read command family with two implementations:
- DB datasource (default): current behavior using
repository(no change in semantics/output). - JSON-RPC datasource: fetches data from a remote JSON-RPC endpoint and renders the same output as the DB datasource.
CLI UX:
- Add a global flag (and env var) to enable JSON-RPC mode, without breaking existing flows:
--jsonrpc-endpoint <url>(env:CARTESI_JSONRPC_API_ADDRESS)
- Commands outside
readthat require DB access must remain unchanged for now.
Implementation should reuse the same method semantics and response shapes defined by internal/jsonrpc/jsonrpc-discover.json.
Deliverables
- Define a small interface for
readoperations (e.g.ReadService/ReadDatasource) that covers the existingreadentities (and the new PRT ones). - Implement DB-backed datasource by adapting the existing code paths that call
repository. - Implement JSON-RPC-backed datasource:
- JSON-RPC client wrapper with request/response types derived from (or aligned with)
internal/jsonrpc/jsonrpc-discover.json - Proper error mapping (HTTP/JSON-RPC errors -> CLI-friendly messages)
- JSON-RPC client wrapper with request/response types derived from (or aligned with)
- Wire datasource selection at the
readroot command level so all subcommands share the same mechanism. - Update help text to document the new flags and env vars.
Acceptance criteria
- Backwards compatible: running any existing
readcommand without new flags behaves exactly as before (same output, same defaults). - New flags are exposed at the appropriate scope (global for the CLI or at least under
read), and documented in--help, including env vars. - JSON-RPC mode works without DB access:
-
cartesi-rollups-cli read epochs <app> --jsonrpc-endpoint <url>returns valid data and exits0.
-
- Output parity: for equivalent queries and parameters, JSON output produced by
dbdatasource matches the JSON-RPC datasource output (normalized). - Non-
readcommands that require DB connectivity are unaffected by these changes.
Notes:
- Prefer keeping the rendering/formatting layer shared so only the data-fetching changes between datasources.
- If we already have common filtering/pagination conventions in the DB path, mirror them in JSON-RPC mode (same flag names, same defaults).
Metadata
Metadata
Assignees
Labels
Type
Projects
Status