# Set Up

> The toolchain the repository pins, the two workspaces it holds, the ceremony file proving needs, and the machine each step asks for.

Apogee v1.0.0 is a Rust repository. There is nothing to install beyond `rustup`: the repository pins its toolchain, and the toolchain carries the guest target. Writing, building, running and profiling a guest need nothing else. Proving adds one large file and a machine with memory to match.

## The toolchain

`rust-toolchain.toml` at the repository root pins stable Rust **1.96.1** with `rustfmt`, `clippy` and `llvm-tools`, and the target **`riscv32imac-unknown-none-elf`**, whose `core` and `alloc` ship prebuilt. rustup applies it in every directory below the root and installs it on first use.

```sh
cd apogee-vm
rustup show active-toolchain     # 1.96.1, overridden by rust-toolchain.toml
cargo --version
```

No nightly and no unstable features are used anywhere. `llvm-tools` supplies the `llvm-objdump` and `llvm-nm` matching the compiler's LLVM, which the repository uses for its committed disassembly listings and which you can use to read your guest's code.

## Two workspaces

The checkout holds two Cargo workspaces, and the split matters:

| Workspace | Root | Builds for | Holds |
| --- | --- | --- | --- |
| The root workspace | `Cargo.toml` | your host | the prover, the verifier, the host SDK, the tools, everything in `crates/` and `tools/` |
| The guest workspace | `guests/Cargo.toml` | `riscv32imac-unknown-none-elf` | every guest, with its own `guests/target` directory |

Guests are kept apart because every member compiles for the guest target and links a `#[panic_handler]`; `cargo test --workspace` at the root must never reach them. The guest workspace also carries what a guest needs to be built correctly, so you never type it:

- `guests/.cargo/config.toml` sets the target and passes the linker `-T crates/guest-sdk/link.ld`, the memory map, and `--no-relax`, because relaxation would move addresses that the program identity binds.
- `guests/Cargo.toml` pins both build profiles to the same semantics, overflow checks included ([Build and inspect](https://apogee.gweb3networks.com/docs/launch/build#profiles)).
- Its `[patch.crates-io]` routes `k256`, `ark-ff` and `revm-precompile` to vendored copies that call Apogee's delegations ([Delegations](https://apogee.gweb3networks.com/docs/launch/delegations#vendored)).

> [!TIP]
> Open `guests/` as its own folder in your editor. rust-analyzer then reads that workspace's `.cargo/config.toml` and checks guest code against the guest target instead of your host.

## The ceremony file

Every commitment Apogee makes is under the powers of a secret `τ` from a public ceremony: the **PSE perpetual powers of tau, contribution 80**. One file serves every use:

```text
assets/ptau/ppot_0080_24.ptau        19.3 GB, 2^24 powers; assets/ptau/ is gitignored
```

You need it to compute a program identity, to build real keys and to prove. You do not need it to build, run or profile a guest, or to run the workspace tests, which prove over toy setups of their own.

Files from PSE's ceremony are cut from one transcript, so any file of power 24 or more serves. Hermez's `powersOfTau28_hez_final_*.ptau` is a different ceremony with a different `τ`: the reader ingests it as readily, and every commitment, key and identity over it comes out different. To confirm you hold the right ceremony, its `[τ]_1`, as the hex of its canonical encoding `x ‖ y`, is:

```text
9bbb31bedc304e081e2aada4b56c2217e0e94ee16874e3517d14bef5dcec3a16
317ff1589e53513fa333591b318e8f1e55ef7c37d92beb6d9a61d770a2f39506
```

The specification's [SRS page](https://apogee.gweb3networks.com/docs/auditors/spec/srs) states exactly what the reader checks and what it takes on trust.

## The machine

Building and running are laptop work. Proving is memory-bound, and its memory follows the shards being proved at once, not the length of the run.

| Step | Needs |
| --- | --- |
| Build a guest, run it, profile it, export and inspect its image | Any recent laptop; seconds |
| Compute a program identity (`artifact-dump tables --ptau`) | The ceremony file; about 25 s on an 18-core laptop at the default heights |
| Prove a small guest at `2^20` heights | Tens of GiB. One `2^20` shard of the widest instruction family holds about 8.4 GiB of field elements in its forward pass, and each shard in flight holds its own |
| Prove a full Ethereum block | The measured block peaked at 174 GiB on a 32-vCPU, 247.7 GiB machine |

The proving page explains how heights and the number of shards in flight trade memory against time: [Prove and verify](https://apogee.gweb3networks.com/docs/launch/prove#heights).

## Check your checkout

What CI runs, all of it without the ceremony file:

```sh
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo run -p kat-gen && git diff --exit-code      # committed fixtures regenerate identically
(cd guests && cargo clippy --bins -- -D warnings)
```

The suites that prove real shards are `#[ignore]`d, because each needs tens of GiB. Run one by name when you want to see a proof made and refused on your own machine:

```sh
cargo test --release -p prover --test acceptance -- --include-ignored --test-threads=1
```

Next: [write a guest](https://apogee.gweb3networks.com/docs/launch/write), or run the whole loop once in the [Quickstart](https://apogee.gweb3networks.com/docs/launch/quickstart).