Skip to content

Commit

Permalink
Merge pull request #11 from anton-rs/cl/cannon
Browse files Browse the repository at this point in the history
✨ Updates
  • Loading branch information
clabby authored Dec 20, 2023
2 parents d389c64 + dfe025a commit 8cc4481
Show file tree
Hide file tree
Showing 25 changed files with 479 additions and 134 deletions.
71 changes: 7 additions & 64 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

33 changes: 19 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,17 @@
</h1>

<h4 align="center">
A suite of libraries and build pipelines for developing verifiable Rust programs targeting Fault Proof VMs.
A verifiable implementation of the [Optimism][op-stack] rollup state transition.
</h4>

<p align="center">
<a href="https://github.com/anton-rs/kona/actions/workflows/ci.yaml">
<img src="https://github.com/anton-rs/kona/actions/workflows/ci.yaml/badge.svg?label=ci" alt="Ci">
<img src="https://github.com/anton-rs/kona/actions/workflows/ci.yaml/badge.svg?label=ci" alt="CI">
</a>
<img src="https://img.shields.io/badge/License-MIT-green.svg?label=license" alt="License">
<a href="https://anton-rs.github.io/kona">
<img src="https://img.shields.io/badge/Contributor%20Book-grey?logo=mdBook" alt="Book">
</a>
<a href="https://github.com/ethereum-optimism/monorepo"><img src="https://img.shields.io/badge/OP%20Stack-monorepo-red" alt="OP Stack"></a>
<a href="https://t.me/+2yfSX0YikWMxNTRh"><img src="https://img.shields.io/badge/Telegram-x?logo=telegram&label=anton-rs%20contributors"></a>
</p>
Expand All @@ -25,26 +28,19 @@

## What's Kona?

Kona is a suite of libraries and build pipelines for developing verifiable Rust programs targeting Fault Proof VMs. Currently, Kona seeks to support the following targets:
* [`cannon`][cannon] & [`cannon-rs`][cannon-rs]: A `MIPS32rel1` based Fault Proof VM.
* [`asterisc`][asterisc]: A `RISC-V` based Fault Proof VM.

This repository also contains an implementation of the [`op-program` specification][fpp-specs] in Rust, which is used to validate a claim about the state of an [OP Stack rollup][op-stack] on L1 Ethereum.
Kona is a [fault proof program] designed to execute a rollup state transition and ultimately verify an [L2 output root][g-output-root] from
L1 inputs, derived through the rollup's [derivation pipeline][g-derivation-pipeline].

## Overview

*todo*
*TODO - overview after mockup*

```
crates
├── `common-client`: A suite of utilities for developing `client` programs to be ran on top of Fault Proof VMs.
└── `common-host`: A suite of utilities for developing `host` programs.
├── `common`: A suite of utilities for developing `client` programs to be ran on top of Fault Proof VMs.
└── `placeholder`: Placeholder
```

## Credits

`kona` is inspired by the work of several other teams, namely [OP Labs][op-labs] and other contributors' work on the [`op-program`][op-program] and [BadBoiLabs][bad-boi-labs].

## Book

The [book][book] contains a more in-depth overview of the project, tutorials for getting started with building your own programs, and a reference for the libraries and tools provided by Kona.
Expand All @@ -53,14 +49,23 @@ The [book][book] contains a more in-depth overview of the project, tutorials for

*TODO - write `CONTRIBUTING.md`*

## Credits

`kona` is inspired by the work of several teams, namely [OP Labs][op-labs] and other contributors' work on the [`op-program`][op-program] and [BadBoiLabs][bad-boi-labs]'s work on [Cannon-rs][badboi-cannon-rs].

[op-stack]: https://github.com/ethereum-optimism/optimism
[op-program]: https://github.com/ethereum-optimism/optimism/tree/develop/op-program
[cannon]: https://github.com/ethereum-optimism/optimism/tree/develop/cannon
[cannon-rs]: https://github.com/anton-rs/cannon-rs
[badboi-cannon-rs]: https://github.com/BadBoiLabs/cannon-rs
[asterisc]: https://github.com/protolambda/asterisc
[fpp-specs]: https://github.com/ethereum-optimism/optimism/blob/develop/specs/fault-proof.md#fault-proof-program

