feat: add UPPER_BOUND & LOWER_BOUND to all our new types

Author: tdelabro

crates/starknet-types-core/src/contract_address.rs

@@ -9,9 +9,7 @@ use core::str::FromStr;
 
 use crate::{
     felt::Felt,
-    patricia_key::{
-        PatriciaKey, PatriciaKeyFromFeltError, PatriciaKeyFromStrError, PATRICIA_KEY_UPPER_BOUND,
-    },
+    patricia_key::{PatriciaKey, PatriciaKeyFromFeltError, PatriciaKeyFromStrError},
 };
 
 #[repr(transparent)]
@@ -29,6 +27,11 @@ impl ContractAddress {
     pub const ONE: Self = Self::from_hex_unchecked("0x1");
     pub const TWO: Self = Self::from_hex_unchecked("0x2");
     pub const THREE: Self = Self::from_hex_unchecked("0x3");
+
+    /// Lower inclusive bound
+    pub const LOWER_BOUND: Self = Self::ZERO;
+    /// Upper non-inclusive bound
+    pub const UPPER_BOUND: Self = Self(PatriciaKey::UPPER_BOUND);
 }
 
 impl core::fmt::Display for ContractAddress {
@@ -78,7 +81,7 @@ impl TryFrom<Felt> for ContractAddress {
 impl Felt {
     /// Validates that a Felt value represents a valid Starknet contract address.
     pub fn is_valid_contract_address(&self) -> bool {
-        self < &PATRICIA_KEY_UPPER_BOUND
+        self < &Felt::from(ContractAddress::UPPER_BOUND)
     }
 }
 
@@ -91,6 +94,11 @@ impl FromStr for ContractAddress {
 }
 
 impl ContractAddress {
+    /// Create a new [ContractAddress] from an hex encoded string without checking it is a valid value.
+    ///
+    /// Should NEVER be used on user inputs,
+    /// as it can cause erroneous execution if dynamically initialized with bad values.
+    /// Should mostly be used at compilation time on hardcoded static string.
     pub const fn from_hex_unchecked(s: &'static str) -> ContractAddress {
         let patricia_key = PatriciaKey::from_hex_unchecked(s);
 
@@ -110,8 +118,6 @@ mod test {
 
     #[test]
     fn basic_values() {
-        assert!(ContractAddress::try_from(Felt::ZERO).is_err());
-        assert!(ContractAddress::try_from(Felt::ONE).is_err());
         assert!(ContractAddress::try_from(PATRICIA_KEY_UPPER_BOUND).is_err());
 
         let felt = Felt::TWO;

crates/starknet-types-core/src/patricia_key.rs

@@ -25,6 +25,13 @@ pub const PATRICIA_KEY_UPPER_BOUND: Felt =
 )]
 pub struct PatriciaKey(Felt);
 
+impl PatriciaKey {
+    /// Lower inclusive bound
+    pub const LOWER_BOUND: Self = Self(Felt::ZERO);
+    /// Upper non-inclusive bound
+    pub const UPPER_BOUND: Self = Self(PATRICIA_KEY_UPPER_BOUND);
+}
+
 impl core::fmt::Display for PatriciaKey {
     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
         write!(f, "{}", self.0)
@@ -110,6 +117,11 @@ impl FromStr for PatriciaKey {
 }
 
 impl PatriciaKey {
+    /// Create a new [PatriciaKey] from an hex encoded string without checking it is a valid value.
+    ///
+    /// Should NEVER be used on user inputs,
+    /// as it can cause erroneous execution if dynamically initialized with bad values.
+    /// Should mostly be used at compilation time on hardcoded static string.
     pub const fn from_hex_unchecked(s: &'static str) -> PatriciaKey {
         let felt = Felt::from_hex_unwrap(s);
 

crates/starknet-types-core/src/regular_contract_address.rs

@@ -16,9 +16,7 @@ use core::str::FromStr;
 use crate::{
     contract_address::ContractAddress,
     felt::Felt,
-    patricia_key::{
-        PatriciaKey, PatriciaKeyFromFeltError, PatriciaKeyFromStrError, PATRICIA_KEY_UPPER_BOUND,
-    },
+    patricia_key::{PatriciaKey, PatriciaKeyFromFeltError, PatriciaKeyFromStrError},
 };
 
 #[repr(transparent)]
@@ -31,6 +29,13 @@ use crate::{
 )]
 pub struct RegularContractAddress(ContractAddress);
 
+impl RegularContractAddress {
+    /// Lower inclusive bound
+    pub const LOWER_BOUND: Self = Self::from_hex_unchecked("0x4");
+    /// Upper non-inclusive bound
+    pub const UPPER_BOUND: Self = Self(ContractAddress::UPPER_BOUND);
+}
+
 impl core::fmt::Display for RegularContractAddress {
     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
         write!(f, "{}", self.0)
@@ -167,7 +172,8 @@ impl Felt {
     /// https://docs.starknet.io/learn/protocol/state#special-addresses
     /// https://github.com/starkware-libs/sequencer/blob/ecd4779abef7bf345938a69f18ef70b6239d3a50/crates/blockifier/resources/blockifier_versioned_constants_0_15_0.json#L92-L97
     pub fn is_regular_contract_address(&self) -> bool {
-        self > &Felt::THREE && self < &PATRICIA_KEY_UPPER_BOUND
+        self >= &Felt::from(RegularContractAddress::LOWER_BOUND)
+            && self < &Felt::from(RegularContractAddress::UPPER_BOUND)
     }
 }
 
@@ -218,9 +224,50 @@ impl FromStr for RegularContractAddress {
 }
 
 impl RegularContractAddress {
+    /// Create a new [RegularContractAddress] from an hex encoded string without checking it is a valid value.
+    ///
+    /// Should NEVER be used on user inputs,
+    /// as it can cause erroneous execution if dynamically initialized with bad values.
+    /// Should mostly be used at compilation time on hardcoded static string.
     pub const fn from_hex_unchecked(s: &'static str) -> RegularContractAddress {
         let contract_address = ContractAddress::from_hex_unchecked(s);
 
         RegularContractAddress(contract_address)
     }
 }
+
+#[cfg(test)]
+mod test {
+    #[cfg(feature = "alloc")]
+    pub extern crate alloc;
+    use proptest::prelude::*;
+
+    use crate::{
+        felt::Felt, patricia_key::PATRICIA_KEY_UPPER_BOUND,
+        regular_contract_address::RegularContractAddress,
+    };
+
+    #[test]
+    fn basic_values() {
+        assert!(RegularContractAddress::try_from(Felt::ZERO).is_err());
+        assert!(RegularContractAddress::try_from(Felt::ONE).is_err());
+        assert!(RegularContractAddress::try_from(Felt::TWO).is_err());
+        assert!(RegularContractAddress::try_from(Felt::THREE).is_err());
+        assert!(RegularContractAddress::try_from(PATRICIA_KEY_UPPER_BOUND).is_err());
+
+        let felt = Felt::from_hex_unwrap("0xcaffe");
+        let contract_address = RegularContractAddress::try_from(felt).unwrap();
+        assert_eq!(Felt::from(contract_address), felt);
+    }
+
+    proptest! {
+        #[test]
+        fn is_valid_match_try_into(ref x in any::<Felt>()) {
+            if x.is_regular_contract_address() {
+                prop_assert!(RegularContractAddress::try_from(*x).is_ok());
+            } else {
+                prop_assert!(RegularContractAddress::try_from(*x).is_err());
+            }
+        }
+    }
+}