anton-rs · refcell · Sep 23, 2024 · Sep 22, 2024 · Sep 23, 2024 · Sep 23, 2024
@@ -28,6 +28,16 @@ the block execution logic.
 Built on top of these libraries, this repository also features a [fault proof program][fpp-specs] designed to deterministically execute the
 rollup state transition in order to verify an [L2 output root][g-output-root] from the L1 inputs it was [derived from][g-derivation-pipeline].
 
+### Alternative Backends
+
+Kona's libraries were built with alternative backend support and extensibility in mind - it is not just a fault proof 
+program! Kona is also used by:
+
+- [`op-succinct`][op-succinct]
+
+To build your own backend for kona, or build a new application on top of its libraries,
+see the [SDK section of the book](https://anton-rs.github.io/kona/sdk/intro.html).
+
 ### Development Status
 
 `kona` is currently in active development, and is not yet ready for use in production.
@@ -70,6 +80,7 @@ The [book][book] contains a more in-depth overview of the project, contributor g
 [asterisc]: https://github.com/etheruem-optimism/asterisc
 [fpp-specs]: https://specs.optimism.io/experimental/fault-proof/index.html
 [book]: https://anton-rs.github.io/kona/
+[op-succinct]: https://github.com/succinctlabs/op-succinct
 [op-labs]: https://github.com/ethereum-optimism
 [bad-boi-labs]: https://github.com/BadBoiLabs
 [g-output-root]: https://specs.optimism.io/glossary.html#l2-output-root

@@ -11,4 +11,9 @@ command = "mdbook-mermaid"
 [preprocessor.template]
 
 [output.html]
+default-theme = "ferra"
+preferred-dark-theme = "ferra"
+git-repository-url = "https://github.com/anton-rs/kona"
+edit-url-template = "https://github.com/anton-rs/kona/edit/main/book/{path}"
+additional-css = ["custom.css"]
 additional-js = ["mermaid.min.js", "mermaid-init.js"]
@@ -0,0 +1,141 @@
+table {
+    width: 100%;
+}
+
+table thead th {
+    padding: .75rem;
+    text-align: left;
+    font-weight: 500;
+    line-height: 1.5;
+    width: auto;
+}
+
+table td {
+    padding: .75rem;
+    border: none;
+}
+
+table thead tr {
+    border: none;
+    border-bottom: 2px var(--table-border-color) solid;
+}
+
+table tbody tr {
+    border-bottom: 1px var(--table-border-line) solid;
+}
+
+table tbody tr:nth-child(2n) {
+    background: unset;
+}
+
+.content h1,
+.content h2,
+.content h3,
+.content h4 {
+    font-weight: 600;
+    margin-top: 1.275em;
+    margin-bottom: .875em;
+}
+
+.ferra {
+    --bg: #2b292d;
+    --fg: #fecdb2;
+    --heading-fg: #fff;
+
+    --sidebar-bg: #383539;
+    --sidebar-fg: #fecdb2;
+    --sidebar-non-existant: #feceb454;
+    --sidebar-active: #ffa07a;
+    --scrollbar: var(--sidebar-fg);
+
+    --icons: #f6b6c9ba;
+    --icons-hover: #b7b9cc;
+
+    --links: #ffa07a;
+
+    --inline-code-color: #f6b6c9ba;
+
+    --theme-popup-bg: #383539;
+    --theme-popup-border: #5f5a60;
+    --theme-hover: rgba(0, 0, 0, .2);
+
+    --quote-bg: #222124;
+    --quote-border: #2b292d;
+
+    --table-border-color: #383539;
+    --table-header-bg: hsla(226, 23%, 31%, 0);
+    --table-alternate-bg: hsl(226, 23%, 14%);
+    --table-border-line: #383539;
+
+    --searchbar-border-color: #222124;
+    --searchbar-bg: #222124;
+    --searchbar-fg: #fecdb2;
+    --searchbar-shadow-color: #aaa;
+    --searchresults-header-fg: #fce2d4;
+    --searchresults-border-color: #feceb454;
+    --search-mark-bg: #f6b6c9ba;
+
+}
+
+.ferra .content .header {
+    color: #fce2d4;
+}
+
+/* highlight.js theme, :where() is used to avoid increasing specificity */
+
+:where(.ferra) .hljs {
+    background: #222124;
+    color: #feceb4e1;
+}
+
+:where(.ferra) .hljs-comment,
+:where(.ferra) .hljs-quote {
+    color: #6F5D63;
+}
+
+:where(.ferra) .hljs-link,
+:where(.ferra) .hljs-meta,
+:where(.ferra) .hljs-name,
+:where(.ferra) .hljs-regexp,
+:where(.ferra) .hljs-selector-class,
+:where(.ferra) .hljs-selector-id,
+:where(.ferra) .hljs-tag,
+:where(.ferra) .hljs-template-variable,
+:where(.ferra) .hljs-variable {
+    color: #fecdb2;
+}
+
+:where(.ferra) .hljs-built_in,
+:where(.ferra) .hljs-deletion,
+:where(.ferra) .hljs-literal,
+:where(.ferra) .hljs-number,
+:where(.ferra) .hljs-params,
+:where(.ferra) .hljs-type {
+    color: #f6b6c9;
+}
+
+:where(.ferra) .hljs-attribute,
+:where(.ferra) .hljs-section,
+:where(.ferra) .hljs-title {
+    color: #ffa07a;
+}
+
+:where(.ferra) .hljs-addition,
+:where(.ferra) .hljs-bullet,
+:where(.ferra) .hljs-string,
+:where(.ferra) .hljs-symbol {
+    color: #b1b695;
+}
+
+:where(.ferra) .hljs-keyword,
+:where(.ferra) .hljs-selector-tag {
+    color: #d1d1e0;
+}
+
+:where(.ferra) .hljs-emphasis {
+    font-style: italic;
+}
+
+:where(.ferra) .hljs-strong {
+    font-weight: 700;
+}
@@ -1,7 +1,7 @@
 # Contributing
 
 Thank you for wanting to contribute! Before contributing to this repository, please read through this document and
-discuss the change you wish to make via issue or in the development telegram.
+discuss the change you wish to make via issue.
 
 ## Dependencies
 

@@ -7,5 +7,9 @@
   - [Prologue](./fpp-dev/prologue.md)
   - [Execution](./fpp-dev/execution.md)
   - [Epilogue](./fpp-dev/epilogue.md)
+- [Kona SDK](./sdk/intro.md)
+  - [FPVM Backend](./sdk/fpvm-backend.md)
+  - [Custom Backend](./sdk/custom-backend.md)
+  - [`kona-executor` Extensions](./sdk/exec-ext.md)
 - [Glossary](./glossary.md)
 - [Contributing](./CONTRIBUTING.md)
@@ -28,9 +28,9 @@ when the `host` is the native implementation of the FPVM.
 ```mermaid
 sequenceDiagram
     Client->>+Host: Hint preimage (no-op on-chain / read-only mode)
-    Host-->>Host: Prepare Preimage
     Host-->>-Client: Hint acknowledgement
     Client-->>+Host: Preimage Request
+    Host-->>Host: Prepare Preimage
     Host-->>-Client: Preimage Data
 ```
 

@@ -3,95 +3,13 @@
 Kona seeks to support all FPVM targets that LLVM and `rustc` can offer introductory support for. Below is a matrix of features that Kona offers
 for each FPVM target:
 
-| Target                 | Build Pipeline | IO  | malloc | Program Stages |
-| ---------------------- | -------------- | --- | ------ | -------------- |
-| `cannon` & `cannon-rs` | ✅             | ✅  | ✅     | ❌             |
-| `asterisc`             | ✅             | ✅  | ✅     | ❌             |
+| Target                 | Build Pipeline | IO  | malloc |
+| ---------------------- | -------------- | --- | ------ |
+| `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]!
 
-## Cannon (MIPS32r2)
-
-Cannon is based off of the `mips32r2` target architecture, supporting 55 instructions:
-
-| Category             | Instruction | Description                               |
-| -------------------- | ----------- | ----------------------------------------- |
-| `Arithmetic`         | `addi`      | Add immediate (with sign-extension).      |
-| `Arithmetic`         | `addiu`     | Add immediate unsigned (no overflow).     |
-| `Arithmetic`         | `addu`      | Add unsigned (no overflow).               |
-| `Logical`            | `and`       | Bitwise AND.                              |
-| `Logical`            | `andi`      | Bitwise AND immediate.                    |
-| `Branch`             | `b`         | Unconditional branch.                     |
-| `Conditional Branch` | `beq`       | Branch on equal.                          |
-| `Conditional Branch` | `beqz`      | Branch if equal to zero.                  |
-| `Conditional Branch` | `bgez`      | Branch on greater than or equal to zero.  |
-| `Conditional Branch` | `bgtz`      | Branch on greater than zero.              |
-| `Conditional Branch` | `blez`      | Branch on less than or equal to zero.     |
-| `Conditional Branch` | `bltz`      | Branch on less than zero.                 |
-| `Conditional Branch` | `bne`       | Branch on not equal.                      |
-| `Conditional Branch` | `bnez`      | Branch if not equal to zero.              |
-| `Logical`            | `clz`       | Count leading zeros.                      |
-| `Arithmetic`         | `divu`      | Divide unsigned.                          |
-| `Unconditional Jump` | `j`         | Jump.                                     |
-| `Unconditional Jump` | `jal`       | Jump and link.                            |
-| `Unconditional Jump` | `jalr`      | Jump and link register.                   |
-| `Unconditional Jump` | `jr`        | Jump register.                            |
-| `Data Transfer`      | `lb`        | Load byte.                                |
-| `Data Transfer`      | `lbu`       | Load byte unsigned.                       |
-| `Data Transfer`      | `lui`       | Load upper immediate.                     |
-| `Data Transfer`      | `lw`        | Load word.                                |
-| `Data Transfer`      | `lwr`       | Load word right.                          |
-| `Data Transfer`      | `mfhi`      | Move from HI register.                    |
-| `Data Transfer`      | `mflo`      | Move from LO register.                    |
-| `Data Transfer`      | `move`      | Move between registers.                   |
-| `Data Transfer`      | `movn`      | Move conditional on not zero.             |
-| `Data Transfer`      | `movz`      | Move conditional on zero.                 |
-| `Data Transfer`      | `mtlo`      | Move to LO register.                      |
-| `Arithmetic`         | `mul`       | Multiply (to produce a word result).      |
-| `Arithmetic`         | `multu`     | Multiply unsigned.                        |
-| `Arithmetic`         | `negu`      | Negate unsigned.                          |
-| `No Op`              | `nop`       | No operation.                             |
-| `Logical`            | `not`       | Bitwise NOT (pseudo-instruction in MIPS). |
-| `Logical`            | `or`        | Bitwise OR.                               |
-| `Logical`            | `ori`       | Bitwise OR immediate.                     |
-| `Data Transfer`      | `sb`        | Store byte.                               |
-| `Logical`            | `sll`       | Shift left logical.                       |
-| `Logical`            | `sllv`      | Shift left logical variable.              |
-| `Comparison`         | `slt`       | Set on less than (signed).                |
-| `Comparison`         | `slti`      | Set on less than immediate.               |
-| `Comparison`         | `sltiu`     | Set on less than immediate unsigned.      |
-| `Comparison`         | `sltu`      | Set on less than unsigned.                |
-| `Logical`            | `sra`       | Shift right arithmetic.                   |
-| `Logical`            | `srl`       | Shift right logical.                      |
-| `Logical`            | `srlv`      | Shift right logical variable.             |
-| `Arithmetic`         | `subu`      | Subtract unsigned.                        |
-| `Data Transfer`      | `sw`        | Store word.                               |
-| `Data Transfer`      | `swr`       | Store word right.                         |
-| `Serialization`      | `sync`      | Synchronize shared memory.                |
-| `System Calls`       | `syscall`   | System call.                              |
-| `Logical`            | `xor`       | Bitwise XOR.                              |
-| `Logical`            | `xori`      | Bitwise XOR immediate.                    |
-
-### Syscalls
-
-| \$v0 | system call | \$a0            | \$a1       | \$a2         | Effect                                                                                                               |
-| ---- | ----------- | --------------- | ---------- | ------------ | -------------------------------------------------------------------------------------------------------------------- |
-| 4090 | mmap        | uint32 addr     | uint32 len | 🚫           | Allocates a page from the heap. See [heap](#heap) for details.                                                       |
-| 4045 | brk         | 🚫              | 🚫         | 🚫           | Returns a fixed address for the program break at `0x40000000`                                                        |
-| 4120 | clone       | 🚫              | 🚫         | 🚫           | Returns 1                                                                                                            |
-| 4246 | exit_group  | uint8 exit_code | 🚫         | 🚫           | Sets the Exited and ExitCode states to `true` and `$a0` respectively.                                                |
-| 4003 | read        | uint32 fd       | char \*buf | uint32 count | Similar behavior as Linux/MIPS with support for unaligned reads. See [I/O](#io) for more details.                    |
-| 4004 | write       | uint32 fd       | char \*buf | uint32 count | Similar behavior as Linux/MIPS with support for unaligned writes. See [I/O](#io) for more details.                   |
-| 4055 | fcntl       | uint32 fd       | int32 cmd  | 🚫           | Similar behavior as Linux/MIPS. Only the `F_GETFL` (3) cmd is supported. Sets errno to `0x16` for all other commands |
-
-For all of the above syscalls, an error is indicated by setting the return
-register (`$v0`) to `0xFFFFFFFF` (-1) and `errno` (`$a3`) is set accordingly.
-The VM must not modify any register other than `$v0` and `$a3` during syscall handling.
-For unsupported syscalls, the VM must do nothing except to zero out the syscall return (`$v0`)
-and errno (`$a3`) registers.
-
-Note that the above syscalls have identical syscall numbers and ABIs as Linux/MIPS.
-
 ## Asterisc (RISC-V)
 
 Asterisc is based off of the `rv64gc` target architecture, which defines the following extensions:
@@ -100,7 +18,6 @@ Asterisc is based off of the `rv64gc` target architecture, which defines the fol
   - `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)
