Skip to main content

Smart Rollups

Smart Rollups handle transactions and logic in a separate environment from the main Tezos nodes. The transactions and logic that Smart Rollups run is called layer 2 to differentiate it from the main network, which is called layer 1.

The code of a Smart Rollup is public, and anyone can run a Smart Rollup node to run that code and verify that other nodes are running it correctly, just like anyone can run nodes, bakers, and accusers on layer 1. This code, called the kernel, must behave in a deterministic manner and use a proof-generating virtual machine (PVM) to generate a proof of its state. In this way, multiple nodes can run the same code to create a single state for the rollup, and other nodes can verify the state of the rollup.

For an introduction to Smart Rollups, see the tutorial Deploy a Smart Rollup.

This diagram shows a high-level view of how Smart Rollups interact with layer 1:

Uses for Smart Rollups​

Smart Rollups allow you to run large amounts of processing that would be impractical on layer 1. For example, Smart Rollups are not constrained to the layer 1 block baking rate and therefore can run far more transactions per second than layer 1. Smart Rollups can also manipulate large amounts of data without needing to store it on layer 1.

Smart Rollups can also retrieve data from outside the blockchain in specific ways that smart contracts can't do. For example, Smart Rollups enable Etherlink, which connects Tezos to Ethereum.

Communication​

Smart Rollups have access to two sources of information: the rollup inbox and the reveal data channel. These are the only sources of information that rollups can use. Smart Rollup nodes cannot communicate directly with each other; they do not have a peer-ro-peer communication channel like layer 1 nodes.

Rollup inbox​

As part of its state, layer 1 has a rollup inbox that contains messages from layer 1 to all rollups. Anyone can add a message to this inbox and all messages are visible to all rollups. Smart Rollups filter the inbox to the messages that they are interested in and act on them accordingly.

The messages that users add to the rollup inbox are called external messages. For example, users can add messages to the inbox with the Octez client send smart rollup message command. Smart contracts can add messages in a way similar to calling a smart contract entrypoint, by using the Michelson TRANSFER_TOKENS instruction.

Each block also contains these internal messages, which are created by the protocol:

  • Start of level, which indicates the beginning of the block
  • Info per level, which includes the timestamp and block hash of the preceding block
  • End of level, which indicates the end of the block

Smart Rollup nodes can use these internal messages to know when blocks begin and end.

Reveal data channel​

Smart Rollups can request information through the reveal data channel, which can include information about layer 1 or information that comes from outside layer 1. Importantly, the information that passes through the reveal data channel does not pass through layer 1, so it is not limited by the bandwidth of layer 1 and can include large amounts of data.

The reveal data channel supports these requests:

  • A rollup node can request arbitrary data up to 4KB at a time if it knows the blake2b hash of the data, known as preimage requests. To transfer more than 4KB of data, rollups must use multiple files, such as a single file that contains hashes that point to other files.

  • A rollup node can request information about the rollup, including the address and origination level of the rollup, known as metadata requests.

Consensus​

Smart Rollup nodes acheive consensus differently from layer 1 nodes. Instead of constantly sharing blocks and updating their states, layer 2 nodes maintain their states internally and share them at predefined intervals. Because the nodes behave in a deterministic manner, their states should all be the same if they have processed the same Smart Rollup inbox messages. This state is referred to as the "state of the rollup."

Rollups share and achieve consensus on the state of the rollup with these two intervals:

  • The commitment period runs for 60 consecutive blocks. During the commitment period, the rollups receive messages from the Smart Rollup inbox, process them, and update their internal states.

    At the end of the commitment period, Smart Rollup nodes use the PVM to generate a hash of their states and publish it to layer 1. This hash is referred to as the node's commitment. The commitment allows other nodes to verify that the node has responded to all of the messages during the commitment period and run the rollup code accurately.

    Then a new commitment period begins.

  • The refutation period for a commitment period starts when the commitment period ends. During the refutation period, if two or more commitments are different, the nodes play a refutation game to identify the correct commitment.

    Then the correct commitment is said to be cemented and therefore final and unchangeable. The commitments for the next commitment period build on this cemented commitment.

Smart Rollup lifecycle​

