cardano_crypto/vrf/

draft03.rs

//! VRF implementation following IETF draft-03 specification
//!
//! Implements **ECVRF-ED25519-SHA512-Elligator2** as defined in
//! [draft-irtf-cfrg-vrf-03](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-vrf-03).
//! This variant produces 80-byte proofs and provides full byte-for-byte compatibility
//! with Cardano's libsodium VRF implementation.
//!
//! # Specification Details
//!
//! - **Suite**: ECVRF-ED25519-SHA512-Elligator2
//! - **Curve**: Edwards25519 (Ed25519)
//! - **Hash Function**: SHA-512
//! - **Hash-to-Curve**: Elligator2 (for non-uniform hash-to-curve)
//! - **Proof Size**: 80 bytes (Gamma point 32 bytes + challenge 16 bytes + response 32 bytes)
//! - **Public Key Size**: 32 bytes
//! - **Secret Key Size**: 64 bytes (32-byte seed || 32-byte public key, Ed25519 format)
//! - **Output Size**: 64 bytes (SHA-512 hash)
//!
//! # Cardano Compatibility
//!
//! This implementation is **100% compatible** with Cardano's VRF as used in:
//! - Block production (VRF-based leader selection)
//! - Epoch nonce generation
//! - Praos consensus protocol
//!
//! All proofs generated by this library can be verified by Cardano nodes and vice versa.
//!
//! # Security
//!
//! - Constant-time operations for secret key material
//! - Automatic memory zeroization for sensitive data
//! - No unsafe code
//! - Extensively tested against official test vectors
//!
//! # Examples
//!
//! ```rust,ignore
//! use cardano_crypto::vrf::VrfDraft03;
//!
//! // Generate keypair from seed
//! let seed = [42u8; 32];
//! let (secret_key, public_key) = VrfDraft03::keypair_from_seed(&seed);
//!
//! // Generate proof
//! let message = b"Cardano block production";
//! let proof = VrfDraft03::prove(&secret_key, message)?;
//!
//! // Verify proof and get VRF output
//! let output = VrfDraft03::verify(&public_key, &proof, message)?;
//!
//! // Convert proof directly to hash (without verification)
//! let hash = VrfDraft03::proof_to_hash(&proof)?;
//! assert_eq!(&output[..], &hash[..]);
//! ```
//!
//! # Performance
//!
//! Typical operation times on modern hardware:
//! - Keypair generation: ~20μs
//! - Proof generation: ~1.2ms
//! - Proof verification: ~800μs
//!
//! # When to Use
//!
//! Use this variant when:
//! - You need Cardano compatibility
//! - Proof size (80 bytes) is acceptable
//! - You're working with existing Cardano infrastructure

use curve25519_dalek::{constants::ED25519_BASEPOINT_POINT, scalar::Scalar};
use sha2::{Digest, Sha512};
use zeroize::Zeroizing;

use crate::common::{clamp_scalar, point_to_bytes, CryptoResult, SUITE_DRAFT03, THREE};
use crate::vrf::cardano_compat::{cardano_vrf_prove, cardano_vrf_verify};

/// VRF proof size for draft-03: 80 bytes
///
/// Structure: Gamma (32 bytes) || c (16 bytes) || s (32 bytes)
/// - Gamma: Hashed message point on Edwards curve
///
/// # Example
///
/// ```rust
/// use cardano_crypto::vrf::{VrfDraft03, draft03::PROOF_SIZE};
///
/// # fn main() -> cardano_crypto::common::Result<()> {
/// // Generate a keypair
/// let seed = [1u8; 32];
/// let (sk, pk) = VrfDraft03::keypair_from_seed(&seed);
///
/// // Create a proof
/// let message = b"test message";
/// let proof = VrfDraft03::prove(&sk, message)?;
///
/// // Verify the proof length
/// assert_eq!(proof.len(), PROOF_SIZE);
/// # Ok(())
/// # }
/// ```
/// - c: Challenge scalar (truncated to 16 bytes)
/// - s: Response scalar
pub const PROOF_SIZE: usize = 80;

/// Ed25519 public key size: 32 bytes
///
/// Compressed Edwards curve point in standard Ed25519 format.
///
/// # Example
///
/// ```
/// use cardano_crypto::vrf::draft03::PUBLIC_KEY_SIZE;
///
/// assert_eq!(PUBLIC_KEY_SIZE, 32);
/// ```
pub const PUBLIC_KEY_SIZE: usize = 32;

