RPC Client

This library provides a typed JSON-RPC client for the Cartesi Rollups v2 JSON-RPC API. The API currently provides read-only access to 9 entities managed by a rollups node: applications, epochs, tournaments, commitments, matches, match advances, inputs, outputs and Reports.

There are RPC methods to get a single entity and methods to list a paginated collection of entities, for the 5 entities above:

cartesi_getApplication
cartesi_getEpoch
cartesi_getTournament
cartesi_getCommitment
cartesi_getMatch
cartesi_getMatchAdvance
cartesi_getInput
cartesi_getOutput
cartesi_getReport
cartesi_getWithdrawal

cartesi_listApplications
cartesi_listEpochs
cartesi_listTournaments
cartesi_listCommitments
cartesi_listMatches
cartesi_listMatchAdvances
cartesi_listInputs
cartesi_listOutputs
cartesi_listReports
cartesi_listWithdrawals

Applications

Cartesi Rollups nodes can manage several deployed applications at the same time. Each application has a corresponding Cartesi Machine, starting from a genesis machine, and evolving with each new input addressed to that application.

Deployment of new applications is currently managed by node operators on behalf of application developers. An application have an onchain representation, which can be deployed by the application developer or the node operator, but the offchain Cartesi machine have to be registered in the node by the node operator.

Epochs

Cartesi rollups is an optimistic rollups solution based on fraud proofs. These proofs are generated every interval called epoch, and a commitment is posted onchain. These commitments can then be challenged by Cartesi's upcoming fraud proof system. Once epochs are finalized executable outputs that were generated within that epoch can then be executed.

Tournaments, commitments, matches and match advances

Tournaments are the base of the dispute resolution system of Cartesi Rollups, currently implemented using the PRT algorithm. It follows a multi-level structure, composed of top level tournaments, which breaks down into mid level tournaments and bottom level tournaments. Validators submit commitments to tournaments, which are matched with other commitments in case of disputes to create matches.

Inputs

Inputs are "transactions" that are addressed to an application and fed into the application Cartesi machine, making it transition from state A to state B. Inputs are either sent directly to the application base layer InputBox smart contract, or to an alternative data availability solution.

Cartesi is working on integrations with Espresso and Avail.

Outputs

Outputs are pieces of information with attached proofs that are generated by applications. There are two basic types of outputs: notices and vouchers.

Notices are information only data with attached proofs that can be used on the base layer to prove some fact stated by the Cartesi rollup application.

Vouchers represent not only information but executable actions that can be performed on the base layer, through the execution of any function of any smart contract, or simply an ETH transfer.

Both notices and vouchers proofs are generated at the end of an epoch.

Reports

Reports are pieces of information with no attached proof.

State changes

Additional methods are provided by the API that are useful for identifying state changes: cartesi_getLastAcceptedEpochIndex, cartesi_getProcessedInputCount and cartesi_getExecutedOutputCount. These can be used for example by polling mechanisms to detect application state changes, to then take further actions. They are all monotone, so an unchanged value means nothing new happened.

cartesi_getPendingExecutableOutputCount is not one of them: it is a gauge that grows with new vouchers and shrinks with executions, so it can return to a previous value while work happened in between.

Node information

cartesi_getNodeInfo returns the chain ID, the semantic node version and the blockchain block tag the node reads the base layer at. It replaces cartesi_getChainId and cartesi_getNodeVersion, which are both deprecated.

Errors

Every method documents the errors it can return, and clients can dispatch on the error code.

-32603 is never used for missing resources, and -31001 on a forward-looking resource (the next epoch, input or output index) is the documented "not created yet" signal, so it is safe to poll.

The codes are exported as the errorCodes object, alongside the batch limits:

import {
    errorCodes,
    type ErrorCode,
    maxBatchSize,
    maxBatchListWork,
    defaultListLimit,
} from "@cartesi/rpc";

Batch requests

The node accepts JSON-RPC 2.0 batch arrays of up to maxBatchSize (100) entries. Entries execute sequentially and responses come back in request order, with every entry answered — including entries without an id, which are answered with id: null rather than suppressed as the specification would have it. Two budgets apply beyond the entry count.

A 10 MB response-size budget applies per HTTP request, cumulatively across a batch. An entry whose response would exceed the remaining budget is discarded without consuming it and gets -31003; the budget is then closed, so every later entry gets -31003 too, even one that would still have fit. Affected entries can be retried individually or in a smaller batch.

A list-work budget bounds a batch's row-fetch work to that of one maximal list request. Before dispatching anything, the node sums the effective limit of every list entry — counting an omitted or zero limit as defaultListLimit (50) and capping each entry at maxBatchListWork (10 000). A total above maxBatchListWork rejects the whole batch with a single -31004 and dispatches nothing. -31004 is a batch-level error raised before dispatch, so it is not attributed to any one method.

The budget bounds row-fetch work only. Neither the COUNT queries behind pagination nor offset traversal is metered, so a deep offset over a broad filter can still make the database scan and discard rows before the requested page. Broad list filters are worth avoiding regardless. offset itself is bounded to a signed 64-bit integer.

Because execution is sequential and bounded by the node's time limit, heavy list calls are better kept outside large batches.

Pagination

All the list methods, cartesi_listApplications, cartesi_listEpochs, cartesi_listInputs, cartesi_listOutputs and cartesi_listReports, are paginated. They all receive a limit and an offset number param in the request, and return a pagination object in the return, in addition to a data array of entity objects.

The methods listing entities indexed by a sequential number — epochs, inputs, outputs and reports — additionally accept from and to, an inclusive range on that index.

type Pagination = {
    total_count: number;
    limit: number;
    offset: number;
};
 
type PaginatedReturnType<T> = {
    data: T[];
    pagination: Pagination;
};