polyrob 0.5.0__py3-none-any.whl

modules/credits/balance_manager.py

@@ -0,0 +1,237 @@
+"""Credit balance manager for managing user credit balances."""
+
+import logging
+from datetime import datetime
+
+logger = logging.getLogger(__name__)
+
+
+class CreditBalanceManager:
+    """Manage user credit balances."""
+
+    def __init__(self, db, tier_manager=None):
+        """
+        Initialize credit balance manager.
+
+        Args:
+            db: Database manager instance
+            tier_manager: TierManager instance (optional)
+        """
+        self.db = db
+        self.tier_manager = tier_manager
+        self.logger = logging.getLogger('credits.balance_manager')
+
+    async def get_balance(self, user_id: str) -> dict:
+        """Get user's credit balance."""
+
+        result = await self.db.fetch_one("""
+            SELECT balance, lifetime_earned, lifetime_spent
+            FROM user_credits
+            WHERE user_id = ?
+        """, (user_id,))
+
+        if not result:
+            # User must exist (payment_endpoints ensures this now)
+            # Initialize balance
+            await self.db.execute("""
+                INSERT INTO user_credits (user_id, balance)
+                VALUES (?, 0)
+            """, (user_id,))
+            return {"balance": 0, "lifetime_earned": 0, "lifetime_spent": 0}
+
+        return dict(result)
+
+    async def has_sufficient_balance(self, user_id: str, amount: int) -> bool:
+        """Check if user has enough credits."""
+
+        balance = await self.get_balance(user_id)
+        return balance['balance'] >= amount
+
+    async def deduct_credits(self, user_id: str, amount: int,
+                             reason: str, session_id: str = None) -> bool:
+        """
+        Deduct credits from user balance.
+
+        Uses atomic UPDATE with WHERE clause to prevent race conditions.
+        Wrapped in transaction for consistency between balance update and transaction log.
+
+        Args:
+            user_id: User ID
+            amount: Amount to deduct
+            reason: Reason for deduction
+            session_id: Optional session ID
+
+        Returns:
+            True if successful, False if insufficient balance
+        """
+        # Ensure user exists (creates with 0 balance if not)
+        await self.get_balance(user_id)
+
+        try:
+            # Start transaction for atomic operation
+            await self.db.connection.begin_transaction()
+
+            try:
+                # SECURITY FIX: Atomic UPDATE with balance check in WHERE clause
+                # This prevents TOCTOU race condition where two concurrent requests
+                # could both read the same balance before either deducts
+                cursor = await self.db.execute("""
+                    UPDATE user_credits
+                    SET balance = balance - ?,
+                        lifetime_spent = lifetime_spent + ?,
+                        updated_at = CURRENT_TIMESTAMP
+                    WHERE user_id = ? AND balance >= ?
+                """, (amount, amount, user_id, amount))
+
+                # Check if update succeeded (rowcount > 0 means balance was sufficient)
+                if cursor.rowcount == 0:
+                    # No rows updated - insufficient balance
+                    await self.db.connection.rollback()
+
+                    # Get current balance for logging
+                    balance_info = await self.get_balance(user_id)
+                    self.logger.warning(
+                        f"Insufficient credits for {user_id}: need {amount}, have {balance_info['balance']}"
+                    )
+                    return False
+
+                # Get new balance for transaction log
+                balance_info = await self.get_balance(user_id)
+                new_balance = balance_info['balance']
+                # Calculate what balance was before deduction
+                balance_before = new_balance + amount
+
+                # Record transaction (within same transaction)
+                await self.db.execute("""
+                    INSERT INTO credit_transactions (
+                        user_id, amount, transaction_type, reason,
+                        session_id, balance_before, balance_after, timestamp
+                    ) VALUES (?, ?, 'usage', ?, ?, ?, ?, CURRENT_TIMESTAMP)
+                """, (user_id, -amount, reason, session_id, balance_before, new_balance))
+
+                # Commit transaction
+                await self.db.connection.commit()
+
+                self.logger.info(f"Deducted {amount} credits from {user_id}: {reason}")
+                return True
+
+            except Exception as e:
+                # Rollback on any error
+                await self.db.connection.rollback()
+                raise
+
+        except Exception as e:
+            self.logger.error(f"Error deducting credits for {user_id}: {e}")
+            raise
+
+    async def add_credits(self, user_id: str, amount: int,
+                         reason: str, transaction_type: str = 'purchase') -> bool:
+        """
+        Add credits to user balance.
+
+        Args:
+            user_id: User ID
+            amount: Amount to add
+            reason: Reason for addition
+            transaction_type: Type ('purchase', 'allowance', 'refund', 'admin_grant')
+
+        Returns:
+            True if successful
+        """
+
+        # Ensure the row exists (creates with 0 balance if not) so the atomic
+        # UPDATE below actually matches a row.
+        await self.get_balance(user_id)
+
+        # Join an already-open transaction instead of nesting: a caller like
+        # DepositMonitor._process_deposit wraps credit + dedup-row in ONE outer
+        # transaction, and a nested BEGIN raises (while an inner COMMIT would
+        # end the outer transaction early, breaking its rollback guarantee).
+        owns_tx = not await self.db.connection.in_transaction()
+        try:
+            if owns_tx:
+                await self.db.connection.begin_transaction()
+            try:
+                # SECURITY FIX (C2): atomic relative UPDATE, mirroring deduct_credits.
+                # The previous read-modify-write (get_balance -> SET balance=<abs>)
+                # let two concurrent grants both read the same stale balance and the
+                # later absolute write clobber the earlier one — a silently lost grant.
+                await self.db.execute("""
+                    UPDATE user_credits
+                    SET balance = balance + ?,
+                        lifetime_earned = lifetime_earned + ?,
+                        updated_at = CURRENT_TIMESTAMP
+                    WHERE user_id = ?
+                """, (amount, amount, user_id))
+
+                # Read the authoritative post-update balance for the ledger row.
+                balance_info = await self.get_balance(user_id)
+                new_balance = balance_info['balance']
+                balance_before = new_balance - amount
+
+                await self.db.execute("""
+                    INSERT INTO credit_transactions (
+                        user_id, amount, transaction_type, reason,
+                        balance_before, balance_after, timestamp
+                    ) VALUES (?, ?, ?, ?, ?, ?, CURRENT_TIMESTAMP)
+                """, (user_id, amount, transaction_type, reason, balance_before, new_balance))
+
+                if owns_tx:
+                    await self.db.connection.commit()
+            except Exception:
+                if owns_tx:
+                    await self.db.connection.rollback()
+                raise
+        except Exception as e:
+            self.logger.error(f"Error adding credits for {user_id}: {e}")
+            raise
+
+        self.logger.info(f"Added {amount} credits to {user_id}: {reason} ({transaction_type})")
+
+        return True
+
+    async def get_transaction_history(self, user_id: str, limit: int = 50) -> list:
+        """Get user's credit transaction history."""
+
+        results = await self.db.fetch_all("""
+            SELECT
+                amount,
+                transaction_type,
+                reason,
+                session_id,
+                balance_before,
+                balance_after,
+                timestamp
+            FROM credit_transactions
+            WHERE user_id = ?
+            ORDER BY timestamp DESC
+            LIMIT ?
+        """, (user_id, limit))
+
+        return [dict(row) for row in results]
+
+    async def get_monthly_stats(self, user_id: str) -> dict:
+        """Get monthly usage statistics."""
+
+        # Get this month's usage
+        month_usage = await self.db.fetch_one("""
+            SELECT COALESCE(SUM(ABS(amount)), 0) as total
+            FROM credit_transactions
+            WHERE user_id = ?
+                AND transaction_type = 'usage'
+                AND timestamp >= date('now', 'start of month')
+        """, (user_id,))
+
+        # Get this month's purchases
+        month_purchased = await self.db.fetch_one("""
+            SELECT COALESCE(SUM(amount), 0) as total
+            FROM credit_transactions
+            WHERE user_id = ?
+                AND transaction_type IN ('purchase', 'allowance')
+                AND timestamp >= date('now', 'start of month')
+        """, (user_id,))
+
+        return {
+            "month_spent": month_usage['total'] if month_usage else 0,
+            "month_earned": month_purchased['total'] if month_purchased else 0
+        }

