Royal Protocol

The First Provably Fair Blockchain Lottery with Deflationary Token Economics on Solana

Overview

Royal Protocol is a revolutionary blockchain-based lottery system that combines transparent gaming mechanics with deflationary token economics. Players compete in fair, VRF-powered number matching games while every entry automatically contributes to token buybacks, creating sustainable value appreciation.

Key Features

Provably Fair Gaming - VRF-powered random number generation
Transparent Odds - Clear probability mechanics with no house edge
Automatic Buybacks - 10% of every game triggers token purchases and burns
Lightning Fast - Built on Solana for sub-second finality
Non-Custodial - Smart contracts handle all payouts automatically
Dual Token Support - Play with SOL or ROYAL tokens

Game Mechanics

Room Types

Room	Entry Fee	Max Players	Buyback Target
Rookie	0.1 SOL / 100 ROYAL	10	Immediate
Pro	0.25 SOL / 250 ROYAL	10	Batched
Elite	0.5 SOL / 500 ROYAL	10	Batched
Gold	1.0 SOL / 1000 ROYAL	10	Immediate

Game Mathematics

Match Mechanics:

Each position: 10 possible digits (0-9)
Probability of match per position: 1/10
Expected matches per player: ~1.0

Win Determination:

Highest match count wins the prize pool
Multiple winners split prizes equally
No matches = automatic full refunds

Important Notes:

Actual win probabilities depend on player distribution
10% platform fee affects expected returns
Results may vary significantly from mathematical expectations

How to Play

1. Select Numbers - Choose 10 digits (0-9) for each position

2. Join Room - Pay entry fee, game starts when 2+ players join

3. Wait for Draw - 60-second timer or when room fills up

4. VRF Generation - Provably random winning numbers generated

5. Win Prizes - Highest match count wins, ties split the pot

Win Probability Analysis

Player vs Player: No house edge, players compete against each other
Match-Based Winning: Higher number matches win the prize pool
Tie Handling: Multiple winners split prizes equally
Player Protection: If no winners found, all players receive full refunds
Transparency: All odds calculable from game mechanics

Unlike traditional gambling where the house always has an edge, Royal Protocol uses a player-vs-player model with transparent mathematics.

Technical Architecture

Program Structure

// Core account structures
#[account]
pub struct LotteryRoom {
    pub room_id: [u8; 16],
    pub room_type: RoomType,
    pub player_count: u8,
    pub players: [Pubkey; 10],
    pub player_numbers: [[u8; 10]; 10],
    pub status: GameStatus,
    pub prize_pool_amount: u64,
    pub winning_numbers: [u8; 10],
    // ... more fields
}

#[account] 
pub struct Protocol {
    pub authority: Pubkey,
    pub is_active: bool,
}

Revenue Flow

Player Entry → Lottery Room
├── 90% → Prize Pool (Winners)
└── 10% → Fee Vault → Automatic Buyback & Burn

PDA Architecture

Protocol: ["protocol"]
Room: ["room", room_id]
Fee Vault: ["fee_vault", authority]
WSOL Account: ["wsol", fee_vault]
Base Token Account: ["base_token", fee_vault]

Getting Started

Prerequisites

Rust (1.75.0+)
Solana CLI (1.18.0+)
Anchor (0.30.0+)
Node.js (18.0.0+)

Installation

# Clone repository
git clone https://github.com/tokenroyal/royal_protocol.git
cd royal_protocol

# Install dependencies
yarn install

# Build program
anchor build

# Generate program keypair
solana-keygen new -o target/deploy/royal_protocol-keypair.json

# Update program ID in lib.rs and Anchor.toml
anchor keys list

Local Development

# Start local validator
solana-test-validator

# Deploy program
anchor deploy

# Run tests
anchor test

Environment Setup

# Set cluster (devnet/mainnet)
solana config set --url devnet
anchor build
anchor deploy

# Initialize protocol
anchor run initialize-protocol

# Create game rooms
anchor run create-rooms

Testing

Unit Tests

# Run all tests
anchor test

# Run specific test suites
anchor test --skip-local-validator tests/unit/01-protocol.ts
anchor test --skip-local-validator tests/unit/02-room-creation.ts
anchor test --skip-local-validator tests/unit/03-player-mechanics.ts

Integration Tests

# Full SOL room workflow
anchor test tests/integration/royal-protocol.ts

# Full ROYAL token workflow  
anchor test tests/integration/royal-token-test.ts.ts

Test Wallets

Generate test wallets for development:

mkdir test-wallets
for i in {1..10}; do
  solana-keygen new --outfile test-wallets/player${i}.json --no-bip39-passphrase
done

Program Instructions

Core Instructions

