VM Storage Cache

Cargo.toml

@@ -21,9 +21,6 @@ keccak-const = "0.2.0"
 lazy_static = "1.4.0"
 sha3 = "0.10.8"
 
-# data structures
-fnv = "1.0.7"
-
 # proc macros
 syn = { version = "1.0", features = ["full"] }
 paste = "1.0.14"

stylus-proc/Cargo.toml

@@ -25,11 +25,10 @@ quote.workspace = true
 
 [features]
 export-abi = []
-storage-cache = []
 reentrant = []
 
 [package.metadata.docs.rs]
-features = ["export-abi", "storage-cache"]
+features = ["export-abi"]
 
 [lib]
 proc-macro = true

stylus-proc/src/lib.rs

@@ -148,8 +148,8 @@ pub fn sol_storage(input: TokenStream) -> TokenStream {
 /// # Reentrant calls
 ///
 /// Contracts that opt into reentrancy via the `reentrant` feature flag require extra care.
-/// When the `storage-cache` feature is enabled, cross-contract calls must [`flush`] or [`clear`]
-/// the [`StorageCache`] to safeguard state. This happens automatically via the type system.
+/// When enabled, cross-contract calls must [`flush`] or [`clear`] the [`StorageCache`] to safeguard state.
+/// This happens automatically via the type system.
 ///
 /// ```ignore
 /// sol_interface! {

stylus-proc/src/methods/entrypoint.rs

@@ -72,15 +72,6 @@ pub fn entrypoint(attr: TokenStream, input: TokenStream) -> TokenStream {
         }
     }
 
