feat(workspace): Client programs in workspace

Moves the client programs into the workspace, by using custom build
profiles in the virtual workspace for the client binaries.

This change will allow us to work on the primary client program within
the workspace, without having to have loose crates.

A new crate, `kona-common-proc`, has been added as an extension of
`kona-common` to make clean `main` functions in client programs.

The `#[client_entry(<heap_size>)]` attribute will expand to include a
`_start` symbol if the binary is being compiled to a supported FPVM
target. If not, it will include a `main` symbol, as normal to run on the
native hardware.

.github/workflows/fpvm-tests.yaml

@@ -20,8 +20,7 @@ jobs:
           cache-on-failure: true
           prefix-key: ${{ matrix.fpvm }}
           cache-directories: |
-            examples/minimal/target
-            examples/simple-revm/target
+            target/
       - uses: taiki-e/install-action@just
       - name: Log into ghcr
         uses: docker/login-action@v3
@@ -36,8 +35,8 @@ jobs:
         with:
           name: images-${{ matrix.fpvm }}
           path: |
-            examples/minimal/target/${{ matrix.fpvm == 'cannon' && 'mips-unknown-none' || 'riscv64gc-unknown-none-elf' }}/release/minimal
-            examples/simple-revm/target/${{ matrix.fpvm == 'cannon' && 'mips-unknown-none' || 'riscv64gc-unknown-none-elf' }}/release/simple-revm
+            target/${{ matrix.fpvm == 'cannon' && 'mips-unknown-none' || 'riscv64gc-unknown-none-elf' }}/release-client-lto/minimal
+            target/${{ matrix.fpvm == 'cannon' && 'mips-unknown-none' || 'riscv64gc-unknown-none-elf' }}/release-client-lto/simple-revm
   fpvm-example-tests:
     needs: build-example-programs
     runs-on: ubuntu-latest
@@ -46,6 +45,8 @@ jobs:
       matrix:
         fpvm: ["cannon-go", "cannon-rs", "asterisc"]
     name: ${{ matrix.fpvm }}-tests
+    env:
+      TARGET_NAME: ${{ contains(matrix.fpvm, 'cannon') && 'mips-unknown-none' || 'riscv64gc-unknown-none-elf' }}
     steps:
       - name: Checkout sources
         uses: actions/checkout@v4
@@ -93,8 +94,9 @@ jobs:
           name: images-${{ contains(matrix.fpvm, 'cannon') && 'cannon' || 'asterisc' }}
       - name: Restore Targets
         run: |
-          mv minimal/target examples/minimal
-          mv simple-revm/target examples/simple-revm
+          mkdir -p target/$TARGET_NAME/release-client-lto/
+          mv minimal target/$TARGET_NAME/release-client-lto
+          mv simple-revm target/$TARGET_NAME/release-client-lto
       - name: Run FPVM tests
         working-directory: ./fpvm-tests
         run: just test-${{ matrix.fpvm }}

.gitignore

@@ -1,7 +1,5 @@
-# Rust target
-target
-
-# Example targets
-examples/**/target
-
+# MacOS dust
 .DS_Store
+
+# Rust target
+target/

Cargo.toml

@@ -1,6 +1,6 @@
 [workspace]
-members = ["crates/*", "bin/host"]
-exclude = ["examples/minimal", "examples/simple-revm", "fpvm-tests/cannon-rs-tests"]
+members = ["crates/*", "bin/host", "bin/programs/*"]
+exclude = ["fpvm-tests/cannon-rs-tests", "bin/programs/optimism"]
 resolver = "2"
 
 [workspace.package]
@@ -12,16 +12,30 @@ homepage = "https://github.com/ethereum-optimism/kona"
 exclude = ["**/target", "benches/", "tests"]
 
 [workspace.dependencies]
+# General
 anyhow = { version = "1.0.79", default-features = false }
 tracing = { version = "0.1.40", default-features = false }
 cfg-if = "1.0.0"
+
+# Ethereum
 alloy-primitives = { version = "0.7.1", default-features = false }
 alloy-rlp = { version = "0.3.4", default-features = false }
 alloy-consensus = { git = "https://github.com/alloy-rs/alloy", rev = "e3f2f07", default-features = false }
+revm = { version = "9.0.0", default-features = false }
 
 [profile.dev]
 opt-level = 1
 overflow-checks = false
 
 [profile.bench]
 debug = true
+
+[profile.dev-client]
+inherits = "dev"
+panic = "abort"
+
+[profile.release-client-lto]
+inherits = "release"
+panic = "abort"
+codegen-units = 1
+lto = "fat"

bin/programs/README.md

@@ -0,0 +1,3 @@
+# `kona` programs
+
+This directory contains all client programs checked into `kona`.

