feat: modify ContracAddress upper bound to be PATRICIA_KEY_UPPER_BOUND -256

tdelabro · tdelabro · commit a25e4f9a9ade · 2025-11-03T17:00:08.000-03:00
diff --git a/crates/starknet-types-core/src/contract_address.rs b/crates/starknet-types-core/src/contract_address.rs
@@ -9,7 +9,10 @@ use core::str::FromStr;
 
 use crate::{
     felt::Felt,
-    patricia_key::{PatriciaKey, PatriciaKeyFromFeltError, PatriciaKeyFromStrError},
+    patricia_key::{
+        PatriciaKey, PatriciaKeyFromFeltError, PatriciaKeyFromStrError,
+        STORAGE_LEAF_ADDRESS_UPPER_BOUND,
+    },
 };
 
 #[repr(transparent)]
@@ -31,7 +34,9 @@ impl ContractAddress {
     /// Lower inclusive bound
     pub const LOWER_BOUND: Self = Self::ZERO;
     /// Upper non-inclusive bound
-    pub const UPPER_BOUND: Self = Self(PatriciaKey::UPPER_BOUND);
+    ///
+    /// For consistency with other merkle leaf bounds, [ContractAddress] is also bounded by [STORAGE_LEAF_ADDRESS_UPPER_BOUND]
+    pub const UPPER_BOUND: Self = Self(STORAGE_LEAF_ADDRESS_UPPER_BOUND);
 }
 
 impl core::fmt::Display for ContractAddress {
@@ -64,17 +69,67 @@ impl From<ContractAddress> for PatriciaKey {
     }
 }
 
-impl From<PatriciaKey> for ContractAddress {
-    fn from(value: PatriciaKey) -> Self {
-        ContractAddress(value)
+#[derive(Debug)]
+pub enum ContractAddressFromPatriciaKeyError {
+    OutOfBound,
+}
+
+impl core::fmt::Display for ContractAddressFromPatriciaKeyError {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        match self {
+            ContractAddressFromPatriciaKeyError::OutOfBound => write!(
+                f,
+                "value out of bound, upper non-inclusive bound is {}",
+                ContractAddress::UPPER_BOUND
+            ),
+        }
+    }
+}
+
+#[cfg(feature = "std")]
+impl std::error::Error for ContractAddressFromPatriciaKeyError {}
+
+impl TryFrom<PatriciaKey> for ContractAddress {
+    type Error = ContractAddressFromPatriciaKeyError;
+
+    fn try_from(value: PatriciaKey) -> Result<Self, Self::Error> {
+        if value >= STORAGE_LEAF_ADDRESS_UPPER_BOUND {
+            Err(ContractAddressFromPatriciaKeyError::OutOfBound)
+        } else {
+            Ok(ContractAddress(value))
+        }
+    }
+}
+
+#[derive(Debug)]
+pub enum ContractAddressFromFeltError {
+    PatriciaKey(PatriciaKeyFromFeltError),
+    OutOfBound(ContractAddressFromPatriciaKeyError),
+}
+
+impl core::fmt::Display for ContractAddressFromFeltError {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        match self {
+            ContractAddressFromFeltError::OutOfBound(e) => {
+                write!(f, "invalid value for contract address: {e}")
+            }
+            ContractAddressFromFeltError::PatriciaKey(e) => {
+                write!(f, "invalid patricia key value: {e}")
+            }
+        }
     }
 }
 
+#[cfg(feature = "std")]
+impl std::error::Error for ContractAddressFromFeltError {}
 impl TryFrom<Felt> for ContractAddress {
-    type Error = PatriciaKeyFromFeltError;
+    type Error = ContractAddressFromFeltError;
 
     fn try_from(value: Felt) -> Result<Self, Self::Error> {
-        Ok(ContractAddress(PatriciaKey::try_from(value)?))
+        let pk = PatriciaKey::try_from(value).map_err(ContractAddressFromFeltError::PatriciaKey)?;
+        let ca = ContractAddress::try_from(pk).map_err(ContractAddressFromFeltError::OutOfBound)?;
+
+        Ok(ca)
     }
 }
 
