recover_epoch tx comments

transactions/epoch/admin/recover_epoch.cdc

@@ -3,14 +3,16 @@ import FlowIDTableStaking from "FlowIDTableStaking"
 import FlowClusterQC from "FlowClusterQC"
 
 // The recoverEpoch transaction creates and starts a new epoch in the FlowEpoch smart contract
-// to which will force the network exit EFM. The recoverEpoch service event will be emitted 
-// and processed by all protocol participants and each participant will update their protocol 
-// state with the new Epoch data.
+// which will cause the network exit Epoch Fallback Mode [EFM]. The RecoverEpoch service event
+// will be processed by the consensus committee, which will add it to the Protocol State.
+//
 // This transaction should only be used with the output of the bootstrap utility:
 //   util epoch efm-recover-tx-args
-// Note: setting unsafeAllowOverwrite to true will force the FlowEpoch contract to overwrite the current 
-// epoch with the new configuration. If you need to instantiate a brand new epoch with the new configuration 
-// this should be set to false.
+//
+// NOTE: setting unsafeAllowOverwrite to true will allow the FlowEpoch contract to overwrite the current 
+// epoch with the new configuration, if the recoveryEpochCounter matches (otherwise will panic).
+// This function exists to recover from potential race conditions that caused a prior recoverCurrentEpoch transaction to fail;
+// this allows operators to retry the recovery procedure, overwriting the prior failed attempt.
 transaction(recoveryEpochCounter: UInt64,
             startView: UInt64,
             stakingEndView: UInt64,
@@ -27,7 +29,7 @@ transaction(recoveryEpochCounter: UInt64,
 
     prepare(signer: auth(BorrowValue) &Account) {
         let epochAdmin = signer.storage.borrow<&FlowEpoch.Admin>(from: FlowEpoch.adminStoragePath)
-            ?? panic("Could not borrow epoch admin from storage path")
+            ?? panic("Could not borrow epoch admin from ".concat(FlowEpoch.adminStoragePath.toString()))
 
         let proposedEpochCounter = FlowEpoch.proposedEpochCounter()
         if recoveryEpochCounter == proposedEpochCounter {
@@ -48,8 +50,11 @@ transaction(recoveryEpochCounter: UInt64,
             )
         } else {
             // Atypical path: RecoveryEpoch is overwriting existing epoch. 
+            // CAUTION: This causes data loss by replacing the existing current epoch metadata with the inputs to this function.
+            // This function exists to recover from potential race conditions that caused a prior recoverCurrentEpoch transaction to fail;
+            // this allows operators to retry the recovery procedure, overwriting the prior failed attempt.
             if !unsafeAllowOverwrite {
-                panic("cannot overwrite existing epoch with safety flag specified")
+                panic("Cannot overwrite existing epoch without unsafeAllowOverwrite set to true")
             }
             epochAdmin.recoverCurrentEpoch(
                 recoveryEpochCounter: recoveryEpochCounter,