/// Ed25519 secret key size: 64 bytes
///
/// Format: seed (32 bytes) || public_key (32 bytes)
/// This follows the Ed25519 expanded secret key format used by Cardano.
///
/// # Example
///
/// ```
/// use cardano_crypto::vrf::draft03::SECRET_KEY_SIZE;
///
/// assert_eq!(SECRET_KEY_SIZE, 64);
/// ```
pub const SECRET_KEY_SIZE: usize = 64;

/// Random seed size for keypair generation: 32 bytes
///
/// High-quality randomness is critical for security. Use a
/// cryptographically secure random number generator.
///
/// # Example
///
/// ```
/// use cardano_crypto::vrf::draft03::SEED_SIZE;
///
/// assert_eq!(SEED_SIZE, 32);
/// ```
pub const SEED_SIZE: usize = 32;

/// VRF output hash size: 64 bytes
///
/// SHA-512 hash of the VRF proof's Gamma point.
///
/// # Example
///
/// ```
/// use cardano_crypto::vrf::draft03::OUTPUT_SIZE;
///
/// assert_eq!(OUTPUT_SIZE, 64);
/// ```
pub const OUTPUT_SIZE: usize = 64;

/// VRF Draft-03 implementation (ECVRF-ED25519-SHA512-Elligator2)
///
/// Zero-sized type providing static methods for VRF operations following
/// the draft-03 specification. All methods are stateless and thread-safe.
///
/// # Cloning
///
/// This type is `Clone` but contains no data - clones are identical.
///
/// # Examples
///
/// ```rust,ignore
/// use cardano_crypto::vrf::VrfDraft03;
///
/// // All operations are static - no instance needed
/// let seed = [0u8; 32];
/// let (sk, pk) = VrfDraft03::keypair_from_seed(&seed);
/// ```
#[derive(Clone, Debug)]
pub struct VrfDraft03;

impl VrfDraft03 {
    /// Generates a VRF proof for the given message using the secret key
    ///
    /// Produces an 80-byte proof that can be verified by anyone with the corresponding
    /// public key. The proof binds the message to the secret key while maintaining
    /// the randomness properties required for VRF applications.
    ///
    /// # Arguments
    ///
    /// * `secret_key` - 64-byte Ed25519 expanded secret key (seed || public_key)
    /// * `message` - Arbitrary-length message to prove (typically a blockchain slot ID or similar)
    ///
    /// # Returns
    ///
    /// 80-byte proof on success containing (Gamma || c || s)
    ///
    /// # Errors
    ///
    /// Returns [`crate::common::error::CryptoError`] if:
    /// - Secret key is malformed or invalid
    /// - Internal cryptographic operations fail (extremely rare)
    ///
    /// # Security
    ///
    /// - Uses constant-time operations for secret key handling
    /// - Automatically zeroizes sensitive intermediate values
    /// - Safe against timing attacks
    ///
    /// # Examples
    ///
    /// ```rust,ignore
    /// use cardano_crypto::vrf::VrfDraft03;
    ///
    /// let seed = [1u8; 32];
    /// let (secret_key, public_key) = VrfDraft03::keypair_from_seed(&seed);
    ///
    /// let message = b"slot_12345";
    /// let proof = VrfDraft03::prove(&secret_key, message)?;
    ///
    /// assert_eq!(proof.len(), 80);
    /// ```
    ///
    /// # Panics
    ///
    /// May panic if internal cryptographic operations encounter invalid state
    /// (extremely unlikely in correct usage).
    pub fn prove(
        secret_key: &[u8; SECRET_KEY_SIZE],
        message: &[u8],
    ) -> CryptoResult<[u8; PROOF_SIZE]> {
        cardano_vrf_prove(secret_key, message)
    }

