torvyon-core 0.1.3

Keys, addresses, post-quantum signing and transaction building for the Torvyon blockchain
Documentation
//! ML-DSA-65 post-quantum keys, signatures, and addresses.
//!
//! The byte layout and address domains match the public `@torvyon/sdk` PQ
//! implementation. Legacy Schnorr keys remain available through the original
//! APIs while applications migrate to this module.

use ml_dsa::{
    signature::{Keypair, SignatureEncoding, Verifier},
    EncodedSignature, EncodedVerifyingKey, ExpandedSigningKey, KeyExport, MlDsa65, Seed, SigningKey,
    VerifyingKey,
};
use sha3::{Digest, Sha3_256};

use crate::{Error, Result};

/// Packed ML-DSA-65 sizes used by the Torvyon PQ wire format.
pub const PQ_PUBLIC_KEY_BYTES: usize = 1_952;
/// Expanded ML-DSA-65 private-key size used by the JavaScript SDK.
pub const PQ_PRIVATE_KEY_BYTES: usize = 4_032;
/// ML-DSA-65 signature size.
pub const PQ_SIGNATURE_BYTES: usize = 3_309;
/// Deterministic ML-DSA seed size.
pub const PQ_SEED_BYTES: usize = 32;

const ADDRESS_DOMAIN: &[u8] = b"TORVYON-ADDRESS-MLDSA65-V1\0";
const CHECKSUM_DOMAIN: &[u8] = b"TORVYON-ADDRESS-CHECKSUM-V1\0";

/// Network identity for post-quantum addresses.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PQNetwork {
    /// Mainnet, using `qbt1` addresses.
    Mainnet,
    /// Testnet, using `tqbt1` addresses.
    Testnet,
}

impl PQNetwork {
    /// Chain ID for this PQ network.
    pub const fn chain_id(self) -> &'static str {
        match self {
            Self::Mainnet => MAINNET_CHAIN_ID,
            Self::Testnet => TESTNET_CHAIN_ID,
        }
    }

    /// Address prefix for this PQ network.
    pub const fn address_prefix(self) -> &'static str {
        match self {
            Self::Mainnet => "qbt1",
            Self::Testnet => "tqbt1",
        }
    }
}

/// PQ chain ID for mainnet.
pub const MAINNET_CHAIN_ID: &str = "torvyon-mainnet";
/// PQ chain ID for testnet.
pub const TESTNET_CHAIN_ID: &str = "torvyon-testnet-1";

/// An ML-DSA-65 keypair in the Torvyon packed format.
#[derive(Clone)]
pub struct PQKeypair {
    seed: [u8; PQ_SEED_BYTES],
    public_key: Vec<u8>,
    private_key: Vec<u8>,
}

impl PQKeypair {
    /// Derives a deterministic ML-DSA-65 keypair from a 32-byte seed.
    pub fn from_seed(seed: &[u8; PQ_SEED_BYTES]) -> Self {
        let seed_array: Seed = (*seed).into();
        let signing = SigningKey::<MlDsa65>::from_seed(&seed_array);
        let public_key = signing.verifying_key().to_bytes().to_vec();
        let expanded = ExpandedSigningKey::<MlDsa65>::from_seed(&seed_array);
        #[allow(deprecated)]
        let private_key = expanded.to_expanded().to_vec();
        Self {
            seed: *seed,
            public_key,
            private_key,
        }
    }

    /// Returns the seed used to derive this keypair.
    pub fn seed(&self) -> [u8; PQ_SEED_BYTES] {
        self.seed
    }

    /// Returns the packed ML-DSA-65 public key.
    pub fn public_key(&self) -> &[u8] {
        &self.public_key
    }

    /// Returns the packed expanded ML-DSA-65 private key.
    pub fn private_key(&self) -> &[u8] {
        &self.private_key
    }

    /// Derives a `qbt1`/`tqbt1` address for this keypair.
    pub fn address(&self, network: PQNetwork) -> Result<PQAddress> {
        PQAddress::from_public_key(self.public_key(), network)
    }

    /// Signs a message with deterministic ML-DSA-65 signing and an empty context.
    pub fn sign(&self, message: &[u8]) -> Result<PQSignature> {
        sign_expanded(&self.private_key, message)
    }
}

/// A validated post-quantum address.
#[derive(Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct PQAddress(String);

impl PQAddress {
    /// Derives an address from a packed ML-DSA-65 public key.
    pub fn from_public_key(public_key: &[u8], network: PQNetwork) -> Result<Self> {
        if public_key.len() != PQ_PUBLIC_KEY_BYTES {
            return Err(Error::InvalidPQKey);
        }
        let mut address_hash = Sha3_256::new();
        address_hash.update(ADDRESS_DOMAIN);
        address_hash.update(public_key);
        let digest = address_hash.finalize();
        let base = format!("{}{}", network.address_prefix(), hex::encode(digest));
        let mut checksum_hash = Sha3_256::new();
        checksum_hash.update(CHECKSUM_DOMAIN);
        checksum_hash.update(base.as_bytes());
        let checksum = checksum_hash.finalize();
        Ok(Self(format!("{}{}", base, hex::encode(&checksum[..4]))))
    }

