Add example usage comments to EnvAccess methods (#797)

* Add example usage comments to env methods

* Remove superfluous line

* wip

* Remove debug code

* Make doc comment examples compile

* Remove superfluous line

* Surround with complete contract code

* Experiment with macro to reduce code duplication

* Revert "Experiment with macro to reduce code duplication"

This reverts commit f731912.

* Add complete contract code in doc tests

* Remove unnecessary `[dev-dependencies]`

* Improve code in doc tests

* Fix doc tests

* Improve code appearance

* Add better doc test examples

* Make `gas` be of type `u64` instead of `Balance`

* Make `gas` be of type `u64` instead of `Balance`

* Make `gas` be of type `u64` instead of `Balance`

* Apply suggestions from code review

Co-authored-by: Robin Freyler <[email protected]>

* Add simple access permission contract

* Fix syntax

Co-authored-by: Robin Freyler <[email protected]>

Author: Michael Müller

crates/env/src/api.rs

@@ -90,7 +90,7 @@ where
 /// # Errors
 ///
 /// If the returned value cannot be properly decoded.
-pub fn gas_left<T>() -> Result<T::Balance>
+pub fn gas_left<T>() -> Result<u64>
 where
     T: Environment,
 {
@@ -436,7 +436,8 @@ pub fn restore_contract<T>(
     })
 }
 
-/// Terminates the existence of the currently executed smart contract.
+/// Terminates the existence of the currently executed smart contract
+/// without creating a tombstone.
 ///
 /// This removes the calling account and transfers all remaining balance
 /// to the given beneficiary.
@@ -561,6 +562,15 @@ pub fn debug_message(message: &str) {
 }
 
 /// Conducts the crypto hash of the given input and stores the result in `output`.
+///
+/// # Example
+///
+/// ```
+/// use ink_env::hash::{Sha2x256, HashOutput};
+/// let input: &[u8] = &[13, 14, 15];
+/// let mut output = <Sha2x256 as HashOutput>::Type::default(); // 256-bit buffer
+/// let hash  = ink_env::hash_bytes::<Sha2x256>(input, &mut output);
+/// ```
 pub fn hash_bytes<H>(input: &[u8], output: &mut <H as HashOutput>::Type)
 where
     H: CryptoHash,

crates/env/src/backend.rs

