Enable mocking contracts (#1331)

# Description
This PR introduces two changes:
- the previous `Tracing` trait has been modified to accept contract
address instead of code hash (seems to be way more convenient)
- a new trait `CallInterceptor` that allows intercepting contract calls;
in particular the default implementation for `()` will just proceed in a
standard way (after compilation optimizations, there will be no
footprint of that); however, implementing type might decide to mock
invocation and return `ExecResult` instead

Note: one might try merging `before_call` and `intercept_call`. However,
IMHO this would be bad, since it would mix two completely different
abstractions - tracing without any effects and actual intervention into
execution process.

This will unblock working on mocking contracts utility in drink and
similar tools (inkdevhub/drink#33)

# Checklist

- [x] My PR includes a detailed description as outlined in the
"Description" section above
- [ ] My PR follows the [labeling
requirements](https://github.com/paritytech/polkadot-sdk/blob/master/docs/CONTRIBUTING.md#process)
of this project (at minimum one label for `T` required)
- [x] I have made corresponding changes to the documentation (if
applicable)
- [x] I have added tests that prove my fix is effective or that my
feature works (if applicable)

substrate/frame/contracts/src/debug.rs

@@ -15,14 +15,14 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-pub use crate::exec::ExportedFunction;
-use crate::{CodeHash, Config, LOG_TARGET};
-use pallet_contracts_primitives::ExecReturnValue;
+pub use crate::exec::{ExecResult, ExportedFunction};
+use crate::{Config, LOG_TARGET};
+pub use pallet_contracts_primitives::ExecReturnValue;
 
 /// Umbrella trait for all interfaces that serves for debugging.
-pub trait Debugger<T: Config>: Tracing<T> {}
+pub trait Debugger<T: Config>: Tracing<T> + CallInterceptor<T> {}
 
-impl<T: Config, V> Debugger<T> for V where V: Tracing<T> {}
+impl<T: Config, V> Debugger<T> for V where V: Tracing<T> + CallInterceptor<T> {}
 
 /// Defines methods to capture contract calls, enabling external observers to
 /// measure, trace, and react to contract interactions.
@@ -37,11 +37,11 @@ pub trait Tracing<T: Config> {
  ///
  /// # Arguments
  ///
- /// * `code_hash` - The code hash of the contract being called.
+ /// * `contract_address` - The address of the contract that is about to be executed.
  /// * `entry_point` - Describes whether the call is the constructor or a regular call.
  /// * `input_data` - The raw input data of the call.
  fn new_call_span(
- code_hash: &CodeHash<T>,
+ contract_address: &T::AccountId,
  entry_point: ExportedFunction,
  input_data: &[u8],
  ) -> Self::CallSpan;
@@ -60,8 +60,12 @@ pub trait CallSpan {
 impl<T: Config> Tracing<T> for () {
  type CallSpan = ();
 
- fn new_call_span(code_hash: &CodeHash<T>, entry_point: ExportedFunction, input_data: &[u8]) {
- log::trace!(target: LOG_TARGET, "call {entry_point:?} hash: {code_hash:?}, input_data: {input_data:?}")
+ fn new_call_span(
+ contract_address: &T::AccountId,
+ entry_point: ExportedFunction,
+ input_data: &[u8],
+ ) {
+ log::trace!(target: LOG_TARGET, "call {entry_point:?} account: {contract_address:?}, input_data: {input_data:?}")
  }
 }
 
@@ -70,3 +74,37 @@ impl CallSpan for () {
  log::trace!(target: LOG_TARGET, "call result {output:?}")
  }
 }
+
+/// Provides an interface for intercepting contract calls.
+pub trait CallInterceptor<T: Config> {
+ /// Allows to intercept contract calls and decide whether they should be executed or not.
+ /// If the call is intercepted, the mocked result of the call is returned.
+ ///
+ /// # Arguments
+ ///
+ /// * `contract_address` - The address of the contract that is about to be executed.
+ /// * `entry_point` - Describes whether the call is the constructor or a regular call.
+ /// * `input_data` - The raw input data of the call.
+ ///
+ /// # Expected behavior
+ ///
+ /// This method should return:
+ /// * `Some(ExecResult)` - if the call should be intercepted and the mocked result of the call
+ /// is returned.
+ /// * `None` - otherwise, i.e. the call should be executed normally.
+ fn intercept_call(
+ contract_address: &T::AccountId,
+ entry_point: &ExportedFunction,
+ input_data: &[u8],
+ ) -> Option<ExecResult>;
+}
+
+impl<T: Config> CallInterceptor<T> for () {
+ fn intercept_call(
+ _contract_address: &T::AccountId,
+ _entry_point: &ExportedFunction,
+ _input_data: &[u8],
+ ) -> Option<ExecResult> {
+ None
+ }
+}

substrate/frame/contracts/src/exec.rs

@@ -16,7 +16,7 @@
 // limitations under the License.
 
 use crate::{
- debug::{CallSpan, Tracing},
+ debug::{CallInterceptor, CallSpan, Tracing},
  gas::GasMeter,
  storage::{self, meter::Diff, WriteOutcome},
  BalanceOf, CodeHash, CodeInfo, CodeInfoOf, Config, ContractInfo, ContractInfoOf,
@@ -908,13 +908,16 @@ where
  // Every non delegate call or instantiate also optionally transfers the balance.
  self.initial_transfer()?;
 
- let call_span =
- T::Debug::new_call_span(executable.code_hash(), entry_point, &input_data);
+ let contract_address = &top_frame!(self).account_id;
 
- // Call into the Wasm blob.
- let output = executable
- .execute(self, &entry_point, input_data)
- .map_err(|e| ExecError { error: e.error, origin: ErrorOrigin::Callee })?;
+ let call_span = T::Debug::new_call_span(contract_address, entry_point, &input_data);
+
+ let output = T::Debug::intercept_call(contract_address, &entry_point, &input_data)
+ .unwrap_or_else(|| {
+ executable
+ .execute(self, &entry_point, input_data)
+ .map_err(|e| ExecError { error: e.error, origin: ErrorOrigin::Callee })
+ })?;
 
  call_span.after_call(&output);
 

substrate/frame/contracts/src/tests/test_debug.rs

@@ -16,27 +16,31 @@
 // limitations under the License.
 
 use super::*;
-use crate::debug::{CallSpan, ExportedFunction, Tracing};
+use crate::{
+ debug::{CallInterceptor, CallSpan, ExecResult, ExportedFunction, Tracing},
+ AccountIdOf,
+};
 use frame_support::traits::Currency;
 use pallet_contracts_primitives::ExecReturnValue;
 use pretty_assertions::assert_eq;
 use std::cell::RefCell;
 
 #[derive(Clone, PartialEq, Eq, Debug)]
 struct DebugFrame {
- code_hash: CodeHash<Test>,
+ contract_account: AccountId32,
  call: ExportedFunction,
  input: Vec<u8>,
  result: Option<Vec<u8>>,
 }
 
 thread_local! {
  static DEBUG_EXECUTION_TRACE: RefCell<Vec<DebugFrame>> = RefCell::new(Vec::new());
+ static INTERCEPTED_ADDRESS: RefCell<Option<AccountId32>> = RefCell::new(None);
 }
 
 pub struct TestDebug;
 pub struct TestCallSpan {
- code_hash: CodeHash<Test>,
+ contract_account: AccountId32,
  call: ExportedFunction,
  input: Vec<u8>,
 }
@@ -45,27 +49,47 @@ impl Tracing<Test> for TestDebug {
  type CallSpan = TestCallSpan;
 
  fn new_call_span(
- code_hash: &CodeHash<Test>,
+ contract_account: &AccountIdOf<Test>,
  entry_point: ExportedFunction,
  input_data: &[u8],
  ) -> TestCallSpan {
  DEBUG_EXECUTION_TRACE.with(|d| {
  d.borrow_mut().push(DebugFrame {
- code_hash: *code_hash,
+ contract_account: contract_account.clone(),
  call: entry_point,
  input: input_data.to_vec(),
  result: None,
  })
  });
- TestCallSpan { code_hash: *code_hash, call: entry_point, input: input_data.to_vec() }
+ TestCallSpan {
+ contract_account: contract_account.clone(),
+ call: entry_point,
+ input: input_data.to_vec(),
+ }
+ }
+}
+
+impl CallInterceptor<Test> for TestDebug {
+ fn intercept_call(
+ contract_address: &<Test as frame_system::Config>::AccountId,
+ _entry_point: &ExportedFunction,
+ _input_data: &[u8],
+ ) -> Option<ExecResult> {
+ INTERCEPTED_ADDRESS.with(|i| {
+ if i.borrow().as_ref() == Some(contract_address) {
+ Some(Ok(ExecReturnValue { flags: ReturnFlags::REVERT, data: vec![] }))
+ } else {
+ None
+ }
+ })
  }
 }
 
 impl CallSpan for TestCallSpan {
  fn after_call(self, output: &ExecReturnValue) {
  DEBUG_EXECUTION_TRACE.with(|d| {
  d.borrow_mut().push(DebugFrame {
- code_hash: self.code_hash,
+ contract_account: self.contract_account,
  call: self.call,
  input: self.input,
  result: Some(output.data.clone()),
@@ -75,9 +99,9 @@ impl CallSpan for TestCallSpan {
 }
 
 #[test]
-fn unsafe_debugging_works() {
- let (wasm_caller, code_hash_caller) = compile_module::<Test>("call").unwrap();
- let (wasm_callee, code_hash_callee) = compile_module::<Test>("store_call").unwrap();
+fn debugging_works() {
+ let (wasm_caller, _) = compile_module::<Test>("call").unwrap();
+ let (wasm_callee, _) = compile_module::<Test>("store_call").unwrap();
 
  fn current_stack() -> Vec<DebugFrame> {
  DEBUG_EXECUTION_TRACE.with(|stack| stack.borrow().clone())
@@ -100,18 +124,18 @@ fn unsafe_debugging_works() {
  .account_id
  }
 
- fn constructor_frame(hash: CodeHash<Test>, after: bool) -> DebugFrame {
+ fn constructor_frame(contract_account: &AccountId32, after: bool) -> DebugFrame {
  DebugFrame {
- code_hash: hash,
+ contract_account: contract_account.clone(),
  call: ExportedFunction::Constructor,
  input: vec![],
  result: if after { Some(vec![]) } else { None },
  }
  }
 
- fn call_frame(hash: CodeHash<Test>, args: Vec<u8>, after: bool) -> DebugFrame {
+ fn call_frame(contract_account: &AccountId32, args: Vec<u8>, after: bool) -> DebugFrame {
  DebugFrame {
- code_hash: hash,
+ contract_account: contract_account.clone(),
  call: ExportedFunction::Call,
  input: args,
  result: if after { Some(vec![]) } else { None },
@@ -129,19 +153,19 @@ fn unsafe_debugging_works() {
  assert_eq!(
  current_stack(),
  vec![
- constructor_frame(code_hash_caller, false),
- constructor_frame(code_hash_caller, true),
- constructor_frame(code_hash_callee, false),
- constructor_frame(code_hash_callee, true),
+ constructor_frame(&addr_caller, false),
+ constructor_frame(&addr_caller, true),
+ constructor_frame(&addr_callee, false),
+ constructor_frame(&addr_callee, true),
  ]
  );
 
- let main_args = (100u32, &addr_callee).encode();
+ let main_args = (100u32, &addr_callee.clone()).encode();
  let inner_args = (100u32).encode();
 
  assert_ok!(Contracts::call(
  RuntimeOrigin::signed(ALICE),
- addr_caller,
+ addr_caller.clone(),
  0,
  GAS_LIMIT,
  None,
@@ -152,11 +176,54 @@ fn unsafe_debugging_works() {
  assert_eq!(
  stack_top,
  vec![
- call_frame(code_hash_caller, main_args.clone(), false),
- call_frame(code_hash_callee, inner_args.clone(), false),
- call_frame(code_hash_callee, inner_args, true),
- call_frame(code_hash_caller, main_args, true),
+ call_frame(&addr_caller, main_args.clone(), false),
+ call_frame(&addr_callee, inner_args.clone(), false),
+ call_frame(&addr_callee, inner_args, true),
+ call_frame(&addr_caller, main_args, true),
  ]
  );
  });
 }
+
+#[test]
+fn call_interception_works() {
+ let (wasm, _) = compile_module::<Test>("dummy").unwrap();
+
+ ExtBuilder::default().existential_deposit(200).build().execute_with(|| {
+ let _ = Balances::deposit_creating(&ALICE, 1_000_000);
+
+ let account_id = Contracts::bare_instantiate(
+ ALICE,
+ 0,
+ GAS_LIMIT,
+ None,
+ Code::Upload(wasm),
+ vec![],
+ // some salt to ensure that the address of this contract is unique among all tests
+ vec![0x41, 0x41, 0x41, 0x41],
+ DebugInfo::Skip,
+ CollectEvents::Skip,
+ )
+ .result
+ .unwrap()
+ .account_id;
+
+ // no interception yet
+ assert_ok!(Contracts::call(
+ RuntimeOrigin::signed(ALICE),
+ account_id.clone(),
+ 0,
+ GAS_LIMIT,
+ None,
+ vec![],
+ ));
+
+ // intercept calls to this contract
+ INTERCEPTED_ADDRESS.with(|i| *i.borrow_mut() = Some(account_id.clone()));
+
+ assert_err_ignore_postinfo!(
+ Contracts::call(RuntimeOrigin::signed(ALICE), account_id, 0, GAS_LIMIT, None, vec![],),
+ <Error<Test>>::ContractReverted,
+ );
+ });
+}