> For the complete documentation index, see [llms.txt](https://docs.veloxlabs.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.veloxlabs.xyz/subscription_model_v2_notes.md).

# Subscription Model V2 Notes

This document captures the subscription model decisions discussed for the next monetization phase.

## Goals

* Monetize the platform while remaining accessible for smaller users.
* Avoid "all-or-nothing" high-cost access by allowing smaller bundles.
* Keep implementation modular using entitlements and plan bundles.
* Support safe iteration in non-production environments first.

## Core Product Model

### 1) Entitlements (atomic capabilities)

Use feature-level entitlements as building blocks:

* `manual_trade`
* `volume_bot`
* `bundler`
* `launch_token`

Plans are bundles of these entitlements.

### 2) Plan Bundles

Target bundles discussed:

1. Volume Bot + Manual Trade
2. Bundler + Manual Trade
3. Manual Trade only
4. Launch Token only
5. Launch Token + Bundler
6. Launch Token + Volume Bot + Bundler
7. Complete package (all functions)

### 3) Chain Unit and Add-ons

* One unit = one chain.
* Commercial model = base plan + extra chains as add-ons.
* Users may subscribe to chains at different times.
* A user may operate one chain per session.

## Time and Renewal Rules

### 4) Rolling Durations (not calendar-based)

* Daily = 24 hours
* Weekly = 168 hours
* Monthly = 720 hours

These are rolling durations from grant/renewal time, not calendar month boundaries.

### 5) Expiry Scope

* Use separate expiry per chain.
* Each chain entitlement has its own lifecycle.

### 6) Stacking Behavior

If a user repurchases before expiry, time adds to the end:

`new_expiry = max(now, current_expiry_for_chain) + purchased_duration`

### 7) Renewal Mode

* Manual repurchase only.
* No auto-renew in V2 baseline.

## Access Gate and Onboarding

### 8) Gate Type

* Pay-to-enter gate.
* Access is granted after successful crypto payment.

### 9) Onboarding

* Add a gated onboarding service where user pays in crypto for access.
* Payment success should trigger entitlement + whitelist updates.

### 10) Whitelist and Test Accounts

* All-access users should be whitelisted through the token gate process.
* Define two test accounts for staging/testing:
  * 1 admin test account
  * 1 user test account
* These test accounts should be able to operate with unpaid full access in test flows.

## Reminder and UX Rules

### 11) Reminder Thresholds

Show renewal reminders when remaining access crosses:

* 50%
* 25%
* 10%

Use percent-of-remaining-time logic per chain entitlement period.

### 12) Reminder Surface

* Dashboard/in-app broadcast is acceptable for V2 initial implementation.
* Primary UX action: "Extend Access" when low or expired.

## Fee Context (Current-State Compatibility)

Current fee logic (already in codebase) collects a profit fee on profitable sells for active subscriptions. When implementing V2 tiers, ensure fee behavior is explicitly mapped to tier semantics (for example, whether `free` should be fee-eligible or excluded).

## Implementation Guidance

* Prefer entitlements + plan composition instead of hardcoding many plan-specific code paths.
* Keep chain entitlement records explicit (including `chain_id`, `expires_at`, `period_seconds`).
* Ensure payment processing is idempotent (avoid duplicate extension for repeated callbacks).
* Keep staging and production environments fully separated for testing and rollout safety.

## Open Questions for Build Phase

These should be finalized before production release:

1. Exact tier naming and display order in UI.
2. Whether chain add-ons inherit base entitlements 1:1 or use a subset.
3. Whether reminders should include additional channels (email/Telegram/push) beyond dashboard.
4. Migration strategy for existing users and existing subscription flags.