Quick start

This walkthrough runs the repository's standard local network: three witness nodes, a gateway on port 8080, and a threshold of two witnesses. It is a development/demo setup, not a production deployment.

1. Build the binaries

From a machine with Rust and SQLite available:

git clone https://git.carpocratian.org/sibyl/witness.git
cd witness
cargo build --release

The CLI binary is target/release/witness.

2. Start the example network

Run these commands from the repository root:

./examples/setup.sh
./examples/start.sh

setup.sh generates local witness keys and writes the example configuration. start.sh launches witnesses on ports 3001–3003 and the gateway on http://localhost:8080.

3. Submit and poll a job

Submit a file. The CLI computes its SHA-256 hash locally and sends only that hash to the gateway:

target/release/witness attest --file README.md

The response includes the hash and a job status. Job creation is asynchronous: the first response may be Pending or Retryable, and it may not contain a signed attestation yet. Poll the same hash until the status is Confirmed:

HASH="$(shasum -a 256 README.md | awk '{print $1}')"
target/release/witness status "$HASH"

Run status again after a short wait if the job is still pending. A confirmed response reports the verified signature count. Failed is terminal and may include the last worker error.

You can also submit a known 64-character, hex-encoded SHA-256 hash directly:

target/release/witness attest --hash "$HASH"

4. Save and verify the signed attestation

Once the job is confirmed, save its response and extract the nested signed_attestation object. The example scripts use jq for this step:

target/release/witness attest --hash "$HASH" --save /tmp/attestation.json
jq -r '.signed_attestation' /tmp/attestation.json > /tmp/attestation-signed.json
target/release/witness verify /tmp/attestation-signed.json

verify fetches the public verification configuration from the gateway and performs the signature check locally. A valid result prints VALID; an invalid result prints INVALID and exits non-zero. The saved job response is not itself the input to verify; the command expects the signed attestation JSON object extracted above.

5. Run the bundled demo

The repository includes the same end-to-end flow, including polling and verification:

./examples/demo.sh

When finished, stop all local processes:

./examples/stop.sh

The scripts leave generated configuration, logs, and the example SQLite database under examples/. Do not reuse the generated local keys or tokens for a real deployment.