Rename CallBuilder::fire() method to invoke() (#1604)

* Rename `fire()` method to `invoke()`

This keeps this more consistent since we're wrapping a few methods with
`invoke` in the name anyways.

* Update `CHANGELOG`

* Use actual PR number

CHANGELOG.md

@@ -8,13 +8,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add E2E testing framework MVP ‒ [#1395](https://github.com/paritytech/ink/pull/1395)
 - Add E2E tests for `Mapping` functions - [#1492](https://github.com/paritytech/ink/pull/1492)
 - Make CallBuilder and CreateBuilder error handling optional - [#1602](https://github.com/paritytech/ink/pull/1602)
+- Rename `CallBuilder::fire()` method to `invoke()` - [#1604](https://github.com/paritytech/ink/pull/1604)
 
 ### Breaking Changes
-With the addition of [#1602](https://github.com/paritytech/ink/pull/1602),
-the `CallBuilder::fire()`, `CallParams::invoke()`, and `CreateBuilder::instantiate()`
-methods now unwrap the `Result` from `pallet-contracts` under the hood.
+With this release there are two breaking changes related to the `CallBuilder` and
+`CreateBuilder`.
 
-If you wish to handle the error use the new `try_` variants of those methods instead.
+1. The `invoke()` methods now unwrap the `Result` from `pallet-contracts` under the hood
+   ([#1602](https://github.com/paritytech/ink/pull/1602))
+1. The `CallBuilder::fire()` method has been renamed to `invoke()`
+   ([#1604](https://github.com/paritytech/ink/pull/1604))
+
+For (1), if you which to handle the the error use the new `try_` variants of those
+methods instead.
 
 ## Version 4.0.0-beta
 

crates/env/src/call/call_builder.rs

@@ -214,7 +214,7 @@ where
 ///             .push_arg(&[0x10u8; 32])
 ///     )
 ///     .returns::<()>()
-///     .fire();
+///     .invoke();
 /// ```
 ///
 /// ## Example 2: With Return Value
@@ -249,7 +249,7 @@ where
 ///             .push_arg(&[0x10u8; 32])
 ///     )
 ///     .returns::<i32>()
-///     .fire();
+///     .invoke();
 /// ```
 ///
 /// ## Example 3: Delegate call
@@ -276,16 +276,16 @@ where
 ///             .push_arg(&[0x10u8; 32])
 ///     )
 ///     .returns::<i32>()
-///     .fire();
+///     .invoke();
 /// ```
 ///
 /// # 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.
+/// If you want to handle these errors use the [`CallBuilder::try_invoke`] methods instead of the
+/// [`CallBuilder::invoke`] ones.
 ///
 /// **Note:** The shown examples panic because there is currently no cross-calling
 ///           support in the off-chain testing environment. However, this code
@@ -309,7 +309,7 @@ where
 ///             .gas_limit(5000)
 ///             .transferred_value(10),
 ///     )
-///     .try_fire()
+///     .try_invoke()
 ///     .expect("Got an error from the Contract's pallet.");
 ///
 /// match call_result {
@@ -681,8 +681,8 @@ where
     ///
     /// This method panics if it encounters an [`ink::env::Error`][`crate::Error`] or an
     /// [`ink::primitives::LangError`][`ink_primitives::LangError`]. If you want to handle those
-    /// use the [`try_fire`][`CallBuilder::try_fire`] method instead.
-    pub fn fire(self) {
+    /// use the [`try_invoke`][`CallBuilder::try_invoke`] method instead.
+    pub fn invoke(self) {
         self.params().invoke()
     }
 
@@ -692,7 +692,7 @@ where
     ///
     /// On failure this returns an outer [`ink::env::Error`][`crate::Error`] or inner
     /// [`ink_primitives::LangError`], both of which can be handled by the caller.
-    pub fn try_fire(self) -> Result<ink_primitives::MessageResult<()>, Error> {
+    pub fn try_invoke(self) -> Result<ink_primitives::MessageResult<()>, Error> {
         self.params().try_invoke()
     }
 }
@@ -712,8 +712,8 @@ where
     /// # Panics
     ///
     /// This method panics if it encounters an [`ink::env::Error`][`crate::Error`]
-    /// If you want to handle those use the [`try_fire`][`CallBuilder::try_fire`] method instead.
-    pub fn fire(self) {
+    /// If you want to handle those use the [`try_invoke`][`CallBuilder::try_invoke`] method instead.
+    pub fn invoke(self) {
         self.params().invoke()
     }
 
@@ -722,7 +722,7 @@ where
     /// # Note
     ///
     /// On failure this an [`ink::env::Error`][`crate::Error`] which can be handled by the caller.
-    pub fn try_fire(self) -> Result<(), Error> {
+    pub fn try_invoke(self) -> Result<(), Error> {
         self.params().try_invoke()
     }
 }
@@ -740,8 +740,8 @@ where
     ///
     /// This method panics if it encounters an [`ink::env::Error`][`crate::Error`] or an
     /// [`ink::primitives::LangError`][`ink_primitives::LangError`]. If you want to handle those
-    /// use the [`try_fire`][`CallBuilder::try_fire`] method instead.
-    pub fn fire(self) -> R {
+    /// use the [`try_invoke`][`CallBuilder::try_invoke`] method instead.
+    pub fn invoke(self) -> R {
         self.params().invoke()
     }
 
@@ -751,7 +751,7 @@ where
     ///
     /// On failure this returns an outer [`ink::env::Error`][`crate::Error`] or inner
     /// [`ink_primitives::LangError`], both of which can be handled by the caller.
-    pub fn try_fire(self) -> Result<ink_primitives::MessageResult<R>, Error> {
+    pub fn try_invoke(self) -> Result<ink_primitives::MessageResult<R>, Error> {
         self.params().try_invoke()
     }
 }
@@ -768,8 +768,8 @@ where
     /// # Panics
     ///
     /// This method panics if it encounters an [`ink::env::Error`][`crate::Error`]
-    /// If you want to handle those use the [`try_fire`][`CallBuilder::try_fire`] method instead.
-    pub fn fire(self) -> R {
+    /// If you want to handle those use the [`try_invoke`][`CallBuilder::try_invoke`] method instead.
+    pub fn invoke(self) -> R {
         self.params().invoke()
     }
 
@@ -778,7 +778,7 @@ where
     /// # Note
     ///
     /// On failure this an [`ink::env::Error`][`crate::Error`] which can be handled by the caller.
-    pub fn try_fire(self) -> Result<R, Error> {
+    pub fn try_invoke(self) -> Result<R, Error> {
         self.params().try_invoke()
     }
 }

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 ),* )
-                    .try_fire()
+                    .try_invoke()
                     .unwrap_or_else(|error| ::core::panic!(
                         "encountered error while calling {}::{}: {:?}",
                         ::core::stringify!(#storage_ident),

crates/ink/codegen/src/generator/trait_def/call_forwarder.rs

@@ -355,7 +355,7 @@ impl CallForwarder<'_> {
                         , #input_bindings
                     )*
                 )
-                    .try_fire()
+                    .try_invoke()
                     .unwrap_or_else(|env_err| ::core::panic!("{}: {:?}", #panic_str, env_err))
                     .unwrap_or_else(|lang_err| ::core::panic!("{}: {:?}", #panic_str, lang_err))
             }

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

@@ -53,7 +53,7 @@ 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 `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
+error[E0599]: the method `try_invoke` 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) {}

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

@@ -34,7 +34,7 @@ note: required by a bound in `return_value`
    |     R: scale::Encode,
    |        ^^^^^^^^^^^^^ required by this bound in `return_value`
 
-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
+error[E0599]: the method `try_invoke` 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;

crates/ink/tests/ui/trait_def/fail/message_input_non_codec.stderr

@@ -41,7 +41,7 @@ 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 `try_fire` exists for struct `CallBuilder<E, Set<Call<E>>, Set<ExecutionInput<ArgumentList<ink::ink_env::call::utils::Argument<NonCodec>, ArgumentList<ArgumentListEnd, ArgumentListEnd>>>>, Set<ReturnType<()>>>`, but its trait bounds were not satisfied
+error[E0599]: the method `try_invoke` exists for struct `CallBuilder<E, Set<Call<E>>, Set<ExecutionInput<ArgumentList<ink::ink_env::call::utils::Argument<NonCodec>, ArgumentList<ArgumentListEnd, ArgumentListEnd>>>>, Set<ReturnType<()>>>`, but its trait bounds were not satisfied
  --> tests/ui/trait_def/fail/message_input_non_codec.rs:5:5
   |
 5 |     #[ink(message)]

crates/ink/tests/ui/trait_def/fail/message_output_non_codec.stderr

@@ -21,7 +21,7 @@ note: required by a bound in `DispatchOutput`
   |     T: scale::Encode + 'static;
   |        ^^^^^^^^^^^^^ required by this bound in `DispatchOutput`
 
-error[E0599]: the method `try_fire` exists for struct `CallBuilder<E, Set<Call<E>>, Set<ExecutionInput<ArgumentList<ArgumentListEnd, ArgumentListEnd>>>, Set<ReturnType<NonCodec>>>`, but its trait bounds were not satisfied
+error[E0599]: the method `try_invoke` exists for struct `CallBuilder<E, Set<Call<E>>, Set<ExecutionInput<ArgumentList<ArgumentListEnd, ArgumentListEnd>>>, Set<ReturnType<NonCodec>>>`, but its trait bounds were not satisfied
  --> tests/ui/trait_def/fail/message_output_non_codec.rs:5:5
   |
 1 | pub struct NonCodec;

examples/lang-err-integration-tests/call-builder/lib.rs

@@ -44,7 +44,7 @@ mod call_builder {
                 .call_type(Call::new().callee(address))
                 .exec_input(ExecutionInput::new(Selector::new(selector)))
                 .returns::<()>()
-                .try_fire()
+                .try_invoke()
                 .expect("Error from the Contracts pallet.");
 
             match result {
@@ -64,14 +64,14 @@ mod call_builder {
         /// This message does not allow the caller to handle any `LangErrors`, for that use the
         /// `call` message instead.
         #[ink(message)]
-        pub fn fire(&mut self, address: AccountId, selector: [u8; 4]) {
+        pub fn invoke(&mut self, address: AccountId, selector: [u8; 4]) {
             use ink::env::call::build_call;
 
             build_call::<DefaultEnvironment>()
                 .call_type(Call::new().callee(address))
                 .exec_input(ExecutionInput::new(Selector::new(selector)))
                 .returns::<()>()
-                .fire()
+                .invoke()
         }
 
         #[ink(message)]
@@ -173,7 +173,7 @@ mod call_builder {
         }
 
         #[ink_e2e::test(additional_contracts = "../integration-flipper/Cargo.toml")]
-        async fn e2e_invalid_message_selector_panics_on_fire(
+        async fn e2e_invalid_message_selector_panics_on_invoke(
             mut client: ink_e2e::Client<C, E>,
         ) -> E2EResult<()> {
             let constructor = CallBuilderTestRef::new();
@@ -196,11 +196,11 @@ mod call_builder {
                 .expect("instantiate `flipper` failed")
                 .account_id;
 
-            // Since `LangError`s can't be handled by the `CallBuilder::fire()` method we expect
+            // Since `LangError`s can't be handled by the `CallBuilder::invoke()` method we expect
             // this to panic.
             let invalid_selector = [0x00, 0x00, 0x00, 0x00];
             let call = build_message::<CallBuilderTestRef>(contract_acc_id)
-                .call(|contract| contract.fire(flipper_acc_id, invalid_selector));
+                .call(|contract| contract.invoke(flipper_acc_id, invalid_selector));
             let call_result = client.call(&ink_e2e::ferdie(), call, 0, None).await;
 
             assert!(call_result.is_err());

examples/multisig/lib.rs

@@ -348,7 +348,7 @@ mod multisig {
         ///         .push_arg(&transaction_candidate)
         ///     )
         ///     .returns::<(u32, ConfirmationStatus)>()
-        ///     .fire();
+        ///     .invoke();
         ///
         /// // Wait until all required owners have confirmed and then execute the transaction
         /// //
@@ -361,7 +361,7 @@ mod multisig {
         ///         .push_arg(&id)
         ///     )
         ///     .returns::<()>()
-        ///     .fire();
+        ///     .invoke();
         /// ```
         #[ink(message)]
         pub fn add_owner(&mut self, new_owner: AccountId) {
@@ -547,7 +547,7 @@ mod multisig {
                     ExecutionInput::new(t.selector.into()).push_arg(CallInput(&t.input)),
                 )
                 .returns::<()>()
-                .try_fire();
+                .try_invoke();
 
             let result = match result {
                 Ok(Ok(_)) => Ok(()),
@@ -585,7 +585,7 @@ mod multisig {
                     ExecutionInput::new(t.selector.into()).push_arg(CallInput(&t.input)),
                 )
                 .returns::<Vec<u8>>()
-                .try_fire();
+                .try_invoke();
 
             let result = match result {
                 Ok(Ok(v)) => Ok(v),

examples/upgradeable-contracts/forward-calls/lib.rs

@@ -81,7 +81,7 @@ pub mod proxy {
                         .set_forward_input(true)
                         .set_tail_call(true),
                 )
-                .try_fire()
+                .try_invoke()
                 .unwrap_or_else(|env_err| {
                     panic!(
                         "cross-contract call to {:?} failed due to {:?}",