Merge pull request #7 from anton-rs/cl/book-fpp

feat(book): FPP Introduction

book/src/SUMMARY.md

@@ -1,4 +1,9 @@
 # Summary
 
 - [Introduction](./intro.md)
+- [Fault Proof Program Development](./fpp-dev/intro.md)
+    - [Environment](./fpp-dev/env.md)
+    - [Prologue](./fpp-dev/prologue.md)
+    - [Execution](./fpp-dev/execution.md)
+    - [Epilogue](./fpp-dev/epilogue.md)
 - [Glossary](./glossary.md)

book/src/fpp-dev/env.md

@@ -0,0 +1,57 @@
+# Environment
+
+Before kicking off the development of your own {{#template ../../templates/glossary-link.md root=../ text=Fault Proof Program ref=fault-proof-program}},
+it's important to understand the environment that your program will be running in.
+
+The FPP runs on top of a custom FPVM target, which is typically a VM with a modified subset of an existing reduced instruction set architecture. The FPVM is designed to
+execute verifiable programs, and commonly modifies the instruction set it is derived from as well as the internal representation of memory to support verifiable memory access, `client` (program)
+communication with the `host` (the FPVM), and other implementation-specific features.
+
+## Host <-> Client Communication
+While the program is running on top of the FPVM, it is considered to be in the `client` role, while the VM is in the `host` role. The only way for the `client` and `host`
+to communicate with one another is synchronously through the {{#template ../../templates/glossary-link.md root=../ text=Preimage ABI ref=preimage-abi}} ([specification][preimage-specs]).
+
+In order for the `client` to read from the `host`, special syscalls are modified within the FPVM to allow the `client` to request preparation of and read foreign data.
+
+### Reading
+When the `client` wants to read data from the `host`, it must first send a "hint" to the `host` through the hint file descriptor, which is a request for the `host` to prepare the data for reading. The `host` will then
+prepare the data, and send a hint acknowledgement back to the `client`. The `client` can then read the data from the host through the designated file descriptor.
+
+The preparation step ("hinting") is an optimization that allows the `host` to know ahead of time the intents of the `client` and the data it requires for execution. This can allow
+for lazy loading of data, and also prevent the need for unnecessary allocations within the `host`'s memory. This step is a no-op on-chain, and is only ran locally
+when the `host` is the native implementation of the FPVM.
+
+<center>
+
+```mermaid
+sequenceDiagram
+    Client->>+Host: Hint preimage (no-op on-chain / read-only mode)
+    Host-->>Host: Prepare Preimage
+    Host-->>-Client: Hint acknowledgement
+    Client-->>+Host: Preimage Read
+    Host-->>-Client: Preimage Data
+```
+</center>
+
+## Full Example
+
+Below, we have a full architecture diagram of the [`op-program`][op-program] (source: [fault proof specs][fp-specs]), the reference implementation for the OP Stack's Fault Proof Program,
+which has the objective of verifying claims about the state of an [OP Stack][op-stack] layer two.
+
+<img src="../../../static/op-program-fpp.svg">
+
+In this program, execution and derivation of the L2 chain is performed within it, and ultimately the claimed state of the L2 chain is verified in the [prologue](../prologue.md) stage.
+
+It communicates with the `host` for two reasons:
+1. To request preparation of L1 and L2 state data preimages.
+1. To read the L1 and L2 state data preimages that were prepared after the above requests.
+
+The `host` is responsible for:
+1. Preparing and maintaining a store of the L1 and L2 state data preimages, as well as localized bootstrap k/v pairs.
+1. Providing the L1 and L2 state data preimages to the `client` for reading.
+
+Other programs (`clients`) may have different requirements for communication with the `host`, but the above is a common pattern for programs built on top of a FPVMs. In general:
+1. The `client` program is a state machine that is responsible for bootstrapping itself from the inputs, executing the progam logic, and verifying the outcome.
+1. The `host` is responsible for providing the `client` with data it wasn't bootstrapped with, and for executing the program itself.
+
+{{#include ../static/links.md}}

book/src/fpp-dev/epilogue.md

@@ -0,0 +1 @@
+# Epilogue

book/src/fpp-dev/execution.md

@@ -0,0 +1 @@
+# Execution

book/src/fpp-dev/intro.md

@@ -0,0 +1,20 @@
+# Fault Proof Program Development
+
+This chapter provides an overview of {{#template ../../templates/glossary-link.md root=../ text=Fault Proof Program ref=fault-proof-program}} development
+on top of the custom FPVM targets supported by [Kona][kona].
+
+At a high level, a Fault Proof Program is not much different from a regular `no_std` Rust program. A custom entrypoint is provided, and the program
+is compiled down to a custom target, which is then executed on the FPVM.
+
+Fault Proof Programs are structured with 3 stages:
+1. **Prologue**: The bootstrapping stage, where the program is loaded into memory and the initial state is set up. During this phase, the program's initial
+    state is written to the FPVM's memory, and the program's entrypoint is set.
+1. **Execution**: The main execution stage, where the program is executed on the FPVM. During this phase, the program's entrypoint is called, and the
+    program is executed until it exits.
+1. **Epilogue**: The finalization stage, where the program's final state is read from the FPVM's memory. During this phase, the program's final state is
+    inspected and properties of the state transition are verified.
+
+The following sections will provide a more in-depth overview of each of these stages, as well as the tools and abstractions provided by Kona for
+developing your own Fault Proof Programs.
+
+{{#include ../static/links.md}}

book/src/fpp-dev/io.md

@@ -0,0 +1 @@
+# IO

book/src/fpp-dev/prologue.md

@@ -0,0 +1 @@
+# Prologue

book/src/glossary.md

@@ -15,4 +15,8 @@ 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}}
+#### Preimage ABI
+The `Preimage ABI` is a specification for a synchronous communication protocol between a `client` and a `host` that is used to request and read data from the `host`'s
+datastore. Full specifications for the `Preimage ABI` are available in the [Optimism Monorepo][preimage-specs].
+
+{{#include ./static/links.md}}

book/src/intro.md

@@ -53,4 +53,4 @@ for optimizing performance-critical code.
 
 Contributors are welcome! Please see the [contributing guide][contributing] for more information.
 
-{{#include ../static/links.md}}
+{{#include ./static/links.md}}

book/static/links.md → book/src/static/links.md

@@ -4,10 +4,13 @@
 [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
+[fp-specs]: https://github.com/ethereum-optimism/optimism/blob/develop/specs/fault-proof.md
 [fpp-specs]: https://github.com/ethereum-optimism/optimism/blob/develop/specs/fault-proof.md#fault-proof-program
+[preimage-specs]: https://github.com/ethereum-optimism/optimism/blob/develop/specs/fault-proof.md#pre-image-oracle
 [cannon-specs]: https://github.com/ethereum-optimism/optimism/blob/develop/specs/cannon-fault-proof-vm.md
 
 <!-- Kona links -->
+[kona]: https://github.com/anton-rs/kona
 [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