# Contributing to zkwid

## Layout

| Path | What |
|---|---|
| `crates/zkwid` | Core lib: lexicon types, measuring, challenge JWT, scopes, client metadata, did:key resolver |
| `crates/zkwid-n` | N, the zkwid.at service: OAuth clients, `at.zkwid.*` XRPC, reverse proxy |
| `crates/zkwid-h` | H stub, the hosted service that runs workloads |
| `crates/zkwid-zkvm` | RISC Zero host (`prove`, `verify`), with `core/` (shared types) and `guest/` (zkVM program) |
| `crates/zkwid-dev` | Devnet harness (PLC, PDS, CA, CONNECT proxy) and the end-to-end test |
| `stages/` | Workload WASM: `shim` and `stage2` |
| `lexicons/at/zkwid` | Lexicons |
| `docs/` | `plan.md`, `interfaces.md`, `future-work.md` |

`../atproto-crates` must be checked out next to this repo. All atproto crates are path dependencies.

## Toolchain

Linux x86_64 is required: the devnet relies on `SSL_CERT_FILE`, which is honoured only on Linux.

```sh
rustup toolchain install 1.97
rustup target add wasm32-unknown-unknown
curl -L https://risczero.com/install | bash
~/.risc0/bin/rzup install
cargo build -p atproto-pds --bin pds --features clap --manifest-path ../atproto-crates/Cargo.toml
```

`rzup install` provides `cargo-risczero 3.0.x`, `r0vm` and the RISC Zero Rust toolchain. It builds the guest.

The devnet finds the PDS binary at `../atproto-crates/target/debug/pds`. Override that with `ZKWID_PDS_BIN`.

## Dev iteration loop

| Loop | Command | Rough time |
|---|---|---|
| Build stages | `scripts/stages.sh` | seconds |
| Core unit tests | `cargo test -p zkwid` | seconds |
| N / H unit tests | `cargo test -p zkwid-n -p zkwid-h` | seconds |
| zkVM round trip (fake receipt) | `RISC0_DEV_MODE=1 cargo test -p zkwid-zkvm` | tens of seconds after the first guest build |
| Full flow | `RISC0_DEV_MODE=1 cargo test -p zkwid-dev --test e2e` | about a minute |
| Real proof | `cargo test -p zkwid-zkvm --release -- --ignored real_proof` | minutes on CPU |

`RISC0_DEV_MODE=1` makes fake receipts, so iteration is fast. A production N is built with `--features zkwid-n/prod`, which refuses fake receipts.

The first build compiles the guest with the RISC Zero toolchain. After that the guest rebuilds only when `crates/zkwid-zkvm/guest` or `crates/zkwid-zkvm/core` changes.

## Gate

Every change must pass:

```sh
cargo build --workspace
RISC0_DEV_MODE=1 cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
```

## Style

- Minimal code. No comments.
- One concern per module.
- Signatures in `docs/interfaces.md` are shared contracts.
- New NSIDs go under `at.zkwid.*` only.

## Commits

Small commits. Push after each one that passes the gate.