Skip to content

lopeselio/aptos-sigil

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

62 Commits
docs
docs
 
 
move
move
 
 
README.md
README.md
 
 
ROADMAP_AND_SDK_INTEGRATION.md
ROADMAP_AND_SDK_INTEGRATION.md
 
 

Repository files navigation

Sigil Game Platform - Aptos Smart Contract

License: MIT Aptos Move

SIGIL - Signatures for In-Game Incentives & Leaderboards

A complete, production-ready gaming platform on Aptos featuring instant automated rewards, gasless gameplay, and comprehensive achievement systems.

⚡ Phase Final: Automatic Rewards LIVE!

Players now receive APT/NFT rewards INSTANTLY when claiming achievements!

→ See Automatic Rewards Integration Guide

🎮 Features

Module Status Description
game_platform ✅ Live Game registration, player profiles, score submission
leaderboard ✅ Live Dynamic rankings, top-N tracking, configurable sorting
achievements ✅ Live 6 achievement types, progress tracking, badge/NFT support
rewards ✅ Live Automatic FA/NFT distribution ⚡ (Phase Final!)
seasons ✅ Live Time-bounded competitions, seasonal rankings, prize pools 🏆
quests ✅ Live Mission-based progression, 6 quest types, wrapper pattern 🎯 (NEW!)
roles ✅ Live Multi-admin & operator management for teams 🔐
shadow_signers ✅ Live Gasless gameplay via session keys (no wallet popups!)
treasury ✅ Live FA management, deposit/withdrawal tracking
attest ✅ Live Server-side score verification (anti-cheat) 🛡️

Core Capabilities

  • Game Management - Publishers can register games with unique IDs
  • Player Profiles - Players create on-chain profiles with usernames
  • Score Submission - Submit and track scores for any registered game
  • Leaderboards - Dynamic, gas-optimized leaderboards with configurable ranking
  • Achievements - Flexible achievement system with progress tracking, badges, and advanced conditions
    • Basic score thresholds
    • Consistency achievements (score X, N times)
    • Dedication achievements (play N times)
    • Combo achievements (combine conditions)
    • Game-specific achievements
    • Badge/NFT URI support
  • Automatic Rewards ⚡
    • Instant FA distribution on claim (no waiting!)
    • Automatic NFT minting (badges delivered instantly)
    • Resource account integration (secure, trustless)
    • Single-transaction claiming (870 gas for FA)
    • No backend server required
  • Seasons 🏆
    • Time-bounded competitive periods (1-90 days)
    • Isolated season scores & leaderboards
    • Prize pool management (APT distribution)
    • Season states (upcoming/active/ended)
    • Wrapper pattern (works with all modules)
    • Battle pass & tournament support
  • Quests 🎯 NEW!
    • Mission-based progression system
    • 6 quest types (score, achievement, play count, streak, rank, multi-step)
    • Automatic progress tracking
    • Seasonal quest support
    • Instant rewards on completion
    • Wrapper pattern (coordinates all 8 modules)
  • Gasless Gameplay - Shadow Signers (session keys)
    • One wallet popup, then play freely
    • Relayer-paid gas (configurable)
    • Scope-based permissions (secure delegation)
    • TTL management (max 7 days)
  • Treasury Management - Multi-FA support
    • Deposit/withdrawal tracking
    • Balance verification
    • Publisher-controlled
  • Events - All actions emit events for easy indexing

🎭 Who Can Use Sigil?

Anyone can become a publisher! The Sigil platform uses per-publisher architecture - each game creator has their own independent gaming ecosystem.

Role What You Can Do Access Control
Publisher (You!) ✅ Create your own games
✅ Set up leaderboards
✅ Design achievements
✅ Attach rewards
✅ Manage your ecosystem		 Your &signer controls YOUR resources only
Players ✅ Play any publisher's games
✅ Submit scores
✅ Earn achievements
✅ Claim rewards		 Their &signer for claims
Anyone ✅ View all games/leaderboards
✅ Check achievements
✅ See rewards		 Public view functions (free)

Key Point: ✅ No approval needed! Just initialize the modules at your address and you're a publisher.

See: REWARDS_GUIDE.md - Actors & Access Control for complete details.

📋 Prerequisites

  • Aptos CLI installed (v7.8.1+)
  • Aptos account with devnet tokens (your publisher address)
  • API Key from Aptos Labs (optional, for higher rate limits)

📁 Project Structure