    /// Parses and validates an address for the selected network.
    pub fn parse_for_network(address: &str, network: PQNetwork) -> Result<Self> {
        let prefix = network.address_prefix();
        if address.len() != prefix.len() + 64 + 8 || !address.starts_with(prefix) {
            return Err(Error::InvalidPQKey);
        }
        let base_len = prefix.len() + 64;
        if !address[base_len..].chars().all(|c| c.is_ascii_hexdigit())
            || !address[prefix.len()..base_len]
                .chars()
                .all(|c| c.is_ascii_hexdigit())
        {
            return Err(Error::InvalidPQKey);
        }
        let base = &address[..base_len];
        let mut checksum_hash = Sha3_256::new();
        checksum_hash.update(CHECKSUM_DOMAIN);
        checksum_hash.update(base.as_bytes());
        let expected = hex::encode(&checksum_hash.finalize()[..4]);
        if expected != address[base_len..].to_ascii_lowercase() {
            return Err(Error::InvalidPQKey);
        }
        Ok(Self(address.to_owned()))
    }

    /// Returns the address text.
    pub fn as_str(&self) -> &str {
        &self.0
    }
}

impl std::fmt::Display for PQAddress {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(&self.0)
    }
}

/// An ML-DSA-65 signature in packed wire format.
#[derive(Clone, PartialEq, Eq)]
pub struct PQSignature(Vec<u8>);

impl PQSignature {
    /// Wraps a packed signature.
    pub fn from_bytes(bytes: &[u8]) -> Result<Self> {
        if bytes.len() != PQ_SIGNATURE_BYTES {
            return Err(Error::InvalidPQSignature);
        }
        Ok(Self(bytes.to_vec()))
    }

    /// Returns the packed signature bytes.
    pub fn as_bytes(&self) -> &[u8] {
        &self.0
    }
}

fn sign_expanded(private_key: &[u8], message: &[u8]) -> Result<PQSignature> {
    if private_key.len() != PQ_PRIVATE_KEY_BYTES {
        return Err(Error::InvalidPQKey);
    }
    let encoded = ExpandedSigningKeyBytes::try_from(private_key).map_err(|_| Error::InvalidPQKey)?;
    #[allow(deprecated)]
    let signing = ExpandedSigningKey::<MlDsa65>::from_expanded(&encoded);
    let signature = signing
        .sign_deterministic(message, &[])
        .map_err(|_| Error::InvalidPQSignature)?;
    Ok(PQSignature(signature.to_bytes().to_vec()))
}

/// Signs with a packed expanded ML-DSA-65 private key.
pub fn pq_sign(private_key: &[u8], message: &[u8]) -> Result<PQSignature> {
    sign_expanded(private_key, message)
}

/// Verifies a packed ML-DSA-65 signature.
pub fn pq_verify(public_key: &[u8], message: &[u8], signature: &[u8]) -> bool {
    let Ok(public_key) = EncodedVerifyingKey::<MlDsa65>::try_from(public_key) else {
        return false;
    };
    let Ok(signature) = EncodedSignature::<MlDsa65>::try_from(signature) else {
        return false;
    };
    let key = VerifyingKey::<MlDsa65>::decode(&public_key);
    let signature = ml_dsa::Signature::<MlDsa65>::decode(&signature);
    signature.is_some_and(|signature| key.verify(message, &signature).is_ok())
}

type ExpandedSigningKeyBytes = ml_dsa::ExpandedSigningKeyBytes<MlDsa65>;

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

    #[test]
    fn pq_vector_matches_typescript_sdk() {
        let seed = core::array::from_fn(|i| i as u8);
        let pair = PQKeypair::from_seed(&seed);
        assert_eq!(pair.public_key().len(), PQ_PUBLIC_KEY_BYTES);
        assert_eq!(pair.private_key().len(), PQ_PRIVATE_KEY_BYTES);
        assert_eq!(
            pair.address(PQNetwork::Mainnet).unwrap().to_string(),
            "qbt1e47ca17e6595c839b347fcac4bd4e0b8e8c4d8517db38f1ac571da9accb88fce626b6737"
        );
        assert_eq!(
            pair.address(PQNetwork::Testnet).unwrap().to_string(),
            "tqbt1e47ca17e6595c839b347fcac4bd4e0b8e8c4d8517db38f1ac571da9accb88fce0a74c8ba"
        );
        let message = b"torvyon-pq-test-vector";
        let signature = pair.sign(message).unwrap();
        assert_eq!(signature.as_bytes().len(), PQ_SIGNATURE_BYTES);
        assert!(pq_verify(pair.public_key(), message, signature.as_bytes()));
        assert!(!pq_verify(pair.public_key(), b"tampered", signature.as_bytes()));
    }
}