# Rollup node architecture

## Modules layout

### Restructuring in libraries

In the [proposed reorganization](https://gitlab.com/tezos/tezos/-/merge_requests/7500), there are three libraries:

- `lib_sc_rollup_node`: code that provides functionality to the rollup node
- `lib_sc_rollup_client`: code that provides functionality to the rollup client
- `lib_sc_rollup`: modules that are used both in the node and client


The graph above shows the dependency relations between the different modules of the rollup node and client and the chosen separation for the libraries. Note that the white modules could have gone to the common library (strictly based on dependency relations), but some of them only make sense in the context of the node or the client.

This setup allows to write unit test easily (which are currently absent).

### Caveat :warning:

The tests in `lib_protocol` depend on the library `lib_sc_rollup` (named `tezos-sc-rollup-alpha`) with a global open.

In order to not change code in `proto_PtMumbai/lib_protocol`, one cannot rename the library or remove the global open. In addition, we have to be careful as to what we put in scope in the library so as not to break existing tests.

**Suggestion**: for future protocols (including N), we should probably move the tests that depend on the library outside of `lib_protocol`.

## Proposed changes for moving core outside of `proto_alpha`

We propose the following architecture to move part of the rollup node outside of `proto_alpha`.

The parts of the rollup node which are inherently protocol specific are:
- The interpretation of messages and the execution of the PVM
- The PVM step and input proof production (arguable)
- The `Sc_rollup_*` operations that appear in L1 blocks (but not necessarily their content, e.g. messages)

The result of this refactoring will be (if we only look at the node and not the client):
- a library (outside of `proto_*`) in `octez-sc-rollup-node` which contains the "factorizable" part of the rollup node between the different protocols,
- multiple libraries `octez-sc-rollup-node-PtMumbai`, `octez-sc-rollup-node-alpha`, _etc._ which contain code specific to each protocol,
- a binary `octez-sc-rollup-node` which depend on the `octez-sc-rollup-node` and the the protocol libraries `octez-sc-rollup-node-PtMumbai`, `octez-sc-rollup-node-alpha`, _etc._

:::info
🛈 The `octez-sc-rollup-node` library could depend on the protocol libraries but does not need to, as show in the diagram below. The protocol libraries depend on the `octez-sc-rollup-node` library and act instead as _plugins_, and their functionality is made available to rollup node at initialization time.
:::

[](https://excalidraw.com/#json=cP6LEhD8r_V0KL-Kwi3y-,ZhvYSjJgLWGBDqUILVqP8Q)

The rollup node has its own base data types for commitments, messages, dissections, etc. which are in bijection with their corresponding version for **each** (supported) protocol:

- The rollup node only manipulate _non-protocol specific_ data.
- All transformations are handled by the protocol specific rollup node library.

:::warning
⚠︎ This design choice is made on the assumption that the basic types of the smart rollups will not change drastically.
:::

Each protocol library exposes part of their functionality through a module with a given signature ("SC Protocol signature" on the schema) and registers itself in the rollup node.

There is an association from protocol hashes to supported protocol modules. Each Tezos block header has a protocol information associated and so we use the correction functions to, _e.g._, interpret the messages of a block or recompute states for dissections.

This will allow to more gracefully handle protocol migration, and _e.g._ play refutation games that span over protocol upgrades.

:::info
🛈 The surface area of the protocol signature can be large in our case (as long as there isn't too much overhead) and can _evolve over time_ to cover features supported only in a subset of the protocols.
:::

The injector is also moved outside of `proto_alpha` and is abstracted over the type of operations that it can inject. The conversion to _protocol manager operations_ is handled by the protocol rollup node library (not shown on the diagram) and the injection primitives for each protocols are provided by a protocol specific library (lib_injector_alpha).

The "rollup operations" will be defined at the level of the rollup node (they only become tezos [manager] operations at the time of simulation or injection) and so will be valid for any supported protocol.

The graph below shows the dependency relation for the rollup node (A $\rightarrow$ B indicates that A depends on B, either directly, by registration with a side effect at initialization, or at linking time.)

digraph G {
  rankdir = BT
  // newrank = true
  
  node [style="rounded"; shape=box]
  
  subgraph cluster_shell {
  label=shell
  bin [label="octez-smart-rollup-node (bin)"; style="filled"]
  lib [label="octez-smart-rollup-node (lib)"]
  lib_inj [label="octez-injector (lib)"]
  }
  
  subgraph cluster_alpha {
  label=proto_alpha
  lib_inj_alpha [label="octez-injector-alpha (lib)"]
  lib_alpha [label="octez-smart-rollup-node-alpha (lib)"]
  }
  
  subgraph cluster_mumbai {
  label=proto_PtMumbai
  lib_inj_mumbai [label="octez-injector-PtMumbai (lib)"]
  lib_mumbai [label="octez-smart-rollup-node-PtMumbai (lib)"]
  }

  bin -> lib
  bin -> lib_alpha [style=dotted; label=link]
  bin -> lib_mumbai [style=dotted; label=link]
  lib_alpha -> lib [style=dashed; label=register]
  lib_mumbai -> lib  [style=dashed; label=register]
  lib -> lib_inj
  lib_inj_alpha -> lib_inj [style=dashed; label=register]
  lib_inj_mumbai -> lib_inj [style=dashed; label=register]
  bin -> lib_inj_alpha [style=dotted; label=link]
  bin -> lib_inj_mumbai [style=dotted; label=link]
}