aether-economy

Double-entry ledger, wallets, and transaction processing

The aether-economy crate provides the financial backbone for Aether's virtual economy. It implements a double-entry ledger, wallet management, fraud detection, transaction coordination, and settlement/payout processing.

Overview

All value transfers in Aether flow through this crate's ledger. The double-entry design ensures that every credit has a matching debit, maintaining an auditable record. Features include:

• Double-entry ledger with typed currency entries and audit trail.
• Wallet management with balance constraints and operation history.
• Transaction coordination with idempotency, rollback, and state tracking.
• Fraud detection using velocity windows, anomaly signals, and risk scoring.
• Settlement and payout for creator earnings with destination routing.

Key Types

CurrencyLedger

The central ledger that records all financial entries using double-entry bookkeeping.

use aether_economy::{CurrencyLedger, LedgerEntry, LedgerKind};

let mut ledger = CurrencyLedger::new();
ledger.record(LedgerEntry {
    kind: LedgerKind::Credit,
    account: buyer_wallet,
    amount: 100,
    currency: "aether_coin".into(),
    reference: transaction_id,
});

WalletAccount

Represents a user's wallet with balance tracking and operation constraints.

use aether_economy::{WalletAccount, WalletConstraint, WalletOperation};

let wallet = WalletAccount::new(user_id);
let op = WalletOperation::Debit { amount: 50 };
wallet.apply(op, WalletConstraint::NonNegativeBalance)?;

TransactionCoordinator

Manages the lifecycle of a transaction from initiation through completion or rollback.

use aether_economy::{
    TransactionCoordinator, EconomyTransaction, TransactionKind,
    TransactionState,
};

let mut coordinator = TransactionCoordinator::new();
let tx = EconomyTransaction {
    kind: TransactionKind::Purchase,
    from: buyer_wallet,
    to: seller_wallet,
    amount: 250,
    currency: "aether_coin".into(),
};
let result = coordinator.execute(tx)?;
assert_eq!(result.state, TransactionState::Completed);

FraudScore

Computes a risk score for a transaction based on velocity patterns and anomaly signals.

use aether_economy::{FraudScore, FraudSignal, VelocityWindow, AnomalySignal};

let score = FraudScore::evaluate(&[
    FraudSignal::HighVelocity(VelocityWindow::OneHour),
    FraudSignal::Anomaly(AnomalySignal::UnusualAmount),
]);
if score.is_high_risk() {
    // Hold transaction for manual review
}

SettlementStream

Processes pending payouts to creators, batching settlements by destination.

use aether_economy::{SettlementStream, PayoutDestination, PayoutRecord, SettlementState};

let mut settlement = SettlementStream::new();
settlement.enqueue(PayoutRecord {
    recipient: creator_id,
    destination: PayoutDestination::BankTransfer,
    amount: 1000,
    currency: "usd".into(),
});
settlement.process_batch()?;

Usage Examples

Complete Purchase Flow

use aether_economy::{
    TransactionCoordinator, EconomyTransaction, TransactionKind,
    CurrencyLedger, WalletAccount, IdempotencyRecord,
};

let mut coordinator = TransactionCoordinator::new();
let mut ledger = CurrencyLedger::new();

// Idempotent transaction execution
let tx = EconomyTransaction {
    kind: TransactionKind::Purchase,
    from: buyer,
    to: seller,
    amount: 100,
    currency: "aether_coin".into(),
};
let result = coordinator.execute(tx)?;
// Ledger entries are created automatically

Wallet Summary

use aether_economy::WalletSummary;

let summary: WalletSummary = wallet.summarize();
// Contains balance, pending holds, and recent transaction count