Skip to content

Milestone 5 — $QTRA Token Utility & Monetization — Integration Plan

Milestone: Phase 1, M5 (Week 5) Status: Planning

Scope Mapping

The M5 deliverables break into 4 workstreams. The staking system spec covers WS1 fully.

%%{init: {'theme':'base','themeVariables':{'background':'#ffffff','primaryColor':'#ddf4ff','primaryBorderColor':'#0969da','primaryTextColor':'#0a0a0a','lineColor':'#1f2328','secondaryColor':'#fff8c5','tertiaryColor':'#dafbe1','clusterBkg':'#f6f8fa','clusterBorder':'#d0d7de'}}}%%
graph TB
 subgraph WS1["WS1: Staking System (CLIENT SPEC PROVIDED)"]
 S1[StakingVault Contract<br/>Lock tiers, weights, safeguards]
 S2[RewardDistributor Contract<br/>Per-second accrual, claim vesting]
 S3[CircuitBreaker Contract<br/>6 automatic triggers]
 S4[Staking UI<br/>Live APY, tier selector, claim progress]
 end

 subgraph WS2["WS2: Buyback & Burn"]
 B1[BuybackEngine Contract<br/>Monthly profit → DEX buy → burn]
 B2[Revenue calculation logic]
 B3[On-chain burn auditability]
 end

 subgraph WS3["WS3: Fee Rebates & Discounts"]
 F1[Fee discount tiers<br/>Based on $QTRA staked amount]
 F2[Trading fee rebate integration<br/>Matching engine fee override]
 F3[Subscription discount<br/>Platform subscription pricing]
 end

 subgraph WS4["WS4: Revenue Router"]
 R1[RevenueRouter Contract<br/>50% subs + 20% fees + 20% profit → pool]
 R2[Off-chain revenue bridge<br/>Fiat/crypto revenue → on-chain USDC]
 R3[Treasury backstop<br/>$5M floor + $1.5M emergency]
 end

 R1 --> S2
 B1 --> S2
 F1 --> S1

 style WS1 fill:#ddf4ff
 style WS2 fill:#ddf4ff
 style WS3 fill:#ddf4ff
 style WS4 fill:#fff8c5

Smart Contract Architecture

%%{init: {'theme':'base','themeVariables':{'background':'#ffffff','primaryColor':'#ddf4ff','primaryBorderColor':'#0969da','primaryTextColor':'#0a0a0a','lineColor':'#1f2328','secondaryColor':'#fff8c5','tertiaryColor':'#dafbe1','clusterBkg':'#f6f8fa','clusterBorder':'#d0d7de'}}}%%
graph TB
 subgraph Core["Core Contracts"]
 TOKEN[$QTRA Token<br/>ERC20 + Burnable<br/>(from M2)]
 VAULT[StakingVault<br/>Lock / Unlock / Tiers<br/>Weights / Safeguards]
 REWARD[RewardDistributor<br/>Per-second accrual<br/>Claim vesting (7d stream)<br/>Auto-compound]
 end

 subgraph Revenue["Revenue Contracts"]
 ROUTER[RevenueRouter<br/>Split incoming revenue<br/>50% sub / 20% fees / 20% profit]
 BACKSTOP[TreasuryBackstop<br/>$5M annual floor<br/>$1.5M emergency USDC reserve]
 end

 subgraph Buyback["Buyback Contracts"]
 BUYBACK[BuybackEngine<br/>Monthly DEX purchase<br/>Auto-burn purchased tokens]
 end

 subgraph Protection["Protection Layer"]
 CIRCUIT[CircuitBreaker<br/>6 triggers: staked < 10M,<br/>stakers < 100, price crash,<br/>zero revenue, whale cap]
 ORACLE[Price Oracle<br/>Chainlink QTRA/USD<br/>or DEX TWAP]
 end

 subgraph External["External"]
 DEX[Uniswap/Aerodrome<br/>on Base]
 USDC[USDC Deposits<br/>from platform revenue]
 ADMIN[Revenue Admin<br/>Multisig deposits]
 end

 USDC -->|deposit| ROUTER
 ADMIN -->|deposit| ROUTER
 ROUTER -->|50%+20%+20%| REWARD
 ROUTER -->|remaining| BACKSTOP
 REWARD -->|claim| TOKEN
 VAULT -->|stake/unstake| TOKEN
 VAULT -->|weight lookup| REWARD
 CIRCUIT -->|pause/redirect| REWARD
 ORACLE -->|price feed| CIRCUIT
 ORACLE -->|price feed| BUYBACK
 BUYBACK -->|buy on DEX| DEX
 BUYBACK -->|burn| TOKEN

 style Core fill:#ddf4ff
 style Revenue fill:#ddf4ff
 style Buyback fill:#fff8c5
 style Protection fill:#ddf4ff

