Clean up CallBuilder return() type

crates/e2e/src/client.rs

@@ -33,6 +33,7 @@ use super::{
 };
 use contract_metadata::ContractMetadata;
 use ink_env::Environment;
+use ink_primitives::MessageResult;
 
 use sp_runtime::traits::{
     IdentifyAccount,
@@ -124,7 +125,7 @@ pub struct CallResult<C: subxt::Config, E: Environment, V> {
     pub events: ExtrinsicEvents<C>,
     /// Contains the result of decoding the return value of the called
     /// function.
-    pub value: Result<V, scale::Error>,
+    pub value: Result<MessageResult<V>, scale::Error>,
     /// Returns the bytes of the encoded dry-run return value.
     pub data: Vec<u8>,
 }
@@ -139,12 +140,19 @@ where
     /// Panics if the value could not be decoded. The raw bytes can be accessed
     /// via [`return_data`].
     pub fn return_value(self) -> V {
-        self.value.unwrap_or_else(|err| {
-            panic!(
-                "decoding dry run result to ink! message return type failed: {}",
-                err
-            )
-        })
+        self.value
+            .unwrap_or_else(|env_err| {
+                panic!(
+                    "Decoding dry run result to ink! message return type failed: {}",
+                    env_err
+                )
+            })
+            .unwrap_or_else(|lang_err| {
+                panic!(
+                    "Encountered a `LangError` while decoding dry run result to ink! message: {:?}",
+                    lang_err
+                )
+            })
     }
 
     /// Returns true if the specified event was triggered by the call.
@@ -655,7 +663,7 @@ where
         }
 
         let bytes = &dry_run.result.as_ref().unwrap().data;