sigil-aptos/
├── move/
│   ├── sources/
│   │   ├── sigil_core.move         ✅ Game platform (9 functions)
│   │   ├── leaderboard.move        ✅ Dynamic rankings (7 functions)
│   │   ├── achievements.move       ✅ Achievement system (13 functions)
│   │   └── rewards.move            ✅ Reward distribution (12 functions)
│   │
│   ├── tests/
│   │   ├── leaderboard_tests.move  ✅ 15 tests passing
│   │   ├── achievements_tests.move ✅ 20 tests passing
│   │   └── rewards_tests.move      ✅ 26 tests passing
│   │
│   └── Move.toml                   📦 Package configuration
│
├── .aptos/
│   └── config.yaml                 🔧 Aptos CLI profiles (included in .gitignore)
│
├── README.md                        📚 Main documentation 
├── REWARDS_GUIDE.md                 📚 Complete rewards guide with use cases
├── ACHIEVEMENTS_GUIDE.md            📚 Complete achievements guide 
├── LEADERBOARD_INTEGRATION.md       📚 Leaderboard integration details 
├── TESTING_GUIDE.md                 📚 Testing scenarios and commands 
└── SUMMARY.md                       📚 Technical implementation notes

Total Stats:

  • 4 Modules - 3 deployed on devnet, 1 ready to deploy
  • 61 Unit Tests - 100% passing
  • 41 Public Functions - Complete gaming API
  • 6 Comprehensive Guides - 5,500+ lines of documentation

🚀 Deployment Steps

1. Configure Your Environment

Create or update .aptos/config.yaml in your project root:

---
profiles:
  sigil-main:
    network: Devnet
    private_key: "YOUR_PRIVATE_KEY_HERE"
    public_key: "YOUR_PUBLIC_KEY_HERE"
    account: YOUR_ACCOUNT_ADDRESS
    rest_url: "https://api.devnet.aptoslabs.com"
    faucet_url: "https://faucet.devnet.aptoslabs.com"
    api_key: "YOUR_API_KEY_HERE"

2. Update Move.toml

Update move/Move.toml with your account address:

[addresses]
sigil = "YOUR_ACCOUNT_ADDRESS"

[dev-addresses]

3. Fund Your Account

aptos account fund-with-faucet \
  --account YOUR_ACCOUNT_ADDRESS \
  --profile sigil-main

4. Compile the Modules

cd move
aptos move compile --save-metadata

5. Deploy to Devnet

aptos move publish \
  --package-dir move \
  --profile sigil-main \
  --assume-yes

6. Initialize the Modules

Important: Initialize all modules after deployment.

# Initialize Game Platform
aptos move run \
  --function-id 'YOUR_ACCOUNT_ADDRESS::game_platform::init' \
  --profile sigil-main \
  --assume-yes \
  --max-gas 2000

# Initialize Leaderboards
aptos move run \
  --function-id 'YOUR_ACCOUNT_ADDRESS::leaderboard::init_leaderboards' \
  --profile sigil-main \
  --assume-yes \
  --max-gas 2000

# Initialize Achievements
aptos move run \
  --function-id 'YOUR_ACCOUNT_ADDRESS::achievements::init_achievements' \
  --profile sigil-main \
  --assume-yes \
  --max-gas 2000

📝 Game Platform Functions

Publisher Functions

Register a Game

aptos move run \
  --function-id 'YOUR_ACCOUNT_ADDRESS::game_platform::register_game' \
  --args string:"Game Title Here" \
  --profile sigil-main \
  --assume-yes

Parameters:

  • string - The title of your game

Example:

aptos move run \
  --function-id '0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6::game_platform::register_game' \
  --args string:"Space Shooter 2024" \
  --profile sigil-main \
  --assume-yes

Player Functions

Register as a Player

Players must register before submitting scores.

aptos move run \
  --function-id 'YOUR_ACCOUNT_ADDRESS::game_platform::register_player' \
  --args string:"your_username" \
  --profile sigil-main \
  --assume-yes

Example:

aptos move run \
  --function-id '0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6::game_platform::register_player' \
  --args string:"player123" \
  --profile sigil-main \
  --assume-yes

Submit a Score

aptos move run \
  --function-id 'YOUR_ACCOUNT_ADDRESS::game_platform::submit_score' \
  --args address:PUBLISHER_ADDRESS u64:GAME_ID u64:SCORE \
  --profile sigil-main \
  --assume-yes

Parameters:

  • address - The publisher's address who owns the game
  • u64 - The game ID (starts from 0)
  • u64 - The score value

Example:

