TRNUsageOracleViewAdapter

Module Type: Off-chain Read Interface Category: Identity & Access Purpose: Provides real-time, read-only access to TRN user state — including fruit balances, earned TRN, pending debits, ad eligibility, and restrictions — for frontend display and validator checks.

Purpose

The TRNUsageOracleViewAdapter is an off-chain interface used by the platform to expose read-only user account state derived from the authoritative TRNUsageOracle.

This view adapter powers:

• Real-time frontend balance displays

• User action eligibility checks (e.g. can subscribe, can boost, can claim)

• Daily fruit ledger rendering

• Ad targeting filters (e.g. is user allowed to view ads)

• Admin monitoring of usage patterns

All data surfaced through this adapter is derived from the on-chain oracle and Merkle reconciliation ledger. No speculative balance calculations occur off-chain. All states are enforced by contract logic before any action is allowed.

---

📋 Exposed Data Points

Each user has a dynamic identity profile computed through this adapter. The following read-only properties are exposed in real-time:

Field	Description
availableFruit	TRN fruit balance available for spending
pendingBoostBudget	TRN set aside for active boost campaigns
pendingSubscriptionDebit	Scheduled auto-renewal subscription costs pending settlement
earnedToday	Fruit TRN earned from views, retrns, boosts, and blessings since last drop
debitedToday	TRN consumed from subscriptions, burns, content views
netDailyDelta	Difference between earned and spent TRN in the current cycle
boostEligibility	Boolean indicating if the user can currently boost content
subscriptionEligibility	Boolean indicating if the user can renew or purchase subscriptions
adWatchEligibility	Boolean indicating if the user may watch ads for TRN
fruitIsZero	True if user's spendable balance is 0 (triggers view restrictions)
viewableContentFilter	CID filters for what the user may still view in zero-fruit state
botFlagStatus	Internal flag, only exposed to admin interfaces
userWithdrawalStatus	Whether user is cleared for KYC-based withdrawal to fiat
lastMerkleDropReference	ID of last reconciliation batch applied
creditBufferInEffect	Whether the user is operating on expected earnings not yet settled

---

🔐 Permissioning

The TRNUsageOracleViewAdapter is fully read-only and used by:

• The app UI layer to determine access controls

• The boost and subscription modules to check eligibility

• Ad delivery systems to verify post-payment capability

• DAO admin panels to audit flagged or suspicious activity

It does not expose sensitive fraud detection data such as the internal scoring used by the AI Bot Verifier — only the public-facing “can or cannot proceed” flags derived from them.

---

⚙️ Internal Source Logic

This adapter reads live data from:

• TRNUsageOracle — The canonical real-time balance and debt ledger

• Daily MerkleDrop reconciliation — Used to update fruit balances and finalize earnings

• User’s wallet transaction history

• BoostingModule, SubscriptionManager, BurnRegistry, and other engagement subsystems

All actions on the platform (e.g. viewing content, subscribing, boosting) must consult this adapter prior to execution. It guarantees that users never accidentally overspend, and that no transaction violates TRN balance logic.

---

🚫 When Access Is Blocked

If the fruitIsZero flag returns true, then the user is considered temporarily ineligible for further paid activity until they:

• View boosted posts (which are still allowed and earn TRN)

• View content already paid for during the current day

• Watch ads to earn fresh TRN

• Create a post that earns retrns or blessings to replenish their fruit

All other actions — subscription renewals, boosts, and fiat withdrawals — will be blocked until the user is back above zero fruit.

---

🪙 Example Flow

1. User logs in

2. App requests TRNUsageOracleViewAdapter.getUserState(userCid)

3. Response:

   jsonCopyEdit{
     "availableFruit": 2.5,
     "pendingBoostBudget": 0.8,
     "pendingSubscriptionDebit": 1.2,
     "earnedToday": 4.0,
     "debitedToday": 2.7,
     "boostEligibility": true,
     "subscriptionEligibility": true,
     "adWatchEligibility": true,
     "fruitIsZero": false,
     "creditBufferInEffect": true
   }

4. App enables content viewing, ad watching, and boost initiation

5. User proceeds to view content or interact based on available fruit

---

🔄 Relationship to Other Modules

Related Module	How It Connects
TRNUsageOracle	The root data source; all states are derived from its ledger
BoostingModule	Consults this adapter to validate campaign initiation and credits
SubscriptionManager	Reads this to allow or block new or renewing subscriptions
DebtSettlementModule	Prevents outgoing TRN transfers if debt status is unresolved
Merkle Tree Drops	Adapter reflects all changes after the daily batch reconciliation
LottoModule	May exclude users with flags or ineligible fruit status