    /// Verifies a VRF proof and returns the deterministic VRF output
    ///
    /// Checks that the proof is cryptographically valid for the given public key
    /// and message. If verification succeeds, returns the deterministic 64-byte
    /// VRF output - a deterministic 64-byte value derived from the proof.
    ///
    /// # Arguments
    ///
    /// * `public_key` - 32-byte Ed25519 public key
    /// * `proof` - 80-byte VRF proof to verify
    /// * `message` - Message that was allegedly proven
    ///
    /// # Returns
    ///
    /// 64-byte VRF output (SHA-512 hash) on successful verification
    ///
    /// # Errors
    ///
    /// Returns [`crate::common::error::CryptoError`] if:
    /// - `InvalidPublicKey`: Public key is malformed or not on the curve
    /// - `InvalidProof`: Proof is malformed, wrong length, or contains invalid data
    /// - `VerificationFailed`: Proof is well-formed but cryptographically invalid
    ///
    /// # Examples
    ///
    /// ```rust,ignore
    /// use cardano_crypto::vrf::VrfDraft03;
    ///
    /// let seed = [2u8; 32];
    /// let (secret_key, public_key) = VrfDraft03::keypair_from_seed(&seed);
    ///
    /// let message = b"verify_this_message";
    /// let proof = VrfDraft03::prove(&secret_key, message)?;
    ///
    /// // Verify proof and get VRF output
    /// let output = VrfDraft03::verify(&public_key, &proof, message)?;
    /// assert_eq!(output.len(), 64);
    ///
    /// // Wrong message should fail verification
    /// assert!(VrfDraft03::verify(&public_key, &proof, b"wrong").is_err());
    /// ```
    pub fn verify(
        public_key: &[u8; PUBLIC_KEY_SIZE],
        proof: &[u8; PROOF_SIZE],
        message: &[u8],
    ) -> CryptoResult<[u8; OUTPUT_SIZE]> {
        cardano_vrf_verify(public_key, proof, message)
    }

    /// Extracts the VRF output hash directly from a proof without verification
    ///
    /// Computes the VRF output (SHA-512 hash of the Gamma point) from a proof
    /// **without verifying** its validity. This is useful when the proof has
    /// already been verified or when you need to extract the hash for other purposes.
    ///
    /// ⚠️ **WARNING**: This function does NOT verify the proof's authenticity.
    /// Use [`verify`](Self::verify) if you need cryptographic assurance.
    ///
    /// # Arguments
    ///
    /// * `proof` - 80-byte VRF proof
    ///
    /// # Returns
    ///
    /// 64-byte VRF output hash (same as what `verify` would return)
    ///
    /// # Errors
    ///
    /// Returns [`crate::common::error::CryptoError::InvalidProof`] if the proof is malformed
    ///
    /// # Examples
    ///
    /// ```rust,ignore
    /// use cardano_crypto::vrf::VrfDraft03;
    ///
    /// let seed = [3u8; 32];
    /// let (secret_key, public_key) = VrfDraft03::keypair_from_seed(&seed);
    ///
    /// let message = b"extract_hash_example";
    /// let proof = VrfDraft03::prove(&secret_key, message)?;
    ///
    /// // Extract hash without verification (fast)
    /// let hash = VrfDraft03::proof_to_hash(&proof)?;
    ///
    /// // Verify that it matches the verified output
    /// let verified_output = VrfDraft03::verify(&public_key, &proof, message)?;
    /// assert_eq!(hash, verified_output);
    /// ```
    pub fn proof_to_hash(proof: &[u8; PROOF_SIZE]) -> CryptoResult<[u8; OUTPUT_SIZE]> {
        use crate::common::bytes_to_point;
        use crate::vrf::cardano_compat::cardano_clear_cofactor;

        let gamma_bytes: [u8; 32] = proof[0..32]
            .try_into()
            .expect("proof gamma segment must be 32 bytes");

        let gamma = bytes_to_point(&gamma_bytes)?;
        let gamma_cleared = cardano_clear_cofactor(&gamma);

        let mut hasher = Sha512::new();
        hasher.update([SUITE_DRAFT03]);
        hasher.update([THREE]);
        hasher.update(point_to_bytes(&gamma_cleared));
        let hash = hasher.finalize();

        let mut output = [0u8; OUTPUT_SIZE];
        output.copy_from_slice(&hash);
        Ok(output)
    }

