Openclaw Fomo3d

Play Fomo3D, Slot Machine, and Prediction Market on BNB Chain (BSC). Fomo3D is a blockchain game where players buy shares using tokens — the last buyer before the countdown ends wins the grand prize. Includes a Slot Machine mini-game with VRF-powered random spins and a Prediction Market for betting on outcomes (sports, crypto prices, events). This skill provides a CLI to check game status, purchase shares, claim dividends, spin the slot machine, create/bet on prediction markets, and more. Use this skill whenever the user wants to interact with Fomo3D, buy/sell FOMO tokens, check game status, spin the slot machine, trade on FLAP Portal or PancakeSwap, create prediction markets, place bets, settle markets, or manage their BNB Chain gaming wallet.

# Fomo3D — BNB Chain Blockchain Game

Fomo3D is a decentralized game on BNB Chain (BSC) with three game modes:

1. **Fomo3D Main Game** — Buy shares with tokens. Each purchase resets a countdown timer. The last buyer when the timer hits zero wins the grand prize pool. All shareholders earn dividends from each purchase.

2. **Slot Machine** — Bet tokens for a VRF-powered random spin. Matching symbols win multiplied payouts (up to 100x). Depositors earn dividend shares from every spin.

3. **Prediction Market** — Bet on the outcome of events (Yes/No/Draw). Markets use either Oracle (Chainlink price feeds) or Optimistic (human proposal + challenge) settlement. Bettors earn dividends from other bets on the same market, and winners share the prize pool.

## Installation and Config (required)

Ensure dependencies are installed at repo root (`npm install`).

A private key is required. If the user has not configured the skill yet, **run `fomo3d setup`** from the repo root. This runs an interactive CLI that prompts for:
- BSC private key (for signing transactions)
- Network (testnet or mainnet)
- Optional custom RPC URL

Alternatively, set environment variables (no `setup` needed):
- `FOMO3D_PRIVATE_KEY` — BSC wallet private key (hex, with or without 0x prefix)
- `FOMO3D_NETWORK` — `testnet` or `mainnet` (default: testnet)
- `FOMO3D_RPC_URL` — custom RPC endpoint (optional)
- `FOMO3D_FLAP_TOKEN` — override FLAP token address for buy/sell commands (optional, for testing)

**Important:** The wallet must be an EOA (externally owned account), not a smart contract wallet. The game contracts require `msg.sender == tx.origin`.

## How to run (CLI)

Run from the **repo root** (where `package.json` lives). For machine-readable output, always append `--json`. The CLI prints JSON to stdout in `--json` mode.

```bash
fomo3d <command> [options] --json
```

On error the CLI prints `{"success":false,"error":"message"}` to stdout and exits with code 1. On success the CLI prints `{"success":true,"data":{...}}`.

## Important Concepts

### Token Amounts

All token amounts in CLI arguments and JSON output are in **wei** (18 decimals). For example:
- 1 token = `1000000000000000000` (1e18)
- 0.5 tokens = `500000000000000000` (5e17)

When displaying amounts to users, divide by 1e18 for human-readable values.

### Share Amounts

Share amounts for `purchase --shares` are **integers** (not wei). 1 share = 1 share.

### Auto-Approve

The CLI automatically checks ERC20 token allowance and approves if needed before `purchase`, `buy`, `sell`, `slot spin`, `slot deposit`, `pred bet`, `pred propose`, and `pred dispute`. No manual approval step required.

### FOMO Token Trading

The FOMO token is launched on the FLAP platform (BNB Chain bonding curve). Trading uses **BNB** as the quote token:
- **内盘 (Portal)**: Directly calls FLAP Portal's `swapExactInput` with native BNB
- **外盘 (PancakeSwap V2)**: After the token graduates to DEX, uses PancakeSwap V2 Router

The CLI auto-detects the current phase via `getTokenV6` and routes accordingly. Buy/sell commands work on both **testnet** and **mainnet**.

### VRF (Verifiable Random Function)

Slot machine spins use Binance Oracle VRF for provably fair randomness. Each `spin` requires a small BNB fee (~0.00015 BNB) sent as `msg.value`. The spin result is determined by a VRF callback (1-3 blocks later) — the CLI returns the spin request transaction, not the result. Check the result with `fomo3d slot status` or `fomo3d player` afterward.

## Commands Reference

### Setup

```bash
fomo3d setup --json
```
Interactive configuration. Prompts for private key, network, and optional RPC URL. Saves to `config.json`.

### Wallet — Check Balances

```bash
fomo3d wallet --json
```
Returns BNB balance and game token balance for the configured wallet.

