Skip to main content

Ethproofs posting

This page shows you how to make the Airbender or Hypercube service report its proofs to Ethproofs, and what it sends along the way.

Ethproofs collects proofs of Ethereum blocks from registered proving clusters. The Airbender and Hypercube services can both report to it, but the ZisK backend can't yet.

Live clusters​

One Zilkworm cluster posts today, "Zilkworm Airbender v3 2x5090 on-prem". It was the only one on ethproofs.org/provers when checked on 2026-10-26. The Hypercube service has the same posting code, but no Zilkworm Hypercube cluster posts.

Three settings​

You turn posting on with three settings, and you need all three:

  • --ethproofs-endpoint: the API base URL. The service appends paths such as /proofs/queued to it.
  • --ethproofs-token: the API token, sent as Authorization: Bearer <token>.
  • --ethproofs-cluster-id: the numeric cluster id.

If any of them is unset, the service still proves but posts nothing. Posting only happens in --service mode, because the prove subcommands of both binaries never post. Both binaries also accept --post-every, though neither uses it.

The examples in docs/airbender-docker-service.md and prover/prover_airbender/README.md use the staging API, https://staging--ethproofs.netlify.app/api/v0. In the commands below, replace <endpoint> with the URL Ethproofs gives your cluster.

Each binary takes the settings in its own way:

  • z6m_prover_hypercube reads the three flags only.
  • z6m_prover_airbender reads the flags or the variables ETHPROOFS_ENDPOINT, ETHPROOFS_TOKEN and ETHPROOFS_CLUSTER_ID.
  • The Airbender image reads the three variables. If one is missing, its entrypoint unsets all three and logs that nothing is posted.

Posting lifecycle​

For each block it proves, the service sends three POST requests:

  1. /proofs/queued when the service picks the block, before it waits for the prover.
  2. /proofs/proving when proving starts.
  3. /proofs/proved after a successful proof.

queued and proving carry only block_number and cluster_id. proved carries five fields:

FieldContent
block_numberThe block number
cluster_idThe cluster id
proving_timeProving time in milliseconds, measured by the host
proving_cyclesThe guest's cycle count
proofThe proof file, base64-encoded

The proof file is proof.bin for Airbender and proof<N>.bin for Hypercube. For Airbender, proving_time leaves out fetching, witness conversion and the preflight. Airbender also posts a proof only after the preflight and the proof both commit the expected block hash.

Each request has a 60 s timeout, and queued and proving go out once. A proved post that gets a 429, a 5xx or no answer is tried up to four times in all. After a 429, the service waits as long as the body's retryAfter or the Retry-After header asks, or 30 s by default. After a 5xx or no answer it waits 10 s, and no wait is longer than 120 s. If a retry gets a 409, an earlier attempt already landed, so the service stops there.

Other errors are logged and not retried. Posts run in the background and never hold up proving, and a failed post leaves the proof on disk.

Cluster and verification key​

Ethproofs checks a cluster's proofs against the key registered for it. If your cluster runs the Airbender image, register z6m_guest_airbender.vk from the same release:

curl -LO https://github.com/erigontech/zilkworm/releases/download/v0.1.0-alpha.7/z6m_guest_airbender.vk
sha256sum z6m_guest_airbender.vk

The alpha.7 release notes give its sha256 as ffcdff786029d7f9621ad8c23ece641de9d72c38ecb1097d1d4b5e3e583c1de5. When your cluster moves to a new release image, it needs that release's key. On first start, the image's entrypoint also computes a key and logs its sha256.

Command examples​

Airbender image​

export RPC_URL=http://<execution-client>:8545
export ETHPROOFS_ENDPOINT=<endpoint>
export ETHPROOFS_TOKEN=<api-token>
export ETHPROOFS_CLUSTER_ID=<cluster-id>
docker run -d --name zilkworm-airbender --gpus all --restart unless-stopped \
  -v /srv/zilkworm-airbender:/data \
  -e RPC_URL -e PROVE_EVERY=100 \
  -e ETHPROOFS_ENDPOINT -e ETHPROOFS_TOKEN -e ETHPROOFS_CLUSTER_ID \
  ghcr.io/erigontech/zilkworm-airbender:v0.1.0-alpha.7

When posting is on, the entrypoint logs posting to Ethproofs at with the endpoint and cluster id. Proofs land in /srv/zilkworm-airbender/proofs/<N>/proof.bin, and Airbender prover covers the rest of the service.

Hypercube binary​

export RPC_URL=http://<execution-client>:8545
export ETHPROOFS_ENDPOINT=<endpoint>
export ETHPROOFS_TOKEN=<api-token>
export ETHPROOFS_CLUSTER_ID=<cluster-id>
SP1_PROVER=cuda ./z6m_prover_hypercube --service \
  --rpc-url "$RPC_URL" --data-dir data --prove-every 100 \
  --ethproofs-endpoint "$ETHPROOFS_ENDPOINT" \
  --ethproofs-token "$ETHPROOFS_TOKEN" \
  --ethproofs-cluster-id "$ETHPROOFS_CLUSTER_ID"

Proofs land in data/<N>/proof<N>.bin, and Hypercube prover covers the rest of the service.

Further reading​