Technical Whitepaper | Feline Dynasty

01.

Executive Summary

Feline Dynasty is an idle breeding Play-to-Earn (P2E) game operating as a Telegram Mini App on the TON Blockchain. Players collect, breed, and evolve unique cat NFTs, each producing in-game currency passively. The game features a triple-token economy designed for long-term sustainability, a comprehensive DeFi center, guild-based territory wars, and PvP arena battles.

check_circle5 NFT rarity tiers with increasing production rates

check_circle20-level habitat progression with cosmetic rewards

check_circleMulti-tier DeFi staking with dynamic APY

check_circleMulti-level referral commission structure

check_circle14 languages supported natively

check_circleMulti-oracle pricing for reliable market data

check_circleAutomated + manual withdrawal with treasury protection

02.

Architecture Overview

Technical Stack

Layer	Technology
Frontend	React + TypeScript, Tailwind CSS, Shadcn UI
Backend	Express.js + TypeScript (Cloudflare Functions)
Database	PostgreSQL (Neon) with Drizzle ORM
Blockchain	TON (The Open Network)
Hosting	Cloudflare Pages + Functions + KV
Connection Pooling	Cloudflare Hyperdrive
Wallet Integration	TON Connect with cryptographic proof verification
Real-time	WebSocket with polling fallback

Infrastructure

The system is deployed on Cloudflare's global edge network, ensuring low latency worldwide. The database uses Neon's serverless PostgreSQL with connection pooling through Cloudflare Hyperdrive for optimal performance under load. Smart contracts are deployed on the TON blockchain using FunC, handling deposit/withdrawal operations with multi-signature security.

03.

Triple-Token Economy

The Feline Dynasty ecosystem utilizes a sophisticated three-token architecture designed to maintain equilibrium between inflationary utility and deflationary governance.

bolt

EF

Essenza Felina: Passive cat production, upgrades, in-game purchases.

Utility Token

token

FTON

Feline Token: Cat purchases, marketplace, premium features.

Premium Token

workspace_premium

FGOLD

Feline Gold: Staking, withdrawal to TON, premium operations.

Withdrawable

// Token Flow Cat Production --> EF (passive hourly) | v EF Conversion --> FTON + FGOLD | | v v Marketplace Withdrawal (TON) Cosmetics Staking Upgrades Burning

Treasury-Responsive FGOLD Rate

The EF→FGOLD conversion rate is treasury-responsive: it grows as the global treasury grows, rewarding players proportionally as the protocol becomes more sustainable. Seven public tiers (T0 to T6) govern the conversion ratio. The active tier is recalculated on a fixed cadence and announced in-game.

Tier	Treasury Range (USD)	FGOLD per 100 EF
T0	< $5,000	0.08
T1	$5,000 – $25,000	0.10
T2	$25,000 – $75,000	0.11
T3	$75,000 – $200,000	0.13
T4	$200,000 – $500,000	0.15
T5	$500,000 – $1,500,000	0.17
T6	> $1,500,000	0.18

Why tiered? A static rate would either drain a young treasury or under-reward a mature one. Tiered rates align player earnings with protocol health: as the community grows, payouts grow with it. The current active tier is always visible inside the game.

Fee Structure

Net_Revenue = Σ(Transaction_i * Fee_Rate_i) for i ∈ {deposits, withdrawals, marketplace, auctions, breeding, fusion} // Token Equilibrium condition: Total_Sinks ≥ Total_Emissions * (1 + Safety_Margin)

Active Fee Rates

Operation	Rate	Notes
TON Deposit	5%	4% founder batch + 1% relayer (on-chain)
USDT Deposit	4%	Via STON.fi swap USDT → TON (founder only)
Withdrawal FGOLD	3%	$0.10 USD per FGOLD, dynamic cap 200–400%
Marketplace Sale	5%	Taken from seller on successful trade
Marketplace Listing	2%	FTON burned at listing creation
Auction	7.5%	On settlement of winning bid

USDT Deposit via STON.fi (v2.15.0)

A two-popup in-wallet flow: the user's USDT Jetton is swapped on STON.fi to native TON, which is then forwarded to Treasury V4.4. Treasury V4.4 does not accept Jetton transfer_notification directly (exit 105 would lock funds). Slippage tolerance is ±3%.