The general flow of a Smart Rollup goes through these steps:

  1. A user originates the Smart Rollup to layer 1.
  2. One or more users start Smart Rollup nodes based on that Smart Rollup.
  3. A commitment period begins.
  4. During the commitment period, the Smart Rollup nodes receive the messages in the Smart Rollup inbox, filter them to the messages that they are interested in, and run processing based on those messages.
  5. The nodes add outgoing messages to the Smart Rollup outbox in the form of calls to smart contracts.
  6. At the end of the commitment period, the nodes publish their commitments to layer 1. These commitments are proofs generated from the state of the Smart Rollup node, which means that if all of the nodes run the Smart Rollup correctly, the commitments are all the same.
  7. A new commitment period begins.
  8. At the same time as the new commitment period begins, a refutation period for the previous commitment period begins, during which time other nodes can verify the commitment and publish a concurrent commitment to confirm or refute it. Because commitment periods are shorter than refutation periods, many overlapping refutation periods can be active at the same time, but only one commitment period is active at a time. If there are two or more different commitments, the nodes play a refutation game to determine the correct commitment.
  9. At end of the refutation period, the correct commitment is said to be cemented and therefore final and unchangeable.
  10. After the commitment is cemented, any client, including the rollup operator or ordinary layer 1 user, can trigger one of the outbox messages to run the smart contract call.

Origination​

Like smart contracts, users deploy Smart Rollups to layer 1 in a process called origination.

The origination process stores data about the rollup on layer 1, including:

  • An address for the rollup, which starts with sr1
  • The type of proof-generating virtual machine (PVM) for the rollup, which generates a proof based on the state of the rollup; currently only the wasm_2_0_0 PVM is supported
  • The source code of the rollup, which is a WebAssembly program referred to as the rollup's kernel
  • The Michelson data type of the messages it receives from layer 1

TODO: Later docs mention the genesis commitment -- is that a different thing or is it implied by other things in the origination?

After it is originated, anyone can run a Smart Rollup node based on this information.

Commitment periods​

Starting from the rollup origination level, levels are partitioned into commitment periods of 60 consecutive blocks. During each commitment period, the rollup receives the messages in the rollup inbox and processes them.

At the end of the commitment period, the rollup node must use the PVM to publish its state to layer 1, which is called its commitment. Each commitment builds on the previous commitment, going back to the genesis commitment from when the Smart Rollup was originated. This commitment asserts that the rollup node has responded to every message in every block in the commitment period and updated its state according to the code for the Smart Rollup.

Each node must stake 10,000 tez along with its commitment. When another node makes an identical commitment, its stake is added to the stake of the first commitment.

Then a refutation period for the commitment period begins, and a new commitment period begins.

Refutation periods​

Because the PVM is deterministic and all of the inputs are the same for all nodes, any honest node that runs the same Smart Rollup produces the same commitment. As long as nodes publish matching commitments, they continue running normally.

During the refutation period for a commitment period, if two or more nodes publish different commitments, two of them play a refutation game to identify the correct commitment. The nodes automatically play the refutation game by stepping through their logic to identify the point at which they differ. At this point, layer 1 uses the PVM to identify the correct commitment. Then the protocol gives half of the incorrect commitment's stake to the correct commitment's stake, and burns the other half. Then the protocol eliminates the incorrect commitment because it has no stake.

This refutation game happens as many times as is necessary to eliminate incorrect commitments. Because the node that ran the PVM correctly is guaranteed to win the refutation game, a single honest node is enough to ensure that the Smart Rollup is running correctly. For this reason, Smart Rollups are sometimes called Smart Optimistic Rollups.

At the end of the refutation period, the correct commitment is said to be cemented and therefore final and unchangeable. A commitment can't be cemented until the end of the refutation period and until all previous commitments are cemented.

The refutation period lasts 2 weeks on Mainnet; it can be different on other networks.

Running outbox messages​

After a commitment is cemented, clients can trigger the transactions in that commitment's outbox with the Octez execute outbox message command. When they trigger the transaction, it runs like any other call to a smart contract. For more information, se Triggering the execution of an outbox message in the Octez documentation.

Examples​

For examples of Smart Rollups, see this repository: https://gitlab.com/tezos/kernel-gallery.

Last updated on