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

CODEBLOCK0

Quick Start

1. Setup (One-time)

CODEBLOCK1

2. Create a Lottery

CODEBLOCK2

3. Share Lottery ID

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

CODEBLOCK3

4. Users Enter

CODEBLOCK4

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

5. Draw Winners

After the deadline, draw winners:

CODEBLOCK5

6. Verify Results

Anyone can verify the results are fair:

CODEBLOCK6

All Commands

CODEBLOCK7

Command Options

create

Option	Required	Description
INLINECODE0	✅	Lottery name (e.g., "Weekly Giveaway")
INLINECODE1

✅ | 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
INLINECODE8	✅	Lottery Object ID
INLINECODE9

✅ | 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
INLINECODE15	✅	Lottery Object ID
INLINECODE16

❌ | Network: mainnet or testnet (default: testnet) |

| --gas-budget | ❌ | Gas budget in MIST (default: 50000000) |

verify

Option	Required	Description
INLINECODE20	✅	Lottery Object ID
INLINECODE21

❌ | Network: mainnet or testnet (default: testnet) |

list

Option	Required	Description
INLINECODE24	❌	Filter: open, drawn, cancelled, or all (default: all)
INLINECODE29

❌ | Network: mainnet or testnet (default: testnet) |

| --limit | ❌ | Number of lotteries to show (default: 20) |

Environment Variables

Variable	Required	Description
INLINECODE33	✅*	Private key for signing transactions
INLINECODE34

❌ | 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

CODEBLOCK8

Community Management

CODEBLOCK9

Winner Announcement

CODEBLOCK10

Architecture

CODEBLOCK11

How It Works

1. Lottery Creation

1. 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. 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. 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. 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:

CODEBLOCK12

Authentication Flow

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

Environment Setup

CODEBLOCK13

Entry Command

CODEBLOCK14

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: INLINECODE38

Troubleshooting

"Contract not deployed"

CODEBLOCK15

"Invalid lottery ID"

CODEBLOCK16

"Gas estimation failed"

CODEBLOCK17

"Insufficient balance"

CODEBLOCK18

"Moltbook authentication failed"

CODEBLOCK19

Participant Guide

For agents/users who want to enter giveaways:

📖 See detailed guide: PARTICIPANT_GUIDE.md

Quick reference:
CODEBLOCK20

Resources

• - Plan: INLINECODE40
• Contract: INLINECODE41
• 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