#![cfg_attr(not(feature = "zeroize"), allow(unused_mut))]
#![doc = include_str!("../README.md")]
mod block;
mod errors;
mod memory;
mod mix;
mod params;
use blake3::Hasher;
use subtle::{Choice, ConstantTimeEq};
#[cfg(feature = "zeroize")]
use zeroize::{Zeroize, ZeroizeOnDrop};
pub use crate::block::Block;
pub use crate::errors::TraverseVErr;
pub use crate::memory::Mode;
use crate::memory::build_buffer;
use crate::mix::iter_mix;
pub use crate::params::Params;
#[cfg_attr(test, derive(Clone))]
pub struct TraverseV {
mode: Mode,
buffer: Vec<Block>,
tag: [u8; 32],
key: Option<[u8; 32]>,
params: Params,
}
impl TraverseV {
pub fn new_trustless(context: impl Into<String>, params: Params) -> Self {
let context = context.into();
let v = build_buffer(Mode::Trustless, None, &context, params);
let mut tag = context_tag(&context);
let this = Self {
mode: Mode::Trustless,
buffer: v,
tag,
key: None,
params,
};
#[cfg(feature = "zeroize")]
tag.zeroize();
this
}
pub fn new_permissioned(
secret: &[u8],
context: impl Into<String>,
params: Params,
) -> Self {
let context = context.into();
let v =
build_buffer(Mode::Permissioned, Some(secret), &context, params);
let mut tag = context_tag(&context);
let mut hasher = Hasher::new_derive_key(&context);
hasher.update(secret);
let mut hash = hasher.finalize();
let mut key: [u8; 32] = hash.into();
let this = Self {
mode: Mode::Permissioned,
buffer: v,
tag,
key: Some(key),
params,
};
#[cfg(feature = "zeroize")]
{
tag.zeroize();
hasher.zeroize();
hash.zeroize();
key.zeroize();
}
this
}
pub fn mine<T, N, I>(&self, input: &[u8], mut counter: T, increment: I) -> N
where
T: core::ops::AddAssign<I> + Into<N> + Copy,
N: num_traits::ToBytes + Copy,
I: Copy,
{
let mut hasher = Hasher::new();
hasher.update(input);
let mut hash = hasher.finalize();
let mut prefix: [u8; 32] = hash.into();
#[cfg(feature = "zeroize")]
{
hasher.zeroize();
hash.zeroize();
}
let proof = loop {
let v: N = counter.into();
let mut candidate = self.evaluate(&prefix, v);
let satisfied = self.check_n(&candidate);
#[cfg(feature = "zeroize")]
candidate.zeroize();
if bool::from(satisfied) {
break v;
}
counter += increment
};
#[cfg(feature = "zeroize")]
prefix.zeroize();
proof
}
pub fn verify<N: num_traits::ToBytes + Copy>(
&self,
input: &[u8],
proof: N,
) -> bool {
let mut hasher = Hasher::new();
hasher.update(input);
let mut hash = hasher.finalize();
let mut prefix: [u8; 32] = hash.into();
let mut candidate = self.evaluate(&prefix, proof);
let satisfied = self.check_n(&candidate);
#[cfg(feature = "zeroize")]
{
hasher.zeroize();
hash.zeroize();
prefix.zeroize();
candidate.zeroize();
}
bool::from(satisfied)
}
pub const fn mode(&self) -> Mode {
self.mode
}
fn evaluate<N: num_traits::ToBytes + Copy>(
&self,
prefix: &[u8; 32],
v: N,
) -> [u8; 32] {
let mut hasher = if let Some(key) = &self.key {
Hasher::new_keyed(key)
} else {
Hasher::new()
};
hasher.update(prefix);
hasher.update(v.to_le_bytes().as_ref());
hasher.update(&self.tag);
let mut bytes = [0u8; Block::SIZE];
let mut reader = hasher.finalize_xof();
reader.fill(&mut bytes);
let mut x = Block::new();
x.copy_from_bytes(&bytes);
let k = self.params.e_cost() as usize;
iter_mix(&mut x, &self.buffer, k);
let mut x_bytes = [0u8; Block::SIZE];
x.copy_to_bytes(&mut x_bytes);
let mut hash = blake3::hash(&x_bytes);
let candidate: [u8; 32] = hash.into();
#[cfg(feature = "zeroize")]
{
hasher.zeroize();
reader.zeroize();
bytes.zeroize();
x.zeroize();
x_bytes.zeroize();
hash.zeroize();
}
candidate
}
fn check_n(&self, candidate: &[u8; 32]) -> Choice {
let n = self.params.n_cost() as u8;
let bytes = (n / 8) as usize;
let bits = n % 8;
let mut satisfied = Choice::from(1u8);
for byte in &candidate[..bytes] {
satisfied &= byte.ct_eq(&0u8);
}
if bits > 0 {
let mask = (0xFF << (8 - bits)) as u8;
satisfied &= (candidate[bytes] & mask).ct_eq(&0u8);
}
satisfied
}
}
fn context_tag(context: &str) -> [u8; 32] {
let mut hasher = Hasher::new();
hasher.update(context.as_bytes());
let mut hash = hasher.finalize();
let tag: [u8; 32] = hash.into();
#[cfg(feature = "zeroize")]
{
hasher.zeroize();
hash.zeroize();
}
tag
}
impl Default for TraverseV {
fn default() -> Self {
let context = "";
let params = Params::default();
TraverseV::new_trustless(context, params)
}
}
impl core::fmt::Debug for TraverseV {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("TraverseV")
.field("mode", &self.mode)
.field("params", &self.params)
.finish_non_exhaustive()
}
}
#[cfg(feature = "zeroize")]
impl Drop for TraverseV {
fn drop(&mut self) {
self.tag.zeroize();
self.key.zeroize();
}
}
#[cfg(feature = "zeroize")]
impl ZeroizeOnDrop for TraverseV {}
#[cfg(test)]
mod tests {
use super::*;
const CONTEXT: &str = "TRAVERSEV_TEST";
const SECRET: &[u8] = b"This is a secret.";
const INPUT: &[u8] = b"Some mining input.";
fn params() -> Params {
Params::new(8, 2, 2, 12).expect("test parameters are valid")
}
#[test]
fn trustless_proof_verifies() {
let miner = TraverseV::new_trustless(CONTEXT, params());
let verifier = miner.clone();
let proof: u128 = miner.mine(INPUT, 0u128, 1);
assert!(verifier.verify(INPUT, proof));
}
#[test]
fn permissioned_proof_verifies() {
let miner = TraverseV::new_permissioned(SECRET, CONTEXT, params());
let verifier = miner.clone();
let proof: u128 = miner.mine(INPUT, 0u128, 1);
assert!(verifier.verify(INPUT, proof));
}
#[test]
fn trustless_rejects_permissioned_proof() {
let miner = TraverseV::new_permissioned(SECRET, CONTEXT, params());
let verifier = TraverseV::new_trustless(CONTEXT, params());
assert_eq!(miner.mode(), Mode::Permissioned);
assert_eq!(verifier.mode(), Mode::Trustless);
let proof: u128 = miner.mine(INPUT, 0u128, 1);
assert!(!verifier.verify(INPUT, proof));
}
#[test]
fn verify_rejects_unsatisfied_difficulty() {
let params = Params::new(2 * 1024, 2, 2, 255)
.expect("test parameters are valid");
let verifier = TraverseV::new_trustless(CONTEXT, params);
assert!(!verifier.verify(INPUT, 0u128));
}
#[test]
fn debug_omits_secret_state() {
let params = params();
let tv = TraverseV::new_permissioned(SECRET, CONTEXT, params);
let output = format!("{tv:?}");
assert!(output.contains("TraverseV"));
assert!(output.contains(&format!("{:?}", tv.mode())));
assert!(output.contains(&format!("{params:?}")));
for field in ["buffer", "tag", "key"] {
assert!(!output.contains(field));
}
}
}