Merge pull request #5 from anton-rs/cl/book-intro

feat(book): Add intro section to book

.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

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
+```

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"]

book/src/SUMMARY.md

@@ -1,3 +1,4 @@
 # Summary
 
-- [Introduction](./introduction.md)
+- [Introduction](./intro.md)
+- [Glossary](./glossary.md)

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}}

book/src/intro.md

@@ -0,0 +1,56 @@
+# Kona Book
+
+*Documentation for the Kona project.*
+
+<a href="https://github.com/kona-rs/kona"><img src="https://img.shields.io/badge/GitHub%20Repo-kona-green?logo=github"></a>
+<a href="https://t.me/+2yfSX0YikWMxNTRh"><img src="https://img.shields.io/badge/Telegram-x?logo=telegram&label=anton-rs%20contributors"></a>
+
+> 📖 `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}}

book/static/links.md

@@ -0,0 +1,18 @@
+<!-- External -->
+[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
+
+<!-- Kona links -->
+[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
+
+<!-- People -->
+[op-labs]: https://github.com/ethereum-optimism
+[bad-boi-labs]: https://github.com/BadBoiLabs

book/templates/glossary-link.md

@@ -0,0 +1 @@
+[[[ #text ]]]([[ #root ]]glossary.md#[[ #ref ]])