---
title: Kernel in SCORU
tags: Kernel
---

# Knowledge - Kernel in SCORU

## Gather knowledge

- Big picture about SCORU and kernel
:::spoiler
- A big picture of SCORU
A talk by Yann and Hans about scaling Tezos with rollups: https://www.youtube.com/watch?v=SRDlaAhhKBY

- The relationship of the two VMs:
- Use Fast VM by default [^1]
- Take snapshots - every 20s
- In case of a refutation, replay from a snapshot on the PVM
- Key elements to build on top of Optimistic rollups
- A big picture of environments will be available on Optimistic Rollups
:::
[^1]: Design document: https://hackmd.io/dkiwun7JQnCgHjuVbmtX_Q

- What is "WASM" - WebAssembly PVM?
- It is a low-level assembly-like language.
- A Wasm rollup runs a Wasm program named a "kernel".
- This wasm desiged as a compilation target for other languages.
- A WebAssembly engine is responsible for parsing and instantiating modules, maintaining the state of module instances, and executing instructions, either interpretation or compilation.

- Why choose WASM as the programming language for smart rollups?
- One of the reason is because it has gradually become an ubiquitous compilation target over the year.
- Go or Rust now natively compile to WASM.
- `cargo` - the official Rust package manager, provides an official target to compile `.wasm` binary file that are valid WASM kernel.

- What is "PVM"?
- A PVM stands for *Proof-generating Virtual Machine*. This PVM is implemented in the Tezos protocol. It's a slightly modified virtual machine that can **output a proof that operations have been processed corrected**. The rollup node can use this implementation to produce a proof and post it to Layer 1, where it will be checked by the Layer 1 node.

- What is "kernel" in SCORU?[^2]
- A kernel can be seen as an operation system, it can be anything, for instance: a kernel EVM engine - Ethereum Virtual machine, enabling Solidity smart contracts, or a kernel transaction engine - focus on transactions of assets
- From a Layer 1 point of view, the kernel acts like a smart contract, interacting with its host through a Rollup Management Protocol, which lets it accept deposits, effect withdrawal, self-upgrade and so on.

[^2]: Reference from NL post: https://research-development.nomadic-labs.com/next-generation-rollups.html

- Recap: the relationship of kernel, wasm, pvm

- What is the role of a "kernel" in SCORU?
- The role of the kernel is to process input messages, to update a state, and to output messages targetting the Layer 1 following a user-defined logic.

- What are the "rules" for kernel that can be complied with the WASM?[^3]
- Some instructions and types of the WASM language are forbidden, specially the one related to floating-point arithmetic.
- The call stack of the WASM kernel is restricted to 300.
A valid kernel statisfies the following constraints:
- It exports a function `kernel_next` that takes no arguments and returns nothing.
- It declares and exports exactly one memory.
- It only imports the host functions, exported by the (virtual) module `rollup_safe_core`.

[^3]: Reference from this MR: https://gitlab.com/tezos/tezos/-/merge_requests/6629

