API

Workflow

Participants: Customer | ZEROBASE Hub | Prover Nodes

1. Request Node List

• Customer submits a proof‐generation request to the ZEROBASE Hub, including the circuit ID, inputs and payment credentials.
• Hub records the task, issues a unique UUID, and returns it to the Customer.

2. Respond Node List

• Hub and Prover Nodes exchange periodic heartbeat messages to confirm node health.
• Hub selects a pseudo-random subset (e.g. 4) of available nodes.
• Hub returns the chosen nodes’ gRPC endpoints to the Customer.

3. Send Proof Generation Tasks

• Customer invokes GenerateProof(taskID, inputs) in parallel on each selected node.
• Each Prover:
  1. (If in payment-verified mode) validates on-chain payment status.
  2. Executes the circuit to derive the zero-knowledge proof and witness.

4. Respond Proofs

• Prover Nodes transmit the computed proof and witness back to the Customer via gRPC.

Role Description

ZEROBASE Hub

The ZEROBASE Hub is the core module of the network, responsible for task broadcasting, Prover node scheduling, user request handling, and node communication management. Before submitting a zero-knowledge proof request, users must first register their task. Once registration is successful, the Hub broadcasts the task across the network and randomly selects Prover nodes to generate the proof. The Hub also manages the node list, processes heartbeat packets, and handles payment workflows.

Prover Node

Prover nodes are responsible for generating ZK-SNARK proofs by receiving input data and performing the necessary computations. They periodically send heartbeat packets to update their status. Prover nodes support both a basic mode and a payment-verified mode. In basic mode, they generate proofs directly; in payment-verified mode, they must first confirm the payment status before proceeding. By transmitting heartbeat packets, the nodes help maintain system stability. This architecture enables high-performance scheduling of ZK computation tasks.

Pre-request

Install gRPC Tools

Install grpcio-tools to generate gRPC code:

pip install grpcio-tools

Get Prover Node

Example Request:

curl -X GET "https://prove-api.zerobase.pro/api/v1/hub/node"

Example Response:

{"code":0,"msg":"Successfully","results":[{"grpc_info":{"address":"","timestamp":1750351910},"http_info":{"address":"","timestamp":1750351910},"poh":"622b40c2431bd60508f46e232c17de82bf8b083c85cf6bc638a643c80942e099"}],"proof_hash":"0x683a8622e80caaf9bbcc58b45ebe803bdc82a381216188ff620fc023c04f2b54"}

Generate gRPC Code

Use protoc to generate Python service and message handling code.

python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. prove.proto

// File: prove_service_v2.proto
// Description: ProveService gRPC definitions for zero-knowledge proof generation,

syntax = "proto3";

package prove_service.v2;

import "google/protobuf/empty.proto";

message GenerateProofRequest {
  string prover = 1;
  string circuit_template_id = 2;
  string payload = 3;
  int32 length = 4;
  bool is_encrypted = 5;
  string auth_token = 6;
  int32 task_type = 7;
  string oauth_provider = 8;
  string proof_hash = 9;
}

message GenerateProofResponse {
  int32 code = 1;
  string msg = 2;
  string proof = 3;
  string proof_solidity = 4;
  bytes proof_bytes = 5;
  string public_witness = 6;
  bytes public_witness_bytes = 7;
}

message GetPublicKeyResponse {
  int32 code = 1;
  string msg = 2;
  string public_key = 3;
}

service ProveService {
  rpc Prove(GenerateProofRequest) returns (GenerateProofResponse);
  rpc GetPublicKey(google.protobuf.Empty) returns (GetPublicKeyResponse);
  rpc Ping(google.protobuf.Empty) returns (google.protobuf.Empty);
}

Params

GenerateProofRequest

Field	Type	Required	Description
prover	string	Yes	Prover identifier
circuit_template_id	string	Yes	Circuit template ID
payload	string	Yes	Input data
length	int32	Yes	For nosha256
is_encrypted	bool	No	Whether the payload is encrypted (default: false)
auth_token	string	Yes	Authentication token (see Authentication section)
task_type	string	No	Business-defined task type
oauth_provider	string	No	OAuth provider name (default: google)
proof_hash	string	Yes	Fetch this parameter from the Hub API

GenerateProofResponse

Field	Type	Required	Description
code	int32	Yes	Response code (0 = success; see Status Code section)
msg	string	Yes	Human-readable message
proof	string	Yes	String proof
proof_solidity	string	Yes	Proof for smart contract verification
proof_bytes	bytes	Yes	Raw proof bytes
public witness	string	Yes	String Public witness
public_witness_byte	bytes	Yes	Raw public witness bytes

Status Code

STATUS_CODE	VALUE
STATUS_CODE_SUCCESSFULLY	0
STATUS_CODE_ERROR	-1
STATUS_CODE_TASK_NOT_FOUND	1000
STATUS_CODE_TASK_INVALID	1001
STATUS_CODE_UNSUPPORT_TASK_TYPE	1002
STATUS_CODE_UNSUPPORT_PROVER	1003
STATUS_CODE_UNSUPPORT_OAUTH_PROVIDER	1004
STATUS_CODE_UNAUTHORIZED_PAYLOAD	1005
STATUS_CODE_PROVER_NOT_RESPONSE	1006
STATUS_CODE_PUBLIC_KEY_NOT_FOUND	2000
STATUS_CODE_PUBLIC_KEY_INVALID	2001
STATUS_CODE_PRIVATE_KEY_NOT_FOUND	2002
STATUS_CODE_PRIVATE_KEY_INVALID	2003
STATUS_CODE_UNSUPPORT_CIRCUIT	100000
STATUS_CODE_GPU_DEVICE_ERROR	100001
STATUS_CODE_SHA256_NOT_MATCH	100002
STATUS_CODE_JSON_FROMAT_ERROR	100003
STATUS_CODE_INVALID_INPUT	100004
STATUS_CODE_TO_WITNESS_ERROR	100005
STATUS_CODE_TO_SECRET_WITNESS_ERROR	100006
STATUS_CODE_TO_PUBLIC_WITNESS_ERROR	100007
STATUS_CODE_GENERATE_PROOF_ERROR	100008

Pricing Table

We do not offer free proof generation for commercial circuits. The fee is intended to encourage you to approach circuit development with a focus on validity. However, we do offer free circuit generation for public goods. Please feel free to email me directly at: [email protected]

Service	Cost
Circuit Deployment & Distribution	1000 USD/one-time
Network Resource Usage Base Fee	50 USD/month
Proof Generation <10K proofs/month	0.01 USD/proof
Proof Generation 10K-100K proofs/month	0.008 USD/proof
Proof Generation 100K-1M proofs/month	0.005 USD/proof
Proof Generation >1M proofs/month	Contact Sales