The Cartesi Node is the part of the Cartesi Rollups Framework responsible for handling the communication between the on-chain smart contracts and the Cartesi Machine.
The Cartesi Rollups machine and smart contracts live in fundamentally different environments. This creates the need for the node that manages and controls the communication between the blockchain and the machine. As such, the node is responsible for first reading data from Cartesi smart contracts, then sending them to the machine to be processed, and finally publishing their results back to the blockchain.
The node can be used by anyone who's interested in the rollups state of affairs. We divide interested users into two roles, which run different types of nodes: readers and validators.
Reader nodes are only interested in advancing their off-chain machine. They consume information from the blockchain but do not bother to enforce state updates, trusting that validators will ensure the validity of all on-chain state updates.
Validators, on the other hand, have more responsibility: they not only watch the blockchain but also fight to ensure that the blockchain will only accept valid state updates.
Before building and running any of the inner projects, you should download the submodules with:
git submodule update --init --recursiveTo more information on how to build the rollups-node docker image, see the build directory.
All projects comprising the Cartesi Node require Rust to be executed. To install it, follow the instructions from the Rust website.
The Cartesi Node depends on the following components:
| Component | Version |
|---|---|
| Cartesi Machine SDK | v0.16.2 |
| Cartesi OpenAPI Interfaces | v0.6.0 |
| Cartesi Rollups Contracts | v1.0.2 |
| Cartesi Server Manager | v0.8.2 |
To run any of the inner projects, execute the command:
cargo runSome of the inner projects may have additional run instructions. Refer to their own documentation for more details.
It is possible to configure the behavior of any of the projects by passing CLI arguments and using environment variables. Execute the following command to check the available options for each project:
cargo run -- -hTo connect the Broker to a Redis server via TLS, the server's URL must use the rediss:// scheme (with two "s"es).
This is currently the only way to tell Broker to use a TLS connection.
To run the tests available in any of the projects, execute the command:
cargo testThe Cartesi Node is an event-based solution that may be depicted as follows:
The Broker is a Redis-based message broker that mediates the transferring of Inputs, Outputs and Claims between the Cartesi Node components. For details specific to the Broker and the available event streams, refer to the Rollups Events project.
The State-fold Server is the component responsible for tracking blockchain state changes and deriving Inputs from them to be processed.
The Dispatcher is the component that messages Inputs via the Broker to be processed elsewhere and submits Claims to the blockchain.
The Advance Runner is the one responsible for relaying Inputs to the Server Manager to be processed by the underlying DApp running in the embedded Cartesi Machine. The Advance Runner obtains the resulting Outputs and Claims from the Server Manager and adds them to the Broker.
The Indexer consumes all Inputs and Outputs transferred by the Broker and store them in a PostgreSQL database for later querying via a GraphQL Server instance.
The Inspect Server is responsible for the processing of Inspect requests via HTTP.
The Cartesi Node may act as a User (aka Reader) or Validator Node, hence performing different roles, which may be represented by different workflows.
In the Reader Flow, any Input read from the blockchain by the State-fold Server is received by the Dispatcher and relayed to the Broker through an input-specific stream. The Input is eventually consumed by the Advance Runner and used to advance the state of the Server Manager, thus generating an Advance request to be processed by the underlying DApp.
After finishing the processing, the DApp may generate a number of Outputs, which are eventually retrieved by the Advance Runner and fed back into the Broker through an output-specific stream.
Inputs and Outputs are consumed from their respective streams by the Indexer and stored in a PostgreSQL database and may be queried by the DApp Frontend via a GraphQL Server instance.
The Validator Flow may only be performed by Validator nodes. It complements the Reader Flow by generating Claims at the end of Epochs, which are generated by the Server Manager, and sent to the Broker by the Advance Runner through a claims-specific stream to be eventually consumed by the Dispatcher for being submitted to the blockchain.
Every Inspect request sent by the Frontend via the Rollups HTTP API is captured by the Inspect Server and forwarded to the Server Manager, which queries the state of the underlying DApp via Inspect requests.
Every request results in an Inspect Response that is returned to the Inspect Server, which sends it back to the Frontend.
The Cartesi Node may operate in a so-called Host mode when deployed locally for development purposes.
In this case, the overall topology is very similar to the one presented in the Architecture Overview as depicted below.
The main difference is that the Server Manager is not present and, there's no Cartesi Machine available as a result. Their features are emulated by the Host Runner, which interacts with the DApp Backend being executed locally in the host to perform the Cartesi Node workflows.
Thank you for your interest in Cartesi! Head over to our Contributing Guidelines for instructions on how to sign our Contributors Agreement and get started with Cartesi!
Please note we have a Code of Conduct, please follow it in all your interactions with the project.
Note: This component currently has dependencies that are licensed under the GNU GPL, version 3, and so you should treat this component as a whole as being under the GPL version 3. But all Cartesi-written code in this component is licensed under the Apache License, version 2, or a compatible permissive license, and can be used independently under the Apache v2 license. After this component is rewritten, the entire component will be released under the Apache v2 license.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent