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.

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:

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.

johnandersen777.bsky.social/zkwid Switch repository Loading…