Merge pull request #6641 from Jiloc/chore/document-cost-errors

chore: add docstrings for `CostErrors`

Author: francesco-stacks

clarity-types/src/errors/cost.rs

@@ -16,16 +16,43 @@ use std::fmt;
 
 use crate::execution_cost::ExecutionCost;
 
+/// Errors related to cost tracking and resource accounting in the Clarity VM.
+///
+/// Each error variant is annotated with "Invalidates Block" status, indicating
+/// whether the inclusion of the transaction that caused the error should cause
+/// an entire block to be rejected.
 #[derive(Debug, PartialEq, Eq)]
 pub enum CostErrors {
-    CostComputationFailed(String),
+    /// Arithmetic overflow in cost computation during type-checking, exceeding the maximum threshold.
+    /// Invalidates Block: true.
     CostOverflow,
+    /// Cumulative type-checking cost exceeds the allocated budget, indicating budget depletion.
+    /// The first `ExecutionCost` represents the total consumed cost, and the second represents the budget limit.
+    /// Invalidates Block: true.
     CostBalanceExceeded(ExecutionCost, ExecutionCost),
+    /// Memory usage during type-checking exceeds the allocated budget.
+    /// The first `u64` represents the total consumed memory, and the second represents the memory limit.
+    /// Invalidates Block:
+    ///  - true if happens during contract analysis
+    ///  - false if happens during contract intitialization or contract call.
     MemoryBalanceExceeded(u64, u64),
+    /// Failure to access or load cost-related contracts or their state during runtime operations.
+    /// Invalidates Block: false.
     CostContractLoadFailure,
+    /// Failure in cost-tracking due to an unexpected condition or invalid state.
+    /// The `String` wraps the specific reason for the failure.
+    /// Invalidates Block: false.
+    CostComputationFailed(String),
+    // Time checker errors
+    /// Type-checking time exceeds the allowed budget, halting analysis to ensure responsiveness.
+    /// Invalidates Block: true.
+    ExecutionTimeExpired,
+    /// Unexpected condition or failure, indicating a bug or invalid state.
+    /// Invalidates Block: true.
     InterpreterFailure,
+    /// Unexpected condition or failure, indicating a bug or invalid state.
+    /// Invalidates Block: true.
     Expect(String),
-    ExecutionTimeExpired,
 }
 
 impl fmt::Display for CostErrors {

clarity/src/vm/clarity.rs

@@ -81,6 +81,28 @@ impl From<CheckError> for Error {
     }
 }
 
+/// Converts [`InterpreterError`] to [`Error`] for transaction execution contexts.
+///
+/// This conversion is used in:
+/// - [`TransactionConnection::initialize_smart_contract`]
+/// - [`TransactionConnection::run_contract_call`]
+/// - [`TransactionConnection::run_stx_transfer`]
+///
+/// # Notes
+///
+/// - [`CheckErrors::MemoryBalanceExceeded`] and [`CheckErrors::CostComputationFailed`]
+///   are intentionally not converted to [`Error::CostError`].
+///   Instead, they remain wrapped in `Error::Interpreter(Unchecked(CheckErrors::MemoryBalanceExceeded))`,
+///   which causes the transaction to fail, but still be included in the block.
+///
+/// - This behavior differs from direct conversions of [`CheckError`] and [`ParseError`] to [`Error`],
+///   where [`CheckErrors::MemoryBalanceExceeded`] is converted to [`Error::CostError`],
+///   during contract analysis.
+///
+///   As a result:
+///   - A `MemoryBalanceExceeded` during contract analysis causes the block to be rejected.
+///   - A `MemoryBalanceExceeded` during execution (initialization or contract call)
+///     causes the transaction to fail, but the block remains valid.
 impl From<InterpreterError> for Error {
     fn from(e: InterpreterError) -> Self {
         match &e {