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

Projects

Status

No status

Relationships

None yet

Development

No branches or pull requests

Issue actions