rusk: comments explaining the deployment code

rusk/src/lib/chain/rusk.rs

@@ -521,6 +521,8 @@ fn execute(
     tx: &PhoenixTransaction,
     gas_per_deploy_byte: Option<u64>,
 ) -> Result<CallReceipt<Result<Vec<u8>, ContractError>>, PiecrustError> {
+    // Transaction will be discarded if it is a deployment transaction
+    // with gas limit smaller than deploy charge.
     if let Some(deploy) = tx.payload().contract_deploy() {
         let deploy_charge =
             bytecode_charge(&deploy.bytecode, &gas_per_deploy_byte);
@@ -541,7 +543,21 @@ fn execute(
         tx.payload().fee.gas_limit,
     )?;
 
-    // Deploy if this is a deployment transaction
+    // Deploy if this is a deployment transaction.
+    // Deployment transaction will fail and charge full gas limit in the
+    // following cases:
+    // 1) Transaction gas limit is smaller than deploy charge plus gas used for
+    //    spending funds.
+    // 2) Transaction's bytecode's bytes are not consistent with bytecode's
+    //    hash.
+    // 3) Deployment fails for deploy-specific reasons like e.g.:
+    //      - 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.
     if let Some(deploy) = tx.payload().contract_deploy() {
         if receipt.data.is_ok() {
             let deploy_charge =