MyFans – Decentralized Content Subscription Platform (Stellar)

MyFans is a decentralized content subscription platform built on Stellar and Soroban. It lets creators monetize their work with on-chain subscriptions, direct payments, and transparent revenue—using Stellar’s speed, low cost, and multi-currency support.

Why Stellar

Speed & cost: 3–5 second finality and very low fees, suitable for subscriptions and micro-payments.
Multi-currency: Native support for XLM and Stellar assets (e.g. USDC, EURT) so fans can pay in stablecoins or XLM.
Soroban: Rust/Wasm smart contracts with deterministic execution and a strong SDK.
Ecosystem: Anchors and on/off-ramps can connect subscriptions to fiat (card, bank).
Scale: Stellar handles high throughput; no gas auctions or volatile fees.

Problems MyFans Solves

Problem	MyFans approach
High platform fees	Direct creator payouts; small, transparent protocol fee.
Delayed or opaque payments	On-chain subscriptions and instant settlement.
Single-currency lock-in	Pay in XLM or any Stellar asset (e.g. USDC).
Centralized access control	Subscription and access enforced in Soroban contracts.
No fiat-friendly path	Backend + frontend can integrate anchors/ramps for card/bank.

Architecture Overview

┌─────────────────────────────────────────────────────────────────────────┐
│                           MyFans Platform                                 │
├─────────────────┬─────────────────────────┬─────────────────────────────┤
│   frontend/     │      backend/           │      contract/              │
│   (Next.js)     │      (Nest.js)          │      (Soroban/Rust)         │
├─────────────────┼─────────────────────────┼─────────────────────────────┤
│ • Wallet connect│ • Auth & sessions       │ • Subscription lifecycle    │
│   (Freighter,   │ • Creator/fan APIs      │ • Payment routing & fees    │
│    Lobstr, etc.)│ • Content metadata      │ • Access control (is        │
│ • Creator       │ • IPFS / storage refs   │   subscriber?)              │
│   dashboard     │ • Webhooks / events     │ • Multi-asset payments      │
│ • Fan discovery │ • Indexer / analytics   │ • Pause, cancel, renew      │
│ • Subscription  │ • Notifications         │                             │
│   management    │ • Contract event poller │                             │
│                 │ • JWT auth (Stellar key) │                             │
└────────┬────────┴────────────┬────────────┴──────────────┬──────────────┘
         │                     │                            │
         └─────────────────────┼────────────────────────────┘
                               ▼
                    ┌──────────────────────┐
                    │  Stellar / Soroban    │
                    │  (XLM, USDC, etc.)    │
                    └──────────────────────┘

Repository Structure

Folder	Role
`contract/`	Soroban smart contract (Rust). Subscription state, payments, access control.
`frontend/`	Next.js app. Creator and fan UI, wallet connection, subscription flows.
`backend/`	Nest.js API. Auth, content metadata, IPFS refs, indexing, notifications.

You will keep only these three folders and this README; other files can be removed.

Getting Started

New here? Start with the QUICKSTART.md — the single canonical first-hour guide from a clean clone to subscribing on Stellar testnet with Freighter. It covers the honest wallet support matrix, required environment variables (including where contract ids come from), the local Docker Compose stack, and CSP/network troubleshooting.

Documentation

QUICKSTART.md – clone-to-subscribe on testnet (Freighter-first).
Contract Upgrade Governance – required process, upgrade log, and rollback criteria for mainnet contract upgrades.
Contract Changelog – version history for the Soroban contracts.
Security Policy – how to report vulnerabilities.

1. Smart Contract (Soroban) – `contract/`

Responsibilities

Subscription lifecycle: Create subscription (plan, asset, amount, interval), renew, cancel, pause.
Payment logic: Accept payments in configured Stellar asset; split creator vs protocol fee; optional escrow for chargebacks/disputes.
Access control: Expose “is subscriber” (and optionally tier/expiry) for backend/frontend to gate content.
Multi-asset: Support XLM and Stellar tokens (e.g. USDC) so creators can choose accepted assets.

Suggested contract interface (conceptual)

init(admin, protocol_fee_bps, fee_recipient) – set fee (in basis points) and recipient. Admin-only; the fee is capped at MAX_FEE_BPS = 1_000 (10%) and can never be set to 100%. fee_recipient must be the deployed treasury contract.
set_protocol_fee_bps(admin, bps) – admin-only (require_auth on the stored admin; non-admin callers revert). Enforces bps <= MAX_FEE_BPS (1_000 = 10%); bps > 1_000 (e.g. 10_000 or 10_001) reverts. bps = 0 is explicitly allowed and disables the protocol fee. Emits a FeeUpdated event for indexers/analytics.
set_fee_recipient(admin, recipient) – admin-only. The recipient is restricted to the deployed treasury contract (allowlisted); setting it to any other address (e.g. a fan address) reverts. This keeps the treasury recipient invariant intact.
create_plan(creator, asset, amount, interval_days) – define a subscription plan.
subscribe(fan, plan_id, duration) – fan subscribes; payment is split: creator receives the amount minus the protocol fee, and the fee is routed into the treasury via its deposit(from, amount) entry point (pause honored, deposit event emitted).
renew(subscription_id) – renew if within allowed window.
cancel(subscription_id) – cancel; no refund of current period (or implement refund rules in contract).
is_subscriber(fan, creator) → bool (and optionally expiry).
Events for: subscription_created, payment_received, subscription_cancelled, fee_updated (for indexer/backend).

