@zkthings/range-proof-evm

Zero-Knowledge Range Proofs for EVM chains - Prove values are within ranges without revealing them.

Part of the zkSDK ecosystem - Simplified ZK development

Early Stage Project: This package is under active development. APIs may change as we improve the implementation.

What Range Proofs Do

Range proofs prove your value is within a range WITHOUT revealing the exact value.

The Power of Zero-Knowledge

Normal way (no privacy):

• Lender: "What's your credit score?"
• You: "My score is 720"
• Lender: "OK, approved for premium rate" (now they know your exact score)

Zero-knowledge way (private):

• Lender: "Prove your credit score is 650 or higher"
• You: generates proof
• Lender: "Proof valid, approved for premium rate" (they only know you qualify, not your exact 720 score)

Installation

npm install @zkthings/range-proof-evm
# or
bun add @zkthings/range-proof-evm

Quick Start

import { RangeProof } from '@zkthings/range-proof-evm';

// Initialize the range proof system
const rangeProof = new RangeProof();

// Prove you're 18+ without revealing exact age
const ageProof = await rangeProof.prove(25, 18, 255);

// Verify the proof
const isValid = await rangeProof.verify(ageProof);
console.log('Valid adult:', isValid); // true

// Export Solidity verifier for on-chain verification
const verifierContract = await rangeProof.exportSolidityVerifier(ageProof);
// Deploy this contract to your blockchain for on-chain verification

Complete API Reference

rangeProof.prove(value, minValue, maxValue, bitSize?)

Proves a value is within the specified range. Auto-detects optimal circuit size based on your maximum value.

// Age verification (0-255) → Auto-detects 8-bit circuit
const ageProof = await rangeProof.prove(25, 18, 255);

// Credit score (300-850) → Auto-detects 16-bit circuit  
const creditProof = await rangeProof.prove(720, 650, 850);

// Income verification ($50K-$500K) → Auto-detects 32-bit circuit
const incomeProof = await rangeProof.prove(85000, 50000, 500000);

// Test score (0-100) → Auto-detects 8-bit circuit
const testProof = await rangeProof.prove(92, 70, 100);

Circuit Selection Guide:

• 8-bit (max 255): Ages, percentages, grades, temperatures
• 16-bit (max 65,535): Credit scores, ratings, large percentages
• 32-bit (max 4.3B): Financial amounts, populations
• 64-bit (max 18E): Very large financial systems

Verification

// Simple verification (auto-detects bit size from proof)
const isValid = await rangeProof.verify(proof);

// Legacy verification (manual bit size)
const isValid = await rangeProof.verify(
  proof.proof,        // Proof object
  proof.publicSignals, // Public signals array
  proof.bitSize       // Bit size used (must match original)
);

Use Cases

Range proofs are useful for any scenario where you need to prove a value is within bounds without revealing the exact value:

• Age verification: Prove you're 18+ without revealing exact age
• Financial eligibility: Prove income/balance meets requirements
• Scores & ratings: Prove test scores, credit scores, or ratings are in valid ranges
• IoT & monitoring: Prove sensor readings are within acceptable ranges

Circuit Performance

Automatically optimized based on your values:

| Circuit | Max Value | Constraints | Proof Time | Use Cases | |---------|-----------|-------------|------------|-----------| | 8-bit | 255 | ~19 | ~50ms | Ages, percentages, temperatures | | 16-bit | 65,535 | ~35 | ~100ms | Credit scores, large percentages | | 32-bit | 4.3B | ~67 | ~200ms | Financial amounts, populations | | 64-bit | 18E | ~131 | ~500ms | Very large financial systems |

No need to choose manually - the library picks the optimal size automatically!

Advanced Configuration

Custom Circuit Location

import { RangeProof } from '@zkthings/range-proof-evm';

// Use custom zkConfig directory
const rangeProof = new RangeProof('/path/to/zkConfig');
await rangeProof.prove(25, 18, 255);

Manual Circuit Size (Advanced)

// Force specific circuit size (only if you need to optimize manually)
await rangeProof.prove(value, min, max, 16); // Force 16-bit circuit

Working with Negative Numbers

Range proofs work with positive numbers only. For negative ranges, use offsets:

// ❌ Wrong: Direct negative numbers
await rangeProof.prove(-5, -10, 10); // Will fail!

// ✅ Correct: Add offset to make positive
const temp = -5;          // -5°C
const tempOffset = temp + 20;  // Add 20: -5 + 20 = 15
await rangeProof.prove(15, 10, 30); // Range: -10°C to 10°C

Error Handling

try {
  // This will throw if value is outside range
  const proof = await rangeProof.prove(150, 0, 100);
} catch (error) {
  console.error('Value outside range:', error.message);
}

try {
  // This will throw if age > 255 (circuit limit)
  const proof = await rangeProof.prove(300, 18, 255);
} catch (error) {
  console.error('Age too large for circuit:', error.message);
}

Solidity Integration

Export verifier contracts for on-chain verification:

// Generate a proof first
const proof = await rangeProof.prove(25, 18, 255);

// Export verifier contract (auto-detects bit size from proof)
const verifierCode = await rangeProof.exportSolidityVerifier(proof);

// Save to file for deployment
import fs from 'fs';
fs.writeFileSync('RangeVerifier.sol', verifierCode);
// Now deploy RangeVerifier.sol to your blockchain

Security Considerations

What's Public vs Private

await rangeProof.prove(85000, 50000, 500000);
//                           ^^^^^  ^^^^^  ^^^^^^
//                           |      |      └── Public (max context)
//                           |      └─────── Public (min requirement)
//                           └────────────── Private (your secret!)

• ✅ Private: Your actual value (85000)
• ❌ Public: Range bounds (50000, 500000)
• ✅ Zero Knowledge: Verifier learns nothing about your actual value

Best Practices

1. Choose appropriate ranges - not too narrow, not too wide
2. Validate inputs before proof generation
3. Use HTTPS when transmitting proofs
4. Cache verification keys for better performance
5. Handle edge cases (exact min/max values)

Circuit Attribution

This implementation builds upon excellent work from the zero-knowledge community:

• Circom & snarkjs: Core ZK infrastructure by iden3
• Range proof patterns: Inspired by fluree/example-zero-knowledge
• Comparator circuits: Based on circomlib implementation
• zkSDK ecosystem: Part of the broader zkSDK toolkit

Development

Setup

git clone https://github.com/zkThings/range-proof-evm.git
cd range-proof-evm
bun install

Testing

# Compile circuits
bun run compile:circuits

# Run all tests
bun test

# Build package
bun run build

License

MIT License - see LICENSE file for details.

Part of zkSDK - Making zero-knowledge development simple and accessible for everyone.