diff --git a/.github/workflows/book.yaml b/.github/workflows/book.yaml index ed6444bb4..77252c490 100644 --- a/.github/workflows/book.yaml +++ b/.github/workflows/book.yaml @@ -22,6 +22,11 @@ jobs: uses: magicgh/mdbook-mermaid-action@v1 with: version: 'latest' + - name: Install mdbook-template + run: | + mkdir mdbook-template + curl -sSL https://github.com/sgoudham/mdbook-template/releases/latest/download/mdbook-template-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook-template + echo `pwd`/mdbook-template >> $GITHUB_PATH - name: Build book working-directory: ./book run: mdbook build diff --git a/book/README.md b/book/README.md new file mode 100644 index 000000000..0269e8d68 --- /dev/null +++ b/book/README.md @@ -0,0 +1,15 @@ +# `kona-book` + +This repository contains the source code for the Kona book, which is available at [anton-rs.github.io/kona](https://anton-rs.github.io/kona/). + +## Contributing + +To build the book locally, a few dependencies are required: +```sh +cargo install mdbook mdbook-mermaid mdbook-template +``` + +Then, to run the book locally during development, run: +```sh +mdbook serve +``` diff --git a/book/book.toml b/book/book.toml index b0b30c158..c2002cc2a 100644 --- a/book/book.toml +++ b/book/book.toml @@ -8,5 +8,7 @@ title = "The Kona Book" [preprocessor.mermaid] command = "mdbook-mermaid" +[preprocessor.template] + [output.html] additional-js = ["mermaid.min.js", "mermaid-init.js"] diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index e0ff9f902..9bde9769c 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -1,3 +1,4 @@ # Summary -- [Introduction](./introduction.md) +- [Introduction](./intro.md) +- [Glossary](./glossary.md) diff --git a/book/src/glossary.md b/book/src/glossary.md new file mode 100644 index 000000000..7bed188a7 --- /dev/null +++ b/book/src/glossary.md @@ -0,0 +1,18 @@ +# Glossary + +*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, +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]. + +#### Fault Proof Program +A `Fault Proof Program` is a program, commonly written in a general purpose language such as Golang, C, or Rust, that may be compiled down +to a compatible `Fault Proof VM` target and provably executed on that target VM. + +Examples of `Fault Proof Programs` include the [OP Program][op-program], which runs on top of [`cannon`][cannon], [`cannon-rs`][cannon-rs], and +[`asterisc`][asterisc] to verify a claim about the state of an [OP Stack][op-stack] layer two. + +{{#include ../static/links.md}} diff --git a/book/src/intro.md b/book/src/intro.md new file mode 100644 index 000000000..3853c8126 --- /dev/null +++ b/book/src/intro.md @@ -0,0 +1,56 @@ +# Kona Book + +*Documentation for the Kona project.* + + + + +> 📖 `kona` is in active development, and is not yet ready for use in production. During development, this book will evolve quickly and may contain inaccuracies. +> +> Please [open an issue][new-issue] if you find any errors or have any suggestions for improvements, and also feel free to [contribute][contributing] to the project! + +## Introduction + +Kona is a suite of libraries and build pipelines for developing verifiable Rust programs targeting +{{#template ../templates/glossary-link.md root=./ ref=fault-proof-vm text=Fault Proof VMs}}. + +It is built and maintained by members of [OP Labs][op-labs] as well as open source contributors, and is licensed under the MIT License. + +Kona provides tooling and abstractions around low-level syscalls, memory management, and other common structures that authors of verifiable programs +will need to interact with. It also provides build pipelines for compiling `no_std` Rust programs to a format that can be executed by supported +Fault Proof VM targets. + +## Goals of Kona + +**1. Composability** + +Kona provides a common set of tools and abstractions for developing verifiable Rust programs on top of several supported Fault Proof VM targets. This is done +to ensure that programs written for one supported FPVM can be easily ported to another supported FPVM, and that the ecosystem of programs built on top of these targets +can be easily shared and reused. + +**2. Safety** + +Through standardization of these low-level system interfaces and build pipelines, Kona seeks to increase coverage over the low-level operations that are +required to build on top of a FPVM. + +**3. Developer Experience** + +Building on top of custom Rust targets can be difficult, especially when the target is nascent and tooling is not yet mature. Kona seeks to improve this +experience by standardizing and streamlining the process of developing and compiling verifiable Rust programs, targeted at supported FPVMs. + +**4. Performance** + +Kona is opinionated in that it favors `no_std` Rust programs for embedded FPVM development, for both performance and portability. In contrast with alternative approaches, such +as the [`op-program`][op-program] using the Golang `MIPS32` target, `no_std` Rust programs produce much smaller binaries, resulting in fewer instructions +that need to be executed on the FPVM. In addition, this offers developers more low-level control over interactions with the FPVM kernel, which can be useful +for optimizing performance-critical code. + +## Development Status + +**Kona is currently in active development, and is not yet ready for use in production.** + +## Contributing + +Contributors are welcome! Please see the [contributing guide][contributing] for more information. + +{{#include ../static/links.md}} diff --git a/book/static/links.md b/book/static/links.md new file mode 100644 index 000000000..87f670a44 --- /dev/null +++ b/book/static/links.md @@ -0,0 +1,18 @@ + +[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 +[asterisc]: https://github.com/protolambda/asterisc +[fpp-specs]: https://github.com/ethereum-optimism/optimism/blob/develop/specs/fault-proof.md#fault-proof-program +[cannon-specs]: https://github.com/ethereum-optimism/optimism/blob/develop/specs/cannon-fault-proof-vm.md + + +[book]: https://anton-rs.github.io/kona/ +[issues]: https://github.com/anton-rs/kona/issues +[new-issue]: https://github.com/anton-rs/kona/issues/new +[contributing]: https://github.com/anton-rs/kona/tree/main/CONTRIBUTING.md + + +[op-labs]: https://github.com/ethereum-optimism +[bad-boi-labs]: https://github.com/BadBoiLabs diff --git a/book/templates/glossary-link.md b/book/templates/glossary-link.md new file mode 100644 index 000000000..560fcf252 --- /dev/null +++ b/book/templates/glossary-link.md @@ -0,0 +1 @@ +[[[ #text ]]]([[ #root ]]glossary.md#[[ #ref ]])