zkDeal engineering · Platform Engineering

Run the supplied Docker stack—or customize any role

Start with zkDeal’s published Docker operating planes, inspect a digest-pinned CUDA prover, and learn where customization keeps the proof and settlement boundaries intact.

Oleg Iakushkin5 min read
DockerRISC ZeroCUDAOperations

DEPLOYABLE DOCKER ARCHITECTURE • READY-TO-RUN IMAGES

Run the supplied Docker stack—or customize any role

zkdeal supplies separate Docker images for live room execution, operations and validation. Teams can run the default topology, co-locate roles for a smaller deployment, or substitute individual components while preserving the selected room and settlement boundaries.

From an application request to Ethereum settlement

Explore the architecture

Deployable Docker architecture

Pan · zoom · select a node
Users + app services

configure rooms • sign transactions • read results • request withdrawals

Ethereum L1

RoomManager • RoomPool • RoomVault • forced inbox • verifiers • claims

zkdeal/coordinator

API • rooms • admissions • proof queue • index • reconcile • publish • auto-claim • active or standby roles

zkdeal/headless-room-node

join room • sequence • prepare batches • request proofs • verify • watch finality • checksummed room lifecycle state

L1 connections

two RPC views • scoped writer • L1 events and finality in • proof-backed checkpoints out

Application infrastructure

PostgreSQL • object storage • route • remote signer • room volume

Durable queue

proof jobs • leases • results

zkdeal/prover-agent

outbound pull • lease • feed • return

zkdeal/prover-cuda

GPU room • data • aggregate proof generation

zkdeal/operator-docs

guides • API • metrics

zkdeal/deployment-tools

deploy • inspect • conform

zkdeal/backup-tools

encrypted backup • restore

zkdeal/promotion-controller

verify promotion conditions

zkdeal/failover-provider

fence writer • switch route

zkdeal/acceptance-runner

end-to-end behavior

zkdeal/failover-runner

promotion + fencing drill

zkdeal/soak-runner

sustained restart-safe run

zkdeal/fault-control

restarts • partitions • reorgs

zkdeal/backup-restore-control

fresh-target restore checks

Solid arrows

live capital, requests, state or proofs

Dashed arrows

deployment, recovery or validation control

GPU boundary

The agent pulls jobs; the GPU host needs no public or control-plane inbound connection.

Mini Map
React Flow

Drag the canvas to pan, use the wheel or pinch gesture to zoom, and use the controls to zoom or fit the whole model. Expand for a page-sized view; press Escape to close it.

Interactive architecture diagram.
View the static reference imagezkdeal deployment architecture. Users and app services send signed room requests to the coordinator and interact directly with Ethereum for deposits, claims and refunds. The coordinator works with a headless room node, durable storage and a pull-only proving lane made of prover-agent and prover-cuda. Ethereum L1 receives data and proof-backed checkpoints. Operator, deployment, backup, promotion and failover images support the live stack. Acceptance, failover, soak, fault-control and backup-restore images validate it on demand. Every role can be customized behind the same interfaces.
Read the figure transcript

zkdeal deployment architecture. Users and app services send signed room requests to the coordinator and interact directly with Ethereum for deposits, claims and refunds. The coordinator works with a headless room node, durable storage and a pull-only proving lane made of prover-agent and prover-cuda. Ethereum L1 receives data and proof-backed checkpoints. Operator, deployment, backup, promotion and failover images support the live stack. Acceptance, failover, soak, fault-control and backup-restore images validate it on demand. Every role can be customized behind the same interfaces.

Ready images by operating plane

RUN zkdeal/coordinator hosts the API and service roles; zkdeal/headless-room-node runs bounded room execution; zkdeal/prover-agent pulls proof work; zkdeal/prover-cuda generates room, data and aggregate proofs.

OPERATE + RECOVER zkdeal/operator-docs, zkdeal/deployment-tools and zkdeal/backup-tools support the deployment; zkdeal/promotion-controller and zkdeal/failover-provider verify a handoff, fence the old writer and switch the route.

VALIDATE + REHEARSE zkdeal/acceptance-runner, zkdeal/failover-runner, zkdeal/soak-runner, zkdeal/fault-control and zkdeal/backup-restore-control exercise normal operation, recovery, long runs, controlled faults and clean-target restore.

Customize by interface, then revalidate the chosen profile

Platform advocate view

A deployable system, not an architecture diagram

The most compelling thing about zkDeal’s operating model is that teams do not have to swallow a monolith. Execution, coordination, proving, promotion, recovery, and acceptance are published as separate operating planes. That makes the default stack useful immediately—and makes each boundary a deliberate integration point instead of a future promise.

Start with the supplied topology to shorten the path from evaluation to evidence. Then replace only the role your organization needs to own. The contract is simple: keep the API, queue, proof-format, storage, and L1 behavior required by the room profile, and rerun the corresponding validation exercises.

  • Pull a prover for the RTX 4090’s sm89 architecture by immutable digest.
  • Use unauthenticated read-only health and capability routes without publishing machine identity.
  • Keep the HTTP listener on loopback for evaluation and configure a token before any job route is exposed.

Demo / use it today

Run the public path

This smoke path proves three concrete things: the exact public image was selected, Docker can pass an NVIDIA GPU into it, and the running service reports a production CUDA build with CPU fallback disabled.

