@@ -109,7 +109,31 @@ where
109109 /// Invokes the contract with the given built-up call parameters.
110110///
111111/// Returns the result of the contract execution.
112- pub fn invoke ( & self ) -> Result < R , crate :: Error > {
112+ ///
113+ /// # Panics
114+ ///
115+ /// This method panics if it encounters an [`ink::env::Error`][`crate::Error`] or an
116+ /// [`ink::primitives::LangError`][`ink_primitives::LangError`]. If you want to handle those
117+ /// use the [`try_invoke`][`CallParams::try_invoke`] method instead.
118+ pub fn invoke ( & self ) -> R {
119+ crate :: invoke_contract ( self )
120+ . unwrap_or_else ( |env_error| {
121+ panic ! ( "Cross-contract call failed with {:?}" , env_error)
122+ } )
123+ . unwrap_or_else ( |lang_error| {
124+ panic ! ( "Cross-contract call failed with {:?}" , lang_error)
125+ } )
126+ }
127+
128+ /// Invokes the contract with the given built-up call parameters.
129+ ///
130+ /// Returns the result of the contract execution.
131+ ///
132+ /// # Note
133+ ///
134+ /// On failure this returns an outer [`ink::env::Error`][`crate::Error`] or inner
135+ /// [`ink_primitives::LangError`], both of which can be handled by the caller.
136+ pub fn try_invoke ( & self ) -> Result < ink_primitives:: MessageResult < R > , crate :: Error > {
113137 crate :: invoke_contract ( self )
114138 }
115139}
@@ -120,11 +144,29 @@ where
120144 Args : scale:: Encode ,
121145 R : scale:: Decode ,
122146{
123- /// Invokes the contract via delegated call with the given
124- /// built-up call parameters.
147+ /// Invoke the contract using Delegate Call semantics with the given built-up call parameters.
125148///
126149/// Returns the result of the contract execution.
127- pub fn invoke ( & self ) -> Result < R , crate :: Error > {
150+ ///
151+ /// # Panics
152+ ///
153+ /// This method panics if it encounters an [`ink::env::Error`][`crate::Error`]. If you want to
154+ /// handle those use the [`try_invoke`][`CallParams::try_invoke`] method instead.
155+ pub fn invoke ( & self ) -> R {
156+ crate :: invoke_contract_delegate ( self ) . unwrap_or_else ( |env_error| {
157+ panic ! ( "Cross-contract call failed with {:?}" , env_error)
158+ } )
159+ }
160+
161+ /// Invoke the contract using Delegate Call semantics with the given built-up call parameters.
162+ ///
163+ /// Returns the result of the contract execution.
164+ ///
165+ /// # Note
166+ ///
167+ /// On failure this returns an [`ink::env::Error`][`crate::Error`] which can be handled by the
168+ /// caller.
169+ pub fn try_invoke ( & self ) -> Result < R , crate :: Error > {
128170 crate :: invoke_contract_delegate ( self )
129171 }
130172}
@@ -172,8 +214,7 @@ where
172214/// .push_arg(&[0x10u8; 32])
173215/// )
174216/// .returns::<()>()
175- /// .fire()
176- /// .unwrap();
217+ /// .invoke();
177218/// ```
178219///
179220/// ## Example 2: With Return Value
@@ -208,8 +249,7 @@ where
208249/// .push_arg(&[0x10u8; 32])
209250/// )
210251/// .returns::<i32>()
211- /// .fire()
212- /// .unwrap();
252+ /// .invoke();
213253/// ```
214254///
215255/// ## Example 3: Delegate call
@@ -236,8 +276,47 @@ where
236276/// .push_arg(&[0x10u8; 32])
237277/// )
238278/// .returns::<i32>()
239- /// .fire()
240- /// .unwrap();
279+ /// .invoke();
280+ /// ```
281+ ///
282+ /// # Handling `LangError`s
283+ ///
284+ /// It is also important to note that there are certain types of errors which can happen during
285+ /// cross-contract calls which can be handled know as [`LangError`][`ink_primitives::LangError`].
286+ ///
287+ /// If you want to handle these errors use the [`CallBuilder::try_invoke`] methods instead of the
288+ /// [`CallBuilder::invoke`] ones.
289+ ///
290+ /// **Note:** The shown examples panic because there is currently no cross-calling
291+ /// support in the off-chain testing environment. However, this code
292+ /// should work fine in on-chain environments.
293+ ///
294+ /// ## Example: Handling a `LangError`
295+ ///
296+ /// ```should_panic
297+ /// # use ::ink_env::{
298+ /// # Environment,
299+ /// # DefaultEnvironment,
300+ /// # call::{build_call, Selector, ExecutionInput}
301+ /// # };
302+ /// # use ink_env::call::Call;
303+ /// # type AccountId = <DefaultEnvironment as Environment>::AccountId;
304+ /// # type Balance = <DefaultEnvironment as Environment>::Balance;
305+ /// let call_result = build_call::<DefaultEnvironment>()
306+ /// .call_type(
307+ /// Call::new()
308+ /// .callee(AccountId::from([0x42; 32]))
309+ /// .gas_limit(5000)
310+ /// .transferred_value(10),
311+ /// )
312+ /// .try_invoke()
313+ /// .expect("Got an error from the Contract's pallet.");
314+ ///
315+ /// match call_result {
316+ /// Ok(_) => unimplemented!(),
317+ /// Err(e @ ink_primitives::LangError::CouldNotReadInput) => unimplemented!(),
318+ /// Err(_) => unimplemented!(),
319+ /// }
241320/// ```
242321#[ allow( clippy:: type_complexity) ]
243322pub fn build_call < E > ( ) -> CallBuilder <
@@ -597,9 +676,25 @@ where
597676 E : Environment ,
598677{
599678 /// Invokes the cross-chain function call.
600- pub fn fire ( self ) -> Result < ( ) , Error > {
679+ ///
680+ /// # Panics
681+ ///
682+ /// This method panics if it encounters an [`ink::env::Error`][`crate::Error`] or an
683+ /// [`ink::primitives::LangError`][`ink_primitives::LangError`]. If you want to handle those
684+ /// use the [`try_invoke`][`CallBuilder::try_invoke`] method instead.
685+ pub fn invoke ( self ) {
601686 self . params ( ) . invoke ( )
602687 }
688+
689+ /// Invokes the cross-chain function call.
690+ ///
691+ /// # Note
692+ ///
693+ /// On failure this returns an outer [`ink::env::Error`][`crate::Error`] or inner
694+ /// [`ink_primitives::LangError`], both of which can be handled by the caller.
695+ pub fn try_invoke ( self ) -> Result < ink_primitives:: MessageResult < ( ) > , Error > {
696+ self . params ( ) . try_invoke ( )
697+ }
603698}
604699
605700impl < E >
@@ -612,10 +707,24 @@ impl<E>
612707where
613708 E : Environment ,
614709{
615- /// Invokes the cross-chain function call.
616- pub fn fire ( self ) -> Result < ( ) , Error > {
710+ /// Invokes the cross-chain function call using Delegate Call semantics.
711+ ///
712+ /// # Panics
713+ ///
714+ /// This method panics if it encounters an [`ink::env::Error`][`crate::Error`]
715+ /// If you want to handle those use the [`try_invoke`][`CallBuilder::try_invoke`] method instead.
716+ pub fn invoke ( self ) {
617717 self . params ( ) . invoke ( )
618718 }
719+
720+ /// Invokes the cross-chain function call using Delegate Call semantics.
721+ ///
722+ /// # Note
723+ ///
724+ /// On failure this an [`ink::env::Error`][`crate::Error`] which can be handled by the caller.
725+ pub fn try_invoke ( self ) -> Result < ( ) , Error > {
726+ self . params ( ) . try_invoke ( )
727+ }
619728}
620729
621730impl < E , Args , R >
@@ -626,9 +735,25 @@ where
626735 R : scale:: Decode ,
627736{
628737 /// Invokes the cross-chain function call and returns the result.
629- pub fn fire ( self ) -> Result < R , Error > {
738+ ///
739+ /// # Panics
740+ ///
741+ /// This method panics if it encounters an [`ink::env::Error`][`crate::Error`] or an
742+ /// [`ink::primitives::LangError`][`ink_primitives::LangError`]. If you want to handle those
743+ /// use the [`try_invoke`][`CallBuilder::try_invoke`] method instead.
744+ pub fn invoke ( self ) -> R {
630745 self . params ( ) . invoke ( )
631746 }
747+
748+ /// Invokes the cross-chain function call and returns the result.
749+ ///
750+ /// # Note
751+ ///
752+ /// On failure this returns an outer [`ink::env::Error`][`crate::Error`] or inner
753+ /// [`ink_primitives::LangError`], both of which can be handled by the caller.
754+ pub fn try_invoke ( self ) -> Result < ink_primitives:: MessageResult < R > , Error > {
755+ self . params ( ) . try_invoke ( )
756+ }
632757}
633758
634759impl < E , Args , R >
@@ -638,8 +763,22 @@ where
638763 Args : scale:: Encode ,
639764 R : scale:: Decode ,
640765{
641- /// Invokes the cross-chain function call and returns the result.
642- pub fn fire ( self ) -> Result < R , Error > {
766+ /// Invokes the cross-chain function call using Delegate Call semantics and returns the result.
767+ ///
768+ /// # Panics
769+ ///
770+ /// This method panics if it encounters an [`ink::env::Error`][`crate::Error`]
771+ /// If you want to handle those use the [`try_invoke`][`CallBuilder::try_invoke`] method instead.
772+ pub fn invoke ( self ) -> R {
643773 self . params ( ) . invoke ( )
644774 }
775+
776+ /// Invokes the cross-chain function call using Delegate Call semantics and returns the result.
777+ ///
778+ /// # Note
779+ ///
780+ /// On failure this an [`ink::env::Error`][`crate::Error`] which can be handled by the caller.
781+ pub fn try_invoke ( self ) -> Result < R , Error > {
782+ self . params ( ) . try_invoke ( )
783+ }
645784}
0 commit comments