Building from Source

The repository’s AGENTS.md is the full guide. This is the short version.

Layout

Each top-level Rust directory is its own cargo workspace, so cd into it before running cargo.

directory	what
core/	notes, nullifiers, trees, records, the statement layout, the pin
circuit/	the circuits, the recursion, the provers
pool-covenant/	the GSR pool covenant (tapleaf 0xc2): settlement, inboxes, vault, migrations, and an interpreter
aggregator/	the share-chain node and the coordinator
wallet-core/	the iOS wallet’s Rust core: client, light client, Tor, payment codes
wallet/ios/	the iOS app
docs/	the design notes (docs/*.md)
site/	the landing page and /docs/ documentation (Astro + Starlight)

Bootstrap and build

scripts/bootstrap.sh                          # clone vendor/ at pinned commits, apply patches/
CHESHIRE_BOOTSTRAP_GSR=1 scripts/bootstrap.sh # also the GSR node source

(cd aggregator    && cargo build --release)
(cd circuit       && cargo build --release)
(cd pool-covenant && cargo build --release)

The GSR node, for a local signet:

cmake -B vendor/gsr-bitcoin/build -S vendor/gsr-bitcoin -DCMAKE_BUILD_TYPE=Release \
  -DBUILD_GUI=OFF -DENABLE_WALLET=ON -DBUILD_UTIL=ON -DBUILD_TESTS=OFF -DENABLE_IPC=OFF
cmake --build vendor/gsr-bitcoin/build -j

just lists the common tasks (just build, just test, just purity, just verify).

Tests

(cd circuit       && cargo test --release)   # incl. the forgery suite and the ZK checks
(cd pool-covenant && cargo test --release)   # incl. the covenant tamper tests

These are fast and do no full proving. A whole settlement, by contrast, takes about an hour and ~9 GB on one Mac.

A local demo

bash scripts/demo-up.sh   # a local GSR signet, the explorer (with Docker), the coordinator

The iOS app

brew install xcodegen
cd wallet/ios
bash scripts/build-core.sh   # wallet-core's XCFramework and Swift bindings
xcodegen generate
open Cheshire.xcodeproj

This site

The landing page and docs share one Astro project in site/ (docs pages in site/src/content/docs/docs/). It needs Node 22.12 or later:

just docs          # npm ci, build into site/dist/, check every internal link
just docs-serve    # serve locally with live reload