Detailed Specifications

WS1: Staking System (from client spec)

Contract: StakingVault.sol

// Key state
mapping(address => StakeInfo) public stakes;
uint256 public totalStaked;
uint256 public totalStakers;
uint256 public constant MIN_STAKED_THRESHOLD = 10_000_000e18; // 10M QTRA
uint256 public constant MIN_STAKER_COUNT = 100;
uint256 public constant MAX_WALLET_CAP_BPS = 200; // 2% per epoch
uint256 public constant MIN_STAKE_PER_WALLET = 1_000e18; // 1,000 QTRA

struct StakeInfo {
 uint256 amount;
 uint256 weightedAmount; // amount * tierMultiplier
 LockTier tier;
 uint256 lockStart;
 uint256 lockEnd;
 uint256 warmupEnd; // lockStart + 7 days
 bool active;
}

enum LockTier { SEVEN_DAYS, THIRTY_DAYS, NINETY_DAYS, SIX_MONTHS, ONE_YEAR }

// Tier weights (immutable, basis points)
// 10000 = 1.00x, 10500 = 1.05x, 12000 = 1.20x, 14000 = 1.40x, 16000 = 1.60x

Key functions: - stake(uint256 amount, LockTier tier) — lock tokens, 7-day warmup before earning - unstake() — after lock period expires, 3-day cooldown - earlyUnstake() — reverts to 7-day base rate weight retroactively - getEffectiveWeight(address user) — returns weighted staking power

Contract: RewardDistributor.sol

// Per-second reward accrual (Synthetix-style)
uint256 public rewardRate; // tokens per second
uint256 public rewardPerTokenStored;
uint256 public lastUpdateTime;
mapping(address => uint256) public userRewardPerTokenPaid;
mapping(address => uint256) public rewards;

// Claim vesting
struct ClaimStream {
 uint256 totalAmount;
 uint256 claimed;
 uint256 startTime;
 uint256 endTime; // startTime + 7 days
}
mapping(address => ClaimStream[]) public claimStreams;

Key functions: - earned(address user) — accrued rewards (continuous) - claimRewards() — starts 7-day vesting stream - autoCompound() — restakes rewards into same tier - collectVested() — withdraw vested portion of active streams - forfeitStream(uint256 streamId) — returns unvested to pool

WS2: Buyback & Burn

Contract: BuybackEngine.sol

uint256 public constant BUYBACK_PERCENTAGE = 1000; // 10% of net profit (BPS)
uint256 public constant CRISIS_BUYBACK_PERCENTAGE = 2000; // 20% during price crash
uint256 public constant CRISIS_DURATION = 30 days;

// Buyback execution
function executeBuyback(uint256 usdcAmount) external onlyAuthorized {
 // 1. Swap USDC → QTRA on DEX (Uniswap V3 / Aerodrome)
 // 2. Burn purchased QTRA tokens
 // 3. Emit BuybackExecuted event with amounts
}

Off-chain component (backend): - Monthly profit calculation from platform revenue - 10% of net profit allocated to buyback - Backend triggers executeBuyback() via multisig or automated keeper - All buyback txs logged for on-chain auditability

Burn mechanism: - Purchased tokens sent to QTRAToken.burn() (OpenZeppelin ERC20Burnable) - Burn events indexed by chain-indexer - Dashboard shows cumulative burned, remaining supply, deflation rate

WS3: Fee Rebates & Discounts

Trading Fee Rebates (integrated into matching engine):

$QTRA Staked Fee Discount
0 0% (standard fees)
10,000+ 5% discount
50,000+ 10% discount
100,000+ 15% discount
500,000+ 20% discount
1,000,000+ 25% discount

Implementation: - Matching engine queries staking balance via gRPC on order placement - Fee discount applied at trade settlement in ledger-service - Discount tiers configurable (stored in contract or platform config) - UI shows "Your fee tier" based on staked amount

Subscription Discounts:

Payment Method Discount
Pay in USDC 0% (standard)
Pay in $QTRA 10% discount
Pay in $QTRA + staking 100K+ 20% discount

Implementation: - Subscription service checks $QTRA balance and staking status - Discount applied at checkout - $QTRA payments route through RevenueRouter

WS4: Revenue Router

Contract: RevenueRouter.sol