aptos move run \
  --function-id '0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6::game_platform::submit_score' \
  --args address:0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6 u64:0 u64:5000 \
  --profile sigil-main \
  --assume-yes

View Functions (Read State)

View functions don't require gas and are free to call.

Get Game Count

aptos move view \
  --profile sigil-main \
  --function-id '0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6::game_platform::game_count' \
  --args address:0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6

Returns: ["1"] - Number of games

Get Game Details

aptos move view \
  --profile sigil-main \
  --function-id '0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6::game_platform::get_game' \
  --args address:0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6 u64:0

Returns:

[
  "0",           // Game ID
  "Test Game",   // Game Title
  "0xe68ef..."   // Creator Address
]

Get Player Scores

aptos move view \
  --profile sigil-main \
  --function-id '0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6::game_platform::get_scores' \
  --args address:0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6 address:PLAYER_ADDRESS u64:0

🏆 Leaderboard Functions

Create a Leaderboard

Publishers can create customizable leaderboards for their games.

aptos move run \
  --profile sigil-main \
  --function-id 'YOUR_ACCOUNT_ADDRESS::leaderboard::create_leaderboard' \
  --args u64:GAME_ID u8:DECIMALS u64:MIN_SCORE u64:MAX_SCORE bool:IS_ASCENDING bool:ALLOW_MULTIPLE u64:TOP_N \
  --assume-yes

Parameters:

  • game_id (u64) - The game ID to create leaderboard for
  • decimals (u8) - Number of decimal places for display (0 for integers)
  • min_score (u64) - Minimum valid score (scores below are rejected)
  • max_score (u64) - Maximum valid score (scores above are rejected)
  • is_ascending (bool) - false = higher is better, true = lower is better (speedruns)
  • allow_multiple (bool) - false = only best score per player, true = allow multiple submissions
  • scores_to_retain (u64) - How many top entries to keep (e.g., top 10, top 100)

Example - High Score Leaderboard (Top 10):

aptos move run \
  --profile sigil-main \
  --function-id '0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6::leaderboard::create_leaderboard' \
  --args u64:0 u8:0 u64:0 u64:999999999 bool:false bool:false u64:10 \
  --assume-yes

Example - Speedrun Leaderboard (Lower Time is Better):

aptos move run \
  --profile sigil-main \
  --function-id '0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6::leaderboard::create_leaderboard' \
  --args u64:0 u8:2 u64:0 u64:999999 bool:true bool:false u64:50 \
  --assume-yes

Submit Score to Leaderboard

For testing purposes, you can directly submit scores to the leaderboard:

aptos move run \
  --profile sigil-main \
  --function-id 'YOUR_ACCOUNT_ADDRESS::leaderboard::submit_score_direct' \
  --args address:PUBLISHER_ADDRESS u64:LEADERBOARD_ID address:PLAYER_ADDRESS u64:SCORE \
  --assume-yes

Example:

aptos move run \
  --profile sigil-main \
  --function-id '0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6::leaderboard::submit_score_direct' \
  --args address:0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6 u64:0 address:0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6 u64:2500 \
  --assume-yes

Leaderboard View Functions

Get Leaderboard Count

aptos move view \
  --profile sigil-main \
  --function-id '0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6::leaderboard::get_leaderboard_count' \
  --args address:0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6

Returns: Number of leaderboards created

Get Leaderboard Configuration

aptos move view \
  --profile sigil-main \
  --function-id '0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6::leaderboard::get_leaderboard_config' \
  --args address:0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6 u64:0

Returns:

[
  "0",         // game_id
  0,           // decimals
  "0",         // min_score
  "999999999", // max_score
  false,       // is_ascending
  false,       // allow_multiple
  "10"         // scores_to_retain
]

Get Top Entries (Leaderboard Rankings)

aptos move view \
  --profile sigil-main \
  --function-id '0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6::leaderboard::get_top_entries' \
  --args address:0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6 u64:0

Returns: Two aligned arrays - player addresses and their scores

{
  "Result": [
    [
      "0x30be4b352a2e02eae96e771a210d32ecab488f82c5b059bb1fa875117b81f239",
      "0x14cbc9d57823000f77aa8d29454ba90c52f0443fdb670b5a1357bcc07971c048",
      "0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6"
    ],
    [
      "2500",
      "2000",
      "1500"
    ]
  ]
}

🏆 Achievement Functions

