Implement Zero-Knowledge Proof API Endpoints For Enhanced Privacy

Overview

The API client requires zero-knowledge proof generation and verification endpoints, which are currently missing on the ZHTP node. This deficiency prevents privacy-preserving credential verification, a crucial feature for modern applications. Zero-knowledge proofs (ZKPs) are cryptographic methods that enable a user to prove the truth of a statement to a verifier without revealing any information beyond the validity of the statement itself. This is particularly useful in scenarios where sensitive information needs to be verified without exposing the underlying data, such as verifying age, citizenship, or other credentials.

In the context of the ZHTP node, the absence of these endpoints means that users cannot leverage the benefits of ZKPs for privacy-sensitive operations. This limitation not only hinders the functionality of the API client but also restricts the potential use cases of the ZHTP node in privacy-focused applications. The implementation of ZKP API endpoints is thus essential for enhancing the privacy features of the platform and enabling a broader range of secure and confidential interactions. By adding these endpoints, the system can support functionalities that require proof of certain attributes without disclosing the actual attribute values, thereby safeguarding user privacy and data integrity.

To fully realize the benefits of ZKPs, it's important to understand their role in preserving privacy while still allowing for verification. For instance, a user might need to prove they are over 18 years old without revealing their exact age, or confirm their citizenship without disclosing their specific identity. These kinds of verifications are crucial in various applications, such as online voting, secure access control, and privacy-preserving data sharing. The successful implementation of ZKP API endpoints will therefore significantly enhance the utility and security of the ZHTP node, making it a more versatile and privacy-respecting platform.

Problem

The primary issue stems from the mismatch between the API client's expectations and the ZHTP node's capabilities. Specifically, the API client anticipates two critical endpoints: POST /api/v1/zkp/generate for generating ZK proofs and POST /api/v1/zkp/verify for verifying them, as outlined in Issue #6. However, the ZHTP node, while equipped with the lib-proofs library that offers ZK functionality, lacks the necessary HTTP API endpoints to expose these capabilities. This discrepancy creates a significant impediment to leveraging ZKPs within the system.

This absence of HTTP API endpoints effectively means that the ZK proof functionalities within lib-proofs are inaccessible to external applications and users interacting with the ZHTP node via the API. While the underlying cryptographic machinery is present, the lack of an interface to interact with it renders it unusable in practice. Consequently, the potential for privacy-preserving operations is severely curtailed, undermining a core principle of ZKPs: the ability to prove claims without revealing sensitive data.

The impact of this issue is substantial. Without these endpoints, users cannot utilize ZKPs to prove essential attributes like age or citizenship without disclosing the actual data. This limitation is particularly critical in contexts where privacy is paramount, such as identity verification or secure credential management. The inability to generate and verify ZK proofs via the API not only restricts the system's functionality but also poses a barrier to its adoption in privacy-focused applications. Thus, addressing this issue by implementing the required endpoints is a vital step in unlocking the full potential of the ZHTP node and ensuring its viability in privacy-conscious environments.

Background

Zero-knowledge proofs (ZKPs) are a groundbreaking cryptographic technique that allows one party (the prover) to demonstrate to another party (the verifier) that a statement is true, without revealing any information beyond the validity of the statement itself. This capability is crucial for applications requiring privacy and security, as it enables the verification of claims without exposing sensitive underlying data. The core principle behind ZKPs is to ensure that the verifier gains confidence in the truth of the statement without learning anything else about the prover's information.

ZKPs are especially valuable in scenarios where sensitive information needs to be verified without revealing the underlying data. For example, a user might want to prove that they are over 18 years old without disclosing their exact age, or demonstrate that they are a verified citizen without revealing their identity. In the digital world, these proofs can be used to verify identity, authenticate credentials, and enable secure transactions, all while maintaining user privacy. The flexibility and security offered by ZKPs make them a cornerstone of modern cryptographic applications.