-        let value: Result<RetType, scale::Error> =
+        let value: Result<MessageResult<RetType>, scale::Error> =
             scale::Decode::decode(&mut bytes.as_ref());
 
         Ok(CallResult {

crates/env/src/api.rs

@@ -268,7 +268,9 @@ where
 /// - If the called contract execution has trapped.
 /// - If the called contract ran out of gas upon execution.
 /// - If the returned value failed to decode properly.
-pub fn invoke_contract<E, Args, R>(params: &CallParams<E, Call<E>, Args, R>) -> Result<R>
+pub fn invoke_contract<E, Args, R>(
+    params: &CallParams<E, Call<E>, Args, R>,
+) -> Result<ink_primitives::MessageResult<R>>
 where
     E: Environment,
     Args: scale::Encode,

crates/env/src/backend.rs

@@ -414,7 +414,7 @@ pub trait TypedEnvBackend: EnvBackend {
     fn invoke_contract<E, Args, R>(
         &mut self,
         call_data: &CallParams<E, Call<E>, Args, R>,
-    ) -> Result<R>
+    ) -> Result<ink_primitives::MessageResult<R>>
     where
         E: Environment,
         Args: scale::Encode,

crates/env/src/call/call_builder.rs

@@ -109,7 +109,28 @@ where
     /// Invokes the contract with the given built-up call parameters.
     ///
     /// Returns the result of the contract execution.
+    ///
+    /// # Panics
+    ///
+    /// This method panics if it encounters an [`ink_primitives::LangError`]. If you want to handle
+    /// those use the [`try_invoke`][`CallParams::try_invoke`] method instead.
     pub fn invoke(&self) -> Result<R, crate::Error> {
+        crate::invoke_contract(self).map(|inner| {
+            inner.expect(
+                "Handling `LangError`s is not supported by `CallParams::invoke`, use \
+                `CallParams::try_invoke` instead.",
+            )
+        })
+    }
+
+    /// Invokes the contract with the given built-up call parameters.
+    ///
+    /// Returns the result of the contract execution.
+    ///
+    /// # Note
+    ///
+    /// On failure this returns an [`ink_primitives::LangError`] which can be handled by the caller.
+    pub fn try_invoke(&self) -> Result<ink_primitives::MessageResult<R>, crate::Error> {
         crate::invoke_contract(self)
     }
 }
@@ -173,7 +194,7 @@ where
 ///     )
 ///     .returns::<()>()
 ///     .fire()
-///     .unwrap();
+///     .expect("Got an error from the Contract's pallet.");
 /// ```
 ///
 /// ## Example 2: With Return Value
@@ -209,7 +230,7 @@ where
 ///     )
 ///     .returns::<i32>()
 ///     .fire()
-///     .unwrap();
+///     .expect("Got an error from the Contract's pallet.");
 /// ```
 ///
 /// ## Example 3: Delegate call
@@ -237,7 +258,47 @@ where
 ///     )
 ///     .returns::<i32>()
 ///     .fire()
-///     .unwrap();
+///     .expect("Got an error from the Contract's pallet.");
+/// ```
+///
+/// # Handling `LangError`s
+///
+/// It is also important to note that there are certain types of errors which can happen during
+/// cross-contract calls which can be handled know as [`LangError`][`ink_primitives::LangError`].
+///
+/// If you want to handle these errors use the [`CallBuilder::try_fire`] methods instead of the
+/// [`CallBuilder::fire`] ones.
+///
+/// **Note:** The shown examples panic because there is currently no cross-calling
+///           support in the off-chain testing environment. However, this code
+///           should work fine in on-chain environments.
+///
+/// ## Example: Handling a `LangError`
+///
+/// ```should_panic
+/// # use ::ink_env::{
+/// #     Environment,
+/// #     DefaultEnvironment,
+/// #     call::{build_call, Selector, ExecutionInput}
+/// # };
+/// # use ink_env::call::Call;
+/// # type AccountId = <DefaultEnvironment as Environment>::AccountId;
+/// # type Balance = <DefaultEnvironment as Environment>::Balance;
+/// let call_result = build_call::<DefaultEnvironment>()
+///     .call_type(
+///         Call::new()
+///             .callee(AccountId::from([0x42; 32]))
+///             .gas_limit(5000)
+///             .transferred_value(10),
+///     )
+///     .try_fire()
+///     .expect("Got an error from the Contract's pallet.");
+///
+/// match call_result {
+///     Ok(_) => unimplemented!(),
+///     Err(e @ ink_primitives::LangError::CouldNotReadInput) => unimplemented!(),
+///     Err(_) => unimplemented!(),
+/// }
 /// ```
 #[allow(clippy::type_complexity)]
 pub fn build_call<E>() -> CallBuilder<
@@ -597,9 +658,23 @@ where
     E: Environment,
 {
     /// Invokes the cross-chain function call.
+    ///
+    /// # Panics
+    ///
+    /// This method panics if it encounters an [`ink_primitives::LangError`]. If you want to handle
+    /// those use the [`try_fire`][`CallBuilder::try_fire`] method instead.
     pub fn fire(self) -> Result<(), Error> {
         self.params().invoke()
     }
+
+    /// Invokes the cross-chain function call.
+    ///
+    /// # Note
+    ///
+    /// On failure this returns an [`ink_primitives::LangError`] which can be handled by the caller.
+    pub fn try_fire(self) -> Result<ink_primitives::MessageResult<()>, Error> {
+        self.params().try_invoke()
+    }
 }
 
 impl<E>
@@ -626,9 +701,23 @@ where
     R: scale::Decode,
 {
     /// Invokes the cross-chain function call and returns the result.
+    ///
+    /// # Panics
+    ///
+    /// This method panics if it encounters an [`ink_primitives::LangError`]. If you want to handle
+    /// those use the [`try_fire`][`CallBuilder::try_fire`] method instead.
     pub fn fire(self) -> Result<R, Error> {
         self.params().invoke()
     }
+
+    /// Invokes the cross-chain function call and returns the result.
+    ///
+    /// # Note
+    ///
+    /// On failure this returns an [`ink_primitives::LangError`] which can be handled by the caller.
+    pub fn try_fire(self) -> Result<ink_primitives::MessageResult<R>, Error> {
+        self.params().try_invoke()
+    }
 }
 
 impl<E, Args, R>

crates/env/src/engine/off_chain/impls.rs

@@ -440,7 +440,7 @@ impl TypedEnvBackend for EnvInstance {
     fn invoke_contract<E, Args, R>(
         &mut self,
         params: &CallParams<E, Call<E>, Args, R>,
-    ) -> Result<R>
+    ) -> Result<ink_primitives::MessageResult<R>>
     where
         E: Environment,
         Args: scale::Encode,

crates/env/src/engine/on_chain/impls.rs

@@ -415,7 +415,7 @@ impl TypedEnvBackend for EnvInstance {
     fn invoke_contract<E, Args, R>(
         &mut self,
         params: &CallParams<E, Call<E>, Args, R>,
-    ) -> Result<R>
+    ) -> Result<ink_primitives::MessageResult<R>>
     where
         E: Environment,
         Args: scale::Encode,

crates/ink/codegen/src/generator/as_dependency/call_builder.rs

@@ -369,7 +369,10 @@ impl CallBuilder<'_> {
         let input_types = generator::input_types(message.inputs());
         let arg_list = generator::generate_argument_list(input_types.iter().cloned());
         let mut_tok = callable.receiver().is_ref_mut().then(|| quote! { mut });
-        let return_type = message.wrapped_output();
+        let return_type = message
+            .output()
+            .map(quote::ToTokens::to_token_stream)
+            .unwrap_or_else(|| quote::quote! { () });
         let output_span = return_type.span();
         let output_type = quote_spanned!(output_span=>
             ::ink::env::call::CallBuilder<

crates/ink/codegen/src/generator/as_dependency/contract_ref.rs

@@ -370,7 +370,7 @@ impl ContractRef<'_> {
             ) -> #wrapped_output_type {
                 <Self as ::ink::codegen::TraitCallBuilder>::#call_operator(self)
                     .#message_ident( #( #input_bindings ),* )
-                    .fire()
+                    .try_fire()
                     .unwrap_or_else(|error| ::core::panic!(
                         "encountered error while calling {}::{}: {:?}",
                         ::core::stringify!(#storage_ident),

crates/ink/src/env_access.rs

@@ -519,7 +519,10 @@ where
     ///     )
     ///     .returns::<i32>()
     ///     .params();
-    ///     self.env().invoke_contract(&call_params).unwrap_or_else(|err| panic!("call invocation must succeed: {:?}", err))
+    ///
+    ///     self.env().invoke_contract(&call_params)
+    ///         .unwrap_or_else(|env_err| panic!("Received an error from the Environment: {:?}", env_err))
+    ///         .unwrap_or_else(|lang_err| panic!("Received a `LangError`: {:?}", lang_err))
     /// }
     /// #
     /// #     }
@@ -532,7 +535,7 @@ where
     pub fn invoke_contract<Args, R>(
         self,
         params: &CallParams<E, Call<E>, Args, R>,
-    ) -> Result<R>
+    ) -> Result<ink_primitives::MessageResult<R>>
     where
         Args: scale::Encode,
         R: scale::Decode,

crates/ink/tests/ui/contract/fail/message-input-non-codec.stderr

@@ -53,11 +53,11 @@ note: required by a bound in `ExecutionInput::<ArgumentList<ArgumentListEnd, Arg
    |         T: scale::Encode,
    |            ^^^^^^^^^^^^^ required by this bound in `ExecutionInput::<ArgumentList<ArgumentListEnd, ArgumentListEnd>>::push_arg`
 
-error[E0599]: the method `fire` exists for struct `ink::ink_env::call::CallBuilder<DefaultEnvironment, Set<Call<DefaultEnvironment>>, Set<ExecutionInput<ArgumentList<ink::ink_env::call::utils::Argument<NonCodecType>, ArgumentList<ArgumentListEnd, ArgumentListEnd>>>>, Set<ReturnType<Result<(), LangError>>>>`, but its trait bounds were not satisfied
+error[E0599]: the method `try_fire` exists for struct `ink::ink_env::call::CallBuilder<DefaultEnvironment, Set<Call<DefaultEnvironment>>, Set<ExecutionInput<ArgumentList<ink::ink_env::call::utils::Argument<NonCodecType>, ArgumentList<ArgumentListEnd, ArgumentListEnd>>>>, Set<ReturnType<()>>>`, but its trait bounds were not satisfied
   --> tests/ui/contract/fail/message-input-non-codec.rs:16:9
    |
 16 |         pub fn message(&self, _input: NonCodecType) {}
-   |         ^^^ method cannot be called on `ink::ink_env::call::CallBuilder<DefaultEnvironment, Set<Call<DefaultEnvironment>>, Set<ExecutionInput<ArgumentList<ink::ink_env::call::utils::Argument<NonCodecType>, ArgumentList<ArgumentListEnd, ArgumentListEnd>>>>, Set<ReturnType<Result<(), LangError>>>>` due to unsatisfied trait bounds
+   |         ^^^ method cannot be called on `ink::ink_env::call::CallBuilder<DefaultEnvironment, Set<Call<DefaultEnvironment>>, Set<ExecutionInput<ArgumentList<ink::ink_env::call::utils::Argument<NonCodecType>, ArgumentList<ArgumentListEnd, ArgumentListEnd>>>>, Set<ReturnType<()>>>` due to unsatisfied trait bounds
    |
   ::: $WORKSPACE/crates/env/src/call/execution_input.rs
    |

crates/ink/tests/ui/contract/fail/message-returns-non-codec.stderr

@@ -34,16 +34,19 @@ note: required by a bound in `return_value`
    |     R: scale::Encode,
    |        ^^^^^^^^^^^^^ required by this bound in `return_value`
 
-error[E0599]: the method `fire` exists for struct `ink::ink_env::call::CallBuilder<DefaultEnvironment, Set<Call<DefaultEnvironment>>, Set<ExecutionInput<ArgumentList<ArgumentListEnd, ArgumentListEnd>>>, Set<ReturnType<Result<NonCodecType, LangError>>>>`, but its trait bounds were not satisfied
+error[E0599]: the method `try_fire` exists for struct `ink::ink_env::call::CallBuilder<DefaultEnvironment, Set<Call<DefaultEnvironment>>, Set<ExecutionInput<ArgumentList<ArgumentListEnd, ArgumentListEnd>>>, Set<ReturnType<NonCodecType>>>`, but its trait bounds were not satisfied
   --> tests/ui/contract/fail/message-returns-non-codec.rs:16:9
    |
+4  |     pub struct NonCodecType;
+   |     ----------------------- doesn't satisfy `NonCodecType: parity_scale_codec::Decode`
+...
 16 |         pub fn message(&self) -> NonCodecType {
-   |         ^^^ method cannot be called on `ink::ink_env::call::CallBuilder<DefaultEnvironment, Set<Call<DefaultEnvironment>>, Set<ExecutionInput<ArgumentList<ArgumentListEnd, ArgumentListEnd>>>, Set<ReturnType<Result<NonCodecType, LangError>>>>` due to unsatisfied trait bounds
-   |
-  ::: $RUST/core/src/result.rs
-   |
-   | pub enum Result<T, E> {
-   | --------------------- doesn't satisfy `_: parity_scale_codec::Decode`
+   |         ^^^ method cannot be called on `ink::ink_env::call::CallBuilder<DefaultEnvironment, Set<Call<DefaultEnvironment>>, Set<ExecutionInput<ArgumentList<ArgumentListEnd, ArgumentListEnd>>>, Set<ReturnType<NonCodecType>>>` due to unsatisfied trait bounds
    |
    = note: the following trait bounds were not satisfied:
-           `Result<NonCodecType, LangError>: parity_scale_codec::Decode`
+           `NonCodecType: parity_scale_codec::Decode`
+note: the following trait must be implemented
+  --> $CARGO/parity-scale-codec-3.2.1/src/codec.rs
+   |
+   | pub trait Decode: Sized {
+   | ^^^^^^^^^^^^^^^^^^^^^^^

examples/delegator/lib.rs

@@ -174,8 +174,7 @@ mod delegator {
                 .call(&ink_e2e::bob(), get, 0, None)
                 .await
                 .expect("calling `get` failed")
-                .return_value()
-                .expect("calling `get` returned a `LangError`");
+                .return_value();
             assert_eq!(value, 1234);
             let change = build_message::<DelegatorRef>(delegator_acc_id.clone())
                 .call(|contract| contract.change(6));
@@ -191,8 +190,7 @@ mod delegator {
                 .call(&ink_e2e::bob(), get, 0, None)
                 .await
                 .expect("calling `get` failed")
-                .return_value()
-                .expect("calling `get` returned a `LangError`");
+                .return_value();
             assert_eq!(value, 1234 + 6);
 
             // when
@@ -216,8 +214,7 @@ mod delegator {
                 .call(&ink_e2e::bob(), get, 0, None)
                 .await
                 .expect("calling `get` failed")
-                .return_value()
-                .expect("calling `get` returned a `LangError`");
+                .return_value();
             assert_eq!(value, 1234 + 6 - 3);
 
             Ok(())

examples/erc1155/lib.rs

@@ -365,7 +365,7 @@ mod erc1155 {
 
                 // If our recipient is a smart contract we need to see if they accept or
                 // reject this transfer. If they reject it we need to revert the call.
-                let params = build_call::<Environment>()
+                let result = build_call::<Environment>()
                     .call_type(Call::new().callee(to).gas_limit(5000))
                     .exec_input(
                         ExecutionInput::new(Selector::new(ON_ERC_1155_RECEIVED_SELECTOR))
@@ -376,9 +376,10 @@ mod erc1155 {
                             .push_arg(data),
                     )
                     .returns::<Vec<u8>>()
-                    .params();
+                    .params()
+                    .invoke();
 
-                match ink::env::invoke_contract(&params) {
+                match result {
                     Ok(v) => {
                         ink::env::debug_println!(
                             "Received return value \"{:?}\" from contract {:?}",

examples/erc20/lib.rs

@@ -577,14 +577,10 @@ mod erc20 {
             // then
             assert_eq!(
                 total_supply,
-                total_supply_res.return_value().unwrap(),
+                total_supply_res.return_value(),
                 "total_supply"
             );
-            assert_eq!(
-                transfer_to_bob,
-                balance_of_res.return_value().unwrap(),
-                "balance_of"
-            );
+            assert_eq!(transfer_to_bob, balance_of_res.return_value(), "balance_of");
 
             Ok(())
         }
@@ -671,7 +667,7 @@ mod erc20 {
 
             assert_eq!(
                 total_supply - approved_value,
-                balance_of_res.return_value().unwrap(),
+                balance_of_res.return_value(),
                 "balance_of"
             );