# TBURN On-Chain Referral System v2.0
> Enterprise-grade, fully on-chain referral protocol built natively on TBurnChain — an independent Layer 1 blockchain (Chain ID: 5800) and its Layer 2 sidechain (Chain ID: 58001). No ERC standards. No EIP compliance. TBC Protocol Standards only.

TBURN Referral System v2.0 is a decentralized, blockchain-native referral platform where every referral relationship, reward distribution, and tier upgrade is recorded immutably on-chain via smart contracts. The system is powered by Soulbound Token (SBT) verification, BFT consensus with 125 validators, and a Federation Gateway API with 87 authenticated endpoints.

## Platform Identity

- **Product Name**: TBURN On-Chain Referral System v2.0
- **Canonical URL**: https://referral.tburn.io/
- **Operator**: TBURN Federation
- **Blockchain**: TBurnChain (independent Layer 1, NOT Ethereum)
- **L1 Chain ID**: 5800
- **L2 Chain ID**: 58001
- **Protocol Standard**: TBC-REF v2 (TBurnChain-native, no ERC/EIP)
- **Consensus**: Byzantine Fault Tolerant (BFT), 125 validators, 11-node quorum
- **L1 TPS Capacity**: 87,420 transactions per second
- **Block Time**: ~500ms
- **API**: Federation Gateway API — 87 HMAC-SHA256 authenticated endpoints
- **Languages Supported**: English, Korean, Chinese, Japanese, Arabic, Spanish, French, German, Russian, Portuguese, Vietnamese, Turkish

## How the Referral Protocol Works

The TBURN referral protocol implements a 3-hop referral tree (TBC-REF v2 standard):

1. **Referrer (Hop 1)**: The direct inviter earns 5% of every transaction fee generated by their direct referral, on-chain, in real time.
2. **Grandparent (Hop 2)**: The referrer's inviter earns 2% of the same transaction fees — passively and automatically.
3. **Great-grandparent (Hop 3)**: Earns 1% of transaction fees, also automatic and on-chain.

All referral relationships are anchored to wallet addresses and verified via TBC-SBT (Soulbound Token) on the ReferralRegistry smart contract. Referral chains are immutable once committed.

## Reward Types

### One-Time Onboarding Rewards
| Action | Reward | Distribution |
|---|---|---|
| Register a new referral | 5 TBURN | At TGE |
| Complete KYC verification | 3 TBURN | Immediately |
| First on-chain trade | 2 TBURN | Immediately |
| Daily check-in (7-day streak) | 5 TBURN | Immediately |
| Provide first liquidity (LP) | 10 TBURN | Immediately |

### Perpetual Fee-Share Rewards (on-chain, real-time)
| Referral Depth | Share Rate | Distribution |
|---|---|---|
| Direct (L1) | 5% of TX fee | Per transaction |
| L2 (grandparent) | 2% of TX fee | Per transaction |
| L3 (great-grandparent) | 1% of TX fee | Per transaction |

## Tier System (5 Tiers)

Tiers unlock reward multipliers and exclusive privileges. Tier upgrades are triggered by on-chain milestones.

| Tier | Name | Multiplier | Direct Reward | Milestone Bonus |
|---|---|---|---|---|
| Tier 1 | Bronze | 1.0× | 5T | — |
| Tier 2 | Silver | 1.2× | 6T | +50T |
| Tier 3 | Gold | 1.5× | 7.5T | +300T |
| Tier 4 | Diamond | 2.0× | 10T | +1,000T |
| Tier 5 | Legend | 3.0× | 15T | +5,000T |

### Tier Unlock Requirements

| Tier | Referrals Needed | Additional Requirements |
|---|---|---|
| Bronze (Tier 0→1) | 10 referrals | Account verification complete |
| Silver (Tier 1→2) | 50 referrals | At least 1 on-chain TX |
| Gold (Tier 2→3) | 100 referrals | KYC level 2 complete |
| Diamond (Tier 3→4) | 500 referrals | Wallet bound on-chain |
| Legend (Tier 4→5) | 1,000 referrals | TBURN governance participation |

## SBT Achievement Badges (7 Badges)

Soulbound Token badges are non-transferable, on-chain credentials minted to users' wallets upon milestone completion.