bin/programs/minimal/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "minimal"
+version = "0.1.0"
+publish = false
+edition.workspace = true
+authors.workspace = true
+license.workspace = true
+repository.workspace = true
+homepage.workspace = true
+
+[dependencies]
+cfg-if.workspace = true
+kona-common = { path = "../../../crates/common" }
+kona-common-proc = { path = "../../../crates/common-proc" }
+
+[[bin]]
+name = "minimal"
+path = "src/main.rs"

bin/programs/minimal/README.md

@@ -0,0 +1,3 @@
+# `minimal`
+
+Minimal "Hello, world!" example program using the `kona-common` SDK.

examples/simple-revm/justfile → bin/programs/minimal/justfile

@@ -5,15 +5,15 @@ build-cannon *args='':
   docker run \
     --rm \
     --platform linux/amd64 \
-    -v `pwd`/../../:/workdir \
-    -w="/workdir/examples/simple-revm" \
-    ghcr.io/ethereum-optimism/kona/cannon-builder:main cargo build -Zbuild-std $@
+    -v `pwd`/../../../:/workdir \
+    -w="/workdir/bin/programs/minimal" \
+    ghcr.io/ethereum-optimism/kona/cannon-builder:main cargo build -Zbuild-std --bin minimal $@
 
 # Build for the `asterisc` target
 build-asterisc *args='':
   docker run \
     --rm \
     --platform linux/amd64 \
-    -v `pwd`/../../:/workdir \
-    -w="/workdir/examples/simple-revm" \
-    ghcr.io/ethereum-optimism/kona/asterisc-builder:main cargo build -Zbuild-std $@
+    -v `pwd`/../../../:/workdir \
+    -w="/workdir/bin/programs/minimal" \
+    ghcr.io/ethereum-optimism/kona/asterisc-builder:main cargo build -Zbuild-std --bin minimal $@

bin/programs/minimal/src/main.rs

@@ -0,0 +1,12 @@
+#![no_std]
+#![cfg_attr(any(target_arch = "mips", target_arch = "riscv64"), no_main)]
+
+use kona_common::io;
+use kona_common_proc::client_entry;
+
+extern crate alloc;
+
+#[client_entry(0xFFFFFFF)]
+fn main() {
+    io::print("Hello, world!\n");
+}

bin/programs/optimism/README.md

@@ -0,0 +1,15 @@
+# `kona-optimism`
+
+This binary contains the client program for executing the Optimism rollup state transition.
+
+## Modes
+
+The `kona-optimism` program supports several different modes, each with a separate purpose:
+
+| Name     | Description                                                                                                                                                                                                                |
+| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `online` | Directly fetches external data from trusted providers. To be invoked without the `host` program on native hardware.                                                                                                        |
+| `fault`  | Fetches in external data over the wire through the [`PreimageOracle` ABI][preimage-oracle-abi], supported by the `kona-host` program. Can run on native hardware or one of the supported [Fault Proof VM][fpvm] soft-CPUs. |
+
+[preimage-oracle-abi]: https://specs.optimism.io/experimental/fault-proof/index.html#pre-image-oracle
+[fpvm]: https://static.optimism.io/kona/fpp-dev/targets.html

bin/programs/simple-revm/Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "simple-revm"
+version = "0.1.0"
+publish = false
+edition.workspace = true
+authors.workspace = true
+license.workspace = true
+repository.workspace = true
+homepage.workspace = true
+
+[dependencies]
+anyhow.workspace = true
+revm.workspace = true
+cfg-if.workspace = true
+
+kona-common = { path = "../../../crates/common" }
+kona-common-proc = { path = "../../../crates/common-proc" }
+kona-preimage = { path = "../../../crates/preimage" }
+
+[[bin]]
+name = "simple-revm"
+path = "src/main.rs"

examples/minimal/justfile → bin/programs/simple-revm/justfile

@@ -5,15 +5,15 @@ build-cannon *args='':
   docker run \
     --rm \
     --platform linux/amd64 \
-    -v `pwd`/../../:/workdir \
-    -w="/workdir/examples/minimal" \
-    ghcr.io/ethereum-optimism/kona/cannon-builder:main cargo build -Zbuild-std $@
+    -v `pwd`/../../../:/workdir \
+    -w="/workdir/bin/programs/simple-revm" \
+    ghcr.io/ethereum-optimism/kona/cannon-builder:main cargo build -Zbuild-std --bin simple-revm $@
 
 # Build for the `asterisc` target
 build-asterisc *args='':
   docker run \
     --rm \
     --platform linux/amd64 \
-    -v `pwd`/../../:/workdir \
-    -w="/workdir/examples/minimal" \
-    ghcr.io/ethereum-optimism/kona/asterisc-builder:main cargo build -Zbuild-std $@
+    -v `pwd`/../../../:/workdir \
+    -w="/workdir/bin/programs/simple-revm" \
+    ghcr.io/ethereum-optimism/kona/asterisc-builder:main cargo build -Zbuild-std --bin simple-revm $@