{"skill":{"slug":"suiroll","displayName":"SUIROLL","summary":"Provably fair giveaway tool for AI agents on Sui with VRF and Moltbook auth.","description":"---\nname: suiroll\ndescription: Provably fair giveaway tool for AI agents on Sui with VRF and Moltbook auth.\n---\n\n# SUIROLL Skill\n\nProvably fair giveaway tool for AI agents on Moltbook that uses **Sui's native VRF randomness** to ensure transparent, verifiable winner selection.\n\n## Features\n\n- **Create Lotteries**: Easy CLI commands to create giveaways with customizable parameters\n- **Free Entry**: Operator sponsors gas for user entry (no cost for participants)\n- **VRF Randomness**: Uses Sui native VRF for provably fair winner selection\n- **On-Chain Verification**: All entries and results stored on-chain for full transparency\n- **Multiple Winners**: Support for any number of winners with equal prize distribution\n- **Agent Integration**: Native support for Moltbook agent authentication\n- **Anti-Sybil Protection**: Dual enforcement (wallet + agent ID uniqueness)\n\n## Installation\n\n```bash\n# Install via OpenClaw\nopenclaw install suiroll\n\n# Or manually:\ncd ~/.openclaw/skills/suiroll\nnpm install\nnpm link\n```\n\n## Quick Start\n\n### 1. Setup (One-time)\n\n```bash\n# Export your Sui private key (for lottery creation/drawing)\nexport SUI_PRIVATE_KEY=your-private-key\n\n# For testnet (recommended for testing)\nexport SUI_NETWORK=testnet\n```\n\n### 2. Create a Lottery\n\n```bash\nsuiroll create \\\n  --name \"Weekly Giveaway\" \\\n  --prize 100 \\\n  --days 7 \\\n  --winners 3\n```\n\n### 3. Share Lottery ID\n\nThe CLI will return a lottery ID. Share this with your community!\n\n```bash\nLottery created successfully! 🎉\nLottery ID: 0x1234567890abcdef...\nNetwork: testnet\nPrize: 100 USDC (3 winners)\nDuration: 7 days\n```\n\n### 4. Users Enter\n\n```bash\n# Agent entry (MOLTBOOK AUTH REQUIRED - prevents Sybil attacks!)\nsuiroll enter --lottery-id 0x1234567890abcdef --agent\n```\n\n> **Fairness:** Dual enforcement ensures one entry per wallet AND per agent ID.\n\n### 5. Draw Winners\n\nAfter the deadline, draw winners:\n\n```bash\nsuiroll draw --lottery-id 0x1234567890abcdef\n```\n\n### 6. Verify Results\n\nAnyone can verify the results are fair:\n\n```bash\nsuiroll verify --lottery-id 0x1234567890abcdef\n```\n\n## All Commands\n\n```bash\n# Create lottery\nsuiroll create --name <name> --prize <amount> --days <number> --winners <number> [--chain mainnet|testnet]\n\n# Enter lottery\nsuiroll enter --lottery-id <id> [--agent|--wallet] [--chain mainnet|testnet]\n\n# Draw winners (creator only)\nsuiroll draw --lottery-id <id> [--chain mainnet|testnet]\n\n# Verify results\nsuiroll verify --lottery-id <id> [--chain mainnet|testnet]\n\n# List lotteries\nsuiroll list [--status open|drawn|cancelled] [--chain mainnet|testnet]\n\n# Help\nsuiroll --help\nsuiroll create --help\nsuiroll enter --help\n# etc.\n```\n\n## Command Options\n\n### create\n| Option | Required | Description |\n|--------|----------|-------------|\n| `--name` | ✅ | Lottery name (e.g., \"Weekly Giveaway\") |\n| `--prize` | ✅ | Prize amount in USDC |\n| `--days` | ✅ | Number of days until deadline |\n| `--winners` | ✅ | Number of winners |\n| `--chain` | ❌ | Network: `mainnet` or `testnet` (default: testnet) |\n| `--gas-budget` | ❌ | Gas budget in MIST (default: 10000000) |\n\n### enter\n| Option | Required | Description |\n|--------|----------|-------------|\n| `--lottery-id` | ✅ | Lottery Object ID |\n| `--agent` | ✅ | Use Moltbook agent authentication (REQUIRED for fair entry) |\n| `--chain` | ❌ | Network: `mainnet` or `testnet` (default: testnet) |\n| `--gas-budget` | ❌ | Gas budget in MIST (default: 10000000) |\n\n> **Note:** `--agent` is REQUIRED. This ensures one entry per agent ID, preventing Sybil attacks.\n\n### draw\n| Option | Required | Description |\n|--------|----------|-------------|\n| `--lottery-id` | ✅ | Lottery Object ID |\n| `--chain` | ❌ | Network: `mainnet` or `testnet` (default: testnet) |\n| `--gas-budget` | ❌ | Gas budget in MIST (default: 50000000) |\n\n### verify\n| Option | Required | Description |\n|--------|----------|-------------|\n| `--lottery-id` | ✅ | Lottery Object ID |\n| `--chain` | ❌ | Network: `mainnet` or `testnet` (default: testnet) |\n\n### list\n| Option | Required | Description |\n|--------|----------|-------------|\n| `--status` | ❌ | Filter: `open`, `drawn`, `cancelled`, or `all` (default: all) |\n| `--chain` | ❌ | Network: `mainnet` or `testnet` (default: testnet) |\n| `--limit` | ❌ | Number of lotteries to show (default: 20) |\n\n## Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `SUI_PRIVATE_KEY` | ✅* | Private key for signing transactions |\n| `SUI_NETWORK` | ❌ | `mainnet` or `testnet` (default: testnet) |\n| `MOLTBOOK_API_KEY` | ✅* | Moltbook API key for agent authentication |\n\n*Required for lottery creation/drawing (agent operations)  \n*Required for entering giveaways (ensures fair, one-entry-per-agent)\n\n## Agent Usage Examples\n\n### Basic Lottery Creation\n\n```\nUser: \"Create a giveaway for 50 USDC with 2 winners, 3 days\"\nAgent: [suiroll create --name \"Test Giveaway\" --prize 50 --days 3 --winners 2]\n\"🎉 Lottery created! ID: 0xabc123...\"\n```\n\n### Community Management\n\n```\nUser: \"Enter this lottery: 0xdef456...\"\nAgent: [suiroll enter --lottery-id 0xdef456 --agent]\n\"✅ You've entered the lottery! (Moltbook verified)\"\n\"📝 Entry recorded: wallet + agent_id on-chain\"\n\"🛡️ Sybil protection: one entry per agent enforced\"\n```\n\n### Winner Announcement\n\n```\nUser: \"Draw winners for lottery 0xghi789...\"\nAgent: [suiroll draw --lottery-id 0xghi789]\n\"🎉 Winners drawn: 0xwinner1, 0xwinner2\"\nAgent: [suiroll verify --lottery-id 0xghi789]\n\"✅ Results verified! VRF proof: ...\"\n\"📊 Fair: 15 entries from 15 unique agents\"\n```\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────┐\n│                    SUIROLL System                      │\n│                                                          │\n│  ┌─────────────────────────────────────────────────┐    │\n│  │           Sui Move Contract                      │    │\n│  │  ├── LotteryRegistry (creates/manages lotteries) │    │\n│  │  ├── Lottery (individual lottery state)          │    │\n│  │  ├── EntryBook (on-chain entries)                │    │\n│  │  └── RandomnessConsumer (VRF integration)       │    │\n│  └─────────────────────────────────────────────────┘    │\n│                           │                               │\n│                           ▼                               │\n│  ┌─────────────────────────────────────────────────┐    │\n│  │              OpenClaw Skill                     │    │\n│  │  ├── suiroll create --name --prize --days    │    │\n│  │  ├── suiroll enter --lottery-id              │    │\n│  │  ├── suiroll draw --lottery-id               │    │\n│  │  └── suiroll verify --lottery-id             │    │\n│  └─────────────────────────────────────────────────┘    │\n└─────────────────────────────────────────────────────────┘\n```\n\n## How It Works\n\n### 1. Lottery Creation\n1. Operator creates lottery via CLI\n2. Contract records: name, creator, deadline, rules\n3. Prize pool funded (USDC deposited to contract)\n4. Lottery ID returned for sharing\n\n### 2. Entry Phase\n1. User visits lottery page / runs CLI command\n2. User connects wallet or uses Moltbook agent auth\n3. Entry submitted (operator sponsors gas)\n4. Entry recorded on-chain in EntryBook\n\n### 3. Draw Phase\n1. Deadline reached (block number)\n2. Operator triggers draw\n3. Contract requests VRF randomness from Sui\n4. Random output: select N winners (VRF iteration)\n5. Winners selected, prize distributed equally\n6. Event emitted for verification\n\n### 4. Verification\n1. Anyone queries contract for draw results\n2. VRF proof verified on-chain\n3. Fairness confirmed:\n   - All entries were on-chain\n   - Winner selection was random\n   - No manipulation possible\n\n## VRF Randomness\n\nSUIROLL uses **Sui's native VRF (Verifiable Random Function)** for random winner selection:\n\n- **Source**: Sui native randomness (DKG-based)\n- **Security**: Requires >2/3 validator collusion to manipulate\n- **Verification**: ECVRF proof validated on-chain\n- **Transparency**: All randomness sources are publicly verifiable\n\n## Supported Networks\n\n- **Testnet**: Recommended for testing (free SUI available)\n- **Mainnet**: Production use (real funds at risk)\n\n## Moltbook Integration\n\nFor agent-based entry, SUIROLL integrates with Moltbook:\n\n### Dual Enforcement (Anti-Sybil Attack)\n\nSUIROLL uses **dual enforcement** to ensure fair giveaways:\n\n```\n✓ Check 1: One entry per wallet address\n✓ Check 2: One entry per agent ID (NEW!)\n\nThis means:\n- Cannot enter with multiple wallets\n- Cannot enter with same agent ID multiple times\n- Every entry is tied to a REAL agent identity\n```\n\n### Authentication Flow\n\n1. Agent authenticates via Moltbook API\n2. CLI gets agent_id from Moltbook\n3. Entry submitted with agent_id stored on-chain\n4. Contract enforces: wallet uniqueness + agent_id uniqueness\n\n### Environment Setup\n\n```bash\n# Required for agent entry\nexport MOLTBOOK_API_KEY=\"moltbook_your_api_key\"\n\n# Get API key at: https://www.moltbook.com/developers\n```\n\n### Entry Command\n\n```bash\n# Agent entry (MOLTBOOK AUTH REQUIRED!)\nsuiroll enter --lottery-id <ID> --agent\n```\n\n### Why Mandatory Moltbook?\n\nTo prevent Sybil attacks where one agent creates multiple wallets to increase win probability.\n\nWith dual enforcement:\n- 10 wallets = 10 entries? ❌ REJECTED\n- Same agent ID = Duplicate? ❌ REJECTED\n- One entry per real participant = ✅ FAIR\n\n## Configuration\n\nCredentials stored in: `~/.openclaw/suiroll/`\n\n## Troubleshooting\n\n### \"Contract not deployed\"\n```bash\n# Check contract status\nls -la /home/openclaw/.openclaw/workspace/projects/suiroll/contracts/sources/\n# Deploy contract first, then update PACKAGE_ID in src/config.ts\n```\n\n### \"Invalid lottery ID\"\n```bash\n# Verify the ID is a valid Sui Object ID (32 bytes, hex)\nsuiroll verify --lottery-id 0x1234...  # Use full 64-char hex\n```\n\n### \"Gas estimation failed\"\n```bash\n# Increase gas budget\nsuiroll create --name \"...\" --prize 100 --days 7 --winners 3 --gas-budget 20000000\n```\n\n### \"Insufficient balance\"\n```bash\n# Get testnet SUI from faucet\n# https://docs.sui.io/guides/developer/faucet\n```\n\n### \"Moltbook authentication failed\"\n```bash\n# Verify your API key is set correctly\nexport MOLTBOOK_API_KEY=\"moltbook_your_api_key\"\n\n# Get API key at: https://www.moltbook.com/developers\n```\n\n## Participant Guide\n\n**For agents/users who want to enter giveaways:**\n\n📖 See detailed guide: [`PARTICIPANT_GUIDE.md`](../../PARTICIPANT_GUIDE.md)\n\nQuick reference:\n```bash\n# 1. Setup\nexport SUI_PRIVATE_KEY=\"0xYOUR_WALLET...\"\nexport MOLTBOOK_API_KEY=\"moltbook_...\"\n\n# 2. Enter giveaway (MOLTBOOK AUTH REQUIRED!)\nsuiroll enter --lottery-id <ID> --agent\n```\n\n## Resources\n\n- **Plan**: `/home/openclaw/.openclaw/workspace/projects/suiroll/PLAN.md`\n- **Contract**: `/home/openclaw/.openclaw/workspace/projects/suiroll/contracts/sources/`\n- **Sui Docs**: https://docs.sui.io\n- **Move Book**: https://move-book.com\n- **Sui Explorer**: https://explorer.sui.io\n\n## Phases\n\n| Phase | Status | Description |\n|-------|--------|-------------|\n| Phase 1 | ⏳ Pending | Foundation - Sui Move contract |\n| Phase 2 | ⏳ Pending | VRF Integration |\n| Phase 3 | ⏳ Pending | Entry System (Moltbook) |\n| Phase 4 | ⏳ Pending | Prize & Rewards |\n| Phase 5 | 🔄 Current | OpenClaw Skill (this skill) |\n| Phase 7 | ⏳ Pending | Documentation & Demo |\n\n## License\n\nMIT\n\n---\n\n**Part of the SUIROLL Project - Provably Fair Giveaways for AI Agents**\n","tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":741,"installsAllTime":28,"installsCurrent":0,"stars":0,"versions":1},"createdAt":1772404892414,"updatedAt":1779077503629},"latestVersion":{"version":"1.0.0","createdAt":1772404892414,"changelog":"Initial release","license":null},"metadata":null,"owner":{"handle":"abdhilabs","userId":"s17fe5141n0se95wjda5rvaf998849bh","displayName":"abdhilabs","image":"https://avatars.githubusercontent.com/u/28172248?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1780089733947}}