Expose invocation metering in the SDK. (#1411)

### What

Expose invocation metering in the SDK.

### Why

Improving testing UX.

#1319

### Known limitations

N/A

---------

Co-authored-by: Jay Geng <jay@stellar.org>
Co-authored-by: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com>

soroban-sdk/Cargo.toml

@@ -53,6 +53,7 @@ derive_arbitrary = { version = "~1.3.0" }
 proptest = "1.2.0"
 proptest-arbitrary-interop = "0.1.0"
 libfuzzer-sys = "0.4.7"
+expect-test = "1.4.1"
 
 [features]
 alloc = []

soroban-sdk/src/env.rs

@@ -449,6 +449,8 @@ impl Env {
     }
 }
 
+#[cfg(any(test, feature = "testutils"))]
+use crate::testutils::cost_estimate::CostEstimate;
 #[cfg(any(test, feature = "testutils"))]
 use crate::{
     auth,
@@ -560,6 +562,7 @@ impl Env {
                 }
             })))
             .unwrap();
+        env_impl.enable_invocation_metering();
 
         let env = Env {
             env_impl,
@@ -576,6 +579,31 @@ impl Env {
         env
     }
 
+    /// Returns the resources metered during the last top level contract
+    /// invocation.    
+    ///
+    /// In order to get non-`None` results, `enable_invocation_metering` has to
+    /// be called and at least one invocation has to happen after that.
+    ///
+    /// Take the return value with a grain of salt. The returned resources mostly
+    /// correspond only to the operations that have happened during the host
+    /// invocation, i.e. this won't try to simulate the work that happens in
+    /// production scenarios (e.g. certain XDR rountrips). This also doesn't try
+    /// to model resources related to the transaction size.
+    ///
+    /// The returned value is as useful as the preceding setup, e.g. if a test
+    /// contract is used instead of a Wasm contract, all the costs related to
+    /// VM instantiation and execution, as well as Wasm reads/rent bumps will be
+    /// missed.
+    ///
+    /// While the resource metering may be useful for contract optimization,
+    /// keep in mind that resource and fee estimation may be imprecise. Use
+    /// simulation with RPC in order to get the exact resources for submitting
+    /// the transactions to the network.    
+    pub fn cost_estimate(&self) -> CostEstimate {
+        CostEstimate::new(self.clone())
+    }
+
     /// Register a contract with the [Env] for testing.
     ///
     /// Pass the contract type when the contract is defined in the current crate
@@ -1611,6 +1639,7 @@ impl Env {
     }
 
     /// Get the budget that tracks the resources consumed for the environment.
+    #[deprecated(note = "use cost_estimate().detailed_metering()")]
     pub fn budget(&self) -> Budget {
         Budget::new(self.env_impl.budget_cloned())
     }

soroban-sdk/src/tests.rs

@@ -2,7 +2,6 @@
 
 mod address;
 mod auth;
-mod budget;
 mod bytes_alloc_vec;
 mod bytes_buffer;
 mod contract_add_i32;
@@ -25,6 +24,7 @@ mod contract_udt_struct;
 mod contract_udt_struct_tuple;
 mod contractimport;
 mod contractimport_with_error;
+mod cost_estimate;
 mod crypto_bls12_381;
 mod crypto_ed25519;
 mod crypto_keccak256;