Rate: 1 USDT → 10 FTON (gross) → 9.6 FTON (net, 4% fee) Slippage: ±3% (verify-swap.ts enforces 0.97×/1.03× band) Integrated in: TON tab (shop), Legendary modal, Mythic modal, Guild treasury // Cosmetics and Mystery Box are FTON/TON native only

04.

NFT Cat System

Rarity Tiers & Per-User Caps

Rarity	Cat Type	Max / User	Description
Common	Kitten	40	Entry-level, accessible to all players
Uncommon	Hunter	25	Enhanced production, breeding potential
Rare	Guardian	15	Significant output, genetic diversity
Epic	Emperor	10	High-value producer, rare genetics
Legendary	Divine	7	Maximum production, premium genetics (225 EF/hr, $500 TON-only)
Mythic	Mythic	3	Apex tier — 680 EF/hr, $1,600 TON-only, hard cap 3 per user

CAT_RARITY_CAP enforcement (v2.15.2): all 13 acquisition paths (shop, breeding, fusion, roulette, mystery boxes, marketplace, auctions, compensations, etc.) re-check the per-user cap through a centralized checkCatRarityCap() helper with ?? 0 fail-closed on unknown rarities.

Promotional Bundles

Two permanent bundles in the Mystery Box tab give new and experienced players a head-start. Both accept TON and USDT.

Starter Bundle

$187

1 Uncommon (Hunter) + 1 Rare (Guardian) + 1 Epic (Emperor). Each rarity is checked against the per-user cap before delivery.

Double Legendary

$900

2 Legendary cats in one purchase. Requires two free Legendary slots under the cap of 7 per user. Saves vs single-purchase price ($1,000).

Production Formula

P_eff(cat) = R_base(rarity) * M_habitat(level) * (1 + B_genetics) * (1 + B_achievement) * A_ability where: R_base = base production rate (tier-specific constant, EF/h) M_habitat = habitat multiplier function, M: [1..20] → [1.0, M_max] B_genetics = Σ(trait_bonus_i) for i ∈ {eye, fur, body, ear, tail, pattern} B_achievement = Σ(milestone_bonus_j) for completed achievements j A_ability = special ability multiplier ≥ 1.0

Accumulation System

Cap(level) = C_base + (level * C_increment) Overflow_Zone = Cap * κ, where κ > 1 Production_Rate = { P_eff if accumulated < Cap P_eff * δ if Cap ≤ accumulated < Overflow_Zone (δ < 1) 0 if accumulated ≥ Overflow_Zone }

05.

Habitat Evolution

The habitat is a 20-level progression system that directly impacts EF production and accumulation capacity. Levels span from "Basic Shelter" (L1, 600 EF cap) to "Genesis" (L20, 32,000 EF cap), with L10 at +215% production bonus and L20 at +335%. Fatigue: max 5 claim cycles per day per cat.

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

MAX

Base Tier (Novice) Imperial Tier (Grandmaster)

Habitat Multiplier Growth

M_habitat(n) = 1 + Σ(Δ_i) for i = 2..n where Δ_i follows a diminishing returns curve: Δ_i = Δ_base * (1 - e^(-λ*i)) / i^γ Upgrade_Cost(n) = C_1 * n^β * e^(μ*n) // exponential-polynomial hybrid ensuring late-game scarcity

Endgame Cosmetic Rewards (Levels 11-20)

BadgesProfile display

AurasVisual effects

FramesProfile frames

BackgroundsHabitat decor

PedestalsCat display

06.

Breeding & Genetics

Offspring Rarity Determination

R_offspring = floor((R_parent1 + R_parent2) / 2) + Mutation(p) where Mutation(p) = { +1 with probability p_mutation 0 with probability (1 - p_mutation) } p_mutation = p_base + (generation * Δ_gen)

Allele Inheritance Model

The game implements a Mendelian inheritance model with 7 trait categories: Eye Color, Fur Pattern, Fur Color, Body Shape, Ear Type, Tail Type, and Special Ability.

