Cryptography Guide

A zero-knowledge proof system for private transactions using SP1 zkVM, combining Ethereum compatibility with ZK-efficient cryptography.

Overview

This system provides cryptographic primitives for building privacy-preserving transactions with:

• Hidden Amounts: Pedersen commitments on Ristretto curve

• Hidden Senders: Ring signatures (LSAG variant)

• Hidden Receivers: Stealth addresses for Ethereum (secp256k1)

• Curve Bridge: Convert between secp256k1 and Ristretto curves

• ZK Proofs: SP1-based SNARK proofs for Ethereum verification

Architecture

Features

Pedersen Commitments

Hide transaction amounts while maintaining verifiability.

use cryptography_crypto::{commit, verify_commitment, generate_blinding};

// Commit to an amount
let amount = 100u64;
let blinding = generate_blinding();
let commitment = commit(amount, &blinding);

// Verify commitment
assert!(verify_commitment(&commitment, amount, &blinding));

// Homomorphic addition (C1 + C2 = C(amount1 + amount2))
let c1 = commit(50, &blinding1);
let c2 = commit(30, &blinding2);
let c_sum = c1.add(&c2); // Commitment to 80

Ring Signatures

Hide transaction sender within an anonymity set.

use cryptography_crypto::{sign_ring, verify_ring};
use curve25519_dalek::{constants::RISTRETTO_BASEPOINT_POINT, scalar::Scalar};

// Create a ring of public keys
let public_keys = vec![pk1, pk2, pk3, pk4, pk5]; // 5 possible senders

// Sign as one member (index 2) without revealing which one
let secret_key = /* your private key */;
let secret_index = 2;
let message = b"transfer 100 tokens";

let signature = sign_ring(message, &secret_key, secret_index, &public_keys);

// Anyone can verify, but cannot determine which member signed
assert!(verify_ring(&signature, message, &public_keys));

// Key image prevents double-spending (same for all sigs from same key)
let key_image = signature.key_image;

Ethereum Stealth Addresses

Hide transaction receiver using stealth address generation on secp256k1.

use cryptography_crypto::{generate_stealth_eth, scan_stealth_eth, EthKeyPair};

// Recipient generates view and spend key pairs
let view_keypair = EthKeyPair::random().unwrap();
let spend_keypair = EthKeyPair::random().unwrap();

// Sender creates a stealth address for the recipient
let (stealth_addr, ephemeral_secret) = generate_stealth_eth(
    &view_keypair.public,
    &spend_keypair.public
).unwrap();

// Get the stealth Ethereum address (0x...)
let stealth_eth_address = format_address(&stealth_addr.stealth_address);

// Recipient scans for their stealth payments
let found_key = scan_stealth_eth(
    &stealth_addr,
    &view_keypair.secret,
    &spend_keypair.public
).unwrap();

if found_key.is_some() {
    // This stealth address belongs to us!
    // Use found_key to spend the funds
}

Curve Bridge Functions

Convert between Ethereum's secp256k1 and Ristretto curves for ZK proofs.

use cryptography_crypto::{secp256k1_to_ristretto, address_to_ristretto};
use secp256k1::PublicKey;

// Convert Ethereum public key to Ristretto point
let eth_pubkey: PublicKey = /* secp256k1 public key */;
let ristretto_point = secp256k1_to_ristretto(&eth_pubkey);

// Convert Ethereum address to Ristretto point
let eth_address: EthAddress = [0x42; 20];
let point = address_to_ristretto(&eth_address);

// Use in ring signatures or commitments
let public_keys = vec![ristretto_point, /* other points */];

Getting Started

Prerequisites

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install SP1
curl -L https://sp1.succinct.xyz | bash
sp1up

Build & Run

# Clone repository
git clone https://github.com/GelapLabs/gelap-cryptography.git
cd gelap-cryptography

# Build all workspace members
cargo build --release

# Run tests
cargo test --all

API Reference

Pedersen Commitments

// Create commitment
pub fn commit(amount: u64, blinding: &Scalar) -> PedersenCommitment

// Verify commitment
pub fn verify_commitment(
    commitment: &PedersenCommitment,
    amount: u64,
    blinding: &Scalar
) -> bool

// Generate random blinding factor
pub fn generate_blinding() -> Scalar

// Homomorphic operations
impl PedersenCommitment {
    pub fn add(&self, other: &Self) -> Self
    pub fn sub(&self, other: &Self) -> Self
    pub fn to_bytes(&self) -> [u8; 32]
    pub fn from_bytes(bytes: &[u8; 32]) -> Result<Self>
}

Ring Signatures

// Sign message with ring
pub fn sign_ring(
    message: &[u8],
    secret_key: &Scalar,
    secret_index: usize,
    public_keys: &[RistrettoPoint]
) -> RingSignature