| Badge | Name | Condition | Bonus |
|---|---|---|---|
| First Referral | Pioneer | Complete first referral | Early bird bonus |
| Speed Referrer | Velocity | 5 referrals within 7 days | Speed bonus |
| Hot Streak | Inferno | 3 referrals in 24 hours | Streak bonus |
| Global Connector | Ambassador | Referrals in 3+ countries | Global bonus |
| Century Club | Centurion | 100 total referrals | +1,000T bonus |
| TGE Pioneer | Genesis | Active before Token Generation Event | Pioneer allocation |
| Legend Badge | Apex | Reach Legend tier | VIP status + governance weight |

## Vesting Schedules

| Reward Type | TGE Unlock | Cliff | Vesting Period |
|---|---|---|---|
| Daily check-in | 100% | None | Immediate |
| Direct referral bonus | 30% | None | 12 months linear |
| Milestone bonus | 50% | None | 6 months linear |
| LP rewards | 50% | None | 6 months linear |
| Tier upgrade bonus | 0% | 30 days | 3 months linear |
| Legend tier rewards | 0% | 60 days | 6 months linear |

## Technical Architecture

- **Smart Contracts**: ReferralRegistry, TBURNSoulBound (SBT minting), RewardVault (distribution)
- **On-Chain Finality**: BFT consensus — transactions finalize in ~500ms
- **Cross-Chain**: L1 ↔ L2 native bridge with HMAC-SHA256 authenticated relay
- **API Auth**: HMAC-SHA256 Server-to-Server authentication with timestamp validation and nonce deduplication
- **WebSocket**: Real-time event streaming (burn-events, referral-events, sbt-events, reward-events, consensus, network_stats)
- **Security**: 4-tier rate limiting, CSRF protection, 8 security headers (CSP, X-Frame-Options DENY, COEP, CORP), IDOR protection at storage layer

## Smart Contract Reference

### ReferralRegistry (L2 Chain ID: 58001)
- **Function**: `registerReferral(address referrer, address referee, address grandparent, address greatGrandparent, address relayer)`
- **Selector**: `0xf533f0d0`
- **Gas Limit**: 200,000 units
- **Gas Price**: 10 EMB (native L2 gas token)
- **Finality**: ~500ms BFT consensus
- **Purpose**: Immutable on-chain binding of referral relationships across 3 hops

### TBURNSoulBound (SBT Contract, L1 Chain ID: 5800)
- **Standard**: TBC-SBT (non-transferable token, TBurnChain native)
- **Function**: `mintBadge(address wallet, uint256 badgeId, bytes32 metadata)`
- **Purpose**: Non-transferable achievement badges minted upon milestone completion
- **Badge IDs**: 1=Pioneer, 2=Velocity, 3=Inferno, 4=Ambassador, 5=Centurion, 6=Genesis, 7=Apex

### RewardVault (L1 Chain ID: 5800)
- **Purpose**: Holds and distributes all TBURN referral rewards
- **Distribution**: Automatic vesting schedule enforcement on-chain
- **Withdrawal**: Triggered at TGE or upon reaching vesting cliff

## API Reference (Federation Gateway)

All API endpoints are REST-based. Server-to-server endpoints use HMAC-SHA256 authentication. User-facing endpoints use session cookies (HttpOnly, Secure, SameSite=Strict).

### Authentication Endpoints
- `POST /api/auth/register` — Register new account with optional referral code
- `POST /api/auth/login` — Authenticate and receive session cookie
- `POST /api/auth/logout` — Invalidate session
- `GET /api/auth/me` — Get authenticated user profile (sanitized, no password hash)

### Referral Endpoints
- `GET /api/referral/my-code` — Get or create personal referral code
- `POST /api/referral/register` — Register referral via code
- `GET /api/referral/tree` — Fetch full 3-hop referral tree for authenticated user
- `GET /api/referral/stats` — Aggregated referral statistics (count, earnings, tier)
- `GET /api/referral/leaderboard` — Global top referrers by count, reward, tier

### Reward Endpoints
- `GET /api/rewards/history` — Paginated list of all reward events for user
- `GET /api/rewards/pending` — Pending rewards awaiting TGE or vesting cliff
- `GET /api/rewards/summary` — Total earned, total pending, total distributed
- `POST /api/rewards/claim` — Trigger manual claim for unlocked rewards