For each trait T: Allele_pool = {P1_dom(w₁), P1_rec(w₂), P2_dom(w₃), P2_rec(w₄)} where w₁ + w₂ + w₃ + w₄ = 1.0 Selected_allele = weighted_random(Allele_pool) if random() < p_mutation(generation): Selected_allele = mutate(Selected_allele, direction)

Genetic Production Bonuses

B_genetics_total = Σ(TRAIT_BONUS[rarity(trait_i)]) for i ∈ all_traits P_final = P_base * (1 + B_genetics_total) * ABILITY_MULTIPLIER[ability_type]

07.

Fusion Lab

The Fusion Lab allows players to combine multiple cats of identical type and rarity to create a higher-rarity cat.

P(success) = P_base * Quality_Factor(input_cats) On Success: Output = Cat(rarity + 1, random_genetics(rarity + 1)) On Failure: Lost = N - 1 cats Survivor receives permanent +σ% production bonus

Rarity Progression

Common → Uncommon → Rare → Epic → Legendary

08.

Cat Synth Lab

The Synth Lab is a guild-collaborative crafting system for advanced cat modifications.

speed

Production Enhancement

Boost cat output

auto_awesome

Rarity Enhancement

Chance to upgrade rarity

genetics

Trait Fusion

Combine best genetic traits

09.

DeFi Center

Staking

Mining

Lending

Dynamic APY Staking

APY_actual(tier, t) = APY_base(tier) * H(t) where H(t) = Treasury Health Multiplier: H(t) = { 1.0 if Reserve_Ratio > θ_healthy (Reserve_Ratio - θ_critical) / (θ_healthy - θ_critical) if θ_critical < Reserve_Ratio ≤ θ_healthy H_min if Reserve_Ratio ≤ θ_critical } Safety Constraint: TVL_staking ≤ τ_hard * Treasury_Total

Staking APY range: 5–18% depending on tier and lock duration. Longer commitments and rarer collateral classes earn higher base APY, scaled in real-time by the treasury-health multiplier H(t).

Early exit penalty (v2.15.1): a flat 10% penalty applies to every staking tier on early withdrawal — replacing the prior 50% misconfiguration. Atomic double-fence pattern: FOR UPDATE NOWAIT + UPDATE ... WHERE balance ≥ amount RETURNING id.

Mining (Emission Control)

EF_daily(user) = FTON_committed * R_base * M_lock(duration) Global Emission Cap: Σ(EF_daily(all_miners)) ≤ Total_EF_Supply * ε_daily Per-User Cap: active_mining_positions ≤ 3

NFT Lending

Collateral Rarity	Loan (FTON)	Interest	Term
Common	20	10% flat	15 days
Uncommon	40	10% flat	15 days
Rare	120	10% flat	15 days
Epic	300	10% flat	15 days
Legendary	1,000	10% flat	15 days

Loan_Amount(cat) = RARITY_LOAN_AMOUNTS[rarity] // fixed per tier Interest = Principal * 0.10 // 10% flat Term = 15 days Liquidation triggered if: - Loan term expires without repayment → NFT transferred to lending pool

10.

Arena PvP System

ELO Rating System

R_new = R_current + K * (S - E) where: K = adjustment constant (asymmetric: K_win > K_loss) S = actual outcome (1 = win, 0 = loss) E = expected outcome = 1 / (1 + 10^((R_opponent - R_current) / 400)) Matchmaking constraint: |R_player - R_opponent| ≤ Δ_max

Battle Rewards & Equipment

Equipment_Drop = Bernoulli(p_drop) Rarity_Distribution = Categorical(p_common, p_uncommon, p_rare, p_epic, p_legendary) where Σ(p_i) = 1.0 and p_i decreases with rarity Stat_Bonus(slot, rarity) = f(fighter_level, rarity_tier) for slot ∈ {weapon, armor, helmet, accessory}

11.

Guild System & Wars

Territory Conquest

Territory_Value(t) = Base_Bonus * Decay_Function(t) Decay_Function(t) = { 1.0 if t_inactive ≤ T_grace max(D_min, 1.0 - ρ * (t_inactive - T_grace)) if t_inactive > T_grace } Attack_Power = Σ(EF_contributed_by_members) / η

Dual Treasury Architecture

Treasury	Purpose
Game Treasury	Player deposits/withdrawals
Guild Treasury	Guild operations, war funding