    /// Generate keypair from seed
    ///
    /// Derives a deterministic Ed25519 keypair from a 32-byte seed using SHA-512
    /// and standard Ed25519 scalar clamping.
    ///
    /// # Arguments
    ///
    /// * `seed` - 32-byte random seed (must be cryptographically secure)
    ///
    /// # Returns
    ///
    /// Tuple of (secret_key, public_key):
    /// - `secret_key`: 64 bytes (seed || public_key)
    /// - `public_key`: 32 bytes (compressed Edwards point)
    ///
    /// # Examples
    ///
    /// ```rust,ignore
    /// use cardano_crypto::vrf::VrfDraft03;
    ///
    /// let seed = [42u8; 32];
    /// let (secret_key, public_key) = VrfDraft03::keypair_from_seed(&seed);
    ///
    /// assert_eq!(secret_key.len(), 64);
    /// assert_eq!(public_key.len(), 32);
    /// ```
    #[must_use]
    pub fn keypair_from_seed(
        seed: &[u8; SEED_SIZE],
    ) -> ([u8; SECRET_KEY_SIZE], [u8; PUBLIC_KEY_SIZE]) {
        let mut hasher = Sha512::new();
        hasher.update(seed);
        let hash = hasher.finalize();

        let mut secret_scalar = Zeroizing::new([0u8; 32]);
        secret_scalar.copy_from_slice(&hash[0..32]);
        *secret_scalar = clamp_scalar(*secret_scalar);

        let scalar = Scalar::from_bytes_mod_order(*secret_scalar);
        let public_point = ED25519_BASEPOINT_POINT * scalar;
        let public_key = point_to_bytes(&public_point);

        let mut secret_key = [0u8; SECRET_KEY_SIZE];
        secret_key[0..32].copy_from_slice(seed);
        secret_key[32..64].copy_from_slice(&public_key);

        (secret_key, public_key)
    }
}

// ============================================================================
// VrfAlgorithm trait implementation
// ============================================================================

impl crate::vrf::VrfAlgorithm for VrfDraft03 {
    type SecretKey = [u8; SECRET_KEY_SIZE];
    type VerificationKey = [u8; PUBLIC_KEY_SIZE];
    type Proof = [u8; PROOF_SIZE];
    type Output = [u8; OUTPUT_SIZE];

    const ALGORITHM_NAME: &'static str = "ECVRF-ED25519-SHA512-Elligator2-Draft03";
    const SEED_SIZE: usize = SEED_SIZE;
    const SECRET_KEY_SIZE: usize = SECRET_KEY_SIZE;
    const VERIFICATION_KEY_SIZE: usize = PUBLIC_KEY_SIZE;
    const PROOF_SIZE: usize = PROOF_SIZE;
    const OUTPUT_SIZE: usize = OUTPUT_SIZE;

    fn keypair_from_seed(seed: &[u8; 32]) -> (Self::SecretKey, Self::VerificationKey) {
        VrfDraft03::keypair_from_seed(seed)
    }

    fn derive_verification_key(sk: &Self::SecretKey) -> Self::VerificationKey {
        let mut pk = [0u8; PUBLIC_KEY_SIZE];
        pk.copy_from_slice(&sk[32..64]);
        pk
    }

    fn prove(sk: &Self::SecretKey, message: &[u8]) -> CryptoResult<Self::Proof> {
        VrfDraft03::prove(sk, message)
    }

    fn verify(
        vk: &Self::VerificationKey,
        proof: &Self::Proof,
        message: &[u8],
    ) -> CryptoResult<Self::Output> {
        VrfDraft03::verify(vk, proof, message)
    }

    fn proof_to_hash(proof: &Self::Proof) -> CryptoResult<Self::Output> {
        VrfDraft03::proof_to_hash(proof)
    }

    fn raw_serialize_verification_key(vk: &Self::VerificationKey) -> &[u8] {
        vk.as_slice()
    }

    fn raw_deserialize_verification_key(bytes: &[u8]) -> Option<Self::VerificationKey> {
        if bytes.len() != PUBLIC_KEY_SIZE {
            return None;
        }
        let mut vk = [0u8; PUBLIC_KEY_SIZE];
        vk.copy_from_slice(bytes);
        Some(vk)
    }

    fn raw_serialize_proof(proof: &Self::Proof) -> &[u8] {
        proof.as_slice()
    }

