OutlawFlip Whitepaper

1. Abstract

OutlawFlip is a decentralized coinflip game that leverages Robinhood Chain's fast finality and low fees to deliver an instant, transparent, and provably fair betting experience. Players stake in USDG or $OUTLAW tokens and receive payouts in $OUTLAW at 1.9× multiplier, with settlement occurring in the same transaction as the bet — eliminating the delay and complexity associated with oracle-based randomness solutions.

2. Architecture

2.1 Smart Contracts

The protocol consists of a single primary contract, CoinFlipV2, which handles all game logic, token transfers, and settlement.

• CoinFlipV2 — Main game contract. Handles bet placement, randomness generation, settlement, and payout.
• OUTLAW Token — ERC-20 reward token. All payouts are denominated in OUTLAW.
• USDG Token — ERC-20 stable token. Accepted as stake, converted to OUTLAW equivalent at a fixed rate.

2.2 Frontend

The frontend is a static single-page application deployed on Vercel, using ethers.js v6 for blockchain interaction. It supports MetaMask and EIP-6963 multi-wallet detection.

2.3 No External Dependencies

Unlike V1 which relied on Chainlink VRF for randomness, V2 uses on-chain blockhash entropy. This removes the need for:

• VRF Coordinator contract
• VRF Subscription and LINK funding
• Keeper/automation bot for fulfillment
• Two-transaction settle flow (place + fulfill)

3. Game Mechanics

3.1 Bet Flow

1. Player selects token (USDG or OUTLAW), amount, and side (HEADS or TAILS).
2. Player approves the CoinFlipV2 contract to transfer the stake amount.
3. Player calls placeBetWithOutlaw() or placeBetWithUSDG().
4. Contract transfers stake from player to itself.
5. Contract generates random result using blockhash entropy.
6. If player wins, contract transfers 1.9× bet in OUTLAW to player.
7. Contract emits BetPlaced and BetSettled events.

All steps 3–7 execute in a single transaction.

3.2 Randomness

The random result is derived from:

entropy = keccak256(
  abi.encodePacked(
    blockhash(block.number - 1),
    block.timestamp,
    msg.sender,
    nextBetId,
    tx.gasprice
  )
)
result = uint8(entropy & 1)  // 0 = HEADS, 1 = TAILS

Unpredictability: The blockhash of the current block's parent is unknown to the player at transaction submission time. The inclusion of block.timestamp, msg.sender, nextBetId, and tx.gasprice adds additional entropy that makes pre-computation infeasible.

Limitations: On production networks, validators/miners could theoretically manipulate blockhash or timestamp. For high-stakes production deployment, a commit-reveal scheme or Chainlink VRF should be reconsidered. For testnet and low-stakes use, blockhash provides sufficient fairness.

3.3 Payout

4. Token Economics

4.1 OUTLAW Token

OUTLAW is the primary reward token of the OutlawFlip ecosystem. All winning bets are paid out in OUTLAW, regardless of whether the stake was in USDG or OUTLAW.

4.2 USDG Integration

USDG is accepted as an alternative stake token. The conversion rate is fixed at 1 USDG = 20,000 OUTLAW. When a player stakes USDG:

1. USDG is transferred to the contract.
2. The bet is denominated in OUTLAW equivalent using the fixed rate.
3. If won, payout is calculated on the OUTLAW equivalent and paid in OUTLAW.

4.3 Bankroll

The contract maintains a bankroll of OUTLAW tokens to cover potential payouts. The bankroll is funded by the contract owner. Each bet is checked against available bankroll before acceptance — if the bankroll cannot cover the maximum potential payout, the bet is rejected.

5. Security

5.1 Reentrancy Protection

All bet functions use OpenZeppelin's ReentrancyGuard, preventing reentrancy attacks during token transfers.

5.2 Safe Token Transfers

All ERC-20 transfers use SafeERC20, which handles non-standard return value tokens gracefully.

5.3 Solvency Check

Before each bet is accepted, the contract verifies that availableOutlaw() ≥ payout. If the bankroll is insufficient, the transaction reverts.

5.4 Access Control

Admin functions (withdraw, pause, set limits) are restricted to the contract owner via OpenZeppelin's Ownable.

5.5 Non-Custodial

The contract does not hold player funds between bets. Winnings are transferred directly to the player's wallet in the same transaction. Only the bankroll and accumulated USDG stakes are held by the contract.

6. Roadmap

7. Disclaimer

OutlawFlip is reference software. Before running a real gambling service, you must:

• Obtain appropriate gambling licenses in your jurisdiction
• Implement responsible-gambling controls (deposit limits, self-exclusion)
• Conduct professional smart contract audits
• Consider upgrading to commit-reveal or Chainlink VRF for production randomness
• Comply with all local, state, and federal regulations

This software is provided "as is" without warranty of any kind.