# Subscription System

The **Subscription System** enables creators to gate premium content behind a daily-access subscription, enforced via NFT ownership and managed by real-time access rules. This system balances creator earnings with clear permissions logic and seamless UX.

***

### 🧱 System Overview

The system includes two core smart contracts:

* **`SubscriptionNFT.sol`** – A non-transferable token representing an active subscription to a creator’s content.
* **`SubscriptionManager.sol`** – The controller that handles minting, revocation, pricing enforcement, auto-renewal, and access checks.

All subscription logic is enforced at the smart contract level and validated during view attempts by content consumers.

***

### 🎟️ How Subscriptions Work

* Users **subscribe** to a creator by minting a `SubscriptionNFT`.
* Subscriptions are priced **per day**, and pricing is set **by the creator**.
* Once minted, the NFT allows access to **all of that creator's gated posts** for the current cycle (1 day).
* **Renewal** is automatic as long as the user has sufficient credit (fruit balance) and no moderation flags.
* If a subscription price changes, **existing subscribers are paused** and must **opt-in again** at the new price.
* Users may **not burn and repurchase** the NFT again — once revoked, they are **permanently blocked** from resubscribing to the same creator.

***

### ⏳ Pricing, Pausing & Re-entry Rules

| Event                              | Behavior                                                                |
| ---------------------------------- | ----------------------------------------------------------------------- |
| Creator raises subscription price  | All active subscriptions are **paused**. Users must opt-in at new rate. |
| User pauses their own subscription | Discouraged. Paused users must re-opt-in (if still allowed).            |
| Creator lowers subscription price  | Users may opt-in again if previously blocked.                           |
| Price changes mid-day              | Apply to next cycle only. Current cycle finishes as-is.                 |

Subscriptions are **disincentivized from being paused**, as a new opt-in is always required — and previously banned users **may not opt in again**.

***

### 💳 Payment Mechanics

* Subscriptions cost **TRN per day** (price defined by the creator).
* All subscription purchases and renewals go through the **TRNUsageOracle**.
* If a user subscribes **mid-day**, the system allows **temporary credit** based on projected fruit earnings.
* Renewals are processed **after the Merkle drop** using actual earned TRN (not projections).
* If a user is **too far in debt** to renew, subscription renewal is blocked until they **watch ads**, **earn TRN**, or otherwise top-up.

**Negative balances are never allowed.** All subscription logic is fully enforced by the `TRNUsageOracle`.

***

### 📄 NFT Behavior

| Rule                         | Behavior                                                              |
| ---------------------------- | --------------------------------------------------------------------- |
| Non-transferable             | Users may not trade or sell SubscriptionNFTs.                         |
| Burnable (by contract logic) | NFTs may be revoked automatically if user is banned or price changes. |
| Permanent revocation         | Once burned, users **can never re-subscribe** to that creator.        |
| One per creator per user     | No stacking, splitting, or multiple subs.                             |

The **NFT acts as a flag** for viewing eligibility during each access check.

***

### 🔎 Access Control Flow

Every time a user tries to view a gated post:

1. **Does the post require a subscription?**
2. **Does the user hold a valid SubscriptionNFT for that creator?**
3. **Has the NFT expired or been paused?**
4. **Is the user in good standing (not restricted or burned)?**

If all conditions pass, access is granted. If any fail, the post remains locked.

***

### 🏦 Revenue Distribution

* 90% of subscription revenue goes to the creator (post-Merkle, via `PostVaultSplitter`).
* 10% goes to the DAO vault via `DailyVaultSplitter`.
* All funds are routed via the `TRNUsageOracle` and are logged in the day’s fruit ledger.

Subscription renewals are **automatically applied** as part of the Merkle batch process.

***

### ⚠️ Moderation & Restrictions

* SubscriptionNFTs can be **force-burned** if the creator is banned or the user is restricted.
* A user’s reputation or flags do **not affect visibility** of their content, but can restrict future subscription activity.
* CountryNFT restrictions still apply — if a user is geo-blocked, they will be unable to view content **even if subscribed**.

***

### 🔄 Integration Modules

| Module                    | Function                                               |
| ------------------------- | ------------------------------------------------------ |
| `SubscriptionNFT.sol`     | NFT representing daily subscription                    |
| `SubscriptionManager.sol` | Manages minting, burn rules, pricing, and renewals     |
| `TRNUsageOracle.sol`      | Enforces subscription payment, credit, and view access |
| `PostVaultSplitter.sol`   | Routes subscription revenue to creators                |
| `DailyVaultSplitter.sol`  | Sends DAO share of subscription income                 |
| `BurnRegistry.sol`        | Logs any subscription-related forced revocations       |

***

### 🧠 Design Principles

* **Simple UX**: No staking, no manual renewals, no wallets to manage daily.
* **Immutable Ban Logic**: If you burn a creator’s sub, you can never return.
* **Price = Access**: Each day is a fresh opt-in at the current price — no long-term lock-ins.
* **Oracle-Enforced Security**: All credit/debit events are reconciled via Merkle batches.
