Skip to main content

Quickstart

The fastest path to a running ZisK prover. Start a coordinator and a worker on your own machine and submit a real proving job to it via the in-tree sha-hasher example. Roughly 15 minutes end-to-end.

Install ZisK​

The Quickstart assumes you already have ZisK installed via ziskup. The developer install guide is the canonical source, it covers system prerequisites (shared memory, Rust toolchain, package dependencies) plus the ziskup flow that drops cargo-zisk, zisk-coordinator, zisk-worker, and the proving-key bundle on your machine:

Pick option 1 at the ziskup prompt to install the full proving key so the worker can produce proofs. Come back here once zisk-coordinator --version works from a fresh shell.

Clone the repository​

A few steps below use files that ship with the ZisK repo — ready-to-go example configs for the coordinator and worker, plus the host example used for the smoke test. Clone it into a working directory:

bash
git clone https://github.com/0xPolygonHermez/zisk.git
cd zisk

The rest of the Quickstart runs from inside this clone.

Start the coordinator​

The repo ships an example coordinator config at distributed/deploy/config/coordinator.toml:

distributed/deploy/config/coordinator.toml
[service]
name = "ZisK Coordinator"
environment = "production"

[server]
host = "0.0.0.0"
port = 7001                  # client-facing gRPC

[coordinator]
port = 50052                 # worker-facing gRPC

[metrics]
enabled = true
host = "0.0.0.0"
port = 9091

[logging]
level = "info"
format = "json"

[backend]
mode = "coordinator"

It's tuned for a Docker Compose deployment, so its ports (7001 / 50052 / 9091) are offset by one from the canonical defaults to coexist with a host install. For the Quickstart, point the coordinator at it and override the ports back to the defaults on the command line:

bash
zisk-coordinator --config distributed/deploy/config/coordinator.toml \
    --api-port 7000 --cluster-port 50051 --metrics-port 9090

Leave the terminal open. The coordinator now listens on:

PortPurpose
7000Client-facing gRPC API. Clients connect here.
50051Worker-facing cluster gRPC. Workers connect here.
9090Prometheus /metrics and /health HTTP endpoint.

Start a worker​

The repo also ships an example worker config at distributed/deploy/config/worker.toml:

distributed/deploy/config/worker.toml
[worker]
compute_capacity.compute_units = 10
environment = "production"

[coordinator]
url = "http://127.0.0.1:50052"

[connection]
reconnect_interval_seconds = 5
heartbeat_timeout_seconds  = 30

[logging]
level  = "info"
format = "json"

In a second terminal (still inside the zisk clone), start a worker using this config. Override the coordinator URL so the worker dials the canonical :50051 you bound the coordinator on:

bash
zisk-worker --config distributed/deploy/config/worker.toml \
    --coordinator-url http://127.0.0.1:50051

The worker opens a bidirectional WorkerStream, registers itself with a random worker_id, and starts heartbeating. You should see a worker registered line in the coordinator terminal. You now have a one-worker cluster running locally.

On worker console:

INFO: Connecting to coordinator at http://127.0.0.1:50051
INFO: Registration accepted: Registration successful

On Coordinator console:

INFO: Registered worker: WorkerId(917be5ba…) (total: 1 CC: 10CU ACC: 0CU)
INFO: WorkerId(917be5ba…) registered successfully

Health check​

Before submitting a job, confirm the coordinator is live. Its metrics server exposes a /health endpoint that returns 200 OK when the binary is healthy:

bash
curl -i http://127.0.0.1:9090/health
HTTP/1.1 200 OK
content-length: 2

If you don't get a 200, scroll back to the coordinator terminal — most failures (port conflict, missing config field) show up there immediately.

Submit a smoke-test job​

The sha-hasher example in the clone you made earlier ships a host program that submits a real proving job over the coordinator's public gRPC API. It uses the in-tree ProverClient::remote(...) helper, so you exercise the same code path your own host applications will use — no separate CLI involved.

In a third terminal, from inside the zisk clone:

bash
cd examples/sha-hasher/host
cargo run --release --bin prove-remote

prove-remote builds a ProverClient::remote("http://127.0.0.1:7000"), uploads the sha-hasher guest ELF, waits for the coordinator to drive the job through the worker, and writes the resulting proof to disk.

While it runs, watch the other two terminals. The coordinator log shows the job moving through Queued → Running → Completed with worker registered and segment-assignment lines; the worker log shows witness generation, partial proofs, and a final "job complete" message.

Next steps​

  • Pick a real deployment style in Deploying your prover — local dev, Linux server, Docker Compose, container images, or Kubernetes.
  • Wire /metrics into Prometheus and Grafana — see Monitoring.