Tech

Rust, soroban-sdk.
Build & test: stellar-cli / soroban-cli; deploy to Stellar testnet/mainnet via CLI or CI.

Upgrading

Contract upgrades on mainnet MUST follow docs/CONTRACT_UPGRADE_GOVERNANCE.md, including the upgrade log and rollback criteria.

2. Frontend – `frontend/`

Responsibilities

Wallets: Connect Freighter, Lobstr, or other Stellar wallets (via standard Stellar/Soroban wallet interfaces).
Creators: Dashboard to create plans, set pricing (XLM or asset), view subscribers and earnings.
Fans: Discover creators, view plans, subscribe (sign Soroban tx), manage active subscriptions.
UX: Show subscription status, next billing, and “access granted” for gated content.

Wallet support today

The current frontend wallet implementation does not treat all wallets equally:

Wallet	Current repo status	Practical difference in MyFans
Freighter	Fully wired for connection and transaction signing	The reference wallet. Guaranteed for every flow; local onboarding (see QUICKSTART.md) is Freighter-only
Lobstr	Connection and signing dispatch wired (`signTransaction` routes to Lobstr when it is the connected wallet)	Usable for connect + subscribe/cancel signing; still less battle-tested than Freighter
WalletConnect	Sign Client wired behind the `walletConnect` feature flag (off by default); requires `NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID`	Enable the flag + set a project ID for QR-based mobile wallet connect/sign. With the flag off the UI shows "Coming soon"

Assume Freighter is the reference implementation and the only wallet with a guaranteed full-flow path. Lobstr and WalletConnect share the same signTransaction dispatch path but have had less real-world exercise. See frontend/docs/WALLET_SETUP.md for the full support matrix, feature-flag config, and signing dispatch order.

Tech

Next.js (App Router or Pages as you prefer).

3. Backend – `backend/`

Responsibilities

Auth: Sessions or JWTs; link Stellar public key to “user” (creator/fan).
Creator/fan APIs: Profiles, plans metadata (mirroring or complementing on-chain plan_id), content catalog.
Content & IPFS: Store content metadata and IPFS links; serve “content access” API that checks subscription via contract (e.g. call is_subscriber or use indexer data).
Indexer: Subscribe to Soroban events or use Stellar Horizon + Soroban events to keep “subscriptions” and “payments” in DB for analytics and fast “is subscriber?” checks.
Notifications: Email/in-app for new subscribers, renewals, cancellations (using indexer/events).
Optional: Integrate Stellar anchors/ramps for fiat on/off-ramp.

Tech

