{"id":31127236,"url":"https://github.com/tokenroyal/royal_protocol","last_synced_at":"2026-05-09T03:32:52.412Z","repository":{"id":315305831,"uuid":"1047618858","full_name":"tokenroyal/royal_protocol","owner":"tokenroyal","description":"Royal Protocol - The first provably fair blockchain lottery with deflationary token economics on Solana. VRF-powered number matching games with automatic token buybacks.","archived":false,"fork":false,"pushed_at":"2025-09-15T18:18:05.000Z","size":248,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-17T21:49:49.176Z","etag":null,"topics":["anchor","blockchain","buyback","defi","gambling","gaming","lottery","provably-fair","rust","solana","tokenomics","vrf"],"latest_commit_sha":null,"homepage":"https://tokenroyal.fun","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tokenroyal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-30T20:31:04.000Z","updated_at":"2025-09-17T08:45:28.000Z","dependencies_parsed_at":"2025-09-17T21:49:52.002Z","dependency_job_id":"4f8aebf6-66ab-471f-8f5f-b23f31ae8012","html_url":"https://github.com/tokenroyal/royal_protocol","commit_stats":null,"previous_names":["tokenroyal/royal_protocol"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/tokenroyal/royal_protocol","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tokenroyal%2Froyal_protocol","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tokenroyal%2Froyal_protocol/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tokenroyal%2Froyal_protocol/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tokenroyal%2Froyal_protocol/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tokenroyal","download_url":"https://codeload.github.com/tokenroyal/royal_protocol/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tokenroyal%2Froyal_protocol/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275680444,"owners_count":25508570,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-17T02:00:09.119Z","response_time":84,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anchor","blockchain","buyback","defi","gambling","gaming","lottery","provably-fair","rust","solana","tokenomics","vrf"],"created_at":"2025-09-17T23:04:17.284Z","updated_at":"2025-09-17T23:04:19.862Z","avatar_url":"https://github.com/tokenroyal.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# \u003cdiv align=\"center\"\u003e\u003cimg src=\"assets/logo.svg\" width=\"200\" height=\"200\" alt=\"tokenroyal.fun\"\u003e\u003c/div\u003e\n\n# Royal Protocol\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Solana](https://img.shields.io/badge/Built%20on-Solana-purple)](https://solana.com/)\n[![Anchor](https://img.shields.io/badge/Framework-Anchor-blue)](https://www.anchor-lang.com/)\n\nThe First Provably Fair Blockchain Lottery with Deflationary Token Economics on Solana\n\n## Overview\nRoyal 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.\n\n## Key Features\n- **Provably Fair Gaming** - VRF-powered random number generation\n- **Transparent Odds** - Clear probability mechanics with no house edge\n- **Automatic Buybacks** - 10% of every game triggers token purchases and burns\n- **Lightning Fast** - Built on Solana for sub-second finality\n- **Non-Custodial** - Smart contracts handle all payouts automatically\n- **Dual Token Support** - Play with SOL or ROYAL tokens\n\n## Game Mechanics\n\n### Room Types\n\n| Room | Entry Fee | Max Players | Buyback Target |\n|------|-----------|-------------|----------------|\n| **Rookie** | 0.1 SOL / 100 ROYAL | 10 | Immediate |\n| **Pro** | 0.25 SOL / 250 ROYAL | 10 | Batched |\n| **Elite** | 0.5 SOL / 500 ROYAL | 10 | Batched |\n| **Gold** | 1.0 SOL / 1000 ROYAL | 10 | Immediate |\n\n\n### Game Mathematics\n\n**Match Mechanics:**\n- Each position: 10 possible digits (0-9) \n- Probability of match per position: 1/10\n- Expected matches per player: ~1.0\n\n**Win Determination:**\n- Highest match count wins the prize pool\n- Multiple winners split prizes equally  \n- No matches = automatic full refunds\n\n**Important Notes:**\n- Actual win probabilities depend on player distribution\n- 10% platform fee affects expected returns\n- Results may vary significantly from mathematical expectations\n\n### How to Play\n\n#### 1. **Select Numbers** - Choose 10 digits (0-9) for each position\n#### 2. **Join Room** - Pay entry fee, game starts when 2+ players join\n#### 3. **Wait for Draw** - 60-second timer or when room fills up\n#### 4. **VRF Generation** - Provably random winning numbers generated\n#### 5. **Win Prizes** - Highest match count wins, ties split the pot\n\n### Win Probability Analysis\n\n- **Player vs Player**: No house edge, players compete against each other\n- **Match-Based Winning**: Higher number matches win the prize pool\n- **Tie Handling**: Multiple winners split prizes equally\n- **Player Protection**: If no winners found, all players receive full refunds\n- **Transparency**: All odds calculable from game mechanics\n\n*Unlike traditional gambling where the house always has an edge, Royal Protocol uses a player-vs-player model with transparent mathematics.*\n\n## Technical Architecture\n\n### Program Structure\n\n```rust\n// Core account structures\n#[account]\npub struct LotteryRoom {\n    pub room_id: [u8; 16],\n    pub room_type: RoomType,\n    pub player_count: u8,\n    pub players: [Pubkey; 10],\n    pub player_numbers: [[u8; 10]; 10],\n    pub status: GameStatus,\n    pub prize_pool_amount: u64,\n    pub winning_numbers: [u8; 10],\n    // ... more fields\n}\n\n#[account] \npub struct Protocol {\n    pub authority: Pubkey,\n    pub is_active: bool,\n}\n```\n\n### Revenue Flow\n\n```\nPlayer Entry → Lottery Room\n├── 90% → Prize Pool (Winners)\n└── 10% → Fee Vault → Automatic Buyback \u0026 Burn\n```\n\n\n### PDA Architecture\n\n- **Protocol**: `[\"protocol\"]`\n- **Room**: `[\"room\", room_id]` \n- **Fee Vault**: `[\"fee_vault\", authority]`\n- **WSOL Account**: `[\"wsol\", fee_vault]`\n- **Base Token Account**: `[\"base_token\", fee_vault]`\n\n## Getting Started\n\n### Prerequisites\n\n- [Rust](https://rustlang.org/tools/install) (1.75.0+)\n- [Solana CLI](https://docs.solana.com/cli/install-solana-cli-tools) (1.18.0+)\n- [Anchor](https://www.anchor-lang.com/docs/installation) (0.30.0+)\n- [Node.js](https://nodejs.org/) (18.0.0+)\n\n### Installation\n\n```bash\n# Clone repository\ngit clone https://github.com/tokenroyal/royal_protocol.git\ncd royal_protocol\n\n# Install dependencies\nyarn install\n\n# Build program\nanchor build\n\n# Generate program keypair\nsolana-keygen new -o target/deploy/royal_protocol-keypair.json\n\n# Update program ID in lib.rs and Anchor.toml\nanchor keys list\n```\n\n### Local Development\n\n```bash\n# Start local validator\nsolana-test-validator\n\n# Deploy program\nanchor deploy\n\n# Run tests\nanchor test\n```\n\n### Environment Setup\n\n```bash\n# Set cluster (devnet/mainnet)\nsolana config set --url devnet\nanchor build\nanchor deploy\n\n# Initialize protocol\nanchor run initialize-protocol\n\n# Create game rooms\nanchor run create-rooms\n```\n\n## Testing\n\n### Unit Tests\n\n```bash\n# Run all tests\nanchor test\n\n# Run specific test suites\nanchor test --skip-local-validator tests/unit/01-protocol.ts\nanchor test --skip-local-validator tests/unit/02-room-creation.ts\nanchor test --skip-local-validator tests/unit/03-player-mechanics.ts\n```\n\n### Integration Tests\n\n```bash\n# Full SOL room workflow\nanchor test tests/integration/royal-protocol.ts\n\n# Full ROYAL token workflow  \nanchor test tests/integration/royal-token-test.ts.ts\n```\n\n### Test Wallets\n\nGenerate test wallets for development:\n\n```bash\nmkdir test-wallets\nfor i in {1..10}; do\n  solana-keygen new --outfile test-wallets/player${i}.json --no-bip39-passphrase\ndone\n```\n\n## Program Instructions\n\n### Core Instructions\n\n```rust\n// Initialize the protocol\npub fn initialize_protocol(ctx: Context\u003cInitializeProtocol\u003e) -\u003e Result\u003c()\u003e\n\n// Create a new lottery room\npub fn create_room(ctx: Context\u003cCreateRoom\u003e, room_id: [u8; 16], room_type: RoomType) -\u003e Result\u003c()\u003e\n\n// Join room with number selection\npub fn join_room(ctx: Context\u003cJoinRoom\u003e, numbers: [u8; 10]) -\u003e Result\u003c()\u003e\n\n// Trigger VRF draw\npub fn trigger_draw(ctx: Context\u003cTriggerDraw\u003e, force: [u8; 32]) -\u003e Result\u003c()\u003e\n\n// Complete draw after VRF fulfillment\npub fn complete_draw(ctx: Context\u003cCompleteDraw\u003e) -\u003e Result\u003c()\u003e\n\n// Claim prizes\npub fn claim_prize(ctx: Context\u003cClaimPrize\u003e) -\u003e Result\u003c()\u003e\n\n// Execute buyback and burn\npub fn execute_buyback_and_burn(ctx: Context\u003cExecuteBuyback\u003e) -\u003e Result\u003c()\u003e\n```\n\n### Error Codes\n\n```rust\n#[error_code]\npub enum RoyalError {\n    #[msg(\"Room is not accepting players\")]\n    RoomNotAcceptingPlayers,\n    #[msg(\"Room is full\")]\n    RoomFull,\n    #[msg(\"Invalid numbers - must be 0-9\")]\n    InvalidNumbers,\n    #[msg(\"Player already joined this room\")]\n    PlayerAlreadyJoined\n}\n```\n\n## Tokenomics\n\n### TOKEN ROYAL ($ROYAL)\n\n- **Blockchain**: Solana (SPL Token)\n- **Use Cases**: \n  - Native gameplay currency\n  - Deflationary buyback target\n  - Future governance rights\n\n### Deflationary Mechanism\n\n#### 1. **SOL Rooms**: 10% fee → Auto SOL→ROYAL swap → Immediate burn\n#### 2. **ROYAL Rooms**: 10% fee → Direct token burn\n#### 3. **Volume Impact**: Higher game volume = More tokens removed from supply\n\n### Buyback Thresholds\n\n```rust\nconst BUYBACK_THRESHOLDS: [u64; 4] = [\n    500_000_000,  // Rookie: 0.5 SOL accumulated  \n    300_000_000,  // Pro: 0.3 SOL accumulated\n    200_000_000,  // Elite: 0.2 SOL accumulated  \n    100_000_000,  // Gold: 0.1 SOL (immediate)\n];\n```\n\n## Security Features\n\n### Smart Contract Security\n\n- Anchor framework with built-in protections\n- PDA-based access control\n- Overflow/underflow protection\n- VRF randomness verification\n- Emergency pause functionality\n\n### Randomness Security\n\n- ORAO VRF integration for provable fairness\n- On-chain randomness verification\n- Historical auditability of all draws\n- Impossible for manipulation by players or operators\n\n### Economic Security\n\n- Non-custodial prize distribution\n- Transparent fee structure\n- Immediate settlement\n- **Automatic refunds** when no winners exist\n- No operator withdrawal capabilities\n- **Zero-loss protection** in edge cases\n\n## Deployment\n\n### Devnet Deployment\n\n```bash\n# Configure for devnet\nsolana config set --url devnet\nanchor build\n\n# Deploy\nanchor deploy --provider.cluster devnet\n\n# Verify deployment\nsolana program show \u003cPROGRAM_ID\u003e\n```\n\n### Mainnet Deployment\n\n```bash\n# Configure for mainnet\nsolana config set --url mainnet-beta\n\n# Build with mainnet configurations\nanchor build --verifiable\n\n# Deploy with buffer account\nsolana program write-buffer target/deploy/royal_protocol.so\nsolana program set-buffer-authority \u003cBUFFER_ADDRESS\u003e --new-buffer-authority \u003cUPGRADE_AUTHORITY\u003e\nsolana program deploy \u003cBUFFER_ADDRESS\u003e\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Development Workflow\n\n#### 1. Fork the repository\n#### 2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n#### 3. Make your changes\n#### 4. Add tests for new functionality\n#### 5. Ensure all tests pass (`anchor test`)\n#### 6. Commit your changes (`git commit -m 'Add amazing feature'`)\n#### 7. Push to the branch (`git push origin feature/amazing-feature`)\n#### 8. Open a Pull Request\n\n## 🔗 Links\n\n- **Website**: https://tokenroyal.fun\n- **Twitter**: @tokenroyalwin\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Disclaimer\n\nThis 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.\n\n---\n\n**Built with ❤️ for the Solana ecosystem**\n\n*Royal Protocol - Where Players Win, House Never Does*","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftokenroyal%2Froyal_protocol","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftokenroyal%2Froyal_protocol","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftokenroyal%2Froyal_protocol/lists"}