@@ -116,6 +33,16 @@ programs to directly invoke a select few syscalls:
 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/ethereum-optimism/asterisc
+[asterisc-syscalls]: https://github.com/ethereum-optimism/asterisc/blob/master/docs/golang.md#linux-syscalls-used-by-go
+
+## Cannon (MIPS32r2)
+
+Cannon is based off of the `mips32r2` target architecture, specified in [_MIPS32™ Architecture For Programmers Volume III: The MIPS32™ Privileged Resource Architecture_](https://www.cs.cornell.edu/courses/cs3410/2013sp/MIPS_Vol3.pdf)
+
+### Syscalls
+
+Syscalls supported by `cannon` can be found within the `cannon` specification [here][cannon-syscalls].
+
+[cannon-syscalls]: https://specs.optimism.io/fault-proof/cannon-fault-proof-vm.html#syscalls
 
 {{#include ../links.md}}
@@ -2,7 +2,7 @@
 
 _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://github.com/anton-rs/kona"><img src="https://img.shields.io/badge/GitHub%20Repo-kona-green?logo=github"></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.
 >

@@ -10,6 +10,8 @@
 [preimage-specs]: https://specs.optimism.io/experimental/fault-proof/index.html#pre-image-oracle
 [cannon-specs]: https://specs.optimism.io/experimental/fault-proof/cannon-fault-proof-vm.html#cannon-fault-proof-virtual-machine
 [l2-output-root]: https://specs.optimism.io/protocol/proposals.html#l2-output-commitment-construction
+[op-succinct]: https://github.com/succinctlabs/op-succinct
+[revm]: https://github.com/bluealloy/revm
 
 <!-- Kona links -->