// Verify ring signature
pub fn verify_ring(
    signature: &RingSignature,
    message: &[u8],
    public_keys: &[RistrettoPoint]
) -> bool

impl RingSignature {
    pub fn to_bytes(&self) -> Vec<u8>
    pub fn from_bytes(bytes: &[u8]) -> Result<Self>
    pub key_image: RistrettoPoint // For double-spend prevention
}

Ethereum Stealth Addresses

// Generate stealth address
pub fn generate_stealth_eth(
    recipient_view_pubkey: &PublicKey,
    recipient_spend_pubkey: &PublicKey,
) -> Result<(StealthAddressEth, SecretKey)>

// Scan for stealth payments
pub fn scan_stealth_eth(
    stealth_addr: &StealthAddressEth,
    view_secret: &SecretKey,
    spend_pubkey: &PublicKey,
) -> Result<Option<SecretKey>>

// Utility functions
pub fn pubkey_to_address(pubkey: &PublicKey) -> EthAddress
pub fn format_address(address: &EthAddress) -> String
pub fn parse_address(s: &str) -> Result<EthAddress>
pub fn checksum_address(address: &EthAddress) -> String // EIP-55

Curve Bridge

// Convert secp256k1 pubkey to Ristretto point
pub fn secp256k1_to_ristretto(pubkey: &PublicKey) -> RistrettoPoint

// Convert Ethereum address to Ristretto point
pub fn address_to_ristretto(address: &EthAddress) -> RistrettoPoint

// Generic hash to Ristretto point
pub fn hash_to_ristretto(data: &[u8]) -> RistrettoPoint

Utilities

// Hash functions
pub fn hash_sha256(data: &[u8]) -> [u8; 32]
pub fn hash_keccak256(data: &[u8]) -> [u8; 32]

// Hex conversion
pub fn to_hex(data: &[u8]) -> String
pub fn from_hex(s: &str) -> Result<Vec<u8>, String>

// Random generation
pub fn random_bytes<const N: usize>() -> [u8; N]

Data Types for Solidity

Commitment (32 bytes)

Compressed Ristretto point: bytes32

Key Image (32 bytes)

Compressed Ristretto point: bytes32
Used for double-spend prevention

Ring Signature (variable size)

struct RingSignature {
    bytes32 keyImage;
    bytes32[] c;  // Challenge scalars (n elements)
    bytes32[] r;  // Response scalars (n elements)
}
// Total size: 32 + 32*n + 32*n bytes for ring of size n

SP1 Proof Generation

For detailed instructions on building and running the SP1 prover, see the SP1 Prover Guide.

Quick Reference

# Generate an SP1 Core Proof
cd prover
cargo run --release -- --prove

# Generate an EVM-Compatible Proof (requires 16GB+ RAM)
cargo run --release --bin evm -- --system groth16

# Retrieve the Verification Key
cargo run --release --bin vkey

Security Considerations

Cryptographic Guarantees

• Hiding: Commitments reveal nothing about amounts

• Binding: Cannot change committed amount after creation

• Anonymity: Ring signatures hide signer in anonymity set

• Linkability: Same key creates same key image (prevent double-spend)

• Unforgeability: Cannot forge signature without private key

For Solidity Developers

1. Always check key images: Prevent double-spending by tracking used key images

2. Validate commitment balance: Ensure input commitments = output commitments

3. Store verification key: Use immutable PROGRAM_VKEY from prover

4. Gas optimization: Batch verify multiple proofs when possible

5. Upgrade path: Use proxy pattern for verifier contract

Testing

# Run all tests
cargo test --all

# Run specific module tests
cargo test --package cryptography-crypto

# Run with output
cargo test -- --nocapture

# Test ring signatures
cargo test --package cryptography-crypto ring_signature

# Test Pedersen commitments
cargo test --package cryptography-crypto pedersen

Performance

Pedersen Commitments

• Create: ~50 μs

• Verify: ~50 μs

• Serialize: 32 bytes

Ring Signatures

• Sign (ring size 8): ~2 ms

• Verify (ring size 8): ~2 ms

• Serialize: 32 + 64*n bytes (n = ring size)

ZK Proof Generation (Estimated)

• Local proving: ~30-60 seconds

• Network proving: ~10-20 seconds

• Proof size: ~200 KB (Groth16)

Roadmap

• Pedersen commitments

• Ring signatures (LSAG with key images)

• Ethereum stealth addresses (secp256k1)

• Curve bridge (secp256k1 ↔ Ristretto)

• Unified zkproof module

• SP1 zkVM circuit implementation (transaction verification)

• LSAG ring signature generation with proper cryptographic validation

• Prover service with network support (Groth16/PLONK)

• EVM-compatible proof generation

• Solidity verifier contracts

• Transaction format & serialization

• SDK for wallet integration

References

• SP1 Documentation

• Curve25519-Dalek

• Ring Signatures

• Pedersen Commitments