---
# System prepended metadata

title: Technical Specification Document - CircleJerk DApp
tags: [blockchain, spec, documentation]

---

# CropCircle - Product & Technical Specification

## Part 1: Product Requirements

### 1.1 Product Overview
CropCircle (name can be changed) is a collaborative memecoin launcher designed for in-person events. Attendees can submit memes, vote on submissions, and participate in launching a new memecoin on the CORN network.

### 1.2 Core Features

#### Event Access
- QR code scanning leads to web application
- Automatic burner wallet generation
- Initial 100 $CROP tokens provided

#### Meme Submission
- Cost: 60 $CROP tokens
- Required inputs:
  - Name (becomes token ticker)
  - Image upload (jpg, gif supported)
  - Description
- No editing/deletion allowed

#### Voting System
- Cost: 1 $ token per vote (up or down)
- Downvotes subtract from total score
- Only upvotes count for final token distribution
- Real-time vote count updates

#### Sorting & Display
- Sort by:
  - Upvote count
  - Downvote count
  - Time submitted (newest/oldest)
- Display for each meme:
  - Current vote count
  - Submission time
  - Creator's wallet address
  - Image and description

#### Token Launch
- 100k total supply of winning meme token
- 30% to winning meme creator
- 70% distributed proportionally to upvoters
- Automatic distribution at event end

### 1.3 User Experience Requirements
- Mobile-friendly web interface
- Real-time updates for votes and submissions
- Clear token balance display
- Simple, intuitive voting mechanism
- Optional features:
  - Countdown timer
  - Voting history
  - Token allocation display

## Part 2: Technical Specification

## 1. System Overview
### 1.1 Core Flow
1. Event Creation & Access
   - Automated event creation with unique QR code generation
   - QR code leads to web application
   - Automatic burner wallet generation
   - Initial 100 $CROP token distribution

2. Meme Submission
   - Cost: 60 $CROP tokens
   - Required inputs:
     - Name (becomes token ticker)
     - Image (jpg, gif supported)
     - Description

3. Voting System
   - Cost: 1 $CROP token per vote
   - Upvotes and downvotes affect total score
   - Only upvotes count for final token distribution
   - Real-time vote tracking

4. Token Launch
   - 100k total supply
   - 30% to winning meme creator
   - 70% distributed to upvoters proportionally

## 2. Technical Architecture

### 2.1 Smart Contracts
```solidity
// Core game contract
contract CROP {
    struct Meme {
        string name;         // Token ticker
        string imageHash;    // IPFS hash
        string description;
        address creator;
        uint256 upvotes;
        uint256 downvotes;
        uint256 timestamp;
        mapping(address => bool) hasVoted;
        mapping(address => int8) voteType; // 1 for up, -1 for down
    }

    struct Event {
        uint256 startTime;
        uint256 endTime;
        bytes32 qrCodeHash;
        bool active;
        mapping(uint256 => Meme) memes;
        uint256 memeCount;
    }

    // Key state variables
    mapping(bytes32 => Event) public events;
    mapping(address => uint256) public tokenBalances;
    
    // Core functions
    function createEvent() external returns (bytes32 eventId);
    function submitMeme(bytes32 eventId, string memory name, string memory imageHash, string memory description) external;
    function vote(bytes32 eventId, uint256 memeId, bool isUpvote) external;
    function endEvent(bytes32 eventId) external;
}

// Simple ERC20 for winning token
contract MemeToken is ERC20 {
    constructor(string memory name, string memory symbol) ERC20(name, symbol) {
        _mint(msg.sender, 100000 * 10**decimals());
    }
}
```

### 2.2 Frontend Architecture (scaffold-eth based)
```typescript
// Core components structure
src/
  components/
    MemeBoard/
      MemeList.tsx        // Sortable meme listing
      MemeSubmission.tsx  // Meme submission form
      VoteButton.tsx      // Voting interface
    WalletStatus/
      TokenBalance.tsx    // $CIRCLEJERK balance
      VoteHistory.tsx     // Optional voting history
    EventStatus/
      Timer.tsx          // Optional countdown
      WinnerDisplay.tsx  // Winning meme display
```

## 3. Key Functionalities

### 3.1 Event Management
- Automated creation using scaffold-eth's contract factory
- QR code generation and validation
- Event timing tracking
- Automated or manual event conclusion

