Name API consistently: transferred_balance ➔ transferred_value

RELEASES.md

@@ -1,3 +1,10 @@
+# Version 3.0-rc8 (UNRELEASED)
+
+This is the 8th release candidate for ink! 3.0.
+
+## Change
+- Renamed the `ink_env` function `transferred_balance()` to `transferred_value()` ‒ [#1063](/~https://github.com/paritytech/ink/pull/1063).
+
 # Version 3.0-rc7
 
 This is the 7th release candidate for ink! 3.0.

crates/env/src/api.rs

@@ -53,17 +53,17 @@ where
     })
 }
 
-/// Returns the transferred balance for the contract execution.
+/// Returns the transferred value for the contract execution.
 ///
 /// # Errors
 ///
 /// If the returned value cannot be properly decoded.
-pub fn transferred_balance<T>() -> T::Balance
+pub fn transferred_value<T>() -> T::Balance
 where
     T: Environment,
 {
     <EnvInstance as OnInstance>::on_instance(|instance| {
-        TypedEnvBackend::transferred_balance::<T>(instance)
+        TypedEnvBackend::transferred_value::<T>(instance)
     })
 }
 

crates/env/src/backend.rs

@@ -290,12 +290,12 @@ pub trait TypedEnvBackend: EnvBackend {
     /// For more details visit: [`caller`][`crate::caller`]
     fn caller<T: Environment>(&mut self) -> T::AccountId;
 
-    /// Returns the transferred balance for the contract execution.
+    /// Returns the transferred value for the contract execution.
     ///
     /// # Note
     ///
-    /// For more details visit: [`transferred_balance`][`crate::transferred_balance`]
-    fn transferred_balance<T: Environment>(&mut self) -> T::Balance;
+    /// For more details visit: [`transferred_value`][`crate::transferred_value`]
+    fn transferred_value<T: Environment>(&mut self) -> T::Balance;
 
     /// Returns the price for the specified amount of gas.
     ///

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

@@ -324,7 +324,7 @@ impl TypedEnvBackend for EnvInstance {
             })
     }
 
