consensus_stage Enum

namespace keychain {
    enum class consensus_stage {
        PENDING,        // Transaction submitted but not yet processed
        VALIDATING,     // Transaction being validated by consensus
        CONFIRMED,      // Transaction confirmed by consensus
        FINALIZED,      // Transaction finalized and immutable
        REJECTED        // Transaction rejected by consensus
    };
}

#include <keychain/keychain.h>

// Monitor transaction progress
keychain::transaction tx;
// ... create and submit transaction ...

// Check current stage
auto stage = tx.get_consensus_stage();
switch (stage) {
    case keychain::consensus_stage::PENDING:
        std::cout << "Transaction pending..." << std::endl;
        break;
    case keychain::consensus_stage::VALIDATING:
        std::cout << "Transaction being validated..." << std::endl;
        break;
    case keychain::consensus_stage::CONFIRMED:
        std::cout << "Transaction confirmed!" << std::endl;
        break;
    case keychain::consensus_stage::FINALIZED:
        std::cout << "Transaction finalized!" << std::endl;
        // Safe to proceed with business logic
        break;
    case keychain::consensus_stage::REJECTED:
        std::cout << "Transaction rejected" << std::endl;
        // Handle error case
        break;
}

// Wait for specific stage
bool wait_for_confirmation(keychain::transaction& tx) {
    while (true) {
        auto stage = tx.get_consensus_stage();
        if (stage == keychain::consensus_stage::CONFIRMED ||
            stage == keychain::consensus_stage::FINALIZED) {
            return true;
        }
        if (stage == keychain::consensus_stage::REJECTED) {
            return false;
        }
        std::this_thread::sleep_for(std::chrono::seconds(1));
    }
}

stateDiagram-v2
    [*] --> PENDING : Transaction submitted
    PENDING --> VALIDATING : Picked up by consensus
    PENDING --> REJECTED : Invalid transaction
    VALIDATING --> CONFIRMED : Consensus reached
    VALIDATING --> REJECTED : Validation failed
    CONFIRMED --> FINALIZED : Finality achieved
    CONFIRMED --> REJECTED : Reorganization (rare)
    REJECTED --> [*]
    FINALIZED --> [*]

// Handle rejection with error details
if (tx.get_consensus_stage() == keychain::consensus_stage::REJECTED) {
    auto result = tx.get_ledger_result();
    if (result != keychain::ledger_result::SUCCESS) {
        std::cerr << "Transaction rejected: " << to_string(result) << std::endl;

        // Get detailed error information
        auto error_details = tx.get_error_details();
        for (const auto& error : error_details) {
            std::cerr << "  - " << error << std::endl;
        }
    }
}