Add test resource limit enforcement functionality. (#1677)

dmkozh · Copilot · leighmcculloch · web-flow · commit a3cefc1682d1 · 2026-01-23T10:56:06.000Z
### What

Add test resource limit enforcement functionality. Also enable mainnet
limit enforcement by default. These shouldn't be disruptive to most of
the existing users (as they're likely able to run their contracts in
testnet or mainnet), and for those in the experimentation stage this
might be useful for early discovery of the issues.

The limits enforced can be customized or enforcement can be disabled
altogether.

### Why

Resource limit enforcement provides early feedback for the contracts
that might be too heavy to be usable after deployment. The resource
estimation is not perfect, but usually the test environment will have
under-estimated resources (e.g. due to not using the compiled Wasms),
i.e. there shouldn't be annoying 'false positives' for this.

### Known limitations

N/A

---------

Co-authored-by: Copilot &lt;175728472+Copilot@users.noreply.github.com&gt;
Co-authored-by: Leigh &lt;351529+leighmcculloch@users.noreply.github.com&gt;
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -30,17 +30,17 @@ soroban-token-spec = { version = "25.0.0", path = "soroban-token-spec" }
 stellar-asset-spec = { version = "25.0.0", path = "stellar-asset-spec" }
 
 [workspace.dependencies.soroban-env-common]
-version = "=25.0.0"
+version = "=25.0.1"
 # git = "https://github.com/stellar/rs-soroban-env"
 # rev = "cf58d535ab05d02802a5e804a95524650f8c62c7"
 
 [workspace.dependencies.soroban-env-guest]
-version = "=25.0.0"
+version = "=25.0.1"
 # git = "https://github.com/stellar/rs-soroban-env"
 # rev = "cf58d535ab05d02802a5e804a95524650f8c62c7"
 
 [workspace.dependencies.soroban-env-host]
-version = "=25.0.0"
+version = "=25.0.1"
 # git = "https://github.com/stellar/rs-soroban-env"
 # rev = "cf58d535ab05d02802a5e804a95524650f8c62c7"
 
diff --git a/soroban-sdk/src/_migrating.rs b/soroban-sdk/src/_migrating.rs
@@ -15,7 +15,14 @@
 //!    Define traits with default implementations using `#[contracttrait]`, then implement them
 //!    in contracts using `#[contractimpl(contracttrait)]`.
 //!
+//! 5. [Resource limit enforcement enabled by default in tests][v25_resource_limits].
+//!    `Env::default()` now enforces Mainnet resource limits for contract invocations.
+//!    Tests will fail if limits are exceeded. This provides early warning of contracts that
+//!    may be too resource-heavy for Mainnet. If you see test failures after upgrading,
+//!    use `env.cost_estimate().disable_resource_limits()` to opt-out while optimizing.
+//!
 //! [v25_contracttrait]: v25_contracttrait
+//! [v25_resource_limits]: v25_resource_limits
 //!
 //! # Migrating from v22 to v23
 //!
@@ -272,3 +279,4 @@ pub mod v25_bn254;
 pub mod v25_contracttrait;
 pub mod v25_event_testing;
 pub mod v25_poseidon;
+pub mod v25_resource_limits;
diff --git a/soroban-sdk/src/_migrating/v25_resource_limits.rs b/soroban-sdk/src/_migrating/v25_resource_limits.rs
@@ -0,0 +1,145 @@
+//! Resource limit enforcement in tests.
+//!
+//! ## Breaking Change: Tests May Fail Due to Resource Limits
+//!
+//! By default, [`Env::default()`] now enforces mainnet resource limits for contract invocations in
+//! tests. **If your contract exceeds any resource limit, your tests will panic** with details
+//! about which limits were exceeded.
+//!
+//! This provides an early warning that a contract might be too resource-heavy to run on mainnet.
+//!
+//! **If you see test failures after upgrading**, and you wish to test without mainnet limits
+//! (e.g., while experimenting or optimizing), see [Disabling Resource
+//! Limits](#disabling-resource-limits) below.
+//!
+//! ## New Default Behavior
+//!
+//! When creating a new `Env` with [`Env::default()`], mainnet resource limits are automatically
+//! enforced. No changes to existing test code are required to benefit from this protection.
+//!
+//! ```
+//! use soroban_sdk::{contract, contractimpl, Env};
+//!
+//! #[contract]
+//! pub struct Contract;
+//!
+//! #[contractimpl]
+//! impl Contract {
+//!     pub fn execute() {
+//!         // ... code
+//!     }
+//! }
+//!
+//! #[test]
+//! fn test() {
+//! # }
+//! # #[cfg(feature = "testutils")]
+//! # fn main() {
+//!     let env = Env::default(); // Mainnet limits enforced automatically
+//!     let contract_id = env.register(Contract, ());
+//!     let client = ContractClient::new(&env, &contract_id);
+//!     client.execute(); // Will panic if resource limit exceeded
+//! }
+//! # #[cfg(not(feature = "testutils"))]
+//! # fn main() { }
+//! ```
+//!
+//! ## Disabling Resource Limits
+//!
+//! For experimental contracts that are still being optimized, resource limit enforcement can be
+//! disabled using [`CostEstimate::disable_resource_limits()`]:
+//!
+//! ```
+//! use soroban_sdk::{contract, contractimpl, Env};
+//!
+//! #[contract]
+//! pub struct Contract;
+//!
+//! #[contractimpl]
+//! impl Contract {
+//!     pub fn execute() {
+//!         // ... resource-heavy code
+//!     }
+//! }
+//!
+//! #[test]
+//! fn test() {
+//! # }
+//! # #[cfg(feature = "testutils")]
+//! # fn main() {
+//!     let env = Env::default();
+//!     env.cost_estimate().disable_resource_limits(); // Disable resource limit
+//!
+//!     let contract_id = env.register(Contract, ());
+//!     let client = ContractClient::new(&env, &contract_id);
+//!     client.execute(); // Won't panic even if limits exceeded
+//! }
+//! # #[cfg(not(feature = "testutils"))]
+//! # fn main() { }
+//! ```
+//!
+//! ## Custom Resource Limits
+//!
+//! Custom resource limits can be enforced using [`CostEstimate::enforce_resource_limits()`]:
+//!
+//! ```
+//! use soroban_sdk::{contract, contractimpl, Env};
+//! use soroban_sdk::testutils::cost_estimate::NetworkInvocationResourceLimits;
+//! use soroban_env_host::InvocationResourceLimits;
+//!
+//! #[contract]
+//! pub struct Contract;
+//!
+//! #[contractimpl]
+//! impl Contract {
+//!     pub fn execute() {
+//!         // ... code
+//!     }
+//! }
+//!
+//! #[test]
+//! fn test() {
+//! # }
+//! # #[cfg(feature = "testutils")]
+//! # fn main() {
+//!     let env = Env::default();
+//!
+//!     // Use custom limits (this example uses mainnet limits as a base)
+//!     let mut limits = InvocationResourceLimits::mainnet();
+//!     limits.instructions = 100_000_000;  // Reduce instruction limit
+//!     env.cost_estimate().enforce_resource_limits(limits);
+//!
+//!     let contract_id = env.register(Contract, ());
+//!     let client = ContractClient::new(&env, &contract_id);
+//!     client.execute(); // Uses the custom limits
+//! }
+//! # #[cfg(not(feature = "testutils"))]
+//! # fn main() { }
+//! ```
+//!
+//! ## Mainnet Resource Limits
+//!
+//! The [`NetworkInvocationResourceLimits`] trait provides the `mainnet()` method on
+//! [`InvocationResourceLimits`] to get the current mainnet limits:
+//!
+//! - Instructions: 600,000,000
+//! - Memory: 41,943,040 bytes
+//! - Disk read entries: 100
+//! - Write entries: 50
+//! - Ledger entries: 100
+//! - Disk read bytes: 200,000
+//! - Write bytes: 132,096
+//! - Contract events size: 16,384 bytes
+//! - Max contract data key size: 250 bytes
+//! - Max contract data entry size: 65,536 bytes
+//! - Max contract code entry size: 131,072 bytes
+//!
+//! Note: These values are not pulled dynamically. The SDK will be updated from time-to-time to
+//! pick up changes to mainnet limits. These changes may occur in any major, minor, or patch
+//! release.
+//!
+//! [`Env::default()`]: crate::Env::default
+//! [`CostEstimate::disable_resource_limits()`]: crate::testutils::cost_estimate::CostEstimate::disable_resource_limits
+//! [`CostEstimate::enforce_resource_limits()`]: crate::testutils::cost_estimate::CostEstimate::enforce_resource_limits
+//! [`InvocationResourceLimits`]: soroban_env_host::InvocationResourceLimits
+//! [`NetworkInvocationResourceLimits`]: crate::testutils::cost_estimate::NetworkInvocationResourceLimits
diff --git a/soroban-sdk/src/env.rs b/soroban-sdk/src/env.rs
@@ -477,16 +477,17 @@ use crate::testutils::cost_estimate::CostEstimate;
 use crate::{
     auth,
     testutils::{
-        budget::Budget, default_ledger_info, Address as _, AuthSnapshot, AuthorizedInvocation,
-        ContractFunctionSet, EventsSnapshot, Generators, Ledger as _, MockAuth, MockAuthContract,
-        Register, Snapshot, SnapshotSourceInput, StellarAssetContract, StellarAssetIssuer,
+        budget::Budget, cost_estimate::NetworkInvocationResourceLimits, default_ledger_info,
+        Address as _, AuthSnapshot, AuthorizedInvocation, ContractFunctionSet, EventsSnapshot,
+        Generators, Ledger as _, MockAuth, MockAuthContract, Register, Snapshot,
+        SnapshotSourceInput, StellarAssetContract, StellarAssetIssuer,
     },
     Bytes, BytesN, ConstructorArgs,
 };
 #[cfg(any(test, feature = "testutils"))]
 use core::{cell::RefCell, cell::RefMut};
 #[cfg(any(test, feature = "testutils"))]
-use internal::ContractInvocationEvent;
+use internal::{ContractInvocationEvent, InvocationResourceLimits};
 #[cfg(any(test, feature = "testutils"))]
 use soroban_ledger_snapshot::LedgerSnapshot;
 #[cfg(any(test, feature = "testutils"))]
@@ -547,6 +548,7 @@ impl Env {
         // Store in the Env the name of the test it is for, and a number so that within a test
         // where one or more Env's have been created they can be uniquely identified relative to
         // each other.
+
         let test_name = match std::thread::current().name() {
             // When doc tests are running they're all run with the thread name main. There's no way
             // to detect which doc test is being run.
@@ -608,6 +610,9 @@ impl Env {
             })))
             .unwrap();
         env_impl.enable_invocation_metering();