In the context of privacy-preserving identity verification, ZKPs enable users to assert specific claims about themselves without revealing the actual data. This is particularly relevant in applications like online voting, secure access control, and privacy-preserving data sharing. By employing ZKPs, individuals can prove their eligibility or authorization without exposing personal details, thereby reducing the risk of identity theft and enhancing overall security. The ZHTP node's ability to support ZKPs is therefore essential for ensuring that users can interact with the system in a privacy-respecting manner. The implementation of ZKP API endpoints is a critical step towards realizing this goal, enabling the creation of applications that prioritize user privacy while maintaining robust security measures.

Required Endpoints

To fully integrate zero-knowledge proof functionality into the ZHTP node, two primary API endpoints are essential: /api/v1/zkp/generate for proof generation and /api/v1/zkp/verify for proof verification. These endpoints will serve as the primary interfaces for applications to interact with the ZKP capabilities of the system. The design and implementation of these endpoints must be carefully considered to ensure they are secure, efficient, and user-friendly.

1. POST /api/v1/zkp/generate

Purpose: This endpoint is designed to generate a zero-knowledge proof for a given credential. It allows users to prove certain attributes about themselves without revealing the underlying data. The request to this endpoint should include all the necessary information for proof generation, such as the identity of the user, the type of proof required, and the relevant credential data. The response will contain the generated ZK proof, along with any public inputs and the validity period for the proof.

Request:

{
  "identity_id": "...",
  "proof_type": "age_over_18",
  "credential_data": {
    "age": 25,
    "jurisdiction": "US"
  }
}

The request body includes the identity_id, which identifies the user for whom the proof is being generated. The proof_type specifies the type of proof required (e.g., age_over_18), and the credential_data provides the necessary information to generate the proof, such as the user's age and jurisdiction.

Response:

{
  "status": "success",
  "proof": {
    "proof_data": "...", // ZK proof bytes (base64)
    "public_inputs": ["..."], // Public values
    "proof_type": "age_over_18"
  },
  "valid_until": 1234567890
}

The response includes a status indicating the outcome of the request, a proof object containing the generated ZK proof data, public inputs, and the proof type. The proof_data is typically encoded in base64 format for easy transmission. The valid_until field specifies the timestamp until which the proof is considered valid, providing a mechanism for proof expiration and freshness checks.

2. POST /api/v1/zkp/verify

Purpose: This endpoint is used to verify a zero-knowledge proof. It takes a ZK proof as input and checks its validity against the specified public inputs. The response indicates whether the proof is valid, the claim being verified, and the timestamp of the verification.

Request:

{
  "proof": {
    "proof_data": "...",
    "public_inputs": ["..."],
    "proof_type": "age_over_18"
  }
}

The request body includes the proof object, which contains the proof data, public inputs, and the proof type. This information is used to perform the verification process.

Response:

{
  "status": "success",
  "valid": true,
  "claim": "age_over_18",
  "verified_at": 1234567890
}

The response includes a status indicating the outcome of the request, a valid field specifying whether the proof is valid, the claim that was verified (e.g., age_over_18), and the verified_at timestamp. A valid value of true confirms that the proof is valid, while false indicates that the proof failed verification.

The implementation of these endpoints will provide a comprehensive framework for generating and verifying ZK proofs, enabling a wide range of privacy-preserving applications within the ZHTP node.

Supported Proof Types (for Alpha)

For the initial Alpha release, it is crucial to focus on implementing the most essential proof types to ensure core functionality and privacy features are available. These proof types should address common use cases and provide a solid foundation for future expansion. The following proof types are prioritized for the Alpha release, categorized as essential and nice-to-have.

Essential for Alpha:

1. age_over_18 - This proof type allows users to prove that they are at least 18 years old without revealing their exact age. This is a fundamental requirement for many applications, such as age-restricted content access, online purchases of age-sensitive goods, and compliance with age-related regulations. The implementation of this proof type involves cryptographic techniques that can verify the age threshold without disclosing the precise age value. This ensures that users can maintain their privacy while still meeting the necessary verification requirements.

