Remove BelowSubsistenceThreshold and NewContractNotFunded (#1062)

* Remove `BelowSubsistenceThreshold` and `NewContractNotFunded`

* Fix `clippy:single-match`

* Fix doc-link

* Fix `clippy:redundant-pattern-matching`

* Fix error codes

* Fix error codes

* Remove superfluous whitespace

* Clarity what minimum balance refers to

* Fix typo: chain's ➜ chains

* Revert "Fix typo: chain's ➜ chains"

This reverts commit 40c0920.

crates/engine/src/ext.rs

@@ -75,23 +75,21 @@ define_error_codes! {
     CalleeReverted = 2,
     /// The passed key does not exist in storage.
     KeyNotFound = 3,
-    /// Transfer failed because it would have brought the sender's total balance
-    /// below the subsistence threshold.
-    BelowSubsistenceThreshold = 4,
+    /// Deprecated and no longer returned: There is only the minimum balance.
+    _BelowSubsistenceThreshold = 4,
     /// Transfer failed for other not further specified reason. Most probably
     /// reserved or locked balance of the sender that was preventing the transfer.
     TransferFailed = 5,
-    /// The newly created contract is below the subsistence threshold after executing
-    /// its constructor so no usable contract instance will be created.
-    NewContractNotFunded = 6,
+    /// Deprecated and no longer returned: Endowment is no longer required.
+    _EndowmentTooLow = 6,
     /// No code could be found at the supplied code hash.
     CodeNotFound = 7,
-    /// The account that was called is no contract, but a plain account.
+    /// The account that was called is no contract.
     NotCallable = 8,
     /// The call to `seal_debug_message` had no effect because debug message
     /// recording was disabled.
     LoggingDisabled = 9,
-    /// ECDSA pubkey recovery failed. Most probably wrong recovery id or signature.
+    /// ECDSA public key recovery failed. Most probably wrong recovery id or signature.
     EcdsaRecoveryFailed = 11,
 }
 

crates/env/src/api.rs

@@ -155,7 +155,8 @@ where
     })
 }
 
-/// Returns the minimum balance that is required for creating an account.
+/// Returns the minimum balance that is required for creating an account
+/// (i.e. the chain's existential deposit).
 ///
 /// # Errors
 ///
@@ -324,9 +325,10 @@ where
 ///
 /// # Errors
 ///
-/// - If the contract does not have sufficient funds.
+/// - If the contract does not have sufficient free funds.
 /// - If the transfer had brought the sender's total balance below the
-///   subsistence threshold.
+///   minimum balance. You need to use [`terminate_contract`] in case
+///   this is your intention.
 pub fn transfer<T>(destination: T::AccountId, value: T::Balance) -> Result<()>
 where
     T: Environment,

crates/env/src/backend.rs