+        env_impl
+            .set_invocation_resource_limits(Some(InvocationResourceLimits::mainnet()))
+            .unwrap();
 
         let env = Env {
             env_impl,
diff --git a/soroban-sdk/src/tests/cost_estimate.rs b/soroban-sdk/src/tests/cost_estimate.rs
@@ -161,17 +161,17 @@ fn test_cost_estimate_budget() {
     // Budget breakdown corresponds to the last invocation only.
     expect![[r#"
         ===============================================================================================================================================================================
-        Cpu limit: 100000000; used: 242479
-        Mem limit: 41943040; used: 1126705
+        Cpu limit: 100000000; used: 257503
+        Mem limit: 41943040; used: 1145211
         ===============================================================================================================================================================================
         CostType                           iterations     input          cpu_insns      mem_bytes      const_term_cpu      lin_term_cpu        const_term_mem      lin_term_mem        
         WasmInsnExec                       284            None           1136           0              4                   0                   0                   0                   
         MemAlloc                           23             Some(1051337)  141397         1051705        434                 16                  16                  128                 
-        MemCpy                             97             Some(9494)     5246           0              42                  16                  0                   0                   
-        MemCmp                             60             Some(1806)     2854           0              44                  16                  0                   0                   
+        MemCpy                             104            Some(10589)    5675           0              42                  16                  0                   0                   
+        MemCmp                             67             Some(1996)     3184           0              44                  16                  0                   0                   
         DispatchHostFunction               1              None           310            0              310                 0                   0                   0                   
         VisitObject                        2              None           122            0              61                  0                   0                   0                   
-        ValSer                             0              Some(0)        0              0              230                 29                  242                 384                 
+        ValSer                             61             Some(1248)     14265          18506          230                 29                  242                 384                 
         ValDeser                           0              Some(0)        0              0              59052               4001                0                   384                 
         ComputeSha256Hash                  1              Some(0)        3738           0              3738                7012                0                   0                   
         ComputeEd25519PubKey               0              None           0              0              40253               0                   0                   0                   
@@ -252,7 +252,7 @@ fn test_cost_estimate_budget() {
         Bn254FrInv                         0              None           0              0              33151               0                   0                   0                   
         ===============================================================================================================================================================================
         Internal details (diagnostics info, does not affect fees) 
-        Total # times meter was called: 197
+        Total # times meter was called: 272
         Shadow cpu limit: 100000000; used: 32431
         Shadow mem limit: 41943040; used: 27108
         ===============================================================================================================================================================================
diff --git a/soroban-sdk/src/testutils/cost_estimate.rs b/soroban-sdk/src/testutils/cost_estimate.rs
@@ -1,4 +1,6 @@
-use soroban_env_host::{fees::FeeConfiguration, FeeEstimate, InvocationResources};
+use soroban_env_host::{
+    fees::FeeConfiguration, FeeEstimate, InvocationResourceLimits, InvocationResources,
+};
 
 use crate::{testutils::budget::Budget, Env};
 
@@ -89,4 +91,63 @@ impl CostEstimate {
     pub fn budget(&self) -> Budget {
         Budget::new(self.env.host().budget_cloned())
     }
+
+    /// Enforces custom resource limits for contract invocations in tests.
+    ///
+    /// When limit enforcement is enabled, for every contract invocation the
+    /// resource usage is checked against the provided limits, and if any of the
+    /// limits is exceeded, the contract invocation will result in a panic
+    /// that indicates which limits were exceeded.
+    ///
+    /// Limit enforcement is meant to provide an early warning sign that a
+    /// contract might be too resource heavy to run on a real network. If the
+    /// high resource usage is intentional and expected (e.g. for
+    /// experimentation), disable the enforcement via
+    /// `disable_resource_limits()`.
+    ///
+    /// By default, `InvocationResourceLimits::mainnet()` limits are enforced.
+    pub fn enforce_resource_limits(&self, limits: InvocationResourceLimits) {
+        self.env
+            .host()
+            .set_invocation_resource_limits(Some(limits))
+            .unwrap();
+    }
+
+    /// Disables resource limit enforcement for contract invocations in tests.
+    ///
+    /// This may be useful for the experimental contracts that are still being
+    /// optimized.
+    pub fn disable_resource_limits(&self) {
+        self.env
+            .host()
+            .set_invocation_resource_limits(None)
+            .unwrap();
+    }
+}
+
+/// Predefined network invocation resource limits.
+pub trait NetworkInvocationResourceLimits {
+    fn mainnet() -> Self;
+}
+
+impl NetworkInvocationResourceLimits for InvocationResourceLimits {
+    /// Returns the invocation resource limits used on Stellar Mainnet.
+    ///
+    /// This is not pulling the values dynamically, so updating the SDK is
+    /// necessary to pick up the most recent values.
+    fn mainnet() -> Self {
+        InvocationResourceLimits {
+            instructions: 600_000_000,
+            mem_bytes: 41943040,
+            disk_read_entries: 100,
+            write_entries: 50,
+            ledger_entries: 100,
+            disk_read_bytes: 200000,
+            write_bytes: 132096,
+            contract_events_size_bytes: 16384,
+            max_contract_data_key_size_bytes: 250,
+            max_contract_data_entry_size_bytes: 65536,
+            max_contract_code_entry_size_bytes: 131072,
+        }
+    }
 }
diff --git a/tests/fuzz/fuzz/Cargo.lock b/tests/fuzz/fuzz/Cargo.lock