📖 Full Documentation: See ACHIEVEMENTS_GUIDE.md for comprehensive documentation including:

  • All 6 achievement types with examples
  • Complete testing scenarios
  • Live deployment verification
  • Gas optimization details
  • 20 unit tests coverage
  • Helper tools and troubleshooting

Quick Start - Achievements

Create Achievement (Basic Example)

Example - "High Scorer" (Score 1000+):

aptos move run \
  --profile sigil-main \
  --function-id '0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6::achievements::create' \
  --args \
    hex:"486967682053636f726572" \
    hex:"53636f72652031303030206f72206d6f7265" \
    u64:1000 \
    hex:"" \
  --assume-yes \
  --max-gas 2000

Parameters:

  • title (hex) - Achievement title in UTF-8 hex (echo -n "Text" | xxd -p)
  • description (hex) - Description in UTF-8 hex
  • min_score (u64) - Minimum score to unlock
  • badge_uri (hex) - Badge URI (empty hex:"" for none)

Create Advanced Achievement

Example - "Consistent Performer" (Score 1000+ three times):

aptos move run \
  --profile sigil-main \
  --function-id '0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6::achievements::create_advanced' \
  --args \
    hex:"436f6e73697374656e7420506572666f726d6572" \
    hex:"53636f72652031303030206f72206d6f726520332074696d6573" \
    u64:1000 \
    u64:3 \
    u64:0 \
    hex:"" \
  --assume-yes \
  --max-gas 2000

Parameters:

  • min_score - Score threshold (0 = any score)
  • required_count - Times must hit threshold (0 = ignore)
  • min_submissions - Total games played (0 = ignore)

Achievement View Functions

Get Unlocked Achievements:

aptos move view --profile sigil-main \
  --function-id '0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6::achievements::unlocked_for' \
  --args address:PUBLISHER address:PLAYER
# Returns: [["0", "1", "2"]]

Get Achievement Progress:

aptos move view --profile sigil-main \
  --function-id '0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6::achievements::get_progress' \
  --args address:PUBLISHER address:PLAYER u64:ACHIEVEMENT_ID \
  --max-gas 2000
# Returns: ["2", "5", false]  // 2/3 threshold, 5 total plays, not unlocked

More view functions: achievement_count, get_achievement, is_unlocked, list_catalog
See: ACHIEVEMENTS_GUIDE.md for complete API reference

🎮 Complete Example Workflow

Here's a complete example of deploying and using the platform:

# 1. Compile
cd move && aptos move compile --save-metadata && cd ..

# 2. Deploy both modules
aptos move publish --package-dir move --profile sigil-main --assume-yes

# 3. Initialize game platform
aptos move run \
  --function-id '0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6::game_platform::init' \
  --profile sigil-main --assume-yes

# 4. Initialize leaderboards
aptos move run \
  --function-id '0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6::leaderboard::init_leaderboards' \
  --profile sigil-main --assume-yes

# 5. Register a game
aptos move run \
  --function-id '0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6::game_platform::register_game' \
  --args string:"Space Shooter" \
  --profile sigil-main --assume-yes

# 6. Create a leaderboard for the game (top 10)
aptos move run \
  --profile sigil-main \
  --function-id '0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6::leaderboard::create_leaderboard' \
  --args u64:0 u8:0 u64:0 u64:999999999 bool:false bool:false u64:10 \
  --assume-yes

# 7. Register as a player
aptos move run \
  --function-id '0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6::game_platform::register_player' \
  --args string:"gamer123" \
  --profile sigil-main --assume-yes

# 8. Submit scores to leaderboard
aptos move run \
  --profile sigil-main \
  --function-id '0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6::leaderboard::submit_score_direct' \
  --args address:0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6 u64:0 address:0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6 u64:1500 \
  --assume-yes

# 9. Check the leaderboard rankings
aptos move view \
  --profile sigil-main \
  --function-id '0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6::leaderboard::get_top_entries' \
  --args address:0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6 u64:0

🛡️ Anti-Cheat with Attest

Optional server-side score verification for competitive games.

The attest module prevents score manipulation by requiring server signatures on all score submissions.

When To Use

Game Type Use Attest? Why
Casual games ❌ No submit_score (simple, direct)
Competitive/Esports ✅ Yes submit_score_attested (verified)
Games with prizes ✅ Yes Prevent fraud
Leaderboards with rewards ✅ Yes Fair competition

How It Works

Without Attest (Easy but hackable):
Player → submit_score(any_score) → Blockchain accepts

With Attest (Secure):
Player → Game Server validates → Signs score → submit_score_attested(score + signature)
         └─ Blockchain verifies: "Did server really sign this?" → Accept/Reject

