1  // Copyright (c) 2025-2026 ACDC Network
  2  // This file is part of the alphavm library.
  3  //
  4  // Alpha Chain | Delta Chain Protocol
  5  // International Monetary Graphite.
  6  //
  7  // Derived from Aleo (https://aleo.org) and ProvableHQ (https://provable.com).
  8  // They built world-class ZK infrastructure. We installed the EASY button.
  9  // Their cryptography: elegant. Our modifications: bureaucracy-compatible.
 10  // Original brilliance: theirs. Robert's Rules: ours. Bugs: definitely ours.
 11  //
 12  // Original Aleo/ProvableHQ code subject to Apache 2.0 https://www.apache.org/licenses/LICENSE-2.0
 13  // All modifications and new work: CC0 1.0 Universal Public Domain Dedication.
 14  // No rights reserved. No permission required. No warranty. No refunds.
 15  //
 16  // https://creativecommons.org/publicdomain/zero/1.0/
 17  // SPDX-License-Identifier: CC0-1.0
 18  
 19  //! AX Token error types for AlphaVM.
 20  //!
 21  //! This module defines the error types specific to AX token operations.
 22  //! These errors are used by the AX token interfaces and implementations.
 23  
 24  use core::fmt::{self, Display, Formatter};
 25  
 26  /// Errors that can occur during AX token operations.
 27  ///
 28  /// This enum defines all possible error conditions for AX token
 29  /// balance queries, minting, burning, and transfer operations.
 30  #[derive(Debug, Clone, PartialEq, Eq)]
 31  pub enum AxError {
 32      /// The account has insufficient balance for the requested operation.
 33      ///
 34      /// Contains the required amount and the available balance.
 35      InsufficientBalance {
 36          /// The amount required for the operation (in microcredits).
 37          required: u64,
 38          /// The amount available in the account (in microcredits).
 39          available: u64,
 40      },
 41  
 42      /// The provided amount is invalid.
 43      ///
 44      /// This can occur when an amount string cannot be parsed or
 45      /// when a zero amount is provided where non-zero is required.
 46      InvalidAmount(String),
 47  
 48      /// The caller is not authorized to mint tokens.
 49      ///
 50      /// Only governors are permitted to mint AX tokens.
 51      UnauthorizedMint,
 52  
 53      /// An arithmetic overflow occurred during the operation.
 54      ///
 55      /// This can happen when adding amounts would exceed u64::MAX.
 56      Overflow,
 57  }
 58  
 59  impl Display for AxError {
 60      fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
 61          match self {
 62              Self::InsufficientBalance { required, available } => {
 63                  write!(
 64                      f,
 65                      "insufficient balance: required {} microcredits, available {} microcredits",
 66                      required, available
 67                  )
 68              }
 69              Self::InvalidAmount(msg) => {
 70                  write!(f, "invalid amount: {}", msg)
 71              }
 72              Self::UnauthorizedMint => {
 73                  write!(f, "unauthorized: only governors can mint AX tokens")
 74              }
 75              Self::Overflow => {
 76                  write!(f, "arithmetic overflow in AX token operation")
 77              }
 78          }
 79      }
 80  }
 81  
 82  impl std::error::Error for AxError {}
 83  
 84  #[cfg(test)]
 85  mod tests {
 86      use super::*;
 87  
 88      #[test]
 89      fn test_insufficient_balance_display() {
 90          let err = AxError::InsufficientBalance { required: 100_000, available: 50_000 };
 91          assert_eq!(
 92              format!("{}", err),
 93              "insufficient balance: required 100000 microcredits, available 50000 microcredits"
 94          );
 95      }
 96  
 97      #[test]
 98      fn test_invalid_amount_display() {
 99          let err = AxError::InvalidAmount("negative values not allowed".to_string());
100          assert_eq!(format!("{}", err), "invalid amount: negative values not allowed");
101      }
102  
103      #[test]
104      fn test_unauthorized_mint_display() {
105          let err = AxError::UnauthorizedMint;
106          assert_eq!(format!("{}", err), "unauthorized: only governors can mint AX tokens");
107      }
108  
109      #[test]
110      fn test_overflow_display() {
111          let err = AxError::Overflow;
112          assert_eq!(format!("{}", err), "arithmetic overflow in AX token operation");
113      }
114  
115      #[test]
116      fn test_error_is_error_trait() {
117          // Verify that AxError implements std::error::Error
118          fn assert_error<E: std::error::Error>() {}
119          assert_error::<AxError>();
120      }
121  
122      #[test]
123      fn test_error_equality() {
124          let err1 = AxError::InsufficientBalance { required: 100, available: 50 };
125          let err2 = AxError::InsufficientBalance { required: 100, available: 50 };
126          let err3 = AxError::InsufficientBalance { required: 200, available: 50 };
127  
128          assert_eq!(err1, err2);
129          assert_ne!(err1, err3);
130      }
131  
132      #[test]
133      fn test_error_clone() {
134          let err = AxError::UnauthorizedMint;
135          let cloned = err.clone();
136          assert_eq!(err, cloned);
137      }
138  
139      #[test]
140      fn test_error_debug() {
141          let err = AxError::Overflow;
142          let debug_str = format!("{:?}", err);
143          assert!(debug_str.contains("Overflow"));
144      }
145  }