ci: add GitHub Actions pipeline scaffolding

.github/README.md

@@ -0,0 +1,100 @@
+# GitHub Actions CI/CD Guide
+
+This repository uses a multi-workflow GitHub Actions setup so maintainers can
+review failures by area instead of debugging one giant pipeline.
+
+## Workflows
+
+### `circuits.yml`
+- installs the Noir toolchain
+- compiles all Noir workspace packages
+- runs circuit tests
+- uploads a simple constraint report artifact
+
+### `contracts.yml`
+- installs stable Rust and the `wasm32-unknown-unknown` target
+- builds the Soroban workspace
+- runs contract tests
+- generates a coverage report artifact with `cargo-tarpaulin`
+
+### `sdk.yml`
+- prepares Node.js CI for the future SDK package
+- skips cleanly when `sdk/package.json` does not exist yet
+- runs lint, typecheck, and tests once the SDK lands
+
+### `benchmark.yml`
+- runs a lightweight contract benchmark snapshot
+- uploads benchmark artifacts
+- comments the benchmark summary on pull requests
+
+### `quality.yml`
+- runs Rust formatting, clippy, and `cargo audit`
+- runs Node lint/format/security checks when the SDK package exists
+
+### `docs.yml`
+- verifies required Markdown files exist
+- checks internal Markdown links
+- uploads a docs manifest artifact
+
+## Trigger Model
+
+All workflows run on:
+- pull requests
+- pushes to `main`
+
+That keeps the signal aligned with contributor work and post-merge regression
+checks.
+
+## Caching Strategy
+
+The workflows cache:
+- cargo registry and build artifacts
+- Noir artifacts and package cache
+- npm dependencies once the SDK package exists
+
+Cache keys are derived from lock/config/source files so stale artifacts are less
+likely to bleed across incompatible changes.
+
+## Benchmarks
+
+The benchmark workflow intentionally uses a repository-local shell script:
+`scripts/ci/benchmark_contracts.sh`.
+
+Right now it captures a reproducible build/test snapshot rather than a full gas
+delta engine. That gives maintainers a baseline immediately and leaves room for
+future benchmark specialization once more benchmarking code exists in the repo.
+
+## Branch Protection
+
+Branch protection cannot be enabled from a pull request unless the actor has
+repository admin access. Maintainers should enable the following protections on
+`main`:
+
+1. require a pull request before merging
+2. require at least one approving review
+3. require branches to be up to date before merging
+4. require status checks to pass
+
+Recommended required checks:
+- `Circuits / noir-circuits`
+- `Contracts / rust-contracts`
+- `SDK / sdk-checks`
+- `Benchmarks / contract-benchmarks`
+- `Code Quality / rust-quality`
+- `Code Quality / node-quality`
+- `Documentation / docs`
+
+## Secrets
+
+Current workflows do not require repository secrets. If future deployment steps
+or external reporting are added, secrets should be stored in GitHub Actions
+repository settings and referenced only through environment variables.
+
+## Maintenance Notes
+
+- If the SDK folder is added later, update `sdk.yml` and `quality.yml` to pin
+  the package manager and concrete scripts.
+- If benchmark thresholds become strict, move the threshold logic into
+  `scripts/ci/benchmark_contracts.sh` so the rule lives close to the data.
+- If GitHub Pages documentation is added later, extend `docs.yml` with a deploy
+  job guarded behind `push` to `main`.

.github/benchmarks/contracts-wasm-size-baseline.txt

@@ -0,0 +1 @@
+0

.github/workflows/benchmark.yml

@@ -0,0 +1,62 @@
+name: Benchmarks
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  contract-benchmarks:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: wasm32-unknown-unknown
+
+      - name: Cache cargo registry and build
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/bin/
+            ~/.cargo/registry/index/
+            ~/.cargo/registry/cache/
+            ~/.cargo/git/db/
+            contracts/target/
+          key: ${{ runner.os }}-bench-cargo-${{ hashFiles('contracts/Cargo.toml', 'contracts/privacy_pool/Cargo.toml', 'contracts/**/*.rs', 'scripts/ci/benchmark_contracts.sh') }}
+          restore-keys: |
+            ${{ runner.os }}-bench-cargo-
+
+      - name: Run benchmark snapshot
+        run: bash scripts/ci/benchmark_contracts.sh
+
+      - name: Upload benchmark snapshot
+        uses: actions/upload-artifact@v4
+        with:
+          name: benchmark-report
+          path: artifacts/benchmarks
+
+      - name: Comment benchmark summary on PR
+        if: github.event_name == 'pull_request'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const path = 'artifacts/benchmarks/summary.md';
+            if (!fs.existsSync(path)) {
+              core.info('No benchmark summary found.');
+              return;
+            }
+            const body = fs.readFileSync(path, 'utf8');
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.payload.pull_request.number,
+              body,
+            });

