Skip to content

Commit

Permalink
docs: add authority claimer documentation to node
Browse files Browse the repository at this point in the history
  • Loading branch information
GMKrieger committed Nov 8, 2023
1 parent c99e179 commit 112abb5
Show file tree
Hide file tree
Showing 6 changed files with 43 additions and 17 deletions.
46 changes: 33 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,9 +79,7 @@ cargo test

## Architecture Overview

The Cartesi Node is an event-based solution that may be depicted as follows:

![Node architecture diagram](./docs/node-architecture.drawio.svg)
The Cartesi Node is an event-based solution that runs the following microservices:

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](./offchain/rollups-events/README.md).
Expand All @@ -90,42 +88,64 @@ The [**State-fold Server**](./offchain/state-server/README.md) is the component

The [**Dispatcher**](./offchain/dispatcher/README.md) is the component that messages *Inputs* via the **Broker** to be processed elsewhere and submits *Claims* to the blockchain.

The [**Authority Claimer**](./offchain/authority-claimer/README.md) is the component that submits *Claims* to the blockchain at the end of every epoch.

The [**Advance Runner**](./offchain/advance-runner/README.md) 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**](./offchain/indexer/README.md) consumes all *Inputs* and *Outputs* transferred by the **Broker** and stores them in a **PostgreSQL** database for later querying via a **GraphQL Server** instance.

The [**Inspect Server**](./offchain/inspect-server/README.md) is responsible for the processing of *Inspect* requests via HTTP.

## Workflows
## Framework features

The Cartesi Node may act as a *User* (aka *Reader*) or *Validator* Node, hence performing different roles, which may be represented by different workflows.
The Cartesi Node contains 3 main features, the combination of which defines the node capabilities

### Reader Flow
### Reader Feature

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.
With the Reader Feature, 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.

### Validator Flow
### Claiming Feature

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.
The Claiming Feature allows a node to be run as a *Validator* node.
It complements the Reader Feature 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 **Authority Claimer** for being submitted to the blockchain.

### Inspect Data Flow
### Inspect Data Feature

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**.

## Host mode
## Execution modes

The Cartesi Node may act as a *User* (aka *Reader*), as a *Validator* or run locally as a *Host*, hence performing different roles, which may be represented by different workflows.

### Reader Mode

The *Reader Mode* is the default running operation of the node. It doesn't submit claims to the blockchain, instead only reads and updates the state. It contains the Reader and Inspect Data features.

![Reader mode architecture diagram](./docs/reader-architecture.drawio.svg)

To run the node in *Reader Mode*, one must have a Redis instance to act as the *Broker*, a PostgreSQL database instance and a GraphQL instance, and run the *State-fold Server*, *Dispatcher*, *Advance Runner*, *Indexer* and *Inspect Server*.

### Validator Mode

The *Validator Mode* has all the features of the *Reader Mode*, but can also submit claims through the [*Claiming Feature*](#claiming-feature).

![Validator mode architecture diagram](./docs/node-architecture.drawio.svg)

To run the node in *Validator Mode*, one must start the services as described in the *Reader Mode* above, but also initiate the *Authority Claimer* service.

### Host Mode

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](#architecture-overview) as depicted below.
In this case, the overall topology is very similar to the one presented in the [Validator Mode](#validator-mode) as depicted below.

![Host mode architecture diagram](./docs/host-architecture.drawio.svg)

Expand Down
2 changes: 1 addition & 1 deletion docs/host-architecture.drawio.svg
100755 → 100644
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion docs/node-architecture.drawio.svg
100755 → 100644
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 4 additions & 0 deletions docs/reader-architecture.drawio.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 4 additions & 0 deletions offchain/authority-claimer/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
# Authority Claimer

This service submits rollups claims consumed from the broker to the blockchain using the [tx-manager crate](https://github.com/cartesi/tx-manager).
It runs at the end of every epoch, when new claims are inserted on the broker.
2 changes: 0 additions & 2 deletions offchain/dispatcher/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,5 +2,3 @@

This service generates rollups inputs from state changes in the blockchain detected by the state-server.
These inputs are sent to the broker to be eventually used by the advance-runner.

The dispatcher also submits rollups claims consumed from the broker to the blockchain using the [tx-manager crate](https://github.com/cartesi/tx-manager).

0 comments on commit 112abb5

Please sign in to comment.