Before you start

  • A Bash-compatible shell: Linux, macOS, or WSL on Windows. The copyable commands use POSIX shell syntax.
  • Docker with the NVIDIA Container Toolkit and an sm89-capable RTX 4090.
  • OpenSSL for an unprinted temporary token, plus curl and jq for deliberately filtered readiness output.
  • A free loopback port 8080 and no other GPU compute container.

  1. Pin first

    The tutorial assigns the full multi-architecture digest to IMAGE. It never uses latest, and the pull output is expected to repeat the same digest.

  2. Verify the hardware boundary

    The first disposable run overrides the image entrypoint only to ask NVIDIA for the model and compute capability. Stop if the GPU is absent or is not compatible with the selected image.

  3. Inspect only safe fields

    The service routes include richer identity data. The jq projections intentionally omit GPU UUID, guest program identifiers, container telemetry labels, and any token.

Pin the public image

IMAGE=zkdeal/prover-cuda@sha256:3d783bfd12fd3d634ea03bdd96eb5f04930d1563d494619d088758e51a8d5d34

Pull by digest

docker pull "$IMAGE"
Expected output shape
Digest: sha256:3d783bfd12fd3d634ea03bdd96eb5f04930d1563d494619d088758e51a8d5d34
Status: Image is up to date for zkdeal/prover-cuda@sha256:3d783bfd…

Confirm the GPU architecture

docker run --rm --gpus all --entrypoint nvidia-smi "$IMAGE" \
  --query-gpu=name,compute_cap --format=csv,noheader
Expected output shape
NVIDIA GeForce RTX 4090, 8.9

Generate a temporary token without printing it

export ZKDEAL_PROVER_TOKEN="$(openssl rand -hex 32)"

Start a loopback-only smoke service

PROVER_ID="$(docker run --rm --gpus all -d \
  -p 127.0.0.1:8080:8080 -e ZKDEAL_PROVER_TOKEN \
  -e SEGMENT_PO2=20 "$IMAGE")" && export PROVER_ID

Read sanitized readiness

curl -fsS http://127.0.0.1:8080/healthz | \
  jq '{status,protocolVersion,evmFork,cpuFallback,prover}'
Expected output shape
{"status":"ready","protocolVersion":6,"evmFork":"osaka","cpuFallback":false,"prover":"risc0-local-cuda"}

Read sanitized capabilities

curl -fsS http://127.0.0.1:8080/v5/capabilities | \
  jq '{protocolVersion,backendId,cudaCompiled,productionCompiled,proofModes,ethereumSeal}'
Expected output shape
{"protocolVersion":6,"backendId":"risc0","cudaCompiled":true,"productionCompiled":true,"proofModes":["succinct","groth16"],"ethereumSeal":true}

Remove the disposable service

docker stop "$PROVER_ID" >/dev/null && unset PROVER_ID ZKDEAL_PROVER_TOKEN

What this gives you: A ready result with protocolVersion 6, cudaCompiled and productionCompiled true, and cpuFallback false is the minimum useful smoke signal. It is not a proof-correctness qualification or a replacement for the release ceremony.

Interactive expected I/O

Inspect the digest-pinned RTX 4090 prover

Source-pinned expected output

Select text directly in the player, pause at any point, or copy the complete transcript below.

Copy or read the complete transcript
Plain textAsciicast v3VHS tape
$ IMAGE=zkdeal/prover-cuda@sha256:3d783bfd12fd3d634ea03bdd96eb5f04930d1563d494619d088758e51a8d5d34
$ docker pull "$IMAGE"
Digest: sha256:3d783bfd12fd3d634ea03bdd96eb5f04930d1563d494619d088758e51a8d5d34
Status: Image is up to date for zkdeal/prover-cuda@sha256:3d783bfd…
$ docker run --rm --gpus all --entrypoint nvidia-smi "$IMAGE" \
>   --query-gpu=name,compute_cap --format=csv,noheader
NVIDIA GeForce RTX 4090, 8.9
$ export ZKDEAL_PROVER_TOKEN="$(openssl rand -hex 32)"
$ PROVER_ID="$(docker run --rm --gpus all -d \
>   -p 127.0.0.1:8080:8080 -e ZKDEAL_PROVER_TOKEN \
>   -e SEGMENT_PO2=20 "$IMAGE")" && export PROVER_ID
$ curl -fsS http://127.0.0.1:8080/healthz | \
>   jq '{status,protocolVersion,evmFork,cpuFallback,prover}'
{"status":"ready","protocolVersion":6,"evmFork":"osaka","cpuFallback":false,"prover":"risc0-local-cuda"}
$ curl -fsS http://127.0.0.1:8080/v5/capabilities | \
>   jq '{protocolVersion,backendId,cudaCompiled,productionCompiled,proofModes,ethereumSeal}'
{"protocolVersion":6,"backendId":"risc0","cudaCompiled":true,"productionCompiled":true,"proofModes":["succinct","groth16"],"ethereumSeal":true}
$ docker stop "$PROVER_ID" >/dev/null && unset PROVER_ID ZKDEAL_PROVER_TOKEN
Video fallback generated with VHS 0.11.0

Pinned public inputs

Repositories and images used here

Public availability is not one license claim: protocol, examples, and testing are MIT; node, prover, and coordinator are public source under BUSL-1.1.

Explore public repositoriesBrowse Docker images