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_getMatchAdvanced
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

Two additional methods are provided by the API that are useful for identifying state changes: cartesi_getLastAcceptedEpochIndex and cartesi_getProcessedInputCount. These can be used for example by polling mechanisms to detect application state changes, to then take further actions.

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.

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