modules/credits/cost_utils.py

@@ -0,0 +1,129 @@
+"""
+Shared cost calculation utilities.
+
+SINGLE SOURCE OF TRUTH for cost estimation from token counts.
+All modules should import from here, not duplicate logic.
+
+This module consolidates:
+- webview/stats_service.py::_calculate_cost_from_registry (REMOVED)
+- agents/task/telemetry/service.py::_calculate_cost_from_registry (REMOVED)
+- modules/llm/token_counter.py::estimate_cost (delegates here)
+"""
+
+from typing import Optional, Tuple, Dict, Any
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def calculate_cost_from_tokens(
+    model_name: str,
+    input_tokens: Optional[int] = None,
+    output_tokens: Optional[int] = None,
+    total_tokens: Optional[int] = None,
+    cached_tokens: int = 0
+) -> float:
+    """
+    Calculate API cost from token counts using model registry.
+
+    This is the SINGLE implementation - all other files should import this.
+
+    Args:
+        model_name: Name of the model
+        input_tokens: Number of input/prompt tokens
+        output_tokens: Number of output/completion tokens
+        total_tokens: Total tokens (fallback if split not available)
+        cached_tokens: Number of cached tokens
+
+    Returns:
+        Estimated API cost in USD
+    """
+    from modules.llm.model_registry import calculate_cost
+
+    if not model_name or model_name == "unknown":
+        logger.debug("Cannot calculate cost: invalid model name")
+        return 0.0
+
+    # Use split tokens if available (most accurate)
+    if input_tokens is not None and output_tokens is not None:
+        try:
+            return calculate_cost(
+                model_name=model_name,
+                input_tokens=input_tokens,
+                output_tokens=output_tokens,
+                cached_tokens=cached_tokens
+            )
+        except Exception as e:
+            logger.warning(f"Cost calculation failed for {model_name}: {e}")
+            # Fall through to estimation
+
+    # Fallback: estimate split from total (65% input, 35% output)
+    if total_tokens and total_tokens > 0:
+        estimated_input = int(total_tokens * 0.65)
+        estimated_output = int(total_tokens * 0.35)
+
+        logger.debug(
+            f"Estimating token split for {model_name}: "
+            f"{estimated_input} input + {estimated_output} output = {total_tokens} total"
+        )
+
+        try:
+            return calculate_cost(
+                model_name=model_name,
+                input_tokens=estimated_input,
+                output_tokens=estimated_output,
+                cached_tokens=0  # Can't estimate cached from total
+            )
+        except Exception as e:
+            logger.warning(f"Cost estimation failed for {model_name}: {e}")
+
+    logger.debug(f"Cannot calculate cost for {model_name}: no token data")
+    return 0.0
+
+
+def calculate_user_cost(api_cost_usd: float) -> Tuple[int, float]:
+    """
+    Calculate what user pays from API cost.
+
+    SINGLE SOURCE - uses pricing.py configuration.
+
+    Args:
+        api_cost_usd: What we pay the API provider
+
+    Returns:
+        Tuple of (credits_charged, user_cost_usd)
+    """
+    from modules.credits.pricing import pricing
+    return pricing.calculate_credits_from_api_cost(api_cost_usd)
+
+
+def get_cost_breakdown(api_cost_usd: float) -> Dict[str, Any]:
+    """
+    Get complete cost breakdown for transparency.
+
+    Args:
+        api_cost_usd: What we pay the API provider
+
+    Returns:
+        Dict with complete breakdown including markup
+    """
+    from modules.credits.pricing import pricing
+
+    credits_charged, user_cost_usd = pricing.calculate_credits_from_api_cost(api_cost_usd)
+
+    return {
+        "api_cost_usd": api_cost_usd,
+        "user_cost_usd": user_cost_usd,
+        "credits_charged": credits_charged,
+        "markup": pricing.MARKUP,
+        "markup_usd": user_cost_usd - api_cost_usd
+    }
+
+
+# Re-export for convenience
+__all__ = [
+    'calculate_cost_from_tokens',
+    'calculate_user_cost',
+    'get_cost_breakdown'
+]
+