12.

Engagement Systems

casino

Daily Roulette

Weighted prize wheel with tokens and rare cats

local_fire_department

Daily Streak

Consecutive login rewards with escalating bonuses

inventory_2

Treasure Hunt

30-day progressive reward cycle

task_alt

Mission System

Social and partner missions for community engagement

military_tech

Achievements

Milestone-based permanent EF production boosts

emoji_events

Competitions

Periodic leaderboard events with FGOLD prize pools

stadia_controller

Arcade Felino (BETA)

Three mini-games — Feline Wheel, Cat vs Mouse, Prize Piggy Bank — powered by Paw Tokens as the in-arcade currency. The Piggy Bank unlocks permanent account bonuses (extra accumulation capacity, breeding/fusion discounts, fatigue bonus claims, streak shields). Server-side RNG with full audit trail (arcade_plays with UNIQUE idempotency keys).

deceased

Cemetery & Resurrection

Cats have a lifespan (common–mythic 12 months, celestiale 15). At end of life they enter the dynasty Cemetery instead of vanishing: sacrifice the fallen to resurrect a higher-rarity cat that inherits the lineage. Includes Zombie mode and a Hall of Fame — the dynasty never truly dies.

casino

Weekly Jackpot

On-chain weekly draw every Sunday at 20:00 UTC. Entry: 1 DYNA per ticket (max 5). 1st prize: 1% of the accumulated EF pool; 2nd prize: 10% of the DYNA pool. Weighted transparent RNG, rollover below 10 participants.

smart_toy

Felix AI Support

In-app support engine: hybrid RAG (BM25 + pgvector) × quality_score + gpt-4o-mini, 450+ KB entries, cross-session memory 72h, dynamic few-shot prompting, integrated compensation claim flow in 14 languages. Current quality score 10/10.

13.

Marketplace & Auctions

P2P Marketplace

Direct cat trading between players with platform fees on sales. Prices set by sellers in FTON.

Auction System

Time-limited bidding with minimum bid increments. Anti-wash-trading detection prevents market manipulation through behavioral analysis.

14.

Referral Program

Four-Tier Customer Chain (v2.14.14)

Referral rewards cascade through four levels of the dynasty tree. As of v2.14.14 the structure was simplified from 5 tiers / 15% to 4 tiers / 12% total to preserve long-term treasury health while keeping strong first-line incentives.

Level	Commission
L1 (direct)	7%
L2	3%
L3	1%
L4	1%
Total	12%

Anti-abuse protections include:

shieldCircular referral loop detection
shieldSelf-farming prevention via device analysis
shieldMinimum distribution thresholds
shieldDynamic withdrawal cap 200–400% scaled by active L1 referrals

person

7%

3%

1%

15.

Treasury & Blockchain

contract

Smart Contracts

FunC on TON mainnet with multi-signature security

monitoring

Multi-Oracle Pricing

5-oracle cascade for reliable TON/USD pricing

account_balance_wallet

USDT Deposits

Native TON + USDT Jetton transfers supported

swap_vert

Withdrawal System

Automated below threshold, manual approval for larger amounts. Lifetime cap relative to deposits.

shield

Treasury Protection

Absolute floor mechanism blocks all withdrawals below critical reserve threshold.

16.

Security Architecture

Audited Security Score

10/10— 46 findings closed across 5 Sprints (Sprint 5 completed 2026-04-21)

Financial Rate Limit

10 req/min/user

Authentication Layers

01

Telegram initData Validation

Cryptographic verification with expiry protection

02

Session Tokens

Signed tokens with timing-safe comparison

03

Wallet Proof Verification

Cryptographic signature validation of wallet ownership

Anti-Abuse System

Detection	Method
Multi-Account	Device fingerprinting + behavioral analysis
Bot Detection	Timing pattern analysis, speed anomaly
Wash Trading	Buyer/seller correlation analysis
Referral Abuse	Loop detection, self-farming prevention
Exploit Detection	Rate anomaly detection on economic ops

Financial Safety Patterns

