rusk: improved comment for the execute method

rusk/src/lib/chain/rusk.rs

@@ -515,10 +515,6 @@ fn bytecode_charge(
 //      - contract already deployed
 //      - corrupted bytecode
 //      - sufficient gas to spend funds yet insufficient for deployment
-// Note that deployment transaction will never be re-executed for reasons
-// related to deployment, as it is either discarded or it requires full
-// gas limit to be charged. It might be re-executed only if some other
-// transaction failed to fit the block.
 fn contract_deploy(
     session: &mut Session,
     deploy: &ContractDeploy,
@@ -554,14 +550,36 @@ fn contract_deploy(
 /// Executes a transaction, returning the receipt of the call and the gas spent.
 /// The following steps are performed:
 ///
-/// 1. Call the "spend_and_execute" function on the transfer contract with
+/// 1. Check if the transaction contains contract deployment data, and if so,
+///    verifies if gas limit is enough for deployment. If gas limit is not
+///    sufficient for deployment, transaction is discarded.
+///
+/// 2. Call the "spend_and_execute" function on the transfer contract with
 ///    unlimited gas. If this fails, an error is returned. If an error is
 ///    returned the transaction should be considered unspendable/invalid, but no
 ///    re-execution of previous transactions is required.
 ///
-/// 2. Call the "refund" function on the transfer contract with unlimited gas.
+/// 3. If the transaction contains contract deployment data, additional checks
+///    are performed and if they pass, deployment is executed. The following
+///    checks are performed:
+///    - gas limit should be is smaller than deploy charge plus gas used for
+///      spending funds
+///    - transaction's bytecode's bytes are consistent with bytecode's hash
+///    Deployment execution may fail for deployment-specific reasons, such as
+///    for example:
+///    - contract already deployed
+///    - corrupted bytecode
+///    If deployment execution fails, the entire gas limit is consumed and error
+///    is returned.
+///
+/// 4. Call the "refund" function on the transfer contract with unlimited gas.
 ///    The amount charged depends on the gas spent by the transaction, and the
-///    optional contract call in step 1.
+///    optional contract call in steps 2 or 3.
+///
+/// Note that deployment transaction will never be re-executed for reasons
+/// related to deployment, as it is either discarded or it charges the
+/// full gas limit. It might be re-executed only if some other transaction
+/// failed to fit the block.
 fn execute(
     session: &mut Session,
     tx: &PhoenixTransaction,