modules/credits/pricing.py

@@ -0,0 +1,139 @@
+"""
+Credits Module - Pricing Configuration
+
+SINGLE SOURCE OF TRUTH for all credit pricing and cost calculation.
+
+This config is used by:
+- modules/credits/usage_tracker.py (calculates and charges)
+- modules/credits/usage_meter.py (metering)
+- modules/credits/balance_manager.py (balance operations)
+- modules/auth/identity_mapper.py (welcome bonus, DEN allowance)
+- modules/auth/tier_manager.py (tier limits)
+- api/payment_endpoints.py (public pricing API)
+- webview/stats_service.py (display fallback only)
+
+Location: modules/credits/pricing.py
+Why here? Pricing is OWNED by the credits module - it's business logic, not bot config.
+"""
+
+import math
+import os
+from typing import Dict
+
+
+# ============================================================================
+# CREDIT BONUSES - Single source of truth for all bonus amounts
+# ============================================================================
+
+# Welcome bonus given to ALL new users on sign up
+WELCOME_BONUS: int = int(os.environ.get("WELCOME_BONUS", "100"))
+
+# One-time DEN Sign Up Allowance per token ID (prevents transfer abuse)
+DEN_SIGNUP_ALLOWANCE: int = int(os.environ.get("DEN_SIGNUP_ALLOWANCE", "2000"))
+
+
+class PricingConfig:
+    """Centralized pricing configuration for the entire application."""
+
+    # ============================================================================
+    # MARKUP CONFIGURATION (Core business logic)
+    # ============================================================================
+
+    # MARKUP: Users pay API cost × this multiplier
+    # Examples:
+    #   1.00 = 0% markup (users pay exactly what API costs)
+    #   1.20 = 20% markup (users pay API cost + 20%)
+    #   1.50 = 50% markup
+    MARKUP: float = float(os.environ.get("PRICING_MARKUP", "1.00"))
+
+    # ============================================================================
+    # CREDIT SYSTEM (Currency conversion)
+    # ============================================================================
+
+    # How much USD one credit is worth
+    CREDIT_VALUE_USD: float = float(os.environ.get("CREDIT_VALUE_USD", "0.01"))  # 1 credit = $0.01
+
+    # Minimum charge per LLM call (prevents free calls)
+    MIN_CREDIT_CHARGE: int = int(os.environ.get("MIN_CREDIT_CHARGE", "1"))  # Minimum 1 credit
+
+    # ============================================================================
+    # FIXED COSTS (Non-LLM resources)
+    # ============================================================================
+
+    # Session creation cost (infrastructure setup)
+    SESSION_CREATION_COST: int = int(os.environ.get("SESSION_CREATION_COST", "1"))
+
+    # Browser action costs
+    BROWSER_PAGE_LOAD_COST: float = float(os.environ.get("BROWSER_PAGE_LOAD_COST", "0.5"))
+    BROWSER_SCREENSHOT_COST: float = float(os.environ.get("BROWSER_SCREENSHOT_COST", "0.2"))
+    BROWSER_INTERACTION_COST: float = float(os.environ.get("BROWSER_INTERACTION_COST", "0.1"))
+    BROWSER_DEFAULT_COST: float = float(os.environ.get("BROWSER_DEFAULT_COST", "0.5"))
+
+    # Special action costs
+    VISION_CALL_COST: int = int(os.environ.get("VISION_CALL_COST", "2"))
+    TOOL_CALL_COST: float = float(os.environ.get("TOOL_CALL_COST", "0.5"))
+
+    @classmethod
+    def get_markup_info(cls) -> Dict[str, any]:
+        """Get markup information for display/reporting.
+
+        Returns:
+            Dict with markup details and formatted description
+        """
+        markup_percentage = (cls.MARKUP - 1.0) * 100
+
+        return {
+            "markup": cls.MARKUP,
+            "markup_percentage": markup_percentage,
+            "description": f"{markup_percentage:.0f}% markup" if markup_percentage > 0 else "No markup (API cost only)",
+            "credit_value_usd": cls.CREDIT_VALUE_USD,
+            "min_charge": cls.MIN_CREDIT_CHARGE
+        }
+
+    @classmethod
+    def calculate_credits_from_api_cost(cls, api_cost_usd: float) -> tuple[int, float]:
+        """Calculate credits to charge user from API cost.
+
+        This is the CORE pricing logic used throughout the application.
+
+        Args:
+            api_cost_usd: Cost charged by API provider in USD
+
+        Returns:
+            Tuple of (credits_to_charge, user_cost_usd)
+        """
+        # Convert to credits with markup
+        credits_raw = (api_cost_usd / cls.CREDIT_VALUE_USD) * cls.MARKUP
+
+        # ALWAYS round UP to ensure we never charge less than API cost
+        # Using math.ceil() instead of int(x + 0.5) which was incorrectly rounding DOWN
+        # for values like 2.42 → int(2.92) = 2, losing money!
+        credits_charged = max(cls.MIN_CREDIT_CHARGE, math.ceil(credits_raw))
+
+        # Calculate what user actually pays
+        user_cost_usd = credits_charged * cls.CREDIT_VALUE_USD
+
+        return credits_charged, user_cost_usd
+
+    @classmethod
+    def get_browser_action_cost(cls, action_type: str) -> float:
+        """Get cost for browser action.
+
+        Args:
+            action_type: Type of browser action (page_load, screenshot, interaction, etc.)
+
+        Returns:
+            Cost in credits
+        """
+        costs = {
+            "page_load": cls.BROWSER_PAGE_LOAD_COST,
+            "screenshot": cls.BROWSER_SCREENSHOT_COST,
+            "interaction": cls.BROWSER_INTERACTION_COST,
+        }
+        return costs.get(action_type, cls.BROWSER_DEFAULT_COST)
+
+
+# Create singleton instance for easy importing
+# Usage: from modules.credits.pricing import pricing
+#        price = pricing.MARKUP * api_cost
+pricing = PricingConfig()