// Atomic double-fence for all withdrawals / stakes / burns BEGIN; SELECT ... FROM users WHERE id = $1 FOR UPDATE NOWAIT; UPDATE users SET balance = balance - $amount WHERE id = $1 AND balance >= $amount RETURNING id; // empty RETURNING => concurrent contention => 409 COMMIT; // Retry wrapper for high-contention endpoints (claim, claim-all) withDbTransactionRetry(env, fn, maxRetries = 2) // backoff: 25ms * 2^attempt + jitter; retries 55P03 / 40001 / 40P01 // Signature comparison is always constant-time XOR loop (never ===)

17.

Economic Sustainability

Inflation Control

dS/dt = Emissions(t) - Sinks(t) - Burns(t) where: Emissions(t) = Mining_Output(t) + Staking_Rewards(t) + Game_Rewards(t) Sinks(t) = Σ(Fee_i * Volume_i) for all fee-bearing operations Burns(t) = Breeding_Burns + Fusion_Burns + Synth_Burns + Cosmetic_Burns // Stability condition: dS/dt ≤ 0 (net deflationary or neutral)

Growth Zone

Supply emission exceeds burn. Permitted during early phases to establish player base.

Imperial Zone

Perfect equilibrium (1:1 burn-to-mint ratio). Our primary long-term target.

Scarcity Zone

Hyper-deflationary pressure. Triggered when circulating supply exceeds protocol caps.

Treasury Health System

H(t) = Treasury_Balance(t) / Total_Liability(t) Adaptive Response Function: APY_multiplier = g₁(H) ∈ [H_min_mult, 1.0] Emission_rate = g₂(H) ∈ [ε_min, ε_max] Fee_multiplier = g₃(H) ∈ [1.0, F_max] Withdrawal_speed = g₄(H) ∈ [0, W_max_daily] Emergency Protocol: if H(t) < θ_floor: Withdrawal_speed = 0 // absolute floor protection

18.

Roadmap

Recent Changelog

Version	Highlights
v2.17.x	Treasury-responsive FGOLD rate (7 tiers T0–T6), Starter Bundle ($187) + Double Legendary ($900) permanent bundles, EF burn fallback for ad failures, admin web dashboard
v2.15.2	CAT_RARITY_CAP (40/25/15/10/7/3), achievements overhaul (mythic_monster, legendary_monster removed), staking penalty fix, IDOR/TOCTOU hardening
v2.15.0	USDT deposit via STON.fi swap (2-popup flow), ±3% slippage, jetton-safe Treasury path
v2.14.14	Referral system restructured: 5 levels / 15% → 4 levels / 12%
v2.14.x	Felix AI (hybrid RAG BM25+pgvector, 450+ KB, 10/10), Compensation system, Mythic cat, DeFi full launch, cap 200–400% dynamic
v2.13.x	DeFi Center launch (Staking, Mining, Lending)
v2.12.x	Arcade Felino beta, 20-level Habitat capacity expansion

Development Phases

PHASE 1 Launch & Core COMPLETED

Triple-Token Economy, NFT Cats, 20-Level Habitat, Breeding + Fusion + Genetics, DeFi Center, Arena PvP, Marketplace, 14 Languages

PHASE 2 Growth COMPLETED

Advanced Security, Cosmetics Shop, Achievement System, Landing Page, Daily Streak & Treasure Hunt

PHASE 3 Expansion IN PROGRESS

Guild Wars & Territory Control, NFT On-Chain Minting, Competition System, Cat Synth Lab (Done), Partner Games

PHASE 4 Dynasty Universe FUTURE

2D PC Adventure Game, Cross-Platform Sync, Multi-Level World with NPCs, NFT Cats as companions

19.

Conclusion

Feline Dynasty represents a new paradigm in blockchain gaming: a sustainable, community-driven economy built on the TON blockchain. Through its triple-token model, dynamic treasury management, and multi-layered security architecture, the project is designed for long-term viability rather than short-term speculation.

01Triple-token separation prevents single-point economic failure

02Dynamic economic controls adapt to market conditions in real-time

03Multi-oracle pricing eliminates manipulation risks

04Production-grade security with cryptographic verification at every layer

0514-language support for true global accessibility

Disclaimer: This whitepaper is for informational purposes only. It does not constitute financial advice. Token values and game mechanics are subject to change based on economic conditions and development priorities. Always do your own research before participating in any blockchain-based project.

WHITE PAPER