Nest.js, TypeScript.
DB: e.g. PostgreSQL (users, plans metadata, content, subscription cache

Data Flow (High Level)

Creator sets a plan on-chain (contract) and optionally registers plan metadata in backend.
Fan chooses a plan in frontend; frontend builds Soroban subscribe tx; fan signs with Stellar wallet; contract executes payment and updates subscription state.
Backend indexes contract events (or polls contract), updates DB; when fan requests gated content, backend checks DB or calls contract to confirm is_subscriber.
Frontend shows “Subscribed until …” and

Tech Stack Summary

Layer	Technologies
Chain & contracts	Stellar, Soroban, Rust, soroban-sdk, stellar-cli
Frontend	Next.js, TypeScript, Stellar SDK, wallet integration
Backend	Nest.js, TypeScript, PostgreSQL (or similar), Stellar/Soroban RPC, IPFS (metadata/refs)
Storage	IPFS (content refs), DB (metadata, indexer cache)

Development Milestones

Contract
- Implement subscription lifecycle (create plan, subscribe, renew, cancel).
- Implement payment split (creator + protocol fee) for one asset, then multi-asset.
- Emit events; add access control (is_subscriber).
- Unit tests; deploy to testnet.
Backend
- Nest.js project; auth (Stellar key ↔ user); CRUD for creators, plans metadata, content.
- Integrate Soroban RPC; event indexer or polling; “is subscriber?” API.
- IPFS for content refs; optional notifications.
Frontend
- Next.js; wallet connect; creator dashboard (create plan, view earnings); fan flow (discover, subscribe, manage subscriptions).
- Use backend for metadata and access checks; use contract for tx signing and state.
Integration
- End-to-end: create plan → subscribe → access gated content.
- Optional: fiat on-ramp (anchor) so fans can pay with card. See Fiat On-Ramp Spike.
Launch
- Testnet beta (runbook, bug bash); security review; mainnet deployment (readiness gate); docs and community.

Getting Started (After Initialization)

Install dependencies for all packages:

./scripts/myfans install
# or: npm run install:all

Build everything:

./scripts/myfans build
# or: npm run build

Run dev servers (separate terminals):

./scripts/myfans dev:backend   # NestJS API on :3001
./scripts/myfans dev:frontend  # Next.js app on :3000

Full local verification (lint + test + build):

./scripts/myfans check

Per-package commands are also available via root package.json scripts (build:backend, test:contract, etc.) or by cd-ing into each folder:

Contract: cd contract && cargo test; npm run build for WASM artifacts (deploy with stellar-cli). See Contract Testing Guide.
Backend: cd backend && npm ci && npm run start:dev.
Frontend: cd frontend && npm ci && npm run dev.

Documentation

Contract Development

Contract Testing Guide - Comprehensive testing patterns and best practices for Soroban contracts
Regression Testing Guide - How contract regression testing is enforced in CI
Regression Prevention Checklist - Developer checklist for PR submission
Contract Branch Protection - CI status checks required before merge
Contract Interfaces - Method documentation for each contract

Platform Governance & Operations

Contract Upgrade Governance - Process for upgrading smart contracts safely
Security Policy - Security reporting, penetration testing tracker, and best practices
Secret Management - JWT and secret rotation runbooks
CORS & Security Headers - Per-environment CORS allowlist and header configuration
Bug Bash Checklist - Binary pass/fail testnet beta checklist: money path, auth, gating, pause, CSRF/CSP headers, a11y
Testnet Beta Runbook - Ordered launch steps: deploy contracts, set IDs, enable poller, pause drill, invites, rollback
Mainnet Readiness Gate - Go/no-go checklist: audits, pause tested, backups, monitoring, fee caps, sign-off
Fiat On-Ramp Spike - Anchor/ramp evaluation, threat model, and MVP recommendation
Changelog Guide - How to use conventional commits for automatic changelog generation
Postgres Backup / Restore - Backup runbook, restore decision tree, and CI drill
Dependency Update Policy - Dependabot schedule, grouping, and review rules for bot PRs
E2E Testnet Path - Create plan → subscribe → gated access proof on testnet, with nightly job

Development

Changelog - Automatically generated from conventional commits
Upgrade Log - Historical record of contract upgrades

License

MIT.

Contact

Email: realjaiboi70@gmail.com

This README describes the MyFans project on Stellar. Implement each module (contract, backend, frontend) step by step as needed.

Handsoff notes

#1781: SubscriptionsModule: checkout, index, spending-cap, swagger completeness

#1751: creator-deposits: stake/deposit withdraw security—unauthorized withdraw leaves stake unchanged

#1753: myfans-lib: eliminate panics from library paths; stable error_codes for all callers

#1791: FavoritesModule persistence APIs replacing local-only context as source of truth

#1794: EarningsModule prepare/confirm withdraw orchestration with chain

#1788: FeedModule: subscription-gated teasers, cursor pagination, no full body leak

#1821: Fan subscriptions pages: active/history/payments from /v1/subscriptions only

Name		Name	Last commit message	Last commit date
.github		.github
backend		backend
contract		contract
docs		docs
frontend		frontend
scripts		scripts
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
QUICKSTART.md		QUICKSTART.md
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json

Navigation Menu

Repository navigation

About

Repository files navigation

MyFans – Decentralized Content Subscription Platform (Stellar)

Why Stellar

Problems MyFans Solves

Architecture Overview

Repository Structure

Getting Started

Documentation

1. Smart Contract (Soroban) – `contract/`

Responsibilities

Suggested contract interface (conceptual)

Tech

Upgrading

2. Frontend – `frontend/`

Responsibilities

Wallet support today

Tech

3. Backend – `backend/`

Responsibilities

Tech

Data Flow (High Level)

Tech Stack Summary

Development Milestones

Getting Started (After Initialization)

Documentation

Contract Development

Platform Governance & Operations

Development

License

Contact

Handsoff notes

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

MyFans – Decentralized Content Subscription Platform (Stellar)

Why Stellar

Problems MyFans Solves

Architecture Overview

Repository Structure

Getting Started

Documentation

1. Smart Contract (Soroban) – contract/

Responsibilities

Suggested contract interface (conceptual)

Tech

Upgrading

2. Frontend – frontend/

Responsibilities

Wallet support today

Tech

3. Backend – backend/

Responsibilities

Tech

Data Flow (High Level)

Tech Stack Summary

Development Milestones

Getting Started (After Initialization)

Documentation

Contract Development

Platform Governance & Operations

Development

License

Contact

Handsoff notes

About

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

1. Smart Contract (Soroban) – `contract/`

2. Frontend – `frontend/`

3. Backend – `backend/`