feat: add marketplace metrics, privacy features, and service registry endpoints
- Add Prometheus metrics for marketplace API throughput and error rates with new dashboard panels - Implement confidential transaction models with encryption support and access control - Add key management system with registration, rotation, and audit logging - Create services and registry routers for service discovery and management - Integrate ZK proof generation for privacy-preserving receipts - Add metrics instru
This commit is contained in:
oib
260
docs/reference/zk-receipt-attestation.md
Normal file
260
docs/reference/zk-receipt-attestation.md
Normal file
@ -0,0 +1,260 @@
|
||||
# Zero-Knowledge Receipt Attestation Design
|
||||
|
||||
## Overview
|
||||
|
||||
This document outlines the design for adding zero-knowledge proof capabilities to the AITBC receipt attestation system, enabling privacy-preserving settlement flows while maintaining verifiability.
|
||||
|
||||
## Goals
|
||||
|
||||
1. **Privacy**: Hide sensitive transaction details (amounts, parties, specific computations)
|
||||
2. **Verifiability**: Prove receipts are valid and correctly signed without revealing contents
|
||||
3. **Compatibility**: Work with existing receipt signing and settlement systems
|
||||
4. **Efficiency**: Minimize proof generation and verification overhead
|
||||
|
||||
## Architecture
|
||||
|
||||
### Current Receipt System
|
||||
|
||||
The existing system has:
|
||||
- Receipt signing with coordinator private key
|
||||
- Optional coordinator attestations
|
||||
- History retrieval endpoints
|
||||
- Cross-chain settlement hooks
|
||||
|
||||
Receipt structure includes:
|
||||
- Job ID and metadata
|
||||
- Computation results
|
||||
- Pricing information
|
||||
- Miner and coordinator signatures
|
||||
|
||||
### Privacy-Preserving Flow
|
||||
|
||||
```
|
||||
1. Job Execution
|
||||
↓
|
||||
2. Receipt Generation (clear text)
|
||||
↓
|
||||
3. ZK Circuit Input Preparation
|
||||
↓
|
||||
4. ZK Proof Generation
|
||||
↓
|
||||
5. On-Chain Settlement (with proof)
|
||||
↓
|
||||
6. Verification (without revealing data)
|
||||
```
|
||||
|
||||
## ZK Circuit Design
|
||||
|
||||
### What to Prove
|
||||
|
||||
1. **Receipt Validity**
|
||||
- Receipt was signed by coordinator
|
||||
- Computation was performed correctly
|
||||
- Pricing follows agreed rules
|
||||
|
||||
2. **Settlement Conditions**
|
||||
- Amount owed is correctly calculated
|
||||
- Parties have sufficient funds/balance
|
||||
- Cross-chain transfer conditions met
|
||||
|
||||
### What to Hide
|
||||
|
||||
1. **Sensitive Data**
|
||||
- Actual computation amounts
|
||||
- Specific job details
|
||||
- Pricing rates
|
||||
- Participant identities
|
||||
|
||||
### Circuit Components
|
||||
|
||||
```circom
|
||||
// High-level circuit structure
|
||||
template ReceiptAttestation() {
|
||||
// Public inputs
|
||||
signal input receiptHash;
|
||||
signal input settlementAmount;
|
||||
signal input timestamp;
|
||||
|
||||
// Private inputs
|
||||
signal input receipt;
|
||||
signal input computationResult;
|
||||
signal input pricingRate;
|
||||
signal input minerReward;
|
||||
|
||||
// Verify receipt signature
|
||||
component signatureVerifier = ECDSAVerify();
|
||||
// ... signature verification logic
|
||||
|
||||
// Verify computation correctness
|
||||
component computationChecker = ComputationVerify();
|
||||
// ... computation verification logic
|
||||
|
||||
// Verify pricing calculation
|
||||
component pricingVerifier = PricingVerify();
|
||||
// ... pricing verification logic
|
||||
|
||||
// Output settlement proof
|
||||
settlementAmount <== minerReward + coordinatorFee;
|
||||
}
|
||||
```
|
||||
|
||||
## Implementation Plan
|
||||
|
||||
### Phase 1: Research & Prototyping
|
||||
1. **Library Selection**
|
||||
- snarkjs for development (JavaScript/TypeScript)
|
||||
- circomlib2 for standard circuits
|
||||
- Web3.js for blockchain integration
|
||||
|
||||
2. **Basic Circuit**
|
||||
- Simple receipt hash preimage proof
|
||||
- ECDSA signature verification
|
||||
- Basic arithmetic operations
|
||||
|
||||
### Phase 2: Integration
|
||||
1. **Coordinator API Updates**
|
||||
- Add ZK proof generation endpoint
|
||||
- Integrate with existing receipt signing
|
||||
- Add proof verification utilities
|
||||
|
||||
2. **Settlement Flow**
|
||||
- Modify cross-chain hooks to accept proofs
|
||||
- Update verification logic
|
||||
- Maintain backward compatibility
|
||||
|
||||
### Phase 3: Optimization
|
||||
1. **Performance**
|
||||
- Trusted setup for Groth16
|
||||
- Batch proof generation
|
||||
- Recursive proofs for complex receipts
|
||||
|
||||
2. **Security**
|
||||
- Audit circuits
|
||||
- Formal verification
|
||||
- Side-channel resistance
|
||||
|
||||
## Data Flow
|
||||
|
||||
### Proof Generation (Coordinator)
|
||||
|
||||
```python
|
||||
async def generate_receipt_proof(receipt: Receipt) -> ZKProof:
|
||||
# 1. Prepare circuit inputs
|
||||
public_inputs = {
|
||||
"receiptHash": hash_receipt(receipt),
|
||||
"settlementAmount": calculate_settlement(receipt),
|
||||
"timestamp": receipt.timestamp
|
||||
}
|
||||
|
||||
private_inputs = {
|
||||
"receipt": receipt,
|
||||
"computationResult": receipt.result,
|
||||
"pricingRate": receipt.pricing.rate,
|
||||
"minerReward": receipt.pricing.miner_reward
|
||||
}
|
||||
|
||||
# 2. Generate witness
|
||||
witness = generate_witness(public_inputs, private_inputs)
|
||||
|
||||
# 3. Generate proof
|
||||
proof = groth16.prove(witness, proving_key)
|
||||
|
||||
return {
|
||||
"proof": proof,
|
||||
"publicSignals": public_inputs
|
||||
}
|
||||
```
|
||||
|
||||
### Proof Verification (On-Chain/Settlement Layer)
|
||||
|
||||
```solidity
|
||||
contract SettlementVerifier {
|
||||
// Groth16 verifier
|
||||
function verifySettlement(
|
||||
uint256[2] memory a,
|
||||
uint256[2][2] memory b,
|
||||
uint256[2] memory c,
|
||||
uint256[] memory input
|
||||
) public pure returns (bool) {
|
||||
return verifyProof(a, b, c, input);
|
||||
}
|
||||
|
||||
function settleWithProof(
|
||||
address recipient,
|
||||
uint256 amount,
|
||||
ZKProof memory proof
|
||||
) public {
|
||||
require(verifySettlement(proof.a, proof.b, proof.c, proof.inputs));
|
||||
// Execute settlement
|
||||
_transfer(recipient, amount);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Privacy Levels
|
||||
|
||||
### Level 1: Basic Privacy
|
||||
- Hide computation amounts
|
||||
- Prove pricing correctness
|
||||
- Reveal participant identities
|
||||
|
||||
### Level 2: Enhanced Privacy
|
||||
- Hide all amounts
|
||||
- Zero-knowledge participant proofs
|
||||
- Anonymous settlement
|
||||
|
||||
### Level 3: Full Privacy
|
||||
- Complete transaction privacy
|
||||
- Ring signatures or similar
|
||||
- Confidential transfers
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **Trusted Setup**
|
||||
- Multi-party ceremony for Groth16
|
||||
- Documentation of setup process
|
||||
- Toxic waste destruction proof
|
||||
|
||||
2. **Circuit Security**
|
||||
- Constant-time operations
|
||||
- No side-channel leaks
|
||||
- Formal verification where possible
|
||||
|
||||
3. **Integration Security**
|
||||
- Maintain existing security guarantees
|
||||
- Fail-safe verification
|
||||
- Gradual rollout with monitoring
|
||||
|
||||
## Migration Strategy
|
||||
|
||||
1. **Parallel Operation**
|
||||
- Run both clear and ZK receipts
|
||||
- Gradual opt-in adoption
|
||||
- Performance monitoring
|
||||
|
||||
2. **Backward Compatibility**
|
||||
- Existing receipts remain valid
|
||||
- Optional ZK proofs
|
||||
- Graceful degradation
|
||||
|
||||
3. **Network Upgrade**
|
||||
- Coordinate with all participants
|
||||
- Clear communication
|
||||
- Rollback capability
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Research Task**
|
||||
- Evaluate zk-SNARKs vs zk-STARKs trade-offs
|
||||
- Benchmark proof generation times
|
||||
- Assess gas costs for on-chain verification
|
||||
|
||||
2. **Prototype Development**
|
||||
- Implement basic circuit in circom
|
||||
- Create proof generation service
|
||||
- Build verification contract
|
||||
|
||||
3. **Integration Planning**
|
||||
- Design API changes
|
||||
- Plan data migration
|
||||
- Prepare rollout strategy
|
||||
Reference in New Issue
Block a user