uint256 public constant SUBSCRIPTION_SHARE = 5000; // 50% to staking pool
uint256 public constant EXCHANGE_FEE_SHARE = 2000; // 20% to staking pool
uint256 public constant TRADING_PROFIT_SHARE = 2000; // 20% to staking pool

enum RevenueType { SUBSCRIPTION, EXCHANGE_FEE, TRADING_PROFIT, OTHER }

function depositRevenue(uint256 amount, RevenueType revenueType) external onlyAuthorized {
 uint256 stakingShare = calculateShare(amount, revenueType);
 uint256 treasuryShare = amount - stakingShare;

 USDC.transfer(address(rewardDistributor), stakingShare);
 USDC.transfer(address(treasuryBackstop), treasuryShare);

 rewardDistributor.notifyRewardAmount(stakingShare);
}

Off-chain revenue bridge: - Platform revenue (fiat subscriptions, exchange fees, trading profit) is collected off-chain - Weekly batch: convert to USDC, deposit to RevenueRouter via multisig - RevenueRouter splits and routes automatically - All deposits logged with revenue type for auditability

TreasuryBackstop.sol: - Holds USDC reserve ($5M annual floor + $1.5M emergency) - If staking pool falls below $5M/year rate, backstop tops up automatically - Emergency reserve activates after 90 days zero revenue - Managed by multisig (cannot be drained by single party)

Implementation Timeline (Week 5)

%%{init: {'theme':'base','themeVariables':{'background':'#ffffff','primaryColor':'#ddf4ff','primaryBorderColor':'#0969da','primaryTextColor':'#0a0a0a','lineColor':'#1f2328','secondaryColor':'#fff8c5','tertiaryColor':'#dafbe1','clusterBkg':'#f6f8fa','clusterBorder':'#d0d7de'}}}%%
gantt
 title M5 — Token Utility & Monetization (Week 5)
 dateFormat YYYY-MM-DD
 axisFormat %a

 section Day 1-2: Staking Contracts
 StakingVault.sol :d1, 2026-05-05, 1d
 RewardDistributor.sol :d2, 2026-05-05, 2d
 CircuitBreaker.sol :d3, 2026-05-06, 1d

 section Day 2-3: Revenue & Buyback
 RevenueRouter.sol :d4, 2026-05-06, 1d
 TreasuryBackstop.sol :d5, 2026-05-06, 1d
 BuybackEngine.sol :d6, 2026-05-07, 1d

 section Day 3-4: Integration
 Fee rebate integration (matching engine) :d7, 2026-05-07, 1d
 Subscription discount logic :d8, 2026-05-07, 1d
 Backend revenue bridge :d9, 2026-05-08, 1d

 section Day 4-5: Testing & UI
 Contract tests (90%+ coverage) :d10, 2026-05-08, 1d
 Staking UI (live APY, tiers, claims) :d11, 2026-05-08, 2d
 Testnet deployment :d12, 2026-05-09, 1d
 End-to-end testing :d13, 2026-05-09, 1d

Acceptance Criteria (M5)

From original delivery plan + staking spec:

  • Staking and rewards functional (stake, unstake, claim, auto-compound)
  • Lock tiers enforce correct weights (1.00x → 1.60x)
  • All 6 safeguards enforced (min staked, min stakers, whale cap, dust prevention, floor, continuous accrual)
  • All 6 circuit breakers trigger correctly
  • 7-day claim vesting streams work (partial claim, forfeit)
  • Buyback and burn logic executes correctly
  • Revenue router splits correctly (50%/20%/20%)
  • Trading fee rebates applied based on staking amount
  • Subscription discounts work for $QTRA payments
  • On-chain auditability (all events indexed, burn tracking)
  • Token utilities applied correctly
  • Contract tests at 90%+ coverage
  • Deployed to Base Sepolia testnet

Open Questions for Client

  1. Epoch duration for 2% wallet cap — 7 days? 30 days?
  2. Revenue bridge frequency — weekly multisig deposits? Daily automated?
  3. Price oracle — Chainlink on Base? DEX TWAP? Custom?
  4. Early unstake penalty — just lose tier bonus, or also forfeit % of principal?
  5. Warmup period — does 90-day lock = 7d warmup + 90d, or 7d warmup + 83d?
  6. Buyback DEX — Uniswap V3 on Base? Aerodrome?
  7. Fee rebate tiers — are the proposed thresholds (10K/50K/100K/500K/1M) acceptable?
  8. Subscription discount — 10% for QTRA payment, 20% with staking — acceptable?