// Initialize the protocol
pub fn initialize_protocol(ctx: Context<InitializeProtocol>) -> Result<()>

// Create a new lottery room
pub fn create_room(ctx: Context<CreateRoom>, room_id: [u8; 16], room_type: RoomType) -> Result<()>

// Join room with number selection
pub fn join_room(ctx: Context<JoinRoom>, numbers: [u8; 10]) -> Result<()>

// Trigger VRF draw
pub fn trigger_draw(ctx: Context<TriggerDraw>, force: [u8; 32]) -> Result<()>

// Complete draw after VRF fulfillment
pub fn complete_draw(ctx: Context<CompleteDraw>) -> Result<()>

// Claim prizes
pub fn claim_prize(ctx: Context<ClaimPrize>) -> Result<()>

// Execute buyback and burn
pub fn execute_buyback_and_burn(ctx: Context<ExecuteBuyback>) -> Result<()>

Error Codes

#[error_code]
pub enum RoyalError {
    #[msg("Room is not accepting players")]
    RoomNotAcceptingPlayers,
    #[msg("Room is full")]
    RoomFull,
    #[msg("Invalid numbers - must be 0-9")]
    InvalidNumbers,
    #[msg("Player already joined this room")]
    PlayerAlreadyJoined
}

Tokenomics

TOKEN ROYAL ($ROYAL)

Blockchain: Solana (SPL Token)
Use Cases:
- Native gameplay currency
- Deflationary buyback target
- Future governance rights

Deflationary Mechanism

1. SOL Rooms: 10% fee → Auto SOL→ROYAL swap → Immediate burn

2. ROYAL Rooms: 10% fee → Direct token burn

3. Volume Impact: Higher game volume = More tokens removed from supply

Buyback Thresholds

const BUYBACK_THRESHOLDS: [u64; 4] = [
    500_000_000,  // Rookie: 0.5 SOL accumulated  
    300_000_000,  // Pro: 0.3 SOL accumulated
    200_000_000,  // Elite: 0.2 SOL accumulated  
    100_000_000,  // Gold: 0.1 SOL (immediate)
];

Security Features

Smart Contract Security

Anchor framework with built-in protections
PDA-based access control
Overflow/underflow protection
VRF randomness verification
Emergency pause functionality

Randomness Security

ORAO VRF integration for provable fairness
On-chain randomness verification
Historical auditability of all draws
Impossible for manipulation by players or operators

Economic Security

Non-custodial prize distribution
Transparent fee structure
Immediate settlement
Automatic refunds when no winners exist
No operator withdrawal capabilities
Zero-loss protection in edge cases

Deployment

Devnet Deployment

# Configure for devnet
solana config set --url devnet
anchor build

# Deploy
anchor deploy --provider.cluster devnet

# Verify deployment
solana program show <PROGRAM_ID>

Mainnet Deployment

# Configure for mainnet
solana config set --url mainnet-beta

# Build with mainnet configurations
anchor build --verifiable

# Deploy with buffer account
solana program write-buffer target/deploy/royal_protocol.so
solana program set-buffer-authority <BUFFER_ADDRESS> --new-buffer-authority <UPGRADE_AUTHORITY>
solana program deploy <BUFFER_ADDRESS>

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Workflow

1. Fork the repository

2. Create a feature branch (`git checkout -b feature/amazing-feature`)

3. Make your changes

4. Add tests for new functionality

5. Ensure all tests pass (`anchor test`)

6. Commit your changes (`git commit -m 'Add amazing feature'`)

7. Push to the branch (`git push origin feature/amazing-feature`)

8. Open a Pull Request

🔗 Links

Website: https://tokenroyal.fun
Twitter: @tokenroyalwin

License

This project is licensed under the MIT License - see the LICENSE file for details.

Disclaimer

This software is provided "as is" without warranty. Cryptocurrency and blockchain gaming involve financial risk. Users should understand the risks before participating. This is experimental technology and should be used responsibly.

Built with ❤️ for the Solana ecosystem

Royal Protocol - Where Players Win, House Never Does

Name		Name	Last commit message	Last commit date
Latest commit History 39 Commits
.github/workflows		.github/workflows
assets		assets
migrations		migrations
programs/royal_protocol		programs/royal_protocol
scripts		scripts
tests		tests
utils		utils
.gitignore		.gitignore
.prettierignore		.prettierignore
Anchor.toml		Anchor.toml
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
README.md		README.md
package.json		package.json
send-royal-to-players.sh		send-royal-to-players.sh
send-sol-to-players.sh		send-sol-to-players.sh
token-info.json		token-info.json
tsconfig.json		tsconfig.json
yarn.lock		yarn.lock

tokenroyal/royal_protocol

Folders and files

Latest commit

History

Repository files navigation