//! Strongly-typed zatoshi amounts that prevent under/overflows. use std::{ convert::{TryFrom, TryInto}, marker::PhantomData, ops::RangeInclusive, }; use byteorder::{ByteOrder, LittleEndian}; type Result = std::result::Result; /// A runtime validated type for representing amounts of zatoshis #[derive(Debug, Eq, PartialEq, Clone, Copy, Serialize, Deserialize)] #[serde(try_from = "i64")] #[serde(bound = "C: Constraint")] pub struct Amount(i64, PhantomData); impl Amount { /// Convert this amount to a different Amount type if it satisfies the new constraint pub fn constrain(self) -> Result> where C2: Constraint, { self.0.try_into() } /// To little endian byte array pub fn to_bytes(&self) -> [u8; 8] { let mut buf: [u8; 8] = [0; 8]; LittleEndian::write_i64(&mut buf, self.0); buf } } impl std::ops::Add> for Amount where C: Constraint, { type Output = Result>; fn add(self, rhs: Amount) -> Self::Output { let value = self.0 + rhs.0; value.try_into() } } impl std::ops::Add> for Result> where C: Constraint, { type Output = Result>; fn add(self, rhs: Amount) -> Self::Output { self? + rhs } } impl std::ops::Add>> for Amount where C: Constraint, { type Output = Result>; fn add(self, rhs: Result>) -> Self::Output { self + rhs? } } impl std::ops::AddAssign> for Result> where Amount: Copy, C: Constraint, { fn add_assign(&mut self, rhs: Amount) { if let Ok(lhs) = *self { *self = lhs + rhs; } } } impl std::ops::Sub> for Amount where C: Constraint, { type Output = Result>; fn sub(self, rhs: Amount) -> Self::Output { let value = self.0 - rhs.0; value.try_into() } } impl std::ops::Sub> for Result> where C: Constraint, { type Output = Result>; fn sub(self, rhs: Amount) -> Self::Output { self? - rhs } } impl std::ops::Sub>> for Amount where C: Constraint, { type Output = Result>; fn sub(self, rhs: Result>) -> Self::Output { self - rhs? } } impl std::ops::SubAssign> for Result> where Amount: Copy, C: Constraint, { fn sub_assign(&mut self, rhs: Amount) { if let Ok(lhs) = *self { *self = lhs - rhs; } } } impl From> for i64 { fn from(amount: Amount) -> Self { amount.0 } } impl From> for u64 { fn from(amount: Amount) -> Self { amount.0 as _ } } impl From> for jubjub::Fr { fn from(a: Amount) -> jubjub::Fr { // TODO: this isn't constant time -- does that matter? if a.0 < 0 { jubjub::Fr::from(a.0.abs() as u64).neg() } else { jubjub::Fr::from(a.0 as u64) } } } impl TryFrom for Amount where C: Constraint, { type Error = Error; fn try_from(value: i64) -> Result { C::validate(value).map(|v| Self(v, PhantomData)) } } impl TryFrom for Amount where C: Constraint, { type Error = Error; fn try_from(value: i32) -> Result { C::validate(value as _).map(|v| Self(v, PhantomData)) } } impl TryFrom for Amount where C: Constraint, { type Error = Error; fn try_from(value: u64) -> Result { let value = value .try_into() .map_err(|source| Error::Convert { value, source })?; C::validate(value).map(|v| Self(v, PhantomData)) } } #[derive(thiserror::Error, Debug, displaydoc::Display, Clone, PartialEq)] #[allow(missing_docs)] /// Errors that can be returned when validating `Amount`s pub enum Error { /// input {value} is outside of valid range for zatoshi Amount, valid_range={range:?} Contains { range: RangeInclusive, value: i64, }, /// u64 {value} could not be converted to an i64 Amount Convert { value: u64, source: std::num::TryFromIntError, }, } #[derive(Clone, Copy, Debug, Eq, PartialEq)] /// Marker type for `Amount` that restricts the values to `-MAX_MONEY..=MAX_MONEY` pub enum NegativeAllowed {} impl Constraint for NegativeAllowed { fn valid_range() -> RangeInclusive { -MAX_MONEY..=MAX_MONEY } } #[derive(Clone, Copy, Debug, Eq, PartialEq)] /// Marker type for `Amount` that restricts the value to positive numbers `0..=MAX_MONEY` pub enum NonNegative {} impl Constraint for NonNegative { fn valid_range() -> RangeInclusive { 0..=MAX_MONEY } } /// The max amount of money that can be obtained in zatoshis pub const MAX_MONEY: i64 = 21_000_000 * 100_000_000; /// A trait for defining constraints on `Amount` pub trait Constraint { /// Returns the range of values that are valid under this constraint fn valid_range() -> RangeInclusive; /// Check if an input value is within the valid range fn validate(value: i64) -> Result { let range = Self::valid_range(); if !range.contains(&value) { Err(Error::Contains { range, value }) } else { Ok(value) } } } #[cfg(test)] mod test { use super::*; use color_eyre::eyre::Result; use proptest::prelude::*; use std::fmt; impl Arbitrary for Amount where C: Constraint + fmt::Debug, { type Parameters = (); fn arbitrary_with(_args: Self::Parameters) -> Self::Strategy { C::valid_range().prop_map(|v| Self(v, PhantomData)).boxed() } type Strategy = BoxedStrategy; } #[test] fn test_add_bare() -> Result<()> { zebra_test::init(); let one: Amount = 1.try_into()?; let neg_one: Amount = (-1).try_into()?; let zero: Amount = 0.try_into()?; let new_zero = one + neg_one; assert_eq!(zero, new_zero?); Ok(()) } #[test] fn test_add_opt_lhs() -> Result<()> { zebra_test::init(); let one: Amount = 1.try_into()?; let one = Ok(one); let neg_one: Amount = (-1).try_into()?; let zero: Amount = 0.try_into()?; let new_zero = one + neg_one; assert_eq!(zero, new_zero?); Ok(()) } #[test] fn test_add_opt_rhs() -> Result<()> { zebra_test::init(); let one: Amount = 1.try_into()?; let neg_one: Amount = (-1).try_into()?; let neg_one = Ok(neg_one); let zero: Amount = 0.try_into()?; let new_zero = one + neg_one; assert_eq!(zero, new_zero?); Ok(()) } #[test] fn test_add_opt_both() -> Result<()> { zebra_test::init(); let one: Amount = 1.try_into()?; let one = Ok(one); let neg_one: Amount = (-1).try_into()?; let neg_one = Ok(neg_one); let zero: Amount = 0.try_into()?; let new_zero = one.and_then(|one| one + neg_one); assert_eq!(zero, new_zero?); Ok(()) } #[test] fn test_add_assign() -> Result<()> { zebra_test::init(); let one: Amount = 1.try_into()?; let neg_one: Amount = (-1).try_into()?; let mut neg_one = Ok(neg_one); let zero: Amount = 0.try_into()?; neg_one += one; let new_zero = neg_one; assert_eq!(Ok(zero), new_zero); Ok(()) } #[test] fn test_sub_bare() -> Result<()> { zebra_test::init(); let one: Amount = 1.try_into()?; let zero: Amount = 0.try_into()?; let neg_one: Amount = (-1).try_into()?; let new_neg_one = zero - one; assert_eq!(Ok(neg_one), new_neg_one); Ok(()) } #[test] fn test_sub_opt_lhs() -> Result<()> { zebra_test::init(); let one: Amount = 1.try_into()?; let one = Ok(one); let zero: Amount = 0.try_into()?; let neg_one: Amount = (-1).try_into()?; let new_neg_one = zero - one; assert_eq!(Ok(neg_one), new_neg_one); Ok(()) } #[test] fn test_sub_opt_rhs() -> Result<()> { zebra_test::init(); let one: Amount = 1.try_into()?; let zero: Amount = 0.try_into()?; let zero = Ok(zero); let neg_one: Amount = (-1).try_into()?; let new_neg_one = zero - one; assert_eq!(Ok(neg_one), new_neg_one); Ok(()) } #[test] fn test_sub_assign() -> Result<()> { zebra_test::init(); let one: Amount = 1.try_into()?; let zero: Amount = 0.try_into()?; let mut zero = Ok(zero); let neg_one: Amount = (-1).try_into()?; zero -= one; let new_neg_one = zero; assert_eq!(Ok(neg_one), new_neg_one); Ok(()) } #[test] fn add_with_diff_constraints() -> Result<()> { let one = Amount::::try_from(1)?; let zero = Amount::::try_from(0)?; (zero - one.constrain()).expect("should allow negative"); (zero.constrain() - one).expect_err("shouldn't allow negative"); Ok(()) } #[test] fn deserialize_checks_bounds() -> Result<()> { let big = MAX_MONEY * 2; let neg = -10; let big_bytes = bincode::serialize(&big)?; let neg_bytes = bincode::serialize(&neg)?; bincode::deserialize::>(&big_bytes) .expect_err("deserialization should reject too large values"); bincode::deserialize::>(&big_bytes) .expect_err("deserialization should reject too large values"); bincode::deserialize::>(&neg_bytes) .expect_err("NonNegative deserialization should reject negative values"); let amount = bincode::deserialize::>(&neg_bytes) .expect("NegativeAllowed deserialization should allow negative values"); assert_eq!(amount.0, neg); Ok(()) } }