privashhdocs
HomeGitHubQuick start

Getting Started

Project layout

A map of the monorepo: the three core packages (circuits, contracts, sdk), the infrastructure (op-stack, explorer), the app, and the top-level scripts that tie a local run together.

shh is a pnpm workspace. Three packages hold the cryptography and contracts, infra/ holds the chain and explorer, and apps/web is the UI + backend. Top-level scripts orchestrate a local run.

The tree

shh/
├─ packages/
│  ├─ circuits/    Circom circuits + trusted-setup tooling (zk core)
│  ├─ contracts/   Hardhat: pools, Merkle tree, bridges, verifiers
│  └─ sdk/         TypeScript: notes, Merkle tree, witness + proofs
├─ infra/
│  ├─ op-stack/    Docker Compose single-sequencer L3 devnet
│  └─ explorer/    Blockscout (db + redis + backend + frontend)
├─ apps/
│  └─ web/         Next.js wallet backend (+ deferred UI)
├─ scripts/        dev.mjs (turn-key boot) + copy-artifacts.mjs
└─ docs/           workflow · architecture · privacy-design · threat-model

The three packages

PackageTechResponsibility
@shh/circuitsCircom + Groth16 (snarkjs)UTXO join-split & Privacy-Pool withdraw circuits; compile + setup + verifier export.
@shh/contractsSolidity (Hardhat)Pools, on-chain Poseidon Merkle tree, shielded bridge, generated verifiers.
@shh/sdkTypeScriptNotes, Merkle tree, witness building, proof generation; isomorphic (browser + node).

Infrastructure & app

infra/op-stack
docker-compose.yml for L1 (anvil fork of Base Sepolia), op-geth, op-node, op-batcher, op-proposer; make generate / up / down.
infra/explorer
Blockscout stack (db, redis, backend, frontend) pointed at op-geth.
apps/web
Next.js route handlers — config, pool leaves, association path, shielded events, relayer withdraw — plus the staged circuit artifacts in public/.

Top-level scripts

  • scripts/dev.mjs — what pnpm dev runs: chain + deploy + artifact copy + backend.
  • scripts/copy-artifacts.mjs — stages .wasm/.zkey and deployment manifests into the app.

The source-of-truth docs

The repo's own docs/ directory is the canonical specification these pages are built from:

  • workflow.md — the phased build plan and verification gates (see Roadmap).
  • architecture.md — system architecture (see Architecture).
  • privacy-design.md — the cryptographic source of truth (see The cryptographic core).
  • threat-model.md — assets, trust assumptions, mitigations (see Threat model).

Next: Configuration & environment.