1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
# 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.