[book]: https://anton-rs.github.io/kona/

[op-labs]: https://github.com/ethereum-optimism
[bad-boi-labs]: https://github.com/BadBoiLabs

[g-output-root]: https://github.com/ethereum-optimism/optimism/blob/develop/specs/glossary.md#l2-output-root
[g-derivation-pipeline]: https://github.com/ethereum-optimism/optimism/blob/develop/specs/derivation.md#l2-chain-derivation-pipeline
[g-fault-proof-vm]: https://github.com/ethereum-optimism/optimism/blob/develop/specs/fault-proof.md#fault-proof-vm
Empty file added bin/client/.gitkeep
Empty file.
Empty file added bin/server/.gitkeep
Empty file.
27 changes: 25 additions & 2 deletions book/src/fpp-dev/targets.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,32 @@ for each FPVM target:

| Target | Build Pipeline | IO | malloc | Program Stages |
|------------------------|----------------|----|--------|----------------|
| `cannon` & `cannon-rs` | | | ||
| `asterisc` || | ||
| `cannon` & `cannon-rs` | | | ||
| `asterisc` || | ||

If there is a feature that you would like to see supported, please [open an issue][new-issue] or [consider contributing][contributing]!

## Asterisc (RISC-V)

Asterisc is based off of the `rv64gc` target architecture, which defines the following extensions:
- `RV32I` support - 32 bit base instruction set
- `FENCE`, `ECALL`, `EBREAK` are hardwired to implement a minimal subset of systemcalls of the linux kernel
- Work in progress. All syscalls used by the Golang `risc64` runtime.
- `RV64I` support
- `RV64C`: Compressed instructions
- `RV32M`+`RV64M`: Multiplication support
- `RV32A`+`RV64A`: Atomics support
- `RV{32,64}{D,F,Q}`: no-op: No floating points support (since no IEEE754 determinism with rounding modes etc., nor worth the complexity)
- `Zifencei`: `FENCE.I` no-op: No need for `FENCE.I`
- `Zicsr`: no-op: some support for Control-and-status registers may come later though.
- `Ztso`: no-op: no need for Total Store Ordering
- other: revert with error code on unrecognized instructions

`asterisc` supports a plethora of syscalls, documented [in the repository][asterisc-syscalls]. `kona` offers an interface for
programs to directly invoke several syscalls:
1. `EXIT` - Terminate the process with the provided exit code.
1. `WRITE` - Write the passed buffer to the passed file descriptor.
1. `READ` - Read the specified number of bytes from the passed file descriptor.

