feat(book): Add minimal program stage documentation (#202)

* feat(book): Add minimal program stage documentation ## Overview Adds some documentation for each program stage in the [book](https://static.optimism.io/kona). * Update book/src/fpp-dev/epilogue.md Co-authored-by: refcell <[email protected]> --------- Co-authored-by: refcell <[email protected]>
op-rs · Jun 4, 2024 · f19efaf · f19efaf
1 parent 3b6c4d8
commit f19efaf
Show file tree

Hide file tree

Showing 5 changed files with 56 additions and 6 deletions.
diff --git a/book/src/fpp-dev/epilogue.md b/book/src/fpp-dev/epilogue.md
@@ -1,3 +1,16 @@
 # Epilogue
 
-_TODO_
+The epilogue stage of the program is intended to perform the final validation on the outputs from the
+[execution phase](./execution.md). In most programs, this entails comparing the outputs of the execution phase
+to portions of the bootstrap data made available during the [prologue phase](./prologue.md).
+
+Generally, this phase should consist almost entirely of validation steps.
+
+## Example
+
+In the `kona-client` program, the prologue phase only contains two directives:
+
+1. Validate that the L2 safe chain could be produced at the claimed L2 block height.
+1. The constructed output root is equivalent to the claimed [L2 output root][l2-output-root].
+
+{{#include ../links.md}}
diff --git a/book/src/fpp-dev/execution.md b/book/src/fpp-dev/execution.md
@@ -1,3 +1,20 @@
 # Execution
 
-_TODO_
+The execution phase of the program is commonly the heaviest portion of the fault proof program, where the computation
+that is being verified is performed.
+
+This phase consumes the outputs of the [prologue phase](./prologue.md), and performs the bulk of the verifiable
+computation. After execution has concluded, the outputs are passed along to the [epilogue phase](./epilogue.md) for
+final verification.
+
+## Example
+
+At a high-level, in the `kona-client` program, the execution phase:
+
+1. Derives the inputs to the L2 derivation pipeline by unrolling the L1 head hash fetched in the epilogue.
+1. Passes the inputs to the L2 derivation pipeline, producing the L2 execution payloads required to reproduce
+   the L2 safe chain at the claimed height.
+1. Executes the payloads produced by the L2 derivation pipeline, producing the [L2 output root][l2-output-root] at the
+   L2 claim height.
+
+{{#include ../links.md}}
diff --git a/book/src/fpp-dev/prologue.md b/book/src/fpp-dev/prologue.md
@@ -1,3 +1,23 @@
 # Prologue
 
-_TODO_
+The prologue stage of the program is commonly responsible for bootstrapping the program with inputs from an external
+source, pulled in through the [Host <-> Client communication](./env.md#host---client-communication) implementation.
+
+As a rule of thumb, the prologue implementation should be kept minimal, and should not do much more than establish
+the inputs for the [execution phase](./execution.md).
+
+## Example
+
+As an example, the prologue stage of the `kona-client` program runs through several steps:
+
+1. Pull in the boot information over the [Preimage Oracle ABI][preimage-specs], containing:
+   - The L1 head hash containing all data required to reproduce the L2 safe chain at the claimed block height.
+   - The latest finalized [L2 output root][l2-output-root].
+   - The [L2 output root][l2-output-root] claim.
+   - The block number of the [L2 output root][l2-output-root] claim.
+   - The L2 chain ID.
+1. Pull in the `RollupConfig` and `L2ChainConfig` corresponding to the passed L2 chain ID.
+1. Validate these values.
+1. Pass the boot information to the execution phase.
+
+{{#include ../links.md}}
diff --git a/book/src/intro.md b/book/src/intro.md
@@ -1,9 +1,8 @@
 # Kona Book
 
-*Documentation for the Kona project.*
+_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.
 >
@@ -14,7 +13,7 @@
 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. 
+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

diff --git a/book/src/links.md b/book/src/links.md
@@ -9,6 +9,7 @@
 [fpp-specs]: https://specs.optimism.io/experimental/fault-proof/index.html#fault-proof-program
 [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
 
 <!-- Kona links -->