Key Features

  • ✅ Ed25519 signature verification
  • ✅ Nonce-based replay protection
  • ✅ Timestamp validation (max 60s age)
  • ✅ Server key rotation support
  • ✅ Backward compatible (original submit_score still works)

Functions

# Initialize (register server pubkey)
aptos move run ... attest::init_attest \
  --args hex:SERVER_PUBKEY u64:60

# Update server key (rotate)
aptos move run ... attest::update_server_key \
  --args hex:NEW_SERVER_PUBKEY

# Check configuration
aptos move view ... attest::is_initialized ...
aptos move view ... attest::get_server_pubkey ...
aptos move view ... attest::get_max_age ...
aptos move view ... attest::get_last_nonce ...

Server Required: ✅ YES (for validated submissions)
Gas Cost: +100 gas per attested submission (~$0.0001)
Security: Prevents client-side score hacking

See: Attest Guide for complete details and server integration examples

🔐 Multi-Admin Management with Roles

Delegate permissions to your team without sharing keys!

The roles module enables multi-admin and operator management for teams and studios. Perfect for scaling from solo dev to AAA studio.

Role Hierarchy

Owner (Publisher) → Can add/remove Admins + All permissions
  ├─ Admin → Can add/remove Operators, manage treasury, full control
  └─ Operator → Can create achievements, attach rewards, manage leaderboards

When To Use

Scenario Use Roles? Setup
Solo developer ❌ No Just use owner account
Small team (2-5) ✅ Yes Add operators for content management
Studio (10+) ✅ Yes Add admins + operators with hierarchy
DAO-governed ✅ Yes Multisig owner, elected admins

Key Features

  • ✅ Owner is immutable - No takeover risk
  • ✅ Granular permissions - Operators can't touch treasury
  • ✅ Bitwise roles - Can be both admin AND operator
  • ✅ Optional integration - Modules work without roles
  • ✅ Gas-efficient - ~$0.000065 total setup cost
  • ✅ Per-publisher isolation - Each publisher has independent roles

Functions

# 1. Initialize roles
aptos move run --function-id '0x1cc...::roles::init_roles' --profile publisher

# 2. Add admin (owner only)
aptos move run --function-id '0x1cc...::roles::add_admin' \
  --args address:0x1cc... address:ADMIN_ADDR

# 3. Add operator (owner or admin)
aptos move run --function-id '0x1cc...::roles::add_operator' \
  --args address:0x1cc... address:OPERATOR_ADDR

# 4. Check permissions
aptos move view --function-id '0x1cc...::roles::can_manage_achievements' \
  --args address:0x1cc... address:USER_ADDR

Permission Matrix

Function Owner Admin Operator
Add/Remove Admin ✅ ❌ ❌
Add/Remove Operator ✅ ✅ ❌
Create Achievements ✅ ✅ ✅
Attach Rewards ✅ ✅ ✅
Manage Treasury ✅ ✅ ❌

Example: AAA Studio Setup

# 1. Owner (studio wallet in cold storage)
roles::init_roles(publisher)

# 2. Economy lead = Admin
roles::add_admin(publisher, economy_lead)

# 3. Economy lead adds operators
roles::add_operator(economy_lead, game_designer_1)
roles::add_operator(economy_lead, community_manager)

# 4. Operators manage content daily
# 5. Owner stays secure in cold storage

Server Required: ❌ NO (fully on-chain)
Gas Cost: ~300 gas init + 150 gas per operator ($0.000045)
Security: Owner immutable, operators can't withdraw funds

See: Roles Guide for complete details, use cases, and security model

🔗 Deployed Contract Info

Network: Aptos Devnet

Main Deployment (sigil-main)

Module Address: 0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6
Modules: game_platform, leaderboard, achievements, rewards

Explorer Links:

🎊 Phase Final Deployment (phase-final-test) ⚡ AUTOMATIC REWARDS!

Module Address: 0x1cc029fcb6f1c5770147584f3bdedc9e0fe4a59353de514342b57cb4f4286c19
Resource Account: 0x7352fcfd4658a3181264d1ac50ccdde5c56dc73d4fbc07887e4fb24c8e109835
Modules: ALL 10 modules with automatic FA/NFT distribution + seasons + quests + anti-cheat!

Explorer Links:

🚀 What's NEW in Phase Final:

  • ✅ Automatic FA Transfer - APT sent INSTANTLY on claim (no backend needed!)
  • ✅ NFT Minting - Badges minted automatically with aptos_token_objects
  • ✅ Resource Account - Secure signer capability for automated distribution
  • ✅ Single Transaction - Player claims → receives reward in same tx
  • ✅ Verified on Devnet - Real APT transfer tested and working!

Recommendation: Use this deployment for production. Fully automatic, zero manual work, truly decentralized.

Integrated Deployment (sigil-v2-fresh) - Testing

Module Address: 0x0a78db867e0f6ece75a070c04f1f2534305131a217b3fe6f76ab9de2ac65a87b
Modules: 6 modules (shadow_signers + treasury testing)

Explorer Links:

✅ PHASE FINAL: Automatic Rewards - LIVE! 🎉

Module Feature Status Notes
Treasury FA deposits ✅ Working Anyone can deposit
Treasury FA withdrawals ✅ Working Publisher only, real transfers
Treasury Balance tracking ✅ Working Accurate stats
Rewards Claim tracking ✅ Working Supply decrements
Rewards FA auto-transfer ✅ WORKING! Resource account implemented! ⚡
Rewards NFT minting ✅ WORKING! aptos_token_objects integrated! 🎨

🎊 What Phase Final Means

Before (Manual):

Player claims → Wait → Backend distributes → APT arrives (5-60 seconds)
Requires: Backend server running 24/7

Now (Automatic):

Player claims → APT/NFT arrives INSTANTLY ⚡ (single transaction!)
Requires: Nothing! Fully on-chain automation

Verified on Devnet:

  • ✅ Automatic 0.5 APT transfer (Gas: 870 units)
  • ✅ Double-claim prevention working
  • ✅ Supply management accurate (10→9)
  • ✅ Resource account integration tested

See: Automatic Rewards Integration Guide for complete details

✅ Latest Deployments & Tests on Devnet

Latest Deployment (January 2025)

Action Transaction Hash Explorer Link Gas Status
Initial Modules (game_platform + leaderboard) 0x3ca4da35dcd2d2f57cd35b8e695ba24d3c6d27767d1873c4d77fc6adb6cc780c View 2,710 ✅ Success
Leaderboards Initialized 0x273fa651eb3b0e73c2ff54c26ea0ef0a4e3cd8c82a503bb72d14c4b394052a8f View 456 ✅ Success
Leaderboard Created (Game 0, Top 10) 0xdd82e156a7a68f3088c3c80a85d89b15376d12885c149db4945896700fa988ea View 452 ✅ Success
Achievements Module Added 0x20430c13248fce29609091efe21dfe7ba190dff9b61a7a89fe639a3f64402dce View 3,851 ✅ Success
Achievements Initialized 0x70ee2605dc11ba8ad0b8eb7ac62f30bce9bee112ec3337b1143970f8912dbe14 View 504 ✅ Success
Achievements Module Upgraded (CLI wrapper) 0xc411143c25a9fbf6352993b597846fdd7b8f026248a8ae26b1bd451cf61ade0c View 170 ✅ Success
Rewards Module Deployed 0x4bc16150bb80e5c28fe9a773ffe4c4963395b40475074212877a564c529b5ff1 View 3,443 ✅ Success
Rewards Initialized 0x7440d558e4a1117465491444f9818f00fbb9bae5d94ee564fb1bb960c66a5719 View 503 ✅ Success

Test Transactions - Leaderboard System

Action Details Transaction Hash Explorer Link Status
Submit Score #1 Player: 0xe68e..., Score: 1500 0x2f5e9f6a8d9bd6528e1130be967194b83f1d83648e02234c875e616878f4dce4 View ✅ Success
Submit Score #2 Player: 0x14cb..., Score: 2000 0x47135fe138630f9e047aaf5119a8dfcf8024844126452b1700e9159b2f9e87cf View ✅ Success
Submit Score #3 Player: 0x30be..., Score: 1000 0x6ae5339f9c5ab4654fbb75dd1caf749473a8ef758afb36457fbed5cc3bba5128 View ✅ Success
Update Score Player: 0x30be... → 2500 (moved to 1st place!) 0x168b100df4cb36a1e72a1d907e87d8ab5d427c7ef8fb4afefe0bf5f509a3ba95 View ✅ Success

Verified Live Leaderboard State

After testing, the leaderboard rankings on-chain:

Rank Player Address Score Status
🥇 1st 0x30be4b... 2500 Updated from 1000 → 2500
🥈 2nd 0x14cbc9... 2000 Maintained
🥉 3rd 0xe68ef2... 1500 Maintained