2. age_range - This proof type enables users to prove that their age falls within a specific range (e.g., 18-25) without revealing their exact age. This is particularly useful in scenarios where age-based criteria need to be met, but the precise age is not required. For instance, an application might need to verify that a user is within a certain age group for demographic analysis or eligibility for specific programs. The cryptographic protocols for this proof type ensure that only the range criteria are satisfied, without exposing the user's exact age, thus preserving their privacy.

3. citizenship_verified - This proof type allows users to prove that they are a verified citizen of a particular jurisdiction without revealing their identity or other personal details. This is crucial for applications that require citizenship verification, such as online voting, access to government services, and compliance with citizenship-based regulations. The implementation of this proof type involves cryptographic mechanisms that can verify the user's citizenship status without revealing their personal information, thereby ensuring privacy and security.

4. jurisdiction_membership - This proof type enables users to prove their membership in a specific jurisdiction without revealing any personal data or identity information. This is particularly useful in scenarios where jurisdictional requirements need to be verified, such as compliance with regional regulations, access to location-specific services, and participation in jurisdiction-based programs. The cryptographic techniques employed in this proof type ensure that only the membership status is verified, without exposing any other personal details, thus maintaining user privacy and data protection.

Nice to Have (Post-Alpha):

1. reputation_threshold - This proof type allows users to prove that their reputation score is above a certain threshold without revealing their exact score. This can be used in reputation systems to ensure that users meet a minimum reputation level for certain actions or privileges. The implementation involves cryptographic protocols that verify the threshold requirement without disclosing the actual reputation score, thereby preserving the user's privacy.

2. dao_member - This proof type enables users to prove their membership in a Decentralized Autonomous Organization (DAO) without revealing their identity or other membership details. This is crucial for secure governance and participation in DAO activities, such as voting and decision-making. The cryptographic mechanisms used in this proof type ensure that only the membership status is verified, without exposing any personal information, thereby maintaining user privacy and security within the DAO.

3. wallet_balance - This proof type allows users to prove that their wallet balance is above a certain amount without revealing their exact balance. This can be used in financial applications to verify that users meet a minimum balance requirement for certain transactions or services. The implementation involves cryptographic techniques that verify the balance threshold without disclosing the actual balance, thus preserving the user's financial privacy.

By prioritizing these proof types, the Alpha release will provide a robust set of privacy-preserving capabilities, laying the groundwork for more advanced features in subsequent releases. The essential proof types address fundamental requirements, while the nice-to-have proof types offer additional functionality that can be integrated based on user feedback and application needs.

Implementation Requirements

To successfully implement the zero-knowledge proof API endpoints, several key requirements must be addressed. These requirements span the utilization of existing libraries, the mechanics of proof generation and verification, security considerations, and error handling. A comprehensive approach to these aspects will ensure the robustness, security, and usability of the ZKP API.

1. Use Existing lib-proofs

The existing lib-proofs library already contains the necessary implementation for ZeroKnowledgeProof functionality. Leveraging this library is essential to avoid redundant development efforts and ensure consistency with existing cryptographic protocols. The primary task is to expose the functionalities of lib-proofs through the new HTTP API endpoints. This involves creating an interface between the API layer and the lib-proofs library, allowing external applications to utilize the ZKP capabilities seamlessly. The lib-proofs library should be treated as a core component, and any new implementation should integrate with it rather than duplicating its functionality.

2. Proof Generation

The process of generating a ZK proof involves several steps. First, the system must extract the relevant credential data from the user's identity. This data is the basis for the proof and must be securely accessed. Next, the system utilizes lib-proofs to generate the ZK proof based on the extracted credential data and the specified proof type. The generated proof must then be formatted into an API-friendly format, such as a JSON object containing the proof data, public inputs, and proof type. This formatted proof is then returned as part of the API response. The entire process must be efficient and secure to ensure timely proof generation and prevent unauthorized access to sensitive data.

3. Proof Verification