@@ -339,7 +339,8 @@ pub trait TypedEnvBackend: EnvBackend {
     /// For more details visit: [`block_number`][`crate::block_number`]
     fn block_number<T: Environment>(&mut self) -> T::BlockNumber;
 
-    /// Returns the minimum balance that is required for creating an account.
+    /// Returns the minimum balance that is required for creating an account
+    /// (i.e. the chain's existential deposit).
     ///
     /// # Note
     ///

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

@@ -105,9 +105,9 @@ impl From<ext::Error> for crate::Error {
             ext::Error::CalleeTrapped => Self::CalleeTrapped,
             ext::Error::CalleeReverted => Self::CalleeReverted,
             ext::Error::KeyNotFound => Self::KeyNotFound,
-            ext::Error::BelowSubsistenceThreshold => Self::BelowSubsistenceThreshold,
+            ext::Error::_BelowSubsistenceThreshold => Self::_BelowSubsistenceThreshold,
             ext::Error::TransferFailed => Self::TransferFailed,
-            ext::Error::NewContractNotFunded => Self::NewContractNotFunded,
+            ext::Error::_EndowmentTooLow => Self::_EndowmentTooLow,
             ext::Error::CodeNotFound => Self::CodeNotFound,
             ext::Error::NotCallable => Self::NotCallable,
             ext::Error::LoggingDisabled => Self::LoggingDisabled,

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

@@ -100,7 +100,8 @@ impl ChainSpec {
         self.gas_price = OffBalance::new(&gas_price)
     }
 
-    /// Returns the minimum balance that is required for creating an account.
+    /// Returns the minimum balance that is required for creating an account
+    /// (i.e. the chain's existential deposit).
     pub fn minimum_balance<T>(&self) -> Result<T::Balance>
     where
         T: Environment,

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

@@ -62,23 +62,21 @@ define_error_codes! {
     CalleeReverted = 2,
     /// The passed key does not exist in storage.
     KeyNotFound = 3,
-    /// Transfer failed because it would have brought the sender's total balance
-    /// below the subsistence threshold.
-    BelowSubsistenceThreshold = 4,
+    /// Deprecated and no longer returned: There is only the minimum balance.
+    _BelowSubsistenceThreshold = 4,
     /// Transfer failed for other not further specified reason. Most probably
     /// reserved or locked balance of the sender that was preventing the transfer.
     TransferFailed = 5,
-    /// The newly created contract is below the subsistence threshold after executing
-    /// its constructor so no usable contract instance will be created.
-    NewContractNotFunded = 6,
+    /// Deprecated and no longer returned: Endowment is no longer required.
+    _EndowmentTooLow = 6,
     /// No code could be found at the supplied code hash.
     CodeNotFound = 7,
     /// The account that was called is no contract.
     NotCallable = 8,
      /// The call to `seal_debug_message` had no effect because debug message
     /// recording was disabled.
     LoggingDisabled = 9,
-    /// ECDSA pubkey recovery failed. Most probably wrong recovery id or signature.
+    /// ECDSA public key recovery failed. Most probably wrong recovery id or signature.
     EcdsaRecoveryFailed = 11,
 }
 

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

@@ -102,9 +102,9 @@ impl From<ext::Error> for Error {
             ext::Error::CalleeTrapped => Self::CalleeTrapped,
             ext::Error::CalleeReverted => Self::CalleeReverted,
             ext::Error::KeyNotFound => Self::KeyNotFound,
-            ext::Error::BelowSubsistenceThreshold => Self::BelowSubsistenceThreshold,
+            ext::Error::_BelowSubsistenceThreshold => Self::_BelowSubsistenceThreshold,
             ext::Error::TransferFailed => Self::TransferFailed,
-            ext::Error::NewContractNotFunded => Self::NewContractNotFunded,
+            ext::Error::_EndowmentTooLow => Self::_EndowmentTooLow,
             ext::Error::CodeNotFound => Self::CodeNotFound,
             ext::Error::NotCallable => Self::NotCallable,
             ext::Error::LoggingDisabled => Self::LoggingDisabled,

crates/env/src/error.rs

@@ -31,15 +31,13 @@ pub enum Error {
     CalleeReverted,
     /// The queried contract storage entry is missing.
     KeyNotFound,
-    /// Transfer failed because it would have brought the sender's total balance
-    /// below the subsistence threshold.
-    BelowSubsistenceThreshold,
+    /// Deprecated and no longer returned: There is only the minimum balance.
+    _BelowSubsistenceThreshold,
     /// Transfer failed for other not further specified reason. Most probably
     /// reserved or locked balance of the sender that was preventing the transfer.
     TransferFailed,
-    /// The newly created contract is below the subsistence threshold after executing
-    /// its constructor so no usable contract instance will be created.
-    NewContractNotFunded,
+    /// Deprecated and no longer returned: Endowment is no longer required.
+    _EndowmentTooLow,
     /// No code could be found at the supplied code hash.
     CodeNotFound,
     /// The account that was called is no contract, but a plain account.

crates/lang/src/env_access.rs

@@ -388,7 +388,8 @@ where
         ink_env::block_number::<T>()
     }
 
-    /// Returns the minimum balance that is required for creating an account.
+    /// Returns the minimum balance that is required for creating an account
+    /// (i.e. the chain's existential deposit).
     ///
     /// # Example
     ///

examples/contract-transfer/lib.rs

@@ -12,21 +12,6 @@ pub mod give_me {
     #[ink(storage)]
     pub struct GiveMe {}
 
-    /// The error types.
-    #[derive(Debug, PartialEq, Eq, scale::Encode, scale::Decode)]
-    #[cfg_attr(feature = "std", derive(scale_info::TypeInfo))]
-    pub enum Error {
-        /// Returned if the transfer failed.
-        TransferFailed,
-        /// Insufficient funds to execute transfer.
-        InsufficientFunds,
-        /// Transfer failed because it would have brought the contract's
-        /// balance below the subsistence threshold. No transfer is
-        /// allowed to do this. Use `self.env().terminate()` to recover
-        /// the deposit.
-        BelowSubsistenceThreshold,
-    }
-
     impl GiveMe {
         /// Creates a new instance of this contract.
         #[ink(constructor)]
@@ -39,8 +24,9 @@ pub mod give_me {
         /// # Errors
         ///
         /// - Panics in case the requested transfer exceeds the contract balance.
-        /// - Panics in case the requested transfer would have brought the
-        ///   contract balance below the subsistence threshold.
+        /// - Panics in case the requested transfer would have brought this
+        ///   contract's balance below the minimum balance (i.e. the chain's
+        ///   existential deposit).
         /// - Panics in case the transfer failed for another reason.
         #[ink(message)]
         pub fn give_me(&mut self, value: Balance) {
@@ -49,15 +35,12 @@ pub mod give_me {
 
             assert!(value <= self.env().balance(), "insufficient funds!");
 
-            match self.env().transfer(self.env().caller(), value) {
-                Err(ink_env::Error::BelowSubsistenceThreshold) => {
-                    panic!(
-                        "requested transfer would have brought contract\
-                        below subsistence threshold!"
-                    )
-                }
-                Err(_) => panic!("transfer failed!"),
-                Ok(_) => {}
+            if self.env().transfer(self.env().caller(), value).is_err() {
+                panic!(
+                    "requested transfer failed. this can be the case if the contract does not\
+                     have sufficient free funds or if the transfer would have brought the\
+                     contract's balance below minimum balance."
+                )
             }
         }