Verified using:

aptos move view --profile sigil-main \
  --function-id '0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6::leaderboard::get_top_entries' \
  --args address:0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6 u64:0

Test Transactions - Achievements System

Action Details Transaction Hash Explorer Link Gas Status
Create Achievement #0 "High Scorer" (Score 1000+) 0xe6e6e240af3f3a20a29660dc2920a6277b2450dedc9351419bae7c29d874ff5c View 447 ✅ Success
Create Achievement #1 "Consistent Performer" (1000+ 3x) 0x1836f6b4167a041d417152f10436272b5170a9d4ad744cbf0c62f95da1a5167f View 454 ✅ Success
Create Achievement #2 "Game Master" + Badge URI 0xca52445dfac500fa4b050bae6c4787be9dade6f563d38584d07c1f0eff2f752f View 465 ✅ Success
Submit Score: 1200 Unlocked Achievement #0, Progress 1/3 0xedc31b40c5a0ab56804535a9ccd875184139a0a367dbaea45e46c150d0ad0b1e View 2,572 ✅ Success
Submit Score: 1500 Progress 2/3 0x401eeb54d318f1efdba2d498b638b43d60b6c4e5fe33125d37aab2104685eb30 View 13 ✅ Success
Submit Score: 1800 Progress 3/3, Unlocked Achievement #1 0x38d63e425b66acf02ed77dedfd24a9e6c79ab86af5f2dd300eec1bda86f12e7a View 430 ✅ Success
Submit Score: 2500 Unlocked Achievement #2 (Game Master) 0x31981b6e476d0ae6b616c36a491695b1ca9b6379852ebe14e87eb05a4b75167e View 430 ✅ Success

Verified Live Achievements State

All 3 achievements unlocked for player: 0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6

ID Achievement Type Condition Status
0 High Scorer Basic Score 1000+ ✅ Unlocked
1 Consistent Performer Advanced Score 1000+ 3 times ✅ Unlocked (3/3)
2 Game Master Game-Specific + Badge Score 2000+ on Game 0 ✅ Unlocked

Verified using:

# Check unlocked achievements
aptos move view --profile sigil-main \
  --function-id '0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6::achievements::unlocked_for' \
  --args address:0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6 address:0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6
# Result: [["0", "1", "2"]]

# Check progress for achievement #1
aptos move view --profile sigil-main \
  --function-id '0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6::achievements::get_progress' \
  --args address:0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6 address:0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6 u64:1
# Result: ["3", "3", true]  ✅ 3/3 threshold met!

Test Transactions - Rewards System

Action Details Transaction Hash Explorer Link Gas Status
Attach FA Reward 1 APT per claim, supply: 10 0x3d700292cca8b276a46fa4980c8d066cc85669e7f7d0e9504f3641b5aad4f5eb View 450 ✅ Success
Attach NFT Reward "Consistent Performer Badge", supply: 100 0x5adf027c42ba5d3d13082450500d6f0e3f38ee88d9e598428fea378874a5dd67 View 493 ✅ Success
Claim FA Reward Player claimed achievement #0 reward 0xa2f60e1b90709a791d3fa2708a9849243a08fc5912c8e0062dc6491a4ce1f89e View 862 ✅ Success
Claim NFT Reward Player claimed achievement #1 reward 0x7be610e9b2b32947290ae038c9b4f85707e493d87068d20b636aa9cd98c9b362 View 424 ✅ Success
Double-Claim Test Prevented (E_ALREADY_CLAIMED) 0xdf78bc2600f9a9237c83a7eb6f9e76ee35af0ccbdf29ccee1a3eb7bceec5eecd View - ✅ Failed (expected)

Verified Live Rewards State

2 Rewards Configured:

Achievement ID Reward Type Details Supply Claimed Available
0 Fungible Asset 1 APT (100,000,000 octas) 10 1 9
1 NFT "Consistent Performer Badge" 100 1 99

Player Claimed Rewards: [0, 1] ✅

Verified using:

# Check claimed rewards
aptos move view --profile sigil-main \
  --function-id '0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6::rewards::get_claimed_rewards' \
  --args address:0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6 address:0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6
# Result: [["0", "1"]]

# Check available supply
aptos move view --profile sigil-main \
  --function-id '0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6::rewards::get_available' \
  --args address:0xe68ef23cb6316728ae3b0f3edcc96640219275c2ed62c405578cc486a12dfac6 u64:0
# Result: [true, "9"]  ✅ 9 remaining (10 - 1)