### Analytics Endpoints
- `GET /api/analytics/dashboard` — User-level dashboard metrics
- `GET /api/analytics/advanced/:userId` — Advanced analytics (owner or admin only, IDOR-protected)
- `GET /api/analytics/network` — Network-wide statistics (public)

### On-Chain Endpoints
- `GET /api/onchain/registration/:userId` — Check on-chain registration status
- `GET /api/onchain/tx/:txHash` — Verify transaction receipt on L2
- `GET /api/onchain/sbt/:wallet` — Check SBT badges for a wallet address
- `POST /api/onchain/bind-wallet` — Bind TBurnChain wallet to user account (requires signature)

### Admin Endpoints (role=admin required)
- `GET /api/admin/users` — List all users with pagination
- `PATCH /api/admin/users/:id` — Update user role or status
- `GET /api/admin/metrics` — System health, queue depth, relayer status
- `GET /api/admin/pending-registrations` — View queued L2 registration transactions
- `POST /api/admin/retry-registration/:id` — Retry failed L2 registration

### Airdrop Endpoints
- `GET /api/airdrop/active` — List active airdrop campaigns
- `POST /api/airdrop/:id/claim` — Claim airdrop (eligibility checked server-side)
- `GET /api/airdrop/my-claims` — History of user's airdrop claims

### WebSocket Events
Connect to `wss://referral.tburn.io/ws` for real-time updates.

| Event Type | Description |
|---|---|
| `referral-registered` | New referral confirmed on-chain |
| `reward-distributed` | Reward credited to user account |
| `tier-upgraded` | User tier advanced to next level |
| `sbt-minted` | New SBT badge minted to wallet |
| `burn-event` | TBURN token burn recorded on L1 |
| `network_stats` | L1/L2 network statistics update |
| `consensus` | BFT consensus round completed |

## Security Architecture

### Rate Limiting (4-Tier)
- **Auth tier**: 10 requests/15 min per IP (login, register)
- **API tier**: 100 requests/15 min per IP (general API)
- **Financial tier**: 20 requests/hour per user (claims, withdrawals)
- **Admin tier**: 50 requests/15 min (admin panel)
- **Strict tier**: 5 requests/15 min (sensitive operations)

### HTTP Security Headers
- `Content-Security-Policy`: Script-src self, inline scripts blocked
- `X-Frame-Options`: DENY (clickjacking prevention)
- `Cross-Origin-Embedder-Policy`: require-corp
- `Cross-Origin-Resource-Policy`: same-origin
- `X-Content-Type-Options`: nosniff
- `Referrer-Policy`: strict-origin-when-cross-origin
- `Permissions-Policy`: camera=(), microphone=(), geolocation=()
- `Strict-Transport-Security`: max-age=31536000; includeSubDomains

### CSRF Protection
All state-changing requests validate Origin/Referer headers against allowed domains (tburn.io, referral.tburn.io). Session cookies are SameSite=Strict.

### IDOR Prevention
Advanced analytics endpoints verify request user ID matches authenticated session user ID (or admin role) before returning data.

### Self-Referral Prevention
The system blocks circular referral relationships. A user cannot use their own referral code or the referral code of any account they control. Sybil score system tracks suspicious referral patterns.

### Sybil Resistance
Each user has a dynamic Sybil Score (0.0–1.0) computed from:
- IP diversity of referrals
- Device fingerprint clustering
- Referral velocity patterns
- On-chain wallet age and activity

High sybil scores reduce reward multipliers and flag accounts for manual review.

## Reward Earnings Calculator (Examples)

| Referrals | Estimated Reward |
|---|---|
| 10 direct referrals | ~250 TBURN |
| 50 direct referrals | ~1,550 TBURN |
| 100 direct referrals | ~4,100 TBURN |
| 500 referrals (Diamond) | ~25,000 TBURN |
| 1,000 referrals (Legend) | ~60,000+ TBURN |

Actual rewards depend on: tier multiplier, vesting factor (account age), sybil penalty, network conditions, and TGE distribution allocation.

## Frequently Asked Questions

