https://github.com/tokenroyal/royal_protocol
Royal Protocol - The first provably fair blockchain lottery with deflationary token economics on Solana. VRF-powered number matching games with automatic token buybacks.
https://github.com/tokenroyal/royal_protocol
anchor blockchain buyback defi gambling gaming lottery provably-fair rust solana tokenomics vrf
Last synced: about 1 month ago
JSON representation
Royal Protocol - The first provably fair blockchain lottery with deflationary token economics on Solana. VRF-powered number matching games with automatic token buybacks.
- Host: GitHub
- URL: https://github.com/tokenroyal/royal_protocol
- Owner: tokenroyal
- Created: 2025-08-30T20:31:04.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-09-15T18:18:05.000Z (9 months ago)
- Last Synced: 2025-09-17T21:49:49.176Z (9 months ago)
- Topics: anchor, blockchain, buyback, defi, gambling, gaming, lottery, provably-fair, rust, solana, tokenomics, vrf
- Language: TypeScript
- Homepage: https://tokenroyal.fun
- Size: 242 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
#
# Royal Protocol
[](https://opensource.org/licenses/MIT)
[](https://solana.com/)
[](https://www.anchor-lang.com/)
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
```rust
// 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](https://rustlang.org/tools/install) (1.75.0+)
- [Solana CLI](https://docs.solana.com/cli/install-solana-cli-tools) (1.18.0+)
- [Anchor](https://www.anchor-lang.com/docs/installation) (0.30.0+)
- [Node.js](https://nodejs.org/) (18.0.0+)
### Installation
```bash
# 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
```bash
# Start local validator
solana-test-validator
# Deploy program
anchor deploy
# Run tests
anchor test
```
### Environment Setup
```bash
# 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
```bash
# 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
```bash
# 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:
```bash
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
```rust
// Initialize the protocol
pub fn initialize_protocol(ctx: Context) -> Result<()>
// Create a new lottery room
pub fn create_room(ctx: Context, room_id: [u8; 16], room_type: RoomType) -> Result<()>
// Join room with number selection
pub fn join_room(ctx: Context, numbers: [u8; 10]) -> Result<()>
// Trigger VRF draw
pub fn trigger_draw(ctx: Context, force: [u8; 32]) -> Result<()>
// Complete draw after VRF fulfillment
pub fn complete_draw(ctx: Context) -> Result<()>
// Claim prizes
pub fn claim_prize(ctx: Context) -> Result<()>
// Execute buyback and burn
pub fn execute_buyback_and_burn(ctx: Context) -> Result<()>
```
### Error Codes
```rust
#[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
```rust
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
```bash
# Configure for devnet
solana config set --url devnet
anchor build
# Deploy
anchor deploy --provider.cluster devnet
# Verify deployment
solana program show
```
### Mainnet Deployment
```bash
# 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 --new-buffer-authority
solana program deploy
```
## 🤝 Contributing
We welcome contributions! Please see [CONTRIBUTING.md](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](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*