[E2E] Call builders and extra gas margin option

CHANGELOG.md

@@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ## Changed
+- [E2E] E2E call builders and extra gas margin option - [#1917](https://github.com/paritytech/ink/pull/1917)
 - Make `set_code_hash` generic - [#1906](https://github.com/paritytech/ink/pull/1906)
 
 ## Version 5.0.0-alpha

crates/e2e/src/backend.rs

@@ -14,10 +14,15 @@
 
 use super::Keypair;
 use crate::{
+    backend_calls::{
+        InstantiateBuilder,
+        UploadBuilder,
+    },
     builders::CreateBuilderPartial,
+    contract_results::BareInstantiationResult,
+    CallBuilder,
     CallBuilderFinal,
     CallDryRunResult,
-    CallResult,
     InstantiationResult,
     UploadResult,
 };
@@ -27,6 +32,7 @@ use ink_env::{
 };
 use jsonrpsee::core::async_trait;
 use pallet_contracts_primitives::ContractInstantiateResult;
+use sp_weights::Weight;
 use subxt::dynamic::Value;
 
 /// Full E2E testing backend: combines general chain API and contract-specific operations.
@@ -42,7 +48,7 @@ pub trait ChainBackend {
     /// Account type.
     type AccountId;
     /// Balance type.
-    type Balance: Send;
+    type Balance: Send + From<u32>;
     /// Error type.
     type Error;
     /// Event log type.
@@ -93,6 +99,60 @@ pub trait ContractsBackend<E: Environment> {
     /// Event log type.
     type EventLog;
 
+    /// Start building an instantiate call using a builder pattern.
+    ///
+    /// # Example
+    ///
+    /// ```ignore
+    /// // Constructor method
+    /// let constructor = FlipperRef::new(false);
+    /// let contract = client
+    ///     .instantiate("flipper", &ink_e2e::alice(), constructor)
+    ///     // Optional arguments
+    ///     // Send 100 units with the call.
+    ///     .value(100)
+    ///     // Add 10% margin to the gas limit
+    ///     .extra_gas_portion(10)
+    ///     .storage_deposit_limit(100)
+    ///     // Submit the call for on-chain execution.
+    ///     .submit()
+    ///     .await
+    ///     .expect("instantiate failed");
+    /// ```
+    fn instantiate<'a, Contract, Args: Send + Clone + scale::Encode + Sync, R>(
+        &'a mut self,
+        contract_name: &'a str,
+        caller: &'a Keypair,
+        constructor: CreateBuilderPartial<E, Contract, Args, R>,
+    ) -> InstantiateBuilder<'a, E, Contract, Args, R, Self>
+    where
+        Self: std::marker::Sized,
+    {
+        InstantiateBuilder::new(self, caller, contract_name, constructor)
+    }
+
+    /// Submits an instantiate call with a gas margin.
+    ///
+    /// Intended to be used as part of builder API.
+    async fn instantiate_with_gas_margin<
+        Contract,
+        Args: Send + scale::Encode + Clone,
+        R,
+    >(
+        &mut self,
+        contract_name: &str,
+        caller: &Keypair,
+        constructor: CreateBuilderPartial<E, Contract, Args, R>,
+        value: E::Balance,
+        margin: Option<u64>,
+        storage_deposit_limit: Option<E::Balance>,
+    ) -> Result<InstantiationResult<E, Self::EventLog>, Self::Error>;
+
+    /// Bare instantiate call. This function does perform a dry-run,
+    /// and user is expected to provide the gas limit.
+    ///
+    /// Use it when you want to have a more precise control over submitting extrinsic.
+    ///
     /// The function subsequently uploads and instantiates an instance of the contract.
     ///
     /// This function extracts the metadata of the contract at the file path
@@ -101,17 +161,22 @@ pub trait ContractsBackend<E: Environment> {
     /// Calling this function multiple times should be idempotent, the contract is
     /// newly instantiated each time using a unique salt. No existing contract
     /// instance is reused!
-    async fn instantiate<Contract, Args: Send + scale::Encode, R>(
+    async fn bare_instantiate<Contract, Args: Send + scale::Encode + Clone, R>(
         &mut self,
         contract_name: &str,
         caller: &Keypair,
         constructor: CreateBuilderPartial<E, Contract, Args, R>,
         value: E::Balance,
+        gas_limit: Weight,
         storage_deposit_limit: Option<E::Balance>,
-    ) -> Result<InstantiationResult<E, Self::EventLog>, Self::Error>;
+    ) -> Result<BareInstantiationResult<E, Self::EventLog>, Self::Error>;
 
     /// Dry run contract instantiation.
-    async fn instantiate_dry_run<Contract, Args: Send + scale::Encode, R>(
+    async fn bare_instantiate_dry_run<
+        Contract,
+        Args: Send + Sync + scale::Encode + Clone,
+        R,
+    >(
         &mut self,
         contract_name: &str,
         caller: &Keypair,
@@ -120,39 +185,104 @@ pub trait ContractsBackend<E: Environment> {
         storage_deposit_limit: Option<E::Balance>,
     ) -> ContractInstantiateResult<E::AccountId, E::Balance, ()>;
 
+    /// Start building an upload call.
+    /// # Example
+    ///
+    /// ```ignore
+    /// let contract = client
+    ///     .upload("flipper", &ink_e2e::alice())
+    ///     // Optional arguments
+    ///     .storage_deposit_limit(100)
+    ///     // Submit the call for on-chain execution.
+    ///     .submit()
+    ///     .await
+    ///     .expect("upload failed");
+    /// ```
+    fn upload<'a>(
+        &'a mut self,
+        contract_name: &'a str,
+        caller: &'a Keypair,
+    ) -> UploadBuilder<E, Self>
+    where
+        Self: Sized,
+    {
+        UploadBuilder::new(self, contract_name, caller)
+    }
+
     /// The function subsequently uploads and instantiates an instance of the contract.
     ///
     /// This function extracts the Wasm of the contract for the specified contract.
     ///
     /// Calling this function multiple times should be idempotent, the contract is
     /// newly instantiated each time using a unique salt. No existing contract
     /// instance is reused!
-    async fn upload(
+    async fn bare_upload(
         &mut self,
         contract_name: &str,
         caller: &Keypair,
         storage_deposit_limit: Option<E::Balance>,
     ) -> Result<UploadResult<E, Self::EventLog>, Self::Error>;
 
-    /// Executes a `call` for the contract at `account_id`.
+    /// Start building a call using a builder pattern.
+    ///
+    /// # Example
+    ///
+    /// ```ignore
+    /// // Message method
+    /// let get = call.get();
+    /// let get_res = client
+    ///    .call(&ink_e2e::bob(), &get)
+    ///     // Optional arguments
+    ///     // Send 100 units with the call.
+    ///     .value(100)
+    ///     // Add 10% margin to the gas limit
+    ///     .extra_gas_portion(10)
+    ///     .storage_deposit_limit(100)
+    ///     // Submit the call for on-chain execution.
+    ///     .submit()
+    ///     .await
+    ///     .expect("instantiate failed");
+    /// ```
+    fn call<'a, Args: Sync + scale::Encode + Clone, RetType: Send + scale::Decode>(
+        &'a mut self,
+        caller: &'a Keypair,
+        message: &'a CallBuilderFinal<E, Args, RetType>,
+    ) -> CallBuilder<'a, E, Args, RetType, Self>
+    where
+        Self: std::marker::Sized,
+    {
+        CallBuilder::new(self, caller, message)
+    }
+
+    /// Executes a bare `call` for the contract at `account_id`. This function does
+    /// perform a dry-run, and user is expected to provide the gas limit.
+    ///
+    /// Use it when you want to have a more precise control over submitting extrinsic.
     ///
     /// Returns when the transaction is included in a block. The return value
     /// contains all events that are associated with this transaction.
-    async fn call<Args: Sync + scale::Encode, RetType: Send + scale::Decode>(
+    async fn bare_call<
+        Args: Sync + scale::Encode + Clone,
+        RetType: Send + scale::Decode,
+    >(
         &mut self,
         caller: &Keypair,
         message: &CallBuilderFinal<E, Args, RetType>,
         value: E::Balance,
+        gas_limit: Weight,
         storage_deposit_limit: Option<E::Balance>,
-    ) -> Result<CallResult<E, RetType, Self::EventLog>, Self::Error>
+    ) -> Result<Self::EventLog, Self::Error>
     where
         CallBuilderFinal<E, Args, RetType>: Clone;
 
     /// Executes a dry-run `call`.
     ///
     /// Returns the result of the dry run, together with the decoded return value of the
     /// invoked message.
-    async fn call_dry_run<Args: Sync + scale::Encode, RetType: Send + scale::Decode>(
+    async fn bare_call_dry_run<
+        Args: Sync + scale::Encode + Clone,
+        RetType: Send + scale::Decode,
+    >(
         &mut self,
         caller: &Keypair,
         message: &CallBuilderFinal<E, Args, RetType>,