SovereignBit Realms: Core Protocol Implementation

[peter-curl]

Overview

This pull request introduces the foundational components for a Bitcoin-native gaming protocol on Stacks L2, implementing 6 key feature sets with Clarity's verifiable smart contract paradigm. The changes establish a compliant framework for NFT-based gameplay with enterprise-grade security controls.

Added Features

Input Validation System

• is-valid-name enforces 1-50 char names with regex patterns
• is-valid-description validates 200 char max descriptions
• Blacklisted phrase filtering for compliance

Competitive Gameplay Infrastructure

• player-rankings map with score/rank tracking
• Leaderboard pagination via get-paginated-leaderboard
• Experience validation with calculate-level-up-experience

Trustless Asset Economy

• active-trades system with expiry/status tracking
• STX/NFT atomic swaps in execute-trade
• BRC-20 price validation in trade creation

Player Management

• Avatar creation with world access permissions
• NFT-gated experience progression
• Equippable asset management system

World Building Tools

• Admin-controlled world creation
• Dynamic entry requirement checks
• Cross-world asset compatibility

Compliance Framework

• Rate limiting per function/caller
• BRC-20 metadata validation hooks
• AML-friendly trade monitoring

Technical Implementation

1. Input Validation

(define-private (is-valid-name (name (string-ascii 50)))
  (and 
    (>= (len name) u1)
    (<= (len name) u50)
    (not (is-eq name ""))
    (regex-match? name "^[a-zA-Z0-9 ]+$")
  )
)

2. State Management

• player-rankings: Leaderboard storage with O(1) lookups
• rate-limits: Call tracking per (function, principal) pair
• active-trades: Time-locked escrow positions

3. Trading Mechanics

• STX-denominated pricing
• Block height-based expiry
• Multi-sig compatible settlement

4. Reward System

• Score-based reward curve
• BTC/STX dual payout support
• Anti-sybil farming checks

5. Security

(define-map rate-limits
  { function: (string-ascii 50), caller: principal }
  { last-call: uint, calls: uint }
)

• 24h rate limiting window
• Max 100 calls/function/window

Compliance & Security

• BRC-20 metadata standards enforcement
• Rate-limited critical operations
• Formal verification ready patterns
• Audit-ready code structure

Documentation

• Complete protocol README
• Usage examples for all public functions
• Compliance requirements matrix

Next Steps

1. Oracle integration for real-world asset pricing
2. Cross-chain BTC reward settlements
3. Player reputation subsystem