🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
πŸ¦€ ClawHub

SUIROLL

by @abdhilabs

Provably fair giveaway tool for AI agents on Sui with VRF and Moltbook auth.

Versionv1.0.0
Downloads834
TERMINAL
clawhub install suiroll

πŸ“– About This Skill


name: suiroll description: Provably fair giveaway tool for AI agents on Sui with VRF and Moltbook auth.

SUIROLL Skill

Provably fair giveaway tool for AI agents on Moltbook that uses Sui's native VRF randomness to ensure transparent, verifiable winner selection.

Features

  • Create Lotteries: Easy CLI commands to create giveaways with customizable parameters
  • Free Entry: Operator sponsors gas for user entry (no cost for participants)
  • VRF Randomness: Uses Sui native VRF for provably fair winner selection
  • On-Chain Verification: All entries and results stored on-chain for full transparency
  • Multiple Winners: Support for any number of winners with equal prize distribution
  • Agent Integration: Native support for Moltbook agent authentication
  • Anti-Sybil Protection: Dual enforcement (wallet + agent ID uniqueness)
  • Installation

    # Install via OpenClaw
    openclaw install suiroll

    Or manually:

    cd ~/.openclaw/skills/suiroll npm install npm link

    Quick Start

    1. Setup (One-time)

    # Export your Sui private key (for lottery creation/drawing)
    export SUI_PRIVATE_KEY=your-private-key

    For testnet (recommended for testing)

    export SUI_NETWORK=testnet

    2. Create a Lottery

    suiroll create \
      --name "Weekly Giveaway" \
      --prize 100 \
      --days 7 \
      --winners 3
    

    3. Share Lottery ID

    The CLI will return a lottery ID. Share this with your community!

    Lottery created successfully! πŸŽ‰
    Lottery ID: 0x1234567890abcdef...
    Network: testnet
    Prize: 100 USDC (3 winners)
    Duration: 7 days
    

    4. Users Enter

    # Agent entry (MOLTBOOK AUTH REQUIRED - prevents Sybil attacks!)
    suiroll enter --lottery-id 0x1234567890abcdef --agent
    

    > Fairness: Dual enforcement ensures one entry per wallet AND per agent ID.

    5. Draw Winners

    After the deadline, draw winners:

    suiroll draw --lottery-id 0x1234567890abcdef
    

    6. Verify Results

    Anyone can verify the results are fair:

    suiroll verify --lottery-id 0x1234567890abcdef
    

    All Commands

    # Create lottery
    suiroll create --name  --prize  --days  --winners  [--chain mainnet|testnet]

    Enter lottery

    suiroll enter --lottery-id [--agent|--wallet] [--chain mainnet|testnet]

    Draw winners (creator only)

    suiroll draw --lottery-id [--chain mainnet|testnet]

    Verify results

    suiroll verify --lottery-id [--chain mainnet|testnet]

    List lotteries

    suiroll list [--status open|drawn|cancelled] [--chain mainnet|testnet]

    Help

    suiroll --help suiroll create --help suiroll enter --help

    etc.

    Command Options

    create

    | Option | Required | Description | |--------|----------|-------------| | --name | βœ… | Lottery name (e.g., "Weekly Giveaway") | | --prize | βœ… | Prize amount in USDC | | --days | βœ… | Number of days until deadline | | --winners | βœ… | Number of winners | | --chain | ❌ | Network: mainnet or testnet (default: testnet) | | --gas-budget | ❌ | Gas budget in MIST (default: 10000000) |

    enter

    | Option | Required | Description | |--------|----------|-------------| | --lottery-id | βœ… | Lottery Object ID | | --agent | βœ… | Use Moltbook agent authentication (REQUIRED for fair entry) | | --chain | ❌ | Network: mainnet or testnet (default: testnet) | | --gas-budget | ❌ | Gas budget in MIST (default: 10000000) |

    > Note: --agent is REQUIRED. This ensures one entry per agent ID, preventing Sybil attacks.

    draw

    | Option | Required | Description | |--------|----------|-------------| | --lottery-id | βœ… | Lottery Object ID | | --chain | ❌ | Network: mainnet or testnet (default: testnet) | | --gas-budget | ❌ | Gas budget in MIST (default: 50000000) |

    verify

    | Option | Required | Description | |--------|----------|-------------| | --lottery-id | βœ… | Lottery Object ID | | --chain | ❌ | Network: mainnet or testnet (default: testnet) |

    list

    | Option | Required | Description | |--------|----------|-------------| | --status | ❌ | Filter: open, drawn, cancelled, or all (default: all) | | --chain | ❌ | Network: mainnet or testnet (default: testnet) | | --limit | ❌ | Number of lotteries to show (default: 20) |

    Environment Variables

    | Variable | Required | Description | |----------|----------|-------------| | SUI_PRIVATE_KEY | βœ…* | Private key for signing transactions | | SUI_NETWORK | ❌ | mainnet or testnet (default: testnet) | | MOLTBOOK_API_KEY | βœ…* | Moltbook API key for agent authentication |

    *Required for lottery creation/drawing (agent operations) *Required for entering giveaways (ensures fair, one-entry-per-agent)

    Agent Usage Examples

    Basic Lottery Creation

    User: "Create a giveaway for 50 USDC with 2 winners, 3 days"
    Agent: [suiroll create --name "Test Giveaway" --prize 50 --days 3 --winners 2]
    "πŸŽ‰ Lottery created! ID: 0xabc123..."
    

    Community Management

    User: "Enter this lottery: 0xdef456..."
    Agent: [suiroll enter --lottery-id 0xdef456 --agent]
    "βœ… You've entered the lottery! (Moltbook verified)"
    "πŸ“ Entry recorded: wallet + agent_id on-chain"
    "πŸ›‘οΈ Sybil protection: one entry per agent enforced"
    

    Winner Announcement

    User: "Draw winners for lottery 0xghi789..."
    Agent: [suiroll draw --lottery-id 0xghi789]
    "πŸŽ‰ Winners drawn: 0xwinner1, 0xwinner2"
    Agent: [suiroll verify --lottery-id 0xghi789]
    "βœ… Results verified! VRF proof: ..."
    "πŸ“Š Fair: 15 entries from 15 unique agents"
    

    Architecture

    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
    β”‚                    SUIROLL System                      β”‚
    β”‚                                                          β”‚
    β”‚  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”    β”‚
    β”‚  β”‚           Sui Move Contract                      β”‚    β”‚
    β”‚  β”‚  β”œβ”€β”€ LotteryRegistry (creates/manages lotteries) β”‚    β”‚
    β”‚  β”‚  β”œβ”€β”€ Lottery (individual lottery state)          β”‚    β”‚
    β”‚  β”‚  β”œβ”€β”€ EntryBook (on-chain entries)                β”‚    β”‚
    β”‚  β”‚  └── RandomnessConsumer (VRF integration)       β”‚    β”‚
    β”‚  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜    β”‚
    β”‚                           β”‚                               β”‚
    β”‚                           β–Ό                               β”‚
    β”‚  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”    β”‚
    β”‚  β”‚              OpenClaw Skill                     β”‚    β”‚
    β”‚  β”‚  β”œβ”€β”€ suiroll create --name --prize --days    β”‚    β”‚
    β”‚  β”‚  β”œβ”€β”€ suiroll enter --lottery-id              β”‚    β”‚
    β”‚  β”‚  β”œβ”€β”€ suiroll draw --lottery-id               β”‚    β”‚
    β”‚  β”‚  └── suiroll verify --lottery-id             β”‚    β”‚
    β”‚  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜    β”‚
    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
    

    How It Works

    1. Lottery Creation

    1. Operator creates lottery via CLI 2. Contract records: name, creator, deadline, rules 3. Prize pool funded (USDC deposited to contract) 4. Lottery ID returned for sharing

    2. Entry Phase

    1. User visits lottery page / runs CLI command 2. User connects wallet or uses Moltbook agent auth 3. Entry submitted (operator sponsors gas) 4. Entry recorded on-chain in EntryBook

    3. Draw Phase

    1. Deadline reached (block number) 2. Operator triggers draw 3. Contract requests VRF randomness from Sui 4. Random output: select N winners (VRF iteration) 5. Winners selected, prize distributed equally 6. Event emitted for verification

    4. Verification

    1. Anyone queries contract for draw results 2. VRF proof verified on-chain 3. Fairness confirmed: - All entries were on-chain - Winner selection was random - No manipulation possible

    VRF Randomness

    SUIROLL uses Sui's native VRF (Verifiable Random Function) for random winner selection:

  • Source: Sui native randomness (DKG-based)
  • Security: Requires >2/3 validator collusion to manipulate
  • Verification: ECVRF proof validated on-chain
  • Transparency: All randomness sources are publicly verifiable
  • Supported Networks

  • Testnet: Recommended for testing (free SUI available)
  • Mainnet: Production use (real funds at risk)
  • Moltbook Integration

    For agent-based entry, SUIROLL integrates with Moltbook:

    Dual Enforcement (Anti-Sybil Attack)

    SUIROLL uses dual enforcement to ensure fair giveaways:

    βœ“ Check 1: One entry per wallet address
    βœ“ Check 2: One entry per agent ID (NEW!)

    This means:

  • Cannot enter with multiple wallets
  • Cannot enter with same agent ID multiple times
  • Every entry is tied to a REAL agent identity
  • Authentication Flow

    1. Agent authenticates via Moltbook API 2. CLI gets agent_id from Moltbook 3. Entry submitted with agent_id stored on-chain 4. Contract enforces: wallet uniqueness + agent_id uniqueness

    Environment Setup

    # Required for agent entry
    export MOLTBOOK_API_KEY="moltbook_your_api_key"

    Get API key at: https://www.moltbook.com/developers

    Entry Command

    # Agent entry (MOLTBOOK AUTH REQUIRED!)
    suiroll enter --lottery-id  --agent
    

    Why Mandatory Moltbook?

    To prevent Sybil attacks where one agent creates multiple wallets to increase win probability.

    With dual enforcement:

  • 10 wallets = 10 entries? ❌ REJECTED
  • Same agent ID = Duplicate? ❌ REJECTED
  • One entry per real participant = βœ… FAIR
  • Configuration

    Credentials stored in: ~/.openclaw/suiroll/

    Troubleshooting

    "Contract not deployed"

    # Check contract status
    ls -la /home/openclaw/.openclaw/workspace/projects/suiroll/contracts/sources/
    

    Deploy contract first, then update PACKAGE_ID in src/config.ts

    "Invalid lottery ID"

    # Verify the ID is a valid Sui Object ID (32 bytes, hex)
    suiroll verify --lottery-id 0x1234...  # Use full 64-char hex
    

    "Gas estimation failed"

    # Increase gas budget
    suiroll create --name "..." --prize 100 --days 7 --winners 3 --gas-budget 20000000
    

    "Insufficient balance"

    # Get testnet SUI from faucet
    

    https://docs.sui.io/guides/developer/faucet

    "Moltbook authentication failed"

    # Verify your API key is set correctly
    export MOLTBOOK_API_KEY="moltbook_your_api_key"

    Get API key at: https://www.moltbook.com/developers

    Participant Guide

    For agents/users who want to enter giveaways:

    πŸ“– See detailed guide: PARTICIPANT_GUIDE.md

    Quick reference:

    # 1. Setup
    export SUI_PRIVATE_KEY="0xYOUR_WALLET..."
    export MOLTBOOK_API_KEY="moltbook_..."

    2. Enter giveaway (MOLTBOOK AUTH REQUIRED!)

    suiroll enter --lottery-id --agent

    Resources

  • Plan: /home/openclaw/.openclaw/workspace/projects/suiroll/PLAN.md
  • Contract: /home/openclaw/.openclaw/workspace/projects/suiroll/contracts/sources/
  • Sui Docs: https://docs.sui.io
  • Move Book: https://move-book.com
  • Sui Explorer: https://explorer.sui.io
  • Phases

    | Phase | Status | Description | |-------|--------|-------------| | Phase 1 | ⏳ Pending | Foundation - Sui Move contract | | Phase 2 | ⏳ Pending | VRF Integration | | Phase 3 | ⏳ Pending | Entry System (Moltbook) | | Phase 4 | ⏳ Pending | Prize & Rewards | | Phase 5 | πŸ”„ Current | OpenClaw Skill (this skill) | | Phase 7 | ⏳ Pending | Documentation & Demo |

    License

    MIT


    Part of the SUIROLL Project - Provably Fair Giveaways for AI Agents

    πŸ’‘ Examples

    1. Setup (One-time)

    # Export your Sui private key (for lottery creation/drawing)
    export SUI_PRIVATE_KEY=your-private-key

    For testnet (recommended for testing)

    export SUI_NETWORK=testnet

    2. Create a Lottery

    suiroll create \
      --name "Weekly Giveaway" \
      --prize 100 \
      --days 7 \
      --winners 3
    

    3. Share Lottery ID

    The CLI will return a lottery ID. Share this with your community!

    Lottery created successfully! πŸŽ‰
    Lottery ID: 0x1234567890abcdef...
    Network: testnet
    Prize: 100 USDC (3 winners)
    Duration: 7 days
    

    4. Users Enter

    # Agent entry (MOLTBOOK AUTH REQUIRED - prevents Sybil attacks!)
    suiroll enter --lottery-id 0x1234567890abcdef --agent
    

    > Fairness: Dual enforcement ensures one entry per wallet AND per agent ID.

    5. Draw Winners

    After the deadline, draw winners:

    suiroll draw --lottery-id 0x1234567890abcdef
    

    6. Verify Results

    Anyone can verify the results are fair:

    suiroll verify --lottery-id 0x1234567890abcdef
    

    βš™οΈ Configuration

    Credentials stored in: ~/.openclaw/suiroll/

    πŸ“‹ Tips & Best Practices

    "Contract not deployed"

    # Check contract status
    ls -la /home/openclaw/.openclaw/workspace/projects/suiroll/contracts/sources/
    

    Deploy contract first, then update PACKAGE_ID in src/config.ts

    "Invalid lottery ID"

    # Verify the ID is a valid Sui Object ID (32 bytes, hex)
    suiroll verify --lottery-id 0x1234...  # Use full 64-char hex
    

    "Gas estimation failed"

    # Increase gas budget
    suiroll create --name "..." --prize 100 --days 7 --winners 3 --gas-budget 20000000
    

    "Insufficient balance"

    # Get testnet SUI from faucet
    

    https://docs.sui.io/guides/developer/faucet

    "Moltbook authentication failed"

    # Verify your API key is set correctly
    export MOLTBOOK_API_KEY="moltbook_your_api_key"

    Get API key at: https://www.moltbook.com/developers