**Output fields:** `address`, `bnbBalance` (wei), `tokenBalance` (wei), `tokenSymbol`, `tokenDecimals`

### Status — Game Round Info

```bash
fomo3d status --json
```
Returns current round status including countdown, prize pools, share price, and last buyers.

**Output fields:** `currentRound`, `roundStatus` (NotStarted/Active/Ended), `paused`, `countdownRemaining` (seconds), `grandPrizePool` (wei), `dividendPool` (wei), `sharePrice` (wei), `totalShares`, `lastBuyers` (address[]), `pools`

**Strategy tip:** When `countdownRemaining` is low, buying shares has higher expected value because you may win the grand prize. Each purchase resets the countdown by a fixed increment.

### Player — Player Info

```bash
fomo3d player --json
fomo3d player --address 0x1234... --json
```
Returns player's shares, earnings, and pending withdrawals. Without `--address`, uses the configured wallet.

**Output fields:** `address`, `shares`, `totalEarnings` (wei), `pendingEarnings` (wei), `pendingWithdrawal` (wei), `hasExited`, `currentRound`

**Decision guide:**
- If `pendingWithdrawal > 0`: Must run `fomo3d settle` before purchasing more shares
- If `pendingEarnings > 0` and round is active: Can `exit` to lock in earnings, or hold for more dividends
- If `hasExited == true`: Already exited this round, wait for round to end or settle

### Purchase — Buy Shares

```bash
fomo3d purchase --shares <integer> --json
```
Buy shares in the current round. The `--shares` value is an integer count (not wei). Token cost = shares × sharePrice (auto-calculated).

**Pre-checks performed automatically:**
- Game must not be paused
- No pending withdrawal (must `settle` first)
- Token approval (auto-approved if needed)

**Output fields:** `txHash`, `blockNumber`, `status`, `sharesAmount`, `tokensCost` (wei)

### Exit — Exit Game

```bash
fomo3d exit --json
```
Exit the current round and lock in your dividend earnings.

**Output fields:** `txHash`, `blockNumber`, `status`

### Settle — Claim Dividends & Prize

```bash
fomo3d settle --json
```
Settle dividends and claim any grand prize after a round ends. Must be called if `pendingEarnings > 0` or `pendingWithdrawal > 0`.

**Output fields:** `txHash`, `blockNumber`, `status`, `pendingEarnings` (wei), `pendingWithdrawal` (wei)

### End Round — End Expired Round

```bash
fomo3d end-round --json
```
End a round whose countdown has reached zero. Anyone can call this. The grand prize is distributed to the last buyer.

**Output fields:** `txHash`, `blockNumber`, `status`

### Faucet — Claim Test Tokens (testnet only)

```bash
fomo3d faucet --json
```
Claim 10000 test FOMO game tokens on BSC Testnet. Rate limited to 1 claim per address per hour.

**Output fields:** `txHash`, `amount`, `token`, `account`

### Buy — Buy FOMO with BNB

```bash
fomo3d buy --amount <bnb_amount_in_wei> --json
```
Buy FOMO tokens using BNB via the FLAP platform. Auto-detects market phase: Portal (内盘) or PancakeSwap V2 (外盘).

**Example:** Buy with 0.01 BNB:
```bash
fomo3d buy --amount 10000000000000000 --json
```

**Output fields:** `txHash`, `blockNumber`, `status`, `bnbSpent` (wei), `token`, `market`

**Note:** Buy and sell commands use `minOutputAmount=0` (no slippage protection). For large trades, consider splitting into smaller amounts.

### Sell — Sell FOMO for BNB

```bash
# 按数量卖出
fomo3d sell --amount <token_amount_in_wei> --json

# 按持仓比例卖出
fomo3d sell --percent <bps> --json
```
Sell FOMO tokens for BNB. Two modes:
- `--amount`: Sell exact token amount (in wei, 18 decimals)
- `--percent`: Sell by percentage of holdings in basis points (10000=100%, 5000=50%, 1000=10%)

Cannot use both flags simultaneously. Token allowance is auto-approved for Portal/PancakeSwap.

**Example:** Sell 50% of holdings:
```bash
fomo3d sell --percent 5000 --json
```

**Output fields:** `txHash`, `blockNumber`, `status`, `tokensSold` (wei), `market`, `method`

### Token Info — Token Status & Balances

```bash
fomo3d token-info --json
fomo3d token-info --address 0x1234... --json
```
Query FOMO token status on the FLAP platform and balances. Works without private key (shows token status only). Supports `--address` flag to check another wallet.

**Output fiel