- What is the Rust bindings/host to the Wasm PVM - Rust SDK?
- The Host capabilities is provided by the VM. Used by kernels.
- An example of a minial kernel using the host capabilities
:::spoiler
:::
- This host bindings is like an API, for instance, if you want to send an asset from the rollup to a Layer 1 address, there is a ready-made function for that.
- With these bindings, developers can write a kernel, compile it to WebAssembly, and know that its interaction with the Tezos blockchain will be reliable and secure.
- It is written in [Rust](https://docs.substrate.io/fundamentals/rust-basics/) because it is a popular language with a mature toolchain providing robust compilation to Wasm.

Diagram of the kernel repo (maybe out of date), but good to add here to have a general picture
:::success
:::spoiler
:::

Host bindings implementation:
:::success
:::spoiler Details
Source code of this bindings is at: https://gitlab.com/tezos/kernel/-/tree/main/host and its doc is at https://tezos.gitlab.io/kernel/doc/host/index.html
This define the SCORU wasm host function. The host exposes "safe capabilites" as a set of C-style APIs. The `host` crate defines these as `extern` functions (see [`rollup_core`](https://tezos.gitlab.io/kernel/doc/host/rollup_core/index.html)) and is reponsible for providing safe wrappers which can be called from **safe rust**.
- [input](https://tezos.gitlab.io/kernel/doc/host/input/index.html): the possible types that may be returned by (Runtime) `crate::runtime::Runtime` when reading an input
- [path](https://tezos.gitlab.io/kernel/doc/host/path/index.html): enforcing correct encoding of [storage paths](https://tezos.gitlab.io/kernel/doc/host/path/trait.Path.html). A storage path can be written to, or read from the kernel - and may correspond to a sequence of bytes in the runtime storage.
- [rollup_core](https://tezos.gitlab.io/kernel/doc/host/rollup_core/index.html): defines the *raw* bindings to the **rollup_safe_core** host module. These can be accessed by a kernel running in safe mode - which prevents the kernel messing up the state tree w.r.t hardware gas limits, and inputs.
- [wasm_host](https://tezos.gitlab.io/kernel/doc/host/wasm_host/index.html): implementation of `RawRollupCore` that used when compiling to wasm.
:::

Example of some use cases of kernel in SCORU at the moment:

:::success
:::spoiler Tx-kernel
A simple kernel with transaction functionality similar to TORUs: https://tezos.gitlab.io/kernel/doc/kernel_core/index.html.
e2e tests covering the top-level behaviour of the transactions kernel: https://gitlab.com/tezos/kernel/-/blob/main/e2e_kernel_tests/tests/tx_kernel.rs.
The milestone of warm kernel transactions: https://gitlab.com/tezos/tezos/-/milestones/86#tab-issues
- [bls](https://tezos.gitlab.io/kernel/doc/kernel_core/bls/index.html): BLS support for the kernel. Provides signature verification and de-serialization for BLS signatures and public keys.
- [deposit](https://tezos.gitlab.io/kernel/doc/kernel_core/deposit/index.html): deposit tickets into the kernel state
- [encoding](https://tezos.gitlab.io/kernel/doc/kernel_core/encoding/index.html): defines tezos-encoding compabible structures.
- [inbox](https://tezos.gitlab.io/kernel/doc/kernel_core/inbox/index.html): types and encoding for the *inbox-half* of the L1/L2 communication protocol. In general, this module is a re-implementation of the tezos protocol [inbox message repr](https://gitlab.com/tezos/tezos/-/blob/9028b797894a5d9db38bc61a20abb793c3778316/src/proto_alpha/lib_protocol/sc_rollup_inbox_message_repr.mli).
- memory: defines operations over kernel memory - persisted in RAM between yields
- [outbox](https://tezos.gitlab.io/kernel/doc/kernel_core/outbox/index.html): types and encodings for the *outbox-half* of the L1/L2 communcation protocol. Similar as inbox, this module is a re-implementation of the tezos-protocol [outbox message repr](https://gitlab.com/tezos/tezos/-/blob/80b2cccb9c663dde2d86a6c94806fc149b7d1ef3/src/proto_alpha/lib_protocol/sc_rollup_outbox_message_repr.ml)
- transactions: transactions kernel core logic for handling messages
- tx_kernel: define the `kernel_next` for the transaction kernel

:::info
:::spoiler Examples of using Host in Tx-kernel
- deposit ticket function: deposits ticket into account. Returns error if amount is negative, or if the amount is greater than it can fit in the account. Where [`Host: RawRollupCore`](https://tezos.gitlab.io/kernel/doc/host/rollup_core/trait.RawRollupCore.html) is defined in `wasm_host.rs`

pub fn deposit_ticket<Host: RawRollupCore>(
    memory: &mut Memory, 
    account_address: Layer2Tz4Hash, 
    ticket: StringTicket
) -> Result<(), DepositError>

- Transactions:
- Function [`transactions_run`](https://tezos.gitlab.io/kernel/doc/src/kernel_core/lib.rs.html#48-70) the entrypoint of the *transactions* kernel (like main function for the tx-kernel). It is where it calls the host modules for the implementation, such as: `input`, `rollup_core`, `runtime`

    pub fn transactions_run<Host: RawRollupCore>(host: &mut Host) {
    ...
        if let Some(input) = host.read_input (MAX_READ_INPUT_SIZE){
        match input {
           Input::Message(message) => {
           ...
           }
           Input::Slot(_message) => todo!
        }
        }
    }

- external inbox: prepare an external message for processing, in a stepwise manner.

    pub fn prepare_for_processing<'a, Host>(
    message: ExternalInboxMessage<'a>, 
    accounts: &mut Accounts
    ) -> Option<impl FnMut(&Accounts) ->
    ProcessedOutcome + 'a> where Host: RawRollupCore, 

- handle withdrawals: send given withdrawals to Layer 1, in an OutboxMessage

    pub fn handle_withdrawals<Host: RawRollupCore>(
        host: &mut Host, 
        memory: &mut Memory, 
        withdrawals: Vec<Withdrawal>
    )

- Using the [`kernel`](https://tezos.gitlab.io/kernel/doc/kernel/index.html): `kernel_entry` macros derive `kernel_next` and `mock_kernel_next` entrypoints.
- [`tx_kernel`](https://tezos.gitlab.io/kernel/doc/kernel_core/tx_kernel/index.html): define the `kernel_next` for the transactions kernel. It defines inside the function `transactions_run` above.
- `kernel_next`: function is called by the wasm host at regular intervals.

        pub fn kernel_next()
        
        #[cfg(feature = "tx-kernel")]
        pub mod tx_kernel {
        use crate::transactions_run;
        use kernel::kernel_entry;
        kernel_entry!(transactions_run);
        }

- `mock_kernel_next`: is called by the [mock_host](https://tezos.gitlab.io/kernel/doc/mock_host/index.html) at regular intervals. Mock runtime provides a host that can used in integration and unit tests. Used when not compiling to wasm.

        pub fn mock_kernel_next(host: &mut MockHost)

:::

:::success
:::spoiler EVM-kernel
https://tezos.gitlab.io/kernel/doc/evm_kernel/index.html. This contains the EVM kernel, this kernel runs EVM contract code emulating Ethereum, but on a rollup.
e2e tests for the EVM-kernel: https://gitlab.com/tezos/kernel/-/blob/main/e2e_kernel_tests/tests/evm_kernel.rs.
The milestone of evm on wasm: https://gitlab.com/tezos/tezos/-/milestones/108#tab-issues
- ethereum: types and functions for Ethereum compapility
- deposit: deposit tickets into the kernel state
- inbox: types and encodings for the *inbox* for the EVM kernel
- memory: defines operations over kernel memory - persisted in RAM between yields
- outbox: types and encodings for the *outbox-half* of the L1/L2 communication protocols
- transactions: handle transactions
- evm_kernel: define the `kernel_next` for the transactions kernel
:::

Details design of kernel in SCORU:
:::info
Execution environment
:::spoiler
- State: the smart rollups have two states
- A transient state: it is reset after each call to the `kernel_next` function and is similar to RAM.
- A persistent state: it is preserved across `kernel_next` calls. It consists: inbox, and outbox, and a durable storage which is similar to a file system.
- A WASM kernel can write/read raw bytes stored under a given path (files). It can also delete/copy/move/etc. with subtrees (directories).
- The value and subtress at key `read_only` are not writable by a kernel, but it can be used by the PVM to give information to the kernel.

- Control Flow:
- WASM kernel has to filter the inputs (the inbox exposed to the smart rollup is populated with all the inputs published on Tezos in this block).
- After the inbox has been populated with the inputs of the Tezos block, the `kernel_next` is called from a "transient state".
- The WASM kernel is parsed, linked, initialized, then `kernel_next` is called.
- By default, `kernel_next` is called only once.
- Host functions:
- The host functions provides an API to the WASM program to interact with an "outer world".
- The host functions exposed to a WASM kernel allow it to interact with the various components of "persistent state":
- read_input
- write_output
- write_debug
- store_has
- store_delete
- store_copy
- store_move
- store_read
- store_write
- store_value_size
- store_list_size
- store_get_nth_key
- reveal_preimage
- reveal_metadata
- These host functions use a "C-like" API, most of them return a signed 32bit integer, where negative values are reserved for conveying errors.
:::

:::info
Implementing a WASM kernel in Rust
:::spoiler
- Setting up Rust
- Host functions in Rust
:::

:::info
Testing the kernel
:::spoiler

:::

:::info
:::spoiler Reference
from this MR: https://gitlab.com/tezos/tezos/-/merge_requests/6629
:::

Some on-going milestones:
:::info
:::spoiler
- EVM on Wasm: run EVM interpreter from kernel: https://gitlab.com/tezos/tezos/-/milestones/108#tab-issues
- Wasm kernel IV: upgrade path https://gitlab.com/tezos/tezos/-/milestones/139#tab-issues
- Wasm kernel V: Beta kernel framework https://gitlab.com/tezos/tezos/-/milestones/140#tab-issues
- SCORU WebAssembly PVM I: https://gitlab.com/tezos/tezos/-/milestones/83#tab-issues
- SCORU wasm kernel (core): https://gitlab.com/tezos/tezos/-/milestones/85#tab-issues: the goal is to create a minimal infrastructure/library for building a wasm kernel in rust. (The bindings APIs rust above).
- Wasm kernel (transactions): https://gitlab.com/tezos/tezos/-/milestones/86#tab-issues: this is a build on SCORU wasm kernel (core) to create a proof-of-concept WASM kernel, able to carry out TORU style exchanges with signature checking.
- Wasm kernel III (DAL integration): https://gitlab.com/tezos/tezos/-/milestones/116#tab-issues: this is a build on the wasm kernel (transactions) to provide integration with the DAL layer for both the `TX_kernel` and future `EVM kernel`

:::spoiler Glossary in SCORU
- message: is a mere sequence of bytes following no particular underlying format. The interpretation of this sequence of bytes is the responsibility of the kernel.
- inbox: is a sequence of messages from the Layer 1 to smart rollups. The contents of the inbox is determined by the consensus of the Tezos protocol.
- outbox: is a sequence of messages from a smart rollup to the Layer 1. Messages are smart contract calls, potentially containing tickets. These calls can be triggered only when the related commitment is cemented (hence, at least two weeks after the actual execution of the operation)
:::