#![doc = include_str!("../README.md")]
mod common;
mod errors;
mod memory;
mod nonce;
mod params;
mod traverse;
use blake3::Hasher;
use subtle::{Choice, ConstantTimeEq};
#[cfg(feature = "zeroize")]
use zeroize::{Zeroize, ZeroizeOnDrop};
pub use crate::common::{BLOCK_SIZE, Mode};
pub use crate::errors::TraverseVErr;
use crate::memory::{fill, initial_blocks};
use crate::nonce::Nonce;
pub use crate::params::Params;
use crate::traverse::dependency_chain;
macro_rules! fill_memory {
($mode: expr, $secret:expr, $context:expr, $params:expr) => {{
let q = $params.m_cost() as usize;
let t = $params.t_cost() as usize;
let mut v = vec![0u8; q * BLOCK_SIZE];
#[cfg_attr(not(feature = "zeroize"), allow(unused_mut))]
let (mut b0, mut b1) = initial_blocks(
$mode,
$params.m_cost(),
$params.t_cost(),
$params.e_cost(),
$params.n_cost(),
$context,
$secret,
);
v[0..BLOCK_SIZE].copy_from_slice(&b0);
v[BLOCK_SIZE..2 * BLOCK_SIZE].copy_from_slice(&b1);
#[cfg(feature = "zeroize")]
{
b0.zeroize();
b1.zeroize();
}
fill(&mut v, q, t);
v
}};
}
macro_rules! context_tag {
($context:expr) => {{
let mut hasher = Hasher::new();
hasher.update($context.as_bytes());
#[cfg_attr(not(feature = "zeroize"), allow(unused_mut))]
let mut hash = hasher.finalize();
let tag: [u8; 32] = hash.into();
#[cfg(feature = "zeroize")]
{
hasher.zeroize();
hash.zeroize();
}
tag
}};
}
#[cfg_attr(test, derive(Clone))]
pub struct TraverseV {
mode: Mode,
buffer: Vec<u8>,
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 = fill_memory!(Mode::Trustless, None, &context, params);
#[cfg_attr(not(feature = "zeroize"), allow(unused_mut))]
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 =
fill_memory!(Mode::Permissioned, Some(secret), &context, params);
#[cfg_attr(not(feature = "zeroize"), allow(unused_mut))]
let mut tag = context_tag!(context);
let mut hasher = Hasher::new_derive_key(&context);
hasher.update(secret);
#[cfg_attr(not(feature = "zeroize"), allow(unused_mut))]
let mut hash = hasher.finalize();
#[cfg_attr(not(feature = "zeroize"), allow(unused_mut))]
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(&self, input: &[u8]) -> u128 {
let mut nonce = Nonce::new();
let mut hasher = Hasher::new();
hasher.update(input);
#[cfg_attr(not(feature = "zeroize"), allow(unused_mut))]
let mut hash = hasher.finalize();
#[cfg_attr(not(feature = "zeroize"), allow(unused_mut))]
let mut prefix: [u8; 32] = hash.into();
#[cfg(feature = "zeroize")]
{
hasher.zeroize();
hash.zeroize();
}
let proof = loop {
let v = u128::from(nonce);
#[cfg_attr(not(feature = "zeroize"), allow(unused_mut))]
let mut candidate = self.evaluate(&prefix, v);
let satisfied = self.check_n(&candidate);
#[cfg(feature = "zeroize")]
candidate.zeroize();
if bool::from(satisfied) {
break v;
}
nonce += 1
};
#[cfg(feature = "zeroize")]
prefix.zeroize();
proof
}
pub fn verify(&self, input: &[u8], proof: u128) -> bool {
let mut hasher = Hasher::new();
hasher.update(input);
#[cfg_attr(not(feature = "zeroize"), allow(unused_mut))]
let mut hash = hasher.finalize();
#[cfg_attr(not(feature = "zeroize"), allow(unused_mut))]
let mut prefix: [u8; 32] = hash.into();
#[cfg_attr(not(feature = "zeroize"), allow(unused_mut))]
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(&self, prefix: &[u8; 32], v: u128) -> [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());
hasher.update(&self.tag);
let mut x = [0u8; BLOCK_SIZE];
let mut reader = hasher.finalize_xof();
reader.fill(&mut x);
let q = self.params.m_cost() as usize;
let k = self.params.e_cost() as usize;
x = dependency_chain(x, &self.buffer, q, k);
#[cfg_attr(not(feature = "zeroize"), allow(unused_mut))]
let mut hash = blake3::hash(&x);
let candidate: [u8; 32] = hash.into();
#[cfg(feature = "zeroize")]
{
hasher.zeroize();
reader.zeroize();
x.zeroize();
hash.zeroize();
}
candidate
}
fn check_n(&self, candidate: &[u8; 32]) -> Choice {
let n = self.params.n_cost() as u8;
let bytes = n / 8;
let bits = n % 8;
let mut satisfied = Choice::from(1u8);
for i in 0..bytes {
satisfied &= candidate[i as usize].ct_eq(&0u8);
}
if bits > 0 {
let mask = (0xFF << (8 - bits)) as u8;
satisfied &= (candidate[bytes as usize] & mask).ct_eq(&0u8);
}
satisfied
}
}
#[cfg(feature = "zeroize")]
impl Drop for TraverseV {
fn drop(&mut self) {
self.buffer.zeroize();
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")
}
fn expected_buffer(mode: Mode, secret: Option<&[u8]>) -> Vec<u8> {
let q = 8_usize;
let t = 2_usize;
#[rustfmt::skip]
let (b0, b1) = initial_blocks(
mode,
q as u32,
t as u32,
2,
12,
CONTEXT,
secret
);
let mut v = vec![0u8; q * BLOCK_SIZE];
v[..BLOCK_SIZE].copy_from_slice(&b0);
v[BLOCK_SIZE..2 * BLOCK_SIZE].copy_from_slice(&b1);
fill(&mut v, q, 2);
v
}
#[test]
fn new_trustless_builds_instance() {
let params = params();
let tv = TraverseV::new_trustless(CONTEXT, params);
let tag = blake3::hash(CONTEXT.as_bytes());
let buffer = expected_buffer(Mode::Trustless, None);
assert_eq!(tv.mode() as u8, Mode::Trustless as u8);
assert!(tv.key.is_none());
assert_eq!(tv.tag, *tag.as_bytes());
assert_eq!(tv.params, params);
assert_eq!(tv.buffer, buffer);
}
#[test]
fn new_permissioned_builds_instance() {
let params = params();
let tv = TraverseV::new_permissioned(SECRET, CONTEXT, params);
let tag = blake3::hash(CONTEXT.as_bytes());
let buffer = expected_buffer(Mode::Permissioned, Some(SECRET));
assert_eq!(tv.mode() as u8, Mode::Permissioned as u8);
assert_eq!(tv.key, Some(blake3::derive_key(CONTEXT, SECRET)));
assert_eq!(tv.tag, *tag.as_bytes());
assert_eq!(tv.params, params);
assert_eq!(tv.buffer, buffer);
}
#[test]
fn trustless_proof_verifies() {
let miner = TraverseV::new_trustless(CONTEXT, params());
let verifier = miner.clone();
let proof = miner.mine(INPUT);
assert!(verifier.verify(INPUT, proof));
}
#[test]
fn permissioned_proof_verifies() {
let miner = TraverseV::new_permissioned(SECRET, CONTEXT, params());
let verifier = miner.clone();
let proof = miner.mine(INPUT);
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());
let proof = miner.mine(INPUT);
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));
}
}