Quick Start

This is a development setup guide, checked September 25, 2026. Use synthetic data and testnet funds. There is no guaranteed setup or proving time.

Public package access

The main source repository  is public. npm packages are at version 0.7.2:

npm install @clearproof/proof@0.7.2

Proof generation requires compatible circuit WASM and proving-key files. Verification requires the matching verification key. Inspect package contents before relying on exported artifact paths; installing the SDK alone does not create a complete proving environment.

Version 0.7.2, published October 7, 2026, matches this package and this source checkout and includes the pilot and the current pilot-transfer-v3 profile. @clearproof/circuits publishes the circuit sources only, with no compiled artifacts or keys.

The CLI installs from npm with npm install -g @clearproof/cli (verified September 26, 2026). The source setup below builds the same workspaces and adds the Python API, circuits and pilot acceptance tooling.

Quick verification example

Prerequisites: Git and Node.js 22.12+ with npm. This source example needs no Circom, PostgreSQL, Python, proving key, testnet account or API credentials.

git clone --branch main https://github.com/repfigit/clearproof.git
cd clearproof
npm exec --yes --package=npm@11.9.0 -- npm ci
npm run build --workspace=@clearproof/proof
node scripts/inspect_example.mjs

The script independently pairs the repository’s existing historical legacy 16-signal development proof, then alters its public registry domain and verifies that pairing rejects the tampered statement. Expected output includes:

{
  "cryptographic_valid": true,
  "policy_accepted": false,
  "rejection_reasons": ["threshold_mismatch"],
  "tampered_pairing_rejected": true,
  "authorization_consumed": false,
  "production_eligible": false
}

The original fixture deliberately has policy-negative thresholds, a zero chain ID and an old timestamp. Exit 0 means the expected pairing, policy rejection and tamper rejection occurred. It does not authorize a transfer or demonstrate the current eight-signal pilot. If the example fails, rebuild the SDK from this checkout and restore the unchanged fixture; do not alter its thresholds to make it pass. See the repository guide .

Complete local pilot

Prerequisites: Git, Python 3.11+ with uv (the locked install uses 3.12), Node.js 22.12+ with npm, Circom 2.2.2 and PostgreSQL 18 for the pilot acceptance run.

git clone --branch main https://github.com/repfigit/clearproof.git
cd clearproof
npm exec --yes --package=npm@11.9.0 -- npm ci
uv sync --frozen --extra dev --python 3.12
npm run build
node packages/cli/dist/index.js --help

To generate development artifacts for both proof profiles and run the pilot end to end, follow the local acceptance guide :

curl --fail -L -o /absolute/ppot_0080_17.ptau \
  https://pse-trusted-setup-ppot.s3.eu-central-1.amazonaws.com/pot28_0080/ppot_0080_17.ptau
.venv/bin/python scripts/test_development_circuits.py /absolute/new-development-artifacts \
  --prepared-ptau /absolute/ppot_0080_17.ptau
.venv/bin/python scripts/test_pilot_local.py /absolute/new-development-artifacts/pilot \
  /absolute/new-pilot-run --postgres-bin /usr/lib/postgresql/18/bin --preflight
.venv/bin/python scripts/test_pilot_local.py /absolute/new-development-artifacts/pilot \
  /absolute/new-pilot-run --postgres-bin /usr/lib/postgresql/18/bin

Check the file’s SHA-256 against the one pinned in the guide before using it. Locally generated development keys are not production keys. bash scripts/compile_circuits.sh still builds the legacy profile on its own.

Preflight checks the selected Python dependencies, Node/Hardhat, built CLI, PostgreSQL 18 and the artifact doctor’s development acceptance and production rejection. It creates no output directory and starts no service. The full run owns its database and EVM, stops them on failure, and retains nine scoped reports plus a report-only inventory. Keep private/, database files and logs private. After a failure, follow the recovery steps  and use a new run directory.

API exploration

For a disposable local evaluation:

export AUTH_MODE=api-key
export API_KEY="$(openssl rand -hex 32)"
export PII_MASTER_KEY="$(openssl rand -hex 32)"
export HKDF_SALT="$(openssl rand -hex 32)"
uv run uvicorn src.api.main:app --reload --host 127.0.0.1 --port 8000

Open the local OpenAPI UI . Protected requests use X-API-Key in this mode. Keep keys and the HKDF salt stable and protected for any evaluation whose encrypted records need to survive restart. The commands above generate new material for a disposable run; do not rerun them over retained data. See the legacy encryption migration guide  before upgrading a deployment that used the old default salt.

Download the schema generated by this running instance from http://localhost:8000/openapi.json. To generate a schema from a source checkout without starting the API or connecting storage:

uv run python -c 'import json; from src.api.main import create_app; print(json.dumps(create_app().openapi(), indent=2, sort_keys=True))' > /absolute/openapi.json

The schema describes routes and validation; deployment trust and role requirements still apply. Pilot routes in API-key mode additionally require operator-configured API_KEY_TENANT_ID, API_KEY_ACTOR_ID and API_KEY_ROLES; use the intended tenant/actor and only the roles needed for the operation. See the current SDK example.

Starting the server does not establish a working proof workflow. The pilot routes need PostgreSQL, storage keys, tenant trust configuration and compatible artifacts; /health reports process liveness only. Do not treat synthetic output as a live transfer authorization.

Checks

make test
npm run test:ts
npm run build

At this checkout, root npm test runs Python tests; npm run test:ts runs the TypeScript workspaces. Database integration tests need an isolated PostgreSQL instance. Real circuit checks have additional artifact/toolchain requirements.

See project status before planning an integration.