    fn raw_deserialize_proof(bytes: &[u8]) -> Option<Self::Proof> {
        if bytes.len() != PROOF_SIZE {
            return None;
        }
        let mut proof = [0u8; PROOF_SIZE];
        proof.copy_from_slice(bytes);
        Some(proof)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_prove_verify_roundtrip() {
        let seed = [42u8; SEED_SIZE];
        let (sk, pk) = VrfDraft03::keypair_from_seed(&seed);
        let message = b"test message";

        let proof = VrfDraft03::prove(&sk, message).expect("prove failed");
        let output = VrfDraft03::verify(&pk, &proof, message).expect("verify failed");

        assert_eq!(output.len(), OUTPUT_SIZE);
    }

    #[test]
    fn test_verify_rejects_invalid_proof() {
        let seed = [42u8; SEED_SIZE];
        let (_sk, pk) = VrfDraft03::keypair_from_seed(&seed);
        let message = b"test message";

        let invalid_proof = [0u8; PROOF_SIZE];
        let result = VrfDraft03::verify(&pk, &invalid_proof, message);

        assert!(result.is_err());
    }

    #[test]
    fn test_proof_to_hash_deterministic() {
        let seed = [42u8; SEED_SIZE];
        let (sk, _pk) = VrfDraft03::keypair_from_seed(&seed);
        let message = b"test message";

        let proof = VrfDraft03::prove(&sk, message).expect("prove failed");
        let hash1 = VrfDraft03::proof_to_hash(&proof).expect("hash failed");
        let hash2 = VrfDraft03::proof_to_hash(&proof).expect("hash failed");

        assert_eq!(hash1, hash2);
    }

    #[test]
    fn test_keypair_generation() {
        let seed = [1u8; 32];
        let (sk, pk) = VrfDraft03::keypair_from_seed(&seed);

        // Check sizes
        assert_eq!(sk.len(), 64);
        assert_eq!(pk.len(), 32);

        // Check that secret key contains seed and public key
        assert_eq!(&sk[0..32], &seed);
        assert_eq!(&sk[32..64], &pk);
    }

    #[test]
    fn test_proof_sizes() {
        assert_eq!(PROOF_SIZE, 80);
        assert_eq!(SECRET_KEY_SIZE, 64);
        assert_eq!(PUBLIC_KEY_SIZE, 32);
        assert_eq!(OUTPUT_SIZE, 64);
        assert_eq!(SEED_SIZE, 32);
    }

    #[test]
    fn test_vrf_algorithm_trait() {
        use crate::hash::Blake2b256;
        use crate::vrf::VrfAlgorithm;

        let seed = [42u8; 32];
        let (sk, vk) = <VrfDraft03 as VrfAlgorithm>::keypair_from_seed(&seed);

        // Test trait constants
        assert_eq!(<VrfDraft03 as VrfAlgorithm>::SEED_SIZE, 32);
        assert_eq!(<VrfDraft03 as VrfAlgorithm>::SECRET_KEY_SIZE, 64);
        assert_eq!(<VrfDraft03 as VrfAlgorithm>::VERIFICATION_KEY_SIZE, 32);
        assert_eq!(<VrfDraft03 as VrfAlgorithm>::PROOF_SIZE, 80);
        assert_eq!(<VrfDraft03 as VrfAlgorithm>::OUTPUT_SIZE, 64);

        // Test prove/verify through trait
        let message = b"test message";
        let proof = <VrfDraft03 as VrfAlgorithm>::prove(&sk, message).unwrap();
        let output = <VrfDraft03 as VrfAlgorithm>::verify(&vk, &proof, message).unwrap();
        assert_eq!(output.len(), 64);

        // Test hash_verification_key
        let hash = <VrfDraft03 as VrfAlgorithm>::hash_verification_key::<Blake2b256>(&vk);
        assert_eq!(hash.len(), 32);

        // Different keys should have different hashes
        let seed2 = [43u8; 32];
        let (_, vk2) = <VrfDraft03 as VrfAlgorithm>::keypair_from_seed(&seed2);
        let hash2 = <VrfDraft03 as VrfAlgorithm>::hash_verification_key::<Blake2b256>(&vk2);
        assert_ne!(hash, hash2);
    }

    #[test]
    fn test_serialization_roundtrip() {
        use crate::vrf::VrfAlgorithm;

        let seed = [99u8; 32];
        let (sk, vk) = VrfDraft03::keypair_from_seed(&seed);
        let message = b"test";
        let proof = VrfDraft03::prove(&sk, message).unwrap();

        // Test verification key roundtrip
        let vk_bytes = <VrfDraft03 as VrfAlgorithm>::raw_serialize_verification_key(&vk);
        let vk_restored =
            <VrfDraft03 as VrfAlgorithm>::raw_deserialize_verification_key(vk_bytes).unwrap();
        assert_eq!(vk, vk_restored);

        // Test proof roundtrip
        let proof_bytes = <VrfDraft03 as VrfAlgorithm>::raw_serialize_proof(&proof);
        let proof_restored =
            <VrfDraft03 as VrfAlgorithm>::raw_deserialize_proof(proof_bytes).unwrap();
        assert_eq!(proof, proof_restored);
    }
}