[asterisc-syscalls]: https://github.com/protolambda/asterisc
{{#include ../links.md}}
2 changes: 1 addition & 1 deletion book/src/glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
*This document contains definitions for terms used throughout the Kona book.*

#### Fault Proof VM
A `Fault Proof VM` is a virtual machine, commonly supporting a modified subset of an existing reduced instruction set architecture,
A `Fault Proof VM` is a virtual machine, commonly supporting a subset of the Linux kernel's syscalls and a modified subset of an existing reduced instruction set architecture,
that is designed to execute verifiable programs.

Full specification for the `cannon` & `cannon-rs` FPVMs, as an example, is available in the [Optimism Monorepo][cannon-specs].
Expand Down
8 changes: 8 additions & 0 deletions build/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ To build the images, run `make` in the root of this directory.

### Compiling Programs

**cannon**

```
docker run \
--rm \
Expand All @@ -19,4 +21,10 @@ docker run \
cannon-pipeline:latest cargo build --release -Zbuild-std
```

**asterisc**
```
RUSTFLAGS="-Clink-arg=-e_start -C target-feature=-c" \
cargo build --target riscv64gc-unknown-none-elf --release
```

[cross]: https://github.com/cross-rs/cross
Empty file added build/asterisc/.gitkeep
Empty file.
4 changes: 1 addition & 3 deletions build/Makefile → build/justfile
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
all: cannon

.PHONY: cannon
# Build the `cannon` program builder image
cannon:
docker build -t cannon-pipeline:latest -f cannon/cannon.dockerfile ./cannon
4 changes: 2 additions & 2 deletions crates/common/Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[package]
name = "kona-common"
description = "Common traits and utilities for Kona"
description = "Common traits and system interfaces for developing client programs on top of Fault Proof VMs."
version = { workspace = true }
edition = { workspace = true }
authors = { workspace = true }
Expand All @@ -13,5 +13,5 @@ homepage = { workspace = true }
anyhow.workspace = true

# external
num = { version = "0.4.1", default-features = false }
good_memory_allocator = "0.1.7"
cfg-if = "1.0.0"
4 changes: 2 additions & 2 deletions crates/common/README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# `kona-common`
# `kona-client`

A suite of utilities for developing `host` programs and verifiable `client` executables.
A suite of utilities for developing verifiable `client` executables that may run on top of FPVM targets.

*TODO*
54 changes: 54 additions & 0 deletions crates/common/src/asterisc/io.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
use crate::{asterisc::syscall, traits::BasicKernelInterface, types::RegisterSize};
use anyhow::Result;

/// Concrete implementation of the [`KernelIO`] trait for the `riscv64` target architecture.
pub struct AsteriscIO;

/// Relevant system call numbers for the `riscv64` target architecture.
///
/// See https://jborza.com/post/2021-05-11-riscv-linux-syscalls/
///
/// **Note**: This is not an exhaustive list of system calls available to the `client` program,
/// only the ones necessary for the [BasicKernelInterface] trait implementation. If an extension trait for
/// the [BasicKernelInterface] trait is created for the `asterisc` kernel, this list should be extended
/// accordingly.
#[repr(u32)]
pub enum SyscallNumber {
/// Sets the Exited and ExitCode states to true and $a0 respectively.
Exit = 93,
/// Similar behavior as Linux with support for unaligned reads.
Read = 63,
/// Similar behavior as Linux with support for unaligned writes.
Write = 64,
}

impl BasicKernelInterface for AsteriscIO {
fn write(fd: Self::FileDescriptor, buf: &[u8]) -> Result<RegisterSize> {
unsafe {
Ok(syscall::syscall3(
SyscallNumber::Write as usize,
fd as usize,
buf.as_ptr() as usize,
buf.len() as usize,
) as RegisterSize)
}
}

fn read(fd: Self::FileDescriptor, buf: &mut [u8]) -> Result<RegisterSize> {
unsafe {
Ok(syscall::syscall3(
SyscallNumber::Read as usize,
fd as usize,
buf.as_ptr() as usize,
buf.len() as usize,
) as RegisterSize)
}
}

fn exit(code: RegisterSize) -> ! {
unsafe {
syscall::syscall1(SyscallNumber::Exit as usize, code as usize);
panic!()
}
}
}
4 changes: 4 additions & 0 deletions crates/common/src/asterisc/mod.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
//! TODO
pub mod io;
mod syscall;
44 changes: 44 additions & 0 deletions crates/common/src/asterisc/syscall.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
//! Unsafe system call interface for the `riscv64` target architecture.
//!
//! List of RISC-V system calls: https://jborza.com/post/2021-05-11-riscv-linux-syscalls/
//!
//! **Registers used for system calls**
//! | Register Number | Description |
//! |=================|====================|
//! | %a0 | arg1, return value |
//! | %a1 | arg2 |
//! | %a2 | arg3 |
//! | %a3 | arg4 |
//! | %a4 | arg5 |
//! | %a5 | arg6 |
//! | %a7 | syscall number |
use core::arch::asm;

/// Issues a raw system call with 1 argument. (e.g. exit)
#[inline]
pub unsafe fn syscall1(syscall_number: usize, arg1: usize) -> usize {
let mut ret: usize;
asm!(
"ecall",
in("a7") syscall_number,
inlateout("a0") arg1 => ret,
options(nostack, preserves_flags)
);
ret
}

/// Issues a raw system call with 3 arguments. (e.g. read, write)
#[inline]
pub unsafe fn syscall3(syscall_number: usize, arg1: usize, arg2: usize, arg3: usize) -> usize {
let mut ret: usize;
asm!(
"ecall",
in("a7") syscall_number,
inlateout("a0") arg1 => ret,
in("a1") arg2,
in("a2") arg3,
options(nostack, preserves_flags)
);
ret
}
Loading

0 comments on commit 8cc4481

Please sign in to comment.