modules/credits/unified_ledger.py

@@ -0,0 +1,148 @@
+"""Unified agent ledger: one read model over the
+three money organs, so "what did I earn and spend this week, on what" is
+answerable with evidence.
+
+Legs (each fail-open to zeros — the stores live in different backends and any
+may be absent in a given deployment):
+
+- **costs** — LLM/tool self-cost from ``usage_records`` (api_cost_usd is the
+  provider truth; credits are the platform-billing view) in the async
+  ``database_manager`` store;
+- **outbound spend** — wallet payments from the durable telemetry event log's
+  ``wallet_spend`` events (``core/wallet/factory._emit_spend_to_event_log``);
+- **inbound** — x402 receipts from ``x402_payment_requests`` (settled rows),
+  plus the open pipeline (pending agent invoices).
+
+Deliberately read-only and deliberately NOT a new table: `modules/credits`
+stays the platform-billing concern; this is the agent's own balance-sheet VIEW
+joining what already exists (application-level union — the legs share no DB).
+"""
+import logging
+import time
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+
+async def _resolve_db(db=None):
+    if db is not None:
+        return db
+    from core.container import DependencyContainer
+    return DependencyContainer.get_instance().get_service("database_manager")
+
+
+async def _costs_leg(database, user_id: str, days: int) -> Dict[str, Any]:
+    try:
+        row = await database.fetch_one(
+            """SELECT COALESCE(SUM(api_cost_usd), 0) AS api_usd,
+                      COALESCE(SUM(cost), 0) AS credits,
+                      COUNT(*) AS calls
+               FROM usage_records
+               WHERE user_id = ? AND timestamp >= datetime('now', ?)""",
+            (user_id, f"-{int(days)} day"),
+        )
+        return {
+            "llm_api_cost_usd": round(float(row.get("api_usd") or 0), 6) if row else 0.0,
+            "credits_spent": round(float(row.get("credits") or 0), 4) if row else 0.0,
+            "llm_calls": int(row.get("calls") or 0) if row else 0,
+        }
+    except Exception:
+        logger.debug("ledger: usage_records leg unavailable", exc_info=True)
+        return {"llm_api_cost_usd": 0.0, "credits_spent": 0.0, "llm_calls": 0}
+
+
+def _wallet_leg(user_id: str, days: int) -> Dict[str, Any]:
+    if not user_id:
+        # query(user_id=None) means "no filter" — an empty tenant must NEVER
+        # widen into the platform-wide spend aggregate (cross-tenant leak)
+        return {"wallet_spend_usd": 0.0, "wallet_payments": 0}
+    try:
+        from agents.task.telemetry.event_log import get_event_log, event_log_enabled
+        if not event_log_enabled():
+            return {"wallet_spend_usd": 0.0, "wallet_payments": 0}
+        events = get_event_log().query(
+            kind="wallet_spend", user_id=user_id,
+            since_ts=time.time() - days * 86400, limit=1000,
+        )
+        total = 0.0
+        for ev in events or []:
+            attrs = ev.get("attrs") or {}
+            try:
+                total += float(attrs.get("amount_usd") or 0)
+            except (TypeError, ValueError):
+                continue
+        return {"wallet_spend_usd": round(total, 6), "wallet_payments": len(events or [])}
+    except Exception:
+        logger.debug("ledger: wallet_spend leg unavailable", exc_info=True)
+        return {"wallet_spend_usd": 0.0, "wallet_payments": 0}
+
+
+async def _inbound_leg(database, user_id: str, days: int) -> Dict[str, Any]:
+    try:
+        tenant_like = f'%"tenant_id": "{user_id}"%'
+        settled = await database.fetch_one(
+            """SELECT COALESCE(SUM(amount_usd), 0) AS usd, COUNT(*) AS n
+               FROM x402_payment_requests
+               WHERE (user_id = ? OR metadata LIKE ?)
+                 AND status IN ('completed', 'settled_no_tx')
+                 AND created_at >= datetime('now', ?)""",
+            (user_id, tenant_like, f"-{int(days)} day"),
+        )
+        pending = await database.fetch_one(
+            """SELECT COALESCE(SUM(amount_usd), 0) AS usd, COUNT(*) AS n
+               FROM x402_payment_requests
+               WHERE (user_id = ? OR metadata LIKE ?) AND status = 'pending'""",
+            (user_id, tenant_like),
+        )
+        return {
+            "earned_usd": round(float(settled.get("usd") or 0), 6) if settled else 0.0,
+            "settled_payments": int(settled.get("n") or 0) if settled else 0,
+            "pending_invoices_usd": round(float(pending.get("usd") or 0), 6) if pending else 0.0,
+            "pending_invoices": int(pending.get("n") or 0) if pending else 0,
+        }
+    except Exception:
+        logger.debug("ledger: x402 inbound leg unavailable", exc_info=True)
+        return {"earned_usd": 0.0, "settled_payments": 0,
+                "pending_invoices_usd": 0.0, "pending_invoices": 0}
+
+
+async def build_ledger(user_id: str, *, days: int = 7, db=None) -> Dict[str, Any]:
+    """The unified balance-sheet view for one tenant over a trailing window.
+
+    Tenant-scoped by contract: an empty user_id is refused (mirrors
+    MEMORY_REQUIRE_USER_ID) — anonymity must never widen into an all-tenants view.
+    """
+    if not user_id:
+        raise ValueError("accounting requires an authenticated tenant (empty user_id refused)")
+    days = max(1, int(days))
+    database = await _resolve_db(db)
+    costs = (await _costs_leg(database, user_id, days)) if database is not None else {
+        "llm_api_cost_usd": 0.0, "credits_spent": 0.0, "llm_calls": 0}
+    inbound = (await _inbound_leg(database, user_id, days)) if database is not None else {
+        "earned_usd": 0.0, "settled_payments": 0,
+        "pending_invoices_usd": 0.0, "pending_invoices": 0}
+    wallet = _wallet_leg(user_id, days)
+    total_out = costs["llm_api_cost_usd"] + wallet["wallet_spend_usd"]
+    return {
+        "user_id": user_id,
+        "window_days": days,
+        **costs,
+        **wallet,
+        **inbound,
+        "total_spend_usd": round(total_out, 6),
+        "net_usd": round(inbound["earned_usd"] - total_out, 6),
+    }
+
+
+def format_ledger(ledger: Dict[str, Any]) -> str:
+    """Agent/owner-readable rendering of :func:`build_ledger` (pure)."""
+    return (
+        f"Ledger — last {ledger['window_days']}d (tenant {ledger['user_id'] or '(all)'})\n"
+        f"  earned:   ${ledger['earned_usd']:.4f} across {ledger['settled_payments']} settled payment(s)\n"
+        f"  pending:  ${ledger['pending_invoices_usd']:.4f} across {ledger['pending_invoices']} open invoice(s)\n"
+        f"  spent:    ${ledger['total_spend_usd']:.4f} total — "
+        f"${ledger['llm_api_cost_usd']:.4f} LLM/API ({ledger['llm_calls']} calls), "
+        f"${ledger['wallet_spend_usd']:.4f} wallet ({ledger['wallet_payments']} payment(s))\n"
+        f"  credits:  {ledger['credits_spent']:.2f} platform credits consumed\n"
+        f"  net:      ${ledger['net_usd']:+.4f}"
+    )