The verification of a ZK proof involves receiving a proof from a client, deserializing it, and then verifying its validity using lib-proofs. The proof, typically received in a JSON format, must be deserialized into a format that lib-proofs can process. The lib-proofs verifier is then used to check the proof against the specified public inputs. The result of the verification process is a boolean value indicating whether the proof is valid. This result, along with additional information such as the claim being verified, is then returned as part of the API response. The verification process must be robust and efficient to ensure accurate and timely proof validation.

4. Security

Security is a paramount concern in the implementation of ZKP API endpoints. Several measures must be taken to protect the system and user data. First, the proof type must be validated before generating a proof to prevent the generation of unsupported or malicious proofs. Second, the system must check that the user requesting the proof owns the credential before generating the proof to prevent unauthorized access to credentials. Third, proof expiration and freshness checks should be implemented to prevent the use of outdated or compromised proofs. Finally, rate limiting should be applied to proof generation to prevent abuse and denial-of-service attacks. These security measures are essential to ensure the integrity and reliability of the ZKP system.

5. Error Handling

Robust error handling is crucial for providing a user-friendly and reliable API. The API should return appropriate HTTP status codes and error messages for various failure scenarios. For example, if an invalid proof type is requested, the API should return a 400 Bad Request error. If a requested credential is not found, the API should return a 404 Not Found error. If proof verification fails, the API should return a 200 OK response with a valid field set to false. If the proof format is invalid, the API should return a 400 Bad Request error. Comprehensive error handling ensures that clients can effectively diagnose and respond to issues, improving the overall usability of the API.

Files to Modify

To implement the zero-knowledge proof API endpoints, specific files within the ZHTP node and the lib-proofs library will need to be modified. These modifications will involve creating new handlers, registering the handlers with the API, and potentially defining new API request/response types.

• zhtp/src/api/handlers/zkp.rs - This new file will contain the implementation of the ZKP handler functions. These handlers will be responsible for receiving API requests, processing them, interacting with the lib-proofs library, and constructing the API responses. The ZKP handler will include functions for both proof generation and proof verification, corresponding to the /api/v1/zkp/generate and /api/v1/zkp/verify endpoints, respectively. The handler functions will need to extract the necessary data from the request body, validate the input, call the appropriate functions from lib-proofs, and format the results into a JSON response.

• zhtp/src/server/api_registration.rs - This file will be modified to register the new ZKP handler functions with the API server. API registration involves adding the routes for the ZKP endpoints to the server's routing table, associating them with the corresponding handler functions. This ensures that incoming requests to /api/v1/zkp/generate and /api/v1/zkp/verify are correctly routed to the ZKP handler for processing. The registration process typically involves specifying the HTTP method (POST in this case), the URL path, and the handler function to be invoked.

• lib-proofs/src/api_types.rs - This file may need to be modified to define new API request and response types, if necessary. If the existing types in lib-proofs do not adequately represent the data required for the ZKP API, new types will need to be defined. This might include structures for representing proof generation requests, proof verification requests, and the corresponding responses. Defining these types ensures type safety and clarity in the API implementation, making it easier to work with and maintain. The new types should be carefully designed to accommodate the necessary data fields and formats for ZKP operations.

These file modifications are essential for integrating the ZKP functionality into the ZHTP node. The new ZKP handler will serve as the interface between the API and the lib-proofs library, while the API registration process ensures that the endpoints are accessible to clients. The potential modifications to api_types.rs will ensure that the data structures used by the API are well-defined and appropriate for ZKP operations.

Acceptance Criteria

To ensure that the implementation of the zero-knowledge proof API endpoints meets the required standards and functions correctly, specific acceptance criteria must be defined. These criteria serve as a checklist to verify that all aspects of the implementation are complete and working as expected.

• [ ] POST /api/v1/zkp/generate endpoint implemented - This criterion verifies that the /api/v1/zkp/generate endpoint is implemented and accessible. It includes ensuring that the endpoint can receive requests, process them correctly, and return appropriate responses. The implementation should adhere to the API specifications, including request and response formats, error handling, and security considerations.

