TRNUsageOracle

The TRNUsageOracle is the central enforcement mechanism for all TRN-based interactions across the platform. It is responsible for maintaining a real-time, authoritative ledger of token usage, earnings, and balances—ensuring that no user can spend, transfer, or withdraw more than they are allowed. It acts as the binding agent between user activity, the Merkle distribution process, off-chain indexing, and on-chain enforcement.

Core Responsibilities

1. Real-Time Usage Ledger

   • Tracks every view, post, retrn, subscription, bless, brn, and ad interaction.

   • Deducts TRN usage in real-time, including crediting fruit (earnings) and debiting costs.

2. Balance Enforcement

   • All user transactions (including TRN→TRN transfers) must pass through the TRNUsageOracle.

   • The oracle confirms:

     • Whether the user has available TRN (or fruit-based credit) to complete the transaction.

     • Whether the transaction would cause a negative balance or exceed available earnings.

   • No action is permitted that would place a user into debt.

3. Merkle Drop Integration

   • At the top of every UTC day, the system finalizes the day’s transactions via a Merkle tree.

   • The oracle confirms:

     • Pending balance changes (fruit earnings, pending debits).

     • Final settlement amounts and distributes TRN or adjusts balances accordingly.

   • After settlement, accounts are “evened out,” and a new fruit balance begins.

4. Withdrawal and Transfer Control

   • Users must settle their ledger balance before withdrawing or transferring any TRN.

   • If a user attempts to transfer out TRN, the oracle:

     • Ensures all prior usage is reconciled.

     • Denies the transfer if any part of the day’s usage is unpaid or would result in an unreconciled state.

   • This prevents gaming the system (e.g., consuming 300 views, then draining the wallet).

5. Credit Enforcement

   • Users may use TRN “on credit” during the day if their projected earnings (fruit) exceed their spending.

   • The TRNUsageOracle and the off-chain index work together to simulate this in real-time.

   • Credit is short-term and never leaves the ecosystem—it is always reconciled at Merkle drop time.

6. Interaction Gating

   • If the oracle determines that a user has reached a balance of 0 (or exceeded their credit ceiling):

     • All interactions are paused.

     • They can still access:

       • Their own posts.

       • Previously paid-for content.

       • Boosted posts (used to earn TRN by watching ads).

     • They can resume interactions after earning TRN via content, receiving fruit, or watching ads.

7. Boosted Post Enforcement

   • Boosted post views go through the oracle.

   • Viewers receive 90% of the cost as TRN credit.

   • Funds are tracked on the ledger immediately and included in the next Merkle drop.

8. Subscription Management

   • Auto-renews subscriptions after Merkle drop using fruit or remaining balance.

   • If subscription is initiated mid-day, oracle allows it only if user has sufficient projected balance.

   • If a user burns or is revoked from a subscription, the oracle blocks future access permanently.

9. Ad View Tracking

   • When users opt into ads:

     • The oracle credits their fruit balance after each ad is viewed completely.

     • Ensures the interaction was legitimate (e.g., minimum watch time, audio required, cannot scroll).

   • This earns spendable TRN and re-enables platform usage if paused.

10. Price-Limit Enforcement on Swaps

    • Interacts with both internal AMMs to:

      • Block any TRN↔USD or TRN↔BRN swaps that would move the price more than 2%.

      • Enforce transaction limits (e.g., 333,333 TRN per swap).

Design Principles

• Immutable and Referenceable:

  • The off-chain index provides the frontend with a real-time, immutable view of the ledger.

  • This simulates deductions and earnings before Merkle reconciliation occurs.

• Real-Time Feedback:

  • The UI reflects the user’s fruit balance, current balance, and pending changes via the oracle.

  • Alerts the user when nearing zero or about to be paused.

• Security and Abuse Resistance:

  • All interactions run through the oracle hook—including user-to-user transfers.

  • Bots, exploiters, or scripted abuse attempts are detected by AI Bot Verifier hooks and blocked.

• Strict Accounting Model:

  • No staking is used.

  • All balance changes are fully visible and auditable.

  • Transfers only occur if all debt is cleared and usage has been fully recorded in the index.

• Withdrawal Gatekeeping:

  • Withdrawal requests are denied if:

    • The user has pending interactions not reconciled to the Merkle tree.

    • The transaction would cause the price to shift outside of the 2% range.

  • Withdrawal is tied to off-chain KYC and fiat endpoints for user experience.

System Integrations

Component	Role in Oracle Integration
TRN Token	All token transfers route through oracle logic.
BRN Token	Burns tracked, but BRN is never held by users directly.
ViewIndex	Posts cost 1 TRN each; deducted on interaction.
RetrnIndex	Earnings are credited for posts that are retrned and generate engagement.
BoostingModule	Costs 3x per view; 90% paid to viewer through the ledger.
SubscriptionManager	Handles NFT renewals and payment enforcement post-drop.
TRN↔BRN AMM	Routes interaction-related swaps through oracle.
TRN↔USD AMM	Monitors market activity; oracle enforces price change limits.
BurnRegistry	Registers burns for moderation and index tallying.
DailyVaultSplitter	Calculates and applies daily distributions post-Merkle drop.
FlagEscalator	Influences moderation-triggered burn or disablement tied to oracle flows.

Technical Hooks

solidityCopyEditfunction transfer(address to, uint256 amount) public override {
    require(TRNUsageOracle.canTransfer(msg.sender, amount), "Insufficient cleared balance");
    super.transfer(to, amount);
}

This contract hook ensures no tokens can be moved if they haven’t been cleared through the usage ledger. It is used in all TRN-related token actions, regardless of context.

Files to Reference

• TRNUsageOracle.sol

• TRNUsageOracleViewAdapter.ts

• FruitBalanceLedger.sol

• DailyUsageMerklizer.ts

• InteractionPauseController.sol

• AdCreditTracker.sol

• WithdrawalGuard.ts

Summary

The TRNUsageOracle is the heartbeat of TRN accounting. It ensures that consumption and earnings are perfectly matched, prevents all forms of overuse, guards platform liquidity, and powers the seamless yet strict financial infrastructure of the TRN ecosystem.

If it is not approved by the oracle, it does not happen.