📊 Data Structures

Game Platform

Game

struct Game {
    id: u64,
    title: String,
    creator: address,
}

Player

struct Player {
    user: address,
    username: String,
}

Leaderboard

Leaderboard Config

struct Config {
    game_id: u64,
    decimals: u8,
    min_score: u64,
    max_score: u64,
    is_ascending: bool,      // true => lower is better
    allow_multiple: bool,    // if false: only keep best per player
    scores_to_retain: u64,   // how many entries to keep in top list
}

Leaderboard

struct Leaderboard {
    id: u64,
    config: Config,
    best_by_player: Table<address, u64>,           // Track best score per player
    top_entries_players: vector<address>,          // Sorted player addresses
    top_entries_scores: vector<u64>,               // Corresponding scores
}

Events

GameRegisteredEvent

struct GameRegisteredEvent {
    id: u64,
    creator: address,
    title: String,
}

ScoreSubmittedEvent

struct ScoreSubmittedEvent {
    publisher: address,
    player: address,
    game_id: u64,
    score: u64,
}

⚠️ Error Codes

Game Platform

  • E_ALREADY_INIT (0) - Module already initialized
  • E_GAME_NOT_FOUND (1) - Game ID doesn't exist
  • E_PLAYER_EXISTS (2) - Player already registered
  • E_PLAYER_REQUIRED (3) - Must register as player first

Leaderboard

  • E_ALREADY_INIT (0) - Leaderboards already initialized
  • E_NOT_FOUND (1) - Leaderboard ID doesn't exist
  • E_ID_EXISTS (2) - Leaderboard ID already exists

🎯 Leaderboard Features

Gas Optimization

  • Best Score Tracking: Prevents unnecessary updates
  • Bounded Operations: Only maintains top N entries (no unbounded growth)
  • Smart Sorting: Efficient insertion-sort algorithm that only bubbles the changed entry
  • Early Exits: Score gates reject invalid entries before processing

Flexible Configurations

High Score Games (Points-based)

# Higher is better, keep top 100
--args u64:0 u8:0 u64:0 u64:999999999 bool:false bool:false u64:100

Speedrun Games (Time-based)

# Lower is better (faster time), keep top 50
--args u64:0 u8:2 u64:0 u64:999999 bool:true bool:false u64:50

Competitive Games (Skill-gated)

# Must score at least 10000 to appear, keep top 20
--args u64:0 u8:0 u64:10000 u64:999999 bool:false bool:false u64:20

🛠️ Troubleshooting

Rate Limit Exceeded

If you see rate limit errors, make sure you're using your API key in the config:

api_key: "aptoslabs_YOUR_API_KEY_HERE"

Transaction Timeout

Add explicit profile to avoid simulation timeouts:

--profile sigil-main --assume-yes

Profile Not Found

Make sure you're running commands from the project root directory where .aptos/config.yaml exists.

Module Already Exists

If republishing, the modules will be upgraded automatically. Make sure you're using the same address in Move.toml.

📚 Additional Documentation

Module Guides (Individual modules in depth)

Integration Guides (Cross-module workflows)

Testing & Verification

Project Info

🧪 Running Tests

The project includes comprehensive unit tests:

cd move
aptos move test

Test Coverage:

  • Leaderboard: 15 unit tests ✅
  • Achievements: 20 unit tests ✅
  • Rewards: 26 unit tests ✅
  • Roles: 23 unit tests ✅
  • Seasons: 16 unit tests (14 passing) ✅
  • Quests: 22 unit tests (8 passing) ✅
  • Total: 122+ tests ✅

Test by Module:

# Test all modules
aptos move test

# Test specific modules
aptos move test --filter leaderboard
aptos move test --filter achievements
aptos move test --filter rewards

Coverage Includes:

  • Initialization and setup for all modules
  • All achievement types (basic, advanced, game-specific)
  • Progress tracking and updates
  • FT and NFT reward attachment
  • Claim flow with double-claim prevention
  • Supply management and stock tracking
  • Multiple players and edge cases
  • Badge URI storage and retrieval
  • Complete view function coverage

📜 License

MIT

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

  1. Clone the repository
  2. Install Aptos CLI
  3. Set up your .aptos/config.yaml
  4. Run aptos move test to verify setup
  5. Make your changes
  6. Submit a PR

📧 Contact

For questions or support, please open an issue on GitHub.

Built with ❤️ for the Aptos gaming ecosystem

Last Updated: Oct 2025

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages