Skip to content

CLI: Support read commands backed by either local DB or remote JSON-RPC datasource #723

@vfusco

Description

@vfusco

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:

  1. DB datasource (default): current behavior using repository (no change in semantics/output).
  2. 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 read that 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 read operations (e.g. ReadService / ReadDatasource) that covers the existing read entities (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)
  • Wire datasource selection at the read root 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 read command 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 exits 0.
  • Output parity: for equivalent queries and parameters, JSON output produced by db datasource matches the JSON-RPC datasource output (normalized).
  • Non-read commands 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

No labels
No labels

Type

No type
No fields configured for issues without a type.

Projects

Status

No status

Relationships

None yet

Development

No branches or pull requests

Issue actions