**Q: Is TBURN Referral on Ethereum?**
A: No. TBURN runs on TBurnChain, a completely independent Layer 1 blockchain (Chain ID: 5800). It uses TBC Protocol Standards, not ERC or EIP.

**Q: How are referral relationships verified?**
A: Via on-chain wallet address binding recorded on the ReferralRegistry smart contract, further secured by Soulbound Token (SBT) minting on the TBURNSoulBound contract.

**Q: When are rewards distributed?**
A: Fee-share rewards are distributed per transaction in real time. Onboarding rewards follow vesting schedules (some immediately at TGE, others with cliff periods).

**Q: Is KYC required?**
A: KYC is required to unlock full reward withdrawal and higher-tier features. The KYC flow is managed in-platform.

**Q: What wallets are supported?**
A: Any EVM-compatible wallet configured for TBurnChain (Chain ID: 5800) is supported. MetaMask, Trust Wallet, and hardware wallets with custom RPC configuration are compatible.

**Q: Can I see my referral tree?**
A: Yes. The dashboard shows your full 3-hop referral tree in real time, including tier status, pending rewards, and on-chain confirmation status.

**Q: What is a Soulbound Token (SBT)?**
A: An SBT is a non-transferable blockchain token (TBC-SBT standard) that permanently records achievement milestones. Unlike regular tokens, SBTs cannot be sold or transferred — they represent your verified on-chain identity and accomplishments.

**Q: How long do referral rewards vest?**
A: It depends on the reward type. Direct referral bonuses vest over 12 months with 30% unlocked at TGE. Milestone bonuses vest over 6 months with 50% at TGE. See the vesting schedule table above for full details.

**Q: Can referral chains be modified after registration?**
A: No. Once recorded on the ReferralRegistry smart contract, referral relationships are immutable and cannot be changed or deleted.

**Q: How does the L2 registration process work?**
A: After account creation, a background relayer service submits a `registerReferral` transaction to the L2 chain (Chain ID 58001). The transaction is confirmed in ~500ms via BFT consensus. Status is tracked in real time on the dashboard.

**Q: What is the Federation Gateway API?**
A: A secure, centralized API layer that interfaces with TBurnChain L1 and L2. All endpoints use HMAC-SHA256 request signing for server-to-server communication. User endpoints use session-based authentication.

**Q: Are there any fees to participate?**
A: No fees to register or participate in the referral program. Gas fees for L2 smart contract registration are covered by the TBURN Federation relayer.

## Important Disclaimers

- TBURN tokens ("T" or "TBURN") are utility tokens on the TBurnChain network. This is NOT an investment product.
- Referral rewards are subject to vesting schedules and network conditions.
- The platform operates under CONFIDENTIAL pre-launch status. No ERC. No EIP. TBC Protocol Standards Only.
- Smart contract addresses are published at TGE.
- Estimated reward figures are illustrative and do not constitute financial guarantees.

## Key Links

- [Home / Landing Page](https://referral.tburn.io/)
- [Register / Join](https://referral.tburn.io/register)
- [Sign In](https://referral.tburn.io/login)
- [Dashboard](https://referral.tburn.io/dashboard)
- [How It Works](https://referral.tburn.io/#how-it-works)
- [Tier System](https://referral.tburn.io/#tiers)
- [Reward Structure](https://referral.tburn.io/#rewards)
- [Earnings Calculator](https://referral.tburn.io/#calculator)
- [Security Overview](https://referral.tburn.io/#security)
- [AI Plugin Manifest](https://referral.tburn.io/ai-plugin.json)
- [OpenAPI Spec](https://referral.tburn.io/.well-known/openapi.json)
- [LLMs.txt (full)](https://referral.tburn.io/.well-known/llms.txt)

## Structured Data & Discovery

- [Sitemap](https://referral.tburn.io/sitemap.xml)
- [Robots](https://referral.tburn.io/robots.txt)
- [LLMs Discovery](https://referral.tburn.io/llms.txt)
- [OpenAPI Spec](https://referral.tburn.io/.well-known/openapi.json)
- [AI Plugin JSON](https://referral.tburn.io/ai-plugin.json)

This document is designed for AI language model consumption, search engine indexing, and developer reference. It is maintained as part of the TBURN platform's AI-first SEO strategy.