Skip to main content

Skyhitz Documentation

Welcome to the Skyhitz technical documentation. Skyhitz is a decentralized music platform powered by the Stellar blockchain, featuring a dual-contract system with the HITZ token and sustainable tokenomics.

What is Skyhitz?​

Skyhitz is a music streaming and investment platform where:

  • Listeners earn HITZ tokens by streaming, liking, and downloading tracks
  • Investors stake HITZ tokens to gain equity in music entries and earn ongoing rewards
  • Miners bring external music onto the platform and earn as initial stakeholders
  • Creators can claim ownership and benefit from their music's performance

System Overview​

Dual-Contract Architecture​

Skyhitz runs on two Soroban smart contracts:

  1. HITZ Token Contract (SEP-41 compatible)

    • 21 million max supply
    • Bitcoin-style halving every 4 years
    • No pre-mint - all tokens earned through actions
    • 7 decimals precision

  2. Skyhitz Core Contract

    • Records all user actions (stream, like, download, mine, invest)
    • Manages HITZ token staking for equity positions
    • Handles XLM fee collection and treasury management
    • Distributes HITZ rewards to entry pools

Dual Token Economy​

  • XLM (Stellar Lumens): Used for action fees (0.01-0.1 XLM per action)
  • HITZ Token: Earned as instant rewards and used for staking/governance

Two Revenue Streams​

  1. Escrow (Performance-based)

    • Generated by micro-spend actions: stream, like, download
    • Increases entry's escrow value
    • Used to distribute Treasury rewards proportionally

  2. TVL (Total Value Locked - Equity-based)

    • Generated by equity actions: mine, invest
    • Requires staking HITZ tokens
    • Grants proportional ownership and reward claims

Quick Start​

For New Users​

  1. Start with Tokenomics & Rewards to understand the economic model
  2. Read User Action Flows to see how actions work
  3. Learn about APR Calculation to evaluate investment opportunities

For Developers​

  1. Review the Stellar & Soroban Contracts documentation
  2. Explore the Contract Source Code
  3. Check out the GraphQL API documentation

For Platform Operators​

  1. Understand the Treasury Bot System for automated distributions
  2. Review Deployment Procedures for contract updates
  3. Study the APR Math for monitoring platform health

Key Features​

Instant Rewards​

Every action on Skyhitz earns HITZ tokens immediately:

  • Stream a song → 0.3 HITZ (epoch 0)
  • Like a track → 0.6 HITZ (epoch 0)
  • Download → 0.9 HITZ (epoch 0)
  • Mine a track → 3.0 HITZ (epoch 0)
  • Invest 1 XLM → 3.0 HITZ (epoch 0)

Staking & Ownership​

Mine and Invest actions require staking HITZ tokens:

  • Stake is locked in the contract
  • Grants proportional ownership in the entry
  • Enables claiming rewards from the entry's reward pool
  • Ownership percentage: your_stake / total_staked

Treasury Bot Automation​

The Treasury bot automates the reward distribution:

  1. Collects accumulated XLM fees from user actions
  2. Converts XLM to HITZ on Stellar DEX
  3. Distributes HITZ to entry reward pools
  4. Distribution is proportional to entry performance (escrow)

Deflationary Supply​

HITZ token follows Bitcoin's emission model:

  • Max supply: 21,000,000 HITZ
  • Halving every 4 years
  • ~99% released in first 24 years
  • Creates long-term scarcity and value

Documentation Structure​

Tokenomics​

Backend​

Frontend​

Operations​

Getting Started​

Use the left sidebar to explore different sections of the documentation.

If you're new, we recommend starting with:

  1. Rewards Overview - Understand how the system works
  2. User Action Flows - See detailed flow diagrams
  3. Stellar & Soroban - Learn about the smart contracts

Key Concepts​

Actions​

All user interactions are recorded as actions with difficulty levels:

  • Stream (difficulty 1): Listen to a track
  • Like (difficulty 2): Like a track
  • Download (difficulty 3): Download a track
  • Mine (difficulty 10): Bring external music to platform
  • Invest (dynamic): Stake more in an existing entry

Difficulty & Rewards​

Rewards scale with difficulty:

HITZ Reward = difficulty × unit_reward(epoch)

Example (epoch 0):

  • Stream: 1 × 0.3 = 0.3 HITZ
  • Mine: 10 × 0.3 = 3.0 HITZ
  • Invest 5 XLM: 50 × 0.3 = 15.0 HITZ

Staking​

Equity actions (mine/invest) require staking HITZ:

HITZ Stake = difficulty × 5 HITZ

Example:

  • Mine (difficulty 10): 50 HITZ stake
  • Invest 1 XLM (difficulty 10): 50 HITZ stake
  • Invest 10 XLM (difficulty 100): 500 HITZ stake

APR (Annual Percentage Rate)​

APR shows projected annual returns for stakers:

APR = (reward_pool / total_staked / days_elapsed) × 365 × 10000

Returns are in basis points (10000 = 100% APR).

Claiming​

Stakers claim rewards proportional to their ownership:

Claimable = (your_stake / total_staked) × reward_pool - already_claimed

Claims can be made anytime and don't affect your stake.

Platform Statistics​

Track these key metrics:

Token Metrics​

  • Total Released: Total HITZ minted
  • Current Epoch: Current halving period
  • Unit Reward: Current reward per unit of difficulty
  • Remaining Supply: HITZ until max supply

Entry Metrics​

  • TVL: Total XLM value locked in equity stakes
  • Escrow: Total XLM from performance actions
  • Total Staked: Total HITZ staked across all users
  • APR: Annualized return rate for stakers
  • Reward Pool: Available HITZ rewards

User Metrics​

  • Actions/Day: Platform activity level
  • Average Stake: Typical stake size
  • Claim Frequency: How often users claim rewards

Support & Resources​

For security issues, email: [email protected]

What's Next?​

Choose your path:

📊 Understanding Economics → Start with Rewards Overview

🔧 Technical Implementation → Start with Stellar & Soroban

🎵 Using the Platform → Start with User Action Flows

🚀 Operating the System → Start with Treasury Bot