From 9889297beeac6fac68b7c803857e4f6acfe177a5 Mon Sep 17 00:00:00 2001 From: Gustavo Madeira Krieger Date: Wed, 8 Nov 2023 16:00:47 -0300 Subject: [PATCH] docs: add authority claimer documentation to node --- README.md | 46 ++++++++++++++++++++-------- docs/host-architecture.drawio.svg | 2 +- docs/node-architecture.drawio.svg | 2 +- docs/reader-architecture.drawio.svg | 4 +++ offchain/authority-claimer/README.md | 4 +++ offchain/dispatcher/README.md | 2 -- 6 files changed, 43 insertions(+), 17 deletions(-) mode change 100755 => 100644 docs/host-architecture.drawio.svg mode change 100755 => 100644 docs/node-architecture.drawio.svg create mode 100644 docs/reader-architecture.drawio.svg create mode 100644 offchain/authority-claimer/README.md diff --git a/README.md b/README.md index ffe52c0e1..6b656f93c 100644 --- a/README.md +++ b/README.md @@ -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). @@ -90,6 +88,8 @@ 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**. @@ -97,35 +97,55 @@ The [**Indexer**](./offchain/indexer/README.md) consumes all *Inputs* and *Outpu 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) diff --git a/docs/host-architecture.drawio.svg b/docs/host-architecture.drawio.svg old mode 100755 new mode 100644 index 57469ee58..310e26a81 --- a/docs/host-architecture.drawio.svg +++ b/docs/host-architecture.drawio.svg @@ -1,4 +1,4 @@ -
PostgreSQL
PostgreSQL
Host
Runner
Host...
Advance Runner
Advance Runner
Indexer
Indexer
State-fold Server
State-fold Ser...
Dispatcher
Dispatcher
Inspect
Server
Inspect...
GraphQL
Server
GraphQL...
Frontend
Frontend
DApp
Backend
DApp...
Container environment
Container env...
Host
Host
Broker
(Redis)
Broker...Text is not SVG - cannot display \ No newline at end of file +
PostgreSQL
PostgreSQL
Host
Runner
Host...
Advance Runner
Advance Runner
Indexer
Indexer
State-fold Server
State-fold Ser...
Dispatcher
Dispatcher
Inspect
Server
Inspect...
GraphQL
Server
GraphQL...
Frontend
Frontend
DApp
Backend
DApp...
Container environment
Container env...
Host
Host
Broker
(Redis)
Broker...
Authority Claimer
Authority Clai...Text is not SVG - cannot display \ No newline at end of file diff --git a/docs/node-architecture.drawio.svg b/docs/node-architecture.drawio.svg old mode 100755 new mode 100644 index 0aa28e887..696677358 --- a/docs/node-architecture.drawio.svg +++ b/docs/node-architecture.drawio.svg @@ -1,4 +1,4 @@ -
PostgreSQL
PostgreSQL
Snapshot Repository (filesystem)
Snapshot Repo...
Server Manager
Server Mana...
Advance Runner
Advance Runner
Indexer
Indexer
State-fold Server
State-fold Ser...
Dispatcher
Dispatcher
Inspect
Server
Inspect...
GraphQL
Server
GraphQL...
Frontend
Frontend
Cloud
Cloud
internet
internet
Broker
(Redis)
Broker...Text is not SVG - cannot display \ No newline at end of file +
PostgreSQL
PostgreSQL
Snapshot Repository (filesystem)
Snapshot Repo...
Server Manager
Server Mana...
Advance Runner
Advance Runner
Indexer
Indexer
State-fold Server
State-fold Ser...
Dispatcher
Dispatcher
Inspect
Server
Inspect...
GraphQL
Server
GraphQL...
Frontend
Frontend
Cloud
Cloud
internet
internet
Broker
(Redis)
Broker...
Authority Claimer
Authority Clai...Text is not SVG - cannot display \ No newline at end of file diff --git a/docs/reader-architecture.drawio.svg b/docs/reader-architecture.drawio.svg new file mode 100644 index 000000000..fb78b3d67 --- /dev/null +++ b/docs/reader-architecture.drawio.svg @@ -0,0 +1,4 @@ + + + +
PostgreSQL
PostgreSQL
Snapshot Repository (filesystem)
Snapshot Repo...
Server Manager
Server Mana...
Advance Runner
Advance Runner
Indexer
Indexer
State-fold Server
State-fold Ser...
Dispatcher
Dispatcher
Inspect
Server
Inspect...
GraphQL
Server
GraphQL...
Frontend
Frontend
Cloud
Cloud
internet
internet
Broker
(Redis)
Broker...Text is not SVG - cannot display \ No newline at end of file diff --git a/offchain/authority-claimer/README.md b/offchain/authority-claimer/README.md new file mode 100644 index 000000000..fc91cb73c --- /dev/null +++ b/offchain/authority-claimer/README.md @@ -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. diff --git a/offchain/dispatcher/README.md b/offchain/dispatcher/README.md index 78087daba..19fbe8749 100644 --- a/offchain/dispatcher/README.md +++ b/offchain/dispatcher/README.md @@ -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).