Zero-Knowledge Proof (ZKP) Module Documentation

This documentation provides an overview of the available API endpoints for generating, verifying, retrieving, and deleting zero-knowledge proofs (ZKP) using the Bulletproofs protocol.

API Endpoints

1. Generate Proof

Endpoint: POST /generate

Description:
This endpoint generates a zero-knowledge proof based on a provided secret. The proof, along with a blinding factor, is stored in the RocksDB database. The blinding factor is a random value used to ensure the privacy of the committed secret.

Request Payload:

{
  "secret": "string"
}

secret: The secret string for which the proof will be generated. This should be a valid UUID.

Response:

{
  "proof": "base64-encoded proof",
  "blinding": "base64-encoded blinding factor"
}

proof: The generated zero-knowledge proof in base64 format.
blinding: The blinding factor used during proof generation in base64 format.

2. Verify Proof

Endpoint: POST /verify

Description: This endpoint verifies the validity of a zero-knowledge proof for a given secret using the stored blinding factor. It returns whether the proof is valid or not.

Request Payload:

{
  "secret": "string",
  "proof": "base64-encoded proof",
  "blinding": "base64-encoded blinding factor"
}

secret: The secret string associated with the proof.
proof: The zero-knowledge proof in base64 format.
blinding: The blinding factor used during proof generation in base64 format.

Response:

{
  "valid": true or false
}

valid: A boolean indicating whether the proof is valid.

3. Retrieve Receipt

Endpoint: GET /receipt/{secret}

Description: This endpoint retrieves the receipt for a given secret, including the proof, blinding factor, verification result, and the timestamp when the proof was verified.

Path Parameter:

secret: The secret string (UUID) for which the receipt is requested.

Response:

{
  "proof": "base64-encoded proof",
  "blinding": "base64-encoded blinding factor",
  "valid": true or false,
  "verified_at": "ISO 8601 timestamp or null"
}

proof: The zero-knowledge proof in base64 format.
blinding: The blinding factor used during proof generation in base64 format.
valid: A boolean indicating whether the proof was verified successfully.
verified_at: The timestamp of when the proof was verified, or null if not verified.

4. Delete Proof

Endpoint: DELETE /delete

Description: This endpoint deletes a zero-knowledge proof from the database. The proof is only deleted if it is verified to be valid using the stored blinding factor and secret.

Request Payload:

{
  "secret": "string",
  "proof": "base64-encoded proof",
  "blinding": "base64-encoded blinding factor"
}

secret: The secret string associated with the proof.
proof: The zero-knowledge proof in base64 format.
blinding: The blinding factor used during proof generation in base64 format.

Response:

{
  "valid": true or false
}

valid: A boolean indicating whether the proof was valid before it was deleted.

Usage Example

Generate a Proof: Send a POST /generate request with a secret string to generate and store a proof.
Verify a Proof: Send a POST /verify request with the secret, proof, and blinding factor to verify the proof.
Retrieve a Receipt: Send a GET /receipt/{secret} request to retrieve the receipt containing the proof, its validity, and verification timestamp.
Delete a Proof: Send a DELETE /delete request with the secret, proof, and blinding factor to delete the proof from the database if it is valid.

These endpoints are designed to facilitate secure proof generation and verification processes, ensuring the privacy and integrity of the secret values being handled.

´´´

Endpoint Details

1. Generate Proof

Usage Example:

To generate a zero-knowledge proof, you would send a POST request to the /generate endpoint with the following JSON payload:

{
  "secret": "550e8400-e29b-41d4-a716-446655440000"
}

Expected Response:

{
  "proof": "base64-encoded proof",
  "blinding": "base64-encoded blinding factor"
}

This response contains the generated proof and the blinding factor in base64 format. The proof and blinding factor are also stored in the RocksDB database associated with the provided secret.

2. Verify Proof

Usage Example:

To verify the proof, send a POST request to the /verify endpoint with the following JSON payload:

{
  "secret": "550e8400-e29b-41d4-a716-446655440000",
  "proof": "base64-encoded proof",
  "blinding": "base64-encoded blinding factor"
}

Expected Response:

{
  "valid": true
}

This response indicates whether the provided proof is valid. If valid, the proof is marked as verified in the database, and the verification timestamp is updated.

3. Retrieve Receipt

Usage Example:

To retrieve a receipt for a proof, send a GET request to the /receipt/{secret} endpoint, where {secret} is replaced with the actual secret (UUID).

Example Request:

GET /receipt/550e8400-e29b-41d4-a716-446655440000

Expected Response:

{
  "proof": "base64-encoded proof",
  "blinding": "base64-encoded blinding factor",
  "valid": true,
  "verified_at": "2024-08-31T12:34:56Z"
}

This response includes the proof, blinding factor, validity status, and the timestamp when the proof was verified. If the proof has not been verified, the verified_at field will be null.

4. Delete Proof

Usage Example:

To delete a proof, send a DELETE request to the /delete endpoint with the following JSON payload:

{
  "secret": "550e8400-e29b-41d4-a716-446655440000",
  "proof": "base64-encoded proof",
  "blinding": "base64-encoded blinding factor"
}

Expected Response:

{
  "valid": true
}

This response indicates whether the proof was valid before it was deleted. If the proof is valid, it will be removed from the database.

Summary

These endpoints provide a complete lifecycle for managing zero-knowledge proofs, from generation and verification to retrieval and deletion. The integration with the RocksDB database ensures that proofs and their verification statuses are securely stored and can be retrieved as needed.

This continuation completes the API documentation, covering all the endpoints available for interacting with zero-knowledge proofs using the Bulletproofs protocol. Each section provides usage examples and expected responses, making it easier for developers to integrate and use these features in their applications.

Simulation Synnq NQA