-    // flush the cache before program exit
-    cfg_if! {
-        if #[cfg(feature = "storage-cache")] {
-            let flush_cache = quote! { stylus_sdk::storage::StorageCache::flush(); };
-        } else {
-            let flush_cache = quote! {};
-        }
-    }
-
     output.extend(quote! {
         #[no_mangle]
         pub unsafe fn mark_used() {
@@ -97,7 +88,7 @@ pub fn entrypoint(attr: TokenStream, input: TokenStream) -> TokenStream {
                 Ok(data) => (data, 0),
                 Err(data) => (data, 1),
             };
-            #flush_cache
+            unsafe { stylus_sdk::storage::StorageCache::flush() };
             stylus_sdk::contract::output(&data);
             status
         }

stylus-sdk/Cargo.toml

@@ -22,9 +22,6 @@ lazy_static.workspace = true
 # export-abi
 regex = { workspace = true, optional = true }
 
-# storage-cache
-fnv = { workspace = true, optional = true }
-
 # local deps
 stylus-proc.workspace = true
 
@@ -36,10 +33,9 @@ sha3.workspace = true
 features = ["default", "docs", "debug", "export-abi"]
 
 [features]
-default = ["storage-cache"]
+default = []
 export-abi = ["debug", "regex", "stylus-proc/export-abi"]
 debug = []
 docs = []
 hostio = []
-storage-cache = ["fnv", "stylus-proc/storage-cache"]
 reentrant = ["stylus-proc/reentrant"]

stylus-sdk/src/call/context.rs

@@ -1,4 +1,4 @@
-// Copyright 2022-2023, Offchain Labs, Inc.
+// Copyright 2022-2024, Offchain Labs, Inc.
 // For licensing, see https://github.com/OffchainLabs/stylus-sdk-rs/blob/stylus/licenses/COPYRIGHT.md
 
 use crate::storage::TopLevelStorage;
@@ -52,9 +52,6 @@ where
     /// }
     /// ```
     ///
-    /// Projects that opt out of the [`StorageCache`] by disabling the `storage-cache` feature
-    /// may ignore this method.
-    ///
     /// [`StorageCache`]: crate::storage::StorageCache
     /// [`flush`]: crate::storage::StorageCache::flush
     /// [`clear`]: crate::storage::StorageCache::clear
@@ -133,7 +130,7 @@ where
 impl<T> NonPayableCallContext for &mut T where T: TopLevelStorage {}
 
 cfg_if! {
-    if #[cfg(all(feature = "storage-cache", feature = "reentrant"))] {
+    if #[cfg(feature = "reentrant")] {
         // The following impls safeguard state during reentrancy scenarios
 
         impl<S: TopLevelStorage> StaticCallContext for Call<&S, false> {}
@@ -165,7 +162,7 @@ cfg_if! {
 }
 
 cfg_if! {
-    if #[cfg(any(all(feature = "storage-cache", feature = "reentrant"), feature = "docs"))] {
+    if #[cfg(any(feature = "reentrant", feature = "docs"))] {
         impl Default for Call<(), false> {
             fn default() -> Self {
                 Self::new()

stylus-sdk/src/call/mod.rs

@@ -1,4 +1,4 @@
-// Copyright 2022-2023, Offchain Labs, Inc.
+// Copyright 2022-2024, Offchain Labs, Inc.
 // For licensing, see https://github.com/OffchainLabs/stylus-sdk-rs/blob/stylus/licenses/COPYRIGHT.md
 
 //! Call other contracts.
@@ -18,7 +18,7 @@ pub use self::{context::Call, error::Error, raw::RawCall, traits::*, transfer::t
 
 pub(crate) use raw::CachePolicy;
 
-#[cfg(all(feature = "storage-cache", feature = "reentrant"))]
+#[cfg(feature = "reentrant")]
 use crate::storage::Storage;
 
 mod context;
@@ -29,12 +29,12 @@ mod transfer;
 
 macro_rules! unsafe_reentrant {
     ($block:block) => {
-        #[cfg(all(feature = "storage-cache", feature = "reentrant"))]
+        #[cfg(feature = "reentrant")]
         unsafe {
             $block
         }
 
-        #[cfg(not(all(feature = "storage-cache", feature = "reentrant")))]
+        #[cfg(not(feature = "reentrant"))]
         $block
     };
 }
@@ -45,7 +45,7 @@ pub fn static_call(
     to: Address,
     data: &[u8],
 ) -> Result<Vec<u8>, Error> {
-    #[cfg(all(feature = "storage-cache", feature = "reentrant"))]
+    #[cfg(feature = "reentrant")]
     Storage::flush(); // flush storage to persist changes, but don't invalidate the cache
 
     unsafe_reentrant! {{
@@ -68,7 +68,7 @@ pub unsafe fn delegate_call(
     to: Address,
     data: &[u8],
 ) -> Result<Vec<u8>, Error> {
-    #[cfg(all(feature = "storage-cache", feature = "reentrant"))]
+    #[cfg(feature = "reentrant")]
     Storage::clear(); // clear the storage to persist changes, invalidating the cache
 
     RawCall::new_delegate()
@@ -79,7 +79,7 @@ pub unsafe fn delegate_call(
 
 /// Calls the contract at the given address.
 pub fn call(context: impl MutatingCallContext, to: Address, data: &[u8]) -> Result<Vec<u8>, Error> {
-    #[cfg(all(feature = "storage-cache", feature = "reentrant"))]
+    #[cfg(feature = "reentrant")]
     Storage::clear(); // clear the storage to persist changes, invalidating the cache
 
     unsafe_reentrant! {{

stylus-sdk/src/call/raw.rs

@@ -8,13 +8,13 @@ use crate::{
 use alloy_primitives::{Address, B256, U256};
 use cfg_if::cfg_if;
 
-#[cfg(all(feature = "storage-cache", feature = "reentrant"))]
+#[cfg(feature = "reentrant")]
 use crate::storage::StorageCache;
 
 macro_rules! unsafe_reentrant {
     ($(#[$meta:meta])* pub fn $name:ident $($rest:tt)*) => {
         cfg_if! {
-            if #[cfg(all(feature = "storage-cache", feature = "reentrant"))] {
+            if #[cfg(feature = "reentrant")] {
                 $(#[$meta])*
                 pub unsafe fn $name $($rest)*
             } else {
@@ -161,20 +161,14 @@ impl RawCall {
     }
 
     /// Write all cached values to persistent storage before the call.
-    #[cfg(any(
-        all(feature = "storage-cache", feature = "reentrant"),
-        feature = "docs"
-    ))]
+    #[cfg(any(feature = "reentrant", feature = "docs"))]
     pub fn flush_storage_cache(mut self) -> Self {
         self.cache_policy = self.cache_policy.max(CachePolicy::Flush);
         self
     }
 
     /// Flush and clear the storage cache before the call.
-    #[cfg(any(
-        all(feature = "storage-cache", feature = "reentrant"),
-        feature = "docs"
-    ))]
+    #[cfg(any(feature = "reentrant", feature = "docs"))]
     pub fn clear_storage_cache(mut self) -> Self {
         self.cache_policy = CachePolicy::Clear;
         self
@@ -185,7 +179,7 @@ impl RawCall {
         ///
         /// # Safety
         ///
-        /// This function becomes `unsafe` when the `reentrant` and `storage-cache` features are enabled.
+        /// This function becomes `unsafe` when the `reentrant` feature is enabled.
         /// That's because raw calls might alias storage if used in the middle of a storage ref's lifetime.
         ///
         /// For extra flexibility, this method does not clear the global storage cache by default.
@@ -198,7 +192,7 @@ impl RawCall {
             let gas = self.gas.unwrap_or(u64::MAX); // will be clamped by 63/64 rule
             let value = B256::from(self.callvalue);
             let status = unsafe {
-                #[cfg(all(feature = "storage-cache", feature = "reentrant"))]
+                #[cfg(feature = "reentrant")]
                 match self.cache_policy {
                     CachePolicy::Clear => StorageCache::clear(),
                     CachePolicy::Flush => StorageCache::flush(),

stylus-sdk/src/call/transfer.rs

@@ -1,14 +1,14 @@
-// Copyright 2022-2023, Offchain Labs, Inc.
+// Copyright 2022-2024, Offchain Labs, Inc.
 // For licensing, see https://github.com/OffchainLabs/stylus-sdk-rs/blob/stylus/licenses/COPYRIGHT.md
 
 use crate::call::RawCall;
 use alloc::vec::Vec;
 use alloy_primitives::{Address, U256};
 
-#[cfg(all(feature = "storage-cache", feature = "reentrant"))]
+#[cfg(feature = "reentrant")]
 use crate::storage::TopLevelStorage;
 
-#[cfg(all(feature = "storage-cache", feature = "reentrant"))]
+#[cfg(feature = "reentrant")]
 use crate::storage::Storage;
 
 /// Transfers an amount of ETH in wei to the given account.
@@ -18,7 +18,7 @@ use crate::storage::Storage;
 /// If this is not desired, the [`call`](super::call) function may be used directly.
 ///
 /// [`call`]: super::call
-#[cfg(all(feature = "storage-cache", feature = "reentrant"))]
+#[cfg(feature = "reentrant")]
 pub fn transfer_eth(
     _storage: &mut impl TopLevelStorage,
     to: Address,
@@ -43,7 +43,7 @@ pub fn transfer_eth(
 /// transfer_eth(recipient, value)?;                 // these two are equivalent
 /// call(Call::new().value(value), recipient, &[])?; // these two are equivalent
 /// ```
-#[cfg(not(all(feature = "storage-cache", feature = "reentrant")))]
+#[cfg(not(feature = "reentrant"))]
 pub fn transfer_eth(to: Address, amount: U256) -> Result<(), Vec<u8>> {
     RawCall::new_with_value(amount)
         .skip_return_data()

stylus-sdk/src/deploy/raw.rs

@@ -9,7 +9,7 @@ use crate::{
 use alloc::vec::Vec;
 use alloy_primitives::{Address, B256, U256};
 
-#[cfg(all(feature = "storage-cache", feature = "reentrant"))]
+#[cfg(feature = "reentrant")]
 use crate::storage::StorageCache;
 
 /// Mechanism for performing raw deploys of other contracts.
@@ -62,14 +62,14 @@ impl RawDeploy {
     }
 
     /// Write all cached values to persistent storage before the init code.
-    #[cfg(feature = "storage-cache")]
+    #[cfg(feature = "reentrant")]
     pub fn flush_storage_cache(mut self) -> Self {
         self.cache_policy = self.cache_policy.max(CachePolicy::Flush);
         self
     }
 
     /// Flush and clear the storage cache before the init code.
-    #[cfg(feature = "storage-cache")]
+    #[cfg(feature = "reentrant")]
     pub fn clear_storage_cache(mut self) -> Self {
         self.cache_policy = CachePolicy::Clear;
         self
@@ -90,7 +90,7 @@ impl RawDeploy {
     /// [flush]: crate::storage::StorageCache::flush
     /// [clear]: crate::storage::StorageCache::clear
     pub unsafe fn deploy(self, code: &[u8], endowment: U256) -> Result<Address, Vec<u8>> {
-        #[cfg(all(feature = "storage-cache", feature = "reentrant"))]
+        #[cfg(feature = "reentrant")]
         match self.cache_policy {
             CachePolicy::Clear => StorageCache::clear(),
             CachePolicy::Flush => StorageCache::flush(),

stylus-sdk/src/hostio.rs

@@ -55,16 +55,27 @@ extern "C" {
     /// value stored in the EVM state trie at offset `key`, which will be `0` when not previously
     /// set. The semantics, then, are equivalent to that of the EVM's [`SLOAD`] opcode.
     ///
+    /// Note: the Stylus VM implements storage caching. This means that repeated calls to the same key
+    /// will cost less than in the EVM.
+    ///
     /// [`SLOAD`]: https://www.evm.codes/#54
     pub fn storage_load_bytes32(key: *const u8, dest: *mut u8);
 
-    /// Stores a 32-byte value to permanent storage. Stylus's storage format is identical to that
-    /// of the EVM. This means that, under the hood, this hostio is storing a 32-byte value into
-    /// the EVM state trie at offset `key`. Furthermore, refunds are tabulated exactly as in the
-    /// EVM. The semantics, then, are equivalent to that of the EVM's [`SSTORE`] opcode.
+    /// Writes a 32-byte value to the permanent storage cache. Stylus's storage format is identical to that
+    /// of the EVM. This means that, under the hood, this hostio represents storing a 32-byte value into
+    /// the EVM state trie at offset `key`. Refunds are tabulated exactly as in the EVM. The semantics, then,
+    /// are equivalent to that of the EVM's [`SSTORE`] opcode.
+    ///
+    /// Note: because the value is cached, one must call `storage_flush_cache` to persist it.
+    ///
+    /// [`SSTORE`]: https://www.evm.codes/#55
+    pub fn storage_cache_bytes32(key: *const u8, value: *const u8);
+
+    /// Persists any dirty values in the storage cache to the EVM state trie, dropping the cache entirely if requested.
+    /// Analogous to repeated invocations of [`SSTORE`].
     ///
     /// [`SSTORE`]: https://www.evm.codes/#55
-    pub fn storage_store_bytes32(key: *const u8, value: *const u8);
+    pub fn storage_flush_cache(clear: bool);
 
     /// Gets the basefee of the current block. The semantics are equivalent to that of the EVM's
     /// [`BASEFEE`] opcode.