-    fn transferred_balance<T: Environment>(&mut self) -> T::Balance {
+    fn transferred_value<T: Environment>(&mut self) -> T::Balance {
         self.get_property::<T::Balance>(Engine::value_transferred)
             .unwrap_or_else(|error| {
                 panic!("could not read `transferred_value` property: {:?}", error)

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

@@ -332,12 +332,12 @@ impl TypedEnvBackend for EnvInstance {
             })
     }
 
-    fn transferred_balance<T: Environment>(&mut self) -> T::Balance {
+    fn transferred_value<T: Environment>(&mut self) -> T::Balance {
         self.exec_context()
             .expect(UNINITIALIZED_EXEC_CONTEXT)
             .transferred_value::<T>()
             .unwrap_or_else(|error| {
-                panic!("could not read `transferred_balance` property: {:?}", error)
+                panic!("could not read `transferred_value` property: {:?}", error)
             })
     }
 

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

@@ -357,7 +357,7 @@ impl TypedEnvBackend for EnvInstance {
         self.get_property_inplace::<T::AccountId>(ext::caller)
     }
 
-    fn transferred_balance<T: Environment>(&mut self) -> T::Balance {
+    fn transferred_value<T: Environment>(&mut self) -> T::Balance {
         self.get_property_little_endian::<T::Balance>(ext::value_transferred)
     }
 

crates/lang/codegen/src/generator/trait_def/call_builder.rs

@@ -307,7 +307,7 @@ impl CallBuilder<'_> {
     /// the respective ink! trait message calls of the called smart contract
     /// instance.
     /// The way these messages are built-up allows the caller to customize message
-    /// parameters such as gas limit and transferred balance.
+    /// parameters such as gas limit and transferred value.
     fn generate_ink_trait_impl(&self) -> TokenStream2 {
         let span = self.trait_def.span();
         let trait_ident = self.trait_def.trait_def.item().ident();

crates/lang/macro/src/lib.rs

@@ -481,7 +481,7 @@ pub fn selector_bytes(input: TokenStream) -> TokenStream {
 ///         #[ink(message, payable)]
 ///         pub fn fund(&self) {
 ///             let caller = self.env().caller();
-///             let value = self.env().transferred_balance();
+///             let value = self.env().transferred_value();
 ///             debug_println!("thanks for the funding of {:?} from {:?}", value, caller);
 ///         }
 ///     }

crates/lang/src/codegen/dispatch/execution.rs

@@ -63,7 +63,7 @@ pub fn deny_payment<E>() -> Result<(), DispatchError>
 where
     E: Environment,
 {
-    let transferred = ink_env::transferred_balance::<E>();
+    let transferred = ink_env::transferred_value::<E>();
     if transferred != <E as Environment>::Balance::from(0_u32) {
         return Err(DispatchError::PaidUnpayableMessage)
     }

crates/lang/src/env_access.rs

@@ -107,7 +107,7 @@ where
         ink_env::caller::<T>()
     }
 
-    /// Returns the transferred balance for the contract execution.
+    /// Returns the transferred value for the contract execution.
     ///
     /// # Example
     ///
@@ -125,11 +125,11 @@ where
     /// #             Self {}
     /// #         }
     /// #
-    /// /// Allows funding the contract. Prints a debug message with the transferred balance.
+    /// /// Allows funding the contract. Prints a debug message with the transferred value.
     /// #[ink(message, payable)]
     /// pub fn fund(&self) {
     ///     let caller = self.env().caller();
-    ///     let value = self.env().transferred_balance();
+    ///     let value = self.env().transferred_value();
     ///     ink_env::debug_println!("thanks for the funding of {:?} from {:?}", value, caller);
     /// }
     /// #
@@ -139,9 +139,9 @@ where
     ///
     /// # Note
     ///
-    /// For more details visit: [`ink_env::transferred_balance`]
-    pub fn transferred_balance(self) -> T::Balance {
-        ink_env::transferred_balance::<T>()
+    /// For more details visit: [`ink_env::transferred_value`]
+    pub fn transferred_value(self) -> T::Balance {
+        ink_env::transferred_value::<T>()
     }
 
     /// Returns the price for the specified amount of gas.

crates/lang/tests/ui/contract/pass/env-access.rs

@@ -16,7 +16,7 @@ mod contract {
             let _ = Self::env().gas_left();
             let _ = Self::env().minimum_balance();
             let _ = Self::env().random(&[]);
-            let _ = Self::env().transferred_balance();
+            let _ = Self::env().transferred_value();
             let _ = Self::env().weight_to_fee(0);
             Self {}
         }
@@ -31,7 +31,7 @@ mod contract {
             let _ = self.env().gas_left();
             let _ = self.env().minimum_balance();
             let _ = self.env().random(&[]);
-            let _ = self.env().transferred_balance();
+            let _ = self.env().transferred_value();
             let _ = self.env().weight_to_fee(0);
         }
     }

examples/contract-transfer/lib.rs

@@ -73,12 +73,9 @@ pub mod give_me {
         pub fn was_it_ten(&self) {
             ink_env::debug_println!(
                 "received payment: {}",
-                self.env().transferred_balance()
-            );
-            assert!(
-                self.env().transferred_balance() == 10,
-                "payment was not ten"
+                self.env().transferred_value()
             );
+            assert!(self.env().transferred_value() == 10, "payment was not ten");
         }
     }
 
@@ -137,16 +134,16 @@ pub mod give_me {
                 0xCA, 0xFE, 0xBA, 0xBE,
             ]));
             data.push_arg(&accounts.eve);
-            let mock_transferred_balance = 10;
+            let mock_transferred_value = 10;
 
             // Push the new execution context which sets Eve as caller and
-            // the `mock_transferred_balance` as the value which the contract
+            // the `mock_transferred_value` as the value which the contract
             // will see as transferred to it.
             ink_env::test::push_execution_context::<ink_env::DefaultEnvironment>(
                 accounts.eve,
                 contract_id(),
                 1000000,
-                mock_transferred_balance,
+                mock_transferred_value,
                 data,
             );
 
@@ -168,16 +165,16 @@ pub mod give_me {
                 0xCA, 0xFE, 0xBA, 0xBE,
             ]));
             data.push_arg(&accounts.eve);
-            let mock_transferred_balance = 13;
+            let mock_transferred_value = 13;
 
             // Push the new execution context which sets Eve as caller and
-            // the `mock_transferred_balance` as the value which the contract
+            // the `mock_transferred_value` as the value which the contract
             // will see as transferred to it.
             ink_env::test::push_execution_context::<ink_env::DefaultEnvironment>(
                 accounts.eve,
                 contract_id(),
                 1000000,
-                mock_transferred_balance,
+                mock_transferred_value,
                 data,
             );
 
@@ -277,7 +274,7 @@ pub mod give_me {
 
             // when
             // Push the new execution context which sets Eve as caller and
-            // the `mock_transferred_balance` as the value which the contract
+            // the `mock_transferred_value` as the value which the contract
             // will see as transferred to it.
             set_sender(accounts.eve);
             ink_env::test::set_value_transferred::<ink_env::DefaultEnvironment>(10);
@@ -296,7 +293,7 @@ pub mod give_me {
 
             // when
             // Push the new execution context which sets Eve as caller and
-            // the `mock_transferred_balance` as the value which the contract
+            // the `mock_transferred_value` as the value which the contract
             // will see as transferred to it.
             set_sender(accounts.eve);
             ink_env::test::set_value_transferred::<ink_env::DefaultEnvironment>(13);

examples/multisig/lib.rs

@@ -483,7 +483,7 @@ mod multisig {
         ) -> Result<(), Error> {
             self.ensure_confirmed(trans_id);
             let t = self.take_transaction(trans_id).expect(WRONG_TRANSACTION_ID);
-            assert!(self.env().transferred_balance() == t.transferred_value);
+            assert!(self.env().transferred_value() == t.transferred_value);
             let result = build_call::<<Self as ::ink_lang::reflect::ContractEnv>::Env>()
                 .callee(t.callee)
                 .gas_limit(t.gas_limit)

examples/proxy/lib.rs

@@ -76,7 +76,7 @@ pub mod proxy {
                         .set_forward_input(true)
                         .set_tail_call(true),
                 )
-                .transferred_value(self.env().transferred_balance())
+                .transferred_value(self.env().transferred_value())
                 .fire()
                 .unwrap_or_else(|err| {
                     panic!(