@@ -85,19 +140,43 @@ impl Felt {
     }
 }
 
+#[derive(Debug)]
+pub enum ContractAddressFromStrError {
+    PatriciaKey(PatriciaKeyFromStrError),
+    OutOfBound(ContractAddressFromPatriciaKeyError),
+}
+
+impl core::fmt::Display for ContractAddressFromStrError {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        match self {
+            ContractAddressFromStrError::PatriciaKey(e) => {
+                write!(f, "invalid patricia key: {e}")
+            }
+            ContractAddressFromStrError::OutOfBound(e) => {
+                write!(f, "invalid value for contract address: {e}")
+            }
+        }
+    }
+}
+
+#[cfg(feature = "std")]
+impl std::error::Error for ContractAddressFromStrError {}
+
 impl FromStr for ContractAddress {
-    type Err = PatriciaKeyFromStrError;
+    type Err = ContractAddressFromStrError;
 
     fn from_str(s: &str) -> Result<Self, Self::Err> {
-        Ok(ContractAddress(PatriciaKey::from_str(s)?))
+        let pk = PatriciaKey::from_str(s).map_err(ContractAddressFromStrError::PatriciaKey)?;
+        let ca = ContractAddress::try_from(pk).map_err(ContractAddressFromStrError::OutOfBound)?;
+
+        Ok(ca)
     }
 }
 
 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 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);
diff --git a/crates/starknet-types-core/src/patricia_key.rs b/crates/starknet-types-core/src/patricia_key.rs
@@ -12,8 +12,24 @@ use core::str::FromStr;
 
 use crate::felt::Felt;
 
-pub const PATRICIA_KEY_UPPER_BOUND: Felt =
-    Felt::from_hex_unwrap("0x800000000000000000000000000000000000000000000000000000000000000");
+pub const PATRICIA_KEY_UPPER_BOUND: PatriciaKey = PatriciaKey(Felt::from_hex_unwrap(
+    "0x800000000000000000000000000000000000000000000000000000000000000",
+));
+
+/// The index upper bound for a Starknet tree
+///
+/// Equal to `0x800000000000000000000000000000000000000000000000000000000000000 - 256`.
+///
+/// In Starknet users are allowed to store up to 256 felts in a tree leaf.
+/// Therfore, storage addresses can be used as "pointers" to some specific felt stored in a leaf:
+/// ValueAddress = LeafAddress + IndexInsideTheLeaf
+/// So, all leaf addresses are modulo this value.
+pub const STORAGE_LEAF_ADDRESS_UPPER_BOUND: PatriciaKey = PatriciaKey(Felt::from_raw([
+    576459263475590224,
+    18446744073709255680,
+    160989183,
+    18446743986131443745,
+]));
 
 #[repr(transparent)]
 #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