### 3.2 Meme Board
- Reddit-style listing showing:
  - Current vote count (up/down)
  - Submission time
  - Creator's wallet address
  - Meme image and details
- Sorting options:
  - Upvote count
  - Downvote count
  - Submission time (ascending/descending)

### 3.3 Voting System
- Real-time balance updates
- Vote tracking
- Score calculation: upvotes - downvotes
- Optional vote history tracking

### 3.4 Token Distribution
- Automatic token deployment
- Proportional distribution based on upvotes
- Balance viewing in standard ERC20 wallet

## 4. Development Guidelines

### 4.1 Setup
```bash
# Clone and setup scaffold-eth
git clone https://github.com/scaffold-eth/scaffold-eth.git circlejerk
cd circlejerk
yarn install

# Start development
yarn chain
yarn deploy
yarn start
```

### 4.2 Key Dependencies
- scaffold-eth core components
- IPFS for image storage
- ERC20 for token contracts
- Hardhat for development and testing

### 4.3 Testing
```bash
# Run all tests
yarn test

# Deploy to testnet
yarn deploy --network cornTestnet
```

## 5. Storage Architecture

### 5.1 Smart Contract Storage
```solidity
// Core storage in CircleJerk.sol
mapping(bytes32 => Event) public events;
mapping(uint256 => Meme) public memes;
mapping(address => uint256) public userBalances;
mapping(address => mapping(uint256 => bool)) public userVotes;

// Event tracking
event MemeSubmitted(
    bytes32 indexed eventId,
    uint256 indexed memeId,
    address creator,
    string name,
    string imageHash,
    uint256 timestamp
);

event VoteCast(
    bytes32 indexed eventId,
    uint256 indexed memeId,
    address voter,
    bool isUpvote,
    uint256 timestamp
);

event EventCreated(
    bytes32 indexed eventId,
    uint256 startTime,
    uint256 endTime,
    string qrCode
);

event EventEnded(
    bytes32 indexed eventId,
    uint256 winningMemeId,
    address tokenAddress
);
```

### 5.2 IPFS Storage (via scaffold-eth)
```typescript
// Using scaffold-eth's IPFS hooks
import { useScaffoldContract, useIPFS } from "~~/hooks/scaffold-eth";

// Store meme image
const storeImage = async (file) => {
    const { uploadToIPFS } = useIPFS();
    const imageHash = await uploadToIPFS(file);
    return imageHash;
};

// Retrieve meme image
const MemeDisplay = ({ imageHash }) => {
    const { resolveIPFS } = useIPFS();
    const imageUrl = resolveIPFS(imageHash);
    return <img src={imageUrl} alt="meme" />;
};
```

### 5.3 Local Storage (Burner Wallet)
```typescript
// Using scaffold-eth's burner wallet system
import { useScaffoldConfig } from "~~/hooks/scaffold-eth";

const { burnerWallet } = useScaffoldConfig();

// Store temporary wallet data
const storeBurnerWallet = (eventId: string, walletData: any) => {
    localStorage.setItem(`burner-${eventId}`, JSON.stringify(walletData));
};

// Retrieve wallet for event
const getBurnerWallet = (eventId: string) => {
    return JSON.parse(localStorage.getItem(`burner-${eventId}`));
};
```

### 5.4 Event Monitoring
```typescript
// Using scaffold-eth's contract event hooks
import { useScaffoldEventSubscriber } from "~~/hooks/scaffold-eth";

const EventMonitor = () => {
    useScaffoldEventSubscriber({
        contractName: "CircleJerk",
        eventName: "MemeSubmitted",
        listener: (eventId, memeId, creator, name, imageHash, timestamp) => {
            // Update UI with new meme
        },
    });

    useScaffoldEventSubscriber({
        contractName: "CircleJerk",
        eventName: "VoteCast",
        listener: (eventId, memeId, voter, isUpvote, timestamp) => {
            // Update vote counts
        },
    });
};
```

## 6. Production Deployment

### 5.1 Smart Contracts
```bash
yarn deploy --network corn
```

### 5.2 Frontend
```bash
yarn build
yarn deploy
```

### 5.3 Configuration
```typescript
// scaffold.config.ts
export const scaffoldConfig = {
  targetNetwork: CORN,
  burnerWallet: true,
  ipfsGateway: "https://ipfs.io/ipfs/",
  // Additional configurations from scaffold-eth
};
```

Note: UI implementation will follow provided Figma designs. All component styling and layouts should match the design specifications exactly.