.github/workflows/circuits.yml

@@ -0,0 +1,72 @@
+name: Circuits
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  noir-circuits:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    defaults:
+      run:
+        shell: bash
+        working-directory: circuits
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Noir toolchain
+        run: |
+          curl -L https://raw.githubusercontent.com/noir-lang/noirup/refs/heads/main/install | bash
+          echo "$HOME/.nargo/bin" >> "$GITHUB_PATH"
+          "$HOME/.nargo/bin/noirup"
+
+      - name: Cache Noir artifacts
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.nargo
+            circuits/target
+            circuits/**/target
+          key: ${{ runner.os }}-noir-${{ hashFiles('circuits/Nargo.toml', 'circuits/**/Nargo.toml', 'circuits/**/*.nr') }}
+          restore-keys: |
+            ${{ runner.os }}-noir-
+
+      - name: Check Noir toolchain
+        run: |
+          noirup --version || true
+          nargo --version
+
+      - name: Compile all circuits
+        run: nargo compile --workspace
+
+      - name: Run circuit tests
+        run: |
+          for circuit in commitment merkle withdraw; do
+            echo "Running tests for ${circuit}"
+            nargo test --package "${circuit}"
+          done
+
+      - name: Report constraint counts
+        run: |
+          mkdir -p ../artifacts
+          {
+            echo "# Noir Constraint Report"
+            echo
+            for circuit in commitment merkle withdraw; do
+              echo "## ${circuit}"
+              nargo info --package "${circuit}" || echo "nargo info not available for ${circuit}"
+              echo
+            done
+          } | tee ../artifacts/circuit-constraints.md
+
+      - name: Upload circuit artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: circuit-constraints
+          path: artifacts/circuit-constraints.md

.github/workflows/contracts.yml

@@ -0,0 +1,60 @@
+name: Contracts
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  rust-contracts:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    defaults:
+      run:
+        shell: bash
+        working-directory: contracts
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: wasm32-unknown-unknown
+          components: rustfmt, clippy
+
+      - name: Cache cargo registry and build
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/bin/
+            ~/.cargo/registry/index/
+            ~/.cargo/registry/cache/
+            ~/.cargo/git/db/
+            contracts/target/
+          key: ${{ runner.os }}-cargo-${{ hashFiles('contracts/Cargo.toml', 'contracts/privacy_pool/Cargo.toml', 'contracts/**/*.rs') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-
+
+      - name: Fetch dependencies
+        run: cargo fetch
+
+      - name: Build contract workspace
+        run: cargo build --workspace --target wasm32-unknown-unknown
+
+      - name: Run unit and integration tests
+        run: cargo test --package privacy_pool
+
+      - name: Generate coverage report
+        run: |
+          cargo install cargo-tarpaulin --locked
+          cargo tarpaulin --package privacy_pool --out Xml --output-dir ../artifacts/coverage
+
+      - name: Upload coverage artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: contracts-coverage
+          path: artifacts/coverage

.github/workflows/docs.yml

@@ -0,0 +1,41 @@
+name: Documentation
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Verify required docs exist
+        run: |
+          test -f README.md
+          test -f CONTRIBUTING.md
+          test -f contracts/privacy_pool/ARCHITECTURE.md
+          test -f .github/README.md
+
+      - name: Validate Markdown links
+        run: bash scripts/ci/check_markdown_links.sh
+
+      - name: Upload docs manifest
+        run: |
+          mkdir -p artifacts/docs
+          {
+            echo "# Documentation Manifest"
+            echo
+            find . -maxdepth 3 -name '*.md' | sort
+          } > artifacts/docs/manifest.md
+
+      - name: Upload docs artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-manifest
+          path: artifacts/docs