• [ ] POST /api/v1/zkp/verify endpoint implemented - This criterion verifies that the /api/v1/zkp/verify endpoint is implemented and accessible. It includes ensuring that the endpoint can receive proof verification requests, process them correctly, and return appropriate responses indicating the validity of the proof. The implementation should follow the API specifications and include robust error handling and security measures.

• [ ] age_over_18 proof type supported - This criterion confirms that the system supports the age_over_18 proof type. This involves verifying that the system can generate and verify proofs for this type, ensuring that users can prove they are over 18 years old without revealing their exact age. The implementation should include the necessary cryptographic protocols and data handling mechanisms to support this proof type.

• [ ] citizenship_verified proof type supported - This criterion confirms that the system supports the citizenship_verified proof type. This involves verifying that the system can generate and verify proofs for citizenship verification, allowing users to prove their citizenship without revealing their identity or other personal details. The implementation should include the necessary cryptographic protocols and data handling mechanisms to support this proof type.

• [ ] Proof generation works with lib-proofs - This criterion verifies that the proof generation process correctly utilizes the lib-proofs library. It includes ensuring that the API handler functions can invoke the appropriate functions from lib-proofs to generate ZK proofs based on the provided credential data and proof type. The integration with lib-proofs should be seamless and efficient, leveraging the library's cryptographic capabilities.

• [ ] Proof verification works with lib-proofs - This criterion verifies that the proof verification process correctly utilizes the lib-proofs library. It includes ensuring that the API handler functions can invoke the verifier functions from lib-proofs to check the validity of ZK proofs. The verification process should be robust and accurate, correctly identifying valid and invalid proofs.

• [ ] API client ZK proof flow works end-to-end - This criterion verifies that the ZK proof flow works seamlessly from the API client perspective. It includes ensuring that the client can generate a proof request, send it to the /api/v1/zkp/generate endpoint, receive a proof, and then send the proof to the /api/v1/zkp/verify endpoint for verification. The entire flow should be tested to ensure that all components work together correctly and that the client receives the expected responses.

• [ ] Tests added for proof generation/verification - This criterion ensures that comprehensive tests are added for both proof generation and verification. These tests should cover various scenarios, including valid and invalid inputs, different proof types, and edge cases. The tests should be automated to ensure that the ZKP functionality remains robust and reliable as the system evolves.

• [ ] Documentation for supported proof types - This criterion ensures that clear and comprehensive documentation is provided for the supported proof types. The documentation should include details on the purpose of each proof type, the required inputs, the expected outputs, and any specific considerations for their use. Good documentation is essential for developers to understand and utilize the ZKP API effectively.

Priority

The implementation of the zero-knowledge proof API endpoints is considered P1 - HIGH priority. This designation reflects the critical importance of these endpoints for enabling privacy-preserving features within the system. While the Alpha release can proceed with a limited set of proof types, the core ZKP functionality is essential for achieving the desired level of privacy and security. The ability to generate and verify ZK proofs is fundamental for many use cases, such as identity verification, secure credential management, and privacy-preserving data sharing. Prioritizing this implementation ensures that the system can meet its core privacy goals and provide a robust foundation for future enhancements.

Related Issues

• API Client Issue: SOVEREIGN-NET/Sovereign-Network-API-Client#6
• Tracking Issue: SOVEREIGN-NET/Sovereign-Network-API-Client#11

Dependencies

• lib-proofs (already exists)
• Identity credentials system

Notes

For the Alpha release, a pragmatic approach is to start with just 2-3 basic proof types, such as age_over_18 and citizenship_verified. This allows for a focused effort on implementing and testing the core ZKP functionality. More advanced proof types can be added in subsequent releases, based on user feedback and application requirements. This phased approach ensures that the initial release is stable and reliable while laying the groundwork for future enhancements.

In conclusion, the implementation of zero-knowledge proof API endpoints is a crucial step in enhancing the privacy and security of the ZHTP node. By focusing on the essential proof types and leveraging the existing lib-proofs library, the system can provide a robust and privacy-respecting platform for a wide range of applications. For more information on zero-knowledge proofs, you can check out this resource.