@@ -29,7 +45,7 @@ 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);
+    pub const UPPER_BOUND: Self = PATRICIA_KEY_UPPER_BOUND;
 }
 
 impl core::fmt::Display for PatriciaKey {
@@ -78,7 +94,7 @@ impl TryFrom<Felt> for PatriciaKey {
     type Error = PatriciaKeyFromFeltError;
 
     fn try_from(value: Felt) -> Result<Self, Self::Error> {
-        if value >= PATRICIA_KEY_UPPER_BOUND {
+        if value >= PATRICIA_KEY_UPPER_BOUND.0 {
             return Err(PatriciaKeyFromFeltError(value));
         }
 
@@ -128,3 +144,19 @@ impl PatriciaKey {
         PatriciaKey(felt)
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use crate::{
+        felt::Felt,
+        patricia_key::{PATRICIA_KEY_UPPER_BOUND, STORAGE_LEAF_ADDRESS_UPPER_BOUND},
+    };
+
+    #[test]
+    fn enforce_max_storage_leaf_address() {
+        assert_eq!(
+            PATRICIA_KEY_UPPER_BOUND.0 - Felt::from(256),
+            STORAGE_LEAF_ADDRESS_UPPER_BOUND.into(),
+        );
+    }
+}
diff --git a/crates/starknet-types-core/src/regular_contract_address.rs b/crates/starknet-types-core/src/regular_contract_address.rs
@@ -14,9 +14,11 @@
 use core::str::FromStr;
 
 use crate::{
-    contract_address::ContractAddress,
+    contract_address::{
+        ContractAddress, ContractAddressFromFeltError, ContractAddressFromStrError,
+    },
     felt::Felt,
-    patricia_key::{PatriciaKey, PatriciaKeyFromFeltError, PatriciaKeyFromStrError},
+    patricia_key::PatriciaKey,
 };
 
 #[repr(transparent)]
@@ -143,20 +145,20 @@ impl TryFrom<ContractAddress> for RegularContractAddress {
     }
 }
 
-#[derive(Debug, Clone, Copy)]
+#[derive(Debug)]
 pub enum RegularContractAddressFromFeltError {
-    TooBig(PatriciaKeyFromFeltError),
+    ContractAddress(ContractAddressFromFeltError),
     SpecialAddress(RegularContractAddressFromContractAddressError),
 }
 
 impl core::fmt::Display for RegularContractAddressFromFeltError {
     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
         match self {
-            RegularContractAddressFromFeltError::TooBig(e) => {
+            RegularContractAddressFromFeltError::ContractAddress(e) => {
                 write!(f, "invalid contract address: {}", e)
             }
             RegularContractAddressFromFeltError::SpecialAddress(e) => {
-                write!(f, "got special contract address: {e}")
+                write!(f, "value is a special contract address: {e}")
             }
         }
     }
@@ -182,7 +184,7 @@ impl TryFrom<Felt> for RegularContractAddress {
 
     fn try_from(value: Felt) -> Result<Self, Self::Error> {
         let contract_address = ContractAddress::try_from(value)
-            .map_err(RegularContractAddressFromFeltError::TooBig)?;
+            .map_err(RegularContractAddressFromFeltError::ContractAddress)?;
 
         RegularContractAddress::try_from(contract_address)
             .map_err(RegularContractAddressFromFeltError::SpecialAddress)
@@ -191,14 +193,14 @@ impl TryFrom<Felt> for RegularContractAddress {
 
 #[derive(Debug)]
 pub enum RegularContractAddressFromStrError {
-    BadContractAddress(PatriciaKeyFromStrError),
+    ContractAddress(ContractAddressFromStrError),
     SpecialContractAddress(RegularContractAddressFromContractAddressError),
 }
 
 impl core::fmt::Display for RegularContractAddressFromStrError {
     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
         match self {
-            RegularContractAddressFromStrError::BadContractAddress(e) => {
+            RegularContractAddressFromStrError::ContractAddress(e) => {
                 write!(f, "invalid felt string: {e}")
             }
             RegularContractAddressFromStrError::SpecialContractAddress(e) => {
@@ -216,7 +218,7 @@ impl FromStr for RegularContractAddress {
 
     fn from_str(s: &str) -> Result<Self, Self::Err> {
         let contract_address = ContractAddress::from_str(s)
-            .map_err(RegularContractAddressFromStrError::BadContractAddress)?;
+            .map_err(RegularContractAddressFromStrError::ContractAddress)?;
 
         RegularContractAddress::try_from(contract_address)
             .map_err(RegularContractAddressFromStrError::SpecialContractAddress)
@@ -253,7 +255,7 @@ mod test {
         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());
+        assert!(RegularContractAddress::try_from(Felt::from(PATRICIA_KEY_UPPER_BOUND)).is_err());
 
         let felt = Felt::from_hex_unwrap("0xcaffe");
         let contract_address = RegularContractAddress::try_from(felt).unwrap();
