Contributor’s guide

Commit signing

git config commit.gpgsign true

Project Structure

stellar-private-transactions/
├── app/                        # Browser-based frontend application (See app/README.md for more information)
│   ├── crates/                 # Rust WASM modules
│   │   ├── prover/             # Groth16 proof generation
│   │   └── witness/            # Circom witness calculator
│   ├── js/                     # JavaScript frontend code
│   │   ├── state/              # State management (IndexedDB, sync) (see app/ARCHITECTURE.md for more information)
│   │   ├── ui/                 # UI components 
│   │   └── *.js                # Core modules (bridge, wallet, stellar)
│   └── index.html              # Main application entry
├── circuits/                   # Circom ZK circuits
│   ├── src/
│   │   ├── poseidon2/          # Poseidon2 hash circuits
│   │   ├── smt/                # Sparse Merkle tree circuits
│   │   ├── test/               # Circuit test utilities
│   │   ├── policyTransaction.circom  # Main transaction circuit
│   │   └── *.circom            # Supporting circuits
│   └── build.rs                # Circuit compilation build script
├── contracts/                  # Soroban smart contracts
│   ├── asp-membership/         # ASP membership Merkle tree
│   ├── asp-non-membership/     # ASP non-membership sparse Merkle tree
│   ├── circom-groth16-verifier/# On-chain Groth16 proof verifier
│   ├── pool/                   # Main privacy pool contract
│   ├── soroban-utils/          # Shared utilities (Poseidon2, etc.)
│   └── types/                  # Shared contract types
├── e2e-tests/                  # End-to-end integration tests
├── poseidon2/                  # Poseidon2 hash implementation
├── scripts/                    # Deployment and utility scripts
│   ├── deploy.sh               # Contract deployment script
│   └── deployments.json        # Deployment output
└── Makefile                    # Build automation

Prerequisites

Rust 1.92.0 or later (see rust-toolchain.toml).
Circom 2.2.2 or later for circuit compilation.
Stellar CLI for contract deployment.
Node.js for frontend dependencies.
Wasm-pack for building WASM modules.
Trunk for serving the web application.
Cargo Deny
Typos
Cargo Sort

Building and testing crates

Building Circuits

To explicitly build them:

# Build circuits
cargo build -p circuits

The circuit crate also exposes 2 flags:

BUILD_TESTS: Builds the circom test circuits. Most Circom circuits simply define a template. And if you want to use it or test it, you need to instantiate it with some specific parameters. For efficiency, the compilation of these circuits test is gatekeeped behind this flag. When enabled, if the verifying keys are not in scripts/testdata, it will generate them.
REGEN_KEYS: Forces the generation of new verification keys, even if they already exist. Should not generally be used, as it might cause issues with deployed contracts.

Also, for efficiency reasons, some tests are ignored by default. To run them:

# Test circuits requires the flag to be enabled
BUILD_TESTS=1 cargo test -p circuits -- --ignored

Building Contracts

# Build all contracts
stellar contract build --manifest-path Cargo.toml --out-dir target/stellar --optimize --package pool
stellar contract build --manifest-path Cargo.toml --out-dir target/stellar --optimize --package asp-membership
stellar contract build --manifest-path Cargo.toml --out-dir target/stellar --optimize --package asp-non-membership
stellar contract build --manifest-path Cargo.toml --out-dir target/stellar --optimize --package circom-groth16-verifier

# Or use the deployment script which builds automatically
./scripts/deploy.sh --help