@@ -203,7 +203,7 @@ pub trait TypedEnvBackend: EnvBackend {
     /// # Note
     ///
     /// For more details visit: [`gas_left`][`crate::gas_left`]
-    fn gas_left<T: Environment>(&mut self) -> Result<T::Balance>;
+    fn gas_left<T: Environment>(&mut self) -> Result<u64>;
 
     /// Returns the timestamp of the current block.
     ///

crates/env/src/call/call_builder.rs

@@ -302,6 +302,7 @@ mod seal {
     impl Sealed for () {}
     impl<T> Sealed for super::ReturnType<T> {}
 }
+
 /// Types that can be used in [`CallBuilder::returns`] to signal return type.
 pub trait IndicateReturnType: Default + self::seal::Sealed {}
 impl IndicateReturnType for () {}

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

@@ -284,8 +284,8 @@ impl TypedEnvBackend for EnvInstance {
         self.get_property::<T::Balance>(Engine::value_transferred)
     }
 
-    fn gas_left<T: Environment>(&mut self) -> Result<T::Balance> {
-        self.get_property::<T::Balance>(Engine::gas_left)
+    fn gas_left<T: Environment>(&mut self) -> Result<u64> {
+        self.get_property::<u64>(Engine::gas_left)
     }
 
     fn block_timestamp<T: Environment>(&mut self) -> Result<T::Timestamp> {

crates/env/src/engine/off_chain/db/exec_context.rs

@@ -37,7 +37,7 @@ pub struct ExecContext {
     /// The transferred value from caller to callee.
     pub transferred_value: OffBalance,
     /// The gas provided for the whole execution.
-    pub gas: OffBalance,
+    pub gas: u64,
     /// The inputs provided for the whole execution.
     ///
     /// # Note
@@ -82,11 +82,11 @@ impl ExecContext {
     }
 
     /// Returns the gas.
-    pub fn gas<T>(&self) -> Result<T::Balance>
+    pub fn gas<T>(&self) -> u64
     where
         T: Environment,
     {
-        self.gas.decode().map_err(Into::into)
+        self.gas
     }
 
     /// Returns the call data.
@@ -122,7 +122,7 @@ where
     /// The transferred value from caller to callee.
     transferred_value: Option<T::Balance>,
     /// The gas provided for the contract execution from caller to callee.
-    gas: Option<T::Balance>,
+    gas: Option<u64>,
     /// The inputs given to the contract execution.
     call_data: Option<CallData>,
 }
@@ -173,7 +173,7 @@ where
     /// # Panics
     ///
     /// If there has already been set provided gas.
-    pub fn gas(mut self, gas: T::Balance) -> Self {
+    pub fn gas(mut self, gas: u64) -> Self {
         if self.gas.is_some() {
             panic!("already has provided gas");
         }
@@ -223,7 +223,7 @@ where
             caller: TypedEncoded::new(&caller),
             callee: TypedEncoded::new(&callee),
             transferred_value: TypedEncoded::new(&transferred_value),
-            gas: TypedEncoded::new(&gas),
+            gas,
             call_data: self.call_data.unwrap(),
             output: None,
         }

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

@@ -316,12 +316,11 @@ impl TypedEnvBackend for EnvInstance {
             .saturating_mul(gas.try_into().unwrap_or_else(|_| Bounded::max_value())))
     }
 
-    fn gas_left<T: Environment>(&mut self) -> Result<T::Balance> {
-        self.exec_context()
+    fn gas_left<T: Environment>(&mut self) -> Result<u64> {
+        Ok(self
+            .exec_context()
             .expect(UNINITIALIZED_EXEC_CONTEXT)
-            .gas::<T>()
-            .map_err(|_| scale::Error::from("could not decode gas left"))
-            .map_err(Into::into)
+            .gas::<T>())
     }
 
     fn block_timestamp<T: Environment>(&mut self) -> Result<T::Timestamp> {

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

@@ -205,7 +205,7 @@ impl EnvInstance {
             ExecContext::build::<T>()
                 .caller(default_accounts.alice)
                 .callee(contract_account_id)
-                .gas(T::Balance::from(500_000u32))
+                .gas(500_000u64)
                 .transferred_value(T::Balance::from(500u32))
                 .call_data(CallData::new(Selector::new(selector_bytes_for_call)))
                 .finish(),

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

@@ -44,7 +44,7 @@ use std::panic::UnwindSafe;
 pub fn push_execution_context<T>(
     caller: T::AccountId,
     callee: T::AccountId,
-    gas_limit: T::Balance,
+    gas_limit: u64,
     endowment: T::Balance,
     call_data: CallData,
 ) where

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

@@ -309,8 +309,8 @@ impl TypedEnvBackend for EnvInstance {
         self.get_property::<T::Balance>(ext::value_transferred)
     }
 
-    fn gas_left<T: Environment>(&mut self) -> Result<T::Balance> {
-        self.get_property::<T::Balance>(ext::gas_left)
+    fn gas_left<T: Environment>(&mut self) -> Result<u64> {
+        self.get_property::<u64>(ext::gas_left)
     }
 
     fn block_timestamp<T: Environment>(&mut self) -> Result<T::Timestamp> {

crates/lang/Cargo.toml

@@ -26,6 +26,10 @@ scale = { package = "parity-scale-codec", version = "2.1", default-features = fa
 derive_more = { version = "0.99", default-features = false, features = ["from"] }
 static_assertions = "1.1"
 
+[dev-dependencies]
+# required for the doctest of `env_access::EnvAccess::instantiate_contract`
+scale-info = { version = "0.6", default-features = false, features = ["derive"] }
+
 [features]
 default = ["std"]
 std = [

crates/lang/macro/tests/ui/pass/08-static-env.rs

@@ -13,7 +13,7 @@ mod static_env {
         }
 
         #[ink(message)]
-        pub fn gas_left(&mut self) -> Balance {
+        pub fn gas_left(&mut self) -> u64 {
             Self::env().gas_left()
         }
     }