🌌 StacksOne Vault Ecosystem

StacksOne Vault is a modular gamified Web3 identity and progression protocol built on the Stacks blockchain.

It enables users to:

• Complete on-chain missions
• Earn Experience Points (XP)
• Level up
• Mint exclusive SIP-009 NFT badges
• Accumulate competitive leaderboard score
• Engage in modular game extensions

Fully verifiable on-chain.

🔒 Production-grade Clarity contracts
🧠 Modular multi-layer architecture
✅ Automated test suite (Vitest + Clarinet Simnet)
🚀 GitHub Actions CI enabled

---

🏗️ Architecture Overview (v10 + Modular Expansion)

StacksOne Vault utilizes a scalable multi-contract architecture designed for modularity, upgrade safety, and progressive ecosystem growth.

---

🧠 Core Layer

1️⃣ genesis-core-v10.clar — The Brain

• Manages user XP & Level state
• Routes mission completion
• Handles badge claims
• Computes dynamic level progression

level = (XP / 500) + 1

---

2️⃣ genesis-missions-v10.clar — The Tracker

• Enforces 144 block-height cooldown for daily check-in
• Prevents duplicate mission claims
• Accepts write calls only from authorized Core contract

---

3️⃣ genesis-badges-v10.clar — The Vault

• Fully SIP-009 compliant NFT contract
• On-chain metadata URI (IPFS)
• Minting restricted to authorized Core contract only

---

🏆 Aggregation Layer — Leaderboard Engine (NEW)

genesis-leaderboard-v1.clar — On-Chain Ranking Module

Lightweight aggregation contract designed to track engagement across modules.

Features:

• Gas-efficient score accumulation
• Rank tier calculation
• Stateless read logic
• Event logging for interaction tracking

Functions:

• add-score(uint)
• get-score(principal)
• get-rank-tier(principal)
• reset-season()

Rank Tiers:

Tier	Score Requirement
0	< 100
1	≥ 100
2	≥ 500
3	≥ 1000

This module integrates with game interactions to create a persistent competitive layer.

---

🎮 Engagement Layer (Modular Add-ons)

StacksOne includes lightweight independent engagement contracts.

---

🎲 genesis-lucky-v1.clar — Lucky Draw

• On-chain roll counter
• Ultra-low gas interaction
• Engagement loop module

Functions:

• roll()
• get-rolls(principal)

---

⚔️ genesis-duel-v1.clar — Duel Arena

• Combat score counter
• Stateless increment logic

Functions:

• fight()
• get-score(principal)

---

🔢 genesis-predict-v1.clar — Prediction Room

• On-chain number submission
• Minimal write storage

Functions:

• predict(uint)
• get-prediction(principal)

---

🔥 Boost Layer

genesis-boost-v1.clar — XP Lock & Multiplier

Progression enhancement contract.

Features:

• Lock XP simulation
• Boost multiplier storage
• Unlock reset logic
• Gas-efficient state updates

Functions:

• lock-xp(uint)
• unlock-xp()
• get-locked(principal)
• get-boost(principal)

---

🪙 Token Layer — SIP-010

token-one.clar

StacksOne includes a SIP-010 fungible token implementation.

Features:

• Owner-controlled minting
• Approved minter system
• Transfer validation
• Strict zero-amount validation

Fully tested via automated suite.

---

🔐 Dual-Authorization Security Model

Supporting contracts implement a dual-authorization upgrade-safe structure.

admin (Principal)

• Deployer wallet
• Permanent authority
• Can re-route ecosystem to new Core contract

Functions:

• transfer-admin
• set-game-core

game-core-address (Principal)

• Current operational Core contract
• Authorized to mint NFTs and modify XP

Ensures:

• No contract lockout
• Safe upgradability
• Long-term protocol resilience

---

🧩 Modular Ecosystem Overview

StacksOne operates as a layered ecosystem:

Core Layer

• XP & Level engine
• Mission routing
• Badge gating

Identity Layer

• SIP-009 NFT badge vault

Token Layer

• SIP-010 fungible token

Engagement Layer

• Lucky Draw
• Duel Arena
• Prediction Room

Boost Layer

• XP Multiplier

Aggregation Layer

• On-chain Leaderboard
• Rank Tier System

---

🧪 Automated Testing & CI

Complete smart contract testing suite included.

✔ Vitest + Clarinet Simnet

• Metadata validation
• Mint authorization tests
• Transfer logic tests
• Security edge cases

✔ GitHub Actions CI

• Automated test execution on every push
• Node 18 runner
• Clean install per job

Run locally:

cd smart-contracts
npm install
npm run test

---

✨ Key Features

📅 Daily On-Chain Check-In

Earn base XP with enforced cooldown.

🎯 Mission Board

Dynamic tasks for protocol interaction.

📈 Level Progression

XP auto-converts to Levels.

🏅 NFT Badge Gating

Badge	Requirement
Genesis Pioneer	Level 1
Node Operator	Level 2 (500 XP) + Genesis
Protocol Guardian	Level 5 (2000 XP) + Node

🏆 On-Chain Leaderboard

Competitive scoring across all engagement modules.

---

🚀 Deployment Guide (Mainnet)

Generate Deployment Plan

clarinet deployments generate --mainnet --low-cost
clarinet deployments apply --mainnet

Contract Wiring (Critical)

From admin wallet:

In genesis-badges-v10

Call:

set-game-core
'<YOUR_WALLET>.genesis-core-v10

In genesis-missions-v10

Call:

set-game-core
'<YOUR_WALLET>.genesis-core-v10

---

🌐 Live Mainnet Contracts

Deployer: SP3GHKMV4GSYNA8WGBX83DACG80K1RRVQZAZMB9J3

Core:

• genesis-core-v10

Missions:

• genesis-missions-v10

Badges:

• genesis-badges-v10

Token:

• token-one

Reputation:

• reputation-engine

Boost:

• genesis-boost-v1

Leaderboard:

• genesis-leaderboard-v1

Games:

• genesis-lucky-v1
• genesis-duel-v1
• genesis-predict-v1

---

🖥️ Frontend Stack

• React (Vite)
• TailwindCSS
• Framer Motion
• @stacks/connect
• @stacks/transactions
• Supabase (off-chain caching layer)

---

📊 Engineering Maturity Signals

• Modular contract design
• Upgrade-safe architecture
• SIP-009 + SIP-010 compliance
• Aggregation & ranking layer
• Automated testing suite
• CI/CD enabled
• Multi-contract mainnet deployment
• Continuous ecosystem iteration

---

👨‍💻 Author

Developed by Bayu Benjamin

GitHub: https://github.com/bayyubenjamin
Ecosystem: Stacks / Web3 Builder