protocol overview

A trustless crossword puzzle competition with random winner selection.

create a puzzle

Deploy your own crossword puzzle. Takes ~5 minutes.

# your wallet private key (keep secret!)
export PRIVATE_KEY="0x..."

# network RPC (pick one)
export RPC="https://sepolia.base.org"           # Base testnet (recommended)
# export RPC="https://mainnet.base.org"         # Base mainnet (real money)
# export RPC="https://rpc-amoy.polygon.technology"  # Polygon testnet

# pinata JWT for IPFS uploads (free at pinata.cloud)
export PINATA_JWT="eyJ..."

# format: {"slotID": "ANSWER", ...}
# - slotID = number + A (across) or D (down)
# - answers = UPPERCASE only
# - keys MUST be sorted: 1A, 1D, 2A, 2D, 10A...

cat > solution.json << 'EOF'
{"1A":"HELLO","1D":"HI","2D":"ELF","3A":"LOW"}
EOF

# generate solution commitment (this is public)
export SOLUTION=$(cat solution.json)
export COMMITMENT=$(cast keccak "$SOLUTION")
echo "Commitment: $COMMITMENT"

# grid format: cells[row][col], isBlack=true for blocked squares

cat > puzzle.json << EOF
{
  "title": "My First Puzzle",
  "description": "A simple test crossword",
  "grid": {
    "rows": 3,
    "cols": 5,
    "cells": [
      [{"isBlack":false},{"isBlack":false},{"isBlack":false},{"isBlack":false},{"isBlack":false}],
      [{"isBlack":false},{"isBlack":true},{"isBlack":false},{"isBlack":true},{"isBlack":false}],
      [{"isBlack":false},{"isBlack":true},{"isBlack":false},{"isBlack":true},{"isBlack":false}]
    ]
  },
  "clues": {
    "1A": {"clue": "Greeting", "length": 5},
    "1D": {"clue": "Short greeting", "length": 2},
    "2D": {"clue": "Santa's helper", "length": 3},
    "3A": {"clue": "Opposite of high", "length": 3}
  },
  "solutionCommitment": "$COMMITMENT"
}
EOF

# upload puzzle metadata to IPFS via Pinata
export IPFS_HASH=$(curl -s -X POST "https://api.pinata.cloud/pinning/pinJSONToIPFS" \
  -H "Authorization: Bearer $PINATA_JWT" \
  -H "Content-Type: application/json" \
  -d @puzzle.json | jq -r '.IpfsHash')

export IPFS_URI="ipfs://$IPFS_HASH"
echo "Uploaded to: $IPFS_URI"

# verify it works
curl -s "https://gateway.pinata.cloud/ipfs/$IPFS_HASH" | jq .title

# download contract source
curl -sL "https://cryptocrossword.org/CryptoCrossword.sol" > CryptoCrossword.sol

# deploy with forge
# args: commitment, ipfsURI, entryFee(wei), creatorFee%, commitHours, revealHours
# value: your stake (you lose this if you don't reveal!)

forge create CryptoCrossword.sol:CryptoCrossword \
  --rpc-url "$RPC" \
  --private-key "$PRIVATE_KEY" \
  --value 0.001ether \
  --constructor-args "$COMMITMENT" "$IPFS_URI" 1000000000000000 10 24 24

# note the "Deployed to:" address from output
export CONTRACT="0x...paste_deployed_address_here..."

# players can solve at:
echo "https://cryptocrossword.org/solve/$CONTRACT"

# IMPORTANT: keep solution.json safe - you need it to reveal!
echo "SAVE THIS FILE: solution.json"

play a puzzle

Submit your answer to a puzzle.

export CONTRACT="0x...puzzle_contract_address..."
export RPC="https://sepolia.base.org"
export PRIVATE_KEY="0x...your_private_key..."

# check phase (must be COMMITTING)
cast call $CONTRACT "getPhase()(string)" --rpc-url $RPC

# check entry fee
cast call $CONTRACT "entryFee()(uint256)" --rpc-url $RPC

# check prize pool
cast call $CONTRACT "prizePool()(uint256)" --rpc-url $RPC

# get puzzle clues
IPFS=$(cast call $CONTRACT "puzzleDataURI()(string)" --rpc-url $RPC)
curl -s "https://gateway.pinata.cloud/ipfs/${IPFS#ipfs://}" | jq .clues

# your answer (same format as solution - sorted keys, uppercase)
export ANSWER='{"1A":"HELLO","1D":"HI","2D":"ELF","3A":"LOW"}'

# generate random salt (KEEP THIS SAFE!)
export SALT="0x$(openssl rand -hex 32)"

# compute commit hash
export HASH=$(cast keccak "$ANSWER$SALT")

# get entry fee
ENTRY_FEE=$(cast call $CONTRACT "entryFee()(uint256)" --rpc-url $RPC)

# submit answer
cast send $CONTRACT "commit(bytes32)" $HASH \
  --value $ENTRY_FEE \
  --private-key $PRIVATE_KEY \
  --rpc-url $RPC

# SAVE THESE! You need them to claim the prize
cat > my-claim.json << EOF
{
  "answer": $ANSWER,
  "salt": "$SALT",
  "hash": "$HASH",
  "contract": "$CONTRACT"
}
EOF
echo "SAVED: my-claim.json - DO NOT LOSE THIS FILE!"

reveal solution (creator only)

After commit phase ends, reveal your solution. A random player is selected as the potential winner and your creator fee is paid.

# check phase (must be REVEAL_PENDING)
cast call $CONTRACT "getPhase()(string)" --rpc-url $RPC

# reveal using your saved solution.json
export SOLUTION=$(cat solution.json)
cast send $CONTRACT "reveal(string)" "$SOLUTION" \
  --private-key $PRIVATE_KEY \
  --rpc-url $RPC

# check who was selected as potential winner
cast call $CONTRACT "getWinner()(address)" --rpc-url $RPC

# verify phase is now WINNER_CLAIM
cast call $CONTRACT "getPhase()(string)" --rpc-url $RPC

claim prize (selected winner)

If you are selected as the winner, prove your answer was correct to claim the prize.

# check if you are the selected winner
cast call $CONTRACT "getWinner()(address)" --rpc-url $RPC

# if you are selected, claim with your saved answer and salt
export ANSWER=$(jq -r '.answer' my-claim.json)
export SALT=$(jq -r '.salt' my-claim.json)

cast send $CONTRACT "claimPrize(string,bytes32)" "$ANSWER" "$SALT" \
  --private-key $PRIVATE_KEY \
  --rpc-url $RPC

# if you had wrong answer, forfeit your selection
cast send $CONTRACT "forfeitSelection()" \
  --private-key $PRIVATE_KEY \
  --rpc-url $RPC

# or anyone can trigger reselection after 1 hour timeout
cast send $CONTRACT "reselectWinner()" \
  --private-key $PRIVATE_KEY \
  --rpc-url $RPC